summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml/html')
-rw-r--r--doc/src/sgml/html/acronyms.html219
-rw-r--r--doc/src/sgml/html/admin.html26
-rw-r--r--doc/src/sgml/html/adminpack.html89
-rw-r--r--doc/src/sgml/html/amcheck.html377
-rw-r--r--doc/src/sgml/html/app-clusterdb.html122
-rw-r--r--doc/src/sgml/html/app-createdb.html149
-rw-r--r--doc/src/sgml/html/app-createuser.html190
-rw-r--r--doc/src/sgml/html/app-dropdb.html111
-rw-r--r--doc/src/sgml/html/app-dropuser.html103
-rw-r--r--doc/src/sgml/html/app-ecpg.html106
-rw-r--r--doc/src/sgml/html/app-initdb.html251
-rw-r--r--doc/src/sgml/html/app-pg-ctl.html288
-rw-r--r--doc/src/sgml/html/app-pg-dumpall.html364
-rw-r--r--doc/src/sgml/html/app-pg-isready.html79
-rw-r--r--doc/src/sgml/html/app-pgamcheck.html295
-rw-r--r--doc/src/sgml/html/app-pgbasebackup.html550
-rw-r--r--doc/src/sgml/html/app-pgchecksums.html75
-rw-r--r--doc/src/sgml/html/app-pgconfig.html110
-rw-r--r--doc/src/sgml/html/app-pgcontroldata.html23
-rw-r--r--doc/src/sgml/html/app-pgdump.html824
-rw-r--r--doc/src/sgml/html/app-pgreceivewal.html249
-rw-r--r--doc/src/sgml/html/app-pgreceivexlog.html10
-rw-r--r--doc/src/sgml/html/app-pgrecvlogical.html177
-rw-r--r--doc/src/sgml/html/app-pgresetwal.html169
-rw-r--r--doc/src/sgml/html/app-pgresetxlog.html10
-rw-r--r--doc/src/sgml/html/app-pgrestore.html504
-rw-r--r--doc/src/sgml/html/app-pgrewind.html216
-rw-r--r--doc/src/sgml/html/app-pgverifybackup.html144
-rw-r--r--doc/src/sgml/html/app-postgres.html432
-rw-r--r--doc/src/sgml/html/app-postmaster.html6
-rw-r--r--doc/src/sgml/html/app-psql.html2959
-rw-r--r--doc/src/sgml/html/app-reindexdb.html164
-rw-r--r--doc/src/sgml/html/app-vacuumdb.html244
-rw-r--r--doc/src/sgml/html/appendix-obsolete.html8
-rw-r--r--doc/src/sgml/html/appendixes.html2
-rw-r--r--doc/src/sgml/html/applevel-consistency.html114
-rw-r--r--doc/src/sgml/html/archive-module-callbacks.html50
-rw-r--r--doc/src/sgml/html/archive-module-init.html24
-rw-r--r--doc/src/sgml/html/archive-modules.html24
-rw-r--r--doc/src/sgml/html/arrays.html647
-rw-r--r--doc/src/sgml/html/auth-bsd.html21
-rw-r--r--doc/src/sgml/html/auth-cert.html25
-rw-r--r--doc/src/sgml/html/auth-delay.html28
-rw-r--r--doc/src/sgml/html/auth-ident.html52
-rw-r--r--doc/src/sgml/html/auth-ldap.html190
-rw-r--r--doc/src/sgml/html/auth-methods.html59
-rw-r--r--doc/src/sgml/html/auth-pam.html31
-rw-r--r--doc/src/sgml/html/auth-password.html80
-rw-r--r--doc/src/sgml/html/auth-peer.html21
-rw-r--r--doc/src/sgml/html/auth-pg-hba-conf.html492
-rw-r--r--doc/src/sgml/html/auth-radius.html65
-rw-r--r--doc/src/sgml/html/auth-trust.html37
-rw-r--r--doc/src/sgml/html/auth-username-maps.html102
-rw-r--r--doc/src/sgml/html/auto-explain.html189
-rw-r--r--doc/src/sgml/html/backup-dump.html247
-rw-r--r--doc/src/sgml/html/backup-file.html91
-rw-r--r--doc/src/sgml/html/backup-manifest-files.html39
-rw-r--r--doc/src/sgml/html/backup-manifest-format.html16
-rw-r--r--doc/src/sgml/html/backup-manifest-toplevel.html25
-rw-r--r--doc/src/sgml/html/backup-manifest-wal-ranges.html22
-rw-r--r--doc/src/sgml/html/backup.html13
-rw-r--r--doc/src/sgml/html/basebackup-to-shell.html43
-rw-r--r--doc/src/sgml/html/basic-archive.html38
-rw-r--r--doc/src/sgml/html/bgworker.html231
-rw-r--r--doc/src/sgml/html/biblio.html23
-rw-r--r--doc/src/sgml/html/bki-commands.html111
-rw-r--r--doc/src/sgml/html/bki-example.html15
-rw-r--r--doc/src/sgml/html/bki-format.html19
-rw-r--r--doc/src/sgml/html/bki-structure.html42
-rw-r--r--doc/src/sgml/html/bki.html56
-rw-r--r--doc/src/sgml/html/bloom.html190
-rw-r--r--doc/src/sgml/html/bookindex.html62
-rw-r--r--doc/src/sgml/html/brin-builtin-opclasses.html46
-rw-r--r--doc/src/sgml/html/brin-extensibility.html168
-rw-r--r--doc/src/sgml/html/brin-intro.html99
-rw-r--r--doc/src/sgml/html/brin.html2
-rw-r--r--doc/src/sgml/html/btree-behavior.html118
-rw-r--r--doc/src/sgml/html/btree-gin.html38
-rw-r--r--doc/src/sgml/html/btree-gist.html80
-rw-r--r--doc/src/sgml/html/btree-implementation.html254
-rw-r--r--doc/src/sgml/html/btree-intro.html17
-rw-r--r--doc/src/sgml/html/btree-support-funcs.html291
-rw-r--r--doc/src/sgml/html/btree.html2
-rw-r--r--doc/src/sgml/html/bug-reporting.html248
-rw-r--r--doc/src/sgml/html/catalog-pg-aggregate.html170
-rw-r--r--doc/src/sgml/html/catalog-pg-am.html44
-rw-r--r--doc/src/sgml/html/catalog-pg-amop.html104
-rw-r--r--doc/src/sgml/html/catalog-pg-amproc.html55
-rw-r--r--doc/src/sgml/html/catalog-pg-attrdef.html37
-rw-r--r--doc/src/sgml/html/catalog-pg-attribute.html211
-rw-r--r--doc/src/sgml/html/catalog-pg-auth-members.html40
-rw-r--r--doc/src/sgml/html/catalog-pg-authid.html113
-rw-r--r--doc/src/sgml/html/catalog-pg-cast.html86
-rw-r--r--doc/src/sgml/html/catalog-pg-class.html264
-rw-r--r--doc/src/sgml/html/catalog-pg-collation.html93
-rw-r--r--doc/src/sgml/html/catalog-pg-constraint.html206
-rw-r--r--doc/src/sgml/html/catalog-pg-conversion.html56
-rw-r--r--doc/src/sgml/html/catalog-pg-database.html124
-rw-r--r--doc/src/sgml/html/catalog-pg-db-role-setting.html33
-rw-r--r--doc/src/sgml/html/catalog-pg-default-acl.html58
-rw-r--r--doc/src/sgml/html/catalog-pg-depend.html175
-rw-r--r--doc/src/sgml/html/catalog-pg-description.html43
-rw-r--r--doc/src/sgml/html/catalog-pg-enum.html49
-rw-r--r--doc/src/sgml/html/catalog-pg-event-trigger.html53
-rw-r--r--doc/src/sgml/html/catalog-pg-extension.html65
-rw-r--r--doc/src/sgml/html/catalog-pg-foreign-data-wrapper.html56
-rw-r--r--doc/src/sgml/html/catalog-pg-foreign-server.html54
-rw-r--r--doc/src/sgml/html/catalog-pg-foreign-table.html32
-rw-r--r--doc/src/sgml/html/catalog-pg-index.html163
-rw-r--r--doc/src/sgml/html/catalog-pg-inherits.html41
-rw-r--r--doc/src/sgml/html/catalog-pg-init-privs.html61
-rw-r--r--doc/src/sgml/html/catalog-pg-language.html76
-rw-r--r--doc/src/sgml/html/catalog-pg-largeobject-metadata.html28
-rw-r--r--doc/src/sgml/html/catalog-pg-largeobject.html48
-rw-r--r--doc/src/sgml/html/catalog-pg-namespace.html33
-rw-r--r--doc/src/sgml/html/catalog-pg-opclass.html75
-rw-r--r--doc/src/sgml/html/catalog-pg-operator.html101
-rw-r--r--doc/src/sgml/html/catalog-pg-opfamily.html53
-rw-r--r--doc/src/sgml/html/catalog-pg-parameter-acl.html31
-rw-r--r--doc/src/sgml/html/catalog-pg-partitioned-table.html71
-rw-r--r--doc/src/sgml/html/catalog-pg-policy.html68
-rw-r--r--doc/src/sgml/html/catalog-pg-proc.html256
-rw-r--r--doc/src/sgml/html/catalog-pg-publication-namespace.html28
-rw-r--r--doc/src/sgml/html/catalog-pg-publication-rel.html43
-rw-r--r--doc/src/sgml/html/catalog-pg-publication.html64
-rw-r--r--doc/src/sgml/html/catalog-pg-range.html61
-rw-r--r--doc/src/sgml/html/catalog-pg-replication-origin.html28
-rw-r--r--doc/src/sgml/html/catalog-pg-rewrite.html64
-rw-r--r--doc/src/sgml/html/catalog-pg-seclabel.html46
-rw-r--r--doc/src/sgml/html/catalog-pg-sequence.html54
-rw-r--r--doc/src/sgml/html/catalog-pg-shdepend.html98
-rw-r--r--doc/src/sgml/html/catalog-pg-shdescription.html38
-rw-r--r--doc/src/sgml/html/catalog-pg-shseclabel.html43
-rw-r--r--doc/src/sgml/html/catalog-pg-statistic-ext-data.html71
-rw-r--r--doc/src/sgml/html/catalog-pg-statistic-ext.html88
-rw-r--r--doc/src/sgml/html/catalog-pg-statistic.html134
-rw-r--r--doc/src/sgml/html/catalog-pg-subscription-rel.html45
-rw-r--r--doc/src/sgml/html/catalog-pg-subscription.html103
-rw-r--r--doc/src/sgml/html/catalog-pg-tablespace.html42
-rw-r--r--doc/src/sgml/html/catalog-pg-transform.html44
-rw-r--r--doc/src/sgml/html/catalog-pg-trigger.html148
-rw-r--r--doc/src/sgml/html/catalog-pg-ts-config-map.html38
-rw-r--r--doc/src/sgml/html/catalog-pg-ts-config.html45
-rw-r--r--doc/src/sgml/html/catalog-pg-ts-dict.html52
-rw-r--r--doc/src/sgml/html/catalog-pg-ts-parser.html62
-rw-r--r--doc/src/sgml/html/catalog-pg-ts-template.html44
-rw-r--r--doc/src/sgml/html/catalog-pg-type.html310
-rw-r--r--doc/src/sgml/html/catalog-pg-user-mapping.html35
-rw-r--r--doc/src/sgml/html/catalogs-overview.html10
-rw-r--r--doc/src/sgml/html/catalogs.html17
-rw-r--r--doc/src/sgml/html/charset.html20
-rw-r--r--doc/src/sgml/html/checksums.html25
-rw-r--r--doc/src/sgml/html/citext.html166
-rw-r--r--doc/src/sgml/html/client-authentication-problems.html40
-rw-r--r--doc/src/sgml/html/client-authentication.html37
-rw-r--r--doc/src/sgml/html/client-interfaces.html12
-rw-r--r--doc/src/sgml/html/collation.html417
-rw-r--r--doc/src/sgml/html/color-when.html15
-rw-r--r--doc/src/sgml/html/color-which.html26
-rw-r--r--doc/src/sgml/html/color.html5
-rw-r--r--doc/src/sgml/html/config-setting.html336
-rw-r--r--doc/src/sgml/html/connect-estab.html36
-rw-r--r--doc/src/sgml/html/continuous-archiving.html757
-rw-r--r--doc/src/sgml/html/contrib-dblink-build-sql-delete.html42
-rw-r--r--doc/src/sgml/html/contrib-dblink-build-sql-insert.html52
-rw-r--r--doc/src/sgml/html/contrib-dblink-build-sql-update.html54
-rw-r--r--doc/src/sgml/html/contrib-dblink-cancel-query.html19
-rw-r--r--doc/src/sgml/html/contrib-dblink-close.html42
-rw-r--r--doc/src/sgml/html/contrib-dblink-connect-u.html29
-rw-r--r--doc/src/sgml/html/contrib-dblink-connect.html105
-rw-r--r--doc/src/sgml/html/contrib-dblink-disconnect.html26
-rw-r--r--doc/src/sgml/html/contrib-dblink-error-message.html22
-rw-r--r--doc/src/sgml/html/contrib-dblink-exec.html65
-rw-r--r--doc/src/sgml/html/contrib-dblink-fetch.html77
-rw-r--r--doc/src/sgml/html/contrib-dblink-function.html143
-rw-r--r--doc/src/sgml/html/contrib-dblink-get-connections.html9
-rw-r--r--doc/src/sgml/html/contrib-dblink-get-notify.html33
-rw-r--r--doc/src/sgml/html/contrib-dblink-get-pkey.html43
-rw-r--r--doc/src/sgml/html/contrib-dblink-get-result.html98
-rw-r--r--doc/src/sgml/html/contrib-dblink-is-busy.html14
-rw-r--r--doc/src/sgml/html/contrib-dblink-open.html48
-rw-r--r--doc/src/sgml/html/contrib-dblink-send-query.html24
-rw-r--r--doc/src/sgml/html/contrib-prog-client.html9
-rw-r--r--doc/src/sgml/html/contrib-prog-server.html7
-rw-r--r--doc/src/sgml/html/contrib-prog.html15
-rw-r--r--doc/src/sgml/html/contrib-spi.html81
-rw-r--r--doc/src/sgml/html/contrib.html87
-rw-r--r--doc/src/sgml/html/creating-cluster.html203
-rw-r--r--doc/src/sgml/html/cube.html391
-rw-r--r--doc/src/sgml/html/custom-rmgr.html81
-rw-r--r--doc/src/sgml/html/custom-scan-execution.html139
-rw-r--r--doc/src/sgml/html/custom-scan-path.html101
-rw-r--r--doc/src/sgml/html/custom-scan-plan.html67
-rw-r--r--doc/src/sgml/html/custom-scan.html21
-rw-r--r--doc/src/sgml/html/database-roles.html70
-rw-r--r--doc/src/sgml/html/datatype-binary.html132
-rw-r--r--doc/src/sgml/html/datatype-bit.html49
-rw-r--r--doc/src/sgml/html/datatype-boolean.html58
-rw-r--r--doc/src/sgml/html/datatype-character.html142
-rw-r--r--doc/src/sgml/html/datatype-datetime.html550
-rw-r--r--doc/src/sgml/html/datatype-enum.html115
-rw-r--r--doc/src/sgml/html/datatype-geometric.html152
-rw-r--r--doc/src/sgml/html/datatype-json.html730
-rw-r--r--doc/src/sgml/html/datatype-money.html44
-rw-r--r--doc/src/sgml/html/datatype-net-types.html132
-rw-r--r--doc/src/sgml/html/datatype-numeric.html370
-rw-r--r--doc/src/sgml/html/datatype-oid.html166
-rw-r--r--doc/src/sgml/html/datatype-pg-lsn.html22
-rw-r--r--doc/src/sgml/html/datatype-pseudo.html59
-rw-r--r--doc/src/sgml/html/datatype-textsearch.html196
-rw-r--r--doc/src/sgml/html/datatype-uuid.html39
-rw-r--r--doc/src/sgml/html/datatype-xml.html151
-rw-r--r--doc/src/sgml/html/datatype.html36
-rw-r--r--doc/src/sgml/html/datetime-appendix.html15
-rw-r--r--doc/src/sgml/html/datetime-config-files.html98
-rw-r--r--doc/src/sgml/html/datetime-input-rules.html74
-rw-r--r--doc/src/sgml/html/datetime-invalid-input.html62
-rw-r--r--doc/src/sgml/html/datetime-julian-dates.html48
-rw-r--r--doc/src/sgml/html/datetime-keywords.html11
-rw-r--r--doc/src/sgml/html/datetime-posix-timezone-specs.html135
-rw-r--r--doc/src/sgml/html/datetime-units-history.html87
-rw-r--r--doc/src/sgml/html/dblink.html18
-rw-r--r--doc/src/sgml/html/ddl-alter.html156
-rw-r--r--doc/src/sgml/html/ddl-basics.html101
-rw-r--r--doc/src/sgml/html/ddl-constraints.html607
-rw-r--r--doc/src/sgml/html/ddl-default.html49
-rw-r--r--doc/src/sgml/html/ddl-depend.html99
-rw-r--r--doc/src/sgml/html/ddl-foreign-data.html41
-rw-r--r--doc/src/sgml/html/ddl-generated-columns.html85
-rw-r--r--doc/src/sgml/html/ddl-inherit.html289
-rw-r--r--doc/src/sgml/html/ddl-others.html20
-rw-r--r--doc/src/sgml/html/ddl-partitioning.html992
-rw-r--r--doc/src/sgml/html/ddl-priv.html307
-rw-r--r--doc/src/sgml/html/ddl-rowsecurity.html382
-rw-r--r--doc/src/sgml/html/ddl-schemas.html329
-rw-r--r--doc/src/sgml/html/ddl-system-columns.html58
-rw-r--r--doc/src/sgml/html/ddl.html13
-rw-r--r--doc/src/sgml/html/default-roles.html9
-rw-r--r--doc/src/sgml/html/dict-int.html62
-rw-r--r--doc/src/sgml/html/dict-xsyn.html97
-rw-r--r--doc/src/sgml/html/different-replication-solutions.html137
-rw-r--r--doc/src/sgml/html/disk-full.html20
-rw-r--r--doc/src/sgml/html/disk-usage.html83
-rw-r--r--doc/src/sgml/html/diskusage.html5
-rw-r--r--doc/src/sgml/html/dml-delete.html28
-rw-r--r--doc/src/sgml/html/dml-insert.html81
-rw-r--r--doc/src/sgml/html/dml-returning.html53
-rw-r--r--doc/src/sgml/html/dml-update.html61
-rw-r--r--doc/src/sgml/html/dml.html9
-rw-r--r--doc/src/sgml/html/docguide-authoring.html23
-rw-r--r--doc/src/sgml/html/docguide-build.html91
-rw-r--r--doc/src/sgml/html/docguide-docbook.html23
-rw-r--r--doc/src/sgml/html/docguide-style.html89
-rw-r--r--doc/src/sgml/html/docguide-toolsets.html115
-rw-r--r--doc/src/sgml/html/docguide.html24
-rw-r--r--doc/src/sgml/html/domains.html34
-rw-r--r--doc/src/sgml/html/dynamic-trace.html301
-rw-r--r--doc/src/sgml/html/earthdistance.html158
-rw-r--r--doc/src/sgml/html/ecpg-commands.html163
-rw-r--r--doc/src/sgml/html/ecpg-concept.html52
-rw-r--r--doc/src/sgml/html/ecpg-connect.html247
-rw-r--r--doc/src/sgml/html/ecpg-cpp.html228
-rw-r--r--doc/src/sgml/html/ecpg-descriptors.html710
-rw-r--r--doc/src/sgml/html/ecpg-develop.html124
-rw-r--r--doc/src/sgml/html/ecpg-dynamic.html103
-rw-r--r--doc/src/sgml/html/ecpg-errors.html441
-rw-r--r--doc/src/sgml/html/ecpg-informix-compat.html892
-rw-r--r--doc/src/sgml/html/ecpg-library.html46
-rw-r--r--doc/src/sgml/html/ecpg-lo.html100
-rw-r--r--doc/src/sgml/html/ecpg-oracle-compat.html19
-rw-r--r--doc/src/sgml/html/ecpg-pgtypes.html765
-rw-r--r--doc/src/sgml/html/ecpg-preproc.html129
-rw-r--r--doc/src/sgml/html/ecpg-process.html68
-rw-r--r--doc/src/sgml/html/ecpg-sql-allocate-descriptor.html19
-rw-r--r--doc/src/sgml/html/ecpg-sql-commands.html7
-rw-r--r--doc/src/sgml/html/ecpg-sql-connect.html109
-rw-r--r--doc/src/sgml/html/ecpg-sql-deallocate-descriptor.html16
-rw-r--r--doc/src/sgml/html/ecpg-sql-declare-statement.html33
-rw-r--r--doc/src/sgml/html/ecpg-sql-declare.html43
-rw-r--r--doc/src/sgml/html/ecpg-sql-describe.html26
-rw-r--r--doc/src/sgml/html/ecpg-sql-disconnect.html35
-rw-r--r--doc/src/sgml/html/ecpg-sql-execute-immediate.html37
-rw-r--r--doc/src/sgml/html/ecpg-sql-get-descriptor.html104
-rw-r--r--doc/src/sgml/html/ecpg-sql-open.html31
-rw-r--r--doc/src/sgml/html/ecpg-sql-prepare.html42
-rw-r--r--doc/src/sgml/html/ecpg-sql-set-autocommit.html13
-rw-r--r--doc/src/sgml/html/ecpg-sql-set-connection.html18
-rw-r--r--doc/src/sgml/html/ecpg-sql-set-descriptor.html38
-rw-r--r--doc/src/sgml/html/ecpg-sql-type.html88
-rw-r--r--doc/src/sgml/html/ecpg-sql-var.html19
-rw-r--r--doc/src/sgml/html/ecpg-sql-whenever.html57
-rw-r--r--doc/src/sgml/html/ecpg-variables.html881
-rw-r--r--doc/src/sgml/html/ecpg.html13
-rw-r--r--doc/src/sgml/html/encryption-options.html84
-rw-r--r--doc/src/sgml/html/errcodes-appendix.html45
-rw-r--r--doc/src/sgml/html/error-message-reporting.html250
-rw-r--r--doc/src/sgml/html/error-style-guide.html250
-rw-r--r--doc/src/sgml/html/event-log-registration.html28
-rw-r--r--doc/src/sgml/html/event-trigger-definition.html78
-rw-r--r--doc/src/sgml/html/event-trigger-example.html78
-rw-r--r--doc/src/sgml/html/event-trigger-interface.html68
-rw-r--r--doc/src/sgml/html/event-trigger-matrix.html5
-rw-r--r--doc/src/sgml/html/event-trigger-table-rewrite-example.html48
-rw-r--r--doc/src/sgml/html/event-triggers.html12
-rw-r--r--doc/src/sgml/html/executor.html78
-rw-r--r--doc/src/sgml/html/explicit-joins.html144
-rw-r--r--doc/src/sgml/html/explicit-locking.html396
-rw-r--r--doc/src/sgml/html/extend-extensions.html626
-rw-r--r--doc/src/sgml/html/extend-how.html33
-rw-r--r--doc/src/sgml/html/extend-pgxs.html230
-rw-r--r--doc/src/sgml/html/extend-type-system.html222
-rw-r--r--doc/src/sgml/html/extend.html20
-rw-r--r--doc/src/sgml/html/external-admin-tools.html7
-rw-r--r--doc/src/sgml/html/external-extensions.html14
-rw-r--r--doc/src/sgml/html/external-interfaces.html24
-rw-r--r--doc/src/sgml/html/external-pl.html18
-rw-r--r--doc/src/sgml/html/external-projects.html7
-rw-r--r--doc/src/sgml/html/fdw-callbacks.html1257
-rw-r--r--doc/src/sgml/html/fdw-functions.html36
-rw-r--r--doc/src/sgml/html/fdw-helpers.html114
-rw-r--r--doc/src/sgml/html/fdw-planning.html191
-rw-r--r--doc/src/sgml/html/fdw-row-locking.html93
-rw-r--r--doc/src/sgml/html/fdwhandler.html21
-rw-r--r--doc/src/sgml/html/features-sql-standard.html4
-rw-r--r--doc/src/sgml/html/features.html73
-rw-r--r--doc/src/sgml/html/file-fdw.html145
-rw-r--r--doc/src/sgml/html/functions-admin.html1648
-rw-r--r--doc/src/sgml/html/functions-aggregate.html729
-rw-r--r--doc/src/sgml/html/functions-array.html385
-rw-r--r--doc/src/sgml/html/functions-binarystring.html510
-rw-r--r--doc/src/sgml/html/functions-bitstring.html235
-rw-r--r--doc/src/sgml/html/functions-comparison.html400
-rw-r--r--doc/src/sgml/html/functions-comparisons.html215
-rw-r--r--doc/src/sgml/html/functions-conditional.html187
-rw-r--r--doc/src/sgml/html/functions-datetime.html1316
-rw-r--r--doc/src/sgml/html/functions-enum.html84
-rw-r--r--doc/src/sgml/html/functions-event-triggers.html133
-rw-r--r--doc/src/sgml/html/functions-formatting.html410
-rw-r--r--doc/src/sgml/html/functions-geometry.html886
-rw-r--r--doc/src/sgml/html/functions-info.html1774
-rw-r--r--doc/src/sgml/html/functions-json.html1781
-rw-r--r--doc/src/sgml/html/functions-logical.html36
-rw-r--r--doc/src/sgml/html/functions-matching.html1415
-rw-r--r--doc/src/sgml/html/functions-math.html1001
-rw-r--r--doc/src/sgml/html/functions-net.html397
-rw-r--r--doc/src/sgml/html/functions-range.html707
-rw-r--r--doc/src/sgml/html/functions-sequence.html139
-rw-r--r--doc/src/sgml/html/functions-srf.html218
-rw-r--r--doc/src/sgml/html/functions-statistics.html24
-rw-r--r--doc/src/sgml/html/functions-string.html1208
-rw-r--r--doc/src/sgml/html/functions-subquery.html213
-rw-r--r--doc/src/sgml/html/functions-textsearch.html763
-rw-r--r--doc/src/sgml/html/functions-trigger.html93
-rw-r--r--doc/src/sgml/html/functions-uuid.html16
-rw-r--r--doc/src/sgml/html/functions-window.html182
-rw-r--r--doc/src/sgml/html/functions-xml.html912
-rw-r--r--doc/src/sgml/html/functions.html33
-rw-r--r--doc/src/sgml/html/fuzzystrmatch.html138
-rw-r--r--doc/src/sgml/html/generic-wal.html102
-rw-r--r--doc/src/sgml/html/genetic-algorithm.svg140
-rw-r--r--doc/src/sgml/html/geqo-biblio.html18
-rw-r--r--doc/src/sgml/html/geqo-intro.html36
-rw-r--r--doc/src/sgml/html/geqo-intro2.html27
-rw-r--r--doc/src/sgml/html/geqo-pg-intro.html107
-rw-r--r--doc/src/sgml/html/geqo.html8
-rw-r--r--doc/src/sgml/html/gin-builtin-opclasses.html13
-rw-r--r--doc/src/sgml/html/gin-examples.html10
-rw-r--r--doc/src/sgml/html/gin-extensibility.html237
-rw-r--r--doc/src/sgml/html/gin-implementation.html64
-rw-r--r--doc/src/sgml/html/gin-intro.html40
-rw-r--r--doc/src/sgml/html/gin-limit.html10
-rw-r--r--doc/src/sgml/html/gin-tips.html58
-rw-r--r--doc/src/sgml/html/gin.html2
-rw-r--r--doc/src/sgml/html/gin.svg317
-rw-r--r--doc/src/sgml/html/gist-builtin-opclasses.html16
-rw-r--r--doc/src/sgml/html/gist-examples.html13
-rw-r--r--doc/src/sgml/html/gist-extensibility.html813
-rw-r--r--doc/src/sgml/html/gist-implementation.html38
-rw-r--r--doc/src/sgml/html/gist-intro.html23
-rw-r--r--doc/src/sgml/html/gist.html2
-rw-r--r--doc/src/sgml/html/git.html42
-rw-r--r--doc/src/sgml/html/glossary.html1061
-rw-r--r--doc/src/sgml/html/gssapi-auth.html118
-rw-r--r--doc/src/sgml/html/gssapi-enc.html31
-rw-r--r--doc/src/sgml/html/hash-implementation.html36
-rw-r--r--doc/src/sgml/html/hash-index.html2
-rw-r--r--doc/src/sgml/html/hash-intro.html77
-rw-r--r--doc/src/sgml/html/high-availability.html57
-rw-r--r--doc/src/sgml/html/history.html140
-rw-r--r--doc/src/sgml/html/hot-standby.html575
-rw-r--r--doc/src/sgml/html/how-parallel-query-works.html71
-rw-r--r--doc/src/sgml/html/hstore.html699
-rw-r--r--doc/src/sgml/html/index-api.html180
-rw-r--r--doc/src/sgml/html/index-cost-estimation.html142
-rw-r--r--doc/src/sgml/html/index-functions.html487
-rw-r--r--doc/src/sgml/html/index-locking.html91
-rw-r--r--doc/src/sgml/html/index-scanning.html123
-rw-r--r--doc/src/sgml/html/index-unique-checks.html109
-rw-r--r--doc/src/sgml/html/index.html2
-rw-r--r--doc/src/sgml/html/indexam.html35
-rw-r--r--doc/src/sgml/html/indexes-bitmap-scans.html61
-rw-r--r--doc/src/sgml/html/indexes-collations.html31
-rw-r--r--doc/src/sgml/html/indexes-examine.html82
-rw-r--r--doc/src/sgml/html/indexes-expressional.html49
-rw-r--r--doc/src/sgml/html/indexes-index-only-scans.html209
-rw-r--r--doc/src/sgml/html/indexes-intro.html77
-rw-r--r--doc/src/sgml/html/indexes-multicolumn.html82
-rw-r--r--doc/src/sgml/html/indexes-opclass.html107
-rw-r--r--doc/src/sgml/html/indexes-ordering.html64
-rw-r--r--doc/src/sgml/html/indexes-partial.html212
-rw-r--r--doc/src/sgml/html/indexes-types.html162
-rw-r--r--doc/src/sgml/html/indexes-unique.html26
-rw-r--r--doc/src/sgml/html/indexes.html8
-rw-r--r--doc/src/sgml/html/information-schema.html31
-rw-r--r--doc/src/sgml/html/infoschema-administrable-role-authorizations.html28
-rw-r--r--doc/src/sgml/html/infoschema-applicable-roles.html33
-rw-r--r--doc/src/sgml/html/infoschema-attributes.html226
-rw-r--r--doc/src/sgml/html/infoschema-character-sets.html86
-rw-r--r--doc/src/sgml/html/infoschema-check-constraint-routine-usage.html42
-rw-r--r--doc/src/sgml/html/infoschema-check-constraints.html32
-rw-r--r--doc/src/sgml/html/infoschema-collation-character-set-applicab.html44
-rw-r--r--doc/src/sgml/html/infoschema-collations.html31
-rw-r--r--doc/src/sgml/html/infoschema-column-column-usage.html36
-rw-r--r--doc/src/sgml/html/infoschema-column-domain-usage.html46
-rw-r--r--doc/src/sgml/html/infoschema-column-options.html42
-rw-r--r--doc/src/sgml/html/infoschema-column-privileges.html60
-rw-r--r--doc/src/sgml/html/infoschema-column-udt-usage.html52
-rw-r--r--doc/src/sgml/html/infoschema-columns.html337
-rw-r--r--doc/src/sgml/html/infoschema-constraint-column-usage.html55
-rw-r--r--doc/src/sgml/html/infoschema-constraint-table-usage.html50
-rw-r--r--doc/src/sgml/html/infoschema-data-type-privileges.html52
-rw-r--r--doc/src/sgml/html/infoschema-datatypes.html33
-rw-r--r--doc/src/sgml/html/infoschema-domain-constraints.html52
-rw-r--r--doc/src/sgml/html/infoschema-domain-udt-usage.html43
-rw-r--r--doc/src/sgml/html/infoschema-domains.html197
-rw-r--r--doc/src/sgml/html/infoschema-element-types.html194
-rw-r--r--doc/src/sgml/html/infoschema-enabled-roles.html28
-rw-r--r--doc/src/sgml/html/infoschema-foreign-data-wrapper-options.html33
-rw-r--r--doc/src/sgml/html/infoschema-foreign-data-wrappers.html38
-rw-r--r--doc/src/sgml/html/infoschema-foreign-server-options.html32
-rw-r--r--doc/src/sgml/html/infoschema-foreign-servers.html48
-rw-r--r--doc/src/sgml/html/infoschema-foreign-table-options.html37
-rw-r--r--doc/src/sgml/html/infoschema-foreign-tables.html37
-rw-r--r--doc/src/sgml/html/infoschema-information-schema-catalog-name.html16
-rw-r--r--doc/src/sgml/html/infoschema-key-column-usage.html65
-rw-r--r--doc/src/sgml/html/infoschema-parameters.html188
-rw-r--r--doc/src/sgml/html/infoschema-referential-constraints.html70
-rw-r--r--doc/src/sgml/html/infoschema-role-column-grants.html58
-rw-r--r--doc/src/sgml/html/infoschema-role-routine-grants.html66
-rw-r--r--doc/src/sgml/html/infoschema-role-table-grants.html64
-rw-r--r--doc/src/sgml/html/infoschema-role-udt-grants.html53
-rw-r--r--doc/src/sgml/html/infoschema-role-usage-grants.html57
-rw-r--r--doc/src/sgml/html/infoschema-routine-column-usage.html62
-rw-r--r--doc/src/sgml/html/infoschema-routine-privileges.html62
-rw-r--r--doc/src/sgml/html/infoschema-routine-routine-usage.html55
-rw-r--r--doc/src/sgml/html/infoschema-routine-sequence-usage.html59
-rw-r--r--doc/src/sgml/html/infoschema-routine-table-usage.html57
-rw-r--r--doc/src/sgml/html/infoschema-routines.html464
-rw-r--r--doc/src/sgml/html/infoschema-schema.html16
-rw-r--r--doc/src/sgml/html/infoschema-schemata.html46
-rw-r--r--doc/src/sgml/html/infoschema-sequences.html87
-rw-r--r--doc/src/sgml/html/infoschema-sql-features.html50
-rw-r--r--doc/src/sgml/html/infoschema-sql-implementation-info.html45
-rw-r--r--doc/src/sgml/html/infoschema-sql-parts.html39
-rw-r--r--doc/src/sgml/html/infoschema-sql-sizing.html38
-rw-r--r--doc/src/sgml/html/infoschema-table-constraints.html73
-rw-r--r--doc/src/sgml/html/infoschema-table-privileges.html60
-rw-r--r--doc/src/sgml/html/infoschema-tables.html82
-rw-r--r--doc/src/sgml/html/infoschema-transforms.html55
-rw-r--r--doc/src/sgml/html/infoschema-triggered-update-columns.html51
-rw-r--r--doc/src/sgml/html/infoschema-triggers.html150
-rw-r--r--doc/src/sgml/html/infoschema-udt-privileges.html50
-rw-r--r--doc/src/sgml/html/infoschema-usage-privileges.html66
-rw-r--r--doc/src/sgml/html/infoschema-user-defined-types.html168
-rw-r--r--doc/src/sgml/html/infoschema-user-mapping-options.html45
-rw-r--r--doc/src/sgml/html/infoschema-user-mappings.html30
-rw-r--r--doc/src/sgml/html/infoschema-view-column-usage.html54
-rw-r--r--doc/src/sgml/html/infoschema-view-routine-usage.html43
-rw-r--r--doc/src/sgml/html/infoschema-view-table-usage.html47
-rw-r--r--doc/src/sgml/html/infoschema-views.html70
-rw-r--r--doc/src/sgml/html/install-binaries.html13
-rw-r--r--doc/src/sgml/html/install-getsource.html20
-rw-r--r--doc/src/sgml/html/install-post.html103
-rw-r--r--doc/src/sgml/html/install-procedure.html818
-rw-r--r--doc/src/sgml/html/install-requirements.html197
-rw-r--r--doc/src/sgml/html/install-short.html19
-rw-r--r--doc/src/sgml/html/install-windows-full.html341
-rw-r--r--doc/src/sgml/html/install-windows.html44
-rw-r--r--doc/src/sgml/html/installation-platform-notes.html314
-rw-r--r--doc/src/sgml/html/installation.html13
-rw-r--r--doc/src/sgml/html/intagg.html89
-rw-r--r--doc/src/sgml/html/intarray.html321
-rw-r--r--doc/src/sgml/html/internals.html5
-rw-r--r--doc/src/sgml/html/intro-whatis.html26
-rw-r--r--doc/src/sgml/html/isn.html209
-rw-r--r--doc/src/sgml/html/jit-configuration.html17
-rw-r--r--doc/src/sgml/html/jit-decision.html71
-rw-r--r--doc/src/sgml/html/jit-extensibility.html51
-rw-r--r--doc/src/sgml/html/jit-reason.html47
-rw-r--r--doc/src/sgml/html/jit.html5
-rw-r--r--doc/src/sgml/html/kernel-resources.html553
-rw-r--r--doc/src/sgml/html/largeobjects.html17
-rw-r--r--doc/src/sgml/html/legalnotice.html27
-rw-r--r--doc/src/sgml/html/libpq-async.html337
-rw-r--r--doc/src/sgml/html/libpq-build.html106
-rw-r--r--doc/src/sgml/html/libpq-cancel.html74
-rw-r--r--doc/src/sgml/html/libpq-connect.html1134
-rw-r--r--doc/src/sgml/html/libpq-control.html139
-rw-r--r--doc/src/sgml/html/libpq-copy.html300
-rw-r--r--doc/src/sgml/html/libpq-envars.html156
-rw-r--r--doc/src/sgml/html/libpq-events.html425
-rw-r--r--doc/src/sgml/html/libpq-example.html529
-rw-r--r--doc/src/sgml/html/libpq-exec.html1050
-rw-r--r--doc/src/sgml/html/libpq-fastpath.html85
-rw-r--r--doc/src/sgml/html/libpq-ldap.html63
-rw-r--r--doc/src/sgml/html/libpq-misc.html233
-rw-r--r--doc/src/sgml/html/libpq-notice-processing.html86
-rw-r--r--doc/src/sgml/html/libpq-notify.html73
-rw-r--r--doc/src/sgml/html/libpq-pgpass.html45
-rw-r--r--doc/src/sgml/html/libpq-pgservice.html52
-rw-r--r--doc/src/sgml/html/libpq-pipeline-mode.html327
-rw-r--r--doc/src/sgml/html/libpq-single-row-mode.html64
-rw-r--r--doc/src/sgml/html/libpq-ssl.html273
-rw-r--r--doc/src/sgml/html/libpq-status.html427
-rw-r--r--doc/src/sgml/html/libpq-threading.html47
-rw-r--r--doc/src/sgml/html/libpq.html29
-rw-r--r--doc/src/sgml/html/limits.html27
-rw-r--r--doc/src/sgml/html/lo-examplesect.html281
-rw-r--r--doc/src/sgml/html/lo-funcs.html117
-rw-r--r--doc/src/sgml/html/lo-implementation.html30
-rw-r--r--doc/src/sgml/html/lo-interfaces.html322
-rw-r--r--doc/src/sgml/html/lo-intro.html18
-rw-r--r--doc/src/sgml/html/lo.html76
-rw-r--r--doc/src/sgml/html/locale.html246
-rw-r--r--doc/src/sgml/html/locking-indexes.html42
-rw-r--r--doc/src/sgml/html/logfile-maintenance.html112
-rw-r--r--doc/src/sgml/html/logical-replication-architecture.html54
-rw-r--r--doc/src/sgml/html/logical-replication-col-lists.html144
-rw-r--r--doc/src/sgml/html/logical-replication-config.html23
-rw-r--r--doc/src/sgml/html/logical-replication-conflicts.html56
-rw-r--r--doc/src/sgml/html/logical-replication-monitoring.html20
-rw-r--r--doc/src/sgml/html/logical-replication-publication.html53
-rw-r--r--doc/src/sgml/html/logical-replication-quick-setup.html31
-rw-r--r--doc/src/sgml/html/logical-replication-restrictions.html57
-rw-r--r--doc/src/sgml/html/logical-replication-row-filter.html440
-rw-r--r--doc/src/sgml/html/logical-replication-security.html48
-rw-r--r--doc/src/sgml/html/logical-replication-subscription.html278
-rw-r--r--doc/src/sgml/html/logical-replication.html55
-rw-r--r--doc/src/sgml/html/logicaldecoding-catalogs.html13
-rw-r--r--doc/src/sgml/html/logicaldecoding-example.html184
-rw-r--r--doc/src/sgml/html/logicaldecoding-explanation.html76
-rw-r--r--doc/src/sgml/html/logicaldecoding-output-plugin.html471
-rw-r--r--doc/src/sgml/html/logicaldecoding-sql.html10
-rw-r--r--doc/src/sgml/html/logicaldecoding-streaming.html86
-rw-r--r--doc/src/sgml/html/logicaldecoding-synchronous.html50
-rw-r--r--doc/src/sgml/html/logicaldecoding-two-phase-commits.html55
-rw-r--r--doc/src/sgml/html/logicaldecoding-walsender.html13
-rw-r--r--doc/src/sgml/html/logicaldecoding-writer.html9
-rw-r--r--doc/src/sgml/html/logicaldecoding.html27
-rw-r--r--doc/src/sgml/html/ltree.html582
-rw-r--r--doc/src/sgml/html/maintenance.html37
-rw-r--r--doc/src/sgml/html/manage-ag-config.html25
-rw-r--r--doc/src/sgml/html/manage-ag-createdb.html79
-rw-r--r--doc/src/sgml/html/manage-ag-dropdb.html28
-rw-r--r--doc/src/sgml/html/manage-ag-overview.html59
-rw-r--r--doc/src/sgml/html/manage-ag-tablespaces.html132
-rw-r--r--doc/src/sgml/html/manage-ag-templatedbs.html92
-rw-r--r--doc/src/sgml/html/managing-databases.html9
-rw-r--r--doc/src/sgml/html/monitoring-locks.html28
-rw-r--r--doc/src/sgml/html/monitoring-ps.html77
-rw-r--r--doc/src/sgml/html/monitoring-stats.html2470
-rw-r--r--doc/src/sgml/html/monitoring.html18
-rw-r--r--doc/src/sgml/html/multibyte.html351
-rw-r--r--doc/src/sgml/html/multivariate-statistics-examples.html210
-rw-r--r--doc/src/sgml/html/mvcc-caveats.html34
-rw-r--r--doc/src/sgml/html/mvcc-intro.html37
-rw-r--r--doc/src/sgml/html/mvcc-serialization-failure-handling.html47
-rw-r--r--doc/src/sgml/html/mvcc.html10
-rw-r--r--doc/src/sgml/html/nls-programmer.html154
-rw-r--r--doc/src/sgml/html/nls-translator.html218
-rw-r--r--doc/src/sgml/html/nls.html2
-rw-r--r--doc/src/sgml/html/non-durability.html39
-rw-r--r--doc/src/sgml/html/notation.html22
-rw-r--r--doc/src/sgml/html/oid2name.html192
-rw-r--r--doc/src/sgml/html/oldsnapshot.html10
-rw-r--r--doc/src/sgml/html/overview.html15
-rw-r--r--doc/src/sgml/html/pageinspect.html567
-rw-r--r--doc/src/sgml/html/pagelayout.svg35
-rw-r--r--doc/src/sgml/html/parallel-plans.html155
-rw-r--r--doc/src/sgml/html/parallel-query.html15
-rw-r--r--doc/src/sgml/html/parallel-safety.html83
-rw-r--r--doc/src/sgml/html/parser-stage.html91
-rw-r--r--doc/src/sgml/html/passwordcheck.html42
-rw-r--r--doc/src/sgml/html/performance-tips.html7
-rw-r--r--doc/src/sgml/html/perm-functions.html22
-rw-r--r--doc/src/sgml/html/pgarchivecleanup.html94
-rw-r--r--doc/src/sgml/html/pgbench.html1721
-rw-r--r--doc/src/sgml/html/pgbuffercache.html118
-rw-r--r--doc/src/sgml/html/pgcrypto.html544
-rw-r--r--doc/src/sgml/html/pgfreespacemap.html68
-rw-r--r--doc/src/sgml/html/pgprewarm.html82
-rw-r--r--doc/src/sgml/html/pgrowlocks.html51
-rw-r--r--doc/src/sgml/html/pgstatstatements.html613
-rw-r--r--doc/src/sgml/html/pgstattuple.html199
-rw-r--r--doc/src/sgml/html/pgsurgery.html68
-rw-r--r--doc/src/sgml/html/pgtestfsync.html41
-rw-r--r--doc/src/sgml/html/pgtesttiming.html179
-rw-r--r--doc/src/sgml/html/pgtrgm.html424
-rw-r--r--doc/src/sgml/html/pgupgrade.html432
-rw-r--r--doc/src/sgml/html/pgvisibility.html69
-rw-r--r--doc/src/sgml/html/pgwaldump.html108
-rw-r--r--doc/src/sgml/html/pgwalinspect.html130
-rw-r--r--doc/src/sgml/html/pgxlogdump.html10
-rw-r--r--doc/src/sgml/html/planner-optimizer.html111
-rw-r--r--doc/src/sgml/html/planner-stats-details.html13
-rw-r--r--doc/src/sgml/html/planner-stats-security.html49
-rw-r--r--doc/src/sgml/html/planner-stats.html336
-rw-r--r--doc/src/sgml/html/plhandler.html156
-rw-r--r--doc/src/sgml/html/plperl-builtins.html360
-rw-r--r--doc/src/sgml/html/plperl-data.html14
-rw-r--r--doc/src/sgml/html/plperl-event-triggers.html28
-rw-r--r--doc/src/sgml/html/plperl-funcs.html308
-rw-r--r--doc/src/sgml/html/plperl-global.html65
-rw-r--r--doc/src/sgml/html/plperl-triggers.html74
-rw-r--r--doc/src/sgml/html/plperl-trusted.html72
-rw-r--r--doc/src/sgml/html/plperl-under-the-hood.html111
-rw-r--r--doc/src/sgml/html/plperl.html22
-rw-r--r--doc/src/sgml/html/plpgsql-control-structures.html943
-rw-r--r--doc/src/sgml/html/plpgsql-cursors.html386
-rw-r--r--doc/src/sgml/html/plpgsql-declarations.html464
-rw-r--r--doc/src/sgml/html/plpgsql-development-tips.html228
-rw-r--r--doc/src/sgml/html/plpgsql-errors-and-messages.html148
-rw-r--r--doc/src/sgml/html/plpgsql-expressions.html55
-rw-r--r--doc/src/sgml/html/plpgsql-implementation.html276
-rw-r--r--doc/src/sgml/html/plpgsql-overview.html103
-rw-r--r--doc/src/sgml/html/plpgsql-porting.html560
-rw-r--r--doc/src/sgml/html/plpgsql-statements.html598
-rw-r--r--doc/src/sgml/html/plpgsql-structure.html108
-rw-r--r--doc/src/sgml/html/plpgsql-transactions.html82
-rw-r--r--doc/src/sgml/html/plpgsql-trigger.html516
-rw-r--r--doc/src/sgml/html/plpgsql.html2
-rw-r--r--doc/src/sgml/html/plpython-data.html343
-rw-r--r--doc/src/sgml/html/plpython-database.html238
-rw-r--r--doc/src/sgml/html/plpython-do.html14
-rw-r--r--doc/src/sgml/html/plpython-envar.html17
-rw-r--r--doc/src/sgml/html/plpython-funcs.html88
-rw-r--r--doc/src/sgml/html/plpython-python23.html7
-rw-r--r--doc/src/sgml/html/plpython-sharing.html14
-rw-r--r--doc/src/sgml/html/plpython-subtransaction.html68
-rw-r--r--doc/src/sgml/html/plpython-transactions.html31
-rw-r--r--doc/src/sgml/html/plpython-trigger.html40
-rw-r--r--doc/src/sgml/html/plpython-util.html60
-rw-r--r--doc/src/sgml/html/plpython.html28
-rw-r--r--doc/src/sgml/html/pltcl-config.html42
-rw-r--r--doc/src/sgml/html/pltcl-data.html9
-rw-r--r--doc/src/sgml/html/pltcl-dbaccess.html193
-rw-r--r--doc/src/sgml/html/pltcl-error-handling.html60
-rw-r--r--doc/src/sgml/html/pltcl-event-trigger.html30
-rw-r--r--doc/src/sgml/html/pltcl-functions.html141
-rw-r--r--doc/src/sgml/html/pltcl-global.html45
-rw-r--r--doc/src/sgml/html/pltcl-overview.html43
-rw-r--r--doc/src/sgml/html/pltcl-procnames.html13
-rw-r--r--doc/src/sgml/html/pltcl-subtransactions.html67
-rw-r--r--doc/src/sgml/html/pltcl-transactions.html33
-rw-r--r--doc/src/sgml/html/pltcl-trigger.html115
-rw-r--r--doc/src/sgml/html/pltcl.html8
-rw-r--r--doc/src/sgml/html/populate.html206
-rw-r--r--doc/src/sgml/html/postgres-fdw.html677
-rw-r--r--doc/src/sgml/html/postgres-user.html20
-rw-r--r--doc/src/sgml/html/predefined-roles.html79
-rw-r--r--doc/src/sgml/html/preface.html47
-rw-r--r--doc/src/sgml/html/preventing-server-spoofing.html44
-rw-r--r--doc/src/sgml/html/progress-reporting.html651
-rw-r--r--doc/src/sgml/html/protocol-changes.html73
-rw-r--r--doc/src/sgml/html/protocol-error-fields.html99
-rw-r--r--doc/src/sgml/html/protocol-flow.html975
-rw-r--r--doc/src/sgml/html/protocol-logical-replication.html84
-rw-r--r--doc/src/sgml/html/protocol-logicalrep-message-formats.html307
-rw-r--r--doc/src/sgml/html/protocol-message-formats.html676
-rw-r--r--doc/src/sgml/html/protocol-message-types.html34
-rw-r--r--doc/src/sgml/html/protocol-overview.html112
-rw-r--r--doc/src/sgml/html/protocol-replication.html529
-rw-r--r--doc/src/sgml/html/protocol.html35
-rw-r--r--doc/src/sgml/html/queries-limit.html48
-rw-r--r--doc/src/sgml/html/queries-order.html76
-rw-r--r--doc/src/sgml/html/queries-overview.html53
-rw-r--r--doc/src/sgml/html/queries-select-lists.html122
-rw-r--r--doc/src/sgml/html/queries-table-expressions.html1030
-rw-r--r--doc/src/sgml/html/queries-union.html76
-rw-r--r--doc/src/sgml/html/queries-values.html60
-rw-r--r--doc/src/sgml/html/queries-with.html564
-rw-r--r--doc/src/sgml/html/queries.html6
-rw-r--r--doc/src/sgml/html/query-path.html55
-rw-r--r--doc/src/sgml/html/querytree.html152
-rw-r--r--doc/src/sgml/html/rangetypes.html435
-rw-r--r--doc/src/sgml/html/recovery-config.html31
-rw-r--r--doc/src/sgml/html/reference-client.html24
-rw-r--r--doc/src/sgml/html/reference-server.html8
-rw-r--r--doc/src/sgml/html/reference.html31
-rw-r--r--doc/src/sgml/html/regress-coverage.html43
-rw-r--r--doc/src/sgml/html/regress-evaluation.html166
-rw-r--r--doc/src/sgml/html/regress-run.html258
-rw-r--r--doc/src/sgml/html/regress-tap.html42
-rw-r--r--doc/src/sgml/html/regress-variant.html77
-rw-r--r--doc/src/sgml/html/regress.html7
-rw-r--r--doc/src/sgml/html/release-15-1.html224
-rw-r--r--doc/src/sgml/html/release-15-2.html433
-rw-r--r--doc/src/sgml/html/release-15-3.html603
-rw-r--r--doc/src/sgml/html/release-15-4.html351
-rw-r--r--doc/src/sgml/html/release-15-5.html468
-rw-r--r--doc/src/sgml/html/release-15.html1113
-rw-r--r--doc/src/sgml/html/release-prior.html5
-rw-r--r--doc/src/sgml/html/release.html21
-rw-r--r--doc/src/sgml/html/replication-origins.html68
-rw-r--r--doc/src/sgml/html/resources.html32
-rw-r--r--doc/src/sgml/html/role-attributes.html120
-rw-r--r--doc/src/sgml/html/role-membership.html107
-rw-r--r--doc/src/sgml/html/role-removal.html54
-rw-r--r--doc/src/sgml/html/routine-reindex.html31
-rw-r--r--doc/src/sgml/html/routine-vacuuming.html695
-rw-r--r--doc/src/sgml/html/row-estimation-examples.html399
-rw-r--r--doc/src/sgml/html/rowtypes.html424
-rw-r--r--doc/src/sgml/html/rule-system.html30
-rw-r--r--doc/src/sgml/html/rules-materializedviews.html182
-rw-r--r--doc/src/sgml/html/rules-privileges.html160
-rw-r--r--doc/src/sgml/html/rules-status.html35
-rw-r--r--doc/src/sgml/html/rules-triggers.html178
-rw-r--r--doc/src/sgml/html/rules-update.html750
-rw-r--r--doc/src/sgml/html/rules-views.html506
-rw-r--r--doc/src/sgml/html/rules.html21
-rw-r--r--doc/src/sgml/html/runtime-config-autovacuum.html163
-rw-r--r--doc/src/sgml/html/runtime-config-client.html854
-rw-r--r--doc/src/sgml/html/runtime-config-compatible.html143
-rw-r--r--doc/src/sgml/html/runtime-config-connection.html546
-rw-r--r--doc/src/sgml/html/runtime-config-custom.html21
-rw-r--r--doc/src/sgml/html/runtime-config-developer.html377
-rw-r--r--doc/src/sgml/html/runtime-config-error-handling.html71
-rw-r--r--doc/src/sgml/html/runtime-config-file-locations.html74
-rw-r--r--doc/src/sgml/html/runtime-config-locks.html84
-rw-r--r--doc/src/sgml/html/runtime-config-logging.html938
-rw-r--r--doc/src/sgml/html/runtime-config-preset.html152
-rw-r--r--doc/src/sgml/html/runtime-config-query.html544
-rw-r--r--doc/src/sgml/html/runtime-config-replication.html562
-rw-r--r--doc/src/sgml/html/runtime-config-resource.html714
-rw-r--r--doc/src/sgml/html/runtime-config-short.html24
-rw-r--r--doc/src/sgml/html/runtime-config-statistics.html149
-rw-r--r--doc/src/sgml/html/runtime-config-wal.html830
-rw-r--r--doc/src/sgml/html/runtime-config.html7
-rw-r--r--doc/src/sgml/html/runtime.html16
-rw-r--r--doc/src/sgml/html/sasl-authentication.html104
-rw-r--r--doc/src/sgml/html/seg.html222
-rw-r--r--doc/src/sgml/html/sepgsql.html520
-rw-r--r--doc/src/sgml/html/server-programming.html13
-rw-r--r--doc/src/sgml/html/server-shutdown.html66
-rw-r--r--doc/src/sgml/html/server-start.html259
-rw-r--r--doc/src/sgml/html/source-conventions.html106
-rw-r--r--doc/src/sgml/html/source-format.html63
-rw-r--r--doc/src/sgml/html/source.html2
-rw-r--r--doc/src/sgml/html/sourcerepo.html17
-rw-r--r--doc/src/sgml/html/spgist-builtin-opclasses.html16
-rw-r--r--doc/src/sgml/html/spgist-examples.html8
-rw-r--r--doc/src/sgml/html/spgist-extensibility.html621
-rw-r--r--doc/src/sgml/html/spgist-implementation.html90
-rw-r--r--doc/src/sgml/html/spgist-intro.html34
-rw-r--r--doc/src/sgml/html/spgist.html2
-rw-r--r--doc/src/sgml/html/spi-examples.html170
-rw-r--r--doc/src/sgml/html/spi-interface-support.html9
-rw-r--r--doc/src/sgml/html/spi-interface.html6
-rw-r--r--doc/src/sgml/html/spi-memory.html46
-rw-r--r--doc/src/sgml/html/spi-realloc.html18
-rw-r--r--doc/src/sgml/html/spi-spi-commit.html23
-rw-r--r--doc/src/sgml/html/spi-spi-connect.html28
-rw-r--r--doc/src/sgml/html/spi-spi-copytuple.html18
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-close.html13
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-fetch.html22
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-find.html20
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-move.html18
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-open-with-args.html59
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-open-with-paramlist.html30
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-open.html47
-rw-r--r--doc/src/sgml/html/spi-spi-cursor-parse-open.html47
-rw-r--r--doc/src/sgml/html/spi-spi-exec.html16
-rw-r--r--doc/src/sgml/html/spi-spi-execp.html36
-rw-r--r--doc/src/sgml/html/spi-spi-execute-extended.html68
-rw-r--r--doc/src/sgml/html/spi-spi-execute-plan-extended.html68
-rw-r--r--doc/src/sgml/html/spi-spi-execute-plan-with-paramlist.html32
-rw-r--r--doc/src/sgml/html/spi-spi-execute-plan.html47
-rw-r--r--doc/src/sgml/html/spi-spi-execute-with-args.html60
-rw-r--r--doc/src/sgml/html/spi-spi-execute.html179
-rw-r--r--doc/src/sgml/html/spi-spi-finish.html15
-rw-r--r--doc/src/sgml/html/spi-spi-fname.html17
-rw-r--r--doc/src/sgml/html/spi-spi-fnumber.html22
-rw-r--r--doc/src/sgml/html/spi-spi-freeplan.html14
-rw-r--r--doc/src/sgml/html/spi-spi-freetuple.html13
-rw-r--r--doc/src/sgml/html/spi-spi-freetupletable.html26
-rw-r--r--doc/src/sgml/html/spi-spi-getargcount.html15
-rw-r--r--doc/src/sgml/html/spi-spi-getargtypeid.html21
-rw-r--r--doc/src/sgml/html/spi-spi-getbinval.html27
-rw-r--r--doc/src/sgml/html/spi-spi-getnspname.html14
-rw-r--r--doc/src/sgml/html/spi-spi-getrelname.html12
-rw-r--r--doc/src/sgml/html/spi-spi-gettype.html16
-rw-r--r--doc/src/sgml/html/spi-spi-gettypeid.html16
-rw-r--r--doc/src/sgml/html/spi-spi-getvalue.html25
-rw-r--r--doc/src/sgml/html/spi-spi-is-cursor-plan.html27
-rw-r--r--doc/src/sgml/html/spi-spi-keepplan.html20
-rw-r--r--doc/src/sgml/html/spi-spi-modifytuple.html59
-rw-r--r--doc/src/sgml/html/spi-spi-palloc.html14
-rw-r--r--doc/src/sgml/html/spi-spi-pfree.html14
-rw-r--r--doc/src/sgml/html/spi-spi-prepare-cursor.html35
-rw-r--r--doc/src/sgml/html/spi-spi-prepare-extended.html34
-rw-r--r--doc/src/sgml/html/spi-spi-prepare-params.html27
-rw-r--r--doc/src/sgml/html/spi-spi-prepare.html84
-rw-r--r--doc/src/sgml/html/spi-spi-register-relation.html29
-rw-r--r--doc/src/sgml/html/spi-spi-register-trigger-data.html32
-rw-r--r--doc/src/sgml/html/spi-spi-result-code-string.html12
-rw-r--r--doc/src/sgml/html/spi-spi-returntuple.html26
-rw-r--r--doc/src/sgml/html/spi-spi-rollback.html20
-rw-r--r--doc/src/sgml/html/spi-spi-saveplan.html30
-rw-r--r--doc/src/sgml/html/spi-spi-scroll-cursor-fetch.html34
-rw-r--r--doc/src/sgml/html/spi-spi-scroll-cursor-move.html36
-rw-r--r--doc/src/sgml/html/spi-spi-start-transaction.html11
-rw-r--r--doc/src/sgml/html/spi-spi-unregister-relation.html27
-rw-r--r--doc/src/sgml/html/spi-transaction.html19
-rw-r--r--doc/src/sgml/html/spi-visibility.html38
-rw-r--r--doc/src/sgml/html/spi.html38
-rw-r--r--doc/src/sgml/html/sql-abort.html31
-rw-r--r--doc/src/sgml/html/sql-alteraggregate.html83
-rw-r--r--doc/src/sgml/html/sql-altercollation.html98
-rw-r--r--doc/src/sgml/html/sql-alterconversion.html39
-rw-r--r--doc/src/sgml/html/sql-alterdatabase.html112
-rw-r--r--doc/src/sgml/html/sql-alterdefaultprivileges.html163
-rw-r--r--doc/src/sgml/html/sql-alterdomain.html152
-rw-r--r--doc/src/sgml/html/sql-altereventtrigger.html25
-rw-r--r--doc/src/sgml/html/sql-alterextension.html141
-rw-r--r--doc/src/sgml/html/sql-alterforeigndatawrapper.html68
-rw-r--r--doc/src/sgml/html/sql-alterforeigntable.html236
-rw-r--r--doc/src/sgml/html/sql-alterfunction.html174
-rw-r--r--doc/src/sgml/html/sql-altergroup.html53
-rw-r--r--doc/src/sgml/html/sql-alterindex.html138
-rw-r--r--doc/src/sgml/html/sql-alterlanguage.html19
-rw-r--r--doc/src/sgml/html/sql-alterlargeobject.html20
-rw-r--r--doc/src/sgml/html/sql-altermaterializedview.html75
-rw-r--r--doc/src/sgml/html/sql-alteropclass.html36
-rw-r--r--doc/src/sgml/html/sql-alteroperator.html49
-rw-r--r--doc/src/sgml/html/sql-alteropfamily.html181
-rw-r--r--doc/src/sgml/html/sql-alterpolicy.html45
-rw-r--r--doc/src/sgml/html/sql-alterprocedure.html133
-rw-r--r--doc/src/sgml/html/sql-alterpublication.html112
-rw-r--r--doc/src/sgml/html/sql-alterrole.html189
-rw-r--r--doc/src/sgml/html/sql-alterroutine.html49
-rw-r--r--doc/src/sgml/html/sql-alterrule.html25
-rw-r--r--doc/src/sgml/html/sql-alterschema.html26
-rw-r--r--doc/src/sgml/html/sql-altersequence.html165
-rw-r--r--doc/src/sgml/html/sql-alterserver.html48
-rw-r--r--doc/src/sgml/html/sql-alterstatistics.html46
-rw-r--r--doc/src/sgml/html/sql-altersubscription.html147
-rw-r--r--doc/src/sgml/html/sql-altersystem.html65
-rw-r--r--doc/src/sgml/html/sql-altertable.html1094
-rw-r--r--doc/src/sgml/html/sql-altertablespace.html50
-rw-r--r--doc/src/sgml/html/sql-altertrigger.html49
-rw-r--r--doc/src/sgml/html/sql-altertsconfig.html68
-rw-r--r--doc/src/sgml/html/sql-altertsdictionary.html60
-rw-r--r--doc/src/sgml/html/sql-altertsparser.html20
-rw-r--r--doc/src/sgml/html/sql-altertstemplate.html20
-rw-r--r--doc/src/sgml/html/sql-altertype.html226
-rw-r--r--doc/src/sgml/html/sql-alteruser.html38
-rw-r--r--doc/src/sgml/html/sql-alterusermapping.html43
-rw-r--r--doc/src/sgml/html/sql-alterview.html80
-rw-r--r--doc/src/sgml/html/sql-analyze.html187
-rw-r--r--doc/src/sgml/html/sql-begin.html71
-rw-r--r--doc/src/sgml/html/sql-call.html47
-rw-r--r--doc/src/sgml/html/sql-checkpoint.html28
-rw-r--r--doc/src/sgml/html/sql-close.html42
-rw-r--r--doc/src/sgml/html/sql-cluster.html137
-rw-r--r--doc/src/sgml/html/sql-commands.html19
-rw-r--r--doc/src/sgml/html/sql-comment.html198
-rw-r--r--doc/src/sgml/html/sql-commit-prepared.html33
-rw-r--r--doc/src/sgml/html/sql-commit.html28
-rw-r--r--doc/src/sgml/html/sql-copy.html641
-rw-r--r--doc/src/sgml/html/sql-create-access-method.html39
-rw-r--r--doc/src/sgml/html/sql-createaggregate.html510
-rw-r--r--doc/src/sgml/html/sql-createcast.html256
-rw-r--r--doc/src/sgml/html/sql-createcollation.html109
-rw-r--r--doc/src/sgml/html/sql-createconversion.html72
-rw-r--r--doc/src/sgml/html/sql-createdatabase.html240
-rw-r--r--doc/src/sgml/html/sql-createdomain.html148
-rw-r--r--doc/src/sgml/html/sql-createeventtrigger.html65
-rw-r--r--doc/src/sgml/html/sql-createextension.html128
-rw-r--r--doc/src/sgml/html/sql-createforeigndatawrapper.html77
-rw-r--r--doc/src/sgml/html/sql-createforeigntable.html244
-rw-r--r--doc/src/sgml/html/sql-createfunction.html554
-rw-r--r--doc/src/sgml/html/sql-creategroup.html29
-rw-r--r--doc/src/sgml/html/sql-createindex.html580
-rw-r--r--doc/src/sgml/html/sql-createlanguage.html120
-rw-r--r--doc/src/sgml/html/sql-creatematerializedview.html71
-rw-r--r--doc/src/sgml/html/sql-createopclass.html152
-rw-r--r--doc/src/sgml/html/sql-createoperator.html136
-rw-r--r--doc/src/sgml/html/sql-createopfamily.html43
-rw-r--r--doc/src/sgml/html/sql-createpolicy.html361
-rw-r--r--doc/src/sgml/html/sql-createprocedure.html208
-rw-r--r--doc/src/sgml/html/sql-createpublication.html232
-rw-r--r--doc/src/sgml/html/sql-createrole.html269
-rw-r--r--doc/src/sgml/html/sql-createrule.html176
-rw-r--r--doc/src/sgml/html/sql-createschema.html118
-rw-r--r--doc/src/sgml/html/sql-createsequence.html214
-rw-r--r--doc/src/sgml/html/sql-createserver.html56
-rw-r--r--doc/src/sgml/html/sql-createstatistics.html210
-rw-r--r--doc/src/sgml/html/sql-createsubscription.html217
-rw-r--r--doc/src/sgml/html/sql-createtable.html1470
-rw-r--r--doc/src/sgml/html/sql-createtableas.html148
-rw-r--r--doc/src/sgml/html/sql-createtablespace.html80
-rw-r--r--doc/src/sgml/html/sql-createtransform.html106
-rw-r--r--doc/src/sgml/html/sql-createtrigger.html461
-rw-r--r--doc/src/sgml/html/sql-createtsconfig.html40
-rw-r--r--doc/src/sgml/html/sql-createtsdictionary.html47
-rw-r--r--doc/src/sgml/html/sql-createtsparser.html51
-rw-r--r--doc/src/sgml/html/sql-createtstemplate.html45
-rw-r--r--doc/src/sgml/html/sql-createtype.html655
-rw-r--r--doc/src/sgml/html/sql-createuser.html35
-rw-r--r--doc/src/sgml/html/sql-createusermapping.html42
-rw-r--r--doc/src/sgml/html/sql-createview.html346
-rw-r--r--doc/src/sgml/html/sql-deallocate.html19
-rw-r--r--doc/src/sgml/html/sql-declare.html200
-rw-r--r--doc/src/sgml/html/sql-delete.html145
-rw-r--r--doc/src/sgml/html/sql-discard.html41
-rw-r--r--doc/src/sgml/html/sql-do.html49
-rw-r--r--doc/src/sgml/html/sql-drop-access-method.html27
-rw-r--r--doc/src/sgml/html/sql-drop-owned.html41
-rw-r--r--doc/src/sgml/html/sql-dropaggregate.html65
-rw-r--r--doc/src/sgml/html/sql-dropcast.html26
-rw-r--r--doc/src/sgml/html/sql-dropcollation.html28
-rw-r--r--doc/src/sgml/html/sql-dropconversion.html26
-rw-r--r--doc/src/sgml/html/sql-dropdatabase.html44
-rw-r--r--doc/src/sgml/html/sql-dropdomain.html29
-rw-r--r--doc/src/sgml/html/sql-dropeventtrigger.html28
-rw-r--r--doc/src/sgml/html/sql-dropextension.html38
-rw-r--r--doc/src/sgml/html/sql-dropforeigndatawrapper.html29
-rw-r--r--doc/src/sgml/html/sql-dropforeigntable.html30
-rw-r--r--doc/src/sgml/html/sql-dropfunction.html67
-rw-r--r--doc/src/sgml/html/sql-dropgroup.html9
-rw-r--r--doc/src/sgml/html/sql-dropindex.html50
-rw-r--r--doc/src/sgml/html/sql-droplanguage.html35
-rw-r--r--doc/src/sgml/html/sql-dropmaterializedview.html30
-rw-r--r--doc/src/sgml/html/sql-dropopclass.html47
-rw-r--r--doc/src/sgml/html/sql-dropoperator.html42
-rw-r--r--doc/src/sgml/html/sql-dropopfamily.html40
-rw-r--r--doc/src/sgml/html/sql-droppolicy.html30
-rw-r--r--doc/src/sgml/html/sql-dropprocedure.html96
-rw-r--r--doc/src/sgml/html/sql-droppublication.html24
-rw-r--r--doc/src/sgml/html/sql-droprole.html41
-rw-r--r--doc/src/sgml/html/sql-droproutine.html45
-rw-r--r--doc/src/sgml/html/sql-droprule.html30
-rw-r--r--doc/src/sgml/html/sql-dropschema.html38
-rw-r--r--doc/src/sgml/html/sql-dropsequence.html30
-rw-r--r--doc/src/sgml/html/sql-dropserver.html29
-rw-r--r--doc/src/sgml/html/sql-dropstatistics.html26
-rw-r--r--doc/src/sgml/html/sql-dropsubscription.html49
-rw-r--r--doc/src/sgml/html/sql-droptable.html42
-rw-r--r--doc/src/sgml/html/sql-droptablespace.html28
-rw-r--r--doc/src/sgml/html/sql-droptransform.html31
-rw-r--r--doc/src/sgml/html/sql-droptrigger.html35
-rw-r--r--doc/src/sgml/html/sql-droptsconfig.html35
-rw-r--r--doc/src/sgml/html/sql-droptsdictionary.html34
-rw-r--r--doc/src/sgml/html/sql-droptsparser.html32
-rw-r--r--doc/src/sgml/html/sql-droptstemplate.html33
-rw-r--r--doc/src/sgml/html/sql-droptype.html31
-rw-r--r--doc/src/sgml/html/sql-dropuser.html11
-rw-r--r--doc/src/sgml/html/sql-dropusermapping.html30
-rw-r--r--doc/src/sgml/html/sql-dropview.html29
-rw-r--r--doc/src/sgml/html/sql-end.html30
-rw-r--r--doc/src/sgml/html/sql-execute.html38
-rw-r--r--doc/src/sgml/html/sql-explain.html306
-rw-r--r--doc/src/sgml/html/sql-expressions.html995
-rw-r--r--doc/src/sgml/html/sql-fetch.html190
-rw-r--r--doc/src/sgml/html/sql-grant.html318
-rw-r--r--doc/src/sgml/html/sql-importforeignschema.html60
-rw-r--r--doc/src/sgml/html/sql-insert.html488
-rw-r--r--doc/src/sgml/html/sql-keywords-appendix.html63
-rw-r--r--doc/src/sgml/html/sql-listen.html70
-rw-r--r--doc/src/sgml/html/sql-load.html31
-rw-r--r--doc/src/sgml/html/sql-lock.html167
-rw-r--r--doc/src/sgml/html/sql-merge.html380
-rw-r--r--doc/src/sgml/html/sql-move.html59
-rw-r--r--doc/src/sgml/html/sql-notify.html132
-rw-r--r--doc/src/sgml/html/sql-prepare-transaction.html90
-rw-r--r--doc/src/sgml/html/sql-prepare.html151
-rw-r--r--doc/src/sgml/html/sql-reassign-owned.html42
-rw-r--r--doc/src/sgml/html/sql-refreshmaterializedview.html59
-rw-r--r--doc/src/sgml/html/sql-reindex.html327
-rw-r--r--doc/src/sgml/html/sql-release-savepoint.html45
-rw-r--r--doc/src/sgml/html/sql-reset.html39
-rw-r--r--doc/src/sgml/html/sql-revoke.html249
-rw-r--r--doc/src/sgml/html/sql-rollback-prepared.html33
-rw-r--r--doc/src/sgml/html/sql-rollback-to.html71
-rw-r--r--doc/src/sgml/html/sql-rollback.html27
-rw-r--r--doc/src/sgml/html/sql-savepoint.html79
-rw-r--r--doc/src/sgml/html/sql-security-label.html101
-rw-r--r--doc/src/sgml/html/sql-select.html1606
-rw-r--r--doc/src/sgml/html/sql-selectinto.html68
-rw-r--r--doc/src/sgml/html/sql-set-constraints.html71
-rw-r--r--doc/src/sgml/html/sql-set-role.html85
-rw-r--r--doc/src/sgml/html/sql-set-session-authorization.html64
-rw-r--r--doc/src/sgml/html/sql-set-transaction.html179
-rw-r--r--doc/src/sgml/html/sql-set.html155
-rw-r--r--doc/src/sgml/html/sql-show.html82
-rw-r--r--doc/src/sgml/html/sql-start-transaction.html37
-rw-r--r--doc/src/sgml/html/sql-syntax-calling-funcs.html132
-rw-r--r--doc/src/sgml/html/sql-syntax-lexical.html647
-rw-r--r--doc/src/sgml/html/sql-syntax.html11
-rw-r--r--doc/src/sgml/html/sql-truncate.html119
-rw-r--r--doc/src/sgml/html/sql-unlisten.html48
-rw-r--r--doc/src/sgml/html/sql-update.html290
-rw-r--r--doc/src/sgml/html/sql-vacuum.html258
-rw-r--r--doc/src/sgml/html/sql-values.html138
-rw-r--r--doc/src/sgml/html/sql.html30
-rw-r--r--doc/src/sgml/html/ssh-tunnels.html76
-rw-r--r--doc/src/sgml/html/ssl-tcp.html264
-rw-r--r--doc/src/sgml/html/sslinfo.html135
-rw-r--r--doc/src/sgml/html/sspi-auth.html70
-rw-r--r--doc/src/sgml/html/storage-file-layout.html133
-rw-r--r--doc/src/sgml/html/storage-fsm.html26
-rw-r--r--doc/src/sgml/html/storage-hot.html45
-rw-r--r--doc/src/sgml/html/storage-init.html8
-rw-r--r--doc/src/sgml/html/storage-page-layout.html157
-rw-r--r--doc/src/sgml/html/storage-toast.html223
-rw-r--r--doc/src/sgml/html/storage-vm.html29
-rw-r--r--doc/src/sgml/html/storage.html5
-rw-r--r--doc/src/sgml/html/stylesheet.css165
-rw-r--r--doc/src/sgml/html/supported-platforms.html39
-rw-r--r--doc/src/sgml/html/system-catalog-declarations.html74
-rw-r--r--doc/src/sgml/html/system-catalog-initial-data.html404
-rw-r--r--doc/src/sgml/html/tableam.html72
-rw-r--r--doc/src/sgml/html/tablefunc.html613
-rw-r--r--doc/src/sgml/html/tablesample-method.html57
-rw-r--r--doc/src/sgml/html/tablesample-support-functions.html163
-rw-r--r--doc/src/sgml/html/tcn.html55
-rw-r--r--doc/src/sgml/html/test-decoding.html48
-rw-r--r--doc/src/sgml/html/textsearch-configuration.html108
-rw-r--r--doc/src/sgml/html/textsearch-controls.html550
-rw-r--r--doc/src/sgml/html/textsearch-debugging.html253
-rw-r--r--doc/src/sgml/html/textsearch-dictionaries.html661
-rw-r--r--doc/src/sgml/html/textsearch-features.html392
-rw-r--r--doc/src/sgml/html/textsearch-indexes.html80
-rw-r--r--doc/src/sgml/html/textsearch-intro.html339
-rw-r--r--doc/src/sgml/html/textsearch-limitations.html21
-rw-r--r--doc/src/sgml/html/textsearch-parsers.html59
-rw-r--r--doc/src/sgml/html/textsearch-psql.html165
-rw-r--r--doc/src/sgml/html/textsearch-tables.html139
-rw-r--r--doc/src/sgml/html/textsearch.html2
-rw-r--r--doc/src/sgml/html/transaction-iso.html540
-rw-r--r--doc/src/sgml/html/trigger-datachanges.html46
-rw-r--r--doc/src/sgml/html/trigger-definition.html315
-rw-r--r--doc/src/sgml/html/trigger-example.html180
-rw-r--r--doc/src/sgml/html/trigger-interface.html184
-rw-r--r--doc/src/sgml/html/triggers.html18
-rw-r--r--doc/src/sgml/html/tsm-system-rows.html39
-rw-r--r--doc/src/sgml/html/tsm-system-time.html41
-rw-r--r--doc/src/sgml/html/tutorial-accessdb.html103
-rw-r--r--doc/src/sgml/html/tutorial-advanced-intro.html18
-rw-r--r--doc/src/sgml/html/tutorial-advanced.html2
-rw-r--r--doc/src/sgml/html/tutorial-agg.html172
-rw-r--r--doc/src/sgml/html/tutorial-arch.html49
-rw-r--r--doc/src/sgml/html/tutorial-concepts.html37
-rw-r--r--doc/src/sgml/html/tutorial-conclusion.html12
-rw-r--r--doc/src/sgml/html/tutorial-createdb.html118
-rw-r--r--doc/src/sgml/html/tutorial-delete.html34
-rw-r--r--doc/src/sgml/html/tutorial-fk.html51
-rw-r--r--doc/src/sgml/html/tutorial-inheritance.html113
-rw-r--r--doc/src/sgml/html/tutorial-install.html38
-rw-r--r--doc/src/sgml/html/tutorial-join.html162
-rw-r--r--doc/src/sgml/html/tutorial-populate.html59
-rw-r--r--doc/src/sgml/html/tutorial-select.html142
-rw-r--r--doc/src/sgml/html/tutorial-sql-intro.html43
-rw-r--r--doc/src/sgml/html/tutorial-sql.html2
-rw-r--r--doc/src/sgml/html/tutorial-start.html2
-rw-r--r--doc/src/sgml/html/tutorial-table.html69
-rw-r--r--doc/src/sgml/html/tutorial-transactions.html142
-rw-r--r--doc/src/sgml/html/tutorial-update.html26
-rw-r--r--doc/src/sgml/html/tutorial-views.html26
-rw-r--r--doc/src/sgml/html/tutorial-window.html202
-rw-r--r--doc/src/sgml/html/tutorial.html20
-rw-r--r--doc/src/sgml/html/typeconv-func.html268
-rw-r--r--doc/src/sgml/html/typeconv-oper.html247
-rw-r--r--doc/src/sgml/html/typeconv-overview.html113
-rw-r--r--doc/src/sgml/html/typeconv-query.html55
-rw-r--r--doc/src/sgml/html/typeconv-select.html30
-rw-r--r--doc/src/sgml/html/typeconv-union-case.html114
-rw-r--r--doc/src/sgml/html/typeconv.html19
-rw-r--r--doc/src/sgml/html/unaccent.html131
-rw-r--r--doc/src/sgml/html/unsupported-features-sql-standard.html9
-rw-r--r--doc/src/sgml/html/upgrading.html195
-rw-r--r--doc/src/sgml/html/user-manag.html20
-rw-r--r--doc/src/sgml/html/using-explain.html804
-rw-r--r--doc/src/sgml/html/uuid-ossp.html144
-rw-r--r--doc/src/sgml/html/vacuumlo.html74
-rw-r--r--doc/src/sgml/html/view-pg-available-extension-versions.html65
-rw-r--r--doc/src/sgml/html/view-pg-available-extensions.html37
-rw-r--r--doc/src/sgml/html/view-pg-backend-memory-contexts.html62
-rw-r--r--doc/src/sgml/html/view-pg-config.html29
-rw-r--r--doc/src/sgml/html/view-pg-cursors.html72
-rw-r--r--doc/src/sgml/html/view-pg-file-settings.html77
-rw-r--r--doc/src/sgml/html/view-pg-group.html32
-rw-r--r--doc/src/sgml/html/view-pg-hba-file-rules.html76
-rw-r--r--doc/src/sgml/html/view-pg-ident-file-mappings.html53
-rw-r--r--doc/src/sgml/html/view-pg-indexes.html40
-rw-r--r--doc/src/sgml/html/view-pg-locks.html255
-rw-r--r--doc/src/sgml/html/view-pg-matviews.html49
-rw-r--r--doc/src/sgml/html/view-pg-policies.html55
-rw-r--r--doc/src/sgml/html/view-pg-prepared-statements.html65
-rw-r--r--doc/src/sgml/html/view-pg-prepared-xacts.html50
-rw-r--r--doc/src/sgml/html/view-pg-publication-tables.html46
-rw-r--r--doc/src/sgml/html/view-pg-replication-origin-status.html36
-rw-r--r--doc/src/sgml/html/view-pg-replication-slots.html131
-rw-r--r--doc/src/sgml/html/view-pg-roles.html85
-rw-r--r--doc/src/sgml/html/view-pg-rules.html37
-rw-r--r--doc/src/sgml/html/view-pg-seclabels.html60
-rw-r--r--doc/src/sgml/html/view-pg-sequences.html74
-rw-r--r--doc/src/sgml/html/view-pg-settings.html201
-rw-r--r--doc/src/sgml/html/view-pg-shadow.html71
-rw-r--r--doc/src/sgml/html/view-pg-shmem-allocations.html52
-rw-r--r--doc/src/sgml/html/view-pg-stats-ext-exprs.html147
-rw-r--r--doc/src/sgml/html/view-pg-stats-ext.html124
-rw-r--r--doc/src/sgml/html/view-pg-stats.html128
-rw-r--r--doc/src/sgml/html/view-pg-tables.html58
-rw-r--r--doc/src/sgml/html/view-pg-timezone-abbrevs.html32
-rw-r--r--doc/src/sgml/html/view-pg-timezone-names.html38
-rw-r--r--doc/src/sgml/html/view-pg-user-mappings.html60
-rw-r--r--doc/src/sgml/html/view-pg-user.html60
-rw-r--r--doc/src/sgml/html/view-pg-views.html33
-rw-r--r--doc/src/sgml/html/views-overview.html6
-rw-r--r--doc/src/sgml/html/views.html20
-rw-r--r--doc/src/sgml/html/wal-async-commit.html99
-rw-r--r--doc/src/sgml/html/wal-configuration.html295
-rw-r--r--doc/src/sgml/html/wal-internals.html70
-rw-r--r--doc/src/sgml/html/wal-intro.html48
-rw-r--r--doc/src/sgml/html/wal-reliability.html161
-rw-r--r--doc/src/sgml/html/wal.html5
-rw-r--r--doc/src/sgml/html/warm-standby-failover.html65
-rw-r--r--doc/src/sgml/html/warm-standby.html657
-rw-r--r--doc/src/sgml/html/when-can-parallel-query-be-used.html78
-rw-r--r--doc/src/sgml/html/xaggr.html528
-rw-r--r--doc/src/sgml/html/xfunc-c.html1387
-rw-r--r--doc/src/sgml/html/xfunc-internal.html31
-rw-r--r--doc/src/sgml/html/xfunc-optimization.html94
-rw-r--r--doc/src/sgml/html/xfunc-overload.html67
-rw-r--r--doc/src/sgml/html/xfunc-pl.html12
-rw-r--r--doc/src/sgml/html/xfunc-sql.html1123
-rw-r--r--doc/src/sgml/html/xfunc-volatility.html107
-rw-r--r--doc/src/sgml/html/xfunc.html43
-rw-r--r--doc/src/sgml/html/xindex.html772
-rw-r--r--doc/src/sgml/html/xml-limits-conformance.html204
-rw-r--r--doc/src/sgml/html/xml2.html274
-rw-r--r--doc/src/sgml/html/xoper-optimization.html281
-rw-r--r--doc/src/sgml/html/xoper.html58
-rw-r--r--doc/src/sgml/html/xplang-install.html142
-rw-r--r--doc/src/sgml/html/xplang.html29
-rw-r--r--doc/src/sgml/html/xproc.html41
-rw-r--r--doc/src/sgml/html/xtypes.html302
1158 files changed, 176809 insertions, 0 deletions
diff --git a/doc/src/sgml/html/acronyms.html b/doc/src/sgml/html/acronyms.html
new file mode 100644
index 0000000..94dfb64
--- /dev/null
+++ b/doc/src/sgml/html/acronyms.html
@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix L. Acronyms</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="limits.html" title="Appendix K. PostgreSQL Limits" /><link rel="next" href="glossary.html" title="Appendix M. Glossary" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix L. Acronyms</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="limits.html" title="Appendix K. PostgreSQL Limits">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="glossary.html" title="Appendix M. Glossary">Next</a></td></tr></table><hr /></div><div class="appendix" id="ACRONYMS"><div class="titlepage"><div><div><h2 class="title">Appendix L. Acronyms</h2></div></div></div><p>
+ This is a list of acronyms commonly used in the <span class="productname">PostgreSQL</span>
+ documentation and in discussions about <span class="productname">PostgreSQL</span>.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><acronym class="acronym">ANSI</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/American_National_Standards_Institute" target="_top">
+ American National Standards Institute</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">API</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/API" target="_top">Application Programming Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ASCII</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Ascii" target="_top">American Standard
+ Code for Information Interchange</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">BKI</acronym></span></dt><dd><p>
+ <a class="link" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Backend Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CA</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Certificate_authority" target="_top">Certificate Authority</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CIDR</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing" target="_top">Classless
+ Inter-Domain Routing</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CPAN</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://www.cpan.org/" target="_top">Comprehensive Perl Archive Network</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CRL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Certificate_revocation_list" target="_top">Certificate
+ Revocation List</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CSV</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Comma-separated_values" target="_top">Comma
+ Separated Values</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CTE</acronym></span></dt><dd><p>
+ <a class="link" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Common Table Expression</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">CVE</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://cve.mitre.org/" target="_top">Common Vulnerabilities and Exposures</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">DBA</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Database_administrator" target="_top">Database
+ Administrator</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">DBI</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://dbi.perl.org/" target="_top">Database Interface (Perl)</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">DBMS</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Dbms" target="_top">Database Management
+ System</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">DDL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Data_Definition_Language" target="_top">Data
+ Definition Language</a>, SQL commands such as <code class="command">CREATE
+ TABLE</code>, <code class="command">ALTER USER</code>
+ </p></dd><dt><span class="term"><acronym class="acronym">DML</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Data_Manipulation_Language" target="_top">Data
+ Manipulation Language</a>, SQL commands such as <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>
+ </p></dd><dt><span class="term"><acronym class="acronym">DST</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Daylight_saving_time" target="_top">Daylight
+ Saving Time</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ECPG</acronym></span></dt><dd><p>
+ <a class="link" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Embedded C for PostgreSQL</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ESQL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Embedded_SQL" target="_top">Embedded
+ SQL</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">FAQ</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/FAQ" target="_top">Frequently Asked
+ Questions</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">FSM</acronym></span></dt><dd><p>
+ <a class="link" href="storage-fsm.html" title="73.3. Free Space Map">Free Space Map</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GEQO</acronym></span></dt><dd><p>
+ <a class="link" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Genetic Query Optimizer</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GIN</acronym></span></dt><dd><p>
+ <a class="link" href="gin.html" title="Chapter 70. GIN Indexes">Generalized Inverted Index</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GiST</acronym></span></dt><dd><p>
+ <a class="link" href="gist.html" title="Chapter 68. GiST Indexes">Generalized Search Tree</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">Git</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Git_(software)" target="_top">Git</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GMT</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/GMT" target="_top">Greenwich Mean Time</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GSSAPI</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface" target="_top">Generic
+ Security Services Application Programming Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">GUC</acronym></span></dt><dd><p>
+ <a class="link" href="config-setting.html" title="20.1. Setting Parameters">Grand Unified Configuration</a>,
+ the <span class="productname">PostgreSQL</span> subsystem that handles server configuration
+ </p></dd><dt><span class="term"><acronym class="acronym">HBA</acronym></span></dt><dd><p>
+ <a class="link" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Host-Based Authentication</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">HOT</acronym></span></dt><dd><p>
+ <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">Heap-Only Tuples</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">IEC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/International_Electrotechnical_Commission" target="_top">International
+ Electrotechnical Commission</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">IEEE</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://standards.ieee.org/" target="_top">Institute of Electrical and
+ Electronics Engineers</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">IPC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Inter-process_communication" target="_top">Inter-Process
+ Communication</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ISO</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://www.iso.org/home.html" target="_top">International Organization for
+ Standardization</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ISSN</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Issn" target="_top">International Standard
+ Serial Number</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">JDBC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Java_Database_Connectivity" target="_top">Java
+ Database Connectivity</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">JIT</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Just-in-time_compilation" target="_top">Just-in-Time
+ compilation</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">JSON</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://www.json.org" target="_top">JavaScript Object Notation</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">LDAP</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol" target="_top">Lightweight
+ Directory Access Protocol</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">LSN</acronym></span></dt><dd><p>
+ Log Sequence Number, see <a class="link" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type"><code class="type">pg_lsn</code></a>
+ and <a class="link" href="wal-internals.html" title="30.6. WAL Internals">WAL Internals</a>.
+ </p></dd><dt><span class="term"><acronym class="acronym">MITM</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Man-in-the-middle_attack" target="_top">
+ Man-in-the-middle attack</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">MSVC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Visual_C++" target="_top"><span class="productname">Microsoft
+ Visual C</span></a>
+ </p></dd><dt><span class="term"><acronym class="acronym">MVCC</acronym></span></dt><dd><p>
+ <a class="link" href="mvcc.html" title="Chapter 13. Concurrency Control">Multi-Version Concurrency Control</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">NLS</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Internationalization_and_localization" target="_top">National
+ Language Support</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ODBC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Open_Database_Connectivity" target="_top">Open
+ Database Connectivity</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">OID</acronym></span></dt><dd><p>
+ <a class="link" href="datatype-oid.html" title="8.19. Object Identifier Types">Object Identifier</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">OLAP</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Olap" target="_top">Online Analytical
+ Processing</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">OLTP</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/OLTP" target="_top">Online Transaction
+ Processing</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">ORDBMS</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/ORDBMS" target="_top">Object-Relational
+ Database Management System</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">PAM</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules" target="_top">Pluggable
+ Authentication Modules</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">PGSQL</acronym></span></dt><dd><p>
+ <a class="link" href="index.html" title="PostgreSQL 15.5 Documentation"><span class="productname">PostgreSQL</span></a>
+ </p></dd><dt><span class="term"><acronym class="acronym">PGXS</acronym></span></dt><dd><p>
+ <a class="link" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure"><span class="productname">PostgreSQL</span> Extension System</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">PID</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Process_identifier" target="_top">Process Identifier</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">PITR</acronym></span></dt><dd><p>
+ <a class="link" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Point-In-Time
+ Recovery</a> (Continuous Archiving)
+ </p></dd><dt><span class="term"><acronym class="acronym">PL</acronym></span></dt><dd><p>
+ <a class="link" href="server-programming.html" title="Part V. Server Programming">Procedural Languages (server-side)</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">POSIX</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/POSIX" target="_top">Portable Operating
+ System Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">RDBMS</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Relational_database_management_system" target="_top">Relational
+ Database Management System</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">RFC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Request_for_Comments" target="_top">Request For
+ Comments</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SGML</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/SGML" target="_top">Standard Generalized
+ Markup Language</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SNI</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Server_Name_Indication" target="_top">
+ Server Name Indication</a>,
+ <a class="ulink" href="https://tools.ietf.org/html/rfc6066#section-3" target="_top">RFC 6066</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SPI</acronym></span></dt><dd><p>
+ <a class="link" href="spi.html" title="Chapter 47. Server Programming Interface">Server Programming Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SP-GiST</acronym></span></dt><dd><p>
+ <a class="link" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Space-Partitioned Generalized Search Tree</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SQL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/SQL" target="_top">Structured Query Language</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SRF</acronym></span></dt><dd><p>
+ <a class="link" href="xfunc-c.html#XFUNC-C-RETURN-SET" title="38.10.8. Returning Sets">Set-Returning Function</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SSH</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Secure_Shell" target="_top">Secure
+ Shell</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SSL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Secure_Sockets_Layer" target="_top">Secure Sockets Layer</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SSPI</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://msdn.microsoft.com/en-us/library/aa380493%28VS.85%29.aspx" target="_top">Security
+ Support Provider Interface</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">SYSV</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/System_V" target="_top">Unix System V</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">TCP/IP</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Transmission_Control_Protocol" target="_top">Transmission
+ Control Protocol (TCP) / Internet Protocol (IP)</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">TID</acronym></span></dt><dd><p>
+ <a class="link" href="datatype-oid.html" title="8.19. Object Identifier Types">Tuple Identifier</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">TLS</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Transport_Layer_Security" target="_top">
+ Transport Layer Security</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">TOAST</acronym></span></dt><dd><p>
+ <a class="link" href="storage-toast.html" title="73.2. TOAST">The Oversized-Attribute Storage Technique</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">TPC</acronym></span></dt><dd><p>
+ <a class="ulink" href="http://www.tpc.org/" target="_top">Transaction Processing
+ Performance Council</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">URL</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/URL" target="_top">Uniform Resource
+ Locator</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">UTC</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time" target="_top">Coordinated
+ Universal Time</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">UTF</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://www.unicode.org/" target="_top">Unicode Transformation
+ Format</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">UTF8</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Utf8" target="_top">Eight-Bit Unicode
+ Transformation Format</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">UUID</acronym></span></dt><dd><p>
+ <a class="link" href="datatype-uuid.html" title="8.12. UUID Type">Universally Unique Identifier</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">WAL</acronym></span></dt><dd><p>
+ <a class="link" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Write-Ahead Log</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">XID</acronym></span></dt><dd><p>
+ <a class="link" href="datatype-oid.html" title="8.19. Object Identifier Types">Transaction Identifier</a>
+ </p></dd><dt><span class="term"><acronym class="acronym">XML</acronym></span></dt><dd><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/XML" target="_top">Extensible Markup
+ Language</a>
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="limits.html" title="Appendix K. PostgreSQL Limits">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="glossary.html" title="Appendix M. Glossary">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix K. <span class="productname">PostgreSQL</span> Limits </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix M. Glossary</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/admin.html b/doc/src/sgml/html/admin.html
new file mode 100644
index 0000000..3653cc1
--- /dev/null
+++ b/doc/src/sgml/html/admin.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part III. Server Administration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="parallel-safety.html" title="15.4. Parallel Safety" /><link rel="next" href="install-binaries.html" title="Chapter 16. Installation from Binaries" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part III. Server Administration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="parallel-safety.html" title="15.4. Parallel Safety">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-binaries.html" title="Chapter 16. Installation from Binaries">Next</a></td></tr></table><hr /></div><div class="part" id="ADMIN"><div class="titlepage"><div><div><h1 class="title">Part III. Server Administration</h1></div></div></div><div class="partintro" id="id-1.6.2"><div></div><p>
+ This part covers topics that are of interest to a
+ <span class="productname">PostgreSQL</span> database administrator. This includes
+ installation of the software, set up and configuration of the
+ server, management of users and databases, and maintenance tasks.
+ Anyone who runs a <span class="productname">PostgreSQL</span> server, even for
+ personal use, but especially in production, should be familiar
+ with the topics covered in this part.
+ </p><p>
+ The information in this part is arranged approximately in the
+ order in which a new user should read it. But the chapters are
+ self-contained and can be read individually as desired. The
+ information in this part is presented in a narrative fashion in
+ topical units. Readers looking for a complete description of a
+ particular command should see <a class="xref" href="reference.html" title="Part VI. Reference">Part VI</a>.
+ </p><p>
+ The first few chapters are written so they can be understood
+ without prerequisite knowledge, so new users who need to set
+ up their own server can begin their exploration with this part.
+ The rest of this part is about tuning and management; that material
+ assumes that the reader is familiar with the general use of
+ the <span class="productname">PostgreSQL</span> database system. Readers are
+ encouraged to look at <a class="xref" href="tutorial.html" title="Part I. Tutorial">Part I</a> and <a class="xref" href="sql.html" title="Part II. The SQL Language">Part II</a> for additional information.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="install-binaries.html">16. Installation from Binaries</a></span></dt><dt><span class="chapter"><a href="installation.html">17. Installation from Source Code</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-short.html">17.1. Short Version</a></span></dt><dt><span class="sect1"><a href="install-requirements.html">17.2. Requirements</a></span></dt><dt><span class="sect1"><a href="install-getsource.html">17.3. Getting the Source</a></span></dt><dt><span class="sect1"><a href="install-procedure.html">17.4. Installation Procedure</a></span></dt><dt><span class="sect1"><a href="install-post.html">17.5. Post-Installation Setup</a></span></dt><dt><span class="sect1"><a href="supported-platforms.html">17.6. Supported Platforms</a></span></dt><dt><span class="sect1"><a href="installation-platform-notes.html">17.7. Platform-Specific Notes</a></span></dt></dl></dd><dt><span class="chapter"><a href="install-windows.html">18. Installation from Source Code on <span class="productname">Windows</span></a></span></dt><dd><dl><dt><span class="sect1"><a href="install-windows-full.html">18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span></a></span></dt></dl></dd><dt><span class="chapter"><a href="runtime.html">19. Server Setup and Operation</a></span></dt><dd><dl><dt><span class="sect1"><a href="postgres-user.html">19.1. The <span class="productname">PostgreSQL</span> User Account</a></span></dt><dt><span class="sect1"><a href="creating-cluster.html">19.2. Creating a Database Cluster</a></span></dt><dt><span class="sect1"><a href="server-start.html">19.3. Starting the Database Server</a></span></dt><dt><span class="sect1"><a href="kernel-resources.html">19.4. Managing Kernel Resources</a></span></dt><dt><span class="sect1"><a href="server-shutdown.html">19.5. Shutting Down the Server</a></span></dt><dt><span class="sect1"><a href="upgrading.html">19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</a></span></dt><dt><span class="sect1"><a href="preventing-server-spoofing.html">19.7. Preventing Server Spoofing</a></span></dt><dt><span class="sect1"><a href="encryption-options.html">19.8. Encryption Options</a></span></dt><dt><span class="sect1"><a href="ssl-tcp.html">19.9. Secure TCP/IP Connections with SSL</a></span></dt><dt><span class="sect1"><a href="gssapi-enc.html">19.10. Secure TCP/IP Connections with GSSAPI Encryption</a></span></dt><dt><span class="sect1"><a href="ssh-tunnels.html">19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</a></span></dt><dt><span class="sect1"><a href="event-log-registration.html">19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span></a></span></dt></dl></dd><dt><span class="chapter"><a href="runtime-config.html">20. Server Configuration</a></span></dt><dd><dl><dt><span class="sect1"><a href="config-setting.html">20.1. Setting Parameters</a></span></dt><dt><span class="sect1"><a href="runtime-config-file-locations.html">20.2. File Locations</a></span></dt><dt><span class="sect1"><a href="runtime-config-connection.html">20.3. Connections and Authentication</a></span></dt><dt><span class="sect1"><a href="runtime-config-resource.html">20.4. Resource Consumption</a></span></dt><dt><span class="sect1"><a href="runtime-config-wal.html">20.5. Write Ahead Log</a></span></dt><dt><span class="sect1"><a href="runtime-config-replication.html">20.6. Replication</a></span></dt><dt><span class="sect1"><a href="runtime-config-query.html">20.7. Query Planning</a></span></dt><dt><span class="sect1"><a href="runtime-config-logging.html">20.8. Error Reporting and Logging</a></span></dt><dt><span class="sect1"><a href="runtime-config-statistics.html">20.9. Run-time Statistics</a></span></dt><dt><span class="sect1"><a href="runtime-config-autovacuum.html">20.10. Automatic Vacuuming</a></span></dt><dt><span class="sect1"><a href="runtime-config-client.html">20.11. Client Connection Defaults</a></span></dt><dt><span class="sect1"><a href="runtime-config-locks.html">20.12. Lock Management</a></span></dt><dt><span class="sect1"><a href="runtime-config-compatible.html">20.13. Version and Platform Compatibility</a></span></dt><dt><span class="sect1"><a href="runtime-config-error-handling.html">20.14. Error Handling</a></span></dt><dt><span class="sect1"><a href="runtime-config-preset.html">20.15. Preset Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-custom.html">20.16. Customized Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-developer.html">20.17. Developer Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-short.html">20.18. Short Options</a></span></dt></dl></dd><dt><span class="chapter"><a href="client-authentication.html">21. Client Authentication</a></span></dt><dd><dl><dt><span class="sect1"><a href="auth-pg-hba-conf.html">21.1. The <code class="filename">pg_hba.conf</code> File</a></span></dt><dt><span class="sect1"><a href="auth-username-maps.html">21.2. User Name Maps</a></span></dt><dt><span class="sect1"><a href="auth-methods.html">21.3. Authentication Methods</a></span></dt><dt><span class="sect1"><a href="auth-trust.html">21.4. Trust Authentication</a></span></dt><dt><span class="sect1"><a href="auth-password.html">21.5. Password Authentication</a></span></dt><dt><span class="sect1"><a href="gssapi-auth.html">21.6. GSSAPI Authentication</a></span></dt><dt><span class="sect1"><a href="sspi-auth.html">21.7. SSPI Authentication</a></span></dt><dt><span class="sect1"><a href="auth-ident.html">21.8. Ident Authentication</a></span></dt><dt><span class="sect1"><a href="auth-peer.html">21.9. Peer Authentication</a></span></dt><dt><span class="sect1"><a href="auth-ldap.html">21.10. LDAP Authentication</a></span></dt><dt><span class="sect1"><a href="auth-radius.html">21.11. RADIUS Authentication</a></span></dt><dt><span class="sect1"><a href="auth-cert.html">21.12. Certificate Authentication</a></span></dt><dt><span class="sect1"><a href="auth-pam.html">21.13. PAM Authentication</a></span></dt><dt><span class="sect1"><a href="auth-bsd.html">21.14. BSD Authentication</a></span></dt><dt><span class="sect1"><a href="client-authentication-problems.html">21.15. Authentication Problems</a></span></dt></dl></dd><dt><span class="chapter"><a href="user-manag.html">22. Database Roles</a></span></dt><dd><dl><dt><span class="sect1"><a href="database-roles.html">22.1. Database Roles</a></span></dt><dt><span class="sect1"><a href="role-attributes.html">22.2. Role Attributes</a></span></dt><dt><span class="sect1"><a href="role-membership.html">22.3. Role Membership</a></span></dt><dt><span class="sect1"><a href="role-removal.html">22.4. Dropping Roles</a></span></dt><dt><span class="sect1"><a href="predefined-roles.html">22.5. Predefined Roles</a></span></dt><dt><span class="sect1"><a href="perm-functions.html">22.6. Function Security</a></span></dt></dl></dd><dt><span class="chapter"><a href="managing-databases.html">23. Managing Databases</a></span></dt><dd><dl><dt><span class="sect1"><a href="manage-ag-overview.html">23.1. Overview</a></span></dt><dt><span class="sect1"><a href="manage-ag-createdb.html">23.2. Creating a Database</a></span></dt><dt><span class="sect1"><a href="manage-ag-templatedbs.html">23.3. Template Databases</a></span></dt><dt><span class="sect1"><a href="manage-ag-config.html">23.4. Database Configuration</a></span></dt><dt><span class="sect1"><a href="manage-ag-dropdb.html">23.5. Destroying a Database</a></span></dt><dt><span class="sect1"><a href="manage-ag-tablespaces.html">23.6. Tablespaces</a></span></dt></dl></dd><dt><span class="chapter"><a href="charset.html">24. Localization</a></span></dt><dd><dl><dt><span class="sect1"><a href="locale.html">24.1. Locale Support</a></span></dt><dt><span class="sect1"><a href="collation.html">24.2. Collation Support</a></span></dt><dt><span class="sect1"><a href="multibyte.html">24.3. Character Set Support</a></span></dt></dl></dd><dt><span class="chapter"><a href="maintenance.html">25. Routine Database Maintenance Tasks</a></span></dt><dd><dl><dt><span class="sect1"><a href="routine-vacuuming.html">25.1. Routine Vacuuming</a></span></dt><dt><span class="sect1"><a href="routine-reindex.html">25.2. Routine Reindexing</a></span></dt><dt><span class="sect1"><a href="logfile-maintenance.html">25.3. Log File Maintenance</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup.html">26. Backup and Restore</a></span></dt><dd><dl><dt><span class="sect1"><a href="backup-dump.html">26.1. <acronym class="acronym">SQL</acronym> Dump</a></span></dt><dt><span class="sect1"><a href="backup-file.html">26.2. File System Level Backup</a></span></dt><dt><span class="sect1"><a href="continuous-archiving.html">26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</a></span></dt></dl></dd><dt><span class="chapter"><a href="high-availability.html">27. High Availability, Load Balancing, and Replication</a></span></dt><dd><dl><dt><span class="sect1"><a href="different-replication-solutions.html">27.1. Comparison of Different Solutions</a></span></dt><dt><span class="sect1"><a href="warm-standby.html">27.2. Log-Shipping Standby Servers</a></span></dt><dt><span class="sect1"><a href="warm-standby-failover.html">27.3. Failover</a></span></dt><dt><span class="sect1"><a href="hot-standby.html">27.4. Hot Standby</a></span></dt></dl></dd><dt><span class="chapter"><a href="monitoring.html">28. Monitoring Database Activity</a></span></dt><dd><dl><dt><span class="sect1"><a href="monitoring-ps.html">28.1. Standard Unix Tools</a></span></dt><dt><span class="sect1"><a href="monitoring-stats.html">28.2. The Cumulative Statistics System</a></span></dt><dt><span class="sect1"><a href="monitoring-locks.html">28.3. Viewing Locks</a></span></dt><dt><span class="sect1"><a href="progress-reporting.html">28.4. Progress Reporting</a></span></dt><dt><span class="sect1"><a href="dynamic-trace.html">28.5. Dynamic Tracing</a></span></dt></dl></dd><dt><span class="chapter"><a href="diskusage.html">29. Monitoring Disk Usage</a></span></dt><dd><dl><dt><span class="sect1"><a href="disk-usage.html">29.1. Determining Disk Usage</a></span></dt><dt><span class="sect1"><a href="disk-full.html">29.2. Disk Full Failure</a></span></dt></dl></dd><dt><span class="chapter"><a href="wal.html">30. Reliability and the Write-Ahead Log</a></span></dt><dd><dl><dt><span class="sect1"><a href="wal-reliability.html">30.1. Reliability</a></span></dt><dt><span class="sect1"><a href="checksums.html">30.2. Data Checksums</a></span></dt><dt><span class="sect1"><a href="wal-intro.html">30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>)</a></span></dt><dt><span class="sect1"><a href="wal-async-commit.html">30.4. Asynchronous Commit</a></span></dt><dt><span class="sect1"><a href="wal-configuration.html">30.5. <acronym class="acronym">WAL</acronym> Configuration</a></span></dt><dt><span class="sect1"><a href="wal-internals.html">30.6. WAL Internals</a></span></dt></dl></dd><dt><span class="chapter"><a href="logical-replication.html">31. Logical Replication</a></span></dt><dd><dl><dt><span class="sect1"><a href="logical-replication-publication.html">31.1. Publication</a></span></dt><dt><span class="sect1"><a href="logical-replication-subscription.html">31.2. Subscription</a></span></dt><dt><span class="sect1"><a href="logical-replication-row-filter.html">31.3. Row Filters</a></span></dt><dt><span class="sect1"><a href="logical-replication-col-lists.html">31.4. Column Lists</a></span></dt><dt><span class="sect1"><a href="logical-replication-conflicts.html">31.5. Conflicts</a></span></dt><dt><span class="sect1"><a href="logical-replication-restrictions.html">31.6. Restrictions</a></span></dt><dt><span class="sect1"><a href="logical-replication-architecture.html">31.7. Architecture</a></span></dt><dt><span class="sect1"><a href="logical-replication-monitoring.html">31.8. Monitoring</a></span></dt><dt><span class="sect1"><a href="logical-replication-security.html">31.9. Security</a></span></dt><dt><span class="sect1"><a href="logical-replication-config.html">31.10. Configuration Settings</a></span></dt><dt><span class="sect1"><a href="logical-replication-quick-setup.html">31.11. Quick Setup</a></span></dt></dl></dd><dt><span class="chapter"><a href="jit.html">32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</a></span></dt><dd><dl><dt><span class="sect1"><a href="jit-reason.html">32.1. What Is <acronym class="acronym">JIT</acronym> compilation?</a></span></dt><dt><span class="sect1"><a href="jit-decision.html">32.2. When to <acronym class="acronym">JIT</acronym>?</a></span></dt><dt><span class="sect1"><a href="jit-configuration.html">32.3. Configuration</a></span></dt><dt><span class="sect1"><a href="jit-extensibility.html">32.4. Extensibility</a></span></dt></dl></dd><dt><span class="chapter"><a href="regress.html">33. Regression Tests</a></span></dt><dd><dl><dt><span class="sect1"><a href="regress-run.html">33.1. Running the Tests</a></span></dt><dt><span class="sect1"><a href="regress-evaluation.html">33.2. Test Evaluation</a></span></dt><dt><span class="sect1"><a href="regress-variant.html">33.3. Variant Comparison Files</a></span></dt><dt><span class="sect1"><a href="regress-tap.html">33.4. TAP Tests</a></span></dt><dt><span class="sect1"><a href="regress-coverage.html">33.5. Test Coverage Examination</a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel-safety.html" title="15.4. Parallel Safety">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-binaries.html" title="Chapter 16. Installation from Binaries">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.4. Parallel Safety </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. Installation from Binaries</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/adminpack.html b/doc/src/sgml/html/adminpack.html
new file mode 100644
index 0000000..ef27467
--- /dev/null
+++ b/doc/src/sgml/html/adminpack.html
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.1. adminpack</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib.html" title="Appendix F. Additional Supplied Modules" /><link rel="next" href="amcheck.html" title="F.2. amcheck" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.1. adminpack</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib.html" title="Appendix F. Additional Supplied Modules">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="amcheck.html" title="F.2. amcheck">Next</a></td></tr></table><hr /></div><div class="sect1" id="ADMINPACK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.1. adminpack</h2></div></div></div><a id="id-1.11.7.10.2" class="indexterm"></a><p>
+ <code class="filename">adminpack</code> provides a number of support functions which
+ <span class="application">pgAdmin</span> and other administration and management tools can
+ use to provide additional functionality, such as remote management
+ of server log files.
+ Use of all these functions is only allowed to the superuser by default but may be
+ allowed to other users by using the <code class="command">GRANT</code> command.
+ </p><p>
+ The functions shown in <a class="xref" href="adminpack.html#FUNCTIONS-ADMINPACK-TABLE" title="Table F.1. adminpack Functions">Table F.1</a> provide
+ write access to files on the machine hosting the server. (See also the
+ functions in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE-TABLE" title="Table 9.99. Generic File Access Functions">Table 9.99</a>, which
+ provide read-only access.)
+ Only files within the database cluster directory can be accessed, unless the
+ user is a superuser or given privileges of one of the
+ <code class="literal">pg_read_server_files</code> or
+ <code class="literal">pg_write_server_files</code> roles, as appropriate for the
+ function, but either a relative or absolute path is allowable.
+ </p><div class="table" id="FUNCTIONS-ADMINPACK-TABLE"><p class="title"><strong>Table F.1. <code class="filename">adminpack</code> Functions</strong></p><div class="table-contents"><table class="table" summary="adminpack Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_catalog.pg_file_write</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code>, <em class="parameter"><code>data</code></em> <code class="type">text</code>, <em class="parameter"><code>append</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Writes, or appends to, a text file.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_catalog.pg_file_sync</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Flushes a file or directory to disk.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_catalog.pg_file_rename</code> ( <em class="parameter"><code>oldname</code></em> <code class="type">text</code>, <em class="parameter"><code>newname</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>archivename</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Renames a file.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_catalog.pg_file_unlink</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Removes a file.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_catalog.pg_logdir_ls</code> ()
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Lists the log files in the <code class="varname">log_directory</code> directory.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><a id="id-1.11.7.10.6" class="indexterm"></a><p>
+ <code class="function">pg_file_write</code> writes the specified <em class="parameter"><code>data</code></em> into
+ the file named by <em class="parameter"><code>filename</code></em>. If <em class="parameter"><code>append</code></em> is
+ false, the file must not already exist. If <em class="parameter"><code>append</code></em> is true,
+ the file can already exist, and will be appended to if so.
+ Returns the number of bytes written.
+ </p><a id="id-1.11.7.10.8" class="indexterm"></a><p>
+ <code class="function">pg_file_sync</code> fsyncs the specified file or directory
+ named by <em class="parameter"><code>filename</code></em>. An error is thrown
+ on failure (e.g., the specified file is not present). Note that
+ <a class="xref" href="runtime-config-error-handling.html#GUC-DATA-SYNC-RETRY">data_sync_retry</a> has no effect on this function,
+ and therefore a PANIC-level error will not be raised even on failure to
+ flush database files.
+ </p><a id="id-1.11.7.10.10" class="indexterm"></a><p>
+ <code class="function">pg_file_rename</code> renames a file. If <em class="parameter"><code>archivename</code></em>
+ is omitted or NULL, it simply renames <em class="parameter"><code>oldname</code></em>
+ to <em class="parameter"><code>newname</code></em> (which must not already exist).
+ If <em class="parameter"><code>archivename</code></em> is provided, it first
+ renames <em class="parameter"><code>newname</code></em> to <em class="parameter"><code>archivename</code></em> (which must
+ not already exist), and then renames <em class="parameter"><code>oldname</code></em>
+ to <em class="parameter"><code>newname</code></em>. In event of failure of the second rename step,
+ it will try to rename <em class="parameter"><code>archivename</code></em> back
+ to <em class="parameter"><code>newname</code></em> before reporting the error.
+ Returns true on success, false if the source file(s) are not present or
+ not writable; other cases throw errors.
+ </p><a id="id-1.11.7.10.12" class="indexterm"></a><p>
+ <code class="function">pg_file_unlink</code> removes the specified file.
+ Returns true on success, false if the specified file is not present
+ or the <code class="function">unlink()</code> call fails; other cases throw errors.
+ </p><a id="id-1.11.7.10.14" class="indexterm"></a><p>
+ <code class="function">pg_logdir_ls</code> returns the start timestamps and path
+ names of all the log files in the <a class="xref" href="runtime-config-logging.html#GUC-LOG-DIRECTORY">log_directory</a>
+ directory. The <a class="xref" href="runtime-config-logging.html#GUC-LOG-FILENAME">log_filename</a> parameter must have its
+ default setting (<code class="literal">postgresql-%Y-%m-%d_%H%M%S.log</code>) to use this
+ function.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib.html" title="Appendix F. Additional Supplied Modules">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="amcheck.html" title="F.2. amcheck">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix F. Additional Supplied Modules </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.2. amcheck</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/amcheck.html b/doc/src/sgml/html/amcheck.html
new file mode 100644
index 0000000..97a929a
--- /dev/null
+++ b/doc/src/sgml/html/amcheck.html
@@ -0,0 +1,377 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.2. amcheck</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="adminpack.html" title="F.1. adminpack" /><link rel="next" href="auth-delay.html" title="F.3. auth_delay" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.2. amcheck</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="adminpack.html" title="F.1. adminpack">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-delay.html" title="F.3. auth_delay">Next</a></td></tr></table><hr /></div><div class="sect1" id="AMCHECK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.2. amcheck</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.8">F.2.1. Functions</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.9">F.2.2. Optional <em class="parameter"><code>heapallindexed</code></em> Verification</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.10">F.2.3. Using <code class="filename">amcheck</code> Effectively</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.11">F.2.4. Repairing Corruption</a></span></dt></dl></div><a id="id-1.11.7.11.2" class="indexterm"></a><p>
+ The <code class="filename">amcheck</code> module provides functions that allow you to
+ verify the logical consistency of the structure of relations.
+ </p><p>
+ The B-Tree checking functions verify various <span class="emphasis"><em>invariants</em></span> in the
+ structure of the representation of particular relations. The
+ correctness of the access method functions behind index scans and
+ other important operations relies on these invariants always
+ holding. For example, certain functions verify, among other things,
+ that all B-Tree pages have items in <span class="quote">“<span class="quote">logical</span>”</span> order (e.g.,
+ for B-Tree indexes on <code class="type">text</code>, index tuples should be in
+ collated lexical order). If that particular invariant somehow fails
+ to hold, we can expect binary searches on the affected page to
+ incorrectly guide index scans, resulting in wrong answers to SQL
+ queries. If the structure appears to be valid, no error is raised.
+ </p><p>
+ Verification is performed using the same procedures as those used by
+ index scans themselves, which may be user-defined operator class
+ code. For example, B-Tree index verification relies on comparisons
+ made with one or more B-Tree support function 1 routines. See <a class="xref" href="xindex.html#XINDEX-SUPPORT" title="38.16.3. Index Method Support Routines">Section 38.16.3</a> for details of operator class support
+ functions.
+ </p><p>
+ Unlike the B-Tree checking functions which report corruption by raising
+ errors, the heap checking function <code class="function">verify_heapam</code> checks
+ a table and attempts to return a set of rows, one row per corruption
+ detected. Despite this, if facilities that
+ <code class="function">verify_heapam</code> relies upon are themselves corrupted, the
+ function may be unable to continue and may instead raise an error.
+ </p><p>
+ Permission to execute <code class="filename">amcheck</code> functions may be granted
+ to non-superusers, but before granting such permissions careful consideration
+ should be given to data security and privacy concerns. Although the
+ corruption reports generated by these functions do not focus on the contents
+ of the corrupted data so much as on the structure of that data and the nature
+ of the corruptions found, an attacker who gains permission to execute these
+ functions, particularly if the attacker can also induce corruption, might be
+ able to infer something of the data itself from such messages.
+ </p><div class="sect2" id="id-1.11.7.11.8"><div class="titlepage"><div><div><h3 class="title">F.2.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">bt_index_check(index regclass, heapallindexed boolean) returns void</code>
+ <a id="id-1.11.7.11.8.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">bt_index_check</code> tests that its target, a
+ B-Tree index, respects a variety of invariants. Example usage:
+</p><pre class="screen">
+test=# SELECT bt_index_check(index =&gt; c.oid, heapallindexed =&gt; i.indisunique),
+ c.relname,
+ c.relpages
+FROM pg_index i
+JOIN pg_opclass op ON i.indclass[0] = op.oid
+JOIN pg_am am ON op.opcmethod = am.oid
+JOIN pg_class c ON i.indexrelid = c.oid
+JOIN pg_namespace n ON c.relnamespace = n.oid
+WHERE am.amname = 'btree' AND n.nspname = 'pg_catalog'
+-- Don't check temp tables, which may be from another session:
+AND c.relpersistence != 't'
+-- Function may throw an error when this is omitted:
+AND c.relkind = 'i' AND i.indisready AND i.indisvalid
+ORDER BY c.relpages DESC LIMIT 10;
+ bt_index_check | relname | relpages
+----------------+---------------------------------+----------
+ | pg_depend_reference_index | 43
+ | pg_depend_depender_index | 40
+ | pg_proc_proname_args_nsp_index | 31
+ | pg_description_o_c_o_index | 21
+ | pg_attribute_relid_attnam_index | 14
+ | pg_proc_oid_index | 10
+ | pg_attribute_relid_attnum_index | 9
+ | pg_amproc_fam_proc_index | 5
+ | pg_amop_opr_fam_index | 5
+ | pg_amop_fam_strat_index | 5
+(10 rows)
+</pre><p>
+ This example shows a session that performs verification of the
+ 10 largest catalog indexes in the database <span class="quote">“<span class="quote">test</span>”</span>.
+ Verification of the presence of heap tuples as index tuples is
+ requested for the subset that are unique indexes. Since no
+ error is raised, all indexes tested appear to be logically
+ consistent. Naturally, this query could easily be changed to
+ call <code class="function">bt_index_check</code> for every index in the
+ database where verification is supported.
+ </p><p>
+ <code class="function">bt_index_check</code> acquires an <code class="literal">AccessShareLock</code>
+ on the target index and the heap relation it belongs to. This lock mode
+ is the same lock mode acquired on relations by simple
+ <code class="literal">SELECT</code> statements.
+ <code class="function">bt_index_check</code> does not verify invariants
+ that span child/parent relationships, but will verify the
+ presence of all heap tuples as index tuples within the index
+ when <em class="parameter"><code>heapallindexed</code></em> is
+ <code class="literal">true</code>. When a routine, lightweight test for
+ corruption is required in a live production environment, using
+ <code class="function">bt_index_check</code> often provides the best
+ trade-off between thoroughness of verification and limiting the
+ impact on application performance and availability.
+ </p></dd><dt><span class="term">
+ <code class="function">bt_index_parent_check(index regclass, heapallindexed boolean, rootdescend boolean) returns void</code>
+ <a id="id-1.11.7.11.8.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">bt_index_parent_check</code> tests that its
+ target, a B-Tree index, respects a variety of invariants.
+ Optionally, when the <em class="parameter"><code>heapallindexed</code></em>
+ argument is <code class="literal">true</code>, the function verifies the
+ presence of all heap tuples that should be found within the
+ index. When the optional <em class="parameter"><code>rootdescend</code></em>
+ argument is <code class="literal">true</code>, verification re-finds
+ tuples on the leaf level by performing a new search from the
+ root page for each tuple. The checks that can be performed by
+ <code class="function">bt_index_parent_check</code> are a superset of the
+ checks that can be performed by <code class="function">bt_index_check</code>.
+ <code class="function">bt_index_parent_check</code> can be thought of as
+ a more thorough variant of <code class="function">bt_index_check</code>:
+ unlike <code class="function">bt_index_check</code>,
+ <code class="function">bt_index_parent_check</code> also checks
+ invariants that span parent/child relationships, including checking
+ that there are no missing downlinks in the index structure.
+ <code class="function">bt_index_parent_check</code> follows the general
+ convention of raising an error if it finds a logical
+ inconsistency or other problem.
+ </p><p>
+ A <code class="literal">ShareLock</code> is required on the target index by
+ <code class="function">bt_index_parent_check</code> (a
+ <code class="literal">ShareLock</code> is also acquired on the heap relation).
+ These locks prevent concurrent data modification from
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code>
+ commands. The locks also prevent the underlying relation from
+ being concurrently processed by <code class="command">VACUUM</code>, as well as
+ all other utility commands. Note that the function holds locks
+ only while running, not for the entire transaction.
+ </p><p>
+ <code class="function">bt_index_parent_check</code>'s additional
+ verification is more likely to detect various pathological
+ cases. These cases may involve an incorrectly implemented
+ B-Tree operator class used by the index that is checked, or,
+ hypothetically, undiscovered bugs in the underlying B-Tree index
+ access method code. Note that
+ <code class="function">bt_index_parent_check</code> cannot be used when
+ hot standby mode is enabled (i.e., on read-only physical
+ replicas), unlike <code class="function">bt_index_check</code>.
+ </p></dd></dl></div><div class="tip"><h3 class="title">Tip</h3><p>
+ <code class="function">bt_index_check</code> and
+ <code class="function">bt_index_parent_check</code> both output log
+ messages about the verification process at
+ <code class="literal">DEBUG1</code> and <code class="literal">DEBUG2</code> severity
+ levels. These messages provide detailed information about the
+ verification process that may be of interest to
+ <span class="productname">PostgreSQL</span> developers. Advanced users
+ may also find this information helpful, since it provides
+ additional context should verification actually detect an
+ inconsistency. Running:
+</p><pre class="programlisting">
+SET client_min_messages = DEBUG1;
+</pre><p>
+ in an interactive <span class="application">psql</span> session before
+ running a verification query will display messages about the
+ progress of verification with a manageable level of detail.
+ </p></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">
+ verify_heapam(relation regclass,
+ on_error_stop boolean,
+ check_toast boolean,
+ skip text,
+ startblock bigint,
+ endblock bigint,
+ blkno OUT bigint,
+ offnum OUT integer,
+ attnum OUT integer,
+ msg OUT text)
+ returns setof record
+ </code>
+ </span></dt><dd><p>
+ Checks a table, sequence, or materialized view for structural corruption,
+ where pages in the relation contain data that is invalidly formatted, and
+ for logical corruption, where pages are structurally valid but
+ inconsistent with the rest of the database cluster.
+ </p><p>
+ The following optional arguments are recognized:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">on_error_stop</code></span></dt><dd><p>
+ If true, corruption checking stops at the end of the first block in
+ which any corruptions are found.
+ </p><p>
+ Defaults to false.
+ </p></dd><dt><span class="term"><code class="literal">check_toast</code></span></dt><dd><p>
+ If true, toasted values are checked against the target relation's
+ TOAST table.
+ </p><p>
+ This option is known to be slow. Also, if the toast table or its
+ index is corrupt, checking it against toast values could conceivably
+ crash the server, although in many cases this would just produce an
+ error.
+ </p><p>
+ Defaults to false.
+ </p></dd><dt><span class="term"><code class="literal">skip</code></span></dt><dd><p>
+ If not <code class="literal">none</code>, corruption checking skips blocks that
+ are marked as all-visible or all-frozen, as specified.
+ Valid options are <code class="literal">all-visible</code>,
+ <code class="literal">all-frozen</code> and <code class="literal">none</code>.
+ </p><p>
+ Defaults to <code class="literal">none</code>.
+ </p></dd><dt><span class="term"><code class="literal">startblock</code></span></dt><dd><p>
+ If specified, corruption checking begins at the specified block,
+ skipping all previous blocks. It is an error to specify a
+ <em class="parameter"><code>startblock</code></em> outside the range of blocks in the
+ target table.
+ </p><p>
+ By default, checking begins at the first block.
+ </p></dd><dt><span class="term"><code class="literal">endblock</code></span></dt><dd><p>
+ If specified, corruption checking ends at the specified block,
+ skipping all remaining blocks. It is an error to specify an
+ <em class="parameter"><code>endblock</code></em> outside the range of blocks in the target
+ table.
+ </p><p>
+ By default, all blocks are checked.
+ </p></dd></dl></div><p>
+ For each corruption detected, <code class="function">verify_heapam</code> returns
+ a row with the following columns:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">blkno</code></span></dt><dd><p>
+ The number of the block containing the corrupt page.
+ </p></dd><dt><span class="term"><code class="literal">offnum</code></span></dt><dd><p>
+ The OffsetNumber of the corrupt tuple.
+ </p></dd><dt><span class="term"><code class="literal">attnum</code></span></dt><dd><p>
+ The attribute number of the corrupt column in the tuple, if the
+ corruption is specific to a column and not the tuple as a whole.
+ </p></dd><dt><span class="term"><code class="literal">msg</code></span></dt><dd><p>
+ A message describing the problem detected.
+ </p></dd></dl></div></dd></dl></div></div><div class="sect2" id="id-1.11.7.11.9"><div class="titlepage"><div><div><h3 class="title">F.2.2. Optional <em class="parameter"><code>heapallindexed</code></em> Verification</h3></div></div></div><p>
+ When the <em class="parameter"><code>heapallindexed</code></em> argument to B-Tree
+ verification functions is <code class="literal">true</code>, an additional
+ phase of verification is performed against the table associated with
+ the target index relation. This consists of a <span class="quote">“<span class="quote">dummy</span>”</span>
+ <code class="command">CREATE INDEX</code> operation, which checks for the
+ presence of all hypothetical new index tuples against a temporary,
+ in-memory summarizing structure (this is built when needed during
+ the basic first phase of verification). The summarizing structure
+ <span class="quote">“<span class="quote">fingerprints</span>”</span> every tuple found within the target
+ index. The high level principle behind
+ <em class="parameter"><code>heapallindexed</code></em> verification is that a new
+ index that is equivalent to the existing, target index must only
+ have entries that can be found in the existing structure.
+ </p><p>
+ The additional <em class="parameter"><code>heapallindexed</code></em> phase adds
+ significant overhead: verification will typically take several times
+ longer. However, there is no change to the relation-level locks
+ acquired when <em class="parameter"><code>heapallindexed</code></em> verification is
+ performed.
+ </p><p>
+ The summarizing structure is bound in size by
+ <code class="varname">maintenance_work_mem</code>. In order to ensure that
+ there is no more than a 2% probability of failure to detect an
+ inconsistency for each heap tuple that should be represented in the
+ index, approximately 2 bytes of memory are needed per tuple. As
+ less memory is made available per tuple, the probability of missing
+ an inconsistency slowly increases. This approach limits the
+ overhead of verification significantly, while only slightly reducing
+ the probability of detecting a problem, especially for installations
+ where verification is treated as a routine maintenance task. Any
+ single absent or malformed tuple has a new opportunity to be
+ detected with each new verification attempt.
+ </p></div><div class="sect2" id="id-1.11.7.11.10"><div class="titlepage"><div><div><h3 class="title">F.2.3. Using <code class="filename">amcheck</code> Effectively</h3></div></div></div><p>
+ <code class="filename">amcheck</code> can be effective at detecting various types of
+ failure modes that <a class="link" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS"><span class="application">data
+ checksums</span></a> will fail to catch. These include:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Structural inconsistencies caused by incorrect operator class
+ implementations.
+ </p><p>
+ This includes issues caused by the comparison rules of operating
+ system collations changing. Comparisons of datums of a collatable
+ type like <code class="type">text</code> must be immutable (just as all
+ comparisons used for B-Tree index scans must be immutable), which
+ implies that operating system collation rules must never change.
+ Though rare, updates to operating system collation rules can
+ cause these issues. More commonly, an inconsistency in the
+ collation order between a primary server and a standby server is
+ implicated, possibly because the <span class="emphasis"><em>major</em></span> operating
+ system version in use is inconsistent. Such inconsistencies will
+ generally only arise on standby servers, and so can generally
+ only be detected on standby servers.
+ </p><p>
+ If a problem like this arises, it may not affect each individual
+ index that is ordered using an affected collation, simply because
+ <span class="emphasis"><em>indexed</em></span> values might happen to have the same
+ absolute ordering regardless of the behavioral inconsistency. See
+ <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> and <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a> for
+ further details about how <span class="productname">PostgreSQL</span> uses
+ operating system locales and collations.
+ </p></li><li class="listitem"><p>
+ Structural inconsistencies between indexes and the heap relations
+ that are indexed (when <em class="parameter"><code>heapallindexed</code></em>
+ verification is performed).
+ </p><p>
+ There is no cross-checking of indexes against their heap relation
+ during normal operation. Symptoms of heap corruption can be subtle.
+ </p></li><li class="listitem"><p>
+ Corruption caused by hypothetical undiscovered bugs in the
+ underlying <span class="productname">PostgreSQL</span> access method
+ code, sort code, or transaction management code.
+ </p><p>
+ Automatic verification of the structural integrity of indexes
+ plays a role in the general testing of new or proposed
+ <span class="productname">PostgreSQL</span> features that could plausibly allow a
+ logical inconsistency to be introduced. Verification of table
+ structure and associated visibility and transaction status
+ information plays a similar role. One obvious testing strategy
+ is to call <code class="filename">amcheck</code> functions continuously
+ when running the standard regression tests. See <a class="xref" href="regress-run.html" title="33.1. Running the Tests">Section 33.1</a> for details on running the tests.
+ </p></li><li class="listitem"><p>
+ File system or storage subsystem faults where checksums happen to
+ simply not be enabled.
+ </p><p>
+ Note that <code class="filename">amcheck</code> examines a page as represented in some
+ shared memory buffer at the time of verification if there is only a
+ shared buffer hit when accessing the block. Consequently,
+ <code class="filename">amcheck</code> does not necessarily examine data read from the
+ file system at the time of verification. Note that when checksums are
+ enabled, <code class="filename">amcheck</code> may raise an error due to a checksum
+ failure when a corrupt block is read into a buffer.
+ </p></li><li class="listitem"><p>
+ Corruption caused by faulty RAM, or the broader memory subsystem.
+ </p><p>
+ <span class="productname">PostgreSQL</span> does not protect against correctable
+ memory errors and it is assumed you will operate using RAM that
+ uses industry standard Error Correcting Codes (ECC) or better
+ protection. However, ECC memory is typically only immune to
+ single-bit errors, and should not be assumed to provide
+ <span class="emphasis"><em>absolute</em></span> protection against failures that
+ result in memory corruption.
+ </p><p>
+ When <em class="parameter"><code>heapallindexed</code></em> verification is
+ performed, there is generally a greatly increased chance of
+ detecting single-bit errors, since strict binary equality is
+ tested, and the indexed attributes within the heap are tested.
+ </p></li></ul></div><p>
+ </p><p>
+ Structural corruption can happen due to faulty storage hardware, or
+ relation files being overwritten or modified by unrelated software.
+ This kind of corruption can also be detected with
+ <a class="link" href="checksums.html" title="30.2. Data Checksums"><span class="application">data page
+ checksums</span></a>.
+ </p><p>
+ Relation pages which are correctly formatted, internally consistent, and
+ correct relative to their own internal checksums may still contain
+ logical corruption. As such, this kind of corruption cannot be detected
+ with <span class="application">checksums</span>. Examples include toasted
+ values in the main table which lack a corresponding entry in the toast
+ table, and tuples in the main table with a Transaction ID that is older
+ than the oldest valid Transaction ID in the database or cluster.
+ </p><p>
+ Multiple causes of logical corruption have been observed in production
+ systems, including bugs in the <span class="productname">PostgreSQL</span>
+ server software, faulty and ill-conceived backup and restore tools, and
+ user error.
+ </p><p>
+ Corrupt relations are most concerning in live production environments,
+ precisely the same environments where high risk activities are least
+ welcome. For this reason, <code class="function">verify_heapam</code> has been
+ designed to diagnose corruption without undue risk. It cannot guard
+ against all causes of backend crashes, as even executing the calling
+ query could be unsafe on a badly corrupted system. Access to <a class="link" href="catalogs-overview.html" title="53.1. Overview">catalog tables</a> is performed and could
+ be problematic if the catalogs themselves are corrupted.
+ </p><p>
+ In general, <code class="filename">amcheck</code> can only prove the presence of
+ corruption; it cannot prove its absence.
+ </p></div><div class="sect2" id="id-1.11.7.11.11"><div class="titlepage"><div><div><h3 class="title">F.2.4. Repairing Corruption</h3></div></div></div><p>
+ No error concerning corruption raised by <code class="filename">amcheck</code> should
+ ever be a false positive. <code class="filename">amcheck</code> raises
+ errors in the event of conditions that, by definition, should never
+ happen, and so careful analysis of <code class="filename">amcheck</code>
+ errors is often required.
+ </p><p>
+ There is no general method of repairing problems that
+ <code class="filename">amcheck</code> detects. An explanation for the root cause of
+ an invariant violation should be sought. <a class="xref" href="pageinspect.html" title="F.25. pageinspect">pageinspect</a> may play a useful role in diagnosing
+ corruption that <code class="filename">amcheck</code> detects. A <code class="command">REINDEX</code>
+ may not be effective in repairing corruption.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adminpack.html" title="F.1. adminpack">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-delay.html" title="F.3. auth_delay">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.1. adminpack </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.3. auth_delay</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-clusterdb.html b/doc/src/sgml/html/app-clusterdb.html
new file mode 100644
index 0000000..83df6df
--- /dev/null
+++ b/doc/src/sgml/html/app-clusterdb.html
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>clusterdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="reference-client.html" title="PostgreSQL Client Applications" /><link rel="next" href="app-createdb.html" title="createdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">clusterdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="reference-client.html" title="PostgreSQL Client Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-createdb.html" title="createdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-CLUSTERDB"><div class="titlepage"></div><a id="id-1.9.4.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">clusterdb</span></span></h2><p>clusterdb — cluster a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.3.4.1"><code class="command">clusterdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [ <code class="option">--verbose</code> | <code class="option">-v</code> ]
+ [
+ <code class="option">--table</code> | <code class="option">-t</code>
+ <em class="replaceable"><code>table</code></em>
+ ]
+ ... [<em class="replaceable"><code>dbname</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.4.3.4.2"><code class="command">clusterdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [ <code class="option">--verbose</code> | <code class="option">-v</code> ] <code class="option">--all</code> | <code class="option">-a</code> </p></div></div><div class="refsect1" id="id-1.9.4.3.5"><h2>Description</h2><p>
+ <span class="application">clusterdb</span> is a utility for reclustering tables
+ in a <span class="productname">PostgreSQL</span> database. It finds tables
+ that have previously been clustered, and clusters them again on the same
+ index that was last used. Tables that have never been clustered are not
+ affected.
+ </p><p>
+ <span class="application">clusterdb</span> is a wrapper around the SQL
+ command <a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a>.
+ There is no effective difference between clustering databases via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.3.6"><h2>Options</h2><p>
+ <span class="application">clusterdb</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
+ Cluster all databases.
+ </p></dd><dt><span class="term"><code class="option">[<span class="optional">-d</span>] <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">[<span class="optional">--dbname=</span>]<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to be clustered,
+ when <code class="option">-a</code>/<code class="option">--all</code> is not used.
+ If this is not specified, the database name is read
+ from the environment variable <code class="envar">PGDATABASE</code>. If
+ that is not set, the user name specified for the connection is
+ used. The <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>. If so,
+ connection string parameters will override any conflicting command
+ line options.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">clusterdb</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Do not display progress messages.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>table</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>table</code></em></code></span></dt><dd><p>
+ Cluster <em class="replaceable"><code>table</code></em> only.
+ Multiple tables can be clustered by writing multiple
+ <code class="option">-t</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Print detailed information during processing.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">clusterdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">clusterdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">clusterdb</span> also accepts
+ the following command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">clusterdb</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">clusterdb</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">clusterdb</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to to discover which
+ databases should be clustered,
+ when <code class="option">-a</code>/<code class="option">--all</code> is used.
+ If not specified, the <code class="literal">postgres</code> database will be used,
+ or if that does not exist, <code class="literal">template1</code> will be used.
+ This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
+ string</a>. If so, connection string parameters will override any
+ conflicting command line options. Also, connection string parameters
+ other than the database name itself will be re-used when connecting
+ to other databases.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.3.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.3.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.3.9"><h2>Examples</h2><p>
+ To cluster the database <code class="literal">test</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>clusterdb test</code></strong>
+</pre><p>
+ </p><p>
+ To cluster a single table
+ <code class="literal">foo</code> in a database named
+ <code class="literal">xyzzy</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>clusterdb --table=foo xyzzy</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.3.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reference-client.html" title="PostgreSQL Client Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-createdb.html" title="createdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostgreSQL Client Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">createdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-createdb.html b/doc/src/sgml/html/app-createdb.html
new file mode 100644
index 0000000..aad42a6
--- /dev/null
+++ b/doc/src/sgml/html/app-createdb.html
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>createdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-clusterdb.html" title="clusterdb" /><link rel="next" href="app-createuser.html" title="createuser" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">createdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-clusterdb.html" title="clusterdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-createuser.html" title="createuser">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-CREATEDB"><div class="titlepage"></div><a id="id-1.9.4.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">createdb</span></span></h2><p>createdb — create a new <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.4.4.1"><code class="command">createdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>
+ [<em class="replaceable"><code>description</code></em>]]</p></div></div><div class="refsect1" id="R1-APP-CREATEDB-1"><h2>Description</h2><p>
+ <span class="application">createdb</span> creates a new <span class="productname">PostgreSQL</span>
+ database.
+ </p><p>
+ Normally, the database user who executes this command becomes the owner of
+ the new database.
+ However, a different owner can be specified via the <code class="option">-O</code>
+ option, if the executing user has appropriate privileges.
+ </p><p>
+ <span class="application">createdb</span> is a wrapper around the
+ <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>.
+ There is no effective difference between creating databases via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.4.6"><h2>Options</h2><p>
+ <span class="application">createdb</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
+ Specifies the name of the database to be created. The name must be
+ unique among all <span class="productname">PostgreSQL</span> databases in this cluster.
+ The default is to create a database with the same name as the
+ current system user.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>description</code></em></span></dt><dd><p>
+ Specifies a comment to be associated with the newly created
+ database.
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>tablespace</code></em></code><br /></span><span class="term"><code class="option">--tablespace=<em class="replaceable"><code>tablespace</code></em></code></span></dt><dd><p>
+ Specifies the default tablespace for the database. (This name
+ is processed as a double-quoted identifier.)
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">createdb</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
+ Specifies the character encoding scheme to be used in this
+ database. The character sets supported by the
+ <span class="productname">PostgreSQL</span> server are described in
+ <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
+ </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the locale to be used in this database. This is equivalent
+ to specifying both <code class="option">--lc-collate</code> and <code class="option">--lc-ctype</code>.
+ </p></dd><dt><span class="term"><code class="option">--lc-collate=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the LC_COLLATE setting to be used in this database.
+ </p></dd><dt><span class="term"><code class="option">--lc-ctype=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the LC_CTYPE setting to be used in this database.
+ </p></dd><dt><span class="term"><code class="option">--icu-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the ICU locale ID to be used in this database, if the
+ ICU locale provider is selected.
+ </p></dd><dt><span class="term"><code class="option">--locale-provider={<code class="literal">libc</code>|<code class="literal">icu</code>}</code></span></dt><dd><p>
+ Specifies the locale provider for the database's default collation.
+ </p></dd><dt><span class="term"><code class="option">-O <em class="replaceable"><code>owner</code></em></code><br /></span><span class="term"><code class="option">--owner=<em class="replaceable"><code>owner</code></em></code></span></dt><dd><p>
+ Specifies the database user who will own the new database.
+ (This name is processed as a double-quoted identifier.)
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>template</code></em></code><br /></span><span class="term"><code class="option">--strategy=<em class="replaceable"><code>strategy</code></em></code></span></dt><dd><p>
+ Specifies the database creation strategy. See
+ <a class="xref" href="sql-createdatabase.html#CREATE-DATABASE-STRATEGY">CREATE DATABASE STRATEGY</a> for more details.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>template</code></em></code><br /></span><span class="term"><code class="option">--template=<em class="replaceable"><code>template</code></em></code></span></dt><dd><p>
+ Specifies the template database from which to build this
+ database. (This name is processed as a double-quoted identifier.)
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">createdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">createdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ The options <code class="option">-D</code>, <code class="option">-l</code>, <code class="option">-E</code>,
+ <code class="option">-O</code>, and
+ <code class="option">-T</code> correspond to options of the underlying
+ SQL command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>; see there for more information
+ about them.
+ </p><p>
+ <span class="application">createdb</span> also accepts the following
+ command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server is running. If the value begins with a slash, it is used
+ as the directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or the local Unix domain socket file
+ extension on which the server is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">createdb</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">createdb</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">createdb</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to when creating the
+ new database. If not specified, the <code class="literal">postgres</code>
+ database will be used; if that does not exist (or if it is the name
+ of the new database being created), <code class="literal">template1</code> will
+ be used.
+ This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
+ string</a>. If so, connection string parameters will override any
+ conflicting command line options.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.4.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code></span></dt><dd><p>
+ If set, the name of the database to create, unless overridden on
+ the command line.
+ </p></dd><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters. <code class="envar">PGUSER</code> also
+ determines the name of the database to create, if it is not
+ specified on the command line or by <code class="envar">PGDATABASE</code>.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.4.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.4.9"><h2>Examples</h2><p>
+ To create the database <code class="literal">demo</code> using the default
+ database server:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createdb demo</code></strong>
+</pre><p>
+ </p><p>
+ To create the database <code class="literal">demo</code> using the
+ server on host <code class="literal">eden</code>, port 5000, using the
+ <code class="literal">template0</code> template database, here is the
+ command-line command and the underlying SQL command:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createdb -p 5000 -h eden -T template0 -e demo</code></strong>
+<code class="computeroutput">CREATE DATABASE demo TEMPLATE template0;</code>
+</pre></div><div class="refsect1" id="id-1.9.4.4.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-dropdb.html" title="dropdb"><span class="refentrytitle"><span class="application">dropdb</span></span></a>, <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-clusterdb.html" title="clusterdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-createuser.html" title="createuser">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">clusterdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">createuser</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-createuser.html b/doc/src/sgml/html/app-createuser.html
new file mode 100644
index 0000000..3e4d5be
--- /dev/null
+++ b/doc/src/sgml/html/app-createuser.html
@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>createuser</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-createdb.html" title="createdb" /><link rel="next" href="app-dropdb.html" title="dropdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">createuser</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-createdb.html" title="createdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-dropdb.html" title="dropdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-CREATEUSER"><div class="titlepage"></div><a id="id-1.9.4.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">createuser</span></span></h2><p>createuser — define a new <span class="productname">PostgreSQL</span> user account</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.5.4.1"><code class="command">createuser</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>username</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.5.5"><h2>Description</h2><p>
+ <span class="application">createuser</span> creates a
+ new <span class="productname">PostgreSQL</span> user (or more precisely, a role).
+ Only superusers and users with <code class="literal">CREATEROLE</code> privilege can create
+ new users, so <span class="application">createuser</span> must be
+ invoked by someone who can connect as a superuser or a user with
+ <code class="literal">CREATEROLE</code> privilege.
+ </p><p>
+ If you wish to create a role with the <code class="literal">SUPERUSER</code>,
+ <code class="literal">REPLICATION</code>, or <code class="literal">BYPASSRLS</code> privilege,
+ you must connect as a superuser, not merely with
+ <code class="literal">CREATEROLE</code> privilege.
+ Being a superuser implies the ability to bypass all access permission
+ checks within the database, so superuser access should not be granted
+ lightly. <code class="literal">CREATEROLE</code> also conveys
+ <a class="link" href="role-attributes.html#ROLE-CREATION">very extensive privileges</a>.
+ </p><p>
+ <span class="application">createuser</span> is a wrapper around the
+ <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a>.
+ There is no effective difference between creating users via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.5.6"><h2>Options</h2><p>
+ <span class="application">createuser</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>username</code></em></span></dt><dd><p>
+ Specifies the name of the <span class="productname">PostgreSQL</span> user
+ to be created.
+ This name must be different from all existing roles in this
+ <span class="productname">PostgreSQL</span> installation.
+ </p></dd><dt><span class="term"><code class="option">-c <em class="replaceable"><code>number</code></em></code><br /></span><span class="term"><code class="option">--connection-limit=<em class="replaceable"><code>number</code></em></code></span></dt><dd><p>
+ Set a maximum number of connections for the new user.
+ The default is to set no limit.
+ </p></dd><dt><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--createdb</code></span></dt><dd><p>
+ The new user will be allowed to create databases.
+ </p></dd><dt><span class="term"><code class="option">-D</code><br /></span><span class="term"><code class="option">--no-createdb</code></span></dt><dd><p>
+ The new user will not be allowed to create databases. This is the
+ default.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">createuser</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-E</code><br /></span><span class="term"><code class="option">--encrypted</code></span></dt><dd><p>
+ This option is obsolete but still accepted for backward
+ compatibility.
+ </p></dd><dt><span class="term"><code class="option">-g <em class="replaceable"><code>role</code></em></code><br /></span><span class="term"><code class="option">--role=<em class="replaceable"><code>role</code></em></code></span></dt><dd><p>
+ Indicates role to which this role will be added immediately as a new
+ member. Multiple roles to which this role will be added as a member
+ can be specified by writing multiple
+ <code class="option">-g</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--inherit</code></span></dt><dd><p>
+ The new role will automatically inherit privileges of roles
+ it is a member of.
+ This is the default.
+ </p></dd><dt><span class="term"><code class="option">-I</code><br /></span><span class="term"><code class="option">--no-inherit</code></span></dt><dd><p>
+ The new role will not automatically inherit privileges of roles
+ it is a member of.
+ </p></dd><dt><span class="term"><code class="option">--interactive</code></span></dt><dd><p>
+ Prompt for the user name if none is specified on the command line, and
+ also prompt for whichever of the options
+ <code class="option">-d</code>/<code class="option">-D</code>,
+ <code class="option">-r</code>/<code class="option">-R</code>,
+ <code class="option">-s</code>/<code class="option">-S</code> is not specified on the command
+ line. (This was the default behavior up to PostgreSQL 9.1.)
+ </p></dd><dt><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--login</code></span></dt><dd><p>
+ The new user will be allowed to log in (that is, the user name
+ can be used as the initial session user identifier).
+ This is the default.
+ </p></dd><dt><span class="term"><code class="option">-L</code><br /></span><span class="term"><code class="option">--no-login</code></span></dt><dd><p>
+ The new user will not be allowed to log in.
+ (A role without login privilege is still useful as a means of
+ managing database permissions.)
+ </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--pwprompt</code></span></dt><dd><p>
+ If given, <span class="application">createuser</span> will issue a prompt for
+ the password of the new user. This is not necessary if you do not plan
+ on using password authentication.
+ </p></dd><dt><span class="term"><code class="option">-r</code><br /></span><span class="term"><code class="option">--createrole</code></span></dt><dd><p>
+ The new user will be allowed to create, alter, drop, comment on,
+ change the security label for, and grant or revoke membership in
+ other roles; that is,
+ this user will have <code class="literal">CREATEROLE</code> privilege.
+ See <a class="xref" href="role-attributes.html#ROLE-CREATION">role creation</a> for more details about what
+ capabilities are conferred by this privilege.
+ </p></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--no-createrole</code></span></dt><dd><p>
+ The new user will not be allowed to create new roles. This is the
+ default.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--superuser</code></span></dt><dd><p>
+ The new user will be a superuser.
+ </p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--no-superuser</code></span></dt><dd><p>
+ The new user will not be a superuser. This is the default.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">createuser</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">--replication</code></span></dt><dd><p>
+ The new user will have the <code class="literal">REPLICATION</code> privilege,
+ which is described more fully in the documentation for <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>.
+ </p></dd><dt><span class="term"><code class="option">--no-replication</code></span></dt><dd><p>
+ The new user will not have the <code class="literal">REPLICATION</code>
+ privilege, which is described more fully in the documentation for <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">createuser</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">createuser</span> also accepts the following
+ command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server
+ is running. If the value begins with a slash, it is used
+ as the directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as (not the user name to create).
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">createuser</span> to prompt for a
+ password (for connecting to the server, not for the
+ password of the new user).
+ </p><p>
+ This option is never essential, since
+ <span class="application">createuser</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">createuser</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.5.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.5.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.5.9"><h2>Examples</h2><p>
+ To create a user <code class="literal">joe</code> on the default database
+ server:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createuser joe</code></strong>
+</pre><p>
+ </p><p>
+ To create a user <code class="literal">joe</code> on the default database
+ server with prompting for some additional attributes:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createuser --interactive joe</code></strong>
+<code class="computeroutput">Shall the new role be a superuser? (y/n) </code><strong class="userinput"><code>n</code></strong>
+<code class="computeroutput">Shall the new role be allowed to create databases? (y/n) </code><strong class="userinput"><code>n</code></strong>
+<code class="computeroutput">Shall the new role be allowed to create more new roles? (y/n) </code><strong class="userinput"><code>n</code></strong>
+</pre><p>
+ </p><p>
+ To create the same user <code class="literal">joe</code> using the
+ server on host <code class="literal">eden</code>, port 5000, with attributes explicitly specified,
+ taking a look at the underlying command:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createuser -h eden -p 5000 -S -D -R -e joe</code></strong>
+<code class="computeroutput">CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</code>
+</pre><p>
+ </p><p>
+ To create the user <code class="literal">joe</code> as a superuser,
+ and assign a password immediately:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>createuser -P -s -e joe</code></strong>
+<code class="computeroutput">Enter password for new role: </code><strong class="userinput"><code>xyzzy</code></strong>
+<code class="computeroutput">Enter it again: </code><strong class="userinput"><code>xyzzy</code></strong>
+<code class="computeroutput">CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</code>
+</pre><p>
+ In the above example, the new password isn't actually echoed when typed,
+ but we show what was typed for clarity. As you see, the password is
+ encrypted before it is sent to the client.
+ </p></div><div class="refsect1" id="id-1.9.4.5.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-dropuser.html" title="dropuser"><span class="refentrytitle"><span class="application">dropuser</span></span></a>, <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-createdb.html" title="createdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-dropdb.html" title="dropdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">createdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">dropdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-dropdb.html b/doc/src/sgml/html/app-dropdb.html
new file mode 100644
index 0000000..16be89b
--- /dev/null
+++ b/doc/src/sgml/html/app-dropdb.html
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dropdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-createuser.html" title="createuser" /><link rel="next" href="app-dropuser.html" title="dropuser" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">dropdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-createuser.html" title="createuser">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-dropuser.html" title="dropuser">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-DROPDB"><div class="titlepage"></div><a id="id-1.9.4.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">dropdb</span></span></h2><p>dropdb — remove a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.6.4.1"><code class="command">dropdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>dbname</code></em> </p></div></div><div class="refsect1" id="id-1.9.4.6.5"><h2>Description</h2><p>
+ <span class="application">dropdb</span> destroys an existing
+ <span class="productname">PostgreSQL</span> database.
+ The user who executes this command must be a database
+ superuser or the owner of the database.
+ </p><p>
+ <span class="application">dropdb</span> is a wrapper around the
+ <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-dropdatabase.html" title="DROP DATABASE"><code class="command">DROP DATABASE</code></a>.
+ There is no effective difference between dropping databases via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.6.6"><h2>Options</h2><p>
+ <span class="application">dropdb</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
+ Specifies the name of the database to be removed.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">dropdb</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--force</code></span></dt><dd><p>
+ Attempt to terminate all existing connections to the target database
+ before dropping it. See <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a> for more
+ information on this option.
+ </p></dd><dt><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--interactive</code></span></dt><dd><p>
+ Issues a verification prompt before doing anything destructive.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">dropdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
+ Do not throw an error if the database does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">dropdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+
+ </p><p>
+ <span class="application">dropdb</span> also accepts the following
+ command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server
+ is running. If the value begins with a slash, it is used
+ as the directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">dropdb</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">dropdb</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">dropdb</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to in order to drop the
+ target database. If not specified, the <code class="literal">postgres</code>
+ database will be used; if that does not exist (or is the database
+ being dropped), <code class="literal">template1</code> will be used.
+ This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
+ string</a>. If so, connection string parameters will override any
+ conflicting command line options.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.6.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.6.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.6.9"><h2>Examples</h2><p>
+ To destroy the database <code class="literal">demo</code> on the default
+ database server:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>dropdb demo</code></strong>
+</pre><p>
+ </p><p>
+ To destroy the database <code class="literal">demo</code> using the
+ server on host <code class="literal">eden</code>, port 5000, with verification and a peek
+ at the underlying command:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>dropdb -p 5000 -h eden -i -e demo</code></strong>
+<code class="computeroutput">Database "demo" will be permanently deleted.
+Are you sure? (y/n) </code><strong class="userinput"><code>y</code></strong>
+<code class="computeroutput">DROP DATABASE demo;</code>
+</pre></div><div class="refsect1" id="id-1.9.4.6.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-createdb.html" title="createdb"><span class="refentrytitle"><span class="application">createdb</span></span></a>, <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-createuser.html" title="createuser">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-dropuser.html" title="dropuser">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">createuser</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">dropuser</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-dropuser.html b/doc/src/sgml/html/app-dropuser.html
new file mode 100644
index 0000000..11fb25c
--- /dev/null
+++ b/doc/src/sgml/html/app-dropuser.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dropuser</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-dropdb.html" title="dropdb" /><link rel="next" href="app-ecpg.html" title="ecpg" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">dropuser</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-dropdb.html" title="dropdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-ecpg.html" title="ecpg">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-DROPUSER"><div class="titlepage"></div><a id="id-1.9.4.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">dropuser</span></span></h2><p>dropuser — remove a <span class="productname">PostgreSQL</span> user account</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.7.4.1"><code class="command">dropuser</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>username</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.7.5"><h2>Description</h2><p>
+ <span class="application">dropuser</span> removes an existing
+ <span class="productname">PostgreSQL</span> user.
+ Only superusers and users with the <code class="literal">CREATEROLE</code> privilege can
+ remove <span class="productname">PostgreSQL</span> users. (To remove a
+ superuser, you must yourself be a superuser.)
+ </p><p>
+ <span class="application">dropuser</span> is a wrapper around the
+ <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>.
+ There is no effective difference between dropping users via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.7.6"><h2>Options</h2><p>
+ <span class="application">dropuser</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>username</code></em></span></dt><dd><p>
+ Specifies the name of the <span class="productname">PostgreSQL</span> user to be removed.
+ You will be prompted for a name if none is specified on the command
+ line and the <code class="option">-i</code>/<code class="option">--interactive</code> option
+ is used.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">dropuser</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--interactive</code></span></dt><dd><p>
+ Prompt for confirmation before actually removing the user, and prompt
+ for the user name if none is specified on the command line.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">dropuser</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
+ Do not throw an error if the user does not exist. A notice is
+ issued in this case.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">dropuser</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">dropuser</span> also accepts the following
+ command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server
+ is running. If the value begins with a slash, it is used
+ as the directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as (not the user name to drop).
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">dropuser</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">dropuser</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">dropuser</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.7.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.7.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.7.9"><h2>Examples</h2><p>
+ To remove user <code class="literal">joe</code> from the default database
+ server:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>dropuser joe</code></strong>
+</pre><p>
+ </p><p>
+ To remove user <code class="literal">joe</code> using the server on host
+ <code class="literal">eden</code>, port 5000, with verification and a peek at the underlying
+ command:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>dropuser -p 5000 -h eden -i -e joe</code></strong>
+<code class="computeroutput">Role "joe" will be permanently removed.
+Are you sure? (y/n) </code><strong class="userinput"><code>y</code></strong>
+<code class="computeroutput">DROP ROLE joe;</code>
+</pre></div><div class="refsect1" id="id-1.9.4.7.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-createuser.html" title="createuser"><span class="refentrytitle"><span class="application">createuser</span></span></a>, <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-dropdb.html" title="dropdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-ecpg.html" title="ecpg">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">dropdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">ecpg</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-ecpg.html b/doc/src/sgml/html/app-ecpg.html
new file mode 100644
index 0000000..377e376
--- /dev/null
+++ b/doc/src/sgml/html/app-ecpg.html
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ecpg</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-dropuser.html" title="dropuser" /><link rel="next" href="app-pgamcheck.html" title="pg_amcheck" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">ecpg</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-dropuser.html" title="dropuser">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgamcheck.html" title="pg_amcheck">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-ECPG"><div class="titlepage"></div><a id="id-1.9.4.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">ecpg</span></span></h2><p><span class="application">ecpg</span> — embedded SQL C preprocessor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.8.4.1"><code class="command">ecpg</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>file</code></em>... </p></div></div><div class="refsect1" id="APP-ECPG-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">ecpg</code> is the embedded SQL preprocessor for C
+ programs. It converts C programs with embedded SQL statements to
+ normal C code by replacing the SQL invocations with special
+ function calls. The output files can then be processed with any C
+ compiler tool chain.
+ </p><p>
+ <code class="command">ecpg</code> will convert each input file given on the
+ command line to the corresponding C output file. If an input file
+ name does not have any extension, <code class="filename">.pgc</code> is
+ assumed. The file's extension will be replaced
+ by <code class="filename">.c</code> to construct the output file name.
+ But the output file name can be overridden using the
+ <code class="option">-o</code> option.
+ </p><p>
+ If an input file name is just <code class="literal">-</code>,
+ <code class="command">ecpg</code> reads the program from standard input
+ (and writes to standard output, unless that is overridden
+ with <code class="option">-o</code>).
+ </p><p>
+ This reference page does not describe the embedded SQL language.
+ See <a class="xref" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Chapter 36</a> for more information on that topic.
+ </p></div><div class="refsect1" id="id-1.9.4.8.6"><h2>Options</h2><p>
+ <code class="command">ecpg</code> accepts the following command-line
+ arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-c</code></span></dt><dd><p>
+ Automatically generate certain C code from SQL code. Currently, this
+ works for <code class="literal">EXEC SQL TYPE</code>.
+ </p></dd><dt><span class="term"><code class="option">-C <em class="replaceable"><code>mode</code></em></code></span></dt><dd><p>
+ Set a compatibility mode. <em class="replaceable"><code>mode</code></em> can
+ be <code class="literal">INFORMIX</code>,
+ <code class="literal">INFORMIX_SE</code>, or <code class="literal">ORACLE</code>.
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>symbol</code></em></code></span></dt><dd><p>
+ Define a C preprocessor symbol.
+ </p></dd><dt><span class="term"><code class="option">-h</code></span></dt><dd><p>
+ Process header files. When this option is specified, the output file
+ extension becomes <code class="literal">.h</code> not <code class="literal">.c</code>,
+ and the default input file extension is <code class="literal">.pgh</code>
+ not <code class="literal">.pgc</code>. Also, the <code class="option">-c</code> option is
+ forced on.
+ </p></dd><dt><span class="term"><code class="option">-i</code></span></dt><dd><p>
+ Parse system include files as well.
+ </p></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specify an additional include path, used to find files included
+ via <code class="literal">EXEC SQL INCLUDE</code>. Defaults are
+ <code class="filename">.</code> (current directory),
+ <code class="filename">/usr/local/include</code>, the
+ <span class="productname">PostgreSQL</span> include directory which
+ is defined at compile time (default:
+ <code class="filename">/usr/local/pgsql/include</code>), and
+ <code class="filename">/usr/include</code>, in that order.
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Specifies that <code class="command">ecpg</code> should write all
+ its output to the given <em class="replaceable"><code>filename</code></em>.
+ Write <code class="literal">-o -</code> to send all output to standard output.
+ </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>option</code></em></code></span></dt><dd><p>
+ Selects run-time behavior. <em class="replaceable"><code>Option</code></em> can be
+ one of the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">no_indicator</code></span></dt><dd><p>
+ Do not use indicators but instead use special values to represent
+ null values. Historically there have been databases using this approach.
+ </p></dd><dt><span class="term"><code class="option">prepare</code></span></dt><dd><p>
+ Prepare all statements before using them. Libecpg will keep a cache of
+ prepared statements and reuse a statement if it gets executed again. If the
+ cache runs full, libecpg will free the least used statement.
+ </p></dd><dt><span class="term"><code class="option">questionmarks</code></span></dt><dd><p>
+ Allow question mark as placeholder for compatibility reasons.
+ This used to be the default long ago.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-t</code></span></dt><dd><p>
+ Turn on autocommit of transactions. In this mode, each SQL command is
+ automatically committed unless it is inside an explicit
+ transaction block. In the default mode, commands are committed
+ only when <code class="command">EXEC SQL COMMIT</code> is issued.
+ </p></dd><dt><span class="term"><code class="option">-v</code></span></dt><dd><p>
+ Print additional information including the version and the
+ "include" path.
+ </p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">ecpg</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">ecpg</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.8.7"><h2>Notes</h2><p>
+ When compiling the preprocessed C code files, the compiler needs to
+ be able to find the <span class="application">ECPG</span> header files in the
+ <span class="productname">PostgreSQL</span> include directory. Therefore, you might
+ have to use the <code class="option">-I</code> option when invoking the compiler
+ (e.g., <code class="literal">-I/usr/local/pgsql/include</code>).
+ </p><p>
+ Programs using C code with embedded SQL have to be linked against
+ the <code class="filename">libecpg</code> library, for example using the
+ linker options <code class="literal">-L/usr/local/pgsql/lib -lecpg</code>.
+ </p><p>
+ The value of either of these directories that is appropriate for
+ the installation can be found out using <a class="xref" href="app-pgconfig.html" title="pg_config"><span class="refentrytitle"><span class="application">pg_config</span></span></a>.
+ </p></div><div class="refsect1" id="id-1.9.4.8.8"><h2>Examples</h2><p>
+ If you have an embedded SQL C source file named
+ <code class="filename">prog1.pgc</code>, you can create an executable
+ program using the following sequence of commands:
+</p><pre class="programlisting">
+ecpg prog1.pgc
+cc -I/usr/local/pgsql/include -c prog1.c
+cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-dropuser.html" title="dropuser">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgamcheck.html" title="pg_amcheck">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">dropuser</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_amcheck</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-initdb.html b/doc/src/sgml/html/app-initdb.html
new file mode 100644
index 0000000..00f2877
--- /dev/null
+++ b/doc/src/sgml/html/app-initdb.html
@@ -0,0 +1,251 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>initdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="reference-server.html" title="PostgreSQL Server Applications" /><link rel="next" href="pgarchivecleanup.html" title="pg_archivecleanup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">initdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="reference-server.html" title="PostgreSQL Server Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgarchivecleanup.html" title="pg_archivecleanup">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-INITDB"><div class="titlepage"></div><a id="id-1.9.5.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">initdb</span></span></h2><p>initdb — create a new <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.3.4.1"><code class="command">initdb</code> [<em class="replaceable"><code>option</code></em>...] [ <code class="option">--pgdata</code> | <code class="option">-D</code> ]<em class="replaceable"><code> directory</code></em> </p></div></div><div class="refsect1" id="R1-APP-INITDB-1"><h2>Description</h2><p>
+ <code class="command">initdb</code> creates a new
+ <span class="productname">PostgreSQL</span> database cluster. A database
+ cluster is a collection of databases that are managed by a single
+ server instance.
+ </p><p>
+ Creating a database cluster consists of creating the directories in
+ which the database data will live, generating the shared catalog
+ tables (tables that belong to the whole cluster rather than to any
+ particular database), and creating the <code class="literal">postgres</code>,
+ <code class="literal">template1</code>, and <code class="literal">template0</code> databases.
+ The <code class="literal">postgres</code> database is a default database meant
+ for use by users, utilities and third party applications.
+ <code class="literal">template1</code> and <code class="literal">template0</code> are
+ meant as source databases to be copied by later <code class="command">CREATE
+ DATABASE</code> commands. <code class="literal">template0</code> should never
+ be modified, but you can add objects to <code class="literal">template1</code>,
+ which by default will be copied into databases created later. See
+ <a class="xref" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Section 23.3</a> for more details.
+ </p><p>
+ Although <code class="command">initdb</code> will attempt to create the
+ specified data directory, it might not have permission if the parent
+ directory of the desired data directory is root-owned. To initialize
+ in such a setup, create an empty data directory as root, then use
+ <code class="command">chown</code> to assign ownership of that directory to the
+ database user account, then <code class="command">su</code> to become the
+ database user to run <code class="command">initdb</code>.
+ </p><p>
+ <code class="command">initdb</code> must be run as the user that will own the
+ server process, because the server needs to have access to the
+ files and directories that <code class="command">initdb</code> creates.
+ Since the server cannot be run as root, you must not run
+ <code class="command">initdb</code> as root either. (It will in fact refuse
+ to do so.)
+ </p><p>
+ For security reasons the new cluster created by <code class="command">initdb</code>
+ will only be accessible by the cluster owner by default. The
+ <code class="option">--allow-group-access</code> option allows any user in the same
+ group as the cluster owner to read files in the cluster. This is useful
+ for performing backups as a non-privileged user.
+ </p><p>
+ <code class="command">initdb</code> initializes the database cluster's default locale
+ and character set encoding. These can also be set separately for each
+ database when it is created. <code class="command">initdb</code> determines those
+ settings for the template databases, which will serve as the default for
+ all other databases. By default, <code class="command">initdb</code> uses the
+ locale provider <code class="literal">libc</code>, takes the locale settings from
+ the environment, and determines the encoding from the locale settings.
+ This is almost always sufficient, unless there are special requirements.
+ </p><p>
+ To choose a different locale for the cluster, use the option
+ <code class="option">--locale</code>. There are also individual options
+ <code class="option">--lc-*</code> (see below) to set values for the individual locale
+ categories. Note that inconsistent settings for different locale
+ categories can give nonsensical results, so this should be used with care.
+ </p><p>
+ Alternatively, the ICU library can be used to provide locale services.
+ (Again, this only sets the default for subsequently created databases.) To
+ select this option, specify <code class="literal">--locale-provider=icu</code>.
+ To choose the specific ICU locale ID to apply, use the option
+ <code class="option">--icu-locale</code>. Note that
+ for implementation reasons and to support legacy code,
+ <code class="command">initdb</code> will still select and initialize libc locale
+ settings when the ICU locale provider is used.
+ </p><p>
+ When <code class="command">initdb</code> runs, it will print out the locale settings
+ it has chosen. If you have complex requirements or specified multiple
+ options, it is advisable to check that the result matches what was
+ intended.
+ </p><p>
+ More details about locale settings can be found in <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>.
+ </p><p>
+ To alter the default encoding, use the <code class="option">--encoding</code>.
+ More details can be found in <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>.
+ </p></div><div class="refsect1" id="id-1.9.5.3.6"><h2>Options</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-A <em class="replaceable"><code>authmethod</code></em></code><br /></span><span class="term"><code class="option">--auth=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the default authentication method for local
+ users used in <code class="filename">pg_hba.conf</code> (<code class="literal">host</code>
+ and <code class="literal">local</code> lines). See <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a>
+ for an overview of valid values.
+ </p><p>
+ <code class="command">initdb</code> will
+ prepopulate <code class="filename">pg_hba.conf</code> entries using the
+ specified authentication method for non-replication as well as
+ replication connections.
+ </p><p>
+ Do not use <code class="literal">trust</code> unless you trust all local users on your
+ system. <code class="literal">trust</code> is the default for ease of installation.
+ </p></dd><dt><span class="term"><code class="option">--auth-host=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the authentication method for local users via
+ TCP/IP connections used in <code class="filename">pg_hba.conf</code>
+ (<code class="literal">host</code> lines).
+ </p></dd><dt><span class="term"><code class="option">--auth-local=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the authentication method for local users via
+ Unix-domain socket connections used in <code class="filename">pg_hba.conf</code>
+ (<code class="literal">local</code> lines).
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ This option specifies the directory where the database cluster
+ should be stored. This is the only information required by
+ <code class="command">initdb</code>, but you can avoid writing it by
+ setting the <code class="envar">PGDATA</code> environment variable, which
+ can be convenient since the database server
+ (<code class="command">postgres</code>) can find the database
+ directory later by the same variable.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
+ Selects the encoding of the template databases. This will also
+ be the default encoding of any database you create later,
+ unless you override it then. The default is derived from the locale,
+ if the libc locale provider is used, or <code class="literal">UTF8</code> if the
+ ICU locale provider is used. The character sets supported by
+ the <span class="productname">PostgreSQL</span> server are described
+ in <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
+ </p></dd><dt id="APP-INITDB-ALLOW-GROUP-ACCESS"><span class="term"><code class="option">-g</code><br /></span><span class="term"><code class="option">--allow-group-access</code></span></dt><dd><p>
+ Allows users in the same group as the cluster owner to read all cluster
+ files created by <code class="command">initdb</code>. This option is ignored
+ on <span class="productname">Windows</span> as it does not support
+ <acronym class="acronym">POSIX</acronym>-style group permissions.
+ </p></dd><dt><span class="term"><code class="option">--icu-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the ICU locale ID, if the ICU locale provider is used.
+ </p></dd><dt id="APP-INITDB-DATA-CHECKSUMS"><span class="term"><code class="option">-k</code><br /></span><span class="term"><code class="option">--data-checksums</code></span></dt><dd><p>
+ Use checksums on data pages to help detect corruption by the
+ I/O system that would otherwise be silent. Enabling checksums
+ may incur a noticeable performance penalty. If set, checksums
+ are calculated for all objects, in all databases. All checksum
+ failures will be reported in the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW" title="28.2.15. pg_stat_database">
+ <code class="structname">pg_stat_database</code></a> view.
+ See <a class="xref" href="checksums.html" title="30.2. Data Checksums">Section 30.2</a> for details.
+ </p></dd><dt><span class="term"><code class="option">--locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Sets the default locale for the database cluster. If this
+ option is not specified, the locale is inherited from the
+ environment that <code class="command">initdb</code> runs in. Locale
+ support is described in <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>.
+ </p></dd><dt><span class="term"><code class="option">--lc-collate=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-ctype=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-messages=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-monetary=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-numeric=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-time=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Like <code class="option">--locale</code>, but only sets the locale in
+ the specified category.
+ </p></dd><dt><span class="term"><code class="option">--no-locale</code></span></dt><dd><p>
+ Equivalent to <code class="option">--locale=C</code>.
+ </p></dd><dt><span class="term"><code class="option">--locale-provider={<code class="literal">libc</code>|<code class="literal">icu</code>}</code></span></dt><dd><p>
+ This option sets the locale provider for databases created in the
+ new cluster. It can be overridden in the <code class="command">CREATE
+ DATABASE</code> command when new databases are subsequently
+ created. The default is <code class="literal">libc</code>.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">initdb</code> will wait for all files to be
+ written safely to disk. This option causes <code class="command">initdb</code>
+ to return without waiting, which is faster, but means that a
+ subsequent operating system crash can leave the data directory
+ corrupt. Generally, this option is useful for testing, but should not
+ be used when creating a production installation.
+ </p></dd><dt><span class="term"><code class="option">--no-instructions</code></span></dt><dd><p>
+ By default, <code class="command">initdb</code> will write instructions for how
+ to start the cluster at the end of its output. This option causes
+ those instructions to be left out. This is primarily intended for use
+ by tools that wrap <code class="command">initdb</code> in platform-specific
+ behavior, where those instructions are likely to be incorrect.
+ </p></dd><dt><span class="term"><code class="option">--pwfile=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Makes <code class="command">initdb</code> read the database superuser's password
+ from a file. The first line of the file is taken as the password.
+ </p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--sync-only</code></span></dt><dd><p>
+ Safely write all database files to disk and exit. This does not
+ perform any of the normal <span class="application">initdb</span> operations.
+ Generally, this option is useful for ensuring reliable recovery after
+ changing <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> from <code class="literal">off</code> to
+ <code class="literal">on</code>.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>config</code></em></code><br /></span><span class="term"><code class="option">--text-search-config=<em class="replaceable"><code>config</code></em></code></span></dt><dd><p>
+ Sets the default text search configuration.
+ See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a> for further information.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Selects the user name of the database superuser. This defaults
+ to the name of the effective user running
+ <code class="command">initdb</code>. It is really not important what the
+ superuser's name is, but one might choose to keep the
+ customary name <span class="systemitem">postgres</span>, even if the operating
+ system user's name is different.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--pwprompt</code></span></dt><dd><p>
+ Makes <code class="command">initdb</code> prompt for a password
+ to give the database superuser. If you don't plan on using password
+ authentication, this is not important. Otherwise you won't be
+ able to use password authentication until you have a password
+ set up.
+ </p></dd><dt><span class="term"><code class="option">-X <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--waldir=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ This option specifies the directory where the write-ahead log
+ should be stored.
+ </p></dd><dt><span class="term"><code class="option">--wal-segsize=<em class="replaceable"><code>size</code></em></code></span></dt><dd><p>
+ Set the <em class="firstterm">WAL segment size</em>, in megabytes. This
+ is the size of each individual file in the WAL log. The default size
+ is 16 megabytes. The value must be a power of 2 between 1 and 1024
+ (megabytes). This option can only be set during initialization, and
+ cannot be changed later.
+ </p><p>
+ It may be useful to adjust this size to control the granularity of
+ WAL log shipping or archiving. Also, in databases with a high volume
+ of WAL, the sheer number of WAL files per directory can become a
+ performance and management problem. Increasing the WAL file size
+ will reduce the number of WAL files.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other, less commonly used, options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--debug</code></span></dt><dd><p>
+ Print debugging output from the bootstrap backend and a few other
+ messages of lesser interest for the general public.
+ The bootstrap backend is the program <code class="command">initdb</code>
+ uses to create the catalog tables. This option generates a tremendous
+ amount of extremely boring output.
+ </p></dd><dt><span class="term"><code class="option">--discard-caches</code></span></dt><dd><p>
+ Run the bootstrap backend with the
+ <code class="literal">debug_discard_caches=1</code> option.
+ This takes a very long time and is only of use for deep debugging.
+ </p></dd><dt><span class="term"><code class="option">-L <em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specifies where <code class="command">initdb</code> should find
+ its input files to initialize the database cluster. This is
+ normally not necessary. You will be told if you need to
+ specify their location explicitly.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-clean</code></span></dt><dd><p>
+ By default, when <code class="command">initdb</code>
+ determines that an error prevented it from completely creating the database
+ cluster, it removes any files it might have created before discovering
+ that it cannot finish the job. This option inhibits tidying-up and is
+ thus useful for debugging.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">initdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">initdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.3.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Specifies the directory where the database cluster is to be
+ stored; can be overridden using the <code class="option">-D</code> option.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd><dt><span class="term"><code class="envar">TZ</code></span></dt><dd><p>
+ Specifies the default time zone of the created database cluster. The
+ value should be a full time zone name
+ (see <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>).
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.5.3.8"><h2>Notes</h2><p>
+ <code class="command">initdb</code> can also be invoked via
+ <code class="command">pg_ctl initdb</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.3.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>, <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>, <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reference-server.html" title="PostgreSQL Server Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgarchivecleanup.html" title="pg_archivecleanup">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostgreSQL Server Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_archivecleanup</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pg-ctl.html b/doc/src/sgml/html/app-pg-ctl.html
new file mode 100644
index 0000000..dafbad2
--- /dev/null
+++ b/doc/src/sgml/html/app-pg-ctl.html
@@ -0,0 +1,288 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_ctl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgcontroldata.html" title="pg_controldata" /><link rel="next" href="app-pgresetwal.html" title="pg_resetwal" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_ctl</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgcontroldata.html" title="pg_controldata">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgresetwal.html" title="pg_resetwal">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PG-CTL"><div class="titlepage"></div><a id="id-1.9.5.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_ctl</span></span></h2><p>pg_ctl — initialize, start, stop, or control a <span class="productname">PostgreSQL</span> server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.7.4.1"><code class="command">pg_ctl</code> <code class="option">init[db]</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-s</code>] [<code class="option">-o</code> <em class="replaceable"><code>initdb-options</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.2"><code class="command">pg_ctl</code> <code class="option">start</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-l</code> <em class="replaceable"><code>filename</code></em>] [<code class="option">-W</code>] [<code class="option">-t</code> <em class="replaceable"><code>seconds</code></em>] [<code class="option">-s</code>] [<code class="option">-o</code> <em class="replaceable"><code>options</code></em>] [<code class="option">-p</code> <em class="replaceable"><code>path</code></em>] [<code class="option">-c</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.3"><code class="command">pg_ctl</code> <code class="option">stop</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-m</code>
+ <code class="option">s[mart]</code> | <code class="option">f[ast]</code> | <code class="option">i[mmediate]</code>
+ ] [<code class="option">-W</code>] [<code class="option">-t</code> <em class="replaceable"><code>seconds</code></em>] [<code class="option">-s</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.4"><code class="command">pg_ctl</code> <code class="option">restart</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-m</code>
+ <code class="option">s[mart]</code> | <code class="option">f[ast]</code> | <code class="option">i[mmediate]</code>
+ ] [<code class="option">-W</code>] [<code class="option">-t</code> <em class="replaceable"><code>seconds</code></em>] [<code class="option">-s</code>] [<code class="option">-o</code> <em class="replaceable"><code>options</code></em>] [<code class="option">-c</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.5"><code class="command">pg_ctl</code> <code class="option">reload</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-s</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.6"><code class="command">pg_ctl</code> <code class="option">status</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.7"><code class="command">pg_ctl</code> <code class="option">promote</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-W</code>] [<code class="option">-t</code> <em class="replaceable"><code>seconds</code></em>] [<code class="option">-s</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.8"><code class="command">pg_ctl</code> <code class="option">logrotate</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-s</code>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.9"><code class="command">pg_ctl</code> <code class="option">kill</code> <em class="replaceable"><code>signal_name</code></em> <em class="replaceable"><code>process_id</code></em> </p></div><p>On Microsoft Windows, also:</p><div class="cmdsynopsis"><p id="id-1.9.5.7.4.11"><code class="command">pg_ctl</code> <code class="option">register</code> [<code class="option">-D</code> <em class="replaceable"><code>datadir</code></em>] [<code class="option">-N</code> <em class="replaceable"><code>servicename</code></em>] [<code class="option">-U</code> <em class="replaceable"><code>username</code></em>] [<code class="option">-P</code> <em class="replaceable"><code>password</code></em>] [<code class="option">-S</code>
+ <code class="option">a[uto]</code> | <code class="option">d[emand]</code>
+ ] [<code class="option">-e</code> <em class="replaceable"><code>source</code></em>] [<code class="option">-W</code>] [<code class="option">-t</code> <em class="replaceable"><code>seconds</code></em>] [<code class="option">-s</code>] [<code class="option">-o</code> <em class="replaceable"><code>options</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.5.7.4.12"><code class="command">pg_ctl</code> <code class="option">unregister</code> [<code class="option">-N</code> <em class="replaceable"><code>servicename</code></em>]</p></div></div><div class="refsect1" id="APP-PG-CTL-DESCRIPTION"><h2>Description</h2><p>
+ <span class="application">pg_ctl</span> is a utility for initializing a
+ <span class="productname">PostgreSQL</span> database cluster, starting,
+ stopping, or restarting the <span class="productname">PostgreSQL</span>
+ database server (<a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>), or displaying the
+ status of a running server. Although the server can be started
+ manually, <span class="application">pg_ctl</span> encapsulates tasks such
+ as redirecting log output and properly detaching from the terminal
+ and process group. It also provides convenient options for
+ controlled shutdown.
+ </p><p>
+ The <code class="option">init</code> or <code class="option">initdb</code> mode creates a new
+ <span class="productname">PostgreSQL</span> database cluster, that is,
+ a collection of databases that will be managed by a single
+ server instance. This mode invokes the <code class="command">initdb</code>
+ command. See <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a> for details.
+ </p><p>
+ <code class="option">start</code> mode launches a new server. The
+ server is started in the background, and its standard input is attached
+ to <code class="filename">/dev/null</code> (or <code class="literal">nul</code> on Windows).
+ On Unix-like systems, by default, the server's standard output and
+ standard error are sent to <span class="application">pg_ctl</span>'s
+ standard output (not standard error). The standard output of
+ <span class="application">pg_ctl</span> should then be redirected to a
+ file or piped to another process such as a log rotating program
+ like <span class="application">rotatelogs</span>; otherwise <code class="command">postgres</code>
+ will write its output to the controlling terminal (from the
+ background) and will not leave the shell's process group. On
+ Windows, by default the server's standard output and standard error
+ are sent to the terminal. These default behaviors can be changed
+ by using <code class="option">-l</code> to append the server's output to a log file.
+ Use of either <code class="option">-l</code> or output redirection is recommended.
+ </p><p>
+ <code class="option">stop</code> mode shuts down the server that is running in
+ the specified data directory. Three different
+ shutdown methods can be selected with the <code class="option">-m</code>
+ option. <span class="quote">“<span class="quote">Smart</span>”</span> mode disallows new connections, then waits
+ for all existing clients to disconnect.
+ If the server is in hot standby, recovery and streaming replication
+ will be terminated once all clients have disconnected.
+ <span class="quote">“<span class="quote">Fast</span>”</span> mode (the default) does not wait for clients to disconnect.
+ All active transactions are
+ rolled back and clients are forcibly disconnected, then the
+ server is shut down. <span class="quote">“<span class="quote">Immediate</span>”</span> mode will abort
+ all server processes immediately, without a clean shutdown. This choice
+ will lead to a crash-recovery cycle during the next server start.
+ </p><p>
+ <code class="option">restart</code> mode effectively executes a stop followed
+ by a start. This allows changing the <code class="command">postgres</code>
+ command-line options, or changing configuration-file options that
+ cannot be changed without restarting the server.
+ If relative paths were used on the command line during server
+ start, <code class="option">restart</code> might fail unless
+ <span class="application">pg_ctl</span> is executed in the same current
+ directory as it was during server start.
+ </p><p>
+ <code class="option">reload</code> mode simply sends the
+ <code class="command">postgres</code> server process a <span class="systemitem">SIGHUP</span>
+ signal, causing it to reread its configuration files
+ (<code class="filename">postgresql.conf</code>,
+ <code class="filename">pg_hba.conf</code>, etc.). This allows changing
+ configuration-file options that do not require a full server restart
+ to take effect.
+ </p><p>
+ <code class="option">status</code> mode checks whether a server is running in
+ the specified data directory. If it is, the server's <acronym class="acronym">PID</acronym>
+ and the command line options that were used to invoke it are displayed.
+ If the server is not running, <span class="application">pg_ctl</span> returns
+ an exit status of 3. If an accessible data directory is not
+ specified, <span class="application">pg_ctl</span> returns an exit status of 4.
+ </p><p>
+ <code class="option">promote</code> mode commands the standby server that is
+ running in the specified data directory to end standby mode
+ and begin read-write operations.
+ </p><p>
+ <code class="option">logrotate</code> mode rotates the server log file.
+ For details on how to use this mode with external log rotation tools, see
+ <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a>.
+ </p><p>
+ <code class="option">kill</code> mode sends a signal to a specified process.
+ This is primarily valuable on <span class="productname">Microsoft Windows</span>
+ which does not have a built-in <span class="application">kill</span> command. Use
+ <code class="literal">--help</code> to see a list of supported signal names.
+ </p><p>
+ <code class="option">register</code> mode registers the <span class="productname">PostgreSQL</span>
+ server as a system service on <span class="productname">Microsoft Windows</span>.
+ The <code class="option">-S</code> option allows selection of service start type,
+ either <span class="quote">“<span class="quote">auto</span>”</span> (start service automatically on system startup)
+ or <span class="quote">“<span class="quote">demand</span>”</span> (start service on demand).
+ </p><p>
+ <code class="option">unregister</code> mode unregisters a system service
+ on <span class="productname">Microsoft Windows</span>. This undoes the effects of the
+ <code class="option">register</code> command.
+ </p></div><div class="refsect1" id="APP-PG-CTL-OPTIONS"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--core-files</code></span></dt><dd><p>
+ Attempt to allow server crashes to produce core files, on platforms
+ where this is possible, by lifting any soft resource limit placed on
+ core files.
+ This is useful in debugging or diagnosing problems by allowing a
+ stack trace to be obtained from a failed server process.
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>datadir</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>datadir</code></em></code></span></dt><dd><p>
+ Specifies the file system location of the database configuration files. If
+ this option is omitted, the environment variable
+ <code class="envar">PGDATA</code> is used.
+ </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--log=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Append the server log output to
+ <em class="replaceable"><code>filename</code></em>. If the file does not
+ exist, it is created. The <span class="systemitem">umask</span> is set to 077,
+ so access to the log file is disallowed to other users by default.
+ </p></dd><dt><span class="term"><code class="option">-m <em class="replaceable"><code>mode</code></em></code><br /></span><span class="term"><code class="option">--mode=<em class="replaceable"><code>mode</code></em></code></span></dt><dd><p>
+ Specifies the shutdown mode. <em class="replaceable"><code>mode</code></em>
+ can be <code class="literal">smart</code>, <code class="literal">fast</code>, or
+ <code class="literal">immediate</code>, or the first letter of one of
+ these three. If this option is omitted, <code class="literal">fast</code> is
+ the default.
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>options</code></em></code><br /></span><span class="term"><code class="option">--options=<em class="replaceable"><code>options</code></em></code></span></dt><dd><p>
+ Specifies options to be passed directly to the
+ <code class="command">postgres</code> command.
+ <code class="option">-o</code> can be specified multiple times, with all the given
+ options being passed through.
+ </p><p>
+ The <em class="replaceable"><code>options</code></em> should usually be surrounded by single or
+ double quotes to ensure that they are passed through as a group.
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>initdb-options</code></em></code><br /></span><span class="term"><code class="option">--options=<em class="replaceable"><code>initdb-options</code></em></code></span></dt><dd><p>
+ Specifies options to be passed directly to the
+ <code class="command">initdb</code> command.
+ <code class="option">-o</code> can be specified multiple times, with all the given
+ options being passed through.
+ </p><p>
+ The <em class="replaceable"><code>initdb-options</code></em> should usually be surrounded by single or
+ double quotes to ensure that they are passed through as a group.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
+ Specifies the location of the <code class="filename">postgres</code>
+ executable. By default the <code class="filename">postgres</code> executable is taken from the same
+ directory as <code class="command">pg_ctl</code>, or failing that, the hard-wired
+ installation directory. It is not necessary to use this
+ option unless you are doing something unusual and get errors
+ that the <code class="filename">postgres</code> executable was not found.
+ </p><p>
+ In <code class="literal">init</code> mode, this option analogously
+ specifies the location of the <code class="filename">initdb</code>
+ executable.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--silent</code></span></dt><dd><p>
+ Print only errors, no informational messages.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>seconds</code></em></code><br /></span><span class="term"><code class="option">--timeout=<em class="replaceable"><code>seconds</code></em></code></span></dt><dd><p>
+ Specifies the maximum number of seconds to wait when waiting for an
+ operation to complete (see option <code class="option">-w</code>). Defaults to
+ the value of the <code class="envar">PGCTLTIMEOUT</code> environment variable or, if
+ not set, to 60 seconds.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_ctl</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--wait</code></span></dt><dd><p>
+ Wait for the operation to complete. This is supported for the
+ modes <code class="literal">start</code>, <code class="literal">stop</code>,
+ <code class="literal">restart</code>, <code class="literal">promote</code>,
+ and <code class="literal">register</code>, and is the default for those modes.
+ </p><p>
+ When waiting, <code class="command">pg_ctl</code> repeatedly checks the
+ server's <acronym class="acronym">PID</acronym> file, sleeping for a short amount
+ of time between checks. Startup is considered complete when
+ the <acronym class="acronym">PID</acronym> file indicates that the server is ready to
+ accept connections. Shutdown is considered complete when the server
+ removes the <acronym class="acronym">PID</acronym> file.
+ <code class="command">pg_ctl</code> returns an exit code based on the
+ success of the startup or shutdown.
+ </p><p>
+ If the operation does not complete within the timeout (see
+ option <code class="option">-t</code>), then <code class="command">pg_ctl</code> exits with
+ a nonzero exit status. But note that the operation might continue in
+ the background and eventually succeed.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--no-wait</code></span></dt><dd><p>
+ Do not wait for the operation to complete. This is the opposite of
+ the option <code class="option">-w</code>.
+ </p><p>
+ If waiting is disabled, the requested action is triggered, but there
+ is no feedback about its success. In that case, the server log file
+ or an external monitoring system would have to be used to check the
+ progress and success of the operation.
+ </p><p>
+ In prior releases of PostgreSQL, this was the default except for
+ the <code class="literal">stop</code> mode.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_ctl</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ If an option is specified that is valid, but not relevant to the selected
+ operating mode, <span class="application">pg_ctl</span> ignores it.
+ </p><div class="refsect2" id="APP-PG-CTL-WINDOWS-OPTIONS"><h3>Options for Windows</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e <em class="replaceable"><code>source</code></em></code></span></dt><dd><p>
+ Name of the event source for <span class="application">pg_ctl</span> to use
+ for logging to the event log when running as a Windows service. The
+ default is <code class="literal">PostgreSQL</code>. Note that this only controls
+ messages sent from <span class="application">pg_ctl</span> itself; once
+ started, the server will use the event source specified
+ by its <a class="xref" href="runtime-config-logging.html#GUC-EVENT-SOURCE">event_source</a> parameter. Should the server
+ fail very early in startup, before that parameter has been set,
+ it might also log using the default event
+ source name <code class="literal">PostgreSQL</code>.
+ </p></dd><dt><span class="term"><code class="option">-N <em class="replaceable"><code>servicename</code></em></code></span></dt><dd><p>
+ Name of the system service to register. This name will be used
+ as both the service name and the display name.
+ The default is <code class="literal">PostgreSQL</code>.
+ </p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>password</code></em></code></span></dt><dd><p>
+ Password for the user to run the service as.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>start-type</code></em></code></span></dt><dd><p>
+ Start type of the system service. <em class="replaceable"><code>start-type</code></em> can
+ be <code class="literal">auto</code>, or <code class="literal">demand</code>, or
+ the first letter of one of these two. If this option is omitted,
+ <code class="literal">auto</code> is the default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name for the user to run the service as. For domain users, use the
+ format <code class="literal">DOMAIN\username</code>.
+ </p></dd></dl></div></div></div><div class="refsect1" id="id-1.9.5.7.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGCTLTIMEOUT</code></span></dt><dd><p>
+ Default limit on the number of seconds to wait when waiting for startup
+ or shutdown to complete. If not set, the default is 60 seconds.
+ </p></dd><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Default data directory location.
+ </p></dd></dl></div><p>
+ Most <code class="command">pg_ctl</code> modes require knowing the data directory
+ location; therefore, the <code class="option">-D</code> option is required
+ unless <code class="envar">PGDATA</code> is set.
+ </p><p>
+ <code class="command">pg_ctl</code>, like most other <span class="productname">PostgreSQL</span>
+ utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ For additional variables that affect the server,
+ see <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>.
+ </p></div><div class="refsect1" id="id-1.9.5.7.8"><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">postmaster.pid</code></span></dt><dd><p>
+ <span class="application">pg_ctl</span> examines this file in the data
+ directory to determine whether the server is currently running.
+ </p></dd><dt><span class="term"><code class="filename">postmaster.opts</code></span></dt><dd><p>If this file exists in the data directory,
+ <span class="application">pg_ctl</span> (in <code class="option">restart</code> mode)
+ will pass the contents of the file as options to
+ <span class="application">postgres</span>, unless overridden
+ by the <code class="option">-o</code> option. The contents of this file
+ are also displayed in <code class="option">status</code> mode.
+ </p></dd></dl></div></div><div class="refsect1" id="R1-APP-PGCTL-2"><h2>Examples</h2><div class="refsect2" id="R2-APP-PGCTL-3"><h3>Starting the Server</h3><p>
+ To start the server, waiting until the server is
+ accepting connections:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl start</code></strong>
+</pre><p>
+ </p><p>
+ To start the server using port 5433, and
+ running without <code class="function">fsync</code>, use:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -o "-F -p 5433" start</code></strong>
+</pre></div><div class="refsect2" id="R2-APP-PGCTL-4"><h3>Stopping the Server</h3><p>
+ To stop the server, use:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl stop</code></strong>
+</pre><p>
+ The <code class="option">-m</code> option allows control over
+ <span class="emphasis"><em>how</em></span> the server shuts down:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl stop -m smart</code></strong>
+</pre></div><div class="refsect2" id="R2-APP-PGCTL-5"><h3>Restarting the Server</h3><p>
+ Restarting the server is almost equivalent to stopping the
+ server and starting it again, except that by default,
+ <code class="command">pg_ctl</code> saves and reuses the command line options that
+ were passed to the previously-running instance. To restart
+ the server using the same options as before, use:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl restart</code></strong>
+</pre><p>
+ </p><p>
+ But if <code class="option">-o</code> is specified, that replaces any previous options.
+ To restart using port 5433, disabling <code class="function">fsync</code> upon restart:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -o "-F -p 5433" restart</code></strong>
+</pre></div><div class="refsect2" id="R2-APP-PGCTL-6"><h3>Showing the Server Status</h3><p>
+ Here is sample status output from
+ <span class="application">pg_ctl</span>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl status</code></strong>
+<code class="computeroutput">
+pg_ctl: server is running (PID: 13718)
+/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
+</code></pre><p>
+ The second line is the command that would be invoked in restart mode.
+ </p></div></div><div class="refsect1" id="id-1.9.5.7.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>, <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgcontroldata.html" title="pg_controldata">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgresetwal.html" title="pg_resetwal">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_controldata</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_resetwal</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pg-dumpall.html b/doc/src/sgml/html/app-pg-dumpall.html
new file mode 100644
index 0000000..3c574b4
--- /dev/null
+++ b/doc/src/sgml/html/app-pg-dumpall.html
@@ -0,0 +1,364 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_dumpall</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgdump.html" title="pg_dump" /><link rel="next" href="app-pg-isready.html" title="pg_isready" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_dumpall</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgdump.html" title="pg_dump">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pg-isready.html" title="pg_isready">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PG-DUMPALL"><div class="titlepage"></div><a id="id-1.9.4.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_dumpall</span></span></h2><p>pg_dumpall — extract a <span class="productname">PostgreSQL</span> database cluster into a script file</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.14.4.1"><code class="command">pg_dumpall</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="APP-PG-DUMPALL-DESCRIPTION"><h2>Description</h2><p>
+ <span class="application">pg_dumpall</span> is a utility for writing out
+ (<span class="quote">“<span class="quote">dumping</span>”</span>) all <span class="productname">PostgreSQL</span> databases
+ of a cluster into one script file. The script file contains
+ <acronym class="acronym">SQL</acronym> commands that can be used as input to <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> to restore the databases. It does this by
+ calling <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> for each database in the cluster.
+ <span class="application">pg_dumpall</span> also dumps global objects
+ that are common to all databases, namely database roles, tablespaces,
+ and privilege grants for configuration parameters.
+ (<span class="application">pg_dump</span> does not save these objects.)
+ </p><p>
+ Since <span class="application">pg_dumpall</span> reads tables from all
+ databases you will most likely have to connect as a database
+ superuser in order to produce a complete dump. Also you will need
+ superuser privileges to execute the saved script in order to be
+ allowed to add roles and create databases.
+ </p><p>
+ The SQL script will be written to the standard output. Use the
+ <code class="option">-f</code>/<code class="option">--file</code> option or shell operators to
+ redirect it into a file.
+ </p><p>
+ <span class="application">pg_dumpall</span> needs to connect several
+ times to the <span class="productname">PostgreSQL</span> server (once per
+ database). If you use password authentication it will ask for
+ a password each time. It is convenient to have a
+ <code class="filename">~/.pgpass</code> file in such cases. See <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> for more information.
+ </p></div><div class="refsect1" id="id-1.9.4.14.6"><h2>Options</h2><p>
+ The following command-line options control the content and
+ format of the output.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--data-only</code></span></dt><dd><p>
+ Dump only the data, not the schema (data definitions).
+ </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--clean</code></span></dt><dd><p>
+ Emit SQL commands to <code class="command">DROP</code> all the dumped
+ databases, roles, and tablespaces before recreating them.
+ This option is useful when the restore is to overwrite an existing
+ cluster. If any of the objects do not exist in the destination
+ cluster, ignorable error messages will be reported during
+ restore, unless <code class="option">--if-exists</code> is also specified.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
+ Create the dump in the specified character set encoding. By default,
+ the dump is created in the database encoding. (Another way to get the
+ same result is to set the <code class="envar">PGCLIENTENCODING</code> environment
+ variable to the desired dump encoding.)
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Send output to the specified file. If this is omitted, the
+ standard output is used.
+ </p></dd><dt><span class="term"><code class="option">-g</code><br /></span><span class="term"><code class="option">--globals-only</code></span></dt><dd><p>
+ Dump only global objects (roles and tablespaces), no databases.
+ </p></dd><dt><span class="term"><code class="option">-O</code><br /></span><span class="term"><code class="option">--no-owner</code></span></dt><dd><p>
+ Do not output commands to set
+ ownership of objects to match the original database.
+ By default, <span class="application">pg_dumpall</span> issues
+ <code class="command">ALTER OWNER</code> or
+ <code class="command">SET SESSION AUTHORIZATION</code>
+ statements to set ownership of created schema elements.
+ These statements
+ will fail when the script is run unless it is started by a superuser
+ (or the same user that owns all of the objects in the script).
+ To make a script that can be restored by any user, but will give
+ that user ownership of all the objects, specify <code class="option">-O</code>.
+ </p></dd><dt><span class="term"><code class="option">-r</code><br /></span><span class="term"><code class="option">--roles-only</code></span></dt><dd><p>
+ Dump only roles, no databases or tablespaces.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--schema-only</code></span></dt><dd><p>
+ Dump only the object definitions (schema), not data.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--superuser=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Specify the superuser user name to use when disabling triggers.
+ This is relevant only if <code class="option">--disable-triggers</code> is used.
+ (Usually, it's better to leave this out, and instead start the
+ resulting script as superuser.)
+ </p></dd><dt><span class="term"><code class="option">-t</code><br /></span><span class="term"><code class="option">--tablespaces-only</code></span></dt><dd><p>
+ Dump only tablespaces, no databases or roles.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Specifies verbose mode. This will cause
+ <span class="application">pg_dumpall</span> to output start/stop
+ times to the dump file, and progress messages to standard error.
+ Repeating the option causes additional debug-level messages
+ to appear on standard error.
+ The option is also passed down to <span class="application">pg_dump</span>.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_dumpall</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--no-privileges</code><br /></span><span class="term"><code class="option">--no-acl</code></span></dt><dd><p>
+ Prevent dumping of access privileges (grant/revoke commands).
+ </p></dd><dt><span class="term"><code class="option">--binary-upgrade</code></span></dt><dd><p>
+ This option is for use by in-place upgrade utilities. Its use
+ for other purposes is not recommended or supported. The
+ behavior of the option may change in future releases without
+ notice.
+ </p></dd><dt><span class="term"><code class="option">--column-inserts</code><br /></span><span class="term"><code class="option">--attribute-inserts</code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands with explicit
+ column names (<code class="literal">INSERT INTO
+ <em class="replaceable"><code>table</code></em>
+ (<em class="replaceable"><code>column</code></em>, ...) VALUES
+ ...</code>). This will make restoration very slow; it is mainly
+ useful for making dumps that can be loaded into
+ non-<span class="productname">PostgreSQL</span> databases.
+ </p></dd><dt><span class="term"><code class="option">--disable-dollar-quoting</code></span></dt><dd><p>
+ This option disables the use of dollar quoting for function bodies,
+ and forces them to be quoted using SQL standard string syntax.
+ </p></dd><dt><span class="term"><code class="option">--disable-triggers</code></span></dt><dd><p>
+ This option is relevant only when creating a data-only dump.
+ It instructs <span class="application">pg_dumpall</span> to include commands
+ to temporarily disable triggers on the target tables while
+ the data is restored. Use this if you have referential
+ integrity checks or other triggers on the tables that you
+ do not want to invoke during data restore.
+ </p><p>
+ Presently, the commands emitted for <code class="option">--disable-triggers</code>
+ must be done as superuser. So, you should also specify
+ a superuser name with <code class="option">-S</code>, or preferably be careful to
+ start the resulting script as a superuser.
+ </p></dd><dt><span class="term"><code class="option">--exclude-database=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Do not dump databases whose name matches
+ <em class="replaceable"><code>pattern</code></em>.
+ Multiple patterns can be excluded by writing multiple
+ <code class="option">--exclude-database</code> switches. The
+ <em class="replaceable"><code>pattern</code></em> parameter is
+ interpreted as a pattern according to the same rules used by
+ <span class="application">psql</span>'s <code class="literal">\d</code>
+ commands (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below),
+ so multiple databases can also be excluded by writing wildcard
+ characters in the pattern. When using wildcards, be careful to
+ quote the pattern if needed to prevent shell wildcard expansion.
+ </p></dd><dt><span class="term"><code class="option">--extra-float-digits=<em class="replaceable"><code>ndigits</code></em></code></span></dt><dd><p>
+ Use the specified value of extra_float_digits when dumping
+ floating-point data, instead of the maximum available precision.
+ Routine dumps made for backup purposes should not use this option.
+ </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
+ Use <code class="literal">DROP ... IF EXISTS</code> commands to drop objects
+ in <code class="option">--clean</code> mode. This suppresses <span class="quote">“<span class="quote">does not
+ exist</span>”</span> errors that might otherwise be reported. This
+ option is not valid unless <code class="option">--clean</code> is also
+ specified.
+ </p></dd><dt><span class="term"><code class="option">--inserts</code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands (rather
+ than <code class="command">COPY</code>). This will make restoration very slow;
+ it is mainly useful for making dumps that can be loaded into
+ non-<span class="productname">PostgreSQL</span> databases. Note that
+ the restore might fail altogether if you have rearranged column order.
+ The <code class="option">--column-inserts</code> option is safer, though even
+ slower.
+ </p></dd><dt><span class="term"><code class="option">--load-via-partition-root</code></span></dt><dd><p>
+ When dumping data for a table partition, make
+ the <code class="command">COPY</code> or <code class="command">INSERT</code> statements
+ target the root of the partitioning hierarchy that contains it, rather
+ than the partition itself. This causes the appropriate partition to
+ be re-determined for each row when the data is loaded. This may be
+ useful when restoring data on a server where rows do not always fall
+ into the same partitions as they did on the original server. That
+ could happen, for example, if the partitioning column is of type text
+ and the two systems have different definitions of the collation used
+ to sort the partitioning column.
+ </p></dd><dt><span class="term"><code class="option">--lock-wait-timeout=<em class="replaceable"><code>timeout</code></em></code></span></dt><dd><p>
+ Do not wait forever to acquire shared table locks at the beginning of
+ the dump. Instead, fail if unable to lock a table within the specified
+ <em class="replaceable"><code>timeout</code></em>. The timeout may be
+ specified in any of the formats accepted by <code class="command">SET
+ statement_timeout</code>.
+ </p></dd><dt><span class="term"><code class="option">--no-comments</code></span></dt><dd><p>
+ Do not dump comments.
+ </p></dd><dt><span class="term"><code class="option">--no-publications</code></span></dt><dd><p>
+ Do not dump publications.
+ </p></dd><dt><span class="term"><code class="option">--no-role-passwords</code></span></dt><dd><p>
+ Do not dump passwords for roles. When restored, roles will have a
+ null password, and password authentication will always fail until the
+ password is set. Since password values aren't needed when this option
+ is specified, the role information is read from the catalog
+ view <code class="structname">pg_roles</code> instead
+ of <code class="structname">pg_authid</code>. Therefore, this option also
+ helps if access to <code class="structname">pg_authid</code> is restricted by
+ some security policy.
+ </p></dd><dt><span class="term"><code class="option">--no-security-labels</code></span></dt><dd><p>
+ Do not dump security labels.
+ </p></dd><dt><span class="term"><code class="option">--no-subscriptions</code></span></dt><dd><p>
+ Do not dump subscriptions.
+ </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_dumpall</code> will wait for all files
+ to be written safely to disk. This option causes
+ <code class="command">pg_dumpall</code> to return without waiting, which is
+ faster, but means that a subsequent operating system crash can leave
+ the dump corrupt. Generally, this option is useful for testing
+ but should not be used when dumping data from production installation.
+ </p></dd><dt><span class="term"><code class="option">--no-table-access-method</code></span></dt><dd><p>
+ Do not output commands to select table access methods.
+ With this option, all objects will be created with whichever
+ table access method is the default during restore.
+ </p></dd><dt><span class="term"><code class="option">--no-tablespaces</code></span></dt><dd><p>
+ Do not output commands to create tablespaces nor select tablespaces
+ for objects.
+ With this option, all objects will be created in whichever
+ tablespace is the default during restore.
+ </p></dd><dt><span class="term"><code class="option">--no-toast-compression</code></span></dt><dd><p>
+ Do not output commands to set <acronym class="acronym">TOAST</acronym> compression
+ methods.
+ With this option, all columns will be restored with the default
+ compression setting.
+ </p></dd><dt><span class="term"><code class="option">--no-unlogged-table-data</code></span></dt><dd><p>
+ Do not dump the contents of unlogged tables. This option has no
+ effect on whether or not the table definitions (schema) are dumped;
+ it only suppresses dumping the table data.
+ </p></dd><dt><span class="term"><code class="option">--on-conflict-do-nothing</code></span></dt><dd><p>
+ Add <code class="literal">ON CONFLICT DO NOTHING</code> to
+ <code class="command">INSERT</code> commands.
+ This option is not valid unless <code class="option">--inserts</code> or
+ <code class="option">--column-inserts</code> is also specified.
+ </p></dd><dt><span class="term"><code class="option">--quote-all-identifiers</code></span></dt><dd><p>
+ Force quoting of all identifiers. This option is recommended when
+ dumping a database from a server whose <span class="productname">PostgreSQL</span>
+ major version is different from <span class="application">pg_dumpall</span>'s, or when
+ the output is intended to be loaded into a server of a different
+ major version. By default, <span class="application">pg_dumpall</span> quotes only
+ identifiers that are reserved words in its own major version.
+ This sometimes results in compatibility issues when dealing with
+ servers of other versions that may have slightly different sets
+ of reserved words. Using <code class="option">--quote-all-identifiers</code> prevents
+ such issues, at the price of a harder-to-read dump script.
+ </p></dd><dt><span class="term"><code class="option">--rows-per-insert=<em class="replaceable"><code>nrows</code></em></code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands (rather than
+ <code class="command">COPY</code>). Controls the maximum number of rows per
+ <code class="command">INSERT</code> command. The value specified must be a
+ number greater than zero. Any error during restoring will cause only
+ rows that are part of the problematic <code class="command">INSERT</code> to be
+ lost, rather than the entire table contents.
+ </p></dd><dt><span class="term"><code class="option">--use-set-session-authorization</code></span></dt><dd><p>
+ Output SQL-standard <code class="command">SET SESSION AUTHORIZATION</code> commands
+ instead of <code class="command">ALTER OWNER</code> commands to determine object
+ ownership. This makes the dump more standards compatible, but
+ depending on the history of the objects in the dump, might not restore
+ properly.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_dumpall</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control the database connection parameters.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>connstr</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
+ Specifies parameters used to connect to the server, as a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>; these
+ will override any conflicting command line options.
+ </p><p>
+ The option is called <code class="literal">--dbname</code> for consistency with other
+ client applications, but because <span class="application">pg_dumpall</span>
+ needs to connect to many databases, the database name in the
+ connection string will be ignored. Use the <code class="literal">-l</code>
+ option to specify the name of the database used for the initial
+ connection, which will dump global objects and discover what other
+ databases should be dumped.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the database
+ server is running. If the value begins with a slash, it is
+ used as the directory for the Unix domain socket. The default
+ is taken from the <code class="envar">PGHOST</code> environment variable,
+ if set, else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--database=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to for dumping global
+ objects and discovering what other databases should be dumped. If
+ not specified, the <code class="literal">postgres</code> database will be used,
+ and if that does not exist, <code class="literal">template1</code> will be used.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_dumpall</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_dumpall</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_dumpall</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p><p>
+ Note that the password prompt will occur again for each database
+ to be dumped. Usually, it's better to set up a
+ <code class="filename">~/.pgpass</code> file than to rely on manual password entry.
+ </p></dd><dt><span class="term"><code class="option">--role=<em class="replaceable"><code>rolename</code></em></code></span></dt><dd><p>
+ Specifies a role name to be used to create the dump.
+ This option causes <span class="application">pg_dumpall</span> to issue a
+ <code class="command">SET ROLE</code> <em class="replaceable"><code>rolename</code></em>
+ command after connecting to the database. It is useful when the
+ authenticated user (specified by <code class="option">-U</code>) lacks privileges
+ needed by <span class="application">pg_dumpall</span>, but can switch to a role with
+ the required rights. Some installations have a policy against
+ logging in directly as a superuser, and use of this option allows
+ dumps to be made without violating the policy.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.14.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGOPTIONS</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.14.8"><h2>Notes</h2><p>
+ Since <span class="application">pg_dumpall</span> calls
+ <span class="application">pg_dump</span> internally, some diagnostic
+ messages will refer to <span class="application">pg_dump</span>.
+ </p><p>
+ The <code class="option">--clean</code> option can be useful even when your
+ intention is to restore the dump script into a fresh cluster. Use of
+ <code class="option">--clean</code> authorizes the script to drop and re-create the
+ built-in <code class="literal">postgres</code> and <code class="literal">template1</code>
+ databases, ensuring that those databases will retain the same properties
+ (for instance, locale and encoding) that they had in the source cluster.
+ Without the option, those databases will retain their existing
+ database-level properties, as well as any pre-existing contents.
+ </p><p>
+ Once restored, it is wise to run <code class="command">ANALYZE</code> on each
+ database so the optimizer has useful statistics. You
+ can also run <code class="command">vacuumdb -a -z</code> to analyze all
+ databases.
+ </p><p>
+ The dump script should not be expected to run completely without errors.
+ In particular, because the script will issue <code class="command">CREATE ROLE</code>
+ for every role existing in the source cluster, it is certain to get a
+ <span class="quote">“<span class="quote">role already exists</span>”</span> error for the bootstrap superuser,
+ unless the destination cluster was initialized with a different bootstrap
+ superuser name. This error is harmless and should be ignored. Use of
+ the <code class="option">--clean</code> option is likely to produce additional
+ harmless error messages about non-existent objects, although you can
+ minimize those by adding <code class="option">--if-exists</code>.
+ </p><p>
+ <span class="application">pg_dumpall</span> requires all needed
+ tablespace directories to exist before the restore; otherwise,
+ database creation will fail for databases in non-default
+ locations.
+ </p></div><div class="refsect1" id="APP-PG-DUMPALL-EX"><h2>Examples</h2><p>
+ To dump all databases:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dumpall &gt; db.out</code></strong>
+</pre><p>
+ </p><p>
+ To restore database(s) from this file, you can use:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>psql -f db.out postgres</code></strong>
+</pre><p>
+ It is not important to which database you connect here since the
+ script file created by <span class="application">pg_dumpall</span> will
+ contain the appropriate commands to create and connect to the saved
+ databases. An exception is that if you specified <code class="option">--clean</code>,
+ you must connect to the <code class="literal">postgres</code> database initially;
+ the script will attempt to drop other databases immediately, and that
+ will fail for the database you are connected to.
+ </p></div><div class="refsect1" id="id-1.9.4.14.10"><h2>See Also</h2><p>
+ Check <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> for details on possible
+ error conditions.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgdump.html" title="pg_dump">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pg-isready.html" title="pg_isready">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_dump</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_isready</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pg-isready.html b/doc/src/sgml/html/app-pg-isready.html
new file mode 100644
index 0000000..b193fc5
--- /dev/null
+++ b/doc/src/sgml/html/app-pg-isready.html
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_isready</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pg-dumpall.html" title="pg_dumpall" /><link rel="next" href="app-pgreceivewal.html" title="pg_receivewal" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_isready</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pg-dumpall.html" title="pg_dumpall">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgreceivewal.html" title="pg_receivewal">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PG-ISREADY"><div class="titlepage"></div><a id="id-1.9.4.15.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_isready</span></span></h2><p>pg_isready — check the connection status of a <span class="productname">PostgreSQL</span> server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.15.4.1"><code class="command">pg_isready</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="APP-PG-ISREADY-DESCRIPTION"><h2>Description</h2><p>
+ <span class="application">pg_isready</span> is a utility for checking the connection
+ status of a <span class="productname">PostgreSQL</span> database server. The exit
+ status specifies the result of the connection check.
+ </p></div><div class="refsect1" id="APP-PG-ISREADY-OPTIONS"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to. The
+ <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>. If so,
+ connection string parameters will override any conflicting command
+ line options.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server is running. If the value begins
+ with a slash, it is used as the directory for the Unix-domain
+ socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or the local Unix-domain
+ socket file extension on which the server is listening for
+ connections. Defaults to the value of the <code class="envar">PGPORT</code>
+ environment variable or, if not set, to the port specified at
+ compile time, usually 5432.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Do not display status message. This is useful when scripting.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>seconds</code></em></code><br /></span><span class="term"><code class="option">--timeout=<em class="replaceable"><code>seconds</code></em></code></span></dt><dd><p>
+ The maximum number of seconds to wait when attempting connection before
+ returning that the server is not responding. Setting to 0 disables. The
+ default is 3 seconds.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Connect to the database as the user <em class="replaceable"><code>username</code></em> instead of the default.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_isready</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_isready</span> command line
+ arguments, and exit.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.4.15.7"><h2>Exit Status</h2><p>
+ <span class="application">pg_isready</span> returns <code class="literal">0</code> to the shell if the server
+ is accepting connections normally, <code class="literal">1</code> if the server is rejecting
+ connections (for example during startup), <code class="literal">2</code> if there was no response to the
+ connection attempt, and <code class="literal">3</code> if no attempt was made (for example due to invalid
+ parameters).
+ </p></div><div class="refsect1" id="id-1.9.4.15.8"><h2>Environment</h2><p>
+ <code class="command">pg_isready</code>, like most other <span class="productname">PostgreSQL</span>
+ utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="APP-PG-ISREADY-NOTES"><h2>Notes</h2><p>
+ It is not necessary to supply correct user name, password, or database
+ name values to obtain the server status; however, if incorrect values
+ are provided, the server will log a failed connection attempt.
+ </p></div><div class="refsect1" id="APP-PG-ISREADY-EXAMPLES"><h2>Examples</h2><p>
+ Standard Usage:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_isready</code></strong>
+<code class="computeroutput">/tmp:5432 - accepting connections</code>
+<code class="prompt">$</code> <strong class="userinput"><code>echo $?</code></strong>
+<code class="computeroutput">0</code>
+</pre><p>
+ </p><p>
+ Running with connection parameters to a <span class="productname">PostgreSQL</span> cluster in startup:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>pg_isready -h localhost -p 5433</code></strong>
+<code class="computeroutput">localhost:5433 - rejecting connections</code>
+<code class="prompt">$</code> <strong class="userinput"><code>echo $?</code></strong>
+<code class="computeroutput">1</code>
+</pre><p>
+ </p><p>
+ Running with connection parameters to a non-responsive <span class="productname">PostgreSQL</span> cluster:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>pg_isready -h someremotehost</code></strong>
+<code class="computeroutput">someremotehost:5432 - no response</code>
+<code class="prompt">$</code> <strong class="userinput"><code>echo $?</code></strong>
+<code class="computeroutput">2</code>
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pg-dumpall.html" title="pg_dumpall">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgreceivewal.html" title="pg_receivewal">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_dumpall</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_receivewal</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgamcheck.html b/doc/src/sgml/html/app-pgamcheck.html
new file mode 100644
index 0000000..8096ada
--- /dev/null
+++ b/doc/src/sgml/html/app-pgamcheck.html
@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_amcheck</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-ecpg.html" title="ecpg" /><link rel="next" href="app-pgbasebackup.html" title="pg_basebackup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_amcheck</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-ecpg.html" title="ecpg">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgbasebackup.html" title="pg_basebackup">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGAMCHECK"><div class="titlepage"></div><a id="id-1.9.4.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_amcheck</span></span></h2><p>pg_amcheck — checks for corruption in one or more
+ <span class="productname">PostgreSQL</span> databases</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.9.4.1"><code class="command">pg_amcheck</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.9.5"><h2>Description</h2><p>
+ <span class="application">pg_amcheck</span> supports running
+ <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s corruption checking functions against one or
+ more databases, with options to select which schemas, tables and indexes to
+ check, which kinds of checking to perform, and whether to perform the checks
+ in parallel, and if so, the number of parallel connections to establish and
+ use.
+ </p><p>
+ Only ordinary and toast table relations, materialized views, sequences, and
+ btree indexes are currently supported. Other relation types are silently
+ skipped.
+ </p><p>
+ If <code class="literal">dbname</code> is specified, it should be the name of a
+ single database to check, and no other database selection options should
+ be present. Otherwise, if any database selection options are present,
+ all matching databases will be checked. If no such options are present,
+ the default database will be checked. Database selection options include
+ <code class="option">--all</code>, <code class="option">--database</code> and
+ <code class="option">--exclude-database</code>. They also include
+ <code class="option">--relation</code>, <code class="option">--exclude-relation</code>,
+ <code class="option">--table</code>, <code class="option">--exclude-table</code>,
+ <code class="option">--index</code>, and <code class="option">--exclude-index</code>,
+ but only when such options are used with a three-part pattern
+ (e.g. <code class="option">mydb*.myschema*.myrel*</code>). Finally, they include
+ <code class="option">--schema</code> and <code class="option">--exclude-schema</code>
+ when such options are used with a two-part pattern
+ (e.g. <code class="option">mydb*.myschema*</code>).
+ </p><p>
+ <em class="replaceable"><code>dbname</code></em> can also be a
+ <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.
+ </p></div><div class="refsect1" id="id-1.9.4.9.6"><h2>Options</h2><p>
+ The following command-line options control what is checked:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
+ Check all databases, except for any excluded via
+ <code class="option">--exclude-database</code>.
+ </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--database=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Check databases matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+ except for any excluded by <code class="option">--exclude-database</code>.
+ This option can be specified more than once.
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-database=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Exclude databases matching the given
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+ This option can be specified more than once.
+ </p></dd><dt><span class="term"><code class="option">-i <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--index=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Check indexes matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+ unless they are otherwise excluded.
+ This option can be specified more than once.
+ </p><p>
+ This is similar to the <code class="option">--relation</code> option, except that
+ it applies only to indexes, not to other relation types.
+ </p></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-index=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Exclude indexes matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+ This option can be specified more than once.
+ </p><p>
+ This is similar to the <code class="option">--exclude-relation</code> option,
+ except that it applies only to indexes, not other relation types.
+ </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--relation=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Check relations matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+ unless they are otherwise excluded.
+ This option can be specified more than once.
+ </p><p>
+ Patterns may be unqualified, e.g. <code class="literal">myrel*</code>, or they
+ may be schema-qualified, e.g. <code class="literal">myschema*.myrel*</code> or
+ database-qualified and schema-qualified, e.g.
+ <code class="literal">mydb*.myschema*.myrel*</code>. A database-qualified
+ pattern will add matching databases to the list of databases to be
+ checked.
+ </p></dd><dt><span class="term"><code class="option">-R <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-relation=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Exclude relations matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+ This option can be specified more than once.
+ </p><p>
+ As with <code class="option">--relation</code>, the
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> may be unqualified, schema-qualified,
+ or database- and schema-qualified.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Check tables and indexes in schemas matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>, unless they are otherwise excluded.
+ This option can be specified more than once.
+ </p><p>
+ To select only tables in schemas matching a particular pattern,
+ consider using something like
+ <code class="literal">--table=SCHEMAPAT.* --no-dependent-indexes</code>.
+ To select only indexes, consider using something like
+ <code class="literal">--index=SCHEMAPAT.*</code>.
+ </p><p>
+ A schema pattern may be database-qualified. For example, you may
+ write <code class="literal">--schema=mydb*.myschema*</code> to select
+ schemas matching <code class="literal">myschema*</code> in databases matching
+ <code class="literal">mydb*</code>.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Exclude tables and indexes in schemas matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+ This option can be specified more than once.
+ </p><p>
+ As with <code class="option">--schema</code>, the pattern may be
+ database-qualified.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Check tables matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+ unless they are otherwise excluded.
+ This option can be specified more than once.
+ </p><p>
+ This is similar to the <code class="option">--relation</code> option, except that
+ it applies only to tables, materialized views, and sequences, not to
+ indexes.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Exclude tables matching the specified
+ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+ This option can be specified more than once.
+ </p><p>
+ This is similar to the <code class="option">--exclude-relation</code> option,
+ except that it applies only to tables, materialized views, and
+ sequences, not to indexes.
+ </p></dd><dt><span class="term"><code class="option">--no-dependent-indexes</code></span></dt><dd><p>
+ By default, if a table is checked, any btree indexes of that table
+ will also be checked, even if they are not explicitly selected by
+ an option such as <code class="literal">--index</code> or
+ <code class="literal">--relation</code>. This option suppresses that behavior.
+ </p></dd><dt><span class="term"><code class="option">--no-dependent-toast</code></span></dt><dd><p>
+ By default, if a table is checked, its toast table, if any, will also
+ be checked, even if it is not explicitly selected by an option
+ such as <code class="literal">--table</code> or <code class="literal">--relation</code>.
+ This option suppresses that behavior.
+ </p></dd><dt><span class="term"><code class="option">--no-strict-names</code></span></dt><dd><p>
+ By default, if an argument to <code class="literal">--database</code>,
+ <code class="literal">--table</code>, <code class="literal">--index</code>,
+ or <code class="literal">--relation</code> matches no objects, it is a fatal
+ error. This option downgrades that error to a warning.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control checking of tables:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--exclude-toast-pointers</code></span></dt><dd><p>
+ By default, whenever a toast pointer is encountered in a table,
+ a lookup is performed to ensure that it references apparently-valid
+ entries in the toast table. These checks can be quite slow, and this
+ option can be used to skip them.
+ </p></dd><dt><span class="term"><code class="option">--on-error-stop</code></span></dt><dd><p>
+ After reporting all corruptions on the first page of a table where
+ corruption is found, stop processing that table relation and move on
+ to the next table or index.
+ </p><p>
+ Note that index checking always stops after the first corrupt page.
+ This option only has meaning relative to table relations.
+ </p></dd><dt><span class="term"><code class="option">--skip=<em class="replaceable"><code>option</code></em></code></span></dt><dd><p>
+ If <code class="literal">all-frozen</code> is given, table corruption checks
+ will skip over pages in all tables that are marked as all frozen.
+ </p><p>
+ If <code class="literal">all-visible</code> is given, table corruption checks
+ will skip over pages in all tables that are marked as all visible.
+ </p><p>
+ By default, no pages are skipped. This can be specified as
+ <code class="literal">none</code>, but since this is the default, it need not be
+ mentioned.
+ </p></dd><dt><span class="term"><code class="option">--startblock=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
+ Start checking at the specified block number. An error will occur if
+ the table relation being checked has fewer than this number of blocks.
+ This option does not apply to indexes, and is probably only useful
+ when checking a single table relation. See <code class="literal">--endblock</code>
+ for further caveats.
+ </p></dd><dt><span class="term"><code class="option">--endblock=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
+ End checking at the specified block number. An error will occur if the
+ table relation being checked has fewer than this number of blocks.
+ This option does not apply to indexes, and is probably only useful when
+ checking a single table relation. If both a regular table and a toast
+ table are checked, this option will apply to both, but higher-numbered
+ toast blocks may still be accessed while validating toast pointers,
+ unless that is suppressed using
+ <code class="option">--exclude-toast-pointers</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control checking of B-tree indexes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--heapallindexed</code></span></dt><dd><p>
+ For each index checked, verify the presence of all heap tuples as index
+ tuples in the index using <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s
+ <code class="option">heapallindexed</code> option.
+ </p></dd><dt><span class="term"><code class="option">--parent-check</code></span></dt><dd><p>
+ For each btree index checked, use <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s
+ <code class="function">bt_index_parent_check</code> function, which performs
+ additional checks of parent/child relationships during index checking.
+ </p><p>
+ The default is to use <span class="application">amcheck</span>'s
+ <code class="function">bt_index_check</code> function, but note that use of the
+ <code class="option">--rootdescend</code> option implicitly selects
+ <code class="function">bt_index_parent_check</code>.
+ </p></dd><dt><span class="term"><code class="option">--rootdescend</code></span></dt><dd><p>
+ For each index checked, re-find tuples on the leaf level by performing a
+ new search from the root page for each tuple using
+ <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s <code class="option">rootdescend</code> option.
+ </p><p>
+ Use of this option implicitly also selects the
+ <code class="option">--parent-check</code> option.
+ </p><p>
+ This form of verification was originally written to help in the
+ development of btree index features. It may be of limited use or even
+ of no use in helping detect the kinds of corruption that occur in
+ practice. It may also cause corruption checking to take considerably
+ longer and consume considerably more resources on the server.
+ </p></dd></dl></div><p>
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ The extra checks performed against B-tree indexes when the
+ <code class="option">--parent-check</code> option or the
+ <code class="option">--rootdescend</code> option is specified require
+ relatively strong relation-level locks. These checks are the only
+ checks that will block concurrent data modification from
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> commands.
+ </p></div><p>
+ The following command-line options control the connection to the server:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is running.
+ If the value begins with a slash, it is used as the directory for the
+ Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file extension on
+ which the server is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U</code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires password
+ authentication and a password is not available by other means such as
+ a <code class="filename">.pgpass</code> file, the connection attempt will fail.
+ This option can be useful in batch jobs and scripts where no user is
+ present to enter a password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_amcheck</span> to prompt for a password
+ before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_amcheck</span> will automatically prompt for a
+ password if the server demands password authentication. However,
+ <span class="application">pg_amcheck</span> will waste a connection attempt
+ finding out that the server wants a password. In some cases it is
+ worth typing <code class="option">-W</code> to avoid the extra connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies a database or
+ <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a> to be
+ used to discover the list of databases to be checked. If neither
+ <code class="option">--all</code> nor any option including a database pattern is
+ used, no such connection is required and this option does nothing.
+ Otherwise, any connection string parameters other than
+ the database name which are included in the value for this option
+ will also be used when connecting to the databases
+ being checked. If this option is omitted, the default is
+ <code class="literal">postgres</code> or, if that fails,
+ <code class="literal">template1</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo to stdout all SQL sent to the server.
+ </p></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>num</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>num</code></em></code></span></dt><dd><p>
+ Use <em class="replaceable"><code>num</code></em> concurrent connections to the server,
+ or one per object to be checked, whichever is less.
+ </p><p>
+ The default is to use a single connection.
+ </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
+ Show progress information. Progress information includes the number
+ of relations for which checking has been completed, and the total
+ size of those relations. It also includes the total number of relations
+ that will eventually be checked, and the estimated size of those
+ relations.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Print more messages. In particular, this will print a message for
+ each relation being checked, and will increase the level of detail
+ shown for server errors.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_amcheck</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">--install-missing</code><br /></span><span class="term"><code class="option">--install-missing=<em class="replaceable"><code>schema</code></em></code></span></dt><dd><p>
+ Install any missing extensions that are required to check the
+ database(s). If not yet installed, each extension's objects will be
+ installed into the given
+ <em class="replaceable"><code>schema</code></em>, or if not specified
+ into schema <code class="literal">pg_catalog</code>.
+ </p><p>
+ At present, the only required extension is <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_amcheck</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.9.7"><h2>Notes</h2><p>
+ <span class="application">pg_amcheck</span> is designed to work with
+ <span class="productname">PostgreSQL</span> 14.0 and later.
+ </p></div><div class="refsect1" id="id-1.9.4.9.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-ecpg.html" title="ecpg">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgbasebackup.html" title="pg_basebackup">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">ecpg</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_basebackup</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgbasebackup.html b/doc/src/sgml/html/app-pgbasebackup.html
new file mode 100644
index 0000000..16a5f66
--- /dev/null
+++ b/doc/src/sgml/html/app-pgbasebackup.html
@@ -0,0 +1,550 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_basebackup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgamcheck.html" title="pg_amcheck" /><link rel="next" href="pgbench.html" title="pgbench" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_basebackup</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgamcheck.html" title="pg_amcheck">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgbench.html" title="pgbench">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGBASEBACKUP"><div class="titlepage"></div><a id="id-1.9.4.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_basebackup</span></span></h2><p>pg_basebackup — take a base backup of a <span class="productname">PostgreSQL</span> cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.10.4.1"><code class="command">pg_basebackup</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.10.5"><h2>Description</h2><p>
+ <span class="application">pg_basebackup</span> is used to take a base backup of
+ a running <span class="productname">PostgreSQL</span> database cluster. The backup
+ is taken without affecting other clients of the database, and can be used
+ both for point-in-time recovery (see <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>)
+ and as the starting point for a log-shipping or streaming-replication standby
+ server (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
+ </p><p>
+ <span class="application">pg_basebackup</span> makes an exact copy of the database
+ cluster's files, while making sure the server is put into and
+ out of backup mode automatically. Backups are always taken of the entire
+ database cluster; it is not possible to back up individual databases or
+ database objects. For selective backups, another tool such as
+ <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> must be used.
+ </p><p>
+ The backup is made over a regular <span class="productname">PostgreSQL</span>
+ connection that uses the replication protocol. The connection must be made
+ with a user ID that has <code class="literal">REPLICATION</code> permissions
+ (see <a class="xref" href="role-attributes.html" title="22.2. Role Attributes">Section 22.2</a>) or is a superuser,
+ and <a class="link" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File"><code class="filename">pg_hba.conf</code></a>
+ must permit the replication connection. The server must also be configured
+ with <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> set high enough to provide at
+ least one walsender for the backup plus one for WAL streaming (if used).
+ </p><p>
+ There can be multiple <code class="command">pg_basebackup</code>s running at the same time, but it is usually
+ better from a performance point of view to take only one backup, and copy
+ the result.
+ </p><p>
+ <span class="application">pg_basebackup</span> can make a base backup from
+ not only a primary server but also a standby. To take a backup from a standby,
+ set up the standby so that it can accept replication connections (that is, set
+ <code class="varname">max_wal_senders</code> and <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a>,
+ and configure its <code class="filename">pg_hba.conf</code> appropriately).
+ You will also need to enable <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> on the primary.
+ </p><p>
+ Note that there are some limitations in taking a backup from a standby:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The backup history file is not created in the database cluster backed up.
+ </p></li><li class="listitem"><p>
+ <span class="application">pg_basebackup</span> cannot force the standby
+ to switch to a new WAL file at the end of backup.
+ When you are using <code class="literal">-X none</code>, if write activity on
+ the primary is low, <span class="application">pg_basebackup</span> may
+ need to wait a long time for the last WAL file required for the backup
+ to be switched and archived. In this case, it may be useful to run
+ <code class="function">pg_switch_wal</code> on the primary in order to
+ trigger an immediate WAL file switch.
+ </p></li><li class="listitem"><p>
+ If the standby is promoted to be primary during backup, the backup fails.
+ </p></li><li class="listitem"><p>
+ All WAL records required for the backup must contain sufficient full-page writes,
+ which requires you to enable <code class="varname">full_page_writes</code> on the primary.
+ </p></li></ul></div><p>
+ </p><p>
+ Whenever <span class="application">pg_basebackup</span> is taking a base
+ backup, the server's <code class="structname">pg_stat_progress_basebackup</code>
+ view will report the progress of the backup.
+ See <a class="xref" href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING" title="28.4.5. Base Backup Progress Reporting">Section 28.4.5</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.4.10.6"><h2>Options</h2><p>
+ The following command-line options control the location and format of the
+ output:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Sets the target directory to write the output to.
+ <span class="application">pg_basebackup</span> will create this directory
+ (and any missing parent directories) if it does not exist. If it
+ already exists, it must be empty.
+ </p><p>
+ When the backup is in tar format, the target directory may be
+ specified as <code class="literal">-</code> (dash), causing the tar file to be
+ written to <code class="literal">stdout</code>.
+ </p><p>
+ This option is required.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>format</code></em></code><br /></span><span class="term"><code class="option">--format=<em class="replaceable"><code>format</code></em></code></span></dt><dd><p>
+ Selects the format for the output. <em class="replaceable"><code>format</code></em>
+ can be one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">p</code><br /></span><span class="term"><code class="literal">plain</code></span></dt><dd><p>
+ Write the output as plain files, with the same layout as the
+ source server's data directory and tablespaces. When the cluster has
+ no additional tablespaces, the whole database will be placed in
+ the target directory. If the cluster contains additional
+ tablespaces, the main data directory will be placed in the
+ target directory, but all other tablespaces will be placed
+ in the same absolute path as they have on the source server.
+ (See <code class="option">--tablespace-mapping</code> to change that.)
+ </p><p>
+ This is the default format.
+ </p></dd><dt><span class="term"><code class="literal">t</code><br /></span><span class="term"><code class="literal">tar</code></span></dt><dd><p>
+ Write the output as tar files in the target directory. The main
+ data directory's contents will be written to a file named
+ <code class="filename">base.tar</code>, and each other tablespace will be
+ written to a separate tar file named after that tablespace's OID.
+ </p><p>
+ If the target directory is specified as <code class="literal">-</code>
+ (dash), the tar contents will be written to
+ standard output, suitable for piping to (for example)
+ <span class="productname">gzip</span>. This is only allowed if
+ the cluster has no additional tablespaces and WAL
+ streaming is not used.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--write-recovery-conf</code></span></dt><dd><p>
+ Creates a
+ <a class="link" href="warm-standby.html#FILE-STANDBY-SIGNAL"><code class="filename">standby.signal</code></a>
+ <a id="id-1.9.4.10.6.2.1.3.3.1.2" class="indexterm"></a>
+ file and appends
+ connection settings to the <code class="filename">postgresql.auto.conf</code>
+ file in the target directory (or within the base archive file when
+ using tar format). This eases setting up a standby server using the
+ results of the backup.
+ </p><p>
+ The <code class="filename">postgresql.auto.conf</code> file will record the connection
+ settings and, if specified, the replication slot
+ that <span class="application">pg_basebackup</span> is using, so that
+ streaming replication will use the same settings later on.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>target</code></em></code><br /></span><span class="term"><code class="option">--target=<em class="replaceable"><code>target</code></em></code></span></dt><dd><p>
+ Instructs the server where to place the base backup. The default target
+ is <code class="literal">client</code>, which specifies that the backup should
+ be sent to the machine where <span class="application">pg_basebackup</span>
+ is running. If the target is instead set to
+ <code class="literal">server:/some/path</code>, the backup will be stored on
+ the machine where the server is running in the
+ <code class="literal">/some/path</code> directory. Storing a backup on the
+ server requires superuser privileges or having privileges of the
+ <code class="literal">pg_write_server_files</code> role. If the target is set to
+ <code class="literal">blackhole</code>, the contents are discarded and not
+ stored anywhere. This should only be used for testing purposes, as you
+ will not end up with an actual backup.
+ </p><p>
+ Since WAL streaming is implemented by
+ <span class="application">pg_basebackup</span> rather than by the server,
+ this option cannot be used together with <code class="literal">-Xstream</code>.
+ Since that is the default, when this option is specified, you must also
+ specify either <code class="literal">-Xfetch</code> or <code class="literal">-Xnone</code>.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>olddir</code></em>=<em class="replaceable"><code>newdir</code></em></code><br /></span><span class="term"><code class="option">--tablespace-mapping=<em class="replaceable"><code>olddir</code></em>=<em class="replaceable"><code>newdir</code></em></code></span></dt><dd><p>
+ Relocates the tablespace in directory <em class="replaceable"><code>olddir</code></em>
+ to <em class="replaceable"><code>newdir</code></em> during the backup. To be
+ effective, <em class="replaceable"><code>olddir</code></em> must exactly match the
+ path specification of the tablespace as it is defined on the source
+ server. (But it is not an error if there is no tablespace
+ in <em class="replaceable"><code>olddir</code></em> on the source server.)
+ Meanwhile <em class="replaceable"><code>newdir</code></em> is a directory in the
+ receiving host's filesystem. As with the main target directory,
+ <em class="replaceable"><code>newdir</code></em> need not exist already, but if
+ it does exist it must be empty.
+ Both <em class="replaceable"><code>olddir</code></em>
+ and <em class="replaceable"><code>newdir</code></em> must be absolute paths. If
+ either path needs to contain an equal sign (<code class="literal">=</code>),
+ precede that with a backslash. This option can be specified multiple
+ times for multiple tablespaces.
+ </p><p>
+ If a tablespace is relocated in this way, the symbolic links inside
+ the main data directory are updated to point to the new location. So
+ the new data directory is ready to be used for a new server instance
+ with all tablespaces in the updated locations.
+ </p><p>
+ Currently, this option only works with plain output format; it is
+ ignored if tar format is selected.
+ </p></dd><dt><span class="term"><code class="option">--waldir=<em class="replaceable"><code>waldir</code></em></code></span></dt><dd><p>
+ Sets the directory to write WAL (write-ahead log) files to.
+ By default WAL files will be placed in
+ the <code class="filename">pg_wal</code> subdirectory of the target
+ directory, but this option can be used to place them elsewhere.
+ <em class="replaceable"><code>waldir</code></em> must be an absolute path.
+ As with the main target directory,
+ <em class="replaceable"><code>waldir</code></em> need not exist already, but if
+ it does exist it must be empty.
+ This option can only be specified when
+ the backup is in plain format.
+ </p></dd><dt><span class="term"><code class="option">-X <em class="replaceable"><code>method</code></em></code><br /></span><span class="term"><code class="option">--wal-method=<em class="replaceable"><code>method</code></em></code></span></dt><dd><p>
+ Includes the required WAL (write-ahead log) files in the
+ backup. This will include all write-ahead logs generated during
+ the backup. Unless the method <code class="literal">none</code> is specified,
+ it is possible to start a postmaster in the target
+ directory without the need to consult the log archive, thus
+ making the output a completely standalone backup.
+ </p><p>
+ The following <em class="replaceable"><code>method</code></em>s for collecting the
+ write-ahead logs are supported:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">n</code><br /></span><span class="term"><code class="literal">none</code></span></dt><dd><p>
+ Don't include write-ahead logs in the backup.
+ </p></dd><dt><span class="term"><code class="literal">f</code><br /></span><span class="term"><code class="literal">fetch</code></span></dt><dd><p>
+ The write-ahead log files are collected at the end of the backup.
+ Therefore, it is necessary for the source server's
+ <a class="xref" href="runtime-config-replication.html#GUC-WAL-KEEP-SIZE">wal_keep_size</a> parameter to be set high
+ enough that the required log data is not removed before the end
+ of the backup. If the required log data has been recycled
+ before it's time to transfer it, the backup will fail and be
+ unusable.
+ </p><p>
+ When tar format is used, the write-ahead log files will be
+ included in the <code class="filename">base.tar</code> file.
+ </p></dd><dt><span class="term"><code class="literal">s</code><br /></span><span class="term"><code class="literal">stream</code></span></dt><dd><p>
+ Stream write-ahead log data while the backup is being taken.
+ This method will open a second connection to the server and
+ start streaming the write-ahead log in parallel while running
+ the backup. Therefore, it will require two replication
+ connections not just one. As long as the client can keep up
+ with the write-ahead log data, using this method requires no
+ extra write-ahead logs to be saved on the source server.
+ </p><p>
+ When tar format is used, the write-ahead log files will be
+ written to a separate file named <code class="filename">pg_wal.tar</code>
+ (if the server is a version earlier than 10, the file will be named
+ <code class="filename">pg_xlog.tar</code>).
+ </p><p>
+ This value is the default.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--gzip</code></span></dt><dd><p>
+ Enables gzip compression of tar file output, with the default
+ compression level. Compression is only available when using
+ the tar format, and the suffix <code class="filename">.gz</code> will
+ automatically be added to all tar filenames.
+ </p></dd><dt><span class="term"><code class="option">-Z <em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">-Z [{client|server}-]<em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">--compress=[{client|server}-]<em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code></span></dt><dd><p>
+ Requests compression of the backup. If <code class="literal">client</code> or
+ <code class="literal">server</code> is included, it specifies where the
+ compression is to be performed. Compressing on the server will reduce
+ transfer bandwidth but will increase server CPU consumption. The
+ default is <code class="literal">client</code> except when
+ <code class="literal">--target</code> is used. In that case, the backup is not
+ being sent to the client, so only server compression is sensible.
+ When <code class="literal">-Xstream</code>, which is the default, is used,
+ server-side compression will not be applied to the WAL. To compress
+ the WAL, use client-side compression, or
+ specify <code class="literal">-Xfetch</code>.
+ </p><p>
+ The compression method can be set to <code class="literal">gzip</code>,
+ <code class="literal">lz4</code>, <code class="literal">zstd</code>, or
+ <code class="literal">none</code> for no compression. A compression detail
+ string can optionally be specified. If the detail string is an
+ integer, it specifies the compression level. Otherwise, it should be
+ a comma-separated list of items, each of the form
+ <code class="literal">keyword</code> or <code class="literal">keyword=value</code>.
+ Currently, the supported keywords are <code class="literal">level</code>
+ and <code class="literal">workers</code>.
+ </p><p>
+ If no compression level is specified, the default compression level
+ will be used. If only a level is specified without mentioning an
+ algorithm, <code class="literal">gzip</code> compression will be used if the
+ level is greater than 0, and no compression will be used if the level
+ is 0.
+ </p><p>
+ When the tar format is used with <code class="literal">gzip</code>,
+ <code class="literal">lz4</code>, or <code class="literal">zstd</code>, the suffix
+ <code class="filename">.gz</code>, <code class="filename">.lz4</code>, or
+ <code class="filename">.zst</code>, respectively, will be automatically added to
+ all tar filenames. When the plain format is used, client-side
+ compression may not be specified, but it is still possible to request
+ server-side compression. If this is done, the server will compress the
+ backup for transmission, and the client will decompress and extract it.
+ </p><p>
+ When this option is used in combination with
+ <code class="literal">-Xstream</code>, <code class="literal">pg_wal.tar</code> will
+ be compressed using <code class="literal">gzip</code> if client-side gzip
+ compression is selected, but will not be compressed if any other
+ compression algorithm is selected, or if server-side compression
+ is selected.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control the generation of the
+ backup and the invocation of the program:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-c {fast|spread}</code><br /></span><span class="term"><code class="option">--checkpoint={fast|spread}</code></span></dt><dd><p>
+ Sets checkpoint mode to fast (immediate) or spread (the default)
+ (see <a class="xref" href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP" title="26.3.3. Making a Base Backup Using the Low Level API">Section 26.3.3</a>).
+ </p></dd><dt><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>
+ Specifies that the replication slot named by the
+ <code class="literal">--slot</code> option should be created before starting
+ the backup. An error is raised if the slot already exists.
+ </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>label</code></em></code><br /></span><span class="term"><code class="option">--label=<em class="replaceable"><code>label</code></em></code></span></dt><dd><p>
+ Sets the label for the backup. If none is specified, a default value of
+ <span class="quote">“<span class="quote"><code class="literal">pg_basebackup base backup</code></span>”</span> will be used.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-clean</code></span></dt><dd><p>
+ By default, when <code class="command">pg_basebackup</code> aborts with an
+ error, it removes any directories it might have created before
+ discovering that it cannot finish the job (for example, the target
+ directory and write-ahead log directory). This option inhibits
+ tidying-up and is thus useful for debugging.
+ </p><p>
+ Note that tablespace directories are not cleaned up either way.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_basebackup</code> will wait for all files
+ to be written safely to disk. This option causes
+ <code class="command">pg_basebackup</code> to return without waiting, which is
+ faster, but means that a subsequent operating system crash can leave
+ the base backup corrupt. Generally, this option is useful for testing
+ but should not be used when creating a production installation.
+ </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
+ Enables progress reporting. Turning this on will deliver an approximate
+ progress report during the backup. Since the database may change during
+ the backup, this is only an approximation and may not end at exactly
+ <code class="literal">100%</code>. In particular, when WAL log is included in the
+ backup, the total amount of data cannot be estimated in advance, and
+ in this case the estimated target size will increase once it passes the
+ total estimate without WAL.
+ </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>rate</code></em></code><br /></span><span class="term"><code class="option">--max-rate=<em class="replaceable"><code>rate</code></em></code></span></dt><dd><p>
+ Sets the maximum transfer rate at which data is collected from the
+ source server. This can be useful to limit the impact
+ of <span class="application">pg_basebackup</span> on the server. Values
+ are in kilobytes per second. Use a suffix of <code class="literal">M</code>
+ to indicate megabytes per second. A suffix of <code class="literal">k</code>
+ is also accepted, and has no effect. Valid values are between 32
+ kilobytes per second and 1024 megabytes per second.
+ </p><p>
+ This option always affects transfer of the data directory. Transfer of
+ WAL files is only affected if the collection method
+ is <code class="literal">fetch</code>.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>slotname</code></em></code><br /></span><span class="term"><code class="option">--slot=<em class="replaceable"><code>slotname</code></em></code></span></dt><dd><p>
+ This option can only be used together with <code class="literal">-X
+ stream</code>. It causes WAL streaming to use the specified
+ replication slot. If the base backup is intended to be used as a
+ streaming-replication standby using a replication slot, the standby
+ should then use the same replication slot name as
+ <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">primary_slot_name</a>. This ensures that the
+ primary server does not remove any necessary WAL data in the time
+ between the end of the base backup and the start of streaming
+ replication on the new standby.
+ </p><p>
+ The specified replication slot has to exist unless the
+ option <code class="option">-C</code> is also used.
+ </p><p>
+ If this option is not specified and the server supports temporary
+ replication slots (version 10 and later), then a temporary replication
+ slot is automatically used for WAL streaming.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Enables verbose mode. Will output some extra steps during startup and
+ shutdown, as well as show the exact file name that is currently being
+ processed if progress reporting is also enabled.
+ </p></dd><dt><span class="term"><code class="option">--manifest-checksums=<em class="replaceable"><code>algorithm</code></em></code></span></dt><dd><p>
+ Specifies the checksum algorithm that should be applied to each file
+ included in the backup manifest. Currently, the available
+ algorithms are <code class="literal">NONE</code>, <code class="literal">CRC32C</code>,
+ <code class="literal">SHA224</code>, <code class="literal">SHA256</code>,
+ <code class="literal">SHA384</code>, and <code class="literal">SHA512</code>.
+ The default is <code class="literal">CRC32C</code>.
+ </p><p>
+ If <code class="literal">NONE</code> is selected, the backup manifest will
+ not contain any checksums. Otherwise, it will contain a checksum
+ of each file in the backup using the specified algorithm. In addition,
+ the manifest will always contain a <code class="literal">SHA256</code>
+ checksum of its own contents. The <code class="literal">SHA</code> algorithms
+ are significantly more CPU-intensive than <code class="literal">CRC32C</code>,
+ so selecting one of them may increase the time required to complete
+ the backup.
+ </p><p>
+ Using a SHA hash function provides a cryptographically secure digest
+ of each file for users who wish to verify that the backup has not been
+ tampered with, while the CRC32C algorithm provides a checksum that is
+ much faster to calculate; it is good at catching errors due to accidental
+ changes but is not resistant to malicious modifications. Note that, to
+ be useful against an adversary who has access to the backup, the backup
+ manifest would need to be stored securely elsewhere or otherwise
+ verified not to have been modified since the backup was taken.
+ </p><p>
+ <a class="xref" href="app-pgverifybackup.html" title="pg_verifybackup"><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></a> can be used to check the
+ integrity of a backup against the backup manifest.
+ </p></dd><dt><span class="term"><code class="option">--manifest-force-encode</code></span></dt><dd><p>
+ Forces all filenames in the backup manifest to be hex-encoded.
+ If this option is not specified, only non-UTF8 filenames are
+ hex-encoded. This option is mostly intended to test that tools which
+ read a backup manifest file properly handle this case.
+ </p></dd><dt><span class="term"><code class="option">--no-estimate-size</code></span></dt><dd><p>
+ Prevents the server from estimating the total
+ amount of backup data that will be streamed, resulting in the
+ <code class="structfield">backup_total</code> column in the
+ <code class="structname">pg_stat_progress_basebackup</code> view
+ always being <code class="literal">NULL</code>.
+ </p><p>
+ Without this option, the backup will start by enumerating
+ the size of the entire database, and then go back and send
+ the actual contents. This may make the backup take slightly
+ longer, and in particular it will take longer before the first
+ data is sent. This option is useful to avoid such estimation
+ time if it's too long.
+ </p><p>
+ This option is not allowed when using <code class="option">--progress</code>.
+ </p></dd><dt><span class="term"><code class="option">--no-manifest</code></span></dt><dd><p>
+ Disables generation of a backup manifest. If this option is not
+ specified, the server will generate and send a backup manifest
+ which can be verified using <a class="xref" href="app-pgverifybackup.html" title="pg_verifybackup"><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></a>.
+ The manifest is a list of every file present in the backup with the
+ exception of any WAL files that may be included. It also stores the
+ size, last modification time, and an optional checksum for each file.
+ </p></dd><dt><span class="term"><code class="option">--no-slot</code></span></dt><dd><p>
+ Prevents the creation of a temporary replication slot
+ for the backup.
+ </p><p>
+ By default, if log streaming is selected but no slot name is given
+ with the <code class="option">-S</code> option, then a temporary replication
+ slot is created (if supported by the source server).
+ </p><p>
+ The main purpose of this option is to allow taking a base backup when
+ the server has no free replication slots. Using a replication slot
+ is almost always preferred, because it prevents needed WAL from being
+ removed by the server during the backup.
+ </p></dd><dt><span class="term"><code class="option">--no-verify-checksums</code></span></dt><dd><p>
+ Disables verification of checksums, if they are enabled on the server
+ the base backup is taken from.
+ </p><p>
+ By default, checksums are verified and checksum failures will result
+ in a non-zero exit status. However, the base backup will not be
+ removed in such a case, as if the <code class="option">--no-clean</code> option
+ had been used. Checksum verification failures will also be reported
+ in the <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW" title="28.2.15. pg_stat_database">
+ <code class="structname">pg_stat_database</code></a> view.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control the connection to the source
+ server:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>connstr</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
+ Specifies parameters used to connect to the server, as a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>; these
+ will override any conflicting command line options.
+ </p><p>
+ The option is called <code class="literal">--dbname</code> for consistency with other
+ client applications, but because <span class="application">pg_basebackup</span>
+ doesn't connect to any particular database in the cluster, any database
+ name in the connection string will be ignored.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for a Unix domain socket. The default is taken
+ from the <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>interval</code></em></code><br /></span><span class="term"><code class="option">--status-interval=<em class="replaceable"><code>interval</code></em></code></span></dt><dd><p>
+ Specifies the number of seconds between status packets sent back to
+ the source server. Smaller values allow more accurate monitoring of
+ backup progress from the server.
+ A value of zero disables periodic status updates completely,
+ although an update will still be sent when requested by the server, to
+ avoid timeout-based disconnects. The default value is 10 seconds.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Specifies the user name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Prevents issuing a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Forces <span class="application">pg_basebackup</span> to prompt for a
+ password before connecting to the source server.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_basebackup</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_basebackup</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Prints the <span class="application">pg_basebackup</span> version and exits.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Shows help about <span class="application">pg_basebackup</span> command line
+ arguments, and exits.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.10.7"><h2>Environment</h2><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.4.10.8"><h2>Notes</h2><p>
+ At the beginning of the backup, a checkpoint needs to be performed on the
+ source server. This can take some time (especially if the option
+ <code class="literal">--checkpoint=fast</code> is not used), during
+ which <span class="application">pg_basebackup</span> will appear to be idle.
+ </p><p>
+ The backup will include all files in the data directory and tablespaces,
+ including the configuration files and any additional files placed in the
+ directory by third parties, except certain temporary files managed by
+ PostgreSQL. But only regular files and directories are copied, except that
+ symbolic links used for tablespaces are preserved. Symbolic links pointing
+ to certain directories known to PostgreSQL are copied as empty directories.
+ Other symbolic links and special device files are skipped.
+ See <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> for the precise details.
+ </p><p>
+ In plain format, tablespaces will be backed up to the same path
+ they have on the source server, unless the
+ option <code class="literal">--tablespace-mapping</code> is used. Without
+ this option, running a plain format base backup on the same host as the
+ server will not work if tablespaces are in use, because the backup would
+ have to be written to the same directory locations as the original
+ tablespaces.
+ </p><p>
+ When tar format is used, it is the user's responsibility to unpack each
+ tar file before starting a PostgreSQL server that uses the data. If there
+ are additional tablespaces, the
+ tar files for them need to be unpacked in the correct locations. In this
+ case the symbolic links for those tablespaces will be created by the server
+ according to the contents of the <code class="filename">tablespace_map</code> file that is
+ included in the <code class="filename">base.tar</code> file.
+ </p><p>
+ <span class="application">pg_basebackup</span> works with servers of the same
+ or an older major version, down to 9.1. However, WAL streaming mode (<code class="literal">-X
+ stream</code>) only works with server version 9.3 and later, and tar format
+ (<code class="literal">--format=tar</code>) only works with server version 9.5
+ and later.
+ </p><p>
+ <span class="application">pg_basebackup</span> will preserve group permissions
+ for data files if group permissions are enabled on the source cluster.
+ </p></div><div class="refsect1" id="id-1.9.4.10.9"><h2>Examples</h2><p>
+ To create a base backup of the server at <code class="literal">mydbserver</code>
+ and store it in the local directory
+ <code class="filename">/usr/local/pgsql/data</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ </p><p>
+ To create a backup of the local server with one compressed
+ tar file for each tablespace, and store it in the directory
+ <code class="filename">backup</code>, showing a progress report while running:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -D backup -Ft -z -P</code></strong>
+</pre><p>
+ </p><p>
+ To create a backup of a single-tablespace local database and compress
+ this with <span class="productname">bzip2</span>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -D - -Ft -X fetch | bzip2 &gt; backup.tar.bz2</code></strong>
+</pre><p>
+ (This command will fail if there are multiple tablespaces in the
+ database.)
+ </p><p>
+ To create a backup of a local database where the tablespace in
+ <code class="filename">/opt/ts</code> is relocated
+ to <code class="filename">./backup/ts</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts</code></strong>
+</pre><p>
+ To create a backup of a local server with one tar file for each tablespace
+ compressed with <span class="application">gzip</span> at level 9, stored in the
+ directory <code class="filename">backup</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -D backup -Ft --compress=gzip:9</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.10.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a>, <a class="xref" href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING" title="28.4.5. Base Backup Progress Reporting">Section 28.4.5</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgamcheck.html" title="pg_amcheck">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgbench.html" title="pgbench">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_amcheck</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pgbench</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgchecksums.html b/doc/src/sgml/html/app-pgchecksums.html
new file mode 100644
index 0000000..8e940c1
--- /dev/null
+++ b/doc/src/sgml/html/app-pgchecksums.html
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_checksums</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgarchivecleanup.html" title="pg_archivecleanup" /><link rel="next" href="app-pgcontroldata.html" title="pg_controldata" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_checksums</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgarchivecleanup.html" title="pg_archivecleanup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgcontroldata.html" title="pg_controldata">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGCHECKSUMS"><div class="titlepage"></div><a id="id-1.9.5.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_checksums</span></span></h2><p>pg_checksums — enable, disable or check data checksums in a <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.5.4.1"><code class="command">pg_checksums</code> [<em class="replaceable"><code>option</code></em>...] [[ <code class="option">-D</code> | <code class="option">--pgdata</code> ]<em class="replaceable"><code>datadir</code></em>]</p></div></div><div class="refsect1" id="R1-APP-PG_CHECKSUMS-1"><h2>Description</h2><p>
+ <span class="application">pg_checksums</span> checks, enables or disables data
+ checksums in a <span class="productname">PostgreSQL</span> cluster. The server
+ must be shut down cleanly before running
+ <span class="application">pg_checksums</span>. When verifying checksums, the exit
+ status is zero if there are no checksum errors, and nonzero if at least one
+ checksum failure is detected. When enabling or disabling checksums, the
+ exit status is nonzero if the operation failed.
+ </p><p>
+ When verifying checksums, every file in the cluster is scanned. When
+ enabling checksums, each relation file block with a changed checksum is
+ rewritten in-place.
+ Disabling checksums only updates the file <code class="filename">pg_control</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.5.6"><h2>Options</h2><p>
+ The following command-line options are available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specifies the directory where the database cluster is stored.
+ </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--check</code></span></dt><dd><p>
+ Checks checksums. This is the default mode if nothing else is
+ specified.
+ </p></dd><dt><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--disable</code></span></dt><dd><p>
+ Disables checksums.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--enable</code></span></dt><dd><p>
+ Enables checksums.
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filenode</code></em></code><br /></span><span class="term"><code class="option">--filenode=<em class="replaceable"><code>filenode</code></em></code></span></dt><dd><p>
+ Only validate checksums in the relation with filenode
+ <em class="replaceable"><code>filenode</code></em>.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_checksums</code> will wait for all files
+ to be written safely to disk. This option causes
+ <code class="command">pg_checksums</code> to return without waiting, which is
+ faster, but means that a subsequent operating system crash can leave
+ the updated data directory corrupt. Generally, this option is useful
+ for testing but should not be used on a production installation.
+ This option has no effect when using <code class="literal">--check</code>.
+ </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
+ Enable progress reporting. Turning this on will deliver a progress
+ report while checking or enabling checksums.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Enable verbose output. Lists all checked files.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_checksums</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_checksums</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.5.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Specifies the directory where the database cluster is
+ stored; can be overridden using the <code class="option">-D</code> option.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.5.8"><h2>Notes</h2><p>
+ Enabling checksums in a large cluster can potentially take a long time.
+ During this operation, the cluster or other programs that write to the
+ data directory must not be started or else data loss may occur.
+ </p><p>
+ When using a replication setup with tools which perform direct copies
+ of relation file blocks (for example <a class="xref" href="app-pgrewind.html" title="pg_rewind"><span class="refentrytitle"><span class="application">pg_rewind</span></span></a>),
+ enabling or disabling checksums can lead to page corruptions in the
+ shape of incorrect checksums if the operation is not done consistently
+ across all nodes. When enabling or disabling checksums in a replication
+ setup, it is thus recommended to stop all the clusters before switching
+ them all consistently. Destroying all standbys, performing the operation
+ on the primary and finally recreating the standbys from scratch is also
+ safe.
+ </p><p>
+ If <span class="application">pg_checksums</span> is aborted or killed while
+ enabling or disabling checksums, the cluster's data checksum configuration
+ remains unchanged, and <span class="application">pg_checksums</span> can be
+ re-run to perform the same operation.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgarchivecleanup.html" title="pg_archivecleanup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgcontroldata.html" title="pg_controldata">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_archivecleanup</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_controldata</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgconfig.html b/doc/src/sgml/html/app-pgconfig.html
new file mode 100644
index 0000000..e37f8de
--- /dev/null
+++ b/doc/src/sgml/html/app-pgconfig.html
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_config</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgbench.html" title="pgbench" /><link rel="next" href="app-pgdump.html" title="pg_dump" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_config</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgbench.html" title="pgbench">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgdump.html" title="pg_dump">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGCONFIG"><div class="titlepage"></div><a id="id-1.9.4.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_config</span></span></h2><p>pg_config — retrieve information about the installed version of <span class="productname">PostgreSQL</span></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.12.4.1"><code class="command">pg_config</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.12.5"><h2>Description</h2><p>
+ The <span class="application">pg_config</span> utility prints configuration parameters
+ of the currently installed version of <span class="productname">PostgreSQL</span>. It is
+ intended, for example, to be used by software packages that want to interface
+ to <span class="productname">PostgreSQL</span> to facilitate finding the required header files
+ and libraries.
+ </p></div><div class="refsect1" id="id-1.9.4.12.6"><h2>Options</h2><p>
+ To use <span class="application">pg_config</span>, supply one or more of the following
+ options:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--bindir</code></span></dt><dd><p>
+ Print the location of user executables. Use this, for example, to find
+ the <code class="command">psql</code> program. This is normally also the location
+ where the <code class="filename">pg_config</code> program resides.
+ </p></dd><dt><span class="term"><code class="option">--docdir</code></span></dt><dd><p>
+ Print the location of documentation files.
+ </p></dd><dt><span class="term"><code class="option">--htmldir</code></span></dt><dd><p>
+ Print the location of HTML documentation files.
+ </p></dd><dt><span class="term"><code class="option">--includedir</code></span></dt><dd><p>
+ Print the location of C header files of the client interfaces.
+ </p></dd><dt><span class="term"><code class="option">--pkgincludedir</code></span></dt><dd><p>
+ Print the location of other C header files.
+ </p></dd><dt><span class="term"><code class="option">--includedir-server</code></span></dt><dd><p>
+ Print the location of C header files for server programming.
+ </p></dd><dt><span class="term"><code class="option">--libdir</code></span></dt><dd><p>
+ Print the location of object code libraries.
+ </p></dd><dt><span class="term"><code class="option">--pkglibdir</code></span></dt><dd><p>
+ Print the location of dynamically loadable modules, or where
+ the server would search for them. (Other
+ architecture-dependent data files might also be installed in this
+ directory.)
+ </p></dd><dt><span class="term"><code class="option">--localedir</code></span></dt><dd><p>
+ Print the location of locale support files. (This will be an empty
+ string if locale support was not configured when
+ <span class="productname">PostgreSQL</span> was built.)
+ </p></dd><dt><span class="term"><code class="option">--mandir</code></span></dt><dd><p>
+ Print the location of manual pages.
+ </p></dd><dt><span class="term"><code class="option">--sharedir</code></span></dt><dd><p>
+ Print the location of architecture-independent support files.
+ </p></dd><dt><span class="term"><code class="option">--sysconfdir</code></span></dt><dd><p>
+ Print the location of system-wide configuration files.
+ </p></dd><dt><span class="term"><code class="option">--pgxs</code></span></dt><dd><p>
+ Print the location of extension makefiles.
+ </p></dd><dt><span class="term"><code class="option">--configure</code></span></dt><dd><p>
+ Print the options that were given to the <code class="filename">configure</code>
+ script when <span class="productname">PostgreSQL</span> was configured for building.
+ This can be used to reproduce the identical configuration, or
+ to find out with what options a binary package was built. (Note
+ however that binary packages often contain vendor-specific custom
+ patches.) See also the examples below.
+ </p></dd><dt><span class="term"><code class="option">--cc</code></span></dt><dd><p>
+ Print the value of the <code class="varname">CC</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows the C compiler used.
+ </p></dd><dt><span class="term"><code class="option">--cppflags</code></span></dt><dd><p>
+ Print the value of the <code class="varname">CPPFLAGS</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows C compiler switches needed
+ at preprocessing time (typically, <code class="literal">-I</code> switches).
+ </p></dd><dt><span class="term"><code class="option">--cflags</code></span></dt><dd><p>
+ Print the value of the <code class="varname">CFLAGS</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows C compiler switches.
+ </p></dd><dt><span class="term"><code class="option">--cflags_sl</code></span></dt><dd><p>
+ Print the value of the <code class="varname">CFLAGS_SL</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows extra C compiler switches
+ used for building shared libraries.
+ </p></dd><dt><span class="term"><code class="option">--ldflags</code></span></dt><dd><p>
+ Print the value of the <code class="varname">LDFLAGS</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows linker switches.
+ </p></dd><dt><span class="term"><code class="option">--ldflags_ex</code></span></dt><dd><p>
+ Print the value of the <code class="varname">LDFLAGS_EX</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows linker switches
+ used for building executables only.
+ </p></dd><dt><span class="term"><code class="option">--ldflags_sl</code></span></dt><dd><p>
+ Print the value of the <code class="varname">LDFLAGS_SL</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This shows linker switches
+ used for building shared libraries only.
+ </p></dd><dt><span class="term"><code class="option">--libs</code></span></dt><dd><p>
+ Print the value of the <code class="varname">LIBS</code> variable that was used for building
+ <span class="productname">PostgreSQL</span>. This normally contains <code class="literal">-l</code>
+ switches for external libraries linked into <span class="productname">PostgreSQL</span>.
+ </p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the version of <span class="productname">PostgreSQL</span>.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_config</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+
+ If more than one option is given, the information is printed in that order,
+ one item per line. If no options are given, all available information
+ is printed, with labels.
+ </p></div><div class="refsect1" id="id-1.9.4.12.7"><h2>Notes</h2><p>
+ The options <code class="option">--docdir</code>, <code class="option">--pkgincludedir</code>,
+ <code class="option">--localedir</code>, <code class="option">--mandir</code>,
+ <code class="option">--sharedir</code>, <code class="option">--sysconfdir</code>,
+ <code class="option">--cc</code>, <code class="option">--cppflags</code>,
+ <code class="option">--cflags</code>, <code class="option">--cflags_sl</code>,
+ <code class="option">--ldflags</code>, <code class="option">--ldflags_sl</code>,
+ and <code class="option">--libs</code> were added in <span class="productname">PostgreSQL</span> 8.1.
+ The option <code class="option">--htmldir</code> was added in <span class="productname">PostgreSQL</span> 8.4.
+ The option <code class="option">--ldflags_ex</code> was added in <span class="productname">PostgreSQL</span> 9.0.
+ </p></div><div class="refsect1" id="id-1.9.4.12.8"><h2>Example</h2><p>
+ To reproduce the build configuration of the current PostgreSQL
+ installation, run the following command:
+</p><pre class="programlisting">
+eval ./configure `pg_config --configure`
+</pre><p>
+ The output of <code class="literal">pg_config --configure</code> contains
+ shell quotation marks so arguments with spaces are represented
+ correctly. Therefore, using <code class="literal">eval</code> is required
+ for proper results.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgbench.html" title="pgbench">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgdump.html" title="pg_dump">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pgbench</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_dump</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgcontroldata.html b/doc/src/sgml/html/app-pgcontroldata.html
new file mode 100644
index 0000000..79f6509
--- /dev/null
+++ b/doc/src/sgml/html/app-pgcontroldata.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_controldata</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgchecksums.html" title="pg_checksums" /><link rel="next" href="app-pg-ctl.html" title="pg_ctl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_controldata</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgchecksums.html" title="pg_checksums">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pg-ctl.html" title="pg_ctl">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGCONTROLDATA"><div class="titlepage"></div><a id="id-1.9.5.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_controldata</span></span></h2><p>pg_controldata — display control information of a <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.6.4.1"><code class="command">pg_controldata</code> [<em class="replaceable"><code>option</code></em>] [[ <code class="option">-D</code> | <code class="option">--pgdata</code> ]<em class="replaceable"><code>datadir</code></em>]</p></div></div><div class="refsect1" id="R1-APP-PGCONTROLDATA-1"><h2>Description</h2><p>
+ <code class="command">pg_controldata</code> prints information initialized during
+ <code class="command">initdb</code>, such as the catalog version.
+ It also shows information about write-ahead logging and checkpoint
+ processing. This information is cluster-wide, and not specific to any one
+ database.
+ </p><p>
+ This utility can only be run by the user who initialized the cluster because
+ it requires read access to the data directory.
+ You can specify the data directory on the command line, or use
+ the environment variable <code class="envar">PGDATA</code>. This utility supports the options
+ <code class="option">-V</code> and <code class="option">--version</code>, which print the
+ <span class="application">pg_controldata</span> version and exit. It also
+ supports options <code class="option">-?</code> and <code class="option">--help</code>, which output the
+ supported arguments.
+ </p></div><div class="refsect1" id="id-1.9.5.6.6"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Default data directory location
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgchecksums.html" title="pg_checksums">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pg-ctl.html" title="pg_ctl">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_checksums</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_ctl</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgdump.html b/doc/src/sgml/html/app-pgdump.html
new file mode 100644
index 0000000..a27bd9a
--- /dev/null
+++ b/doc/src/sgml/html/app-pgdump.html
@@ -0,0 +1,824 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_dump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgconfig.html" title="pg_config" /><link rel="next" href="app-pg-dumpall.html" title="pg_dumpall" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_dump</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgconfig.html" title="pg_config">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pg-dumpall.html" title="pg_dumpall">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGDUMP"><div class="titlepage"></div><a id="id-1.9.4.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_dump</span></span></h2><p>pg_dump —
+ extract a <span class="productname">PostgreSQL</span> database into a script file or other archive file
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.13.4.1"><code class="command">pg_dump</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="PG-DUMP-DESCRIPTION"><h2>Description</h2><p>
+ <span class="application">pg_dump</span> is a utility for backing up a
+ <span class="productname">PostgreSQL</span> database. It makes consistent
+ backups even if the database is being used concurrently.
+ <span class="application">pg_dump</span> does not block other users
+ accessing the database (readers or writers).
+ </p><p>
+ <span class="application">pg_dump</span> only dumps a single database.
+ To back up an entire cluster, or to back up global objects that are
+ common to all databases in a cluster (such as roles and tablespaces),
+ use <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>.
+ </p><p>
+ Dumps can be output in script or archive file formats. Script
+ dumps are plain-text files containing the SQL commands required
+ to reconstruct the database to the state it was in at the time it was
+ saved. To restore from such a script, feed it to <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>. Script files
+ can be used to reconstruct the database even on other machines and
+ other architectures; with some modifications, even on other SQL
+ database products.
+ </p><p>
+ The alternative archive file formats must be used with
+ <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a> to rebuild the database. They
+ allow <span class="application">pg_restore</span> to be selective about
+ what is restored, or even to reorder the items prior to being
+ restored.
+ The archive file formats are designed to be portable across
+ architectures.
+ </p><p>
+ When used with one of the archive file formats and combined with
+ <span class="application">pg_restore</span>,
+ <span class="application">pg_dump</span> provides a flexible archival and
+ transfer mechanism. <span class="application">pg_dump</span> can be used to
+ backup an entire database, then <span class="application">pg_restore</span>
+ can be used to examine the archive and/or select which parts of the
+ database are to be restored. The most flexible output file formats are
+ the <span class="quote">“<span class="quote">custom</span>”</span> format (<code class="option">-Fc</code>) and the
+ <span class="quote">“<span class="quote">directory</span>”</span> format (<code class="option">-Fd</code>). They allow
+ for selection and reordering of all archived items, support parallel
+ restoration, and are compressed by default. The <span class="quote">“<span class="quote">directory</span>”</span>
+ format is the only format that supports parallel dumps.
+ </p><p>
+ While running <span class="application">pg_dump</span>, one should examine the
+ output for any warnings (printed on standard error), especially in
+ light of the limitations listed below.
+ </p></div><div class="refsect1" id="PG-DUMP-OPTIONS"><h2>Options</h2><p>
+ The following command-line options control the content and
+ format of the output.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
+ Specifies the name of the database to be dumped. If this is
+ not specified, the environment variable
+ <code class="envar">PGDATABASE</code> is used. If that is not set, the
+ user name specified for the connection is used.
+ </p></dd><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--data-only</code></span></dt><dd><p>
+ Dump only the data, not the schema (data definitions).
+ Table data, large objects, and sequence values are dumped.
+ </p><p>
+ This option is similar to, but for historical reasons not identical
+ to, specifying <code class="option">--section=data</code>.
+ </p></dd><dt><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--blobs</code></span></dt><dd><p>
+ Include large objects in the dump. This is the default behavior
+ except when <code class="option">--schema</code>, <code class="option">--table</code>, or
+ <code class="option">--schema-only</code> is specified. The <code class="option">-b</code>
+ switch is therefore only useful to add large objects to dumps
+ where a specific schema or table has been requested. Note that
+ blobs are considered data and therefore will be included when
+ <code class="option">--data-only</code> is used, but not
+ when <code class="option">--schema-only</code> is.
+ </p></dd><dt><span class="term"><code class="option">-B</code><br /></span><span class="term"><code class="option">--no-blobs</code></span></dt><dd><p>
+ Exclude large objects in the dump.
+ </p><p>
+ When both <code class="option">-b</code> and <code class="option">-B</code> are given, the behavior
+ is to output large objects, when data is being dumped, see the
+ <code class="option">-b</code> documentation.
+ </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--clean</code></span></dt><dd><p>
+ Output commands to <code class="command">DROP</code> all the dumped
+ database objects prior to outputting the commands for creating them.
+ This option is useful when the restore is to overwrite an existing
+ database. If any of the objects do not exist in the destination
+ database, ignorable error messages will be reported during
+ restore, unless <code class="option">--if-exists</code> is also specified.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--create</code></span></dt><dd><p>
+ Begin the output with a command to create the
+ database itself and reconnect to the created database. (With a
+ script of this form, it doesn't matter which database in the
+ destination installation you connect to before running the script.)
+ If <code class="option">--clean</code> is also specified, the script drops and
+ recreates the target database before reconnecting to it.
+ </p><p>
+ With <code class="option">--create</code>, the output also includes the
+ database's comment if any, and any configuration variable settings
+ that are specific to this database, that is,
+ any <code class="command">ALTER DATABASE ... SET ...</code>
+ and <code class="command">ALTER ROLE ... IN DATABASE ... SET ...</code>
+ commands that mention this database.
+ Access privileges for the database itself are also dumped,
+ unless <code class="option">--no-acl</code> is specified.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">-e <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--extension=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Dump only extensions matching <em class="replaceable"><code>pattern</code></em>. When this option is not
+ specified, all non-system extensions in the target database will be
+ dumped. Multiple extensions can be selected by writing multiple
+ <code class="option">-e</code> switches. The <em class="replaceable"><code>pattern</code></em> parameter is interpreted as a
+ pattern according to the same rules used by
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands (see
+ <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>), so multiple extensions can also
+ be selected by writing wildcard characters in the pattern. When using
+ wildcards, be careful to quote the pattern if needed to prevent the
+ shell from expanding the wildcards.
+ </p><p>
+ Any configuration relation registered by
+ <code class="function">pg_extension_config_dump</code> is included in the
+ dump if its extension is specified by <code class="option">--extension</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="option">-e</code> is specified,
+ <span class="application">pg_dump</span> makes no attempt to dump any other
+ database objects that the selected extension(s) might depend upon.
+ Therefore, there is no guarantee that the results of a
+ specific-extension dump can be successfully restored by themselves
+ into a clean database.
+ </p></div></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
+ Create the dump in the specified character set encoding. By default,
+ the dump is created in the database encoding. (Another way to get the
+ same result is to set the <code class="envar">PGCLIENTENCODING</code> environment
+ variable to the desired dump encoding.) The supported encodings are
+ described in <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>file</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>file</code></em></code></span></dt><dd><p>
+ Send output to the specified file. This parameter can be omitted for
+ file based output formats, in which case the standard output is used.
+ It must be given for the directory output format however, where it
+ specifies the target directory instead of a file. In this case the
+ directory is created by <code class="command">pg_dump</code> and must not exist
+ before.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>format</code></em></code><br /></span><span class="term"><code class="option">--format=<em class="replaceable"><code>format</code></em></code></span></dt><dd><p>
+ Selects the format of the output.
+ <em class="replaceable"><code>format</code></em> can be one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">p</code><br /></span><span class="term"><code class="literal">plain</code></span></dt><dd><p>
+ Output a plain-text <acronym class="acronym">SQL</acronym> script file (the default).
+ </p></dd><dt><span class="term"><code class="literal">c</code><br /></span><span class="term"><code class="literal">custom</code></span></dt><dd><p>
+ Output a custom-format archive suitable for input into
+ <span class="application">pg_restore</span>.
+ Together with the directory output format, this is the most flexible
+ output format in that it allows manual selection and reordering of
+ archived items during restore. This format is also compressed by
+ default.
+ </p></dd><dt><span class="term"><code class="literal">d</code><br /></span><span class="term"><code class="literal">directory</code></span></dt><dd><p>
+ Output a directory-format archive suitable for input into
+ <span class="application">pg_restore</span>. This will create a directory
+ with one file for each table and blob being dumped, plus a
+ so-called Table of Contents file describing the dumped objects in a
+ machine-readable format that <span class="application">pg_restore</span>
+ can read. A directory format archive can be manipulated with
+ standard Unix tools; for example, files in an uncompressed archive
+ can be compressed with the <span class="application">gzip</span> tool.
+ This format is compressed by default and also supports parallel
+ dumps.
+ </p></dd><dt><span class="term"><code class="literal">t</code><br /></span><span class="term"><code class="literal">tar</code></span></dt><dd><p>
+ Output a <code class="command">tar</code>-format archive suitable for input
+ into <span class="application">pg_restore</span>. The tar format is
+ compatible with the directory format: extracting a tar-format
+ archive produces a valid directory-format archive.
+ However, the tar format does not support compression. Also, when
+ using tar format the relative order of table data items cannot be
+ changed during restore.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>njobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>njobs</code></em></code></span></dt><dd><p>
+ Run the dump in parallel by dumping <em class="replaceable"><code>njobs</code></em>
+ tables simultaneously. This option may reduce the time needed to perform the dump but it also
+ increases the load on the database server. You can only use this option with the
+ directory output format because this is the only output format where multiple processes
+ can write their data at the same time.
+ </p><p><span class="application">pg_dump</span> will open <em class="replaceable"><code>njobs</code></em>
+ + 1 connections to the database, so make sure your <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>
+ setting is high enough to accommodate all connections.
+ </p><p>
+ Requesting exclusive locks on database objects while running a parallel dump could
+ cause the dump to fail. The reason is that the <span class="application">pg_dump</span> leader process
+ requests shared locks (<a class="link" href="explicit-locking.html#LOCKING-TABLES" title="13.3.1. Table-Level Locks">ACCESS SHARE</a>) on the
+ objects that the worker processes are going to dump later in order to
+ make sure that nobody deletes them and makes them go away while the dump is running.
+ If another client then requests an exclusive lock on a table, that lock will not be
+ granted but will be queued waiting for the shared lock of the leader process to be
+ released. Consequently any other access to the table will not be granted either and
+ will queue after the exclusive lock request. This includes the worker process trying
+ to dump the table. Without any precautions this would be a classic deadlock situation.
+ To detect this conflict, the <span class="application">pg_dump</span> worker process requests another
+ shared lock using the <code class="literal">NOWAIT</code> option. If the worker process is not granted
+ this shared lock, somebody else must have requested an exclusive lock in the meantime
+ and there is no way to continue with the dump, so <span class="application">pg_dump</span> has no choice
+ but to abort the dump.
+ </p><p>
+ To perform a parallel dump, the database server needs to support
+ synchronized snapshots, a feature that was introduced in
+ <span class="productname">PostgreSQL</span> 9.2 for primary servers and 10
+ for standbys. With this feature, database clients can ensure they see
+ the same data set even though they use different connections.
+ <code class="command">pg_dump -j</code> uses multiple database connections; it
+ connects to the database once with the leader process and once again
+ for each worker job. Without the synchronized snapshot feature, the
+ different worker jobs wouldn't be guaranteed to see the same data in
+ each connection, which could lead to an inconsistent backup.
+ </p></dd><dt><span class="term"><code class="option">-n <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Dump only schemas matching <em class="replaceable"><code>pattern</code></em>; this selects both the
+ schema itself, and all its contained objects. When this option is
+ not specified, all non-system schemas in the target database will be
+ dumped. Multiple schemas can be
+ selected by writing multiple <code class="option">-n</code> switches. The
+ <em class="replaceable"><code>pattern</code></em> parameter is
+ interpreted as a pattern according to the same rules used by
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands
+ (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below),
+ so multiple schemas can also be selected by writing wildcard characters
+ in the pattern. When using wildcards, be careful to quote the pattern
+ if needed to prevent the shell from expanding the wildcards; see
+ <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="option">-n</code> is specified, <span class="application">pg_dump</span>
+ makes no attempt to dump any other database objects that the selected
+ schema(s) might depend upon. Therefore, there is no guarantee
+ that the results of a specific-schema dump can be successfully
+ restored by themselves into a clean database.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Non-schema objects such as blobs are not dumped when <code class="option">-n</code> is
+ specified. You can add blobs back to the dump with the
+ <code class="option">--blobs</code> switch.
+ </p></div></dd><dt><span class="term"><code class="option">-N <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Do not dump any schemas matching <em class="replaceable"><code>pattern</code></em>. The pattern is
+ interpreted according to the same rules as for <code class="option">-n</code>.
+ <code class="option">-N</code> can be given more than once to exclude schemas
+ matching any of several patterns.
+ </p><p>
+ When both <code class="option">-n</code> and <code class="option">-N</code> are given, the behavior
+ is to dump just the schemas that match at least one <code class="option">-n</code>
+ switch but no <code class="option">-N</code> switches. If <code class="option">-N</code> appears
+ without <code class="option">-n</code>, then schemas matching <code class="option">-N</code> are
+ excluded from what is otherwise a normal dump.
+ </p></dd><dt><span class="term"><code class="option">-O</code><br /></span><span class="term"><code class="option">--no-owner</code></span></dt><dd><p>
+ Do not output commands to set
+ ownership of objects to match the original database.
+ By default, <span class="application">pg_dump</span> issues
+ <code class="command">ALTER OWNER</code> or
+ <code class="command">SET SESSION AUTHORIZATION</code>
+ statements to set ownership of created database objects.
+ These statements
+ will fail when the script is run unless it is started by a superuser
+ (or the same user that owns all of the objects in the script).
+ To make a script that can be restored by any user, but will give
+ that user ownership of all the objects, specify <code class="option">-O</code>.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--no-reconnect</code></span></dt><dd><p>
+ This option is obsolete but still accepted for backwards
+ compatibility.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--schema-only</code></span></dt><dd><p>
+ Dump only the object definitions (schema), not data.
+ </p><p>
+ This option is the inverse of <code class="option">--data-only</code>.
+ It is similar to, but for historical reasons not identical to,
+ specifying
+ <code class="option">--section=pre-data --section=post-data</code>.
+ </p><p>
+ (Do not confuse this with the <code class="option">--schema</code> option, which
+ uses the word <span class="quote">“<span class="quote">schema</span>”</span> in a different meaning.)
+ </p><p>
+ To exclude table data for only a subset of tables in the database,
+ see <code class="option">--exclude-table-data</code>.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--superuser=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Specify the superuser user name to use when disabling triggers.
+ This is relevant only if <code class="option">--disable-triggers</code> is used.
+ (Usually, it's better to leave this out, and instead start the
+ resulting script as superuser.)
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Dump only tables with names matching
+ <em class="replaceable"><code>pattern</code></em>. Multiple tables
+ can be selected by writing multiple <code class="option">-t</code> switches. The
+ <em class="replaceable"><code>pattern</code></em> parameter is
+ interpreted as a pattern according to the same rules used by
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands
+ (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below),
+ so multiple tables can also be selected by writing wildcard characters
+ in the pattern. When using wildcards, be careful to quote the pattern
+ if needed to prevent the shell from expanding the wildcards; see
+ <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
+ </p><p>
+ As well as tables, this option can be used to dump the definition of matching
+ views, materialized views, foreign tables, and sequences. It will not dump the
+ contents of views or materialized views, and the contents of foreign tables will
+ only be dumped if the corresponding foreign server is specified with
+ <code class="option">--include-foreign-data</code>.
+ </p><p>
+ The <code class="option">-n</code> and <code class="option">-N</code> switches have no effect when
+ <code class="option">-t</code> is used, because tables selected by <code class="option">-t</code> will
+ be dumped regardless of those switches, and non-table objects will not
+ be dumped.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="option">-t</code> is specified, <span class="application">pg_dump</span>
+ makes no attempt to dump any other database objects that the selected
+ table(s) might depend upon. Therefore, there is no guarantee
+ that the results of a specific-table dump can be successfully
+ restored by themselves into a clean database.
+ </p></div></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Do not dump any tables matching <em class="replaceable"><code>pattern</code></em>. The pattern is
+ interpreted according to the same rules as for <code class="option">-t</code>.
+ <code class="option">-T</code> can be given more than once to exclude tables
+ matching any of several patterns.
+ </p><p>
+ When both <code class="option">-t</code> and <code class="option">-T</code> are given, the behavior
+ is to dump just the tables that match at least one <code class="option">-t</code>
+ switch but no <code class="option">-T</code> switches. If <code class="option">-T</code> appears
+ without <code class="option">-t</code>, then tables matching <code class="option">-T</code> are
+ excluded from what is otherwise a normal dump.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Specifies verbose mode. This will cause
+ <span class="application">pg_dump</span> to output detailed object
+ comments and start/stop times to the dump file, and progress
+ messages to standard error.
+ Repeating the option causes additional debug-level messages
+ to appear on standard error.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_dump</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--no-privileges</code><br /></span><span class="term"><code class="option">--no-acl</code></span></dt><dd><p>
+ Prevent dumping of access privileges (grant/revoke commands).
+ </p></dd><dt><span class="term"><code class="option">-Z <em class="replaceable"><code>0..9</code></em></code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>0..9</code></em></code></span></dt><dd><p>
+ Specify the compression level to use. Zero means no compression.
+ For the custom and directory archive formats, this specifies compression of
+ individual table-data segments, and the default is to compress
+ at a moderate level.
+ For plain text output, setting a nonzero compression level causes
+ the entire output file to be compressed, as though it had been
+ fed through <span class="application">gzip</span>; but the default is not to compress.
+ The tar archive format currently does not support compression at all.
+ </p></dd><dt><span class="term"><code class="option">--binary-upgrade</code></span></dt><dd><p>
+ This option is for use by in-place upgrade utilities. Its use
+ for other purposes is not recommended or supported. The
+ behavior of the option may change in future releases without
+ notice.
+ </p></dd><dt><span class="term"><code class="option">--column-inserts</code><br /></span><span class="term"><code class="option">--attribute-inserts</code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands with explicit
+ column names (<code class="literal">INSERT INTO
+ <em class="replaceable"><code>table</code></em>
+ (<em class="replaceable"><code>column</code></em>, ...) VALUES
+ ...</code>). This will make restoration very slow; it is mainly
+ useful for making dumps that can be loaded into
+ non-<span class="productname">PostgreSQL</span> databases.
+ Any error during restoring will cause only rows that are part of the
+ problematic <code class="command">INSERT</code> to be lost, rather than the
+ entire table contents.
+ </p></dd><dt><span class="term"><code class="option">--disable-dollar-quoting</code></span></dt><dd><p>
+ This option disables the use of dollar quoting for function bodies,
+ and forces them to be quoted using SQL standard string syntax.
+ </p></dd><dt><span class="term"><code class="option">--disable-triggers</code></span></dt><dd><p>
+ This option is relevant only when creating a data-only dump.
+ It instructs <span class="application">pg_dump</span> to include commands
+ to temporarily disable triggers on the target tables while
+ the data is restored. Use this if you have referential
+ integrity checks or other triggers on the tables that you
+ do not want to invoke during data restore.
+ </p><p>
+ Presently, the commands emitted for <code class="option">--disable-triggers</code>
+ must be done as superuser. So, you should also specify
+ a superuser name with <code class="option">-S</code>, or preferably be careful to
+ start the resulting script as a superuser.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">--enable-row-security</code></span></dt><dd><p>
+ This option is relevant only when dumping the contents of a table
+ which has row security. By default, <span class="application">pg_dump</span> will set
+ <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to off, to ensure
+ that all data is dumped from the table. If the user does not have
+ sufficient privileges to bypass row security, then an error is thrown.
+ This parameter instructs <span class="application">pg_dump</span> to set
+ <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to on instead, allowing the user
+ to dump the parts of the contents of the table that they have access to.
+ </p><p>
+ Note that if you use this option currently, you probably also want
+ the dump be in <code class="command">INSERT</code> format, as the
+ <code class="command">COPY FROM</code> during restore does not support row security.
+ </p></dd><dt><span class="term"><code class="option">--exclude-table-data=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+ Do not dump data for any tables matching <em class="replaceable"><code>pattern</code></em>. The pattern is
+ interpreted according to the same rules as for <code class="option">-t</code>.
+ <code class="option">--exclude-table-data</code> can be given more than once to
+ exclude tables matching any of several patterns. This option is
+ useful when you need the definition of a particular table even
+ though you do not need the data in it.
+ </p><p>
+ To exclude data for all tables in the database, see <code class="option">--schema-only</code>.
+ </p></dd><dt><span class="term"><code class="option">--extra-float-digits=<em class="replaceable"><code>ndigits</code></em></code></span></dt><dd><p>
+ Use the specified value of <code class="option">extra_float_digits</code> when dumping
+ floating-point data, instead of the maximum available precision.
+ Routine dumps made for backup purposes should not use this option.
+ </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
+ Use <code class="literal">DROP ... IF EXISTS</code> commands to drop objects
+ in <code class="option">--clean</code> mode. This suppresses <span class="quote">“<span class="quote">does not
+ exist</span>”</span> errors that might otherwise be reported. This
+ option is not valid unless <code class="option">--clean</code> is also
+ specified.
+ </p></dd><dt><span class="term"><code class="option">--include-foreign-data=<em class="replaceable"><code>foreignserver</code></em></code></span></dt><dd><p>
+ Dump the data for any foreign table with a foreign server
+ matching <em class="replaceable"><code>foreignserver</code></em>
+ pattern. Multiple foreign servers can be selected by writing multiple
+ <code class="option">--include-foreign-data</code> switches.
+ Also, the <em class="replaceable"><code>foreignserver</code></em> parameter is
+ interpreted as a pattern according to the same rules used by
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands
+ (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below),
+ so multiple foreign servers can also be selected by writing wildcard characters
+ in the pattern. When using wildcards, be careful to quote the pattern
+ if needed to prevent the shell from expanding the wildcards; see
+ <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
+ The only exception is that an empty pattern is disallowed.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="option">--include-foreign-data</code> is specified,
+ <span class="application">pg_dump</span> does not check that the foreign
+ table is writable. Therefore, there is no guarantee that the
+ results of a foreign table dump can be successfully restored.
+ </p></div></dd><dt><span class="term"><code class="option">--inserts</code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands (rather
+ than <code class="command">COPY</code>). This will make restoration very slow;
+ it is mainly useful for making dumps that can be loaded into
+ non-<span class="productname">PostgreSQL</span> databases.
+ Any error during restoring will cause only rows that are part of the
+ problematic <code class="command">INSERT</code> to be lost, rather than the
+ entire table contents. Note that the restore might fail altogether if
+ you have rearranged column order. The
+ <code class="option">--column-inserts</code> option is safe against column order
+ changes, though even slower.
+ </p></dd><dt><span class="term"><code class="option">--load-via-partition-root</code></span></dt><dd><p>
+ When dumping data for a table partition, make
+ the <code class="command">COPY</code> or <code class="command">INSERT</code> statements
+ target the root of the partitioning hierarchy that contains it, rather
+ than the partition itself. This causes the appropriate partition to
+ be re-determined for each row when the data is loaded. This may be
+ useful when restoring data on a server where rows do not always fall
+ into the same partitions as they did on the original server. That
+ could happen, for example, if the partitioning column is of type text
+ and the two systems have different definitions of the collation used
+ to sort the partitioning column.
+ </p></dd><dt><span class="term"><code class="option">--lock-wait-timeout=<em class="replaceable"><code>timeout</code></em></code></span></dt><dd><p>
+ Do not wait forever to acquire shared table locks at the beginning of
+ the dump. Instead fail if unable to lock a table within the specified
+ <em class="replaceable"><code>timeout</code></em>. The timeout may be
+ specified in any of the formats accepted by <code class="command">SET
+ statement_timeout</code>. (Allowed formats vary depending on the server
+ version you are dumping from, but an integer number of milliseconds
+ is accepted by all versions.)
+ </p></dd><dt><span class="term"><code class="option">--no-comments</code></span></dt><dd><p>
+ Do not dump comments.
+ </p></dd><dt><span class="term"><code class="option">--no-publications</code></span></dt><dd><p>
+ Do not dump publications.
+ </p></dd><dt><span class="term"><code class="option">--no-security-labels</code></span></dt><dd><p>
+ Do not dump security labels.
+ </p></dd><dt><span class="term"><code class="option">--no-subscriptions</code></span></dt><dd><p>
+ Do not dump subscriptions.
+ </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_dump</code> will wait for all files
+ to be written safely to disk. This option causes
+ <code class="command">pg_dump</code> to return without waiting, which is
+ faster, but means that a subsequent operating system crash can leave
+ the dump corrupt. Generally, this option is useful for testing
+ but should not be used when dumping data from production installation.
+ </p></dd><dt><span class="term"><code class="option">--no-table-access-method</code></span></dt><dd><p>
+ Do not output commands to select table access methods.
+ With this option, all objects will be created with whichever
+ table access method is the default during restore.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">--no-tablespaces</code></span></dt><dd><p>
+ Do not output commands to select tablespaces.
+ With this option, all objects will be created in whichever
+ tablespace is the default during restore.
+ </p><p>
+ This option is ignored when emitting an archive (non-text) output
+ file. For the archive formats, you can specify the option when you
+ call <code class="command">pg_restore</code>.
+ </p></dd><dt><span class="term"><code class="option">--no-toast-compression</code></span></dt><dd><p>
+ Do not output commands to set <acronym class="acronym">TOAST</acronym> compression
+ methods.
+ With this option, all columns will be restored with the default
+ compression setting.
+ </p></dd><dt><span class="term"><code class="option">--no-unlogged-table-data</code></span></dt><dd><p>
+ Do not dump the contents of unlogged tables and sequences. This
+ option has no effect on whether or not the table and sequence
+ definitions (schema) are dumped; it only suppresses dumping the table
+ and sequence data. Data in unlogged tables and sequences
+ is always excluded when dumping from a standby server.
+ </p></dd><dt><span class="term"><code class="option">--on-conflict-do-nothing</code></span></dt><dd><p>
+ Add <code class="literal">ON CONFLICT DO NOTHING</code> to
+ <code class="command">INSERT</code> commands.
+ This option is not valid unless <code class="option">--inserts</code>,
+ <code class="option">--column-inserts</code> or
+ <code class="option">--rows-per-insert</code> is also specified.
+ </p></dd><dt><span class="term"><code class="option">--quote-all-identifiers</code></span></dt><dd><p>
+ Force quoting of all identifiers. This option is recommended when
+ dumping a database from a server whose <span class="productname">PostgreSQL</span>
+ major version is different from <span class="application">pg_dump</span>'s, or when
+ the output is intended to be loaded into a server of a different
+ major version. By default, <span class="application">pg_dump</span> quotes only
+ identifiers that are reserved words in its own major version.
+ This sometimes results in compatibility issues when dealing with
+ servers of other versions that may have slightly different sets
+ of reserved words. Using <code class="option">--quote-all-identifiers</code> prevents
+ such issues, at the price of a harder-to-read dump script.
+ </p></dd><dt><span class="term"><code class="option">--rows-per-insert=<em class="replaceable"><code>nrows</code></em></code></span></dt><dd><p>
+ Dump data as <code class="command">INSERT</code> commands (rather than
+ <code class="command">COPY</code>). Controls the maximum number of rows per
+ <code class="command">INSERT</code> command. The value specified must be a
+ number greater than zero. Any error during restoring will cause only
+ rows that are part of the problematic <code class="command">INSERT</code> to be
+ lost, rather than the entire table contents.
+ </p></dd><dt><span class="term"><code class="option">--section=<em class="replaceable"><code>sectionname</code></em></code></span></dt><dd><p>
+ Only dump the named section. The section name can be
+ <code class="option">pre-data</code>, <code class="option">data</code>, or <code class="option">post-data</code>.
+ This option can be specified more than once to select multiple
+ sections. The default is to dump all sections.
+ </p><p>
+ The data section contains actual table data, large-object
+ contents, and sequence values.
+ Post-data items include definitions of indexes, triggers, rules,
+ and constraints other than validated check constraints.
+ Pre-data items include all other data definition items.
+ </p></dd><dt><span class="term"><code class="option">--serializable-deferrable</code></span></dt><dd><p>
+ Use a <code class="literal">serializable</code> transaction for the dump, to
+ ensure that the snapshot used is consistent with later database
+ states; but do this by waiting for a point in the transaction stream
+ at which no anomalies can be present, so that there isn't a risk of
+ the dump failing or causing other transactions to roll back with a
+ <code class="literal">serialization_failure</code>. See <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>
+ for more information about transaction isolation and concurrency
+ control.
+ </p><p>
+ This option is not beneficial for a dump which is intended only for
+ disaster recovery. It could be useful for a dump used to load a
+ copy of the database for reporting or other read-only load sharing
+ while the original database continues to be updated. Without it the
+ dump may reflect a state which is not consistent with any serial
+ execution of the transactions eventually committed. For example, if
+ batch processing techniques are used, a batch may show as closed in
+ the dump without all of the items which are in the batch appearing.
+ </p><p>
+ This option will make no difference if there are no read-write
+ transactions active when pg_dump is started. If read-write
+ transactions are active, the start of the dump may be delayed for an
+ indeterminate length of time. Once running, performance with or
+ without the switch is the same.
+ </p></dd><dt><span class="term"><code class="option">--snapshot=<em class="replaceable"><code>snapshotname</code></em></code></span></dt><dd><p>
+ Use the specified synchronized snapshot when making a dump of the
+ database (see
+ <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE" title="Table 9.92. Snapshot Synchronization Functions">Table 9.92</a> for more
+ details).
+ </p><p>
+ This option is useful when needing to synchronize the dump with
+ a logical replication slot (see <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>)
+ or with a concurrent session.
+ </p><p>
+ In the case of a parallel dump, the snapshot name defined by this
+ option is used rather than taking a new snapshot.
+ </p></dd><dt><span class="term"><code class="option">--strict-names</code></span></dt><dd><p>
+ Require that each
+ extension (<code class="option">-e</code>/<code class="option">--extension</code>),
+ schema (<code class="option">-n</code>/<code class="option">--schema</code>) and
+ table (<code class="option">-t</code>/<code class="option">--table</code>) qualifier
+ match at least one extension/schema/table in the database to be dumped.
+ Note that if none of the extension/schema/table qualifiers find
+ matches, <span class="application">pg_dump</span> will generate an error
+ even without <code class="option">--strict-names</code>.
+ </p><p>
+ This option has no effect
+ on <code class="option">-N</code>/<code class="option">--exclude-schema</code>,
+ <code class="option">-T</code>/<code class="option">--exclude-table</code>,
+ or <code class="option">--exclude-table-data</code>. An exclude pattern failing
+ to match any objects is not considered an error.
+ </p></dd><dt><span class="term"><code class="option">--use-set-session-authorization</code></span></dt><dd><p>
+ Output SQL-standard <code class="command">SET SESSION AUTHORIZATION</code> commands
+ instead of <code class="command">ALTER OWNER</code> commands to determine object
+ ownership. This makes the dump more standards-compatible, but
+ depending on the history of the objects in the dump, might not restore
+ properly. Also, a dump using <code class="command">SET SESSION AUTHORIZATION</code>
+ will certainly require superuser privileges to restore correctly,
+ whereas <code class="command">ALTER OWNER</code> requires lesser privileges.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_dump</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control the database connection parameters.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to. This is
+ equivalent to specifying <em class="replaceable"><code>dbname</code></em> as the first non-option
+ argument on the command line. The <em class="replaceable"><code>dbname</code></em>
+ can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.
+ If so, connection string parameters will override any conflicting
+ command line options.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_dump</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_dump</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_dump</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--role=<em class="replaceable"><code>rolename</code></em></code></span></dt><dd><p>
+ Specifies a role name to be used to create the dump.
+ This option causes <span class="application">pg_dump</span> to issue a
+ <code class="command">SET ROLE</code> <em class="replaceable"><code>rolename</code></em>
+ command after connecting to the database. It is useful when the
+ authenticated user (specified by <code class="option">-U</code>) lacks privileges
+ needed by <span class="application">pg_dump</span>, but can switch to a role with
+ the required rights. Some installations have a policy against
+ logging in directly as a superuser, and use of this option allows
+ dumps to be made without violating the policy.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.13.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGOPTIONS</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="APP-PGDUMP-DIAGNOSTICS"><h2>Diagnostics</h2><p>
+ <span class="application">pg_dump</span> internally executes
+ <code class="command">SELECT</code> statements. If you have problems running
+ <span class="application">pg_dump</span>, make sure you are able to
+ select information from the database using, for example, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p><p>
+ The database activity of <span class="application">pg_dump</span> is
+ normally collected by the cumulative statistics system. If this is
+ undesirable, you can set parameter <code class="varname">track_counts</code>
+ to false via <code class="envar">PGOPTIONS</code> or the <code class="literal">ALTER
+ USER</code> command.
+ </p></div><div class="refsect1" id="PG-DUMP-NOTES"><h2>Notes</h2><p>
+ If your database cluster has any local additions to the <code class="literal">template1</code> database,
+ be careful to restore the output of <span class="application">pg_dump</span> into a
+ truly empty database; otherwise you are likely to get errors due to
+ duplicate definitions of the added objects. To make an empty database
+ without any local additions, copy from <code class="literal">template0</code> not <code class="literal">template1</code>,
+ for example:
+</p><pre class="programlisting">
+CREATE DATABASE foo WITH TEMPLATE template0;
+</pre><p>
+ </p><p>
+ When a data-only dump is chosen and the option <code class="option">--disable-triggers</code>
+ is used, <span class="application">pg_dump</span> emits commands
+ to disable triggers on user tables before inserting the data,
+ and then commands to re-enable them after the data has been
+ inserted. If the restore is stopped in the middle, the system
+ catalogs might be left in the wrong state.
+ </p><p>
+ The dump file produced by <span class="application">pg_dump</span>
+ does not contain the statistics used by the optimizer to make
+ query planning decisions. Therefore, it is wise to run
+ <code class="command">ANALYZE</code> after restoring from a dump file
+ to ensure optimal performance; see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>
+ and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ </p><p>
+ Because <span class="application">pg_dump</span> is used to transfer data
+ to newer versions of <span class="productname">PostgreSQL</span>, the output of
+ <span class="application">pg_dump</span> can be expected to load into
+ <span class="productname">PostgreSQL</span> server versions newer than
+ <span class="application">pg_dump</span>'s version. <span class="application">pg_dump</span> can also
+ dump from <span class="productname">PostgreSQL</span> servers older than its own version.
+ (Currently, servers back to version 9.2 are supported.)
+ However, <span class="application">pg_dump</span> cannot dump from
+ <span class="productname">PostgreSQL</span> servers newer than its own major version;
+ it will refuse to even try, rather than risk making an invalid dump.
+ Also, it is not guaranteed that <span class="application">pg_dump</span>'s output can
+ be loaded into a server of an older major version — not even if the
+ dump was taken from a server of that version. Loading a dump file
+ into an older server may require manual editing of the dump file
+ to remove syntax not understood by the older server.
+ Use of the <code class="option">--quote-all-identifiers</code> option is recommended
+ in cross-version cases, as it can prevent problems arising from varying
+ reserved-word lists in different <span class="productname">PostgreSQL</span> versions.
+ </p><p>
+ When dumping logical replication subscriptions,
+ <span class="application">pg_dump</span> will generate <code class="command">CREATE
+ SUBSCRIPTION</code> commands that use the <code class="literal">connect = false</code>
+ option, so that restoring the subscription does not make remote connections
+ for creating a replication slot or for initial table copy. That way, the
+ dump can be restored without requiring network access to the remote
+ servers. It is then up to the user to reactivate the subscriptions in a
+ suitable way. If the involved hosts have changed, the connection
+ information might have to be changed. It might also be appropriate to
+ truncate the target tables before initiating a new full table copy. If users
+ intend to copy initial data during refresh they must create the slot with
+ <code class="literal">two_phase = false</code>. After the initial sync, the
+ <code class="literal">two_phase</code> option will be automatically enabled by the
+ subscriber if the subscription had been originally created with
+ <code class="literal">two_phase = true</code> option.
+ </p></div><div class="refsect1" id="PG-DUMP-EXAMPLES"><h2>Examples</h2><p>
+ To dump a database called <code class="literal">mydb</code> into an SQL-script file:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To reload such a script into a (freshly created) database named
+ <code class="literal">newdb</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>psql -d newdb -f db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To dump a database into a custom-format archive file:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fc mydb &gt; db.dump</code></strong>
+</pre><p>
+ </p><p>
+ To dump a database into a directory-format archive:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fd mydb -f dumpdir</code></strong>
+</pre><p>
+ </p><p>
+ To dump a database into a directory-format archive in parallel with
+ 5 worker jobs:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fd mydb -j 5 -f dumpdir</code></strong>
+</pre><p>
+ </p><p>
+ To reload an archive file into a (freshly created) database named
+ <code class="literal">newdb</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -d newdb db.dump</code></strong>
+</pre><p>
+ </p><p>
+ To reload an archive file into the same database it was dumped from,
+ discarding the current contents of that database:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -d postgres --clean --create db.dump</code></strong>
+</pre><p>
+ </p><p>
+ To dump a single table named <code class="literal">mytab</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t mytab mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To dump all tables whose names start with <code class="literal">emp</code> in the
+ <code class="literal">detroit</code> schema, except for the table named
+ <code class="literal">employee_log</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To dump all schemas whose names start with <code class="literal">east</code> or
+ <code class="literal">west</code> and end in <code class="literal">gsm</code>, excluding any schemas whose
+ names contain the word <code class="literal">test</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ The same, using regular expression notation to consolidate the switches:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -n '(east|west)*gsm' -N '*test*' mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To dump all database objects except for tables whose names begin with
+ <code class="literal">ts_</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -T 'ts_*' mydb &gt; db.sql</code></strong>
+</pre><p>
+ </p><p>
+ To specify an upper-case or mixed-case name in <code class="option">-t</code> and related
+ switches, you need to double-quote the name; else it will be folded to
+ lower case (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below). But
+ double quotes are special to the shell, so in turn they must be quoted.
+ Thus, to dump a single table with a mixed-case name, you need something
+ like
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t "\"MixedCaseName\"" mydb &gt; mytab.sql</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.13.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>, <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a>, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgconfig.html" title="pg_config">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pg-dumpall.html" title="pg_dumpall">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_config</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_dumpall</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgreceivewal.html b/doc/src/sgml/html/app-pgreceivewal.html
new file mode 100644
index 0000000..c5e6b06
--- /dev/null
+++ b/doc/src/sgml/html/app-pgreceivewal.html
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_receivewal</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pg-isready.html" title="pg_isready" /><link rel="next" href="app-pgrecvlogical.html" title="pg_recvlogical" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_receivewal</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pg-isready.html" title="pg_isready">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgrecvlogical.html" title="pg_recvlogical">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGRECEIVEWAL"><div class="titlepage"></div><a id="id-1.9.4.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_receivewal</span></span></h2><p>pg_receivewal — stream write-ahead logs from a <span class="productname">PostgreSQL</span> server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.16.4.1"><code class="command">pg_receivewal</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.16.5"><h2>Description</h2><p>
+ <span class="application">pg_receivewal</span> is used to stream the write-ahead log
+ from a running <span class="productname">PostgreSQL</span> cluster. The write-ahead
+ log is streamed using the streaming replication protocol, and is written
+ to a local directory of files. This directory can be used as the archive
+ location for doing a restore using point-in-time recovery (see
+ <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>).
+ </p><p>
+ <span class="application">pg_receivewal</span> streams the write-ahead
+ log in real time as it's being generated on the server, and does not wait
+ for segments to complete like <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> and
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> do.
+ For this reason, it is not necessary to set
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> when using
+ <span class="application">pg_receivewal</span>.
+ </p><p>
+ Unlike the WAL receiver of a PostgreSQL standby server, <span class="application">pg_receivewal</span>
+ by default flushes WAL data only when a WAL file is closed.
+ The option <code class="option">--synchronous</code> must be specified to flush WAL data
+ in real time. Since <span class="application">pg_receivewal</span> does not
+ apply WAL, you should not allow it to become a synchronous standby when
+ <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> equals
+ <code class="literal">remote_apply</code>. If it does, it will appear to be a
+ standby that never catches up, and will cause transaction commits to
+ block. To avoid this, you should either configure an appropriate value
+ for <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a>, or specify
+ <code class="varname">application_name</code> for
+ <span class="application">pg_receivewal</span> that does not match it, or
+ change the value of <code class="varname">synchronous_commit</code> to
+ something other than <code class="literal">remote_apply</code>.
+ </p><p>
+ The write-ahead log is streamed over a regular
+ <span class="productname">PostgreSQL</span> connection and uses the replication
+ protocol. The connection must be made with a user having
+ <code class="literal">REPLICATION</code> permissions (see
+ <a class="xref" href="role-attributes.html" title="22.2. Role Attributes">Section 22.2</a>) or a superuser, and
+ <code class="filename">pg_hba.conf</code> must permit the replication connection.
+ The server must also be configured with
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> set high enough to leave at least
+ one session available for the stream.
+ </p><p>
+ The starting point of the write-ahead log streaming is calculated when
+ <span class="application">pg_receivewal</span> starts:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ First, scan the directory where the WAL segment files are written and
+ find the newest completed segment file, using as the starting point the
+ beginning of the next WAL segment file.
+ </p></li><li class="listitem"><p>
+ If a starting point cannot be calculated with the previous method,
+ and if a replication slot is used, an extra
+ <code class="command">READ_REPLICATION_SLOT</code> command is issued to retrieve
+ the slot's <code class="literal">restart_lsn</code> to use as the starting point.
+ This option is only available when streaming write-ahead logs from
+ <span class="productname">PostgreSQL</span> 15 and up.
+ </p></li><li class="listitem"><p>
+ If a starting point cannot be calculated with the previous method,
+ the latest WAL flush location is used as reported by the server from
+ an <code class="literal">IDENTIFY_SYSTEM</code> command.
+ </p></li></ol></div><p>
+ </p><p>
+ If the connection is lost, or if it cannot be initially established,
+ with a non-fatal error, <span class="application">pg_receivewal</span> will
+ retry the connection indefinitely, and reestablish streaming as soon
+ as possible. To avoid this behavior, use the <code class="literal">-n</code>
+ parameter.
+ </p><p>
+ In the absence of fatal errors, <span class="application">pg_receivewal</span>
+ will run until terminated by the <span class="systemitem">SIGINT</span> signal
+ (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>).
+ </p></div><div class="refsect1" id="id-1.9.4.16.6"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--directory=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Directory to write the output to.
+ </p><p>
+ This parameter is required.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>lsn</code></em></code><br /></span><span class="term"><code class="option">--endpos=<em class="replaceable"><code>lsn</code></em></code></span></dt><dd><p>
+ Automatically stop replication and exit with normal exit status 0 when
+ receiving reaches the specified LSN.
+ </p><p>
+ If there is a record with LSN exactly equal to <em class="replaceable"><code>lsn</code></em>,
+ the record will be processed.
+ </p></dd><dt><span class="term"><code class="option">--if-not-exists</code></span></dt><dd><p>
+ Do not error out when <code class="option">--create-slot</code> is specified
+ and a slot with the specified name already exists.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-loop</code></span></dt><dd><p>
+ Don't loop on connection errors. Instead, exit right away with
+ an error.
+ </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ This option causes <code class="command">pg_receivewal</code> to not force WAL
+ data to be flushed to disk. This is faster, but means that a
+ subsequent operating system crash can leave the WAL segments corrupt.
+ Generally, this option is useful for testing but should not be used
+ when doing WAL archiving on a production deployment.
+ </p><p>
+ This option is incompatible with <code class="literal">--synchronous</code>.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>interval</code></em></code><br /></span><span class="term"><code class="option">--status-interval=<em class="replaceable"><code>interval</code></em></code></span></dt><dd><p>
+ Specifies the number of seconds between status packets sent back to the
+ server. This allows for easier monitoring of the progress from server.
+ A value of zero disables the periodic status updates completely,
+ although an update will still be sent when requested by the server, to
+ avoid timeout disconnect. The default value is 10 seconds.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>slotname</code></em></code><br /></span><span class="term"><code class="option">--slot=<em class="replaceable"><code>slotname</code></em></code></span></dt><dd><p>
+ Require <span class="application">pg_receivewal</span> to use an existing
+ replication slot (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>).
+ When this option is used, <span class="application">pg_receivewal</span> will report
+ a flush position to the server, indicating when each segment has been
+ synchronized to disk so that the server can remove that segment if it
+ is not otherwise needed.
+ </p><p>
+ When the replication client
+ of <span class="application">pg_receivewal</span> is configured on the
+ server as a synchronous standby, then using a replication slot will
+ report the flush position to the server, but only when a WAL file is
+ closed. Therefore, that configuration will cause transactions on the
+ primary to wait for a long time and effectively not work
+ satisfactorily. The option <code class="literal">--synchronous</code> (see
+ below) must be specified in addition to make this work correctly.
+ </p></dd><dt><span class="term"><code class="option">--synchronous</code></span></dt><dd><p>
+ Flush the WAL data to disk immediately after it has been received. Also
+ send a status packet back to the server immediately after flushing,
+ regardless of <code class="literal">--status-interval</code>.
+ </p><p>
+ This option should be specified if the replication client
+ of <span class="application">pg_receivewal</span> is configured on the
+ server as a synchronous standby, to ensure that timely feedback is
+ sent to the server.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Enables verbose mode.
+ </p></dd><dt><span class="term"><code class="option">-Z <em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">-Z <em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code></span></dt><dd><p>
+ Enables compression of write-ahead logs.
+ </p><p>
+ The compression method can be set to <code class="literal">gzip</code>,
+ <code class="literal">lz4</code> (if <span class="productname">PostgreSQL</span>
+ was compiled with <code class="option">--with-lz4</code>) or
+ <code class="literal">none</code> for no compression.
+ A compression detail string can optionally be specified. If the
+ detail string is an integer, it specifies the compression level.
+ Otherwise, it should be a comma-separated list of items, each of the
+ form <code class="literal">keyword</code> or <code class="literal">keyword=value</code>.
+ Currently, the only supported keyword is <code class="literal">level</code>.
+ </p><p>
+ If no compression level is specified, the default compression level
+ will be used. If only a level is specified without mentioning an
+ algorithm, <code class="literal">gzip</code> compression will be used if the
+ level is greater than 0, and no compression will be used if the level
+ is 0.
+ </p><p>
+ The suffix <code class="filename">.gz</code> will automatically be added to
+ all filenames when using <code class="literal">gzip</code>, and the suffix
+ <code class="filename">.lz4</code> is added when using <code class="literal">lz4</code>.
+ </p></dd></dl></div><p>
+ The following command-line options control the database connection parameters.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>connstr</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
+ Specifies parameters used to connect to the server, as a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>; these
+ will override any conflicting command line options.
+ </p><p>
+ The option is called <code class="literal">--dbname</code> for consistency with other
+ client applications, but because <span class="application">pg_receivewal</span>
+ doesn't connect to any particular database in the cluster, database
+ name in the connection string will be ignored.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_receivewal</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_receivewal</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_receivewal</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">pg_receivewal</span> can perform one of the two
+ following actions in order to control physical replication slots:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>
+ Create a new physical replication slot with the name specified in
+ <code class="option">--slot</code>, then exit.
+ </p></dd><dt><span class="term"><code class="option">--drop-slot</code></span></dt><dd><p>
+ Drop the replication slot with the name specified in
+ <code class="option">--slot</code>, then exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_receivewal</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_receivewal</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.16.7"><h2>Exit Status</h2><p>
+ <span class="application">pg_receivewal</span> will exit with status 0 when
+ terminated by the <span class="systemitem">SIGINT</span> signal. (That is the
+ normal way to end it. Hence it is not an error.) For fatal errors or
+ other signals, the exit status will be nonzero.
+ </p></div><div class="refsect1" id="id-1.9.4.16.8"><h2>Environment</h2><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.4.16.9"><h2>Notes</h2><p>
+ When using <span class="application">pg_receivewal</span> instead of
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> as the main WAL backup method, it is
+ strongly recommended to use replication slots. Otherwise, the server is
+ free to recycle or remove write-ahead log files before they are backed up,
+ because it does not have any information, either
+ from <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> or the replication slots, about
+ how far the WAL stream has been archived. Note, however, that a
+ replication slot will fill up the server's disk space if the receiver does
+ not keep up with fetching the WAL data.
+ </p><p>
+ <span class="application">pg_receivewal</span> will preserve group permissions on
+ the received WAL files if group permissions are enabled on the source
+ cluster.
+ </p></div><div class="refsect1" id="id-1.9.4.16.10"><h2>Examples</h2><p>
+ To stream the write-ahead log from the server at
+ <code class="literal">mydbserver</code> and store it in the local directory
+ <code class="filename">/usr/local/pgsql/archive</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.16.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pg-isready.html" title="pg_isready">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgrecvlogical.html" title="pg_recvlogical">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_isready</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_recvlogical</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgreceivexlog.html b/doc/src/sgml/html/app-pgreceivexlog.html
new file mode 100644
index 0000000..459f79e
--- /dev/null
+++ b/doc/src/sgml/html/app-pgreceivexlog.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>O.5. pg_receivexlog renamed to pg_receivewal</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal" /><link rel="next" href="biblio.html" title="Bibliography" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><th width="60%" align="center">Appendix O. Obsolete or Renamed Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="biblio.html" title="Bibliography">Next</a></td></tr></table><hr /></div><div class="sect1" id="APP-PGRECEIVEXLOG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code></h2></div></div></div><a id="id-1.11.16.7.2" class="indexterm"></a><p>
+ PostgreSQL 9.6 and below provided a command named
+ <code class="command">pg_receivexlog</code>
+ <a id="id-1.11.16.7.3.2" class="indexterm"></a>
+ to fetch write-ahead-log (WAL) files. This command was renamed to <code class="command">pg_receivewal</code>, see
+ <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a> for documentation of <code class="command">pg_receivewal</code> and see
+ <a class="link" href="release-prior.html" title="E.7. Prior Releases">the release notes for PostgreSQL 10</a> for details
+ on this change.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="biblio.html" title="Bibliography">Next</a></td></tr><tr><td width="40%" align="left" valign="top">O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Bibliography</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgrecvlogical.html b/doc/src/sgml/html/app-pgrecvlogical.html
new file mode 100644
index 0000000..a6d0c79
--- /dev/null
+++ b/doc/src/sgml/html/app-pgrecvlogical.html
@@ -0,0 +1,177 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_recvlogical</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgreceivewal.html" title="pg_receivewal" /><link rel="next" href="app-pgrestore.html" title="pg_restore" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_recvlogical</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgreceivewal.html" title="pg_receivewal">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgrestore.html" title="pg_restore">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGRECVLOGICAL"><div class="titlepage"></div><a id="id-1.9.4.17.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></h2><p>pg_recvlogical — control <span class="productname">PostgreSQL</span> logical decoding streams</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.17.4.1"><code class="command">pg_recvlogical</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.17.5"><h2>Description</h2><p>
+ <code class="command">pg_recvlogical</code> controls logical decoding replication
+ slots and streams data from such replication slots.
+ </p><p>
+ It creates a replication-mode connection, so it is subject to the same
+ constraints as <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a>, plus those for logical
+ replication (see <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>).
+ </p><p>
+ <code class="command">pg_recvlogical</code> has no equivalent to the logical decoding
+ SQL interface's peek and get modes. It sends replay confirmations for
+ data lazily as it receives it and on clean exit. To examine pending data on
+ a slot without consuming it, use
+ <a class="link" href="functions-admin.html#FUNCTIONS-REPLICATION" title="9.27.6. Replication Management Functions"><code class="function">pg_logical_slot_peek_changes</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.4.17.6"><h2>Options</h2><p>
+ At least one of the following options must be specified to select an action:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>
+ Create a new logical replication slot with the name specified by
+ <code class="option">--slot</code>, using the output plugin specified by
+ <code class="option">--plugin</code>, for the database specified
+ by <code class="option">--dbname</code>.
+ </p><p>
+ The <code class="option">--two-phase</code> can be specified with
+ <code class="option">--create-slot</code> to enable decoding of prepared transactions.
+ </p></dd><dt><span class="term"><code class="option">--drop-slot</code></span></dt><dd><p>
+ Drop the replication slot with the name specified
+ by <code class="option">--slot</code>, then exit.
+ </p></dd><dt><span class="term"><code class="option">--start</code></span></dt><dd><p>
+ Begin streaming changes from the logical replication slot specified
+ by <code class="option">--slot</code>, continuing until terminated by a
+ signal. If the server side change stream ends with a server shutdown
+ or disconnect, retry in a loop unless
+ <code class="option">--no-loop</code> is specified.
+ </p><p>
+ The stream format is determined by the output plugin specified when
+ the slot was created.
+ </p><p>
+ The connection must be to the same database used to create the slot.
+ </p></dd></dl></div><p>
+ </p><p>
+ <code class="option">--create-slot</code> and <code class="option">--start</code> can be
+ specified together. <code class="option">--drop-slot</code> cannot be combined with
+ another action.
+ </p><p>
+ The following command-line options control the location and format of the
+ output and other replication behavior:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-E <em class="replaceable"><code>lsn</code></em></code><br /></span><span class="term"><code class="option">--endpos=<em class="replaceable"><code>lsn</code></em></code></span></dt><dd><p>
+ In <code class="option">--start</code> mode, automatically stop replication
+ and exit with normal exit status 0 when receiving reaches the
+ specified LSN. If specified when not in <code class="option">--start</code>
+ mode, an error is raised.
+ </p><p>
+ If there's a record with LSN exactly equal to <em class="replaceable"><code>lsn</code></em>,
+ the record will be output.
+ </p><p>
+ The <code class="option">--endpos</code> option is not aware of transaction
+ boundaries and may truncate output partway through a transaction.
+ Any partially output transaction will not be consumed and will be
+ replayed again when the slot is next read from. Individual messages
+ are never truncated.
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Write received and decoded transaction data into this
+ file. Use <code class="literal">-</code> for <span class="systemitem">stdout</span>.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>interval_seconds</code></em></code><br /></span><span class="term"><code class="option">--fsync-interval=<em class="replaceable"><code>interval_seconds</code></em></code></span></dt><dd><p>
+ Specifies how often <span class="application">pg_recvlogical</span> should
+ issue <code class="function">fsync()</code> calls to ensure the output file is
+ safely flushed to disk.
+ </p><p>
+ The server will occasionally request the client to perform a flush and
+ report the flush position to the server. This setting is in addition
+ to that, to perform flushes more frequently.
+ </p><p>
+ Specifying an interval of <code class="literal">0</code> disables
+ issuing <code class="function">fsync()</code> calls altogether, while still
+ reporting progress to the server. In this case, data could be lost in
+ the event of a crash.
+ </p></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>lsn</code></em></code><br /></span><span class="term"><code class="option">--startpos=<em class="replaceable"><code>lsn</code></em></code></span></dt><dd><p>
+ In <code class="option">--start</code> mode, start replication from the given
+ LSN. For details on the effect of this, see the documentation
+ in <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>
+ and <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>. Ignored in other modes.
+ </p></dd><dt><span class="term"><code class="option">--if-not-exists</code></span></dt><dd><p>
+ Do not error out when <code class="option">--create-slot</code> is specified
+ and a slot with the specified name already exists.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-loop</code></span></dt><dd><p>
+ When the connection to the server is lost, do not retry in a loop, just exit.
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>name</code></em>[=<em class="replaceable"><code>value</code></em>]</code><br /></span><span class="term"><code class="option">--option=<em class="replaceable"><code>name</code></em>[=<em class="replaceable"><code>value</code></em>]</code></span></dt><dd><p>
+ Pass the option <em class="replaceable"><code>name</code></em> to the output plugin with,
+ if specified, the option value <em class="replaceable"><code>value</code></em>. Which
+ options exist and their effects depends on the used output plugin.
+ </p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>plugin</code></em></code><br /></span><span class="term"><code class="option">--plugin=<em class="replaceable"><code>plugin</code></em></code></span></dt><dd><p>
+ When creating a slot, use the specified logical decoding output
+ plugin. See <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>. This option has no
+ effect if the slot already exists.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>interval_seconds</code></em></code><br /></span><span class="term"><code class="option">--status-interval=<em class="replaceable"><code>interval_seconds</code></em></code></span></dt><dd><p>
+ This option has the same effect as the option of the same name
+ in <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a>. See the description there.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>slot_name</code></em></code><br /></span><span class="term"><code class="option">--slot=<em class="replaceable"><code>slot_name</code></em></code></span></dt><dd><p>
+ In <code class="option">--start</code> mode, use the existing logical replication slot named
+ <em class="replaceable"><code>slot_name</code></em>. In <code class="option">--create-slot</code>
+ mode, create the slot with this name. In <code class="option">--drop-slot</code>
+ mode, delete the slot with this name.
+ </p></dd><dt><span class="term"><code class="option">-t</code><br /></span><span class="term"><code class="option">--two-phase</code></span></dt><dd><p>
+ Enables decoding of prepared transactions. This option may only be specified with
+ <code class="option">--create-slot</code>
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Enables verbose mode.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following command-line options control the database connection parameters.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ The database to connect to. See the description
+ of the actions for what this means in detail.
+ The <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>. If so,
+ connection string parameters will override any conflicting
+ command line options. Defaults to the user name.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname-or-ip</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname-or-ip</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>user</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>user</code></em></code></span></dt><dd><p>
+ User name to connect as. Defaults to current operating system user
+ name.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_recvlogical</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_recvlogical</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_recvlogical</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following additional options are available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_recvlogical</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_recvlogical</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.17.7"><h2>Environment</h2><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.4.17.8"><h2>Notes</h2><p>
+ <span class="application">pg_recvlogical</span> will preserve group permissions on
+ the received WAL files if group permissions are enabled on the source
+ cluster.
+ </p></div><div class="refsect1" id="id-1.9.4.17.9"><h2>Examples</h2><p>
+ See <a class="xref" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples">Section 49.1</a> for an example.
+ </p></div><div class="refsect1" id="id-1.9.4.17.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgreceivewal.html" title="pg_receivewal">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgrestore.html" title="pg_restore">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_receivewal</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_restore</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgresetwal.html b/doc/src/sgml/html/app-pgresetwal.html
new file mode 100644
index 0000000..d8014dc
--- /dev/null
+++ b/doc/src/sgml/html/app-pgresetwal.html
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_resetwal</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pg-ctl.html" title="pg_ctl" /><link rel="next" href="app-pgrewind.html" title="pg_rewind" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_resetwal</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pg-ctl.html" title="pg_ctl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgrewind.html" title="pg_rewind">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGRESETWAL"><div class="titlepage"></div><a id="id-1.9.5.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_resetwal</span></span></h2><p>pg_resetwal — reset the write-ahead log and other control information of a <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.8.4.1"><code class="command">pg_resetwal</code> [ <code class="option">-f</code> | <code class="option">--force</code> ] [ <code class="option">-n</code> | <code class="option">--dry-run</code> ] [<em class="replaceable"><code>option</code></em>...] [ <code class="option">-D</code> | <code class="option">--pgdata</code> ]<em class="replaceable"><code>datadir</code></em> </p></div></div><div class="refsect1" id="R1-APP-PGRESETWAL-1"><h2>Description</h2><p>
+ <code class="command">pg_resetwal</code> clears the write-ahead log (WAL) and
+ optionally resets some other control information stored in the
+ <code class="filename">pg_control</code> file. This function is sometimes needed
+ if these files have become corrupted. It should be used only as a
+ last resort, when the server will not start due to such corruption.
+ </p><p>
+ After running this command, it should be possible to start the server,
+ but bear in mind that the database might contain inconsistent data due to
+ partially-committed transactions. You should immediately dump your data,
+ run <code class="command">initdb</code>, and restore. After restore, check for
+ inconsistencies and repair as needed.
+ </p><p>
+ This utility can only be run by the user who installed the server, because
+ it requires read/write access to the data directory.
+ For safety reasons, you must specify the data directory on the command line.
+ <code class="command">pg_resetwal</code> does not use the environment variable
+ <code class="envar">PGDATA</code>.
+ </p><p>
+ If <code class="command">pg_resetwal</code> complains that it cannot determine
+ valid data for <code class="filename">pg_control</code>, you can force it to proceed anyway
+ by specifying the <code class="option">-f</code> (force) option. In this case plausible
+ values will be substituted for the missing data. Most of the fields can be
+ expected to match, but manual assistance might be needed for the next OID,
+ next transaction ID and epoch, next multitransaction ID and offset, and
+ WAL starting location fields. These fields can be set using the options
+ discussed below. If you are not able to determine correct values for all
+ these fields, <code class="option">-f</code> can still be used, but
+ the recovered database must be treated with even more suspicion than
+ usual: an immediate dump and restore is imperative. <span class="emphasis"><em>Do not</em></span>
+ execute any data-modifying operations in the database before you dump,
+ as any such action is likely to make the corruption worse.
+ </p></div><div class="refsect1" id="id-1.9.5.8.6"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--force</code></span></dt><dd><p>
+ Force <code class="command">pg_resetwal</code> to proceed even if it cannot determine
+ valid data for <code class="filename">pg_control</code>, as explained above.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>
+ The <code class="option">-n</code>/<code class="option">--dry-run</code> option instructs
+ <code class="command">pg_resetwal</code> to print the values reconstructed from
+ <code class="filename">pg_control</code> and values about to be changed, and then exit
+ without modifying anything. This is mainly a debugging tool, but can be
+ useful as a sanity check before allowing <code class="command">pg_resetwal</code>
+ to proceed for real.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>Display version information, then exit.</p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>Show help, then exit.</p></dd></dl></div><p>
+ The following options are only needed when
+ <code class="command">pg_resetwal</code> is unable to determine appropriate values
+ by reading <code class="filename">pg_control</code>. Safe values can be determined as
+ described below. For values that take numeric arguments, hexadecimal
+ values can be specified by using the prefix <code class="literal">0x</code>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-c <em class="replaceable"><code>xid</code></em>,<em class="replaceable"><code>xid</code></em></code><br /></span><span class="term"><code class="option">--commit-timestamp-ids=<em class="replaceable"><code>xid</code></em>,<em class="replaceable"><code>xid</code></em></code></span></dt><dd><p>
+ Manually set the oldest and newest transaction IDs for which the commit
+ time can be retrieved.
+ </p><p>
+ A safe value for the oldest transaction ID for which the commit time can
+ be retrieved (first part) can be determined by looking
+ for the numerically smallest file name in the directory
+ <code class="filename">pg_commit_ts</code> under the data directory. Conversely, a safe
+ value for the newest transaction ID for which the commit time can be
+ retrieved (second part) can be determined by looking for the numerically
+ greatest file name in the same directory. The file names are in
+ hexadecimal.
+ </p></dd><dt><span class="term"><code class="option">-e <em class="replaceable"><code>xid_epoch</code></em></code><br /></span><span class="term"><code class="option">--epoch=<em class="replaceable"><code>xid_epoch</code></em></code></span></dt><dd><p>
+ Manually set the next transaction ID's epoch.
+ </p><p>
+ The transaction ID epoch is not actually stored anywhere in the database
+ except in the field that is set by <code class="command">pg_resetwal</code>,
+ so any value will work so far as the database itself is concerned.
+ You might need to adjust this value to ensure that replication
+ systems such as <span class="application">Slony-I</span> and
+ <span class="application">Skytools</span> work correctly —
+ if so, an appropriate value should be obtainable from the state of
+ the downstream replicated database.
+ </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>walfile</code></em></code><br /></span><span class="term"><code class="option">--next-wal-file=<em class="replaceable"><code>walfile</code></em></code></span></dt><dd><p>
+ Manually set the WAL starting location by specifying the name of the
+ next WAL segment file.
+ </p><p>
+ The name of next WAL segment file should be
+ larger than any WAL segment file name currently existing in
+ the directory <code class="filename">pg_wal</code> under the data directory.
+ These names are also in hexadecimal and have three parts. The first
+ part is the <span class="quote">“<span class="quote">timeline ID</span>”</span> and should usually be kept the same.
+ For example, if <code class="filename">00000001000000320000004A</code> is the
+ largest entry in <code class="filename">pg_wal</code>, use <code class="literal">-l 00000001000000320000004B</code> or higher.
+ </p><p>
+ Note that when using nondefault WAL segment sizes, the numbers in the WAL
+ file names are different from the LSNs that are reported by system
+ functions and system views. This option takes a WAL file name, not an
+ LSN.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="command">pg_resetwal</code> itself looks at the files in
+ <code class="filename">pg_wal</code> and chooses a default <code class="option">-l</code> setting
+ beyond the last existing file name. Therefore, manual adjustment of
+ <code class="option">-l</code> should only be needed if you are aware of WAL segment
+ files that are not currently present in <code class="filename">pg_wal</code>, such as
+ entries in an offline archive; or if the contents of
+ <code class="filename">pg_wal</code> have been lost entirely.
+ </p></div></dd><dt><span class="term"><code class="option">-m <em class="replaceable"><code>mxid</code></em>,<em class="replaceable"><code>mxid</code></em></code><br /></span><span class="term"><code class="option">--multixact-ids=<em class="replaceable"><code>mxid</code></em>,<em class="replaceable"><code>mxid</code></em></code></span></dt><dd><p>
+ Manually set the next and oldest multitransaction ID.
+ </p><p>
+ A safe value for the next multitransaction ID (first part) can be
+ determined by looking for the numerically largest file name in the
+ directory <code class="filename">pg_multixact/offsets</code> under the data directory,
+ adding one, and then multiplying by 65536 (0x10000). Conversely, a safe
+ value for the oldest multitransaction ID (second part of
+ <code class="option">-m</code>) can be determined by looking for the numerically smallest
+ file name in the same directory and multiplying by 65536. The file
+ names are in hexadecimal, so the easiest way to do this is to specify
+ the option value in hexadecimal and append four zeroes.
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>oid</code></em></code><br /></span><span class="term"><code class="option">--next-oid=<em class="replaceable"><code>oid</code></em></code></span></dt><dd><p>
+ Manually set the next OID.
+ </p><p>
+ There is no comparably easy way to determine a next OID that's beyond
+ the largest one in the database, but fortunately it is not critical to
+ get the next-OID setting right.
+ </p></dd><dt><span class="term"><code class="option">-O <em class="replaceable"><code>mxoff</code></em></code><br /></span><span class="term"><code class="option">--multixact-offset=<em class="replaceable"><code>mxoff</code></em></code></span></dt><dd><p>
+ Manually set the next multitransaction offset.
+ </p><p>
+ A safe value can be determined by looking for the numerically largest
+ file name in the directory <code class="filename">pg_multixact/members</code> under the
+ data directory, adding one, and then multiplying by 52352 (0xCC80).
+ The file names are in hexadecimal. There is no simple recipe such as
+ the ones for other options of appending zeroes.
+ </p></dd><dt><span class="term"><code class="option">--wal-segsize=<em class="replaceable"><code>wal_segment_size</code></em></code></span></dt><dd><p>
+ Set the new WAL segment size, in megabytes. The value must be set to a
+ power of 2 between 1 and 1024 (megabytes). See the same option of <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a> for more information.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ While <code class="command">pg_resetwal</code> will set the WAL starting address
+ beyond the latest existing WAL segment file, some segment size changes
+ can cause previous WAL file names to be reused. It is recommended to
+ use <code class="option">-l</code> together with this option to manually set the
+ WAL starting address if WAL file name overlap will cause problems with
+ your archiving strategy.
+ </p></div></dd><dt><span class="term"><code class="option">-u <em class="replaceable"><code>xid</code></em></code><br /></span><span class="term"><code class="option">--oldest-transaction-id=<em class="replaceable"><code>xid</code></em></code></span></dt><dd><p>
+ Manually set the oldest unfrozen transaction ID.
+ </p><p>
+ A safe value can be determined by looking for the numerically smallest
+ file name in the directory <code class="filename">pg_xact</code> under the data directory
+ and then multiplying by 1048576 (0x100000). Note that the file names are in
+ hexadecimal. It is usually easiest to specify the option value in
+ hexadecimal too. For example, if <code class="filename">0007</code> is the smallest entry
+ in <code class="filename">pg_xact</code>, <code class="literal">-u 0x700000</code> will work (five
+ trailing zeroes provide the proper multiplier).
+ </p></dd><dt><span class="term"><code class="option">-x <em class="replaceable"><code>xid</code></em></code><br /></span><span class="term"><code class="option">--next-transaction-id=<em class="replaceable"><code>xid</code></em></code></span></dt><dd><p>
+ Manually set the next transaction ID.
+ </p><p>
+ A safe value can be determined by looking for the numerically largest
+ file name in the directory <code class="filename">pg_xact</code> under the data directory,
+ adding one,
+ and then multiplying by 1048576 (0x100000). Note that the file names are in
+ hexadecimal. It is usually easiest to specify the option value in
+ hexadecimal too. For example, if <code class="filename">0011</code> is the largest entry
+ in <code class="filename">pg_xact</code>, <code class="literal">-x 0x1200000</code> will work (five
+ trailing zeroes provide the proper multiplier).
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.8.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.8.8"><h2>Notes</h2><p>
+ This command must not be used when the server is
+ running. <code class="command">pg_resetwal</code> will refuse to start up if
+ it finds a server lock file in the data directory. If the
+ server crashed then a lock file might have been left
+ behind; in that case you can remove the lock file to allow
+ <code class="command">pg_resetwal</code> to run. But before you do
+ so, make doubly certain that there is no server process still alive.
+ </p><p>
+ <code class="command">pg_resetwal</code> works only with servers of the same
+ major version.
+ </p></div><div class="refsect1" id="id-1.9.5.8.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgcontroldata.html" title="pg_controldata"><span class="refentrytitle"><span class="application">pg_controldata</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pg-ctl.html" title="pg_ctl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgrewind.html" title="pg_rewind">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_ctl</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_rewind</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgresetxlog.html b/doc/src/sgml/html/app-pgresetxlog.html
new file mode 100644
index 0000000..227bf0b
--- /dev/null
+++ b/doc/src/sgml/html/app-pgresetxlog.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>O.4. pg_resetxlog renamed to pg_resetwal</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump" /><link rel="next" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><th width="60%" align="center">Appendix O. Obsolete or Renamed Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal">Next</a></td></tr></table><hr /></div><div class="sect1" id="APP-PGRESETXLOG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code></h2></div></div></div><a id="id-1.11.16.6.2" class="indexterm"></a><p>
+ PostgreSQL 9.6 and below provided a command named
+ <code class="command">pg_resetxlog</code>
+ <a id="id-1.11.16.6.3.2" class="indexterm"></a>
+ to reset the write-ahead-log (WAL) files. This command was renamed to <code class="command">pg_resetwal</code>, see
+ <a class="xref" href="app-pgresetwal.html" title="pg_resetwal"><span class="refentrytitle"><span class="application">pg_resetwal</span></span></a> for documentation of <code class="command">pg_resetwal</code> and see
+ <a class="link" href="release-prior.html" title="E.7. Prior Releases">the release notes for PostgreSQL 10</a> for details
+ on this change.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal">Next</a></td></tr><tr><td width="40%" align="left" valign="top">O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgrestore.html b/doc/src/sgml/html/app-pgrestore.html
new file mode 100644
index 0000000..1c0034d
--- /dev/null
+++ b/doc/src/sgml/html/app-pgrestore.html
@@ -0,0 +1,504 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_restore</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgrecvlogical.html" title="pg_recvlogical" /><link rel="next" href="app-pgverifybackup.html" title="pg_verifybackup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_restore</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgrecvlogical.html" title="pg_recvlogical">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgverifybackup.html" title="pg_verifybackup">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGRESTORE"><div class="titlepage"></div><a id="id-1.9.4.18.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_restore</span></span></h2><p>pg_restore —
+ restore a <span class="productname">PostgreSQL</span> database from an
+ archive file created by <span class="application">pg_dump</span>
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.18.4.1"><code class="command">pg_restore</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>filename</code></em>]</p></div></div><div class="refsect1" id="APP-PGRESTORE-DESCRIPTION"><h2>Description</h2><p>
+ <span class="application">pg_restore</span> is a utility for restoring a
+ <span class="productname">PostgreSQL</span> database from an archive
+ created by <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> in one of the non-plain-text
+ formats. It will issue the commands necessary to reconstruct the
+ database to the state it was in at the time it was saved. The
+ archive files also allow <span class="application">pg_restore</span> to
+ be selective about what is restored, or even to reorder the items
+ prior to being restored. The archive files are designed to be
+ portable across architectures.
+ </p><p>
+ <span class="application">pg_restore</span> can operate in two modes.
+ If a database name is specified, <span class="application">pg_restore</span>
+ connects to that database and restores archive contents directly into
+ the database. Otherwise, a script containing the SQL
+ commands necessary to rebuild the database is created and written
+ to a file or standard output. This script output is equivalent to
+ the plain text output format of <span class="application">pg_dump</span>.
+ Some of the options controlling the output are therefore analogous to
+ <span class="application">pg_dump</span> options.
+ </p><p>
+ Obviously, <span class="application">pg_restore</span> cannot restore information
+ that is not present in the archive file. For instance, if the
+ archive was made using the <span class="quote">“<span class="quote">dump data as
+ <code class="command">INSERT</code> commands</span>”</span> option,
+ <span class="application">pg_restore</span> will not be able to load the data
+ using <code class="command">COPY</code> statements.
+ </p></div><div class="refsect1" id="APP-PGRESTORE-OPTIONS"><h2>Options</h2><p>
+ <span class="application">pg_restore</span> accepts the following command
+ line arguments.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>filename</code></em></span></dt><dd><p>
+ Specifies the location of the archive file (or directory, for a
+ directory-format archive) to be restored.
+ If not specified, the standard input is used.
+ </p></dd><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--data-only</code></span></dt><dd><p>
+ Restore only the data, not the schema (data definitions).
+ Table data, large objects, and sequence values are restored,
+ if present in the archive.
+ </p><p>
+ This option is similar to, but for historical reasons not identical
+ to, specifying <code class="option">--section=data</code>.
+ </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--clean</code></span></dt><dd><p>
+ Before restoring database objects, issue commands
+ to <code class="command">DROP</code> all the objects that will be restored.
+ This option is useful for overwriting an existing database.
+ If any of the objects do not exist in the destination database,
+ ignorable error messages will be reported,
+ unless <code class="option">--if-exists</code> is also specified.
+ </p></dd><dt><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--create</code></span></dt><dd><p>
+ Create the database before restoring into it.
+ If <code class="option">--clean</code> is also specified, drop and
+ recreate the target database before connecting to it.
+ </p><p>
+ With <code class="option">--create</code>, <span class="application">pg_restore</span>
+ also restores the database's comment if any, and any configuration
+ variable settings that are specific to this database, that is,
+ any <code class="command">ALTER DATABASE ... SET ...</code>
+ and <code class="command">ALTER ROLE ... IN DATABASE ... SET ...</code>
+ commands that mention this database.
+ Access privileges for the database itself are also restored,
+ unless <code class="option">--no-acl</code> is specified.
+ </p><p>
+ When this option is used, the database named with <code class="option">-d</code>
+ is used only to issue the initial <code class="command">DROP DATABASE</code> and
+ <code class="command">CREATE DATABASE</code> commands. All data is restored into the
+ database name that appears in the archive.
+ </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Connect to database <em class="replaceable"><code>dbname</code></em> and restore directly
+ into the database. The <em class="replaceable"><code>dbname</code></em> can
+ be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.
+ If so, connection string parameters will override any conflicting
+ command line options.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--exit-on-error</code></span></dt><dd><p>
+ Exit if an error is encountered while sending SQL commands to
+ the database. The default is to continue and to display a count of
+ errors at the end of the restoration.
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Specify output file for generated script, or for the listing
+ when used with <code class="option">-l</code>. Use <code class="literal">-</code>
+ for <span class="systemitem">stdout</span>.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>format</code></em></code><br /></span><span class="term"><code class="option">--format=<em class="replaceable"><code>format</code></em></code></span></dt><dd><p>
+ Specify format of the archive. It is not necessary to specify
+ the format, since <span class="application">pg_restore</span> will
+ determine the format automatically. If specified, it can be
+ one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">c</code><br /></span><span class="term"><code class="literal">custom</code></span></dt><dd><p>
+ The archive is in the custom format of
+ <span class="application">pg_dump</span>.
+ </p></dd><dt><span class="term"><code class="literal">d</code><br /></span><span class="term"><code class="literal">directory</code></span></dt><dd><p>
+ The archive is a directory archive.
+ </p></dd><dt><span class="term"><code class="literal">t</code><br /></span><span class="term"><code class="literal">tar</code></span></dt><dd><p>
+ The archive is a <code class="command">tar</code> archive.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>index</code></em></code><br /></span><span class="term"><code class="option">--index=<em class="replaceable"><code>index</code></em></code></span></dt><dd><p>
+ Restore definition of named index only. Multiple indexes
+ may be specified with multiple <code class="option">-I</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>number-of-jobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>number-of-jobs</code></em></code></span></dt><dd><p>
+ Run the most time-consuming steps
+ of <span class="application">pg_restore</span> — those that load data,
+ create indexes, or create constraints — concurrently, using up
+ to <em class="replaceable"><code>number-of-jobs</code></em>
+ concurrent sessions. This option can dramatically reduce the time
+ to restore a large database to a server running on a
+ multiprocessor machine. This option is ignored when emitting a script
+ rather than connecting directly to a database server.
+ </p><p>
+ Each job is one process or one thread, depending on the
+ operating system, and uses a separate connection to the
+ server.
+ </p><p>
+ The optimal value for this option depends on the hardware
+ setup of the server, of the client, and of the network.
+ Factors include the number of CPU cores and the disk setup. A
+ good place to start is the number of CPU cores on the server,
+ but values larger than that can also lead to faster restore
+ times in many cases. Of course, values that are too high will
+ lead to decreased performance because of thrashing.
+ </p><p>
+ Only the custom and directory archive formats are supported
+ with this option.
+ The input must be a regular file or directory (not, for example, a
+ pipe or standard input). Also, multiple
+ jobs cannot be used together with the
+ option <code class="option">--single-transaction</code>.
+ </p></dd><dt><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--list</code></span></dt><dd><p>
+ List the table of contents of the archive. The output of this operation
+ can be used as input to the <code class="option">-L</code> option. Note that
+ if filtering switches such as <code class="option">-n</code> or <code class="option">-t</code> are
+ used with <code class="option">-l</code>, they will restrict the items listed.
+ </p></dd><dt><span class="term"><code class="option">-L <em class="replaceable"><code>list-file</code></em></code><br /></span><span class="term"><code class="option">--use-list=<em class="replaceable"><code>list-file</code></em></code></span></dt><dd><p>
+ Restore only those archive elements that are listed in <em class="replaceable"><code>list-file</code></em>, and restore them in the
+ order they appear in the file. Note that
+ if filtering switches such as <code class="option">-n</code> or <code class="option">-t</code> are
+ used with <code class="option">-L</code>, they will further restrict the items restored.
+ </p><p><em class="replaceable"><code>list-file</code></em> is normally created by
+ editing the output of a previous <code class="option">-l</code> operation.
+ Lines can be moved or removed, and can also
+ be commented out by placing a semicolon (<code class="literal">;</code>) at the
+ start of the line. See below for examples.
+ </p></dd><dt><span class="term"><code class="option">-n <em class="replaceable"><code>schema</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>schema</code></em></code></span></dt><dd><p>
+ Restore only objects that are in the named schema. Multiple schemas
+ may be specified with multiple <code class="option">-n</code> switches. This can be
+ combined with the <code class="option">-t</code> option to restore just a
+ specific table.
+ </p></dd><dt><span class="term"><code class="option">-N <em class="replaceable"><code>schema</code></em></code><br /></span><span class="term"><code class="option">--exclude-schema=<em class="replaceable"><code>schema</code></em></code></span></dt><dd><p>
+ Do not restore objects that are in the named schema. Multiple schemas
+ to be excluded may be specified with multiple <code class="option">-N</code> switches.
+ </p><p>
+ When both <code class="option">-n</code> and <code class="option">-N</code> are given for the same
+ schema name, the <code class="option">-N</code> switch wins and the schema is excluded.
+ </p></dd><dt><span class="term"><code class="option">-O</code><br /></span><span class="term"><code class="option">--no-owner</code></span></dt><dd><p>
+ Do not output commands to set
+ ownership of objects to match the original database.
+ By default, <span class="application">pg_restore</span> issues
+ <code class="command">ALTER OWNER</code> or
+ <code class="command">SET SESSION AUTHORIZATION</code>
+ statements to set ownership of created schema elements.
+ These statements will fail unless the initial connection to the
+ database is made by a superuser
+ (or the same user that owns all of the objects in the script).
+ With <code class="option">-O</code>, any user name can be used for the
+ initial connection, and this user will own all the created objects.
+ </p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>function-name(argtype [, ...])</code></em></code><br /></span><span class="term"><code class="option">--function=<em class="replaceable"><code>function-name(argtype [, ...])</code></em></code></span></dt><dd><p>
+ Restore the named function only. Be careful to spell the function
+ name and arguments exactly as they appear in the dump file's table
+ of contents. Multiple functions may be specified with multiple
+ <code class="option">-P</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--no-reconnect</code></span></dt><dd><p>
+ This option is obsolete but still accepted for backwards
+ compatibility.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--schema-only</code></span></dt><dd><p>
+ Restore only the schema (data definitions), not data,
+ to the extent that schema entries are present in the archive.
+ </p><p>
+ This option is the inverse of <code class="option">--data-only</code>.
+ It is similar to, but for historical reasons not identical to,
+ specifying
+ <code class="option">--section=pre-data --section=post-data</code>.
+ </p><p>
+ (Do not confuse this with the <code class="option">--schema</code> option, which
+ uses the word <span class="quote">“<span class="quote">schema</span>”</span> in a different meaning.)
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--superuser=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Specify the superuser user name to use when disabling triggers.
+ This is relevant only if <code class="option">--disable-triggers</code> is used.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>table</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>table</code></em></code></span></dt><dd><p>
+ Restore definition and/or data of only the named table.
+ For this purpose, <span class="quote">“<span class="quote">table</span>”</span> includes views, materialized views,
+ sequences, and foreign tables. Multiple tables
+ can be selected by writing multiple <code class="option">-t</code> switches.
+ This option can be combined with the <code class="option">-n</code> option to
+ specify table(s) in a particular schema.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="option">-t</code> is specified, <span class="application">pg_restore</span>
+ makes no attempt to restore any other database objects that the
+ selected table(s) might depend upon. Therefore, there is no
+ guarantee that a specific-table restore into a clean database will
+ succeed.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ This flag does not behave identically to the <code class="option">-t</code>
+ flag of <span class="application">pg_dump</span>. There is not currently
+ any provision for wild-card matching in <span class="application">pg_restore</span>,
+ nor can you include a schema name within its <code class="option">-t</code>.
+ And, while <span class="application">pg_dump</span>'s <code class="option">-t</code>
+ flag will also dump subsidiary objects (such as indexes) of the
+ selected table(s),
+ <span class="application">pg_restore</span>'s <code class="option">-t</code>
+ flag does not include such subsidiary objects.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ In versions prior to <span class="productname">PostgreSQL</span> 9.6, this flag
+ matched only tables, not any other type of relation.
+ </p></div></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>trigger</code></em></code><br /></span><span class="term"><code class="option">--trigger=<em class="replaceable"><code>trigger</code></em></code></span></dt><dd><p>
+ Restore named trigger only. Multiple triggers may be specified with
+ multiple <code class="option">-T</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Specifies verbose mode. This will cause
+ <span class="application">pg_restore</span> to output detailed object
+ comments and start/stop times to the output file, and progress
+ messages to standard error.
+ Repeating the option causes additional debug-level messages
+ to appear on standard error.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_restore</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--no-privileges</code><br /></span><span class="term"><code class="option">--no-acl</code></span></dt><dd><p>
+ Prevent restoration of access privileges (grant/revoke commands).
+ </p></dd><dt><span class="term"><code class="option">-1</code><br /></span><span class="term"><code class="option">--single-transaction</code></span></dt><dd><p>
+ Execute the restore as a single transaction (that is, wrap the
+ emitted commands in <code class="command">BEGIN</code>/<code class="command">COMMIT</code>). This
+ ensures that either all the commands complete successfully, or no
+ changes are applied. This option implies
+ <code class="option">--exit-on-error</code>.
+ </p></dd><dt><span class="term"><code class="option">--disable-triggers</code></span></dt><dd><p>
+ This option is relevant only when performing a data-only restore.
+ It instructs <span class="application">pg_restore</span> to execute commands
+ to temporarily disable triggers on the target tables while
+ the data is restored. Use this if you have referential
+ integrity checks or other triggers on the tables that you
+ do not want to invoke during data restore.
+ </p><p>
+ Presently, the commands emitted for
+ <code class="option">--disable-triggers</code> must be done as superuser. So you
+ should also specify a superuser name with <code class="option">-S</code> or,
+ preferably, run <span class="application">pg_restore</span> as a
+ <span class="productname">PostgreSQL</span> superuser.
+ </p></dd><dt><span class="term"><code class="option">--enable-row-security</code></span></dt><dd><p>
+ This option is relevant only when restoring the contents of a table
+ which has row security. By default, <span class="application">pg_restore</span> will set
+ <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to off, to ensure
+ that all data is restored in to the table. If the user does not have
+ sufficient privileges to bypass row security, then an error is thrown.
+ This parameter instructs <span class="application">pg_restore</span> to set
+ <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to on instead, allowing the user to attempt to restore
+ the contents of the table with row security enabled. This might still
+ fail if the user does not have the right to insert the rows from the
+ dump into the table.
+ </p><p>
+ Note that this option currently also requires the dump be in <code class="command">INSERT</code>
+ format, as <code class="command">COPY FROM</code> does not support row security.
+ </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
+ Use <code class="literal">DROP ... IF EXISTS</code> commands to drop objects
+ in <code class="option">--clean</code> mode. This suppresses <span class="quote">“<span class="quote">does not
+ exist</span>”</span> errors that might otherwise be reported. This
+ option is not valid unless <code class="option">--clean</code> is also
+ specified.
+ </p></dd><dt><span class="term"><code class="option">--no-comments</code></span></dt><dd><p>
+ Do not output commands to restore comments, even if the archive
+ contains them.
+ </p></dd><dt><span class="term"><code class="option">--no-data-for-failed-tables</code></span></dt><dd><p>
+ By default, table data is restored even if the creation command
+ for the table failed (e.g., because it already exists).
+ With this option, data for such a table is skipped.
+ This behavior is useful if the target database already
+ contains the desired table contents. For example,
+ auxiliary tables for <span class="productname">PostgreSQL</span> extensions
+ such as <span class="productname">PostGIS</span> might already be loaded in
+ the target database; specifying this option prevents duplicate
+ or obsolete data from being loaded into them.
+ </p><p>
+ This option is effective only when restoring directly into a
+ database, not when producing SQL script output.
+ </p></dd><dt><span class="term"><code class="option">--no-publications</code></span></dt><dd><p>
+ Do not output commands to restore publications, even if the archive
+ contains them.
+ </p></dd><dt><span class="term"><code class="option">--no-security-labels</code></span></dt><dd><p>
+ Do not output commands to restore security labels,
+ even if the archive contains them.
+ </p></dd><dt><span class="term"><code class="option">--no-subscriptions</code></span></dt><dd><p>
+ Do not output commands to restore subscriptions, even if the archive
+ contains them.
+ </p></dd><dt><span class="term"><code class="option">--no-table-access-method</code></span></dt><dd><p>
+ Do not output commands to select table access methods.
+ With this option, all objects will be created with whichever
+ access method is the default during restore.
+ </p></dd><dt><span class="term"><code class="option">--no-tablespaces</code></span></dt><dd><p>
+ Do not output commands to select tablespaces.
+ With this option, all objects will be created in whichever
+ tablespace is the default during restore.
+ </p></dd><dt><span class="term"><code class="option">--section=<em class="replaceable"><code>sectionname</code></em></code></span></dt><dd><p>
+ Only restore the named section. The section name can be
+ <code class="option">pre-data</code>, <code class="option">data</code>, or <code class="option">post-data</code>.
+ This option can be specified more than once to select multiple
+ sections. The default is to restore all sections.
+ </p><p>
+ The data section contains actual table data as well as large-object
+ definitions.
+ Post-data items consist of definitions of indexes, triggers, rules
+ and constraints other than validated check constraints.
+ Pre-data items consist of all other data definition items.
+ </p></dd><dt><span class="term"><code class="option">--strict-names</code></span></dt><dd><p>
+ Require that each schema
+ (<code class="option">-n</code>/<code class="option">--schema</code>) and table
+ (<code class="option">-t</code>/<code class="option">--table</code>) qualifier match at
+ least one schema/table in the backup file.
+ </p></dd><dt><span class="term"><code class="option">--use-set-session-authorization</code></span></dt><dd><p>
+ Output SQL-standard <code class="command">SET SESSION AUTHORIZATION</code> commands
+ instead of <code class="command">ALTER OWNER</code> commands to determine object
+ ownership. This makes the dump more standards-compatible, but
+ depending on the history of the objects in the dump, might not restore
+ properly.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_restore</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">pg_restore</span> also accepts
+ the following command line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_restore</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_restore</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_restore</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--role=<em class="replaceable"><code>rolename</code></em></code></span></dt><dd><p>
+ Specifies a role name to be used to perform the restore.
+ This option causes <span class="application">pg_restore</span> to issue a
+ <code class="command">SET ROLE</code> <em class="replaceable"><code>rolename</code></em>
+ command after connecting to the database. It is useful when the
+ authenticated user (specified by <code class="option">-U</code>) lacks privileges
+ needed by <span class="application">pg_restore</span>, but can switch to a role with
+ the required rights. Some installations have a policy against
+ logging in directly as a superuser, and use of this option allows
+ restores to be performed without violating the policy.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.18.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGOPTIONS</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>). However, it does not read
+ <code class="envar">PGDATABASE</code> when a database name is not supplied.
+ </p></div><div class="refsect1" id="APP-PGRESTORE-DIAGNOSTICS"><h2>Diagnostics</h2><p>
+ When a direct database connection is specified using the
+ <code class="option">-d</code> option, <span class="application">pg_restore</span>
+ internally executes <acronym class="acronym">SQL</acronym> statements. If you have
+ problems running <span class="application">pg_restore</span>, make sure
+ you are able to select information from the database using, for
+ example, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>. Also, any default connection
+ settings and environment variables used by the
+ <span class="application">libpq</span> front-end library will apply.
+ </p></div><div class="refsect1" id="APP-PGRESTORE-NOTES"><h2>Notes</h2><p>
+ If your installation has any local additions to the
+ <code class="literal">template1</code> database, be careful to load the output of
+ <span class="application">pg_restore</span> into a truly empty database;
+ otherwise you are likely to get errors due to duplicate definitions
+ of the added objects. To make an empty database without any local
+ additions, copy from <code class="literal">template0</code> not <code class="literal">template1</code>, for example:
+</p><pre class="programlisting">
+CREATE DATABASE foo WITH TEMPLATE template0;
+</pre><p>
+ </p><p>
+ The limitations of <span class="application">pg_restore</span> are detailed below.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ When restoring data to a pre-existing table and the option
+ <code class="option">--disable-triggers</code> is used,
+ <span class="application">pg_restore</span> emits commands
+ to disable triggers on user tables before inserting the data, then emits commands to
+ re-enable them after the data has been inserted. If the restore is stopped in the
+ middle, the system catalogs might be left in the wrong state.
+ </p></li><li class="listitem"><p><span class="application">pg_restore</span> cannot restore large objects
+ selectively; for instance, only those for a specific table. If
+ an archive contains large objects, then all large objects will be
+ restored, or none of them if they are excluded via <code class="option">-L</code>,
+ <code class="option">-t</code>, or other options.
+ </p></li></ul></div><p>
+ </p><p>
+ See also the <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> documentation for details on
+ limitations of <span class="application">pg_dump</span>.
+ </p><p>
+ Once restored, it is wise to run <code class="command">ANALYZE</code> on each
+ restored table so the optimizer has useful statistics; see
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a> and
+ <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ </p></div><div class="refsect1" id="APP-PGRESTORE-EXAMPLES"><h2>Examples</h2><p>
+ Assume we have dumped a database called <code class="literal">mydb</code> into a
+ custom-format dump file:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fc mydb &gt; db.dump</code></strong>
+</pre><p>
+ </p><p>
+ To drop the database and recreate it from the dump:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>dropdb mydb</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -C -d postgres db.dump</code></strong>
+</pre><p>
+
+ The database named in the <code class="option">-d</code> switch can be any database existing
+ in the cluster; <span class="application">pg_restore</span> only uses it to issue the
+ <code class="command">CREATE DATABASE</code> command for <code class="literal">mydb</code>. With
+ <code class="option">-C</code>, data is always restored into the database name that appears
+ in the dump file.
+ </p><p>
+ To restore the dump into a new database called <code class="literal">newdb</code>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>createdb -T template0 newdb</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -d newdb db.dump</code></strong>
+</pre><p>
+
+ Notice we don't use <code class="option">-C</code>, and instead connect directly to the
+ database to be restored into. Also note that we clone the new database
+ from <code class="literal">template0</code> not <code class="literal">template1</code>, to ensure it is
+ initially empty.
+ </p><p>
+ To reorder database items, it is first necessary to dump the table of
+ contents of the archive:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -l db.dump &gt; db.list</code></strong>
+</pre><p>
+ The listing file consists of a header and one line for each item, e.g.:
+</p><pre class="programlisting">
+;
+; Archive created at Mon Sep 14 13:55:39 2009
+; dbname: DBDEMOS
+; TOC Entries: 81
+; Compression: 9
+; Dump Version: 1.10-0
+; Format: CUSTOM
+; Integer: 4 bytes
+; Offset: 8 bytes
+; Dumped from database version: 8.3.5
+; Dumped by pg_dump version: 8.3.8
+;
+;
+; Selected TOC Entries:
+;
+3; 2615 2200 SCHEMA - public pasha
+1861; 0 0 COMMENT - SCHEMA public pasha
+1862; 0 0 ACL - public pasha
+317; 1247 17715 TYPE public composite pasha
+319; 1247 25899 DOMAIN public domain0 pasha
+</pre><p>
+ Semicolons start a comment, and the numbers at the start of lines refer to the
+ internal archive ID assigned to each item.
+ </p><p>
+ Lines in the file can be commented out, deleted, and reordered. For example:
+</p><pre class="programlisting">
+10; 145433 TABLE map_resolutions postgres
+;2; 145344 TABLE species postgres
+;4; 145359 TABLE nt_header postgres
+6; 145402 TABLE species_records postgres
+;8; 145416 TABLE ss_old postgres
+</pre><p>
+ could be used as input to <span class="application">pg_restore</span> and would only restore
+ items 10 and 6, in that order:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_restore -L db.list db.dump</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.18.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a>, <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgrecvlogical.html" title="pg_recvlogical">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgverifybackup.html" title="pg_verifybackup">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_recvlogical</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_verifybackup</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgrewind.html b/doc/src/sgml/html/app-pgrewind.html
new file mode 100644
index 0000000..c23f061
--- /dev/null
+++ b/doc/src/sgml/html/app-pgrewind.html
@@ -0,0 +1,216 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_rewind</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgresetwal.html" title="pg_resetwal" /><link rel="next" href="pgtestfsync.html" title="pg_test_fsync" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_rewind</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgresetwal.html" title="pg_resetwal">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgtestfsync.html" title="pg_test_fsync">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGREWIND"><div class="titlepage"></div><a id="id-1.9.5.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_rewind</span></span></h2><p>pg_rewind — synchronize a <span class="productname">PostgreSQL</span> data directory with another data directory that was forked from it</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.9.4.1"><code class="command">pg_rewind</code> [<em class="replaceable"><code>option</code></em>...] { <code class="option">-D</code> | <code class="option">--target-pgdata</code> }<em class="replaceable"><code> directory</code></em> { <code class="option">--source-pgdata=<em class="replaceable"><code>directory</code></em></code> | <code class="option">--source-server=<em class="replaceable"><code>connstr</code></em></code> } </p></div></div><div class="refsect1" id="id-1.9.5.9.5"><h2>Description</h2><p>
+ <span class="application">pg_rewind</span> is a tool for synchronizing a PostgreSQL cluster
+ with another copy of the same cluster, after the clusters' timelines have
+ diverged. A typical scenario is to bring an old primary server back online
+ after failover as a standby that follows the new primary.
+ </p><p>
+ After a successful rewind, the state of the target data directory is
+ analogous to a base backup of the source data directory. Unlike taking
+ a new base backup or using a tool like <span class="application">rsync</span>,
+ <span class="application">pg_rewind</span> does not require comparing or copying
+ unchanged relation blocks in the cluster. Only changed blocks from existing
+ relation files are copied; all other files, including new relation files,
+ configuration files, and WAL segments, are copied in full. As such the
+ rewind operation is significantly faster than other approaches when the
+ database is large and only a small fraction of blocks differ between the
+ clusters.
+ </p><p>
+ <span class="application">pg_rewind</span> examines the timeline histories of the source
+ and target clusters to determine the point where they diverged, and
+ expects to find WAL in the target cluster's <code class="filename">pg_wal</code> directory
+ reaching all the way back to the point of divergence. The point of divergence
+ can be found either on the target timeline, the source timeline, or their common
+ ancestor. In the typical failover scenario where the target cluster was
+ shut down soon after the divergence, this is not a problem, but if the
+ target cluster ran for a long time after the divergence, its old WAL
+ files might no longer be present. In this case, you can manually copy them
+ from the WAL archive to the <code class="filename">pg_wal</code> directory, or run
+ <span class="application">pg_rewind</span> with the <code class="literal">-c</code> option to
+ automatically retrieve them from the WAL archive. The use of
+ <span class="application">pg_rewind</span> is not limited to failover, e.g., a standby
+ server can be promoted, run some write transactions, and then rewound
+ to become a standby again.
+ </p><p>
+ After running <span class="application">pg_rewind</span>, WAL replay needs to
+ complete for the data directory to be in a consistent state. When the
+ target server is started again it will enter archive recovery and replay
+ all WAL generated in the source server from the last checkpoint before
+ the point of divergence. If some of the WAL was no longer available in the
+ source server when <span class="application">pg_rewind</span> was run, and
+ therefore could not be copied by the <span class="application">pg_rewind</span>
+ session, it must be made available when the target server is started.
+ This can be done by creating a <code class="filename">recovery.signal</code> file
+ in the target data directory and by configuring a suitable
+ <a class="xref" href="runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a> in
+ <code class="filename">postgresql.conf</code>.
+ </p><p>
+ <span class="application">pg_rewind</span> requires that the target server either has
+ the <a class="xref" href="runtime-config-wal.html#GUC-WAL-LOG-HINTS">wal_log_hints</a> option enabled
+ in <code class="filename">postgresql.conf</code> or data checksums enabled when
+ the cluster was initialized with <span class="application">initdb</span>. Neither of these
+ are currently on by default. <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a>
+ must also be set to <code class="literal">on</code>, but is enabled by default.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ If <span class="application">pg_rewind</span> fails while processing, then
+ the data folder of the target is likely not in a state that can be
+ recovered. In such a case, taking a new fresh backup is recommended.
+ </p><p>
+ As <span class="application">pg_rewind</span> copies configuration files
+ entirely from the source, it may be required to correct the configuration
+ used for recovery before restarting the target server, especially if
+ the target is reintroduced as a standby of the source. If you restart
+ the server after the rewind operation has finished but without configuring
+ recovery, the target may again diverge from the primary.
+ </p><p>
+ <span class="application">pg_rewind</span> will fail immediately if it finds
+ files it cannot write directly to. This can happen for example when
+ the source and the target server use the same file mapping for read-only
+ SSL keys and certificates. If such files are present on the target server
+ it is recommended to remove them before running
+ <span class="application">pg_rewind</span>. After doing the rewind, some of
+ those files may have been copied from the source, in which case it may
+ be necessary to remove the data copied and restore back the set of links
+ used before the rewind.
+ </p></div></div><div class="refsect1" id="id-1.9.5.9.6"><h2>Options</h2><p>
+ <span class="application">pg_rewind</span> accepts the following command-line
+ arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--target-pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ This option specifies the target data directory that is synchronized
+ with the source. The target server must be shut down cleanly before
+ running <span class="application">pg_rewind</span>
+ </p></dd><dt><span class="term"><code class="option">--source-pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specifies the file system path to the data directory of the source
+ server to synchronize the target with. This option requires the
+ source server to be cleanly shut down.
+ </p></dd><dt><span class="term"><code class="option">--source-server=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
+ Specifies a libpq connection string to connect to the source
+ <span class="productname">PostgreSQL</span> server to synchronize the target
+ with. The connection must be a normal (non-replication) connection
+ with a role having sufficient permissions to execute the functions
+ used by <span class="application">pg_rewind</span> on the source server
+ (see Notes section for details) or a superuser role. This option
+ requires the source server to be running and accepting connections.
+ </p></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--write-recovery-conf</code></span></dt><dd><p>
+ Create <code class="filename">standby.signal</code> and append connection
+ settings to <code class="filename">postgresql.auto.conf</code> in the output
+ directory. <code class="literal">--source-server</code> is mandatory with
+ this option.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>
+ Do everything except actually modifying the target directory.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_rewind</code> will wait for all files
+ to be written safely to disk. This option causes
+ <code class="command">pg_rewind</code> to return without waiting, which is
+ faster, but means that a subsequent operating system crash can leave
+ the data directory corrupt. Generally, this option is useful for
+ testing but should not be used on a production
+ installation.
+ </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
+ Enables progress reporting. Turning this on will deliver an approximate
+ progress report while copying data from the source cluster.
+ </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--restore-target-wal</code></span></dt><dd><p>
+ Use <code class="varname">restore_command</code> defined in the target cluster
+ configuration to retrieve WAL files from the WAL archive if these
+ files are no longer available in the <code class="filename">pg_wal</code>
+ directory.
+ </p></dd><dt><span class="term"><code class="option">--config-file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Use the specified main server configuration file for the target
+ cluster. This affects <span class="application">pg_rewind</span> when
+ it uses internally the <span class="application">postgres</span> command
+ for the rewind operation on this cluster (when retrieving
+ <code class="varname">restore_command</code> with the option
+ <code class="option">-c/--restore-target-wal</code> and when forcing a
+ completion of crash recovery).
+ </p></dd><dt><span class="term"><code class="option">--debug</code></span></dt><dd><p>
+ Print verbose debugging output that is mostly useful for developers
+ debugging <span class="application">pg_rewind</span>.
+ </p></dd><dt><span class="term"><code class="option">--no-ensure-shutdown</code></span></dt><dd><p>
+ <span class="application">pg_rewind</span> requires that the target server
+ is cleanly shut down before rewinding. By default, if the target server
+ is not shut down cleanly, <span class="application">pg_rewind</span> starts
+ the target server in single-user mode to complete crash recovery first,
+ and stops it.
+ By passing this option, <span class="application">pg_rewind</span> skips
+ this and errors out immediately if the server is not cleanly shut
+ down. Users are expected to handle the situation themselves in that
+ case.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>Display version information, then exit.</p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>Show help, then exit.</p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.9.7"><h2>Environment</h2><p>
+ When <code class="option">--source-server</code> option is used,
+ <span class="application">pg_rewind</span> also uses the environment variables
+ supported by <span class="application">libpq</span> (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.9.8"><h2>Notes</h2><p>
+ When executing <span class="application">pg_rewind</span> using an online
+ cluster as source, a role having sufficient permissions to execute the
+ functions used by <span class="application">pg_rewind</span> on the source
+ cluster can be used instead of a superuser. Here is how to create such
+ a role, named <code class="literal">rewind_user</code> here:
+</p><pre class="programlisting">
+CREATE USER rewind_user LOGIN;
+GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
+GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;
+</pre><p>
+ </p><p>
+ When executing <span class="application">pg_rewind</span> using an online
+ cluster as source which has been recently promoted, it is necessary
+ to execute a <code class="command">CHECKPOINT</code> after promotion such that its
+ control file reflects up-to-date timeline information, which is used by
+ <span class="application">pg_rewind</span> to check if the target cluster
+ can be rewound using the designated source cluster.
+ </p><div class="refsect2" id="id-1.9.5.9.8.4"><h3>How It Works</h3><p>
+ The basic idea is to copy all file system-level changes from the source
+ cluster to the target cluster:
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ Scan the WAL log of the target cluster, starting from the last
+ checkpoint before the point where the source cluster's timeline
+ history forked off from the target cluster. For each WAL record,
+ record each data block that was touched. This yields a list of all
+ the data blocks that were changed in the target cluster, after the
+ source cluster forked off. If some of the WAL files are no longer
+ available, try re-running <span class="application">pg_rewind</span> with
+ the <code class="option">-c</code> option to search for the missing files in
+ the WAL archive.
+ </p></li><li class="step"><p>
+ Copy all those changed blocks from the source cluster to
+ the target cluster, either using direct file system access
+ (<code class="option">--source-pgdata</code>) or SQL (<code class="option">--source-server</code>).
+ Relation files are now in a state equivalent to the moment of the last
+ completed checkpoint prior to the point at which the WAL timelines of the
+ source and target diverged plus the current state on the source of any
+ blocks changed on the target after that divergence.
+ </p></li><li class="step"><p>
+ Copy all other files, including new relation files, WAL segments,
+ <code class="filename">pg_xact</code>, and configuration files from the source
+ cluster to the target cluster. Similarly to base backups, the contents
+ of the directories <code class="filename">pg_dynshmem/</code>,
+ <code class="filename">pg_notify/</code>, <code class="filename">pg_replslot/</code>,
+ <code class="filename">pg_serial/</code>, <code class="filename">pg_snapshots/</code>,
+ <code class="filename">pg_stat_tmp/</code>, and <code class="filename">pg_subtrans/</code>
+ are omitted from the data copied from the source cluster. The files
+ <code class="filename">backup_label</code>,
+ <code class="filename">tablespace_map</code>,
+ <code class="filename">pg_internal.init</code>,
+ <code class="filename">postmaster.opts</code>, and
+ <code class="filename">postmaster.pid</code>, as well as any file or directory
+ beginning with <code class="filename">pgsql_tmp</code>, are omitted.
+ </p></li><li class="step"><p>
+ Create a <code class="filename">backup_label</code> file to begin WAL replay at
+ the checkpoint created at failover and configure the
+ <code class="filename">pg_control</code> file with a minimum consistency LSN
+ defined as the result of <code class="literal">pg_current_wal_insert_lsn()</code>
+ when rewinding from a live source or the last checkpoint LSN when
+ rewinding from a stopped source.
+ </p></li><li class="step"><p>
+ When starting the target, <span class="productname">PostgreSQL</span> replays
+ all the required WAL, resulting in a data directory in a consistent
+ state.
+ </p></li></ol></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgresetwal.html" title="pg_resetwal">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgtestfsync.html" title="pg_test_fsync">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_resetwal</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_test_fsync</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-pgverifybackup.html b/doc/src/sgml/html/app-pgverifybackup.html
new file mode 100644
index 0000000..058b47b
--- /dev/null
+++ b/doc/src/sgml/html/app-pgverifybackup.html
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_verifybackup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgrestore.html" title="pg_restore" /><link rel="next" href="app-psql.html" title="psql" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_verifybackup</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgrestore.html" title="pg_restore">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-psql.html" title="psql">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGVERIFYBACKUP"><div class="titlepage"></div><a id="id-1.9.4.19.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></h2><p>pg_verifybackup — verify the integrity of a base backup of a
+ <span class="productname">PostgreSQL</span> cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.19.4.1"><code class="command">pg_verifybackup</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.19.5"><h2>Description</h2><p>
+ <span class="application">pg_verifybackup</span> is used to check the
+ integrity of a database cluster backup taken using
+ <code class="command">pg_basebackup</code> against a
+ <code class="literal">backup_manifest</code> generated by the server at the time
+ of the backup. The backup must be stored in the "plain"
+ format; a "tar" format backup can be checked after extracting it.
+ </p><p>
+ It is important to note that the validation which is performed by
+ <span class="application">pg_verifybackup</span> does not and cannot include
+ every check which will be performed by a running server when attempting
+ to make use of the backup. Even if you use this tool, you should still
+ perform test restores and verify that the resulting databases work as
+ expected and that they appear to contain the correct data. However,
+ <span class="application">pg_verifybackup</span> can detect many problems
+ that commonly occur due to storage problems or user error.
+ </p><p>
+ Backup verification proceeds in four stages. First,
+ <code class="literal">pg_verifybackup</code> reads the
+ <code class="literal">backup_manifest</code> file. If that file
+ does not exist, cannot be read, is malformed, or fails verification
+ against its own internal checksum, <code class="literal">pg_verifybackup</code>
+ will terminate with a fatal error.
+ </p><p>
+ Second, <code class="literal">pg_verifybackup</code> will attempt to verify that
+ the data files currently stored on disk are exactly the same as the data
+ files which the server intended to send, with some exceptions that are
+ described below. Extra and missing files will be detected, with a few
+ exceptions. This step will ignore the presence or absence of, or any
+ modifications to, <code class="literal">postgresql.auto.conf</code>,
+ <code class="literal">standby.signal</code>, and <code class="literal">recovery.signal</code>,
+ because it is expected that these files may have been created or modified
+ as part of the process of taking the backup. It also won't complain about
+ a <code class="literal">backup_manifest</code> file in the target directory or
+ about anything inside <code class="literal">pg_wal</code>, even though these
+ files won't be listed in the backup manifest. Only files are checked;
+ the presence or absence of directories is not verified, except
+ indirectly: if a directory is missing, any files it should have contained
+ will necessarily also be missing.
+ </p><p>
+ Next, <code class="literal">pg_verifybackup</code> will checksum all the files,
+ compare the checksums against the values in the manifest, and emit errors
+ for any files for which the computed checksum does not match the
+ checksum stored in the manifest. This step is not performed for any files
+ which produced errors in the previous step, since they are already known
+ to have problems. Files which were ignored in the previous step are also
+ ignored in this step.
+ </p><p>
+ Finally, <code class="literal">pg_verifybackup</code> will use the manifest to
+ verify that the write-ahead log records which will be needed to recover
+ the backup are present and that they can be read and parsed. The
+ <code class="literal">backup_manifest</code> contains information about which
+ write-ahead log records will be needed, and
+ <code class="literal">pg_verifybackup</code> will use that information to
+ invoke <code class="literal">pg_waldump</code> to parse those write-ahead log
+ records. The <code class="literal">--quiet</code> flag will be used, so that
+ <code class="literal">pg_waldump</code> will only report errors, without producing
+ any other output. While this level of verification is sufficient to
+ detect obvious problems such as a missing file or one whose internal
+ checksums do not match, they aren't extensive enough to detect every
+ possible problem that might occur when attempting to recover. For
+ instance, a server bug that produces write-ahead log records that have
+ the correct checksums but specify nonsensical actions can't be detected
+ by this method.
+ </p><p>
+ Note that if extra WAL files which are not required to recover the backup
+ are present, they will not be checked by this tool, although
+ a separate invocation of <code class="literal">pg_waldump</code> could be used for
+ that purpose. Also note that WAL verification is version-specific: you
+ must use the version of <code class="literal">pg_verifybackup</code>, and thus of
+ <code class="literal">pg_waldump</code>, which pertains to the backup being checked.
+ In contrast, the data file integrity checks should work with any version
+ of the server that generates a <code class="literal">backup_manifest</code> file.
+ </p></div><div class="refsect1" id="id-1.9.4.19.6"><h2>Options</h2><p>
+ <span class="application">pg_verifybackup</span> accepts the following
+ command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--exit-on-error</code></span></dt><dd><p>
+ Exit as soon as a problem with the backup is detected. If this option
+ is not specified, <code class="literal">pg_verifybackup</code> will continue
+ checking the backup even after a problem has been detected, and will
+ report all problems detected as errors.
+ </p></dd><dt><span class="term"><code class="option">-i <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--ignore=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
+ Ignore the specified file or directory, which should be expressed
+ as a relative path name, when comparing the list of data files
+ actually present in the backup to those listed in the
+ <code class="literal">backup_manifest</code> file. If a directory is
+ specified, this option affects the entire subtree rooted at that
+ location. Complaints about extra files, missing files, file size
+ differences, or checksum mismatches will be suppressed if the
+ relative path name matches the specified path name. This option
+ can be specified multiple times.
+ </p></dd><dt><span class="term"><code class="option">-m <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--manifest-path=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
+ Use the manifest file at the specified path, rather than one located
+ in the root of the backup directory.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-parse-wal</code></span></dt><dd><p>
+ Don't attempt to parse write-ahead log data that will be needed
+ to recover from this backup.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Don't print anything when a backup is successfully verified.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--skip-checksums</code></span></dt><dd><p>
+ Do not verify data file checksums. The presence or absence of
+ files and the sizes of those files will still be checked. This is
+ much faster, because the files themselves do not need to be read.
+ </p></dd><dt><span class="term"><code class="option">-w <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--wal-directory=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
+ Try to parse WAL files stored in the specified directory, rather than
+ in <code class="literal">pg_wal</code>. This may be useful if the backup is
+ stored in a separate location from the WAL archive.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_verifybackup</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_verifybackup</span> command
+ line arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.19.7"><h2>Examples</h2><p>
+ To create a base backup of the server at <code class="literal">mydbserver</code> and
+ verify the integrity of the backup:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup /usr/local/pgsql/data</code></strong>
+</pre><p>
+ </p><p>
+ To create a base backup of the server at <code class="literal">mydbserver</code>, move
+ the manifest somewhere outside the backup directory, and verify the
+ backup:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</code></strong>
+</pre><p>
+ </p><p>
+ To verify a backup while ignoring a file that was added manually to the
+ backup directory, and also skipping checksum verification:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>edit /usr/local/pgsql/data/note.to.self</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.19.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgrestore.html" title="pg_restore">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-psql.html" title="psql">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_restore</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">psql</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-postgres.html b/doc/src/sgml/html/app-postgres.html
new file mode 100644
index 0000000..8c896c9
--- /dev/null
+++ b/doc/src/sgml/html/app-postgres.html
@@ -0,0 +1,432 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>postgres</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgwaldump.html" title="pg_waldump" /><link rel="next" href="app-postmaster.html" title="postmaster" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">postgres</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgwaldump.html" title="pg_waldump">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-postmaster.html" title="postmaster">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-POSTGRES"><div class="titlepage"></div><a id="id-1.9.5.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">postgres</span></span></h2><p>postgres — <span class="productname">PostgreSQL</span> database server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.14.4.1"><code class="command">postgres</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.5.14.5"><h2>Description</h2><p>
+ <code class="command">postgres</code> is the
+ <span class="productname">PostgreSQL</span> database server. In order
+ for a client application to access a database it connects (over a
+ network or locally) to a running <code class="command">postgres</code> instance.
+ The <code class="command">postgres</code> instance then starts a separate server
+ process to handle the connection.
+ </p><p>
+ One <code class="command">postgres</code> instance always manages the data of
+ exactly one database cluster. A database cluster is a collection
+ of databases that is stored at a common file system location (the
+ <span class="quote">“<span class="quote">data area</span>”</span>). More than one
+ <code class="command">postgres</code> instance can run on a system at one
+ time, so long as they use different data areas and different
+ communication ports (see below). When
+ <code class="command">postgres</code> starts it needs to know the location
+ of the data area. The location must be specified by the
+ <code class="option">-D</code> option or the <code class="envar">PGDATA</code> environment
+ variable; there is no default. Typically, <code class="option">-D</code> or
+ <code class="envar">PGDATA</code> points directly to the data area directory
+ created by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. Other possible file layouts are
+ discussed in <a class="xref" href="runtime-config-file-locations.html" title="20.2. File Locations">Section 20.2</a>.
+ </p><p>
+ By default <code class="command">postgres</code> starts in the
+ foreground and prints log messages to the standard error stream. In
+ practical applications <code class="command">postgres</code>
+ should be started as a background process, perhaps at boot time.
+ </p><p>
+ The <code class="command">postgres</code> command can also be called in
+ single-user mode. The primary use for this mode is during
+ bootstrapping by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. Sometimes it is used
+ for debugging or disaster recovery; note that running a single-user
+ server is not truly suitable for debugging the server, since no
+ realistic interprocess communication and locking will happen.
+ When invoked in single-user
+ mode from the shell, the user can enter queries and the results
+ will be printed to the screen, but in a form that is more useful
+ for developers than end users. In the single-user mode,
+ the session user will be set to the user with ID 1, and implicit
+ superuser powers are granted to this user.
+ This user does not actually have to exist, so the single-user mode
+ can be used to manually recover from certain
+ kinds of accidental damage to the system catalogs.
+ </p></div><div class="refsect1" id="APP-POSTGRES-OPTIONS"><h2>Options</h2><p>
+ <code class="command">postgres</code> accepts the following command-line
+ arguments. For a detailed discussion of the options consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>. You can save typing most of these
+ options by setting up a configuration file. Some (safe) options
+ can also be set from the connecting client in an
+ application-dependent way to apply only for that session. For
+ example, if the environment variable <code class="envar">PGOPTIONS</code> is
+ set, then <span class="application">libpq</span>-based clients will pass that
+ string to the server, which will interpret it as
+ <code class="command">postgres</code> command-line options.
+ </p><div class="refsect2" id="id-1.9.5.14.6.3"><h3>General Purpose</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-B <em class="replaceable"><code>nbuffers</code></em></code></span></dt><dd><p>
+ Sets the number of shared buffers for use by the server
+ processes. The default value of this parameter is chosen
+ automatically by <span class="application">initdb</span>.
+ Specifying this option is equivalent to setting the
+ <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a> configuration parameter.
+ </p></dd><dt><span class="term"><code class="option">-c <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code></span></dt><dd><p>
+ Sets a named run-time parameter. The configuration parameters
+ supported by <span class="productname">PostgreSQL</span> are
+ described in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>. Most of the
+ other command line options are in fact short forms of such a
+ parameter assignment. <code class="option">-c</code> can appear multiple times
+ to set multiple parameters.
+ </p></dd><dt><span class="term"><code class="option">-C <em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
+ Prints the value of the named run-time parameter, and exits.
+ (See the <code class="option">-c</code> option above for details.) This
+ returns values from
+ <code class="filename">postgresql.conf</code>, modified by any parameters
+ supplied in this invocation. It does not reflect parameters
+ supplied when the cluster was started.
+ </p><p>
+ This can be used on a running server for most parameters. However,
+ the server must be shut down for some runtime-computed parameters
+ (e.g., <a class="xref" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE">shared_memory_size</a>,
+ <a class="xref" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE-IN-HUGE-PAGES">shared_memory_size_in_huge_pages</a>, and
+ <a class="xref" href="runtime-config-preset.html#GUC-WAL-SEGMENT-SIZE">wal_segment_size</a>).
+ </p><p>
+ This option is meant for other programs that interact with a server
+ instance, such as <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>, to query configuration
+ parameter values. User-facing applications should instead use <a class="link" href="sql-show.html" title="SHOW"><code class="command">SHOW</code></a> or the <code class="structname">pg_settings</code> view.
+ </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>debug-level</code></em></code></span></dt><dd><p>
+ Sets the debug level. The higher this value is set, the more
+ debugging output is written to the server log. Values are
+ from 1 to 5. It is also possible to pass <code class="literal">-d
+ 0</code> for a specific session, which will prevent the
+ server log level of the parent <code class="command">postgres</code> process from being
+ propagated to this session.
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>datadir</code></em></code></span></dt><dd><p>
+ Specifies the file system location of the database
+ configuration files. See
+ <a class="xref" href="runtime-config-file-locations.html" title="20.2. File Locations">Section 20.2</a> for details.
+ </p></dd><dt><span class="term"><code class="option">-e</code></span></dt><dd><p>
+ Sets the default date style to <span class="quote">“<span class="quote">European</span>”</span>, that is
+ <code class="literal">DMY</code> ordering of input date fields. This also causes
+ the day to be printed before the month in certain date output formats.
+ See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for more information.
+ </p></dd><dt><span class="term"><code class="option">-F</code></span></dt><dd><p>
+ Disables <code class="function">fsync</code> calls for improved
+ performance, at the risk of data corruption in the event of a
+ system crash. Specifying this option is equivalent to
+ disabling the <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> configuration
+ parameter. Read the detailed documentation before using this!
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code></span></dt><dd><p>
+ Specifies the IP host name or address on which
+ <code class="command">postgres</code> is to listen for TCP/IP
+ connections from client applications. The value can also be a
+ comma-separated list of addresses, or <code class="literal">*</code> to specify
+ listening on all available interfaces. An empty value
+ specifies not listening on any IP addresses, in which case
+ only Unix-domain sockets can be used to connect to the
+ server. Defaults to listening only on
+ <span class="systemitem">localhost</span>.
+ Specifying this option is equivalent to setting the <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> configuration parameter.
+ </p></dd><dt><span class="term"><code class="option">-i</code></span></dt><dd><p>
+ Allows remote clients to connect via TCP/IP (Internet domain)
+ connections. Without this option, only local connections are
+ accepted. This option is equivalent to setting
+ <code class="varname">listen_addresses</code> to <code class="literal">*</code> in
+ <code class="filename">postgresql.conf</code> or via <code class="option">-h</code>.
+ </p><p>
+ This option is deprecated since it does not allow access to the
+ full functionality of <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a>.
+ It's usually better to set <code class="varname">listen_addresses</code> directly.
+ </p></dd><dt><span class="term"><code class="option">-k <em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specifies the directory of the Unix-domain socket on which
+ <code class="command">postgres</code> is to listen for
+ connections from client applications. The value can also be a
+ comma-separated list of directories. An empty value
+ specifies not listening on any Unix-domain sockets, in which case
+ only TCP/IP sockets can be used to connect to the server.
+ The default value is normally
+ <code class="filename">/tmp</code>, but that can be changed at build time.
+ Specifying this option is equivalent to setting the <a class="xref" href="runtime-config-connection.html#GUC-UNIX-SOCKET-DIRECTORIES">unix_socket_directories</a> configuration parameter.
+ </p></dd><dt><span class="term"><code class="option">-l</code></span></dt><dd><p>
+ Enables secure connections using <acronym class="acronym">SSL</acronym>.
+ <span class="productname">PostgreSQL</span> must have been compiled with
+ support for <acronym class="acronym">SSL</acronym> for this option to be
+ available. For more information on using <acronym class="acronym">SSL</acronym>,
+ refer to <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a>.
+ </p></dd><dt><span class="term"><code class="option">-N <em class="replaceable"><code>max-connections</code></em></code></span></dt><dd><p>
+ Sets the maximum number of client connections that this
+ server will accept. The default value of this parameter is chosen
+ automatically by <span class="application">initdb</span>.
+ Specifying this option is equivalent to setting the
+ <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> configuration parameter.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP/IP port or local Unix domain socket file
+ extension on which <code class="command">postgres</code>
+ is to listen for connections from client applications.
+ Defaults to the value of the <code class="envar">PGPORT</code> environment
+ variable, or if <code class="envar">PGPORT</code> is not set, then
+ defaults to the value established during compilation (normally
+ 5432). If you specify a port other than the default port,
+ then all client applications must specify the same port using
+ either command-line options or <code class="envar">PGPORT</code>.
+ </p></dd><dt><span class="term"><code class="option">-s</code></span></dt><dd><p>
+ Print time information and other statistics at the end of each command.
+ This is useful for benchmarking or for use in tuning the number of
+ buffers.
+ </p></dd><dt><span class="term"><code class="option">-S</code> <em class="replaceable"><code>work-mem</code></em></span></dt><dd><p>
+ Specifies the base amount of memory to be used by sorts and
+ hash tables before resorting to temporary disk files. See the
+ description of the <code class="varname">work_mem</code> configuration
+ parameter in <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY" title="20.4.1. Memory">Section 20.4.1</a>.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">postgres</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">--<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code></span></dt><dd><p>
+ Sets a named run-time parameter; a shorter form of
+ <code class="option">-c</code>.
+ </p></dd><dt><span class="term"><code class="option">--describe-config</code></span></dt><dd><p>
+ This option dumps out the server's internal configuration variables,
+ descriptions, and defaults in tab-delimited <code class="command">COPY</code> format.
+ It is designed primarily for use by administration tools.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">postgres</span> command line
+ arguments, and exit.
+ </p></dd></dl></div></div><div class="refsect2" id="id-1.9.5.14.6.4"><h3>Semi-Internal Options</h3><p>
+ The options described here are used
+ mainly for debugging purposes, and in some cases to assist with
+ recovery of severely damaged databases. There should be no reason
+ to use them in a production database setup. They are listed
+ here only for use by <span class="productname">PostgreSQL</span>
+ system developers. Furthermore, these options might
+ change or be removed in a future release without notice.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-f</code> <code class="literal">{ s | i | o | b | t | n | m | h }</code></span></dt><dd><p>
+ Forbids the use of particular scan and join methods:
+ <code class="literal">s</code> and <code class="literal">i</code>
+ disable sequential and index scans respectively,
+ <code class="literal">o</code>, <code class="literal">b</code> and <code class="literal">t</code>
+ disable index-only scans, bitmap index scans, and TID scans
+ respectively, while
+ <code class="literal">n</code>, <code class="literal">m</code>, and <code class="literal">h</code>
+ disable nested-loop, merge and hash joins respectively.
+ </p><p>
+ Neither sequential scans nor nested-loop joins can be disabled
+ completely; the <code class="literal">-fs</code> and
+ <code class="literal">-fn</code> options simply discourage the optimizer
+ from using those plan types if it has any other alternative.
+ </p></dd><dt><span class="term"><code class="option">-n</code></span></dt><dd><p>
+ This option is for debugging problems that cause a server
+ process to die abnormally. The ordinary strategy in this
+ situation is to notify all other server processes that they
+ must terminate and then reinitialize the shared memory and
+ semaphores. This is because an errant server process could
+ have corrupted some shared state before terminating. This
+ option specifies that <code class="command">postgres</code> will
+ not reinitialize shared data structures. A knowledgeable
+ system programmer can then use a debugger to examine shared
+ memory and semaphore state.
+ </p></dd><dt><span class="term"><code class="option">-O</code></span></dt><dd><p>
+ Allows the structure of system tables to be modified. This is
+ used by <code class="command">initdb</code>.
+ </p></dd><dt><span class="term"><code class="option">-P</code></span></dt><dd><p>
+ Ignore system indexes when reading system tables, but still update
+ the indexes when modifying the tables. This is useful when
+ recovering from damaged system indexes.
+ </p></dd><dt><span class="term"><code class="option">-t</code> <code class="literal">pa[rser] | pl[anner] | e[xecutor]</code></span></dt><dd><p>
+ Print timing statistics for each query relating to each of the
+ major system modules. This option cannot be used together
+ with the <code class="option">-s</code> option.
+ </p></dd><dt><span class="term"><code class="option">-T</code></span></dt><dd><p>
+ This option is for debugging problems that cause a server
+ process to die abnormally. The ordinary strategy in this
+ situation is to notify all other server processes that they
+ must terminate and then reinitialize the shared memory and
+ semaphores. This is because an errant server process could
+ have corrupted some shared state before terminating. This
+ option specifies that <code class="command">postgres</code> will
+ stop all other server processes by sending the signal
+ <code class="literal">SIGSTOP</code>, but will not cause them to
+ terminate. This permits system programmers to collect core
+ dumps from all server processes by hand.
+ </p></dd><dt><span class="term"><code class="option">-v</code> <em class="replaceable"><code>protocol</code></em></span></dt><dd><p>
+ Specifies the version number of the frontend/backend protocol
+ to be used for a particular session. This option is for
+ internal use only.
+ </p></dd><dt><span class="term"><code class="option">-W</code> <em class="replaceable"><code>seconds</code></em></span></dt><dd><p>
+ A delay of this many seconds occurs when a new server process
+ is started, after it conducts the authentication procedure.
+ This is intended to give an opportunity to attach to the
+ server process with a debugger.
+ </p></dd></dl></div></div><div class="refsect2" id="id-1.9.5.14.6.5"><h3>Options for Single-User Mode</h3><a id="id-1.9.5.14.6.5.2" class="indexterm"></a><p>
+ The following options only apply to the single-user mode
+ (see <a class="xref" href="app-postgres.html#APP-POSTGRES-SINGLE-USER" title="Single-User Mode">Single-User Mode</a> below).
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--single</code></span></dt><dd><p>
+ Selects the single-user mode. This must be the first argument
+ on the command line.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt><dd><p>
+ Specifies the name of the database to be accessed. This must be
+ the last argument on the command line. If it is
+ omitted it defaults to the user name.
+ </p></dd><dt><span class="term"><code class="option">-E</code></span></dt><dd><p>
+ Echo all commands to standard output before executing them.
+ </p></dd><dt><span class="term"><code class="option">-j</code></span></dt><dd><p>
+ Use semicolon followed by two newlines, rather than just newline,
+ as the command entry terminator.
+ </p></dd><dt><span class="term"><code class="option">-r</code> <em class="replaceable"><code>filename</code></em></span></dt><dd><p>
+ Send all server log output to <em class="replaceable"><code>filename</code></em>. This option is only
+ honored when supplied as a command-line option.
+ </p></dd></dl></div></div></div><div class="refsect1" id="id-1.9.5.14.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGCLIENTENCODING</code></span></dt><dd><p>
+ Default character encoding used by clients. (The clients can
+ override this individually.) This value can also be set in the
+ configuration file.
+ </p></dd><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Default data directory location
+ </p></dd><dt><span class="term"><code class="envar">PGDATESTYLE</code></span></dt><dd><p>
+ Default value of the <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a> run-time
+ parameter. (The use of this environment variable is deprecated.)
+ </p></dd><dt><span class="term"><code class="envar">PGPORT</code></span></dt><dd><p>
+ Default port number (preferably set in the configuration file)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.14.8"><h2>Diagnostics</h2><p>
+ A failure message mentioning <code class="literal">semget</code> or
+ <code class="literal">shmget</code> probably indicates you need to configure your
+ kernel to provide adequate shared memory and semaphores. For more
+ discussion see <a class="xref" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Section 19.4</a>. You might be able
+ to postpone reconfiguring your kernel by decreasing <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a> to reduce the shared memory
+ consumption of <span class="productname">PostgreSQL</span>, and/or by reducing
+ <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> to reduce the semaphore
+ consumption.
+ </p><p>
+ A failure message suggesting that another server is already running
+ should be checked carefully, for example by using the command
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>ps ax | grep postgres</code></strong>
+</pre><p>
+ or
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>ps -ef | grep postgres</code></strong>
+</pre><p>
+ depending on your system. If you are certain that no conflicting
+ server is running, you can remove the lock file mentioned in the
+ message and try again.
+ </p><p>
+ A failure message indicating inability to bind to a port might
+ indicate that that port is already in use by some
+ non-<span class="productname">PostgreSQL</span> process. You might also
+ get this error if you terminate <code class="command">postgres</code>
+ and immediately restart it using the same port; in this case, you
+ must simply wait a few seconds until the operating system closes
+ the port before trying again. Finally, you might get this error if
+ you specify a port number that your operating system considers to
+ be reserved. For example, many versions of Unix consider port
+ numbers under 1024 to be <span class="quote">“<span class="quote">trusted</span>”</span> and only permit
+ the Unix superuser to access them.
+ </p></div><div class="refsect1" id="id-1.9.5.14.9"><h2>Notes</h2><p>
+ The utility command <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a> can be used to
+ start and shut down the <code class="command">postgres</code> server
+ safely and comfortably.
+ </p><p>
+ If at all possible, <span class="emphasis"><em>do not</em></span> use
+ <code class="literal">SIGKILL</code> to kill the main
+ <code class="command">postgres</code> server. Doing so will prevent
+ <code class="command">postgres</code> from freeing the system
+ resources (e.g., shared memory and semaphores) that it holds before
+ terminating. This might cause problems for starting a fresh
+ <code class="command">postgres</code> run.
+ </p><p>
+ To terminate the <code class="command">postgres</code> server normally, the
+ signals <code class="literal">SIGTERM</code>, <code class="literal">SIGINT</code>, or
+ <code class="literal">SIGQUIT</code> can be used. The first will wait for
+ all clients to terminate before quitting, the second will
+ forcefully disconnect all clients, and the third will quit
+ immediately without proper shutdown, resulting in a recovery run
+ during restart.
+ </p><p>
+ The <code class="literal">SIGHUP</code> signal will reload
+ the server configuration files. It is also possible to send
+ <code class="literal">SIGHUP</code> to an individual server process, but that
+ is usually not sensible.
+ </p><p>
+ To cancel a running query, send the <code class="literal">SIGINT</code> signal
+ to the process running that command. To terminate a backend process
+ cleanly, send <code class="literal">SIGTERM</code> to that process. See
+ also <code class="function">pg_cancel_backend</code> and <code class="function">pg_terminate_backend</code>
+ in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL" title="9.27.2. Server Signaling Functions">Section 9.27.2</a> for the SQL-callable equivalents
+ of these two actions.
+ </p><p>
+ The <code class="command">postgres</code> server uses <code class="literal">SIGQUIT</code>
+ to tell subordinate server processes to terminate without normal
+ cleanup.
+ This signal <span class="emphasis"><em>should not</em></span> be used by users. It
+ is also unwise to send <code class="literal">SIGKILL</code> to a server
+ process — the main <code class="command">postgres</code> process will
+ interpret this as a crash and will force all the sibling processes
+ to quit as part of its standard crash-recovery procedure.
+ </p></div><div class="refsect1" id="APP-POSTGRES-BUGS"><h2>Bugs</h2><p>
+ The <code class="option">--</code> options will not work on <span class="systemitem">FreeBSD</span> or <span class="systemitem">OpenBSD</span>.
+ Use <code class="option">-c</code> instead. This is a bug in the affected operating
+ systems; a future release of <span class="productname">PostgreSQL</span>
+ will provide a workaround if this is not fixed.
+ </p></div><div class="refsect1" id="APP-POSTGRES-SINGLE-USER"><h2>Single-User Mode</h2><p>
+ To start a single-user mode server, use a command like
+</p><pre class="screen">
+<strong class="userinput"><code>postgres --single -D /usr/local/pgsql/data <em class="replaceable"><code>other-options</code></em> my_database</code></strong>
+</pre><p>
+ Provide the correct path to the database directory with <code class="option">-D</code>, or
+ make sure that the environment variable <code class="envar">PGDATA</code> is set.
+ Also specify the name of the particular database you want to work in.
+ </p><p>
+ Normally, the single-user mode server treats newline as the command
+ entry terminator; there is no intelligence about semicolons,
+ as there is in <span class="application">psql</span>. To continue a command
+ across multiple lines, you must type backslash just before each
+ newline except the last one. The backslash and adjacent newline are
+ both dropped from the input command. Note that this will happen even
+ when within a string literal or comment.
+ </p><p>
+ But if you use the <code class="option">-j</code> command line switch, a single newline
+ does not terminate command entry; instead, the sequence
+ semicolon-newline-newline does. That is, type a semicolon immediately
+ followed by a completely empty line. Backslash-newline is not
+ treated specially in this mode. Again, there is no intelligence about
+ such a sequence appearing within a string literal or comment.
+ </p><p>
+ In either input mode, if you type a semicolon that is not just before or
+ part of a command entry terminator, it is considered a command separator.
+ When you do type a command entry terminator, the multiple statements
+ you've entered will be executed as a single transaction.
+ </p><p>
+ To quit the session, type <acronym class="acronym">EOF</acronym>
+ (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>D</strong></span>, usually).
+ If you've entered any text since the last command entry terminator,
+ then <acronym class="acronym">EOF</acronym> will be taken as a command entry terminator,
+ and another <acronym class="acronym">EOF</acronym> will be needed to exit.
+ </p><p>
+ Note that the single-user mode server does not provide sophisticated
+ line-editing features (no command history, for example).
+ Single-user mode also does not do any background processing, such as
+ automatic checkpoints or replication.
+ </p></div><div class="refsect1" id="APP-POSTGRES-EXAMPLES"><h2>Examples</h2><p>
+ To start <code class="command">postgres</code> in the background
+ using default values, type:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>nohup postgres &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</code></strong>
+</pre><p>
+ </p><p>
+ To start <code class="command">postgres</code> with a specific
+ port, e.g., 1234:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>postgres -p 1234</code></strong>
+</pre><p>
+ To connect to this server using <span class="application">psql</span>, specify this port with the -p option:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>psql -p 1234</code></strong>
+</pre><p>
+ or set the environment variable <code class="envar">PGPORT</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>export PGPORT=1234</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>psql</code></strong>
+</pre><p>
+ </p><p>
+ Named run-time parameters can be set in either of these styles:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>postgres -c work_mem=1234</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>postgres --work-mem=1234</code></strong>
+</pre><p>
+ Either form overrides whatever setting might exist for
+ <code class="varname">work_mem</code> in <code class="filename">postgresql.conf</code>. Notice that
+ underscores in parameter names can be written as either underscore
+ or dash on the command line. Except for short-term experiments,
+ it's probably better practice to edit the setting in
+ <code class="filename">postgresql.conf</code> than to rely on a command-line switch
+ to set a parameter.
+ </p></div><div class="refsect1" id="id-1.9.5.14.13"><h2>See Also</h2><p>
+ <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>,
+ <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgwaldump.html" title="pg_waldump">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-postmaster.html" title="postmaster">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_waldump</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">postmaster</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-postmaster.html b/doc/src/sgml/html/app-postmaster.html
new file mode 100644
index 0000000..d29a306
--- /dev/null
+++ b/doc/src/sgml/html/app-postmaster.html
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>postmaster</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-postgres.html" title="postgres" /><link rel="next" href="internals.html" title="Part VII. Internals" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">postmaster</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-postgres.html" title="postgres">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="internals.html" title="Part VII. Internals">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-POSTMASTER"><div class="titlepage"></div><a id="id-1.9.5.15.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">postmaster</span></span></h2><p>postmaster — <span class="productname">PostgreSQL</span> database server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.15.4.1"><code class="command">postmaster</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.5.15.5"><h2>Description</h2><p>
+ <code class="command">postmaster</code> is a deprecated alias of <code class="command">postgres</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.15.6"><h2>See Also</h2><p>
+ <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-postgres.html" title="postgres">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.html" title="Part VII. Internals">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">postgres</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part VII. Internals</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-psql.html b/doc/src/sgml/html/app-psql.html
new file mode 100644
index 0000000..783b3c4
--- /dev/null
+++ b/doc/src/sgml/html/app-psql.html
@@ -0,0 +1,2959 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>psql</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgverifybackup.html" title="pg_verifybackup" /><link rel="next" href="app-reindexdb.html" title="reindexdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">psql</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgverifybackup.html" title="pg_verifybackup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-reindexdb.html" title="reindexdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PSQL"><div class="titlepage"></div><a id="id-1.9.4.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">psql</span></span></h2><p><span class="application">psql</span> —
+ <span class="productname">PostgreSQL</span> interactive terminal
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.20.4.1"><code class="command">psql</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>
+ [<em class="replaceable"><code>username</code></em>]]</p></div></div><div class="refsect1" id="id-1.9.4.20.5"><h2>Description</h2><p>
+ <span class="application">psql</span> is a terminal-based front-end to
+ <span class="productname">PostgreSQL</span>. It enables you to type in
+ queries interactively, issue them to
+ <span class="productname">PostgreSQL</span>, and see the query results.
+ Alternatively, input can be from a file or from command line
+ arguments. In addition, <span class="application">psql</span> provides a
+ number of meta-commands and various shell-like features to
+ facilitate writing scripts and automating a wide variety of tasks.
+ </p></div><div class="refsect1" id="R1-APP-PSQL-3"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--echo-all</code></span></dt><dd><p>
+ Print all nonempty input lines to standard output as they are read.
+ (This does not apply to lines read interactively.) This is
+ equivalent to setting the variable <code class="varname">ECHO</code> to
+ <code class="literal">all</code>.
+ </p></dd><dt><span class="term"><code class="option">-A</code><br /></span><span class="term"><code class="option">--no-align</code></span></dt><dd><p>
+ Switches to unaligned output mode. (The default output mode is
+ <code class="literal">aligned</code>.) This is equivalent to
+ <code class="command">\pset format unaligned</code>.
+ </p></dd><dt><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--echo-errors</code></span></dt><dd><p>
+ Print failed SQL commands to standard error output. This is
+ equivalent to setting the variable <code class="varname">ECHO</code> to
+ <code class="literal">errors</code>.
+ </p></dd><dt><span class="term"><code class="option">-c <em class="replaceable"><code>command</code></em></code><br /></span><span class="term"><code class="option">--command=<em class="replaceable"><code>command</code></em></code></span></dt><dd><p>
+ Specifies that <span class="application">psql</span> is to execute the given
+ command string, <em class="replaceable"><code>command</code></em>.
+ This option can be repeated and combined in any order with
+ the <code class="option">-f</code> option. When either <code class="option">-c</code>
+ or <code class="option">-f</code> is specified, <span class="application">psql</span>
+ does not read commands from standard input; instead it terminates
+ after processing all the <code class="option">-c</code> and <code class="option">-f</code>
+ options in sequence.
+ </p><p>
+ <em class="replaceable"><code>command</code></em> must be either
+ a command string that is completely parsable by the server (i.e.,
+ it contains no <span class="application">psql</span>-specific features),
+ or a single backslash command. Thus you cannot mix
+ <acronym class="acronym">SQL</acronym> and <span class="application">psql</span>
+ meta-commands within a <code class="option">-c</code> option. To achieve that,
+ you could use repeated <code class="option">-c</code> options or pipe the string
+ into <span class="application">psql</span>, for example:
+</p><pre class="programlisting">
+psql -c '\x' -c 'SELECT * FROM foo;'
+</pre><p>
+ or
+</p><pre class="programlisting">
+echo '\x \\ SELECT * FROM foo;' | psql
+</pre><p>
+ (<code class="literal">\\</code> is the separator meta-command.)
+ </p><p>
+ Each <acronym class="acronym">SQL</acronym> command string passed
+ to <code class="option">-c</code> is sent to the server as a single request.
+ Because of this, the server executes it as a single transaction even
+ if the string contains multiple <acronym class="acronym">SQL</acronym> commands,
+ unless there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>
+ commands included in the string to divide it into multiple
+ transactions. (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="55.2.2.1. Multiple Statements in a Simple Query">Section 55.2.2.1</a>
+ for more details about how the server handles multi-query strings.)
+ </p><p>
+ If having several commands executed in one transaction is not desired,
+ use repeated <code class="option">-c</code> commands or feed multiple commands to
+ <span class="application">psql</span>'s standard input,
+ either using <span class="application">echo</span> as illustrated above, or
+ via a shell here-document, for example:
+</p><pre class="programlisting">
+psql &lt;&lt;EOF
+\x
+SELECT * FROM foo;
+EOF
+</pre></dd><dt><span class="term"><code class="option">--csv</code></span></dt><dd><p>
+ Switches to <acronym class="acronym">CSV</acronym> (Comma-Separated Values) output
+ mode. This is equivalent to <code class="command">\pset format csv</code>.
+ </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to. This is
+ equivalent to specifying <em class="replaceable"><code>dbname</code></em> as the first non-option
+ argument on the command line. The <em class="replaceable"><code>dbname</code></em>
+ can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.
+ If so, connection string parameters will override any conflicting
+ command line options.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo-queries</code></span></dt><dd><p>
+ Copy all SQL commands sent to the server to standard output as well.
+ This is equivalent
+ to setting the variable <code class="varname">ECHO</code> to
+ <code class="literal">queries</code>.
+ </p></dd><dt><span class="term"><code class="option">-E</code><br /></span><span class="term"><code class="option">--echo-hidden</code></span></dt><dd><p>
+ Echo the actual queries generated by <code class="command">\d</code> and other backslash
+ commands. You can use this to study <span class="application">psql</span>'s
+ internal operations. This is equivalent to
+ setting the variable <code class="varname">ECHO_HIDDEN</code> to <code class="literal">on</code>.
+ </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Read commands from the
+ file <em class="replaceable"><code>filename</code></em>,
+ rather than standard input.
+ This option can be repeated and combined in any order with
+ the <code class="option">-c</code> option. When either <code class="option">-c</code>
+ or <code class="option">-f</code> is specified, <span class="application">psql</span>
+ does not read commands from standard input; instead it terminates
+ after processing all the <code class="option">-c</code> and <code class="option">-f</code>
+ options in sequence.
+ Except for that, this option is largely equivalent to the
+ meta-command <code class="command">\i</code>.
+ </p><p>
+ If <em class="replaceable"><code>filename</code></em> is <code class="literal">-</code>
+ (hyphen), then standard input is read until an EOF indication
+ or <code class="command">\q</code> meta-command. This can be used to intersperse
+ interactive input with input from files. Note however that Readline
+ is not used in this case (much as if <code class="option">-n</code> had been
+ specified).
+ </p><p>
+ Using this option is subtly different from writing <code class="literal">psql
+ &lt; <em class="replaceable"><code>filename</code></em></code>. In general,
+ both will do what you expect, but using <code class="literal">-f</code>
+ enables some nice features such as error messages with line
+ numbers. There is also a slight chance that using this option will
+ reduce the start-up overhead. On the other hand, the variant using
+ the shell's input redirection is (in theory) guaranteed to yield
+ exactly the same output you would have received had you entered
+ everything by hand.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>separator</code></em></code><br /></span><span class="term"><code class="option">--field-separator=<em class="replaceable"><code>separator</code></em></code></span></dt><dd><p>
+ Use <em class="replaceable"><code>separator</code></em> as the
+ field separator for unaligned output. This is equivalent to
+ <code class="command">\pset fieldsep</code> or <code class="command">\f</code>.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the
+ server is running. If the value begins
+ with a slash, it is used as the directory for the Unix-domain
+ socket.
+ </p></dd><dt><span class="term"><code class="option">-H</code><br /></span><span class="term"><code class="option">--html</code></span></dt><dd><p>
+ Switches to <acronym class="acronym">HTML</acronym> output mode. This is
+ equivalent to <code class="command">\pset format html</code> or the
+ <code class="command">\H</code> command.
+ </p></dd><dt><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--list</code></span></dt><dd><p>
+ List all available databases, then exit. Other non-connection
+ options are ignored. This is similar to the meta-command
+ <code class="command">\list</code>.
+ </p><p>
+ When this option is used, <span class="application">psql</span> will connect
+ to the database <code class="literal">postgres</code>, unless a different database
+ is named on the command line (option <code class="option">-d</code> or non-option
+ argument, possibly via a service entry, but not via an environment
+ variable).
+ </p></dd><dt><span class="term"><code class="option">-L <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--log-file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Write all query output into file <em class="replaceable"><code>filename</code></em>, in addition to the
+ normal output destination.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-readline</code></span></dt><dd><p>
+ Do not use <span class="application">Readline</span> for line editing and
+ do not use the command history (see
+ <a class="xref" href="app-psql.html#APP-PSQL-READLINE" title="Command-Line Editing">the section called “Command-Line Editing”</a> below).
+ </p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--output=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Put all query output into file <em class="replaceable"><code>filename</code></em>. This is equivalent to
+ the command <code class="command">\o</code>.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or the local Unix-domain
+ socket file extension on which the server is listening for
+ connections. Defaults to the value of the <code class="envar">PGPORT</code>
+ environment variable or, if not set, to the port specified at
+ compile time, usually 5432.
+ </p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--pset=<em class="replaceable"><code>assignment</code></em></code></span></dt><dd><p>
+ Specifies printing options, in the style of
+ <code class="command">\pset</code>. Note that here you
+ have to separate name and value with an equal sign instead of a
+ space. For example, to set the output format to <span class="application">LaTeX</span>, you could write
+ <code class="literal">-P format=latex</code>.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Specifies that <span class="application">psql</span> should do its work
+ quietly. By default, it prints welcome messages and various
+ informational output. If this option is used, none of this
+ happens. This is useful with the <code class="option">-c</code> option.
+ This is equivalent to setting the variable <code class="varname">QUIET</code>
+ to <code class="literal">on</code>.
+ </p></dd><dt><span class="term"><code class="option">-R <em class="replaceable"><code>separator</code></em></code><br /></span><span class="term"><code class="option">--record-separator=<em class="replaceable"><code>separator</code></em></code></span></dt><dd><p>
+ Use <em class="replaceable"><code>separator</code></em> as the
+ record separator for unaligned output. This is equivalent to
+ <code class="command">\pset recordsep</code>.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--single-step</code></span></dt><dd><p>
+ Run in single-step mode. That means the user is prompted before
+ each command is sent to the server, with the option to cancel
+ execution as well. Use this to debug scripts.
+ </p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--single-line</code></span></dt><dd><p>
+ Runs in single-line mode where a newline terminates an SQL command, as a
+ semicolon does.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This mode is provided for those who insist on it, but you are not
+ necessarily encouraged to use it. In particular, if you mix
+ <acronym class="acronym">SQL</acronym> and meta-commands on a line the order of
+ execution might not always be clear to the inexperienced user.
+ </p></div></dd><dt><span class="term"><code class="option">-t</code><br /></span><span class="term"><code class="option">--tuples-only</code></span></dt><dd><p>
+ Turn off printing of column names and result row count footers,
+ etc. This is equivalent to <code class="command">\t</code> or
+ <code class="command">\pset tuples_only</code>.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>table_options</code></em></code><br /></span><span class="term"><code class="option">--table-attr=<em class="replaceable"><code>table_options</code></em></code></span></dt><dd><p>
+ Specifies options to be placed within the
+ <acronym class="acronym">HTML</acronym> <code class="sgmltag-element">table</code> tag. See
+ <code class="command">\pset tableattr</code> for details.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Connect to the database as the user <em class="replaceable"><code>username</code></em> instead of the default.
+ (You must have permission to do so, of course.)
+ </p></dd><dt><span class="term"><code class="option">-v <em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--set=<em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--variable=<em class="replaceable"><code>assignment</code></em></code></span></dt><dd><p>
+ Perform a variable assignment, like the <code class="command">\set</code>
+ meta-command. Note that you must separate name and value, if
+ any, by an equal sign on the command line. To unset a variable,
+ leave off the equal sign. To set a variable with an empty value,
+ use the equal sign but leave off the value. These assignments are
+ done during command line processing, so variables that reflect
+ connection state will get overwritten later.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">psql</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires password
+ authentication and a password is not available from other sources
+ such as a <code class="filename">.pgpass</code> file, the connection
+ attempt will fail. This option can be useful in batch jobs and
+ scripts where no user is present to enter a password.
+ </p><p>
+ Note that this option will remain set for the entire session,
+ and so it affects uses of the meta-command
+ <code class="command">\connect</code> as well as the initial connection attempt.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">psql</span> to prompt for a
+ password before connecting to a database, even if the password will
+ not be used.
+ </p><p>
+ If the server requires password authentication and a password is not
+ available from other sources such as a <code class="filename">.pgpass</code>
+ file, <span class="application">psql</span> will prompt for a
+ password in any case. However, <span class="application">psql</span>
+ will waste a connection attempt finding out that the server wants a
+ password. In some cases it is worth typing <code class="option">-W</code> to avoid
+ the extra connection attempt.
+ </p><p>
+ Note that this option will remain set for the entire session,
+ and so it affects uses of the meta-command
+ <code class="command">\connect</code> as well as the initial connection attempt.
+ </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--expanded</code></span></dt><dd><p>
+ Turn on the expanded table formatting mode. This is equivalent to
+ <code class="command">\x</code> or <code class="command">\pset expanded</code>.
+ </p></dd><dt><span class="term"><code class="option">-X,</code><br /></span><span class="term"><code class="option">--no-psqlrc</code></span></dt><dd><p>
+ Do not read the start-up file (neither the system-wide
+ <code class="filename">psqlrc</code> file nor the user's
+ <code class="filename">~/.psqlrc</code> file).
+ </p></dd><dt><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--field-separator-zero</code></span></dt><dd><p>
+ Set the field separator for unaligned output to a zero byte. This is
+ equivalent to <code class="command">\pset fieldsep_zero</code>.
+ </p></dd><dt><span class="term"><code class="option">-0</code><br /></span><span class="term"><code class="option">--record-separator-zero</code></span></dt><dd><p>
+ Set the record separator for unaligned output to a zero byte. This is
+ useful for interfacing, for example, with <code class="literal">xargs -0</code>.
+ This is equivalent to <code class="command">\pset recordsep_zero</code>.
+ </p></dd><dt><span class="term"><code class="option">-1</code><br /></span><span class="term"><code class="option">--single-transaction</code></span></dt><dd><p>
+ This option can only be used in combination with one or more
+ <code class="option">-c</code> and/or <code class="option">-f</code> options. It causes
+ <span class="application">psql</span> to issue a <code class="command">BEGIN</code> command
+ before the first such option and a <code class="command">COMMIT</code> command after
+ the last one, thereby wrapping all the commands into a single
+ transaction. If any of the commands fails and the variable
+ <code class="varname">ON_ERROR_STOP</code> was set, a
+ <code class="command">ROLLBACK</code> command is sent instead. This ensures that
+ either all the commands complete successfully, or no changes are
+ applied.
+ </p><p>
+ If the commands themselves
+ contain <code class="command">BEGIN</code>, <code class="command">COMMIT</code>,
+ or <code class="command">ROLLBACK</code>, this option will not have the desired
+ effects. Also, if an individual command cannot be executed inside a
+ transaction block, specifying this option will cause the whole
+ transaction to fail.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help[=<em class="replaceable"><code>topic</code></em>]</code></span></dt><dd><p>
+ Show help about <span class="application">psql</span> and exit. The optional
+ <em class="replaceable"><code>topic</code></em> parameter (defaulting
+ to <code class="literal">options</code>) selects which part of <span class="application">psql</span> is
+ explained: <code class="literal">commands</code> describes <span class="application">psql</span>'s
+ backslash commands; <code class="literal">options</code> describes the command-line
+ options that can be passed to <span class="application">psql</span>;
+ and <code class="literal">variables</code> shows help about <span class="application">psql</span> configuration
+ variables.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.4.20.7"><h2>Exit Status</h2><p>
+ <span class="application">psql</span> returns 0 to the shell if it
+ finished normally, 1 if a fatal error of its own occurs (e.g., out of memory,
+ file not found), 2 if the connection to the server went bad
+ and the session was not interactive, and 3 if an error occurred in a
+ script and the variable <code class="varname">ON_ERROR_STOP</code> was set.
+ </p></div><div class="refsect1" id="id-1.9.4.20.8"><h2>Usage</h2><div class="refsect2" id="R2-APP-PSQL-CONNECTING"><h3>Connecting to a Database</h3><p>
+ <span class="application">psql</span> is a regular
+ <span class="productname">PostgreSQL</span> client application. In order
+ to connect to a database you need to know the name of your target
+ database, the host name and port number of the server, and what user
+ name you want to connect as. <span class="application">psql</span> can be
+ told about those parameters via command line options, namely
+ <code class="option">-d</code>, <code class="option">-h</code>, <code class="option">-p</code>, and
+ <code class="option">-U</code> respectively. If an argument is found that does
+ not belong to any option it will be interpreted as the database name
+ (or the user name, if the database name is already given). Not all
+ of these options are required; there are useful defaults. If you omit the host
+ name, <span class="application">psql</span> will connect via a Unix-domain socket
+ to a server on the local host, or via TCP/IP to <code class="literal">localhost</code> on
+ machines that don't have Unix-domain sockets. The default port number is
+ determined at compile time.
+ Since the database server uses the same default, you will not have
+ to specify the port in most cases. The default user name is your
+ operating-system user name, as is the default database name.
+ Note that you cannot
+ just connect to any database under any user name. Your database
+ administrator should have informed you about your access rights.
+ </p><p>
+ When the defaults aren't quite right, you can save yourself
+ some typing by setting the environment variables
+ <code class="envar">PGDATABASE</code>, <code class="envar">PGHOST</code>,
+ <code class="envar">PGPORT</code> and/or <code class="envar">PGUSER</code> to appropriate
+ values. (For additional environment variables, see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>.) It is also convenient to have a
+ <code class="filename">~/.pgpass</code> file to avoid regularly having to type in
+ passwords. See <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> for more information.
+ </p><p>
+ An alternative way to specify connection parameters is in a
+ <em class="parameter"><code>conninfo</code></em> string or
+ a <acronym class="acronym">URI</acronym>, which is used instead of a database
+ name. This mechanism give you very wide control over the
+ connection. For example:
+</p><pre class="programlisting">
+$ <strong class="userinput"><code>psql "service=myservice sslmode=require"</code></strong>
+$ <strong class="userinput"><code>psql postgresql://dbmaster:5433/mydb?sslmode=require</code></strong>
+</pre><p>
+ This way you can also use <acronym class="acronym">LDAP</acronym> for connection
+ parameter lookup as described in <a class="xref" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Section 34.18</a>.
+ See <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for more information on all the
+ available connection options.
+ </p><p>
+ If the connection could not be made for any reason (e.g., insufficient
+ privileges, server is not running on the targeted host, etc.),
+ <span class="application">psql</span> will return an error and terminate.
+ </p><p>
+ If both standard input and standard output are a
+ terminal, then <span class="application">psql</span> sets the client
+ encoding to <span class="quote">“<span class="quote">auto</span>”</span>, which will detect the
+ appropriate client encoding from the locale settings
+ (<code class="envar">LC_CTYPE</code> environment variable on Unix systems).
+ If this doesn't work out as expected, the client encoding can be
+ overridden using the environment
+ variable <code class="envar">PGCLIENTENCODING</code>.
+ </p></div><div class="refsect2" id="R2-APP-PSQL-4"><h3>Entering SQL Commands</h3><p>
+ In normal operation, <span class="application">psql</span> provides a
+ prompt with the name of the database to which
+ <span class="application">psql</span> is currently connected, followed by
+ the string <code class="literal">=&gt;</code>. For example:
+</p><pre class="programlisting">
+$ <strong class="userinput"><code>psql testdb</code></strong>
+psql (15.5)
+Type "help" for help.
+
+testdb=&gt;
+</pre><p>
+ </p><p>
+ At the prompt, the user can type in <acronym class="acronym">SQL</acronym> commands.
+ Ordinarily, input lines are sent to the server when a
+ command-terminating semicolon is reached. An end of line does not
+ terminate a command. Thus commands can be spread over several lines for
+ clarity. If the command was sent and executed without error, the results
+ of the command are displayed on the screen.
+ </p><p>
+ If untrusted users have access to a database that has not adopted a
+ <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
+ begin your session by removing publicly-writable schemas
+ from <code class="varname">search_path</code>. One can
+ add <code class="literal">options=-csearch_path=</code> to the connection string or
+ issue <code class="literal">SELECT pg_catalog.set_config('search_path', '',
+ false)</code> before other SQL commands. This consideration is not
+ specific to <span class="application">psql</span>; it applies to every interface
+ for executing arbitrary SQL commands.
+ </p><p>
+ Whenever a command is executed, <span class="application">psql</span> also polls
+ for asynchronous notification events generated by
+ <a class="link" href="sql-listen.html" title="LISTEN"><code class="command">LISTEN</code></a> and
+ <a class="link" href="sql-notify.html" title="NOTIFY"><code class="command">NOTIFY</code></a>.
+ </p><p>
+ While C-style block comments are passed to the server for
+ processing and removal, SQL-standard comments are removed by
+ <span class="application">psql</span>.
+ </p></div><div class="refsect2" id="APP-PSQL-META-COMMANDS"><h3>Meta-Commands</h3><p>
+ Anything you enter in <span class="application">psql</span> that begins
+ with an unquoted backslash is a <span class="application">psql</span>
+ meta-command that is processed by <span class="application">psql</span>
+ itself. These commands make
+ <span class="application">psql</span> more useful for administration or
+ scripting. Meta-commands are often called slash or backslash commands.
+ </p><p>
+ The format of a <span class="application">psql</span> command is the backslash,
+ followed immediately by a command verb, then any arguments. The arguments
+ are separated from the command verb and each other by any number of
+ whitespace characters.
+ </p><p>
+ To include whitespace in an argument you can quote it with
+ single quotes. To include a single quote in an argument,
+ write two single quotes within single-quoted text.
+ Anything contained in single quotes is
+ furthermore subject to C-like substitutions for
+ <code class="literal">\n</code> (new line), <code class="literal">\t</code> (tab),
+ <code class="literal">\b</code> (backspace), <code class="literal">\r</code> (carriage return),
+ <code class="literal">\f</code> (form feed),
+ <code class="literal">\</code><em class="replaceable"><code>digits</code></em> (octal), and
+ <code class="literal">\x</code><em class="replaceable"><code>digits</code></em> (hexadecimal).
+ A backslash preceding any other character within single-quoted text
+ quotes that single character, whatever it is.
+ </p><p>
+ If an unquoted colon (<code class="literal">:</code>) followed by a
+ <span class="application">psql</span> variable name appears within an argument, it is
+ replaced by the variable's value, as described in <a class="xref" href="app-psql.html#APP-PSQL-INTERPOLATION" title="SQL Interpolation">SQL Interpolation</a> below.
+ The forms <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> and
+ <code class="literal">:"<em class="replaceable"><code>variable_name</code></em>"</code> described there
+ work as well.
+ The <code class="literal">:{?<em class="replaceable"><code>variable_name</code></em>}</code> syntax allows
+ testing whether a variable is defined. It is substituted by
+ TRUE or FALSE.
+ Escaping the colon with a backslash protects it from substitution.
+ </p><p>
+ Within an argument, text that is enclosed in backquotes
+ (<code class="literal">`</code>) is taken as a command line that is passed to the
+ shell. The output of the command (with any trailing newline removed)
+ replaces the backquoted text. Within the text enclosed in backquotes,
+ no special quoting or other processing occurs, except that appearances
+ of <code class="literal">:<em class="replaceable"><code>variable_name</code></em></code> where
+ <em class="replaceable"><code>variable_name</code></em> is a <span class="application">psql</span> variable name
+ are replaced by the variable's value. Also, appearances of
+ <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> are replaced by the
+ variable's value suitably quoted to become a single shell command
+ argument. (The latter form is almost always preferable, unless you are
+ very sure of what is in the variable.) Because carriage return and line
+ feed characters cannot be safely quoted on all platforms, the
+ <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> form prints an
+ error message and does not substitute the variable value when such
+ characters appear in the value.
+ </p><p>
+ Some commands take an <acronym class="acronym">SQL</acronym> identifier (such as a
+ table name) as argument. These arguments follow the syntax rules
+ of <acronym class="acronym">SQL</acronym>: Unquoted letters are forced to
+ lowercase, while double quotes (<code class="literal">"</code>) protect letters
+ from case conversion and allow incorporation of whitespace into
+ the identifier. Within double quotes, paired double quotes reduce
+ to a single double quote in the resulting name. For example,
+ <code class="literal">FOO"BAR"BAZ</code> is interpreted as <code class="literal">fooBARbaz</code>,
+ and <code class="literal">"A weird"" name"</code> becomes <code class="literal">A weird"
+ name</code>.
+ </p><p>
+ Parsing for arguments stops at the end of the line, or when another
+ unquoted backslash is found. An unquoted backslash
+ is taken as the beginning of a new meta-command. The special
+ sequence <code class="literal">\\</code> (two backslashes) marks the end of
+ arguments and continues parsing <acronym class="acronym">SQL</acronym> commands, if
+ any. That way <acronym class="acronym">SQL</acronym> and
+ <span class="application">psql</span> commands can be freely mixed on a
+ line. But in any case, the arguments of a meta-command cannot
+ continue beyond the end of the line.
+ </p><p>
+ Many of the meta-commands act on the <em class="firstterm">current query buffer</em>.
+ This is simply a buffer holding whatever SQL command text has been typed
+ but not yet sent to the server for execution. This will include previous
+ input lines as well as any text appearing before the meta-command on the
+ same line.
+ </p><p>
+ The following meta-commands are defined:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">\a</code></span></dt><dd><p>
+ If the current table output format is unaligned, it is switched to aligned.
+ If it is not unaligned, it is set to unaligned. This command is
+ kept for backwards compatibility. See <code class="command">\pset</code> for a
+ more general solution.
+ </p></dd><dt><span class="term"><code class="literal">\c</code> or <code class="literal">\connect [ -reuse-previous=<em class="replaceable"><code>on|off</code></em> ] [ <em class="replaceable"><code>dbname</code></em> [ <em class="replaceable"><code>username</code></em> ] [ <em class="replaceable"><code>host</code></em> ] [ <em class="replaceable"><code>port</code></em> ] | <em class="replaceable"><code>conninfo</code></em> ]</code></span></dt><dd><p>
+ Establishes a new connection to a <span class="productname">PostgreSQL</span>
+ server. The connection parameters to use can be specified either
+ using a positional syntax (one or more of database name, user,
+ host, and port), or using a <em class="replaceable"><code>conninfo</code></em>
+ connection string as detailed in
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>. If no arguments are given, a
+ new connection is made using the same parameters as before.
+ </p><p>
+ Specifying any
+ of <em class="replaceable"><code>dbname</code></em>,
+ <em class="replaceable"><code>username</code></em>,
+ <em class="replaceable"><code>host</code></em> or
+ <em class="replaceable"><code>port</code></em>
+ as <code class="literal">-</code> is equivalent to omitting that parameter.
+ </p><p>
+ The new connection can re-use connection parameters from the previous
+ connection; not only database name, user, host, and port, but other
+ settings such as <em class="replaceable"><code>sslmode</code></em>. By default,
+ parameters are re-used in the positional syntax, but not when
+ a <em class="replaceable"><code>conninfo</code></em> string is given. Passing a
+ first argument of <code class="literal">-reuse-previous=on</code>
+ or <code class="literal">-reuse-previous=off</code> overrides that default. If
+ parameters are re-used, then any parameter not explicitly specified as
+ a positional parameter or in the <em class="replaceable"><code>conninfo</code></em>
+ string is taken from the existing connection's parameters. An
+ exception is that if the <em class="replaceable"><code>host</code></em> setting
+ is changed from its previous value using the positional syntax,
+ any <em class="replaceable"><code>hostaddr</code></em> setting present in the
+ existing connection's parameters is dropped.
+ Also, any password used for the existing connection will be re-used
+ only if the user, host, and port settings are not changed.
+ When the command neither specifies nor reuses a particular parameter,
+ the <span class="application">libpq</span> default is used.
+ </p><p>
+ If the new connection is successfully made, the previous
+ connection is closed.
+ If the connection attempt fails (wrong user name, access
+ denied, etc.), the previous connection will be kept if
+ <span class="application">psql</span> is in interactive mode. But when
+ executing a non-interactive script, the old connection is closed
+ and an error is reported. That may or may not terminate the
+ script; if it does not, all database-accessing commands will fail
+ until another <code class="literal">\connect</code> command is successfully
+ executed. This distinction was chosen as
+ a user convenience against typos on the one hand, and a safety
+ mechanism that scripts are not accidentally acting on the
+ wrong database on the other hand.
+ Note that whenever a <code class="literal">\connect</code> command attempts
+ to re-use parameters, the values re-used are those of the last
+ successful connection, not of any failed attempts made subsequently.
+ However, in the case of a
+ non-interactive <code class="literal">\connect</code> failure, no parameters
+ are allowed to be re-used later, since the script would likely be
+ expecting the values from the failed <code class="literal">\connect</code>
+ to be re-used.
+ </p><p>
+ Examples:
+ </p><pre class="programlisting">
+=&gt; \c mydb myuser host.dom 6432
+=&gt; \c service=foo
+=&gt; \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
+=&gt; \c -reuse-previous=on sslmode=require -- changes only sslmode
+=&gt; \c postgresql://tom@localhost/mydb?application_name=myapp
+</pre></dd><dt><span class="term"><code class="literal">\C [ <em class="replaceable"><code>title</code></em> ]</code></span></dt><dd><p>
+ Sets the title of any tables being printed as the result of a
+ query or unset any such title. This command is equivalent to
+ <code class="literal">\pset title <em class="replaceable"><code>title</code></em></code>. (The name of
+ this command derives from <span class="quote">“<span class="quote">caption</span>”</span>, as it was
+ previously only used to set the caption in an
+ <acronym class="acronym">HTML</acronym> table.)
+ </p></dd><dt><span class="term"><code class="literal">\cd [ <em class="replaceable"><code>directory</code></em> ]</code></span></dt><dd><p>
+ Changes the current working directory to
+ <em class="replaceable"><code>directory</code></em>. Without argument, changes
+ to the current user's home directory.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ To print your current working directory, use <code class="literal">\! pwd</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">\conninfo</code></span></dt><dd><p>
+ Outputs information about the current database connection.
+ </p></dd><dt id="APP-PSQL-META-COMMANDS-COPY"><span class="term"><code class="literal">\copy { <em class="replaceable"><code>table</code></em> [ ( <em class="replaceable"><code>column_list</code></em> ) ] }
+ <code class="literal">from</code>
+ { <em class="replaceable"><code>'filename'</code></em> | program <em class="replaceable"><code>'command'</code></em> | stdin | pstdin }
+ [ [ with ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+ [ where <em class="replaceable"><code>condition</code></em> ]</code><br /></span><span class="term"><code class="literal">\copy { <em class="replaceable"><code>table</code></em> [ ( <em class="replaceable"><code>column_list</code></em> ) ] | ( <em class="replaceable"><code>query</code></em> ) }
+ <code class="literal">to</code>
+ { <em class="replaceable"><code>'filename'</code></em> | program <em class="replaceable"><code>'command'</code></em> | stdout | pstdout }
+ [ [ with ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]</code></span></dt><dd><p>
+ Performs a frontend (client) copy. This is an operation that
+ runs an <acronym class="acronym">SQL</acronym> <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a>
+ command, but instead of the server
+ reading or writing the specified file,
+ <span class="application">psql</span> reads or writes the file and
+ routes the data between the server and the local file system.
+ This means that file accessibility and privileges are those of
+ the local user, not the server, and no SQL superuser
+ privileges are required.
+ </p><p>
+ When <code class="literal">program</code> is specified,
+ <em class="replaceable"><code>command</code></em> is
+ executed by <span class="application">psql</span> and the data passed from
+ or to <em class="replaceable"><code>command</code></em> is
+ routed between the server and the client.
+ Again, the execution privileges are those of
+ the local user, not the server, and no SQL superuser
+ privileges are required.
+ </p><p>
+ For <code class="literal">\copy ... from stdin</code>, data rows are read from the same
+ source that issued the command, continuing until <code class="literal">\.</code>
+ is read or the stream reaches <acronym class="acronym">EOF</acronym>. This option is useful
+ for populating tables in-line within an SQL script file.
+ For <code class="literal">\copy ... to stdout</code>, output is sent to the same place
+ as <span class="application">psql</span> command output, and
+ the <code class="literal">COPY <em class="replaceable"><code>count</code></em></code> command status is
+ not printed (since it might be confused with a data row).
+ To read/write <span class="application">psql</span>'s standard input or
+ output regardless of the current command source or <code class="literal">\o</code>
+ option, write <code class="literal">from pstdin</code> or <code class="literal">to pstdout</code>.
+ </p><p>
+ The syntax of this command is similar to that of the
+ <acronym class="acronym">SQL</acronym> <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a>
+ command. All options other than the data source/destination are
+ as specified for <code class="command">COPY</code>.
+ Because of this, special parsing rules apply to the <code class="command">\copy</code>
+ meta-command. Unlike most other meta-commands, the entire remainder
+ of the line is always taken to be the arguments of <code class="command">\copy</code>,
+ and neither variable interpolation nor backquote expansion are
+ performed in the arguments.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Another way to obtain the same result as <code class="literal">\copy
+ ... to</code> is to use the <acronym class="acronym">SQL</acronym> <code class="literal">COPY
+ ... TO STDOUT</code> command and terminate it
+ with <code class="literal">\g <em class="replaceable"><code>filename</code></em></code>
+ or <code class="literal">\g |<em class="replaceable"><code>program</code></em></code>.
+ Unlike <code class="literal">\copy</code>, this method allows the command to
+ span multiple lines; also, variable interpolation and backquote
+ expansion can be used.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ These operations are not as efficient as the <acronym class="acronym">SQL</acronym>
+ <code class="command">COPY</code> command with a file or program data source or
+ destination, because all data must pass through the client/server
+ connection. For large amounts of data the <acronym class="acronym">SQL</acronym>
+ command might be preferable.
+ Also, because of this pass-through method, <code class="literal">\copy
+ ... from</code> in <acronym class="acronym">CSV</acronym> mode will erroneously
+ treat a <code class="literal">\.</code> data value alone on a line as an
+ end-of-input marker.
+ </p></div></dd><dt><span class="term"><code class="literal">\copyright</code></span></dt><dd><p>
+ Shows the copyright and distribution terms of
+ <span class="productname">PostgreSQL</span>.
+ </p></dd><dt id="APP-PSQL-META-COMMANDS-CROSSTABVIEW"><span class="term"><code class="literal">\crosstabview [
+ <em class="replaceable"><code>colV</code></em>
+ [ <em class="replaceable"><code>colH</code></em>
+ [ <em class="replaceable"><code>colD</code></em>
+ [ <em class="replaceable"><code>sortcolH</code></em>
+ ] ] ] ] </code></span></dt><dd><p>
+ Executes the current query buffer (like <code class="literal">\g</code>) and
+ shows the results in a crosstab grid.
+ The query must return at least three columns.
+ The output column identified by <em class="replaceable"><code>colV</code></em>
+ becomes a vertical header and the output column identified by
+ <em class="replaceable"><code>colH</code></em>
+ becomes a horizontal header.
+ <em class="replaceable"><code>colD</code></em> identifies
+ the output column to display within the grid.
+ <em class="replaceable"><code>sortcolH</code></em> identifies
+ an optional sort column for the horizontal header.
+ </p><p>
+ Each column specification can be a column number (starting at 1) or
+ a column name. The usual SQL case folding and quoting rules apply to
+ column names. If omitted,
+ <em class="replaceable"><code>colV</code></em> is taken as column 1
+ and <em class="replaceable"><code>colH</code></em> as column 2.
+ <em class="replaceable"><code>colH</code></em> must differ from
+ <em class="replaceable"><code>colV</code></em>.
+ If <em class="replaceable"><code>colD</code></em> is not
+ specified, then there must be exactly three columns in the query
+ result, and the column that is neither
+ <em class="replaceable"><code>colV</code></em> nor
+ <em class="replaceable"><code>colH</code></em>
+ is taken to be <em class="replaceable"><code>colD</code></em>.
+ </p><p>
+ The vertical header, displayed as the leftmost column, contains the
+ values found in column <em class="replaceable"><code>colV</code></em>, in the
+ same order as in the query results, but with duplicates removed.
+ </p><p>
+ The horizontal header, displayed as the first row, contains the values
+ found in column <em class="replaceable"><code>colH</code></em>,
+ with duplicates removed. By default, these appear in the same order
+ as in the query results. But if the
+ optional <em class="replaceable"><code>sortcolH</code></em> argument is given,
+ it identifies a column whose values must be integer numbers, and the
+ values from <em class="replaceable"><code>colH</code></em> will
+ appear in the horizontal header sorted according to the
+ corresponding <em class="replaceable"><code>sortcolH</code></em> values.
+ </p><p>
+ Inside the crosstab grid, for each distinct value <code class="literal">x</code>
+ of <em class="replaceable"><code>colH</code></em> and each distinct
+ value <code class="literal">y</code>
+ of <em class="replaceable"><code>colV</code></em>, the cell located
+ at the intersection <code class="literal">(x,y)</code> contains the value of
+ the <code class="literal">colD</code> column in the query result row for which
+ the value of <em class="replaceable"><code>colH</code></em>
+ is <code class="literal">x</code> and the value
+ of <em class="replaceable"><code>colV</code></em>
+ is <code class="literal">y</code>. If there is no such row, the cell is empty. If
+ there are multiple such rows, an error is reported.
+ </p></dd><dt><span class="term"><code class="literal">\d[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ For each relation (table, view, materialized view, index, sequence,
+ or foreign table)
+ or composite type matching the
+ <em class="replaceable"><code>pattern</code></em>, show all
+ columns, their types, the tablespace (if not the default) and any
+ special attributes such as <code class="literal">NOT NULL</code> or defaults.
+ Associated indexes, constraints, rules, and triggers are
+ also shown. For foreign tables, the associated foreign
+ server is shown as well.
+ (<span class="quote">“<span class="quote">Matching the pattern</span>”</span> is defined in
+ <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below.)
+ </p><p>
+ For some types of relation, <code class="literal">\d</code> shows additional information
+ for each column: column values for sequences, indexed expressions for
+ indexes, and foreign data wrapper options for foreign tables.
+ </p><p>
+ The command form <code class="literal">\d+</code> is identical, except that
+ more information is displayed: any comments associated with the
+ columns of the table are shown, as is the presence of OIDs in the
+ table, the view definition if the relation is a view, a non-default
+ <a class="link" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY">replica
+ identity</a> setting and the
+ <a class="link" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">access method</a> name
+ if the relation has an access method.
+ </p><p>
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If <code class="command">\d</code> is used without a
+ <em class="replaceable"><code>pattern</code></em> argument, it is
+ equivalent to <code class="command">\dtvmsE</code> which will show a list of
+ all visible tables, views, materialized views, sequences and
+ foreign tables.
+ This is purely a convenience measure.
+ </p></div></dd><dt><span class="term"><code class="literal">\da[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists aggregate functions, together with their
+ return type and the data types they operate on. If <em class="replaceable"><code>pattern</code></em>
+ is specified, only aggregates whose names match the pattern are shown.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ </p></dd><dt><span class="term"><code class="literal">\dA[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists access methods. If <em class="replaceable"><code>pattern</code></em> is specified, only access
+ methods whose names match the pattern are shown. If
+ <code class="literal">+</code> is appended to the command name, each access
+ method is listed with its associated handler function and description.
+ </p></dd><dt><span class="term">
+ <code class="literal">\dAc[+]
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>input-type-pattern</code></em></a>]]
+ </code>
+ </span></dt><dd><p>
+ Lists operator classes
+ (see <a class="xref" href="xindex.html#XINDEX-OPCLASS" title="38.16.1. Index Methods and Operator Classes">Section 38.16.1</a>).
+ If <em class="replaceable"><code>access-method-pattern</code></em>
+ is specified, only operator classes associated with access methods whose
+ names match that pattern are listed.
+ If <em class="replaceable"><code>input-type-pattern</code></em>
+ is specified, only operator classes associated with input types whose
+ names match that pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, each operator
+ class is listed with its associated operator family and owner.
+ </p></dd><dt><span class="term">
+ <code class="literal">\dAf[+]
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>input-type-pattern</code></em></a>]]
+ </code>
+ </span></dt><dd><p>
+ Lists operator families
+ (see <a class="xref" href="xindex.html#XINDEX-OPFAMILY" title="38.16.5. Operator Classes and Operator Families">Section 38.16.5</a>).
+ If <em class="replaceable"><code>access-method-pattern</code></em>
+ is specified, only operator families associated with access methods whose
+ names match that pattern are listed.
+ If <em class="replaceable"><code>input-type-pattern</code></em>
+ is specified, only operator families associated with input types whose
+ names match that pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, each operator
+ family is listed with its owner.
+ </p></dd><dt><span class="term">
+ <code class="literal">\dAo[+]
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>operator-family-pattern</code></em></a>]]
+ </code>
+ </span></dt><dd><p>
+ Lists operators associated with operator families
+ (see <a class="xref" href="xindex.html#XINDEX-STRATEGIES" title="38.16.2. Index Method Strategies">Section 38.16.2</a>).
+ If <em class="replaceable"><code>access-method-pattern</code></em>
+ is specified, only members of operator families associated with access
+ methods whose names match that pattern are listed.
+ If <em class="replaceable"><code>operator-family-pattern</code></em>
+ is specified, only members of operator families whose names match that
+ pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, each operator
+ is listed with its sort operator family (if it is an ordering operator).
+ </p></dd><dt><span class="term">
+ <code class="literal">\dAp[+]
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>
+ [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>operator-family-pattern</code></em></a>]]
+ </code>
+ </span></dt><dd><p>
+ Lists support functions associated with operator families
+ (see <a class="xref" href="xindex.html#XINDEX-SUPPORT" title="38.16.3. Index Method Support Routines">Section 38.16.3</a>).
+ If <em class="replaceable"><code>access-method-pattern</code></em>
+ is specified, only functions of operator families associated with
+ access methods whose names match that pattern are listed.
+ If <em class="replaceable"><code>operator-family-pattern</code></em>
+ is specified, only functions of operator families whose names match
+ that pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, functions are
+ displayed verbosely, with their actual parameter lists.
+ </p></dd><dt><span class="term"><code class="literal">\db[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists tablespaces. If <em class="replaceable"><code>pattern</code></em>
+ is specified, only tablespaces whose names match the pattern are shown.
+ If <code class="literal">+</code> is appended to the command name, each tablespace
+ is listed with its associated options, on-disk size, permissions and
+ description.
+ </p></dd><dt><span class="term"><code class="literal">\dc[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists conversions between character-set encodings.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only conversions whose names match the pattern are
+ listed.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ If <code class="literal">+</code> is appended to the command name, each object
+ is listed with its associated description.
+ </p></dd><dt><span class="term"><code class="literal">\dconfig[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists server configuration parameters and their values.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only parameters whose names match the pattern are listed. Without
+ a <em class="replaceable"><code>pattern</code></em>, only
+ parameters that are set to non-default values are listed.
+ (Use <code class="literal">\dconfig *</code> to see all parameters.)
+ If <code class="literal">+</code> is appended to the command name, each
+ parameter is listed with its data type, context in which the
+ parameter can be set, and access privileges (if non-default access
+ privileges have been granted).
+ </p></dd><dt><span class="term"><code class="literal">\dC[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists type casts.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only casts whose source or target types match the
+ pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, each object
+ is listed with its associated description.
+ </p></dd><dt><span class="term"><code class="literal">\dd[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Shows the descriptions of objects of type <code class="literal">constraint</code>,
+ <code class="literal">operator class</code>, <code class="literal">operator family</code>,
+ <code class="literal">rule</code>, and <code class="literal">trigger</code>. All
+ other comments may be viewed by the respective backslash commands for
+ those object types.
+ </p><p><code class="literal">\dd</code> displays descriptions for objects matching the
+ <em class="replaceable"><code>pattern</code></em>, or of visible
+ objects of the appropriate type if no argument is given. But in either
+ case, only objects that have a description are listed.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ </p><p>
+ Descriptions for objects can be created with the <a class="link" href="sql-comment.html" title="COMMENT"><code class="command">COMMENT</code></a>
+ <acronym class="acronym">SQL</acronym> command.
+ </p></dd><dt><span class="term"><code class="literal">\dD[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists domains. If <em class="replaceable"><code>pattern</code></em>
+ is specified, only domains whose names match the pattern are shown.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ If <code class="literal">+</code> is appended to the command name, each object
+ is listed with its associated permissions and description.
+ </p></dd><dt><span class="term"><code class="literal">\ddp [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists default access privilege settings. An entry is shown for
+ each role (and schema, if applicable) for which the default
+ privilege settings have been changed from the built-in defaults.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only entries whose role name or schema name matches
+ the pattern are listed.
+ </p><p>
+ The <a class="link" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES"><code class="command">ALTER DEFAULT
+ PRIVILEGES</code></a> command is used to set default access
+ privileges. The meaning of the privilege display is explained in
+ <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.
+ </p></dd><dt><span class="term"><code class="literal">\dE[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\di[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dm[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\ds[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dt[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dv[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ In this group of commands, the letters <code class="literal">E</code>,
+ <code class="literal">i</code>, <code class="literal">m</code>, <code class="literal">s</code>,
+ <code class="literal">t</code>, and <code class="literal">v</code>
+ stand for foreign table, index, materialized view,
+ sequence, table, and view,
+ respectively.
+ You can specify any or all of
+ these letters, in any order, to obtain a listing of objects
+ of these types. For example, <code class="literal">\dti</code> lists
+ tables and indexes. If <code class="literal">+</code> is
+ appended to the command name, each object is listed with its
+ persistence status (permanent, temporary, or unlogged),
+ physical size on disk, and associated description if any.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only objects whose names match the pattern are listed.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ </p></dd><dt><span class="term"><code class="literal">\des[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists foreign servers (mnemonic: <span class="quote">“<span class="quote">external
+ servers</span>”</span>).
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only those servers whose name matches the pattern
+ are listed. If the form <code class="literal">\des+</code> is used, a
+ full description of each server is shown, including the
+ server's access privileges, type, version, options, and description.
+ </p></dd><dt><span class="term"><code class="literal">\det[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists foreign tables (mnemonic: <span class="quote">“<span class="quote">external tables</span>”</span>).
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only entries whose table name or schema name matches
+ the pattern are listed. If the form <code class="literal">\det+</code>
+ is used, generic options and the foreign table description
+ are also displayed.
+ </p></dd><dt><span class="term"><code class="literal">\deu[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists user mappings (mnemonic: <span class="quote">“<span class="quote">external
+ users</span>”</span>).
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only those mappings whose user names match the
+ pattern are listed. If the form <code class="literal">\deu+</code> is
+ used, additional information about each mapping is shown.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ <code class="literal">\deu+</code> might also display the user name and
+ password of the remote user, so care should be taken not to
+ disclose them.
+ </p></div></dd><dt><span class="term"><code class="literal">\dew[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists foreign-data wrappers (mnemonic: <span class="quote">“<span class="quote">external
+ wrappers</span>”</span>).
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only those foreign-data wrappers whose name matches
+ the pattern are listed. If the form <code class="literal">\dew+</code>
+ is used, the access privileges, options, and description of the
+ foreign-data wrapper are also shown.
+ </p></dd><dt><span class="term"><code class="literal">\df[anptwS+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> [ <em class="replaceable"><code>arg_pattern</code></em> ... ] ]</code></span></dt><dd><p>
+ Lists functions, together with their result data types, argument data
+ types, and function types, which are classified as <span class="quote">“<span class="quote">agg</span>”</span>
+ (aggregate), <span class="quote">“<span class="quote">normal</span>”</span>, <span class="quote">“<span class="quote">procedure</span>”</span>, <span class="quote">“<span class="quote">trigger</span>”</span>, or <span class="quote">“<span class="quote">window</span>”</span>.
+ To display only functions
+ of specific type(s), add the corresponding letters <code class="literal">a</code>,
+ <code class="literal">n</code>, <code class="literal">p</code>, <code class="literal">t</code>, or <code class="literal">w</code> to the command.
+ If <em class="replaceable"><code>pattern</code></em> is specified, only
+ functions whose names match the pattern are shown.
+ Any additional arguments are type-name patterns, which are matched
+ to the type names of the first, second, and so on arguments of the
+ function. (Matching functions can have more arguments than what
+ you specify. To prevent that, write a dash <code class="literal">-</code> as
+ the last <em class="replaceable"><code>arg_pattern</code></em>.)
+ By default, only user-created
+ objects are shown; supply a pattern or the <code class="literal">S</code>
+ modifier to include system objects.
+ If the form <code class="literal">\df+</code> is used, additional information
+ about each function is shown, including volatility,
+ parallel safety, owner, security classification, access privileges,
+ language, source code and description.
+ </p></dd><dt><span class="term"><code class="literal">\dF[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists text search configurations.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only configurations whose names match the pattern are shown.
+ If the form <code class="literal">\dF+</code> is used, a full description of
+ each configuration is shown, including the underlying text search
+ parser and the dictionary list for each parser token type.
+ </p></dd><dt><span class="term"><code class="literal">\dFd[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists text search dictionaries.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only dictionaries whose names match the pattern are shown.
+ If the form <code class="literal">\dFd+</code> is used, additional information
+ is shown about each selected dictionary, including the underlying
+ text search template and the option values.
+ </p></dd><dt><span class="term"><code class="literal">\dFp[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists text search parsers.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only parsers whose names match the pattern are shown.
+ If the form <code class="literal">\dFp+</code> is used, a full description of
+ each parser is shown, including the underlying functions and the
+ list of recognized token types.
+ </p></dd><dt><span class="term"><code class="literal">\dFt[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists text search templates.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only templates whose names match the pattern are shown.
+ If the form <code class="literal">\dFt+</code> is used, additional information
+ is shown about each template, including the underlying function names.
+ </p></dd><dt><span class="term"><code class="literal">\dg[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists database roles.
+ (Since the concepts of <span class="quote">“<span class="quote">users</span>”</span> and <span class="quote">“<span class="quote">groups</span>”</span> have been
+ unified into <span class="quote">“<span class="quote">roles</span>”</span>, this command is now equivalent to
+ <code class="literal">\du</code>.)
+ By default, only user-created roles are shown; supply the
+ <code class="literal">S</code> modifier to include system roles.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only those roles whose names match the pattern are listed.
+ If the form <code class="literal">\dg+</code> is used, additional information
+ is shown about each role; currently this adds the comment for each
+ role.
+ </p></dd><dt><span class="term"><code class="literal">\dl[+]</code></span></dt><dd><p>
+ This is an alias for <code class="command">\lo_list</code>, which shows a
+ list of large objects.
+ If <code class="literal">+</code> is appended to the command name,
+ each large object is listed with its associated permissions,
+ if any.
+ </p></dd><dt><span class="term"><code class="literal">\dL[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists procedural languages. If <em class="replaceable"><code>pattern</code></em>
+ is specified, only languages whose names match the pattern are listed.
+ By default, only user-created languages
+ are shown; supply the <code class="literal">S</code> modifier to include system
+ objects. If <code class="literal">+</code> is appended to the command name, each
+ language is listed with its call handler, validator, access privileges,
+ and whether it is a system object.
+ </p></dd><dt><span class="term"><code class="literal">\dn[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists schemas (namespaces). If <em class="replaceable"><code>pattern</code></em>
+ is specified, only schemas whose names match the pattern are listed.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system objects.
+ If <code class="literal">+</code> is appended to the command name, each object
+ is listed with its associated permissions and description, if any.
+ </p></dd><dt><span class="term"><code class="literal">\do[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> [ <em class="replaceable"><code>arg_pattern</code></em> [ <em class="replaceable"><code>arg_pattern</code></em> ] ] ]</code></span></dt><dd><p>
+ Lists operators with their operand and result types.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only operators whose names match the pattern are listed.
+ If one <em class="replaceable"><code>arg_pattern</code></em> is
+ specified, only prefix operators whose right argument's type name
+ matches that pattern are listed.
+ If two <em class="replaceable"><code>arg_pattern</code></em>s
+ are specified, only binary operators whose argument type names match
+ those patterns are listed. (Alternatively, write <code class="literal">-</code>
+ for the unused argument of a unary operator.)
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ If <code class="literal">+</code> is appended to the command name,
+ additional information about each operator is shown, currently just
+ the name of the underlying function.
+ </p></dd><dt><span class="term"><code class="literal">\dO[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists collations.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only collations whose names match the pattern are
+ listed. By default, only user-created objects are shown;
+ supply a pattern or the <code class="literal">S</code> modifier to
+ include system objects. If <code class="literal">+</code> is appended
+ to the command name, each collation is listed with its associated
+ description, if any.
+ Note that only collations usable with the current database's encoding
+ are shown, so the results may vary in different databases of the
+ same installation.
+ </p></dd><dt><span class="term"><code class="literal">\dp [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists tables, views and sequences with their
+ associated access privileges.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only tables, views and sequences whose names match the
+ pattern are listed.
+ </p><p>
+ The <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a>
+ commands are used to set access privileges. The meaning of the
+ privilege display is explained in
+ <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.
+ </p></dd><dt><span class="term"><code class="literal">\dP[itn+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists partitioned relations.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only entries whose name matches the pattern are listed.
+ The modifiers <code class="literal">t</code> (tables) and <code class="literal">i</code>
+ (indexes) can be appended to the command, filtering the kind of
+ relations to list. By default, partitioned tables and indexes are
+ listed.
+ </p><p>
+ If the modifier <code class="literal">n</code> (<span class="quote">“<span class="quote">nested</span>”</span>) is used,
+ or a pattern is specified, then non-root partitioned relations are
+ included, and a column is shown displaying the parent of each
+ partitioned relation.
+ </p><p>
+ If <code class="literal">+</code> is appended to the command name, the sum of the
+ sizes of each relation's partitions is also displayed, along with the
+ relation's description.
+ If <code class="literal">n</code> is combined with <code class="literal">+</code>, two
+ sizes are shown: one including the total size of directly-attached
+ leaf partitions, and another showing the total size of all partitions,
+ including indirectly attached sub-partitions.
+ </p></dd><dt><span class="term"><code class="literal">\drds [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>role-pattern</code></em></a> [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>database-pattern</code></em></a> ] ]</code></span></dt><dd><p>
+ Lists defined configuration settings. These settings can be
+ role-specific, database-specific, or both.
+ <em class="replaceable"><code>role-pattern</code></em> and
+ <em class="replaceable"><code>database-pattern</code></em> are used to select
+ specific roles and databases to list, respectively. If omitted, or if
+ <code class="literal">*</code> is specified, all settings are listed, including those
+ not role-specific or database-specific, respectively.
+ </p><p>
+ The <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a> and
+ <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE</code></a>
+ commands are used to define per-role and per-database configuration
+ settings.
+ </p></dd><dt><span class="term"><code class="literal">\dRp[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists replication publications.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only those publications whose names match the pattern are
+ listed.
+ If <code class="literal">+</code> is appended to the command name, the tables and
+ schemas associated with each publication are shown as well.
+ </p></dd><dt><span class="term"><code class="literal">\dRs[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists replication subscriptions.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only those subscriptions whose names match the pattern are
+ listed.
+ If <code class="literal">+</code> is appended to the command name, additional
+ properties of the subscriptions are shown.
+ </p></dd><dt><span class="term"><code class="literal">\dT[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists data types.
+ If <em class="replaceable"><code>pattern</code></em> is
+ specified, only types whose names match the pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, each type is
+ listed with its internal name and size, its allowed values
+ if it is an <code class="type">enum</code> type, and its associated permissions.
+ By default, only user-created objects are shown; supply a
+ pattern or the <code class="literal">S</code> modifier to include system
+ objects.
+ </p></dd><dt><span class="term"><code class="literal">\du[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists database roles.
+ (Since the concepts of <span class="quote">“<span class="quote">users</span>”</span> and <span class="quote">“<span class="quote">groups</span>”</span> have been
+ unified into <span class="quote">“<span class="quote">roles</span>”</span>, this command is now equivalent to
+ <code class="literal">\dg</code>.)
+ By default, only user-created roles are shown; supply the
+ <code class="literal">S</code> modifier to include system roles.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only those roles whose names match the pattern are listed.
+ If the form <code class="literal">\du+</code> is used, additional information
+ is shown about each role; currently this adds the comment for each
+ role.
+ </p></dd><dt><span class="term"><code class="literal">\dx[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists installed extensions.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only those extensions whose names match the pattern
+ are listed.
+ If the form <code class="literal">\dx+</code> is used, all the objects belonging
+ to each matching extension are listed.
+ </p></dd><dt><span class="term"><code class="literal">\dX [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists extended statistics.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only those extended statistics whose names match the
+ pattern are listed.
+ </p><p>
+ The status of each kind of extended statistics is shown in a column
+ named after its statistic kind (e.g. Ndistinct).
+ <code class="literal">defined</code> means that it was requested when creating
+ the statistics, and NULL means it wasn't requested.
+ You can use <code class="structname">pg_stats_ext</code> if you'd like to
+ know whether <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
+ was run and statistics are available to the planner.
+ </p></dd><dt><span class="term"><code class="literal">\dy[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists event triggers.
+ If <em class="replaceable"><code>pattern</code></em>
+ is specified, only those event triggers whose names match the pattern
+ are listed.
+ If <code class="literal">+</code> is appended to the command name, each object
+ is listed with its associated description.
+ </p></dd><dt><span class="term"><code class="literal">\e</code> or <code class="literal">\edit</code> <code class="literal"> [<span class="optional"> <em class="replaceable"><code>filename</code></em> </span>] [<span class="optional"> <em class="replaceable"><code>line_number</code></em> </span>] </code></span></dt><dd><p>
+ If <em class="replaceable"><code>filename</code></em> is
+ specified, the file is edited; after the editor exits, the file's
+ content is copied into the current query buffer. If no <em class="replaceable"><code>filename</code></em> is given, the current query
+ buffer is copied to a temporary file which is then edited in the same
+ fashion. Or, if the current query buffer is empty, the most recently
+ executed query is copied to a temporary file and edited in the same
+ fashion.
+ </p><p>
+ If you edit a file or the previous query, and you quit the editor without
+ modifying the file, the query buffer is cleared.
+ Otherwise, the new contents of the query buffer are re-parsed according to
+ the normal rules of <span class="application">psql</span>, treating the
+ whole buffer as a single line. Any complete queries are immediately
+ executed; that is, if the query buffer contains or ends with a
+ semicolon, everything up to that point is executed and removed from
+ the query buffer. Whatever remains in the query buffer is
+ redisplayed. Type semicolon or <code class="literal">\g</code> to send it,
+ or <code class="literal">\r</code> to cancel it by clearing the query buffer.
+ </p><p>
+ Treating the buffer as a single line primarily affects meta-commands:
+ whatever is in the buffer after a meta-command will be taken as
+ argument(s) to the meta-command, even if it spans multiple lines.
+ (Thus you cannot make meta-command-using scripts this way.
+ Use <code class="command">\i</code> for that.)
+ </p><p>
+ If a line number is specified, <span class="application">psql</span> will
+ position the cursor on the specified line of the file or query buffer.
+ Note that if a single all-digits argument is given,
+ <span class="application">psql</span> assumes it is a line number,
+ not a file name.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ See <a class="xref" href="app-psql.html#APP-PSQL-ENVIRONMENT" title="Environment">Environment</a>, below, for how to
+ configure and customize your editor.
+ </p></div></dd><dt><span class="term"><code class="literal">\echo <em class="replaceable"><code>text</code></em> [ ... ]</code></span></dt><dd><p>
+ Prints the evaluated arguments to standard output, separated by
+ spaces and followed by a newline. This can be useful to
+ intersperse information in the output of scripts. For example:
+</p><pre class="programlisting">
+=&gt; <strong class="userinput"><code>\echo `date`</code></strong>
+Tue Oct 26 21:40:57 CEST 1999
+</pre><p>
+ If the first argument is an unquoted <code class="literal">-n</code> the trailing
+ newline is not written (nor is the first argument).
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If you use the <code class="command">\o</code> command to redirect your
+ query output you might wish to use <code class="command">\qecho</code>
+ instead of this command. See also <code class="command">\warn</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">\ef [<span class="optional"> <em class="replaceable"><code>function_description</code></em> [<span class="optional"> <em class="replaceable"><code>line_number</code></em> </span>] </span>] </code></span></dt><dd><p>
+ This command fetches and edits the definition of the named function or procedure,
+ in the form of a <code class="command">CREATE OR REPLACE FUNCTION</code> or
+ <code class="command">CREATE OR REPLACE PROCEDURE</code> command.
+ Editing is done in the same way as for <code class="literal">\edit</code>.
+ If you quit the editor without saving, the statement is discarded.
+ If you save and exit the editor, the updated command is executed immediately
+ if you added a semicolon to it. Otherwise it is redisplayed;
+ type semicolon or <code class="literal">\g</code> to send it, or <code class="literal">\r</code>
+ to cancel.
+ </p><p>
+ The target function can be specified by name alone, or by name
+ and arguments, for example <code class="literal">foo(integer, text)</code>.
+ The argument types must be given if there is more
+ than one function of the same name.
+ </p><p>
+ If no function is specified, a blank <code class="command">CREATE FUNCTION</code>
+ template is presented for editing.
+ </p><p>
+ If a line number is specified, <span class="application">psql</span> will
+ position the cursor on the specified line of the function body.
+ (Note that the function body typically does not begin on the first
+ line of the file.)
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\ef</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ See <a class="xref" href="app-psql.html#APP-PSQL-ENVIRONMENT" title="Environment">Environment</a>, below, for how to
+ configure and customize your editor.
+ </p></div></dd><dt><span class="term"><code class="literal">\encoding [ <em class="replaceable"><code>encoding</code></em> ]</code></span></dt><dd><p>
+ Sets the client character set encoding. Without an argument, this command
+ shows the current encoding.
+ </p></dd><dt><span class="term"><code class="literal">\errverbose</code></span></dt><dd><p>
+ Repeats the most recent server error message at maximum
+ verbosity, as though <code class="varname">VERBOSITY</code> were set
+ to <code class="literal">verbose</code> and <code class="varname">SHOW_CONTEXT</code> were
+ set to <code class="literal">always</code>.
+ </p></dd><dt><span class="term"><code class="literal">\ev [<span class="optional"> <em class="replaceable"><code>view_name</code></em> [<span class="optional"> <em class="replaceable"><code>line_number</code></em> </span>] </span>] </code></span></dt><dd><p>
+ This command fetches and edits the definition of the named view,
+ in the form of a <code class="command">CREATE OR REPLACE VIEW</code> command.
+ Editing is done in the same way as for <code class="literal">\edit</code>.
+ If you quit the editor without saving, the statement is discarded.
+ If you save and exit the editor, the updated command is executed immediately
+ if you added a semicolon to it. Otherwise it is redisplayed;
+ type semicolon or <code class="literal">\g</code> to send it, or <code class="literal">\r</code>
+ to cancel.
+ </p><p>
+ If no view is specified, a blank <code class="command">CREATE VIEW</code>
+ template is presented for editing.
+ </p><p>
+ If a line number is specified, <span class="application">psql</span> will
+ position the cursor on the specified line of the view definition.
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\ev</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments.
+ </p></dd><dt><span class="term"><code class="literal">\f [ <em class="replaceable"><code>string</code></em> ]</code></span></dt><dd><p>
+ Sets the field separator for unaligned query output. The default
+ is the vertical bar (<code class="literal">|</code>). It is equivalent to
+ <code class="command">\pset fieldsep</code>.
+ </p></dd><dt><span class="term"><code class="literal">\g [ (<em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em> [...]) ] [ <em class="replaceable"><code>filename</code></em> ]</code><br /></span><span class="term"><code class="literal">\g [ (<em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em> [...]) ] [ |<em class="replaceable"><code>command</code></em> ]</code></span></dt><dd><p>
+ Sends the current query buffer to the server for execution.
+ </p><p>
+ If parentheses appear after <code class="literal">\g</code>, they surround a
+ space-separated list
+ of <em class="replaceable"><code>option</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em>
+ formatting-option clauses, which are interpreted in the same way
+ as <code class="literal">\pset</code>
+ <em class="replaceable"><code>option</code></em>
+ <em class="replaceable"><code>value</code></em> commands, but take
+ effect only for the duration of this query. In this list, spaces are
+ not allowed around <code class="literal">=</code> signs, but are required
+ between option clauses.
+ If <code class="literal">=</code><em class="replaceable"><code>value</code></em>
+ is omitted, the
+ named <em class="replaceable"><code>option</code></em> is changed
+ in the same way as for
+ <code class="literal">\pset</code> <em class="replaceable"><code>option</code></em>
+ with no explicit <em class="replaceable"><code>value</code></em>.
+ </p><p>
+ If a <em class="replaceable"><code>filename</code></em>
+ or <code class="literal">|</code><em class="replaceable"><code>command</code></em>
+ argument is given, the query's output is written to the named
+ file or piped to the given shell command, instead of displaying it as
+ usual. The file or command is written to only if the query
+ successfully returns zero or more tuples, not if the query fails or
+ is a non-data-returning SQL command.
+ </p><p>
+ If the current query buffer is empty, the most recently sent query is
+ re-executed instead. Except for that behavior, <code class="literal">\g</code>
+ without any arguments is essentially equivalent to a semicolon.
+ With arguments, <code class="literal">\g</code> provides
+ a <span class="quote">“<span class="quote">one-shot</span>”</span> alternative to the <code class="command">\o</code>
+ command, and additionally allows one-shot adjustments of the
+ output formatting options normally set by <code class="literal">\pset</code>.
+ </p><p>
+ When the last argument begins with <code class="literal">|</code>, the entire
+ remainder of the line is taken to be
+ the <em class="replaceable"><code>command</code></em> to execute,
+ and neither variable interpolation nor backquote expansion are
+ performed in it. The rest of the line is simply passed literally to
+ the shell.
+ </p></dd><dt><span class="term"><code class="literal">\gdesc</code></span></dt><dd><p>
+ Shows the description (that is, the column names and data types)
+ of the result of the current query buffer. The query is not
+ actually executed; however, if it contains some type of syntax
+ error, that error will be reported in the normal way.
+ </p><p>
+ If the current query buffer is empty, the most recently sent query
+ is described instead.
+ </p></dd><dt><span class="term"><code class="literal">\getenv <em class="replaceable"><code>psql_var</code></em> <em class="replaceable"><code>env_var</code></em></code></span></dt><dd><p>
+ Gets the value of the environment
+ variable <em class="replaceable"><code>env_var</code></em>
+ and assigns it to the <span class="application">psql</span>
+ variable <em class="replaceable"><code>psql_var</code></em>.
+ If <em class="replaceable"><code>env_var</code></em> is
+ not defined in the <span class="application">psql</span> process's
+ environment, <em class="replaceable"><code>psql_var</code></em>
+ is not changed. Example:
+</p><pre class="programlisting">
+=&gt; <strong class="userinput"><code>\getenv home HOME</code></strong>
+=&gt; <strong class="userinput"><code>\echo :home</code></strong>
+/home/postgres
+</pre></dd><dt><span class="term"><code class="literal">\gexec</code></span></dt><dd><p>
+ Sends the current query buffer to the server, then treats
+ each column of each row of the query's output (if any) as an SQL
+ statement to be executed. For example, to create an index on each
+ column of <code class="structname">my_table</code>:
+</p><pre class="programlisting">
+=&gt; <strong class="userinput"><code>SELECT format('create index on my_table(%I)', attname)</code></strong>
+-&gt; <strong class="userinput"><code>FROM pg_attribute</code></strong>
+-&gt; <strong class="userinput"><code>WHERE attrelid = 'my_table'::regclass AND attnum &gt; 0</code></strong>
+-&gt; <strong class="userinput"><code>ORDER BY attnum</code></strong>
+-&gt; <strong class="userinput"><code>\gexec</code></strong>
+CREATE INDEX
+CREATE INDEX
+CREATE INDEX
+CREATE INDEX
+</pre><p>
+ </p><p>
+ The generated queries are executed in the order in which the rows
+ are returned, and left-to-right within each row if there is more
+ than one column. NULL fields are ignored. The generated queries
+ are sent literally to the server for processing, so they cannot be
+ <span class="application">psql</span> meta-commands nor contain <span class="application">psql</span>
+ variable references. If any individual query fails, execution of
+ the remaining queries continues
+ unless <code class="varname">ON_ERROR_STOP</code> is set. Execution of each
+ query is subject to <code class="varname">ECHO</code> processing.
+ (Setting <code class="varname">ECHO</code> to <code class="literal">all</code>
+ or <code class="literal">queries</code> is often advisable when
+ using <code class="command">\gexec</code>.) Query logging, single-step mode,
+ timing, and other query execution features apply to each generated
+ query as well.
+ </p><p>
+ If the current query buffer is empty, the most recently sent query
+ is re-executed instead.
+ </p></dd><dt><span class="term"><code class="literal">\gset [ <em class="replaceable"><code>prefix</code></em> ]</code></span></dt><dd><p>
+ Sends the current query buffer to the server and stores the
+ query's output into <span class="application">psql</span> variables
+ (see <a class="xref" href="app-psql.html#APP-PSQL-VARIABLES" title="Variables">Variables</a> below).
+ The query to be executed must return exactly one row. Each column of
+ the row is stored into a separate variable, named the same as the
+ column. For example:
+</p><pre class="programlisting">
+=&gt; <strong class="userinput"><code>SELECT 'hello' AS var1, 10 AS var2</code></strong>
+-&gt; <strong class="userinput"><code>\gset</code></strong>
+=&gt; <strong class="userinput"><code>\echo :var1 :var2</code></strong>
+hello 10
+</pre><p>
+ </p><p>
+ If you specify a <em class="replaceable"><code>prefix</code></em>,
+ that string is prepended to the query's column names to create the
+ variable names to use:
+</p><pre class="programlisting">
+=&gt; <strong class="userinput"><code>SELECT 'hello' AS var1, 10 AS var2</code></strong>
+-&gt; <strong class="userinput"><code>\gset result_</code></strong>
+=&gt; <strong class="userinput"><code>\echo :result_var1 :result_var2</code></strong>
+hello 10
+</pre><p>
+ </p><p>
+ If a column result is NULL, the corresponding variable is unset
+ rather than being set.
+ </p><p>
+ If the query fails or does not return one row,
+ no variables are changed.
+ </p><p>
+ If the current query buffer is empty, the most recently sent query
+ is re-executed instead.
+ </p></dd><dt><span class="term"><code class="literal">\gx [ (<em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em> [...]) ] [ <em class="replaceable"><code>filename</code></em> ]</code><br /></span><span class="term"><code class="literal">\gx [ (<em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em> [...]) ] [ |<em class="replaceable"><code>command</code></em> ]</code></span></dt><dd><p>
+ <code class="literal">\gx</code> is equivalent to <code class="literal">\g</code>, except
+ that it forces expanded output mode for this query, as
+ if <code class="literal">expanded=on</code> were included in the list of
+ <code class="literal">\pset</code> options. See also <code class="literal">\x</code>.
+ </p></dd><dt><span class="term"><code class="literal">\h</code> or <code class="literal">\help</code> <code class="literal">[ <em class="replaceable"><code>command</code></em> ]</code></span></dt><dd><p>
+ Gives syntax help on the specified <acronym class="acronym">SQL</acronym>
+ command. If <em class="replaceable"><code>command</code></em>
+ is not specified, then <span class="application">psql</span> will list
+ all the commands for which syntax help is available. If
+ <em class="replaceable"><code>command</code></em> is an
+ asterisk (<code class="literal">*</code>), then syntax help on all
+ <acronym class="acronym">SQL</acronym> commands is shown.
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\help</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ To simplify typing, commands that consists of several words do
+ not have to be quoted. Thus it is fine to type <strong class="userinput"><code>\help
+ alter table</code></strong>.
+ </p></div></dd><dt><span class="term"><code class="literal">\H</code> or <code class="literal">\html</code></span></dt><dd><p>
+ Turns on <acronym class="acronym">HTML</acronym> query output format. If the
+ <acronym class="acronym">HTML</acronym> format is already on, it is switched
+ back to the default aligned text format. This command is for
+ compatibility and convenience, but see <code class="command">\pset</code>
+ about setting other output options.
+ </p></dd><dt><span class="term"><code class="literal">\i</code> or <code class="literal">\include</code> <em class="replaceable"><code>filename</code></em></span></dt><dd><p>
+ Reads input from the file <em class="replaceable"><code>filename</code></em> and executes it as
+ though it had been typed on the keyboard.
+ </p><p>
+ If <em class="replaceable"><code>filename</code></em> is <code class="literal">-</code>
+ (hyphen), then standard input is read until an EOF indication
+ or <code class="command">\q</code> meta-command. This can be used to intersperse
+ interactive input with input from files. Note that Readline behavior
+ will be used only if it is active at the outermost level.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If you want to see the lines on the screen as they are read you
+ must set the variable <code class="varname">ECHO</code> to
+ <code class="literal">all</code>.
+ </p></div></dd><dt id="PSQL-METACOMMAND-IF"><span class="term"><code class="literal">\if</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\elif</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\else</code><br /></span><span class="term"><code class="literal">\endif</code></span></dt><dd><p>
+ This group of commands implements nestable conditional blocks.
+ A conditional block must begin with an <code class="command">\if</code> and end
+ with an <code class="command">\endif</code>. In between there may be any number
+ of <code class="command">\elif</code> clauses, which may optionally be followed
+ by a single <code class="command">\else</code> clause. Ordinary queries and
+ other types of backslash commands may (and usually do) appear between
+ the commands forming a conditional block.
+ </p><p>
+ The <code class="command">\if</code> and <code class="command">\elif</code> commands read
+ their argument(s) and evaluate them as a Boolean expression. If the
+ expression yields <code class="literal">true</code> then processing continues
+ normally; otherwise, lines are skipped until a
+ matching <code class="command">\elif</code>, <code class="command">\else</code>,
+ or <code class="command">\endif</code> is reached. Once
+ an <code class="command">\if</code> or <code class="command">\elif</code> test has
+ succeeded, the arguments of later <code class="command">\elif</code> commands in
+ the same block are not evaluated but are treated as false. Lines
+ following an <code class="command">\else</code> are processed only if no earlier
+ matching <code class="command">\if</code> or <code class="command">\elif</code> succeeded.
+ </p><p>
+ The <em class="replaceable"><code>expression</code></em> argument
+ of an <code class="command">\if</code> or <code class="command">\elif</code> command
+ is subject to variable interpolation and backquote expansion, just
+ like any other backslash command argument. After that it is evaluated
+ like the value of an on/off option variable. So a valid value
+ is any unambiguous case-insensitive match for one of:
+ <code class="literal">true</code>, <code class="literal">false</code>, <code class="literal">1</code>,
+ <code class="literal">0</code>, <code class="literal">on</code>, <code class="literal">off</code>,
+ <code class="literal">yes</code>, <code class="literal">no</code>. For example,
+ <code class="literal">t</code>, <code class="literal">T</code>, and <code class="literal">tR</code>
+ will all be considered to be <code class="literal">true</code>.
+ </p><p>
+ Expressions that do not properly evaluate to true or false will
+ generate a warning and be treated as false.
+ </p><p>
+ Lines being skipped are parsed normally to identify queries and
+ backslash commands, but queries are not sent to the server, and
+ backslash commands other than conditionals
+ (<code class="command">\if</code>, <code class="command">\elif</code>,
+ <code class="command">\else</code>, <code class="command">\endif</code>) are
+ ignored. Conditional commands are checked only for valid nesting.
+ Variable references in skipped lines are not expanded, and backquote
+ expansion is not performed either.
+ </p><p>
+ All the backslash commands of a given conditional block must appear in
+ the same source file. If EOF is reached on the main input file or an
+ <code class="command">\include</code>-ed file before all local
+ <code class="command">\if</code>-blocks have been closed,
+ then <span class="application">psql</span> will raise an error.
+ </p><p>
+ Here is an example:
+ </p><pre class="programlisting">
+-- check for the existence of two separate records in the database and store
+-- the results in separate psql variables
+SELECT
+ EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer,
+ EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee
+\gset
+\if :is_customer
+ SELECT * FROM customer WHERE customer_id = 123;
+\elif :is_employee
+ \echo 'is not a customer but is an employee'
+ SELECT * FROM employee WHERE employee_id = 456;
+\else
+ \if yes
+ \echo 'not a customer or employee'
+ \else
+ \echo 'this will never print'
+ \endif
+\endif
+</pre></dd><dt><span class="term"><code class="literal">\ir</code> or <code class="literal">\include_relative</code> <em class="replaceable"><code>filename</code></em></span></dt><dd><p>
+ The <code class="literal">\ir</code> command is similar to <code class="literal">\i</code>, but resolves
+ relative file names differently. When executing in interactive mode,
+ the two commands behave identically. However, when invoked from a
+ script, <code class="literal">\ir</code> interprets file names relative to the
+ directory in which the script is located, rather than the current
+ working directory.
+ </p></dd><dt><span class="term"><code class="literal">\l[+]</code> or <code class="literal">\list[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ List the databases in the server and show their names, owners,
+ character set encodings, and access privileges.
+ If <em class="replaceable"><code>pattern</code></em> is specified,
+ only databases whose names match the pattern are listed.
+ If <code class="literal">+</code> is appended to the command name, database
+ sizes, default tablespaces, and descriptions are also displayed.
+ (Size information is only available for databases that the current
+ user can connect to.)
+ </p></dd><dt><span class="term"><code class="literal">\lo_export <em class="replaceable"><code>loid</code></em> <em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Reads the large object with <acronym class="acronym">OID</acronym> <em class="replaceable"><code>loid</code></em> from the database and
+ writes it to <em class="replaceable"><code>filename</code></em>. Note that this is
+ subtly different from the server function
+ <code class="function">lo_export</code>, which acts with the permissions
+ of the user that the database server runs as and on the server's
+ file system.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Use <code class="command">\lo_list</code> to find out the large object's
+ <acronym class="acronym">OID</acronym>.
+ </p></div></dd><dt><span class="term"><code class="literal">\lo_import <em class="replaceable"><code>filename</code></em> [ <em class="replaceable"><code>comment</code></em> ]</code></span></dt><dd><p>
+ Stores the file into a <span class="productname">PostgreSQL</span>
+ large object. Optionally, it associates the given
+ comment with the object. Example:
+</p><pre class="programlisting">
+foo=&gt; <strong class="userinput"><code>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</code></strong>
+lo_import 152801
+</pre><p>
+ The response indicates that the large object received object
+ ID 152801, which can be used to access the newly-created large
+ object in the future. For the sake of readability, it is
+ recommended to always associate a human-readable comment with
+ every object. Both OIDs and comments can be viewed with the
+ <code class="command">\lo_list</code> command.
+ </p><p>
+ Note that this command is subtly different from the server-side
+ <code class="function">lo_import</code> because it acts as the local user
+ on the local file system, rather than the server's user and file
+ system.
+ </p></dd><dt><span class="term"><code class="literal">\lo_list[+]</code></span></dt><dd><p>
+ Shows a list of all <span class="productname">PostgreSQL</span>
+ large objects currently stored in the database,
+ along with any comments provided for them.
+ If <code class="literal">+</code> is appended to the command name,
+ each large object is listed with its associated permissions,
+ if any.
+ </p></dd><dt><span class="term"><code class="literal">\lo_unlink <em class="replaceable"><code>loid</code></em></code></span></dt><dd><p>
+ Deletes the large object with <acronym class="acronym">OID</acronym>
+ <em class="replaceable"><code>loid</code></em> from the
+ database.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Use <code class="command">\lo_list</code> to find out the large object's
+ <acronym class="acronym">OID</acronym>.
+ </p></div></dd><dt><span class="term"><code class="literal">\o</code> or <code class="literal">\out [ <em class="replaceable"><code>filename</code></em> ]</code><br /></span><span class="term"><code class="literal">\o</code> or <code class="literal">\out [ |<em class="replaceable"><code>command</code></em> ]</code></span></dt><dd><p>
+ Arranges to save future query results to the file <em class="replaceable"><code>filename</code></em> or pipe future results
+ to the shell command <em class="replaceable"><code>command</code></em>. If no argument is
+ specified, the query output is reset to the standard output.
+ </p><p>
+ If the argument begins with <code class="literal">|</code>, then the entire remainder
+ of the line is taken to be
+ the <em class="replaceable"><code>command</code></em> to execute,
+ and neither variable interpolation nor backquote expansion are
+ performed in it. The rest of the line is simply passed literally to
+ the shell.
+ </p><p>
+ <span class="quote">“<span class="quote">Query results</span>”</span> includes all tables, command
+ responses, and notices obtained from the database server, as
+ well as output of various backslash commands that query the
+ database (such as <code class="command">\d</code>); but not error
+ messages.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ To intersperse text output in between query results, use
+ <code class="command">\qecho</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">\p</code> or <code class="literal">\print</code></span></dt><dd><p>
+ Print the current query buffer to the standard output.
+ If the current query buffer is empty, the most recently executed query
+ is printed instead.
+ </p></dd><dt><span class="term"><code class="literal">\password [ <em class="replaceable"><code>username</code></em> ]</code></span></dt><dd><p>
+ Changes the password of the specified user (by default, the current
+ user). This command prompts for the new password, encrypts it, and
+ sends it to the server as an <code class="command">ALTER ROLE</code> command. This
+ makes sure that the new password does not appear in cleartext in the
+ command history, the server log, or elsewhere.
+ </p></dd><dt><span class="term"><code class="literal">\prompt [ <em class="replaceable"><code>text</code></em> ] <em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
+ Prompts the user to supply text, which is assigned to the variable
+ <em class="replaceable"><code>name</code></em>.
+ An optional prompt string, <em class="replaceable"><code>text</code></em>, can be specified. (For multiword
+ prompts, surround the text with single quotes.)
+ </p><p>
+ By default, <code class="literal">\prompt</code> uses the terminal for input and
+ output. However, if the <code class="option">-f</code> command line switch was
+ used, <code class="literal">\prompt</code> uses standard input and standard output.
+ </p></dd><dt><span class="term"><code class="literal">\pset [ <em class="replaceable"><code>option</code></em> [ <em class="replaceable"><code>value</code></em> ] ]</code></span></dt><dd><p>
+ This command sets options affecting the output of query result tables.
+ <em class="replaceable"><code>option</code></em>
+ indicates which option is to be set. The semantics of
+ <em class="replaceable"><code>value</code></em> vary depending
+ on the selected option. For some options, omitting <em class="replaceable"><code>value</code></em> causes the option to be toggled
+ or unset, as described under the particular option. If no such
+ behavior is mentioned, then omitting
+ <em class="replaceable"><code>value</code></em> just results in
+ the current setting being displayed.
+ </p><p>
+ <code class="command">\pset</code> without any arguments displays the current status
+ of all printing options.
+ </p><p>
+ Adjustable printing options are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">border</code></span></dt><dd><p>
+ The <em class="replaceable"><code>value</code></em> must be a
+ number. In general, the higher
+ the number the more borders and lines the tables will have,
+ but details depend on the particular format.
+ In <acronym class="acronym">HTML</acronym> format, this will translate directly
+ into the <code class="literal">border=...</code> attribute.
+ In most other formats only values 0 (no border), 1 (internal
+ dividing lines), and 2 (table frame) make sense, and values above 2
+ will be treated the same as <code class="literal">border = 2</code>.
+ The <code class="literal">latex</code> and <code class="literal">latex-longtable</code>
+ formats additionally allow a value of 3 to add dividing lines
+ between data rows.
+ </p></dd><dt><span class="term"><code class="literal">columns</code></span></dt><dd><p>
+ Sets the target width for the <code class="literal">wrapped</code> format, and also
+ the width limit for determining whether output is wide enough to
+ require the pager or switch to the vertical display in expanded auto
+ mode.
+ Zero (the default) causes the target width to be controlled by the
+ environment variable <code class="envar">COLUMNS</code>, or the detected screen width
+ if <code class="envar">COLUMNS</code> is not set.
+ In addition, if <code class="literal">columns</code> is zero then the
+ <code class="literal">wrapped</code> format only affects screen output.
+ If <code class="literal">columns</code> is nonzero then file and pipe output is
+ wrapped to that width as well.
+ </p></dd><dt><span class="term"><code class="literal">csv_fieldsep</code></span></dt><dd><p>
+ Specifies the field separator to be used in
+ <acronym class="acronym">CSV</acronym> output format. If the separator character
+ appears in a field's value, that field is output within double
+ quotes, following standard <acronym class="acronym">CSV</acronym> rules.
+ The default is a comma.
+ </p></dd><dt><span class="term"><code class="literal">expanded</code> (or <code class="literal">x</code>)</span></dt><dd><p>
+ If <em class="replaceable"><code>value</code></em> is specified it
+ must be either <code class="literal">on</code> or <code class="literal">off</code>, which
+ will enable or disable expanded mode, or <code class="literal">auto</code>.
+ If <em class="replaceable"><code>value</code></em> is omitted the
+ command toggles between the on and off settings. When expanded mode
+ is enabled, query results are displayed in two columns, with the
+ column name on the left and the data on the right. This mode is
+ useful if the data wouldn't fit on the screen in the
+ normal <span class="quote">“<span class="quote">horizontal</span>”</span> mode. In the auto setting, the
+ expanded mode is used whenever the query output has more than one
+ column and is wider than the screen; otherwise, the regular mode is
+ used. The auto setting is only
+ effective in the aligned and wrapped formats. In other formats, it
+ always behaves as if the expanded mode is off.
+ </p></dd><dt><span class="term"><code class="literal">fieldsep</code></span></dt><dd><p>
+ Specifies the field separator to be used in unaligned output
+ format. That way one can create, for example, tab-separated
+ output, which other programs might prefer. To
+ set a tab as field separator, type <code class="literal">\pset fieldsep
+ '\t'</code>. The default field separator is
+ <code class="literal">'|'</code> (a vertical bar).
+ </p></dd><dt><span class="term"><code class="literal">fieldsep_zero</code></span></dt><dd><p>
+ Sets the field separator to use in unaligned output format to a zero
+ byte.
+ </p></dd><dt><span class="term"><code class="literal">footer</code></span></dt><dd><p>
+ If <em class="replaceable"><code>value</code></em> is specified
+ it must be either <code class="literal">on</code> or <code class="literal">off</code>
+ which will enable or disable display of the table footer
+ (the <code class="literal">(<em class="replaceable"><code>n</code></em> rows)</code> count).
+ If <em class="replaceable"><code>value</code></em> is omitted the
+ command toggles footer display on or off.
+ </p></dd><dt><span class="term"><code class="literal">format</code></span></dt><dd><p>
+ Sets the output format to one of <code class="literal">aligned</code>,
+ <code class="literal">asciidoc</code>,
+ <code class="literal">csv</code>,
+ <code class="literal">html</code>,
+ <code class="literal">latex</code>,
+ <code class="literal">latex-longtable</code>, <code class="literal">troff-ms</code>,
+ <code class="literal">unaligned</code>, or <code class="literal">wrapped</code>.
+ Unique abbreviations are allowed.
+ </p><p><code class="literal">aligned</code> format is the standard,
+ human-readable, nicely formatted text output; this is the default.
+ </p><p><code class="literal">unaligned</code> format writes all columns of a row on one
+ line, separated by the currently active field separator. This
+ is useful for creating output that might be intended to be read
+ in by other programs, for example, tab-separated or comma-separated
+ format. However, the field separator character is not treated
+ specially if it appears in a column's value;
+ so <acronym class="acronym">CSV</acronym> format may be better suited for such
+ purposes.
+ </p><p><code class="literal">csv</code> format
+ <a id="id-1.9.4.20.8.4.10.1.76.2.3.1.8.2.4.2" class="indexterm"></a>
+ writes column values separated by commas, applying the quoting
+ rules described in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc4180" target="_top">RFC 4180</a>.
+ This output is compatible with the CSV format of the server's
+ <code class="command">COPY</code> command.
+ A header line with column names is generated unless
+ the <code class="literal">tuples_only</code> parameter is
+ <code class="literal">on</code>. Titles and footers are not printed.
+ Each row is terminated by the system-dependent end-of-line character,
+ which is typically a single newline (<code class="literal">\n</code>) for
+ Unix-like systems or a carriage return and newline sequence
+ (<code class="literal">\r\n</code>) for Microsoft Windows.
+ Field separator characters other than comma can be selected with
+ <code class="command">\pset csv_fieldsep</code>.
+ </p><p><code class="literal">wrapped</code> format is like <code class="literal">aligned</code> but wraps
+ wide data values across lines to make the output fit in the target
+ column width. The target width is determined as described under
+ the <code class="literal">columns</code> option. Note that <span class="application">psql</span> will
+ not attempt to wrap column header titles; therefore,
+ <code class="literal">wrapped</code> format behaves the same as <code class="literal">aligned</code>
+ if the total width needed for column headers exceeds the target.
+ </p><p>
+ The <code class="literal">asciidoc</code>, <code class="literal">html</code>,
+ <code class="literal">latex</code>, <code class="literal">latex-longtable</code>, and
+ <code class="literal">troff-ms</code> formats put out tables that are intended
+ to be included in documents using the respective mark-up
+ language. They are not complete documents! This might not be
+ necessary in <acronym class="acronym">HTML</acronym>, but in
+ <span class="application">LaTeX</span> you must have a complete
+ document wrapper.
+ The <code class="literal">latex</code> format
+ uses <span class="application">LaTeX</span>'s <code class="literal">tabular</code>
+ environment.
+ The <code class="literal">latex-longtable</code> format
+ requires the <span class="application">LaTeX</span>
+ <code class="literal">longtable</code> and <code class="literal">booktabs</code> packages.
+ </p></dd><dt><span class="term"><code class="literal">linestyle</code></span></dt><dd><p>
+ Sets the border line drawing style to one
+ of <code class="literal">ascii</code>, <code class="literal">old-ascii</code>,
+ or <code class="literal">unicode</code>.
+ Unique abbreviations are allowed. (That would mean one
+ letter is enough.)
+ The default setting is <code class="literal">ascii</code>.
+ This option only affects the <code class="literal">aligned</code> and
+ <code class="literal">wrapped</code> output formats.
+ </p><p><code class="literal">ascii</code> style uses plain <acronym class="acronym">ASCII</acronym>
+ characters. Newlines in data are shown using
+ a <code class="literal">+</code> symbol in the right-hand margin.
+ When the <code class="literal">wrapped</code> format wraps data from
+ one line to the next without a newline character, a dot
+ (<code class="literal">.</code>) is shown in the right-hand margin of the first line,
+ and again in the left-hand margin of the following line.
+ </p><p><code class="literal">old-ascii</code> style uses plain <acronym class="acronym">ASCII</acronym>
+ characters, using the formatting style used
+ in <span class="productname">PostgreSQL</span> 8.4 and earlier.
+ Newlines in data are shown using a <code class="literal">:</code>
+ symbol in place of the left-hand column separator.
+ When the data is wrapped from one line
+ to the next without a newline character, a <code class="literal">;</code>
+ symbol is used in place of the left-hand column separator.
+ </p><p><code class="literal">unicode</code> style uses Unicode box-drawing characters.
+ Newlines in data are shown using a carriage return symbol
+ in the right-hand margin. When the data is wrapped from one line
+ to the next without a newline character, an ellipsis symbol
+ is shown in the right-hand margin of the first line, and
+ again in the left-hand margin of the following line.
+ </p><p>
+ When the <code class="literal">border</code> setting is greater than zero,
+ the <code class="literal">linestyle</code> option also determines the
+ characters with which the border lines are drawn.
+ Plain <acronym class="acronym">ASCII</acronym> characters work everywhere, but
+ Unicode characters look nicer on displays that recognize them.
+ </p></dd><dt><span class="term"><code class="literal">null</code></span></dt><dd><p>
+ Sets the string to be printed in place of a null value.
+ The default is to print nothing, which can easily be mistaken for
+ an empty string. For example, one might prefer <code class="literal">\pset null
+ '(null)'</code>.
+ </p></dd><dt><span class="term"><code class="literal">numericlocale</code></span></dt><dd><p>
+ If <em class="replaceable"><code>value</code></em> is specified
+ it must be either <code class="literal">on</code> or <code class="literal">off</code>
+ which will enable or disable display of a locale-specific character
+ to separate groups of digits to the left of the decimal marker.
+ If <em class="replaceable"><code>value</code></em> is omitted the
+ command toggles between regular and locale-specific numeric output.
+ </p></dd><dt><span class="term"><code class="literal">pager</code></span></dt><dd><p>
+ Controls use of a pager program for query and <span class="application">psql</span>
+ help output.
+ When the <code class="literal">pager</code> option is <code class="literal">off</code>, the pager
+ program is not used. When the <code class="literal">pager</code> option is
+ <code class="literal">on</code>, the pager is used when appropriate, i.e., when the
+ output is to a terminal and will not fit on the screen.
+ The <code class="literal">pager</code> option can also be set to <code class="literal">always</code>,
+ which causes the pager to be used for all terminal output regardless
+ of whether it fits on the screen. <code class="literal">\pset pager</code>
+ without a <em class="replaceable"><code>value</code></em>
+ toggles pager use on and off.
+ </p><p>
+ If the environment variable <code class="envar">PSQL_PAGER</code>
+ or <code class="envar">PAGER</code> is set, output to be paged is piped to the
+ specified program. Otherwise a platform-dependent default program
+ (such as <code class="filename">more</code>) is used.
+ </p><p>
+ When using the <code class="literal">\watch</code> command to execute a query
+ repeatedly, the environment variable <code class="envar">PSQL_WATCH_PAGER</code>
+ is used to find the pager program instead, on Unix systems. This is
+ configured separately because it may confuse traditional pagers, but
+ can be used to send output to tools that understand
+ <span class="application">psql</span>'s output format (such as
+ <code class="filename">pspg --stream</code>).
+ </p></dd><dt><span class="term"><code class="literal">pager_min_lines</code></span></dt><dd><p>
+ If <code class="literal">pager_min_lines</code> is set to a number greater than the
+ page height, the pager program will not be called unless there are
+ at least this many lines of output to show. The default setting
+ is 0.
+ </p></dd><dt><span class="term"><code class="literal">recordsep</code></span></dt><dd><p>
+ Specifies the record (line) separator to use in unaligned
+ output format. The default is a newline character.
+ </p></dd><dt><span class="term"><code class="literal">recordsep_zero</code></span></dt><dd><p>
+ Sets the record separator to use in unaligned output format to a zero
+ byte.
+ </p></dd><dt><span class="term"><code class="literal">tableattr</code> (or <code class="literal">T</code>)</span></dt><dd><p>
+ In <acronym class="acronym">HTML</acronym> format, this specifies attributes
+ to be placed inside the <code class="sgmltag-element">table</code> tag. This
+ could for example be <code class="literal">cellpadding</code> or
+ <code class="literal">bgcolor</code>. Note that you probably don't want
+ to specify <code class="literal">border</code> here, as that is already
+ taken care of by <code class="literal">\pset border</code>.
+ If no
+ <em class="replaceable"><code>value</code></em> is given,
+ the table attributes are unset.
+ </p><p>
+ In <code class="literal">latex-longtable</code> format, this controls
+ the proportional width of each column containing a left-aligned
+ data type. It is specified as a whitespace-separated list of values,
+ e.g., <code class="literal">'0.2 0.2 0.6'</code>. Unspecified output columns
+ use the last specified value.
+ </p></dd><dt><span class="term"><code class="literal">title</code> (or <code class="literal">C</code>)</span></dt><dd><p>
+ Sets the table title for any subsequently printed tables. This
+ can be used to give your output descriptive tags. If no
+ <em class="replaceable"><code>value</code></em> is given,
+ the title is unset.
+ </p></dd><dt><span class="term"><code class="literal">tuples_only</code> (or <code class="literal">t</code>)</span></dt><dd><p>
+ If <em class="replaceable"><code>value</code></em> is specified
+ it must be either <code class="literal">on</code> or <code class="literal">off</code>
+ which will enable or disable tuples-only mode.
+ If <em class="replaceable"><code>value</code></em> is omitted the
+ command toggles between regular and tuples-only output.
+ Regular output includes extra information such
+ as column headers, titles, and various footers. In tuples-only
+ mode, only actual table data is shown.
+ </p></dd><dt><span class="term"><code class="literal">unicode_border_linestyle</code></span></dt><dd><p>
+ Sets the border drawing style for the <code class="literal">unicode</code>
+ line style to one of <code class="literal">single</code>
+ or <code class="literal">double</code>.
+ </p></dd><dt><span class="term"><code class="literal">unicode_column_linestyle</code></span></dt><dd><p>
+ Sets the column drawing style for the <code class="literal">unicode</code>
+ line style to one of <code class="literal">single</code>
+ or <code class="literal">double</code>.
+ </p></dd><dt><span class="term"><code class="literal">unicode_header_linestyle</code></span></dt><dd><p>
+ Sets the header drawing style for the <code class="literal">unicode</code>
+ line style to one of <code class="literal">single</code>
+ or <code class="literal">double</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ Illustrations of how these different formats look can be seen in
+ <a class="xref" href="app-psql.html#APP-PSQL-EXAMPLES" title="Examples">Examples</a>, below.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ There are various shortcut commands for <code class="command">\pset</code>. See
+ <code class="command">\a</code>, <code class="command">\C</code>, <code class="command">\f</code>,
+ <code class="command">\H</code>, <code class="command">\t</code>, <code class="command">\T</code>,
+ and <code class="command">\x</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">\q</code> or <code class="literal">\quit</code></span></dt><dd><p>
+ Quits the <span class="application">psql</span> program.
+ In a script file, only execution of that script is terminated.
+ </p></dd><dt><span class="term"><code class="literal">\qecho <em class="replaceable"><code>text</code></em> [ ... ] </code></span></dt><dd><p>
+ This command is identical to <code class="command">\echo</code> except
+ that the output will be written to the query output channel, as
+ set by <code class="command">\o</code>.
+ </p></dd><dt><span class="term"><code class="literal">\r</code> or <code class="literal">\reset</code></span></dt><dd><p>
+ Resets (clears) the query buffer.
+ </p></dd><dt><span class="term"><code class="literal">\s [ <em class="replaceable"><code>filename</code></em> ]</code></span></dt><dd><p>
+ Print <span class="application">psql</span>'s command line history
+ to <em class="replaceable"><code>filename</code></em>.
+ If <em class="replaceable"><code>filename</code></em> is omitted,
+ the history is written to the standard output (using the pager if
+ appropriate). This command is not available
+ if <span class="application">psql</span> was built
+ without <span class="application">Readline</span> support.
+ </p></dd><dt><span class="term"><code class="literal">\set [ <em class="replaceable"><code>name</code></em> [ <em class="replaceable"><code>value</code></em> [ ... ] ] ]</code></span></dt><dd><p>
+ Sets the <span class="application">psql</span> variable <em class="replaceable"><code>name</code></em> to <em class="replaceable"><code>value</code></em>, or if more than one value
+ is given, to the concatenation of all of them. If only one
+ argument is given, the variable is set to an empty-string value. To
+ unset a variable, use the <code class="command">\unset</code> command.
+ </p><p><code class="command">\set</code> without any arguments displays the names and values
+ of all currently-set <span class="application">psql</span> variables.
+ </p><p>
+ Valid variable names can contain letters, digits, and
+ underscores. See <a class="xref" href="app-psql.html#APP-PSQL-VARIABLES" title="Variables">Variables</a> below for details.
+ Variable names are case-sensitive.
+ </p><p>
+ Certain variables are special, in that they
+ control <span class="application">psql</span>'s behavior or are
+ automatically set to reflect connection state. These variables are
+ documented in <a class="xref" href="app-psql.html#APP-PSQL-VARIABLES" title="Variables">Variables</a>, below.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This command is unrelated to the <acronym class="acronym">SQL</acronym>
+ command <a class="link" href="sql-set.html" title="SET"><code class="command">SET</code></a>.
+ </p></div></dd><dt><span class="term"><code class="literal">\setenv <em class="replaceable"><code>name</code></em> [ <em class="replaceable"><code>value</code></em> ]</code></span></dt><dd><p>
+ Sets the environment variable <em class="replaceable"><code>name</code></em> to <em class="replaceable"><code>value</code></em>, or if the
+ <em class="replaceable"><code>value</code></em> is
+ not supplied, unsets the environment variable. Example:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\setenv PAGER less</code></strong>
+testdb=&gt; <strong class="userinput"><code>\setenv LESS -imx4F</code></strong>
+</pre></dd><dt><span class="term"><code class="literal">\sf[+] <em class="replaceable"><code>function_description</code></em> </code></span></dt><dd><p>
+ This command fetches and shows the definition of the named function or procedure,
+ in the form of a <code class="command">CREATE OR REPLACE FUNCTION</code> or
+ <code class="command">CREATE OR REPLACE PROCEDURE</code> command.
+ The definition is printed to the current query output channel,
+ as set by <code class="command">\o</code>.
+ </p><p>
+ The target function can be specified by name alone, or by name
+ and arguments, for example <code class="literal">foo(integer, text)</code>.
+ The argument types must be given if there is more
+ than one function of the same name.
+ </p><p>
+ If <code class="literal">+</code> is appended to the command name, then the
+ output lines are numbered, with the first line of the function body
+ being line 1.
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\sf</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments.
+ </p></dd><dt><span class="term"><code class="literal">\sv[+] <em class="replaceable"><code>view_name</code></em> </code></span></dt><dd><p>
+ This command fetches and shows the definition of the named view,
+ in the form of a <code class="command">CREATE OR REPLACE VIEW</code> command.
+ The definition is printed to the current query output channel,
+ as set by <code class="command">\o</code>.
+ </p><p>
+ If <code class="literal">+</code> is appended to the command name, then the
+ output lines are numbered from 1.
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\sv</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments.
+ </p></dd><dt><span class="term"><code class="literal">\t</code></span></dt><dd><p>
+ Toggles the display of output column name headings and row count
+ footer. This command is equivalent to <code class="literal">\pset
+ tuples_only</code> and is provided for convenience.
+ </p></dd><dt><span class="term"><code class="literal">\T <em class="replaceable"><code>table_options</code></em></code></span></dt><dd><p>
+ Specifies attributes to be placed within the
+ <code class="sgmltag-element">table</code> tag in <acronym class="acronym">HTML</acronym>
+ output format. This command is equivalent to <code class="literal">\pset
+ tableattr <em class="replaceable"><code>table_options</code></em></code>.
+ </p></dd><dt><span class="term"><code class="literal">\timing [ <em class="replaceable"><code>on</code></em> | <em class="replaceable"><code>off</code></em> ]</code></span></dt><dd><p>
+ With a parameter, turns displaying of how long each SQL statement
+ takes on or off. Without a parameter, toggles the display between
+ on and off. The display is in milliseconds; intervals longer than
+ 1 second are also shown in minutes:seconds format, with hours and
+ days fields added if needed.
+ </p></dd><dt><span class="term"><code class="literal">\unset <em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
+ Unsets (deletes) the <span class="application">psql</span> variable <em class="replaceable"><code>name</code></em>.
+ </p><p>
+ Most variables that control <span class="application">psql</span>'s behavior
+ cannot be unset; instead, an <code class="literal">\unset</code> command is interpreted
+ as setting them to their default values.
+ See <a class="xref" href="app-psql.html#APP-PSQL-VARIABLES" title="Variables">Variables</a> below.
+ </p></dd><dt><span class="term"><code class="literal">\w</code> or <code class="literal">\write</code> <em class="replaceable"><code>filename</code></em><br /></span><span class="term"><code class="literal">\w</code> or <code class="literal">\write</code> <code class="literal">|</code><em class="replaceable"><code>command</code></em></span></dt><dd><p>
+ Writes the current query buffer to the file <em class="replaceable"><code>filename</code></em> or pipes it to the shell
+ command <em class="replaceable"><code>command</code></em>.
+ If the current query buffer is empty, the most recently executed query
+ is written instead.
+ </p><p>
+ If the argument begins with <code class="literal">|</code>, then the entire remainder
+ of the line is taken to be
+ the <em class="replaceable"><code>command</code></em> to execute,
+ and neither variable interpolation nor backquote expansion are
+ performed in it. The rest of the line is simply passed literally to
+ the shell.
+ </p></dd><dt><span class="term"><code class="literal">\warn <em class="replaceable"><code>text</code></em> [ ... ]</code></span></dt><dd><p>
+ This command is identical to <code class="command">\echo</code> except
+ that the output will be written to <span class="application">psql</span>'s
+ standard error channel, rather than standard output.
+ </p></dd><dt><span class="term"><code class="literal">\watch [ <em class="replaceable"><code>seconds</code></em> ]</code></span></dt><dd><p>
+ Repeatedly execute the current query buffer (as <code class="literal">\g</code> does)
+ until interrupted or the query fails. Wait the specified number of
+ seconds (default 2) between executions. Each query result is
+ displayed with a header that includes the <code class="literal">\pset title</code>
+ string (if any), the time as of query start, and the delay interval.
+ </p><p>
+ If the current query buffer is empty, the most recently sent query
+ is re-executed instead.
+ </p></dd><dt><span class="term"><code class="literal">\x [ <em class="replaceable"><code>on</code></em> | <em class="replaceable"><code>off</code></em> | <em class="replaceable"><code>auto</code></em> ]</code></span></dt><dd><p>
+ Sets or toggles expanded table formatting mode. As such it is equivalent to
+ <code class="literal">\pset expanded</code>.
+ </p></dd><dt><span class="term"><code class="literal">\z [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span></dt><dd><p>
+ Lists tables, views and sequences with their
+ associated access privileges.
+ If a <em class="replaceable"><code>pattern</code></em> is
+ specified, only tables, views and sequences whose names match the
+ pattern are listed.
+ </p><p>
+ This is an alias for <code class="command">\dp</code> (<span class="quote">“<span class="quote">display
+ privileges</span>”</span>).
+ </p></dd><dt><span class="term"><code class="literal">\! [ <em class="replaceable"><code>command</code></em> ]</code></span></dt><dd><p>
+ With no argument, escapes to a sub-shell; <span class="application">psql</span>
+ resumes when the sub-shell exits. With an argument, executes the
+ shell command <em class="replaceable"><code>command</code></em>.
+ </p><p>
+ Unlike most other meta-commands, the entire remainder of the line is
+ always taken to be the argument(s) of <code class="command">\!</code>, and neither
+ variable interpolation nor backquote expansion are performed in the
+ arguments. The rest of the line is simply passed literally to the
+ shell.
+ </p></dd><dt><span class="term"><code class="literal">\? [ <em class="replaceable"><code>topic</code></em> ]</code></span></dt><dd><p>
+ Shows help information. The optional
+ <em class="replaceable"><code>topic</code></em> parameter
+ (defaulting to <code class="literal">commands</code>) selects which part of <span class="application">psql</span> is
+ explained: <code class="literal">commands</code> describes <span class="application">psql</span>'s
+ backslash commands; <code class="literal">options</code> describes the command-line
+ options that can be passed to <span class="application">psql</span>;
+ and <code class="literal">variables</code> shows help about <span class="application">psql</span> configuration
+ variables.
+ </p></dd><dt><span class="term"><code class="literal">\;</code></span></dt><dd><p>
+ Backslash-semicolon is not a meta-command in the same way as the
+ preceding commands; rather, it simply causes a semicolon to be
+ added to the query buffer without any further processing.
+ </p><p>
+ Normally, <span class="application">psql</span> will dispatch an SQL command to the
+ server as soon as it reaches the command-ending semicolon, even if
+ more input remains on the current line. Thus for example entering
+</p><pre class="programlisting">
+select 1; select 2; select 3;
+</pre><p>
+ will result in the three SQL commands being individually sent to
+ the server, with each one's results being displayed before
+ continuing to the next command. However, a semicolon entered
+ as <code class="literal">\;</code> will not trigger command processing, so that the
+ command before it and the one after are effectively combined and
+ sent to the server in one request. So for example
+</p><pre class="programlisting">
+select 1\; select 2\; select 3;
+</pre><p>
+ results in sending the three SQL commands to the server in a single
+ request, when the non-backslashed semicolon is reached.
+ The server executes such a request as a single transaction,
+ unless there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>
+ commands included in the string to divide it into multiple
+ transactions. (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="55.2.2.1. Multiple Statements in a Simple Query">Section 55.2.2.1</a>
+ for more details about how the server handles multi-query strings.)
+ </p></dd></dl></div><p>
+ </p><div class="refsect3" id="APP-PSQL-PATTERNS"><h4>Patterns</h4><a id="id-1.9.4.20.8.4.11.2" class="indexterm"></a><p>
+ The various <code class="literal">\d</code> commands accept a <em class="replaceable"><code>pattern</code></em> parameter to specify the
+ object name(s) to be displayed. In the simplest case, a pattern
+ is just the exact name of the object. The characters within a
+ pattern are normally folded to lower case, just as in SQL names;
+ for example, <code class="literal">\dt FOO</code> will display the table named
+ <code class="literal">foo</code>. As in SQL names, placing double quotes around
+ a pattern stops folding to lower case. Should you need to include
+ an actual double quote character in a pattern, write it as a pair
+ of double quotes within a double-quote sequence; again this is in
+ accord with the rules for SQL quoted identifiers. For example,
+ <code class="literal">\dt "FOO""BAR"</code> will display the table named
+ <code class="literal">FOO"BAR</code> (not <code class="literal">foo"bar</code>). Unlike the normal
+ rules for SQL names, you can put double quotes around just part
+ of a pattern, for instance <code class="literal">\dt FOO"FOO"BAR</code> will display
+ the table named <code class="literal">fooFOObar</code>.
+ </p><p>
+ Whenever the <em class="replaceable"><code>pattern</code></em> parameter
+ is omitted completely, the <code class="literal">\d</code> commands display all objects
+ that are visible in the current schema search path — this is
+ equivalent to using <code class="literal">*</code> as the pattern.
+ (An object is said to be <em class="firstterm">visible</em> if its
+ containing schema is in the search path and no object of the same
+ kind and name appears earlier in the search path. This is equivalent to the
+ statement that the object can be referenced by name without explicit
+ schema qualification.)
+ To see all objects in the database regardless of visibility,
+ use <code class="literal">*.*</code> as the pattern.
+ </p><p>
+ Within a pattern, <code class="literal">*</code> matches any sequence of characters
+ (including no characters) and <code class="literal">?</code> matches any single character.
+ (This notation is comparable to Unix shell file name patterns.)
+ For example, <code class="literal">\dt int*</code> displays tables whose names
+ begin with <code class="literal">int</code>. But within double quotes, <code class="literal">*</code>
+ and <code class="literal">?</code> lose these special meanings and are just matched
+ literally.
+ </p><p>
+ A relation pattern that contains a dot (<code class="literal">.</code>) is interpreted as a schema
+ name pattern followed by an object name pattern. For example,
+ <code class="literal">\dt foo*.*bar*</code> displays all tables whose table name
+ includes <code class="literal">bar</code> that are in schemas whose schema name
+ starts with <code class="literal">foo</code>. When no dot appears, then the pattern
+ matches only objects that are visible in the current schema search path.
+ Again, a dot within double quotes loses its special meaning and is matched
+ literally. A relation pattern that contains two dots (<code class="literal">.</code>)
+ is interpreted as a database name followed by a schema name pattern followed
+ by an object name pattern. The database name portion will not be treated as
+ a pattern and must match the name of the currently connected database, else
+ an error will be raised.
+ </p><p>
+ A schema pattern that contains a dot (<code class="literal">.</code>) is interpreted
+ as a database name followed by a schema name pattern. For example,
+ <code class="literal">\dn mydb.*foo*</code> displays all schemas whose schema name
+ includes <code class="literal">foo</code>. The database name portion will not be
+ treated as a pattern and must match the name of the currently connected
+ database, else an error will be raised.
+ </p><p>
+ Advanced users can use regular-expression notations such as character
+ classes, for example <code class="literal">[0-9]</code> to match any digit. All regular
+ expression special characters work as specified in
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>, except for <code class="literal">.</code> which
+ is taken as a separator as mentioned above, <code class="literal">*</code> which is
+ translated to the regular-expression notation <code class="literal">.*</code>,
+ <code class="literal">?</code> which is translated to <code class="literal">.</code>, and
+ <code class="literal">$</code> which is matched literally. You can emulate
+ these pattern characters at need by writing
+ <code class="literal">?</code> for <code class="literal">.</code>,
+ <code class="literal">(<em class="replaceable"><code>R</code></em>+|)</code> for
+ <code class="literal"><em class="replaceable"><code>R</code></em>*</code>, or
+ <code class="literal">(<em class="replaceable"><code>R</code></em>|)</code> for
+ <code class="literal"><em class="replaceable"><code>R</code></em>?</code>.
+ <code class="literal">$</code> is not needed as a regular-expression character since
+ the pattern must match the whole name, unlike the usual
+ interpretation of regular expressions (in other words, <code class="literal">$</code>
+ is automatically appended to your pattern). Write <code class="literal">*</code> at the
+ beginning and/or end if you don't wish the pattern to be anchored.
+ Note that within double quotes, all regular expression special characters
+ lose their special meanings and are matched literally. Also, the regular
+ expression special characters are matched literally in operator name
+ patterns (i.e., the argument of <code class="literal">\do</code>).
+ </p></div></div><div class="refsect2" id="id-1.9.4.20.8.5"><h3>Advanced Features</h3><div class="refsect3" id="APP-PSQL-VARIABLES"><h4>Variables</h4><p>
+ <span class="application">psql</span> provides variable substitution
+ features similar to common Unix command shells.
+ Variables are simply name/value pairs, where the value
+ can be any string of any length. The name must consist of letters
+ (including non-Latin letters), digits, and underscores.
+ </p><p>
+ To set a variable, use the <span class="application">psql</span> meta-command
+ <code class="command">\set</code>. For example,
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\set foo bar</code></strong>
+</pre><p>
+ sets the variable <code class="literal">foo</code> to the value
+ <code class="literal">bar</code>. To retrieve the content of the variable, precede
+ the name with a colon, for example:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\echo :foo</code></strong>
+bar
+</pre><p>
+ This works in both regular SQL commands and meta-commands; there is
+ more detail in <a class="xref" href="app-psql.html#APP-PSQL-INTERPOLATION" title="SQL Interpolation">SQL Interpolation</a>, below.
+ </p><p>
+ If you call <code class="command">\set</code> without a second argument, the
+ variable is set to an empty-string value. To unset (i.e., delete)
+ a variable, use the command <code class="command">\unset</code>. To show the
+ values of all variables, call <code class="command">\set</code> without any argument.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The arguments of <code class="command">\set</code> are subject to the same
+ substitution rules as with other commands. Thus you can construct
+ interesting references such as <code class="literal">\set :foo
+ 'something'</code> and get <span class="quote">“<span class="quote">soft links</span>”</span> or
+ <span class="quote">“<span class="quote">variable variables</span>”</span> of <span class="productname">Perl</span>
+ or <span class="productname"><acronym class="acronym">PHP</acronym></span> fame,
+ respectively. Unfortunately (or fortunately?), there is no way to do
+ anything useful with these constructs. On the other hand,
+ <code class="literal">\set bar :foo</code> is a perfectly valid way to copy a
+ variable.
+ </p></div><p>
+ A number of these variables are treated specially
+ by <span class="application">psql</span>. They represent certain option
+ settings that can be changed at run time by altering the value of
+ the variable, or in some cases represent changeable state of
+ <span class="application">psql</span>.
+ By convention, all specially treated variables' names
+ consist of all upper-case ASCII letters (and possibly digits and
+ underscores). To ensure maximum compatibility in the future, avoid
+ using such variable names for your own purposes.
+ </p><p>
+ Variables that control <span class="application">psql</span>'s behavior
+ generally cannot be unset or set to invalid values. An <code class="literal">\unset</code>
+ command is allowed but is interpreted as setting the variable to its
+ default value. A <code class="literal">\set</code> command without a second argument is
+ interpreted as setting the variable to <code class="literal">on</code>, for control
+ variables that accept that value, and is rejected for others. Also,
+ control variables that accept the values <code class="literal">on</code>
+ and <code class="literal">off</code> will also accept other common spellings of Boolean
+ values, such as <code class="literal">true</code> and <code class="literal">false</code>.
+ </p><p>
+ The specially treated variables are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">AUTOCOMMIT</code>
+ <a id="id-1.9.4.20.8.5.2.9.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="literal">on</code> (the default), each SQL command is automatically
+ committed upon successful completion. To postpone commit in this
+ mode, you must enter a <code class="command">BEGIN</code> or <code class="command">START
+ TRANSACTION</code> SQL command. When <code class="literal">off</code> or unset, SQL
+ commands are not committed until you explicitly issue
+ <code class="command">COMMIT</code> or <code class="command">END</code>. The autocommit-off
+ mode works by issuing an implicit <code class="command">BEGIN</code> for you, just
+ before any command that is not already in a transaction block and
+ is not itself a <code class="command">BEGIN</code> or other transaction-control
+ command, nor a command that cannot be executed inside a transaction
+ block (such as <code class="command">VACUUM</code>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In autocommit-off mode, you must explicitly abandon any failed
+ transaction by entering <code class="command">ABORT</code> or <code class="command">ROLLBACK</code>.
+ Also keep in mind that if you exit the session
+ without committing, your work will be lost.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ The autocommit-on mode is <span class="productname">PostgreSQL</span>'s traditional
+ behavior, but autocommit-off is closer to the SQL spec. If you
+ prefer autocommit-off, you might wish to set it in the system-wide
+ <code class="filename">psqlrc</code> file or your
+ <code class="filename">~/.psqlrc</code> file.
+ </p></div></dd><dt><span class="term"><code class="varname">COMP_KEYWORD_CASE</code></span></dt><dd><p>
+ Determines which letter case to use when completing an SQL key word.
+ If set to <code class="literal">lower</code> or <code class="literal">upper</code>, the
+ completed word will be in lower or upper case, respectively. If set
+ to <code class="literal">preserve-lower</code>
+ or <code class="literal">preserve-upper</code> (the default), the completed word
+ will be in the case of the word already entered, but words being
+ completed without anything entered will be in lower or upper case,
+ respectively.
+ </p></dd><dt><span class="term"><code class="varname">DBNAME</code></span></dt><dd><p>
+ The name of the database you are currently connected to. This is
+ set every time you connect to a database (including program
+ start-up), but can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">ECHO</code></span></dt><dd><p>
+ If set to <code class="literal">all</code>, all nonempty input lines are printed
+ to standard output as they are read. (This does not apply to lines
+ read interactively.) To select this behavior on program
+ start-up, use the switch <code class="option">-a</code>. If set to
+ <code class="literal">queries</code>,
+ <span class="application">psql</span> prints each query to standard output
+ as it is sent to the server. The switch to select this behavior is
+ <code class="option">-e</code>. If set to <code class="literal">errors</code>, then only
+ failed queries are displayed on standard error output. The switch
+ for this behavior is <code class="option">-b</code>. If set to
+ <code class="literal">none</code> (the default), then no queries are displayed.
+ </p></dd><dt><span class="term"><code class="varname">ECHO_HIDDEN</code></span></dt><dd><p>
+ When this variable is set to <code class="literal">on</code> and a backslash command
+ queries the database, the query is first shown.
+ This feature helps you to study
+ <span class="productname">PostgreSQL</span> internals and provide
+ similar functionality in your own programs. (To select this behavior
+ on program start-up, use the switch <code class="option">-E</code>.) If you set
+ this variable to the value <code class="literal">noexec</code>, the queries are
+ just shown but are not actually sent to the server and executed.
+ The default value is <code class="literal">off</code>.
+ </p></dd><dt><span class="term"><code class="varname">ENCODING</code></span></dt><dd><p>
+ The current client character set encoding.
+ This is set every time you connect to a database (including
+ program start-up), and when you change the encoding
+ with <code class="literal">\encoding</code>, but it can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">ERROR</code></span></dt><dd><p>
+ <code class="literal">true</code> if the last SQL query failed, <code class="literal">false</code> if
+ it succeeded. See also <code class="varname">SQLSTATE</code>.
+ </p></dd><dt><span class="term"><code class="varname">FETCH_COUNT</code></span></dt><dd><p>
+ If this variable is set to an integer value greater than zero,
+ the results of <code class="command">SELECT</code> queries are fetched
+ and displayed in groups of that many rows, rather than the
+ default behavior of collecting the entire result set before
+ display. Therefore only a
+ limited amount of memory is used, regardless of the size of
+ the result set. Settings of 100 to 1000 are commonly used
+ when enabling this feature.
+ Keep in mind that when using this feature, a query might
+ fail after having already displayed some rows.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Although you can use any output format with this feature,
+ the default <code class="literal">aligned</code> format tends to look bad
+ because each group of <code class="varname">FETCH_COUNT</code> rows
+ will be formatted separately, leading to varying column
+ widths across the row groups. The other output formats work better.
+ </p></div></dd><dt><span class="term"><code class="varname">HIDE_TABLEAM</code></span></dt><dd><p>
+ If this variable is set to <code class="literal">true</code>, a table's access
+ method details are not displayed. This is mainly useful for
+ regression tests.
+ </p></dd><dt><span class="term"><code class="varname">HIDE_TOAST_COMPRESSION</code></span></dt><dd><p>
+ If this variable is set to <code class="literal">true</code>, column
+ compression method details are not displayed. This is mainly
+ useful for regression tests.
+ </p></dd><dt><span class="term"><code class="varname">HISTCONTROL</code></span></dt><dd><p>
+ If this variable is set to <code class="literal">ignorespace</code>,
+ lines which begin with a space are not entered into the history
+ list. If set to a value of <code class="literal">ignoredups</code>, lines
+ matching the previous history line are not entered. A value of
+ <code class="literal">ignoreboth</code> combines the two options. If
+ set to <code class="literal">none</code> (the default), all lines
+ read in interactive mode are saved on the history list.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature was shamelessly plagiarized from
+ <span class="application">Bash</span>.
+ </p></div></dd><dt><span class="term"><code class="varname">HISTFILE</code></span></dt><dd><p>
+ The file name that will be used to store the history list. If unset,
+ the file name is taken from the <code class="envar">PSQL_HISTORY</code>
+ environment variable. If that is not set either, the default
+ is <code class="filename">~/.psql_history</code>,
+ or <code class="filename">%APPDATA%\postgresql\psql_history</code> on Windows.
+ For example, putting:
+</p><pre class="programlisting">
+\set HISTFILE ~/.psql_history-:DBNAME
+</pre><p>
+ in <code class="filename">~/.psqlrc</code> will cause
+ <span class="application">psql</span> to maintain a separate history for
+ each database.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature was shamelessly plagiarized from
+ <span class="application">Bash</span>.
+ </p></div></dd><dt><span class="term"><code class="varname">HISTSIZE</code></span></dt><dd><p>
+ The maximum number of commands to store in the command history
+ (default 500). If set to a negative value, no limit is applied.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature was shamelessly plagiarized from
+ <span class="application">Bash</span>.
+ </p></div></dd><dt><span class="term"><code class="varname">HOST</code></span></dt><dd><p>
+ The database server host you are currently connected to. This is
+ set every time you connect to a database (including program
+ start-up), but can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">IGNOREEOF</code></span></dt><dd><p>
+ If set to 1 or less, sending an <acronym class="acronym">EOF</acronym> character (usually
+ <span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>D</strong></span>)
+ to an interactive session of <span class="application">psql</span>
+ will terminate the application. If set to a larger numeric value,
+ that many consecutive <acronym class="acronym">EOF</acronym> characters must be typed to
+ make an interactive session terminate. If the variable is set to a
+ non-numeric value, it is interpreted as 10. The default is 0.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature was shamelessly plagiarized from
+ <span class="application">Bash</span>.
+ </p></div></dd><dt><span class="term"><code class="varname">LASTOID</code></span></dt><dd><p>
+ The value of the last affected OID, as returned from an
+ <code class="command">INSERT</code> or <code class="command">\lo_import</code>
+ command. This variable is only guaranteed to be valid until
+ after the result of the next <acronym class="acronym">SQL</acronym> command has
+ been displayed.
+ <span class="productname">PostgreSQL</span> servers since version 12 do not
+ support OID system columns anymore, thus LASTOID will always be 0
+ following <code class="command">INSERT</code> when targeting such servers.
+ </p></dd><dt><span class="term"><code class="varname">LAST_ERROR_MESSAGE</code><br /></span><span class="term"><code class="varname">LAST_ERROR_SQLSTATE</code></span></dt><dd><p>
+ The primary error message and associated SQLSTATE code for the most
+ recent failed query in the current <span class="application">psql</span> session, or
+ an empty string and <code class="literal">00000</code> if no error has occurred in
+ the current session.
+ </p></dd><dt><span class="term">
+ <code class="varname">ON_ERROR_ROLLBACK</code>
+ <a id="id-1.9.4.20.8.5.2.9.18.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to <code class="literal">on</code>, if a statement in a transaction block
+ generates an error, the error is ignored and the transaction
+ continues. When set to <code class="literal">interactive</code>, such errors are only
+ ignored in interactive sessions, and not when reading script
+ files. When set to <code class="literal">off</code> (the default), a statement in a
+ transaction block that generates an error aborts the entire
+ transaction. The error rollback mode works by issuing an
+ implicit <code class="command">SAVEPOINT</code> for you, just before each command
+ that is in a transaction block, and then rolling back to the
+ savepoint if the command fails.
+ </p></dd><dt><span class="term"><code class="varname">ON_ERROR_STOP</code></span></dt><dd><p>
+ By default, command processing continues after an error. When this
+ variable is set to <code class="literal">on</code>, processing will instead stop
+ immediately. In interactive mode,
+ <span class="application">psql</span> will return to the command prompt;
+ otherwise, <span class="application">psql</span> will exit, returning
+ error code 3 to distinguish this case from fatal error
+ conditions, which are reported using error code 1. In either case,
+ any currently running scripts (the top-level script, if any, and any
+ other scripts which it may have in invoked) will be terminated
+ immediately. If the top-level command string contained multiple SQL
+ commands, processing will stop with the current command.
+ </p></dd><dt><span class="term"><code class="varname">PORT</code></span></dt><dd><p>
+ The database server port to which you are currently connected.
+ This is set every time you connect to a database (including
+ program start-up), but can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">PROMPT1</code><br /></span><span class="term"><code class="varname">PROMPT2</code><br /></span><span class="term"><code class="varname">PROMPT3</code></span></dt><dd><p>
+ These specify what the prompts <span class="application">psql</span>
+ issues should look like. See <a class="xref" href="app-psql.html#APP-PSQL-PROMPTING" title="Prompting">Prompting</a> below.
+ </p></dd><dt><span class="term"><code class="varname">QUIET</code></span></dt><dd><p>
+ Setting this variable to <code class="literal">on</code> is equivalent to the command
+ line option <code class="option">-q</code>. It is probably not too useful in
+ interactive mode.
+ </p></dd><dt><span class="term"><code class="varname">ROW_COUNT</code></span></dt><dd><p>
+ The number of rows returned or affected by the last SQL query, or 0
+ if the query failed or did not report a row count.
+ </p></dd><dt><span class="term"><code class="varname">SERVER_VERSION_NAME</code><br /></span><span class="term"><code class="varname">SERVER_VERSION_NUM</code></span></dt><dd><p>
+ The server's version number as a string, for
+ example <code class="literal">9.6.2</code>, <code class="literal">10.1</code> or <code class="literal">11beta1</code>,
+ and in numeric form, for
+ example <code class="literal">90602</code> or <code class="literal">100001</code>.
+ These are set every time you connect to a database
+ (including program start-up), but can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">SHOW_ALL_RESULTS</code></span></dt><dd><p>
+ When this variable is set to <code class="literal">off</code>, only the last
+ result of a combined query (<code class="literal">\;</code>) is shown instead of
+ all of them. The default is <code class="literal">on</code>. The off behavior
+ is for compatibility with older versions of psql.
+ </p></dd><dt><span class="term"><code class="varname">SHOW_CONTEXT</code></span></dt><dd><p>
+ This variable can be set to the
+ values <code class="literal">never</code>, <code class="literal">errors</code>, or <code class="literal">always</code>
+ to control whether <code class="literal">CONTEXT</code> fields are displayed in
+ messages from the server. The default is <code class="literal">errors</code> (meaning
+ that context will be shown in error messages, but not in notice or
+ warning messages). This setting has no effect
+ when <code class="varname">VERBOSITY</code> is set to <code class="literal">terse</code>
+ or <code class="literal">sqlstate</code>.
+ (See also <code class="command">\errverbose</code>, for use when you want a verbose
+ version of the error you just got.)
+ </p></dd><dt><span class="term"><code class="varname">SINGLELINE</code></span></dt><dd><p>
+ Setting this variable to <code class="literal">on</code> is equivalent to the command
+ line option <code class="option">-S</code>.
+ </p></dd><dt><span class="term"><code class="varname">SINGLESTEP</code></span></dt><dd><p>
+ Setting this variable to <code class="literal">on</code> is equivalent to the command
+ line option <code class="option">-s</code>.
+ </p></dd><dt><span class="term"><code class="varname">SQLSTATE</code></span></dt><dd><p>
+ The error code (see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>) associated
+ with the last SQL query's failure, or <code class="literal">00000</code> if it
+ succeeded.
+ </p></dd><dt><span class="term"><code class="varname">USER</code></span></dt><dd><p>
+ The database user you are currently connected as. This is set
+ every time you connect to a database (including program
+ start-up), but can be changed or unset.
+ </p></dd><dt><span class="term"><code class="varname">VERBOSITY</code></span></dt><dd><p>
+ This variable can be set to the values <code class="literal">default</code>,
+ <code class="literal">verbose</code>, <code class="literal">terse</code>,
+ or <code class="literal">sqlstate</code> to control the verbosity of error
+ reports.
+ (See also <code class="command">\errverbose</code>, for use when you want a verbose
+ version of the error you just got.)
+ </p></dd><dt><span class="term"><code class="varname">VERSION</code><br /></span><span class="term"><code class="varname">VERSION_NAME</code><br /></span><span class="term"><code class="varname">VERSION_NUM</code></span></dt><dd><p>
+ These variables are set at program start-up to reflect
+ <span class="application">psql</span>'s version, respectively as a verbose string,
+ a short string (e.g., <code class="literal">9.6.2</code>, <code class="literal">10.1</code>,
+ or <code class="literal">11beta1</code>), and a number (e.g., <code class="literal">90602</code>
+ or <code class="literal">100001</code>). They can be changed or unset.
+ </p></dd></dl></div></div><div class="refsect3" id="APP-PSQL-INTERPOLATION"><h4><acronym class="acronym">SQL</acronym> Interpolation</h4><p>
+ A key feature of <span class="application">psql</span>
+ variables is that you can substitute (<span class="quote">“<span class="quote">interpolate</span>”</span>)
+ them into regular <acronym class="acronym">SQL</acronym> statements, as well as the
+ arguments of meta-commands. Furthermore,
+ <span class="application">psql</span> provides facilities for
+ ensuring that variable values used as SQL literals and identifiers are
+ properly quoted. The syntax for interpolating a value without
+ any quoting is to prepend the variable name with a colon
+ (<code class="literal">:</code>). For example,
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\set foo 'my_table'</code></strong>
+testdb=&gt; <strong class="userinput"><code>SELECT * FROM :foo;</code></strong>
+</pre><p>
+ would query the table <code class="literal">my_table</code>. Note that this
+ may be unsafe: the value of the variable is copied literally, so it can
+ contain unbalanced quotes, or even backslash commands. You must make sure
+ that it makes sense where you put it.
+ </p><p>
+ When a value is to be used as an SQL literal or identifier, it is
+ safest to arrange for it to be quoted. To quote the value of
+ a variable as an SQL literal, write a colon followed by the variable
+ name in single quotes. To quote the value as an SQL identifier, write
+ a colon followed by the variable name in double quotes.
+ These constructs deal correctly with quotes and other special
+ characters embedded within the variable value.
+ The previous example would be more safely written this way:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\set foo 'my_table'</code></strong>
+testdb=&gt; <strong class="userinput"><code>SELECT * FROM :"foo";</code></strong>
+</pre><p>
+ </p><p>
+ Variable interpolation will not be performed within quoted
+ <acronym class="acronym">SQL</acronym> literals and identifiers. Therefore, a
+ construction such as <code class="literal">':foo'</code> doesn't work to produce a quoted
+ literal from a variable's value (and it would be unsafe if it did work,
+ since it wouldn't correctly handle quotes embedded in the value).
+ </p><p>
+ One example use of this mechanism is to
+ copy the contents of a file into a table column.
+ First load the file into a variable and then interpolate the variable's
+ value as a quoted string:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\set content `cat my_file.txt`</code></strong>
+testdb=&gt; <strong class="userinput"><code>INSERT INTO my_table VALUES (:'content');</code></strong>
+</pre><p>
+ (Note that this still won't work if <code class="filename">my_file.txt</code> contains NUL bytes.
+ <span class="application">psql</span> does not support embedded NUL bytes in variable values.)
+ </p><p>
+ Since colons can legally appear in SQL commands, an apparent attempt
+ at interpolation (that is, <code class="literal">:name</code>,
+ <code class="literal">:'name'</code>, or <code class="literal">:"name"</code>) is not
+ replaced unless the named variable is currently set. In any case, you
+ can escape a colon with a backslash to protect it from substitution.
+ </p><p>
+ The <code class="literal">:{?<em class="replaceable"><code>name</code></em>}</code> special syntax returns TRUE
+ or FALSE depending on whether the variable exists or not, and is thus
+ always substituted, unless the colon is backslash-escaped.
+ </p><p>
+ The colon syntax for variables is standard <acronym class="acronym">SQL</acronym> for
+ embedded query languages, such as <span class="application">ECPG</span>.
+ The colon syntaxes for array slices and type casts are
+ <span class="productname">PostgreSQL</span> extensions, which can sometimes
+ conflict with the standard usage. The colon-quote syntax for escaping a
+ variable's value as an SQL literal or identifier is a
+ <span class="application">psql</span> extension.
+ </p></div><div class="refsect3" id="APP-PSQL-PROMPTING"><h4>Prompting</h4><p>
+ The prompts <span class="application">psql</span> issues can be customized
+ to your preference. The three variables <code class="varname">PROMPT1</code>,
+ <code class="varname">PROMPT2</code>, and <code class="varname">PROMPT3</code> contain strings
+ and special escape sequences that describe the appearance of the
+ prompt. Prompt 1 is the normal prompt that is issued when
+ <span class="application">psql</span> requests a new command. Prompt 2 is
+ issued when more input is expected during command entry, for example
+ because the command was not terminated with a semicolon or a quote
+ was not closed.
+ Prompt 3 is issued when you are running an <acronym class="acronym">SQL</acronym>
+ <code class="command">COPY FROM STDIN</code> command and you need to type in
+ a row value on the terminal.
+ </p><p>
+ The value of the selected prompt variable is printed literally,
+ except where a percent sign (<code class="literal">%</code>) is encountered.
+ Depending on the next character, certain other text is substituted
+ instead. Defined substitutions are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">%M</code></span></dt><dd><p>
+ The full host name (with domain name) of the database server,
+ or <code class="literal">[local]</code> if the connection is over a Unix
+ domain socket, or
+ <code class="literal">[local:<em class="replaceable"><code>/dir/name</code></em>]</code>,
+ if the Unix domain socket is not at the compiled in default
+ location.
+ </p></dd><dt><span class="term"><code class="literal">%m</code></span></dt><dd><p>
+ The host name of the database server, truncated at the
+ first dot, or <code class="literal">[local]</code> if the connection is
+ over a Unix domain socket.
+ </p></dd><dt><span class="term"><code class="literal">%&gt;</code></span></dt><dd><p>The port number at which the database server is listening.</p></dd><dt><span class="term"><code class="literal">%n</code></span></dt><dd><p>
+ The database session user name. (The expansion of this
+ value might change during a database session as the result
+ of the command <code class="command">SET SESSION
+ AUTHORIZATION</code>.)
+ </p></dd><dt><span class="term"><code class="literal">%/</code></span></dt><dd><p>The name of the current database.</p></dd><dt><span class="term"><code class="literal">%~</code></span></dt><dd><p>Like <code class="literal">%/</code>, but the output is <code class="literal">~</code>
+ (tilde) if the database is your default database.</p></dd><dt><span class="term"><code class="literal">%#</code></span></dt><dd><p>
+ If the session user is a database superuser, then a
+ <code class="literal">#</code>, otherwise a <code class="literal">&gt;</code>.
+ (The expansion of this value might change during a database
+ session as the result of the command <code class="command">SET SESSION
+ AUTHORIZATION</code>.)
+ </p></dd><dt><span class="term"><code class="literal">%p</code></span></dt><dd><p>The process ID of the backend currently connected to.</p></dd><dt><span class="term"><code class="literal">%R</code></span></dt><dd><p>
+ In prompt 1 normally <code class="literal">=</code>,
+ but <code class="literal">@</code> if the session is in an inactive branch of a
+ conditional block, or <code class="literal">^</code> if in single-line mode,
+ or <code class="literal">!</code> if the session is disconnected from the
+ database (which can happen if <code class="command">\connect</code> fails).
+ In prompt 2 <code class="literal">%R</code> is replaced by a character that
+ depends on why <span class="application">psql</span> expects more input:
+ <code class="literal">-</code> if the command simply wasn't terminated yet,
+ but <code class="literal">*</code> if there is an unfinished
+ <code class="literal">/* ... */</code> comment,
+ a single quote if there is an unfinished quoted string,
+ a double quote if there is an unfinished quoted identifier,
+ a dollar sign if there is an unfinished dollar-quoted string,
+ or <code class="literal">(</code> if there is an unmatched left parenthesis.
+ In prompt 3 <code class="literal">%R</code> doesn't produce anything.
+ </p></dd><dt><span class="term"><code class="literal">%x</code></span></dt><dd><p>
+ Transaction status: an empty string when not in a transaction
+ block, or <code class="literal">*</code> when in a transaction block, or
+ <code class="literal">!</code> when in a failed transaction block, or <code class="literal">?</code>
+ when the transaction state is indeterminate (for example, because
+ there is no connection).
+ </p></dd><dt><span class="term"><code class="literal">%l</code></span></dt><dd><p>
+ The line number inside the current statement, starting from <code class="literal">1</code>.
+ </p></dd><dt><span class="term"><code class="literal">%</code><em class="replaceable"><code>digits</code></em></span></dt><dd><p>
+ The character with the indicated octal code is substituted.
+ </p></dd><dt><span class="term"><code class="literal">%:</code><em class="replaceable"><code>name</code></em><code class="literal">:</code></span></dt><dd><p>
+ The value of the <span class="application">psql</span> variable
+ <em class="replaceable"><code>name</code></em>. See
+ <a class="xref" href="app-psql.html#APP-PSQL-VARIABLES" title="Variables">Variables</a>, above, for details.
+ </p></dd><dt><span class="term"><code class="literal">%`</code><em class="replaceable"><code>command</code></em><code class="literal">`</code></span></dt><dd><p>
+ The output of <em class="replaceable"><code>command</code></em>, similar to ordinary
+ <span class="quote">“<span class="quote">back-tick</span>”</span> substitution.
+ </p></dd><dt><span class="term"><code class="literal">%[</code> ... <code class="literal">%]</code></span></dt><dd><p>
+ Prompts can contain terminal control characters which, for
+ example, change the color, background, or style of the prompt
+ text, or change the title of the terminal window. In order for
+ the line editing features of <span class="application">Readline</span> to work properly, these
+ non-printing control characters must be designated as invisible
+ by surrounding them with <code class="literal">%[</code> and
+ <code class="literal">%]</code>. Multiple pairs of these can occur within
+ the prompt. For example:
+</p><pre class="programlisting">
+testdb=&gt; \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
+</pre><p>
+ results in a boldfaced (<code class="literal">1;</code>) yellow-on-black
+ (<code class="literal">33;40</code>) prompt on VT100-compatible, color-capable
+ terminals.
+ </p></dd><dt><span class="term"><code class="literal">%w</code></span></dt><dd><p>
+ Whitespace of the same width as the most recent output of
+ <code class="varname">PROMPT1</code>. This can be used as a
+ <code class="varname">PROMPT2</code> setting, so that multi-line statements are
+ aligned with the first line, but there is no visible secondary prompt.
+ </p></dd></dl></div><p>
+
+ To insert a percent sign into your prompt, write
+ <code class="literal">%%</code>. The default prompts are
+ <code class="literal">'%/%R%x%# '</code> for prompts 1 and 2, and
+ <code class="literal">'&gt;&gt; '</code> for prompt 3.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature was shamelessly plagiarized from
+ <span class="application">tcsh</span>.
+ </p></div></div><div class="refsect3" id="APP-PSQL-READLINE"><h4>Command-Line Editing</h4><a id="id-1.9.4.20.8.5.5.2" class="indexterm"></a><a id="id-1.9.4.20.8.5.5.3" class="indexterm"></a><p>
+ <span class="application">psql</span> uses
+ the <span class="application">Readline</span>
+ or <span class="application">libedit</span> library, if available, for
+ convenient line editing and retrieval. The command history is
+ automatically saved when <span class="application">psql</span> exits and is
+ reloaded when <span class="application">psql</span> starts up. Type
+ up-arrow or control-P to retrieve previous lines.
+ </p><p>
+ You can also use tab completion to fill in partially-typed keywords
+ and SQL object names in many (by no means all) contexts. For example,
+ at the start of a command, typing <code class="literal">ins</code> and pressing
+ TAB will fill in <code class="literal">insert into </code>. Then, typing a few
+ characters of a table or schema name and pressing <code class="literal">TAB</code>
+ will fill in the unfinished name, or offer a menu of possible completions
+ when there's more than one. (Depending on the library in use, you may need to
+ press <code class="literal">TAB</code> more than once to get a menu.)
+ </p><p>
+ Tab completion for SQL object names requires sending queries to the
+ server to find possible matches. In some contexts this can interfere
+ with other operations. For example, after <code class="command">BEGIN</code>
+ it will be too late to issue <code class="command">SET TRANSACTION ISOLATION
+ LEVEL</code> if a tab-completion query is issued in between.
+ If you do not want tab completion at all, you
+ can turn it off permanently by putting this in a file named
+ <code class="filename">.inputrc</code> in your home directory:
+</p><pre class="programlisting">
+$if psql
+set disable-completion on
+$endif
+</pre><p>
+ (This is not a <span class="application">psql</span> but a
+ <span class="application">Readline</span> feature. Read its documentation
+ for further details.)
+ </p><p>
+ The <code class="option">-n</code> (<code class="option">--no-readline</code>) command line
+ option can also be useful to disable use
+ of <span class="application">Readline</span> for a single run
+ of <span class="application">psql</span>. This prevents tab completion,
+ use or recording of command line history, and editing of multi-line
+ commands. It is particularly useful when you need to copy-and-paste
+ text that contains <code class="literal">TAB</code> characters.
+ </p></div></div></div><div class="refsect1" id="APP-PSQL-ENVIRONMENT"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">COLUMNS</code></span></dt><dd><p>
+ If <code class="literal">\pset columns</code> is zero, controls the
+ width for the <code class="literal">wrapped</code> format and width for determining
+ if wide output requires the pager or should be switched to the
+ vertical format in expanded auto mode.
+ </p></dd><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd><dt><span class="term"><code class="envar">PSQL_EDITOR</code><br /></span><span class="term"><code class="envar">EDITOR</code><br /></span><span class="term"><code class="envar">VISUAL</code></span></dt><dd><p>
+ Editor used by the <code class="command">\e</code>, <code class="command">\ef</code>,
+ and <code class="command">\ev</code> commands.
+ These variables are examined in the order listed;
+ the first that is set is used.
+ If none of them is set, the default is to use <code class="filename">vi</code>
+ on Unix systems or <code class="filename">notepad.exe</code> on Windows systems.
+ </p></dd><dt><span class="term"><code class="envar">PSQL_EDITOR_LINENUMBER_ARG</code></span></dt><dd><p>
+ When <code class="command">\e</code>, <code class="command">\ef</code>, or
+ <code class="command">\ev</code> is used
+ with a line number argument, this variable specifies the
+ command-line argument used to pass the starting line number to
+ the user's editor. For editors such as <span class="productname">Emacs</span> or
+ <span class="productname">vi</span>, this is a plus sign. Include a trailing
+ space in the value of the variable if there needs to be space
+ between the option name and the line number. Examples:
+</p><pre class="programlisting">
+PSQL_EDITOR_LINENUMBER_ARG='+'
+PSQL_EDITOR_LINENUMBER_ARG='--line '
+</pre><p>
+ </p><p>
+ The default is <code class="literal">+</code> on Unix systems
+ (corresponding to the default editor <code class="filename">vi</code>,
+ and useful for many other common editors); but there is no
+ default on Windows systems.
+ </p></dd><dt><span class="term"><code class="envar">PSQL_HISTORY</code></span></dt><dd><p>
+ Alternative location for the command history file. Tilde (<code class="literal">~</code>) expansion is performed.
+ </p></dd><dt><span class="term"><code class="envar">PSQL_PAGER</code><br /></span><span class="term"><code class="envar">PAGER</code></span></dt><dd><p>
+ If a query's results do not fit on the screen, they are piped
+ through this command. Typical values are <code class="literal">more</code>
+ or <code class="literal">less</code>.
+ Use of the pager can be disabled by setting <code class="envar">PSQL_PAGER</code>
+ or <code class="envar">PAGER</code> to an empty string, or by adjusting the
+ pager-related options of the <code class="command">\pset</code> command.
+ These variables are examined in the order listed;
+ the first that is set is used.
+ If neither of them is set, the default is to use <code class="literal">more</code> on most
+ platforms, but <code class="literal">less</code> on Cygwin.
+ </p></dd><dt><span class="term"><code class="envar">PSQL_WATCH_PAGER</code></span></dt><dd><p>
+ When a query is executed repeatedly with the <code class="command">\watch</code>
+ command, a pager is not used by default. This behavior can be changed
+ by setting <code class="envar">PSQL_WATCH_PAGER</code> to a pager command, on Unix
+ systems. The <code class="literal">pspg</code> pager (not part of
+ <span class="productname">PostgreSQL</span> but available in many open source
+ software distributions) can display the output of
+ <code class="command">\watch</code> if started with the option
+ <code class="literal">--stream</code>.
+ </p></dd><dt><span class="term"><code class="envar">PSQLRC</code></span></dt><dd><p>
+ Alternative location of the user's <code class="filename">.psqlrc</code> file. Tilde (<code class="literal">~</code>) expansion is performed.
+ </p></dd><dt><span class="term"><code class="envar">SHELL</code></span></dt><dd><p>
+ Command executed by the <code class="command">\!</code> command.
+ </p></dd><dt><span class="term"><code class="envar">TMPDIR</code></span></dt><dd><p>
+ Directory for storing temporary files. The default is
+ <code class="filename">/tmp</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.20.10"><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">psqlrc</code> and <code class="filename">~/.psqlrc</code></span></dt><dd><p>
+ Unless it is passed an <code class="option">-X</code> option,
+ <span class="application">psql</span> attempts to read and execute commands
+ from the system-wide startup file (<code class="filename">psqlrc</code>) and then
+ the user's personal startup file (<code class="filename">~/.psqlrc</code>), after
+ connecting to the database but before accepting normal commands.
+ These files can be used to set up the client and/or the server to taste,
+ typically with <code class="command">\set</code> and <code class="command">SET</code>
+ commands.
+ </p><p>
+ The system-wide startup file is named <code class="filename">psqlrc</code>.
+ By default it is
+ sought in the installation's <span class="quote">“<span class="quote">system configuration</span>”</span> directory,
+ which is most reliably identified by running <code class="literal">pg_config
+ --sysconfdir</code>.
+ Typically this directory will be <code class="filename">../etc/</code>
+ relative to the directory containing
+ the <span class="productname">PostgreSQL</span> executables.
+ The directory to look in can be set explicitly via
+ the <code class="envar">PGSYSCONFDIR</code> environment variable.
+ </p><p>
+ The user's personal startup file is named <code class="filename">.psqlrc</code>
+ and is sought in the invoking user's home directory.
+ On Windows the personal startup file is instead named
+ <code class="filename">%APPDATA%\postgresql\psqlrc.conf</code>.
+ In either case, this default file path can be overridden by setting
+ the <code class="envar">PSQLRC</code> environment variable.
+ </p><p>
+ Both the system-wide startup file and the user's personal startup file
+ can be made <span class="application">psql</span>-version-specific
+ by appending a dash and the <span class="productname">PostgreSQL</span>
+ major or minor release identifier to the file name,
+ for example <code class="filename">~/.psqlrc-15</code> or
+ <code class="filename">~/.psqlrc-15.5</code>.
+ The most specific version-matching file will be read in preference
+ to a non-version-specific file.
+ These version suffixes are added after determining the file path
+ as explained above.
+ </p></dd><dt><span class="term"><code class="filename">.psql_history</code></span></dt><dd><p>
+ The command-line history is stored in the file
+ <code class="filename">~/.psql_history</code>, or
+ <code class="filename">%APPDATA%\postgresql\psql_history</code> on Windows.
+ </p><p>
+ The location of the history file can be set explicitly via
+ the <code class="varname">HISTFILE</code> <span class="application">psql</span> variable or
+ the <code class="envar">PSQL_HISTORY</code> environment variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.4.20.11"><h2>Notes</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="application">psql</span> works best with servers of the same
+ or an older major version. Backslash commands are particularly likely
+ to fail if the server is of a newer version than <span class="application">psql</span>
+ itself. However, backslash commands of the <code class="literal">\d</code> family should
+ work with servers of versions back to 9.2, though not necessarily with
+ servers newer than <span class="application">psql</span> itself. The general
+ functionality of running SQL commands and displaying query results
+ should also work with servers of a newer major version, but this cannot
+ be guaranteed in all cases.
+ </p><p>
+ If you want to use <span class="application">psql</span> to connect to several
+ servers of different major versions, it is recommended that you use the
+ newest version of <span class="application">psql</span>. Alternatively, you
+ can keep around a copy of <span class="application">psql</span> from each
+ major version and be sure to use the version that matches the
+ respective server. But in practice, this additional complication should
+ not be necessary.
+ </p></li><li class="listitem"><p>
+ Before <span class="productname">PostgreSQL</span> 9.6,
+ the <code class="option">-c</code> option implied <code class="option">-X</code>
+ (<code class="option">--no-psqlrc</code>); this is no longer the case.
+ </p></li><li class="listitem"><p>
+ Before <span class="productname">PostgreSQL</span> 8.4,
+ <span class="application">psql</span> allowed the
+ first argument of a single-letter backslash command to start
+ directly after the command, without intervening whitespace.
+ Now, some whitespace is required.
+ </p></li></ul></div></div><div class="refsect1" id="id-1.9.4.20.12"><h2>Notes for Windows Users</h2><p>
+ <span class="application">psql</span> is built as a <span class="quote">“<span class="quote">console
+ application</span>”</span>. Since the Windows console windows use a different
+ encoding than the rest of the system, you must take special care
+ when using 8-bit characters within <span class="application">psql</span>.
+ If <span class="application">psql</span> detects a problematic
+ console code page, it will warn you at startup. To change the
+ console code page, two things are necessary:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Set the code page by entering <strong class="userinput"><code>cmd.exe /c chcp
+ 1252</code></strong>. (1252 is a code page that is appropriate for
+ German; replace it with your value.) If you are using Cygwin,
+ you can put this command in <code class="filename">/etc/profile</code>.
+ </p></li><li class="listitem"><p>
+ Set the console font to <code class="literal">Lucida Console</code>, because the
+ raster font does not work with the ANSI code page.
+ </p></li></ul></div></div><div class="refsect1" id="APP-PSQL-EXAMPLES"><h2>Examples</h2><p>
+ The first example shows how to spread a command over several lines of
+ input. Notice the changing prompt:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>CREATE TABLE my_table (</code></strong>
+testdb(&gt; <strong class="userinput"><code> first integer not null default 0,</code></strong>
+testdb(&gt; <strong class="userinput"><code> second text)</code></strong>
+testdb-&gt; <strong class="userinput"><code>;</code></strong>
+CREATE TABLE
+</pre><p>
+ Now look at the table definition again:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\d my_table</code></strong>
+ Table "public.my_table"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ first | integer | | not null | 0
+ second | text | | |
+</pre><p>
+ Now we change the prompt to something more interesting:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\set PROMPT1 '%n@%m %~%R%# '</code></strong>
+peter@localhost testdb=&gt;
+</pre><p>
+ Let's assume you have filled the table with data and want to take a
+ look at it:
+</p><pre class="programlisting">
+peter@localhost testdb=&gt; SELECT * FROM my_table;
+ first | second
+-------+--------
+ 1 | one
+ 2 | two
+ 3 | three
+ 4 | four
+(4 rows)
+</pre><p>
+ You can display tables in different ways by using the
+ <code class="command">\pset</code> command:
+</p><pre class="programlisting">
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset border 2</code></strong>
+Border style is 2.
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT * FROM my_table;</code></strong>
++-------+--------+
+| first | second |
++-------+--------+
+| 1 | one |
+| 2 | two |
+| 3 | three |
+| 4 | four |
++-------+--------+
+(4 rows)
+
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset border 0</code></strong>
+Border style is 0.
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT * FROM my_table;</code></strong>
+first second
+----- ------
+ 1 one
+ 2 two
+ 3 three
+ 4 four
+(4 rows)
+
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset border 1</code></strong>
+Border style is 1.
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset format csv</code></strong>
+Output format is csv.
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset tuples_only</code></strong>
+Tuples only is on.
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT second, first FROM my_table;</code></strong>
+one,1
+two,2
+three,3
+four,4
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset format unaligned</code></strong>
+Output format is unaligned.
+peter@localhost testdb=&gt; <strong class="userinput"><code>\pset fieldsep '\t'</code></strong>
+Field separator is " ".
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT second, first FROM my_table;</code></strong>
+one 1
+two 2
+three 3
+four 4
+</pre><p>
+ Alternatively, use the short commands:
+</p><pre class="programlisting">
+peter@localhost testdb=&gt; <strong class="userinput"><code>\a \t \x</code></strong>
+Output format is aligned.
+Tuples only is off.
+Expanded display is on.
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT * FROM my_table;</code></strong>
+-[ RECORD 1 ]-
+first | 1
+second | one
+-[ RECORD 2 ]-
+first | 2
+second | two
+-[ RECORD 3 ]-
+first | 3
+second | three
+-[ RECORD 4 ]-
+first | 4
+second | four
+</pre><p>
+ </p><p>
+ Also, these output format options can be set for just one query by using
+ <code class="literal">\g</code>:
+</p><pre class="programlisting">
+peter@localhost testdb=&gt; <strong class="userinput"><code>SELECT * FROM my_table</code></strong>
+peter@localhost testdb-&gt; <strong class="userinput"><code>\g (format=aligned tuples_only=off expanded=on)</code></strong>
+-[ RECORD 1 ]-
+first | 1
+second | one
+-[ RECORD 2 ]-
+first | 2
+second | two
+-[ RECORD 3 ]-
+first | 3
+second | three
+-[ RECORD 4 ]-
+first | 4
+second | four
+</pre><p>
+ </p><p>
+ Here is an example of using the <code class="command">\df</code> command to
+ find only functions with names matching <code class="literal">int*pl</code>
+ and whose second argument is of type <code class="type">bigint</code>:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>\df int*pl * bigint</code></strong>
+ List of functions
+ Schema | Name | Result data type | Argument data types | Type
+------------+---------+------------------+---------------------+------
+ pg_catalog | int28pl | bigint | smallint, bigint | func
+ pg_catalog | int48pl | bigint | integer, bigint | func
+ pg_catalog | int8pl | bigint | bigint, bigint | func
+(3 rows)
+</pre><p>
+ </p><p>
+ When suitable, query results can be shown in a crosstab representation
+ with the <code class="command">\crosstabview</code> command:
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>SELECT first, second, first &gt; 2 AS gt2 FROM my_table;</code></strong>
+ first | second | gt2
+-------+--------+-----
+ 1 | one | f
+ 2 | two | f
+ 3 | three | t
+ 4 | four | t
+(4 rows)
+
+testdb=&gt; <strong class="userinput"><code>\crosstabview first second</code></strong>
+ first | one | two | three | four
+-------+-----+-----+-------+------
+ 1 | f | | |
+ 2 | | f | |
+ 3 | | | t |
+ 4 | | | | t
+(4 rows)
+</pre><p>
+
+This second example shows a multiplication table with rows sorted in reverse
+numerical order and columns with an independent, ascending numerical order.
+</p><pre class="programlisting">
+testdb=&gt; <strong class="userinput"><code>SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB",</code></strong>
+testdb(&gt; <strong class="userinput"><code>row_number() over(order by t2.first) AS ord</code></strong>
+testdb(&gt; <strong class="userinput"><code>FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC</code></strong>
+testdb(&gt; <strong class="userinput"><code>\crosstabview "A" "B" "AxB" ord</code></strong>
+ A | 101 | 102 | 103 | 104
+---+-----+-----+-----+-----
+ 4 | 404 | 408 | 412 | 416
+ 3 | 303 | 306 | 309 | 312
+ 2 | 202 | 204 | 206 | 208
+ 1 | 101 | 102 | 103 | 104
+(4 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgverifybackup.html" title="pg_verifybackup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-reindexdb.html" title="reindexdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_verifybackup</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">reindexdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-reindexdb.html b/doc/src/sgml/html/app-reindexdb.html
new file mode 100644
index 0000000..1295f0a
--- /dev/null
+++ b/doc/src/sgml/html/app-reindexdb.html
@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>reindexdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-psql.html" title="psql" /><link rel="next" href="app-vacuumdb.html" title="vacuumdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">reindexdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-psql.html" title="psql">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-vacuumdb.html" title="vacuumdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-REINDEXDB"><div class="titlepage"></div><a id="id-1.9.4.21.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">reindexdb</span></span></h2><p>reindexdb — reindex a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.21.4.1"><code class="command">reindexdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...]
+ [
+ <code class="option">-S</code> | <code class="option">--schema</code>
+ <em class="replaceable"><code>schema</code></em>
+ ]
+ ...
+ [
+ <code class="option">-t</code> | <code class="option">--table</code>
+ <em class="replaceable"><code>table</code></em>
+ ]
+ ...
+ [
+ <code class="option">-i</code> | <code class="option">--index</code>
+ <em class="replaceable"><code>index</code></em>
+ ]
+ ... [<em class="replaceable"><code>dbname</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.4.21.4.2"><code class="command">reindexdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] <code class="option">-a</code> | <code class="option">--all</code> </p></div><div class="cmdsynopsis"><p id="id-1.9.4.21.4.3"><code class="command">reindexdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] <code class="option">-s</code> | <code class="option">--system</code> [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.21.5"><h2>Description</h2><p>
+ <span class="application">reindexdb</span> is a utility for rebuilding indexes
+ in a <span class="productname">PostgreSQL</span> database.
+ </p><p>
+ <span class="application">reindexdb</span> is a wrapper around the SQL
+ command <a class="link" href="sql-reindex.html" title="REINDEX"><code class="command">REINDEX</code></a>.
+ There is no effective difference between reindexing databases via
+ this utility and via other methods for accessing the server.
+ </p></div><div class="refsect1" id="id-1.9.4.21.6"><h2>Options</h2><p>
+ <span class="application">reindexdb</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
+ Reindex all databases.
+ </p></dd><dt><span class="term"><code class="option">--concurrently</code></span></dt><dd><p>
+ Use the <code class="literal">CONCURRENTLY</code> option. See
+ <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a>, where all the caveats of this option
+ are explained in detail.
+ </p></dd><dt><span class="term"><code class="option">[<span class="optional">-d</span>] <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">[<span class="optional">--dbname=</span>]<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to be reindexed,
+ when <code class="option">-a</code>/<code class="option">--all</code> is not used.
+ If this is not specified, the database name is read
+ from the environment variable <code class="envar">PGDATABASE</code>. If
+ that is not set, the user name specified for the connection is
+ used. The <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>. If so,
+ connection string parameters will override any conflicting command
+ line options.
+ </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">reindexdb</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-i <em class="replaceable"><code>index</code></em></code><br /></span><span class="term"><code class="option">--index=<em class="replaceable"><code>index</code></em></code></span></dt><dd><p>
+ Recreate <em class="replaceable"><code>index</code></em> only.
+ Multiple indexes can be recreated by writing multiple
+ <code class="option">-i</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>njobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>njobs</code></em></code></span></dt><dd><p>
+ Execute the reindex commands in parallel by running
+ <em class="replaceable"><code>njobs</code></em>
+ commands simultaneously. This option may reduce the processing time
+ but it also increases the load on the database server.
+ </p><p>
+ <span class="application">reindexdb</span> will open
+ <em class="replaceable"><code>njobs</code></em> connections to the
+ database, so make sure your <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>
+ setting is high enough to accommodate all connections.
+ </p><p>
+ Note that this option is incompatible with the <code class="option">--index</code>
+ and <code class="option">--system</code> options.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Do not display progress messages.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--system</code></span></dt><dd><p>
+ Reindex database's system catalogs only.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>schema</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>schema</code></em></code></span></dt><dd><p>
+ Reindex <em class="replaceable"><code>schema</code></em> only.
+ Multiple schemas can be reindexed by writing multiple
+ <code class="option">-S</code> switches.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>table</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>table</code></em></code></span></dt><dd><p>
+ Reindex <em class="replaceable"><code>table</code></em> only.
+ Multiple tables can be reindexed by writing multiple
+ <code class="option">-t</code> switches.
+ </p></dd><dt><span class="term"><code class="option">--tablespace=<em class="replaceable"><code>tablespace</code></em></code></span></dt><dd><p>
+ Specifies the tablespace where indexes are rebuilt. (This name is
+ processed as a double-quoted identifier.)
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Print detailed information during processing.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">reindexdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">reindexdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+
+ </p><p>
+ <span class="application">reindexdb</span> also accepts
+ the following command-line arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">reindexdb</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">reindexdb</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">reindexdb</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to to discover which
+ databases should be reindexed,
+ when <code class="option">-a</code>/<code class="option">--all</code> is used.
+ If not specified, the <code class="literal">postgres</code> database will be used,
+ or if that does not exist, <code class="literal">template1</code> will be used.
+ This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
+ string</a>. If so, connection string parameters will override any
+ conflicting command line options. Also, connection string parameters
+ other than the database name itself will be re-used when connecting
+ to other databases.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.21.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.21.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.21.9"><h2>Notes</h2><p>
+ <span class="application">reindexdb</span> might need to connect several
+ times to the <span class="productname">PostgreSQL</span> server, asking
+ for a password each time. It is convenient to have a
+ <code class="filename">~/.pgpass</code> file in such cases. See <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> for more information.
+ </p></div><div class="refsect1" id="id-1.9.4.21.10"><h2>Examples</h2><p>
+ To reindex the database <code class="literal">test</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>reindexdb test</code></strong>
+</pre><p>
+ </p><p>
+ To reindex the table <code class="literal">foo</code> and the index
+ <code class="literal">bar</code> in a database named <code class="literal">abcd</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>reindexdb --table=foo --index=bar abcd</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.21.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-psql.html" title="psql">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-vacuumdb.html" title="vacuumdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">psql</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">vacuumdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/app-vacuumdb.html b/doc/src/sgml/html/app-vacuumdb.html
new file mode 100644
index 0000000..c3fc6e5
--- /dev/null
+++ b/doc/src/sgml/html/app-vacuumdb.html
@@ -0,0 +1,244 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>vacuumdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-reindexdb.html" title="reindexdb" /><link rel="next" href="reference-server.html" title="PostgreSQL Server Applications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">vacuumdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-reindexdb.html" title="reindexdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="reference-server.html" title="PostgreSQL Server Applications">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-VACUUMDB"><div class="titlepage"></div><a id="id-1.9.4.22.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">vacuumdb</span></span></h2><p>vacuumdb — garbage-collect and analyze a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.22.4.1"><code class="command">vacuumdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...]
+ [
+ <code class="option">-t</code> | <code class="option">--table</code>
+ <em class="replaceable"><code>table</code></em>
+ [( <em class="replaceable"><code>column</code></em> [,...] )]
+ ]
+ ... [<em class="replaceable"><code>dbname</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.4.22.4.2"><code class="command">vacuumdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] <code class="option">-a</code> | <code class="option">--all</code> </p></div></div><div class="refsect1" id="id-1.9.4.22.5"><h2>Description</h2><p>
+ <span class="application">vacuumdb</span> is a utility for cleaning a
+ <span class="productname">PostgreSQL</span> database.
+ <span class="application">vacuumdb</span> will also generate internal statistics
+ used by the <span class="productname">PostgreSQL</span> query optimizer.
+ </p><p>
+ <span class="application">vacuumdb</span> is a wrapper around the SQL
+ command <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>.
+ There is no effective difference between vacuuming and analyzing
+ databases via this utility and via other methods for accessing the
+ server.
+ </p></div><div class="refsect1" id="id-1.9.4.22.6"><h2>Options</h2><p>
+ <span class="application">vacuumdb</span> accepts the following command-line arguments:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
+ Vacuum all databases.
+ </p></dd><dt><span class="term"><code class="option">[<span class="optional">-d</span>] <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">[<span class="optional">--dbname=</span>]<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to be cleaned or analyzed,
+ when <code class="option">-a</code>/<code class="option">--all</code> is not used.
+ If this is not specified, the database name is read
+ from the environment variable <code class="envar">PGDATABASE</code>. If
+ that is not set, the user name specified for the connection is
+ used. The <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>. If so,
+ connection string parameters will override any conflicting command
+ line options.
+ </p></dd><dt><span class="term"><code class="option">--disable-page-skipping</code></span></dt><dd><p>
+ Disable skipping pages based on the contents of the visibility map.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 9.6 and later.
+ </p></div></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+ Echo the commands that <span class="application">vacuumdb</span> generates
+ and sends to the server.
+ </p></dd><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--full</code></span></dt><dd><p>
+ Perform <span class="quote">“<span class="quote">full</span>”</span> vacuuming.
+ </p></dd><dt><span class="term"><code class="option">-F</code><br /></span><span class="term"><code class="option">--freeze</code></span></dt><dd><p>
+ Aggressively <span class="quote">“<span class="quote">freeze</span>”</span> tuples.
+ </p></dd><dt><span class="term"><code class="option">--force-index-cleanup</code></span></dt><dd><p>
+ Always remove index entries pointing to dead tuples.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 12 and later.
+ </p></div></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>njobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>njobs</code></em></code></span></dt><dd><p>
+ Execute the vacuum or analyze commands in parallel by running
+ <em class="replaceable"><code>njobs</code></em>
+ commands simultaneously. This option may reduce the processing time
+ but it also increases the load on the database server.
+ </p><p>
+ <span class="application">vacuumdb</span> will open
+ <em class="replaceable"><code>njobs</code></em> connections to the
+ database, so make sure your <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>
+ setting is high enough to accommodate all connections.
+ </p><p>
+ Note that using this mode together with the <code class="option">-f</code>
+ (<code class="literal">FULL</code>) option might cause deadlock failures if
+ certain system catalogs are processed in parallel.
+ </p></dd><dt><span class="term"><code class="option">--min-mxid-age <em class="replaceable"><code>mxid_age</code></em></code></span></dt><dd><p>
+ Only execute the vacuum or analyze commands on tables with a multixact
+ ID age of at least <em class="replaceable"><code>mxid_age</code></em>.
+ This setting is useful for prioritizing tables to process to prevent
+ multixact ID wraparound (see
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND" title="25.1.5.1. Multixacts and Wraparound">Section 25.1.5.1</a>).
+ </p><p>
+ For the purposes of this option, the multixact ID age of a relation is
+ the greatest of the ages of the main relation and its associated
+ <acronym class="acronym">TOAST</acronym> table, if one exists. Since the commands
+ issued by <span class="application">vacuumdb</span> will also process the
+ <acronym class="acronym">TOAST</acronym> table for the relation if necessary, it does
+ not need to be considered separately.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 9.6 and later.
+ </p></div></dd><dt><span class="term"><code class="option">--min-xid-age <em class="replaceable"><code>xid_age</code></em></code></span></dt><dd><p>
+ Only execute the vacuum or analyze commands on tables with a
+ transaction ID age of at least
+ <em class="replaceable"><code>xid_age</code></em>. This setting
+ is useful for prioritizing tables to process to prevent transaction
+ ID wraparound (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>).
+ </p><p>
+ For the purposes of this option, the transaction ID age of a relation
+ is the greatest of the ages of the main relation and its associated
+ <acronym class="acronym">TOAST</acronym> table, if one exists. Since the commands
+ issued by <span class="application">vacuumdb</span> will also process the
+ <acronym class="acronym">TOAST</acronym> table for the relation if necessary, it does
+ not need to be considered separately.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 9.6 and later.
+ </p></div></dd><dt><span class="term"><code class="option">--no-index-cleanup</code></span></dt><dd><p>
+ Do not remove index entries pointing to dead tuples.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 12 and later.
+ </p></div></dd><dt><span class="term"><code class="option">--no-process-toast</code></span></dt><dd><p>
+ Skip the TOAST table associated with the table to vacuum, if any.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 14 and later.
+ </p></div></dd><dt><span class="term"><code class="option">--no-truncate</code></span></dt><dd><p>
+ Do not truncate empty pages at the end of the table.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 12 and later.
+ </p></div></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>parallel_workers</code></em></code><br /></span><span class="term"><code class="option">--parallel=<em class="replaceable"><code>parallel_workers</code></em></code></span></dt><dd><p>
+ Specify the number of parallel workers for <em class="firstterm">parallel vacuum</em>.
+ This allows the vacuum to leverage multiple CPUs to process indexes.
+ See <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 13 and later.
+ </p></div></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Do not display progress messages.
+ </p></dd><dt><span class="term"><code class="option">--skip-locked</code></span></dt><dd><p>
+ Skip relations that cannot be immediately locked for processing.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This option is only available for servers running
+ <span class="productname">PostgreSQL</span> 12 and later.
+ </p></div></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>table</code></em> [ (<em class="replaceable"><code>column</code></em> [,...]) ]</code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>table</code></em> [ (<em class="replaceable"><code>column</code></em> [,...]) ]</code></span></dt><dd><p>
+ Clean or analyze <em class="replaceable"><code>table</code></em> only.
+ Column names can be specified only in conjunction with
+ the <code class="option">--analyze</code> or <code class="option">--analyze-only</code> options.
+ Multiple tables can be vacuumed by writing multiple
+ <code class="option">-t</code> switches.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If you specify columns, you probably have to escape the parentheses
+ from the shell. (See examples below.)
+ </p></div></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Print detailed information during processing.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">vacuumdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--analyze</code></span></dt><dd><p>
+ Also calculate statistics for use by the optimizer.
+ </p></dd><dt><span class="term"><code class="option">-Z</code><br /></span><span class="term"><code class="option">--analyze-only</code></span></dt><dd><p>
+ Only calculate statistics for use by the optimizer (no vacuum).
+ </p></dd><dt><span class="term"><code class="option">--analyze-in-stages</code></span></dt><dd><p>
+ Only calculate statistics for use by the optimizer (no vacuum),
+ like <code class="option">--analyze-only</code>. Run three
+ stages of analyze; the first stage uses the lowest possible statistics
+ target (see <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a>)
+ to produce usable statistics faster, and subsequent stages build the
+ full statistics.
+ </p><p>
+ This option is only useful to analyze a database that currently has
+ no statistics or has wholly incorrect ones, such as if it is newly
+ populated from a restored dump or by <code class="command">pg_upgrade</code>.
+ Be aware that running with this option in a database with existing
+ statistics may cause the query optimizer choices to become
+ transiently worse due to the low statistics targets of the early
+ stages.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">vacuumdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">vacuumdb</span> also accepts
+ the following command-line arguments for connection parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ Specifies the host name of the machine on which the server
+ is running. If the value begins with a slash, it is used
+ as the directory for the Unix domain socket.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server
+ is listening for connections.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> file, the
+ connection attempt will fail. This option can be useful in
+ batch jobs and scripts where no user is present to enter a
+ password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">vacuumdb</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">vacuumdb</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">vacuumdb</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+ Specifies the name of the database to connect to to discover which
+ databases should be vacuumed,
+ when <code class="option">-a</code>/<code class="option">--all</code> is used.
+ If not specified, the <code class="literal">postgres</code> database will be used,
+ or if that does not exist, <code class="literal">template1</code> will be used.
+ This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
+ string</a>. If so, connection string parameters will override any
+ conflicting command line options. Also, connection string parameters
+ other than the database name itself will be re-used when connecting
+ to other databases.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.22.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.4.22.8"><h2>Diagnostics</h2><p>
+ In case of difficulty, see <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a>
+ and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <span class="application">libpq</span> front-end
+ library will apply.
+ </p></div><div class="refsect1" id="id-1.9.4.22.9"><h2>Notes</h2><p>
+ <span class="application">vacuumdb</span> might need to connect several
+ times to the <span class="productname">PostgreSQL</span> server, asking
+ for a password each time. It is convenient to have a
+ <code class="filename">~/.pgpass</code> file in such cases. See <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> for more information.
+ </p></div><div class="refsect1" id="id-1.9.4.22.10"><h2>Examples</h2><p>
+ To clean the database <code class="literal">test</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>vacuumdb test</code></strong>
+</pre><p>
+ </p><p>
+ To clean and analyze for the optimizer a database named
+ <code class="literal">bigdb</code>:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>vacuumdb --analyze bigdb</code></strong>
+</pre><p>
+ </p><p>
+ To clean a single table
+ <code class="literal">foo</code> in a database named
+ <code class="literal">xyzzy</code>, and analyze a single column
+ <code class="literal">bar</code> of the table for the optimizer:
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>vacuumdb --analyze --verbose --table='foo(bar)' xyzzy</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.22.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-reindexdb.html" title="reindexdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="reference-server.html" title="PostgreSQL Server Applications">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">reindexdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> PostgreSQL Server Applications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/appendix-obsolete.html b/doc/src/sgml/html/appendix-obsolete.html
new file mode 100644
index 0000000..8a07dd0
--- /dev/null
+++ b/doc/src/sgml/html/appendix-obsolete.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix O. Obsolete or Renamed Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="color-which.html" title="N.2. Configuring the Colors" /><link rel="next" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix O. Obsolete or Renamed Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="color-which.html" title="N.2. Configuring the Colors">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf">Next</a></td></tr></table><hr /></div><div class="appendix" id="APPENDIX-OBSOLETE"><div class="titlepage"><div><div><h2 class="title">Appendix O. Obsolete or Renamed Features</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="recovery-config.html">O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code></a></span></dt><dt><span class="sect1"><a href="default-roles.html">O.2. Default Roles Renamed to Predefined Roles</a></span></dt><dt><span class="sect1"><a href="pgxlogdump.html">O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code></a></span></dt><dt><span class="sect1"><a href="app-pgresetxlog.html">O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code></a></span></dt><dt><span class="sect1"><a href="app-pgreceivexlog.html">O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code></a></span></dt></dl></div><p>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="color-which.html" title="N.2. Configuring the Colors">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf">Next</a></td></tr><tr><td width="40%" align="left" valign="top">N.2. Configuring the Colors </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/appendixes.html b/doc/src/sgml/html/appendixes.html
new file mode 100644
index 0000000..9b2c6f1
--- /dev/null
+++ b/doc/src/sgml/html/appendixes.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part VIII. Appendixes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object" /><link rel="next" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part VIII. Appendixes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Next</a></td></tr></table><hr /></div><div class="part" id="APPENDIXES"><div class="titlepage"><div><div><h1 class="title">Part VIII. Appendixes</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="appendix"><a href="errcodes-appendix.html">A. <span class="productname">PostgreSQL</span> Error Codes</a></span></dt><dt><span class="appendix"><a href="datetime-appendix.html">B. Date/Time Support</a></span></dt><dd><dl><dt><span class="sect1"><a href="datetime-input-rules.html">B.1. Date/Time Input Interpretation</a></span></dt><dt><span class="sect1"><a href="datetime-invalid-input.html">B.2. Handling of Invalid or Ambiguous Timestamps</a></span></dt><dt><span class="sect1"><a href="datetime-keywords.html">B.3. Date/Time Key Words</a></span></dt><dt><span class="sect1"><a href="datetime-config-files.html">B.4. Date/Time Configuration Files</a></span></dt><dt><span class="sect1"><a href="datetime-posix-timezone-specs.html">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</a></span></dt><dt><span class="sect1"><a href="datetime-units-history.html">B.6. History of Units</a></span></dt><dt><span class="sect1"><a href="datetime-julian-dates.html">B.7. Julian Dates</a></span></dt></dl></dd><dt><span class="appendix"><a href="sql-keywords-appendix.html">C. <acronym class="acronym">SQL</acronym> Key Words</a></span></dt><dt><span class="appendix"><a href="features.html">D. SQL Conformance</a></span></dt><dd><dl><dt><span class="sect1"><a href="features-sql-standard.html">D.1. Supported Features</a></span></dt><dt><span class="sect1"><a href="unsupported-features-sql-standard.html">D.2. Unsupported Features</a></span></dt><dt><span class="sect1"><a href="xml-limits-conformance.html">D.3. XML Limits and Conformance to SQL/XML</a></span></dt></dl></dd><dt><span class="appendix"><a href="release.html">E. Release Notes</a></span></dt><dd><dl><dt><span class="sect1"><a href="release-15-5.html">E.1. Release 15.5</a></span></dt><dt><span class="sect1"><a href="release-15-4.html">E.2. Release 15.4</a></span></dt><dt><span class="sect1"><a href="release-15-3.html">E.3. Release 15.3</a></span></dt><dt><span class="sect1"><a href="release-15-2.html">E.4. Release 15.2</a></span></dt><dt><span class="sect1"><a href="release-15-1.html">E.5. Release 15.1</a></span></dt><dt><span class="sect1"><a href="release-15.html">E.6. Release 15</a></span></dt><dt><span class="sect1"><a href="release-prior.html">E.7. Prior Releases</a></span></dt></dl></dd><dt><span class="appendix"><a href="contrib.html">F. Additional Supplied Modules</a></span></dt><dd><dl><dt><span class="sect1"><a href="adminpack.html">F.1. adminpack</a></span></dt><dt><span class="sect1"><a href="amcheck.html">F.2. amcheck</a></span></dt><dt><span class="sect1"><a href="auth-delay.html">F.3. auth_delay</a></span></dt><dt><span class="sect1"><a href="auto-explain.html">F.4. auto_explain</a></span></dt><dt><span class="sect1"><a href="basebackup-to-shell.html">F.5. basebackup_to_shell</a></span></dt><dt><span class="sect1"><a href="basic-archive.html">F.6. basic_archive</a></span></dt><dt><span class="sect1"><a href="bloom.html">F.7. bloom</a></span></dt><dt><span class="sect1"><a href="btree-gin.html">F.8. btree_gin</a></span></dt><dt><span class="sect1"><a href="btree-gist.html">F.9. btree_gist</a></span></dt><dt><span class="sect1"><a href="citext.html">F.10. citext</a></span></dt><dt><span class="sect1"><a href="cube.html">F.11. cube</a></span></dt><dt><span class="sect1"><a href="dblink.html">F.12. dblink</a></span></dt><dt><span class="sect1"><a href="dict-int.html">F.13. dict_int</a></span></dt><dt><span class="sect1"><a href="dict-xsyn.html">F.14. dict_xsyn</a></span></dt><dt><span class="sect1"><a href="earthdistance.html">F.15. earthdistance</a></span></dt><dt><span class="sect1"><a href="file-fdw.html">F.16. file_fdw</a></span></dt><dt><span class="sect1"><a href="fuzzystrmatch.html">F.17. fuzzystrmatch</a></span></dt><dt><span class="sect1"><a href="hstore.html">F.18. hstore</a></span></dt><dt><span class="sect1"><a href="intagg.html">F.19. intagg</a></span></dt><dt><span class="sect1"><a href="intarray.html">F.20. intarray</a></span></dt><dt><span class="sect1"><a href="isn.html">F.21. isn</a></span></dt><dt><span class="sect1"><a href="lo.html">F.22. lo</a></span></dt><dt><span class="sect1"><a href="ltree.html">F.23. ltree</a></span></dt><dt><span class="sect1"><a href="oldsnapshot.html">F.24. old_snapshot</a></span></dt><dt><span class="sect1"><a href="pageinspect.html">F.25. pageinspect</a></span></dt><dt><span class="sect1"><a href="passwordcheck.html">F.26. passwordcheck</a></span></dt><dt><span class="sect1"><a href="pgbuffercache.html">F.27. pg_buffercache</a></span></dt><dt><span class="sect1"><a href="pgcrypto.html">F.28. pgcrypto</a></span></dt><dt><span class="sect1"><a href="pgfreespacemap.html">F.29. pg_freespacemap</a></span></dt><dt><span class="sect1"><a href="pgprewarm.html">F.30. pg_prewarm</a></span></dt><dt><span class="sect1"><a href="pgrowlocks.html">F.31. pgrowlocks</a></span></dt><dt><span class="sect1"><a href="pgstatstatements.html">F.32. pg_stat_statements</a></span></dt><dt><span class="sect1"><a href="pgstattuple.html">F.33. pgstattuple</a></span></dt><dt><span class="sect1"><a href="pgsurgery.html">F.34. pg_surgery</a></span></dt><dt><span class="sect1"><a href="pgtrgm.html">F.35. pg_trgm</a></span></dt><dt><span class="sect1"><a href="pgvisibility.html">F.36. pg_visibility</a></span></dt><dt><span class="sect1"><a href="pgwalinspect.html">F.37. pg_walinspect</a></span></dt><dt><span class="sect1"><a href="postgres-fdw.html">F.38. postgres_fdw</a></span></dt><dt><span class="sect1"><a href="seg.html">F.39. seg</a></span></dt><dt><span class="sect1"><a href="sepgsql.html">F.40. sepgsql</a></span></dt><dt><span class="sect1"><a href="contrib-spi.html">F.41. spi</a></span></dt><dt><span class="sect1"><a href="sslinfo.html">F.42. sslinfo</a></span></dt><dt><span class="sect1"><a href="tablefunc.html">F.43. tablefunc</a></span></dt><dt><span class="sect1"><a href="tcn.html">F.44. tcn</a></span></dt><dt><span class="sect1"><a href="test-decoding.html">F.45. test_decoding</a></span></dt><dt><span class="sect1"><a href="tsm-system-rows.html">F.46. tsm_system_rows</a></span></dt><dt><span class="sect1"><a href="tsm-system-time.html">F.47. tsm_system_time</a></span></dt><dt><span class="sect1"><a href="unaccent.html">F.48. unaccent</a></span></dt><dt><span class="sect1"><a href="uuid-ossp.html">F.49. uuid-ossp</a></span></dt><dt><span class="sect1"><a href="xml2.html">F.50. xml2</a></span></dt></dl></dd><dt><span class="appendix"><a href="contrib-prog.html">G. Additional Supplied Programs</a></span></dt><dd><dl><dt><span class="sect1"><a href="contrib-prog-client.html">G.1. Client Applications</a></span></dt><dt><span class="sect1"><a href="contrib-prog-server.html">G.2. Server Applications</a></span></dt></dl></dd><dt><span class="appendix"><a href="external-projects.html">H. External Projects</a></span></dt><dd><dl><dt><span class="sect1"><a href="external-interfaces.html">H.1. Client Interfaces</a></span></dt><dt><span class="sect1"><a href="external-admin-tools.html">H.2. Administration Tools</a></span></dt><dt><span class="sect1"><a href="external-pl.html">H.3. Procedural Languages</a></span></dt><dt><span class="sect1"><a href="external-extensions.html">H.4. Extensions</a></span></dt></dl></dd><dt><span class="appendix"><a href="sourcerepo.html">I. The Source Code Repository</a></span></dt><dd><dl><dt><span class="sect1"><a href="git.html">I.1. Getting the Source via <span class="productname">Git</span></a></span></dt></dl></dd><dt><span class="appendix"><a href="docguide.html">J. Documentation</a></span></dt><dd><dl><dt><span class="sect1"><a href="docguide-docbook.html">J.1. DocBook</a></span></dt><dt><span class="sect1"><a href="docguide-toolsets.html">J.2. Tool Sets</a></span></dt><dt><span class="sect1"><a href="docguide-build.html">J.3. Building the Documentation</a></span></dt><dt><span class="sect1"><a href="docguide-authoring.html">J.4. Documentation Authoring</a></span></dt><dt><span class="sect1"><a href="docguide-style.html">J.5. Style Guide</a></span></dt></dl></dd><dt><span class="appendix"><a href="limits.html">K. <span class="productname">PostgreSQL</span> Limits</a></span></dt><dt><span class="appendix"><a href="acronyms.html">L. Acronyms</a></span></dt><dt><span class="appendix"><a href="glossary.html">M. Glossary</a></span></dt><dt><span class="appendix"><a href="color.html">N. Color Support</a></span></dt><dd><dl><dt><span class="sect1"><a href="color-when.html">N.1. When Color is Used</a></span></dt><dt><span class="sect1"><a href="color-which.html">N.2. Configuring the Colors</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix-obsolete.html">O. Obsolete or Renamed Features</a></span></dt><dd><dl><dt><span class="sect1"><a href="recovery-config.html">O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code></a></span></dt><dt><span class="sect1"><a href="default-roles.html">O.2. Default Roles Renamed to Predefined Roles</a></span></dt><dt><span class="sect1"><a href="pgxlogdump.html">O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code></a></span></dt><dt><span class="sect1"><a href="app-pgresetxlog.html">O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code></a></span></dt><dt><span class="sect1"><a href="app-pgreceivexlog.html">O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code></a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">76.3. Backup Manifest WAL Range Object </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix A. <span class="productname">PostgreSQL</span> Error Codes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/applevel-consistency.html b/doc/src/sgml/html/applevel-consistency.html
new file mode 100644
index 0000000..4c502b9
--- /dev/null
+++ b/doc/src/sgml/html/applevel-consistency.html
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.4. Data Consistency Checks at the Application Level</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="explicit-locking.html" title="13.3. Explicit Locking" /><link rel="next" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.4. Data Consistency Checks at the Application Level</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="explicit-locking.html" title="13.3. Explicit Locking">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling">Next</a></td></tr></table><hr /></div><div class="sect1" id="APPLEVEL-CONSISTENCY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.4. Data Consistency Checks at the Application Level</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="applevel-consistency.html#SERIALIZABLE-CONSISTENCY">13.4.1. Enforcing Consistency with Serializable Transactions</a></span></dt><dt><span class="sect2"><a href="applevel-consistency.html#NON-SERIALIZABLE-CONSISTENCY">13.4.2. Enforcing Consistency with Explicit Blocking Locks</a></span></dt></dl></div><p>
+ It is very difficult to enforce business rules regarding data integrity
+ using Read Committed transactions because the view of the data is
+ shifting with each statement, and even a single statement may not
+ restrict itself to the statement's snapshot if a write conflict occurs.
+ </p><p>
+ While a Repeatable Read transaction has a stable view of the data
+ throughout its execution, there is a subtle issue with using
+ <acronym class="acronym">MVCC</acronym> snapshots for data consistency checks, involving
+ something known as <em class="firstterm">read/write conflicts</em>.
+ If one transaction writes data and a concurrent transaction attempts
+ to read the same data (whether before or after the write), it cannot
+ see the work of the other transaction. The reader then appears to have
+ executed first regardless of which started first or which committed
+ first. If that is as far as it goes, there is no problem, but
+ if the reader also writes data which is read by a concurrent transaction
+ there is now a transaction which appears to have run before either of
+ the previously mentioned transactions. If the transaction which appears
+ to have executed last actually commits first, it is very easy for a
+ cycle to appear in a graph of the order of execution of the transactions.
+ When such a cycle appears, integrity checks will not work correctly
+ without some help.
+ </p><p>
+ As mentioned in <a class="xref" href="transaction-iso.html#XACT-SERIALIZABLE" title="13.2.3. Serializable Isolation Level">Section 13.2.3</a>, Serializable
+ transactions are just Repeatable Read transactions which add
+ nonblocking monitoring for dangerous patterns of read/write conflicts.
+ When a pattern is detected which could cause a cycle in the apparent
+ order of execution, one of the transactions involved is rolled back to
+ break the cycle.
+ </p><div class="sect2" id="SERIALIZABLE-CONSISTENCY"><div class="titlepage"><div><div><h3 class="title">13.4.1. Enforcing Consistency with Serializable Transactions</h3></div></div></div><p>
+ If the Serializable transaction isolation level is used for all writes
+ and for all reads which need a consistent view of the data, no other
+ effort is required to ensure consistency. Software from other
+ environments which is written to use serializable transactions to
+ ensure consistency should <span class="quote">“<span class="quote">just work</span>”</span> in this regard in
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ When using this technique, it will avoid creating an unnecessary burden
+ for application programmers if the application software goes through a
+ framework which automatically retries transactions which are rolled
+ back with a serialization failure. It may be a good idea to set
+ <code class="literal">default_transaction_isolation</code> to <code class="literal">serializable</code>.
+ It would also be wise to take some action to ensure that no other
+ transaction isolation level is used, either inadvertently or to
+ subvert integrity checks, through checks of the transaction isolation
+ level in triggers.
+ </p><p>
+ See <a class="xref" href="transaction-iso.html#XACT-SERIALIZABLE" title="13.2.3. Serializable Isolation Level">Section 13.2.3</a> for performance suggestions.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ This level of integrity protection using Serializable transactions
+ does not yet extend to hot standby mode (<a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a>).
+ Because of that, those using hot standby may want to use Repeatable
+ Read and explicit locking on the primary.
+ </p></div></div><div class="sect2" id="NON-SERIALIZABLE-CONSISTENCY"><div class="titlepage"><div><div><h3 class="title">13.4.2. Enforcing Consistency with Explicit Blocking Locks</h3></div></div></div><p>
+ When non-serializable writes are possible,
+ to ensure the current validity of a row and protect it against
+ concurrent updates one must use <code class="command">SELECT FOR UPDATE</code>,
+ <code class="command">SELECT FOR SHARE</code>, or an appropriate <code class="command">LOCK
+ TABLE</code> statement. (<code class="command">SELECT FOR UPDATE</code>
+ and <code class="command">SELECT FOR SHARE</code> lock just the
+ returned rows against concurrent updates, while <code class="command">LOCK
+ TABLE</code> locks the whole table.) This should be taken into
+ account when porting applications to
+ <span class="productname">PostgreSQL</span> from other environments.
+ </p><p>
+ Also of note to those converting from other environments is the fact
+ that <code class="command">SELECT FOR UPDATE</code> does not ensure that a
+ concurrent transaction will not update or delete a selected row.
+ To do that in <span class="productname">PostgreSQL</span> you must actually
+ update the row, even if no values need to be changed.
+ <code class="command">SELECT FOR UPDATE</code> <span class="emphasis"><em>temporarily blocks</em></span>
+ other transactions from acquiring the same lock or executing an
+ <code class="command">UPDATE</code> or <code class="command">DELETE</code> which would
+ affect the locked row, but once the transaction holding this lock
+ commits or rolls back, a blocked transaction will proceed with the
+ conflicting operation unless an actual <code class="command">UPDATE</code> of
+ the row was performed while the lock was held.
+ </p><p>
+ Global validity checks require extra thought under
+ non-serializable <acronym class="acronym">MVCC</acronym>.
+ For example, a banking application might wish to check that the sum of
+ all credits in one table equals the sum of debits in another table,
+ when both tables are being actively updated. Comparing the results of two
+ successive <code class="literal">SELECT sum(...)</code> commands will not work reliably in
+ Read Committed mode, since the second query will likely include the results
+ of transactions not counted by the first. Doing the two sums in a
+ single repeatable read transaction will give an accurate picture of only the
+ effects of transactions that committed before the repeatable read transaction
+ started — but one might legitimately wonder whether the answer is still
+ relevant by the time it is delivered. If the repeatable read transaction
+ itself applied some changes before trying to make the consistency check,
+ the usefulness of the check becomes even more debatable, since now it
+ includes some but not all post-transaction-start changes. In such cases
+ a careful person might wish to lock all tables needed for the check,
+ in order to get an indisputable picture of current reality. A
+ <code class="literal">SHARE</code> mode (or higher) lock guarantees that there are no
+ uncommitted changes in the locked table, other than those of the current
+ transaction.
+ </p><p>
+ Note also that if one is relying on explicit locking to prevent concurrent
+ changes, one should either use Read Committed mode, or in Repeatable Read
+ mode be careful to obtain
+ locks before performing queries. A lock obtained by a
+ repeatable read transaction guarantees that no other transactions modifying
+ the table are still running, but if the snapshot seen by the
+ transaction predates obtaining the lock, it might predate some now-committed
+ changes in the table. A repeatable read transaction's snapshot is actually
+ frozen at the start of its first query or data-modification command
+ (<code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>, or
+ <code class="literal">MERGE</code>), so it is possible to obtain locks explicitly
+ before the snapshot is frozen.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="explicit-locking.html" title="13.3. Explicit Locking">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.3. Explicit Locking </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.5. Serialization Failure Handling</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/archive-module-callbacks.html b/doc/src/sgml/html/archive-module-callbacks.html
new file mode 100644
index 0000000..7b64ad3
--- /dev/null
+++ b/doc/src/sgml/html/archive-module-callbacks.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>51.2. Archive Module Callbacks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="archive-module-init.html" title="51.1. Initialization Functions" /><link rel="next" href="reference.html" title="Part VI. Reference" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">51.2. Archive Module Callbacks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="archive-module-init.html" title="51.1. Initialization Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="archive-modules.html" title="Chapter 51. Archive Modules">Up</a></td><th width="60%" align="center">Chapter 51. Archive Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="reference.html" title="Part VI. Reference">Next</a></td></tr></table><hr /></div><div class="sect1" id="ARCHIVE-MODULE-CALLBACKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">51.2. Archive Module Callbacks</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-CHECK">51.2.1. Check Callback</a></span></dt><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-ARCHIVE">51.2.2. Archive Callback</a></span></dt><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-SHUTDOWN">51.2.3. Shutdown Callback</a></span></dt></dl></div><p>
+ The archive callbacks define the actual archiving behavior of the module.
+ The server will call them as required to process each individual WAL file.
+ </p><div class="sect2" id="ARCHIVE-MODULE-CHECK"><div class="titlepage"><div><div><h3 class="title">51.2.1. Check Callback</h3></div></div></div><p>
+ The <code class="function">check_configured_cb</code> callback is called to determine
+ whether the module is fully configured and ready to accept WAL files (e.g.,
+ its configuration parameters are set to valid values). If no
+ <code class="function">check_configured_cb</code> is defined, the server always
+ assumes the module is configured.
+
+</p><pre class="programlisting">
+typedef bool (*ArchiveCheckConfiguredCB) (void);
+</pre><p>
+
+ If <code class="literal">true</code> is returned, the server will proceed with
+ archiving the file by calling the <code class="function">archive_file_cb</code>
+ callback. If <code class="literal">false</code> is returned, archiving will not
+ proceed, and the archiver will emit the following message to the server log:
+</p><pre class="screen">
+WARNING: archive_mode enabled, yet archiving is not configured
+</pre><p>
+ In the latter case, the server will periodically call this function, and
+ archiving will proceed only when it returns <code class="literal">true</code>.
+ </p></div><div class="sect2" id="ARCHIVE-MODULE-ARCHIVE"><div class="titlepage"><div><div><h3 class="title">51.2.2. Archive Callback</h3></div></div></div><p>
+ The <code class="function">archive_file_cb</code> callback is called to archive a
+ single WAL file.
+
+</p><pre class="programlisting">
+typedef bool (*ArchiveFileCB) (const char *file, const char *path);
+</pre><p>
+
+ If <code class="literal">true</code> is returned, the server proceeds as if the file
+ was successfully archived, which may include recycling or removing the
+ original WAL file. If <code class="literal">false</code> is returned, the server will
+ keep the original WAL file and retry archiving later.
+ <em class="replaceable"><code>file</code></em> will contain just the file name of the WAL
+ file to archive, while <em class="replaceable"><code>path</code></em> contains the full
+ path of the WAL file (including the file name).
+ </p></div><div class="sect2" id="ARCHIVE-MODULE-SHUTDOWN"><div class="titlepage"><div><div><h3 class="title">51.2.3. Shutdown Callback</h3></div></div></div><p>
+ The <code class="function">shutdown_cb</code> callback is called when the archiver
+ process exits (e.g., after an error) or the value of
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> changes. If no
+ <code class="function">shutdown_cb</code> is defined, no special action is taken in
+ these situations.
+
+</p><pre class="programlisting">
+typedef void (*ArchiveShutdownCB) (void);
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="archive-module-init.html" title="51.1. Initialization Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="archive-modules.html" title="Chapter 51. Archive Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="reference.html" title="Part VI. Reference">Next</a></td></tr><tr><td width="40%" align="left" valign="top">51.1. Initialization Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part VI. Reference</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/archive-module-init.html b/doc/src/sgml/html/archive-module-init.html
new file mode 100644
index 0000000..1486928
--- /dev/null
+++ b/doc/src/sgml/html/archive-module-init.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>51.1. Initialization Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="archive-modules.html" title="Chapter 51. Archive Modules" /><link rel="next" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">51.1. Initialization Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="archive-modules.html" title="Chapter 51. Archive Modules">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="archive-modules.html" title="Chapter 51. Archive Modules">Up</a></td><th width="60%" align="center">Chapter 51. Archive Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks">Next</a></td></tr></table><hr /></div><div class="sect1" id="ARCHIVE-MODULE-INIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">51.1. Initialization Functions</h2></div></div></div><a id="id-1.8.16.7.2" class="indexterm"></a><p>
+ An archive library is loaded by dynamically loading a shared library with the
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a>'s name as the library base name. The
+ normal library search path is used to locate the library. To provide the
+ required archive module callbacks and to indicate that the library is
+ actually an archive module, it needs to provide a function named
+ <code class="function">_PG_archive_module_init</code>. This function is passed a
+ struct that needs to be filled with the callback function pointers for
+ individual actions.
+
+</p><pre class="programlisting">
+typedef struct ArchiveModuleCallbacks
+{
+ ArchiveCheckConfiguredCB check_configured_cb;
+ ArchiveFileCB archive_file_cb;
+ ArchiveShutdownCB shutdown_cb;
+} ArchiveModuleCallbacks;
+typedef void (*ArchiveModuleInit) (struct ArchiveModuleCallbacks *cb);
+</pre><p>
+
+ Only the <code class="function">archive_file_cb</code> callback is required. The
+ others are optional.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="archive-modules.html" title="Chapter 51. Archive Modules">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="archive-modules.html" title="Chapter 51. Archive Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 51. Archive Modules </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 51.2. Archive Module Callbacks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/archive-modules.html b/doc/src/sgml/html/archive-modules.html
new file mode 100644
index 0000000..2431fa9
--- /dev/null
+++ b/doc/src/sgml/html/archive-modules.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 51. Archive Modules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking" /><link rel="next" href="archive-module-init.html" title="51.1. Initialization Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 51. Archive Modules</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="archive-module-init.html" title="51.1. Initialization Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="ARCHIVE-MODULES"><div class="titlepage"><div><div><h2 class="title">Chapter 51. Archive Modules</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="archive-module-init.html">51.1. Initialization Functions</a></span></dt><dt><span class="sect1"><a href="archive-module-callbacks.html">51.2. Archive Module Callbacks</a></span></dt><dd><dl><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-CHECK">51.2.1. Check Callback</a></span></dt><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-ARCHIVE">51.2.2. Archive Callback</a></span></dt><dt><span class="sect2"><a href="archive-module-callbacks.html#ARCHIVE-MODULE-SHUTDOWN">51.2.3. Shutdown Callback</a></span></dt></dl></dd></dl></div><a id="id-1.8.16.2" class="indexterm"></a><p>
+ PostgreSQL provides infrastructure to create custom modules for continuous
+ archiving (see <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>). While archiving via
+ a shell command (i.e., <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a>) is much
+ simpler, a custom archive module will often be considerably more robust and
+ performant.
+ </p><p>
+ When a custom <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> is configured, PostgreSQL
+ will submit completed WAL files to the module, and the server will avoid
+ recycling or removing these WAL files until the module indicates that the files
+ were successfully archived. It is ultimately up to the module to decide what
+ to do with each WAL file, but many recommendations are listed at
+ <a class="xref" href="continuous-archiving.html#BACKUP-ARCHIVING-WAL" title="26.3.1. Setting Up WAL Archiving">Section 26.3.1</a>.
+ </p><p>
+ Archiving modules must at least consist of an initialization function (see
+ <a class="xref" href="archive-module-init.html" title="51.1. Initialization Functions">Section 51.1</a>) and the required callbacks (see
+ <a class="xref" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks">Section 51.2</a>). However, archive modules are
+ also permitted to do much more (e.g., declare GUCs and register background
+ workers).
+ </p><p>
+ The <code class="filename">contrib/basic_archive</code> module contains a working
+ example, which demonstrates some useful techniques.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="archive-module-init.html" title="51.1. Initialization Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 50. Replication Progress Tracking </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 51.1. Initialization Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/arrays.html b/doc/src/sgml/html/arrays.html
new file mode 100644
index 0000000..8795041
--- /dev/null
+++ b/doc/src/sgml/html/arrays.html
@@ -0,0 +1,647 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.15. Arrays</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-json.html" title="8.14. JSON Types" /><link rel="next" href="rowtypes.html" title="8.16. Composite Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.15. Arrays</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-json.html" title="8.14. JSON Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rowtypes.html" title="8.16. Composite Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="ARRAYS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.15. Arrays</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="arrays.html#ARRAYS-DECLARATION">8.15.1. Declaration of Array Types</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-INPUT">8.15.2. Array Value Input</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-ACCESSING">8.15.3. Accessing Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-MODIFYING">8.15.4. Modifying Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-SEARCHING">8.15.5. Searching in Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-IO">8.15.6. Array Input and Output Syntax</a></span></dt></dl></div><a id="id-1.5.7.23.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> allows columns of a table to be
+ defined as variable-length multidimensional arrays. Arrays of any
+ built-in or user-defined base type, enum type, composite type, range type,
+ or domain can be created.
+ </p><div class="sect2" id="ARRAYS-DECLARATION"><div class="titlepage"><div><div><h3 class="title">8.15.1. Declaration of Array Types</h3></div></div></div><a id="id-1.5.7.23.4.2" class="indexterm"></a><p>
+ To illustrate the use of array types, we create this table:
+</p><pre class="programlisting">
+CREATE TABLE sal_emp (
+ name text,
+ pay_by_quarter integer[],
+ schedule text[][]
+);
+</pre><p>
+ As shown, an array data type is named by appending square brackets
+ (<code class="literal">[]</code>) to the data type name of the array elements. The
+ above command will create a table named
+ <code class="structname">sal_emp</code> with a column of type
+ <code class="type">text</code> (<code class="structfield">name</code>), a
+ one-dimensional array of type <code class="type">integer</code>
+ (<code class="structfield">pay_by_quarter</code>), which represents the
+ employee's salary by quarter, and a two-dimensional array of
+ <code class="type">text</code> (<code class="structfield">schedule</code>), which
+ represents the employee's weekly schedule.
+ </p><p>
+ The syntax for <code class="command">CREATE TABLE</code> allows the exact size of
+ arrays to be specified, for example:
+
+</p><pre class="programlisting">
+CREATE TABLE tictactoe (
+ squares integer[3][3]
+);
+</pre><p>
+
+ However, the current implementation ignores any supplied array size
+ limits, i.e., the behavior is the same as for arrays of unspecified
+ length.
+ </p><p>
+ The current implementation does not enforce the declared
+ number of dimensions either. Arrays of a particular element type are
+ all considered to be of the same type, regardless of size or number
+ of dimensions. So, declaring the array size or number of dimensions in
+ <code class="command">CREATE TABLE</code> is simply documentation; it does not
+ affect run-time behavior.
+ </p><p>
+ An alternative syntax, which conforms to the SQL standard by using
+ the keyword <code class="literal">ARRAY</code>, can be used for one-dimensional arrays.
+ <code class="structfield">pay_by_quarter</code> could have been defined
+ as:
+</p><pre class="programlisting">
+ pay_by_quarter integer ARRAY[4],
+</pre><p>
+ Or, if no array size is to be specified:
+</p><pre class="programlisting">
+ pay_by_quarter integer ARRAY,
+</pre><p>
+ As before, however, <span class="productname">PostgreSQL</span> does not enforce the
+ size restriction in any case.
+ </p></div><div class="sect2" id="ARRAYS-INPUT"><div class="titlepage"><div><div><h3 class="title">8.15.2. Array Value Input</h3></div></div></div><a id="id-1.5.7.23.5.2" class="indexterm"></a><p>
+ To write an array value as a literal constant, enclose the element
+ values within curly braces and separate them by commas. (If you
+ know C, this is not unlike the C syntax for initializing
+ structures.) You can put double quotes around any element value,
+ and must do so if it contains commas or curly braces. (More
+ details appear below.) Thus, the general format of an array
+ constant is the following:
+</p><pre class="synopsis">
+'{ <em class="replaceable"><code>val1</code></em> <em class="replaceable"><code>delim</code></em> <em class="replaceable"><code>val2</code></em> <em class="replaceable"><code>delim</code></em> ... }'
+</pre><p>
+ where <em class="replaceable"><code>delim</code></em> is the delimiter character
+ for the type, as recorded in its <code class="literal">pg_type</code> entry.
+ Among the standard data types provided in the
+ <span class="productname">PostgreSQL</span> distribution, all use a comma
+ (<code class="literal">,</code>), except for type <code class="type">box</code> which uses a semicolon
+ (<code class="literal">;</code>). Each <em class="replaceable"><code>val</code></em> is
+ either a constant of the array element type, or a subarray. An example
+ of an array constant is:
+</p><pre class="programlisting">
+'{{1,2,3},{4,5,6},{7,8,9}}'
+</pre><p>
+ This constant is a two-dimensional, 3-by-3 array consisting of
+ three subarrays of integers.
+ </p><p>
+ To set an element of an array constant to NULL, write <code class="literal">NULL</code>
+ for the element value. (Any upper- or lower-case variant of
+ <code class="literal">NULL</code> will do.) If you want an actual string value
+ <span class="quote">“<span class="quote">NULL</span>”</span>, you must put double quotes around it.
+ </p><p>
+ (These kinds of array constants are actually only a special case of
+ the generic type constants discussed in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC" title="4.1.2.7. Constants of Other Types">Section 4.1.2.7</a>. The constant is initially
+ treated as a string and passed to the array input conversion
+ routine. An explicit type specification might be necessary.)
+ </p><p>
+ Now we can show some <code class="command">INSERT</code> statements:
+
+</p><pre class="programlisting">
+INSERT INTO sal_emp
+ VALUES ('Bill',
+ '{10000, 10000, 10000, 10000}',
+ '{{"meeting", "lunch"}, {"training", "presentation"}}');
+
+INSERT INTO sal_emp
+ VALUES ('Carol',
+ '{20000, 25000, 25000, 25000}',
+ '{{"breakfast", "consulting"}, {"meeting", "lunch"}}');
+</pre><p>
+ </p><p>
+ The result of the previous two inserts looks like this:
+
+</p><pre class="programlisting">
+SELECT * FROM sal_emp;
+ name | pay_by_quarter | schedule
+-------+---------------------------+-------------------------------------------
+ Bill | {10000,10000,10000,10000} | {{meeting,lunch},{training,presentation}}
+ Carol | {20000,25000,25000,25000} | {{breakfast,consulting},{meeting,lunch}}
+(2 rows)
+</pre><p>
+ </p><p>
+ Multidimensional arrays must have matching extents for each
+ dimension. A mismatch causes an error, for example:
+
+</p><pre class="programlisting">
+INSERT INTO sal_emp
+ VALUES ('Bill',
+ '{10000, 10000, 10000, 10000}',
+ '{{"meeting", "lunch"}, {"meeting"}}');
+ERROR: multidimensional arrays must have array expressions with matching dimensions
+</pre><p>
+ </p><p>
+ The <code class="literal">ARRAY</code> constructor syntax can also be used:
+</p><pre class="programlisting">
+INSERT INTO sal_emp
+ VALUES ('Bill',
+ ARRAY[10000, 10000, 10000, 10000],
+ ARRAY[['meeting', 'lunch'], ['training', 'presentation']]);
+
+INSERT INTO sal_emp
+ VALUES ('Carol',
+ ARRAY[20000, 25000, 25000, 25000],
+ ARRAY[['breakfast', 'consulting'], ['meeting', 'lunch']]);
+</pre><p>
+ Notice that the array elements are ordinary SQL constants or
+ expressions; for instance, string literals are single quoted, instead of
+ double quoted as they would be in an array literal. The <code class="literal">ARRAY</code>
+ constructor syntax is discussed in more detail in
+ <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS" title="4.2.12. Array Constructors">Section 4.2.12</a>.
+ </p></div><div class="sect2" id="ARRAYS-ACCESSING"><div class="titlepage"><div><div><h3 class="title">8.15.3. Accessing Arrays</h3></div></div></div><a id="id-1.5.7.23.6.2" class="indexterm"></a><p>
+ Now, we can run some queries on the table.
+ First, we show how to access a single element of an array.
+ This query retrieves the names of the employees whose pay changed in
+ the second quarter:
+
+</p><pre class="programlisting">
+SELECT name FROM sal_emp WHERE pay_by_quarter[1] &lt;&gt; pay_by_quarter[2];
+
+ name
+-------
+ Carol
+(1 row)
+</pre><p>
+
+ The array subscript numbers are written within square brackets.
+ By default <span class="productname">PostgreSQL</span> uses a
+ one-based numbering convention for arrays, that is,
+ an array of <em class="replaceable"><code>n</code></em> elements starts with <code class="literal">array[1]</code> and
+ ends with <code class="literal">array[<em class="replaceable"><code>n</code></em>]</code>.
+ </p><p>
+ This query retrieves the third quarter pay of all employees:
+
+</p><pre class="programlisting">
+SELECT pay_by_quarter[3] FROM sal_emp;
+
+ pay_by_quarter
+----------------
+ 10000
+ 25000
+(2 rows)
+</pre><p>
+ </p><p>
+ We can also access arbitrary rectangular slices of an array, or
+ subarrays. An array slice is denoted by writing
+ <code class="literal"><em class="replaceable"><code>lower-bound</code></em>:<em class="replaceable"><code>upper-bound</code></em></code>
+ for one or more array dimensions. For example, this query retrieves the first
+ item on Bill's schedule for the first two days of the week:
+
+</p><pre class="programlisting">
+SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
+
+ schedule
+------------------------
+ {{meeting},{training}}
+(1 row)
+</pre><p>
+
+ If any dimension is written as a slice, i.e., contains a colon, then all
+ dimensions are treated as slices. Any dimension that has only a single
+ number (no colon) is treated as being from 1
+ to the number specified. For example, <code class="literal">[2]</code> is treated as
+ <code class="literal">[1:2]</code>, as in this example:
+
+</p><pre class="programlisting">
+SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
+
+ schedule
+-------------------------------------------
+ {{meeting,lunch},{training,presentation}}
+(1 row)
+</pre><p>
+
+ To avoid confusion with the non-slice case, it's best to use slice syntax
+ for all dimensions, e.g., <code class="literal">[1:2][1:1]</code>, not <code class="literal">[2][1:1]</code>.
+ </p><p>
+ It is possible to omit the <em class="replaceable"><code>lower-bound</code></em> and/or
+ <em class="replaceable"><code>upper-bound</code></em> of a slice specifier; the missing
+ bound is replaced by the lower or upper limit of the array's subscripts.
+ For example:
+
+</p><pre class="programlisting">
+SELECT schedule[:2][2:] FROM sal_emp WHERE name = 'Bill';
+
+ schedule
+------------------------
+ {{lunch},{presentation}}
+(1 row)
+
+SELECT schedule[:][1:1] FROM sal_emp WHERE name = 'Bill';
+
+ schedule
+------------------------
+ {{meeting},{training}}
+(1 row)
+</pre><p>
+ </p><p>
+ An array subscript expression will return null if either the array itself or
+ any of the subscript expressions are null. Also, null is returned if a
+ subscript is outside the array bounds (this case does not raise an error).
+ For example, if <code class="literal">schedule</code>
+ currently has the dimensions <code class="literal">[1:3][1:2]</code> then referencing
+ <code class="literal">schedule[3][3]</code> yields NULL. Similarly, an array reference
+ with the wrong number of subscripts yields a null rather than an error.
+ </p><p>
+ An array slice expression likewise yields null if the array itself or
+ any of the subscript expressions are null. However, in other
+ cases such as selecting an array slice that
+ is completely outside the current array bounds, a slice expression
+ yields an empty (zero-dimensional) array instead of null. (This
+ does not match non-slice behavior and is done for historical reasons.)
+ If the requested slice partially overlaps the array bounds, then it
+ is silently reduced to just the overlapping region instead of
+ returning null.
+ </p><p>
+ The current dimensions of any array value can be retrieved with the
+ <code class="function">array_dims</code> function:
+
+</p><pre class="programlisting">
+SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol';
+
+ array_dims
+------------
+ [1:2][1:2]
+(1 row)
+</pre><p>
+
+ <code class="function">array_dims</code> produces a <code class="type">text</code> result,
+ which is convenient for people to read but perhaps inconvenient
+ for programs. Dimensions can also be retrieved with
+ <code class="function">array_upper</code> and <code class="function">array_lower</code>,
+ which return the upper and lower bound of a
+ specified array dimension, respectively:
+
+</p><pre class="programlisting">
+SELECT array_upper(schedule, 1) FROM sal_emp WHERE name = 'Carol';
+
+ array_upper
+-------------
+ 2
+(1 row)
+</pre><p>
+
+ <code class="function">array_length</code> will return the length of a specified
+ array dimension:
+
+</p><pre class="programlisting">
+SELECT array_length(schedule, 1) FROM sal_emp WHERE name = 'Carol';
+
+ array_length
+--------------
+ 2
+(1 row)
+</pre><p>
+
+ <code class="function">cardinality</code> returns the total number of elements in an
+ array across all dimensions. It is effectively the number of rows a call to
+ <code class="function">unnest</code> would yield:
+
+</p><pre class="programlisting">
+SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol';
+
+ cardinality
+-------------
+ 4
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="ARRAYS-MODIFYING"><div class="titlepage"><div><div><h3 class="title">8.15.4. Modifying Arrays</h3></div></div></div><a id="id-1.5.7.23.7.2" class="indexterm"></a><p>
+ An array value can be replaced completely:
+
+</p><pre class="programlisting">
+UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}'
+ WHERE name = 'Carol';
+</pre><p>
+
+ or using the <code class="literal">ARRAY</code> expression syntax:
+
+</p><pre class="programlisting">
+UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000]
+ WHERE name = 'Carol';
+</pre><p>
+
+ An array can also be updated at a single element:
+
+</p><pre class="programlisting">
+UPDATE sal_emp SET pay_by_quarter[4] = 15000
+ WHERE name = 'Bill';
+</pre><p>
+
+ or updated in a slice:
+
+</p><pre class="programlisting">
+UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}'
+ WHERE name = 'Carol';
+</pre><p>
+
+ The slice syntaxes with omitted <em class="replaceable"><code>lower-bound</code></em> and/or
+ <em class="replaceable"><code>upper-bound</code></em> can be used too, but only when
+ updating an array value that is not NULL or zero-dimensional (otherwise,
+ there is no existing subscript limit to substitute).
+ </p><p>
+ A stored array value can be enlarged by assigning to elements not already
+ present. Any positions between those previously present and the newly
+ assigned elements will be filled with nulls. For example, if array
+ <code class="literal">myarray</code> currently has 4 elements, it will have six
+ elements after an update that assigns to <code class="literal">myarray[6]</code>;
+ <code class="literal">myarray[5]</code> will contain null.
+ Currently, enlargement in this fashion is only allowed for one-dimensional
+ arrays, not multidimensional arrays.
+ </p><p>
+ Subscripted assignment allows creation of arrays that do not use one-based
+ subscripts. For example one might assign to <code class="literal">myarray[-2:7]</code> to
+ create an array with subscript values from -2 to 7.
+ </p><p>
+ New array values can also be constructed using the concatenation operator,
+ <code class="literal">||</code>:
+</p><pre class="programlisting">
+SELECT ARRAY[1,2] || ARRAY[3,4];
+ ?column?
+-----------
+ {1,2,3,4}
+(1 row)
+
+SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
+ ?column?
+---------------------
+ {{5,6},{1,2},{3,4}}
+(1 row)
+</pre><p>
+ </p><p>
+ The concatenation operator allows a single element to be pushed onto the
+ beginning or end of a one-dimensional array. It also accepts two
+ <em class="replaceable"><code>N</code></em>-dimensional arrays, or an <em class="replaceable"><code>N</code></em>-dimensional
+ and an <em class="replaceable"><code>N+1</code></em>-dimensional array.
+ </p><p>
+ When a single element is pushed onto either the beginning or end of a
+ one-dimensional array, the result is an array with the same lower bound
+ subscript as the array operand. For example:
+</p><pre class="programlisting">
+SELECT array_dims(1 || '[0:1]={2,3}'::int[]);
+ array_dims
+------------
+ [0:2]
+(1 row)
+
+SELECT array_dims(ARRAY[1,2] || 3);
+ array_dims
+------------
+ [1:3]
+(1 row)
+</pre><p>
+ </p><p>
+ When two arrays with an equal number of dimensions are concatenated, the
+ result retains the lower bound subscript of the left-hand operand's outer
+ dimension. The result is an array comprising every element of the left-hand
+ operand followed by every element of the right-hand operand. For example:
+</p><pre class="programlisting">
+SELECT array_dims(ARRAY[1,2] || ARRAY[3,4,5]);
+ array_dims
+------------
+ [1:5]
+(1 row)
+
+SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
+ array_dims
+------------
+ [1:5][1:2]
+(1 row)
+</pre><p>
+ </p><p>
+ When an <em class="replaceable"><code>N</code></em>-dimensional array is pushed onto the beginning
+ or end of an <em class="replaceable"><code>N+1</code></em>-dimensional array, the result is
+ analogous to the element-array case above. Each <em class="replaceable"><code>N</code></em>-dimensional
+ sub-array is essentially an element of the <em class="replaceable"><code>N+1</code></em>-dimensional
+ array's outer dimension. For example:
+</p><pre class="programlisting">
+SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]);
+ array_dims
+------------
+ [1:3][1:2]
+(1 row)
+</pre><p>
+ </p><p>
+ An array can also be constructed by using the functions
+ <code class="function">array_prepend</code>, <code class="function">array_append</code>,
+ or <code class="function">array_cat</code>. The first two only support one-dimensional
+ arrays, but <code class="function">array_cat</code> supports multidimensional arrays.
+ Some examples:
+
+</p><pre class="programlisting">
+SELECT array_prepend(1, ARRAY[2,3]);
+ array_prepend
+---------------
+ {1,2,3}
+(1 row)
+
+SELECT array_append(ARRAY[1,2], 3);
+ array_append
+--------------
+ {1,2,3}
+(1 row)
+
+SELECT array_cat(ARRAY[1,2], ARRAY[3,4]);
+ array_cat
+-----------
+ {1,2,3,4}
+(1 row)
+
+SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]);
+ array_cat
+---------------------
+ {{1,2},{3,4},{5,6}}
+(1 row)
+
+SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]);
+ array_cat
+---------------------
+ {{5,6},{1,2},{3,4}}
+</pre><p>
+ </p><p>
+ In simple cases, the concatenation operator discussed above is preferred
+ over direct use of these functions. However, because the concatenation
+ operator is overloaded to serve all three cases, there are situations where
+ use of one of the functions is helpful to avoid ambiguity. For example
+ consider:
+
+</p><pre class="programlisting">
+SELECT ARRAY[1, 2] || '{3, 4}'; -- the untyped literal is taken as an array
+ ?column?
+-----------
+ {1,2,3,4}
+
+SELECT ARRAY[1, 2] || '7'; -- so is this one
+ERROR: malformed array literal: "7"
+
+SELECT ARRAY[1, 2] || NULL; -- so is an undecorated NULL
+ ?column?
+----------
+ {1,2}
+(1 row)
+
+SELECT array_append(ARRAY[1, 2], NULL); -- this might have been meant
+ array_append
+--------------
+ {1,2,NULL}
+</pre><p>
+
+ In the examples above, the parser sees an integer array on one side of the
+ concatenation operator, and a constant of undetermined type on the other.
+ The heuristic it uses to resolve the constant's type is to assume it's of
+ the same type as the operator's other input — in this case,
+ integer array. So the concatenation operator is presumed to
+ represent <code class="function">array_cat</code>, not <code class="function">array_append</code>. When
+ that's the wrong choice, it could be fixed by casting the constant to the
+ array's element type; but explicit use of <code class="function">array_append</code> might
+ be a preferable solution.
+ </p></div><div class="sect2" id="ARRAYS-SEARCHING"><div class="titlepage"><div><div><h3 class="title">8.15.5. Searching in Arrays</h3></div></div></div><a id="id-1.5.7.23.8.2" class="indexterm"></a><p>
+ To search for a value in an array, each value must be checked.
+ This can be done manually, if you know the size of the array.
+ For example:
+
+</p><pre class="programlisting">
+SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
+ pay_by_quarter[2] = 10000 OR
+ pay_by_quarter[3] = 10000 OR
+ pay_by_quarter[4] = 10000;
+</pre><p>
+
+ 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 <a class="xref" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Section 9.24</a>. The above
+ query could be replaced by:
+
+</p><pre class="programlisting">
+SELECT * FROM sal_emp WHERE 10000 = ANY (pay_by_quarter);
+</pre><p>
+
+ In addition, you can find rows where the array has all values
+ equal to 10000 with:
+
+</p><pre class="programlisting">
+SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
+</pre><p>
+
+ </p><p>
+ Alternatively, the <code class="function">generate_subscripts</code> function can be used.
+ For example:
+
+</p><pre class="programlisting">
+SELECT * FROM
+ (SELECT pay_by_quarter,
+ generate_subscripts(pay_by_quarter, 1) AS s
+ FROM sal_emp) AS foo
+ WHERE pay_by_quarter[s] = 10000;
+</pre><p>
+
+ This function is described in <a class="xref" href="functions-srf.html#FUNCTIONS-SRF-SUBSCRIPTS" title="Table 9.65. Subscript Generating Functions">Table 9.65</a>.
+ </p><p>
+ You can also search an array using the <code class="literal">&amp;&amp;</code> operator,
+ which checks whether the left operand overlaps with the right operand.
+ For instance:
+
+</p><pre class="programlisting">
+SELECT * FROM sal_emp WHERE pay_by_quarter &amp;&amp; ARRAY[10000];
+</pre><p>
+
+ This and other array operators are further described in
+ <a class="xref" href="functions-array.html" title="9.19. Array Functions and Operators">Section 9.19</a>. It can be accelerated by an appropriate
+ index, as described in <a class="xref" href="indexes-types.html" title="11.2. Index Types">Section 11.2</a>.
+ </p><p>
+ You can also search for specific values in an array using the <code class="function">array_position</code>
+ and <code class="function">array_positions</code> functions. The former returns the subscript of
+ the first occurrence of a value in an array; the latter returns an array with the
+ subscripts of all occurrences of the value in the array. For example:
+
+</p><pre class="programlisting">
+SELECT array_position(ARRAY['sun','mon','tue','wed','thu','fri','sat'], 'mon');
+ array_position
+----------------
+ 2
+(1 row)
+
+SELECT array_positions(ARRAY[1, 4, 3, 1, 3, 4, 2, 1], 1);
+ array_positions
+-----------------
+ {1,4,8}
+(1 row)
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Arrays are not sets; searching for specific array elements
+ can be a sign of database misdesign. Consider
+ using a separate table with a row for each item that would be an
+ array element. This will be easier to search, and is likely to
+ scale better for a large number of elements.
+ </p></div></div><div class="sect2" id="ARRAYS-IO"><div class="titlepage"><div><div><h3 class="title">8.15.6. Array Input and Output Syntax</h3></div></div></div><a id="id-1.5.7.23.9.2" class="indexterm"></a><p>
+ The external text representation of an array value consists of items that
+ are interpreted according to the I/O conversion rules for the array's
+ element type, plus decoration that indicates the array structure.
+ The decoration consists of curly braces (<code class="literal">{</code> and <code class="literal">}</code>)
+ around the array value plus delimiter characters between adjacent items.
+ The delimiter character is usually a comma (<code class="literal">,</code>) but can be
+ something else: it is determined by the <code class="literal">typdelim</code> setting
+ for the array's element type. Among the standard data types provided
+ in the <span class="productname">PostgreSQL</span> distribution, all use a comma,
+ except for type <code class="type">box</code>, which uses a semicolon (<code class="literal">;</code>).
+ In a multidimensional array, each dimension (row, plane,
+ cube, etc.) gets its own level of curly braces, and delimiters
+ must be written between adjacent curly-braced entities of the same level.
+ </p><p>
+ The array output routine will put double quotes around element values
+ if they are empty strings, contain curly braces, delimiter characters,
+ double quotes, backslashes, or white space, or match the word
+ <code class="literal">NULL</code>. Double quotes and backslashes
+ embedded in element values will be backslash-escaped. For numeric
+ data types it is safe to assume that double quotes will never appear, but
+ for textual data types one should be prepared to cope with either the presence
+ or absence of quotes.
+ </p><p>
+ By default, the lower bound index value of an array's dimensions is
+ set to one. To represent arrays with other lower bounds, the array
+ subscript ranges can be specified explicitly before writing the
+ array contents.
+ This decoration consists of square brackets (<code class="literal">[]</code>)
+ around each array dimension's lower and upper bounds, with
+ a colon (<code class="literal">:</code>) delimiter character in between. The
+ array dimension decoration is followed by an equal sign (<code class="literal">=</code>).
+ For example:
+</p><pre class="programlisting">
+SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
+ FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss;
+
+ e1 | e2
+----+----
+ 1 | 6
+(1 row)
+</pre><p>
+ The array output routine will include explicit dimensions in its result
+ only when there are one or more lower bounds different from one.
+ </p><p>
+ If the value written for an element is <code class="literal">NULL</code> (in any case
+ variant), the element is taken to be NULL. The presence of any quotes
+ or backslashes disables this and allows the literal string value
+ <span class="quote">“<span class="quote">NULL</span>”</span> to be entered. Also, for backward compatibility with
+ pre-8.2 versions of <span class="productname">PostgreSQL</span>, the <a class="xref" href="runtime-config-compatible.html#GUC-ARRAY-NULLS">array_nulls</a> configuration parameter can be turned
+ <code class="literal">off</code> to suppress recognition of <code class="literal">NULL</code> as a NULL.
+ </p><p>
+ As shown previously, when writing an array value you can use double
+ quotes around any individual array element. You <span class="emphasis"><em>must</em></span> do so
+ if the element value would otherwise confuse the array-value parser.
+ For example, elements containing curly braces, commas (or the data type's
+ delimiter character), double quotes, backslashes, or leading or trailing
+ whitespace must be double-quoted. Empty strings and strings matching the
+ word <code class="literal">NULL</code> must be quoted, too. To put a double
+ quote or backslash in a quoted array element value, precede it
+ with a backslash. Alternatively, you can avoid quotes and use
+ backslash-escaping to protect all data characters that would otherwise
+ be taken as array syntax.
+ </p><p>
+ You can add whitespace before a left brace or after a right
+ brace. You can also add whitespace before or after any individual item
+ string. In all of these cases the whitespace will be ignored. However,
+ whitespace within double-quoted elements, or surrounded on both sides by
+ non-whitespace characters of an element, is not ignored.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The <code class="literal">ARRAY</code> constructor syntax (see
+ <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS" title="4.2.12. Array Constructors">Section 4.2.12</a>) is often easier to work
+ with than the array-literal syntax when writing array values in SQL
+ commands. In <code class="literal">ARRAY</code>, individual element values are written the
+ same way they would be written when not members of an array.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-json.html" title="8.14. JSON Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rowtypes.html" title="8.16. Composite Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.14. <acronym class="acronym">JSON</acronym> Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.16. Composite Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-bsd.html b/doc/src/sgml/html/auth-bsd.html
new file mode 100644
index 0000000..f8247af
--- /dev/null
+++ b/doc/src/sgml/html/auth-bsd.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.14. BSD Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-pam.html" title="21.13. PAM Authentication" /><link rel="next" href="client-authentication-problems.html" title="21.15. Authentication Problems" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.14. BSD Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-pam.html" title="21.13. PAM Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="client-authentication-problems.html" title="21.15. Authentication Problems">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-BSD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.14. BSD Authentication</h2></div></div></div><a id="id-1.6.8.21.2" class="indexterm"></a><p>
+ This authentication method operates similarly to
+ <code class="literal">password</code> except that it uses BSD Authentication
+ to verify the password. BSD Authentication is used only
+ to validate user name/password pairs. Therefore the user's role must
+ already exist in the database before BSD Authentication can be used
+ for authentication. The BSD Authentication framework is currently
+ only available on OpenBSD.
+ </p><p>
+ BSD Authentication in <span class="productname">PostgreSQL</span> uses
+ the <code class="literal">auth-postgresql</code> login type and authenticates with
+ the <code class="literal">postgresql</code> login class if that's defined
+ in <code class="filename">login.conf</code>. By default that login class does not
+ exist, and <span class="productname">PostgreSQL</span> will use the default login class.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ To use BSD Authentication, the PostgreSQL user account (that is, the
+ operating system user running the server) must first be added to
+ the <code class="literal">auth</code> group. The <code class="literal">auth</code> group
+ exists by default on OpenBSD systems.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-pam.html" title="21.13. PAM Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="client-authentication-problems.html" title="21.15. Authentication Problems">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.13. PAM Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.15. Authentication Problems</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-cert.html b/doc/src/sgml/html/auth-cert.html
new file mode 100644
index 0000000..95506b2
--- /dev/null
+++ b/doc/src/sgml/html/auth-cert.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.12. Certificate Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-radius.html" title="21.11. RADIUS Authentication" /><link rel="next" href="auth-pam.html" title="21.13. PAM Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.12. Certificate Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-radius.html" title="21.11. RADIUS Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-pam.html" title="21.13. PAM Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-CERT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.12. Certificate Authentication</h2></div></div></div><a id="id-1.6.8.19.2" class="indexterm"></a><p>
+ This authentication method uses SSL client certificates to perform
+ authentication. It is therefore only available for SSL connections;
+ see <a class="xref" href="ssl-tcp.html#SSL-OPENSSL-CONFIG" title="19.9.2. OpenSSL Configuration">Section 19.9.2</a> for SSL configuration instructions.
+ When using this authentication method, the server will require that
+ the client provide a valid, trusted certificate. No password prompt
+ will be sent to the client. The <code class="literal">cn</code> (Common Name)
+ attribute of the certificate
+ will be compared to the requested database user name, and if they match
+ the login will be allowed. User name mapping can be used to allow
+ <code class="literal">cn</code> to be different from the database user name.
+ </p><p>
+ The following configuration options are supported for SSL certificate
+ authentication:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
+ Allows for mapping between system and database user names. See
+ <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details.
+ </p></dd></dl></div><p>
+ </p><p>
+ It is redundant to use the <code class="literal">clientcert</code> option with
+ <code class="literal">cert</code> authentication because <code class="literal">cert</code>
+ authentication is effectively <code class="literal">trust</code> authentication
+ with <code class="literal">clientcert=verify-full</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-radius.html" title="21.11. RADIUS Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-pam.html" title="21.13. PAM Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.11. RADIUS Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.13. PAM Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-delay.html b/doc/src/sgml/html/auth-delay.html
new file mode 100644
index 0000000..f4fa997
--- /dev/null
+++ b/doc/src/sgml/html/auth-delay.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.3. auth_delay</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="amcheck.html" title="F.2. amcheck" /><link rel="next" href="auto-explain.html" title="F.4. auto_explain" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.3. auth_delay</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="amcheck.html" title="F.2. amcheck">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auto-explain.html" title="F.4. auto_explain">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-DELAY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.3. auth_delay</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="auth-delay.html#id-1.11.7.12.5">F.3.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="auth-delay.html#id-1.11.7.12.6">F.3.2. Author</a></span></dt></dl></div><a id="id-1.11.7.12.2" class="indexterm"></a><p>
+ <code class="filename">auth_delay</code> causes the server to pause briefly before
+ reporting authentication failure, to make brute-force attacks on database
+ passwords more difficult. Note that it does nothing to prevent
+ denial-of-service attacks, and may even exacerbate them, since processes
+ that are waiting before reporting authentication failure will still consume
+ connection slots.
+ </p><p>
+ In order to function, this module must be loaded via
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> in <code class="filename">postgresql.conf</code>.
+ </p><div class="sect2" id="id-1.11.7.12.5"><div class="titlepage"><div><div><h3 class="title">F.3.1. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">auth_delay.milliseconds</code> (<code class="type">integer</code>)
+ <a id="id-1.11.7.12.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The number of milliseconds to wait before reporting an authentication
+ failure. The default is 0.
+ </p></dd></dl></div><p>
+ These parameters must be set in <code class="filename">postgresql.conf</code>.
+ Typical usage might be:
+ </p><pre class="programlisting">
+# postgresql.conf
+shared_preload_libraries = 'auth_delay'
+
+auth_delay.milliseconds = '500'
+</pre></div><div class="sect2" id="id-1.11.7.12.6"><div class="titlepage"><div><div><h3 class="title">F.3.2. Author</h3></div></div></div><p>
+ KaiGai Kohei <code class="email">&lt;<a class="email" href="mailto:kaigai@ak.jp.nec.com">kaigai@ak.jp.nec.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="amcheck.html" title="F.2. amcheck">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auto-explain.html" title="F.4. auto_explain">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.2. amcheck </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.4. auto_explain</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-ident.html b/doc/src/sgml/html/auth-ident.html
new file mode 100644
index 0000000..e2999e7
--- /dev/null
+++ b/doc/src/sgml/html/auth-ident.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.8. Ident Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sspi-auth.html" title="21.7. SSPI Authentication" /><link rel="next" href="auth-peer.html" title="21.9. Peer Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.8. Ident Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sspi-auth.html" title="21.7. SSPI Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-peer.html" title="21.9. Peer Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-IDENT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.8. Ident Authentication</h2></div></div></div><a id="id-1.6.8.15.2" class="indexterm"></a><p>
+ The ident authentication method works by obtaining the client's
+ operating system user name from an ident server and using it as
+ the allowed database user name (with an optional user name mapping).
+ This is only supported on TCP/IP connections.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When ident is specified for a local (non-TCP/IP) connection,
+ peer authentication (see <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a>) will be
+ used instead.
+ </p></div><p>
+ The following configuration options are supported for <code class="literal">ident</code>:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
+ Allows for mapping between system and database user names. See
+ <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <span class="quote">“<span class="quote">Identification Protocol</span>”</span> is described in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc1413" target="_top">RFC 1413</a>.
+ Virtually every Unix-like
+ operating system ships with an ident server that listens on TCP
+ port 113 by default. The basic functionality of an ident server
+ is to answer questions like <span class="quote">“<span class="quote">What user initiated the
+ connection that goes out of your port <em class="replaceable"><code>X</code></em>
+ and connects to my port <em class="replaceable"><code>Y</code></em>?</span>”</span>.
+ Since <span class="productname">PostgreSQL</span> knows both <em class="replaceable"><code>X</code></em> and
+ <em class="replaceable"><code>Y</code></em> when a physical connection is established, it
+ can interrogate the ident server on the host of the connecting
+ client and can theoretically determine the operating system user
+ for any given connection.
+ </p><p>
+ The drawback of this procedure is that it depends on the integrity
+ of the client: if the client machine is untrusted or compromised,
+ an attacker could run just about any program on port 113 and
+ return any user name they choose. This authentication method is
+ therefore only appropriate for closed networks where each client
+ machine is under tight control and where the database and system
+ administrators operate in close contact. In other words, you must
+ trust the machine running the ident server.
+ Heed the warning:
+ </p><div class="blockquote"><table border="0" class="blockquote" style="width: 100%; cellspacing: 0; cellpadding: 0;" summary="Block quote"><tr><td width="10%" valign="top"> </td><td width="80%" valign="top"><p>
+ The Identification Protocol is not intended as an authorization
+ or access control protocol.
+ </p></td><td width="10%" valign="top"> </td></tr><tr><td width="10%" valign="top"> </td><td colspan="2" align="right" valign="top">--<span class="attribution">RFC 1413</span></td></tr></table></div><p>
+ </p><p>
+ Some ident servers have a nonstandard option that causes the returned
+ user name to be encrypted, using a key that only the originating
+ machine's administrator knows. This option <span class="emphasis"><em>must not</em></span> be
+ used when using the ident server with <span class="productname">PostgreSQL</span>,
+ since <span class="productname">PostgreSQL</span> does not have any way to decrypt the
+ returned string to determine the actual user name.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sspi-auth.html" title="21.7. SSPI Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-peer.html" title="21.9. Peer Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.7. SSPI Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.9. Peer Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-ldap.html b/doc/src/sgml/html/auth-ldap.html
new file mode 100644
index 0000000..22b7a56
--- /dev/null
+++ b/doc/src/sgml/html/auth-ldap.html
@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.10. LDAP Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-peer.html" title="21.9. Peer Authentication" /><link rel="next" href="auth-radius.html" title="21.11. RADIUS Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.10. LDAP Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-peer.html" title="21.9. Peer Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-radius.html" title="21.11. RADIUS Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-LDAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.10. LDAP Authentication</h2></div></div></div><a id="id-1.6.8.17.2" class="indexterm"></a><p>
+ This authentication method operates similarly to
+ <code class="literal">password</code> except that it uses LDAP
+ as the password verification method. LDAP is used only to validate
+ the user name/password pairs. Therefore the user must already
+ exist in the database before LDAP can be used for
+ authentication.
+ </p><p>
+ LDAP authentication can operate in two modes. In the first mode,
+ which we will call the simple bind mode,
+ the server will bind to the distinguished name constructed as
+ <em class="replaceable"><code>prefix</code></em> <em class="replaceable"><code>username</code></em> <em class="replaceable"><code>suffix</code></em>.
+ Typically, the <em class="replaceable"><code>prefix</code></em> parameter is used to specify
+ <code class="literal">cn=</code>, or <em class="replaceable"><code>DOMAIN</code></em><code class="literal">\</code> in an Active
+ Directory environment. <em class="replaceable"><code>suffix</code></em> is used to specify the
+ remaining part of the DN in a non-Active Directory environment.
+ </p><p>
+ In the second mode, which we will call the search+bind mode,
+ the server first binds to the LDAP directory with
+ a fixed user name and password, specified with <em class="replaceable"><code>ldapbinddn</code></em>
+ and <em class="replaceable"><code>ldapbindpasswd</code></em>, and performs a search for the user trying
+ to log in to the database. If no user and password is configured, an
+ anonymous bind will be attempted to the directory. The search will be
+ performed over the subtree at <em class="replaceable"><code>ldapbasedn</code></em>, and will try to
+ do an exact match of the attribute specified in
+ <em class="replaceable"><code>ldapsearchattribute</code></em>.
+ Once the user has been found in
+ this search, the server disconnects and re-binds to the directory as
+ this user, using the password specified by the client, to verify that the
+ login is correct. This mode is the same as that used by LDAP authentication
+ schemes in other software, such as Apache <code class="literal">mod_authnz_ldap</code> and <code class="literal">pam_ldap</code>.
+ This method allows for significantly more flexibility
+ in where the user objects are located in the directory, but will cause
+ two separate connections to the LDAP server to be made.
+ </p><p>
+ The following configuration options are used in both modes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapserver</code></span></dt><dd><p>
+ Names or IP addresses of LDAP servers to connect to. Multiple
+ servers may be specified, separated by spaces.
+ </p></dd><dt><span class="term"><code class="literal">ldapport</code></span></dt><dd><p>
+ Port number on LDAP server to connect to. If no port is specified,
+ the LDAP library's default port setting will be used.
+ </p></dd><dt><span class="term"><code class="literal">ldapscheme</code></span></dt><dd><p>
+ Set to <code class="literal">ldaps</code> to use LDAPS. This is a non-standard
+ way of using LDAP over SSL, supported by some LDAP server
+ implementations. See also the <code class="literal">ldaptls</code> option for
+ an alternative.
+ </p></dd><dt><span class="term"><code class="literal">ldaptls</code></span></dt><dd><p>
+ Set to 1 to make the connection between PostgreSQL and the LDAP server
+ use TLS encryption. This uses the <code class="literal">StartTLS</code>
+ operation per <a class="ulink" href="https://tools.ietf.org/html/rfc4513" target="_top">RFC 4513</a>.
+ See also the <code class="literal">ldapscheme</code> option for an alternative.
+ </p></dd></dl></div><p>
+ </p><p>
+ Note that using <code class="literal">ldapscheme</code> or
+ <code class="literal">ldaptls</code> only encrypts the traffic between the
+ PostgreSQL server and the LDAP server. The connection between the
+ PostgreSQL server and the PostgreSQL client will still be unencrypted
+ unless SSL is used there as well.
+ </p><p>
+ The following options are used in simple bind mode only:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapprefix</code></span></dt><dd><p>
+ String to prepend to the user name when forming the DN to bind as,
+ when doing simple bind authentication.
+ </p></dd><dt><span class="term"><code class="literal">ldapsuffix</code></span></dt><dd><p>
+ String to append to the user name when forming the DN to bind as,
+ when doing simple bind authentication.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following options are used in search+bind mode only:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ldapbasedn</code></span></dt><dd><p>
+ Root DN to begin the search for the user in, when doing search+bind
+ authentication.
+ </p></dd><dt><span class="term"><code class="literal">ldapbinddn</code></span></dt><dd><p>
+ DN of user to bind to the directory with to perform the search when
+ doing search+bind authentication.
+ </p></dd><dt><span class="term"><code class="literal">ldapbindpasswd</code></span></dt><dd><p>
+ Password for user to bind to the directory with to perform the search
+ when doing search+bind authentication.
+ </p></dd><dt><span class="term"><code class="literal">ldapsearchattribute</code></span></dt><dd><p>
+ Attribute to match against the user name in the search when doing
+ search+bind authentication. If no attribute is specified, the
+ <code class="literal">uid</code> attribute will be used.
+ </p></dd><dt><span class="term"><code class="literal">ldapsearchfilter</code></span></dt><dd><p>
+ The search filter to use when doing search+bind authentication.
+ Occurrences of <code class="literal">$username</code> will be replaced with the
+ user name. This allows for more flexible search filters than
+ <code class="literal">ldapsearchattribute</code>.
+ </p></dd><dt><span class="term"><code class="literal">ldapurl</code></span></dt><dd><p>
+ An <a class="ulink" href="https://tools.ietf.org/html/rfc4516" target="_top">RFC 4516</a>
+ LDAP URL. This is an alternative way to write some of the
+ other LDAP options in a more compact and standard form. The format is
+</p><pre class="synopsis">
+ldap[s]://<em class="replaceable"><code>host</code></em>[:<em class="replaceable"><code>port</code></em>]/<em class="replaceable"><code>basedn</code></em>[?[<em class="replaceable"><code>attribute</code></em>][?[<em class="replaceable"><code>scope</code></em>][?[<em class="replaceable"><code>filter</code></em>]]]]
+</pre><p>
+ <em class="replaceable"><code>scope</code></em> must be one
+ of <code class="literal">base</code>, <code class="literal">one</code>, <code class="literal">sub</code>,
+ typically the last. (The default is <code class="literal">base</code>, which
+ is normally not useful in this application.) <em class="replaceable"><code>attribute</code></em> can
+ nominate a single attribute, in which case it is used as a value for
+ <code class="literal">ldapsearchattribute</code>. If
+ <em class="replaceable"><code>attribute</code></em> is empty then
+ <em class="replaceable"><code>filter</code></em> can be used as a value for
+ <code class="literal">ldapsearchfilter</code>.
+ </p><p>
+ The URL scheme <code class="literal">ldaps</code> chooses the LDAPS method for
+ making LDAP connections over SSL, equivalent to using
+ <code class="literal">ldapscheme=ldaps</code>. To use encrypted LDAP
+ connections using the <code class="literal">StartTLS</code> operation, use the
+ normal URL scheme <code class="literal">ldap</code> and specify the
+ <code class="literal">ldaptls</code> option in addition to
+ <code class="literal">ldapurl</code>.
+ </p><p>
+ For non-anonymous binds, <code class="literal">ldapbinddn</code>
+ and <code class="literal">ldapbindpasswd</code> must be specified as separate
+ options.
+ </p><p>
+ LDAP URLs are currently only supported with
+ <span class="productname">OpenLDAP</span>, not on Windows.
+ </p></dd></dl></div><p>
+ </p><p>
+ It is an error to mix configuration options for simple bind with options
+ for search+bind.
+ </p><p>
+ When using search+bind mode, the search can be performed using a single
+ attribute specified with <code class="literal">ldapsearchattribute</code>, or using
+ a custom search filter specified with
+ <code class="literal">ldapsearchfilter</code>.
+ Specifying <code class="literal">ldapsearchattribute=foo</code> is equivalent to
+ specifying <code class="literal">ldapsearchfilter="(foo=$username)"</code>. If neither
+ option is specified the default is
+ <code class="literal">ldapsearchattribute=uid</code>.
+ </p><p>
+ If <span class="productname">PostgreSQL</span> was compiled with
+ <span class="productname">OpenLDAP</span> as the LDAP client library, the
+ <code class="literal">ldapserver</code> setting may be omitted. In that case, a
+ list of host names and ports is looked up via
+ <a class="ulink" href="https://tools.ietf.org/html/rfc2782" target="_top">RFC 2782</a> DNS SRV records.
+ The name <code class="literal">_ldap._tcp.DOMAIN</code> is looked up, where
+ <code class="literal">DOMAIN</code> is extracted from <code class="literal">ldapbasedn</code>.
+ </p><p>
+ Here is an example for a simple-bind LDAP configuration:
+</p><pre class="programlisting">
+host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
+</pre><p>
+ When a connection to the database server as database
+ user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to
+ bind to the LDAP server using the DN <code class="literal">cn=someuser, dc=example,
+ dc=net</code> and the password provided by the client. If that connection
+ succeeds, the database access is granted.
+ </p><p>
+ Here is an example for a search+bind configuration:
+</p><pre class="programlisting">
+host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchattribute=uid
+</pre><p>
+ When a connection to the database server as database
+ user <code class="literal">someuser</code> is requested, PostgreSQL will attempt to
+ bind anonymously (since <code class="literal">ldapbinddn</code> was not specified) to
+ the LDAP server, perform a search for <code class="literal">(uid=someuser)</code>
+ under the specified base DN. If an entry is found, it will then attempt to
+ bind using that found information and the password supplied by the client.
+ If that second connection succeeds, the database access is granted.
+ </p><p>
+ Here is the same search+bind configuration written as a URL:
+</p><pre class="programlisting">
+host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub"
+</pre><p>
+ Some other software that supports authentication against LDAP uses the
+ same URL format, so it will be easier to share the configuration.
+ </p><p>
+ Here is an example for a search+bind configuration that uses
+ <code class="literal">ldapsearchfilter</code> instead of
+ <code class="literal">ldapsearchattribute</code> to allow authentication by
+ user ID or email address:
+</p><pre class="programlisting">
+host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapsearchfilter="(|(uid=$username)(mail=$username))"
+</pre><p>
+ </p><p>
+ Here is an example for a search+bind configuration that uses DNS SRV
+ discovery to find the host name(s) and port(s) for the LDAP service for the
+ domain name <code class="literal">example.net</code>:
+</p><pre class="programlisting">
+host ... ldap ldapbasedn="dc=example,dc=net"
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Since LDAP often uses commas and spaces to separate the different
+ parts of a DN, it is often necessary to use double-quoted parameter
+ values when configuring LDAP options, as shown in the examples.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-peer.html" title="21.9. Peer Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-radius.html" title="21.11. RADIUS Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.9. Peer Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.11. RADIUS Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-methods.html b/doc/src/sgml/html/auth-methods.html
new file mode 100644
index 0000000..52df71b
--- /dev/null
+++ b/doc/src/sgml/html/auth-methods.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.3. Authentication Methods</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-username-maps.html" title="21.2. User Name Maps" /><link rel="next" href="auth-trust.html" title="21.4. Trust Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.3. Authentication Methods</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-username-maps.html" title="21.2. User Name Maps">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-trust.html" title="21.4. Trust Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-METHODS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.3. Authentication Methods</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides various methods for
+ authenticating users:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="link" href="auth-trust.html" title="21.4. Trust Authentication">Trust authentication</a>, which
+ simply trusts that users are who they say they are.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-password.html" title="21.5. Password Authentication">Password authentication</a>, which
+ requires that users send a password.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">GSSAPI authentication</a>, which
+ relies on a GSSAPI-compatible security library. Typically this is
+ used to access an authentication server such as a Kerberos or
+ Microsoft Active Directory server.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="sspi-auth.html" title="21.7. SSPI Authentication">SSPI authentication</a>, which
+ uses a Windows-specific protocol similar to GSSAPI.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-ident.html" title="21.8. Ident Authentication">Ident authentication</a>, which
+ relies on an <span class="quote">“<span class="quote">Identification Protocol</span>”</span>
+ (<a class="ulink" href="https://tools.ietf.org/html/rfc1413" target="_top">RFC 1413</a>)
+ service on the client's machine. (On local Unix-socket connections,
+ this is treated as peer authentication.)
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-peer.html" title="21.9. Peer Authentication">Peer authentication</a>, which
+ relies on operating system facilities to identify the process at the
+ other end of a local connection. This is not supported for remote
+ connections.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-ldap.html" title="21.10. LDAP Authentication">LDAP authentication</a>, which
+ relies on an LDAP authentication server.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-radius.html" title="21.11. RADIUS Authentication">RADIUS authentication</a>, which
+ relies on a RADIUS authentication server.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-cert.html" title="21.12. Certificate Authentication">Certificate authentication</a>, which
+ requires an SSL connection and authenticates users by checking the
+ SSL certificate they send.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-pam.html" title="21.13. PAM Authentication">PAM authentication</a>, which
+ relies on a PAM (Pluggable Authentication Modules) library.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="auth-bsd.html" title="21.14. BSD Authentication">BSD authentication</a>, which
+ relies on the BSD Authentication framework (currently available
+ only on OpenBSD).
+ </p></li></ul></div><p>
+ </p><p>
+ Peer authentication is usually recommendable for local connections,
+ though trust authentication might be sufficient in some circumstances.
+ Password authentication is the easiest choice for remote connections.
+ All the other options require some kind of external security
+ infrastructure (usually an authentication server or a certificate
+ authority for issuing SSL certificates), or are platform-specific.
+ </p><p>
+ The following sections describe each of these authentication methods
+ in more detail.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-username-maps.html" title="21.2. User Name Maps">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-trust.html" title="21.4. Trust Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.2. User Name Maps </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.4. Trust Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-pam.html b/doc/src/sgml/html/auth-pam.html
new file mode 100644
index 0000000..6096e60
--- /dev/null
+++ b/doc/src/sgml/html/auth-pam.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.13. PAM Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-cert.html" title="21.12. Certificate Authentication" /><link rel="next" href="auth-bsd.html" title="21.14. BSD Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.13. PAM Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-cert.html" title="21.12. Certificate Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-bsd.html" title="21.14. BSD Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PAM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.13. PAM Authentication</h2></div></div></div><a id="id-1.6.8.20.2" class="indexterm"></a><p>
+ This authentication method operates similarly to
+ <code class="literal">password</code> except that it uses PAM (Pluggable
+ Authentication Modules) as the authentication mechanism. The
+ default PAM service name is <code class="literal">postgresql</code>.
+ PAM is used only to validate user name/password pairs and optionally the
+ connected remote host name or IP address. Therefore the user must already
+ exist in the database before PAM can be used for authentication. For more
+ information about PAM, please read the
+ <a class="ulink" href="https://www.kernel.org/pub/linux/libs/pam/" target="_top">
+ <span class="productname">Linux-PAM</span> Page</a>.
+ </p><p>
+ The following configuration options are supported for PAM:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">pamservice</code></span></dt><dd><p>
+ PAM service name.
+ </p></dd><dt><span class="term"><code class="literal">pam_use_hostname</code></span></dt><dd><p>
+ Determines whether the remote IP address or the host name is provided
+ to PAM modules through the <code class="symbol">PAM_RHOST</code> item. By
+ default, the IP address is used. Set this option to 1 to use the
+ resolved host name instead. Host name resolution can lead to login
+ delays. (Most PAM configurations don't use this information, so it is
+ only necessary to consider this setting if a PAM configuration was
+ specifically created to make use of it.)
+ </p></dd></dl></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If PAM is set up to read <code class="filename">/etc/shadow</code>, authentication
+ will fail because the PostgreSQL server is started by a non-root
+ user. However, this is not an issue when PAM is configured to use
+ LDAP or other authentication methods.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-cert.html" title="21.12. Certificate Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-bsd.html" title="21.14. BSD Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.12. Certificate Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.14. BSD Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-password.html b/doc/src/sgml/html/auth-password.html
new file mode 100644
index 0000000..f30a8bd
--- /dev/null
+++ b/doc/src/sgml/html/auth-password.html
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.5. Password Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-trust.html" title="21.4. Trust Authentication" /><link rel="next" href="gssapi-auth.html" title="21.6. GSSAPI Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.5. Password Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-trust.html" title="21.4. Trust Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PASSWORD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.5. Password Authentication</h2></div></div></div><a id="id-1.6.8.12.2" class="indexterm"></a><a id="id-1.6.8.12.3" class="indexterm"></a><a id="id-1.6.8.12.4" class="indexterm"></a><p>
+ There are several password-based authentication methods. These methods
+ operate similarly but differ in how the users' passwords are stored on the
+ server and how the password provided by a client is sent across the
+ connection.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
+ The method <code class="literal">scram-sha-256</code> performs SCRAM-SHA-256
+ authentication, as described in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc7677" target="_top">RFC 7677</a>. It
+ is a challenge-response scheme that prevents password sniffing on
+ untrusted connections and supports storing passwords on the server in a
+ cryptographically hashed form that is thought to be secure.
+ </p><p>
+ This is the most secure of the currently provided methods, but it is
+ not supported by older client libraries.
+ </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
+ The method <code class="literal">md5</code> uses a custom less secure challenge-response
+ mechanism. It prevents password sniffing and avoids storing passwords
+ on the server in plain text but provides no protection if an attacker
+ manages to steal the password hash from the server. Also, the MD5 hash
+ algorithm is nowadays no longer considered secure against determined
+ attacks.
+ </p><p>
+ The <code class="literal">md5</code> method cannot be used with
+ the <a class="xref" href="runtime-config-connection.html#GUC-DB-USER-NAMESPACE">db_user_namespace</a> feature.
+ </p><p>
+ To ease transition from the <code class="literal">md5</code> method to the newer
+ SCRAM method, if <code class="literal">md5</code> is specified as a method
+ in <code class="filename">pg_hba.conf</code> but the user's password on the
+ server is encrypted for SCRAM (see below), then SCRAM-based
+ authentication will automatically be chosen instead.
+ </p></dd><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
+ The method <code class="literal">password</code> sends the password in clear-text and is
+ therefore vulnerable to password <span class="quote">“<span class="quote">sniffing</span>”</span> attacks. It should
+ always be avoided if possible. If the connection is protected by SSL
+ encryption then <code class="literal">password</code> can be used safely, though.
+ (Though SSL certificate authentication might be a better choice if one
+ is depending on using SSL).
+ </p></dd></dl></div><p>
+ <span class="productname">PostgreSQL</span> database passwords are
+ separate from operating system user passwords. The password for
+ each database user is stored in the <code class="literal">pg_authid</code> system
+ catalog. Passwords can be managed with the SQL commands
+ <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a> and
+ <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>,
+ e.g., <strong class="userinput"><code>CREATE ROLE foo WITH LOGIN PASSWORD 'secret'</code></strong>,
+ or the <span class="application">psql</span>
+ command <code class="literal">\password</code>.
+ If no password has been set up for a user, the stored password
+ is null and password authentication will always fail for that user.
+ </p><p>
+ 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 <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a> at the time the
+ password is set. If a password was encrypted using
+ the <code class="literal">scram-sha-256</code> setting, then it can be used for the
+ authentication methods <code class="literal">scram-sha-256</code>
+ and <code class="literal">password</code> (but password transmission will be in
+ plain text in the latter case). The authentication method
+ specification <code class="literal">md5</code> will automatically switch to using
+ the <code class="literal">scram-sha-256</code> method in this case, as explained
+ above, so it will also work. If a password was encrypted using
+ the <code class="literal">md5</code> setting, then it can be used only for
+ the <code class="literal">md5</code> and <code class="literal">password</code> authentication
+ method specifications (again, with the password transmitted in plain text
+ in the latter case). (Previous PostgreSQL releases supported storing the
+ password on the server in plain text. This is no longer possible.) To
+ check the currently stored password hashes, see the system
+ catalog <code class="literal">pg_authid</code>.
+ </p><p>
+ To upgrade an existing installation from <code class="literal">md5</code>
+ to <code class="literal">scram-sha-256</code>, after having ensured that all client
+ libraries in use are new enough to support SCRAM,
+ set <code class="literal">password_encryption = 'scram-sha-256'</code>
+ in <code class="filename">postgresql.conf</code>, make all users set new passwords,
+ and change the authentication method specifications
+ in <code class="filename">pg_hba.conf</code> to <code class="literal">scram-sha-256</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-trust.html" title="21.4. Trust Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.4. Trust Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.6. GSSAPI Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-peer.html b/doc/src/sgml/html/auth-peer.html
new file mode 100644
index 0000000..ddb598c
--- /dev/null
+++ b/doc/src/sgml/html/auth-peer.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.9. Peer Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-ident.html" title="21.8. Ident Authentication" /><link rel="next" href="auth-ldap.html" title="21.10. LDAP Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.9. Peer Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-ident.html" title="21.8. Ident Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-ldap.html" title="21.10. LDAP Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PEER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.9. Peer Authentication</h2></div></div></div><a id="id-1.6.8.16.2" class="indexterm"></a><p>
+ The peer authentication method works by obtaining the client's
+ operating system user name from the kernel and using it as the
+ allowed database user name (with optional user name mapping). This
+ method is only supported on local connections.
+ </p><p>
+ The following configuration options are supported for <code class="literal">peer</code>:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
+ Allows for mapping between system and database user names. See
+ <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details.
+ </p></dd></dl></div><p>
+ </p><p>
+ Peer authentication is only available on operating systems providing
+ the <code class="function">getpeereid()</code> function, the <code class="symbol">SO_PEERCRED</code>
+ socket parameter, or similar mechanisms. Currently that includes
+ <span class="systemitem">Linux</span>,
+ most flavors of <span class="systemitem">BSD</span> including
+ <span class="systemitem">macOS</span>,
+ and <span class="systemitem">Solaris</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-ident.html" title="21.8. Ident Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-ldap.html" title="21.10. LDAP Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.8. Ident Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.10. LDAP Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-pg-hba-conf.html b/doc/src/sgml/html/auth-pg-hba-conf.html
new file mode 100644
index 0000000..4ac90fb
--- /dev/null
+++ b/doc/src/sgml/html/auth-pg-hba-conf.html
@@ -0,0 +1,492 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.1. The pg_hba.conf File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="client-authentication.html" title="Chapter 21. Client Authentication" /><link rel="next" href="auth-username-maps.html" title="21.2. User Name Maps" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.1. The <code class="filename">pg_hba.conf</code> File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 21. Client Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="21.2. User Name Maps">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PG-HBA-CONF"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.1. The <code class="filename">pg_hba.conf</code> File</h2></div></div></div><a id="id-1.6.8.8.2" class="indexterm"></a><p>
+ Client authentication is controlled by a configuration file,
+ which traditionally is named
+ <code class="filename">pg_hba.conf</code> and is stored in the database
+ cluster's data directory.
+ (<acronym class="acronym">HBA</acronym> stands for host-based authentication.) A default
+ <code class="filename">pg_hba.conf</code> file is installed when the data
+ directory is initialized by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. It is
+ possible to place the authentication configuration file elsewhere,
+ however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-HBA-FILE">hba_file</a> configuration parameter.
+ </p><p>
+ The general format of the <code class="filename">pg_hba.conf</code> file is
+ a set of records, one per line. Blank lines are ignored, as is any
+ text after the <code class="literal">#</code> comment character.
+ A record can be continued onto the next line by ending the line with
+ a backslash. (Backslashes are not special except at the end of a line.)
+ A record is made
+ up of a number of fields which are separated by spaces and/or tabs.
+ Fields can contain white space if the field value is double-quoted.
+ Quoting one of the keywords in a database, user, or address field (e.g.,
+ <code class="literal">all</code> or <code class="literal">replication</code>) makes the word lose its special
+ meaning, and just match a database, user, or host with that name.
+ Backslash line continuation applies even within quoted text or comments.
+ </p><p>
+ Each record specifies a connection type, a client IP address range
+ (if relevant for the connection type), a database name, a user name,
+ and the authentication method to be used for connections matching
+ these parameters. The first record with a matching connection type,
+ client address, requested database, and user name is used to perform
+ authentication. There is no <span class="quote">“<span class="quote">fall-through</span>”</span> or
+ <span class="quote">“<span class="quote">backup</span>”</span>: if one record is chosen and the authentication
+ fails, subsequent records are not considered. If no record matches,
+ access is denied.
+ </p><p>
+ A record can have several formats:
+</p><pre class="synopsis">
+local <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]
+</pre><p>
+ The meaning of the fields is as follows:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">local</code></span></dt><dd><p>
+ This record matches connection attempts using Unix-domain
+ sockets. Without a record of this type, Unix-domain socket
+ connections are disallowed.
+ </p></dd><dt><span class="term"><code class="literal">host</code></span></dt><dd><p>
+ This record matches connection attempts made using TCP/IP.
+ <code class="literal">host</code> records match
+ <acronym class="acronym">SSL</acronym> or non-<acronym class="acronym">SSL</acronym> connection
+ attempts as well as <acronym class="acronym">GSSAPI</acronym> encrypted or
+ non-<acronym class="acronym">GSSAPI</acronym> encrypted connection attempts.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Remote TCP/IP connections will not be possible unless
+ the server is started with an appropriate value for the
+ <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> configuration parameter,
+ since the default behavior is to listen for TCP/IP connections
+ only on the local loopback address <code class="literal">localhost</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">hostssl</code></span></dt><dd><p>
+ This record matches connection attempts made using TCP/IP,
+ but only when the connection is made with <acronym class="acronym">SSL</acronym>
+ encryption.
+ </p><p>
+ To make use of this option the server must be built with
+ <acronym class="acronym">SSL</acronym> support. Furthermore,
+ <acronym class="acronym">SSL</acronym> must be enabled
+ by setting the <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> configuration parameter (see
+ <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for more information).
+ Otherwise, the <code class="literal">hostssl</code> record is ignored except for
+ logging a warning that it cannot match any connections.
+ </p></dd><dt><span class="term"><code class="literal">hostnossl</code></span></dt><dd><p>
+ This record type has the opposite behavior of <code class="literal">hostssl</code>;
+ it only matches connection attempts made over
+ TCP/IP that do not use <acronym class="acronym">SSL</acronym>.
+ </p></dd><dt><span class="term"><code class="literal">hostgssenc</code></span></dt><dd><p>
+ This record matches connection attempts made using TCP/IP,
+ but only when the connection is made with <acronym class="acronym">GSSAPI</acronym>
+ encryption.
+ </p><p>
+ To make use of this option the server must be built with
+ <acronym class="acronym">GSSAPI</acronym> support. Otherwise,
+ the <code class="literal">hostgssenc</code> record is ignored except for logging
+ a warning that it cannot match any connections.
+ </p></dd><dt><span class="term"><code class="literal">hostnogssenc</code></span></dt><dd><p>
+ This record type has the opposite behavior of <code class="literal">hostgssenc</code>;
+ it only matches connection attempts made over
+ TCP/IP that do not use <acronym class="acronym">GSSAPI</acronym> encryption.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt><dd><p>
+ Specifies which database name(s) this record matches. The value
+ <code class="literal">all</code> specifies that it matches all databases.
+ The value <code class="literal">sameuser</code> specifies that the record
+ matches if the requested database has the same name as the
+ requested user. The value <code class="literal">samerole</code> specifies that
+ the requested user must be a member of the role with the same
+ name as the requested database. (<code class="literal">samegroup</code> is an
+ obsolete but still accepted spelling of <code class="literal">samerole</code>.)
+ Superusers are not considered to be members of a role for the
+ purposes of <code class="literal">samerole</code> unless they are explicitly
+ members of the role, directly or indirectly, and not just by
+ virtue of being a superuser.
+ The value <code class="literal">replication</code> specifies that the record
+ matches if a physical replication connection is requested, however, it
+ doesn't match with logical replication connections. Note that physical
+ replication connections do not specify any particular database whereas
+ logical replication connections do specify it.
+ Otherwise, this is the name of
+ a specific <span class="productname">PostgreSQL</span> database.
+ Multiple database names can be supplied by separating them with
+ commas. A separate file containing database names can be specified by
+ preceding the file name with <code class="literal">@</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user</code></em></span></dt><dd><p>
+ Specifies which database user name(s) this record
+ matches. The value <code class="literal">all</code> specifies that it
+ matches all users. Otherwise, this is either the name of a specific
+ database user, or a group name preceded by <code class="literal">+</code>.
+ (Recall that there is no real distinction between users and groups
+ in <span class="productname">PostgreSQL</span>; a <code class="literal">+</code> mark really means
+ <span class="quote">“<span class="quote">match any of the roles that are directly or indirectly members
+ of this role</span>”</span>, while a name without a <code class="literal">+</code> mark matches
+ only that specific role.) For this purpose, a superuser is only
+ considered to be a member of a role if they are explicitly a member
+ of the role, directly or indirectly, and not just by virtue of
+ being a superuser.
+ Multiple user names can be supplied by separating them with commas.
+ A separate file containing user names can be specified by preceding the
+ file name with <code class="literal">@</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>address</code></em></span></dt><dd><p>
+ Specifies the client machine address(es) that this record
+ matches. This field can contain either a host name, an IP
+ address range, or one of the special key words mentioned below.
+ </p><p>
+ An IP address range is specified using standard numeric notation
+ for the range's starting address, then a slash (<code class="literal">/</code>)
+ and a <acronym class="acronym">CIDR</acronym> mask length. The mask
+ length indicates the number of high-order bits of the client
+ IP address that must match. Bits to the right of this should
+ be zero in the given IP address.
+ There must not be any white space between the IP address, the
+ <code class="literal">/</code>, and the CIDR mask length.
+ </p><p>
+ Typical examples of an IPv4 address range specified this way are
+ <code class="literal">172.20.143.89/32</code> for a single host, or
+ <code class="literal">172.20.143.0/24</code> for a small network, or
+ <code class="literal">10.6.0.0/16</code> for a larger one.
+ An IPv6 address range might look like <code class="literal">::1/128</code>
+ for a single host (in this case the IPv6 loopback address) or
+ <code class="literal">fe80::7a31:c1ff:0000:0000/96</code> for a small
+ network.
+ <code class="literal">0.0.0.0/0</code> represents all
+ IPv4 addresses, and <code class="literal">::0/0</code> represents
+ all IPv6 addresses.
+ To specify a single host, use a mask length of 32 for IPv4 or
+ 128 for IPv6. In a network address, do not omit trailing zeroes.
+ </p><p>
+ An entry given in IPv4 format will match only IPv4 connections,
+ and an entry given in IPv6 format will match only IPv6 connections,
+ even if the represented address is in the IPv4-in-IPv6 range.
+ Note that entries in IPv6 format will be rejected if the system's
+ C library does not have support for IPv6 addresses.
+ </p><p>
+ You can also write <code class="literal">all</code> to match any IP address,
+ <code class="literal">samehost</code> to match any of the server's own IP
+ addresses, or <code class="literal">samenet</code> to match any address in any
+ subnet that the server is directly connected to.
+ </p><p>
+ If a host name is specified (anything that is not an IP address
+ range or a special key word is treated as a host name),
+ that name is compared with the result of a reverse name
+ resolution of the client's IP address (e.g., reverse DNS
+ lookup, if DNS is used). Host name comparisons are case
+ insensitive. If there is a match, then a forward name
+ resolution (e.g., forward DNS lookup) is performed on the host
+ name to check whether any of the addresses it resolves to are
+ equal to the client's IP address. If both directions match,
+ then the entry is considered to match. (The host name that is
+ used in <code class="filename">pg_hba.conf</code> should be the one that
+ address-to-name resolution of the client's IP address returns,
+ otherwise the line won't be matched. Some host name databases
+ allow associating an IP address with multiple host names, but
+ the operating system will only return one host name when asked
+ to resolve an IP address.)
+ </p><p>
+ A host name specification that starts with a dot
+ (<code class="literal">.</code>) matches a suffix of the actual host
+ name. So <code class="literal">.example.com</code> would match
+ <code class="literal">foo.example.com</code> (but not just
+ <code class="literal">example.com</code>).
+ </p><p>
+ When host names are specified
+ in <code class="filename">pg_hba.conf</code>, you should make sure that
+ name resolution is reasonably fast. It can be of advantage to
+ set up a local name resolution cache such
+ as <code class="command">nscd</code>. Also, you may wish to enable the
+ configuration parameter <code class="varname">log_hostname</code> to see
+ the client's host name instead of the IP address in the log.
+ </p><p>
+ These fields do not apply to <code class="literal">local</code> records.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Users sometimes wonder why host names are handled
+ in this seemingly complicated way, with two name resolutions
+ including a reverse lookup of the client's IP address. This
+ complicates use of the feature in case the client's reverse DNS
+ entry is not set up or yields some undesirable host name.
+ It is done primarily for efficiency: this way, a connection attempt
+ requires at most two resolver lookups, one reverse and one forward.
+ If there is a resolver problem with some address, it becomes only
+ that client's problem. A hypothetical alternative
+ implementation that only did forward lookups would have to
+ resolve every host name mentioned in
+ <code class="filename">pg_hba.conf</code> during every connection attempt.
+ That could be quite slow if many names are listed.
+ And if there is a resolver problem with one of the host names,
+ it becomes everyone's problem.
+ </p><p>
+ Also, a reverse lookup is necessary to implement the suffix
+ matching feature, because the actual client host name needs to
+ be known in order to match it against the pattern.
+ </p><p>
+ Note that this behavior is consistent with other popular
+ implementations of host name-based access control, such as the
+ Apache HTTP Server and TCP Wrappers.
+ </p></div></dd><dt><span class="term"><em class="replaceable"><code>IP-address</code></em><br /></span><span class="term"><em class="replaceable"><code>IP-mask</code></em></span></dt><dd><p>
+ These two fields can be used as an alternative to the
+ <em class="replaceable"><code>IP-address</code></em><code class="literal">/</code><em class="replaceable"><code>mask-length</code></em>
+ notation. Instead of
+ specifying the mask length, the actual mask is specified in a
+ separate column. For example, <code class="literal">255.0.0.0</code> represents an IPv4
+ CIDR mask length of 8, and <code class="literal">255.255.255.255</code> represents a
+ CIDR mask length of 32.
+ </p><p>
+ These fields do not apply to <code class="literal">local</code> records.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>auth-method</code></em></span></dt><dd><p>
+ Specifies the authentication method to use when a connection matches
+ this record. The possible choices are summarized here; details
+ are in <a class="xref" href="auth-methods.html" title="21.3. Authentication Methods">Section 21.3</a>. All the options
+ are lower case and treated case sensitively, so even acronyms like
+ <code class="literal">ldap</code> must be specified as lower case.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">trust</code></span></dt><dd><p>
+ Allow the connection unconditionally. This method
+ allows anyone that can connect to the
+ <span class="productname">PostgreSQL</span> database server to login as
+ any <span class="productname">PostgreSQL</span> user they wish,
+ without the need for a password or any other authentication. See <a class="xref" href="auth-trust.html" title="21.4. Trust Authentication">Section 21.4</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">reject</code></span></dt><dd><p>
+ Reject the connection unconditionally. This is useful for
+ <span class="quote">“<span class="quote">filtering out</span>”</span> certain hosts from a group, for example a
+ <code class="literal">reject</code> line could block a specific host from connecting,
+ while a later line allows the remaining hosts in a specific
+ network to connect.
+ </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
+ Perform SCRAM-SHA-256 authentication to verify the user's
+ password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
+ Perform SCRAM-SHA-256 or MD5 authentication to verify the
+ user's password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a>
+ for details.
+ </p></dd><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
+ Require the client to supply an unencrypted password for
+ authentication.
+ Since the password is sent in clear text over the
+ network, this should not be used on untrusted networks.
+ See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>
+ Use GSSAPI to authenticate the user. This is only
+ available for TCP/IP connections. See <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a> for details. It can be used in conjunction
+ with GSSAPI encryption.
+ </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>
+ Use SSPI to authenticate the user. This is only
+ available on Windows. See <a class="xref" href="sspi-auth.html" title="21.7. SSPI Authentication">Section 21.7</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">ident</code></span></dt><dd><p>
+ Obtain the operating system user name of the client
+ by contacting the ident server on the client
+ and check if it matches the requested database user name.
+ Ident authentication can only be used on TCP/IP
+ connections. When specified for local connections, peer
+ authentication will be used instead.
+ See <a class="xref" href="auth-ident.html" title="21.8. Ident Authentication">Section 21.8</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">peer</code></span></dt><dd><p>
+ 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 <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">ldap</code></span></dt><dd><p>
+ Authenticate using an <acronym class="acronym">LDAP</acronym> server. See <a class="xref" href="auth-ldap.html" title="21.10. LDAP Authentication">Section 21.10</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">radius</code></span></dt><dd><p>
+ Authenticate using a RADIUS server. See <a class="xref" href="auth-radius.html" title="21.11. RADIUS Authentication">Section 21.11</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">cert</code></span></dt><dd><p>
+ Authenticate using SSL client certificates. See
+ <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">pam</code></span></dt><dd><p>
+ Authenticate using the Pluggable Authentication Modules
+ (PAM) service provided by the operating system. See <a class="xref" href="auth-pam.html" title="21.13. PAM Authentication">Section 21.13</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">bsd</code></span></dt><dd><p>
+ Authenticate using the BSD Authentication service provided by the
+ operating system. See <a class="xref" href="auth-bsd.html" title="21.14. BSD Authentication">Section 21.14</a> for details.
+ </p></dd></dl></div><p>
+
+ </p></dd><dt><span class="term"><em class="replaceable"><code>auth-options</code></em></span></dt><dd><p>
+ After the <em class="replaceable"><code>auth-method</code></em> field, there can be field(s) of
+ the form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em> that
+ specify options for the authentication method. Details about which
+ options are available for which authentication methods appear below.
+ </p><p>
+ In addition to the method-specific options listed below, there is a
+ method-independent authentication option <code class="literal">clientcert</code>, which
+ can be specified in any <code class="literal">hostssl</code> record.
+ This option can be set to <code class="literal">verify-ca</code> or
+ <code class="literal">verify-full</code>. Both options require the client
+ to present a valid (trusted) SSL certificate, while
+ <code class="literal">verify-full</code> additionally enforces that the
+ <code class="literal">cn</code> (Common Name) in the certificate matches
+ the username or an applicable mapping.
+ This behavior is similar to the <code class="literal">cert</code> authentication
+ method (see <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a>) but enables pairing
+ the verification of client certificates with any authentication
+ method that supports <code class="literal">hostssl</code> entries.
+ </p><p>
+ On any record using client certificate authentication (i.e. one
+ using the <code class="literal">cert</code> authentication method or one
+ using the <code class="literal">clientcert</code> option), you can specify
+ which part of the client certificate credentials to match using
+ the <code class="literal">clientname</code> option. This option can have one
+ of two values. If you specify <code class="literal">clientname=CN</code>, which
+ is the default, the username is matched against the certificate's
+ <code class="literal">Common Name (CN)</code>. If instead you specify
+ <code class="literal">clientname=DN</code> the username is matched against the
+ entire <code class="literal">Distinguished Name (DN)</code> of the certificate.
+ This option is probably best used in conjunction with a username map.
+ The comparison is done with the <code class="literal">DN</code> in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc2253" target="_top">RFC 2253</a>
+ format. To see the <code class="literal">DN</code> of a client certificate
+ in this format, do
+</p><pre class="programlisting">
+openssl x509 -in myclient.crt -noout --subject -nameopt RFC2253 | sed "s/^subject=//"
+</pre><p>
+ Care needs to be taken when using this option, especially when using
+ regular expression matching against the <code class="literal">DN</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ Files included by <code class="literal">@</code> constructs are read as lists of names,
+ which can be separated by either whitespace or commas. Comments are
+ introduced by <code class="literal">#</code>, just as in
+ <code class="filename">pg_hba.conf</code>, and nested <code class="literal">@</code> constructs are
+ allowed. Unless the file name following <code class="literal">@</code> is an absolute
+ path, it is taken to be relative to the directory containing the
+ referencing file.
+ </p><p>
+ Since the <code class="filename">pg_hba.conf</code> records are examined
+ sequentially for each connection attempt, the order of the records is
+ significant. Typically, earlier records will have tight connection
+ match parameters and weaker authentication methods, while later
+ records will have looser match parameters and stronger authentication
+ methods. For example, one might wish to use <code class="literal">trust</code>
+ authentication for local TCP/IP connections but require a password for
+ remote TCP/IP connections. In this case a record specifying
+ <code class="literal">trust</code> authentication for connections from 127.0.0.1 would
+ appear before a record specifying password authentication for a wider
+ range of allowed client IP addresses.
+ </p><p>
+ The <code class="filename">pg_hba.conf</code> file is read on start-up and when
+ the main server process receives a
+ <span class="systemitem">SIGHUP</span><a id="id-1.6.8.8.9.3" class="indexterm"></a>
+ signal. If you edit the file on an
+ active system, you will need to signal the postmaster
+ (using <code class="literal">pg_ctl reload</code>, calling the SQL function
+ <code class="function">pg_reload_conf()</code>, or using <code class="literal">kill
+ -HUP</code>) to make it re-read the file.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The preceding statement is not true on Microsoft Windows: there, any
+ changes in the <code class="filename">pg_hba.conf</code> file are immediately
+ applied by subsequent new connections.
+ </p></div><p>
+ The system view
+ <a class="link" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a>
+ can be helpful for pre-testing changes to the <code class="filename">pg_hba.conf</code>
+ file, or for diagnosing problems if loading of the file did not have the
+ desired effects. Rows in the view with
+ non-null <code class="structfield">error</code> fields indicate problems in the
+ corresponding lines of the file.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ To connect to a particular database, a user must not only pass the
+ <code class="filename">pg_hba.conf</code> checks, but must have the
+ <code class="literal">CONNECT</code> privilege for the database. If you wish to
+ restrict which users can connect to which databases, it's usually
+ easier to control this by granting/revoking <code class="literal">CONNECT</code> privilege
+ than to put the rules in <code class="filename">pg_hba.conf</code> entries.
+ </p></div><p>
+ Some examples of <code class="filename">pg_hba.conf</code> entries are shown in
+ <a class="xref" href="auth-pg-hba-conf.html#EXAMPLE-PG-HBA.CONF" title="Example 21.1. Example pg_hba.conf Entries">Example 21.1</a>. See the next section for details on the
+ different authentication methods.
+ </p><div class="example" id="EXAMPLE-PG-HBA.CONF"><p class="title"><strong>Example 21.1. Example <code class="filename">pg_hba.conf</code> Entries</strong></p><div class="example-contents"><pre class="programlisting">
+# Allow any user on the local system to connect to any database with
+# any database user name using Unix-domain sockets (the default for local
+# connections).
+#
+# TYPE DATABASE USER ADDRESS METHOD
+local all all trust
+
+# The same using local loopback TCP/IP connections.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all all 127.0.0.1/32 trust
+
+# The same as the previous line, but using a separate netmask column
+#
+# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
+host all all 127.0.0.1 255.255.255.255 trust
+
+# The same over IPv6.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all all ::1/128 trust
+
+# The same using a host name (would typically cover both IPv4 and IPv6).
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all all localhost trust
+
+# Allow any user from any host with IP address 192.168.93.x to connect
+# to database "postgres" as the same user name that ident reports for
+# the connection (typically the operating system user name).
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host postgres all 192.168.93.0/24 ident
+
+# Allow any user from host 192.168.12.10 to connect to database
+# "postgres" if the user's password is correctly supplied.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host postgres all 192.168.12.10/32 scram-sha-256
+
+# Allow any user from hosts in the example.com domain to connect to
+# any database if the user's password is correctly supplied.
+#
+# Require SCRAM authentication for most users, but make an exception
+# for user 'mike', who uses an older client that doesn't support SCRAM
+# authentication.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all mike .example.com md5
+host all all .example.com scram-sha-256
+
+# In the absence of preceding "host" lines, these three lines will
+# reject all connections from 192.168.54.1 (since that entry will be
+# matched first), but allow GSSAPI-encrypted connections from anywhere else
+# on the Internet. The zero mask causes no bits of the host IP address to
+# be considered, so it matches any host. Unencrypted GSSAPI connections
+# (which "fall through" to the third line since "hostgssenc" only matches
+# encrypted GSSAPI connections) are allowed, but only from 192.168.12.10.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all all 192.168.54.1/32 reject
+hostgssenc all all 0.0.0.0/0 gss
+host all all 192.168.12.10/32 gss
+
+# Allow users from 192.168.x.x hosts to connect to any database, if
+# they pass the ident check. If, for example, ident says the user is
+# "bryanh" and he requests to connect as PostgreSQL user "guest1", the
+# connection is allowed if there is an entry in pg_ident.conf for map
+# "omicron" that says "bryanh" is allowed to connect as "guest1".
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host all all 192.168.0.0/16 ident map=omicron
+
+# If these are the only three lines for local connections, they will
+# allow local users to connect only to their own databases (databases
+# with the same name as their database user name) except for administrators
+# and members of role "support", who can connect to all databases. The file
+# $PGDATA/admins contains a list of names of administrators. Passwords
+# are required in all cases.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+local sameuser all md5
+local all @admins md5
+local all +support md5
+
+# The last two lines above can be combined into a single line:
+local all @admins,+support md5
+
+# The database column can also use lists and file names:
+local db1,db2,@demodbs all md5
+</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 21. Client Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="21.2. User Name Maps">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Client Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.2. User Name Maps</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-radius.html b/doc/src/sgml/html/auth-radius.html
new file mode 100644
index 0000000..e75890d
--- /dev/null
+++ b/doc/src/sgml/html/auth-radius.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.11. RADIUS Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-ldap.html" title="21.10. LDAP Authentication" /><link rel="next" href="auth-cert.html" title="21.12. Certificate Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.11. RADIUS Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-ldap.html" title="21.10. LDAP Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-cert.html" title="21.12. Certificate Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-RADIUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.11. RADIUS Authentication</h2></div></div></div><a id="id-1.6.8.18.2" class="indexterm"></a><p>
+ This authentication method operates similarly to
+ <code class="literal">password</code> except that it uses RADIUS
+ as the password verification method. RADIUS is used only to validate
+ the user name/password pairs. Therefore the user must already
+ exist in the database before RADIUS can be used for
+ authentication.
+ </p><p>
+ When using RADIUS authentication, an Access Request message will be sent
+ to the configured RADIUS server. This request will be of type
+ <code class="literal">Authenticate Only</code>, and include parameters for
+ <code class="literal">user name</code>, <code class="literal">password</code> (encrypted) and
+ <code class="literal">NAS Identifier</code>. The request will be encrypted using
+ a secret shared with the server. The RADIUS server will respond to
+ this request with either <code class="literal">Access Accept</code> or
+ <code class="literal">Access Reject</code>. There is no support for RADIUS accounting.
+ </p><p>
+ Multiple RADIUS servers can be specified, in which case they will
+ be tried sequentially. If a negative response is received from
+ a server, the authentication will fail. If no response is received,
+ the next server in the list will be tried. To specify multiple
+ servers, separate the server names with commas and surround the list
+ with double quotes. If multiple servers are specified, the other
+ RADIUS options can also be given as comma-separated lists, to provide
+ individual values for each server. They can also be specified as
+ a single value, in which case that value will apply to all servers.
+ </p><p>
+ The following configuration options are supported for RADIUS:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">radiusservers</code></span></dt><dd><p>
+ The DNS names or IP addresses of the RADIUS servers to connect to.
+ This parameter is required.
+ </p></dd><dt><span class="term"><code class="literal">radiussecrets</code></span></dt><dd><p>
+ The shared secrets used when talking securely to the RADIUS
+ servers. This must have exactly the same value on the PostgreSQL
+ and RADIUS servers. It is recommended that this be a string of
+ at least 16 characters. This parameter is required.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The encryption vector used will only be cryptographically
+ strong if <span class="productname">PostgreSQL</span> is built with support for
+ <span class="productname">OpenSSL</span>. In other cases, the transmission to the
+ RADIUS server should only be considered obfuscated, not secured, and
+ external security measures should be applied if necessary.
+ </p></div><p>
+ </p></dd><dt><span class="term"><code class="literal">radiusports</code></span></dt><dd><p>
+ The port numbers to connect to on the RADIUS servers. If no port
+ is specified, the default RADIUS port (<code class="literal">1812</code>)
+ will be used.
+ </p></dd><dt><span class="term"><code class="literal">radiusidentifiers</code></span></dt><dd><p>
+ The strings to be used as <code class="literal">NAS Identifier</code> in the
+ RADIUS requests. This parameter can be used, for example, to
+ identify which database cluster the user is attempting to connect
+ to, which can be useful for policy matching on
+ the RADIUS server. If no identifier is specified, the default
+ <code class="literal">postgresql</code> will be used.
+ </p></dd></dl></div><p>
+ </p><p>
+ If it is necessary to have a comma or whitespace in a RADIUS parameter
+ value, that can be done by putting double quotes around the value, but
+ it is tedious because two layers of double-quoting are now required.
+ An example of putting whitespace into RADIUS secret strings is:
+</p><pre class="programlisting">
+host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""secret two"""
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-ldap.html" title="21.10. LDAP Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-cert.html" title="21.12. Certificate Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.10. LDAP Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.12. Certificate Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-trust.html b/doc/src/sgml/html/auth-trust.html
new file mode 100644
index 0000000..3f911e2
--- /dev/null
+++ b/doc/src/sgml/html/auth-trust.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.4. Trust Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-methods.html" title="21.3. Authentication Methods" /><link rel="next" href="auth-password.html" title="21.5. Password Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.4. Trust Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-methods.html" title="21.3. Authentication Methods">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-password.html" title="21.5. Password Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-TRUST"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.4. Trust Authentication</h2></div></div></div><p>
+ When <code class="literal">trust</code> authentication is specified,
+ <span class="productname">PostgreSQL</span> assumes that anyone who can
+ connect to the server is authorized to access the database with
+ whatever database user name they specify (even superuser names).
+ Of course, restrictions made in the <code class="literal">database</code> and
+ <code class="literal">user</code> columns still apply.
+ This method should only be used when there is adequate
+ operating-system-level protection on connections to the server.
+ </p><p>
+ <code class="literal">trust</code> authentication is appropriate and very
+ convenient for local connections on a single-user workstation. It
+ is usually <span class="emphasis"><em>not</em></span> appropriate by itself on a multiuser
+ machine. However, you might be able to use <code class="literal">trust</code> even
+ on a multiuser machine, if you restrict access to the server's
+ Unix-domain socket file using file-system permissions. To do this, set the
+ <code class="varname">unix_socket_permissions</code> (and possibly
+ <code class="varname">unix_socket_group</code>) configuration parameters as
+ described in <a class="xref" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Section 20.3</a>. Or you
+ could set the <code class="varname">unix_socket_directories</code>
+ configuration parameter to place the socket file in a suitably
+ restricted directory.
+ </p><p>
+ Setting file-system permissions only helps for Unix-socket connections.
+ Local TCP/IP connections are not restricted by file-system permissions.
+ Therefore, if you want to use file-system permissions for local security,
+ remove the <code class="literal">host ... 127.0.0.1 ...</code> line from
+ <code class="filename">pg_hba.conf</code>, or change it to a
+ non-<code class="literal">trust</code> authentication method.
+ </p><p>
+ <code class="literal">trust</code> authentication is only suitable for TCP/IP connections
+ if you trust every user on every machine that is allowed to connect
+ to the server by the <code class="filename">pg_hba.conf</code> lines that specify
+ <code class="literal">trust</code>. It is seldom reasonable to use <code class="literal">trust</code>
+ for any TCP/IP connections other than those from <span class="systemitem">localhost</span> (127.0.0.1).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-methods.html" title="21.3. Authentication Methods">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-password.html" title="21.5. Password Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.3. Authentication Methods </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.5. Password Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auth-username-maps.html b/doc/src/sgml/html/auth-username-maps.html
new file mode 100644
index 0000000..9e9d9c8
--- /dev/null
+++ b/doc/src/sgml/html/auth-username-maps.html
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.2. User Name Maps</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File" /><link rel="next" href="auth-methods.html" title="21.3. Authentication Methods" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.2. User Name Maps</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-methods.html" title="21.3. Authentication Methods">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-USERNAME-MAPS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.2. User Name Maps</h2></div></div></div><a id="id-1.6.8.9.2" class="indexterm"></a><p>
+ When using an external authentication system such as Ident or GSSAPI,
+ the name of the operating system user that initiated the connection
+ might not be the same as the database user (role) that is to be used.
+ In this case, a user name map can be applied to map the operating system
+ user name to a database user. To use user name mapping, specify
+ <code class="literal">map</code>=<em class="replaceable"><code>map-name</code></em>
+ in the options field in <code class="filename">pg_hba.conf</code>. This option is
+ supported for all authentication methods that receive external user names.
+ Since different mappings might be needed for different connections,
+ the name of the map to be used is specified in the
+ <em class="replaceable"><code>map-name</code></em> parameter in <code class="filename">pg_hba.conf</code>
+ to indicate which map to use for each individual connection.
+ </p><p>
+ User name maps are defined in the ident map file, which by default is named
+ <code class="filename">pg_ident.conf</code><a id="id-1.6.8.9.4.2" class="indexterm"></a>
+ and is stored in the
+ cluster's data directory. (It is possible to place the map file
+ elsewhere, however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-IDENT-FILE">ident_file</a>
+ configuration parameter.)
+ The ident map file contains lines of the general form:
+</p><pre class="synopsis">
+<em class="replaceable"><code>map-name</code></em> <em class="replaceable"><code>system-username</code></em> <em class="replaceable"><code>database-username</code></em>
+</pre><p>
+ Comments, whitespace and line continuations are handled in the same way as in
+ <code class="filename">pg_hba.conf</code>. The
+ <em class="replaceable"><code>map-name</code></em> is an arbitrary name that will be used to
+ refer to this mapping in <code class="filename">pg_hba.conf</code>. The other
+ two fields specify an operating system user name and a matching
+ database user name. The same <em class="replaceable"><code>map-name</code></em> can be
+ used repeatedly to specify multiple user-mappings within a single map.
+ </p><p>
+ There is no restriction regarding how many database users a given
+ operating system user can correspond to, nor vice versa. Thus, entries
+ in a map should be thought of as meaning <span class="quote">“<span class="quote">this operating system
+ user is allowed to connect as this database user</span>”</span>, rather than
+ implying that they are equivalent. The connection will be allowed if
+ there is any map entry that pairs the user name obtained from the
+ external authentication system with the database user name that the
+ user has requested to connect as.
+ </p><p>
+ If the <em class="replaceable"><code>system-username</code></em> field starts with a slash (<code class="literal">/</code>),
+ the remainder of the field is treated as a regular expression.
+ (See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of
+ <span class="productname">PostgreSQL</span>'s regular expression syntax.) The regular
+ expression can include a single capture, or parenthesized subexpression,
+ which can then be referenced in the <em class="replaceable"><code>database-username</code></em>
+ field as <code class="literal">\1</code> (backslash-one). This allows the mapping of
+ multiple user names in a single line, which is particularly useful for
+ simple syntax substitutions. For example, these entries
+</p><pre class="programlisting">
+mymap /^(.*)@mydomain\.com$ \1
+mymap /^(.*)@otherdomain\.com$ guest
+</pre><p>
+ will remove the domain part for users with system user names that end with
+ <code class="literal">@mydomain.com</code>, and allow any user whose system name ends with
+ <code class="literal">@otherdomain.com</code> to log in as <code class="literal">guest</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Keep in mind that by default, a regular expression can match just part of
+ a string. It's usually wise to use <code class="literal">^</code> and <code class="literal">$</code>, as
+ shown in the above example, to force the match to be to the entire
+ system user name.
+ </p></div><p>
+ The <code class="filename">pg_ident.conf</code> file is read on start-up and
+ when the main server process receives a
+ <span class="systemitem">SIGHUP</span><a id="id-1.6.8.9.8.3" class="indexterm"></a>
+ signal. If you edit the file on an
+ active system, you will need to signal the postmaster
+ (using <code class="literal">pg_ctl reload</code>, calling the SQL function
+ <code class="function">pg_reload_conf()</code>, or using <code class="literal">kill
+ -HUP</code>) to make it re-read the file.
+ </p><p>
+ The system view
+ <a class="link" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings"><code class="structname">pg_ident_file_mappings</code></a>
+ can be helpful for pre-testing changes to the
+ <code class="filename">pg_ident.conf</code> file, or for diagnosing problems if
+ loading of the file did not have the desired effects. Rows in the view with
+ non-null <code class="structfield">error</code> fields indicate problems in the
+ corresponding lines of the file.
+ </p><p>
+ A <code class="filename">pg_ident.conf</code> file that could be used in
+ conjunction with the <code class="filename">pg_hba.conf</code> file in <a class="xref" href="auth-pg-hba-conf.html#EXAMPLE-PG-HBA.CONF" title="Example 21.1. Example pg_hba.conf Entries">Example 21.1</a> is shown in <a class="xref" href="auth-username-maps.html#EXAMPLE-PG-IDENT.CONF" title="Example 21.2. An Example pg_ident.conf File">Example 21.2</a>. In this example, anyone
+ logged in to a machine on the 192.168 network that does not have the
+ operating system user name <code class="literal">bryanh</code>, <code class="literal">ann</code>, or
+ <code class="literal">robert</code> would not be granted access. Unix user
+ <code class="literal">robert</code> would only be allowed access when he tries to
+ connect as <span class="productname">PostgreSQL</span> user <code class="literal">bob</code>, not
+ as <code class="literal">robert</code> or anyone else. <code class="literal">ann</code> would
+ only be allowed to connect as <code class="literal">ann</code>. User
+ <code class="literal">bryanh</code> would be allowed to connect as either
+ <code class="literal">bryanh</code> or as <code class="literal">guest1</code>.
+ </p><div class="example" id="EXAMPLE-PG-IDENT.CONF"><p class="title"><strong>Example 21.2. An Example <code class="filename">pg_ident.conf</code> File</strong></p><div class="example-contents"><pre class="programlisting">
+# MAPNAME SYSTEM-USERNAME PG-USERNAME
+
+omicron bryanh bryanh
+omicron ann ann
+# bob has user name robert on these machines
+omicron robert bob
+# bryanh can also connect as guest1
+omicron bryanh guest1
+</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-methods.html" title="21.3. Authentication Methods">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.1. The <code class="filename">pg_hba.conf</code> File </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.3. Authentication Methods</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/auto-explain.html b/doc/src/sgml/html/auto-explain.html
new file mode 100644
index 0000000..f94ea4b
--- /dev/null
+++ b/doc/src/sgml/html/auto-explain.html
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.4. auto_explain</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-delay.html" title="F.3. auth_delay" /><link rel="next" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.4. auto_explain</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-delay.html" title="F.3. auth_delay">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTO-EXPLAIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.4. auto_explain</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.5">F.4.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.6">F.4.2. Example</a></span></dt><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.7">F.4.3. Author</a></span></dt></dl></div><a id="id-1.11.7.13.2" class="indexterm"></a><p>
+ The <code class="filename">auto_explain</code> module provides a means for
+ logging execution plans of slow statements automatically, without
+ having to run <a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a>
+ by hand. This is especially helpful for tracking down un-optimized queries
+ in large applications.
+ </p><p>
+ The module provides no SQL-accessible functions. To use it, simply
+ load it into the server. You can load it into an individual session:
+
+</p><pre class="programlisting">
+LOAD 'auto_explain';
+</pre><p>
+
+ (You must be superuser to do that.) More typical usage is to preload
+ it into some or all sessions by including <code class="literal">auto_explain</code> in
+ <a class="xref" href="runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES">session_preload_libraries</a> or
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> in
+ <code class="filename">postgresql.conf</code>. Then you can track unexpectedly slow queries
+ no matter when they happen. Of course there is a price in overhead for
+ that.
+ </p><div class="sect2" id="id-1.11.7.13.5"><div class="titlepage"><div><div><h3 class="title">F.4.1. Configuration Parameters</h3></div></div></div><p>
+ There are several configuration parameters that control the behavior of
+ <code class="filename">auto_explain</code>. Note that the default behavior is
+ to do nothing, so you must set at least
+ <code class="varname">auto_explain.log_min_duration</code> if you want any results.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">auto_explain.log_min_duration</code> (<code class="type">integer</code>)
+ <a id="id-1.11.7.13.5.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_min_duration</code> is the minimum statement
+ execution time, in milliseconds, that will cause the statement's plan to
+ be logged. Setting this to <code class="literal">0</code> logs all plans.
+ <code class="literal">-1</code> (the default) disables logging of plans. For
+ example, if you set it to <code class="literal">250ms</code> then all statements
+ that run 250ms or longer will be logged. Only superusers can change this
+ setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_analyze</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_analyze</code> causes <code class="command">EXPLAIN ANALYZE</code>
+ output, rather than just <code class="command">EXPLAIN</code> output, to be printed
+ when an execution plan is logged. This parameter is off by default.
+ Only superusers can change this setting.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When this parameter is on, per-plan-node timing occurs for all
+ statements executed, whether or not they run long enough to actually
+ get logged. This can have an extremely negative impact on performance.
+ Turning off <code class="varname">auto_explain.log_timing</code> ameliorates the
+ performance cost, at the price of obtaining less information.
+ </p></div></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_buffers</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_buffers</code> controls whether buffer
+ usage statistics are printed when an execution plan is logged; it's
+ equivalent to the <code class="literal">BUFFERS</code> option of <code class="command">EXPLAIN</code>.
+ This parameter has no effect
+ unless <code class="varname">auto_explain.log_analyze</code> is enabled.
+ This parameter is off by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_wal</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_wal</code> controls whether WAL
+ usage statistics are printed when an execution plan is logged; it's
+ equivalent to the <code class="literal">WAL</code> option of <code class="command">EXPLAIN</code>.
+ This parameter has no effect
+ unless <code class="varname">auto_explain.log_analyze</code> is enabled.
+ This parameter is off by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_timing</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_timing</code> controls whether per-node
+ timing information is printed when an execution plan is logged; it's
+ equivalent to the <code class="literal">TIMING</code> option of <code class="command">EXPLAIN</code>.
+ The overhead of repeatedly reading the system clock can slow down
+ queries significantly on some systems, so it may be useful to set this
+ parameter to off when only actual row counts, and not exact times, are
+ needed.
+ This parameter has no effect
+ unless <code class="varname">auto_explain.log_analyze</code> is enabled.
+ This parameter is on by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_triggers</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_triggers</code> causes trigger
+ execution statistics to be included when an execution plan is logged.
+ This parameter has no effect
+ unless <code class="varname">auto_explain.log_analyze</code> is enabled.
+ This parameter is off by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_verbose</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_verbose</code> controls whether verbose
+ details are printed when an execution plan is logged; it's
+ equivalent to the <code class="literal">VERBOSE</code> option of <code class="command">EXPLAIN</code>.
+ This parameter is off by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_settings</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_settings</code> controls whether information
+ about modified configuration options is printed when an execution plan is logged.
+ Only options affecting query planning with value different from the built-in
+ default value are included in the output. This parameter is off by default.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_format</code> (<code class="type">enum</code>)
+ <a id="id-1.11.7.13.5.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_format</code> selects the
+ <code class="command">EXPLAIN</code> output format to be used.
+ The allowed values are <code class="literal">text</code>, <code class="literal">xml</code>,
+ <code class="literal">json</code>, and <code class="literal">yaml</code>. The default is text.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_level</code> (<code class="type">enum</code>)
+ <a id="id-1.11.7.13.5.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_level</code> selects the log level at which
+ auto_explain will log the query plan.
+ Valid values are <code class="literal">DEBUG5</code>, <code class="literal">DEBUG4</code>,
+ <code class="literal">DEBUG3</code>, <code class="literal">DEBUG2</code>,
+ <code class="literal">DEBUG1</code>, <code class="literal">INFO</code>,
+ <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>,
+ and <code class="literal">LOG</code>. The default is <code class="literal">LOG</code>.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.log_nested_statements</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.13.5.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.log_nested_statements</code> causes nested
+ statements (statements executed inside a function) to be considered
+ for logging. When it is off, only top-level query plans are logged. This
+ parameter is off by default. Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">auto_explain.sample_rate</code> (<code class="type">real</code>)
+ <a id="id-1.11.7.13.5.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">auto_explain.sample_rate</code> causes auto_explain to only
+ explain a fraction of the statements in each session. The default is 1,
+ meaning explain all the queries. In case of nested statements, either all
+ will be explained or none. Only superusers can change this setting.
+ </p></dd></dl></div><p>
+ In ordinary usage, these parameters are set
+ in <code class="filename">postgresql.conf</code>, although superusers can alter them
+ on-the-fly within their own sessions.
+ Typical usage might be:
+ </p><pre class="programlisting">
+# postgresql.conf
+session_preload_libraries = 'auto_explain'
+
+auto_explain.log_min_duration = '3s'
+</pre></div><div class="sect2" id="id-1.11.7.13.6"><div class="titlepage"><div><div><h3 class="title">F.4.2. Example</h3></div></div></div><pre class="programlisting">
+postgres=# LOAD 'auto_explain';
+postgres=# SET auto_explain.log_min_duration = 0;
+postgres=# SET auto_explain.log_analyze = true;
+postgres=# SELECT count(*)
+ FROM pg_class, pg_index
+ WHERE oid = indrelid AND indisunique;
+</pre><p>
+ This might produce log output such as:
+ </p><pre class="screen">
+LOG: duration: 3.651 ms plan:
+ Query Text: SELECT count(*)
+ FROM pg_class, pg_index
+ WHERE oid = indrelid AND indisunique;
+ Aggregate (cost=16.79..16.80 rows=1 width=0) (actual time=3.626..3.627 rows=1 loops=1)
+ -&gt; Hash Join (cost=4.17..16.55 rows=92 width=0) (actual time=3.349..3.594 rows=92 loops=1)
+ Hash Cond: (pg_class.oid = pg_index.indrelid)
+ -&gt; Seq Scan on pg_class (cost=0.00..9.55 rows=255 width=4) (actual time=0.016..0.140 rows=255 loops=1)
+ -&gt; Hash (cost=3.02..3.02 rows=92 width=4) (actual time=3.238..3.238 rows=92 loops=1)
+ Buckets: 1024 Batches: 1 Memory Usage: 4kB
+ -&gt; Seq Scan on pg_index (cost=0.00..3.02 rows=92 width=4) (actual time=0.008..3.187 rows=92 loops=1)
+ Filter: indisunique
+</pre></div><div class="sect2" id="id-1.11.7.13.7"><div class="titlepage"><div><div><h3 class="title">F.4.3. Author</h3></div></div></div><p>
+ Takahiro Itagaki <code class="email">&lt;<a class="email" href="mailto:itagaki.takahiro@oss.ntt.co.jp">itagaki.takahiro@oss.ntt.co.jp</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-delay.html" title="F.3. auth_delay">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.3. auth_delay </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.5. basebackup_to_shell</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-dump.html b/doc/src/sgml/html/backup-dump.html
new file mode 100644
index 0000000..4515c67
--- /dev/null
+++ b/doc/src/sgml/html/backup-dump.html
@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>26.1. SQL Dump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup.html" title="Chapter 26. Backup and Restore" /><link rel="next" href="backup-file.html" title="26.2. File System Level Backup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">26.1. <acronym class="acronym">SQL</acronym> Dump</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup.html" title="Chapter 26. Backup and Restore">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><th width="60%" align="center">Chapter 26. Backup and Restore</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-file.html" title="26.2. File System Level Backup">Next</a></td></tr></table><hr /></div><div class="sect1" id="BACKUP-DUMP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">26.1. <acronym class="acronym">SQL</acronym> Dump</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-RESTORE">26.1.1. Restoring the Dump</a></span></dt><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-ALL">26.1.2. Using <span class="application">pg_dumpall</span></a></span></dt><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-LARGE">26.1.3. Handling Large Databases</a></span></dt></dl></div><p>
+ The idea behind this dump method is to generate a file with SQL
+ 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.
+ <span class="productname">PostgreSQL</span> provides the utility program
+ <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> for this purpose. The basic usage of this
+ command is:
+</p><pre class="synopsis">
+pg_dump <em class="replaceable"><code>dbname</code></em> &gt; <em class="replaceable"><code>dumpfile</code></em>
+</pre><p>
+ As you see, <span class="application">pg_dump</span> writes its result to the
+ standard output. We will see below how this can be useful.
+ While the above command creates a text file, <span class="application">pg_dump</span>
+ can create files in other formats that allow for parallelism and more
+ fine-grained control of object restoration.
+ </p><p>
+ <span class="application">pg_dump</span> is a regular <span class="productname">PostgreSQL</span>
+ client application (albeit a particularly clever one). This means
+ that you can perform this backup procedure from any remote host that has
+ access to the database. But remember that <span class="application">pg_dump</span>
+ does not operate with special permissions. In particular, it must
+ have read access to all tables that you want to back up, so in order
+ to back up the entire database you almost always have to run it as a
+ database superuser. (If you do not have sufficient privileges to back up
+ the entire database, you can still back up portions of the database to which
+ you do have access using options such as
+ <code class="option">-n <em class="replaceable"><code>schema</code></em></code>
+ or <code class="option">-t <em class="replaceable"><code>table</code></em></code>.)
+ </p><p>
+ To specify which database server <span class="application">pg_dump</span> should
+ contact, use the command line options <code class="option">-h
+ <em class="replaceable"><code>host</code></em></code> and <code class="option">-p <em class="replaceable"><code>port</code></em></code>. The
+ default host is the local host or whatever your
+ <code class="envar">PGHOST</code> environment variable specifies. Similarly,
+ the default port is indicated by the <code class="envar">PGPORT</code>
+ environment variable or, failing that, by the compiled-in default.
+ (Conveniently, the server will normally have the same compiled-in
+ default.)
+ </p><p>
+ Like any other <span class="productname">PostgreSQL</span> client application,
+ <span class="application">pg_dump</span> will by default connect with the database
+ user name that is equal to the current operating system user name. To override
+ this, either specify the <code class="option">-U</code> option or set the
+ environment variable <code class="envar">PGUSER</code>. Remember that
+ <span class="application">pg_dump</span> connections are subject to the normal
+ client authentication mechanisms (which are described in <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>).
+ </p><p>
+ An important advantage of <span class="application">pg_dump</span> over the other backup
+ methods described later is that <span class="application">pg_dump</span>'s output can
+ generally be re-loaded into newer versions of <span class="productname">PostgreSQL</span>,
+ whereas file-level backups and continuous archiving are both extremely
+ server-version-specific. <span class="application">pg_dump</span> is also the only method
+ that will work when transferring a database to a different machine
+ architecture, such as going from a 32-bit to a 64-bit server.
+ </p><p>
+ Dumps created by <span class="application">pg_dump</span> are internally consistent,
+ meaning, the dump represents a snapshot of the database at the time
+ <span class="application">pg_dump</span> began running. <span class="application">pg_dump</span> does not
+ block other operations on the database while it is working.
+ (Exceptions are those operations that need to operate with an
+ exclusive lock, such as most forms of <code class="command">ALTER TABLE</code>.)
+ </p><div class="sect2" id="BACKUP-DUMP-RESTORE"><div class="titlepage"><div><div><h3 class="title">26.1.1. Restoring the Dump</h3></div></div></div><p>
+ Text files created by <span class="application">pg_dump</span> are intended to
+ be read in by the <span class="application">psql</span> program. The
+ general command form to restore a dump is
+</p><pre class="synopsis">
+psql <em class="replaceable"><code>dbname</code></em> &lt; <em class="replaceable"><code>dumpfile</code></em>
+</pre><p>
+ where <em class="replaceable"><code>dumpfile</code></em> is the
+ file output by the <span class="application">pg_dump</span> command. The database <em class="replaceable"><code>dbname</code></em> will not be created by this
+ command, so you must create it yourself from <code class="literal">template0</code>
+ before executing <span class="application">psql</span> (e.g., with
+ <code class="literal">createdb -T template0 <em class="replaceable"><code>dbname</code></em></code>). <span class="application">psql</span>
+ supports options similar to <span class="application">pg_dump</span> for specifying
+ the database server to connect to and the user name to use. See
+ the <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> reference page for more information.
+ Non-text file dumps are restored using the <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a> utility.
+ </p><p>
+ Before restoring an SQL dump, all the users who own objects or were
+ granted permissions on objects in the dumped database must already
+ exist. If they do not, the restore will fail to recreate the
+ objects with the original ownership and/or permissions.
+ (Sometimes this is what you want, but usually it is not.)
+ </p><p>
+ By default, the <span class="application">psql</span> script will continue to
+ execute after an SQL error is encountered. You might wish to run
+ <span class="application">psql</span> with
+ the <code class="literal">ON_ERROR_STOP</code> variable set to alter that
+ behavior and have <span class="application">psql</span> exit with an
+ exit status of 3 if an SQL error occurs:
+</p><pre class="programlisting">
+psql --set ON_ERROR_STOP=on <em class="replaceable"><code>dbname</code></em> &lt; <em class="replaceable"><code>dumpfile</code></em>
+</pre><p>
+ Either way, you will only have a partially restored database.
+ Alternatively, you can specify that the whole dump should be
+ restored as a single transaction, so the restore is either fully
+ completed or fully rolled back. This mode can be specified by
+ passing the <code class="option">-1</code> or <code class="option">--single-transaction</code>
+ command-line options to <span class="application">psql</span>. When using this
+ mode, be aware that even a minor error can rollback a
+ restore that has already run for many hours. However, that might
+ still be preferable to manually cleaning up a complex database
+ after a partially restored dump.
+ </p><p>
+ The ability of <span class="application">pg_dump</span> and <span class="application">psql</span> to
+ write to or read from pipes makes it possible to dump a database
+ directly from one server to another, for example:
+</p><pre class="programlisting">
+pg_dump -h <em class="replaceable"><code>host1</code></em> <em class="replaceable"><code>dbname</code></em> | psql -h <em class="replaceable"><code>host2</code></em> <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+ </p><div class="important"><h3 class="title">Important</h3><p>
+ The dumps produced by <span class="application">pg_dump</span> are relative to
+ <code class="literal">template0</code>. This means that any languages, procedures,
+ etc. added via <code class="literal">template1</code> will also be dumped by
+ <span class="application">pg_dump</span>. As a result, when restoring, if you are
+ using a customized <code class="literal">template1</code>, you must create the
+ empty database from <code class="literal">template0</code>, as in the example
+ above.
+ </p></div><p>
+ After restoring a backup, it is wise to run <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> on each
+ database so the query optimizer has useful statistics;
+ see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>
+ and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ For more advice on how to load large amounts of data
+ into <span class="productname">PostgreSQL</span> efficiently, refer to <a class="xref" href="populate.html" title="14.4. Populating a Database">Section 14.4</a>.
+ </p></div><div class="sect2" id="BACKUP-DUMP-ALL"><div class="titlepage"><div><div><h3 class="title">26.1.2. Using <span class="application">pg_dumpall</span></h3></div></div></div><p>
+ <span class="application">pg_dump</span> dumps only a single database at a time,
+ 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 <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a> program is provided.
+ <span class="application">pg_dumpall</span> 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:
+</p><pre class="synopsis">
+pg_dumpall &gt; <em class="replaceable"><code>dumpfile</code></em>
+</pre><p>
+ The resulting dump can be restored with <span class="application">psql</span>:
+</p><pre class="synopsis">
+psql -f <em class="replaceable"><code>dumpfile</code></em> postgres
+</pre><p>
+ (Actually, you can specify any existing database name to start from,
+ but if you are loading into an empty cluster then <code class="literal">postgres</code>
+ should usually be used.) It is always necessary to have
+ database superuser access when restoring a <span class="application">pg_dumpall</span>
+ dump, as that is required to restore the role and tablespace information.
+ If you use tablespaces, make sure that the tablespace paths in the
+ dump are appropriate for the new installation.
+ </p><p>
+ <span class="application">pg_dumpall</span> works by emitting commands to re-create
+ roles, tablespaces, and empty databases, then invoking
+ <span class="application">pg_dump</span> for each database. This means that while
+ each database will be internally consistent, the snapshots of
+ different databases are not synchronized.
+ </p><p>
+ Cluster-wide data can be dumped alone using the
+ <span class="application">pg_dumpall</span> <code class="option">--globals-only</code> option.
+ This is necessary to fully backup the cluster if running the
+ <span class="application">pg_dump</span> command on individual databases.
+ </p></div><div class="sect2" id="BACKUP-DUMP-LARGE"><div class="titlepage"><div><div><h3 class="title">26.1.3. Handling Large Databases</h3></div></div></div><p>
+ Some operating systems have maximum file size limits that cause
+ problems when creating large <span class="application">pg_dump</span> output files.
+ Fortunately, <span class="application">pg_dump</span> can write to the standard
+ output, so you can use standard Unix tools to work around this
+ potential problem. There are several possible methods:
+ </p><p><strong>Use compressed dumps. </strong>
+ You can use your favorite compression program, for example
+ <span class="application">gzip</span>:
+
+</p><pre class="programlisting">
+pg_dump <em class="replaceable"><code>dbname</code></em> | gzip &gt; <em class="replaceable"><code>filename</code></em>.gz
+</pre><p>
+
+ Reload with:
+
+</p><pre class="programlisting">
+gunzip -c <em class="replaceable"><code>filename</code></em>.gz | psql <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ or:
+
+</p><pre class="programlisting">
+cat <em class="replaceable"><code>filename</code></em>.gz | gunzip | psql <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+ </p><p><strong>Use <code class="command">split</code>. </strong>
+ The <code class="command">split</code> command
+ allows you to split the output into smaller files that are
+ acceptable in size to the underlying file system. For example, to
+ make 2 gigabyte chunks:
+
+</p><pre class="programlisting">
+pg_dump <em class="replaceable"><code>dbname</code></em> | split -b 2G - <em class="replaceable"><code>filename</code></em>
+</pre><p>
+
+ Reload with:
+
+</p><pre class="programlisting">
+cat <em class="replaceable"><code>filename</code></em>* | psql <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ If using GNU <span class="application">split</span>, it is possible to
+ use it and <span class="application">gzip</span> together:
+
+</p><pre class="programlisting">
+pg_dump <em class="replaceable"><code>dbname</code></em> | split -b 2G --filter='gzip &gt; $FILE.gz'
+</pre><p>
+
+ It can be restored using <code class="command">zcat</code>.
+ </p><p><strong>Use <span class="application">pg_dump</span>'s custom dump format. </strong>
+ If <span class="productname">PostgreSQL</span> was built on a system with the
+ <span class="application">zlib</span> compression library installed, the custom dump
+ format will compress data as it writes it to the output file. This will
+ produce dump file sizes similar to using <code class="command">gzip</code>, but it
+ has the added advantage that tables can be restored selectively. The
+ following command dumps a database using the custom dump format:
+
+</p><pre class="programlisting">
+pg_dump -Fc <em class="replaceable"><code>dbname</code></em> &gt; <em class="replaceable"><code>filename</code></em>
+</pre><p>
+
+ A custom-format dump is not a script for <span class="application">psql</span>, but
+ instead must be restored with <span class="application">pg_restore</span>, for example:
+
+</p><pre class="programlisting">
+pg_restore -d <em class="replaceable"><code>dbname</code></em> <em class="replaceable"><code>filename</code></em>
+</pre><p>
+
+ See the <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> and <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a> reference pages for details.
+ </p><p>
+ For very large databases, you might need to combine <code class="command">split</code>
+ with one of the other two approaches.
+ </p><p><strong>Use <span class="application">pg_dump</span>'s parallel dump feature. </strong>
+ To speed up the dump of a large database, you can use
+ <span class="application">pg_dump</span>'s parallel mode. This will dump
+ multiple tables at the same time. You can control the degree of
+ parallelism with the <code class="command">-j</code> parameter. Parallel dumps
+ are only supported for the "directory" archive format.
+
+</p><pre class="programlisting">
+pg_dump -j <em class="replaceable"><code>num</code></em> -F d -f <em class="replaceable"><code>out.dir</code></em> <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ You can use <code class="command">pg_restore -j</code> to restore a dump in parallel.
+ This will work for any archive of either the "custom" or the "directory"
+ archive mode, whether or not it has been created with <code class="command">pg_dump -j</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup.html" title="Chapter 26. Backup and Restore">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-file.html" title="26.2. File System Level Backup">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. Backup and Restore </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 26.2. File System Level Backup</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-file.html b/doc/src/sgml/html/backup-file.html
new file mode 100644
index 0000000..cdc50c2
--- /dev/null
+++ b/doc/src/sgml/html/backup-file.html
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>26.2. File System Level Backup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-dump.html" title="26.1. SQL Dump" /><link rel="next" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">26.2. File System Level Backup</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-dump.html" title="26.1. SQL Dump">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><th width="60%" align="center">Chapter 26. Backup and Restore</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Next</a></td></tr></table><hr /></div><div class="sect1" id="BACKUP-FILE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">26.2. File System Level Backup</h2></div></div></div><p>
+ An alternative backup strategy is to directly copy the files that
+ <span class="productname">PostgreSQL</span> uses to store the data in the database;
+ <a class="xref" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Section 19.2</a> explains where these files
+ are located. You can use whatever method you prefer
+ for doing file system backups; for example:
+
+</p><pre class="programlisting">
+tar -cf backup.tar /usr/local/pgsql/data
+</pre><p>
+ </p><p>
+ There are two restrictions, however, which make this method
+ impractical, or at least inferior to the <span class="application">pg_dump</span>
+ method:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ The database server <span class="emphasis"><em>must</em></span> be shut down in order to
+ get a usable backup. Half-way measures such as disallowing all
+ connections will <span class="emphasis"><em>not</em></span> work
+ (in part because <code class="command">tar</code> and similar tools do not take
+ 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
+ <a class="xref" href="server-shutdown.html" title="19.5. Shutting Down the Server">Section 19.5</a>. Needless to say, you
+ also need to shut down the server before restoring the data.
+ </p></li><li class="listitem"><p>
+ If you have dug into the details of the file system layout of the
+ database, you might be tempted to try to back up or restore only certain
+ individual tables or databases from their respective files or
+ directories. This will <span class="emphasis"><em>not</em></span> work because the
+ information contained in these files is not usable without
+ the commit log files,
+ <code class="filename">pg_xact/*</code>, which contain the commit status of
+ all transactions. A table file is only usable with this
+ information. Of course it is also impossible to restore only a
+ table and the associated <code class="filename">pg_xact</code> data
+ because that would render all other tables in the database
+ cluster useless. So file system backups only work for complete
+ backup and restoration of an entire database cluster.
+ </p></li></ol></div><p>
+ </p><p>
+ An alternative file-system backup approach is to make a
+ <span class="quote">“<span class="quote">consistent snapshot</span>”</span> of the data directory, if the
+ file system supports that functionality (and you are willing to
+ trust that it is implemented correctly). The typical procedure is
+ to make a <span class="quote">“<span class="quote">frozen snapshot</span>”</span> of the volume containing the
+ database, then copy the whole data directory (not just parts, see
+ above) from the snapshot to a backup device, then release the frozen
+ snapshot. This will work even while the database server is running.
+ However, a backup created in this way saves
+ the database files in a state as if the database server was not
+ properly shut down; therefore, when you start the database server
+ on the backed-up data, it will think the previous server instance
+ crashed and will replay the WAL log. This is not a problem; just
+ be aware of it (and be sure to include the WAL files in your backup).
+ You can perform a <code class="command">CHECKPOINT</code> before taking the
+ snapshot to reduce recovery time.
+ </p><p>
+ If your database is spread across multiple file systems, there might not
+ be any way to obtain exactly-simultaneous frozen snapshots of all
+ the volumes. For example, if your data files and WAL log are on different
+ disks, or if tablespaces are on different file systems, it might
+ not be possible to use snapshot backup because the snapshots
+ <span class="emphasis"><em>must</em></span> be simultaneous.
+ Read your file system documentation very carefully before trusting
+ the consistent-snapshot technique in such situations.
+ </p><p>
+ 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 (<a class="xref" href="continuous-archiving.html#BACKUP-BASE-BACKUP" title="26.3.2. Making a Base Backup">Section 26.3.2</a>) 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 (<a class="xref" href="continuous-archiving.html#BACKUP-PITR-RECOVERY" title="26.3.4. Recovering Using a Continuous Archive Backup">Section 26.3.4</a>).
+ </p><p>
+ Another option is to use <span class="application">rsync</span> to perform a file
+ system backup. This is done by first running <span class="application">rsync</span>
+ while the database server is running, then shutting down the database
+ server long enough to do an <code class="command">rsync --checksum</code>.
+ (<code class="option">--checksum</code> is necessary because <code class="command">rsync</code> only
+ has file modification-time granularity of one second.) The
+ second <span class="application">rsync</span> will be quicker than the first,
+ because it has relatively little data to transfer, and the end result
+ will be consistent because the server was down. This method
+ allows a file system backup to be performed with minimal downtime.
+ </p><p>
+ Note that a file system backup will typically be larger
+ than an SQL dump. (<span class="application">pg_dump</span> does not need to dump
+ the contents of indexes for example, just the commands to recreate
+ them.) However, taking a file system backup might be faster.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-dump.html" title="26.1. SQL Dump">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">26.1. <acronym class="acronym">SQL</acronym> Dump </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-manifest-files.html b/doc/src/sgml/html/backup-manifest-files.html
new file mode 100644
index 0000000..b2f9d43
--- /dev/null
+++ b/doc/src/sgml/html/backup-manifest-files.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>76.2. Backup Manifest File Object</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object" /><link rel="next" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">76.2. Backup Manifest File Object</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><th width="60%" align="center">Chapter 76. Backup Manifest Format</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object">Next</a></td></tr></table><hr /></div><div class="sect1" id="BACKUP-MANIFEST-FILES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">76.2. Backup Manifest File Object</h2></div></div></div><p>
+ The object which describes a single file contains either a
+ <code class="literal">Path</code> key or an <code class="literal">Encoded-Path</code> key.
+ Normally, the <code class="literal">Path</code> key will be present. The
+ associated string value is the path of the file relative to the root
+ of the backup directory. Files located in a user-defined tablespace
+ will have paths whose first two components are <code class="filename">pg_tblspc</code> and the OID
+ of the tablespace. If the path is not a string that is legal in UTF-8,
+ or if the user requests that encoded paths be used for all files, then
+ the <code class="literal">Encoded-Path</code> key will be present instead. This
+ stores the same data, but it is encoded as a string of hexadecimal
+ digits. Each pair of hexadecimal digits in the string represents a
+ single octet.
+ </p><p>
+ The following two keys are always present:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Size</code></span></dt><dd><p>
+ The expected size of this file, as an integer.
+ </p></dd><dt><span class="term"><code class="literal">Last-Modified</code></span></dt><dd><p>
+ The last modification time of the file as reported by the server at
+ the time of the backup. Unlike the other fields stored in the backup,
+ this field is not used by <a class="xref" href="app-pgverifybackup.html" title="pg_verifybackup"><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></a>.
+ It is included only for informational purposes.
+ </p></dd></dl></div><p>
+ If the backup was taken with file checksums enabled, the following
+ keys will be present:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Checksum-Algorithm</code></span></dt><dd><p>
+ The checksum algorithm used to compute a checksum for this file.
+ Currently, this will be the same for every file in the backup
+ manifest, but this may change in future releases. At present, the
+ supported checksum algorithms are <code class="literal">CRC32C</code>,
+ <code class="literal">SHA224</code>,
+ <code class="literal">SHA256</code>,
+ <code class="literal">SHA384</code>, and
+ <code class="literal">SHA512</code>.
+ </p></dd><dt><span class="term"><code class="literal">Checksum</code></span></dt><dd><p>
+ The checksum computed for this file, stored as a series of
+ hexadecimal characters, two for each byte of the checksum.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object">Next</a></td></tr><tr><td width="40%" align="left" valign="top">76.1. Backup Manifest Top-level Object </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 76.3. Backup Manifest WAL Range Object</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-manifest-format.html b/doc/src/sgml/html/backup-manifest-format.html
new file mode 100644
index 0000000..ea78388
--- /dev/null
+++ b/doc/src/sgml/html/backup-manifest-format.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 76. Backup Manifest Format</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="planner-stats-security.html" title="75.3. Planner Statistics and Security" /><link rel="next" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 76. Backup Manifest Format</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="planner-stats-security.html" title="75.3. Planner Statistics and Security">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object">Next</a></td></tr></table><hr /></div><div class="chapter" id="BACKUP-MANIFEST-FORMAT"><div class="titlepage"><div><div><h2 class="title">Chapter 76. Backup Manifest Format</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="backup-manifest-toplevel.html">76.1. Backup Manifest Top-level Object</a></span></dt><dt><span class="sect1"><a href="backup-manifest-files.html">76.2. Backup Manifest File Object</a></span></dt><dt><span class="sect1"><a href="backup-manifest-wal-ranges.html">76.3. Backup Manifest WAL Range Object</a></span></dt></dl></div><a id="id-1.10.27.2" class="indexterm"></a><p>
+ The backup manifest generated by <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a> is
+ primarily intended to permit the backup to be verified using
+ <a class="xref" href="app-pgverifybackup.html" title="pg_verifybackup"><span class="refentrytitle"><span class="application">pg_verifybackup</span></span></a>. However, it is
+ also possible for other tools to read the backup manifest file and use
+ the information contained therein for their own purposes. To that end,
+ this chapter describes the format of the backup manifest file.
+ </p><p>
+ A backup manifest is a JSON document encoded as UTF-8. (Although in
+ general JSON documents are required to be Unicode, PostgreSQL permits
+ the <code class="type">json</code> and <code class="type">jsonb</code> data types to be used with any
+ supported server encoding. There is no similar exception for backup
+ manifests.) The JSON document is always an object; the keys that are present
+ in this object are described in the next section.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="planner-stats-security.html" title="75.3. Planner Statistics and Security">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-manifest-toplevel.html" title="76.1. Backup Manifest Top-level Object">Next</a></td></tr><tr><td width="40%" align="left" valign="top">75.3. Planner Statistics and Security </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 76.1. Backup Manifest Top-level Object</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-manifest-toplevel.html b/doc/src/sgml/html/backup-manifest-toplevel.html
new file mode 100644
index 0000000..88642c8
--- /dev/null
+++ b/doc/src/sgml/html/backup-manifest-toplevel.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>76.1. Backup Manifest Top-level Object</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format" /><link rel="next" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">76.1. Backup Manifest Top-level Object</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><th width="60%" align="center">Chapter 76. Backup Manifest Format</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object">Next</a></td></tr></table><hr /></div><div class="sect1" id="BACKUP-MANIFEST-TOPLEVEL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">76.1. Backup Manifest Top-level Object</h2></div></div></div><p>
+ The backup manifest JSON document contains the following keys.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PostgreSQL-Backup-Manifest-Version</code></span></dt><dd><p>
+ The associated value is always the integer 1.
+ </p></dd><dt><span class="term"><code class="literal">Files</code></span></dt><dd><p>
+ The associated value is always a list of objects, each describing one
+ file that is present in the backup. No entries are present in this
+ list for the WAL files that are needed in order to use the backup,
+ or for the backup manifest itself. The structure of each object in the
+ list is described in <a class="xref" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object">Section 76.2</a>.
+ </p></dd><dt><span class="term"><code class="literal">WAL-Ranges</code></span></dt><dd><p>
+ The associated value is always a list of objects, each describing a
+ range of WAL records that must be readable from a particular timeline
+ in order to make use of the backup. The structure of these objects is
+ further described in <a class="xref" href="backup-manifest-wal-ranges.html" title="76.3. Backup Manifest WAL Range Object">Section 76.3</a>.
+ </p></dd><dt><span class="term"><code class="literal">Manifest-Checksum</code></span></dt><dd><p>
+ This key is always present on the last line of the backup manifest file.
+ The associated value is a SHA256 checksum of all the preceding lines.
+ We use a fixed checksum method here to make it possible for clients
+ to do incremental parsing of the manifest. While a SHA256 checksum
+ is significantly more expensive than a CRC32C checksum, the manifest
+ should normally be small enough that the extra computation won't matter
+ very much.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 76. Backup Manifest Format </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 76.2. Backup Manifest File Object</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup-manifest-wal-ranges.html b/doc/src/sgml/html/backup-manifest-wal-ranges.html
new file mode 100644
index 0000000..29889a6
--- /dev/null
+++ b/doc/src/sgml/html/backup-manifest-wal-ranges.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>76.3. Backup Manifest WAL Range Object</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object" /><link rel="next" href="appendixes.html" title="Part VIII. Appendixes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">76.3. Backup Manifest WAL Range Object</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><th width="60%" align="center">Chapter 76. Backup Manifest Format</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="appendixes.html" title="Part VIII. Appendixes">Next</a></td></tr></table><hr /></div><div class="sect1" id="BACKUP-MANIFEST-WAL-RANGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">76.3. Backup Manifest WAL Range Object</h2></div></div></div><p>
+ The object which describes a WAL range always has three keys:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Timeline</code></span></dt><dd><p>
+ The timeline for this range of WAL records, as an integer.
+ </p></dd><dt><span class="term"><code class="literal">Start-LSN</code></span></dt><dd><p>
+ The LSN at which replay must begin on the indicated timeline in order to
+ make use of this backup. The LSN is stored in the format normally used
+ by <span class="productname">PostgreSQL</span>; that is, it is a string
+ consisting of two strings of hexadecimal characters, each with a length
+ of between 1 and 8, separated by a slash.
+ </p></dd><dt><span class="term"><code class="literal">End-LSN</code></span></dt><dd><p>
+ The earliest LSN at which replay on the indicated timeline may end when
+ making use of this backup. This is stored in the same format as
+ <code class="literal">Start-LSN</code>.
+ </p></dd></dl></div><p>
+ Ordinarily, there will be only a single WAL range. However, if a backup is
+ taken from a standby which switches timelines during the backup due to an
+ upstream promotion, it is possible for multiple ranges to be present, each
+ with a different timeline. There will never be multiple WAL ranges present
+ for the same timeline.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-manifest-files.html" title="76.2. Backup Manifest File Object">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendixes.html" title="Part VIII. Appendixes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">76.2. Backup Manifest File Object </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part VIII. Appendixes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/backup.html b/doc/src/sgml/html/backup.html
new file mode 100644
index 0000000..33cdfb5
--- /dev/null
+++ b/doc/src/sgml/html/backup.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 26. Backup and Restore</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logfile-maintenance.html" title="25.3. Log File Maintenance" /><link rel="next" href="backup-dump.html" title="26.1. SQL Dump" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 26. Backup and Restore</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-dump.html" title="26.1. SQL Dump">Next</a></td></tr></table><hr /></div><div class="chapter" id="BACKUP"><div class="titlepage"><div><div><h2 class="title">Chapter 26. Backup and Restore</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="backup-dump.html">26.1. <acronym class="acronym">SQL</acronym> Dump</a></span></dt><dd><dl><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-RESTORE">26.1.1. Restoring the Dump</a></span></dt><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-ALL">26.1.2. Using <span class="application">pg_dumpall</span></a></span></dt><dt><span class="sect2"><a href="backup-dump.html#BACKUP-DUMP-LARGE">26.1.3. Handling Large Databases</a></span></dt></dl></dd><dt><span class="sect1"><a href="backup-file.html">26.2. File System Level Backup</a></span></dt><dt><span class="sect1"><a href="continuous-archiving.html">26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</a></span></dt><dd><dl><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-ARCHIVING-WAL">26.3.1. Setting Up WAL Archiving</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-BASE-BACKUP">26.3.2. Making a Base Backup</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP">26.3.3. Making a Base Backup Using the Low Level API</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-PITR-RECOVERY">26.3.4. Recovering Using a Continuous Archive Backup</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-TIMELINES">26.3.5. Timelines</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-TIPS">26.3.6. Tips and Examples</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#CONTINUOUS-ARCHIVING-CAVEATS">26.3.7. Caveats</a></span></dt></dl></dd></dl></div><a id="id-1.6.13.2" class="indexterm"></a><p>
+ As with everything that contains valuable data, <span class="productname">PostgreSQL</span>
+ databases should be backed up regularly. While the procedure is
+ essentially simple, it is important to have a clear understanding of
+ the underlying techniques and assumptions.
+ </p><p>
+ There are three fundamentally different approaches to backing up
+ <span class="productname">PostgreSQL</span> data:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><acronym class="acronym">SQL</acronym> dump</p></li><li class="listitem"><p>File system level backup</p></li><li class="listitem"><p>Continuous archiving</p></li></ul></div><p>
+ Each has its own strengths and weaknesses; each is discussed in turn
+ in the following sections.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-dump.html" title="26.1. SQL Dump">Next</a></td></tr><tr><td width="40%" align="left" valign="top">25.3. Log File Maintenance </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 26.1. <acronym class="acronym">SQL</acronym> Dump</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/basebackup-to-shell.html b/doc/src/sgml/html/basebackup-to-shell.html
new file mode 100644
index 0000000..764c210
--- /dev/null
+++ b/doc/src/sgml/html/basebackup-to-shell.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.5. basebackup_to_shell</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auto-explain.html" title="F.4. auto_explain" /><link rel="next" href="basic-archive.html" title="F.6. basic_archive" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.5. basebackup_to_shell</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auto-explain.html" title="F.4. auto_explain">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="basic-archive.html" title="F.6. basic_archive">Next</a></td></tr></table><hr /></div><div class="sect1" id="BASEBACKUP-TO-SHELL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.5. basebackup_to_shell</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="basebackup-to-shell.html#id-1.11.7.14.5">F.5.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="basebackup-to-shell.html#id-1.11.7.14.6">F.5.2. Author</a></span></dt></dl></div><a id="id-1.11.7.14.2" class="indexterm"></a><p>
+ <code class="filename">basebackup_to_shell</code> adds a custom basebackup target
+ called <code class="literal">shell</code>. This makes it possible to run
+ <code class="command">pg_basebackup --target=shell</code> or, depending on how this
+ module is configured,
+ <code class="command">pg_basebackup --target=shell:<em class="replaceable"><code>DETAIL_STRING</code></em></code>,
+ and cause a server command chosen by the server administrator to be executed
+ for each tar archive generated by the backup process. The command will receive
+ the contents of the archive via standard input.
+ </p><p>
+ This module is primarily intended as an example of how to create a new
+ backup targets via an extension module, but in some scenarios it may be
+ useful for its own sake.
+ In order to function, this module must be loaded via
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> or
+ <a class="xref" href="runtime-config-client.html#GUC-LOCAL-PRELOAD-LIBRARIES">local_preload_libraries</a>.
+ </p><div class="sect2" id="id-1.11.7.14.5"><div class="titlepage"><div><div><h3 class="title">F.5.1. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">basebackup_to_shell.command</code> (<code class="type">string</code>)
+ <a id="id-1.11.7.14.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The command which the server should execute for each archive generated
+ by the backup process. If <code class="literal">%f</code> occurs in the command
+ string, it will be replaced by the name of the archive (e.g.
+ <code class="literal">base.tar</code>). If <code class="literal">%d</code> occurs in the
+ command string, it will be replaced by the target detail provided by
+ the user. A target detail is required if <code class="literal">%d</code> is
+ used in the command string, and prohibited otherwise. For security
+ reasons, it may contain only alphanumeric characters. If
+ <code class="literal">%%</code> occurs in the command string, it will be replaced
+ by a single <code class="literal">%</code>. If <code class="literal">%</code> occurs in
+ the command string followed by any other character or at the end of the
+ string, an error occurs.
+ </p></dd><dt><span class="term">
+ <code class="varname">basebackup_to_shell.required_role</code> (<code class="type">string</code>)
+ <a id="id-1.11.7.14.5.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The role required in order to make use of the <code class="literal">shell</code>
+ backup target. If this is not set, any replication user may make use of
+ the <code class="literal">shell</code> backup target.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.14.6"><div class="titlepage"><div><div><h3 class="title">F.5.2. Author</h3></div></div></div><p>
+ Robert Haas <code class="email">&lt;<a class="email" href="mailto:rhaas@postgresql.org">rhaas@postgresql.org</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auto-explain.html" title="F.4. auto_explain">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="basic-archive.html" title="F.6. basic_archive">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.4. auto_explain </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.6. basic_archive</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/basic-archive.html b/doc/src/sgml/html/basic-archive.html
new file mode 100644
index 0000000..a8b4081
--- /dev/null
+++ b/doc/src/sgml/html/basic-archive.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.6. basic_archive</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell" /><link rel="next" href="bloom.html" title="F.7. bloom" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.6. basic_archive</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bloom.html" title="F.7. bloom">Next</a></td></tr></table><hr /></div><div class="sect1" id="BASIC-ARCHIVE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.6. basic_archive</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.5">F.6.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.6">F.6.2. Notes</a></span></dt><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.7">F.6.3. Author</a></span></dt></dl></div><a id="id-1.11.7.15.2" class="indexterm"></a><p>
+ <code class="filename">basic_archive</code> is an example of an archive module. This
+ module copies completed WAL segment files to the specified directory. This
+ may not be especially useful, but it can serve as a starting point for
+ developing your own archive module. For more information about archive
+ modules, see <a class="xref" href="archive-modules.html" title="Chapter 51. Archive Modules">Chapter 51</a>.
+ </p><p>
+ In order to function, this module must be loaded via
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a>, and <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a>
+ must be enabled.
+ </p><div class="sect2" id="id-1.11.7.15.5"><div class="titlepage"><div><div><h3 class="title">F.6.1. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">basic_archive.archive_directory</code> (<code class="type">string</code>)
+ <a id="id-1.11.7.15.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The directory where the server should copy WAL segment files. This
+ directory must already exist. The default is an empty string, which
+ effectively halts WAL archiving, but if <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a>
+ is enabled, the server will accumulate WAL segment files in the
+ expectation that a value will soon be provided.
+ </p></dd></dl></div><p>
+ These parameters must be set in <code class="filename">postgresql.conf</code>.
+ Typical usage might be:
+ </p><pre class="programlisting">
+# postgresql.conf
+archive_mode = 'on'
+archive_library = 'basic_archive'
+basic_archive.archive_directory = '/path/to/archive/directory'
+</pre></div><div class="sect2" id="id-1.11.7.15.6"><div class="titlepage"><div><div><h3 class="title">F.6.2. Notes</h3></div></div></div><p>
+ Server crashes may leave temporary files with the prefix
+ <code class="filename">archtemp</code> in the archive directory. It is recommended to
+ delete such files before restarting the server after a crash. It is safe to
+ remove such files while the server is running as long as they are unrelated
+ to any archiving still in progress, but users should use extra caution when
+ doing so.
+ </p></div><div class="sect2" id="id-1.11.7.15.7"><div class="titlepage"><div><div><h3 class="title">F.6.3. Author</h3></div></div></div><p>
+ Nathan Bossart
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bloom.html" title="F.7. bloom">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.5. basebackup_to_shell </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.7. bloom</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bgworker.html b/doc/src/sgml/html/bgworker.html
new file mode 100644
index 0000000..52cd297
--- /dev/null
+++ b/doc/src/sgml/html/bgworker.html
@@ -0,0 +1,231 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 48. Background Worker Processes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-start-transaction.html" title="SPI_start_transaction" /><link rel="next" href="logicaldecoding.html" title="Chapter 49. Logical Decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 48. Background Worker Processes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Next</a></td></tr></table><hr /></div><div class="chapter" id="BGWORKER"><div class="titlepage"><div><div><h2 class="title">Chapter 48. Background Worker Processes</h2></div></div></div><a id="id-1.8.13.2" class="indexterm"></a><p>
+ PostgreSQL can be extended to run user-supplied code in separate processes.
+ Such processes are started, stopped and monitored by <code class="command">postgres</code>,
+ which permits them to have a lifetime closely linked to the server's status.
+ These processes are attached to <span class="productname">PostgreSQL</span>'s
+ shared memory area and have the option to connect to databases internally; they can also run
+ multiple transactions serially, just like a regular client-connected server
+ process. Also, by linking to <span class="application">libpq</span> they can connect to the
+ server and behave like a regular client application.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ There are considerable robustness and security risks in using background
+ worker processes because, being written in the <code class="literal">C</code> language,
+ they have unrestricted access to data. Administrators wishing to enable
+ modules that include background worker processes should exercise extreme
+ caution. Only carefully audited modules should be permitted to run
+ background worker processes.
+ </p></div><p>
+ Background workers can be initialized at the time that
+ <span class="productname">PostgreSQL</span> is started by including the module name in
+ <code class="varname">shared_preload_libraries</code>. A module wishing to run a background
+ worker can register it by calling
+ <code class="function">RegisterBackgroundWorker(<code class="type">BackgroundWorker</code>
+ *<em class="parameter"><code>worker</code></em>)</code>
+ from its <code class="function">_PG_init()</code> function.
+ Background workers can also be started
+ after the system is up and running by calling
+ <code class="function">RegisterDynamicBackgroundWorker(<code class="type">BackgroundWorker</code>
+ *<em class="parameter"><code>worker</code></em>, <code class="type">BackgroundWorkerHandle</code>
+ **<em class="parameter"><code>handle</code></em>)</code>. Unlike
+ <code class="function">RegisterBackgroundWorker</code>, which can only be called from
+ within the postmaster process,
+ <code class="function">RegisterDynamicBackgroundWorker</code> must be called
+ from a regular backend or another background worker.
+ </p><p>
+ The structure <code class="structname">BackgroundWorker</code> is defined thus:
+</p><pre class="programlisting">
+typedef void (*bgworker_main_type)(Datum main_arg);
+typedef struct BackgroundWorker
+{
+ char bgw_name[BGW_MAXLEN];
+ char bgw_type[BGW_MAXLEN];
+ int bgw_flags;
+ BgWorkerStartTime bgw_start_time;
+ int bgw_restart_time; /* in seconds, or BGW_NEVER_RESTART */
+ char bgw_library_name[BGW_MAXLEN];
+ char bgw_function_name[BGW_MAXLEN];
+ Datum bgw_main_arg;
+ char bgw_extra[BGW_EXTRALEN];
+ int bgw_notify_pid;
+} BackgroundWorker;
+</pre><p>
+ </p><p>
+ <code class="structfield">bgw_name</code> and <code class="structfield">bgw_type</code> are
+ strings to be used in log messages, process listings and similar contexts.
+ <code class="structfield">bgw_type</code> should be the same for all background
+ workers of the same type, so that it is possible to group such workers in a
+ process listing, for example. <code class="structfield">bgw_name</code> on the
+ other hand can contain additional information about the specific process.
+ (Typically, the string for <code class="structfield">bgw_name</code> will contain
+ the type somehow, but that is not strictly required.)
+ </p><p>
+ <code class="structfield">bgw_flags</code> is a bitwise-or'd bit mask indicating the
+ capabilities that the module wants. Possible values are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">BGWORKER_SHMEM_ACCESS</code></span></dt><dd><p>
+ <a id="id-1.8.13.8.2.1.2.1.1" class="indexterm"></a>
+ Requests shared memory access. This flag is required.
+ </p></dd><dt><span class="term"><code class="literal">BGWORKER_BACKEND_DATABASE_CONNECTION</code></span></dt><dd><p>
+ <a id="id-1.8.13.8.2.2.2.1.1" class="indexterm"></a>
+ Requests the ability to establish a database connection through which it
+ can later run transactions and queries. A background worker using
+ <code class="literal">BGWORKER_BACKEND_DATABASE_CONNECTION</code> to connect to a
+ database must also attach shared memory using
+ <code class="literal">BGWORKER_SHMEM_ACCESS</code>, or worker start-up will fail.
+ </p></dd></dl></div><p>
+
+ </p><p>
+ <code class="structfield">bgw_start_time</code> is the server state during which
+ <code class="command">postgres</code> should start the process; it can be one of
+ <code class="literal">BgWorkerStart_PostmasterStart</code> (start as soon as
+ <code class="command">postgres</code> itself has finished its own initialization; processes
+ requesting this are not eligible for database connections),
+ <code class="literal">BgWorkerStart_ConsistentState</code> (start as soon as a consistent state
+ has been reached in a hot standby, allowing processes to connect to
+ databases and run read-only queries), and
+ <code class="literal">BgWorkerStart_RecoveryFinished</code> (start as soon as the system has
+ entered normal read-write state). Note the last two values are equivalent
+ in a server that's not a hot standby. Note that this setting only indicates
+ when the processes are to be started; they do not stop when a different state
+ is reached.
+ </p><p>
+ <code class="structfield">bgw_restart_time</code> is the interval, in seconds, that
+ <code class="command">postgres</code> should wait before restarting the process in
+ the event that it crashes. It can be any positive value,
+ or <code class="literal">BGW_NEVER_RESTART</code>, indicating not to restart the
+ process in case of a crash.
+ </p><p>
+ <code class="structfield">bgw_library_name</code> is the name of a library in
+ which the initial entry point for the background worker should be sought.
+ The named library will be dynamically loaded by the worker process and
+ <code class="structfield">bgw_function_name</code> will be used to identify the
+ function to be called. If loading a function from the core code, this must
+ be set to "postgres".
+ </p><p>
+ <code class="structfield">bgw_function_name</code> is the name of a function in
+ a dynamically loaded library which should be used as the initial entry point
+ for a new background worker.
+ </p><p>
+ <code class="structfield">bgw_main_arg</code> is the <code class="type">Datum</code> argument
+ to the background worker main function. This main function should take a
+ single argument of type <code class="type">Datum</code> and return <code class="type">void</code>.
+ <code class="structfield">bgw_main_arg</code> will be passed as the argument.
+ In addition, the global variable <code class="literal">MyBgworkerEntry</code>
+ points to a copy of the <code class="structname">BackgroundWorker</code> structure
+ passed at registration time; the worker may find it helpful to examine
+ this structure.
+ </p><p>
+ On Windows (and anywhere else where <code class="literal">EXEC_BACKEND</code> is
+ defined) or in dynamic background workers it is not safe to pass a
+ <code class="type">Datum</code> by reference, only by value. If an argument is required, it
+ is safest to pass an int32 or other small value and use that as an index
+ into an array allocated in shared memory. If a value like a <code class="type">cstring</code>
+ or <code class="type">text</code> is passed then the pointer won't be valid from the
+ new background worker process.
+ </p><p>
+ <code class="structfield">bgw_extra</code> can contain extra data to be passed
+ to the background worker. Unlike <code class="structfield">bgw_main_arg</code>, this data
+ is not passed as an argument to the worker's main function, but it can be
+ accessed via <code class="literal">MyBgworkerEntry</code>, as discussed above.
+ </p><p>
+ <code class="structfield">bgw_notify_pid</code> is the PID of a PostgreSQL
+ backend process to which the postmaster should send <code class="literal">SIGUSR1</code>
+ when the process is started or exits. It should be 0 for workers registered
+ at postmaster startup time, or when the backend registering the worker does
+ not wish to wait for the worker to start up. Otherwise, it should be
+ initialized to <code class="literal">MyProcPid</code>.
+ </p><p>Once running, the process can connect to a database by calling
+ <code class="function">BackgroundWorkerInitializeConnection(<em class="parameter"><code>char *dbname</code></em>, <em class="parameter"><code>char *username</code></em>, <em class="parameter"><code>uint32 flags</code></em>)</code> or
+ <code class="function">BackgroundWorkerInitializeConnectionByOid(<em class="parameter"><code>Oid dboid</code></em>, <em class="parameter"><code>Oid useroid</code></em>, <em class="parameter"><code>uint32 flags</code></em>)</code>.
+ This allows the process to run transactions and queries using the
+ <code class="literal">SPI</code> interface. If <code class="varname">dbname</code> is NULL or
+ <code class="varname">dboid</code> is <code class="literal">InvalidOid</code>, the session is not connected
+ to any particular database, but shared catalogs can be accessed.
+ If <code class="varname">username</code> is NULL or <code class="varname">useroid</code> is
+ <code class="literal">InvalidOid</code>, the process will run as the superuser created
+ during <code class="command">initdb</code>. If <code class="literal">BGWORKER_BYPASS_ALLOWCONN</code>
+ is specified as <code class="varname">flags</code> it is possible to bypass the restriction
+ to connect to databases not allowing user connections.
+ A background worker can only call one of these two functions, and only
+ once. It is not possible to switch databases.
+ </p><p>
+ Signals are initially blocked when control reaches the
+ background worker's main function, and must be unblocked by it; this is to
+ allow the process to customize its signal handlers, if necessary.
+ Signals can be unblocked in the new process by calling
+ <code class="function">BackgroundWorkerUnblockSignals</code> and blocked by calling
+ <code class="function">BackgroundWorkerBlockSignals</code>.
+ </p><p>
+ If <code class="structfield">bgw_restart_time</code> for a background worker is
+ configured as <code class="literal">BGW_NEVER_RESTART</code>, or if it exits with an exit
+ code of 0 or is terminated by <code class="function">TerminateBackgroundWorker</code>,
+ it will be automatically unregistered by the postmaster on exit.
+ Otherwise, it will be restarted after the time period configured via
+ <code class="structfield">bgw_restart_time</code>, or immediately if the postmaster
+ reinitializes the cluster due to a backend failure. Backends which need
+ to suspend execution only temporarily should use an interruptible sleep
+ rather than exiting; this can be achieved by calling
+ <code class="function">WaitLatch()</code>. Make sure the
+ <code class="literal">WL_POSTMASTER_DEATH</code> flag is set when calling that function, and
+ verify the return code for a prompt exit in the emergency case that
+ <code class="command">postgres</code> itself has terminated.
+ </p><p>
+ When a background worker is registered using the
+ <code class="function">RegisterDynamicBackgroundWorker</code> function, it is
+ possible for the backend performing the registration to obtain information
+ regarding the status of the worker. Backends wishing to do this should
+ pass the address of a <code class="type">BackgroundWorkerHandle *</code> as the second
+ argument to <code class="function">RegisterDynamicBackgroundWorker</code>. If the
+ worker is successfully registered, this pointer will be initialized with an
+ opaque handle that can subsequently be passed to
+ <code class="function">GetBackgroundWorkerPid(<em class="parameter"><code>BackgroundWorkerHandle *</code></em>, <em class="parameter"><code>pid_t *</code></em>)</code> or
+ <code class="function">TerminateBackgroundWorker(<em class="parameter"><code>BackgroundWorkerHandle *</code></em>)</code>.
+ <code class="function">GetBackgroundWorkerPid</code> can be used to poll the status of the
+ worker: a return value of <code class="literal">BGWH_NOT_YET_STARTED</code> indicates that
+ the worker has not yet been started by the postmaster;
+ <code class="literal">BGWH_STOPPED</code> indicates that it has been started but is
+ no longer running; and <code class="literal">BGWH_STARTED</code> indicates that it is
+ currently running. In this last case, the PID will also be returned via the
+ second argument.
+ <code class="function">TerminateBackgroundWorker</code> causes the postmaster to send
+ <code class="literal">SIGTERM</code> to the worker if it is running, and to unregister it
+ as soon as it is not.
+ </p><p>
+ In some cases, a process which registers a background worker may wish to
+ wait for the worker to start up. This can be accomplished by initializing
+ <code class="structfield">bgw_notify_pid</code> to <code class="literal">MyProcPid</code> and
+ then passing the <code class="type">BackgroundWorkerHandle *</code> obtained at
+ registration time to
+ <code class="function">WaitForBackgroundWorkerStartup(<em class="parameter"><code>BackgroundWorkerHandle
+ *handle</code></em>, <em class="parameter"><code>pid_t *</code></em>)</code> function.
+ This function will block until the postmaster has attempted to start the
+ background worker, or until the postmaster dies. If the background worker
+ is running, the return value will be <code class="literal">BGWH_STARTED</code>, and
+ the PID will be written to the provided address. Otherwise, the return
+ value will be <code class="literal">BGWH_STOPPED</code> or
+ <code class="literal">BGWH_POSTMASTER_DIED</code>.
+ </p><p>
+ A process can also wait for a background worker to shut down, by using the
+ <code class="function">WaitForBackgroundWorkerShutdown(<em class="parameter"><code>BackgroundWorkerHandle
+ *handle</code></em>)</code> function and passing the
+ <code class="type">BackgroundWorkerHandle *</code> obtained at registration. This
+ function will block until the background worker exits, or postmaster dies.
+ When the background worker exits, the return value is
+ <code class="literal">BGWH_STOPPED</code>, if postmaster dies it will return
+ <code class="literal">BGWH_POSTMASTER_DIED</code>.
+ </p><p>
+ Background workers can send asynchronous notification messages, either by
+ using the <code class="command">NOTIFY</code> command via <acronym class="acronym">SPI</acronym>,
+ or directly via <code class="function">Async_Notify()</code>. Such notifications
+ will be sent at transaction commit.
+ Background workers should not register to receive asynchronous
+ notifications with the <code class="command">LISTEN</code> command, as there is no
+ infrastructure for a worker to consume such notifications.
+ </p><p>
+ The <code class="filename">src/test/modules/worker_spi</code> module
+ contains a working example,
+ which demonstrates some useful techniques.
+ </p><p>
+ The maximum number of registered background workers is limited by
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_start_transaction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 49. Logical Decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/biblio.html b/doc/src/sgml/html/biblio.html
new file mode 100644
index 0000000..f3815db
--- /dev/null
+++ b/doc/src/sgml/html/biblio.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Bibliography</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal" /><link rel="next" href="bookindex.html" title="Index" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Bibliography</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bookindex.html" title="Index">Next</a></td></tr></table><hr /></div><div class="bibliography" id="BIBLIO"><div class="titlepage"><div><div><h1 class="title">Bibliography</h1></div></div></div><p>
+ Selected references and readings for <acronym class="acronym">SQL</acronym>
+ and <span class="productname">PostgreSQL</span>.
+ </p><p>
+ Some white papers and technical reports from the original
+ <span class="productname">POSTGRES</span> development team
+ are available at the University of California, Berkeley, Computer Science
+ Department <a class="ulink" href="https://dsf.berkeley.edu/papers/" target="_top">web site</a>.
+ </p><div class="bibliodiv" id="id-1.12.4"><h3 class="title"><acronym class="acronym">SQL</acronym> Reference Books</h3><div class="biblioentry" id="BOWMAN01"><p>[bowman01] <span class="title"><em>The Practical <acronym class="acronym">SQL</acronym> Handbook</em>. </span><span class="subtitle">Using SQL Variants. </span><span class="edition">Fourth Edition. </span><span class="authorgroup"><span class="firstname">Judith</span> <span class="surname">Bowman</span>, <span class="firstname">Sandra</span> <span class="surname">Emerson</span>, and <span class="firstname">Marcy</span> <span class="surname">Darnovsky</span>. </span><span class="isbn">ISBN 0-201-70309-2. </span><span class="publisher"><span class="publishername">Addison-Wesley Professional. </span></span><span class="pubdate">2001. </span></p></div><div class="biblioentry" id="DATE97"><p>[date97] <span class="title"><em>A Guide to the <acronym class="acronym">SQL</acronym> Standard</em>. </span><span class="subtitle">A user's guide to the standard database language <acronym class="acronym">SQL</acronym>. </span><span class="edition">Fourth Edition. </span><span class="authorgroup"><span class="firstname">C. J.</span> <span class="surname">Date</span> and <span class="firstname">Hugh</span> <span class="surname">Darwen</span>. </span><span class="isbn">ISBN 0-201-96426-0. </span><span class="publisher"><span class="publishername">Addison-Wesley. </span></span><span class="pubdate">1997. </span></p></div><div class="biblioentry" id="DATE04"><p>[date04] <span class="title"><em>An Introduction to Database Systems</em>. </span><span class="edition">Eighth Edition. </span><span class="authorgroup"><span class="firstname">C. J.</span> <span class="surname">Date</span>. </span><span class="isbn">ISBN 0-321-19784-4. </span><span class="publisher"><span class="publishername">Addison-Wesley. </span></span><span class="pubdate">2003. </span></p></div><div class="biblioentry" id="ELMA04"><p>[elma04] <span class="title"><em>Fundamentals of Database Systems</em>. </span><span class="edition">Fourth Edition. </span><span class="authorgroup"><span class="firstname">Ramez</span> <span class="surname">Elmasri</span> and <span class="firstname">Shamkant</span> <span class="surname">Navathe</span>. </span><span class="isbn">ISBN 0-321-12226-7. </span><span class="publisher"><span class="publishername">Addison-Wesley. </span></span><span class="pubdate">2003. </span></p></div><div class="biblioentry" id="MELT93"><p>[melt93] <span class="title"><em>Understanding the New <acronym class="acronym">SQL</acronym></em>. </span><span class="subtitle">A complete guide. </span><span class="authorgroup"><span class="firstname">Jim</span> <span class="surname">Melton</span> and <span class="firstname">Alan R.</span> <span class="surname">Simon</span>. </span><span class="isbn">ISBN 1-55860-245-3. </span><span class="publisher"><span class="publishername">Morgan Kaufmann. </span></span><span class="pubdate">1993. </span></p></div><div class="biblioentry" id="ULL88"><p>[ull88] <span class="title"><em>Principles of Database and Knowledge-Base Systems</em>. </span><span class="subtitle">Classical Database Systems. </span><span class="authorgroup"><span class="firstname">Jeffrey D.</span> <span class="surname">Ullman</span>. </span><span class="volumenum">Volume 1. </span><span class="publisher"><span class="publishername">Computer Science Press. </span></span><span class="pubdate">1988. </span></p></div><div class="biblioentry" id="SQLTR-19075-6"><p>[sqltr-19075-6] <span class="title"><em>SQL Technical Report</em>. </span><span class="subtitle">Part 6: SQL support for JavaScript Object
+ Notation (JSON). </span><span class="edition">First Edition. </span><span class="pubdate">2017. </span></p></div></div><div class="bibliodiv" id="id-1.12.5"><h3 class="title">PostgreSQL-specific Documentation</h3><div class="biblioentry" id="SIM98"><p>[sim98] <span class="title"><em>Enhancement of the ANSI SQL Implementation of PostgreSQL</em>. </span><span class="authorgroup"><span class="firstname">Stefan</span> <span class="surname">Simkovics</span>. </span><span class="publisher"><span class="publishername">Department of Information Systems, Vienna University of Technology. </span><span class="address">Vienna, Austria. </span></span><span class="pubdate">November 29, 1998. </span></p></div><div class="biblioentry" id="YU95"><p>[yu95] <span class="title"><em>The <span class="productname">Postgres95. </span> User Manual</em>. </span><span class="authorgroup"><span class="firstname">A.</span> <span class="surname">Yu</span> and <span class="firstname">J.</span> <span class="surname">Chen</span>. </span><span class="publisher"><span class="publishername">University of California. </span><span class="address">Berkeley, California. </span></span><span class="pubdate">Sept. 5, 1995. </span></p></div><div class="biblioentry" id="FONG"><p>[fong] <span class="title"><em><a class="ulink" href="https://dsf.berkeley.edu/papers/UCB-MS-zfong.pdf" target="_top">The
+ design and implementation of the <span class="productname">POSTGRES</span> query
+ optimizer</a></em>. </span><span class="author"><span class="firstname">Zelaine</span> <span class="surname">Fong</span>. </span><span class="publisher"><span class="publishername">University of California, Berkeley, Computer Science Department. </span></span></p></div></div><div class="bibliodiv" id="id-1.12.6"><h3 class="title">Proceedings and Articles</h3><div class="biblioentry" id="PORTS12"><p>[ports12] <span class="biblioset">“<a class="ulink" href="https://arxiv.org/pdf/1208.4179" target="_top">Serializable Snapshot Isolation in PostgreSQL</a>”. <span class="authorgroup"><span class="firstname">D.</span> <span class="surname">Ports</span> and <span class="firstname">K.</span> <span class="surname">Grittner</span>. </span></span><span class="confgroup">VLDB Conference, August 2012. </span></p></div><div class="biblioentry" id="BERENSON95"><p>[berenson95] <span class="biblioset">“<a class="ulink" href="https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf" target="_top">A Critique of ANSI SQL Isolation Levels</a>”. <span class="authorgroup"><span class="firstname">H.</span> <span class="surname">Berenson</span>, <span class="firstname">P.</span> <span class="surname">Bernstein</span>, <span class="firstname">J.</span> <span class="surname">Gray</span>, <span class="firstname">J.</span> <span class="surname">Melton</span>, <span class="firstname">E.</span> <span class="surname">O'Neil</span>, and <span class="firstname">P.</span> <span class="surname">O'Neil</span>. </span></span><span class="confgroup">ACM-SIGMOD Conference on Management of Data, June 1995. </span></p></div><div class="biblioentry" id="OLSON93"><p>[olson93] <span class="title"><em>Partial indexing in POSTGRES: research project</em>. </span><span class="authorgroup"><span class="firstname">Nels</span> <span class="surname">Olson</span>. </span><span class="pubsnumber">UCB Engin T7.49.1993 O676. </span><span class="publisher"><span class="publishername">University of California. </span><span class="address">Berkeley, California. </span></span><span class="pubdate">1993. </span></p></div><div class="biblioentry" id="ONG90"><p>[ong90] <span class="biblioset">“A Unified Framework for Version Modeling Using Production Rules in a Database System”. <span class="authorgroup"><span class="firstname">L.</span> <span class="surname">Ong</span> and <span class="firstname">J.</span> <span class="surname">Goh</span>. </span></span><span class="biblioset"><em>ERL Technical Memorandum M90/33</em>. <span class="publisher"><span class="publishername">University of California. </span><span class="address">Berkeley, California. </span></span><span class="pubdate">April, 1990. </span></span></p></div><div class="biblioentry" id="ROWE87"><p>[rowe87] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M87-13.pdf" target="_top">The <span class="productname">POSTGRES</span>
+ data model</a>”. <span class="authorgroup"><span class="firstname">L.</span> <span class="surname">Rowe</span> and <span class="firstname">M.</span> <span class="surname">Stonebraker</span>. </span></span><span class="confgroup">VLDB Conference, Sept. 1987. </span></p></div><div class="biblioentry" id="SESHADRI95"><p>[seshadri95] <span class="biblioset">“<a class="ulink" href="https://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.40.5740" target="_top">Generalized
+ Partial Indexes</a>”. <span class="authorgroup"><span class="firstname">P.</span> <span class="surname">Seshadri</span> and <span class="firstname">A.</span> <span class="surname">Swami</span>. </span></span><span class="confgroup">Eleventh International Conference on Data Engineering, 6–10 March 1995. </span><span class="pubsnumber">Cat. No.95CH35724. </span><span class="publisher"><span class="publishername">IEEE Computer Society Press. </span><span class="address">Los Alamitos, California. </span></span><span class="pubdate">1995. </span><span class="pagenums">420–7. </span></p></div><div class="biblioentry" id="STON86"><p>[ston86] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M85-95.pdf" target="_top">The
+ design of <span class="productname">POSTGRES</span></a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span> and <span class="firstname">L.</span> <span class="surname">Rowe</span>. </span></span><span class="confgroup">ACM-SIGMOD Conference on Management of Data, May 1986. </span></p></div><div class="biblioentry" id="STON87A"><p>[ston87a] <span class="biblioset">“The design of the <span class="productname">POSTGRES</span> rules system”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>, <span class="firstname">E.</span> <span class="surname">Hanson</span>, and <span class="firstname">C. H.</span> <span class="surname">Hong</span>. </span></span><span class="confgroup">IEEE Conference on Data Engineering, Feb. 1987. </span></p></div><div class="biblioentry" id="STON87B"><p>[ston87b] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M87-06.pdf" target="_top">The
+ design of the <span class="productname">POSTGRES</span> storage
+ system</a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>. </span></span><span class="confgroup">VLDB Conference, Sept. 1987. </span></p></div><div class="biblioentry" id="STON89"><p>[ston89] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M89-82.pdf" target="_top">A
+ commentary on the <span class="productname">POSTGRES</span> rules
+ system</a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>, <span class="firstname">M.</span> <span class="surname">Hearst</span>, and <span class="firstname">S.</span> <span class="surname">Potamianos</span>. </span></span><span class="biblioset"><em>SIGMOD Record 18(3)</em>. <span class="date">Sept. 1989. </span></span></p></div><div class="biblioentry" id="STON89B"><p>[ston89b] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M89-17.pdf" target="_top">The
+ case for partial indexes</a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>. </span></span><span class="biblioset"><em>SIGMOD Record 18(4)</em>. <span class="date">Dec. 1989. </span><span class="pagenums">4–11. </span></span></p></div><div class="biblioentry" id="STON90A"><p>[ston90a] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M90-34.pdf" target="_top">The
+ implementation of <span class="productname">POSTGRES</span></a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>, <span class="firstname">L. A.</span> <span class="surname">Rowe</span>, and <span class="firstname">M.</span> <span class="surname">Hirohama</span>. </span></span><span class="biblioset"><em>Transactions on Knowledge and Data Engineering 2(1)</em>. <span class="publisher"><span class="publishername">IEEE. </span></span><span class="date">March 1990. </span></span></p></div><div class="biblioentry" id="STON90B"><p>[ston90b] <span class="biblioset">“<a class="ulink" href="https://dsf.berkeley.edu/papers/ERL-M90-36.pdf" target="_top">On
+ Rules, Procedures, Caching and Views in Database Systems</a>”. <span class="authorgroup"><span class="firstname">M.</span> <span class="surname">Stonebraker</span>, <span class="firstname">A.</span> <span class="surname">Jhingran</span>, <span class="firstname">J.</span> <span class="surname">Goh</span>, and <span class="firstname">S.</span> <span class="surname">Potamianos</span>. </span></span><span class="confgroup">ACM-SIGMOD Conference on Management of Data, June 1990. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgreceivexlog.html" title="O.5. pg_receivexlog renamed to pg_receivewal">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bookindex.html" title="Index">Next</a></td></tr><tr><td width="40%" align="left" valign="top">O.5. <code class="command">pg_receivexlog</code> renamed to <code class="command">pg_receivewal</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Index</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bki-commands.html b/doc/src/sgml/html/bki-commands.html
new file mode 100644
index 0000000..2809143
--- /dev/null
+++ b/doc/src/sgml/html/bki-commands.html
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.4. BKI Commands</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki-format.html" title="74.3. BKI File Format" /><link rel="next" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.4. <acronym class="acronym">BKI</acronym> Commands</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki-format.html" title="74.3. BKI File Format">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File">Next</a></td></tr></table><hr /></div><div class="sect1" id="BKI-COMMANDS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.4. <acronym class="acronym">BKI</acronym> Commands</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal">create</code>
+ <em class="replaceable"><code>tablename</code></em>
+ <em class="replaceable"><code>tableoid</code></em>
+ [<span class="optional"><code class="literal">bootstrap</code></span>]
+ [<span class="optional"><code class="literal">shared_relation</code></span>]
+ [<span class="optional"><code class="literal">rowtype_oid</code> <em class="replaceable"><code>oid</code></em></span>]
+ (<em class="replaceable"><code>name1</code></em> =
+ <em class="replaceable"><code>type1</code></em>
+ [<span class="optional"><code class="literal">FORCE NOT NULL</code> | <code class="literal">FORCE NULL</code> </span>] [<span class="optional">,
+ <em class="replaceable"><code>name2</code></em> =
+ <em class="replaceable"><code>type2</code></em>
+ [<span class="optional"><code class="literal">FORCE NOT NULL</code> | <code class="literal">FORCE NULL</code> </span>],
+ ...</span>])
+ </span></dt><dd><p>
+ Create a table named <em class="replaceable"><code>tablename</code></em>, and having the OID
+ <em class="replaceable"><code>tableoid</code></em>,
+ with the columns given in parentheses.
+ </p><p>
+ The following column types are supported directly by
+ <code class="filename">bootstrap.c</code>: <code class="type">bool</code>,
+ <code class="type">bytea</code>, <code class="type">char</code> (1 byte),
+ <code class="type">name</code>, <code class="type">int2</code>,
+ <code class="type">int4</code>, <code class="type">regproc</code>, <code class="type">regclass</code>,
+ <code class="type">regtype</code>, <code class="type">text</code>,
+ <code class="type">oid</code>, <code class="type">tid</code>, <code class="type">xid</code>,
+ <code class="type">cid</code>, <code class="type">int2vector</code>, <code class="type">oidvector</code>,
+ <code class="type">_int4</code> (array), <code class="type">_text</code> (array),
+ <code class="type">_oid</code> (array), <code class="type">_char</code> (array),
+ <code class="type">_aclitem</code> (array). Although it is possible to create
+ tables containing columns of other types, this cannot be done until
+ after <code class="structname">pg_type</code> has been created and filled with
+ appropriate entries. (That effectively means that only these
+ column types can be used in bootstrap catalogs, but non-bootstrap
+ catalogs can contain any built-in type.)
+ </p><p>
+ When <code class="literal">bootstrap</code> is specified,
+ the table will only be created on disk; nothing is entered into
+ <code class="structname">pg_class</code>,
+ <code class="structname">pg_attribute</code>, etc., for it. Thus the
+ table will not be accessible by ordinary SQL operations until
+ such entries are made the hard way (with <code class="literal">insert</code>
+ commands). This option is used for creating
+ <code class="structname">pg_class</code> etc. themselves.
+ </p><p>
+ The table is created as shared if <code class="literal">shared_relation</code> is
+ specified.
+ The table's row type OID (<code class="structname">pg_type</code> OID) can optionally
+ be specified via the <code class="literal">rowtype_oid</code> clause; if not specified,
+ an OID is automatically generated for it. (The <code class="literal">rowtype_oid</code>
+ clause is useless if <code class="literal">bootstrap</code> is specified, but it can be
+ provided anyway for documentation.)
+ </p></dd><dt><span class="term">
+ <code class="literal">open</code> <em class="replaceable"><code>tablename</code></em>
+ </span></dt><dd><p>
+ Open the table named
+ <em class="replaceable"><code>tablename</code></em>
+ for insertion of data. Any currently open table is closed.
+ </p></dd><dt><span class="term">
+ <code class="literal">close</code> <em class="replaceable"><code>tablename</code></em>
+ </span></dt><dd><p>
+ Close the open table. The name of the table must be given as a
+ cross-check.
+ </p></dd><dt><span class="term">
+ <code class="literal">insert</code> <code class="literal">(</code> [<span class="optional"><em class="replaceable"><code>oid_value</code></em></span>] <em class="replaceable"><code>value1</code></em> <em class="replaceable"><code>value2</code></em> ... <code class="literal">)</code>
+ </span></dt><dd><p>
+ Insert a new row into the open table using <em class="replaceable"><code>value1</code></em>, <em class="replaceable"><code>value2</code></em>, etc., for its column
+ values.
+ </p><p>
+ NULL values can be specified using the special key word
+ <code class="literal">_null_</code>. Values that do not look like
+ identifiers or digit strings must be single-quoted.
+ (To include a single quote in a value, write it twice.
+ Escape-string-style backslash escapes are allowed in the string, too.)
+ </p></dd><dt><span class="term">
+ <code class="literal">declare</code> [<span class="optional"><code class="literal">unique</code></span>]
+ <code class="literal">index</code> <em class="replaceable"><code>indexname</code></em>
+ <em class="replaceable"><code>indexoid</code></em>
+ <code class="literal">on</code> <em class="replaceable"><code>tablename</code></em>
+ <code class="literal">using</code> <em class="replaceable"><code>amname</code></em>
+ <code class="literal">(</code> <em class="replaceable"><code>opclass1</code></em>
+ <em class="replaceable"><code>name1</code></em>
+ [<span class="optional">, ...</span>] <code class="literal">)</code>
+ </span></dt><dd><p>
+ Create an index named <em class="replaceable"><code>indexname</code></em>, having OID
+ <em class="replaceable"><code>indexoid</code></em>,
+ on the table named
+ <em class="replaceable"><code>tablename</code></em>, using the
+ <em class="replaceable"><code>amname</code></em> access
+ method. The fields to index are called <em class="replaceable"><code>name1</code></em>, <em class="replaceable"><code>name2</code></em> etc., and the operator
+ classes to use are <em class="replaceable"><code>opclass1</code></em>, <em class="replaceable"><code>opclass2</code></em> etc., respectively.
+ The index file is created and appropriate catalog entries are
+ made for it, but the index contents are not initialized by this command.
+ </p></dd><dt><span class="term">
+ <code class="literal">declare toast</code>
+ <em class="replaceable"><code>toasttableoid</code></em>
+ <em class="replaceable"><code>toastindexoid</code></em>
+ <code class="literal">on</code> <em class="replaceable"><code>tablename</code></em>
+ </span></dt><dd><p>
+ Create a TOAST table for the table named
+ <em class="replaceable"><code>tablename</code></em>.
+ The TOAST table is assigned OID
+ <em class="replaceable"><code>toasttableoid</code></em>
+ and its index is assigned OID
+ <em class="replaceable"><code>toastindexoid</code></em>.
+ As with <code class="literal">declare index</code>, filling of the index
+ is postponed.
+ </p></dd><dt><span class="term"><code class="literal">build indices</code></span></dt><dd><p>
+ Fill in the indices that have previously been declared.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki-format.html" title="74.3. BKI File Format">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.3. <acronym class="acronym">BKI</acronym> File Format </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bki-example.html b/doc/src/sgml/html/bki-example.html
new file mode 100644
index 0000000..df92e68
--- /dev/null
+++ b/doc/src/sgml/html/bki-example.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.6. BKI Example</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File" /><link rel="next" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.6. BKI Example</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Next</a></td></tr></table><hr /></div><div class="sect1" id="BKI-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.6. BKI Example</h2></div></div></div><p>
+ The following sequence of commands will create the table
+ <code class="literal">test_table</code> with OID 420, having three columns
+ <code class="literal">oid</code>, <code class="literal">cola</code> and <code class="literal">colb</code>
+ of type <code class="type">oid</code>, <code class="type">int4</code> and <code class="type">text</code>,
+ respectively, and insert two rows into the table:
+</p><pre class="programlisting">
+create test_table 420 (oid = oid, cola = int4, colb = text)
+open test_table
+insert ( 421 1 'value 1' )
+insert ( 422 2 _null_ )
+close test_table
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki-structure.html" title="74.5. Structure of the Bootstrap BKI File">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 75. How the Planner Uses Statistics</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bki-format.html b/doc/src/sgml/html/bki-format.html
new file mode 100644
index 0000000..aaeddb7
--- /dev/null
+++ b/doc/src/sgml/html/bki-format.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.3. BKI File Format</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data" /><link rel="next" href="bki-commands.html" title="74.4. BKI Commands" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.3. <acronym class="acronym">BKI</acronym> File Format</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bki-commands.html" title="74.4. BKI Commands">Next</a></td></tr></table><hr /></div><div class="sect1" id="BKI-FORMAT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.3. <acronym class="acronym">BKI</acronym> File Format</h2></div></div></div><p>
+ This section describes how the <span class="productname">PostgreSQL</span>
+ backend interprets <acronym class="acronym">BKI</acronym> files. This description
+ will be easier to understand if the <code class="filename">postgres.bki</code>
+ file is at hand as an example.
+ </p><p>
+ <acronym class="acronym">BKI</acronym> input consists of a sequence of commands. Commands are made up
+ of a number of tokens, depending on the syntax of the command.
+ Tokens are usually separated by whitespace, but need not be if
+ there is no ambiguity. There is no special command separator; the
+ next token that syntactically cannot belong to the preceding
+ command starts a new one. (Usually you would put a new command on
+ a new line, for clarity.) Tokens can be certain key words, special
+ characters (parentheses, commas, etc.), identifiers, numbers, or
+ single-quoted strings. Everything is case sensitive.
+ </p><p>
+ Lines starting with <code class="literal">#</code> are ignored.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bki-commands.html" title="74.4. BKI Commands">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.2. System Catalog Initial Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.4. <acronym class="acronym">BKI</acronym> Commands</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bki-structure.html b/doc/src/sgml/html/bki-structure.html
new file mode 100644
index 0000000..2ad533d
--- /dev/null
+++ b/doc/src/sgml/html/bki-structure.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.5. Structure of the Bootstrap BKI File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki-commands.html" title="74.4. BKI Commands" /><link rel="next" href="bki-example.html" title="74.6. BKI Example" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki-commands.html" title="74.4. BKI Commands">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bki-example.html" title="74.6. BKI Example">Next</a></td></tr></table><hr /></div><div class="sect1" id="BKI-STRUCTURE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File</h2></div></div></div><p>
+ The <code class="literal">open</code> command cannot be used until the tables it uses
+ exist and have entries for the table that is to be opened.
+ (These minimum tables are <code class="structname">pg_class</code>,
+ <code class="structname">pg_attribute</code>, <code class="structname">pg_proc</code>, and
+ <code class="structname">pg_type</code>.) To allow those tables themselves to be filled,
+ <code class="literal">create</code> with the <code class="literal">bootstrap</code> option implicitly opens
+ the created table for data insertion.
+ </p><p>
+ Also, the <code class="literal">declare index</code> and <code class="literal">declare toast</code>
+ commands cannot be used until the system catalogs they need have been
+ created and filled in.
+ </p><p>
+ Thus, the structure of the <code class="filename">postgres.bki</code> file has to
+ be:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ <code class="literal">create bootstrap</code> one of the critical tables
+ </p></li><li class="listitem"><p>
+ <code class="literal">insert</code> data describing at least the critical tables
+ </p></li><li class="listitem"><p>
+ <code class="literal">close</code>
+ </p></li><li class="listitem"><p>
+ Repeat for the other critical tables.
+ </p></li><li class="listitem"><p>
+ <code class="literal">create</code> (without <code class="literal">bootstrap</code>) a noncritical table
+ </p></li><li class="listitem"><p>
+ <code class="literal">open</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">insert</code> desired data
+ </p></li><li class="listitem"><p>
+ <code class="literal">close</code>
+ </p></li><li class="listitem"><p>
+ Repeat for the other noncritical tables.
+ </p></li><li class="listitem"><p>
+ Define indexes and toast tables.
+ </p></li><li class="listitem"><p>
+ <code class="literal">build indices</code>
+ </p></li></ol></div><p>
+ </p><p>
+ There are doubtless other, undocumented ordering dependencies.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki-commands.html" title="74.4. BKI Commands">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bki-example.html" title="74.6. BKI Example">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.4. <acronym class="acronym">BKI</acronym> Commands </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.6. BKI Example</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bki.html b/doc/src/sgml/html/bki.html
new file mode 100644
index 0000000..aa9c479
--- /dev/null
+++ b/doc/src/sgml/html/bki.html
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 74. System Catalog Declarations and Initial Contents</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)" /><link rel="next" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules">Next</a></td></tr></table><hr /></div><div class="chapter" id="BKI"><div class="titlepage"><div><div><h2 class="title">Chapter 74. System Catalog Declarations and Initial Contents</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="system-catalog-declarations.html">74.1. System Catalog Declaration Rules</a></span></dt><dt><span class="sect1"><a href="system-catalog-initial-data.html">74.2. System Catalog Initial Data</a></span></dt><dd><dl><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-INITIAL-DATA-FORMAT">74.2.1. Data File Format</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-ASSIGNMENT">74.2.2. OID Assignment</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-REFERENCES">74.2.3. OID Reference Lookup</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-AUTO-ARRAY-TYPES">74.2.4. Automatic Creation of Array Types</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-RECIPES">74.2.5. Recipes for Editing Data Files</a></span></dt></dl></dd><dt><span class="sect1"><a href="bki-format.html">74.3. <acronym class="acronym">BKI</acronym> File Format</a></span></dt><dt><span class="sect1"><a href="bki-commands.html">74.4. <acronym class="acronym">BKI</acronym> Commands</a></span></dt><dt><span class="sect1"><a href="bki-structure.html">74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File</a></span></dt><dt><span class="sect1"><a href="bki-example.html">74.6. BKI Example</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> uses many different system catalogs
+ to keep track of the existence and properties of database objects, such as
+ tables and functions. Physically there is no difference between a system
+ catalog and a plain user table, but the backend C code knows the structure
+ and properties of each catalog, and can manipulate it directly at a low
+ level. Thus, for example, it is inadvisable to attempt to alter the
+ structure of a catalog on-the-fly; that would break assumptions built into
+ the C code about how rows of the catalog are laid out. But the structure
+ of the catalogs can change between major versions.
+ </p><p>
+ The structures of the catalogs are declared in specially formatted C
+ header files in the <code class="filename">src/include/catalog/</code> directory of
+ the source tree. For each catalog there is a header file
+ named after the catalog (e.g., <code class="filename">pg_class.h</code>
+ for <code class="structname">pg_class</code>), which defines the set of columns
+ the catalog has, as well as some other basic properties such as its OID.
+ </p><p>
+ Many of the catalogs have initial data that must be loaded into them
+ during the <span class="quote">“<span class="quote">bootstrap</span>”</span> phase
+ of <span class="application">initdb</span>, to bring the system up to a point
+ where it is capable of executing SQL commands. (For
+ example, <code class="filename">pg_class.h</code> must contain an entry for itself,
+ as well as one for each other system catalog and index.) This
+ initial data is kept in editable form in data files that are also stored
+ in the <code class="filename">src/include/catalog/</code> directory. For example,
+ <code class="filename">pg_proc.dat</code> describes all the initial rows that must
+ be inserted into the <code class="structname">pg_proc</code> catalog.
+ </p><p>
+ To create the catalog files and load this initial data into them, a
+ backend running in bootstrap mode reads a <acronym class="acronym">BKI</acronym>
+ (Backend Interface) file containing commands and initial data.
+ The <code class="filename">postgres.bki</code> file used in this mode is prepared
+ from the aforementioned header and data files, while building
+ a <span class="productname">PostgreSQL</span> distribution, by a Perl script
+ named <code class="filename">genbki.pl</code>.
+ Although it's specific to a particular <span class="productname">PostgreSQL</span>
+ release, <code class="filename">postgres.bki</code> is platform-independent and is
+ installed in the <code class="filename">share</code> subdirectory of the
+ installation tree.
+ </p><p>
+ <code class="filename">genbki.pl</code> also produces a derived header file for
+ each catalog, for example <code class="filename">pg_class_d.h</code> for
+ the <code class="structname">pg_class</code> catalog. This file contains
+ automatically-generated macro definitions, and may contain other macros,
+ enum declarations, and so on that can be useful for client C code that
+ reads a particular catalog.
+ </p><p>
+ Most PostgreSQL developers don't need to be directly concerned with
+ the <acronym class="acronym">BKI</acronym> file, but almost any nontrivial feature
+ addition in the backend will require modifying the catalog header files
+ and/or initial data files. The rest of this chapter gives some
+ information about that, and for completeness describes
+ the <acronym class="acronym">BKI</acronym> file format.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.1. System Catalog Declaration Rules</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bloom.html b/doc/src/sgml/html/bloom.html
new file mode 100644
index 0000000..6f2361d
--- /dev/null
+++ b/doc/src/sgml/html/bloom.html
@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.7. bloom</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="basic-archive.html" title="F.6. basic_archive" /><link rel="next" href="btree-gin.html" title="F.8. btree_gin" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.7. bloom</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="basic-archive.html" title="F.6. basic_archive">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-gin.html" title="F.8. btree_gin">Next</a></td></tr></table><hr /></div><div class="sect1" id="BLOOM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.7. bloom</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.7">F.7.1. Parameters</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.8">F.7.2. Examples</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.9">F.7.3. Operator Class Interface</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.10">F.7.4. Limitations</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.11">F.7.5. Authors</a></span></dt></dl></div><a id="id-1.11.7.16.2" class="indexterm"></a><p>
+ <code class="literal">bloom</code> provides an index access method based on
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Bloom_filter" target="_top">Bloom filters</a>.
+ </p><p>
+ A Bloom filter is a space-efficient data structure that is used to test
+ whether an element is a member of a set. In the case of an index access
+ method, it allows fast exclusion of non-matching tuples via signatures
+ whose size is determined at index creation.
+ </p><p>
+ A signature is a lossy representation of the indexed attribute(s), and as
+ such is prone to reporting false positives; that is, it may be reported
+ that an element is in the set, when it is not. So index search results
+ must always be rechecked using the actual attribute values from the heap
+ entry. Larger signatures reduce the odds of a false positive and thus
+ reduce the number of useless heap visits, but of course also make the index
+ larger and hence slower to scan.
+ </p><p>
+ This type of index is most useful when a table has many attributes and
+ queries test arbitrary combinations of them. A traditional btree index is
+ faster than a bloom index, but it can require many btree indexes to support
+ all possible queries where one needs only a single bloom index. Note
+ however that bloom indexes only support equality queries, whereas btree
+ indexes can also perform inequality and range searches.
+ </p><div class="sect2" id="id-1.11.7.16.7"><div class="titlepage"><div><div><h3 class="title">F.7.1. Parameters</h3></div></div></div><p>
+ A <code class="literal">bloom</code> index accepts the following parameters in its
+ <code class="literal">WITH</code> clause:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">length</code></span></dt><dd><p>
+ Length of each signature (index entry) in bits. It is rounded up to the
+ nearest multiple of <code class="literal">16</code>. The default is
+ <code class="literal">80</code> bits and the maximum is <code class="literal">4096</code>.
+ </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">col1 — col32</code></span></dt><dd><p>
+ Number of bits generated for each index column. Each parameter's name
+ refers to the number of the index column that it controls. The default
+ is <code class="literal">2</code> bits and the maximum is <code class="literal">4095</code>.
+ Parameters for index columns not actually used are ignored.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.16.8"><div class="titlepage"><div><div><h3 class="title">F.7.2. Examples</h3></div></div></div><p>
+ This is an example of creating a bloom index:
+ </p><pre class="programlisting">
+CREATE INDEX bloomidx ON tbloom USING bloom (i1,i2,i3)
+ WITH (length=80, col1=2, col2=2, col3=4);
+</pre><p>
+ The index is created with a signature length of 80 bits, with attributes
+ i1 and i2 mapped to 2 bits, and attribute i3 mapped to 4 bits. We could
+ have omitted the <code class="literal">length</code>, <code class="literal">col1</code>,
+ and <code class="literal">col2</code> specifications since those have the default values.
+ </p><p>
+ Here is a more complete example of bloom index definition and usage, as
+ well as a comparison with equivalent btree indexes. The bloom index is
+ considerably smaller than the btree index, and can perform better.
+ </p><pre class="programlisting">
+=# CREATE TABLE tbloom AS
+ SELECT
+ (random() * 1000000)::int as i1,
+ (random() * 1000000)::int as i2,
+ (random() * 1000000)::int as i3,
+ (random() * 1000000)::int as i4,
+ (random() * 1000000)::int as i5,
+ (random() * 1000000)::int as i6
+ FROM
+ generate_series(1,10000000);
+SELECT 10000000
+</pre><p>
+ A sequential scan over this large table takes a long time:
+</p><pre class="programlisting">
+=# EXPLAIN ANALYZE SELECT * FROM tbloom WHERE i2 = 898732 AND i5 = 123451;
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------
+ Seq Scan on tbloom (cost=0.00..2137.14 rows=3 width=24) (actual time=16.971..16.971 rows=0 loops=1)
+ Filter: ((i2 = 898732) AND (i5 = 123451))
+ Rows Removed by Filter: 100000
+ Planning Time: 0.346 ms
+ Execution Time: 16.988 ms
+(5 rows)
+</pre><p>
+ </p><p>
+ Even with the btree index defined the result will still be a
+ sequential scan:
+</p><pre class="programlisting">
+=# CREATE INDEX btreeidx ON tbloom (i1, i2, i3, i4, i5, i6);
+CREATE INDEX
+=# SELECT pg_size_pretty(pg_relation_size('btreeidx'));
+ pg_size_pretty
+----------------
+ 3976 kB
+(1 row)
+=# EXPLAIN ANALYZE SELECT * FROM tbloom WHERE i2 = 898732 AND i5 = 123451;
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------
+ Seq Scan on tbloom (cost=0.00..2137.00 rows=2 width=24) (actual time=12.805..12.805 rows=0 loops=1)
+ Filter: ((i2 = 898732) AND (i5 = 123451))
+ Rows Removed by Filter: 100000
+ Planning Time: 0.138 ms
+ Execution Time: 12.817 ms
+(5 rows)
+</pre><p>
+ </p><p>
+ Having the bloom index defined on the table is better than btree in
+ handling this type of search:
+</p><pre class="programlisting">
+=# CREATE INDEX bloomidx ON tbloom USING bloom (i1, i2, i3, i4, i5, i6);
+CREATE INDEX
+=# SELECT pg_size_pretty(pg_relation_size('bloomidx'));
+ pg_size_pretty
+----------------
+ 1584 kB
+(1 row)
+=# EXPLAIN ANALYZE SELECT * FROM tbloom WHERE i2 = 898732 AND i5 = 123451;
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------------------------------
+ Bitmap Heap Scan on tbloom (cost=1792.00..1799.69 rows=2 width=24) (actual time=0.388..0.388 rows=0 loops=1)
+ Recheck Cond: ((i2 = 898732) AND (i5 = 123451))
+ Rows Removed by Index Recheck: 29
+ Heap Blocks: exact=28
+ -&gt; Bitmap Index Scan on bloomidx (cost=0.00..1792.00 rows=2 width=0) (actual time=0.356..0.356 rows=29 loops=1)
+ Index Cond: ((i2 = 898732) AND (i5 = 123451))
+ Planning Time: 0.099 ms
+ Execution Time: 0.408 ms
+(8 rows)
+</pre><p>
+ </p><p>
+ Now, the main problem with the btree search is that btree is inefficient
+ when the search conditions do not constrain the leading index column(s).
+ A better strategy for btree is to create a separate index on each column.
+ Then the planner will choose something like this:
+</p><pre class="programlisting">
+=# CREATE INDEX btreeidx1 ON tbloom (i1);
+CREATE INDEX
+=# CREATE INDEX btreeidx2 ON tbloom (i2);
+CREATE INDEX
+=# CREATE INDEX btreeidx3 ON tbloom (i3);
+CREATE INDEX
+=# CREATE INDEX btreeidx4 ON tbloom (i4);
+CREATE INDEX
+=# CREATE INDEX btreeidx5 ON tbloom (i5);
+CREATE INDEX
+=# CREATE INDEX btreeidx6 ON tbloom (i6);
+CREATE INDEX
+=# EXPLAIN ANALYZE SELECT * FROM tbloom WHERE i2 = 898732 AND i5 = 123451;
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------------------------------------
+ Bitmap Heap Scan on tbloom (cost=24.34..32.03 rows=2 width=24) (actual time=0.028..0.029 rows=0 loops=1)
+ Recheck Cond: ((i5 = 123451) AND (i2 = 898732))
+ -&gt; BitmapAnd (cost=24.34..24.34 rows=2 width=0) (actual time=0.027..0.027 rows=0 loops=1)
+ -&gt; Bitmap Index Scan on btreeidx5 (cost=0.00..12.04 rows=500 width=0) (actual time=0.026..0.026 rows=0 loops=1)
+ Index Cond: (i5 = 123451)
+ -&gt; Bitmap Index Scan on btreeidx2 (cost=0.00..12.04 rows=500 width=0) (never executed)
+ Index Cond: (i2 = 898732)
+ Planning Time: 0.491 ms
+ Execution Time: 0.055 ms
+(9 rows)
+</pre><p>
+ Although this query runs much faster than with either of the single
+ indexes, we pay a penalty in index size. Each of the single-column
+ btree indexes occupies 2 MB, so the total space needed is 12 MB,
+ eight times the space used by the bloom index.
+ </p></div><div class="sect2" id="id-1.11.7.16.9"><div class="titlepage"><div><div><h3 class="title">F.7.3. Operator Class Interface</h3></div></div></div><p>
+ An operator class for bloom indexes requires only a hash function for the
+ indexed data type and an equality operator for searching. This example
+ shows the operator class definition for the <code class="type">text</code> data type:
+ </p><pre class="programlisting">
+CREATE OPERATOR CLASS text_ops
+DEFAULT FOR TYPE text USING bloom AS
+ OPERATOR 1 =(text, text),
+ FUNCTION 1 hashtext(text);
+</pre></div><div class="sect2" id="id-1.11.7.16.10"><div class="titlepage"><div><div><h3 class="title">F.7.4. Limitations</h3></div></div></div><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Only operator classes for <code class="type">int4</code> and <code class="type">text</code> are
+ included with the module.
+ </p></li><li class="listitem"><p>
+ Only the <code class="literal">=</code> operator is supported for search. But
+ it is possible to add support for arrays with union and intersection
+ operations in the future.
+ </p></li><li class="listitem"><p>
+ <code class="literal">bloom</code> access method doesn't support
+ <code class="literal">UNIQUE</code> indexes.
+ </p></li><li class="listitem"><p>
+ <code class="literal">bloom</code> access method doesn't support searching for
+ <code class="literal">NULL</code> values.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="id-1.11.7.16.11"><div class="titlepage"><div><div><h3 class="title">F.7.5. Authors</h3></div></div></div><p>
+ Teodor Sigaev <code class="email">&lt;<a class="email" href="mailto:teodor@postgrespro.ru">teodor@postgrespro.ru</a>&gt;</code>,
+ Postgres Professional, Moscow, Russia
+ </p><p>
+ Alexander Korotkov <code class="email">&lt;<a class="email" href="mailto:a.korotkov@postgrespro.ru">a.korotkov@postgrespro.ru</a>&gt;</code>,
+ Postgres Professional, Moscow, Russia
+ </p><p>
+ Oleg Bartunov <code class="email">&lt;<a class="email" href="mailto:obartunov@postgrespro.ru">obartunov@postgrespro.ru</a>&gt;</code>,
+ Postgres Professional, Moscow, Russia
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="basic-archive.html" title="F.6. basic_archive">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-gin.html" title="F.8. btree_gin">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.6. basic_archive </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.8. btree_gin</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bookindex.html b/doc/src/sgml/html/bookindex.html
new file mode 100644
index 0000000..af8450b
--- /dev/null
+++ b/doc/src/sgml/html/bookindex.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Index</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="biblio.html" title="Bibliography" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Index</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="biblio.html" title="Bibliography">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> </td></tr></table><hr /></div><div class="index" id="BOOKINDEX"><div class="titlepage"><div><div><h1 class="title">Index</h1></div></div></div><div xmlns:xlink="http://www.w3.org/1999/xlink" class="index"><p class="indexdiv-quicklinks"><a href="#indexdiv-Symbols">Symbols</a>
+ |
+ <a href="#indexdiv-A">A</a>
+ |
+ <a href="#indexdiv-B">B</a>
+ |
+ <a href="#indexdiv-C">C</a>
+ |
+ <a href="#indexdiv-D">D</a>
+ |
+ <a href="#indexdiv-E">E</a>
+ |
+ <a href="#indexdiv-F">F</a>
+ |
+ <a href="#indexdiv-G">G</a>
+ |
+ <a href="#indexdiv-H">H</a>
+ |
+ <a href="#indexdiv-I">I</a>
+ |
+ <a href="#indexdiv-J">J</a>
+ |
+ <a href="#indexdiv-K">K</a>
+ |
+ <a href="#indexdiv-L">L</a>
+ |
+ <a href="#indexdiv-M">M</a>
+ |
+ <a href="#indexdiv-N">N</a>
+ |
+ <a href="#indexdiv-O">O</a>
+ |
+ <a href="#indexdiv-P">P</a>
+ |
+ <a href="#indexdiv-Q">Q</a>
+ |
+ <a href="#indexdiv-R">R</a>
+ |
+ <a href="#indexdiv-S">S</a>
+ |
+ <a href="#indexdiv-T">T</a>
+ |
+ <a href="#indexdiv-U">U</a>
+ |
+ <a href="#indexdiv-V">V</a>
+ |
+ <a href="#indexdiv-W">W</a>
+ |
+ <a href="#indexdiv-X">X</a>
+ |
+ <a href="#indexdiv-Y">Y</a>
+ |
+ <a href="#indexdiv-Z">Z</a></p><div class="indexdiv" id="indexdiv-Symbols"><h3>Symbols</h3><dl><dt id="ientry-idm1813">$, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL">Positional Parameters</a></dt><dt id="ientry-idm74039">$libdir, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm43700">$libdir/plugins, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">Shared Library Preloading</a>, <a class="indexterm" href="sql-load.html#SQL-LOAD-DESCRIPTION">Description</a></dt><dt id="ientry-idm5260">*, <a class="indexterm" href="queries-select-lists.html#QUERIES-SELECT-LIST-ITEMS">Select-List Items</a></dt><dt id="ientry-idm61948">.pgpass, <a class="indexterm" href="libpq-pgpass.html">The Password File</a></dt><dt id="ientry-idm61983">.pg_service.conf, <a class="indexterm" href="libpq-pgservice.html">The Connection Service File</a></dt><dt id="ientry-idm2213">::, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">Type Casts</a></dt><dt id="ientry-idm87827">_PG_archive_module_init, <a class="indexterm" href="archive-module-init.html">Initialization Functions</a></dt><dt id="ientry-idm74072">_PG_init, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm87390">_PG_output_plugin_init, <a class="indexterm" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-INIT">Initialization Function</a></dt></dl></div><div class="indexdiv" id="indexdiv-A"><h3>A</h3><dl><dt id="ientry-idm19569">abbrev, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm87879">ABORT, <a class="indexterm" href="sql-abort.html">ABORT</a></dt><dt id="ientry-idm11175">abs, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm3034">ACL, <a class="indexterm" href="ddl-priv.html">Privileges</a></dt><dt id="ientry-idm26897">aclcontains, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26936">acldefault, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26968">aclexplode, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm3465">aclitem, <a class="indexterm" href="ddl-priv.html">Privileges</a></dt><dt id="ientry-idm26881">aclitemeq, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm11732">acos, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11744">acosd, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm12001">acosh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm173482">administration tools</dt><dd><dl><dt>externally maintained, <a class="indexterm" href="external-admin-tools.html">Administration Tools</a></dt></dl></dd><dt id="ientry-idm163324">adminpack, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm34240">advisory lock, <a class="indexterm" href="explicit-locking.html#ADVISORY-LOCKS">Advisory Locks</a></dt><dt id="ientry-idm17145">age, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm828">aggregate function, <a class="indexterm" href="tutorial-agg.html">Aggregate Functions</a>, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a>, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a>, <a class="indexterm" href="xaggr.html">User-Defined Aggregates</a></dt><dd><dl><dt>built-in, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt>invocation, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a></dt><dt>moving aggregate, <a class="indexterm" href="xaggr.html#XAGGR-MOVING-AGGREGATES">Moving-Aggregate Mode</a></dt><dt>ordered set, <a class="indexterm" href="xaggr.html#XAGGR-ORDERED-SET-AGGREGATES">Ordered-Set Aggregates</a></dt><dt>partial aggregation, <a class="indexterm" href="xaggr.html#XAGGR-PARTIAL-AGGREGATES">Partial Aggregation</a></dt><dt>polymorphic, <a class="indexterm" href="xaggr.html#XAGGR-POLYMORPHIC-AGGREGATES">Polymorphic and Variadic Aggregates</a></dt><dt>support functions for, <a class="indexterm" href="xaggr.html#XAGGR-SUPPORT-FUNCTIONS">Support Functions for Aggregates</a></dt><dt>user-defined, <a class="indexterm" href="xaggr.html">User-Defined Aggregates</a></dt><dt>variadic, <a class="indexterm" href="xaggr.html#XAGGR-POLYMORPHIC-AGGREGATES">Polymorphic and Variadic Aggregates</a></dt></dl></dd><dt id="ientry-idm36421">AIX, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-AIX">AIX</a></dt><dd><dl><dt>installation on, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-AIX">AIX</a></dt><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt></dl></dd><dt id="ientry-idm166339">akeys, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm810">alias, <a class="indexterm" href="queries-table-expressions.html#QUERIES-TABLE-ALIASES">Table and Column Aliases</a>, <a class="indexterm" href="queries-select-lists.html#QUERIES-COLUMN-LABELS">Column Labels</a></dt><dd><dl><dt>for table name in query, <a class="indexterm" href="tutorial-join.html">Joins Between Tables</a></dt><dt>in the FROM clause, <a class="indexterm" href="queries-table-expressions.html#QUERIES-TABLE-ALIASES">Table and Column Aliases</a></dt><dt>in the select list, <a class="indexterm" href="queries-select-lists.html#QUERIES-COLUMN-LABELS">Column Labels</a></dt></dl></dd><dt id="ientry-idm5202">ALL, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a>, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a>, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dd><dl><dt>GROUP BY ALL, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a></dt><dt>SELECT ALL, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a></dt></dl></dd><dt id="ientry-idm44352">allow_in_place_tablespaces configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44364">allow_system_table_mods configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm87941">ALTER AGGREGATE, <a class="indexterm" href="sql-alteraggregate.html">ALTER AGGREGATE</a></dt><dt id="ientry-idm88064">ALTER COLLATION, <a class="indexterm" href="sql-altercollation.html">ALTER COLLATION</a></dt><dt id="ientry-idm88157">ALTER CONVERSION, <a class="indexterm" href="sql-alterconversion.html">ALTER CONVERSION</a></dt><dt id="ientry-idm88226">ALTER DATABASE, <a class="indexterm" href="sql-alterdatabase.html">ALTER DATABASE</a></dt><dt id="ientry-idm88360">ALTER DEFAULT PRIVILEGES, <a class="indexterm" href="sql-alterdefaultprivileges.html">ALTER DEFAULT PRIVILEGES</a></dt><dt id="ientry-idm88464">ALTER DOMAIN, <a class="indexterm" href="sql-alterdomain.html">ALTER DOMAIN</a></dt><dt id="ientry-idm88663">ALTER EVENT TRIGGER, <a class="indexterm" href="sql-altereventtrigger.html">ALTER EVENT TRIGGER</a></dt><dt id="ientry-idm88722">ALTER EXTENSION, <a class="indexterm" href="sql-alterextension.html">ALTER EXTENSION</a></dt><dt id="ientry-idm88950">ALTER FOREIGN DATA WRAPPER, <a class="indexterm" href="sql-alterforeigndatawrapper.html">ALTER FOREIGN DATA WRAPPER</a></dt><dt id="ientry-idm89057">ALTER FOREIGN TABLE, <a class="indexterm" href="sql-alterforeigntable.html">ALTER FOREIGN TABLE</a></dt><dt id="ientry-idm89391">ALTER FUNCTION, <a class="indexterm" href="sql-alterfunction.html">ALTER FUNCTION</a></dt><dt id="ientry-idm89640">ALTER GROUP, <a class="indexterm" href="sql-altergroup.html">ALTER GROUP</a></dt><dt id="ientry-idm89713">ALTER INDEX, <a class="indexterm" href="sql-alterindex.html">ALTER INDEX</a></dt><dt id="ientry-idm89895">ALTER LANGUAGE, <a class="indexterm" href="sql-alterlanguage.html">ALTER LANGUAGE</a></dt><dt id="ientry-idm89945">ALTER LARGE OBJECT, <a class="indexterm" href="sql-alterlargeobject.html">ALTER LARGE OBJECT</a></dt><dt id="ientry-idm89987">ALTER MATERIALIZED VIEW, <a class="indexterm" href="sql-altermaterializedview.html">ALTER MATERIALIZED VIEW</a></dt><dt id="ientry-idm90104">ALTER OPERATOR, <a class="indexterm" href="sql-alteroperator.html">ALTER OPERATOR</a></dt><dt id="ientry-idm90196">ALTER OPERATOR CLASS, <a class="indexterm" href="sql-alteropclass.html">ALTER OPERATOR CLASS</a></dt><dt id="ientry-idm90265">ALTER OPERATOR FAMILY, <a class="indexterm" href="sql-alteropfamily.html">ALTER OPERATOR FAMILY</a></dt><dt id="ientry-idm90438">ALTER POLICY, <a class="indexterm" href="sql-alterpolicy.html">ALTER POLICY</a></dt><dt id="ientry-idm90521">ALTER PROCEDURE, <a class="indexterm" href="sql-alterprocedure.html">ALTER PROCEDURE</a></dt><dt id="ientry-idm90699">ALTER PUBLICATION, <a class="indexterm" href="sql-alterpublication.html">ALTER PUBLICATION</a></dt><dt id="ientry-idm46172">ALTER ROLE, <a class="indexterm" href="role-attributes.html">Role Attributes</a>, <a class="indexterm" href="sql-alterrole.html">ALTER ROLE</a></dt><dt id="ientry-idm91057">ALTER ROUTINE, <a class="indexterm" href="sql-alterroutine.html">ALTER ROUTINE</a></dt><dt id="ientry-idm91137">ALTER RULE, <a class="indexterm" href="sql-alterrule.html">ALTER RULE</a></dt><dt id="ientry-idm91192">ALTER SCHEMA, <a class="indexterm" href="sql-alterschema.html">ALTER SCHEMA</a></dt><dt id="ientry-idm91246">ALTER SEQUENCE, <a class="indexterm" href="sql-altersequence.html">ALTER SEQUENCE</a></dt><dt id="ientry-idm91468">ALTER SERVER, <a class="indexterm" href="sql-alterserver.html">ALTER SERVER</a></dt><dt id="ientry-idm91550">ALTER STATISTICS, <a class="indexterm" href="sql-alterstatistics.html">ALTER STATISTICS</a></dt><dt id="ientry-idm91624">ALTER SUBSCRIPTION, <a class="indexterm" href="sql-altersubscription.html">ALTER SUBSCRIPTION</a></dt><dt id="ientry-idm91829">ALTER SYSTEM, <a class="indexterm" href="sql-altersystem.html">ALTER SYSTEM</a></dt><dt id="ientry-idm91909">ALTER TABLE, <a class="indexterm" href="sql-altertable.html">ALTER TABLE</a></dt><dt id="ientry-idm92847">ALTER TABLESPACE, <a class="indexterm" href="sql-altertablespace.html">ALTER TABLESPACE</a></dt><dt id="ientry-idm92925">ALTER TEXT SEARCH CONFIGURATION, <a class="indexterm" href="sql-altertsconfig.html">ALTER TEXT SEARCH CONFIGURATION</a></dt><dt id="ientry-idm93036">ALTER TEXT SEARCH DICTIONARY, <a class="indexterm" href="sql-altertsdictionary.html">ALTER TEXT SEARCH DICTIONARY</a></dt><dt id="ientry-idm93119">ALTER TEXT SEARCH PARSER, <a class="indexterm" href="sql-altertsparser.html">ALTER TEXT SEARCH PARSER</a></dt><dt id="ientry-idm93170">ALTER TEXT SEARCH TEMPLATE, <a class="indexterm" href="sql-altertstemplate.html">ALTER TEXT SEARCH TEMPLATE</a></dt><dt id="ientry-idm93221">ALTER TRIGGER, <a class="indexterm" href="sql-altertrigger.html">ALTER TRIGGER</a></dt><dt id="ientry-idm93295">ALTER TYPE, <a class="indexterm" href="sql-altertype.html">ALTER TYPE</a></dt><dt id="ientry-idm93557">ALTER USER, <a class="indexterm" href="sql-alteruser.html">ALTER USER</a></dt><dt id="ientry-idm93609">ALTER USER MAPPING, <a class="indexterm" href="sql-alterusermapping.html">ALTER USER MAPPING</a></dt><dt id="ientry-idm93681">ALTER VIEW, <a class="indexterm" href="sql-alterview.html">ALTER VIEW</a></dt><dt id="ientry-idm163435">amcheck, <a class="indexterm" href="amcheck.html">amcheck</a></dt><dt id="ientry-idm49039">ANALYZE, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS">Updating Planner Statistics</a>, <a class="indexterm" href="sql-analyze.html">ANALYZE</a></dt><dt id="ientry-idm10360">AND (operator), <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm104292">anonymous code blocks, <a class="indexterm" href="sql-do.html">DO</a></dt><dt id="ientry-idm10126">any, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm24944">ANY, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a>, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm10130">anyarray, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10140">anycompatible, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10142">anycompatiblearray, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10148">anycompatiblemultirange, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10144">anycompatiblenonarray, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10146">anycompatiblerange, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10128">anyelement, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10134">anyenum, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10138">anymultirange, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10132">anynonarray, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm10136">anyrange, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm67623">applicable role, <a class="indexterm" href="infoschema-applicable-roles.html">applicable_roles</a></dt><dt id="ientry-idm41959">application_name configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm6262">arbitrary precision numbers, <a class="indexterm" href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">Arbitrary Precision Numbers</a></dt><dt id="ientry-idm87812">Archive Modules, <a class="indexterm" href="archive-modules.html">Archive Modules</a></dt><dt id="ientry-idm40286">archive_cleanup_command configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a></dt><dt id="ientry-idm40151">archive_command configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">Archiving</a></dt><dt id="ientry-idm40175">archive_library configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">Archiving</a></dt><dt id="ientry-idm40124">archive_mode configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">Archiving</a></dt><dt id="ientry-idm40189">archive_timeout configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">Archiving</a></dt><dt id="ientry-idm18954">area, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm168863">armor, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.16">armor(), dearmor()</a></dt><dt id="ientry-idm2281">array, <a class="indexterm" href="arrays.html">Arrays</a></dt><dd><dl><dt>accessing, <a class="indexterm" href="arrays.html#ARRAYS-ACCESSING">Accessing Arrays</a></dt><dt>constant, <a class="indexterm" href="arrays.html#ARRAYS-INPUT">Array Value Input</a></dt><dt>constructor, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS">Array Constructors</a></dt><dt>declaration, <a class="indexterm" href="arrays.html#ARRAYS-DECLARATION">Declaration of Array Types</a></dt><dt>I/O, <a class="indexterm" href="arrays.html#ARRAYS-IO">Array Input and Output Syntax</a></dt><dt>modifying, <a class="indexterm" href="arrays.html#ARRAYS-MODIFYING">Modifying Arrays</a></dt><dt>of user-defined type, <a class="indexterm" href="xtypes.html">User-Defined Types</a></dt><dt>searching, <a class="indexterm" href="arrays.html#ARRAYS-SEARCHING">Searching in Arrays</a></dt></dl></dd><dt id="ientry-idm2284">ARRAY, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS">Array Constructors</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm24581">array_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a>, <a class="indexterm" href="intagg.html#id-1.11.7.28.4">Functions</a></dt><dt id="ientry-idm23521">array_append, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23537">array_cat, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23553">array_dims, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23565">array_fill, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23584">array_length, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23603">array_lower, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23616">array_ndims, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm43890">array_nulls configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm23628">array_position, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23646">array_positions, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23663">array_prepend, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23679">array_remove, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm23694">array_replace, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm21723">array_to_json, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm23708">array_to_string, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm19977">array_to_tsvector, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm23732">array_upper, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm12423">ascii, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm11756">asin, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11768">asind, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11989">asinh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm81455">ASSERT</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">Checking Assertions</a></dt></dl></dd><dt id="ientry-idm81458">assertions</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">Checking Assertions</a></dt></dl></dd><dt id="ientry-idm56382">asynchronous commit, <a class="indexterm" href="wal-async-commit.html">Asynchronous Commit</a></dt><dt id="ientry-idm18118">AT TIME ZONE, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT">AT TIME ZONE</a></dt><dt id="ientry-idm11780">atan, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11804">atan2, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11821">atan2d, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11792">atand, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm12013">atanh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm38790">authentication_timeout configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt><dt id="ientry-idm163663">auth_delay, <a class="indexterm" href="auth-delay.html">auth_delay</a></dt><dt id="ientry-idm163677">auth_delay.milliseconds configuration parameter, <a class="indexterm" href="auth-delay.html#id-1.11.7.12.5">Configuration Parameters</a></dt><dt id="ientry-idm6468">auto-increment (see <a href="#ientry-idm6458">serial</a>)</dt><dt id="ientry-idm34810">autocommit</dt><dd><dl><dt>bulk-loading data, <a class="indexterm" href="populate.html#DISABLE-AUTOCOMMIT">Disable Autocommit</a></dt><dt>psql, <a class="indexterm" href="app-psql.html#APP-PSQL-VARIABLES">Variables</a></dt></dl></dd><dt id="ientry-idm97823">autosummarize storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt><dt id="ientry-idm42789">autovacuum</dt><dd><dl><dt>configuration parameters, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>general information, <a class="indexterm" href="routine-vacuuming.html#AUTOVACUUM">The Autovacuum Daemon</a></dt></dl></dd><dt id="ientry-idm42801">autovacuum configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt id="ientry-idm42899">autovacuum_analyze_scale_factor</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42861">autovacuum_analyze_threshold</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm101408">autovacuum_enabled storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm42912">autovacuum_freeze_max_age</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm101557">autovacuum_freeze_min_age storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm101583">autovacuum_freeze_table_age storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm42814">autovacuum_max_workers configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt id="ientry-idm42928">autovacuum_multixact_freeze_max_age</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm101594">autovacuum_multixact_freeze_min_age storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm101620">autovacuum_multixact_freeze_table_age storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm42823">autovacuum_naptime configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt id="ientry-idm42945">autovacuum_vacuum_cost_delay</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42958">autovacuum_vacuum_cost_limit</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42886">autovacuum_vacuum_insert_scale_factor</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42848">autovacuum_vacuum_insert_threshold</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42873">autovacuum_vacuum_scale_factor</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm42836">autovacuum_vacuum_threshold</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-autovacuum.html">Automatic Vacuuming</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm39273">autovacuum_work_mem configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm163691">auto_explain, <a class="indexterm" href="auto-explain.html">auto_explain</a></dt><dt id="ientry-idm163725">auto_explain.log_analyze configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163740">auto_explain.log_buffers configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163812">auto_explain.log_format configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163827">auto_explain.log_level configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163712">auto_explain.log_min_duration configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163847">auto_explain.log_nested_statements configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163802">auto_explain.log_settings configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163766">auto_explain.log_timing configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163779">auto_explain.log_triggers configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163790">auto_explain.log_verbose configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163753">auto_explain.log_wal configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm163857">auto_explain.sample_rate configuration parameter, <a class="indexterm" href="auto-explain.html#id-1.11.7.13.5">Configuration Parameters</a></dt><dt id="ientry-idm166366">avals, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm24599">average, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24601">avg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></div><div class="indexdiv" id="indexdiv-B"><h3>B</h3><dl><dt id="ientry-idm31183">B-Tree (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm39529">backend_flush_after configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm87094">Background workers, <a class="indexterm" href="bgworker.html">Background Worker Processes</a></dt><dt id="ientry-idm1308">backslash escapes, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE">String Constants with C-Style Escapes</a></dt><dt id="ientry-idm43910">backslash_quote configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm44374">backtrace_functions configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm28732">backup, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a>, <a class="indexterm" href="backup.html">Backup and Restore</a></dt><dt id="ientry-idm148703">Backup Manifest, <a class="indexterm" href="backup-manifest-format.html">Backup Manifest Format</a></dt><dt id="ientry-idm73170">base type, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dt id="ientry-idm14035">base64 format, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm163877">basebackup_to_shell, <a class="indexterm" href="basebackup-to-shell.html">basebackup_to_shell</a></dt><dt id="ientry-idm163895">basebackup_to_shell.command configuration parameter, <a class="indexterm" href="basebackup-to-shell.html#id-1.11.7.14.5">Configuration Parameters</a></dt><dt id="ientry-idm163911">basebackup_to_shell.required_role configuration parameter, <a class="indexterm" href="basebackup-to-shell.html#id-1.11.7.14.5">Configuration Parameters</a></dt><dt id="ientry-idm138677">BASE_BACKUP, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm163924">basic_archive, <a class="indexterm" href="basic-archive.html">basic_archive</a></dt><dt id="ientry-idm163939">basic_archive.archive_directory configuration parameter, <a class="indexterm" href="basic-archive.html#id-1.11.7.15.5">Configuration Parameters</a></dt><dt id="ientry-idm60371">batch mode, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a></dt></dl></dd><dt id="ientry-idm93982">BEGIN, <a class="indexterm" href="sql-begin.html">BEGIN</a></dt><dt id="ientry-idm10757">BETWEEN, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10759">BETWEEN SYMMETRIC, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm87141">BGWORKER_BACKEND_​DATABASE_CONNECTION, <a class="indexterm" href="bgworker.html">Background Worker Processes</a></dt><dt id="ientry-idm87134">BGWORKER_SHMEM_ACCESS, <a class="indexterm" href="bgworker.html">Background Worker Processes</a></dt><dt id="ientry-idm39468">bgwriter_delay configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">Background Writer</a></dt><dt id="ientry-idm39505">bgwriter_flush_after configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">Background Writer</a></dt><dt id="ientry-idm39482">bgwriter_lru_maxpages configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">Background Writer</a></dt><dt id="ientry-idm39492">bgwriter_lru_multiplier configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">Background Writer</a></dt><dt id="ientry-idm1483">bigint, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC">Numeric Constants</a>, <a class="indexterm" href="datatype-numeric.html#DATATYPE-INT">Integer Types</a></dt><dt id="ientry-idm6460">bigserial, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm6732">binary data, <a class="indexterm" href="datatype-binary.html">Binary Data Types</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dd><dl><dt>functions, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt></dl></dd><dt id="ientry-idm13471">binary string</dt><dd><dl><dt>concatenation, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt>converting to character string, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt>length, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt></dl></dd><dt id="ientry-idm35396">bison, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm1441">bit string, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-BIT-STRINGS">Bit-String Constants</a>, <a class="indexterm" href="datatype-bit.html">Bit String Types</a></dt><dd><dl><dt>constant, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-BIT-STRINGS">Bit-String Constants</a></dt><dt>data type, <a class="indexterm" href="datatype-bit.html">Bit String Types</a></dt><dt>length, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt></dl></dd><dt id="ientry-idm14077">bit strings, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dd><dl><dt>functions, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt></dl></dd><dt id="ientry-idm31367">bitmap scan, <a class="indexterm" href="indexes-bitmap-scans.html">Combining Multiple Indexes</a>, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm24635">bit_and, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm13640">bit_count, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm12114">bit_length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm24657">bit_or, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24679">bit_xor, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm62459">BLOB (see <a href="#ientry-idm62457">large object</a>)</dt><dt id="ientry-idm44113">block_size configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm163957">bloom, <a class="indexterm" href="bloom.html">bloom</a></dt><dt id="ientry-idm38694">bonjour configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38704">bonjour_name configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm7853">Boolean, <a class="indexterm" href="datatype-boolean.html">Boolean Type</a></dt><dd><dl><dt>data type, <a class="indexterm" href="datatype-boolean.html">Boolean Type</a></dt><dt>operators (see operators, logical)</dt></dl></dd><dt id="ientry-idm24701">bool_and, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24711">bool_or, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm37136">booting</dt><dd><dl><dt>starting the server during, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm19188">bound_box, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm19145">box, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm8129">box (data type), <a class="indexterm" href="datatype-geometric.html#id-1.5.7.16.8">Boxes</a></dt><dt id="ientry-idm31275">BRIN (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm29818">brin_desummarize_range, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">Index Maintenance Functions</a></dt><dt id="ientry-idm168179">brin_metapage_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.7">BRIN Functions</a></dt><dt id="ientry-idm168199">brin_page_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.7">BRIN Functions</a></dt><dt id="ientry-idm168168">brin_page_type, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.7">BRIN Functions</a></dt><dt id="ientry-idm168189">brin_revmap_data, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.7">BRIN Functions</a></dt><dt id="ientry-idm29795">brin_summarize_new_values, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">Index Maintenance Functions</a></dt><dt id="ientry-idm29805">brin_summarize_range, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">Index Maintenance Functions</a></dt><dt id="ientry-idm19595">broadcast, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm45963">BSD Authentication, <a class="indexterm" href="auth-bsd.html">BSD Authentication</a></dt><dt id="ientry-idm164039">btree_gin, <a class="indexterm" href="btree-gin.html">btree_gin</a></dt><dt id="ientry-idm164086">btree_gist, <a class="indexterm" href="btree-gist.html">btree_gist</a></dt><dt id="ientry-idm12437">btrim, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm163456">bt_index_check, <a class="indexterm" href="amcheck.html#id-1.11.7.11.8">Functions</a></dt><dt id="ientry-idm163475">bt_index_parent_check, <a class="indexterm" href="amcheck.html#id-1.11.7.11.8">Functions</a></dt><dt id="ientry-idm168103">bt_metap, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.6">B-Tree Functions</a></dt><dt id="ientry-idm168121">bt_page_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.6">B-Tree Functions</a></dt><dt id="ientry-idm168112">bt_page_stats, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.6">B-Tree Functions</a></dt><dt id="ientry-idm97759">buffering storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt><dt id="ientry-idm6734">bytea, <a class="indexterm" href="datatype-binary.html">Binary Data Types</a></dt><dt id="ientry-idm43426">bytea_output configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></div><div class="indexdiv" id="indexdiv-C"><h3>C</h3><dl><dt id="ientry-idm57678">C, <a class="indexterm" href="libpq.html">libpq — C Library</a>, <a class="indexterm" href="ecpg.html">ECPG — Embedded SQL in C</a></dt><dt id="ientry-idm74832">C++, <a class="indexterm" href="xfunc-c.html#EXTEND-CPP">Using C++ for Extensibility</a></dt><dt id="ientry-idm94069">CALL, <a class="indexterm" href="sql-call.html">CALL</a></dt><dt id="ientry-idm60628">canceling, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dd><dl><dt>SQL command, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt></dl></dd><dt id="ientry-idm23745">cardinality, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm2770">CASCADE, <a class="indexterm" href="ddl-depend.html">Dependency Tracking</a></dt><dd><dl><dt>with DROP, <a class="indexterm" href="ddl-depend.html">Dependency Tracking</a></dt><dt>foreign key action, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt></dl></dd><dt id="ientry-idm50498">Cascading Replication, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm23258">CASE, <a class="indexterm" href="functions-conditional.html">Conditional Expressions</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm1227">case sensitivity</dt><dd><dl><dt>of SQL commands, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt></dl></dd><dt id="ientry-idm95910">cast, <a class="indexterm" href="sql-createcast.html">CREATE CAST</a></dt><dd><dl><dt>I/O conversion, <a class="indexterm" href="sql-createcast.html">CREATE CAST</a></dt></dl></dd><dt id="ientry-idm11188">cbrt, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11200">ceil, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11219">ceiling, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm18971">center, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm45916">Certificate, <a class="indexterm" href="auth-cert.html">Certificate Authentication</a></dt><dt id="ientry-idm81286">chained transactions, <a class="indexterm" href="plpgsql-transactions.html#PLPGSQL-TRANSACTION-CHAIN">Transaction Management</a>, <a class="indexterm" href="sql-commit.html#SQL-COMMIT-CHAIN">Parameters</a>, <a class="indexterm" href="sql-rollback.html#SQL-ROLLBACK-CHAIN">Parameters</a></dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-transactions.html#PLPGSQL-TRANSACTION-CHAIN">Transaction Management</a></dt></dl></dd><dt id="ientry-idm6592">char, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dt id="ientry-idm6586">character, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dt id="ientry-idm43609">character set, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a>, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a>, <a class="indexterm" href="multibyte.html">Character Set Support</a></dt><dt id="ientry-idm1285">character string, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS">String Constants</a>, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dd><dl><dt>concatenation, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt>constant, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS">String Constants</a></dt><dt>converting to binary string, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt>data types, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dt>length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt>prefix test, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt></dl></dd><dt id="ientry-idm6588">character varying, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dt id="ientry-idm12140">character_length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm12127">char_length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm2605">check constraint, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">Check Constraints</a></dt><dt id="ientry-idm103630">CHECK OPTION, <a class="indexterm" href="sql-createview.html">CREATE VIEW</a></dt><dt id="ientry-idm56428">checkpoint, <a class="indexterm" href="wal-configuration.html">WAL Configuration</a></dt><dt id="ientry-idm94137">CHECKPOINT, <a class="indexterm" href="sql-checkpoint.html">CHECKPOINT</a></dt><dt id="ientry-idm40055">checkpoint_completion_target configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm40065">checkpoint_flush_after configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm40044">checkpoint_timeout configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm40083">checkpoint_warning configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm56339">checksums, <a class="indexterm" href="checksums.html">Data Checksums</a></dt><dt id="ientry-idm43139">check_function_bodies configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm12455">chr, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm9895">cid, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm8301">cidr, <a class="indexterm" href="datatype-net-types.html#DATATYPE-CIDR">cidr</a></dt><dt id="ientry-idm8216">circle, <a class="indexterm" href="datatype-geometric.html#DATATYPE-CIRCLE">Circles</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm164160">citext, <a class="indexterm" href="citext.html">citext</a></dt><dt id="ientry-idm38787">client authentication, <a class="indexterm" href="client-authentication.html">Client Authentication</a></dt><dd><dl><dt>timeout during, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt></dl></dd><dt id="ientry-idm38764">client_connection_check_interval configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm43606">client_encoding configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm42976">client_min_messages configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm17170">clock_timestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm94169">CLOSE, <a class="indexterm" href="sql-close.html">CLOSE</a></dt><dt id="ientry-idm622">cluster</dt><dd><dl><dt>of databases (see <a href="#ientry-idm620">database cluster</a>)</dt></dl></dd><dt id="ientry-idm94239">CLUSTER, <a class="indexterm" href="sql-cluster.html">CLUSTER</a></dt><dt id="ientry-idm113365">clusterdb, <a class="indexterm" href="app-clusterdb.html">clusterdb</a></dt><dt id="ientry-idm50075">clustering, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm42597">cluster_name configuration parameter, <a class="indexterm" href="runtime-config-logging.html#id-1.6.7.11.8">Process Title</a></dt><dt id="ientry-idm2885">cmax, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm2871">cmin, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm23335">COALESCE, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-COALESCE-NVL-IFNULL">COALESCE</a></dt><dt id="ientry-idm2244">COLLATE, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-COLLATE-EXPRS">Collation Expressions</a></dt><dt id="ientry-idm46861">collation, <a class="indexterm" href="collation.html">Collation Support</a></dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-declarations.html#PLPGSQL-DECLARATION-COLLATION">Collation of PL/pgSQL Variables</a></dt><dt>in SQL functions, <a class="indexterm" href="xfunc-sql.html#id-1.8.3.8.21">SQL Functions with Collations</a></dt></dl></dd><dt id="ientry-idm27568">COLLATION FOR, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm175474">color, <a class="indexterm" href="color.html">Color Support</a></dt><dt id="ientry-idm615">column, <a class="indexterm" href="tutorial-concepts.html">Concepts</a>, <a class="indexterm" href="ddl-basics.html">Table Basics</a></dt><dd><dl><dt>adding, <a class="indexterm" href="ddl-alter.html#DDL-ALTER-ADDING-A-COLUMN">Adding a Column</a></dt><dt>removing, <a class="indexterm" href="ddl-alter.html#DDL-ALTER-REMOVING-A-COLUMN">Removing a Column</a></dt><dt>renaming, <a class="indexterm" href="ddl-alter.html#id-1.5.4.8.11">Renaming a Column</a></dt><dt>system column, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt></dl></dd><dt id="ientry-idm2999">column data type</dt><dd><dl><dt>changing, <a class="indexterm" href="ddl-alter.html#id-1.5.4.8.10">Changing a Column's Data Type</a></dt></dl></dd><dt id="ientry-idm1798">column reference, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-COLUMN-REFS">Column References</a></dt><dt id="ientry-idm27958">col_description, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm1599">comment, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS">Comments</a></dt><dd><dl><dt>about database objects, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt>in SQL, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS">Comments</a></dt></dl></dd><dt id="ientry-idm94366">COMMENT, <a class="indexterm" href="sql-comment.html">COMMENT</a></dt><dt id="ientry-idm94602">COMMIT, <a class="indexterm" href="sql-commit.html">COMMIT</a></dt><dt id="ientry-idm94660">COMMIT PREPARED, <a class="indexterm" href="sql-commit-prepared.html">COMMIT PREPARED</a></dt><dt id="ientry-idm40012">commit_delay configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm40031">commit_siblings configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm5567">common table expression (see <a href="#ientry-idm5564">WITH</a>)</dt><dt id="ientry-idm10456">comparison, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a>, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a></dt><dd><dl><dt>composite type, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt>operators, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt>row constructor, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt>subquery result row, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a></dt></dl></dd><dt id="ientry-idm62376">compiling, <a class="indexterm" href="libpq-build.html">Building libpq Programs</a></dt><dd><dl><dt>libpq applications, <a class="indexterm" href="libpq-build.html">Building libpq Programs</a></dt></dl></dd><dt id="ientry-idm2313">composite type, <a class="indexterm" href="rowtypes.html">Composite Types</a>, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dd><dl><dt>comparison, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt>constant, <a class="indexterm" href="rowtypes.html#id-1.5.7.24.6">Constructing Composite Values</a></dt><dt>constructor, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS">Row Constructors</a></dt></dl></dd><dt id="ientry-idm9579">computed field, <a class="indexterm" href="rowtypes.html#ROWTYPES-USAGE">Using Composite Types in Queries</a></dt><dt id="ientry-idm42736">compute_query_id configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">Statistics Monitoring</a></dt><dt id="ientry-idm12470">concat, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm12485">concat_ws, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm33503">concurrency, <a class="indexterm" href="mvcc.html">Concurrency Control</a></dt><dt id="ientry-idm23260">conditional expression, <a class="indexterm" href="functions-conditional.html">Conditional Expressions</a></dt><dt id="ientry-idm28562">configuration</dt><dd><dl><dt>of recovery</dt><dd><dl><dt>general settings, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">Recovery</a></dt><dt>of a standby server, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a></dt></dl></dd><dt>of the server, <a class="indexterm" href="runtime-config.html">Server Configuration</a></dt><dt>of the server</dt><dd><dl><dt>functions, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SET">Configuration Settings Functions</a></dt></dl></dd></dl></dd><dt id="ientry-idm35442">configure, <a class="indexterm" href="install-procedure.html#CONFIGURE">Installation Procedure</a></dt><dt id="ientry-idm36150">configure environment variables, <a class="indexterm" href="install-procedure.html#CONFIGURE-ENVVARS">configure Environment Variables</a></dt><dt id="ientry-idm35546">configure options, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS">configure Options</a></dt><dt id="ientry-idm38516">config_file configuration parameter, <a class="indexterm" href="runtime-config-file-locations.html">File Locations</a></dt><dt id="ientry-idm10366">conjunction, <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm172239">connectby, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5">Functions Provided</a>, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5.8">connectby</a></dt><dt id="ientry-idm61979">connection service file, <a class="indexterm" href="libpq-pgservice.html">The Connection Service File</a></dt><dt id="ientry-idm58139">conninfo, <a class="indexterm" href="libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings</a></dt><dt id="ientry-idm1278">constant, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS">Constants</a></dt><dt id="ientry-idm2599">constraint, <a class="indexterm" href="ddl-constraints.html">Constraints</a></dt><dd><dl><dt>adding, <a class="indexterm" href="ddl-alter.html#DDL-ALTER-ADDING-A-CONSTRAINT">Adding a Constraint</a></dt><dt>check, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">Check Constraints</a></dt><dt>exclusion, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-EXCLUSION">Exclusion Constraints</a></dt><dt>foreign key, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt><dt>name, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">Check Constraints</a></dt><dt>NOT NULL, <a class="indexterm" href="ddl-constraints.html#id-1.5.4.6.6">Not-Null Constraints</a></dt><dt>primary key, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-PRIMARY-KEYS">Primary Keys</a></dt><dt>removing, <a class="indexterm" href="ddl-alter.html#DDL-ALTER-REMOVING-A-CONSTRAINT">Removing a Constraint</a></dt><dt>unique, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS">Unique Constraints</a></dt></dl></dd><dt id="ientry-idm4265">constraint exclusion, <a class="indexterm" href="ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION">Partitioning and Constraint Exclusion</a>, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm41331">constraint_exclusion configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm73180">container type, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dt id="ientry-idm80685">CONTINUE</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#id-1.8.8.8.7.6">CONTINUE</a></dt></dl></dd><dt id="ientry-idm49687">continuous archiving, <a class="indexterm" href="backup.html">Backup and Restore</a></dt><dd><dl><dt>in standby, <a class="indexterm" href="warm-standby.html#CONTINUOUS-ARCHIVING-IN-STANDBY">Continuous Archiving in Standby</a></dt></dl></dd><dt id="ientry-idm76135">control file, <a class="indexterm" href="extend-extensions.html#id-1.8.3.20.11">Extension Files</a></dt><dt id="ientry-idm13937">convert, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm13957">convert_from, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm13975">convert_to, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm689">COPY, <a class="indexterm" href="tutorial-populate.html">Populating a Table With Rows</a>, <a class="indexterm" href="libpq-copy.html">Functions Associated with the COPY Command</a>, <a class="indexterm" href="sql-copy.html">COPY</a></dt><dd><dl><dt>with libpq, <a class="indexterm" href="libpq-copy.html">Functions Associated with the COPY Command</a></dt></dl></dd><dt id="ientry-idm24997">corr, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24995">correlation, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dd><dl><dt>in the query planner, <a class="indexterm" href="planner-stats.html#PLANNER-STATS-EXTENDED">Extended Statistics</a></dt></dl></dd><dt id="ientry-idm11838">cos, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11850">cosd, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11965">cosh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11862">cot, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11874">cotd, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm24721">count, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25010">covariance</dt><dd><dl><dt>population, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt>sample, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm25013">covar_pop, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25029">covar_samp, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm31523">covering index, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a></dt><dt id="ientry-idm41120">cpu_index_tuple_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm41129">cpu_operator_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm41111">cpu_tuple_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm95289">CREATE ACCESS METHOD, <a class="indexterm" href="sql-create-access-method.html">CREATE ACCESS METHOD</a></dt><dt id="ientry-idm95358">CREATE AGGREGATE, <a class="indexterm" href="sql-createaggregate.html">CREATE AGGREGATE</a></dt><dt id="ientry-idm95759">CREATE CAST, <a class="indexterm" href="sql-createcast.html">CREATE CAST</a></dt><dt id="ientry-idm95956">CREATE COLLATION, <a class="indexterm" href="sql-createcollation.html">CREATE COLLATION</a></dt><dt id="ientry-idm96082">CREATE CONVERSION, <a class="indexterm" href="sql-createconversion.html">CREATE CONVERSION</a></dt><dt id="ientry-idm46427">CREATE DATABASE, <a class="indexterm" href="manage-ag-createdb.html">Creating a Database</a>, <a class="indexterm" href="sql-createdatabase.html">CREATE DATABASE</a></dt><dt id="ientry-idm96404">CREATE DOMAIN, <a class="indexterm" href="sql-createdomain.html">CREATE DOMAIN</a></dt><dt id="ientry-idm96527">CREATE EVENT TRIGGER, <a class="indexterm" href="sql-createeventtrigger.html">CREATE EVENT TRIGGER</a></dt><dt id="ientry-idm96613">CREATE EXTENSION, <a class="indexterm" href="sql-createextension.html">CREATE EXTENSION</a></dt><dt id="ientry-idm96721">CREATE FOREIGN DATA WRAPPER, <a class="indexterm" href="sql-createforeigndatawrapper.html">CREATE FOREIGN DATA WRAPPER</a></dt><dt id="ientry-idm96818">CREATE FOREIGN TABLE, <a class="indexterm" href="sql-createforeigntable.html">CREATE FOREIGN TABLE</a></dt><dt id="ientry-idm97048">CREATE FUNCTION, <a class="indexterm" href="sql-createfunction.html">CREATE FUNCTION</a></dt><dt id="ientry-idm97480">CREATE GROUP, <a class="indexterm" href="sql-creategroup.html">CREATE GROUP</a></dt><dt id="ientry-idm97519">CREATE INDEX, <a class="indexterm" href="sql-createindex.html">CREATE INDEX</a></dt><dt id="ientry-idm97993">CREATE LANGUAGE, <a class="indexterm" href="sql-createlanguage.html">CREATE LANGUAGE</a></dt><dt id="ientry-idm98117">CREATE MATERIALIZED VIEW, <a class="indexterm" href="sql-creatematerializedview.html">CREATE MATERIALIZED VIEW</a></dt><dt id="ientry-idm98230">CREATE OPERATOR, <a class="indexterm" href="sql-createoperator.html">CREATE OPERATOR</a></dt><dt id="ientry-idm98389">CREATE OPERATOR CLASS, <a class="indexterm" href="sql-createopclass.html">CREATE OPERATOR CLASS</a></dt><dt id="ientry-idm98552">CREATE OPERATOR FAMILY, <a class="indexterm" href="sql-createopfamily.html">CREATE OPERATOR FAMILY</a></dt><dt id="ientry-idm98611">CREATE POLICY, <a class="indexterm" href="sql-createpolicy.html">CREATE POLICY</a></dt><dt id="ientry-idm99015">CREATE PROCEDURE, <a class="indexterm" href="sql-createprocedure.html">CREATE PROCEDURE</a></dt><dt id="ientry-idm99221">CREATE PUBLICATION, <a class="indexterm" href="sql-createpublication.html">CREATE PUBLICATION</a></dt><dt id="ientry-idm46010">CREATE ROLE, <a class="indexterm" href="database-roles.html">Database Roles</a>, <a class="indexterm" href="sql-createrole.html">CREATE ROLE</a></dt><dt id="ientry-idm99701">CREATE RULE, <a class="indexterm" href="sql-createrule.html">CREATE RULE</a></dt><dt id="ientry-idm99876">CREATE SCHEMA, <a class="indexterm" href="sql-createschema.html">CREATE SCHEMA</a></dt><dt id="ientry-idm99987">CREATE SEQUENCE, <a class="indexterm" href="sql-createsequence.html">CREATE SEQUENCE</a></dt><dt id="ientry-idm100197">CREATE SERVER, <a class="indexterm" href="sql-createserver.html">CREATE SERVER</a></dt><dt id="ientry-idm100289">CREATE STATISTICS, <a class="indexterm" href="sql-createstatistics.html">CREATE STATISTICS</a></dt><dt id="ientry-idm100390">CREATE SUBSCRIPTION, <a class="indexterm" href="sql-createsubscription.html">CREATE SUBSCRIPTION</a></dt><dt id="ientry-idm630">CREATE TABLE, <a class="indexterm" href="tutorial-table.html">Creating a New Table</a>, <a class="indexterm" href="sql-createtable.html">CREATE TABLE</a></dt><dt id="ientry-idm101864">CREATE TABLE AS, <a class="indexterm" href="sql-createtableas.html">CREATE TABLE AS</a></dt><dt id="ientry-idm46606">CREATE TABLESPACE, <a class="indexterm" href="manage-ag-tablespaces.html">Tablespaces</a>, <a class="indexterm" href="sql-createtablespace.html">CREATE TABLESPACE</a></dt><dt id="ientry-idm102173">CREATE TEXT SEARCH CONFIGURATION, <a class="indexterm" href="sql-createtsconfig.html">CREATE TEXT SEARCH CONFIGURATION</a></dt><dt id="ientry-idm102232">CREATE TEXT SEARCH DICTIONARY, <a class="indexterm" href="sql-createtsdictionary.html">CREATE TEXT SEARCH DICTIONARY</a></dt><dt id="ientry-idm102295">CREATE TEXT SEARCH PARSER, <a class="indexterm" href="sql-createtsparser.html">CREATE TEXT SEARCH PARSER</a></dt><dt id="ientry-idm102368">CREATE TEXT SEARCH TEMPLATE, <a class="indexterm" href="sql-createtstemplate.html">CREATE TEXT SEARCH TEMPLATE</a></dt><dt id="ientry-idm102424">CREATE TRANSFORM, <a class="indexterm" href="sql-createtransform.html">CREATE TRANSFORM</a></dt><dt id="ientry-idm102524">CREATE TRIGGER, <a class="indexterm" href="sql-createtrigger.html">CREATE TRIGGER</a></dt><dt id="ientry-idm102928">CREATE TYPE, <a class="indexterm" href="sql-createtype.html">CREATE TYPE</a></dt><dt id="ientry-idm103403">CREATE USER, <a class="indexterm" href="sql-createuser.html">CREATE USER</a></dt><dt id="ientry-idm103448">CREATE USER MAPPING, <a class="indexterm" href="sql-createusermapping.html">CREATE USER MAPPING</a></dt><dt id="ientry-idm103520">CREATE VIEW, <a class="indexterm" href="sql-createview.html">CREATE VIEW</a></dt><dt id="ientry-idm432">createdb, <a class="indexterm" href="tutorial-createdb.html">Creating a Database</a>, <a class="indexterm" href="manage-ag-createdb.html">Creating a Database</a>, <a class="indexterm" href="app-createdb.html">createdb</a></dt><dt id="ientry-idm46025">createuser, <a class="indexterm" href="database-roles.html">Database Roles</a>, <a class="indexterm" href="app-createuser.html">createuser</a></dt><dt id="ientry-idm138351">CREATE_REPLICATION_SLOT, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm36011">cross compilation, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-BUILD-PROCESS">Build Process Details</a></dt><dt id="ientry-idm4629">cross join, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt id="ientry-idm172277">crosstab, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5.5">crosstab(text)</a>, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5.6">crosstabN(text)</a>, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5.7">crosstab(text, text)</a></dt><dt id="ientry-idm168587">crypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.8.7">crypt()</a></dt><dt id="ientry-idm10168">cstring, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm122526">CSV (Comma-Separated Values) format</dt><dd><dl><dt>in psql, <a class="indexterm" href="app-psql.html#APP-PSQL-META-COMMANDS">Meta-Commands</a></dt></dl></dd><dt id="ientry-idm2892">ctid, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm78975">CTID, <a class="indexterm" href="rules-views.html#id-1.8.6.7.6">View Rules in Non-SELECT Statements</a></dt><dt id="ientry-idm5146">CUBE, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a></dt><dt id="ientry-idm164310">cube (extension), <a class="indexterm" href="cube.html">cube</a></dt><dt id="ientry-idm25473">cume_dist, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dd><dl><dt>hypothetical, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm26242">current_catalog, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26247">current_database, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm17182">current_date, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm26384">current_logfiles</dt><dd><dl><dt>and the log_destination configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt>and the pg_current_logfile function, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt></dl></dd><dt id="ientry-idm26257">current_query, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26265">current_role, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26274">current_schema, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26288">current_schemas, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28581">current_setting, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SET">Configuration Settings Functions</a></dt><dt id="ientry-idm17194">current_time, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17217">current_timestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm26304">current_user, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm23207">currval, <a class="indexterm" href="functions-sequence.html">Sequence Manipulation Functions</a></dt><dt id="ientry-idm81020">cursor, <a class="indexterm" href="plpgsql-cursors.html">Cursors</a>, <a class="indexterm" href="sql-close.html">CLOSE</a>, <a class="indexterm" href="sql-declare.html">DECLARE</a>, <a class="indexterm" href="sql-explain.html">EXPLAIN</a>, <a class="indexterm" href="sql-fetch.html">FETCH</a>, <a class="indexterm" href="sql-move.html">MOVE</a></dt><dd><dl><dt>CLOSE, <a class="indexterm" href="sql-close.html">CLOSE</a></dt><dt>DECLARE, <a class="indexterm" href="sql-declare.html">DECLARE</a></dt><dt>FETCH, <a class="indexterm" href="sql-fetch.html">FETCH</a></dt><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-cursors.html">Cursors</a></dt><dt>MOVE, <a class="indexterm" href="sql-move.html">MOVE</a></dt><dt>showing the query plan, <a class="indexterm" href="sql-explain.html">EXPLAIN</a></dt></dl></dd><dt id="ientry-idm41355">cursor_tuple_fraction configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm142683">custom scan provider, <a class="indexterm" href="custom-scan.html">Writing a Custom Scan Provider</a></dt><dd><dl><dt>handler for, <a class="indexterm" href="custom-scan.html">Writing a Custom Scan Provider</a></dt></dl></dd><dt id="ientry-idm36465">Cygwin, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-CYGWIN">Cygwin</a></dt><dd><dl><dt>installation on, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-CYGWIN">Cygwin</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-D"><h3>D</h3><dl><dt id="ientry-idm36962">data area (see <a href="#ientry-idm620">database cluster</a>)</dt><dt id="ientry-idm50077">data partitioning, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm1501">data type, <a class="indexterm" href="datatype.html">Data Types</a>, <a class="indexterm" href="datatype-numeric.html">Numeric Types</a>, <a class="indexterm" href="datatype-enum.html">Enumerated Types</a>, <a class="indexterm" href="domains.html">Domain Types</a>, <a class="indexterm" href="typeconv.html">Type Conversion</a>, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a>, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a>, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a>, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a>, <a class="indexterm" href="xfunc-c.html#XFUNC-C-BASETYPE">Base Types in C-Language Functions</a>, <a class="indexterm" href="xtypes.html">User-Defined Types</a></dt><dd><dl><dt>base, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dt>category, <a class="indexterm" href="typeconv-overview.html">Overview</a></dt><dt>composite, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dt>constant, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC">Constants of Other Types</a></dt><dt>container, <a class="indexterm" href="extend-type-system.html">The PostgreSQL Type System</a></dt><dt>conversion, <a class="indexterm" href="typeconv.html">Type Conversion</a></dt><dt>domain, <a class="indexterm" href="domains.html">Domain Types</a></dt><dt>enumerated (enum), <a class="indexterm" href="datatype-enum.html">Enumerated Types</a></dt><dt>internal organization, <a class="indexterm" href="xfunc-c.html#XFUNC-C-BASETYPE">Base Types in C-Language Functions</a></dt><dt>numeric, <a class="indexterm" href="datatype-numeric.html">Numeric Types</a></dt><dt>polymorphic, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a></dt><dt>type cast, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">Type Casts</a></dt><dt>user-defined, <a class="indexterm" href="xtypes.html">User-Defined Types</a></dt></dl></dd><dt id="ientry-idm429">database, <a class="indexterm" href="tutorial-createdb.html">Creating a Database</a>, <a class="indexterm" href="managing-databases.html">Managing Databases</a></dt><dd><dl><dt>creating, <a class="indexterm" href="tutorial-createdb.html">Creating a Database</a></dt><dt>privilege to create, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt></dl></dd><dt id="ientry-idm50997">database activity, <a class="indexterm" href="monitoring.html">Monitoring Database Activity</a></dt><dd><dl><dt>monitoring, <a class="indexterm" href="monitoring.html">Monitoring Database Activity</a></dt></dl></dd><dt id="ientry-idm620">database cluster, <a class="indexterm" href="tutorial-concepts.html">Concepts</a>, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a></dt><dt id="ientry-idm44126">data_checksums configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm38507">data_directory configuration parameter, <a class="indexterm" href="runtime-config-file-locations.html">File Locations</a></dt><dt id="ientry-idm44136">data_directory_mode configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44074">data_sync_retry configuration parameter, <a class="indexterm" href="runtime-config-error-handling.html">Error Handling</a></dt><dt id="ientry-idm6919">date, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.5">Dates</a></dt><dd><dl><dt>constants, <a class="indexterm" href="datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-VALUES">Special Values</a></dt><dt>current, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT">Current Date/Time</a></dt><dt>output format, <a class="indexterm" href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT">Date/Time Output</a></dt><dd><dl><dt>(see also <a href="#ientry-idm15924">formatting</a>)</dt></dl></dd></dl></dd><dt id="ientry-idm43496">DateStyle configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm18080">date_bin, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-BIN">date_bin</a></dt><dt id="ientry-idm17253">date_part, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a>, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT">EXTRACT, date_part</a></dt><dt id="ientry-idm17281">date_trunc, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a>, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC">date_trunc</a></dt><dt id="ientry-idm164735">dblink, <a class="indexterm" href="dblink.html">dblink</a>, <a class="indexterm" href="contrib-dblink-function.html">dblink</a></dt><dt id="ientry-idm165480">dblink_build_sql_delete, <a class="indexterm" href="contrib-dblink-build-sql-delete.html">dblink_build_sql_delete</a></dt><dt id="ientry-idm165419">dblink_build_sql_insert, <a class="indexterm" href="contrib-dblink-build-sql-insert.html">dblink_build_sql_insert</a></dt><dt id="ientry-idm165536">dblink_build_sql_update, <a class="indexterm" href="contrib-dblink-build-sql-update.html">dblink_build_sql_update</a></dt><dt id="ientry-idm165353">dblink_cancel_query, <a class="indexterm" href="contrib-dblink-cancel-query.html">dblink_cancel_query</a></dt><dt id="ientry-idm165092">dblink_close, <a class="indexterm" href="contrib-dblink-close.html">dblink_close</a></dt><dt id="ientry-idm164743">dblink_connect, <a class="indexterm" href="contrib-dblink-connect.html">dblink_connect</a></dt><dt id="ientry-idm164800">dblink_connect_u, <a class="indexterm" href="contrib-dblink-connect-u.html">dblink_connect_u</a></dt><dt id="ientry-idm164827">dblink_disconnect, <a class="indexterm" href="contrib-dblink-disconnect.html">dblink_disconnect</a></dt><dt id="ientry-idm165163">dblink_error_message, <a class="indexterm" href="contrib-dblink-error-message.html">dblink_error_message</a></dt><dt id="ientry-idm164926">dblink_exec, <a class="indexterm" href="contrib-dblink-exec.html">dblink_exec</a></dt><dt id="ientry-idm165040">dblink_fetch, <a class="indexterm" href="contrib-dblink-fetch.html">dblink_fetch</a></dt><dt id="ientry-idm165141">dblink_get_connections, <a class="indexterm" href="contrib-dblink-get-connections.html">dblink_get_connections</a></dt><dt id="ientry-idm165269">dblink_get_notify, <a class="indexterm" href="contrib-dblink-get-notify.html">dblink_get_notify</a></dt><dt id="ientry-idm165384">dblink_get_pkey, <a class="indexterm" href="contrib-dblink-get-pkey.html">dblink_get_pkey</a></dt><dt id="ientry-idm165303">dblink_get_result, <a class="indexterm" href="contrib-dblink-get-result.html">dblink_get_result</a></dt><dt id="ientry-idm165239">dblink_is_busy, <a class="indexterm" href="contrib-dblink-is-busy.html">dblink_is_busy</a></dt><dt id="ientry-idm164977">dblink_open, <a class="indexterm" href="contrib-dblink-open.html">dblink_open</a></dt><dt id="ientry-idm165200">dblink_send_query, <a class="indexterm" href="contrib-dblink-send-query.html">dblink_send_query</a></dt><dt id="ientry-idm38842">db_user_namespace configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt><dt id="ientry-idm34224">deadlock, <a class="indexterm" href="explicit-locking.html#LOCKING-DEADLOCKS">Deadlocks</a></dt><dd><dl><dt>timeout during, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt></dl></dd><dt id="ientry-idm43822">deadlock_timeout configuration parameter, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt><dt id="ientry-idm103819">DEALLOCATE, <a class="indexterm" href="sql-deallocate.html">DEALLOCATE</a></dt><dt id="ientry-idm168865">dearmor, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.16">armor(), dearmor()</a></dt><dt id="ientry-idm44148">debug_assertions configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44568">debug_deadlocks configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44386">debug_discard_caches configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm41998">debug_pretty_print configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41974">debug_print_parse configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41986">debug_print_plan configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41980">debug_print_rewritten configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm6264">decimal (see <a href="#ientry-idm1485">numeric</a>)</dt><dt id="ientry-idm103870">DECLARE, <a class="indexterm" href="sql-declare.html">DECLARE</a></dt><dt id="ientry-idm14015">decode, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm83049">decode_bytea</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm168989">decrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.10">Raw Encryption Functions</a></dt><dt id="ientry-idm168993">decrypt_iv, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.10">Raw Encryption Functions</a></dt><dt id="ientry-idm97737">deduplicate_items storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt><dt id="ientry-idm2518">default value, <a class="indexterm" href="ddl-default.html">Default Values</a></dt><dd><dl><dt>changing, <a class="indexterm" href="ddl-alter.html#id-1.5.4.8.9">Changing a Column's Default Value</a></dt></dl></dd><dt id="ientry-idm175575">default-roles, <a class="indexterm" href="default-roles.html">Default Roles Renamed to Predefined Roles</a></dt><dt id="ientry-idm41316">default_statistics_target configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm43074">default_tablespace configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43062">default_table_access_method configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43665">default_text_search_config configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm43097">default_toast_compression configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43191">default_transaction_deferrable configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43156">default_transaction_isolation configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43176">default_transaction_read_only configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43188">deferrable transaction, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dd><dl><dt>setting, <a class="indexterm" href="sql-set-transaction.html">SET TRANSACTION</a></dt><dt>setting default, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></dd><dt id="ientry-idm166527">defined, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm11236">degrees, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm18278">delay, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">Delaying Execution</a></dt><dt id="ientry-idm910">DELETE, <a class="indexterm" href="tutorial-delete.html">Deletions</a>, <a class="indexterm" href="dml-delete.html">Deleting Data</a>, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a>, <a class="indexterm" href="sql-delete.html">DELETE</a></dt><dd><dl><dt>RETURNING, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a></dt></dl></dd><dt id="ientry-idm166542">delete, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm4471">deleting, <a class="indexterm" href="dml-delete.html">Deleting Data</a></dt><dt id="ientry-idm25444">dense_rank, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dd><dl><dt>hypothetical, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm18985">diagonal, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm18998">diameter, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm165600">dict_int, <a class="indexterm" href="dict-int.html">dict_int</a></dt><dt id="ientry-idm165645">dict_xsyn, <a class="indexterm" href="dict-xsyn.html">dict_xsyn</a></dt><dt id="ientry-idm165999">difference, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.6">Soundex</a></dt><dt id="ientry-idm168487">digest, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.7.2">digest()</a></dt><dt id="ientry-idm33542">dirty read, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a></dt><dt id="ientry-idm104235">DISCARD, <a class="indexterm" href="sql-discard.html">DISCARD</a></dt><dt id="ientry-idm10368">disjunction, <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm56603">disk drive, <a class="indexterm" href="wal-internals.html">WAL Internals</a></dt><dt id="ientry-idm48990">disk space, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-SPACE-RECOVERY">Recovering Disk Space</a></dt><dt id="ientry-idm56204">disk usage, <a class="indexterm" href="disk-usage.html">Determining Disk Usage</a></dt><dt id="ientry-idm737">DISTINCT, <a class="indexterm" href="tutorial-select.html">Querying a Table</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a>, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a></dt><dd><dl><dt>GROUP BY DISTINCT, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a></dt><dt>SELECT DISTINCT, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a></dt></dl></dd><dt id="ientry-idm11248">div, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm166046">dmetaphone, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.9">Double Metaphone</a></dt><dt id="ientry-idm166048">dmetaphone_alt, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.9">Double Metaphone</a></dt><dt id="ientry-idm104290">DO, <a class="indexterm" href="sql-do.html">DO</a></dt><dt id="ientry-idm31803">document, <a class="indexterm" href="textsearch-intro.html#TEXTSEARCH-DOCUMENT">What Is a Document?</a></dt><dd><dl><dt>text search, <a class="indexterm" href="textsearch-intro.html#TEXTSEARCH-DOCUMENT">What Is a Document?</a></dt></dl></dd><dt id="ientry-idm1419">dollar quoting, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING">Dollar-Quoted String Constants</a></dt><dt id="ientry-idm9845">domain, <a class="indexterm" href="domains.html">Domain Types</a></dt><dt id="ientry-idm6371">double precision, <a class="indexterm" href="datatype-numeric.html#DATATYPE-FLOAT">Floating-Point Types</a></dt><dt id="ientry-idm104354">DROP ACCESS METHOD, <a class="indexterm" href="sql-drop-access-method.html">DROP ACCESS METHOD</a></dt><dt id="ientry-idm104410">DROP AGGREGATE, <a class="indexterm" href="sql-dropaggregate.html">DROP AGGREGATE</a></dt><dt id="ientry-idm104510">DROP CAST, <a class="indexterm" href="sql-dropcast.html">DROP CAST</a></dt><dt id="ientry-idm104569">DROP COLLATION, <a class="indexterm" href="sql-dropcollation.html">DROP COLLATION</a></dt><dt id="ientry-idm104629">DROP CONVERSION, <a class="indexterm" href="sql-dropconversion.html">DROP CONVERSION</a></dt><dt id="ientry-idm46577">DROP DATABASE, <a class="indexterm" href="manage-ag-dropdb.html">Destroying a Database</a>, <a class="indexterm" href="sql-dropdatabase.html">DROP DATABASE</a></dt><dt id="ientry-idm104745">DROP DOMAIN, <a class="indexterm" href="sql-dropdomain.html">DROP DOMAIN</a></dt><dt id="ientry-idm104803">DROP EVENT TRIGGER, <a class="indexterm" href="sql-dropeventtrigger.html">DROP EVENT TRIGGER</a></dt><dt id="ientry-idm104860">DROP EXTENSION, <a class="indexterm" href="sql-dropextension.html">DROP EXTENSION</a></dt><dt id="ientry-idm104926">DROP FOREIGN DATA WRAPPER, <a class="indexterm" href="sql-dropforeigndatawrapper.html">DROP FOREIGN DATA WRAPPER</a></dt><dt id="ientry-idm104985">DROP FOREIGN TABLE, <a class="indexterm" href="sql-dropforeigntable.html">DROP FOREIGN TABLE</a></dt><dt id="ientry-idm105044">DROP FUNCTION, <a class="indexterm" href="sql-dropfunction.html">DROP FUNCTION</a></dt><dt id="ientry-idm105146">DROP GROUP, <a class="indexterm" href="sql-dropgroup.html">DROP GROUP</a></dt><dt id="ientry-idm105174">DROP INDEX, <a class="indexterm" href="sql-dropindex.html">DROP INDEX</a></dt><dt id="ientry-idm105245">DROP LANGUAGE, <a class="indexterm" href="sql-droplanguage.html">DROP LANGUAGE</a></dt><dt id="ientry-idm105310">DROP MATERIALIZED VIEW, <a class="indexterm" href="sql-dropmaterializedview.html">DROP MATERIALIZED VIEW</a></dt><dt id="ientry-idm105370">DROP OPERATOR, <a class="indexterm" href="sql-dropoperator.html">DROP OPERATOR</a></dt><dt id="ientry-idm105447">DROP OPERATOR CLASS, <a class="indexterm" href="sql-dropopclass.html">DROP OPERATOR CLASS</a></dt><dt id="ientry-idm105523">DROP OPERATOR FAMILY, <a class="indexterm" href="sql-dropopfamily.html">DROP OPERATOR FAMILY</a></dt><dt id="ientry-idm105596">DROP OWNED, <a class="indexterm" href="sql-drop-owned.html">DROP OWNED</a></dt><dt id="ientry-idm105658">DROP POLICY, <a class="indexterm" href="sql-droppolicy.html">DROP POLICY</a></dt><dt id="ientry-idm105721">DROP PROCEDURE, <a class="indexterm" href="sql-dropprocedure.html">DROP PROCEDURE</a></dt><dt id="ientry-idm105840">DROP PUBLICATION, <a class="indexterm" href="sql-droppublication.html">DROP PUBLICATION</a></dt><dt id="ientry-idm46012">DROP ROLE, <a class="indexterm" href="database-roles.html">Database Roles</a>, <a class="indexterm" href="sql-droprole.html">DROP ROLE</a></dt><dt id="ientry-idm105956">DROP ROUTINE, <a class="indexterm" href="sql-droproutine.html">DROP ROUTINE</a></dt><dt id="ientry-idm106030">DROP RULE, <a class="indexterm" href="sql-droprule.html">DROP RULE</a></dt><dt id="ientry-idm106094">DROP SCHEMA, <a class="indexterm" href="sql-dropschema.html">DROP SCHEMA</a></dt><dt id="ientry-idm106158">DROP SEQUENCE, <a class="indexterm" href="sql-dropsequence.html">DROP SEQUENCE</a></dt><dt id="ientry-idm106218">DROP SERVER, <a class="indexterm" href="sql-dropserver.html">DROP SERVER</a></dt><dt id="ientry-idm106277">DROP STATISTICS, <a class="indexterm" href="sql-dropstatistics.html">DROP STATISTICS</a></dt><dt id="ientry-idm106329">DROP SUBSCRIPTION, <a class="indexterm" href="sql-dropsubscription.html">DROP SUBSCRIPTION</a></dt><dt id="ientry-idm668">DROP TABLE, <a class="indexterm" href="tutorial-table.html">Creating a New Table</a>, <a class="indexterm" href="sql-droptable.html">DROP TABLE</a></dt><dt id="ientry-idm106459">DROP TABLESPACE, <a class="indexterm" href="sql-droptablespace.html">DROP TABLESPACE</a></dt><dt id="ientry-idm106513">DROP TEXT SEARCH CONFIGURATION, <a class="indexterm" href="sql-droptsconfig.html">DROP TEXT SEARCH CONFIGURATION</a></dt><dt id="ientry-idm106572">DROP TEXT SEARCH DICTIONARY, <a class="indexterm" href="sql-droptsdictionary.html">DROP TEXT SEARCH DICTIONARY</a></dt><dt id="ientry-idm106630">DROP TEXT SEARCH PARSER, <a class="indexterm" href="sql-droptsparser.html">DROP TEXT SEARCH PARSER</a></dt><dt id="ientry-idm106688">DROP TEXT SEARCH TEMPLATE, <a class="indexterm" href="sql-droptstemplate.html">DROP TEXT SEARCH TEMPLATE</a></dt><dt id="ientry-idm106746">DROP TRANSFORM, <a class="indexterm" href="sql-droptransform.html">DROP TRANSFORM</a></dt><dt id="ientry-idm106811">DROP TRIGGER, <a class="indexterm" href="sql-droptrigger.html">DROP TRIGGER</a></dt><dt id="ientry-idm106876">DROP TYPE, <a class="indexterm" href="sql-droptype.html">DROP TYPE</a></dt><dt id="ientry-idm106936">DROP USER, <a class="indexterm" href="sql-dropuser.html">DROP USER</a></dt><dt id="ientry-idm106965">DROP USER MAPPING, <a class="indexterm" href="sql-dropusermapping.html">DROP USER MAPPING</a></dt><dt id="ientry-idm107026">DROP VIEW, <a class="indexterm" href="sql-dropview.html">DROP VIEW</a></dt><dt id="ientry-idm46587">dropdb, <a class="indexterm" href="manage-ag-dropdb.html">Destroying a Database</a>, <a class="indexterm" href="app-dropdb.html">dropdb</a></dt><dt id="ientry-idm46027">dropuser, <a class="indexterm" href="database-roles.html">Database Roles</a>, <a class="indexterm" href="app-dropuser.html">dropuser</a></dt><dt id="ientry-idm138658">DROP_REPLICATION_SLOT, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm8657">DTD, <a class="indexterm" href="datatype-xml.html#id-1.5.7.21.6">Creating XML Values</a></dt><dt id="ientry-idm36130">DTrace, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-DEVEL">Developer Options</a>, <a class="indexterm" href="dynamic-trace.html">Dynamic Tracing</a></dt><dt id="ientry-idm739">duplicate, <a class="indexterm" href="tutorial-select.html">Querying a Table</a></dt><dt id="ientry-idm5314">duplicates, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a></dt><dt id="ientry-idm43779">dynamic loading, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER">Other Defaults</a>, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm74044">dynamic_library_path, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm43776">dynamic_library_path configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER">Other Defaults</a></dt><dt id="ientry-idm39332">dynamic_shared_memory_type configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt></dl></div><div class="indexdiv" id="indexdiv-E"><h3>E</h3><dl><dt id="ientry-idm166495">each, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm165748">earth, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm165702">earthdistance, <a class="indexterm" href="earthdistance.html">earthdistance</a></dt><dt id="ientry-idm165812">earth_box, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm165802">earth_distance, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm62863">ECPG, <a class="indexterm" href="ecpg.html">ECPG — Embedded SQL in C</a></dt><dt id="ientry-idm114604">ecpg, <a class="indexterm" href="app-ecpg.html">ecpg</a></dt><dt id="ientry-idm41179">effective_cache_size configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm39545">effective_io_concurrency configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm82437">elog, <a class="indexterm" href="error-message-reporting.html">Reporting Errors Within the Server</a></dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt><dt>in PL/Python, <a class="indexterm" href="plpython-util.html">Utility Functions</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-dbaccess.html">Database Access from PL/Tcl</a></dt></dl></dd><dt id="ientry-idm62858">embedded SQL, <a class="indexterm" href="ecpg.html">ECPG — Embedded SQL in C</a></dt><dd><dl><dt>in C, <a class="indexterm" href="ecpg.html">ECPG — Embedded SQL in C</a></dt></dl></dd><dt id="ientry-idm69481">enabled role, <a class="indexterm" href="infoschema-enabled-roles.html">enabled_roles</a></dt><dt id="ientry-idm40863">enable_async_append configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40875">enable_bitmapscan configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40885">enable_gathermerge configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40895">enable_hashagg configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40905">enable_hashjoin configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40915">enable_incremental_sort configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40937">enable_indexonlyscan configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40927">enable_indexscan configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40948">enable_material configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40958">enable_memoize configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40968">enable_mergejoin configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40978">enable_nestloop configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40988">enable_parallel_append configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm40998">enable_parallel_hash configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41029">enable_partitionwise_aggregate configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41019">enable_partitionwise_join configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41008">enable_partition_pruning configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41042">enable_seqscan configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41052">enable_sort configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41062">enable_tidscan configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm13993">encode, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm83099">encode_array_constructor</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm83071">encode_array_literal</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm83060">encode_bytea</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm83089">encode_typed_literal</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm168987">encrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.10">Raw Encryption Functions</a></dt><dt id="ientry-idm37946">encryption, <a class="indexterm" href="encryption-options.html">Encryption Options</a>, <a class="indexterm" href="pgcrypto.html">pgcrypto</a></dt><dd><dl><dt>for specific columns, <a class="indexterm" href="pgcrypto.html">pgcrypto</a></dt></dl></dd><dt id="ientry-idm168991">encrypt_iv, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.10">Raw Encryption Functions</a></dt><dt id="ientry-idm107084">END, <a class="indexterm" href="sql-end.html">END</a></dt><dt id="ientry-idm7941">enumerated types, <a class="indexterm" href="datatype-enum.html">Enumerated Types</a></dt><dt id="ientry-idm18315">enum_first, <a class="indexterm" href="functions-enum.html">Enum Support Functions</a></dt><dt id="ientry-idm18327">enum_last, <a class="indexterm" href="functions-enum.html">Enum Support Functions</a></dt><dt id="ientry-idm18339">enum_range, <a class="indexterm" href="functions-enum.html">Enum Support Functions</a></dt><dt id="ientry-idm61676">environment variable, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm86027">ephemeral named relation</dt><dd><dl><dt>registering with SPI, <a class="indexterm" href="spi-spi-register-relation.html">SPI_register_relation</a>, <a class="indexterm" href="spi-spi-register-trigger-data.html">SPI_register_trigger_data</a></dt><dt>unregistering from SPI, <a class="indexterm" href="spi-spi-unregister-relation.html">SPI_unregister_relation</a></dt></dl></dd><dt id="ientry-idm140947">ereport, <a class="indexterm" href="error-message-reporting.html">Reporting Errors Within the Server</a></dt><dt id="ientry-idm59530">error codes, <a class="indexterm" href="errcodes-appendix.html">PostgreSQL Error Codes</a></dt><dd><dl><dt>libpq, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt>list of, <a class="indexterm" href="errcodes-appendix.html">PostgreSQL Error Codes</a></dt></dl></dd><dt id="ientry-idm58977">error message, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm14046">escape format, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm1306">escape string syntax, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE">String Constants with C-Style Escapes</a></dt><dt id="ientry-idm43939">escape_string_warning configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm59926">escaping strings, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt></dl></dd><dt id="ientry-idm38251">event log, <a class="indexterm" href="event-log-registration.html">Registering Event Log on Windows</a></dt><dd><dl><dt>event log, <a class="indexterm" href="event-log-registration.html">Registering Event Log on Windows</a></dt></dl></dd><dt id="ientry-idm77238">event trigger, <a class="indexterm" href="event-triggers.html">Event Triggers</a>, <a class="indexterm" href="event-trigger-interface.html">Writing Event Trigger Functions in C</a></dt><dd><dl><dt>in C, <a class="indexterm" href="event-trigger-interface.html">Writing Event Trigger Functions in C</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-event-trigger.html">Event Trigger Functions in PL/Tcl</a></dt></dl></dd><dt id="ientry-idm41716">event_source configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm10154">event_trigger, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm24739">every, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm5351">EXCEPT, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm80835">exceptions</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING">Trapping Errors</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-error-handling.html">Error Handling in PL/Tcl</a></dt></dl></dd><dt id="ientry-idm2829">exclusion constraint, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-EXCLUSION">Exclusion Constraints</a></dt><dt id="ientry-idm107147">EXECUTE, <a class="indexterm" href="sql-execute.html">EXECUTE</a></dt><dt id="ientry-idm166513">exist, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm25728">EXISTS, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a></dt><dt id="ientry-idm80653">EXIT</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#id-1.8.8.8.7.5">EXIT</a></dt></dl></dd><dt id="ientry-idm44052">exit_on_error configuration parameter, <a class="indexterm" href="runtime-config-error-handling.html">Error Handling</a></dt><dt id="ientry-idm11265">exp, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm34381">EXPLAIN, <a class="indexterm" href="using-explain.html">Using EXPLAIN</a>, <a class="indexterm" href="sql-explain.html">EXPLAIN</a></dt><dt id="ientry-idm1742">expression, <a class="indexterm" href="sql-expressions.html">Value Expressions</a></dt><dd><dl><dt>order of evaluation, <a class="indexterm" href="sql-expressions.html#SYNTAX-EXPRESS-EVAL">Expression Evaluation Rules</a></dt><dt>syntax, <a class="indexterm" href="sql-expressions.html">Value Expressions</a></dt></dl></dd><dt id="ientry-idm73127">extending SQL, <a class="indexterm" href="extend.html">Extending SQL</a></dt><dt id="ientry-idm76086">extension, <a class="indexterm" href="extend-extensions.html">Packaging Related Objects into an Extension</a></dt><dd><dl><dt>externally maintained, <a class="indexterm" href="external-extensions.html">Extensions</a></dt></dl></dd><dt id="ientry-idm38548">external_pid_file configuration parameter, <a class="indexterm" href="runtime-config-file-locations.html">File Locations</a></dt><dt id="ientry-idm17320">extract, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a>, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT">EXTRACT, date_part</a></dt><dt id="ientry-idm43582">extra_float_digits configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt></dl></div><div class="indexdiv" id="indexdiv-F"><h3>F</h3><dl><dt id="ientry-idm11282">factorial, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm50069">failover, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm7858">false, <a class="indexterm" href="datatype-boolean.html">Boolean Type</a></dt><dt id="ientry-idm19607">family, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm60702">fast path, <a class="indexterm" href="libpq-fastpath.html">The Fast-Path Interface</a></dt><dt id="ientry-idm97777">fastupdate storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt><dt id="ientry-idm10160">fdw_handler, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm107410">FETCH, <a class="indexterm" href="sql-fetch.html">FETCH</a></dt><dt id="ientry-idm9581">field</dt><dd><dl><dt>computed, <a class="indexterm" href="rowtypes.html#ROWTYPES-USAGE">Using Composite Types in Queries</a></dt></dl></dd><dt id="ientry-idm1843">field selection, <a class="indexterm" href="sql-expressions.html#FIELD-SELECTION">Field Selection</a></dt><dt id="ientry-idm37061">file system mount points, <a class="indexterm" href="creating-cluster.html#CREATING-CLUSTER-MOUNT-POINTS">Use of Secondary File Systems</a></dt><dt id="ientry-idm165852">file_fdw, <a class="indexterm" href="file-fdw.html">file_fdw</a></dt><dt id="ientry-idm97715">fillfactor storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a>, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm1921">FILTER, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a></dt><dt id="ientry-idm25652">first_value, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm35392">flex, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm6373">float4 (see <a href="#ientry-idm6369">real</a>)</dt><dt id="ientry-idm6376">float8 (see <a href="#ientry-idm6371">double precision</a>)</dt><dt id="ientry-idm6379">floating point, <a class="indexterm" href="datatype-numeric.html#DATATYPE-FLOAT">Floating-Point Types</a></dt><dt id="ientry-idm43579">floating-point</dt><dd><dl><dt>display, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt></dl></dd><dt id="ientry-idm11294">floor, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm44405">force_parallel_mode configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm4309">foreign data, <a class="indexterm" href="ddl-foreign-data.html">Foreign Data</a></dt><dt id="ientry-idm141568">foreign data wrapper, <a class="indexterm" href="fdwhandler.html">Writing a Foreign Data Wrapper</a></dt><dd><dl><dt>handler for, <a class="indexterm" href="fdwhandler.html">Writing a Foreign Data Wrapper</a></dt></dl></dd><dt id="ientry-idm947">foreign key, <a class="indexterm" href="tutorial-fk.html">Foreign Keys</a>, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt><dd><dl><dt>self-referential, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt></dl></dd><dt id="ientry-idm4311">foreign table, <a class="indexterm" href="ddl-foreign-data.html">Foreign Data</a></dt><dt id="ientry-idm12502">format, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-string.html#FUNCTIONS-STRING-FORMAT">format</a></dt><dd><dl><dt>use in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">Executing Dynamic Commands</a></dt></dl></dd><dt id="ientry-idm15924">formatting, <a class="indexterm" href="functions-formatting.html">Data Type Formatting Functions</a></dt><dt id="ientry-idm27173">format_type, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm147697">Free Space Map, <a class="indexterm" href="storage-fsm.html">Free Space Map</a></dt><dt id="ientry-idm37157">FreeBSD</dt><dd><dl><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt>start script, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm41365">from_collapse_limit configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm147699">FSM (see <a href="#ientry-idm147697">Free Space Map</a>)</dt><dt id="ientry-idm168022">fsm_page_contents, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.4">General Functions</a></dt><dt id="ientry-idm39720">fsync configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm8515">full text search, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a>, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a>, <a class="indexterm" href="textsearch.html">Full Text Search</a></dt><dd><dl><dt>data types, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a></dt><dt>functions and operators, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a></dt></dl></dd><dt id="ientry-idm39879">full_page_writes configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm1887">function, <a class="indexterm" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS">Table Functions</a>, <a class="indexterm" href="functions.html">Functions and Operators</a>, <a class="indexterm" href="functions-statistics.html">Statistics Information Functions</a>, <a class="indexterm" href="typeconv-func.html">Functions</a>, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a>, <a class="indexterm" href="xfunc.html">User-Defined Functions</a>, <a class="indexterm" href="xfunc-sql.html">Query Language (SQL) Functions</a>, <a class="indexterm" href="xfunc-internal.html">Internal Functions</a>, <a class="indexterm" href="xfunc-c.html">C-Language Functions</a></dt><dd><dl><dt>default values for arguments, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-PARAMETER-DEFAULTS">SQL Functions with Default Values for Arguments</a></dt><dt>in the FROM clause, <a class="indexterm" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS">Table Functions</a></dt><dt>internal, <a class="indexterm" href="xfunc-internal.html">Internal Functions</a></dt><dt>invocation, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-FUNCTION-CALLS">Function Calls</a></dt><dt>mixed notation, <a class="indexterm" href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-MIXED">Using Mixed Notation</a></dt><dt>named argument, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS">Arguments for SQL Functions</a></dt><dt>named notation, <a class="indexterm" href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED">Using Named Notation</a></dt><dt>output parameter, <a class="indexterm" href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS">SQL Functions with Output Parameters</a></dt><dt>polymorphic, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a></dt><dt>positional notation, <a class="indexterm" href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-POSITIONAL">Using Positional Notation</a></dt><dt>RETURNS TABLE, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-TABLE">SQL Functions Returning TABLE</a></dt><dt>statistics, <a class="indexterm" href="functions-statistics.html">Statistics Information Functions</a></dt><dt>type resolution in an invocation, <a class="indexterm" href="typeconv-func.html">Functions</a></dt><dt>user-defined, <a class="indexterm" href="xfunc.html">User-Defined Functions</a>, <a class="indexterm" href="xfunc-sql.html">Query Language (SQL) Functions</a>, <a class="indexterm" href="xfunc-c.html">C-Language Functions</a></dt><dd><dl><dt>in C, <a class="indexterm" href="xfunc-c.html">C-Language Functions</a></dt><dt>in SQL, <a class="indexterm" href="xfunc-sql.html">Query Language (SQL) Functions</a></dt></dl></dd><dt>variadic, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS">SQL Functions with Variable Numbers of Arguments</a></dt><dt>with SETOF, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-SET">SQL Functions Returning Sets</a></dt></dl></dd><dt id="ientry-idm5103">functional dependency, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUP">The GROUP BY and HAVING Clauses</a></dt><dt id="ientry-idm165979">fuzzystrmatch, <a class="indexterm" href="fuzzystrmatch.html">fuzzystrmatch</a></dt></dl></div><div class="indexdiv" id="indexdiv-G"><h3>G</h3><dl><dt id="ientry-idm11313">gcd, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm165765">gc_to_sec, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm2546">generated column, <a class="indexterm" href="ddl-generated-columns.html">Generated Columns</a>, <a class="indexterm" href="sql-createforeigntable.html#id-1.9.3.66.6">Parameters</a>, <a class="indexterm" href="sql-createtable.html#id-1.9.3.85.6">Parameters</a></dt><dd><dl><dt>in
+ triggers, <a class="indexterm" href="trigger-definition.html">Overview of Trigger Behavior</a></dt></dl></dd><dt id="ientry-idm26106">generate_series, <a class="indexterm" href="functions-srf.html">Set Returning Functions</a></dt><dt id="ientry-idm26188">generate_subscripts, <a class="indexterm" href="functions-srf.html">Set Returning Functions</a></dt><dt id="ientry-idm41237">genetic query optimization, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm169039">gen_random_bytes, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.11">Random-Data Functions</a></dt><dt id="ientry-idm20694">gen_random_uuid, <a class="indexterm" href="functions-uuid.html">UUID Functions</a>, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.11">Random-Data Functions</a></dt><dt id="ientry-idm168603">gen_salt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.8.8">gen_salt()</a></dt><dt id="ientry-idm41239">GEQO (see <a href="#ientry-idm41237">genetic query optimization</a>)</dt><dt id="ientry-idm41242">geqo configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41264">geqo_effort configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41285">geqo_generations configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41275">geqo_pool_size configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41304">geqo_seed configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41295">geqo_selection_bias configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm41252">geqo_threshold configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">Genetic Query Optimizer</a></dt><dt id="ientry-idm13674">get_bit, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm13690">get_byte, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm19991">get_current_ts_config, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm167969">get_raw_page, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.4">General Functions</a></dt><dt id="ientry-idm31258">GIN (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm29830">gin_clean_pending_list, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">Index Maintenance Functions</a></dt><dt id="ientry-idm43803">gin_fuzzy_search_limit configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER">Other Defaults</a></dt><dt id="ientry-idm168235">gin_leafpage_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.8">GIN Functions</a></dt><dt id="ientry-idm168215">gin_metapage_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.8">GIN Functions</a></dt><dt id="ientry-idm168225">gin_page_opaque_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.8">GIN Functions</a></dt><dt id="ientry-idm43479">gin_pending_list_limit</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt></dl></dd><dt id="ientry-idm31219">GiST (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm168258">gist_page_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.9">GiST Functions</a></dt><dt id="ientry-idm168268">gist_page_items_bytea, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.9">GiST Functions</a></dt><dt id="ientry-idm168248">gist_page_opaque_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.9">GiST Functions</a></dt><dt id="ientry-idm82282">global data, <a class="indexterm" href="pltcl-global.html">Global Data in PL/Tcl</a></dt><dd><dl><dt>in PL/Python, <a class="indexterm" href="plpython-sharing.html">Sharing Data</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-global.html">Global Data in PL/Tcl</a></dt></dl></dd><dt id="ientry-idm3030">GRANT, <a class="indexterm" href="ddl-priv.html">Privileges</a>, <a class="indexterm" href="sql-grant.html">GRANT</a></dt><dt id="ientry-idm23396">GREATEST, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-GREATEST-LEAST">GREATEST and LEAST</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm150650">Gregorian calendar, <a class="indexterm" href="datetime-units-history.html">History of Units</a></dt><dt id="ientry-idm853">GROUP BY, <a class="indexterm" href="tutorial-agg.html">Aggregate Functions</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUP">The GROUP BY and HAVING Clauses</a></dt><dt id="ientry-idm5060">grouping, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUP">The GROUP BY and HAVING Clauses</a></dt><dt id="ientry-idm25497">GROUPING, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm5144">GROUPING SETS, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a></dt><dt id="ientry-idm38185">gssapi, <a class="indexterm" href="gssapi-enc.html">Secure TCP/IP Connections with GSSAPI Encryption</a></dt><dt id="ientry-idm45491">GSSAPI, <a class="indexterm" href="gssapi-auth.html">GSSAPI Authentication</a></dt><dd><dl><dt>with
+ libpq, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt></dl></dd><dt id="ientry-idm8613">GUID, <a class="indexterm" href="datatype-uuid.html">UUID Type</a></dt></dl></div><div class="indexdiv" id="indexdiv-H"><h3>H</h3><dl><dt id="ientry-idm31209">hash (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm168311">hash_bitmap_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.10">Hash Functions</a></dt><dt id="ientry-idm39237">hash_mem_multiplier configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm168321">hash_metapage_info, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.10">Hash Functions</a></dt><dt id="ientry-idm168301">hash_page_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.10">Hash Functions</a></dt><dt id="ientry-idm168291">hash_page_stats, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.10">Hash Functions</a></dt><dt id="ientry-idm168281">hash_page_type, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.10">Hash Functions</a></dt><dt id="ientry-idm26566">has_any_column_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26587">has_column_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26613">has_database_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26635">has_foreign_data_wrapper_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26653">has_function_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26675">has_language_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26693">has_parameter_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26711">has_schema_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26730">has_sequence_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26750">has_server_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26792">has_tablespace_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26768">has_table_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26810">has_type_privilege, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm855">HAVING, <a class="indexterm" href="tutorial-agg.html">Aggregate Functions</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUP">The GROUP BY and HAVING Clauses</a></dt><dt id="ientry-idm38527">hba_file configuration parameter, <a class="indexterm" href="runtime-config-file-locations.html">File Locations</a></dt><dt id="ientry-idm168038">heap_page_items, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.5">Heap Functions</a></dt><dt id="ientry-idm168069">heap_page_item_attrs, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.5">Heap Functions</a></dt><dt id="ientry-idm168083">heap_tuple_infomask_flags, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.5">Heap Functions</a></dt><dt id="ientry-idm19010">height, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm14056">hex format, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm599">hierarchical database, <a class="indexterm" href="tutorial-concepts.html">Concepts</a></dt><dt id="ientry-idm50067">high availability, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm100">history, <a class="indexterm" href="history.html">A Brief History of PostgreSQL</a></dt><dd><dl><dt>of PostgreSQL, <a class="indexterm" href="history.html">A Brief History of PostgreSQL</a></dt></dl></dd><dt id="ientry-idm168506">hmac, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.7.3">hmac()</a></dt><dt id="ientry-idm19621">host, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm58243">host
+ name, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt><dt id="ientry-idm19633">hostmask, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm50658">hot standby, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm40691">hot_standby configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40755">hot_standby_feedback configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm37482">HP-UX</dt><dd><dl><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt></dl></dd><dt id="ientry-idm166056">hstore, <a class="indexterm" href="hstore.html">hstore</a>, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166393">hstore_to_array, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166419">hstore_to_json, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166436">hstore_to_jsonb, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166467">hstore_to_jsonb_loose, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166453">hstore_to_json_loose, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm166406">hstore_to_matrix, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm39129">huge_pages configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm39165">huge_page_size configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm25402">hypothetical-set aggregate</dt><dd><dl><dt>built-in, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-I"><h3>I</h3><dl><dt id="ientry-idm166759">icount, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm35736">ICU, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a>, <a class="indexterm" href="locale.html#id-1.6.11.3.7">Locale Providers</a>, <a class="indexterm" href="collation.html#COLLATION-MANAGING">Managing Collations</a>, <a class="indexterm" href="sql-createcollation.html#id-1.9.3.59.6">Parameters</a>, <a class="indexterm" href="sql-createdatabase.html#id-1.9.3.61.6">Parameters</a></dt><dt id="ientry-idm45652">ident, <a class="indexterm" href="auth-ident.html">Ident Authentication</a></dt><dt id="ientry-idm1192">identifier, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dd><dl><dt>length, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dt>syntax of, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt></dl></dd><dt id="ientry-idm138273">IDENTIFY_SYSTEM, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm38537">ident_file configuration parameter, <a class="indexterm" href="runtime-config-file-locations.html">File Locations</a></dt><dt id="ientry-idm43307">idle_in_transaction_session_timeout configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43318">idle_session_timeout configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm166832">idx, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm23339">IFNULL, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-COALESCE-NVL-IFNULL">COALESCE</a></dt><dt id="ientry-idm44625">ignore_checksum_failure configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44655">ignore_invalid_pages configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44431">ignore_system_indexes configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm73911">IMMUTABLE, <a class="indexterm" href="xfunc-volatility.html">Function Volatility Categories</a></dt><dt id="ientry-idm107898">IMPORT FOREIGN SCHEMA, <a class="indexterm" href="sql-importforeignschema.html">IMPORT FOREIGN SCHEMA</a></dt><dt id="ientry-idm25730">IN, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm31553">INCLUDE</dt><dd><dl><dt>in index definitions, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a></dt></dl></dd><dt id="ientry-idm38453">include</dt><dd><dl><dt>in configuration file, <a class="indexterm" href="config-setting.html#CONFIG-INCLUDES">Managing Configuration File Contents</a></dt></dl></dd><dt id="ientry-idm38470">include_dir</dt><dd><dl><dt>in configuration file, <a class="indexterm" href="config-setting.html#CONFIG-INCLUDES">Managing Configuration File Contents</a></dt></dl></dd><dt id="ientry-idm38461">include_if_exists</dt><dd><dl><dt>in configuration file, <a class="indexterm" href="config-setting.html#CONFIG-INCLUDES">Managing Configuration File Contents</a></dt></dl></dd><dt id="ientry-idm31131">index, <a class="indexterm" href="indexes.html">Indexes</a>, <a class="indexterm" href="indexes-multicolumn.html">Multicolumn Indexes</a>, <a class="indexterm" href="indexes-ordering.html">Indexes and ORDER BY</a>, <a class="indexterm" href="indexes-bitmap-scans.html">Combining Multiple Indexes</a>, <a class="indexterm" href="indexes-unique.html">Unique Indexes</a>, <a class="indexterm" href="indexes-expressional.html">Indexes on Expressions</a>, <a class="indexterm" href="indexes-partial.html">Partial Indexes</a>, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a>, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a>, <a class="indexterm" href="indexes-examine.html">Examining Index Usage</a>, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a>, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a>, <a class="indexterm" href="locking-indexes.html">Locking and Indexes</a>, <a class="indexterm" href="xindex.html">Interfacing Extensions to Indexes</a>, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY">Building Indexes Concurrently</a>, <a class="indexterm" href="sql-reindex.html#SQL-REINDEX-CONCURRENTLY">Rebuilding Indexes Concurrently</a>, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dd><dl><dt>and ORDER BY, <a class="indexterm" href="indexes-ordering.html">Indexes and ORDER BY</a></dt><dt>B-Tree, <a class="indexterm" href="indexes-types.html#INDEXES-TYPES-BTREE">B-Tree</a>, <a class="indexterm" href="btree.html">B-Tree Indexes</a></dt><dt>BRIN, <a class="indexterm" href="indexes-types.html#INDEXES-TYPES-BRIN">BRIN</a>, <a class="indexterm" href="brin.html">BRIN Indexes</a></dt><dt>building concurrently, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY">Building Indexes Concurrently</a></dt><dt>combining multiple indexes, <a class="indexterm" href="indexes-bitmap-scans.html">Combining Multiple Indexes</a></dt><dt>covering, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a></dt><dt>examining usage, <a class="indexterm" href="indexes-examine.html">Examining Index Usage</a></dt><dt>on expressions, <a class="indexterm" href="indexes-expressional.html">Indexes on Expressions</a></dt><dt>for user-defined data type, <a class="indexterm" href="xindex.html">Interfacing Extensions to Indexes</a></dt><dt>GIN, <a class="indexterm" href="indexes-types.html#INDEXES-TYPES-GIN">GIN</a>, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a>, <a class="indexterm" href="gin.html">GIN Indexes</a></dt><dd><dl><dt>text search, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a></dt></dl></dd><dt>GiST, <a class="indexterm" href="indexes-types.html#INDEXES-TYPE-GIST">GiST</a>, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a>, <a class="indexterm" href="gist.html">GiST Indexes</a></dt><dd><dl><dt>text search, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a></dt></dl></dd><dt>hash, <a class="indexterm" href="indexes-types.html#INDEXES-TYPES-HASH">Hash</a></dt><dt>Hash, <a class="indexterm" href="hash-index.html">Hash Indexes</a></dt><dt>index-only scans, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a></dt><dt>locks, <a class="indexterm" href="locking-indexes.html">Locking and Indexes</a></dt><dt>multicolumn, <a class="indexterm" href="indexes-multicolumn.html">Multicolumn Indexes</a></dt><dt>partial, <a class="indexterm" href="indexes-partial.html">Partial Indexes</a></dt><dt>rebuilding concurrently, <a class="indexterm" href="sql-reindex.html#SQL-REINDEX-CONCURRENTLY">Rebuilding Indexes Concurrently</a></dt><dt>SP-GiST, <a class="indexterm" href="indexes-types.html#INDEXES-TYPE-SPGIST">SP-GiST</a>, <a class="indexterm" href="spgist.html">SP-GiST Indexes</a></dt><dt>unique, <a class="indexterm" href="indexes-unique.html">Unique Indexes</a></dt></dl></dd><dt id="ientry-idm143002">Index Access Method, <a class="indexterm" href="indexam.html">Index Access Method Interface Definition</a></dt><dt id="ientry-idm40925">index scan, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm31518">index-only scan, <a class="indexterm" href="indexes-index-only-scans.html">Index-Only Scans and Covering Indexes</a></dt><dt id="ientry-idm143004">indexam</dt><dd><dl><dt>Index Access Method, <a class="indexterm" href="indexam.html">Index Access Method Interface Definition</a></dt></dl></dd><dt id="ientry-idm10164">index_am_handler, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm8285">inet (data type), <a class="indexterm" href="datatype-net-types.html#DATATYPE-INET">inet</a></dt><dt id="ientry-idm26315">inet_client_addr, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26324">inet_client_port, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm19645">inet_merge, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm19658">inet_same_family, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm26333">inet_server_addr, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm26342">inet_server_port, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm6312">infinity</dt><dd><dl><dt>floating point, <a class="indexterm" href="datatype-numeric.html#DATATYPE-FLOAT">Floating-Point Types</a></dt><dt>numeric (data type), <a class="indexterm" href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">Arbitrary Precision Numbers</a></dt></dl></dd><dt id="ientry-idm67505">information schema, <a class="indexterm" href="information-schema.html">The Information Schema</a></dt><dt id="ientry-idm1091">inheritance, <a class="indexterm" href="tutorial-inheritance.html">Inheritance</a>, <a class="indexterm" href="ddl-inherit.html">Inheritance</a></dt><dt id="ientry-idm12519">initcap, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm36979">initdb, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a>, <a class="indexterm" href="app-initdb.html">initdb</a></dt><dt id="ientry-idm147735">Initialization Fork, <a class="indexterm" href="storage-init.html">The Initialization Fork</a></dt><dt id="ientry-idm75123">input function, <a class="indexterm" href="xtypes.html">User-Defined Types</a></dt><dt id="ientry-idm674">INSERT, <a class="indexterm" href="tutorial-populate.html">Populating a Table With Rows</a>, <a class="indexterm" href="dml-insert.html">Inserting Data</a>, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a>, <a class="indexterm" href="sql-insert.html">INSERT</a></dt><dd><dl><dt>RETURNING, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a></dt></dl></dd><dt id="ientry-idm4408">inserting, <a class="indexterm" href="dml-insert.html">Inserting Data</a></dt><dt id="ientry-idm35214">installation, <a class="indexterm" href="installation.html">Installation from Source Code</a></dt><dd><dl><dt>binaries, <a class="indexterm" href="install-binaries.html">Installation from Binaries</a></dt><dt>on Windows, <a class="indexterm" href="install-windows.html">Installation from Source Code on Windows</a></dt></dl></dd><dt id="ientry-idm82196">instr function, <a class="indexterm" href="plpgsql-porting.html#PLPGSQL-PORTING-APPENDIX">Appendix</a></dt><dt id="ientry-idm6233">int2 (see <a href="#ientry-idm6226">smallint</a>)</dt><dt id="ientry-idm6230">int4 (see <a href="#ientry-idm1481">integer</a>)</dt><dt id="ientry-idm6236">int8 (see <a href="#ientry-idm1483">bigint</a>)</dt><dt id="ientry-idm166687">intagg, <a class="indexterm" href="intagg.html">intagg</a></dt><dt id="ientry-idm166729">intarray, <a class="indexterm" href="intarray.html">intarray</a></dt><dt id="ientry-idm1481">integer, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC">Numeric Constants</a>, <a class="indexterm" href="datatype-numeric.html#DATATYPE-INT">Integer Types</a></dt><dt id="ientry-idm44163">integer_datetimes configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm173463">interfaces</dt><dd><dl><dt>externally maintained, <a class="indexterm" href="external-interfaces.html">Client Interfaces</a></dt></dl></dd><dt id="ientry-idm10170">internal, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm5349">INTERSECT, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm6935">interval, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#DATATYPE-INTERVAL-INPUT">Interval Input</a></dt><dd><dl><dt>output format, <a class="indexterm" href="datatype-datetime.html#DATATYPE-INTERVAL-OUTPUT">Interval Output</a></dt><dd><dl><dt>(see also <a href="#ientry-idm15924">formatting</a>)</dt></dl></dd></dl></dd><dt id="ientry-idm43523">IntervalStyle configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm166878">intset, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm166694">int_array_aggregate, <a class="indexterm" href="intagg.html#id-1.11.7.28.4">Functions</a></dt><dt id="ientry-idm166701">int_array_enum, <a class="indexterm" href="intagg.html#id-1.11.7.28.4">Functions</a></dt><dt id="ientry-idm25298">inverse distribution, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm44175">in_hot_standby configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm143831">in_range support functions, <a class="indexterm" href="btree-support-funcs.html">B-Tree Support Functions</a></dt><dt id="ientry-idm10785">IS DISTINCT FROM, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm20900">IS DOCUMENT, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.6.3">IS DOCUMENT</a></dt><dt id="ientry-idm10853">IS FALSE, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10787">IS NOT DISTINCT FROM, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm20912">IS NOT DOCUMENT, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.6.4">IS NOT DOCUMENT</a></dt><dt id="ientry-idm10855">IS NOT FALSE, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10807">IS NOT NULL, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10851">IS NOT TRUE, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10859">IS NOT UNKNOWN, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10805">IS NULL, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a>, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-CLIENTS">Platform and Client Compatibility</a></dt><dt id="ientry-idm10849">IS TRUE, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10857">IS UNKNOWN, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm19022">isclosed, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm24341">isempty, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm17348">isfinite, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm167068">isn, <a class="indexterm" href="isn.html">isn</a></dt><dt id="ientry-idm10809">ISNULL, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm167195">isn_weak, <a class="indexterm" href="isn.html#id-1.11.7.30.7">Functions and Operators</a></dt><dt id="ientry-idm19034">isopen, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm83124">is_array_ref</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm167219">is_valid, <a class="indexterm" href="isn.html#id-1.11.7.30.7">Functions and Operators</a></dt></dl></div><div class="indexdiv" id="indexdiv-J"><h3>J</h3><dl><dt id="ientry-idm57168">JIT, <a class="indexterm" href="jit.html">Just-in-Time Compilation (JIT)</a></dt><dt id="ientry-idm41379">jit configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm41194">jit_above_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm44669">jit_debugging_support configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44680">jit_dump_bitcode configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44693">jit_expressions configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm41207">jit_inline_above_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm41219">jit_optimize_above_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm44704">jit_profiling_support configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm43759">jit_provider configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">Shared Library Preloading</a></dt><dt id="ientry-idm44716">jit_tuple_deforming configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm755">join, <a class="indexterm" href="tutorial-join.html">Joins Between Tables</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a>, <a class="indexterm" href="explicit-joins.html">Controlling the Planner with Explicit JOIN Clauses</a></dt><dd><dl><dt>controlling the order, <a class="indexterm" href="explicit-joins.html">Controlling the Planner with Explicit JOIN Clauses</a></dt><dt>cross, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt>left, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt>natural, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt>outer, <a class="indexterm" href="tutorial-join.html">Joins Between Tables</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt>right, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt>self, <a class="indexterm" href="tutorial-join.html">Joins Between Tables</a></dt></dl></dd><dt id="ientry-idm41392">join_collapse_limit configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm8708">JSON, <a class="indexterm" href="datatype-json.html">JSON Types</a>, <a class="indexterm" href="functions-json.html">JSON Functions and Operators</a></dt><dd><dl><dt>functions and operators, <a class="indexterm" href="functions-json.html">JSON Functions and Operators</a></dt></dl></dd><dt id="ientry-idm8710">JSONB, <a class="indexterm" href="datatype-json.html">JSON Types</a></dt><dt id="ientry-idm8841">jsonb</dt><dd><dl><dt>containment, <a class="indexterm" href="datatype-json.html#JSON-CONTAINMENT">jsonb Containment and Existence</a></dt><dt>existence, <a class="indexterm" href="datatype-json.html#JSON-CONTAINMENT">jsonb Containment and Existence</a></dt><dt>indexes on, <a class="indexterm" href="datatype-json.html#JSON-INDEXING">jsonb Indexing</a></dt></dl></dd><dt id="ientry-idm24756">jsonb_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm21859">jsonb_array_elements, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21878">jsonb_array_elements_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21898">jsonb_array_length, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21760">jsonb_build_array, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21782">jsonb_build_object, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21923">jsonb_each, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21950">jsonb_each_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21979">jsonb_extract_path, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22006">jsonb_extract_path_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22242">jsonb_insert, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21803">jsonb_object, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm24777">jsonb_object_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm22030">jsonb_object_keys, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22293">jsonb_path_exists, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22419">jsonb_path_exists_tz, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22320">jsonb_path_match, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22434">jsonb_path_match_tz, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22345">jsonb_path_query, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22370">jsonb_path_query_array, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22464">jsonb_path_query_array_tz, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22394">jsonb_path_query_first, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22479">jsonb_path_query_first_tz, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22449">jsonb_path_query_tz, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22052">jsonb_populate_record, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22107">jsonb_populate_recordset, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22503">jsonb_pretty, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22175">jsonb_set, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22207">jsonb_set_lax, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22281">jsonb_strip_nulls, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22133">jsonb_to_record, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22158">jsonb_to_recordset, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm20226">jsonb_to_tsvector, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm22522">jsonb_typeof, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm9047">jsonpath, <a class="indexterm" href="datatype-json.html#DATATYPE-JSONPATH">jsonpath Type</a></dt><dt id="ientry-idm24750">json_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm21853">json_array_elements, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21872">json_array_elements_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21892">json_array_length, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21753">json_build_array, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21775">json_build_object, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21913">json_each, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21940">json_each_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21969">json_extract_path, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21996">json_extract_path_text, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21797">json_object, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm24768">json_object_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm22024">json_object_keys, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22043">json_populate_record, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22098">json_populate_recordset, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22275">json_strip_nulls, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22127">json_to_record, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm22152">json_to_recordset, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm20214">json_to_tsvector, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm22516">json_typeof, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm150673">Julian date, <a class="indexterm" href="datetime-julian-dates.html">Julian Dates</a></dt><dt id="ientry-idm57171">Just-In-Time compilation (see <a href="#ientry-idm57168">JIT</a>)</dt><dt id="ientry-idm17380">justify_days, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17392">justify_hours, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17404">justify_interval, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt></dl></div><div class="indexdiv" id="indexdiv-K"><h3>K</h3><dl><dt id="ientry-idm1198">key word, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a>, <a class="indexterm" href="sql-keywords-appendix.html">SQL Key Words</a></dt><dd><dl><dt>list of, <a class="indexterm" href="sql-keywords-appendix.html">SQL Key Words</a></dt><dt>syntax of, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt></dl></dd><dt id="ientry-idm38831">krb_caseins_users configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt><dt id="ientry-idm38817">krb_server_keyfile configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt></dl></div><div class="indexdiv" id="indexdiv-L"><h3>L</h3><dl><dt id="ientry-idm4813">label (see <a href="#ientry-idm810">alias</a>)</dt><dt id="ientry-idm25602">lag, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm10158">language_handler, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm62457">large object, <a class="indexterm" href="largeobjects.html">Large Objects</a></dt><dt id="ientry-idm23222">lastval, <a class="indexterm" href="functions-sequence.html">Sequence Manipulation Functions</a></dt><dt id="ientry-idm25663">last_value, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm4973">LATERAL, <a class="indexterm" href="queries-table-expressions.html#QUERIES-LATERAL">LATERAL Subqueries</a></dt><dd><dl><dt>in the FROM clause, <a class="indexterm" href="queries-table-expressions.html#QUERIES-LATERAL">LATERAL Subqueries</a></dt></dl></dd><dt id="ientry-idm165784">latitude, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm167833">lca, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm11331">lcm, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm44186">lc_collate configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44196">lc_ctype configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm43619">lc_messages configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm43632">lc_monetary configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm43643">lc_numeric configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm43654">lc_time configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm35830">LDAP, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a>, <a class="indexterm" href="auth-ldap.html">LDAP Authentication</a></dt><dt id="ientry-idm62010">LDAP connection parameter lookup, <a class="indexterm" href="libpq-ldap.html">LDAP Lookup of Connection Parameters</a></dt><dt id="ientry-idm36358">ldconfig, <a class="indexterm" href="install-post.html#INSTALL-POST-SHLIBS">Shared Libraries</a></dt><dt id="ientry-idm25627">lead, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm23398">LEAST, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-GREATEST-LEAST">GREATEST and LEAST</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm12531">left, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm4714">left join, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt id="ientry-idm12132">length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a>, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dd><dl><dt>of a binary string (see binary strings, length)</dt><dt>of a character string (see <a href="#ientry-idm1285">character string, length</a>)</dt></dl></dd><dt id="ientry-idm32416">length(tsvector), <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">Manipulating Documents</a></dt><dt id="ientry-idm166011">levenshtein, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.7">Levenshtein</a></dt><dt id="ientry-idm166013">levenshtein_less_equal, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.7">Levenshtein</a></dt><dt id="ientry-idm35394">lex, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm35280">libedit, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dd><dl><dt>in psql, <a class="indexterm" href="app-psql.html#APP-PSQL-READLINE">Command-Line Editing</a></dt></dl></dd><dt id="ientry-idm35314">libperl, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm57676">libpq, <a class="indexterm" href="libpq.html">libpq — C Library</a>, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a>, <a class="indexterm" href="libpq-single-row-mode.html">Retrieving Query Results Row-by-Row</a></dt><dd><dl><dt>pipeline mode, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a></dt><dt>single-row mode, <a class="indexterm" href="libpq-single-row-mode.html">Retrieving Query Results Row-by-Row</a></dt></dl></dd><dt id="ientry-idm57703">libpq-fe.h, <a class="indexterm" href="libpq.html">libpq — C Library</a>, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58750">libpq-int.h, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm35337">libpython, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm74074">library initialization function, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm14381">LIKE, <a class="indexterm" href="functions-matching.html#FUNCTIONS-LIKE">LIKE</a></dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm15764">LIKE_REGEX, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a>, <a class="indexterm" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS">SQL/JSON Regular Expressions</a></dt><dd><dl><dt>in SQL/JSON, <a class="indexterm" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS">SQL/JSON Regular Expressions</a></dt></dl></dd><dt id="ientry-idm5481">LIMIT, <a class="indexterm" href="queries-limit.html">LIMIT and OFFSET</a></dt><dt id="ientry-idm8059">line, <a class="indexterm" href="datatype-geometric.html#DATATYPE-LINE">Lines</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm8099">line segment, <a class="indexterm" href="datatype-geometric.html#DATATYPE-LSEG">Line Segments</a></dt><dt id="ientry-idm24978">linear regression, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm37171">Linux</dt><dd><dl><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt>start script, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm108404">LISTEN, <a class="indexterm" href="sql-listen.html">LISTEN</a></dt><dt id="ientry-idm38585">listen_addresses configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm35768">llvm-config, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a></dt><dt id="ientry-idm165774">ll_to_earth, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm11349">ln, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm167279">lo, <a class="indexterm" href="lo.html">lo</a></dt><dt id="ientry-idm108474">LOAD, <a class="indexterm" href="sql-load.html">LOAD</a></dt><dt id="ientry-idm50073">load balancing, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm37047">locale, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a>, <a class="indexterm" href="locale.html">Locale Support</a></dt><dt id="ientry-idm17418">localtime, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17441">localtimestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm43697">local_preload_libraries configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">Shared Library Preloading</a></dt><dt id="ientry-idm33812">lock, <a class="indexterm" href="explicit-locking.html">Explicit Locking</a>, <a class="indexterm" href="explicit-locking.html#ADVISORY-LOCKS">Advisory Locks</a>, <a class="indexterm" href="monitoring-locks.html">Viewing Locks</a></dt><dd><dl><dt>advisory, <a class="indexterm" href="explicit-locking.html#ADVISORY-LOCKS">Advisory Locks</a></dt><dt>monitoring, <a class="indexterm" href="monitoring-locks.html">Viewing Locks</a></dt></dl></dd><dt id="ientry-idm33826">LOCK, <a class="indexterm" href="explicit-locking.html#LOCKING-TABLES">Table-Level Locks</a>, <a class="indexterm" href="sql-lock.html">LOCK</a></dt><dt id="ientry-idm43286">lock_timeout configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm11365">log, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm50317">log shipping, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm11381">log10, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm26381">Logging</dt><dd><dl><dt>current_logfiles file and the pg_current_logfile
+ function, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt>pg_current_logfile function, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt></dl></dd><dt id="ientry-idm41509">logging_collector configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm87254">Logical Decoding, <a class="indexterm" href="logicaldecoding.html">Logical Decoding</a>, <a class="indexterm" href="logicaldecoding-explanation.html#id-1.8.14.8.2">Logical Decoding</a></dt><dt id="ientry-idm39288">logical_decoding_work_mem configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm46057">login privilege, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt id="ientry-idm42012">log_autovacuum_min_duration</dt><dd><dl><dt>configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt>storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt></dl></dd><dt id="ientry-idm44580">log_btree_build_stats configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm42027">log_checkpoints configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42037">log_connections configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41450">log_destination configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41530">log_directory configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm42052">log_disconnections configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42064">log_duration configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42084">log_error_verbosity configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42778">log_executor_stats configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">Statistics Monitoring</a></dt><dt id="ientry-idm41542">log_filename configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41575">log_file_mode configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm42105">log_hostname configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42115">log_line_prefix configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42270">log_lock_waits configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41804">log_min_duration_sample configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm41783">log_min_duration_statement configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm41758">log_min_error_statement configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm41732">log_min_messages configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm42295">log_parameter_max_length configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42309">log_parameter_max_length_on_error configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42766">log_parser_stats configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">Statistics Monitoring</a></dt><dt id="ientry-idm42772">log_planner_stats configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">Statistics Monitoring</a></dt><dt id="ientry-idm42282">log_recovery_conflict_waits configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42358">log_replication_commands configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41594">log_rotation_age configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41605">log_rotation_size configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41854">log_startup_progress_interval configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm42321">log_statement configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41823">log_statement_sample_rate configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm42760">log_statement_stats configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">Statistics Monitoring</a></dt><dt id="ientry-idm42370">log_temp_files configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm42380">log_timezone configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">What to Log</a></dt><dt id="ientry-idm41838">log_transaction_sample_rate configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">When to Log</a></dt><dt id="ientry-idm41616">log_truncate_on_rotation configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm165793">longitude, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm83112">looks_like_number</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt></dl></dd><dt id="ientry-idm80623">loop, <a class="indexterm" href="plpgsql-control-structures.html#PLPGSQL-CONTROL-STRUCTURES-LOOPS">Simple Loops</a></dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#PLPGSQL-CONTROL-STRUCTURES-LOOPS">Simple Loops</a></dt></dl></dd><dt id="ientry-idm12152">lower, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm24353">lower_inc, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm24377">lower_inf, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm62732">lo_close, <a class="indexterm" href="lo-interfaces.html#LO-CLOSE">Closing a Large Object Descriptor</a></dt><dt id="ientry-idm43954">lo_compat_privileges configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm62533">lo_creat, <a class="indexterm" href="lo-interfaces.html#LO-CREATE">Creating a Large Object</a>, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62522">lo_create, <a class="indexterm" href="lo-interfaces.html#LO-CREATE">Creating a Large Object</a></dt><dt id="ientry-idm62580">lo_export, <a class="indexterm" href="lo-interfaces.html#LO-EXPORT">Exporting a Large Object</a>, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62763">lo_from_bytea, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62798">lo_get, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62557">lo_import, <a class="indexterm" href="lo-interfaces.html#LO-IMPORT">Importing a Large Object</a>, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62563">lo_import_with_oid, <a class="indexterm" href="lo-interfaces.html#LO-IMPORT">Importing a Large Object</a></dt><dt id="ientry-idm62664">lo_lseek, <a class="indexterm" href="lo-interfaces.html#LO-SEEK">Seeking in a Large Object</a></dt><dt id="ientry-idm62674">lo_lseek64, <a class="indexterm" href="lo-interfaces.html#LO-SEEK">Seeking in a Large Object</a></dt><dt id="ientry-idm62588">lo_open, <a class="indexterm" href="lo-interfaces.html#LO-OPEN">Opening an Existing Large Object</a></dt><dt id="ientry-idm62780">lo_put, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62647">lo_read, <a class="indexterm" href="lo-interfaces.html#LO-READ">Reading Data from a Large Object</a></dt><dt id="ientry-idm62686">lo_tell, <a class="indexterm" href="lo-interfaces.html#LO-TELL">Obtaining the Seek Position of a Large Object</a></dt><dt id="ientry-idm62690">lo_tell64, <a class="indexterm" href="lo-interfaces.html#LO-TELL">Obtaining the Seek Position of a Large Object</a></dt><dt id="ientry-idm62701">lo_truncate, <a class="indexterm" href="lo-interfaces.html#LO-TRUNCATE">Truncating a Large Object</a></dt><dt id="ientry-idm62718">lo_truncate64, <a class="indexterm" href="lo-interfaces.html#LO-TRUNCATE">Truncating a Large Object</a></dt><dt id="ientry-idm62742">lo_unlink, <a class="indexterm" href="lo-interfaces.html#LO-UNLINK">Removing a Large Object</a>, <a class="indexterm" href="lo-funcs.html">Server-Side Functions</a></dt><dt id="ientry-idm62630">lo_write, <a class="indexterm" href="lo-interfaces.html#LO-WRITE">Writing Data to a Large Object</a></dt><dt id="ientry-idm12561">lpad, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm8097">lseg, <a class="indexterm" href="datatype-geometric.html#DATATYPE-LSEG">Line Segments</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm56577">LSN, <a class="indexterm" href="wal-internals.html">WAL Internals</a></dt><dt id="ientry-idm167335">ltree, <a class="indexterm" href="ltree.html">ltree</a></dt><dt id="ientry-idm167822">ltree2text, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm12584">ltrim, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt></dl></div><div class="indexdiv" id="indexdiv-M"><h3>M</h3><dl><dt id="ientry-idm8414">MAC address (see macaddr)</dt><dt id="ientry-idm8443">MAC address (EUI-64 format) (see macaddr)</dt><dt id="ientry-idm8412">macaddr (data type), <a class="indexterm" href="datatype-net-types.html#DATATYPE-MACADDR">macaddr</a></dt><dt id="ientry-idm8441">macaddr8 (data type), <a class="indexterm" href="datatype-net-types.html#DATATYPE-MACADDR8">macaddr8</a></dt><dt id="ientry-idm19794">macaddr8_set7bit, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm36507">macOS, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-MACOS">macOS</a></dt><dd><dl><dt>installation on, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-MACOS">macOS</a></dt><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt></dl></dd><dt id="ientry-idm74063">magic block, <a class="indexterm" href="xfunc-c.html#XFUNC-C-DYNLOAD">Dynamic Loading</a></dt><dt id="ientry-idm48914">maintenance, <a class="indexterm" href="maintenance.html">Routine Database Maintenance Tasks</a></dt><dt id="ientry-idm39561">maintenance_io_concurrency configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm39253">maintenance_work_mem configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm35250">make, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm26990">makeaclitem, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm17464">make_date, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17481">make_interval, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17513">make_time, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17530">make_timestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm17553">make_timestamptz, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm167210">make_valid, <a class="indexterm" href="isn.html#id-1.11.7.30.7">Functions and Operators</a></dt><dt id="ientry-idm36388">MANPATH, <a class="indexterm" href="install-post.html#id-1.6.4.9.3">Environment Variables</a></dt><dt id="ientry-idm19671">masklen, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm79049">materialized view, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a></dt><dd><dl><dt>implementation through rules, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a></dt></dl></dd><dt id="ientry-idm135630">materialized views, <a class="indexterm" href="view-pg-matviews.html">pg_matviews</a></dt><dt id="ientry-idm24792">max, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm38611">max_connections configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm39382">max_files_per_process configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-KERNEL">Kernel Resource Usage</a></dt><dt id="ientry-idm44207">max_function_args configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44217">max_identifier_length configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44229">max_index_keys configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm43836">max_locks_per_transaction configuration parameter, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt><dt id="ientry-idm40825">max_logical_replication_workers configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SUBSCRIBER">Subscribers</a></dt><dt id="ientry-idm39605">max_parallel_maintenance_workers configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm39621">max_parallel_workers configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm39587">max_parallel_workers_per_gather configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm43875">max_pred_locks_per_page configuration parameter, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt><dt id="ientry-idm43863">max_pred_locks_per_relation configuration parameter, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt><dt id="ientry-idm43850">max_pred_locks_per_transaction configuration parameter, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt><dt id="ientry-idm39204">max_prepared_transactions configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm40476">max_replication_slots configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm40507">max_slot_wal_keep_size configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm39300">max_stack_depth configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm40702">max_standby_archive_delay configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40716">max_standby_streaming_delay configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40837">max_sync_workers_per_subscription configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SUBSCRIBER">Subscribers</a></dt><dt id="ientry-idm40462">max_wal_senders configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm40097">max_wal_size configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm39573">max_worker_processes configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm12602">md5, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm45425">MD5, <a class="indexterm" href="auth-password.html">Password Authentication</a></dt><dt id="ientry-idm2004">median, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a></dt><dd><dl><dt>(see also <a href="#ientry-idm25329">percentile</a>)</dt></dl></dd><dt id="ientry-idm86566">memory context</dt><dd><dl><dt>in SPI, <a class="indexterm" href="spi-memory.html">Memory Management</a></dt></dl></dd><dt id="ientry-idm37638">memory overcommit, <a class="indexterm" href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">Linux Memory Overcommit</a></dt><dt id="ientry-idm108654">MERGE, <a class="indexterm" href="sql-merge.html">MERGE</a></dt><dt id="ientry-idm166032">metaphone, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.8">Metaphone</a></dt><dt id="ientry-idm24810">min, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm36540">MinGW, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-MINGW">MinGW/Native Windows</a></dt><dd><dl><dt>installation on, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-MINGW">MinGW/Native Windows</a></dt></dl></dd><dt id="ientry-idm39349">min_dynamic_shared_memory configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm41167">min_parallel_index_scan_size configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm41156">min_parallel_table_scan_size configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm11413">min_scale, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm40111">min_wal_size configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">Checkpoints</a></dt><dt id="ientry-idm11425">mod, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm25315">mode</dt><dd><dl><dt>statistical, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm50994">monitoring, <a class="indexterm" href="monitoring.html">Monitoring Database Activity</a></dt><dd><dl><dt>database activity, <a class="indexterm" href="monitoring.html">Monitoring Database Activity</a></dt></dl></dd><dt id="ientry-idm109015">MOVE, <a class="indexterm" href="sql-move.html">MOVE</a></dt><dt id="ientry-idm74951">moving-aggregate mode, <a class="indexterm" href="xaggr.html#XAGGR-MOVING-AGGREGATES">Moving-Aggregate Mode</a></dt><dt id="ientry-idm24522">multirange (function), <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm9621">multirange type, <a class="indexterm" href="rangetypes.html">Range Types</a></dt><dt id="ientry-idm33509">Multiversion Concurrency Control, <a class="indexterm" href="mvcc-intro.html">Introduction</a></dt><dt id="ientry-idm49250">MultiXactId, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND">Multixacts and Wraparound</a></dt><dt id="ientry-idm33511">MVCC, <a class="indexterm" href="mvcc-intro.html">Introduction</a></dt></dl></div><div class="indexdiv" id="indexdiv-N"><h3>N</h3><dl><dt id="ientry-idm1195">name, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dd><dl><dt>qualified, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CREATE">Creating a Schema</a></dt><dt>syntax of, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dt>unqualified, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a></dt></dl></dd><dt id="ientry-idm6315">NaN (see <a href="#ientry-idm6318">not a number</a>)</dt><dt id="ientry-idm4761">natural join, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt id="ientry-idm10370">negation, <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm37196">NetBSD</dt><dd><dl><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt>start script, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm19683">netmask, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm8240">network, <a class="indexterm" href="datatype-net-types.html">Network Address Types</a>, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dd><dl><dt>data types, <a class="indexterm" href="datatype-net-types.html">Network Address Types</a></dt></dl></dd><dt id="ientry-idm23157">nextval, <a class="indexterm" href="functions-sequence.html">Sequence Manipulation Functions</a></dt><dt id="ientry-idm37072">NFS, <a class="indexterm" href="creating-cluster.html#CREATING-CLUSTER-NFS">NFS</a></dt><dt id="ientry-idm167762">nlevel, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm34953">non-durable, <a class="indexterm" href="non-durability.html">Non-Durable Settings</a></dt><dt id="ientry-idm57831">nonblocking connection, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a>, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm33548">nonrepeatable read, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a></dt><dt id="ientry-idm12164">normalize, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm12089">normalized, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm172263">normal_rand, <a class="indexterm" href="tablefunc.html#id-1.11.7.52.5.4">normal_rand</a></dt><dt id="ientry-idm10364">NOT (operator), <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm6318">not a number</dt><dd><dl><dt>floating point, <a class="indexterm" href="datatype-numeric.html#DATATYPE-FLOAT">Floating-Point Types</a></dt><dt>numeric (data type), <a class="indexterm" href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">Arbitrary Precision Numbers</a></dt></dl></dd><dt id="ientry-idm25732">NOT IN, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm2660">not-null constraint, <a class="indexterm" href="ddl-constraints.html#id-1.5.4.6.6">Not-Null Constraints</a></dt><dt id="ientry-idm2403">notation, <a class="indexterm" href="sql-syntax-calling-funcs.html">Calling Functions</a></dt><dd><dl><dt>functions, <a class="indexterm" href="sql-syntax-calling-funcs.html">Calling Functions</a></dt></dl></dd><dt id="ientry-idm61411">notice processing, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt></dl></dd><dt id="ientry-idm61424">notice processor, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt><dt id="ientry-idm61419">notice receiver, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt><dt id="ientry-idm60753">NOTIFY, <a class="indexterm" href="libpq-notify.html">Asynchronous Notification</a>, <a class="indexterm" href="sql-notify.html">NOTIFY</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-notify.html">Asynchronous Notification</a></dt></dl></dd><dt id="ientry-idm10811">NOTNULL, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm17584">now, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm19060">npoints, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm25674">nth_value, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm25592">ntile, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm2523">null value</dt><dd><dl><dt>with check constraints, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">Check Constraints</a></dt><dt>comparing, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt>default value, <a class="indexterm" href="ddl-default.html">Default Values</a></dt><dt>in DISTINCT, <a class="indexterm" href="queries-select-lists.html#QUERIES-DISTINCT">DISTINCT</a></dt><dt>in libpq, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt>in PL/Perl, <a class="indexterm" href="plperl-funcs.html">PL/Perl Functions and Arguments</a></dt><dt>in PL/Python, <a class="indexterm" href="plpython-data.html#id-1.8.11.10.4">Null, None</a></dt><dt>with unique constraints, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS">Unique Constraints</a></dt></dl></dd><dt id="ientry-idm23361">NULLIF, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-NULLIF">NULLIF</a></dt><dt id="ientry-idm1455">number</dt><dd><dl><dt>constant, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC">Numeric Constants</a></dt></dl></dd><dt id="ientry-idm1485">numeric, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC">Numeric Constants</a></dt><dt id="ientry-idm6260">numeric (data type), <a class="indexterm" href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">Arbitrary Precision Numbers</a></dt><dt id="ientry-idm20016">numnode, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSQUERY">Manipulating Queries</a></dt><dt id="ientry-idm10888">num_nonnulls, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm10901">num_nulls, <a class="indexterm" href="functions-comparison.html">Comparison Functions and Operators</a></dt><dt id="ientry-idm23337">NVL, <a class="indexterm" href="functions-conditional.html#FUNCTIONS-COALESCE-NVL-IFNULL">COALESCE</a></dt></dl></div><div class="indexdiv" id="indexdiv-O"><h3>O</h3><dl><dt id="ientry-idm9866">object identifier, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dd><dl><dt>data type, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt></dl></dd><dt id="ientry-idm601">object-oriented database, <a class="indexterm" href="tutorial-concepts.html">Concepts</a></dt><dt id="ientry-idm27971">obj_description, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm15766">OCCURRENCES_REGEX, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a></dt><dt id="ientry-idm12186">octet_length, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm5483">OFFSET, <a class="indexterm" href="queries-limit.html">LIMIT and OFFSET</a></dt><dt id="ientry-idm9869">oid, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm59903">OID</dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">Retrieving Other Result Information</a></dt></dl></dd><dt id="ientry-idm173075">oid2name, <a class="indexterm" href="oid2name.html">oid2name</a></dt><dt id="ientry-idm167944">old_snapshot, <a class="indexterm" href="oldsnapshot.html">old_snapshot</a></dt><dt id="ientry-idm39646">old_snapshot_threshold configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm108180">ON CONFLICT, <a class="indexterm" href="sql-insert.html">INSERT</a></dt><dt id="ientry-idm4600">ONLY, <a class="indexterm" href="queries-table-expressions.html#QUERIES-FROM">The FROM Clause</a></dt><dt id="ientry-idm37640">OOM, <a class="indexterm" href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">Linux Memory Overcommit</a></dt><dt id="ientry-idm37164">OpenBSD</dt><dd><dl><dt>IPC configuration, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt>start script, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm35797">OpenSSL, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a></dt><dd><dl><dt>(see also <a href="#ientry-idm37993">SSL</a>)</dt></dl></dd><dt id="ientry-idm1542">operator, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-OPERATORS">Operators</a>, <a class="indexterm" href="sql-syntax-lexical.html#SQL-PRECEDENCE">Operator Precedence</a>, <a class="indexterm" href="functions.html">Functions and Operators</a>, <a class="indexterm" href="functions-logical.html">Logical Operators</a>, <a class="indexterm" href="typeconv-oper.html">Operators</a>, <a class="indexterm" href="xoper.html">User-Defined Operators</a></dt><dd><dl><dt>invocation, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-OPERATOR-CALLS">Operator Invocations</a></dt><dt>logical, <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt>precedence, <a class="indexterm" href="sql-syntax-lexical.html#SQL-PRECEDENCE">Operator Precedence</a></dt><dt>syntax, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-OPERATORS">Operators</a></dt><dt>type resolution in an invocation, <a class="indexterm" href="typeconv-oper.html">Operators</a></dt><dt>user-defined, <a class="indexterm" href="xoper.html">User-Defined Operators</a></dt></dl></dd><dt id="ientry-idm31612">operator class, <a class="indexterm" href="indexes-opclass.html">Operator Classes and Operator Families</a>, <a class="indexterm" href="xindex.html#XINDEX-OPCLASS">Index Methods and Operator Classes</a></dt><dt id="ientry-idm31614">operator family, <a class="indexterm" href="indexes-opclass.html">Operator Classes and Operator Families</a>, <a class="indexterm" href="xindex.html#XINDEX-OPFAMILY">Operator Classes and Operator Families</a></dt><dt id="ientry-idm74858">optimization information, <a class="indexterm" href="xfunc-optimization.html">Function Optimization Information</a>, <a class="indexterm" href="xoper-optimization.html">Operator Optimization Information</a></dt><dd><dl><dt>for functions, <a class="indexterm" href="xfunc-optimization.html">Function Optimization Information</a></dt><dt>for operators, <a class="indexterm" href="xoper-optimization.html">Operator Optimization Information</a></dt></dl></dd><dt id="ientry-idm10362">OR (operator), <a class="indexterm" href="functions-logical.html">Logical Operators</a></dt><dt id="ientry-idm81986">Oracle, <a class="indexterm" href="plpgsql-porting.html">Porting from Oracle PL/SQL</a></dt><dd><dl><dt>porting from PL/SQL to PL/pgSQL, <a class="indexterm" href="plpgsql-porting.html">Porting from Oracle PL/SQL</a></dt></dl></dd><dt id="ientry-idm731">ORDER BY, <a class="indexterm" href="tutorial-select.html">Querying a Table</a>, <a class="indexterm" href="queries-order.html">Sorting Rows (ORDER BY)</a></dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm1917">ordered-set aggregate, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a></dt><dd><dl><dt>built-in, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm75989">ordering operator, <a class="indexterm" href="xindex.html#XINDEX-OPCLASS-DEPENDENCIES">System Dependencies on Operator Classes</a></dt><dt id="ientry-idm26216">ordinality, <a class="indexterm" href="functions-srf.html">Set Returning Functions</a></dt><dt id="ientry-idm4670">outer join, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt id="ientry-idm75125">output function, <a class="indexterm" href="xtypes.html">User-Defined Types</a></dt><dt id="ientry-idm2031">OVER clause, <a class="indexterm" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS">Window Function Calls</a></dt><dt id="ientry-idm37642">overcommit, <a class="indexterm" href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">Linux Memory Overcommit</a></dt><dt id="ientry-idm17644">OVERLAPS, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm12211">overlay, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm73871">overloading, <a class="indexterm" href="xfunc-overload.html">Function Overloading</a></dt><dd><dl><dt>functions, <a class="indexterm" href="xfunc-overload.html">Function Overloading</a></dt><dt>operators, <a class="indexterm" href="xoper.html">User-Defined Operators</a></dt></dl></dd><dt id="ientry-idm3028">owner, <a class="indexterm" href="ddl-priv.html">Privileges</a></dt></dl></div><div class="indexdiv" id="indexdiv-P"><h3>P</h3><dl><dt id="ientry-idm167959">pageinspect, <a class="indexterm" href="pageinspect.html">pageinspect</a></dt><dt id="ientry-idm97811">pages_per_range storage parameter, <a class="indexterm" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS">Index Storage Parameters</a></dt><dt id="ientry-idm168008">page_checksum, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.4">General Functions</a></dt><dt id="ientry-idm167992">page_header, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.4">General Functions</a></dt><dt id="ientry-idm74463">palloc, <a class="indexterm" href="xfunc-c.html#id-1.8.3.13.8">Writing Code</a></dt><dt id="ientry-idm35845">PAM, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a>, <a class="indexterm" href="auth-pam.html">PAM Authentication</a></dt><dt id="ientry-idm34983">parallel query, <a class="indexterm" href="parallel-query.html">Parallel Query</a></dt><dt id="ientry-idm39633">parallel_leader_participation configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">Asynchronous Behavior</a></dt><dt id="ientry-idm41138">parallel_setup_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm41147">parallel_tuple_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm101397">parallel_workers storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm1810">parameter</dt><dd><dl><dt>syntax, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL">Positional Parameters</a></dt></dl></dd><dt id="ientry-idm1789">parenthesis, <a class="indexterm" href="sql-expressions.html">Value Expressions</a></dt><dt id="ientry-idm12615">parse_ident, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm4234">partition pruning, <a class="indexterm" href="ddl-partitioning.html#DDL-PARTITION-PRUNING">Partition Pruning</a></dt><dt id="ientry-idm3950">partitioned table, <a class="indexterm" href="ddl-partitioning.html">Table Partitioning</a></dt><dt id="ientry-idm3945">partitioning, <a class="indexterm" href="ddl-partitioning.html">Table Partitioning</a></dt><dt id="ientry-idm37035">password, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dd><dl><dt>authentication, <a class="indexterm" href="auth-password.html">Password Authentication</a></dt><dt>of the superuser, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a></dt></dl></dd><dt id="ientry-idm61946">password file, <a class="indexterm" href="libpq-pgpass.html">The Password File</a></dt><dt id="ientry-idm168330">passwordcheck, <a class="indexterm" href="passwordcheck.html">passwordcheck</a></dt><dt id="ientry-idm38801">password_encryption configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt><dt id="ientry-idm19270">path, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dd><dl><dt>for schemas, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></dd><dt id="ientry-idm36369">PATH, <a class="indexterm" href="install-post.html#id-1.6.4.9.3">Environment Variables</a></dt><dt id="ientry-idm8158">path (data type), <a class="indexterm" href="datatype-geometric.html#id-1.5.7.16.9">Paths</a></dt><dt id="ientry-idm14358">pattern matching, <a class="indexterm" href="functions-matching.html">Pattern Matching</a></dt><dt id="ientry-idm122935">patterns</dt><dd><dl><dt>in psql and pg_dump, <a class="indexterm" href="app-psql.html#APP-PSQL-PATTERNS">Patterns</a></dt></dl></dd><dt id="ientry-idm19074">pclose, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm45686">peer, <a class="indexterm" href="auth-peer.html">Peer Authentication</a></dt><dt id="ientry-idm25329">percentile</dt><dd><dl><dt>continuous, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt>discrete, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm25458">percent_rank, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dd><dl><dt>hypothetical, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm34374">performance, <a class="indexterm" href="performance-tips.html">Performance Tips</a></dt><dt id="ientry-idm35408">perl, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm82706">Perl, <a class="indexterm" href="plperl.html">PL/Perl — Perl Procedural Language</a></dt><dt id="ientry-idm3025">permission (see <a href="#ientry-idm3023">privilege</a>)</dt><dt id="ientry-idm74466">pfree, <a class="indexterm" href="xfunc-c.html#id-1.8.3.13.8">Writing Code</a></dt><dt id="ientry-idm61767">PGAPPNAME, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm115765">pgbench, <a class="indexterm" href="pgbench.html">pgbench</a></dt><dt id="ientry-idm60644">PGcancel, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dt id="ientry-idm61737">PGCHANNELBINDING, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61887">PGCLIENTENCODING, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm57711">PGconn, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm61880">PGCONNECT_TIMEOUT, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm168469">pgcrypto, <a class="indexterm" href="pgcrypto.html">pgcrypto</a></dt><dt id="ientry-idm36996">PGDATA, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a></dt><dt id="ientry-idm61707">PGDATABASE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61906">PGDATESTYLE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61578">PGEventProc, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-PROC">Event Callback Procedure</a></dt><dt id="ientry-idm61920">PGGEQO, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61859">PGGSSENCMODE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61873">PGGSSLIB, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61685">PGHOST, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61692">PGHOSTADDR, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61866">PGKRBSRVNAME, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61939">PGLOCALEDIR, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61760">PGOPTIONS, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61730">PGPASSFILE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61721">PGPASSWORD, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61700">PGPORT, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm168876">pgp_armor_headers, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.17">pgp_armor_headers</a></dt><dt id="ientry-idm168841">pgp_key_id, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.15">pgp_key_id()</a></dt><dt id="ientry-idm168824">pgp_pub_decrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.14">pgp_pub_decrypt()</a></dt><dt id="ientry-idm168826">pgp_pub_decrypt_bytea, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.14">pgp_pub_decrypt()</a></dt><dt id="ientry-idm168811">pgp_pub_encrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.13">pgp_pub_encrypt()</a></dt><dt id="ientry-idm168813">pgp_pub_encrypt_bytea, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.13">pgp_pub_encrypt()</a></dt><dt id="ientry-idm168796">pgp_sym_decrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.12">pgp_sym_decrypt()</a></dt><dt id="ientry-idm168798">pgp_sym_decrypt_bytea, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.12">pgp_sym_decrypt()</a></dt><dt id="ientry-idm168784">pgp_sym_encrypt, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.11">pgp_sym_encrypt()</a></dt><dt id="ientry-idm168786">pgp_sym_encrypt_bytea, <a class="indexterm" href="pgcrypto.html#id-1.11.7.37.9.11">pgp_sym_encrypt()</a></dt><dt id="ientry-idm61838">PGREQUIREPEER, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61781">PGREQUIRESSL, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm59338">PGresult, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm169269">pgrowlocks, <a class="indexterm" href="pgrowlocks.html">pgrowlocks</a>, <a class="indexterm" href="pgrowlocks.html#id-1.11.7.40.5">Overview</a></dt><dt id="ientry-idm61744">PGSERVICE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61751">PGSERVICEFILE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61796">PGSSLCERT, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61789">PGSSLCOMPRESSION, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61817">PGSSLCRL, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61824">PGSSLCRLDIR, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61803">PGSSLKEY, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61852">PGSSLMAXPROTOCOLVERSION, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61845">PGSSLMINPROTOCOLVERSION, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61774">PGSSLMODE, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61810">PGSSLROOTCERT, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61831">PGSSLSNI, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm170076">pgstatginindex, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm170112">pgstathashindex, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm169986">pgstatindex, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm169879">pgstattuple, <a class="indexterm" href="pgstattuple.html">pgstattuple</a>, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm170192">pgstattuple_approx, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm61932">PGSYSCONFDIR, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61894">PGTARGETSESSIONATTRS, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61913">PGTZ, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm61714">PGUSER, <a class="indexterm" href="libpq-envars.html">Environment Variables</a></dt><dt id="ientry-idm76490">pgxs, <a class="indexterm" href="extend-pgxs.html">Extension Building Infrastructure</a></dt><dt id="ientry-idm30107">pg_advisory_lock, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30124">pg_advisory_lock_shared, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30141">pg_advisory_unlock, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30160">pg_advisory_unlock_all, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30168">pg_advisory_unlock_shared, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30187">pg_advisory_xact_lock, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30204">pg_advisory_xact_lock_shared, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm128233">pg_aggregate, <a class="indexterm" href="catalog-pg-aggregate.html">pg_aggregate</a></dt><dt id="ientry-idm128447">pg_am, <a class="indexterm" href="catalog-pg-am.html">pg_am</a></dt><dt id="ientry-idm114766">pg_amcheck, <a class="indexterm" href="app-pgamcheck.html">pg_amcheck</a></dt><dt id="ientry-idm128501">pg_amop, <a class="indexterm" href="catalog-pg-amop.html">pg_amop</a></dt><dt id="ientry-idm128622">pg_amproc, <a class="indexterm" href="catalog-pg-amproc.html">pg_amproc</a></dt><dt id="ientry-idm124921">pg_archivecleanup, <a class="indexterm" href="pgarchivecleanup.html">pg_archivecleanup</a></dt><dt id="ientry-idm128694">pg_attrdef, <a class="indexterm" href="catalog-pg-attrdef.html">pg_attrdef</a></dt><dt id="ientry-idm128745">pg_attribute, <a class="indexterm" href="catalog-pg-attribute.html">pg_attribute</a></dt><dt id="ientry-idm128973">pg_authid, <a class="indexterm" href="catalog-pg-authid.html">pg_authid</a></dt><dt id="ientry-idm129096">pg_auth_members, <a class="indexterm" href="catalog-pg-auth-members.html">pg_auth_members</a></dt><dt id="ientry-idm134789">pg_available_extensions, <a class="indexterm" href="view-pg-available-extensions.html">pg_available_extensions</a></dt><dt id="ientry-idm134836">pg_available_extension_versions, <a class="indexterm" href="view-pg-available-extension-versions.html">pg_available_extension_versions</a></dt><dt id="ientry-idm134914">pg_backend_memory_contexts, <a class="indexterm" href="view-pg-backend-memory-contexts.html">pg_backend_memory_contexts</a></dt><dt id="ientry-idm26351">pg_backend_pid, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28789">pg_backup_start, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm28805">pg_backup_stop, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm115186">pg_basebackup, <a class="indexterm" href="app-pgbasebackup.html">pg_basebackup</a></dt><dt id="ientry-idm26359">pg_blocking_pids, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm168356">pg_buffercache, <a class="indexterm" href="pgbuffercache.html">pg_buffercache</a></dt><dt id="ientry-idm168360">pg_buffercache_pages, <a class="indexterm" href="pgbuffercache.html">pg_buffercache</a></dt><dt id="ientry-idm28646">pg_cancel_backend, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt><dt id="ientry-idm129152">pg_cast, <a class="indexterm" href="catalog-pg-cast.html">pg_cast</a></dt><dt id="ientry-idm27185">pg_char_to_encoding, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm125040">pg_checksums, <a class="indexterm" href="app-pgchecksums.html">pg_checksums</a></dt><dt id="ientry-idm129240">pg_class, <a class="indexterm" href="catalog-pg-class.html">pg_class</a></dt><dt id="ientry-idm12635">pg_client_encoding, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm129564">pg_collation, <a class="indexterm" href="catalog-pg-collation.html">pg_collation</a></dt><dt id="ientry-idm29692">pg_collation_actual_version, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm27024">pg_collation_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm175481">PG_COLOR, <a class="indexterm" href="color-when.html">When Color is Used</a></dt><dt id="ientry-idm175496">PG_COLORS, <a class="indexterm" href="color-which.html">Configuring the Colors</a></dt><dt id="ientry-idm29499">pg_column_compression, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29490">pg_column_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm62397">pg_config, <a class="indexterm" href="app-pgconfig.html">pg_config</a>, <a class="indexterm" href="view-pg-config.html">pg_config</a></dt><dd><dl><dt>with
+ ecpg, <a class="indexterm" href="ecpg-process.html">Processing Embedded SQL Programs</a></dt><dt>with libpq, <a class="indexterm" href="libpq-build.html">Building libpq Programs</a></dt><dt>with user-defined C functions, <a class="indexterm" href="xfunc-c.html#id-1.8.3.13.8">Writing Code</a></dt></dl></dd><dt id="ientry-idm26371">pg_conf_load_time, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm129674">pg_constraint, <a class="indexterm" href="catalog-pg-constraint.html">pg_constraint</a></dt><dt id="ientry-idm125181">pg_controldata, <a class="indexterm" href="app-pgcontroldata.html">pg_controldata</a></dt><dt id="ientry-idm28293">pg_control_checkpoint, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28311">pg_control_init, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28320">pg_control_recovery, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28302">pg_control_system, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm129924">pg_conversion, <a class="indexterm" href="catalog-pg-conversion.html">pg_conversion</a></dt><dt id="ientry-idm27034">pg_conversion_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm29185">pg_copy_logical_replication_slot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29161">pg_copy_physical_replication_slot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29135">pg_create_logical_replication_slot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29097">pg_create_physical_replication_slot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm28753">pg_create_restore_point, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm37002">pg_ctl, <a class="indexterm" href="creating-cluster.html">Creating a Database Cluster</a>, <a class="indexterm" href="server-start.html">Starting the Database Server</a>, <a class="indexterm" href="app-pg-ctl.html">pg_ctl</a></dt><dt id="ientry-idm26379">pg_current_logfile, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28051">pg_current_snapshot, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28765">pg_current_wal_flush_lsn, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm28773">pg_current_wal_insert_lsn, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm28781">pg_current_wal_lsn, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm28017">pg_current_xact_id, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28025">pg_current_xact_id_if_assigned, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm135025">pg_cursors, <a class="indexterm" href="view-pg-cursors.html">pg_cursors</a></dt><dt id="ientry-idm46533">pg_database, <a class="indexterm" href="manage-ag-templatedbs.html">Template Databases</a>, <a class="indexterm" href="catalog-pg-database.html">pg_database</a></dt><dt id="ientry-idm29704">pg_database_collation_actual_version, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29509">pg_database_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm130147">pg_db_role_setting, <a class="indexterm" href="catalog-pg-db-role-setting.html">pg_db_role_setting</a></dt><dt id="ientry-idm10156">pg_ddl_command, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm130191">pg_default_acl, <a class="indexterm" href="catalog-pg-default-acl.html">pg_default_acl</a></dt><dt id="ientry-idm130260">pg_depend, <a class="indexterm" href="catalog-pg-depend.html">pg_depend</a></dt><dt id="ientry-idm27846">pg_describe_object, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm130413">pg_description, <a class="indexterm" href="catalog-pg-description.html">pg_description</a></dt><dt id="ientry-idm29123">pg_drop_replication_slot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm117788">pg_dump, <a class="indexterm" href="app-pgdump.html">pg_dump</a></dt><dt id="ientry-idm37844">pg_dumpall, <a class="indexterm" href="app-pg-dumpall.html">pg_dumpall</a></dt><dd><dl><dt>use during upgrade, <a class="indexterm" href="upgrading.html#UPGRADING-VIA-PGDUMPALL">Upgrading Data via pg_dumpall</a></dt></dl></dd><dt id="ientry-idm27196">pg_encoding_to_char, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm130467">pg_enum, <a class="indexterm" href="catalog-pg-enum.html">pg_enum</a></dt><dt id="ientry-idm130520">pg_event_trigger, <a class="indexterm" href="catalog-pg-event-trigger.html">pg_event_trigger</a></dt><dt id="ientry-idm30363">pg_event_trigger_ddl_commands, <a class="indexterm" href="functions-event-triggers.html#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS">Capturing Changes at Command End</a></dt><dt id="ientry-idm30438">pg_event_trigger_dropped_objects, <a class="indexterm" href="functions-event-triggers.html#PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS">Processing Objects Dropped by a DDL Command</a></dt><dt id="ientry-idm30552">pg_event_trigger_table_rewrite_oid, <a class="indexterm" href="functions-event-triggers.html#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS">Handling a Table Rewrite Event</a></dt><dt id="ientry-idm30560">pg_event_trigger_table_rewrite_reason, <a class="indexterm" href="functions-event-triggers.html#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS">Handling a Table Rewrite Event</a></dt><dt id="ientry-idm29060">pg_export_snapshot, <a class="indexterm" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION">Snapshot Synchronization Functions</a></dt><dt id="ientry-idm130594">pg_extension, <a class="indexterm" href="catalog-pg-extension.html">pg_extension</a></dt><dt id="ientry-idm76323">pg_extension_config_dump, <a class="indexterm" href="extend-extensions.html#EXTEND-EXTENSIONS-CONFIG-TABLES">Extension Configuration Tables</a></dt><dt id="ientry-idm29667">pg_filenode_relation, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm163407">pg_file_rename, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm135104">pg_file_settings, <a class="indexterm" href="view-pg-file-settings.html">pg_file_settings</a></dt><dt id="ientry-idm163401">pg_file_sync, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm163421">pg_file_unlink, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm163393">pg_file_write, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm130678">pg_foreign_data_wrapper, <a class="indexterm" href="catalog-pg-foreign-data-wrapper.html">pg_foreign_data_wrapper</a></dt><dt id="ientry-idm130748">pg_foreign_server, <a class="indexterm" href="catalog-pg-foreign-server.html">pg_foreign_server</a></dt><dt id="ientry-idm130821">pg_foreign_table, <a class="indexterm" href="catalog-pg-foreign-table.html">pg_foreign_table</a></dt><dt id="ientry-idm169177">pg_freespace, <a class="indexterm" href="pgfreespacemap.html#id-1.11.7.38.5">Functions</a></dt><dt id="ientry-idm169161">pg_freespacemap, <a class="indexterm" href="pgfreespacemap.html">pg_freespacemap</a></dt><dt id="ientry-idm27044">pg_function_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27206">pg_get_catalog_foreign_keys, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27233">pg_get_constraintdef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27246">pg_get_expr, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27261">pg_get_functiondef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27273">pg_get_function_arguments, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27284">pg_get_function_identity_arguments, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27295">pg_get_function_result, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27308">pg_get_indexdef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27324">pg_get_keywords, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27915">pg_get_object_address, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27356">pg_get_ruledef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27369">pg_get_serial_sequence, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27389">pg_get_statisticsobjdef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27399">pg_get_triggerdef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27412">pg_get_userbyid, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27422">pg_get_viewdef, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28976">pg_get_wal_replay_pause_state, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm28942">pg_get_wal_resource_managers, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm135180">pg_group, <a class="indexterm" href="view-pg-group.html">pg_group</a></dt><dt id="ientry-idm26830">pg_has_role, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm44892">pg_hba.conf, <a class="indexterm" href="auth-pg-hba-conf.html">The pg_hba.conf File</a></dt><dt id="ientry-idm135226">pg_hba_file_rules, <a class="indexterm" href="view-pg-hba-file-rules.html">pg_hba_file_rules</a></dt><dt id="ientry-idm45294">pg_ident.conf, <a class="indexterm" href="auth-username-maps.html">User Name Maps</a></dt><dt id="ientry-idm27862">pg_identify_object, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27891">pg_identify_object_as_address, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm135312">pg_ident_file_mappings, <a class="indexterm" href="view-pg-ident-file-mappings.html">pg_ident_file_mappings</a></dt><dt id="ientry-idm29716">pg_import_system_collations, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm130868">pg_index, <a class="indexterm" href="catalog-pg-index.html">pg_index</a></dt><dt id="ientry-idm27489">pg_indexam_has_property, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm135372">pg_indexes, <a class="indexterm" href="view-pg-indexes.html">pg_indexes</a></dt><dt id="ientry-idm29524">pg_indexes_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm27459">pg_index_column_has_property, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27475">pg_index_has_property, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131062">pg_inherits, <a class="indexterm" href="catalog-pg-inherits.html">pg_inherits</a></dt><dt id="ientry-idm131112">pg_init_privs, <a class="indexterm" href="catalog-pg-init-privs.html">pg_init_privs</a></dt><dt id="ientry-idm119165">pg_isready, <a class="indexterm" href="app-pg-isready.html">pg_isready</a></dt><dt id="ientry-idm28906">pg_is_in_recovery, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm26419">pg_is_other_temp_schema, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28968">pg_is_wal_replay_paused, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm26428">pg_jit_available, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131183">pg_language, <a class="indexterm" href="catalog-pg-language.html">pg_language</a></dt><dt id="ientry-idm131273">pg_largeobject, <a class="indexterm" href="catalog-pg-largeobject.html">pg_largeobject</a></dt><dt id="ientry-idm131326">pg_largeobject_metadata, <a class="indexterm" href="catalog-pg-largeobject-metadata.html">pg_largeobject_metadata</a></dt><dt id="ientry-idm28266">pg_last_committed_xact, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28914">pg_last_wal_receive_lsn, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm28923">pg_last_wal_replay_lsn, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm28932">pg_last_xact_replay_timestamp, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm26440">pg_listening_channels, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm135432">pg_locks, <a class="indexterm" href="view-pg-locks.html">pg_locks</a></dt><dt id="ientry-idm163426">pg_logdir_ls, <a class="indexterm" href="adminpack.html">adminpack</a></dt><dt id="ientry-idm29449">pg_logical_emit_message, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29264">pg_logical_slot_get_binary_changes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29212">pg_logical_slot_get_changes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29289">pg_logical_slot_peek_binary_changes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29240">pg_logical_slot_peek_changes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm28657">pg_log_backend_memory_contexts, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt><dt id="ientry-idm10105">pg_lsn, <a class="indexterm" href="datatype-pg-lsn.html">pg_lsn Type</a></dt><dt id="ientry-idm29977">pg_ls_archive_statusdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29870">pg_ls_dir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29891">pg_ls_logdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29923">pg_ls_logicalmapdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29940">pg_ls_logicalsnapdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29957">pg_ls_replslotdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29994">pg_ls_tmpdir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm29907">pg_ls_waldir, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm135628">pg_matviews, <a class="indexterm" href="view-pg-matviews.html">pg_matviews</a></dt><dt id="ientry-idm30577">pg_mcv_list_items, <a class="indexterm" href="functions-statistics.html#FUNCTIONS-STATISTICS-MCV">Inspecting MCV Lists</a></dt><dt id="ientry-idm26411">pg_my_temp_schema, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131367">pg_namespace, <a class="indexterm" href="catalog-pg-namespace.html">pg_namespace</a></dt><dt id="ientry-idm26448">pg_notification_queue_usage, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm109144">pg_notify, <a class="indexterm" href="sql-notify.html#id-1.9.3.158.7.5">pg_notify</a></dt><dt id="ientry-idm131412">pg_opclass, <a class="indexterm" href="catalog-pg-opclass.html">pg_opclass</a></dt><dt id="ientry-idm27054">pg_opclass_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131512">pg_operator, <a class="indexterm" href="catalog-pg-operator.html">pg_operator</a></dt><dt id="ientry-idm27064">pg_operator_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131657">pg_opfamily, <a class="indexterm" href="catalog-pg-opfamily.html">pg_opfamily</a></dt><dt id="ientry-idm27074">pg_opfamily_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27503">pg_options_to_table, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm131724">pg_parameter_acl, <a class="indexterm" href="catalog-pg-parameter-acl.html">pg_parameter_acl</a></dt><dt id="ientry-idm131763">pg_partitioned_table, <a class="indexterm" href="catalog-pg-partitioned-table.html">pg_partitioned_table</a></dt><dt id="ientry-idm29760">pg_partition_ancestors, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29769">pg_partition_root, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29743">pg_partition_tree, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm135702">pg_policies, <a class="indexterm" href="view-pg-policies.html">pg_policies</a></dt><dt id="ientry-idm131856">pg_policy, <a class="indexterm" href="catalog-pg-policy.html">pg_policy</a></dt><dt id="ientry-idm26458">pg_postmaster_start_time, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm135776">pg_prepared_statements, <a class="indexterm" href="view-pg-prepared-statements.html">pg_prepared_statements</a></dt><dt id="ientry-idm135849">pg_prepared_xacts, <a class="indexterm" href="view-pg-prepared-xacts.html">pg_prepared_xacts</a></dt><dt id="ientry-idm169205">pg_prewarm, <a class="indexterm" href="pgprewarm.html">pg_prewarm</a></dt><dt id="ientry-idm169244">pg_prewarm.autoprewarm configuration parameter, <a class="indexterm" href="pgprewarm.html#id-1.11.7.39.5">Configuration Parameters</a></dt><dt id="ientry-idm169254">pg_prewarm.autoprewarm_interval configuration parameter, <a class="indexterm" href="pgprewarm.html#id-1.11.7.39.5">Configuration Parameters</a></dt><dt id="ientry-idm131944">pg_proc, <a class="indexterm" href="catalog-pg-proc.html">pg_proc</a></dt><dt id="ientry-idm28987">pg_promote, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm132233">pg_publication, <a class="indexterm" href="catalog-pg-publication.html">pg_publication</a></dt><dt id="ientry-idm132312">pg_publication_namespace, <a class="indexterm" href="catalog-pg-publication-namespace.html">pg_publication_namespace</a></dt><dt id="ientry-idm132353">pg_publication_rel, <a class="indexterm" href="catalog-pg-publication-rel.html">pg_publication_rel</a></dt><dt id="ientry-idm135907">pg_publication_tables, <a class="indexterm" href="view-pg-publication-tables.html">pg_publication_tables</a></dt><dt id="ientry-idm132412">pg_range, <a class="indexterm" href="catalog-pg-range.html">pg_range</a></dt><dt id="ientry-idm30040">pg_read_binary_file, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm30016">pg_read_file, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm119315">pg_receivewal, <a class="indexterm" href="app-pgreceivewal.html">pg_receivewal</a></dt><dt id="ientry-idm175616">pg_receivexlog, <a class="indexterm" href="app-pgreceivexlog.html">pg_receivexlog renamed to pg_receivewal</a> (see <a href="#ientry-idm119315">pg_receivewal</a>)</dt><dt id="ientry-idm119636">pg_recvlogical, <a class="indexterm" href="app-pgrecvlogical.html">pg_recvlogical</a></dt><dt id="ientry-idm29641">pg_relation_filenode, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29656">pg_relation_filepath, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29533">pg_relation_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm28670">pg_reload_conf, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt><dt id="ientry-idm170178">pg_relpages, <a class="indexterm" href="pgstattuple.html#id-1.11.7.42.5">Functions</a></dt><dt id="ientry-idm132500">pg_replication_origin, <a class="indexterm" href="catalog-pg-replication-origin.html">pg_replication_origin</a></dt><dt id="ientry-idm29424">pg_replication_origin_advance, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29331">pg_replication_origin_create, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29341">pg_replication_origin_drop, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29351">pg_replication_origin_oid, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29436">pg_replication_origin_progress, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29382">pg_replication_origin_session_is_setup, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29390">pg_replication_origin_session_progress, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29373">pg_replication_origin_session_reset, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29362">pg_replication_origin_session_setup, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm135970">pg_replication_origin_status, <a class="indexterm" href="view-pg-replication-origin-status.html">pg_replication_origin_status</a></dt><dt id="ientry-idm29415">pg_replication_origin_xact_reset, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm29401">pg_replication_origin_xact_setup, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm136019">pg_replication_slots, <a class="indexterm" href="view-pg-replication-slots.html">pg_replication_slots</a></dt><dt id="ientry-idm29314">pg_replication_slot_advance, <a class="indexterm" href="functions-admin.html#FUNCTIONS-REPLICATION">Replication Management Functions</a></dt><dt id="ientry-idm125783">pg_resetwal, <a class="indexterm" href="app-pgresetwal.html">pg_resetwal</a></dt><dt id="ientry-idm175601">pg_resetxlog, <a class="indexterm" href="app-pgresetxlog.html">pg_resetxlog renamed to pg_resetwal</a> (see <a href="#ientry-idm125783">pg_resetwal</a>)</dt><dt id="ientry-idm119931">pg_restore, <a class="indexterm" href="app-pgrestore.html">pg_restore</a></dt><dt id="ientry-idm126023">pg_rewind, <a class="indexterm" href="app-pgrewind.html">pg_rewind</a></dt><dt id="ientry-idm132533">pg_rewrite, <a class="indexterm" href="catalog-pg-rewrite.html">pg_rewrite</a></dt><dt id="ientry-idm136168">pg_roles, <a class="indexterm" href="view-pg-roles.html">pg_roles</a></dt><dt id="ientry-idm28687">pg_rotate_logfile, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt><dt id="ientry-idm136270">pg_rules, <a class="indexterm" href="view-pg-rules.html">pg_rules</a></dt><dt id="ientry-idm26466">pg_safe_snapshot_blocking_pids, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm132619">pg_seclabel, <a class="indexterm" href="catalog-pg-seclabel.html">pg_seclabel</a></dt><dt id="ientry-idm136327">pg_seclabels, <a class="indexterm" href="view-pg-seclabels.html">pg_seclabels</a></dt><dt id="ientry-idm132677">pg_sequence, <a class="indexterm" href="catalog-pg-sequence.html">pg_sequence</a></dt><dt id="ientry-idm136408">pg_sequences, <a class="indexterm" href="view-pg-sequences.html">pg_sequences</a></dt><dt id="ientry-idm61981">pg_service.conf, <a class="indexterm" href="libpq-pgservice.html">The Connection Service File</a></dt><dt id="ientry-idm136505">pg_settings, <a class="indexterm" href="view-pg-settings.html">pg_settings</a></dt><dt id="ientry-idm27521">pg_settings_get_flags, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm136726">pg_shadow, <a class="indexterm" href="view-pg-shadow.html">pg_shadow</a></dt><dt id="ientry-idm132752">pg_shdepend, <a class="indexterm" href="catalog-pg-shdepend.html">pg_shdepend</a></dt><dt id="ientry-idm132864">pg_shdescription, <a class="indexterm" href="catalog-pg-shdescription.html">pg_shdescription</a></dt><dt id="ientry-idm136814">pg_shmem_allocations, <a class="indexterm" href="view-pg-shmem-allocations.html">pg_shmem_allocations</a></dt><dt id="ientry-idm132912">pg_shseclabel, <a class="indexterm" href="catalog-pg-shseclabel.html">pg_shseclabel</a></dt><dt id="ientry-idm29564">pg_size_bytes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm29574">pg_size_pretty, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm18270">pg_sleep, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">Delaying Execution</a></dt><dt id="ientry-idm18272">pg_sleep_for, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">Delaying Execution</a></dt><dt id="ientry-idm18274">pg_sleep_until, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">Delaying Execution</a></dt><dt id="ientry-idm28060">pg_snapshot_xip, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28069">pg_snapshot_xmax, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28079">pg_snapshot_xmin, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm51360">pg_statio_all_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-INDEXES-VIEW">pg_statio_all_indexes</a></dt><dt id="ientry-idm51382">pg_statio_all_sequences, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-SEQUENCES-VIEW">pg_statio_all_sequences</a></dt><dt id="ientry-idm51338">pg_statio_all_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-TABLES-VIEW">pg_statio_all_tables</a></dt><dt id="ientry-idm51368">pg_statio_sys_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51390">pg_statio_sys_sequences, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51346">pg_statio_sys_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51375">pg_statio_user_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51397">pg_statio_user_sequences, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51353">pg_statio_user_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm34627">pg_statistic, <a class="indexterm" href="planner-stats.html#id-1.5.13.5.3">Single-Column Statistics</a>, <a class="indexterm" href="catalog-pg-statistic.html">pg_statistic</a></dt><dt id="ientry-idm27084">pg_statistics_obj_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm34674">pg_statistic_ext, <a class="indexterm" href="planner-stats.html#PLANNER-STATS-EXTENDED">Extended Statistics</a>, <a class="indexterm" href="catalog-pg-statistic-ext.html">pg_statistic_ext</a></dt><dt id="ientry-idm34676">pg_statistic_ext_data, <a class="indexterm" href="planner-stats.html#PLANNER-STATS-EXTENDED">Extended Statistics</a>, <a class="indexterm" href="catalog-pg-statistic-ext.html">pg_statistic_ext</a></dt><dt id="ientry-idm34639">pg_stats, <a class="indexterm" href="planner-stats.html#id-1.5.13.5.3">Single-Column Statistics</a>, <a class="indexterm" href="view-pg-stats.html">pg_stats</a></dt><dt id="ientry-idm136997">pg_stats_ext, <a class="indexterm" href="view-pg-stats-ext.html">pg_stats_ext</a></dt><dt id="ientry-idm137145">pg_stats_ext_exprs, <a class="indexterm" href="view-pg-stats-ext-exprs.html">pg_stats_ext_exprs</a></dt><dt id="ientry-idm51118">pg_stat_activity, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW">pg_stat_activity</a></dt><dt id="ientry-idm51316">pg_stat_all_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-ALL-INDEXES-VIEW">pg_stat_all_indexes</a></dt><dt id="ientry-idm51271">pg_stat_all_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW">pg_stat_all_tables</a></dt><dt id="ientry-idm51231">pg_stat_archiver, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-ARCHIVER-VIEW">pg_stat_archiver</a></dt><dt id="ientry-idm51239">pg_stat_bgwriter, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-BGWRITER-VIEW">pg_stat_bgwriter</a></dt><dt id="ientry-idm54612">pg_stat_clear_snapshot, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm51255">pg_stat_database, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW">pg_stat_database</a></dt><dt id="ientry-idm51263">pg_stat_database_conflicts, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW">pg_stat_database_conflicts</a></dt><dt id="ientry-idm30065">pg_stat_file, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">Generic File Access Functions</a></dt><dt id="ientry-idm54570">pg_stat_get_activity, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54737">pg_stat_get_backend_activity, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54746">pg_stat_get_backend_activity_start, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54755">pg_stat_get_backend_client_addr, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54764">pg_stat_get_backend_client_port, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54773">pg_stat_get_backend_dbid, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54729">pg_stat_get_backend_idset, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54782">pg_stat_get_backend_pid, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54791">pg_stat_get_backend_start, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54800">pg_stat_get_backend_userid, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54819">pg_stat_get_backend_wait_event, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54809">pg_stat_get_backend_wait_event_type, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54830">pg_stat_get_backend_xact_start, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54581">pg_stat_get_snapshot_timestamp, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54591">pg_stat_get_xact_blocks_fetched, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54602">pg_stat_get_xact_blocks_hit, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm51166">pg_stat_gssapi, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-GSSAPI-VIEW">pg_stat_gssapi</a></dt><dt id="ientry-idm51174">pg_stat_progress_analyze, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING">ANALYZE Progress Reporting</a></dt><dt id="ientry-idm51208">pg_stat_progress_basebackup, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING">Base Backup Progress Reporting</a></dt><dt id="ientry-idm51199">pg_stat_progress_cluster, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING">CLUSTER Progress Reporting</a></dt><dt id="ientry-idm51215">pg_stat_progress_copy, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#COPY-PROGRESS-REPORTING">COPY Progress Reporting</a></dt><dt id="ientry-idm51182">pg_stat_progress_create_index, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING">CREATE INDEX Progress Reporting</a></dt><dt id="ientry-idm51191">pg_stat_progress_vacuum, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="progress-reporting.html#VACUUM-PROGRESS-REPORTING">VACUUM Progress Reporting</a></dt><dt id="ientry-idm51142">pg_stat_recovery_prefetch, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-RECOVERY-PREFETCH">pg_stat_recovery_prefetch</a></dt><dt id="ientry-idm51126">pg_stat_replication, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW">pg_stat_replication</a></dt><dt id="ientry-idm51429">pg_stat_replication_slots, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW">pg_stat_replication_slots</a></dt><dt id="ientry-idm54620">pg_stat_reset, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54686">pg_stat_reset_replication_slot, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54629">pg_stat_reset_shared, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54657">pg_stat_reset_single_function_counters, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54647">pg_stat_reset_single_table_counters, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54667">pg_stat_reset_slru, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm54697">pg_stat_reset_subscription_stats, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">Statistics Functions</a></dt><dt id="ientry-idm51421">pg_stat_slru, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-SLRU-VIEW">pg_stat_slru</a></dt><dt id="ientry-idm51158">pg_stat_ssl, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW">pg_stat_ssl</a></dt><dt id="ientry-idm169357">pg_stat_statements, <a class="indexterm" href="pgstatstatements.html">pg_stat_statements</a></dt><dd><dl><dt>function, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.8">Functions</a></dt></dl></dd><dt id="ientry-idm169799">pg_stat_statements.max configuration parameter, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.9">Configuration Parameters</a></dt><dt id="ientry-idm169853">pg_stat_statements.save configuration parameter, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.9">Configuration Parameters</a></dt><dt id="ientry-idm169811">pg_stat_statements.track configuration parameter, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.9">Configuration Parameters</a></dt><dt id="ientry-idm169841">pg_stat_statements.track_planning configuration parameter, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.9">Configuration Parameters</a></dt><dt id="ientry-idm169825">pg_stat_statements.track_utility configuration parameter, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.9">Configuration Parameters</a></dt><dt id="ientry-idm169725">pg_stat_statements_info, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.7">The pg_stat_statements_info View</a></dt><dt id="ientry-idm169762">pg_stat_statements_reset, <a class="indexterm" href="pgstatstatements.html#id-1.11.7.41.8">Functions</a></dt><dt id="ientry-idm51150">pg_stat_subscription, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION">pg_stat_subscription</a></dt><dt id="ientry-idm51437">pg_stat_subscription_stats, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION-STATS">pg_stat_subscription_stats</a></dt><dt id="ientry-idm51324">pg_stat_sys_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51279">pg_stat_sys_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51404">pg_stat_user_functions, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-USER-FUNCTIONS-VIEW">pg_stat_user_functions</a></dt><dt id="ientry-idm51331">pg_stat_user_indexes, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51286">pg_stat_user_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51247">pg_stat_wal, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-VIEW">pg_stat_wal</a></dt><dt id="ientry-idm51134">pg_stat_wal_receiver, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a>, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-RECEIVER-VIEW">pg_stat_wal_receiver</a></dt><dt id="ientry-idm51293">pg_stat_xact_all_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51302">pg_stat_xact_sys_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51412">pg_stat_xact_user_functions, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm51309">pg_stat_xact_user_tables, <a class="indexterm" href="monitoring-stats.html#MONITORING-STATS-VIEWS">Viewing Statistics</a></dt><dt id="ientry-idm133299">pg_subscription, <a class="indexterm" href="catalog-pg-subscription.html">pg_subscription</a></dt><dt id="ientry-idm133419">pg_subscription_rel, <a class="indexterm" href="catalog-pg-subscription-rel.html">pg_subscription_rel</a></dt><dt id="ientry-idm170283">pg_surgery, <a class="indexterm" href="pgsurgery.html">pg_surgery</a></dt><dt id="ientry-idm28833">pg_switch_wal, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm137304">pg_tables, <a class="indexterm" href="view-pg-tables.html">pg_tables</a></dt><dt id="ientry-idm133478">pg_tablespace, <a class="indexterm" href="catalog-pg-tablespace.html">pg_tablespace</a></dt><dt id="ientry-idm27533">pg_tablespace_databases, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27545">pg_tablespace_location, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm29597">pg_tablespace_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm27094">pg_table_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm29588">pg_table_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm43024">pg_temp, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dd><dl><dt>securing functions, <a class="indexterm" href="sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY">Writing SECURITY DEFINER Functions Safely</a></dt></dl></dd><dt id="ientry-idm28695">pg_terminate_backend, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt><dt id="ientry-idm126258">pg_test_fsync, <a class="indexterm" href="pgtestfsync.html">pg_test_fsync</a></dt><dt id="ientry-idm126336">pg_test_timing, <a class="indexterm" href="pgtesttiming.html">pg_test_timing</a></dt><dt id="ientry-idm137393">pg_timezone_abbrevs, <a class="indexterm" href="view-pg-timezone-abbrevs.html">pg_timezone_abbrevs</a></dt><dt id="ientry-idm137431">pg_timezone_names, <a class="indexterm" href="view-pg-timezone-names.html">pg_timezone_names</a></dt><dt id="ientry-idm29612">pg_total_relation_size, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">Database Object Management Functions</a></dt><dt id="ientry-idm133533">pg_transform, <a class="indexterm" href="catalog-pg-transform.html">pg_transform</a></dt><dt id="ientry-idm170314">pg_trgm, <a class="indexterm" href="pgtrgm.html">pg_trgm</a></dt><dt id="ientry-idm170565">pg_trgm.similarity_threshold configuration parameter, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.7">GUC Parameters</a></dt><dt id="ientry-idm170586">pg_trgm.strict_word_similarity_threshold configuration parameter, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.7">GUC Parameters</a></dt><dt id="ientry-idm170575">pg_trgm.word_similarity_threshold configuration parameter, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.7">GUC Parameters</a></dt><dt id="ientry-idm133593">pg_trigger, <a class="indexterm" href="catalog-pg-trigger.html">pg_trigger</a></dt><dt id="ientry-idm26480">pg_trigger_depth, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm30221">pg_try_advisory_lock, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30240">pg_try_advisory_lock_shared, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30259">pg_try_advisory_xact_lock, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm30278">pg_try_advisory_xact_lock_shared, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">Advisory Lock Functions</a></dt><dt id="ientry-idm133780">pg_ts_config, <a class="indexterm" href="catalog-pg-ts-config.html">pg_ts_config</a></dt><dt id="ientry-idm27104">pg_ts_config_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm133842">pg_ts_config_map, <a class="indexterm" href="catalog-pg-ts-config-map.html">pg_ts_config_map</a></dt><dt id="ientry-idm133895">pg_ts_dict, <a class="indexterm" href="catalog-pg-ts-dict.html">pg_ts_dict</a></dt><dt id="ientry-idm27114">pg_ts_dict_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm133961">pg_ts_parser, <a class="indexterm" href="catalog-pg-ts-parser.html">pg_ts_parser</a></dt><dt id="ientry-idm27124">pg_ts_parser_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm134047">pg_ts_template, <a class="indexterm" href="catalog-pg-ts-template.html">pg_ts_template</a></dt><dt id="ientry-idm27134">pg_ts_template_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm134106">pg_type, <a class="indexterm" href="catalog-pg-type.html">pg_type</a></dt><dt id="ientry-idm27555">pg_typeof, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27144">pg_type_is_visible, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm126427">pg_upgrade, <a class="indexterm" href="pgupgrade.html">pg_upgrade</a></dt><dt id="ientry-idm137477">pg_user, <a class="indexterm" href="view-pg-user.html">pg_user</a></dt><dt id="ientry-idm134547">pg_user_mapping, <a class="indexterm" href="catalog-pg-user-mapping.html">pg_user_mapping</a></dt><dt id="ientry-idm137552">pg_user_mappings, <a class="indexterm" href="view-pg-user-mappings.html">pg_user_mappings</a></dt><dt id="ientry-idm120563">pg_verifybackup, <a class="indexterm" href="app-pgverifybackup.html">pg_verifybackup</a></dt><dt id="ientry-idm137631">pg_views, <a class="indexterm" href="view-pg-views.html">pg_views</a></dt><dt id="ientry-idm170679">pg_visibility, <a class="indexterm" href="pgvisibility.html">pg_visibility</a></dt><dt id="ientry-idm28089">pg_visible_in_snapshot, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm126920">pg_waldump, <a class="indexterm" href="pgwaldump.html">pg_waldump</a></dt><dt id="ientry-idm28843">pg_walfile_name, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm28853">pg_walfile_name_offset, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm170743">pg_walinspect, <a class="indexterm" href="pgwalinspect.html">pg_walinspect</a></dt><dt id="ientry-idm28867">pg_wal_lsn_diff, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">Backup Control Functions</a></dt><dt id="ientry-idm29013">pg_wal_replay_pause, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm29024">pg_wal_replay_resume, <a class="indexterm" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">Recovery Control Functions</a></dt><dt id="ientry-idm28244">pg_xact_commit_timestamp, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28253">pg_xact_commit_timestamp_origin, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28034">pg_xact_status, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm175586">pg_xlogdump, <a class="indexterm" href="pgxlogdump.html">pg_xlogdump renamed to pg_waldump</a> (see <a href="#ientry-idm126920">pg_waldump</a>)</dt><dt id="ientry-idm33554">phantom read, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a></dt><dt id="ientry-idm20046">phraseto_tsquery, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES">Parsing Queries</a></dt><dt id="ientry-idm11447">pi, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm74505">PIC, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt id="ientry-idm59004">PID</dt><dd><dl><dt>determining PID of server process</dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt></dl></dd></dl></dd><dt id="ientry-idm60368">pipelining, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a>, <a class="indexterm" href="protocol-flow.html#PROTOCOL-FLOW-PIPELINING">Pipelining</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-pipeline-mode.html">Pipeline Mode</a></dt><dt>protocol specification, <a class="indexterm" href="protocol-flow.html#PROTOCOL-FLOW-PIPELINING">Pipelining</a></dt></dl></dd><dt id="ientry-idm49691">PITR, <a class="indexterm" href="backup.html">Backup and Restore</a></dt><dt id="ientry-idm50313">PITR standby, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm35744">pkg-config, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a></dt><dd><dl><dt>with
+ ecpg, <a class="indexterm" href="ecpg-process.html">Processing Embedded SQL Programs</a></dt><dt>with
+ libpq, <a class="indexterm" href="libpq-build.html">Building libpq Programs</a></dt></dl></dd><dt id="ientry-idm82704">PL/Perl, <a class="indexterm" href="plperl.html">PL/Perl — Perl Procedural Language</a></dt><dt id="ientry-idm83162">PL/PerlU, <a class="indexterm" href="plperl-trusted.html">Trusted and Untrusted PL/Perl</a></dt><dt id="ientry-idm79577">PL/pgSQL, <a class="indexterm" href="plpgsql.html">PL/pgSQL — SQL Procedural Language</a></dt><dt id="ientry-idm83399">PL/Python, <a class="indexterm" href="plpython.html">PL/Python — Python Procedural Language</a></dt><dt id="ientry-idm81989">PL/SQL (Oracle), <a class="indexterm" href="plpgsql-porting.html">Porting from Oracle PL/SQL</a></dt><dd><dl><dt>porting to PL/pgSQL, <a class="indexterm" href="plpgsql-porting.html">Porting from Oracle PL/SQL</a></dt></dl></dd><dt id="ientry-idm82202">PL/Tcl, <a class="indexterm" href="pltcl.html">PL/Tcl — Tcl Procedural Language</a></dt><dt id="ientry-idm20029">plainto_tsquery, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES">Parsing Queries</a></dt><dt id="ientry-idm41411">plan_cache_mode configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm83325">plperl.on_init configuration parameter, <a class="indexterm" href="plperl-under-the-hood.html#PLPERL-CONFIG">Configuration</a></dt><dt id="ientry-idm83356">plperl.on_plperlu_init configuration parameter, <a class="indexterm" href="plperl-under-the-hood.html#PLPERL-CONFIG">Configuration</a></dt><dt id="ientry-idm83350">plperl.on_plperl_init configuration parameter, <a class="indexterm" href="plperl-under-the-hood.html#PLPERL-CONFIG">Configuration</a></dt><dt id="ientry-idm83372">plperl.use_strict configuration parameter, <a class="indexterm" href="plperl-under-the-hood.html#PLPERL-CONFIG">Configuration</a></dt><dt id="ientry-idm81461">plpgsql.check_asserts configuration parameter, <a class="indexterm" href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">Checking Assertions</a></dt><dt id="ientry-idm81763">plpgsql.variable_conflict configuration parameter, <a class="indexterm" href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST">Variable Substitution</a></dt><dt id="ientry-idm82675">pltcl.start_proc configuration parameter, <a class="indexterm" href="pltcl-config.html">PL/Tcl Configuration</a></dt><dt id="ientry-idm82689">pltclu.start_proc configuration parameter, <a class="indexterm" href="pltcl-config.html">PL/Tcl Configuration</a></dt><dt id="ientry-idm8045">point, <a class="indexterm" href="datatype-geometric.html#id-1.5.7.16.5">Points</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm49689">point-in-time recovery, <a class="indexterm" href="backup.html">Backup and Restore</a></dt><dt id="ientry-idm3505">policy, <a class="indexterm" href="ddl-rowsecurity.html">Row Security Policies</a></dt><dt id="ientry-idm8191">polygon, <a class="indexterm" href="datatype-geometric.html#DATATYPE-POLYGON">Polygons</a>, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm73225">polymorphic function, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a></dt><dt id="ientry-idm73223">polymorphic type, <a class="indexterm" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">Polymorphic Types</a></dt><dt id="ientry-idm13642">popcount (see <a href="#ientry-idm13640">bit_count</a>)</dt><dt id="ientry-idm19086">popen, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm166577">populate_record, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm58301">port, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt><dt id="ientry-idm38602">port configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm12240">position, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm15768">POSITION_REGEX, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a></dt><dt id="ientry-idm110">POSTGRES, <a class="indexterm" href="history.html#HISTORY-BERKELEY">The Berkeley POSTGRES Project</a></dt><dt id="ientry-idm417">postgres, <a class="indexterm" href="tutorial-arch.html">Architectural Fundamentals</a>, <a class="indexterm" href="server-start.html">Starting the Database Server</a>, <a class="indexterm" href="manage-ag-createdb.html">Creating a Database</a>, <a class="indexterm" href="app-postgres.html">postgres</a></dt><dt id="ientry-idm36946">postgres user, <a class="indexterm" href="postgres-user.html">The PostgreSQL User Account</a></dt><dt id="ientry-idm143">Postgres95, <a class="indexterm" href="history.html#HISTORY-POSTGRES95">Postgres95</a></dt><dt id="ientry-idm38361">postgresql.auto.conf, <a class="indexterm" href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE">Parameter Interaction via the Configuration File</a></dt><dt id="ientry-idm38345">postgresql.conf, <a class="indexterm" href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE">Parameter Interaction via the Configuration File</a></dt><dt id="ientry-idm170818">postgres_fdw, <a class="indexterm" href="postgres-fdw.html">postgres_fdw</a></dt><dt id="ientry-idm171292">postgres_fdw.application_name configuration parameter, <a class="indexterm" href="postgres-fdw.html#id-1.11.7.47.18">Configuration Parameters</a></dt><dt id="ientry-idm127616">postmaster, <a class="indexterm" href="app-postmaster.html">postmaster</a></dt><dt id="ientry-idm44440">post_auth_delay configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm11459">power, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm58999">PQbackendPID, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59762">PQbinaryTuples, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dd><dl><dt>with COPY, <a class="indexterm" href="libpq-copy.html">Functions Associated with the COPY Command</a></dt></dl></dd><dt id="ientry-idm60668">PQcancel, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dt id="ientry-idm59626">PQclear, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm61085">PQclientEncoding, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm59858">PQcmdStatus, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">Retrieving Other Result Information</a></dt><dt id="ientry-idm59870">PQcmdTuples, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">Retrieving Other Result Information</a></dt><dt id="ientry-idm57949">PQconndefaults, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57774">PQconnectdb, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57734">PQconnectdbParams, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm59017">PQconnectionNeedsPassword, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59026">PQconnectionUsedPassword, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm57827">PQconnectPoll, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57823">PQconnectStart, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57819">PQconnectStartParams, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57965">PQconninfo, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm61215">PQconninfoFree, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm57979">PQconninfoParse, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm60268">PQconsumeInput, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm61314">PQcopyResult, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm58767">PQdb, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59317">PQdescribePortal, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59295">PQdescribePrepared, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm61258">PQencryptPassword, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm61227">PQencryptPasswordConn, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm61049">PQendcopy, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">Obsolete Functions for COPY</a></dt><dt id="ientry-idm60522">PQenterPipelineMode, <a class="indexterm" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">Functions Associated with Pipeline Mode</a></dt><dt id="ientry-idm58973">PQerrorMessage, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm60073">PQescapeBytea, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm60044">PQescapeByteaConn, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm59964">PQescapeIdentifier, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm59933">PQescapeLiteral, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm60023">PQescapeString, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm59989">PQescapeStringConn, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm59141">PQexec, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59162">PQexecParams, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59281">PQexecPrepared, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm60532">PQexitPipelineMode, <a class="indexterm" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">Functions Associated with Pipeline Mode</a></dt><dt id="ientry-idm59719">PQfformat, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dd><dl><dt>with COPY, <a class="indexterm" href="libpq-copy.html">Functions Associated with the COPY Command</a></dt></dl></dd><dt id="ientry-idm58011">PQfinish, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm61294">PQfireResultCreateEvents, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm60350">PQflush, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm59742">PQfmod, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm60710">PQfn, <a class="indexterm" href="libpq-fastpath.html">The Fast-Path Interface</a></dt><dt id="ientry-idm59665">PQfname, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59677">PQfnumber, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm60656">PQfreeCancel, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dt id="ientry-idm61198">PQfreemem, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm59752">PQfsize, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59695">PQftable, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59710">PQftablecol, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59728">PQftype, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm60636">PQgetCancel, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dt id="ientry-idm60931">PQgetCopyData, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-RECEIVE">Functions for Receiving COPY Data</a></dt><dt id="ientry-idm59797">PQgetisnull, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59810">PQgetlength, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm60972">PQgetline, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">Obsolete Functions for COPY</a></dt><dt id="ientry-idm60990">PQgetlineAsync, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">Obsolete Functions for COPY</a></dt><dt id="ientry-idm60223">PQgetResult, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm59117">PQgetssl, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58130">PQgetSSLKeyPassHook_OpenSSL, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm59776">PQgetvalue, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm58796">PQhost, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58820">PQhostaddr, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm62295">PQinitOpenSSL, <a class="indexterm" href="libpq-ssl.html#LIBPQ-SSL-INITIALIZE">SSL Library Initialization</a></dt><dt id="ientry-idm62314">PQinitSSL, <a class="indexterm" href="libpq-ssl.html#LIBPQ-SSL-INITIALIZE">SSL Library Initialization</a></dt><dt id="ientry-idm61634">PQinstanceData, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-FUNCS">Event Support Functions</a></dt><dt id="ientry-idm60288">PQisBusy, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60341">PQisnonblocking, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm62345">PQisthreadsafe, <a class="indexterm" href="libpq-threading.html">Behavior in Threaded Programs</a></dt><dt id="ientry-idm61391">PQlibVersion, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dd><dl><dt>(see also <a href="#ientry-idm58959">PQserverVersion</a>)</dt></dl></dd><dt id="ientry-idm61271">PQmakeEmptyPGresult, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm59657">PQnfields, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dd><dl><dt>with COPY, <a class="indexterm" href="libpq-copy.html">Functions Associated with the COPY Command</a></dt></dl></dd><dt id="ientry-idm60771">PQnotifies, <a class="indexterm" href="libpq-notify.html">Asynchronous Notification</a></dt><dt id="ientry-idm59823">PQnparams, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59646">PQntuples, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm59917">PQoidStatus, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">Retrieving Other Result Information</a></dt><dt id="ientry-idm59899">PQoidValue, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">Retrieving Other Result Information</a></dt><dt id="ientry-idm58863">PQoptions, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58908">PQparameterStatus, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59833">PQparamtype, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm58783">PQpass, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58087">PQping, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm58056">PQpingParams, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm60489">PQpipelineStatus, <a class="indexterm" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">Functions Associated with Pipeline Mode</a></dt><dt id="ientry-idm60543">PQpipelineSync, <a class="indexterm" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">Functions Associated with Pipeline Mode</a></dt><dt id="ientry-idm58834">PQport, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59243">PQprepare, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59843">PQprint, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">Retrieving Query Result Information</a></dt><dt id="ientry-idm58950">PQprotocolVersion, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm60880">PQputCopyData, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-SEND">Functions for Sending COPY Data</a></dt><dt id="ientry-idm60898">PQputCopyEnd, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-SEND">Functions for Sending COPY Data</a></dt><dt id="ientry-idm61017">PQputline, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">Obsolete Functions for COPY</a></dt><dt id="ientry-idm61038">PQputnbytes, <a class="indexterm" href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">Obsolete Functions for COPY</a></dt><dt id="ientry-idm61601">PQregisterEventProc, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-FUNCS">Event Support Functions</a></dt><dt id="ientry-idm60688">PQrequestCancel, <a class="indexterm" href="libpq-cancel.html">Canceling Queries in Progress</a></dt><dt id="ientry-idm58026">PQreset, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm58039">PQresetPoll, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm58035">PQresetStart, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm59441">PQresStatus, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm61365">PQresultAlloc, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm59487">PQresultErrorField, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59450">PQresultErrorMessage, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm61662">PQresultInstanceData, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-FUNCS">Event Support Functions</a></dt><dt id="ientry-idm61378">PQresultMemorySize, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm61646">PQresultSetInstanceData, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-FUNCS">Event Support Functions</a></dt><dt id="ientry-idm59348">PQresultStatus, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm59469">PQresultVerboseErrorMessage, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-MAIN">Main Functions</a></dt><dt id="ientry-idm60212">PQsendDescribePortal, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60201">PQsendDescribePrepared, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60555">PQsendFlushRequest, <a class="indexterm" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">Functions Associated with Pipeline Mode</a></dt><dt id="ientry-idm60180">PQsendPrepare, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60155">PQsendQuery, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60169">PQsendQueryParams, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm60191">PQsendQueryPrepared, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm58959">PQserverVersion, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm61097">PQsetClientEncoding, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm57807">PQsetdb, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm57787">PQsetdbLogin, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm61130">PQsetErrorContextVisibility, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm61110">PQsetErrorVerbosity, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm61620">PQsetInstanceData, <a class="indexterm" href="libpq-events.html#LIBPQ-EVENTS-FUNCS">Event Support Functions</a></dt><dt id="ientry-idm60322">PQsetnonblocking, <a class="indexterm" href="libpq-async.html">Asynchronous Command Processing</a></dt><dt id="ientry-idm61426">PQsetNoticeProcessor, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt><dt id="ientry-idm61421">PQsetNoticeReceiver, <a class="indexterm" href="libpq-notice-processing.html">Notice Processing</a></dt><dt id="ientry-idm61333">PQsetResultAttrs, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm60611">PQsetSingleRowMode, <a class="indexterm" href="libpq-single-row-mode.html">Retrieving Query Results Row-by-Row</a></dt><dt id="ientry-idm58099">PQsetSSLKeyPassHook_OpenSSL, <a class="indexterm" href="libpq-connect.html">Database Connection Control Functions</a></dt><dt id="ientry-idm61170">PQsetTraceFlags, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm61348">PQsetvalue, <a class="indexterm" href="libpq-misc.html">Miscellaneous Functions</a></dt><dt id="ientry-idm58991">PQsocket, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59045">PQsslAttribute, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59093">PQsslAttributeNames, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59037">PQsslInUse, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm59101">PQsslStruct, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58874">PQstatus, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm61154">PQtrace, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm58894">PQtransactionStatus, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm58852">PQtty, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm60092">PQunescapeBytea, <a class="indexterm" href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">Escaping Strings for Inclusion in SQL Commands</a></dt><dt id="ientry-idm61185">PQuntrace, <a class="indexterm" href="libpq-control.html">Control Functions</a></dt><dt id="ientry-idm58775">PQuser, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt id="ientry-idm33738">predicate locking, <a class="indexterm" href="transaction-iso.html#XACT-SERIALIZABLE">Serializable Isolation Level</a></dt><dt id="ientry-idm109169">PREPARE, <a class="indexterm" href="sql-prepare.html">PREPARE</a></dt><dt id="ientry-idm109284">PREPARE TRANSACTION, <a class="indexterm" href="sql-prepare-transaction.html">PREPARE TRANSACTION</a></dt><dt id="ientry-idm103821">prepared statements, <a class="indexterm" href="sql-deallocate.html">DEALLOCATE</a>, <a class="indexterm" href="sql-execute.html">EXECUTE</a>, <a class="indexterm" href="sql-explain.html">EXPLAIN</a>, <a class="indexterm" href="sql-prepare.html">PREPARE</a></dt><dd><dl><dt>creating, <a class="indexterm" href="sql-prepare.html">PREPARE</a></dt><dt>executing, <a class="indexterm" href="sql-execute.html">EXECUTE</a></dt><dt>removing, <a class="indexterm" href="sql-deallocate.html">DEALLOCATE</a></dt><dt>showing the query plan, <a class="indexterm" href="sql-explain.html">EXPLAIN</a></dt></dl></dd><dt id="ientry-idm81810">preparing a query</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING">Plan Caching</a></dt><dt>in PL/Python, <a class="indexterm" href="plpython-database.html#id-1.8.11.14.3">Database Access Functions</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-dbaccess.html">Database Access from PL/Tcl</a></dt></dl></dd><dt id="ientry-idm44449">pre_auth_delay configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm2716">primary key, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-PRIMARY-KEYS">Primary Keys</a></dt><dt id="ientry-idm40647">primary_conninfo configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40667">primary_slot_name configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm3023">privilege, <a class="indexterm" href="ddl-priv.html">Privileges</a>, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PRIV">Schemas and Privileges</a>, <a class="indexterm" href="rules-privileges.html">Rules and Privileges</a>, <a class="indexterm" href="rules-privileges.html">Rules and Privileges</a></dt><dd><dl><dt>querying, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt>with rules, <a class="indexterm" href="rules-privileges.html">Rules and Privileges</a></dt><dt>for schemas, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PRIV">Schemas and Privileges</a></dt><dt>with views, <a class="indexterm" href="rules-privileges.html">Rules and Privileges</a></dt></dl></dd><dt id="ientry-idm79467">procedural language, <a class="indexterm" href="xplang.html">Procedural Languages</a>, <a class="indexterm" href="plhandler.html">Writing a Procedural Language Handler</a></dt><dd><dl><dt>externally maintained, <a class="indexterm" href="external-pl.html">Procedural Languages</a></dt><dt>handler for, <a class="indexterm" href="plhandler.html">Writing a Procedural Language Handler</a></dt></dl></dd><dt id="ientry-idm73429">procedure, <a class="indexterm" href="xproc.html">User-Defined Procedures</a></dt><dd><dl><dt>user-defined, <a class="indexterm" href="xproc.html">User-Defined Procedures</a></dt></dl></dd><dt id="ientry-idm73658">procedures</dt><dd><dl><dt>output parameter, <a class="indexterm" href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS-PROC">SQL Procedures with Output Parameters</a></dt></dl></dd><dt id="ientry-idm40679">promote_trigger_file configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm137681">protocol, <a class="indexterm" href="protocol.html">Frontend/Backend Protocol</a></dt><dd><dl><dt>frontend-backend, <a class="indexterm" href="protocol.html">Frontend/Backend Protocol</a></dt></dl></dd><dt id="ientry-idm51015">ps, <a class="indexterm" href="monitoring-ps.html">Standard Unix Tools</a></dt><dd><dl><dt>to monitor activity, <a class="indexterm" href="monitoring-ps.html">Standard Unix Tools</a></dt></dl></dd><dt id="ientry-idm490">psql, <a class="indexterm" href="tutorial-accessdb.html">Accessing a Database</a>, <a class="indexterm" href="app-psql.html">psql</a></dt><dt id="ientry-idm83401">Python, <a class="indexterm" href="plpython.html">PL/Python — Python Procedural Language</a></dt></dl></div><div class="indexdiv" id="indexdiv-Q"><h3>Q</h3><dl><dt id="ientry-idm3648">qualified name, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CREATE">Creating a Schema</a></dt><dt id="ientry-idm700">query, <a class="indexterm" href="tutorial-select.html">Querying a Table</a>, <a class="indexterm" href="queries.html">Queries</a></dt><dt id="ientry-idm34383">query plan, <a class="indexterm" href="using-explain.html">Using EXPLAIN</a></dt><dt id="ientry-idm78742">query tree, <a class="indexterm" href="querytree.html">The Query Tree</a></dt><dt id="ientry-idm20084">querytree, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSQUERY">Manipulating Queries</a></dt><dt id="ientry-idm1234">quotation marks</dt><dd><dl><dt>and identifiers, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dt>escaping, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS">String Constants</a></dt></dl></dd><dt id="ientry-idm43969">quote_all_identifiers configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm12646">quote_ident, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt><dt>use in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">Executing Dynamic Commands</a></dt></dl></dd><dt id="ientry-idm12660">quote_literal, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt><dt>use in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">Executing Dynamic Commands</a></dt></dl></dd><dt id="ientry-idm12686">quote_nullable, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">Utility Functions in PL/Perl</a></dt><dt>use in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">Executing Dynamic Commands</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-R"><h3>R</h3><dl><dt id="ientry-idm11483">radians, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm19098">radius, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm45871">RADIUS, <a class="indexterm" href="auth-radius.html">RADIUS Authentication</a></dt><dt id="ientry-idm81317">RAISE</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE">Reporting Errors and Messages</a></dt></dl></dd><dt id="ientry-idm11689">random, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm41092">random_page_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm78768">range table, <a class="indexterm" href="querytree.html">The Query Tree</a></dt><dt id="ientry-idm9619">range type, <a class="indexterm" href="rangetypes.html">Range Types</a></dt><dd><dl><dt>exclude, <a class="indexterm" href="rangetypes.html#RANGETYPES-CONSTRAINT">Constraints on Ranges</a></dt><dt>indexes on, <a class="indexterm" href="rangetypes.html#RANGETYPES-INDEXING">Indexing</a></dt></dl></dd><dt id="ientry-idm24828">range_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24844">range_intersect_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm24401">range_merge, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm25430">rank, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dd><dl><dt>hypothetical, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm33620">read committed, <a class="indexterm" href="transaction-iso.html#XACT-READ-COMMITTED">Read Committed Isolation Level</a></dt><dt id="ientry-idm43173">read-only transaction, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dd><dl><dt>setting, <a class="indexterm" href="sql-set-transaction.html">SET TRANSACTION</a></dt><dt>setting default, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></dd><dt id="ientry-idm35278">readline, <a class="indexterm" href="install-requirements.html">Requirements</a></dt><dt id="ientry-idm123526">Readline</dt><dd><dl><dt>in psql, <a class="indexterm" href="app-psql.html#APP-PSQL-READLINE">Command-Line Editing</a></dt></dl></dd><dt id="ientry-idm138449">READ_REPLICATION_SLOT, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm6369">real, <a class="indexterm" href="datatype-numeric.html#DATATYPE-FLOAT">Floating-Point Types</a></dt><dt id="ientry-idm109371">REASSIGN OWNED, <a class="indexterm" href="sql-reassign-owned.html">REASSIGN OWNED</a></dt><dt id="ientry-idm10124">record, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm175545">recovery.conf, <a class="indexterm" href="recovery-config.html">recovery.conf file merged into postgresql.conf</a></dt><dt id="ientry-idm40253">recovery.signal, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a></dt><dt id="ientry-idm40309">recovery_end_command configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a></dt><dt id="ientry-idm44087">recovery_init_sync_method configuration parameter, <a class="indexterm" href="runtime-config-error-handling.html">Error Handling</a></dt><dt id="ientry-idm40793">recovery_min_apply_delay configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40212">recovery_prefetch configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">Recovery</a></dt><dt id="ientry-idm40333">recovery_target configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40422">recovery_target_action configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40393">recovery_target_inclusive configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40379">recovery_target_lsn configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40344">recovery_target_name configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40354">recovery_target_time configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40408">recovery_target_timeline configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm40369">recovery_target_xid configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">Recovery Target</a></dt><dt id="ientry-idm8131">rectangle, <a class="indexterm" href="datatype-geometric.html#id-1.5.7.16.8">Boxes</a></dt><dt id="ientry-idm5604">RECURSIVE, <a class="indexterm" href="sql-createview.html">CREATE VIEW</a></dt><dd><dl><dt>in common table expressions, <a class="indexterm" href="queries-with.html#QUERIES-WITH-RECURSIVE">Recursive Queries</a></dt><dt>in views, <a class="indexterm" href="sql-createview.html">CREATE VIEW</a></dt></dl></dd><dt id="ientry-idm41425">recursive_worktable_factor configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">Other Planner Options</a></dt><dt id="ientry-idm949">referential integrity, <a class="indexterm" href="tutorial-fk.html">Foreign Keys</a>, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt><dt id="ientry-idm109436">REFRESH MATERIALIZED VIEW, <a class="indexterm" href="sql-refreshmaterializedview.html">REFRESH MATERIALIZED VIEW</a></dt><dt id="ientry-idm9871">regclass, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9873">regcollation, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9875">regconfig, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9877">regdictionary, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm12712">regexp_count, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12734">regexp_instr, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12766">regexp_like, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12786">regexp_match, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12806">regexp_matches, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12828">regexp_replace, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12877">regexp_split_to_array, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12896">regexp_split_to_table, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm12916">regexp_substr, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm9879">regnamespace, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9881">regoper, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9883">regoperator, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9885">regproc, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9887">regprocedure, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm25087">regression intercept, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25117">regression slope, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm35488">regression test, <a class="indexterm" href="install-procedure.html">Installation Procedure</a></dt><dt id="ientry-idm57310">regression tests, <a class="indexterm" href="regress.html">Regression Tests</a></dt><dt id="ientry-idm9889">regrole, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm25042">regr_avgx, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25058">regr_avgy, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25074">regr_count, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25089">regr_intercept, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25104">regr_r2, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25119">regr_slope, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25134">regr_sxx, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25152">regr_sxy, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25172">regr_syy, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm9891">regtype, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm14461">regular expression, <a class="indexterm" href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP">SIMILAR TO Regular Expressions</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dd><dl><dt>(see also <a href="#ientry-idm14358">pattern matching</a>)</dt></dl></dd><dt id="ientry-idm46782">regular expressions</dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm49364">reindex, <a class="indexterm" href="routine-reindex.html">Routine Reindexing</a></dt><dt id="ientry-idm109504">REINDEX, <a class="indexterm" href="sql-reindex.html">REINDEX</a></dt><dt id="ientry-idm123799">reindexdb, <a class="indexterm" href="app-reindexdb.html">reindexdb</a></dt><dt id="ientry-idm603">relation, <a class="indexterm" href="tutorial-concepts.html">Concepts</a></dt><dt id="ientry-idm597">relational database, <a class="indexterm" href="tutorial-concepts.html">Concepts</a></dt><dt id="ientry-idm109764">RELEASE SAVEPOINT, <a class="indexterm" href="sql-release-savepoint.html">RELEASE SAVEPOINT</a></dt><dt id="ientry-idm44727">remove_temp_files_after_crash configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm12947">repeat, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm33701">repeatable read, <a class="indexterm" href="transaction-iso.html#XACT-REPEATABLE-READ">Repeatable Read Isolation Level</a></dt><dt id="ientry-idm12964">replace, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm50071">replication, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm87775">Replication Origins, <a class="indexterm" href="replication-origins.html">Replication Progress Tracking</a></dt><dt id="ientry-idm87773">Replication Progress Tracking, <a class="indexterm" href="replication-origins.html">Replication Progress Tracking</a></dt><dt id="ientry-idm50467">replication slot</dt><dd><dl><dt>logical replication, <a class="indexterm" href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS">Replication Slots</a></dt><dt>streaming replication, <a class="indexterm" href="warm-standby.html#STREAMING-REPLICATION-SLOTS">Replication Slots</a></dt></dl></dd><dt id="ientry-idm81320">reporting errors</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE">Reporting Errors and Messages</a></dt></dl></dd><dt id="ientry-idm109824">RESET, <a class="indexterm" href="sql-reset.html">RESET</a></dt><dt id="ientry-idm56477">restartpoint, <a class="indexterm" href="wal-configuration.html">WAL Configuration</a></dt><dt id="ientry-idm44061">restart_after_crash configuration parameter, <a class="indexterm" href="runtime-config-error-handling.html">Error Handling</a></dt><dt id="ientry-idm40264">restore_command configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a></dt><dt id="ientry-idm2773">RESTRICT, <a class="indexterm" href="ddl-depend.html">Dependency Tracking</a></dt><dd><dl><dt>with DROP, <a class="indexterm" href="ddl-depend.html">Dependency Tracking</a></dt><dt>foreign key action, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-FK">Foreign Keys</a></dt></dl></dd><dt id="ientry-idm34318">retryable error, <a class="indexterm" href="mvcc-serialization-failure-handling.html">Serialization Failure Handling</a></dt><dt id="ientry-idm80401">RETURN NEXT</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#id-1.8.8.8.3.4">RETURN NEXT and RETURN QUERY</a></dt></dl></dd><dt id="ientry-idm80404">RETURN QUERY</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#id-1.8.8.8.3.4">RETURN NEXT and RETURN QUERY</a></dt></dl></dd><dt id="ientry-idm4484">RETURNING, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a></dt><dt id="ientry-idm80037">RETURNING INTO, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">Executing a Command with a Single-Row Result</a></dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">Executing a Command with a Single-Row Result</a></dt></dl></dd><dt id="ientry-idm12984">reverse, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm3032">REVOKE, <a class="indexterm" href="ddl-priv.html">Privileges</a>, <a class="indexterm" href="sql-revoke.html">REVOKE</a></dt><dt id="ientry-idm12996">right, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm4724">right join, <a class="indexterm" href="queries-table-expressions.html#QUERIES-JOIN">Joined Tables</a></dt><dt id="ientry-idm46006">role, <a class="indexterm" href="database-roles.html">Database Roles</a>, <a class="indexterm" href="role-membership.html">Role Membership</a>, <a class="indexterm" href="predefined-roles.html">Predefined Roles</a></dt><dd><dl><dt>applicable, <a class="indexterm" href="infoschema-applicable-roles.html">applicable_roles</a></dt><dt>enabled, <a class="indexterm" href="infoschema-enabled-roles.html">enabled_roles</a></dt><dt>membership in, <a class="indexterm" href="role-membership.html">Role Membership</a></dt><dt>privilege to bypass, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt>privilege to create, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt>privilege to inherit, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt>privilege to initiate replication, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt>privilege to limit connection, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt></dl></dd><dt id="ientry-idm110041">ROLLBACK, <a class="indexterm" href="sql-rollback.html">ROLLBACK</a></dt><dt id="ientry-idm123212">rollback</dt><dd><dl><dt>psql, <a class="indexterm" href="app-psql.html#APP-PSQL-VARIABLES">Variables</a></dt></dl></dd><dt id="ientry-idm110102">ROLLBACK PREPARED, <a class="indexterm" href="sql-rollback-prepared.html">ROLLBACK PREPARED</a></dt><dt id="ientry-idm110151">ROLLBACK TO SAVEPOINT, <a class="indexterm" href="sql-rollback-to.html">ROLLBACK TO SAVEPOINT</a></dt><dt id="ientry-idm5148">ROLLUP, <a class="indexterm" href="queries-table-expressions.html#QUERIES-GROUPING-SETS">GROUPING SETS, CUBE, and ROLLUP</a></dt><dt id="ientry-idm11495">round, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm73455">routine, <a class="indexterm" href="xproc.html">User-Defined Procedures</a></dt><dt id="ientry-idm48916">routine maintenance, <a class="indexterm" href="maintenance.html">Routine Database Maintenance Tasks</a></dt><dt id="ientry-idm613">row, <a class="indexterm" href="tutorial-concepts.html">Concepts</a>, <a class="indexterm" href="ddl-basics.html">Table Basics</a></dt><dt id="ientry-idm2319">ROW, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS">Row Constructors</a></dt><dt id="ientry-idm148515">row estimation, <a class="indexterm" href="row-estimation-examples.html">Row Estimation Examples</a></dt><dd><dl><dt>multivariate, <a class="indexterm" href="multivariate-statistics-examples.html">Multivariate Statistics Examples</a></dt><dt>planner, <a class="indexterm" href="row-estimation-examples.html">Row Estimation Examples</a></dt></dl></dd><dt id="ientry-idm2316">row type, <a class="indexterm" href="rowtypes.html">Composite Types</a></dt><dd><dl><dt>constructor, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS">Row Constructors</a></dt></dl></dd><dt id="ientry-idm3503">row-level security, <a class="indexterm" href="ddl-rowsecurity.html">Row Security Policies</a></dt><dt id="ientry-idm25918">row-wise comparison, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm25549">row_number, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt id="ientry-idm43045">row_security configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm26855">row_security_active, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm21738">row_to_json, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm13014">rpad, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm13037">rtrim, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm78731">rule, <a class="indexterm" href="rules.html">The Rule System</a>, <a class="indexterm" href="rules-views.html">Views and the Rule System</a>, <a class="indexterm" href="rules-views.html#RULES-SELECT">How SELECT Rules Work</a>, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a>, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a>, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a>, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a>, <a class="indexterm" href="rules-triggers.html">Rules Versus Triggers</a></dt><dd><dl><dt>and materialized views, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a></dt><dt>and views, <a class="indexterm" href="rules-views.html">Views and the Rule System</a></dt><dt>for DELETE, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a></dt><dt>for INSERT, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a></dt><dt>for SELECT, <a class="indexterm" href="rules-views.html#RULES-SELECT">How SELECT Rules Work</a></dt><dt>compared with triggers, <a class="indexterm" href="rules-triggers.html">Rules Versus Triggers</a></dt><dt>for UPDATE, <a class="indexterm" href="rules-update.html">Rules on INSERT, UPDATE, and DELETE</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-S"><h3>S</h3><dl><dt id="ientry-idm110225">SAVEPOINT, <a class="indexterm" href="sql-savepoint.html">SAVEPOINT</a></dt><dt id="ientry-idm109766">savepoints, <a class="indexterm" href="sql-release-savepoint.html">RELEASE SAVEPOINT</a>, <a class="indexterm" href="sql-rollback-to.html">ROLLBACK TO SAVEPOINT</a>, <a class="indexterm" href="sql-savepoint.html">SAVEPOINT</a></dt><dd><dl><dt>defining, <a class="indexterm" href="sql-savepoint.html">SAVEPOINT</a></dt><dt>releasing, <a class="indexterm" href="sql-release-savepoint.html">RELEASE SAVEPOINT</a></dt><dt>rolling back, <a class="indexterm" href="sql-rollback-to.html">ROLLBACK TO SAVEPOINT</a></dt></dl></dd><dt id="ientry-idm1747">scalar (see <a href="#ientry-idm1742">expression</a>)</dt><dt id="ientry-idm11532">scale, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm3619">schema, <a class="indexterm" href="ddl-schemas.html">Schemas</a>, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CREATE">Creating a Schema</a>, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PUBLIC">The Public Schema</a>, <a class="indexterm" href="manage-ag-overview.html">Overview</a></dt><dd><dl><dt>creating, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CREATE">Creating a Schema</a></dt><dt>current, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a>, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt>public, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PUBLIC">The Public Schema</a></dt><dt>removing, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CREATE">Creating a Schema</a></dt></dl></dd><dt id="ientry-idm45427">SCRAM, <a class="indexterm" href="auth-password.html">Password Authentication</a></dt><dt id="ientry-idm3693">search path, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a></dt><dd><dl><dt>current, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt>object visibility, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt></dl></dd><dt id="ientry-idm3712">search_path configuration parameter, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a>, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dd><dl><dt>use in securing functions, <a class="indexterm" href="sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY">Writing SECURITY DEFINER Functions Safely</a></dt></dl></dd><dt id="ientry-idm110291">SECURITY LABEL, <a class="indexterm" href="sql-security-label.html">SECURITY LABEL</a></dt><dt id="ientry-idm165756">sec_to_gc, <a class="indexterm" href="earthdistance.html#id-1.11.7.24.7">Cube-Based Earth Distances</a></dt><dt id="ientry-idm171384">seg, <a class="indexterm" href="seg.html">seg</a></dt><dt id="ientry-idm44239">segment_size configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm702">SELECT, <a class="indexterm" href="tutorial-select.html">Querying a Table</a>, <a class="indexterm" href="queries.html">Queries</a>, <a class="indexterm" href="typeconv-select.html">SELECT Output Columns</a>, <a class="indexterm" href="sql-select.html">SELECT</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-select.html">SELECT Output Columns</a></dt><dt>select list, <a class="indexterm" href="queries-select-lists.html">Select Lists</a></dt></dl></dd><dt id="ientry-idm80034">SELECT INTO, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">Executing a Command with a Single-Row Result</a>, <a class="indexterm" href="sql-selectinto.html">SELECT INTO</a></dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">Executing a Command with a Single-Row Result</a></dt></dl></dd><dt id="ientry-idm37262">semaphores, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt id="ientry-idm171637">sepgsql, <a class="indexterm" href="sepgsql.html">sepgsql</a></dt><dt id="ientry-idm171754">sepgsql.debug_audit configuration parameter, <a class="indexterm" href="sepgsql.html#SEPGSQL-PARAMETERS">GUC Parameters</a></dt><dt id="ientry-idm171741">sepgsql.permissive configuration parameter, <a class="indexterm" href="sepgsql.html#SEPGSQL-PARAMETERS">GUC Parameters</a></dt><dt id="ientry-idm6471">sequence, <a class="indexterm" href="functions-sequence.html">Sequence Manipulation Functions</a></dt><dd><dl><dt>and serial type, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt></dl></dd><dt id="ientry-idm41040">sequential scan, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">Planner Method Configuration</a></dt><dt id="ientry-idm41082">seq_page_cost configuration parameter, <a class="indexterm" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">Planner Cost Constants</a></dt><dt id="ientry-idm6458">serial, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm6462">serial2, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm6464">serial4, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm6466">serial8, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm33736">serializable, <a class="indexterm" href="transaction-iso.html#XACT-SERIALIZABLE">Serializable Isolation Level</a></dt><dt id="ientry-idm33513">Serializable Snapshot Isolation, <a class="indexterm" href="mvcc-intro.html">Introduction</a></dt><dt id="ientry-idm33560">serialization anomaly, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a>, <a class="indexterm" href="transaction-iso.html#XACT-SERIALIZABLE">Serializable Isolation Level</a></dt><dt id="ientry-idm34316">serialization failure, <a class="indexterm" href="mvcc-serialization-failure-handling.html">Serialization Failure Handling</a></dt><dt id="ientry-idm41436">server log, <a class="indexterm" href="runtime-config-logging.html">Error Reporting and Logging</a>, <a class="indexterm" href="logfile-maintenance.html">Log File Maintenance</a></dt><dd><dl><dt>log file maintenance, <a class="indexterm" href="logfile-maintenance.html">Log File Maintenance</a></dt></dl></dd><dt id="ientry-idm58642">Server Name Indication, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt><dt id="ientry-idm37917">server spoofing, <a class="indexterm" href="preventing-server-spoofing.html">Preventing Server Spoofing</a></dt><dt id="ientry-idm44251">server_encoding configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44263">server_version configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44273">server_version_num configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm43724">session_preload_libraries configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">Shared Library Preloading</a></dt><dt id="ientry-idm43245">session_replication_role configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm26489">session_user, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28558">SET, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SET">Configuration Settings Functions</a>, <a class="indexterm" href="sql-set.html">SET</a></dt><dt id="ientry-idm112061">SET CONSTRAINTS, <a class="indexterm" href="sql-set-constraints.html">SET CONSTRAINTS</a></dt><dt id="ientry-idm5357">set difference, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm5355">set intersection, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm5359">set operation, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm26087">set returning functions, <a class="indexterm" href="functions-srf.html">Set Returning Functions</a></dt><dd><dl><dt>functions, <a class="indexterm" href="functions-srf.html">Set Returning Functions</a></dt></dl></dd><dt id="ientry-idm112123">SET ROLE, <a class="indexterm" href="sql-set-role.html">SET ROLE</a></dt><dt id="ientry-idm112202">SET SESSION AUTHORIZATION, <a class="indexterm" href="sql-set-session-authorization.html">SET SESSION AUTHORIZATION</a></dt><dt id="ientry-idm112259">SET TRANSACTION, <a class="indexterm" href="sql-set-transaction.html">SET TRANSACTION</a></dt><dt id="ientry-idm5353">set union, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a></dt><dt id="ientry-idm43460">SET XML OPTION, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm11700">setseed, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm23172">setval, <a class="indexterm" href="functions-sequence.html">Sequence Manipulation Functions</a></dt><dt id="ientry-idm20098">setweight, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">Manipulating Documents</a></dt><dd><dl><dt>setweight for specific lexeme(s), <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt></dl></dd><dt id="ientry-idm13786">set_bit, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a></dt><dt id="ientry-idm13805">set_byte, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm28603">set_config, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SET">Configuration Settings Functions</a></dt><dt id="ientry-idm170426">set_limit, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm19708">set_masklen, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm13824">sha224, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm13837">sha256, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm13850">sha384, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm13863">sha512, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm36318">shared library, <a class="indexterm" href="install-post.html#INSTALL-POST-SHLIBS">Shared Libraries</a>, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt id="ientry-idm37260">shared memory, <a class="indexterm" href="kernel-resources.html#SYSVIPC">Shared Memory and Semaphores</a></dt><dt id="ientry-idm39108">shared_buffers configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm44283">shared_memory_size configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm44292">shared_memory_size_in_huge_pages configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm39315">shared_memory_type configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm74810">shared_preload_libraries, <a class="indexterm" href="xfunc-c.html#XFUNC-SHARED-ADDIN">Shared Memory and LWLocks</a></dt><dt id="ientry-idm43742">shared_preload_libraries configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">Shared Library Preloading</a></dt><dt id="ientry-idm27993">shobj_description, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28560">SHOW, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SET">Configuration Settings Functions</a>, <a class="indexterm" href="sql-show.html">SHOW</a>, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm170414">show_limit, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm170384">show_trgm, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm37722">shutdown, <a class="indexterm" href="server-shutdown.html">Shutting Down the Server</a></dt><dt id="ientry-idm38351">SIGHUP, <a class="indexterm" href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE">Parameter Interaction via the Configuration File</a>, <a class="indexterm" href="auth-pg-hba-conf.html">The pg_hba.conf File</a>, <a class="indexterm" href="auth-username-maps.html">User Name Maps</a></dt><dt id="ientry-idm37743">SIGINT, <a class="indexterm" href="server-shutdown.html">Shutting Down the Server</a></dt><dt id="ientry-idm11544">sign, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm28625">signal</dt><dd><dl><dt>backend processes, <a class="indexterm" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">Server Signaling Functions</a></dt></dl></dd><dt id="ientry-idm43577">significant digits, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm37752">SIGQUIT, <a class="indexterm" href="server-shutdown.html">Shutting Down the Server</a></dt><dt id="ientry-idm37734">SIGTERM, <a class="indexterm" href="server-shutdown.html">Shutting Down the Server</a></dt><dt id="ientry-idm14463">SIMILAR TO, <a class="indexterm" href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP">SIMILAR TO Regular Expressions</a></dt><dt id="ientry-idm170374">similarity, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm11886">sin, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11898">sind, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm127443">single-user mode, <a class="indexterm" href="app-postgres.html#id-1.9.5.14.6.5">Options for Single-User Mode</a></dt><dt id="ientry-idm11953">sinh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm166352">skeys, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm18276">sleep, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">Delaying Execution</a></dt><dt id="ientry-idm166481">slice, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm147562">sliced bread (see <a href="#ientry-idm62471">TOAST</a>)</dt><dt id="ientry-idm19110">slope, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm54473">SLRU, <a class="indexterm" href="monitoring-stats.html#MONITORING-PG-STAT-SLRU-VIEW">pg_stat_slru</a></dt><dt id="ientry-idm6226">smallint, <a class="indexterm" href="datatype-numeric.html#DATATYPE-INT">Integer Types</a></dt><dt id="ientry-idm6456">smallserial, <a class="indexterm" href="datatype-numeric.html#DATATYPE-SERIAL">Serial Types</a></dt><dt id="ientry-idm36566">Solaris, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-SOLARIS">Solaris</a></dt><dd><dl><dt>installation on, <a class="indexterm" href="installation-platform-notes.html#INSTALLATION-NOTES-SOLARIS">Solaris</a></dt><dt>shared library, <a class="indexterm" href="xfunc-c.html#DFUNC">Compiling and Linking Dynamically-Loaded Functions</a></dt><dt>start script, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt></dl></dd><dt id="ientry-idm24946">SOME, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a>, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a>, <a class="indexterm" href="functions-comparisons.html">Row and Array Comparisons</a></dt><dt id="ientry-idm166771">sort, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm5423">sorting, <a class="indexterm" href="queries-order.html">Sorting Rows (ORDER BY)</a></dt><dt id="ientry-idm166792">sort_asc, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm166804">sort_desc, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm165997">soundex, <a class="indexterm" href="fuzzystrmatch.html#id-1.11.7.26.6">Soundex</a></dt><dt id="ientry-idm31240">SP-GiST (see <a href="#ientry-idm31131">index</a>)</dt><dt id="ientry-idm84013">SPI, <a class="indexterm" href="spi.html">Server Programming Interface</a>, <a class="indexterm" href="contrib-spi.html">spi</a></dt><dd><dl><dt>examples, <a class="indexterm" href="contrib-spi.html">spi</a></dt></dl></dd><dt id="ientry-idm82970">spi_commit</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm86980">SPI_commit, <a class="indexterm" href="spi-spi-commit.html">SPI_commit</a></dt><dt id="ientry-idm86982">SPI_commit_and_chain, <a class="indexterm" href="spi-spi-commit.html">SPI_commit</a></dt><dt id="ientry-idm84034">SPI_connect, <a class="indexterm" href="spi-spi-connect.html">SPI_connect</a></dt><dt id="ientry-idm84036">SPI_connect_ext, <a class="indexterm" href="spi-spi-connect.html">SPI_connect</a></dt><dt id="ientry-idm86687">SPI_copytuple, <a class="indexterm" href="spi-spi-copytuple.html">SPI_copytuple</a></dt><dt id="ientry-idm82891">spi_cursor_close</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm85909">SPI_cursor_close, <a class="indexterm" href="spi-spi-cursor-close.html">SPI_cursor_close</a></dt><dt id="ientry-idm85686">SPI_cursor_fetch, <a class="indexterm" href="spi-spi-cursor-fetch.html">SPI_cursor_fetch</a></dt><dt id="ientry-idm85651">SPI_cursor_find, <a class="indexterm" href="spi-spi-cursor-find.html">SPI_cursor_find</a></dt><dt id="ientry-idm85737">SPI_cursor_move, <a class="indexterm" href="spi-spi-cursor-move.html">SPI_cursor_move</a></dt><dt id="ientry-idm85337">SPI_cursor_open, <a class="indexterm" href="spi-spi-cursor-open.html">SPI_cursor_open</a></dt><dt id="ientry-idm85412">SPI_cursor_open_with_args, <a class="indexterm" href="spi-spi-cursor-open-with-args.html">SPI_cursor_open_with_args</a></dt><dt id="ientry-idm85516">SPI_cursor_open_with_paramlist, <a class="indexterm" href="spi-spi-cursor-open-with-paramlist.html">SPI_cursor_open_with_paramlist</a></dt><dt id="ientry-idm85574">SPI_cursor_parse_open, <a class="indexterm" href="spi-spi-cursor-parse-open.html">SPI_cursor_parse_open</a></dt><dt id="ientry-idm84329">SPI_exec, <a class="indexterm" href="spi-spi-exec.html">SPI_exec</a></dt><dt id="ientry-idm85268">SPI_execp, <a class="indexterm" href="spi-spi-execp.html">SPI_execp</a></dt><dt id="ientry-idm84110">SPI_execute, <a class="indexterm" href="spi-spi-execute.html">SPI_execute</a></dt><dt id="ientry-idm84369">SPI_execute_extended, <a class="indexterm" href="spi-spi-execute-extended.html">SPI_execute_extended</a></dt><dt id="ientry-idm85000">SPI_execute_plan, <a class="indexterm" href="spi-spi-execute-plan.html">SPI_execute_plan</a></dt><dt id="ientry-idm85096">SPI_execute_plan_extended, <a class="indexterm" href="spi-spi-execute-plan-extended.html">SPI_execute_plan_extended</a></dt><dt id="ientry-idm85204">SPI_execute_plan_with_paramlist, <a class="indexterm" href="spi-spi-execute-plan-with-paramlist.html">SPI_execute_plan_with_paramlist</a></dt><dt id="ientry-idm84480">SPI_execute_with_args, <a class="indexterm" href="spi-spi-execute-with-args.html">SPI_execute_with_args</a></dt><dt id="ientry-idm82932">spi_exec_prepared</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm82843">spi_exec_query</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm82884">spi_fetchrow</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm84081">SPI_finish, <a class="indexterm" href="spi-spi-finish.html">SPI_finish</a></dt><dt id="ientry-idm86210">SPI_fname, <a class="indexterm" href="spi-spi-fname.html">SPI_fname</a></dt><dt id="ientry-idm86250">SPI_fnumber, <a class="indexterm" href="spi-spi-fnumber.html">SPI_fnumber</a></dt><dt id="ientry-idm82939">spi_freeplan</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm86937">SPI_freeplan, <a class="indexterm" href="spi-spi-freeplan.html">SPI_freeplan</a></dt><dt id="ientry-idm86877">SPI_freetuple, <a class="indexterm" href="spi-spi-freetuple.html">SPI_freetuple</a></dt><dt id="ientry-idm86904">SPI_freetuptable, <a class="indexterm" href="spi-spi-freetupletable.html">SPI_freetuptable</a></dt><dt id="ientry-idm84869">SPI_getargcount, <a class="indexterm" href="spi-spi-getargcount.html">SPI_getargcount</a></dt><dt id="ientry-idm84905">SPI_getargtypeid, <a class="indexterm" href="spi-spi-getargtypeid.html">SPI_getargtypeid</a></dt><dt id="ientry-idm86341">SPI_getbinval, <a class="indexterm" href="spi-spi-getbinval.html">SPI_getbinval</a></dt><dt id="ientry-idm86505">SPI_getnspname, <a class="indexterm" href="spi-spi-getnspname.html">SPI_getnspname</a></dt><dt id="ientry-idm86476">SPI_getrelname, <a class="indexterm" href="spi-spi-getrelname.html">SPI_getrelname</a></dt><dt id="ientry-idm86396">SPI_gettype, <a class="indexterm" href="spi-spi-gettype.html">SPI_gettype</a></dt><dt id="ientry-idm86435">SPI_gettypeid, <a class="indexterm" href="spi-spi-gettypeid.html">SPI_gettypeid</a></dt><dt id="ientry-idm86290">SPI_getvalue, <a class="indexterm" href="spi-spi-getvalue.html">SPI_getvalue</a></dt><dt id="ientry-idm84951">SPI_is_cursor_plan, <a class="indexterm" href="spi-spi-is-cursor-plan.html">SPI_is_cursor_plan</a></dt><dt id="ientry-idm85936">SPI_keepplan, <a class="indexterm" href="spi-spi-keepplan.html">SPI_keepplan</a></dt><dt id="ientry-idm86767">SPI_modifytuple, <a class="indexterm" href="spi-spi-modifytuple.html">SPI_modifytuple</a></dt><dt id="ientry-idm86591">SPI_palloc, <a class="indexterm" href="spi-spi-palloc.html">SPI_palloc</a></dt><dt id="ientry-idm86658">SPI_pfree, <a class="indexterm" href="spi-spi-pfree.html">SPI_pfree</a></dt><dt id="ientry-idm82915">spi_prepare</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm84583">SPI_prepare, <a class="indexterm" href="spi-spi-prepare.html">SPI_prepare</a></dt><dt id="ientry-idm84674">SPI_prepare_cursor, <a class="indexterm" href="spi-spi-prepare-cursor.html">SPI_prepare_cursor</a></dt><dt id="ientry-idm84746">SPI_prepare_extended, <a class="indexterm" href="spi-spi-prepare-extended.html">SPI_prepare_extended</a></dt><dt id="ientry-idm84814">SPI_prepare_params, <a class="indexterm" href="spi-spi-prepare-params.html">SPI_prepare_params</a></dt><dt id="ientry-idm82877">spi_query</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm82923">spi_query_prepared</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm86025">SPI_register_relation, <a class="indexterm" href="spi-spi-register-relation.html">SPI_register_relation</a></dt><dt id="ientry-idm86142">SPI_register_trigger_data, <a class="indexterm" href="spi-spi-register-trigger-data.html">SPI_register_trigger_data</a></dt><dt id="ientry-idm86620">SPI_repalloc, <a class="indexterm" href="spi-realloc.html">SPI_repalloc</a></dt><dt id="ientry-idm86535">SPI_result_code_string, <a class="indexterm" href="spi-spi-result-code-string.html">SPI_result_code_string</a></dt><dt id="ientry-idm86721">SPI_returntuple, <a class="indexterm" href="spi-spi-returntuple.html">SPI_returntuple</a></dt><dt id="ientry-idm82976">spi_rollback</dt><dd><dl><dt>in PL/Perl, <a class="indexterm" href="plperl-builtins.html#PLPERL-DATABASE">Database Access from PL/Perl</a></dt></dl></dd><dt id="ientry-idm87005">SPI_rollback, <a class="indexterm" href="spi-spi-rollback.html">SPI_rollback</a></dt><dt id="ientry-idm87007">SPI_rollback_and_chain, <a class="indexterm" href="spi-spi-rollback.html">SPI_rollback</a></dt><dt id="ientry-idm85973">SPI_saveplan, <a class="indexterm" href="spi-spi-saveplan.html">SPI_saveplan</a></dt><dt id="ientry-idm85782">SPI_scroll_cursor_fetch, <a class="indexterm" href="spi-spi-scroll-cursor-fetch.html">SPI_scroll_cursor_fetch</a></dt><dt id="ientry-idm85845">SPI_scroll_cursor_move, <a class="indexterm" href="spi-spi-scroll-cursor-move.html">SPI_scroll_cursor_move</a></dt><dt id="ientry-idm87030">SPI_start_transaction, <a class="indexterm" href="spi-spi-start-transaction.html">SPI_start_transaction</a></dt><dt id="ientry-idm86085">SPI_unregister_relation, <a class="indexterm" href="spi-spi-unregister-relation.html">SPI_unregister_relation</a></dt><dt id="ientry-idm13055">split_part, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm156621">SQL/CLI, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156617">SQL/Foundation, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156613">SQL/Framework, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156641">SQL/JRT, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm22546">SQL/JSON path language, <a class="indexterm" href="functions-json.html#FUNCTIONS-SQLJSON-PATH">The SQL/JSON Path Language</a></dt><dt id="ientry-idm156649">SQL/MDA, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156629">SQL/MED, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156633">SQL/OLB, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156625">SQL/PSM, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156637">SQL/Schemata, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dt id="ientry-idm156645">SQL/XML, <a class="indexterm" href="features.html">SQL Conformance</a></dt><dd><dl><dt>limits and conformance, <a class="indexterm" href="xml-limits-conformance.html">XML Limits and Conformance to SQL/XML</a></dt></dl></dd><dt id="ientry-idm11560">sqrt, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm38212">ssh, <a class="indexterm" href="ssh-tunnels.html">Secure TCP/IP Connections with SSH Tunnels</a></dt><dt id="ientry-idm33515">SSI, <a class="indexterm" href="mvcc-intro.html">Introduction</a></dt><dt id="ientry-idm37993">SSL, <a class="indexterm" href="ssl-tcp.html">Secure TCP/IP Connections with SSL</a>, <a class="indexterm" href="libpq-ssl.html">SSL Support</a></dt><dd><dl><dt>in libpq, <a class="indexterm" href="libpq-status.html">Connection Status Functions</a></dt><dt>with libpq, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt><dt>TLS, <a class="indexterm" href="ssl-tcp.html">Secure TCP/IP Connections with SSL</a>, <a class="indexterm" href="libpq-ssl.html">SSL Support</a></dt></dl></dd><dt id="ientry-idm38879">ssl configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm172047">sslinfo, <a class="indexterm" href="sslinfo.html">sslinfo</a></dt><dt id="ientry-idm38891">ssl_ca_file configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm38901">ssl_cert_file configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm172077">ssl_cipher, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm38951">ssl_ciphers configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm172084">ssl_client_cert_present, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172099">ssl_client_dn, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172118">ssl_client_dn_field, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172091">ssl_client_serial, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm38923">ssl_crl_dir configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm38912">ssl_crl_file configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39062">ssl_dh_params_file configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39013">ssl_ecdh_curve configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm172137">ssl_extension_info, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172108">ssl_issuer_dn, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172129">ssl_issuer_field, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm172063">ssl_is_used, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm38940">ssl_key_file configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm44308">ssl_library configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm39050">ssl_max_protocol_version configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39032">ssl_min_protocol_version configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39074">ssl_passphrase_command configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39090">ssl_passphrase_command_supports_reload configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm39001">ssl_prefer_server_ciphers configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">SSL</a></dt><dt id="ientry-idm172070">ssl_version, <a class="indexterm" href="sslinfo.html#id-1.11.7.51.6">Functions Provided</a></dt><dt id="ientry-idm45583">SSPI, <a class="indexterm" href="sspi-auth.html">SSPI Authentication</a></dt><dt id="ientry-idm73909">STABLE, <a class="indexterm" href="xfunc-volatility.html">Function Volatility Categories</a></dt><dt id="ientry-idm25190">standard deviation, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dd><dl><dt>population, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt>sample, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm43986">standard_conforming_strings configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm50315">standby server, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm40245">standby.signal, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">Archive Recovery</a>, <a class="indexterm" href="warm-standby.html#STANDBY-SERVER-OPERATION">Standby Server Operation</a>, <a class="indexterm" href="warm-standby.html#STANDBY-SERVER-SETUP">Setting Up a Standby Server</a></dt><dd><dl><dt>for hot standby, <a class="indexterm" href="hot-standby.html#HOT-STANDBY-ADMIN">Administrator's Overview</a></dt><dt>pg_basebackup --write-recovery-conf, <a class="indexterm" href="app-pgbasebackup.html#id-1.9.4.10.6">Options</a></dt></dl></dd><dt id="ientry-idm175568">standby_mode (see <a href="#ientry-idm40245">standby.signal</a>)</dt><dt id="ientry-idm112503">START TRANSACTION, <a class="indexterm" href="sql-start-transaction.html">START TRANSACTION</a></dt><dt id="ientry-idm13080">starts_with, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm138487">START_REPLICATION, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm43270">statement_timeout configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm17596">statement_timestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm24976">statistics, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a>, <a class="indexterm" href="planner-stats.html">Statistics Used by the Planner</a>, <a class="indexterm" href="planner-stats.html#PLANNER-STATS-EXTENDED">Extended Statistics</a>, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS">Updating Planner Statistics</a>, <a class="indexterm" href="monitoring-stats.html">The Cumulative Statistics System</a></dt><dd><dl><dt>of the planner, <a class="indexterm" href="planner-stats.html">Statistics Used by the Planner</a>, <a class="indexterm" href="planner-stats.html#PLANNER-STATS-EXTENDED">Extended Statistics</a>, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS">Updating Planner Statistics</a></dt></dl></dd><dt id="ientry-idm42713">stats_fetch_consistency configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm25192">stddev, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25210">stddev_pop, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25227">stddev_samp, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm50321">STONITH, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm101358">storage parameters, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm50392">Streaming Replication, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm170403">strict_word_similarity, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm6583">string (see <a href="#ientry-idm1285">character string</a>)</dt><dt id="ientry-idm43907">strings</dt><dd><dl><dt>backslash quotes, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt>escape warning, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt>standard conforming, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt></dl></dd><dt id="ientry-idm24860">string_agg, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm13097">string_to_array, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm13128">string_to_table, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm20138">strip, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">Manipulating Documents</a></dt><dt id="ientry-idm13158">strpos, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm166847">subarray, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm167707">subltree, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm167726">subpath, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm842">subquery, <a class="indexterm" href="tutorial-agg.html">Aggregate Functions</a>, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-SCALAR-SUBQUERIES">Scalar Subqueries</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-SUBQUERIES">Subqueries</a>, <a class="indexterm" href="functions-subquery.html">Subquery Expressions</a></dt><dt id="ientry-idm1824">subscript, <a class="indexterm" href="sql-expressions.html#SQL-EXPRESSIONS-SUBSCRIPTS">Subscripts</a></dt><dt id="ientry-idm13178">substr, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm12258">substring, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a>, <a class="indexterm" href="functions-bitstring.html">Bit String Functions and Operators</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP">SIMILAR TO Regular Expressions</a>, <a class="indexterm" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">POSIX Regular Expressions</a></dt><dt id="ientry-idm15770">SUBSTRING_REGEX, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a></dt><dt id="ientry-idm82635">subtransactions</dt><dd><dl><dt>in PL/Tcl, <a class="indexterm" href="pltcl-subtransactions.html">Explicit Subtransactions in PL/Tcl</a></dt></dl></dd><dt id="ientry-idm24881">sum, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm517">superuser, <a class="indexterm" href="tutorial-accessdb.html">Accessing a Database</a>, <a class="indexterm" href="role-attributes.html">Role Attributes</a></dt><dt id="ientry-idm38622">superuser_reserved_connections configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm143833">support functions</dt><dd><dl><dt>in_range, <a class="indexterm" href="btree-support-funcs.html">B-Tree Support Functions</a></dt></dl></dd><dt id="ientry-idm30314">suppress_redundant_updates_trigger, <a class="indexterm" href="functions-trigger.html">Trigger Functions</a></dt><dt id="ientry-idm166379">svals, <a class="indexterm" href="hstore.html#id-1.11.7.27.6">hstore Operators and Functions</a></dt><dt id="ientry-idm44001">synchronize_seqscans configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">Previous PostgreSQL Versions</a></dt><dt id="ientry-idm56380">synchronous commit, <a class="indexterm" href="wal-async-commit.html">Asynchronous Commit</a></dt><dt id="ientry-idm50516">Synchronous Replication, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm39750">synchronous_commit configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm40548">synchronous_standby_names configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY">Primary Server</a></dt><dt id="ientry-idm1158">syntax, <a class="indexterm" href="sql-syntax.html">SQL Syntax</a></dt><dd><dl><dt>SQL, <a class="indexterm" href="sql-syntax.html">SQL Syntax</a></dt></dl></dd><dt id="ientry-idm41650">syslog_facility configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41673">syslog_ident configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41687">syslog_sequence_numbers configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm41703">syslog_split_messages configuration parameter, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm3756">system catalog, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CATALOG">The System Catalog Schema</a></dt><dd><dl><dt>schema, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-CATALOG">The System Catalog Schema</a></dt></dl></dd><dt id="ientry-idm35858">systemd, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a>, <a class="indexterm" href="server-start.html">Starting the Database Server</a></dt><dd><dl><dt>RemoveIPC, <a class="indexterm" href="kernel-resources.html#SYSTEMD-REMOVEIPC">systemd RemoveIPC</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-T"><h3>T</h3><dl><dt id="ientry-idm605">table, <a class="indexterm" href="tutorial-concepts.html">Concepts</a>, <a class="indexterm" href="ddl-basics.html">Table Basics</a>, <a class="indexterm" href="ddl-alter.html">Modifying Tables</a></dt><dd><dl><dt>creating, <a class="indexterm" href="ddl-basics.html">Table Basics</a></dt><dt>inheritance, <a class="indexterm" href="ddl-inherit.html">Inheritance</a></dt><dt>modifying, <a class="indexterm" href="ddl-alter.html">Modifying Tables</a></dt><dt>partitioning, <a class="indexterm" href="ddl-partitioning.html">Table Partitioning</a></dt><dt>removing, <a class="indexterm" href="ddl-basics.html">Table Basics</a></dt><dt>renaming, <a class="indexterm" href="ddl-alter.html#id-1.5.4.8.12">Renaming a Table</a></dt></dl></dd><dt id="ientry-idm142952">Table Access Method, <a class="indexterm" href="tableam.html">Table Access Method Interface Definition</a></dt><dt id="ientry-idm110447">TABLE command, <a class="indexterm" href="sql-select.html">SELECT</a></dt><dt id="ientry-idm4570">table expression, <a class="indexterm" href="queries-table-expressions.html">Table Expressions</a></dt><dt id="ientry-idm4871">table function, <a class="indexterm" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS">Table Functions</a>, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-PROCESSING-XMLTABLE">xmltable</a></dt><dd><dl><dt>XMLTABLE, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-PROCESSING-XMLTABLE">xmltable</a></dt></dl></dd><dt id="ientry-idm142555">table sampling method, <a class="indexterm" href="tablesample-method.html">Writing a Table Sampling Method</a></dt><dt id="ientry-idm142954">tableam</dt><dd><dl><dt>Table Access Method, <a class="indexterm" href="tableam.html">Table Access Method Interface Definition</a></dt></dl></dd><dt id="ientry-idm172151">tablefunc, <a class="indexterm" href="tablefunc.html">tablefunc</a></dt><dt id="ientry-idm2852">tableoid, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm142557">TABLESAMPLE method, <a class="indexterm" href="tablesample-method.html">Writing a Table Sampling Method</a></dt><dt id="ientry-idm43077">tablespace, <a class="indexterm" href="manage-ag-tablespaces.html">Tablespaces</a></dt><dd><dl><dt>default, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt>temporary, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></dd><dt id="ientry-idm10162">table_am_handler, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm11910">tan, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11922">tand, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm11977">tanh, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm78791">target list, <a class="indexterm" href="querytree.html">The Query Tree</a></dt><dt id="ientry-idm82204">Tcl, <a class="indexterm" href="pltcl.html">PL/Tcl — Tcl Procedural Language</a></dt><dt id="ientry-idm172519">tcn, <a class="indexterm" href="tcn.html">tcn</a></dt><dt id="ientry-idm38740">tcp_keepalives_count configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38716">tcp_keepalives_idle configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38728">tcp_keepalives_interval configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38752">tcp_user_timeout configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm46455">template0, <a class="indexterm" href="manage-ag-createdb.html">Creating a Database</a>, <a class="indexterm" href="manage-ag-templatedbs.html">Template Databases</a></dt><dt id="ientry-idm46452">template1, <a class="indexterm" href="manage-ag-createdb.html">Creating a Database</a>, <a class="indexterm" href="manage-ag-templatedbs.html">Template Databases</a></dt><dt id="ientry-idm39188">temp_buffers configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm39365">temp_file_limit configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-DISK">Disk</a></dt><dt id="ientry-idm43115">temp_tablespaces configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm57312">test, <a class="indexterm" href="regress.html">Regression Tests</a></dt><dt id="ientry-idm172538">test_decoding, <a class="indexterm" href="test-decoding.html">test_decoding</a></dt><dt id="ientry-idm6590">text, <a class="indexterm" href="datatype-character.html">Character Types</a>, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm8518">text search, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a>, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a>, <a class="indexterm" href="textsearch.html">Full Text Search</a>, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a></dt><dd><dl><dt>data types, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a></dt><dt>functions and operators, <a class="indexterm" href="datatype-textsearch.html">Text Search Types</a></dt><dt>indexes, <a class="indexterm" href="textsearch-indexes.html">Preferred Index Types for Text Search</a></dt></dl></dd><dt id="ientry-idm167811">text2ltree, <a class="indexterm" href="ltree.html#id-1.11.7.32.6">Operators and Functions</a></dt><dt id="ientry-idm62332">threads, <a class="indexterm" href="libpq-threading.html">Behavior in Threaded Programs</a></dt><dd><dl><dt>with libpq, <a class="indexterm" href="libpq-threading.html">Behavior in Threaded Programs</a></dt></dl></dd><dt id="ientry-idm9897">tid, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm6921">time, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.6">Times</a></dt><dd><dl><dt>constants, <a class="indexterm" href="datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-VALUES">Special Values</a></dt><dt>current, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT">Current Date/Time</a></dt><dt>output format, <a class="indexterm" href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT">Date/Time Output</a></dt><dd><dl><dt>(see also <a href="#ientry-idm15924">formatting</a>)</dt></dl></dd></dl></dd><dt id="ientry-idm6937">time span, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a></dt><dt id="ientry-idm6925">time with time zone, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.6">Times</a></dt><dt id="ientry-idm6923">time without time zone, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.6">Times</a></dt><dt id="ientry-idm7548">time zone, <a class="indexterm" href="datatype-datetime.html#DATATYPE-TIMEZONES">Time Zones</a>, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a>, <a class="indexterm" href="datetime-posix-timezone-specs.html">POSIX Time Zone Specifications</a></dt><dd><dl><dt>conversion, <a class="indexterm" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT">AT TIME ZONE</a></dt><dt>input abbreviations, <a class="indexterm" href="datetime-config-files.html">Date/Time Configuration Files</a></dt><dt>POSIX-style specification, <a class="indexterm" href="datetime-posix-timezone-specs.html">POSIX Time Zone Specifications</a></dt></dl></dd><dt id="ientry-idm36002">time zone data, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-BUILD-PROCESS">Build Process Details</a></dt><dt id="ientry-idm43565">time zone names, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm49990">timelines, <a class="indexterm" href="backup.html">Backup and Restore</a></dt><dt id="ientry-idm138322">TIMELINE_HISTORY, <a class="indexterm" href="protocol-replication.html">Streaming Replication Protocol</a></dt><dt id="ientry-idm17608">timeofday, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm38784">timeout</dt><dd><dl><dt>client authentication, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">Authentication</a></dt><dt>deadlock, <a class="indexterm" href="runtime-config-locks.html">Lock Management</a></dt></dl></dd><dt id="ientry-idm6927">timestamp, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.7">Time Stamps</a></dt><dt id="ientry-idm6931">timestamp with time zone, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.7">Time Stamps</a></dt><dt id="ientry-idm6933">timestamp without time zone, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a>, <a class="indexterm" href="datatype-datetime.html#id-1.5.7.13.18.7">Time Stamps</a></dt><dt id="ientry-idm6929">timestamptz, <a class="indexterm" href="datatype-datetime.html">Date/Time Types</a></dt><dt id="ientry-idm43547">TimeZone configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm43562">timezone_abbreviations configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">Locale and Formatting</a></dt><dt id="ientry-idm62471">TOAST, <a class="indexterm" href="storage-toast.html">TOAST</a></dt><dd><dl><dt>and user-defined types, <a class="indexterm" href="xtypes.html#XTYPES-TOAST">TOAST Considerations</a></dt><dt>per-column storage settings, <a class="indexterm" href="sql-altertable.html#id-1.9.3.35.5">Description</a></dt><dt>per-type storage settings, <a class="indexterm" href="sql-altertype.html#id-1.9.3.42.5">Description</a></dt><dt>versus large objects, <a class="indexterm" href="lo-intro.html">Introduction</a></dt></dl></dd><dt id="ientry-idm101388">toast_tuple_target storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm1166">token, <a class="indexterm" href="sql-syntax-lexical.html">Lexical Structure</a></dt><dt id="ientry-idm13206">to_ascii, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm15942">to_char, <a class="indexterm" href="functions-formatting.html">Data Type Formatting Functions</a></dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm15993">to_date, <a class="indexterm" href="functions-formatting.html">Data Type Formatting Functions</a></dt><dt id="ientry-idm13241">to_hex, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm21693">to_json, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm21699">to_jsonb, <a class="indexterm" href="functions-json.html#FUNCTIONS-JSON-PROCESSING">Processing and Creating JSON Data</a></dt><dt id="ientry-idm16006">to_number, <a class="indexterm" href="functions-formatting.html">Data Type Formatting Functions</a></dt><dt id="ientry-idm27580">to_regclass, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27592">to_regcollation, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27604">to_regnamespace, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27616">to_regoper, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27628">to_regoperator, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27640">to_regproc, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27652">to_regprocedure, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27664">to_regrole, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm27676">to_regtype, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm16019">to_timestamp, <a class="indexterm" href="functions-formatting.html">Data Type Formatting Functions</a>, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm20151">to_tsquery, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES">Parsing Queries</a></dt><dt id="ientry-idm20169">to_tsvector, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-PARSING-DOCUMENTS">Parsing Documents</a></dt><dt id="ientry-idm44505">trace_locks configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44544">trace_lock_oidmin configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44556">trace_lock_table configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44519">trace_lwlocks configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44459">trace_notify configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44473">trace_recovery_messages configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44493">trace_sort configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44531">trace_userlocks configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm42633">track_activities configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm42644">track_activity_query_size configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm40531">track_commit_timestamp configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm42655">track_counts configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm42697">track_functions configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm42665">track_io_timing configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm42684">track_wal_io_timing configuration parameter, <a class="indexterm" href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">Cumulative Query and Index Statistics</a></dt><dt id="ientry-idm969">transaction, <a class="indexterm" href="tutorial-transactions.html">Transactions</a></dt><dt id="ientry-idm49085">transaction ID, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND">Preventing Transaction ID Wraparound Failures</a></dt><dd><dl><dt>wraparound, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND">Preventing Transaction ID Wraparound Failures</a></dt></dl></dd><dt id="ientry-idm33534">transaction isolation, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a></dt><dt id="ientry-idm33565">transaction isolation level, <a class="indexterm" href="transaction-iso.html">Transaction Isolation</a>, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dd><dl><dt>read committed, <a class="indexterm" href="transaction-iso.html#XACT-READ-COMMITTED">Read Committed Isolation Level</a></dt><dt>repeatable read, <a class="indexterm" href="transaction-iso.html#XACT-REPEATABLE-READ">Repeatable Read Isolation Level</a></dt><dt>serializable, <a class="indexterm" href="transaction-iso.html#XACT-SERIALIZABLE">Serializable Isolation Level</a></dt><dt>setting, <a class="indexterm" href="sql-set-transaction.html">SET TRANSACTION</a></dt><dt>setting default, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt></dl></dd><dt id="ientry-idm56360">transaction log (see <a href="#ientry-idm56358">WAL</a>)</dt><dt id="ientry-idm43234">transaction_deferrable configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43208">transaction_isolation configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43221">transaction_read_only configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm17622">transaction_timestamp, <a class="indexterm" href="functions-datetime.html">Date/Time Functions and Operators</a></dt><dt id="ientry-idm44019">transform_null_equals configuration parameter, <a class="indexterm" href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-CLIENTS">Platform and Client Compatibility</a></dt><dt id="ientry-idm77037">transition tables, <a class="indexterm" href="sql-createtrigger.html">CREATE TRIGGER</a></dt><dd><dl><dt>(see also <a href="#ientry-idm86027">ephemeral named relation</a>)</dt><dt>implementation in PLs, <a class="indexterm" href="spi-spi-register-trigger-data.html">SPI_register_trigger_data</a></dt><dt>referencing from C trigger, <a class="indexterm" href="trigger-interface.html">Writing Trigger Functions in C</a></dt></dl></dd><dt id="ientry-idm13257">translate, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm15772">TRANSLATE_REGEX, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a></dt><dt id="ientry-idm39157">transparent
+ huge pages, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm10152">trigger, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a>, <a class="indexterm" href="triggers.html">Triggers</a>, <a class="indexterm" href="trigger-interface.html">Writing Trigger Functions in C</a>, <a class="indexterm" href="rules-triggers.html">Rules Versus Triggers</a>, <a class="indexterm" href="plpgsql-trigger.html">Trigger Functions</a>, <a class="indexterm" href="plpython-trigger.html">Trigger Functions</a></dt><dd><dl><dt>arguments for trigger functions, <a class="indexterm" href="trigger-definition.html">Overview of Trigger Behavior</a></dt><dt>constraint trigger, <a class="indexterm" href="sql-createtrigger.html#id-1.9.3.93.6">Description</a></dt><dt>for updating a derived tsvector column, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS">Triggers for Automatic Updates</a></dt><dt>in C, <a class="indexterm" href="trigger-interface.html">Writing Trigger Functions in C</a></dt><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-trigger.html">Trigger Functions</a></dt><dt>in PL/Python, <a class="indexterm" href="plpython-trigger.html">Trigger Functions</a></dt><dt>in PL/Tcl, <a class="indexterm" href="pltcl-trigger.html">Trigger Functions in PL/Tcl</a></dt><dt>compared with rules, <a class="indexterm" href="rules-triggers.html">Rules Versus Triggers</a></dt></dl></dd><dt id="ientry-idm172521">triggered_change_notification, <a class="indexterm" href="tcn.html">tcn</a></dt><dt id="ientry-idm175562">trigger_file (see promote_trigger_file)</dt><dt id="ientry-idm12335">trim, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-binarystring.html">Binary String Functions and Operators</a></dt><dt id="ientry-idm23757">trim_array, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dt id="ientry-idm11576">trim_scale, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm7856">true, <a class="indexterm" href="datatype-boolean.html">Boolean Type</a></dt><dt id="ientry-idm11588">trunc, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a>, <a class="indexterm" href="functions-net.html">Network Address Functions and Operators</a></dt><dt id="ientry-idm112560">TRUNCATE, <a class="indexterm" href="sql-truncate.html">TRUNCATE</a></dt><dt id="ientry-idm83149">trusted, <a class="indexterm" href="plperl-trusted.html">Trusted and Untrusted PL/Perl</a></dt><dd><dl><dt>PL/Perl, <a class="indexterm" href="plperl-trusted.html">Trusted and Untrusted PL/Perl</a></dt></dl></dd><dt id="ientry-idm10166">tsm_handler, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm172550">tsm_system_rows, <a class="indexterm" href="tsm-system-rows.html">tsm_system_rows</a></dt><dt id="ientry-idm172580">tsm_system_time, <a class="indexterm" href="tsm-system-time.html">tsm_system_time</a></dt><dt id="ientry-idm8563">tsquery (data type), <a class="indexterm" href="datatype-textsearch.html#DATATYPE-TSQUERY">tsquery</a></dt><dt id="ientry-idm20457">tsquery_phrase, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSQUERY">Manipulating Queries</a></dt><dt id="ientry-idm8532">tsvector (data type), <a class="indexterm" href="datatype-textsearch.html#DATATYPE-TSVECTOR">tsvector</a></dt><dt id="ientry-idm32378">tsvector concatenation, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">Manipulating Documents</a></dt><dt id="ientry-idm20493">tsvector_to_array, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm30324">tsvector_update_trigger, <a class="indexterm" href="functions-trigger.html">Trigger Functions</a></dt><dt id="ientry-idm30336">tsvector_update_trigger_column, <a class="indexterm" href="functions-trigger.html">Trigger Functions</a></dt><dt id="ientry-idm20543">ts_debug, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-debugging.html#TEXTSEARCH-CONFIGURATION-TESTING">Configuration Testing</a></dt><dt id="ientry-idm20259">ts_delete, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm20294">ts_filter, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm20311">ts_headline, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-HEADLINE">Highlighting Results</a></dt><dt id="ientry-idm20573">ts_lexize, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-debugging.html#TEXTSEARCH-DICTIONARY-TESTING">Dictionary Testing</a></dt><dt id="ientry-idm20589">ts_parse, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING">Parser Testing</a></dt><dt id="ientry-idm20372">ts_rank, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-RANKING">Ranking Search Results</a></dt><dt id="ientry-idm20396">ts_rank_cd, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-controls.html#TEXTSEARCH-RANKING">Ranking Search Results</a></dt><dt id="ientry-idm20420">ts_rewrite, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-QUERY-REWRITING">Query Rewriting</a></dt><dt id="ientry-idm20667">ts_stat, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-features.html#TEXTSEARCH-STATISTICS">Gathering Document Statistics</a></dt><dt id="ientry-idm20629">ts_token_type, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a>, <a class="indexterm" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING">Parser Testing</a></dt><dt id="ientry-idm168055">tuple_data_split, <a class="indexterm" href="pageinspect.html#id-1.11.7.34.5">Heap Functions</a></dt><dt id="ientry-idm28154">txid_current, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28163">txid_current_if_assigned, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28172">txid_current_snapshot, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28181">txid_snapshot_xip, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28191">txid_snapshot_xmax, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28201">txid_snapshot_xmin, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28222">txid_status, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm28211">txid_visible_in_snapshot, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt><dt id="ientry-idm5839">type (see <a href="#ientry-idm1501">data type</a>)</dt><dt id="ientry-idm1494">type cast, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC">Numeric Constants</a>, <a class="indexterm" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">Type Casts</a></dt></dl></div><div class="indexdiv" id="indexdiv-U"><h3>U</h3><dl><dt id="ientry-idm1269">UESCAPE, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a>, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-UESCAPE">String Constants with Unicode Escapes</a></dt><dt id="ientry-idm172610">unaccent, <a class="indexterm" href="unaccent.html">unaccent</a>, <a class="indexterm" href="unaccent.html#id-1.11.7.57.8">Functions</a></dt><dt id="ientry-idm1256">Unicode escape, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-UESCAPE">String Constants with Unicode Escapes</a></dt><dd><dl><dt>in identifiers, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">Identifiers and Key Words</a></dt><dt>in string constants, <a class="indexterm" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-UESCAPE">String Constants with Unicode Escapes</a></dt></dl></dd><dt id="ientry-idm12091">Unicode normalization, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm5347">UNION, <a class="indexterm" href="queries-union.html">Combining Queries (UNION, INTERSECT, EXCEPT)</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm166816">uniq, <a class="indexterm" href="intarray.html#id-1.11.7.29.7">intarray Functions and Operators</a></dt><dt id="ientry-idm2686">unique constraint, <a class="indexterm" href="ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS">Unique Constraints</a></dt><dt id="ientry-idm13280">unistr, <a class="indexterm" href="functions-string.html">String Functions and Operators</a></dt><dt id="ientry-idm58247">Unix domain socket, <a class="indexterm" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">Parameter Key Words</a></dt><dt id="ientry-idm38638">unix_socket_directories configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38660">unix_socket_group configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm38671">unix_socket_permissions configuration parameter, <a class="indexterm" href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">Connection Settings</a></dt><dt id="ientry-idm10172">unknown, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm112669">UNLISTEN, <a class="indexterm" href="sql-unlisten.html">UNLISTEN</a></dt><dt id="ientry-idm20506">unnest, <a class="indexterm" href="functions-array.html">Array Functions and Operators</a></dt><dd><dl><dt>for multirange, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt>for tsvector, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt></dl></dd><dt id="ientry-idm3695">unqualified name, <a class="indexterm" href="ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a></dt><dt id="ientry-idm103710">updatable views, <a class="indexterm" href="sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS">Updatable Views</a></dt><dt id="ientry-idm901">UPDATE, <a class="indexterm" href="tutorial-update.html">Updates</a>, <a class="indexterm" href="dml-update.html">Updating Data</a>, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a>, <a class="indexterm" href="sql-update.html">UPDATE</a></dt><dd><dl><dt>RETURNING, <a class="indexterm" href="dml-returning.html">Returning Data from Modified Rows</a></dt></dl></dd><dt id="ientry-idm42612">update_process_title configuration parameter, <a class="indexterm" href="runtime-config-logging.html#id-1.6.7.11.8">Process Title</a></dt><dt id="ientry-idm4437">updating, <a class="indexterm" href="dml-update.html">Updating Data</a></dt><dt id="ientry-idm37780">upgrading, <a class="indexterm" href="upgrading.html">Upgrading a PostgreSQL Cluster</a></dt><dt id="ientry-idm12380">upper, <a class="indexterm" href="functions-string.html">String Functions and Operators</a>, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dd><dl><dt>and locales, <a class="indexterm" href="locale.html#id-1.6.11.3.5">Behavior</a></dt></dl></dd><dt id="ientry-idm24365">upper_inc, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm24389">upper_inf, <a class="indexterm" href="functions-range.html">Range/Multirange Functions and Operators</a></dt><dt id="ientry-idm108178">UPSERT, <a class="indexterm" href="sql-insert.html">INSERT</a></dt><dt id="ientry-idm58142">URI, <a class="indexterm" href="libpq-connect.html#LIBPQ-CONNSTRING">Connection Strings</a></dt><dt id="ientry-idm26306">user, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a>, <a class="indexterm" href="database-roles.html">Database Roles</a></dt><dd><dl><dt>current, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a></dt></dl></dd><dt id="ientry-idm4313">user mapping, <a class="indexterm" href="ddl-foreign-data.html">Foreign Data</a></dt><dt id="ientry-idm45284">User name maps, <a class="indexterm" href="auth-username-maps.html">User Name Maps</a></dt><dt id="ientry-idm101642">user_catalog_table storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm8608">UUID, <a class="indexterm" href="datatype-uuid.html">UUID Type</a>, <a class="indexterm" href="datatype-uuid.html">UUID Type</a>, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES">PostgreSQL Features</a></dt><dd><dl><dt>generating, <a class="indexterm" href="datatype-uuid.html">UUID Type</a></dt></dl></dd><dt id="ientry-idm172688">uuid-ossp, <a class="indexterm" href="uuid-ossp.html">uuid-ossp</a></dt><dt id="ientry-idm172715">uuid_generate_v1, <a class="indexterm" href="uuid-ossp.html#id-1.11.7.58.5">uuid-ossp Functions</a></dt><dt id="ientry-idm172723">uuid_generate_v1mc, <a class="indexterm" href="uuid-ossp.html#id-1.11.7.58.5">uuid-ossp Functions</a></dt><dt id="ientry-idm172731">uuid_generate_v3, <a class="indexterm" href="uuid-ossp.html#id-1.11.7.58.5">uuid-ossp Functions</a></dt></dl></div><div class="indexdiv" id="indexdiv-V"><h3>V</h3><dl><dt id="ientry-idm48940">vacuum, <a class="indexterm" href="routine-vacuuming.html">Routine Vacuuming</a></dt><dt id="ientry-idm112968">VACUUM, <a class="indexterm" href="sql-vacuum.html">VACUUM</a></dt><dt id="ientry-idm124132">vacuumdb, <a class="indexterm" href="app-vacuumdb.html">vacuumdb</a></dt><dt id="ientry-idm173290">vacuumlo, <a class="indexterm" href="vacuumlo.html">vacuumlo</a></dt><dt id="ientry-idm39406">vacuum_cost_delay configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">Cost-based Vacuum Delay</a></dt><dt id="ientry-idm39447">vacuum_cost_limit configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">Cost-based Vacuum Delay</a></dt><dt id="ientry-idm39438">vacuum_cost_page_dirty configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">Cost-based Vacuum Delay</a></dt><dt id="ientry-idm39420">vacuum_cost_page_hit configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">Cost-based Vacuum Delay</a></dt><dt id="ientry-idm39429">vacuum_cost_page_miss configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">Cost-based Vacuum Delay</a></dt><dt id="ientry-idm40624">vacuum_defer_cleanup_age configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY">Primary Server</a></dt><dt id="ientry-idm43360">vacuum_failsafe_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43347">vacuum_freeze_min_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43330">vacuum_freeze_table_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm101425">vacuum_index_cleanup storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm43408">vacuum_multixact_failsafe_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43395">vacuum_multixact_freeze_min_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm43378">vacuum_multixact_freeze_table_age configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm101446">vacuum_truncate storage parameter, <a class="indexterm" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS">Storage Parameters</a></dt><dt id="ientry-idm1745">value expression, <a class="indexterm" href="sql-expressions.html">Value Expressions</a></dt><dt id="ientry-idm5529">VALUES, <a class="indexterm" href="queries-values.html">VALUES Lists</a>, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a>, <a class="indexterm" href="sql-values.html">VALUES</a></dt><dd><dl><dt>determination of result type, <a class="indexterm" href="typeconv-union-case.html">UNION, CASE, and Related Constructs</a></dt></dl></dd><dt id="ientry-idm6594">varchar, <a class="indexterm" href="datatype-character.html">Character Types</a></dt><dt id="ientry-idm73677">variadic function, <a class="indexterm" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS">SQL Functions with Variable Numbers of Arguments</a></dt><dt id="ientry-idm25241">variance, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dd><dl><dt>population, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt>sample, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt></dl></dd><dt id="ientry-idm25259">var_pop, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm25276">var_samp, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm530">version, <a class="indexterm" href="tutorial-accessdb.html">Accessing a Database</a>, <a class="indexterm" href="functions-info.html">System Information Functions and Operators</a>, <a class="indexterm" href="upgrading.html">Upgrading a PostgreSQL Cluster</a></dt><dd><dl><dt>compatibility, <a class="indexterm" href="upgrading.html">Upgrading a PostgreSQL Cluster</a></dt></dl></dd><dt id="ientry-idm937">view, <a class="indexterm" href="tutorial-views.html">Views</a>, <a class="indexterm" href="rules-views.html">Views and the Rule System</a>, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a>, <a class="indexterm" href="rules-update.html#RULES-UPDATE-VIEWS">Cooperation with Views</a></dt><dd><dl><dt>implementation through rules, <a class="indexterm" href="rules-views.html">Views and the Rule System</a></dt><dt>materialized, <a class="indexterm" href="rules-materializedviews.html">Materialized Views</a></dt><dt>updating, <a class="indexterm" href="rules-update.html#RULES-UPDATE-VIEWS">Cooperation with Views</a></dt></dl></dd><dt id="ientry-idm147719">Visibility Map, <a class="indexterm" href="storage-vm.html">Visibility Map</a></dt><dt id="ientry-idm147721">VM (see <a href="#ientry-idm147719">Visibility Map</a>)</dt><dt id="ientry-idm10150">void, <a class="indexterm" href="datatype-pseudo.html">Pseudo-Types</a></dt><dt id="ientry-idm73907">VOLATILE, <a class="indexterm" href="xfunc-volatility.html">Function Volatility Categories</a></dt><dt id="ientry-idm73904">volatility, <a class="indexterm" href="xfunc-volatility.html">Function Volatility Categories</a></dt><dd><dl><dt>functions, <a class="indexterm" href="xfunc-volatility.html">Function Volatility Categories</a></dt></dl></dd><dt id="ientry-idm35450">VPATH, <a class="indexterm" href="install-procedure.html">Installation Procedure</a>, <a class="indexterm" href="extend-pgxs.html">Extension Building Infrastructure</a></dt></dl></div><div class="indexdiv" id="indexdiv-W"><h3>W</h3><dl><dt id="ientry-idm56358">WAL, <a class="indexterm" href="wal.html">Reliability and the Write-Ahead Log</a></dt><dt id="ientry-idm44319">wal_block_size configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm39953">wal_buffers configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm39910">wal_compression configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm44592">wal_consistency_checking configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm44614">wal_debug configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm40229">wal_decode_buffer_size configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">Recovery</a></dt><dt id="ientry-idm39931">wal_init_zero configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm40492">wal_keep_size configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm39674">wal_level configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm39896">wal_log_hints configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm40730">wal_receiver_create_temp_slot configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40741">wal_receiver_status_interval configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm40771">wal_receiver_timeout configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm39943">wal_recycle configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm40781">wal_retrieve_retry_interval configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">Standby Servers</a></dt><dt id="ientry-idm44329">wal_segment_size configuration parameter, <a class="indexterm" href="runtime-config-preset.html">Preset Options</a></dt><dt id="ientry-idm40521">wal_sender_timeout configuration parameter, <a class="indexterm" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">Sending Servers</a></dt><dt id="ientry-idm40000">wal_skip_threshold configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm39840">wal_sync_method configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm39969">wal_writer_delay configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm39984">wal_writer_flush_after configuration parameter, <a class="indexterm" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">Settings</a></dt><dt id="ientry-idm50311">warm standby, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm20066">websearch_to_tsquery, <a class="indexterm" href="functions-textsearch.html">Text Search Functions and Operators</a></dt><dt id="ientry-idm5015">WHERE, <a class="indexterm" href="queries-table-expressions.html#QUERIES-WHERE">The WHERE Clause</a></dt><dt id="ientry-idm41440">where to log, <a class="indexterm" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">Where to Log</a></dt><dt id="ientry-idm80707">WHILE</dt><dd><dl><dt>in PL/pgSQL, <a class="indexterm" href="plpgsql-control-structures.html#id-1.8.8.8.7.7">WHILE</a></dt></dl></dd><dt id="ientry-idm19123">width, <a class="indexterm" href="functions-geometry.html">Geometric Functions and Operators</a></dt><dt id="ientry-idm11622">width_bucket, <a class="indexterm" href="functions-math.html">Mathematical Functions and Operators</a></dt><dt id="ientry-idm1012">window function, <a class="indexterm" href="tutorial-window.html">Window Functions</a>, <a class="indexterm" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS">Window Function Calls</a>, <a class="indexterm" href="queries-table-expressions.html#QUERIES-WINDOW">Window Function Processing</a>, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dd><dl><dt>built-in, <a class="indexterm" href="functions-window.html">Window Functions</a></dt><dt>invocation, <a class="indexterm" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS">Window Function Calls</a></dt><dt>order of execution, <a class="indexterm" href="queries-table-expressions.html#QUERIES-WINDOW">Window Function Processing</a></dt></dl></dd><dt id="ientry-idm5564">WITH, <a class="indexterm" href="queries-with.html">WITH Queries (Common Table Expressions)</a>, <a class="indexterm" href="sql-select.html">SELECT</a></dt><dd><dl><dt>in SELECT, <a class="indexterm" href="queries-with.html">WITH Queries (Common Table Expressions)</a>, <a class="indexterm" href="sql-select.html">SELECT</a></dt></dl></dd><dt id="ientry-idm103632">WITH CHECK OPTION, <a class="indexterm" href="sql-createview.html">CREATE VIEW</a></dt><dt id="ientry-idm1919">WITHIN GROUP, <a class="indexterm" href="sql-expressions.html#SYNTAX-AGGREGATES">Aggregate Expressions</a></dt><dt id="ientry-idm50319">witness server, <a class="indexterm" href="high-availability.html">High Availability, Load Balancing, and Replication</a></dt><dt id="ientry-idm170393">word_similarity, <a class="indexterm" href="pgtrgm.html#id-1.11.7.44.6">Functions and Operators</a></dt><dt id="ientry-idm39219">work_mem configuration parameter, <a class="indexterm" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">Memory</a></dt><dt id="ientry-idm49088">wraparound</dt><dd><dl><dt>of multixact IDs, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND">Multixacts and Wraparound</a></dt><dt>of transaction IDs, <a class="indexterm" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND">Preventing Transaction ID Wraparound Failures</a></dt></dl></dd></dl></div><div class="indexdiv" id="indexdiv-X"><h3>X</h3><dl><dt id="ientry-idm9899">xid, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm9893">xid8, <a class="indexterm" href="datatype-oid.html">Object Identifier Types</a></dt><dt id="ientry-idm2878">xmax, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm2864">xmin, <a class="indexterm" href="ddl-system-columns.html">System Columns</a></dt><dt id="ientry-idm8625">XML, <a class="indexterm" href="datatype-xml.html">XML Type</a></dt><dt id="ientry-idm21166">XML export, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-MAPPING">Mapping Tables to XML</a></dt><dt id="ientry-idm20708">XML Functions, <a class="indexterm" href="functions-xml.html">XML Functions</a></dt><dt id="ientry-idm8679">XML option, <a class="indexterm" href="datatype-xml.html#id-1.5.7.21.6">Creating XML Values</a>, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm172824">xml2, <a class="indexterm" href="xml2.html">xml2</a></dt><dt id="ientry-idm20875">xmlagg, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-XMLAGG">xmlagg</a>, <a class="indexterm" href="functions-aggregate.html">Aggregate Functions</a></dt><dt id="ientry-idm43440">xmlbinary configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm20726">xmlcomment, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.3">xmlcomment</a></dt><dt id="ientry-idm20743">xmlconcat, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.4">xmlconcat</a></dt><dt id="ientry-idm20762">xmlelement, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.5">xmlelement</a></dt><dt id="ientry-idm20923">XMLEXISTS, <a class="indexterm" href="functions-xml.html#XML-EXISTS">XMLEXISTS</a></dt><dt id="ientry-idm20807">xmlforest, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.6">xmlforest</a></dt><dt id="ientry-idm43457">xmloption configuration parameter, <a class="indexterm" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">Statement Behavior</a></dt><dt id="ientry-idm8649">xmlparse, <a class="indexterm" href="datatype-xml.html#id-1.5.7.21.6">Creating XML Values</a></dt><dt id="ientry-idm20833">xmlpi, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.7">xmlpi</a></dt><dt id="ientry-idm20854">xmlroot, <a class="indexterm" href="functions-xml.html#id-1.5.8.21.5.8">xmlroot</a></dt><dt id="ientry-idm8662">xmlserialize, <a class="indexterm" href="datatype-xml.html#id-1.5.7.21.6">Creating XML Values</a></dt><dt id="ientry-idm21043">xmltable, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-PROCESSING-XMLTABLE">xmltable</a></dt><dt id="ientry-idm20955">xml_is_well_formed, <a class="indexterm" href="functions-xml.html#XML-IS-WELL-FORMED">xml_is_well_formed</a></dt><dt id="ientry-idm20959">xml_is_well_formed_content, <a class="indexterm" href="functions-xml.html#XML-IS-WELL-FORMED">xml_is_well_formed</a></dt><dt id="ientry-idm20957">xml_is_well_formed_document, <a class="indexterm" href="functions-xml.html#XML-IS-WELL-FORMED">xml_is_well_formed</a></dt><dt id="ientry-idm20994">XPath, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-PROCESSING-XPATH">xpath</a></dt><dt id="ientry-idm21022">xpath_exists, <a class="indexterm" href="functions-xml.html#FUNCTIONS-XML-PROCESSING-XPATH-EXISTS">xpath_exists</a></dt><dt id="ientry-idm172961">xpath_table, <a class="indexterm" href="xml2.html#id-1.11.7.59.6">xpath_table</a></dt><dt id="ientry-idm15774">XQuery regular expressions, <a class="indexterm" href="functions-matching.html#POSIX-VS-XQUERY">Differences from SQL Standard and XQuery</a></dt><dt id="ientry-idm173042">xslt_process, <a class="indexterm" href="xml2.html#id-1.11.7.59.7.3">xslt_process</a></dt></dl></div><div class="indexdiv" id="indexdiv-Y"><h3>Y</h3><dl><dt id="ientry-idm35398">yacc, <a class="indexterm" href="install-requirements.html">Requirements</a></dt></dl></div><div class="indexdiv" id="indexdiv-Z"><h3>Z</h3><dl><dt id="ientry-idm44641">zero_damaged_pages configuration parameter, <a class="indexterm" href="runtime-config-developer.html">Developer Options</a></dt><dt id="ientry-idm35298">zlib, <a class="indexterm" href="install-requirements.html">Requirements</a>, <a class="indexterm" href="install-procedure.html#CONFIGURE-OPTIONS-ANTI-FEATURES">Anti-Features</a></dt></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="biblio.html" title="Bibliography">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Bibliography </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/brin-builtin-opclasses.html b/doc/src/sgml/html/brin-builtin-opclasses.html
new file mode 100644
index 0000000..50dfb55
--- /dev/null
+++ b/doc/src/sgml/html/brin-builtin-opclasses.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>71.2. Built-in Operator Classes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="brin-intro.html" title="71.1. Introduction" /><link rel="next" href="brin-extensibility.html" title="71.3. Extensibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">71.2. Built-in Operator Classes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="brin-intro.html" title="71.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><th width="60%" align="center">Chapter 71. BRIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="brin-extensibility.html" title="71.3. Extensibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="BRIN-BUILTIN-OPCLASSES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">71.2. Built-in Operator Classes</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="brin-builtin-opclasses.html#BRIN-BUILTIN-OPCLASSES--PARAMETERS">71.2.1. Operator Class Parameters</a></span></dt></dl></div><p>
+ The core <span class="productname">PostgreSQL</span> distribution
+ includes the <acronym class="acronym">BRIN</acronym> operator classes shown in
+ <a class="xref" href="brin-builtin-opclasses.html#BRIN-BUILTIN-OPCLASSES-TABLE" title="Table 71.1. Built-in BRIN Operator Classes">Table 71.1</a>.
+ </p><p>
+ The <em class="firstterm">minmax</em>
+ operator classes store the minimum and the maximum values appearing
+ in the indexed column within the range. The <em class="firstterm">inclusion</em>
+ operator classes store a value which includes the values in the indexed
+ column within the range. The <em class="firstterm">bloom</em> operator
+ classes build a Bloom filter for all values in the range. The
+ <em class="firstterm">minmax-multi</em> operator classes store multiple
+ minimum and maximum values, representing values appearing in the indexed
+ column within the range.
+ </p><div class="table" id="BRIN-BUILTIN-OPCLASSES-TABLE"><p class="title"><strong>Table 71.1. Built-in <acronym class="acronym">BRIN</acronym> Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Built-in BRIN Operator Classes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Indexable Operators</th></tr></thead><tbody><tr><td rowspan="5" valign="middle"><code class="literal">bit_minmax_ops</code></td><td><code class="literal">= (bit,bit)</code></td></tr><tr><td><code class="literal">&lt; (bit,bit)</code></td></tr><tr><td><code class="literal">&gt; (bit,bit)</code></td></tr><tr><td><code class="literal">&lt;= (bit,bit)</code></td></tr><tr><td><code class="literal">&gt;= (bit,bit)</code></td></tr><tr><td rowspan="13" valign="middle"><code class="literal">box_inclusion_ops</code></td><td><code class="literal">@&gt; (box,point)</code></td></tr><tr><td><code class="literal">&lt;&lt; (box,box)</code></td></tr><tr><td><code class="literal">&amp;&lt; (box,box)</code></td></tr><tr><td><code class="literal">&amp;&gt; (box,box)</code></td></tr><tr><td><code class="literal">&gt;&gt; (box,box)</code></td></tr><tr><td><code class="literal">&lt;@ (box,box)</code></td></tr><tr><td><code class="literal">@&gt; (box,box)</code></td></tr><tr><td><code class="literal">~= (box,box)</code></td></tr><tr><td><code class="literal">&amp;&amp; (box,box)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (box,box)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (box,box)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (box,box)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (box,box)</code></td></tr><tr><td valign="middle"><code class="literal">bpchar_bloom_ops</code></td><td><code class="literal">= (character,character)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">bpchar_minmax_ops</code></td><td><code class="literal">= (character,character)</code></td></tr><tr><td><code class="literal">&lt; (character,character)</code></td></tr><tr><td><code class="literal">&lt;= (character,character)</code></td></tr><tr><td><code class="literal">&gt; (character,character)</code></td></tr><tr><td><code class="literal">&gt;= (character,character)</code></td></tr><tr><td valign="middle"><code class="literal">bytea_bloom_ops</code></td><td><code class="literal">= (bytea,bytea)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">bytea_minmax_ops</code></td><td><code class="literal">= (bytea,bytea)</code></td></tr><tr><td><code class="literal">&lt; (bytea,bytea)</code></td></tr><tr><td><code class="literal">&lt;= (bytea,bytea)</code></td></tr><tr><td><code class="literal">&gt; (bytea,bytea)</code></td></tr><tr><td><code class="literal">&gt;= (bytea,bytea)</code></td></tr><tr><td valign="middle"><code class="literal">char_bloom_ops</code></td><td><code class="literal">= ("char","char")</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">char_minmax_ops</code></td><td><code class="literal">= ("char","char")</code></td></tr><tr><td><code class="literal">&lt; ("char","char")</code></td></tr><tr><td><code class="literal">&lt;= ("char","char")</code></td></tr><tr><td><code class="literal">&gt; ("char","char")</code></td></tr><tr><td><code class="literal">&gt;= ("char","char")</code></td></tr><tr><td valign="middle"><code class="literal">date_bloom_ops</code></td><td><code class="literal">= (date,date)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">date_minmax_ops</code></td><td><code class="literal">= (date,date)</code></td></tr><tr><td><code class="literal">&lt; (date,date)</code></td></tr><tr><td><code class="literal">&lt;= (date,date)</code></td></tr><tr><td><code class="literal">&gt; (date,date)</code></td></tr><tr><td><code class="literal">&gt;= (date,date)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">date_minmax_multi_ops</code></td><td><code class="literal">= (date,date)</code></td></tr><tr><td><code class="literal">&lt; (date,date)</code></td></tr><tr><td><code class="literal">&lt;= (date,date)</code></td></tr><tr><td><code class="literal">&gt; (date,date)</code></td></tr><tr><td><code class="literal">&gt;= (date,date)</code></td></tr><tr><td valign="middle"><code class="literal">float4_bloom_ops</code></td><td><code class="literal">= (float4,float4)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">float4_minmax_ops</code></td><td><code class="literal">= (float4,float4)</code></td></tr><tr><td><code class="literal">&lt; (float4,float4)</code></td></tr><tr><td><code class="literal">&gt; (float4,float4)</code></td></tr><tr><td><code class="literal">&lt;= (float4,float4)</code></td></tr><tr><td><code class="literal">&gt;= (float4,float4)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">float4_minmax_multi_ops</code></td><td><code class="literal">= (float4,float4)</code></td></tr><tr><td><code class="literal">&lt; (float4,float4)</code></td></tr><tr><td><code class="literal">&gt; (float4,float4)</code></td></tr><tr><td><code class="literal">&lt;= (float4,float4)</code></td></tr><tr><td><code class="literal">&gt;= (float4,float4)</code></td></tr><tr><td valign="middle"><code class="literal">float8_bloom_ops</code></td><td><code class="literal">= (float8,float8)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">float8_minmax_ops</code></td><td><code class="literal">= (float8,float8)</code></td></tr><tr><td><code class="literal">&lt; (float8,float8)</code></td></tr><tr><td><code class="literal">&lt;= (float8,float8)</code></td></tr><tr><td><code class="literal">&gt; (float8,float8)</code></td></tr><tr><td><code class="literal">&gt;= (float8,float8)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">float8_minmax_multi_ops</code></td><td><code class="literal">= (float8,float8)</code></td></tr><tr><td><code class="literal">&lt; (float8,float8)</code></td></tr><tr><td><code class="literal">&lt;= (float8,float8)</code></td></tr><tr><td><code class="literal">&gt; (float8,float8)</code></td></tr><tr><td><code class="literal">&gt;= (float8,float8)</code></td></tr><tr><td rowspan="6" valign="middle"><code class="literal">inet_inclusion_ops</code></td><td><code class="literal">&lt;&lt; (inet,inet)</code></td></tr><tr><td><code class="literal">&lt;&lt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;&gt;= (inet,inet)</code></td></tr><tr><td><code class="literal">= (inet,inet)</code></td></tr><tr><td><code class="literal">&amp;&amp; (inet,inet)</code></td></tr><tr><td valign="middle"><code class="literal">inet_bloom_ops</code></td><td><code class="literal">= (inet,inet)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">inet_minmax_ops</code></td><td><code class="literal">= (inet,inet)</code></td></tr><tr><td><code class="literal">&lt; (inet,inet)</code></td></tr><tr><td><code class="literal">&lt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;= (inet,inet)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">inet_minmax_multi_ops</code></td><td><code class="literal">= (inet,inet)</code></td></tr><tr><td><code class="literal">&lt; (inet,inet)</code></td></tr><tr><td><code class="literal">&lt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;= (inet,inet)</code></td></tr><tr><td valign="middle"><code class="literal">int2_bloom_ops</code></td><td><code class="literal">= (int2,int2)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int2_minmax_ops</code></td><td><code class="literal">= (int2,int2)</code></td></tr><tr><td><code class="literal">&lt; (int2,int2)</code></td></tr><tr><td><code class="literal">&gt; (int2,int2)</code></td></tr><tr><td><code class="literal">&lt;= (int2,int2)</code></td></tr><tr><td><code class="literal">&gt;= (int2,int2)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int2_minmax_multi_ops</code></td><td><code class="literal">= (int2,int2)</code></td></tr><tr><td><code class="literal">&lt; (int2,int2)</code></td></tr><tr><td><code class="literal">&gt; (int2,int2)</code></td></tr><tr><td><code class="literal">&lt;= (int2,int2)</code></td></tr><tr><td><code class="literal">&gt;= (int2,int2)</code></td></tr><tr><td valign="middle"><code class="literal">int4_bloom_ops</code></td><td><code class="literal">= (int4,int4)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int4_minmax_ops</code></td><td><code class="literal">= (int4,int4)</code></td></tr><tr><td><code class="literal">&lt; (int4,int4)</code></td></tr><tr><td><code class="literal">&gt; (int4,int4)</code></td></tr><tr><td><code class="literal">&lt;= (int4,int4)</code></td></tr><tr><td><code class="literal">&gt;= (int4,int4)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int4_minmax_multi_ops</code></td><td><code class="literal">= (int4,int4)</code></td></tr><tr><td><code class="literal">&lt; (int4,int4)</code></td></tr><tr><td><code class="literal">&gt; (int4,int4)</code></td></tr><tr><td><code class="literal">&lt;= (int4,int4)</code></td></tr><tr><td><code class="literal">&gt;= (int4,int4)</code></td></tr><tr><td valign="middle"><code class="literal">int8_bloom_ops</code></td><td><code class="literal">= (bigint,bigint)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int8_minmax_ops</code></td><td><code class="literal">= (bigint,bigint)</code></td></tr><tr><td><code class="literal">&lt; (bigint,bigint)</code></td></tr><tr><td><code class="literal">&gt; (bigint,bigint)</code></td></tr><tr><td><code class="literal">&lt;= (bigint,bigint)</code></td></tr><tr><td><code class="literal">&gt;= (bigint,bigint)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">int8_minmax_multi_ops</code></td><td><code class="literal">= (bigint,bigint)</code></td></tr><tr><td><code class="literal">&lt; (bigint,bigint)</code></td></tr><tr><td><code class="literal">&gt; (bigint,bigint)</code></td></tr><tr><td><code class="literal">&lt;= (bigint,bigint)</code></td></tr><tr><td><code class="literal">&gt;= (bigint,bigint)</code></td></tr><tr><td valign="middle"><code class="literal">interval_bloom_ops</code></td><td><code class="literal">= (interval,interval)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">interval_minmax_ops</code></td><td><code class="literal">= (interval,interval)</code></td></tr><tr><td><code class="literal">&lt; (interval,interval)</code></td></tr><tr><td><code class="literal">&lt;= (interval,interval)</code></td></tr><tr><td><code class="literal">&gt; (interval,interval)</code></td></tr><tr><td><code class="literal">&gt;= (interval,interval)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">interval_minmax_multi_ops</code></td><td><code class="literal">= (interval,interval)</code></td></tr><tr><td><code class="literal">&lt; (interval,interval)</code></td></tr><tr><td><code class="literal">&lt;= (interval,interval)</code></td></tr><tr><td><code class="literal">&gt; (interval,interval)</code></td></tr><tr><td><code class="literal">&gt;= (interval,interval)</code></td></tr><tr><td valign="middle"><code class="literal">macaddr_bloom_ops</code></td><td><code class="literal">= (macaddr,macaddr)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">macaddr_minmax_ops</code></td><td><code class="literal">= (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&lt; (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&lt;= (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&gt; (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&gt;= (macaddr,macaddr)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">macaddr_minmax_multi_ops</code></td><td><code class="literal">= (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&lt; (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&lt;= (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&gt; (macaddr,macaddr)</code></td></tr><tr><td><code class="literal">&gt;= (macaddr,macaddr)</code></td></tr><tr><td valign="middle"><code class="literal">macaddr8_bloom_ops</code></td><td><code class="literal">= (macaddr8,macaddr8)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">macaddr8_minmax_ops</code></td><td><code class="literal">= (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&lt; (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&lt;= (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&gt; (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&gt;= (macaddr8,macaddr8)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">macaddr8_minmax_multi_ops</code></td><td><code class="literal">= (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&lt; (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&lt;= (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&gt; (macaddr8,macaddr8)</code></td></tr><tr><td><code class="literal">&gt;= (macaddr8,macaddr8)</code></td></tr><tr><td valign="middle"><code class="literal">name_bloom_ops</code></td><td><code class="literal">= (name,name)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">name_minmax_ops</code></td><td><code class="literal">= (name,name)</code></td></tr><tr><td><code class="literal">&lt; (name,name)</code></td></tr><tr><td><code class="literal">&lt;= (name,name)</code></td></tr><tr><td><code class="literal">&gt; (name,name)</code></td></tr><tr><td><code class="literal">&gt;= (name,name)</code></td></tr><tr><td valign="middle"><code class="literal">numeric_bloom_ops</code></td><td><code class="literal">= (numeric,numeric)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">numeric_minmax_ops</code></td><td><code class="literal">= (numeric,numeric)</code></td></tr><tr><td><code class="literal">&lt; (numeric,numeric)</code></td></tr><tr><td><code class="literal">&lt;= (numeric,numeric)</code></td></tr><tr><td><code class="literal">&gt; (numeric,numeric)</code></td></tr><tr><td><code class="literal">&gt;= (numeric,numeric)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">numeric_minmax_multi_ops</code></td><td><code class="literal">= (numeric,numeric)</code></td></tr><tr><td><code class="literal">&lt; (numeric,numeric)</code></td></tr><tr><td><code class="literal">&lt;= (numeric,numeric)</code></td></tr><tr><td><code class="literal">&gt; (numeric,numeric)</code></td></tr><tr><td><code class="literal">&gt;= (numeric,numeric)</code></td></tr><tr><td valign="middle"><code class="literal">oid_bloom_ops</code></td><td><code class="literal">= (oid,oid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">oid_minmax_ops</code></td><td><code class="literal">= (oid,oid)</code></td></tr><tr><td><code class="literal">&lt; (oid,oid)</code></td></tr><tr><td><code class="literal">&gt; (oid,oid)</code></td></tr><tr><td><code class="literal">&lt;= (oid,oid)</code></td></tr><tr><td><code class="literal">&gt;= (oid,oid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">oid_minmax_multi_ops</code></td><td><code class="literal">= (oid,oid)</code></td></tr><tr><td><code class="literal">&lt; (oid,oid)</code></td></tr><tr><td><code class="literal">&gt; (oid,oid)</code></td></tr><tr><td><code class="literal">&lt;= (oid,oid)</code></td></tr><tr><td><code class="literal">&gt;= (oid,oid)</code></td></tr><tr><td valign="middle"><code class="literal">pg_lsn_bloom_ops</code></td><td><code class="literal">= (pg_lsn,pg_lsn)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">pg_lsn_minmax_ops</code></td><td><code class="literal">= (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&lt; (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&gt; (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&lt;= (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&gt;= (pg_lsn,pg_lsn)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">pg_lsn_minmax_multi_ops</code></td><td><code class="literal">= (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&lt; (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&gt; (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&lt;= (pg_lsn,pg_lsn)</code></td></tr><tr><td><code class="literal">&gt;= (pg_lsn,pg_lsn)</code></td></tr><tr><td rowspan="14" valign="middle"><code class="literal">range_inclusion_ops</code></td><td><code class="literal">= (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt;= (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&gt;= (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&amp;&amp; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange,anyelement)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt;@ (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">-|- (anyrange,anyrange)</code></td></tr><tr><td valign="middle"><code class="literal">text_bloom_ops</code></td><td><code class="literal">= (text,text)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">text_minmax_ops</code></td><td><code class="literal">= (text,text)</code></td></tr><tr><td><code class="literal">&lt; (text,text)</code></td></tr><tr><td><code class="literal">&lt;= (text,text)</code></td></tr><tr><td><code class="literal">&gt; (text,text)</code></td></tr><tr><td><code class="literal">&gt;= (text,text)</code></td></tr><tr><td valign="middle"><code class="literal">tid_bloom_ops</code></td><td><code class="literal">= (tid,tid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">tid_minmax_ops</code></td><td><code class="literal">= (tid,tid)</code></td></tr><tr><td><code class="literal">&lt; (tid,tid)</code></td></tr><tr><td><code class="literal">&gt; (tid,tid)</code></td></tr><tr><td><code class="literal">&lt;= (tid,tid)</code></td></tr><tr><td><code class="literal">&gt;= (tid,tid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">tid_minmax_multi_ops</code></td><td><code class="literal">= (tid,tid)</code></td></tr><tr><td><code class="literal">&lt; (tid,tid)</code></td></tr><tr><td><code class="literal">&gt; (tid,tid)</code></td></tr><tr><td><code class="literal">&lt;= (tid,tid)</code></td></tr><tr><td><code class="literal">&gt;= (tid,tid)</code></td></tr><tr><td valign="middle"><code class="literal">timestamp_bloom_ops</code></td><td><code class="literal">= (timestamp,timestamp)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timestamp_minmax_ops</code></td><td><code class="literal">= (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&lt; (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&lt;= (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&gt; (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&gt;= (timestamp,timestamp)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timestamp_minmax_multi_ops</code></td><td><code class="literal">= (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&lt; (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&lt;= (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&gt; (timestamp,timestamp)</code></td></tr><tr><td><code class="literal">&gt;= (timestamp,timestamp)</code></td></tr><tr><td valign="middle"><code class="literal">timestamptz_bloom_ops</code></td><td><code class="literal">= (timestamptz,timestamptz)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timestamptz_minmax_ops</code></td><td><code class="literal">= (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&lt; (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&lt;= (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&gt; (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&gt;= (timestamptz,timestamptz)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timestamptz_minmax_multi_ops</code></td><td><code class="literal">= (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&lt; (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&lt;= (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&gt; (timestamptz,timestamptz)</code></td></tr><tr><td><code class="literal">&gt;= (timestamptz,timestamptz)</code></td></tr><tr><td valign="middle"><code class="literal">time_bloom_ops</code></td><td><code class="literal">= (time,time)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">time_minmax_ops</code></td><td><code class="literal">= (time,time)</code></td></tr><tr><td><code class="literal">&lt; (time,time)</code></td></tr><tr><td><code class="literal">&lt;= (time,time)</code></td></tr><tr><td><code class="literal">&gt; (time,time)</code></td></tr><tr><td><code class="literal">&gt;= (time,time)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">time_minmax_multi_ops</code></td><td><code class="literal">= (time,time)</code></td></tr><tr><td><code class="literal">&lt; (time,time)</code></td></tr><tr><td><code class="literal">&lt;= (time,time)</code></td></tr><tr><td><code class="literal">&gt; (time,time)</code></td></tr><tr><td><code class="literal">&gt;= (time,time)</code></td></tr><tr><td valign="middle"><code class="literal">timetz_bloom_ops</code></td><td><code class="literal">= (timetz,timetz)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timetz_minmax_ops</code></td><td><code class="literal">= (timetz,timetz)</code></td></tr><tr><td><code class="literal">&lt; (timetz,timetz)</code></td></tr><tr><td><code class="literal">&lt;= (timetz,timetz)</code></td></tr><tr><td><code class="literal">&gt; (timetz,timetz)</code></td></tr><tr><td><code class="literal">&gt;= (timetz,timetz)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">timetz_minmax_multi_ops</code></td><td><code class="literal">= (timetz,timetz)</code></td></tr><tr><td><code class="literal">&lt; (timetz,timetz)</code></td></tr><tr><td><code class="literal">&lt;= (timetz,timetz)</code></td></tr><tr><td><code class="literal">&gt; (timetz,timetz)</code></td></tr><tr><td><code class="literal">&gt;= (timetz,timetz)</code></td></tr><tr><td valign="middle"><code class="literal">uuid_bloom_ops</code></td><td><code class="literal">= (uuid,uuid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">uuid_minmax_ops</code></td><td><code class="literal">= (uuid,uuid)</code></td></tr><tr><td><code class="literal">&lt; (uuid,uuid)</code></td></tr><tr><td><code class="literal">&gt; (uuid,uuid)</code></td></tr><tr><td><code class="literal">&lt;= (uuid,uuid)</code></td></tr><tr><td><code class="literal">&gt;= (uuid,uuid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">uuid_minmax_multi_ops</code></td><td><code class="literal">= (uuid,uuid)</code></td></tr><tr><td><code class="literal">&lt; (uuid,uuid)</code></td></tr><tr><td><code class="literal">&gt; (uuid,uuid)</code></td></tr><tr><td><code class="literal">&lt;= (uuid,uuid)</code></td></tr><tr><td><code class="literal">&gt;= (uuid,uuid)</code></td></tr><tr><td rowspan="5" valign="middle"><code class="literal">varbit_minmax_ops</code></td><td><code class="literal">= (varbit,varbit)</code></td></tr><tr><td><code class="literal">&lt; (varbit,varbit)</code></td></tr><tr><td><code class="literal">&gt; (varbit,varbit)</code></td></tr><tr><td><code class="literal">&lt;= (varbit,varbit)</code></td></tr><tr><td><code class="literal">&gt;= (varbit,varbit)</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="sect2" id="BRIN-BUILTIN-OPCLASSES--PARAMETERS"><div class="titlepage"><div><div><h3 class="title">71.2.1. Operator Class Parameters</h3></div></div></div><p>
+ Some of the built-in operator classes allow specifying parameters affecting
+ behavior of the operator class. Each operator class has its own set of
+ allowed parameters. Only the <code class="literal">bloom</code> and <code class="literal">minmax-multi</code>
+ operator classes allow specifying parameters:
+ </p><p>
+ bloom operator classes accept these parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">n_distinct_per_range</code></span></dt><dd><p>
+ Defines the estimated number of distinct non-null values in the block
+ range, used by <acronym class="acronym">BRIN</acronym> bloom indexes for sizing of the
+ Bloom filter. It behaves similarly to <code class="literal">n_distinct</code> option
+ for <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>. When set to a positive value,
+ each block range is assumed to contain this number of distinct non-null
+ values. When set to a negative value, which must be greater than or
+ equal to -1, the number of distinct non-null values is assumed to grow linearly with
+ the maximum possible number of tuples in the block range (about 290
+ rows per block). The default value is <code class="literal">-0.1</code>, and
+ the minimum number of distinct non-null values is <code class="literal">16</code>.
+ </p></dd><dt><span class="term"><code class="literal">false_positive_rate</code></span></dt><dd><p>
+ Defines the desired false positive rate used by <acronym class="acronym">BRIN</acronym>
+ bloom indexes for sizing of the Bloom filter. The values must be
+ between 0.0001 and 0.25. The default value is 0.01, which is 1% false
+ positive rate.
+ </p></dd></dl></div><p>
+ minmax-multi operator classes accept these parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">values_per_range</code></span></dt><dd><p>
+ Defines the maximum number of values stored by <acronym class="acronym">BRIN</acronym>
+ minmax indexes to summarize a block range. Each value may represent
+ either a point, or a boundary of an interval. Values must be between
+ 8 and 256, and the default value is 32.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="brin-intro.html" title="71.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="brin-extensibility.html" title="71.3. Extensibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">71.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 71.3. Extensibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/brin-extensibility.html b/doc/src/sgml/html/brin-extensibility.html
new file mode 100644
index 0000000..206afcf
--- /dev/null
+++ b/doc/src/sgml/html/brin-extensibility.html
@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>71.3. Extensibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes" /><link rel="next" href="hash-index.html" title="Chapter 72. Hash Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">71.3. Extensibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><th width="60%" align="center">Chapter 71. BRIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="hash-index.html" title="Chapter 72. Hash Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="BRIN-EXTENSIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">71.3. Extensibility</h2></div></div></div><p>
+ The <acronym class="acronym">BRIN</acronym> interface has a high level of abstraction,
+ requiring the access method implementer only to implement the semantics
+ of the data type being accessed. The <acronym class="acronym">BRIN</acronym> layer
+ itself takes care of concurrency, logging and searching the index structure.
+ </p><p>
+ All it takes to get a <acronym class="acronym">BRIN</acronym> access method working is to
+ implement a few user-defined methods, which define the behavior of
+ summary values stored in the index and the way they interact with
+ scan keys.
+ In short, <acronym class="acronym">BRIN</acronym> combines
+ extensibility with generality, code reuse, and a clean interface.
+ </p><p>
+ There are four methods that an operator class for <acronym class="acronym">BRIN</acronym>
+ must provide:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">BrinOpcInfo *opcInfo(Oid type_oid)</code></span></dt><dd><p>
+ Returns internal information about the indexed columns' summary data.
+ The return value must point to a palloc'd <code class="structname">BrinOpcInfo</code>,
+ which has this definition:
+</p><pre class="programlisting">
+typedef struct BrinOpcInfo
+{
+ /* Number of columns stored in an index column of this opclass */
+ uint16 oi_nstored;
+
+ /* Opaque pointer for the opclass' private use */
+ void *oi_opaque;
+
+ /* Type cache entries of the stored columns */
+ TypeCacheEntry *oi_typcache[FLEXIBLE_ARRAY_MEMBER];
+} BrinOpcInfo;
+</pre><p>
+ <code class="structname">BrinOpcInfo</code>.<code class="structfield">oi_opaque</code> can be used by the
+ operator class routines to pass information between support functions
+ during an index scan.
+ </p></dd><dt><span class="term"><code class="function">bool consistent(BrinDesc *bdesc, BrinValues *column,
+ ScanKey *keys, int nkeys)</code></span></dt><dd><p>
+ Returns whether all the ScanKey entries are consistent with the given
+ indexed values for a range.
+ The attribute number to use is passed as part of the scan key.
+ Multiple scan keys for the same attribute may be passed at once; the
+ number of entries is determined by the <code class="literal">nkeys</code> parameter.
+ </p></dd><dt><span class="term"><code class="function">bool consistent(BrinDesc *bdesc, BrinValues *column,
+ ScanKey key)</code></span></dt><dd><p>
+ Returns whether the ScanKey is consistent with the given indexed
+ values for a range.
+ The attribute number to use is passed as part of the scan key.
+ This is an older backward-compatible variant of the consistent function.
+ </p></dd><dt><span class="term"><code class="function">bool addValue(BrinDesc *bdesc, BrinValues *column,
+ Datum newval, bool isnull)</code></span></dt><dd><p>
+ Given an index tuple and an indexed value, modifies the indicated
+ attribute of the tuple so that it additionally represents the new value.
+ If any modification was done to the tuple, <code class="literal">true</code> is
+ returned.
+ </p></dd><dt><span class="term"><code class="function">bool unionTuples(BrinDesc *bdesc, BrinValues *a,
+ BrinValues *b)</code></span></dt><dd><p>
+ Consolidates two index tuples. Given two index tuples, modifies the
+ indicated attribute of the first of them so that it represents both tuples.
+ The second tuple is not modified.
+ </p></dd></dl></div><p>
+
+ An operator class for <acronym class="acronym">BRIN</acronym> can optionally specify the
+ following method:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">void options(local_relopts *relopts)</code></span></dt><dd><p>
+ Defines a set of user-visible parameters that control operator class
+ behavior.
+ </p><p>
+ The <code class="function">options</code> function is passed a pointer to a
+ <code class="structname">local_relopts</code> struct, which needs to be
+ filled with a set of operator class specific options. The options
+ can be accessed from other support functions using the
+ <code class="literal">PG_HAS_OPCLASS_OPTIONS()</code> and
+ <code class="literal">PG_GET_OPCLASS_OPTIONS()</code> macros.
+ </p><p>
+ Since both key extraction of indexed values and representation of the
+ key in <acronym class="acronym">BRIN</acronym> are flexible, they may depend on
+ user-specified parameters.
+ </p></dd></dl></div><p>
+
+ The core distribution includes support for four types of operator classes:
+ minmax, minmax-multi, inclusion and bloom. Operator class definitions
+ using them are shipped for in-core data types as appropriate. Additional
+ operator classes can be defined by the user for other data types using
+ equivalent definitions, without having to write any source code;
+ appropriate catalog entries being declared is enough. Note that
+ assumptions about the semantics of operator strategies are embedded in the
+ support functions' source code.
+ </p><p>
+ Operator classes that implement completely different semantics are also
+ possible, provided implementations of the four main support functions
+ described above are written. Note that backwards compatibility across major
+ releases is not guaranteed: for example, additional support functions might
+ be required in later releases.
+ </p><p>
+ To write an operator class for a data type that implements a totally
+ ordered set, it is possible to use the minmax support functions
+ alongside the corresponding operators, as shown in
+ <a class="xref" href="brin-extensibility.html#BRIN-EXTENSIBILITY-MINMAX-TABLE" title="Table 71.2. Function and Support Numbers for Minmax Operator Classes">Table 71.2</a>.
+ All operator class members (functions and operators) are mandatory.
+ </p><div class="table" id="BRIN-EXTENSIBILITY-MINMAX-TABLE"><p class="title"><strong>Table 71.2. Function and Support Numbers for Minmax Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Function and Support Numbers for Minmax Operator Classes" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Operator class member</th><th>Object</th></tr></thead><tbody><tr><td>Support Function 1</td><td>internal function <code class="function">brin_minmax_opcinfo()</code></td></tr><tr><td>Support Function 2</td><td>internal function <code class="function">brin_minmax_add_value()</code></td></tr><tr><td>Support Function 3</td><td>internal function <code class="function">brin_minmax_consistent()</code></td></tr><tr><td>Support Function 4</td><td>internal function <code class="function">brin_minmax_union()</code></td></tr><tr><td>Operator Strategy 1</td><td>operator less-than</td></tr><tr><td>Operator Strategy 2</td><td>operator less-than-or-equal-to</td></tr><tr><td>Operator Strategy 3</td><td>operator equal-to</td></tr><tr><td>Operator Strategy 4</td><td>operator greater-than-or-equal-to</td></tr><tr><td>Operator Strategy 5</td><td>operator greater-than</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ 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
+ functions alongside the corresponding operators, as shown
+ in <a class="xref" href="brin-extensibility.html#BRIN-EXTENSIBILITY-INCLUSION-TABLE" title="Table 71.3. Function and Support Numbers for Inclusion Operator Classes">Table 71.3</a>. 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
+ dependencies on the table.
+ </p><div class="table" id="BRIN-EXTENSIBILITY-INCLUSION-TABLE"><p class="title"><strong>Table 71.3. Function and Support Numbers for Inclusion Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Function and Support Numbers for Inclusion Operator Classes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Operator class member</th><th>Object</th><th>Dependency</th></tr></thead><tbody><tr><td>Support Function 1</td><td>internal function <code class="function">brin_inclusion_opcinfo()</code></td><td> </td></tr><tr><td>Support Function 2</td><td>internal function <code class="function">brin_inclusion_add_value()</code></td><td> </td></tr><tr><td>Support Function 3</td><td>internal function <code class="function">brin_inclusion_consistent()</code></td><td> </td></tr><tr><td>Support Function 4</td><td>internal function <code class="function">brin_inclusion_union()</code></td><td> </td></tr><tr><td>Support Function 11</td><td>function to merge two elements</td><td> </td></tr><tr><td>Support Function 12</td><td>optional function to check whether two elements are mergeable</td><td> </td></tr><tr><td>Support Function 13</td><td>optional function to check if an element is contained within another</td><td> </td></tr><tr><td>Support Function 14</td><td>optional function to check whether an element is empty</td><td> </td></tr><tr><td>Operator Strategy 1</td><td>operator left-of</td><td>Operator Strategy 4</td></tr><tr><td>Operator Strategy 2</td><td>operator does-not-extend-to-the-right-of</td><td>Operator Strategy 5</td></tr><tr><td>Operator Strategy 3</td><td>operator overlaps</td><td> </td></tr><tr><td>Operator Strategy 4</td><td>operator does-not-extend-to-the-left-of</td><td>Operator Strategy 1</td></tr><tr><td>Operator Strategy 5</td><td>operator right-of</td><td>Operator Strategy 2</td></tr><tr><td>Operator Strategy 6, 18</td><td>operator same-as-or-equal-to</td><td>Operator Strategy 7</td></tr><tr><td>Operator Strategy 7, 16, 24, 25</td><td>operator contains-or-equal-to</td><td> </td></tr><tr><td>Operator Strategy 8, 26, 27</td><td>operator is-contained-by-or-equal-to</td><td>Operator Strategy 3</td></tr><tr><td>Operator Strategy 9</td><td>operator does-not-extend-above</td><td>Operator Strategy 11</td></tr><tr><td>Operator Strategy 10</td><td>operator is-below</td><td>Operator Strategy 12</td></tr><tr><td>Operator Strategy 11</td><td>operator is-above</td><td>Operator Strategy 9</td></tr><tr><td>Operator Strategy 12</td><td>operator does-not-extend-below</td><td>Operator Strategy 10</td></tr><tr><td>Operator Strategy 20</td><td>operator less-than</td><td>Operator Strategy 5</td></tr><tr><td>Operator Strategy 21</td><td>operator less-than-or-equal-to</td><td>Operator Strategy 5</td></tr><tr><td>Operator Strategy 22</td><td>operator greater-than</td><td>Operator Strategy 1</td></tr><tr><td>Operator Strategy 23</td><td>operator greater-than-or-equal-to</td><td>Operator Strategy 1</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Support function numbers 1 through 10 are reserved for the BRIN internal
+ functions, so the SQL level functions start with number 11. Support
+ function number 11 is the main function required to build the index.
+ It should accept two arguments with the same data type as the operator class,
+ and return the union of them. The inclusion operator class can store union
+ values with different data types if it is defined with the
+ <code class="literal">STORAGE</code> parameter. The return value of the union
+ function should match the <code class="literal">STORAGE</code> data type.
+ </p><p>
+ Support function numbers 12 and 14 are provided to support
+ irregularities of built-in data types. Function number 12
+ is used to support network addresses from different families which
+ are not mergeable. Function number 14 is used to support
+ empty ranges. Function number 13 is an optional but
+ recommended one, which allows the new value to be checked before
+ it is passed to the union function. As the BRIN framework can shortcut
+ some operations when the union is not changed, using this
+ function can improve index performance.
+ </p><p>
+ To write an operator class for a data type that implements only an equality
+ operator and supports hashing, it is possible to use the bloom support procedures
+ alongside the corresponding operators, as shown in
+ <a class="xref" href="brin-extensibility.html#BRIN-EXTENSIBILITY-BLOOM-TABLE" title="Table 71.4. Procedure and Support Numbers for Bloom Operator Classes">Table 71.4</a>.
+ All operator class members (procedures and operators) are mandatory.
+ </p><div class="table" id="BRIN-EXTENSIBILITY-BLOOM-TABLE"><p class="title"><strong>Table 71.4. Procedure and Support Numbers for Bloom Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Procedure and Support Numbers for Bloom Operator Classes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operator class member</th><th>Object</th></tr></thead><tbody><tr><td>Support Procedure 1</td><td>internal function <code class="function">brin_bloom_opcinfo()</code></td></tr><tr><td>Support Procedure 2</td><td>internal function <code class="function">brin_bloom_add_value()</code></td></tr><tr><td>Support Procedure 3</td><td>internal function <code class="function">brin_bloom_consistent()</code></td></tr><tr><td>Support Procedure 4</td><td>internal function <code class="function">brin_bloom_union()</code></td></tr><tr><td>Support Procedure 5</td><td>internal function <code class="function">brin_bloom_options()</code></td></tr><tr><td>Support Procedure 11</td><td>function to compute hash of an element</td></tr><tr><td>Operator Strategy 1</td><td>operator equal-to</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Support procedure numbers 1-10 are reserved for the BRIN internal
+ functions, so the SQL level functions start with number 11. Support
+ function number 11 is the main function required to build the index.
+ It should accept one argument with the same data type as the operator class,
+ and return a hash of the value.
+ </p><p>
+ The minmax-multi operator class is also intended for data types implementing
+ a totally ordered set, and may be seen as a simple extension of the minmax
+ operator class. While minmax operator class summarizes values from each block
+ range into a single contiguous interval, minmax-multi allows summarization
+ into multiple smaller intervals to improve handling of outlier values.
+ It is possible to use the minmax-multi support procedures alongside the
+ corresponding operators, as shown in
+ <a class="xref" href="brin-extensibility.html#BRIN-EXTENSIBILITY-MINMAX-MULTI-TABLE" title="Table 71.5. Procedure and Support Numbers for minmax-multi Operator Classes">Table 71.5</a>.
+ All operator class members (procedures and operators) are mandatory.
+ </p><div class="table" id="BRIN-EXTENSIBILITY-MINMAX-MULTI-TABLE"><p class="title"><strong>Table 71.5. Procedure and Support Numbers for minmax-multi Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Procedure and Support Numbers for minmax-multi Operator Classes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operator class member</th><th>Object</th></tr></thead><tbody><tr><td>Support Procedure 1</td><td>internal function <code class="function">brin_minmax_multi_opcinfo()</code></td></tr><tr><td>Support Procedure 2</td><td>internal function <code class="function">brin_minmax_multi_add_value()</code></td></tr><tr><td>Support Procedure 3</td><td>internal function <code class="function">brin_minmax_multi_consistent()</code></td></tr><tr><td>Support Procedure 4</td><td>internal function <code class="function">brin_minmax_multi_union()</code></td></tr><tr><td>Support Procedure 5</td><td>internal function <code class="function">brin_minmax_multi_options()</code></td></tr><tr><td>Support Procedure 11</td><td>function to compute distance between two values (length of a range)</td></tr><tr><td>Operator Strategy 1</td><td>operator less-than</td></tr><tr><td>Operator Strategy 2</td><td>operator less-than-or-equal-to</td></tr><tr><td>Operator Strategy 3</td><td>operator equal-to</td></tr><tr><td>Operator Strategy 4</td><td>operator greater-than-or-equal-to</td></tr><tr><td>Operator Strategy 5</td><td>operator greater-than</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Both minmax and inclusion operator classes support cross-data-type
+ operators, though with these the dependencies become more complicated.
+ The minmax operator class requires a full set of operators to be
+ defined with both arguments having the same data type. It allows
+ 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
+ <a class="xref" href="brin-extensibility.html#BRIN-EXTENSIBILITY-INCLUSION-TABLE" title="Table 71.3. Function and Support Numbers for Inclusion Operator Classes">Table 71.3</a>, or the same
+ operator strategy as themselves. They require the dependency
+ operator to be defined with the <code class="literal">STORAGE</code> data type as the
+ left-hand-side argument and the other supported data type to be the
+ right-hand-side argument of the supported operator. See
+ <code class="literal">float4_minmax_ops</code> as an example of minmax, and
+ <code class="literal">box_inclusion_ops</code> as an example of inclusion.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hash-index.html" title="Chapter 72. Hash Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">71.2. Built-in Operator Classes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 72. Hash Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/brin-intro.html b/doc/src/sgml/html/brin-intro.html
new file mode 100644
index 0000000..8f56f6d
--- /dev/null
+++ b/doc/src/sgml/html/brin-intro.html
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>71.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="brin.html" title="Chapter 71. BRIN Indexes" /><link rel="next" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">71.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="brin.html" title="Chapter 71. BRIN Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><th width="60%" align="center">Chapter 71. BRIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes">Next</a></td></tr></table><hr /></div><div class="sect1" id="BRIN-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">71.1. Introduction</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="brin-intro.html#BRIN-OPERATION">71.1.1. Index Maintenance</a></span></dt></dl></div><p>
+ <acronym class="acronym">BRIN</acronym> stands for Block Range Index.
+ <acronym class="acronym">BRIN</acronym> is designed for handling very large tables
+ in which certain columns have some natural correlation with their
+ physical location within the table.
+ </p><p>
+ <acronym class="acronym">BRIN</acronym> works in terms of <em class="firstterm">block ranges</em>
+ (or <span class="quote">“<span class="quote">page ranges</span>”</span>).
+ A block range is a group of pages that are physically
+ adjacent in the table; for each block range, some summary info is stored
+ by the index.
+ For example, a table storing a store's sale orders might have
+ a date column on which each order was placed, and most of the time
+ the entries for earlier orders will appear earlier in the table as well;
+ a table storing a ZIP code column might have all codes for a city
+ grouped together naturally.
+ </p><p>
+ <acronym class="acronym">BRIN</acronym> indexes can satisfy queries via regular bitmap
+ index scans, and will return all tuples in all pages within each range if
+ the summary info stored by the index is <em class="firstterm">consistent</em> with the
+ query conditions.
+ The query executor is in charge of rechecking these tuples and discarding
+ those that do not match the query conditions — in other words, these
+ indexes are lossy.
+ Because a <acronym class="acronym">BRIN</acronym> index is very small, scanning the index
+ adds little overhead compared to a sequential scan, but may avoid scanning
+ large parts of the table that are known not to contain matching tuples.
+ </p><p>
+ The specific data that a <acronym class="acronym">BRIN</acronym> index will store,
+ as well as the specific queries that the index will be able to satisfy,
+ depend on the operator class selected for each column of the index.
+ Data types having a linear sort order can have operator classes that
+ store the minimum and maximum value within each block range, for instance;
+ geometrical types might store the bounding box for all the objects
+ in the block range.
+ </p><p>
+ The size of the block range is determined at index creation time by
+ the <code class="literal">pages_per_range</code> storage parameter. The number of index
+ entries will be equal to the size of the relation in pages divided by
+ the selected value for <code class="literal">pages_per_range</code>. Therefore, the smaller
+ the number, the larger the index becomes (because of the need to
+ store more index entries), but at the same time the summary data stored can
+ be more precise and more data blocks can be skipped during an index scan.
+ </p><div class="sect2" id="BRIN-OPERATION"><div class="titlepage"><div><div><h3 class="title">71.1.1. Index Maintenance</h3></div></div></div><p>
+ At the time of creation, all existing heap pages are scanned and a
+ summary index tuple is created for each range, including the
+ possibly-incomplete range at the end.
+ As new pages are filled with data, page ranges that are already
+ summarized will cause the summary information to be updated with data
+ from the new tuples.
+ When a new page is created that does not fall within the last
+ summarized range, the range that the new page belongs to
+ does not automatically acquire a summary tuple;
+ those tuples remain unsummarized until a summarization run is
+ invoked later, creating the initial summary for that range.
+ </p><p>
+ There are several ways to trigger the initial summarization of a page range.
+ If the table is vacuumed, either manually or by
+ <a class="link" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">autovacuum</a>, all existing unsummarized
+ page ranges are summarized.
+ Also, if the index's
+ <a class="xref" href="sql-createindex.html#INDEX-RELOPTION-AUTOSUMMARIZE">autosummarize</a> parameter is enabled,
+ which it isn't by default,
+ whenever autovacuum runs in that database, summarization will occur for all
+ unsummarized page ranges that have been filled,
+ regardless of whether the table itself is processed by autovacuum; see below.
+ </p><p>
+ Lastly, the following functions can be used:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td>
+ <code class="function">brin_summarize_new_values(regclass)</code>
+ which summarizes all unsummarized ranges;
+ </td></tr><tr><td>
+ <code class="function">brin_summarize_range(regclass, bigint)</code>
+ which summarizes only the range containing the given page,
+ if it is unsummarized.
+ </td></tr></table><p>
+ </p><p>
+ When autosummarization is enabled, a request is sent to
+ <code class="literal">autovacuum</code> to execute a targeted summarization
+ for a block range when an insertion is detected for the first item
+ of the first page of the next block range,
+ to be fulfilled the next time an autovacuum
+ worker finishes running in the
+ same database. If the request queue is full, the request is not recorded
+ and a message is sent to the server log:
+</p><pre class="screen">
+LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded
+</pre><p>
+ When this happens, the range will remain unsummarized until the next
+ regular vacuum run on the table, or one of the functions mentioned above
+ are invoked.
+ </p><p>
+ Conversely, a range can be de-summarized using the
+ <code class="function">brin_desummarize_range(regclass, bigint)</code> function,
+ which is useful when the index tuple is no longer a very good
+ representation because the existing values have changed.
+ See <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX" title="9.27.8. Index Maintenance Functions">Section 9.27.8</a> for details.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="brin.html" title="Chapter 71. BRIN Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="brin.html" title="Chapter 71. BRIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="brin-builtin-opclasses.html" title="71.2. Built-in Operator Classes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 71. BRIN Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 71.2. Built-in Operator Classes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/brin.html b/doc/src/sgml/html/brin.html
new file mode 100644
index 0000000..6e33cac
--- /dev/null
+++ b/doc/src/sgml/html/brin.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 71. BRIN Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-examples.html" title="70.7. Examples" /><link rel="next" href="brin-intro.html" title="71.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 71. BRIN Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-examples.html" title="70.7. Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="brin-intro.html" title="71.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="BRIN"><div class="titlepage"><div><div><h2 class="title">Chapter 71. BRIN Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="brin-intro.html">71.1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="brin-intro.html#BRIN-OPERATION">71.1.1. Index Maintenance</a></span></dt></dl></dd><dt><span class="sect1"><a href="brin-builtin-opclasses.html">71.2. Built-in Operator Classes</a></span></dt><dd><dl><dt><span class="sect2"><a href="brin-builtin-opclasses.html#BRIN-BUILTIN-OPCLASSES--PARAMETERS">71.2.1. Operator Class Parameters</a></span></dt></dl></dd><dt><span class="sect1"><a href="brin-extensibility.html">71.3. Extensibility</a></span></dt></dl></div><a id="id-1.10.22.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-examples.html" title="70.7. Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="brin-intro.html" title="71.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.7. Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 71.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-behavior.html b/doc/src/sgml/html/btree-behavior.html
new file mode 100644
index 0000000..b70228b
--- /dev/null
+++ b/doc/src/sgml/html/btree-behavior.html
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>67.2. Behavior of B-Tree Operator Classes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-intro.html" title="67.1. Introduction" /><link rel="next" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">67.2. Behavior of B-Tree Operator Classes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-intro.html" title="67.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><th width="60%" align="center">Chapter 67. B-Tree Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-BEHAVIOR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">67.2. Behavior of B-Tree Operator Classes</h2></div></div></div><p>
+ As shown in <a class="xref" href="xindex.html#XINDEX-BTREE-STRAT-TABLE" title="Table 38.3. B-Tree Strategies">Table 38.3</a>, a btree operator
+ class must provide five comparison operators,
+ <code class="literal">&lt;</code>,
+ <code class="literal">&lt;=</code>,
+ <code class="literal">=</code>,
+ <code class="literal">&gt;=</code> and
+ <code class="literal">&gt;</code>.
+ One might expect that <code class="literal">&lt;&gt;</code> should also be part of
+ the operator class, but it is not, because it would almost never be
+ useful to use a <code class="literal">&lt;&gt;</code> WHERE clause in an index
+ search. (For some purposes, the planner treats <code class="literal">&lt;&gt;</code>
+ as associated with a btree operator class; but it finds that operator via
+ the <code class="literal">=</code> operator's negator link, rather than
+ from <code class="structname">pg_amop</code>.)
+ </p><p>
+ When several data types share near-identical sorting semantics, their
+ operator classes can be grouped into an operator family. Doing so is
+ advantageous because it allows the planner to make deductions about
+ cross-type comparisons. Each operator class within the family should
+ contain the single-type operators (and associated support functions)
+ for its input data type, while cross-type comparison operators and
+ support functions are <span class="quote">“<span class="quote">loose</span>”</span> in the family. It is
+ recommendable that a complete set of cross-type operators be included
+ in the family, thus ensuring that the planner can represent any
+ comparison conditions that it deduces from transitivity.
+ </p><p>
+ There are some basic assumptions that a btree operator family must
+ satisfy:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ An <code class="literal">=</code> operator must be an equivalence relation; that
+ is, for all non-null values <em class="replaceable"><code>A</code></em>,
+ <em class="replaceable"><code>B</code></em>, <em class="replaceable"><code>C</code></em> of the
+ data type:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ <em class="replaceable"><code>A</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>A</code></em> is true
+ (<em class="firstterm">reflexive law</em>)
+ </p></li><li class="listitem"><p>
+ if <em class="replaceable"><code>A</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>B</code></em>,
+ then <em class="replaceable"><code>B</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>A</code></em>
+ (<em class="firstterm">symmetric law</em>)
+ </p></li><li class="listitem"><p>
+ if <em class="replaceable"><code>A</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>B</code></em> and <em class="replaceable"><code>B</code></em>
+ <code class="literal">=</code> <em class="replaceable"><code>C</code></em>,
+ then <em class="replaceable"><code>A</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>C</code></em>
+ (<em class="firstterm">transitive law</em>)
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ A <code class="literal">&lt;</code> operator must be a strong ordering relation;
+ that is, for all non-null values <em class="replaceable"><code>A</code></em>,
+ <em class="replaceable"><code>B</code></em>, <em class="replaceable"><code>C</code></em>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ <em class="replaceable"><code>A</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>A</code></em> is false
+ (<em class="firstterm">irreflexive law</em>)
+ </p></li><li class="listitem"><p>
+ if <em class="replaceable"><code>A</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>B</code></em>
+ and <em class="replaceable"><code>B</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>C</code></em>,
+ then <em class="replaceable"><code>A</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>C</code></em>
+ (<em class="firstterm">transitive law</em>)
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ Furthermore, the ordering is total; that is, for all non-null
+ values <em class="replaceable"><code>A</code></em>, <em class="replaceable"><code>B</code></em>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ exactly one of <em class="replaceable"><code>A</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>B</code></em>, <em class="replaceable"><code>A</code></em>
+ <code class="literal">=</code> <em class="replaceable"><code>B</code></em>, and
+ <em class="replaceable"><code>B</code></em> <code class="literal">&lt;</code>
+ <em class="replaceable"><code>A</code></em> is true
+ (<em class="firstterm">trichotomy law</em>)
+ </p></li></ul></div><p>
+
+ (The trichotomy law justifies the definition of the comparison support
+ function, of course.)
+ </p></li></ul></div><p>
+ The other three operators are defined in terms of <code class="literal">=</code>
+ and <code class="literal">&lt;</code> in the obvious way, and must act consistently
+ with them.
+ </p><p>
+ For an operator family supporting multiple data types, the above laws must
+ hold when <em class="replaceable"><code>A</code></em>, <em class="replaceable"><code>B</code></em>,
+ <em class="replaceable"><code>C</code></em> are taken from any data types in the family.
+ The transitive laws are the trickiest to ensure, as in cross-type
+ situations they represent statements that the behaviors of two or three
+ different operators are consistent.
+ As an example, it would not work to put <code class="type">float8</code>
+ and <code class="type">numeric</code> into the same operator family, at least not with
+ the current semantics that <code class="type">numeric</code> values are converted
+ to <code class="type">float8</code> for comparison to a <code class="type">float8</code>. Because
+ of the limited accuracy of <code class="type">float8</code>, this means there are
+ distinct <code class="type">numeric</code> values that will compare equal to the
+ same <code class="type">float8</code> value, and thus the transitive law would fail.
+ </p><p>
+ Another requirement for a multiple-data-type family is that any implicit
+ or binary-coercion casts that are defined between data types included in
+ the operator family must not change the associated sort ordering.
+ </p><p>
+ It should be fairly clear why a btree index requires these laws to hold
+ within a single data type: without them there is no ordering to arrange
+ the keys with. Also, index searches using a comparison key of a
+ different data type require comparisons to behave sanely across two
+ data types. The extensions to three or more data types within a family
+ are not strictly required by the btree index mechanism itself, but the
+ planner relies on them for optimization purposes.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-intro.html" title="67.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">67.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 67.3. B-Tree Support Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-gin.html b/doc/src/sgml/html/btree-gin.html
new file mode 100644
index 0000000..f79c46f
--- /dev/null
+++ b/doc/src/sgml/html/btree-gin.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.8. btree_gin</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bloom.html" title="F.7. bloom" /><link rel="next" href="btree-gist.html" title="F.9. btree_gist" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.8. btree_gin</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bloom.html" title="F.7. bloom">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-gist.html" title="F.9. btree_gist">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-GIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.8. btree_gin</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="btree-gin.html#id-1.11.7.17.6">F.8.1. Example Usage</a></span></dt><dt><span class="sect2"><a href="btree-gin.html#id-1.11.7.17.7">F.8.2. Authors</a></span></dt></dl></div><a id="id-1.11.7.17.2" class="indexterm"></a><p>
+ <code class="filename">btree_gin</code> provides sample GIN operator classes that
+ implement B-tree equivalent behavior for the data types
+ <code class="type">int2</code>, <code class="type">int4</code>, <code class="type">int8</code>, <code class="type">float4</code>,
+ <code class="type">float8</code>, <code class="type">timestamp with time zone</code>,
+ <code class="type">timestamp without time zone</code>, <code class="type">time with time zone</code>,
+ <code class="type">time without time zone</code>, <code class="type">date</code>, <code class="type">interval</code>,
+ <code class="type">oid</code>, <code class="type">money</code>, <code class="type">"char"</code>,
+ <code class="type">varchar</code>, <code class="type">text</code>, <code class="type">bytea</code>, <code class="type">bit</code>,
+ <code class="type">varbit</code>, <code class="type">macaddr</code>, <code class="type">macaddr8</code>, <code class="type">inet</code>,
+ <code class="type">cidr</code>, <code class="type">uuid</code>, <code class="type">name</code>, <code class="type">bool</code>,
+ <code class="type">bpchar</code>, and all <code class="type">enum</code> types.
+ </p><p>
+ In general, these operator classes will not outperform the equivalent
+ standard B-tree index methods, and they lack one major feature of the
+ standard B-tree code: the ability to enforce uniqueness. However,
+ they are useful for GIN testing and as a base for developing other
+ GIN operator classes. Also, for queries that test both a GIN-indexable
+ column and a B-tree-indexable column, it might be more efficient to create
+ a multicolumn GIN index that uses one of these operator classes than to create
+ two separate indexes that would have to be combined via bitmap ANDing.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.17.6"><div class="titlepage"><div><div><h3 class="title">F.8.1. Example Usage</h3></div></div></div><pre class="programlisting">
+CREATE TABLE test (a int4);
+-- create index
+CREATE INDEX testidx ON test USING GIN (a);
+-- query
+SELECT * FROM test WHERE a &lt; 10;
+</pre></div><div class="sect2" id="id-1.11.7.17.7"><div class="titlepage"><div><div><h3 class="title">F.8.2. Authors</h3></div></div></div><p>
+ Teodor Sigaev (<code class="email">&lt;<a class="email" href="mailto:teodor@stack.net">teodor@stack.net</a>&gt;</code>) and
+ Oleg Bartunov (<code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>). See
+ <a class="ulink" href="http://www.sai.msu.su/~megera/oddmuse/index.cgi/Gin" target="_top">http://www.sai.msu.su/~megera/oddmuse/index.cgi/Gin</a>
+ for additional information.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bloom.html" title="F.7. bloom">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-gist.html" title="F.9. btree_gist">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.7. bloom </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.9. btree_gist</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-gist.html b/doc/src/sgml/html/btree-gist.html
new file mode 100644
index 0000000..56aa8db
--- /dev/null
+++ b/doc/src/sgml/html/btree-gist.html
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.9. btree_gist</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-gin.html" title="F.8. btree_gin" /><link rel="next" href="citext.html" title="F.10. citext" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.9. btree_gist</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-gin.html" title="F.8. btree_gin">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="citext.html" title="F.10. citext">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-GIST"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.9. btree_gist</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="btree-gist.html#id-1.11.7.18.8">F.9.1. Example Usage</a></span></dt><dt><span class="sect2"><a href="btree-gist.html#id-1.11.7.18.9">F.9.2. Authors</a></span></dt></dl></div><a id="id-1.11.7.18.2" class="indexterm"></a><p>
+ <code class="filename">btree_gist</code> provides GiST index operator classes that
+ implement B-tree equivalent behavior for the data types
+ <code class="type">int2</code>, <code class="type">int4</code>, <code class="type">int8</code>, <code class="type">float4</code>,
+ <code class="type">float8</code>, <code class="type">numeric</code>, <code class="type">timestamp with time zone</code>,
+ <code class="type">timestamp without time zone</code>, <code class="type">time with time zone</code>,
+ <code class="type">time without time zone</code>, <code class="type">date</code>, <code class="type">interval</code>,
+ <code class="type">oid</code>, <code class="type">money</code>, <code class="type">char</code>,
+ <code class="type">varchar</code>, <code class="type">text</code>, <code class="type">bytea</code>, <code class="type">bit</code>,
+ <code class="type">varbit</code>, <code class="type">macaddr</code>, <code class="type">macaddr8</code>, <code class="type">inet</code>,
+ <code class="type">cidr</code>, <code class="type">uuid</code>, <code class="type">bool</code> and all <code class="type">enum</code> types.
+ </p><p>
+ In general, these operator classes will not outperform the equivalent
+ standard B-tree index methods, and they lack one major feature of the
+ standard B-tree code: the ability to enforce uniqueness. However,
+ they provide some other features that are not available with a B-tree
+ index, as described below. Also, these operator classes are useful
+ when a multicolumn GiST index is needed, wherein some of the columns
+ are of data types that are only indexable with GiST but other columns
+ are just simple data types. Lastly, these operator classes are useful for
+ GiST testing and as a base for developing other GiST operator classes.
+ </p><p>
+ In addition to the typical B-tree search operators, <code class="filename">btree_gist</code>
+ also provides index support for <code class="literal">&lt;&gt;</code> (<span class="quote">“<span class="quote">not
+ equals</span>”</span>). This may be useful in combination with an
+ <a class="link" href="sql-createtable.html#SQL-CREATETABLE-EXCLUDE">exclusion constraint</a>,
+ as described below.
+ </p><p>
+ Also, for data types for which there is a natural distance metric,
+ <code class="filename">btree_gist</code> defines a distance operator <code class="literal">&lt;-&gt;</code>,
+ and provides GiST index support for nearest-neighbor searches using
+ this operator. Distance operators are provided for
+ <code class="type">int2</code>, <code class="type">int4</code>, <code class="type">int8</code>, <code class="type">float4</code>,
+ <code class="type">float8</code>, <code class="type">timestamp with time zone</code>,
+ <code class="type">timestamp without time zone</code>,
+ <code class="type">time without time zone</code>, <code class="type">date</code>, <code class="type">interval</code>,
+ <code class="type">oid</code>, and <code class="type">money</code>.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.18.8"><div class="titlepage"><div><div><h3 class="title">F.9.1. Example Usage</h3></div></div></div><p>
+ Simple example using <code class="literal">btree_gist</code> instead of <code class="literal">btree</code>:
+ </p><pre class="programlisting">
+CREATE TABLE test (a int4);
+-- create index
+CREATE INDEX testidx ON test USING GIST (a);
+-- query
+SELECT * FROM test WHERE a &lt; 10;
+-- nearest-neighbor search: find the ten entries closest to "42"
+SELECT *, a &lt;-&gt; 42 AS dist FROM test ORDER BY a &lt;-&gt; 42 LIMIT 10;
+</pre><p>
+ Use an <a class="link" href="sql-createtable.html#SQL-CREATETABLE-EXCLUDE">exclusion
+ constraint</a> to enforce the rule that a cage at a zoo
+ can contain only one kind of animal:
+ </p><pre class="programlisting">
+=&gt; CREATE TABLE zoo (
+ cage INTEGER,
+ animal TEXT,
+ EXCLUDE USING GIST (cage WITH =, animal WITH &lt;&gt;)
+);
+
+=&gt; INSERT INTO zoo VALUES(123, 'zebra');
+INSERT 0 1
+=&gt; INSERT INTO zoo VALUES(123, 'zebra');
+INSERT 0 1
+=&gt; INSERT INTO zoo VALUES(123, 'lion');
+ERROR: conflicting key value violates exclusion constraint "zoo_cage_animal_excl"
+DETAIL: Key (cage, animal)=(123, lion) conflicts with existing key (cage, animal)=(123, zebra).
+=&gt; INSERT INTO zoo VALUES(124, 'lion');
+INSERT 0 1
+</pre></div><div class="sect2" id="id-1.11.7.18.9"><div class="titlepage"><div><div><h3 class="title">F.9.2. Authors</h3></div></div></div><p>
+ Teodor Sigaev (<code class="email">&lt;<a class="email" href="mailto:teodor@stack.net">teodor@stack.net</a>&gt;</code>),
+ Oleg Bartunov (<code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>),
+ Janko Richter (<code class="email">&lt;<a class="email" href="mailto:jankorichter@yahoo.de">jankorichter@yahoo.de</a>&gt;</code>), and
+ Paul Jungwirth (<code class="email">&lt;<a class="email" href="mailto:pj@illuminatedcomputing.com">pj@illuminatedcomputing.com</a>&gt;</code>). See
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/</a>
+ for additional information.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-gin.html" title="F.8. btree_gin">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="citext.html" title="F.10. citext">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.8. btree_gin </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.10. citext</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-implementation.html b/doc/src/sgml/html/btree-implementation.html
new file mode 100644
index 0000000..d575eb1
--- /dev/null
+++ b/doc/src/sgml/html/btree-implementation.html
@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>67.4. Implementation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions" /><link rel="next" href="gist.html" title="Chapter 68. GiST Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">67.4. Implementation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><th width="60%" align="center">Chapter 67. B-Tree Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist.html" title="Chapter 68. GiST Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">67.4. Implementation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="btree-implementation.html#BTREE-STRUCTURE">67.4.1. B-Tree Structure</a></span></dt><dt><span class="sect2"><a href="btree-implementation.html#BTREE-DELETION">67.4.2. Bottom-up Index Deletion</a></span></dt><dt><span class="sect2"><a href="btree-implementation.html#BTREE-DEDUPLICATION">67.4.3. Deduplication</a></span></dt></dl></div><p>
+ This section covers B-Tree index implementation details that may be
+ of use to advanced users. See
+ <code class="filename">src/backend/access/nbtree/README</code> in the source
+ distribution for a much more detailed, internals-focused description
+ of the B-Tree implementation.
+ </p><div class="sect2" id="BTREE-STRUCTURE"><div class="titlepage"><div><div><h3 class="title">67.4.1. B-Tree Structure</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> B-Tree indexes are
+ multi-level tree structures, where each level of the tree can be
+ used as a doubly-linked list of pages. A single metapage is stored
+ in a fixed position at the start of the first segment file of the
+ index. All other pages are either leaf pages or internal pages.
+ Leaf pages are the pages on the lowest level of the tree. All
+ other levels consist of internal pages. Each leaf page contains
+ tuples that point to table rows. Each internal page contains
+ tuples that point to the next level down in the tree. Typically,
+ over 99% of all pages are leaf pages. Both internal pages and leaf
+ pages use the standard page format described in <a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>.
+ </p><p>
+ New leaf pages are added to a B-Tree index when an existing leaf
+ page cannot fit an incoming tuple. A <em class="firstterm">page
+ split</em> operation makes room for items that originally
+ belonged on the overflowing page by moving a portion of the items
+ to a new page. Page splits must also insert a new
+ <em class="firstterm">downlink</em> to the new page in the parent page,
+ which may cause the parent to split in turn. Page splits
+ <span class="quote">“<span class="quote">cascade upwards</span>”</span> in a recursive fashion. When the
+ root page finally cannot fit a new downlink, a <em class="firstterm">root page
+ split</em> operation takes place. This adds a new level to
+ the tree structure by creating a new root page that is one level
+ above the original root page.
+ </p></div><div class="sect2" id="BTREE-DELETION"><div class="titlepage"><div><div><h3 class="title">67.4.2. Bottom-up Index Deletion</h3></div></div></div><p>
+ B-Tree indexes are not directly aware that under MVCC, there might
+ be multiple extant versions of the same logical table row; to an
+ index, each tuple is an independent object that needs its own index
+ entry. <span class="quote">“<span class="quote">Version churn</span>”</span> tuples may sometimes
+ accumulate and adversely affect query latency and throughput. This
+ typically occurs with <code class="command">UPDATE</code>-heavy workloads
+ where most individual updates cannot apply the
+ <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)"><acronym class="acronym">HOT</acronym> optimization.</a>
+ Changing the value of only
+ one column covered by one index during an <code class="command">UPDATE</code>
+ <span class="emphasis"><em>always</em></span> necessitates a new set of index tuples
+ — one for <span class="emphasis"><em>each and every</em></span> index on the
+ table. Note in particular that this includes indexes that were not
+ <span class="quote">“<span class="quote">logically modified</span>”</span> by the <code class="command">UPDATE</code>.
+ All indexes will need a successor physical index tuple that points
+ to the latest version in the table. Each new tuple within each
+ index will generally need to coexist with the original
+ <span class="quote">“<span class="quote">updated</span>”</span> tuple for a short period of time (typically
+ until shortly after the <code class="command">UPDATE</code> transaction
+ commits).
+ </p><p>
+ B-Tree indexes incrementally delete version churn index tuples by
+ performing <em class="firstterm">bottom-up index deletion</em> passes.
+ Each deletion pass is triggered in reaction to an anticipated
+ <span class="quote">“<span class="quote">version churn page split</span>”</span>. This only happens with
+ indexes that are not logically modified by
+ <code class="command">UPDATE</code> statements, where concentrated build up
+ of obsolete versions in particular pages would occur otherwise. A
+ page split will usually be avoided, though it's possible that
+ certain implementation-level heuristics will fail to identify and
+ delete even one garbage index tuple (in which case a page split or
+ deduplication pass resolves the issue of an incoming new tuple not
+ fitting on a leaf page). The worst-case number of versions that
+ any index scan must traverse (for any single logical row) is an
+ important contributor to overall system responsiveness and
+ throughput. A bottom-up index deletion pass targets suspected
+ garbage tuples in a single leaf page based on
+ <span class="emphasis"><em>qualitative</em></span> distinctions involving logical
+ rows and versions. This contrasts with the <span class="quote">“<span class="quote">top-down</span>”</span>
+ index cleanup performed by autovacuum workers, which is triggered
+ when certain <span class="emphasis"><em>quantitative</em></span> table-level
+ thresholds are exceeded (see <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Not all deletion operations that are performed within B-Tree
+ indexes are bottom-up deletion operations. There is a distinct
+ category of index tuple deletion: <em class="firstterm">simple index tuple
+ deletion</em>. This is a deferred maintenance operation
+ that deletes index tuples that are known to be safe to delete
+ (those whose item identifier's <code class="literal">LP_DEAD</code> bit is
+ already set). Like bottom-up index deletion, simple index
+ deletion takes place at the point that a page split is anticipated
+ as a way of avoiding the split.
+ </p><p>
+ Simple deletion is opportunistic in the sense that it can only
+ take place when recent index scans set the
+ <code class="literal">LP_DEAD</code> bits of affected items in passing.
+ Prior to <span class="productname">PostgreSQL</span> 14, the only
+ category of B-Tree deletion was simple deletion. The main
+ differences between it and bottom-up deletion are that only the
+ former is opportunistically driven by the activity of passing
+ index scans, while only the latter specifically targets version
+ churn from <code class="command">UPDATE</code>s that do not logically modify
+ indexed columns.
+ </p></div><p>
+ Bottom-up index deletion performs the vast majority of all garbage
+ index tuple cleanup for particular indexes with certain workloads.
+ This is expected with any B-Tree index that is subject to
+ significant version churn from <code class="command">UPDATE</code>s that
+ rarely or never logically modify the columns that the index covers.
+ The average and worst-case number of versions per logical row can
+ be kept low purely through targeted incremental deletion passes.
+ It's quite possible that the on-disk size of certain indexes will
+ never increase by even one single page/block despite
+ <span class="emphasis"><em>constant</em></span> version churn from
+ <code class="command">UPDATE</code>s. Even then, an exhaustive <span class="quote">“<span class="quote">clean
+ sweep</span>”</span> by a <code class="command">VACUUM</code> operation (typically
+ run in an autovacuum worker process) will eventually be required as
+ a part of <span class="emphasis"><em>collective</em></span> cleanup of the table and
+ each of its indexes.
+ </p><p>
+ Unlike <code class="command">VACUUM</code>, bottom-up index deletion does not
+ provide any strong guarantees about how old the oldest garbage
+ index tuple may be. No index can be permitted to retain
+ <span class="quote">“<span class="quote">floating garbage</span>”</span> index tuples that became dead prior
+ to a conservative cutoff point shared by the table and all of its
+ indexes collectively. This fundamental table-level invariant makes
+ it safe to recycle table <acronym class="acronym">TID</acronym>s. This is how it
+ is possible for distinct logical rows to reuse the same table
+ <acronym class="acronym">TID</acronym> over time (though this can never happen with
+ two logical rows whose lifetimes span the same
+ <code class="command">VACUUM</code> cycle).
+ </p></div><div class="sect2" id="BTREE-DEDUPLICATION"><div class="titlepage"><div><div><h3 class="title">67.4.3. Deduplication</h3></div></div></div><p>
+ A duplicate is a leaf page tuple (a tuple that points to a table
+ row) where <span class="emphasis"><em>all</em></span> indexed key columns have values
+ that match corresponding column values from at least one other leaf
+ page tuple in the same index. Duplicate tuples are quite common in
+ practice. B-Tree indexes can use a special, space-efficient
+ representation for duplicates when an optional technique is
+ enabled: <em class="firstterm">deduplication</em>.
+ </p><p>
+ Deduplication works by periodically merging groups of duplicate
+ tuples together, forming a single <em class="firstterm">posting list</em> tuple for each
+ group. The column key value(s) only appear once in this
+ representation. This is followed by a sorted array of
+ <acronym class="acronym">TID</acronym>s that point to rows in the table. This
+ significantly reduces the storage size of indexes where each value
+ (or each distinct combination of column values) appears several
+ times on average. The latency of queries can be reduced
+ significantly. Overall query throughput may increase
+ significantly. The overhead of routine index vacuuming may also be
+ reduced significantly.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ B-Tree deduplication is just as effective with
+ <span class="quote">“<span class="quote">duplicates</span>”</span> that contain a NULL value, even though
+ NULL values are never equal to each other according to the
+ <code class="literal">=</code> member of any B-Tree operator class. As far
+ as any part of the implementation that understands the on-disk
+ B-Tree structure is concerned, NULL is just another value from the
+ domain of indexed values.
+ </p></div><p>
+ The deduplication process occurs lazily, when a new item is
+ inserted that cannot fit on an existing leaf page, though only when
+ index tuple deletion could not free sufficient space for the new
+ item (typically deletion is briefly considered and then skipped
+ over). Unlike GIN posting list tuples, B-Tree posting list tuples
+ do not need to expand every time a new duplicate is inserted; they
+ are merely an alternative physical representation of the original
+ logical contents of the leaf page. This design prioritizes
+ consistent performance with mixed read-write workloads. Most
+ client applications will at least see a moderate performance
+ benefit from using deduplication. Deduplication is enabled by
+ default.
+ </p><p>
+ <code class="command">CREATE INDEX</code> and <code class="command">REINDEX</code>
+ apply deduplication to create posting list tuples, though the
+ strategy they use is slightly different. Each group of duplicate
+ ordinary tuples encountered in the sorted input taken from the
+ table is merged into a posting list tuple
+ <span class="emphasis"><em>before</em></span> being added to the current pending leaf
+ page. Individual posting list tuples are packed with as many
+ <acronym class="acronym">TID</acronym>s as possible. Leaf pages are written out in
+ the usual way, without any separate deduplication pass. This
+ strategy is well-suited to <code class="command">CREATE INDEX</code> and
+ <code class="command">REINDEX</code> because they are once-off batch
+ operations.
+ </p><p>
+ Write-heavy workloads that don't benefit from deduplication due to
+ having few or no duplicate values in indexes will incur a small,
+ fixed performance penalty (unless deduplication is explicitly
+ disabled). The <code class="literal">deduplicate_items</code> storage
+ parameter can be used to disable deduplication within individual
+ indexes. There is never any performance penalty with read-only
+ workloads, since reading posting list tuples is at least as
+ efficient as reading the standard tuple representation. Disabling
+ deduplication isn't usually helpful.
+ </p><p>
+ It is sometimes possible for unique indexes (as well as unique
+ constraints) to use deduplication. This allows leaf pages to
+ temporarily <span class="quote">“<span class="quote">absorb</span>”</span> extra version churn duplicates.
+ Deduplication in unique indexes augments bottom-up index deletion,
+ especially in cases where a long-running transaction holds a
+ snapshot that blocks garbage collection. The goal is to buy time
+ for the bottom-up index deletion strategy to become effective
+ again. Delaying page splits until a single long-running
+ transaction naturally goes away can allow a bottom-up deletion pass
+ to succeed where an earlier deletion pass failed.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ A special heuristic is applied to determine whether a
+ deduplication pass in a unique index should take place. It can
+ often skip straight to splitting a leaf page, avoiding a
+ performance penalty from wasting cycles on unhelpful deduplication
+ passes. If you're concerned about the overhead of deduplication,
+ consider setting <code class="literal">deduplicate_items = off</code>
+ selectively. Leaving deduplication enabled in unique indexes has
+ little downside.
+ </p></div><p>
+ Deduplication cannot be used in all cases due to
+ implementation-level restrictions. Deduplication safety is
+ determined when <code class="command">CREATE INDEX</code> or
+ <code class="command">REINDEX</code> is run.
+ </p><p>
+ Note that deduplication is deemed unsafe and cannot be used in the
+ following cases involving semantically significant differences
+ among equal datums:
+ </p><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="type">text</code>, <code class="type">varchar</code>, and <code class="type">char</code>
+ cannot use deduplication when a
+ <span class="emphasis"><em>nondeterministic</em></span> collation is used. Case
+ and accent differences must be preserved among equal datums.
+ </p></li><li class="listitem"><p>
+ <code class="type">numeric</code> cannot use deduplication. Numeric display
+ scale must be preserved among equal datums.
+ </p></li><li class="listitem"><p>
+ <code class="type">jsonb</code> cannot use deduplication, since the
+ <code class="type">jsonb</code> B-Tree operator class uses
+ <code class="type">numeric</code> internally.
+ </p></li><li class="listitem"><p>
+ <code class="type">float4</code> and <code class="type">float8</code> cannot use
+ deduplication. These types have distinct representations for
+ <code class="literal">-0</code> and <code class="literal">0</code>, which are
+ nevertheless considered equal. This difference must be
+ preserved.
+ </p></li></ul></div><p>
+ </p><p>
+ There is one further implementation-level restriction that may be
+ lifted in a future version of
+ <span class="productname">PostgreSQL</span>:
+ </p><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Container types (such as composite types, arrays, or range
+ types) cannot use deduplication.
+ </p></li></ul></div><p>
+ </p><p>
+ There is one further implementation-level restriction that applies
+ regardless of the operator class or collation used:
+ </p><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">INCLUDE</code> indexes can never use deduplication.
+ </p></li></ul></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist.html" title="Chapter 68. GiST Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">67.3. B-Tree Support Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 68. GiST Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-intro.html b/doc/src/sgml/html/btree-intro.html
new file mode 100644
index 0000000..20796ba
--- /dev/null
+++ b/doc/src/sgml/html/btree-intro.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>67.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree.html" title="Chapter 67. B-Tree Indexes" /><link rel="next" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">67.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree.html" title="Chapter 67. B-Tree Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><th width="60%" align="center">Chapter 67. B-Tree Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">67.1. Introduction</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> includes an implementation of the
+ standard <acronym class="acronym">btree</acronym> (multi-way balanced tree) index data
+ structure. Any data type that can be sorted into a well-defined linear
+ order can be indexed by a btree index. The only limitation is that an
+ index entry cannot exceed approximately one-third of a page (after TOAST
+ compression, if applicable).
+ </p><p>
+ Because each btree operator class imposes a sort order on its data type,
+ btree operator classes (or, really, operator families) have come to be
+ used as <span class="productname">PostgreSQL</span>'s general representation
+ and understanding of sorting semantics. Therefore, they've acquired
+ some features that go beyond what would be needed just to support btree
+ indexes, and parts of the system that are quite distant from the
+ btree AM make use of them.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree.html" title="Chapter 67. B-Tree Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 67. B-Tree Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 67.2. Behavior of B-Tree Operator Classes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree-support-funcs.html b/doc/src/sgml/html/btree-support-funcs.html
new file mode 100644
index 0000000..72310b2
--- /dev/null
+++ b/doc/src/sgml/html/btree-support-funcs.html
@@ -0,0 +1,291 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>67.3. B-Tree Support Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes" /><link rel="next" href="btree-implementation.html" title="67.4. Implementation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">67.3. B-Tree Support Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><th width="60%" align="center">Chapter 67. B-Tree Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-implementation.html" title="67.4. Implementation">Next</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-SUPPORT-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">67.3. B-Tree Support Functions</h2></div></div></div><p>
+ As shown in <a class="xref" href="xindex.html#XINDEX-BTREE-SUPPORT-TABLE" title="Table 38.9. B-Tree Support Functions">Table 38.9</a>, btree defines
+ one required and four optional support functions. The five
+ user-defined methods are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">order</code></span></dt><dd><p>
+ For each combination of data types that a btree operator family
+ provides comparison operators for, it must provide a comparison
+ support function, registered in
+ <code class="structname">pg_amproc</code> with support function number 1
+ and
+ <code class="structfield">amproclefttype</code>/<code class="structfield">amprocrighttype</code>
+ equal to the left and right data types for the comparison (i.e.,
+ the same data types that the matching operators are registered
+ with in <code class="structname">pg_amop</code>). The comparison
+ function must take two non-null values
+ <em class="replaceable"><code>A</code></em> and <em class="replaceable"><code>B</code></em> and
+ return an <code class="type">int32</code> value that is
+ <code class="literal">&lt;</code> <code class="literal">0</code>,
+ <code class="literal">0</code>, or <code class="literal">&gt;</code>
+ <code class="literal">0</code> when <em class="replaceable"><code>A</code></em>
+ <code class="literal">&lt;</code> <em class="replaceable"><code>B</code></em>,
+ <em class="replaceable"><code>A</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>B</code></em>, or <em class="replaceable"><code>A</code></em>
+ <code class="literal">&gt;</code> <em class="replaceable"><code>B</code></em>,
+ respectively. A null result is disallowed: all values of the
+ data type must be comparable. See
+ <code class="filename">src/backend/access/nbtree/nbtcompare.c</code> for
+ examples.
+ </p><p>
+ If the compared values are of a collatable data type, the
+ appropriate collation OID will be passed to the comparison
+ support function, using the standard
+ <code class="function">PG_GET_COLLATION()</code> mechanism.
+ </p></dd><dt><span class="term"><code class="function">sortsupport</code></span></dt><dd><p>
+ Optionally, a btree operator family may provide <em class="firstterm">sort
+ support</em> function(s), registered under support
+ function number 2. These functions allow implementing
+ comparisons for sorting purposes in a more efficient way than
+ naively calling the comparison support function. The APIs
+ involved in this are defined in
+ <code class="filename">src/include/utils/sortsupport.h</code>.
+ </p></dd><dt><span class="term"><code class="function">in_range</code></span></dt><dd><a id="id-1.10.18.5.3.3.2.1" class="indexterm"></a><a id="id-1.10.18.5.3.3.2.2" class="indexterm"></a><p>
+ Optionally, a btree operator family may provide
+ <em class="firstterm">in_range</em> support function(s), registered
+ under support function number 3. These are not used during btree
+ index operations; rather, they extend the semantics of the
+ operator family so that it can support window clauses containing
+ the <code class="literal">RANGE</code> <em class="replaceable"><code>offset</code></em>
+ <code class="literal">PRECEDING</code> and <code class="literal">RANGE</code>
+ <em class="replaceable"><code>offset</code></em> <code class="literal">FOLLOWING</code>
+ frame bound types (see <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a>). Fundamentally, the extra
+ information provided is how to add or subtract an
+ <em class="replaceable"><code>offset</code></em> value in a way that is
+ compatible with the family's data ordering.
+ </p><p>
+ An <code class="function">in_range</code> function must have the signature
+</p><pre class="synopsis">
+in_range(<em class="replaceable"><code>val</code></em> type1, <em class="replaceable"><code>base</code></em> type1, <em class="replaceable"><code>offset</code></em> type2, <em class="replaceable"><code>sub</code></em> bool, <em class="replaceable"><code>less</code></em> bool)
+returns bool
+</pre><p>
+ <em class="replaceable"><code>val</code></em> and
+ <em class="replaceable"><code>base</code></em> must be of the same type, which
+ is one of the types supported by the operator family (i.e., a
+ type for which it provides an ordering). However,
+ <em class="replaceable"><code>offset</code></em> could be of a different type,
+ which might be one otherwise unsupported by the family. An
+ example is that the built-in <code class="literal">time_ops</code> family
+ provides an <code class="function">in_range</code> function that has
+ <em class="replaceable"><code>offset</code></em> of type <code class="type">interval</code>.
+ A family can provide <code class="function">in_range</code> functions for
+ any of its supported types and one or more
+ <em class="replaceable"><code>offset</code></em> types. Each
+ <code class="function">in_range</code> function should be entered in
+ <code class="structname">pg_amproc</code> with
+ <code class="structfield">amproclefttype</code> equal to
+ <code class="type">type1</code> and <code class="structfield">amprocrighttype</code>
+ equal to <code class="type">type2</code>.
+ </p><p>
+ The essential semantics of an <code class="function">in_range</code>
+ function depend on the two Boolean flag parameters. It should
+ add or subtract <em class="replaceable"><code>base</code></em> and
+ <em class="replaceable"><code>offset</code></em>, then compare
+ <em class="replaceable"><code>val</code></em> to the result, as follows:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ if <code class="literal">!</code><em class="replaceable"><code>sub</code></em> and
+ <code class="literal">!</code><em class="replaceable"><code>less</code></em>, return
+ <em class="replaceable"><code>val</code></em> <code class="literal">&gt;=</code>
+ (<em class="replaceable"><code>base</code></em> <code class="literal">+</code>
+ <em class="replaceable"><code>offset</code></em>)
+ </p></li><li class="listitem"><p>
+ if <code class="literal">!</code><em class="replaceable"><code>sub</code></em> and
+ <em class="replaceable"><code>less</code></em>, return
+ <em class="replaceable"><code>val</code></em> <code class="literal">&lt;=</code>
+ (<em class="replaceable"><code>base</code></em> <code class="literal">+</code>
+ <em class="replaceable"><code>offset</code></em>)
+ </p></li><li class="listitem"><p>
+ if <em class="replaceable"><code>sub</code></em> and
+ <code class="literal">!</code><em class="replaceable"><code>less</code></em>, return
+ <em class="replaceable"><code>val</code></em> <code class="literal">&gt;=</code>
+ (<em class="replaceable"><code>base</code></em> <code class="literal">-</code>
+ <em class="replaceable"><code>offset</code></em>)
+ </p></li><li class="listitem"><p>
+ if <em class="replaceable"><code>sub</code></em> and
+ <em class="replaceable"><code>less</code></em>, return
+ <em class="replaceable"><code>val</code></em> <code class="literal">&lt;=</code>
+ (<em class="replaceable"><code>base</code></em> <code class="literal">-</code>
+ <em class="replaceable"><code>offset</code></em>)
+ </p></li></ul></div><p>
+ Before doing so, the function should check the sign of
+ <em class="replaceable"><code>offset</code></em>: if it is less than zero, raise
+ error
+ <code class="literal">ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE</code>
+ (22013) with error text like <span class="quote">“<span class="quote">invalid preceding or
+ following size in window function</span>”</span>. (This is required by
+ the SQL standard, although nonstandard operator families might
+ perhaps choose to ignore this restriction, since there seems to
+ be little semantic necessity for it.) This requirement is
+ delegated to the <code class="function">in_range</code> function so that
+ the core code needn't understand what <span class="quote">“<span class="quote">less than
+ zero</span>”</span> means for a particular data type.
+ </p><p>
+ An additional expectation is that <code class="function">in_range</code>
+ functions should, if practical, avoid throwing an error if
+ <em class="replaceable"><code>base</code></em> <code class="literal">+</code>
+ <em class="replaceable"><code>offset</code></em> or
+ <em class="replaceable"><code>base</code></em> <code class="literal">-</code>
+ <em class="replaceable"><code>offset</code></em> would overflow. The correct
+ comparison result can be determined even if that value would be
+ out of the data type's range. Note that if the data type
+ includes concepts such as <span class="quote">“<span class="quote">infinity</span>”</span> or
+ <span class="quote">“<span class="quote">NaN</span>”</span>, extra care may be needed to ensure that
+ <code class="function">in_range</code>'s results agree with the normal
+ sort order of the operator family.
+ </p><p>
+ The results of the <code class="function">in_range</code> function must be
+ consistent with the sort ordering imposed by the operator family.
+ To be precise, given any fixed values of
+ <em class="replaceable"><code>offset</code></em> and
+ <em class="replaceable"><code>sub</code></em>, then:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If <code class="function">in_range</code> with
+ <em class="replaceable"><code>less</code></em> = true is true for some
+ <em class="replaceable"><code>val1</code></em> and
+ <em class="replaceable"><code>base</code></em>, it must be true for every
+ <em class="replaceable"><code>val2</code></em> <code class="literal">&lt;=</code>
+ <em class="replaceable"><code>val1</code></em> with the same
+ <em class="replaceable"><code>base</code></em>.
+ </p></li><li class="listitem"><p>
+ If <code class="function">in_range</code> with
+ <em class="replaceable"><code>less</code></em> = true is false for some
+ <em class="replaceable"><code>val1</code></em> and
+ <em class="replaceable"><code>base</code></em>, it must be false for every
+ <em class="replaceable"><code>val2</code></em> <code class="literal">&gt;=</code>
+ <em class="replaceable"><code>val1</code></em> with the same
+ <em class="replaceable"><code>base</code></em>.
+ </p></li><li class="listitem"><p>
+ If <code class="function">in_range</code> with
+ <em class="replaceable"><code>less</code></em> = true is true for some
+ <em class="replaceable"><code>val</code></em> and
+ <em class="replaceable"><code>base1</code></em>, it must be true for every
+ <em class="replaceable"><code>base2</code></em> <code class="literal">&gt;=</code>
+ <em class="replaceable"><code>base1</code></em> with the same
+ <em class="replaceable"><code>val</code></em>.
+ </p></li><li class="listitem"><p>
+ If <code class="function">in_range</code> with
+ <em class="replaceable"><code>less</code></em> = true is false for some
+ <em class="replaceable"><code>val</code></em> and
+ <em class="replaceable"><code>base1</code></em>, it must be false for every
+ <em class="replaceable"><code>base2</code></em> <code class="literal">&lt;=</code>
+ <em class="replaceable"><code>base1</code></em> with the same
+ <em class="replaceable"><code>val</code></em>.
+ </p></li></ul></div><p>
+ Analogous statements with inverted conditions hold when
+ <em class="replaceable"><code>less</code></em> = false.
+ </p><p>
+ If the type being ordered (<code class="type">type1</code>) is collatable, the
+ appropriate collation OID will be passed to the
+ <code class="function">in_range</code> function, using the standard
+ PG_GET_COLLATION() mechanism.
+ </p><p>
+ <code class="function">in_range</code> functions need not handle NULL
+ inputs, and typically will be marked strict.
+ </p></dd><dt><span class="term"><code class="function">equalimage</code></span></dt><dd><p>
+ Optionally, a btree operator family may provide
+ <code class="function">equalimage</code> (<span class="quote">“<span class="quote">equality implies image
+ equality</span>”</span>) support functions, registered under support
+ function number 4. These functions allow the core code to
+ determine when it is safe to apply the btree deduplication
+ optimization. Currently, <code class="function">equalimage</code>
+ functions are only called when building or rebuilding an index.
+ </p><p>
+ An <code class="function">equalimage</code> function must have the
+ signature
+</p><pre class="synopsis">
+equalimage(<em class="replaceable"><code>opcintype</code></em> <code class="type">oid</code>) returns bool
+</pre><p>
+ The return value is static information about an operator class
+ and collation. Returning <code class="literal">true</code> indicates that
+ the <code class="function">order</code> function for the operator class is
+ guaranteed to only return <code class="literal">0</code> (<span class="quote">“<span class="quote">arguments
+ are equal</span>”</span>) when its <em class="replaceable"><code>A</code></em> and
+ <em class="replaceable"><code>B</code></em> arguments are also interchangeable
+ without any loss of semantic information. Not registering an
+ <code class="function">equalimage</code> function or returning
+ <code class="literal">false</code> indicates that this condition cannot be
+ assumed to hold.
+ </p><p>
+ The <em class="replaceable"><code>opcintype</code></em> argument is the
+ <code class="literal"><code class="structname">pg_type</code>.oid</code> of the
+ data type that the operator class indexes. This is a convenience
+ that allows reuse of the same underlying
+ <code class="function">equalimage</code> function across operator classes.
+ If <em class="replaceable"><code>opcintype</code></em> is a collatable data
+ type, the appropriate collation OID will be passed to the
+ <code class="function">equalimage</code> function, using the standard
+ <code class="function">PG_GET_COLLATION()</code> mechanism.
+ </p><p>
+ As far as the operator class is concerned, returning
+ <code class="literal">true</code> indicates that deduplication is safe (or
+ safe for the collation whose OID was passed to its
+ <code class="function">equalimage</code> function). However, the core
+ code will only deem deduplication safe for an index when
+ <span class="emphasis"><em>every</em></span> indexed column uses an operator class
+ that registers an <code class="function">equalimage</code> function, and
+ each function actually returns <code class="literal">true</code> when
+ called.
+ </p><p>
+ Image equality is <span class="emphasis"><em>almost</em></span> the same condition
+ as simple bitwise equality. There is one subtle difference: When
+ indexing a varlena data type, the on-disk representation of two
+ image equal datums may not be bitwise equal due to inconsistent
+ application of <acronym class="acronym">TOAST</acronym> compression on input.
+ Formally, when an operator class's
+ <code class="function">equalimage</code> function returns
+ <code class="literal">true</code>, it is safe to assume that the
+ <code class="literal">datum_image_eq()</code> C function will always agree
+ with the operator class's <code class="function">order</code> function
+ (provided that the same collation OID is passed to both the
+ <code class="function">equalimage</code> and <code class="function">order</code>
+ functions).
+ </p><p>
+ The core code is fundamentally unable to deduce anything about
+ the <span class="quote">“<span class="quote">equality implies image equality</span>”</span> status of an
+ operator class within a multiple-data-type family based on
+ details from other operator classes in the same family. Also, it
+ is not sensible for an operator family to register a cross-type
+ <code class="function">equalimage</code> function, and attempting to do so
+ will result in an error. This is because <span class="quote">“<span class="quote">equality implies
+ image equality</span>”</span> status does not just depend on
+ sorting/equality semantics, which are more or less defined at the
+ operator family level. In general, the semantics that one
+ particular data type implements must be considered separately.
+ </p><p>
+ The convention followed by the operator classes included with the
+ core <span class="productname">PostgreSQL</span> distribution is to
+ register a stock, generic <code class="function">equalimage</code>
+ function. Most operator classes register
+ <code class="function">btequalimage()</code>, which indicates that
+ deduplication is safe unconditionally. Operator classes for
+ collatable data types such as <code class="type">text</code> register
+ <code class="function">btvarstrequalimage()</code>, which indicates that
+ deduplication is safe with deterministic collations. Best
+ practice for third-party extensions is to register their own
+ custom function to retain control.
+ </p></dd><dt><span class="term"><code class="function">options</code></span></dt><dd><p>
+ Optionally, a B-tree operator family may provide
+ <code class="function">options</code> (<span class="quote">“<span class="quote">operator class specific
+ options</span>”</span>) support functions, registered under support
+ function number 5. These functions define a set of user-visible
+ parameters that control operator class behavior.
+ </p><p>
+ An <code class="function">options</code> support function must have the
+ signature
+</p><pre class="synopsis">
+options(<em class="replaceable"><code>relopts</code></em> <code class="type">local_relopts *</code>) returns void
+</pre><p>
+ The function is passed a pointer to a <code class="structname">local_relopts</code>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using the <code class="literal">PG_HAS_OPCLASS_OPTIONS()</code> and
+ <code class="literal">PG_GET_OPCLASS_OPTIONS()</code> macros.
+ </p><p>
+ Currently, no B-Tree operator class has an <code class="function">options</code>
+ support function. B-tree doesn't allow flexible representation of keys
+ like GiST, SP-GiST, GIN and BRIN do. So, <code class="function">options</code>
+ probably doesn't have much application in the current B-tree index
+ access method. Nevertheless, this support function was added to B-tree
+ for uniformity, and will probably find uses during further
+ evolution of B-tree in <span class="productname">PostgreSQL</span>.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="btree.html" title="Chapter 67. B-Tree Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-implementation.html" title="67.4. Implementation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">67.2. Behavior of B-Tree Operator Classes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 67.4. Implementation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/btree.html b/doc/src/sgml/html/btree.html
new file mode 100644
index 0000000..1871b85
--- /dev/null
+++ b/doc/src/sgml/html/btree.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 67. B-Tree Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers" /><link rel="next" href="btree-intro.html" title="67.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 67. B-Tree Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree-intro.html" title="67.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="BTREE"><div class="titlepage"><div><div><h2 class="title">Chapter 67. B-Tree Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="btree-intro.html">67.1. Introduction</a></span></dt><dt><span class="sect1"><a href="btree-behavior.html">67.2. Behavior of B-Tree Operator Classes</a></span></dt><dt><span class="sect1"><a href="btree-support-funcs.html">67.3. B-Tree Support Functions</a></span></dt><dt><span class="sect1"><a href="btree-implementation.html">67.4. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="btree-implementation.html#BTREE-STRUCTURE">67.4.1. B-Tree Structure</a></span></dt><dt><span class="sect2"><a href="btree-implementation.html#BTREE-DELETION">67.4.2. Bottom-up Index Deletion</a></span></dt><dt><span class="sect2"><a href="btree-implementation.html#BTREE-DEDUPLICATION">67.4.3. Deduplication</a></span></dt></dl></dd></dl></div><a id="id-1.10.18.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-intro.html" title="67.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 66. Custom WAL Resource Managers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 67.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/bug-reporting.html b/doc/src/sgml/html/bug-reporting.html
new file mode 100644
index 0000000..ed250ab
--- /dev/null
+++ b/doc/src/sgml/html/bug-reporting.html
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5. Bug Reporting Guidelines</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="resources.html" title="4. Further Information" /><link rel="next" href="tutorial.html" title="Part I. Tutorial" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5. Bug Reporting Guidelines</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr></table><hr /></div><div class="sect1" id="BUG-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5. Bug Reporting Guidelines</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.5">5.1. Identifying Bugs</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.6">5.2. What to Report</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.7">5.3. Where to Report Bugs</a></span></dt></dl></div><p>
+ When you find a bug in <span class="productname">PostgreSQL</span> we want to
+ hear about it. Your bug reports play an important part in making
+ <span class="productname">PostgreSQL</span> more reliable because even the utmost
+ care cannot guarantee that every part of
+ <span class="productname">PostgreSQL</span>
+ will work on every platform under every circumstance.
+ </p><p>
+ The following suggestions are intended to assist you in forming bug reports
+ that can be handled in an effective fashion. No one is required to follow
+ them but doing so tends to be to everyone's advantage.
+ </p><p>
+ We cannot promise to fix every bug right away. If the bug is obvious, critical,
+ or affects a lot of users, chances are good that someone will look into it. It
+ could also happen that we tell you to update to a newer version to see if the
+ bug happens there. Or we might decide that the bug
+ cannot be fixed before some major rewrite we might be planning is done. Or
+ perhaps it is simply too hard and there are more important things on the agenda.
+ If you need help immediately, consider obtaining a commercial support contract.
+ </p><div class="sect2" id="id-1.3.8.5"><div class="titlepage"><div><div><h3 class="title">5.1. Identifying Bugs</h3></div></div></div><p>
+ Before you report a bug, please read and re-read the
+ documentation to verify that you can really do whatever it is you are
+ trying. If it is not clear from the documentation whether you can do
+ something or not, please report that too; it is a bug in the documentation.
+ If it turns out that a program does something different from what the
+ documentation says, that is a bug. That might include, but is not limited to,
+ the following circumstances:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A program terminates with a fatal signal or an operating system
+ error message that would point to a problem in the program. (A
+ counterexample might be a <span class="quote">“<span class="quote">disk full</span>”</span> message,
+ since you have to fix that yourself.)
+ </p></li><li class="listitem"><p>
+ A program produces the wrong output for any given input.
+ </p></li><li class="listitem"><p>
+ A program refuses to accept valid input (as defined in the documentation).
+ </p></li><li class="listitem"><p>
+ A program accepts invalid input without a notice or error message.
+ But keep in mind that your idea of invalid input might be our idea of
+ an extension or compatibility with traditional practice.
+ </p></li><li class="listitem"><p>
+ <span class="productname">PostgreSQL</span> fails to compile, build, or
+ install according to the instructions on supported platforms.
+ </p></li></ul></div><p>
+
+ Here <span class="quote">“<span class="quote">program</span>”</span> refers to any executable, not only the backend process.
+ </p><p>
+ Being slow or resource-hogging is not necessarily a bug. Read the
+ documentation or ask on one of the mailing lists for help in tuning your
+ applications. Failing to comply to the <acronym class="acronym">SQL</acronym> standard is
+ not necessarily a bug either, unless compliance for the
+ specific feature is explicitly claimed.
+ </p><p>
+ Before you continue, check on the TODO list and in the FAQ to see if your bug is
+ already known. If you cannot decode the information on the TODO list, report your
+ problem. The least we can do is make the TODO list clearer.
+ </p></div><div class="sect2" id="id-1.3.8.6"><div class="titlepage"><div><div><h3 class="title">5.2. What to Report</h3></div></div></div><p>
+ The most important thing to remember about bug reporting is to state all
+ the facts and only facts. Do not speculate what you think went wrong, what
+ <span class="quote">“<span class="quote">it seemed to do</span>”</span>, or which part of the program has a fault.
+ If you are not familiar with the implementation you would probably guess
+ wrong and not help us a bit. And even if you are, educated explanations are
+ a great supplement to but no substitute for facts. If we are going to fix
+ the bug we still have to see it happen for ourselves first.
+ Reporting the bare facts
+ is relatively straightforward (you can probably copy and paste them from the
+ screen) but all too often important details are left out because someone
+ thought it does not matter or the report would be understood
+ anyway.
+ </p><p>
+ The following items should be contained in every bug report:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The exact sequence of steps <span class="emphasis"><em>from program
+ start-up</em></span> necessary to reproduce the problem. This
+ should be self-contained; it is not enough to send in a bare
+ <code class="command">SELECT</code> statement without the preceding
+ <code class="command">CREATE TABLE</code> and <code class="command">INSERT</code>
+ statements, if the output should depend on the data in the
+ tables. We do not have the time to reverse-engineer your
+ database schema, and if we are supposed to make up our own data
+ we would probably miss the problem.
+ </p><p>
+ The best format for a test case for SQL-related problems is a
+ file that can be run through the <span class="application">psql</span>
+ frontend that shows the problem. (Be sure to not have anything
+ in your <code class="filename">~/.psqlrc</code> start-up file.) An easy
+ way to create this file is to use <span class="application">pg_dump</span>
+ to dump out the table declarations and data needed to set the
+ scene, then add the problem query. You are encouraged to
+ minimize the size of your example, but this is not absolutely
+ necessary. If the bug is reproducible, we will find it either
+ way.
+ </p><p>
+ If your application uses some other client interface, such as <span class="application">PHP</span>, then
+ please try to isolate the offending queries. We will probably not set up a
+ web server to reproduce your problem. In any case remember to provide
+ the exact input files; do not guess that the problem happens for
+ <span class="quote">“<span class="quote">large files</span>”</span> or <span class="quote">“<span class="quote">midsize databases</span>”</span>, etc. since this
+ information is too inexact to be of use.
+ </p></li><li class="listitem"><p>
+ The output you got. Please do not say that it <span class="quote">“<span class="quote">didn't work</span>”</span> or
+ <span class="quote">“<span class="quote">crashed</span>”</span>. If there is an error message,
+ show it, even if you do not understand it. If the program terminates with
+ an operating system error, say which. If nothing at all happens, say so.
+ Even if the result of your test case is a program crash or otherwise obvious
+ it might not happen on our platform. The easiest thing is to copy the output
+ from the terminal, if possible.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If you are reporting an error message, please obtain the most verbose
+ form of the message. In <span class="application">psql</span>, say <code class="literal">\set
+ VERBOSITY verbose</code> beforehand. If you are extracting the message
+ from the server log, set the run-time parameter
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-ERROR-VERBOSITY">log_error_verbosity</a> to <code class="literal">verbose</code> so that all
+ details are logged.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ In case of fatal errors, the error message reported by the client might
+ not contain all the information available. Please also look at the
+ log output of the database server. If you do not keep your server's log
+ output, this would be a good time to start doing so.
+ </p></div></li><li class="listitem"><p>
+ The output you expected is very important to state. If you just write
+ <span class="quote">“<span class="quote">This command gives me that output.</span>”</span> or <span class="quote">“<span class="quote">This is not
+ what I expected.</span>”</span>, we might run it ourselves, scan the output, and
+ think it looks OK and is exactly what we expected. We should not have to
+ spend the time to decode the exact semantics behind your commands.
+ Especially refrain from merely saying that <span class="quote">“<span class="quote">This is not what SQL says/Oracle
+ does.</span>”</span> Digging out the correct behavior from <acronym class="acronym">SQL</acronym>
+ is not a fun undertaking, nor do we all know how all the other relational
+ databases out there behave. (If your problem is a program crash, you can
+ obviously omit this item.)
+ </p></li><li class="listitem"><p>
+ Any command line options and other start-up options, including
+ any relevant environment variables or configuration files that
+ you changed from the default. Again, please provide exact
+ information. If you are using a prepackaged distribution that
+ starts the database server at boot time, you should try to find
+ out how that is done.
+ </p></li><li class="listitem"><p>
+ Anything you did at all differently from the installation
+ instructions.
+ </p></li><li class="listitem"><p>
+ The <span class="productname">PostgreSQL</span> version. You can run the command
+ <code class="literal">SELECT version();</code> to
+ find out the version of the server you are connected to. Most executable
+ programs also support a <code class="option">--version</code> option; at least
+ <code class="literal">postgres --version</code> and <code class="literal">psql --version</code>
+ should work.
+ If the function or the options do not exist then your version is
+ more than old enough to warrant an upgrade.
+ If you run a prepackaged version, such as RPMs, say so, including any
+ subversion the package might have. If you are talking about a Git
+ snapshot, mention that, including the commit hash.
+ </p><p>
+ If your version is older than 15.5 we will almost certainly
+ tell you to upgrade. There are many bug fixes and improvements
+ in each new release, so it is quite possible that a bug you have
+ encountered in an older release of <span class="productname">PostgreSQL</span>
+ has already been fixed. We can only provide limited support for
+ sites using older releases of <span class="productname">PostgreSQL</span>; if you
+ require more than we can provide, consider acquiring a
+ commercial support contract.
+ </p><p>
+ </p></li><li class="listitem"><p>
+ Platform information. This includes the kernel name and version,
+ C library, processor, memory information, and so on. In most
+ cases it is sufficient to report the vendor and version, but do
+ not assume everyone knows what exactly <span class="quote">“<span class="quote">Debian</span>”</span>
+ contains or that everyone runs on x86_64. If you have
+ installation problems then information about the toolchain on
+ your machine (compiler, <span class="application">make</span>, and so
+ on) is also necessary.
+ </p></li></ul></div><p>
+
+ Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
+ It is better to report everything the first time than us having to squeeze the
+ facts out of you. On the other hand, if your input files are huge, it is
+ fair to ask first whether somebody is interested in looking into it. Here is
+ an <a class="ulink" href="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target="_top">article</a>
+ that outlines some more tips on reporting bugs.
+ </p><p>
+ Do not spend all your time to figure out which changes in the input make
+ the problem go away. This will probably not help solving it. If it turns
+ out that the bug cannot be fixed right away, you will still have time to
+ find and share your work-around. Also, once again, do not waste your time
+ guessing why the bug exists. We will find that out soon enough.
+ </p><p>
+ When writing a bug report, please avoid confusing terminology.
+ The software package in total is called <span class="quote">“<span class="quote">PostgreSQL</span>”</span>,
+ sometimes <span class="quote">“<span class="quote">Postgres</span>”</span> for short. If you
+ are specifically talking about the backend process, mention that, do not
+ just say <span class="quote">“<span class="quote">PostgreSQL crashes</span>”</span>. A crash of a single
+ backend process is quite different from crash of the parent
+ <span class="quote">“<span class="quote">postgres</span>”</span> process; please don't say <span class="quote">“<span class="quote">the server
+ crashed</span>”</span> when you mean a single backend process went down, nor vice versa.
+ Also, client programs such as the interactive frontend <span class="quote">“<span class="quote"><span class="application">psql</span></span>”</span>
+ are completely separate from the backend. Please try to be specific
+ about whether the problem is on the client or server side.
+ </p></div><div class="sect2" id="id-1.3.8.7"><div class="titlepage"><div><div><h3 class="title">5.3. Where to Report Bugs</h3></div></div></div><p>
+ In general, send bug reports to the bug report mailing list at
+ <code class="email">&lt;<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>&gt;</code>.
+ You are requested to use a descriptive subject for your email
+ message, perhaps parts of the error message.
+ </p><p>
+ Another method is to fill in the bug report web-form available
+ at the project's
+ <a class="ulink" href="https://www.postgresql.org/" target="_top">web site</a>.
+ Entering a bug report this way causes it to be mailed to the
+ <code class="email">&lt;<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>&gt;</code> mailing list.
+ </p><p>
+ If your bug report has security implications and you'd prefer that it
+ not become immediately visible in public archives, don't send it to
+ <code class="literal">pgsql-bugs</code>. Security issues can be
+ reported privately to <code class="email">&lt;<a class="email" href="mailto:security@postgresql.org">security@postgresql.org</a>&gt;</code>.
+ </p><p>
+ Do not send bug reports to any of the user mailing lists, such as
+ <code class="email">&lt;<a class="email" href="mailto:pgsql-sql@lists.postgresql.org">pgsql-sql@lists.postgresql.org</a>&gt;</code> or
+ <code class="email">&lt;<a class="email" href="mailto:pgsql-general@lists.postgresql.org">pgsql-general@lists.postgresql.org</a>&gt;</code>.
+ These mailing lists are for answering
+ user questions, and their subscribers normally do not wish to receive
+ bug reports. More importantly, they are unlikely to fix them.
+ </p><p>
+ Also, please do <span class="emphasis"><em>not</em></span> send reports to
+ the developers' mailing list <code class="email">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</code>.
+ This list is for discussing the
+ development of <span class="productname">PostgreSQL</span>, and it would be nice
+ if we could keep the bug reports separate. We might choose to take up a
+ discussion about your bug report on <code class="literal">pgsql-hackers</code>,
+ if the problem needs more review.
+ </p><p>
+ If you have a problem with the documentation, the best place to report it
+ is the documentation mailing list <code class="email">&lt;<a class="email" href="mailto:pgsql-docs@lists.postgresql.org">pgsql-docs@lists.postgresql.org</a>&gt;</code>.
+ Please be specific about what part of the documentation you are unhappy
+ with.
+ </p><p>
+ If your bug is a portability problem on a non-supported platform,
+ send mail to <code class="email">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</code>,
+ so we (and you) can work on
+ porting <span class="productname">PostgreSQL</span> to your platform.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Due to the unfortunate amount of spam going around, all of the above
+ lists will be moderated unless you are subscribed. That means there
+ will be some delay before the email is delivered. If you wish to subscribe
+ to the lists, please visit
+ <a class="ulink" href="https://lists.postgresql.org/" target="_top">https://lists.postgresql.org/</a> for instructions.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Further Information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part I. Tutorial</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-aggregate.html b/doc/src/sgml/html/catalog-pg-aggregate.html
new file mode 100644
index 0000000..8b38ccd
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-aggregate.html
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.2. pg_aggregate</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalogs-overview.html" title="53.1. Overview" /><link rel="next" href="catalog-pg-am.html" title="53.3. pg_am" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.2. <code class="structname">pg_aggregate</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalogs-overview.html" title="53.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-am.html" title="53.3. pg_am">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AGGREGATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.2. <code class="structname">pg_aggregate</code></h2></div></div></div><a id="id-1.10.4.4.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_aggregate</code> stores information about
+ aggregate functions. An aggregate function is a function that
+ operates on a set of values (typically one column from each row
+ that matches a query condition) and returns a single value computed
+ from all these values. Typical aggregate functions are
+ <code class="function">sum</code>, <code class="function">count</code>, and
+ <code class="function">max</code>. Each entry in
+ <code class="structname">pg_aggregate</code> is an extension of an entry
+ in <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.
+ The <code class="structname">pg_proc</code> entry carries the aggregate's name,
+ input and output data types, and other information that is similar to
+ ordinary functions.
+ </p><div class="table" id="id-1.10.4.4.4"><p class="title"><strong>Table 53.2. <code class="structname">pg_aggregate</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_aggregate Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggfnoid</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ <code class="structname">pg_proc</code> OID of the aggregate function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggkind</code> <code class="type">char</code>
+ </p>
+ <p>
+ Aggregate kind:
+ <code class="literal">n</code> for <span class="quote">“<span class="quote">normal</span>”</span> aggregates,
+ <code class="literal">o</code> for <span class="quote">“<span class="quote">ordered-set</span>”</span> aggregates, or
+ <code class="literal">h</code> for <span class="quote">“<span class="quote">hypothetical-set</span>”</span> aggregates
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggnumdirectargs</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of direct (non-aggregated) arguments of an ordered-set or
+ hypothetical-set aggregate, counting a variadic array as one argument.
+ If equal to <code class="structfield">pronargs</code>, the aggregate must be variadic
+ and the variadic array describes the aggregated arguments as well as
+ the final direct arguments.
+ Always zero for normal aggregates.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggtransfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Transition function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggfinalfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Final function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggcombinefn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Combine function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggserialfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Serialization function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggdeserialfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Deserialization function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmtransfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Forward transition function for moving-aggregate mode (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggminvtransfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Inverse transition function for moving-aggregate mode (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmfinalfn</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Final function for moving-aggregate mode (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggfinalextra</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True to pass extra dummy arguments to <code class="structfield">aggfinalfn</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmfinalextra</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True to pass extra dummy arguments to <code class="structfield">aggmfinalfn</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggfinalmodify</code> <code class="type">char</code>
+ </p>
+ <p>
+ Whether <code class="structfield">aggfinalfn</code> modifies the
+ transition state value:
+ <code class="literal">r</code> if it is read-only,
+ <code class="literal">s</code> if the <code class="structfield">aggtransfn</code>
+ cannot be applied after the <code class="structfield">aggfinalfn</code>, or
+ <code class="literal">w</code> if it writes on the value
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmfinalmodify</code> <code class="type">char</code>
+ </p>
+ <p>
+ Like <code class="structfield">aggfinalmodify</code>, but for
+ the <code class="structfield">aggmfinalfn</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggsortop</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Associated sort operator (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggtranstype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the aggregate function's internal transition (state) data
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggtransspace</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Approximate average size (in bytes) of the transition state
+ data, or zero to use a default estimate
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmtranstype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the aggregate function's internal transition (state)
+ data for moving-aggregate mode (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggmtransspace</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Approximate average size (in bytes) of the transition state data
+ for moving-aggregate mode, or zero to use a default estimate
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">agginitval</code> <code class="type">text</code>
+ </p>
+ <p>
+ The initial value of the transition state. This is a text
+ field containing the initial value in its external string
+ representation. If this field is null, the transition state
+ value starts out null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">aggminitval</code> <code class="type">text</code>
+ </p>
+ <p>
+ The initial value of the transition state for moving-aggregate mode.
+ This is a text field containing the initial value in its external
+ string representation. If this field is null, the transition state
+ value starts out null.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ New aggregate functions are registered with the <a class="link" href="sql-createaggregate.html" title="CREATE AGGREGATE"><code class="command">CREATE AGGREGATE</code></a>
+ command. See <a class="xref" href="xaggr.html" title="38.12. User-Defined Aggregates">Section 38.12</a> for more information about
+ writing aggregate functions and the meaning of the transition
+ functions, etc.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalogs-overview.html" title="53.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-am.html" title="53.3. pg_am">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.3. <code class="structname">pg_am</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-am.html b/doc/src/sgml/html/catalog-pg-am.html
new file mode 100644
index 0000000..48e8cae
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-am.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.3. pg_am</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate" /><link rel="next" href="catalog-pg-amop.html" title="53.4. pg_amop" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.3. <code class="structname">pg_am</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-amop.html" title="53.4. pg_amop">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.3. <code class="structname">pg_am</code></h2></div></div></div><a id="id-1.10.4.5.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_am</code> stores information about
+ relation access methods. There is one row for each access method supported
+ by the system.
+ Currently, only tables and indexes have access methods. The requirements for table
+ and index access methods are discussed in detail in <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> and
+ <a class="xref" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Chapter 64</a> respectively.
+ </p><div class="table" id="id-1.10.4.5.4"><p class="title"><strong>Table 53.3. <code class="structname">pg_am</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_am Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the access method
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amhandler</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of a handler function that is responsible for supplying information
+ about the access method
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">t</code> = table (including materialized views),
+ <code class="literal">i</code> = index.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 9.6, <code class="structname">pg_am</code>
+ contained many additional columns representing properties of index access
+ methods. That data is now only directly visible at the C code level.
+ However, <code class="function">pg_index_column_has_property()</code> and related
+ functions have been added to allow SQL queries to inspect index access
+ method properties; see <a class="xref" href="functions-info.html#FUNCTIONS-INFO-CATALOG-TABLE" title="Table 9.71. System Catalog Information Functions">Table 9.71</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-amop.html" title="53.4. pg_amop">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.2. <code class="structname">pg_aggregate</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.4. <code class="structname">pg_amop</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-amop.html b/doc/src/sgml/html/catalog-pg-amop.html
new file mode 100644
index 0000000..c43164e
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-amop.html
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.4. pg_amop</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-am.html" title="53.3. pg_am" /><link rel="next" href="catalog-pg-amproc.html" title="53.5. pg_amproc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.4. <code class="structname">pg_amop</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-am.html" title="53.3. pg_am">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-amproc.html" title="53.5. pg_amproc">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AMOP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.4. <code class="structname">pg_amop</code></h2></div></div></div><a id="id-1.10.4.6.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_amop</code> stores information about
+ operators associated with access method operator families. There is one
+ row for each operator that is a member of an operator family. A family
+ member can be either a <em class="firstterm">search</em> operator or an
+ <em class="firstterm">ordering</em> operator. An operator
+ can appear in more than one family, but cannot appear in more than one
+ search position nor more than one ordering position within a family.
+ (It is allowed, though unlikely, for an operator to be used for both
+ search and ordering purposes.)
+ </p><div class="table" id="id-1.10.4.6.4"><p class="title"><strong>Table 53.4. <code class="structname">pg_amop</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_amop Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amopfamily</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The operator family this entry is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amoplefttype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Left-hand input data type of operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amoprighttype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Right-hand input data type of operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amopstrategy</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Operator strategy number
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amoppurpose</code> <code class="type">char</code>
+ </p>
+ <p>
+ Operator purpose, either <code class="literal">s</code> for search or
+ <code class="literal">o</code> for ordering
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amopopr</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amopmethod</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Index access method operator family is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amopsortfamily</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The B-tree operator family this entry sorts according to, if an
+ ordering operator; zero if a search operator
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ A <span class="quote">“<span class="quote">search</span>”</span> operator entry indicates that an index of this operator
+ family can be searched to find all rows satisfying
+ <code class="literal">WHERE</code>
+ <em class="replaceable"><code>indexed_column</code></em>
+ <em class="replaceable"><code>operator</code></em>
+ <em class="replaceable"><code>constant</code></em>.
+ Obviously, such an operator must return <code class="type">boolean</code>, and its left-hand input
+ type must match the index's column data type.
+ </p><p>
+ An <span class="quote">“<span class="quote">ordering</span>”</span> operator entry indicates that an index of this
+ operator family can be scanned to return rows in the order represented by
+ <code class="literal">ORDER BY</code>
+ <em class="replaceable"><code>indexed_column</code></em>
+ <em class="replaceable"><code>operator</code></em>
+ <em class="replaceable"><code>constant</code></em>.
+ Such an operator could return any sortable data type, though again
+ its left-hand input type must match the index's column data type.
+ The exact semantics of the <code class="literal">ORDER BY</code> are specified by the
+ <code class="structfield">amopsortfamily</code> column, which must reference
+ a B-tree operator family for the operator's result type.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ At present, it's assumed that the sort order for an ordering operator
+ is the default for the referenced operator family, i.e., <code class="literal">ASC NULLS
+ LAST</code>. This might someday be relaxed by adding additional columns
+ to specify sort options explicitly.
+ </p></div><p>
+ An entry's <code class="structfield">amopmethod</code> must match the
+ <code class="structfield">opfmethod</code> of its containing operator family (including
+ <code class="structfield">amopmethod</code> here is an intentional denormalization of the
+ catalog structure for performance reasons). Also,
+ <code class="structfield">amoplefttype</code> and <code class="structfield">amoprighttype</code> must match
+ the <code class="structfield">oprleft</code> and <code class="structfield">oprright</code> fields of the
+ referenced <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a> entry.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-am.html" title="53.3. pg_am">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-amproc.html" title="53.5. pg_amproc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.3. <code class="structname">pg_am</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.5. <code class="structname">pg_amproc</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-amproc.html b/doc/src/sgml/html/catalog-pg-amproc.html
new file mode 100644
index 0000000..f2b1604
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-amproc.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.5. pg_amproc</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-amop.html" title="53.4. pg_amop" /><link rel="next" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.5. <code class="structname">pg_amproc</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-amop.html" title="53.4. pg_amop">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AMPROC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.5. <code class="structname">pg_amproc</code></h2></div></div></div><a id="id-1.10.4.7.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_amproc</code> stores information about
+ support functions associated with access method operator families. There
+ is one row for each support function belonging to an operator family.
+ </p><div class="table" id="id-1.10.4.7.4"><p class="title"><strong>Table 53.5. <code class="structname">pg_amproc</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_amproc Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amprocfamily</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The operator family this entry is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amproclefttype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Left-hand input data type of associated operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amprocrighttype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Right-hand input data type of associated operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amprocnum</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Support function number
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">amproc</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The usual interpretation of the
+ <code class="structfield">amproclefttype</code> and <code class="structfield">amprocrighttype</code> fields
+ is that they identify the left and right input types of the operator(s)
+ that a particular support function supports. For some access methods
+ these match the input data type(s) of the support function itself, for
+ others not. There is a notion of <span class="quote">“<span class="quote">default</span>”</span> support functions for
+ an index, which are those with <code class="structfield">amproclefttype</code> and
+ <code class="structfield">amprocrighttype</code> both equal to the index operator class's
+ <code class="structfield">opcintype</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-amop.html" title="53.4. pg_amop">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.4. <code class="structname">pg_amop</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.6. <code class="structname">pg_attrdef</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-attrdef.html b/doc/src/sgml/html/catalog-pg-attrdef.html
new file mode 100644
index 0000000..6f9afd5
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-attrdef.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.6. pg_attrdef</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-amproc.html" title="53.5. pg_amproc" /><link rel="next" href="catalog-pg-attribute.html" title="53.7. pg_attribute" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.6. <code class="structname">pg_attrdef</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-amproc.html" title="53.5. pg_amproc">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-attribute.html" title="53.7. pg_attribute">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-ATTRDEF"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.6. <code class="structname">pg_attrdef</code></h2></div></div></div><a id="id-1.10.4.8.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_attrdef</code> stores column default
+ values. The main information about columns is stored in
+ <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.
+ Only columns for which a default value has been explicitly set will have
+ an entry here.
+ </p><div class="table" id="id-1.10.4.8.4"><p class="title"><strong>Table 53.6. <code class="structname">pg_attrdef</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_attrdef Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">adrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table this column belongs to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">adnum</code> <code class="type">int2</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ The number of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">adbin</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ The column default value, in <code class="function">nodeToString()</code>
+ representation. Use <code class="literal">pg_get_expr(adbin, adrelid)</code> to
+ convert it to an SQL expression.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-amproc.html" title="53.5. pg_amproc">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-attribute.html" title="53.7. pg_attribute">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.5. <code class="structname">pg_amproc</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.7. <code class="structname">pg_attribute</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-attribute.html b/doc/src/sgml/html/catalog-pg-attribute.html
new file mode 100644
index 0000000..75b840f
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-attribute.html
@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.7. pg_attribute</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef" /><link rel="next" href="catalog-pg-authid.html" title="53.8. pg_authid" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.7. <code class="structname">pg_attribute</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-authid.html" title="53.8. pg_authid">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-ATTRIBUTE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.7. <code class="structname">pg_attribute</code></h2></div></div></div><a id="id-1.10.4.9.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_attribute</code> stores information about
+ table columns. There will be exactly one
+ <code class="structname">pg_attribute</code> row for every column in every
+ table in the database. (There will also be attribute entries for
+ indexes, and indeed all objects that have
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>
+ entries.)
+ </p><p>
+ The term attribute is equivalent to column and is used for
+ historical reasons.
+ </p><div class="table" id="id-1.10.4.9.5"><p class="title"><strong>Table 53.7. <code class="structname">pg_attribute</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_attribute Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table this column belongs to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attname</code> <code class="type">name</code>
+ </p>
+ <p>
+ The column name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">atttypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The data type of this column (zero for a dropped column)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attstattarget</code> <code class="type">int4</code>
+ </p>
+ <p>
+ <code class="structfield">attstattarget</code> controls the level of detail
+ of statistics accumulated for this column by
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>.
+ 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.
+ For scalar data types, <code class="structfield">attstattarget</code>
+ is both the target number of <span class="quote">“<span class="quote">most common values</span>”</span>
+ to collect, and the target number of histogram bins to create.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attlen</code> <code class="type">int2</code>
+ </p>
+ <p>
+ A copy of <code class="literal">pg_type.typlen</code> of this column's
+ type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attnum</code> <code class="type">int2</code>
+ </p>
+ <p>
+ The number of the column. Ordinary columns are numbered from 1
+ up. System columns, such as <code class="structfield">ctid</code>,
+ have (arbitrary) negative numbers.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attndims</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Number of dimensions, if the column is an array type; otherwise 0.
+ (Presently, the number of dimensions of an array is not enforced,
+ so any nonzero value effectively means <span class="quote">“<span class="quote">it's an array</span>”</span>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attcacheoff</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Always -1 in storage, but when loaded into a row descriptor
+ in memory this might be updated to cache the offset of the attribute
+ within the row
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">atttypmod</code> <code class="type">int4</code>
+ </p>
+ <p>
+ <code class="structfield">atttypmod</code> records type-specific data
+ supplied at table creation time (for example, the maximum
+ length of a <code class="type">varchar</code> column). It is passed to
+ type-specific input functions and length coercion functions.
+ The value will generally be -1 for types that do not need <code class="structfield">atttypmod</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attbyval</code> <code class="type">bool</code>
+ </p>
+ <p>
+ A copy of <code class="literal">pg_type.typbyval</code> of this column's type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attalign</code> <code class="type">char</code>
+ </p>
+ <p>
+ A copy of <code class="literal">pg_type.typalign</code> of this column's type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attstorage</code> <code class="type">char</code>
+ </p>
+ <p>
+ Normally a copy of <code class="literal">pg_type.typstorage</code> of this
+ column's type. For TOAST-able data types, this can be altered
+ after column creation to control storage policy.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attcompression</code> <code class="type">char</code>
+ </p>
+ <p>
+ The current compression method of the column. Typically this is
+ <code class="literal">'\0'</code> to specify use of the current default setting
+ (see <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TOAST-COMPRESSION">default_toast_compression</a>). Otherwise,
+ <code class="literal">'p'</code> selects pglz compression, while
+ <code class="literal">'l'</code> selects <span class="productname">LZ4</span>
+ compression. However, this field is ignored
+ whenever <code class="structfield">attstorage</code> does not allow
+ compression.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attnotnull</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This represents a not-null constraint.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">atthasdef</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This column has a default expression or generation expression, in which
+ case there will be a corresponding entry in the
+ <a class="link" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef"><code class="structname">pg_attrdef</code></a> catalog that actually defines the
+ expression. (Check <code class="structfield">attgenerated</code> to
+ determine whether this is a default or a generation expression.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">atthasmissing</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This column has a value which is used where the column is entirely
+ missing from the row, as happens when a column is added with a
+ non-volatile <code class="literal">DEFAULT</code> value after the row is created.
+ The actual value used is stored in the
+ <code class="structfield">attmissingval</code> column.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attidentity</code> <code class="type">char</code>
+ </p>
+ <p>
+ If a zero byte (<code class="literal">''</code>), then not an identity column.
+ Otherwise, <code class="literal">a</code> = generated
+ always, <code class="literal">d</code> = generated by default.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attgenerated</code> <code class="type">char</code>
+ </p>
+ <p>
+ If a zero byte (<code class="literal">''</code>), then not a generated column.
+ Otherwise, <code class="literal">s</code> = stored. (Other values might be added
+ in the future.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attisdropped</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This column has been dropped and is no longer valid. A dropped
+ column is still physically present in the table, but is
+ ignored by the parser and so cannot be accessed via SQL.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attislocal</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This column is defined locally in the relation. Note that a column can
+ be locally defined and inherited simultaneously.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attinhcount</code> <code class="type">int4</code>
+ </p>
+ <p>
+ The number of direct ancestors this column has. A column with a
+ nonzero number of ancestors cannot be dropped nor renamed.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attcollation</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The defined collation of the column, or zero if the column is
+ not of a collatable data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Column-level access privileges, if any have been granted specifically
+ on this column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Attribute-level options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attfdwoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Attribute-level foreign data wrapper options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attmissingval</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ This column has a one element array containing the value used when the
+ column is entirely missing from the row, as happens when the column is
+ added with a non-volatile <code class="literal">DEFAULT</code> value after the
+ row is created. The value is only used when
+ <code class="structfield">atthasmissing</code> is true. If there is no value
+ the column is null.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In a dropped column's <code class="structname">pg_attribute</code> entry,
+ <code class="structfield">atttypid</code> is reset to zero, but
+ <code class="structfield">attlen</code> and the other fields copied from
+ <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a> are still valid. This arrangement is needed
+ to cope with the situation where the dropped column's data type was
+ later dropped, and so there is no <code class="structname">pg_type</code> row anymore.
+ <code class="structfield">attlen</code> and the other fields can be used
+ to interpret the contents of a row of the table.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-authid.html" title="53.8. pg_authid">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.6. <code class="structname">pg_attrdef</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.8. <code class="structname">pg_authid</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-auth-members.html b/doc/src/sgml/html/catalog-pg-auth-members.html
new file mode 100644
index 0000000..014acb5
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-auth-members.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.9. pg_auth_members</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-authid.html" title="53.8. pg_authid" /><link rel="next" href="catalog-pg-cast.html" title="53.10. pg_cast" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.9. <code class="structname">pg_auth_members</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-authid.html" title="53.8. pg_authid">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-cast.html" title="53.10. pg_cast">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AUTH-MEMBERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.9. <code class="structname">pg_auth_members</code></h2></div></div></div><a id="id-1.10.4.11.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_auth_members</code> shows the membership
+ relations between roles. Any non-circular set of relationships is allowed.
+ </p><p>
+ Because user identities are cluster-wide,
+ <code class="structname">pg_auth_members</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_auth_members</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.11.5"><p class="title"><strong>Table 53.9. <code class="structname">pg_auth_members</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_auth_members Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">roleid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of a role that has a member
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">member</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of a role that is a member of <code class="structfield">roleid</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of the role that granted this membership
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">admin_option</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if <code class="structfield">member</code> can grant membership in
+ <code class="structfield">roleid</code> to others
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-authid.html" title="53.8. pg_authid">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-cast.html" title="53.10. pg_cast">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.8. <code class="structname">pg_authid</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.10. <code class="structname">pg_cast</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-authid.html b/doc/src/sgml/html/catalog-pg-authid.html
new file mode 100644
index 0000000..d45b1f7
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-authid.html
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.8. pg_authid</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-attribute.html" title="53.7. pg_attribute" /><link rel="next" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.8. <code class="structname">pg_authid</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-attribute.html" title="53.7. pg_attribute">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-AUTHID"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.8. <code class="structname">pg_authid</code></h2></div></div></div><a id="id-1.10.4.10.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_authid</code> contains information about
+ database authorization identifiers (roles). A role subsumes the concepts
+ of <span class="quote">“<span class="quote">users</span>”</span> and <span class="quote">“<span class="quote">groups</span>”</span>. A user is essentially just a
+ role with the <code class="structfield">rolcanlogin</code> flag set. Any role (with or
+ without <code class="structfield">rolcanlogin</code>) can have other roles as members; see
+ <a class="link" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members"><code class="structname">pg_auth_members</code></a>.
+ </p><p>
+ Since this catalog contains passwords, it must not be publicly readable.
+ <a class="link" href="view-pg-roles.html" title="54.20. pg_roles"><code class="structname">pg_roles</code></a>
+ is a publicly readable view on
+ <code class="structname">pg_authid</code> that blanks out the password field.
+ </p><p>
+ <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a> contains detailed information about user and
+ privilege management.
+ </p><p>
+ Because user identities are cluster-wide,
+ <code class="structname">pg_authid</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_authid</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.10.7"><p class="title"><strong>Table 53.8. <code class="structname">pg_authid</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_authid Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Role name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolsuper</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role has superuser privileges
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolinherit</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role automatically inherits privileges of roles it is a
+ member of
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcreaterole</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can create more roles
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcreatedb</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can create databases
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcanlogin</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can log in. That is, this role can be given as the initial
+ session authorization identifier.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolreplication</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role is a replication role. A replication role can initiate replication
+ connections and create and drop replication slots.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolbypassrls</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role bypasses every row-level security policy, see
+ <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolconnlimit</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For roles that can log in, this sets maximum number of concurrent
+ connections this role can make. -1 means no limit.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolpassword</code> <code class="type">text</code>
+ </p>
+ <p>
+ Password (possibly encrypted); null if none. The format depends
+ on the form of encryption used.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolvaliduntil</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Password expiry time (only used for password authentication);
+ null if no expiration
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For an MD5 encrypted password, <code class="structfield">rolpassword</code>
+ column will begin with the string <code class="literal">md5</code> followed by a
+ 32-character hexadecimal MD5 hash. The MD5 hash will be of the user's
+ password concatenated to their user name. For example, if user
+ <code class="literal">joe</code> has password <code class="literal">xyzzy</code>, <span class="productname">PostgreSQL</span>
+ will store the md5 hash of <code class="literal">xyzzyjoe</code>.
+ </p><p>
+ If the password is encrypted with SCRAM-SHA-256, it has the format:
+</p><pre class="synopsis">
+SCRAM-SHA-256$<em class="replaceable"><code>&lt;iteration count&gt;</code></em>:<em class="replaceable"><code>&lt;salt&gt;</code></em>$<em class="replaceable"><code>&lt;StoredKey&gt;</code></em>:<em class="replaceable"><code>&lt;ServerKey&gt;</code></em>
+</pre><p>
+ where <em class="replaceable"><code>salt</code></em>, <em class="replaceable"><code>StoredKey</code></em> and
+ <em class="replaceable"><code>ServerKey</code></em> are in Base64 encoded format. This format is
+ the same as that specified by <a class="ulink" href="https://tools.ietf.org/html/rfc5803" target="_top">RFC 5803</a>.
+ </p><p>
+ A password that does not follow either of those formats is assumed to be
+ unencrypted.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-attribute.html" title="53.7. pg_attribute">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.7. <code class="structname">pg_attribute</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.9. <code class="structname">pg_auth_members</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-cast.html b/doc/src/sgml/html/catalog-pg-cast.html
new file mode 100644
index 0000000..84762e5
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-cast.html
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.10. pg_cast</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members" /><link rel="next" href="catalog-pg-class.html" title="53.11. pg_class" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.10. <code class="structname">pg_cast</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-class.html" title="53.11. pg_class">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-CAST"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.10. <code class="structname">pg_cast</code></h2></div></div></div><a id="id-1.10.4.12.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_cast</code> stores data type conversion
+ paths, both built-in and user-defined.
+ </p><p>
+ It should be noted that <code class="structname">pg_cast</code> does not represent
+ every type conversion that the system knows how to perform; only those that
+ cannot be deduced from some generic rule. For example, casting between a
+ domain and its base type is not explicitly represented in
+ <code class="structname">pg_cast</code>. Another important exception is that
+ <span class="quote">“<span class="quote">automatic I/O conversion casts</span>”</span>, those performed using a data
+ type's own I/O functions to convert to or from <code class="type">text</code> or other
+ string types, are not explicitly represented in
+ <code class="structname">pg_cast</code>.
+ </p><div class="table" id="id-1.10.4.12.5"><p class="title"><strong>Table 53.10. <code class="structname">pg_cast</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_cast Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">castsource</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the source data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">casttarget</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the target data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">castfunc</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the function to use to perform this cast. Zero is
+ stored if the cast method doesn't require a function.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">castcontext</code> <code class="type">char</code>
+ </p>
+ <p>
+ Indicates what contexts the cast can be invoked in.
+ <code class="literal">e</code> means only as an explicit cast (using
+ <code class="literal">CAST</code> or <code class="literal">::</code> syntax).
+ <code class="literal">a</code> means implicitly in assignment
+ to a target column, as well as explicitly.
+ <code class="literal">i</code> means implicitly in expressions, as well as the
+ other cases.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">castmethod</code> <code class="type">char</code>
+ </p>
+ <p>
+ Indicates how the cast is performed.
+ <code class="literal">f</code> means that the function specified in the <code class="structfield">castfunc</code> field is used.
+ <code class="literal">i</code> means that the input/output functions are used.
+ <code class="literal">b</code> means that the types are binary-coercible, thus no conversion is required.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The cast functions listed in <code class="structname">pg_cast</code> must
+ always take the cast source type as their first argument type, and
+ return the cast destination type as their result type. A cast
+ function can have up to three arguments. The second argument,
+ if present, must be type <code class="type">integer</code>; it receives the type
+ modifier associated with the destination type, or -1
+ if there is none. The third argument,
+ if present, must be type <code class="type">boolean</code>; it receives <code class="literal">true</code>
+ if the cast is an explicit cast, <code class="literal">false</code> otherwise.
+ </p><p>
+ It is legitimate to create a <code class="structname">pg_cast</code> entry
+ in which the source and target types are the same, if the associated
+ function takes more than one argument. Such entries represent
+ <span class="quote">“<span class="quote">length coercion functions</span>”</span> that coerce values of the type
+ to be legal for a particular type modifier value.
+ </p><p>
+ When a <code class="structname">pg_cast</code> entry has different source and
+ target types and a function that takes more than one argument, it
+ represents converting from one type to another and applying a length
+ coercion in a single step. When no such entry is available, coercion
+ to a type that uses a type modifier involves two steps, one to
+ convert between data types and a second to apply the modifier.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-class.html" title="53.11. pg_class">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.9. <code class="structname">pg_auth_members</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.11. <code class="structname">pg_class</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-class.html b/doc/src/sgml/html/catalog-pg-class.html
new file mode 100644
index 0000000..15bb128
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-class.html
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.11. pg_class</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-cast.html" title="53.10. pg_cast" /><link rel="next" href="catalog-pg-collation.html" title="53.12. pg_collation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.11. <code class="structname">pg_class</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-cast.html" title="53.10. pg_cast">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-collation.html" title="53.12. pg_collation">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-CLASS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.11. <code class="structname">pg_class</code></h2></div></div></div><a id="id-1.10.4.13.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_class</code> describes tables and
+ other objects that have columns or are otherwise similar to a
+ table. This includes indexes (but see also <a class="link" href="catalog-pg-index.html" title="53.26. pg_index"><code class="structname">pg_index</code></a>),
+ sequences (but see also <a class="link" href="catalog-pg-sequence.html" title="53.47. pg_sequence"><code class="structname">pg_sequence</code></a>),
+ views, materialized views, composite types, and TOAST tables;
+ see <code class="structfield">relkind</code>.
+ Below, when we mean all of these kinds of objects we speak of
+ <span class="quote">“<span class="quote">relations</span>”</span>. Not all of <code class="structname">pg_class</code>'s
+ columns are meaningful for all relation kinds.
+ </p><div class="table" id="id-1.10.4.13.4"><p class="title"><strong>Table 53.11. <code class="structname">pg_class</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_class Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the table, index, view, etc.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reltype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the data type that corresponds to this table's row type,
+ if any; zero for indexes, sequences, and toast tables, which have
+ no <code class="structname">pg_type</code> entry
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reloftype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For typed tables, the OID of the underlying composite type;
+ zero for all other relations
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relam</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If this is a table or an index, the access method used (heap,
+ B-tree, hash, etc.); otherwise zero (zero occurs for sequences,
+ as well as relations without storage, such as views)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relfilenode</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Name of the on-disk file of this relation; zero means this
+ is a <span class="quote">“<span class="quote">mapped</span>”</span> relation whose disk file name is determined
+ by low-level state
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reltablespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The tablespace in which this relation is stored. If zero,
+ the database's default tablespace is implied. (Not meaningful
+ if the relation has no on-disk file.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relpages</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Size of the on-disk representation of this table in pages (of size
+ <code class="symbol">BLCKSZ</code>). This is only an estimate used by the
+ planner. It is updated by <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>,
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>, and a few DDL commands such as
+ <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE INDEX</code></a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reltuples</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Number of live rows in the table. This is only an estimate used by
+ the planner. It is updated by <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>,
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>, and a few DDL commands such as
+ <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE INDEX</code></a>.
+ If the table has never yet been vacuumed or
+ analyzed, <code class="structfield">reltuples</code>
+ contains <code class="literal">-1</code> indicating that the row count is
+ unknown.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relallvisible</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Number of pages that are marked all-visible in the table's
+ visibility map. This is only an estimate used by the
+ planner. It is updated by <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>,
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>, and a few DDL commands such as
+ <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE INDEX</code></a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reltoastrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the TOAST table associated with this table, zero if none. The
+ TOAST table stores large attributes <span class="quote">“<span class="quote">out of line</span>”</span> in a
+ secondary table.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relhasindex</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this is a table and it has (or recently had) any indexes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relisshared</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this table is shared across all databases in the cluster. Only
+ certain system catalogs (such as <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>)
+ are shared.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relpersistence</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">p</code> = permanent table/sequence, <code class="literal">u</code> = unlogged table/sequence,
+ <code class="literal">t</code> = temporary table/sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relkind</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">r</code> = ordinary table,
+ <code class="literal">i</code> = index,
+ <code class="literal">S</code> = sequence,
+ <code class="literal">t</code> = TOAST table,
+ <code class="literal">v</code> = view,
+ <code class="literal">m</code> = materialized view,
+ <code class="literal">c</code> = composite type,
+ <code class="literal">f</code> = foreign table,
+ <code class="literal">p</code> = partitioned table,
+ <code class="literal">I</code> = partitioned index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relnatts</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of user columns in the relation (system columns not
+ counted). There must be this many corresponding entries in
+ <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>. See also
+ <code class="structname">pg_attribute</code>.<code class="structfield">attnum</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relchecks</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of <code class="literal">CHECK</code> constraints on the table; see
+ <a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a> catalog
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relhasrules</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if table has (or once had) rules; see
+ <a class="link" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite"><code class="structname">pg_rewrite</code></a> catalog
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relhastriggers</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if table has (or once had) triggers; see
+ <a class="link" href="catalog-pg-trigger.html" title="53.58. pg_trigger"><code class="structname">pg_trigger</code></a> catalog
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relhassubclass</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if table or index has (or once had) any inheritance children or partitions
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relrowsecurity</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if table has row-level security enabled; see
+ <a class="link" href="catalog-pg-policy.html" title="53.38. pg_policy"><code class="structname">pg_policy</code></a> catalog
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relforcerowsecurity</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if row-level security (when enabled) will also apply to table owner; see
+ <a class="link" href="catalog-pg-policy.html" title="53.38. pg_policy"><code class="structname">pg_policy</code></a> catalog
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relispopulated</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if relation is populated (this is true for all
+ relations other than some materialized views)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relreplident</code> <code class="type">char</code>
+ </p>
+ <p>
+ Columns used to form <span class="quote">“<span class="quote">replica identity</span>”</span> for rows:
+ <code class="literal">d</code> = default (primary key, if any),
+ <code class="literal">n</code> = nothing,
+ <code class="literal">f</code> = all columns,
+ <code class="literal">i</code> = index with
+ <code class="structfield">indisreplident</code> set (same as nothing if the
+ index used has been dropped)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relispartition</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if table or index is a partition
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relrewrite</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For new relations being written during a DDL operation that requires a
+ table rewrite, this contains the OID of the original relation;
+ otherwise zero. That state is only visible internally; this field should
+ never contain anything other than zero for a user-visible relation.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relfrozenxid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ All transaction IDs before this one have been replaced with a permanent
+ (<span class="quote">“<span class="quote">frozen</span>”</span>) transaction ID in this table. This is used to track
+ whether the table needs to be vacuumed in order to prevent transaction
+ ID wraparound or to allow <code class="literal">pg_xact</code> to be shrunk. Zero
+ (<code class="symbol">InvalidTransactionId</code>) if the relation is not a table.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relminmxid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ All multixact IDs before this one have been replaced by a
+ transaction ID in this table. This is used to track
+ whether the table needs to be vacuumed in order to prevent multixact ID
+ wraparound or to allow <code class="literal">pg_multixact</code> to be shrunk. Zero
+ (<code class="symbol">InvalidMultiXactId</code>) if the relation is not a table.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reloptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Access-method-specific options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relpartbound</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ If table is a partition (see <code class="structfield">relispartition</code>),
+ internal representation of the partition bound
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Several of the Boolean flags in <code class="structname">pg_class</code> are maintained
+ lazily: they are guaranteed to be true if that's the correct state, but
+ may not be reset to false immediately when the condition is no longer
+ true. For example, <code class="structfield">relhasindex</code> is set by
+ <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE INDEX</code></a>, but it is never cleared by
+ <a class="link" href="sql-dropindex.html" title="DROP INDEX"><code class="command">DROP INDEX</code></a>. Instead, <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a> clears
+ <code class="structfield">relhasindex</code> if it finds the table has no indexes. This
+ arrangement avoids race conditions and improves concurrency.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-cast.html" title="53.10. pg_cast">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-collation.html" title="53.12. pg_collation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.10. <code class="structname">pg_cast</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.12. <code class="structname">pg_collation</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-collation.html b/doc/src/sgml/html/catalog-pg-collation.html
new file mode 100644
index 0000000..65e8e82
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-collation.html
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.12. pg_collation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-class.html" title="53.11. pg_class" /><link rel="next" href="catalog-pg-constraint.html" title="53.13. pg_constraint" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.12. <code class="structname">pg_collation</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-class.html" title="53.11. pg_class">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-constraint.html" title="53.13. pg_constraint">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-COLLATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.12. <code class="structname">pg_collation</code></h2></div></div></div><a id="id-1.10.4.14.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_collation</code> describes the
+ available collations, which are essentially mappings from an SQL
+ name to operating system locale categories.
+ See <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a> for more information.
+ </p><div class="table" id="id-1.10.4.14.4"><p class="title"><strong>Table 53.12. <code class="structname">pg_collation</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_collation Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Collation name (unique per namespace and encoding)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collprovider</code> <code class="type">char</code>
+ </p>
+ <p>
+ Provider of the collation: <code class="literal">d</code> = database
+ default, <code class="literal">c</code> = libc, <code class="literal">i</code> = icu
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collisdeterministic</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Is the collation deterministic?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collencoding</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Encoding in which the collation is applicable, or -1 if it
+ works for any encoding
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collcollate</code> <code class="type">text</code>
+ </p>
+ <p>
+ <code class="symbol">LC_COLLATE</code> for this collation object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collctype</code> <code class="type">text</code>
+ </p>
+ <p>
+ <code class="symbol">LC_CTYPE</code> for this collation object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">colliculocale</code> <code class="type">text</code>
+ </p>
+ <p>
+ ICU locale ID for this collation object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collversion</code> <code class="type">text</code>
+ </p>
+ <p>
+ Provider-specific version of the collation. This is recorded when the
+ collation is created and then checked when it is used, to detect
+ changes in the collation definition that could lead to data corruption.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Note that the unique key on this catalog is (<code class="structfield">collname</code>,
+ <code class="structfield">collencoding</code>, <code class="structfield">collnamespace</code>) not just
+ (<code class="structfield">collname</code>, <code class="structfield">collnamespace</code>).
+ <span class="productname">PostgreSQL</span> generally ignores all
+ collations that do not have <code class="structfield">collencoding</code> equal to
+ either the current database's encoding or -1, and creation of new entries
+ with the same name as an entry with <code class="structfield">collencoding</code> = -1
+ is forbidden. Therefore it is sufficient to use a qualified SQL name
+ (<em class="replaceable"><code>schema</code></em>.<em class="replaceable"><code>name</code></em>) to identify a collation,
+ even though this is not unique according to the catalog definition.
+ The reason for defining the catalog this way is that
+ <span class="application">initdb</span> fills it in at cluster initialization time with
+ entries for all locales available on the system, so it must be able to
+ hold entries for all encodings that might ever be used in the cluster.
+ </p><p>
+ In the <code class="literal">template0</code> database, it could be useful to create
+ collations whose encoding does not match the database encoding,
+ since they could match the encodings of databases later cloned from
+ <code class="literal">template0</code>. This would currently have to be done manually.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-class.html" title="53.11. pg_class">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-constraint.html" title="53.13. pg_constraint">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.11. <code class="structname">pg_class</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.13. <code class="structname">pg_constraint</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-constraint.html b/doc/src/sgml/html/catalog-pg-constraint.html
new file mode 100644
index 0000000..3ddeeb9
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-constraint.html
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.13. pg_constraint</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-collation.html" title="53.12. pg_collation" /><link rel="next" href="catalog-pg-conversion.html" title="53.14. pg_conversion" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.13. <code class="structname">pg_constraint</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-collation.html" title="53.12. pg_collation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-conversion.html" title="53.14. pg_conversion">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-CONSTRAINT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.13. <code class="structname">pg_constraint</code></h2></div></div></div><a id="id-1.10.4.15.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_constraint</code> stores check, primary
+ key, unique, foreign key, and exclusion constraints on tables.
+ (Column constraints are not treated specially. Every column constraint is
+ equivalent to some table constraint.)
+ Not-null constraints are represented in the
+ <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>
+ catalog, not here.
+ </p><p>
+ User-defined constraint triggers (created with <a class="link" href="sql-createtrigger.html" title="CREATE TRIGGER">
+ <code class="command">CREATE CONSTRAINT TRIGGER</code></a>) also give rise to an entry in this table.
+ </p><p>
+ Check constraints on domains are stored here, too.
+ </p><div class="table" id="id-1.10.4.15.6"><p class="title"><strong>Table 53.13. <code class="structname">pg_constraint</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_constraint Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Constraint name (not necessarily unique!)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">connamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">contype</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">c</code> = check constraint,
+ <code class="literal">f</code> = foreign key constraint,
+ <code class="literal">p</code> = primary key constraint,
+ <code class="literal">u</code> = unique constraint,
+ <code class="literal">t</code> = constraint trigger,
+ <code class="literal">x</code> = exclusion constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">condeferrable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Is the constraint deferrable?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">condeferred</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Is the constraint deferred by default?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">convalidated</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Has the constraint been validated?
+ Currently, can be false only for foreign keys and CHECK constraints
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table this constraint is on; zero if not a table constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">contypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The domain this constraint is on; zero if not a domain constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conindid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The index supporting this constraint, if it's a unique, primary
+ key, foreign key, or exclusion constraint; else zero
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conparentid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The corresponding constraint of the parent partitioned table,
+ if this is a constraint on a partition; else zero
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If a foreign key, the referenced table; else zero
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confupdtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ Foreign key update action code:
+ <code class="literal">a</code> = no action,
+ <code class="literal">r</code> = restrict,
+ <code class="literal">c</code> = cascade,
+ <code class="literal">n</code> = set null,
+ <code class="literal">d</code> = set default
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confdeltype</code> <code class="type">char</code>
+ </p>
+ <p>
+ Foreign key deletion action code:
+ <code class="literal">a</code> = no action,
+ <code class="literal">r</code> = restrict,
+ <code class="literal">c</code> = cascade,
+ <code class="literal">n</code> = set null,
+ <code class="literal">d</code> = set default
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confmatchtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ Foreign key match type:
+ <code class="literal">f</code> = full,
+ <code class="literal">p</code> = partial,
+ <code class="literal">s</code> = simple
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conislocal</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This constraint is defined locally for the relation. Note that a
+ constraint can be locally defined and inherited simultaneously.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">coninhcount</code> <code class="type">int4</code>
+ </p>
+ <p>
+ The number of direct inheritance ancestors this constraint has.
+ A constraint with
+ a nonzero number of ancestors cannot be dropped nor renamed.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">connoinherit</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This constraint is defined locally for the relation. It is a
+ non-inheritable constraint.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conkey</code> <code class="type">int2[]</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ If a table constraint (including foreign keys, but not constraint
+ triggers), list of the constrained columns
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confkey</code> <code class="type">int2[]</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ If a foreign key, list of the referenced columns
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conpfeqop</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If a foreign key, list of the equality operators for PK = FK comparisons
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conppeqop</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If a foreign key, list of the equality operators for PK = PK comparisons
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conffeqop</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If a foreign key, list of the equality operators for FK = FK comparisons
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confdelsetcols</code> <code class="type">int2[]</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ If a foreign key with a <code class="literal">SET NULL</code> or <code class="literal">SET
+ DEFAULT</code> delete action, the columns that will be updated.
+ If null, all of the referencing columns will be updated.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conexclop</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If an exclusion constraint, list of the per-column exclusion operators
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conbin</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ If a check constraint, an internal representation of the
+ expression. (It's recommended to use
+ <code class="function">pg_get_constraintdef()</code> to extract the definition of
+ a check constraint.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In the case of an exclusion constraint, <code class="structfield">conkey</code>
+ is only useful for constraint elements that are simple column references.
+ For other cases, a zero appears in <code class="structfield">conkey</code>
+ and the associated index must be consulted to discover the expression
+ that is constrained. (<code class="structfield">conkey</code> thus has the
+ same contents as <a class="link" href="catalog-pg-index.html" title="53.26. pg_index"><code class="structname">pg_index</code></a>.<code class="structfield">indkey</code> for the
+ index.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">pg_class.relchecks</code> needs to agree with the
+ number of check-constraint entries found in this table for each
+ relation.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-collation.html" title="53.12. pg_collation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-conversion.html" title="53.14. pg_conversion">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.12. <code class="structname">pg_collation</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.14. <code class="structname">pg_conversion</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-conversion.html b/doc/src/sgml/html/catalog-pg-conversion.html
new file mode 100644
index 0000000..953bf19
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-conversion.html
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.14. pg_conversion</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-constraint.html" title="53.13. pg_constraint" /><link rel="next" href="catalog-pg-database.html" title="53.15. pg_database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.14. <code class="structname">pg_conversion</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-constraint.html" title="53.13. pg_constraint">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-database.html" title="53.15. pg_database">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-CONVERSION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.14. <code class="structname">pg_conversion</code></h2></div></div></div><a id="id-1.10.4.16.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_conversion</code> describes
+ encoding conversion functions. See <a class="xref" href="sql-createconversion.html" title="CREATE CONVERSION"><span class="refentrytitle">CREATE CONVERSION</span></a>
+ for more information.
+ </p><div class="table" id="id-1.10.4.16.4"><p class="title"><strong>Table 53.14. <code class="structname">pg_conversion</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_conversion Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Conversion name (unique within a namespace)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">connamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this conversion
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the conversion
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conforencoding</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Source encoding ID (<a class="link" href="functions-info.html#PG-ENCODING-TO-CHAR"><code class="function">pg_encoding_to_char()</code></a>
+ can translate this number to the encoding name)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">contoencoding</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Destination encoding ID (<a class="link" href="functions-info.html#PG-ENCODING-TO-CHAR"><code class="function">pg_encoding_to_char()</code></a>
+ can translate this number to the encoding name)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conproc</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Conversion function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">condefault</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this is the default conversion
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-constraint.html" title="53.13. pg_constraint">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-database.html" title="53.15. pg_database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.13. <code class="structname">pg_constraint</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.15. <code class="structname">pg_database</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-database.html b/doc/src/sgml/html/catalog-pg-database.html
new file mode 100644
index 0000000..9346423
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-database.html
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.15. pg_database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-conversion.html" title="53.14. pg_conversion" /><link rel="next" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.15. <code class="structname">pg_database</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-conversion.html" title="53.14. pg_conversion">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-DATABASE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.15. <code class="structname">pg_database</code></h2></div></div></div><a id="id-1.10.4.17.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_database</code> stores information about
+ the available databases. Databases are created with the <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a> command.
+ Consult <a class="xref" href="managing-databases.html" title="Chapter 23. Managing Databases">Chapter 23</a> for details about the meaning
+ of some of the parameters.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_database</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_database</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.17.5"><p class="title"><strong>Table 53.15. <code class="structname">pg_database</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_database Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Database name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datdba</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the database, usually the user who created it
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">encoding</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Character encoding for this database
+ (<a class="link" href="functions-info.html#PG-ENCODING-TO-CHAR"><code class="function">pg_encoding_to_char()</code></a> can translate
+ this number to the encoding name)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datlocprovider</code> <code class="type">char</code>
+ </p>
+ <p>
+ Locale provider for this database: <code class="literal">c</code> = libc,
+ <code class="literal">i</code> = icu
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datistemplate</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, then this database can be cloned by
+ any user with <code class="literal">CREATEDB</code> privileges;
+ if false, then only superusers or the owner of
+ the database can clone it.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datallowconn</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If false then no one can connect to this database. This is
+ used to protect the <code class="literal">template0</code> database from being altered.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datconnlimit</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Sets maximum number of concurrent connections that can be made
+ to this database. -1 means no limit, -2 indicates the database is
+ invalid.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datfrozenxid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ All transaction IDs before this one have been replaced with a permanent
+ (<span class="quote">“<span class="quote">frozen</span>”</span>) transaction ID in this database. This is used to
+ track whether the database needs to be vacuumed in order to prevent
+ transaction ID wraparound or to allow <code class="literal">pg_xact</code> to be shrunk.
+ It is the minimum of the per-table
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relfrozenxid</code> values.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datminmxid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ All multixact IDs before this one have been replaced with a
+ transaction ID in this database. This is used to
+ track whether the database needs to be vacuumed in order to prevent
+ multixact ID wraparound or to allow <code class="literal">pg_multixact</code> to be shrunk.
+ It is the minimum of the per-table
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relminmxid</code> values.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dattablespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The default tablespace for the database.
+ Within this database, all tables for which
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">reltablespace</code> is zero
+ will be stored in this tablespace; in particular, all the non-shared
+ system catalogs will be there.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datcollate</code> <code class="type">text</code>
+ </p>
+ <p>
+ LC_COLLATE for this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datctype</code> <code class="type">text</code>
+ </p>
+ <p>
+ LC_CTYPE for this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">daticulocale</code> <code class="type">text</code>
+ </p>
+ <p>
+ ICU locale ID for this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datcollversion</code> <code class="type">text</code>
+ </p>
+ <p>
+ Provider-specific version of the collation. This is recorded when the
+ database is created and then checked when it is used, to detect
+ changes in the collation definition that could lead to data corruption.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-conversion.html" title="53.14. pg_conversion">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.14. <code class="structname">pg_conversion</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.16. <code class="structname">pg_db_role_setting</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-db-role-setting.html b/doc/src/sgml/html/catalog-pg-db-role-setting.html
new file mode 100644
index 0000000..b139f76
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-db-role-setting.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.16. pg_db_role_setting</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-database.html" title="53.15. pg_database" /><link rel="next" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.16. <code class="structname">pg_db_role_setting</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-database.html" title="53.15. pg_database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-DB-ROLE-SETTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.16. <code class="structname">pg_db_role_setting</code></h2></div></div></div><a id="id-1.10.4.18.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_db_role_setting</code> records the default
+ values that have been set for run-time configuration variables,
+ for each role and database combination.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_db_role_setting</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_db_role_setting</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.18.5"><p class="title"><strong>Table 53.16. <code class="structname">pg_db_role_setting</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_db_role_setting Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setdatabase</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the database the setting is applicable to, or zero if not database-specific
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setrole</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the role the setting is applicable to, or zero if not role-specific
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setconfig</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Defaults for run-time configuration variables
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-database.html" title="53.15. pg_database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.15. <code class="structname">pg_database</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.17. <code class="structname">pg_default_acl</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-default-acl.html b/doc/src/sgml/html/catalog-pg-default-acl.html
new file mode 100644
index 0000000..9787142
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-default-acl.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.17. pg_default_acl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting" /><link rel="next" href="catalog-pg-depend.html" title="53.18. pg_depend" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.17. <code class="structname">pg_default_acl</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-depend.html" title="53.18. pg_depend">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-DEFAULT-ACL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.17. <code class="structname">pg_default_acl</code></h2></div></div></div><a id="id-1.10.4.19.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_default_acl</code> stores initial
+ privileges to be assigned to newly created objects.
+ </p><div class="table" id="id-1.10.4.19.4"><p class="title"><strong>Table 53.17. <code class="structname">pg_default_acl</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_default_acl Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">defaclrole</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the role associated with this entry
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">defaclnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace associated with this entry,
+ or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">defaclobjtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ Type of object this entry is for:
+ <code class="literal">r</code> = relation (table, view),
+ <code class="literal">S</code> = sequence,
+ <code class="literal">f</code> = function,
+ <code class="literal">T</code> = type,
+ <code class="literal">n</code> = schema
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">defaclacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges that this type of object should have on creation
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ A <code class="structname">pg_default_acl</code> entry shows the initial privileges to
+ be assigned to an object belonging to the indicated user. There are
+ currently two types of entry: <span class="quote">“<span class="quote">global</span>”</span> entries with
+ <code class="structfield">defaclnamespace</code> = zero, and <span class="quote">“<span class="quote">per-schema</span>”</span> entries
+ that reference a particular schema. If a global entry is present then
+ it <span class="emphasis"><em>overrides</em></span> the normal hard-wired default privileges
+ for the object type. A per-schema entry, if present, represents privileges
+ to be <span class="emphasis"><em>added to</em></span> the global or hard-wired default privileges.
+ </p><p>
+ Note that when an ACL entry in another catalog is null, it is taken
+ to represent the hard-wired default privileges for its object,
+ <span class="emphasis"><em>not</em></span> whatever might be in <code class="structname">pg_default_acl</code>
+ at the moment. <code class="structname">pg_default_acl</code> is only consulted during
+ object creation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-depend.html" title="53.18. pg_depend">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.16. <code class="structname">pg_db_role_setting</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.18. <code class="structname">pg_depend</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-depend.html b/doc/src/sgml/html/catalog-pg-depend.html
new file mode 100644
index 0000000..adf6a59
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-depend.html
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.18. pg_depend</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl" /><link rel="next" href="catalog-pg-description.html" title="53.19. pg_description" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.18. <code class="structname">pg_depend</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-description.html" title="53.19. pg_description">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-DEPEND"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.18. <code class="structname">pg_depend</code></h2></div></div></div><a id="id-1.10.4.20.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_depend</code> records the dependency
+ relationships between database objects. This information allows
+ <code class="command">DROP</code> commands to find which other objects must be dropped
+ by <code class="command">DROP CASCADE</code> or prevent dropping in the <code class="command">DROP
+ RESTRICT</code> case.
+ </p><p>
+ See also <a class="link" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend"><code class="structname">pg_shdepend</code></a>,
+ which performs a similar function for dependencies involving objects
+ that are shared across a database cluster.
+ </p><div class="table" id="id-1.10.4.20.5"><p class="title"><strong>Table 53.18. <code class="structname">pg_depend</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_depend Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog the dependent object is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the specific dependent object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a table column, this is the column number (the
+ <code class="structfield">objid</code> and <code class="structfield">classid</code> refer to the
+ table itself). For all other object types, this column is
+ zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">refclassid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog the referenced object is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">refobjid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the specific referenced object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">refobjsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a table column, this is the column number (the
+ <code class="structfield">refobjid</code> and <code class="structfield">refclassid</code> refer
+ to the table itself). For all other object types, this column
+ is zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">deptype</code> <code class="type">char</code>
+ </p>
+ <p>
+ A code defining the specific semantics of this dependency relationship; see text
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In all cases, a <code class="structname">pg_depend</code> entry indicates that the
+ referenced object cannot be dropped without also dropping the dependent
+ object. However, there are several subflavors identified by
+ <code class="structfield">deptype</code>:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">DEPENDENCY_NORMAL</code> (<code class="literal">n</code>)</span></dt><dd><p>
+ A normal relationship between separately-created objects. The
+ dependent object can be dropped without affecting the
+ referenced object. The referenced object can only be dropped
+ by specifying <code class="literal">CASCADE</code>, in which case the dependent
+ object is dropped, too. Example: a table column has a normal
+ dependency on its data type.
+ </p></dd><dt><span class="term"><code class="symbol">DEPENDENCY_AUTO</code> (<code class="literal">a</code>)</span></dt><dd><p>
+ The dependent object can be dropped separately from the
+ referenced object, and should be automatically dropped
+ (regardless of <code class="literal">RESTRICT</code> or <code class="literal">CASCADE</code>
+ mode) if the referenced object is dropped. Example: a named
+ constraint on a table is made auto-dependent on the table, so
+ that it will go away if the table is dropped.
+ </p></dd><dt><span class="term"><code class="symbol">DEPENDENCY_INTERNAL</code> (<code class="literal">i</code>)</span></dt><dd><p>
+ The dependent object was created as part of creation of the
+ referenced object, and is really just a part of its internal
+ implementation. A direct <code class="command">DROP</code> of the dependent
+ object will be disallowed outright (we'll tell the user to issue
+ a <code class="command">DROP</code> against the referenced object, instead).
+ A <code class="command">DROP</code> of the referenced object will result in
+ automatically dropping the dependent object
+ whether <code class="literal">CASCADE</code> is specified or not. If the
+ dependent object has to be dropped due to a dependency on some other
+ object being removed, its drop is converted to a drop of the referenced
+ object, so that <code class="literal">NORMAL</code> and <code class="literal">AUTO</code>
+ dependencies of the dependent object behave much like they were
+ dependencies of the referenced object.
+ Example: a view's <code class="literal">ON SELECT</code> rule is made
+ internally dependent on the view, preventing it from being dropped
+ while the view remains. Dependencies of the rule (such as tables it
+ refers to) act as if they were dependencies of the view.
+ </p></dd><dt><span class="term"><code class="symbol">DEPENDENCY_PARTITION_PRI</code> (<code class="literal">P</code>)<br /></span><span class="term"><code class="symbol">DEPENDENCY_PARTITION_SEC</code> (<code class="literal">S</code>)</span></dt><dd><p>
+ The dependent object was created as part of creation of the
+ referenced object, and is really just a part of its internal
+ implementation; however, unlike <code class="literal">INTERNAL</code>,
+ there is more than one such referenced object. The dependent object
+ must not be dropped unless at least one of these referenced objects
+ is dropped; if any one is, the dependent object should be dropped
+ whether or not <code class="literal">CASCADE</code> is specified. Also
+ unlike <code class="literal">INTERNAL</code>, a drop of some other object
+ that the dependent object depends on does not result in automatic
+ deletion of any partition-referenced object. Hence, if the drop
+ does not cascade to at least one of these objects via some other
+ path, it will be refused. (In most cases, the dependent object
+ shares all its non-partition dependencies with at least one
+ partition-referenced object, so that this restriction does not
+ result in blocking any cascaded delete.)
+ Primary and secondary partition dependencies behave identically
+ except that the primary dependency is preferred for use in error
+ messages; hence, a partition-dependent object should have one
+ primary partition dependency and one or more secondary partition
+ dependencies.
+ Note that partition dependencies are made in addition to, not
+ instead of, any dependencies the object would normally have. This
+ simplifies <code class="command">ATTACH/DETACH PARTITION</code> operations:
+ the partition dependencies need only be added or removed.
+ Example: a child partitioned index is made partition-dependent
+ on both the partition table it is on and the parent partitioned
+ index, so that it goes away if either of those is dropped, but
+ not otherwise. The dependency on the parent index is primary,
+ so that if the user tries to drop the child partitioned index,
+ the error message will suggest dropping the parent index instead
+ (not the table).
+ </p></dd><dt><span class="term"><code class="symbol">DEPENDENCY_EXTENSION</code> (<code class="literal">e</code>)</span></dt><dd><p>
+ The dependent object is a member of the <em class="firstterm">extension</em> that is
+ the referenced object (see
+ <a class="link" href="catalog-pg-extension.html" title="53.22. pg_extension"><code class="structname">pg_extension</code></a>).
+ The dependent object can be dropped only via
+ <a class="link" href="sql-dropextension.html" title="DROP EXTENSION"><code class="command">DROP EXTENSION</code></a> on the referenced object.
+ Functionally this dependency type acts the same as
+ an <code class="literal">INTERNAL</code> dependency, but it's kept separate for
+ clarity and to simplify <span class="application">pg_dump</span>.
+ </p></dd><dt><span class="term"><code class="symbol">DEPENDENCY_AUTO_EXTENSION</code> (<code class="literal">x</code>)</span></dt><dd><p>
+ The dependent object is not a member of the extension that is the
+ referenced object (and so it should not be ignored
+ by <span class="application">pg_dump</span>), but it cannot function
+ without the extension and should be auto-dropped if the extension is.
+ The dependent object may be dropped on its own as well.
+ Functionally this dependency type acts the same as
+ an <code class="literal">AUTO</code> dependency, but it's kept separate for
+ clarity and to simplify <span class="application">pg_dump</span>.
+ </p></dd></dl></div><p>
+
+ Other dependency flavors might be needed in future.
+ </p><p>
+ Note that it's quite possible for two objects to be linked by more than
+ one <code class="structname">pg_depend</code> entry. For example, a child
+ partitioned index would have both a partition-type dependency on its
+ associated partition table, and an auto dependency on each column of
+ that table that it indexes. This sort of situation expresses the union
+ of multiple dependency semantics. A dependent object can be dropped
+ without <code class="literal">CASCADE</code> if any of its dependencies satisfies
+ its condition for automatic dropping. Conversely, all the
+ dependencies' restrictions about which objects must be dropped together
+ must be satisfied.
+ </p><p>
+ Most objects created during <span class="application">initdb</span> are
+ considered <span class="quote">“<span class="quote">pinned</span>”</span>, which means that the system itself
+ depends on them. Therefore, they are never allowed to be dropped.
+ Also, knowing that pinned objects will not be dropped, the dependency
+ mechanism doesn't bother to make <code class="structname">pg_depend</code>
+ entries showing dependencies on them. Thus, for example, a table
+ column of type <code class="type">numeric</code> notionally has
+ a <code class="literal">NORMAL</code> dependency on the <code class="type">numeric</code>
+ data type, but no such entry actually appears
+ in <code class="structname">pg_depend</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-description.html" title="53.19. pg_description">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.17. <code class="structname">pg_default_acl</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.19. <code class="structname">pg_description</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-description.html b/doc/src/sgml/html/catalog-pg-description.html
new file mode 100644
index 0000000..83cda40
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-description.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.19. pg_description</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-depend.html" title="53.18. pg_depend" /><link rel="next" href="catalog-pg-enum.html" title="53.20. pg_enum" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.19. <code class="structname">pg_description</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-depend.html" title="53.18. pg_depend">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-enum.html" title="53.20. pg_enum">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-DESCRIPTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.19. <code class="structname">pg_description</code></h2></div></div></div><a id="id-1.10.4.21.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_description</code> stores optional descriptions
+ (comments) for each database object. Descriptions can be manipulated
+ with the <a class="link" href="sql-comment.html" title="COMMENT"><code class="command">COMMENT</code></a> command and viewed with
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands.
+ Descriptions of many built-in system objects are provided in the initial
+ contents of <code class="structname">pg_description</code>.
+ </p><p>
+ See also <a class="link" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription"><code class="structname">pg_shdescription</code></a>,
+ which performs a similar function for descriptions involving objects that
+ are shared across a database cluster.
+ </p><div class="table" id="id-1.10.4.21.5"><p class="title"><strong>Table 53.19. <code class="structname">pg_description</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_description Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the object this description pertains to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog this object appears in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a comment on a table column, this is the column number (the
+ <code class="structfield">objoid</code> and <code class="structfield">classoid</code> refer to
+ the table itself). For all other object types, this column is
+ zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">description</code> <code class="type">text</code>
+ </p>
+ <p>
+ Arbitrary text that serves as the description of this object
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-depend.html" title="53.18. pg_depend">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-enum.html" title="53.20. pg_enum">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.18. <code class="structname">pg_depend</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.20. <code class="structname">pg_enum</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-enum.html b/doc/src/sgml/html/catalog-pg-enum.html
new file mode 100644
index 0000000..504a1dd
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-enum.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.20. pg_enum</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-description.html" title="53.19. pg_description" /><link rel="next" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.20. <code class="structname">pg_enum</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-description.html" title="53.19. pg_description">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-ENUM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.20. <code class="structname">pg_enum</code></h2></div></div></div><a id="id-1.10.4.22.2" class="indexterm"></a><p>
+ The <code class="structname">pg_enum</code> catalog contains entries
+ showing the values and labels for each enum type. The
+ internal representation of a given enum value is actually the OID
+ of its associated row in <code class="structname">pg_enum</code>.
+ </p><div class="table" id="id-1.10.4.22.4"><p class="title"><strong>Table 53.20. <code class="structname">pg_enum</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_enum Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">enumtypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a> entry owning this enum value
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">enumsortorder</code> <code class="type">float4</code>
+ </p>
+ <p>
+ The sort position of this enum value within its enum type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">enumlabel</code> <code class="type">name</code>
+ </p>
+ <p>
+ The textual label for this enum value
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The OIDs for <code class="structname">pg_enum</code> rows follow a special
+ rule: even-numbered OIDs are guaranteed to be ordered in the same way
+ as the sort ordering of their enum type. That is, if two even OIDs
+ belong to the same enum type, the smaller OID must have the smaller
+ <code class="structfield">enumsortorder</code> value. Odd-numbered OID values
+ need bear no relationship to the sort order. This rule allows the
+ enum comparison routines to avoid catalog lookups in many common cases.
+ The routines that create and alter enum types attempt to assign even
+ OIDs to enum values whenever possible.
+ </p><p>
+ When an enum type is created, its members are assigned sort-order
+ positions 1..<em class="replaceable"><code>n</code></em>. But members added later might be given
+ negative or fractional values of <code class="structfield">enumsortorder</code>.
+ The only requirement on these values is that they be correctly
+ ordered and unique within each enum type.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-description.html" title="53.19. pg_description">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.19. <code class="structname">pg_description</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.21. <code class="structname">pg_event_trigger</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-event-trigger.html b/doc/src/sgml/html/catalog-pg-event-trigger.html
new file mode 100644
index 0000000..ad892a2
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-event-trigger.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.21. pg_event_trigger</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-enum.html" title="53.20. pg_enum" /><link rel="next" href="catalog-pg-extension.html" title="53.22. pg_extension" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.21. <code class="structname">pg_event_trigger</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-enum.html" title="53.20. pg_enum">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-extension.html" title="53.22. pg_extension">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-EVENT-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.21. <code class="structname">pg_event_trigger</code></h2></div></div></div><a id="id-1.10.4.23.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_event_trigger</code> stores event triggers.
+ See <a class="xref" href="event-triggers.html" title="Chapter 40. Event Triggers">Chapter 40</a> for more information.
+ </p><div class="table" id="id-1.10.4.23.4"><p class="title"><strong>Table 53.21. <code class="structname">pg_event_trigger</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_event_trigger Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evtname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Trigger name (must be unique)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evtevent</code> <code class="type">name</code>
+ </p>
+ <p>
+ Identifies the event for which this trigger fires
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evtowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the event trigger
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evtfoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The function to be called
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evtenabled</code> <code class="type">char</code>
+ </p>
+ <p>
+ Controls in which <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a> modes
+ the event trigger fires.
+ <code class="literal">O</code> = trigger fires in <span class="quote">“<span class="quote">origin</span>”</span> and <span class="quote">“<span class="quote">local</span>”</span> modes,
+ <code class="literal">D</code> = trigger is disabled,
+ <code class="literal">R</code> = trigger fires in <span class="quote">“<span class="quote">replica</span>”</span> mode,
+ <code class="literal">A</code> = trigger fires always.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">evttags</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Command tags for which this trigger will fire. If NULL, the firing
+ of this trigger is not restricted on the basis of the command tag.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-enum.html" title="53.20. pg_enum">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-extension.html" title="53.22. pg_extension">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.20. <code class="structname">pg_enum</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.22. <code class="structname">pg_extension</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-extension.html b/doc/src/sgml/html/catalog-pg-extension.html
new file mode 100644
index 0000000..0a71cf4
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-extension.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.22. pg_extension</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger" /><link rel="next" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.22. <code class="structname">pg_extension</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-EXTENSION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.22. <code class="structname">pg_extension</code></h2></div></div></div><a id="id-1.10.4.24.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_extension</code> stores information
+ about the installed extensions. See <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a>
+ for details about extensions.
+ </p><div class="table" id="id-1.10.4.24.4"><p class="title"><strong>Table 53.22. <code class="structname">pg_extension</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_extension Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the extension
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the extension
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Schema containing the extension's exported objects
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extrelocatable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if extension can be relocated to another schema
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extversion</code> <code class="type">text</code>
+ </p>
+ <p>
+ Version name for the extension
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extconfig</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Array of <code class="type">regclass</code> OIDs for the extension's configuration
+ table(s), or <code class="literal">NULL</code> if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extcondition</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Array of <code class="literal">WHERE</code>-clause filter conditions for the
+ extension's configuration table(s), or <code class="literal">NULL</code> if none
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Note that unlike most catalogs with a <span class="quote">“<span class="quote">namespace</span>”</span> column,
+ <code class="structfield">extnamespace</code> is not meant to imply
+ that the extension belongs to that schema. Extension names are never
+ schema-qualified. Rather, <code class="structfield">extnamespace</code>
+ indicates the schema that contains most or all of the extension's
+ objects. If <code class="structfield">extrelocatable</code> is true, then
+ this schema must in fact contain all schema-qualifiable objects
+ belonging to the extension.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.21. <code class="structname">pg_event_trigger</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.23. <code class="structname">pg_foreign_data_wrapper</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-foreign-data-wrapper.html b/doc/src/sgml/html/catalog-pg-foreign-data-wrapper.html
new file mode 100644
index 0000000..7b7daa7
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-foreign-data-wrapper.html
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.23. pg_foreign_data_wrapper</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-extension.html" title="53.22. pg_extension" /><link rel="next" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.23. <code class="structname">pg_foreign_data_wrapper</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-extension.html" title="53.22. pg_extension">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-FOREIGN-DATA-WRAPPER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.23. <code class="structname">pg_foreign_data_wrapper</code></h2></div></div></div><a id="id-1.10.4.25.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_foreign_data_wrapper</code> stores
+ foreign-data wrapper definitions. A foreign-data wrapper is the
+ mechanism by which external data, residing on foreign servers, is
+ accessed.
+ </p><div class="table" id="id-1.10.4.25.4"><p class="title"><strong>Table 53.23. <code class="structname">pg_foreign_data_wrapper</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_foreign_data_wrapper Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the foreign-data wrapper
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the foreign-data wrapper
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwhandler</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ References a handler function that is responsible for
+ supplying execution routines for the foreign-data wrapper.
+ Zero if no handler is provided
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwvalidator</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ References a validator function that is responsible for
+ checking the validity of the options given to the
+ foreign-data wrapper, as well as options for foreign servers and user
+ mappings using the foreign-data wrapper. Zero if no validator
+ is provided
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fdwoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Foreign-data wrapper specific options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-extension.html" title="53.22. pg_extension">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.22. <code class="structname">pg_extension</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.24. <code class="structname">pg_foreign_server</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-foreign-server.html b/doc/src/sgml/html/catalog-pg-foreign-server.html
new file mode 100644
index 0000000..3ea5002
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-foreign-server.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.24. pg_foreign_server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper" /><link rel="next" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.24. <code class="structname">pg_foreign_server</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-FOREIGN-SERVER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.24. <code class="structname">pg_foreign_server</code></h2></div></div></div><a id="id-1.10.4.26.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_foreign_server</code> stores
+ foreign server definitions. A foreign server describes a source
+ of external data, such as a remote server. Foreign
+ servers are accessed via foreign-data wrappers.
+ </p><div class="table" id="id-1.10.4.26.4"><p class="title"><strong>Table 53.24. <code class="structname">pg_foreign_server</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_foreign_server Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvfdw</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper"><code class="structname">pg_foreign_data_wrapper</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the foreign-data wrapper of this foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvtype</code> <code class="type">text</code>
+ </p>
+ <p>
+ Type of the server (optional)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvversion</code> <code class="type">text</code>
+ </p>
+ <p>
+ Version of the server (optional)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Foreign server specific options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.23. <code class="structname">pg_foreign_data_wrapper</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.25. <code class="structname">pg_foreign_table</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-foreign-table.html b/doc/src/sgml/html/catalog-pg-foreign-table.html
new file mode 100644
index 0000000..2146cf9
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-foreign-table.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.25. pg_foreign_table</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server" /><link rel="next" href="catalog-pg-index.html" title="53.26. pg_index" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.25. <code class="structname">pg_foreign_table</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-index.html" title="53.26. pg_index">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-FOREIGN-TABLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.25. <code class="structname">pg_foreign_table</code></h2></div></div></div><a id="id-1.10.4.27.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_foreign_table</code> contains
+ auxiliary information about foreign tables. A foreign table is
+ primarily represented by a
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>
+ entry, just like a regular table. Its <code class="structname">pg_foreign_table</code>
+ entry contains the information that is pertinent only to foreign tables
+ and not any other kind of relation.
+ </p><div class="table" id="id-1.10.4.27.4"><p class="title"><strong>Table 53.25. <code class="structname">pg_foreign_table</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_foreign_table Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ftrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for this foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ftserver</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server"><code class="structname">pg_foreign_server</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the foreign server for this foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ftoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Foreign table options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-index.html" title="53.26. pg_index">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.24. <code class="structname">pg_foreign_server</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.26. <code class="structname">pg_index</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-index.html b/doc/src/sgml/html/catalog-pg-index.html
new file mode 100644
index 0000000..313f973
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-index.html
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.26. pg_index</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table" /><link rel="next" href="catalog-pg-inherits.html" title="53.27. pg_inherits" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.26. <code class="structname">pg_index</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-inherits.html" title="53.27. pg_inherits">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-INDEX"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.26. <code class="structname">pg_index</code></h2></div></div></div><a id="id-1.10.4.28.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_index</code> contains part of the information
+ about indexes. The rest is mostly in
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.
+ </p><div class="table" id="id-1.10.4.28.4"><p class="title"><strong>Table 53.26. <code class="structname">pg_index</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_index Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for the table this index is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indnatts</code> <code class="type">int2</code>
+ </p>
+ <p>
+ The total number of columns in the index (duplicates
+ <code class="literal">pg_class.relnatts</code>); this number includes both key and included attributes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indnkeyatts</code> <code class="type">int2</code>
+ </p>
+ <p>
+ The number of <em class="firstterm">key columns</em> in the index,
+ not counting any <em class="firstterm">included columns</em>, which are
+ merely stored and do not participate in the index semantics
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisunique</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, this is a unique index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indnullsnotdistinct</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This value is only used for unique indexes. If false, this unique
+ index will consider null values distinct (so the index can contain
+ multiple null values in a column, the default PostgreSQL behavior). If
+ it is true, it will consider null values to be equal (so the index can
+ only contain one null value in a column).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisprimary</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, this index represents the primary key of the table
+ (<code class="structfield">indisunique</code> should always be true when this is true)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisexclusion</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, this index supports an exclusion constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indimmediate</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the uniqueness check is enforced immediately on
+ insertion
+ (irrelevant if <code class="structfield">indisunique</code> is not true)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisclustered</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the table was last clustered on this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisvalid</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the index is currently valid for queries. False means the
+ index is possibly incomplete: it must still be modified by
+ <a class="link" href="sql-insert.html" title="INSERT"><code class="command">INSERT</code></a>/<a class="link" href="sql-update.html" title="UPDATE"><code class="command">UPDATE</code></a> operations, but it cannot safely
+ be used for queries. If it is unique, the uniqueness property is not
+ guaranteed true either.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indcheckxmin</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, queries must not use the index until the <code class="structfield">xmin</code>
+ of this <code class="structname">pg_index</code> row is below their <code class="symbol">TransactionXmin</code>
+ event horizon, because the table may contain broken <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">HOT chains</a> with
+ incompatible rows that they can see
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisready</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the index is currently ready for inserts. False means the
+ index must be ignored by <a class="link" href="sql-insert.html" title="INSERT"><code class="command">INSERT</code></a>/<a class="link" href="sql-update.html" title="UPDATE"><code class="command">UPDATE</code></a>
+ operations.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indislive</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If false, the index is in process of being dropped, and should be
+ ignored for all purposes (including HOT-safety decisions)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indisreplident</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true this index has been chosen as <span class="quote">“<span class="quote">replica identity</span>”</span>
+ using <a class="link" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY"><code class="command">ALTER TABLE ...
+ REPLICA IDENTITY USING INDEX ...</code></a>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indkey</code> <code class="type">int2vector</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ This is an array of <code class="structfield">indnatts</code> values that
+ indicate which table columns this index indexes. For example, a value
+ of <code class="literal">1 3</code> would mean that the first and the third table
+ columns make up the index entries. Key columns come before non-key
+ (included) columns. A zero in this array indicates that the
+ corresponding index attribute is an expression over the table columns,
+ rather than a simple column reference.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indcollation</code> <code class="type">oidvector</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For each column in the index key
+ (<code class="structfield">indnkeyatts</code> values), this contains the OID
+ of the collation to use for the index, or zero if the column is not of
+ a collatable data type.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indclass</code> <code class="type">oidvector</code>
+ (references <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For each column in the index key
+ (<code class="structfield">indnkeyatts</code> values), this contains the OID
+ of the operator class to use. See
+ <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a> for details.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indoption</code> <code class="type">int2vector</code>
+ </p>
+ <p>
+ This is an array of <code class="structfield">indnkeyatts</code> values that
+ store per-column flag bits. The meaning of the bits is defined by
+ the index's access method.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexprs</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression trees (in <code class="function">nodeToString()</code>
+ representation) for index attributes that are not simple column
+ references. This is a list with one element for each zero
+ entry in <code class="structfield">indkey</code>. Null if all index attributes
+ are simple references.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indpred</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression tree (in <code class="function">nodeToString()</code>
+ representation) for partial index predicate. Null if not a
+ partial index.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-inherits.html" title="53.27. pg_inherits">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.25. <code class="structname">pg_foreign_table</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.27. <code class="structname">pg_inherits</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-inherits.html b/doc/src/sgml/html/catalog-pg-inherits.html
new file mode 100644
index 0000000..7d02903
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-inherits.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.27. pg_inherits</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-index.html" title="53.26. pg_index" /><link rel="next" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.27. <code class="structname">pg_inherits</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-index.html" title="53.26. pg_index">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-INHERITS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.27. <code class="structname">pg_inherits</code></h2></div></div></div><a id="id-1.10.4.29.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_inherits</code> records information about
+ table and index inheritance hierarchies. There is one entry for each direct
+ parent-child table or index relationship in the database. (Indirect
+ inheritance can be determined by following chains of entries.)
+ </p><div class="table" id="id-1.10.4.29.4"><p class="title"><strong>Table 53.27. <code class="structname">pg_inherits</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_inherits Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inhrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the child table or index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inhparent</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the parent table or index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inhseqno</code> <code class="type">int4</code>
+ </p>
+ <p>
+ If there is more than one direct parent for a child table (multiple
+ inheritance), this number tells the order in which the
+ inherited columns are to be arranged. The count starts at 1.
+ </p>
+ <p>
+ Indexes cannot have multiple inheritance, since they can only inherit
+ when using declarative partitioning.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inhdetachpending</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> for a partition that is in the process of
+ being detached; <code class="literal">false</code> otherwise.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-index.html" title="53.26. pg_index">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.26. <code class="structname">pg_index</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.28. <code class="structname">pg_init_privs</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-init-privs.html b/doc/src/sgml/html/catalog-pg-init-privs.html
new file mode 100644
index 0000000..e6f7697
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-init-privs.html
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.28. pg_init_privs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-inherits.html" title="53.27. pg_inherits" /><link rel="next" href="catalog-pg-language.html" title="53.29. pg_language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.28. <code class="structname">pg_init_privs</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-inherits.html" title="53.27. pg_inherits">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-language.html" title="53.29. pg_language">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-INIT-PRIVS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.28. <code class="structname">pg_init_privs</code></h2></div></div></div><a id="id-1.10.4.30.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_init_privs</code> records information about
+ the initial privileges of objects in the system. There is one entry
+ for each object in the database which has a non-default (non-NULL)
+ initial set of privileges.
+ </p><p>
+ Objects can have initial privileges either by having those privileges set
+ when the system is initialized (by <span class="application">initdb</span>) or when the
+ object is created during a <a class="link" href="sql-createextension.html" title="CREATE EXTENSION"><code class="command">CREATE EXTENSION</code></a> and the
+ extension script sets initial privileges using the <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a>
+ system. Note that the system will automatically handle recording of the
+ privileges during the extension script and that extension authors need
+ only use the <code class="command">GRANT</code> and <code class="command">REVOKE</code>
+ statements in their script to have the privileges recorded. The
+ <code class="literal">privtype</code> column indicates if the initial privilege was
+ set by <span class="application">initdb</span> or during a
+ <code class="command">CREATE EXTENSION</code> command.
+ </p><p>
+ Objects which have initial privileges set by <span class="application">initdb</span> will
+ have entries where <code class="literal">privtype</code> is
+ <code class="literal">'i'</code>, while objects which have initial privileges set
+ by <code class="command">CREATE EXTENSION</code> will have entries where
+ <code class="literal">privtype</code> is <code class="literal">'e'</code>.
+ </p><div class="table" id="id-1.10.4.30.6"><p class="title"><strong>Table 53.28. <code class="structname">pg_init_privs</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_init_privs Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the specific object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog the object is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a table column, this is the column number (the
+ <code class="structfield">objoid</code> and <code class="structfield">classoid</code> refer to the
+ table itself). For all other object types, this column is
+ zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ A code defining the type of initial privilege of this object; see text
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">initprivs</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ The initial access privileges; see
+ <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-inherits.html" title="53.27. pg_inherits">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-language.html" title="53.29. pg_language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.27. <code class="structname">pg_inherits</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.29. <code class="structname">pg_language</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-language.html b/doc/src/sgml/html/catalog-pg-language.html
new file mode 100644
index 0000000..ea5a2e8
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-language.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.29. pg_language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs" /><link rel="next" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.29. <code class="structname">pg_language</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-LANGUAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.29. <code class="structname">pg_language</code></h2></div></div></div><a id="id-1.10.4.31.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_language</code> registers
+ languages in which you can write functions or stored procedures.
+ See <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>
+ and <a class="xref" href="xplang.html" title="Chapter 42. Procedural Languages">Chapter 42</a> for more information about language handlers.
+ </p><div class="table" id="id-1.10.4.31.4"><p class="title"><strong>Table 53.29. <code class="structname">pg_language</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_language Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the language
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the language
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanispl</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This is false for internal languages (such as
+ <acronym class="acronym">SQL</acronym>) and true for user-defined languages.
+ Currently, <span class="application">pg_dump</span> still uses this
+ to determine which languages need to be dumped, but this might be
+ replaced by a different mechanism in the future.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanpltrusted</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this is a trusted language, which means that it is believed
+ not to grant access to anything outside the normal SQL execution
+ environment. Only superusers can create functions in untrusted
+ languages.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanplcallfoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For noninternal languages this references the language
+ handler, which is a special function that is responsible for
+ executing all functions that are written in the particular
+ language. Zero for internal languages.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">laninline</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ This references a function that is responsible for executing
+ <span class="quote">“<span class="quote">inline</span>”</span> anonymous code blocks
+ (<a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> blocks).
+ Zero if inline blocks are not supported.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanvalidator</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ This references a language validator function that is responsible
+ for checking the syntax and validity of new functions when they
+ are created. Zero if no validator is provided.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lanacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.28. <code class="structname">pg_init_privs</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.30. <code class="structname">pg_largeobject</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-largeobject-metadata.html b/doc/src/sgml/html/catalog-pg-largeobject-metadata.html
new file mode 100644
index 0000000..7bd9453
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-largeobject-metadata.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.31. pg_largeobject_metadata</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject" /><link rel="next" href="catalog-pg-namespace.html" title="53.32. pg_namespace" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.31. <code class="structname">pg_largeobject_metadata</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-namespace.html" title="53.32. pg_namespace">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-LARGEOBJECT-METADATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.31. <code class="structname">pg_largeobject_metadata</code></h2></div></div></div><a id="id-1.10.4.33.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_largeobject_metadata</code>
+ holds metadata associated with large objects. The actual large object
+ data is stored in
+ <a class="link" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject"><code class="structname">pg_largeobject</code></a>.
+ </p><div class="table" id="id-1.10.4.33.4"><p class="title"><strong>Table 53.31. <code class="structname">pg_largeobject_metadata</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_largeobject_metadata Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lomowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the large object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lomacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-namespace.html" title="53.32. pg_namespace">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.30. <code class="structname">pg_largeobject</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.32. <code class="structname">pg_namespace</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-largeobject.html b/doc/src/sgml/html/catalog-pg-largeobject.html
new file mode 100644
index 0000000..0149154
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-largeobject.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.30. pg_largeobject</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-language.html" title="53.29. pg_language" /><link rel="next" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.30. <code class="structname">pg_largeobject</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-language.html" title="53.29. pg_language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-LARGEOBJECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.30. <code class="structname">pg_largeobject</code></h2></div></div></div><a id="id-1.10.4.32.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_largeobject</code> holds the data making up
+ <span class="quote">“<span class="quote">large objects</span>”</span>. A large object is identified by an OID
+ assigned when it is created. Each large object is broken into
+ segments or <span class="quote">“<span class="quote">pages</span>”</span> small enough to be conveniently stored as rows
+ in <code class="structname">pg_largeobject</code>.
+ The amount of data per page is defined to be <code class="symbol">LOBLKSIZE</code> (which is currently
+ <code class="literal">BLCKSZ/4</code>, or typically 2 kB).
+ </p><p>
+ Prior to <span class="productname">PostgreSQL</span> 9.0, there was no permission structure
+ associated with large objects. As a result,
+ <code class="structname">pg_largeobject</code> was publicly readable and could be
+ used to obtain the OIDs (and contents) of all large objects in the system.
+ This is no longer the case; use
+ <a class="link" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata"><code class="structname">pg_largeobject_metadata</code></a>
+ to obtain a list of large object OIDs.
+ </p><div class="table" id="id-1.10.4.32.5"><p class="title"><strong>Table 53.30. <code class="structname">pg_largeobject</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_largeobject Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">loid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata"><code class="structname">pg_largeobject_metadata</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Identifier of the large object that includes this page
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pageno</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Page number of this page within its large object
+ (counting from zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data</code> <code class="type">bytea</code>
+ </p>
+ <p>
+ Actual data stored in the large object.
+ This will never be more than <code class="symbol">LOBLKSIZE</code> bytes and might be less.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Each row of <code class="structname">pg_largeobject</code> holds data
+ for one page of a large object, beginning at
+ byte offset (<code class="literal">pageno * LOBLKSIZE</code>) within the object. The implementation
+ allows sparse storage: pages might be missing, and might be shorter than
+ <code class="literal">LOBLKSIZE</code> bytes even if they are not the last page of the object.
+ Missing regions within a large object read as zeroes.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-language.html" title="53.29. pg_language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.29. <code class="structname">pg_language</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.31. <code class="structname">pg_largeobject_metadata</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-namespace.html b/doc/src/sgml/html/catalog-pg-namespace.html
new file mode 100644
index 0000000..b16d623
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-namespace.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.32. pg_namespace</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata" /><link rel="next" href="catalog-pg-opclass.html" title="53.33. pg_opclass" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.32. <code class="structname">pg_namespace</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-opclass.html" title="53.33. pg_opclass">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-NAMESPACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.32. <code class="structname">pg_namespace</code></h2></div></div></div><a id="id-1.10.4.34.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_namespace</code> stores namespaces.
+ A namespace is the structure underlying SQL schemas: each namespace
+ can have a separate collection of relations, types, etc. without name
+ conflicts.
+ </p><div class="table" id="id-1.10.4.34.4"><p class="title"><strong>Table 53.32. <code class="structname">pg_namespace</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_namespace Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">nspname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the namespace
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">nspowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the namespace
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">nspacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-opclass.html" title="53.33. pg_opclass">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.31. <code class="structname">pg_largeobject_metadata</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.33. <code class="structname">pg_opclass</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-opclass.html b/doc/src/sgml/html/catalog-pg-opclass.html
new file mode 100644
index 0000000..57f3ffe
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-opclass.html
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.33. pg_opclass</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-namespace.html" title="53.32. pg_namespace" /><link rel="next" href="catalog-pg-operator.html" title="53.34. pg_operator" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.33. <code class="structname">pg_opclass</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-namespace.html" title="53.32. pg_namespace">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-operator.html" title="53.34. pg_operator">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-OPCLASS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.33. <code class="structname">pg_opclass</code></h2></div></div></div><a id="id-1.10.4.35.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_opclass</code> defines
+ index access method operator classes. Each operator class defines
+ semantics for index columns of a particular data type and a particular
+ index access method. An operator class essentially specifies that a
+ particular operator family is applicable to a particular indexable column
+ data type. The set of operators from the family that are actually usable
+ with the indexed column are whichever ones accept the column's data type
+ as their left-hand input.
+ </p><p>
+ Operator classes are described at length in <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>.
+ </p><div class="table" id="id-1.10.4.35.5"><p class="title"><strong>Table 53.33. <code class="structname">pg_opclass</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_opclass Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcmethod</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Index access method operator class is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this operator class
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Namespace of this operator class
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the operator class
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcfamily</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Operator family containing the operator class
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcintype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type that the operator class indexes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opcdefault</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this operator class is the default for <code class="structfield">opcintype</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opckeytype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type of data stored in index, or zero if same as <code class="structfield">opcintype</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ An operator class's <code class="structfield">opcmethod</code> must match the
+ <code class="structfield">opfmethod</code> of its containing operator family.
+ Also, there must be no more than one <code class="structname">pg_opclass</code>
+ row having <code class="structfield">opcdefault</code> true for any given combination of
+ <code class="structfield">opcmethod</code> and <code class="structfield">opcintype</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-namespace.html" title="53.32. pg_namespace">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-operator.html" title="53.34. pg_operator">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.32. <code class="structname">pg_namespace</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.34. <code class="structname">pg_operator</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-operator.html b/doc/src/sgml/html/catalog-pg-operator.html
new file mode 100644
index 0000000..e99413e
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-operator.html
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.34. pg_operator</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-opclass.html" title="53.33. pg_opclass" /><link rel="next" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.34. <code class="structname">pg_operator</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-opclass.html" title="53.33. pg_opclass">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-OPERATOR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.34. <code class="structname">pg_operator</code></h2></div></div></div><a id="id-1.10.4.36.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_operator</code> stores information about operators.
+ See <a class="xref" href="sql-createoperator.html" title="CREATE OPERATOR"><span class="refentrytitle">CREATE OPERATOR</span></a>
+ and <a class="xref" href="xoper.html" title="38.14. User-Defined Operators">Section 38.14</a> for more information.
+ </p><div class="table" id="id-1.10.4.36.4"><p class="title"><strong>Table 53.34. <code class="structname">pg_operator</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_operator Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the operator
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprkind</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">b</code> = infix operator (<span class="quote">“<span class="quote">both</span>”</span>),
+ or <code class="literal">l</code> = prefix operator (<span class="quote">“<span class="quote">left</span>”</span>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprcanmerge</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This operator supports merge joins
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprcanhash</code> <code class="type">bool</code>
+ </p>
+ <p>
+ This operator supports hash joins
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprleft</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type of the left operand (zero for a prefix operator)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprright</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type of the right operand
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprresult</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type of the result
+ (zero for a not-yet-defined <span class="quote">“<span class="quote">shell</span>”</span> operator)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprcom</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Commutator of this operator (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprnegate</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Negator of this operator (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprcode</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Function that implements this operator
+ (zero for a not-yet-defined <span class="quote">“<span class="quote">shell</span>”</span> operator)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprrest</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Restriction selectivity estimation function for this operator
+ (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oprjoin</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Join selectivity estimation function for this operator
+ (zero if none)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-opclass.html" title="53.33. pg_opclass">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.33. <code class="structname">pg_opclass</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.35. <code class="structname">pg_opfamily</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-opfamily.html b/doc/src/sgml/html/catalog-pg-opfamily.html
new file mode 100644
index 0000000..65ab26f
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-opfamily.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.35. pg_opfamily</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-operator.html" title="53.34. pg_operator" /><link rel="next" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.35. <code class="structname">pg_opfamily</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-operator.html" title="53.34. pg_operator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-OPFAMILY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.35. <code class="structname">pg_opfamily</code></h2></div></div></div><a id="id-1.10.4.37.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_opfamily</code> defines operator families.
+ Each operator family is a collection of operators and associated
+ support routines that implement the semantics specified for a particular
+ index access method. Furthermore, the operators in a family are all
+ <span class="quote">“<span class="quote">compatible</span>”</span>, in a way that is specified by the access method.
+ The operator family concept allows cross-data-type operators to be used
+ with indexes and to be reasoned about using knowledge of access method
+ semantics.
+ </p><p>
+ Operator families are described at length in <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>.
+ </p><div class="table" id="id-1.10.4.37.5"><p class="title"><strong>Table 53.35. <code class="structname">pg_opfamily</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_opfamily Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opfmethod</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Index access method operator family is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opfname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this operator family
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opfnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Namespace of this operator family
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">opfowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the operator family
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The majority of the information defining an operator family is not in its
+ <code class="structname">pg_opfamily</code> row, but in the associated rows in
+ <a class="link" href="catalog-pg-amop.html" title="53.4. pg_amop"><code class="structname">pg_amop</code></a>,
+ <a class="link" href="catalog-pg-amproc.html" title="53.5. pg_amproc"><code class="structname">pg_amproc</code></a>,
+ and
+ <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-operator.html" title="53.34. pg_operator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.34. <code class="structname">pg_operator</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.36. <code class="structname">pg_parameter_acl</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-parameter-acl.html b/doc/src/sgml/html/catalog-pg-parameter-acl.html
new file mode 100644
index 0000000..181cc67
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-parameter-acl.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.36. pg_parameter_acl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily" /><link rel="next" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.36. <code class="structname">pg_parameter_acl</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PARAMETER-ACL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.36. <code class="structname">pg_parameter_acl</code></h2></div></div></div><a id="id-1.10.4.38.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_parameter_acl</code> records configuration
+ parameters for which privileges have been granted to one or more roles.
+ No entry is made for parameters that have default privileges.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_parameter_acl</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_parameter_acl</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.38.5"><p class="title"><strong>Table 53.36. <code class="structname">pg_parameter_acl</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_parameter_acl Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parname</code> <code class="type">text</code>
+ </p>
+ <p>
+ The name of a configuration parameter for which privileges are granted
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">paracl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.35. <code class="structname">pg_opfamily</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.37. <code class="structname">pg_partitioned_table</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-partitioned-table.html b/doc/src/sgml/html/catalog-pg-partitioned-table.html
new file mode 100644
index 0000000..6c1b582
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-partitioned-table.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.37. pg_partitioned_table</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl" /><link rel="next" href="catalog-pg-policy.html" title="53.38. pg_policy" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.37. <code class="structname">pg_partitioned_table</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-policy.html" title="53.38. pg_policy">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PARTITIONED-TABLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.37. <code class="structname">pg_partitioned_table</code></h2></div></div></div><a id="id-1.10.4.39.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_partitioned_table</code> stores
+ information about how tables are partitioned.
+ </p><div class="table" id="id-1.10.4.39.4"><p class="title"><strong>Table 53.37. <code class="structname">pg_partitioned_table</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_partitioned_table Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for this partitioned table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partstrat</code> <code class="type">char</code>
+ </p>
+ <p>
+ Partitioning strategy; <code class="literal">h</code> = hash partitioned table,
+ <code class="literal">l</code> = list partitioned table, <code class="literal">r</code> = range partitioned table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partnatts</code> <code class="type">int2</code>
+ </p>
+ <p>
+ The number of columns in the partition key
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partdefid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for the default partition
+ of this partitioned table, or zero if this partitioned table does not
+ have a default partition
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partattrs</code> <code class="type">int2vector</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ This is an array of <code class="structfield">partnatts</code> values that
+ indicate which table columns are part of the partition key. For
+ example, a value of <code class="literal">1 3</code> would mean that the first
+ and the third table columns make up the partition key. A zero in this
+ array indicates that the corresponding partition key column is an
+ expression, rather than a simple column reference.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partclass</code> <code class="type">oidvector</code>
+ (references <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For each column in the partition key, this contains the OID of the
+ operator class to use. See
+ <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a> for details.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partcollation</code> <code class="type">oidvector</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ For each column in the partition key, this contains the OID of the
+ collation to use for partitioning, or zero if the column is not
+ of a collatable data type.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partexprs</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression trees (in <code class="function">nodeToString()</code>
+ representation) for partition key columns that are not simple column
+ references. This is a list with one element for each zero
+ entry in <code class="structfield">partattrs</code>. Null if all partition key columns
+ are simple references.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-policy.html" title="53.38. pg_policy">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.36. <code class="structname">pg_parameter_acl</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.38. <code class="structname">pg_policy</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-policy.html b/doc/src/sgml/html/catalog-pg-policy.html
new file mode 100644
index 0000000..60dd14f
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-policy.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.38. pg_policy</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table" /><link rel="next" href="catalog-pg-proc.html" title="53.39. pg_proc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.38. <code class="structname">pg_policy</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-proc.html" title="53.39. pg_proc">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-POLICY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.38. <code class="structname">pg_policy</code></h2></div></div></div><a id="id-1.10.4.40.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_policy</code> stores row-level
+ security policies for tables. A policy includes the kind of
+ command that it applies to (possibly all commands), the roles that it
+ applies to, the expression to be added as a security-barrier
+ qualification to queries that include the table, and the expression
+ to be added as a <code class="literal">WITH CHECK</code> option for queries that attempt to
+ add new records to the table.
+ </p><div class="table" id="id-1.10.4.40.4"><p class="title"><strong>Table 53.38. <code class="structname">pg_policy</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_policy Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polname</code> <code class="type">name</code>
+ </p>
+ <p>
+ The name of the policy
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table to which the policy applies
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polcmd</code> <code class="type">char</code>
+ </p>
+ <p>
+ The command type to which the policy is applied:
+ <code class="literal">r</code> for <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>,
+ <code class="literal">a</code> for <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>,
+ <code class="literal">w</code> for <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a>,
+ <code class="literal">d</code> for <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a>,
+ or <code class="literal">*</code> for all
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polpermissive</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Is the policy permissive or restrictive?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polroles</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The roles to which the policy is applied;
+ zero means <code class="literal">PUBLIC</code>
+ (and normally appears alone in the array)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polqual</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ The expression tree to be added to the security barrier qualifications for queries that use the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">polwithcheck</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ The expression tree to be added to the WITH CHECK qualifications for queries that attempt to add rows to the table
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ Policies stored in <code class="structname">pg_policy</code> are applied only when
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relrowsecurity</code> is set for
+ their table.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-proc.html" title="53.39. pg_proc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.37. <code class="structname">pg_partitioned_table</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.39. <code class="structname">pg_proc</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-proc.html b/doc/src/sgml/html/catalog-pg-proc.html
new file mode 100644
index 0000000..9c29fc4
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-proc.html
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.39. pg_proc</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-policy.html" title="53.38. pg_policy" /><link rel="next" href="catalog-pg-publication.html" title="53.40. pg_publication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.39. <code class="structname">pg_proc</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-policy.html" title="53.38. pg_policy">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-publication.html" title="53.40. pg_publication">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PROC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.39. <code class="structname">pg_proc</code></h2></div></div></div><a id="id-1.10.4.41.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_proc</code> stores information about
+ functions, procedures, aggregate functions, and window functions
+ (collectively also known as routines). See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a>, and
+ <a class="xref" href="xfunc.html" title="38.3. User-Defined Functions">Section 38.3</a> for more information.
+ </p><p>
+ If <code class="structfield">prokind</code> indicates that the entry is for an
+ aggregate function, there should be a matching row in
+ <a class="link" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate"><code class="structfield">pg_aggregate</code></a>.
+ </p><div class="table" id="id-1.10.4.41.5"><p class="title"><strong>Table 53.39. <code class="structname">pg_proc</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_proc Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pronamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prolang</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-language.html" title="53.29. pg_language"><code class="structname">pg_language</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Implementation language or call interface of this function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">procost</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Estimated execution cost (in units of
+ <a class="xref" href="runtime-config-query.html#GUC-CPU-OPERATOR-COST">cpu_operator_cost</a>); if <code class="structfield">proretset</code>,
+ this is cost per row returned
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prorows</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Estimated number of result rows (zero if not <code class="structfield">proretset</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">provariadic</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the variadic array parameter's elements,
+ or zero if the function does not have a variadic parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prosupport</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Planner support function for this function
+ (see <a class="xref" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Section 38.11</a>), or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prokind</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="literal">f</code> for a normal function, <code class="literal">p</code>
+ for a procedure, <code class="literal">a</code> for an aggregate function, or
+ <code class="literal">w</code> for a window function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prosecdef</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Function is a security definer (i.e., a <span class="quote">“<span class="quote">setuid</span>”</span>
+ function)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proleakproof</code> <code class="type">bool</code>
+ </p>
+ <p>
+ The function has no side effects. No information about the
+ arguments is conveyed except via the return value. Any function
+ that might throw an error depending on the values of its arguments
+ is not leak-proof.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proisstrict</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Function returns null if any call argument is null. In that
+ case the function won't actually be called at all. Functions
+ that are not <span class="quote">“<span class="quote">strict</span>”</span> must be prepared to handle
+ null inputs.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proretset</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Function returns a set (i.e., multiple values of the specified
+ data type)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">provolatile</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">provolatile</code> tells whether the function's
+ result depends only on its input arguments, or is affected by outside
+ factors.
+ It is <code class="literal">i</code> for <span class="quote">“<span class="quote">immutable</span>”</span> functions,
+ which always deliver the same result for the same inputs.
+ It is <code class="literal">s</code> for <span class="quote">“<span class="quote">stable</span>”</span> functions,
+ whose results (for fixed inputs) do not change within a scan.
+ It is <code class="literal">v</code> for <span class="quote">“<span class="quote">volatile</span>”</span> functions,
+ whose results might change at any time. (Use <code class="literal">v</code> also
+ for functions with side-effects, so that calls to them cannot get
+ optimized away.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proparallel</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">proparallel</code> tells whether the function
+ can be safely run in parallel mode.
+ It is <code class="literal">s</code> for functions which are safe to run in
+ parallel mode without restriction.
+ It is <code class="literal">r</code> for functions which can be run in parallel
+ mode, but their execution is restricted to the parallel group leader;
+ parallel worker processes cannot invoke these functions.
+ It is <code class="literal">u</code> for functions which are unsafe in parallel
+ mode; the presence of such a function forces a serial execution plan.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pronargs</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of input arguments
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pronargdefaults</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of arguments that have defaults
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prorettype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the return value
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proargtypes</code> <code class="type">oidvector</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ An array of the data types of the function arguments. This includes
+ only input arguments (including <code class="literal">INOUT</code> and
+ <code class="literal">VARIADIC</code> arguments), and thus represents
+ the call signature of the function.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proallargtypes</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ An array of the data types of the function arguments. This includes
+ all arguments (including <code class="literal">OUT</code> and
+ <code class="literal">INOUT</code> arguments); however, if all the
+ arguments are <code class="literal">IN</code> arguments, this field will be null.
+ Note that subscripting is 1-based, whereas for historical reasons
+ <code class="structfield">proargtypes</code> is subscripted from 0.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proargmodes</code> <code class="type">char[]</code>
+ </p>
+ <p>
+ An array of the modes of the function arguments, encoded as
+ <code class="literal">i</code> for <code class="literal">IN</code> arguments,
+ <code class="literal">o</code> for <code class="literal">OUT</code> arguments,
+ <code class="literal">b</code> for <code class="literal">INOUT</code> arguments,
+ <code class="literal">v</code> for <code class="literal">VARIADIC</code> arguments,
+ <code class="literal">t</code> for <code class="literal">TABLE</code> arguments.
+ If all the arguments are <code class="literal">IN</code> arguments,
+ this field will be null.
+ Note that subscripts correspond to positions of
+ <code class="structfield">proallargtypes</code> not <code class="structfield">proargtypes</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proargnames</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ An array of the names of the function arguments.
+ Arguments without a name are set to empty strings in the array.
+ If none of the arguments have a name, this field will be null.
+ Note that subscripts correspond to positions of
+ <code class="structfield">proallargtypes</code> not <code class="structfield">proargtypes</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proargdefaults</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression trees (in <code class="function">nodeToString()</code> representation)
+ for default values. This is a list with
+ <code class="structfield">pronargdefaults</code> elements, corresponding to the last
+ <em class="replaceable"><code>N</code></em> <span class="emphasis"><em>input</em></span> arguments (i.e., the last
+ <em class="replaceable"><code>N</code></em> <code class="structfield">proargtypes</code> positions).
+ If none of the arguments have defaults, this field will be null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">protrftypes</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ An array of the argument/result data type(s) for which to apply
+ transforms (from the function's <code class="literal">TRANSFORM</code>
+ clause). Null if none.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prosrc</code> <code class="type">text</code>
+ </p>
+ <p>
+ This tells the function handler how to invoke the function. It
+ might be the actual source code of the function for interpreted
+ languages, a link symbol, a file name, or just about anything
+ else, depending on the implementation language/call convention.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">probin</code> <code class="type">text</code>
+ </p>
+ <p>
+ Additional information about how to invoke the function.
+ Again, the interpretation is language-specific.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prosqlbody</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Pre-parsed SQL function body. This is used for SQL-language
+ functions when the body is given in SQL-standard notation
+ rather than as a string literal. It's null in other cases.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proconfig</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Function's local settings for run-time configuration variables
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">proacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For compiled functions, both built-in and dynamically loaded,
+ <code class="structfield">prosrc</code> contains the function's C-language
+ name (link symbol).
+ For SQL-language functions, <code class="structfield">prosrc</code> contains
+ the function's source text if that is specified as a string literal;
+ but if the function body is specified in SQL-standard style,
+ <code class="structfield">prosrc</code> is unused (typically it's an empty
+ string) and <code class="structfield">prosqlbody</code> contains the
+ pre-parsed definition.
+ For all other currently-known language types,
+ <code class="structfield">prosrc</code> contains the function's source
+ text. <code class="structfield">probin</code> is null except for
+ dynamically-loaded C functions, for which it gives the name of the
+ shared library file containing the function.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-policy.html" title="53.38. pg_policy">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-publication.html" title="53.40. pg_publication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.38. <code class="structname">pg_policy</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.40. <code class="structname">pg_publication</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-publication-namespace.html b/doc/src/sgml/html/catalog-pg-publication-namespace.html
new file mode 100644
index 0000000..8965e2d
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-publication-namespace.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.41. pg_publication_namespace</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-publication.html" title="53.40. pg_publication" /><link rel="next" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.41. <code class="structname">pg_publication_namespace</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-publication.html" title="53.40. pg_publication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PUBLICATION-NAMESPACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.41. <code class="structname">pg_publication_namespace</code></h2></div></div></div><a id="id-1.10.4.43.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_publication_namespace</code> contains the
+ mapping between schemas and publications in the database. This is a
+ many-to-many mapping.
+ </p><div class="table" id="id-1.10.4.43.4"><p class="title"><strong>Table 53.41. <code class="structname">pg_publication_namespace</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_publication_namespace Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pnpubid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-publication.html" title="53.40. pg_publication"><code class="structname">pg_publication</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to publication
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pnnspid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to schema
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-publication.html" title="53.40. pg_publication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.40. <code class="structname">pg_publication</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.42. <code class="structname">pg_publication_rel</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-publication-rel.html b/doc/src/sgml/html/catalog-pg-publication-rel.html
new file mode 100644
index 0000000..a3cd9c6
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-publication-rel.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.42. pg_publication_rel</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace" /><link rel="next" href="catalog-pg-range.html" title="53.43. pg_range" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.42. <code class="structname">pg_publication_rel</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-range.html" title="53.43. pg_range">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PUBLICATION-REL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.42. <code class="structname">pg_publication_rel</code></h2></div></div></div><a id="id-1.10.4.44.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_publication_rel</code> contains the
+ mapping between relations and publications in the database. This is a
+ many-to-many mapping. See also <a class="xref" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables">Section 54.17</a>
+ for a more user-friendly view of this information.
+ </p><div class="table" id="id-1.10.4.44.4"><p class="title"><strong>Table 53.42. <code class="structname">pg_publication_rel</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_publication_rel Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prpubid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-publication.html" title="53.40. pg_publication"><code class="structname">pg_publication</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to publication
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prqual</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>Expression tree (in <code class="function">nodeToString()</code>
+ representation) for the relation's publication qualifying condition. Null
+ if there is no publication qualifying condition.</p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prattrs</code> <code class="type">int2vector</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ This is an array of values that indicates which table columns are
+ part of the publication. For example, a value of <code class="literal">1 3</code>
+ would mean that the first and the third table columns are published.
+ A null value indicates that all columns are published.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-range.html" title="53.43. pg_range">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.41. <code class="structname">pg_publication_namespace</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.43. <code class="structname">pg_range</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-publication.html b/doc/src/sgml/html/catalog-pg-publication.html
new file mode 100644
index 0000000..5d9ab24
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-publication.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.40. pg_publication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-proc.html" title="53.39. pg_proc" /><link rel="next" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.40. <code class="structname">pg_publication</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-proc.html" title="53.39. pg_proc">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-PUBLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.40. <code class="structname">pg_publication</code></h2></div></div></div><a id="id-1.10.4.42.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_publication</code> contains all
+ publications created in the database. For more on publications see
+ <a class="xref" href="logical-replication-publication.html" title="31.1. Publication">Section 31.1</a>.
+ </p><div class="table" id="id-1.10.4.42.4"><p class="title"><strong>Table 53.40. <code class="structname">pg_publication</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_publication Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the publication
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the publication
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">puballtables</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, this publication automatically includes all tables
+ in the database, including any that will be created in the future.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubinsert</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a> operations are replicated for
+ tables in the publication.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubupdate</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a> operations are replicated for
+ tables in the publication.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubdelete</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a> operations are replicated for
+ tables in the publication.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubtruncate</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> operations are replicated for
+ tables in the publication.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubviaroot</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, operations on a leaf partition are replicated using the
+ identity and schema of its topmost partitioned ancestor mentioned in the
+ publication instead of its own.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-proc.html" title="53.39. pg_proc">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.39. <code class="structname">pg_proc</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.41. <code class="structname">pg_publication_namespace</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-range.html b/doc/src/sgml/html/catalog-pg-range.html
new file mode 100644
index 0000000..69d0327
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-range.html
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.43. pg_range</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel" /><link rel="next" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.43. <code class="structname">pg_range</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-RANGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.43. <code class="structname">pg_range</code></h2></div></div></div><a id="id-1.10.4.45.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_range</code> stores information about
+ range types. This is in addition to the types' entries in
+ <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.
+ </p><div class="table" id="id-1.10.4.45.4"><p class="title"><strong>Table 53.43. <code class="structname">pg_range</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_range Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngtypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the range type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngsubtype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the element type (subtype) of this range type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngmultitypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the multirange type for this range type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngcollation</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the collation used for range comparisons, or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngsubopc</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the subtype's operator class used for range comparisons
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngcanonical</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the function to convert a range value into canonical form,
+ or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rngsubdiff</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the function to return the difference between two element
+ values as <code class="type">double precision</code>, or zero if none
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="structfield">rngsubopc</code> (plus <code class="structfield">rngcollation</code>, if the
+ element type is collatable) determines the sort ordering used by the range
+ type. <code class="structfield">rngcanonical</code> is used when the element type is
+ discrete. <code class="structfield">rngsubdiff</code> is optional but should be supplied to
+ improve performance of GiST indexes on the range type.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.42. <code class="structname">pg_publication_rel</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.44. <code class="structname">pg_replication_origin</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-replication-origin.html b/doc/src/sgml/html/catalog-pg-replication-origin.html
new file mode 100644
index 0000000..66167a0
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-replication-origin.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.44. pg_replication_origin</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-range.html" title="53.43. pg_range" /><link rel="next" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.44. <code class="structname">pg_replication_origin</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-range.html" title="53.43. pg_range">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-REPLICATION-ORIGIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.44. <code class="structname">pg_replication_origin</code></h2></div></div></div><a id="id-1.10.4.46.2" class="indexterm"></a><p>
+ The <code class="structname">pg_replication_origin</code> catalog contains
+ all replication origins created. For more on replication origins
+ see <a class="xref" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Chapter 50</a>.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_replication_origin</code>
+ is shared across all databases of a cluster: there is only one copy
+ of <code class="structname">pg_replication_origin</code> per cluster, not one per
+ database.
+ </p><div class="table" id="id-1.10.4.46.5"><p class="title"><strong>Table 53.44. <code class="structname">pg_replication_origin</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_replication_origin Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">roident</code> <code class="type">oid</code>
+ </p>
+ <p>
+ A unique, cluster-wide identifier for the replication
+ origin. Should never leave the system.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">roname</code> <code class="type">text</code>
+ </p>
+ <p>
+ The external, user defined, name of a replication
+ origin.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-range.html" title="53.43. pg_range">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.43. <code class="structname">pg_range</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.45. <code class="structname">pg_rewrite</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-rewrite.html b/doc/src/sgml/html/catalog-pg-rewrite.html
new file mode 100644
index 0000000..e610f4e
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-rewrite.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.45. pg_rewrite</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin" /><link rel="next" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.45. <code class="structname">pg_rewrite</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-REWRITE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.45. <code class="structname">pg_rewrite</code></h2></div></div></div><a id="id-1.10.4.47.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_rewrite</code> stores rewrite rules for tables and views.
+ </p><div class="table" id="id-1.10.4.47.4"><p class="title"><strong>Table 53.45. <code class="structname">pg_rewrite</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_rewrite Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rulename</code> <code class="type">name</code>
+ </p>
+ <p>
+ Rule name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ev_class</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table this rule is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ev_type</code> <code class="type">char</code>
+ </p>
+ <p>
+ Event type that the rule is for: 1 = <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>, 2 =
+ <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a>, 3 = <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>, 4 =
+ <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ev_enabled</code> <code class="type">char</code>
+ </p>
+ <p>
+ Controls in which <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a> modes
+ the rule fires.
+ <code class="literal">O</code> = rule fires in <span class="quote">“<span class="quote">origin</span>”</span> and <span class="quote">“<span class="quote">local</span>”</span> modes,
+ <code class="literal">D</code> = rule is disabled,
+ <code class="literal">R</code> = rule fires in <span class="quote">“<span class="quote">replica</span>”</span> mode,
+ <code class="literal">A</code> = rule fires always.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_instead</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the rule is an <code class="literal">INSTEAD</code> rule
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ev_qual</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression tree (in the form of a
+ <code class="function">nodeToString()</code> representation) for the
+ rule's qualifying condition
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ev_action</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Query tree (in the form of a
+ <code class="function">nodeToString()</code> representation) for the
+ rule's action
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">pg_class.relhasrules</code>
+ must be true if a table has any rules in this catalog.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.44. <code class="structname">pg_replication_origin</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.46. <code class="structname">pg_seclabel</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-seclabel.html b/doc/src/sgml/html/catalog-pg-seclabel.html
new file mode 100644
index 0000000..be5afa1
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-seclabel.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.46. pg_seclabel</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite" /><link rel="next" href="catalog-pg-sequence.html" title="53.47. pg_sequence" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.46. <code class="structname">pg_seclabel</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-sequence.html" title="53.47. pg_sequence">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SECLABEL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.46. <code class="structname">pg_seclabel</code></h2></div></div></div><a id="id-1.10.4.48.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_seclabel</code> stores security
+ labels on database objects. Security labels can be manipulated
+ with the <a class="link" href="sql-security-label.html" title="SECURITY LABEL"><code class="command">SECURITY LABEL</code></a> command. For an easier
+ way to view security labels, see <a class="xref" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Section 54.22</a>.
+ </p><p>
+ See also <a class="link" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel"><code class="structname">pg_shseclabel</code></a>,
+ which performs a similar function for security labels of database objects
+ that are shared across a database cluster.
+ </p><div class="table" id="id-1.10.4.48.5"><p class="title"><strong>Table 53.46. <code class="structname">pg_seclabel</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_seclabel Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the object this security label pertains to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog this object appears in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a security label on a table column, this is the column number (the
+ <code class="structfield">objoid</code> and <code class="structfield">classoid</code> refer to
+ the table itself). For all other object types, this column is
+ zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">provider</code> <code class="type">text</code>
+ </p>
+ <p>
+ The label provider associated with this label.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">label</code> <code class="type">text</code>
+ </p>
+ <p>
+ The security label applied to this object.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-sequence.html" title="53.47. pg_sequence">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.45. <code class="structname">pg_rewrite</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.47. <code class="structname">pg_sequence</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-sequence.html b/doc/src/sgml/html/catalog-pg-sequence.html
new file mode 100644
index 0000000..e3351e8
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-sequence.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.47. pg_sequence</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel" /><link rel="next" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.47. <code class="structname">pg_sequence</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SEQUENCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.47. <code class="structname">pg_sequence</code></h2></div></div></div><a id="id-1.10.4.49.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_sequence</code> contains information about
+ sequences. Some of the information about sequences, such as the name and
+ the schema, is in
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>
+ </p><div class="table" id="id-1.10.4.49.4"><p class="title"><strong>Table 53.47. <code class="structname">pg_sequence</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_sequence Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry for this sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqtypid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqstart</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Start value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqincrement</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Increment value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqmax</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Maximum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqmin</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Minimum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqcache</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Cache size of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqcycle</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Whether the sequence cycles
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.46. <code class="structname">pg_seclabel</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.48. <code class="structname">pg_shdepend</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-shdepend.html b/doc/src/sgml/html/catalog-pg-shdepend.html
new file mode 100644
index 0000000..0cf67cf
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-shdepend.html
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.48. pg_shdepend</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-sequence.html" title="53.47. pg_sequence" /><link rel="next" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.48. <code class="structname">pg_shdepend</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-sequence.html" title="53.47. pg_sequence">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SHDEPEND"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.48. <code class="structname">pg_shdepend</code></h2></div></div></div><a id="id-1.10.4.50.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_shdepend</code> records the
+ dependency relationships between database objects and shared objects,
+ such as roles. This information allows
+ <span class="productname">PostgreSQL</span> to ensure that those objects are
+ unreferenced before attempting to delete them.
+ </p><p>
+ See also <a class="link" href="catalog-pg-depend.html" title="53.18. pg_depend"><code class="structname">pg_depend</code></a>,
+ which performs a similar function for dependencies involving objects
+ within a single database.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_shdepend</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_shdepend</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.50.6"><p class="title"><strong>Table 53.48. <code class="structname">pg_shdepend</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_shdepend Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dbid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the database the dependent object is in,
+ or zero for a shared object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog the dependent object is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the specific dependent object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a table column, this is the column number (the
+ <code class="structfield">objid</code> and <code class="structfield">classid</code> refer to the
+ table itself). For all other object types, this column is zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">refclassid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog the referenced object is in
+ (must be a shared catalog)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">refobjid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the specific referenced object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">deptype</code> <code class="type">char</code>
+ </p>
+ <p>
+ A code defining the specific semantics of this dependency relationship; see text
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In all cases, a <code class="structname">pg_shdepend</code> entry indicates that
+ the referenced object cannot be dropped without also dropping the dependent
+ object. However, there are several subflavors identified by
+ <code class="structfield">deptype</code>:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SHARED_DEPENDENCY_OWNER</code> (<code class="literal">o</code>)</span></dt><dd><p>
+ The referenced object (which must be a role) is the owner of the
+ dependent object.
+ </p></dd><dt><span class="term"><code class="symbol">SHARED_DEPENDENCY_ACL</code> (<code class="literal">a</code>)</span></dt><dd><p>
+ The referenced object (which must be a role) is mentioned in the
+ ACL (access control list, i.e., privileges list) of the
+ dependent object. (A <code class="symbol">SHARED_DEPENDENCY_ACL</code> entry is
+ not made for the owner of the object, since the owner will have
+ a <code class="symbol">SHARED_DEPENDENCY_OWNER</code> entry anyway.)
+ </p></dd><dt><span class="term"><code class="symbol">SHARED_DEPENDENCY_POLICY</code> (<code class="literal">r</code>)</span></dt><dd><p>
+ The referenced object (which must be a role) is mentioned as the
+ target of a dependent policy object.
+ </p></dd><dt><span class="term"><code class="symbol">SHARED_DEPENDENCY_TABLESPACE</code> (<code class="literal">t</code>)</span></dt><dd><p>
+ The referenced object (which must be a tablespace) is mentioned as
+ the tablespace for a relation that doesn't have storage.
+ </p></dd></dl></div><p>
+
+ Other dependency flavors might be needed in future. Note in particular
+ that the current definition only supports roles and tablespaces as referenced
+ objects.
+ </p><p>
+ As in the <code class="structname">pg_depend</code> catalog, most objects
+ created during <span class="application">initdb</span> are
+ considered <span class="quote">“<span class="quote">pinned</span>”</span>. No entries are made
+ in <code class="structname">pg_shdepend</code> that would have a pinned
+ object as either referenced or dependent object.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-sequence.html" title="53.47. pg_sequence">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.47. <code class="structname">pg_sequence</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.49. <code class="structname">pg_shdescription</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-shdescription.html b/doc/src/sgml/html/catalog-pg-shdescription.html
new file mode 100644
index 0000000..c4a53be
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-shdescription.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.49. pg_shdescription</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend" /><link rel="next" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.49. <code class="structname">pg_shdescription</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SHDESCRIPTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.49. <code class="structname">pg_shdescription</code></h2></div></div></div><a id="id-1.10.4.51.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_shdescription</code> stores optional
+ descriptions (comments) for shared database objects. Descriptions can be
+ manipulated with the <a class="link" href="sql-comment.html" title="COMMENT"><code class="command">COMMENT</code></a> command and viewed with
+ <span class="application">psql</span>'s <code class="literal">\d</code> commands.
+ </p><p>
+ See also <a class="link" href="catalog-pg-description.html" title="53.19. pg_description"><code class="structname">pg_description</code></a>,
+ which performs a similar function for descriptions involving objects
+ within a single database.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_shdescription</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_shdescription</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.51.6"><p class="title"><strong>Table 53.49. <code class="structname">pg_shdescription</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_shdescription Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the object this description pertains to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog this object appears in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">description</code> <code class="type">text</code>
+ </p>
+ <p>
+ Arbitrary text that serves as the description of this object
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.48. <code class="structname">pg_shdepend</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.50. <code class="structname">pg_shseclabel</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-shseclabel.html b/doc/src/sgml/html/catalog-pg-shseclabel.html
new file mode 100644
index 0000000..2daa59d
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-shseclabel.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.50. pg_shseclabel</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription" /><link rel="next" href="catalog-pg-statistic.html" title="53.51. pg_statistic" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.50. <code class="structname">pg_shseclabel</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-statistic.html" title="53.51. pg_statistic">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SHSECLABEL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.50. <code class="structname">pg_shseclabel</code></h2></div></div></div><a id="id-1.10.4.52.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_shseclabel</code> stores security
+ labels on shared database objects. Security labels can be manipulated
+ with the <a class="link" href="sql-security-label.html" title="SECURITY LABEL"><code class="command">SECURITY LABEL</code></a> command. For an easier
+ way to view security labels, see <a class="xref" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Section 54.22</a>.
+ </p><p>
+ See also <a class="link" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel"><code class="structname">pg_seclabel</code></a>,
+ which performs a similar function for security labels involving objects
+ within a single database.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_shseclabel</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_shseclabel</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.52.6"><p class="title"><strong>Table 53.50. <code class="structname">pg_shseclabel</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_shseclabel Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the object this security label pertains to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog this object appears in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">provider</code> <code class="type">text</code>
+ </p>
+ <p>
+ The label provider associated with this label.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">label</code> <code class="type">text</code>
+ </p>
+ <p>
+ The security label applied to this object.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-statistic.html" title="53.51. pg_statistic">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.49. <code class="structname">pg_shdescription</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.51. <code class="structname">pg_statistic</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-statistic-ext-data.html b/doc/src/sgml/html/catalog-pg-statistic-ext-data.html
new file mode 100644
index 0000000..37d2257
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-statistic-ext-data.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.53. pg_statistic_ext_data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext" /><link rel="next" href="catalog-pg-subscription.html" title="53.54. pg_subscription" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.53. <code class="structname">pg_statistic_ext_data</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-subscription.html" title="53.54. pg_subscription">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-STATISTIC-EXT-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.53. <code class="structname">pg_statistic_ext_data</code></h2></div></div></div><a id="id-1.10.4.55.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_statistic_ext_data</code>
+ holds data for extended planner statistics defined in
+ <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>.
+ Each row in this catalog corresponds to a <em class="firstterm">statistics object</em>
+ created with <a class="link" href="sql-createstatistics.html" title="CREATE STATISTICS"><code class="command">CREATE STATISTICS</code></a>.
+ </p><p>
+ Normally there is one entry, with <code class="structfield">stxdinherit</code> =
+ <code class="literal">false</code>, for each statistics object that has been analyzed.
+ If the table has inheritance children or partitions, a second entry with
+ <code class="structfield">stxdinherit</code> = <code class="literal">true</code> is also created.
+ This row represents the statistics object over the inheritance tree, i.e.,
+ statistics for the data you'd see with
+ <code class="literal">SELECT * FROM <em class="replaceable"><code>table</code></em>*</code>,
+ whereas the <code class="structfield">stxdinherit</code> = <code class="literal">false</code> row
+ represents the results of
+ <code class="literal">SELECT * FROM ONLY <em class="replaceable"><code>table</code></em></code>.
+ </p><p>
+ Like <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>,
+ <code class="structname">pg_statistic_ext_data</code> should not be
+ readable by the public, since the contents might be considered sensitive.
+ (Example: most common combinations of values in columns might be quite
+ interesting.)
+ <a class="link" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext"><code class="structname">pg_stats_ext</code></a>
+ is a publicly readable view
+ on <code class="structname">pg_statistic_ext_data</code> (after joining
+ with <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>) that only exposes
+ information about those tables and columns that are readable by the
+ current user.
+ </p><div class="table" id="id-1.10.4.55.6"><p class="title"><strong>Table 53.53. <code class="structname">pg_statistic_ext_data</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_statistic_ext_data Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Extended statistics object containing the definition for this data
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxdinherit</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the stats include values from child tables, not just the
+ values in the specified relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxdndistinct</code> <code class="type">pg_ndistinct</code>
+ </p>
+ <p>
+ N-distinct counts, serialized as <code class="structname">pg_ndistinct</code> type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxddependencies</code> <code class="type">pg_dependencies</code>
+ </p>
+ <p>
+ Functional dependency statistics, serialized
+ as <code class="structname">pg_dependencies</code> type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxdmcv</code> <code class="type">pg_mcv_list</code>
+ </p>
+ <p>
+ MCV (most-common values) list statistics, serialized as
+ <code class="structname">pg_mcv_list</code> type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxdexpr</code> <code class="type">pg_statistic[]</code>
+ </p>
+ <p>
+ Per-expression statistics, serialized as an array of
+ <code class="structname">pg_statistic</code> type
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-subscription.html" title="53.54. pg_subscription">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.52. <code class="structname">pg_statistic_ext</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.54. <code class="structname">pg_subscription</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-statistic-ext.html b/doc/src/sgml/html/catalog-pg-statistic-ext.html
new file mode 100644
index 0000000..1a9b500
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-statistic-ext.html
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.52. pg_statistic_ext</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-statistic.html" title="53.51. pg_statistic" /><link rel="next" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.52. <code class="structname">pg_statistic_ext</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-statistic.html" title="53.51. pg_statistic">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-STATISTIC-EXT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.52. <code class="structname">pg_statistic_ext</code></h2></div></div></div><a id="id-1.10.4.54.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_statistic_ext</code>
+ holds definitions of extended planner statistics.
+ Each row in this catalog corresponds to a <em class="firstterm">statistics object</em>
+ created with <a class="link" href="sql-createstatistics.html" title="CREATE STATISTICS"><code class="command">CREATE STATISTICS</code></a>.
+ </p><div class="table" id="id-1.10.4.54.4"><p class="title"><strong>Table 53.52. <code class="structname">pg_statistic_ext</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_statistic_ext Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Table containing the columns described by this object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxstattarget</code> <code class="type">int4</code>
+ </p>
+ <p>
+ <code class="structfield">stxstattarget</code> controls the level of detail
+ of statistics accumulated for this statistics object by
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>.
+ A zero value indicates that no statistics should be collected.
+ A negative value says to use the maximum of the statistics targets of
+ the referenced columns, if set, or the system default statistics target.
+ Positive values of <code class="structfield">stxstattarget</code>
+ determine the target number of <span class="quote">“<span class="quote">most common values</span>”</span>
+ to collect.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxkeys</code> <code class="type">int2vector</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ An array of attribute numbers, indicating which table columns are
+ covered by this statistics object;
+ for example a value of <code class="literal">1 3</code> would
+ mean that the first and the third table columns are covered
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxkind</code> <code class="type">char[]</code>
+ </p>
+ <p>
+ An array containing codes for the enabled statistics kinds;
+ valid values are:
+ <code class="literal">d</code> for n-distinct statistics,
+ <code class="literal">f</code> for functional dependency statistics,
+ <code class="literal">m</code> for most common values (MCV) list statistics, and
+ <code class="literal">e</code> for expression statistics
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stxexprs</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression trees (in <code class="function">nodeToString()</code>
+ representation) for statistics object attributes that are not simple
+ column references. This is a list with one element per expression.
+ Null if all statistics object attributes are simple references.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_statistic_ext</code> entry is filled in
+ completely during <a class="link" href="sql-createstatistics.html" title="CREATE STATISTICS"><code class="command">CREATE STATISTICS</code></a>, but the actual
+ statistical values are not computed then.
+ Subsequent <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> commands compute the desired values
+ and populate an entry in the
+ <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ catalog.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-statistic.html" title="53.51. pg_statistic">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.51. <code class="structname">pg_statistic</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.53. <code class="structname">pg_statistic_ext_data</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-statistic.html b/doc/src/sgml/html/catalog-pg-statistic.html
new file mode 100644
index 0000000..b991189
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-statistic.html
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.51. pg_statistic</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel" /><link rel="next" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.51. <code class="structname">pg_statistic</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-STATISTIC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.51. <code class="structname">pg_statistic</code></h2></div></div></div><a id="id-1.10.4.53.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_statistic</code> stores
+ statistical data about the contents of the database. Entries are
+ created by <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
+ and subsequently used by the query planner. Note that all the
+ statistical data is inherently approximate, even assuming that it
+ is up-to-date.
+ </p><p>
+ Normally there is one entry, with <code class="structfield">stainherit</code> =
+ <code class="literal">false</code>, for each table column that has been analyzed.
+ If the table has inheritance children or partitions, a second entry with
+ <code class="structfield">stainherit</code> = <code class="literal">true</code> is also created. This row
+ represents the column's statistics over the inheritance tree, i.e.,
+ statistics for the data you'd see with
+ <code class="literal">SELECT <em class="replaceable"><code>column</code></em> FROM <em class="replaceable"><code>table</code></em>*</code>,
+ whereas the <code class="structfield">stainherit</code> = <code class="literal">false</code> row represents
+ the results of
+ <code class="literal">SELECT <em class="replaceable"><code>column</code></em> FROM ONLY <em class="replaceable"><code>table</code></em></code>.
+ </p><p>
+ <code class="structname">pg_statistic</code> also stores statistical data about
+ the values of index expressions. These are described as if they were
+ actual data columns; in particular, <code class="structfield">starelid</code>
+ references the index. No entry is made for an ordinary non-expression
+ index column, however, since it would be redundant with the entry
+ for the underlying table column. Currently, entries for index expressions
+ always have <code class="structfield">stainherit</code> = <code class="literal">false</code>.
+ </p><p>
+ Since different kinds of statistics might be appropriate for different
+ kinds of data, <code class="structname">pg_statistic</code> is designed not
+ to assume very much about what sort of statistics it stores. Only
+ extremely general statistics (such as nullness) are given dedicated
+ columns in <code class="structname">pg_statistic</code>. Everything else
+ is stored in <span class="quote">“<span class="quote">slots</span>”</span>, which are groups of associated columns
+ whose content is identified by a code number in one of the slot's columns.
+ For more information see
+ <code class="filename">src/include/catalog/pg_statistic.h</code>.
+ </p><p>
+ <code class="structname">pg_statistic</code> should not be readable by the
+ public, since even statistical information about a table's contents
+ might be considered sensitive. (Example: minimum and maximum values
+ of a salary column might be quite interesting.)
+ <a class="link" href="view-pg-stats.html" title="54.27. pg_stats"><code class="structname">pg_stats</code></a>
+ is a publicly readable view on
+ <code class="structname">pg_statistic</code> that only exposes information
+ about those tables that are readable by the current user.
+ </p><div class="table" id="id-1.10.4.53.8"><p class="title"><strong>Table 53.51. <code class="structname">pg_statistic</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_statistic Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">starelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table or index that the described column belongs to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">staattnum</code> <code class="type">int2</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ The number of the described column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stainherit</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the stats include values from child tables, not just the
+ values in the specified relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stanullfrac</code> <code class="type">float4</code>
+ </p>
+ <p>
+ The fraction of the column's entries that are null
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stawidth</code> <code class="type">int4</code>
+ </p>
+ <p>
+ The average stored width, in bytes, of nonnull entries
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stadistinct</code> <code class="type">float4</code>
+ </p>
+ <p>
+ The number of distinct nonnull data values in the column.
+ A value greater than zero is the actual number of distinct values.
+ A value less than zero is the negative of a multiplier for the number
+ of rows in the table; for example, a column in which about 80% of the
+ values are nonnull and each nonnull value appears about twice on
+ average could be represented by <code class="structfield">stadistinct</code> = -0.4.
+ A zero value means the number of distinct values is unknown.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stakind<em class="replaceable"><code>N</code></em></code> <code class="type">int2</code>
+ </p>
+ <p>
+ A code number indicating the kind of statistics stored in the
+ <em class="replaceable"><code>N</code></em>th <span class="quote">“<span class="quote">slot</span>”</span> of the
+ <code class="structname">pg_statistic</code> row.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">staop<em class="replaceable"><code>N</code></em></code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ An operator used to derive the statistics stored in the
+ <em class="replaceable"><code>N</code></em>th <span class="quote">“<span class="quote">slot</span>”</span>. For example, a
+ histogram slot would show the <code class="literal">&lt;</code> operator
+ that defines the sort order of the data.
+ Zero if the statistics kind does not require an operator.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stacoll<em class="replaceable"><code>N</code></em></code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The collation used to derive the statistics stored in the
+ <em class="replaceable"><code>N</code></em>th <span class="quote">“<span class="quote">slot</span>”</span>. For example, a
+ histogram slot for a collatable column would show the collation that
+ defines the sort order of the data. Zero for noncollatable data.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stanumbers<em class="replaceable"><code>N</code></em></code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ Numerical statistics of the appropriate kind for the
+ <em class="replaceable"><code>N</code></em>th <span class="quote">“<span class="quote">slot</span>”</span>, or null if the slot
+ kind does not involve numerical values
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stavalues<em class="replaceable"><code>N</code></em></code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ Column data values of the appropriate kind for the
+ <em class="replaceable"><code>N</code></em>th <span class="quote">“<span class="quote">slot</span>”</span>, or null if the slot
+ kind does not store any data values. Each array's element
+ values are actually of the specific column's data type, or a related
+ type such as an array's element type, so there is no way to define
+ these columns' type more specifically than <code class="type">anyarray</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.50. <code class="structname">pg_shseclabel</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.52. <code class="structname">pg_statistic_ext</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-subscription-rel.html b/doc/src/sgml/html/catalog-pg-subscription-rel.html
new file mode 100644
index 0000000..39260a0
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-subscription-rel.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.55. pg_subscription_rel</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-subscription.html" title="53.54. pg_subscription" /><link rel="next" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.55. <code class="structname">pg_subscription_rel</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-subscription.html" title="53.54. pg_subscription">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SUBSCRIPTION-REL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.55. <code class="structname">pg_subscription_rel</code></h2></div></div></div><a id="id-1.10.4.57.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_subscription_rel</code> contains the
+ state for each replicated relation in each subscription. This is a
+ many-to-many mapping.
+ </p><p>
+ This catalog only contains tables known to the subscription after running
+ either <a class="link" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><code class="command">CREATE SUBSCRIPTION</code></a> or
+ <a class="link" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><code class="command">ALTER SUBSCRIPTION ... REFRESH
+ PUBLICATION</code></a>.
+ </p><div class="table" id="id-1.10.4.57.5"><p class="title"><strong>Table 53.55. <code class="structname">pg_subscription_rel</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_subscription_rel Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srsubid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-subscription.html" title="53.54. pg_subscription"><code class="structname">pg_subscription</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Reference to relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srsubstate</code> <code class="type">char</code>
+ </p>
+ <p>
+ State code:
+ <code class="literal">i</code> = initialize,
+ <code class="literal">d</code> = data is being copied,
+ <code class="literal">f</code> = finished table copy,
+ <code class="literal">s</code> = synchronized,
+ <code class="literal">r</code> = ready (normal replication)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srsublsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Remote LSN of the state change used for synchronization coordination
+ when in <code class="literal">s</code> or <code class="literal">r</code> states,
+ otherwise null
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-subscription.html" title="53.54. pg_subscription">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.54. <code class="structname">pg_subscription</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.56. <code class="structname">pg_tablespace</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-subscription.html b/doc/src/sgml/html/catalog-pg-subscription.html
new file mode 100644
index 0000000..4400b09
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-subscription.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.54. pg_subscription</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data" /><link rel="next" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.54. <code class="structname">pg_subscription</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-SUBSCRIPTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.54. <code class="structname">pg_subscription</code></h2></div></div></div><a id="id-1.10.4.56.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_subscription</code> contains all existing
+ logical replication subscriptions. For more information about logical
+ replication see <a class="xref" href="logical-replication.html" title="Chapter 31. Logical Replication">Chapter 31</a>.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_subscription</code> is
+ shared across all databases of a cluster: there is only one copy
+ of <code class="structname">pg_subscription</code> per cluster, not one per
+ database.
+ </p><p>
+ Access to the column <code class="structfield">subconninfo</code> is revoked from
+ normal users, because it could contain plain-text passwords.
+ </p><div class="table" id="id-1.10.4.56.6"><p class="title"><strong>Table 53.54. <code class="structname">pg_subscription</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_subscription Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subdbid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the database that the subscription resides in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subskiplsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Finish LSN of the transaction whose changes are to be skipped, if a valid
+ LSN; otherwise <code class="literal">0/0</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subenabled</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the subscription is enabled and should be replicating
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subbinary</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the subscription will request that the publisher send data
+ in binary format
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">substream</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the subscription will allow streaming of in-progress
+ transactions
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subtwophasestate</code> <code class="type">char</code>
+ </p>
+ <p>
+ State codes for two-phase mode:
+ <code class="literal">d</code> = disabled,
+ <code class="literal">p</code> = pending enablement,
+ <code class="literal">e</code> = enabled
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subdisableonerr</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, the subscription will be disabled if one of its workers
+ detects an error
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subconninfo</code> <code class="type">text</code>
+ </p>
+ <p>
+ Connection string to the upstream database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subslotname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the replication slot in the upstream database (also used
+ for the local replication origin name);
+ null represents <code class="literal">NONE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subsynccommit</code> <code class="type">text</code>
+ </p>
+ <p>
+ The <code class="varname">synchronous_commit</code>
+ setting for the subscription's workers to use
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subpublications</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Array of subscribed publication names. These reference
+ publications defined in the upstream database. For more on publications
+ see <a class="xref" href="logical-replication-publication.html" title="31.1. Publication">Section 31.1</a>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.53. <code class="structname">pg_statistic_ext_data</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.55. <code class="structname">pg_subscription_rel</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-tablespace.html b/doc/src/sgml/html/catalog-pg-tablespace.html
new file mode 100644
index 0000000..eb13f76
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-tablespace.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.56. pg_tablespace</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel" /><link rel="next" href="catalog-pg-transform.html" title="53.57. pg_transform" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.56. <code class="structname">pg_tablespace</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-transform.html" title="53.57. pg_transform">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TABLESPACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.56. <code class="structname">pg_tablespace</code></h2></div></div></div><a id="id-1.10.4.58.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_tablespace</code> stores information
+ about the available tablespaces. Tables can be placed in particular
+ tablespaces to aid administration of disk layout.
+ </p><p>
+ Unlike most system catalogs, <code class="structname">pg_tablespace</code>
+ is shared across all databases of a cluster: there is only one
+ copy of <code class="structname">pg_tablespace</code> per cluster, not
+ one per database.
+ </p><div class="table" id="id-1.10.4.58.5"><p class="title"><strong>Table 53.56. <code class="structname">pg_tablespace</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_tablespace Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spcname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Tablespace name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spcowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the tablespace, usually the user who created it
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spcacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spcoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Tablespace-level options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-transform.html" title="53.57. pg_transform">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.55. <code class="structname">pg_subscription_rel</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.57. <code class="structname">pg_transform</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-transform.html b/doc/src/sgml/html/catalog-pg-transform.html
new file mode 100644
index 0000000..a22ba51
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-transform.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.57. pg_transform</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace" /><link rel="next" href="catalog-pg-trigger.html" title="53.58. pg_trigger" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.57. <code class="structname">pg_transform</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-trigger.html" title="53.58. pg_trigger">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TRANSFORM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.57. <code class="structname">pg_transform</code></h2></div></div></div><a id="id-1.10.4.59.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_transform</code> stores information about
+ transforms, which are a mechanism to adapt data types to procedural
+ languages. See <a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a> for more information.
+ </p><div class="table" id="id-1.10.4.59.4"><p class="title"><strong>Table 53.57. <code class="structname">pg_transform</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_transform Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trftype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the data type this transform is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trflang</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-language.html" title="53.29. pg_language"><code class="structname">pg_language</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the language this transform is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trffromsql</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the function to use when converting the data type for input
+ to the procedural language (e.g., function parameters). Zero is stored
+ if the default behavior should be used.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trftosql</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the function to use when converting output from the
+ procedural language (e.g., return values) to the data type. Zero is
+ stored if the default behavior should be used.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-trigger.html" title="53.58. pg_trigger">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.56. <code class="structname">pg_tablespace</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.58. <code class="structname">pg_trigger</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-trigger.html b/doc/src/sgml/html/catalog-pg-trigger.html
new file mode 100644
index 0000000..da92ff0
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-trigger.html
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.58. pg_trigger</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-transform.html" title="53.57. pg_transform" /><link rel="next" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.58. <code class="structname">pg_trigger</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-transform.html" title="53.57. pg_transform">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.58. <code class="structname">pg_trigger</code></h2></div></div></div><a id="id-1.10.4.60.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_trigger</code> stores triggers on tables
+ and views.
+ See <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>
+ for more information.
+ </p><div class="table" id="id-1.10.4.60.4"><p class="title"><strong>Table 53.58. <code class="structname">pg_trigger</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_trigger Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table this trigger is on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgparentid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-trigger.html" title="53.58. pg_trigger"><code class="structname">pg_trigger</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Parent trigger that this trigger is cloned from (this happens when
+ partitions are created or attached to a partitioned table);
+ zero if not a clone
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Trigger name (must be unique among triggers of same table)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgfoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The function to be called
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgtype</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Bit mask identifying trigger firing conditions
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgenabled</code> <code class="type">char</code>
+ </p>
+ <p>
+ Controls in which <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a> modes
+ the trigger fires.
+ <code class="literal">O</code> = trigger fires in <span class="quote">“<span class="quote">origin</span>”</span> and <span class="quote">“<span class="quote">local</span>”</span> modes,
+ <code class="literal">D</code> = trigger is disabled,
+ <code class="literal">R</code> = trigger fires in <span class="quote">“<span class="quote">replica</span>”</span> mode,
+ <code class="literal">A</code> = trigger fires always.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgisinternal</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if trigger is internally generated (usually, to enforce
+ the constraint identified by <code class="structfield">tgconstraint</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgconstrrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The table referenced by a referential integrity constraint
+ (zero if trigger is not for a referential integrity constraint)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgconstrindid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The index supporting a unique, primary key, referential integrity,
+ or exclusion constraint
+ (zero if trigger is not for one of these types of constraint)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgconstraint</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The <a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a> entry associated with the trigger
+ (zero if trigger is not for a constraint)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgdeferrable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if constraint trigger is deferrable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tginitdeferred</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if constraint trigger is initially deferred
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgnargs</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Number of argument strings passed to trigger function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgattr</code> <code class="type">int2vector</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attnum</code>)
+ </p>
+ <p>
+ Column numbers, if trigger is column-specific; otherwise an
+ empty array
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgargs</code> <code class="type">bytea</code>
+ </p>
+ <p>
+ Argument strings to pass to trigger, each NULL-terminated
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgqual</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ Expression tree (in <code class="function">nodeToString()</code>
+ representation) for the trigger's <code class="literal">WHEN</code> condition, or null
+ if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgoldtable</code> <code class="type">name</code>
+ </p>
+ <p>
+ <code class="literal">REFERENCING</code> clause name for <code class="literal">OLD TABLE</code>,
+ or null if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tgnewtable</code> <code class="type">name</code>
+ </p>
+ <p>
+ <code class="literal">REFERENCING</code> clause name for <code class="literal">NEW TABLE</code>,
+ or null if none
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Currently, column-specific triggering is supported only for
+ <code class="literal">UPDATE</code> events, and so <code class="structfield">tgattr</code> is relevant
+ only for that event type. <code class="structfield">tgtype</code> might
+ contain bits for other event types as well, but those are presumed
+ to be table-wide regardless of what is in <code class="structfield">tgattr</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When <code class="structfield">tgconstraint</code> is nonzero,
+ <code class="structfield">tgconstrrelid</code>, <code class="structfield">tgconstrindid</code>,
+ <code class="structfield">tgdeferrable</code>, and <code class="structfield">tginitdeferred</code> are
+ largely redundant with the referenced <a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a> entry.
+ However, it is possible for a non-deferrable trigger to be associated
+ with a deferrable constraint: foreign key constraints can have some
+ deferrable and some non-deferrable triggers.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">pg_class.relhastriggers</code>
+ must be true if a relation has any triggers in this catalog.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-transform.html" title="53.57. pg_transform">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.57. <code class="structname">pg_transform</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.59. <code class="structname">pg_ts_config</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-ts-config-map.html b/doc/src/sgml/html/catalog-pg-ts-config-map.html
new file mode 100644
index 0000000..33a26ec
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-ts-config-map.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.60. pg_ts_config_map</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config" /><link rel="next" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.60. <code class="structname">pg_ts_config_map</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TS-CONFIG-MAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.60. <code class="structname">pg_ts_config_map</code></h2></div></div></div><a id="id-1.10.4.62.2" class="indexterm"></a><p>
+ The <code class="structname">pg_ts_config_map</code> catalog contains entries
+ showing which text search dictionaries should be consulted, and in
+ what order, for each output token type of each text search configuration's
+ parser.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s text search features are
+ described at length in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="id-1.10.4.62.5"><p class="title"><strong>Table 53.60. <code class="structname">pg_ts_config_map</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ts_config_map Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mapcfg</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config"><code class="structname">pg_ts_config</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the <a class="link" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config"><code class="structname">pg_ts_config</code></a> entry owning this map entry
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maptokentype</code> <code class="type">int4</code>
+ </p>
+ <p>
+ A token type emitted by the configuration's parser
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mapseqno</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Order in which to consult this entry (lower
+ <code class="structfield">mapseqno</code>s first)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mapdict</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict"><code class="structname">pg_ts_dict</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the text search dictionary to consult
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.59. <code class="structname">pg_ts_config</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.61. <code class="structname">pg_ts_dict</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-ts-config.html b/doc/src/sgml/html/catalog-pg-ts-config.html
new file mode 100644
index 0000000..6ff3a84
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-ts-config.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.59. pg_ts_config</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-trigger.html" title="53.58. pg_trigger" /><link rel="next" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.59. <code class="structname">pg_ts_config</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-trigger.html" title="53.58. pg_trigger">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TS-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.59. <code class="structname">pg_ts_config</code></h2></div></div></div><a id="id-1.10.4.61.2" class="indexterm"></a><p>
+ The <code class="structname">pg_ts_config</code> catalog contains entries
+ representing text search configurations. A configuration specifies
+ a particular text search parser and a list of dictionaries to use
+ for each of the parser's output token types. The parser is shown
+ in the <code class="structname">pg_ts_config</code> entry, but the
+ token-to-dictionary mapping is defined by subsidiary entries in <a class="link" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map"><code class="structname">pg_ts_config_map</code></a>.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s text search features are
+ described at length in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="id-1.10.4.61.5"><p class="title"><strong>Table 53.59. <code class="structname">pg_ts_config</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ts_config Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cfgname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Text search configuration name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cfgnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this configuration
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cfgowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the configuration
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cfgparser</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser"><code class="structname">pg_ts_parser</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the text search parser for this configuration
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-trigger.html" title="53.58. pg_trigger">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.58. <code class="structname">pg_trigger</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.60. <code class="structname">pg_ts_config_map</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-ts-dict.html b/doc/src/sgml/html/catalog-pg-ts-dict.html
new file mode 100644
index 0000000..f35bea4
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-ts-dict.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.61. pg_ts_dict</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map" /><link rel="next" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.61. <code class="structname">pg_ts_dict</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TS-DICT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.61. <code class="structname">pg_ts_dict</code></h2></div></div></div><a id="id-1.10.4.63.2" class="indexterm"></a><p>
+ The <code class="structname">pg_ts_dict</code> catalog contains entries
+ defining text search dictionaries. A dictionary depends on a text
+ search template, which specifies all the implementation functions
+ needed; the dictionary itself provides values for the user-settable
+ parameters supported by the template. This division of labor allows
+ dictionaries to be created by unprivileged users. The parameters
+ are specified by a text string <code class="structfield">dictinitoption</code>,
+ whose format and meaning vary depending on the template.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s text search features are
+ described at length in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="id-1.10.4.63.5"><p class="title"><strong>Table 53.61. <code class="structname">pg_ts_dict</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ts_dict Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dictname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Text search dictionary name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dictnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this dictionary
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dictowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the dictionary
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dicttemplate</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template"><code class="structname">pg_ts_template</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the text search template for this dictionary
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dictinitoption</code> <code class="type">text</code>
+ </p>
+ <p>
+ Initialization option string for the template
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.60. <code class="structname">pg_ts_config_map</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.62. <code class="structname">pg_ts_parser</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-ts-parser.html b/doc/src/sgml/html/catalog-pg-ts-parser.html
new file mode 100644
index 0000000..0a56d1f
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-ts-parser.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.62. pg_ts_parser</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict" /><link rel="next" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.62. <code class="structname">pg_ts_parser</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TS-PARSER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.62. <code class="structname">pg_ts_parser</code></h2></div></div></div><a id="id-1.10.4.64.2" class="indexterm"></a><p>
+ The <code class="structname">pg_ts_parser</code> catalog contains entries
+ defining text search parsers. A parser is responsible for splitting
+ input text into lexemes and assigning a token type to each lexeme.
+ Since a parser must be implemented by C-language-level functions,
+ creation of new parsers is restricted to database superusers.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s text search features are
+ described at length in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="id-1.10.4.64.5"><p class="title"><strong>Table 53.62. <code class="structname">pg_ts_parser</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ts_parser Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prsname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Text search parser name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prsnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this parser
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prsstart</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the parser's startup function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prstoken</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the parser's next-token function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prsend</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the parser's shutdown function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prsheadline</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the parser's headline function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prslextype</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the parser's lextype function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.61. <code class="structname">pg_ts_dict</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.63. <code class="structname">pg_ts_template</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-ts-template.html b/doc/src/sgml/html/catalog-pg-ts-template.html
new file mode 100644
index 0000000..7802b78
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-ts-template.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.63. pg_ts_template</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser" /><link rel="next" href="catalog-pg-type.html" title="53.64. pg_type" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.63. <code class="structname">pg_ts_template</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-type.html" title="53.64. pg_type">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TS-TEMPLATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.63. <code class="structname">pg_ts_template</code></h2></div></div></div><a id="id-1.10.4.65.2" class="indexterm"></a><p>
+ The <code class="structname">pg_ts_template</code> catalog contains entries
+ defining text search templates. A template is the implementation
+ skeleton for a class of text search dictionaries.
+ Since a template must be implemented by C-language-level functions,
+ creation of new templates is restricted to database superusers.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s text search features are
+ described at length in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="id-1.10.4.65.5"><p class="title"><strong>Table 53.63. <code class="structname">pg_ts_template</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ts_template Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tmplname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Text search template name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tmplnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this template
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tmplinit</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the template's initialization function (zero if none)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tmpllexize</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the template's lexize function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-type.html" title="53.64. pg_type">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.62. <code class="structname">pg_ts_parser</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.64. <code class="structname">pg_type</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-type.html b/doc/src/sgml/html/catalog-pg-type.html
new file mode 100644
index 0000000..93b96cf
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-type.html
@@ -0,0 +1,310 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.64. pg_type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template" /><link rel="next" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.64. <code class="structname">pg_type</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-TYPE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.64. <code class="structname">pg_type</code></h2></div></div></div><a id="id-1.10.4.66.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_type</code> stores information about data
+ types. Base types and enum types (scalar types) are created with
+ <a class="link" href="sql-createtype.html" title="CREATE TYPE"><code class="command">CREATE TYPE</code></a>, and
+ domains with
+ <a class="link" href="sql-createdomain.html" title="CREATE DOMAIN"><code class="command">CREATE DOMAIN</code></a>.
+ 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 <code class="command">CREATE TYPE AS</code>.
+ </p><div class="table" id="id-1.10.4.66.4"><p class="title"><strong>Table 53.64. <code class="structname">pg_type</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_type Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Data type name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace that contains this type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typowner</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Owner of the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typlen</code> <code class="type">int2</code>
+ </p>
+ <p>
+ For a fixed-size type, <code class="structfield">typlen</code> is the number
+ of bytes in the internal representation of the type. But for a
+ variable-length type, <code class="structfield">typlen</code> is negative.
+ -1 indicates a <span class="quote">“<span class="quote">varlena</span>”</span> type (one that has a length word),
+ -2 indicates a null-terminated C string.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typbyval</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="structfield">typbyval</code> determines whether internal
+ routines pass a value of this type by value or by reference.
+ <code class="structfield">typbyval</code> had better be false if
+ <code class="structfield">typlen</code> is not 1, 2, or 4 (or 8 on machines
+ where Datum is 8 bytes).
+ Variable-length types are always passed by reference. Note that
+ <code class="structfield">typbyval</code> can be false even if the
+ length would allow pass-by-value.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typtype</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">typtype</code> is
+ <code class="literal">b</code> for a base type,
+ <code class="literal">c</code> for a composite type (e.g., a table's row type),
+ <code class="literal">d</code> for a domain,
+ <code class="literal">e</code> for an enum type,
+ <code class="literal">p</code> for a pseudo-type,
+ <code class="literal">r</code> for a range type, or
+ <code class="literal">m</code> for a multirange type.
+ See also <code class="structfield">typrelid</code> and
+ <code class="structfield">typbasetype</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typcategory</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">typcategory</code> is an arbitrary classification
+ of data types that is used by the parser to determine which implicit
+ casts should be <span class="quote">“<span class="quote">preferred</span>”</span>.
+ See <a class="xref" href="catalog-pg-type.html#CATALOG-TYPCATEGORY-TABLE" title="Table 53.65. typcategory Codes">Table 53.65</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typispreferred</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the type is a preferred cast target within its
+ <code class="structfield">typcategory</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typisdefined</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the type is defined, false if this is a placeholder
+ entry for a not-yet-defined type. When
+ <code class="structfield">typisdefined</code> is false, nothing
+ except the type name, namespace, and OID can be relied on.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typdelim</code> <code class="type">char</code>
+ </p>
+ <p>
+ Character that separates two values of this type when parsing
+ array input. Note that the delimiter is associated with the array
+ element data type, not the array data type.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typrelid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If this is a composite type (see
+ <code class="structfield">typtype</code>), then this column points to
+ the <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry that defines the
+ corresponding table. (For a free-standing composite type, the
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a> entry doesn't really represent
+ a table, but it is needed anyway for the type's
+ <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a> entries to link to.)
+ Zero for non-composite types.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typsubscript</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Subscripting handler function's OID, or zero if this type doesn't
+ support subscripting. Types that are <span class="quote">“<span class="quote">true</span>”</span> array
+ types have <code class="structfield">typsubscript</code>
+ = <code class="function">array_subscript_handler</code>, but other types may
+ have other handler functions to implement specialized subscripting
+ behavior.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typelem</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If <code class="structfield">typelem</code> is not zero then it
+ identifies another row in <code class="structname">pg_type</code>,
+ defining the type yielded by subscripting. This should be zero
+ if <code class="structfield">typsubscript</code> is zero. However, it can
+ be zero when <code class="structfield">typsubscript</code> isn't zero, if the
+ handler doesn't need <code class="structfield">typelem</code> to
+ determine the subscripting result type.
+ Note that a <code class="structfield">typelem</code> dependency is
+ considered to imply physical containment of the element type in
+ this type; so DDL changes on the element type might be restricted
+ by the presence of this type.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typarray</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If <code class="structfield">typarray</code> is not zero then it
+ identifies another row in <code class="structname">pg_type</code>, which
+ is the <span class="quote">“<span class="quote">true</span>”</span> array type having this type as element
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typinput</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Input conversion function (text format)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typoutput</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Output conversion function (text format)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typreceive</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Input conversion function (binary format), or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typsend</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Output conversion function (binary format), or zero if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typmodin</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type modifier input function, or zero if type does not support modifiers
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typmodout</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Type modifier output function, or zero to use the standard format
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typanalyze</code> <code class="type">regproc</code>
+ (references <a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Custom <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a> function,
+ or zero to use the standard function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typalign</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">typalign</code> is the alignment required
+ when storing a value of this type. It applies to storage on
+ disk as well as most representations of the value inside
+ <span class="productname">PostgreSQL</span>.
+ When multiple values are stored consecutively, such
+ as in the representation of a complete row on disk, padding is
+ inserted before a datum of this type so that it begins on the
+ specified boundary. The alignment reference is the beginning
+ of the first datum in the sequence.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">c</code> = <code class="type">char</code> alignment, i.e., no alignment needed.</p></li><li class="listitem"><p><code class="literal">s</code> = <code class="type">short</code> alignment (2 bytes on most machines).</p></li><li class="listitem"><p><code class="literal">i</code> = <code class="type">int</code> alignment (4 bytes on most machines).</p></li><li class="listitem"><p><code class="literal">d</code> = <code class="type">double</code> alignment (8 bytes on many machines, but by no means all).</p></li></ul></div><p>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typstorage</code> <code class="type">char</code>
+ </p>
+ <p>
+ <code class="structfield">typstorage</code> tells for varlena
+ types (those with <code class="structfield">typlen</code> = -1) if
+ the type is prepared for toasting and what the default strategy
+ for attributes of this type should be.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">p</code> (plain): Values must always be stored plain
+ (non-varlena types always use this value).
+ </p></li><li class="listitem"><p>
+ <code class="literal">e</code> (external): Values can be stored in a
+ secondary <span class="quote">“<span class="quote">TOAST</span>”</span> relation (if relation has one, see
+ <code class="literal">pg_class.reltoastrelid</code>).
+ </p></li><li class="listitem"><p>
+ <code class="literal">m</code> (main): Values can be compressed and stored
+ inline.
+ </p></li><li class="listitem"><p>
+ <code class="literal">x</code> (extended): Values can be compressed and/or
+ moved to a secondary relation.
+ </p></li></ul></div><p>
+ <code class="literal">x</code> is the usual choice for toast-able types.
+ Note that <code class="literal">m</code> values can also be moved out to
+ secondary storage, but only as a last resort (<code class="literal">e</code>
+ and <code class="literal">x</code> values are moved first).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typnotnull</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="structfield">typnotnull</code> represents a not-null
+ constraint on a type. Used for domains only.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typbasetype</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ If this is a domain (see <code class="structfield">typtype</code>), then
+ <code class="structfield">typbasetype</code> identifies the type that this
+ one is based on. Zero if this type is not a domain.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typtypmod</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Domains use <code class="structfield">typtypmod</code> to record the <code class="literal">typmod</code>
+ to be applied to their base type (-1 if base type does not use a
+ <code class="literal">typmod</code>). -1 if this type is not a domain.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typndims</code> <code class="type">int4</code>
+ </p>
+ <p>
+ <code class="structfield">typndims</code> is the number of array dimensions
+ for a domain over an array (that is, <code class="structfield">typbasetype</code> is
+ an array type).
+ Zero for types other than domains over array types.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typcollation</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ <code class="structfield">typcollation</code> specifies the collation
+ of the type. If the type does not support collations, this will
+ be zero. A base type that supports collations will have a nonzero
+ value here, typically <code class="symbol">DEFAULT_COLLATION_OID</code>.
+ A domain over a collatable type can have a collation OID different
+ from its base type's, if one was specified for the domain.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typdefaultbin</code> <code class="type">pg_node_tree</code>
+ </p>
+ <p>
+ If <code class="structfield">typdefaultbin</code> is not null, it is the
+ <code class="function">nodeToString()</code>
+ representation of a default expression for the type. This is
+ only used for domains.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typdefault</code> <code class="type">text</code>
+ </p>
+ <p>
+ <code class="structfield">typdefault</code> is null if the type has no associated
+ default value. If <code class="structfield">typdefaultbin</code> is not null,
+ <code class="structfield">typdefault</code> must contain a human-readable version of the
+ default expression represented by <code class="structfield">typdefaultbin</code>. If
+ <code class="structfield">typdefaultbin</code> is null and <code class="structfield">typdefault</code> is
+ not, then <code class="structfield">typdefault</code> is the external representation of
+ the type's default value, which can be fed to the type's input
+ converter to produce a constant.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">typacl</code> <code class="type">aclitem[]</code>
+ </p>
+ <p>
+ Access privileges; see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for details
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ For fixed-width types used in system tables, it is critical that the size
+ and alignment defined in <code class="structname">pg_type</code>
+ agree with the way that the compiler will lay out the column in
+ a structure representing a table row.
+ </p></div><p>
+ <a class="xref" href="catalog-pg-type.html#CATALOG-TYPCATEGORY-TABLE" title="Table 53.65. typcategory Codes">Table 53.65</a> lists the system-defined values
+ of <code class="structfield">typcategory</code>. Any future additions to this list will
+ also be upper-case ASCII letters. All other ASCII characters are reserved
+ for user-defined categories.
+ </p><div class="table" id="CATALOG-TYPCATEGORY-TABLE"><p class="title"><strong>Table 53.65. <code class="structfield">typcategory</code> Codes</strong></p><div class="table-contents"><table class="table" summary="typcategory Codes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Code</th><th>Category</th></tr></thead><tbody><tr><td><code class="literal">A</code></td><td>Array types</td></tr><tr><td><code class="literal">B</code></td><td>Boolean types</td></tr><tr><td><code class="literal">C</code></td><td>Composite types</td></tr><tr><td><code class="literal">D</code></td><td>Date/time types</td></tr><tr><td><code class="literal">E</code></td><td>Enum types</td></tr><tr><td><code class="literal">G</code></td><td>Geometric types</td></tr><tr><td><code class="literal">I</code></td><td>Network address types</td></tr><tr><td><code class="literal">N</code></td><td>Numeric types</td></tr><tr><td><code class="literal">P</code></td><td>Pseudo-types</td></tr><tr><td><code class="literal">R</code></td><td>Range types</td></tr><tr><td><code class="literal">S</code></td><td>String types</td></tr><tr><td><code class="literal">T</code></td><td>Timespan types</td></tr><tr><td><code class="literal">U</code></td><td>User-defined types</td></tr><tr><td><code class="literal">V</code></td><td>Bit-string types</td></tr><tr><td><code class="literal">X</code></td><td><code class="type">unknown</code> type</td></tr><tr><td><code class="literal">Z</code></td><td>Internal-use types</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.63. <code class="structname">pg_ts_template</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.65. <code class="structname">pg_user_mapping</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalog-pg-user-mapping.html b/doc/src/sgml/html/catalog-pg-user-mapping.html
new file mode 100644
index 0000000..dd350c5
--- /dev/null
+++ b/doc/src/sgml/html/catalog-pg-user-mapping.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.65. pg_user_mapping</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-type.html" title="53.64. pg_type" /><link rel="next" href="views.html" title="Chapter 54. System Views" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.65. <code class="structname">pg_user_mapping</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-type.html" title="53.64. pg_type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="views.html" title="Chapter 54. System Views">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOG-PG-USER-MAPPING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.65. <code class="structname">pg_user_mapping</code></h2></div></div></div><a id="id-1.10.4.67.2" class="indexterm"></a><p>
+ The catalog <code class="structname">pg_user_mapping</code> stores
+ the mappings from local user to remote. Access to this catalog is
+ restricted from normal users, use the view
+ <a class="link" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings"><code class="structname">pg_user_mappings</code></a>
+ instead.
+ </p><div class="table" id="id-1.10.4.67.4"><p class="title"><strong>Table 53.66. <code class="structname">pg_user_mapping</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_user_mapping Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ Row identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umuser</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the local role being mapped, or zero if the user mapping is public
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umserver</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server"><code class="structname">pg_foreign_server</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the foreign server that contains this mapping
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ User mapping specific options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-type.html" title="53.64. pg_type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="views.html" title="Chapter 54. System Views">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.64. <code class="structname">pg_type</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 54. System Views</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalogs-overview.html b/doc/src/sgml/html/catalogs-overview.html
new file mode 100644
index 0000000..0d7ad11
--- /dev/null
+++ b/doc/src/sgml/html/catalogs-overview.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>53.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalogs.html" title="Chapter 53. System Catalogs" /><link rel="next" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">53.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalogs.html" title="Chapter 53. System Catalogs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><th width="60%" align="center">Chapter 53. System Catalogs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate">Next</a></td></tr></table><hr /></div><div class="sect1" id="CATALOGS-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">53.1. Overview</h2></div></div></div><p>
+ <a class="xref" href="catalogs-overview.html#CATALOG-TABLE" title="Table 53.1. System Catalogs">Table 53.1</a> lists the system catalogs.
+ More detailed documentation of each catalog follows below.
+ </p><p>
+ Most system catalogs are copied from the template database during
+ database creation and are thereafter database-specific. A few
+ catalogs are physically shared across all databases in a cluster;
+ these are noted in the descriptions of the individual catalogs.
+ </p><div class="table" id="CATALOG-TABLE"><p class="title"><strong>Table 53.1. System Catalogs</strong></p><div class="table-contents"><table class="table" summary="System Catalogs" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Catalog Name</th><th>Purpose</th></tr></thead><tbody><tr><td><a class="link" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate"><code class="structname">pg_aggregate</code></a></td><td>aggregate functions</td></tr><tr><td><a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a></td><td>relation access methods</td></tr><tr><td><a class="link" href="catalog-pg-amop.html" title="53.4. pg_amop"><code class="structname">pg_amop</code></a></td><td>access method operators</td></tr><tr><td><a class="link" href="catalog-pg-amproc.html" title="53.5. pg_amproc"><code class="structname">pg_amproc</code></a></td><td>access method support functions</td></tr><tr><td><a class="link" href="catalog-pg-attrdef.html" title="53.6. pg_attrdef"><code class="structname">pg_attrdef</code></a></td><td>column default values</td></tr><tr><td><a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a></td><td>table columns (<span class="quote">“<span class="quote">attributes</span>”</span>)</td></tr><tr><td><a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a></td><td>authorization identifiers (roles)</td></tr><tr><td><a class="link" href="catalog-pg-auth-members.html" title="53.9. pg_auth_members"><code class="structname">pg_auth_members</code></a></td><td>authorization identifier membership relationships</td></tr><tr><td><a class="link" href="catalog-pg-cast.html" title="53.10. pg_cast"><code class="structname">pg_cast</code></a></td><td>casts (data type conversions)</td></tr><tr><td><a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a></td><td>tables, indexes, sequences, views (<span class="quote">“<span class="quote">relations</span>”</span>)</td></tr><tr><td><a class="link" href="catalog-pg-collation.html" title="53.12. pg_collation"><code class="structname">pg_collation</code></a></td><td>collations (locale information)</td></tr><tr><td><a class="link" href="catalog-pg-constraint.html" title="53.13. pg_constraint"><code class="structname">pg_constraint</code></a></td><td>check constraints, unique constraints, primary key constraints, foreign key constraints</td></tr><tr><td><a class="link" href="catalog-pg-conversion.html" title="53.14. pg_conversion"><code class="structname">pg_conversion</code></a></td><td>encoding conversion information</td></tr><tr><td><a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a></td><td>databases within this database cluster</td></tr><tr><td><a class="link" href="catalog-pg-db-role-setting.html" title="53.16. pg_db_role_setting"><code class="structname">pg_db_role_setting</code></a></td><td>per-role and per-database settings</td></tr><tr><td><a class="link" href="catalog-pg-default-acl.html" title="53.17. pg_default_acl"><code class="structname">pg_default_acl</code></a></td><td>default privileges for object types</td></tr><tr><td><a class="link" href="catalog-pg-depend.html" title="53.18. pg_depend"><code class="structname">pg_depend</code></a></td><td>dependencies between database objects</td></tr><tr><td><a class="link" href="catalog-pg-description.html" title="53.19. pg_description"><code class="structname">pg_description</code></a></td><td>descriptions or comments on database objects</td></tr><tr><td><a class="link" href="catalog-pg-enum.html" title="53.20. pg_enum"><code class="structname">pg_enum</code></a></td><td>enum label and value definitions</td></tr><tr><td><a class="link" href="catalog-pg-event-trigger.html" title="53.21. pg_event_trigger"><code class="structname">pg_event_trigger</code></a></td><td>event triggers</td></tr><tr><td><a class="link" href="catalog-pg-extension.html" title="53.22. pg_extension"><code class="structname">pg_extension</code></a></td><td>installed extensions</td></tr><tr><td><a class="link" href="catalog-pg-foreign-data-wrapper.html" title="53.23. pg_foreign_data_wrapper"><code class="structname">pg_foreign_data_wrapper</code></a></td><td>foreign-data wrapper definitions</td></tr><tr><td><a class="link" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server"><code class="structname">pg_foreign_server</code></a></td><td>foreign server definitions</td></tr><tr><td><a class="link" href="catalog-pg-foreign-table.html" title="53.25. pg_foreign_table"><code class="structname">pg_foreign_table</code></a></td><td>additional foreign table information</td></tr><tr><td><a class="link" href="catalog-pg-index.html" title="53.26. pg_index"><code class="structname">pg_index</code></a></td><td>additional index information</td></tr><tr><td><a class="link" href="catalog-pg-inherits.html" title="53.27. pg_inherits"><code class="structname">pg_inherits</code></a></td><td>table inheritance hierarchy</td></tr><tr><td><a class="link" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs"><code class="structname">pg_init_privs</code></a></td><td>object initial privileges</td></tr><tr><td><a class="link" href="catalog-pg-language.html" title="53.29. pg_language"><code class="structname">pg_language</code></a></td><td>languages for writing functions</td></tr><tr><td><a class="link" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject"><code class="structname">pg_largeobject</code></a></td><td>data pages for large objects</td></tr><tr><td><a class="link" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata"><code class="structname">pg_largeobject_metadata</code></a></td><td>metadata for large objects</td></tr><tr><td><a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a></td><td>schemas</td></tr><tr><td><a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a></td><td>access method operator classes</td></tr><tr><td><a class="link" href="catalog-pg-operator.html" title="53.34. pg_operator"><code class="structname">pg_operator</code></a></td><td>operators</td></tr><tr><td><a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a></td><td>access method operator families</td></tr><tr><td><a class="link" href="catalog-pg-parameter-acl.html" title="53.36. pg_parameter_acl"><code class="structname">pg_parameter_acl</code></a></td><td>configuration parameters for which privileges have been granted</td></tr><tr><td><a class="link" href="catalog-pg-partitioned-table.html" title="53.37. pg_partitioned_table"><code class="structname">pg_partitioned_table</code></a></td><td>information about partition key of tables</td></tr><tr><td><a class="link" href="catalog-pg-policy.html" title="53.38. pg_policy"><code class="structname">pg_policy</code></a></td><td>row-security policies</td></tr><tr><td><a class="link" href="catalog-pg-proc.html" title="53.39. pg_proc"><code class="structname">pg_proc</code></a></td><td>functions and procedures</td></tr><tr><td><a class="link" href="catalog-pg-publication.html" title="53.40. pg_publication"><code class="structname">pg_publication</code></a></td><td>publications for logical replication</td></tr><tr><td><a class="link" href="catalog-pg-publication-namespace.html" title="53.41. pg_publication_namespace"><code class="structname">pg_publication_namespace</code></a></td><td>schema to publication mapping</td></tr><tr><td><a class="link" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel"><code class="structname">pg_publication_rel</code></a></td><td>relation to publication mapping</td></tr><tr><td><a class="link" href="catalog-pg-range.html" title="53.43. pg_range"><code class="structname">pg_range</code></a></td><td>information about range types</td></tr><tr><td><a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin"><code class="structname">pg_replication_origin</code></a></td><td>registered replication origins</td></tr><tr><td><a class="link" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite"><code class="structname">pg_rewrite</code></a></td><td>query rewrite rules</td></tr><tr><td><a class="link" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel"><code class="structname">pg_seclabel</code></a></td><td>security labels on database objects</td></tr><tr><td><a class="link" href="catalog-pg-sequence.html" title="53.47. pg_sequence"><code class="structname">pg_sequence</code></a></td><td>information about sequences</td></tr><tr><td><a class="link" href="catalog-pg-shdepend.html" title="53.48. pg_shdepend"><code class="structname">pg_shdepend</code></a></td><td>dependencies on shared objects</td></tr><tr><td><a class="link" href="catalog-pg-shdescription.html" title="53.49. pg_shdescription"><code class="structname">pg_shdescription</code></a></td><td>comments on shared objects</td></tr><tr><td><a class="link" href="catalog-pg-shseclabel.html" title="53.50. pg_shseclabel"><code class="structname">pg_shseclabel</code></a></td><td>security labels on shared database objects</td></tr><tr><td><a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a></td><td>planner statistics</td></tr><tr><td><a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a></td><td>extended planner statistics (definition)</td></tr><tr><td><a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a></td><td>extended planner statistics (built statistics)</td></tr><tr><td><a class="link" href="catalog-pg-subscription.html" title="53.54. pg_subscription"><code class="structname">pg_subscription</code></a></td><td>logical replication subscriptions</td></tr><tr><td><a class="link" href="catalog-pg-subscription-rel.html" title="53.55. pg_subscription_rel"><code class="structname">pg_subscription_rel</code></a></td><td>relation state for subscriptions</td></tr><tr><td><a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a></td><td>tablespaces within this database cluster</td></tr><tr><td><a class="link" href="catalog-pg-transform.html" title="53.57. pg_transform"><code class="structname">pg_transform</code></a></td><td>transforms (data type to procedural language conversions)</td></tr><tr><td><a class="link" href="catalog-pg-trigger.html" title="53.58. pg_trigger"><code class="structname">pg_trigger</code></a></td><td>triggers</td></tr><tr><td><a class="link" href="catalog-pg-ts-config.html" title="53.59. pg_ts_config"><code class="structname">pg_ts_config</code></a></td><td>text search configurations</td></tr><tr><td><a class="link" href="catalog-pg-ts-config-map.html" title="53.60. pg_ts_config_map"><code class="structname">pg_ts_config_map</code></a></td><td>text search configurations' token mappings</td></tr><tr><td><a class="link" href="catalog-pg-ts-dict.html" title="53.61. pg_ts_dict"><code class="structname">pg_ts_dict</code></a></td><td>text search dictionaries</td></tr><tr><td><a class="link" href="catalog-pg-ts-parser.html" title="53.62. pg_ts_parser"><code class="structname">pg_ts_parser</code></a></td><td>text search parsers</td></tr><tr><td><a class="link" href="catalog-pg-ts-template.html" title="53.63. pg_ts_template"><code class="structname">pg_ts_template</code></a></td><td>text search templates</td></tr><tr><td><a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a></td><td>data types</td></tr><tr><td><a class="link" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping"><code class="structname">pg_user_mapping</code></a></td><td>mappings of users to foreign servers</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalogs.html" title="Chapter 53. System Catalogs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="catalogs.html" title="Chapter 53. System Catalogs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalog-pg-aggregate.html" title="53.2. pg_aggregate">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 53. System Catalogs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.2. <code class="structname">pg_aggregate</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/catalogs.html b/doc/src/sgml/html/catalogs.html
new file mode 100644
index 0000000..ccdbaad
--- /dev/null
+++ b/doc/src/sgml/html/catalogs.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 53. System Catalogs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="executor.html" title="52.6. Executor" /><link rel="next" href="catalogs-overview.html" title="53.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 53. System Catalogs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="executor.html" title="52.6. Executor">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalogs-overview.html" title="53.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="CATALOGS"><div class="titlepage"><div><div><h2 class="title">Chapter 53. System Catalogs</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="catalogs-overview.html">53.1. Overview</a></span></dt><dt><span class="sect1"><a href="catalog-pg-aggregate.html">53.2. <code class="structname">pg_aggregate</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-am.html">53.3. <code class="structname">pg_am</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-amop.html">53.4. <code class="structname">pg_amop</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-amproc.html">53.5. <code class="structname">pg_amproc</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-attrdef.html">53.6. <code class="structname">pg_attrdef</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-attribute.html">53.7. <code class="structname">pg_attribute</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-authid.html">53.8. <code class="structname">pg_authid</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-auth-members.html">53.9. <code class="structname">pg_auth_members</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-cast.html">53.10. <code class="structname">pg_cast</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-class.html">53.11. <code class="structname">pg_class</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-collation.html">53.12. <code class="structname">pg_collation</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-constraint.html">53.13. <code class="structname">pg_constraint</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-conversion.html">53.14. <code class="structname">pg_conversion</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-database.html">53.15. <code class="structname">pg_database</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-db-role-setting.html">53.16. <code class="structname">pg_db_role_setting</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-default-acl.html">53.17. <code class="structname">pg_default_acl</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-depend.html">53.18. <code class="structname">pg_depend</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-description.html">53.19. <code class="structname">pg_description</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-enum.html">53.20. <code class="structname">pg_enum</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-event-trigger.html">53.21. <code class="structname">pg_event_trigger</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-extension.html">53.22. <code class="structname">pg_extension</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-data-wrapper.html">53.23. <code class="structname">pg_foreign_data_wrapper</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-server.html">53.24. <code class="structname">pg_foreign_server</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-table.html">53.25. <code class="structname">pg_foreign_table</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-index.html">53.26. <code class="structname">pg_index</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-inherits.html">53.27. <code class="structname">pg_inherits</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-init-privs.html">53.28. <code class="structname">pg_init_privs</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-language.html">53.29. <code class="structname">pg_language</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-largeobject.html">53.30. <code class="structname">pg_largeobject</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-largeobject-metadata.html">53.31. <code class="structname">pg_largeobject_metadata</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-namespace.html">53.32. <code class="structname">pg_namespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-opclass.html">53.33. <code class="structname">pg_opclass</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-operator.html">53.34. <code class="structname">pg_operator</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-opfamily.html">53.35. <code class="structname">pg_opfamily</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-parameter-acl.html">53.36. <code class="structname">pg_parameter_acl</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-partitioned-table.html">53.37. <code class="structname">pg_partitioned_table</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-policy.html">53.38. <code class="structname">pg_policy</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-proc.html">53.39. <code class="structname">pg_proc</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication.html">53.40. <code class="structname">pg_publication</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication-namespace.html">53.41. <code class="structname">pg_publication_namespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication-rel.html">53.42. <code class="structname">pg_publication_rel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-range.html">53.43. <code class="structname">pg_range</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-replication-origin.html">53.44. <code class="structname">pg_replication_origin</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-rewrite.html">53.45. <code class="structname">pg_rewrite</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-seclabel.html">53.46. <code class="structname">pg_seclabel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-sequence.html">53.47. <code class="structname">pg_sequence</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shdepend.html">53.48. <code class="structname">pg_shdepend</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shdescription.html">53.49. <code class="structname">pg_shdescription</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shseclabel.html">53.50. <code class="structname">pg_shseclabel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic.html">53.51. <code class="structname">pg_statistic</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic-ext.html">53.52. <code class="structname">pg_statistic_ext</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic-ext-data.html">53.53. <code class="structname">pg_statistic_ext_data</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-subscription.html">53.54. <code class="structname">pg_subscription</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-subscription-rel.html">53.55. <code class="structname">pg_subscription_rel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-tablespace.html">53.56. <code class="structname">pg_tablespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-transform.html">53.57. <code class="structname">pg_transform</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-trigger.html">53.58. <code class="structname">pg_trigger</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-config.html">53.59. <code class="structname">pg_ts_config</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-config-map.html">53.60. <code class="structname">pg_ts_config_map</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-dict.html">53.61. <code class="structname">pg_ts_dict</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-parser.html">53.62. <code class="structname">pg_ts_parser</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-template.html">53.63. <code class="structname">pg_ts_template</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-type.html">53.64. <code class="structname">pg_type</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-user-mapping.html">53.65. <code class="structname">pg_user_mapping</code></a></span></dt></dl></div><p>
+ The system catalogs are the place where a relational database
+ management system stores schema metadata, such as information about
+ tables and columns, and internal bookkeeping information.
+ <span class="productname">PostgreSQL</span>'s system catalogs are regular
+ tables. You can drop and recreate the tables, add columns, insert
+ and update values, and severely mess up your system that way.
+ Normally, one should not change the system catalogs by hand, there
+ are normally SQL commands to do that. (For example, <code class="command">CREATE
+ DATABASE</code> inserts a row into the
+ <code class="structname">pg_database</code> catalog — and actually
+ creates the database on disk.) There are some exceptions for
+ particularly esoteric operations, but many of those have been made
+ available as SQL commands over time, and so the need for direct manipulation
+ of the system catalogs is ever decreasing.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="executor.html" title="52.6. Executor">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalogs-overview.html" title="53.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.6. Executor </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 53.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/charset.html b/doc/src/sgml/html/charset.html
new file mode 100644
index 0000000..4808158
--- /dev/null
+++ b/doc/src/sgml/html/charset.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 24. Localization</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-tablespaces.html" title="23.6. Tablespaces" /><link rel="next" href="locale.html" title="24.1. Locale Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 24. Localization</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="locale.html" title="24.1. Locale Support">Next</a></td></tr></table><hr /></div><div class="chapter" id="CHARSET"><div class="titlepage"><div><div><h2 class="title">Chapter 24. Localization</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="locale.html">24.1. Locale Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.4">24.1.1. Overview</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.5">24.1.2. Behavior</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.6">24.1.3. Selecting Locales</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.7">24.1.4. Locale Providers</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.8">24.1.5. Problems</a></span></dt></dl></dd><dt><span class="sect1"><a href="collation.html">24.2. Collation Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="collation.html#id-1.6.11.4.4">24.2.1. Concepts</a></span></dt><dt><span class="sect2"><a href="collation.html#COLLATION-MANAGING">24.2.2. Managing Collations</a></span></dt></dl></dd><dt><span class="sect1"><a href="multibyte.html">24.3. Character Set Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED">24.3.1. Supported Character Sets</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.6">24.3.2. Setting the Character Set</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.7">24.3.3. Automatic Character Set Conversion Between Server and Client</a></span></dt><dt><span class="sect2"><a href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED">24.3.4. Available Character Set Conversions</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.9">24.3.5. Further Reading</a></span></dt></dl></dd></dl></div><p>
+ This chapter describes the available localization features from the
+ point of view of the administrator.
+ <span class="productname">PostgreSQL</span> supports two localization
+ facilities:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 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 <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> and
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>.
+ </p></li><li class="listitem"><p>
+ 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 <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="locale.html" title="24.1. Locale Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.6. Tablespaces </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 24.1. Locale Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/checksums.html b/doc/src/sgml/html/checksums.html
new file mode 100644
index 0000000..8d2e9d5
--- /dev/null
+++ b/doc/src/sgml/html/checksums.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.2. Data Checksums</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-reliability.html" title="30.1. Reliability" /><link rel="next" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.2. Data Checksums</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-reliability.html" title="30.1. Reliability">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)">Next</a></td></tr></table><hr /></div><div class="sect1" id="CHECKSUMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.2. Data Checksums</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="checksums.html#CHECKSUMS-OFFLINE-ENABLE-DISABLE">30.2.1. Off-line Enabling of Checksums</a></span></dt></dl></div><a id="id-1.6.17.4.2" class="indexterm"></a><p>
+ By default, data pages are not protected by checksums, but this can
+ optionally be enabled for a cluster. When enabled, each data page includes
+ a checksum that is updated when the page is written and verified each time
+ the page is read. Only data pages are protected by checksums; internal data
+ structures and temporary files are not.
+ </p><p>
+ Checksums are normally enabled when the cluster is initialized using <a class="link" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS"><span class="application">initdb</span></a>.
+ They can also be enabled or disabled at a later time as an offline
+ operation. Data checksums are enabled or disabled at the full cluster
+ level, and cannot be specified individually for databases or tables.
+ </p><p>
+ The current state of checksums in the cluster can be verified by viewing the
+ value of the read-only configuration variable <a class="xref" href="runtime-config-preset.html#GUC-DATA-CHECKSUMS">data_checksums</a> by issuing the command <code class="command">SHOW
+ data_checksums</code>.
+ </p><p>
+ When attempting to recover from page corruptions, it may be necessary to
+ bypass the checksum protection. To do this, temporarily set the
+ configuration parameter <a class="xref" href="runtime-config-developer.html#GUC-IGNORE-CHECKSUM-FAILURE">ignore_checksum_failure</a>.
+ </p><div class="sect2" id="CHECKSUMS-OFFLINE-ENABLE-DISABLE"><div class="titlepage"><div><div><h3 class="title">30.2.1. Off-line Enabling of Checksums</h3></div></div></div><p>
+ The <a class="link" href="app-pgchecksums.html" title="pg_checksums"><span class="application">pg_checksums</span></a>
+ application can be used to enable or disable data checksums, as well as
+ verify checksums, on an offline cluster.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-reliability.html" title="30.1. Reliability">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.1. Reliability </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/citext.html b/doc/src/sgml/html/citext.html
new file mode 100644
index 0000000..f0dbd60
--- /dev/null
+++ b/doc/src/sgml/html/citext.html
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.10. citext</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-gist.html" title="F.9. btree_gist" /><link rel="next" href="cube.html" title="F.11. cube" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.10. citext</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-gist.html" title="F.9. btree_gist">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="cube.html" title="F.11. cube">Next</a></td></tr></table><hr /></div><div class="sect1" id="CITEXT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.10. citext</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.6">F.10.1. Rationale</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.7">F.10.2. How to Use It</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.8">F.10.3. String Comparison Behavior</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.9">F.10.4. Limitations</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.10">F.10.5. Author</a></span></dt></dl></div><a id="id-1.11.7.19.2" class="indexterm"></a><p>
+ The <code class="filename">citext</code> module provides a case-insensitive
+ character string type, <code class="type">citext</code>. Essentially, it internally calls
+ <code class="function">lower</code> when comparing values. Otherwise, it behaves almost
+ exactly like <code class="type">text</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Consider using <em class="firstterm">nondeterministic collations</em> (see
+ <a class="xref" href="collation.html#COLLATION-NONDETERMINISTIC" title="24.2.2.4. Nondeterministic Collations">Section 24.2.2.4</a>) instead of this module. They
+ can be used for case-insensitive comparisons, accent-insensitive
+ comparisons, and other combinations, and they handle more Unicode special
+ cases correctly.
+ </p></div><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.19.6"><div class="titlepage"><div><div><h3 class="title">F.10.1. Rationale</h3></div></div></div><p>
+ The standard approach to doing case-insensitive matches
+ in <span class="productname">PostgreSQL</span> has been to use the <code class="function">lower</code>
+ function when comparing values, for example
+
+</p><pre class="programlisting">
+SELECT * FROM tab WHERE lower(col) = LOWER(?);
+</pre><p>
+ </p><p>
+ This works reasonably well, but has a number of drawbacks:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ It makes your SQL statements verbose, and you always have to remember to
+ use <code class="function">lower</code> on both the column and the query value.
+ </p></li><li class="listitem"><p>
+ It won't use an index, unless you create a functional index using
+ <code class="function">lower</code>.
+ </p></li><li class="listitem"><p>
+ If you declare a column as <code class="literal">UNIQUE</code> or <code class="literal">PRIMARY
+ KEY</code>, the implicitly generated index is case-sensitive. So it's
+ useless for case-insensitive searches, and it won't enforce
+ uniqueness case-insensitively.
+ </p></li></ul></div><p>
+ The <code class="type">citext</code> data type allows you to eliminate calls
+ to <code class="function">lower</code> in SQL queries, and allows a primary key to
+ be case-insensitive. <code class="type">citext</code> is locale-aware, just
+ like <code class="type">text</code>, which means that the matching of upper case and
+ lower case characters is dependent on the rules of
+ the database's <code class="literal">LC_CTYPE</code> setting. Again, this behavior is
+ identical to the use of <code class="function">lower</code> in queries. But because it's
+ done transparently by the data type, you don't have to remember to do
+ anything special in your queries.
+ </p></div><div class="sect2" id="id-1.11.7.19.7"><div class="titlepage"><div><div><h3 class="title">F.10.2. How to Use It</h3></div></div></div><p>
+ Here's a simple example of usage:
+
+</p><pre class="programlisting">
+CREATE TABLE users (
+ nick CITEXT PRIMARY KEY,
+ pass TEXT NOT NULL
+);
+
+INSERT INTO users VALUES ( 'larry', sha256(random()::text::bytea) );
+INSERT INTO users VALUES ( 'Tom', sha256(random()::text::bytea) );
+INSERT INTO users VALUES ( 'Damian', sha256(random()::text::bytea) );
+INSERT INTO users VALUES ( 'NEAL', sha256(random()::text::bytea) );
+INSERT INTO users VALUES ( 'Bjørn', sha256(random()::text::bytea) );
+
+SELECT * FROM users WHERE nick = 'Larry';
+</pre><p>
+
+ The <code class="command">SELECT</code> statement will return one tuple, even though
+ the <code class="structfield">nick</code> column was set to <code class="literal">larry</code> and the query
+ was for <code class="literal">Larry</code>.
+ </p></div><div class="sect2" id="id-1.11.7.19.8"><div class="titlepage"><div><div><h3 class="title">F.10.3. String Comparison Behavior</h3></div></div></div><p>
+ <code class="type">citext</code> performs comparisons by converting each string to lower
+ case (as though <code class="function">lower</code> were called) and then comparing the
+ results normally. Thus, for example, two strings are considered equal
+ if <code class="function">lower</code> would produce identical results for them.
+ </p><p>
+ In order to emulate a case-insensitive collation as closely as possible,
+ there are <code class="type">citext</code>-specific versions of a number of string-processing
+ operators and functions. So, for example, the regular expression
+ operators <code class="literal">~</code> and <code class="literal">~*</code> exhibit the same behavior when
+ applied to <code class="type">citext</code>: they both match case-insensitively.
+ The same is true
+ for <code class="literal">!~</code> and <code class="literal">!~*</code>, as well as for the
+ <code class="literal">LIKE</code> operators <code class="literal">~~</code> and <code class="literal">~~*</code>, and
+ <code class="literal">!~~</code> and <code class="literal">!~~*</code>. If you'd like to match
+ case-sensitively, you can cast the operator's arguments to <code class="type">text</code>.
+ </p><p>
+ Similarly, all of the following functions perform matching
+ case-insensitively if their arguments are <code class="type">citext</code>:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="function">regexp_match()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">regexp_matches()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">regexp_replace()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">regexp_split_to_array()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">regexp_split_to_table()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">replace()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">split_part()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">strpos()</code>
+ </p></li><li class="listitem"><p>
+ <code class="function">translate()</code>
+ </p></li></ul></div><p>
+ For the regexp functions, if you want to match case-sensitively, you can
+ specify the <span class="quote">“<span class="quote">c</span>”</span> flag to force a case-sensitive match. Otherwise,
+ you must cast to <code class="type">text</code> before using one of these functions if
+ you want case-sensitive behavior.
+ </p></div><div class="sect2" id="id-1.11.7.19.9"><div class="titlepage"><div><div><h3 class="title">F.10.4. Limitations</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="type">citext</code>'s case-folding behavior depends on
+ the <code class="literal">LC_CTYPE</code> setting of your database. How it compares
+ values is therefore determined when the database is created.
+ It is not truly
+ case-insensitive in the terms defined by the Unicode standard.
+ Effectively, what this means is that, as long as you're happy with your
+ collation, you should be happy with <code class="type">citext</code>'s comparisons. But
+ if you have data in different languages stored in your database, users
+ of one language may find their query results are not as expected if the
+ collation is for another language.
+ </p></li><li class="listitem"><p>
+ As of <span class="productname">PostgreSQL</span> 9.1, you can attach a
+ <code class="literal">COLLATE</code> specification to <code class="type">citext</code> columns or data
+ values. Currently, <code class="type">citext</code> operators will honor a non-default
+ <code class="literal">COLLATE</code> specification while comparing case-folded strings,
+ but the initial folding to lower case is always done according to the
+ database's <code class="literal">LC_CTYPE</code> setting (that is, as though
+ <code class="literal">COLLATE "default"</code> were given). This may be changed in a
+ future release so that both steps follow the input <code class="literal">COLLATE</code>
+ specification.
+ </p></li><li class="listitem"><p>
+ <code class="type">citext</code> is not as efficient as <code class="type">text</code> because the
+ operator functions and the B-tree comparison functions must make copies
+ of the data and convert it to lower case for comparisons. Also, only
+ <code class="type">text</code> can support B-Tree deduplication. However,
+ <code class="type">citext</code> is slightly more efficient than using
+ <code class="function">lower</code> to get case-insensitive matching.
+ </p></li><li class="listitem"><p>
+ <code class="type">citext</code> doesn't help much if you need data to compare
+ case-sensitively in some contexts and case-insensitively in other
+ contexts. The standard answer is to use the <code class="type">text</code> type and
+ manually use the <code class="function">lower</code> function when you need to compare
+ case-insensitively; this works all right if case-insensitive comparison
+ is needed only infrequently. If you need case-insensitive behavior most
+ of the time and case-sensitive infrequently, consider storing the data
+ as <code class="type">citext</code> and explicitly casting the column to <code class="type">text</code>
+ when you want case-sensitive comparison. In either situation, you will
+ need two indexes if you want both types of searches to be fast.
+ </p></li><li class="listitem"><p>
+ The schema containing the <code class="type">citext</code> operators must be
+ in the current <code class="varname">search_path</code> (typically <code class="literal">public</code>);
+ if it is not, the normal case-sensitive <code class="type">text</code> operators
+ will be invoked instead.
+ </p></li><li class="listitem"><p>
+ The approach of lower-casing strings for comparison does not handle some
+ Unicode special cases correctly, for example when one upper-case letter
+ has two lower-case letter equivalents. Unicode distinguishes between
+ <em class="firstterm">case mapping</em> and <em class="firstterm">case
+ folding</em> for this reason. Use nondeterministic collations
+ instead of <code class="type">citext</code> to handle that correctly.
+ </p></li></ul></div></div><div class="sect2" id="id-1.11.7.19.10"><div class="titlepage"><div><div><h3 class="title">F.10.5. Author</h3></div></div></div><p>
+ David E. Wheeler <code class="email">&lt;<a class="email" href="mailto:david@kineticode.com">david@kineticode.com</a>&gt;</code>
+ </p><p>
+ Inspired by the original <code class="type">citext</code> module by Donald Fraser.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-gist.html" title="F.9. btree_gist">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="cube.html" title="F.11. cube">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.9. btree_gist </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.11. cube</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/client-authentication-problems.html b/doc/src/sgml/html/client-authentication-problems.html
new file mode 100644
index 0000000..2157438
--- /dev/null
+++ b/doc/src/sgml/html/client-authentication-problems.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.15. Authentication Problems</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-bsd.html" title="21.14. BSD Authentication" /><link rel="next" href="user-manag.html" title="Chapter 22. Database Roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.15. Authentication Problems</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-bsd.html" title="21.14. BSD Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="user-manag.html" title="Chapter 22. Database Roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="CLIENT-AUTHENTICATION-PROBLEMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.15. Authentication Problems</h2></div></div></div><p>
+ Authentication failures and related problems generally
+ manifest themselves through error messages like the following:
+ </p><p>
+</p><pre class="programlisting">
+FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb"
+</pre><p>
+ This is what you are most likely to get if you succeed in contacting
+ the server, but it does not want to talk to you. As the message
+ suggests, the server refused the connection request because it found
+ no matching entry in its <code class="filename">pg_hba.conf</code>
+ configuration file.
+ </p><p>
+</p><pre class="programlisting">
+FATAL: password authentication failed for user "andym"
+</pre><p>
+ Messages like this indicate that you contacted the server, and it is
+ willing to talk to you, but not until you pass the authorization
+ method specified in the <code class="filename">pg_hba.conf</code> file. Check
+ the password you are providing, or check your Kerberos or ident
+ software if the complaint mentions one of those authentication
+ types.
+ </p><p>
+</p><pre class="programlisting">
+FATAL: user "andym" does not exist
+</pre><p>
+ The indicated database user name was not found.
+ </p><p>
+</p><pre class="programlisting">
+FATAL: database "testdb" does not exist
+</pre><p>
+ The database you are trying to connect to does not exist. Note that
+ if you do not specify a database name, it defaults to the database
+ user name, which might or might not be the right thing.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The server log might contain more information about an
+ authentication failure than is reported to the client. If you are
+ confused about the reason for a failure, check the server log.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-bsd.html" title="21.14. BSD Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="user-manag.html" title="Chapter 22. Database Roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.14. BSD Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 22. Database Roles</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/client-authentication.html b/doc/src/sgml/html/client-authentication.html
new file mode 100644
index 0000000..2e7fe0f
--- /dev/null
+++ b/doc/src/sgml/html/client-authentication.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 21. Client Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-short.html" title="20.18. Short Options" /><link rel="next" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 21. Client Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-short.html" title="20.18. Short Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Next</a></td></tr></table><hr /></div><div class="chapter" id="CLIENT-AUTHENTICATION"><div class="titlepage"><div><div><h2 class="title">Chapter 21. Client Authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="auth-pg-hba-conf.html">21.1. The <code class="filename">pg_hba.conf</code> File</a></span></dt><dt><span class="sect1"><a href="auth-username-maps.html">21.2. User Name Maps</a></span></dt><dt><span class="sect1"><a href="auth-methods.html">21.3. Authentication Methods</a></span></dt><dt><span class="sect1"><a href="auth-trust.html">21.4. Trust Authentication</a></span></dt><dt><span class="sect1"><a href="auth-password.html">21.5. Password Authentication</a></span></dt><dt><span class="sect1"><a href="gssapi-auth.html">21.6. GSSAPI Authentication</a></span></dt><dt><span class="sect1"><a href="sspi-auth.html">21.7. SSPI Authentication</a></span></dt><dt><span class="sect1"><a href="auth-ident.html">21.8. Ident Authentication</a></span></dt><dt><span class="sect1"><a href="auth-peer.html">21.9. Peer Authentication</a></span></dt><dt><span class="sect1"><a href="auth-ldap.html">21.10. LDAP Authentication</a></span></dt><dt><span class="sect1"><a href="auth-radius.html">21.11. RADIUS Authentication</a></span></dt><dt><span class="sect1"><a href="auth-cert.html">21.12. Certificate Authentication</a></span></dt><dt><span class="sect1"><a href="auth-pam.html">21.13. PAM Authentication</a></span></dt><dt><span class="sect1"><a href="auth-bsd.html">21.14. BSD Authentication</a></span></dt><dt><span class="sect1"><a href="client-authentication-problems.html">21.15. Authentication Problems</a></span></dt></dl></div><a id="id-1.6.8.2" class="indexterm"></a><p>
+ When a client application connects to the database server, it
+ specifies which <span class="productname">PostgreSQL</span> database user name it
+ 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
+ <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a> for more information. Therefore, it is
+ essential to restrict which database users can connect.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ As explained in <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a>,
+ <span class="productname">PostgreSQL</span> actually does privilege
+ management in terms of <span class="quote">“<span class="quote">roles</span>”</span>. In this chapter, we
+ consistently use <em class="firstterm">database user</em> to mean <span class="quote">“<span class="quote">role with the
+ <code class="literal">LOGIN</code> privilege</span>”</span>.
+ </p></div><p>
+ <em class="firstterm">Authentication</em> is the process by which the
+ database server establishes the identity of the client, and by
+ extension determines whether the client application (or the user
+ who runs the client application) is permitted to connect with the
+ database user name that was requested.
+ </p><p>
+ <span class="productname">PostgreSQL</span> offers a number of different
+ client authentication methods. The method used to authenticate a
+ particular client connection can be selected on the basis of
+ (client) host address, database, and user.
+ </p><p>
+ <span class="productname">PostgreSQL</span> database user names are logically
+ separate from user names of the operating system in which the server
+ runs. If all the users of a particular server also have accounts on
+ the server's machine, it makes sense to assign database user names
+ that match their operating system user names. However, a server that
+ accepts remote connections might have many database users who have no local
+ operating system
+ account, and in such cases there need be no connection between
+ database user names and OS user names.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-short.html" title="20.18. Short Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.18. Short Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.1. The <code class="filename">pg_hba.conf</code> File</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/client-interfaces.html b/doc/src/sgml/html/client-interfaces.html
new file mode 100644
index 0000000..9cbb83c
--- /dev/null
+++ b/doc/src/sgml/html/client-interfaces.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part IV. Client Interfaces</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress-coverage.html" title="33.5. Test Coverage Examination" /><link rel="next" href="libpq.html" title="Chapter 34. libpq — C Library" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part IV. Client Interfaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress-coverage.html" title="33.5. Test Coverage Examination">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq.html" title="Chapter 34. libpq — C Library">Next</a></td></tr></table><hr /></div><div class="part" id="CLIENT-INTERFACES"><div class="titlepage"><div><div><h1 class="title">Part IV. Client Interfaces</h1></div></div></div><div class="partintro" id="id-1.7.2"><div></div><p>
+ This part describes the client programming interfaces distributed
+ with <span class="productname">PostgreSQL</span>. Each of these chapters can be
+ read independently. Note that there are many other programming
+ interfaces for client programs that are distributed separately and
+ contain their own documentation (<a class="xref" href="external-projects.html" title="Appendix H. External Projects">Appendix H</a>
+ lists some of the more popular ones). Readers of this part should be
+ familiar with using <acronym class="acronym">SQL</acronym> commands to manipulate
+ and query the database (see <a class="xref" href="sql.html" title="Part II. The SQL Language">Part II</a>) and of course
+ with the programming language that the interface uses.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="libpq.html">34. <span class="application">libpq</span> — C Library</a></span></dt><dd><dl><dt><span class="sect1"><a href="libpq-connect.html">34.1. Database Connection Control Functions</a></span></dt><dt><span class="sect1"><a href="libpq-status.html">34.2. Connection Status Functions</a></span></dt><dt><span class="sect1"><a href="libpq-exec.html">34.3. Command Execution Functions</a></span></dt><dt><span class="sect1"><a href="libpq-async.html">34.4. Asynchronous Command Processing</a></span></dt><dt><span class="sect1"><a href="libpq-pipeline-mode.html">34.5. Pipeline Mode</a></span></dt><dt><span class="sect1"><a href="libpq-single-row-mode.html">34.6. Retrieving Query Results Row-by-Row</a></span></dt><dt><span class="sect1"><a href="libpq-cancel.html">34.7. Canceling Queries in Progress</a></span></dt><dt><span class="sect1"><a href="libpq-fastpath.html">34.8. The Fast-Path Interface</a></span></dt><dt><span class="sect1"><a href="libpq-notify.html">34.9. Asynchronous Notification</a></span></dt><dt><span class="sect1"><a href="libpq-copy.html">34.10. Functions Associated with the <code class="command">COPY</code> Command</a></span></dt><dt><span class="sect1"><a href="libpq-control.html">34.11. Control Functions</a></span></dt><dt><span class="sect1"><a href="libpq-misc.html">34.12. Miscellaneous Functions</a></span></dt><dt><span class="sect1"><a href="libpq-notice-processing.html">34.13. Notice Processing</a></span></dt><dt><span class="sect1"><a href="libpq-events.html">34.14. Event System</a></span></dt><dt><span class="sect1"><a href="libpq-envars.html">34.15. Environment Variables</a></span></dt><dt><span class="sect1"><a href="libpq-pgpass.html">34.16. The Password File</a></span></dt><dt><span class="sect1"><a href="libpq-pgservice.html">34.17. The Connection Service File</a></span></dt><dt><span class="sect1"><a href="libpq-ldap.html">34.18. LDAP Lookup of Connection Parameters</a></span></dt><dt><span class="sect1"><a href="libpq-ssl.html">34.19. SSL Support</a></span></dt><dt><span class="sect1"><a href="libpq-threading.html">34.20. Behavior in Threaded Programs</a></span></dt><dt><span class="sect1"><a href="libpq-build.html">34.21. Building <span class="application">libpq</span> Programs</a></span></dt><dt><span class="sect1"><a href="libpq-example.html">34.22. Example Programs</a></span></dt></dl></dd><dt><span class="chapter"><a href="largeobjects.html">35. Large Objects</a></span></dt><dd><dl><dt><span class="sect1"><a href="lo-intro.html">35.1. Introduction</a></span></dt><dt><span class="sect1"><a href="lo-implementation.html">35.2. Implementation Features</a></span></dt><dt><span class="sect1"><a href="lo-interfaces.html">35.3. Client Interfaces</a></span></dt><dt><span class="sect1"><a href="lo-funcs.html">35.4. Server-Side Functions</a></span></dt><dt><span class="sect1"><a href="lo-examplesect.html">35.5. Example Program</a></span></dt></dl></dd><dt><span class="chapter"><a href="ecpg.html">36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</a></span></dt><dd><dl><dt><span class="sect1"><a href="ecpg-concept.html">36.1. The Concept</a></span></dt><dt><span class="sect1"><a href="ecpg-connect.html">36.2. Managing Database Connections</a></span></dt><dt><span class="sect1"><a href="ecpg-commands.html">36.3. Running SQL Commands</a></span></dt><dt><span class="sect1"><a href="ecpg-variables.html">36.4. Using Host Variables</a></span></dt><dt><span class="sect1"><a href="ecpg-dynamic.html">36.5. Dynamic SQL</a></span></dt><dt><span class="sect1"><a href="ecpg-pgtypes.html">36.6. pgtypes Library</a></span></dt><dt><span class="sect1"><a href="ecpg-descriptors.html">36.7. Using Descriptor Areas</a></span></dt><dt><span class="sect1"><a href="ecpg-errors.html">36.8. Error Handling</a></span></dt><dt><span class="sect1"><a href="ecpg-preproc.html">36.9. Preprocessor Directives</a></span></dt><dt><span class="sect1"><a href="ecpg-process.html">36.10. Processing Embedded SQL Programs</a></span></dt><dt><span class="sect1"><a href="ecpg-library.html">36.11. Library Functions</a></span></dt><dt><span class="sect1"><a href="ecpg-lo.html">36.12. Large Objects</a></span></dt><dt><span class="sect1"><a href="ecpg-cpp.html">36.13. <acronym class="acronym">C++</acronym> Applications</a></span></dt><dt><span class="sect1"><a href="ecpg-sql-commands.html">36.14. Embedded SQL Commands</a></span></dt><dt><span class="sect1"><a href="ecpg-informix-compat.html">36.15. <span class="productname">Informix</span> Compatibility Mode</a></span></dt><dt><span class="sect1"><a href="ecpg-oracle-compat.html">36.16. <span class="productname">Oracle</span> Compatibility Mode</a></span></dt><dt><span class="sect1"><a href="ecpg-develop.html">36.17. Internals</a></span></dt></dl></dd><dt><span class="chapter"><a href="information-schema.html">37. The Information Schema</a></span></dt><dd><dl><dt><span class="sect1"><a href="infoschema-schema.html">37.1. The Schema</a></span></dt><dt><span class="sect1"><a href="infoschema-datatypes.html">37.2. Data Types</a></span></dt><dt><span class="sect1"><a href="infoschema-information-schema-catalog-name.html">37.3. <code class="literal">information_schema_catalog_name</code></a></span></dt><dt><span class="sect1"><a href="infoschema-administrable-role-authorizations.html">37.4. <code class="literal">administrable_role_​authorizations</code></a></span></dt><dt><span class="sect1"><a href="infoschema-applicable-roles.html">37.5. <code class="literal">applicable_roles</code></a></span></dt><dt><span class="sect1"><a href="infoschema-attributes.html">37.6. <code class="literal">attributes</code></a></span></dt><dt><span class="sect1"><a href="infoschema-character-sets.html">37.7. <code class="literal">character_sets</code></a></span></dt><dt><span class="sect1"><a href="infoschema-check-constraint-routine-usage.html">37.8. <code class="literal">check_constraint_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-check-constraints.html">37.9. <code class="literal">check_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-collations.html">37.10. <code class="literal">collations</code></a></span></dt><dt><span class="sect1"><a href="infoschema-collation-character-set-applicab.html">37.11. <code class="literal">collation_character_set_​applicability</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-column-usage.html">37.12. <code class="literal">column_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-domain-usage.html">37.13. <code class="literal">column_domain_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-options.html">37.14. <code class="literal">column_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-privileges.html">37.15. <code class="literal">column_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-udt-usage.html">37.16. <code class="literal">column_udt_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-columns.html">37.17. <code class="literal">columns</code></a></span></dt><dt><span class="sect1"><a href="infoschema-constraint-column-usage.html">37.18. <code class="literal">constraint_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-constraint-table-usage.html">37.19. <code class="literal">constraint_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-data-type-privileges.html">37.20. <code class="literal">data_type_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domain-constraints.html">37.21. <code class="literal">domain_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domain-udt-usage.html">37.22. <code class="literal">domain_udt_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domains.html">37.23. <code class="literal">domains</code></a></span></dt><dt><span class="sect1"><a href="infoschema-element-types.html">37.24. <code class="literal">element_types</code></a></span></dt><dt><span class="sect1"><a href="infoschema-enabled-roles.html">37.25. <code class="literal">enabled_roles</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-data-wrapper-options.html">37.26. <code class="literal">foreign_data_wrapper_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-data-wrappers.html">37.27. <code class="literal">foreign_data_wrappers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-server-options.html">37.28. <code class="literal">foreign_server_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-servers.html">37.29. <code class="literal">foreign_servers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-table-options.html">37.30. <code class="literal">foreign_table_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-tables.html">37.31. <code class="literal">foreign_tables</code></a></span></dt><dt><span class="sect1"><a href="infoschema-key-column-usage.html">37.32. <code class="literal">key_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-parameters.html">37.33. <code class="literal">parameters</code></a></span></dt><dt><span class="sect1"><a href="infoschema-referential-constraints.html">37.34. <code class="literal">referential_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-column-grants.html">37.35. <code class="literal">role_column_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-routine-grants.html">37.36. <code class="literal">role_routine_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-table-grants.html">37.37. <code class="literal">role_table_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-udt-grants.html">37.38. <code class="literal">role_udt_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-usage-grants.html">37.39. <code class="literal">role_usage_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-column-usage.html">37.40. <code class="literal">routine_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-privileges.html">37.41. <code class="literal">routine_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-routine-usage.html">37.42. <code class="literal">routine_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-sequence-usage.html">37.43. <code class="literal">routine_sequence_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-table-usage.html">37.44. <code class="literal">routine_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routines.html">37.45. <code class="literal">routines</code></a></span></dt><dt><span class="sect1"><a href="infoschema-schemata.html">37.46. <code class="literal">schemata</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sequences.html">37.47. <code class="literal">sequences</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-features.html">37.48. <code class="literal">sql_features</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-implementation-info.html">37.49. <code class="literal">sql_implementation_info</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-parts.html">37.50. <code class="literal">sql_parts</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-sizing.html">37.51. <code class="literal">sql_sizing</code></a></span></dt><dt><span class="sect1"><a href="infoschema-table-constraints.html">37.52. <code class="literal">table_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-table-privileges.html">37.53. <code class="literal">table_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-tables.html">37.54. <code class="literal">tables</code></a></span></dt><dt><span class="sect1"><a href="infoschema-transforms.html">37.55. <code class="literal">transforms</code></a></span></dt><dt><span class="sect1"><a href="infoschema-triggered-update-columns.html">37.56. <code class="literal">triggered_update_columns</code></a></span></dt><dt><span class="sect1"><a href="infoschema-triggers.html">37.57. <code class="literal">triggers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-udt-privileges.html">37.58. <code class="literal">udt_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-usage-privileges.html">37.59. <code class="literal">usage_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-defined-types.html">37.60. <code class="literal">user_defined_types</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-mapping-options.html">37.61. <code class="literal">user_mapping_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-mappings.html">37.62. <code class="literal">user_mappings</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-column-usage.html">37.63. <code class="literal">view_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-routine-usage.html">37.64. <code class="literal">view_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-table-usage.html">37.65. <code class="literal">view_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-views.html">37.66. <code class="literal">views</code></a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress-coverage.html" title="33.5. Test Coverage Examination">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq.html" title="Chapter 34. libpq — C Library">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.5. Test Coverage Examination </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 34. <span class="application">libpq</span> — C Library</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/collation.html b/doc/src/sgml/html/collation.html
new file mode 100644
index 0000000..505d76a
--- /dev/null
+++ b/doc/src/sgml/html/collation.html
@@ -0,0 +1,417 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>24.2. Collation Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="locale.html" title="24.1. Locale Support" /><link rel="next" href="multibyte.html" title="24.3. Character Set Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">24.2. Collation Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="locale.html" title="24.1. Locale Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><th width="60%" align="center">Chapter 24. Localization</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="multibyte.html" title="24.3. Character Set Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="COLLATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">24.2. Collation Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="collation.html#id-1.6.11.4.4">24.2.1. Concepts</a></span></dt><dt><span class="sect2"><a href="collation.html#COLLATION-MANAGING">24.2.2. Managing Collations</a></span></dt></dl></div><a id="id-1.6.11.4.2" class="indexterm"></a><p>
+ The collation feature allows specifying the sort order and character
+ classification behavior of data per-column, or even per-operation.
+ This alleviates the restriction that the
+ <code class="symbol">LC_COLLATE</code> and <code class="symbol">LC_CTYPE</code> settings
+ of a database cannot be changed after its creation.
+ </p><div class="sect2" id="id-1.6.11.4.4"><div class="titlepage"><div><div><h3 class="title">24.2.1. Concepts</h3></div></div></div><p>
+ Conceptually, every expression of a collatable data type has a
+ collation. (The built-in collatable data types are
+ <code class="type">text</code>, <code class="type">varchar</code>, and <code class="type">char</code>.
+ User-defined base types can also be marked collatable, and of course
+ a <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain</a></em></a> over a
+ collatable data type is collatable.) If the
+ expression is a column reference, the collation of the expression is the
+ defined collation of the column. If the expression is a constant, the
+ collation is the default collation of the data type of the
+ constant. The collation of a more complex expression is derived
+ from the collations of its inputs, as described below.
+ </p><p>
+ The collation of an expression can be the <span class="quote">“<span class="quote">default</span>”</span>
+ collation, which means the locale settings defined for the
+ database. It is also possible for an expression's collation to be
+ indeterminate. In such cases, ordering operations and other
+ operations that need to know the collation will fail.
+ </p><p>
+ When the database system has to perform an ordering or a character
+ classification, it uses the collation of the input expression. This
+ happens, for example, with <code class="literal">ORDER BY</code> clauses
+ and function or operator calls such as <code class="literal">&lt;</code>.
+ The collation to apply for an <code class="literal">ORDER BY</code> clause
+ is simply the collation of the sort key. The collation to apply for a
+ function or operator call is derived from the arguments, as described
+ below. In addition to comparison operators, collations are taken into
+ account by functions that convert between lower and upper case
+ letters, such as <code class="function">lower</code>, <code class="function">upper</code>, and
+ <code class="function">initcap</code>; by pattern matching operators; and by
+ <code class="function">to_char</code> and related functions.
+ </p><p>
+ For a function or operator call, the collation that is derived by
+ examining the argument collations is used at run time for performing
+ the specified operation. If the result of the function or operator
+ call is of a collatable data type, the collation is also used at parse
+ time as the defined collation of the function or operator expression,
+ in case there is a surrounding expression that requires knowledge of
+ its collation.
+ </p><p>
+ The <em class="firstterm">collation derivation</em> of an expression can be
+ implicit or explicit. This distinction affects how collations are
+ combined when multiple different collations appear in an
+ expression. An explicit collation derivation occurs when a
+ <code class="literal">COLLATE</code> clause is used; all other collation
+ derivations are implicit. When multiple collations need to be
+ combined, for example in a function call, the following rules are
+ used:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ If any input expression has an explicit collation derivation, then
+ all explicitly derived collations among the input expressions must be
+ the same, otherwise an error is raised. If any explicitly
+ derived collation is present, that is the result of the
+ collation combination.
+ </p></li><li class="listitem"><p>
+ Otherwise, all input expressions must have the same implicit
+ collation derivation or the default collation. If any non-default
+ collation is present, that is the result of the collation combination.
+ Otherwise, the result is the default collation.
+ </p></li><li class="listitem"><p>
+ If there are conflicting non-default implicit collations among the
+ input expressions, then the combination is deemed to have indeterminate
+ collation. This is not an error condition unless the particular
+ function being invoked requires knowledge of the collation it should
+ apply. If it does, an error will be raised at run-time.
+ </p></li></ol></div><p>
+
+ For example, consider this table definition:
+</p><pre class="programlisting">
+CREATE TABLE test1 (
+ a text COLLATE "de_DE",
+ b text COLLATE "es_ES",
+ ...
+);
+</pre><p>
+
+ Then in
+</p><pre class="programlisting">
+SELECT a &lt; 'foo' FROM test1;
+</pre><p>
+ the <code class="literal">&lt;</code> comparison is performed according to
+ <code class="literal">de_DE</code> rules, because the expression combines an
+ implicitly derived collation with the default collation. But in
+</p><pre class="programlisting">
+SELECT a &lt; ('foo' COLLATE "fr_FR") FROM test1;
+</pre><p>
+ the comparison is performed using <code class="literal">fr_FR</code> rules,
+ because the explicit collation derivation overrides the implicit one.
+ Furthermore, given
+</p><pre class="programlisting">
+SELECT a &lt; b FROM test1;
+</pre><p>
+ the parser cannot determine which collation to apply, since the
+ <code class="structfield">a</code> and <code class="structfield">b</code> columns have conflicting
+ implicit collations. Since the <code class="literal">&lt;</code> operator
+ does need to know which collation to use, this will result in an
+ error. The error can be resolved by attaching an explicit collation
+ specifier to either input expression, thus:
+</p><pre class="programlisting">
+SELECT a &lt; b COLLATE "de_DE" FROM test1;
+</pre><p>
+ or equivalently
+</p><pre class="programlisting">
+SELECT a COLLATE "de_DE" &lt; b FROM test1;
+</pre><p>
+ On the other hand, the structurally similar case
+</p><pre class="programlisting">
+SELECT a || b FROM test1;
+</pre><p>
+ does not result in an error, because the <code class="literal">||</code> operator
+ does not care about collations: its result is the same regardless
+ of the collation.
+ </p><p>
+ The collation assigned to a function or operator's combined input
+ expressions is also considered to apply to the function or operator's
+ result, if the function or operator delivers a result of a collatable
+ data type. So, in
+</p><pre class="programlisting">
+SELECT * FROM test1 ORDER BY a || 'foo';
+</pre><p>
+ the ordering will be done according to <code class="literal">de_DE</code> rules.
+ But this query:
+</p><pre class="programlisting">
+SELECT * FROM test1 ORDER BY a || b;
+</pre><p>
+ results in an error, because even though the <code class="literal">||</code> operator
+ doesn't need to know a collation, the <code class="literal">ORDER BY</code> clause does.
+ As before, the conflict can be resolved with an explicit collation
+ specifier:
+</p><pre class="programlisting">
+SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
+</pre><p>
+ </p></div><div class="sect2" id="COLLATION-MANAGING"><div class="titlepage"><div><div><h3 class="title">24.2.2. Managing Collations</h3></div></div></div><p>
+ A collation is an SQL schema object that maps an SQL name to locales
+ provided by libraries installed in the operating system. A collation
+ definition has a <em class="firstterm">provider</em> that specifies which
+ library supplies the locale data. One standard provider name
+ is <code class="literal">libc</code>, which uses the locales provided by the
+ operating system C library. These are the locales used by most tools
+ provided by the operating system. Another provider
+ is <code class="literal">icu</code>, which uses the external
+ ICU<a id="id-1.6.11.4.5.2.4" class="indexterm"></a> library. ICU locales can only be
+ used if support for ICU was configured when PostgreSQL was built.
+ </p><p>
+ A collation object provided by <code class="literal">libc</code> maps to a
+ combination of <code class="symbol">LC_COLLATE</code> and <code class="symbol">LC_CTYPE</code>
+ settings, as accepted by the <code class="literal">setlocale()</code> system library call. (As
+ the name would suggest, the main purpose of a collation is to set
+ <code class="symbol">LC_COLLATE</code>, which controls the sort order. But
+ it is rarely necessary in practice to have an
+ <code class="symbol">LC_CTYPE</code> setting that is different from
+ <code class="symbol">LC_COLLATE</code>, so it is more convenient to collect
+ these under one concept than to create another infrastructure for
+ setting <code class="symbol">LC_CTYPE</code> per expression.) Also,
+ a <code class="literal">libc</code> collation
+ is tied to a character set encoding (see <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>).
+ The same collation name may exist for different encodings.
+ </p><p>
+ A collation object provided by <code class="literal">icu</code> maps to a named
+ collator provided by the ICU library. ICU does not support
+ separate <span class="quote">“<span class="quote">collate</span>”</span> and <span class="quote">“<span class="quote">ctype</span>”</span> settings, so
+ they are always the same. Also, ICU collations are independent of the
+ encoding, so there is always only one ICU collation of a given name in
+ a database.
+ </p><div class="sect3" id="id-1.6.11.4.5.5"><div class="titlepage"><div><div><h4 class="title">24.2.2.1. Standard Collations</h4></div></div></div><p>
+ On all platforms, the collations named <code class="literal">default</code>,
+ <code class="literal">C</code>, and <code class="literal">POSIX</code> are available. Additional
+ collations may be available depending on operating system support.
+ The <code class="literal">default</code> collation selects the <code class="symbol">LC_COLLATE</code>
+ and <code class="symbol">LC_CTYPE</code> values specified at database creation time.
+ The <code class="literal">C</code> and <code class="literal">POSIX</code> collations both specify
+ <span class="quote">“<span class="quote">traditional C</span>”</span> behavior, in which only the ASCII letters
+ <span class="quote">“<span class="quote"><code class="literal">A</code></span>”</span> through <span class="quote">“<span class="quote"><code class="literal">Z</code></span>”</span>
+ are treated as letters, and sorting is done strictly by character
+ code byte values.
+ </p><p>
+ Additionally, the SQL standard collation name <code class="literal">ucs_basic</code>
+ is available for encoding <code class="literal">UTF8</code>. It is equivalent
+ to <code class="literal">C</code> and sorts by Unicode code point.
+ </p></div><div class="sect3" id="id-1.6.11.4.5.6"><div class="titlepage"><div><div><h4 class="title">24.2.2.2. Predefined Collations</h4></div></div></div><p>
+ If the operating system provides support for using multiple locales
+ within a single program (<code class="function">newlocale</code> and related functions),
+ or if support for ICU is configured,
+ then when a database cluster is initialized, <code class="command">initdb</code>
+ populates the system catalog <code class="literal">pg_collation</code> with
+ collations based on all the locales it finds in the operating
+ system at the time.
+ </p><p>
+ To inspect the currently available locales, use the query <code class="literal">SELECT
+ * FROM pg_collation</code>, or the command <code class="command">\dOS+</code>
+ in <span class="application">psql</span>.
+ </p><div class="sect4" id="id-1.6.11.4.5.6.4"><div class="titlepage"><div><div><h5 class="title">24.2.2.2.1. libc Collations</h5></div></div></div><p>
+ For example, the operating system might
+ provide a locale named <code class="literal">de_DE.utf8</code>.
+ <code class="command">initdb</code> would then create a collation named
+ <code class="literal">de_DE.utf8</code> for encoding <code class="literal">UTF8</code>
+ that has both <code class="symbol">LC_COLLATE</code> and
+ <code class="symbol">LC_CTYPE</code> set to <code class="literal">de_DE.utf8</code>.
+ It will also create a collation with the <code class="literal">.utf8</code>
+ tag stripped off the name. So you could also use the collation
+ under the name <code class="literal">de_DE</code>, which is less cumbersome
+ to write and makes the name less encoding-dependent. Note that,
+ nevertheless, the initial set of collation names is
+ platform-dependent.
+ </p><p>
+ The default set of collations provided by <code class="literal">libc</code> map
+ directly to the locales installed in the operating system, which can be
+ listed using the command <code class="literal">locale -a</code>. In case
+ a <code class="literal">libc</code> collation is needed that has different values
+ for <code class="symbol">LC_COLLATE</code> and <code class="symbol">LC_CTYPE</code>, 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 <a class="xref" href="sql-createcollation.html" title="CREATE COLLATION"><span class="refentrytitle">CREATE COLLATION</span></a> command.
+ New operating system locales can also be imported en masse using
+ the <a class="link" href="functions-admin.html#FUNCTIONS-ADMIN-COLLATION" title="Table 9.96. Collation Management Functions"><code class="function">pg_import_system_collations()</code></a> function.
+ </p><p>
+ Within any particular database, only collations that use that
+ database's encoding are of interest. Other entries in
+ <code class="literal">pg_collation</code> are ignored. Thus, a stripped collation
+ name such as <code class="literal">de_DE</code> can be considered unique
+ within a given database even though it would not be unique globally.
+ Use of the stripped collation names is recommended, since it will
+ make one fewer thing you need to change if you decide to change to
+ another database encoding. Note however that the <code class="literal">default</code>,
+ <code class="literal">C</code>, and <code class="literal">POSIX</code> collations can be used regardless of
+ the database encoding.
+ </p><p>
+ <span class="productname">PostgreSQL</span> considers distinct collation
+ objects to be incompatible even when they have identical properties.
+ Thus for example,
+</p><pre class="programlisting">
+SELECT a COLLATE "C" &lt; b COLLATE "POSIX" FROM test1;
+</pre><p>
+ will draw an error even though the <code class="literal">C</code> and <code class="literal">POSIX</code>
+ collations have identical behaviors. Mixing stripped and non-stripped
+ collation names is therefore not recommended.
+ </p></div><div class="sect4" id="id-1.6.11.4.5.6.5"><div class="titlepage"><div><div><h5 class="title">24.2.2.2.2. ICU Collations</h5></div></div></div><p>
+ With ICU, it is not sensible to enumerate all possible locale names. ICU
+ uses a particular naming system for locales, but there are many more ways
+ to name a locale than there are actually distinct locales.
+ <code class="command">initdb</code> uses the ICU APIs to extract a set of distinct
+ locales to populate the initial set of collations. Collations provided by
+ ICU are created in the SQL environment with names in BCP 47 language tag
+ format, with a <span class="quote">“<span class="quote">private use</span>”</span>
+ extension <code class="literal">-x-icu</code> appended, to distinguish them from
+ libc locales.
+ </p><p>
+ Here are some example collations that might be created:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">de-x-icu</code></span></dt><dd><p>German collation, default variant</p></dd><dt><span class="term"><code class="literal">de-AT-x-icu</code></span></dt><dd><p>German collation for Austria, default variant</p><p>
+ (There are also, say, <code class="literal">de-DE-x-icu</code>
+ or <code class="literal">de-CH-x-icu</code>, but as of this writing, they are
+ equivalent to <code class="literal">de-x-icu</code>.)
+ </p></dd><dt><span class="term"><code class="literal">und-x-icu</code> (for <span class="quote">“<span class="quote">undefined</span>”</span>)</span></dt><dd><p>
+ ICU <span class="quote">“<span class="quote">root</span>”</span> collation. Use this to get a reasonable
+ language-agnostic sort order.
+ </p></dd></dl></div><p>
+ </p><p>
+ Some (less frequently used) encodings are not supported by ICU. When the
+ database encoding is one of these, ICU collation entries
+ in <code class="literal">pg_collation</code> are ignored. Attempting to use one
+ will draw an error along the lines of <span class="quote">“<span class="quote">collation "de-x-icu" for
+ encoding "WIN874" does not exist</span>”</span>.
+ </p></div></div><div class="sect3" id="COLLATION-CREATE"><div class="titlepage"><div><div><h4 class="title">24.2.2.3. Creating New Collation Objects</h4></div></div></div><p>
+ If the standard and predefined collations are not sufficient, users can
+ create their own collation objects using the SQL
+ command <a class="xref" href="sql-createcollation.html" title="CREATE COLLATION"><span class="refentrytitle">CREATE COLLATION</span></a>.
+ </p><p>
+ The standard and predefined collations are in the
+ schema <code class="literal">pg_catalog</code>, like all predefined objects.
+ User-defined collations should be created in user schemas. This also
+ ensures that they are saved by <code class="command">pg_dump</code>.
+ </p><div class="sect4" id="id-1.6.11.4.5.7.4"><div class="titlepage"><div><div><h5 class="title">24.2.2.3.1. libc Collations</h5></div></div></div><p>
+ New libc collations can be created like this:
+</p><pre class="programlisting">
+CREATE COLLATION german (provider = libc, locale = 'de_DE');
+</pre><p>
+ The exact values that are acceptable for the <code class="literal">locale</code>
+ clause in this command depend on the operating system. On Unix-like
+ systems, the command <code class="literal">locale -a</code> will show a list.
+ </p><p>
+ Since the predefined libc collations already include all collations
+ 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 <a class="xref" href="collation.html#COLLATION-COPY" title="24.2.2.3.3. Copying Collations">Section 24.2.2.3.3</a>) or if the operating system has
+ been upgraded to provide new locale definitions (in which case see
+ also <a class="link" href="functions-admin.html#FUNCTIONS-ADMIN-COLLATION" title="Table 9.96. Collation Management Functions"><code class="function">pg_import_system_collations()</code></a>).
+ </p></div><div class="sect4" id="id-1.6.11.4.5.7.5"><div class="titlepage"><div><div><h5 class="title">24.2.2.3.2. ICU Collations</h5></div></div></div><p>
+ ICU allows collations to be customized beyond the basic language+country
+ set that is preloaded by <code class="command">initdb</code>. Users are encouraged
+ to define their own collation objects that make use of these facilities to
+ suit the sorting behavior to their requirements.
+ See <a class="ulink" href="https://unicode-org.github.io/icu/userguide/locale/" target="_top">https://unicode-org.github.io/icu/userguide/locale/</a>
+ and <a class="ulink" href="https://unicode-org.github.io/icu/userguide/collation/api.html" target="_top">https://unicode-org.github.io/icu/userguide/collation/api.html</a> for
+ information on ICU locale naming. The set of acceptable names and
+ attributes depends on the particular ICU version.
+ </p><p>
+ Here are some examples:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CREATE COLLATION "de-u-co-phonebk-x-icu" (provider = icu, locale = 'de-u-co-phonebk');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION "de-u-co-phonebk-x-icu" (provider = icu, locale = 'de@collation=phonebook');</code></span></dt><dd><p>German collation with phone book collation type</p><p>
+ The first example selects the ICU locale using a <span class="quote">“<span class="quote">language
+ tag</span>”</span> per BCP 47. The second example uses the traditional
+ ICU-specific locale syntax. The first style is preferred going
+ forward, but it is not supported by older ICU versions.
+ </p><p>
+ Note that you can name the collation objects in the SQL environment
+ anything you want. In this example, we follow the naming style that
+ the predefined collations use, which in turn also follow BCP 47, but
+ that is not required for user-defined collations.
+ </p></dd><dt><span class="term"><code class="literal">CREATE COLLATION "und-u-co-emoji-x-icu" (provider = icu, locale = 'und-u-co-emoji');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION "und-u-co-emoji-x-icu" (provider = icu, locale = '@collation=emoji');</code></span></dt><dd><p>
+ Root collation with Emoji collation type, per Unicode Technical Standard #51
+ </p><p>
+ Observe how in the traditional ICU locale naming system, the root
+ locale is selected by an empty string.
+ </p></dd><dt><span class="term"><code class="literal">CREATE COLLATION latinlast (provider = icu, locale = 'en-u-kr-grek-latn');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION latinlast (provider = icu, locale = 'en@colReorder=grek-latn');</code></span></dt><dd><p>
+ Sort Greek letters before Latin ones. (The default is Latin before Greek.)
+ </p></dd><dt><span class="term"><code class="literal">CREATE COLLATION upperfirst (provider = icu, locale = 'en-u-kf-upper');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION upperfirst (provider = icu, locale = 'en@colCaseFirst=upper');</code></span></dt><dd><p>
+ Sort upper-case letters before lower-case letters. (The default is
+ lower-case letters first.)
+ </p></dd><dt><span class="term"><code class="literal">CREATE COLLATION special (provider = icu, locale = 'en-u-kf-upper-kr-grek-latn');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION special (provider = icu, locale = 'en@colCaseFirst=upper;colReorder=grek-latn');</code></span></dt><dd><p>
+ Combines both of the above options.
+ </p></dd><dt><span class="term"><code class="literal">CREATE COLLATION numeric (provider = icu, locale = 'en-u-kn-true');</code><br /></span><span class="term"><code class="literal">CREATE COLLATION numeric (provider = icu, locale = 'en@colNumeric=yes');</code></span></dt><dd><p>
+ Numeric ordering, sorts sequences of digits by their numeric value,
+ for example: <code class="literal">A-21</code> &lt; <code class="literal">A-123</code>
+ (also known as natural sort).
+ </p></dd></dl></div><p>
+
+ See <a class="ulink" href="https://www.unicode.org/reports/tr35/tr35-collation.html" target="_top">Unicode
+ Technical Standard #35</a>
+ and <a class="ulink" href="https://tools.ietf.org/html/bcp47" target="_top">BCP 47</a> for
+ details. The list of possible collation types (<code class="literal">co</code>
+ subtag) can be found in
+ the <a class="ulink" href="https://github.com/unicode-org/cldr/blob/master/common/bcp47/collation.xml" target="_top">CLDR
+ repository</a>.
+ </p><p>
+ Note that while this system allows creating collations that <span class="quote">“<span class="quote">ignore
+ case</span>”</span> or <span class="quote">“<span class="quote">ignore accents</span>”</span> or similar (using the
+ <code class="literal">ks</code> key), in order for such collations to act in a
+ truly case- or accent-insensitive manner, they also need to be declared as not
+ <em class="firstterm">deterministic</em> in <code class="command">CREATE COLLATION</code>;
+ see <a class="xref" href="collation.html#COLLATION-NONDETERMINISTIC" title="24.2.2.4. Nondeterministic Collations">Section 24.2.2.4</a>.
+ Otherwise, any strings that compare equal according to the collation but
+ are not byte-wise equal will be sorted according to their byte values.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ By design, ICU will accept almost any string as a locale name and match
+ it to the closest locale it can provide, using the fallback procedure
+ described in its documentation. Thus, there will be no direct feedback
+ if a collation specification is composed using features that the given
+ ICU installation does not actually support. It is therefore recommended
+ to create application-level test cases to check that the collation
+ definitions satisfy one's requirements.
+ </p></div></div><div class="sect4" id="COLLATION-COPY"><div class="titlepage"><div><div><h5 class="title">24.2.2.3.3. Copying Collations</h5></div></div></div><p>
+ The command <a class="xref" href="sql-createcollation.html" title="CREATE COLLATION"><span class="refentrytitle">CREATE COLLATION</span></a> can also be used to
+ create a new collation from an existing collation, which can be useful to
+ be able to use operating-system-independent collation names in
+ applications, create compatibility names, or use an ICU-provided collation
+ under a more readable name. For example:
+</p><pre class="programlisting">
+CREATE COLLATION german FROM "de_DE";
+CREATE COLLATION french FROM "fr-x-icu";
+</pre><p>
+ </p></div></div><div class="sect3" id="COLLATION-NONDETERMINISTIC"><div class="titlepage"><div><div><h4 class="title">24.2.2.4. Nondeterministic Collations</h4></div></div></div><p>
+ A collation is either <em class="firstterm">deterministic</em> or
+ <em class="firstterm">nondeterministic</em>. A deterministic collation uses
+ deterministic comparisons, which means that it considers strings to be
+ equal only if they consist of the same byte sequence. Nondeterministic
+ comparison may determine strings to be equal even if they consist of
+ different bytes. Typical situations include case-insensitive comparison,
+ accent-insensitive comparison, as well as comparison of strings in
+ different Unicode normal forms. It is up to the collation provider to
+ actually implement such insensitive comparisons; the deterministic flag
+ only determines whether ties are to be broken using bytewise comparison.
+ See also <a class="ulink" href="https://www.unicode.org/reports/tr10" target="_top">Unicode Technical
+ Standard 10</a> for more information on the terminology.
+ </p><p>
+ To create a nondeterministic collation, specify the property
+ <code class="literal">deterministic = false</code> to <code class="command">CREATE
+ COLLATION</code>, for example:
+</p><pre class="programlisting">
+CREATE COLLATION ndcoll (provider = icu, locale = 'und', deterministic = false);
+</pre><p>
+ This example would use the standard Unicode collation in a
+ nondeterministic way. In particular, this would allow strings in
+ different normal forms to be compared correctly. More interesting
+ examples make use of the ICU customization facilities explained above.
+ For example:
+</p><pre class="programlisting">
+CREATE COLLATION case_insensitive (provider = icu, locale = 'und-u-ks-level2', deterministic = false);
+CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-true', deterministic = false);
+</pre><p>
+ </p><p>
+ All standard and predefined collations are deterministic, all
+ user-defined collations are deterministic by default. While
+ nondeterministic collations give a more <span class="quote">“<span class="quote">correct</span>”</span> behavior,
+ especially when considering the full power of Unicode and its many
+ special cases, they also have some drawbacks. Foremost, their use leads
+ to a performance penalty. Note, in particular, that B-tree cannot use
+ deduplication with indexes that use a nondeterministic collation. Also,
+ certain operations are not possible with nondeterministic collations,
+ such as pattern matching operations. Therefore, they should be used
+ only in cases where they are specifically wanted.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ To deal with text in different Unicode normalization forms, it is also
+ an option to use the functions/expressions
+ <code class="function">normalize</code> and <code class="literal">is normalized</code> to
+ preprocess or check the strings, instead of using nondeterministic
+ collations. There are different trade-offs for each approach.
+ </p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="locale.html" title="24.1. Locale Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="multibyte.html" title="24.3. Character Set Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">24.1. Locale Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 24.3. Character Set Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/color-when.html b/doc/src/sgml/html/color-when.html
new file mode 100644
index 0000000..8f68af8
--- /dev/null
+++ b/doc/src/sgml/html/color-when.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>N.1. When Color is Used</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="color.html" title="Appendix N. Color Support" /><link rel="next" href="color-which.html" title="N.2. Configuring the Colors" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">N.1. When Color is Used</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="color.html" title="Appendix N. Color Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="color.html" title="Appendix N. Color Support">Up</a></td><th width="60%" align="center">Appendix N. Color Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="color-which.html" title="N.2. Configuring the Colors">Next</a></td></tr></table><hr /></div><div class="sect1" id="COLOR-WHEN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">N.1. When Color is Used</h2></div></div></div><p>
+ To use colorized output, set the environment variable
+ <code class="envar">PG_COLOR</code><a id="id-1.11.15.4.2.2" class="indexterm"></a>
+ as follows:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ If the value is <code class="literal">always</code>, then color is used.
+ </p></li><li class="listitem"><p>
+ If the value is <code class="literal">auto</code> and the standard error stream
+ is associated with a terminal device, then color is used.
+ </p></li><li class="listitem"><p>
+ Otherwise, color is not used.
+ </p></li></ol></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="color.html" title="Appendix N. Color Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="color.html" title="Appendix N. Color Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="color-which.html" title="N.2. Configuring the Colors">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix N. Color Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> N.2. Configuring the Colors</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/color-which.html b/doc/src/sgml/html/color-which.html
new file mode 100644
index 0000000..eea1c4f
--- /dev/null
+++ b/doc/src/sgml/html/color-which.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>N.2. Configuring the Colors</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="color-when.html" title="N.1. When Color is Used" /><link rel="next" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">N.2. Configuring the Colors</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="color-when.html" title="N.1. When Color is Used">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="color.html" title="Appendix N. Color Support">Up</a></td><th width="60%" align="center">Appendix N. Color Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Next</a></td></tr></table><hr /></div><div class="sect1" id="COLOR-WHICH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">N.2. Configuring the Colors</h2></div></div></div><p>
+ The actual colors to be used are configured using the environment variable
+ <code class="envar">PG_COLORS</code><a id="id-1.11.15.5.2.2" class="indexterm"></a>
+ (note plural). The value is a colon-separated list of
+ <code class="literal"><em class="replaceable"><code>key</code></em>=<em class="replaceable"><code>value</code></em></code>
+ pairs. The keys specify what the color is to be used for. The values are
+ SGR (Select Graphic Rendition) specifications, which are interpreted by the
+ terminal.
+ </p><p>
+ The following keys are currently in use:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">error</code></span></dt><dd><p>used to highlight the text <span class="quote">“<span class="quote">error</span>”</span> in error messages</p></dd><dt><span class="term"><code class="literal">warning</code></span></dt><dd><p>used to highlight the text <span class="quote">“<span class="quote">warning</span>”</span> in warning
+ messages</p></dd><dt><span class="term"><code class="literal">note</code></span></dt><dd><p>used to highlight the text <span class="quote">“<span class="quote">detail</span>”</span> and
+ <span class="quote">“<span class="quote">hint</span>”</span> in such messages</p></dd><dt><span class="term"><code class="literal">locus</code></span></dt><dd><p>used to highlight location information (e.g., program name and
+ file name) in messages</p></dd></dl></div><p>
+ </p><p>
+ The default value is
+ <code class="literal">error=01;31:warning=01;35:note=01;36:locus=01</code>
+ (<code class="literal">01;31</code> = bold red, <code class="literal">01;35</code> = bold
+ magenta, <code class="literal">01;36</code> = bold cyan, <code class="literal">01</code> = bold
+ default color).
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ This color specification format is also used by other software packages
+ such as <span class="productname">GCC</span>, <span class="productname">GNU
+ coreutils</span>, and <span class="productname">GNU grep</span>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="color-when.html" title="N.1. When Color is Used">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="color.html" title="Appendix N. Color Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">N.1. When Color is Used </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix O. Obsolete or Renamed Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/color.html b/doc/src/sgml/html/color.html
new file mode 100644
index 0000000..5b3f280
--- /dev/null
+++ b/doc/src/sgml/html/color.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix N. Color Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="glossary.html" title="Appendix M. Glossary" /><link rel="next" href="color-when.html" title="N.1. When Color is Used" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix N. Color Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="glossary.html" title="Appendix M. Glossary">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="color-when.html" title="N.1. When Color is Used">Next</a></td></tr></table><hr /></div><div class="appendix" id="COLOR"><div class="titlepage"><div><div><h2 class="title">Appendix N. Color Support</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="color-when.html">N.1. When Color is Used</a></span></dt><dt><span class="sect1"><a href="color-which.html">N.2. Configuring the Colors</a></span></dt></dl></div><a id="id-1.11.15.2" class="indexterm"></a><p>
+ Most programs in the PostgreSQL package can produce colorized console
+ output. This appendix describes how that is configured.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="glossary.html" title="Appendix M. Glossary">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="color-when.html" title="N.1. When Color is Used">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix M. Glossary </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> N.1. When Color is Used</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/config-setting.html b/doc/src/sgml/html/config-setting.html
new file mode 100644
index 0000000..a5d68b7
--- /dev/null
+++ b/doc/src/sgml/html/config-setting.html
@@ -0,0 +1,336 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.1. Setting Parameters</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config.html" title="Chapter 20. Server Configuration" /><link rel="next" href="runtime-config-file-locations.html" title="20.2. File Locations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.1. Setting Parameters</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config.html" title="Chapter 20. Server Configuration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-file-locations.html" title="20.2. File Locations">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONFIG-SETTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.1. Setting Parameters</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-NAMES-VALUES">20.1.1. Parameter Names and Values</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE">20.1.2. Parameter Interaction via the Configuration File</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-SQL-COMMAND-INTERACTION">20.1.3. Parameter Interaction via SQL</a></span></dt><dt><span class="sect2"><a href="config-setting.html#id-1.6.7.4.5">20.1.4. Parameter Interaction via the Shell</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-INCLUDES">20.1.5. Managing Configuration File Contents</a></span></dt></dl></div><div class="sect2" id="CONFIG-SETTING-NAMES-VALUES"><div class="titlepage"><div><div><h3 class="title">20.1.1. Parameter Names and Values</h3></div></div></div><p>
+ All parameter names are case-insensitive. Every parameter takes a
+ value of one of five types: boolean, string, integer, floating point,
+ or enumerated (enum). The type determines the syntax for setting the
+ parameter:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <span class="emphasis"><em>Boolean:</em></span>
+ Values can be written as
+ <code class="literal">on</code>,
+ <code class="literal">off</code>,
+ <code class="literal">true</code>,
+ <code class="literal">false</code>,
+ <code class="literal">yes</code>,
+ <code class="literal">no</code>,
+ <code class="literal">1</code>,
+ <code class="literal">0</code>
+ (all case-insensitive) or any unambiguous prefix of one of these.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>String:</em></span>
+ In general, enclose the value in single quotes, doubling any single
+ quotes within the value. Quotes can usually be omitted if the value
+ is a simple number or identifier, however.
+ (Values that match an SQL keyword require quoting in some contexts.)
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Numeric (integer and floating point):</em></span>
+ Numeric parameters can be specified in the customary integer and
+ floating-point formats; fractional values are rounded to the nearest
+ integer if the parameter is of integer type. Integer parameters
+ additionally accept hexadecimal input (beginning
+ with <code class="literal">0x</code>) and octal input (beginning
+ with <code class="literal">0</code>), but these formats cannot have a fraction.
+ Do not use thousands separators.
+ Quotes are not required, except for hexadecimal input.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Numeric with Unit:</em></span>
+ Some numeric parameters have an implicit unit, because they describe
+ quantities of memory or time. The unit might be bytes, kilobytes, blocks
+ (typically eight kilobytes), milliseconds, seconds, or minutes.
+ An unadorned numeric value for one of these settings will use the
+ setting's default unit, which can be learned from
+ <code class="structname">pg_settings</code>.<code class="structfield">unit</code>.
+ For convenience, settings can be given with a unit specified explicitly,
+ for example <code class="literal">'120 ms'</code> for a time value, and they will be
+ converted to whatever the parameter's actual unit is. Note that the
+ value must be written as a string (with quotes) to use this feature.
+ The unit name is case-sensitive, and there can be whitespace between
+ the numeric value and the unit.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ Valid memory units are <code class="literal">B</code> (bytes),
+ <code class="literal">kB</code> (kilobytes),
+ <code class="literal">MB</code> (megabytes), <code class="literal">GB</code>
+ (gigabytes), and <code class="literal">TB</code> (terabytes).
+ The multiplier for memory units is 1024, not 1000.
+ </p></li><li class="listitem"><p>
+ Valid time units are
+ <code class="literal">us</code> (microseconds),
+ <code class="literal">ms</code> (milliseconds),
+ <code class="literal">s</code> (seconds), <code class="literal">min</code> (minutes),
+ <code class="literal">h</code> (hours), and <code class="literal">d</code> (days).
+ </p></li></ul></div><p>
+
+ If a fractional value is specified with a unit, it will be rounded
+ to a multiple of the next smaller unit if there is one.
+ For example, <code class="literal">30.1 GB</code> will be converted
+ to <code class="literal">30822 MB</code> not <code class="literal">32319628902 B</code>.
+ If the parameter is of integer type, a final rounding to integer
+ occurs after any unit conversion.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Enumerated:</em></span>
+ Enumerated-type parameters are written in the same way as string
+ parameters, but are restricted to have one of a limited set of
+ values. The values allowable for such a parameter can be found from
+ <code class="structname">pg_settings</code>.<code class="structfield">enumvals</code>.
+ Enum parameter values are case-insensitive.
+ </p></li></ul></div></div><div class="sect2" id="CONFIG-SETTING-CONFIGURATION-FILE"><div class="titlepage"><div><div><h3 class="title">20.1.2. Parameter Interaction via the Configuration File</h3></div></div></div><p>
+ The most fundamental way to set these parameters is to edit the file
+ <code class="filename">postgresql.conf</code><a id="id-1.6.7.4.3.2.2" class="indexterm"></a>,
+ which is normally kept in the data directory. A default copy is
+ installed when the database cluster directory is initialized.
+ An example of what this file might look like is:
+</p><pre class="programlisting">
+# This is a comment
+log_connections = yes
+log_destination = 'syslog'
+search_path = '"$user", public'
+shared_buffers = 128MB
+</pre><p>
+ One parameter is specified per line. The equal sign between name and
+ value is optional. Whitespace is insignificant (except within a quoted
+ parameter value) and blank lines are
+ ignored. Hash marks (<code class="literal">#</code>) designate the remainder
+ of the line as a comment. Parameter values that are not simple
+ identifiers or numbers must be single-quoted. To embed a single
+ quote in a parameter value, write either two quotes (preferred)
+ or backslash-quote.
+ If the file contains multiple entries for the same parameter,
+ all but the last one are ignored.
+ </p><p>
+ Parameters set in this way provide default values for the cluster.
+ The settings seen by active sessions will be these values unless they
+ are overridden. The following sections describe ways in which the
+ administrator or user can override these defaults.
+ </p><p>
+ <a id="id-1.6.7.4.3.4.1" class="indexterm"></a>
+ The configuration file is reread whenever the main server process
+ receives a <span class="systemitem">SIGHUP</span> signal; this signal is most easily
+ sent by running <code class="literal">pg_ctl reload</code> from the command line or by
+ calling the SQL function <code class="function">pg_reload_conf()</code>. The main
+ server process also propagates this signal to all currently running
+ server processes, so that existing sessions also adopt the new values
+ (this will happen after they complete any currently-executing client
+ command). Alternatively, you can
+ send the signal to a single server process directly. Some parameters
+ can only be set at server start; any changes to their entries in the
+ configuration file will be ignored until the server is restarted.
+ Invalid parameter settings in the configuration file are likewise
+ ignored (but logged) during <span class="systemitem">SIGHUP</span> processing.
+ </p><p>
+ In addition to <code class="filename">postgresql.conf</code>,
+ a <span class="productname">PostgreSQL</span> data directory contains a file
+ <code class="filename">postgresql.auto.conf</code><a id="id-1.6.7.4.3.5.4" class="indexterm"></a>,
+ which has the same format as <code class="filename">postgresql.conf</code> but
+ is intended to be edited automatically, not manually. This file holds
+ settings provided through the <a class="link" href="sql-altersystem.html" title="ALTER SYSTEM"><code class="command">ALTER SYSTEM</code></a> command.
+ This file is read whenever <code class="filename">postgresql.conf</code> is,
+ and its settings take effect in the same way. Settings
+ in <code class="filename">postgresql.auto.conf</code> override those
+ in <code class="filename">postgresql.conf</code>.
+ </p><p>
+ External tools may also
+ modify <code class="filename">postgresql.auto.conf</code>. It is not
+ recommended to do this while the server is running, since a
+ concurrent <code class="command">ALTER SYSTEM</code> command could overwrite
+ such changes. Such tools might simply append new settings to the end,
+ or they might choose to remove duplicate settings and/or comments
+ (as <code class="command">ALTER SYSTEM</code> will).
+ </p><p>
+ The system view
+ <a class="link" href="view-pg-file-settings.html" title="54.7. pg_file_settings"><code class="structname">pg_file_settings</code></a>
+ can be helpful for pre-testing changes to the configuration files, or for
+ diagnosing problems if a <span class="systemitem">SIGHUP</span> signal did not have the
+ desired effects.
+ </p></div><div class="sect2" id="CONFIG-SETTING-SQL-COMMAND-INTERACTION"><div class="titlepage"><div><div><h3 class="title">20.1.3. Parameter Interaction via SQL</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides three SQL
+ commands to establish configuration defaults.
+ The already-mentioned <code class="command">ALTER SYSTEM</code> command
+ provides an SQL-accessible means of changing global defaults; it is
+ functionally equivalent to editing <code class="filename">postgresql.conf</code>.
+ In addition, there are two commands that allow setting of defaults
+ on a per-database or per-role basis:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE</code></a> command allows global
+ settings to be overridden on a per-database basis.
+ </p></li><li class="listitem"><p>
+ The <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a> command allows both global and
+ per-database settings to be overridden with user-specific values.
+ </p></li></ul></div><p>
+ Values set with <code class="command">ALTER DATABASE</code> and <code class="command">ALTER ROLE</code>
+ are applied only when starting a fresh database session. They
+ override values obtained from the configuration files or server
+ command line, and constitute defaults for the rest of the session.
+ Note that some settings cannot be changed after server start, and
+ so cannot be set with these commands (or the ones listed below).
+ </p><p>
+ Once a client is connected to the database, <span class="productname">PostgreSQL</span>
+ provides two additional SQL commands (and equivalent functions) to
+ interact with session-local configuration settings:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <a class="link" href="sql-show.html" title="SHOW"><code class="command">SHOW</code></a> command allows inspection of the
+ current value of any parameter. The corresponding SQL function is
+ <code class="function">current_setting(setting_name text)</code>
+ (see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET" title="9.27.1. Configuration Settings Functions">Section 9.27.1</a>).
+ </p></li><li class="listitem"><p>
+ The <a class="link" href="sql-set.html" title="SET"><code class="command">SET</code></a> 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.
+ Many parameters can be set this way by any user, but some can
+ only be set by superusers and users who have been
+ granted <code class="literal">SET</code> privilege on that parameter.
+ The corresponding SQL function is
+ <code class="function">set_config(setting_name, new_value, is_local)</code>
+ (see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET" title="9.27.1. Configuration Settings Functions">Section 9.27.1</a>).
+ </p></li></ul></div><p>
+ In addition, the system view <a class="link" href="view-pg-settings.html" title="54.24. pg_settings"><code class="structname">pg_settings</code></a> can be
+ used to view and change session-local values:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Querying this view is similar to using <code class="command">SHOW ALL</code> but
+ provides more detail. It is also more flexible, since it's possible
+ to specify filter conditions or join against other relations.
+ </p></li><li class="listitem"><p>
+ Using <code class="command">UPDATE</code> on this view, specifically
+ updating the <code class="structname">setting</code> column, is the equivalent
+ of issuing <code class="command">SET</code> commands. For example, the equivalent of
+</p><pre class="programlisting">
+SET configuration_parameter TO DEFAULT;
+</pre><p>
+ is:
+</p><pre class="programlisting">
+UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
+</pre><p>
+ </p></li></ul></div></div><div class="sect2" id="id-1.6.7.4.5"><div class="titlepage"><div><div><h3 class="title">20.1.4. Parameter Interaction via the Shell</h3></div></div></div><p>
+ In addition to setting global defaults or attaching
+ overrides at the database or role level, you can pass settings to
+ <span class="productname">PostgreSQL</span> via shell facilities.
+ Both the server and <span class="application">libpq</span> client library
+ accept parameter values via the shell.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ During server startup, parameter settings can be
+ passed to the <code class="command">postgres</code> command via the
+ <code class="option">-c</code> command-line parameter. For example,
+</p><pre class="programlisting">
+postgres -c log_connections=yes -c log_destination='syslog'
+</pre><p>
+ Settings provided in this way override those set via
+ <code class="filename">postgresql.conf</code> or <code class="command">ALTER SYSTEM</code>,
+ so they cannot be changed globally without restarting the server.
+ </p></li><li class="listitem"><p>
+ When starting a client session via <span class="application">libpq</span>,
+ parameter settings can be
+ specified using the <code class="envar">PGOPTIONS</code> environment variable.
+ Settings established in this way constitute defaults for the life
+ of the session, but do not affect other sessions.
+ For historical reasons, the format of <code class="envar">PGOPTIONS</code> is
+ similar to that used when launching the <code class="command">postgres</code>
+ command; specifically, the <code class="option">-c</code> flag must be specified.
+ For example,
+</p><pre class="programlisting">
+env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql
+</pre><p>
+ </p><p>
+ Other clients and libraries might provide their own mechanisms,
+ via the shell or otherwise, that allow the user to alter session
+ settings without direct use of SQL commands.
+ </p></li></ul></div></div><div class="sect2" id="CONFIG-INCLUDES"><div class="titlepage"><div><div><h3 class="title">20.1.5. Managing Configuration File Contents</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides several features for breaking
+ down complex <code class="filename">postgresql.conf</code> files into sub-files.
+ These features are especially useful when managing multiple servers
+ with related, but not identical, configurations.
+ </p><p>
+ <a id="id-1.6.7.4.6.3.1" class="indexterm"></a>
+ In addition to individual parameter settings,
+ the <code class="filename">postgresql.conf</code> file can contain <em class="firstterm">include
+ directives</em>, which specify another file to read and process as if
+ it were inserted into the configuration file at this point. This
+ feature allows a configuration file to be divided into physically
+ separate parts. Include directives simply look like:
+</p><pre class="programlisting">
+include 'filename'
+</pre><p>
+ If the file name is not an absolute path, it is taken as relative to
+ the directory containing the referencing configuration file.
+ Inclusions can be nested.
+ </p><p>
+ <a id="id-1.6.7.4.6.4.1" class="indexterm"></a>
+ There is also an <code class="literal">include_if_exists</code> directive, which acts
+ the same as the <code class="literal">include</code> directive, except
+ when the referenced file does not exist or cannot be read. A regular
+ <code class="literal">include</code> will consider this an error condition, but
+ <code class="literal">include_if_exists</code> merely logs a message and continues
+ processing the referencing configuration file.
+ </p><p>
+ <a id="id-1.6.7.4.6.5.1" class="indexterm"></a>
+ The <code class="filename">postgresql.conf</code> file can also contain
+ <code class="literal">include_dir</code> directives, which specify an entire
+ directory of configuration files to include. These look like
+</p><pre class="programlisting">
+include_dir 'directory'
+</pre><p>
+ Non-absolute directory names are taken as relative to the directory
+ containing the referencing configuration file. Within the specified
+ directory, only non-directory files whose names end with the
+ suffix <code class="literal">.conf</code> will be included. File names that
+ start with the <code class="literal">.</code> character are also ignored, to
+ prevent mistakes since such files are hidden on some platforms. Multiple
+ files within an include directory are processed in file name order
+ (according to C locale rules, i.e., numbers before letters, and
+ uppercase letters before lowercase ones).
+ </p><p>
+ Include files or directories can be used to logically separate portions
+ of the database configuration, rather than having a single large
+ <code class="filename">postgresql.conf</code> file. Consider a company that has two
+ database servers, each with a different amount of memory. There are
+ likely elements of the configuration both will share, for things such
+ as logging. But memory-related parameters on the server will vary
+ between the two. And there might be server specific customizations,
+ too. One way to manage this situation is to break the custom
+ configuration changes for your site into three files. You could add
+ this to the end of your <code class="filename">postgresql.conf</code> file to include
+ them:
+</p><pre class="programlisting">
+include 'shared.conf'
+include 'memory.conf'
+include 'server.conf'
+</pre><p>
+ All systems would have the same <code class="filename">shared.conf</code>. Each
+ server with a particular amount of memory could share the
+ same <code class="filename">memory.conf</code>; you might have one for all servers
+ with 8GB of RAM, another for those having 16GB. And
+ finally <code class="filename">server.conf</code> could have truly server-specific
+ configuration information in it.
+ </p><p>
+ Another possibility is to create a configuration file directory and
+ put this information into files there. For example, a <code class="filename">conf.d</code>
+ directory could be referenced at the end of <code class="filename">postgresql.conf</code>:
+</p><pre class="programlisting">
+include_dir 'conf.d'
+</pre><p>
+ Then you could name the files in the <code class="filename">conf.d</code> directory
+ like this:
+</p><pre class="programlisting">
+00shared.conf
+01memory.conf
+02server.conf
+</pre><p>
+ This naming convention establishes a clear order in which these
+ files will be loaded. This is important because only the last
+ setting encountered for a particular parameter while the server is
+ reading configuration files will be used. In this example,
+ something set in <code class="filename">conf.d/02server.conf</code> would override a
+ value set in <code class="filename">conf.d/01memory.conf</code>.
+ </p><p>
+ You might instead use this approach to naming the files
+ descriptively:
+</p><pre class="programlisting">
+00shared.conf
+01memory-8GB.conf
+02server-foo.conf
+</pre><p>
+ This sort of arrangement gives a unique name for each configuration file
+ variation. This can help eliminate ambiguity when several servers have
+ their configurations all stored in one place, such as in a version
+ control repository. (Storing database configuration files under version
+ control is another good practice to consider.)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config.html" title="Chapter 20. Server Configuration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-file-locations.html" title="20.2. File Locations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 20. Server Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.2. File Locations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/connect-estab.html b/doc/src/sgml/html/connect-estab.html
new file mode 100644
index 0000000..87e3a8b
--- /dev/null
+++ b/doc/src/sgml/html/connect-estab.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.2. How Connections Are Established</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="query-path.html" title="52.1. The Path of a Query" /><link rel="next" href="parser-stage.html" title="52.3. The Parser Stage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.2. How Connections Are Established</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="query-path.html" title="52.1. The Path of a Query">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parser-stage.html" title="52.3. The Parser Stage">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONNECT-ESTAB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.2. How Connections Are Established</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> implements a
+ <span class="quote">“<span class="quote">process per user</span>”</span> client/server model.
+ In this model, every
+ <a class="glossterm" href="glossary.html#GLOSSARY-CLIENT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CLIENT" title="Client (process)">client process</a></em></a>
+ connects to exactly one
+ <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend process</a></em></a>.
+ As we do not know ahead of time how many connections will be made,
+ we have to use a <span class="quote">“<span class="quote">supervisor process</span>”</span> that spawns a new
+ backend process every time a connection is requested. This supervisor
+ process is called
+ <a class="glossterm" href="glossary.html#GLOSSARY-POSTMASTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-POSTMASTER" title="Postmaster (process)">postmaster</a></em></a>
+ and listens at a specified TCP/IP port for incoming connections.
+ Whenever it detects a request for a connection, it spawns a new
+ backend process. Those backend processes communicate with each
+ other and with other processes of the
+ <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>
+ using <em class="firstterm">semaphores</em> and
+ <a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY" title="Shared memory">shared memory</a></em></a>
+ to ensure data integrity throughout concurrent data access.
+ </p><p>
+ The client process can be any program that understands the
+ <span class="productname">PostgreSQL</span> protocol described in
+ <a class="xref" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Chapter 55</a>. Many clients are based on the
+ C-language library <span class="application">libpq</span>, but several independent
+ implementations of the protocol exist, such as the Java
+ <span class="application">JDBC</span> driver.
+ </p><p>
+ Once a connection is established, the client process can send a query
+ to the backend process it's connected to. The query is transmitted using
+ plain text, i.e., there is no parsing done in the client. The backend
+ process parses the query, creates an <em class="firstterm">execution plan</em>,
+ executes the plan, and returns the retrieved rows to the client
+ by transmitting them over the established connection.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="query-path.html" title="52.1. The Path of a Query">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parser-stage.html" title="52.3. The Parser Stage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.1. The Path of a Query </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.3. The Parser Stage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/continuous-archiving.html b/doc/src/sgml/html/continuous-archiving.html
new file mode 100644
index 0000000..adc7ae7
--- /dev/null
+++ b/doc/src/sgml/html/continuous-archiving.html
@@ -0,0 +1,757 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="backup-file.html" title="26.2. File System Level Backup" /><link rel="next" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="backup-file.html" title="26.2. File System Level Backup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><th width="60%" align="center">Chapter 26. Backup and Restore</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONTINUOUS-ARCHIVING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">26.3. Continuous Archiving and Point-in-Time Recovery (PITR)</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-ARCHIVING-WAL">26.3.1. Setting Up WAL Archiving</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-BASE-BACKUP">26.3.2. Making a Base Backup</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP">26.3.3. Making a Base Backup Using the Low Level API</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-PITR-RECOVERY">26.3.4. Recovering Using a Continuous Archive Backup</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-TIMELINES">26.3.5. Timelines</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#BACKUP-TIPS">26.3.6. Tips and Examples</a></span></dt><dt><span class="sect2"><a href="continuous-archiving.html#CONTINUOUS-ARCHIVING-CAVEATS">26.3.7. Caveats</a></span></dt></dl></div><a id="id-1.6.13.7.2" class="indexterm"></a><a id="id-1.6.13.7.3" class="indexterm"></a><a id="id-1.6.13.7.4" class="indexterm"></a><p>
+ At all times, <span class="productname">PostgreSQL</span> maintains a
+ <em class="firstterm">write ahead log</em> (WAL) in the <code class="filename">pg_wal/</code>
+ subdirectory of the cluster's data directory. The log records
+ every change made to the database's data files. This log exists
+ primarily for crash-safety purposes: if the system crashes, the
+ database can be restored to consistency by <span class="quote">“<span class="quote">replaying</span>”</span> the
+ log entries made since the last checkpoint. However, the existence
+ of the log makes it possible to use a third strategy for backing up
+ databases: we can combine a file-system-level backup with backup of
+ the WAL files. If recovery is needed, we restore the file system backup and
+ then replay from the backed-up WAL files to bring the system to a
+ current state. This approach is more complex to administer than
+ either of the previous approaches, but it has some significant
+ benefits:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ We do not need a perfectly consistent file system backup as the starting point.
+ Any internal inconsistency in the backup will be corrected by log
+ replay (this is not significantly different from what happens during
+ crash recovery). So we do not need a file system snapshot capability,
+ just <span class="application">tar</span> or a similar archiving tool.
+ </p></li><li class="listitem"><p>
+ Since we can combine an indefinitely long sequence of WAL files
+ for replay, continuous backup can be achieved simply by continuing to archive
+ the WAL files. This is particularly valuable for large databases, where
+ it might not be convenient to take a full backup frequently.
+ </p></li><li class="listitem"><p>
+ It is not necessary to replay the WAL entries all the
+ way to the end. We could stop the replay at any point and have a
+ consistent snapshot of the database as it was at that time. Thus,
+ this technique supports <em class="firstterm">point-in-time recovery</em>: it is
+ possible to restore the database to its state at any time since your base
+ backup was taken.
+ </p></li><li class="listitem"><p>
+ If we continuously feed the series of WAL files to another
+ machine that has been loaded with the same base backup file, we
+ have a <em class="firstterm">warm standby</em> system: at any point we can bring up
+ the second machine and it will have a nearly-current copy of the
+ database.
+ </p></li></ul></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="application">pg_dump</span> and
+ <span class="application">pg_dumpall</span> do not produce file-system-level
+ backups and cannot be used as part of a continuous-archiving solution.
+ Such dumps are <span class="emphasis"><em>logical</em></span> and do not contain enough
+ information to be used by WAL replay.
+ </p></div><p>
+ As with the plain file-system-backup technique, this method can only
+ support restoration of an entire database cluster, not a subset.
+ Also, it requires a lot of archival storage: the base backup might be bulky,
+ and a busy system will generate many megabytes of WAL traffic that
+ have to be archived. Still, it is the preferred backup technique in
+ many situations where high reliability is needed.
+ </p><p>
+ To recover successfully using continuous archiving (also called
+ <span class="quote">“<span class="quote">online backup</span>”</span> by many database vendors), you need a continuous
+ sequence of archived WAL files that extends back at least as far as the
+ start time of your backup. So to get started, you should set up and test
+ your procedure for archiving WAL files <span class="emphasis"><em>before</em></span> you take your
+ first base backup. Accordingly, we first discuss the mechanics of
+ archiving WAL files.
+ </p><div class="sect2" id="BACKUP-ARCHIVING-WAL"><div class="titlepage"><div><div><h3 class="title">26.3.1. Setting Up WAL Archiving</h3></div></div></div><p>
+ In an abstract sense, a running <span class="productname">PostgreSQL</span> system
+ produces an indefinitely long sequence of WAL records. The system
+ physically divides this sequence into WAL <em class="firstterm">segment
+ files</em>, which are normally 16MB apiece (although the segment size
+ can be altered during <span class="application">initdb</span>). The segment
+ files are given numeric names that reflect their position in the
+ abstract WAL sequence. When not using WAL archiving, the system
+ normally creates just a few segment files and then
+ <span class="quote">“<span class="quote">recycles</span>”</span> them by renaming no-longer-needed segment files
+ to higher segment numbers. It's assumed that segment files whose
+ contents precede the last checkpoint are no longer of
+ interest and can be recycled.
+ </p><p>
+ When archiving WAL data, we need to capture the contents of each segment
+ file once it is filled, and save that data somewhere before the segment
+ file is recycled for reuse. Depending on the application and the
+ available hardware, there could be many different ways of <span class="quote">“<span class="quote">saving
+ the data somewhere</span>”</span>: we could copy the segment files to an NFS-mounted
+ directory on another machine, write them onto a tape drive (ensuring that
+ you have a way of identifying the original name of each file), or batch
+ them together and burn them onto CDs, or something else entirely. To
+ provide the database administrator with flexibility,
+ <span class="productname">PostgreSQL</span> tries not to make any assumptions about how
+ the archiving will be done. Instead, <span class="productname">PostgreSQL</span> lets
+ the administrator specify a shell command or an archive library to be executed to copy a
+ completed segment file to wherever it needs to go. This could be as simple
+ as a shell command that uses <code class="literal">cp</code>, or it could invoke a
+ complex C function — it's all up to you.
+ </p><p>
+ To enable WAL archiving, set the <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a>
+ configuration parameter to <code class="literal">replica</code> or higher,
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a> to <code class="literal">on</code>,
+ specify the shell command to use in the <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> configuration parameter
+ or specify the library to use in the <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> configuration parameter. In practice
+ these settings will always be placed in the
+ <code class="filename">postgresql.conf</code> file.
+ </p><p>
+ In <code class="varname">archive_command</code>,
+ <code class="literal">%p</code> is replaced by the path name of the file to
+ archive, while <code class="literal">%f</code> is replaced by only the file name.
+ (The path name is relative to the current working directory,
+ i.e., the cluster's data directory.)
+ Use <code class="literal">%%</code> if you need to embed an actual <code class="literal">%</code>
+ character in the command. The simplest useful command is something
+ like:
+</p><pre class="programlisting">
+archive_command = 'test ! -f /mnt/server/archivedir/%f &amp;&amp; cp %p /mnt/server/archivedir/%f' # Unix
+archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"' # Windows
+</pre><p>
+ which will copy archivable WAL segments to the directory
+ <code class="filename">/mnt/server/archivedir</code>. (This is an example, not a
+ recommendation, and might not work on all platforms.) After the
+ <code class="literal">%p</code> and <code class="literal">%f</code> parameters have been replaced,
+ the actual command executed might look like this:
+</p><pre class="programlisting">
+test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065
+</pre><p>
+ A similar command will be generated for each new file to be archived.
+ </p><p>
+ The archive command will be executed under the ownership of the same
+ user that the <span class="productname">PostgreSQL</span> server is running as. Since
+ the series of WAL files being archived contains effectively everything
+ in your database, you will want to be sure that the archived data is
+ protected from prying eyes; for example, archive into a directory that
+ does not have group or world read access.
+ </p><p>
+ It is important that the archive command return zero exit status if and
+ only if it succeeds. Upon getting a zero result,
+ <span class="productname">PostgreSQL</span> will assume that the file has been
+ successfully archived, and will remove or recycle it. However, a nonzero
+ status tells <span class="productname">PostgreSQL</span> that the file was not archived;
+ it will try again periodically until it succeeds.
+ </p><p>
+ Another way to archive is to use a custom archive module as the
+ <code class="varname">archive_library</code>. Since such modules are written in
+ <code class="literal">C</code>, creating your own may require considerably more effort
+ than writing a shell command. However, archive modules can be more
+ performant than archiving via shell, and they will have access to many
+ useful server resources. For more information about archive modules, see
+ <a class="xref" href="archive-modules.html" title="Chapter 51. Archive Modules">Chapter 51</a>.
+ </p><p>
+ When the archive command is terminated by a signal (other than
+ <span class="systemitem">SIGTERM</span> that is used as part of a server
+ shutdown) or an error by the shell with an exit status greater than
+ 125 (such as command not found), or if the archive function emits an
+ <code class="literal">ERROR</code> or <code class="literal">FATAL</code>, the archiver process
+ aborts and gets restarted by the postmaster. In such cases, the failure is
+ not reported in <a class="xref" href="monitoring-stats.html#PG-STAT-ARCHIVER-VIEW" title="Table 28.22. pg_stat_archiver View">pg_stat_archiver</a>.
+ </p><p>
+ Archive commands and libraries should generally be designed to refuse to overwrite
+ any pre-existing archive file. This is an important safety feature to
+ preserve the integrity of your archive in case of administrator error
+ (such as sending the output of two different servers to the same archive
+ directory).
+ </p><p>
+ It is advisable to test your proposed archive command or library to ensure that it
+ indeed does not overwrite an existing file, <span class="emphasis"><em>and that it returns
+ nonzero status or <code class="literal">false</code>, respectively, in this case</em></span>.
+ The example command above for Unix ensures this by including a separate
+ <code class="command">test</code> step. On some Unix platforms, <code class="command">cp</code> has
+ switches such as <code class="option">-i</code> that can be used to do the same thing
+ less verbosely, but you should not rely on these without verifying that
+ the right exit status is returned. (In particular, GNU <code class="command">cp</code>
+ will return status zero when <code class="option">-i</code> is used and the target file
+ already exists, which is <span class="emphasis"><em>not</em></span> the desired behavior.)
+ </p><p>
+ While designing your archiving setup, consider what will happen if
+ the archive command or library fails repeatedly because some aspect requires
+ operator intervention or the archive runs out of space. For example, this
+ could occur if you write to tape without an autochanger; when the tape
+ fills, nothing further can be archived until the tape is swapped.
+ You should ensure that any error condition or request to a human operator
+ is reported appropriately so that the situation can be
+ resolved reasonably quickly. The <code class="filename">pg_wal/</code> directory will
+ continue to fill with WAL segment files until the situation is resolved.
+ (If the file system containing <code class="filename">pg_wal/</code> fills up,
+ <span class="productname">PostgreSQL</span> will do a PANIC shutdown. No committed
+ transactions will be lost, but the database will remain offline until
+ you free some space.)
+ </p><p>
+ The speed of the archive command or library is unimportant as long as it can keep up
+ with the average rate at which your server generates WAL data. Normal
+ operation continues even if the archiving process falls a little behind.
+ If archiving falls significantly behind, this will increase the amount of
+ data that would be lost in the event of a disaster. It will also mean that
+ the <code class="filename">pg_wal/</code> directory will contain large numbers of
+ not-yet-archived segment files, which could eventually exceed available
+ disk space. You are advised to monitor the archiving process to ensure that
+ it is working as you intend.
+ </p><p>
+ In writing your archive command or library, you should assume that the file names to
+ be archived can be up to 64 characters long and can contain any
+ combination of ASCII letters, digits, and dots. It is not necessary to
+ preserve the original relative path (<code class="literal">%p</code>) but it is necessary to
+ preserve the file name (<code class="literal">%f</code>).
+ </p><p>
+ Note that although WAL archiving will allow you to restore any
+ modifications made to the data in your <span class="productname">PostgreSQL</span> database,
+ it will not restore changes made to configuration files (that is,
+ <code class="filename">postgresql.conf</code>, <code class="filename">pg_hba.conf</code> and
+ <code class="filename">pg_ident.conf</code>), since those are edited manually rather
+ 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
+ <a class="xref" href="runtime-config-file-locations.html" title="20.2. File Locations">Section 20.2</a> for how to relocate the
+ configuration files.
+ </p><p>
+ The archive command or function is only invoked on completed WAL segments. Hence,
+ if your server generates only 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 recording in archive storage. To put
+ a limit on how old unarchived data can be, you can set
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> 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
+ short <code class="varname">archive_timeout</code> — it will bloat your archive
+ storage. <code class="varname">archive_timeout</code> settings of a minute or so are
+ usually reasonable.
+ </p><p>
+ Also, you can force a segment switch manually with
+ <code class="function">pg_switch_wal</code> 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 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.89. Backup Control Functions">Table 9.89</a>.
+ </p><p>
+ When <code class="varname">wal_level</code> is <code class="literal">minimal</code> some SQL commands
+ are optimized to avoid WAL logging, as described in <a class="xref" href="populate.html#POPULATE-PITR" title="14.4.7. Disable WAL Archival and Streaming Replication">Section 14.4.7</a>. 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, <code class="varname">wal_level</code> can only be changed at
+ server start. However, <code class="varname">archive_command</code> and <code class="varname">archive_library</code> can be changed with a
+ configuration file reload. If you are archiving via shell and wish to
+ temporarily stop archiving,
+ one way to do it is to set <code class="varname">archive_command</code> to the empty
+ string (<code class="literal">''</code>).
+ This will cause WAL files to accumulate in <code class="filename">pg_wal/</code> until a
+ working <code class="varname">archive_command</code> is re-established.
+ </p></div><div class="sect2" id="BACKUP-BASE-BACKUP"><div class="titlepage"><div><div><h3 class="title">26.3.2. Making a Base Backup</h3></div></div></div><p>
+ The easiest way to perform a base backup is to use the
+ <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a> tool. It can create
+ a base backup either as regular files or as a tar archive. If more
+ flexibility than <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a> can provide is
+ required, you can also make a base backup using the low level API
+ (see <a class="xref" href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP" title="26.3.3. Making a Base Backup Using the Low Level API">Section 26.3.3</a>).
+ </p><p>
+ It is not necessary to be concerned about the amount of time it takes
+ to make a base backup. However, if you normally run the
+ server with <code class="varname">full_page_writes</code> disabled, you might notice a drop
+ in performance while the backup runs since <code class="varname">full_page_writes</code> is
+ effectively forced on during backup mode.
+ </p><p>
+ To make use of the backup, you will need to keep all the WAL
+ segment files generated during and after the file system backup.
+ To aid you in doing this, the base backup process
+ creates a <em class="firstterm">backup history file</em> that is immediately
+ stored into the WAL archive area. This file is named after the first
+ WAL segment file that you need for the file system backup.
+ For example, if the starting WAL file is
+ <code class="literal">0000000100001234000055CD</code> the backup history file will be
+ named something like
+ <code class="literal">0000000100001234000055CD.007C9330.backup</code>. (The second
+ part of the file name stands for an exact position within the WAL
+ file, and can ordinarily be ignored.) Once you have safely archived
+ the file system backup and the WAL segment files used during the
+ backup (as specified in the backup history file), all archived WAL
+ segments with names numerically less are no longer needed to recover
+ the file system backup and can be deleted. However, you should
+ consider keeping several backup sets to be absolutely certain that
+ you can recover your data.
+ </p><p>
+ The backup history file is just a small text file. It contains the
+ label string you gave to <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a>, 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
+ restore.
+ </p><p>
+ Since you have to keep around all the archived WAL files back to your
+ last base backup, the interval between base backups should usually be
+ chosen based on how much storage you want to expend on archived WAL
+ files. You should also consider how long you are prepared to spend
+ recovering, if recovery should be necessary — the system will have to
+ replay all those WAL segments, and that could take awhile if it has
+ been a long time since the last base backup.
+ </p></div><div class="sect2" id="BACKUP-LOWLEVEL-BASE-BACKUP"><div class="titlepage"><div><div><h3 class="title">26.3.3. Making a Base Backup Using the Low Level API</h3></div></div></div><p>
+ The procedure for making a base backup using the low level
+ APIs contains a few more steps than
+ the <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a> 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.
+ </p><p>
+ Multiple backups are able to be run concurrently (both those
+ started using this backup API and those started using
+ <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a>).
+ </p><p>
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Ensure that WAL archiving is enabled and working.
+ </p></li><li class="listitem"><p>
+ Connect to the server (it does not matter which database) as a user with
+ rights to run <code class="function">pg_backup_start</code> (superuser,
+ or a user who has been granted <code class="literal">EXECUTE</code> on the
+ function) and issue the command:
+</p><pre class="programlisting">
+SELECT pg_backup_start(label =&gt; 'label', fast =&gt; false);
+</pre><p>
+ where <code class="literal">label</code> is any string you want to use to uniquely
+ identify this backup operation. The connection
+ calling <code class="function">pg_backup_start</code> must be maintained until the end of
+ the backup, or the backup will be automatically aborted.
+ </p><p>
+ Online backups are always started at the beginning of a checkpoint.
+ By default, <code class="function">pg_backup_start</code> will wait for the next
+ regularly scheduled checkpoint to complete, which may take a long time (see the
+ configuration parameters <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-TIMEOUT">checkpoint_timeout</a> and
+ <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-COMPLETION-TARGET">checkpoint_completion_target</a>). This is
+ usually preferable as it minimizes the impact on the running system. If you
+ want to start the backup as soon as possible, pass <code class="literal">true</code> as
+ the second parameter to <code class="function">pg_backup_start</code> and it will
+ request an immediate checkpoint, which will finish as fast as possible using
+ as much I/O as possible.
+ </p></li><li class="listitem"><p>
+ Perform the backup, using any convenient file-system-backup tool
+ such as <span class="application">tar</span> or <span class="application">cpio</span> (not
+ <span class="application">pg_dump</span> or
+ <span class="application">pg_dumpall</span>). It is neither
+ necessary nor desirable to stop normal operation of the database
+ while you do this. See
+ <a class="xref" href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP-DATA" title="26.3.3.1. Backing Up the Data Directory">Section 26.3.3.1</a> for things to
+ consider during this backup.
+ </p></li><li class="listitem"><p>
+ In the same connection as before, issue the command:
+</p><pre class="programlisting">
+SELECT * FROM pg_backup_stop(wait_for_archive =&gt; true);
+</pre><p>
+ This terminates backup mode. On a primary, it also performs an automatic
+ switch to the next WAL segment. On a standby, it is not possible to
+ automatically switch WAL segments, so you may wish to run
+ <code class="function">pg_switch_wal</code> on the primary to perform a manual
+ switch. The reason for the switch is to arrange for
+ the last WAL segment file written during the backup interval to be
+ ready to archive.
+ </p><p>
+ <code class="function">pg_backup_stop</code> will return one row with three
+ values. The second of these fields should be written to a file named
+ <code class="filename">backup_label</code> in the root directory of the backup. The
+ third field should be written to a file named
+ <code class="filename">tablespace_map</code> unless the field is empty. These files are
+ vital to the backup working and must be written byte for byte without
+ modification, which may require opening the file in binary mode.
+ </p></li><li class="listitem"><p>
+ Once the WAL segment files active during the backup are archived, you are
+ done. The file identified by <code class="function">pg_backup_stop</code>'s first return
+ value is the last segment that is required to form a complete set of
+ backup files. On a primary, if <code class="varname">archive_mode</code> is enabled and the
+ <code class="literal">wait_for_archive</code> parameter is <code class="literal">true</code>,
+ <code class="function">pg_backup_stop</code> does not return until the last segment has
+ been archived.
+ On a standby, <code class="varname">archive_mode</code> must be <code class="literal">always</code> in order
+ for <code class="function">pg_backup_stop</code> to wait.
+ Archiving of these files happens automatically since you have
+ already configured <code class="varname">archive_command</code> or <code class="varname">archive_library</code>.
+ In most cases this happens quickly, but you are advised to monitor your
+ archive system to ensure there are no delays.
+ If the archive process has fallen behind because of failures of the
+ archive command or library, it will keep retrying
+ until the archive succeeds and the backup is complete.
+ If you wish to place a time limit on the execution of
+ <code class="function">pg_backup_stop</code>, set an appropriate
+ <code class="varname">statement_timeout</code> value, but make note that if
+ <code class="function">pg_backup_stop</code> terminates because of this your backup
+ may not be valid.
+ </p><p>
+ If the backup process monitors and ensures that all WAL segment files
+ required for the backup are successfully archived then the
+ <code class="literal">wait_for_archive</code> parameter (which defaults to true) can be set
+ to false to have
+ <code class="function">pg_backup_stop</code> return as soon as the stop backup record is
+ written to the WAL. By default, <code class="function">pg_backup_stop</code> will wait
+ until all WAL has been archived, which can take some time. This option
+ must be used with caution: if WAL archiving is not monitored correctly
+ then the backup might not include all of the WAL files and will
+ therefore be incomplete and not able to be restored.
+ </p></li></ol></div><p>
+ </p><div class="sect3" id="BACKUP-LOWLEVEL-BASE-BACKUP-DATA"><div class="titlepage"><div><div><h4 class="title">26.3.3.1. Backing Up the Data Directory</h4></div></div></div><p>
+ Some file system backup tools emit warnings or errors
+ if the files they are trying to copy change while the copy proceeds.
+ When taking a base backup of an active database, this situation is normal
+ and not an error. However, you need to ensure that you can distinguish
+ complaints of this sort from real errors. For example, some versions
+ of <span class="application">rsync</span> return a separate exit code for
+ <span class="quote">“<span class="quote">vanished source files</span>”</span>, and you can write a driver script to
+ accept this exit code as a non-error case. Also, some versions of
+ GNU <span class="application">tar</span> return an error code indistinguishable from
+ a fatal error if a file was truncated while <span class="application">tar</span> was
+ copying it. Fortunately, GNU <span class="application">tar</span> versions 1.16 and
+ later exit with 1 if a file was changed during the backup,
+ and 2 for other errors. With GNU <span class="application">tar</span> version 1.23 and
+ later, you can use the warning options <code class="literal">--warning=no-file-changed
+ --warning=no-file-removed</code> to hide the related warning messages.
+ </p><p>
+ Be certain that your backup includes all of the files under
+ the database cluster directory (e.g., <code class="filename">/usr/local/pgsql/data</code>).
+ If you are using tablespaces that do not reside underneath this directory,
+ be careful to include them as well (and be sure that your backup
+ archives symbolic links as links, otherwise the restore will corrupt
+ your tablespaces).
+ </p><p>
+ You should, however, omit from the backup the files within the
+ cluster's <code class="filename">pg_wal/</code> subdirectory. This
+ slight adjustment is worthwhile because it reduces the risk
+ of mistakes when restoring. This is easy to arrange if
+ <code class="filename">pg_wal/</code> is a symbolic link pointing to someplace outside
+ the cluster directory, which is a common setup anyway for performance
+ reasons. You might also want to exclude <code class="filename">postmaster.pid</code>
+ and <code class="filename">postmaster.opts</code>, which record information
+ about the running <span class="application">postmaster</span>, not about the
+ <span class="application">postmaster</span> which will eventually use this backup.
+ (These files can confuse <span class="application">pg_ctl</span>.)
+ </p><p>
+ It is often a good idea to also omit from the backup the files
+ within the cluster's <code class="filename">pg_replslot/</code> directory, so that
+ replication slots that exist on the primary do not become part of the
+ backup. Otherwise, the subsequent use of the backup to create a standby
+ may result in indefinite retention of WAL files on the standby, and
+ possibly bloat on the primary if hot standby feedback is enabled, because
+ the clients that are using those replication slots will still be connecting
+ to and updating the slots on the primary, not the standby. Even if the
+ backup is only intended for use in creating a new primary, copying the
+ replication slots isn't expected to be particularly useful, since the
+ contents of those slots will likely be badly out of date by the time
+ the new primary comes on line.
+ </p><p>
+ The contents of the directories <code class="filename">pg_dynshmem/</code>,
+ <code class="filename">pg_notify/</code>, <code class="filename">pg_serial/</code>,
+ <code class="filename">pg_snapshots/</code>, <code class="filename">pg_stat_tmp/</code>,
+ and <code class="filename">pg_subtrans/</code> (but not the directories themselves) can be
+ omitted from the backup as they will be initialized on postmaster startup.
+ </p><p>
+ Any file or directory beginning with <code class="filename">pgsql_tmp</code> can be
+ omitted from the backup. These files are removed on postmaster start and
+ the directories will be recreated as needed.
+ </p><p>
+ <code class="filename">pg_internal.init</code> files can be omitted from the
+ backup whenever a file of that name is found. These files contain
+ relation cache data that is always rebuilt when recovering.
+ </p><p>
+ The backup label
+ file includes the label string you gave to <code class="function">pg_backup_start</code>,
+ as well as the time at which <code class="function">pg_backup_start</code> was run, and
+ the name of the starting WAL file. In case of confusion it is therefore
+ possible to look inside a backup file and determine exactly which
+ backup session the dump file came from. The tablespace map file includes
+ the symbolic link names as they exist in the directory
+ <code class="filename">pg_tblspc/</code> and the full path of each symbolic link.
+ These files are not merely for your information; their presence and
+ contents are critical to the proper operation of the system's recovery
+ process.
+ </p><p>
+ It is also possible to make a backup while the server is
+ stopped. In this case, you obviously cannot use
+ <code class="function">pg_backup_start</code> or <code class="function">pg_backup_stop</code>, and
+ you will therefore be left to your own devices to keep track of which
+ backup is which and how far back the associated WAL files go.
+ It is generally better to follow the continuous archiving procedure above.
+ </p></div></div><div class="sect2" id="BACKUP-PITR-RECOVERY"><div class="titlepage"><div><div><h3 class="title">26.3.4. Recovering Using a Continuous Archive Backup</h3></div></div></div><p>
+ Okay, the worst has happened and you need to recover from your backup.
+ Here is the procedure:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Stop the server, if it's running.
+ </p></li><li class="listitem"><p>
+ If you have the space to do so,
+ copy the whole cluster data directory and any tablespaces to a temporary
+ location in case you need them later. Note that this precaution will
+ require that you have enough free space on your system to hold two
+ copies of your existing database. If you do not have enough space,
+ you should at least save the contents of the cluster's <code class="filename">pg_wal</code>
+ subdirectory, as it might contain logs which
+ were not archived before the system went down.
+ </p></li><li class="listitem"><p>
+ Remove all existing files and subdirectories under the cluster data
+ directory and under the root directories of any tablespaces you are using.
+ </p></li><li class="listitem"><p>
+ Restore the database files from your file system backup. Be sure that they
+ are restored with the right ownership (the database system user, not
+ <code class="literal">root</code>!) and with the right permissions. If you are using
+ tablespaces,
+ you should verify that the symbolic links in <code class="filename">pg_tblspc/</code>
+ were correctly restored.
+ </p></li><li class="listitem"><p>
+ Remove any files present in <code class="filename">pg_wal/</code>; these came from the
+ file system backup and are therefore probably obsolete rather than current.
+ If you didn't archive <code class="filename">pg_wal/</code> at all, then recreate
+ it with proper permissions,
+ being careful to ensure that you re-establish it as a symbolic link
+ if you had it set up that way before.
+ </p></li><li class="listitem"><p>
+ If you have unarchived WAL segment files that you saved in step 2,
+ copy them into <code class="filename">pg_wal/</code>. (It is best to copy them,
+ not move them, so you still have the unmodified files if a
+ problem occurs and you have to start over.)
+ </p></li><li class="listitem"><p>
+ Set recovery configuration settings in
+ <code class="filename">postgresql.conf</code> (see <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY" title="20.5.5. Archive Recovery">Section 20.5.5</a>) and create a file
+ <code class="filename">recovery.signal</code> in the cluster
+ data directory. You might
+ also want to temporarily modify <code class="filename">pg_hba.conf</code> to prevent
+ ordinary users from connecting until you are sure the recovery was successful.
+ </p></li><li class="listitem"><p>
+ Start the server. The server will go into recovery mode and
+ proceed to read through the archived WAL files it needs. Should the
+ recovery be terminated because of an external error, the server can
+ simply be restarted and it will continue recovery. Upon completion
+ of the recovery process, the server will remove
+ <code class="filename">recovery.signal</code> (to prevent
+ accidentally re-entering recovery mode later) and then
+ commence normal database operations.
+ </p></li><li class="listitem"><p>
+ Inspect the contents of the database to ensure you have recovered to
+ the desired state. If not, return to step 1. If all is well,
+ allow your users to connect by restoring <code class="filename">pg_hba.conf</code> to normal.
+ </p></li></ol></div><p>
+ </p><p>
+ The key part of all this is to set up a recovery configuration that
+ describes how you want to recover and how far the recovery should
+ run. The one thing that you absolutely must specify is the <code class="varname">restore_command</code>,
+ which tells <span class="productname">PostgreSQL</span> how to retrieve archived
+ WAL file segments. Like the <code class="varname">archive_command</code>, this is
+ a shell command string. It can contain <code class="literal">%f</code>, which is
+ replaced by the name of the desired log file, and <code class="literal">%p</code>,
+ which is replaced by the path name to copy the log file to.
+ (The path name is relative to the current working directory,
+ i.e., the cluster's data directory.)
+ Write <code class="literal">%%</code> if you need to embed an actual <code class="literal">%</code>
+ character in the command. The simplest useful command is
+ something like:
+</p><pre class="programlisting">
+restore_command = 'cp /mnt/server/archivedir/%f %p'
+</pre><p>
+ which will copy previously archived WAL segments from the directory
+ <code class="filename">/mnt/server/archivedir</code>. Of course, you can use something
+ much more complicated, perhaps even a shell script that requests the
+ operator to mount an appropriate tape.
+ </p><p>
+ It is important that the command return nonzero exit status on failure.
+ The command <span class="emphasis"><em>will</em></span> be called requesting files that are not
+ present in the archive; it must return nonzero when so asked. This is not
+ an error condition. An exception is that if the command was terminated by
+ a signal (other than <span class="systemitem">SIGTERM</span>, which is used as
+ part of a database server shutdown) or an error by the shell (such as
+ command not found), then recovery will abort and the server will not start
+ up.
+ </p><p>
+ Not all of the requested files will be WAL segment
+ files; you should also expect requests for files with a suffix of
+ <code class="literal">.history</code>. Also be aware that
+ the base name of the <code class="literal">%p</code> path will be different from
+ <code class="literal">%f</code>; do not expect them to be interchangeable.
+ </p><p>
+ WAL segments that cannot be found in the archive will be sought in
+ <code class="filename">pg_wal/</code>; this allows use of recent un-archived segments.
+ However, segments that are available from the archive will be used in
+ preference to files in <code class="filename">pg_wal/</code>.
+ </p><p>
+ Normally, recovery will proceed through all available WAL segments,
+ thereby restoring the database to the current point in time (or as
+ close as possible given the available WAL segments). Therefore, a normal
+ recovery will end with a <span class="quote">“<span class="quote">file not found</span>”</span> message, the exact text
+ of the error message depending upon your choice of
+ <code class="varname">restore_command</code>. You may also see an error message
+ at the start of recovery for a file named something like
+ <code class="filename">00000001.history</code>. This is also normal and does not
+ indicate a problem in simple recovery situations; see
+ <a class="xref" href="continuous-archiving.html#BACKUP-TIMELINES" title="26.3.5. Timelines">Section 26.3.5</a> for discussion.
+ </p><p>
+ If you want to recover to some previous point in time (say, right before
+ the junior DBA dropped your main transaction table), just specify the
+ required <a class="link" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="20.5.6. Recovery Target">stopping point</a>. You can specify
+ the stop point, known as the <span class="quote">“<span class="quote">recovery target</span>”</span>, either by
+ date/time, named restore point or by completion of a specific transaction
+ ID. As of this writing only the date/time and named restore point options
+ are very usable, since there are no tools to help you identify with any
+ accuracy which transaction ID to use.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The stop point must be after the ending time of the base backup, i.e.,
+ the end time of <code class="function">pg_backup_stop</code>. You cannot use a base backup
+ to recover to a time when that backup was in progress. (To
+ recover to such a time, you must go back to your previous base backup
+ and roll forward from there.)
+ </p></div><p>
+ If recovery finds corrupted WAL data, recovery will
+ halt at that point and the server will not start. In such a case the
+ recovery process could be re-run from the beginning, specifying a
+ <span class="quote">“<span class="quote">recovery target</span>”</span> before the point of corruption so that recovery
+ can complete normally.
+ If recovery fails for an external reason, such as a system crash or
+ if the WAL archive has become inaccessible, then the recovery can simply
+ be restarted and it will restart almost from where it failed.
+ Recovery restart works much like checkpointing in normal operation:
+ the server periodically forces all its state to disk, and then updates
+ the <code class="filename">pg_control</code> file to indicate that the already-processed
+ WAL data need not be scanned again.
+ </p></div><div class="sect2" id="BACKUP-TIMELINES"><div class="titlepage"><div><div><h3 class="title">26.3.5. Timelines</h3></div></div></div><a id="id-1.6.13.7.13.2" class="indexterm"></a><p>
+ The ability to restore the database to a previous point in time creates
+ some complexities that are akin to science-fiction stories about time
+ travel and parallel universes. For example, in the original history of the database,
+ suppose you dropped a critical table at 5:15PM on Tuesday evening, but
+ didn't realize your mistake until Wednesday noon.
+ Unfazed, you get out your backup, restore to the point-in-time 5:14PM
+ Tuesday evening, and are up and running. In <span class="emphasis"><em>this</em></span> history of
+ the database universe, you never dropped the table. But suppose
+ you later realize this wasn't such a great idea, and would like
+ to return to sometime Wednesday morning in the original history.
+ You won't be able
+ to if, while your database was up-and-running, it overwrote some of the
+ WAL segment files that led up to the time you now wish you
+ could get back to. Thus, to avoid this, you need to distinguish the series of
+ WAL records generated after you've done a point-in-time recovery from
+ those that were generated in the original database history.
+ </p><p>
+ To deal with this problem, <span class="productname">PostgreSQL</span> has a notion
+ of <em class="firstterm">timelines</em>. Whenever an archive recovery completes,
+ a new timeline is created to identify the series of WAL records
+ generated after that recovery. The timeline
+ ID number is part of WAL segment file names so a new timeline does
+ not overwrite the WAL data generated by previous timelines. It is
+ in fact possible to archive many different timelines. While that might
+ seem like a useless feature, it's often a lifesaver. Consider the
+ situation where you aren't quite sure what point-in-time to recover to,
+ and so have to do several point-in-time recoveries by trial and error
+ until you find the best place to branch off from the old history. Without
+ timelines this process would soon generate an unmanageable mess. With
+ timelines, you can recover to <span class="emphasis"><em>any</em></span> prior state, including
+ states in timeline branches that you abandoned earlier.
+ </p><p>
+ Every time a new timeline is created, <span class="productname">PostgreSQL</span> creates
+ a <span class="quote">“<span class="quote">timeline history</span>”</span> file that shows which timeline it branched
+ off from and when. These history files are necessary to allow the system
+ to pick the right WAL segment files when recovering from an archive that
+ contains multiple timelines. Therefore, they are archived into the WAL
+ archive area just like WAL segment files. The history files are just
+ small text files, so it's cheap and appropriate to keep them around
+ indefinitely (unlike the segment files which are large). You can, if
+ you like, add comments to a history file to record your own notes about
+ how and why this particular timeline was created. Such comments will be
+ especially valuable when you have a thicket of different timelines as
+ a result of experimentation.
+ </p><p>
+ The default behavior of recovery is to recover to the latest timeline found
+ in the archive. If you wish to recover to the timeline that was current
+ when the base backup was taken or into a specific child timeline (that
+ is, you want to return to some state that was itself generated after a
+ recovery attempt), you need to specify <code class="literal">current</code> or the
+ target timeline ID in <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-TIMELINE">recovery_target_timeline</a>. You
+ cannot recover into timelines that branched off earlier than the base backup.
+ </p></div><div class="sect2" id="BACKUP-TIPS"><div class="titlepage"><div><div><h3 class="title">26.3.6. Tips and Examples</h3></div></div></div><p>
+ Some tips for configuring continuous archiving are given here.
+ </p><div class="sect3" id="BACKUP-STANDALONE"><div class="titlepage"><div><div><h4 class="title">26.3.6.1. Standalone Hot Backups</h4></div></div></div><p>
+ It is possible to use <span class="productname">PostgreSQL</span>'s backup facilities to
+ produce standalone hot backups. These are backups that cannot be used
+ for point-in-time recovery, yet are typically much faster to backup and
+ restore than <span class="application">pg_dump</span> dumps. (They are also much larger
+ than <span class="application">pg_dump</span> dumps, so in some cases the speed advantage
+ might be negated.)
+ </p><p>
+ As with base backups, the easiest way to produce a standalone
+ hot backup is to use the <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a>
+ tool. If you include the <code class="literal">-X</code> 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
+ required to restore the backup.
+ </p></div><div class="sect3" id="COMPRESSED-ARCHIVE-LOGS"><div class="titlepage"><div><div><h4 class="title">26.3.6.2. Compressed Archive Logs</h4></div></div></div><p>
+ If archive storage size is a concern, you can use
+ <span class="application">gzip</span> to compress the archive files:
+</p><pre class="programlisting">
+archive_command = 'gzip &lt; %p &gt; /mnt/server/archivedir/%f.gz'
+</pre><p>
+ You will then need to use <span class="application">gunzip</span> during recovery:
+</p><pre class="programlisting">
+restore_command = 'gunzip &lt; /mnt/server/archivedir/%f.gz &gt; %p'
+</pre><p>
+ </p></div><div class="sect3" id="BACKUP-SCRIPTS"><div class="titlepage"><div><div><h4 class="title">26.3.6.3. <code class="varname">archive_command</code> Scripts</h4></div></div></div><p>
+ Many people choose to use scripts to define their
+ <code class="varname">archive_command</code>, so that their
+ <code class="filename">postgresql.conf</code> entry looks very simple:
+</p><pre class="programlisting">
+archive_command = 'local_backup_script.sh "%p" "%f"'
+</pre><p>
+ Using a separate script file is advisable any time you want to use
+ more than a single command in the archiving process.
+ This allows all complexity to be managed within the script, which
+ can be written in a popular scripting language such as
+ <span class="application">bash</span> or <span class="application">perl</span>.
+ </p><p>
+ Examples of requirements that might be solved within a script include:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Copying data to secure off-site data storage
+ </p></li><li class="listitem"><p>
+ Batching WAL files so that they are transferred every three hours,
+ rather than one at a time
+ </p></li><li class="listitem"><p>
+ Interfacing with other backup and recovery software
+ </p></li><li class="listitem"><p>
+ Interfacing with monitoring software to report errors
+ </p></li></ul></div><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ When using an <code class="varname">archive_command</code> script, it's desirable
+ to enable <a class="xref" href="runtime-config-logging.html#GUC-LOGGING-COLLECTOR">logging_collector</a>.
+ Any messages written to <span class="systemitem">stderr</span> from the script will then
+ appear in the database server log, allowing complex configurations to
+ be diagnosed easily if they fail.
+ </p></div></div></div><div class="sect2" id="CONTINUOUS-ARCHIVING-CAVEATS"><div class="titlepage"><div><div><h3 class="title">26.3.7. Caveats</h3></div></div></div><p>
+ At this writing, there are several limitations of the continuous archiving
+ technique. These will probably be fixed in future releases:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If a <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>
+ command is executed while a base backup is being taken, and then
+ the template database that the <code class="command">CREATE DATABASE</code> copied
+ is modified while the base backup is still in progress, it is
+ possible that recovery will cause those modifications to be
+ propagated into the created database as well. This is of course
+ undesirable. To avoid this risk, it is best not to modify any
+ template databases while taking a base backup.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="sql-createtablespace.html" title="CREATE TABLESPACE"><code class="command">CREATE TABLESPACE</code></a>
+ 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
+ replayed on a different machine. It can be dangerous even if the
+ log is being replayed on the same machine, but into a new data
+ directory: the replay will still overwrite the contents of the
+ original tablespace. To avoid potential gotchas of this sort,
+ the best practice is to take a new base backup after creating or
+ dropping tablespaces.
+ </p></li></ul></div><p>
+ </p><p>
+ It should also be noted that the default <acronym class="acronym">WAL</acronym>
+ format is fairly bulky since it includes many disk page snapshots.
+ These page snapshots are designed to support crash recovery, since
+ we might need to fix partially-written disk pages. Depending on
+ 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 <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a>
+ parameter. (Read the notes and warnings in <a class="xref" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Chapter 30</a>
+ 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
+ unnecessary page copies even when <code class="varname">full_page_writes</code> is
+ on. In the meantime, administrators might wish to reduce the number
+ of page snapshots included in WAL by increasing the checkpoint
+ interval parameters as much as feasible.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-file.html" title="26.2. File System Level Backup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="backup.html" title="Chapter 26. Backup and Restore">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">26.2. File System Level Backup </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 27. High Availability, Load Balancing, and Replication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-build-sql-delete.html b/doc/src/sgml/html/contrib-dblink-build-sql-delete.html
new file mode 100644
index 0000000..6dcc48a
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-build-sql-delete.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_build_sql_delete</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert" /><link rel="next" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_build_sql_delete</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-BUILD-SQL-DELETE"><div class="titlepage"></div><a id="id-1.11.7.21.22.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_build_sql_delete</span></h2><p>dblink_build_sql_delete — builds a DELETE statement using supplied values for primary
+ key field values
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_build_sql_delete(text relname,
+ int2vector primary_key_attnums,
+ integer num_primary_key_atts,
+ text[] tgt_pk_att_vals_array) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.22.5"><h2>Description</h2><p>
+ <code class="function">dblink_build_sql_delete</code> can be useful in doing selective
+ replication of a local table to a remote database. It builds an SQL
+ <code class="command">DELETE</code> command that will delete the row with the given
+ primary key values.
+ </p></div><div class="refsect1" id="id-1.11.7.21.22.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>relname</code></em></span></dt><dd><p>
+ Name of a local relation, for example <code class="literal">foo</code> or
+ <code class="literal">myschema.mytab</code>. Include double quotes if the
+ name is mixed-case or contains special characters, for
+ example <code class="literal">"FooBar"</code>; without quotes, the string
+ will be folded to lower case.
+ </p></dd><dt><span class="term"><em class="parameter"><code>primary_key_attnums</code></em></span></dt><dd><p>
+ Attribute numbers (1-based) of the primary key fields,
+ for example <code class="literal">1 2</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>num_primary_key_atts</code></em></span></dt><dd><p>
+ The number of primary key fields.
+ </p></dd><dt><span class="term"><em class="parameter"><code>tgt_pk_att_vals_array</code></em></span></dt><dd><p>
+ Values of the primary key fields to be used in the resulting
+ <code class="command">DELETE</code> command. Each field is represented in text form.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.22.7"><h2>Return Value</h2><p>Returns the requested SQL statement as text.</p></div><div class="refsect1" id="id-1.11.7.21.22.8"><h2>Notes</h2><p>
+ As of <span class="productname">PostgreSQL</span> 9.0, the attribute numbers in
+ <em class="parameter"><code>primary_key_attnums</code></em> are interpreted as logical
+ column numbers, corresponding to the column's position in
+ <code class="literal">SELECT * FROM relname</code>. Previous versions interpreted the
+ numbers as physical column positions. There is a difference if any
+ column(s) to the left of the indicated column have been dropped during
+ the lifetime of the table.
+ </p></div><div class="refsect1" id="id-1.11.7.21.22.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_build_sql_delete('"MyFoo"', '1 2', 2, '{"1", "b"}');
+ dblink_build_sql_delete
+---------------------------------------------
+ DELETE FROM "MyFoo" WHERE f1='1' AND f2='b'
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_build_sql_insert </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_build_sql_update</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-build-sql-insert.html b/doc/src/sgml/html/contrib-dblink-build-sql-insert.html
new file mode 100644
index 0000000..d1158a0
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-build-sql-insert.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_build_sql_insert</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey" /><link rel="next" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_build_sql_insert</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-BUILD-SQL-INSERT"><div class="titlepage"></div><a id="id-1.11.7.21.21.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_build_sql_insert</span></h2><p>dblink_build_sql_insert —
+ builds an INSERT statement using a local tuple, replacing the
+ primary key field values with alternative supplied values
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_build_sql_insert(text relname,
+ int2vector primary_key_attnums,
+ integer num_primary_key_atts,
+ text[] src_pk_att_vals_array,
+ text[] tgt_pk_att_vals_array) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.21.5"><h2>Description</h2><p>
+ <code class="function">dblink_build_sql_insert</code> can be useful in doing selective
+ replication of a local table to a remote database. It selects a row
+ from the local table based on primary key, and then builds an SQL
+ <code class="command">INSERT</code> command that will duplicate that row, but with
+ the primary key values replaced by the values in the last argument.
+ (To make an exact copy of the row, just specify the same values for
+ the last two arguments.)
+ </p></div><div class="refsect1" id="id-1.11.7.21.21.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>relname</code></em></span></dt><dd><p>
+ Name of a local relation, for example <code class="literal">foo</code> or
+ <code class="literal">myschema.mytab</code>. Include double quotes if the
+ name is mixed-case or contains special characters, for
+ example <code class="literal">"FooBar"</code>; without quotes, the string
+ will be folded to lower case.
+ </p></dd><dt><span class="term"><em class="parameter"><code>primary_key_attnums</code></em></span></dt><dd><p>
+ Attribute numbers (1-based) of the primary key fields,
+ for example <code class="literal">1 2</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>num_primary_key_atts</code></em></span></dt><dd><p>
+ The number of primary key fields.
+ </p></dd><dt><span class="term"><em class="parameter"><code>src_pk_att_vals_array</code></em></span></dt><dd><p>
+ Values of the primary key fields to be used to look up the
+ local tuple. Each field is represented in text form.
+ An error is thrown if there is no local row with these
+ primary key values.
+ </p></dd><dt><span class="term"><em class="parameter"><code>tgt_pk_att_vals_array</code></em></span></dt><dd><p>
+ Values of the primary key fields to be placed in the resulting
+ <code class="command">INSERT</code> command. Each field is represented in text form.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.21.7"><h2>Return Value</h2><p>Returns the requested SQL statement as text.</p></div><div class="refsect1" id="id-1.11.7.21.21.8"><h2>Notes</h2><p>
+ As of <span class="productname">PostgreSQL</span> 9.0, the attribute numbers in
+ <em class="parameter"><code>primary_key_attnums</code></em> are interpreted as logical
+ column numbers, corresponding to the column's position in
+ <code class="literal">SELECT * FROM relname</code>. Previous versions interpreted the
+ numbers as physical column positions. There is a difference if any
+ column(s) to the left of the indicated column have been dropped during
+ the lifetime of the table.
+ </p></div><div class="refsect1" id="id-1.11.7.21.21.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_build_sql_insert('foo', '1 2', 2, '{"1", "a"}', '{"1", "b''a"}');
+ dblink_build_sql_insert
+--------------------------------------------------
+ INSERT INTO foo(f1,f2,f3) VALUES('1','b''a','1')
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_get_pkey </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_build_sql_delete</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-build-sql-update.html b/doc/src/sgml/html/contrib-dblink-build-sql-update.html
new file mode 100644
index 0000000..7b8d343
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-build-sql-update.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_build_sql_update</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete" /><link rel="next" href="dict-int.html" title="F.13. dict_int" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_build_sql_update</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dict-int.html" title="F.13. dict_int">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-BUILD-SQL-UPDATE"><div class="titlepage"></div><a id="id-1.11.7.21.23.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_build_sql_update</span></h2><p>dblink_build_sql_update — builds an UPDATE statement using a local tuple, replacing
+ the primary key field values with alternative supplied values
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_build_sql_update(text relname,
+ int2vector primary_key_attnums,
+ integer num_primary_key_atts,
+ text[] src_pk_att_vals_array,
+ text[] tgt_pk_att_vals_array) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.23.5"><h2>Description</h2><p>
+ <code class="function">dblink_build_sql_update</code> can be useful in doing selective
+ replication of a local table to a remote database. It selects a row
+ from the local table based on primary key, and then builds an SQL
+ <code class="command">UPDATE</code> command that will duplicate that row, but with
+ the primary key values replaced by the values in the last argument.
+ (To make an exact copy of the row, just specify the same values for
+ the last two arguments.) The <code class="command">UPDATE</code> command always assigns
+ all fields of the row — the main difference between this and
+ <code class="function">dblink_build_sql_insert</code> is that it's assumed that
+ the target row already exists in the remote table.
+ </p></div><div class="refsect1" id="id-1.11.7.21.23.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>relname</code></em></span></dt><dd><p>
+ Name of a local relation, for example <code class="literal">foo</code> or
+ <code class="literal">myschema.mytab</code>. Include double quotes if the
+ name is mixed-case or contains special characters, for
+ example <code class="literal">"FooBar"</code>; without quotes, the string
+ will be folded to lower case.
+ </p></dd><dt><span class="term"><em class="parameter"><code>primary_key_attnums</code></em></span></dt><dd><p>
+ Attribute numbers (1-based) of the primary key fields,
+ for example <code class="literal">1 2</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>num_primary_key_atts</code></em></span></dt><dd><p>
+ The number of primary key fields.
+ </p></dd><dt><span class="term"><em class="parameter"><code>src_pk_att_vals_array</code></em></span></dt><dd><p>
+ Values of the primary key fields to be used to look up the
+ local tuple. Each field is represented in text form.
+ An error is thrown if there is no local row with these
+ primary key values.
+ </p></dd><dt><span class="term"><em class="parameter"><code>tgt_pk_att_vals_array</code></em></span></dt><dd><p>
+ Values of the primary key fields to be placed in the resulting
+ <code class="command">UPDATE</code> command. Each field is represented in text form.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.23.7"><h2>Return Value</h2><p>Returns the requested SQL statement as text.</p></div><div class="refsect1" id="id-1.11.7.21.23.8"><h2>Notes</h2><p>
+ As of <span class="productname">PostgreSQL</span> 9.0, the attribute numbers in
+ <em class="parameter"><code>primary_key_attnums</code></em> are interpreted as logical
+ column numbers, corresponding to the column's position in
+ <code class="literal">SELECT * FROM relname</code>. Previous versions interpreted the
+ numbers as physical column positions. There is a difference if any
+ column(s) to the left of the indicated column have been dropped during
+ the lifetime of the table.
+ </p></div><div class="refsect1" id="id-1.11.7.21.23.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_build_sql_update('foo', '1 2', 2, '{"1", "a"}', '{"1", "b"}');
+ dblink_build_sql_update
+-------------------------------------------------------------
+ UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b'
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-delete.html" title="dblink_build_sql_delete">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dict-int.html" title="F.13. dict_int">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_build_sql_delete </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.13. dict_int</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-cancel-query.html b/doc/src/sgml/html/contrib-dblink-cancel-query.html
new file mode 100644
index 0000000..96d6294
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-cancel-query.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_cancel_query</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-get-result.html" title="dblink_get_result" /><link rel="next" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_cancel_query</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-get-result.html" title="dblink_get_result">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-CANCEL-QUERY"><div class="titlepage"></div><a id="id-1.11.7.21.19.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_cancel_query</span></h2><p>dblink_cancel_query — cancels any active query on the named connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_cancel_query(text connname) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.19.5"><h2>Description</h2><p>
+ <code class="function">dblink_cancel_query</code> attempts to cancel any query that
+ is in progress on the named connection. Note that this is not
+ certain to succeed (since, for example, the remote query might
+ already have finished). A cancel request simply improves the
+ odds that the query will fail soon. You must still complete the
+ normal query protocol, for example by calling
+ <code class="function">dblink_get_result</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.19.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.19.7"><h2>Return Value</h2><p>
+ Returns <code class="literal">OK</code> if the cancel request has been sent, or
+ the text of an error message on failure.
+ </p></div><div class="refsect1" id="id-1.11.7.21.19.8"><h2>Examples</h2><pre class="programlisting">
+SELECT dblink_cancel_query('dtest1');
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-get-result.html" title="dblink_get_result">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-get-pkey.html" title="dblink_get_pkey">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_get_result </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_get_pkey</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-close.html b/doc/src/sgml/html/contrib-dblink-close.html
new file mode 100644
index 0000000..5263873
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-close.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_close</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-fetch.html" title="dblink_fetch" /><link rel="next" href="contrib-dblink-get-connections.html" title="dblink_get_connections" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_close</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-fetch.html" title="dblink_fetch">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-get-connections.html" title="dblink_get_connections">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-CLOSE"><div class="titlepage"></div><a id="id-1.11.7.21.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_close</span></h2><p>dblink_close — closes a cursor in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_close(text cursorname [, bool fail_on_error]) returns text
+dblink_close(text connname, text cursorname [, bool fail_on_error]) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.12.5"><h2>Description</h2><p>
+ <code class="function">dblink_close</code> closes a cursor previously opened with
+ <code class="function">dblink_open</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.12.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use; omit this parameter to use the
+ unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>cursorname</code></em></span></dt><dd><p>
+ The name of the cursor to close.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function's return value is set to <code class="literal">ERROR</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.12.7"><h2>Return Value</h2><p>
+ Returns status, either <code class="literal">OK</code> or <code class="literal">ERROR</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.12.8"><h2>Notes</h2><p>
+ If <code class="function">dblink_open</code> started an explicit transaction block,
+ and this is the last remaining open cursor in this connection,
+ <code class="function">dblink_close</code> will issue the matching <code class="command">COMMIT</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.12.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_connect('dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_open('foo', 'select proname, prosrc from pg_proc');
+ dblink_open
+-------------
+ OK
+(1 row)
+
+SELECT dblink_close('foo');
+ dblink_close
+--------------
+ OK
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-fetch.html" title="dblink_fetch">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-get-connections.html" title="dblink_get_connections">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_fetch </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_get_connections</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-connect-u.html b/doc/src/sgml/html/contrib-dblink-connect-u.html
new file mode 100644
index 0000000..e2ca67b
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-connect-u.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_connect_u</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-connect.html" title="dblink_connect" /><link rel="next" href="contrib-dblink-disconnect.html" title="dblink_disconnect" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_connect_u</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-connect.html" title="dblink_connect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-disconnect.html" title="dblink_disconnect">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-CONNECT-U"><div class="titlepage"></div><a id="id-1.11.7.21.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_connect_u</span></h2><p>dblink_connect_u — opens a persistent connection to a remote database, insecurely</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_connect_u(text connstr) returns text
+dblink_connect_u(text connname, text connstr) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.6.5"><h2>Description</h2><p>
+ <code class="function">dblink_connect_u()</code> is identical to
+ <code class="function">dblink_connect()</code>, except that it will allow non-superusers
+ to connect using any authentication method.
+ </p><p>
+ If the remote server selects an authentication method that does not
+ involve a password, then impersonation and subsequent escalation of
+ privileges can occur, because the session will appear to have
+ originated from the user as which the local <span class="productname">PostgreSQL</span>
+ server runs. Also, even if the remote server does demand a password,
+ it is possible for the password to be supplied from the server
+ environment, such as a <code class="filename">~/.pgpass</code> file belonging to the
+ server's user. This opens not only a risk of impersonation, but the
+ possibility of exposing a password to an untrustworthy remote server.
+ Therefore, <code class="function">dblink_connect_u()</code> is initially
+ installed with all privileges revoked from <code class="literal">PUBLIC</code>,
+ making it un-callable except by superusers. In some situations
+ it may be appropriate to grant <code class="literal">EXECUTE</code> permission for
+ <code class="function">dblink_connect_u()</code> to specific users who are considered
+ trustworthy, but this should be done with care. It is also recommended
+ that any <code class="filename">~/.pgpass</code> file belonging to the server's user
+ <span class="emphasis"><em>not</em></span> contain any records specifying a wildcard host name.
+ </p><p>
+ For further details see <code class="function">dblink_connect()</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-connect.html" title="dblink_connect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-disconnect.html" title="dblink_disconnect">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_connect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_disconnect</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-connect.html b/doc/src/sgml/html/contrib-dblink-connect.html
new file mode 100644
index 0000000..a07fdc4
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-connect.html
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_connect</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dblink.html" title="F.12. dblink" /><link rel="next" href="contrib-dblink-connect-u.html" title="dblink_connect_u" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_connect</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dblink.html" title="F.12. dblink">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-connect-u.html" title="dblink_connect_u">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-CONNECT"><div class="titlepage"></div><a id="id-1.11.7.21.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_connect</span></h2><p>dblink_connect — opens a persistent connection to a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_connect(text connstr) returns text
+dblink_connect(text connname, text connstr) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.5.5"><h2>Description</h2><p>
+ <code class="function">dblink_connect()</code> establishes a connection to a remote
+ <span class="productname">PostgreSQL</span> database. The server and database to
+ be contacted are identified through a standard <span class="application">libpq</span>
+ connection string. Optionally, a name can be assigned to the
+ connection. Multiple named connections can be open at once, but
+ only one unnamed connection is permitted at a time. The connection
+ will persist until closed or until the database session is ended.
+ </p><p>
+ The connection string may also be the name of an existing foreign
+ server. It is recommended to use the foreign-data wrapper
+ <code class="literal">dblink_fdw</code> when defining the foreign
+ server. See the example below, as well as
+ <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a> and
+ <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.5.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ The name to use for this connection; if omitted, an unnamed
+ connection is opened, replacing any existing unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>connstr</code></em></span></dt><dd><p><span class="application">libpq</span>-style connection info string, for example
+ <code class="literal">hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres
+ password=mypasswd options=-csearch_path=</code>.
+ For details see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.
+ Alternatively, the name of a foreign server.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.5.7"><h2>Return Value</h2><p>
+ Returns status, which is always <code class="literal">OK</code> (since any error
+ causes the function to throw an error instead of returning).
+ </p></div><div class="refsect1" id="id-1.11.7.21.5.8"><h2>Notes</h2><p>
+ If untrusted users have access to a database that has not adopted a
+ <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
+ begin each session by removing publicly-writable schemas from
+ <code class="varname">search_path</code>. One could, for example,
+ add <code class="literal">options=-csearch_path=</code> to
+ <em class="parameter"><code>connstr</code></em>. This consideration is not specific
+ to <code class="filename">dblink</code>; it applies to every interface for
+ executing arbitrary SQL commands.
+ </p><p>
+ Only superusers may use <code class="function">dblink_connect</code> to create
+ non-password-authenticated connections. If non-superusers need this
+ capability, use <code class="function">dblink_connect_u</code> instead.
+ </p><p>
+ It is unwise to choose connection names that contain equal signs,
+ as this opens a risk of confusion with connection info strings
+ in other <code class="filename">dblink</code> functions.
+ </p></div><div class="refsect1" id="id-1.11.7.21.5.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_connect('dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_connect('myconn', 'dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+-- FOREIGN DATA WRAPPER functionality
+-- Note: local connection must require password authentication for this to work properly
+-- Otherwise, you will receive the following error from dblink_connect():
+-- ERROR: password is required
+-- DETAIL: Non-superuser cannot connect if the server does not request a password.
+-- HINT: Target server's authentication method must be changed.
+
+CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression');
+
+CREATE USER regress_dblink_user WITH PASSWORD 'secret';
+CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user 'regress_dblink_user', password 'secret');
+GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user;
+GRANT SELECT ON TABLE foo TO regress_dblink_user;
+
+\set ORIGINAL_USER :USER
+\c - regress_dblink_user
+SELECT dblink_connect('myconn', 'fdtest');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT * FROM dblink('myconn', 'SELECT * FROM foo') AS t(a int, b text, c text[]);
+ a | b | c
+----+---+---------------
+ 0 | a | {a0,b0,c0}
+ 1 | b | {a1,b1,c1}
+ 2 | c | {a2,b2,c2}
+ 3 | d | {a3,b3,c3}
+ 4 | e | {a4,b4,c4}
+ 5 | f | {a5,b5,c5}
+ 6 | g | {a6,b6,c6}
+ 7 | h | {a7,b7,c7}
+ 8 | i | {a8,b8,c8}
+ 9 | j | {a9,b9,c9}
+ 10 | k | {a10,b10,c10}
+(11 rows)
+
+\c - :ORIGINAL_USER
+REVOKE USAGE ON FOREIGN SERVER fdtest FROM regress_dblink_user;
+REVOKE SELECT ON TABLE foo FROM regress_dblink_user;
+DROP USER MAPPING FOR regress_dblink_user SERVER fdtest;
+DROP USER regress_dblink_user;
+DROP SERVER fdtest;
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dblink.html" title="F.12. dblink">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-connect-u.html" title="dblink_connect_u">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.12. dblink </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_connect_u</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-disconnect.html b/doc/src/sgml/html/contrib-dblink-disconnect.html
new file mode 100644
index 0000000..1a0a625
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-disconnect.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_disconnect</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-connect-u.html" title="dblink_connect_u" /><link rel="next" href="contrib-dblink-function.html" title="dblink" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_disconnect</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-connect-u.html" title="dblink_connect_u">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-function.html" title="dblink">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-DISCONNECT"><div class="titlepage"></div><a id="id-1.11.7.21.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_disconnect</span></h2><p>dblink_disconnect — closes a persistent connection to a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_disconnect() returns text
+dblink_disconnect(text connname) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.7.5"><h2>Description</h2><p>
+ <code class="function">dblink_disconnect()</code> closes a connection previously opened
+ by <code class="function">dblink_connect()</code>. The form with no arguments closes
+ an unnamed connection.
+ </p></div><div class="refsect1" id="id-1.11.7.21.7.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ The name of a named connection to be closed.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.7.7"><h2>Return Value</h2><p>
+ Returns status, which is always <code class="literal">OK</code> (since any error
+ causes the function to throw an error instead of returning).
+ </p></div><div class="refsect1" id="id-1.11.7.21.7.8"><h2>Examples</h2><pre class="screen">
+SELECT dblink_disconnect();
+ dblink_disconnect
+-------------------
+ OK
+(1 row)
+
+SELECT dblink_disconnect('myconn');
+ dblink_disconnect
+-------------------
+ OK
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-connect-u.html" title="dblink_connect_u">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-function.html" title="dblink">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_connect_u </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-error-message.html b/doc/src/sgml/html/contrib-dblink-error-message.html
new file mode 100644
index 0000000..ae55b48
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-error-message.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_error_message</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-get-connections.html" title="dblink_get_connections" /><link rel="next" href="contrib-dblink-send-query.html" title="dblink_send_query" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_error_message</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-get-connections.html" title="dblink_get_connections">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-send-query.html" title="dblink_send_query">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-ERROR-MESSAGE"><div class="titlepage"></div><a id="id-1.11.7.21.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_error_message</span></h2><p>dblink_error_message — gets last error message on the named connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_error_message(text connname) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.14.5"><h2>Description</h2><p>
+ <code class="function">dblink_error_message</code> fetches the most recent remote
+ error message for a given connection.
+ </p></div><div class="refsect1" id="id-1.11.7.21.14.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.14.7"><h2>Return Value</h2><p>
+ Returns last error message, or <code class="literal">OK</code> if there has been
+ no error in this connection.
+ </p></div><div class="refsect1" id="id-1.11.7.21.14.8"><h2>Notes</h2><p>
+ When asynchronous queries are initiated by
+ <code class="function">dblink_send_query</code>, the error message associated with
+ the connection might not get updated until the server's response message
+ is consumed. This typically means that <code class="function">dblink_is_busy</code>
+ or <code class="function">dblink_get_result</code> should be called prior to
+ <code class="function">dblink_error_message</code>, so that any error generated by
+ the asynchronous query will be visible.
+ </p></div><div class="refsect1" id="id-1.11.7.21.14.9"><h2>Examples</h2><pre class="programlisting">
+SELECT dblink_error_message('dtest1');
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-get-connections.html" title="dblink_get_connections">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-send-query.html" title="dblink_send_query">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_get_connections </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_send_query</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-exec.html b/doc/src/sgml/html/contrib-dblink-exec.html
new file mode 100644
index 0000000..8a25864
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-exec.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_exec</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-function.html" title="dblink" /><link rel="next" href="contrib-dblink-open.html" title="dblink_open" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_exec</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-function.html" title="dblink">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-open.html" title="dblink_open">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-EXEC"><div class="titlepage"></div><a id="id-1.11.7.21.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_exec</span></h2><p>dblink_exec — executes a command in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
+dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
+dblink_exec(text sql [, bool fail_on_error]) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.9.5"><h2>Description</h2><p>
+ <code class="function">dblink_exec</code> executes a command (that is, any SQL statement
+ that doesn't return rows) in a remote database.
+ </p><p>
+ When two <code class="type">text</code> arguments are given, the first one is first
+ looked up as a persistent connection's name; if found, the command
+ is executed on that connection. If not found, the first argument
+ is treated as a connection info string as for <code class="function">dblink_connect</code>,
+ and the indicated connection is made just for the duration of this command.
+ </p></div><div class="refsect1" id="id-1.11.7.21.9.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use; omit this parameter to use the
+ unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>connstr</code></em></span></dt><dd><p>
+ A connection info string, as previously described for
+ <code class="function">dblink_connect</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
+ The SQL command that you wish to execute in the remote database,
+ for example
+ <code class="literal">insert into foo values(0, 'a', '{"a0","b0","c0"}')</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function's return value is set to <code class="literal">ERROR</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.9.7"><h2>Return Value</h2><p>
+ Returns status, either the command's status string or <code class="literal">ERROR</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.9.8"><h2>Examples</h2><pre class="screen">
+SELECT dblink_connect('dbname=dblink_test_standby');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_exec('insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
+ dblink_exec
+-----------------
+ INSERT 943366 1
+(1 row)
+
+SELECT dblink_connect('myconn', 'dbname=regression');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_exec('myconn', 'insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
+ dblink_exec
+------------------
+ INSERT 6432584 1
+(1 row)
+
+SELECT dblink_exec('myconn', 'insert into pg_class values (''foo'')',false);
+NOTICE: sql error
+DETAIL: ERROR: null value in column "relnamespace" violates not-null constraint
+
+ dblink_exec
+-------------
+ ERROR
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-function.html" title="dblink">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-open.html" title="dblink_open">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_open</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-fetch.html b/doc/src/sgml/html/contrib-dblink-fetch.html
new file mode 100644
index 0000000..68d2c12
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-fetch.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_fetch</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-open.html" title="dblink_open" /><link rel="next" href="contrib-dblink-close.html" title="dblink_close" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_fetch</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-open.html" title="dblink_open">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-close.html" title="dblink_close">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-FETCH"><div class="titlepage"></div><a id="id-1.11.7.21.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_fetch</span></h2><p>dblink_fetch — returns rows from an open cursor in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
+dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
+</pre></div><div class="refsect1" id="id-1.11.7.21.11.5"><h2>Description</h2><p>
+ <code class="function">dblink_fetch</code> fetches rows from a cursor previously
+ established by <code class="function">dblink_open</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.11.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use; omit this parameter to use the
+ unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>cursorname</code></em></span></dt><dd><p>
+ The name of the cursor to fetch from.
+ </p></dd><dt><span class="term"><em class="parameter"><code>howmany</code></em></span></dt><dd><p>
+ The maximum number of rows to retrieve. The next <em class="parameter"><code>howmany</code></em>
+ rows are fetched, starting at the current cursor position, moving
+ forward. Once the cursor has reached its end, no more rows are produced.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function returns no rows.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.11.7"><h2>Return Value</h2><p>
+ The function returns the row(s) fetched from the cursor. To use this
+ function, you will need to specify the expected set of columns,
+ as previously discussed for <code class="function">dblink</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.11.8"><h2>Notes</h2><p>
+ On a mismatch between the number of return columns specified in the
+ <code class="literal">FROM</code> clause, and the actual number of columns returned by the
+ remote cursor, an error will be thrown. In this event, the remote cursor
+ is still advanced by as many rows as it would have been if the error had
+ not occurred. The same is true for any other error occurring in the local
+ query after the remote <code class="command">FETCH</code> has been done.
+ </p></div><div class="refsect1" id="id-1.11.7.21.11.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_connect('dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%''');
+ dblink_open
+-------------
+ OK
+(1 row)
+
+SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
+ funcname | source
+----------+----------
+ byteacat | byteacat
+ byteacmp | byteacmp
+ byteaeq | byteaeq
+ byteage | byteage
+ byteagt | byteagt
+(5 rows)
+
+SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
+ funcname | source
+-----------+-----------
+ byteain | byteain
+ byteale | byteale
+ bytealike | bytealike
+ bytealt | bytealt
+ byteane | byteane
+(5 rows)
+
+SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
+ funcname | source
+------------+------------
+ byteanlike | byteanlike
+ byteaout | byteaout
+(2 rows)
+
+SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
+ funcname | source
+----------+--------
+(0 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-open.html" title="dblink_open">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-close.html" title="dblink_close">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_open </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_close</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-function.html b/doc/src/sgml/html/contrib-dblink-function.html
new file mode 100644
index 0000000..0dfe220
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-function.html
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-disconnect.html" title="dblink_disconnect" /><link rel="next" href="contrib-dblink-exec.html" title="dblink_exec" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-disconnect.html" title="dblink_disconnect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-exec.html" title="dblink_exec">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-FUNCTION"><div class="titlepage"></div><a id="id-1.11.7.21.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink</span></h2><p>dblink — executes a query in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink(text connname, text sql [, bool fail_on_error]) returns setof record
+dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
+dblink(text sql [, bool fail_on_error]) returns setof record
+</pre></div><div class="refsect1" id="id-1.11.7.21.8.5"><h2>Description</h2><p>
+ <code class="function">dblink</code> executes a query (usually a <code class="command">SELECT</code>,
+ but it can be any SQL statement that returns rows) in a remote database.
+ </p><p>
+ When two <code class="type">text</code> arguments are given, the first one is first
+ looked up as a persistent connection's name; if found, the command
+ is executed on that connection. If not found, the first argument
+ is treated as a connection info string as for <code class="function">dblink_connect</code>,
+ and the indicated connection is made just for the duration of this command.
+ </p></div><div class="refsect1" id="id-1.11.7.21.8.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use; omit this parameter to use the
+ unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>connstr</code></em></span></dt><dd><p>
+ A connection info string, as previously described for
+ <code class="function">dblink_connect</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
+ The SQL query that you wish to execute in the remote database,
+ for example <code class="literal">select * from foo</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function returns no rows.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.8.7"><h2>Return Value</h2><p>
+ The function returns the row(s) produced by the query. Since
+ <code class="function">dblink</code> can be used with any query, it is declared
+ to return <code class="type">record</code>, rather than specifying any particular
+ set of columns. This means that you must specify the expected
+ set of columns in the calling query — otherwise
+ <span class="productname">PostgreSQL</span> would not know what to expect.
+ Here is an example:
+
+</p><pre class="programlisting">
+SELECT *
+ FROM dblink('dbname=mydb options=-csearch_path=',
+ 'select proname, prosrc from pg_proc')
+ AS t1(proname name, prosrc text)
+ WHERE proname LIKE 'bytea%';
+</pre><p>
+
+ The <span class="quote">“<span class="quote">alias</span>”</span> part of the <code class="literal">FROM</code> clause must
+ specify the column names and types that the function will return.
+ (Specifying column names in an alias is actually standard SQL
+ syntax, but specifying column types is a <span class="productname">PostgreSQL</span>
+ extension.) This allows the system to understand what
+ <code class="literal">*</code> should expand to, and what <code class="structname">proname</code>
+ in the <code class="literal">WHERE</code> clause refers to, in advance of trying
+ to execute the function. At run time, an error will be thrown
+ if the actual query result from the remote database does not
+ have the same number of columns shown in the <code class="literal">FROM</code> clause.
+ The column names need not match, however, and <code class="function">dblink</code>
+ does not insist on exact type matches either. It will succeed
+ so long as the returned data strings are valid input for the
+ column type declared in the <code class="literal">FROM</code> clause.
+ </p></div><div class="refsect1" id="id-1.11.7.21.8.8"><h2>Notes</h2><p>
+ A convenient way to use <code class="function">dblink</code> with predetermined
+ queries is to create a view.
+ This allows the column type information to be buried in the view,
+ instead of having to spell it out in every query. For example,
+
+</p><pre class="programlisting">
+CREATE VIEW myremote_pg_proc AS
+ SELECT *
+ FROM dblink('dbname=postgres options=-csearch_path=',
+ 'select proname, prosrc from pg_proc')
+ AS t1(proname name, prosrc text);
+
+SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%';
+</pre></div><div class="refsect1" id="id-1.11.7.21.8.9"><h2>Examples</h2><pre class="screen">
+SELECT * FROM dblink('dbname=postgres options=-csearch_path=',
+ 'select proname, prosrc from pg_proc')
+ AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
+ proname | prosrc
+------------+------------
+ byteacat | byteacat
+ byteaeq | byteaeq
+ bytealt | bytealt
+ byteale | byteale
+ byteagt | byteagt
+ byteage | byteage
+ byteane | byteane
+ byteacmp | byteacmp
+ bytealike | bytealike
+ byteanlike | byteanlike
+ byteain | byteain
+ byteaout | byteaout
+(12 rows)
+
+SELECT dblink_connect('dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT * FROM dblink('select proname, prosrc from pg_proc')
+ AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
+ proname | prosrc
+------------+------------
+ byteacat | byteacat
+ byteaeq | byteaeq
+ bytealt | bytealt
+ byteale | byteale
+ byteagt | byteagt
+ byteage | byteage
+ byteane | byteane
+ byteacmp | byteacmp
+ bytealike | bytealike
+ byteanlike | byteanlike
+ byteain | byteain
+ byteaout | byteaout
+(12 rows)
+
+SELECT dblink_connect('myconn', 'dbname=regression options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc')
+ AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
+ proname | prosrc
+------------+------------
+ bytearecv | bytearecv
+ byteasend | byteasend
+ byteale | byteale
+ byteagt | byteagt
+ byteage | byteage
+ byteane | byteane
+ byteacmp | byteacmp
+ bytealike | bytealike
+ byteanlike | byteanlike
+ byteacat | byteacat
+ byteaeq | byteaeq
+ bytealt | bytealt
+ byteain | byteain
+ byteaout | byteaout
+(14 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-disconnect.html" title="dblink_disconnect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-exec.html" title="dblink_exec">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_disconnect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_exec</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-get-connections.html b/doc/src/sgml/html/contrib-dblink-get-connections.html
new file mode 100644
index 0000000..049c21e
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-get-connections.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_get_connections</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-close.html" title="dblink_close" /><link rel="next" href="contrib-dblink-error-message.html" title="dblink_error_message" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_get_connections</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-close.html" title="dblink_close">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-error-message.html" title="dblink_error_message">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-GET-CONNECTIONS"><div class="titlepage"></div><a id="id-1.11.7.21.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_get_connections</span></h2><p>dblink_get_connections — returns the names of all open named dblink connections</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_get_connections() returns text[]
+</pre></div><div class="refsect1" id="id-1.11.7.21.13.5"><h2>Description</h2><p>
+ <code class="function">dblink_get_connections</code> returns an array of the names
+ of all open named <code class="filename">dblink</code> connections.
+ </p></div><div class="refsect1" id="id-1.11.7.21.13.6"><h2>Return Value</h2><p>Returns a text array of connection names, or NULL if none.</p></div><div class="refsect1" id="id-1.11.7.21.13.7"><h2>Examples</h2><pre class="programlisting">
+SELECT dblink_get_connections();
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-close.html" title="dblink_close">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-error-message.html" title="dblink_error_message">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_close </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_error_message</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-get-notify.html b/doc/src/sgml/html/contrib-dblink-get-notify.html
new file mode 100644
index 0000000..6051896
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-get-notify.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_get_notify</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-is-busy.html" title="dblink_is_busy" /><link rel="next" href="contrib-dblink-get-result.html" title="dblink_get_result" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_get_notify</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-is-busy.html" title="dblink_is_busy">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-get-result.html" title="dblink_get_result">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-GET-NOTIFY"><div class="titlepage"></div><a id="id-1.11.7.21.17.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_get_notify</span></h2><p>dblink_get_notify — retrieve async notifications on a connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_get_notify() returns setof (notify_name text, be_pid int, extra text)
+dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, extra text)
+</pre></div><div class="refsect1" id="id-1.11.7.21.17.5"><h2>Description</h2><p>
+ <code class="function">dblink_get_notify</code> retrieves notifications on either
+ the unnamed connection, or on a named connection if specified.
+ To receive notifications via dblink, <code class="function">LISTEN</code> must
+ first be issued, using <code class="function">dblink_exec</code>.
+ For details see <a class="xref" href="sql-listen.html" title="LISTEN"><span class="refentrytitle">LISTEN</span></a> and <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.17.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ The name of a named connection to get notifications on.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.17.7"><h2>Return Value</h2><p>Returns <code class="type">setof (notify_name text, be_pid int, extra text)</code>, or an empty set if none.</p></div><div class="refsect1" id="id-1.11.7.21.17.8"><h2>Examples</h2><pre class="screen">
+SELECT dblink_exec('LISTEN virtual');
+ dblink_exec
+-------------
+ LISTEN
+(1 row)
+
+SELECT * FROM dblink_get_notify();
+ notify_name | be_pid | extra
+-------------+--------+-------
+(0 rows)
+
+NOTIFY virtual;
+NOTIFY
+
+SELECT * FROM dblink_get_notify();
+ notify_name | be_pid | extra
+-------------+--------+-------
+ virtual | 1229 |
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-is-busy.html" title="dblink_is_busy">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-get-result.html" title="dblink_get_result">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_is_busy </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_get_result</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-get-pkey.html b/doc/src/sgml/html/contrib-dblink-get-pkey.html
new file mode 100644
index 0000000..579a8bc
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-get-pkey.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_get_pkey</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query" /><link rel="next" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_get_pkey</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-GET-PKEY"><div class="titlepage"></div><a id="id-1.11.7.21.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_get_pkey</span></h2><p>dblink_get_pkey — returns the positions and field names of a relation's
+ primary key fields
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_get_pkey(text relname) returns setof dblink_pkey_results
+</pre></div><div class="refsect1" id="id-1.11.7.21.20.5"><h2>Description</h2><p>
+ <code class="function">dblink_get_pkey</code> provides information about the primary
+ key of a relation in the local database. This is sometimes useful
+ in generating queries to be sent to remote databases.
+ </p></div><div class="refsect1" id="id-1.11.7.21.20.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>relname</code></em></span></dt><dd><p>
+ Name of a local relation, for example <code class="literal">foo</code> or
+ <code class="literal">myschema.mytab</code>. Include double quotes if the
+ name is mixed-case or contains special characters, for
+ example <code class="literal">"FooBar"</code>; without quotes, the string
+ will be folded to lower case.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.20.7"><h2>Return Value</h2><p>
+ Returns one row for each primary key field, or no rows if the relation
+ has no primary key. The result row type is defined as
+
+</p><pre class="programlisting">
+CREATE TYPE dblink_pkey_results AS (position int, colname text);
+</pre><p>
+
+ The <code class="literal">position</code> column simply runs from 1 to <em class="replaceable"><code>N</code></em>;
+ it is the number of the field within the primary key, not the number
+ within the table's columns.
+ </p></div><div class="refsect1" id="id-1.11.7.21.20.8"><h2>Examples</h2><pre class="screen">
+CREATE TABLE foobar (
+ f1 int,
+ f2 int,
+ f3 int,
+ PRIMARY KEY (f1, f2, f3)
+);
+CREATE TABLE
+
+SELECT * FROM dblink_get_pkey('foobar');
+ position | colname
+----------+---------
+ 1 | f1
+ 2 | f2
+ 3 | f3
+(3 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-build-sql-insert.html" title="dblink_build_sql_insert">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_cancel_query </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_build_sql_insert</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-get-result.html b/doc/src/sgml/html/contrib-dblink-get-result.html
new file mode 100644
index 0000000..5bbea8e
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-get-result.html
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_get_result</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-get-notify.html" title="dblink_get_notify" /><link rel="next" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_get_result</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-get-notify.html" title="dblink_get_notify">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-GET-RESULT"><div class="titlepage"></div><a id="id-1.11.7.21.18.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_get_result</span></h2><p>dblink_get_result — gets an async query result</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_get_result(text connname [, bool fail_on_error]) returns setof record
+</pre></div><div class="refsect1" id="id-1.11.7.21.18.5"><h2>Description</h2><p>
+ <code class="function">dblink_get_result</code> collects the results of an
+ asynchronous query previously sent with <code class="function">dblink_send_query</code>.
+ If the query is not already completed, <code class="function">dblink_get_result</code>
+ will wait until it is.
+ </p></div><div class="refsect1" id="id-1.11.7.21.18.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function returns no rows.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.18.7"><h2>Return Value</h2><p>
+ For an async query (that is, an SQL statement returning rows),
+ the function returns the row(s) produced by the query. To use this
+ function, you will need to specify the expected set of columns,
+ as previously discussed for <code class="function">dblink</code>.
+ </p><p>
+ For an async command (that is, an SQL statement not returning rows),
+ the function returns a single row with a single text column containing
+ the command's status string. It is still necessary to specify that
+ the result will have a single text column in the calling <code class="literal">FROM</code>
+ clause.
+ </p></div><div class="refsect1" id="id-1.11.7.21.18.8"><h2>Notes</h2><p>
+ This function <span class="emphasis"><em>must</em></span> be called if
+ <code class="function">dblink_send_query</code> returned 1.
+ It must be called once for each query
+ sent, and one additional time to obtain an empty set result,
+ before the connection can be used again.
+ </p><p>
+ When using <code class="function">dblink_send_query</code> and
+ <code class="function">dblink_get_result</code>, <span class="application">dblink</span> fetches the entire
+ remote query result before returning any of it to the local query
+ processor. If the query returns a large number of rows, this can result
+ in transient memory bloat in the local session. It may be better to open
+ such a query as a cursor with <code class="function">dblink_open</code> and then fetch a
+ manageable number of rows at a time. Alternatively, use plain
+ <code class="function">dblink()</code>, which avoids memory bloat by spooling large result
+ sets to disk.
+ </p></div><div class="refsect1" id="id-1.11.7.21.18.9"><h2>Examples</h2><pre class="screen">
+contrib_regression=# SELECT dblink_connect('dtest1', 'dbname=contrib_regression');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+contrib_regression=# SELECT * FROM
+contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 &lt; 3') AS t1;
+ t1
+----
+ 1
+(1 row)
+
+contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]);
+ f1 | f2 | f3
+----+----+------------
+ 0 | a | {a0,b0,c0}
+ 1 | b | {a1,b1,c1}
+ 2 | c | {a2,b2,c2}
+(3 rows)
+
+contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]);
+ f1 | f2 | f3
+----+----+----
+(0 rows)
+
+contrib_regression=# SELECT * FROM
+contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 &lt; 3; select * from foo where f1 &gt; 6') AS t1;
+ t1
+----
+ 1
+(1 row)
+
+contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]);
+ f1 | f2 | f3
+----+----+------------
+ 0 | a | {a0,b0,c0}
+ 1 | b | {a1,b1,c1}
+ 2 | c | {a2,b2,c2}
+(3 rows)
+
+contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]);
+ f1 | f2 | f3
+----+----+---------------
+ 7 | h | {a7,b7,c7}
+ 8 | i | {a8,b8,c8}
+ 9 | j | {a9,b9,c9}
+ 10 | k | {a10,b10,c10}
+(4 rows)
+
+contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]);
+ f1 | f2 | f3
+----+----+----
+(0 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-get-notify.html" title="dblink_get_notify">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-cancel-query.html" title="dblink_cancel_query">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_get_notify </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_cancel_query</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-is-busy.html b/doc/src/sgml/html/contrib-dblink-is-busy.html
new file mode 100644
index 0000000..3645e3e
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-is-busy.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_is_busy</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-send-query.html" title="dblink_send_query" /><link rel="next" href="contrib-dblink-get-notify.html" title="dblink_get_notify" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_is_busy</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-send-query.html" title="dblink_send_query">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-get-notify.html" title="dblink_get_notify">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-IS-BUSY"><div class="titlepage"></div><a id="id-1.11.7.21.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_is_busy</span></h2><p>dblink_is_busy — checks if connection is busy with an async query</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_is_busy(text connname) returns int
+</pre></div><div class="refsect1" id="id-1.11.7.21.16.5"><h2>Description</h2><p>
+ <code class="function">dblink_is_busy</code> tests whether an async query is in progress.
+ </p></div><div class="refsect1" id="id-1.11.7.21.16.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to check.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.16.7"><h2>Return Value</h2><p>
+ Returns 1 if connection is busy, 0 if it is not busy.
+ If this function returns 0, it is guaranteed that
+ <code class="function">dblink_get_result</code> will not block.
+ </p></div><div class="refsect1" id="id-1.11.7.21.16.8"><h2>Examples</h2><pre class="programlisting">
+SELECT dblink_is_busy('dtest1');
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-send-query.html" title="dblink_send_query">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-get-notify.html" title="dblink_get_notify">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_send_query </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_get_notify</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-open.html b/doc/src/sgml/html/contrib-dblink-open.html
new file mode 100644
index 0000000..518b0f3
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-open.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_open</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-exec.html" title="dblink_exec" /><link rel="next" href="contrib-dblink-fetch.html" title="dblink_fetch" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_open</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-exec.html" title="dblink_exec">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-fetch.html" title="dblink_fetch">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-OPEN"><div class="titlepage"></div><a id="id-1.11.7.21.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_open</span></h2><p>dblink_open — opens a cursor in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text
+dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text
+</pre></div><div class="refsect1" id="id-1.11.7.21.10.5"><h2>Description</h2><p>
+ <code class="function">dblink_open()</code> opens a cursor in a remote database.
+ The cursor can subsequently be manipulated with
+ <code class="function">dblink_fetch()</code> and <code class="function">dblink_close()</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.10.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use; omit this parameter to use the
+ unnamed connection.
+ </p></dd><dt><span class="term"><em class="parameter"><code>cursorname</code></em></span></dt><dd><p>
+ The name to assign to this cursor.
+ </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
+ The <code class="command">SELECT</code> statement that you wish to execute in the remote
+ database, for example <code class="literal">select * from pg_class</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
+ If true (the default when omitted) then an error thrown on the
+ remote side of the connection causes an error to also be thrown
+ locally. If false, the remote error is locally reported as a NOTICE,
+ and the function's return value is set to <code class="literal">ERROR</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.10.7"><h2>Return Value</h2><p>
+ Returns status, either <code class="literal">OK</code> or <code class="literal">ERROR</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.10.8"><h2>Notes</h2><p>
+ Since a cursor can only persist within a transaction,
+ <code class="function">dblink_open</code> starts an explicit transaction block
+ (<code class="command">BEGIN</code>) on the remote side, if the remote side was
+ not already within a transaction. This transaction will be
+ closed again when the matching <code class="function">dblink_close</code> is
+ executed. Note that if
+ you use <code class="function">dblink_exec</code> to change data between
+ <code class="function">dblink_open</code> and <code class="function">dblink_close</code>,
+ and then an error occurs or you use <code class="function">dblink_disconnect</code> before
+ <code class="function">dblink_close</code>, your change <span class="emphasis"><em>will be
+ lost</em></span> because the transaction will be aborted.
+ </p></div><div class="refsect1" id="id-1.11.7.21.10.9"><h2>Examples</h2><pre class="screen">
+SELECT dblink_connect('dbname=postgres options=-csearch_path=');
+ dblink_connect
+----------------
+ OK
+(1 row)
+
+SELECT dblink_open('foo', 'select proname, prosrc from pg_proc');
+ dblink_open
+-------------
+ OK
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-exec.html" title="dblink_exec">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-fetch.html" title="dblink_fetch">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_exec </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_fetch</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-dblink-send-query.html b/doc/src/sgml/html/contrib-dblink-send-query.html
new file mode 100644
index 0000000..0fb28ee
--- /dev/null
+++ b/doc/src/sgml/html/contrib-dblink-send-query.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_send_query</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-error-message.html" title="dblink_error_message" /><link rel="next" href="contrib-dblink-is-busy.html" title="dblink_is_busy" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_send_query</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-error-message.html" title="dblink_error_message">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-is-busy.html" title="dblink_is_busy">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-SEND-QUERY"><div class="titlepage"></div><a id="id-1.11.7.21.15.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_send_query</span></h2><p>dblink_send_query — sends an async query to a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+dblink_send_query(text connname, text sql) returns int
+</pre></div><div class="refsect1" id="id-1.11.7.21.15.5"><h2>Description</h2><p>
+ <code class="function">dblink_send_query</code> sends a query to be executed
+ asynchronously, that is, without immediately waiting for the result.
+ There must not be an async query already in progress on the
+ connection.
+ </p><p>
+ After successfully dispatching an async query, completion status
+ can be checked with <code class="function">dblink_is_busy</code>, and the results
+ are ultimately collected with <code class="function">dblink_get_result</code>.
+ It is also possible to attempt to cancel an active async query
+ using <code class="function">dblink_cancel_query</code>.
+ </p></div><div class="refsect1" id="id-1.11.7.21.15.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
+ Name of the connection to use.
+ </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
+ The SQL statement that you wish to execute in the remote database,
+ for example <code class="literal">select * from pg_class</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.15.7"><h2>Return Value</h2><p>
+ Returns 1 if the query was successfully dispatched, 0 otherwise.
+ </p></div><div class="refsect1" id="id-1.11.7.21.15.8"><h2>Examples</h2><pre class="programlisting">
+SELECT dblink_send_query('dtest1', 'SELECT * FROM foo WHERE f1 &lt; 3');
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-error-message.html" title="dblink_error_message">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-is-busy.html" title="dblink_is_busy">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_error_message </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_is_busy</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-prog-client.html b/doc/src/sgml/html/contrib-prog-client.html
new file mode 100644
index 0000000..67cdca5
--- /dev/null
+++ b/doc/src/sgml/html/contrib-prog-client.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>G.1. Client Applications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs" /><link rel="next" href="oid2name.html" title="oid2name" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">G.1. Client Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Up</a></td><th width="60%" align="center">Appendix G. Additional Supplied Programs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="oid2name.html" title="oid2name">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONTRIB-PROG-CLIENT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">G.1. Client Applications</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="oid2name.html">oid2name</a></span><span class="refpurpose"> — resolve OIDs and file nodes in a <span class="productname">PostgreSQL</span> data directory</span></dt><dt><span class="refentrytitle"><a href="vacuumlo.html"><span class="application">vacuumlo</span></a></span><span class="refpurpose"> — remove orphaned large objects from a <span class="productname">PostgreSQL</span> database</span></dt></dl></div><p>
+ This section covers <span class="productname">PostgreSQL</span> client
+ applications in <code class="literal">contrib</code>. They can be run from anywhere,
+ independent of where the database server resides. See
+ also <a class="xref" href="reference-client.html" title="PostgreSQL Client Applications">PostgreSQL Client Applications</a> for information about client
+ applications that are part of the core <span class="productname">PostgreSQL</span>
+ distribution.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="oid2name.html" title="oid2name">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix G. Additional Supplied Programs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> oid2name</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-prog-server.html b/doc/src/sgml/html/contrib-prog-server.html
new file mode 100644
index 0000000..234af5f
--- /dev/null
+++ b/doc/src/sgml/html/contrib-prog-server.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>G.2. Server Applications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="vacuumlo.html" title="vacuumlo" /><link rel="next" href="external-projects.html" title="Appendix H. External Projects" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">G.2. Server Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="vacuumlo.html" title="vacuumlo">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Up</a></td><th width="60%" align="center">Appendix G. Additional Supplied Programs</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="external-projects.html" title="Appendix H. External Projects">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONTRIB-PROG-SERVER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">G.2. Server Applications</h2></div></div></div><p>
+ Some applications run on the <span class="productname">PostgreSQL</span> server
+ itself. Currently, no such applications are included in the
+ <code class="literal">contrib</code> directory. See also <a class="xref" href="reference-server.html" title="PostgreSQL Server Applications">PostgreSQL Server Applications</a> for information about server applications that
+ are part of the core <span class="productname">PostgreSQL</span> distribution.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vacuumlo.html" title="vacuumlo">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="external-projects.html" title="Appendix H. External Projects">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">vacuumlo</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix H. External Projects</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-prog.html b/doc/src/sgml/html/contrib-prog.html
new file mode 100644
index 0000000..c35e4fc
--- /dev/null
+++ b/doc/src/sgml/html/contrib-prog.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix G. Additional Supplied Programs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xml2.html" title="F.50. xml2" /><link rel="next" href="contrib-prog-client.html" title="G.1. Client Applications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix G. Additional Supplied Programs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xml2.html" title="F.50. xml2">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-prog-client.html" title="G.1. Client Applications">Next</a></td></tr></table><hr /></div><div class="appendix" id="CONTRIB-PROG"><div class="titlepage"><div><div><h2 class="title">Appendix G. Additional Supplied Programs</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="contrib-prog-client.html">G.1. Client Applications</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="oid2name.html">oid2name</a></span><span class="refpurpose"> — resolve OIDs and file nodes in a <span class="productname">PostgreSQL</span> data directory</span></dt><dt><span class="refentrytitle"><a href="vacuumlo.html"><span class="application">vacuumlo</span></a></span><span class="refpurpose"> — remove orphaned large objects from a <span class="productname">PostgreSQL</span> database</span></dt></dl></dd><dt><span class="sect1"><a href="contrib-prog-server.html">G.2. Server Applications</a></span></dt></dl></div><p>
+ This appendix and the previous one contain information regarding the modules that
+ can be found in the <code class="literal">contrib</code> directory of the
+ <span class="productname">PostgreSQL</span> distribution. See <a class="xref" href="contrib.html" title="Appendix F. Additional Supplied Modules">Appendix F</a> for
+ more information about the <code class="literal">contrib</code> section in general and
+ server extensions and plug-ins found in <code class="literal">contrib</code>
+ specifically.
+ </p><p>
+ This appendix covers utility programs found in <code class="literal">contrib</code>.
+ Once installed, either from source or a packaging system, they are found in
+ the <code class="filename">bin</code> directory of the
+ <span class="productname">PostgreSQL</span> installation and can be used like any
+ other program.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xml2.html" title="F.50. xml2">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-prog-client.html" title="G.1. Client Applications">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.50. xml2 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> G.1. Client Applications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib-spi.html b/doc/src/sgml/html/contrib-spi.html
new file mode 100644
index 0000000..86764ae
--- /dev/null
+++ b/doc/src/sgml/html/contrib-spi.html
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.41. spi</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sepgsql.html" title="F.40. sepgsql" /><link rel="next" href="sslinfo.html" title="F.42. sslinfo" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.41. spi</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sepgsql.html" title="F.40. sepgsql">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sslinfo.html" title="F.42. sslinfo">Next</a></td></tr></table><hr /></div><div class="sect1" id="CONTRIB-SPI"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.41. spi</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.5">F.41.1. refint — Functions for Implementing Referential Integrity</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.6">F.41.2. autoinc — Functions for Autoincrementing Fields</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.7">F.41.3. insert_username — Functions for Tracking Who Changed a Table</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.8">F.41.4. moddatetime — Functions for Tracking Last Modification Time</a></span></dt></dl></div><a id="id-1.11.7.50.2" class="indexterm"></a><p>
+ The <span class="application">spi</span> module provides several workable examples
+ of using the <a class="link" href="spi.html" title="Chapter 47. Server Programming Interface">Server Programming Interface</a>
+ (<acronym class="acronym">SPI</acronym>) and triggers. While these functions are of
+ some value in
+ their own right, they are even more useful as examples to modify for
+ your own purposes. The functions are general enough to be used
+ with any table, but you have to specify table and field names (as described
+ below) while creating a trigger.
+ </p><p>
+ Each of the groups of functions described below is provided as a
+ separately-installable extension.
+ </p><div class="sect2" id="id-1.11.7.50.5"><div class="titlepage"><div><div><h3 class="title">F.41.1. refint — Functions for Implementing Referential Integrity</h3></div></div></div><p>
+ <code class="function">check_primary_key()</code> and
+ <code class="function">check_foreign_key()</code> are used to check foreign key constraints.
+ (This functionality is long since superseded by the built-in foreign
+ key mechanism, of course, but the module is still useful as an example.)
+ </p><p>
+ <code class="function">check_primary_key()</code> checks the referencing table.
+ To use, create a <code class="literal">BEFORE INSERT OR UPDATE</code> trigger using this
+ function on a table referencing another table. Specify as the trigger
+ arguments: the referencing table's column name(s) which form the foreign
+ key, the referenced table name, and the column names in the referenced table
+ which form the primary/unique key. To handle multiple foreign
+ keys, create a trigger for each reference.
+ </p><p>
+ <code class="function">check_foreign_key()</code> checks the referenced table.
+ To use, create a <code class="literal">BEFORE DELETE OR UPDATE</code> trigger using this
+ function on a table referenced by other table(s). Specify as the trigger
+ arguments: the number of referencing tables for which the function has to
+ perform checking, the action if a referencing key is found
+ (<code class="literal">cascade</code> — to delete the referencing row,
+ <code class="literal">restrict</code> — to abort transaction if referencing keys
+ exist, <code class="literal">setnull</code> — to set referencing key fields to null),
+ the triggered table's column names which form the primary/unique key, then
+ the referencing table name and column names (repeated for as many
+ referencing tables as were specified by first argument). Note that the
+ primary/unique key columns should be marked NOT NULL and should have a
+ unique index.
+ </p><p>
+ There are examples in <code class="filename">refint.example</code>.
+ </p></div><div class="sect2" id="id-1.11.7.50.6"><div class="titlepage"><div><div><h3 class="title">F.41.2. autoinc — Functions for Autoincrementing Fields</h3></div></div></div><p>
+ <code class="function">autoinc()</code> is a trigger that stores the next value of
+ a sequence into an integer field. This has some overlap with the
+ built-in <span class="quote">“<span class="quote">serial column</span>”</span> feature, but it is not the same:
+ <code class="function">autoinc()</code> will override attempts to substitute a
+ different field value during inserts, and optionally it can be
+ used to increment the field during updates, too.
+ </p><p>
+ To use, create a <code class="literal">BEFORE INSERT</code> (or optionally <code class="literal">BEFORE
+ INSERT OR UPDATE</code>) trigger using this function. Specify two
+ trigger arguments: the name of the integer column to be modified,
+ and the name of the sequence object that will supply values.
+ (Actually, you can specify any number of pairs of such names, if
+ you'd like to update more than one autoincrementing column.)
+ </p><p>
+ There is an example in <code class="filename">autoinc.example</code>.
+ </p></div><div class="sect2" id="id-1.11.7.50.7"><div class="titlepage"><div><div><h3 class="title">F.41.3. insert_username — Functions for Tracking Who Changed a Table</h3></div></div></div><p>
+ <code class="function">insert_username()</code> is a trigger that stores the current
+ user's name into a text field. This can be useful for tracking
+ who last modified a particular row within a table.
+ </p><p>
+ To use, create a <code class="literal">BEFORE INSERT</code> and/or <code class="literal">UPDATE</code>
+ trigger using this function. Specify a single trigger
+ argument: the name of the text column to be modified.
+ </p><p>
+ There is an example in <code class="filename">insert_username.example</code>.
+ </p></div><div class="sect2" id="id-1.11.7.50.8"><div class="titlepage"><div><div><h3 class="title">F.41.4. moddatetime — Functions for Tracking Last Modification Time</h3></div></div></div><p>
+ <code class="function">moddatetime()</code> is a trigger that stores the current
+ time into a <code class="type">timestamp</code> field. This can be useful for tracking
+ the last modification time of a particular row within a table.
+ </p><p>
+ To use, create a <code class="literal">BEFORE UPDATE</code>
+ trigger using this function. Specify a single trigger
+ argument: the name of the column to be modified.
+ The column must be of type <code class="type">timestamp</code> or <code class="type">timestamp with
+ time zone</code>.
+ </p><p>
+ There is an example in <code class="filename">moddatetime.example</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sepgsql.html" title="F.40. sepgsql">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sslinfo.html" title="F.42. sslinfo">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.40. sepgsql </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.42. sslinfo</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/contrib.html b/doc/src/sgml/html/contrib.html
new file mode 100644
index 0000000..4fd5858
--- /dev/null
+++ b/doc/src/sgml/html/contrib.html
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix F. Additional Supplied Modules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-prior.html" title="E.7. Prior Releases" /><link rel="next" href="adminpack.html" title="F.1. adminpack" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix F. Additional Supplied Modules</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-prior.html" title="E.7. Prior Releases">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="adminpack.html" title="F.1. adminpack">Next</a></td></tr></table><hr /></div><div class="appendix" id="CONTRIB"><div class="titlepage"><div><div><h2 class="title">Appendix F. Additional Supplied Modules</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="adminpack.html">F.1. adminpack</a></span></dt><dt><span class="sect1"><a href="amcheck.html">F.2. amcheck</a></span></dt><dd><dl><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.8">F.2.1. Functions</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.9">F.2.2. Optional <em class="parameter"><code>heapallindexed</code></em> Verification</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.10">F.2.3. Using <code class="filename">amcheck</code> Effectively</a></span></dt><dt><span class="sect2"><a href="amcheck.html#id-1.11.7.11.11">F.2.4. Repairing Corruption</a></span></dt></dl></dd><dt><span class="sect1"><a href="auth-delay.html">F.3. auth_delay</a></span></dt><dd><dl><dt><span class="sect2"><a href="auth-delay.html#id-1.11.7.12.5">F.3.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="auth-delay.html#id-1.11.7.12.6">F.3.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="auto-explain.html">F.4. auto_explain</a></span></dt><dd><dl><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.5">F.4.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.6">F.4.2. Example</a></span></dt><dt><span class="sect2"><a href="auto-explain.html#id-1.11.7.13.7">F.4.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="basebackup-to-shell.html">F.5. basebackup_to_shell</a></span></dt><dd><dl><dt><span class="sect2"><a href="basebackup-to-shell.html#id-1.11.7.14.5">F.5.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="basebackup-to-shell.html#id-1.11.7.14.6">F.5.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="basic-archive.html">F.6. basic_archive</a></span></dt><dd><dl><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.5">F.6.1. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.6">F.6.2. Notes</a></span></dt><dt><span class="sect2"><a href="basic-archive.html#id-1.11.7.15.7">F.6.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="bloom.html">F.7. bloom</a></span></dt><dd><dl><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.7">F.7.1. Parameters</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.8">F.7.2. Examples</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.9">F.7.3. Operator Class Interface</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.10">F.7.4. Limitations</a></span></dt><dt><span class="sect2"><a href="bloom.html#id-1.11.7.16.11">F.7.5. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="btree-gin.html">F.8. btree_gin</a></span></dt><dd><dl><dt><span class="sect2"><a href="btree-gin.html#id-1.11.7.17.6">F.8.1. Example Usage</a></span></dt><dt><span class="sect2"><a href="btree-gin.html#id-1.11.7.17.7">F.8.2. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="btree-gist.html">F.9. btree_gist</a></span></dt><dd><dl><dt><span class="sect2"><a href="btree-gist.html#id-1.11.7.18.8">F.9.1. Example Usage</a></span></dt><dt><span class="sect2"><a href="btree-gist.html#id-1.11.7.18.9">F.9.2. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="citext.html">F.10. citext</a></span></dt><dd><dl><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.6">F.10.1. Rationale</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.7">F.10.2. How to Use It</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.8">F.10.3. String Comparison Behavior</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.9">F.10.4. Limitations</a></span></dt><dt><span class="sect2"><a href="citext.html#id-1.11.7.19.10">F.10.5. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="cube.html">F.11. cube</a></span></dt><dd><dl><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.5">F.11.1. Syntax</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.6">F.11.2. Precision</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.7">F.11.3. Usage</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.8">F.11.4. Defaults</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.9">F.11.5. Notes</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.10">F.11.6. Credits</a></span></dt></dl></dd><dt><span class="sect1"><a href="dblink.html">F.12. dblink</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="contrib-dblink-connect.html">dblink_connect</a></span><span class="refpurpose"> — opens a persistent connection to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-connect-u.html">dblink_connect_u</a></span><span class="refpurpose"> — opens a persistent connection to a remote database, insecurely</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-disconnect.html">dblink_disconnect</a></span><span class="refpurpose"> — closes a persistent connection to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-function.html">dblink</a></span><span class="refpurpose"> — executes a query in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-exec.html">dblink_exec</a></span><span class="refpurpose"> — executes a command in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-open.html">dblink_open</a></span><span class="refpurpose"> — opens a cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-fetch.html">dblink_fetch</a></span><span class="refpurpose"> — returns rows from an open cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-close.html">dblink_close</a></span><span class="refpurpose"> — closes a cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-connections.html">dblink_get_connections</a></span><span class="refpurpose"> — returns the names of all open named dblink connections</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-error-message.html">dblink_error_message</a></span><span class="refpurpose"> — gets last error message on the named connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-send-query.html">dblink_send_query</a></span><span class="refpurpose"> — sends an async query to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-is-busy.html">dblink_is_busy</a></span><span class="refpurpose"> — checks if connection is busy with an async query</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-notify.html">dblink_get_notify</a></span><span class="refpurpose"> — retrieve async notifications on a connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-result.html">dblink_get_result</a></span><span class="refpurpose"> — gets an async query result</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-cancel-query.html">dblink_cancel_query</a></span><span class="refpurpose"> — cancels any active query on the named connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-pkey.html">dblink_get_pkey</a></span><span class="refpurpose"> — returns the positions and field names of a relation's
+ primary key fields
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-insert.html">dblink_build_sql_insert</a></span><span class="refpurpose"> —
+ builds an INSERT statement using a local tuple, replacing the
+ primary key field values with alternative supplied values
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-delete.html">dblink_build_sql_delete</a></span><span class="refpurpose"> — builds a DELETE statement using supplied values for primary
+ key field values
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-update.html">dblink_build_sql_update</a></span><span class="refpurpose"> — builds an UPDATE statement using a local tuple, replacing
+ the primary key field values with alternative supplied values
+ </span></dt></dl></dd><dt><span class="sect1"><a href="dict-int.html">F.13. dict_int</a></span></dt><dd><dl><dt><span class="sect2"><a href="dict-int.html#id-1.11.7.22.5">F.13.1. Configuration</a></span></dt><dt><span class="sect2"><a href="dict-int.html#id-1.11.7.22.6">F.13.2. Usage</a></span></dt></dl></dd><dt><span class="sect1"><a href="dict-xsyn.html">F.14. dict_xsyn</a></span></dt><dd><dl><dt><span class="sect2"><a href="dict-xsyn.html#id-1.11.7.23.4">F.14.1. Configuration</a></span></dt><dt><span class="sect2"><a href="dict-xsyn.html#id-1.11.7.23.5">F.14.2. Usage</a></span></dt></dl></dd><dt><span class="sect1"><a href="earthdistance.html">F.15. earthdistance</a></span></dt><dd><dl><dt><span class="sect2"><a href="earthdistance.html#id-1.11.7.24.7">F.15.1. Cube-Based Earth Distances</a></span></dt><dt><span class="sect2"><a href="earthdistance.html#id-1.11.7.24.8">F.15.2. Point-Based Earth Distances</a></span></dt></dl></dd><dt><span class="sect1"><a href="file-fdw.html">F.16. file_fdw</a></span></dt><dt><span class="sect1"><a href="fuzzystrmatch.html">F.17. fuzzystrmatch</a></span></dt><dd><dl><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.6">F.17.1. Soundex</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.7">F.17.2. Levenshtein</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.8">F.17.3. Metaphone</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.9">F.17.4. Double Metaphone</a></span></dt></dl></dd><dt><span class="sect1"><a href="hstore.html">F.18. hstore</a></span></dt><dd><dl><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.5">F.18.1. <code class="type">hstore</code> External Representation</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.6">F.18.2. <code class="type">hstore</code> Operators and Functions</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.7">F.18.3. Indexes</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.8">F.18.4. Examples</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.9">F.18.5. Statistics</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.10">F.18.6. Compatibility</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.11">F.18.7. Transforms</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.12">F.18.8. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="intagg.html">F.19. intagg</a></span></dt><dd><dl><dt><span class="sect2"><a href="intagg.html#id-1.11.7.28.4">F.19.1. Functions</a></span></dt><dt><span class="sect2"><a href="intagg.html#id-1.11.7.28.5">F.19.2. Sample Uses</a></span></dt></dl></dd><dt><span class="sect1"><a href="intarray.html">F.20. intarray</a></span></dt><dd><dl><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.7">F.20.1. <code class="filename">intarray</code> Functions and Operators</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.8">F.20.2. Index Support</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.9">F.20.3. Example</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.10">F.20.4. Benchmark</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.11">F.20.5. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="isn.html">F.21. isn</a></span></dt><dd><dl><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.5">F.21.1. Data Types</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.6">F.21.2. Casts</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.7">F.21.3. Functions and Operators</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.8">F.21.4. Examples</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.9">F.21.5. Bibliography</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.10">F.21.6. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="lo.html">F.22. lo</a></span></dt><dd><dl><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.5">F.22.1. Rationale</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.6">F.22.2. How to Use It</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.7">F.22.3. Limitations</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.8">F.22.4. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="ltree.html">F.23. ltree</a></span></dt><dd><dl><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.5">F.23.1. Definitions</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.6">F.23.2. Operators and Functions</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.7">F.23.3. Indexes</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.8">F.23.4. Example</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.9">F.23.5. Transforms</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.10">F.23.6. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="oldsnapshot.html">F.24. old_snapshot</a></span></dt><dd><dl><dt><span class="sect2"><a href="oldsnapshot.html#id-1.11.7.33.4">F.24.1. Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="pageinspect.html">F.25. pageinspect</a></span></dt><dd><dl><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.4">F.25.1. General Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.5">F.25.2. Heap Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.6">F.25.3. B-Tree Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.7">F.25.4. BRIN Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.8">F.25.5. GIN Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.9">F.25.6. GiST Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.10">F.25.7. Hash Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="passwordcheck.html">F.26. passwordcheck</a></span></dt><dt><span class="sect1"><a href="pgbuffercache.html">F.27. pg_buffercache</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.7">F.27.1. The <code class="structname">pg_buffercache</code> View</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.8">F.27.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.9">F.27.3. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgcrypto.html">F.28. pgcrypto</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.7">F.28.1. General Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.8">F.28.2. Password Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.9">F.28.3. PGP Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.10">F.28.4. Raw Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.11">F.28.5. Random-Data Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.12">F.28.6. Notes</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.13">F.28.7. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgfreespacemap.html">F.29. pg_freespacemap</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.5">F.29.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.6">F.29.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.7">F.29.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgprewarm.html">F.30. pg_prewarm</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.4">F.30.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.5">F.30.2. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.6">F.30.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgrowlocks.html">F.31. pgrowlocks</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.5">F.31.1. Overview</a></span></dt><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.6">F.31.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.7">F.31.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgstatstatements.html">F.32. pg_stat_statements</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.6">F.32.1. The <code class="structname">pg_stat_statements</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.7">F.32.2. The <code class="structname">pg_stat_statements_info</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.8">F.32.3. Functions</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.9">F.32.4. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.10">F.32.5. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.11">F.32.6. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgstattuple.html">F.33. pgstattuple</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgstattuple.html#id-1.11.7.42.5">F.33.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgstattuple.html#id-1.11.7.42.6">F.33.2. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgsurgery.html">F.34. pg_surgery</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgsurgery.html#id-1.11.7.43.4">F.34.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgsurgery.html#id-1.11.7.43.5">F.34.2. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgtrgm.html">F.35. pg_trgm</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.5">F.35.1. Trigram (or Trigraph) Concepts</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.6">F.35.2. Functions and Operators</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.7">F.35.3. GUC Parameters</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.8">F.35.4. Index Support</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.9">F.35.5. Text Search Integration</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.10">F.35.6. References</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.11">F.35.7. Authors</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgvisibility.html">F.36. pg_visibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgvisibility.html#id-1.11.7.45.6">F.36.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgvisibility.html#id-1.11.7.45.7">F.36.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="pgwalinspect.html">F.37. pg_walinspect</a></span></dt><dd><dl><dt><span class="sect2"><a href="pgwalinspect.html#id-1.11.7.46.8">F.37.1. General Functions</a></span></dt><dt><span class="sect2"><a href="pgwalinspect.html#id-1.11.7.46.9">F.37.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="postgres-fdw.html">F.38. postgres_fdw</a></span></dt><dd><dl><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.11">F.38.1. FDW Options of postgres_fdw</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.12">F.38.2. Functions</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.13">F.38.3. Connection Management</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.14">F.38.4. Transaction Management</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.15">F.38.5. Remote Query Optimization</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.16">F.38.6. Remote Query Execution Environment</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.17">F.38.7. Cross-Version Compatibility</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.18">F.38.8. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.19">F.38.9. Examples</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.20">F.38.10. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="seg.html">F.39. seg</a></span></dt><dd><dl><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.5">F.39.1. Rationale</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.6">F.39.2. Syntax</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.7">F.39.3. Precision</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.8">F.39.4. Usage</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.9">F.39.5. Notes</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.10">F.39.6. Credits</a></span></dt></dl></dd><dt><span class="sect1"><a href="sepgsql.html">F.40. sepgsql</a></span></dt><dd><dl><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-OVERVIEW">F.40.1. Overview</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-INSTALLATION">F.40.2. Installation</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-REGRESSION">F.40.3. Regression Tests</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-PARAMETERS">F.40.4. GUC Parameters</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-FEATURES">F.40.5. Features</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-FUNCTIONS">F.40.6. Sepgsql Functions</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-LIMITATIONS">F.40.7. Limitations</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-RESOURCES">F.40.8. External Resources</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-AUTHOR">F.40.9. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="contrib-spi.html">F.41. spi</a></span></dt><dd><dl><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.5">F.41.1. refint — Functions for Implementing Referential Integrity</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.6">F.41.2. autoinc — Functions for Autoincrementing Fields</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.7">F.41.3. insert_username — Functions for Tracking Who Changed a Table</a></span></dt><dt><span class="sect2"><a href="contrib-spi.html#id-1.11.7.50.8">F.41.4. moddatetime — Functions for Tracking Last Modification Time</a></span></dt></dl></dd><dt><span class="sect1"><a href="sslinfo.html">F.42. sslinfo</a></span></dt><dd><dl><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.6">F.42.1. Functions Provided</a></span></dt><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.7">F.42.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="tablefunc.html">F.43. tablefunc</a></span></dt><dd><dl><dt><span class="sect2"><a href="tablefunc.html#id-1.11.7.52.5">F.43.1. Functions Provided</a></span></dt><dt><span class="sect2"><a href="tablefunc.html#id-1.11.7.52.6">F.43.2. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="tcn.html">F.44. tcn</a></span></dt><dt><span class="sect1"><a href="test-decoding.html">F.45. test_decoding</a></span></dt><dt><span class="sect1"><a href="tsm-system-rows.html">F.46. tsm_system_rows</a></span></dt><dd><dl><dt><span class="sect2"><a href="tsm-system-rows.html#id-1.11.7.55.8">F.46.1. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="tsm-system-time.html">F.47. tsm_system_time</a></span></dt><dd><dl><dt><span class="sect2"><a href="tsm-system-time.html#id-1.11.7.56.8">F.47.1. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="unaccent.html">F.48. unaccent</a></span></dt><dd><dl><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.6">F.48.1. Configuration</a></span></dt><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.7">F.48.2. Usage</a></span></dt><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.8">F.48.3. Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="uuid-ossp.html">F.49. uuid-ossp</a></span></dt><dd><dl><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.5">F.49.1. <code class="literal">uuid-ossp</code> Functions</a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.6">F.49.2. Building <code class="filename">uuid-ossp</code></a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.7">F.49.3. Author</a></span></dt></dl></dd><dt><span class="sect1"><a href="xml2.html">F.50. xml2</a></span></dt><dd><dl><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.4">F.50.1. Deprecation Notice</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.5">F.50.2. Description of Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.6">F.50.3. <code class="literal">xpath_table</code></a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.7">F.50.4. XSLT Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.8">F.50.5. Author</a></span></dt></dl></dd></dl></div><p>
+ This appendix and the next one contain information regarding the modules that
+ can be found in the <code class="literal">contrib</code> directory of the
+ <span class="productname">PostgreSQL</span> distribution.
+ These include porting tools, analysis utilities,
+ and plug-in features that are not part of the core PostgreSQL system,
+ mainly because they address a limited audience or are too experimental
+ to be part of the main source tree. This does not preclude their
+ usefulness.
+ </p><p>
+ This appendix covers extensions and other server plug-in modules found in
+ <code class="literal">contrib</code>. <a class="xref" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Appendix G</a> covers utility
+ programs.
+ </p><p>
+ When building from the source distribution, these components are not built
+ automatically, unless you build the "world" target
+ (see <a class="xref" href="install-procedure.html#BUILD" title="Build">Step 2</a>).
+ You can build and install all of them by running:
+</p><pre class="screen">
+<strong class="userinput"><code>make</code></strong>
+<strong class="userinput"><code>make install</code></strong>
+</pre><p>
+ in the <code class="literal">contrib</code> directory of a configured source tree;
+ or to build and install
+ just one selected module, do the same in that module's subdirectory.
+ Many of the modules have regression tests, which can be executed by
+ running:
+</p><pre class="screen">
+<strong class="userinput"><code>make check</code></strong>
+</pre><p>
+ before installation or
+</p><pre class="screen">
+<strong class="userinput"><code>make installcheck</code></strong>
+</pre><p>
+ once you have a <span class="productname">PostgreSQL</span> server running.
+ </p><p>
+ If you are using a pre-packaged version of <span class="productname">PostgreSQL</span>,
+ these modules are typically made available as a separate subpackage,
+ such as <code class="literal">postgresql-contrib</code>.
+ </p><p>
+ Many modules supply new user-defined functions, operators, or types.
+ 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.
+ This is done by executing
+ a <a class="xref" href="sql-createextension.html" title="CREATE EXTENSION"><span class="refentrytitle">CREATE EXTENSION</span></a> command. In a fresh database,
+ you can simply do
+
+</p><pre class="programlisting">
+CREATE EXTENSION <em class="replaceable"><code>module_name</code></em>;
+</pre><p>
+
+ This command registers the new SQL objects in the current database only,
+ so you need to run it in each database that you want
+ the module's facilities to be available in. Alternatively, run it in
+ database <code class="literal">template1</code> so that the extension will be copied into
+ subsequently-created databases by default.
+ </p><p>
+ For all these modules, <code class="command">CREATE EXTENSION</code> must be run
+ by a database superuser, unless the module is
+ considered <span class="quote">“<span class="quote">trusted</span>”</span>, in which case it can be run by any
+ user who has <code class="literal">CREATE</code> privilege on the current
+ database. Modules that are trusted are identified as such in the
+ sections that follow. Generally, trusted modules are ones that cannot
+ provide access to outside-the-database functionality.
+ </p><p>
+ Many modules allow you to install their objects in a schema of your
+ choice. To do that, add <code class="literal">SCHEMA
+ <em class="replaceable"><code>schema_name</code></em></code> to the <code class="command">CREATE EXTENSION</code>
+ command. By default, the objects will be placed in your current creation
+ target schema, which in turn defaults to <code class="literal">public</code>.
+ </p><p>
+ Note, however, that some of these modules are not <span class="quote">“<span class="quote">extensions</span>”</span>
+ in this sense, but are loaded into the server in some other way, for instance
+ by way of
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>. See the documentation of each
+ module for details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-prior.html" title="E.7. Prior Releases">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adminpack.html" title="F.1. adminpack">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.7. Prior Releases </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.1. adminpack</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/creating-cluster.html b/doc/src/sgml/html/creating-cluster.html
new file mode 100644
index 0000000..3d87f20
--- /dev/null
+++ b/doc/src/sgml/html/creating-cluster.html
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.2. Creating a Database Cluster</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="postgres-user.html" title="19.1. The PostgreSQL User Account" /><link rel="next" href="server-start.html" title="19.3. Starting the Database Server" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.2. Creating a Database Cluster</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="server-start.html" title="19.3. Starting the Database Server">Next</a></td></tr></table><hr /></div><div class="sect1" id="CREATING-CLUSTER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.2. Creating a Database Cluster</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="creating-cluster.html#CREATING-CLUSTER-MOUNT-POINTS">19.2.1. Use of Secondary File Systems</a></span></dt><dt><span class="sect2"><a href="creating-cluster.html#CREATING-CLUSTER-FILESYSTEM">19.2.2. File Systems</a></span></dt></dl></div><a id="id-1.6.6.5.2" class="indexterm"></a><a id="id-1.6.6.5.3" class="indexterm"></a><p>
+ Before you can do anything, you must initialize a database storage
+ area on disk. We call this a <em class="firstterm">database cluster</em>.
+ (The <acronym class="acronym">SQL</acronym> standard uses the term catalog cluster.) A
+ database cluster is a collection of databases that is managed by a
+ single instance of a running database server. After initialization, a
+ database cluster will contain a database named <code class="literal">postgres</code>,
+ which is meant as a default database for use by utilities, users and third
+ party applications. The database server itself does not require the
+ <code class="literal">postgres</code> database to exist, but many external utility
+ programs assume it exists. There are two more databases created within
+ each cluster during initialization, named <code class="literal">template1</code>
+ and <code class="literal">template0</code>. As the names suggest, these will be
+ used as templates for subsequently-created databases; they should not be
+ used for actual work. (See <a class="xref" href="managing-databases.html" title="Chapter 23. Managing Databases">Chapter 23</a> for
+ information about creating new databases within a cluster.)
+ </p><p>
+ In file system terms, a database cluster is a single directory
+ under which all data will be stored. We call this the <em class="firstterm">data
+ directory</em> or <em class="firstterm">data area</em>. It is
+ completely up to you where you choose to store your data. There is no
+ default, although locations such as
+ <code class="filename">/usr/local/pgsql/data</code> or
+ <code class="filename">/var/lib/pgsql/data</code> are popular.
+ The data directory must be initialized before being used, using the program
+ <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a><a id="id-1.6.6.5.5.6" class="indexterm"></a>
+ which is installed with <span class="productname">PostgreSQL</span>.
+ </p><p>
+ If you are using a pre-packaged version
+ of <span class="productname">PostgreSQL</span>, it may well have a specific
+ convention for where to place the data directory, and it may also
+ provide a script for creating the data directory. In that case you
+ should use that script in preference to
+ running <code class="command">initdb</code> directly.
+ Consult the package-level documentation for details.
+ </p><p>
+ To initialize a database cluster manually,
+ run <code class="command">initdb</code> and specify the desired
+ file system location of the database cluster with the
+ <code class="option">-D</code> option, for example:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>initdb -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ Note that you must execute this command while logged into the
+ <span class="productname">PostgreSQL</span> user account, which is
+ described in the previous section.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ As an alternative to the <code class="option">-D</code> option, you can set
+ the environment variable <code class="envar">PGDATA</code>.
+ <a id="id-1.6.6.5.8.1.3" class="indexterm"></a>
+ </p></div><p>
+ Alternatively, you can run <code class="command">initdb</code> via
+ the <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>
+ program<a id="id-1.6.6.5.9.3" class="indexterm"></a> like so:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -D /usr/local/pgsql/data initdb</code></strong>
+</pre><p>
+ This may be more intuitive if you are
+ using <code class="command">pg_ctl</code> for starting and stopping the
+ server (see <a class="xref" href="server-start.html" title="19.3. Starting the Database Server">Section 19.3</a>), so
+ that <code class="command">pg_ctl</code> would be the sole command you use
+ for managing the database server instance.
+ </p><p>
+ <code class="command">initdb</code> will attempt to create the directory you
+ specify if it does not already exist. Of course, this will fail if
+ <code class="command">initdb</code> does not have permissions to write in the
+ parent directory. It's generally recommendable that the
+ <span class="productname">PostgreSQL</span> user own not just the data
+ directory but its parent directory as well, so that this should not
+ be a problem. If the desired parent directory doesn't exist either,
+ you will need to create it first, using root privileges if the
+ grandparent directory isn't writable. So the process might look
+ like this:
+</p><pre class="screen">
+root# <strong class="userinput"><code>mkdir /usr/local/pgsql</code></strong>
+root# <strong class="userinput"><code>chown postgres /usr/local/pgsql</code></strong>
+root# <strong class="userinput"><code>su postgres</code></strong>
+postgres$ <strong class="userinput"><code>initdb -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ </p><p>
+ <code class="command">initdb</code> will refuse to run if the data directory
+ exists and already contains files; this is to prevent accidentally
+ overwriting an existing installation.
+ </p><p>
+ Because the data directory contains all the data stored in the
+ database, it is essential that it be secured from unauthorized
+ access. <code class="command">initdb</code> therefore revokes access
+ permissions from everyone but the
+ <span class="productname">PostgreSQL</span> user, and optionally, group.
+ Group access, when enabled, is read-only. This allows an unprivileged
+ user in the same group as the cluster owner to take a backup of the
+ cluster data or perform other operations that only require read access.
+ </p><p>
+ Note that enabling or disabling group access on an existing cluster requires
+ the cluster to be shut down and the appropriate mode to be set on all
+ directories and files before restarting
+ <span class="productname">PostgreSQL</span>. Otherwise, a mix of modes might
+ exist in the data directory. For clusters that allow access only by the
+ owner, the appropriate modes are <code class="literal">0700</code> for directories
+ and <code class="literal">0600</code> for files. For clusters that also allow
+ reads by the group, the appropriate modes are <code class="literal">0750</code>
+ for directories and <code class="literal">0640</code> for files.
+ </p><p>
+ However, while the directory contents are secure, the default
+ client authentication setup allows any local user to connect to the
+ database and even become the database superuser. If you do not
+ trust other local users, we recommend you use one of
+ <code class="command">initdb</code>'s <code class="option">-W</code>, <code class="option">--pwprompt</code>
+ or <code class="option">--pwfile</code> options to assign a password to the
+ database superuser.<a id="id-1.6.6.5.14.5" class="indexterm"></a>
+ Also, specify <code class="option">-A scram-sha-256</code>
+ so that the default <code class="literal">trust</code> authentication
+ mode is not used; or modify the generated <code class="filename">pg_hba.conf</code>
+ file after running <code class="command">initdb</code>, but
+ <span class="emphasis"><em>before</em></span> you start the server for the first time. (Other
+ reasonable approaches include using <code class="literal">peer</code> authentication
+ or file system permissions to restrict connections. See <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> for more information.)
+ </p><p>
+ <code class="command">initdb</code> also initializes the default
+ locale<a id="id-1.6.6.5.15.2" class="indexterm"></a> for the database cluster.
+ Normally, it will just take the locale settings in the environment
+ and apply them to the initialized database. It is possible to
+ specify a different locale for the database; more information about
+ that can be found in <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>. The default sort order used
+ within the particular database cluster is set by
+ <code class="command">initdb</code>, and while you can create new databases using
+ different sort order, the order used in the template databases that initdb
+ creates cannot be changed without dropping and recreating them.
+ There is also a performance impact for using locales
+ other than <code class="literal">C</code> or <code class="literal">POSIX</code>. Therefore, it is
+ important to make this choice correctly the first time.
+ </p><p>
+ <code class="command">initdb</code> also sets the default character set encoding
+ for the database cluster. Normally this should be chosen to match the
+ locale setting. For details see <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>.
+ </p><p>
+ Non-<code class="literal">C</code> and non-<code class="literal">POSIX</code> locales rely on the
+ operating system's collation library for character set ordering.
+ This controls the ordering of keys stored in indexes. For this reason,
+ a cluster cannot switch to an incompatible collation library version,
+ either through snapshot restore, binary streaming replication, a
+ different operating system, or an operating system upgrade.
+ </p><div class="sect2" id="CREATING-CLUSTER-MOUNT-POINTS"><div class="titlepage"><div><div><h3 class="title">19.2.1. Use of Secondary File Systems</h3></div></div></div><a id="id-1.6.6.5.18.2" class="indexterm"></a><p>
+ Many installations create their database clusters on file systems
+ (volumes) other than the machine's <span class="quote">“<span class="quote">root</span>”</span> volume. If you
+ choose to do this, it is not advisable to try to use the secondary
+ volume's topmost directory (mount point) as the data directory.
+ Best practice is to create a directory within the mount-point
+ directory that is owned by the <span class="productname">PostgreSQL</span>
+ user, and then create the data directory within that. This avoids
+ permissions problems, particularly for operations such
+ as <span class="application">pg_upgrade</span>, and it also ensures clean failures if
+ the secondary volume is taken offline.
+ </p></div><div class="sect2" id="CREATING-CLUSTER-FILESYSTEM"><div class="titlepage"><div><div><h3 class="title">19.2.2. File Systems</h3></div></div></div><p>
+ Generally, any file system with POSIX semantics can be used for
+ PostgreSQL. Users prefer different file systems for a variety of reasons,
+ including vendor support, performance, and familiarity. Experience
+ suggests that, all other things being equal, one should not expect major
+ performance or behavior changes merely from switching file systems or
+ making minor file system configuration changes.
+ </p><div class="sect3" id="CREATING-CLUSTER-NFS"><div class="titlepage"><div><div><h4 class="title">19.2.2.1. NFS</h4></div></div></div><a id="id-1.6.6.5.19.3.2" class="indexterm"></a><p>
+ It is possible to use an <acronym class="acronym">NFS</acronym> file system for storing
+ the <span class="productname">PostgreSQL</span> data directory.
+ <span class="productname">PostgreSQL</span> does nothing special for
+ <acronym class="acronym">NFS</acronym> file systems, meaning it assumes
+ <acronym class="acronym">NFS</acronym> behaves exactly like locally-connected drives.
+ <span class="productname">PostgreSQL</span> does not use any functionality that
+ is known to have nonstandard behavior on <acronym class="acronym">NFS</acronym>, such as
+ file locking.
+ </p><p>
+ The only firm requirement for using <acronym class="acronym">NFS</acronym> with
+ <span class="productname">PostgreSQL</span> is that the file system is mounted
+ using the <code class="literal">hard</code> option. With the
+ <code class="literal">hard</code> option, processes can <span class="quote">“<span class="quote">hang</span>”</span>
+ indefinitely if there are network problems, so this configuration will
+ require a careful monitoring setup. The <code class="literal">soft</code> option
+ will interrupt system calls in case of network problems, but
+ <span class="productname">PostgreSQL</span> will not repeat system calls
+ interrupted in this way, so any such interruption will result in an I/O
+ error being reported.
+ </p><p>
+ It is not necessary to use the <code class="literal">sync</code> mount option. The
+ behavior of the <code class="literal">async</code> option is sufficient, since
+ <span class="productname">PostgreSQL</span> issues <code class="literal">fsync</code>
+ calls at appropriate times to flush the write caches. (This is analogous
+ to how it works on a local file system.) However, it is strongly
+ recommended to use the <code class="literal">sync</code> export option on the NFS
+ <span class="emphasis"><em>server</em></span> on systems where it exists (mainly Linux).
+ Otherwise, an <code class="literal">fsync</code> or equivalent on the NFS client is
+ not actually guaranteed to reach permanent storage on the server, which
+ could cause corruption similar to running with the parameter <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> off. The defaults of these mount and export
+ options differ between vendors and versions, so it is recommended to
+ check and perhaps specify them explicitly in any case to avoid any
+ ambiguity.
+ </p><p>
+ In some cases, an external storage product can be accessed either via NFS
+ or a lower-level protocol such as iSCSI. In the latter case, the storage
+ appears as a block device and any available file system can be created on
+ it. That approach might relieve the DBA from having to deal with some of
+ the idiosyncrasies of NFS, but of course the complexity of managing
+ remote storage then happens at other levels.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="server-start.html" title="19.3. Starting the Database Server">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.1. The <span class="productname">PostgreSQL</span> User Account </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.3. Starting the Database Server</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/cube.html b/doc/src/sgml/html/cube.html
new file mode 100644
index 0000000..19db46a
--- /dev/null
+++ b/doc/src/sgml/html/cube.html
@@ -0,0 +1,391 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.11. cube</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="citext.html" title="F.10. citext" /><link rel="next" href="dblink.html" title="F.12. dblink" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.11. cube</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="citext.html" title="F.10. citext">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dblink.html" title="F.12. dblink">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUBE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.11. cube</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.5">F.11.1. Syntax</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.6">F.11.2. Precision</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.7">F.11.3. Usage</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.8">F.11.4. Defaults</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.9">F.11.5. Notes</a></span></dt><dt><span class="sect2"><a href="cube.html#id-1.11.7.20.10">F.11.6. Credits</a></span></dt></dl></div><a id="id-1.11.7.20.2" class="indexterm"></a><p>
+ This module implements a data type <code class="type">cube</code> for
+ representing multidimensional cubes.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.20.5"><div class="titlepage"><div><div><h3 class="title">F.11.1. Syntax</h3></div></div></div><p>
+ <a class="xref" href="cube.html#CUBE-REPR-TABLE" title="Table F.2. Cube External Representations">Table F.2</a> shows the valid external
+ representations for the <code class="type">cube</code>
+ type. <em class="replaceable"><code>x</code></em>, <em class="replaceable"><code>y</code></em>, etc. denote
+ floating-point numbers.
+ </p><div class="table" id="CUBE-REPR-TABLE"><p class="title"><strong>Table F.2. Cube External Representations</strong></p><div class="table-contents"><table class="table" summary="Cube External Representations" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>External Syntax</th><th>Meaning</th></tr></thead><tbody><tr><td><code class="literal"><em class="replaceable"><code>x</code></em></code></td><td>A one-dimensional point
+ (or, zero-length one-dimensional interval)
+ </td></tr><tr><td><code class="literal">(<em class="replaceable"><code>x</code></em>)</code></td><td>Same as above</td></tr><tr><td><code class="literal"><em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>x2</code></em>,...,<em class="replaceable"><code>xn</code></em></code></td><td>A point in n-dimensional space, represented internally as a
+ zero-volume cube
+ </td></tr><tr><td><code class="literal">(<em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>x2</code></em>,...,<em class="replaceable"><code>xn</code></em>)</code></td><td>Same as above</td></tr><tr><td><code class="literal">(<em class="replaceable"><code>x</code></em>),(<em class="replaceable"><code>y</code></em>)</code></td><td>A one-dimensional interval starting at <em class="replaceable"><code>x</code></em> and ending at <em class="replaceable"><code>y</code></em> or vice versa; the
+ order does not matter
+ </td></tr><tr><td><code class="literal">[(<em class="replaceable"><code>x</code></em>),(<em class="replaceable"><code>y</code></em>)]</code></td><td>Same as above</td></tr><tr><td><code class="literal">(<em class="replaceable"><code>x1</code></em>,...,<em class="replaceable"><code>xn</code></em>),(<em class="replaceable"><code>y1</code></em>,...,<em class="replaceable"><code>yn</code></em>)</code></td><td>An n-dimensional cube represented by a pair of its diagonally
+ opposite corners
+ </td></tr><tr><td><code class="literal">[(<em class="replaceable"><code>x1</code></em>,...,<em class="replaceable"><code>xn</code></em>),(<em class="replaceable"><code>y1</code></em>,...,<em class="replaceable"><code>yn</code></em>)]</code></td><td>Same as above</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ It does not matter which order the opposite corners of a cube are
+ entered in. The <code class="type">cube</code> functions
+ automatically swap values if needed to create a uniform
+ <span class="quote">“<span class="quote">lower left — upper right</span>”</span> internal representation.
+ When the corners coincide, <code class="type">cube</code> stores only one corner
+ along with an <span class="quote">“<span class="quote">is point</span>”</span> flag to avoid wasting space.
+ </p><p>
+ White space is ignored on input, so
+ <code class="literal">[(<em class="replaceable"><code>x</code></em>),(<em class="replaceable"><code>y</code></em>)]</code> is the same as
+ <code class="literal">[ ( <em class="replaceable"><code>x</code></em> ), ( <em class="replaceable"><code>y</code></em> ) ]</code>.
+ </p></div><div class="sect2" id="id-1.11.7.20.6"><div class="titlepage"><div><div><h3 class="title">F.11.2. Precision</h3></div></div></div><p>
+ Values are stored internally as 64-bit floating point numbers. This means
+ that numbers with more than about 16 significant digits will be truncated.
+ </p></div><div class="sect2" id="id-1.11.7.20.7"><div class="titlepage"><div><div><h3 class="title">F.11.3. Usage</h3></div></div></div><p>
+ <a class="xref" href="cube.html#CUBE-OPERATORS-TABLE" title="Table F.3. Cube Operators">Table F.3</a> shows the specialized operators
+ provided for type <code class="type">cube</code>.
+ </p><div class="table" id="CUBE-OPERATORS-TABLE"><p class="title"><strong>Table F.3. Cube Operators</strong></p><div class="table-contents"><table class="table" summary="Cube Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">&amp;&amp;</code> <code class="type">cube</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do the cubes overlap?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">@&gt;</code> <code class="type">cube</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first cube contain the second?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">&lt;@</code> <code class="type">cube</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first cube contained in the second?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">-&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Extracts the <em class="parameter"><code>n</code></em>-th coordinate of the cube
+ (counting from 1).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">~&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Extracts the <em class="parameter"><code>n</code></em>-th coordinate of the cube,
+ counting in the following way: <em class="parameter"><code>n</code></em> = 2
+ * <em class="parameter"><code>k</code></em> - 1 means lower bound
+ of <em class="parameter"><code>k</code></em>-th dimension, <em class="parameter"><code>n</code></em> = 2
+ * <em class="parameter"><code>k</code></em> means upper bound of
+ <em class="parameter"><code>k</code></em>-th dimension. Negative
+ <em class="parameter"><code>n</code></em> denotes the inverse value of the corresponding
+ positive coordinate. This operator is designed for KNN-GiST support.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">&lt;-&gt;</code> <code class="type">cube</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Computes the Euclidean distance between the two cubes.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">&lt;#&gt;</code> <code class="type">cube</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Computes the taxicab (L-1 metric) distance between the two cubes.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">cube</code> <code class="literal">&lt;=&gt;</code> <code class="type">cube</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Computes the Chebyshev (L-inf metric) distance between the two cubes.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In addition to the above operators, the usual comparison
+ operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are
+ available for type <code class="type">cube</code>. These
+ operators first compare the first coordinates, and if those are equal,
+ compare the second coordinates, etc. They exist mainly to support the
+ b-tree index operator class for <code class="type">cube</code>, which can be useful for
+ example if you would like a UNIQUE constraint on a <code class="type">cube</code> column.
+ Otherwise, this ordering is not of much practical use.
+ </p><p>
+ The <code class="filename">cube</code> module also provides a GiST index operator class for
+ <code class="type">cube</code> values.
+ A <code class="type">cube</code> GiST index can be used to search for values using the
+ <code class="literal">=</code>, <code class="literal">&amp;&amp;</code>, <code class="literal">@&gt;</code>, and
+ <code class="literal">&lt;@</code> operators in <code class="literal">WHERE</code> clauses.
+ </p><p>
+ In addition, a <code class="type">cube</code> GiST index can be used to find nearest
+ neighbors using the metric operators
+ <code class="literal">&lt;-&gt;</code>, <code class="literal">&lt;#&gt;</code>, and
+ <code class="literal">&lt;=&gt;</code> in <code class="literal">ORDER BY</code> clauses.
+ For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5)
+ could be found efficiently with:
+</p><pre class="programlisting">
+SELECT c FROM test ORDER BY c &lt;-&gt; cube(array[0.5,0.5,0.5]) LIMIT 1;
+</pre><p>
+ </p><p>
+ The <code class="literal">~&gt;</code> operator can also be used in this way to
+ efficiently retrieve the first few values sorted by a selected coordinate.
+ For example, to get the first few cubes ordered by the first coordinate
+ (lower left corner) ascending one could use the following query:
+</p><pre class="programlisting">
+SELECT c FROM test ORDER BY c ~&gt; 1 LIMIT 5;
+</pre><p>
+ And to get 2-D cubes ordered by the first coordinate of the upper right
+ corner descending:
+</p><pre class="programlisting">
+SELECT c FROM test ORDER BY c ~&gt; 3 DESC LIMIT 5;
+</pre><p>
+ </p><p>
+ <a class="xref" href="cube.html#CUBE-FUNCTIONS-TABLE" title="Table F.4. Cube Functions">Table F.4</a> shows the available functions.
+ </p><div class="table" id="CUBE-FUNCTIONS-TABLE"><p class="title"><strong>Table F.4. Cube Functions</strong></p><div class="table-contents"><table class="table" summary="Cube Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">float8</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a one dimensional cube with both coordinates the same.
+ </p>
+ <p>
+ <code class="literal">cube(1)</code>
+ → <code class="returnvalue">(1)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">float8</code>, <code class="type">float8</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a one dimensional cube.
+ </p>
+ <p>
+ <code class="literal">cube(1, 2)</code>
+ → <code class="returnvalue">(1),(2)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">float8[]</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a zero-volume cube using the coordinates defined by the array.
+ </p>
+ <p>
+ <code class="literal">cube(ARRAY[1,2,3])</code>
+ → <code class="returnvalue">(1, 2, 3)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">float8[]</code>, <code class="type">float8[]</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a cube with upper right and lower left coordinates as defined by
+ the two arrays, which must be of the same length.
+ </p>
+ <p>
+ <code class="literal">cube(ARRAY[1,2], ARRAY[3,4])</code>
+ → <code class="returnvalue">(1, 2),(3, 4)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">cube</code>, <code class="type">float8</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a new cube by adding a dimension on to an existing cube,
+ with the same values for both endpoints of the new coordinate. This
+ is useful for building cubes piece by piece from calculated values.
+ </p>
+ <p>
+ <code class="literal">cube('(1,2),(3,4)'::cube, 5)</code>
+ → <code class="returnvalue">(1, 2, 5),(3, 4, 5)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube</code> ( <code class="type">cube</code>, <code class="type">float8</code>, <code class="type">float8</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a new cube by adding a dimension on to an existing cube. This is
+ useful for building cubes piece by piece from calculated values.
+ </p>
+ <p>
+ <code class="literal">cube('(1,2),(3,4)'::cube, 5, 6)</code>
+ → <code class="returnvalue">(1, 2, 5),(3, 4, 6)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_dim</code> ( <code class="type">cube</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of dimensions of the cube.
+ </p>
+ <p>
+ <code class="literal">cube_dim('(1,2),(3,4)')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_ll_coord</code> ( <code class="type">cube</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the <em class="parameter"><code>n</code></em>-th coordinate value for the lower
+ left corner of the cube.
+ </p>
+ <p>
+ <code class="literal">cube_ll_coord('(1,2),(3,4)', 2)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_ur_coord</code> ( <code class="type">cube</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the <em class="parameter"><code>n</code></em>-th coordinate value for the
+ upper right corner of the cube.
+ </p>
+ <p>
+ <code class="literal">cube_ur_coord('(1,2),(3,4)', 2)</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_is_point</code> ( <code class="type">cube</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if the cube is a point, that is,
+ the two defining corners are the same.
+ </p>
+ <p>
+ <code class="literal">cube_is_point(cube(1,1))</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_distance</code> ( <code class="type">cube</code>, <code class="type">cube</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the distance between two cubes. If both
+ cubes are points, this is the normal distance function.
+ </p>
+ <p>
+ <code class="literal">cube_distance('(1,2)', '(3,4)')</code>
+ → <code class="returnvalue">2.8284271247461903</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_subset</code> ( <code class="type">cube</code>, <code class="type">integer[]</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Makes a new cube from an existing cube, using a list of
+ dimension indexes from an array. Can be used to extract the endpoints
+ of a single dimension, or to drop dimensions, or to reorder them as
+ desired.
+ </p>
+ <p>
+ <code class="literal">cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2])</code>
+ → <code class="returnvalue">(3),(7)</code>
+ </p>
+ <p>
+ <code class="literal">cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1])</code>
+ → <code class="returnvalue">(5, 3, 1, 1),(8, 7, 6, 6)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_union</code> ( <code class="type">cube</code>, <code class="type">cube</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Produces the union of two cubes.
+ </p>
+ <p>
+ <code class="literal">cube_union('(1,2)', '(3,4)')</code>
+ → <code class="returnvalue">(1, 2),(3, 4)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_inter</code> ( <code class="type">cube</code>, <code class="type">cube</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Produces the intersection of two cubes.
+ </p>
+ <p>
+ <code class="literal">cube_inter('(1,2)', '(3,4)')</code>
+ → <code class="returnvalue">(3, 4),(1, 2)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">cube_enlarge</code> ( <em class="parameter"><code>c</code></em> <code class="type">cube</code>, <em class="parameter"><code>r</code></em> <code class="type">double</code>, <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Increases the size of the cube by the specified
+ radius <em class="parameter"><code>r</code></em> in at least <em class="parameter"><code>n</code></em>
+ dimensions. If the radius is negative the cube is shrunk instead.
+ All defined dimensions are changed by the
+ radius <em class="parameter"><code>r</code></em>. Lower-left coordinates are decreased
+ by <em class="parameter"><code>r</code></em> and upper-right coordinates are increased
+ by <em class="parameter"><code>r</code></em>. If a lower-left coordinate is increased
+ to more than the corresponding upper-right coordinate (this can only
+ happen when <em class="parameter"><code>r</code></em> &lt; 0) than both coordinates are
+ set to their average. If <em class="parameter"><code>n</code></em> is greater than the
+ number of defined dimensions and the cube is being enlarged
+ (<em class="parameter"><code>r</code></em> &gt; 0), then extra dimensions are added to
+ make <em class="parameter"><code>n</code></em> altogether; 0 is used as the initial
+ value for the extra coordinates. This function is useful for creating
+ bounding boxes around a point for searching for nearby points.
+ </p>
+ <p>
+ <code class="literal">cube_enlarge('(1,2),(3,4)', 0.5, 3)</code>
+ → <code class="returnvalue">(0.5, 1.5, -0.5),(3.5, 4.5, 0.5)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.20.8"><div class="titlepage"><div><div><h3 class="title">F.11.4. Defaults</h3></div></div></div><p>
+ I believe this union:
+ </p><pre class="programlisting">
+select cube_union('(0,5,2),(2,3,1)', '0');
+cube_union
+-------------------
+(0, 0, 0),(2, 5, 2)
+(1 row)
+</pre><p>
+ does not contradict common sense, neither does the intersection
+ </p><pre class="programlisting">
+select cube_inter('(0,-1),(1,1)', '(-2),(2)');
+cube_inter
+-------------
+(0, 0),(1, 0)
+(1 row)
+</pre><p>
+ In all binary operations on differently-dimensioned cubes, I assume the
+ lower-dimensional one to be a Cartesian projection, i. e., having zeroes
+ in place of coordinates omitted in the string representation. The above
+ examples are equivalent to:
+ </p><pre class="programlisting">
+cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)');
+cube_inter('(0,-1),(1,1)','(-2,0),(2,0)');
+</pre><p>
+ The following containment predicate uses the point syntax,
+ while in fact the second argument is internally represented by a box.
+ This syntax makes it unnecessary to define a separate point type
+ and functions for (box,point) predicates.
+ </p><pre class="programlisting">
+select cube_contains('(0,0),(1,1)', '0.5,0.5');
+cube_contains
+--------------
+t
+(1 row)
+</pre></div><div class="sect2" id="id-1.11.7.20.9"><div class="titlepage"><div><div><h3 class="title">F.11.5. Notes</h3></div></div></div><p>
+ For examples of usage, see the regression test <code class="filename">sql/cube.sql</code>.
+ </p><p>
+ To make it harder for people to break things, there
+ is a limit of 100 on the number of dimensions of cubes. This is set
+ in <code class="filename">cubedata.h</code> if you need something bigger.
+ </p></div><div class="sect2" id="id-1.11.7.20.10"><div class="titlepage"><div><div><h3 class="title">F.11.6. Credits</h3></div></div></div><p>
+ Original author: Gene Selkov, Jr. <code class="email">&lt;<a class="email" href="mailto:selkovjr@mcs.anl.gov">selkovjr@mcs.anl.gov</a>&gt;</code>,
+ Mathematics and Computer Science Division, Argonne National Laboratory.
+ </p><p>
+ My thanks are primarily to Prof. Joe Hellerstein
+ (<a class="ulink" href="https://dsf.berkeley.edu/jmh/" target="_top">https://dsf.berkeley.edu/jmh/</a>) for elucidating the
+ gist of the GiST (<a class="ulink" href="http://gist.cs.berkeley.edu/" target="_top">http://gist.cs.berkeley.edu/</a>), and
+ to his former student Andy Dong for his example written for Illustra.
+ I am also grateful to all Postgres developers, present and past, for
+ enabling myself to create my own world and live undisturbed in it. And I
+ would like to acknowledge my gratitude to Argonne Lab and to the
+ U.S. Department of Energy for the years of faithful support of my database
+ research.
+ </p><p>
+ Minor updates to this package were made by Bruno Wolff III
+ <code class="email">&lt;<a class="email" href="mailto:bruno@wolff.to">bruno@wolff.to</a>&gt;</code> in August/September of 2002. These include
+ changing the precision from single precision to double precision and adding
+ some new functions.
+ </p><p>
+ Additional updates were made by Joshua Reich <code class="email">&lt;<a class="email" href="mailto:josh@root.net">josh@root.net</a>&gt;</code> in
+ July 2006. These include <code class="literal">cube(float8[], float8[])</code> and
+ cleaning up the code to use the V1 call protocol instead of the deprecated
+ V0 protocol.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="citext.html" title="F.10. citext">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dblink.html" title="F.12. dblink">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.10. citext </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.12. dblink</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/custom-rmgr.html b/doc/src/sgml/html/custom-rmgr.html
new file mode 100644
index 0000000..6126fe8
--- /dev/null
+++ b/doc/src/sgml/html/custom-rmgr.html
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 66. Custom WAL Resource Managers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="generic-wal.html" title="Chapter 65. Generic WAL Records" /><link rel="next" href="btree.html" title="Chapter 67. B-Tree Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 66. Custom WAL Resource Managers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="btree.html" title="Chapter 67. B-Tree Indexes">Next</a></td></tr></table><hr /></div><div class="chapter" id="CUSTOM-RMGR"><div class="titlepage"><div><div><h2 class="title">Chapter 66. Custom WAL Resource Managers</h2></div></div></div><p>
+ This chapter explains the interface between the core
+ <span class="productname">PostgreSQL</span> system and custom WAL resource
+ managers, which enable extensions to integrate directly with the <a class="link" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log"><acronym class="acronym">WAL</acronym></a>.
+ </p><p>
+ An extension, especially a <a class="link" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Table Access
+ Method</a> or <a class="link" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Index Access Method</a>, may
+ need to use WAL for recovery, replication, and/or <a class="link" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Logical Decoding</a>. Custom resource managers
+ are a more flexible alternative to <a class="link" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Generic
+ WAL</a> (which does not support logical decoding), but more complex for
+ an extension to implement.
+ </p><p>
+ To create a new custom WAL resource manager, first define an
+ <code class="structname">RmgrData</code> structure with implementations for the
+ resource manager methods. Refer to
+ <code class="filename">src/backend/access/transam/README</code> and
+ <code class="filename">src/include/access/xlog_internal.h</code> in the
+ <span class="productname">PostgreSQL</span> source.
+</p><pre class="programlisting">
+/*
+ * Method table for resource managers.
+ *
+ * This struct must be kept in sync with the PG_RMGR definition in
+ * rmgr.c.
+ *
+ * rm_identify must return a name for the record based on xl_info (without
+ * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
+ * "VACUUM". rm_desc can then be called to obtain additional detail for the
+ * record, if available (e.g. the last block).
+ *
+ * rm_mask takes as input a page modified by the resource manager and masks
+ * out bits that shouldn't be flagged by wal_consistency_checking.
+ *
+ * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
+ * NULL, the corresponding RmgrTable entry is considered invalid.
+ */
+typedef struct RmgrData
+{
+ const char *rm_name;
+ void (*rm_redo) (XLogReaderState *record);
+ void (*rm_desc) (StringInfo buf, XLogReaderState *record);
+ const char *(*rm_identify) (uint8 info);
+ void (*rm_startup) (void);
+ void (*rm_cleanup) (void);
+ void (*rm_mask) (char *pagedata, BlockNumber blkno);
+ void (*rm_decode) (struct LogicalDecodingContext *ctx,
+ struct XLogRecordBuffer *buf);
+} RmgrData;
+</pre><p>
+ </p><p>
+ Then, register your new resource
+ manager.
+
+</p><pre class="programlisting">
+/*
+ * Register a new custom WAL resource manager.
+ *
+ * Resource manager IDs must be globally unique across all extensions. Refer
+ * to https://wiki.postgresql.org/wiki/CustomWALResourceManagers to reserve a
+ * unique RmgrId for your extension, to avoid conflicts with other extension
+ * developers. During development, use RM_EXPERIMENTAL_ID to avoid needlessly
+ * reserving a new ID.
+ */
+extern void RegisterCustomRmgr(RmgrId rmid, RmgrData *rmgr);
+</pre><p>
+ <code class="function">RegisterCustomRmgr</code> must be called from the
+ extension module's <a class="link" href="xfunc-c.html#XFUNC-C-DYNLOAD" title="38.10.1. Dynamic Loading">_PG_init</a> function.
+ While developing a new extension, use <code class="literal">RM_EXPERIMENTAL_ID</code>
+ for <em class="parameter"><code>rmid</code></em>. When you are ready to release the extension
+ to users, reserve a new resource manager ID at the <a class="ulink" href="https://wiki.postgresql.org/wiki/CustomWALResourceManagers" target="_top">Custom WAL
+ Resource Manager</a> page.
+ </p><p>
+ Place the extension module implementing the custom resource manager in <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> so that it will be loaded early
+ during <span class="productname">PostgreSQL</span> startup.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The extension must remain in shared_preload_libraries as long as any
+ custom WAL records may exist in the system. Otherwise
+ <span class="productname">PostgreSQL</span> will not be able to apply or decode
+ the custom WAL records, which may prevent the server from starting.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="btree.html" title="Chapter 67. B-Tree Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 65. Generic WAL Records </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 67. B-Tree Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/custom-scan-execution.html b/doc/src/sgml/html/custom-scan-execution.html
new file mode 100644
index 0000000..9a32f38
--- /dev/null
+++ b/doc/src/sgml/html/custom-scan-execution.html
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>61.3. Executing Custom Scans</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans" /><link rel="next" href="geqo.html" title="Chapter 62. Genetic Query Optimizer" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">61.3. Executing Custom Scans</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 61. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUSTOM-SCAN-EXECUTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">61.3. Executing Custom Scans</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-execution.html#CUSTOM-SCAN-EXECUTION-CALLBACKS">61.3.1. Custom Scan Execution Callbacks</a></span></dt></dl></div><p>
+ When a <code class="structfield">CustomScan</code> is executed, its execution state is
+ represented by a <code class="structfield">CustomScanState</code>, which is declared as
+ follows:
+</p><pre class="programlisting">
+typedef struct CustomScanState
+{
+ ScanState ss;
+ uint32 flags;
+ const CustomExecMethods *methods;
+} CustomScanState;
+</pre><p>
+ </p><p>
+ <code class="structfield">ss</code> is initialized as for any other scan state,
+ except that if the scan is for a join rather than a base relation,
+ <code class="literal">ss.ss_currentRelation</code> is left NULL.
+ <code class="structfield">flags</code> is a bit mask with the same meaning as in
+ <code class="structname">CustomPath</code> and <code class="structname">CustomScan</code>.
+ <code class="structfield">methods</code> must point to a (usually statically allocated)
+ object implementing the required custom scan state methods, which are
+ further detailed below. Typically, a <code class="structname">CustomScanState</code>, which
+ need not support <code class="function">copyObject</code>, will actually be a larger
+ structure embedding the above as its first member.
+ </p><div class="sect2" id="CUSTOM-SCAN-EXECUTION-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.3.1. Custom Scan Execution Callbacks</h3></div></div></div><p>
+</p><pre class="programlisting">
+void (*BeginCustomScan) (CustomScanState *node,
+ EState *estate,
+ int eflags);
+</pre><p>
+ Complete initialization of the supplied <code class="structname">CustomScanState</code>.
+ Standard fields have been initialized by <code class="function">ExecInitCustomScan</code>,
+ but any private fields should be initialized here.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
+</pre><p>
+ Fetch the next scan tuple. If any tuples remain, it should fill
+ <code class="literal">ps_ResultTupleSlot</code> with the next tuple in the current scan
+ direction, and then return the tuple slot. If not,
+ <code class="literal">NULL</code> or an empty slot should be returned.
+ </p><p>
+</p><pre class="programlisting">
+void (*EndCustomScan) (CustomScanState *node);
+</pre><p>
+ Clean up any private data associated with the <code class="literal">CustomScanState</code>.
+ This method is required, but it does not need to do anything if there is
+ no associated data or it will be cleaned up automatically.
+ </p><p>
+</p><pre class="programlisting">
+void (*ReScanCustomScan) (CustomScanState *node);
+</pre><p>
+ Rewind the current scan to the beginning and prepare to rescan the
+ relation.
+ </p><p>
+</p><pre class="programlisting">
+void (*MarkPosCustomScan) (CustomScanState *node);
+</pre><p>
+ Save the current scan position so that it can subsequently be restored
+ by the <code class="function">RestrPosCustomScan</code> callback. This callback is
+ optional, and need only be supplied if the
+ <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set.
+ </p><p>
+</p><pre class="programlisting">
+void (*RestrPosCustomScan) (CustomScanState *node);
+</pre><p>
+ Restore the previous scan position as saved by the
+ <code class="function">MarkPosCustomScan</code> callback. This callback is optional,
+ and need only be supplied if the
+ <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> flag is set.
+ </p><p>
+</p><pre class="programlisting">
+Size (*EstimateDSMCustomScan) (CustomScanState *node,
+ ParallelContext *pcxt);
+</pre><p>
+ Estimate the amount of dynamic shared memory that will be required
+ for parallel operation. This may be higher than the amount that will
+ actually be used, but it must not be lower. The return value is in bytes.
+ This callback is optional, and need only be supplied if this custom
+ scan provider supports parallel execution.
+ </p><p>
+</p><pre class="programlisting">
+void (*InitializeDSMCustomScan) (CustomScanState *node,
+ ParallelContext *pcxt,
+ void *coordinate);
+</pre><p>
+ Initialize the dynamic shared memory that will be required for parallel
+ operation. <code class="literal">coordinate</code> points to a shared memory area of
+ size equal to the return value of <code class="function">EstimateDSMCustomScan</code>.
+ This callback is optional, and need only be supplied if this custom
+ scan provider supports parallel execution.
+ </p><p>
+</p><pre class="programlisting">
+void (*ReInitializeDSMCustomScan) (CustomScanState *node,
+ ParallelContext *pcxt,
+ void *coordinate);
+</pre><p>
+ Re-initialize the dynamic shared memory required for parallel operation
+ when the custom-scan plan node is about to be re-scanned.
+ This callback is optional, and need only be supplied if this custom
+ scan provider supports parallel execution.
+ Recommended practice is that this callback reset only shared state,
+ while the <code class="function">ReScanCustomScan</code> callback resets only local
+ state. Currently, this callback will be called
+ before <code class="function">ReScanCustomScan</code>, but it's best not to rely on
+ that ordering.
+ </p><p>
+</p><pre class="programlisting">
+void (*InitializeWorkerCustomScan) (CustomScanState *node,
+ shm_toc *toc,
+ void *coordinate);
+</pre><p>
+ Initialize a parallel worker's local state based on the shared state
+ set up by the leader during <code class="function">InitializeDSMCustomScan</code>.
+ This callback is optional, and need only be supplied if this custom
+ scan provider supports parallel execution.
+ </p><p>
+</p><pre class="programlisting">
+void (*ShutdownCustomScan) (CustomScanState *node);
+</pre><p>
+ Release resources when it is anticipated the node will not be executed
+ to completion. This is not called in all cases; sometimes,
+ <code class="literal">EndCustomScan</code> may be called without this function having
+ been called first. Since the DSM segment used by parallel query is
+ destroyed just after this callback is invoked, custom scan providers that
+ wish to take some action before the DSM segment goes away should implement
+ this method.
+ </p><p>
+</p><pre class="programlisting">
+void (*ExplainCustomScan) (CustomScanState *node,
+ List *ancestors,
+ ExplainState *es);
+</pre><p>
+ Output additional information for <code class="command">EXPLAIN</code> of a custom-scan
+ plan node. This callback is optional. Common data stored in the
+ <code class="structname">ScanState</code>, such as the target list and scan relation, will
+ be shown even without this callback, but the callback allows the display
+ of additional, private state.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Next</a></td></tr><tr><td width="40%" align="left" valign="top">61.2. Creating Custom Scan Plans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 62. Genetic Query Optimizer</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/custom-scan-path.html b/doc/src/sgml/html/custom-scan-path.html
new file mode 100644
index 0000000..bb0fc6d
--- /dev/null
+++ b/doc/src/sgml/html/custom-scan-path.html
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>61.1. Creating Custom Scan Paths</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider" /><link rel="next" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">61.1. Creating Custom Scan Paths</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 61. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUSTOM-SCAN-PATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">61.1. Creating Custom Scan Paths</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-path.html#CUSTOM-SCAN-PATH-CALLBACKS">61.1.1. Custom Scan Path Callbacks</a></span></dt></dl></div><p>
+ A custom scan provider will typically add paths for a base relation by
+ setting the following hook, which is called after the core code has
+ generated all the access paths it can for the relation (except for
+ Gather paths, which are made after this call so that they can use
+ partial paths added by the hook):
+</p><pre class="programlisting">
+typedef void (*set_rel_pathlist_hook_type) (PlannerInfo *root,
+ RelOptInfo *rel,
+ Index rti,
+ RangeTblEntry *rte);
+extern PGDLLIMPORT set_rel_pathlist_hook_type set_rel_pathlist_hook;
+</pre><p>
+ </p><p>
+ Although this hook function can be used to examine, modify, or remove
+ paths generated by the core system, a custom scan provider will typically
+ confine itself to generating <code class="structname">CustomPath</code> objects and adding
+ them to <code class="literal">rel</code> using <code class="function">add_path</code>. The custom scan
+ provider is responsible for initializing the <code class="structname">CustomPath</code>
+ object, which is declared like this:
+</p><pre class="programlisting">
+typedef struct CustomPath
+{
+ Path path;
+ uint32 flags;
+ List *custom_paths;
+ List *custom_private;
+ const CustomPathMethods *methods;
+} CustomPath;
+</pre><p>
+ </p><p>
+ <code class="structfield">path</code> must be initialized as for any other path, including
+ the row-count estimate, start and total cost, and sort ordering provided
+ by this path. <code class="structfield">flags</code> is a bit mask, which
+ specifies whether the scan provider can support certain optional
+ capabilities. <code class="structfield">flags</code> should include
+ <code class="literal">CUSTOMPATH_SUPPORT_BACKWARD_SCAN</code> if the custom path can support
+ a backward scan, <code class="literal">CUSTOMPATH_SUPPORT_MARK_RESTORE</code> if it
+ can support mark and restore,
+ and <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> if it can perform
+ projections. (If <code class="literal">CUSTOMPATH_SUPPORT_PROJECTION</code> is not
+ set, the scan node will only be asked to produce Vars of the scanned
+ relation; while if that flag is set, the scan node must be able to
+ evaluate scalar expressions over these Vars.)
+ An optional <code class="structfield">custom_paths</code> is a list of <code class="structname">Path</code>
+ nodes used by this custom-path node; these will be transformed into
+ <code class="structname">Plan</code> nodes by planner.
+ <code class="structfield">custom_private</code> can be used to store the custom path's
+ private data. Private data should be stored in a form that can be handled
+ by <code class="literal">nodeToString</code>, so that debugging routines that attempt to
+ print the custom path will work as designed. <code class="structfield">methods</code> must
+ point to a (usually statically allocated) object implementing the required
+ custom path methods, which are further detailed below.
+ </p><p>
+ A custom scan provider can also provide join paths. Just as for base
+ relations, such a path must produce the same output as would normally be
+ produced by the join it replaces. To do this, the join provider should
+ set the following hook, and then within the hook function,
+ create <code class="structname">CustomPath</code> path(s) for the join relation.
+</p><pre class="programlisting">
+typedef void (*set_join_pathlist_hook_type) (PlannerInfo *root,
+ RelOptInfo *joinrel,
+ RelOptInfo *outerrel,
+ RelOptInfo *innerrel,
+ JoinType jointype,
+ JoinPathExtraData *extra);
+extern PGDLLIMPORT set_join_pathlist_hook_type set_join_pathlist_hook;
+</pre><p>
+
+ This hook will be invoked repeatedly for the same join relation, with
+ different combinations of inner and outer relations; it is the
+ responsibility of the hook to minimize duplicated work.
+ </p><div class="sect2" id="CUSTOM-SCAN-PATH-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.1.1. Custom Scan Path Callbacks</h3></div></div></div><p>
+</p><pre class="programlisting">
+Plan *(*PlanCustomPath) (PlannerInfo *root,
+ RelOptInfo *rel,
+ CustomPath *best_path,
+ List *tlist,
+ List *clauses,
+ List *custom_plans);
+</pre><p>
+ Convert a custom path to a finished plan. The return value will generally
+ be a <code class="literal">CustomScan</code> object, which the callback must allocate and
+ initialize. See <a class="xref" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Section 61.2</a> for more details.
+ </p><p>
+</p><pre class="programlisting">
+List *(*ReparameterizeCustomPathByChild) (PlannerInfo *root,
+ List *custom_private,
+ RelOptInfo *child_rel);
+</pre><p>
+ This callback is called while converting a path parameterized by the
+ top-most parent of the given child relation <code class="literal">child_rel</code>
+ to be parameterized by the child relation. The callback is used to
+ reparameterize any paths or translate any expression nodes saved in the
+ given <code class="literal">custom_private</code> member of a
+ <code class="structname">CustomPath</code>. The callback may use
+ <code class="literal">reparameterize_path_by_child</code>,
+ <code class="literal">adjust_appendrel_attrs</code> or
+ <code class="literal">adjust_appendrel_attrs_multilevel</code> as required.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-scan-plan.html" title="61.2. Creating Custom Scan Plans">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 61. Writing a Custom Scan Provider </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.2. Creating Custom Scan Plans</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/custom-scan-plan.html b/doc/src/sgml/html/custom-scan-plan.html
new file mode 100644
index 0000000..a253e4d
--- /dev/null
+++ b/doc/src/sgml/html/custom-scan-plan.html
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>61.2. Creating Custom Scan Plans</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths" /><link rel="next" href="custom-scan-execution.html" title="61.3. Executing Custom Scans" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">61.2. Creating Custom Scan Plans</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><th width="60%" align="center">Chapter 61. Writing a Custom Scan Provider</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-scan-execution.html" title="61.3. Executing Custom Scans">Next</a></td></tr></table><hr /></div><div class="sect1" id="CUSTOM-SCAN-PLAN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">61.2. Creating Custom Scan Plans</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="custom-scan-plan.html#CUSTOM-SCAN-PLAN-CALLBACKS">61.2.1. Custom Scan Plan Callbacks</a></span></dt></dl></div><p>
+ A custom scan is represented in a finished plan tree using the following
+ structure:
+</p><pre class="programlisting">
+typedef struct CustomScan
+{
+ Scan scan;
+ uint32 flags;
+ List *custom_plans;
+ List *custom_exprs;
+ List *custom_private;
+ List *custom_scan_tlist;
+ Bitmapset *custom_relids;
+ const CustomScanMethods *methods;
+} CustomScan;
+</pre><p>
+ </p><p>
+ <code class="structfield">scan</code> must be initialized as for any other scan, including
+ estimated costs, target lists, qualifications, and so on.
+ <code class="structfield">flags</code> is a bit mask with the same meaning as in
+ <code class="structname">CustomPath</code>.
+ <code class="structfield">custom_plans</code> can be used to store child
+ <code class="structname">Plan</code> nodes.
+ <code class="structfield">custom_exprs</code> should be used to
+ store expression trees that will need to be fixed up by
+ <code class="filename">setrefs.c</code> and <code class="filename">subselect.c</code>, while
+ <code class="structfield">custom_private</code> should be used to store other private data
+ that is only used by the custom scan provider itself.
+ <code class="structfield">custom_scan_tlist</code> can be NIL when scanning a base
+ relation, indicating that the custom scan returns scan tuples that match
+ the base relation's row type. Otherwise it is a target list describing
+ the actual scan tuples. <code class="structfield">custom_scan_tlist</code> must be
+ provided for joins, and could be provided for scans if the custom scan
+ provider can compute some non-Var expressions.
+ <code class="structfield">custom_relids</code> is set by the core code to the set of
+ relations (range table indexes) that this scan node handles; except when
+ this scan is replacing a join, it will have only one member.
+ <code class="structfield">methods</code> must point to a (usually statically allocated)
+ object implementing the required custom scan methods, which are further
+ detailed below.
+ </p><p>
+ When a <code class="structname">CustomScan</code> scans a single relation,
+ <code class="structfield">scan.scanrelid</code> must be the range table index of the table
+ to be scanned. When it replaces a join, <code class="structfield">scan.scanrelid</code>
+ should be zero.
+ </p><p>
+ Plan trees must be able to be duplicated using <code class="function">copyObject</code>,
+ so all the data stored within the <span class="quote">“<span class="quote">custom</span>”</span> fields must consist of
+ nodes that that function can handle. Furthermore, custom scan providers
+ cannot substitute a larger structure that embeds
+ a <code class="structname">CustomScan</code> for the structure itself, as would be possible
+ for a <code class="structname">CustomPath</code> or <code class="structname">CustomScanState</code>.
+ </p><div class="sect2" id="CUSTOM-SCAN-PLAN-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">61.2.1. Custom Scan Plan Callbacks</h3></div></div></div><p>
+</p><pre class="programlisting">
+Node *(*CreateCustomScanState) (CustomScan *cscan);
+</pre><p>
+ Allocate a <code class="structname">CustomScanState</code> for this
+ <code class="structname">CustomScan</code>. The actual allocation will often be larger than
+ required for an ordinary <code class="structname">CustomScanState</code>, because many
+ providers will wish to embed that as the first field of a larger structure.
+ The value returned must have the node tag and <code class="structfield">methods</code>
+ set appropriately, but other fields should be left as zeroes at this
+ stage; after <code class="function">ExecInitCustomScan</code> performs basic initialization,
+ the <code class="function">BeginCustomScan</code> callback will be invoked to give the
+ custom scan provider a chance to do whatever else is needed.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-scan-execution.html" title="61.3. Executing Custom Scans">Next</a></td></tr><tr><td width="40%" align="left" valign="top">61.1. Creating Custom Scan Paths </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.3. Executing Custom Scans</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/custom-scan.html b/doc/src/sgml/html/custom-scan.html
new file mode 100644
index 0000000..76e8b9c
--- /dev/null
+++ b/doc/src/sgml/html/custom-scan.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 61. Writing a Custom Scan Provider</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions" /><link rel="next" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 61. Writing a Custom Scan Provider</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths">Next</a></td></tr></table><hr /></div><div class="chapter" id="CUSTOM-SCAN"><div class="titlepage"><div><div><h2 class="title">Chapter 61. Writing a Custom Scan Provider</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="custom-scan-path.html">61.1. Creating Custom Scan Paths</a></span></dt><dd><dl><dt><span class="sect2"><a href="custom-scan-path.html#CUSTOM-SCAN-PATH-CALLBACKS">61.1.1. Custom Scan Path Callbacks</a></span></dt></dl></dd><dt><span class="sect1"><a href="custom-scan-plan.html">61.2. Creating Custom Scan Plans</a></span></dt><dd><dl><dt><span class="sect2"><a href="custom-scan-plan.html#CUSTOM-SCAN-PLAN-CALLBACKS">61.2.1. Custom Scan Plan Callbacks</a></span></dt></dl></dd><dt><span class="sect1"><a href="custom-scan-execution.html">61.3. Executing Custom Scans</a></span></dt><dd><dl><dt><span class="sect2"><a href="custom-scan-execution.html#CUSTOM-SCAN-EXECUTION-CALLBACKS">61.3.1. Custom Scan Execution Callbacks</a></span></dt></dl></dd></dl></div><a id="id-1.10.12.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> supports a set of experimental facilities which
+ are intended to allow extension modules to add new scan types to the system.
+ Unlike a <a class="link" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">foreign data wrapper</a>, which is only
+ responsible for knowing how to scan its own foreign tables, a custom scan
+ provider can provide an alternative method of scanning any relation in the
+ system. Typically, the motivation for writing a custom scan provider will
+ be to allow the use of some optimization not supported by the core
+ system, such as caching or some form of hardware acceleration. This chapter
+ outlines how to write a new custom scan provider.
+ </p><p>
+ Implementing a new type of custom scan is a three-step process. First,
+ during planning, it is necessary to generate access paths representing a
+ scan using the proposed strategy. Second, if one of those access paths
+ is selected by the planner as the optimal strategy for scanning a
+ particular relation, the access path must be converted to a plan.
+ Finally, it must be possible to execute the plan and generate the same
+ results that would have been generated for any other access path targeting
+ the same relation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-scan-path.html" title="61.1. Creating Custom Scan Paths">Next</a></td></tr><tr><td width="40%" align="left" valign="top">60.1. Sampling Method Support Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.1. Creating Custom Scan Paths</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/database-roles.html b/doc/src/sgml/html/database-roles.html
new file mode 100644
index 0000000..919b371
--- /dev/null
+++ b/doc/src/sgml/html/database-roles.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.1. Database Roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="user-manag.html" title="Chapter 22. Database Roles" /><link rel="next" href="role-attributes.html" title="22.2. Role Attributes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.1. Database Roles</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="user-manag.html" title="Chapter 22. Database Roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="role-attributes.html" title="22.2. Role Attributes">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATABASE-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.1. Database Roles</h2></div></div></div><a id="id-1.6.9.5.2" class="indexterm"></a><a id="id-1.6.9.5.3" class="indexterm"></a><a id="id-1.6.9.5.4" class="indexterm"></a><a id="id-1.6.9.5.5" class="indexterm"></a><p>
+ Database roles are conceptually completely separate from
+ operating system users. In practice it might be convenient to
+ maintain a correspondence, but this is not required. Database roles
+ are global across a database cluster installation (and not
+ per individual database). To create a role use the <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a> SQL command:
+</p><pre class="synopsis">
+CREATE ROLE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ <em class="replaceable"><code>name</code></em> follows the rules for SQL
+ identifiers: either unadorned without special characters, or
+ double-quoted. (In practice, you will usually want to add additional
+ options, such as <code class="literal">LOGIN</code>, to the command. More details appear
+ below.) To remove an existing role, use the analogous
+ <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a> command:
+</p><pre class="synopsis">
+DROP ROLE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ </p><a id="id-1.6.9.5.7" class="indexterm"></a><a id="id-1.6.9.5.8" class="indexterm"></a><p>
+ For convenience, the programs <a class="xref" href="app-createuser.html" title="createuser"><span class="refentrytitle"><span class="application">createuser</span></span></a>
+ and <a class="xref" href="app-dropuser.html" title="dropuser"><span class="refentrytitle"><span class="application">dropuser</span></span></a> are provided as wrappers
+ around these SQL commands that can be called from the shell command
+ line:
+</p><pre class="synopsis">
+createuser <em class="replaceable"><code>name</code></em>
+dropuser <em class="replaceable"><code>name</code></em>
+</pre><p>
+ </p><p>
+ To determine the set of existing roles, examine the <code class="structname">pg_roles</code>
+ system catalog, for example
+</p><pre class="synopsis">
+SELECT rolname FROM pg_roles;
+</pre><p>
+ The <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> program's <code class="literal">\du</code> meta-command
+ is also useful for listing the existing roles.
+ </p><p>
+ In order to bootstrap the database system, a freshly initialized
+ system always contains one predefined role. This role is always
+ a <span class="quote">“<span class="quote">superuser</span>”</span>, and by default (unless altered when running
+ <code class="command">initdb</code>) it will have the same name as the
+ operating system user that initialized the database
+ cluster. Customarily, this role will be named
+ <code class="literal">postgres</code>. In order to create more roles you
+ first have to connect as this initial role.
+ </p><p>
+ Every connection to the database server is made using the name of some
+ particular role, and this role determines the initial access privileges for
+ commands issued in that connection.
+ The role name to use for a particular database
+ connection is indicated by the client that is initiating the
+ connection request in an application-specific fashion. For example,
+ the <code class="command">psql</code> program uses the
+ <code class="option">-U</code> command line option to indicate the role to
+ connect as. Many applications assume the name of the current
+ operating system user by default (including
+ <code class="command">createuser</code> and <code class="command">psql</code>). Therefore it
+ is often convenient to maintain a naming correspondence between
+ roles and operating system users.
+ </p><p>
+ The set of database roles a given client connection can connect as
+ is determined by the client authentication setup, as explained in
+ <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>. (Thus, a client is not
+ limited to connect as the role matching
+ its operating system user, just as a person's login name
+ need not match his or her real name.) Since the role
+ identity determines the set of privileges available to a connected
+ client, it is important to carefully configure privileges when setting up
+ a multiuser environment.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-manag.html" title="Chapter 22. Database Roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="role-attributes.html" title="22.2. Role Attributes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 22. Database Roles </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.2. Role Attributes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-binary.html b/doc/src/sgml/html/datatype-binary.html
new file mode 100644
index 0000000..624fca7
--- /dev/null
+++ b/doc/src/sgml/html/datatype-binary.html
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.4. Binary Data Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-character.html" title="8.3. Character Types" /><link rel="next" href="datatype-datetime.html" title="8.5. Date/Time Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.4. Binary Data Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-character.html" title="8.3. Character Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-datetime.html" title="8.5. Date/Time Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-BINARY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.4. Binary Data Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-binary.html#id-1.5.7.12.9">8.4.1. <code class="type">bytea</code> Hex Format</a></span></dt><dt><span class="sect2"><a href="datatype-binary.html#id-1.5.7.12.10">8.4.2. <code class="type">bytea</code> Escape Format</a></span></dt></dl></div><a id="id-1.5.7.12.2" class="indexterm"></a><a id="id-1.5.7.12.3" class="indexterm"></a><p>
+ The <code class="type">bytea</code> data type allows storage of binary strings;
+ see <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-TABLE" title="Table 8.6. Binary Data Types">Table 8.6</a>.
+ </p><div class="table" id="DATATYPE-BINARY-TABLE"><p class="title"><strong>Table 8.6. Binary Data Types</strong></p><div class="table-contents"><table class="table" summary="Binary Data Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">bytea</code></td><td>1 or 4 bytes plus the actual binary string</td><td>variable-length binary string</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ A binary string is a sequence of octets (or bytes). Binary
+ strings are distinguished from character strings in two
+ ways. First, binary strings specifically allow storing
+ octets of value zero and other <span class="quote">“<span class="quote">non-printable</span>”</span>
+ octets (usually, octets outside the decimal range 32 to 126).
+ Character strings disallow zero octets, and also disallow any
+ other octet values and sequences of octet values that are invalid
+ according to the database's selected character set encoding.
+ Second, operations on binary strings process the actual bytes,
+ whereas the processing of character strings depends on locale settings.
+ In short, binary strings are appropriate for storing data that the
+ programmer thinks of as <span class="quote">“<span class="quote">raw bytes</span>”</span>, whereas character
+ strings are appropriate for storing text.
+ </p><p>
+ The <code class="type">bytea</code> type supports two
+ formats for input and output: <span class="quote">“<span class="quote">hex</span>”</span> format
+ and <span class="productname">PostgreSQL</span>'s historical
+ <span class="quote">“<span class="quote">escape</span>”</span> format. Both
+ of these are always accepted on input. The output format depends
+ on the configuration parameter <a class="xref" href="runtime-config-client.html#GUC-BYTEA-OUTPUT">bytea_output</a>;
+ the default is hex. (Note that the hex format was introduced in
+ <span class="productname">PostgreSQL</span> 9.0; earlier versions and some
+ tools don't understand it.)
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> standard defines a different binary
+ string type, called <code class="type">BLOB</code> or <code class="type">BINARY LARGE
+ OBJECT</code>. The input format is different from
+ <code class="type">bytea</code>, but the provided functions and operators are
+ mostly the same.
+ </p><div class="sect2" id="id-1.5.7.12.9"><div class="titlepage"><div><div><h3 class="title">8.4.1. <code class="type">bytea</code> Hex Format</h3></div></div></div><p>
+ The <span class="quote">“<span class="quote">hex</span>”</span> format encodes binary data as 2 hexadecimal digits
+ per byte, most significant nibble first. The entire string is
+ preceded by the sequence <code class="literal">\x</code> (to distinguish it
+ from the escape format). In some contexts, the initial backslash may
+ need to be escaped by doubling it
+ (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>).
+ For input, the hexadecimal digits can
+ be either upper or lower case, and whitespace is permitted between
+ digit pairs (but not within a digit pair nor in the starting
+ <code class="literal">\x</code> sequence).
+ The hex format is compatible with a wide
+ range of external applications and protocols, and it tends to be
+ faster to convert than the escape format, so its use is preferred.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+SET bytea_output = 'hex';
+
+SELECT '\xDEADBEEF'::bytea;
+ bytea
+------------
+ \xdeadbeef
+</pre><p>
+ </p></div><div class="sect2" id="id-1.5.7.12.10"><div class="titlepage"><div><div><h3 class="title">8.4.2. <code class="type">bytea</code> Escape Format</h3></div></div></div><p>
+ The <span class="quote">“<span class="quote">escape</span>”</span> format is the traditional
+ <span class="productname">PostgreSQL</span> format for the <code class="type">bytea</code>
+ type. It
+ takes the approach of representing a binary string as a sequence
+ of ASCII characters, while converting those bytes that cannot be
+ represented as an ASCII character into special escape sequences.
+ If, from the point of view of the application, representing bytes
+ as characters makes sense, then this representation can be
+ convenient. But in practice it is usually confusing because it
+ fuzzes up the distinction between binary strings and character
+ strings, and also the particular escape mechanism that was chosen is
+ somewhat unwieldy. Therefore, this format should probably be avoided
+ for most new applications.
+ </p><p>
+ When entering <code class="type">bytea</code> values in escape format,
+ octets of certain
+ values <span class="emphasis"><em>must</em></span> be escaped, while all octet
+ values <span class="emphasis"><em>can</em></span> be escaped. In
+ general, to escape an octet, convert it into its three-digit
+ octal value and precede it by a backslash.
+ Backslash itself (octet decimal value 92) can alternatively be represented by
+ double backslashes.
+ <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a>
+ shows the characters that must be escaped, and gives the alternative
+ escape sequences where applicable.
+ </p><div class="table" id="DATATYPE-BINARY-SQLESC"><p class="title"><strong>Table 8.7. <code class="type">bytea</code> Literal Escaped Octets</strong></p><div class="table-contents"><table class="table" summary="bytea Literal Escaped Octets" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>Decimal Octet Value</th><th>Description</th><th>Escaped Input Representation</th><th>Example</th><th>Hex Representation</th></tr></thead><tbody><tr><td>0</td><td>zero octet</td><td><code class="literal">'\000'</code></td><td><code class="literal">'\000'::bytea</code></td><td><code class="literal">\x00</code></td></tr><tr><td>39</td><td>single quote</td><td><code class="literal">''''</code> or <code class="literal">'\047'</code></td><td><code class="literal">''''::bytea</code></td><td><code class="literal">\x27</code></td></tr><tr><td>92</td><td>backslash</td><td><code class="literal">'\\'</code> or <code class="literal">'\134'</code></td><td><code class="literal">'\\'::bytea</code></td><td><code class="literal">\x5c</code></td></tr><tr><td>0 to 31 and 127 to 255</td><td><span class="quote">“<span class="quote">non-printable</span>”</span> octets</td><td><code class="literal">'\<em class="replaceable"><code>xxx'</code></em></code> (octal value)</td><td><code class="literal">'\001'::bytea</code></td><td><code class="literal">\x01</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The requirement to escape <span class="emphasis"><em>non-printable</em></span> octets
+ varies depending on locale settings. In some instances you can get away
+ with leaving them unescaped.
+ </p><p>
+ The reason that single quotes must be doubled, as shown
+ in <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a>, is that this
+ is true for any string literal in an SQL command. The generic
+ string-literal parser consumes the outermost single quotes
+ and reduces any pair of single quotes to one data character.
+ What the <code class="type">bytea</code> input function sees is just one
+ single quote, which it treats as a plain data character.
+ However, the <code class="type">bytea</code> input function treats
+ backslashes as special, and the other behaviors shown in
+ <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-SQLESC" title="Table 8.7. bytea Literal Escaped Octets">Table 8.7</a> are implemented by
+ that function.
+ </p><p>
+ In some contexts, backslashes must be doubled compared to what is
+ shown above, because the generic string-literal parser will also
+ reduce pairs of backslashes to one data character;
+ see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>.
+ </p><p>
+ <code class="type">Bytea</code> octets are output in <code class="literal">hex</code>
+ format by default. If you change <a class="xref" href="runtime-config-client.html#GUC-BYTEA-OUTPUT">bytea_output</a>
+ to <code class="literal">escape</code>,
+ <span class="quote">“<span class="quote">non-printable</span>”</span> octets are converted to their
+ equivalent three-digit octal value and preceded by one backslash.
+ Most <span class="quote">“<span class="quote">printable</span>”</span> octets are output by their standard
+ representation in the client character set, e.g.:
+
+</p><pre class="programlisting">
+SET bytea_output = 'escape';
+
+SELECT 'abc \153\154\155 \052\251\124'::bytea;
+ bytea
+----------------
+ abc klm *\251T
+</pre><p>
+
+ The octet with decimal value 92 (backslash) is doubled in the output.
+ Details are in <a class="xref" href="datatype-binary.html#DATATYPE-BINARY-RESESC" title="Table 8.8. bytea Output Escaped Octets">Table 8.8</a>.
+ </p><div class="table" id="DATATYPE-BINARY-RESESC"><p class="title"><strong>Table 8.8. <code class="type">bytea</code> Output Escaped Octets</strong></p><div class="table-contents"><table class="table" summary="bytea Output Escaped Octets" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>Decimal Octet Value</th><th>Description</th><th>Escaped Output Representation</th><th>Example</th><th>Output Result</th></tr></thead><tbody><tr><td>92</td><td>backslash</td><td><code class="literal">\\</code></td><td><code class="literal">'\134'::bytea</code></td><td><code class="literal">\\</code></td></tr><tr><td>0 to 31 and 127 to 255</td><td><span class="quote">“<span class="quote">non-printable</span>”</span> octets</td><td><code class="literal">\<em class="replaceable"><code>xxx</code></em></code> (octal value)</td><td><code class="literal">'\001'::bytea</code></td><td><code class="literal">\001</code></td></tr><tr><td>32 to 126</td><td><span class="quote">“<span class="quote">printable</span>”</span> octets</td><td>client character set representation</td><td><code class="literal">'\176'::bytea</code></td><td><code class="literal">~</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Depending on the front end to <span class="productname">PostgreSQL</span> you use,
+ you might have additional work to do in terms of escaping and
+ unescaping <code class="type">bytea</code> strings. For example, you might also
+ have to escape line feeds and carriage returns if your interface
+ automatically translates these.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-character.html" title="8.3. Character Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-datetime.html" title="8.5. Date/Time Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.3. Character Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.5. Date/Time Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-bit.html b/doc/src/sgml/html/datatype-bit.html
new file mode 100644
index 0000000..5fdaabc
--- /dev/null
+++ b/doc/src/sgml/html/datatype-bit.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.10. Bit String Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-net-types.html" title="8.9. Network Address Types" /><link rel="next" href="datatype-textsearch.html" title="8.11. Text Search Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.10. Bit String Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-net-types.html" title="8.9. Network Address Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-textsearch.html" title="8.11. Text Search Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-BIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.10. Bit String Types</h2></div></div></div><a id="id-1.5.7.18.2" class="indexterm"></a><p>
+ Bit strings are strings of 1's and 0's. They can be used to store
+ or visualize bit masks. There are two SQL bit types:
+ <code class="type">bit(<em class="replaceable"><code>n</code></em>)</code> and <code class="type">bit
+ varying(<em class="replaceable"><code>n</code></em>)</code>, where
+ <em class="replaceable"><code>n</code></em> is a positive integer.
+ </p><p>
+ <code class="type">bit</code> type data must match the length
+ <em class="replaceable"><code>n</code></em> exactly; it is an error to attempt to
+ store shorter or longer bit strings. <code class="type">bit varying</code> data is
+ of variable length up to the maximum length
+ <em class="replaceable"><code>n</code></em>; longer strings will be rejected.
+ Writing <code class="type">bit</code> without a length is equivalent to
+ <code class="literal">bit(1)</code>, while <code class="type">bit varying</code> without a length
+ specification means unlimited length.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If one explicitly casts a bit-string value to
+ <code class="type">bit(<em class="replaceable"><code>n</code></em>)</code>, it will be truncated or
+ zero-padded on the right to be exactly <em class="replaceable"><code>n</code></em> bits,
+ without raising an error. Similarly,
+ if one explicitly casts a bit-string value to
+ <code class="type">bit varying(<em class="replaceable"><code>n</code></em>)</code>, it will be truncated
+ on the right if it is more than <em class="replaceable"><code>n</code></em> bits.
+ </p></div><p>
+ Refer to <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-BIT-STRINGS" title="4.1.2.5. Bit-String Constants">Section 4.1.2.5</a> for information about the syntax
+ of bit string constants. Bit-logical operators and string
+ manipulation functions are available; see <a class="xref" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Section 9.6</a>.
+ </p><div class="example" id="id-1.5.7.18.7"><p class="title"><strong>Example 8.3. Using the Bit String Types</strong></p><div class="example-contents"><pre class="programlisting">
+CREATE TABLE test (a BIT(3), b BIT VARYING(5));
+INSERT INTO test VALUES (B'101', B'00');
+INSERT INTO test VALUES (B'10', B'101');
+<code class="computeroutput">
+ERROR: bit string length 2 does not match type bit(3)
+</code>
+INSERT INTO test VALUES (B'10'::bit(3), B'101');
+SELECT * FROM test;
+<code class="computeroutput">
+ a | b
+-----+-----
+ 101 | 00
+ 100 | 101
+</code>
+</pre></div></div><br class="example-break" /><p>
+ 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 <a class="xref" href="datatype-character.html" title="8.3. Character Types">Section 8.3</a> for character strings).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-net-types.html" title="8.9. Network Address Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-textsearch.html" title="8.11. Text Search Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.9. Network Address Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.11. Text Search Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-boolean.html b/doc/src/sgml/html/datatype-boolean.html
new file mode 100644
index 0000000..b833b9c
--- /dev/null
+++ b/doc/src/sgml/html/datatype-boolean.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.6. Boolean Type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-datetime.html" title="8.5. Date/Time Types" /><link rel="next" href="datatype-enum.html" title="8.7. Enumerated Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.6. Boolean Type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-datetime.html" title="8.5. Date/Time Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-enum.html" title="8.7. Enumerated Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-BOOLEAN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.6. Boolean Type</h2></div></div></div><a id="id-1.5.7.14.2" class="indexterm"></a><a id="id-1.5.7.14.3" class="indexterm"></a><a id="id-1.5.7.14.4" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides the
+ standard <acronym class="acronym">SQL</acronym> type <code class="type">boolean</code>;
+ see <a class="xref" href="datatype-boolean.html#DATATYPE-BOOLEAN-TABLE" title="Table 8.19. Boolean Data Type">Table 8.19</a>.
+ The <code class="type">boolean</code> type can have several states:
+ <span class="quote">“<span class="quote">true</span>”</span>, <span class="quote">“<span class="quote">false</span>”</span>, and a third state,
+ <span class="quote">“<span class="quote">unknown</span>”</span>, which is represented by the
+ <acronym class="acronym">SQL</acronym> null value.
+ </p><div class="table" id="DATATYPE-BOOLEAN-TABLE"><p class="title"><strong>Table 8.19. Boolean Data Type</strong></p><div class="table-contents"><table class="table" summary="Boolean Data Type" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">boolean</code></td><td>1 byte</td><td>state of true or false</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Boolean constants can be represented in SQL queries by the SQL
+ key words <code class="literal">TRUE</code>, <code class="literal">FALSE</code>,
+ and <code class="literal">NULL</code>.
+ </p><p>
+ The datatype input function for type <code class="type">boolean</code> accepts these
+ string representations for the <span class="quote">“<span class="quote">true</span>”</span> state:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">true</code></td></tr><tr><td><code class="literal">yes</code></td></tr><tr><td><code class="literal">on</code></td></tr><tr><td><code class="literal">1</code></td></tr></table><p>
+ and these representations for the <span class="quote">“<span class="quote">false</span>”</span> state:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">false</code></td></tr><tr><td><code class="literal">no</code></td></tr><tr><td><code class="literal">off</code></td></tr><tr><td><code class="literal">0</code></td></tr></table><p>
+ Unique prefixes of these strings are also accepted, for
+ example <code class="literal">t</code> or <code class="literal">n</code>.
+ Leading or trailing whitespace is ignored, and case does not matter.
+ </p><p>
+ The datatype output function for type <code class="type">boolean</code> always emits
+ either <code class="literal">t</code> or <code class="literal">f</code>, as shown in
+ <a class="xref" href="datatype-boolean.html#DATATYPE-BOOLEAN-EXAMPLE" title="Example 8.2. Using the boolean Type">Example 8.2</a>.
+ </p><div class="example" id="DATATYPE-BOOLEAN-EXAMPLE"><p class="title"><strong>Example 8.2. Using the <code class="type">boolean</code> Type</strong></p><div class="example-contents"><pre class="programlisting">
+CREATE TABLE test1 (a boolean, b text);
+INSERT INTO test1 VALUES (TRUE, 'sic est');
+INSERT INTO test1 VALUES (FALSE, 'non est');
+SELECT * FROM test1;
+ a | b
+---+---------
+ t | sic est
+ f | non est
+
+SELECT * FROM test1 WHERE a;
+ a | b
+---+---------
+ t | sic est
+</pre></div></div><br class="example-break" /><p>
+ The key words <code class="literal">TRUE</code> and <code class="literal">FALSE</code> are
+ the preferred (<acronym class="acronym">SQL</acronym>-compliant) method for writing
+ Boolean constants in SQL queries. But you can also use the string
+ representations by following the generic string-literal constant syntax
+ described in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC" title="4.1.2.7. Constants of Other Types">Section 4.1.2.7</a>, for
+ example <code class="literal">'yes'::boolean</code>.
+ </p><p>
+ Note that the parser automatically understands
+ that <code class="literal">TRUE</code> and <code class="literal">FALSE</code> are of
+ type <code class="type">boolean</code>, but this is not so
+ for <code class="literal">NULL</code> because that can have any type.
+ So in some contexts you might have to cast <code class="literal">NULL</code>
+ to <code class="type">boolean</code> explicitly, for
+ example <code class="literal">NULL::boolean</code>. Conversely, the cast can be
+ omitted from a string-literal Boolean value in contexts where the parser
+ can deduce that the literal must be of type <code class="type">boolean</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-datetime.html" title="8.5. Date/Time Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-enum.html" title="8.7. Enumerated Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.5. Date/Time Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.7. Enumerated Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-character.html b/doc/src/sgml/html/datatype-character.html
new file mode 100644
index 0000000..4e127d0
--- /dev/null
+++ b/doc/src/sgml/html/datatype-character.html
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.3. Character Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-money.html" title="8.2. Monetary Types" /><link rel="next" href="datatype-binary.html" title="8.4. Binary Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.3. Character Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-money.html" title="8.2. Monetary Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-binary.html" title="8.4. Binary Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-CHARACTER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.3. Character Types</h2></div></div></div><a id="id-1.5.7.11.2" class="indexterm"></a><a id="id-1.5.7.11.3" class="indexterm"></a><a id="id-1.5.7.11.4" class="indexterm"></a><a id="id-1.5.7.11.5" class="indexterm"></a><a id="id-1.5.7.11.6" class="indexterm"></a><a id="id-1.5.7.11.7" class="indexterm"></a><a id="id-1.5.7.11.8" class="indexterm"></a><div class="table" id="DATATYPE-CHARACTER-TABLE"><p class="title"><strong>Table 8.4. Character Types</strong></p><div class="table-contents"><table class="table" summary="Character Types" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">character varying(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">varchar(<em class="replaceable"><code>n</code></em>)</code></td><td>variable-length with limit</td></tr><tr><td><code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">char(<em class="replaceable"><code>n</code></em>)</code></td><td>fixed-length, blank padded</td></tr><tr><td><code class="type">text</code></td><td>variable unlimited length</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="datatype-character.html#DATATYPE-CHARACTER-TABLE" title="Table 8.4. Character Types">Table 8.4</a> shows the
+ general-purpose character types available in
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ <acronym class="acronym">SQL</acronym> defines two primary character types:
+ <code class="type">character varying(<em class="replaceable"><code>n</code></em>)</code> and
+ <code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, where <em class="replaceable"><code>n</code></em>
+ is a positive integer. Both of these types can store strings up to
+ <em class="replaceable"><code>n</code></em> characters (not bytes) in length. An attempt to store a
+ longer string into a column of these types will result in an
+ error, unless the excess characters are all spaces, in which case
+ the string will be truncated to the maximum length. (This somewhat
+ bizarre exception is required by the <acronym class="acronym">SQL</acronym>
+ standard.) If the string to be stored is shorter than the declared
+ length, values of type <code class="type">character</code> will be space-padded;
+ values of type <code class="type">character varying</code> will simply store the
+ shorter
+ string.
+ </p><p>
+ If one explicitly casts a value to <code class="type">character
+ varying(<em class="replaceable"><code>n</code></em>)</code> or
+ <code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, then an over-length
+ value will be truncated to <em class="replaceable"><code>n</code></em> characters without
+ raising an error. (This too is required by the
+ <acronym class="acronym">SQL</acronym> standard.)
+ </p><p>
+ The notations <code class="type">varchar(<em class="replaceable"><code>n</code></em>)</code> and
+ <code class="type">char(<em class="replaceable"><code>n</code></em>)</code> are aliases for <code class="type">character
+ varying(<em class="replaceable"><code>n</code></em>)</code> and
+ <code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, respectively.
+ If specified, the length must be greater than zero and cannot exceed
+ 10485760.
+ <code class="type">character</code> without length specifier is equivalent to
+ <code class="type">character(1)</code>. If <code class="type">character varying</code> is used
+ without length specifier, the type accepts strings of any size. The
+ latter is a <span class="productname">PostgreSQL</span> extension.
+ </p><p>
+ In addition, <span class="productname">PostgreSQL</span> provides the
+ <code class="type">text</code> type, which stores strings of any length.
+ Although the type <code class="type">text</code> is not in the
+ <acronym class="acronym">SQL</acronym> standard, several other SQL database
+ management systems have it as well.
+ </p><p>
+ Values of type <code class="type">character</code> are physically padded
+ with spaces to the specified width <em class="replaceable"><code>n</code></em>, and are
+ stored and displayed that way. However, trailing spaces are treated as
+ semantically insignificant and disregarded when comparing two values
+ of type <code class="type">character</code>. In collations where whitespace
+ is significant, this behavior can produce unexpected results;
+ for example <code class="command">SELECT 'a '::CHAR(2) collate "C" &lt;
+ E'a\n'::CHAR(2)</code> returns true, even though <code class="literal">C</code>
+ locale would consider a space to be greater than a newline.
+ Trailing spaces are removed when converting a <code class="type">character</code> value
+ to one of the other string types. Note that trailing spaces
+ <span class="emphasis"><em>are</em></span> semantically significant in
+ <code class="type">character varying</code> and <code class="type">text</code> values, and
+ when using pattern matching, that is <code class="literal">LIKE</code> and
+ regular expressions.
+ </p><p>
+ The characters that can be stored in any of these data types are
+ determined by the database character set, which is selected when
+ the database is created. Regardless of the specific character set,
+ the character with code zero (sometimes called NUL) cannot be stored.
+ For more information refer to <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>.
+ </p><p>
+ The storage requirement for a short string (up to 126 bytes) is 1 byte
+ plus the actual string, which includes the space padding in the case of
+ <code class="type">character</code>. Longer strings have 4 bytes of overhead instead
+ of 1. Long strings are compressed by the system automatically, so
+ the physical requirement on disk might be less. Very long values are also
+ stored in background tables so that they do not interfere with rapid
+ access to shorter column values. In any case, the longest
+ possible character string that can be stored is about 1 GB. (The
+ maximum value that will be allowed for <em class="replaceable"><code>n</code></em> in the data
+ type declaration is less than that. It wouldn't be useful to
+ change this because with multibyte character encodings the number of
+ characters and bytes can be quite different. If you desire to
+ store long strings with no specific upper limit, use
+ <code class="type">text</code> or <code class="type">character varying</code> without a length
+ specifier, rather than making up an arbitrary length limit.)
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ There is no performance difference among these three types,
+ apart from increased storage space when using the blank-padded
+ type, and a few extra CPU cycles to check the length when storing into
+ a length-constrained column. While
+ <code class="type">character(<em class="replaceable"><code>n</code></em>)</code> has performance
+ advantages in some other database systems, there is no such advantage in
+ <span class="productname">PostgreSQL</span>; in fact
+ <code class="type">character(<em class="replaceable"><code>n</code></em>)</code> is usually the slowest of
+ the three because of its additional storage costs. In most situations
+ <code class="type">text</code> or <code class="type">character varying</code> should be used
+ instead.
+ </p></div><p>
+ Refer to <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> for information about
+ the syntax of string literals, and to <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>
+ for information about available operators and functions.
+ </p><div class="example" id="id-1.5.7.11.20"><p class="title"><strong>Example 8.1. Using the Character Types</strong></p><div class="example-contents"><pre class="programlisting">
+CREATE TABLE test1 (a character(4));
+INSERT INTO test1 VALUES ('ok');
+SELECT a, char_length(a) FROM test1; -- <span id="co.datatype-char"></span>(1)
+<code class="computeroutput">
+ a | char_length
+------+-------------
+ ok | 2
+</code>
+
+CREATE TABLE test2 (b varchar(5));
+INSERT INTO test2 VALUES ('ok');
+INSERT INTO test2 VALUES ('good ');
+INSERT INTO test2 VALUES ('too long');
+<code class="computeroutput">ERROR: value too long for type character varying(5)</code>
+INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
+SELECT b, char_length(b) FROM test2;
+<code class="computeroutput">
+ b | char_length
+-------+-------------
+ ok | 2
+ good | 5
+ too l | 5
+</code>
+</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co.datatype-char">(1)</a> </p></td><td valign="top" align="left"><p>
+ The <code class="function">char_length</code> function is discussed in
+ <a class="xref" href="functions-string.html" title="9.4. String Functions and Operators">Section 9.4</a>.
+ </p></td></tr></table></div></div></div><br class="example-break" /><p>
+ There are two other fixed-length character types in
+ <span class="productname">PostgreSQL</span>, shown in <a class="xref" href="datatype-character.html#DATATYPE-CHARACTER-SPECIAL-TABLE" title="Table 8.5. Special Character Types">Table 8.5</a>.
+ These are not intended for general-purpose use, only for use
+ in the internal system catalogs.
+ The <code class="type">name</code> type is used to store identifiers. Its
+ length is currently defined as 64 bytes (63 usable characters plus
+ terminator) but should be referenced using the constant
+ <code class="symbol">NAMEDATALEN</code> in <code class="literal">C</code> source code.
+ The length is set at compile time (and
+ is therefore adjustable for special uses); the default maximum
+ length might change in a future release. The type <code class="type">"char"</code>
+ (note the quotes) is different from <code class="type">char(1)</code> in that it
+ only uses one byte of storage, and therefore can store only a single
+ ASCII character. It is used in the system
+ catalogs as a simplistic enumeration type.
+ </p><div class="table" id="DATATYPE-CHARACTER-SPECIAL-TABLE"><p class="title"><strong>Table 8.5. Special Character Types</strong></p><div class="table-contents"><table class="table" summary="Special Character Types" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">"char"</code></td><td>1 byte</td><td>single-byte internal type</td></tr><tr><td><code class="type">name</code></td><td>64 bytes</td><td>internal type for object names</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-money.html" title="8.2. Monetary Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-binary.html" title="8.4. Binary Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.2. Monetary Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.4. Binary Data Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-datetime.html b/doc/src/sgml/html/datatype-datetime.html
new file mode 100644
index 0000000..f16f5fe
--- /dev/null
+++ b/doc/src/sgml/html/datatype-datetime.html
@@ -0,0 +1,550 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.5. Date/Time Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-binary.html" title="8.4. Binary Data Types" /><link rel="next" href="datatype-boolean.html" title="8.6. Boolean Type" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.5. Date/Time Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-binary.html" title="8.4. Binary Data Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-boolean.html" title="8.6. Boolean Type">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-DATETIME"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.5. Date/Time Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-DATETIME-INPUT">8.5.1. Date/Time Input</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT">8.5.2. Date/Time Output</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-TIMEZONES">8.5.3. Time Zones</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-INTERVAL-INPUT">8.5.4. Interval Input</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-INTERVAL-OUTPUT">8.5.5. Interval Output</a></span></dt></dl></div><a id="id-1.5.7.13.2" class="indexterm"></a><a id="id-1.5.7.13.3" class="indexterm"></a><a id="id-1.5.7.13.4" class="indexterm"></a><a id="id-1.5.7.13.5" class="indexterm"></a><a id="id-1.5.7.13.6" class="indexterm"></a><a id="id-1.5.7.13.7" class="indexterm"></a><a id="id-1.5.7.13.8" class="indexterm"></a><a id="id-1.5.7.13.9" class="indexterm"></a><a id="id-1.5.7.13.10" class="indexterm"></a><a id="id-1.5.7.13.11" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> supports the full set of
+ <acronym class="acronym">SQL</acronym> date and time types, shown in <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-TABLE" title="Table 8.9. Date/Time Types">Table 8.9</a>. The operations available
+ on these data types are described in
+ <a class="xref" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators">Section 9.9</a>.
+ Dates are counted according to the Gregorian calendar, even in
+ years before that calendar was introduced (see <a class="xref" href="datetime-units-history.html" title="B.6. History of Units">Section B.6</a> for more information).
+ </p><div class="table" id="DATATYPE-DATETIME-TABLE"><p class="title"><strong>Table 8.9. Date/Time Types</strong></p><div class="table-contents"><table class="table" summary="Date/Time Types" border="1"><colgroup><col /><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th><th>Low Value</th><th>High Value</th><th>Resolution</th></tr></thead><tbody><tr><td><code class="type">timestamp [ (<em class="replaceable"><code>p</code></em>) ] [ without time zone ]</code></td><td>8 bytes</td><td>both date and time (no time zone)</td><td>4713 BC</td><td>294276 AD</td><td>1 microsecond</td></tr><tr><td><code class="type">timestamp [ (<em class="replaceable"><code>p</code></em>) ] with time zone</code></td><td>8 bytes</td><td>both date and time, with time zone</td><td>4713 BC</td><td>294276 AD</td><td>1 microsecond</td></tr><tr><td><code class="type">date</code></td><td>4 bytes</td><td>date (no time of day)</td><td>4713 BC</td><td>5874897 AD</td><td>1 day</td></tr><tr><td><code class="type">time [ (<em class="replaceable"><code>p</code></em>) ] [ without time zone ]</code></td><td>8 bytes</td><td>time of day (no date)</td><td>00:00:00</td><td>24:00:00</td><td>1 microsecond</td></tr><tr><td><code class="type">time [ (<em class="replaceable"><code>p</code></em>) ] with time zone</code></td><td>12 bytes</td><td>time of day (no date), with time zone</td><td>00:00:00+1559</td><td>24:00:00-1559</td><td>1 microsecond</td></tr><tr><td><code class="type">interval [ <em class="replaceable"><code>fields</code></em> ] [ (<em class="replaceable"><code>p</code></em>) ]</code></td><td>16 bytes</td><td>time interval</td><td>-178000000 years</td><td>178000000 years</td><td>1 microsecond</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The SQL standard requires that writing just <code class="type">timestamp</code>
+ be equivalent to <code class="type">timestamp without time
+ zone</code>, and <span class="productname">PostgreSQL</span> honors that
+ behavior. <code class="type">timestamptz</code> is accepted as an
+ abbreviation for <code class="type">timestamp with time zone</code>; this is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><p>
+ <code class="type">time</code>, <code class="type">timestamp</code>, and
+ <code class="type">interval</code> accept an optional precision value
+ <em class="replaceable"><code>p</code></em> which specifies the number of
+ fractional digits retained in the seconds field. By default, there
+ is no explicit bound on precision. The allowed range of
+ <em class="replaceable"><code>p</code></em> is from 0 to 6.
+ </p><p>
+ The <code class="type">interval</code> type has an additional option, which is
+ to restrict the set of stored fields by writing one of these phrases:
+</p><pre class="literallayout">
+YEAR
+MONTH
+DAY
+HOUR
+MINUTE
+SECOND
+YEAR TO MONTH
+DAY TO HOUR
+DAY TO MINUTE
+DAY TO SECOND
+HOUR TO MINUTE
+HOUR TO SECOND
+MINUTE TO SECOND
+</pre><p>
+ Note that if both <em class="replaceable"><code>fields</code></em> and
+ <em class="replaceable"><code>p</code></em> are specified, the
+ <em class="replaceable"><code>fields</code></em> must include <code class="literal">SECOND</code>,
+ since the precision applies only to the seconds.
+ </p><p>
+ The type <code class="type">time with time zone</code> is defined by the SQL
+ standard, but the definition exhibits properties which lead to
+ questionable usefulness. In most cases, a combination of
+ <code class="type">date</code>, <code class="type">time</code>, <code class="type">timestamp without time
+ zone</code>, and <code class="type">timestamp with time zone</code> should
+ provide a complete range of date/time functionality required by
+ any application.
+ </p><div class="sect2" id="DATATYPE-DATETIME-INPUT"><div class="titlepage"><div><div><h3 class="title">8.5.1. Date/Time Input</h3></div></div></div><p>
+ Date and time input is accepted in almost any reasonable format, including
+ ISO 8601, <acronym class="acronym">SQL</acronym>-compatible,
+ traditional <span class="productname">POSTGRES</span>, 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 <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a> parameter
+ to <code class="literal">MDY</code> to select month-day-year interpretation,
+ <code class="literal">DMY</code> to select day-month-year interpretation, or
+ <code class="literal">YMD</code> to select year-month-day interpretation.
+ </p><p>
+ <span class="productname">PostgreSQL</span> is more flexible in
+ handling date/time input than the
+ <acronym class="acronym">SQL</acronym> standard requires.
+ See <a class="xref" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Appendix B</a>
+ for the exact parsing rules of date/time input and for the
+ recognized text fields including months, days of the week, and
+ time zones.
+ </p><p>
+ Remember that any date or time literal input needs to be enclosed
+ in single quotes, like text strings. Refer to
+ <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC" title="4.1.2.7. Constants of Other Types">Section 4.1.2.7</a> for more
+ information.
+ <acronym class="acronym">SQL</acronym> requires the following syntax
+</p><pre class="synopsis">
+<em class="replaceable"><code>type</code></em> [ (<em class="replaceable"><code>p</code></em>) ] '<em class="replaceable"><code>value</code></em>'
+</pre><p>
+ where <em class="replaceable"><code>p</code></em> is an optional precision
+ specification giving the number of
+ fractional digits in the seconds field. Precision can be
+ specified for <code class="type">time</code>, <code class="type">timestamp</code>, and
+ <code class="type">interval</code> types, and can range from 0 to 6.
+ If no precision is specified in a constant specification,
+ it defaults to the precision of the literal value (but not
+ more than 6 digits).
+ </p><div class="sect3" id="id-1.5.7.13.18.5"><div class="titlepage"><div><div><h4 class="title">8.5.1.1. Dates</h4></div></div></div><a id="id-1.5.7.13.18.5.2" class="indexterm"></a><p>
+ <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-DATE-TABLE" title="Table 8.10. Date Input">Table 8.10</a> shows some possible
+ inputs for the <code class="type">date</code> type.
+ </p><div class="table" id="DATATYPE-DATETIME-DATE-TABLE"><p class="title"><strong>Table 8.10. Date Input</strong></p><div class="table-contents"><table class="table" summary="Date Input" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>1999-01-08</td><td>ISO 8601; January 8 in any mode
+ (recommended format)</td></tr><tr><td>January 8, 1999</td><td>unambiguous in any <code class="varname">datestyle</code> input mode</td></tr><tr><td>1/8/1999</td><td>January 8 in <code class="literal">MDY</code> mode;
+ August 1 in <code class="literal">DMY</code> mode</td></tr><tr><td>1/18/1999</td><td>January 18 in <code class="literal">MDY</code> mode;
+ rejected in other modes</td></tr><tr><td>01/02/03</td><td>January 2, 2003 in <code class="literal">MDY</code> mode;
+ February 1, 2003 in <code class="literal">DMY</code> mode;
+ February 3, 2001 in <code class="literal">YMD</code> mode
+ </td></tr><tr><td>1999-Jan-08</td><td>January 8 in any mode</td></tr><tr><td>Jan-08-1999</td><td>January 8 in any mode</td></tr><tr><td>08-Jan-1999</td><td>January 8 in any mode</td></tr><tr><td>99-Jan-08</td><td>January 8 in <code class="literal">YMD</code> mode, else error</td></tr><tr><td>08-Jan-99</td><td>January 8, except error in <code class="literal">YMD</code> mode</td></tr><tr><td>Jan-08-99</td><td>January 8, except error in <code class="literal">YMD</code> mode</td></tr><tr><td>19990108</td><td>ISO 8601; January 8, 1999 in any mode</td></tr><tr><td>990108</td><td>ISO 8601; January 8, 1999 in any mode</td></tr><tr><td>1999.008</td><td>year and day of year</td></tr><tr><td>J2451187</td><td>Julian date</td></tr><tr><td>January 8, 99 BC</td><td>year 99 BC</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect3" id="id-1.5.7.13.18.6"><div class="titlepage"><div><div><h4 class="title">8.5.1.2. Times</h4></div></div></div><a id="id-1.5.7.13.18.6.2" class="indexterm"></a><a id="id-1.5.7.13.18.6.3" class="indexterm"></a><a id="id-1.5.7.13.18.6.4" class="indexterm"></a><p>
+ The time-of-day types are <code class="type">time [
+ (<em class="replaceable"><code>p</code></em>) ] without time zone</code> and
+ <code class="type">time [ (<em class="replaceable"><code>p</code></em>) ] with time
+ zone</code>. <code class="type">time</code> alone is equivalent to
+ <code class="type">time without time zone</code>.
+ </p><p>
+ Valid input for these types consists of a time of day followed
+ by an optional time zone. (See <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-TIME-TABLE" title="Table 8.11. Time Input">Table 8.11</a>
+ and <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONE-TABLE" title="Table 8.12. Time Zone Input">Table 8.12</a>.) If a time zone is
+ specified in the input for <code class="type">time without time zone</code>,
+ 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
+ daylight-savings rule, such as
+ <code class="literal">America/New_York</code>. In this case specifying the date
+ is required in order to determine whether standard or daylight-savings
+ time applies. The appropriate time zone offset is recorded in the
+ <code class="type">time with time zone</code> value and is output as stored;
+ it is not adjusted to the active time zone.
+ </p><div class="table" id="DATATYPE-DATETIME-TIME-TABLE"><p class="title"><strong>Table 8.11. Time Input</strong></p><div class="table-contents"><table class="table" summary="Time Input" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Example</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">04:05:06.789</code></td><td>ISO 8601</td></tr><tr><td><code class="literal">04:05:06</code></td><td>ISO 8601</td></tr><tr><td><code class="literal">04:05</code></td><td>ISO 8601</td></tr><tr><td><code class="literal">040506</code></td><td>ISO 8601</td></tr><tr><td><code class="literal">04:05 AM</code></td><td>same as 04:05; AM does not affect value</td></tr><tr><td><code class="literal">04:05 PM</code></td><td>same as 16:05; input hour must be &lt;= 12</td></tr><tr><td><code class="literal">04:05:06.789-8</code></td><td>ISO 8601, with time zone as UTC offset</td></tr><tr><td><code class="literal">04:05:06-08:00</code></td><td>ISO 8601, with time zone as UTC offset</td></tr><tr><td><code class="literal">04:05-08:00</code></td><td>ISO 8601, with time zone as UTC offset</td></tr><tr><td><code class="literal">040506-08</code></td><td>ISO 8601, with time zone as UTC offset</td></tr><tr><td><code class="literal">040506+0730</code></td><td>ISO 8601, with fractional-hour time zone as UTC offset</td></tr><tr><td><code class="literal">040506+07:30:00</code></td><td>UTC offset specified to seconds (not allowed in ISO 8601)</td></tr><tr><td><code class="literal">04:05:06 PST</code></td><td>time zone specified by abbreviation</td></tr><tr><td><code class="literal">2003-04-12 04:05:06 America/New_York</code></td><td>time zone specified by full name</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="DATATYPE-TIMEZONE-TABLE"><p class="title"><strong>Table 8.12. Time Zone Input</strong></p><div class="table-contents"><table class="table" summary="Time Zone Input" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Example</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">PST</code></td><td>Abbreviation (for Pacific Standard Time)</td></tr><tr><td><code class="literal">America/New_York</code></td><td>Full time zone name</td></tr><tr><td><code class="literal">PST8PDT</code></td><td>POSIX-style time zone specification</td></tr><tr><td><code class="literal">-8:00:00</code></td><td>UTC offset for PST</td></tr><tr><td><code class="literal">-8:00</code></td><td>UTC offset for PST (ISO 8601 extended format)</td></tr><tr><td><code class="literal">-800</code></td><td>UTC offset for PST (ISO 8601 basic format)</td></tr><tr><td><code class="literal">-8</code></td><td>UTC offset for PST (ISO 8601 basic format)</td></tr><tr><td><code class="literal">zulu</code></td><td>Military abbreviation for UTC</td></tr><tr><td><code class="literal">z</code></td><td>Short form of <code class="literal">zulu</code> (also in ISO 8601)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Refer to <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a> for more information on how
+ to specify time zones.
+ </p></div><div class="sect3" id="id-1.5.7.13.18.7"><div class="titlepage"><div><div><h4 class="title">8.5.1.3. Time Stamps</h4></div></div></div><a id="id-1.5.7.13.18.7.2" class="indexterm"></a><a id="id-1.5.7.13.18.7.3" class="indexterm"></a><a id="id-1.5.7.13.18.7.4" class="indexterm"></a><p>
+ Valid input for the time stamp types consists of the concatenation
+ of a date and a time, followed by an optional time zone,
+ followed by an optional <code class="literal">AD</code> or <code class="literal">BC</code>.
+ (Alternatively, <code class="literal">AD</code>/<code class="literal">BC</code> can appear
+ before the time zone, but this is not the preferred ordering.)
+ Thus:
+
+</p><pre class="programlisting">
+1999-01-08 04:05:06
+</pre><p>
+ and:
+</p><pre class="programlisting">
+1999-01-08 04:05:06 -8:00
+</pre><p>
+
+ are valid values, which follow the <acronym class="acronym">ISO</acronym> 8601
+ standard. In addition, the common format:
+</p><pre class="programlisting">
+January 8 04:05:06 1999 PST
+</pre><p>
+ is supported.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> standard differentiates
+ <code class="type">timestamp without time zone</code>
+ and <code class="type">timestamp with time zone</code> literals by the presence of a
+ <span class="quote">“<span class="quote">+</span>”</span> or <span class="quote">“<span class="quote">-</span>”</span> symbol and time zone offset after
+ the time. Hence, according to the standard,
+
+</p><pre class="programlisting">
+TIMESTAMP '2004-10-19 10:23:54'
+</pre><p>
+
+ is a <code class="type">timestamp without time zone</code>, while
+
+</p><pre class="programlisting">
+TIMESTAMP '2004-10-19 10:23:54+02'
+</pre><p>
+
+ is a <code class="type">timestamp with time zone</code>.
+ <span class="productname">PostgreSQL</span> never examines the content of a
+ literal string before determining its type, and therefore will treat
+ both of the above as <code class="type">timestamp without time zone</code>. To
+ ensure that a literal is treated as <code class="type">timestamp with time
+ zone</code>, give it the correct explicit type:
+
+</p><pre class="programlisting">
+TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
+</pre><p>
+
+ In a literal that has been determined to be <code class="type">timestamp without time
+ zone</code>, <span class="productname">PostgreSQL</span> will silently ignore
+ any time zone indication.
+ That is, the resulting value is derived from the date/time
+ fields in the input value, and is not adjusted for time zone.
+ </p><p>
+ For <code class="type">timestamp with time zone</code>, the internally stored
+ value is always in UTC (Universal
+ Coordinated Time, traditionally known as Greenwich Mean Time,
+ <acronym class="acronym">GMT</acronym>). An input value that has an explicit
+ 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
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> parameter, and is converted to UTC using the
+ offset for the <code class="varname">timezone</code> zone.
+ </p><p>
+ When a <code class="type">timestamp with time
+ zone</code> value is output, it is always converted from UTC to the
+ current <code class="varname">timezone</code> zone, and displayed as local time in that
+ zone. To see the time in another time zone, either change
+ <code class="varname">timezone</code> or use the <code class="literal">AT TIME ZONE</code> construct
+ (see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT" title="9.9.4. AT TIME ZONE">Section 9.9.4</a>).
+ </p><p>
+ Conversions between <code class="type">timestamp without time zone</code> and
+ <code class="type">timestamp with time zone</code> normally assume that the
+ <code class="type">timestamp without time zone</code> value should be taken or given
+ as <code class="varname">timezone</code> local time. A different time zone can
+ be specified for the conversion using <code class="literal">AT TIME ZONE</code>.
+ </p></div><div class="sect3" id="DATATYPE-DATETIME-SPECIAL-VALUES"><div class="titlepage"><div><div><h4 class="title">8.5.1.4. Special Values</h4></div></div></div><a id="id-1.5.7.13.18.8.2" class="indexterm"></a><a id="id-1.5.7.13.18.8.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> supports several
+ special date/time input values for convenience, as shown in <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-TABLE" title="Table 8.13. Special Date/Time Inputs">Table 8.13</a>. The values
+ <code class="literal">infinity</code> and <code class="literal">-infinity</code>
+ are specially represented inside the system and will be displayed
+ unchanged; but the others are simply notational shorthands
+ that will be converted to ordinary date/time values when read.
+ (In particular, <code class="literal">now</code> and related strings are converted
+ to a specific time value as soon as they are read.)
+ All of these values need to be enclosed in single quotes when used
+ as constants in SQL commands.
+ </p><div class="table" id="DATATYPE-DATETIME-SPECIAL-TABLE"><p class="title"><strong>Table 8.13. Special Date/Time Inputs</strong></p><div class="table-contents"><table class="table" summary="Special Date/Time Inputs" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Input String</th><th>Valid Types</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">epoch</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>1970-01-01 00:00:00+00 (Unix system time zero)</td></tr><tr><td><code class="literal">infinity</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>later than all other time stamps</td></tr><tr><td><code class="literal">-infinity</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>earlier than all other time stamps</td></tr><tr><td><code class="literal">now</code></td><td><code class="type">date</code>, <code class="type">time</code>, <code class="type">timestamp</code></td><td>current transaction's start time</td></tr><tr><td><code class="literal">today</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>midnight (<code class="literal">00:00</code>) today</td></tr><tr><td><code class="literal">tomorrow</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>midnight (<code class="literal">00:00</code>) tomorrow</td></tr><tr><td><code class="literal">yesterday</code></td><td><code class="type">date</code>, <code class="type">timestamp</code></td><td>midnight (<code class="literal">00:00</code>) yesterday</td></tr><tr><td><code class="literal">allballs</code></td><td><code class="type">time</code></td><td>00:00:00.00 UTC</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The following <acronym class="acronym">SQL</acronym>-compatible functions can also
+ be used to obtain the current time value for the corresponding data
+ type:
+ <code class="literal">CURRENT_DATE</code>, <code class="literal">CURRENT_TIME</code>,
+ <code class="literal">CURRENT_TIMESTAMP</code>, <code class="literal">LOCALTIME</code>,
+ <code class="literal">LOCALTIMESTAMP</code>. (See <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>.) Note that these are
+ SQL functions and are <span class="emphasis"><em>not</em></span> recognized in data input strings.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ While the input strings <code class="literal">now</code>,
+ <code class="literal">today</code>, <code class="literal">tomorrow</code>,
+ and <code class="literal">yesterday</code> are fine to use in interactive SQL
+ commands, they can have surprising behavior when the command is
+ saved to be executed later, for example in prepared statements,
+ views, and function definitions. The string can be converted to a
+ specific time value that continues to be used long after it becomes
+ stale. Use one of the SQL functions instead in such contexts.
+ For example, <code class="literal">CURRENT_DATE + 1</code> is safer than
+ <code class="literal">'tomorrow'::date</code>.
+ </p></div></div></div><div class="sect2" id="DATATYPE-DATETIME-OUTPUT"><div class="titlepage"><div><div><h3 class="title">8.5.2. Date/Time Output</h3></div></div></div><a id="id-1.5.7.13.19.2" class="indexterm"></a><a id="id-1.5.7.13.19.3" class="indexterm"></a><p>
+ The output format of the date/time types can be set to one of the four
+ styles ISO 8601,
+ <acronym class="acronym">SQL</acronym> (Ingres), traditional <span class="productname">POSTGRES</span>
+ (Unix <span class="application">date</span> format), or
+ German. The default
+ is the <acronym class="acronym">ISO</acronym> format. (The
+ <acronym class="acronym">SQL</acronym> standard requires the use of the ISO 8601
+ format. The name of the <span class="quote">“<span class="quote">SQL</span>”</span> output format is a
+ historical accident.) <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT-TABLE" title="Table 8.14. Date/Time Output Styles">Table 8.14</a> shows examples of each
+ output style. The output of the <code class="type">date</code> and
+ <code class="type">time</code> types is generally only the date or time part
+ in accordance with the given examples. However, the
+ <span class="productname">POSTGRES</span> style outputs date-only values in
+ <acronym class="acronym">ISO</acronym> format.
+ </p><div class="table" id="DATATYPE-DATETIME-OUTPUT-TABLE"><p class="title"><strong>Table 8.14. Date/Time Output Styles</strong></p><div class="table-contents"><table class="table" summary="Date/Time Output Styles" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Style Specification</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code class="literal">ISO</code></td><td>ISO 8601, SQL standard</td><td><code class="literal">1997-12-17 07:37:16-08</code></td></tr><tr><td><code class="literal">SQL</code></td><td>traditional style</td><td><code class="literal">12/17/1997 07:37:16.00 PST</code></td></tr><tr><td><code class="literal">Postgres</code></td><td>original style</td><td><code class="literal">Wed Dec 17 07:37:16 1997 PST</code></td></tr><tr><td><code class="literal">German</code></td><td>regional style</td><td><code class="literal">17.12.1997 07:37:16.00 PST</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ ISO 8601 specifies the use of uppercase letter <code class="literal">T</code> to separate
+ the date and time. <span class="productname">PostgreSQL</span> accepts that format on
+ input, but on output it uses a space rather than <code class="literal">T</code>, as shown
+ above. This is for readability and for consistency with
+ <a class="ulink" href="https://tools.ietf.org/html/rfc3339" target="_top">RFC 3339</a> as
+ well as some other database systems.
+ </p></div><p>
+ In the <acronym class="acronym">SQL</acronym> and POSTGRES styles, day appears before
+ month if DMY field ordering has been specified, otherwise month appears
+ before day.
+ (See <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-INPUT" title="8.5.1. Date/Time Input">Section 8.5.1</a>
+ for how this setting also affects interpretation of input values.)
+ <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT2-TABLE" title="Table 8.15. Date Order Conventions">Table 8.15</a> shows examples.
+ </p><div class="table" id="DATATYPE-DATETIME-OUTPUT2-TABLE"><p class="title"><strong>Table 8.15. Date Order Conventions</strong></p><div class="table-contents"><table class="table" summary="Date Order Conventions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th><code class="varname">datestyle</code> Setting</th><th>Input Ordering</th><th>Example Output</th></tr></thead><tbody><tr><td><code class="literal">SQL, DMY</code></td><td><em class="replaceable"><code>day</code></em>/<em class="replaceable"><code>month</code></em>/<em class="replaceable"><code>year</code></em></td><td><code class="literal">17/12/1997 15:37:16.00 CET</code></td></tr><tr><td><code class="literal">SQL, MDY</code></td><td><em class="replaceable"><code>month</code></em>/<em class="replaceable"><code>day</code></em>/<em class="replaceable"><code>year</code></em></td><td><code class="literal">12/17/1997 07:37:16.00 PST</code></td></tr><tr><td><code class="literal">Postgres, DMY</code></td><td><em class="replaceable"><code>day</code></em>/<em class="replaceable"><code>month</code></em>/<em class="replaceable"><code>year</code></em></td><td><code class="literal">Wed 17 Dec 07:37:16 1997 PST</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In the <acronym class="acronym">ISO</acronym> style, the time zone is always shown as
+ a signed numeric offset from UTC, with positive sign used for zones
+ east of Greenwich. The offset will be shown
+ as <em class="replaceable"><code>hh</code></em> (hours only) if it is an integral
+ number of hours, else
+ as <em class="replaceable"><code>hh</code></em>:<em class="replaceable"><code>mm</code></em> if it
+ is an integral number of minutes, else as
+ <em class="replaceable"><code>hh</code></em>:<em class="replaceable"><code>mm</code></em>:<em class="replaceable"><code>ss</code></em>.
+ (The third case is not possible with any modern time zone standard,
+ but it can appear when working with timestamps that predate the
+ adoption of standardized time zones.)
+ In the other date styles, the time zone is shown as an alphabetic
+ abbreviation if one is in common use in the current zone. Otherwise
+ it appears as a signed numeric offset in ISO 8601 basic format
+ (<em class="replaceable"><code>hh</code></em> or <em class="replaceable"><code>hhmm</code></em>).
+ </p><p>
+ The date/time style can be selected by the user using the
+ <code class="command">SET datestyle</code> command, the <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a> parameter in the
+ <code class="filename">postgresql.conf</code> configuration file, or the
+ <code class="envar">PGDATESTYLE</code> environment variable on the server or
+ client.
+ </p><p>
+ The formatting function <code class="function">to_char</code>
+ (see <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>) is also available as
+ a more flexible way to format date/time output.
+ </p></div><div class="sect2" id="DATATYPE-TIMEZONES"><div class="titlepage"><div><div><h3 class="title">8.5.3. Time Zones</h3></div></div></div><a id="id-1.5.7.13.20.2" class="indexterm"></a><p>
+ Time zones, and time-zone conventions, are influenced by
+ political decisions, not just earth geometry. Time zones around the
+ world became somewhat standardized during the 1900s,
+ but continue to be prone to arbitrary changes, particularly with
+ respect to daylight-savings rules.
+ <span class="productname">PostgreSQL</span> uses the widely-used
+ IANA (Olson) time zone database for information about
+ historical time zone rules. For times in the future, the assumption
+ is that the latest known rules for a given time zone will
+ continue to be observed indefinitely far into the future.
+ </p><p>
+ <span class="productname">PostgreSQL</span> endeavors to be compatible with
+ the <acronym class="acronym">SQL</acronym> standard definitions for typical usage.
+ However, the <acronym class="acronym">SQL</acronym> standard has an odd mix of date and
+ time types and capabilities. Two obvious problems are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Although the <code class="type">date</code> type
+ cannot have an associated time zone, the
+ <code class="type">time</code> type can.
+ Time zones in the real world have little meaning unless
+ associated with a date as well as a time,
+ since the offset can vary through the year with daylight-saving
+ time boundaries.
+ </p></li><li class="listitem"><p>
+ The default time zone is specified as a constant numeric offset
+ from <acronym class="acronym">UTC</acronym>. It is therefore impossible to adapt to
+ daylight-saving time when doing date/time arithmetic across
+ <acronym class="acronym">DST</acronym> boundaries.
+ </p></li></ul></div><p>
+ </p><p>
+ To address these difficulties, we recommend using date/time types
+ that contain both date and time when using time zones. We
+ do <span class="emphasis"><em>not</em></span> recommend using the type <code class="type">time with
+ time zone</code> (though it is supported by
+ <span class="productname">PostgreSQL</span> for legacy applications and
+ for compliance with the <acronym class="acronym">SQL</acronym> standard).
+ <span class="productname">PostgreSQL</span> assumes
+ your local time zone for any type containing only date or time.
+ </p><p>
+ All timezone-aware dates and times are stored internally in
+ <acronym class="acronym">UTC</acronym>. They are converted to local time
+ in the zone specified by the <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> configuration
+ parameter before being displayed to the client.
+ </p><p>
+ <span class="productname">PostgreSQL</span> allows you to specify time zones in
+ three different forms:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A full time zone name, for example <code class="literal">America/New_York</code>.
+ The recognized time zone names are listed in the
+ <code class="literal">pg_timezone_names</code> view (see <a class="xref" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names">Section 54.32</a>).
+ <span class="productname">PostgreSQL</span> uses the widely-used IANA
+ time zone data for this purpose, so the same time zone
+ names are also recognized by other software.
+ </p></li><li class="listitem"><p>
+ A time zone abbreviation, for example <code class="literal">PST</code>. Such a
+ specification merely defines a particular offset from UTC, in
+ contrast to full time zone names which can imply a set of daylight
+ savings transition rules as well. The recognized abbreviations
+ are listed in the <code class="literal">pg_timezone_abbrevs</code> view (see <a class="xref" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs">Section 54.31</a>). You cannot set the
+ configuration parameters <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> or
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-TIMEZONE">log_timezone</a> to a time
+ zone abbreviation, but you can use abbreviations in
+ date/time input values and with the <code class="literal">AT TIME ZONE</code>
+ operator.
+ </p></li><li class="listitem"><p>
+ In addition to the timezone names and abbreviations,
+ <span class="productname">PostgreSQL</span> will accept POSIX-style time zone
+ specifications, as described in
+ <a class="xref" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications">Section B.5</a>. This option is not
+ normally preferable to using a named time zone, but it may be
+ necessary if no suitable IANA time zone entry is available.
+ </p></li></ul></div><p>
+
+ In short, this is the difference between abbreviations
+ and full names: abbreviations represent a specific offset from UTC,
+ whereas many of the full names imply a local daylight-savings time
+ rule, and so have two possible UTC offsets. As an example,
+ <code class="literal">2014-06-04 12:00 America/New_York</code> represents noon local
+ time in New York, which for this particular date was Eastern Daylight
+ Time (UTC-4). So <code class="literal">2014-06-04 12:00 EDT</code> specifies that
+ same time instant. But <code class="literal">2014-06-04 12:00 EST</code> specifies
+ noon Eastern Standard Time (UTC-5), regardless of whether daylight
+ savings was nominally in effect on that date.
+ </p><p>
+ To complicate matters, some jurisdictions have used the same timezone
+ abbreviation to mean different UTC offsets at different times; for
+ example, in Moscow <code class="literal">MSK</code> has meant UTC+3 in some years and
+ UTC+4 in others. <span class="application">PostgreSQL</span> interprets such
+ abbreviations according to whatever they meant (or had most recently
+ meant) on the specified date; but, as with the <code class="literal">EST</code> example
+ above, this is not necessarily the same as local civil time on that date.
+ </p><p>
+ In all cases, timezone names and abbreviations are recognized
+ case-insensitively. (This is a change from <span class="productname">PostgreSQL</span>
+ versions prior to 8.2, which were case-sensitive in some contexts but
+ not others.)
+ </p><p>
+ Neither timezone names nor abbreviations are hard-wired into the server;
+ they are obtained from configuration files stored under
+ <code class="filename">.../share/timezone/</code> and <code class="filename">.../share/timezonesets/</code>
+ of the installation directory
+ (see <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a>).
+ </p><p>
+ The <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> configuration parameter can
+ be set in the file <code class="filename">postgresql.conf</code>, or in any of the
+ other standard ways described in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.
+ There are also some special ways to set it:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <acronym class="acronym">SQL</acronym> command <code class="command">SET TIME ZONE</code>
+ sets the time zone for the session. This is an alternative spelling
+ of <code class="command">SET TIMEZONE TO</code> with a more SQL-spec-compatible syntax.
+ </p></li><li class="listitem"><p>
+ The <code class="envar">PGTZ</code> environment variable is used by
+ <span class="application">libpq</span> clients
+ to send a <code class="command">SET TIME ZONE</code>
+ command to the server upon connection.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="DATATYPE-INTERVAL-INPUT"><div class="titlepage"><div><div><h3 class="title">8.5.4. Interval Input</h3></div></div></div><a id="id-1.5.7.13.21.2" class="indexterm"></a><p>
+ <code class="type">interval</code> values can be written using the following
+ verbose syntax:
+
+</p><pre class="synopsis">
+[<span class="optional">@</span>] <em class="replaceable"><code>quantity</code></em> <em class="replaceable"><code>unit</code></em> [<span class="optional"><em class="replaceable"><code>quantity</code></em> <em class="replaceable"><code>unit</code></em>...</span>] [<span class="optional"><em class="replaceable"><code>direction</code></em></span>]
+</pre><p>
+
+ where <em class="replaceable"><code>quantity</code></em> is a number (possibly signed);
+ <em class="replaceable"><code>unit</code></em> is <code class="literal">microsecond</code>,
+ <code class="literal">millisecond</code>, <code class="literal">second</code>,
+ <code class="literal">minute</code>, <code class="literal">hour</code>, <code class="literal">day</code>,
+ <code class="literal">week</code>, <code class="literal">month</code>, <code class="literal">year</code>,
+ <code class="literal">decade</code>, <code class="literal">century</code>, <code class="literal">millennium</code>,
+ or abbreviations or plurals of these units;
+ <em class="replaceable"><code>direction</code></em> can be <code class="literal">ago</code> or
+ empty. The at sign (<code class="literal">@</code>) is optional noise. The amounts
+ of the different units are implicitly added with appropriate
+ sign accounting. <code class="literal">ago</code> negates all the fields.
+ This syntax is also used for interval output, if
+ <a class="xref" href="runtime-config-client.html#GUC-INTERVALSTYLE">IntervalStyle</a> is set to
+ <code class="literal">postgres_verbose</code>.
+ </p><p>
+ Quantities of days, hours, minutes, and seconds can be specified without
+ explicit unit markings. For example, <code class="literal">'1 12:59:10'</code> is read
+ the same as <code class="literal">'1 day 12 hours 59 min 10 sec'</code>. Also,
+ a combination of years and months can be specified with a dash;
+ for example <code class="literal">'200-10'</code> is read the same as <code class="literal">'200 years
+ 10 months'</code>. (These shorter forms are in fact the only ones allowed
+ by the <acronym class="acronym">SQL</acronym> standard, and are used for output when
+ <code class="varname">IntervalStyle</code> is set to <code class="literal">sql_standard</code>.)
+ </p><p>
+ Interval values can also be written as ISO 8601 time intervals, using
+ either the <span class="quote">“<span class="quote">format with designators</span>”</span> of the standard's section
+ 4.4.3.2 or the <span class="quote">“<span class="quote">alternative format</span>”</span> of section 4.4.3.3. The
+ format with designators looks like this:
+</p><pre class="synopsis">
+P <em class="replaceable"><code>quantity</code></em> <em class="replaceable"><code>unit</code></em> [<span class="optional"> <em class="replaceable"><code>quantity</code></em> <em class="replaceable"><code>unit</code></em> ...</span>] [<span class="optional"> T [<span class="optional"> <em class="replaceable"><code>quantity</code></em> <em class="replaceable"><code>unit</code></em> ...</span>]</span>]
+</pre><p>
+ The string must start with a <code class="literal">P</code>, and may include a
+ <code class="literal">T</code> that introduces the time-of-day units. The
+ available unit abbreviations are given in <a class="xref" href="datatype-datetime.html#DATATYPE-INTERVAL-ISO8601-UNITS" title="Table 8.16. ISO 8601 Interval Unit Abbreviations">Table 8.16</a>. Units may be
+ omitted, and may be specified in any order, but units smaller than
+ a day must appear after <code class="literal">T</code>. In particular, the meaning of
+ <code class="literal">M</code> depends on whether it is before or after
+ <code class="literal">T</code>.
+ </p><div class="table" id="DATATYPE-INTERVAL-ISO8601-UNITS"><p class="title"><strong>Table 8.16. ISO 8601 Interval Unit Abbreviations</strong></p><div class="table-contents"><table class="table" summary="ISO 8601 Interval Unit Abbreviations" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Abbreviation</th><th>Meaning</th></tr></thead><tbody><tr><td>Y</td><td>Years</td></tr><tr><td>M</td><td>Months (in the date part)</td></tr><tr><td>W</td><td>Weeks</td></tr><tr><td>D</td><td>Days</td></tr><tr><td>H</td><td>Hours</td></tr><tr><td>M</td><td>Minutes (in the time part)</td></tr><tr><td>S</td><td>Seconds</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In the alternative format:
+</p><pre class="synopsis">
+P [<span class="optional"> <em class="replaceable"><code>years</code></em>-<em class="replaceable"><code>months</code></em>-<em class="replaceable"><code>days</code></em> </span>] [<span class="optional"> T <em class="replaceable"><code>hours</code></em>:<em class="replaceable"><code>minutes</code></em>:<em class="replaceable"><code>seconds</code></em> </span>]
+</pre><p>
+ the string must begin with <code class="literal">P</code>, and a
+ <code class="literal">T</code> separates the date and time parts of the interval.
+ The values are given as numbers similar to ISO 8601 dates.
+ </p><p>
+ When writing an interval constant with a <em class="replaceable"><code>fields</code></em>
+ specification, or when assigning a string to an interval column that was
+ defined with a <em class="replaceable"><code>fields</code></em> specification, the interpretation of
+ unmarked quantities depends on the <em class="replaceable"><code>fields</code></em>. For
+ example <code class="literal">INTERVAL '1' YEAR</code> is read as 1 year, whereas
+ <code class="literal">INTERVAL '1'</code> means 1 second. Also, field values
+ <span class="quote">“<span class="quote">to the right</span>”</span> of the least significant field allowed by the
+ <em class="replaceable"><code>fields</code></em> specification are silently discarded. For
+ example, writing <code class="literal">INTERVAL '1 day 2:03:04' HOUR TO MINUTE</code>
+ results in dropping the seconds field, but not the day field.
+ </p><p>
+ According to the <acronym class="acronym">SQL</acronym> standard all fields of an interval
+ value must have the same sign, so a leading negative sign applies to all
+ fields; for example the negative sign in the interval literal
+ <code class="literal">'-1 2:03:04'</code> applies to both the days and hour/minute/second
+ parts. <span class="productname">PostgreSQL</span> allows the fields to have different
+ signs, and traditionally treats each field in the textual representation
+ as independently signed, so that the hour/minute/second part is
+ considered positive in this example. If <code class="varname">IntervalStyle</code> is
+ set to <code class="literal">sql_standard</code> then a leading sign is considered
+ to apply to all fields (but only if no additional signs appear).
+ Otherwise the traditional <span class="productname">PostgreSQL</span> interpretation is
+ used. To avoid ambiguity, it's recommended to attach an explicit sign
+ to each field if any field is negative.
+ </p><p>
+ Field values can have fractional parts: for example, <code class="literal">'1.5
+ weeks'</code> or <code class="literal">'01:02:03.45'</code>. However,
+ because interval internally stores only three integer units (months,
+ days, microseconds), fractional units must be spilled to smaller
+ units. Fractional parts of units greater than months are rounded to
+ be an integer number of months, e.g. <code class="literal">'1.5 years'</code>
+ becomes <code class="literal">'1 year 6 mons'</code>. Fractional parts of
+ weeks and days are computed to be an integer number of days and
+ microseconds, assuming 30 days per month and 24 hours per day, e.g.,
+ <code class="literal">'1.75 months'</code> becomes <code class="literal">1 mon 22 days
+ 12:00:00</code>. Only seconds will ever be shown as fractional
+ on output.
+ </p><p>
+ <a class="xref" href="datatype-datetime.html#DATATYPE-INTERVAL-INPUT-EXAMPLES" title="Table 8.17. Interval Input">Table 8.17</a> shows some examples
+ of valid <code class="type">interval</code> input.
+ </p><div class="table" id="DATATYPE-INTERVAL-INPUT-EXAMPLES"><p class="title"><strong>Table 8.17. Interval Input</strong></p><div class="table-contents"><table class="table" summary="Interval Input" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Example</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">1-2</code></td><td>SQL standard format: 1 year 2 months</td></tr><tr><td><code class="literal">3 4:05:06</code></td><td>SQL standard format: 3 days 4 hours 5 minutes 6 seconds</td></tr><tr><td><code class="literal">1 year 2 months 3 days 4 hours 5 minutes 6 seconds</code></td><td>Traditional Postgres format: 1 year 2 months 3 days 4 hours 5 minutes 6 seconds</td></tr><tr><td><code class="literal">P1Y2M3DT4H5M6S</code></td><td>ISO 8601 <span class="quote">“<span class="quote">format with designators</span>”</span>: same meaning as above</td></tr><tr><td><code class="literal">P0001-02-03T04:05:06</code></td><td>ISO 8601 <span class="quote">“<span class="quote">alternative format</span>”</span>: same meaning as above</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Internally <code class="type">interval</code> values are stored as months, days,
+ and microseconds. This is done because the number of days in a month
+ varies, and a day can have 23 or 25 hours if a daylight savings
+ time adjustment is involved. The months and days fields are integers
+ while the microseconds field can store fractional seconds. Because intervals are
+ usually created from constant strings or <code class="type">timestamp</code> subtraction,
+ this storage method works well in most cases, but can cause unexpected
+ results:
+
+</p><pre class="programlisting">
+SELECT EXTRACT(hours from '80 minutes'::interval);
+ date_part
+-----------
+ 1
+
+SELECT EXTRACT(days from '80 hours'::interval);
+ date_part
+-----------
+ 0
+</pre><p>
+
+ Functions <code class="function">justify_days</code> and
+ <code class="function">justify_hours</code> are available for adjusting days
+ and hours that overflow their normal ranges.
+ </p></div><div class="sect2" id="DATATYPE-INTERVAL-OUTPUT"><div class="titlepage"><div><div><h3 class="title">8.5.5. Interval Output</h3></div></div></div><a id="id-1.5.7.13.22.2" class="indexterm"></a><p>
+ The output format of the interval type can be set to one of the
+ four styles <code class="literal">sql_standard</code>, <code class="literal">postgres</code>,
+ <code class="literal">postgres_verbose</code>, or <code class="literal">iso_8601</code>,
+ using the command <code class="literal">SET intervalstyle</code>.
+ The default is the <code class="literal">postgres</code> format.
+ <a class="xref" href="datatype-datetime.html#INTERVAL-STYLE-OUTPUT-TABLE" title="Table 8.18. Interval Output Style Examples">Table 8.18</a> shows examples of each
+ output style.
+ </p><p>
+ The <code class="literal">sql_standard</code> style produces output that conforms to
+ the SQL standard's specification for interval literal strings, if
+ the interval value meets the standard's restrictions (either year-month
+ only or day-time only, with no mixing of positive
+ and negative components). Otherwise the output looks like a standard
+ year-month literal string followed by a day-time literal string,
+ with explicit signs added to disambiguate mixed-sign intervals.
+ </p><p>
+ The output of the <code class="literal">postgres</code> style matches the output of
+ <span class="productname">PostgreSQL</span> releases prior to 8.4 when the
+ <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a> parameter was set to <code class="literal">ISO</code>.
+ </p><p>
+ The output of the <code class="literal">postgres_verbose</code> style matches the output of
+ <span class="productname">PostgreSQL</span> releases prior to 8.4 when the
+ <code class="varname">DateStyle</code> parameter was set to non-<code class="literal">ISO</code> output.
+ </p><p>
+ The output of the <code class="literal">iso_8601</code> style matches the <span class="quote">“<span class="quote">format
+ with designators</span>”</span> described in section 4.4.3.2 of the
+ ISO 8601 standard.
+ </p><div class="table" id="INTERVAL-STYLE-OUTPUT-TABLE"><p class="title"><strong>Table 8.18. Interval Output Style Examples</strong></p><div class="table-contents"><table class="table" summary="Interval Output Style Examples" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Style Specification</th><th>Year-Month Interval</th><th>Day-Time Interval</th><th>Mixed Interval</th></tr></thead><tbody><tr><td><code class="literal">sql_standard</code></td><td>1-2</td><td>3 4:05:06</td><td>-1-2 +3 -4:05:06</td></tr><tr><td><code class="literal">postgres</code></td><td>1 year 2 mons</td><td>3 days 04:05:06</td><td>-1 year -2 mons +3 days -04:05:06</td></tr><tr><td><code class="literal">postgres_verbose</code></td><td>@ 1 year 2 mons</td><td>@ 3 days 4 hours 5 mins 6 secs</td><td>@ 1 year 2 mons -3 days 4 hours 5 mins 6 secs ago</td></tr><tr><td><code class="literal">iso_8601</code></td><td>P1Y2M</td><td>P3DT4H5M6S</td><td>P-1Y-2M3D​T-4H-5M-6S</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-binary.html" title="8.4. Binary Data Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-boolean.html" title="8.6. Boolean Type">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.4. Binary Data Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.6. Boolean Type</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-enum.html b/doc/src/sgml/html/datatype-enum.html
new file mode 100644
index 0000000..33952e9
--- /dev/null
+++ b/doc/src/sgml/html/datatype-enum.html
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.7. Enumerated Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-boolean.html" title="8.6. Boolean Type" /><link rel="next" href="datatype-geometric.html" title="8.8. Geometric Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.7. Enumerated Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-boolean.html" title="8.6. Boolean Type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-geometric.html" title="8.8. Geometric Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-ENUM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.7. Enumerated Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.5">8.7.1. Declaration of Enumerated Types</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.6">8.7.2. Ordering</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.7">8.7.3. Type Safety</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.8">8.7.4. Implementation Details</a></span></dt></dl></div><a id="id-1.5.7.15.2" class="indexterm"></a><a id="id-1.5.7.15.3" class="indexterm"></a><p>
+ Enumerated (enum) types are data types that
+ comprise a static, ordered set of values.
+ They are equivalent to the <code class="type">enum</code>
+ types supported in a number of programming languages. An example of an enum
+ type might be the days of the week, or a set of status values for
+ a piece of data.
+ </p><div class="sect2" id="id-1.5.7.15.5"><div class="titlepage"><div><div><h3 class="title">8.7.1. Declaration of Enumerated Types</h3></div></div></div><p>
+ Enum types are created using the <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> command,
+ for example:
+
+</p><pre class="programlisting">
+CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy');
+</pre><p>
+
+ Once created, the enum type can be used in table and function
+ definitions much like any other type:
+</p><pre class="programlisting">
+CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy');
+CREATE TABLE person (
+ name text,
+ current_mood mood
+);
+INSERT INTO person VALUES ('Moe', 'happy');
+SELECT * FROM person WHERE current_mood = 'happy';
+ name | current_mood
+------+--------------
+ Moe | happy
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.5.7.15.6"><div class="titlepage"><div><div><h3 class="title">8.7.2. Ordering</h3></div></div></div><p>
+ The ordering of the values in an enum type is the
+ order in which the values were listed when the type was created.
+ All standard comparison operators and related
+ aggregate functions are supported for enums. For example:
+
+</p><pre class="programlisting">
+INSERT INTO person VALUES ('Larry', 'sad');
+INSERT INTO person VALUES ('Curly', 'ok');
+SELECT * FROM person WHERE current_mood &gt; 'sad';
+ name | current_mood
+-------+--------------
+ Moe | happy
+ Curly | ok
+(2 rows)
+
+SELECT * FROM person WHERE current_mood &gt; 'sad' ORDER BY current_mood;
+ name | current_mood
+-------+--------------
+ Curly | ok
+ Moe | happy
+(2 rows)
+
+SELECT name
+FROM person
+WHERE current_mood = (SELECT MIN(current_mood) FROM person);
+ name
+-------
+ Larry
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.5.7.15.7"><div class="titlepage"><div><div><h3 class="title">8.7.3. Type Safety</h3></div></div></div><p>
+ Each enumerated data type is separate and cannot
+ be compared with other enumerated types. See this example:
+
+</p><pre class="programlisting">
+CREATE TYPE happiness AS ENUM ('happy', 'very happy', 'ecstatic');
+CREATE TABLE holidays (
+ num_weeks integer,
+ happiness happiness
+);
+INSERT INTO holidays(num_weeks,happiness) VALUES (4, 'happy');
+INSERT INTO holidays(num_weeks,happiness) VALUES (6, 'very happy');
+INSERT INTO holidays(num_weeks,happiness) VALUES (8, 'ecstatic');
+INSERT INTO holidays(num_weeks,happiness) VALUES (2, 'sad');
+ERROR: invalid input value for enum happiness: "sad"
+SELECT person.name, holidays.num_weeks FROM person, holidays
+ WHERE person.current_mood = holidays.happiness;
+ERROR: operator does not exist: mood = happiness
+</pre><p>
+ </p><p>
+ If you really need to do something like that, you can either
+ write a custom operator or add explicit casts to your query:
+
+</p><pre class="programlisting">
+SELECT person.name, holidays.num_weeks FROM person, holidays
+ WHERE person.current_mood::text = holidays.happiness::text;
+ name | num_weeks
+------+-----------
+ Moe | 4
+(1 row)
+
+</pre><p>
+ </p></div><div class="sect2" id="id-1.5.7.15.8"><div class="titlepage"><div><div><h3 class="title">8.7.4. Implementation Details</h3></div></div></div><p>
+ Enum labels are case sensitive, so
+ <code class="type">'happy'</code> is not the same as <code class="type">'HAPPY'</code>.
+ White space in the labels is significant too.
+ </p><p>
+ Although enum types are primarily intended for static sets of values,
+ there is support for adding new values to an existing enum type, and for
+ renaming values (see <a class="xref" href="sql-altertype.html" title="ALTER TYPE"><span class="refentrytitle">ALTER TYPE</span></a>). Existing values
+ cannot be removed from an enum type, nor can the sort ordering of such
+ values be changed, short of dropping and re-creating the enum type.
+ </p><p>
+ An enum value occupies four bytes on disk. The length of an enum
+ value's textual label is limited by the <code class="symbol">NAMEDATALEN</code>
+ setting compiled into <span class="productname">PostgreSQL</span>; in standard
+ builds this means at most 63 bytes.
+ </p><p>
+ The translations from internal enum values to textual labels are
+ kept in the system catalog
+ <a class="link" href="catalog-pg-enum.html" title="53.20. pg_enum"><code class="structname">pg_enum</code></a>.
+ Querying this catalog directly can be useful.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-boolean.html" title="8.6. Boolean Type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-geometric.html" title="8.8. Geometric Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.6. Boolean Type </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.8. Geometric Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-geometric.html b/doc/src/sgml/html/datatype-geometric.html
new file mode 100644
index 0000000..db70aa6
--- /dev/null
+++ b/doc/src/sgml/html/datatype-geometric.html
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.8. Geometric Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-enum.html" title="8.7. Enumerated Types" /><link rel="next" href="datatype-net-types.html" title="8.9. Network Address Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.8. Geometric Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-enum.html" title="8.7. Enumerated Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-net-types.html" title="8.9. Network Address Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-GEOMETRIC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.8. Geometric Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.5">8.8.1. Points</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-LINE">8.8.2. Lines</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-LSEG">8.8.3. Line Segments</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.8">8.8.4. Boxes</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.9">8.8.5. Paths</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-POLYGON">8.8.6. Polygons</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-CIRCLE">8.8.7. Circles</a></span></dt></dl></div><p>
+ Geometric data types represent two-dimensional spatial
+ objects. <a class="xref" href="datatype-geometric.html#DATATYPE-GEO-TABLE" title="Table 8.20. Geometric Types">Table 8.20</a> shows the geometric
+ types available in <span class="productname">PostgreSQL</span>.
+ </p><div class="table" id="DATATYPE-GEO-TABLE"><p class="title"><strong>Table 8.20. Geometric Types</strong></p><div class="table-contents"><table class="table" summary="Geometric Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th><th>Representation</th></tr></thead><tbody><tr><td><code class="type">point</code></td><td>16 bytes</td><td>Point on a plane</td><td>(x,y)</td></tr><tr><td><code class="type">line</code></td><td>32 bytes</td><td>Infinite line</td><td>{A,B,C}</td></tr><tr><td><code class="type">lseg</code></td><td>32 bytes</td><td>Finite line segment</td><td>((x1,y1),(x2,y2))</td></tr><tr><td><code class="type">box</code></td><td>32 bytes</td><td>Rectangular box</td><td>((x1,y1),(x2,y2))</td></tr><tr><td><code class="type">path</code></td><td>16+16n bytes</td><td>Closed path (similar to polygon)</td><td>((x1,y1),...)</td></tr><tr><td><code class="type">path</code></td><td>16+16n bytes</td><td>Open path</td><td>[(x1,y1),...]</td></tr><tr><td><code class="type">polygon</code></td><td>40+16n bytes</td><td>Polygon (similar to closed path)</td><td>((x1,y1),...)</td></tr><tr><td><code class="type">circle</code></td><td>24 bytes</td><td>Circle</td><td>&lt;(x,y),r&gt; (center point and radius)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ 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 <a class="xref" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Section 9.11</a>.
+ </p><div class="sect2" id="id-1.5.7.16.5"><div class="titlepage"><div><div><h3 class="title">8.8.1. Points</h3></div></div></div><a id="id-1.5.7.16.5.2" class="indexterm"></a><p>
+ Points are the fundamental two-dimensional building block for geometric
+ types. Values of type <code class="type">point</code> are specified using either of
+ the following syntaxes:
+
+</p><pre class="synopsis">
+( <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em> )
+ <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em>
+</pre><p>
+
+ where <em class="replaceable"><code>x</code></em> and <em class="replaceable"><code>y</code></em> are the respective
+ coordinates, as floating-point numbers.
+ </p><p>
+ Points are output using the first syntax.
+ </p></div><div class="sect2" id="DATATYPE-LINE"><div class="titlepage"><div><div><h3 class="title">8.8.2. Lines</h3></div></div></div><a id="id-1.5.7.16.6.2" class="indexterm"></a><p>
+ Lines are represented by the linear
+ equation <em class="replaceable"><code>A</code></em>x + <em class="replaceable"><code>B</code></em>y + <em class="replaceable"><code>C</code></em> = 0,
+ where <em class="replaceable"><code>A</code></em> and <em class="replaceable"><code>B</code></em> are not both zero. Values
+ of type <code class="type">line</code> are input and output in the following form:
+</p><pre class="synopsis">
+{ <em class="replaceable"><code>A</code></em>, <em class="replaceable"><code>B</code></em>, <em class="replaceable"><code>C</code></em> }
+</pre><p>
+
+ Alternatively, any of the following forms can be used for input:
+
+</p><pre class="synopsis">
+[ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> ) ]
+( ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> ) )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> )
+ <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em>
+</pre><p>
+
+ where
+ <code class="literal">(<em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em>)</code>
+ and
+ <code class="literal">(<em class="replaceable"><code>x2</code></em>,<em class="replaceable"><code>y2</code></em>)</code>
+ are two different points on the line.
+ </p></div><div class="sect2" id="DATATYPE-LSEG"><div class="titlepage"><div><div><h3 class="title">8.8.3. Line Segments</h3></div></div></div><a id="id-1.5.7.16.7.2" class="indexterm"></a><a id="id-1.5.7.16.7.3" class="indexterm"></a><p>
+ Line segments are represented by pairs of points that are the endpoints
+ of the segment. Values of type <code class="type">lseg</code> are specified using any
+ of the following syntaxes:
+
+</p><pre class="synopsis">
+[ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> ) ]
+( ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> ) )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> )
+ <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em>
+</pre><p>
+
+ where
+ <code class="literal">(<em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em>)</code>
+ and
+ <code class="literal">(<em class="replaceable"><code>x2</code></em>,<em class="replaceable"><code>y2</code></em>)</code>
+ are the end points of the line segment.
+ </p><p>
+ Line segments are output using the first syntax.
+ </p></div><div class="sect2" id="id-1.5.7.16.8"><div class="titlepage"><div><div><h3 class="title">8.8.4. Boxes</h3></div></div></div><a id="id-1.5.7.16.8.2" class="indexterm"></a><a id="id-1.5.7.16.8.3" class="indexterm"></a><p>
+ Boxes are represented by pairs of points that are opposite
+ corners of the box.
+ Values of type <code class="type">box</code> are specified using any of the following
+ syntaxes:
+
+</p><pre class="synopsis">
+( ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> ) )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ( <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em> )
+ <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , <em class="replaceable"><code>x2</code></em> , <em class="replaceable"><code>y2</code></em>
+</pre><p>
+
+ where
+ <code class="literal">(<em class="replaceable"><code>x1</code></em>,<em class="replaceable"><code>y1</code></em>)</code>
+ and
+ <code class="literal">(<em class="replaceable"><code>x2</code></em>,<em class="replaceable"><code>y2</code></em>)</code>
+ are any two opposite corners of the box.
+ </p><p>
+ Boxes are output using the second syntax.
+ </p><p>
+ Any two opposite corners can be supplied on input, but the values
+ will be reordered as needed to store the
+ upper right and lower left corners, in that order.
+ </p></div><div class="sect2" id="id-1.5.7.16.9"><div class="titlepage"><div><div><h3 class="title">8.8.5. Paths</h3></div></div></div><a id="id-1.5.7.16.9.2" class="indexterm"></a><p>
+ Paths are represented by lists of connected points. Paths can be
+ <em class="firstterm">open</em>, where
+ the first and last points in the list are considered not connected, or
+ <em class="firstterm">closed</em>,
+ where the first and last points are considered connected.
+ </p><p>
+ Values of type <code class="type">path</code> are specified using any of the following
+ syntaxes:
+
+</p><pre class="synopsis">
+[ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ... , ( <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> ) ]
+( ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ... , ( <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> ) )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ... , ( <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , ... , <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> )
+ <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , ... , <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em>
+</pre><p>
+
+ where the points are the end points of the line segments
+ comprising the path. Square brackets (<code class="literal">[]</code>) indicate
+ an open path, while parentheses (<code class="literal">()</code>) indicate a
+ closed path. When the outermost parentheses are omitted, as
+ in the third through fifth syntaxes, a closed path is assumed.
+ </p><p>
+ Paths are output using the first or second syntax, as appropriate.
+ </p></div><div class="sect2" id="DATATYPE-POLYGON"><div class="titlepage"><div><div><h3 class="title">8.8.6. Polygons</h3></div></div></div><a id="id-1.5.7.16.10.2" class="indexterm"></a><p>
+ Polygons are represented by lists of points (the vertexes of the
+ polygon). Polygons are very similar to closed paths; the essential
+ difference is that a polygon is considered to include the area
+ within it, while a path is not.
+ </p><p>
+ Values of type <code class="type">polygon</code> are specified using any of the
+ following syntaxes:
+
+</p><pre class="synopsis">
+( ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ... , ( <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> ) )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> ) , ... , ( <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> )
+ ( <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , ... , <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em> )
+ <em class="replaceable"><code>x1</code></em> , <em class="replaceable"><code>y1</code></em> , ... , <em class="replaceable"><code>xn</code></em> , <em class="replaceable"><code>yn</code></em>
+</pre><p>
+
+ where the points are the end points of the line segments
+ comprising the boundary of the polygon.
+ </p><p>
+ Polygons are output using the first syntax.
+ </p></div><div class="sect2" id="DATATYPE-CIRCLE"><div class="titlepage"><div><div><h3 class="title">8.8.7. Circles</h3></div></div></div><a id="id-1.5.7.16.11.2" class="indexterm"></a><p>
+ Circles are represented by a center point and radius.
+ Values of type <code class="type">circle</code> are specified using any of the
+ following syntaxes:
+
+</p><pre class="synopsis">
+&lt; ( <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em> ) , <em class="replaceable"><code>r</code></em> &gt;
+( ( <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em> ) , <em class="replaceable"><code>r</code></em> )
+ ( <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em> ) , <em class="replaceable"><code>r</code></em>
+ <em class="replaceable"><code>x</code></em> , <em class="replaceable"><code>y</code></em> , <em class="replaceable"><code>r</code></em>
+</pre><p>
+
+ where
+ <code class="literal">(<em class="replaceable"><code>x</code></em>,<em class="replaceable"><code>y</code></em>)</code>
+ is the center point and <em class="replaceable"><code>r</code></em> is the radius of the
+ circle.
+ </p><p>
+ Circles are output using the first syntax.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-enum.html" title="8.7. Enumerated Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-net-types.html" title="8.9. Network Address Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.7. Enumerated Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.9. Network Address Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-json.html b/doc/src/sgml/html/datatype-json.html
new file mode 100644
index 0000000..2fb1553
--- /dev/null
+++ b/doc/src/sgml/html/datatype-json.html
@@ -0,0 +1,730 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.14. JSON Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-xml.html" title="8.13. XML Type" /><link rel="next" href="arrays.html" title="8.15. Arrays" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.14. <acronym class="acronym">JSON</acronym> Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-xml.html" title="8.13. XML Type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="arrays.html" title="8.15. Arrays">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-JSON"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.14. <acronym class="acronym">JSON</acronym> Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-json.html#JSON-KEYS-ELEMENTS">8.14.1. JSON Input and Output Syntax</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-DOC-DESIGN">8.14.2. Designing JSON Documents</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-CONTAINMENT">8.14.3. <code class="type">jsonb</code> Containment and Existence</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-INDEXING">8.14.4. <code class="type">jsonb</code> Indexing</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSONB-SUBSCRIPTING">8.14.5. <code class="type">jsonb</code> Subscripting</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#id-1.5.7.22.20">8.14.6. Transforms</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#DATATYPE-JSONPATH">8.14.7. jsonpath Type</a></span></dt></dl></div><a id="id-1.5.7.22.2" class="indexterm"></a><a id="id-1.5.7.22.3" class="indexterm"></a><p>
+ JSON data types are for storing JSON (JavaScript Object Notation)
+ data, as specified in <a class="ulink" href="https://tools.ietf.org/html/rfc7159" target="_top">RFC
+ 7159</a>. Such data can also be stored as <code class="type">text</code>, but
+ 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 <a class="xref" href="functions-json.html" title="9.16. JSON Functions and Operators">Section 9.16</a>.
+ </p><p>
+ <span class="productname">PostgreSQL</span> offers two types for storing JSON
+ data: <code class="type">json</code> and <code class="type">jsonb</code>. To implement efficient query
+ mechanisms for these data types, <span class="productname">PostgreSQL</span>
+ also provides the <code class="type">jsonpath</code> data type described in
+ <a class="xref" href="datatype-json.html#DATATYPE-JSONPATH" title="8.14.7. jsonpath Type">Section 8.14.7</a>.
+ </p><p>
+ The <code class="type">json</code> and <code class="type">jsonb</code> data types
+ accept <span class="emphasis"><em>almost</em></span> identical sets of values as
+ input. The major practical difference is one of efficiency. The
+ <code class="type">json</code> data type stores an exact copy of the input text,
+ which processing functions must reparse on each execution; while
+ <code class="type">jsonb</code> data is stored in a decomposed binary format that
+ makes it slightly slower to input due to added conversion
+ overhead, but significantly faster to process, since no reparsing
+ is needed. <code class="type">jsonb</code> also supports indexing, which can be a
+ significant advantage.
+ </p><p>
+ Because the <code class="type">json</code> type stores an exact copy of the input text, it
+ will preserve semantically-insignificant white space between tokens, as
+ well as the order of keys within JSON objects. Also, if a JSON object
+ within the value contains the same key more than once, all the key/value
+ pairs are kept. (The processing functions consider the last value as the
+ operative one.) By contrast, <code class="type">jsonb</code> does not preserve white
+ space, does not preserve the order of object keys, and does not keep
+ duplicate object keys. If duplicate keys are specified in the input,
+ only the last value is kept.
+ </p><p>
+ In general, most applications should prefer to store JSON data as
+ <code class="type">jsonb</code>, unless there are quite specialized needs, such as
+ legacy assumptions about ordering of object keys.
+ </p><p>
+ <acronym class="acronym">RFC</acronym> 7159 specifies that JSON strings should be encoded in UTF8.
+ It is therefore not possible for the JSON
+ types to conform rigidly to the JSON specification unless the database
+ encoding is UTF8. Attempts to directly include characters that
+ cannot be represented in the database encoding will fail; conversely,
+ characters that can be represented in the database encoding but not
+ in UTF8 will be allowed.
+ </p><p>
+ <acronym class="acronym">RFC</acronym> 7159 permits JSON strings to contain Unicode escape sequences
+ denoted by <code class="literal">\u<em class="replaceable"><code>XXXX</code></em></code>. In the input
+ function for the <code class="type">json</code> type, Unicode escapes are allowed
+ regardless of the database encoding, and are checked only for syntactic
+ correctness (that is, that four hex digits follow <code class="literal">\u</code>).
+ However, the input function for <code class="type">jsonb</code> is stricter: it disallows
+ Unicode escapes for characters that cannot be represented in the database
+ encoding. The <code class="type">jsonb</code> type also
+ rejects <code class="literal">\u0000</code> (because that cannot be represented in
+ <span class="productname">PostgreSQL</span>'s <code class="type">text</code> type), and it insists
+ that any use of Unicode surrogate pairs to designate characters outside
+ the Unicode Basic Multilingual Plane be correct. Valid Unicode escapes
+ are converted to the equivalent single character for storage;
+ this includes folding surrogate pairs into a single character.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Many of the JSON processing functions described
+ in <a class="xref" href="functions-json.html" title="9.16. JSON Functions and Operators">Section 9.16</a> 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 <code class="type">json</code>
+ not <code class="type">jsonb</code>. The fact that the <code class="type">json</code> input function does
+ not make these checks may be considered a historical artifact, although
+ it does allow for simple storage (without processing) of JSON Unicode
+ escapes in a database encoding that does not support the represented
+ characters.
+ </p></div><p>
+ When converting textual JSON input into <code class="type">jsonb</code>, the primitive
+ types described by <acronym class="acronym">RFC</acronym> 7159 are effectively mapped onto
+ native <span class="productname">PostgreSQL</span> types, as shown
+ in <a class="xref" href="datatype-json.html#JSON-TYPE-MAPPING-TABLE" title="Table 8.23. JSON Primitive Types and Corresponding PostgreSQL Types">Table 8.23</a>.
+ Therefore, there are some minor additional constraints on what
+ constitutes valid <code class="type">jsonb</code> data that do not apply to
+ the <code class="type">json</code> type, nor to JSON in the abstract, corresponding
+ to limits on what can be represented by the underlying data type.
+ Notably, <code class="type">jsonb</code> will reject numbers that are outside the
+ range of the <span class="productname">PostgreSQL</span> <code class="type">numeric</code> data
+ type, while <code class="type">json</code> will not. Such implementation-defined
+ restrictions are permitted by <acronym class="acronym">RFC</acronym> 7159. However, in
+ practice such problems are far more likely to occur in other
+ implementations, as it is common to represent JSON's <code class="type">number</code>
+ primitive type as IEEE 754 double precision floating point
+ (which <acronym class="acronym">RFC</acronym> 7159 explicitly anticipates and allows for).
+ When using JSON as an interchange format with such systems, the danger
+ of losing numeric precision compared to data originally stored
+ by <span class="productname">PostgreSQL</span> should be considered.
+ </p><p>
+ Conversely, as noted in the table there are some minor restrictions on
+ the input format of JSON primitive types that do not apply to
+ the corresponding <span class="productname">PostgreSQL</span> types.
+ </p><div class="table" id="JSON-TYPE-MAPPING-TABLE"><p class="title"><strong>Table 8.23. JSON Primitive Types and Corresponding <span class="productname">PostgreSQL</span> Types</strong></p><div class="table-contents"><table class="table" summary="JSON Primitive Types and Corresponding PostgreSQL Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>JSON primitive type</th><th><span class="productname">PostgreSQL</span> type</th><th>Notes</th></tr></thead><tbody><tr><td><code class="type">string</code></td><td><code class="type">text</code></td><td><code class="literal">\u0000</code> is disallowed, as are Unicode escapes
+ representing characters not available in the database encoding</td></tr><tr><td><code class="type">number</code></td><td><code class="type">numeric</code></td><td><code class="literal">NaN</code> and <code class="literal">infinity</code> values are disallowed</td></tr><tr><td><code class="type">boolean</code></td><td><code class="type">boolean</code></td><td>Only lowercase <code class="literal">true</code> and <code class="literal">false</code> spellings are accepted</td></tr><tr><td><code class="type">null</code></td><td>(none)</td><td>SQL <code class="literal">NULL</code> is a different concept</td></tr></tbody></table></div></div><br class="table-break" /><div class="sect2" id="JSON-KEYS-ELEMENTS"><div class="titlepage"><div><div><h3 class="title">8.14.1. JSON Input and Output Syntax</h3></div></div></div><p>
+ The input/output syntax for the JSON data types is as specified in
+ <acronym class="acronym">RFC</acronym> 7159.
+ </p><p>
+ The following are all valid <code class="type">json</code> (or <code class="type">jsonb</code>) expressions:
+</p><pre class="programlisting">
+-- Simple scalar/primitive value
+-- Primitive values can be numbers, quoted strings, true, false, or null
+SELECT '5'::json;
+
+-- Array of zero or more elements (elements need not be of same type)
+SELECT '[1, 2, "foo", null]'::json;
+
+-- Object containing pairs of keys and values
+-- Note that object keys must always be quoted strings
+SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json;
+
+-- Arrays and objects can be nested arbitrarily
+SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json;
+</pre><p>
+ </p><p>
+ As previously stated, when a JSON value is input and then printed without
+ any additional processing, <code class="type">json</code> outputs the same text that was
+ input, while <code class="type">jsonb</code> does not preserve semantically-insignificant
+ details such as whitespace. For example, note the differences here:
+</p><pre class="programlisting">
+SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::json;
+ json
+-------------------------------------------------
+ {"bar": "baz", "balance": 7.77, "active":false}
+(1 row)
+
+SELECT '{"bar": "baz", "balance": 7.77, "active":false}'::jsonb;
+ jsonb
+--------------------------------------------------
+ {"bar": "baz", "active": false, "balance": 7.77}
+(1 row)
+</pre><p>
+ One semantically-insignificant detail worth noting is that
+ in <code class="type">jsonb</code>, numbers will be printed according to the behavior of the
+ underlying <code class="type">numeric</code> type. In practice this means that numbers
+ entered with <code class="literal">E</code> notation will be printed without it, for
+ example:
+</p><pre class="programlisting">
+SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb;
+ json | jsonb
+-----------------------+-------------------------
+ {"reading": 1.230e-5} | {"reading": 0.00001230}
+(1 row)
+</pre><p>
+ However, <code class="type">jsonb</code> will preserve trailing fractional zeroes, as seen
+ in this example, even though those are semantically insignificant for
+ purposes such as equality checks.
+ </p><p>
+ For the list of built-in functions and operators available for
+ constructing and processing JSON values, see <a class="xref" href="functions-json.html" title="9.16. JSON Functions and Operators">Section 9.16</a>.
+ </p></div><div class="sect2" id="JSON-DOC-DESIGN"><div class="titlepage"><div><div><h3 class="title">8.14.2. Designing JSON Documents</h3></div></div></div><p>
+ Representing data as JSON can be considerably more flexible than
+ the traditional relational data model, which is compelling in
+ environments where requirements are fluid. It is quite possible
+ for both approaches to co-exist and complement each other within
+ the same application. However, even for applications where maximal
+ flexibility is desired, it is still recommended that JSON documents
+ have a somewhat fixed structure. The structure is typically
+ unenforced (though enforcing some business rules declaratively is
+ possible), but having a predictable structure makes it easier to write
+ queries that usefully summarize a set of <span class="quote">“<span class="quote">documents</span>”</span> (datums)
+ in a table.
+ </p><p>
+ JSON data is subject to the same concurrency-control
+ considerations as any other data type when stored in a table.
+ Although storing large documents is practicable, keep in mind that
+ any update acquires a row-level lock on the whole row.
+ Consider limiting JSON documents to a
+ manageable size in order to decrease lock contention among updating
+ transactions. Ideally, JSON documents should each
+ represent an atomic datum that business rules dictate cannot
+ reasonably be further subdivided into smaller datums that
+ could be modified independently.
+ </p></div><div class="sect2" id="JSON-CONTAINMENT"><div class="titlepage"><div><div><h3 class="title">8.14.3. <code class="type">jsonb</code> Containment and Existence</h3></div></div></div><a id="id-1.5.7.22.17.2" class="indexterm"></a><a id="id-1.5.7.22.17.3" class="indexterm"></a><p>
+ Testing <em class="firstterm">containment</em> is an important capability of
+ <code class="type">jsonb</code>. There is no parallel set of facilities for the
+ <code class="type">json</code> type. Containment tests whether
+ one <code class="type">jsonb</code> document has contained within it another one.
+ These examples return true except as noted:
+ </p><pre class="programlisting">
+-- Simple scalar/primitive values contain only the identical value:
+SELECT '"foo"'::jsonb @&gt; '"foo"'::jsonb;
+
+-- The array on the right side is contained within the one on the left:
+SELECT '[1, 2, 3]'::jsonb @&gt; '[1, 3]'::jsonb;
+
+-- Order of array elements is not significant, so this is also true:
+SELECT '[1, 2, 3]'::jsonb @&gt; '[3, 1]'::jsonb;
+
+-- Duplicate array elements don't matter either:
+SELECT '[1, 2, 3]'::jsonb @&gt; '[1, 2, 2]'::jsonb;
+
+-- The object with a single pair on the right side is contained
+-- within the object on the left side:
+SELECT '{"product": "PostgreSQL", "version": 9.4, "jsonb": true}'::jsonb @&gt; '{"version": 9.4}'::jsonb;
+
+-- The array on the right side is <span class="emphasis"><strong>not</strong></span> considered contained within the
+-- array on the left, even though a similar array is nested within it:
+SELECT '[1, 2, [1, 3]]'::jsonb @&gt; '[1, 3]'::jsonb; -- yields false
+
+-- But with a layer of nesting, it is contained:
+SELECT '[1, 2, [1, 3]]'::jsonb @&gt; '[[1, 3]]'::jsonb;
+
+-- Similarly, containment is not reported here:
+SELECT '{"foo": {"bar": "baz"}}'::jsonb @&gt; '{"bar": "baz"}'::jsonb; -- yields false
+
+-- A top-level key and an empty object is contained:
+SELECT '{"foo": {"bar": "baz"}}'::jsonb @&gt; '{"foo": {}}'::jsonb;
+</pre><p>
+ The general principle is that the contained object must match the
+ containing object as to structure and data contents, possibly after
+ discarding some non-matching array elements or object key/value pairs
+ from the containing object.
+ But remember that the order of array elements is not significant when
+ doing a containment match, and duplicate array elements are effectively
+ considered only once.
+ </p><p>
+ As a special exception to the general principle that the structures
+ must match, an array may contain a primitive value:
+ </p><pre class="programlisting">
+-- This array contains the primitive string value:
+SELECT '["foo", "bar"]'::jsonb @&gt; '"bar"'::jsonb;
+
+-- This exception is not reciprocal -- non-containment is reported here:
+SELECT '"bar"'::jsonb @&gt; '["bar"]'::jsonb; -- yields false
+</pre><p>
+ <code class="type">jsonb</code> also has an <em class="firstterm">existence</em> operator, which is
+ a variation on the theme of containment: it tests whether a string
+ (given as a <code class="type">text</code> value) appears as an object key or array
+ element at the top level of the <code class="type">jsonb</code> value.
+ These examples return true except as noted:
+ </p><pre class="programlisting">
+-- String exists as array element:
+SELECT '["foo", "bar", "baz"]'::jsonb ? 'bar';
+
+-- String exists as object key:
+SELECT '{"foo": "bar"}'::jsonb ? 'foo';
+
+-- Object values are not considered:
+SELECT '{"foo": "bar"}'::jsonb ? 'bar'; -- yields false
+
+-- As with containment, existence must match at the top level:
+SELECT '{"foo": {"bar": "baz"}}'::jsonb ? 'bar'; -- yields false
+
+-- A string is considered to exist if it matches a primitive JSON string:
+SELECT '"foo"'::jsonb ? 'foo';
+</pre><p>
+ JSON objects are better suited than arrays for testing containment or
+ existence when there are many keys or elements involved, because
+ unlike arrays they are internally optimized for searching, and do not
+ need to be searched linearly.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Because JSON containment is nested, an appropriate query can skip
+ explicit selection of sub-objects. As an example, suppose that we have
+ a <code class="structfield">doc</code> column containing objects at the top level, with
+ most objects containing <code class="literal">tags</code> fields that contain arrays of
+ sub-objects. This query finds entries in which sub-objects containing
+ both <code class="literal">"term":"paris"</code> and <code class="literal">"term":"food"</code> appear,
+ while ignoring any such keys outside the <code class="literal">tags</code> array:
+</p><pre class="programlisting">
+SELECT doc-&gt;'site_name' FROM websites
+ WHERE doc @&gt; '{"tags":[{"term":"paris"}, {"term":"food"}]}';
+</pre><p>
+ One could accomplish the same thing with, say,
+</p><pre class="programlisting">
+SELECT doc-&gt;'site_name' FROM websites
+ WHERE doc-&gt;'tags' @&gt; '[{"term":"paris"}, {"term":"food"}]';
+</pre><p>
+ but that approach is less flexible, and often less efficient as well.
+ </p><p>
+ On the other hand, the JSON existence operator is not nested: it will
+ only look for the specified key or array element at top level of the
+ JSON value.
+ </p></div><p>
+ The various containment and existence operators, along with all other
+ JSON operators and functions are documented
+ in <a class="xref" href="functions-json.html" title="9.16. JSON Functions and Operators">Section 9.16</a>.
+ </p></div><div class="sect2" id="JSON-INDEXING"><div class="titlepage"><div><div><h3 class="title">8.14.4. <code class="type">jsonb</code> Indexing</h3></div></div></div><a id="id-1.5.7.22.18.2" class="indexterm"></a><p>
+ GIN indexes can be used to efficiently search for
+ keys or key/value pairs occurring within a large number of
+ <code class="type">jsonb</code> documents (datums).
+ Two GIN <span class="quote">“<span class="quote">operator classes</span>”</span> are provided, offering different
+ performance and flexibility trade-offs.
+ </p><p>
+ The default GIN operator class for <code class="type">jsonb</code> supports queries with
+ the key-exists operators <code class="literal">?</code>, <code class="literal">?|</code>
+ and <code class="literal">?&amp;</code>, the containment operator
+ <code class="literal">@&gt;</code>, and the <code class="type">jsonpath</code> match
+ operators <code class="literal">@?</code> and <code class="literal">@@</code>.
+ (For details of the semantics that these operators
+ implement, see <a class="xref" href="functions-json.html#FUNCTIONS-JSONB-OP-TABLE" title="Table 9.46. Additional jsonb Operators">Table 9.46</a>.)
+ An example of creating an index with this operator class is:
+</p><pre class="programlisting">
+CREATE INDEX idxgin ON api USING GIN (jdoc);
+</pre><p>
+ The non-default GIN operator class <code class="literal">jsonb_path_ops</code>
+ does not support the key-exists operators, but it does support
+ <code class="literal">@&gt;</code>, <code class="literal">@?</code> and <code class="literal">@@</code>.
+ An example of creating an index with this operator class is:
+</p><pre class="programlisting">
+CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops);
+</pre><p>
+ </p><p>
+ Consider the example of a table that stores JSON documents
+ retrieved from a third-party web service, with a documented schema
+ definition. A typical document is:
+</p><pre class="programlisting">
+{
+ "guid": "9c36adc1-7fb5-4d5b-83b4-90356a46061a",
+ "name": "Angela Barton",
+ "is_active": true,
+ "company": "Magnafone",
+ "address": "178 Howard Place, Gulf, Washington, 702",
+ "registered": "2009-11-07T08:53:22 +08:00",
+ "latitude": 19.793713,
+ "longitude": 86.513373,
+ "tags": [
+ "enim",
+ "aliquip",
+ "qui"
+ ]
+}
+</pre><p>
+ We store these documents in a table named <code class="structname">api</code>,
+ in a <code class="type">jsonb</code> column named <code class="structfield">jdoc</code>.
+ If a GIN index is created on this column,
+ queries like the following can make use of the index:
+</p><pre class="programlisting">
+-- Find documents in which the key "company" has value "Magnafone"
+SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"company": "Magnafone"}';
+</pre><p>
+ However, the index could not be used for queries like the
+ following, because though the operator <code class="literal">?</code> is indexable,
+ it is not applied directly to the indexed column <code class="structfield">jdoc</code>:
+</p><pre class="programlisting">
+-- Find documents in which the key "tags" contains key or array element "qui"
+SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc -&gt; 'tags' ? 'qui';
+</pre><p>
+ Still, with appropriate use of expression indexes, the above
+ query can use an index. If querying for particular items within
+ the <code class="literal">"tags"</code> key is common, defining an index like this
+ may be worthwhile:
+</p><pre class="programlisting">
+CREATE INDEX idxgintags ON api USING GIN ((jdoc -&gt; 'tags'));
+</pre><p>
+ Now, the <code class="literal">WHERE</code> clause <code class="literal">jdoc -&gt; 'tags' ? 'qui'</code>
+ will be recognized as an application of the indexable
+ operator <code class="literal">?</code> to the indexed
+ expression <code class="literal">jdoc -&gt; 'tags'</code>.
+ (More information on expression indexes can be found in <a class="xref" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Section 11.7</a>.)
+ </p><p>
+ Another approach to querying is to exploit containment, for example:
+</p><pre class="programlisting">
+-- Find documents in which the key "tags" contains array element "qui"
+SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"tags": ["qui"]}';
+</pre><p>
+ A simple GIN index on the <code class="structfield">jdoc</code> column can support this
+ query. But note that such an index will store copies of every key and
+ value in the <code class="structfield">jdoc</code> column, whereas the expression index
+ of the previous example stores only data found under
+ the <code class="literal">tags</code> key. While the simple-index approach is far more
+ flexible (since it supports queries about any key), targeted expression
+ indexes are likely to be smaller and faster to search than a simple
+ index.
+ </p><p>
+ GIN indexes also support the <code class="literal">@?</code>
+ and <code class="literal">@@</code> operators, which
+ perform <code class="type">jsonpath</code> matching. Examples are
+</p><pre class="programlisting">
+SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")';
+</pre><p>
+</p><pre class="programlisting">
+SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
+</pre><p>
+ For these operators, a GIN index extracts clauses of the form
+ <code class="literal"><em class="replaceable"><code>accessors_chain</code></em>
+ = <em class="replaceable"><code>constant</code></em></code> out of
+ the <code class="type">jsonpath</code> pattern, and does the index search based on
+ the keys and values mentioned in these clauses. The accessors chain
+ may include <code class="literal">.<em class="replaceable"><code>key</code></em></code>,
+ <code class="literal">[*]</code>,
+ and <code class="literal">[<em class="replaceable"><code>index</code></em>]</code> accessors.
+ The <code class="literal">jsonb_ops</code> operator class also
+ supports <code class="literal">.*</code> and <code class="literal">.**</code> accessors,
+ but the <code class="literal">jsonb_path_ops</code> operator class does not.
+ </p><p>
+ Although the <code class="literal">jsonb_path_ops</code> operator class supports
+ only queries with the <code class="literal">@&gt;</code>, <code class="literal">@?</code>
+ and <code class="literal">@@</code> operators, it has notable
+ performance advantages over the default operator
+ class <code class="literal">jsonb_ops</code>. A <code class="literal">jsonb_path_ops</code>
+ index is usually much smaller than a <code class="literal">jsonb_ops</code>
+ index over the same data, and the specificity of searches is better,
+ particularly when queries contain keys that appear frequently in the
+ data. Therefore search operations typically perform better
+ than with the default operator class.
+ </p><p>
+ The technical difference between a <code class="literal">jsonb_ops</code>
+ and a <code class="literal">jsonb_path_ops</code> GIN index is that the former
+ creates independent index items for each key and value in the data,
+ while the latter creates index items only for each value in the
+ data.
+ <a href="#ftn.id-1.5.7.22.18.9.3" class="footnote"><sup class="footnote" id="id-1.5.7.22.18.9.3">[7]</sup></a>
+ Basically, each <code class="literal">jsonb_path_ops</code> index item is
+ a hash of the value and the key(s) leading to it; for example to index
+ <code class="literal">{"foo": {"bar": "baz"}}</code>, a single index item would
+ be created incorporating all three of <code class="literal">foo</code>, <code class="literal">bar</code>,
+ and <code class="literal">baz</code> into the hash value. Thus a containment query
+ looking for this structure would result in an extremely specific index
+ search; but there is no way at all to find out whether <code class="literal">foo</code>
+ appears as a key. On the other hand, a <code class="literal">jsonb_ops</code>
+ index would create three index items representing <code class="literal">foo</code>,
+ <code class="literal">bar</code>, and <code class="literal">baz</code> separately; then to do the
+ containment query, it would look for rows containing all three of
+ these items. While GIN indexes can perform such an AND search fairly
+ efficiently, it will still be less specific and slower than the
+ equivalent <code class="literal">jsonb_path_ops</code> search, especially if
+ there are a very large number of rows containing any single one of the
+ three index items.
+ </p><p>
+ A disadvantage of the <code class="literal">jsonb_path_ops</code> approach is
+ that it produces no index entries for JSON structures not containing
+ any values, such as <code class="literal">{"a": {}}</code>. If a search for
+ documents containing such a structure is requested, it will require a
+ full-index scan, which is quite slow. <code class="literal">jsonb_path_ops</code> is
+ therefore ill-suited for applications that often perform such searches.
+ </p><p>
+ <code class="type">jsonb</code> also supports <code class="literal">btree</code> and <code class="literal">hash</code>
+ indexes. These are usually useful only if it's important to check
+ equality of complete JSON documents.
+ The <code class="literal">btree</code> ordering for <code class="type">jsonb</code> datums is seldom
+ of great interest, but for completeness it is:
+</p><pre class="synopsis">
+<em class="replaceable"><code>Object</code></em> &gt; <em class="replaceable"><code>Array</code></em> &gt; <em class="replaceable"><code>Boolean</code></em> &gt; <em class="replaceable"><code>Number</code></em> &gt; <em class="replaceable"><code>String</code></em> &gt; <em class="replaceable"><code>Null</code></em>
+
+<em class="replaceable"><code>Object with n pairs</code></em> &gt; <em class="replaceable"><code>object with n - 1 pairs</code></em>
+
+<em class="replaceable"><code>Array with n elements</code></em> &gt; <em class="replaceable"><code>array with n - 1 elements</code></em>
+</pre><p>
+ Objects with equal numbers of pairs are compared in the order:
+</p><pre class="synopsis">
+<em class="replaceable"><code>key-1</code></em>, <em class="replaceable"><code>value-1</code></em>, <em class="replaceable"><code>key-2</code></em> ...
+</pre><p>
+ Note that object keys are compared in their storage order;
+ in particular, since shorter keys are stored before longer keys, this
+ can lead to results that might be unintuitive, such as:
+</p><pre class="programlisting">
+{ "aa": 1, "c": 1} &gt; {"b": 1, "d": 1}
+</pre><p>
+ Similarly, arrays with equal numbers of elements are compared in the
+ order:
+</p><pre class="synopsis">
+<em class="replaceable"><code>element-1</code></em>, <em class="replaceable"><code>element-2</code></em> ...
+</pre><p>
+ Primitive JSON values are compared using the same
+ comparison rules as for the underlying
+ <span class="productname">PostgreSQL</span> data type. Strings are
+ compared using the default database collation.
+ </p></div><div class="sect2" id="JSONB-SUBSCRIPTING"><div class="titlepage"><div><div><h3 class="title">8.14.5. <code class="type">jsonb</code> Subscripting</h3></div></div></div><p>
+ The <code class="type">jsonb</code> data type supports array-style subscripting expressions
+ to extract and modify elements. Nested values can be indicated by chaining
+ subscripting expressions, following the same rules as the <code class="literal">path</code>
+ argument in the <code class="literal">jsonb_set</code> function. If a <code class="type">jsonb</code>
+ value is an array, numeric subscripts start at zero, and negative integers count
+ backwards from the last element of the array. Slice expressions are not supported.
+ The result of a subscripting expression is always of the jsonb data type.
+ </p><p>
+ <code class="command">UPDATE</code> statements may use subscripting in the
+ <code class="literal">SET</code> clause to modify <code class="type">jsonb</code> values. Subscript
+ paths must be traversable for all affected values insofar as they exist. For
+ instance, the path <code class="literal">val['a']['b']['c']</code> can be traversed all
+ the way to <code class="literal">c</code> if every <code class="literal">val</code>,
+ <code class="literal">val['a']</code>, and <code class="literal">val['a']['b']</code> is an
+ object. If any <code class="literal">val['a']</code> or <code class="literal">val['a']['b']</code>
+ is not defined, it will be created as an empty object and filled as
+ necessary. However, if any <code class="literal">val</code> itself or one of the
+ intermediary values is defined as a non-object such as a string, number, or
+ <code class="literal">jsonb</code> <code class="literal">null</code>, traversal cannot proceed so
+ an error is raised and the transaction aborted.
+ </p><p>
+ An example of subscripting syntax:
+
+</p><pre class="programlisting">
+
+-- Extract object value by key
+SELECT ('{"a": 1}'::jsonb)['a'];
+
+-- Extract nested object value by key path
+SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c'];
+
+-- Extract array element by index
+SELECT ('[1, "2", null]'::jsonb)[1];
+
+-- Update object value by key. Note the quotes around '1': the assigned
+-- value must be of the jsonb type as well
+UPDATE table_name SET jsonb_field['key'] = '1';
+
+-- This will raise an error if any record's jsonb_field['a']['b'] is something
+-- other than an object. For example, the value {"a": 1} has a numeric value
+-- of the key 'a'.
+UPDATE table_name SET jsonb_field['a']['b']['c'] = '1';
+
+-- Filter records using a WHERE clause with subscripting. Since the result of
+-- subscripting is jsonb, the value we compare it against must also be jsonb.
+-- The double quotes make "value" also a valid jsonb string.
+SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"';
+</pre><p>
+
+ <code class="type">jsonb</code> assignment via subscripting handles a few edge cases
+ differently from <code class="literal">jsonb_set</code>. When a source <code class="type">jsonb</code>
+ value is <code class="literal">NULL</code>, assignment via subscripting will proceed
+ as if it was an empty JSON value of the type (object or array) implied by the
+ subscript key:
+
+</p><pre class="programlisting">
+-- Where jsonb_field was NULL, it is now {"a": 1}
+UPDATE table_name SET jsonb_field['a'] = '1';
+
+-- Where jsonb_field was NULL, it is now [1]
+UPDATE table_name SET jsonb_field[0] = '1';
+</pre><p>
+
+ If an index is specified for an array containing too few elements,
+ <code class="literal">NULL</code> elements will be appended until the index is reachable
+ and the value can be set.
+
+</p><pre class="programlisting">
+-- Where jsonb_field was [], it is now [null, null, 2];
+-- where jsonb_field was [0], it is now [0, null, 2]
+UPDATE table_name SET jsonb_field[2] = '2';
+</pre><p>
+
+ A <code class="type">jsonb</code> value will accept assignments to nonexistent subscript
+ paths as long as the last existing element to be traversed is an object or
+ array, as implied by the corresponding subscript (the element indicated by
+ the last subscript in the path is not traversed and may be anything). Nested
+ array and object structures will be created, and in the former case
+ <code class="literal">null</code>-padded, as specified by the subscript path until the
+ assigned value can be placed.
+
+</p><pre class="programlisting">
+-- Where jsonb_field was {}, it is now {"a": [{"b": 1}]}
+UPDATE table_name SET jsonb_field['a'][0]['b'] = '1';
+
+-- Where jsonb_field was [], it is now [null, {"a": 1}]
+UPDATE table_name SET jsonb_field[1]['a'] = '1';
+</pre><p>
+
+ </p></div><div class="sect2" id="id-1.5.7.22.20"><div class="titlepage"><div><div><h3 class="title">8.14.6. Transforms</h3></div></div></div><p>
+ Additional extensions are available that implement transforms for the
+ <code class="type">jsonb</code> type for different procedural languages.
+ </p><p>
+ The extensions for PL/Perl are called <code class="literal">jsonb_plperl</code> and
+ <code class="literal">jsonb_plperlu</code>. If you use them, <code class="type">jsonb</code>
+ values are mapped to Perl arrays, hashes, and scalars, as appropriate.
+ </p><p>
+ The extension for PL/Python is called <code class="literal">jsonb_plpython3u</code>.
+ If you use it, <code class="type">jsonb</code> values are mapped to Python
+ dictionaries, lists, and scalars, as appropriate.
+ </p><p>
+ Of these extensions, <code class="literal">jsonb_plperl</code> is
+ considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be installed by
+ non-superusers who have <code class="literal">CREATE</code> privilege on the
+ current database. The rest require superuser privilege to install.
+ </p></div><div class="sect2" id="DATATYPE-JSONPATH"><div class="titlepage"><div><div><h3 class="title">8.14.7. jsonpath Type</h3></div></div></div><a id="id-1.5.7.22.21.2" class="indexterm"></a><p>
+ The <code class="type">jsonpath</code> type implements support for the SQL/JSON path language
+ in <span class="productname">PostgreSQL</span> to efficiently query JSON data.
+ It provides a binary representation of the parsed SQL/JSON path
+ expression that specifies the items to be retrieved by the path
+ engine from the JSON data for further processing with the
+ SQL/JSON query functions.
+ </p><p>
+ The semantics of SQL/JSON path predicates and operators generally follow SQL.
+ At the same time, to provide a natural way of working with JSON data,
+ SQL/JSON path syntax uses some JavaScript conventions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Dot (<code class="literal">.</code>) is used for member access.
+ </p></li><li class="listitem"><p>
+ Square brackets (<code class="literal">[]</code>) are used for array access.
+ </p></li><li class="listitem"><p>
+ SQL/JSON arrays are 0-relative, unlike regular SQL arrays that start from 1.
+ </p></li></ul></div><p>
+ An SQL/JSON path expression is typically written in an SQL query as an
+ SQL character string literal, so it must be enclosed in single quotes,
+ and any single quotes desired within the value must be doubled
+ (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>).
+ Some forms of path expressions require string literals within them.
+ These embedded string literals follow JavaScript/ECMAScript conventions:
+ they must be surrounded by double quotes, and backslash escapes may be
+ used within them to represent otherwise-hard-to-type characters.
+ In particular, the way to write a double quote within an embedded string
+ literal is <code class="literal">\"</code>, and to write a backslash itself, you
+ must write <code class="literal">\\</code>. Other special backslash sequences
+ include those recognized in JSON strings:
+ <code class="literal">\b</code>,
+ <code class="literal">\f</code>,
+ <code class="literal">\n</code>,
+ <code class="literal">\r</code>,
+ <code class="literal">\t</code>,
+ <code class="literal">\v</code>
+ for various ASCII control characters, and
+ <code class="literal">\u<em class="replaceable"><code>NNNN</code></em></code> for a Unicode
+ character identified by its 4-hex-digit code point. The backslash
+ syntax also includes two cases not allowed by JSON:
+ <code class="literal">\x<em class="replaceable"><code>NN</code></em></code> for a character code
+ written with only two hex digits, and
+ <code class="literal">\u{<em class="replaceable"><code>N...</code></em>}</code> for a character
+ code written with 1 to 6 hex digits.
+ </p><p>
+ A path expression consists of a sequence of path elements,
+ which can be any of the following:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Path literals of JSON primitive types:
+ Unicode text, numeric, true, false, or null.
+ </p></li><li class="listitem"><p>
+ Path variables listed in <a class="xref" href="datatype-json.html#TYPE-JSONPATH-VARIABLES" title="Table 8.24. jsonpath Variables">Table 8.24</a>.
+ </p></li><li class="listitem"><p>
+ Accessor operators listed in <a class="xref" href="datatype-json.html#TYPE-JSONPATH-ACCESSORS" title="Table 8.25. jsonpath Accessors">Table 8.25</a>.
+ </p></li><li class="listitem"><p>
+ <code class="type">jsonpath</code> operators and methods listed
+ in <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS" title="9.16.2.2. SQL/JSON Path Operators and Methods">Section 9.16.2.2</a>.
+ </p></li><li class="listitem"><p>
+ Parentheses, which can be used to provide filter expressions
+ or define the order of path evaluation.
+ </p></li></ul></div><p>
+ </p><p>
+ For details on using <code class="type">jsonpath</code> expressions with SQL/JSON
+ query functions, see <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH" title="9.16.2. The SQL/JSON Path Language">Section 9.16.2</a>.
+ </p><div class="table" id="TYPE-JSONPATH-VARIABLES"><p class="title"><strong>Table 8.24. <code class="type">jsonpath</code> Variables</strong></p><div class="table-contents"><table class="table" summary="jsonpath Variables" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">$</code></td><td>A variable representing the JSON value being queried
+ (the <em class="firstterm">context item</em>).
+ </td></tr><tr><td><code class="literal">$varname</code></td><td>
+ A named variable. Its value can be set by the parameter
+ <em class="parameter"><code>vars</code></em> of several JSON processing functions;
+ see <a class="xref" href="functions-json.html#FUNCTIONS-JSON-PROCESSING-TABLE" title="Table 9.48. JSON Processing Functions">Table 9.48</a> for details.
+
+ </td></tr><tr><td><code class="literal">@</code></td><td>A variable representing the result of path evaluation
+ in filter expressions.
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="TYPE-JSONPATH-ACCESSORS"><p class="title"><strong>Table 8.25. <code class="type">jsonpath</code> Accessors</strong></p><div class="table-contents"><table class="table" summary="jsonpath Accessors" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Accessor Operator</th><th>Description</th></tr></thead><tbody><tr><td>
+ <p>
+ <code class="literal">.<em class="replaceable"><code>key</code></em></code>
+ </p>
+ <p>
+ <code class="literal">."$<em class="replaceable"><code>varname</code></em>"</code>
+ </p>
+ </td><td>
+ <p>
+ Member accessor that returns an object member with
+ the specified key. If the key name matches some named variable
+ starting with <code class="literal">$</code> or does not meet the
+ JavaScript rules for an identifier, it must be enclosed in
+ double quotes to make it a string literal.
+ </p>
+ </td></tr><tr><td>
+ <p>
+ <code class="literal">.*</code>
+ </p>
+ </td><td>
+ <p>
+ Wildcard member accessor that returns the values of all
+ members located at the top level of the current object.
+ </p>
+ </td></tr><tr><td>
+ <p>
+ <code class="literal">.**</code>
+ </p>
+ </td><td>
+ <p>
+ Recursive wildcard member accessor that processes all levels
+ of the JSON hierarchy of the current object and returns all
+ the member values, regardless of their nesting level. This
+ is a <span class="productname">PostgreSQL</span> extension of
+ the SQL/JSON standard.
+ </p>
+ </td></tr><tr><td>
+ <p>
+ <code class="literal">.**{<em class="replaceable"><code>level</code></em>}</code>
+ </p>
+ <p>
+ <code class="literal">.**{<em class="replaceable"><code>start_level</code></em> to
+ <em class="replaceable"><code>end_level</code></em>}</code>
+ </p>
+ </td><td>
+ <p>
+ Like <code class="literal">.**</code>, but selects only the specified
+ levels of the JSON hierarchy. Nesting levels are specified as integers.
+ Level zero corresponds to the current object. To access the lowest
+ nesting level, you can use the <code class="literal">last</code> keyword.
+ This is a <span class="productname">PostgreSQL</span> extension of
+ the SQL/JSON standard.
+ </p>
+ </td></tr><tr><td>
+ <p>
+ <code class="literal">[<em class="replaceable"><code>subscript</code></em>, ...]</code>
+ </p>
+ </td><td>
+ <p>
+ Array element accessor.
+ <code class="literal"><em class="replaceable"><code>subscript</code></em></code> can be
+ given in two forms: <code class="literal"><em class="replaceable"><code>index</code></em></code>
+ or <code class="literal"><em class="replaceable"><code>start_index</code></em> to <em class="replaceable"><code>end_index</code></em></code>.
+ The first form returns a single array element by its index. The second
+ form returns an array slice by the range of indexes, including the
+ elements that correspond to the provided
+ <em class="replaceable"><code>start_index</code></em> and <em class="replaceable"><code>end_index</code></em>.
+ </p>
+ <p>
+ The specified <em class="replaceable"><code>index</code></em> can be an integer, as
+ well as an expression returning a single numeric value, which is
+ automatically cast to integer. Index zero corresponds to the first
+ array element. You can also use the <code class="literal">last</code> keyword
+ to denote the last array element, which is useful for handling arrays
+ of unknown length.
+ </p>
+ </td></tr><tr><td>
+ <p>
+ <code class="literal">[*]</code>
+ </p>
+ </td><td>
+ <p>
+ Wildcard array element accessor that returns all array elements.
+ </p>
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.7.22.18.9.3" class="footnote"><p><a href="#id-1.5.7.22.18.9.3" class="para"><sup class="para">[7] </sup></a>
+ For this purpose, the term <span class="quote">“<span class="quote">value</span>”</span> includes array elements,
+ though JSON terminology sometimes considers array elements distinct
+ from values within objects.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-xml.html" title="8.13. XML Type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="arrays.html" title="8.15. Arrays">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.13. <acronym class="acronym">XML</acronym> Type </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.15. Arrays</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-money.html b/doc/src/sgml/html/datatype-money.html
new file mode 100644
index 0000000..9aa7a96
--- /dev/null
+++ b/doc/src/sgml/html/datatype-money.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.2. Monetary Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-numeric.html" title="8.1. Numeric Types" /><link rel="next" href="datatype-character.html" title="8.3. Character Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.2. Monetary Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-numeric.html" title="8.1. Numeric Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-character.html" title="8.3. Character Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-MONEY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.2. Monetary Types</h2></div></div></div><p>
+ The <code class="type">money</code> type stores a currency amount with a fixed
+ fractional precision; see <a class="xref" href="datatype-money.html#DATATYPE-MONEY-TABLE" title="Table 8.3. Monetary Types">Table 8.3</a>. The fractional precision is
+ determined by the database's <a class="xref" href="runtime-config-client.html#GUC-LC-MONETARY">lc_monetary</a> 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
+ currency formatting, such as <code class="literal">'$1,000.00'</code>.
+ Output is generally in the latter form but depends on the locale.
+ </p><div class="table" id="DATATYPE-MONEY-TABLE"><p class="title"><strong>Table 8.3. Monetary Types</strong></p><div class="table-contents"><table class="table" summary="Monetary Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th><th>Range</th></tr></thead><tbody><tr><td><code class="type">money</code></td><td>8 bytes</td><td>currency amount</td><td>-92233720368547758.08 to +92233720368547758.07</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Since the output of this data type is locale-sensitive, it might not
+ work to load <code class="type">money</code> data into a database that has a different
+ setting of <code class="varname">lc_monetary</code>. To avoid problems, before
+ restoring a dump into a new database make sure <code class="varname">lc_monetary</code> has
+ the same or equivalent value as in the database that was dumped.
+ </p><p>
+ Values of the <code class="type">numeric</code>, <code class="type">int</code>, and
+ <code class="type">bigint</code> data types can be cast to <code class="type">money</code>.
+ Conversion from the <code class="type">real</code> and <code class="type">double precision</code>
+ data types can be done by casting to <code class="type">numeric</code> first, for
+ example:
+</p><pre class="programlisting">
+SELECT '12.34'::float8::numeric::money;
+</pre><p>
+ However, this is not recommended. Floating point numbers should not be
+ used to handle money due to the potential for rounding errors.
+ </p><p>
+ A <code class="type">money</code> value can be cast to <code class="type">numeric</code> without
+ loss of precision. Conversion to other types could potentially lose
+ precision, and must also be done in two stages:
+</p><pre class="programlisting">
+SELECT '52093.89'::money::numeric::float8;
+</pre><p>
+ </p><p>
+ Division of a <code class="type">money</code> value by an integer value is performed
+ with truncation of the fractional part towards zero. To get a rounded
+ result, divide by a floating-point value, or cast the <code class="type">money</code>
+ value to <code class="type">numeric</code> before dividing and back to <code class="type">money</code>
+ afterwards. (The latter is preferable to avoid risking precision loss.)
+ When a <code class="type">money</code> value is divided by another <code class="type">money</code>
+ value, the result is <code class="type">double precision</code> (i.e., a pure number,
+ not money); the currency units cancel each other out in the division.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-numeric.html" title="8.1. Numeric Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-character.html" title="8.3. Character Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.1. Numeric Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.3. Character Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-net-types.html b/doc/src/sgml/html/datatype-net-types.html
new file mode 100644
index 0000000..3a8ef3c
--- /dev/null
+++ b/doc/src/sgml/html/datatype-net-types.html
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.9. Network Address Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-geometric.html" title="8.8. Geometric Types" /><link rel="next" href="datatype-bit.html" title="8.10. Bit String Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.9. Network Address Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-geometric.html" title="8.8. Geometric Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-bit.html" title="8.10. Bit String Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-NET-TYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.9. Network Address Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-INET">8.9.1. <code class="type">inet</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-CIDR">8.9.2. <code class="type">cidr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-INET-VS-CIDR">8.9.3. <code class="type">inet</code> vs. <code class="type">cidr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-MACADDR">8.9.4. <code class="type">macaddr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-MACADDR8">8.9.5. <code class="type">macaddr8</code></a></span></dt></dl></div><a id="id-1.5.7.17.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> offers data types to store IPv4, IPv6, and MAC
+ addresses, as shown in <a class="xref" href="datatype-net-types.html#DATATYPE-NET-TYPES-TABLE" title="Table 8.21. Network Address Types">Table 8.21</a>. 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 <a class="xref" href="functions-net.html" title="9.12. Network Address Functions and Operators">Section 9.12</a>).
+ </p><div class="table" id="DATATYPE-NET-TYPES-TABLE"><p class="title"><strong>Table 8.21. Network Address Types</strong></p><div class="table-contents"><table class="table" summary="Network Address Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">cidr</code></td><td>7 or 19 bytes</td><td>IPv4 and IPv6 networks</td></tr><tr><td><code class="type">inet</code></td><td>7 or 19 bytes</td><td>IPv4 and IPv6 hosts and networks</td></tr><tr><td><code class="type">macaddr</code></td><td>6 bytes</td><td>MAC addresses</td></tr><tr><td><code class="type">macaddr8</code></td><td>8 bytes</td><td>MAC addresses (EUI-64 format)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ When sorting <code class="type">inet</code> or <code class="type">cidr</code> data types,
+ IPv4 addresses will always sort before IPv6 addresses, including
+ IPv4 addresses encapsulated or mapped to IPv6 addresses, such as
+ ::10.2.3.4 or ::ffff:10.4.3.2.
+ </p><div class="sect2" id="DATATYPE-INET"><div class="titlepage"><div><div><h3 class="title">8.9.1. <code class="type">inet</code></h3></div></div></div><a id="id-1.5.7.17.6.2" class="indexterm"></a><p>
+ The <code class="type">inet</code> type holds an IPv4 or IPv6 host address, and
+ optionally its subnet, all in one field.
+ The subnet is represented by the number of network address bits
+ present in the host address (the
+ <span class="quote">“<span class="quote">netmask</span>”</span>). If the netmask is 32 and the address is IPv4,
+ then the value does not indicate a subnet, only a single host.
+ In IPv6, the address length is 128 bits, so 128 bits specify a
+ unique host address. Note that if you
+ want to accept only networks, you should use the
+ <code class="type">cidr</code> type rather than <code class="type">inet</code>.
+ </p><p>
+ The input format for this type is
+ <em class="replaceable"><code>address/y</code></em>
+ where
+ <em class="replaceable"><code>address</code></em>
+ is an IPv4 or IPv6 address and
+ <em class="replaceable"><code>y</code></em>
+ is the number of bits in the netmask. If the
+ <em class="replaceable"><code>/y</code></em>
+ portion is omitted, the
+ netmask is taken to be 32 for IPv4 or 128 for IPv6,
+ so the value represents
+ just a single host. On display, the
+ <em class="replaceable"><code>/y</code></em>
+ portion is suppressed if the netmask specifies a single host.
+ </p></div><div class="sect2" id="DATATYPE-CIDR"><div class="titlepage"><div><div><h3 class="title">8.9.2. <code class="type">cidr</code></h3></div></div></div><a id="id-1.5.7.17.7.2" class="indexterm"></a><p>
+ The <code class="type">cidr</code> type holds an IPv4 or IPv6 network specification.
+ Input and output formats follow Classless Internet Domain Routing
+ conventions.
+ The format for specifying networks is <em class="replaceable"><code>address/y</code></em> where <em class="replaceable"><code>address</code></em> is the network's lowest
+ address represented as an
+ IPv4 or IPv6 address, and <em class="replaceable"><code>y</code></em> is the number of bits in the netmask. If
+ <em class="replaceable"><code>y</code></em> is omitted, it is calculated
+ using assumptions from the older classful network numbering system, except
+ it will be at least large enough to include all of the octets
+ written in the input. It is an error to specify a network address
+ that has bits set to the right of the specified netmask.
+ </p><p>
+ <a class="xref" href="datatype-net-types.html#DATATYPE-NET-CIDR-TABLE" title="Table 8.22. cidr Type Input Examples">Table 8.22</a> shows some examples.
+ </p><div class="table" id="DATATYPE-NET-CIDR-TABLE"><p class="title"><strong>Table 8.22. <code class="type">cidr</code> Type Input Examples</strong></p><div class="table-contents"><table class="table" summary="cidr Type Input Examples" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th><code class="type">cidr</code> Input</th><th><code class="type">cidr</code> Output</th><th><code class="literal"><code class="function">abbrev(<code class="type">cidr</code>)</code></code></th></tr></thead><tbody><tr><td>192.168.100.128/25</td><td>192.168.100.128/25</td><td>192.168.100.128/25</td></tr><tr><td>192.168/24</td><td>192.168.0.0/24</td><td>192.168.0/24</td></tr><tr><td>192.168/25</td><td>192.168.0.0/25</td><td>192.168.0.0/25</td></tr><tr><td>192.168.1</td><td>192.168.1.0/24</td><td>192.168.1/24</td></tr><tr><td>192.168</td><td>192.168.0.0/24</td><td>192.168.0/24</td></tr><tr><td>128.1</td><td>128.1.0.0/16</td><td>128.1/16</td></tr><tr><td>128</td><td>128.0.0.0/16</td><td>128.0/16</td></tr><tr><td>128.1.2</td><td>128.1.2.0/24</td><td>128.1.2/24</td></tr><tr><td>10.1.2</td><td>10.1.2.0/24</td><td>10.1.2/24</td></tr><tr><td>10.1</td><td>10.1.0.0/16</td><td>10.1/16</td></tr><tr><td>10</td><td>10.0.0.0/8</td><td>10/8</td></tr><tr><td>10.1.2.3/32</td><td>10.1.2.3/32</td><td>10.1.2.3/32</td></tr><tr><td>2001:4f8:3:ba::/64</td><td>2001:4f8:3:ba::/64</td><td>2001:4f8:3:ba/64</td></tr><tr><td>2001:4f8:3:ba:​2e0:81ff:fe22:d1f1/128</td><td>2001:4f8:3:ba:​2e0:81ff:fe22:d1f1/128</td><td>2001:4f8:3:ba:​2e0:81ff:fe22:d1f1/128</td></tr><tr><td>::ffff:1.2.3.0/120</td><td>::ffff:1.2.3.0/120</td><td>::ffff:1.2.3/120</td></tr><tr><td>::ffff:1.2.3.0/128</td><td>::ffff:1.2.3.0/128</td><td>::ffff:1.2.3.0/128</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="DATATYPE-INET-VS-CIDR"><div class="titlepage"><div><div><h3 class="title">8.9.3. <code class="type">inet</code> vs. <code class="type">cidr</code></h3></div></div></div><p>
+ The essential difference between <code class="type">inet</code> and <code class="type">cidr</code>
+ data types is that <code class="type">inet</code> accepts values with nonzero bits to
+ the right of the netmask, whereas <code class="type">cidr</code> does not. For
+ example, <code class="literal">192.168.0.1/24</code> is valid for <code class="type">inet</code>
+ but not for <code class="type">cidr</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If you do not like the output format for <code class="type">inet</code> or
+ <code class="type">cidr</code> values, try the functions <code class="function">host</code>,
+ <code class="function">text</code>, and <code class="function">abbrev</code>.
+ </p></div></div><div class="sect2" id="DATATYPE-MACADDR"><div class="titlepage"><div><div><h3 class="title">8.9.4. <code class="type">macaddr</code></h3></div></div></div><a id="id-1.5.7.17.9.2" class="indexterm"></a><a id="id-1.5.7.17.9.3" class="indexterm"></a><p>
+ The <code class="type">macaddr</code> type stores MAC addresses, known for example
+ from Ethernet card hardware addresses (although MAC addresses are
+ used for other purposes as well). Input is accepted in the
+ following formats:
+
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">'08:00:2b:01:02:03'</code></td></tr><tr><td><code class="literal">'08-00-2b-01-02-03'</code></td></tr><tr><td><code class="literal">'08002b:010203'</code></td></tr><tr><td><code class="literal">'08002b-010203'</code></td></tr><tr><td><code class="literal">'0800.2b01.0203'</code></td></tr><tr><td><code class="literal">'0800-2b01-0203'</code></td></tr><tr><td><code class="literal">'08002b010203'</code></td></tr></table><p>
+
+ These examples all specify the same address. Upper and
+ lower case is accepted for the digits
+ <code class="literal">a</code> through <code class="literal">f</code>. Output is always in the
+ first of the forms shown.
+ </p><p>
+ IEEE Standard 802-2001 specifies the second form shown (with hyphens)
+ as the canonical form for MAC addresses, and specifies the first
+ form (with colons) as used with bit-reversed, MSB-first notation, so that
+ 08-00-2b-01-02-03 = 10:00:D4:80:40:C0. This convention is widely
+ ignored nowadays, and it is relevant only for obsolete network
+ protocols (such as Token Ring). PostgreSQL makes no provisions
+ for bit reversal; all accepted formats use the canonical LSB
+ order.
+ </p><p>
+ The remaining five input formats are not part of any standard.
+ </p></div><div class="sect2" id="DATATYPE-MACADDR8"><div class="titlepage"><div><div><h3 class="title">8.9.5. <code class="type">macaddr8</code></h3></div></div></div><a id="id-1.5.7.17.10.2" class="indexterm"></a><a id="id-1.5.7.17.10.3" class="indexterm"></a><p>
+ The <code class="type">macaddr8</code> type stores MAC addresses in EUI-64
+ format, known for example from Ethernet card hardware addresses
+ (although MAC addresses are used for other purposes as well).
+ This type can accept both 6 and 8 byte length MAC addresses
+ and stores them in 8 byte length format. MAC addresses given
+ in 6 byte format will be stored in 8 byte length format with the
+ 4th and 5th bytes set to FF and FE, respectively.
+
+ Note that IPv6 uses a modified EUI-64 format where the 7th bit
+ should be set to one after the conversion from EUI-48. The
+ function <code class="function">macaddr8_set7bit</code> is provided to make this
+ change.
+
+ Generally speaking, any input which is comprised of pairs of hex
+ digits (on byte boundaries), optionally separated consistently by
+ one of <code class="literal">':'</code>, <code class="literal">'-'</code> or <code class="literal">'.'</code>, is
+ accepted. The number of hex digits must be either 16 (8 bytes) or
+ 12 (6 bytes). Leading and trailing whitespace is ignored.
+
+ The following are examples of input formats that are accepted:
+
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">'08:00:2b:01:02:03:04:05'</code></td></tr><tr><td><code class="literal">'08-00-2b-01-02-03-04-05'</code></td></tr><tr><td><code class="literal">'08002b:0102030405'</code></td></tr><tr><td><code class="literal">'08002b-0102030405'</code></td></tr><tr><td><code class="literal">'0800.2b01.0203.0405'</code></td></tr><tr><td><code class="literal">'0800-2b01-0203-0405'</code></td></tr><tr><td><code class="literal">'08002b01:02030405'</code></td></tr><tr><td><code class="literal">'08002b0102030405'</code></td></tr></table><p>
+
+ These examples all specify the same address. Upper and
+ lower case is accepted for the digits
+ <code class="literal">a</code> through <code class="literal">f</code>. Output is always in the
+ first of the forms shown.
+ </p><p>
+ The last six input formats shown above are not part of any standard.
+ </p><p>
+ To convert a traditional 48 bit MAC address in EUI-48 format to
+ modified EUI-64 format to be included as the host portion of an
+ IPv6 address, use <code class="function">macaddr8_set7bit</code> as shown:
+
+</p><pre class="programlisting">
+SELECT macaddr8_set7bit('08:00:2b:01:02:03');
+<code class="computeroutput">
+ macaddr8_set7bit
+-------------------------
+ 0a:00:2b:ff:fe:01:02:03
+(1 row)
+</code>
+</pre><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-geometric.html" title="8.8. Geometric Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-bit.html" title="8.10. Bit String Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.8. Geometric Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.10. Bit String Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-numeric.html b/doc/src/sgml/html/datatype-numeric.html
new file mode 100644
index 0000000..e8df3c1
--- /dev/null
+++ b/doc/src/sgml/html/datatype-numeric.html
@@ -0,0 +1,370 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.1. Numeric Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype.html" title="Chapter 8. Data Types" /><link rel="next" href="datatype-money.html" title="8.2. Monetary Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.1. Numeric Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype.html" title="Chapter 8. Data Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-money.html" title="8.2. Monetary Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-NUMERIC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.1. Numeric Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-INT">8.1.1. Integer Types</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">8.1.2. Arbitrary Precision Numbers</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-FLOAT">8.1.3. Floating-Point Types</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-SERIAL">8.1.4. Serial Types</a></span></dt></dl></div><a id="id-1.5.7.9.2" class="indexterm"></a><p>
+ Numeric types consist of two-, four-, and eight-byte integers,
+ four- and eight-byte floating-point numbers, and selectable-precision
+ decimals. <a class="xref" href="datatype-numeric.html#DATATYPE-NUMERIC-TABLE" title="Table 8.2. Numeric Types">Table 8.2</a> lists the
+ available types.
+ </p><div class="table" id="DATATYPE-NUMERIC-TABLE"><p class="title"><strong>Table 8.2. Numeric Types</strong></p><div class="table-contents"><table class="table" summary="Numeric Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th><th>Range</th></tr></thead><tbody><tr><td><code class="type">smallint</code></td><td>2 bytes</td><td>small-range integer</td><td>-32768 to +32767</td></tr><tr><td><code class="type">integer</code></td><td>4 bytes</td><td>typical choice for integer</td><td>-2147483648 to +2147483647</td></tr><tr><td><code class="type">bigint</code></td><td>8 bytes</td><td>large-range integer</td><td>-9223372036854775808 to +9223372036854775807</td></tr><tr><td><code class="type">decimal</code></td><td>variable</td><td>user-specified precision, exact</td><td>up to 131072 digits before the decimal point; up to 16383 digits after the decimal point</td></tr><tr><td><code class="type">numeric</code></td><td>variable</td><td>user-specified precision, exact</td><td>up to 131072 digits before the decimal point; up to 16383 digits after the decimal point</td></tr><tr><td><code class="type">real</code></td><td>4 bytes</td><td>variable-precision, inexact</td><td>6 decimal digits precision</td></tr><tr><td><code class="type">double precision</code></td><td>8 bytes</td><td>variable-precision, inexact</td><td>15 decimal digits precision</td></tr><tr><td><code class="type">smallserial</code></td><td>2 bytes</td><td>small autoincrementing integer</td><td>1 to 32767</td></tr><tr><td><code class="type">serial</code></td><td>4 bytes</td><td>autoincrementing integer</td><td>1 to 2147483647</td></tr><tr><td><code class="type">bigserial</code></td><td>8 bytes</td><td>large autoincrementing integer</td><td>1 to 9223372036854775807</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The syntax of constants for the numeric types is described in
+ <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS" title="4.1.2. Constants">Section 4.1.2</a>. The numeric types have a
+ full set of corresponding arithmetic operators and
+ functions. Refer to <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a> for more
+ information. The following sections describe the types in detail.
+ </p><div class="sect2" id="DATATYPE-INT"><div class="titlepage"><div><div><h3 class="title">8.1.1. Integer Types</h3></div></div></div><a id="id-1.5.7.9.6.2" class="indexterm"></a><a id="id-1.5.7.9.6.3" class="indexterm"></a><a id="id-1.5.7.9.6.4" class="indexterm"></a><a id="id-1.5.7.9.6.5" class="indexterm"></a><a id="id-1.5.7.9.6.6" class="indexterm"></a><a id="id-1.5.7.9.6.7" class="indexterm"></a><p>
+ The types <code class="type">smallint</code>, <code class="type">integer</code>, and
+ <code class="type">bigint</code> store whole numbers, that is, numbers without
+ fractional components, of various ranges. Attempts to store
+ values outside of the allowed range will result in an error.
+ </p><p>
+ The type <code class="type">integer</code> is the common choice, as it offers
+ the best balance between range, storage size, and performance.
+ The <code class="type">smallint</code> type is generally only used if disk
+ space is at a premium. The <code class="type">bigint</code> type is designed to be
+ used when the range of the <code class="type">integer</code> type is insufficient.
+ </p><p>
+ <acronym class="acronym">SQL</acronym> only specifies the integer types
+ <code class="type">integer</code> (or <code class="type">int</code>),
+ <code class="type">smallint</code>, and <code class="type">bigint</code>. The
+ type names <code class="type">int2</code>, <code class="type">int4</code>, and
+ <code class="type">int8</code> are extensions, which are also used by some
+ other <acronym class="acronym">SQL</acronym> database systems.
+ </p></div><div class="sect2" id="DATATYPE-NUMERIC-DECIMAL"><div class="titlepage"><div><div><h3 class="title">8.1.2. Arbitrary Precision Numbers</h3></div></div></div><a id="id-1.5.7.9.7.2" class="indexterm"></a><a id="id-1.5.7.9.7.3" class="indexterm"></a><a id="id-1.5.7.9.7.4" class="indexterm"></a><p>
+ The type <code class="type">numeric</code> can store numbers with a
+ very large number of digits. It is especially recommended for
+ storing monetary amounts and other quantities where exactness is
+ required. Calculations with <code class="type">numeric</code> values yield exact
+ results where possible, e.g., addition, subtraction, multiplication.
+ However, calculations on <code class="type">numeric</code> values are very slow
+ compared to the integer types, or to the floating-point types
+ described in the next section.
+ </p><p>
+ We use the following terms below: The
+ <em class="firstterm">precision</em> of a <code class="type">numeric</code>
+ is the total count of significant digits in the whole number,
+ that is, the number of digits to both sides of the decimal point.
+ The <em class="firstterm">scale</em> of a <code class="type">numeric</code> is the
+ count of decimal digits in the fractional part, to the right of the
+ decimal point. So the number 23.5141 has a precision of 6 and a
+ scale of 4. Integers can be considered to have a scale of zero.
+ </p><p>
+ Both the maximum precision and the maximum scale of a
+ <code class="type">numeric</code> column can be
+ configured. To declare a column of type <code class="type">numeric</code> use
+ the syntax:
+</p><pre class="programlisting">
+NUMERIC(<em class="replaceable"><code>precision</code></em>, <em class="replaceable"><code>scale</code></em>)
+</pre><p>
+ The precision must be positive, while the scale may be positive or
+ negative (see below). Alternatively:
+</p><pre class="programlisting">
+NUMERIC(<em class="replaceable"><code>precision</code></em>)
+</pre><p>
+ selects a scale of 0. Specifying:
+</p><pre class="programlisting">
+NUMERIC
+</pre><p>
+ without any precision or scale creates an <span class="quote">“<span class="quote">unconstrained
+ numeric</span>”</span> column in which numeric values of any length can be
+ stored, up to the implementation limits. A column of this kind will
+ not coerce input values to any particular scale, whereas
+ <code class="type">numeric</code> columns with a declared scale will coerce
+ input values to that scale. (The <acronym class="acronym">SQL</acronym> standard
+ requires a default scale of 0, i.e., coercion to integer
+ precision. We find this a bit useless. If you're concerned
+ about portability, always specify the precision and scale
+ explicitly.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The maximum precision that can be explicitly specified in
+ a <code class="type">numeric</code> type declaration is 1000. An
+ unconstrained <code class="type">numeric</code> column is subject to the limits
+ described in <a class="xref" href="datatype-numeric.html#DATATYPE-NUMERIC-TABLE" title="Table 8.2. Numeric Types">Table 8.2</a>.
+ </p></div><p>
+ If the scale of a value to be stored is greater than the declared
+ scale of the column, the system will round the value to the specified
+ number of fractional digits. Then, if the number of digits to the
+ left of the decimal point exceeds the declared precision minus the
+ declared scale, an error is raised.
+ For example, a column declared as
+</p><pre class="programlisting">
+NUMERIC(3, 1)
+</pre><p>
+ will round values to 1 decimal place and can store values between
+ -99.9 and 99.9, inclusive.
+ </p><p>
+ Beginning in <span class="productname">PostgreSQL</span> 15, it is allowed
+ to declare a <code class="type">numeric</code> column with a negative scale. Then
+ values will be rounded to the left of the decimal point. The
+ precision still represents the maximum number of non-rounded digits.
+ Thus, a column declared as
+</p><pre class="programlisting">
+NUMERIC(2, -3)
+</pre><p>
+ will round values to the nearest thousand and can store values
+ between -99000 and 99000, inclusive.
+ It is also allowed to declare a scale larger than the declared
+ precision. Such a column can only hold fractional values, and it
+ requires the number of zero digits just to the right of the decimal
+ point to be at least the declared scale minus the declared precision.
+ For example, a column declared as
+</p><pre class="programlisting">
+NUMERIC(3, 5)
+</pre><p>
+ will round values to 5 decimal places and can store values between
+ -0.00999 and 0.00999, inclusive.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> permits the scale in a
+ <code class="type">numeric</code> type declaration to be any value in the range
+ -1000 to 1000. However, the <acronym class="acronym">SQL</acronym> standard requires
+ the scale to be in the range 0 to <em class="replaceable"><code>precision</code></em>.
+ Using scales outside that range may not be portable to other database
+ systems.
+ </p></div><p>
+ Numeric values are physically stored without any extra leading or
+ trailing zeroes. Thus, the declared precision and scale of a column
+ are maximums, not fixed allocations. (In this sense the <code class="type">numeric</code>
+ type is more akin to <code class="type">varchar(<em class="replaceable"><code>n</code></em>)</code>
+ than to <code class="type">char(<em class="replaceable"><code>n</code></em>)</code>.) The actual storage
+ requirement is two bytes for each group of four decimal digits,
+ plus three to eight bytes overhead.
+ </p><a id="id-1.5.7.9.7.13" class="indexterm"></a><a id="id-1.5.7.9.7.14" class="indexterm"></a><a id="id-1.5.7.9.7.15" class="indexterm"></a><p>
+ In addition to ordinary numeric values, the <code class="type">numeric</code> type
+ has several special values:
+</p><div class="literallayout"><p><br />
+<code class="literal">Infinity</code><br />
+<code class="literal">-Infinity</code><br />
+<code class="literal">NaN</code><br />
+</p></div><p>
+ These are adapted from the IEEE 754 standard, and represent
+ <span class="quote">“<span class="quote">infinity</span>”</span>, <span class="quote">“<span class="quote">negative infinity</span>”</span>, and
+ <span class="quote">“<span class="quote">not-a-number</span>”</span>, respectively. When writing these values
+ as constants in an SQL command, you must put quotes around them,
+ for example <code class="literal">UPDATE table SET x = '-Infinity'</code>.
+ On input, these strings are recognized in a case-insensitive manner.
+ The infinity values can alternatively be spelled <code class="literal">inf</code>
+ and <code class="literal">-inf</code>.
+ </p><p>
+ The infinity values behave as per mathematical expectations. For
+ example, <code class="literal">Infinity</code> plus any finite value equals
+ <code class="literal">Infinity</code>, as does <code class="literal">Infinity</code>
+ plus <code class="literal">Infinity</code>; but <code class="literal">Infinity</code>
+ minus <code class="literal">Infinity</code> yields <code class="literal">NaN</code> (not a
+ number), because it has no well-defined interpretation. Note that an
+ infinity can only be stored in an unconstrained <code class="type">numeric</code>
+ column, because it notionally exceeds any finite precision limit.
+ </p><p>
+ The <code class="literal">NaN</code> (not a number) value is used to represent
+ undefined calculational results. In general, any operation with
+ a <code class="literal">NaN</code> input yields another <code class="literal">NaN</code>.
+ The only exception is when the operation's other inputs are such that
+ the same output would be obtained if the <code class="literal">NaN</code> were to
+ be replaced by any finite or infinite numeric value; then, that output
+ value is used for <code class="literal">NaN</code> too. (An example of this
+ principle is that <code class="literal">NaN</code> raised to the zero power
+ yields one.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In most implementations of the <span class="quote">“<span class="quote">not-a-number</span>”</span> concept,
+ <code class="literal">NaN</code> is not considered equal to any other numeric
+ value (including <code class="literal">NaN</code>). In order to allow
+ <code class="type">numeric</code> values to be sorted and used in tree-based
+ indexes, <span class="productname">PostgreSQL</span> treats <code class="literal">NaN</code>
+ values as equal, and greater than all non-<code class="literal">NaN</code>
+ values.
+ </p></div><p>
+ The types <code class="type">decimal</code> and <code class="type">numeric</code> are
+ equivalent. Both types are part of the <acronym class="acronym">SQL</acronym>
+ standard.
+ </p><p>
+ When rounding values, the <code class="type">numeric</code> type rounds ties away
+ from zero, while (on most machines) the <code class="type">real</code>
+ and <code class="type">double precision</code> types round ties to the nearest even
+ number. For example:
+
+</p><pre class="programlisting">
+SELECT x,
+ round(x::numeric) AS num_round,
+ round(x::double precision) AS dbl_round
+FROM generate_series(-3.5, 3.5, 1) as x;
+ x | num_round | dbl_round
+------+-----------+-----------
+ -3.5 | -4 | -4
+ -2.5 | -3 | -2
+ -1.5 | -2 | -2
+ -0.5 | -1 | -0
+ 0.5 | 1 | 0
+ 1.5 | 2 | 2
+ 2.5 | 3 | 2
+ 3.5 | 4 | 4
+(8 rows)
+</pre><p>
+ </p></div><div class="sect2" id="DATATYPE-FLOAT"><div class="titlepage"><div><div><h3 class="title">8.1.3. Floating-Point Types</h3></div></div></div><a id="id-1.5.7.9.8.2" class="indexterm"></a><a id="id-1.5.7.9.8.3" class="indexterm"></a><a id="id-1.5.7.9.8.4" class="indexterm"></a><a id="id-1.5.7.9.8.5" class="indexterm"></a><a id="id-1.5.7.9.8.6" class="indexterm"></a><p>
+ The data types <code class="type">real</code> and <code class="type">double precision</code> are
+ inexact, variable-precision numeric types. On all currently supported
+ platforms, these types are implementations of <acronym class="acronym">IEEE</acronym>
+ Standard 754 for Binary Floating-Point Arithmetic (single and double
+ precision, respectively), to the extent that the underlying processor,
+ operating system, and compiler support it.
+ </p><p>
+ Inexact means that some values cannot be converted exactly to the
+ internal format and are stored as approximations, so that storing
+ and retrieving a value might show slight discrepancies.
+ Managing these errors and how they propagate through calculations
+ is the subject of an entire branch of mathematics and computer
+ science and will not be discussed here, except for the
+ following points:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If you require exact storage and calculations (such as for
+ monetary amounts), use the <code class="type">numeric</code> type instead.
+ </p></li><li class="listitem"><p>
+ If you want to do complicated calculations with these types
+ for anything important, especially if you rely on certain
+ behavior in boundary cases (infinity, underflow), you should
+ evaluate the implementation carefully.
+ </p></li><li class="listitem"><p>
+ Comparing two floating-point values for equality might not
+ always work as expected.
+ </p></li></ul></div><p>
+ </p><p>
+ On all currently supported platforms, the <code class="type">real</code> type has a
+ range of around 1E-37 to 1E+37 with a precision of at least 6 decimal
+ digits. The <code class="type">double precision</code> type has a range of around
+ 1E-307 to 1E+308 with a precision of at least 15 digits. Values that are
+ too large or too small will cause an error. Rounding might take place if
+ the precision of an input number is too high. Numbers too close to zero
+ that are not representable as distinct from zero will cause an underflow
+ error.
+ </p><p>
+ By default, floating point values are output in text form in their
+ shortest precise decimal representation; the decimal value produced is
+ closer to the true stored binary value than to any other value
+ representable in the same binary precision. (However, the output value is
+ currently never <span class="emphasis"><em>exactly</em></span> midway between two
+ representable values, in order to avoid a widespread bug where input
+ routines do not properly respect the round-to-nearest-even rule.) This value will
+ use at most 17 significant decimal digits for <code class="type">float8</code>
+ values, and at most 9 digits for <code class="type">float4</code> values.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This shortest-precise output format is much faster to generate than the
+ historical rounded format.
+ </p></div><p>
+ For compatibility with output generated by older versions
+ of <span class="productname">PostgreSQL</span>, and to allow the output
+ precision to be reduced, the <a class="xref" href="runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS">extra_float_digits</a>
+ parameter can be used to select rounded decimal output instead. Setting a
+ value of 0 restores the previous default of rounding the value to 6
+ (for <code class="type">float4</code>) or 15 (for <code class="type">float8</code>)
+ significant decimal digits. Setting a negative value reduces the number
+ of digits further; for example -2 would round output to 4 or 13 digits
+ respectively.
+ </p><p>
+ Any value of <a class="xref" href="runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS">extra_float_digits</a> greater than 0
+ selects the shortest-precise format.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Applications that wanted precise values have historically had to set
+ <a class="xref" href="runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS">extra_float_digits</a> to 3 to obtain them. For
+ maximum compatibility between versions, they should continue to do so.
+ </p></div><a id="id-1.5.7.9.8.15" class="indexterm"></a><a id="id-1.5.7.9.8.16" class="indexterm"></a><p>
+ In addition to ordinary numeric values, the floating-point types
+ have several special values:
+</p><div class="literallayout"><p><br />
+<code class="literal">Infinity</code><br />
+<code class="literal">-Infinity</code><br />
+<code class="literal">NaN</code><br />
+</p></div><p>
+ These represent the IEEE 754 special values
+ <span class="quote">“<span class="quote">infinity</span>”</span>, <span class="quote">“<span class="quote">negative infinity</span>”</span>, and
+ <span class="quote">“<span class="quote">not-a-number</span>”</span>, respectively. When writing these values
+ as constants in an SQL command, you must put quotes around them,
+ for example <code class="literal">UPDATE table SET x = '-Infinity'</code>. On input,
+ these strings are recognized in a case-insensitive manner.
+ The infinity values can alternatively be spelled <code class="literal">inf</code>
+ and <code class="literal">-inf</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ IEEE 754 specifies that <code class="literal">NaN</code> should not compare equal
+ to any other floating-point value (including <code class="literal">NaN</code>).
+ In order to allow floating-point values to be sorted and used
+ in tree-based indexes, <span class="productname">PostgreSQL</span> treats
+ <code class="literal">NaN</code> values as equal, and greater than all
+ non-<code class="literal">NaN</code> values.
+ </p></div><p>
+ <span class="productname">PostgreSQL</span> also supports the SQL-standard
+ notations <code class="type">float</code> and
+ <code class="type">float(<em class="replaceable"><code>p</code></em>)</code> for specifying
+ inexact numeric types. Here, <em class="replaceable"><code>p</code></em> specifies
+ the minimum acceptable precision in <span class="emphasis"><em>binary</em></span> digits.
+ <span class="productname">PostgreSQL</span> accepts
+ <code class="type">float(1)</code> to <code class="type">float(24)</code> as selecting the
+ <code class="type">real</code> type, while
+ <code class="type">float(25)</code> to <code class="type">float(53)</code> select
+ <code class="type">double precision</code>. Values of <em class="replaceable"><code>p</code></em>
+ outside the allowed range draw an error.
+ <code class="type">float</code> with no precision specified is taken to mean
+ <code class="type">double precision</code>.
+ </p></div><div class="sect2" id="DATATYPE-SERIAL"><div class="titlepage"><div><div><h3 class="title">8.1.4. Serial Types</h3></div></div></div><a id="id-1.5.7.9.9.2" class="indexterm"></a><a id="id-1.5.7.9.9.3" class="indexterm"></a><a id="id-1.5.7.9.9.4" class="indexterm"></a><a id="id-1.5.7.9.9.5" class="indexterm"></a><a id="id-1.5.7.9.9.6" class="indexterm"></a><a id="id-1.5.7.9.9.7" class="indexterm"></a><a id="id-1.5.7.9.9.8" class="indexterm"></a><a id="id-1.5.7.9.9.9" class="indexterm"></a><div class="note"><h3 class="title">Note</h3><p>
+ 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 <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>.
+ </p></div><p>
+ The data types <code class="type">smallserial</code>, <code class="type">serial</code> and
+ <code class="type">bigserial</code> are not true types, but merely
+ a notational convenience for creating unique identifier columns
+ (similar to the <code class="literal">AUTO_INCREMENT</code> property
+ supported by some other databases). In the current
+ implementation, specifying:
+
+</p><pre class="programlisting">
+CREATE TABLE <em class="replaceable"><code>tablename</code></em> (
+ <em class="replaceable"><code>colname</code></em> SERIAL
+);
+</pre><p>
+
+ is equivalent to specifying:
+
+</p><pre class="programlisting">
+CREATE SEQUENCE <em class="replaceable"><code>tablename</code></em>_<em class="replaceable"><code>colname</code></em>_seq AS integer;
+CREATE TABLE <em class="replaceable"><code>tablename</code></em> (
+ <em class="replaceable"><code>colname</code></em> integer NOT NULL DEFAULT nextval('<em class="replaceable"><code>tablename</code></em>_<em class="replaceable"><code>colname</code></em>_seq')
+);
+ALTER SEQUENCE <em class="replaceable"><code>tablename</code></em>_<em class="replaceable"><code>colname</code></em>_seq OWNED BY <em class="replaceable"><code>tablename</code></em>.<em class="replaceable"><code>colname</code></em>;
+</pre><p>
+
+ Thus, we have created an integer column and arranged for its default
+ values to be assigned from a sequence generator. A <code class="literal">NOT NULL</code>
+ constraint is applied to ensure that a null value cannot be
+ inserted. (In most cases you would also want to attach a
+ <code class="literal">UNIQUE</code> or <code class="literal">PRIMARY KEY</code> constraint to prevent
+ duplicate values from being inserted by accident, but this is
+ not automatic.) Lastly, the sequence is marked as <span class="quote">“<span class="quote">owned by</span>”</span>
+ the column, so that it will be dropped if the column or table is dropped.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Because <code class="type">smallserial</code>, <code class="type">serial</code> and
+ <code class="type">bigserial</code> are implemented using sequences, there may
+ be "holes" or gaps in the sequence of values which appears in the
+ column, even if no rows are ever deleted. A value allocated
+ from the sequence is still "used up" even if a row containing that
+ value is never successfully inserted into the table column. This
+ may happen, for example, if the inserting transaction rolls back.
+ See <code class="literal">nextval()</code> in <a class="xref" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Section 9.17</a>
+ for details.
+ </p></div><p>
+ To insert the next value of the sequence into the <code class="type">serial</code>
+ column, specify that the <code class="type">serial</code>
+ column should be assigned its default value. This can be done
+ either by excluding the column from the list of columns in
+ the <code class="command">INSERT</code> statement, or through the use of
+ the <code class="literal">DEFAULT</code> key word.
+ </p><p>
+ The type names <code class="type">serial</code> and <code class="type">serial4</code> are
+ equivalent: both create <code class="type">integer</code> columns. The type
+ names <code class="type">bigserial</code> and <code class="type">serial8</code> work
+ the same way, except that they create a <code class="type">bigint</code>
+ column. <code class="type">bigserial</code> should be used if you anticipate
+ the use of more than 2<sup>31</sup> identifiers over the
+ lifetime of the table. The type names <code class="type">smallserial</code> and
+ <code class="type">serial2</code> also work the same way, except that they
+ create a <code class="type">smallint</code> column.
+ </p><p>
+ The sequence created for a <code class="type">serial</code> column is
+ automatically dropped when the owning column is dropped.
+ You can drop the sequence without dropping the column, but this
+ will force removal of the column default expression.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype.html" title="Chapter 8. Data Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-money.html" title="8.2. Monetary Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. Data Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.2. Monetary Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-oid.html b/doc/src/sgml/html/datatype-oid.html
new file mode 100644
index 0000000..8e20ff7
--- /dev/null
+++ b/doc/src/sgml/html/datatype-oid.html
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.19. Object Identifier Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="domains.html" title="8.18. Domain Types" /><link rel="next" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.19. Object Identifier Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="domains.html" title="8.18. Domain Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-OID"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.19. Object Identifier Types</h2></div></div></div><a id="id-1.5.7.27.2" class="indexterm"></a><a id="id-1.5.7.27.3" class="indexterm"></a><a id="id-1.5.7.27.4" class="indexterm"></a><a id="id-1.5.7.27.5" class="indexterm"></a><a id="id-1.5.7.27.6" class="indexterm"></a><a id="id-1.5.7.27.7" class="indexterm"></a><a id="id-1.5.7.27.8" class="indexterm"></a><a id="id-1.5.7.27.9" class="indexterm"></a><a id="id-1.5.7.27.10" class="indexterm"></a><a id="id-1.5.7.27.11" class="indexterm"></a><a id="id-1.5.7.27.12" class="indexterm"></a><a id="id-1.5.7.27.13" class="indexterm"></a><a id="id-1.5.7.27.14" class="indexterm"></a><a id="id-1.5.7.27.15" class="indexterm"></a><a id="id-1.5.7.27.16" class="indexterm"></a><a id="id-1.5.7.27.17" class="indexterm"></a><a id="id-1.5.7.27.18" class="indexterm"></a><p>
+ Object identifiers (OIDs) are used internally by
+ <span class="productname">PostgreSQL</span> as primary keys for various
+ system tables.
+ Type <code class="type">oid</code> represents an object identifier. There are also
+ several alias types for <code class="type">oid</code>, each
+ named <code class="type">reg<em class="replaceable"><code>something</code></em></code>.
+ <a class="xref" href="datatype-oid.html#DATATYPE-OID-TABLE" title="Table 8.26. Object Identifier Types">Table 8.26</a> shows an
+ overview.
+ </p><p>
+ The <code class="type">oid</code> type is currently implemented as an unsigned
+ four-byte integer. Therefore, it is not large enough to provide
+ database-wide uniqueness in large databases, or even in large
+ individual tables.
+ </p><p>
+ The <code class="type">oid</code> type itself has few operations beyond comparison.
+ It can be cast to integer, however, and then manipulated using the
+ standard integer operators. (Beware of possible
+ signed-versus-unsigned confusion if you do this.)
+ </p><p>
+ The OID alias types have no operations of their own except
+ for specialized input and output routines. These routines are able
+ to accept and display symbolic names for system objects, rather than
+ the raw numeric value that type <code class="type">oid</code> would use. The alias
+ types allow simplified lookup of OID values for objects. For example,
+ to examine the <code class="structname">pg_attribute</code> rows related to a table
+ <code class="literal">mytable</code>, one could write:
+</p><pre class="programlisting">
+SELECT * FROM pg_attribute WHERE attrelid = 'mytable'::regclass;
+</pre><p>
+ rather than:
+</p><pre class="programlisting">
+SELECT * FROM pg_attribute
+ WHERE attrelid = (SELECT oid FROM pg_class WHERE relname = 'mytable');
+</pre><p>
+ While that doesn't look all that bad by itself, it's still oversimplified.
+ A far more complicated sub-select would be needed to
+ select the right OID if there are multiple tables named
+ <code class="literal">mytable</code> in different schemas.
+ The <code class="type">regclass</code> input converter handles the table lookup according
+ to the schema path setting, and so it does the <span class="quote">“<span class="quote">right thing</span>”</span>
+ automatically. Similarly, casting a table's OID to
+ <code class="type">regclass</code> is handy for symbolic display of a numeric OID.
+ </p><div class="table" id="DATATYPE-OID-TABLE"><p class="title"><strong>Table 8.26. Object Identifier Types</strong></p><div class="table-contents"><table class="table" summary="Object Identifier Types" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>References</th><th>Description</th><th>Value Example</th></tr></thead><tbody><tr><td><code class="type">oid</code></td><td>any</td><td>numeric object identifier</td><td><code class="literal">564182</code></td></tr><tr><td><code class="type">regclass</code></td><td><code class="structname">pg_class</code></td><td>relation name</td><td><code class="literal">pg_type</code></td></tr><tr><td><code class="type">regcollation</code></td><td><code class="structname">pg_collation</code></td><td>collation name</td><td><code class="literal">"POSIX"</code></td></tr><tr><td><code class="type">regconfig</code></td><td><code class="structname">pg_ts_config</code></td><td>text search configuration</td><td><code class="literal">english</code></td></tr><tr><td><code class="type">regdictionary</code></td><td><code class="structname">pg_ts_dict</code></td><td>text search dictionary</td><td><code class="literal">simple</code></td></tr><tr><td><code class="type">regnamespace</code></td><td><code class="structname">pg_namespace</code></td><td>namespace name</td><td><code class="literal">pg_catalog</code></td></tr><tr><td><code class="type">regoper</code></td><td><code class="structname">pg_operator</code></td><td>operator name</td><td><code class="literal">+</code></td></tr><tr><td><code class="type">regoperator</code></td><td><code class="structname">pg_operator</code></td><td>operator with argument types</td><td><code class="literal">*(integer,​integer)</code>
+ or <code class="literal">-(NONE,​integer)</code></td></tr><tr><td><code class="type">regproc</code></td><td><code class="structname">pg_proc</code></td><td>function name</td><td><code class="literal">sum</code></td></tr><tr><td><code class="type">regprocedure</code></td><td><code class="structname">pg_proc</code></td><td>function with argument types</td><td><code class="literal">sum(int4)</code></td></tr><tr><td><code class="type">regrole</code></td><td><code class="structname">pg_authid</code></td><td>role name</td><td><code class="literal">smithee</code></td></tr><tr><td><code class="type">regtype</code></td><td><code class="structname">pg_type</code></td><td>data type name</td><td><code class="literal">integer</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ All of the OID alias types for objects that are grouped by namespace
+ accept schema-qualified names, and will
+ display schema-qualified names on output if the object would not
+ be found in the current search path without being qualified.
+ For example, <code class="literal">myschema.mytable</code> is acceptable input
+ for <code class="type">regclass</code> (if there is such a table). That value
+ might be output as <code class="literal">myschema.mytable</code>, or
+ just <code class="literal">mytable</code>, depending on the current search path.
+ The <code class="type">regproc</code> and <code class="type">regoper</code> alias types will only
+ accept input names that are unique (not overloaded), so they are
+ of limited use; for most uses <code class="type">regprocedure</code> or
+ <code class="type">regoperator</code> are more appropriate. For <code class="type">regoperator</code>,
+ unary operators are identified by writing <code class="literal">NONE</code> for the unused
+ operand.
+ </p><p>
+ The input functions for these types allow whitespace between tokens,
+ and will fold upper-case letters to lower case, except within double
+ quotes; this is done to make the syntax rules similar to the way
+ object names are written in SQL. Conversely, the output functions
+ will use double quotes if needed to make the output be a valid SQL
+ identifier. For example, the OID of a function
+ named <code class="literal">Foo</code> (with upper case <code class="literal">F</code>)
+ taking two integer arguments could be entered as
+ <code class="literal">' "Foo" ( int, integer ) '::regprocedure</code>. The
+ output would look like <code class="literal">"Foo"(integer,integer)</code>.
+ Both the function name and the argument type names could be
+ schema-qualified, too.
+ </p><p>
+ Many built-in <span class="productname">PostgreSQL</span> functions accept
+ the OID of a table, or another kind of database object, and for
+ convenience are declared as taking <code class="type">regclass</code> (or the
+ appropriate OID alias type). This means you do not have to look up
+ the object's OID by hand, but can just enter its name as a string
+ literal. For example, the <code class="function">nextval(regclass)</code> function
+ takes a sequence relation's OID, so you could call it like this:
+</p><pre class="programlisting">
+nextval('foo') <em class="lineannotation"><span class="lineannotation">operates on sequence <code class="literal">foo</code></span></em>
+nextval('FOO') <em class="lineannotation"><span class="lineannotation">same as above</span></em>
+nextval('"Foo"') <em class="lineannotation"><span class="lineannotation">operates on sequence <code class="literal">Foo</code></span></em>
+nextval('myschema.foo') <em class="lineannotation"><span class="lineannotation">operates on <code class="literal">myschema.foo</code></span></em>
+nextval('"myschema".foo') <em class="lineannotation"><span class="lineannotation">same as above</span></em>
+nextval('foo') <em class="lineannotation"><span class="lineannotation">searches search path for <code class="literal">foo</code></span></em>
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When you write the argument of such a function as an unadorned
+ literal string, it becomes a constant of type <code class="type">regclass</code>
+ (or the appropriate type).
+ Since this is really just an OID, it will track the originally
+ identified object despite later renaming, schema reassignment,
+ etc. This <span class="quote">“<span class="quote">early binding</span>”</span> behavior is usually desirable for
+ object references in column defaults and views. But sometimes you might
+ want <span class="quote">“<span class="quote">late binding</span>”</span> where the object reference is resolved
+ at run time. To get late-binding behavior, force the constant to be
+ stored as a <code class="type">text</code> constant instead of <code class="type">regclass</code>:
+</p><pre class="programlisting">
+nextval('foo'::text) <em class="lineannotation"><span class="lineannotation"><code class="literal">foo</code> is looked up at runtime</span></em>
+</pre><p>
+ The <code class="function">to_regclass()</code> function and its siblings
+ can also be used to perform run-time lookups. See
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-CATALOG-TABLE" title="Table 9.71. System Catalog Information Functions">Table 9.71</a>.
+ </p></div><p>
+ Another practical example of use of <code class="type">regclass</code>
+ is to look up the OID of a table listed in
+ the <code class="literal">information_schema</code> views, which don't supply
+ such OIDs directly. One might for example wish to call
+ the <code class="function">pg_relation_size()</code> function, which requires
+ the table OID. Taking the above rules into account, the correct way
+ to do that is
+</p><pre class="programlisting">
+SELECT table_schema, table_name,
+ pg_relation_size((quote_ident(table_schema) || '.' ||
+ quote_ident(table_name))::regclass)
+FROM information_schema.tables
+WHERE ...
+</pre><p>
+ The <code class="function">quote_ident()</code> function will take care of
+ double-quoting the identifiers where needed. The seemingly easier
+</p><pre class="programlisting">
+SELECT pg_relation_size(table_name)
+FROM information_schema.tables
+WHERE ...
+</pre><p>
+ is <span class="emphasis"><em>not recommended</em></span>, because it will fail for
+ tables that are outside your search path or have names that require
+ quoting.
+ </p><p>
+ An additional property of most of the OID alias types is the creation of
+ dependencies. If a
+ constant of one of these types appears in a stored expression
+ (such as a column default expression or view), it creates a dependency
+ on the referenced object. For example, if a column has a default
+ expression <code class="literal">nextval('my_seq'::regclass)</code>,
+ <span class="productname">PostgreSQL</span>
+ understands that the default expression depends on the sequence
+ <code class="literal">my_seq</code>, so the system will not let the sequence
+ be dropped without first removing the default expression. The
+ alternative of <code class="literal">nextval('my_seq'::text)</code> does not
+ create a dependency.
+ (<code class="type">regrole</code> is an exception to this property. Constants of this
+ type are not allowed in stored expressions.)
+ </p><p>
+ Another identifier type used by the system is <code class="type">xid</code>, or transaction
+ (abbreviated <abbr class="abbrev">xact</abbr>) identifier. This is the data type of the system columns
+ <code class="structfield">xmin</code> and <code class="structfield">xmax</code>. Transaction identifiers are 32-bit quantities.
+ In some contexts, a 64-bit variant <code class="type">xid8</code> is used. Unlike
+ <code class="type">xid</code> values, <code class="type">xid8</code> values increase strictly
+ monotonically and cannot be reused in the lifetime of a database cluster.
+ </p><p>
+ A third identifier type used by the system is <code class="type">cid</code>, or
+ command identifier. This is the data type of the system columns
+ <code class="structfield">cmin</code> and <code class="structfield">cmax</code>. Command identifiers are also 32-bit quantities.
+ </p><p>
+ A final identifier type used by the system is <code class="type">tid</code>, or tuple
+ identifier (row identifier). This is the data type of the system column
+ <code class="structfield">ctid</code>. A tuple ID is a pair
+ (block number, tuple index within block) that identifies the
+ physical location of the row within its table.
+ </p><p>
+ (The system columns are further explained in <a class="xref" href="ddl-system-columns.html" title="5.5. System Columns">Section 5.5</a>.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="domains.html" title="8.18. Domain Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.18. Domain Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.20. <code class="type">pg_lsn</code> Type</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-pg-lsn.html b/doc/src/sgml/html/datatype-pg-lsn.html
new file mode 100644
index 0000000..ba8fa84
--- /dev/null
+++ b/doc/src/sgml/html/datatype-pg-lsn.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.20. pg_lsn Type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-oid.html" title="8.19. Object Identifier Types" /><link rel="next" href="datatype-pseudo.html" title="8.21. Pseudo-Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.20. <code class="type">pg_lsn</code> Type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-oid.html" title="8.19. Object Identifier Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-pseudo.html" title="8.21. Pseudo-Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-PG-LSN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.20. <code class="type">pg_lsn</code> Type</h2></div></div></div><a id="id-1.5.7.28.2" class="indexterm"></a><p>
+ The <code class="type">pg_lsn</code> data type can be used to store LSN (Log Sequence
+ Number) data which is a pointer to a location in the WAL. This type is a
+ representation of <code class="type">XLogRecPtr</code> and an internal system type of
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ Internally, an LSN is a 64-bit integer, representing a byte position in
+ the write-ahead log stream. It is printed as two hexadecimal numbers of
+ up to 8 digits each, separated by a slash; for example,
+ <code class="literal">16/B374D848</code>. The <code class="type">pg_lsn</code> type supports the
+ standard comparison operators, like <code class="literal">=</code> and
+ <code class="literal">&gt;</code>. Two LSNs can be subtracted using the
+ <code class="literal">-</code> operator; the result is the number of bytes separating
+ those write-ahead log locations. Also the number of bytes can be
+ added into and subtracted from LSN using the
+ <code class="literal">+(pg_lsn,numeric)</code> and
+ <code class="literal">-(pg_lsn,numeric)</code> operators, respectively. Note that
+ the calculated LSN should be in the range of <code class="type">pg_lsn</code> type,
+ i.e., between <code class="literal">0/0</code> and
+ <code class="literal">FFFFFFFF/FFFFFFFF</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-oid.html" title="8.19. Object Identifier Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-pseudo.html" title="8.21. Pseudo-Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.19. Object Identifier Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.21. Pseudo-Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-pseudo.html b/doc/src/sgml/html/datatype-pseudo.html
new file mode 100644
index 0000000..6c24833
--- /dev/null
+++ b/doc/src/sgml/html/datatype-pseudo.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.21. Pseudo-Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type" /><link rel="next" href="functions.html" title="Chapter 9. Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.21. Pseudo-Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions.html" title="Chapter 9. Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-PSEUDO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.21. Pseudo-Types</h2></div></div></div><a id="id-1.5.7.29.2" class="indexterm"></a><a id="id-1.5.7.29.3" class="indexterm"></a><a id="id-1.5.7.29.4" class="indexterm"></a><a id="id-1.5.7.29.5" class="indexterm"></a><a id="id-1.5.7.29.6" class="indexterm"></a><a id="id-1.5.7.29.7" class="indexterm"></a><a id="id-1.5.7.29.8" class="indexterm"></a><a id="id-1.5.7.29.9" class="indexterm"></a><a id="id-1.5.7.29.10" class="indexterm"></a><a id="id-1.5.7.29.11" class="indexterm"></a><a id="id-1.5.7.29.12" class="indexterm"></a><a id="id-1.5.7.29.13" class="indexterm"></a><a id="id-1.5.7.29.14" class="indexterm"></a><a id="id-1.5.7.29.15" class="indexterm"></a><a id="id-1.5.7.29.16" class="indexterm"></a><a id="id-1.5.7.29.17" class="indexterm"></a><a id="id-1.5.7.29.18" class="indexterm"></a><a id="id-1.5.7.29.19" class="indexterm"></a><a id="id-1.5.7.29.20" class="indexterm"></a><a id="id-1.5.7.29.21" class="indexterm"></a><a id="id-1.5.7.29.22" class="indexterm"></a><a id="id-1.5.7.29.23" class="indexterm"></a><a id="id-1.5.7.29.24" class="indexterm"></a><a id="id-1.5.7.29.25" class="indexterm"></a><a id="id-1.5.7.29.26" class="indexterm"></a><p>
+ The <span class="productname">PostgreSQL</span> type system contains a
+ number of special-purpose entries that are collectively called
+ <em class="firstterm">pseudo-types</em>. A pseudo-type cannot be used as a
+ column data type, but it can be used to declare a function's
+ argument or result type. Each of the available pseudo-types is
+ useful in situations where a function's behavior does not
+ correspond to simply taking or returning a value of a specific
+ <acronym class="acronym">SQL</acronym> data type. <a class="xref" href="datatype-pseudo.html#DATATYPE-PSEUDOTYPES-TABLE" title="Table 8.27. Pseudo-Types">Table 8.27</a> lists the existing
+ pseudo-types.
+ </p><div class="table" id="DATATYPE-PSEUDOTYPES-TABLE"><p class="title"><strong>Table 8.27. Pseudo-Types</strong></p><div class="table-contents"><table class="table" summary="Pseudo-Types" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">any</code></td><td>Indicates that a function accepts any input data type.</td></tr><tr><td><code class="type">anyelement</code></td><td>Indicates that a function accepts any data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anyarray</code></td><td>Indicates that a function accepts any array data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anynonarray</code></td><td>Indicates that a function accepts any non-array data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anyenum</code></td><td>Indicates that a function accepts any enum data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a> and
+ <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a>).</td></tr><tr><td><code class="type">anyrange</code></td><td>Indicates that a function accepts any range data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a> and
+ <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>).</td></tr><tr><td><code class="type">anymultirange</code></td><td>Indicates that a function accepts any multirange data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a> and
+ <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>).</td></tr><tr><td><code class="type">anycompatible</code></td><td>Indicates that a function accepts any data type,
+ with automatic promotion of multiple arguments to a common data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anycompatiblearray</code></td><td>Indicates that a function accepts any array data type,
+ with automatic promotion of multiple arguments to a common data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anycompatiblenonarray</code></td><td>Indicates that a function accepts any non-array data type,
+ with automatic promotion of multiple arguments to a common data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>).</td></tr><tr><td><code class="type">anycompatiblerange</code></td><td>Indicates that a function accepts any range data type,
+ with automatic promotion of multiple arguments to a common data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a> and
+ <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>).</td></tr><tr><td><code class="type">anycompatiblemultirange</code></td><td>Indicates that a function accepts any multirange data type,
+ with automatic promotion of multiple arguments to a common data type
+ (see <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a> and
+ <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>).</td></tr><tr><td><code class="type">cstring</code></td><td>Indicates that a function accepts or returns a null-terminated C string.</td></tr><tr><td><code class="type">internal</code></td><td>Indicates that a function accepts or returns a server-internal
+ data type.</td></tr><tr><td><code class="type">language_handler</code></td><td>A procedural language call handler is declared to return <code class="type">language_handler</code>.</td></tr><tr><td><code class="type">fdw_handler</code></td><td>A foreign-data wrapper handler is declared to return <code class="type">fdw_handler</code>.</td></tr><tr><td><code class="type">table_am_handler</code></td><td>A table access method handler is declared to return <code class="type">table_am_handler</code>.</td></tr><tr><td><code class="type">index_am_handler</code></td><td>An index access method handler is declared to return <code class="type">index_am_handler</code>.</td></tr><tr><td><code class="type">tsm_handler</code></td><td>A tablesample method handler is declared to return <code class="type">tsm_handler</code>.</td></tr><tr><td><code class="type">record</code></td><td>Identifies a function taking or returning an unspecified row type.</td></tr><tr><td><code class="type">trigger</code></td><td>A trigger function is declared to return <code class="type">trigger.</code></td></tr><tr><td><code class="type">event_trigger</code></td><td>An event trigger function is declared to return <code class="type">event_trigger.</code></td></tr><tr><td><code class="type">pg_ddl_command</code></td><td>Identifies a representation of DDL commands that is available to event triggers.</td></tr><tr><td><code class="type">void</code></td><td>Indicates that a function returns no value.</td></tr><tr><td><code class="type">unknown</code></td><td>Identifies a not-yet-resolved type, e.g., of an undecorated
+ string literal.</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Functions coded in C (whether built-in or dynamically loaded) can be
+ declared to accept or return any of these pseudo-types. It is up to
+ the function author to ensure that the function will behave safely
+ when a pseudo-type is used as an argument type.
+ </p><p>
+ Functions coded in procedural languages can use pseudo-types only as
+ allowed by their implementation languages. At present most procedural
+ languages forbid use of a pseudo-type as an argument type, and allow
+ only <code class="type">void</code> and <code class="type">record</code> as a result type (plus
+ <code class="type">trigger</code> or <code class="type">event_trigger</code> when the function is used
+ as a trigger or event trigger). Some also support polymorphic functions
+ using the polymorphic pseudo-types, which are shown above and discussed
+ in detail in <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>.
+ </p><p>
+ The <code class="type">internal</code> pseudo-type is used to declare functions
+ that are meant only to be called internally by the database
+ system, and not by direct invocation in an <acronym class="acronym">SQL</acronym>
+ query. If a function has at least one <code class="type">internal</code>-type
+ argument then it cannot be called from <acronym class="acronym">SQL</acronym>. To
+ preserve the type safety of this restriction it is important to
+ follow this coding rule: do not create any function that is
+ declared to return <code class="type">internal</code> unless it has at least one
+ <code class="type">internal</code> argument.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions.html" title="Chapter 9. Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.20. <code class="type">pg_lsn</code> Type </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9. Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-textsearch.html b/doc/src/sgml/html/datatype-textsearch.html
new file mode 100644
index 0000000..2f4e4a9
--- /dev/null
+++ b/doc/src/sgml/html/datatype-textsearch.html
@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.11. Text Search Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-bit.html" title="8.10. Bit String Types" /><link rel="next" href="datatype-uuid.html" title="8.12. UUID Type" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.11. Text Search Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-bit.html" title="8.10. Bit String Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-uuid.html" title="8.12. UUID Type">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-TEXTSEARCH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.11. Text Search Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-textsearch.html#DATATYPE-TSVECTOR">8.11.1. <code class="type">tsvector</code></a></span></dt><dt><span class="sect2"><a href="datatype-textsearch.html#DATATYPE-TSQUERY">8.11.2. <code class="type">tsquery</code></a></span></dt></dl></div><a id="id-1.5.7.19.2" class="indexterm"></a><a id="id-1.5.7.19.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides two data types that
+ are designed to support full text search, which is the activity of
+ searching through a collection of natural-language <em class="firstterm">documents</em>
+ to locate those that best match a <em class="firstterm">query</em>.
+ The <code class="type">tsvector</code> type represents a document in a form optimized
+ for text search; the <code class="type">tsquery</code> type similarly represents
+ a text query.
+ <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> provides a detailed explanation of this
+ facility, and <a class="xref" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Section 9.13</a> summarizes the
+ related functions and operators.
+ </p><div class="sect2" id="DATATYPE-TSVECTOR"><div class="titlepage"><div><div><h3 class="title">8.11.1. <code class="type">tsvector</code></h3></div></div></div><a id="id-1.5.7.19.5.2" class="indexterm"></a><p>
+ A <code class="type">tsvector</code> value is a sorted list of distinct
+ <em class="firstterm">lexemes</em>, which are words that have been
+ <em class="firstterm">normalized</em> to merge different variants of the same word
+ (see <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for details). Sorting and
+ duplicate-elimination are done automatically during input, as shown in
+ this example:
+
+</p><pre class="programlisting">
+SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector;
+ tsvector
+----------------------------------------------------
+ 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat'
+</pre><p>
+
+ To represent
+ lexemes containing whitespace or punctuation, surround them with quotes:
+
+</p><pre class="programlisting">
+SELECT $$the lexeme ' ' contains spaces$$::tsvector;
+ tsvector
+-------------------------------------------
+ ' ' 'contains' 'lexeme' 'spaces' 'the'
+</pre><p>
+
+ (We use dollar-quoted string literals in this example and the next one
+ to avoid the confusion of having to double quote marks within the
+ literals.) Embedded quotes and backslashes must be doubled:
+
+</p><pre class="programlisting">
+SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector;
+ tsvector
+------------------------------------------------
+ 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the'
+</pre><p>
+
+ Optionally, integer <em class="firstterm">positions</em>
+ can be attached to lexemes:
+
+</p><pre class="programlisting">
+SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector;
+ tsvector
+-------------------------------------------------------------------​------------
+ 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4
+</pre><p>
+
+ A position normally indicates the source word's location in the
+ document. Positional information can be used for
+ <em class="firstterm">proximity ranking</em>. Position values can
+ range from 1 to 16383; larger numbers are silently set to 16383.
+ Duplicate positions for the same lexeme are discarded.
+ </p><p>
+ Lexemes that have positions can further be labeled with a
+ <em class="firstterm">weight</em>, which can be <code class="literal">A</code>,
+ <code class="literal">B</code>, <code class="literal">C</code>, or <code class="literal">D</code>.
+ <code class="literal">D</code> is the default and hence is not shown on output:
+
+</p><pre class="programlisting">
+SELECT 'a:1A fat:2B,4C cat:5D'::tsvector;
+ tsvector
+----------------------------
+ 'a':1A 'cat':5 'fat':2B,4C
+</pre><p>
+
+ Weights are typically used to reflect document structure, for example
+ by marking title words differently from body words. Text search
+ ranking functions can assign different priorities to the different
+ weight markers.
+ </p><p>
+ It is important to understand that the
+ <code class="type">tsvector</code> type itself does not perform any word
+ normalization; it assumes the words it is given are normalized
+ appropriately for the application. For example,
+
+</p><pre class="programlisting">
+SELECT 'The Fat Rats'::tsvector;
+ tsvector
+--------------------
+ 'Fat' 'Rats' 'The'
+</pre><p>
+
+ For most English-text-searching applications the above words would
+ be considered non-normalized, but <code class="type">tsvector</code> doesn't care.
+ Raw document text should usually be passed through
+ <code class="function">to_tsvector</code> to normalize the words appropriately
+ for searching:
+
+</p><pre class="programlisting">
+SELECT to_tsvector('english', 'The Fat Rats');
+ to_tsvector
+-----------------
+ 'fat':2 'rat':3
+</pre><p>
+
+ Again, see <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for more detail.
+ </p></div><div class="sect2" id="DATATYPE-TSQUERY"><div class="titlepage"><div><div><h3 class="title">8.11.2. <code class="type">tsquery</code></h3></div></div></div><a id="id-1.5.7.19.6.2" class="indexterm"></a><p>
+ A <code class="type">tsquery</code> value stores lexemes that are to be
+ searched for, and can combine them using the Boolean operators
+ <code class="literal">&amp;</code> (AND), <code class="literal">|</code> (OR), and
+ <code class="literal">!</code> (NOT), as well as the phrase search operator
+ <code class="literal">&lt;-&gt;</code> (FOLLOWED BY). There is also a variant
+ <code class="literal">&lt;<em class="replaceable"><code>N</code></em>&gt;</code> of the FOLLOWED BY
+ operator, where <em class="replaceable"><code>N</code></em> is an integer constant that
+ specifies the distance between the two lexemes being searched
+ for. <code class="literal">&lt;-&gt;</code> is equivalent to <code class="literal">&lt;1&gt;</code>.
+ </p><p>
+ Parentheses can be used to enforce grouping of these operators.
+ In the absence of parentheses, <code class="literal">!</code> (NOT) binds most tightly,
+ <code class="literal">&lt;-&gt;</code> (FOLLOWED BY) next most tightly, then
+ <code class="literal">&amp;</code> (AND), with <code class="literal">|</code> (OR) binding
+ the least tightly.
+ </p><p>
+ Here are some examples:
+
+</p><pre class="programlisting">
+SELECT 'fat &amp; rat'::tsquery;
+ tsquery
+---------------
+ 'fat' &amp; 'rat'
+
+SELECT 'fat &amp; (rat | cat)'::tsquery;
+ tsquery
+---------------------------
+ 'fat' &amp; ( 'rat' | 'cat' )
+
+SELECT 'fat &amp; rat &amp; ! cat'::tsquery;
+ tsquery
+------------------------
+ 'fat' &amp; 'rat' &amp; !'cat'
+</pre><p>
+ </p><p>
+ Optionally, lexemes in a <code class="type">tsquery</code> can be labeled with
+ one or more weight letters, which restricts them to match only
+ <code class="type">tsvector</code> lexemes with one of those weights:
+
+</p><pre class="programlisting">
+SELECT 'fat:ab &amp; cat'::tsquery;
+ tsquery
+------------------
+ 'fat':AB &amp; 'cat'
+</pre><p>
+ </p><p>
+ Also, lexemes in a <code class="type">tsquery</code> can be labeled with <code class="literal">*</code>
+ to specify prefix matching:
+</p><pre class="programlisting">
+SELECT 'super:*'::tsquery;
+ tsquery
+-----------
+ 'super':*
+</pre><p>
+ This query will match any word in a <code class="type">tsvector</code> that begins
+ with <span class="quote">“<span class="quote">super</span>”</span>.
+ </p><p>
+ Quoting rules for lexemes are the same as described previously for
+ lexemes in <code class="type">tsvector</code>; and, as with <code class="type">tsvector</code>,
+ any required normalization of words must be done before converting
+ to the <code class="type">tsquery</code> type. The <code class="function">to_tsquery</code>
+ function is convenient for performing such normalization:
+
+</p><pre class="programlisting">
+SELECT to_tsquery('Fat:ab &amp; Cats');
+ to_tsquery
+------------------
+ 'fat':AB &amp; 'cat'
+</pre><p>
+
+ Note that <code class="function">to_tsquery</code> will process prefixes in the same way
+ as other words, which means this comparison returns true:
+
+</p><pre class="programlisting">
+SELECT to_tsvector( 'postgraduate' ) @@ to_tsquery( 'postgres:*' );
+ ?column?
+----------
+ t
+</pre><p>
+ because <code class="literal">postgres</code> gets stemmed to <code class="literal">postgr</code>:
+</p><pre class="programlisting">
+SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
+ to_tsvector | to_tsquery
+---------------+------------
+ 'postgradu':1 | 'postgr':*
+</pre><p>
+ which will match the stemmed form of <code class="literal">postgraduate</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-bit.html" title="8.10. Bit String Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-uuid.html" title="8.12. UUID Type">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.10. Bit String Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.12. <acronym class="acronym">UUID</acronym> Type</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-uuid.html b/doc/src/sgml/html/datatype-uuid.html
new file mode 100644
index 0000000..63b2e43
--- /dev/null
+++ b/doc/src/sgml/html/datatype-uuid.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.12. UUID Type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-textsearch.html" title="8.11. Text Search Types" /><link rel="next" href="datatype-xml.html" title="8.13. XML Type" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.12. <acronym class="acronym">UUID</acronym> Type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-textsearch.html" title="8.11. Text Search Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-xml.html" title="8.13. XML Type">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-UUID"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.12. <acronym class="acronym">UUID</acronym> Type</h2></div></div></div><a id="id-1.5.7.20.2" class="indexterm"></a><p>
+ The data type <code class="type">uuid</code> stores Universally Unique Identifiers
+ (UUID) as defined by <a class="ulink" href="https://tools.ietf.org/html/rfc4122" target="_top">RFC 4122</a>,
+ ISO/IEC 9834-8:2005, and related standards.
+ (Some systems refer to this data type as a globally unique identifier, or
+ GUID,<a id="id-1.5.7.20.3.3" class="indexterm"></a> instead.) This
+ identifier is a 128-bit quantity that is generated by an algorithm chosen
+ to make it very unlikely that the same identifier will be generated by
+ anyone else in the known universe using the same algorithm. Therefore,
+ for distributed systems, these identifiers provide a better uniqueness
+ guarantee than sequence generators, which
+ are only unique within a single database.
+ </p><p>
+ A UUID is written as a sequence of lower-case hexadecimal digits,
+ in several groups separated by hyphens, specifically a group of 8
+ digits followed by three groups of 4 digits followed by a group of
+ 12 digits, for a total of 32 digits representing the 128 bits. An
+ example of a UUID in this standard form is:
+</p><pre class="programlisting">
+a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
+</pre><p>
+ <span class="productname">PostgreSQL</span> also accepts the following
+ alternative forms for input:
+ use of upper-case digits, the standard format surrounded by
+ braces, omitting some or all hyphens, adding a hyphen after any
+ group of four digits. Examples are:
+</p><pre class="programlisting">
+A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
+{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}
+a0eebc999c0b4ef8bb6d6bb9bd380a11
+a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
+{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}
+</pre><p>
+ Output is always in the standard form.
+ </p><p>
+ See <a class="xref" href="functions-uuid.html" title="9.14. UUID Functions">Section 9.14</a> for how to generate a UUID in
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-textsearch.html" title="8.11. Text Search Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-xml.html" title="8.13. XML Type">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.11. Text Search Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.13. <acronym class="acronym">XML</acronym> Type</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype-xml.html b/doc/src/sgml/html/datatype-xml.html
new file mode 100644
index 0000000..4acc1c6
--- /dev/null
+++ b/doc/src/sgml/html/datatype-xml.html
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.13. XML Type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-uuid.html" title="8.12. UUID Type" /><link rel="next" href="datatype-json.html" title="8.14. JSON Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.13. <acronym class="acronym">XML</acronym> Type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-uuid.html" title="8.12. UUID Type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-json.html" title="8.14. JSON Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.13. <acronym class="acronym">XML</acronym> Type</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.6">8.13.1. Creating XML Values</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.7">8.13.2. Encoding Handling</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.8">8.13.3. Accessing XML Values</a></span></dt></dl></div><a id="id-1.5.7.21.2" class="indexterm"></a><p>
+ The <code class="type">xml</code> data type can be used to store XML data. Its
+ advantage over storing XML data in a <code class="type">text</code> field is that it
+ checks the input values for well-formedness, and there are support
+ functions to perform type-safe operations on it; see <a class="xref" href="functions-xml.html" title="9.15. XML Functions">Section 9.15</a>. Use of this data type requires the
+ installation to have been built with <code class="command">configure
+ --with-libxml</code>.
+ </p><p>
+ The <code class="type">xml</code> type can store well-formed
+ <span class="quote">“<span class="quote">documents</span>”</span>, as defined by the XML standard, as well
+ as <span class="quote">“<span class="quote">content</span>”</span> fragments, which are defined by reference
+ to the more permissive
+ <a class="ulink" href="https://www.w3.org/TR/2010/REC-xpath-datamodel-20101214/#DocumentNode" target="_top"><span class="quote">“<span class="quote">document node</span>”</span></a>
+ of the XQuery and XPath data model.
+ Roughly, this means that content fragments can have
+ more than one top-level element or character node. The expression
+ <code class="literal"><em class="replaceable"><code>xmlvalue</code></em> IS DOCUMENT</code>
+ can be used to evaluate whether a particular <code class="type">xml</code>
+ value is a full document or only a content fragment.
+ </p><p>
+ Limits and compatibility notes for the <code class="type">xml</code> data type
+ can be found in <a class="xref" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Section D.3</a>.
+ </p><div class="sect2" id="id-1.5.7.21.6"><div class="titlepage"><div><div><h3 class="title">8.13.1. Creating XML Values</h3></div></div></div><p>
+ To produce a value of type <code class="type">xml</code> from character data,
+ use the function
+ <code class="function">xmlparse</code>:<a id="id-1.5.7.21.6.2.3" class="indexterm"></a>
+</p><pre class="synopsis">
+XMLPARSE ( { DOCUMENT | CONTENT } <em class="replaceable"><code>value</code></em>)
+</pre><p>
+ Examples:
+</p><pre class="programlisting">
+XMLPARSE (DOCUMENT '&lt;?xml version="1.0"?&gt;&lt;book&gt;&lt;title&gt;Manual&lt;/title&gt;&lt;chapter&gt;...&lt;/chapter&gt;&lt;/book&gt;')
+XMLPARSE (CONTENT 'abc&lt;foo&gt;bar&lt;/foo&gt;&lt;bar&gt;foo&lt;/bar&gt;')
+</pre><p>
+ While this is the only way to convert character strings into XML
+ values according to the SQL standard, the PostgreSQL-specific
+ syntaxes:
+</p><pre class="programlisting">
+xml '&lt;foo&gt;bar&lt;/foo&gt;'
+'&lt;foo&gt;bar&lt;/foo&gt;'::xml
+</pre><p>
+ can also be used.
+ </p><p>
+ The <code class="type">xml</code> type does not validate input values
+ against a document type declaration
+ (DTD),<a id="id-1.5.7.21.6.3.2" class="indexterm"></a>
+ even when the input value specifies a DTD.
+ There is also currently no built-in support for validating against
+ other XML schema languages such as XML Schema.
+ </p><p>
+ The inverse operation, producing a character string value from
+ <code class="type">xml</code>, uses the function
+ <code class="function">xmlserialize</code>:<a id="id-1.5.7.21.6.4.3" class="indexterm"></a>
+</p><pre class="synopsis">
+XMLSERIALIZE ( { DOCUMENT | CONTENT } <em class="replaceable"><code>value</code></em> AS <em class="replaceable"><code>type</code></em> )
+</pre><p>
+ <em class="replaceable"><code>type</code></em> can be
+ <code class="type">character</code>, <code class="type">character varying</code>, or
+ <code class="type">text</code> (or an alias for one of those). Again, according
+ to the SQL standard, this is the only way to convert between type
+ <code class="type">xml</code> and character types, but PostgreSQL also allows
+ you to simply cast the value.
+ </p><p>
+ When a character string value is cast to or from type
+ <code class="type">xml</code> without going through <code class="type">XMLPARSE</code> or
+ <code class="type">XMLSERIALIZE</code>, respectively, the choice of
+ <code class="literal">DOCUMENT</code> versus <code class="literal">CONTENT</code> is
+ determined by the <span class="quote">“<span class="quote">XML option</span>”</span>
+ <a id="id-1.5.7.21.6.5.7" class="indexterm"></a>
+ session configuration parameter, which can be set using the
+ standard command:
+</p><pre class="synopsis">
+SET XML OPTION { DOCUMENT | CONTENT };
+</pre><p>
+ or the more PostgreSQL-like syntax
+</p><pre class="synopsis">
+SET xmloption TO { DOCUMENT | CONTENT };
+</pre><p>
+ The default is <code class="literal">CONTENT</code>, so all forms of XML
+ data are allowed.
+ </p></div><div class="sect2" id="id-1.5.7.21.7"><div class="titlepage"><div><div><h3 class="title">8.13.2. Encoding Handling</h3></div></div></div><p>
+ Care must be taken when dealing with multiple character encodings
+ on the client, server, and in the XML data passed through them.
+ When using the text mode to pass queries to the server and query
+ 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 <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>. 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
+ to other encodings while traveling between client and server,
+ because the embedded encoding declaration is not changed. To cope
+ with this behavior, encoding declarations contained in
+ character strings presented for input to the <code class="type">xml</code> type
+ are <span class="emphasis"><em>ignored</em></span>, and content is assumed
+ to be in the current server encoding. Consequently, for correct
+ processing, character strings of XML data must be sent
+ from the client in the current client encoding. It is the
+ responsibility of the client to either convert documents to the
+ current client encoding before sending them to the server, or to
+ adjust the client encoding appropriately. On output, values of
+ type <code class="type">xml</code> will not have an encoding declaration, and
+ clients should assume all data is in the current client
+ encoding.
+ </p><p>
+ When using binary mode to pass query parameters to the server
+ and query results back to the client, no encoding conversion
+ is performed, so the situation is different. In this case, an
+ encoding declaration in the XML data will be observed, and if it
+ is absent, the data will be assumed to be in UTF-8 (as required by
+ the XML standard; note that PostgreSQL does not support UTF-16).
+ On output, data will have an encoding declaration
+ specifying the client encoding, unless the client encoding is
+ UTF-8, in which case it will be omitted.
+ </p><p>
+ Needless to say, processing XML data with PostgreSQL will be less
+ error-prone and more efficient if the XML data encoding, client encoding,
+ and server encoding are the same. Since XML data is internally
+ processed in UTF-8, computations will be most efficient if the
+ server encoding is also UTF-8.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Some XML-related functions may not work at all on non-ASCII data
+ when the server encoding is not UTF-8. This is known to be an
+ issue for <code class="function">xmltable()</code> and <code class="function">xpath()</code> in particular.
+ </p></div></div><div class="sect2" id="id-1.5.7.21.8"><div class="titlepage"><div><div><h3 class="title">8.13.3. Accessing XML Values</h3></div></div></div><p>
+ The <code class="type">xml</code> data type is unusual in that it does not
+ provide any comparison operators. This is because there is no
+ well-defined and universally useful comparison algorithm for XML
+ data. One consequence of this is that you cannot retrieve rows by
+ comparing an <code class="type">xml</code> column against a search value. XML
+ values should therefore typically be accompanied by a separate key
+ field such as an ID. An alternative solution for comparing XML
+ values is to convert them to character strings first, but note
+ that character string comparison has little to do with a useful
+ XML comparison method.
+ </p><p>
+ Since there are no comparison operators for the <code class="type">xml</code>
+ data type, it is not possible to create an index directly on a
+ column of this type. If speedy searches in XML data are desired,
+ possible workarounds include casting the expression to a
+ character string type and indexing that, or indexing an XPath
+ expression. Of course, the actual query would have to be adjusted
+ to search by the indexed expression.
+ </p><p>
+ The text-search functionality in PostgreSQL can also be used to speed
+ up full-document searches of XML data. The necessary
+ preprocessing support is, however, not yet available in the PostgreSQL
+ distribution.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-uuid.html" title="8.12. UUID Type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-json.html" title="8.14. JSON Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.12. <acronym class="acronym">UUID</acronym> Type </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.14. <acronym class="acronym">JSON</acronym> Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datatype.html b/doc/src/sgml/html/datatype.html
new file mode 100644
index 0000000..a0bdb87
--- /dev/null
+++ b/doc/src/sgml/html/datatype.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 8. Data Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)" /><link rel="next" href="datatype-numeric.html" title="8.1. Numeric Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 8. Data Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-numeric.html" title="8.1. Numeric Types">Next</a></td></tr></table><hr /></div><div class="chapter" id="DATATYPE"><div class="titlepage"><div><div><h2 class="title">Chapter 8. Data Types</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="datatype-numeric.html">8.1. Numeric Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-INT">8.1.1. Integer Types</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL">8.1.2. Arbitrary Precision Numbers</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-FLOAT">8.1.3. Floating-Point Types</a></span></dt><dt><span class="sect2"><a href="datatype-numeric.html#DATATYPE-SERIAL">8.1.4. Serial Types</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-money.html">8.2. Monetary Types</a></span></dt><dt><span class="sect1"><a href="datatype-character.html">8.3. Character Types</a></span></dt><dt><span class="sect1"><a href="datatype-binary.html">8.4. Binary Data Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-binary.html#id-1.5.7.12.9">8.4.1. <code class="type">bytea</code> Hex Format</a></span></dt><dt><span class="sect2"><a href="datatype-binary.html#id-1.5.7.12.10">8.4.2. <code class="type">bytea</code> Escape Format</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-datetime.html">8.5. Date/Time Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-DATETIME-INPUT">8.5.1. Date/Time Input</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-DATETIME-OUTPUT">8.5.2. Date/Time Output</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-TIMEZONES">8.5.3. Time Zones</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-INTERVAL-INPUT">8.5.4. Interval Input</a></span></dt><dt><span class="sect2"><a href="datatype-datetime.html#DATATYPE-INTERVAL-OUTPUT">8.5.5. Interval Output</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-boolean.html">8.6. Boolean Type</a></span></dt><dt><span class="sect1"><a href="datatype-enum.html">8.7. Enumerated Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.5">8.7.1. Declaration of Enumerated Types</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.6">8.7.2. Ordering</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.7">8.7.3. Type Safety</a></span></dt><dt><span class="sect2"><a href="datatype-enum.html#id-1.5.7.15.8">8.7.4. Implementation Details</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-geometric.html">8.8. Geometric Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.5">8.8.1. Points</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-LINE">8.8.2. Lines</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-LSEG">8.8.3. Line Segments</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.8">8.8.4. Boxes</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#id-1.5.7.16.9">8.8.5. Paths</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-POLYGON">8.8.6. Polygons</a></span></dt><dt><span class="sect2"><a href="datatype-geometric.html#DATATYPE-CIRCLE">8.8.7. Circles</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-net-types.html">8.9. Network Address Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-INET">8.9.1. <code class="type">inet</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-CIDR">8.9.2. <code class="type">cidr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-INET-VS-CIDR">8.9.3. <code class="type">inet</code> vs. <code class="type">cidr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-MACADDR">8.9.4. <code class="type">macaddr</code></a></span></dt><dt><span class="sect2"><a href="datatype-net-types.html#DATATYPE-MACADDR8">8.9.5. <code class="type">macaddr8</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-bit.html">8.10. Bit String Types</a></span></dt><dt><span class="sect1"><a href="datatype-textsearch.html">8.11. Text Search Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-textsearch.html#DATATYPE-TSVECTOR">8.11.1. <code class="type">tsvector</code></a></span></dt><dt><span class="sect2"><a href="datatype-textsearch.html#DATATYPE-TSQUERY">8.11.2. <code class="type">tsquery</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-uuid.html">8.12. <acronym class="acronym">UUID</acronym> Type</a></span></dt><dt><span class="sect1"><a href="datatype-xml.html">8.13. <acronym class="acronym">XML</acronym> Type</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.6">8.13.1. Creating XML Values</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.7">8.13.2. Encoding Handling</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#id-1.5.7.21.8">8.13.3. Accessing XML Values</a></span></dt></dl></dd><dt><span class="sect1"><a href="datatype-json.html">8.14. <acronym class="acronym">JSON</acronym> Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="datatype-json.html#JSON-KEYS-ELEMENTS">8.14.1. JSON Input and Output Syntax</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-DOC-DESIGN">8.14.2. Designing JSON Documents</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-CONTAINMENT">8.14.3. <code class="type">jsonb</code> Containment and Existence</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSON-INDEXING">8.14.4. <code class="type">jsonb</code> Indexing</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#JSONB-SUBSCRIPTING">8.14.5. <code class="type">jsonb</code> Subscripting</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#id-1.5.7.22.20">8.14.6. Transforms</a></span></dt><dt><span class="sect2"><a href="datatype-json.html#DATATYPE-JSONPATH">8.14.7. jsonpath Type</a></span></dt></dl></dd><dt><span class="sect1"><a href="arrays.html">8.15. Arrays</a></span></dt><dd><dl><dt><span class="sect2"><a href="arrays.html#ARRAYS-DECLARATION">8.15.1. Declaration of Array Types</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-INPUT">8.15.2. Array Value Input</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-ACCESSING">8.15.3. Accessing Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-MODIFYING">8.15.4. Modifying Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-SEARCHING">8.15.5. Searching in Arrays</a></span></dt><dt><span class="sect2"><a href="arrays.html#ARRAYS-IO">8.15.6. Array Input and Output Syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href="rowtypes.html">8.16. Composite Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-DECLARING">8.16.1. Declaration of Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#id-1.5.7.24.6">8.16.2. Constructing Composite Values</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-ACCESSING">8.16.3. Accessing Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#id-1.5.7.24.8">8.16.4. Modifying Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-USAGE">8.16.5. Using Composite Types in Queries</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-IO-SYNTAX">8.16.6. Composite Type Input and Output Syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href="rangetypes.html">8.17. Range Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-BUILTIN">8.17.1. Built-in Range and Multirange Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-EXAMPLES">8.17.2. Examples</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INCLUSIVITY">8.17.3. Inclusive and Exclusive Bounds</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INFINITE">8.17.4. Infinite (Unbounded) Ranges</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-IO">8.17.5. Range Input/Output</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-CONSTRUCT">8.17.6. Constructing Ranges and Multiranges</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-DISCRETE">8.17.7. Discrete Range Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-DEFINING">8.17.8. Defining New Range Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INDEXING">8.17.9. Indexing</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-CONSTRAINT">8.17.10. Constraints on Ranges</a></span></dt></dl></dd><dt><span class="sect1"><a href="domains.html">8.18. Domain Types</a></span></dt><dt><span class="sect1"><a href="datatype-oid.html">8.19. Object Identifier Types</a></span></dt><dt><span class="sect1"><a href="datatype-pg-lsn.html">8.20. <code class="type">pg_lsn</code> Type</a></span></dt><dt><span class="sect1"><a href="datatype-pseudo.html">8.21. Pseudo-Types</a></span></dt></dl></div><a id="id-1.5.7.2" class="indexterm"></a><a id="id-1.5.7.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> has a rich set of native data
+ types available to users. Users can add new types to
+ <span class="productname">PostgreSQL</span> using the <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> command.
+ </p><p>
+ <a class="xref" href="datatype.html#DATATYPE-TABLE" title="Table 8.1. Data Types">Table 8.1</a> shows all the built-in general-purpose data
+ types. Most of the alternative names listed in the
+ <span class="quote">“<span class="quote">Aliases</span>”</span> column are the names used internally by
+ <span class="productname">PostgreSQL</span> for historical reasons. In
+ addition, some internally used or deprecated types are available,
+ but are not listed here.
+ </p><div class="table" id="DATATYPE-TABLE"><p class="title"><strong>Table 8.1. Data Types</strong></p><div class="table-contents"><table class="table" summary="Data Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">bigint</code></td><td><code class="type">int8</code></td><td>signed eight-byte integer</td></tr><tr><td><code class="type">bigserial</code></td><td><code class="type">serial8</code></td><td>autoincrementing eight-byte integer</td></tr><tr><td><code class="type">bit [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td> </td><td>fixed-length bit string</td></tr><tr><td><code class="type">bit varying [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td><code class="type">varbit [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td>variable-length bit string</td></tr><tr><td><code class="type">boolean</code></td><td><code class="type">bool</code></td><td>logical Boolean (true/false)</td></tr><tr><td><code class="type">box</code></td><td> </td><td>rectangular box on a plane</td></tr><tr><td><code class="type">bytea</code></td><td> </td><td>binary data (<span class="quote">“<span class="quote">byte array</span>”</span>)</td></tr><tr><td><code class="type">character [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td><code class="type">char [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td>fixed-length character string</td></tr><tr><td><code class="type">character varying [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td><code class="type">varchar [ (<em class="replaceable"><code>n</code></em>) ]</code></td><td>variable-length character string</td></tr><tr><td><code class="type">cidr</code></td><td> </td><td>IPv4 or IPv6 network address</td></tr><tr><td><code class="type">circle</code></td><td> </td><td>circle on a plane</td></tr><tr><td><code class="type">date</code></td><td> </td><td>calendar date (year, month, day)</td></tr><tr><td><code class="type">double precision</code></td><td><code class="type">float8</code></td><td>double precision floating-point number (8 bytes)</td></tr><tr><td><code class="type">inet</code></td><td> </td><td>IPv4 or IPv6 host address</td></tr><tr><td><code class="type">integer</code></td><td><code class="type">int</code>, <code class="type">int4</code></td><td>signed four-byte integer</td></tr><tr><td><code class="type">interval [ <em class="replaceable"><code>fields</code></em> ] [ (<em class="replaceable"><code>p</code></em>) ]</code></td><td> </td><td>time span</td></tr><tr><td><code class="type">json</code></td><td> </td><td>textual JSON data</td></tr><tr><td><code class="type">jsonb</code></td><td> </td><td>binary JSON data, decomposed</td></tr><tr><td><code class="type">line</code></td><td> </td><td>infinite line on a plane</td></tr><tr><td><code class="type">lseg</code></td><td> </td><td>line segment on a plane</td></tr><tr><td><code class="type">macaddr</code></td><td> </td><td>MAC (Media Access Control) address</td></tr><tr><td><code class="type">macaddr8</code></td><td> </td><td>MAC (Media Access Control) address (EUI-64 format)</td></tr><tr><td><code class="type">money</code></td><td> </td><td>currency amount</td></tr><tr><td><code class="type">numeric [ (<em class="replaceable"><code>p</code></em>,
+ <em class="replaceable"><code>s</code></em>) ]</code></td><td><code class="type">decimal [ (<em class="replaceable"><code>p</code></em>,
+ <em class="replaceable"><code>s</code></em>) ]</code></td><td>exact numeric of selectable precision</td></tr><tr><td><code class="type">path</code></td><td> </td><td>geometric path on a plane</td></tr><tr><td><code class="type">pg_lsn</code></td><td> </td><td><span class="productname">PostgreSQL</span> Log Sequence Number</td></tr><tr><td><code class="type">pg_snapshot</code></td><td> </td><td>user-level transaction ID snapshot</td></tr><tr><td><code class="type">point</code></td><td> </td><td>geometric point on a plane</td></tr><tr><td><code class="type">polygon</code></td><td> </td><td>closed geometric path on a plane</td></tr><tr><td><code class="type">real</code></td><td><code class="type">float4</code></td><td>single precision floating-point number (4 bytes)</td></tr><tr><td><code class="type">smallint</code></td><td><code class="type">int2</code></td><td>signed two-byte integer</td></tr><tr><td><code class="type">smallserial</code></td><td><code class="type">serial2</code></td><td>autoincrementing two-byte integer</td></tr><tr><td><code class="type">serial</code></td><td><code class="type">serial4</code></td><td>autoincrementing four-byte integer</td></tr><tr><td><code class="type">text</code></td><td> </td><td>variable-length character string</td></tr><tr><td><code class="type">time [ (<em class="replaceable"><code>p</code></em>) ] [ without time zone ]</code></td><td> </td><td>time of day (no time zone)</td></tr><tr><td><code class="type">time [ (<em class="replaceable"><code>p</code></em>) ] with time zone</code></td><td><code class="type">timetz</code></td><td>time of day, including time zone</td></tr><tr><td><code class="type">timestamp [ (<em class="replaceable"><code>p</code></em>) ] [ without time zone ]</code></td><td> </td><td>date and time (no time zone)</td></tr><tr><td><code class="type">timestamp [ (<em class="replaceable"><code>p</code></em>) ] with time zone</code></td><td><code class="type">timestamptz</code></td><td>date and time, including time zone</td></tr><tr><td><code class="type">tsquery</code></td><td> </td><td>text search query</td></tr><tr><td><code class="type">tsvector</code></td><td> </td><td>text search document</td></tr><tr><td><code class="type">txid_snapshot</code></td><td> </td><td>user-level transaction ID snapshot (deprecated; see <code class="type">pg_snapshot</code>)</td></tr><tr><td><code class="type">uuid</code></td><td> </td><td>universally unique identifier</td></tr><tr><td><code class="type">xml</code></td><td> </td><td>XML data</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Compatibility</h3><p>
+ The following types (or spellings thereof) are specified by
+ <acronym class="acronym">SQL</acronym>: <code class="type">bigint</code>, <code class="type">bit</code>, <code class="type">bit
+ varying</code>, <code class="type">boolean</code>, <code class="type">char</code>,
+ <code class="type">character varying</code>, <code class="type">character</code>,
+ <code class="type">varchar</code>, <code class="type">date</code>, <code class="type">double
+ precision</code>, <code class="type">integer</code>, <code class="type">interval</code>,
+ <code class="type">numeric</code>, <code class="type">decimal</code>, <code class="type">real</code>,
+ <code class="type">smallint</code>, <code class="type">time</code> (with or without time zone),
+ <code class="type">timestamp</code> (with or without time zone),
+ <code class="type">xml</code>.
+ </p></div><p>
+ Each data type has an external representation determined by its input
+ and output functions. Many of the built-in types have
+ obvious external formats. However, several types are either unique
+ to <span class="productname">PostgreSQL</span>, such as geometric
+ paths, or have several possible formats, such as the date
+ and time types.
+ Some of the input and output functions are not invertible, i.e.,
+ the result of an output function might lose accuracy when compared to
+ the original input.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-numeric.html" title="8.1. Numeric Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.8. <code class="literal">WITH</code> Queries (Common Table Expressions) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.1. Numeric Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-appendix.html b/doc/src/sgml/html/datetime-appendix.html
new file mode 100644
index 0000000..cc5651d
--- /dev/null
+++ b/doc/src/sgml/html/datetime-appendix.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix B. Date/Time Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes" /><link rel="next" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix B. Date/Time Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation">Next</a></td></tr></table><hr /></div><div class="appendix" id="DATETIME-APPENDIX"><div class="titlepage"><div><div><h2 class="title">Appendix B. Date/Time Support</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="datetime-input-rules.html">B.1. Date/Time Input Interpretation</a></span></dt><dt><span class="sect1"><a href="datetime-invalid-input.html">B.2. Handling of Invalid or Ambiguous Timestamps</a></span></dt><dt><span class="sect1"><a href="datetime-keywords.html">B.3. Date/Time Key Words</a></span></dt><dt><span class="sect1"><a href="datetime-config-files.html">B.4. Date/Time Configuration Files</a></span></dt><dt><span class="sect1"><a href="datetime-posix-timezone-specs.html">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</a></span></dt><dt><span class="sect1"><a href="datetime-units-history.html">B.6. History of Units</a></span></dt><dt><span class="sect1"><a href="datetime-julian-dates.html">B.7. Julian Dates</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> uses an internal heuristic
+ parser for all date/time input support. Dates and times are input as
+ strings, and are broken up into distinct fields with a preliminary
+ determination of what kind of information can be in the
+ field. Each field is interpreted and either assigned a numeric
+ value, ignored, or rejected.
+ The parser contains internal lookup tables for all textual fields,
+ including months, days of the week, and time zones.
+ </p><p>
+ This appendix includes information on the content of these
+ lookup tables and describes the steps used by the parser to decode
+ dates and times.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. <span class="productname">PostgreSQL</span> Error Codes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.1. Date/Time Input Interpretation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-config-files.html b/doc/src/sgml/html/datetime-config-files.html
new file mode 100644
index 0000000..b3877d3
--- /dev/null
+++ b/doc/src/sgml/html/datetime-config-files.html
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.4. Date/Time Configuration Files</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-keywords.html" title="B.3. Date/Time Key Words" /><link rel="next" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.4. Date/Time Configuration Files</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-keywords.html" title="B.3. Date/Time Key Words">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-CONFIG-FILES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.4. Date/Time Configuration Files</h2></div></div></div><a id="id-1.11.3.7.2" class="indexterm"></a><p>
+ Since timezone abbreviations are not well standardized,
+ <span class="productname">PostgreSQL</span> provides a means to customize
+ the set of abbreviations accepted by the server. The
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE-ABBREVIATIONS">timezone_abbreviations</a> 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
+ are in fact names of configuration files stored in
+ <code class="filename">.../share/timezonesets/</code> of the installation directory.
+ By adding or altering files in that directory, the administrator
+ can set local policy for timezone abbreviations.
+ </p><p>
+ <code class="varname">timezone_abbreviations</code> can be set to any file name
+ found in <code class="filename">.../share/timezonesets/</code>, if the file's name
+ is entirely alphabetic. (The prohibition against non-alphabetic
+ characters in <code class="varname">timezone_abbreviations</code> prevents reading
+ files outside the intended directory, as well as reading editor
+ backup files and other extraneous files.)
+ </p><p>
+ A timezone abbreviation file can contain blank lines and comments
+ beginning with <code class="literal">#</code>. Non-comment lines must have one of
+ these formats:
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>zone_abbreviation</code></em> <em class="replaceable"><code>offset</code></em>
+<em class="replaceable"><code>zone_abbreviation</code></em> <em class="replaceable"><code>offset</code></em> D
+<em class="replaceable"><code>zone_abbreviation</code></em> <em class="replaceable"><code>time_zone_name</code></em>
+@INCLUDE <em class="replaceable"><code>file_name</code></em>
+@OVERRIDE
+</pre><p>
+ </p><p>
+ A <em class="replaceable"><code>zone_abbreviation</code></em> is just the abbreviation
+ being defined. An <em class="replaceable"><code>offset</code></em> is an integer giving
+ the equivalent offset in seconds from UTC, positive being east from
+ Greenwich and negative being west. For example, -18000 would be five
+ hours west of Greenwich, or North American east coast standard time.
+ <code class="literal">D</code> indicates that the zone name represents local
+ daylight-savings time rather than standard time.
+ </p><p>
+ Alternatively, a <em class="replaceable"><code>time_zone_name</code></em> can be given, referencing
+ a zone name defined in the IANA timezone database. The zone's definition
+ is consulted to see whether the abbreviation is or has been in use in
+ that zone, and if so, the appropriate meaning is used — that is,
+ the meaning that was currently in use at the timestamp whose value is
+ being determined, or the meaning in use immediately before that if it
+ wasn't current at that time, or the oldest meaning if it was used only
+ after that time. This behavior is essential for dealing with
+ abbreviations whose meaning has historically varied. It is also allowed
+ to define an abbreviation in terms of a zone name in which that
+ abbreviation does not appear; then using the abbreviation is just
+ equivalent to writing out the zone name.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Using a simple integer <em class="replaceable"><code>offset</code></em> is preferred
+ when defining an abbreviation whose offset from UTC has never changed,
+ as such abbreviations are much cheaper to process than those that
+ require consulting a time zone definition.
+ </p></div><p>
+ The <code class="literal">@INCLUDE</code> syntax allows inclusion of another file in the
+ <code class="filename">.../share/timezonesets/</code> directory. Inclusion can be nested,
+ to a limited depth.
+ </p><p>
+ The <code class="literal">@OVERRIDE</code> syntax indicates that subsequent entries in the
+ file can override previous entries (typically, entries obtained from
+ included files). Without this, conflicting definitions of the same
+ timezone abbreviation are considered an error.
+ </p><p>
+ In an unmodified installation, the file <code class="filename">Default</code> contains
+ all the non-conflicting time zone abbreviations for most of the world.
+ Additional files <code class="filename">Australia</code> and <code class="filename">India</code> are
+ provided for those regions: these files first include the
+ <code class="literal">Default</code> file and then add or modify abbreviations as needed.
+ </p><p>
+ For reference purposes, a standard installation also contains files
+ <code class="filename">Africa.txt</code>, <code class="filename">America.txt</code>, etc., containing
+ information about every time zone abbreviation known to be in use
+ according to the IANA timezone database. The zone name
+ definitions found in these files can be copied and pasted into a custom
+ configuration file as needed. Note that these files cannot be directly
+ referenced as <code class="varname">timezone_abbreviations</code> settings, because of
+ the dot embedded in their names.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If an error occurs while reading the time zone abbreviation set, no new
+ value is applied and the old set is kept. If the error occurs while
+ starting the database, startup fails.
+ </p></div><div class="caution"><h3 class="title">Caution</h3><p>
+ Time zone abbreviations defined in the configuration file override
+ non-timezone meanings built into <span class="productname">PostgreSQL</span>.
+ For example, the <code class="filename">Australia</code> configuration file defines
+ <code class="literal">SAT</code> (for South Australian Standard Time). When this
+ file is active, <code class="literal">SAT</code> will not be recognized as an abbreviation
+ for Saturday.
+ </p></div><div class="caution"><h3 class="title">Caution</h3><p>
+ If you modify files in <code class="filename">.../share/timezonesets/</code>,
+ it is up to you to make backups — a normal database dump
+ will not include this directory.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-keywords.html" title="B.3. Date/Time Key Words">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.3. Date/Time Key Words </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-input-rules.html b/doc/src/sgml/html/datetime-input-rules.html
new file mode 100644
index 0000000..0dbac90
--- /dev/null
+++ b/doc/src/sgml/html/datetime-input-rules.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.1. Date/Time Input Interpretation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-appendix.html" title="Appendix B. Date/Time Support" /><link rel="next" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.1. Date/Time Input Interpretation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-INPUT-RULES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.1. Date/Time Input Interpretation</h2></div></div></div><p>
+ Date/time input strings are decoded using the following procedure.
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ Break the input string into tokens and categorize each token as
+ a string, time, time zone, or number.
+ </p><ol type="a" class="substeps"><li class="step"><p>
+ If the numeric token contains a colon (<code class="literal">:</code>), this is
+ a time string. Include all subsequent digits and colons.
+ </p></li><li class="step"><p>
+ If the numeric token contains a dash (<code class="literal">-</code>), slash
+ (<code class="literal">/</code>), or two or more dots (<code class="literal">.</code>), this is
+ a date string which might have a text month. If a date token has
+ already been seen, it is instead interpreted as a time zone
+ name (e.g., <code class="literal">America/New_York</code>).
+ </p></li><li class="step"><p>
+ If the token is numeric only, then it is either a single field
+ or an ISO 8601 concatenated date (e.g.,
+ <code class="literal">19990113</code> for January 13, 1999) or time
+ (e.g., <code class="literal">141516</code> for 14:15:16).
+ </p></li><li class="step"><p>
+ If the token starts with a plus (<code class="literal">+</code>) or minus
+ (<code class="literal">-</code>), then it is either a numeric time zone or a special
+ field.
+ </p></li></ol></li><li class="step"><p>
+ If the token is an alphabetic string, match up with possible strings:
+ </p><ol type="a" class="substeps"><li class="step"><p>
+ See if the token matches any known time zone abbreviation.
+ These abbreviations are supplied by the configuration file
+ described in <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a>.
+ </p></li><li class="step"><p>
+ If not found, search an internal table to match
+ the token as either a special string (e.g., <code class="literal">today</code>),
+ day (e.g., <code class="literal">Thursday</code>),
+ month (e.g., <code class="literal">January</code>),
+ or noise word (e.g., <code class="literal">at</code>, <code class="literal">on</code>).
+ </p></li><li class="step"><p>
+ If still not found, throw an error.
+ </p></li></ol></li><li class="step"><p>
+ When the token is a number or number field:
+ </p><ol type="a" class="substeps"><li class="step"><p>
+ If there are eight or six digits,
+ and if no other date fields have been previously read, then interpret
+ as a <span class="quote">“<span class="quote">concatenated date</span>”</span> (e.g.,
+ <code class="literal">19990118</code> or <code class="literal">990118</code>).
+ The interpretation is <code class="literal">YYYYMMDD</code> or <code class="literal">YYMMDD</code>.
+ </p></li><li class="step"><p>
+ If the token is three digits
+ and a year has already been read, then interpret as day of year.
+ </p></li><li class="step"><p>
+ If four or six digits and a year has already been read, then
+ interpret as a time (<code class="literal">HHMM</code> or <code class="literal">HHMMSS</code>).
+ </p></li><li class="step"><p>
+ If three or more digits and no date fields have yet been found,
+ interpret as a year (this forces yy-mm-dd ordering of the remaining
+ date fields).
+ </p></li><li class="step"><p>
+ Otherwise the date field ordering is assumed to follow the
+ <code class="varname">DateStyle</code> setting: mm-dd-yy, dd-mm-yy, or yy-mm-dd.
+ Throw an error if a month or day field is found to be out of range.
+ </p></li></ol></li><li class="step"><p>
+ If BC has been specified, negate the year and add one for
+ internal storage. (There is no year zero in the Gregorian
+ calendar, so numerically 1 BC becomes year zero.)
+ </p></li><li class="step"><p>
+ If BC was not specified, and if the year field was two digits in length,
+ then adjust the year to four digits. If the field is less than 70, then
+ add 2000, otherwise add 1900.
+
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Gregorian years AD 1–99 can be entered by using 4 digits with leading
+ zeros (e.g., <code class="literal">0099</code> is AD 99).
+ </p></div><p>
+ </p></li></ol></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix B. Date/Time Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.2. Handling of Invalid or Ambiguous Timestamps</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-invalid-input.html b/doc/src/sgml/html/datetime-invalid-input.html
new file mode 100644
index 0000000..16a0330
--- /dev/null
+++ b/doc/src/sgml/html/datetime-invalid-input.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.2. Handling of Invalid or Ambiguous Timestamps</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation" /><link rel="next" href="datetime-keywords.html" title="B.3. Date/Time Key Words" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.2. Handling of Invalid or Ambiguous Timestamps</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-keywords.html" title="B.3. Date/Time Key Words">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-INVALID-INPUT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.2. Handling of Invalid or Ambiguous Timestamps</h2></div></div></div><p>
+ Ordinarily, if a date/time string is syntactically valid but contains
+ out-of-range field values, an error will be thrown. For example, input
+ specifying the 31st of February will be rejected.
+ </p><p>
+ During a daylight-savings-time transition, it is possible for a
+ seemingly valid timestamp string to represent a nonexistent or ambiguous
+ timestamp. Such cases are not rejected; the ambiguity is resolved by
+ determining which UTC offset to apply. For example, supposing that the
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> parameter is set
+ to <code class="literal">America/New_York</code>, consider
+</p><pre class="programlisting">
+=&gt; SELECT '2018-03-11 02:30'::timestamptz;
+ timestamptz
+------------------------
+ 2018-03-11 03:30:00-04
+(1 row)
+</pre><p>
+ Because that day was a spring-forward transition date in that time zone,
+ there was no civil time instant 2:30AM; clocks jumped forward from 2AM
+ EST to 3AM EDT. <span class="productname">PostgreSQL</span> interprets the
+ given time as if it were standard time (UTC-5), which then renders as
+ 3:30AM EDT (UTC-4).
+ </p><p>
+ Conversely, consider the behavior during a fall-back transition:
+</p><pre class="programlisting">
+=&gt; SELECT '2018-11-04 01:30'::timestamptz;
+ timestamptz
+------------------------
+ 2018-11-04 01:30:00-05
+(1 row)
+</pre><p>
+ On that date, there were two possible interpretations of 1:30AM; there
+ was 1:30AM EDT, and then an hour later after clocks jumped back from
+ 2AM EDT to 1AM EST, there was 1:30AM EST.
+ Again, <span class="productname">PostgreSQL</span> interprets the given time
+ as if it were standard time (UTC-5). We can force the other
+ interpretation by specifying daylight-savings time:
+</p><pre class="programlisting">
+=&gt; SELECT '2018-11-04 01:30 EDT'::timestamptz;
+ timestamptz
+------------------------
+ 2018-11-04 01:30:00-04
+(1 row)
+</pre><p>
+ </p><p>
+ The precise rule that is applied in such cases is that an invalid
+ timestamp that appears to fall within a jump-forward daylight savings
+ transition is assigned the UTC offset that prevailed in the time zone
+ just before the transition, while an ambiguous timestamp that could fall
+ on either side of a jump-back transition is assigned the UTC offset that
+ prevailed just after the transition. In most time zones this is
+ equivalent to saying that <span class="quote">“<span class="quote">the standard-time interpretation is
+ preferred when in doubt</span>”</span>.
+ </p><p>
+ In all cases, the UTC offset associated with a timestamp can be
+ specified explicitly, using either a numeric UTC offset or a time zone
+ abbreviation that corresponds to a fixed UTC offset. The rule just
+ given applies only when it is necessary to infer a UTC offset for a time
+ zone in which the offset varies.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-input-rules.html" title="B.1. Date/Time Input Interpretation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-keywords.html" title="B.3. Date/Time Key Words">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.1. Date/Time Input Interpretation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.3. Date/Time Key Words</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-julian-dates.html b/doc/src/sgml/html/datetime-julian-dates.html
new file mode 100644
index 0000000..dea1b65
--- /dev/null
+++ b/doc/src/sgml/html/datetime-julian-dates.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.7. Julian Dates</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-units-history.html" title="B.6. History of Units" /><link rel="next" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.7. Julian Dates</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-units-history.html" title="B.6. History of Units">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-JULIAN-DATES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.7. Julian Dates</h2></div></div></div><a id="id-1.11.3.10.2" class="indexterm"></a><p>
+ The <em class="firstterm">Julian Date</em> system is a method for
+ numbering days. It is
+ unrelated to the Julian calendar, though it is confusingly
+ named similarly to that calendar.
+ The Julian Date system was invented by the French scholar
+ Joseph Justus Scaliger (1540–1609)
+ and probably takes its name from Scaliger's father,
+ the Italian scholar Julius Caesar Scaliger (1484–1558).
+ </p><p>
+ In the Julian Date system, each day has a sequential number, starting
+ from JD 0 (which is sometimes called <span class="emphasis"><em>the</em></span> Julian Date).
+ JD 0 corresponds to 1 January 4713 BC in the Julian calendar, or
+ 24 November 4714 BC in the Gregorian calendar. Julian Date counting
+ is most often used by astronomers for labeling their nightly observations,
+ and therefore a date runs from noon UTC to the next noon UTC, rather than
+ from midnight to midnight: JD 0 designates the 24 hours from noon UTC on
+ 24 November 4714 BC to noon UTC on 25 November 4714 BC.
+ </p><p>
+ Although <span class="productname">PostgreSQL</span> supports Julian Date notation for
+ input and output of dates (and also uses Julian dates for some internal
+ datetime calculations), it does not observe the nicety of having dates
+ run from noon to noon. <span class="productname">PostgreSQL</span> treats a Julian Date
+ as running from local midnight to local midnight, the same as a normal
+ date.
+ </p><p>
+ This definition does, however, provide a way to obtain the astronomical
+ definition when you need it: do the arithmetic in time
+ zone <code class="literal">UTC+12</code>. For example,
+</p><pre class="programlisting">
+=&gt; SELECT extract(julian from '2021-06-23 7:00:00-04'::timestamptz at time zone 'UTC+12');
+ extract
+------------------------------
+ 2459388.95833333333333333333
+(1 row)
+=&gt; SELECT extract(julian from '2021-06-23 8:00:00-04'::timestamptz at time zone 'UTC+12');
+ extract
+--------------------------------------
+ 2459389.0000000000000000000000000000
+(1 row)
+=&gt; SELECT extract(julian from date '2021-06-23');
+ extract
+---------
+ 2459389
+(1 row)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-units-history.html" title="B.6. History of Units">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.6. History of Units </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix C. <acronym class="acronym">SQL</acronym> Key Words</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-keywords.html b/doc/src/sgml/html/datetime-keywords.html
new file mode 100644
index 0000000..ff0cd34
--- /dev/null
+++ b/doc/src/sgml/html/datetime-keywords.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.3. Date/Time Key Words</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps" /><link rel="next" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.3. Date/Time Key Words</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-KEYWORDS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.3. Date/Time Key Words</h2></div></div></div><p>
+ <a class="xref" href="datetime-keywords.html#DATETIME-MONTH-TABLE" title="Table B.1. Month Names">Table B.1</a> shows the tokens that are
+ recognized as names of months.
+ </p><div class="table" id="DATETIME-MONTH-TABLE"><p class="title"><strong>Table B.1. Month Names</strong></p><div class="table-contents"><table class="table" summary="Month Names" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Month</th><th>Abbreviations</th></tr></thead><tbody><tr><td>January</td><td>Jan</td></tr><tr><td>February</td><td>Feb</td></tr><tr><td>March</td><td>Mar</td></tr><tr><td>April</td><td>Apr</td></tr><tr><td>May</td><td> </td></tr><tr><td>June</td><td>Jun</td></tr><tr><td>July</td><td>Jul</td></tr><tr><td>August</td><td>Aug</td></tr><tr><td>September</td><td>Sep, Sept</td></tr><tr><td>October</td><td>Oct</td></tr><tr><td>November</td><td>Nov</td></tr><tr><td>December</td><td>Dec</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="datetime-keywords.html#DATETIME-DOW-TABLE" title="Table B.2. Day of the Week Names">Table B.2</a> shows the tokens that are
+ recognized as names of days of the week.
+ </p><div class="table" id="DATETIME-DOW-TABLE"><p class="title"><strong>Table B.2. Day of the Week Names</strong></p><div class="table-contents"><table class="table" summary="Day of the Week Names" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Day</th><th>Abbreviations</th></tr></thead><tbody><tr><td>Sunday</td><td>Sun</td></tr><tr><td>Monday</td><td>Mon</td></tr><tr><td>Tuesday</td><td>Tue, Tues</td></tr><tr><td>Wednesday</td><td>Wed, Weds</td></tr><tr><td>Thursday</td><td>Thu, Thur, Thurs</td></tr><tr><td>Friday</td><td>Fri</td></tr><tr><td>Saturday</td><td>Sat</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="datetime-keywords.html#DATETIME-MOD-TABLE" title="Table B.3. Date/Time Field Modifiers">Table B.3</a> shows the tokens that serve
+ various modifier purposes.
+ </p><div class="table" id="DATETIME-MOD-TABLE"><p class="title"><strong>Table B.3. Date/Time Field Modifiers</strong></p><div class="table-contents"><table class="table" summary="Date/Time Field Modifiers" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Identifier</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">AM</code></td><td>Time is before 12:00</td></tr><tr><td><code class="literal">AT</code></td><td>Ignored</td></tr><tr><td><code class="literal">JULIAN</code>, <code class="literal">JD</code>, <code class="literal">J</code></td><td>Next field is Julian Date</td></tr><tr><td><code class="literal">ON</code></td><td>Ignored</td></tr><tr><td><code class="literal">PM</code></td><td>Time is on or after 12:00</td></tr><tr><td><code class="literal">T</code></td><td>Next field is time</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-invalid-input.html" title="B.2. Handling of Invalid or Ambiguous Timestamps">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.2. Handling of Invalid or Ambiguous Timestamps </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.4. Date/Time Configuration Files</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-posix-timezone-specs.html b/doc/src/sgml/html/datetime-posix-timezone-specs.html
new file mode 100644
index 0000000..1b0bcaf
--- /dev/null
+++ b/doc/src/sgml/html/datetime-posix-timezone-specs.html
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.5. POSIX Time Zone Specifications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files" /><link rel="next" href="datetime-units-history.html" title="B.6. History of Units" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-units-history.html" title="B.6. History of Units">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-POSIX-TIMEZONE-SPECS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</h2></div></div></div><a id="id-1.11.3.8.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> can accept time zone specifications
+ that are written according to the <acronym class="acronym">POSIX</acronym> standard's rules
+ for the <code class="varname">TZ</code> environment
+ variable. <acronym class="acronym">POSIX</acronym> time zone specifications are
+ inadequate to deal with the complexity of real-world time zone history,
+ but there are sometimes reasons to use them.
+ </p><p>
+ A POSIX time zone specification has the form
+</p><pre class="synopsis">
+<em class="replaceable"><code>STD</code></em> <em class="replaceable"><code>offset</code></em> [<span class="optional"> <em class="replaceable"><code>DST</code></em> [<span class="optional"> <em class="replaceable"><code>dstoffset</code></em> </span>] [<span class="optional"> , <em class="replaceable"><code>rule</code></em> </span>] </span>]
+</pre><p>
+ (For readability, we show spaces between the fields, but spaces should
+ not be used in practice.) The fields are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <em class="replaceable"><code>STD</code></em> is the zone abbreviation to be used
+ for standard time.
+ </p></li><li class="listitem"><p>
+ <em class="replaceable"><code>offset</code></em> is the zone's standard-time offset
+ from UTC.
+ </p></li><li class="listitem"><p>
+ <em class="replaceable"><code>DST</code></em> is the zone abbreviation to be used
+ for daylight-savings time. If this field and the following ones are
+ omitted, the zone uses a fixed UTC offset with no daylight-savings
+ rule.
+ </p></li><li class="listitem"><p>
+ <em class="replaceable"><code>dstoffset</code></em> is the daylight-savings offset
+ from UTC. This field is typically omitted, since it defaults to one
+ hour less than the standard-time <em class="replaceable"><code>offset</code></em>,
+ which is usually the right thing.
+ </p></li><li class="listitem"><p>
+ <em class="replaceable"><code>rule</code></em> defines the rule for when daylight
+ savings is in effect, as described below.
+ </p></li></ul></div><p>
+ </p><p>
+ In this syntax, a zone abbreviation can be a string of letters, such
+ as <code class="literal">EST</code>, or an arbitrary string surrounded by angle
+ brackets, such as <code class="literal">&lt;UTC-05&gt;</code>.
+ Note that the zone abbreviations given here are only used for output,
+ and even then only in some timestamp output formats. The zone
+ abbreviations recognized in timestamp input are determined as explained
+ in <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a>.
+ </p><p>
+ The offset fields specify the hours, and optionally minutes and seconds,
+ difference from UTC. They have the format
+ <em class="replaceable"><code>hh</code></em>[<span class="optional"><code class="literal">:</code><em class="replaceable"><code>mm</code></em>[<span class="optional"><code class="literal">:</code><em class="replaceable"><code>ss</code></em></span>]</span>]
+ optionally with a leading sign (<code class="literal">+</code>
+ or <code class="literal">-</code>). The positive sign is used for
+ zones <span class="emphasis"><em>west</em></span> of Greenwich. (Note that this is the
+ opposite of the ISO-8601 sign convention used elsewhere in
+ <span class="productname">PostgreSQL</span>.) <em class="replaceable"><code>hh</code></em>
+ can have one or two digits; <em class="replaceable"><code>mm</code></em>
+ and <em class="replaceable"><code>ss</code></em> (if used) must have two.
+ </p><p>
+ The daylight-savings transition <em class="replaceable"><code>rule</code></em> has the
+ format
+</p><pre class="synopsis">
+<em class="replaceable"><code>dstdate</code></em> [<span class="optional"> <code class="literal">/</code> <em class="replaceable"><code>dsttime</code></em> </span>] <code class="literal">,</code> <em class="replaceable"><code>stddate</code></em> [<span class="optional"> <code class="literal">/</code> <em class="replaceable"><code>stdtime</code></em> </span>]
+</pre><p>
+ (As before, spaces should not be included in practice.)
+ The <em class="replaceable"><code>dstdate</code></em>
+ and <em class="replaceable"><code>dsttime</code></em> fields define when daylight-savings
+ time starts, while <em class="replaceable"><code>stddate</code></em>
+ and <em class="replaceable"><code>stdtime</code></em> define when standard time
+ starts. (In some cases, notably in zones south of the equator, the
+ former might be later in the year than the latter.) The date fields
+ have one of these formats:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ A plain integer denotes a day of the year, counting from zero to
+ 364, or to 365 in leap years.
+ </p></dd><dt><span class="term"><code class="literal">J</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ In this form, <em class="replaceable"><code>n</code></em> counts from 1 to 365,
+ and February 29 is not counted even if it is present. (Thus, a
+ transition occurring on February 29 could not be specified this
+ way. However, days after February have the same numbers whether
+ it's a leap year or not, so that this form is usually more useful
+ than the plain-integer form for transitions on fixed dates.)
+ </p></dd><dt><span class="term"><code class="literal">M</code><em class="replaceable"><code>m</code></em><code class="literal">.</code><em class="replaceable"><code>n</code></em><code class="literal">.</code><em class="replaceable"><code>d</code></em></span></dt><dd><p>
+ This form specifies a transition that always happens during the same
+ month and on the same day of the week. <em class="replaceable"><code>m</code></em>
+ identifies the month, from 1 to 12. <em class="replaceable"><code>n</code></em>
+ specifies the <em class="replaceable"><code>n</code></em>'th occurrence of the
+ weekday identified by <em class="replaceable"><code>d</code></em>.
+ <em class="replaceable"><code>n</code></em> is a number between 1 and 4, or 5
+ meaning the last occurrence of that weekday in the month (which
+ could be the fourth or the fifth). <em class="replaceable"><code>d</code></em> is
+ a number between 0 and 6, with 0 indicating Sunday.
+ For example, <code class="literal">M3.2.0</code> means <span class="quote">“<span class="quote">the second
+ Sunday in March</span>”</span>.
+ </p></dd></dl></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="literal">M</code> format is sufficient to describe many common
+ daylight-savings transition laws. But note that none of these variants
+ can deal with daylight-savings law changes, so in practice the
+ historical data stored for named time zones (in the IANA time zone
+ database) is necessary to interpret past time stamps correctly.
+ </p></div><p>
+ The time fields in a transition rule have the same format as the offset
+ fields described previously, except that they cannot contain signs.
+ They define the current local time at which the change to the other
+ time occurs. If omitted, they default to <code class="literal">02:00:00</code>.
+ </p><p>
+ If a daylight-savings abbreviation is given but the
+ transition <em class="replaceable"><code>rule</code></em> field is omitted,
+ the fallback behavior is to use the
+ rule <code class="literal">M3.2.0,M11.1.0</code>, which corresponds to USA
+ practice as of 2020 (that is, spring forward on the second Sunday of
+ March, fall back on the first Sunday of November, both transitions
+ occurring at 2AM prevailing time). Note that this rule does not
+ give correct USA transition dates for years before 2007.
+ </p><p>
+ As an example, <code class="literal">CET-1CEST,M3.5.0,M10.5.0/3</code> describes
+ current (as of 2020) timekeeping practice in Paris. This specification
+ says that standard time has the abbreviation <code class="literal">CET</code> and
+ is one hour ahead (east) of UTC; daylight savings time has the
+ abbreviation <code class="literal">CEST</code> and is implicitly two hours ahead
+ of UTC; daylight savings time begins on the last Sunday in March at 2AM
+ CET and ends on the last Sunday in October at 3AM CEST.
+ </p><p>
+ The four timezone names <code class="literal">EST5EDT</code>,
+ <code class="literal">CST6CDT</code>, <code class="literal">MST7MDT</code>,
+ and <code class="literal">PST8PDT</code> look like they are POSIX zone
+ specifications. However, they actually are treated as named time zones
+ because (for historical reasons) there are files by those names in the
+ IANA time zone database. The practical implication of this is that
+ these zone names will produce valid historical USA daylight-savings
+ transitions, even when a plain POSIX specification would not.
+ </p><p>
+ One should be wary that it is easy to misspell a POSIX-style time zone
+ specification, since there is no check on the reasonableness of the
+ zone abbreviation(s). For example, <code class="literal">SET TIMEZONE TO
+ FOOBAR0</code> will work, leaving the system effectively using a
+ rather peculiar abbreviation for UTC.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-units-history.html" title="B.6. History of Units">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.4. Date/Time Configuration Files </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.6. History of Units</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/datetime-units-history.html b/doc/src/sgml/html/datetime-units-history.html
new file mode 100644
index 0000000..023f4cf
--- /dev/null
+++ b/doc/src/sgml/html/datetime-units-history.html
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.6. History of Units</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications" /><link rel="next" href="datetime-julian-dates.html" title="B.7. Julian Dates" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.6. History of Units</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-julian-dates.html" title="B.7. Julian Dates">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-UNITS-HISTORY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.6. History of Units</h2></div></div></div><a id="id-1.11.3.9.2" class="indexterm"></a><p>
+ The SQL standard states that <span class="quote">“<span class="quote">Within the definition of a
+ <span class="quote">‘<span class="quote">datetime literal</span>’</span>, the <span class="quote">‘<span class="quote">datetime
+ values</span>’</span> are constrained by the natural rules for dates and
+ times according to the Gregorian calendar</span>”</span>.
+ <span class="productname">PostgreSQL</span> follows the SQL
+ standard's lead by counting dates exclusively in the Gregorian
+ calendar, even for years before that calendar was in use.
+ This rule is known as the <em class="firstterm">proleptic Gregorian calendar</em>.
+ </p><p>
+ The Julian calendar was introduced by Julius Caesar in 45 BC.
+ It was in common use in the Western world
+ until the year 1582, when countries started changing to the Gregorian
+ calendar. In the Julian calendar, the tropical year is
+ approximated as 365 1/4 days = 365.25 days. This gives an error of
+ about 1 day in 128 years.
+ </p><p>
+ The accumulating calendar error prompted
+ Pope Gregory XIII to reform the calendar in accordance with
+ instructions from the Council of Trent.
+ In the Gregorian calendar, the tropical year is approximated as
+ 365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300
+ years for the tropical year to shift one day with respect to the
+ Gregorian calendar.
+ </p><p>
+ The approximation 365+97/400 is achieved by having 97 leap years
+ every 400 years, using the following rules:
+
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td>
+ Every year divisible by 4 is a leap year.
+ </td></tr><tr><td>
+ However, every year divisible by 100 is not a leap year.
+ </td></tr><tr><td>
+ However, every year divisible by 400 is a leap year after all.
+ </td></tr></table><p>
+
+ So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600,
+ 2000, and 2400 are leap years.
+
+ By contrast, in the older Julian calendar all years divisible by 4 are leap
+ years.
+ </p><p>
+ The papal bull of February 1582 decreed that 10 days should be dropped
+ from October 1582 so that 15 October should follow immediately after
+ 4 October.
+ This was observed in Italy, Poland, Portugal, and Spain. Other Catholic
+ countries followed shortly after, but Protestant countries were
+ reluctant to change, and the Greek Orthodox countries didn't change
+ until the start of the 20th century.
+
+ The reform was observed by Great Britain and its dominions (including what
+ is now the USA) in 1752.
+ Thus 2 September 1752 was followed by 14 September 1752.
+
+ This is why Unix systems that have the <code class="command">cal</code> program
+ produce the following:
+
+</p><pre class="screen">
+$ <strong class="userinput"><code>cal 9 1752</code></strong>
+ September 1752
+ S M Tu W Th F S
+ 1 2 14 15 16
+17 18 19 20 21 22 23
+24 25 26 27 28 29 30
+</pre><p>
+
+ But, of course, this calendar is only valid for Great Britain and
+ dominions, not other places.
+ Since it would be difficult and confusing to try to track the actual
+ calendars that were in use in various places at various times,
+ <span class="productname">PostgreSQL</span> does not try, but rather follows the Gregorian
+ calendar rules for all dates, even though this method is not historically
+ accurate.
+ </p><p>
+ Different calendars have been developed in various parts of the
+ world, many predating the Gregorian system.
+
+ For example,
+ the beginnings of the Chinese calendar can be traced back to the 14th
+ century BC. Legend has it that the Emperor Huangdi invented that
+ calendar in 2637 BC.
+
+ The People's Republic of China uses the Gregorian calendar
+ for civil purposes. The Chinese calendar is used for determining
+ festivals.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-posix-timezone-specs.html" title="B.5. POSIX Time Zone Specifications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-julian-dates.html" title="B.7. Julian Dates">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.7. Julian Dates</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dblink.html b/doc/src/sgml/html/dblink.html
new file mode 100644
index 0000000..ca4f244
--- /dev/null
+++ b/doc/src/sgml/html/dblink.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.12. dblink</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="cube.html" title="F.11. cube" /><link rel="next" href="contrib-dblink-connect.html" title="dblink_connect" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.12. dblink</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="cube.html" title="F.11. cube">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-connect.html" title="dblink_connect">Next</a></td></tr></table><hr /></div><div class="sect1" id="DBLINK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.12. dblink</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="contrib-dblink-connect.html">dblink_connect</a></span><span class="refpurpose"> — opens a persistent connection to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-connect-u.html">dblink_connect_u</a></span><span class="refpurpose"> — opens a persistent connection to a remote database, insecurely</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-disconnect.html">dblink_disconnect</a></span><span class="refpurpose"> — closes a persistent connection to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-function.html">dblink</a></span><span class="refpurpose"> — executes a query in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-exec.html">dblink_exec</a></span><span class="refpurpose"> — executes a command in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-open.html">dblink_open</a></span><span class="refpurpose"> — opens a cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-fetch.html">dblink_fetch</a></span><span class="refpurpose"> — returns rows from an open cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-close.html">dblink_close</a></span><span class="refpurpose"> — closes a cursor in a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-connections.html">dblink_get_connections</a></span><span class="refpurpose"> — returns the names of all open named dblink connections</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-error-message.html">dblink_error_message</a></span><span class="refpurpose"> — gets last error message on the named connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-send-query.html">dblink_send_query</a></span><span class="refpurpose"> — sends an async query to a remote database</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-is-busy.html">dblink_is_busy</a></span><span class="refpurpose"> — checks if connection is busy with an async query</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-notify.html">dblink_get_notify</a></span><span class="refpurpose"> — retrieve async notifications on a connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-result.html">dblink_get_result</a></span><span class="refpurpose"> — gets an async query result</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-cancel-query.html">dblink_cancel_query</a></span><span class="refpurpose"> — cancels any active query on the named connection</span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-get-pkey.html">dblink_get_pkey</a></span><span class="refpurpose"> — returns the positions and field names of a relation's
+ primary key fields
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-insert.html">dblink_build_sql_insert</a></span><span class="refpurpose"> —
+ builds an INSERT statement using a local tuple, replacing the
+ primary key field values with alternative supplied values
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-delete.html">dblink_build_sql_delete</a></span><span class="refpurpose"> — builds a DELETE statement using supplied values for primary
+ key field values
+ </span></dt><dt><span class="refentrytitle"><a href="contrib-dblink-build-sql-update.html">dblink_build_sql_update</a></span><span class="refpurpose"> — builds an UPDATE statement using a local tuple, replacing
+ the primary key field values with alternative supplied values
+ </span></dt></dl></div><a id="id-1.11.7.21.2" class="indexterm"></a><p>
+ <code class="filename">dblink</code> is a module that supports connections to
+ other <span class="productname">PostgreSQL</span> databases from within a database
+ session.
+ </p><p>
+ See also <a class="xref" href="postgres-fdw.html" title="F.38. postgres_fdw">postgres_fdw</a>, which provides roughly the same
+ functionality using a more modern and standards-compliant infrastructure.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cube.html" title="F.11. cube">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-connect.html" title="dblink_connect">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.11. cube </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_connect</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-alter.html b/doc/src/sgml/html/ddl-alter.html
new file mode 100644
index 0000000..259803d
--- /dev/null
+++ b/doc/src/sgml/html/ddl-alter.html
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.6. Modifying Tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-system-columns.html" title="5.5. System Columns" /><link rel="next" href="ddl-priv.html" title="5.7. Privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.6. Modifying Tables</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-system-columns.html" title="5.5. System Columns">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-priv.html" title="5.7. Privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-ALTER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.6. Modifying Tables</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-ADDING-A-COLUMN">5.6.1. Adding a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-REMOVING-A-COLUMN">5.6.2. Removing a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-ADDING-A-CONSTRAINT">5.6.3. Adding a Constraint</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-REMOVING-A-CONSTRAINT">5.6.4. Removing a Constraint</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.9">5.6.5. Changing a Column's Default Value</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.10">5.6.6. Changing a Column's Data Type</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.11">5.6.7. Renaming a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.12">5.6.8. Renaming a Table</a></span></dt></dl></div><a id="id-1.5.4.8.2" class="indexterm"></a><p>
+ When you create a table and you realize that you made a mistake, or
+ the requirements of the application change, you can drop the
+ table and create it again. But this is not a convenient option if
+ the table is already filled with data, or if the table is
+ referenced by other database objects (for instance a foreign key
+ constraint). Therefore <span class="productname">PostgreSQL</span>
+ provides a family of commands to make modifications to existing
+ tables. Note that this is conceptually distinct from altering
+ the data contained in the table: here we are interested in altering
+ the definition, or structure, of the table.
+ </p><p>
+ You can:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>Add columns</p></li><li class="listitem"><p>Remove columns</p></li><li class="listitem"><p>Add constraints</p></li><li class="listitem"><p>Remove constraints</p></li><li class="listitem"><p>Change default values</p></li><li class="listitem"><p>Change column data types</p></li><li class="listitem"><p>Rename columns</p></li><li class="listitem"><p>Rename tables</p></li></ul></div><p>
+
+ All these actions are performed using the
+ <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>
+ command, whose reference page contains details beyond those given
+ here.
+ </p><div class="sect2" id="DDL-ALTER-ADDING-A-COLUMN"><div class="titlepage"><div><div><h3 class="title">5.6.1. Adding a Column</h3></div></div></div><a id="id-1.5.4.8.5.2" class="indexterm"></a><p>
+ To add a column, use a command like:
+</p><pre class="programlisting">
+ALTER TABLE products ADD COLUMN description text;
+</pre><p>
+ The new column is initially filled with whatever default
+ value is given (null if you don't specify a <code class="literal">DEFAULT</code> clause).
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ From <span class="productname">PostgreSQL</span> 11, adding a column with
+ a constant default value no longer means that each row of the table
+ needs to be updated when the <code class="command">ALTER TABLE</code> statement
+ is executed. Instead, the default value will be returned the next time
+ the row is accessed, and applied when the table is rewritten, making
+ the <code class="command">ALTER TABLE</code> very fast even on large tables.
+ </p><p>
+ However, if the default value is volatile (e.g.,
+ <code class="function">clock_timestamp()</code>)
+ each row will need to be updated with the value calculated at the time
+ <code class="command">ALTER TABLE</code> is executed. To avoid a potentially
+ lengthy update operation, particularly if you intend to fill the column
+ with mostly nondefault values anyway, it may be preferable to add the
+ column with no default, insert the correct values using
+ <code class="command">UPDATE</code>, and then add any desired default as described
+ below.
+ </p></div><p>
+ You can also define constraints on the column at the same time,
+ using the usual syntax:
+</p><pre class="programlisting">
+ALTER TABLE products ADD COLUMN description text CHECK (description &lt;&gt; '');
+</pre><p>
+ In fact all the options that can be applied to a column description
+ in <code class="command">CREATE TABLE</code> can be used here. Keep in mind however
+ that the default value must satisfy the given constraints, or the
+ <code class="literal">ADD</code> will fail. Alternatively, you can add
+ constraints later (see below) after you've filled in the new column
+ correctly.
+ </p></div><div class="sect2" id="DDL-ALTER-REMOVING-A-COLUMN"><div class="titlepage"><div><div><h3 class="title">5.6.2. Removing a Column</h3></div></div></div><a id="id-1.5.4.8.6.2" class="indexterm"></a><p>
+ To remove a column, use a command like:
+</p><pre class="programlisting">
+ALTER TABLE products DROP COLUMN description;
+</pre><p>
+ Whatever data was in the column disappears. Table constraints involving
+ the column are dropped, too. However, if the column is referenced by a
+ foreign key constraint of another table,
+ <span class="productname">PostgreSQL</span> will not silently drop that
+ constraint. You can authorize dropping everything that depends on
+ the column by adding <code class="literal">CASCADE</code>:
+</p><pre class="programlisting">
+ALTER TABLE products DROP COLUMN description CASCADE;
+</pre><p>
+ See <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a> for a description of the general
+ mechanism behind this.
+ </p></div><div class="sect2" id="DDL-ALTER-ADDING-A-CONSTRAINT"><div class="titlepage"><div><div><h3 class="title">5.6.3. Adding a Constraint</h3></div></div></div><a id="id-1.5.4.8.7.2" class="indexterm"></a><p>
+ To add a constraint, the table constraint syntax is used. For example:
+</p><pre class="programlisting">
+ALTER TABLE products ADD CHECK (name &lt;&gt; '');
+ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no);
+ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_groups;
+</pre><p>
+ To add a not-null constraint, which cannot be written as a table
+ constraint, use this syntax:
+</p><pre class="programlisting">
+ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
+</pre><p>
+ </p><p>
+ The constraint will be checked immediately, so the table data must
+ satisfy the constraint before it can be added.
+ </p></div><div class="sect2" id="DDL-ALTER-REMOVING-A-CONSTRAINT"><div class="titlepage"><div><div><h3 class="title">5.6.4. Removing a Constraint</h3></div></div></div><a id="id-1.5.4.8.8.2" class="indexterm"></a><p>
+ To remove a constraint you need to know its name. If you gave it
+ a name then that's easy. Otherwise the system assigned a
+ generated name, which you need to find out. The
+ <span class="application">psql</span> command <code class="literal">\d
+ <em class="replaceable"><code>tablename</code></em></code> can be helpful
+ here; other interfaces might also provide a way to inspect table
+ details. Then the command is:
+</p><pre class="programlisting">
+ALTER TABLE products DROP CONSTRAINT some_name;
+</pre><p>
+ (If you are dealing with a generated constraint name like <code class="literal">$2</code>,
+ don't forget that you'll need to double-quote it to make it a valid
+ identifier.)
+ </p><p>
+ As with dropping a column, you need to add <code class="literal">CASCADE</code> if you
+ want to drop a constraint that something else depends on. An example
+ is that a foreign key constraint depends on a unique or primary key
+ constraint on the referenced column(s).
+ </p><p>
+ This works the same for all constraint types except not-null
+ constraints. To drop a not null constraint use:
+</p><pre class="programlisting">
+ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
+</pre><p>
+ (Recall that not-null constraints do not have names.)
+ </p></div><div class="sect2" id="id-1.5.4.8.9"><div class="titlepage"><div><div><h3 class="title">5.6.5. Changing a Column's Default Value</h3></div></div></div><a id="id-1.5.4.8.9.2" class="indexterm"></a><p>
+ To set a new default for a column, use a command like:
+</p><pre class="programlisting">
+ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77;
+</pre><p>
+ Note that this doesn't affect any existing rows in the table, it
+ just changes the default for future <code class="command">INSERT</code> commands.
+ </p><p>
+ To remove any default value, use:
+</p><pre class="programlisting">
+ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
+</pre><p>
+ This is effectively the same as setting the default to null.
+ As a consequence, it is not an error
+ to drop a default where one hadn't been defined, because the
+ default is implicitly the null value.
+ </p></div><div class="sect2" id="id-1.5.4.8.10"><div class="titlepage"><div><div><h3 class="title">5.6.6. Changing a Column's Data Type</h3></div></div></div><a id="id-1.5.4.8.10.2" class="indexterm"></a><p>
+ To convert a column to a different data type, use a command like:
+</p><pre class="programlisting">
+ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2);
+</pre><p>
+ This will succeed only if each existing entry in the column can be
+ converted to the new type by an implicit cast. If a more complex
+ conversion is needed, you can add a <code class="literal">USING</code> clause that
+ specifies how to compute the new values from the old.
+ </p><p>
+ <span class="productname">PostgreSQL</span> will attempt to convert the column's
+ default value (if any) to the new type, as well as any constraints
+ that involve the column. But these conversions might fail, or might
+ produce surprising results. It's often best to drop any constraints
+ on the column before altering its type, and then add back suitably
+ modified constraints afterwards.
+ </p></div><div class="sect2" id="id-1.5.4.8.11"><div class="titlepage"><div><div><h3 class="title">5.6.7. Renaming a Column</h3></div></div></div><a id="id-1.5.4.8.11.2" class="indexterm"></a><p>
+ To rename a column:
+</p><pre class="programlisting">
+ALTER TABLE products RENAME COLUMN product_no TO product_number;
+</pre><p>
+ </p></div><div class="sect2" id="id-1.5.4.8.12"><div class="titlepage"><div><div><h3 class="title">5.6.8. Renaming a Table</h3></div></div></div><a id="id-1.5.4.8.12.2" class="indexterm"></a><p>
+ To rename a table:
+</p><pre class="programlisting">
+ALTER TABLE products RENAME TO items;
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-system-columns.html" title="5.5. System Columns">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-priv.html" title="5.7. Privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.5. System Columns </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.7. Privileges</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-basics.html b/doc/src/sgml/html/ddl-basics.html
new file mode 100644
index 0000000..81e8632
--- /dev/null
+++ b/doc/src/sgml/html/ddl-basics.html
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.1. Table Basics</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl.html" title="Chapter 5. Data Definition" /><link rel="next" href="ddl-default.html" title="5.2. Default Values" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.1. Table Basics</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl.html" title="Chapter 5. Data Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-default.html" title="5.2. Default Values">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-BASICS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.1. Table Basics</h2></div></div></div><a id="id-1.5.4.3.2" class="indexterm"></a><a id="id-1.5.4.3.3" class="indexterm"></a><a id="id-1.5.4.3.4" class="indexterm"></a><p>
+ A table in a relational database is much like a table on paper: It
+ consists of rows and columns. The number and order of the columns
+ is fixed, and each column has a name. The number of rows is
+ variable — it reflects how much data is stored at a given moment.
+ 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 <a class="xref" href="queries.html" title="Chapter 7. Queries">Chapter 7</a>. 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.
+ Later in this chapter we will see how to deal with this issue.
+ </p><p>
+ Each column has a data type. The data type constrains the set of
+ possible values that can be assigned to a column and assigns
+ semantics to the data stored in the column so that it can be used
+ for computations. For instance, a column declared to be of a
+ numerical type will not accept arbitrary text strings, and the data
+ stored in such a column can be used for mathematical computations.
+ By contrast, a column declared to be of a character string type
+ will accept almost any kind of data but it does not lend itself to
+ mathematical calculations, although other operations such as string
+ concatenation are available.
+ </p><p>
+ <span class="productname">PostgreSQL</span> includes a sizable set of
+ 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 <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>. Some of the frequently used data types are
+ <code class="type">integer</code> for whole numbers, <code class="type">numeric</code> for
+ possibly fractional numbers, <code class="type">text</code> for character
+ strings, <code class="type">date</code> for dates, <code class="type">time</code> for
+ time-of-day values, and <code class="type">timestamp</code> for values
+ containing both date and time.
+ </p><a id="id-1.5.4.3.8" class="indexterm"></a><p>
+ To create a table, you use the aptly named <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> 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:
+</p><pre class="programlisting">
+CREATE TABLE my_first_table (
+ first_column text,
+ second_column integer
+);
+</pre><p>
+ This creates a table named <code class="literal">my_first_table</code> with
+ two columns. The first column is named
+ <code class="literal">first_column</code> and has a data type of
+ <code class="type">text</code>; the second column has the name
+ <code class="literal">second_column</code> and the type <code class="type">integer</code>.
+ The table and column names follow the identifier syntax explained
+ in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS" title="4.1.1. Identifiers and Key Words">Section 4.1.1</a>. The type names are
+ usually also identifiers, but there are some exceptions. Note that the
+ column list is comma-separated and surrounded by parentheses.
+ </p><p>
+ Of course, the previous example was heavily contrived. Normally,
+ you would give names to your tables and columns that convey what
+ kind of data they store. So let's look at a more realistic
+ example:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric
+);
+</pre><p>
+ (The <code class="type">numeric</code> type can store fractional components, as
+ would be typical of monetary amounts.)
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ When you create many interrelated tables it is wise to choose a
+ consistent naming pattern for the tables and columns. For
+ instance, there is a choice of using singular or plural nouns for
+ table names, both of which are favored by some theorist or other.
+ </p></div><p>
+ There is a limit on how many columns a table can contain.
+ Depending on the column types, it is between 250 and 1600.
+ However, defining a table with anywhere near this many columns is
+ highly unusual and often a questionable design.
+ </p><a id="id-1.5.4.3.13" class="indexterm"></a><p>
+ If you no longer need a table, you can remove it using the <a class="xref" href="sql-droptable.html" title="DROP TABLE"><span class="refentrytitle">DROP TABLE</span></a> command.
+ For example:
+</p><pre class="programlisting">
+DROP TABLE my_first_table;
+DROP TABLE products;
+</pre><p>
+ Attempting to drop a table that does not exist is an error.
+ Nevertheless, it is common in SQL script files to unconditionally
+ try to drop each table before creating it, ignoring any error
+ messages, so that the script works whether or not the table exists.
+ (If you like, you can use the <code class="literal">DROP TABLE IF EXISTS</code> variant
+ to avoid the error messages, but this is not standard SQL.)
+ </p><p>
+ If you need to modify a table that already exists, see <a class="xref" href="ddl-alter.html" title="5.6. Modifying Tables">Section 5.6</a> later in this chapter.
+ </p><p>
+ With the tools discussed so far you can create fully functional
+ 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 <a class="xref" href="dml.html" title="Chapter 6. Data Manipulation">Chapter 6</a> and read the
+ rest of this chapter later.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl.html" title="Chapter 5. Data Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-default.html" title="5.2. Default Values">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Data Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.2. Default Values</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-constraints.html b/doc/src/sgml/html/ddl-constraints.html
new file mode 100644
index 0000000..b567f7c
--- /dev/null
+++ b/doc/src/sgml/html/ddl-constraints.html
@@ -0,0 +1,607 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.4. Constraints</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-generated-columns.html" title="5.3. Generated Columns" /><link rel="next" href="ddl-system-columns.html" title="5.5. System Columns" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.4. Constraints</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-generated-columns.html" title="5.3. Generated Columns">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-system-columns.html" title="5.5. System Columns">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-CONSTRAINTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.4. Constraints</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">5.4.1. Check Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#id-1.5.4.6.6">5.4.2. Not-Null Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS">5.4.3. Unique Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-PRIMARY-KEYS">5.4.4. Primary Keys</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-FK">5.4.5. Foreign Keys</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-EXCLUSION">5.4.6. Exclusion Constraints</a></span></dt></dl></div><a id="id-1.5.4.6.2" class="indexterm"></a><p>
+ Data types are a way to limit the kind of data that can be stored
+ in a table. For many applications, however, the constraint they
+ provide is too coarse. For example, a column containing a product
+ price should probably only accept positive values. But there is no
+ standard data type that accepts only positive numbers. Another issue is
+ that you might want to constrain column data with respect to other
+ columns or rows. For example, in a table containing product
+ information, there should be only one row for each product number.
+ </p><p>
+ To that end, SQL allows you to define constraints on columns and
+ tables. Constraints give you as much control over the data in your
+ tables as you wish. If a user attempts to store data in a column
+ that would violate a constraint, an error is raised. This applies
+ even if the value came from the default value definition.
+ </p><div class="sect2" id="DDL-CONSTRAINTS-CHECK-CONSTRAINTS"><div class="titlepage"><div><div><h3 class="title">5.4.1. Check Constraints</h3></div></div></div><a id="id-1.5.4.6.5.2" class="indexterm"></a><a id="id-1.5.4.6.5.3" class="indexterm"></a><p>
+ A check constraint is the most generic constraint type. It allows
+ you to specify that the value in a certain column must satisfy a
+ Boolean (truth-value) expression. For instance, to require positive
+ product prices, you could use:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric <span class="emphasis"><strong>CHECK (price &gt; 0)</strong></span>
+);
+</pre><p>
+ </p><p>
+ As you see, the constraint definition comes after the data type,
+ just like default value definitions. Default values and
+ constraints can be listed in any order. A check constraint
+ consists of the key word <code class="literal">CHECK</code> followed by an
+ expression in parentheses. The check constraint expression should
+ involve the column thus constrained, otherwise the constraint
+ would not make too much sense.
+ </p><a id="id-1.5.4.6.5.6" class="indexterm"></a><p>
+ You can also give the constraint a separate name. This clarifies
+ error messages and allows you to refer to the constraint when you
+ need to change it. The syntax is:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric <span class="emphasis"><strong>CONSTRAINT positive_price</strong></span> CHECK (price &gt; 0)
+);
+</pre><p>
+ So, to specify a named constraint, use the key word
+ <code class="literal">CONSTRAINT</code> followed by an identifier followed
+ by the constraint definition. (If you don't specify a constraint
+ name in this way, the system chooses a name for you.)
+ </p><p>
+ A check constraint can also refer to several columns. Say you
+ store a regular price and a discounted price, and you want to
+ ensure that the discounted price is lower than the regular price:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric CHECK (price &gt; 0),
+ discounted_price numeric CHECK (discounted_price &gt; 0),
+ <span class="emphasis"><strong>CHECK (price &gt; discounted_price)</strong></span>
+);
+</pre><p>
+ </p><p>
+ The first two constraints should look familiar. The third one
+ uses a new syntax. It is not attached to a particular column,
+ instead it appears as a separate item in the comma-separated
+ column list. Column definitions and these constraint
+ definitions can be listed in mixed order.
+ </p><p>
+ We say that the first two constraints are column constraints, whereas the
+ third one is a table constraint because it is written separately
+ from any one column definition. Column constraints can also be
+ written as table constraints, while the reverse is not necessarily
+ possible, since a column constraint is supposed to refer to only the
+ column it is attached to. (<span class="productname">PostgreSQL</span> doesn't
+ enforce that rule, but you should follow it if you want your table
+ definitions to work with other database systems.) The above example could
+ also be written as:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric,
+ CHECK (price &gt; 0),
+ discounted_price numeric,
+ CHECK (discounted_price &gt; 0),
+ CHECK (price &gt; discounted_price)
+);
+</pre><p>
+ or even:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric CHECK (price &gt; 0),
+ discounted_price numeric,
+ CHECK (discounted_price &gt; 0 AND price &gt; discounted_price)
+);
+</pre><p>
+ It's a matter of taste.
+ </p><p>
+ Names can be assigned to table constraints in the same way as
+ column constraints:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric,
+ CHECK (price &gt; 0),
+ discounted_price numeric,
+ CHECK (discounted_price &gt; 0),
+ <span class="emphasis"><strong>CONSTRAINT valid_discount</strong></span> CHECK (price &gt; discounted_price)
+);
+</pre><p>
+ </p><a id="id-1.5.4.6.5.12" class="indexterm"></a><p>
+ It should be noted that a check constraint is satisfied if the
+ check expression evaluates to true or the null value. Since most
+ expressions will evaluate to the null value if any operand is null,
+ they will not prevent null values in the constrained columns. To
+ ensure that a column does not contain null values, the not-null
+ constraint described in the next section can be used.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> does not support
+ <code class="literal">CHECK</code> constraints that reference table data other than
+ the new or updated row being checked. While a <code class="literal">CHECK</code>
+ constraint that violates this rule may appear to work in simple
+ tests, it cannot guarantee that the database will not reach a state
+ in which the constraint condition is false (due to subsequent changes
+ of the other row(s) involved). This would cause a database dump and
+ restore to fail. The restore could fail even when the complete
+ database state is consistent with the constraint, due to rows not
+ being loaded in an order that will satisfy the constraint. If
+ possible, use <code class="literal">UNIQUE</code>, <code class="literal">EXCLUDE</code>,
+ or <code class="literal">FOREIGN KEY</code> constraints to express
+ cross-row and cross-table restrictions.
+ </p><p>
+ If what you desire is a one-time check against other rows at row
+ insertion, rather than a continuously-maintained consistency
+ guarantee, a custom <a class="link" href="triggers.html" title="Chapter 39. Triggers">trigger</a> can be used
+ to implement that. (This approach avoids the dump/restore problem because
+ <span class="application">pg_dump</span> does not reinstall triggers until after
+ restoring data, so that the check will not be enforced during a
+ dump/restore.)
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> assumes that
+ <code class="literal">CHECK</code> constraints' conditions are immutable, that
+ is, they will always give the same result for the same input row.
+ This assumption is what justifies examining <code class="literal">CHECK</code>
+ constraints only when rows are inserted or updated, and not at other
+ times. (The warning above about not referencing other table data is
+ really a special case of this restriction.)
+ </p><p>
+ An example of a common way to break this assumption is to reference a
+ user-defined function in a <code class="literal">CHECK</code> expression, and
+ then change the behavior of that
+ function. <span class="productname">PostgreSQL</span> does not disallow
+ that, but it will not notice if there are rows in the table that now
+ violate the <code class="literal">CHECK</code> constraint. That would cause a
+ subsequent database dump and restore to fail.
+ The recommended way to handle such a change is to drop the constraint
+ (using <code class="command">ALTER TABLE</code>), adjust the function definition,
+ and re-add the constraint, thereby rechecking it against all table rows.
+ </p></div></div><div class="sect2" id="id-1.5.4.6.6"><div class="titlepage"><div><div><h3 class="title">5.4.2. Not-Null Constraints</h3></div></div></div><a id="id-1.5.4.6.6.2" class="indexterm"></a><a id="id-1.5.4.6.6.3" class="indexterm"></a><p>
+ A not-null constraint simply specifies that a column must not
+ assume the null value. A syntax example:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer <span class="emphasis"><strong>NOT NULL</strong></span>,
+ name text <span class="emphasis"><strong>NOT NULL</strong></span>,
+ price numeric
+);
+</pre><p>
+ </p><p>
+ A not-null constraint is always written as a column constraint. A
+ not-null constraint is functionally equivalent to creating a check
+ constraint <code class="literal">CHECK (<em class="replaceable"><code>column_name</code></em>
+ IS NOT NULL)</code>, but in
+ <span class="productname">PostgreSQL</span> creating an explicit
+ not-null constraint is more efficient. The drawback is that you
+ cannot give explicit names to not-null constraints created this
+ way.
+ </p><p>
+ Of course, a column can have more than one constraint. Just write
+ the constraints one after another:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer NOT NULL,
+ name text NOT NULL,
+ price numeric NOT NULL CHECK (price &gt; 0)
+);
+</pre><p>
+ The order doesn't matter. It does not necessarily determine in which
+ order the constraints are checked.
+ </p><p>
+ The <code class="literal">NOT NULL</code> constraint has an inverse: the
+ <code class="literal">NULL</code> constraint. This does not mean that the
+ column must be null, which would surely be useless. Instead, this
+ simply selects the default behavior that the column might be null.
+ The <code class="literal">NULL</code> constraint is not present in the SQL
+ standard and should not be used in portable applications. (It was
+ only added to <span class="productname">PostgreSQL</span> to be
+ compatible with some other database systems.) Some users, however,
+ like it because it makes it easy to toggle the constraint in a
+ script file. For example, you could start with:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer NULL,
+ name text NULL,
+ price numeric NULL
+);
+</pre><p>
+ and then insert the <code class="literal">NOT</code> key word where desired.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ In most database designs the majority of columns should be marked
+ not null.
+ </p></div></div><div class="sect2" id="DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS"><div class="titlepage"><div><div><h3 class="title">5.4.3. Unique Constraints</h3></div></div></div><a id="id-1.5.4.6.7.2" class="indexterm"></a><a id="id-1.5.4.6.7.3" class="indexterm"></a><p>
+ Unique constraints ensure that the data contained in a column, or a
+ group of columns, is unique among all the rows in the
+ table. The syntax is:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer <span class="emphasis"><strong>UNIQUE</strong></span>,
+ name text,
+ price numeric
+);
+</pre><p>
+ when written as a column constraint, and:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric,
+ <span class="emphasis"><strong>UNIQUE (product_no)</strong></span>
+);
+</pre><p>
+ when written as a table constraint.
+ </p><p>
+ To define a unique constraint for a group of columns, write it as a
+ table constraint with the column names separated by commas:
+</p><pre class="programlisting">
+CREATE TABLE example (
+ a integer,
+ b integer,
+ c integer,
+ <span class="emphasis"><strong>UNIQUE (a, c)</strong></span>
+);
+</pre><p>
+ This specifies that the combination of values in the indicated columns
+ is unique across the whole table, though any one of the columns
+ need not be (and ordinarily isn't) unique.
+ </p><p>
+ You can assign your own name for a unique constraint, in the usual way:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer <span class="emphasis"><strong>CONSTRAINT must_be_different</strong></span> UNIQUE,
+ name text,
+ price numeric
+);
+</pre><p>
+ </p><p>
+ Adding a unique constraint will automatically create a unique B-tree
+ index on the column or group of columns listed in the constraint.
+ A uniqueness restriction covering only some rows cannot be written as
+ a unique constraint, but it is possible to enforce such a restriction by
+ creating a unique <a class="link" href="indexes-partial.html" title="11.8. Partial Indexes">partial index</a>.
+ </p><a id="id-1.5.4.6.7.8" class="indexterm"></a><p>
+ In general, a unique constraint is violated if there is more than
+ one row in the table where the values of all of the
+ columns included in the constraint are equal.
+ By default, two null values are not considered equal in this
+ comparison. That means even in the presence of a
+ unique constraint it is possible to store duplicate
+ rows that contain a null value in at least one of the constrained
+ columns. This behavior can be changed by adding the clause <code class="literal">NULLS
+ NOT DISTINCT</code>, like
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer UNIQUE <span class="emphasis"><strong>NULLS NOT DISTINCT</strong></span>,
+ name text,
+ price numeric
+);
+</pre><p>
+ or
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric,
+ UNIQUE <span class="emphasis"><strong>NULLS NOT DISTINCT</strong></span> (product_no)
+);
+</pre><p>
+ The default behavior can be specified explicitly using <code class="literal">NULLS
+ DISTINCT</code>. The default null treatment in unique constraints is
+ implementation-defined according to the SQL standard, and other
+ implementations have a different behavior. So be careful when developing
+ applications that are intended to be portable.
+ </p></div><div class="sect2" id="DDL-CONSTRAINTS-PRIMARY-KEYS"><div class="titlepage"><div><div><h3 class="title">5.4.4. Primary Keys</h3></div></div></div><a id="id-1.5.4.6.8.2" class="indexterm"></a><a id="id-1.5.4.6.8.3" class="indexterm"></a><p>
+ A primary key constraint indicates that a column, or group of columns,
+ can be used as a unique identifier for rows in the table. This
+ requires that the values be both unique and not null. So, the following
+ two table definitions accept the same data:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer UNIQUE NOT NULL,
+ name text,
+ price numeric
+);
+</pre><p>
+
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer <span class="emphasis"><strong>PRIMARY KEY</strong></span>,
+ name text,
+ price numeric
+);
+</pre><p>
+ </p><p>
+ Primary keys can span more than one column; the syntax
+ is similar to unique constraints:
+</p><pre class="programlisting">
+CREATE TABLE example (
+ a integer,
+ b integer,
+ c integer,
+ <span class="emphasis"><strong>PRIMARY KEY (a, c)</strong></span>
+);
+</pre><p>
+ </p><p>
+ Adding a primary key will automatically create a unique B-tree index
+ on the column or group of columns listed in the primary key, and will
+ force the column(s) to be marked <code class="literal">NOT NULL</code>.
+ </p><p>
+ A table can have at most one primary key. (There can be any number
+ of unique and not-null constraints, which are functionally almost the
+ same thing, but only one can be identified as the primary key.)
+ Relational database theory
+ dictates that every table must have a primary key. This rule is
+ not enforced by <span class="productname">PostgreSQL</span>, but it is
+ usually best to follow it.
+ </p><p>
+ Primary keys are useful both for
+ documentation purposes and for client applications. For example,
+ a GUI application that allows modifying row values probably needs
+ to know the primary key of a table to be able to identify rows
+ uniquely. There are also various ways in which the database system
+ makes use of a primary key if one has been declared; for example,
+ the primary key defines the default target column(s) for foreign keys
+ referencing its table.
+ </p></div><div class="sect2" id="DDL-CONSTRAINTS-FK"><div class="titlepage"><div><div><h3 class="title">5.4.5. Foreign Keys</h3></div></div></div><a id="id-1.5.4.6.9.2" class="indexterm"></a><a id="id-1.5.4.6.9.3" class="indexterm"></a><a id="id-1.5.4.6.9.4" class="indexterm"></a><p>
+ A foreign key constraint specifies that the values in a column (or
+ a group of columns) must match the values appearing in some row
+ of another table.
+ We say this maintains the <em class="firstterm">referential
+ integrity</em> between two related tables.
+ </p><p>
+ Say you have the product table that we have used several times already:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer PRIMARY KEY,
+ name text,
+ price numeric
+);
+</pre><p>
+ Let's also assume you have a table storing orders of those
+ products. We want to ensure that the orders table only contains
+ orders of products that actually exist. So we define a foreign
+ key constraint in the orders table that references the products
+ table:
+</p><pre class="programlisting">
+CREATE TABLE orders (
+ order_id integer PRIMARY KEY,
+ product_no integer <span class="emphasis"><strong>REFERENCES products (product_no)</strong></span>,
+ quantity integer
+);
+</pre><p>
+ Now it is impossible to create orders with non-NULL
+ <code class="structfield">product_no</code> entries that do not appear in the
+ products table.
+ </p><p>
+ We say that in this situation the orders table is the
+ <em class="firstterm">referencing</em> table and the products table is
+ the <em class="firstterm">referenced</em> table. Similarly, there are
+ referencing and referenced columns.
+ </p><p>
+ You can also shorten the above command to:
+</p><pre class="programlisting">
+CREATE TABLE orders (
+ order_id integer PRIMARY KEY,
+ product_no integer <span class="emphasis"><strong>REFERENCES products</strong></span>,
+ quantity integer
+);
+</pre><p>
+ because in absence of a column list the primary key of the
+ referenced table is used as the referenced column(s).
+ </p><p>
+ You can assign your own name for a foreign key constraint,
+ in the usual way.
+ </p><p>
+ A foreign key can also constrain and reference a group of columns.
+ As usual, it then needs to be written in table constraint form.
+ Here is a contrived syntax example:
+</p><pre class="programlisting">
+CREATE TABLE t1 (
+ a integer PRIMARY KEY,
+ b integer,
+ c integer,
+ <span class="emphasis"><strong>FOREIGN KEY (b, c) REFERENCES other_table (c1, c2)</strong></span>
+);
+</pre><p>
+ Of course, the number and type of the constrained columns need to
+ match the number and type of the referenced columns.
+ </p><a id="id-1.5.4.6.9.11" class="indexterm"></a><p>
+ Sometimes it is useful for the <span class="quote">“<span class="quote">other table</span>”</span> of a
+ foreign key constraint to be the same table; this is called
+ a <em class="firstterm">self-referential</em> foreign key. For
+ example, if you want rows of a table to represent nodes of a tree
+ structure, you could write
+</p><pre class="programlisting">
+CREATE TABLE tree (
+ node_id integer PRIMARY KEY,
+ parent_id integer REFERENCES tree,
+ name text,
+ ...
+);
+</pre><p>
+ A top-level node would have NULL <code class="structfield">parent_id</code>,
+ while non-NULL <code class="structfield">parent_id</code> entries would be
+ constrained to reference valid rows of the table.
+ </p><p>
+ A table can have more than one foreign key constraint. This is
+ used to implement many-to-many relationships between tables. Say
+ you have tables about products and orders, but now you want to
+ allow one order to contain possibly many products (which the
+ structure above did not allow). You could use this table structure:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer PRIMARY KEY,
+ name text,
+ price numeric
+);
+
+CREATE TABLE orders (
+ order_id integer PRIMARY KEY,
+ shipping_address text,
+ ...
+);
+
+CREATE TABLE order_items (
+ product_no integer REFERENCES products,
+ order_id integer REFERENCES orders,
+ quantity integer,
+ PRIMARY KEY (product_no, order_id)
+);
+</pre><p>
+ Notice that the primary key overlaps with the foreign keys in
+ the last table.
+ </p><a id="id-1.5.4.6.9.14" class="indexterm"></a><a id="id-1.5.4.6.9.15" class="indexterm"></a><p>
+ We know that the foreign keys disallow creation of orders that
+ do not relate to any products. But what if a product is removed
+ after an order is created that references it? SQL allows you to
+ handle that as well. Intuitively, we have a few options:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>Disallow deleting a referenced product</p></li><li class="listitem"><p>Delete the orders as well</p></li><li class="listitem"><p>Something else?</p></li></ul></div><p>
+ </p><p>
+ To illustrate this, let's implement the following policy on the
+ many-to-many relationship example above: when someone wants to
+ remove a product that is still referenced by an order (via
+ <code class="literal">order_items</code>), we disallow it. If someone
+ removes an order, the order items are removed as well:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer PRIMARY KEY,
+ name text,
+ price numeric
+);
+
+CREATE TABLE orders (
+ order_id integer PRIMARY KEY,
+ shipping_address text,
+ ...
+);
+
+CREATE TABLE order_items (
+ product_no integer REFERENCES products <span class="emphasis"><strong>ON DELETE RESTRICT</strong></span>,
+ order_id integer REFERENCES orders <span class="emphasis"><strong>ON DELETE CASCADE</strong></span>,
+ quantity integer,
+ PRIMARY KEY (product_no, order_id)
+);
+</pre><p>
+ </p><p>
+ Restricting and cascading deletes are the two most common options.
+ <code class="literal">RESTRICT</code> prevents deletion of a
+ referenced row. <code class="literal">NO ACTION</code> means that if any
+ referencing rows still exist when the constraint is checked, an error
+ is raised; this is the default behavior if you do not specify anything.
+ (The essential difference between these two choices is that
+ <code class="literal">NO ACTION</code> allows the check to be deferred until
+ later in the transaction, whereas <code class="literal">RESTRICT</code> does not.)
+ <code class="literal">CASCADE</code> specifies that when a referenced row is deleted,
+ row(s) referencing it should be automatically deleted as well.
+ There are two other options:
+ <code class="literal">SET NULL</code> and <code class="literal">SET DEFAULT</code>.
+ These cause the referencing column(s) in the referencing row(s)
+ to be set to nulls or their default
+ values, respectively, when the referenced row is deleted.
+ Note that these do not excuse you from observing any constraints.
+ For example, if an action specifies <code class="literal">SET DEFAULT</code>
+ but the default value would not satisfy the foreign key constraint, the
+ operation will fail.
+ </p><p>
+ The appropriate choice of <code class="literal">ON DELETE</code> action depends on
+ what kinds of objects the related tables represent. When the referencing
+ table represents something that is a component of what is represented by
+ the referenced table and cannot exist independently, then
+ <code class="literal">CASCADE</code> could be appropriate. If the two tables
+ represent independent objects, then <code class="literal">RESTRICT</code> or
+ <code class="literal">NO ACTION</code> is more appropriate; an application that
+ actually wants to delete both objects would then have to be explicit about
+ this and run two delete commands. In the above example, order items are
+ part of an order, and it is convenient if they are deleted automatically
+ if an order is deleted. But products and orders are different things, and
+ so making a deletion of a product automatically cause the deletion of some
+ order items could be considered problematic. The actions <code class="literal">SET
+ NULL</code> or <code class="literal">SET DEFAULT</code> can be appropriate if a
+ foreign-key relationship represents optional information. For example, if
+ the products table contained a reference to a product manager, and the
+ product manager entry gets deleted, then setting the product's product
+ manager to null or a default might be useful.
+ </p><p>
+ The actions <code class="literal">SET NULL</code> and <code class="literal">SET DEFAULT</code>
+ can take a column list to specify which columns to set. Normally, all
+ columns of the foreign-key constraint are set; setting only a subset is
+ useful in some special cases. Consider the following example:
+</p><pre class="programlisting">
+CREATE TABLE tenants (
+ tenant_id integer PRIMARY KEY
+);
+
+CREATE TABLE users (
+ tenant_id integer REFERENCES tenants ON DELETE CASCADE,
+ user_id integer NOT NULL,
+ PRIMARY KEY (tenant_id, user_id)
+);
+
+CREATE TABLE posts (
+ tenant_id integer REFERENCES tenants ON DELETE CASCADE,
+ post_id integer NOT NULL,
+ author_id integer,
+ PRIMARY KEY (tenant_id, post_id),
+ FOREIGN KEY (tenant_id, author_id) REFERENCES users ON DELETE SET NULL <span class="emphasis"><strong>(author_id)</strong></span>
+);
+</pre><p>
+ Without the specification of the column, the foreign key would also set
+ the column <code class="literal">tenant_id</code> to null, but that column is still
+ required as part of the primary key.
+ </p><p>
+ Analogous to <code class="literal">ON DELETE</code> there is also
+ <code class="literal">ON UPDATE</code> which is invoked when a referenced
+ column is changed (updated). The possible actions are the same,
+ except that column lists cannot be specified for <code class="literal">SET
+ NULL</code> and <code class="literal">SET DEFAULT</code>.
+ In this case, <code class="literal">CASCADE</code> means that the updated values of the
+ referenced column(s) should be copied into the referencing row(s).
+ </p><p>
+ Normally, a referencing row need not satisfy the foreign key constraint
+ if any of its referencing columns are null. If <code class="literal">MATCH FULL</code>
+ is added to the foreign key declaration, a referencing row escapes
+ satisfying the constraint only if all its referencing columns are null
+ (so a mix of null and non-null values is guaranteed to fail a
+ <code class="literal">MATCH FULL</code> constraint). If you don't want referencing rows
+ to be able to avoid satisfying the foreign key constraint, declare the
+ referencing column(s) as <code class="literal">NOT NULL</code>.
+ </p><p>
+ A foreign key must reference columns that either are a primary key or
+ form a unique constraint. This means that the referenced columns always
+ have an index (the one underlying the primary key or unique constraint);
+ so checks on whether a referencing row has a match will be efficient.
+ Since a <code class="command">DELETE</code> of a row from the referenced table
+ or an <code class="command">UPDATE</code> of a referenced column will require
+ a scan of the referencing table for rows matching the old value, it
+ is often a good idea to index the referencing columns too. Because this
+ is not always needed, and there are many choices available on how
+ to index, declaration of a foreign key constraint does not
+ automatically create an index on the referencing columns.
+ </p><p>
+ More information about updating and deleting data is in <a class="xref" href="dml.html" title="Chapter 6. Data Manipulation">Chapter 6</a>. Also see the description of foreign key constraint
+ syntax in the reference documentation for
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>.
+ </p></div><div class="sect2" id="DDL-CONSTRAINTS-EXCLUSION"><div class="titlepage"><div><div><h3 class="title">5.4.6. Exclusion Constraints</h3></div></div></div><a id="id-1.5.4.6.10.2" class="indexterm"></a><a id="id-1.5.4.6.10.3" class="indexterm"></a><p>
+ Exclusion constraints ensure that if any two rows are compared on
+ the specified columns or expressions using the specified operators,
+ at least one of these operator comparisons will return false or null.
+ The syntax is:
+</p><pre class="programlisting">
+CREATE TABLE circles (
+ c circle,
+ EXCLUDE USING gist (c WITH &amp;&amp;)
+);
+</pre><p>
+ </p><p>
+ See also <a class="link" href="sql-createtable.html#SQL-CREATETABLE-EXCLUDE"><code class="command">CREATE
+ TABLE ... CONSTRAINT ... EXCLUDE</code></a> for details.
+ </p><p>
+ Adding an exclusion constraint will automatically create an index
+ of the type specified in the constraint declaration.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-generated-columns.html" title="5.3. Generated Columns">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-system-columns.html" title="5.5. System Columns">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.3. Generated Columns </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.5. System Columns</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-default.html b/doc/src/sgml/html/ddl-default.html
new file mode 100644
index 0000000..43c7883
--- /dev/null
+++ b/doc/src/sgml/html/ddl-default.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.2. Default Values</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-basics.html" title="5.1. Table Basics" /><link rel="next" href="ddl-generated-columns.html" title="5.3. Generated Columns" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.2. Default Values</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-basics.html" title="5.1. Table Basics">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-generated-columns.html" title="5.3. Generated Columns">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-DEFAULT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.2. Default Values</h2></div></div></div><a id="id-1.5.4.4.2" class="indexterm"></a><p>
+ A column can be assigned a default value. When a new row is
+ created and no values are specified for some of the columns, those
+ 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 <a class="xref" href="dml.html" title="Chapter 6. Data Manipulation">Chapter 6</a>.)
+ </p><p>
+ <a id="id-1.5.4.4.4.1" class="indexterm"></a>
+ If no default value is declared explicitly, the default value is the
+ null value. This usually makes sense because a null value can
+ be considered to represent unknown data.
+ </p><p>
+ In a table definition, default values are listed after the column
+ data type. For example:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric <span class="emphasis"><strong>DEFAULT 9.99</strong></span>
+);
+</pre><p>
+ </p><p>
+ The default value can be an expression, which will be
+ evaluated whenever the default value is inserted
+ (<span class="emphasis"><em>not</em></span> when the table is created). A common example
+ is for a <code class="type">timestamp</code> column to have a default of <code class="literal">CURRENT_TIMESTAMP</code>,
+ so that it gets set to the time of row insertion. Another common
+ example is generating a <span class="quote">“<span class="quote">serial number</span>”</span> for each row.
+ In <span class="productname">PostgreSQL</span> this is typically done by
+ something like:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer <span class="emphasis"><strong>DEFAULT nextval('products_product_no_seq')</strong></span>,
+ ...
+);
+</pre><p>
+ where the <code class="literal">nextval()</code> function supplies successive values
+ from a <em class="firstterm">sequence object</em> (see <a class="xref" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Section 9.17</a>). This arrangement is sufficiently common
+ that there's a special shorthand for it:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no <span class="emphasis"><strong>SERIAL</strong></span>,
+ ...
+);
+</pre><p>
+ The <code class="literal">SERIAL</code> shorthand is discussed further in <a class="xref" href="datatype-numeric.html#DATATYPE-SERIAL" title="8.1.4. Serial Types">Section 8.1.4</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-basics.html" title="5.1. Table Basics">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-generated-columns.html" title="5.3. Generated Columns">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.1. Table Basics </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.3. Generated Columns</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-depend.html b/doc/src/sgml/html/ddl-depend.html
new file mode 100644
index 0000000..ed1be7d
--- /dev/null
+++ b/doc/src/sgml/html/ddl-depend.html
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.14. Dependency Tracking</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-others.html" title="5.13. Other Database Objects" /><link rel="next" href="dml.html" title="Chapter 6. Data Manipulation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.14. Dependency Tracking</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-others.html" title="5.13. Other Database Objects">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dml.html" title="Chapter 6. Data Manipulation">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-DEPEND"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.14. Dependency Tracking</h2></div></div></div><a id="id-1.5.4.16.2" class="indexterm"></a><a id="id-1.5.4.16.3" class="indexterm"></a><p>
+ When you create complex database structures involving many tables
+ with foreign key constraints, views, triggers, functions, etc. you
+ implicitly create a net of dependencies between the objects.
+ For instance, a table with a foreign key constraint depends on the
+ table it references.
+ </p><p>
+ To ensure the integrity of the entire database structure,
+ <span class="productname">PostgreSQL</span> makes sure that you cannot
+ drop objects that other objects still depend on. For example,
+ attempting to drop the products table we considered in <a class="xref" href="ddl-constraints.html#DDL-CONSTRAINTS-FK" title="5.4.5. Foreign Keys">Section 5.4.5</a>, with the orders table depending on
+ it, would result in an error message like this:
+</p><pre class="screen">
+DROP TABLE products;
+
+ERROR: cannot drop table products because other objects depend on it
+DETAIL: constraint orders_product_no_fkey on table orders depends on table products
+HINT: Use DROP ... CASCADE to drop the dependent objects too.
+</pre><p>
+ The error message contains a useful hint: if you do not want to
+ bother deleting all the dependent objects individually, you can run:
+</p><pre class="screen">
+DROP TABLE products CASCADE;
+</pre><p>
+ and all the dependent objects will be removed, as will any objects
+ that depend on them, recursively. In this case, it doesn't remove
+ the orders table, it only removes the foreign key constraint.
+ It stops there because nothing depends on the foreign key constraint.
+ (If you want to check what <code class="command">DROP ... CASCADE</code> will do,
+ run <code class="command">DROP</code> without <code class="literal">CASCADE</code> and read the
+ <code class="literal">DETAIL</code> output.)
+ </p><p>
+ Almost all <code class="command">DROP</code> commands in <span class="productname">PostgreSQL</span> support
+ specifying <code class="literal">CASCADE</code>. Of course, the nature of
+ the possible dependencies varies with the type of the object. You
+ can also write <code class="literal">RESTRICT</code> instead of
+ <code class="literal">CASCADE</code> to get the default behavior, which is to
+ prevent dropping objects that any other objects depend on.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ According to the SQL standard, specifying either
+ <code class="literal">RESTRICT</code> or <code class="literal">CASCADE</code> is
+ required in a <code class="command">DROP</code> command. No database system actually
+ enforces that rule, but whether the default behavior
+ is <code class="literal">RESTRICT</code> or <code class="literal">CASCADE</code> varies
+ across systems.
+ </p></div><p>
+ If a <code class="command">DROP</code> command lists multiple
+ objects, <code class="literal">CASCADE</code> is only required when there are
+ dependencies outside the specified group. For example, when saying
+ <code class="literal">DROP TABLE tab1, tab2</code> the existence of a foreign
+ key referencing <code class="literal">tab1</code> from <code class="literal">tab2</code> would not mean
+ that <code class="literal">CASCADE</code> is needed to succeed.
+ </p><p>
+ For a user-defined function or procedure whose body is defined as a string
+ literal, <span class="productname">PostgreSQL</span> tracks
+ dependencies associated with the function's externally-visible properties,
+ such as its argument and result types, but <span class="emphasis"><em>not</em></span> dependencies
+ that could only be known by examining the function body. As an example,
+ consider this situation:
+
+</p><pre class="programlisting">
+CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow',
+ 'green', 'blue', 'purple');
+
+CREATE TABLE my_colors (color rainbow, note text);
+
+CREATE FUNCTION get_color_note (rainbow) RETURNS text AS
+ 'SELECT note FROM my_colors WHERE color = $1'
+ LANGUAGE SQL;
+</pre><p>
+
+ (See <a class="xref" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Section 38.5</a> for an explanation of SQL-language
+ functions.) <span class="productname">PostgreSQL</span> will be aware that
+ the <code class="function">get_color_note</code> function depends on the <code class="type">rainbow</code>
+ type: dropping the type would force dropping the function, because its
+ argument type would no longer be defined. But <span class="productname">PostgreSQL</span>
+ will not consider <code class="function">get_color_note</code> to depend on
+ the <code class="structname">my_colors</code> table, and so will not drop the function if
+ the table is dropped. While there are disadvantages to this approach,
+ there are also benefits. The function is still valid in some sense if the
+ table is missing, though executing it would cause an error; creating a new
+ table of the same name would allow the function to work again.
+ </p><p>
+ On the other hand, for a SQL-language function or procedure whose body
+ is written in SQL-standard style, the body is parsed at function
+ definition time and all dependencies recognized by the parser are
+ stored. Thus, if we write the function above as
+
+</p><pre class="programlisting">
+CREATE FUNCTION get_color_note (rainbow) RETURNS text
+BEGIN ATOMIC
+ SELECT note FROM my_colors WHERE color = $1;
+END;
+</pre><p>
+
+ then the function's dependency on the <code class="structname">my_colors</code>
+ table will be known and enforced by <code class="command">DROP</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-others.html" title="5.13. Other Database Objects">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dml.html" title="Chapter 6. Data Manipulation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.13. Other Database Objects </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Data Manipulation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-foreign-data.html b/doc/src/sgml/html/ddl-foreign-data.html
new file mode 100644
index 0000000..e3b2ed9
--- /dev/null
+++ b/doc/src/sgml/html/ddl-foreign-data.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.12. Foreign Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-partitioning.html" title="5.11. Table Partitioning" /><link rel="next" href="ddl-others.html" title="5.13. Other Database Objects" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.12. Foreign Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-partitioning.html" title="5.11. Table Partitioning">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-others.html" title="5.13. Other Database Objects">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-FOREIGN-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.12. Foreign Data</h2></div></div></div><a id="id-1.5.4.14.2" class="indexterm"></a><a id="id-1.5.4.14.3" class="indexterm"></a><a id="id-1.5.4.14.4" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> implements portions of the SQL/MED
+ specification, allowing you to access data that resides outside
+ PostgreSQL using regular SQL queries. Such data is referred to as
+ <em class="firstterm">foreign data</em>. (Note that this usage is not to be confused
+ with foreign keys, which are a type of constraint within the database.)
+ </p><p>
+ Foreign data is accessed with help from a
+ <em class="firstterm">foreign data wrapper</em>. A foreign data wrapper is a
+ 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 <code class="filename">contrib</code>
+ modules; see <a class="xref" href="contrib.html" title="Appendix F. Additional Supplied Modules">Appendix F</a>. 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 <a class="xref" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Chapter 59</a>.
+ </p><p>
+ To access foreign data, you need to create a <em class="firstterm">foreign server</em>
+ object, which defines how to connect to a particular external data source
+ according to the set of options used by its supporting foreign data
+ wrapper. Then you need to create one or more <em class="firstterm">foreign
+ tables</em>, which define the structure of the remote data. A
+ foreign table can be used in queries just like a normal table, but a
+ foreign table has no storage in the PostgreSQL server. Whenever it is
+ used, <span class="productname">PostgreSQL</span> asks the foreign data wrapper
+ to fetch data from the external source, or transmit data to the external
+ source in the case of update commands.
+ </p><p>
+ Accessing remote data may require authenticating to the external
+ data source. This information can be provided by a
+ <em class="firstterm">user mapping</em>, which can provide additional data
+ such as user names and passwords based
+ on the current <span class="productname">PostgreSQL</span> role.
+ </p><p>
+ For additional information, see
+ <a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>,
+ <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>,
+ <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>,
+ <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>, and
+ <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-partitioning.html" title="5.11. Table Partitioning">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-others.html" title="5.13. Other Database Objects">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.11. Table Partitioning </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.13. Other Database Objects</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-generated-columns.html b/doc/src/sgml/html/ddl-generated-columns.html
new file mode 100644
index 0000000..707b52a
--- /dev/null
+++ b/doc/src/sgml/html/ddl-generated-columns.html
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.3. Generated Columns</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-default.html" title="5.2. Default Values" /><link rel="next" href="ddl-constraints.html" title="5.4. Constraints" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.3. Generated Columns</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-default.html" title="5.2. Default Values">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-constraints.html" title="5.4. Constraints">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-GENERATED-COLUMNS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.3. Generated Columns</h2></div></div></div><a id="id-1.5.4.5.2" class="indexterm"></a><p>
+ A generated column is a special column that is always computed from other
+ columns. Thus, it is for columns what a view is for tables. There are two
+ kinds of generated columns: stored and virtual. A stored generated column
+ is computed when it is written (inserted or updated) and occupies storage
+ as if it were a normal column. A virtual generated column occupies no
+ storage and is computed when it is read. Thus, a virtual generated column
+ is similar to a view and a stored generated column is similar to a
+ materialized view (except that it is always updated automatically).
+ PostgreSQL currently implements only stored generated columns.
+ </p><p>
+ To create a generated column, use the <code class="literal">GENERATED ALWAYS
+ AS</code> clause in <code class="command">CREATE TABLE</code>, for example:
+</p><pre class="programlisting">
+CREATE TABLE people (
+ ...,
+ height_cm numeric,
+ height_in numeric <span class="emphasis"><strong>GENERATED ALWAYS AS (height_cm / 2.54) STORED</strong></span>
+);
+</pre><p>
+ The keyword <code class="literal">STORED</code> must be specified to choose the
+ stored kind of generated column. See <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for
+ more details.
+ </p><p>
+ A generated column cannot be written to directly. In
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code> commands, a value
+ cannot be specified for a generated column, but the keyword
+ <code class="literal">DEFAULT</code> may be specified.
+ </p><p>
+ Consider the differences between a column with a default and a generated
+ column. The column default is evaluated once when the row is first
+ inserted if no other value was provided; a generated column is updated
+ whenever the row changes and cannot be overridden. A column default may
+ not refer to other columns of the table; a generation expression would
+ normally do so. A column default can use volatile functions, for example
+ <code class="literal">random()</code> or functions referring to the current time;
+ this is not allowed for generated columns.
+ </p><p>
+ Several restrictions apply to the definition of generated columns and
+ tables involving generated columns:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The generation expression can only use immutable functions and cannot
+ use subqueries or reference anything other than the current row in any
+ way.
+ </p></li><li class="listitem"><p>
+ A generation expression cannot reference another generated column.
+ </p></li><li class="listitem"><p>
+ A generation expression cannot reference a system column, except
+ <code class="varname">tableoid</code>.
+ </p></li><li class="listitem"><p>
+ A generated column cannot have a column default or an identity definition.
+ </p></li><li class="listitem"><p>
+ A generated column cannot be part of a partition key.
+ </p></li><li class="listitem"><p>
+ Foreign tables can have generated columns. See <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a> for details.
+ </p></li><li class="listitem"><p>For inheritance:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ If a parent column is a generated column, a child column must also be
+ a generated column using the same expression. In the definition of
+ the child column, leave off the <code class="literal">GENERATED</code> clause,
+ as it will be copied from the parent.
+ </p></li><li class="listitem"><p>
+ In case of multiple inheritance, if one parent column is a generated
+ column, then all parent columns must be generated columns and with the
+ same expression.
+ </p></li><li class="listitem"><p>
+ If a parent column is not a generated column, a child column may be
+ defined to be a generated column or not.
+ </p></li></ul></div></li></ul></div><p>
+ </p><p>
+ Additional considerations apply to the use of generated columns.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Generated columns maintain access privileges separately from their
+ underlying base columns. So, it is possible to arrange it so that a
+ particular role can read from a generated column but not from the
+ underlying base columns.
+ </p></li><li class="listitem"><p>
+ Generated columns are, conceptually, updated after
+ <code class="literal">BEFORE</code> triggers have run. Therefore, changes made to
+ base columns in a <code class="literal">BEFORE</code> trigger will be reflected in
+ generated columns. But conversely, it is not allowed to access
+ generated columns in <code class="literal">BEFORE</code> triggers.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-default.html" title="5.2. Default Values">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-constraints.html" title="5.4. Constraints">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.2. Default Values </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.4. Constraints</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-inherit.html b/doc/src/sgml/html/ddl-inherit.html
new file mode 100644
index 0000000..c2e7efa
--- /dev/null
+++ b/doc/src/sgml/html/ddl-inherit.html
@@ -0,0 +1,289 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.10. Inheritance</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-schemas.html" title="5.9. Schemas" /><link rel="next" href="ddl-partitioning.html" title="5.11. Table Partitioning" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.10. Inheritance</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-schemas.html" title="5.9. Schemas">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-partitioning.html" title="5.11. Table Partitioning">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-INHERIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.10. Inheritance</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ddl-inherit.html#DDL-INHERIT-CAVEATS">5.10.1. Caveats</a></span></dt></dl></div><a id="id-1.5.4.12.2" class="indexterm"></a><a id="id-1.5.4.12.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> implements table inheritance,
+ which can be a useful tool for database designers. (SQL:1999 and
+ later define a type inheritance feature, which differs in many
+ respects from the features described here.)
+ </p><p>
+ Let's start with an example: suppose we are trying to build a data
+ model for cities. Each state has many cities, but only one
+ capital. We want to be able to quickly retrieve the capital city
+ for any particular state. This can be done by creating two tables,
+ one for state capitals and one for cities that are not
+ capitals. However, what happens when we want to ask for data about
+ a city, regardless of whether it is a capital or not? The
+ inheritance feature can help to resolve this problem. We define the
+ <code class="structname">capitals</code> table so that it inherits from
+ <code class="structname">cities</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE cities (
+ name text,
+ population float,
+ elevation int -- in feet
+);
+
+CREATE TABLE capitals (
+ state char(2)
+) INHERITS (cities);
+</pre><p>
+
+ In this case, the <code class="structname">capitals</code> table <em class="firstterm">inherits</em>
+ all the columns of its parent table, <code class="structname">cities</code>. State
+ capitals also have an extra column, <code class="structfield">state</code>, that shows
+ their state.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, a table can inherit from
+ zero or more other tables, and a query can reference either all
+ rows of a table or all rows of a table plus all of its descendant tables.
+ The latter behavior is the default.
+ For example, the following query finds the names of all cities,
+ including state capitals, that are located at an elevation over
+ 500 feet:
+
+</p><pre class="programlisting">
+SELECT name, elevation
+ FROM cities
+ WHERE elevation &gt; 500;
+</pre><p>
+
+ Given the sample data from the <span class="productname">PostgreSQL</span>
+ tutorial (see <a class="xref" href="tutorial-sql-intro.html" title="2.1. Introduction">Section 2.1</a>), this returns:
+
+</p><pre class="programlisting">
+ name | elevation
+-----------+-----------
+ Las Vegas | 2174
+ Mariposa | 1953
+ Madison | 845
+</pre><p>
+ </p><p>
+ On the other hand, the following query finds all the cities that
+ are not state capitals and are situated at an elevation over 500 feet:
+
+</p><pre class="programlisting">
+SELECT name, elevation
+ FROM ONLY cities
+ WHERE elevation &gt; 500;
+
+ name | elevation
+-----------+-----------
+ Las Vegas | 2174
+ Mariposa | 1953
+</pre><p>
+ </p><p>
+ Here the <code class="literal">ONLY</code> keyword indicates that the query
+ should apply only to <code class="structname">cities</code>, and not any tables
+ below <code class="structname">cities</code> in the inheritance hierarchy. Many
+ of the commands that we have already discussed —
+ <code class="command">SELECT</code>, <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code> — support the
+ <code class="literal">ONLY</code> keyword.
+ </p><p>
+ You can also write the table name with a trailing <code class="literal">*</code>
+ to explicitly specify that descendant tables are included:
+
+</p><pre class="programlisting">
+SELECT name, elevation
+ FROM cities*
+ WHERE elevation &gt; 500;
+</pre><p>
+
+ Writing <code class="literal">*</code> is not necessary, since this behavior is always
+ the default. However, this syntax is still supported for
+ compatibility with older releases where the default could be changed.
+ </p><p>
+ In some cases you might wish to know which table a particular row
+ originated from. There is a system column called
+ <code class="structfield">tableoid</code> in each table which can tell you the
+ originating table:
+
+</p><pre class="programlisting">
+SELECT c.tableoid, c.name, c.elevation
+FROM cities c
+WHERE c.elevation &gt; 500;
+</pre><p>
+
+ which returns:
+
+</p><pre class="programlisting">
+ tableoid | name | elevation
+----------+-----------+-----------
+ 139793 | Las Vegas | 2174
+ 139793 | Mariposa | 1953
+ 139798 | Madison | 845
+</pre><p>
+
+ (If you try to reproduce this example, you will probably get
+ different numeric OIDs.) By doing a join with
+ <code class="structname">pg_class</code> you can see the actual table names:
+
+</p><pre class="programlisting">
+SELECT p.relname, c.name, c.elevation
+FROM cities c, pg_class p
+WHERE c.elevation &gt; 500 AND c.tableoid = p.oid;
+</pre><p>
+
+ which returns:
+
+</p><pre class="programlisting">
+ relname | name | elevation
+----------+-----------+-----------
+ cities | Las Vegas | 2174
+ cities | Mariposa | 1953
+ capitals | Madison | 845
+</pre><p>
+ </p><p>
+ Another way to get the same effect is to use the <code class="type">regclass</code>
+ alias type, which will print the table OID symbolically:
+
+</p><pre class="programlisting">
+SELECT c.tableoid::regclass, c.name, c.elevation
+FROM cities c
+WHERE c.elevation &gt; 500;
+</pre><p>
+ </p><p>
+ Inheritance does not automatically propagate data from
+ <code class="command">INSERT</code> or <code class="command">COPY</code> commands to
+ other tables in the inheritance hierarchy. In our example, the
+ following <code class="command">INSERT</code> statement will fail:
+</p><pre class="programlisting">
+INSERT INTO cities (name, population, elevation, state)
+VALUES ('Albany', NULL, NULL, 'NY');
+</pre><p>
+ We might hope that the data would somehow be routed to the
+ <code class="structname">capitals</code> table, but this does not happen:
+ <code class="command">INSERT</code> always inserts into exactly the table
+ specified. In some cases it is possible to redirect the insertion
+ using a rule (see <a class="xref" href="rules.html" title="Chapter 41. The Rule System">Chapter 41</a>). However that does not
+ help for the above case because the <code class="structname">cities</code> table
+ does not contain the column <code class="structfield">state</code>, and so the
+ command will be rejected before the rule can be applied.
+ </p><p>
+ All check constraints and not-null constraints on a parent table are
+ automatically inherited by its children, unless explicitly specified
+ otherwise with <code class="literal">NO INHERIT</code> clauses. Other types of constraints
+ (unique, primary key, and foreign key constraints) are not inherited.
+ </p><p>
+ A table can inherit from more than one parent table, in which case it has
+ the union of the columns defined by the parent tables. Any columns
+ declared in the child table's definition are added to these. If the
+ same column name appears in multiple parent tables, or in both a parent
+ table and the child's definition, then these columns are <span class="quote">“<span class="quote">merged</span>”</span>
+ so that there is only one such column in the child table. To be merged,
+ columns must have the same data types, else an error is raised.
+ Inheritable check constraints and not-null constraints are merged in a
+ similar fashion. Thus, for example, a merged column will be marked
+ not-null if any one of the column definitions it came from is marked
+ not-null. Check constraints are merged if they have the same name,
+ and the merge will fail if their conditions are different.
+ </p><p>
+ Table inheritance is typically established when the child table is
+ created, using the <code class="literal">INHERITS</code> clause of the
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>
+ statement.
+ Alternatively, a table which is already defined in a compatible way can
+ have a new parent relationship added, using the <code class="literal">INHERIT</code>
+ variant of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>.
+ 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
+ parent. Similarly an inheritance link can be removed from a child using the
+ <code class="literal">NO INHERIT</code> variant of <code class="command">ALTER TABLE</code>.
+ Dynamically adding and removing inheritance links like this can be useful
+ when the inheritance relationship is being used for table
+ partitioning (see <a class="xref" href="ddl-partitioning.html" title="5.11. Table Partitioning">Section 5.11</a>).
+ </p><p>
+ One convenient way to create a compatible table that will later be made
+ a new child is to use the <code class="literal">LIKE</code> clause in <code class="command">CREATE
+ TABLE</code>. This creates a new table with the same columns as
+ the source table. If there are any <code class="literal">CHECK</code>
+ constraints defined on the source table, the <code class="literal">INCLUDING
+ CONSTRAINTS</code> option to <code class="literal">LIKE</code> should be
+ specified, as the new child must have constraints matching the parent
+ to be considered compatible.
+ </p><p>
+ A parent table cannot be dropped while any of its children remain. Neither
+ can columns or check constraints of child tables be dropped or altered
+ 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
+ <code class="literal">CASCADE</code> option (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p><p>
+ <code class="command">ALTER TABLE</code> 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
+ the <code class="literal">CASCADE</code> option. <code class="command">ALTER
+ TABLE</code> follows the same rules for duplicate column merging
+ and rejection that apply during <code class="command">CREATE TABLE</code>.
+ </p><p>
+ Inherited queries perform access permission checks on the parent table
+ only. Thus, for example, granting <code class="literal">UPDATE</code> permission on
+ the <code class="structname">cities</code> table implies permission to update rows in
+ the <code class="structname">capitals</code> table as well, when they are
+ accessed through <code class="structname">cities</code>. This preserves the appearance
+ that the data is (also) in the parent table. But
+ the <code class="structname">capitals</code> table could not be updated directly
+ without an additional grant. In a similar way, the parent table's row
+ security policies (see <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a>) are applied to
+ rows coming from child tables during an inherited query. A child table's
+ policies, if any, are applied only when it is the table explicitly named
+ in the query; and in that case, any policies attached to its parent(s) are
+ ignored.
+ </p><p>
+ Foreign tables (see <a class="xref" href="ddl-foreign-data.html" title="5.12. Foreign Data">Section 5.12</a>) 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
+ the foreign table are not supported on the whole hierarchy either.
+ </p><div class="sect2" id="DDL-INHERIT-CAVEATS"><div class="titlepage"><div><div><h3 class="title">5.10.1. Caveats</h3></div></div></div><p>
+ Note that not all SQL commands are able to work on
+ inheritance hierarchies. Commands that are used for data querying,
+ data modification, or schema modification
+ (e.g., <code class="literal">SELECT</code>, <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>,
+ most variants of <code class="literal">ALTER TABLE</code>, but
+ not <code class="literal">INSERT</code> or <code class="literal">ALTER TABLE ...
+ RENAME</code>) typically default to including child tables and
+ support the <code class="literal">ONLY</code> notation to exclude them.
+ Commands that do database maintenance and tuning
+ (e.g., <code class="literal">REINDEX</code>, <code class="literal">VACUUM</code>)
+ 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 (<a class="xref" href="sql-commands.html" title="SQL Commands">SQL Commands</a>).
+ </p><p>
+ A serious limitation of the inheritance feature is that indexes (including
+ unique constraints) and foreign key constraints only apply to single
+ tables, not to their inheritance children. This is true on both the
+ referencing and referenced sides of a foreign key constraint. Thus,
+ in the terms of the above example:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If we declared <code class="structname">cities</code>.<code class="structfield">name</code> to be
+ <code class="literal">UNIQUE</code> or a <code class="literal">PRIMARY KEY</code>, this would not stop the
+ <code class="structname">capitals</code> table from having rows with names duplicating
+ rows in <code class="structname">cities</code>. And those duplicate rows would by
+ default show up in queries from <code class="structname">cities</code>. In fact, by
+ default <code class="structname">capitals</code> would have no unique constraint at all,
+ and so could contain multiple rows with the same name.
+ You could add a unique constraint to <code class="structname">capitals</code>, but this
+ would not prevent duplication compared to <code class="structname">cities</code>.
+ </p></li><li class="listitem"><p>
+ Similarly, if we were to specify that
+ <code class="structname">cities</code>.<code class="structfield">name</code> <code class="literal">REFERENCES</code> some
+ other table, this constraint would not automatically propagate to
+ <code class="structname">capitals</code>. In this case you could work around it by
+ manually adding the same <code class="literal">REFERENCES</code> constraint to
+ <code class="structname">capitals</code>.
+ </p></li><li class="listitem"><p>
+ Specifying that another table's column <code class="literal">REFERENCES
+ cities(name)</code> would allow the other table to contain city names, but
+ not capital names. There is no good workaround for this case.
+ </p></li></ul></div><p>
+
+ Some functionality not implemented for inheritance hierarchies is
+ implemented for declarative partitioning.
+ Considerable care is needed in deciding whether partitioning with legacy
+ inheritance is useful for your application.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-schemas.html" title="5.9. Schemas">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-partitioning.html" title="5.11. Table Partitioning">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.9. Schemas </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.11. Table Partitioning</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-others.html b/doc/src/sgml/html/ddl-others.html
new file mode 100644
index 0000000..58a9b7a
--- /dev/null
+++ b/doc/src/sgml/html/ddl-others.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.13. Other Database Objects</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-foreign-data.html" title="5.12. Foreign Data" /><link rel="next" href="ddl-depend.html" title="5.14. Dependency Tracking" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.13. Other Database Objects</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-foreign-data.html" title="5.12. Foreign Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-depend.html" title="5.14. Dependency Tracking">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-OTHERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.13. Other Database Objects</h2></div></div></div><p>
+ Tables are the central objects in a relational database structure,
+ because they hold your data. But they are not the only objects
+ that exist in a database. Many other kinds of objects can be
+ created to make the use and management of the data more efficient
+ or convenient. They are not discussed in this chapter, but we give
+ you a list here so that you are aware of what is possible:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Views
+ </p></li><li class="listitem"><p>
+ Functions, procedures, and operators
+ </p></li><li class="listitem"><p>
+ Data types and domains
+ </p></li><li class="listitem"><p>
+ Triggers and rewrite rules
+ </p></li></ul></div><p>
+ Detailed information on
+ these topics appears in <a class="xref" href="server-programming.html" title="Part V. Server Programming">Part V</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-foreign-data.html" title="5.12. Foreign Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-depend.html" title="5.14. Dependency Tracking">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.12. Foreign Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.14. Dependency Tracking</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-partitioning.html b/doc/src/sgml/html/ddl-partitioning.html
new file mode 100644
index 0000000..d818fe4
--- /dev/null
+++ b/doc/src/sgml/html/ddl-partitioning.html
@@ -0,0 +1,992 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.11. Table Partitioning</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-inherit.html" title="5.10. Inheritance" /><link rel="next" href="ddl-foreign-data.html" title="5.12. Foreign Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.11. Table Partitioning</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-inherit.html" title="5.10. Inheritance">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-foreign-data.html" title="5.12. Foreign Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-PARTITIONING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.11. Table Partitioning</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-OVERVIEW">5.11.1. Overview</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE">5.11.2. Declarative Partitioning</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-USING-INHERITANCE">5.11.3. Partitioning Using Inheritance</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITION-PRUNING">5.11.4. Partition Pruning</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION">5.11.5. Partitioning and Constraint Exclusion</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-BEST-PRACTICES">5.11.6. Best Practices for Declarative Partitioning</a></span></dt></dl></div><a id="id-1.5.4.13.2" class="indexterm"></a><a id="id-1.5.4.13.3" class="indexterm"></a><a id="id-1.5.4.13.4" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> supports basic table
+ partitioning. This section describes why and how to implement
+ partitioning as part of your database design.
+ </p><div class="sect2" id="DDL-PARTITIONING-OVERVIEW"><div class="titlepage"><div><div><h3 class="title">5.11.1. Overview</h3></div></div></div><p>
+ Partitioning refers to splitting what is logically one large table into
+ smaller physical pieces. Partitioning can provide several benefits:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Query performance can be improved dramatically in certain situations,
+ particularly when most of the heavily accessed rows of the table are in a
+ single partition or a small number of partitions. Partitioning
+ effectively substitutes for the upper tree levels of indexes,
+ making it more likely that the heavily-used parts of the indexes
+ fit in memory.
+ </p></li><li class="listitem"><p>
+ When queries or updates access a large percentage of a single
+ partition, performance can be improved by using a
+ sequential scan of that partition instead of using an
+ index, which would require random-access reads scattered across the
+ whole table.
+ </p></li><li class="listitem"><p>
+ Bulk loads and deletes can be accomplished by adding or removing
+ partitions, if the usage pattern is accounted for in the
+ partitioning design. Dropping an individual partition
+ using <code class="command">DROP TABLE</code>, or doing <code class="command">ALTER TABLE
+ DETACH PARTITION</code>, is far faster than a bulk
+ operation. These commands also entirely avoid the
+ <code class="command">VACUUM</code> overhead caused by a bulk <code class="command">DELETE</code>.
+ </p></li><li class="listitem"><p>
+ Seldom-used data can be migrated to cheaper and slower storage media.
+ </p></li></ul></div><p>
+
+ These benefits will normally be worthwhile only when a table would
+ otherwise be very large. The exact point at which a table will
+ benefit from partitioning depends on the application, although a
+ rule of thumb is that the size of the table should exceed the physical
+ memory of the database server.
+ </p><p>
+ <span class="productname">PostgreSQL</span> offers built-in support for the
+ following forms of partitioning:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Range Partitioning</span></dt><dd><p>
+ The table is partitioned into <span class="quote">“<span class="quote">ranges</span>”</span> defined
+ by a key column or set of columns, with no overlap between
+ the ranges of values assigned to different partitions. For
+ example, one might partition by date ranges, or by ranges of
+ identifiers for particular business objects.
+ Each range's bounds are understood as being inclusive at the
+ lower end and exclusive at the upper end. For example, if one
+ partition's range is from <code class="literal">1</code>
+ to <code class="literal">10</code>, and the next one's range is
+ from <code class="literal">10</code> to <code class="literal">20</code>, then
+ value <code class="literal">10</code> belongs to the second partition not
+ the first.
+ </p></dd><dt><span class="term">List Partitioning</span></dt><dd><p>
+ The table is partitioned by explicitly listing which key value(s)
+ appear in each partition.
+ </p></dd><dt><span class="term">Hash Partitioning</span></dt><dd><p>
+ The table is partitioned by specifying a modulus and a remainder for
+ each partition. Each partition will hold the rows for which the hash
+ value of the partition key divided by the specified modulus will
+ produce the specified remainder.
+ </p></dd></dl></div><p>
+
+ If your application needs to use other forms of partitioning not listed
+ above, alternative methods such as inheritance and
+ <code class="literal">UNION ALL</code> views can be used instead. Such methods
+ offer flexibility but do not have some of the performance benefits
+ of built-in declarative partitioning.
+ </p></div><div class="sect2" id="DDL-PARTITIONING-DECLARATIVE"><div class="titlepage"><div><div><h3 class="title">5.11.2. Declarative Partitioning</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> allows you to declare
+ that a table is divided into partitions. The table that is divided
+ is referred to as a <em class="firstterm">partitioned table</em>. The
+ declaration includes the <em class="firstterm">partitioning method</em>
+ as described above, plus a list of columns or expressions to be used
+ as the <em class="firstterm">partition key</em>.
+ </p><p>
+ The partitioned table itself is a <span class="quote">“<span class="quote">virtual</span>”</span> table having
+ no storage of its own. Instead, the storage belongs
+ to <em class="firstterm">partitions</em>, which are otherwise-ordinary
+ tables associated with the partitioned table.
+ Each partition stores a subset of the data as defined by its
+ <em class="firstterm">partition bounds</em>.
+ All rows inserted into a partitioned table will be routed to the
+ appropriate one of the partitions based on the values of the partition
+ key column(s).
+ Updating the partition key of a row will cause it to be moved into a
+ different partition if it no longer satisfies the partition bounds
+ of its original partition.
+ </p><p>
+ Partitions may themselves be defined as partitioned tables, resulting
+ in <em class="firstterm">sub-partitioning</em>. Although all partitions
+ must have the same columns as their partitioned parent, partitions may
+ have their
+ own indexes, constraints and default values, distinct from those of other
+ partitions. See <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for more details on
+ creating partitioned tables and partitions.
+ </p><p>
+ It is not possible to turn a regular table into a partitioned table or
+ vice versa. However, it is possible to add an existing regular or
+ partitioned table as a partition of a partitioned table, or remove a
+ partition from a partitioned table turning it into a standalone table;
+ this can simplify and speed up many maintenance processes.
+ See <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a> to learn more about the
+ <code class="command">ATTACH PARTITION</code> and <code class="command">DETACH PARTITION</code>
+ sub-commands.
+ </p><p>
+ Partitions can also be <a class="link" href="ddl-foreign-data.html" title="5.12. Foreign Data">foreign
+ tables</a>, although considerable care is needed because it is then
+ the user's responsibility that the contents of the foreign table
+ satisfy the partitioning rule. There are some other restrictions as
+ well. See <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a> for more
+ information.
+ </p><div class="sect3" id="DDL-PARTITIONING-DECLARATIVE-EXAMPLE"><div class="titlepage"><div><div><h4 class="title">5.11.2.1. Example</h4></div></div></div><p>
+ Suppose we are constructing a database for a large ice cream company.
+ The company measures peak temperatures every day as well as ice cream
+ sales in each region. Conceptually, we want a table like:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement (
+ city_id int not null,
+ logdate date not null,
+ peaktemp int,
+ unitsales int
+);
+</pre><p>
+
+ We know that most queries will access just the last week's, month's or
+ quarter's data, since the main use of this table will be to prepare
+ online reports for management. To reduce the amount of old data that
+ needs to be stored, we decide to keep only the most recent 3 years
+ worth of data. At the beginning of each month we will remove the oldest
+ month's data. In this situation we can use partitioning to help us meet
+ all of our different requirements for the measurements table.
+ </p><p>
+ To use declarative partitioning in this case, use the following steps:
+
+ </p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>
+ Create the <code class="structname">measurement</code> table as a partitioned
+ table by specifying the <code class="literal">PARTITION BY</code> clause, which
+ includes the partitioning method (<code class="literal">RANGE</code> in this
+ case) and the list of column(s) to use as the partition key.
+
+</p><pre class="programlisting">
+CREATE TABLE measurement (
+ city_id int not null,
+ logdate date not null,
+ peaktemp int,
+ unitsales int
+) PARTITION BY RANGE (logdate);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Create partitions. Each partition's definition must specify bounds
+ that correspond to the partitioning method and partition key of the
+ parent. Note that specifying bounds such that the new partition's
+ values would overlap with those in one or more existing partitions will
+ cause an error.
+ </p><p>
+ Partitions thus created are in every way normal
+ <span class="productname">PostgreSQL</span>
+ tables (or, possibly, foreign tables). It is possible to specify a
+ tablespace and storage parameters for each partition separately.
+ </p><p>
+ For our example, each partition should hold one month's worth of
+ data, to match the requirement of deleting one month's data at a
+ time. So the commands might look like:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2006m02 PARTITION OF measurement
+ FOR VALUES FROM ('2006-02-01') TO ('2006-03-01');
+
+CREATE TABLE measurement_y2006m03 PARTITION OF measurement
+ FOR VALUES FROM ('2006-03-01') TO ('2006-04-01');
+
+...
+CREATE TABLE measurement_y2007m11 PARTITION OF measurement
+ FOR VALUES FROM ('2007-11-01') TO ('2007-12-01');
+
+CREATE TABLE measurement_y2007m12 PARTITION OF measurement
+ FOR VALUES FROM ('2007-12-01') TO ('2008-01-01')
+ TABLESPACE fasttablespace;
+
+CREATE TABLE measurement_y2008m01 PARTITION OF measurement
+ FOR VALUES FROM ('2008-01-01') TO ('2008-02-01')
+ WITH (parallel_workers = 4)
+ TABLESPACE fasttablespace;
+</pre><p>
+
+ (Recall that adjacent partitions can share a bound value, since
+ range upper bounds are treated as exclusive bounds.)
+ </p><p>
+ If you wish to implement sub-partitioning, again specify the
+ <code class="literal">PARTITION BY</code> clause in the commands used to create
+ individual partitions, for example:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2006m02 PARTITION OF measurement
+ FOR VALUES FROM ('2006-02-01') TO ('2006-03-01')
+ PARTITION BY RANGE (peaktemp);
+</pre><p>
+
+ After creating partitions of <code class="structname">measurement_y2006m02</code>,
+ any data inserted into <code class="structname">measurement</code> that is mapped to
+ <code class="structname">measurement_y2006m02</code> (or data that is
+ directly inserted into <code class="structname">measurement_y2006m02</code>,
+ which is allowed provided its partition constraint is satisfied)
+ will be further redirected to one of its
+ partitions based on the <code class="structfield">peaktemp</code> column. The partition
+ key specified may overlap with the parent's partition key, although
+ care should be taken when specifying the bounds of a sub-partition
+ such that the set of data it accepts constitutes a subset of what
+ the partition's own bounds allow; the system does not try to check
+ whether that's really the case.
+ </p><p>
+ Inserting data into the parent table that does not map
+ to one of the existing partitions will cause an error; an appropriate
+ partition must be added manually.
+ </p><p>
+ It is not necessary to manually create table constraints describing
+ the partition boundary conditions for partitions. Such constraints
+ will be created automatically.
+ </p></li><li class="listitem"><p>
+ Create an index on the key column(s), as well as any other indexes you
+ might want, on the partitioned table. (The key index is not strictly
+ necessary, but in most scenarios it is helpful.)
+ This automatically creates a matching index on each partition, and
+ any partitions you create or attach later will also have such an
+ index.
+ An index or unique constraint declared on a partitioned table
+ is <span class="quote">“<span class="quote">virtual</span>”</span> in the same way that the partitioned table
+ is: the actual data is in child indexes on the individual partition
+ tables.
+
+</p><pre class="programlisting">
+CREATE INDEX ON measurement (logdate);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Ensure that the <a class="xref" href="runtime-config-query.html#GUC-ENABLE-PARTITION-PRUNING">enable_partition_pruning</a>
+ configuration parameter is not disabled in <code class="filename">postgresql.conf</code>.
+ If it is, queries will not be optimized as desired.
+ </p></li></ol></div><p>
+ </p><p>
+ In the above example we would be creating a new partition each month, so
+ it might be wise to write a script that generates the required DDL
+ automatically.
+ </p></div><div class="sect3" id="DDL-PARTITIONING-DECLARATIVE-MAINTENANCE"><div class="titlepage"><div><div><h4 class="title">5.11.2.2. Partition Maintenance</h4></div></div></div><p>
+ Normally the set of partitions established when initially defining the
+ table is not intended to remain static. It is common to want to
+ remove partitions holding old data and periodically add new partitions for
+ new data. One of the most important advantages of partitioning is
+ precisely that it allows this otherwise painful task to be executed
+ nearly instantaneously by manipulating the partition structure, rather
+ than physically moving large amounts of data around.
+ </p><p>
+ The simplest option for removing old data is to drop the partition that
+ is no longer necessary:
+</p><pre class="programlisting">
+DROP TABLE measurement_y2006m02;
+</pre><p>
+ This can very quickly delete millions of records because it doesn't have
+ to individually delete every record. Note however that the above command
+ requires taking an <code class="literal">ACCESS EXCLUSIVE</code> lock on the parent
+ table.
+ </p><p>
+ Another option that is often preferable is to remove the partition from
+ the partitioned table but retain access to it as a table in its own
+ right. This has two forms:
+
+</p><pre class="programlisting">
+ALTER TABLE measurement DETACH PARTITION measurement_y2006m02;
+ALTER TABLE measurement DETACH PARTITION measurement_y2006m02 CONCURRENTLY;
+</pre><p>
+
+ These allow further operations to be performed on the data before
+ it is dropped. For example, this is often a useful time to back up
+ the data using <code class="command">COPY</code>, <span class="application">pg_dump</span>, or
+ similar tools. It might also be a useful time to aggregate data
+ into smaller formats, perform other data manipulations, or run
+ reports. The first form of the command requires an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the parent table.
+ Adding the <code class="literal">CONCURRENTLY</code> qualifier as in the second
+ form allows the detach operation to require only
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock on the parent table, but see
+ <a class="link" href="sql-altertable.html#SQL-ALTERTABLE-DETACH-PARTITION"><code class="literal">ALTER TABLE ... DETACH PARTITION</code></a>
+ for details on the restrictions.
+ </p><p>
+ Similarly we can add a new partition to handle new data. We can create an
+ empty partition in the partitioned table just as the original partitions
+ were created above:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2008m02 PARTITION OF measurement
+ FOR VALUES FROM ('2008-02-01') TO ('2008-03-01')
+ TABLESPACE fasttablespace;
+</pre><p>
+
+ As an alternative, it is sometimes more convenient to create the
+ new table outside the partition structure, and attach it as a
+ partition later. This allows new data to be loaded, checked, and
+ transformed prior to it appearing in the partitioned table.
+ Moreover, the <code class="literal">ATTACH PARTITION</code> operation requires
+ only <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock on the
+ partitioned table, as opposed to the <code class="literal">ACCESS
+ EXCLUSIVE</code> lock that is required by <code class="command">CREATE TABLE
+ ... PARTITION OF</code>, so it is more friendly to concurrent
+ operations on the partitioned table.
+ The <code class="literal">CREATE TABLE ... LIKE</code> option is helpful
+ to avoid tediously repeating the parent table's definition:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2008m02
+ (LIKE measurement INCLUDING DEFAULTS INCLUDING CONSTRAINTS)
+ TABLESPACE fasttablespace;
+
+ALTER TABLE measurement_y2008m02 ADD CONSTRAINT y2008m02
+ CHECK ( logdate &gt;= DATE '2008-02-01' AND logdate &lt; DATE '2008-03-01' );
+
+\copy measurement_y2008m02 from 'measurement_y2008m02'
+-- possibly some other data preparation work
+
+ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02
+ FOR VALUES FROM ('2008-02-01') TO ('2008-03-01' );
+</pre><p>
+ </p><p>
+ Before running the <code class="command">ATTACH PARTITION</code> command, it is
+ recommended to create a <code class="literal">CHECK</code> constraint on the table to
+ be attached that matches the expected partition constraint, as
+ illustrated above. That way, the system will be able to skip the scan
+ which is otherwise needed to validate the implicit
+ partition constraint. Without the <code class="literal">CHECK</code> constraint,
+ the table will be scanned to validate the partition constraint while
+ holding an <code class="literal">ACCESS EXCLUSIVE</code> lock on that partition.
+ It is recommended to drop the now-redundant <code class="literal">CHECK</code>
+ constraint after the <code class="command">ATTACH PARTITION</code> is complete. If
+ the table being attached is itself a partitioned table, then each of its
+ sub-partitions will be recursively locked and scanned until either a
+ suitable <code class="literal">CHECK</code> constraint is encountered or the leaf
+ partitions are reached.
+ </p><p>
+ Similarly, if the partitioned table has a <code class="literal">DEFAULT</code>
+ partition, it is recommended to create a <code class="literal">CHECK</code>
+ constraint which excludes the to-be-attached partition's constraint. If
+ this is not done then the <code class="literal">DEFAULT</code> partition will be
+ scanned to verify that it contains no records which should be located in
+ the partition being attached. This operation will be performed whilst
+ holding an <code class="literal">ACCESS EXCLUSIVE</code> lock on the <code class="literal">
+ DEFAULT</code> partition. If the <code class="literal">DEFAULT</code> partition
+ is itself a partitioned table, then each of its partitions will be
+ recursively checked in the same way as the table being attached, as
+ mentioned above.
+ </p><p>
+ As explained above, it is possible to create indexes on partitioned tables
+ so that they are applied automatically to the entire hierarchy.
+ This is very
+ convenient, as not only will the existing partitions become indexed, but
+ also any partitions that are created in the future will. One limitation is
+ that it's not possible to use the <code class="literal">CONCURRENTLY</code>
+ qualifier when creating such a partitioned index. To avoid long lock
+ times, it is possible to use <code class="command">CREATE INDEX ON ONLY</code>
+ the partitioned table; such an index is marked invalid, and the partitions
+ do not get the index applied automatically. The indexes on partitions can
+ be created individually using <code class="literal">CONCURRENTLY</code>, and then
+ <em class="firstterm">attached</em> to the index on the parent using
+ <code class="command">ALTER INDEX .. ATTACH PARTITION</code>. Once indexes for all
+ partitions are attached to the parent index, the parent index is marked
+ valid automatically. Example:
+</p><pre class="programlisting">
+CREATE INDEX measurement_usls_idx ON ONLY measurement (unitsales);
+
+CREATE INDEX measurement_usls_200602_idx
+ ON measurement_y2006m02 (unitsales);
+ALTER INDEX measurement_usls_idx
+ ATTACH PARTITION measurement_usls_200602_idx;
+...
+</pre><p>
+
+ This technique can be used with <code class="literal">UNIQUE</code> and
+ <code class="literal">PRIMARY KEY</code> constraints too; the indexes are created
+ implicitly when the constraint is created. Example:
+</p><pre class="programlisting">
+ALTER TABLE ONLY measurement ADD UNIQUE (city_id, logdate);
+
+ALTER TABLE measurement_y2006m02 ADD UNIQUE (city_id, logdate);
+ALTER INDEX measurement_city_id_logdate_key
+ ATTACH PARTITION measurement_y2006m02_city_id_logdate_key;
+...
+</pre><p>
+ </p></div><div class="sect3" id="DDL-PARTITIONING-DECLARATIVE-LIMITATIONS"><div class="titlepage"><div><div><h4 class="title">5.11.2.3. Limitations</h4></div></div></div><p>
+ The following limitations apply to partitioned tables:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ To create a unique or primary key constraint on a partitioned table,
+ the partition keys must not include any expressions or function calls
+ and the constraint's columns must include all of the partition key
+ columns. This limitation exists because the individual indexes making
+ up the constraint can only directly enforce uniqueness within their own
+ partitions; therefore, the partition structure itself must guarantee
+ that there are not duplicates in different partitions.
+ </p></li><li class="listitem"><p>
+ There is no way to create an exclusion constraint spanning the
+ whole partitioned table. It is only possible to put such a
+ constraint on each leaf partition individually. Again, this
+ limitation stems from not being able to enforce cross-partition
+ restrictions.
+ </p></li><li class="listitem"><p>
+ <code class="literal">BEFORE ROW</code> triggers on <code class="literal">INSERT</code>
+ cannot change which partition is the final destination for a new row.
+ </p></li><li class="listitem"><p>
+ Mixing temporary and permanent relations in the same partition tree is
+ not allowed. Hence, if the partitioned table is permanent, so must be
+ its partitions and likewise if the partitioned table is temporary. When
+ using temporary relations, all members of the partition tree have to be
+ from the same session.
+ </p></li></ul></div><p>
+ </p><p>
+ Individual partitions are linked to their partitioned table using
+ inheritance behind-the-scenes. However, it is not possible to use
+ all of the generic features of inheritance with declaratively
+ partitioned tables or their partitions, as discussed below. Notably,
+ a partition cannot have any parents other than the partitioned table
+ it is a partition of, nor can a table inherit from both a partitioned
+ table and a regular table. That means partitioned tables and their
+ partitions never share an inheritance hierarchy with regular tables.
+ </p><p>
+ Since a partition hierarchy consisting of the partitioned table and its
+ partitions is still an inheritance hierarchy,
+ <code class="structfield">tableoid</code> and all the normal rules of
+ inheritance apply as described in <a class="xref" href="ddl-inherit.html" title="5.10. Inheritance">Section 5.10</a>, with
+ a few exceptions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Partitions cannot have columns that are not present in the parent. It
+ is not possible to specify columns when creating partitions with
+ <code class="command">CREATE TABLE</code>, nor is it possible to add columns to
+ partitions after-the-fact using <code class="command">ALTER TABLE</code>.
+ Tables may be added as a partition with <code class="command">ALTER TABLE
+ ... ATTACH PARTITION</code> only if their columns exactly match
+ the parent.
+ </p></li><li class="listitem"><p>
+ Both <code class="literal">CHECK</code> and <code class="literal">NOT NULL</code>
+ constraints of a partitioned table are always inherited by all its
+ partitions. <code class="literal">CHECK</code> constraints that are marked
+ <code class="literal">NO INHERIT</code> are not allowed to be created on
+ partitioned tables.
+ You cannot drop a <code class="literal">NOT NULL</code> constraint on a
+ partition's column if the same constraint is present in the parent
+ table.
+ </p></li><li class="listitem"><p>
+ Using <code class="literal">ONLY</code> to add or drop a constraint on only
+ the partitioned table is supported as long as there are no
+ partitions. Once partitions exist, using <code class="literal">ONLY</code>
+ will result in an error. Instead, constraints on the partitions
+ themselves can be added and (if they are not present in the parent
+ table) dropped.
+ </p></li><li class="listitem"><p>
+ As a partitioned table does not have any data itself, attempts to use
+ <code class="command">TRUNCATE</code> <code class="literal">ONLY</code> on a partitioned
+ table will always return an error.
+ </p></li></ul></div><p>
+ </p></div></div><div class="sect2" id="DDL-PARTITIONING-USING-INHERITANCE"><div class="titlepage"><div><div><h3 class="title">5.11.3. Partitioning Using Inheritance</h3></div></div></div><p>
+ While the built-in declarative partitioning is suitable for most
+ common use cases, there are some circumstances where a more flexible
+ approach may be useful. Partitioning can be implemented using table
+ inheritance, which allows for several features not supported
+ by declarative partitioning, such as:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ For declarative partitioning, partitions must have exactly the same set
+ of columns as the partitioned table, whereas with table inheritance,
+ child tables may have extra columns not present in the parent.
+ </p></li><li class="listitem"><p>
+ Table inheritance allows for multiple inheritance.
+ </p></li><li class="listitem"><p>
+ Declarative partitioning only supports range, list and hash
+ partitioning, whereas table inheritance allows data to be divided in a
+ manner of the user's choosing. (Note, however, that if constraint
+ exclusion is unable to prune child tables effectively, query performance
+ might be poor.)
+ </p></li></ul></div><p>
+ </p><div class="sect3" id="DDL-PARTITIONING-INHERITANCE-EXAMPLE"><div class="titlepage"><div><div><h4 class="title">5.11.3.1. Example</h4></div></div></div><p>
+ This example builds a partitioning structure equivalent to the
+ declarative partitioning example above. Use
+ the following steps:
+
+ </p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>
+ Create the <span class="quote">“<span class="quote">root</span>”</span> table, from which all of the
+ <span class="quote">“<span class="quote">child</span>”</span> tables will inherit. This table will contain no data. Do not
+ define any check constraints on this table, unless you intend them
+ to be applied equally to all child tables. There is no point in
+ defining any indexes or unique constraints on it, either. For our
+ example, the root table is the <code class="structname">measurement</code>
+ table as originally defined:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement (
+ city_id int not null,
+ logdate date not null,
+ peaktemp int,
+ unitsales int
+);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Create several <span class="quote">“<span class="quote">child</span>”</span> tables that each inherit from
+ the root table. Normally, these tables will not add any columns
+ to the set inherited from the root. Just as with declarative
+ partitioning, these tables are in every way normal
+ <span class="productname">PostgreSQL</span> tables (or foreign tables).
+ </p><p>
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2006m02 () INHERITS (measurement);
+CREATE TABLE measurement_y2006m03 () INHERITS (measurement);
+...
+CREATE TABLE measurement_y2007m11 () INHERITS (measurement);
+CREATE TABLE measurement_y2007m12 () INHERITS (measurement);
+CREATE TABLE measurement_y2008m01 () INHERITS (measurement);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Add non-overlapping table constraints to the child tables to
+ define the allowed key values in each.
+ </p><p>
+ Typical examples would be:
+</p><pre class="programlisting">
+CHECK ( x = 1 )
+CHECK ( county IN ( 'Oxfordshire', 'Buckinghamshire', 'Warwickshire' ))
+CHECK ( outletID &gt;= 100 AND outletID &lt; 200 )
+</pre><p>
+ Ensure that the constraints guarantee that there is no overlap
+ between the key values permitted in different child tables. A common
+ mistake is to set up range constraints like:
+</p><pre class="programlisting">
+CHECK ( outletID BETWEEN 100 AND 200 )
+CHECK ( outletID BETWEEN 200 AND 300 )
+</pre><p>
+ This is wrong since it is not clear which child table the key
+ value 200 belongs in.
+ Instead, ranges should be defined in this style:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2006m02 (
+ CHECK ( logdate &gt;= DATE '2006-02-01' AND logdate &lt; DATE '2006-03-01' )
+) INHERITS (measurement);
+
+CREATE TABLE measurement_y2006m03 (
+ CHECK ( logdate &gt;= DATE '2006-03-01' AND logdate &lt; DATE '2006-04-01' )
+) INHERITS (measurement);
+
+...
+CREATE TABLE measurement_y2007m11 (
+ CHECK ( logdate &gt;= DATE '2007-11-01' AND logdate &lt; DATE '2007-12-01' )
+) INHERITS (measurement);
+
+CREATE TABLE measurement_y2007m12 (
+ CHECK ( logdate &gt;= DATE '2007-12-01' AND logdate &lt; DATE '2008-01-01' )
+) INHERITS (measurement);
+
+CREATE TABLE measurement_y2008m01 (
+ CHECK ( logdate &gt;= DATE '2008-01-01' AND logdate &lt; DATE '2008-02-01' )
+) INHERITS (measurement);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ For each child table, create an index on the key column(s),
+ as well as any other indexes you might want.
+</p><pre class="programlisting">
+CREATE INDEX measurement_y2006m02_logdate ON measurement_y2006m02 (logdate);
+CREATE INDEX measurement_y2006m03_logdate ON measurement_y2006m03 (logdate);
+CREATE INDEX measurement_y2007m11_logdate ON measurement_y2007m11 (logdate);
+CREATE INDEX measurement_y2007m12_logdate ON measurement_y2007m12 (logdate);
+CREATE INDEX measurement_y2008m01_logdate ON measurement_y2008m01 (logdate);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ We want our application to be able to say <code class="literal">INSERT INTO
+ measurement ...</code> and have the data be redirected into the
+ appropriate child table. We can arrange that by attaching
+ a suitable trigger function to the root table.
+ If data will be added only to the latest child, we can
+ use a very simple trigger function:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION measurement_insert_trigger()
+RETURNS TRIGGER AS $$
+BEGIN
+ INSERT INTO measurement_y2008m01 VALUES (NEW.*);
+ RETURN NULL;
+END;
+$$
+LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ After creating the function, we create a trigger which
+ calls the trigger function:
+
+</p><pre class="programlisting">
+CREATE TRIGGER insert_measurement_trigger
+ BEFORE INSERT ON measurement
+ FOR EACH ROW EXECUTE FUNCTION measurement_insert_trigger();
+</pre><p>
+
+ We must redefine the trigger function each month so that it always
+ inserts into the current child table. The trigger definition does
+ not need to be updated, however.
+ </p><p>
+ We might want to insert data and have the server automatically
+ locate the child table into which the row should be added. We
+ could do this with a more complex trigger function, for example:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION measurement_insert_trigger()
+RETURNS TRIGGER AS $$
+BEGIN
+ IF ( NEW.logdate &gt;= DATE '2006-02-01' AND
+ NEW.logdate &lt; DATE '2006-03-01' ) THEN
+ INSERT INTO measurement_y2006m02 VALUES (NEW.*);
+ ELSIF ( NEW.logdate &gt;= DATE '2006-03-01' AND
+ NEW.logdate &lt; DATE '2006-04-01' ) THEN
+ INSERT INTO measurement_y2006m03 VALUES (NEW.*);
+ ...
+ ELSIF ( NEW.logdate &gt;= DATE '2008-01-01' AND
+ NEW.logdate &lt; DATE '2008-02-01' ) THEN
+ INSERT INTO measurement_y2008m01 VALUES (NEW.*);
+ ELSE
+ RAISE EXCEPTION 'Date out of range. Fix the measurement_insert_trigger() function!';
+ END IF;
+ RETURN NULL;
+END;
+$$
+LANGUAGE plpgsql;
+</pre><p>
+
+ The trigger definition is the same as before.
+ Note that each <code class="literal">IF</code> test must exactly match the
+ <code class="literal">CHECK</code> constraint for its child table.
+ </p><p>
+ While this function is more complex than the single-month case,
+ it doesn't need to be updated as often, since branches can be
+ added in advance of being needed.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In practice, it might be best to check the newest child first,
+ if most inserts go into that child. For simplicity, we have
+ shown the trigger's tests in the same order as in other parts
+ of this example.
+ </p></div><p>
+ A different approach to redirecting inserts into the appropriate
+ child table is to set up rules, instead of a trigger, on the
+ root table. For example:
+
+</p><pre class="programlisting">
+CREATE RULE measurement_insert_y2006m02 AS
+ON INSERT TO measurement WHERE
+ ( logdate &gt;= DATE '2006-02-01' AND logdate &lt; DATE '2006-03-01' )
+DO INSTEAD
+ INSERT INTO measurement_y2006m02 VALUES (NEW.*);
+...
+CREATE RULE measurement_insert_y2008m01 AS
+ON INSERT TO measurement WHERE
+ ( logdate &gt;= DATE '2008-01-01' AND logdate &lt; DATE '2008-02-01' )
+DO INSTEAD
+ INSERT INTO measurement_y2008m01 VALUES (NEW.*);
+</pre><p>
+
+ A rule has significantly more overhead than a trigger, but the
+ overhead is paid once per query rather than once per row, so this
+ method might be advantageous for bulk-insert situations. In most
+ cases, however, the trigger method will offer better performance.
+ </p><p>
+ Be aware that <code class="command">COPY</code> ignores rules. If you want to
+ use <code class="command">COPY</code> to insert data, you'll need to copy into the
+ correct child table rather than directly into the root. <code class="command">COPY</code>
+ does fire triggers, so you can use it normally if you use the trigger
+ approach.
+ </p><p>
+ Another disadvantage of the rule approach is that there is no simple
+ way to force an error if the set of rules doesn't cover the insertion
+ date; the data will silently go into the root table instead.
+ </p></li><li class="listitem"><p>
+ Ensure that the <a class="xref" href="runtime-config-query.html#GUC-CONSTRAINT-EXCLUSION">constraint_exclusion</a>
+ configuration parameter is not disabled in
+ <code class="filename">postgresql.conf</code>; otherwise
+ child tables may be accessed unnecessarily.
+ </p></li></ol></div><p>
+ </p><p>
+ As we can see, a complex table hierarchy could require a
+ substantial amount of DDL. In the above example we would be creating
+ a new child table each month, so it might be wise to write a script that
+ generates the required DDL automatically.
+ </p></div><div class="sect3" id="DDL-PARTITIONING-INHERITANCE-MAINTENANCE"><div class="titlepage"><div><div><h4 class="title">5.11.3.2. Maintenance for Inheritance Partitioning</h4></div></div></div><p>
+ To remove old data quickly, simply drop the child table that is no longer
+ necessary:
+</p><pre class="programlisting">
+DROP TABLE measurement_y2006m02;
+</pre><p>
+ </p><p>
+ To remove the child table from the inheritance hierarchy table but retain access to
+ it as a table in its own right:
+
+</p><pre class="programlisting">
+ALTER TABLE measurement_y2006m02 NO INHERIT measurement;
+</pre><p>
+ </p><p>
+ To add a new child table to handle new data, create an empty child table
+ just as the original children were created above:
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2008m02 (
+ CHECK ( logdate &gt;= DATE '2008-02-01' AND logdate &lt; DATE '2008-03-01' )
+) INHERITS (measurement);
+</pre><p>
+
+ Alternatively, one may want to create and populate the new child table
+ before adding it to the table hierarchy. This could allow data to be
+ loaded, checked, and transformed before being made visible to queries on
+ the parent table.
+
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2008m02
+ (LIKE measurement INCLUDING DEFAULTS INCLUDING CONSTRAINTS);
+ALTER TABLE measurement_y2008m02 ADD CONSTRAINT y2008m02
+ CHECK ( logdate &gt;= DATE '2008-02-01' AND logdate &lt; DATE '2008-03-01' );
+\copy measurement_y2008m02 from 'measurement_y2008m02'
+-- possibly some other data preparation work
+ALTER TABLE measurement_y2008m02 INHERIT measurement;
+</pre><p>
+ </p></div><div class="sect3" id="DDL-PARTITIONING-INHERITANCE-CAVEATS"><div class="titlepage"><div><div><h4 class="title">5.11.3.3. Caveats</h4></div></div></div><p>
+ The following caveats apply to partitioning implemented using
+ inheritance:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ There is no automatic way to verify that all of the
+ <code class="literal">CHECK</code> constraints are mutually
+ exclusive. It is safer to create code that generates
+ child tables and creates and/or modifies associated objects than
+ to write each by hand.
+ </p></li><li class="listitem"><p>
+ Indexes and foreign key constraints apply to single tables and not
+ to their inheritance children, hence they have some
+ <a class="link" href="ddl-inherit.html#DDL-INHERIT-CAVEATS" title="5.10.1. Caveats">caveats</a> to be aware of.
+ </p></li><li class="listitem"><p>
+ The schemes shown here assume that the values of a row's key column(s)
+ never change, or at least do not change enough to require it to move to another partition.
+ An <code class="command">UPDATE</code> that attempts
+ to do that will fail because of the <code class="literal">CHECK</code> constraints.
+ If you need to handle such cases, you can put suitable update triggers
+ on the child tables, but it makes management of the structure
+ much more complicated.
+ </p></li><li class="listitem"><p>
+ If you are using manual <code class="command">VACUUM</code> or
+ <code class="command">ANALYZE</code> commands, don't forget that
+ you need to run them on each child table individually. A command like:
+</p><pre class="programlisting">
+ANALYZE measurement;
+</pre><p>
+ will only process the root table.
+ </p></li><li class="listitem"><p>
+ <code class="command">INSERT</code> statements with <code class="literal">ON CONFLICT</code>
+ clauses are unlikely to work as expected, as the <code class="literal">ON CONFLICT</code>
+ action is only taken in case of unique violations on the specified
+ target relation, not its child relations.
+ </p></li><li class="listitem"><p>
+ Triggers or rules will be needed to route rows to the desired
+ child table, unless the application is explicitly aware of the
+ partitioning scheme. Triggers may be complicated to write, and will
+ be much slower than the tuple routing performed internally by
+ declarative partitioning.
+ </p></li></ul></div><p>
+ </p></div></div><div class="sect2" id="DDL-PARTITION-PRUNING"><div class="titlepage"><div><div><h3 class="title">5.11.4. Partition Pruning</h3></div></div></div><a id="id-1.5.4.13.9.2" class="indexterm"></a><p>
+ <em class="firstterm">Partition pruning</em> is a query optimization technique
+ that improves performance for declaratively partitioned tables.
+ As an example:
+
+</p><pre class="programlisting">
+SET enable_partition_pruning = on; -- the default
+SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
+</pre><p>
+
+ Without partition pruning, the above query would scan each of the
+ partitions of the <code class="structname">measurement</code> table. With
+ partition pruning enabled, the planner will examine the definition
+ of each partition and prove that the partition need not
+ be scanned because it could not contain any rows meeting the query's
+ <code class="literal">WHERE</code> clause. When the planner can prove this, it
+ excludes (<em class="firstterm">prunes</em>) the partition from the query
+ plan.
+ </p><p>
+ By using the EXPLAIN command and the <a class="xref" href="runtime-config-query.html#GUC-ENABLE-PARTITION-PRUNING">enable_partition_pruning</a> configuration parameter, it's
+ possible to show the difference between a plan for which partitions have
+ been pruned and one for which they have not. A typical unoptimized
+ plan for this type of table setup is:
+</p><pre class="programlisting">
+SET enable_partition_pruning = off;
+EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
+ QUERY PLAN
+-------------------------------------------------------------------​----------------
+ Aggregate (cost=188.76..188.77 rows=1 width=8)
+ -&gt; Append (cost=0.00..181.05 rows=3085 width=0)
+ -&gt; Seq Scan on measurement_y2006m02 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+ -&gt; Seq Scan on measurement_y2006m03 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+...
+ -&gt; Seq Scan on measurement_y2007m11 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+ -&gt; Seq Scan on measurement_y2007m12 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+ -&gt; Seq Scan on measurement_y2008m01 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+</pre><p>
+
+ Some or all of the partitions might use index scans instead of
+ full-table sequential scans, but the point here is that there
+ is no need to scan the older partitions at all to answer this query.
+ When we enable partition pruning, we get a significantly
+ cheaper plan that will deliver the same answer:
+</p><pre class="programlisting">
+SET enable_partition_pruning = on;
+EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
+ QUERY PLAN
+-------------------------------------------------------------------​----------------
+ Aggregate (cost=37.75..37.76 rows=1 width=8)
+ -&gt; Seq Scan on measurement_y2008m01 (cost=0.00..33.12 rows=617 width=0)
+ Filter: (logdate &gt;= '2008-01-01'::date)
+</pre><p>
+ </p><p>
+ Note that partition pruning is driven only by the constraints defined
+ implicitly by the partition keys, not by the presence of indexes.
+ Therefore it isn't necessary to define indexes on the key columns.
+ Whether an index needs to be created for a given partition depends on
+ whether you expect that queries that scan the partition will
+ generally scan a large part of the partition or just a small part.
+ An index will be helpful in the latter case but not the former.
+ </p><p>
+ Partition pruning can be performed not only during the planning of a
+ given query, but also during its execution. This is useful as it can
+ allow more partitions to be pruned when clauses contain expressions
+ whose values are not known at query planning time, for example,
+ parameters defined in a <code class="command">PREPARE</code> statement, using a
+ value obtained from a subquery, or using a parameterized value on the
+ inner side of a nested loop join. Partition pruning during execution
+ can be performed at any of the following times:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ During initialization of the query plan. Partition pruning can be
+ performed here for parameter values which are known during the
+ initialization phase of execution. Partitions which are pruned
+ during this stage will not show up in the query's
+ <code class="command">EXPLAIN</code> or <code class="command">EXPLAIN ANALYZE</code>.
+ It is possible to determine the number of partitions which were
+ removed during this phase by observing the
+ <span class="quote">“<span class="quote">Subplans Removed</span>”</span> property in the
+ <code class="command">EXPLAIN</code> output.
+ </p></li><li class="listitem"><p>
+ During actual execution of the query plan. Partition pruning may
+ also be performed here to remove partitions using values which are
+ only known during actual query execution. This includes values
+ from subqueries and values from execution-time parameters such as
+ those from parameterized nested loop joins. Since the value of
+ these parameters may change many times during the execution of the
+ query, partition pruning is performed whenever one of the
+ execution parameters being used by partition pruning changes.
+ Determining if partitions were pruned during this phase requires
+ careful inspection of the <code class="literal">loops</code> property in
+ the <code class="command">EXPLAIN ANALYZE</code> output. Subplans
+ corresponding to different partitions may have different values
+ for it depending on how many times each of them was pruned during
+ execution. Some may be shown as <code class="literal">(never executed)</code>
+ if they were pruned every time.
+ </p></li></ul></div><p>
+ </p><p>
+ Partition pruning can be disabled using the
+ <a class="xref" href="runtime-config-query.html#GUC-ENABLE-PARTITION-PRUNING">enable_partition_pruning</a> setting.
+ </p></div><div class="sect2" id="DDL-PARTITIONING-CONSTRAINT-EXCLUSION"><div class="titlepage"><div><div><h3 class="title">5.11.5. Partitioning and Constraint Exclusion</h3></div></div></div><a id="id-1.5.4.13.10.2" class="indexterm"></a><p>
+ <em class="firstterm">Constraint exclusion</em> is a query optimization
+ technique similar to partition pruning. While it is primarily used
+ for partitioning implemented using the legacy inheritance method, it can be
+ used for other purposes, including with declarative partitioning.
+ </p><p>
+ Constraint exclusion works in a very similar way to partition
+ pruning, except that it uses each table's <code class="literal">CHECK</code>
+ constraints — which gives it its name — whereas partition
+ pruning uses the table's partition bounds, which exist only in the
+ case of declarative partitioning. Another difference is that
+ constraint exclusion is only applied at plan time; there is no attempt
+ to remove partitions at execution time.
+ </p><p>
+ The fact that constraint exclusion uses <code class="literal">CHECK</code>
+ constraints, which makes it slow compared to partition pruning, can
+ sometimes be used as an advantage: because constraints can be defined
+ even on declaratively-partitioned tables, in addition to their internal
+ partition bounds, constraint exclusion may be able
+ to elide additional partitions from the query plan.
+ </p><p>
+ The default (and recommended) setting of
+ <a class="xref" href="runtime-config-query.html#GUC-CONSTRAINT-EXCLUSION">constraint_exclusion</a> is neither
+ <code class="literal">on</code> nor <code class="literal">off</code>, but an intermediate setting
+ called <code class="literal">partition</code>, which causes the technique to be
+ applied only to queries that are likely to be working on inheritance partitioned
+ tables. The <code class="literal">on</code> setting causes the planner to examine
+ <code class="literal">CHECK</code> constraints in all queries, even simple ones that
+ are unlikely to benefit.
+ </p><p>
+ The following caveats apply to constraint exclusion:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Constraint exclusion is only applied during query planning, unlike
+ partition pruning, which can also be applied during query execution.
+ </p></li><li class="listitem"><p>
+ Constraint exclusion only works when the query's <code class="literal">WHERE</code>
+ clause contains constants (or externally supplied parameters).
+ For example, a comparison against a non-immutable function such as
+ <code class="function">CURRENT_TIMESTAMP</code> cannot be optimized, since the
+ planner cannot know which child table the function's value might fall
+ into at run time.
+ </p></li><li class="listitem"><p>
+ Keep the partitioning constraints simple, else the planner may not be
+ able to prove that child tables might not need to be visited. Use simple
+ equality conditions for list partitioning, or simple
+ range tests for range partitioning, as illustrated in the preceding
+ examples. A good rule of thumb is that partitioning constraints should
+ contain only comparisons of the partitioning column(s) to constants
+ using B-tree-indexable operators, because only B-tree-indexable
+ column(s) are allowed in the partition key.
+ </p></li><li class="listitem"><p>
+ All constraints on all children of the parent table are examined
+ during constraint exclusion, so large numbers of children are likely
+ to increase query planning time considerably. So the legacy
+ inheritance based partitioning will work well with up to perhaps a
+ hundred child tables; don't try to use many thousands of children.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="DDL-PARTITIONING-DECLARATIVE-BEST-PRACTICES"><div class="titlepage"><div><div><h3 class="title">5.11.6. Best Practices for Declarative Partitioning</h3></div></div></div><p>
+ The choice of how to partition a table should be made carefully, as the
+ performance of query planning and execution can be negatively affected by
+ poor design.
+ </p><p>
+ One of the most critical design decisions will be the column or columns
+ by which you partition your data. Often the best choice will be to
+ partition by the column or set of columns which most commonly appear in
+ <code class="literal">WHERE</code> clauses of queries being executed on the
+ partitioned table. <code class="literal">WHERE</code> clauses that are compatible
+ with the partition bound constraints can be used to prune unneeded
+ partitions. However, you may be forced into making other decisions by
+ requirements for the <code class="literal">PRIMARY KEY</code> or a
+ <code class="literal">UNIQUE</code> constraint. Removal of unwanted data is also a
+ factor to consider when planning your partitioning strategy. An entire
+ partition can be detached fairly quickly, so it may be beneficial to
+ design the partition strategy in such a way that all data to be removed
+ at once is located in a single partition.
+ </p><p>
+ Choosing the target number of partitions that the table should be divided
+ into is also a critical decision to make. Not having enough partitions
+ may mean that indexes remain too large and that data locality remains poor
+ which could result in low cache hit ratios. However, dividing the table
+ into too many partitions can also cause issues. Too many partitions can
+ mean longer query planning times and higher memory consumption during both
+ query planning and execution, as further described below.
+ When choosing how to partition your table,
+ it's also important to consider what changes may occur in the future. For
+ example, if you choose to have one partition per customer and you
+ currently have a small number of large customers, consider the
+ implications if in several years you instead find yourself with a large
+ number of small customers. In this case, it may be better to choose to
+ partition by <code class="literal">HASH</code> and choose a reasonable number of
+ partitions rather than trying to partition by <code class="literal">LIST</code> and
+ hoping that the number of customers does not increase beyond what it is
+ practical to partition the data by.
+ </p><p>
+ Sub-partitioning can be useful to further divide partitions that are
+ expected to become larger than other partitions.
+ Another option is to use range partitioning with multiple columns in
+ the partition key.
+ Either of these can easily lead to excessive numbers of partitions,
+ so restraint is advisable.
+ </p><p>
+ It is important to consider the overhead of partitioning during
+ query planning and execution. The query planner is generally able to
+ handle partition hierarchies with up to a few thousand partitions fairly
+ well, provided that typical queries allow the query planner to prune all
+ but a small number of partitions. Planning times become longer and memory
+ consumption becomes higher when more partitions remain after the planner
+ performs partition pruning. Another
+ reason to be concerned about having a large number of partitions is that
+ the server's memory consumption may grow significantly over
+ time, especially if many sessions touch large numbers of partitions.
+ That's because each partition requires its metadata to be loaded into the
+ local memory of each session that touches it.
+ </p><p>
+ With data warehouse type workloads, it can make sense to use a larger
+ number of partitions than with an <acronym class="acronym">OLTP</acronym> type workload.
+ Generally, in data warehouses, query planning time is less of a concern as
+ the majority of processing time is spent during query execution. With
+ either of these two types of workload, it is important to make the right
+ decisions early, as re-partitioning large quantities of data can be
+ painfully slow. Simulations of the intended workload are often beneficial
+ for optimizing the partitioning strategy. Never just assume that more
+ partitions are better than fewer partitions, nor vice-versa.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-inherit.html" title="5.10. Inheritance">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-foreign-data.html" title="5.12. Foreign Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.10. Inheritance </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.12. Foreign Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-priv.html b/doc/src/sgml/html/ddl-priv.html
new file mode 100644
index 0000000..c19149c
--- /dev/null
+++ b/doc/src/sgml/html/ddl-priv.html
@@ -0,0 +1,307 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.7. Privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-alter.html" title="5.6. Modifying Tables" /><link rel="next" href="ddl-rowsecurity.html" title="5.8. Row Security Policies" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.7. Privileges</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-alter.html" title="5.6. Modifying Tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-PRIV"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.7. Privileges</h2></div></div></div><a id="id-1.5.4.9.2" class="indexterm"></a><a id="id-1.5.4.9.3" class="indexterm"></a><a id="id-1.5.4.9.4" class="indexterm"></a><a id="id-1.5.4.9.5" class="indexterm"></a><a id="id-1.5.4.9.6" class="indexterm"></a><a id="id-1.5.4.9.7" class="indexterm"></a><p>
+ When an object is created, it is assigned an owner. The
+ owner is normally the role that executed the creation statement.
+ For most kinds of objects, the initial state is that only the owner
+ (or a superuser) can do anything with the object. To allow
+ other roles to use it, <em class="firstterm">privileges</em> must be
+ granted.
+ </p><p>
+ There are different kinds of privileges: <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>,
+ <code class="literal">TRUNCATE</code>, <code class="literal">REFERENCES</code>, <code class="literal">TRIGGER</code>,
+ <code class="literal">CREATE</code>, <code class="literal">CONNECT</code>, <code class="literal">TEMPORARY</code>,
+ <code class="literal">EXECUTE</code>, <code class="literal">USAGE</code>, <code class="literal">SET</code>
+ and <code class="literal">ALTER SYSTEM</code>.
+ The privileges applicable to a particular
+ object vary depending on the object's type (table, function, etc.).
+ More detail about the meanings of these privileges appears below.
+ The following sections and chapters will also show you how
+ these privileges are used.
+ </p><p>
+ The right to modify or destroy an object is inherent in being the
+ object's owner, and cannot be granted or revoked in itself.
+ (However, like all privileges, that right can be inherited by
+ members of the owning role; see <a class="xref" href="role-membership.html" title="22.3. Role Membership">Section 22.3</a>.)
+ </p><p>
+ An object can be assigned to a new owner with an <code class="command">ALTER</code>
+ command of the appropriate kind for the object, for example
+</p><pre class="programlisting">
+ALTER TABLE <em class="replaceable"><code>table_name</code></em> OWNER TO <em class="replaceable"><code>new_owner</code></em>;
+</pre><p>
+ 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.
+ </p><p>
+ To assign privileges, the <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> command is
+ used. For example, if <code class="literal">joe</code> is an existing role, and
+ <code class="literal">accounts</code> is an existing table, the privilege to
+ update the table can be granted with:
+</p><pre class="programlisting">
+GRANT UPDATE ON accounts TO joe;
+</pre><p>
+ Writing <code class="literal">ALL</code> in place of a specific privilege grants all
+ privileges that are relevant for the object type.
+ </p><p>
+ The special <span class="quote">“<span class="quote">role</span>”</span> name <code class="literal">PUBLIC</code> can
+ be used to grant a privilege to every role on the system. Also,
+ <span class="quote">“<span class="quote">group</span>”</span> roles can be set up to help manage privileges when
+ there are many users of a database — for details see
+ <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a>.
+ </p><p>
+ To revoke a previously-granted privilege, use the fittingly named
+ <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a> command:
+</p><pre class="programlisting">
+REVOKE ALL ON accounts FROM PUBLIC;
+</pre><p>
+ </p><p>
+ Ordinarily, only the object's owner (or a superuser) can grant or
+ revoke privileges on an object. However, it is possible to grant a
+ privilege <span class="quote">“<span class="quote">with grant option</span>”</span>, which gives the recipient
+ 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 <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> and
+ <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a> reference pages.
+ </p><p>
+ An object's owner can choose to revoke their own ordinary privileges,
+ for example to make a table read-only for themselves as well as others.
+ But owners are always treated as holding all grant options, so they
+ can always re-grant their own privileges.
+ </p><p>
+ The available privileges are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SELECT</code></span></dt><dd><p>
+ Allows <code class="command">SELECT</code> from
+ any column, or specific column(s), of a table, view, materialized
+ view, or other table-like object.
+ Also allows use of <code class="command">COPY TO</code>.
+ This privilege is also needed to reference existing column values in
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ or <code class="command">MERGE</code>.
+ For sequences, this privilege also allows use of the
+ <code class="function">currval</code> function.
+ For large objects, this privilege allows the object to be read.
+ </p></dd><dt><span class="term"><code class="literal">INSERT</code></span></dt><dd><p>
+ Allows <code class="command">INSERT</code> of a new row into a table, view,
+ etc. Can be granted on specific column(s), in which case
+ only those columns may be assigned to in the <code class="command">INSERT</code>
+ command (other columns will therefore receive default values).
+ Also allows use of <code class="command">COPY FROM</code>.
+ </p></dd><dt><span class="term"><code class="literal">UPDATE</code></span></dt><dd><p>
+ Allows <code class="command">UPDATE</code> of any
+ column, or specific column(s), of a table, view, etc.
+ (In practice, any nontrivial <code class="command">UPDATE</code> command will
+ require <code class="literal">SELECT</code> privilege as well, since it must
+ reference table columns to determine which rows to update, and/or to
+ compute new values for columns.)
+ <code class="literal">SELECT ... FOR UPDATE</code>
+ and <code class="literal">SELECT ... FOR SHARE</code>
+ also require this privilege on at least one column, in addition to the
+ <code class="literal">SELECT</code> privilege. For sequences, this
+ privilege allows use of the <code class="function">nextval</code> and
+ <code class="function">setval</code> functions.
+ For large objects, this privilege allows writing or truncating the
+ object.
+ </p></dd><dt><span class="term"><code class="literal">DELETE</code></span></dt><dd><p>
+ Allows <code class="command">DELETE</code> of a row from a table, view, etc.
+ (In practice, any nontrivial <code class="command">DELETE</code> command will
+ require <code class="literal">SELECT</code> privilege as well, since it must
+ reference table columns to determine which rows to delete.)
+ </p></dd><dt><span class="term"><code class="literal">TRUNCATE</code></span></dt><dd><p>
+ Allows <code class="command">TRUNCATE</code> on a table.
+ </p></dd><dt><span class="term"><code class="literal">REFERENCES</code></span></dt><dd><p>
+ Allows creation of a foreign key constraint referencing a
+ table, or specific column(s) of a table.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER</code></span></dt><dd><p>
+ Allows creation of a trigger on a table, view, etc.
+ </p></dd><dt><span class="term"><code class="literal">CREATE</code></span></dt><dd><p>
+ For databases, allows new schemas and publications to be created within
+ the database, and allows trusted extensions to be installed within
+ the database.
+ </p><p>
+ For schemas, allows new objects to be created within the schema.
+ To rename an existing object, you must own the
+ object <span class="emphasis"><em>and</em></span> have this privilege for the containing
+ schema.
+ </p><p>
+ For tablespaces, allows tables, indexes, and temporary files to be
+ created within the tablespace, and allows databases to be created that
+ have the tablespace as their default tablespace.
+ </p><p>
+ Note that revoking this privilege will not alter the existence or
+ location of existing objects.
+ </p></dd><dt><span class="term"><code class="literal">CONNECT</code></span></dt><dd><p>
+ Allows the grantee to connect to the database. This
+ privilege is checked at connection startup (in addition to checking
+ any restrictions imposed by <code class="filename">pg_hba.conf</code>).
+ </p></dd><dt><span class="term"><code class="literal">TEMPORARY</code></span></dt><dd><p>
+ Allows temporary tables to be created while using the database.
+ </p></dd><dt><span class="term"><code class="literal">EXECUTE</code></span></dt><dd><p>
+ Allows calling a function or procedure, including use of
+ any operators that are implemented on top of the function. This is the
+ only type of privilege that is applicable to functions and procedures.
+ </p></dd><dt><span class="term"><code class="literal">USAGE</code></span></dt><dd><p>
+ For procedural languages, allows use of the language for
+ the creation of functions in that language. This is the only type
+ of privilege that is applicable to procedural languages.
+ </p><p>
+ For schemas, allows access to objects contained in the
+ schema (assuming that the objects' own privilege requirements are
+ also met). Essentially this allows the grantee to <span class="quote">“<span class="quote">look up</span>”</span>
+ objects within the schema. Without this permission, it is still
+ possible to see the object names, e.g., by querying system catalogs.
+ Also, after revoking this permission, existing sessions might have
+ statements that have previously performed this lookup, so this is not
+ a completely secure way to prevent object access.
+ </p><p>
+ For sequences, allows use of the
+ <code class="function">currval</code> and <code class="function">nextval</code> functions.
+ </p><p>
+ For types and domains, allows use of the type or domain in the
+ creation of tables, functions, and other schema objects. (Note that
+ this privilege does not control all <span class="quote">“<span class="quote">usage</span>”</span> of the
+ type, such as values of the type appearing in queries. It only
+ prevents objects from being created that depend on the type. The
+ main purpose of this privilege is controlling which users can create
+ dependencies on a type, which could prevent the owner from changing
+ the type later.)
+ </p><p>
+ For foreign-data wrappers, allows creation of new servers using the
+ foreign-data wrapper.
+ </p><p>
+ For foreign servers, allows creation of foreign tables using the
+ server. Grantees may also create, alter, or drop their own user
+ mappings associated with that server.
+ </p></dd><dt><span class="term"><code class="literal">SET</code></span></dt><dd><p>
+ Allows a server configuration parameter to be set to a new value
+ within the current session. (While this privilege can be granted
+ on any parameter, it is meaningless except for parameters that would
+ normally require superuser privilege to set.)
+ </p></dd><dt><span class="term"><code class="literal">ALTER SYSTEM</code></span></dt><dd><p>
+ Allows a server configuration parameter to be configured to a new
+ value using the <a class="xref" href="sql-altersystem.html" title="ALTER SYSTEM"><span class="refentrytitle">ALTER SYSTEM</span></a> command.
+ </p></dd></dl></div><p>
+
+ The privileges required by other commands are listed on the
+ reference page of the respective command.
+ </p><p>
+ PostgreSQL grants privileges on some types of objects to
+ <code class="literal">PUBLIC</code> by default when the objects are created.
+ No privileges are granted to <code class="literal">PUBLIC</code> by default on
+ tables,
+ table columns,
+ sequences,
+ foreign data wrappers,
+ foreign servers,
+ large objects,
+ schemas,
+ tablespaces,
+ or configuration parameters.
+ For other types of objects, the default privileges
+ granted to <code class="literal">PUBLIC</code> are as follows:
+ <code class="literal">CONNECT</code> and <code class="literal">TEMPORARY</code> (create
+ temporary tables) privileges for databases;
+ <code class="literal">EXECUTE</code> privilege for functions and procedures; and
+ <code class="literal">USAGE</code> privilege for languages and data types
+ (including domains).
+ The object owner can, of course, <code class="command">REVOKE</code>
+ both default and expressly granted privileges. (For maximum
+ security, issue the <code class="command">REVOKE</code> in the same transaction that
+ creates the object; then there is no window in which another user
+ can use the object.)
+ Also, these default privilege settings can be overridden using the
+ <a class="xref" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES"><span class="refentrytitle">ALTER DEFAULT PRIVILEGES</span></a> command.
+ </p><p>
+ <a class="xref" href="ddl-priv.html#PRIVILEGE-ABBREVS-TABLE" title="Table 5.1. ACL Privilege Abbreviations">Table 5.1</a> shows the one-letter
+ abbreviations that are used for these privilege types in
+ <em class="firstterm">ACL</em> (Access Control List) values.
+ You will see these letters in the output of the <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>
+ commands listed below, or when looking at ACL columns of system catalogs.
+ </p><div class="table" id="PRIVILEGE-ABBREVS-TABLE"><p class="title"><strong>Table 5.1. ACL Privilege Abbreviations</strong></p><div class="table-contents"><table class="table" summary="ACL Privilege Abbreviations" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Privilege</th><th>Abbreviation</th><th>Applicable Object Types</th></tr></thead><tbody><tr><td><code class="literal">SELECT</code></td><td><code class="literal">r</code> (<span class="quote">“<span class="quote">read</span>”</span>)</td><td>
+ <code class="literal">LARGE OBJECT</code>,
+ <code class="literal">SEQUENCE</code>,
+ <code class="literal">TABLE</code> (and table-like objects),
+ table column
+ </td></tr><tr><td><code class="literal">INSERT</code></td><td><code class="literal">a</code> (<span class="quote">“<span class="quote">append</span>”</span>)</td><td><code class="literal">TABLE</code>, table column</td></tr><tr><td><code class="literal">UPDATE</code></td><td><code class="literal">w</code> (<span class="quote">“<span class="quote">write</span>”</span>)</td><td>
+ <code class="literal">LARGE OBJECT</code>,
+ <code class="literal">SEQUENCE</code>,
+ <code class="literal">TABLE</code>,
+ table column
+ </td></tr><tr><td><code class="literal">DELETE</code></td><td><code class="literal">d</code></td><td><code class="literal">TABLE</code></td></tr><tr><td><code class="literal">TRUNCATE</code></td><td><code class="literal">D</code></td><td><code class="literal">TABLE</code></td></tr><tr><td><code class="literal">REFERENCES</code></td><td><code class="literal">x</code></td><td><code class="literal">TABLE</code>, table column</td></tr><tr><td><code class="literal">TRIGGER</code></td><td><code class="literal">t</code></td><td><code class="literal">TABLE</code></td></tr><tr><td><code class="literal">CREATE</code></td><td><code class="literal">C</code></td><td>
+ <code class="literal">DATABASE</code>,
+ <code class="literal">SCHEMA</code>,
+ <code class="literal">TABLESPACE</code>
+ </td></tr><tr><td><code class="literal">CONNECT</code></td><td><code class="literal">c</code></td><td><code class="literal">DATABASE</code></td></tr><tr><td><code class="literal">TEMPORARY</code></td><td><code class="literal">T</code></td><td><code class="literal">DATABASE</code></td></tr><tr><td><code class="literal">EXECUTE</code></td><td><code class="literal">X</code></td><td><code class="literal">FUNCTION</code>, <code class="literal">PROCEDURE</code></td></tr><tr><td><code class="literal">USAGE</code></td><td><code class="literal">U</code></td><td>
+ <code class="literal">DOMAIN</code>,
+ <code class="literal">FOREIGN DATA WRAPPER</code>,
+ <code class="literal">FOREIGN SERVER</code>,
+ <code class="literal">LANGUAGE</code>,
+ <code class="literal">SCHEMA</code>,
+ <code class="literal">SEQUENCE</code>,
+ <code class="literal">TYPE</code>
+ </td></tr><tr><td><code class="literal">SET</code></td><td><code class="literal">s</code></td><td><code class="literal">PARAMETER</code></td></tr><tr><td><code class="literal">ALTER SYSTEM</code></td><td><code class="literal">A</code></td><td><code class="literal">PARAMETER</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="ddl-priv.html#PRIVILEGES-SUMMARY-TABLE" title="Table 5.2. Summary of Access Privileges">Table 5.2</a> summarizes the privileges
+ available for each type of SQL object, using the abbreviations shown
+ above.
+ It also shows the <span class="application">psql</span> command
+ that can be used to examine privilege settings for each object type.
+ </p><div class="table" id="PRIVILEGES-SUMMARY-TABLE"><p class="title"><strong>Table 5.2. Summary of Access Privileges</strong></p><div class="table-contents"><table class="table" summary="Summary of Access Privileges" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Object Type</th><th>All Privileges</th><th>Default <code class="literal">PUBLIC</code> Privileges</th><th><span class="application">psql</span> Command</th></tr></thead><tbody><tr><td><code class="literal">DATABASE</code></td><td><code class="literal">CTc</code></td><td><code class="literal">Tc</code></td><td><code class="literal">\l</code></td></tr><tr><td><code class="literal">DOMAIN</code></td><td><code class="literal">U</code></td><td><code class="literal">U</code></td><td><code class="literal">\dD+</code></td></tr><tr><td><code class="literal">FUNCTION</code> or <code class="literal">PROCEDURE</code></td><td><code class="literal">X</code></td><td><code class="literal">X</code></td><td><code class="literal">\df+</code></td></tr><tr><td><code class="literal">FOREIGN DATA WRAPPER</code></td><td><code class="literal">U</code></td><td>none</td><td><code class="literal">\dew+</code></td></tr><tr><td><code class="literal">FOREIGN SERVER</code></td><td><code class="literal">U</code></td><td>none</td><td><code class="literal">\des+</code></td></tr><tr><td><code class="literal">LANGUAGE</code></td><td><code class="literal">U</code></td><td><code class="literal">U</code></td><td><code class="literal">\dL+</code></td></tr><tr><td><code class="literal">LARGE OBJECT</code></td><td><code class="literal">rw</code></td><td>none</td><td><code class="literal">\dl+</code></td></tr><tr><td><code class="literal">PARAMETER</code></td><td><code class="literal">sA</code></td><td>none</td><td><code class="literal">\dconfig+</code></td></tr><tr><td><code class="literal">SCHEMA</code></td><td><code class="literal">UC</code></td><td>none</td><td><code class="literal">\dn+</code></td></tr><tr><td><code class="literal">SEQUENCE</code></td><td><code class="literal">rwU</code></td><td>none</td><td><code class="literal">\dp</code></td></tr><tr><td><code class="literal">TABLE</code> (and table-like objects)</td><td><code class="literal">arwdDxt</code></td><td>none</td><td><code class="literal">\dp</code></td></tr><tr><td>Table column</td><td><code class="literal">arwx</code></td><td>none</td><td><code class="literal">\dp</code></td></tr><tr><td><code class="literal">TABLESPACE</code></td><td><code class="literal">C</code></td><td>none</td><td><code class="literal">\db+</code></td></tr><tr><td><code class="literal">TYPE</code></td><td><code class="literal">U</code></td><td><code class="literal">U</code></td><td><code class="literal">\dT+</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a id="id-1.5.4.9.23.1" class="indexterm"></a>
+ The privileges that have been granted for a particular object are
+ displayed as a list of <code class="type">aclitem</code> entries, where each
+ <code class="type">aclitem</code> describes the permissions of one grantee that
+ have been granted by a particular grantor. For example,
+ <code class="literal">calvin=r*w/hobbes</code> specifies that the role
+ <code class="literal">calvin</code> has the privilege
+ <code class="literal">SELECT</code> (<code class="literal">r</code>) with grant option
+ (<code class="literal">*</code>) as well as the non-grantable
+ privilege <code class="literal">UPDATE</code> (<code class="literal">w</code>), both granted
+ by the role <code class="literal">hobbes</code>. If <code class="literal">calvin</code>
+ also has some privileges on the same object granted by a different
+ grantor, those would appear as a separate <code class="type">aclitem</code> entry.
+ An empty grantee field in an <code class="type">aclitem</code> stands
+ for <code class="literal">PUBLIC</code>.
+ </p><p>
+ As an example, suppose that user <code class="literal">miriam</code> creates
+ table <code class="literal">mytable</code> and does:
+</p><pre class="programlisting">
+GRANT SELECT ON mytable TO PUBLIC;
+GRANT SELECT, UPDATE, INSERT ON mytable TO admin;
+GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw;
+</pre><p>
+ Then <span class="application">psql</span>'s <code class="literal">\dp</code> command
+ would show:
+</p><pre class="programlisting">
+=&gt; \dp mytable
+ Access privileges
+ Schema | Name | Type | Access privileges | Column privileges | Policies
+--------+---------+-------+-----------------------+-----------------------+----------
+ public | mytable | table | miriam=arwdDxt/miriam+| col1: +|
+ | | | =r/miriam +| miriam_rw=rw/miriam |
+ | | | admin=arw/miriam | |
+(1 row)
+</pre><p>
+ </p><p>
+ If the <span class="quote">“<span class="quote">Access privileges</span>”</span> column is empty for a given
+ object, it means the object has default privileges (that is, its
+ privileges entry in the relevant system catalog is null). Default
+ privileges always include all privileges for the owner, and can include
+ some privileges for <code class="literal">PUBLIC</code> depending on the object
+ type, as explained above. The first <code class="command">GRANT</code>
+ or <code class="command">REVOKE</code> on an object will instantiate the default
+ privileges (producing, for
+ example, <code class="literal">miriam=arwdDxt/miriam</code>) and then modify them
+ per the specified request. Similarly, entries are shown in <span class="quote">“<span class="quote">Column
+ privileges</span>”</span> only for columns with nondefault privileges.
+ (Note: for this purpose, <span class="quote">“<span class="quote">default privileges</span>”</span> always means
+ the built-in default privileges for the object's type. An object whose
+ privileges have been affected by an <code class="command">ALTER DEFAULT
+ PRIVILEGES</code> command will always be shown with an explicit
+ privilege entry that includes the effects of
+ the <code class="command">ALTER</code>.)
+ </p><p>
+ Notice that the owner's implicit grant options are not marked in the
+ access privileges display. A <code class="literal">*</code> will appear only when
+ grant options have been explicitly granted to someone.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-alter.html" title="5.6. Modifying Tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.6. Modifying Tables </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.8. Row Security Policies</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-rowsecurity.html b/doc/src/sgml/html/ddl-rowsecurity.html
new file mode 100644
index 0000000..41ef466
--- /dev/null
+++ b/doc/src/sgml/html/ddl-rowsecurity.html
@@ -0,0 +1,382 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.8. Row Security Policies</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-priv.html" title="5.7. Privileges" /><link rel="next" href="ddl-schemas.html" title="5.9. Schemas" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.8. Row Security Policies</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-priv.html" title="5.7. Privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-schemas.html" title="5.9. Schemas">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-ROWSECURITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.8. Row Security Policies</h2></div></div></div><a id="id-1.5.4.10.2" class="indexterm"></a><a id="id-1.5.4.10.3" class="indexterm"></a><p>
+ In addition to the SQL-standard <a class="link" href="ddl-priv.html" title="5.7. Privileges">privilege
+ system</a> available through <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>,
+ tables can have <em class="firstterm">row security policies</em> that restrict,
+ on a per-user basis, which rows can be returned by normal queries
+ or inserted, updated, or deleted by data modification commands.
+ This feature is also known as <em class="firstterm">Row-Level Security</em>.
+ By default, tables do not have any policies, so that if a user has
+ access privileges to a table according to the SQL privilege system,
+ all rows within it are equally available for querying or updating.
+ </p><p>
+ When row security is enabled on a table (with
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE">ALTER TABLE ... ENABLE ROW LEVEL
+ SECURITY</a>), all normal access to the table for selecting rows or
+ modifying rows must be allowed by a row security policy. (However, the
+ table's owner is typically not subject to row security policies.) If no
+ policy exists for the table, a default-deny policy is used, meaning that
+ no rows are visible or can be modified. Operations that apply to the
+ whole table, such as <code class="command">TRUNCATE</code> and <code class="literal">REFERENCES</code>,
+ are not subject to row security.
+ </p><p>
+ Row security policies can be specific to commands, or to roles, or to
+ both. A policy can be specified to apply to <code class="literal">ALL</code>
+ commands, or to <code class="literal">SELECT</code>, <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ or <code class="literal">DELETE</code>. Multiple roles can be assigned to a given
+ policy, and normal role membership and inheritance rules apply.
+ </p><p>
+ To specify which rows are visible or modifiable according to a policy,
+ an expression is required that returns a Boolean result. This
+ expression will be evaluated for each row prior to any conditions or
+ functions coming from the user's query. (The only exceptions to this
+ rule are <code class="literal">leakproof</code> functions, which are guaranteed to
+ not leak information; the optimizer may choose to apply such functions
+ ahead of the row-security check.) Rows for which the expression does
+ not return <code class="literal">true</code> will not be processed. Separate expressions
+ may be specified to provide independent control over the rows which are
+ visible and the rows which are allowed to be modified. Policy
+ expressions are run as part of the query and with the privileges of the
+ user running the query, although security-definer functions can be used
+ to access data not available to the calling user.
+ </p><p>
+ Superusers and roles with the <code class="literal">BYPASSRLS</code> attribute always
+ bypass the row security system when accessing a table. Table owners
+ normally bypass row security as well, though a table owner can choose to
+ be subject to row security with <a class="link" href="sql-altertable.html" title="ALTER TABLE">ALTER
+ TABLE ... FORCE ROW LEVEL SECURITY</a>.
+ </p><p>
+ Enabling and disabling row security, as well as adding policies to a
+ table, is always the privilege of the table owner only.
+ </p><p>
+ Policies are created using the <a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a>
+ command, altered using the <a class="xref" href="sql-alterpolicy.html" title="ALTER POLICY"><span class="refentrytitle">ALTER POLICY</span></a> command,
+ and dropped using the <a class="xref" href="sql-droppolicy.html" title="DROP POLICY"><span class="refentrytitle">DROP POLICY</span></a> command. To
+ enable and disable row security for a given table, use the
+ <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a> command.
+ </p><p>
+ Each policy has a name and multiple policies can be defined for a
+ table. As policies are table-specific, each policy for a table must
+ have a unique name. Different tables may have policies with the
+ same name.
+ </p><p>
+ When multiple policies apply to a given query, they are combined using
+ either <code class="literal">OR</code> (for permissive policies, which are the
+ default) or using <code class="literal">AND</code> (for restrictive policies).
+ This is similar to the rule that a given role has the privileges
+ of all roles that they are a member of. Permissive vs. restrictive
+ policies are discussed further below.
+ </p><p>
+ As a simple example, here is how to create a policy on
+ the <code class="literal">account</code> relation to allow only members of
+ the <code class="literal">managers</code> role to access rows, and only rows of their
+ accounts:
+ </p><pre class="programlisting">
+CREATE TABLE accounts (manager text, company text, contact_email text);
+
+ALTER TABLE accounts ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY account_managers ON accounts TO managers
+ USING (manager = current_user);
+</pre><p>
+ The policy above implicitly provides a <code class="literal">WITH CHECK</code>
+ clause identical to its <code class="literal">USING</code> clause, so that the
+ constraint applies both to rows selected by a command (so a manager
+ cannot <code class="command">SELECT</code>, <code class="command">UPDATE</code>,
+ or <code class="command">DELETE</code> existing rows belonging to a different
+ manager) and to rows modified by a command (so rows belonging to a
+ different manager cannot be created via <code class="command">INSERT</code>
+ or <code class="command">UPDATE</code>).
+ </p><p>
+ If no role is specified, or the special user name
+ <code class="literal">PUBLIC</code> is used, then the policy applies to all
+ users on the system. To allow all users to access only their own row in
+ a <code class="literal">users</code> table, a simple policy can be used:
+ </p><pre class="programlisting">
+CREATE POLICY user_policy ON users
+ USING (user_name = current_user);
+</pre><p>
+ This works similarly to the previous example.
+ </p><p>
+ To use a different policy for rows that are being added to the table
+ compared to those rows that are visible, multiple policies can be
+ combined. This pair of policies would allow all users to view all rows
+ in the <code class="literal">users</code> table, but only modify their own:
+ </p><pre class="programlisting">
+CREATE POLICY user_sel_policy ON users
+ FOR SELECT
+ USING (true);
+CREATE POLICY user_mod_policy ON users
+ USING (user_name = current_user);
+</pre><p>
+ In a <code class="command">SELECT</code> command, these two policies are combined
+ using <code class="literal">OR</code>, with the net effect being that all rows
+ can be selected. In other command types, only the second policy applies,
+ so that the effects are the same as before.
+ </p><p>
+ Row security can also be disabled with the <code class="command">ALTER TABLE</code>
+ command. Disabling row security does not remove any policies that are
+ defined on the table; they are simply ignored. Then all rows in the
+ table are visible and modifiable, subject to the standard SQL privileges
+ system.
+ </p><p>
+ Below is a larger example of how this feature can be used in production
+ environments. The table <code class="literal">passwd</code> emulates a Unix password
+ file:
+ </p><pre class="programlisting">
+-- Simple passwd-file based example
+CREATE TABLE passwd (
+ user_name text UNIQUE NOT NULL,
+ pwhash text,
+ uid int PRIMARY KEY,
+ gid int NOT NULL,
+ real_name text NOT NULL,
+ home_phone text,
+ extra_info text,
+ home_dir text NOT NULL,
+ shell text NOT NULL
+);
+
+CREATE ROLE admin; -- Administrator
+CREATE ROLE bob; -- Normal user
+CREATE ROLE alice; -- Normal user
+
+-- Populate the table
+INSERT INTO passwd VALUES
+ ('admin','xxx',0,0,'Admin','111-222-3333',null,'/root','/bin/dash');
+INSERT INTO passwd VALUES
+ ('bob','xxx',1,1,'Bob','123-456-7890',null,'/home/bob','/bin/zsh');
+INSERT INTO passwd VALUES
+ ('alice','xxx',2,1,'Alice','098-765-4321',null,'/home/alice','/bin/zsh');
+
+-- Be sure to enable row-level security on the table
+ALTER TABLE passwd ENABLE ROW LEVEL SECURITY;
+
+-- Create policies
+-- Administrator can see all rows and add any rows
+CREATE POLICY admin_all ON passwd TO admin USING (true) WITH CHECK (true);
+-- Normal users can view all rows
+CREATE POLICY all_view ON passwd FOR SELECT USING (true);
+-- Normal users can update their own records, but
+-- limit which shells a normal user is allowed to set
+CREATE POLICY user_mod ON passwd FOR UPDATE
+ USING (current_user = user_name)
+ WITH CHECK (
+ current_user = user_name AND
+ shell IN ('/bin/bash','/bin/sh','/bin/dash','/bin/zsh','/bin/tcsh')
+ );
+
+-- Allow admin all normal rights
+GRANT SELECT, INSERT, UPDATE, DELETE ON passwd TO admin;
+-- Users only get select access on public columns
+GRANT SELECT
+ (user_name, uid, gid, real_name, home_phone, extra_info, home_dir, shell)
+ ON passwd TO public;
+-- Allow users to update certain columns
+GRANT UPDATE
+ (pwhash, real_name, home_phone, extra_info, shell)
+ ON passwd TO public;
+</pre><p>
+ As with any security settings, it's important to test and ensure that
+ the system is behaving as expected. Using the example above, this
+ demonstrates that the permission system is working properly.
+ </p><pre class="programlisting">
+-- admin can view all rows and fields
+postgres=&gt; set role admin;
+SET
+postgres=&gt; table passwd;
+ user_name | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell
+-----------+--------+-----+-----+-----------+--------------+------------+-------------+-----------
+ admin | xxx | 0 | 0 | Admin | 111-222-3333 | | /root | /bin/dash
+ bob | xxx | 1 | 1 | Bob | 123-456-7890 | | /home/bob | /bin/zsh
+ alice | xxx | 2 | 1 | Alice | 098-765-4321 | | /home/alice | /bin/zsh
+(3 rows)
+
+-- Test what Alice is able to do
+postgres=&gt; set role alice;
+SET
+postgres=&gt; table passwd;
+ERROR: permission denied for table passwd
+postgres=&gt; select user_name,real_name,home_phone,extra_info,home_dir,shell from passwd;
+ user_name | real_name | home_phone | extra_info | home_dir | shell
+-----------+-----------+--------------+------------+-------------+-----------
+ admin | Admin | 111-222-3333 | | /root | /bin/dash
+ bob | Bob | 123-456-7890 | | /home/bob | /bin/zsh
+ alice | Alice | 098-765-4321 | | /home/alice | /bin/zsh
+(3 rows)
+
+postgres=&gt; update passwd set user_name = 'joe';
+ERROR: permission denied for table passwd
+-- Alice is allowed to change her own real_name, but no others
+postgres=&gt; update passwd set real_name = 'Alice Doe';
+UPDATE 1
+postgres=&gt; update passwd set real_name = 'John Doe' where user_name = 'admin';
+UPDATE 0
+postgres=&gt; update passwd set shell = '/bin/xx';
+ERROR: new row violates WITH CHECK OPTION for "passwd"
+postgres=&gt; delete from passwd;
+ERROR: permission denied for table passwd
+postgres=&gt; insert into passwd (user_name) values ('xxx');
+ERROR: permission denied for table passwd
+-- Alice can change her own password; RLS silently prevents updating other rows
+postgres=&gt; update passwd set pwhash = 'abc';
+UPDATE 1
+</pre><p>
+ All of the policies constructed thus far have been permissive policies,
+ meaning that when multiple policies are applied they are combined using
+ the <span class="quote">“<span class="quote">OR</span>”</span> Boolean operator. While permissive policies can be constructed
+ to only allow access to rows in the intended cases, it can be simpler to
+ combine permissive policies with restrictive policies (which the records
+ must pass and which are combined using the <span class="quote">“<span class="quote">AND</span>”</span> Boolean operator).
+ Building on the example above, we add a restrictive policy to require
+ the administrator to be connected over a local Unix socket to access the
+ records of the <code class="literal">passwd</code> table:
+ </p><pre class="programlisting">
+CREATE POLICY admin_local_only ON passwd AS RESTRICTIVE TO admin
+ USING (pg_catalog.inet_client_addr() IS NULL);
+</pre><p>
+ We can then see that an administrator connecting over a network will not
+ see any records, due to the restrictive policy:
+ </p><pre class="programlisting">
+=&gt; SELECT current_user;
+ current_user
+--------------
+ admin
+(1 row)
+
+=&gt; select inet_client_addr();
+ inet_client_addr
+------------------
+ 127.0.0.1
+(1 row)
+
+=&gt; TABLE passwd;
+ user_name | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell
+-----------+--------+-----+-----+-----------+------------+------------+----------+-------
+(0 rows)
+
+=&gt; UPDATE passwd set pwhash = NULL;
+UPDATE 0
+</pre><p>
+ Referential integrity checks, such as unique or primary key constraints
+ and foreign key references, always bypass row security to ensure that
+ data integrity is maintained. Care must be taken when developing
+ schemas and row level policies to avoid <span class="quote">“<span class="quote">covert channel</span>”</span> leaks of
+ information through such referential integrity checks.
+ </p><p>
+ In some contexts it is important to be sure that row security is
+ 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
+ <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> configuration parameter
+ to <code class="literal">off</code>. 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
+ fixed.
+ </p><p>
+ In the examples above, the policy expressions consider only the current
+ values in the row to be accessed or updated. This is the simplest and
+ best-performing case; when possible, it's best to design row security
+ applications to work this way. If it is necessary to consult other rows
+ or other tables to make a policy decision, that can be accomplished using
+ sub-<code class="command">SELECT</code>s, or functions that contain <code class="command">SELECT</code>s,
+ in the policy expressions. Be aware however that such accesses can
+ create race conditions that could allow information leakage if care is
+ not taken. As an example, consider the following table design:
+ </p><pre class="programlisting">
+-- definition of privilege groups
+CREATE TABLE groups (group_id int PRIMARY KEY,
+ group_name text NOT NULL);
+
+INSERT INTO groups VALUES
+ (1, 'low'),
+ (2, 'medium'),
+ (5, 'high');
+
+GRANT ALL ON groups TO alice; -- alice is the administrator
+GRANT SELECT ON groups TO public;
+
+-- definition of users' privilege levels
+CREATE TABLE users (user_name text PRIMARY KEY,
+ group_id int NOT NULL REFERENCES groups);
+
+INSERT INTO users VALUES
+ ('alice', 5),
+ ('bob', 2),
+ ('mallory', 2);
+
+GRANT ALL ON users TO alice;
+GRANT SELECT ON users TO public;
+
+-- table holding the information to be protected
+CREATE TABLE information (info text,
+ group_id int NOT NULL REFERENCES groups);
+
+INSERT INTO information VALUES
+ ('barely secret', 1),
+ ('slightly secret', 2),
+ ('very secret', 5);
+
+ALTER TABLE information ENABLE ROW LEVEL SECURITY;
+
+-- a row should be visible to/updatable by users whose security group_id is
+-- greater than or equal to the row's group_id
+CREATE POLICY fp_s ON information FOR SELECT
+ USING (group_id &lt;= (SELECT group_id FROM users WHERE user_name = current_user));
+CREATE POLICY fp_u ON information FOR UPDATE
+ USING (group_id &lt;= (SELECT group_id FROM users WHERE user_name = current_user));
+
+-- we rely only on RLS to protect the information table
+GRANT ALL ON information TO public;
+</pre><p>
+ Now suppose that <code class="literal">alice</code> wishes to change the <span class="quote">“<span class="quote">slightly
+ secret</span>”</span> information, but decides that <code class="literal">mallory</code> should not
+ be trusted with the new content of that row, so she does:
+ </p><pre class="programlisting">
+BEGIN;
+UPDATE users SET group_id = 1 WHERE user_name = 'mallory';
+UPDATE information SET info = 'secret from mallory' WHERE group_id = 2;
+COMMIT;
+</pre><p>
+ That looks safe; there is no window wherein <code class="literal">mallory</code> should be
+ able to see the <span class="quote">“<span class="quote">secret from mallory</span>”</span> string. However, there is
+ a race condition here. If <code class="literal">mallory</code> is concurrently doing,
+ say,
+</p><pre class="programlisting">
+SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
+</pre><p>
+ and her transaction is in <code class="literal">READ COMMITTED</code> mode, it is possible
+ for her to see <span class="quote">“<span class="quote">secret from mallory</span>”</span>. That happens if her
+ transaction reaches the <code class="structname">information</code> row just
+ after <code class="literal">alice</code>'s does. It blocks waiting
+ for <code class="literal">alice</code>'s transaction to commit, then fetches the updated
+ row contents thanks to the <code class="literal">FOR UPDATE</code> clause. However, it
+ does <span class="emphasis"><em>not</em></span> fetch an updated row for the
+ implicit <code class="command">SELECT</code> from <code class="structname">users</code>, because that
+ sub-<code class="command">SELECT</code> did not have <code class="literal">FOR UPDATE</code>; instead
+ the <code class="structname">users</code> row is read with the snapshot taken at the start
+ of the query. Therefore, the policy expression tests the old value
+ of <code class="literal">mallory</code>'s privilege level and allows her to see the
+ updated row.
+ </p><p>
+ There are several ways around this problem. One simple answer is to use
+ <code class="literal">SELECT ... FOR SHARE</code> in sub-<code class="command">SELECT</code>s in row
+ security policies. However, that requires granting <code class="literal">UPDATE</code>
+ privilege on the referenced table (here <code class="structname">users</code>) to the
+ affected users, which might be undesirable. (But another row security
+ policy could be applied to prevent them from actually exercising that
+ privilege; or the sub-<code class="command">SELECT</code> could be embedded into a security
+ definer function.) Also, heavy concurrent use of row share locks on the
+ referenced table could pose a performance problem, especially if updates
+ of it are frequent. Another solution, practical if updates of the
+ referenced table are infrequent, is to take an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the
+ referenced table when updating it, so that no concurrent transactions
+ could be examining old row values. Or one could just wait for all
+ concurrent transactions to end after committing an update of the
+ referenced table and before making changes that rely on the new security
+ situation.
+ </p><p>
+ For additional details see <a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a>
+ and <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-priv.html" title="5.7. Privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-schemas.html" title="5.9. Schemas">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.7. Privileges </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.9. Schemas</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-schemas.html b/doc/src/sgml/html/ddl-schemas.html
new file mode 100644
index 0000000..6b7491c
--- /dev/null
+++ b/doc/src/sgml/html/ddl-schemas.html
@@ -0,0 +1,329 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.9. Schemas</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-rowsecurity.html" title="5.8. Row Security Policies" /><link rel="next" href="ddl-inherit.html" title="5.10. Inheritance" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.9. Schemas</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-inherit.html" title="5.10. Inheritance">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-SCHEMAS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.9. Schemas</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-CREATE">5.9.1. Creating a Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PUBLIC">5.9.2. The Public Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PATH">5.9.3. The Schema Search Path</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PRIV">5.9.4. Schemas and Privileges</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-CATALOG">5.9.5. The System Catalog Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS">5.9.6. Usage Patterns</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PORTABILITY">5.9.7. Portability</a></span></dt></dl></div><a id="id-1.5.4.11.2" class="indexterm"></a><p>
+ A <span class="productname">PostgreSQL</span> database cluster contains
+ one or more named databases. Roles and a few other object types are
+ shared across the entire cluster. A client connection to the server
+ can only access data in a single database, the one specified in the
+ connection request.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Users of a cluster do not necessarily have the privilege to access every
+ database in the cluster. Sharing of role names means that there
+ cannot be different roles named, say, <code class="literal">joe</code> in two databases
+ in the same cluster; but the system can be configured to allow
+ <code class="literal">joe</code> access to only some of the databases.
+ </p></div><p>
+ A database contains one or more named <em class="firstterm">schemas</em>, which
+ in turn contain tables. Schemas also contain other kinds of named
+ objects, including data types, functions, and operators. The same
+ object name can be used in different schemas without conflict; for
+ example, both <code class="literal">schema1</code> and <code class="literal">myschema</code> can
+ contain tables named <code class="literal">mytable</code>. Unlike databases,
+ schemas are not rigidly separated: a user can access objects in any
+ of the schemas in the database they are connected to, if they have
+ privileges to do so.
+ </p><p>
+ There are several reasons why one might want to use schemas:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ To allow many users to use one database without interfering with
+ each other.
+ </p></li><li class="listitem"><p>
+ To organize database objects into logical groups to make them
+ more manageable.
+ </p></li><li class="listitem"><p>
+ Third-party applications can be put into separate schemas so
+ they do not collide with the names of other objects.
+ </p></li></ul></div><p>
+
+ Schemas are analogous to directories at the operating system level,
+ except that schemas cannot be nested.
+ </p><div class="sect2" id="DDL-SCHEMAS-CREATE"><div class="titlepage"><div><div><h3 class="title">5.9.1. Creating a Schema</h3></div></div></div><a id="id-1.5.4.11.7.2" class="indexterm"></a><p>
+ To create a schema, use the <a class="xref" href="sql-createschema.html" title="CREATE SCHEMA"><span class="refentrytitle">CREATE SCHEMA</span></a>
+ command. Give the schema a name
+ of your choice. For example:
+</p><pre class="programlisting">
+CREATE SCHEMA myschema;
+</pre><p>
+ </p><a id="id-1.5.4.11.7.4" class="indexterm"></a><a id="id-1.5.4.11.7.5" class="indexterm"></a><p>
+ To create or access objects in a schema, write a
+ <em class="firstterm">qualified name</em> consisting of the schema name and
+ table name separated by a dot:
+</p><pre class="synopsis">
+<em class="replaceable"><code>schema</code></em><code class="literal">.</code><em class="replaceable"><code>table</code></em>
+</pre><p>
+ This works anywhere a table name is expected, including the table
+ modification commands and the data access commands discussed in
+ the following chapters.
+ (For brevity we will speak of tables only, but the same ideas apply
+ to other kinds of named objects, such as types and functions.)
+ </p><p>
+ Actually, the even more general syntax
+</p><pre class="synopsis">
+<em class="replaceable"><code>database</code></em><code class="literal">.</code><em class="replaceable"><code>schema</code></em><code class="literal">.</code><em class="replaceable"><code>table</code></em>
+</pre><p>
+ can be used too, but at present this is just for pro forma
+ compliance with the SQL standard. If you write a database name,
+ it must be the same as the database you are connected to.
+ </p><p>
+ So to create a table in the new schema, use:
+</p><pre class="programlisting">
+CREATE TABLE myschema.mytable (
+ ...
+);
+</pre><p>
+ </p><a id="id-1.5.4.11.7.9" class="indexterm"></a><p>
+ To drop a schema if it's empty (all objects in it have been
+ dropped), use:
+</p><pre class="programlisting">
+DROP SCHEMA myschema;
+</pre><p>
+ To drop a schema including all contained objects, use:
+</p><pre class="programlisting">
+DROP SCHEMA myschema CASCADE;
+</pre><p>
+ See <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a> for a description of the general
+ mechanism behind this.
+ </p><p>
+ Often you will want to create a schema owned by someone else
+ (since this is one of the ways to restrict the activities of your
+ users to well-defined namespaces). The syntax for that is:
+</p><pre class="programlisting">
+CREATE SCHEMA <em class="replaceable"><code>schema_name</code></em> AUTHORIZATION <em class="replaceable"><code>user_name</code></em>;
+</pre><p>
+ You can even omit the schema name, in which case the schema name
+ will be the same as the user name. See <a class="xref" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">Section 5.9.6</a> for how this can be useful.
+ </p><p>
+ Schema names beginning with <code class="literal">pg_</code> are reserved for
+ system purposes and cannot be created by users.
+ </p></div><div class="sect2" id="DDL-SCHEMAS-PUBLIC"><div class="titlepage"><div><div><h3 class="title">5.9.2. The Public Schema</h3></div></div></div><a id="id-1.5.4.11.8.2" class="indexterm"></a><p>
+ In the previous sections we created tables without specifying any
+ schema names. By default such tables (and other objects) are
+ automatically put into a schema named <span class="quote">“<span class="quote">public</span>”</span>. Every new
+ database contains such a schema. Thus, the following are equivalent:
+</p><pre class="programlisting">
+CREATE TABLE products ( ... );
+</pre><p>
+ and:
+</p><pre class="programlisting">
+CREATE TABLE public.products ( ... );
+</pre><p>
+ </p></div><div class="sect2" id="DDL-SCHEMAS-PATH"><div class="titlepage"><div><div><h3 class="title">5.9.3. The Schema Search Path</h3></div></div></div><a id="id-1.5.4.11.9.2" class="indexterm"></a><a id="id-1.5.4.11.9.3" class="indexterm"></a><a id="id-1.5.4.11.9.4" class="indexterm"></a><p>
+ Qualified names are tedious to write, and it's often best not to
+ wire a particular schema name into applications anyway. Therefore
+ tables are often referred to by <em class="firstterm">unqualified names</em>,
+ which consist of just the table name. The system determines which table
+ is meant by following a <em class="firstterm">search path</em>, which is a list
+ of schemas to look in. The first matching table in the search path
+ is taken to be the one wanted. If there is no match in the search
+ path, an error is reported, even if matching table names exist
+ in other schemas in the database.
+ </p><p>
+ The ability to create like-named objects in different schemas complicates
+ writing a query that references precisely the same objects every time. It
+ also opens up the potential for users to change the behavior of other
+ users' queries, maliciously or accidentally. Due to the prevalence of
+ unqualified names in queries and their use
+ in <span class="productname">PostgreSQL</span> internals, adding a schema
+ to <code class="varname">search_path</code> effectively trusts all users having
+ <code class="literal">CREATE</code> privilege on that schema. When you run an
+ ordinary query, a malicious user able to create objects in a schema of
+ your search path can take control and execute arbitrary SQL functions as
+ though you executed them.
+ </p><a id="id-1.5.4.11.9.7" class="indexterm"></a><p>
+ The first schema named in the search path is called the current schema.
+ Aside from being the first schema searched, it is also the schema in
+ which new tables will be created if the <code class="command">CREATE TABLE</code>
+ command does not specify a schema name.
+ </p><a id="id-1.5.4.11.9.9" class="indexterm"></a><p>
+ To show the current search path, use the following command:
+</p><pre class="programlisting">
+SHOW search_path;
+</pre><p>
+ In the default setup this returns:
+</p><pre class="screen">
+ search_path
+--------------
+ "$user", public
+</pre><p>
+ The first element specifies that a schema with the same name as
+ the current user is to be searched. If no such schema exists,
+ the entry is ignored. The second element refers to the
+ public schema that we have seen already.
+ </p><p>
+ The first schema in the search path that exists is the default
+ location for creating new objects. That is the reason that by
+ default objects are created in the public schema. When objects
+ are referenced in any other context without schema qualification
+ (table modification, data modification, or query commands) the
+ search path is traversed until a matching object is found.
+ Therefore, in the default configuration, any unqualified access
+ again can only refer to the public schema.
+ </p><p>
+ To put our new schema in the path, we use:
+</p><pre class="programlisting">
+SET search_path TO myschema,public;
+</pre><p>
+ (We omit the <code class="literal">$user</code> here because we have no
+ immediate need for it.) And then we can access the table without
+ schema qualification:
+</p><pre class="programlisting">
+DROP TABLE mytable;
+</pre><p>
+ Also, since <code class="literal">myschema</code> is the first element in
+ the path, new objects would by default be created in it.
+ </p><p>
+ We could also have written:
+</p><pre class="programlisting">
+SET search_path TO myschema;
+</pre><p>
+ Then we no longer have access to the public schema without
+ explicit qualification. There is nothing special about the public
+ schema except that it exists by default. It can be dropped, too.
+ </p><p>
+ See also <a class="xref" href="functions-info.html" title="9.26. System Information Functions and Operators">Section 9.26</a> for other ways to manipulate
+ the schema search path.
+ </p><p>
+ The search path works in the same way for data type names, function names,
+ and operator names as it does for table names. Data type and function
+ names can be qualified in exactly the same way as table names. If you
+ need to write a qualified operator name in an expression, there is a
+ special provision: you must write
+</p><pre class="synopsis">
+<code class="literal">OPERATOR(</code><em class="replaceable"><code>schema</code></em><code class="literal">.</code><em class="replaceable"><code>operator</code></em><code class="literal">)</code>
+</pre><p>
+ This is needed to avoid syntactic ambiguity. An example is:
+</p><pre class="programlisting">
+SELECT 3 OPERATOR(pg_catalog.+) 4;
+</pre><p>
+ In practice one usually relies on the search path for operators,
+ so as not to have to write anything so ugly as that.
+ </p></div><div class="sect2" id="DDL-SCHEMAS-PRIV"><div class="titlepage"><div><div><h3 class="title">5.9.4. Schemas and Privileges</h3></div></div></div><a id="id-1.5.4.11.10.2" class="indexterm"></a><p>
+ By default, users cannot access any objects in schemas they do not
+ own. To allow that, the owner of the schema must grant the
+ <code class="literal">USAGE</code> privilege on the schema. By default, everyone
+ has that privilege on the schema <code class="literal">public</code>. To allow
+ users to make use of the objects in a schema, additional privileges might
+ need to be granted, as appropriate for the object.
+ </p><p>
+ A user can also be allowed to create objects in someone else's schema. To
+ allow that, the <code class="literal">CREATE</code> privilege on the schema needs to
+ be granted. In databases upgraded from
+ <span class="productname">PostgreSQL</span> 14 or earlier, everyone has that
+ privilege on the schema <code class="literal">public</code>.
+ Some <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">usage patterns</a> call for
+ revoking that privilege:
+</p><pre class="programlisting">
+REVOKE CREATE ON SCHEMA public FROM PUBLIC;
+</pre><p>
+ (The first <span class="quote">“<span class="quote">public</span>”</span> is the schema, the second
+ <span class="quote">“<span class="quote">public</span>”</span> means <span class="quote">“<span class="quote">every user</span>”</span>. 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 <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS" title="4.1.1. Identifiers and Key Words">Section 4.1.1</a>.)
+ </p></div><div class="sect2" id="DDL-SCHEMAS-CATALOG"><div class="titlepage"><div><div><h3 class="title">5.9.5. The System Catalog Schema</h3></div></div></div><a id="id-1.5.4.11.11.2" class="indexterm"></a><p>
+ In addition to <code class="literal">public</code> and user-created schemas, each
+ database contains a <code class="literal">pg_catalog</code> schema, which contains
+ the system tables and all the built-in data types, functions, and
+ operators. <code class="literal">pg_catalog</code> is always effectively part of
+ the search path. If it is not named explicitly in the path then
+ it is implicitly searched <span class="emphasis"><em>before</em></span> searching the path's
+ schemas. This ensures that built-in names will always be
+ findable. However, you can explicitly place
+ <code class="literal">pg_catalog</code> at the end of your search path if you
+ prefer to have user-defined names override built-in names.
+ </p><p>
+ Since system table names begin with <code class="literal">pg_</code>, it is best to
+ avoid such names to ensure that you won't suffer a conflict if some
+ future version defines a system table named the same as your
+ table. (With the default search path, an unqualified reference to
+ your table name would then be resolved as the system table instead.)
+ System tables will continue to follow the convention of having
+ names beginning with <code class="literal">pg_</code>, so that they will not
+ conflict with unqualified user-table names so long as users avoid
+ the <code class="literal">pg_</code> prefix.
+ </p></div><div class="sect2" id="DDL-SCHEMAS-PATTERNS"><div class="titlepage"><div><div><h3 class="title">5.9.6. Usage Patterns</h3></div></div></div><p>
+ Schemas can be used to organize your data in many ways.
+ A <em class="firstterm">secure schema usage pattern</em> prevents untrusted
+ users from changing the behavior of other users' queries. When a database
+ does not use a secure schema usage pattern, users wishing to securely
+ query that database would take protective action at the beginning of each
+ session. Specifically, they would begin each session by
+ setting <code class="varname">search_path</code> to the empty string or otherwise
+ removing schemas that are writable by non-superusers
+ from <code class="varname">search_path</code>. There are a few usage patterns
+ easily supported by the default configuration:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Constrain ordinary users to user-private schemas.
+ To implement this pattern, first ensure that no schemas have
+ public <code class="literal">CREATE</code> privileges. Then, for every user
+ needing to create non-temporary objects, create a schema with the
+ same name as that user, for example
+ <code class="literal">CREATE SCHEMA alice AUTHORIZATION alice</code>.
+ (Recall that the default search path starts
+ with <code class="literal">$user</code>, which resolves to the user
+ name. Therefore, if each user has a separate schema, they access
+ their own schemas by default.) This pattern is a secure schema
+ usage pattern unless an untrusted user is the database owner or
+ holds the <code class="literal">CREATEROLE</code> privilege, in which case no
+ secure schema usage pattern exists.
+ </p><p>
+ In <span class="productname">PostgreSQL</span> 15 and later, the default
+ configuration supports this usage pattern. In prior versions, or
+ when using a database that has been upgraded from a prior version,
+ you will need to remove the public <code class="literal">CREATE</code>
+ privilege from the <code class="literal">public</code> schema (issue
+ <code class="literal">REVOKE CREATE ON SCHEMA public FROM PUBLIC</code>).
+ Then consider auditing the <code class="literal">public</code> schema for
+ objects named like objects in schema <code class="literal">pg_catalog</code>.
+ </p></li><li class="listitem"><p>
+ Remove the public schema from the default search path, by modifying
+ <a class="link" href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE" title="20.1.2. Parameter Interaction via the Configuration File"><code class="filename">postgresql.conf</code></a>
+ or by issuing <code class="literal">ALTER ROLE ALL SET search_path =
+ "$user"</code>. Then, grant privileges to create in the public
+ schema. Only qualified names will choose public schema objects. While
+ qualified table references are fine, calls to functions in the public
+ schema <a class="link" href="typeconv-func.html" title="10.3. Functions">will be unsafe or
+ unreliable</a>. If you create functions or extensions in the public
+ schema, use the first pattern instead. Otherwise, like the first
+ pattern, this is secure unless an untrusted user is the database owner
+ or holds the <code class="literal">CREATEROLE</code> privilege.
+ </p></li><li class="listitem"><p>
+ Keep the default search path, and grant privileges to create in the
+ public schema. All users access the public schema implicitly. This
+ simulates the situation where schemas are not available at all, giving
+ a smooth transition from the non-schema-aware world. However, this is
+ never a secure pattern. It is acceptable only when the database has a
+ single user or a few mutually-trusting users. In databases upgraded
+ from <span class="productname">PostgreSQL</span> 14 or earlier, this is the
+ default.
+ </p></li></ul></div><p>
+ </p><p>
+ For any pattern, to install shared applications (tables to be used by
+ everyone, additional functions provided by third parties, etc.), put them
+ into separate schemas. Remember to grant appropriate privileges to allow
+ the other users to access them. Users can then refer to these additional
+ objects by qualifying the names with a schema name, or they can put the
+ additional schemas into their search path, as they choose.
+ </p></div><div class="sect2" id="DDL-SCHEMAS-PORTABILITY"><div class="titlepage"><div><div><h3 class="title">5.9.7. Portability</h3></div></div></div><p>
+ In the SQL standard, the notion of objects in the same schema
+ being owned by different users does not exist. Moreover, some
+ implementations do not allow you to create schemas that have a
+ different name than their owner. In fact, the concepts of schema
+ and user are nearly equivalent in a database system that
+ implements only the basic schema support specified in the
+ standard. Therefore, many users consider qualified names to
+ really consist of
+ <code class="literal"><em class="replaceable"><code>user_name</code></em>.<em class="replaceable"><code>table_name</code></em></code>.
+ This is how <span class="productname">PostgreSQL</span> will effectively
+ behave if you create a per-user schema for every user.
+ </p><p>
+ Also, there is no concept of a <code class="literal">public</code> schema in the
+ SQL standard. For maximum conformance to the standard, you should
+ not use the <code class="literal">public</code> schema.
+ </p><p>
+ Of course, some SQL database systems might not implement schemas
+ at all, or provide namespace support by allowing (possibly
+ limited) cross-database access. If you need to work with those
+ systems, then maximum portability would be achieved by not using
+ schemas at all.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-inherit.html" title="5.10. Inheritance">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.8. Row Security Policies </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.10. Inheritance</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl-system-columns.html b/doc/src/sgml/html/ddl-system-columns.html
new file mode 100644
index 0000000..ab773d3
--- /dev/null
+++ b/doc/src/sgml/html/ddl-system-columns.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5.5. System Columns</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-constraints.html" title="5.4. Constraints" /><link rel="next" href="ddl-alter.html" title="5.6. Modifying Tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5.5. System Columns</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-constraints.html" title="5.4. Constraints">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><th width="60%" align="center">Chapter 5. Data Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-alter.html" title="5.6. Modifying Tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="DDL-SYSTEM-COLUMNS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.5. System Columns</h2></div></div></div><p>
+ Every table has several <em class="firstterm">system columns</em> that are
+ implicitly defined by the system. Therefore, these names cannot be
+ used as names of user-defined columns. (Note that these
+ restrictions are separate from whether the name is a key word or
+ not; quoting a name will not allow you to escape these
+ restrictions.) You do not really need to be concerned about these
+ columns; just know they exist.
+ </p><a id="id-1.5.4.7.3" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="structfield">tableoid</code></span></dt><dd><a id="id-1.5.4.7.4.1.2.1" class="indexterm"></a><p>
+ The OID of the table containing this row. This column is
+ particularly handy for queries that select from partitioned
+ tables (see <a class="xref" href="ddl-partitioning.html" title="5.11. Table Partitioning">Section 5.11</a>) or inheritance
+ hierarchies (see <a class="xref" href="ddl-inherit.html" title="5.10. Inheritance">Section 5.10</a>), since without it,
+ it's difficult to tell which individual table a row came from. The
+ <code class="structfield">tableoid</code> can be joined against the
+ <code class="structfield">oid</code> column of
+ <code class="structname">pg_class</code> to obtain the table name.
+ </p></dd><dt><span class="term"><code class="structfield">xmin</code></span></dt><dd><a id="id-1.5.4.7.4.2.2.1" class="indexterm"></a><p>
+ The identity (transaction ID) of the inserting transaction for
+ this row version. (A row version is an individual state of a
+ row; each update of a row creates a new row version for the same
+ logical row.)
+ </p></dd><dt><span class="term"><code class="structfield">cmin</code></span></dt><dd><a id="id-1.5.4.7.4.3.2.1" class="indexterm"></a><p>
+ The command identifier (starting at zero) within the inserting
+ transaction.
+ </p></dd><dt><span class="term"><code class="structfield">xmax</code></span></dt><dd><a id="id-1.5.4.7.4.4.2.1" class="indexterm"></a><p>
+ The identity (transaction ID) of the deleting transaction, or
+ zero for an undeleted row version. It is possible for this column to
+ be nonzero in a visible row version. That usually indicates that the
+ deleting transaction hasn't committed yet, or that an attempted
+ deletion was rolled back.
+ </p></dd><dt><span class="term"><code class="structfield">cmax</code></span></dt><dd><a id="id-1.5.4.7.4.5.2.1" class="indexterm"></a><p>
+ The command identifier within the deleting transaction, or zero.
+ </p></dd><dt><span class="term"><code class="structfield">ctid</code></span></dt><dd><a id="id-1.5.4.7.4.6.2.1" class="indexterm"></a><p>
+ The physical location of the row version within its table. Note that
+ although the <code class="structfield">ctid</code> can be used to
+ locate the row version very quickly, a row's
+ <code class="structfield">ctid</code> will change if it is
+ updated or moved by <code class="command">VACUUM FULL</code>. Therefore
+ <code class="structfield">ctid</code> is useless as a long-term row
+ identifier. A primary key should be used to identify logical rows.
+ </p></dd></dl></div><p>
+ 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 <a class="xref" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Chapter 25</a> for details. It is
+ unwise, however, to depend on the uniqueness of transaction IDs
+ over the long term (more than one billion transactions).
+ </p><p>
+ Command identifiers are also 32-bit quantities. This creates a hard limit
+ of 2<sup>32</sup> (4 billion) <acronym class="acronym">SQL</acronym> commands
+ within a single transaction. In practice this limit is not a
+ problem — note that the limit is on the number of
+ <acronym class="acronym">SQL</acronym> commands, not the number of rows processed.
+ Also, only commands that actually modify the database contents will
+ consume a command identifier.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-constraints.html" title="5.4. Constraints">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ddl.html" title="Chapter 5. Data Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-alter.html" title="5.6. Modifying Tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.4. Constraints </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.6. Modifying Tables</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ddl.html b/doc/src/sgml/html/ddl.html
new file mode 100644
index 0000000..14ec801
--- /dev/null
+++ b/doc/src/sgml/html/ddl.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Data Definition</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions" /><link rel="next" href="ddl-basics.html" title="5.1. Table Basics" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 5. Data Definition</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl-basics.html" title="5.1. Table Basics">Next</a></td></tr></table><hr /></div><div class="chapter" id="DDL"><div class="titlepage"><div><div><h2 class="title">Chapter 5. Data Definition</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="ddl-basics.html">5.1. Table Basics</a></span></dt><dt><span class="sect1"><a href="ddl-default.html">5.2. Default Values</a></span></dt><dt><span class="sect1"><a href="ddl-generated-columns.html">5.3. Generated Columns</a></span></dt><dt><span class="sect1"><a href="ddl-constraints.html">5.4. Constraints</a></span></dt><dd><dl><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS">5.4.1. Check Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#id-1.5.4.6.6">5.4.2. Not-Null Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-UNIQUE-CONSTRAINTS">5.4.3. Unique Constraints</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-PRIMARY-KEYS">5.4.4. Primary Keys</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-FK">5.4.5. Foreign Keys</a></span></dt><dt><span class="sect2"><a href="ddl-constraints.html#DDL-CONSTRAINTS-EXCLUSION">5.4.6. Exclusion Constraints</a></span></dt></dl></dd><dt><span class="sect1"><a href="ddl-system-columns.html">5.5. System Columns</a></span></dt><dt><span class="sect1"><a href="ddl-alter.html">5.6. Modifying Tables</a></span></dt><dd><dl><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-ADDING-A-COLUMN">5.6.1. Adding a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-REMOVING-A-COLUMN">5.6.2. Removing a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-ADDING-A-CONSTRAINT">5.6.3. Adding a Constraint</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#DDL-ALTER-REMOVING-A-CONSTRAINT">5.6.4. Removing a Constraint</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.9">5.6.5. Changing a Column's Default Value</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.10">5.6.6. Changing a Column's Data Type</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.11">5.6.7. Renaming a Column</a></span></dt><dt><span class="sect2"><a href="ddl-alter.html#id-1.5.4.8.12">5.6.8. Renaming a Table</a></span></dt></dl></dd><dt><span class="sect1"><a href="ddl-priv.html">5.7. Privileges</a></span></dt><dt><span class="sect1"><a href="ddl-rowsecurity.html">5.8. Row Security Policies</a></span></dt><dt><span class="sect1"><a href="ddl-schemas.html">5.9. Schemas</a></span></dt><dd><dl><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-CREATE">5.9.1. Creating a Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PUBLIC">5.9.2. The Public Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PATH">5.9.3. The Schema Search Path</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PRIV">5.9.4. Schemas and Privileges</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-CATALOG">5.9.5. The System Catalog Schema</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS">5.9.6. Usage Patterns</a></span></dt><dt><span class="sect2"><a href="ddl-schemas.html#DDL-SCHEMAS-PORTABILITY">5.9.7. Portability</a></span></dt></dl></dd><dt><span class="sect1"><a href="ddl-inherit.html">5.10. Inheritance</a></span></dt><dd><dl><dt><span class="sect2"><a href="ddl-inherit.html#DDL-INHERIT-CAVEATS">5.10.1. Caveats</a></span></dt></dl></dd><dt><span class="sect1"><a href="ddl-partitioning.html">5.11. Table Partitioning</a></span></dt><dd><dl><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-OVERVIEW">5.11.1. Overview</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE">5.11.2. Declarative Partitioning</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-USING-INHERITANCE">5.11.3. Partitioning Using Inheritance</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITION-PRUNING">5.11.4. Partition Pruning</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION">5.11.5. Partitioning and Constraint Exclusion</a></span></dt><dt><span class="sect2"><a href="ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-BEST-PRACTICES">5.11.6. Best Practices for Declarative Partitioning</a></span></dt></dl></dd><dt><span class="sect1"><a href="ddl-foreign-data.html">5.12. Foreign Data</a></span></dt><dt><span class="sect1"><a href="ddl-others.html">5.13. Other Database Objects</a></span></dt><dt><span class="sect1"><a href="ddl-depend.html">5.14. Dependency Tracking</a></span></dt></dl></div><p>
+ This chapter covers how one creates the database structures that
+ will hold one's data. In a relational database, the raw data is
+ stored in tables, so the majority of this chapter is devoted to
+ explaining how tables are created and modified and what features are
+ available to control what data is stored in the tables.
+ Subsequently, we discuss how tables can be organized into
+ schemas, and how privileges can be assigned to tables. Finally,
+ we will briefly look at other features that affect the data storage,
+ such as inheritance, table partitioning, views, functions, and
+ triggers.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl-basics.html" title="5.1. Table Basics">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3. Calling Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5.1. Table Basics</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/default-roles.html b/doc/src/sgml/html/default-roles.html
new file mode 100644
index 0000000..03ff13e
--- /dev/null
+++ b/doc/src/sgml/html/default-roles.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>O.2. Default Roles Renamed to Predefined Roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf" /><link rel="next" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">O.2. Default Roles Renamed to Predefined Roles</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><th width="60%" align="center">Appendix O. Obsolete or Renamed Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump">Next</a></td></tr></table><hr /></div><div class="sect1" id="DEFAULT-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">O.2. Default Roles Renamed to Predefined Roles</h2></div></div></div><a id="id-1.11.16.4.2" class="indexterm"></a><p>
+ PostgreSQL 13 and below used the term <span class="quote">“<span class="quote">Default Roles</span>”</span>. However, as these
+ roles are not able to actually be changed and are installed as part of the
+ system at initialization time, the more appropriate term to use is <span class="quote">“<span class="quote">Predefined Roles</span>”</span>.
+ See <a class="xref" href="predefined-roles.html" title="22.5. Predefined Roles">Section 22.5</a> for current documentation regarding
+ Predefined Roles, and <a class="link" href="release-prior.html" title="E.7. Prior Releases">the release notes for
+ PostgreSQL 14</a> for details on this change.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="recovery-config.html" title="O.1. recovery.conf file merged into postgresql.conf">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgxlogdump.html" title="O.3. pg_xlogdump renamed to pg_waldump">Next</a></td></tr><tr><td width="40%" align="left" valign="top">O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dict-int.html b/doc/src/sgml/html/dict-int.html
new file mode 100644
index 0000000..0c14420
--- /dev/null
+++ b/doc/src/sgml/html/dict-int.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.13. dict_int</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update" /><link rel="next" href="dict-xsyn.html" title="F.14. dict_xsyn" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.13. dict_int</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dict-xsyn.html" title="F.14. dict_xsyn">Next</a></td></tr></table><hr /></div><div class="sect1" id="DICT-INT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.13. dict_int</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="dict-int.html#id-1.11.7.22.5">F.13.1. Configuration</a></span></dt><dt><span class="sect2"><a href="dict-int.html#id-1.11.7.22.6">F.13.2. Usage</a></span></dt></dl></div><a id="id-1.11.7.22.2" class="indexterm"></a><p>
+ <code class="filename">dict_int</code> is an example of an add-on dictionary template
+ for full-text search. The motivation for this example dictionary is to
+ control the indexing of integers (signed and unsigned), allowing such
+ numbers to be indexed while preventing excessive growth in the number of
+ unique words, which greatly affects the performance of searching.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.22.5"><div class="titlepage"><div><div><h3 class="title">F.13.1. Configuration</h3></div></div></div><p>
+ The dictionary accepts three options:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <code class="literal">maxlen</code> parameter specifies the maximum number of
+ digits allowed in an integer word. The default value is 6.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">rejectlong</code> parameter specifies whether an overlength
+ integer should be truncated or ignored. If <code class="literal">rejectlong</code> is
+ <code class="literal">false</code> (the default), the dictionary returns the first
+ <code class="literal">maxlen</code> digits of the integer. If <code class="literal">rejectlong</code> is
+ <code class="literal">true</code>, the dictionary treats an overlength integer as a stop
+ word, so that it will not be indexed. Note that this also means that
+ such an integer cannot be searched for.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">absval</code> parameter specifies whether leading
+ <span class="quote">“<span class="quote"><code class="literal">+</code></span>”</span> or <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span>
+ signs should be removed from integer words. The default
+ is <code class="literal">false</code>. When <code class="literal">true</code>, the sign is
+ removed before <code class="literal">maxlen</code> is applied.
+ </p></li></ul></div></div><div class="sect2" id="id-1.11.7.22.6"><div class="titlepage"><div><div><h3 class="title">F.13.2. Usage</h3></div></div></div><p>
+ Installing the <code class="literal">dict_int</code> extension creates a text search
+ template <code class="literal">intdict_template</code> and a dictionary <code class="literal">intdict</code>
+ based on it, with the default parameters. You can alter the
+ parameters, for example
+
+</p><pre class="programlisting">
+mydb# ALTER TEXT SEARCH DICTIONARY intdict (MAXLEN = 4, REJECTLONG = true);
+ALTER TEXT SEARCH DICTIONARY
+</pre><p>
+
+ or create new dictionaries based on the template.
+ </p><p>
+ To test the dictionary, you can try
+
+</p><pre class="programlisting">
+mydb# select ts_lexize('intdict', '12345678');
+ ts_lexize
+-----------
+ {123456}
+</pre><p>
+
+ but real-world usage will involve including it in a text search
+ configuration as described in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ That might look like this:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION english
+ ALTER MAPPING FOR int, uint WITH intdict;
+</pre><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-build-sql-update.html" title="dblink_build_sql_update">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dict-xsyn.html" title="F.14. dict_xsyn">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_build_sql_update </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.14. dict_xsyn</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dict-xsyn.html b/doc/src/sgml/html/dict-xsyn.html
new file mode 100644
index 0000000..a9c392a
--- /dev/null
+++ b/doc/src/sgml/html/dict-xsyn.html
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.14. dict_xsyn</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dict-int.html" title="F.13. dict_int" /><link rel="next" href="earthdistance.html" title="F.15. earthdistance" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.14. dict_xsyn</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dict-int.html" title="F.13. dict_int">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="earthdistance.html" title="F.15. earthdistance">Next</a></td></tr></table><hr /></div><div class="sect1" id="DICT-XSYN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.14. dict_xsyn</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="dict-xsyn.html#id-1.11.7.23.4">F.14.1. Configuration</a></span></dt><dt><span class="sect2"><a href="dict-xsyn.html#id-1.11.7.23.5">F.14.2. Usage</a></span></dt></dl></div><a id="id-1.11.7.23.2" class="indexterm"></a><p>
+ <code class="filename">dict_xsyn</code> (Extended Synonym Dictionary) is an example of an
+ add-on dictionary template for full-text search. This dictionary type
+ replaces words with groups of their synonyms, and so makes it possible to
+ search for a word using any of its synonyms.
+ </p><div class="sect2" id="id-1.11.7.23.4"><div class="titlepage"><div><div><h3 class="title">F.14.1. Configuration</h3></div></div></div><p>
+ A <code class="literal">dict_xsyn</code> dictionary accepts the following options:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">matchorig</code> controls whether the original word is accepted by
+ the dictionary. Default is <code class="literal">true</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">matchsynonyms</code> controls whether the synonyms are
+ accepted by the dictionary. Default is <code class="literal">false</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">keeporig</code> controls whether the original word is included in
+ the dictionary's output. Default is <code class="literal">true</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">keepsynonyms</code> controls whether the synonyms are included in
+ the dictionary's output. Default is <code class="literal">true</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">rules</code> is the base name of the file containing the list of
+ synonyms. This file must be stored in
+ <code class="filename">$SHAREDIR/tsearch_data/</code> (where <code class="literal">$SHAREDIR</code> means
+ the <span class="productname">PostgreSQL</span> installation's shared-data directory).
+ Its name must end in <code class="literal">.rules</code> (which is not to be included in
+ the <code class="literal">rules</code> parameter).
+ </p></li></ul></div><p>
+ The rules file has the following format:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Each line represents a group of synonyms for a single word, which is
+ given first on the line. Synonyms are separated by whitespace, thus:
+</p><pre class="programlisting">
+word syn1 syn2 syn3
+</pre><p>
+ </p></li><li class="listitem"><p>
+ The sharp (<code class="literal">#</code>) sign is a comment delimiter. It may appear at
+ any position in a line. The rest of the line will be skipped.
+ </p></li></ul></div><p>
+ Look at <code class="filename">xsyn_sample.rules</code>, which is installed in
+ <code class="filename">$SHAREDIR/tsearch_data/</code>, for an example.
+ </p></div><div class="sect2" id="id-1.11.7.23.5"><div class="titlepage"><div><div><h3 class="title">F.14.2. Usage</h3></div></div></div><p>
+ Installing the <code class="literal">dict_xsyn</code> extension creates a text search
+ template <code class="literal">xsyn_template</code> and a dictionary <code class="literal">xsyn</code>
+ based on it, with default parameters. You can alter the
+ parameters, for example
+
+</p><pre class="programlisting">
+mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
+ALTER TEXT SEARCH DICTIONARY
+</pre><p>
+
+ or create new dictionaries based on the template.
+ </p><p>
+ To test the dictionary, you can try
+
+</p><pre class="programlisting">
+mydb=# SELECT ts_lexize('xsyn', 'word');
+ ts_lexize
+-----------------------
+ {syn1,syn2,syn3}
+
+mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true);
+ALTER TEXT SEARCH DICTIONARY
+
+mydb=# SELECT ts_lexize('xsyn', 'word');
+ ts_lexize
+-----------------------
+ {word,syn1,syn2,syn3}
+
+mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true);
+ALTER TEXT SEARCH DICTIONARY
+
+mydb=# SELECT ts_lexize('xsyn', 'syn1');
+ ts_lexize
+-----------------------
+ {syn1,syn2,syn3}
+
+mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false);
+ALTER TEXT SEARCH DICTIONARY
+
+mydb=# SELECT ts_lexize('xsyn', 'syn1');
+ ts_lexize
+-----------------------
+ {word}
+</pre><p>
+
+ Real-world usage will involve including it in a text search
+ configuration as described in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ That might look like this:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION english
+ ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
+</pre><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dict-int.html" title="F.13. dict_int">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="earthdistance.html" title="F.15. earthdistance">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.13. dict_int </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.15. earthdistance</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/different-replication-solutions.html b/doc/src/sgml/html/different-replication-solutions.html
new file mode 100644
index 0000000..4919117
--- /dev/null
+++ b/doc/src/sgml/html/different-replication-solutions.html
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>27.1. Comparison of Different Solutions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication" /><link rel="next" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">27.1. Comparison of Different Solutions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><th width="60%" align="center">Chapter 27. High Availability, Load Balancing, and Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Next</a></td></tr></table><hr /></div><div class="sect1" id="DIFFERENT-REPLICATION-SOLUTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">27.1. Comparison of Different Solutions</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Shared Disk Failover</span></dt><dd><p>
+ Shared disk failover avoids synchronization overhead by having only one
+ copy of the database. It uses a single disk array that is shared by
+ multiple servers. If the main database server fails, the standby server
+ is able to mount and start the database as though it were recovering from
+ a database crash. This allows rapid failover with no data loss.
+ </p><p>
+ 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 <acronym class="acronym">POSIX</acronym> behavior (see <a class="xref" href="creating-cluster.html#CREATING-CLUSTER-NFS" title="19.2.2.1. NFS">Section 19.2.2.1</a>). 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
+ the primary server is running.
+ </p></dd><dt><span class="term">File System (Block Device) Replication</span></dt><dd><p>
+ A modified version of shared hardware functionality is file system
+ replication, where all changes to a file system are mirrored to a file
+ system residing on another computer. The only restriction is that
+ the mirroring must be done in a way that ensures the standby server
+ has a consistent copy of the file system — specifically, writes
+ to the standby must be done in the same order as those on the primary.
+ <span class="productname">DRBD</span> is a popular file system replication solution
+ for Linux.
+ </p></dd><dt><span class="term">Write-Ahead Log Shipping</span></dt><dd><p>
+ Warm and hot standby servers can be kept current by reading a
+ stream of write-ahead log (<acronym class="acronym">WAL</acronym>)
+ records. If the main server fails, the standby contains
+ almost all of the data of the main server, and can be quickly
+ made the new primary database server. This can be synchronous or
+ asynchronous and can only be done for the entire database server.
+ </p><p>
+ A standby server can be implemented using file-based log shipping
+ (<a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>) or streaming replication (see
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>), or a combination of both. For
+ information on hot standby, see <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a>.
+ </p></dd><dt><span class="term">Logical Replication</span></dt><dd><p>
+ Logical replication allows a database server to send a stream of data
+ modifications to another server. <span class="productname">PostgreSQL</span>
+ logical replication constructs a stream of logical data modifications
+ from the WAL. Logical replication allows replication of data changes on
+ a per-table basis. In addition, a server that is publishing its own
+ changes can also subscribe to changes from another server, allowing data
+ to flow in multiple directions. For more information on logical
+ replication, see <a class="xref" href="logical-replication.html" title="Chapter 31. Logical Replication">Chapter 31</a>. Through the
+ logical decoding interface (<a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>),
+ third-party extensions can also provide similar functionality.
+ </p></dd><dt><span class="term">Trigger-Based Primary-Standby Replication</span></dt><dd><p>
+ A trigger-based replication setup typically funnels data modification
+ queries to a designated primary server. Operating on a per-table basis,
+ the primary server sends data changes (typically) asynchronously to the
+ standby servers. Standby servers can answer queries while the primary is
+ running, and may allow some local data changes or write activity. This
+ form of replication is often used for offloading large analytical or data
+ warehouse queries.
+ </p><p>
+ <span class="productname">Slony-I</span> is an example of this type of
+ replication, with per-table granularity, and support for multiple standby
+ servers. Because it updates the standby server asynchronously (in
+ batches), there is possible data loss during fail over.
+ </p></dd><dt><span class="term">SQL-Based Replication Middleware</span></dt><dd><p>
+ With SQL-based replication middleware, a program intercepts
+ every SQL query and sends it to one or all servers. Each server
+ operates independently. Read-write queries must be sent to all servers,
+ so that every server receives any changes. But read-only queries can be
+ sent to just one server, allowing the read workload to be distributed
+ among them.
+ </p><p>
+ If queries are simply broadcast unmodified, functions like
+ <code class="function">random()</code>, <code class="function">CURRENT_TIMESTAMP</code>, and
+ sequences can have different values on different servers.
+ This is because each server operates independently, and because
+ SQL queries are broadcast rather than actual data changes. If
+ this is unacceptable, either the middleware or the application
+ must determine such values from a single source and then use those
+ values in write queries. Care must also be taken that all
+ transactions either commit or abort on all servers, perhaps
+ using two-phase commit (<a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>
+ and <a class="xref" href="sql-commit-prepared.html" title="COMMIT PREPARED"><span class="refentrytitle">COMMIT PREPARED</span></a>).
+ <span class="productname">Pgpool-II</span> and <span class="productname">Continuent Tungsten</span>
+ are examples of this type of replication.
+ </p></dd><dt><span class="term">Asynchronous Multimaster Replication</span></dt><dd><p>
+ For servers that are not regularly connected or have slow
+ communication links, like laptops or
+ remote servers, keeping data consistent among servers is a
+ challenge. Using asynchronous multimaster replication, each
+ server works independently, and periodically communicates with
+ the other servers to identify conflicting transactions. The
+ conflicts can be resolved by users or conflict resolution rules.
+ Bucardo is an example of this type of replication.
+ </p></dd><dt><span class="term">Synchronous Multimaster Replication</span></dt><dd><p>
+ In synchronous multimaster replication, each server can accept
+ write requests, and modified data is transmitted from the
+ original server to every other server before each transaction
+ commits. Heavy write activity can cause excessive locking and
+ commit delays, leading to poor performance. Read requests can
+ be sent to any server. Some implementations use shared disk
+ to reduce the communication overhead. Synchronous multimaster
+ replication is best for mostly read workloads, though its big
+ advantage is that any server can accept write requests —
+ there is no need to partition workloads between primary and
+ standby servers, and because the data changes are sent from one
+ server to another, there is no problem with non-deterministic
+ functions like <code class="function">random()</code>.
+ </p><p>
+ <span class="productname">PostgreSQL</span> does not offer this type of replication,
+ though <span class="productname">PostgreSQL</span> two-phase commit (<a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a> and <a class="xref" href="sql-commit-prepared.html" title="COMMIT PREPARED"><span class="refentrytitle">COMMIT PREPARED</span></a>)
+ can be used to implement this in application code or middleware.
+ </p></dd></dl></div><p>
+ <a class="xref" href="different-replication-solutions.html#HIGH-AVAILABILITY-MATRIX" title="Table 27.1. High Availability, Load Balancing, and Replication Feature Matrix">Table 27.1</a> summarizes
+ the capabilities of the various solutions listed above.
+ </p><div class="table" id="HIGH-AVAILABILITY-MATRIX"><p class="title"><strong>Table 27.1. High Availability, Load Balancing, and Replication Feature Matrix</strong></p><div class="table-contents"><table class="table" summary="High Availability, Load Balancing, and Replication Feature Matrix" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /><col class="col6" /><col class="col7" /><col class="col8" /><col class="col9" /></colgroup><thead><tr><th>Feature</th><th>Shared Disk</th><th>File System Repl.</th><th>Write-Ahead Log Shipping</th><th>Logical Repl.</th><th>Trigger-​Based Repl.</th><th>SQL Repl. Middle-ware</th><th>Async. MM Repl.</th><th>Sync. MM Repl.</th></tr></thead><tbody><tr><td>Popular examples</td><td align="center">NAS</td><td align="center">DRBD</td><td align="center">built-in streaming repl.</td><td align="center">built-in logical repl., pglogical</td><td align="center">Londiste, Slony</td><td align="center">pgpool-II</td><td align="center">Bucardo</td><td align="center"> </td></tr><tr><td>Comm. method</td><td align="center">shared disk</td><td align="center">disk blocks</td><td align="center">WAL</td><td align="center">logical decoding</td><td align="center">table rows</td><td align="center">SQL</td><td align="center">table rows</td><td align="center">table rows and row locks</td></tr><tr><td>No special hardware required</td><td align="center"> </td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td></tr><tr><td>Allows multiple primary servers</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center">•</td><td align="center">•</td></tr><tr><td>No overhead on primary</td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center"> </td><td align="center"> </td></tr><tr><td>No waiting for multiple servers</td><td align="center">•</td><td align="center"> </td><td align="center">with sync off</td><td align="center">with sync off</td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center"> </td></tr><tr><td>Primary failure will never lose data</td><td align="center">•</td><td align="center">•</td><td align="center">with sync on</td><td align="center">with sync on</td><td align="center"> </td><td align="center">•</td><td align="center"> </td><td align="center">•</td></tr><tr><td>Replicas accept read-only queries</td><td align="center"> </td><td align="center"> </td><td align="center">with hot standby</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td></tr><tr><td>Per-table granularity</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center">•</td></tr><tr><td>No conflict resolution necessary</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center">•</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ There are a few solutions that do not fit into the above categories:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Data Partitioning</span></dt><dd><p>
+ Data partitioning splits tables into data sets. Each set can
+ be modified by only one server. For example, data can be
+ partitioned by offices, e.g., London and Paris, with a server
+ in each office. If queries combining London and Paris data
+ are necessary, an application can query both servers, or
+ primary/standby replication can be used to keep a read-only copy
+ of the other office's data on each server.
+ </p></dd><dt><span class="term">Multiple-Server Parallel Query Execution</span></dt><dd><p>
+ Many of the above solutions allow multiple servers to handle multiple
+ queries, but none allow a single query to use multiple servers to
+ complete faster. This solution allows multiple servers to work
+ concurrently on a single query. It is usually accomplished by
+ splitting the data among servers and having each server execute its
+ part of the query and return results to a central server where they
+ are combined and returned to the user. This can be implemented using the
+ <span class="productname">PL/Proxy</span> tool set.
+ </p></dd></dl></div><p>
+ It should also be noted that because <span class="productname">PostgreSQL</span>
+ is open source and easily extended, a number of companies have
+ taken <span class="productname">PostgreSQL</span> and created commercial
+ closed-source solutions with unique failover, replication, and load
+ balancing capabilities. These are not discussed here.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 27. High Availability, Load Balancing, and Replication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 27.2. Log-Shipping Standby Servers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/disk-full.html b/doc/src/sgml/html/disk-full.html
new file mode 100644
index 0000000..ded5362
--- /dev/null
+++ b/doc/src/sgml/html/disk-full.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>29.2. Disk Full Failure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="disk-usage.html" title="29.1. Determining Disk Usage" /><link rel="next" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">29.2. Disk Full Failure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="disk-usage.html" title="29.1. Determining Disk Usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Up</a></td><th width="60%" align="center">Chapter 29. Monitoring Disk Usage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Next</a></td></tr></table><hr /></div><div class="sect1" id="DISK-FULL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">29.2. Disk Full Failure</h2></div></div></div><p>
+ The most important disk monitoring task of a database administrator
+ is to make sure the disk doesn't become full. A filled data disk will
+ not result in data corruption, but it might prevent useful activity
+ from occurring. If the disk holding the WAL files grows full, database
+ server panic and consequent shutdown might occur.
+ </p><p>
+ 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 <a class="xref" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Section 23.6</a> for more information about that.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Some file systems perform badly when they are almost full, so do
+ not wait until the disk is completely full to take action.
+ </p></div><p>
+ If your system supports per-user disk quotas, then the database
+ will naturally be subject to whatever quota is placed on the user
+ the server runs as. Exceeding the quota will have the same bad
+ effects as running out of disk space entirely.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="disk-usage.html" title="29.1. Determining Disk Usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Next</a></td></tr><tr><td width="40%" align="left" valign="top">29.1. Determining Disk Usage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 30. Reliability and the Write-Ahead Log</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/disk-usage.html b/doc/src/sgml/html/disk-usage.html
new file mode 100644
index 0000000..3646fe6
--- /dev/null
+++ b/doc/src/sgml/html/disk-usage.html
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>29.1. Determining Disk Usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage" /><link rel="next" href="disk-full.html" title="29.2. Disk Full Failure" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">29.1. Determining Disk Usage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Up</a></td><th width="60%" align="center">Chapter 29. Monitoring Disk Usage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="disk-full.html" title="29.2. Disk Full Failure">Next</a></td></tr></table><hr /></div><div class="sect1" id="DISK-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">29.1. Determining Disk Usage</h2></div></div></div><a id="id-1.6.16.3.2" class="indexterm"></a><p>
+ Each table has a primary heap disk file where most of the data is
+ stored. If the table has any columns with potentially-wide values,
+ there also might be a <acronym class="acronym">TOAST</acronym> file associated with the table,
+ which is used to store values too wide to fit comfortably in the main
+ table (see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>). There will be one valid index
+ on the <acronym class="acronym">TOAST</acronym> 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 <a class="xref" href="storage-file-layout.html" title="73.1. Database File Layout">Section 73.1</a>.
+ </p><p>
+ You can monitor disk space in three ways:
+ using the SQL functions listed in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-DBSIZE" title="Table 9.94. Database Object Size Functions">Table 9.94</a>,
+ using the <a class="xref" href="oid2name.html" title="oid2name"><span class="refentrytitle">oid2name</span></a> 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
+ system catalogs.
+ </p><p>
+ Using <span class="application">psql</span> on a recently vacuumed or analyzed database,
+ you can issue queries to see the disk usage of any table:
+</p><pre class="programlisting">
+SELECT pg_relation_filepath(oid), relpages FROM pg_class WHERE relname = 'customer';
+
+ pg_relation_filepath | relpages
+----------------------+----------
+ base/16384/16806 | 60
+(1 row)
+</pre><p>
+ Each page is typically 8 kilobytes. (Remember, <code class="structfield">relpages</code>
+ is only updated by <code class="command">VACUUM</code>, <code class="command">ANALYZE</code>, and
+ a few DDL commands such as <code class="command">CREATE INDEX</code>.) The file path name
+ is of interest if you want to examine the table's disk file directly.
+ </p><p>
+ To show the space used by <acronym class="acronym">TOAST</acronym> tables, use a query
+ like the following:
+</p><pre class="programlisting">
+SELECT relname, relpages
+FROM pg_class,
+ (SELECT reltoastrelid
+ FROM pg_class
+ WHERE relname = 'customer') AS ss
+WHERE oid = ss.reltoastrelid OR
+ oid = (SELECT indexrelid
+ FROM pg_index
+ WHERE indrelid = ss.reltoastrelid)
+ORDER BY relname;
+
+ relname | relpages
+----------------------+----------
+ pg_toast_16806 | 0
+ pg_toast_16806_index | 1
+</pre><p>
+ </p><p>
+ You can easily display index sizes, too:
+</p><pre class="programlisting">
+SELECT c2.relname, c2.relpages
+FROM pg_class c, pg_class c2, pg_index i
+WHERE c.relname = 'customer' AND
+ c.oid = i.indrelid AND
+ c2.oid = i.indexrelid
+ORDER BY c2.relname;
+
+ relname | relpages
+-------------------+----------
+ customer_id_index | 26
+</pre><p>
+ </p><p>
+ It is easy to find your largest tables and indexes using this
+ information:
+</p><pre class="programlisting">
+SELECT relname, relpages
+FROM pg_class
+ORDER BY relpages DESC;
+
+ relname | relpages
+----------------------+----------
+ bigtable | 3290
+ customer | 3144
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="disk-full.html" title="29.2. Disk Full Failure">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 29. Monitoring Disk Usage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 29.2. Disk Full Failure</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/diskusage.html b/doc/src/sgml/html/diskusage.html
new file mode 100644
index 0000000..4668950
--- /dev/null
+++ b/doc/src/sgml/html/diskusage.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 29. Monitoring Disk Usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dynamic-trace.html" title="28.5. Dynamic Tracing" /><link rel="next" href="disk-usage.html" title="29.1. Determining Disk Usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 29. Monitoring Disk Usage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="disk-usage.html" title="29.1. Determining Disk Usage">Next</a></td></tr></table><hr /></div><div class="chapter" id="DISKUSAGE"><div class="titlepage"><div><div><h2 class="title">Chapter 29. Monitoring Disk Usage</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="disk-usage.html">29.1. Determining Disk Usage</a></span></dt><dt><span class="sect1"><a href="disk-full.html">29.2. Disk Full Failure</a></span></dt></dl></div><p>
+ This chapter discusses how to monitor the disk usage of a
+ <span class="productname">PostgreSQL</span> database system.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="disk-usage.html" title="29.1. Determining Disk Usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.5. Dynamic Tracing </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 29.1. Determining Disk Usage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dml-delete.html b/doc/src/sgml/html/dml-delete.html
new file mode 100644
index 0000000..69c651c
--- /dev/null
+++ b/doc/src/sgml/html/dml-delete.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>6.3. Deleting Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dml-update.html" title="6.2. Updating Data" /><link rel="next" href="dml-returning.html" title="6.4. Returning Data from Modified Rows" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">6.3. Deleting Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml-update.html" title="6.2. Updating Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><th width="60%" align="center">Chapter 6. Data Manipulation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dml-returning.html" title="6.4. Returning Data from Modified Rows">Next</a></td></tr></table><hr /></div><div class="sect1" id="DML-DELETE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">6.3. Deleting Data</h2></div></div></div><a id="id-1.5.5.5.2" class="indexterm"></a><a id="id-1.5.5.5.3" class="indexterm"></a><p>
+ So far we have explained how to add data to tables and how to
+ change data. What remains is to discuss how to remove data that is
+ no longer needed. Just as adding data is only possible in whole
+ rows, you can only remove entire rows from a table. In the
+ previous section we explained that SQL does not provide a way to
+ directly address individual rows. Therefore, removing rows can
+ only be done by specifying conditions that the rows to be removed
+ have to match. If you have a primary key in the table then you can
+ specify the exact row. But you can also remove groups of rows
+ matching a condition, or you can remove all rows in the table at
+ once.
+ </p><p>
+ You use the <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a>
+ command to remove rows; the syntax is very similar to the
+ <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a> command. For instance, to remove all
+ rows from the products table that have a price of 10, use:
+</p><pre class="programlisting">
+DELETE FROM products WHERE price = 10;
+</pre><p>
+ </p><p>
+ If you simply write:
+</p><pre class="programlisting">
+DELETE FROM products;
+</pre><p>
+ then all rows in the table will be deleted! Caveat programmer.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml-update.html" title="6.2. Updating Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dml-returning.html" title="6.4. Returning Data from Modified Rows">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.2. Updating Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 6.4. Returning Data from Modified Rows</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dml-insert.html b/doc/src/sgml/html/dml-insert.html
new file mode 100644
index 0000000..6b24930
--- /dev/null
+++ b/doc/src/sgml/html/dml-insert.html
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>6.1. Inserting Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dml.html" title="Chapter 6. Data Manipulation" /><link rel="next" href="dml-update.html" title="6.2. Updating Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">6.1. Inserting Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml.html" title="Chapter 6. Data Manipulation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><th width="60%" align="center">Chapter 6. Data Manipulation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dml-update.html" title="6.2. Updating Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="DML-INSERT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">6.1. Inserting Data</h2></div></div></div><a id="id-1.5.5.3.2" class="indexterm"></a><a id="id-1.5.5.3.3" class="indexterm"></a><p>
+ When a table is created, it contains no data. The first thing to
+ do before a database can be of much use is to insert data. Data is
+ inserted one row at a time. You can also insert more than one row
+ in a single command, but it is not possible to insert something that
+ is not a complete row. Even if you know only some column values, a
+ complete row must be created.
+ </p><p>
+ To create a new row, use the <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>
+ command. The command requires the
+ table name and column values. For
+ example, consider the products table from <a class="xref" href="ddl.html" title="Chapter 5. Data Definition">Chapter 5</a>:
+</p><pre class="programlisting">
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric
+);
+</pre><p>
+ An example command to insert a row would be:
+</p><pre class="programlisting">
+INSERT INTO products VALUES (1, 'Cheese', 9.99);
+</pre><p>
+ The data values are listed in the order in which the columns appear
+ in the table, separated by commas. Usually, the data values will
+ be literals (constants), but scalar expressions are also allowed.
+ </p><p>
+ The above syntax has the drawback that you need to know the order
+ of the columns in the table. To avoid this you can also list the
+ columns explicitly. For example, both of the following commands
+ have the same effect as the one above:
+</p><pre class="programlisting">
+INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', 9.99);
+INSERT INTO products (name, price, product_no) VALUES ('Cheese', 9.99, 1);
+</pre><p>
+ Many users consider it good practice to always list the column
+ names.
+ </p><p>
+ If you don't have values for all the columns, you can omit some of
+ them. In that case, the columns will be filled with their default
+ values. For example:
+</p><pre class="programlisting">
+INSERT INTO products (product_no, name) VALUES (1, 'Cheese');
+INSERT INTO products VALUES (1, 'Cheese');
+</pre><p>
+ The second form is a <span class="productname">PostgreSQL</span>
+ extension. It fills the columns from the left with as many values
+ as are given, and the rest will be defaulted.
+ </p><p>
+ For clarity, you can also request default values explicitly, for
+ individual columns or for the entire row:
+</p><pre class="programlisting">
+INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', DEFAULT);
+INSERT INTO products DEFAULT VALUES;
+</pre><p>
+ </p><p>
+ You can insert multiple rows in a single command:
+</p><pre class="programlisting">
+INSERT INTO products (product_no, name, price) VALUES
+ (1, 'Cheese', 9.99),
+ (2, 'Bread', 1.99),
+ (3, 'Milk', 2.99);
+</pre><p>
+ </p><p>
+ It is also possible to insert the result of a query (which might be no
+ rows, one row, or many rows):
+</p><pre class="programlisting">
+INSERT INTO products (product_no, name, price)
+ SELECT product_no, name, price FROM new_products
+ WHERE release_date = 'today';
+</pre><p>
+ This provides the full power of the SQL query mechanism (<a class="xref" href="queries.html" title="Chapter 7. Queries">Chapter 7</a>) for computing the rows to be inserted.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ When inserting a lot of data at the same time, consider using
+ the <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> command.
+ It is not as flexible as the <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>
+ command, but is more efficient. Refer
+ to <a class="xref" href="populate.html" title="14.4. Populating a Database">Section 14.4</a> for more information on improving
+ bulk loading performance.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml.html" title="Chapter 6. Data Manipulation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dml-update.html" title="6.2. Updating Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Data Manipulation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 6.2. Updating Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dml-returning.html b/doc/src/sgml/html/dml-returning.html
new file mode 100644
index 0000000..7bb12b2
--- /dev/null
+++ b/doc/src/sgml/html/dml-returning.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>6.4. Returning Data from Modified Rows</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dml-delete.html" title="6.3. Deleting Data" /><link rel="next" href="queries.html" title="Chapter 7. Queries" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">6.4. Returning Data from Modified Rows</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml-delete.html" title="6.3. Deleting Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><th width="60%" align="center">Chapter 6. Data Manipulation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries.html" title="Chapter 7. Queries">Next</a></td></tr></table><hr /></div><div class="sect1" id="DML-RETURNING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">6.4. Returning Data from Modified Rows</h2></div></div></div><a id="id-1.5.5.6.2" class="indexterm"></a><a id="id-1.5.5.6.3" class="indexterm"></a><a id="id-1.5.5.6.4" class="indexterm"></a><a id="id-1.5.5.6.5" class="indexterm"></a><p>
+ Sometimes it is useful to obtain data from modified rows while they are
+ being manipulated. The <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ and <code class="command">DELETE</code> commands all have an
+ optional <code class="literal">RETURNING</code> clause that supports this. Use
+ of <code class="literal">RETURNING</code> avoids performing an extra database query to
+ collect the data, and is especially valuable when it would otherwise be
+ difficult to identify the modified rows reliably.
+ </p><p>
+ The allowed contents of a <code class="literal">RETURNING</code> clause are the same as
+ a <code class="command">SELECT</code> command's output list
+ (see <a class="xref" href="queries-select-lists.html" title="7.3. Select Lists">Section 7.3</a>). It can contain column
+ names of the command's target table, or value expressions using those
+ columns. A common shorthand is <code class="literal">RETURNING *</code>, which selects
+ all columns of the target table in order.
+ </p><p>
+ In an <code class="command">INSERT</code>, the data available to <code class="literal">RETURNING</code> is
+ the row as it was inserted. This is not so useful in trivial inserts,
+ since it would just repeat the data provided by the client. But it can
+ be very handy when relying on computed default values. For example,
+ when using a <a class="link" href="datatype-numeric.html#DATATYPE-SERIAL" title="8.1.4. Serial Types"><code class="type">serial</code></a>
+ column to provide unique identifiers, <code class="literal">RETURNING</code> can return
+ the ID assigned to a new row:
+</p><pre class="programlisting">
+CREATE TABLE users (firstname text, lastname text, id serial primary key);
+
+INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id;
+</pre><p>
+ The <code class="literal">RETURNING</code> clause is also very useful
+ with <code class="literal">INSERT ... SELECT</code>.
+ </p><p>
+ In an <code class="command">UPDATE</code>, the data available to <code class="literal">RETURNING</code> is
+ the new content of the modified row. For example:
+</p><pre class="programlisting">
+UPDATE products SET price = price * 1.10
+ WHERE price &lt;= 99.99
+ RETURNING name, price AS new_price;
+</pre><p>
+ </p><p>
+ In a <code class="command">DELETE</code>, the data available to <code class="literal">RETURNING</code> is
+ the content of the deleted row. For example:
+</p><pre class="programlisting">
+DELETE FROM products
+ WHERE obsoletion_date = 'today'
+ RETURNING *;
+</pre><p>
+ </p><p>
+ If there are triggers (<a class="xref" href="triggers.html" title="Chapter 39. Triggers">Chapter 39</a>) on the target table,
+ the data available to <code class="literal">RETURNING</code> is the row as modified by
+ the triggers. Thus, inspecting columns computed by triggers is another
+ common use-case for <code class="literal">RETURNING</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml-delete.html" title="6.3. Deleting Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries.html" title="Chapter 7. Queries">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.3. Deleting Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Queries</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dml-update.html b/doc/src/sgml/html/dml-update.html
new file mode 100644
index 0000000..f7748cd
--- /dev/null
+++ b/doc/src/sgml/html/dml-update.html
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>6.2. Updating Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dml-insert.html" title="6.1. Inserting Data" /><link rel="next" href="dml-delete.html" title="6.3. Deleting Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">6.2. Updating Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml-insert.html" title="6.1. Inserting Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><th width="60%" align="center">Chapter 6. Data Manipulation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dml-delete.html" title="6.3. Deleting Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="DML-UPDATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">6.2. Updating Data</h2></div></div></div><a id="id-1.5.5.4.2" class="indexterm"></a><a id="id-1.5.5.4.3" class="indexterm"></a><p>
+ The modification of data that is already in the database is
+ referred to as updating. You can update individual rows, all the
+ rows in a table, or a subset of all rows. Each column can be
+ updated separately; the other columns are not affected.
+ </p><p>
+ To update existing rows, use the <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a>
+ command. This requires
+ three pieces of information:
+ </p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>The name of the table and column to update</p></li><li class="listitem"><p>The new value of the column</p></li><li class="listitem"><p>Which row(s) to update</p></li></ol></div><p>
+ </p><p>
+ Recall from <a class="xref" href="ddl.html" title="Chapter 5. Data Definition">Chapter 5</a> 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
+ be updated. Only if you have a primary key in the table (independent of
+ whether you declared it or not) can you reliably address individual rows
+ by choosing a condition that matches the primary key.
+ Graphical database access tools rely on this fact to allow you to
+ update rows individually.
+ </p><p>
+ For example, this command updates all products that have a price of
+ 5 to have a price of 10:
+</p><pre class="programlisting">
+UPDATE products SET price = 10 WHERE price = 5;
+</pre><p>
+ This might cause zero, one, or many rows to be updated. It is not
+ an error to attempt an update that does not match any rows.
+ </p><p>
+ Let's look at that command in detail. First is the key word
+ <code class="literal">UPDATE</code> followed by the table name. As usual,
+ the table name can be schema-qualified, otherwise it is looked up
+ in the path. Next is the key word <code class="literal">SET</code> followed
+ by the column name, an equal sign, and the new column value. The
+ new column value can be any scalar expression, not just a constant.
+ For example, if you want to raise the price of all products by 10%
+ you could use:
+</p><pre class="programlisting">
+UPDATE products SET price = price * 1.10;
+</pre><p>
+ As you see, the expression for the new value can refer to the existing
+ value(s) in the row. We also left out the <code class="literal">WHERE</code> clause.
+ If it is omitted, it means that all rows in the table are updated.
+ If it is present, only those rows that match the
+ <code class="literal">WHERE</code> condition are updated. Note that the equals
+ sign in the <code class="literal">SET</code> clause is an assignment while
+ the one in the <code class="literal">WHERE</code> clause is a comparison, but
+ this does not create any ambiguity. Of course, the
+ <code class="literal">WHERE</code> condition does
+ not have to be an equality test. Many other operators are
+ available (see <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>). But the expression
+ needs to evaluate to a Boolean result.
+ </p><p>
+ You can update more than one column in an
+ <code class="command">UPDATE</code> command by listing more than one
+ assignment in the <code class="literal">SET</code> clause. For example:
+</p><pre class="programlisting">
+UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a &gt; 0;
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml-insert.html" title="6.1. Inserting Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dml.html" title="Chapter 6. Data Manipulation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dml-delete.html" title="6.3. Deleting Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.1. Inserting Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 6.3. Deleting Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dml.html b/doc/src/sgml/html/dml.html
new file mode 100644
index 0000000..34fd93d
--- /dev/null
+++ b/doc/src/sgml/html/dml.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Data Manipulation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ddl-depend.html" title="5.14. Dependency Tracking" /><link rel="next" href="dml-insert.html" title="6.1. Inserting Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 6. Data Manipulation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ddl-depend.html" title="5.14. Dependency Tracking">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dml-insert.html" title="6.1. Inserting Data">Next</a></td></tr></table><hr /></div><div class="chapter" id="DML"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Data Manipulation</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="dml-insert.html">6.1. Inserting Data</a></span></dt><dt><span class="sect1"><a href="dml-update.html">6.2. Updating Data</a></span></dt><dt><span class="sect1"><a href="dml-delete.html">6.3. Deleting Data</a></span></dt><dt><span class="sect1"><a href="dml-returning.html">6.4. Returning Data from Modified Rows</a></span></dt></dl></div><p>
+ The previous chapter discussed how to create tables and other
+ structures to hold your data. Now it is time to fill the tables
+ with data. This chapter covers how to insert, update, and delete
+ table data. The chapter
+ after this will finally explain how to extract your long-lost data
+ from the database.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ddl-depend.html" title="5.14. Dependency Tracking">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dml-insert.html" title="6.1. Inserting Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.14. Dependency Tracking </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 6.1. Inserting Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide-authoring.html b/doc/src/sgml/html/docguide-authoring.html
new file mode 100644
index 0000000..c696bfe
--- /dev/null
+++ b/doc/src/sgml/html/docguide-authoring.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.4. Documentation Authoring</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-build.html" title="J.3. Building the Documentation" /><link rel="next" href="docguide-style.html" title="J.5. Style Guide" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.4. Documentation Authoring</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-build.html" title="J.3. Building the Documentation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-style.html" title="J.5. Style Guide">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-AUTHORING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.4. Documentation Authoring</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-authoring.html#id-1.11.11.7.4">J.4.1. Emacs</a></span></dt></dl></div><p>
+ The documentation sources are most conveniently modified with an editor
+ that has a mode for editing XML, and even more so if it has some awareness
+ of XML schema languages so that it can know about
+ <span class="productname">DocBook</span> syntax specifically.
+ </p><p>
+ Note that for historical reasons the documentation source files are named
+ with an extension <code class="filename">.sgml</code> even though they are now XML
+ files. So you might need to adjust your editor configuration to set the
+ correct mode.
+ </p><div class="sect2" id="id-1.11.11.7.4"><div class="titlepage"><div><div><h3 class="title">J.4.1. Emacs</h3></div></div></div><p>
+ <span class="productname">nXML Mode</span>, which ships with
+ <span class="productname">Emacs</span>, is the most common mode for editing
+ <acronym class="acronym">XML</acronym> documents with <span class="productname">Emacs</span>.
+ It will allow you to use <span class="application">Emacs</span> to insert tags
+ and check markup consistency, and it supports
+ <span class="productname">DocBook</span> out of the box. Check the <a class="ulink" href="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html" target="_top">
+ nXML manual</a> for detailed documentation.
+ </p><p>
+ <code class="filename">src/tools/editors/emacs.samples</code> contains
+ recommended settings for this mode.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-build.html" title="J.3. Building the Documentation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-style.html" title="J.5. Style Guide">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.3. Building the Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.5. Style Guide</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide-build.html b/doc/src/sgml/html/docguide-build.html
new file mode 100644
index 0000000..f26f676
--- /dev/null
+++ b/doc/src/sgml/html/docguide-build.html
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.3. Building the Documentation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-toolsets.html" title="J.2. Tool Sets" /><link rel="next" href="docguide-authoring.html" title="J.4. Documentation Authoring" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.3. Building the Documentation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-toolsets.html" title="J.2. Tool Sets">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-authoring.html" title="J.4. Documentation Authoring">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-BUILD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.3. Building the Documentation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.3">J.3.1. HTML</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.4">J.3.2. Manpages</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.5">J.3.3. PDF</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.6">J.3.4. Plain Text Files</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.7">J.3.5. Syntax Check</a></span></dt></dl></div><p>
+ Once you have everything set up, change to the directory
+ <code class="filename">doc/src/sgml</code> and run one of the commands
+ described in the following subsections to build the
+ documentation. (Remember to use GNU make.)
+ </p><div class="sect2" id="id-1.11.11.6.3"><div class="titlepage"><div><div><h3 class="title">J.3.1. HTML</h3></div></div></div><p>
+ To build the <acronym class="acronym">HTML</acronym> version of the documentation:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make html</code></strong>
+</pre><p>
+ This is also the default target. The output appears in the
+ subdirectory <code class="filename">html</code>.
+ </p><p>
+ To produce HTML documentation with the stylesheet used on <a class="ulink" href="https://www.postgresql.org/docs/current/" target="_top">postgresql.org</a> instead of the
+ default simple style use:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make STYLE=website html</code></strong>
+</pre><p>
+ </p><p>
+ If the <code class="literal">STYLE=website</code> option is used, the generated HTML
+ files include references to stylesheets hosted on <a class="ulink" href="https://www.postgresql.org/docs/current/" target="_top">postgresql.org</a> and
+ require network access to view.
+ </p></div><div class="sect2" id="id-1.11.11.6.4"><div class="titlepage"><div><div><h3 class="title">J.3.2. Manpages</h3></div></div></div><p>
+ We use the DocBook XSL stylesheets to
+ convert <span class="productname">DocBook</span>
+ <code class="sgmltag-element">refentry</code> pages to *roff output suitable for man
+ pages. To create the man pages, use the command:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make man</code></strong>
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.11.6.5"><div class="titlepage"><div><div><h3 class="title">J.3.3. PDF</h3></div></div></div><p>
+ To produce a PDF rendition of the documentation
+ using <span class="productname">FOP</span>, you can use one of the following
+ commands, depending on the preferred paper format:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ For A4 format:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make postgres-A4.pdf</code></strong>
+</pre><p>
+ </p></li><li class="listitem"><p>
+ For U.S. letter format:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make postgres-US.pdf</code></strong>
+</pre><p>
+ </p></li></ul></div><p>
+ </p><p>
+ Because the PostgreSQL documentation is fairly
+ big, <span class="productname">FOP</span> will require a significant amount of
+ memory. Because of that, on some systems, the build will fail with a
+ memory-related error message. This can usually be fixed by configuring
+ Java heap settings in the configuration
+ file <code class="filename">~/.foprc</code>, for example:
+</p><pre class="programlisting">
+# FOP binary distribution
+FOP_OPTS='-Xmx1500m'
+# Debian
+JAVA_ARGS='-Xmx1500m'
+# Red Hat
+ADDITIONAL_FLAGS='-Xmx1500m'
+</pre><p>
+ There is a minimum amount of memory that is required, and to some extent
+ more memory appears to make things a bit faster. On systems with very
+ little memory (less than 1 GB), the build will either be very slow due to
+ swapping or will not work at all.
+ </p><p>
+ Other XSL-FO processors can also be used manually, but the automated build
+ process only supports FOP.
+ </p></div><div class="sect2" id="id-1.11.11.6.6"><div class="titlepage"><div><div><h3 class="title">J.3.4. Plain Text Files</h3></div></div></div><p>
+ 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 <code class="filename">INSTALL</code> file
+ corresponds to <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>, with some minor
+ changes to account for the different context. To recreate the
+ file, change to the directory <code class="filename">doc/src/sgml</code>
+ and enter <strong class="userinput"><code>make INSTALL</code></strong>. Building text output
+ requires <span class="productname">Pandoc</span> version 1.13 or newer as an
+ additional build tool.
+ </p><p>
+ In the past, the release notes and regression testing instructions
+ were also distributed as plain text, but this practice has been
+ discontinued.
+ </p></div><div class="sect2" id="id-1.11.11.6.7"><div class="titlepage"><div><div><h3 class="title">J.3.5. Syntax Check</h3></div></div></div><p>
+ Building the documentation can take very long. But there is a
+ method to just check the correct syntax of the documentation
+ files, which only takes a few seconds:
+</p><pre class="screen">
+<code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>make check</code></strong>
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-toolsets.html" title="J.2. Tool Sets">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-authoring.html" title="J.4. Documentation Authoring">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.2. Tool Sets </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.4. Documentation Authoring</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide-docbook.html b/doc/src/sgml/html/docguide-docbook.html
new file mode 100644
index 0000000..40a366d
--- /dev/null
+++ b/doc/src/sgml/html/docguide-docbook.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.1. DocBook</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide.html" title="Appendix J. Documentation" /><link rel="next" href="docguide-toolsets.html" title="J.2. Tool Sets" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.1. DocBook</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide.html" title="Appendix J. Documentation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-toolsets.html" title="J.2. Tool Sets">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-DOCBOOK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.1. DocBook</h2></div></div></div><p>
+ The documentation sources are written in
+ <em class="firstterm">DocBook</em>, which is a markup language
+ defined in <acronym class="acronym">XML</acronym>. In what
+ follows, the terms DocBook and <acronym class="acronym">XML</acronym> are both
+ used, but technically they are not interchangeable.
+ </p><p>
+ <span class="productname">DocBook</span> allows an author to specify the
+ structure and content of a technical document without worrying
+ about presentation details. A document style defines how that
+ content is rendered into one of several final forms. DocBook is
+ maintained by the <a class="ulink" href="https://www.oasis-open.org" target="_top">
+ OASIS group</a>. The <a class="ulink" href="https://www.oasis-open.org/docbook/" target="_top">
+ official DocBook site</a> has good introductory and reference documentation and
+ a complete O'Reilly book for your online reading pleasure. The
+ <a class="ulink" href="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html" target="_top">
+ NewbieDoc Docbook Guide</a> is very helpful for beginners.
+ The <a class="ulink" href="https://www.freebsd.org/docproj/" target="_top">
+ FreeBSD Documentation Project</a> also uses DocBook and has some good
+ information, including a number of style guidelines that might be
+ worth considering.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide.html" title="Appendix J. Documentation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-toolsets.html" title="J.2. Tool Sets">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix J. Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.2. Tool Sets</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide-style.html b/doc/src/sgml/html/docguide-style.html
new file mode 100644
index 0000000..611927e
--- /dev/null
+++ b/doc/src/sgml/html/docguide-style.html
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.5. Style Guide</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-authoring.html" title="J.4. Documentation Authoring" /><link rel="next" href="limits.html" title="Appendix K. PostgreSQL Limits" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.5. Style Guide</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-authoring.html" title="J.4. Documentation Authoring">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="limits.html" title="Appendix K. PostgreSQL Limits">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-STYLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.5. Style Guide</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-style.html#id-1.11.11.8.2">J.5.1. Reference Pages</a></span></dt></dl></div><div class="sect2" id="id-1.11.11.8.2"><div class="titlepage"><div><div><h3 class="title">J.5.1. Reference Pages</h3></div></div></div><p>
+ Reference pages should follow a standard layout. This allows
+ users to find the desired information more quickly, and it also
+ encourages writers to document all relevant aspects of a command.
+ Consistency is not only desired among
+ <span class="productname">PostgreSQL</span> reference pages, but also
+ with reference pages provided by the operating system and other
+ packages. Hence the following guidelines have been developed.
+ They are for the most part consistent with similar guidelines
+ established by various operating systems.
+ </p><p>
+ Reference pages that describe executable commands should contain
+ the following sections, in this order. Sections that do not apply
+ can be omitted. Additional top-level sections should only be used
+ in special circumstances; often that information belongs in the
+ <span class="quote">“<span class="quote">Usage</span>”</span> section.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Name</span></dt><dd><p>
+ This section is generated automatically. It contains the
+ command name and a half-sentence summary of its functionality.
+ </p></dd><dt><span class="term">Synopsis</span></dt><dd><p>
+ This section contains the syntax diagram of the command. The
+ synopsis should normally not list each command-line option;
+ that is done below. Instead, list the major components of the
+ command line, such as where input and output files go.
+ </p></dd><dt><span class="term">Description</span></dt><dd><p>
+ Several paragraphs explaining what the command does.
+ </p></dd><dt><span class="term">Options</span></dt><dd><p>
+ A list describing each command-line option. If there are a
+ lot of options, subsections can be used.
+ </p></dd><dt><span class="term">Exit Status</span></dt><dd><p>
+ If the program uses 0 for success and non-zero for failure,
+ then you do not need to document it. If there is a meaning
+ behind the different non-zero exit codes, list them here.
+ </p></dd><dt><span class="term">Usage</span></dt><dd><p>
+ Describe any sublanguage or run-time interface of the program.
+ If the program is not interactive, this section can usually be
+ omitted. Otherwise, this section is a catch-all for
+ describing run-time features. Use subsections if appropriate.
+ </p></dd><dt><span class="term">Environment</span></dt><dd><p>
+ List all environment variables that the program might use.
+ Try to be complete; even seemingly trivial variables like
+ <code class="envar">SHELL</code> might be of interest to the user.
+ </p></dd><dt><span class="term">Files</span></dt><dd><p>
+ List any files that the program might access implicitly. That
+ is, do not list input and output files that were specified on
+ the command line, but list configuration files, etc.
+ </p></dd><dt><span class="term">Diagnostics</span></dt><dd><p>
+ Explain any unusual output that the program might create.
+ Refrain from listing every possible error message. This is a
+ lot of work and has little use in practice. But if, say, the
+ error messages have a standard format that the user can parse,
+ this would be the place to explain it.
+ </p></dd><dt><span class="term">Notes</span></dt><dd><p>
+ Anything that doesn't fit elsewhere, but in particular bugs,
+ implementation flaws, security considerations, compatibility
+ issues.
+ </p></dd><dt><span class="term">Examples</span></dt><dd><p>
+ Examples
+ </p></dd><dt><span class="term">History</span></dt><dd><p>
+ If there were some major milestones in the history of the
+ program, they might be listed here. Usually, this section can
+ be omitted.
+ </p></dd><dt><span class="term">Author</span></dt><dd><p>
+ Author (only used in the contrib section)
+ </p></dd><dt><span class="term">See Also</span></dt><dd><p>
+ Cross-references, listed in the following order: other
+ <span class="productname">PostgreSQL</span> command reference pages,
+ <span class="productname">PostgreSQL</span> SQL command reference
+ pages, citation of <span class="productname">PostgreSQL</span>
+ manuals, other reference pages (e.g., operating system, other
+ packages), other documentation. Items in the same group are
+ listed alphabetically.
+ </p></dd></dl></div><p>
+ </p><p>
+ Reference pages describing SQL commands should contain the
+ following sections: Name, Synopsis, Description, Parameters,
+ Outputs, Notes, Examples, Compatibility, History, See
+ Also. The Parameters section is like the Options section, but
+ there is more freedom about which clauses of the command can be
+ listed. The Outputs section is only needed if the command returns
+ something other than a default command-completion tag. The Compatibility
+ section should explain to what extent
+ this command conforms to the SQL standard(s), or to which other
+ database system it is compatible. The See Also section of SQL
+ commands should list SQL commands before cross-references to
+ programs.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-authoring.html" title="J.4. Documentation Authoring">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="limits.html" title="Appendix K. PostgreSQL Limits">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.4. Documentation Authoring </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix K. <span class="productname">PostgreSQL</span> Limits</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide-toolsets.html b/doc/src/sgml/html/docguide-toolsets.html
new file mode 100644
index 0000000..1b217ab
--- /dev/null
+++ b/doc/src/sgml/html/docguide-toolsets.html
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>J.2. Tool Sets</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-docbook.html" title="J.1. DocBook" /><link rel="next" href="docguide-build.html" title="J.3. Building the Documentation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">J.2. Tool Sets</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-docbook.html" title="J.1. DocBook">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><th width="60%" align="center">Appendix J. Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-build.html" title="J.3. Building the Documentation">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOCGUIDE-TOOLSETS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">J.2. Tool Sets</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.4">J.2.1. Installation on Fedora, RHEL, and Derivatives</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.5">J.2.2. Installation on FreeBSD</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.6">J.2.3. Debian Packages</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.7">J.2.4. macOS</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-CONFIGURE">J.2.5. Detection by <code class="command">configure</code></a></span></dt></dl></div><p>
+ The following tools are used to process the documentation. Some
+ might be optional, as noted.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="ulink" href="https://www.oasis-open.org/docbook/" target="_top">DocBook DTD</a></span></dt><dd><p>
+ This is the definition of DocBook itself. We currently use version
+ 4.5; you cannot use later or earlier versions. You need
+ the <acronym class="acronym">XML</acronym> variant of the DocBook DTD, not
+ the <acronym class="acronym">SGML</acronym> variant.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets" target="_top">DocBook XSL Stylesheets</a></span></dt><dd><p>
+ These contain the processing instructions for converting the
+ DocBook sources to other formats, such as
+ <acronym class="acronym">HTML</acronym>.
+ </p><p>
+ The minimum required version is currently 1.77.0, but it is recommended
+ to use the latest available version for best results.
+ </p></dd><dt><span class="term"><a class="ulink" href="http://xmlsoft.org/" target="_top">Libxml2</a> for <code class="command">xmllint</code></span></dt><dd><p>
+ This library and the <code class="command">xmllint</code> tool it contains are
+ used for processing XML. Many developers will already
+ have <span class="application">Libxml2</span> installed, because it is also
+ used when building the PostgreSQL code. Note, however,
+ that <code class="command">xmllint</code> might need to be installed from a
+ separate subpackage.
+ </p></dd><dt><span class="term"><a class="ulink" href="http://xmlsoft.org/XSLT/" target="_top">Libxslt</a> for <code class="command">xsltproc</code></span></dt><dd><p>
+ <code class="command">xsltproc</code> is an XSLT processor, that is, a program to
+ convert XML to other formats using XSLT stylesheets.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://xmlgraphics.apache.org/fop/" target="_top">FOP</a></span></dt><dd><p>
+ This is a program for converting, among other things, XML to PDF.
+ It is needed only if you want to build the documentation in PDF format.
+ </p></dd></dl></div><p>
+ </p><p>
+ We have documented experience with several installation methods for
+ the various tools that are needed to process the documentation.
+ These will be described below. There might be some other packaged
+ distributions for these tools. Please report package status to the
+ documentation mailing list, and we will include that information
+ here.
+ </p><div class="sect2" id="id-1.11.11.5.4"><div class="titlepage"><div><div><h3 class="title">J.2.1. Installation on Fedora, RHEL, and Derivatives</h3></div></div></div><p>
+ To install the required packages, use:
+</p><pre class="programlisting">
+yum install docbook-dtds docbook-style-xsl libxslt fop
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.11.5.5"><div class="titlepage"><div><div><h3 class="title">J.2.2. Installation on FreeBSD</h3></div></div></div><p>
+ To install the required packages with <code class="command">pkg</code>, use:
+</p><pre class="programlisting">
+pkg install docbook-xml docbook-xsl libxslt fop
+</pre><p>
+ </p><p>
+ When building the documentation from the <code class="filename">doc</code>
+ directory you'll need to use <code class="command">gmake</code>, because the
+ makefile provided is not suitable for FreeBSD's <code class="command">make</code>.
+ </p></div><div class="sect2" id="id-1.11.11.5.6"><div class="titlepage"><div><div><h3 class="title">J.2.3. Debian Packages</h3></div></div></div><p>
+ There is a full set of packages of the documentation tools
+ available for <span class="productname">Debian GNU/Linux</span>.
+ To install, simply use:
+</p><pre class="programlisting">
+apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.11.5.7"><div class="titlepage"><div><div><h3 class="title">J.2.4. macOS</h3></div></div></div><p>
+ If you use MacPorts, the following will get you set up:
+</p><pre class="programlisting">
+sudo port install docbook-xml docbook-xsl-nons libxslt fop
+</pre><p>
+ If you use Homebrew, use this:
+</p><pre class="programlisting">
+brew install docbook docbook-xsl libxslt fop
+</pre><p>
+ </p><p>
+ The Homebrew-supplied programs require the following environment variable
+ to be set. For Intel based machines, use this:
+</p><pre class="programlisting">
+export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
+</pre><p>
+ On Apple Silicon based machines, use this:
+</p><pre class="programlisting">
+export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
+</pre><p>
+ Without it, <code class="command">xsltproc</code> will throw errors like this:
+</p><pre class="programlisting">
+I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
+postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+...
+</pre><p>
+ </p><p>
+ While it is possible to use the Apple-provided versions
+ of <code class="command">xmllint</code> and <code class="command">xsltproc</code>
+ instead of those from MacPorts or Homebrew, you'll still need
+ to install the DocBook DTD and stylesheets, and set up a catalog
+ file that points to them.
+ </p></div><div class="sect2" id="DOCGUIDE-TOOLSETS-CONFIGURE"><div class="titlepage"><div><div><h3 class="title">J.2.5. Detection by <code class="command">configure</code></h3></div></div></div><p>
+ Before you can build the documentation you need to run the
+ <code class="filename">configure</code> script, as you would when building
+ the <span class="productname">PostgreSQL</span> programs themselves.
+ Check the output near the end of the run; it should look something
+ like this:
+</p><pre class="screen">
+checking for xmllint... xmllint
+checking for xsltproc... xsltproc
+checking for fop... fop
+checking for dbtoepub... dbtoepub
+</pre><p>
+ If <code class="filename">xmllint</code> or <code class="filename">xsltproc</code> is not
+ found, you will not be able to build any of the documentation.
+ <code class="filename">fop</code> is only needed to build the documentation in
+ PDF format.
+ <code class="filename">dbtoepub</code> is only needed to build the documentation
+ in EPUB format.
+ </p><p>
+ If necessary, you can tell <code class="filename">configure</code> where to find
+ these programs, for example
+</p><pre class="screen">
+./configure ... XMLLINT=/opt/local/bin/xmllint ...
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-docbook.html" title="J.1. DocBook">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="docguide.html" title="Appendix J. Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-build.html" title="J.3. Building the Documentation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.1. DocBook </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.3. Building the Documentation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/docguide.html b/doc/src/sgml/html/docguide.html
new file mode 100644
index 0000000..4bec9e2
--- /dev/null
+++ b/doc/src/sgml/html/docguide.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix J. Documentation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="git.html" title="I.1. Getting the Source via Git" /><link rel="next" href="docguide-docbook.html" title="J.1. DocBook" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix J. Documentation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="git.html" title="I.1. Getting the Source via Git">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide-docbook.html" title="J.1. DocBook">Next</a></td></tr></table><hr /></div><div class="appendix" id="DOCGUIDE"><div class="titlepage"><div><div><h2 class="title">Appendix J. Documentation</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="docguide-docbook.html">J.1. DocBook</a></span></dt><dt><span class="sect1"><a href="docguide-toolsets.html">J.2. Tool Sets</a></span></dt><dd><dl><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.4">J.2.1. Installation on Fedora, RHEL, and Derivatives</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.5">J.2.2. Installation on FreeBSD</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.6">J.2.3. Debian Packages</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#id-1.11.11.5.7">J.2.4. macOS</a></span></dt><dt><span class="sect2"><a href="docguide-toolsets.html#DOCGUIDE-TOOLSETS-CONFIGURE">J.2.5. Detection by <code class="command">configure</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="docguide-build.html">J.3. Building the Documentation</a></span></dt><dd><dl><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.3">J.3.1. HTML</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.4">J.3.2. Manpages</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.5">J.3.3. PDF</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.6">J.3.4. Plain Text Files</a></span></dt><dt><span class="sect2"><a href="docguide-build.html#id-1.11.11.6.7">J.3.5. Syntax Check</a></span></dt></dl></dd><dt><span class="sect1"><a href="docguide-authoring.html">J.4. Documentation Authoring</a></span></dt><dd><dl><dt><span class="sect2"><a href="docguide-authoring.html#id-1.11.11.7.4">J.4.1. Emacs</a></span></dt></dl></dd><dt><span class="sect1"><a href="docguide-style.html">J.5. Style Guide</a></span></dt><dd><dl><dt><span class="sect2"><a href="docguide-style.html#id-1.11.11.8.2">J.5.1. Reference Pages</a></span></dt></dl></dd></dl></div><p>
+ <span class="productname">PostgreSQL</span> has four primary documentation
+ formats:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Plain text, for pre-installation information
+ </p></li><li class="listitem"><p>
+ <acronym class="acronym">HTML</acronym>, for on-line browsing and reference
+ </p></li><li class="listitem"><p>
+ PDF, for printing
+ </p></li><li class="listitem"><p>
+ man pages, for quick reference.
+ </p></li></ul></div><p>
+
+ Additionally, a number of plain-text <code class="filename">README</code> files can
+ be found throughout the <span class="productname">PostgreSQL</span> source tree,
+ documenting various implementation issues.
+ </p><p>
+ <acronym class="acronym">HTML</acronym> documentation and man pages are part of a
+ standard distribution and are installed by default. PDF
+ format documentation is available separately for
+ download.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="git.html" title="I.1. Getting the Source via Git">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide-docbook.html" title="J.1. DocBook">Next</a></td></tr><tr><td width="40%" align="left" valign="top">I.1. Getting the Source via <span class="productname">Git</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> J.1. DocBook</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/domains.html b/doc/src/sgml/html/domains.html
new file mode 100644
index 0000000..8ac9c05
--- /dev/null
+++ b/doc/src/sgml/html/domains.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.18. Domain Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rangetypes.html" title="8.17. Range Types" /><link rel="next" href="datatype-oid.html" title="8.19. Object Identifier Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.18. Domain Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rangetypes.html" title="8.17. Range Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-oid.html" title="8.19. Object Identifier Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DOMAINS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.18. Domain Types</h2></div></div></div><a id="id-1.5.7.26.2" class="indexterm"></a><a id="id-1.5.7.26.3" class="indexterm"></a><p>
+ A <em class="firstterm">domain</em> is a user-defined data type that is
+ based on another <em class="firstterm">underlying type</em>. Optionally,
+ it can have constraints that restrict its valid values to a subset of
+ what the underlying type would allow. Otherwise it behaves like the
+ underlying type — for example, any operator or function that
+ can be applied to the underlying type will work on the domain type.
+ The underlying type can be any built-in or user-defined base type,
+ enum type, array type, composite type, range type, or another domain.
+ </p><p>
+ For example, we could create a domain over integers that accepts only
+ positive integers:
+</p><pre class="programlisting">
+CREATE DOMAIN posint AS integer CHECK (VALUE &gt; 0);
+CREATE TABLE mytable (id posint);
+INSERT INTO mytable VALUES(1); -- works
+INSERT INTO mytable VALUES(-1); -- fails
+</pre><p>
+ </p><p>
+ When an operator or function of the underlying type is applied to a
+ domain value, the domain is automatically down-cast to the underlying
+ type. Thus, for example, the result of <code class="literal">mytable.id - 1</code>
+ is considered to be of type <code class="type">integer</code> not <code class="type">posint</code>.
+ We could write <code class="literal">(mytable.id - 1)::posint</code> to cast the
+ result back to <code class="type">posint</code>, causing the domain's constraints
+ to be rechecked. In this case, that would result in an error if the
+ expression had been applied to an <code class="structfield">id</code> value of
+ 1. Assigning a value of the underlying type to a field or variable of
+ the domain type is allowed without writing an explicit cast, but the
+ domain's constraints will be checked.
+ </p><p>
+ For additional information see <a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rangetypes.html" title="8.17. Range Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-oid.html" title="8.19. Object Identifier Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.17. Range Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.19. Object Identifier Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/dynamic-trace.html b/doc/src/sgml/html/dynamic-trace.html
new file mode 100644
index 0000000..42690bf
--- /dev/null
+++ b/doc/src/sgml/html/dynamic-trace.html
@@ -0,0 +1,301 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>28.5. Dynamic Tracing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="progress-reporting.html" title="28.4. Progress Reporting" /><link rel="next" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">28.5. Dynamic Tracing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="progress-reporting.html" title="28.4. Progress Reporting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="DYNAMIC-TRACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">28.5. Dynamic Tracing</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="dynamic-trace.html#COMPILING-FOR-TRACE">28.5.1. Compiling for Dynamic Tracing</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#TRACE-POINTS">28.5.2. Built-in Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#USING-TRACE-POINTS">28.5.3. Using Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#DEFINING-TRACE-POINTS">28.5.4. Defining New Probes</a></span></dt></dl></div><a id="id-1.6.15.10.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides facilities to support
+ dynamic tracing of the database server. This allows an external
+ utility to be called at specific points in the code and thereby trace
+ execution.
+ </p><p>
+ A number of probes or trace points are already inserted into the source
+ code. These probes are intended to be used by database developers and
+ administrators. By default the probes are not compiled into
+ <span class="productname">PostgreSQL</span>; the user needs to explicitly tell
+ the configure script to make the probes available.
+ </p><p>
+ Currently, the
+ <a class="ulink" href="https://en.wikipedia.org/wiki/DTrace" target="_top">DTrace</a>
+ utility is supported, which, at the time of this writing, is available
+ on Solaris, macOS, FreeBSD, NetBSD, and Oracle Linux. The
+ <a class="ulink" href="https://sourceware.org/systemtap/" target="_top">SystemTap</a> project
+ for Linux provides a DTrace equivalent and can also be used. Supporting other dynamic
+ tracing utilities is theoretically possible by changing the definitions for
+ the macros in <code class="filename">src/include/utils/probes.h</code>.
+ </p><div class="sect2" id="COMPILING-FOR-TRACE"><div class="titlepage"><div><div><h3 class="title">28.5.1. Compiling for Dynamic Tracing</h3></div></div></div><p>
+ By default, probes are not available, so you will need to
+ explicitly tell the configure script to make the probes available
+ in <span class="productname">PostgreSQL</span>. To include DTrace support
+ specify <code class="option">--enable-dtrace</code> to configure. See <a class="xref" href="install-procedure.html" title="17.4. Installation Procedure">Section 17.4</a> for further information.
+ </p></div><div class="sect2" id="TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">28.5.2. Built-in Probes</h3></div></div></div><p>
+ A number of standard probes are provided in the source code,
+ as shown in <a class="xref" href="dynamic-trace.html#DTRACE-PROBE-POINT-TABLE" title="Table 28.47. Built-in DTrace Probes">Table 28.47</a>;
+ <a class="xref" href="dynamic-trace.html#TYPEDEFS-TABLE" title="Table 28.48. Defined Types Used in Probe Parameters">Table 28.48</a>
+ shows the types used in the probes. More probes can certainly be
+ added to enhance <span class="productname">PostgreSQL</span>'s observability.
+ </p><div class="table" id="DTRACE-PROBE-POINT-TABLE"><p class="title"><strong>Table 28.47. Built-in DTrace Probes</strong></p><div class="table-contents"><table class="table" summary="Built-in DTrace Probes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Parameters</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">transaction-start</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires at the start of a new transaction.
+ arg0 is the transaction ID.</td></tr><tr><td><code class="literal">transaction-commit</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires when a transaction completes successfully.
+ arg0 is the transaction ID.</td></tr><tr><td><code class="literal">transaction-abort</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires when a transaction completes unsuccessfully.
+ arg0 is the transaction ID.</td></tr><tr><td><code class="literal">query-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the processing of a query is started.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the processing of a query is complete.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-parse-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the parsing of a query is started.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-parse-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the parsing of a query is complete.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-rewrite-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the rewriting of a query is started.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-rewrite-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the rewriting of a query is complete.
+ arg0 is the query string.</td></tr><tr><td><code class="literal">query-plan-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the planning of a query is started.</td></tr><tr><td><code class="literal">query-plan-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the planning of a query is complete.</td></tr><tr><td><code class="literal">query-execute-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the execution of a query is started.</td></tr><tr><td><code class="literal">query-execute-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the execution of a query is complete.</td></tr><tr><td><code class="literal">statement-status</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires anytime the server process updates its
+ <code class="structname">pg_stat_activity</code>.<code class="structfield">status</code>.
+ arg0 is the new status string.</td></tr><tr><td><code class="literal">checkpoint-start</code></td><td><code class="literal">(int)</code></td><td>Probe that fires when a checkpoint is started.
+ arg0 holds the bitwise flags used to distinguish different checkpoint
+ types, such as shutdown, immediate or force.</td></tr><tr><td><code class="literal">checkpoint-done</code></td><td><code class="literal">(int, int, int, int, int)</code></td><td>Probe that fires when a checkpoint is complete.
+ (The probes listed next fire in sequence during checkpoint processing.)
+ arg0 is the number of buffers written. arg1 is the total number of
+ buffers. arg2, arg3 and arg4 contain the number of WAL files added,
+ removed and recycled respectively.</td></tr><tr><td><code class="literal">clog-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the CLOG portion of a checkpoint is started.
+ arg0 is true for normal checkpoint, false for shutdown
+ checkpoint.</td></tr><tr><td><code class="literal">clog-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the CLOG portion of a checkpoint is
+ complete. arg0 has the same meaning as for <code class="literal">clog-checkpoint-start</code>.</td></tr><tr><td><code class="literal">subtrans-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the SUBTRANS portion of a checkpoint is
+ started.
+ arg0 is true for normal checkpoint, false for shutdown
+ checkpoint.</td></tr><tr><td><code class="literal">subtrans-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the SUBTRANS portion of a checkpoint is
+ complete. arg0 has the same meaning as for
+ <code class="literal">subtrans-checkpoint-start</code>.</td></tr><tr><td><code class="literal">multixact-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the MultiXact portion of a checkpoint is
+ started.
+ arg0 is true for normal checkpoint, false for shutdown
+ checkpoint.</td></tr><tr><td><code class="literal">multixact-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the MultiXact portion of a checkpoint is
+ complete. arg0 has the same meaning as for
+ <code class="literal">multixact-checkpoint-start</code>.</td></tr><tr><td><code class="literal">buffer-checkpoint-start</code></td><td><code class="literal">(int)</code></td><td>Probe that fires when the buffer-writing portion of a checkpoint
+ is started.
+ arg0 holds the bitwise flags used to distinguish different checkpoint
+ types, such as shutdown, immediate or force.</td></tr><tr><td><code class="literal">buffer-sync-start</code></td><td><code class="literal">(int, int)</code></td><td>Probe that fires when we begin to write dirty buffers during
+ checkpoint (after identifying which buffers must be written).
+ arg0 is the total number of buffers.
+ arg1 is the number that are currently dirty and need to be written.</td></tr><tr><td><code class="literal">buffer-sync-written</code></td><td><code class="literal">(int)</code></td><td>Probe that fires after each buffer is written during checkpoint.
+ arg0 is the ID number of the buffer.</td></tr><tr><td><code class="literal">buffer-sync-done</code></td><td><code class="literal">(int, int, int)</code></td><td>Probe that fires when all dirty buffers have been written.
+ arg0 is the total number of buffers.
+ arg1 is the number of buffers actually written by the checkpoint process.
+ arg2 is the number that were expected to be written (arg1 of
+ <code class="literal">buffer-sync-start</code>); any difference reflects other processes flushing
+ buffers during the checkpoint.</td></tr><tr><td><code class="literal">buffer-checkpoint-sync-start</code></td><td><code class="literal">()</code></td><td>Probe that fires after dirty buffers have been written to the
+ kernel, and before starting to issue fsync requests.</td></tr><tr><td><code class="literal">buffer-checkpoint-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when syncing of buffers to disk is
+ complete.</td></tr><tr><td><code class="literal">twophase-checkpoint-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the two-phase portion of a checkpoint is
+ started.</td></tr><tr><td><code class="literal">twophase-checkpoint-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the two-phase portion of a checkpoint is
+ complete.</td></tr><tr><td><code class="literal">buffer-read-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool)</code></td><td>Probe that fires when a buffer read is started.
+ arg0 and arg1 contain the fork and block numbers of the page (but
+ arg1 will be -1 if this is a relation extension request).
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.
+ arg6 is true for a relation extension request, false for normal
+ read.</td></tr><tr><td><code class="literal">buffer-read-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool, bool)</code></td><td>Probe that fires when a buffer read is complete.
+ arg0 and arg1 contain the fork and block numbers of the page (if this
+ is a relation extension request, arg1 now contains the block number
+ of the newly added block).
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.
+ arg6 is true for a relation extension request, false for normal
+ read.
+ arg7 is true if the buffer was found in the pool, false if not.</td></tr><tr><td><code class="literal">buffer-flush-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires before issuing any write request for a shared
+ buffer.
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.</td></tr><tr><td><code class="literal">buffer-flush-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires when a write request is complete. (Note
+ that this just reflects the time to pass the data to the kernel;
+ it's typically not actually been written to disk yet.)
+ The arguments are the same as for <code class="literal">buffer-flush-start</code>.</td></tr><tr><td><code class="literal">buffer-write-dirty-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires when a server process begins to write a dirty
+ buffer. (If this happens often, it implies that
+ <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a> is too
+ small or the background writer control parameters need adjustment.)
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.</td></tr><tr><td><code class="literal">buffer-write-dirty-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires when a dirty-buffer write is complete.
+ The arguments are the same as for <code class="literal">buffer-write-dirty-start</code>.</td></tr><tr><td><code class="literal">wal-buffer-write-dirty-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when a server process begins to write a
+ dirty WAL buffer because no more WAL buffer space is available.
+ (If this happens often, it implies that
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-BUFFERS">wal_buffers</a> is too small.)</td></tr><tr><td><code class="literal">wal-buffer-write-dirty-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when a dirty WAL buffer write is complete.</td></tr><tr><td><code class="literal">wal-insert</code></td><td><code class="literal">(unsigned char, unsigned char)</code></td><td>Probe that fires when a WAL record is inserted.
+ arg0 is the resource manager (rmid) for the record.
+ arg1 contains the info flags.</td></tr><tr><td><code class="literal">wal-switch</code></td><td><code class="literal">()</code></td><td>Probe that fires when a WAL segment switch is requested.</td></tr><tr><td><code class="literal">smgr-md-read-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</code></td><td>Probe that fires when beginning to read a block from a relation.
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.</td></tr><tr><td><code class="literal">smgr-md-read-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</code></td><td>Probe that fires when a block read is complete.
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.
+ arg6 is the number of bytes actually read, while arg7 is the number
+ requested (if these are different it indicates trouble).</td></tr><tr><td><code class="literal">smgr-md-write-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</code></td><td>Probe that fires when beginning to write a block to a relation.
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.</td></tr><tr><td><code class="literal">smgr-md-write-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</code></td><td>Probe that fires when a block write is complete.
+ arg0 and arg1 contain the fork and block numbers of the page.
+ arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
+ identifying the relation.
+ arg5 is the ID of the backend which created the temporary relation for a
+ local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.
+ arg6 is the number of bytes actually written, while arg7 is the number
+ requested (if these are different it indicates trouble).</td></tr><tr><td><code class="literal">sort-start</code></td><td><code class="literal">(int, bool, int, int, bool, int)</code></td><td>Probe that fires when a sort operation is started.
+ arg0 indicates heap, index or datum sort.
+ arg1 is true for unique-value enforcement.
+ arg2 is the number of key columns.
+ arg3 is the number of kilobytes of work memory allowed.
+ arg4 is true if random access to the sort result is required.
+ arg5 indicates serial when <code class="literal">0</code>, parallel worker when
+ <code class="literal">1</code>, or parallel leader when <code class="literal">2</code>.</td></tr><tr><td><code class="literal">sort-done</code></td><td><code class="literal">(bool, long)</code></td><td>Probe that fires when a sort is complete.
+ arg0 is true for external sort, false for internal sort.
+ arg1 is the number of disk blocks used for an external sort,
+ or kilobytes of memory used for an internal sort.</td></tr><tr><td><code class="literal">lwlock-acquire</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock has been acquired.
+ arg0 is the LWLock's tranche.
+ arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-release</code></td><td><code class="literal">(char *)</code></td><td>Probe that fires when an LWLock has been released (but note
+ that any released waiters have not yet been awakened).
+ arg0 is the LWLock's tranche.</td></tr><tr><td><code class="literal">lwlock-wait-start</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was not immediately available and
+ a server process has begun to wait for the lock to become available.
+ arg0 is the LWLock's tranche.
+ arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-wait-done</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when a server process has been released from its
+ wait for an LWLock (it does not actually have the lock yet).
+ arg0 is the LWLock's tranche.
+ arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-condacquire</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was successfully acquired when the
+ caller specified no waiting.
+ arg0 is the LWLock's tranche.
+ arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-condacquire-fail</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was not successfully acquired when
+ the caller specified no waiting.
+ arg0 is the LWLock's tranche.
+ arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lock-wait-start</code></td><td><code class="literal">(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</code></td><td>Probe that fires when a request for a heavyweight lock (lmgr lock)
+ has begun to wait because the lock is not available.
+ arg0 through arg3 are the tag fields identifying the object being
+ locked. arg4 indicates the type of object being locked.
+ arg5 indicates the lock type being requested.</td></tr><tr><td><code class="literal">lock-wait-done</code></td><td><code class="literal">(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</code></td><td>Probe that fires when a request for a heavyweight lock (lmgr lock)
+ has finished waiting (i.e., has acquired the lock).
+ The arguments are the same as for <code class="literal">lock-wait-start</code>.</td></tr><tr><td><code class="literal">deadlock-found</code></td><td><code class="literal">()</code></td><td>Probe that fires when a deadlock is found by the deadlock
+ detector.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="TYPEDEFS-TABLE"><p class="title"><strong>Table 28.48. Defined Types Used in Probe Parameters</strong></p><div class="table-contents"><table class="table" summary="Defined Types Used in Probe Parameters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Type</th><th>Definition</th></tr></thead><tbody><tr><td><code class="type">LocalTransactionId</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">LWLockMode</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">LOCKMODE</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">BlockNumber</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">Oid</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">ForkNumber</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">bool</code></td><td><code class="type">unsigned char</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="USING-TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">28.5.3. Using Probes</h3></div></div></div><p>
+ The example below shows a DTrace script for analyzing transaction
+ counts in the system, as an alternative to snapshotting
+ <code class="structname">pg_stat_database</code> before and after a performance test:
+</p><pre class="programlisting">
+#!/usr/sbin/dtrace -qs
+
+postgresql$1:::transaction-start
+{
+ @start["Start"] = count();
+ self-&gt;ts = timestamp;
+}
+
+postgresql$1:::transaction-abort
+{
+ @abort["Abort"] = count();
+}
+
+postgresql$1:::transaction-commit
+/self-&gt;ts/
+{
+ @commit["Commit"] = count();
+ @time["Total time (ns)"] = sum(timestamp - self-&gt;ts);
+ self-&gt;ts=0;
+}
+</pre><p>
+ When executed, the example D script gives output such as:
+</p><pre class="screen">
+# ./txn_count.d `pgrep -n postgres` or ./txn_count.d &lt;PID&gt;
+^C
+
+Start 71
+Commit 70
+Total time (ns) 2312105013
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ SystemTap uses a different notation for trace scripts than DTrace does,
+ even though the underlying trace points are compatible. One point worth
+ noting is that at this writing, SystemTap scripts must reference probe
+ names using double underscores in place of hyphens. This is expected to
+ be fixed in future SystemTap releases.
+ </p></div><p>
+ You should remember that DTrace scripts need to be carefully written and
+ debugged, otherwise the trace information collected might
+ be meaningless. In most cases where problems are found it is the
+ instrumentation that is at fault, not the underlying system. When
+ discussing information found using dynamic tracing, be sure to enclose
+ the script used to allow that too to be checked and discussed.
+ </p></div><div class="sect2" id="DEFINING-TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">28.5.4. Defining New Probes</h3></div></div></div><p>
+ New probes can be defined within the code wherever the developer
+ desires, though this will require a recompilation. Below are the steps
+ for inserting new probes:
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ Decide on probe names and data to be made available through the probes
+ </p></li><li class="step"><p>
+ Add the probe definitions to <code class="filename">src/backend/utils/probes.d</code>
+ </p></li><li class="step"><p>
+ Include <code class="filename">pg_trace.h</code> if it is not already present in the
+ module(s) containing the probe points, and insert
+ <code class="literal">TRACE_POSTGRESQL</code> probe macros at the desired locations
+ in the source code
+ </p></li><li class="step"><p>
+ Recompile and verify that the new probes are available
+ </p></li></ol></div><p><strong>Example: </strong>
+ Here is an example of how you would add a probe to trace all new
+ transactions by transaction ID.
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ Decide that the probe will be named <code class="literal">transaction-start</code> and
+ requires a parameter of type <code class="type">LocalTransactionId</code>
+ </p></li><li class="step"><p>
+ Add the probe definition to <code class="filename">src/backend/utils/probes.d</code>:
+</p><pre class="programlisting">
+probe transaction__start(LocalTransactionId);
+</pre><p>
+ Note the use of the double underline in the probe name. In a DTrace
+ script using the probe, the double underline needs to be replaced with a
+ hyphen, so <code class="literal">transaction-start</code> is the name to document for
+ users.
+ </p></li><li class="step"><p>
+ At compile time, <code class="literal">transaction__start</code> is converted to a macro
+ called <code class="literal">TRACE_POSTGRESQL_TRANSACTION_START</code> (notice the
+ underscores are single here), which is available by including
+ <code class="filename">pg_trace.h</code>. Add the macro call to the appropriate location
+ in the source code. In this case, it looks like the following:
+
+</p><pre class="programlisting">
+TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
+</pre><p>
+ </p></li><li class="step"><p>
+ After recompiling and running the new binary, check that your newly added
+ probe is available by executing the following DTrace command. You
+ should see similar output:
+</p><pre class="screen">
+# dtrace -ln transaction-start
+ ID PROVIDER MODULE FUNCTION NAME
+18705 postgresql49878 postgres StartTransactionCommand transaction-start
+18755 postgresql49877 postgres StartTransactionCommand transaction-start
+18805 postgresql49876 postgres StartTransactionCommand transaction-start
+18855 postgresql49875 postgres StartTransactionCommand transaction-start
+18986 postgresql49873 postgres StartTransactionCommand transaction-start
+</pre><p>
+ </p></li></ol></div><p>
+ There are a few things to be careful about when adding trace macros
+ to the C code:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ You should take care that the data types specified for a probe's
+ parameters match the data types of the variables used in the macro.
+ Otherwise, you will get compilation errors.
+ </p></li><li class="listitem"><p>
+ On most platforms, if <span class="productname">PostgreSQL</span> is
+ built with <code class="option">--enable-dtrace</code>, the arguments to a trace
+ macro will be evaluated whenever control passes through the
+ macro, <span class="emphasis"><em>even if no tracing is being done</em></span>. This is
+ usually not worth worrying about if you are just reporting the
+ values of a few local variables. But beware of putting expensive
+ function calls into the arguments. If you need to do that,
+ consider protecting the macro with a check to see if the trace
+ is actually enabled:
+
+</p><pre class="programlisting">
+if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
+ TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
+</pre><p>
+
+ Each trace macro has a corresponding <code class="literal">ENABLED</code> macro.
+ </p></li></ul></div><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="progress-reporting.html" title="28.4. Progress Reporting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.4. Progress Reporting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 29. Monitoring Disk Usage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/earthdistance.html b/doc/src/sgml/html/earthdistance.html
new file mode 100644
index 0000000..ebfb48f
--- /dev/null
+++ b/doc/src/sgml/html/earthdistance.html
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.15. earthdistance</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dict-xsyn.html" title="F.14. dict_xsyn" /><link rel="next" href="file-fdw.html" title="F.16. file_fdw" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.15. earthdistance</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dict-xsyn.html" title="F.14. dict_xsyn">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="file-fdw.html" title="F.16. file_fdw">Next</a></td></tr></table><hr /></div><div class="sect1" id="EARTHDISTANCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.15. earthdistance</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="earthdistance.html#id-1.11.7.24.7">F.15.1. Cube-Based Earth Distances</a></span></dt><dt><span class="sect2"><a href="earthdistance.html#id-1.11.7.24.8">F.15.2. Point-Based Earth Distances</a></span></dt></dl></div><a id="id-1.11.7.24.2" class="indexterm"></a><p>
+ The <code class="filename">earthdistance</code> module provides two different approaches to
+ calculating great circle distances on the surface of the Earth. The one
+ described first depends on the <code class="filename">cube</code> module.
+ The second one is based on the built-in <code class="type">point</code> data type,
+ using longitude and latitude for the coordinates.
+ </p><p>
+ In this module, the Earth is assumed to be perfectly spherical.
+ (If that's too inaccurate for you, you might want to look at the
+ <span class="application"><a class="ulink" href="https://postgis.net/" target="_top">PostGIS</a></span>
+ project.)
+ </p><p>
+ The <code class="filename">cube</code> module must be installed
+ before <code class="filename">earthdistance</code> can be installed
+ (although you can use the <code class="literal">CASCADE</code> option
+ of <code class="command">CREATE EXTENSION</code> to install both in one command).
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is strongly recommended that <code class="filename">earthdistance</code>
+ and <code class="filename">cube</code> be installed in the same schema, and that
+ that schema be one for which CREATE privilege has not been and will not
+ be granted to any untrusted users.
+ Otherwise there are installation-time security hazards
+ if <code class="filename">earthdistance</code>'s schema contains objects defined
+ by a hostile user.
+ Furthermore, when using <code class="filename">earthdistance</code>'s functions
+ after installation, the entire search path should contain only trusted
+ schemas.
+ </p></div><div class="sect2" id="id-1.11.7.24.7"><div class="titlepage"><div><div><h3 class="title">F.15.1. Cube-Based Earth Distances</h3></div></div></div><p>
+ Data is stored in cubes that are points (both corners are the same) using 3
+ coordinates representing the x, y, and z distance from the center of the
+ Earth. A <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain</a></em></a>
+ <code class="type">earth</code> over type <code class="type">cube</code> is provided, which
+ includes constraint checks that the value meets these restrictions and
+ is reasonably close to the actual surface of the Earth.
+ </p><p>
+ The radius of the Earth is obtained from the <code class="function">earth()</code>
+ function. It is given in meters. But by changing this one function you can
+ change the module to use some other units, or to use a different value of
+ the radius that you feel is more appropriate.
+ </p><p>
+ This package has applications to astronomical databases as well.
+ Astronomers will probably want to change <code class="function">earth()</code> to return a
+ radius of <code class="literal">180/pi()</code> so that distances are in degrees.
+ </p><p>
+ Functions are provided to support input in latitude and longitude (in
+ degrees), to support output of latitude and longitude, to calculate
+ the great circle distance between two points and to easily specify a
+ bounding box usable for index searches.
+ </p><p>
+ The provided functions are shown
+ in <a class="xref" href="earthdistance.html#EARTHDISTANCE-CUBE-FUNCTIONS" title="Table F.5. Cube-Based Earthdistance Functions">Table F.5</a>.
+ </p><div class="table" id="EARTHDISTANCE-CUBE-FUNCTIONS"><p class="title"><strong>Table F.5. Cube-Based Earthdistance Functions</strong></p><div class="table-contents"><table class="table" summary="Cube-Based Earthdistance Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">earth</code> ()
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the assumed radius of the Earth.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">sec_to_gc</code> ( <code class="type">float8</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Converts the normal straight line
+ (secant) distance between two points on the surface of the Earth
+ to the great circle distance between them.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">gc_to_sec</code> ( <code class="type">float8</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Converts the great circle distance between two points on the
+ surface of the Earth to the normal straight line (secant) distance
+ between them.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">ll_to_earth</code> ( <code class="type">float8</code>, <code class="type">float8</code> )
+ → <code class="returnvalue">earth</code>
+ </p>
+ <p>
+ Returns the location of a point on the surface of the Earth given
+ its latitude (argument 1) and longitude (argument 2) in degrees.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">latitude</code> ( <code class="type">earth</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the latitude in degrees of a point on the surface of the
+ Earth.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">longitude</code> ( <code class="type">earth</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the longitude in degrees of a point on the surface of the
+ Earth.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">earth_distance</code> ( <code class="type">earth</code>, <code class="type">earth</code> )
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Returns the great circle distance between two points on the
+ surface of the Earth.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.24.7.7.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">earth_box</code> ( <code class="type">earth</code>, <code class="type">float8</code> )
+ → <code class="returnvalue">cube</code>
+ </p>
+ <p>
+ Returns a box suitable for an indexed search using the <code class="type">cube</code>
+ <code class="literal">@&gt;</code>
+ operator for points within a given great circle distance of a location.
+ Some points in this box are further than the specified great circle
+ distance from the location, so a second check using
+ <code class="function">earth_distance</code> should be included in the query.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.24.8"><div class="titlepage"><div><div><h3 class="title">F.15.2. Point-Based Earth Distances</h3></div></div></div><p>
+ The second part of the module relies on representing Earth locations as
+ values of type <code class="type">point</code>, in which the first component is taken to
+ represent longitude in degrees, and the second component is taken to
+ represent latitude in degrees. Points are taken as (longitude, latitude)
+ and not vice versa because longitude is closer to the intuitive idea of
+ x-axis and latitude to y-axis.
+ </p><p>
+ A single operator is provided, shown
+ in <a class="xref" href="earthdistance.html#EARTHDISTANCE-POINT-OPERATORS" title="Table F.6. Point-Based Earthdistance Operators">Table F.6</a>.
+ </p><div class="table" id="EARTHDISTANCE-POINT-OPERATORS"><p class="title"><strong>Table F.6. Point-Based Earthdistance Operators</strong></p><div class="table-contents"><table class="table" summary="Point-Based Earthdistance Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">point</code> <code class="literal">&lt;@&gt;</code> <code class="type">point</code>
+ → <code class="returnvalue">float8</code>
+ </p>
+ <p>
+ Computes the distance in statute miles between
+ two points on the Earth's surface.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Note that unlike the <code class="type">cube</code>-based part of the module, units
+ are hardwired here: changing the <code class="function">earth()</code> function will
+ not affect the results of this operator.
+ </p><p>
+ One disadvantage of the longitude/latitude representation is that
+ you need to be careful about the edge conditions near the poles
+ and near +/- 180 degrees of longitude. The <code class="type">cube</code>-based
+ representation avoids these discontinuities.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dict-xsyn.html" title="F.14. dict_xsyn">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="file-fdw.html" title="F.16. file_fdw">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.14. dict_xsyn </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.16. file_fdw</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-commands.html b/doc/src/sgml/html/ecpg-commands.html
new file mode 100644
index 0000000..bf3ef1a
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-commands.html
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.3. Running SQL Commands</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-connect.html" title="36.2. Managing Database Connections" /><link rel="next" href="ecpg-variables.html" title="36.4. Using Host Variables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.3. Running SQL Commands</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-connect.html" title="36.2. Managing Database Connections">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-variables.html" title="36.4. Using Host Variables">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-COMMANDS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.3. Running SQL Commands</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-EXECUTING">36.3.1. Executing SQL Statements</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-CURSORS">36.3.2. Using Cursors</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-TRANSACTIONS">36.3.3. Managing Transactions</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-PREPARED">36.3.4. Prepared Statements</a></span></dt></dl></div><p>
+ Any SQL command can be run from within an embedded SQL application.
+ Below are some examples of how to do that.
+ </p><div class="sect2" id="ECPG-EXECUTING"><div class="titlepage"><div><div><h3 class="title">36.3.1. Executing SQL Statements</h3></div></div></div><p>
+ Creating a table:
+</p><pre class="programlisting">
+EXEC SQL CREATE TABLE foo (number integer, ascii char(16));
+EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number);
+EXEC SQL COMMIT;
+</pre><p>
+ </p><p>
+ Inserting rows:
+</p><pre class="programlisting">
+EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
+EXEC SQL COMMIT;
+</pre><p>
+ </p><p>
+ Deleting rows:
+</p><pre class="programlisting">
+EXEC SQL DELETE FROM foo WHERE number = 9999;
+EXEC SQL COMMIT;
+</pre><p>
+ </p><p>
+ Updates:
+</p><pre class="programlisting">
+EXEC SQL UPDATE foo
+ SET ascii = 'foobar'
+ WHERE number = 9999;
+EXEC SQL COMMIT;
+</pre><p>
+ </p><p>
+ <code class="literal">SELECT</code> statements that return a single result
+ row can also be executed using
+ <code class="literal">EXEC SQL</code> directly. To handle result sets with
+ multiple rows, an application has to use a cursor;
+ see <a class="xref" href="ecpg-commands.html#ECPG-CURSORS" title="36.3.2. Using Cursors">Section 36.3.2</a> below. (As a special case, an
+ application can fetch multiple rows at once into an array host
+ variable; see <a class="xref" href="ecpg-variables.html#ECPG-VARIABLES-ARRAYS" title="36.4.4.3.1. Arrays">Section 36.4.4.3.1</a>.)
+ </p><p>
+ Single-row select:
+</p><pre class="programlisting">
+EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
+</pre><p>
+ </p><p>
+ Also, a configuration parameter can be retrieved with the
+ <code class="literal">SHOW</code> command:
+</p><pre class="programlisting">
+EXEC SQL SHOW search_path INTO :var;
+</pre><p>
+ </p><p>
+ The tokens of the form
+ <code class="literal">:<em class="replaceable"><code>something</code></em></code> are
+ <em class="firstterm">host variables</em>, that is, they refer to
+ variables in the C program. They are explained in <a class="xref" href="ecpg-variables.html" title="36.4. Using Host Variables">Section 36.4</a>.
+ </p></div><div class="sect2" id="ECPG-CURSORS"><div class="titlepage"><div><div><h3 class="title">36.3.2. Using Cursors</h3></div></div></div><p>
+ To retrieve a result set holding multiple rows, an application has
+ to declare a cursor and fetch each row from the cursor. The steps
+ to use a cursor are the following: declare a cursor, open it, fetch
+ a row from the cursor, repeat, and finally close it.
+ </p><p>
+ Select using cursors:
+</p><pre class="programlisting">
+EXEC SQL DECLARE foo_bar CURSOR FOR
+ SELECT number, ascii FROM foo
+ ORDER BY ascii;
+EXEC SQL OPEN foo_bar;
+EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
+...
+EXEC SQL CLOSE foo_bar;
+EXEC SQL COMMIT;
+</pre><p>
+ </p><p>
+ For more details about declaring a cursor, see <a class="xref" href="ecpg-sql-declare.html" title="DECLARE">DECLARE</a>; for more details about fetching rows from a
+ cursor, see <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The ECPG <code class="command">DECLARE</code> command does not actually
+ cause a statement to be sent to the PostgreSQL backend. The
+ cursor is opened in the backend (using the
+ backend's <code class="command">DECLARE</code> command) at the point when
+ the <code class="command">OPEN</code> command is executed.
+ </p></div></div><div class="sect2" id="ECPG-TRANSACTIONS"><div class="titlepage"><div><div><h3 class="title">36.3.3. Managing Transactions</h3></div></div></div><p>
+ In the default mode, statements are committed only when
+ <code class="command">EXEC SQL COMMIT</code> is issued. The embedded SQL
+ interface also supports autocommit of transactions (similar to
+ <span class="application">psql</span>'s default behavior) via the <code class="option">-t</code>
+ command-line option to <code class="command">ecpg</code> (see <a class="xref" href="app-ecpg.html" title="ecpg"><span class="refentrytitle"><span class="application">ecpg</span></span></a>) or via the <code class="literal">EXEC SQL SET AUTOCOMMIT TO
+ ON</code> 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 <code class="literal">EXEC
+ SQL SET AUTOCOMMIT TO OFF</code>.
+ </p><p>
+ The following transaction management commands are available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">EXEC SQL COMMIT</code></span></dt><dd><p>
+ Commit an in-progress transaction.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL ROLLBACK</code></span></dt><dd><p>
+ Roll back an in-progress transaction.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL PREPARE TRANSACTION </code><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ Prepare the current transaction for two-phase commit.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL COMMIT PREPARED </code><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ Commit a transaction that is in prepared state.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL ROLLBACK PREPARED </code><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ Roll back a transaction that is in prepared state.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL SET AUTOCOMMIT TO ON</code></span></dt><dd><p>
+ Enable autocommit mode.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL SET AUTOCOMMIT TO OFF</code></span></dt><dd><p>
+ Disable autocommit mode. This is the default.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PREPARED"><div class="titlepage"><div><div><h3 class="title">36.3.4. Prepared Statements</h3></div></div></div><p>
+ When the values to be passed to an SQL statement are not known at
+ compile time, or the same statement is going to be used many
+ times, then prepared statements can be useful.
+ </p><p>
+ The statement is prepared using the
+ command <code class="literal">PREPARE</code>. For the values that are not
+ known yet, use the
+ placeholder <span class="quote">“<span class="quote"><code class="literal">?</code></span>”</span>:
+</p><pre class="programlisting">
+EXEC SQL PREPARE stmt1 FROM "SELECT oid, datname FROM pg_database WHERE oid = ?";
+</pre><p>
+ </p><p>
+ If a statement returns a single row, the application can
+ call <code class="literal">EXECUTE</code> after
+ <code class="literal">PREPARE</code> to execute the statement, supplying the
+ actual values for the placeholders with a <code class="literal">USING</code>
+ clause:
+</p><pre class="programlisting">
+EXEC SQL EXECUTE stmt1 INTO :dboid, :dbname USING 1;
+</pre><p>
+ </p><p>
+ If a statement returns multiple rows, the application can use a
+ cursor declared based on the prepared statement. To bind input
+ parameters, the cursor must be opened with
+ a <code class="literal">USING</code> clause:
+</p><pre class="programlisting">
+EXEC SQL PREPARE stmt1 FROM "SELECT oid,datname FROM pg_database WHERE oid &gt; ?";
+EXEC SQL DECLARE foo_bar CURSOR FOR stmt1;
+
+/* when end of result set reached, break out of while loop */
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+EXEC SQL OPEN foo_bar USING 100;
+...
+while (1)
+{
+ EXEC SQL FETCH NEXT FROM foo_bar INTO :dboid, :dbname;
+ ...
+}
+EXEC SQL CLOSE foo_bar;
+</pre><p>
+ </p><p>
+ When you don't need the prepared statement anymore, you should
+ deallocate it:
+</p><pre class="programlisting">
+EXEC SQL DEALLOCATE PREPARE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ </p><p>
+ For more details about <code class="literal">PREPARE</code>,
+ see <a class="xref" href="ecpg-sql-prepare.html" title="PREPARE">PREPARE</a>. Also
+ see <a class="xref" href="ecpg-dynamic.html" title="36.5. Dynamic SQL">Section 36.5</a> for more details about using
+ placeholders and input parameters.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-connect.html" title="36.2. Managing Database Connections">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-variables.html" title="36.4. Using Host Variables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.2. Managing Database Connections </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.4. Using Host Variables</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-concept.html b/doc/src/sgml/html/ecpg-concept.html
new file mode 100644
index 0000000..8b3d8ea
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-concept.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.1. The Concept</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C" /><link rel="next" href="ecpg-connect.html" title="36.2. Managing Database Connections" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.1. The Concept</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-connect.html" title="36.2. Managing Database Connections">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-CONCEPT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.1. The Concept</h2></div></div></div><p>
+ An embedded SQL program consists of code written in an ordinary
+ programming language, in this case C, mixed with SQL commands in
+ specially marked sections. To build the program, the source code (<code class="filename">*.pgc</code>)
+ is first passed through the embedded SQL preprocessor, which converts it
+ to an ordinary C program (<code class="filename">*.c</code>), and afterwards it can be processed by a C
+ compiler. (For details about the compiling and linking see <a class="xref" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Section 36.10</a>.)
+ 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.
+ </p><p>
+ Embedded <acronym class="acronym">SQL</acronym> has advantages over other methods
+ for handling <acronym class="acronym">SQL</acronym> commands from C code. First, it
+ takes care of the tedious passing of information to and from
+ variables in your <acronym class="acronym">C</acronym> program. Second, the SQL
+ code in the program is checked at build time for syntactical
+ correctness. Third, embedded <acronym class="acronym">SQL</acronym> in C is
+ specified in the <acronym class="acronym">SQL</acronym> standard and supported by
+ many other <acronym class="acronym">SQL</acronym> database systems. The
+ <span class="productname">PostgreSQL</span> implementation is designed to match this
+ standard as much as possible, and it is usually possible to port
+ embedded <acronym class="acronym">SQL</acronym> programs written for other SQL
+ databases to <span class="productname">PostgreSQL</span> with relative
+ ease.
+ </p><p>
+ As already stated, programs written for the embedded
+ <acronym class="acronym">SQL</acronym> interface are normal C programs with special
+ code inserted to perform database-related actions. This special
+ code always has the form:
+</p><pre class="programlisting">
+EXEC SQL ...;
+</pre><p>
+ These statements syntactically take the place of a C statement.
+ Depending on the particular statement, they can appear at the
+ global level or within a function.
+ </p><p>
+ Embedded
+ <acronym class="acronym">SQL</acronym> statements follow the case-sensitivity rules of
+ normal <acronym class="acronym">SQL</acronym> code, and not those of C. Also they allow nested
+ C-style comments as per the SQL standard. The C part of the
+ program, however, follows the C standard of not accepting nested comments.
+ Embedded <acronym class="acronym">SQL</acronym> statements likewise use SQL rules, not
+ C rules, for parsing quoted strings and identifiers.
+ (See <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> and
+ <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS" title="4.1.1. Identifiers and Key Words">Section 4.1.1</a> respectively. Note that
+ ECPG assumes that <code class="varname">standard_conforming_strings</code>
+ is <code class="literal">on</code>.)
+ Of course, the C part of the program follows C quoting rules.
+ </p><p>
+ The following sections explain all the embedded SQL statements.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-connect.html" title="36.2. Managing Database Connections">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.2. Managing Database Connections</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-connect.html b/doc/src/sgml/html/ecpg-connect.html
new file mode 100644
index 0000000..0310976
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-connect.html
@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.2. Managing Database Connections</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-concept.html" title="36.1. The Concept" /><link rel="next" href="ecpg-commands.html" title="36.3. Running SQL Commands" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.2. Managing Database Connections</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-concept.html" title="36.1. The Concept">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-commands.html" title="36.3. Running SQL Commands">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.2. Managing Database Connections</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-CONNECTING">36.2.1. Connecting to the Database Server</a></span></dt><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-SET-CONNECTION">36.2.2. Choosing a Connection</a></span></dt><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-DISCONNECT">36.2.3. Closing a Connection</a></span></dt></dl></div><p>
+ This section describes how to open, close, and switch database
+ connections.
+ </p><div class="sect2" id="ECPG-CONNECTING"><div class="titlepage"><div><div><h3 class="title">36.2.1. Connecting to the Database Server</h3></div></div></div><p>
+ One connects to a database using the following statement:
+</p><pre class="programlisting">
+EXEC SQL CONNECT TO <em class="replaceable"><code>target</code></em> [<span class="optional">AS <em class="replaceable"><code>connection-name</code></em></span>] [<span class="optional">USER <em class="replaceable"><code>user-name</code></em></span>];
+</pre><p>
+ The <em class="replaceable"><code>target</code></em> can be specified in the
+ following ways:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>dbname</code></em>[<span class="optional">@<em class="replaceable"><code>hostname</code></em></span>][<span class="optional">:<em class="replaceable"><code>port</code></em></span>]</code>
+ </li><li class="listitem">
+ <code class="literal">tcp:postgresql://<em class="replaceable"><code>hostname</code></em>[<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>options</code></em></span>]</code>
+ </li><li class="listitem">
+ <code class="literal">unix:postgresql://localhost[<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>options</code></em></span>]</code>
+ </li><li class="listitem">
+ an SQL string literal containing one of the above forms
+ </li><li class="listitem">
+ a reference to a character variable containing one of the above forms (see examples)
+ </li><li class="listitem">
+ <code class="literal">DEFAULT</code>
+ </li></ul></div><p>
+
+ The connection target <code class="literal">DEFAULT</code> initiates a connection
+ to the default database under the default user name. No separate
+ user name or connection name can be specified in that case.
+ </p><p>
+ If you specify the connection target directly (that is, not as a string
+ literal or variable reference), then the components of the target are
+ passed through normal SQL parsing; this means that, for example,
+ the <em class="replaceable"><code>hostname</code></em> must look like one or more SQL
+ identifiers separated by dots, and those identifiers will be
+ case-folded unless double-quoted. Values of
+ any <em class="replaceable"><code>options</code></em> must be SQL identifiers,
+ integers, or variable references. Of course, you can put nearly
+ anything into an SQL identifier by double-quoting it.
+ In practice, it is probably less error-prone to use a (single-quoted)
+ string literal or a variable reference than to write the connection
+ target directly.
+ </p><p>
+ There are also different ways to specify the user name:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>username</code></em></code>
+ </li><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>username</code></em>/<em class="replaceable"><code>password</code></em></code>
+ </li><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>username</code></em> IDENTIFIED BY <em class="replaceable"><code>password</code></em></code>
+ </li><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>username</code></em> USING <em class="replaceable"><code>password</code></em></code>
+ </li></ul></div><p>
+
+ As above, the parameters <em class="replaceable"><code>username</code></em> and
+ <em class="replaceable"><code>password</code></em> can be an SQL identifier, an
+ SQL string literal, or a reference to a character variable.
+ </p><p>
+ If the connection target includes any <em class="replaceable"><code>options</code></em>,
+ those consist of
+ <code class="literal"><em class="replaceable"><code>keyword</code></em>=<em class="replaceable"><code>value</code></em></code>
+ specifications separated by ampersands (<code class="literal">&amp;</code>).
+ The allowed key words are the same ones recognized
+ by <span class="application">libpq</span> (see
+ <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>). Spaces are ignored before
+ any <em class="replaceable"><code>keyword</code></em> or <em class="replaceable"><code>value</code></em>,
+ though not within or after one. Note that there is no way to
+ write <code class="literal">&amp;</code> within a <em class="replaceable"><code>value</code></em>.
+ </p><p>
+ Notice that when specifying a socket connection
+ (with the <code class="literal">unix:</code> prefix), the host name must be
+ exactly <code class="literal">localhost</code>. To select a non-default
+ socket directory, write the directory's pathname as the value of
+ a <code class="varname">host</code> option in
+ the <em class="replaceable"><code>options</code></em> part of the target.
+ </p><p>
+ The <em class="replaceable"><code>connection-name</code></em> is used to handle
+ multiple connections in one program. It can be omitted if a
+ program uses only one connection. The most recently opened
+ connection becomes the current connection, which is used by default
+ when an SQL statement is to be executed (see later in this
+ chapter).
+ </p><p>
+ Here are some examples of <code class="command">CONNECT</code> statements:
+</p><pre class="programlisting">
+EXEC SQL CONNECT TO mydb@sql.mydomain.com;
+
+EXEC SQL CONNECT TO tcp:postgresql://sql.mydomain.com/mydb AS myconnection USER john;
+
+EXEC SQL BEGIN DECLARE SECTION;
+const char *target = "mydb@sql.mydomain.com";
+const char *user = "john";
+const char *passwd = "secret";
+EXEC SQL END DECLARE SECTION;
+ ...
+EXEC SQL CONNECT TO :target USER :user USING :passwd;
+/* or EXEC SQL CONNECT TO :target USER :user/:passwd; */
+</pre><p>
+ The last example makes use of the feature referred to above as
+ character variable references. You will see in later sections how C
+ variables can be used in SQL statements when you prefix them with a
+ colon.
+ </p><p>
+ Be advised that the format of the connection target is not
+ specified in the SQL standard. So if you want to develop portable
+ applications, you might want to use something based on the last
+ example above to encapsulate the connection target string
+ somewhere.
+ </p><p>
+ If untrusted users have access to a database that has not adopted a
+ <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
+ begin each session by removing publicly-writable schemas
+ from <code class="varname">search_path</code>. For example,
+ add <code class="literal">options=-c search_path=</code>
+ to <code class="literal"><em class="replaceable"><code>options</code></em></code>, or
+ issue <code class="literal">EXEC SQL SELECT pg_catalog.set_config('search_path', '',
+ false);</code> after connecting. This consideration is not specific to
+ ECPG; it applies to every interface for executing arbitrary SQL commands.
+ </p></div><div class="sect2" id="ECPG-SET-CONNECTION"><div class="titlepage"><div><div><h3 class="title">36.2.2. Choosing a Connection</h3></div></div></div><p>
+ SQL statements in embedded SQL programs are by default executed on
+ the current connection, that is, the most recently opened one. If
+ an application needs to manage multiple connections, then there are
+ three ways to handle this.
+ </p><p>
+ The first option is to explicitly choose a connection for each SQL
+ statement, for example:
+</p><pre class="programlisting">
+EXEC SQL AT <em class="replaceable"><code>connection-name</code></em> SELECT ...;
+</pre><p>
+ This option is particularly suitable if the application needs to
+ use several connections in mixed order.
+ </p><p>
+ If your application uses multiple threads of execution, they cannot share a
+ connection concurrently. You must either explicitly control access to the connection
+ (using mutexes) or use a connection for each thread.
+ </p><p>
+ The second option is to execute a statement to switch the current
+ connection. That statement is:
+</p><pre class="programlisting">
+EXEC SQL SET CONNECTION <em class="replaceable"><code>connection-name</code></em>;
+</pre><p>
+ This option is particularly convenient if many statements are to be
+ executed on the same connection.
+ </p><p>
+ Here is an example program managing multiple database connections:
+</p><pre class="programlisting">
+#include &lt;stdio.h&gt;
+
+EXEC SQL BEGIN DECLARE SECTION;
+ char dbname[1024];
+EXEC SQL END DECLARE SECTION;
+
+int
+main()
+{
+ EXEC SQL CONNECT TO testdb1 AS con1 USER testuser;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL CONNECT TO testdb2 AS con2 USER testuser;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL CONNECT TO testdb3 AS con3 USER testuser;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ /* This query would be executed in the last opened database "testdb3". */
+ EXEC SQL SELECT current_database() INTO :dbname;
+ printf("current=%s (should be testdb3)\n", dbname);
+
+ /* Using "AT" to run a query in "testdb2" */
+ EXEC SQL AT con2 SELECT current_database() INTO :dbname;
+ printf("current=%s (should be testdb2)\n", dbname);
+
+ /* Switch the current connection to "testdb1". */
+ EXEC SQL SET CONNECTION con1;
+
+ EXEC SQL SELECT current_database() INTO :dbname;
+ printf("current=%s (should be testdb1)\n", dbname);
+
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre><p>
+
+ This example would produce this output:
+</p><pre class="screen">
+current=testdb3 (should be testdb3)
+current=testdb2 (should be testdb2)
+current=testdb1 (should be testdb1)
+</pre><p>
+ </p><p>
+ The third option is to declare an SQL identifier linked to
+ the connection, for example:
+</p><pre class="programlisting">
+EXEC SQL AT <em class="replaceable"><code>connection-name</code></em> DECLARE <em class="replaceable"><code>statement-name</code></em> STATEMENT;
+EXEC SQL PREPARE <em class="replaceable"><code>statement-name</code></em> FROM :<em class="replaceable"><code>dyn-string</code></em>;
+</pre><p>
+ Once you link an SQL identifier to a connection, you execute dynamic SQL
+ without an AT clause. Note that this option behaves like preprocessor
+ directives, therefore the link is enabled only in the file.
+ </p><p>
+ Here is an example program using this option:
+</p><pre class="programlisting">
+#include &lt;stdio.h&gt;
+
+EXEC SQL BEGIN DECLARE SECTION;
+char dbname[128];
+char *dyn_sql = "SELECT current_database()";
+EXEC SQL END DECLARE SECTION;
+
+int main(){
+ EXEC SQL CONNECT TO postgres AS con1;
+ EXEC SQL CONNECT TO testdb AS con2;
+ EXEC SQL AT con1 DECLARE stmt STATEMENT;
+ EXEC SQL PREPARE stmt FROM :dyn_sql;
+ EXEC SQL EXECUTE stmt INTO :dbname;
+ printf("%s\n", dbname);
+
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre><p>
+
+ This example would produce this output, even if the default connection is testdb:
+</p><pre class="screen">
+postgres
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-DISCONNECT"><div class="titlepage"><div><div><h3 class="title">36.2.3. Closing a Connection</h3></div></div></div><p>
+ To close a connection, use the following statement:
+</p><pre class="programlisting">
+EXEC SQL DISCONNECT [<span class="optional"><em class="replaceable"><code>connection</code></em></span>];
+</pre><p>
+ The <em class="replaceable"><code>connection</code></em> can be specified
+ in the following ways:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ <code class="literal"><em class="replaceable"><code>connection-name</code></em></code>
+ </li><li class="listitem">
+ <code class="literal">CURRENT</code>
+ </li><li class="listitem">
+ <code class="literal">ALL</code>
+ </li></ul></div><p>
+
+ If no connection name is specified, the current connection is
+ closed.
+ </p><p>
+ It is good style that an application always explicitly disconnect
+ from every connection it opened.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-concept.html" title="36.1. The Concept">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-commands.html" title="36.3. Running SQL Commands">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.1. The Concept </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.3. Running SQL Commands</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-cpp.html b/doc/src/sgml/html/ecpg-cpp.html
new file mode 100644
index 0000000..3a54306
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-cpp.html
@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.13. C++ Applications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-lo.html" title="36.12. Large Objects" /><link rel="next" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.13. <acronym class="acronym">C++</acronym> Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-lo.html" title="36.12. Large Objects">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-CPP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.13. <acronym class="acronym">C++</acronym> Applications</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-SCOPE">36.13.1. Scope for Host Variables</a></span></dt><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-AND-C">36.13.2. C++ Application Development with External C Module</a></span></dt></dl></div><p>
+ ECPG has some limited support for C++ applications. This section
+ describes some caveats.
+ </p><p>
+ The <code class="command">ecpg</code> preprocessor takes an input file
+ written in C (or something like C) and embedded SQL commands,
+ converts the embedded SQL commands into C language chunks, and
+ finally generates a <code class="filename">.c</code> file. The header file
+ declarations of the library functions used by the C language chunks
+ that <code class="command">ecpg</code> generates are wrapped
+ in <code class="literal">extern "C" { ... }</code> blocks when used under
+ C++, so they should work seamlessly in C++.
+ </p><p>
+ In general, however, the <code class="command">ecpg</code> preprocessor only
+ understands C; it does not handle the special syntax and reserved
+ words of the C++ language. So, some embedded SQL code written in
+ C++ application code that uses complicated features specific to C++
+ might fail to be preprocessed correctly or might not work as
+ expected.
+ </p><p>
+ 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 <a class="xref" href="ecpg-cpp.html#ECPG-CPP-AND-C" title="36.13.2. C++ Application Development with External C Module">Section 36.13.2</a>
+ about that.
+ </p><div class="sect2" id="ECPG-CPP-SCOPE"><div class="titlepage"><div><div><h3 class="title">36.13.1. Scope for Host Variables</h3></div></div></div><p>
+ The <code class="command">ecpg</code> preprocessor understands the scope of
+ variables in C. In the C language, this is rather simple because
+ the scopes of variables is based on their code blocks. In C++,
+ however, the class member variables are referenced in a different
+ code block from the declared position, so
+ the <code class="command">ecpg</code> preprocessor will not understand the
+ scope of the class member variables.
+ </p><p>
+ For example, in the following case, the <code class="command">ecpg</code>
+ preprocessor cannot find any declaration for the
+ variable <code class="literal">dbname</code> in the <code class="literal">test</code>
+ method, so an error will occur.
+
+</p><pre class="programlisting">
+class TestCpp
+{
+ EXEC SQL BEGIN DECLARE SECTION;
+ char dbname[1024];
+ EXEC SQL END DECLARE SECTION;
+
+ public:
+ TestCpp();
+ void test();
+ ~TestCpp();
+};
+
+TestCpp::TestCpp()
+{
+ EXEC SQL CONNECT TO testdb1;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+}
+
+void Test::test()
+{
+ EXEC SQL SELECT current_database() INTO :dbname;
+ printf("current_database = %s\n", dbname);
+}
+
+TestCpp::~TestCpp()
+{
+ EXEC SQL DISCONNECT ALL;
+}
+</pre><p>
+
+ This code will result in an error like this:
+</p><pre class="screen">
+<strong class="userinput"><code>ecpg test_cpp.pgc</code></strong>
+test_cpp.pgc:28: ERROR: variable "dbname" is not declared
+</pre><p>
+ </p><p>
+ To avoid this scope issue, the <code class="literal">test</code> method
+ could be modified to use a local variable as intermediate storage.
+ But this approach is only a poor workaround, because it uglifies
+ the code and reduces performance.
+
+</p><pre class="programlisting">
+void TestCpp::test()
+{
+ EXEC SQL BEGIN DECLARE SECTION;
+ char tmp[1024];
+ EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL SELECT current_database() INTO :tmp;
+ strlcpy(dbname, tmp, sizeof(tmp));
+
+ printf("current_database = %s\n", dbname);
+}
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-CPP-AND-C"><div class="titlepage"><div><div><h3 class="title">36.13.2. C++ Application Development with External C Module</h3></div></div></div><p>
+ If you understand these technical limitations of
+ the <code class="command">ecpg</code> preprocessor in C++, you might come to
+ the conclusion that linking C objects and C++ objects at the link
+ stage to enable C++ applications to use ECPG features could be
+ better than writing some embedded SQL commands in C++ code
+ directly. This section describes a way to separate some embedded
+ SQL commands from C++ application code with a simple example. In
+ this example, the application is implemented in C++, while C and
+ ECPG is used to connect to the PostgreSQL server.
+ </p><p>
+ Three kinds of files have to be created: a C file
+ (<code class="filename">*.pgc</code>), a header file, and a C++ file:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">test_mod.pgc</code></span></dt><dd><p>
+ A sub-routine module to execute SQL commands embedded in C.
+ It is going to be converted
+ into <code class="filename">test_mod.c</code> by the preprocessor.
+
+</p><pre class="programlisting">
+#include "test_mod.h"
+#include &lt;stdio.h&gt;
+
+void
+db_connect()
+{
+ EXEC SQL CONNECT TO testdb1;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+}
+
+void
+db_test()
+{
+ EXEC SQL BEGIN DECLARE SECTION;
+ char dbname[1024];
+ EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL SELECT current_database() INTO :dbname;
+ printf("current_database = %s\n", dbname);
+}
+
+void
+db_disconnect()
+{
+ EXEC SQL DISCONNECT ALL;
+}
+</pre><p>
+ </p></dd><dt><span class="term"><code class="filename">test_mod.h</code></span></dt><dd><p>
+ A header file with declarations of the functions in the C
+ module (<code class="filename">test_mod.pgc</code>). It is included by
+ <code class="filename">test_cpp.cpp</code>. This file has to have an
+ <code class="literal">extern "C"</code> block around the declarations,
+ because it will be linked from the C++ module.
+
+</p><pre class="programlisting">
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void db_connect();
+void db_test();
+void db_disconnect();
+
+#ifdef __cplusplus
+}
+#endif
+</pre><p>
+ </p></dd><dt><span class="term"><code class="filename">test_cpp.cpp</code></span></dt><dd><p>
+ The main code for the application, including
+ the <code class="function">main</code> routine, and in this example a
+ C++ class.
+
+</p><pre class="programlisting">
+#include "test_mod.h"
+
+class TestCpp
+{
+ public:
+ TestCpp();
+ void test();
+ ~TestCpp();
+};
+
+TestCpp::TestCpp()
+{
+ db_connect();
+}
+
+void
+TestCpp::test()
+{
+ db_test();
+}
+
+TestCpp::~TestCpp()
+{
+ db_disconnect();
+}
+
+int
+main(void)
+{
+ TestCpp *t = new TestCpp();
+
+ t-&gt;test();
+ return 0;
+}
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ To build the application, proceed as follows. Convert
+ <code class="filename">test_mod.pgc</code> into <code class="filename">test_mod.c</code> by
+ running <code class="command">ecpg</code>, and generate
+ <code class="filename">test_mod.o</code> by compiling
+ <code class="filename">test_mod.c</code> with the C compiler:
+</p><pre class="programlisting">
+ecpg -o test_mod.c test_mod.pgc
+cc -c test_mod.c -o test_mod.o
+</pre><p>
+ </p><p>
+ Next, generate <code class="filename">test_cpp.o</code> by compiling
+ <code class="filename">test_cpp.cpp</code> with the C++ compiler:
+</p><pre class="programlisting">
+c++ -c test_cpp.cpp -o test_cpp.o
+</pre><p>
+ </p><p>
+ Finally, link these object files, <code class="filename">test_cpp.o</code>
+ and <code class="filename">test_mod.o</code>, into one executable, using the C++
+ compiler driver:
+</p><pre class="programlisting">
+c++ test_cpp.o test_mod.o -lecpg -o test_cpp
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-lo.html" title="36.12. Large Objects">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.12. Large Objects </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.14. Embedded SQL Commands</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-descriptors.html b/doc/src/sgml/html/ecpg-descriptors.html
new file mode 100644
index 0000000..a93f57e
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-descriptors.html
@@ -0,0 +1,710 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.7. Using Descriptor Areas</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-pgtypes.html" title="36.6. pgtypes Library" /><link rel="next" href="ecpg-errors.html" title="36.8. Error Handling" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.7. Using Descriptor Areas</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-errors.html" title="36.8. Error Handling">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-DESCRIPTORS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.7. Using Descriptor Areas</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS">36.7.1. Named SQL Descriptor Areas</a></span></dt><dt><span class="sect2"><a href="ecpg-descriptors.html#ECPG-SQLDA-DESCRIPTORS">36.7.2. SQLDA Descriptor Areas</a></span></dt></dl></div><p>
+ An SQL descriptor area is a more sophisticated method for processing
+ the result of a <code class="command">SELECT</code>, <code class="command">FETCH</code> or
+ a <code class="command">DESCRIBE</code> statement. An SQL descriptor area groups
+ the data of one row of data together with metadata items into one
+ data structure. The metadata is particularly useful when executing
+ dynamic SQL statements, where the nature of the result columns might
+ not be known ahead of time. PostgreSQL provides two ways to use
+ Descriptor Areas: the named SQL Descriptor Areas and the C-structure
+ SQLDAs.
+ </p><div class="sect2" id="ECPG-NAMED-DESCRIPTORS"><div class="titlepage"><div><div><h3 class="title">36.7.1. Named SQL Descriptor Areas</h3></div></div></div><p>
+ A named SQL descriptor area consists of a header, which contains
+ information concerning the entire descriptor, and one or more item
+ descriptor areas, which basically each describe one column in the
+ result row.
+ </p><p>
+ Before you can use an SQL descriptor area, you need to allocate one:
+</p><pre class="programlisting">
+EXEC SQL ALLOCATE DESCRIPTOR <em class="replaceable"><code>identifier</code></em>;
+</pre><p>
+ The identifier serves as the <span class="quote">“<span class="quote">variable name</span>”</span> of the
+ descriptor area.
+ When you don't need the descriptor anymore, you should deallocate
+ it:
+</p><pre class="programlisting">
+EXEC SQL DEALLOCATE DESCRIPTOR <em class="replaceable"><code>identifier</code></em>;
+</pre><p>
+ </p><p>
+ To use a descriptor area, specify it as the storage target in an
+ <code class="literal">INTO</code> clause, instead of listing host variables:
+</p><pre class="programlisting">
+EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;
+</pre><p>
+ If the result set is empty, the Descriptor Area will still contain
+ the metadata from the query, i.e., the field names.
+ </p><p>
+ For not yet executed prepared queries, the <code class="command">DESCRIBE</code>
+ statement can be used to get the metadata of the result set:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+char *sql_stmt = "SELECT * FROM table1";
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL PREPARE stmt1 FROM :sql_stmt;
+EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
+</pre><p>
+ </p><p>
+ Before PostgreSQL 9.0, the <code class="literal">SQL</code> keyword was optional,
+ so using <code class="literal">DESCRIPTOR</code> and <code class="literal">SQL DESCRIPTOR</code>
+ produced named SQL Descriptor Areas. Now it is mandatory, omitting
+ the <code class="literal">SQL</code> keyword produces SQLDA Descriptor Areas,
+ see <a class="xref" href="ecpg-descriptors.html#ECPG-SQLDA-DESCRIPTORS" title="36.7.2. SQLDA Descriptor Areas">Section 36.7.2</a>.
+ </p><p>
+ In <code class="command">DESCRIBE</code> and <code class="command">FETCH</code> statements,
+ the <code class="literal">INTO</code> and <code class="literal">USING</code> keywords can be
+ used to similarly: they produce the result set and the metadata in a
+ Descriptor Area.
+ </p><p>
+ Now how do you get the data out of the descriptor area? You can
+ think of the descriptor area as a structure with named fields. To
+ retrieve the value of a field from the header and store it into a
+ host variable, use the following command:
+</p><pre class="programlisting">
+EXEC SQL GET DESCRIPTOR <em class="replaceable"><code>name</code></em> :<em class="replaceable"><code>hostvar</code></em> = <em class="replaceable"><code>field</code></em>;
+</pre><p>
+ Currently, there is only one header field defined:
+ <em class="replaceable"><code>COUNT</code></em>, which tells how many item
+ descriptor areas exist (that is, how many columns are contained in
+ the result). The host variable needs to be of an integer type. To
+ get a field from the item descriptor area, use the following
+ command:
+</p><pre class="programlisting">
+EXEC SQL GET DESCRIPTOR <em class="replaceable"><code>name</code></em> VALUE <em class="replaceable"><code>num</code></em> :<em class="replaceable"><code>hostvar</code></em> = <em class="replaceable"><code>field</code></em>;
+</pre><p>
+ <em class="replaceable"><code>num</code></em> can be a literal integer or a host
+ variable containing an integer. Possible fields are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CARDINALITY</code> (integer)</span></dt><dd><p>
+ number of rows in the result set
+ </p></dd><dt><span class="term"><code class="literal">DATA</code></span></dt><dd><p>
+ actual data item (therefore, the data type of this field
+ depends on the query)
+ </p></dd><dt><span class="term"><code class="literal">DATETIME_INTERVAL_CODE</code> (integer)</span></dt><dd><p>
+ When <code class="literal">TYPE</code> is <code class="literal">9</code>,
+ <code class="literal">DATETIME_INTERVAL_CODE</code> will have a value of
+ <code class="literal">1</code> for <code class="literal">DATE</code>,
+ <code class="literal">2</code> for <code class="literal">TIME</code>,
+ <code class="literal">3</code> for <code class="literal">TIMESTAMP</code>,
+ <code class="literal">4</code> for <code class="literal">TIME WITH TIME ZONE</code>, or
+ <code class="literal">5</code> for <code class="literal">TIMESTAMP WITH TIME ZONE</code>.
+ </p></dd><dt><span class="term"><code class="literal">DATETIME_INTERVAL_PRECISION</code> (integer)</span></dt><dd><p>
+ not implemented
+ </p></dd><dt><span class="term"><code class="literal">INDICATOR</code> (integer)</span></dt><dd><p>
+ the indicator (indicating a null value or a value truncation)
+ </p></dd><dt><span class="term"><code class="literal">KEY_MEMBER</code> (integer)</span></dt><dd><p>
+ not implemented
+ </p></dd><dt><span class="term"><code class="literal">LENGTH</code> (integer)</span></dt><dd><p>
+ length of the datum in characters
+ </p></dd><dt><span class="term"><code class="literal">NAME</code> (string)</span></dt><dd><p>
+ name of the column
+ </p></dd><dt><span class="term"><code class="literal">NULLABLE</code> (integer)</span></dt><dd><p>
+ not implemented
+ </p></dd><dt><span class="term"><code class="literal">OCTET_LENGTH</code> (integer)</span></dt><dd><p>
+ length of the character representation of the datum in bytes
+ </p></dd><dt><span class="term"><code class="literal">PRECISION</code> (integer)</span></dt><dd><p>
+ precision (for type <code class="type">numeric</code>)
+ </p></dd><dt><span class="term"><code class="literal">RETURNED_LENGTH</code> (integer)</span></dt><dd><p>
+ length of the datum in characters
+ </p></dd><dt><span class="term"><code class="literal">RETURNED_OCTET_LENGTH</code> (integer)</span></dt><dd><p>
+ length of the character representation of the datum in bytes
+ </p></dd><dt><span class="term"><code class="literal">SCALE</code> (integer)</span></dt><dd><p>
+ scale (for type <code class="type">numeric</code>)
+ </p></dd><dt><span class="term"><code class="literal">TYPE</code> (integer)</span></dt><dd><p>
+ numeric code of the data type of the column
+ </p></dd></dl></div><p>
+ </p><p>
+ In <code class="command">EXECUTE</code>, <code class="command">DECLARE</code> and <code class="command">OPEN</code>
+ statements, the effect of the <code class="literal">INTO</code> and <code class="literal">USING</code>
+ keywords are different. A Descriptor Area can also be manually built to
+ provide the input parameters for a query or a cursor and
+ <code class="literal">USING SQL DESCRIPTOR <em class="replaceable"><code>name</code></em></code>
+ is the way to pass the input parameters into a parameterized query. The statement
+ to build a named SQL Descriptor Area is below:
+</p><pre class="programlisting">
+EXEC SQL SET DESCRIPTOR <em class="replaceable"><code>name</code></em> VALUE <em class="replaceable"><code>num</code></em> <em class="replaceable"><code>field</code></em> = :<em class="replaceable"><code>hostvar</code></em>;
+</pre><p>
+ </p><p>
+ PostgreSQL supports retrieving more that one record in one <code class="command">FETCH</code>
+ statement and storing the data in host variables in this case assumes that the
+ variable is an array. E.g.:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int id[5];
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;
+
+EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;
+</pre><p>
+
+ </p></div><div class="sect2" id="ECPG-SQLDA-DESCRIPTORS"><div class="titlepage"><div><div><h3 class="title">36.7.2. SQLDA Descriptor Areas</h3></div></div></div><p>
+ An SQLDA Descriptor Area is a C language structure which can be also used
+ to get the result set and the metadata of a query. One structure stores one
+ record from the result set.
+</p><pre class="programlisting">
+EXEC SQL include sqlda.h;
+sqlda_t *mysqlda;
+
+EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;
+</pre><p>
+ Note that the <code class="literal">SQL</code> keyword is omitted. The paragraphs about
+ the use cases of the <code class="literal">INTO</code> and <code class="literal">USING</code>
+ keywords in <a class="xref" href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS" title="36.7.1. Named SQL Descriptor Areas">Section 36.7.1</a> also apply here with an addition.
+ In a <code class="command">DESCRIBE</code> statement the <code class="literal">DESCRIPTOR</code>
+ keyword can be completely omitted if the <code class="literal">INTO</code> keyword is used:
+</p><pre class="programlisting">
+EXEC SQL DESCRIBE prepared_statement INTO mysqlda;
+</pre><p>
+ </p><div class="procedure"><p>
+ The general flow of a program that uses SQLDA is:
+ </p><ol class="procedure" type="1"><li class="step"><p>Prepare a query, and declare a cursor for it.</p></li><li class="step"><p>Declare an SQLDA for the result rows.</p></li><li class="step"><p>Declare an SQLDA for the input parameters, and initialize them (memory allocation, parameter settings).</p></li><li class="step"><p>Open a cursor with the input SQLDA.</p></li><li class="step"><p>Fetch rows from the cursor, and store them into an output SQLDA.</p></li><li class="step"><p>Read values from the output SQLDA into the host variables (with conversion if necessary).</p></li><li class="step"><p>Close the cursor.</p></li><li class="step"><p>Free the memory area allocated for the input SQLDA.</p></li></ol></div><div class="sect3" id="id-1.7.5.13.4.4"><div class="titlepage"><div><div><h4 class="title">36.7.2.1. SQLDA Data Structure</h4></div></div></div><p>
+ SQLDA uses three data structure
+ types: <code class="type">sqlda_t</code>, <code class="type">sqlvar_t</code>,
+ and <code class="type">struct sqlname</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ PostgreSQL's SQLDA has a similar data structure to the one in
+ IBM DB2 Universal Database, so some technical information on
+ DB2's SQLDA could help understanding PostgreSQL's one better.
+ </p></div><div class="sect4" id="ECPG-SQLDA-SQLDA"><div class="titlepage"><div><div><h5 class="title">36.7.2.1.1. sqlda_t Structure</h5></div></div></div><p>
+ The structure type <code class="type">sqlda_t</code> is the type of the
+ actual SQLDA. It holds one record. And two or
+ more <code class="type">sqlda_t</code> structures can be connected in a
+ linked list with the pointer in
+ the <code class="structfield">desc_next</code> field, thus
+ representing an ordered collection of rows. So, when two or
+ more rows are fetched, the application can read them by
+ following the <code class="structfield">desc_next</code> pointer in
+ each <code class="type">sqlda_t</code> node.
+ </p><p>
+ The definition of <code class="type">sqlda_t</code> is:
+</p><pre class="programlisting">
+struct sqlda_struct
+{
+ char sqldaid[8];
+ long sqldabc;
+ short sqln;
+ short sqld;
+ struct sqlda_struct *desc_next;
+ struct sqlvar_struct sqlvar[1];
+};
+
+typedef struct sqlda_struct sqlda_t;
+</pre><p>
+
+ The meaning of the fields is:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">sqldaid</code></span></dt><dd><p>
+ It contains the literal string <code class="literal">"SQLDA "</code>.
+ </p></dd><dt><span class="term"><code class="literal">sqldabc</code></span></dt><dd><p>
+ It contains the size of the allocated space in bytes.
+ </p></dd><dt><span class="term"><code class="literal">sqln</code></span></dt><dd><p>
+ It contains the number of input parameters for a parameterized query in
+ case it's passed into <code class="command">OPEN</code>, <code class="command">DECLARE</code> or
+ <code class="command">EXECUTE</code> statements using the <code class="literal">USING</code>
+ keyword. In case it's used as output of <code class="command">SELECT</code>,
+ <code class="command">EXECUTE</code> or <code class="command">FETCH</code> statements,
+ its value is the same as <code class="literal">sqld</code>
+ statement
+ </p></dd><dt><span class="term"><code class="literal">sqld</code></span></dt><dd><p>
+ It contains the number of fields in a result set.
+ </p></dd><dt><span class="term"><code class="literal">desc_next</code></span></dt><dd><p>
+ If the query returns more than one record, multiple linked
+ SQLDA structures are returned, and <code class="literal">desc_next</code> holds
+ a pointer to the next entry in the list.
+ </p></dd><dt><span class="term"><code class="literal">sqlvar</code></span></dt><dd><p>
+ This is the array of the columns in the result set.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect4" id="ECPG-SQLDA-SQLVAR"><div class="titlepage"><div><div><h5 class="title">36.7.2.1.2. sqlvar_t Structure</h5></div></div></div><p>
+ The structure type <code class="type">sqlvar_t</code> holds a column value
+ and metadata such as type and length. The definition of the type
+ is:
+
+</p><pre class="programlisting">
+struct sqlvar_struct
+{
+ short sqltype;
+ short sqllen;
+ char *sqldata;
+ short *sqlind;
+ struct sqlname sqlname;
+};
+
+typedef struct sqlvar_struct sqlvar_t;
+</pre><p>
+
+ The meaning of the fields is:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">sqltype</code></span></dt><dd><p>
+ Contains the type identifier of the field. For values,
+ see <code class="literal">enum ECPGttype</code> in <code class="literal">ecpgtype.h</code>.
+ </p></dd><dt><span class="term"><code class="literal">sqllen</code></span></dt><dd><p>
+ Contains the binary length of the field. e.g., 4 bytes for <code class="type">ECPGt_int</code>.
+ </p></dd><dt><span class="term"><code class="literal">sqldata</code></span></dt><dd><p>
+ Points to the data. The format of the data is described
+ in <a class="xref" href="ecpg-variables.html#ECPG-VARIABLES-TYPE-MAPPING" title="36.4.4. Type Mapping">Section 36.4.4</a>.
+ </p></dd><dt><span class="term"><code class="literal">sqlind</code></span></dt><dd><p>
+ Points to the null indicator. 0 means not null, -1 means
+ null.
+ </p></dd><dt><span class="term"><code class="literal">sqlname</code></span></dt><dd><p>
+ The name of the field.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect4" id="ECPG-SQLDA-SQLNAME"><div class="titlepage"><div><div><h5 class="title">36.7.2.1.3. struct sqlname Structure</h5></div></div></div><p>
+ A <code class="type">struct sqlname</code> structure holds a column name. It
+ is used as a member of the <code class="type">sqlvar_t</code> structure. The
+ definition of the structure is:
+</p><pre class="programlisting">
+#define NAMEDATALEN 64
+
+struct sqlname
+{
+ short length;
+ char data[NAMEDATALEN];
+};
+</pre><p>
+ The meaning of the fields is:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">length</code></span></dt><dd><p>
+ Contains the length of the field name.
+ </p></dd><dt><span class="term"><code class="literal">data</code></span></dt><dd><p>
+ Contains the actual field name.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="sect3" id="ECPG-SQLDA-OUTPUT"><div class="titlepage"><div><div><h4 class="title">36.7.2.2. Retrieving a Result Set Using an SQLDA</h4></div></div></div><div class="procedure"><p>
+ The general steps to retrieve a query result set through an
+ SQLDA are:
+ </p><ol class="procedure" type="1"><li class="step"><p>Declare an <code class="type">sqlda_t</code> structure to receive the result set.</p></li><li class="step"><p>Execute <code class="command">FETCH</code>/<code class="command">EXECUTE</code>/<code class="command">DESCRIBE</code> commands to process a query specifying the declared SQLDA.</p></li><li class="step"><p>Check the number of records in the result set by looking at <code class="structfield">sqln</code>, a member of the <code class="type">sqlda_t</code> structure.</p></li><li class="step"><p>Get the values of each column from <code class="literal">sqlvar[0]</code>, <code class="literal">sqlvar[1]</code>, etc., members of the <code class="type">sqlda_t</code> structure.</p></li><li class="step"><p>Go to next row (<code class="type">sqlda_t</code> structure) by following the <code class="structfield">desc_next</code> pointer, a member of the <code class="type">sqlda_t</code> structure.</p></li><li class="step"><p>Repeat above as you need.</p></li></ol></div><p>
+ Here is an example retrieving a result set through an SQLDA.
+ </p><p>
+ First, declare a <code class="type">sqlda_t</code> structure to receive the result set.
+</p><pre class="programlisting">
+sqlda_t *sqlda1;
+</pre><p>
+ </p><p>
+ Next, specify the SQLDA in a command. This is
+ a <code class="command">FETCH</code> command example.
+</p><pre class="programlisting">
+EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
+</pre><p>
+ </p><p>
+ Run a loop following the linked list to retrieve the rows.
+</p><pre class="programlisting">
+sqlda_t *cur_sqlda;
+
+for (cur_sqlda = sqlda1;
+ cur_sqlda != NULL;
+ cur_sqlda = cur_sqlda-&gt;desc_next)
+{
+ ...
+}
+</pre><p>
+ </p><p>
+ Inside the loop, run another loop to retrieve each column data
+ (<code class="type">sqlvar_t</code> structure) of the row.
+</p><pre class="programlisting">
+for (i = 0; i &lt; cur_sqlda-&gt;sqld; i++)
+{
+ sqlvar_t v = cur_sqlda-&gt;sqlvar[i];
+ char *sqldata = v.sqldata;
+ short sqllen = v.sqllen;
+ ...
+}
+</pre><p>
+ </p><p>
+ To get a column value, check the <code class="structfield">sqltype</code> value,
+ a member of the <code class="type">sqlvar_t</code> structure. Then, switch
+ to an appropriate way, depending on the column type, to copy
+ data from the <code class="structfield">sqlvar</code> field to a host variable.
+</p><pre class="programlisting">
+char var_buf[1024];
+
+switch (v.sqltype)
+{
+ case ECPGt_char:
+ memset(&amp;var_buf, 0, sizeof(var_buf));
+ memcpy(&amp;var_buf, sqldata, (sizeof(var_buf) &lt;= sqllen ? sizeof(var_buf) - 1 : sqllen));
+ break;
+
+ case ECPGt_int: /* integer */
+ memcpy(&amp;intval, sqldata, sqllen);
+ snprintf(var_buf, sizeof(var_buf), "%d", intval);
+ break;
+
+ ...
+}
+</pre><p>
+ </p></div><div class="sect3" id="ECPG-SQLDA-INPUT"><div class="titlepage"><div><div><h4 class="title">36.7.2.3. Passing Query Parameters Using an SQLDA</h4></div></div></div><div class="procedure"><p>
+ The general steps to use an SQLDA to pass input
+ parameters to a prepared query are:
+ </p><ol class="procedure" type="1"><li class="step"><p>Create a prepared query (prepared statement)</p></li><li class="step"><p>Declare an sqlda_t structure as an input SQLDA.</p></li><li class="step"><p>Allocate memory area (as sqlda_t structure) for the input SQLDA.</p></li><li class="step"><p>Set (copy) input values in the allocated memory.</p></li><li class="step"><p>Open a cursor with specifying the input SQLDA.</p></li></ol></div><p>
+ Here is an example.
+ </p><p>
+ First, create a prepared statement.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+char query[1024] = "SELECT d.oid, * FROM pg_database d, pg_stat_database s WHERE d.oid = s.datid AND (d.datname = ? OR d.oid = ?)";
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL PREPARE stmt1 FROM :query;
+</pre><p>
+ </p><p>
+ Next, allocate memory for an SQLDA, and set the number of input
+ parameters in <code class="structfield">sqln</code>, a member variable of
+ the <code class="type">sqlda_t</code> structure. When two or more input
+ parameters are required for the prepared query, the application
+ has to allocate additional memory space which is calculated by
+ (nr. of params - 1) * sizeof(sqlvar_t). The example shown here
+ allocates memory space for two input parameters.
+</p><pre class="programlisting">
+sqlda_t *sqlda2;
+
+sqlda2 = (sqlda_t *) malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
+memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
+
+sqlda2-&gt;sqln = 2; /* number of input variables */
+</pre><p>
+ </p><p>
+ After memory allocation, store the parameter values into the
+ <code class="literal">sqlvar[]</code> array. (This is same array used for
+ retrieving column values when the SQLDA is receiving a result
+ set.) In this example, the input parameters
+ are <code class="literal">"postgres"</code>, having a string type,
+ and <code class="literal">1</code>, having an integer type.
+</p><pre class="programlisting">
+sqlda2-&gt;sqlvar[0].sqltype = ECPGt_char;
+sqlda2-&gt;sqlvar[0].sqldata = "postgres";
+sqlda2-&gt;sqlvar[0].sqllen = 8;
+
+int intval = 1;
+sqlda2-&gt;sqlvar[1].sqltype = ECPGt_int;
+sqlda2-&gt;sqlvar[1].sqldata = (char *) &amp;intval;
+sqlda2-&gt;sqlvar[1].sqllen = sizeof(intval);
+</pre><p>
+ </p><p>
+ By opening a cursor and specifying the SQLDA that was set up
+ beforehand, the input parameters are passed to the prepared
+ statement.
+</p><pre class="programlisting">
+EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
+</pre><p>
+ </p><p>
+ Finally, after using input SQLDAs, the allocated memory space
+ must be freed explicitly, unlike SQLDAs used for receiving query
+ results.
+</p><pre class="programlisting">
+free(sqlda2);
+</pre><p>
+ </p></div><div class="sect3" id="ECPG-SQLDA-EXAMPLE"><div class="titlepage"><div><div><h4 class="title">36.7.2.4. A Sample Application Using SQLDA</h4></div></div></div><p>
+ Here is an example program, which describes how to fetch access
+ statistics of the databases, specified by the input parameters,
+ from the system catalogs.
+ </p><p>
+ This application joins two system tables, pg_database and
+ pg_stat_database on the database OID, and also fetches and shows
+ the database statistics which are retrieved by two input
+ parameters (a database <code class="literal">postgres</code>, and OID <code class="literal">1</code>).
+ </p><p>
+ First, declare an SQLDA for input and an SQLDA for output.
+</p><pre class="programlisting">
+EXEC SQL include sqlda.h;
+
+sqlda_t *sqlda1; /* an output descriptor */
+sqlda_t *sqlda2; /* an input descriptor */
+</pre><p>
+ </p><p>
+ Next, connect to the database, prepare a statement, and declare a
+ cursor for the prepared statement.
+</p><pre class="programlisting">
+int
+main(void)
+{
+ EXEC SQL BEGIN DECLARE SECTION;
+ char query[1024] = "SELECT d.oid,* FROM pg_database d, pg_stat_database s WHERE d.oid=s.datid AND ( d.datname=? OR d.oid=? )";
+ EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO testdb AS con1 USER testuser;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ EXEC SQL PREPARE stmt1 FROM :query;
+ EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
+</pre><p>
+ </p><p>
+ Next, put some values in the input SQLDA for the input
+ parameters. Allocate memory for the input SQLDA, and set the
+ number of input parameters to <code class="literal">sqln</code>. Store
+ type, value, and value length into <code class="literal">sqltype</code>,
+ <code class="literal">sqldata</code>, and <code class="literal">sqllen</code> in the
+ <code class="literal">sqlvar</code> structure.
+
+</p><pre class="programlisting">
+ /* Create SQLDA structure for input parameters. */
+ sqlda2 = (sqlda_t *) malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
+ memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
+ sqlda2-&gt;sqln = 2; /* number of input variables */
+
+ sqlda2-&gt;sqlvar[0].sqltype = ECPGt_char;
+ sqlda2-&gt;sqlvar[0].sqldata = "postgres";
+ sqlda2-&gt;sqlvar[0].sqllen = 8;
+
+ intval = 1;
+ sqlda2-&gt;sqlvar[1].sqltype = ECPGt_int;
+ sqlda2-&gt;sqlvar[1].sqldata = (char *)&amp;intval;
+ sqlda2-&gt;sqlvar[1].sqllen = sizeof(intval);
+</pre><p>
+ </p><p>
+ After setting up the input SQLDA, open a cursor with the input
+ SQLDA.
+
+</p><pre class="programlisting">
+ /* Open a cursor with input parameters. */
+ EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
+</pre><p>
+ </p><p>
+ Fetch rows into the output SQLDA from the opened cursor.
+ (Generally, you have to call <code class="command">FETCH</code> repeatedly
+ in the loop, to fetch all rows in the result set.)
+</p><pre class="programlisting">
+ while (1)
+ {
+ sqlda_t *cur_sqlda;
+
+ /* Assign descriptor to the cursor */
+ EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
+</pre><p>
+ </p><p>
+ Next, retrieve the fetched records from the SQLDA, by following
+ the linked list of the <code class="type">sqlda_t</code> structure.
+</p><pre class="programlisting">
+ for (cur_sqlda = sqlda1 ;
+ cur_sqlda != NULL ;
+ cur_sqlda = cur_sqlda-&gt;desc_next)
+ {
+ ...
+</pre><p>
+ </p><p>
+ Read each columns in the first record. The number of columns is
+ stored in <code class="structfield">sqld</code>, the actual data of the first
+ column is stored in <code class="literal">sqlvar[0]</code>, both members of
+ the <code class="type">sqlda_t</code> structure.
+
+</p><pre class="programlisting">
+ /* Print every column in a row. */
+ for (i = 0; i &lt; sqlda1-&gt;sqld; i++)
+ {
+ sqlvar_t v = sqlda1-&gt;sqlvar[i];
+ char *sqldata = v.sqldata;
+ short sqllen = v.sqllen;
+
+ strncpy(name_buf, v.sqlname.data, v.sqlname.length);
+ name_buf[v.sqlname.length] = '\0';
+</pre><p>
+ </p><p>
+ Now, the column data is stored in the variable <code class="varname">v</code>.
+ Copy every datum into host variables, looking
+ at <code class="literal">v.sqltype</code> for the type of the column.
+</p><pre class="programlisting">
+ switch (v.sqltype) {
+ int intval;
+ double doubleval;
+ unsigned long long int longlongval;
+
+ case ECPGt_char:
+ memset(&amp;var_buf, 0, sizeof(var_buf));
+ memcpy(&amp;var_buf, sqldata, (sizeof(var_buf) &lt;= sqllen ? sizeof(var_buf)-1 : sqllen));
+ break;
+
+ case ECPGt_int: /* integer */
+ memcpy(&amp;intval, sqldata, sqllen);
+ snprintf(var_buf, sizeof(var_buf), "%d", intval);
+ break;
+
+ ...
+
+ default:
+ ...
+ }
+
+ printf("%s = %s (type: %d)\n", name_buf, var_buf, v.sqltype);
+ }
+</pre><p>
+ </p><p>
+ Close the cursor after processing all of records, and disconnect
+ from the database.
+</p><pre class="programlisting">
+ EXEC SQL CLOSE cur1;
+ EXEC SQL COMMIT;
+
+ EXEC SQL DISCONNECT ALL;
+</pre><p>
+ </p><p>
+ The whole program is shown
+ in <a class="xref" href="ecpg-descriptors.html#ECPG-SQLDA-EXAMPLE-EXAMPLE" title="Example 36.1. Example SQLDA Program">Example 36.1</a>.
+ </p><div class="example" id="ECPG-SQLDA-EXAMPLE-EXAMPLE"><p class="title"><strong>Example 36.1. Example SQLDA Program</strong></p><div class="example-contents"><pre class="programlisting">
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdio.h&gt;
+#include &lt;unistd.h&gt;
+
+EXEC SQL include sqlda.h;
+
+sqlda_t *sqlda1; /* descriptor for output */
+sqlda_t *sqlda2; /* descriptor for input */
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+EXEC SQL WHENEVER SQLERROR STOP;
+
+int
+main(void)
+{
+ EXEC SQL BEGIN DECLARE SECTION;
+ char query[1024] = "SELECT d.oid,* FROM pg_database d, pg_stat_database s WHERE d.oid=s.datid AND ( d.datname=? OR d.oid=? )";
+
+ int intval;
+ unsigned long long int longlongval;
+ EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO uptimedb AS con1 USER uptime;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ EXEC SQL PREPARE stmt1 FROM :query;
+ EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
+
+ /* Create an SQLDA structure for an input parameter */
+ sqlda2 = (sqlda_t *)malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
+ memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
+ sqlda2-&gt;sqln = 2; /* a number of input variables */
+
+ sqlda2-&gt;sqlvar[0].sqltype = ECPGt_char;
+ sqlda2-&gt;sqlvar[0].sqldata = "postgres";
+ sqlda2-&gt;sqlvar[0].sqllen = 8;
+
+ intval = 1;
+ sqlda2-&gt;sqlvar[1].sqltype = ECPGt_int;
+ sqlda2-&gt;sqlvar[1].sqldata = (char *) &amp;intval;
+ sqlda2-&gt;sqlvar[1].sqllen = sizeof(intval);
+
+ /* Open a cursor with input parameters. */
+ EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
+
+ while (1)
+ {
+ sqlda_t *cur_sqlda;
+
+ /* Assign descriptor to the cursor */
+ EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
+
+ for (cur_sqlda = sqlda1 ;
+ cur_sqlda != NULL ;
+ cur_sqlda = cur_sqlda-&gt;desc_next)
+ {
+ int i;
+ char name_buf[1024];
+ char var_buf[1024];
+
+ /* Print every column in a row. */
+ for (i=0 ; i&lt;cur_sqlda-&gt;sqld ; i++)
+ {
+ sqlvar_t v = cur_sqlda-&gt;sqlvar[i];
+ char *sqldata = v.sqldata;
+ short sqllen = v.sqllen;
+
+ strncpy(name_buf, v.sqlname.data, v.sqlname.length);
+ name_buf[v.sqlname.length] = '\0';
+
+ switch (v.sqltype)
+ {
+ case ECPGt_char:
+ memset(&amp;var_buf, 0, sizeof(var_buf));
+ memcpy(&amp;var_buf, sqldata, (sizeof(var_buf)&lt;=sqllen ? sizeof(var_buf)-1 : sqllen) );
+ break;
+
+ case ECPGt_int: /* integer */
+ memcpy(&amp;intval, sqldata, sqllen);
+ snprintf(var_buf, sizeof(var_buf), "%d", intval);
+ break;
+
+ case ECPGt_long_long: /* bigint */
+ memcpy(&amp;longlongval, sqldata, sqllen);
+ snprintf(var_buf, sizeof(var_buf), "%lld", longlongval);
+ break;
+
+ default:
+ {
+ int i;
+ memset(var_buf, 0, sizeof(var_buf));
+ for (i = 0; i &lt; sqllen; i++)
+ {
+ char tmpbuf[16];
+ snprintf(tmpbuf, sizeof(tmpbuf), "%02x ", (unsigned char) sqldata[i]);
+ strncat(var_buf, tmpbuf, sizeof(var_buf));
+ }
+ }
+ break;
+ }
+
+ printf("%s = %s (type: %d)\n", name_buf, var_buf, v.sqltype);
+ }
+
+ printf("\n");
+ }
+ }
+
+ EXEC SQL CLOSE cur1;
+ EXEC SQL COMMIT;
+
+ EXEC SQL DISCONNECT ALL;
+
+ return 0;
+}
+</pre><p>
+ The output of this example should look something like the
+ following (some numbers will vary).
+ </p><pre class="screen">
+oid = 1 (type: 1)
+datname = template1 (type: 1)
+datdba = 10 (type: 1)
+encoding = 0 (type: 5)
+datistemplate = t (type: 1)
+datallowconn = t (type: 1)
+datconnlimit = -1 (type: 5)
+datfrozenxid = 379 (type: 1)
+dattablespace = 1663 (type: 1)
+datconfig = (type: 1)
+datacl = {=c/uptime,uptime=CTc/uptime} (type: 1)
+datid = 1 (type: 1)
+datname = template1 (type: 1)
+numbackends = 0 (type: 5)
+xact_commit = 113606 (type: 9)
+xact_rollback = 0 (type: 9)
+blks_read = 130 (type: 9)
+blks_hit = 7341714 (type: 9)
+tup_returned = 38262679 (type: 9)
+tup_fetched = 1836281 (type: 9)
+tup_inserted = 0 (type: 9)
+tup_updated = 0 (type: 9)
+tup_deleted = 0 (type: 9)
+
+oid = 11511 (type: 1)
+datname = postgres (type: 1)
+datdba = 10 (type: 1)
+encoding = 0 (type: 5)
+datistemplate = f (type: 1)
+datallowconn = t (type: 1)
+datconnlimit = -1 (type: 5)
+datfrozenxid = 379 (type: 1)
+dattablespace = 1663 (type: 1)
+datconfig = (type: 1)
+datacl = (type: 1)
+datid = 11511 (type: 1)
+datname = postgres (type: 1)
+numbackends = 0 (type: 5)
+xact_commit = 221069 (type: 9)
+xact_rollback = 18 (type: 9)
+blks_read = 1176 (type: 9)
+blks_hit = 13943750 (type: 9)
+tup_returned = 77410091 (type: 9)
+tup_fetched = 3253694 (type: 9)
+tup_inserted = 0 (type: 9)
+tup_updated = 0 (type: 9)
+tup_deleted = 0 (type: 9)
+</pre></div></div><br class="example-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-errors.html" title="36.8. Error Handling">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.6. pgtypes Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.8. Error Handling</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-develop.html b/doc/src/sgml/html/ecpg-develop.html
new file mode 100644
index 0000000..a643bdb
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-develop.html
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.17. Internals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode" /><link rel="next" href="information-schema.html" title="Chapter 37. The Information Schema" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.17. Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="information-schema.html" title="Chapter 37. The Information Schema">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-DEVELOP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.17. Internals</h2></div></div></div><p>
+ This section explains how <span class="application">ECPG</span> works
+ internally. This information can occasionally be useful to help
+ users understand how to use <span class="application">ECPG</span>.
+ </p><p>
+ The first four lines written by <code class="command">ecpg</code> to the
+ output are fixed lines. Two are comments and two are include
+ lines necessary to interface to the library. Then the
+ preprocessor reads through the file and writes output. Normally
+ it just echoes everything to the output.
+ </p><p>
+ When it sees an <code class="command">EXEC SQL</code> statement, it
+ intervenes and changes it. The command starts with <code class="command">EXEC
+ SQL</code> and ends with <code class="command">;</code>. Everything in
+ between is treated as an <acronym class="acronym">SQL</acronym> statement and
+ parsed for variable substitution.
+ </p><p>
+ Variable substitution occurs when a symbol starts with a colon
+ (<code class="literal">:</code>). The variable with that name is looked up
+ among the variables that were previously declared within a
+ <code class="literal">EXEC SQL DECLARE</code> section.
+ </p><p>
+ The most important function in the library is
+ <code class="function">ECPGdo</code>, which takes care of executing most
+ commands. It takes a variable number of arguments. This can easily
+ add up to 50 or so arguments, and we hope this will not be a
+ problem on any platform.
+ </p><p>
+ The arguments are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">A line number</span></dt><dd><p>
+ This is the line number of the original line; used in error
+ messages only.
+ </p></dd><dt><span class="term">A string</span></dt><dd><p>
+ This is the <acronym class="acronym">SQL</acronym> command that is to be issued.
+ It is modified by the input variables, i.e., the variables that
+ where not known at compile time but are to be entered in the
+ command. Where the variables should go the string contains
+ <code class="literal">?</code>.
+ </p></dd><dt><span class="term">Input variables</span></dt><dd><p>
+ Every input variable causes ten arguments to be created. (See below.)
+ </p></dd><dt><span class="term"><em class="parameter"><code>ECPGt_EOIT</code></em></span></dt><dd><p>
+ An <code class="type">enum</code> telling that there are no more input
+ variables.
+ </p></dd><dt><span class="term">Output variables</span></dt><dd><p>
+ Every output variable causes ten arguments to be created.
+ (See below.) These variables are filled by the function.
+ </p></dd><dt><span class="term"><em class="parameter"><code>ECPGt_EORT</code></em></span></dt><dd><p>
+ An <code class="type">enum</code> telling that there are no more variables.
+ </p></dd></dl></div><p>
+ </p><p>
+ For every variable that is part of the <acronym class="acronym">SQL</acronym>
+ command, the function gets ten arguments:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ The type as a special symbol.
+ </p></li><li class="listitem"><p>
+ A pointer to the value or a pointer to the pointer.
+ </p></li><li class="listitem"><p>
+ The size of the variable if it is a <code class="type">char</code> or <code class="type">varchar</code>.
+ </p></li><li class="listitem"><p>
+ The number of elements in the array (for array fetches).
+ </p></li><li class="listitem"><p>
+ The offset to the next element in the array (for array fetches).
+ </p></li><li class="listitem"><p>
+ The type of the indicator variable as a special symbol.
+ </p></li><li class="listitem"><p>
+ A pointer to the indicator variable.
+ </p></li><li class="listitem"><p>
+ 0
+ </p></li><li class="listitem"><p>
+ The number of elements in the indicator array (for array fetches).
+ </p></li><li class="listitem"><p>
+ The offset to the next element in the indicator array (for
+ array fetches).
+ </p></li></ol></div><p>
+ </p><p>
+ Note that not all SQL commands are treated in this way. For
+ instance, an open cursor statement like:
+</p><pre class="programlisting">
+EXEC SQL OPEN <em class="replaceable"><code>cursor</code></em>;
+</pre><p>
+ is not copied to the output. Instead, the cursor's
+ <code class="command">DECLARE</code> command is used at the position of the <code class="command">OPEN</code> command
+ because it indeed opens the cursor.
+ </p><p>
+ Here is a complete example describing the output of the
+ preprocessor of a file <code class="filename">foo.pgc</code> (details might
+ change with each particular version of the preprocessor):
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int index;
+int result;
+EXEC SQL END DECLARE SECTION;
+...
+EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;
+</pre><p>
+ is translated into:
+</p><pre class="programlisting">
+/* Processed by ecpg (2.6.0) */
+/* These two include files are added by the preprocessor */
+#include &lt;ecpgtype.h&gt;;
+#include &lt;ecpglib.h&gt;;
+
+/* exec sql begin declare section */
+
+#line 1 "foo.pgc"
+
+ int index;
+ int result;
+/* exec sql end declare section */
+...
+ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ? ",
+ ECPGt_int,&amp;(index),1L,1L,sizeof(int),
+ ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
+ ECPGt_int,&amp;(result),1L,1L,sizeof(int),
+ ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
+#line 147 "foo.pgc"
+
+</pre><p>
+ (The indentation here is added for readability and not
+ something the preprocessor does.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="information-schema.html" title="Chapter 37. The Information Schema">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.16. <span class="productname">Oracle</span> Compatibility Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. The Information Schema</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-dynamic.html b/doc/src/sgml/html/ecpg-dynamic.html
new file mode 100644
index 0000000..fb9b2f6
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-dynamic.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.5. Dynamic SQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-variables.html" title="36.4. Using Host Variables" /><link rel="next" href="ecpg-pgtypes.html" title="36.6. pgtypes Library" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.5. Dynamic SQL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-variables.html" title="36.4. Using Host Variables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-DYNAMIC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.5. Dynamic SQL</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-WITHOUT-RESULT">36.5.1. Executing Statements without a Result Set</a></span></dt><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-INPUT">36.5.2. Executing a Statement with Input Parameters</a></span></dt><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-WITH-RESULT">36.5.3. Executing a Statement with a Result Set</a></span></dt></dl></div><p>
+ In many cases, the particular SQL statements that an application
+ has to execute are known at the time the application is written.
+ In some cases, however, the SQL statements are composed at run time
+ or provided by an external source. In these cases you cannot embed
+ the SQL statements directly into the C source code, but there is a
+ facility that allows you to call arbitrary SQL statements that you
+ provide in a string variable.
+ </p><div class="sect2" id="ECPG-DYNAMIC-WITHOUT-RESULT"><div class="titlepage"><div><div><h3 class="title">36.5.1. Executing Statements without a Result Set</h3></div></div></div><p>
+ The simplest way to execute an arbitrary SQL statement is to use
+ the command <code class="command">EXECUTE IMMEDIATE</code>. For example:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+const char *stmt = "CREATE TABLE test1 (...);";
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL EXECUTE IMMEDIATE :stmt;
+</pre><p>
+ <code class="command">EXECUTE IMMEDIATE</code> can be used for SQL
+ statements that do not return a result set (e.g.,
+ DDL, <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>). You cannot execute statements that
+ retrieve data (e.g., <code class="command">SELECT</code>) this way. The
+ next section describes how to do that.
+ </p></div><div class="sect2" id="ECPG-DYNAMIC-INPUT"><div class="titlepage"><div><div><h3 class="title">36.5.2. Executing a Statement with Input Parameters</h3></div></div></div><p>
+ A more powerful way to execute arbitrary SQL statements is to
+ prepare them once and execute the prepared statement as often as
+ you like. It is also possible to prepare a generalized version of
+ a statement and then execute specific versions of it by
+ substituting parameters. When preparing the statement, write
+ question marks where you want to substitute parameters later. For
+ example:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL PREPARE mystmt FROM :stmt;
+ ...
+EXEC SQL EXECUTE mystmt USING 42, 'foobar';
+</pre><p>
+ </p><p>
+ When you don't need the prepared statement anymore, you should
+ deallocate it:
+</p><pre class="programlisting">
+EXEC SQL DEALLOCATE PREPARE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-DYNAMIC-WITH-RESULT"><div class="titlepage"><div><div><h3 class="title">36.5.3. Executing a Statement with a Result Set</h3></div></div></div><p>
+ To execute an SQL statement with a single result row,
+ <code class="command">EXECUTE</code> can be used. To save the result, add
+ an <code class="literal">INTO</code> clause.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+const char *stmt = "SELECT a, b, c FROM test1 WHERE a &gt; ?";
+int v1, v2;
+VARCHAR v3[50];
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL PREPARE mystmt FROM :stmt;
+ ...
+EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37;
+
+</pre><p>
+ An <code class="command">EXECUTE</code> command can have an
+ <code class="literal">INTO</code> clause, a <code class="literal">USING</code> clause,
+ both, or neither.
+ </p><p>
+ If a query is expected to return more than one result row, a
+ cursor should be used, as in the following example.
+ (See <a class="xref" href="ecpg-commands.html#ECPG-CURSORS" title="36.3.2. Using Cursors">Section 36.3.2</a> for more details about the
+ cursor.)
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+char dbaname[128];
+char datname[128];
+char *stmt = "SELECT u.usename as dbaname, d.datname "
+ " FROM pg_database d, pg_user u "
+ " WHERE d.datdba = u.usesysid";
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL CONNECT TO testdb AS con1 USER testuser;
+EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+EXEC SQL PREPARE stmt1 FROM :stmt;
+
+EXEC SQL DECLARE cursor1 CURSOR FOR stmt1;
+EXEC SQL OPEN cursor1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ EXEC SQL FETCH cursor1 INTO :dbaname,:datname;
+ printf("dbaname=%s, datname=%s\n", dbaname, datname);
+}
+
+EXEC SQL CLOSE cursor1;
+
+EXEC SQL COMMIT;
+EXEC SQL DISCONNECT ALL;
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-variables.html" title="36.4. Using Host Variables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.4. Using Host Variables </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.6. pgtypes Library</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-errors.html b/doc/src/sgml/html/ecpg-errors.html
new file mode 100644
index 0000000..d1d4486
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-errors.html
@@ -0,0 +1,441 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.8. Error Handling</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas" /><link rel="next" href="ecpg-preproc.html" title="36.9. Preprocessor Directives" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.8. Error Handling</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-preproc.html" title="36.9. Preprocessor Directives">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-ERRORS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.8. Error Handling</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-WHENEVER">36.8.1. Setting Callbacks</a></span></dt><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-SQLCA">36.8.2. sqlca</a></span></dt><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-SQLSTATE-SQLCODE">36.8.3. <code class="literal">SQLSTATE</code> vs. <code class="literal">SQLCODE</code></a></span></dt></dl></div><p>
+ This section describes how you can handle exceptional conditions
+ and warnings in an embedded SQL program. There are two
+ nonexclusive facilities for this.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+ Callbacks can be configured to handle warning and error
+ conditions using the <code class="literal">WHENEVER</code> command.
+ </li><li class="listitem">
+ Detailed information about the error or warning can be obtained
+ from the <code class="varname">sqlca</code> variable.
+ </li></ul></div><p>
+ </p><div class="sect2" id="ECPG-WHENEVER"><div class="titlepage"><div><div><h3 class="title">36.8.1. Setting Callbacks</h3></div></div></div><p>
+ One simple method to catch errors and warnings is to set a
+ specific action to be executed whenever a particular condition
+ occurs. In general:
+</p><pre class="programlisting">
+EXEC SQL WHENEVER <em class="replaceable"><code>condition</code></em> <em class="replaceable"><code>action</code></em>;
+</pre><p>
+ </p><p>
+ <em class="replaceable"><code>condition</code></em> can be one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SQLERROR</code></span></dt><dd><p>
+ The specified action is called whenever an error occurs during
+ the execution of an SQL statement.
+ </p></dd><dt><span class="term"><code class="literal">SQLWARNING</code></span></dt><dd><p>
+ The specified action is called whenever a warning occurs
+ during the execution of an SQL statement.
+ </p></dd><dt><span class="term"><code class="literal">NOT FOUND</code></span></dt><dd><p>
+ The specified action is called whenever an SQL statement
+ retrieves or affects zero rows. (This condition is not an
+ error, but you might be interested in handling it specially.)
+ </p></dd></dl></div><p>
+ </p><p>
+ <em class="replaceable"><code>action</code></em> can be one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CONTINUE</code></span></dt><dd><p>
+ This effectively means that the condition is ignored. This is
+ the default.
+ </p></dd><dt><span class="term"><code class="literal">GOTO <em class="replaceable"><code>label</code></em></code><br /></span><span class="term"><code class="literal">GO TO <em class="replaceable"><code>label</code></em></code></span></dt><dd><p>
+ Jump to the specified label (using a C <code class="literal">goto</code>
+ statement).
+ </p></dd><dt><span class="term"><code class="literal">SQLPRINT</code></span></dt><dd><p>
+ Print a message to standard error. This is useful for simple
+ programs or during prototyping. The details of the message
+ cannot be configured.
+ </p></dd><dt><span class="term"><code class="literal">STOP</code></span></dt><dd><p>
+ Call <code class="literal">exit(1)</code>, which will terminate the
+ program.
+ </p></dd><dt><span class="term"><code class="literal">DO BREAK</code></span></dt><dd><p>
+ Execute the C statement <code class="literal">break</code>. This should
+ only be used in loops or <code class="literal">switch</code> statements.
+ </p></dd><dt><span class="term"><code class="literal">DO CONTINUE</code></span></dt><dd><p>
+ Execute the C statement <code class="literal">continue</code>. This should
+ only be used in loops statements. if executed, will cause the flow
+ of control to return to the top of the loop.
+ </p></dd><dt><span class="term"><code class="literal">CALL <em class="replaceable"><code>name</code></em> (<em class="replaceable"><code>args</code></em>)</code><br /></span><span class="term"><code class="literal">DO <em class="replaceable"><code>name</code></em> (<em class="replaceable"><code>args</code></em>)</code></span></dt><dd><p>
+ Call the specified C functions with the specified arguments. (This
+ use is different from the meaning of <code class="literal">CALL</code>
+ and <code class="literal">DO</code> in the normal PostgreSQL grammar.)
+ </p></dd></dl></div><p>
+
+ The SQL standard only provides for the actions
+ <code class="literal">CONTINUE</code> and <code class="literal">GOTO</code> (and
+ <code class="literal">GO TO</code>).
+ </p><p>
+ Here is an example that you might want to use in a simple program.
+ It prints a simple message when a warning occurs and aborts the
+ program when an error happens:
+</p><pre class="programlisting">
+EXEC SQL WHENEVER SQLWARNING SQLPRINT;
+EXEC SQL WHENEVER SQLERROR STOP;
+</pre><p>
+ </p><p>
+ The statement <code class="literal">EXEC SQL WHENEVER</code> is a directive
+ of the SQL preprocessor, not a C statement. The error or warning
+ actions that it sets apply to all embedded SQL statements that
+ appear below the point where the handler is set, unless a
+ different action was set for the same condition between the first
+ <code class="literal">EXEC SQL WHENEVER</code> and the SQL statement causing
+ the condition, regardless of the flow of control in the C program.
+ So neither of the two following C program excerpts will have the
+ desired effect:
+</p><pre class="programlisting">
+/*
+ * WRONG
+ */
+int main(int argc, char *argv[])
+{
+ ...
+ if (verbose) {
+ EXEC SQL WHENEVER SQLWARNING SQLPRINT;
+ }
+ ...
+ EXEC SQL SELECT ...;
+ ...
+}
+</pre><p>
+
+</p><pre class="programlisting">
+/*
+ * WRONG
+ */
+int main(int argc, char *argv[])
+{
+ ...
+ set_error_handler();
+ ...
+ EXEC SQL SELECT ...;
+ ...
+}
+
+static void set_error_handler(void)
+{
+ EXEC SQL WHENEVER SQLERROR STOP;
+}
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-SQLCA"><div class="titlepage"><div><div><h3 class="title">36.8.2. sqlca</h3></div></div></div><p>
+ For more powerful error handling, the embedded SQL interface
+ provides a global variable with the name <code class="varname">sqlca</code>
+ (SQL communication area)
+ that has the following structure:
+</p><pre class="programlisting">
+struct
+{
+ char sqlcaid[8];
+ long sqlabc;
+ long sqlcode;
+ struct
+ {
+ int sqlerrml;
+ char sqlerrmc[SQLERRMC_LEN];
+ } sqlerrm;
+ char sqlerrp[8];
+ long sqlerrd[6];
+ char sqlwarn[8];
+ char sqlstate[5];
+} sqlca;
+</pre><p>
+ (In a multithreaded program, every thread automatically gets its
+ own copy of <code class="varname">sqlca</code>. This works similarly to the
+ handling of the standard C global variable
+ <code class="varname">errno</code>.)
+ </p><p>
+ <code class="varname">sqlca</code> covers both warnings and errors. If
+ multiple warnings or errors occur during the execution of a
+ statement, then <code class="varname">sqlca</code> will only contain
+ information about the last one.
+ </p><p>
+ If no error occurred in the last <acronym class="acronym">SQL</acronym> statement,
+ <code class="literal">sqlca.sqlcode</code> will be 0 and
+ <code class="literal">sqlca.sqlstate</code> will be
+ <code class="literal">"00000"</code>. If a warning or error occurred, then
+ <code class="literal">sqlca.sqlcode</code> will be negative and
+ <code class="literal">sqlca.sqlstate</code> will be different from
+ <code class="literal">"00000"</code>. A positive
+ <code class="literal">sqlca.sqlcode</code> indicates a harmless condition,
+ such as that the last query returned zero rows.
+ <code class="literal">sqlcode</code> and <code class="literal">sqlstate</code> are two
+ different error code schemes; details appear below.
+ </p><p>
+ If the last SQL statement was successful, then
+ <code class="literal">sqlca.sqlerrd[1]</code> contains the OID of the
+ processed row, if applicable, and
+ <code class="literal">sqlca.sqlerrd[2]</code> contains the number of
+ processed or returned rows, if applicable to the command.
+ </p><p>
+ In case of an error or warning,
+ <code class="literal">sqlca.sqlerrm.sqlerrmc</code> will contain a string
+ that describes the error. The field
+ <code class="literal">sqlca.sqlerrm.sqlerrml</code> contains the length of
+ the error message that is stored in
+ <code class="literal">sqlca.sqlerrm.sqlerrmc</code> (the result of
+ <code class="function">strlen()</code>, not really interesting for a C
+ programmer). Note that some messages are too long to fit in the
+ fixed-size <code class="literal">sqlerrmc</code> array; they will be truncated.
+ </p><p>
+ In case of a warning, <code class="literal">sqlca.sqlwarn[2]</code> is set
+ to <code class="literal">W</code>. (In all other cases, it is set to
+ something different from <code class="literal">W</code>.) If
+ <code class="literal">sqlca.sqlwarn[1]</code> is set to
+ <code class="literal">W</code>, then a value was truncated when it was
+ stored in a host variable. <code class="literal">sqlca.sqlwarn[0]</code> is
+ set to <code class="literal">W</code> if any of the other elements are set
+ to indicate a warning.
+ </p><p>
+ The fields <code class="structfield">sqlcaid</code>,
+ <code class="structfield">sqlabc</code>,
+ <code class="structfield">sqlerrp</code>, and the remaining elements of
+ <code class="structfield">sqlerrd</code> and
+ <code class="structfield">sqlwarn</code> currently contain no useful
+ information.
+ </p><p>
+ The structure <code class="varname">sqlca</code> is not defined in the SQL
+ standard, but is implemented in several other SQL database
+ systems. The definitions are similar at the core, but if you want
+ to write portable applications, then you should investigate the
+ different implementations carefully.
+ </p><p>
+ Here is one example that combines the use of <code class="literal">WHENEVER</code>
+ and <code class="varname">sqlca</code>, printing out the contents
+ of <code class="varname">sqlca</code> when an error occurs. This is perhaps
+ useful for debugging or prototyping applications, before
+ installing a more <span class="quote">“<span class="quote">user-friendly</span>”</span> error handler.
+
+</p><pre class="programlisting">
+EXEC SQL WHENEVER SQLERROR CALL print_sqlca();
+
+void
+print_sqlca()
+{
+ fprintf(stderr, "==== sqlca ====\n");
+ fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode);
+ fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml);
+ fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc);
+ fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2],
+ sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]);
+ fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2],
+ sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5],
+ sqlca.sqlwarn[6], sqlca.sqlwarn[7]);
+ fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate);
+ fprintf(stderr, "===============\n");
+}
+</pre><p>
+
+ The result could look as follows (here an error due to a
+ misspelled table name):
+
+</p><pre class="screen">
+==== sqlca ====
+sqlcode: -400
+sqlerrm.sqlerrml: 49
+sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38
+sqlerrd: 0 0 0 0 0 0
+sqlwarn: 0 0 0 0 0 0 0 0
+sqlstate: 42P01
+===============
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-SQLSTATE-SQLCODE"><div class="titlepage"><div><div><h3 class="title">36.8.3. <code class="literal">SQLSTATE</code> vs. <code class="literal">SQLCODE</code></h3></div></div></div><p>
+ The fields <code class="literal">sqlca.sqlstate</code> and
+ <code class="literal">sqlca.sqlcode</code> are two different schemes that
+ provide error codes. Both are derived from the SQL standard, but
+ <code class="literal">SQLCODE</code> has been marked deprecated in the SQL-92
+ edition of the standard and has been dropped in later editions.
+ Therefore, new applications are strongly encouraged to use
+ <code class="literal">SQLSTATE</code>.
+ </p><p>
+ <code class="literal">SQLSTATE</code> is a five-character array. The five
+ characters contain digits or upper-case letters that represent
+ codes of various error and warning conditions.
+ <code class="literal">SQLSTATE</code> has a hierarchical scheme: the first
+ two characters indicate the general class of the condition, the
+ last three characters indicate a subclass of the general
+ condition. A successful state is indicated by the code
+ <code class="literal">00000</code>. The <code class="literal">SQLSTATE</code> codes are for
+ the most part defined in the SQL standard. The
+ <span class="productname">PostgreSQL</span> server natively supports
+ <code class="literal">SQLSTATE</code> error codes; therefore a high degree
+ of consistency can be achieved by using this error code scheme
+ throughout all applications. For further information see
+ <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>.
+ </p><p>
+ <code class="literal">SQLCODE</code>, the deprecated error code scheme, is a
+ simple integer. A value of 0 indicates success, a positive value
+ indicates success with additional information, a negative value
+ indicates an error. The SQL standard only defines the positive
+ value +100, which indicates that the last command returned or
+ affected zero rows, and no specific negative values. Therefore,
+ this scheme can only achieve poor portability and does not have a
+ hierarchical code assignment. Historically, the embedded SQL
+ processor for <span class="productname">PostgreSQL</span> has assigned
+ some specific <code class="literal">SQLCODE</code> values for its use, which
+ are listed below with their numeric value and their symbolic name.
+ Remember that these are not portable to other SQL implementations.
+ To simplify the porting of applications to the
+ <code class="literal">SQLSTATE</code> scheme, the corresponding
+ <code class="literal">SQLSTATE</code> 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
+ <code class="literal">SQLSTATE</code> listing in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>
+ in each case.
+ </p><p>
+ These are the assigned <code class="literal">SQLCODE</code> values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">0 (<code class="symbol">ECPG_NO_ERROR</code>)</span></dt><dd><p>
+ Indicates no error. (SQLSTATE 00000)
+ </p></dd><dt><span class="term">100 (<code class="symbol">ECPG_NOT_FOUND</code>)</span></dt><dd><p>
+ This is a harmless condition indicating that the last command
+ retrieved or processed zero rows, or that you are at the end of
+ the cursor. (SQLSTATE 02000)
+ </p><p>
+ When processing a cursor in a loop, you could use this code as
+ a way to detect when to abort the loop, like this:
+</p><pre class="programlisting">
+while (1)
+{
+ EXEC SQL FETCH ... ;
+ if (sqlca.sqlcode == ECPG_NOT_FOUND)
+ break;
+}
+</pre><p>
+ But <code class="literal">WHENEVER NOT FOUND DO BREAK</code> effectively
+ does this internally, so there is usually no advantage in
+ writing this out explicitly.
+ </p></dd><dt><span class="term">-12 (<code class="symbol">ECPG_OUT_OF_MEMORY</code>)</span></dt><dd><p>
+ Indicates that your virtual memory is exhausted. The numeric
+ value is defined as <code class="literal">-ENOMEM</code>. (SQLSTATE
+ YE001)
+ </p></dd><dt><span class="term">-200 (<code class="symbol">ECPG_UNSUPPORTED</code>)</span></dt><dd><p>
+ Indicates the preprocessor has generated something that the
+ library does not know about. Perhaps you are running
+ incompatible versions of the preprocessor and the
+ library. (SQLSTATE YE002)
+ </p></dd><dt><span class="term">-201 (<code class="symbol">ECPG_TOO_MANY_ARGUMENTS</code>)</span></dt><dd><p>
+ This means that the command specified more host variables than
+ the command expected. (SQLSTATE 07001 or 07002)
+ </p></dd><dt><span class="term">-202 (<code class="symbol">ECPG_TOO_FEW_ARGUMENTS</code>)</span></dt><dd><p>
+ This means that the command specified fewer host variables than
+ the command expected. (SQLSTATE 07001 or 07002)
+ </p></dd><dt><span class="term">-203 (<code class="symbol">ECPG_TOO_MANY_MATCHES</code>)</span></dt><dd><p>
+ This means a query has returned multiple rows but the statement
+ was only prepared to store one result row (for example, because
+ the specified variables are not arrays). (SQLSTATE 21000)
+ </p></dd><dt><span class="term">-204 (<code class="symbol">ECPG_INT_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">int</code> and the datum in
+ the database is of a different type and contains a value that
+ cannot be interpreted as an <code class="type">int</code>. The library uses
+ <code class="function">strtol()</code> for this conversion. (SQLSTATE
+ 42804)
+ </p></dd><dt><span class="term">-205 (<code class="symbol">ECPG_UINT_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">unsigned int</code> and the
+ datum in the database is of a different type and contains a
+ value that cannot be interpreted as an <code class="type">unsigned
+ int</code>. The library uses <code class="function">strtoul()</code>
+ for this conversion. (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-206 (<code class="symbol">ECPG_FLOAT_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">float</code> and the datum
+ in the database is of another type and contains a value that
+ cannot be interpreted as a <code class="type">float</code>. The library
+ uses <code class="function">strtod()</code> for this conversion.
+ (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-207 (<code class="symbol">ECPG_NUMERIC_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">numeric</code> and the datum
+ in the database is of another type and contains a value that
+ cannot be interpreted as a <code class="type">numeric</code> value.
+ (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-208 (<code class="symbol">ECPG_INTERVAL_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">interval</code> and the datum
+ in the database is of another type and contains a value that
+ cannot be interpreted as an <code class="type">interval</code> value.
+ (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-209 (<code class="symbol">ECPG_DATE_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">date</code> and the datum in
+ the database is of another type and contains a value that
+ cannot be interpreted as a <code class="type">date</code> value.
+ (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-210 (<code class="symbol">ECPG_TIMESTAMP_FORMAT</code>)</span></dt><dd><p>
+ The host variable is of type <code class="type">timestamp</code> and the
+ datum in the database is of another type and contains a value
+ that cannot be interpreted as a <code class="type">timestamp</code> value.
+ (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-211 (<code class="symbol">ECPG_CONVERT_BOOL</code>)</span></dt><dd><p>
+ This means the host variable is of type <code class="type">bool</code> and
+ the datum in the database is neither <code class="literal">'t'</code> nor
+ <code class="literal">'f'</code>. (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-212 (<code class="symbol">ECPG_EMPTY</code>)</span></dt><dd><p>
+ The statement sent to the <span class="productname">PostgreSQL</span>
+ server was empty. (This cannot normally happen in an embedded
+ SQL program, so it might point to an internal error.) (SQLSTATE
+ YE002)
+ </p></dd><dt><span class="term">-213 (<code class="symbol">ECPG_MISSING_INDICATOR</code>)</span></dt><dd><p>
+ A null value was returned and no null indicator variable was
+ supplied. (SQLSTATE 22002)
+ </p></dd><dt><span class="term">-214 (<code class="symbol">ECPG_NO_ARRAY</code>)</span></dt><dd><p>
+ An ordinary variable was used in a place that requires an
+ array. (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-215 (<code class="symbol">ECPG_DATA_NOT_ARRAY</code>)</span></dt><dd><p>
+ The database returned an ordinary variable in a place that
+ requires array value. (SQLSTATE 42804)
+ </p></dd><dt><span class="term">-216 (<code class="symbol">ECPG_ARRAY_INSERT</code>)</span></dt><dd><p>
+ The value could not be inserted into the array. (SQLSTATE
+ 42804)
+ </p></dd><dt><span class="term">-220 (<code class="symbol">ECPG_NO_CONN</code>)</span></dt><dd><p>
+ The program tried to access a connection that does not exist.
+ (SQLSTATE 08003)
+ </p></dd><dt><span class="term">-221 (<code class="symbol">ECPG_NOT_CONN</code>)</span></dt><dd><p>
+ The program tried to access a connection that does exist but is
+ not open. (This is an internal error.) (SQLSTATE YE002)
+ </p></dd><dt><span class="term">-230 (<code class="symbol">ECPG_INVALID_STMT</code>)</span></dt><dd><p>
+ The statement you are trying to use has not been prepared.
+ (SQLSTATE 26000)
+ </p></dd><dt><span class="term">-239 (<code class="symbol">ECPG_INFORMIX_DUPLICATE_KEY</code>)</span></dt><dd><p>
+ Duplicate key error, violation of unique constraint (Informix
+ compatibility mode). (SQLSTATE 23505)
+ </p></dd><dt><span class="term">-240 (<code class="symbol">ECPG_UNKNOWN_DESCRIPTOR</code>)</span></dt><dd><p>
+ The descriptor specified was not found. The statement you are
+ trying to use has not been prepared. (SQLSTATE 33000)
+ </p></dd><dt><span class="term">-241 (<code class="symbol">ECPG_INVALID_DESCRIPTOR_INDEX</code>)</span></dt><dd><p>
+ The descriptor index specified was out of range. (SQLSTATE
+ 07009)
+ </p></dd><dt><span class="term">-242 (<code class="symbol">ECPG_UNKNOWN_DESCRIPTOR_ITEM</code>)</span></dt><dd><p>
+ An invalid descriptor item was requested. (This is an internal
+ error.) (SQLSTATE YE002)
+ </p></dd><dt><span class="term">-243 (<code class="symbol">ECPG_VAR_NOT_NUMERIC</code>)</span></dt><dd><p>
+ During the execution of a dynamic statement, the database
+ returned a numeric value and the host variable was not numeric.
+ (SQLSTATE 07006)
+ </p></dd><dt><span class="term">-244 (<code class="symbol">ECPG_VAR_NOT_CHAR</code>)</span></dt><dd><p>
+ During the execution of a dynamic statement, the database
+ returned a non-numeric value and the host variable was numeric.
+ (SQLSTATE 07006)
+ </p></dd><dt><span class="term">-284 (<code class="symbol">ECPG_INFORMIX_SUBSELECT_NOT_ONE</code>)</span></dt><dd><p>
+ A result of the subquery is not single row (Informix
+ compatibility mode). (SQLSTATE 21000)
+ </p></dd><dt><span class="term">-400 (<code class="symbol">ECPG_PGSQL</code>)</span></dt><dd><p>
+ Some error caused by the <span class="productname">PostgreSQL</span>
+ server. The message contains the error message from the
+ <span class="productname">PostgreSQL</span> server.
+ </p></dd><dt><span class="term">-401 (<code class="symbol">ECPG_TRANS</code>)</span></dt><dd><p>
+ The <span class="productname">PostgreSQL</span> server signaled that
+ we cannot start, commit, or rollback the transaction.
+ (SQLSTATE 08007)
+ </p></dd><dt><span class="term">-402 (<code class="symbol">ECPG_CONNECT</code>)</span></dt><dd><p>
+ The connection attempt to the database did not succeed.
+ (SQLSTATE 08001)
+ </p></dd><dt><span class="term">-403 (<code class="symbol">ECPG_DUPLICATE_KEY</code>)</span></dt><dd><p>
+ Duplicate key error, violation of unique constraint. (SQLSTATE
+ 23505)
+ </p></dd><dt><span class="term">-404 (<code class="symbol">ECPG_SUBSELECT_NOT_ONE</code>)</span></dt><dd><p>
+ A result for the subquery is not single row. (SQLSTATE 21000)
+ </p></dd><dt><span class="term">-602 (<code class="symbol">ECPG_WARNING_UNKNOWN_PORTAL</code>)</span></dt><dd><p>
+ An invalid cursor name was specified. (SQLSTATE 34000)
+ </p></dd><dt><span class="term">-603 (<code class="symbol">ECPG_WARNING_IN_TRANSACTION</code>)</span></dt><dd><p>
+ Transaction is in progress. (SQLSTATE 25001)
+ </p></dd><dt><span class="term">-604 (<code class="symbol">ECPG_WARNING_NO_TRANSACTION</code>)</span></dt><dd><p>
+ There is no active (in-progress) transaction. (SQLSTATE 25P01)
+ </p></dd><dt><span class="term">-605 (<code class="symbol">ECPG_WARNING_PORTAL_EXISTS</code>)</span></dt><dd><p>
+ An existing cursor name was specified. (SQLSTATE 42P03)
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-preproc.html" title="36.9. Preprocessor Directives">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.7. Using Descriptor Areas </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.9. Preprocessor Directives</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-informix-compat.html b/doc/src/sgml/html/ecpg-informix-compat.html
new file mode 100644
index 0000000..a11a001
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-informix-compat.html
@@ -0,0 +1,892 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.15. Informix Compatibility Mode</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-whenever.html" title="WHENEVER" /><link rel="next" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.15. <span class="productname">Informix</span> Compatibility Mode</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-whenever.html" title="WHENEVER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-INFORMIX-COMPAT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.15. <span class="productname">Informix</span> Compatibility Mode</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-TYPES">36.15.1. Additional Types</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-STATEMENTS">36.15.2. Additional/Missing Embedded SQL Statements</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-SQLDA">36.15.3. Informix-compatible SQLDA Descriptor Areas</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-FUNCTIONS">36.15.4. Additional Functions</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-CONSTANTS">36.15.5. Additional Constants</a></span></dt></dl></div><p>
+ <code class="command">ecpg</code> can be run in a so-called <em class="firstterm">Informix compatibility mode</em>. If
+ this mode is active, it tries to behave as if it were the <span class="productname">Informix</span>
+ precompiler for <span class="productname">Informix</span> E/SQL. Generally spoken this will allow you to use
+ the dollar sign instead of the <code class="literal">EXEC SQL</code> primitive to introduce
+ embedded SQL commands:
+</p><pre class="programlisting">
+$int j = 3;
+$CONNECT TO :dbname;
+$CREATE TABLE test(i INT PRIMARY KEY, j INT);
+$INSERT INTO test(i, j) VALUES (7, :j);
+$COMMIT;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ There must not be any white space between the <code class="literal">$</code>
+ and a following preprocessor directive, that is,
+ <code class="literal">include</code>, <code class="literal">define</code>, <code class="literal">ifdef</code>,
+ etc. Otherwise, the preprocessor will parse the token as a host
+ variable.
+ </p></div><p>
+ There are two compatibility modes: <code class="literal">INFORMIX</code>, <code class="literal">INFORMIX_SE</code>
+ </p><p>
+ When linking programs that use this compatibility mode, remember to link
+ against <code class="literal">libcompat</code> that is shipped with ECPG.
+ </p><p>
+ Besides the previously explained syntactic sugar, the <span class="productname">Informix</span> compatibility
+ mode ports some functions for input, output and transformation of data as
+ well as embedded SQL statements known from E/SQL to ECPG.
+ </p><p>
+ <span class="productname">Informix</span> compatibility mode is closely connected to the pgtypeslib library
+ of ECPG. pgtypeslib maps SQL data types to data types within the C host
+ program and most of the additional functions of the <span class="productname">Informix</span> compatibility
+ mode allow you to operate on those C host program types. Note however that
+ the extent of the compatibility is limited. It does not try to copy <span class="productname">Informix</span>
+ behavior; it allows you to do more or less the same operations and gives
+ you functions that have the same name and the same basic behavior but it is
+ no drop-in replacement if you are using <span class="productname">Informix</span> at the moment. Moreover,
+ some of the data types are different. For example,
+ <span class="productname">PostgreSQL</span>'s datetime and interval types do not
+ know about ranges like for example <code class="literal">YEAR TO MINUTE</code> so you won't
+ find support in ECPG for that either.
+ </p><div class="sect2" id="ECPG-INFORMIX-TYPES"><div class="titlepage"><div><div><h3 class="title">36.15.1. Additional Types</h3></div></div></div><p>
+ The Informix-special "string" pseudo-type for storing right-trimmed character string data is now
+ supported in Informix-mode without using <code class="literal">typedef</code>. In fact, in Informix-mode,
+ ECPG refuses to process source files that contain <code class="literal">typedef sometype string;</code>
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+string userid; /* this variable will contain trimmed data */
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL FETCH MYCUR INTO :userid;
+</pre><p>
+ </p></div><div class="sect2" id="ECPG-INFORMIX-STATEMENTS"><div class="titlepage"><div><div><h3 class="title">36.15.2. Additional/Missing Embedded SQL Statements</h3></div></div></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CLOSE DATABASE</code></span></dt><dd><p>
+ This statement closes the current connection. In fact, this is a
+ synonym for ECPG's <code class="literal">DISCONNECT CURRENT</code>:
+</p><pre class="programlisting">
+$CLOSE DATABASE; /* close the current connection */
+EXEC SQL CLOSE DATABASE;
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">FREE cursor_name</code></span></dt><dd><p>
+ Due to differences in how ECPG works compared to Informix's ESQL/C (namely, which steps
+ are purely grammar transformations and which steps rely on the underlying run-time library)
+ there is no <code class="literal">FREE cursor_name</code> statement in ECPG. This is because in ECPG,
+ <code class="literal">DECLARE CURSOR</code> doesn't translate to a function call into
+ the run-time library that uses to the cursor name. This means that there's no run-time
+ bookkeeping of SQL cursors in the ECPG run-time library, only in the PostgreSQL server.
+ </p></dd><dt><span class="term"><code class="literal">FREE statement_name</code></span></dt><dd><p>
+ <code class="literal">FREE statement_name</code> is a synonym for <code class="literal">DEALLOCATE PREPARE statement_name</code>.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-INFORMIX-SQLDA"><div class="titlepage"><div><div><h3 class="title">36.15.3. Informix-compatible SQLDA Descriptor Areas</h3></div></div></div><p>
+ Informix-compatible mode supports a different structure than the one described in
+ <a class="xref" href="ecpg-descriptors.html#ECPG-SQLDA-DESCRIPTORS" title="36.7.2. SQLDA Descriptor Areas">Section 36.7.2</a>. See below:
+</p><pre class="programlisting">
+struct sqlvar_compat
+{
+ short sqltype;
+ int sqllen;
+ char *sqldata;
+ short *sqlind;
+ char *sqlname;
+ char *sqlformat;
+ short sqlitype;
+ short sqlilen;
+ char *sqlidata;
+ int sqlxid;
+ char *sqltypename;
+ short sqltypelen;
+ short sqlownerlen;
+ short sqlsourcetype;
+ char *sqlownername;
+ int sqlsourceid;
+ char *sqlilongdata;
+ int sqlflags;
+ void *sqlreserved;
+};
+
+struct sqlda_compat
+{
+ short sqld;
+ struct sqlvar_compat *sqlvar;
+ char desc_name[19];
+ short desc_occ;
+ struct sqlda_compat *desc_next;
+ void *reserved;
+};
+
+typedef struct sqlvar_compat sqlvar_t;
+typedef struct sqlda_compat sqlda_t;
+</pre><p>
+ </p><p>
+ The global properties are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">sqld</code></span></dt><dd><p>
+ The number of fields in the <code class="literal">SQLDA</code> descriptor.
+ </p></dd><dt><span class="term"><code class="literal">sqlvar</code></span></dt><dd><p>
+ Pointer to the per-field properties.
+ </p></dd><dt><span class="term"><code class="literal">desc_name</code></span></dt><dd><p>
+ Unused, filled with zero-bytes.
+ </p></dd><dt><span class="term"><code class="literal">desc_occ</code></span></dt><dd><p>
+ Size of the allocated structure.
+ </p></dd><dt><span class="term"><code class="literal">desc_next</code></span></dt><dd><p>
+ Pointer to the next SQLDA structure if the result set contains more than one record.
+ </p></dd><dt><span class="term"><code class="literal">reserved</code></span></dt><dd><p>
+ Unused pointer, contains NULL. Kept for Informix-compatibility.
+ </p></dd></dl></div><p>
+
+ The per-field properties are below, they are stored in the <code class="literal">sqlvar</code> array:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">sqltype</code></span></dt><dd><p>
+ Type of the field. Constants are in <code class="literal">sqltypes.h</code>
+ </p></dd><dt><span class="term"><code class="literal">sqllen</code></span></dt><dd><p>
+ Length of the field data.
+ </p></dd><dt><span class="term"><code class="literal">sqldata</code></span></dt><dd><p>
+ Pointer to the field data. The pointer is of <code class="literal">char *</code> type,
+ the data pointed by it is in a binary format. Example:
+</p><pre class="programlisting">
+int intval;
+
+switch (sqldata-&gt;sqlvar[i].sqltype)
+{
+ case SQLINTEGER:
+ intval = *(int *)sqldata-&gt;sqlvar[i].sqldata;
+ break;
+ ...
+}
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">sqlind</code></span></dt><dd><p>
+ Pointer to the NULL indicator. If returned by DESCRIBE or FETCH then it's always a valid pointer.
+ If used as input for <code class="literal">EXECUTE ... USING sqlda;</code> then NULL-pointer value means
+ that the value for this field is non-NULL. Otherwise a valid pointer and <code class="literal">sqlitype</code>
+ has to be properly set. Example:
+</p><pre class="programlisting">
+if (*(int2 *)sqldata-&gt;sqlvar[i].sqlind != 0)
+ printf("value is NULL\n");
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">sqlname</code></span></dt><dd><p>
+ Name of the field. 0-terminated string.
+ </p></dd><dt><span class="term"><code class="literal">sqlformat</code></span></dt><dd><p>
+ Reserved in Informix, value of <a class="xref" href="libpq-exec.html#LIBPQ-PQFFORMAT"><code class="function">PQfformat</code></a> for the field.
+ </p></dd><dt><span class="term"><code class="literal">sqlitype</code></span></dt><dd><p>
+ Type of the NULL indicator data. It's always SQLSMINT when returning data from the server.
+ When the <code class="literal">SQLDA</code> is used for a parameterized query, the data is treated
+ according to the set type.
+ </p></dd><dt><span class="term"><code class="literal">sqlilen</code></span></dt><dd><p>
+ Length of the NULL indicator data.
+ </p></dd><dt><span class="term"><code class="literal">sqlxid</code></span></dt><dd><p>
+ Extended type of the field, result of <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">sqltypename</code><br /></span><span class="term"><code class="literal">sqltypelen</code><br /></span><span class="term"><code class="literal">sqlownerlen</code><br /></span><span class="term"><code class="literal">sqlsourcetype</code><br /></span><span class="term"><code class="literal">sqlownername</code><br /></span><span class="term"><code class="literal">sqlsourceid</code><br /></span><span class="term"><code class="literal">sqlflags</code><br /></span><span class="term"><code class="literal">sqlreserved</code></span></dt><dd><p>
+ Unused.
+ </p></dd><dt><span class="term"><code class="literal">sqlilongdata</code></span></dt><dd><p>
+ It equals to <code class="literal">sqldata</code> if <code class="literal">sqllen</code> is larger than 32kB.
+ </p></dd></dl></div><p>
+
+ Example:
+</p><pre class="programlisting">
+EXEC SQL INCLUDE sqlda.h;
+
+ sqlda_t *sqlda; /* This doesn't need to be under embedded DECLARE SECTION */
+
+ EXEC SQL BEGIN DECLARE SECTION;
+ char *prep_stmt = "select * from table1";
+ int i;
+ EXEC SQL END DECLARE SECTION;
+
+ ...
+
+ EXEC SQL PREPARE mystmt FROM :prep_stmt;
+
+ EXEC SQL DESCRIBE mystmt INTO sqlda;
+
+ printf("# of fields: %d\n", sqlda-&gt;sqld);
+ for (i = 0; i &lt; sqlda-&gt;sqld; i++)
+ printf("field %d: \"%s\"\n", sqlda-&gt;sqlvar[i]-&gt;sqlname);
+
+ EXEC SQL DECLARE mycursor CURSOR FOR mystmt;
+ EXEC SQL OPEN mycursor;
+ EXEC SQL WHENEVER NOT FOUND GOTO out;
+
+ while (1)
+ {
+ EXEC SQL FETCH mycursor USING sqlda;
+ }
+
+ EXEC SQL CLOSE mycursor;
+
+ free(sqlda); /* The main structure is all to be free(),
+ * sqlda and sqlda-&gt;sqlvar is in one allocated area */
+</pre><p>
+ For more information, see the <code class="literal">sqlda.h</code> header and the
+ <code class="literal">src/interfaces/ecpg/test/compat_informix/sqlda.pgc</code> regression test.
+ </p></div><div class="sect2" id="ECPG-INFORMIX-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">36.15.4. Additional Functions</h3></div></div></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">decadd</code></span></dt><dd><p>
+ Add two decimal type values.
+</p><pre class="synopsis">
+int decadd(decimal *arg1, decimal *arg2, decimal *sum);
+</pre><p>
+ The function receives a pointer to the first operand of type decimal
+ (<code class="literal">arg1</code>), a pointer to the second operand of type decimal
+ (<code class="literal">arg2</code>) and a pointer to a value of type decimal that will
+ contain the sum (<code class="literal">sum</code>). On success, the function returns 0.
+ <code class="symbol">ECPG_INFORMIX_NUM_OVERFLOW</code> is returned in case of overflow and
+ <code class="symbol">ECPG_INFORMIX_NUM_UNDERFLOW</code> in case of underflow. -1 is returned for
+ other failures and <code class="varname">errno</code> is set to the respective <code class="varname">errno</code> number of the
+ pgtypeslib.
+ </p></dd><dt><span class="term"><code class="function">deccmp</code></span></dt><dd><p>
+ Compare two variables of type decimal.
+</p><pre class="synopsis">
+int deccmp(decimal *arg1, decimal *arg2);
+</pre><p>
+ The function receives a pointer to the first decimal value
+ (<code class="literal">arg1</code>), a pointer to the second decimal value
+ (<code class="literal">arg2</code>) and returns an integer value that indicates which is
+ the bigger value.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 1, if the value that <code class="literal">arg1</code> points to is bigger than the
+ value that <code class="literal">var2</code> points to
+ </p></li><li class="listitem"><p>
+ -1, if the value that <code class="literal">arg1</code> points to is smaller than the
+ value that <code class="literal">arg2</code> points to </p></li><li class="listitem"><p>
+ 0, if the value that <code class="literal">arg1</code> points to and the value that
+ <code class="literal">arg2</code> points to are equal
+ </p></li></ul></div><p>
+ </p></dd><dt><span class="term"><code class="function">deccopy</code></span></dt><dd><p>
+ Copy a decimal value.
+</p><pre class="synopsis">
+void deccopy(decimal *src, decimal *target);
+</pre><p>
+ The function receives a pointer to the decimal value that should be
+ copied as the first argument (<code class="literal">src</code>) and a pointer to the
+ target structure of type decimal (<code class="literal">target</code>) as the second
+ argument.
+ </p></dd><dt><span class="term"><code class="function">deccvasc</code></span></dt><dd><p>
+ Convert a value from its ASCII representation into a decimal type.
+</p><pre class="synopsis">
+int deccvasc(char *cp, int len, decimal *np);
+</pre><p>
+ The function receives a pointer to string that contains the string
+ representation of the number to be converted (<code class="literal">cp</code>) as well
+ as its length <code class="literal">len</code>. <code class="literal">np</code> is a pointer to the
+ decimal value that saves the result of the operation.
+ </p><p>
+ Valid formats are for example:
+ <code class="literal">-2</code>,
+ <code class="literal">.794</code>,
+ <code class="literal">+3.44</code>,
+ <code class="literal">592.49E07</code> or
+ <code class="literal">-32.84e-4</code>.
+ </p><p>
+ The function returns 0 on success. If overflow or underflow occurred,
+ <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
+ <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> is returned. If the ASCII
+ representation could not be parsed,
+ <code class="literal">ECPG_INFORMIX_BAD_NUMERIC</code> is returned or
+ <code class="literal">ECPG_INFORMIX_BAD_EXPONENT</code> if this problem occurred while
+ parsing the exponent.
+ </p></dd><dt><span class="term"><code class="function">deccvdbl</code></span></dt><dd><p>
+ Convert a value of type double to a value of type decimal.
+</p><pre class="synopsis">
+int deccvdbl(double dbl, decimal *np);
+</pre><p>
+ The function receives the variable of type double that should be
+ converted as its first argument (<code class="literal">dbl</code>). As the second
+ argument (<code class="literal">np</code>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
+ </p><p>
+ The function returns 0 on success and a negative value if the
+ conversion failed.
+ </p></dd><dt><span class="term"><code class="function">deccvint</code></span></dt><dd><p>
+ Convert a value of type int to a value of type decimal.
+</p><pre class="synopsis">
+int deccvint(int in, decimal *np);
+</pre><p>
+ The function receives the variable of type int that should be
+ converted as its first argument (<code class="literal">in</code>). As the second
+ argument (<code class="literal">np</code>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
+ </p><p>
+ The function returns 0 on success and a negative value if the
+ conversion failed.
+ </p></dd><dt><span class="term"><code class="function">deccvlong</code></span></dt><dd><p>
+ Convert a value of type long to a value of type decimal.
+</p><pre class="synopsis">
+int deccvlong(long lng, decimal *np);
+</pre><p>
+ The function receives the variable of type long that should be
+ converted as its first argument (<code class="literal">lng</code>). As the second
+ argument (<code class="literal">np</code>), the function receives a pointer to the
+ decimal variable that should hold the result of the operation.
+ </p><p>
+ The function returns 0 on success and a negative value if the
+ conversion failed.
+ </p></dd><dt><span class="term"><code class="function">decdiv</code></span></dt><dd><p>
+ Divide two variables of type decimal.
+</p><pre class="synopsis">
+int decdiv(decimal *n1, decimal *n2, decimal *result);
+</pre><p>
+ The function receives pointers to the variables that are the first
+ (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
+ calculates <code class="literal">n1</code>/<code class="literal">n2</code>. <code class="literal">result</code> is a
+ pointer to the variable that should hold the result of the operation.
+ </p><p>
+ On success, 0 is returned and a negative value if the division fails.
+ If overflow or underflow occurred, the function returns
+ <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
+ <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively. If an attempt to
+ divide by zero is observed, the function returns
+ <code class="literal">ECPG_INFORMIX_DIVIDE_ZERO</code>.
+ </p></dd><dt><span class="term"><code class="function">decmul</code></span></dt><dd><p>
+ Multiply two decimal values.
+</p><pre class="synopsis">
+int decmul(decimal *n1, decimal *n2, decimal *result);
+</pre><p>
+ The function receives pointers to the variables that are the first
+ (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
+ calculates <code class="literal">n1</code>*<code class="literal">n2</code>. <code class="literal">result</code> is a
+ pointer to the variable that should hold the result of the operation.
+ </p><p>
+ On success, 0 is returned and a negative value if the multiplication
+ fails. If overflow or underflow occurred, the function returns
+ <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
+ <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively.
+ </p></dd><dt><span class="term"><code class="function">decsub</code></span></dt><dd><p>
+ Subtract one decimal value from another.
+</p><pre class="synopsis">
+int decsub(decimal *n1, decimal *n2, decimal *result);
+</pre><p>
+ The function receives pointers to the variables that are the first
+ (<code class="literal">n1</code>) and the second (<code class="literal">n2</code>) operands and
+ calculates <code class="literal">n1</code>-<code class="literal">n2</code>. <code class="literal">result</code> is a
+ pointer to the variable that should hold the result of the operation.
+ </p><p>
+ On success, 0 is returned and a negative value if the subtraction
+ fails. If overflow or underflow occurred, the function returns
+ <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code> or
+ <code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code> respectively.
+ </p></dd><dt><span class="term"><code class="function">dectoasc</code></span></dt><dd><p>
+ Convert a variable of type decimal to its ASCII representation in a C
+ char* string.
+</p><pre class="synopsis">
+int dectoasc(decimal *np, char *cp, int len, int right)
+</pre><p>
+ The function receives a pointer to a variable of type decimal
+ (<code class="literal">np</code>) that it converts to its textual representation.
+ <code class="literal">cp</code> is the buffer that should hold the result of the
+ operation. The parameter <code class="literal">right</code> specifies, how many digits
+ right of the decimal point should be included in the output. The result
+ will be rounded to this number of decimal digits. Setting
+ <code class="literal">right</code> to -1 indicates that all available decimal digits
+ should be included in the output. If the length of the output buffer,
+ which is indicated by <code class="literal">len</code> is not sufficient to hold the
+ textual representation including the trailing zero byte, only a
+ single <code class="literal">*</code> character is stored in the result and -1 is
+ returned.
+ </p><p>
+ The function returns either -1 if the buffer <code class="literal">cp</code> was too
+ small or <code class="literal">ECPG_INFORMIX_OUT_OF_MEMORY</code> if memory was
+ exhausted.
+ </p></dd><dt><span class="term"><code class="function">dectodbl</code></span></dt><dd><p>
+ Convert a variable of type decimal to a double.
+</p><pre class="synopsis">
+int dectodbl(decimal *np, double *dblp);
+</pre><p>
+ The function receives a pointer to the decimal value to convert
+ (<code class="literal">np</code>) and a pointer to the double variable that
+ should hold the result of the operation (<code class="literal">dblp</code>).
+ </p><p>
+ On success, 0 is returned and a negative value if the conversion
+ failed.
+ </p></dd><dt><span class="term"><code class="function">dectoint</code></span></dt><dd><p>
+ Convert a variable to type decimal to an integer.
+</p><pre class="synopsis">
+int dectoint(decimal *np, int *ip);
+</pre><p>
+ The function receives a pointer to the decimal value to convert
+ (<code class="literal">np</code>) and a pointer to the integer variable that
+ should hold the result of the operation (<code class="literal">ip</code>).
+ </p><p>
+ On success, 0 is returned and a negative value if the conversion
+ failed. If an overflow occurred, <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code>
+ is returned.
+ </p><p>
+ Note that the ECPG implementation differs from the <span class="productname">Informix</span>
+ implementation. <span class="productname">Informix</span> limits an integer to the range from -32767 to
+ 32767, while the limits in the ECPG implementation depend on the
+ architecture (<code class="literal">INT_MIN .. INT_MAX</code>).
+ </p></dd><dt><span class="term"><code class="function">dectolong</code></span></dt><dd><p>
+ Convert a variable to type decimal to a long integer.
+</p><pre class="synopsis">
+int dectolong(decimal *np, long *lngp);
+</pre><p>
+ The function receives a pointer to the decimal value to convert
+ (<code class="literal">np</code>) and a pointer to the long variable that
+ should hold the result of the operation (<code class="literal">lngp</code>).
+ </p><p>
+ On success, 0 is returned and a negative value if the conversion
+ failed. If an overflow occurred, <code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code>
+ is returned.
+ </p><p>
+ Note that the ECPG implementation differs from the <span class="productname">Informix</span>
+ implementation. <span class="productname">Informix</span> limits a long integer to the range from
+ -2,147,483,647 to 2,147,483,647, while the limits in the ECPG
+ implementation depend on the architecture (<code class="literal">-LONG_MAX ..
+ LONG_MAX</code>).
+ </p></dd><dt><span class="term"><code class="function">rdatestr</code></span></dt><dd><p>
+ Converts a date to a C char* string.
+</p><pre class="synopsis">
+int rdatestr(date d, char *str);
+</pre><p>
+ The function receives two arguments, the first one is the date to
+ convert (<code class="literal">d</code>) and the second one is a pointer to the target
+ string. The output format is always <code class="literal">yyyy-mm-dd</code>, so you need
+ to allocate at least 11 bytes (including the zero-byte terminator) for the
+ string.
+ </p><p>
+ The function returns 0 on success and a negative value in case of
+ error.
+ </p><p>
+ Note that ECPG's implementation differs from the <span class="productname">Informix</span>
+ implementation. In <span class="productname">Informix</span> the format can be influenced by setting
+ environment variables. In ECPG however, you cannot change the output
+ format.
+ </p></dd><dt><span class="term"><code class="function">rstrdate</code></span></dt><dd><p>
+ Parse the textual representation of a date.
+</p><pre class="synopsis">
+int rstrdate(char *str, date *d);
+</pre><p>
+ The function receives the textual representation of the date to convert
+ (<code class="literal">str</code>) and a pointer to a variable of type date
+ (<code class="literal">d</code>). This function does not allow you to specify a format
+ mask. It uses the default format mask of <span class="productname">Informix</span> which is
+ <code class="literal">mm/dd/yyyy</code>. Internally, this function is implemented by
+ means of <code class="function">rdefmtdate</code>. Therefore, <code class="function">rstrdate</code> is
+ not faster and if you have the choice you should opt for
+ <code class="function">rdefmtdate</code> which allows you to specify the format mask
+ explicitly.
+ </p><p>
+ The function returns the same values as <code class="function">rdefmtdate</code>.
+ </p></dd><dt><span class="term"><code class="function">rtoday</code></span></dt><dd><p>
+ Get the current date.
+</p><pre class="synopsis">
+void rtoday(date *d);
+</pre><p>
+ The function receives a pointer to a date variable (<code class="literal">d</code>)
+ that it sets to the current date.
+ </p><p>
+ Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATETODAY"><code class="function">PGTYPESdate_today</code></a>
+ function.
+ </p></dd><dt><span class="term"><code class="function">rjulmdy</code></span></dt><dd><p>
+ Extract the values for the day, the month and the year from a variable
+ of type date.
+</p><pre class="synopsis">
+int rjulmdy(date d, short mdy[3]);
+</pre><p>
+ The function receives the date <code class="literal">d</code> and a pointer to an array
+ of 3 short integer values <code class="literal">mdy</code>. The variable name indicates
+ the sequential order: <code class="literal">mdy[0]</code> will be set to contain the
+ number of the month, <code class="literal">mdy[1]</code> will be set to the value of the
+ day and <code class="literal">mdy[2]</code> will contain the year.
+ </p><p>
+ The function always returns 0 at the moment.
+ </p><p>
+ Internally the function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEJULMDY"><code class="function">PGTYPESdate_julmdy</code></a>
+ function.
+ </p></dd><dt><span class="term"><code class="function">rdefmtdate</code></span></dt><dd><p>
+ Use a format mask to convert a character string to a value of type
+ date.
+</p><pre class="synopsis">
+int rdefmtdate(date *d, char *fmt, char *str);
+</pre><p>
+ The function receives a pointer to the date value that should hold the
+ result of the operation (<code class="literal">d</code>), the format mask to use for
+ parsing the date (<code class="literal">fmt</code>) and the C char* string containing
+ the textual representation of the date (<code class="literal">str</code>). The textual
+ representation is expected to match the format mask. However you do not
+ need to have a 1:1 mapping of the string to the format mask. The
+ function only analyzes the sequential order and looks for the literals
+ <code class="literal">yy</code> or <code class="literal">yyyy</code> that indicate the
+ position of the year, <code class="literal">mm</code> to indicate the position of
+ the month and <code class="literal">dd</code> to indicate the position of the
+ day.
+ </p><p>
+ The function returns the following values:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 0 - The function terminated successfully.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ECPG_INFORMIX_ENOSHORTDATE</code> - The date does not contain
+ delimiters between day, month and year. In this case the input
+ string must be exactly 6 or 8 bytes long but isn't.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ECPG_INFORMIX_ENOTDMY</code> - The format string did not
+ correctly indicate the sequential order of year, month and day.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ECPG_INFORMIX_BAD_DAY</code> - The input string does not
+ contain a valid day.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ECPG_INFORMIX_BAD_MONTH</code> - The input string does not
+ contain a valid month.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ECPG_INFORMIX_BAD_YEAR</code> - The input string does not
+ contain a valid year.
+ </p></li></ul></div><p>
+ </p><p>
+ Internally this function is implemented to use the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEDEFMTASC"><code class="function">PGTYPESdate_defmt_asc</code></a> function. See the reference there for a
+ table of example input.
+ </p></dd><dt><span class="term"><code class="function">rfmtdate</code></span></dt><dd><p>
+ Convert a variable of type date to its textual representation using a
+ format mask.
+</p><pre class="synopsis">
+int rfmtdate(date d, char *fmt, char *str);
+</pre><p>
+ The function receives the date to convert (<code class="literal">d</code>), the format
+ mask (<code class="literal">fmt</code>) and the string that will hold the textual
+ representation of the date (<code class="literal">str</code>).
+ </p><p>
+ On success, 0 is returned and a negative value if an error occurred.
+ </p><p>
+ Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEFMTASC"><code class="function">PGTYPESdate_fmt_asc</code></a>
+ function, see the reference there for examples.
+ </p></dd><dt><span class="term"><code class="function">rmdyjul</code></span></dt><dd><p>
+ Create a date value from an array of 3 short integers that specify the
+ day, the month and the year of the date.
+</p><pre class="synopsis">
+int rmdyjul(short mdy[3], date *d);
+</pre><p>
+ The function receives the array of the 3 short integers
+ (<code class="literal">mdy</code>) and a pointer to a variable of type date that should
+ hold the result of the operation.
+ </p><p>
+ Currently the function returns always 0.
+ </p><p>
+ Internally the function is implemented to use the function <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEMDYJUL"><code class="function">PGTYPESdate_mdyjul</code></a>.
+ </p></dd><dt><span class="term"><code class="function">rdayofweek</code></span></dt><dd><p>
+ Return a number representing the day of the week for a date value.
+</p><pre class="synopsis">
+int rdayofweek(date d);
+</pre><p>
+ The function receives the date variable <code class="literal">d</code> as its only
+ argument and returns an integer that indicates the day of the week for
+ this date.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 0 - Sunday
+ </p></li><li class="listitem"><p>
+ 1 - Monday
+ </p></li><li class="listitem"><p>
+ 2 - Tuesday
+ </p></li><li class="listitem"><p>
+ 3 - Wednesday
+ </p></li><li class="listitem"><p>
+ 4 - Thursday
+ </p></li><li class="listitem"><p>
+ 5 - Friday
+ </p></li><li class="listitem"><p>
+ 6 - Saturday
+ </p></li></ul></div><p>
+ </p><p>
+ Internally the function is implemented to use the function <a class="xref" href="ecpg-pgtypes.html#PGTYPESDATEDAYOFWEEK"><code class="function">PGTYPESdate_dayofweek</code></a>.
+ </p></dd><dt><span class="term"><code class="function">dtcurrent</code></span></dt><dd><p>
+ Retrieve the current timestamp.
+</p><pre class="synopsis">
+void dtcurrent(timestamp *ts);
+</pre><p>
+ The function retrieves the current timestamp and saves it into the
+ timestamp variable that <code class="literal">ts</code> points to.
+ </p></dd><dt><span class="term"><code class="function">dtcvasc</code></span></dt><dd><p>
+ Parses a timestamp from its textual representation
+ into a timestamp variable.
+</p><pre class="synopsis">
+int dtcvasc(char *str, timestamp *ts);
+</pre><p>
+ The function receives the string to parse (<code class="literal">str</code>) and a
+ pointer to the timestamp variable that should hold the result of the
+ operation (<code class="literal">ts</code>).
+ </p><p>
+ The function returns 0 on success and a negative value in case of
+ error.
+ </p><p>
+ Internally this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFROMASC"><code class="function">PGTYPEStimestamp_from_asc</code></a> function. See the reference there
+ for a table with example inputs.
+ </p></dd><dt><span class="term"><code class="function">dtcvfmtasc</code></span></dt><dd><p>
+ Parses a timestamp from its textual representation
+ using a format mask into a timestamp variable.
+</p><pre class="synopsis">
+dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
+</pre><p>
+ The function receives the string to parse (<code class="literal">inbuf</code>), the
+ format mask to use (<code class="literal">fmtstr</code>) and a pointer to the timestamp
+ variable that should hold the result of the operation
+ (<code class="literal">dtvalue</code>).
+ </p><p>
+ This function is implemented by means of the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPDEFMTASC"><code class="function">PGTYPEStimestamp_defmt_asc</code></a> function. See the documentation
+ there for a list of format specifiers that can be used.
+ </p><p>
+ The function returns 0 on success and a negative value in case of
+ error.
+ </p></dd><dt><span class="term"><code class="function">dtsub</code></span></dt><dd><p>
+ Subtract one timestamp from another and return a variable of type
+ interval.
+</p><pre class="synopsis">
+int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
+</pre><p>
+ The function will subtract the timestamp variable that <code class="literal">ts2</code>
+ points to from the timestamp variable that <code class="literal">ts1</code> points to
+ and will store the result in the interval variable that <code class="literal">iv</code>
+ points to.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd><dt><span class="term"><code class="function">dttoasc</code></span></dt><dd><p>
+ Convert a timestamp variable to a C char* string.
+</p><pre class="synopsis">
+int dttoasc(timestamp *ts, char *output);
+</pre><p>
+ The function receives a pointer to the timestamp variable to convert
+ (<code class="literal">ts</code>) and the string that should hold the result of the
+ operation (<code class="literal">output</code>). It converts <code class="literal">ts</code> to its
+ textual representation according to the SQL standard, which is
+ be <code class="literal">YYYY-MM-DD HH:MM:SS</code>.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd><dt><span class="term"><code class="function">dttofmtasc</code></span></dt><dd><p>
+ Convert a timestamp variable to a C char* using a format mask.
+</p><pre class="synopsis">
+int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
+</pre><p>
+ The function receives a pointer to the timestamp to convert as its
+ first argument (<code class="literal">ts</code>), a pointer to the output buffer
+ (<code class="literal">output</code>), the maximal length that has been allocated for
+ the output buffer (<code class="literal">str_len</code>) and the format mask to
+ use for the conversion (<code class="literal">fmtstr</code>).
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p><p>
+ Internally, this function uses the <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFMTASC"><code class="function">PGTYPEStimestamp_fmt_asc</code></a> function. See the reference there for
+ information on what format mask specifiers can be used.
+ </p></dd><dt><span class="term"><code class="function">intoasc</code></span></dt><dd><p>
+ Convert an interval variable to a C char* string.
+</p><pre class="synopsis">
+int intoasc(interval *i, char *str);
+</pre><p>
+ The function receives a pointer to the interval variable to convert
+ (<code class="literal">i</code>) and the string that should hold the result of the
+ operation (<code class="literal">str</code>). It converts <code class="literal">i</code> to its
+ textual representation according to the SQL standard, which is
+ be <code class="literal">YYYY-MM-DD HH:MM:SS</code>.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd><dt><span class="term"><code class="function">rfmtlong</code></span></dt><dd><p>
+ Convert a long integer value to its textual representation using a
+ format mask.
+</p><pre class="synopsis">
+int rfmtlong(long lng_val, char *fmt, char *outbuf);
+</pre><p>
+ The function receives the long value <code class="literal">lng_val</code>, the format
+ mask <code class="literal">fmt</code> and a pointer to the output buffer
+ <code class="literal">outbuf</code>. It converts the long value according to the format
+ mask to its textual representation.
+ </p><p>
+ The format mask can be composed of the following format specifying
+ characters:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">*</code> (asterisk) - if this position would be blank
+ otherwise, fill it with an asterisk.
+ </p></li><li class="listitem"><p>
+ <code class="literal">&amp;</code> (ampersand) - if this position would be
+ blank otherwise, fill it with a zero.
+ </p></li><li class="listitem"><p>
+ <code class="literal">#</code> - turn leading zeroes into blanks.
+ </p></li><li class="listitem"><p>
+ <code class="literal">&lt;</code> - left-justify the number in the string.
+ </p></li><li class="listitem"><p>
+ <code class="literal">,</code> (comma) - group numbers of four or more digits
+ into groups of three digits separated by a comma.
+ </p></li><li class="listitem"><p>
+ <code class="literal">.</code> (period) - this character separates the
+ whole-number part of the number from the fractional part.
+ </p></li><li class="listitem"><p>
+ <code class="literal">-</code> (minus) - the minus sign appears if the number
+ is a negative value.
+ </p></li><li class="listitem"><p>
+ <code class="literal">+</code> (plus) - the plus sign appears if the number is
+ a positive value.
+ </p></li><li class="listitem"><p>
+ <code class="literal">(</code> - this replaces the minus sign in front of the
+ negative number. The minus sign will not appear.
+ </p></li><li class="listitem"><p>
+ <code class="literal">)</code> - this character replaces the minus and is
+ printed behind the negative value.
+ </p></li><li class="listitem"><p>
+ <code class="literal">$</code> - the currency symbol.
+ </p></li></ul></div><p>
+ </p></dd><dt><span class="term"><code class="function">rupshift</code></span></dt><dd><p>
+ Convert a string to upper case.
+</p><pre class="synopsis">
+void rupshift(char *str);
+</pre><p>
+ The function receives a pointer to the string and transforms every
+ lower case character to upper case.
+ </p></dd><dt><span class="term"><code class="function">byleng</code></span></dt><dd><p>
+ Return the number of characters in a string without counting trailing
+ blanks.
+</p><pre class="synopsis">
+int byleng(char *str, int len);
+</pre><p>
+ The function expects a fixed-length string as its first argument
+ (<code class="literal">str</code>) and its length as its second argument
+ (<code class="literal">len</code>). It returns the number of significant characters,
+ that is the length of the string without trailing blanks.
+ </p></dd><dt><span class="term"><code class="function">ldchar</code></span></dt><dd><p>
+ Copy a fixed-length string into a null-terminated string.
+</p><pre class="synopsis">
+void ldchar(char *src, int len, char *dest);
+</pre><p>
+ The function receives the fixed-length string to copy
+ (<code class="literal">src</code>), its length (<code class="literal">len</code>) and a pointer to the
+ destination memory (<code class="literal">dest</code>). Note that you need to reserve at
+ least <code class="literal">len+1</code> bytes for the string that <code class="literal">dest</code>
+ points to. The function copies at most <code class="literal">len</code> bytes to the new
+ location (less if the source string has trailing blanks) and adds the
+ null-terminator.
+ </p></dd><dt><span class="term"><code class="function">rgetmsg</code></span></dt><dd><p>
+</p><pre class="synopsis">
+int rgetmsg(int msgnum, char *s, int maxsize);
+</pre><p>
+ This function exists but is not implemented at the moment!
+ </p></dd><dt><span class="term"><code class="function">rtypalign</code></span></dt><dd><p>
+</p><pre class="synopsis">
+int rtypalign(int offset, int type);
+</pre><p>
+ This function exists but is not implemented at the moment!
+ </p></dd><dt><span class="term"><code class="function">rtypmsize</code></span></dt><dd><p>
+</p><pre class="synopsis">
+int rtypmsize(int type, int len);
+</pre><p>
+ This function exists but is not implemented at the moment!
+ </p></dd><dt><span class="term"><code class="function">rtypwidth</code></span></dt><dd><p>
+</p><pre class="synopsis">
+int rtypwidth(int sqltype, int sqllen);
+</pre><p>
+ This function exists but is not implemented at the moment!
+ </p></dd><dt id="RSETNULL"><span class="term"><code class="function">rsetnull</code></span></dt><dd><p>
+ Set a variable to NULL.
+</p><pre class="synopsis">
+int rsetnull(int t, char *ptr);
+</pre><p>
+ The function receives an integer that indicates the type of the
+ variable and a pointer to the variable itself that is cast to a C
+ char* pointer.
+ </p><p>
+ The following types exist:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">CCHARTYPE</code> - For a variable of type <code class="type">char</code> or <code class="type">char*</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CSHORTTYPE</code> - For a variable of type <code class="type">short int</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CINTTYPE</code> - For a variable of type <code class="type">int</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CBOOLTYPE</code> - For a variable of type <code class="type">boolean</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CFLOATTYPE</code> - For a variable of type <code class="type">float</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CLONGTYPE</code> - For a variable of type <code class="type">long</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CDOUBLETYPE</code> - For a variable of type <code class="type">double</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CDECIMALTYPE</code> - For a variable of type <code class="type">decimal</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CDATETYPE</code> - For a variable of type <code class="type">date</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">CDTIMETYPE</code> - For a variable of type <code class="type">timestamp</code>
+ </p></li></ul></div><p>
+ </p><p>
+ Here is an example of a call to this function:
+</p><pre class="programlisting">
+$char c[] = "abc ";
+$short s = 17;
+$int i = -74874;
+
+rsetnull(CCHARTYPE, (char *) c);
+rsetnull(CSHORTTYPE, (char *) &amp;s);
+rsetnull(CINTTYPE, (char *) &amp;i);
+
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">risnull</code></span></dt><dd><p>
+ Test if a variable is NULL.
+</p><pre class="synopsis">
+int risnull(int t, char *ptr);
+</pre><p>
+ The function receives the type of the variable to test (<code class="literal">t</code>)
+ as well a pointer to this variable (<code class="literal">ptr</code>). Note that the
+ latter needs to be cast to a char*. See the function <a class="xref" href="ecpg-informix-compat.html#RSETNULL"><code class="function">rsetnull</code></a> for a list of possible variable types.
+ </p><p>
+ Here is an example of how to use this function:
+</p><pre class="programlisting">
+$char c[] = "abc ";
+$short s = 17;
+$int i = -74874;
+
+risnull(CCHARTYPE, (char *) c);
+risnull(CSHORTTYPE, (char *) &amp;s);
+risnull(CINTTYPE, (char *) &amp;i);
+
+</pre><p>
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-INFORMIX-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">36.15.5. Additional Constants</h3></div></div></div><p>
+ Note that all constants here describe errors and all of them are defined
+ to represent negative values. In the descriptions of the different
+ constants you can also find the value that the constants represent in the
+ current implementation. However you should not rely on this number. You can
+ however rely on the fact all of them are defined to represent negative
+ values.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ECPG_INFORMIX_NUM_OVERFLOW</code></span></dt><dd><p>
+ Functions return this value if an overflow occurred in a
+ calculation. Internally it is defined as -1200 (the <span class="productname">Informix</span>
+ definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_NUM_UNDERFLOW</code></span></dt><dd><p>
+ Functions return this value if an underflow occurred in a calculation.
+ Internally it is defined as -1201 (the <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_DIVIDE_ZERO</code></span></dt><dd><p>
+ Functions return this value if an attempt to divide by zero is
+ observed. Internally it is defined as -1202 (the <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_YEAR</code></span></dt><dd><p>
+ Functions return this value if a bad value for a year was found while
+ parsing a date. Internally it is defined as -1204 (the <span class="productname">Informix</span>
+ definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_MONTH</code></span></dt><dd><p>
+ Functions return this value if a bad value for a month was found while
+ parsing a date. Internally it is defined as -1205 (the <span class="productname">Informix</span>
+ definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_DAY</code></span></dt><dd><p>
+ Functions return this value if a bad value for a day was found while
+ parsing a date. Internally it is defined as -1206 (the <span class="productname">Informix</span>
+ definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_ENOSHORTDATE</code></span></dt><dd><p>
+ Functions return this value if a parsing routine needs a short date
+ representation but did not get the date string in the right length.
+ Internally it is defined as -1209 (the <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_DATE_CONVERT</code></span></dt><dd><p>
+ Functions return this value if an error occurred during date
+ formatting. Internally it is defined as -1210 (the
+ <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_OUT_OF_MEMORY</code></span></dt><dd><p>
+ Functions return this value if memory was exhausted during
+ their operation. Internally it is defined as -1211 (the
+ <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_ENOTDMY</code></span></dt><dd><p>
+ Functions return this value if a parsing routine was supposed to get a
+ format mask (like <code class="literal">mmddyy</code>) but not all fields were listed
+ correctly. Internally it is defined as -1212 (the <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_NUMERIC</code></span></dt><dd><p>
+ Functions return this value either if a parsing routine cannot parse
+ the textual representation for a numeric value because it contains
+ errors or if a routine cannot complete a calculation involving numeric
+ variables because at least one of the numeric variables is invalid.
+ Internally it is defined as -1213 (the <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_EXPONENT</code></span></dt><dd><p>
+ Functions return this value if a parsing routine cannot parse
+ an exponent. Internally it is defined as -1216 (the
+ <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_BAD_DATE</code></span></dt><dd><p>
+ Functions return this value if a parsing routine cannot parse
+ a date. Internally it is defined as -1218 (the
+ <span class="productname">Informix</span> definition).
+ </p></dd><dt><span class="term"><code class="literal">ECPG_INFORMIX_EXTRA_CHARS</code></span></dt><dd><p>
+ Functions return this value if a parsing routine is passed extra
+ characters it cannot parse. Internally it is defined as -1264 (the
+ <span class="productname">Informix</span> definition).
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-whenever.html" title="WHENEVER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">WHENEVER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.16. <span class="productname">Oracle</span> Compatibility Mode</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-library.html b/doc/src/sgml/html/ecpg-library.html
new file mode 100644
index 0000000..24b374b
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-library.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.11. Library Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs" /><link rel="next" href="ecpg-lo.html" title="36.12. Large Objects" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.11. Library Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-lo.html" title="36.12. Large Objects">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-LIBRARY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.11. Library Functions</h2></div></div></div><p>
+ The <code class="filename">libecpg</code> library primarily contains
+ <span class="quote">“<span class="quote">hidden</span>”</span> functions that are used to implement the
+ functionality expressed by the embedded SQL commands. But there
+ are some functions that can usefully be called directly. Note that
+ this makes your code unportable.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="function">ECPGdebug(int <em class="replaceable"><code>on</code></em>, FILE
+ *<em class="replaceable"><code>stream</code></em>)</code> turns on debug
+ logging if called with the first argument non-zero. Debug logging
+ is done on <em class="replaceable"><code>stream</code></em>. The log contains
+ all <acronym class="acronym">SQL</acronym> statements with all the input
+ variables inserted, and the results from the
+ <span class="productname">PostgreSQL</span> server. This can be very
+ useful when searching for errors in your <acronym class="acronym">SQL</acronym>
+ statements.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On Windows, if the <span class="application">ecpg</span> libraries and an application are
+ compiled with different flags, this function call will crash the
+ application because the internal representation of the
+ <code class="literal">FILE</code> pointers differ. Specifically,
+ multithreaded/single-threaded, release/debug, and static/dynamic
+ flags should be the same for the library and all applications using
+ that library.
+ </p></div></li><li class="listitem"><p>
+ <code class="function">ECPGget_PGconn(const char *<em class="replaceable"><code>connection_name</code></em>)
+ </code> returns the library database connection handle identified by the given name.
+ If <em class="replaceable"><code>connection_name</code></em> is set to <code class="literal">NULL</code>, the current
+ connection handle is returned. If no connection handle can be identified, the function returns
+ <code class="literal">NULL</code>. The returned connection handle can be used to call any other functions
+ from <span class="application">libpq</span>, if necessary.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ It is a bad idea to manipulate database connection handles made from <span class="application">ecpg</span> directly
+ with <span class="application">libpq</span> routines.
+ </p></div></li><li class="listitem"><p>
+ <code class="function">ECPGtransactionStatus(const char *<em class="replaceable"><code>connection_name</code></em>)</code>
+ returns the current transaction status of the given connection identified by <em class="replaceable"><code>connection_name</code></em>.
+ See <a class="xref" href="libpq-status.html" title="34.2. Connection Status Functions">Section 34.2</a> and libpq's <a class="xref" href="libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS"><code class="function">PQtransactionStatus</code></a> for details about the returned status codes.
+ </p></li><li class="listitem"><p>
+ <code class="function">ECPGstatus(int <em class="replaceable"><code>lineno</code></em>,
+ const char* <em class="replaceable"><code>connection_name</code></em>)</code>
+ returns true if you are connected to a database and false if not.
+ <em class="replaceable"><code>connection_name</code></em> can be <code class="literal">NULL</code>
+ if a single connection is being used.
+ </p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-lo.html" title="36.12. Large Objects">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.10. Processing Embedded SQL Programs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.12. Large Objects</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-lo.html b/doc/src/sgml/html/ecpg-lo.html
new file mode 100644
index 0000000..bf9e1b1
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-lo.html
@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.12. Large Objects</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-library.html" title="36.11. Library Functions" /><link rel="next" href="ecpg-cpp.html" title="36.13. C++ Applications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.12. Large Objects</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-library.html" title="36.11. Library Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-cpp.html" title="36.13. C++ Applications">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-LO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.12. Large Objects</h2></div></div></div><p>
+ Large objects are not directly supported by ECPG, but ECPG
+ application can manipulate large objects through the libpq large
+ object functions, obtaining the necessary <code class="type">PGconn</code>
+ object by calling the <code class="function">ECPGget_PGconn()</code>
+ function. (However, use of
+ the <code class="function">ECPGget_PGconn()</code> function and touching
+ <code class="type">PGconn</code> objects directly should be done very carefully
+ and ideally not mixed with other ECPG database access calls.)
+ </p><p>
+ For more details about the <code class="function">ECPGget_PGconn()</code>, see
+ <a class="xref" href="ecpg-library.html" title="36.11. Library Functions">Section 36.11</a>. For information about the large
+ object function interface, see <a class="xref" href="largeobjects.html" title="Chapter 35. Large Objects">Chapter 35</a>.
+ </p><p>
+ Large object functions have to be called in a transaction block, so
+ when autocommit is off, <code class="command">BEGIN</code> commands have to
+ be issued explicitly.
+ </p><p>
+ <a class="xref" href="ecpg-lo.html#ECPG-LO-EXAMPLE" title="Example 36.2. ECPG Program Accessing Large Objects">Example 36.2</a> shows an example program that
+ illustrates how to create, write, and read a large object in an
+ ECPG application.
+ </p><div class="example" id="ECPG-LO-EXAMPLE"><p class="title"><strong>Example 36.2. ECPG Program Accessing Large Objects</strong></p><div class="example-contents"><pre class="programlisting">
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;libpq-fe.h&gt;
+#include &lt;libpq/libpq-fs.h&gt;
+
+EXEC SQL WHENEVER SQLERROR STOP;
+
+int
+main(void)
+{
+ PGconn *conn;
+ Oid loid;
+ int fd;
+ char buf[256];
+ int buflen = 256;
+ char buf2[256];
+ int rc;
+
+ memset(buf, 1, buflen);
+
+ EXEC SQL CONNECT TO testdb AS con1;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ conn = ECPGget_PGconn("con1");
+ printf("conn = %p\n", conn);
+
+ /* create */
+ loid = lo_create(conn, 0);
+ if (loid &amp;lt; 0)
+ printf("lo_create() failed: %s", PQerrorMessage(conn));
+
+ printf("loid = %d\n", loid);
+
+ /* write test */
+ fd = lo_open(conn, loid, INV_READ|INV_WRITE);
+ if (fd &amp;lt; 0)
+ printf("lo_open() failed: %s", PQerrorMessage(conn));
+
+ printf("fd = %d\n", fd);
+
+ rc = lo_write(conn, fd, buf, buflen);
+ if (rc &amp;lt; 0)
+ printf("lo_write() failed\n");
+
+ rc = lo_close(conn, fd);
+ if (rc &amp;lt; 0)
+ printf("lo_close() failed: %s", PQerrorMessage(conn));
+
+ /* read test */
+ fd = lo_open(conn, loid, INV_READ);
+ if (fd &amp;lt; 0)
+ printf("lo_open() failed: %s", PQerrorMessage(conn));
+
+ printf("fd = %d\n", fd);
+
+ rc = lo_read(conn, fd, buf2, buflen);
+ if (rc &amp;lt; 0)
+ printf("lo_read() failed\n");
+
+ rc = lo_close(conn, fd);
+ if (rc &amp;lt; 0)
+ printf("lo_close() failed: %s", PQerrorMessage(conn));
+
+ /* check */
+ rc = memcmp(buf, buf2, buflen);
+ printf("memcmp() = %d\n", rc);
+
+ /* cleanup */
+ rc = lo_unlink(conn, loid);
+ if (rc &amp;lt; 0)
+ printf("lo_unlink() failed: %s", PQerrorMessage(conn));
+
+ EXEC SQL COMMIT;
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-library.html" title="36.11. Library Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-cpp.html" title="36.13. C++ Applications">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.11. Library Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.13. <acronym class="acronym">C++</acronym> Applications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-oracle-compat.html b/doc/src/sgml/html/ecpg-oracle-compat.html
new file mode 100644
index 0000000..372b09f
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-oracle-compat.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.16. Oracle Compatibility Mode</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode" /><link rel="next" href="ecpg-develop.html" title="36.17. Internals" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.16. <span class="productname">Oracle</span> Compatibility Mode</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-develop.html" title="36.17. Internals">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-ORACLE-COMPAT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.16. <span class="productname">Oracle</span> Compatibility Mode</h2></div></div></div><p>
+ <code class="command">ecpg</code> can be run in a so-called <em class="firstterm">Oracle
+ compatibility mode</em>. If this mode is active, it tries to
+ behave as if it were Oracle <span class="productname">Pro*C</span>.
+ </p><p>
+ Specifically, this mode changes <code class="command">ecpg</code> in three ways:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Pad character arrays receiving character string types with
+ trailing spaces to the specified length
+ </p></li><li class="listitem"><p>
+ Zero byte terminate these character arrays, and set the indicator
+ variable if truncation occurs
+ </p></li><li class="listitem"><p>
+ Set the null indicator to <code class="literal">-1</code> when character
+ arrays receive empty character string types
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-develop.html" title="36.17. Internals">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.15. <span class="productname">Informix</span> Compatibility Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.17. Internals</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-pgtypes.html b/doc/src/sgml/html/ecpg-pgtypes.html
new file mode 100644
index 0000000..3ec3666
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-pgtypes.html
@@ -0,0 +1,765 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.6. pgtypes Library</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-dynamic.html" title="36.5. Dynamic SQL" /><link rel="next" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.6. pgtypes Library</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-dynamic.html" title="36.5. Dynamic SQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-PGTYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.6. pgtypes Library</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CSTRINGS">36.6.1. Character Strings</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-NUMERIC">36.6.2. The numeric Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DATE">36.6.3. The date Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-TIMESTAMP">36.6.4. The timestamp Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-INTERVAL">36.6.5. The interval Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DECIMAL">36.6.6. The decimal Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-ERRNO">36.6.7. errno Values of pgtypeslib</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CONSTANTS">36.6.8. Special Constants of pgtypeslib</a></span></dt></dl></div><p>
+ The pgtypes library maps <span class="productname">PostgreSQL</span> database
+ types to C equivalents that can be used in C programs. It also offers
+ functions to do basic calculations with those types within C, i.e., without
+ the help of the <span class="productname">PostgreSQL</span> server. See the
+ following example:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ date date1;
+ timestamp ts1, tsout;
+ interval iv1;
+ char *out;
+EXEC SQL END DECLARE SECTION;
+
+PGTYPESdate_today(&amp;date1);
+EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
+PGTYPEStimestamp_add_interval(&amp;ts1, &amp;iv1, &amp;tsout);
+out = PGTYPEStimestamp_to_asc(&amp;tsout);
+printf("Started + duration: %s\n", out);
+PGTYPESchar_free(out);
+
+</pre><p>
+ </p><div class="sect2" id="ECPG-PGTYPES-CSTRINGS"><div class="titlepage"><div><div><h3 class="title">36.6.1. Character Strings</h3></div></div></div><p>
+ Some functions such as <code class="function">PGTYPESnumeric_to_asc</code> return
+ a pointer to a freshly allocated character string. These results should be
+ freed with <code class="function">PGTYPESchar_free</code> instead of
+ <code class="function">free</code>. (This is important only on Windows, where
+ memory allocation and release sometimes need to be done by the same
+ library.)
+ </p></div><div class="sect2" id="ECPG-PGTYPES-NUMERIC"><div class="titlepage"><div><div><h3 class="title">36.6.2. The numeric Type</h3></div></div></div><p>
+ The numeric type offers to do calculations with arbitrary precision. See
+ <a class="xref" href="datatype-numeric.html" title="8.1. Numeric Types">Section 8.1</a> for the equivalent type in the
+ <span class="productname">PostgreSQL</span> 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
+ <code class="function">PGTYPESnumeric_new</code> and <code class="function">PGTYPESnumeric_free</code>
+ functions. The decimal type, which is similar but limited in precision,
+ can be created on the stack as well as on the heap.
+ </p><p>
+ The following functions can be used to work with the numeric type:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">PGTYPESnumeric_new</code></span></dt><dd><p>
+ Request a pointer to a newly allocated numeric variable.
+</p><pre class="synopsis">
+numeric *PGTYPESnumeric_new(void);
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_free</code></span></dt><dd><p>
+ Free a numeric type, release all of its memory.
+</p><pre class="synopsis">
+void PGTYPESnumeric_free(numeric *var);
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_from_asc</code></span></dt><dd><p>
+ Parse a numeric type from its string notation.
+</p><pre class="synopsis">
+numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
+</pre><p>
+ Valid formats are for example:
+ <code class="literal">-2</code>,
+ <code class="literal">.794</code>,
+ <code class="literal">+3.44</code>,
+ <code class="literal">592.49E07</code> or
+ <code class="literal">-32.84e-4</code>.
+ If the value could be parsed successfully, a valid pointer is returned,
+ else the NULL pointer. At the moment ECPG always parses the complete
+ string and so it currently does not support to store the address of the
+ first invalid character in <code class="literal">*endptr</code>. You can safely
+ set <code class="literal">endptr</code> to NULL.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_to_asc</code></span></dt><dd><p>
+ Returns a pointer to a string allocated by <code class="function">malloc</code> that contains the string
+ representation of the numeric type <code class="literal">num</code>.
+</p><pre class="synopsis">
+char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
+</pre><p>
+ The numeric value will be printed with <code class="literal">dscale</code> decimal
+ digits, with rounding applied if necessary.
+ The result must be freed with <code class="function">PGTYPESchar_free()</code>.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_add</code></span></dt><dd><p>
+ Add two numeric variables into a third one.
+</p><pre class="synopsis">
+int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
+</pre><p>
+ The function adds the variables <code class="literal">var1</code> and
+ <code class="literal">var2</code> into the result variable
+ <code class="literal">result</code>.
+ The function returns 0 on success and -1 in case of error.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_sub</code></span></dt><dd><p>
+ Subtract two numeric variables and return the result in a third one.
+</p><pre class="synopsis">
+int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
+</pre><p>
+ The function subtracts the variable <code class="literal">var2</code> from
+ the variable <code class="literal">var1</code>. The result of the operation is
+ stored in the variable <code class="literal">result</code>.
+ The function returns 0 on success and -1 in case of error.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_mul</code></span></dt><dd><p>
+ Multiply two numeric variables and return the result in a third one.
+</p><pre class="synopsis">
+int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
+</pre><p>
+ The function multiplies the variables <code class="literal">var1</code> and
+ <code class="literal">var2</code>. The result of the operation is stored in the
+ variable <code class="literal">result</code>.
+ The function returns 0 on success and -1 in case of error.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_div</code></span></dt><dd><p>
+ Divide two numeric variables and return the result in a third one.
+</p><pre class="synopsis">
+int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
+</pre><p>
+ The function divides the variables <code class="literal">var1</code> by
+ <code class="literal">var2</code>. The result of the operation is stored in the
+ variable <code class="literal">result</code>.
+ The function returns 0 on success and -1 in case of error.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_cmp</code></span></dt><dd><p>
+ Compare two numeric variables.
+</p><pre class="synopsis">
+int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
+</pre><p>
+ This function compares two numeric variables. In case of error,
+ <code class="literal">INT_MAX</code> is returned. On success, the function
+ returns one of three possible results:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 1, if <code class="literal">var1</code> is bigger than <code class="literal">var2</code>
+ </p></li><li class="listitem"><p>
+ -1, if <code class="literal">var1</code> is smaller than <code class="literal">var2</code>
+ </p></li><li class="listitem"><p>
+ 0, if <code class="literal">var1</code> and <code class="literal">var2</code> are equal
+ </p></li></ul></div><p>
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_from_int</code></span></dt><dd><p>
+ Convert an int variable to a numeric variable.
+</p><pre class="synopsis">
+int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
+</pre><p>
+ This function accepts a variable of type signed int and stores it
+ in the numeric variable <code class="literal">var</code>. Upon success, 0 is returned and
+ -1 in case of a failure.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_from_long</code></span></dt><dd><p>
+ Convert a long int variable to a numeric variable.
+</p><pre class="synopsis">
+int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
+</pre><p>
+ This function accepts a variable of type signed long int and stores it
+ in the numeric variable <code class="literal">var</code>. Upon success, 0 is returned and
+ -1 in case of a failure.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_copy</code></span></dt><dd><p>
+ Copy over one numeric variable into another one.
+</p><pre class="synopsis">
+int PGTYPESnumeric_copy(numeric *src, numeric *dst);
+</pre><p>
+ This function copies over the value of the variable that
+ <code class="literal">src</code> points to into the variable that <code class="literal">dst</code>
+ points to. It returns 0 on success and -1 if an error occurs.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_from_double</code></span></dt><dd><p>
+ Convert a variable of type double to a numeric.
+</p><pre class="synopsis">
+int PGTYPESnumeric_from_double(double d, numeric *dst);
+</pre><p>
+ This function accepts a variable of type double and stores the result
+ in the variable that <code class="literal">dst</code> points to. It returns 0 on success
+ and -1 if an error occurs.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_to_double</code></span></dt><dd><p>
+ Convert a variable of type numeric to double.
+</p><pre class="synopsis">
+int PGTYPESnumeric_to_double(numeric *nv, double *dp)
+</pre><p>
+ The function converts the numeric value from the variable that
+ <code class="literal">nv</code> points to into the double variable that <code class="literal">dp</code> points
+ to. It returns 0 on success and -1 if an error occurs, including
+ overflow. On overflow, the global variable <code class="literal">errno</code> will be set
+ to <code class="literal">PGTYPES_NUM_OVERFLOW</code> additionally.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_to_int</code></span></dt><dd><p>
+ Convert a variable of type numeric to int.
+</p><pre class="synopsis">
+int PGTYPESnumeric_to_int(numeric *nv, int *ip);
+</pre><p>
+ The function converts the numeric value from the variable that
+ <code class="literal">nv</code> points to into the integer variable that <code class="literal">ip</code>
+ points to. It returns 0 on success and -1 if an error occurs, including
+ overflow. On overflow, the global variable <code class="literal">errno</code> will be set
+ to <code class="literal">PGTYPES_NUM_OVERFLOW</code> additionally.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_to_long</code></span></dt><dd><p>
+ Convert a variable of type numeric to long.
+</p><pre class="synopsis">
+int PGTYPESnumeric_to_long(numeric *nv, long *lp);
+</pre><p>
+ The function converts the numeric value from the variable that
+ <code class="literal">nv</code> points to into the long integer variable that
+ <code class="literal">lp</code> points to. It returns 0 on success and -1 if an error
+ occurs, including overflow. On overflow, the global variable
+ <code class="literal">errno</code> will be set to <code class="literal">PGTYPES_NUM_OVERFLOW</code>
+ additionally.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_to_decimal</code></span></dt><dd><p>
+ Convert a variable of type numeric to decimal.
+</p><pre class="synopsis">
+int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
+</pre><p>
+ The function converts the numeric value from the variable that
+ <code class="literal">src</code> points to into the decimal variable that
+ <code class="literal">dst</code> points to. It returns 0 on success and -1 if an error
+ occurs, including overflow. On overflow, the global variable
+ <code class="literal">errno</code> will be set to <code class="literal">PGTYPES_NUM_OVERFLOW</code>
+ additionally.
+ </p></dd><dt><span class="term"><code class="function">PGTYPESnumeric_from_decimal</code></span></dt><dd><p>
+ Convert a variable of type decimal to numeric.
+</p><pre class="synopsis">
+int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
+</pre><p>
+ The function converts the decimal value from the variable that
+ <code class="literal">src</code> points to into the numeric variable that
+ <code class="literal">dst</code> points to. It returns 0 on success and -1 if an error
+ occurs. Since the decimal type is implemented as a limited version of
+ the numeric type, overflow cannot occur with this conversion.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-DATE"><div class="titlepage"><div><div><h3 class="title">36.6.3. The date Type</h3></div></div></div><p>
+ The date type in C enables your programs to deal with data of the SQL type
+ date. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent type in the
+ <span class="productname">PostgreSQL</span> server.
+ </p><p>
+ The following functions can be used to work with the date type:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESDATEFROMTIMESTAMP"><span class="term"><code class="function">PGTYPESdate_from_timestamp</code></span></dt><dd><p>
+ Extract the date part from a timestamp.
+</p><pre class="synopsis">
+date PGTYPESdate_from_timestamp(timestamp dt);
+</pre><p>
+ The function receives a timestamp as its only argument and returns the
+ extracted date part from this timestamp.
+ </p></dd><dt id="PGTYPESDATEFROMASC"><span class="term"><code class="function">PGTYPESdate_from_asc</code></span></dt><dd><p>
+ Parse a date from its textual representation.
+</p><pre class="synopsis">
+date PGTYPESdate_from_asc(char *str, char **endptr);
+</pre><p>
+ The function receives a C char* string <code class="literal">str</code> and a pointer to
+ a C char* string <code class="literal">endptr</code>. At the moment ECPG always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <code class="literal">*endptr</code>.
+ You can safely set <code class="literal">endptr</code> to NULL.
+ </p><p>
+ Note that the function always assumes MDY-formatted dates and there is
+ currently no variable to change that within ECPG.
+ </p><p>
+ <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESDATE-FROM-ASC-TABLE" title="Table 36.2. Valid Input Formats for PGTYPESdate_from_asc">Table 36.2</a> shows the allowed input formats.
+ </p><div class="table" id="ECPG-PGTYPESDATE-FROM-ASC-TABLE"><p class="title"><strong>Table 36.2. Valid Input Formats for <code class="function">PGTYPESdate_from_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPESdate_from_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Input</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">January 8, 1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1999-01-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1/8/1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">1/18/1999</code></td><td><code class="literal">January 18, 1999</code></td></tr><tr><td><code class="literal">01/02/03</code></td><td><code class="literal">February 1, 2003</code></td></tr><tr><td><code class="literal">1999-Jan-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">Jan-08-1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-1999</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">99-Jan-08</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-99</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">08-Jan-06</code></td><td><code class="literal">January 8, 2006</code></td></tr><tr><td><code class="literal">Jan-08-99</code></td><td><code class="literal">January 8, 1999</code></td></tr><tr><td><code class="literal">19990108</code></td><td><code class="literal">ISO 8601; January 8, 1999</code></td></tr><tr><td><code class="literal">990108</code></td><td><code class="literal">ISO 8601; January 8, 1999</code></td></tr><tr><td><code class="literal">1999.008</code></td><td><code class="literal">year and day of year</code></td></tr><tr><td><code class="literal">J2451187</code></td><td><code class="literal">Julian day</code></td></tr><tr><td><code class="literal">January 8, 99 BC</code></td><td><code class="literal">year 99 before the Common Era</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESDATETOASC"><span class="term"><code class="function">PGTYPESdate_to_asc</code></span></dt><dd><p>
+ Return the textual representation of a date variable.
+</p><pre class="synopsis">
+char *PGTYPESdate_to_asc(date dDate);
+</pre><p>
+ The function receives the date <code class="literal">dDate</code> as its only parameter.
+ It will output the date in the form <code class="literal">1999-01-18</code>, i.e., in the
+ <code class="literal">YYYY-MM-DD</code> format.
+ The result must be freed with <code class="function">PGTYPESchar_free()</code>.
+ </p></dd><dt id="PGTYPESDATEJULMDY"><span class="term"><code class="function">PGTYPESdate_julmdy</code></span></dt><dd><p>
+ Extract the values for the day, the month and the year from a variable
+ of type date.
+</p><pre class="synopsis">
+void PGTYPESdate_julmdy(date d, int *mdy);
+</pre><p>
+
+ The function receives the date <code class="literal">d</code> and a pointer to an array
+ of 3 integer values <code class="literal">mdy</code>. The variable name indicates
+ the sequential order: <code class="literal">mdy[0]</code> will be set to contain the
+ number of the month, <code class="literal">mdy[1]</code> will be set to the value of the
+ day and <code class="literal">mdy[2]</code> will contain the year.
+ </p></dd><dt id="PGTYPESDATEMDYJUL"><span class="term"><code class="function">PGTYPESdate_mdyjul</code></span></dt><dd><p>
+ Create a date value from an array of 3 integers that specify the
+ day, the month and the year of the date.
+</p><pre class="synopsis">
+void PGTYPESdate_mdyjul(int *mdy, date *jdate);
+</pre><p>
+ The function receives the array of the 3 integers (<code class="literal">mdy</code>) as
+ its first argument and as its second argument a pointer to a variable
+ of type date that should hold the result of the operation.
+ </p></dd><dt id="PGTYPESDATEDAYOFWEEK"><span class="term"><code class="function">PGTYPESdate_dayofweek</code></span></dt><dd><p>
+ Return a number representing the day of the week for a date value.
+</p><pre class="synopsis">
+int PGTYPESdate_dayofweek(date d);
+</pre><p>
+ The function receives the date variable <code class="literal">d</code> as its only
+ argument and returns an integer that indicates the day of the week for
+ this date.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 0 - Sunday
+ </p></li><li class="listitem"><p>
+ 1 - Monday
+ </p></li><li class="listitem"><p>
+ 2 - Tuesday
+ </p></li><li class="listitem"><p>
+ 3 - Wednesday
+ </p></li><li class="listitem"><p>
+ 4 - Thursday
+ </p></li><li class="listitem"><p>
+ 5 - Friday
+ </p></li><li class="listitem"><p>
+ 6 - Saturday
+ </p></li></ul></div><p>
+ </p></dd><dt id="PGTYPESDATETODAY"><span class="term"><code class="function">PGTYPESdate_today</code></span></dt><dd><p>
+ Get the current date.
+</p><pre class="synopsis">
+void PGTYPESdate_today(date *d);
+</pre><p>
+ The function receives a pointer to a date variable (<code class="literal">d</code>)
+ that it sets to the current date.
+ </p></dd><dt id="PGTYPESDATEFMTASC"><span class="term"><code class="function">PGTYPESdate_fmt_asc</code></span></dt><dd><p>
+ Convert a variable of type date to its textual representation using a
+ format mask.
+</p><pre class="synopsis">
+int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
+</pre><p>
+ The function receives the date to convert (<code class="literal">dDate</code>), the
+ format mask (<code class="literal">fmtstring</code>) and the string that will hold the
+ textual representation of the date (<code class="literal">outbuf</code>).
+ </p><p>
+ On success, 0 is returned and a negative value if an error occurred.
+ </p><p>
+ The following literals are the field specifiers you can use:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">dd</code> - The number of the day of the month.
+ </p></li><li class="listitem"><p>
+ <code class="literal">mm</code> - The number of the month of the year.
+ </p></li><li class="listitem"><p>
+ <code class="literal">yy</code> - The number of the year as a two digit number.
+ </p></li><li class="listitem"><p>
+ <code class="literal">yyyy</code> - The number of the year as a four digit number.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ddd</code> - The name of the day (abbreviated).
+ </p></li><li class="listitem"><p>
+ <code class="literal">mmm</code> - The name of the month (abbreviated).
+ </p></li></ul></div><p>
+ All other characters are copied 1:1 to the output string.
+ </p><p>
+ <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESDATE-FMT-ASC-EXAMPLE-TABLE" title="Table 36.3. Valid Input Formats for PGTYPESdate_fmt_asc">Table 36.3</a> 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.
+ </p><div class="table" id="ECPG-PGTYPESDATE-FMT-ASC-EXAMPLE-TABLE"><p class="title"><strong>Table 36.3. Valid Input Formats for <code class="function">PGTYPESdate_fmt_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPESdate_fmt_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Format</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">mmddyy</code></td><td><code class="literal">112359</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">231159</code></td></tr><tr><td><code class="literal">yymmdd</code></td><td><code class="literal">591123</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">59/11/23</code></td></tr><tr><td><code class="literal">yy mm dd</code></td><td><code class="literal">59 11 23</code></td></tr><tr><td><code class="literal">yy.mm.dd</code></td><td><code class="literal">59.11.23</code></td></tr><tr><td><code class="literal">.mm.yyyy.dd.</code></td><td><code class="literal">.11.1959.23.</code></td></tr><tr><td><code class="literal">mmm. dd, yyyy</code></td><td><code class="literal">Nov. 23, 1959</code></td></tr><tr><td><code class="literal">mmm dd yyyy</code></td><td><code class="literal">Nov 23 1959</code></td></tr><tr><td><code class="literal">yyyy dd mm</code></td><td><code class="literal">1959 23 11</code></td></tr><tr><td><code class="literal">ddd, mmm. dd, yyyy</code></td><td><code class="literal">Mon, Nov. 23, 1959</code></td></tr><tr><td><code class="literal">(ddd) mmm. dd, yyyy</code></td><td><code class="literal">(Mon) Nov. 23, 1959</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESDATEDEFMTASC"><span class="term"><code class="function">PGTYPESdate_defmt_asc</code></span></dt><dd><p>
+ Use a format mask to convert a C <code class="type">char*</code> string to a value of type
+ date.
+</p><pre class="synopsis">
+int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
+</pre><p>
+
+ The function receives a pointer to the date value that should hold the
+ result of the operation (<code class="literal">d</code>), the format mask to use for
+ parsing the date (<code class="literal">fmt</code>) and the C char* string containing
+ the textual representation of the date (<code class="literal">str</code>). The textual
+ representation is expected to match the format mask. However you do not
+ need to have a 1:1 mapping of the string to the format mask. The
+ function only analyzes the sequential order and looks for the literals
+ <code class="literal">yy</code> or <code class="literal">yyyy</code> that indicate the
+ position of the year, <code class="literal">mm</code> to indicate the position of
+ the month and <code class="literal">dd</code> to indicate the position of the
+ day.
+ </p><p>
+ <a class="xref" href="ecpg-pgtypes.html#ECPG-RDEFMTDATE-EXAMPLE-TABLE" title="Table 36.4. Valid Input Formats for rdefmtdate">Table 36.4</a> indicates a few possible formats. This will give
+ you an idea of how to use this function.
+ </p><div class="table" id="ECPG-RDEFMTDATE-EXAMPLE-TABLE"><p class="title"><strong>Table 36.4. Valid Input Formats for <code class="function">rdefmtdate</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for rdefmtdate" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Format</th><th>String</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">21-2-54</code></td><td><code class="literal">1954-02-21</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">2-12-54</code></td><td><code class="literal">1954-12-02</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">20111954</code></td><td><code class="literal">1954-11-20</code></td></tr><tr><td><code class="literal">ddmmyy</code></td><td><code class="literal">130464</code></td><td><code class="literal">1964-04-13</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">MAR-12-1967</code></td><td><code class="literal">1967-03-12</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">1954, February 3rd</code></td><td><code class="literal">1954-02-03</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">041269</code></td><td><code class="literal">1969-04-12</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">In the year 2525, in the month of July, mankind will be alive on the 28th day</code></td><td><code class="literal">2525-07-28</code></td></tr><tr><td><code class="literal">dd-mm-yy</code></td><td><code class="literal">I said on the 28th of July in the year 2525</code></td><td><code class="literal">2525-07-28</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">9/14/58</code></td><td><code class="literal">1958-09-14</code></td></tr><tr><td><code class="literal">yy/mm/dd</code></td><td><code class="literal">47/03/29</code></td><td><code class="literal">1947-03-29</code></td></tr><tr><td><code class="literal">mmm.dd.yyyy</code></td><td><code class="literal">oct 28 1975</code></td><td><code class="literal">1975-10-28</code></td></tr><tr><td><code class="literal">mmddyy</code></td><td><code class="literal">Nov 14th, 1985</code></td><td><code class="literal">1985-11-14</code></td></tr></tbody></table></div></div><br class="table-break" /></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-TIMESTAMP"><div class="titlepage"><div><div><h3 class="title">36.6.4. The timestamp Type</h3></div></div></div><p>
+ The timestamp type in C enables your programs to deal with data of the SQL
+ type timestamp. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent
+ type in the <span class="productname">PostgreSQL</span> server.
+ </p><p>
+ The following functions can be used to work with the timestamp type:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESTIMESTAMPFROMASC"><span class="term"><code class="function">PGTYPEStimestamp_from_asc</code></span></dt><dd><p>
+ Parse a timestamp from its textual representation into a timestamp
+ variable.
+</p><pre class="synopsis">
+timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
+</pre><p>
+ The function receives the string to parse (<code class="literal">str</code>) and a
+ pointer to a C char* (<code class="literal">endptr</code>).
+ At the moment ECPG always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <code class="literal">*endptr</code>.
+ You can safely set <code class="literal">endptr</code> to NULL.
+ </p><p>
+ The function returns the parsed timestamp on success. On error,
+ <code class="literal">PGTYPESInvalidTimestamp</code> is returned and <code class="varname">errno</code> is
+ set to <code class="literal">PGTYPES_TS_BAD_TIMESTAMP</code>. See <a class="xref" href="ecpg-pgtypes.html#PGTYPESINVALIDTIMESTAMP"><code class="literal">PGTYPESInvalidTimestamp</code></a> for important notes on this value.
+ </p><p>
+ In general, the input string can contain any combination of an allowed
+ date specification, a whitespace character and an allowed time
+ specification. Note that time zones are not supported by ECPG. It can
+ parse them but does not apply any calculation as the
+ <span class="productname">PostgreSQL</span> server does for example. Timezone
+ specifiers are silently discarded.
+ </p><p>
+ <a class="xref" href="ecpg-pgtypes.html#ECPG-PGTYPESTIMESTAMP-FROM-ASC-EXAMPLE-TABLE" title="Table 36.5. Valid Input Formats for PGTYPEStimestamp_from_asc">Table 36.5</a> contains a few examples for input strings.
+ </p><div class="table" id="ECPG-PGTYPESTIMESTAMP-FROM-ASC-EXAMPLE-TABLE"><p class="title"><strong>Table 36.5. Valid Input Formats for <code class="function">PGTYPEStimestamp_from_asc</code></strong></p><div class="table-contents"><table class="table" summary="Valid Input Formats for PGTYPEStimestamp_from_asc" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Input</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">1999-01-08 04:05:06</code></td><td><code class="literal">1999-01-08 04:05:06</code></td></tr><tr><td><code class="literal">January 8 04:05:06 1999 PST</code></td><td><code class="literal">1999-01-08 04:05:06</code></td></tr><tr><td><code class="literal">1999-Jan-08 04:05:06.789-8</code></td><td><code class="literal">1999-01-08 04:05:06.789 (time zone specifier ignored)</code></td></tr><tr><td><code class="literal">J2451187 04:05-08:00</code></td><td><code class="literal">1999-01-08 04:05:00 (time zone specifier ignored)</code></td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="PGTYPESTIMESTAMPTOASC"><span class="term"><code class="function">PGTYPEStimestamp_to_asc</code></span></dt><dd><p>
+ Converts a date to a C char* string.
+</p><pre class="synopsis">
+char *PGTYPEStimestamp_to_asc(timestamp tstamp);
+</pre><p>
+ The function receives the timestamp <code class="literal">tstamp</code> as
+ its only argument and returns an allocated string that contains the
+ textual representation of the timestamp.
+ The result must be freed with <code class="function">PGTYPESchar_free()</code>.
+ </p></dd><dt id="PGTYPESTIMESTAMPCURRENT"><span class="term"><code class="function">PGTYPEStimestamp_current</code></span></dt><dd><p>
+ Retrieve the current timestamp.
+</p><pre class="synopsis">
+void PGTYPEStimestamp_current(timestamp *ts);
+</pre><p>
+ The function retrieves the current timestamp and saves it into the
+ timestamp variable that <code class="literal">ts</code> points to.
+ </p></dd><dt id="PGTYPESTIMESTAMPFMTASC"><span class="term"><code class="function">PGTYPEStimestamp_fmt_asc</code></span></dt><dd><p>
+ Convert a timestamp variable to a C char* using a format mask.
+</p><pre class="synopsis">
+int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
+</pre><p>
+ The function receives a pointer to the timestamp to convert as its
+ first argument (<code class="literal">ts</code>), a pointer to the output buffer
+ (<code class="literal">output</code>), the maximal length that has been allocated for
+ the output buffer (<code class="literal">str_len</code>) and the format mask to
+ use for the conversion (<code class="literal">fmtstr</code>).
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p><p>
+ You can use the following format specifiers for the format mask. The
+ format specifiers are the same ones that are used in the
+ <code class="function">strftime</code> function in <span class="productname">libc</span>. Any
+ non-format specifier will be copied into the output buffer.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">%A</code> - is replaced by national representation of
+ the full weekday name.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%a</code> - is replaced by national representation of
+ the abbreviated weekday name.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%B</code> - is replaced by national representation of
+ the full month name.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%b</code> - is replaced by national representation of
+ the abbreviated month name.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%C</code> - is replaced by (year / 100) as decimal
+ number; single digits are preceded by a zero.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%c</code> - is replaced by national representation of
+ time and date.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%D</code> - is equivalent to
+ <code class="literal">%m/%d/%y</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%d</code> - is replaced by the day of the month as a
+ decimal number (01–31).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%E*</code> <code class="literal">%O*</code> - POSIX locale
+ extensions. The sequences
+ <code class="literal">%Ec</code>
+ <code class="literal">%EC</code>
+ <code class="literal">%Ex</code>
+ <code class="literal">%EX</code>
+ <code class="literal">%Ey</code>
+ <code class="literal">%EY</code>
+ <code class="literal">%Od</code>
+ <code class="literal">%Oe</code>
+ <code class="literal">%OH</code>
+ <code class="literal">%OI</code>
+ <code class="literal">%Om</code>
+ <code class="literal">%OM</code>
+ <code class="literal">%OS</code>
+ <code class="literal">%Ou</code>
+ <code class="literal">%OU</code>
+ <code class="literal">%OV</code>
+ <code class="literal">%Ow</code>
+ <code class="literal">%OW</code>
+ <code class="literal">%Oy</code>
+ are supposed to provide alternative representations.
+ </p><p>
+ Additionally <code class="literal">%OB</code> implemented to represent
+ alternative months names (used standalone, without day mentioned).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%e</code> - is replaced by the day of month as a decimal
+ number (1–31); single digits are preceded by a blank.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%F</code> - is equivalent to <code class="literal">%Y-%m-%d</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%G</code> - is replaced by a year as a decimal number
+ with century. This year is the one that contains the greater part of
+ the week (Monday as the first day of the week).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%g</code> - is replaced by the same year as in
+ <code class="literal">%G</code>, but as a decimal number without century
+ (00–99).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%H</code> - is replaced by the hour (24-hour clock) as a
+ decimal number (00–23).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%h</code> - the same as <code class="literal">%b</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%I</code> - is replaced by the hour (12-hour clock) as a
+ decimal number (01–12).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%j</code> - is replaced by the day of the year as a
+ decimal number (001–366).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%k</code> - is replaced by the hour (24-hour clock) as a
+ decimal number (0–23); single digits are preceded by a blank.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%l</code> - is replaced by the hour (12-hour clock) as a
+ decimal number (1–12); single digits are preceded by a blank.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%M</code> - is replaced by the minute as a decimal
+ number (00–59).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%m</code> - is replaced by the month as a decimal number
+ (01–12).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%n</code> - is replaced by a newline.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%O*</code> - the same as <code class="literal">%E*</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%p</code> - is replaced by national representation of
+ either <span class="quote">“<span class="quote">ante meridiem</span>”</span> or <span class="quote">“<span class="quote">post meridiem</span>”</span> as appropriate.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%R</code> - is equivalent to <code class="literal">%H:%M</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%r</code> - is equivalent to <code class="literal">%I:%M:%S
+ %p</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%S</code> - is replaced by the second as a decimal
+ number (00–60).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%s</code> - is replaced by the number of seconds since
+ the Epoch, UTC.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%T</code> - is equivalent to <code class="literal">%H:%M:%S</code>
+ </p></li><li class="listitem"><p>
+ <code class="literal">%t</code> - is replaced by a tab.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%U</code> - is replaced by the week number of the year
+ (Sunday as the first day of the week) as a decimal number (00–53).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%u</code> - is replaced by the weekday (Monday as the
+ first day of the week) as a decimal number (1–7).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%V</code> - is replaced by the week number of the year
+ (Monday as the first day of the week) as a decimal number (01–53).
+ If the week containing January 1 has four or more days in the new
+ year, then it is week 1; otherwise it is the last week of the
+ previous year, and the next week is week 1.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%v</code> - is equivalent to
+ <code class="literal">%e-%b-%Y</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%W</code> - is replaced by the week number of the year
+ (Monday as the first day of the week) as a decimal number (00–53).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%w</code> - is replaced by the weekday (Sunday as the
+ first day of the week) as a decimal number (0–6).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%X</code> - is replaced by national representation of
+ the time.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%x</code> - is replaced by national representation of
+ the date.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%Y</code> - is replaced by the year with century as a
+ decimal number.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%y</code> - is replaced by the year without century as a
+ decimal number (00–99).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%Z</code> - is replaced by the time zone name.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%z</code> - is replaced by the time zone offset from
+ UTC; a leading plus sign stands for east of UTC, a minus sign for
+ west of UTC, hours and minutes follow with two digits each and no
+ delimiter between them (common form for <a class="ulink" href="https://tools.ietf.org/html/rfc822" target="_top">RFC 822</a> date headers).
+ </p></li><li class="listitem"><p>
+ <code class="literal">%+</code> - is replaced by national representation of
+ the date and time.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%-*</code> - GNU libc extension. Do not do any padding
+ when performing numerical outputs.
+ </p></li><li class="listitem"><p>
+ $_* - GNU libc extension. Explicitly specify space for padding.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%0*</code> - GNU libc extension. Explicitly specify zero
+ for padding.
+ </p></li><li class="listitem"><p>
+ <code class="literal">%%</code> - is replaced by <code class="literal">%</code>.
+ </p></li></ul></div><p>
+ </p></dd><dt id="PGTYPESTIMESTAMPSUB"><span class="term"><code class="function">PGTYPEStimestamp_sub</code></span></dt><dd><p>
+ Subtract one timestamp from another one and save the result in a
+ variable of type interval.
+</p><pre class="synopsis">
+int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
+</pre><p>
+ The function will subtract the timestamp variable that <code class="literal">ts2</code>
+ points to from the timestamp variable that <code class="literal">ts1</code> points to
+ and will store the result in the interval variable that <code class="literal">iv</code>
+ points to.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd><dt id="PGTYPESTIMESTAMPDEFMTASC"><span class="term"><code class="function">PGTYPEStimestamp_defmt_asc</code></span></dt><dd><p>
+ Parse a timestamp value from its textual representation using a
+ formatting mask.
+</p><pre class="synopsis">
+int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
+</pre><p>
+ The function receives the textual representation of a timestamp in the
+ variable <code class="literal">str</code> as well as the formatting mask to use in the
+ variable <code class="literal">fmt</code>. The result will be stored in the variable
+ that <code class="literal">d</code> points to.
+ </p><p>
+ If the formatting mask <code class="literal">fmt</code> is NULL, the function will fall
+ back to the default formatting mask which is <code class="literal">%Y-%m-%d
+ %H:%M:%S</code>.
+ </p><p>
+ This is the reverse function to <a class="xref" href="ecpg-pgtypes.html#PGTYPESTIMESTAMPFMTASC"><code class="function">PGTYPEStimestamp_fmt_asc</code></a>. See the documentation there in
+ order to find out about the possible formatting mask entries.
+ </p></dd><dt id="PGTYPESTIMESTAMPADDINTERVAL"><span class="term"><code class="function">PGTYPEStimestamp_add_interval</code></span></dt><dd><p>
+ Add an interval variable to a timestamp variable.
+</p><pre class="synopsis">
+int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
+</pre><p>
+ The function receives a pointer to a timestamp variable <code class="literal">tin</code>
+ and a pointer to an interval variable <code class="literal">span</code>. It adds the
+ interval to the timestamp and saves the resulting timestamp in the
+ variable that <code class="literal">tout</code> points to.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd><dt id="PGTYPESTIMESTAMPSUBINTERVAL"><span class="term"><code class="function">PGTYPEStimestamp_sub_interval</code></span></dt><dd><p>
+ Subtract an interval variable from a timestamp variable.
+</p><pre class="synopsis">
+int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
+</pre><p>
+ The function subtracts the interval variable that <code class="literal">span</code>
+ points to from the timestamp variable that <code class="literal">tin</code> points to
+ and saves the result into the variable that <code class="literal">tout</code> points
+ to.
+ </p><p>
+ Upon success, the function returns 0 and a negative value if an
+ error occurred.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-INTERVAL"><div class="titlepage"><div><div><h3 class="title">36.6.5. The interval Type</h3></div></div></div><p>
+ The interval type in C enables your programs to deal with data of the SQL
+ type interval. See <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for the equivalent
+ type in the <span class="productname">PostgreSQL</span> server.
+ </p><p>
+ The following functions can be used to work with the interval type:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESINTERVALNEW"><span class="term"><code class="function">PGTYPESinterval_new</code></span></dt><dd><p>
+ Return a pointer to a newly allocated interval variable.
+</p><pre class="synopsis">
+interval *PGTYPESinterval_new(void);
+</pre><p>
+ </p></dd><dt id="PGTYPESINTERVALFREE"><span class="term"><code class="function">PGTYPESinterval_free</code></span></dt><dd><p>
+ Release the memory of a previously allocated interval variable.
+</p><pre class="synopsis">
+void PGTYPESinterval_free(interval *intvl);
+</pre><p>
+ </p></dd><dt id="PGTYPESINTERVALFROMASC"><span class="term"><code class="function">PGTYPESinterval_from_asc</code></span></dt><dd><p>
+ Parse an interval from its textual representation.
+</p><pre class="synopsis">
+interval *PGTYPESinterval_from_asc(char *str, char **endptr);
+</pre><p>
+ The function parses the input string <code class="literal">str</code> and returns a
+ pointer to an allocated interval variable.
+ At the moment ECPG always parses
+ the complete string and so it currently does not support to store the
+ address of the first invalid character in <code class="literal">*endptr</code>.
+ You can safely set <code class="literal">endptr</code> to NULL.
+ </p></dd><dt id="PGTYPESINTERVALTOASC"><span class="term"><code class="function">PGTYPESinterval_to_asc</code></span></dt><dd><p>
+ Convert a variable of type interval to its textual representation.
+</p><pre class="synopsis">
+char *PGTYPESinterval_to_asc(interval *span);
+</pre><p>
+ The function converts the interval variable that <code class="literal">span</code>
+ points to into a C char*. The output looks like this example:
+ <code class="literal">@ 1 day 12 hours 59 mins 10 secs</code>.
+ The result must be freed with <code class="function">PGTYPESchar_free()</code>.
+ </p></dd><dt id="PGTYPESINTERVALCOPY"><span class="term"><code class="function">PGTYPESinterval_copy</code></span></dt><dd><p>
+ Copy a variable of type interval.
+</p><pre class="synopsis">
+int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
+</pre><p>
+ The function copies the interval variable that <code class="literal">intvlsrc</code>
+ points to into the variable that <code class="literal">intvldest</code> points to. Note
+ that you need to allocate the memory for the destination variable
+ before.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-DECIMAL"><div class="titlepage"><div><div><h3 class="title">36.6.6. The decimal Type</h3></div></div></div><p>
+ The decimal type is similar to the numeric type. However it is limited to
+ a maximum precision of 30 significant digits. In contrast to the numeric
+ type which can be created on the heap only, the decimal type can be
+ created either on the stack or on the heap (by means of the functions
+ <code class="function">PGTYPESdecimal_new</code> and
+ <code class="function">PGTYPESdecimal_free</code>).
+ There are a lot of other functions that deal with the decimal type in the
+ <span class="productname">Informix</span> compatibility mode described in <a class="xref" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode">Section 36.15</a>.
+ </p><p>
+ The following functions can be used to work with the decimal type and are
+ not only contained in the <code class="literal">libcompat</code> library.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">PGTYPESdecimal_new</code></span></dt><dd><p>
+ Request a pointer to a newly allocated decimal variable.
+</p><pre class="synopsis">
+decimal *PGTYPESdecimal_new(void);
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">PGTYPESdecimal_free</code></span></dt><dd><p>
+ Free a decimal type, release all of its memory.
+</p><pre class="synopsis">
+void PGTYPESdecimal_free(decimal *var);
+</pre><p>
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-ERRNO"><div class="titlepage"><div><div><h3 class="title">36.6.7. errno Values of pgtypeslib</h3></div></div></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PGTYPES_NUM_BAD_NUMERIC</code></span></dt><dd><p>
+ An argument should contain a numeric variable (or point to a numeric
+ variable) but in fact its in-memory representation was invalid.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_NUM_OVERFLOW</code></span></dt><dd><p>
+ An overflow occurred. Since the numeric type can deal with almost
+ arbitrary precision, converting a numeric variable into other types
+ might cause overflow.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_NUM_UNDERFLOW</code></span></dt><dd><p>
+ An underflow occurred. Since the numeric type can deal with almost
+ arbitrary precision, converting a numeric variable into other types
+ might cause underflow.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_NUM_DIVIDE_ZERO</code></span></dt><dd><p>
+ A division by zero has been attempted.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_BAD_DATE</code></span></dt><dd><p>
+ An invalid date string was passed to
+ the <code class="function">PGTYPESdate_from_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_ERR_EARGS</code></span></dt><dd><p>
+ Invalid arguments were passed to the
+ <code class="function">PGTYPESdate_defmt_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_ERR_ENOSHORTDATE</code></span></dt><dd><p>
+ An invalid token in the input string was found by the
+ <code class="function">PGTYPESdate_defmt_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_INTVL_BAD_INTERVAL</code></span></dt><dd><p>
+ An invalid interval string was passed to the
+ <code class="function">PGTYPESinterval_from_asc</code> function, or an
+ invalid interval value was passed to the
+ <code class="function">PGTYPESinterval_to_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_ERR_ENOTDMY</code></span></dt><dd><p>
+ There was a mismatch in the day/month/year assignment in the
+ <code class="function">PGTYPESdate_defmt_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_BAD_DAY</code></span></dt><dd><p>
+ An invalid day of the month value was found by
+ the <code class="function">PGTYPESdate_defmt_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_DATE_BAD_MONTH</code></span></dt><dd><p>
+ An invalid month value was found by
+ the <code class="function">PGTYPESdate_defmt_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_TS_BAD_TIMESTAMP</code></span></dt><dd><p>
+ An invalid timestamp string pass passed to
+ the <code class="function">PGTYPEStimestamp_from_asc</code> function,
+ or an invalid timestamp value was passed to
+ the <code class="function">PGTYPEStimestamp_to_asc</code> function.
+ </p></dd><dt><span class="term"><code class="literal">PGTYPES_TS_ERR_EINFTIME</code></span></dt><dd><p>
+ An infinite timestamp value was encountered in a context that
+ cannot handle it.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="ECPG-PGTYPES-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">36.6.8. Special Constants of pgtypeslib</h3></div></div></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PGTYPESINVALIDTIMESTAMP"><span class="term"><code class="literal">PGTYPESInvalidTimestamp</code></span></dt><dd><p>
+ A value of type timestamp representing an invalid time stamp. This is
+ returned by the function <code class="function">PGTYPEStimestamp_from_asc</code> on
+ parse error.
+ Note that due to the internal representation of the <code class="type">timestamp</code> data type,
+ <code class="literal">PGTYPESInvalidTimestamp</code> is also a valid timestamp at
+ the same time. It is set to <code class="literal">1899-12-31 23:59:59</code>. In order
+ to detect errors, make sure that your application does not only test
+ for <code class="literal">PGTYPESInvalidTimestamp</code> but also for
+ <code class="literal">errno != 0</code> after each call to
+ <code class="function">PGTYPEStimestamp_from_asc</code>.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-dynamic.html" title="36.5. Dynamic SQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.5. Dynamic SQL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.7. Using Descriptor Areas</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-preproc.html b/doc/src/sgml/html/ecpg-preproc.html
new file mode 100644
index 0000000..951dbf3
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-preproc.html
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.9. Preprocessor Directives</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-errors.html" title="36.8. Error Handling" /><link rel="next" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.9. Preprocessor Directives</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-errors.html" title="36.8. Error Handling">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-PREPROC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.9. Preprocessor Directives</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-INCLUDE">36.9.1. Including Files</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-DEFINE">36.9.2. The define and undef Directives</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-IFDEF">36.9.3. ifdef, ifndef, elif, else, and endif Directives</a></span></dt></dl></div><p>
+ Several preprocessor directives are available that modify how
+ the <code class="command">ecpg</code> preprocessor parses and processes a
+ file.
+ </p><div class="sect2" id="ECPG-INCLUDE"><div class="titlepage"><div><div><h3 class="title">36.9.1. Including Files</h3></div></div></div><p>
+ To include an external file into your embedded SQL program, use:
+</p><pre class="programlisting">
+EXEC SQL INCLUDE <em class="replaceable"><code>filename</code></em>;
+EXEC SQL INCLUDE &lt;<em class="replaceable"><code>filename</code></em>&gt;;
+EXEC SQL INCLUDE "<em class="replaceable"><code>filename</code></em>";
+</pre><p>
+ The embedded SQL preprocessor will look for a file named
+ <code class="literal"><em class="replaceable"><code>filename</code></em>.h</code>,
+ preprocess it, and include it in the resulting C output. Thus,
+ embedded SQL statements in the included file are handled correctly.
+ </p><p>
+ The <code class="command">ecpg</code> preprocessor will search a file at
+ several directories in following order:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">current directory</li><li class="listitem"><code class="filename">/usr/local/include</code></li><li class="listitem">PostgreSQL include directory, defined at build time (e.g., <code class="filename">/usr/local/pgsql/include</code>)</li><li class="listitem"><code class="filename">/usr/include</code></li></ul></div><p>
+
+ But when <code class="literal">EXEC SQL INCLUDE
+ "<em class="replaceable"><code>filename</code></em>"</code> is used, only the
+ current directory is searched.
+ </p><p>
+ In each directory, the preprocessor will first look for the file
+ name as given, and if not found will append <code class="literal">.h</code>
+ to the file name and try again (unless the specified file name
+ already has that suffix).
+ </p><p>
+ Note that <code class="command">EXEC SQL INCLUDE</code> is <span class="emphasis"><em>not</em></span> the same as:
+</p><pre class="programlisting">
+#include &lt;<em class="replaceable"><code>filename</code></em>.h&gt;
+</pre><p>
+ because this file would not be subject to SQL command preprocessing.
+ Naturally, you can continue to use the C
+ <code class="literal">#include</code> directive to include other header
+ files.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The include file name is case-sensitive, even though the rest of
+ the <code class="literal">EXEC SQL INCLUDE</code> command follows the normal
+ SQL case-sensitivity rules.
+ </p></div></div><div class="sect2" id="ECPG-DEFINE"><div class="titlepage"><div><div><h3 class="title">36.9.2. The define and undef Directives</h3></div></div></div><p>
+ Similar to the directive <code class="literal">#define</code> that is known from C,
+ embedded SQL has a similar concept:
+</p><pre class="programlisting">
+EXEC SQL DEFINE <em class="replaceable"><code>name</code></em>;
+EXEC SQL DEFINE <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>;
+</pre><p>
+ So you can define a name:
+</p><pre class="programlisting">
+EXEC SQL DEFINE HAVE_FEATURE;
+</pre><p>
+ And you can also define constants:
+</p><pre class="programlisting">
+EXEC SQL DEFINE MYNUMBER 12;
+EXEC SQL DEFINE MYSTRING 'abc';
+</pre><p>
+ Use <code class="literal">undef</code> to remove a previous definition:
+</p><pre class="programlisting">
+EXEC SQL UNDEF MYNUMBER;
+</pre><p>
+ </p><p>
+ Of course you can continue to use the C versions <code class="literal">#define</code>
+ and <code class="literal">#undef</code> in your embedded SQL program. The difference
+ is where your defined values get evaluated. If you use <code class="literal">EXEC SQL
+ DEFINE</code> then the <code class="command">ecpg</code> preprocessor evaluates the defines and substitutes
+ the values. For example if you write:
+</p><pre class="programlisting">
+EXEC SQL DEFINE MYNUMBER 12;
+...
+EXEC SQL UPDATE Tbl SET col = MYNUMBER;
+</pre><p>
+ then <code class="command">ecpg</code> will already do the substitution and your C compiler will never
+ see any name or identifier <code class="literal">MYNUMBER</code>. Note that you cannot use
+ <code class="literal">#define</code> for a constant that you are going to use in an
+ embedded SQL query because in this case the embedded SQL precompiler is not
+ able to see this declaration.
+ </p></div><div class="sect2" id="ECPG-IFDEF"><div class="titlepage"><div><div><h3 class="title">36.9.3. ifdef, ifndef, elif, else, and endif Directives</h3></div></div></div><p>
+ You can use the following directives to compile code sections conditionally:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
+ Checks a <em class="replaceable"><code>name</code></em> and processes subsequent lines if
+ <em class="replaceable"><code>name</code></em> has been defined via <code class="literal">EXEC SQL define
+ <em class="replaceable"><code>name</code></em></code>.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
+ Checks a <em class="replaceable"><code>name</code></em> and processes subsequent lines if
+ <em class="replaceable"><code>name</code></em> has <span class="emphasis"><em>not</em></span> been defined via
+ <code class="literal">EXEC SQL define <em class="replaceable"><code>name</code></em></code>.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL elif <em class="replaceable"><code>name</code></em>;</code></span></dt><dd><p>
+ Begins an optional alternative section after an
+ <code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em></code> or
+ <code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em></code>
+ directive. Any number of <code class="literal">elif</code> sections can appear.
+ Lines following an <code class="literal">elif</code> will be processed
+ if <em class="replaceable"><code>name</code></em> has been
+ defined <span class="emphasis"><em>and</em></span> no previous section of the same
+ <code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
+ construct has been processed.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL else;</code></span></dt><dd><p>
+ Begins an optional, final alternative section after an
+ <code class="literal">EXEC SQL ifdef <em class="replaceable"><code>name</code></em></code> or
+ <code class="literal">EXEC SQL ifndef <em class="replaceable"><code>name</code></em></code>
+ directive. Subsequent lines will be processed if no previous section
+ of the same
+ <code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
+ construct has been processed.
+ </p></dd><dt><span class="term"><code class="literal">EXEC SQL endif;</code></span></dt><dd><p>
+ Ends an
+ <code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
+ construct. Subsequent lines are processed normally.
+ </p></dd></dl></div><p>
+ </p><p>
+ <code class="literal">ifdef</code>/<code class="literal">ifndef</code>...<code class="literal">endif</code>
+ constructs can be nested, up to 127 levels deep.
+ </p><p>
+ This example will compile exactly one of the three <code class="literal">SET
+ TIMEZONE</code> commands:
+</p><pre class="programlisting">
+EXEC SQL ifdef TZVAR;
+EXEC SQL SET TIMEZONE TO TZVAR;
+EXEC SQL elif TZNAME;
+EXEC SQL SET TIMEZONE TO TZNAME;
+EXEC SQL else;
+EXEC SQL SET TIMEZONE TO 'GMT';
+EXEC SQL endif;
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-errors.html" title="36.8. Error Handling">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-process.html" title="36.10. Processing Embedded SQL Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.8. Error Handling </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.10. Processing Embedded SQL Programs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-process.html b/doc/src/sgml/html/ecpg-process.html
new file mode 100644
index 0000000..f7bcd5a
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-process.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.10. Processing Embedded SQL Programs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-preproc.html" title="36.9. Preprocessor Directives" /><link rel="next" href="ecpg-library.html" title="36.11. Library Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.10. Processing Embedded SQL Programs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-preproc.html" title="36.9. Preprocessor Directives">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-library.html" title="36.11. Library Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-PROCESS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.10. Processing Embedded SQL Programs</h2></div></div></div><p>
+ Now that you have an idea how to form embedded SQL C programs, you
+ probably want to know how to compile them. Before compiling you
+ run the file through the embedded <acronym class="acronym">SQL</acronym>
+ <acronym class="acronym">C</acronym> preprocessor, which converts the
+ <acronym class="acronym">SQL</acronym> statements you used to special function
+ calls. After compiling, you must link with a special library that
+ contains the needed functions. These functions fetch information
+ from the arguments, perform the <acronym class="acronym">SQL</acronym> command using
+ the <span class="application">libpq</span> interface, and put the result
+ in the arguments specified for output.
+ </p><p>
+ The preprocessor program is called <code class="filename">ecpg</code> and is
+ included in a normal <span class="productname">PostgreSQL</span> installation.
+ Embedded SQL programs are typically named with an extension
+ <code class="filename">.pgc</code>. If you have a program file called
+ <code class="filename">prog1.pgc</code>, you can preprocess it by simply
+ calling:
+</p><pre class="programlisting">
+ecpg prog1.pgc
+</pre><p>
+ This will create a file called <code class="filename">prog1.c</code>. If
+ your input files do not follow the suggested naming pattern, you
+ can specify the output file explicitly using the
+ <code class="option">-o</code> option.
+ </p><p>
+ The preprocessed file can be compiled normally, for example:
+</p><pre class="programlisting">
+cc -c prog1.c
+</pre><p>
+ The generated C source files include header files from the
+ <span class="productname">PostgreSQL</span> installation, so if you installed
+ <span class="productname">PostgreSQL</span> in a location that is not searched by
+ default, you have to add an option such as
+ <code class="literal">-I/usr/local/pgsql/include</code> to the compilation
+ command line.
+ </p><p>
+ To link an embedded SQL program, you need to include the
+ <code class="filename">libecpg</code> library, like so:
+</p><pre class="programlisting">
+cc -o myprog prog1.o prog2.o ... -lecpg
+</pre><p>
+ Again, you might have to add an option like
+ <code class="literal">-L/usr/local/pgsql/lib</code> to that command line.
+ </p><p>
+ You can
+ use <code class="command">pg_config</code><a id="id-1.7.5.16.6.2" class="indexterm"></a>
+ or <code class="command">pkg-config</code><a id="id-1.7.5.16.6.4" class="indexterm"></a> with package name <code class="literal">libecpg</code> to
+ get the paths for your installation.
+ </p><p>
+ If you manage the build process of a larger project using
+ <span class="application">make</span>, it might be convenient to include
+ the following implicit rule to your makefiles:
+</p><pre class="programlisting">
+ECPG = ecpg
+
+%.c: %.pgc
+ $(ECPG) $&lt;
+</pre><p>
+ </p><p>
+ The complete syntax of the <code class="command">ecpg</code> command is
+ detailed in <a class="xref" href="app-ecpg.html" title="ecpg"><span class="refentrytitle"><span class="application">ecpg</span></span></a>.
+ </p><p>
+ The <span class="application">ecpg</span> library is thread-safe by
+ default. However, you might need to use some threading
+ command-line options to compile your client code.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-preproc.html" title="36.9. Preprocessor Directives">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-library.html" title="36.11. Library Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.9. Preprocessor Directives </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.11. Library Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-allocate-descriptor.html b/doc/src/sgml/html/ecpg-sql-allocate-descriptor.html
new file mode 100644
index 0000000..3634450
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-allocate-descriptor.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALLOCATE DESCRIPTOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands" /><link rel="next" href="ecpg-sql-connect.html" title="CONNECT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALLOCATE DESCRIPTOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-connect.html" title="CONNECT">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-ALLOCATE-DESCRIPTOR"><div class="titlepage"></div><div class="refnamediv"><h2>ALLOCATE DESCRIPTOR</h2><p>ALLOCATE DESCRIPTOR — allocate an SQL descriptor area</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALLOCATE DESCRIPTOR <em class="replaceable"><code>name</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.3.3"><h2>Description</h2><p>
+ <code class="command">ALLOCATE DESCRIPTOR</code> allocates a new named SQL
+ descriptor area, which can be used to exchange data between the
+ PostgreSQL server and the host program.
+ </p><p>
+ Descriptor areas should be freed after use using
+ the <code class="command">DEALLOCATE DESCRIPTOR</code> command.
+ </p></div><div class="refsect1" id="id-1.7.5.20.3.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ A name of SQL descriptor, case sensitive. This can be an SQL
+ identifier or a host variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.3.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL ALLOCATE DESCRIPTOR mydesc;
+</pre></div><div class="refsect1" id="id-1.7.5.20.3.6"><h2>Compatibility</h2><p>
+ <code class="command">ALLOCATE DESCRIPTOR</code> is specified in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.3.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR">DEALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">GET DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">SET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-connect.html" title="CONNECT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.14. Embedded SQL Commands </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CONNECT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-commands.html b/doc/src/sgml/html/ecpg-sql-commands.html
new file mode 100644
index 0000000..0fea995
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-commands.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.14. Embedded SQL Commands</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-cpp.html" title="36.13. C++ Applications" /><link rel="next" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.14. Embedded SQL Commands</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-cpp.html" title="36.13. C++ Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-SQL-COMMANDS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.14. Embedded SQL Commands</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="ecpg-sql-allocate-descriptor.html">ALLOCATE DESCRIPTOR</a></span><span class="refpurpose"> — allocate an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-connect.html">CONNECT</a></span><span class="refpurpose"> — establish a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-deallocate-descriptor.html">DEALLOCATE DESCRIPTOR</a></span><span class="refpurpose"> — deallocate an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-declare.html">DECLARE</a></span><span class="refpurpose"> — define a cursor</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-declare-statement.html">DECLARE STATEMENT</a></span><span class="refpurpose"> — declare SQL statement identifier</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-describe.html">DESCRIBE</a></span><span class="refpurpose"> — obtain information about a prepared statement or result set</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-disconnect.html">DISCONNECT</a></span><span class="refpurpose"> — terminate a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-execute-immediate.html">EXECUTE IMMEDIATE</a></span><span class="refpurpose"> — dynamically prepare and execute a statement</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-get-descriptor.html">GET DESCRIPTOR</a></span><span class="refpurpose"> — get information from an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-open.html">OPEN</a></span><span class="refpurpose"> — open a dynamic cursor</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-prepare.html">PREPARE</a></span><span class="refpurpose"> — prepare a statement for execution</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-autocommit.html">SET AUTOCOMMIT</a></span><span class="refpurpose"> — set the autocommit behavior of the current session</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-connection.html">SET CONNECTION</a></span><span class="refpurpose"> — select a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-descriptor.html">SET DESCRIPTOR</a></span><span class="refpurpose"> — set information in an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-type.html">TYPE</a></span><span class="refpurpose"> — define a new data type</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-var.html">VAR</a></span><span class="refpurpose"> — define a variable</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-whenever.html">WHENEVER</a></span><span class="refpurpose"> — specify the action to be taken when an SQL statement causes a specific class condition to be raised</span></dt></dl></div><p>
+ This section describes all SQL commands that are specific to
+ embedded SQL. Also refer to the SQL commands listed
+ in <a class="xref" href="sql-commands.html" title="SQL Commands">SQL Commands</a>, which can also be used in
+ embedded SQL, unless stated otherwise.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-cpp.html" title="36.13. C++ Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.13. <acronym class="acronym">C++</acronym> Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALLOCATE DESCRIPTOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-connect.html b/doc/src/sgml/html/ecpg-sql-connect.html
new file mode 100644
index 0000000..e77c748
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-connect.html
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CONNECT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR" /><link rel="next" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CONNECT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-CONNECT"><div class="titlepage"></div><div class="refnamediv"><h2>CONNECT</h2><p>CONNECT — establish a database connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CONNECT TO <em class="replaceable"><code>connection_target</code></em> [ AS <em class="replaceable"><code>connection_name</code></em> ] [ USER <em class="replaceable"><code>connection_user</code></em> ]
+CONNECT TO DEFAULT
+CONNECT <em class="replaceable"><code>connection_user</code></em>
+DATABASE <em class="replaceable"><code>connection_target</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.4.3"><h2>Description</h2><p>
+ The <code class="command">CONNECT</code> command establishes a connection
+ between the client and the PostgreSQL server.
+ </p></div><div class="refsect1" id="id-1.7.5.20.4.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>connection_target</code></em></span></dt><dd><p>
+ <em class="replaceable"><code>connection_target</code></em>
+ specifies the target server of the connection on one of
+ several forms.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">[ <em class="replaceable"><code>database_name</code></em> ] [ <code class="literal">@</code><em class="replaceable"><code>host</code></em> ] [ <code class="literal">:</code><em class="replaceable"><code>port</code></em> ]</span></dt><dd><p>
+ Connect over TCP/IP
+ </p></dd><dt><span class="term"><code class="literal">unix:postgresql://</code><em class="replaceable"><code>host</code></em> [ <code class="literal">:</code><em class="replaceable"><code>port</code></em> ] <code class="literal">/</code> [ <em class="replaceable"><code>database_name</code></em> ] [ <code class="literal">?</code><em class="replaceable"><code>connection_option</code></em> ]</span></dt><dd><p>
+ Connect over Unix-domain sockets
+ </p></dd><dt><span class="term"><code class="literal">tcp:postgresql://</code><em class="replaceable"><code>host</code></em> [ <code class="literal">:</code><em class="replaceable"><code>port</code></em> ] <code class="literal">/</code> [ <em class="replaceable"><code>database_name</code></em> ] [ <code class="literal">?</code><em class="replaceable"><code>connection_option</code></em> ]</span></dt><dd><p>
+ Connect over TCP/IP
+ </p></dd><dt><span class="term">SQL string constant</span></dt><dd><p>
+ containing a value in one of the above forms
+ </p></dd><dt><span class="term">host variable</span></dt><dd><p>
+ host variable of type <code class="type">char[]</code>
+ or <code class="type">VARCHAR[]</code> containing a value in one of the
+ above forms
+ </p></dd></dl></div><p>
+ </p></dd><dt><span class="term"><em class="replaceable"><code>connection_name</code></em></span></dt><dd><p>
+ An optional identifier for the connection, so that it can be
+ referred to in other commands. This can be an SQL identifier
+ or a host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>connection_user</code></em></span></dt><dd><p>
+ The user name for the database connection.
+ </p><p>
+ This parameter can also specify user name and password, using one the forms
+ <code class="literal"><em class="replaceable"><code>user_name</code></em>/<em class="replaceable"><code>password</code></em></code>,
+ <code class="literal"><em class="replaceable"><code>user_name</code></em> IDENTIFIED BY <em class="replaceable"><code>password</code></em></code>, or
+ <code class="literal"><em class="replaceable"><code>user_name</code></em> USING <em class="replaceable"><code>password</code></em></code>.
+ </p><p>
+ User name and password can be SQL identifiers, string
+ constants, or host variables.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ Use all default connection parameters, as defined by libpq.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.4.5"><h2>Examples</h2><p>
+ Here a several variants for specifying connection parameters:
+</p><pre class="programlisting">
+EXEC SQL CONNECT TO "connectdb" AS main;
+EXEC SQL CONNECT TO "connectdb" AS second;
+EXEC SQL CONNECT TO "unix:postgresql://200.46.204.71/connectdb" AS main USER connectuser;
+EXEC SQL CONNECT TO "unix:postgresql://localhost/connectdb" AS main USER connectuser;
+EXEC SQL CONNECT TO 'connectdb' AS main;
+EXEC SQL CONNECT TO 'unix:postgresql://localhost/connectdb' AS main USER :user;
+EXEC SQL CONNECT TO :db AS :id;
+EXEC SQL CONNECT TO :db USER connectuser USING :pw;
+EXEC SQL CONNECT TO @localhost AS main USER connectdb;
+EXEC SQL CONNECT TO REGRESSDB1 as main;
+EXEC SQL CONNECT TO AS main USER connectdb;
+EXEC SQL CONNECT TO connectdb AS :id;
+EXEC SQL CONNECT TO connectdb AS main USER connectuser/connectdb;
+EXEC SQL CONNECT TO connectdb AS main;
+EXEC SQL CONNECT TO connectdb@localhost AS main;
+EXEC SQL CONNECT TO tcp:postgresql://localhost/ USER connectdb;
+EXEC SQL CONNECT TO tcp:postgresql://localhost/connectdb USER connectuser IDENTIFIED BY connectpw;
+EXEC SQL CONNECT TO tcp:postgresql://localhost:20/connectdb USER connectuser IDENTIFIED BY connectpw;
+EXEC SQL CONNECT TO unix:postgresql://localhost/ AS main USER connectdb;
+EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb AS main USER connectuser;
+EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser IDENTIFIED BY "connectpw";
+EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser USING "connectpw";
+EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb?connect_timeout=14 USER connectuser;
+</pre><p>
+ </p><p>
+ Here is an example program that illustrates the use of host
+ variables to specify connection parameters:
+</p><pre class="programlisting">
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ char *dbname = "testdb"; /* database name */
+ char *user = "testuser"; /* connection user name */
+ char *connection = "tcp:postgresql://localhost:5432/testdb";
+ /* connection string */
+ char ver[256]; /* buffer to store the version string */
+EXEC SQL END DECLARE SECTION;
+
+ ECPGdebug(1, stderr);
+
+ EXEC SQL CONNECT TO :dbname USER :user;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL SELECT version() INTO :ver;
+ EXEC SQL DISCONNECT;
+
+ printf("version: %s\n", ver);
+
+ EXEC SQL CONNECT TO :connection USER :user;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL SELECT version() INTO :ver;
+ EXEC SQL DISCONNECT;
+
+ printf("version: %s\n", ver);
+
+ return 0;
+}
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.4.6"><h2>Compatibility</h2><p>
+ <code class="command">CONNECT</code> is specified in the SQL standard, but
+ the format of the connection parameters is
+ implementation-specific.
+ </p></div><div class="refsect1" id="id-1.7.5.20.4.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-disconnect.html" title="DISCONNECT">DISCONNECT</a>, <a class="xref" href="ecpg-sql-set-connection.html" title="SET CONNECTION">SET CONNECTION</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALLOCATE DESCRIPTOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DEALLOCATE DESCRIPTOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-deallocate-descriptor.html b/doc/src/sgml/html/ecpg-sql-deallocate-descriptor.html
new file mode 100644
index 0000000..8999924
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-deallocate-descriptor.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DEALLOCATE DESCRIPTOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-connect.html" title="CONNECT" /><link rel="next" href="ecpg-sql-declare.html" title="DECLARE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DEALLOCATE DESCRIPTOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-connect.html" title="CONNECT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-declare.html" title="DECLARE">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-DEALLOCATE-DESCRIPTOR"><div class="titlepage"></div><div class="refnamediv"><h2>DEALLOCATE DESCRIPTOR</h2><p>DEALLOCATE DESCRIPTOR — deallocate an SQL descriptor area</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DEALLOCATE DESCRIPTOR <em class="replaceable"><code>name</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.5.3"><h2>Description</h2><p>
+ <code class="command">DEALLOCATE DESCRIPTOR</code> deallocates a named SQL
+ descriptor area.
+ </p></div><div class="refsect1" id="id-1.7.5.20.5.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the descriptor which is going to be deallocated.
+ It is case sensitive. This can be an SQL identifier or a host
+ variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.5.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
+</pre></div><div class="refsect1" id="id-1.7.5.20.5.6"><h2>Compatibility</h2><p>
+ <code class="command">DEALLOCATE DESCRIPTOR</code> is specified in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.5.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">ALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">GET DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">SET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-connect.html" title="CONNECT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-declare.html" title="DECLARE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CONNECT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DECLARE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-declare-statement.html b/doc/src/sgml/html/ecpg-sql-declare-statement.html
new file mode 100644
index 0000000..cf236b2
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-declare-statement.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DECLARE STATEMENT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-declare.html" title="DECLARE" /><link rel="next" href="ecpg-sql-describe.html" title="DESCRIBE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DECLARE STATEMENT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-declare.html" title="DECLARE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-describe.html" title="DESCRIBE">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-DECLARE-STATEMENT"><div class="titlepage"></div><div class="refnamediv"><h2>DECLARE STATEMENT</h2><p>DECLARE STATEMENT — declare SQL statement identifier</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+EXEC SQL [ AT <em class="replaceable"><code>connection_name</code></em> ] DECLARE <em class="replaceable"><code>statement_name</code></em> STATEMENT
+</pre></div><div class="refsect1" id="id-1.7.5.20.7.3"><h2>Description</h2><p>
+ <code class="command">DECLARE STATEMENT</code> declares an SQL statement identifier.
+ SQL statement identifier can be associated with the connection.
+ When the identifier is used by dynamic SQL statements, the statements
+ are executed using the associated connection.
+ The namespace of the declaration is the precompile unit, and multiple
+ declarations to the same SQL statement identifier are not allowed.
+ Note that if the precompiler runs in Informix compatibility mode and
+ some SQL statement is declared, "database" can not be used as a cursor
+ name.
+ </p></div><div class="refsect1" id="id-1.7.5.20.7.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>connection_name</code></em></span></dt><dd><p>
+ A database connection name established by the <code class="command">CONNECT</code> command.
+ </p><p>
+ AT clause can be omitted, but such statement has no meaning.
+ </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>statement_name</code></em></span></dt><dd><p>
+ The name of an SQL statement identifier, either as an SQL identifier or a host variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.7.5"><h2>Notes</h2><p>
+ This association is valid only if the declaration is physically placed on top of a dynamic statement.
+ </p></div><div class="refsect1" id="id-1.7.5.20.7.6"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL CONNECT TO postgres AS con1;
+EXEC SQL AT con1 DECLARE sql_stmt STATEMENT;
+EXEC SQL DECLARE cursor_name CURSOR FOR sql_stmt;
+EXEC SQL PREPARE sql_stmt FROM :dyn_string;
+EXEC SQL OPEN cursor_name;
+EXEC SQL FETCH cursor_name INTO :column1;
+EXEC SQL CLOSE cursor_name;
+</pre></div><div class="refsect1" id="id-1.7.5.20.7.7"><h2>Compatibility</h2><p>
+ <code class="command">DECLARE STATEMENT</code> is an extension of the SQL standard,
+ but can be used in famous DBMSs.
+ </p></div><div class="refsect1" id="id-1.7.5.20.7.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-connect.html" title="CONNECT">CONNECT</a>, <a class="xref" href="ecpg-sql-declare.html" title="DECLARE">DECLARE</a>, <a class="xref" href="ecpg-sql-open.html" title="OPEN">OPEN</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-declare.html" title="DECLARE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-describe.html" title="DESCRIBE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DECLARE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DESCRIBE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-declare.html b/doc/src/sgml/html/ecpg-sql-declare.html
new file mode 100644
index 0000000..037f5ae
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-declare.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DECLARE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR" /><link rel="next" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DECLARE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-DECLARE"><div class="titlepage"></div><div class="refnamediv"><h2>DECLARE</h2><p>DECLARE — define a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DECLARE <em class="replaceable"><code>cursor_name</code></em> [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR <em class="replaceable"><code>prepared_name</code></em>
+DECLARE <em class="replaceable"><code>cursor_name</code></em> [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR <em class="replaceable"><code>query</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.6.3"><h2>Description</h2><p>
+ <code class="command">DECLARE</code> declares a cursor for iterating over
+ the result set of a prepared statement. This command has
+ slightly different semantics from the direct SQL
+ command <code class="command">DECLARE</code>: Whereas the latter executes a
+ query and prepares the result set for retrieval, this embedded
+ SQL command merely declares a name as a <span class="quote">“<span class="quote">loop
+ variable</span>”</span> for iterating over the result set of a query;
+ the actual execution happens when the cursor is opened with
+ the <code class="command">OPEN</code> command.
+ </p></div><div class="refsect1" id="id-1.7.5.20.6.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+ A cursor name, case sensitive. This can be an SQL identifier
+ or a host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>prepared_name</code></em></span></dt><dd><p>
+ The name of a prepared query, either as an SQL identifier or a
+ host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> or
+ <a class="xref" href="sql-values.html" title="VALUES"><span class="refentrytitle">VALUES</span></a> command which will provide the
+ rows to be returned by the cursor.
+ </p></dd></dl></div><p>
+ For the meaning of the cursor options,
+ see <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>.
+ </p></div><div class="refsect1" id="id-1.7.5.20.6.5"><h2>Examples</h2><p>
+ Examples declaring a cursor for a query:
+</p><pre class="programlisting">
+EXEC SQL DECLARE C CURSOR FOR SELECT * FROM My_Table;
+EXEC SQL DECLARE C CURSOR FOR SELECT Item1 FROM T;
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT version();
+</pre><p>
+ </p><p>
+ An example declaring a cursor for a prepared statement:
+</p><pre class="programlisting">
+EXEC SQL PREPARE stmt1 AS SELECT version();
+EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.6.6"><h2>Compatibility</h2><p>
+ <code class="command">DECLARE</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.6.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-open.html" title="OPEN">OPEN</a>, <a class="xref" href="sql-close.html" title="CLOSE"><span class="refentrytitle">CLOSE</span></a>, <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-deallocate-descriptor.html" title="DEALLOCATE DESCRIPTOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DEALLOCATE DESCRIPTOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DECLARE STATEMENT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-describe.html b/doc/src/sgml/html/ecpg-sql-describe.html
new file mode 100644
index 0000000..c82ee5e
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-describe.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DESCRIBE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT" /><link rel="next" href="ecpg-sql-disconnect.html" title="DISCONNECT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DESCRIBE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-disconnect.html" title="DISCONNECT">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-DESCRIBE"><div class="titlepage"></div><div class="refnamediv"><h2>DESCRIBE</h2><p>DESCRIBE — obtain information about a prepared statement or result set</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DESCRIBE [ OUTPUT ] <em class="replaceable"><code>prepared_name</code></em> USING [ SQL ] DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em>
+DESCRIBE [ OUTPUT ] <em class="replaceable"><code>prepared_name</code></em> INTO [ SQL ] DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em>
+DESCRIBE [ OUTPUT ] <em class="replaceable"><code>prepared_name</code></em> INTO <em class="replaceable"><code>sqlda_name</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.8.3"><h2>Description</h2><p>
+ <code class="command">DESCRIBE</code> retrieves metadata information about
+ the result columns contained in a prepared statement, without
+ actually fetching a row.
+ </p></div><div class="refsect1" id="id-1.7.5.20.8.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>prepared_name</code></em></span></dt><dd><p>
+ The name of a prepared statement. This can be an SQL
+ identifier or a host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_name</code></em></span></dt><dd><p>
+ A descriptor name. It is case sensitive. It can be an SQL
+ identifier or a host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sqlda_name</code></em></span></dt><dd><p>
+ The name of an SQLDA variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.8.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL ALLOCATE DESCRIPTOR mydesc;
+EXEC SQL PREPARE stmt1 FROM :sql_stmt;
+EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
+EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :charvar = NAME;
+EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
+</pre></div><div class="refsect1" id="id-1.7.5.20.8.6"><h2>Compatibility</h2><p>
+ <code class="command">DESCRIBE</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.8.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">ALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">GET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-declare-statement.html" title="DECLARE STATEMENT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-disconnect.html" title="DISCONNECT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DECLARE STATEMENT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DISCONNECT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-disconnect.html b/doc/src/sgml/html/ecpg-sql-disconnect.html
new file mode 100644
index 0000000..7528efc
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-disconnect.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DISCONNECT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-describe.html" title="DESCRIBE" /><link rel="next" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DISCONNECT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-describe.html" title="DESCRIBE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-DISCONNECT"><div class="titlepage"></div><div class="refnamediv"><h2>DISCONNECT</h2><p>DISCONNECT — terminate a database connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DISCONNECT <em class="replaceable"><code>connection_name</code></em>
+DISCONNECT [ CURRENT ]
+DISCONNECT ALL
+</pre></div><div class="refsect1" id="id-1.7.5.20.9.3"><h2>Description</h2><p>
+ <code class="command">DISCONNECT</code> closes a connection (or all
+ connections) to the database.
+ </p></div><div class="refsect1" id="id-1.7.5.20.9.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>connection_name</code></em></span></dt><dd><p>
+ A database connection name established by
+ the <code class="command">CONNECT</code> command.
+ </p></dd><dt><span class="term"><code class="literal">CURRENT</code></span></dt><dd><p>
+ Close the <span class="quote">“<span class="quote">current</span>”</span> connection, which is either
+ the most recently opened connection, or the connection set by
+ the <code class="command">SET CONNECTION</code> command. This is also
+ the default if no argument is given to
+ the <code class="command">DISCONNECT</code> command.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Close all open connections.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.9.5"><h2>Examples</h2><pre class="programlisting">
+int
+main(void)
+{
+ EXEC SQL CONNECT TO testdb AS con1 USER testuser;
+ EXEC SQL CONNECT TO testdb AS con2 USER testuser;
+ EXEC SQL CONNECT TO testdb AS con3 USER testuser;
+
+ EXEC SQL DISCONNECT CURRENT; /* close con3 */
+ EXEC SQL DISCONNECT ALL; /* close con2 and con1 */
+
+ return 0;
+}
+</pre></div><div class="refsect1" id="id-1.7.5.20.9.6"><h2>Compatibility</h2><p>
+ <code class="command">DISCONNECT</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.9.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-connect.html" title="CONNECT">CONNECT</a>, <a class="xref" href="ecpg-sql-set-connection.html" title="SET CONNECTION">SET CONNECTION</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-describe.html" title="DESCRIBE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DESCRIBE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> EXECUTE IMMEDIATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-execute-immediate.html b/doc/src/sgml/html/ecpg-sql-execute-immediate.html
new file mode 100644
index 0000000..97c822a
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-execute-immediate.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>EXECUTE IMMEDIATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-disconnect.html" title="DISCONNECT" /><link rel="next" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">EXECUTE IMMEDIATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-disconnect.html" title="DISCONNECT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-EXECUTE-IMMEDIATE"><div class="titlepage"></div><div class="refnamediv"><h2>EXECUTE IMMEDIATE</h2><p>EXECUTE IMMEDIATE — dynamically prepare and execute a statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+EXECUTE IMMEDIATE <em class="replaceable"><code>string</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.10.3"><h2>Description</h2><p>
+ <code class="command">EXECUTE IMMEDIATE</code> immediately prepares and
+ executes a dynamically specified SQL statement, without
+ retrieving result rows.
+ </p></div><div class="refsect1" id="id-1.7.5.20.10.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>string</code></em></span></dt><dd><p>
+ A literal string or a host variable containing the SQL
+ statement to be executed.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.10.5"><h2>Notes</h2><p>
+ In typical usage, the <em class="replaceable"><code>string</code></em> is a host
+ variable reference to a string containing a dynamically-constructed
+ SQL statement. The case of a literal string is not very useful;
+ you might as well just write the SQL statement directly, without
+ the extra typing of <code class="command">EXECUTE IMMEDIATE</code>.
+ </p><p>
+ If you do use a literal string, keep in mind that any double quotes
+ you might wish to include in the SQL statement must be written as
+ octal escapes (<code class="literal">\042</code>) not the usual C
+ idiom <code class="literal">\"</code>. This is because the string is inside
+ an <code class="literal">EXEC SQL</code> section, so the ECPG lexer parses it
+ according to SQL rules not C rules. Any embedded backslashes will
+ later be handled according to C rules; but <code class="literal">\"</code>
+ causes an immediate syntax error because it is seen as ending the
+ literal.
+ </p></div><div class="refsect1" id="id-1.7.5.20.10.6"><h2>Examples</h2><p>
+ Here is an example that executes an <code class="command">INSERT</code>
+ statement using <code class="command">EXECUTE IMMEDIATE</code> and a host
+ variable named <code class="varname">command</code>:
+</p><pre class="programlisting">
+sprintf(command, "INSERT INTO test (name, amount, letter) VALUES ('db: ''r1''', 1, 'f')");
+EXEC SQL EXECUTE IMMEDIATE :command;
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.10.7"><h2>Compatibility</h2><p>
+ <code class="command">EXECUTE IMMEDIATE</code> is specified in the SQL standard.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-disconnect.html" title="DISCONNECT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DISCONNECT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> GET DESCRIPTOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-get-descriptor.html b/doc/src/sgml/html/ecpg-sql-get-descriptor.html
new file mode 100644
index 0000000..3cfb91f
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-get-descriptor.html
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>GET DESCRIPTOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE" /><link rel="next" href="ecpg-sql-open.html" title="OPEN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">GET DESCRIPTOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-open.html" title="OPEN">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-GET-DESCRIPTOR"><div class="titlepage"></div><div class="refnamediv"><h2>GET DESCRIPTOR</h2><p>GET DESCRIPTOR — get information from an SQL descriptor area</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+GET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> <em class="replaceable"><code>:cvariable</code></em> = <em class="replaceable"><code>descriptor_header_item</code></em> [, ... ]
+GET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> VALUE <em class="replaceable"><code>column_number</code></em> <em class="replaceable"><code>:cvariable</code></em> = <em class="replaceable"><code>descriptor_item</code></em> [, ... ]
+</pre></div><div class="refsect1" id="id-1.7.5.20.11.3"><h2>Description</h2><p>
+ <code class="command">GET DESCRIPTOR</code> retrieves information about a
+ query result set from an SQL descriptor area and stores it into
+ host variables. A descriptor area is typically populated
+ using <code class="command">FETCH</code> or <code class="command">SELECT</code>
+ before using this command to transfer the information into host
+ language variables.
+ </p><p>
+ This command has two forms: The first form retrieves
+ descriptor <span class="quote">“<span class="quote">header</span>”</span> items, which apply to the result
+ set in its entirety. One example is the row count. The second
+ form, which requires the column number as additional parameter,
+ retrieves information about a particular column. Examples are
+ the column name and the actual column value.
+ </p></div><div class="refsect1" id="id-1.7.5.20.11.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>descriptor_name</code></em></span></dt><dd><p>
+ A descriptor name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_header_item</code></em></span></dt><dd><p>
+ A token identifying which header information item to retrieve.
+ Only <code class="literal">COUNT</code>, to get the number of columns in the
+ result set, is currently supported.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_number</code></em></span></dt><dd><p>
+ The number of the column about which information is to be
+ retrieved. The count starts at 1.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_item</code></em></span></dt><dd><p>
+ A token identifying which item of information about a column
+ to retrieve. See <a class="xref" href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS" title="36.7.1. Named SQL Descriptor Areas">Section 36.7.1</a> for
+ a list of supported items.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cvariable</code></em></span></dt><dd><p>
+ A host variable that will receive the data retrieved from the
+ descriptor area.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.11.5"><h2>Examples</h2><p>
+ An example to retrieve the number of columns in a result set:
+</p><pre class="programlisting">
+EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
+</pre><p>
+ </p><p>
+ An example to retrieve a data length in the first column:
+</p><pre class="programlisting">
+EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
+</pre><p>
+ </p><p>
+ An example to retrieve the data body of the second column as a
+ string:
+</p><pre class="programlisting">
+EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA;
+</pre><p>
+ </p><p>
+ Here is an example for a whole procedure of
+ executing <code class="literal">SELECT current_database();</code> and showing the number of
+ columns, the column data length, and the column data:
+</p><pre class="programlisting">
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ int d_count;
+ char d_data[1024];
+ int d_returned_octet_length;
+EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO testdb AS con1 USER testuser;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL ALLOCATE DESCRIPTOR d;
+
+ /* Declare, open a cursor, and assign a descriptor to the cursor */
+ EXEC SQL DECLARE cur CURSOR FOR SELECT current_database();
+ EXEC SQL OPEN cur;
+ EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
+
+ /* Get a number of total columns */
+ EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
+ printf("d_count = %d\n", d_count);
+
+ /* Get length of a returned column */
+ EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
+ printf("d_returned_octet_length = %d\n", d_returned_octet_length);
+
+ /* Fetch the returned column as a string */
+ EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA;
+ printf("d_data = %s\n", d_data);
+
+ /* Closing */
+ EXEC SQL CLOSE cur;
+ EXEC SQL COMMIT;
+
+ EXEC SQL DEALLOCATE DESCRIPTOR d;
+ EXEC SQL DISCONNECT ALL;
+
+ return 0;
+}
+</pre><p>
+ When the example is executed, the result will look like this:
+</p><pre class="screen">
+d_count = 1
+d_returned_octet_length = 6
+d_data = testdb
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.11.6"><h2>Compatibility</h2><p>
+ <code class="command">GET DESCRIPTOR</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.11.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">ALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">SET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-execute-immediate.html" title="EXECUTE IMMEDIATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-open.html" title="OPEN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">EXECUTE IMMEDIATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> OPEN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-open.html b/doc/src/sgml/html/ecpg-sql-open.html
new file mode 100644
index 0000000..51c323c
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-open.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>OPEN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR" /><link rel="next" href="ecpg-sql-prepare.html" title="PREPARE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">OPEN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-prepare.html" title="PREPARE">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-OPEN"><div class="titlepage"></div><div class="refnamediv"><h2>OPEN</h2><p>OPEN — open a dynamic cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+OPEN <em class="replaceable"><code>cursor_name</code></em>
+OPEN <em class="replaceable"><code>cursor_name</code></em> USING <em class="replaceable"><code>value</code></em> [, ... ]
+OPEN <em class="replaceable"><code>cursor_name</code></em> USING SQL DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.12.3"><h2>Description</h2><p>
+ <code class="command">OPEN</code> opens a cursor and optionally binds
+ actual values to the placeholders in the cursor's declaration.
+ The cursor must previously have been declared with
+ the <code class="command">DECLARE</code> command. The execution
+ of <code class="command">OPEN</code> causes the query to start executing on
+ the server.
+ </p></div><div class="refsect1" id="id-1.7.5.20.12.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+ The name of the cursor to be opened. This can be an SQL
+ identifier or a host variable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ A value to be bound to a placeholder in the cursor. This can
+ be an SQL constant, a host variable, or a host variable with
+ indicator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_name</code></em></span></dt><dd><p>
+ The name of a descriptor containing values to be bound to the
+ placeholders in the cursor. This can be an SQL identifier or
+ a host variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.12.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL OPEN a;
+EXEC SQL OPEN d USING 1, 'test';
+EXEC SQL OPEN c1 USING SQL DESCRIPTOR mydesc;
+EXEC SQL OPEN :curname1;
+</pre></div><div class="refsect1" id="id-1.7.5.20.12.6"><h2>Compatibility</h2><p>
+ <code class="command">OPEN</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.12.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-declare.html" title="DECLARE">DECLARE</a>, <a class="xref" href="sql-close.html" title="CLOSE"><span class="refentrytitle">CLOSE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-prepare.html" title="PREPARE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">GET DESCRIPTOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> PREPARE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-prepare.html b/doc/src/sgml/html/ecpg-sql-prepare.html
new file mode 100644
index 0000000..f650222
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-prepare.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PREPARE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-open.html" title="OPEN" /><link rel="next" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PREPARE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-open.html" title="OPEN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-PREPARE"><div class="titlepage"></div><div class="refnamediv"><h2>PREPARE</h2><p>PREPARE — prepare a statement for execution</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+PREPARE <em class="replaceable"><code>prepared_name</code></em> FROM <em class="replaceable"><code>string</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.13.3"><h2>Description</h2><p>
+ <code class="command">PREPARE</code> prepares a statement dynamically
+ specified as a string for execution. This is different from the
+ direct SQL statement <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>, which can also
+ be used in embedded programs. The <a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a>
+ command is used to execute either kind of prepared statement.
+ </p></div><div class="refsect1" id="id-1.7.5.20.13.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>prepared_name</code></em></span></dt><dd><p>
+ An identifier for the prepared query.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>string</code></em></span></dt><dd><p>
+ A literal string or a host variable containing a preparable
+ SQL statement, one of SELECT, INSERT, UPDATE, or DELETE.
+ Use question marks (<code class="literal">?</code>) for parameter values
+ to be supplied at execution.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.13.5"><h2>Notes</h2><p>
+ In typical usage, the <em class="replaceable"><code>string</code></em> is a host
+ variable reference to a string containing a dynamically-constructed
+ SQL statement. The case of a literal string is not very useful;
+ you might as well just write a direct SQL <code class="command">PREPARE</code>
+ statement.
+ </p><p>
+ If you do use a literal string, keep in mind that any double quotes
+ you might wish to include in the SQL statement must be written as
+ octal escapes (<code class="literal">\042</code>) not the usual C
+ idiom <code class="literal">\"</code>. This is because the string is inside
+ an <code class="literal">EXEC SQL</code> section, so the ECPG lexer parses it
+ according to SQL rules not C rules. Any embedded backslashes will
+ later be handled according to C rules; but <code class="literal">\"</code>
+ causes an immediate syntax error because it is seen as ending the
+ literal.
+ </p></div><div class="refsect1" id="id-1.7.5.20.13.6"><h2>Examples</h2><pre class="programlisting">
+char *stmt = "SELECT * FROM test1 WHERE a = ? AND b = ?";
+
+EXEC SQL ALLOCATE DESCRIPTOR outdesc;
+EXEC SQL PREPARE foo FROM :stmt;
+
+EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc;
+</pre></div><div class="refsect1" id="id-1.7.5.20.13.7"><h2>Compatibility</h2><p>
+ <code class="command">PREPARE</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.13.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-open.html" title="OPEN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">OPEN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET AUTOCOMMIT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-set-autocommit.html b/doc/src/sgml/html/ecpg-sql-set-autocommit.html
new file mode 100644
index 0000000..3f25e10
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-set-autocommit.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET AUTOCOMMIT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-prepare.html" title="PREPARE" /><link rel="next" href="ecpg-sql-set-connection.html" title="SET CONNECTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET AUTOCOMMIT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-prepare.html" title="PREPARE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-set-connection.html" title="SET CONNECTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-SET-AUTOCOMMIT"><div class="titlepage"></div><div class="refnamediv"><h2>SET AUTOCOMMIT</h2><p>SET AUTOCOMMIT — set the autocommit behavior of the current session</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET AUTOCOMMIT { = | TO } { ON | OFF }
+</pre></div><div class="refsect1" id="id-1.7.5.20.14.3"><h2>Description</h2><p>
+ <code class="command">SET AUTOCOMMIT</code> sets the autocommit behavior of
+ the current database session. By default, embedded SQL programs
+ are <span class="emphasis"><em>not</em></span> in autocommit mode,
+ so <code class="command">COMMIT</code> needs to be issued explicitly when
+ desired. This command can change the session to autocommit mode,
+ where each individual statement is committed implicitly.
+ </p></div><div class="refsect1" id="id-1.7.5.20.14.4"><h2>Compatibility</h2><p>
+ <code class="command">SET AUTOCOMMIT</code> is an extension of PostgreSQL ECPG.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-prepare.html" title="PREPARE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-set-connection.html" title="SET CONNECTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PREPARE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET CONNECTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-set-connection.html b/doc/src/sgml/html/ecpg-sql-set-connection.html
new file mode 100644
index 0000000..0b53774
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-set-connection.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET CONNECTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT" /><link rel="next" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET CONNECTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-SET-CONNECTION"><div class="titlepage"></div><div class="refnamediv"><h2>SET CONNECTION</h2><p>SET CONNECTION — select a database connection</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET CONNECTION [ TO | = ] <em class="replaceable"><code>connection_name</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.15.3"><h2>Description</h2><p>
+ <code class="command">SET CONNECTION</code> sets the <span class="quote">“<span class="quote">current</span>”</span>
+ database connection, which is the one that all commands use
+ unless overridden.
+ </p></div><div class="refsect1" id="id-1.7.5.20.15.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>connection_name</code></em></span></dt><dd><p>
+ A database connection name established by
+ the <code class="command">CONNECT</code> command.
+ </p></dd><dt><span class="term"><code class="literal">CURRENT</code></span></dt><dd><p>
+ Set the connection to the current connection (thus, nothing happens).
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.15.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL SET CONNECTION TO con2;
+EXEC SQL SET CONNECTION = con1;
+</pre></div><div class="refsect1" id="id-1.7.5.20.15.6"><h2>Compatibility</h2><p>
+ <code class="command">SET CONNECTION</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.15.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-connect.html" title="CONNECT">CONNECT</a>, <a class="xref" href="ecpg-sql-disconnect.html" title="DISCONNECT">DISCONNECT</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-set-autocommit.html" title="SET AUTOCOMMIT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET AUTOCOMMIT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET DESCRIPTOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-set-descriptor.html b/doc/src/sgml/html/ecpg-sql-set-descriptor.html
new file mode 100644
index 0000000..d770b67
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-set-descriptor.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET DESCRIPTOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-set-connection.html" title="SET CONNECTION" /><link rel="next" href="ecpg-sql-type.html" title="TYPE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET DESCRIPTOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-set-connection.html" title="SET CONNECTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-type.html" title="TYPE">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-SET-DESCRIPTOR"><div class="titlepage"></div><div class="refnamediv"><h2>SET DESCRIPTOR</h2><p>SET DESCRIPTOR — set information in an SQL descriptor area</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> <em class="replaceable"><code>descriptor_header_item</code></em> = <em class="replaceable"><code>value</code></em> [, ... ]
+SET DESCRIPTOR <em class="replaceable"><code>descriptor_name</code></em> VALUE <em class="replaceable"><code>number</code></em> <em class="replaceable"><code>descriptor_item</code></em> = <em class="replaceable"><code>value</code></em> [, ...]
+</pre></div><div class="refsect1" id="id-1.7.5.20.16.3"><h2>Description</h2><p>
+ <code class="command">SET DESCRIPTOR</code> populates an SQL descriptor
+ area with values. The descriptor area is then typically used to
+ bind parameters in a prepared query execution.
+ </p><p>
+ This command has two forms: The first form applies to the
+ descriptor <span class="quote">“<span class="quote">header</span>”</span>, which is independent of a
+ particular datum. The second form assigns values to particular
+ datums, identified by number.
+ </p></div><div class="refsect1" id="id-1.7.5.20.16.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>descriptor_name</code></em></span></dt><dd><p>
+ A descriptor name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_header_item</code></em></span></dt><dd><p>
+ A token identifying which header information item to set.
+ Only <code class="literal">COUNT</code>, to set the number of descriptor
+ items, is currently supported.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>number</code></em></span></dt><dd><p>
+ The number of the descriptor item to set. The count starts at
+ 1.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>descriptor_item</code></em></span></dt><dd><p>
+ A token identifying which item of information to set in the
+ descriptor. See <a class="xref" href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS" title="36.7.1. Named SQL Descriptor Areas">Section 36.7.1</a> for a
+ list of supported items.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ A value to store into the descriptor item. This can be an SQL
+ constant or a host variable.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.16.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL SET DESCRIPTOR indesc COUNT = 1;
+EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = 2;
+EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = :val1;
+EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val1, DATA = 'some string';
+EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2;
+</pre></div><div class="refsect1" id="id-1.7.5.20.16.6"><h2>Compatibility</h2><p>
+ <code class="command">SET DESCRIPTOR</code> is specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.7.5.20.16.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="ecpg-sql-allocate-descriptor.html" title="ALLOCATE DESCRIPTOR">ALLOCATE DESCRIPTOR</a>, <a class="xref" href="ecpg-sql-get-descriptor.html" title="GET DESCRIPTOR">GET DESCRIPTOR</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-set-connection.html" title="SET CONNECTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-type.html" title="TYPE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET CONNECTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> TYPE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-type.html b/doc/src/sgml/html/ecpg-sql-type.html
new file mode 100644
index 0000000..9ae97fa
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-type.html
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>TYPE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR" /><link rel="next" href="ecpg-sql-var.html" title="VAR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">TYPE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-var.html" title="VAR">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-TYPE"><div class="titlepage"></div><div class="refnamediv"><h2>TYPE</h2><p>TYPE — define a new data type</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+TYPE <em class="replaceable"><code>type_name</code></em> IS <em class="replaceable"><code>ctype</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.17.3"><h2>Description</h2><p>
+ The <code class="command">TYPE</code> command defines a new C type. It is
+ equivalent to putting a <code class="literal">typedef</code> into a declare
+ section.
+ </p><p>
+ This command is only recognized when <code class="command">ecpg</code> is
+ run with the <code class="option">-c</code> option.
+ </p></div><div class="refsect1" id="id-1.7.5.20.17.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
+ The name for the new type. It must be a valid C type name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>ctype</code></em></span></dt><dd><p>
+ A C type specification.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.17.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL TYPE customer IS
+ struct
+ {
+ varchar name[50];
+ int phone;
+ };
+
+EXEC SQL TYPE cust_ind IS
+ struct ind
+ {
+ short name_ind;
+ short phone_ind;
+ };
+
+EXEC SQL TYPE c IS char reference;
+EXEC SQL TYPE ind IS union { int integer; short smallint; };
+EXEC SQL TYPE intarray IS int[AMOUNT];
+EXEC SQL TYPE str IS varchar[BUFFERSIZ];
+EXEC SQL TYPE string IS char[11];
+</pre><p>
+ Here is an example program that uses <code class="command">EXEC SQL
+ TYPE</code>:
+</p><pre class="programlisting">
+EXEC SQL WHENEVER SQLERROR SQLPRINT;
+
+EXEC SQL TYPE tt IS
+ struct
+ {
+ varchar v[256];
+ int i;
+ };
+
+EXEC SQL TYPE tt_ind IS
+ struct ind {
+ short v_ind;
+ short i_ind;
+ };
+
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ tt t;
+ tt_ind t_ind;
+EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO testdb AS con1;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ EXEC SQL SELECT current_database(), 256 INTO :t:t_ind LIMIT 1;
+
+ printf("t.v = %s\n", t.v.arr);
+ printf("t.i = %d\n", t.i);
+
+ printf("t_ind.v_ind = %d\n", t_ind.v_ind);
+ printf("t_ind.i_ind = %d\n", t_ind.i_ind);
+
+ EXEC SQL DISCONNECT con1;
+
+ return 0;
+}
+</pre><p>
+
+ The output from this program looks like this:
+</p><pre class="screen">
+t.v = testdb
+t.i = 256
+t_ind.v_ind = 0
+t_ind.i_ind = 0
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.17.6"><h2>Compatibility</h2><p>
+ The <code class="command">TYPE</code> command is a PostgreSQL extension.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-set-descriptor.html" title="SET DESCRIPTOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-var.html" title="VAR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET DESCRIPTOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> VAR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-var.html b/doc/src/sgml/html/ecpg-sql-var.html
new file mode 100644
index 0000000..5bee6c5
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-var.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>VAR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-type.html" title="TYPE" /><link rel="next" href="ecpg-sql-whenever.html" title="WHENEVER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">VAR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-type.html" title="TYPE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-sql-whenever.html" title="WHENEVER">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-VAR"><div class="titlepage"></div><div class="refnamediv"><h2>VAR</h2><p>VAR — define a variable</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+VAR <em class="replaceable"><code>varname</code></em> IS <em class="replaceable"><code>ctype</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.18.3"><h2>Description</h2><p>
+ The <code class="command">VAR</code> command assigns a new C data type
+ to a host variable. The host variable must be previously
+ declared in a declare section.
+ </p></div><div class="refsect1" id="id-1.7.5.20.18.4"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>varname</code></em></span></dt><dd><p>
+ A C variable name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>ctype</code></em></span></dt><dd><p>
+ A C type specification.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.7.5.20.18.5"><h2>Examples</h2><pre class="programlisting">
+Exec sql begin declare section;
+short a;
+exec sql end declare section;
+EXEC SQL VAR a IS int;
+</pre></div><div class="refsect1" id="id-1.7.5.20.18.6"><h2>Compatibility</h2><p>
+ The <code class="command">VAR</code> command is a PostgreSQL extension.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-type.html" title="TYPE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-sql-whenever.html" title="WHENEVER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">TYPE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> WHENEVER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-sql-whenever.html b/doc/src/sgml/html/ecpg-sql-whenever.html
new file mode 100644
index 0000000..3d739ef
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-sql-whenever.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>WHENEVER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-sql-var.html" title="VAR" /><link rel="next" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">WHENEVER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-sql-var.html" title="VAR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><th width="60%" align="center">36.14. Embedded SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode">Next</a></td></tr></table><hr /></div><div class="refentry" id="ECPG-SQL-WHENEVER"><div class="titlepage"></div><div class="refnamediv"><h2>WHENEVER</h2><p>WHENEVER — specify the action to be taken when an SQL statement causes a specific class condition to be raised</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+WHENEVER { NOT FOUND | SQLERROR | SQLWARNING } <em class="replaceable"><code>action</code></em>
+</pre></div><div class="refsect1" id="id-1.7.5.20.19.3"><h2>Description</h2><p>
+ Define a behavior which is called on the special cases (Rows not
+ found, SQL warnings or errors) in the result of SQL execution.
+ </p></div><div class="refsect1" id="id-1.7.5.20.19.4"><h2>Parameters</h2><p>
+ See <a class="xref" href="ecpg-errors.html#ECPG-WHENEVER" title="36.8.1. Setting Callbacks">Section 36.8.1</a> for a description of the
+ parameters.
+ </p></div><div class="refsect1" id="id-1.7.5.20.19.5"><h2>Examples</h2><pre class="programlisting">
+EXEC SQL WHENEVER NOT FOUND CONTINUE;
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+EXEC SQL WHENEVER NOT FOUND DO CONTINUE;
+EXEC SQL WHENEVER SQLWARNING SQLPRINT;
+EXEC SQL WHENEVER SQLWARNING DO warn();
+EXEC SQL WHENEVER SQLERROR sqlprint;
+EXEC SQL WHENEVER SQLERROR CALL print2();
+EXEC SQL WHENEVER SQLERROR DO handle_error("select");
+EXEC SQL WHENEVER SQLERROR DO sqlnotice(NULL, NONO);
+EXEC SQL WHENEVER SQLERROR DO sqlprint();
+EXEC SQL WHENEVER SQLERROR GOTO error_label;
+EXEC SQL WHENEVER SQLERROR STOP;
+</pre><p>
+ A typical application is the use of <code class="literal">WHENEVER NOT FOUND
+ BREAK</code> to handle looping through result sets:
+</p><pre class="programlisting">
+int
+main(void)
+{
+ EXEC SQL CONNECT TO testdb AS con1;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+ EXEC SQL ALLOCATE DESCRIPTOR d;
+ EXEC SQL DECLARE cur CURSOR FOR SELECT current_database(), 'hoge', 256;
+ EXEC SQL OPEN cur;
+
+ /* when end of result set reached, break out of while loop */
+ EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+ while (1)
+ {
+ EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
+ ...
+ }
+
+ EXEC SQL CLOSE cur;
+ EXEC SQL COMMIT;
+
+ EXEC SQL DEALLOCATE DESCRIPTOR d;
+ EXEC SQL DISCONNECT ALL;
+
+ return 0;
+}
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.7.5.20.19.6"><h2>Compatibility</h2><p>
+ <code class="command">WHENEVER</code> is specified in the SQL standard, but
+ most of the actions are PostgreSQL extensions.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-sql-var.html" title="VAR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg-sql-commands.html" title="36.14. Embedded SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-informix-compat.html" title="36.15. Informix Compatibility Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">VAR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.15. <span class="productname">Informix</span> Compatibility Mode</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg-variables.html b/doc/src/sgml/html/ecpg-variables.html
new file mode 100644
index 0000000..e19508f
--- /dev/null
+++ b/doc/src/sgml/html/ecpg-variables.html
@@ -0,0 +1,881 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.4. Using Host Variables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-commands.html" title="36.3. Running SQL Commands" /><link rel="next" href="ecpg-dynamic.html" title="36.5. Dynamic SQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.4. Using Host Variables</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-commands.html" title="36.3. Running SQL Commands">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><th width="60%" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-dynamic.html" title="36.5. Dynamic SQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="ECPG-VARIABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.4. Using Host Variables</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-OVERVIEW">36.4.1. Overview</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-DECLARE-SECTIONS">36.4.2. Declare Sections</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-RETRIEVING">36.4.3. Retrieving Query Results</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-TYPE-MAPPING">36.4.4. Type Mapping</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-NONPRIMITIVE-SQL">36.4.5. Handling Nonprimitive SQL Data Types</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-INDICATORS">36.4.6. Indicators</a></span></dt></dl></div><p>
+ In <a class="xref" href="ecpg-commands.html" title="36.3. Running SQL Commands">Section 36.3</a> 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
+ the values returned by the query. Those kinds of statements are
+ not really useful in real applications. This section explains in
+ detail how you can pass data between your C program and the
+ embedded SQL statements using a simple mechanism called
+ <em class="firstterm">host variables</em>. In an embedded SQL program we
+ consider the SQL statements to be <em class="firstterm">guests</em> in the C
+ program code which is the <em class="firstterm">host language</em>. Therefore
+ the variables of the C program are called <em class="firstterm">host
+ variables</em>.
+ </p><p>
+ Another way to exchange values between PostgreSQL backends and ECPG
+ applications is the use of SQL descriptors, described
+ in <a class="xref" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Section 36.7</a>.
+ </p><div class="sect2" id="ECPG-VARIABLES-OVERVIEW"><div class="titlepage"><div><div><h3 class="title">36.4.1. Overview</h3></div></div></div><p>
+ Passing data between the C program and the SQL statements is
+ particularly simple in embedded SQL. Instead of having the
+ program paste the data into the statement, which entails various
+ complications, such as properly quoting the value, you can simply
+ write the name of a C variable into the SQL statement, prefixed by
+ a colon. For example:
+</p><pre class="programlisting">
+EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
+</pre><p>
+ This statement refers to two C variables named
+ <code class="varname">v1</code> and <code class="varname">v2</code> and also uses a
+ regular SQL string literal, to illustrate that you are not
+ restricted to use one kind of data or the other.
+ </p><p>
+ This style of inserting C variables in SQL statements works
+ anywhere a value expression is expected in an SQL statement.
+ </p></div><div class="sect2" id="ECPG-DECLARE-SECTIONS"><div class="titlepage"><div><div><h3 class="title">36.4.2. Declare Sections</h3></div></div></div><p>
+ To pass data from the program to the database, for example as
+ parameters in a query, or to pass data from the database back to
+ the program, the C variables that are intended to contain this
+ data need to be declared in specially marked sections, so the
+ embedded SQL preprocessor is made aware of them.
+ </p><p>
+ This section starts with:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+</pre><p>
+ and ends with:
+</p><pre class="programlisting">
+EXEC SQL END DECLARE SECTION;
+</pre><p>
+ Between those lines, there must be normal C variable declarations,
+ such as:
+</p><pre class="programlisting">
+int x = 4;
+char foo[16], bar[16];
+</pre><p>
+ As you can see, you can optionally assign an initial value to the variable.
+ The variable's scope is determined by the location of its declaring
+ section within the program.
+ You can also declare variables with the following syntax which implicitly
+ creates a declare section:
+</p><pre class="programlisting">
+EXEC SQL int i = 4;
+</pre><p>
+ You can have as many declare sections in a program as you like.
+ </p><p>
+ The declarations are also echoed to the output file as normal C
+ variables, so there's no need to declare them again. Variables
+ that are not intended to be used in SQL commands can be declared
+ normally outside these special sections.
+ </p><p>
+ The definition of a structure or union also must be listed inside
+ a <code class="literal">DECLARE</code> section. Otherwise the preprocessor cannot
+ handle these types since it does not know the definition.
+ </p></div><div class="sect2" id="ECPG-RETRIEVING"><div class="titlepage"><div><div><h3 class="title">36.4.3. Retrieving Query Results</h3></div></div></div><p>
+ Now you should be able to pass data generated by your program into
+ an SQL command. But how do you retrieve the results of a query?
+ For that purpose, embedded SQL provides special variants of the
+ usual commands <code class="command">SELECT</code> and
+ <code class="command">FETCH</code>. These commands have a special
+ <code class="literal">INTO</code> clause that specifies which host variables
+ the retrieved values are to be stored in.
+ <code class="command">SELECT</code> is used for a query that returns only
+ single row, and <code class="command">FETCH</code> is used for a query that
+ returns multiple rows, using a cursor.
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+/*
+ * assume this table:
+ * CREATE TABLE test1 (a int, b varchar(50));
+ */
+
+EXEC SQL BEGIN DECLARE SECTION;
+int v1;
+VARCHAR v2;
+EXEC SQL END DECLARE SECTION;
+
+ ...
+
+EXEC SQL SELECT a, b INTO :v1, :v2 FROM test;
+</pre><p>
+ So the <code class="literal">INTO</code> clause appears between the select
+ list and the <code class="literal">FROM</code> clause. The number of
+ elements in the select list and the list after
+ <code class="literal">INTO</code> (also called the target list) must be
+ equal.
+ </p><p>
+ Here is an example using the command <code class="command">FETCH</code>:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int v1;
+VARCHAR v2;
+EXEC SQL END DECLARE SECTION;
+
+ ...
+
+EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test;
+
+ ...
+
+do
+{
+ ...
+ EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2;
+ ...
+} while (...);
+</pre><p>
+ Here the <code class="literal">INTO</code> clause appears after all the
+ normal clauses.
+ </p></div><div class="sect2" id="ECPG-VARIABLES-TYPE-MAPPING"><div class="titlepage"><div><div><h3 class="title">36.4.4. Type Mapping</h3></div></div></div><p>
+ When ECPG applications exchange values between the PostgreSQL
+ server and the C application, such as when retrieving query
+ results from the server or executing SQL statements with input
+ parameters, the values need to be converted between PostgreSQL
+ data types and host language variable types (C language data
+ types, concretely). One of the main points of ECPG is that it
+ takes care of this automatically in most cases.
+ </p><p>
+ In this respect, there are two kinds of data types: Some simple
+ PostgreSQL data types, such as <code class="type">integer</code>
+ and <code class="type">text</code>, can be read and written by the application
+ directly. Other PostgreSQL data types, such
+ as <code class="type">timestamp</code> and <code class="type">numeric</code> can only be
+ accessed through special library functions; see
+ <a class="xref" href="ecpg-variables.html#ECPG-SPECIAL-TYPES" title="36.4.4.2. Accessing Special Data Types">Section 36.4.4.2</a>.
+ </p><p>
+ <a class="xref" href="ecpg-variables.html#ECPG-DATATYPE-HOSTVARS-TABLE" title="Table 36.1. Mapping Between PostgreSQL Data Types and C Variable Types">Table 36.1</a> 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
+ the declare section.
+ </p><div class="table" id="ECPG-DATATYPE-HOSTVARS-TABLE"><p class="title"><strong>Table 36.1. Mapping Between PostgreSQL Data Types and C Variable Types</strong></p><div class="table-contents"><table class="table" summary="Mapping Between PostgreSQL Data Types and C Variable Types" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>PostgreSQL data type</th><th>Host variable type</th></tr></thead><tbody><tr><td><code class="type">smallint</code></td><td><code class="type">short</code></td></tr><tr><td><code class="type">integer</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">bigint</code></td><td><code class="type">long long int</code></td></tr><tr><td><code class="type">decimal</code></td><td><code class="type">decimal</code><a href="#ftn.ECPG-DATATYPE-TABLE-FN" class="footnote"><sup class="footnote" id="ECPG-DATATYPE-TABLE-FN">[a]</sup></a></td></tr><tr><td><code class="type">numeric</code></td><td><code class="type">numeric</code><a href="ecpg-variables.html#ftn.ECPG-DATATYPE-TABLE-FN" class="footnoteref"><sup class="footnoteref">[a]</sup></a></td></tr><tr><td><code class="type">real</code></td><td><code class="type">float</code></td></tr><tr><td><code class="type">double precision</code></td><td><code class="type">double</code></td></tr><tr><td><code class="type">smallserial</code></td><td><code class="type">short</code></td></tr><tr><td><code class="type">serial</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">bigserial</code></td><td><code class="type">long long int</code></td></tr><tr><td><code class="type">oid</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">varchar(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">text</code></td><td><code class="type">char[<em class="replaceable"><code>n</code></em>+1]</code>, <code class="type">VARCHAR[<em class="replaceable"><code>n</code></em>+1]</code></td></tr><tr><td><code class="type">name</code></td><td><code class="type">char[NAMEDATALEN]</code></td></tr><tr><td><code class="type">timestamp</code></td><td><code class="type">timestamp</code><a href="ecpg-variables.html#ftn.ECPG-DATATYPE-TABLE-FN" class="footnoteref"><sup class="footnoteref">[a]</sup></a></td></tr><tr><td><code class="type">interval</code></td><td><code class="type">interval</code><a href="ecpg-variables.html#ftn.ECPG-DATATYPE-TABLE-FN" class="footnoteref"><sup class="footnoteref">[a]</sup></a></td></tr><tr><td><code class="type">date</code></td><td><code class="type">date</code><a href="ecpg-variables.html#ftn.ECPG-DATATYPE-TABLE-FN" class="footnoteref"><sup class="footnoteref">[a]</sup></a></td></tr><tr><td><code class="type">boolean</code></td><td><code class="type">bool</code><a href="#ftn.id-1.7.5.10.7.5.2.2.17.2.2" class="footnote"><sup class="footnote" id="id-1.7.5.10.7.5.2.2.17.2.2">[b]</sup></a></td></tr><tr><td><code class="type">bytea</code></td><td><code class="type">char *</code>, <code class="type">bytea[<em class="replaceable"><code>n</code></em>]</code></td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div id="ftn.ECPG-DATATYPE-TABLE-FN" class="footnote"><p><a href="#ECPG-DATATYPE-TABLE-FN" class="para"><sup class="para">[a] </sup></a>This type can only be accessed through special library functions; see <a class="xref" href="ecpg-variables.html#ECPG-SPECIAL-TYPES" title="36.4.4.2. Accessing Special Data Types">Section 36.4.4.2</a>.</p></div><div id="ftn.id-1.7.5.10.7.5.2.2.17.2.2" class="footnote"><p><a href="#id-1.7.5.10.7.5.2.2.17.2.2" class="para"><sup class="para">[b] </sup></a>declared in <code class="filename">ecpglib.h</code> if not native</p></div></td></tr></tbody></table></div></div><br class="table-break" /><div class="sect3" id="ECPG-CHAR"><div class="titlepage"><div><div><h4 class="title">36.4.4.1. Handling Character Strings</h4></div></div></div><p>
+ To handle SQL character string data types, such
+ as <code class="type">varchar</code> and <code class="type">text</code>, there are two
+ possible ways to declare the host variables.
+ </p><p>
+ One way is using <code class="type">char[]</code>, an array
+ of <code class="type">char</code>, which is the most common way to handle
+ character data in C.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ char str[50];
+EXEC SQL END DECLARE SECTION;
+</pre><p>
+ Note that you have to take care of the length yourself. If you
+ use this host variable as the target variable of a query which
+ returns a string with more than 49 characters, a buffer overflow
+ occurs.
+ </p><p>
+ The other way is using the <code class="type">VARCHAR</code> type, which is a
+ special type provided by ECPG. The definition on an array of
+ type <code class="type">VARCHAR</code> is converted into a
+ named <code class="type">struct</code> for every variable. A declaration like:
+</p><pre class="programlisting">
+VARCHAR var[180];
+</pre><p>
+ is converted into:
+</p><pre class="programlisting">
+struct varchar_var { int len; char arr[180]; } var;
+</pre><p>
+ The member <code class="structfield">arr</code> hosts the string
+ including a terminating zero byte. Thus, to store a string in
+ a <code class="type">VARCHAR</code> host variable, the host variable has to be
+ declared with the length including the zero byte terminator. The
+ member <code class="structfield">len</code> holds the length of the
+ string stored in the <code class="structfield">arr</code> without the
+ terminating zero byte. When a host variable is used as input for
+ a query, if <code class="literal">strlen(arr)</code>
+ and <code class="structfield">len</code> are different, the shorter one
+ is used.
+ </p><p>
+ <code class="type">VARCHAR</code> can be written in upper or lower case, but
+ not in mixed case.
+ </p><p>
+ <code class="type">char</code> and <code class="type">VARCHAR</code> host variables can
+ also hold values of other SQL types, which will be stored in
+ their string forms.
+ </p></div><div class="sect3" id="ECPG-SPECIAL-TYPES"><div class="titlepage"><div><div><h4 class="title">36.4.4.2. Accessing Special Data Types</h4></div></div></div><p>
+ ECPG contains some special types that help you to interact easily
+ with some special data types from the PostgreSQL server. In
+ particular, it has implemented support for the
+ <code class="type">numeric</code>, <code class="type">decimal</code>, <code class="type">date</code>, <code class="type">timestamp</code>,
+ and <code class="type">interval</code> types. These data types cannot usefully be
+ mapped to primitive host variable types (such
+ as <code class="type">int</code>, <code class="type">long long int</code>,
+ or <code class="type">char[]</code>), because they have a complex internal
+ 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 <a class="xref" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Section 36.6</a> 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.
+ </p><p>
+ The follow subsections describe these special data types. For
+ more details about pgtypes library functions,
+ see <a class="xref" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Section 36.6</a>.
+ </p><div class="sect4" id="id-1.7.5.10.7.7.4"><div class="titlepage"><div><div><h5 class="title">36.4.4.2.1. timestamp, date</h5></div></div></div><p>
+ Here is a pattern for handling <code class="type">timestamp</code> variables
+ in the ECPG host application.
+ </p><p>
+ First, the program has to include the header file for the
+ <code class="type">timestamp</code> type:
+</p><pre class="programlisting">
+#include &lt;pgtypes_timestamp.h&gt;
+</pre><p>
+ </p><p>
+ Next, declare a host variable as type <code class="type">timestamp</code> in
+ the declare section:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+timestamp ts;
+EXEC SQL END DECLARE SECTION;
+</pre><p>
+ </p><p>
+ And after reading a value into the host variable, process it
+ using pgtypes library functions. In following example, the
+ <code class="type">timestamp</code> value is converted into text (ASCII) form
+ with the <code class="function">PGTYPEStimestamp_to_asc()</code>
+ function:
+</p><pre class="programlisting">
+EXEC SQL SELECT now()::timestamp INTO :ts;
+
+printf("ts = %s\n", PGTYPEStimestamp_to_asc(ts));
+</pre><p>
+ This example will show some result like following:
+</p><pre class="screen">
+ts = 2010-06-27 18:03:56.949343
+</pre><p>
+ </p><p>
+ In addition, the DATE type can be handled in the same way. The
+ program has to include <code class="filename">pgtypes_date.h</code>, declare a host variable
+ as the date type and convert a DATE value into a text form using
+ <code class="function">PGTYPESdate_to_asc()</code> function. For more details about the
+ pgtypes library functions, see <a class="xref" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Section 36.6</a>.
+ </p></div><div class="sect4" id="ECPG-TYPE-INTERVAL"><div class="titlepage"><div><div><h5 class="title">36.4.4.2.2. interval</h5></div></div></div><p>
+ The handling of the <code class="type">interval</code> type is also similar
+ to the <code class="type">timestamp</code> and <code class="type">date</code> types. It
+ is required, however, to allocate memory for
+ an <code class="type">interval</code> type value explicitly. In other words,
+ the memory space for the variable has to be allocated in the
+ heap memory, not in the stack memory.
+ </p><p>
+ Here is an example program:
+</p><pre class="programlisting">
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;pgtypes_interval.h&gt;
+
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ interval *in;
+EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO testdb;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ in = PGTYPESinterval_new();
+ EXEC SQL SELECT '1 min'::interval INTO :in;
+ printf("interval = %s\n", PGTYPESinterval_to_asc(in));
+ PGTYPESinterval_free(in);
+
+ EXEC SQL COMMIT;
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre><p>
+ </p></div><div class="sect4" id="ECPG-TYPE-NUMERIC-DECIMAL"><div class="titlepage"><div><div><h5 class="title">36.4.4.2.3. numeric, decimal</h5></div></div></div><p>
+ The handling of the <code class="type">numeric</code>
+ and <code class="type">decimal</code> types is similar to the
+ <code class="type">interval</code> type: It requires defining a pointer,
+ 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 <a class="xref" href="ecpg-pgtypes.html" title="36.6. pgtypes Library">Section 36.6</a>.
+ </p><p>
+ No functions are provided specifically for
+ the <code class="type">decimal</code> type. An application has to convert it
+ to a <code class="type">numeric</code> variable using a pgtypes library
+ function to do further processing.
+ </p><p>
+ Here is an example program handling <code class="type">numeric</code>
+ and <code class="type">decimal</code> type variables.
+</p><pre class="programlisting">
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;pgtypes_numeric.h&gt;
+
+EXEC SQL WHENEVER SQLERROR STOP;
+
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ numeric *num;
+ numeric *num2;
+ decimal *dec;
+EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL CONNECT TO testdb;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ num = PGTYPESnumeric_new();
+ dec = PGTYPESdecimal_new();
+
+ EXEC SQL SELECT 12.345::numeric(4,2), 23.456::decimal(4,2) INTO :num, :dec;
+
+ printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 0));
+ printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 1));
+ printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 2));
+
+ /* Convert decimal to numeric to show a decimal value. */
+ num2 = PGTYPESnumeric_new();
+ PGTYPESnumeric_from_decimal(dec, num2);
+
+ printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 0));
+ printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 1));
+ printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 2));
+
+ PGTYPESnumeric_free(num2);
+ PGTYPESdecimal_free(dec);
+ PGTYPESnumeric_free(num);
+
+ EXEC SQL COMMIT;
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre><p>
+ </p></div><div class="sect4" id="id-1.7.5.10.7.7.7"><div class="titlepage"><div><div><h5 class="title">36.4.4.2.4. bytea</h5></div></div></div><p>
+ The handling of the <code class="type">bytea</code> type is similar to
+ that of <code class="type">VARCHAR</code>. The definition on an array of type
+ <code class="type">bytea</code> is converted into a named struct for every
+ variable. A declaration like:
+</p><pre class="programlisting">
+bytea var[180];
+</pre><p>
+ is converted into:
+</p><pre class="programlisting">
+struct bytea_var { int len; char arr[180]; } var;
+</pre><p>
+ The member <code class="structfield">arr</code> hosts binary format
+ data. It can also handle <code class="literal">'\0'</code> as part of
+ data, unlike <code class="type">VARCHAR</code>.
+ The data is converted from/to hex format and sent/received by
+ ecpglib.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="type">bytea</code> variable can be used only when
+ <a class="xref" href="runtime-config-client.html#GUC-BYTEA-OUTPUT">bytea_output</a> is set to <code class="literal">hex</code>.
+ </p></div></div></div><div class="sect3" id="ECPG-VARIABLES-NONPRIMITIVE-C"><div class="titlepage"><div><div><h4 class="title">36.4.4.3. Host Variables with Nonprimitive Types</h4></div></div></div><p>
+ As a host variable you can also use arrays, typedefs, structs, and
+ pointers.
+ </p><div class="sect4" id="ECPG-VARIABLES-ARRAYS"><div class="titlepage"><div><div><h5 class="title">36.4.4.3.1. Arrays</h5></div></div></div><p>
+ There are two use cases for arrays as host variables. The first
+ is a way to store some text string in <code class="type">char[]</code>
+ or <code class="type">VARCHAR[]</code>, as
+ explained in <a class="xref" href="ecpg-variables.html#ECPG-CHAR" title="36.4.4.1. Handling Character Strings">Section 36.4.4.1</a>. 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
+ the <code class="command">FETCH</code> command. But with array host
+ variables, multiple rows can be received at once. The length of
+ the array has to be defined to be able to accommodate all rows,
+ otherwise a buffer overflow will likely occur.
+ </p><p>
+ Following example scans the <code class="literal">pg_database</code>
+ system table and shows all OIDs and names of the available
+ databases:
+</p><pre class="programlisting">
+int
+main(void)
+{
+EXEC SQL BEGIN DECLARE SECTION;
+ int dbid[8];
+ char dbname[8][16];
+ int i;
+EXEC SQL END DECLARE SECTION;
+
+ memset(dbname, 0, sizeof(char)* 16 * 8);
+ memset(dbid, 0, sizeof(int) * 8);
+
+ EXEC SQL CONNECT TO testdb;
+ EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
+
+ /* Retrieve multiple rows into arrays at once. */
+ EXEC SQL SELECT oid,datname INTO :dbid, :dbname FROM pg_database;
+
+ for (i = 0; i &lt; 8; i++)
+ printf("oid=%d, dbname=%s\n", dbid[i], dbname[i]);
+
+ EXEC SQL COMMIT;
+ EXEC SQL DISCONNECT ALL;
+ return 0;
+}
+</pre><p>
+
+ This example shows following result. (The exact values depend on
+ local circumstances.)
+</p><pre class="screen">
+oid=1, dbname=template1
+oid=11510, dbname=template0
+oid=11511, dbname=postgres
+oid=313780, dbname=testdb
+oid=0, dbname=
+oid=0, dbname=
+oid=0, dbname=
+</pre><p>
+ </p></div><div class="sect4" id="ECPG-VARIABLES-STRUCT"><div class="titlepage"><div><div><h5 class="title">36.4.4.3.2. Structures</h5></div></div></div><p>
+ A structure whose member names match the column names of a query
+ result, can be used to retrieve multiple columns at once. The
+ structure enables handling multiple column values in a single
+ host variable.
+ </p><p>
+ The following example retrieves OIDs, names, and sizes of the
+ available databases from the <code class="literal">pg_database</code>
+ system table and using
+ the <code class="function">pg_database_size()</code> function. In this
+ example, a structure variable <code class="varname">dbinfo_t</code> with
+ members whose names match each column in
+ the <code class="literal">SELECT</code> result is used to retrieve one
+ result row without putting multiple host variables in
+ the <code class="literal">FETCH</code> statement.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ typedef struct
+ {
+ int oid;
+ char datname[65];
+ long long int size;
+ } dbinfo_t;
+
+ dbinfo_t dbval;
+EXEC SQL END DECLARE SECTION;
+
+ memset(&amp;dbval, 0, sizeof(dbinfo_t));
+
+ EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
+ EXEC SQL OPEN cur1;
+
+ /* when end of result set reached, break out of while loop */
+ EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+ while (1)
+ {
+ /* Fetch multiple columns into one structure. */
+ EXEC SQL FETCH FROM cur1 INTO :dbval;
+
+ /* Print members of the structure. */
+ printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, dbval.size);
+ }
+
+ EXEC SQL CLOSE cur1;
+</pre><p>
+ </p><p>
+ This example shows following result. (The exact values depend on
+ local circumstances.)
+</p><pre class="screen">
+oid=1, datname=template1, size=4324580
+oid=11510, datname=template0, size=4243460
+oid=11511, datname=postgres, size=4324580
+oid=313780, datname=testdb, size=8183012
+</pre><p>
+ </p><p>
+ Structure host variables <span class="quote">“<span class="quote">absorb</span>”</span> as many columns
+ as the structure as fields. Additional columns can be assigned
+ to other host variables. For example, the above program could
+ also be restructured like this, with the <code class="varname">size</code>
+ variable outside the structure:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ typedef struct
+ {
+ int oid;
+ char datname[65];
+ } dbinfo_t;
+
+ dbinfo_t dbval;
+ long long int size;
+EXEC SQL END DECLARE SECTION;
+
+ memset(&amp;dbval, 0, sizeof(dbinfo_t));
+
+ EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
+ EXEC SQL OPEN cur1;
+
+ /* when end of result set reached, break out of while loop */
+ EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+ while (1)
+ {
+ /* Fetch multiple columns into one structure. */
+ EXEC SQL FETCH FROM cur1 INTO :dbval, :size;
+
+ /* Print members of the structure. */
+ printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, size);
+ }
+
+ EXEC SQL CLOSE cur1;
+</pre><p>
+ </p></div><div class="sect4" id="id-1.7.5.10.7.8.5"><div class="titlepage"><div><div><h5 class="title">36.4.4.3.3. Typedefs</h5></div></div></div><p>
+ Use the <code class="literal">typedef</code> keyword to map new types to already
+ existing types.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ typedef char mychartype[40];
+ typedef long serial_t;
+EXEC SQL END DECLARE SECTION;
+</pre><p>
+ Note that you could also use:
+</p><pre class="programlisting">
+EXEC SQL TYPE serial_t IS long;
+</pre><p>
+ This declaration does not need to be part of a declare section.
+ </p></div><div class="sect4" id="id-1.7.5.10.7.8.6"><div class="titlepage"><div><div><h5 class="title">36.4.4.3.4. Pointers</h5></div></div></div><p>
+ 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 <a class="xref" href="ecpg-descriptors.html" title="36.7. Using Descriptor Areas">Section 36.7</a>
+ for more information on auto-allocation.
+ </p><p>
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ int *intp;
+ char **charp;
+EXEC SQL END DECLARE SECTION;
+</pre><p>
+ </p></div></div></div><div class="sect2" id="ECPG-VARIABLES-NONPRIMITIVE-SQL"><div class="titlepage"><div><div><h3 class="title">36.4.5. Handling Nonprimitive SQL Data Types</h3></div></div></div><p>
+ This section contains information on how to handle nonscalar and
+ user-defined SQL-level data types in ECPG applications. Note that
+ this is distinct from the handling of host variables of
+ nonprimitive types, described in the previous section.
+ </p><div class="sect3" id="id-1.7.5.10.8.3"><div class="titlepage"><div><div><h4 class="title">36.4.5.1. Arrays</h4></div></div></div><p>
+ Multi-dimensional SQL-level arrays are not directly supported in ECPG.
+ One-dimensional SQL-level arrays can be mapped into C array host
+ variables and vice-versa. However, when creating a statement ecpg does
+ not know the types of the columns, so that it cannot check if a C array
+ is input into a corresponding SQL-level array. When processing the
+ output of an SQL statement, ecpg has the necessary information and thus
+ checks if both are arrays.
+ </p><p>
+ If a query accesses <span class="emphasis"><em>elements</em></span> of an array
+ separately, then this avoids the use of arrays in ECPG. Then, a
+ host variable with a type that can be mapped to the element type
+ should be used. For example, if a column type is array of
+ <code class="type">integer</code>, a host variable of type <code class="type">int</code>
+ can be used. Also if the element type is <code class="type">varchar</code>
+ or <code class="type">text</code>, a host variable of type <code class="type">char[]</code>
+ or <code class="type">VARCHAR[]</code> can be used.
+ </p><p>
+ Here is an example. Assume the following table:
+</p><pre class="programlisting">
+CREATE TABLE t3 (
+ ii integer[]
+);
+
+testdb=&gt; SELECT * FROM t3;
+ ii
+-------------
+ {1,2,3,4,5}
+(1 row)
+</pre><p>
+
+ The following example program retrieves the 4th element of the
+ array and stores it into a host variable of
+ type <code class="type">int</code>:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int ii;
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[4] FROM t3;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ EXEC SQL FETCH FROM cur1 INTO :ii ;
+ printf("ii=%d\n", ii);
+}
+
+EXEC SQL CLOSE cur1;
+</pre><p>
+
+ This example shows the following result:
+</p><pre class="screen">
+ii=4
+</pre><p>
+ </p><p>
+ To map multiple array elements to the multiple elements in an
+ array type host variables each element of array column and each
+ element of the host variable array have to be managed separately,
+ for example:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int ii_a[8];
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[1], ii[2], ii[3], ii[4] FROM t3;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ EXEC SQL FETCH FROM cur1 INTO :ii_a[0], :ii_a[1], :ii_a[2], :ii_a[3];
+ ...
+}
+</pre><p>
+ </p><p>
+ Note again that
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int ii_a[8];
+EXEC SQL END DECLARE SECTION;
+
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii FROM t3;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ /* WRONG */
+ EXEC SQL FETCH FROM cur1 INTO :ii_a;
+ ...
+}
+</pre><p>
+ would not work correctly in this case, because you cannot map an
+ array type column to an array host variable directly.
+ </p><p>
+ Another workaround is to store arrays in their external string
+ representation in host variables of type <code class="type">char[]</code>
+ or <code class="type">VARCHAR[]</code>. For more details about this
+ representation, see <a class="xref" href="arrays.html#ARRAYS-INPUT" title="8.15.2. Array Value Input">Section 8.15.2</a>. 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).
+ </p></div><div class="sect3" id="id-1.7.5.10.8.4"><div class="titlepage"><div><div><h4 class="title">36.4.5.2. Composite Types</h4></div></div></div><p>
+ Composite types are not directly supported in ECPG, but an easy workaround is possible.
+ The
+ available workarounds are similar to the ones described for
+ arrays above: Either access each attribute separately or use the
+ external string representation.
+ </p><p>
+ For the following examples, assume the following type and table:
+</p><pre class="programlisting">
+CREATE TYPE comp_t AS (intval integer, textval varchar(32));
+CREATE TABLE t4 (compval comp_t);
+INSERT INTO t4 VALUES ( (256, 'PostgreSQL') );
+</pre><p>
+
+ The most obvious solution is to access each attribute separately.
+ The following program retrieves data from the example table by
+ selecting each attribute of the type <code class="type">comp_t</code>
+ separately:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+int intval;
+varchar textval[33];
+EXEC SQL END DECLARE SECTION;
+
+/* Put each element of the composite type column in the SELECT list. */
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ /* Fetch each element of the composite type column into host variables. */
+ EXEC SQL FETCH FROM cur1 INTO :intval, :textval;
+
+ printf("intval=%d, textval=%s\n", intval, textval.arr);
+}
+
+EXEC SQL CLOSE cur1;
+</pre><p>
+ </p><p>
+ To enhance this example, the host variables to store values in
+ the <code class="command">FETCH</code> command can be gathered into one
+ structure. For more details about the host variable in the
+ structure form, see <a class="xref" href="ecpg-variables.html#ECPG-VARIABLES-STRUCT" title="36.4.4.3.2. Structures">Section 36.4.4.3.2</a>.
+ To switch to the structure, the example can be modified as below.
+ The two host variables, <code class="varname">intval</code>
+ and <code class="varname">textval</code>, become members of
+ the <code class="structname">comp_t</code> structure, and the structure
+ is specified on the <code class="command">FETCH</code> command.
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+typedef struct
+{
+ int intval;
+ varchar textval[33];
+} comp_t;
+
+comp_t compval;
+EXEC SQL END DECLARE SECTION;
+
+/* Put each element of the composite type column in the SELECT list. */
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ /* Put all values in the SELECT list into one structure. */
+ EXEC SQL FETCH FROM cur1 INTO :compval;
+
+ printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
+}
+
+EXEC SQL CLOSE cur1;
+</pre><p>
+
+ Although a structure is used in the <code class="command">FETCH</code>
+ command, the attribute names in the <code class="command">SELECT</code>
+ clause are specified one by one. This can be enhanced by using
+ a <code class="literal">*</code> to ask for all attributes of the composite
+ type value.
+</p><pre class="programlisting">
+...
+EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).* FROM t4;
+EXEC SQL OPEN cur1;
+
+EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+while (1)
+{
+ /* Put all values in the SELECT list into one structure. */
+ EXEC SQL FETCH FROM cur1 INTO :compval;
+
+ printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
+}
+...
+</pre><p>
+ This way, composite types can be mapped into structures almost
+ seamlessly, even though ECPG does not understand the composite
+ type itself.
+ </p><p>
+ Finally, it is also possible to store composite type values in
+ their external string representation in host variables of
+ type <code class="type">char[]</code> or <code class="type">VARCHAR[]</code>. But that
+ way, it is not easily possible to access the fields of the value
+ from the host program.
+ </p></div><div class="sect3" id="id-1.7.5.10.8.5"><div class="titlepage"><div><div><h4 class="title">36.4.5.3. User-Defined Base Types</h4></div></div></div><p>
+ New user-defined base types are not directly supported by ECPG.
+ You can use the external string representation and host variables
+ of type <code class="type">char[]</code> or <code class="type">VARCHAR[]</code>, and this
+ solution is indeed appropriate and sufficient for many types.
+ </p><p>
+ Here is an example using the data type <code class="type">complex</code> from
+ the example in <a class="xref" href="xtypes.html" title="38.13. User-Defined Types">Section 38.13</a>. The external string
+ representation of that type is <code class="literal">(%f,%f)</code>,
+ which is defined in the
+ functions <code class="function">complex_in()</code>
+ and <code class="function">complex_out()</code> functions
+ in <a class="xref" href="xtypes.html" title="38.13. User-Defined Types">Section 38.13</a>. The following example inserts the
+ complex type values <code class="literal">(1,1)</code>
+ and <code class="literal">(3,3)</code> into the
+ columns <code class="literal">a</code> and <code class="literal">b</code>, and select
+ them from the table after that.
+
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+ varchar a[64];
+ varchar b[64];
+EXEC SQL END DECLARE SECTION;
+
+ EXEC SQL INSERT INTO test_complex VALUES ('(1,1)', '(3,3)');
+
+ EXEC SQL DECLARE cur1 CURSOR FOR SELECT a, b FROM test_complex;
+ EXEC SQL OPEN cur1;
+
+ EXEC SQL WHENEVER NOT FOUND DO BREAK;
+
+ while (1)
+ {
+ EXEC SQL FETCH FROM cur1 INTO :a, :b;
+ printf("a=%s, b=%s\n", a.arr, b.arr);
+ }
+
+ EXEC SQL CLOSE cur1;
+</pre><p>
+
+ This example shows following result:
+</p><pre class="screen">
+a=(1,1), b=(3,3)
+</pre><p>
+ </p><p>
+ Another workaround is avoiding the direct use of the user-defined
+ types in ECPG and instead create a function or cast that converts
+ between the user-defined type and a primitive type that ECPG can
+ handle. Note, however, that type casts, especially implicit
+ ones, should be introduced into the type system very carefully.
+ </p><p>
+ For example,
+</p><pre class="programlisting">
+CREATE FUNCTION create_complex(r double, i double) RETURNS complex
+LANGUAGE SQL
+IMMUTABLE
+AS $$ SELECT $1 * complex '(1,0')' + $2 * complex '(0,1)' $$;
+</pre><p>
+ After this definition, the following
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+double a, b, c, d;
+EXEC SQL END DECLARE SECTION;
+
+a = 1;
+b = 2;
+c = 3;
+d = 4;
+
+EXEC SQL INSERT INTO test_complex VALUES (create_complex(:a, :b), create_complex(:c, :d));
+</pre><p>
+ has the same effect as
+</p><pre class="programlisting">
+EXEC SQL INSERT INTO test_complex VALUES ('(1,2)', '(3,4)');
+</pre><p>
+ </p></div></div><div class="sect2" id="ECPG-INDICATORS"><div class="titlepage"><div><div><h3 class="title">36.4.6. Indicators</h3></div></div></div><p>
+ The examples above do not handle null values. In fact, the
+ retrieval examples will raise an error if they fetch a null value
+ from the database. To be able to pass null values to the database
+ or retrieve null values from the database, you need to append a
+ second host variable specification to each host variable that
+ contains data. This second host variable is called the
+ <em class="firstterm">indicator</em> and contains a flag that tells
+ whether the datum is null, in which case the value of the real
+ host variable is ignored. Here is an example that handles the
+ retrieval of null values correctly:
+</p><pre class="programlisting">
+EXEC SQL BEGIN DECLARE SECTION;
+VARCHAR val;
+int val_ind;
+EXEC SQL END DECLARE SECTION:
+
+ ...
+
+EXEC SQL SELECT b INTO :val :val_ind FROM test1;
+</pre><p>
+ The indicator variable <code class="varname">val_ind</code> will be zero if
+ the value was not null, and it will be negative if the value was
+ null. (See <a class="xref" href="ecpg-oracle-compat.html" title="36.16. Oracle Compatibility Mode">Section 36.16</a> to enable
+ Oracle-specific behavior.)
+ </p><p>
+ The indicator has another function: if the indicator value is
+ positive, it means that the value is not null, but it was
+ truncated when it was stored in the host variable.
+ </p><p>
+ If the argument <code class="literal">-r no_indicator</code> is passed to
+ the preprocessor <code class="command">ecpg</code>, it works in
+ <span class="quote">“<span class="quote">no-indicator</span>”</span> mode. In no-indicator mode, if no
+ indicator variable is specified, null values are signaled (on
+ input and output) for character string types as empty string and
+ for integer types as the lowest possible value for type (for
+ example, <code class="symbol">INT_MIN</code> for <code class="type">int</code>).
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-commands.html" title="36.3. Running SQL Commands">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-dynamic.html" title="36.5. Dynamic SQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.3. Running SQL Commands </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.5. Dynamic SQL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ecpg.html b/doc/src/sgml/html/ecpg.html
new file mode 100644
index 0000000..816e0ec
--- /dev/null
+++ b/doc/src/sgml/html/ecpg.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 36. ECPG — Embedded SQL in C</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-examplesect.html" title="35.5. Example Program" /><link rel="next" href="ecpg-concept.html" title="36.1. The Concept" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-examplesect.html" title="35.5. Example Program">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><th width="60%" align="center">Part IV. Client Interfaces</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg-concept.html" title="36.1. The Concept">Next</a></td></tr></table><hr /></div><div class="chapter" id="ECPG"><div class="titlepage"><div><div><h2 class="title">Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="ecpg-concept.html">36.1. The Concept</a></span></dt><dt><span class="sect1"><a href="ecpg-connect.html">36.2. Managing Database Connections</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-CONNECTING">36.2.1. Connecting to the Database Server</a></span></dt><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-SET-CONNECTION">36.2.2. Choosing a Connection</a></span></dt><dt><span class="sect2"><a href="ecpg-connect.html#ECPG-DISCONNECT">36.2.3. Closing a Connection</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-commands.html">36.3. Running SQL Commands</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-EXECUTING">36.3.1. Executing SQL Statements</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-CURSORS">36.3.2. Using Cursors</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-TRANSACTIONS">36.3.3. Managing Transactions</a></span></dt><dt><span class="sect2"><a href="ecpg-commands.html#ECPG-PREPARED">36.3.4. Prepared Statements</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-variables.html">36.4. Using Host Variables</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-OVERVIEW">36.4.1. Overview</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-DECLARE-SECTIONS">36.4.2. Declare Sections</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-RETRIEVING">36.4.3. Retrieving Query Results</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-TYPE-MAPPING">36.4.4. Type Mapping</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-VARIABLES-NONPRIMITIVE-SQL">36.4.5. Handling Nonprimitive SQL Data Types</a></span></dt><dt><span class="sect2"><a href="ecpg-variables.html#ECPG-INDICATORS">36.4.6. Indicators</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-dynamic.html">36.5. Dynamic SQL</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-WITHOUT-RESULT">36.5.1. Executing Statements without a Result Set</a></span></dt><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-INPUT">36.5.2. Executing a Statement with Input Parameters</a></span></dt><dt><span class="sect2"><a href="ecpg-dynamic.html#ECPG-DYNAMIC-WITH-RESULT">36.5.3. Executing a Statement with a Result Set</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-pgtypes.html">36.6. pgtypes Library</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CSTRINGS">36.6.1. Character Strings</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-NUMERIC">36.6.2. The numeric Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DATE">36.6.3. The date Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-TIMESTAMP">36.6.4. The timestamp Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-INTERVAL">36.6.5. The interval Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-DECIMAL">36.6.6. The decimal Type</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-ERRNO">36.6.7. errno Values of pgtypeslib</a></span></dt><dt><span class="sect2"><a href="ecpg-pgtypes.html#ECPG-PGTYPES-CONSTANTS">36.6.8. Special Constants of pgtypeslib</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-descriptors.html">36.7. Using Descriptor Areas</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-descriptors.html#ECPG-NAMED-DESCRIPTORS">36.7.1. Named SQL Descriptor Areas</a></span></dt><dt><span class="sect2"><a href="ecpg-descriptors.html#ECPG-SQLDA-DESCRIPTORS">36.7.2. SQLDA Descriptor Areas</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-errors.html">36.8. Error Handling</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-WHENEVER">36.8.1. Setting Callbacks</a></span></dt><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-SQLCA">36.8.2. sqlca</a></span></dt><dt><span class="sect2"><a href="ecpg-errors.html#ECPG-SQLSTATE-SQLCODE">36.8.3. <code class="literal">SQLSTATE</code> vs. <code class="literal">SQLCODE</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-preproc.html">36.9. Preprocessor Directives</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-INCLUDE">36.9.1. Including Files</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-DEFINE">36.9.2. The define and undef Directives</a></span></dt><dt><span class="sect2"><a href="ecpg-preproc.html#ECPG-IFDEF">36.9.3. ifdef, ifndef, elif, else, and endif Directives</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-process.html">36.10. Processing Embedded SQL Programs</a></span></dt><dt><span class="sect1"><a href="ecpg-library.html">36.11. Library Functions</a></span></dt><dt><span class="sect1"><a href="ecpg-lo.html">36.12. Large Objects</a></span></dt><dt><span class="sect1"><a href="ecpg-cpp.html">36.13. <acronym class="acronym">C++</acronym> Applications</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-SCOPE">36.13.1. Scope for Host Variables</a></span></dt><dt><span class="sect2"><a href="ecpg-cpp.html#ECPG-CPP-AND-C">36.13.2. C++ Application Development with External C Module</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-sql-commands.html">36.14. Embedded SQL Commands</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="ecpg-sql-allocate-descriptor.html">ALLOCATE DESCRIPTOR</a></span><span class="refpurpose"> — allocate an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-connect.html">CONNECT</a></span><span class="refpurpose"> — establish a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-deallocate-descriptor.html">DEALLOCATE DESCRIPTOR</a></span><span class="refpurpose"> — deallocate an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-declare.html">DECLARE</a></span><span class="refpurpose"> — define a cursor</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-declare-statement.html">DECLARE STATEMENT</a></span><span class="refpurpose"> — declare SQL statement identifier</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-describe.html">DESCRIBE</a></span><span class="refpurpose"> — obtain information about a prepared statement or result set</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-disconnect.html">DISCONNECT</a></span><span class="refpurpose"> — terminate a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-execute-immediate.html">EXECUTE IMMEDIATE</a></span><span class="refpurpose"> — dynamically prepare and execute a statement</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-get-descriptor.html">GET DESCRIPTOR</a></span><span class="refpurpose"> — get information from an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-open.html">OPEN</a></span><span class="refpurpose"> — open a dynamic cursor</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-prepare.html">PREPARE</a></span><span class="refpurpose"> — prepare a statement for execution</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-autocommit.html">SET AUTOCOMMIT</a></span><span class="refpurpose"> — set the autocommit behavior of the current session</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-connection.html">SET CONNECTION</a></span><span class="refpurpose"> — select a database connection</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-set-descriptor.html">SET DESCRIPTOR</a></span><span class="refpurpose"> — set information in an SQL descriptor area</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-type.html">TYPE</a></span><span class="refpurpose"> — define a new data type</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-var.html">VAR</a></span><span class="refpurpose"> — define a variable</span></dt><dt><span class="refentrytitle"><a href="ecpg-sql-whenever.html">WHENEVER</a></span><span class="refpurpose"> — specify the action to be taken when an SQL statement causes a specific class condition to be raised</span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-informix-compat.html">36.15. <span class="productname">Informix</span> Compatibility Mode</a></span></dt><dd><dl><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-TYPES">36.15.1. Additional Types</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-STATEMENTS">36.15.2. Additional/Missing Embedded SQL Statements</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-SQLDA">36.15.3. Informix-compatible SQLDA Descriptor Areas</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-FUNCTIONS">36.15.4. Additional Functions</a></span></dt><dt><span class="sect2"><a href="ecpg-informix-compat.html#ECPG-INFORMIX-CONSTANTS">36.15.5. Additional Constants</a></span></dt></dl></dd><dt><span class="sect1"><a href="ecpg-oracle-compat.html">36.16. <span class="productname">Oracle</span> Compatibility Mode</a></span></dt><dt><span class="sect1"><a href="ecpg-develop.html">36.17. Internals</a></span></dt></dl></div><a id="id-1.7.5.2" class="indexterm"></a><a id="id-1.7.5.3" class="indexterm"></a><a id="id-1.7.5.4" class="indexterm"></a><p>
+ This chapter describes the embedded <acronym class="acronym">SQL</acronym> package
+ for <span class="productname">PostgreSQL</span>. It was written by
+ Linus Tolke (<code class="email">&lt;<a class="email" href="mailto:linus@epact.se">linus@epact.se</a>&gt;</code>) and Michael Meskes
+ (<code class="email">&lt;<a class="email" href="mailto:meskes@postgresql.org">meskes@postgresql.org</a>&gt;</code>). Originally it was written to work with
+ <acronym class="acronym">C</acronym>. It also works with <acronym class="acronym">C++</acronym>, but
+ it does not recognize all <acronym class="acronym">C++</acronym> constructs yet.
+ </p><p>
+ This documentation is quite incomplete. But since this
+ interface is standardized, additional information can be found in
+ many resources about SQL.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-examplesect.html" title="35.5. Example Program">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg-concept.html" title="36.1. The Concept">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.5. Example Program </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 36.1. The Concept</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/encryption-options.html b/doc/src/sgml/html/encryption-options.html
new file mode 100644
index 0000000..fc578d8
--- /dev/null
+++ b/doc/src/sgml/html/encryption-options.html
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.8. Encryption Options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing" /><link rel="next" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.8. Encryption Options</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Next</a></td></tr></table><hr /></div><div class="sect1" id="ENCRYPTION-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.8. Encryption Options</h2></div></div></div><a id="id-1.6.6.11.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> offers encryption at several
+ levels, and provides flexibility in protecting data from disclosure
+ due to database server theft, unscrupulous administrators, and
+ insecure networks. Encryption might also be required to secure
+ sensitive data such as medical records or financial transactions.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Password Encryption</span></dt><dd><p>
+ Database user passwords are stored as hashes (determined by the setting
+ <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a>), so the administrator cannot
+ determine the actual password assigned to the user. If SCRAM or MD5
+ encryption is used for client authentication, the unencrypted password is
+ never even temporarily present on the server because the client encrypts
+ it before being sent across the network. SCRAM is preferred, because it
+ is an Internet standard and is more secure than the PostgreSQL-specific
+ MD5 authentication protocol.
+ </p></dd><dt><span class="term">Encryption For Specific Columns</span></dt><dd><p>
+ The <a class="xref" href="pgcrypto.html" title="F.28. pgcrypto">pgcrypto</a> module allows certain fields to be
+ stored encrypted.
+ This is useful if only some of the data is sensitive.
+ The client supplies the decryption key and the data is decrypted
+ on the server and then sent to the client.
+ </p><p>
+ The decrypted data and the decryption key are present on the
+ server for a brief time while it is being decrypted and
+ communicated between the client and server. This presents a brief
+ moment where the data and keys can be intercepted by someone with
+ complete access to the database server, such as the system
+ administrator.
+ </p></dd><dt><span class="term">Data Partition Encryption</span></dt><dd><p>
+ Storage encryption can be performed at the file system level or the
+ block level. Linux file system encryption options include eCryptfs
+ and EncFS, while FreeBSD uses PEFS. Block level or full disk
+ encryption options include dm-crypt + LUKS on Linux and GEOM
+ modules geli and gbde on FreeBSD. Many other operating systems
+ support this functionality, including Windows.
+ </p><p>
+ This mechanism prevents unencrypted data from being read from the
+ drives if the drives or the entire computer is stolen. This does
+ not protect against attacks while the file system is mounted,
+ because when mounted, the operating system provides an unencrypted
+ view of the data. However, to mount the file system, you need some
+ way for the encryption key to be passed to the operating system,
+ and sometimes the key is stored somewhere on the host that mounts
+ the disk.
+ </p></dd><dt><span class="term">Encrypting Data Across A Network</span></dt><dd><p>
+ SSL connections encrypt all data sent across the network: the
+ password, the queries, and the data returned. The
+ <code class="filename">pg_hba.conf</code> file allows administrators to specify
+ which hosts can use non-encrypted connections (<code class="literal">host</code>)
+ and which require SSL-encrypted connections
+ (<code class="literal">hostssl</code>). Also, clients can specify that they
+ connect to servers only via SSL.
+ </p><p>
+ GSSAPI-encrypted connections encrypt all data sent across the network,
+ including queries and data returned. (No password is sent across the
+ network.) The <code class="filename">pg_hba.conf</code> file allows
+ administrators to specify which hosts can use non-encrypted connections
+ (<code class="literal">host</code>) and which require GSSAPI-encrypted connections
+ (<code class="literal">hostgssenc</code>). Also, clients can specify that they
+ connect to servers only on GSSAPI-encrypted connections
+ (<code class="literal">gssencmode=require</code>).
+ </p><p>
+ <span class="application">Stunnel</span> or
+ <span class="application">SSH</span> can also be used to encrypt
+ transmissions.
+ </p></dd><dt><span class="term">SSL Host Authentication</span></dt><dd><p>
+ It is possible for both the client and server to provide SSL
+ certificates to each other. It takes some extra configuration
+ on each side, but this provides stronger verification of identity
+ than the mere use of passwords. It prevents a computer from
+ pretending to be the server just long enough to read the password
+ sent by the client. It also helps prevent <span class="quote">“<span class="quote">man in the middle</span>”</span>
+ attacks where a computer between the client and server pretends to
+ be the server and reads and passes all data between the client and
+ server.
+ </p></dd><dt><span class="term">Client-Side Encryption</span></dt><dd><p>
+ If the system administrator for the server's machine cannot be trusted,
+ it is necessary
+ for the client to encrypt the data; this way, unencrypted data
+ never appears on the database server. Data is encrypted on the
+ client before being sent to the server, and database results have
+ to be decrypted on the client before being used.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.7. Preventing Server Spoofing </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.9. Secure TCP/IP Connections with SSL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/errcodes-appendix.html b/doc/src/sgml/html/errcodes-appendix.html
new file mode 100644
index 0000000..02abbc8
--- /dev/null
+++ b/doc/src/sgml/html/errcodes-appendix.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix A. PostgreSQL Error Codes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="appendixes.html" title="Part VIII. Appendixes" /><link rel="next" href="datetime-appendix.html" title="Appendix B. Date/Time Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix A. <span class="productname">PostgreSQL</span> Error Codes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="appendixes.html" title="Part VIII. Appendixes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Next</a></td></tr></table><hr /></div><div class="appendix" id="ERRCODES-APPENDIX"><div class="titlepage"><div><div><h2 class="title">Appendix A. <span class="productname">PostgreSQL</span> Error Codes</h2></div></div></div><a id="id-1.11.2.2" class="indexterm"></a><p>
+ All messages emitted by the <span class="productname">PostgreSQL</span>
+ server are assigned five-character error codes that follow the SQL
+ standard's conventions for <span class="quote">“<span class="quote">SQLSTATE</span>”</span> codes. Applications
+ that need to know which error condition has occurred should usually
+ test the error code, rather than looking at the textual error
+ message. The error codes are less likely to change across
+ <span class="productname">PostgreSQL</span> releases, and also are not subject to
+ change due to localization of error messages. Note that some, but
+ not all, of the error codes produced by <span class="productname">PostgreSQL</span>
+ are defined by the SQL standard; some additional error codes for
+ conditions not defined by the standard have been invented or
+ borrowed from other databases.
+ </p><p>
+ According to the standard, the first two characters of an error code
+ denote a class of errors, while the last three characters indicate
+ a specific condition within that class. Thus, an application that
+ does not recognize the specific error code might still be able to infer
+ what to do from the error class.
+ </p><p>
+ <a class="xref" href="errcodes-appendix.html#ERRCODES-TABLE" title="Table A.1. PostgreSQL Error Codes">Table A.1</a> lists all the error codes defined in
+ <span class="productname">PostgreSQL</span> 15.5. (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
+ <span class="quote">“<span class="quote">standard</span>”</span> error code having the last three characters
+ <code class="literal">000</code>. This code is used only for error conditions that fall
+ within the class but do not have any more-specific code assigned.
+ </p><p>
+ The symbol shown in the column <span class="quote">“<span class="quote">Condition Name</span>”</span> is
+ the condition name to use in <span class="application">PL/pgSQL</span>. Condition
+ names can be written in either upper or lower case. (Note that
+ <span class="application">PL/pgSQL</span> does not recognize warning, as opposed to error,
+ condition names; those are classes 00, 01, and 02.)
+ </p><p>
+ For some types of errors, the server reports the name of a database object
+ (a table, table column, data type, or constraint) associated with the error;
+ for example, the name of the unique constraint that caused a
+ <code class="symbol">unique_violation</code> error. Such names are supplied in separate
+ fields of the error report message so that applications need not try to
+ extract them from the possibly-localized human-readable text of the message.
+ As of <span class="productname">PostgreSQL</span> 9.3, complete coverage for this feature
+ exists only for errors in SQLSTATE class 23 (integrity constraint
+ violation), but this is likely to be expanded in future.
+ </p><div class="table" id="ERRCODES-TABLE"><p class="title"><strong>Table A.1. <span class="productname">PostgreSQL</span> Error Codes</strong></p><div class="table-contents"><table class="table" summary="PostgreSQL Error Codes" border="1"><colgroup><col class="errorcode" /><col class="condname" /></colgroup><thead><tr><th>Error Code</th><th>Condition Name</th></tr></thead><tbody><tr><td colspan="2"><span class="bold"><strong>Class 00 — Successful Completion</strong></span></td></tr><tr><td><code class="literal">00000</code></td><td><code class="symbol">successful_completion</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 01 — Warning</strong></span></td></tr><tr><td><code class="literal">01000</code></td><td><code class="symbol">warning</code></td></tr><tr><td><code class="literal">0100C</code></td><td><code class="symbol">dynamic_result_sets_returned</code></td></tr><tr><td><code class="literal">01008</code></td><td><code class="symbol">implicit_zero_bit_padding</code></td></tr><tr><td><code class="literal">01003</code></td><td><code class="symbol">null_value_eliminated_in_set_function</code></td></tr><tr><td><code class="literal">01007</code></td><td><code class="symbol">privilege_not_granted</code></td></tr><tr><td><code class="literal">01006</code></td><td><code class="symbol">privilege_not_revoked</code></td></tr><tr><td><code class="literal">01004</code></td><td><code class="symbol">string_data_right_truncation</code></td></tr><tr><td><code class="literal">01P01</code></td><td><code class="symbol">deprecated_feature</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 02 — No Data (this is also a warning class per the SQL standard)</strong></span></td></tr><tr><td><code class="literal">02000</code></td><td><code class="symbol">no_data</code></td></tr><tr><td><code class="literal">02001</code></td><td><code class="symbol">no_additional_dynamic_result_sets_returned</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 03 — SQL Statement Not Yet Complete</strong></span></td></tr><tr><td><code class="literal">03000</code></td><td><code class="symbol">sql_statement_not_yet_complete</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 08 — Connection Exception</strong></span></td></tr><tr><td><code class="literal">08000</code></td><td><code class="symbol">connection_exception</code></td></tr><tr><td><code class="literal">08003</code></td><td><code class="symbol">connection_does_not_exist</code></td></tr><tr><td><code class="literal">08006</code></td><td><code class="symbol">connection_failure</code></td></tr><tr><td><code class="literal">08001</code></td><td><code class="symbol">sqlclient_unable_to_establish_sqlconnection</code></td></tr><tr><td><code class="literal">08004</code></td><td><code class="symbol">sqlserver_rejected_establishment_of_sqlconnection</code></td></tr><tr><td><code class="literal">08007</code></td><td><code class="symbol">transaction_resolution_unknown</code></td></tr><tr><td><code class="literal">08P01</code></td><td><code class="symbol">protocol_violation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 09 — Triggered Action Exception</strong></span></td></tr><tr><td><code class="literal">09000</code></td><td><code class="symbol">triggered_action_exception</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0A — Feature Not Supported</strong></span></td></tr><tr><td><code class="literal">0A000</code></td><td><code class="symbol">feature_not_supported</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0B — Invalid Transaction Initiation</strong></span></td></tr><tr><td><code class="literal">0B000</code></td><td><code class="symbol">invalid_transaction_initiation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0F — Locator Exception</strong></span></td></tr><tr><td><code class="literal">0F000</code></td><td><code class="symbol">locator_exception</code></td></tr><tr><td><code class="literal">0F001</code></td><td><code class="symbol">invalid_locator_specification</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0L — Invalid Grantor</strong></span></td></tr><tr><td><code class="literal">0L000</code></td><td><code class="symbol">invalid_grantor</code></td></tr><tr><td><code class="literal">0LP01</code></td><td><code class="symbol">invalid_grant_operation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0P — Invalid Role Specification</strong></span></td></tr><tr><td><code class="literal">0P000</code></td><td><code class="symbol">invalid_role_specification</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 0Z — Diagnostics Exception</strong></span></td></tr><tr><td><code class="literal">0Z000</code></td><td><code class="symbol">diagnostics_exception</code></td></tr><tr><td><code class="literal">0Z002</code></td><td><code class="symbol">stacked_diagnostics_accessed_without_active_handler</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 20 — Case Not Found</strong></span></td></tr><tr><td><code class="literal">20000</code></td><td><code class="symbol">case_not_found</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 21 — Cardinality Violation</strong></span></td></tr><tr><td><code class="literal">21000</code></td><td><code class="symbol">cardinality_violation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 22 — Data Exception</strong></span></td></tr><tr><td><code class="literal">22000</code></td><td><code class="symbol">data_exception</code></td></tr><tr><td><code class="literal">2202E</code></td><td><code class="symbol">array_subscript_error</code></td></tr><tr><td><code class="literal">22021</code></td><td><code class="symbol">character_not_in_repertoire</code></td></tr><tr><td><code class="literal">22008</code></td><td><code class="symbol">datetime_field_overflow</code></td></tr><tr><td><code class="literal">22012</code></td><td><code class="symbol">division_by_zero</code></td></tr><tr><td><code class="literal">22005</code></td><td><code class="symbol">error_in_assignment</code></td></tr><tr><td><code class="literal">2200B</code></td><td><code class="symbol">escape_character_conflict</code></td></tr><tr><td><code class="literal">22022</code></td><td><code class="symbol">indicator_overflow</code></td></tr><tr><td><code class="literal">22015</code></td><td><code class="symbol">interval_field_overflow</code></td></tr><tr><td><code class="literal">2201E</code></td><td><code class="symbol">invalid_argument_for_logarithm</code></td></tr><tr><td><code class="literal">22014</code></td><td><code class="symbol">invalid_argument_for_ntile_function</code></td></tr><tr><td><code class="literal">22016</code></td><td><code class="symbol">invalid_argument_for_nth_value_function</code></td></tr><tr><td><code class="literal">2201F</code></td><td><code class="symbol">invalid_argument_for_power_function</code></td></tr><tr><td><code class="literal">2201G</code></td><td><code class="symbol">invalid_argument_for_width_bucket_function</code></td></tr><tr><td><code class="literal">22018</code></td><td><code class="symbol">invalid_character_value_for_cast</code></td></tr><tr><td><code class="literal">22007</code></td><td><code class="symbol">invalid_datetime_format</code></td></tr><tr><td><code class="literal">22019</code></td><td><code class="symbol">invalid_escape_character</code></td></tr><tr><td><code class="literal">2200D</code></td><td><code class="symbol">invalid_escape_octet</code></td></tr><tr><td><code class="literal">22025</code></td><td><code class="symbol">invalid_escape_sequence</code></td></tr><tr><td><code class="literal">22P06</code></td><td><code class="symbol">nonstandard_use_of_escape_character</code></td></tr><tr><td><code class="literal">22010</code></td><td><code class="symbol">invalid_indicator_parameter_value</code></td></tr><tr><td><code class="literal">22023</code></td><td><code class="symbol">invalid_parameter_value</code></td></tr><tr><td><code class="literal">22013</code></td><td><code class="symbol">invalid_preceding_or_following_size</code></td></tr><tr><td><code class="literal">2201B</code></td><td><code class="symbol">invalid_regular_expression</code></td></tr><tr><td><code class="literal">2201W</code></td><td><code class="symbol">invalid_row_count_in_limit_clause</code></td></tr><tr><td><code class="literal">2201X</code></td><td><code class="symbol">invalid_row_count_in_result_offset_clause</code></td></tr><tr><td><code class="literal">2202H</code></td><td><code class="symbol">invalid_tablesample_argument</code></td></tr><tr><td><code class="literal">2202G</code></td><td><code class="symbol">invalid_tablesample_repeat</code></td></tr><tr><td><code class="literal">22009</code></td><td><code class="symbol">invalid_time_zone_displacement_value</code></td></tr><tr><td><code class="literal">2200C</code></td><td><code class="symbol">invalid_use_of_escape_character</code></td></tr><tr><td><code class="literal">2200G</code></td><td><code class="symbol">most_specific_type_mismatch</code></td></tr><tr><td><code class="literal">22004</code></td><td><code class="symbol">null_value_not_allowed</code></td></tr><tr><td><code class="literal">22002</code></td><td><code class="symbol">null_value_no_indicator_parameter</code></td></tr><tr><td><code class="literal">22003</code></td><td><code class="symbol">numeric_value_out_of_range</code></td></tr><tr><td><code class="literal">2200H</code></td><td><code class="symbol">sequence_generator_limit_exceeded</code></td></tr><tr><td><code class="literal">22026</code></td><td><code class="symbol">string_data_length_mismatch</code></td></tr><tr><td><code class="literal">22001</code></td><td><code class="symbol">string_data_right_truncation</code></td></tr><tr><td><code class="literal">22011</code></td><td><code class="symbol">substring_error</code></td></tr><tr><td><code class="literal">22027</code></td><td><code class="symbol">trim_error</code></td></tr><tr><td><code class="literal">22024</code></td><td><code class="symbol">unterminated_c_string</code></td></tr><tr><td><code class="literal">2200F</code></td><td><code class="symbol">zero_length_character_string</code></td></tr><tr><td><code class="literal">22P01</code></td><td><code class="symbol">floating_point_exception</code></td></tr><tr><td><code class="literal">22P02</code></td><td><code class="symbol">invalid_text_representation</code></td></tr><tr><td><code class="literal">22P03</code></td><td><code class="symbol">invalid_binary_representation</code></td></tr><tr><td><code class="literal">22P04</code></td><td><code class="symbol">bad_copy_file_format</code></td></tr><tr><td><code class="literal">22P05</code></td><td><code class="symbol">untranslatable_character</code></td></tr><tr><td><code class="literal">2200L</code></td><td><code class="symbol">not_an_xml_document</code></td></tr><tr><td><code class="literal">2200M</code></td><td><code class="symbol">invalid_xml_document</code></td></tr><tr><td><code class="literal">2200N</code></td><td><code class="symbol">invalid_xml_content</code></td></tr><tr><td><code class="literal">2200S</code></td><td><code class="symbol">invalid_xml_comment</code></td></tr><tr><td><code class="literal">2200T</code></td><td><code class="symbol">invalid_xml_processing_instruction</code></td></tr><tr><td><code class="literal">22030</code></td><td><code class="symbol">duplicate_json_object_key_value</code></td></tr><tr><td><code class="literal">22031</code></td><td><code class="symbol">invalid_argument_for_sql_json_datetime_function</code></td></tr><tr><td><code class="literal">22032</code></td><td><code class="symbol">invalid_json_text</code></td></tr><tr><td><code class="literal">22033</code></td><td><code class="symbol">invalid_sql_json_subscript</code></td></tr><tr><td><code class="literal">22034</code></td><td><code class="symbol">more_than_one_sql_json_item</code></td></tr><tr><td><code class="literal">22035</code></td><td><code class="symbol">no_sql_json_item</code></td></tr><tr><td><code class="literal">22036</code></td><td><code class="symbol">non_numeric_sql_json_item</code></td></tr><tr><td><code class="literal">22037</code></td><td><code class="symbol">non_unique_keys_in_a_json_object</code></td></tr><tr><td><code class="literal">22038</code></td><td><code class="symbol">singleton_sql_json_item_required</code></td></tr><tr><td><code class="literal">22039</code></td><td><code class="symbol">sql_json_array_not_found</code></td></tr><tr><td><code class="literal">2203A</code></td><td><code class="symbol">sql_json_member_not_found</code></td></tr><tr><td><code class="literal">2203B</code></td><td><code class="symbol">sql_json_number_not_found</code></td></tr><tr><td><code class="literal">2203C</code></td><td><code class="symbol">sql_json_object_not_found</code></td></tr><tr><td><code class="literal">2203D</code></td><td><code class="symbol">too_many_json_array_elements</code></td></tr><tr><td><code class="literal">2203E</code></td><td><code class="symbol">too_many_json_object_members</code></td></tr><tr><td><code class="literal">2203F</code></td><td><code class="symbol">sql_json_scalar_required</code></td></tr><tr><td><code class="literal">2203G</code></td><td><code class="symbol">sql_json_item_cannot_be_cast_to_target_type</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 23 — Integrity Constraint Violation</strong></span></td></tr><tr><td><code class="literal">23000</code></td><td><code class="symbol">integrity_constraint_violation</code></td></tr><tr><td><code class="literal">23001</code></td><td><code class="symbol">restrict_violation</code></td></tr><tr><td><code class="literal">23502</code></td><td><code class="symbol">not_null_violation</code></td></tr><tr><td><code class="literal">23503</code></td><td><code class="symbol">foreign_key_violation</code></td></tr><tr><td><code class="literal">23505</code></td><td><code class="symbol">unique_violation</code></td></tr><tr><td><code class="literal">23514</code></td><td><code class="symbol">check_violation</code></td></tr><tr><td><code class="literal">23P01</code></td><td><code class="symbol">exclusion_violation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 24 — Invalid Cursor State</strong></span></td></tr><tr><td><code class="literal">24000</code></td><td><code class="symbol">invalid_cursor_state</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 25 — Invalid Transaction State</strong></span></td></tr><tr><td><code class="literal">25000</code></td><td><code class="symbol">invalid_transaction_state</code></td></tr><tr><td><code class="literal">25001</code></td><td><code class="symbol">active_sql_transaction</code></td></tr><tr><td><code class="literal">25002</code></td><td><code class="symbol">branch_transaction_already_active</code></td></tr><tr><td><code class="literal">25008</code></td><td><code class="symbol">held_cursor_requires_same_isolation_level</code></td></tr><tr><td><code class="literal">25003</code></td><td><code class="symbol">inappropriate_access_mode_for_branch_transaction</code></td></tr><tr><td><code class="literal">25004</code></td><td><code class="symbol">inappropriate_isolation_level_for_branch_transaction</code></td></tr><tr><td><code class="literal">25005</code></td><td><code class="symbol">no_active_sql_transaction_for_branch_transaction</code></td></tr><tr><td><code class="literal">25006</code></td><td><code class="symbol">read_only_sql_transaction</code></td></tr><tr><td><code class="literal">25007</code></td><td><code class="symbol">schema_and_data_statement_mixing_not_supported</code></td></tr><tr><td><code class="literal">25P01</code></td><td><code class="symbol">no_active_sql_transaction</code></td></tr><tr><td><code class="literal">25P02</code></td><td><code class="symbol">in_failed_sql_transaction</code></td></tr><tr><td><code class="literal">25P03</code></td><td><code class="symbol">idle_in_transaction_session_timeout</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 26 — Invalid SQL Statement Name</strong></span></td></tr><tr><td><code class="literal">26000</code></td><td><code class="symbol">invalid_sql_statement_name</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 27 — Triggered Data Change Violation</strong></span></td></tr><tr><td><code class="literal">27000</code></td><td><code class="symbol">triggered_data_change_violation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 28 — Invalid Authorization Specification</strong></span></td></tr><tr><td><code class="literal">28000</code></td><td><code class="symbol">invalid_authorization_specification</code></td></tr><tr><td><code class="literal">28P01</code></td><td><code class="symbol">invalid_password</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 2B — Dependent Privilege Descriptors Still Exist</strong></span></td></tr><tr><td><code class="literal">2B000</code></td><td><code class="symbol">dependent_privilege_descriptors_still_exist</code></td></tr><tr><td><code class="literal">2BP01</code></td><td><code class="symbol">dependent_objects_still_exist</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 2D — Invalid Transaction Termination</strong></span></td></tr><tr><td><code class="literal">2D000</code></td><td><code class="symbol">invalid_transaction_termination</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 2F — SQL Routine Exception</strong></span></td></tr><tr><td><code class="literal">2F000</code></td><td><code class="symbol">sql_routine_exception</code></td></tr><tr><td><code class="literal">2F005</code></td><td><code class="symbol">function_executed_no_return_statement</code></td></tr><tr><td><code class="literal">2F002</code></td><td><code class="symbol">modifying_sql_data_not_permitted</code></td></tr><tr><td><code class="literal">2F003</code></td><td><code class="symbol">prohibited_sql_statement_attempted</code></td></tr><tr><td><code class="literal">2F004</code></td><td><code class="symbol">reading_sql_data_not_permitted</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 34 — Invalid Cursor Name</strong></span></td></tr><tr><td><code class="literal">34000</code></td><td><code class="symbol">invalid_cursor_name</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 38 — External Routine Exception</strong></span></td></tr><tr><td><code class="literal">38000</code></td><td><code class="symbol">external_routine_exception</code></td></tr><tr><td><code class="literal">38001</code></td><td><code class="symbol">containing_sql_not_permitted</code></td></tr><tr><td><code class="literal">38002</code></td><td><code class="symbol">modifying_sql_data_not_permitted</code></td></tr><tr><td><code class="literal">38003</code></td><td><code class="symbol">prohibited_sql_statement_attempted</code></td></tr><tr><td><code class="literal">38004</code></td><td><code class="symbol">reading_sql_data_not_permitted</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 39 — External Routine Invocation Exception</strong></span></td></tr><tr><td><code class="literal">39000</code></td><td><code class="symbol">external_routine_invocation_exception</code></td></tr><tr><td><code class="literal">39001</code></td><td><code class="symbol">invalid_sqlstate_returned</code></td></tr><tr><td><code class="literal">39004</code></td><td><code class="symbol">null_value_not_allowed</code></td></tr><tr><td><code class="literal">39P01</code></td><td><code class="symbol">trigger_protocol_violated</code></td></tr><tr><td><code class="literal">39P02</code></td><td><code class="symbol">srf_protocol_violated</code></td></tr><tr><td><code class="literal">39P03</code></td><td><code class="symbol">event_trigger_protocol_violated</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 3B — Savepoint Exception</strong></span></td></tr><tr><td><code class="literal">3B000</code></td><td><code class="symbol">savepoint_exception</code></td></tr><tr><td><code class="literal">3B001</code></td><td><code class="symbol">invalid_savepoint_specification</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 3D — Invalid Catalog Name</strong></span></td></tr><tr><td><code class="literal">3D000</code></td><td><code class="symbol">invalid_catalog_name</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 3F — Invalid Schema Name</strong></span></td></tr><tr><td><code class="literal">3F000</code></td><td><code class="symbol">invalid_schema_name</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 40 — Transaction Rollback</strong></span></td></tr><tr><td><code class="literal">40000</code></td><td><code class="symbol">transaction_rollback</code></td></tr><tr><td><code class="literal">40002</code></td><td><code class="symbol">transaction_integrity_constraint_violation</code></td></tr><tr><td><code class="literal">40001</code></td><td><code class="symbol">serialization_failure</code></td></tr><tr><td><code class="literal">40003</code></td><td><code class="symbol">statement_completion_unknown</code></td></tr><tr><td><code class="literal">40P01</code></td><td><code class="symbol">deadlock_detected</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 42 — Syntax Error or Access Rule Violation</strong></span></td></tr><tr><td><code class="literal">42000</code></td><td><code class="symbol">syntax_error_or_access_rule_violation</code></td></tr><tr><td><code class="literal">42601</code></td><td><code class="symbol">syntax_error</code></td></tr><tr><td><code class="literal">42501</code></td><td><code class="symbol">insufficient_privilege</code></td></tr><tr><td><code class="literal">42846</code></td><td><code class="symbol">cannot_coerce</code></td></tr><tr><td><code class="literal">42803</code></td><td><code class="symbol">grouping_error</code></td></tr><tr><td><code class="literal">42P20</code></td><td><code class="symbol">windowing_error</code></td></tr><tr><td><code class="literal">42P19</code></td><td><code class="symbol">invalid_recursion</code></td></tr><tr><td><code class="literal">42830</code></td><td><code class="symbol">invalid_foreign_key</code></td></tr><tr><td><code class="literal">42602</code></td><td><code class="symbol">invalid_name</code></td></tr><tr><td><code class="literal">42622</code></td><td><code class="symbol">name_too_long</code></td></tr><tr><td><code class="literal">42939</code></td><td><code class="symbol">reserved_name</code></td></tr><tr><td><code class="literal">42804</code></td><td><code class="symbol">datatype_mismatch</code></td></tr><tr><td><code class="literal">42P18</code></td><td><code class="symbol">indeterminate_datatype</code></td></tr><tr><td><code class="literal">42P21</code></td><td><code class="symbol">collation_mismatch</code></td></tr><tr><td><code class="literal">42P22</code></td><td><code class="symbol">indeterminate_collation</code></td></tr><tr><td><code class="literal">42809</code></td><td><code class="symbol">wrong_object_type</code></td></tr><tr><td><code class="literal">428C9</code></td><td><code class="symbol">generated_always</code></td></tr><tr><td><code class="literal">42703</code></td><td><code class="symbol">undefined_column</code></td></tr><tr><td><code class="literal">42883</code></td><td><code class="symbol">undefined_function</code></td></tr><tr><td><code class="literal">42P01</code></td><td><code class="symbol">undefined_table</code></td></tr><tr><td><code class="literal">42P02</code></td><td><code class="symbol">undefined_parameter</code></td></tr><tr><td><code class="literal">42704</code></td><td><code class="symbol">undefined_object</code></td></tr><tr><td><code class="literal">42701</code></td><td><code class="symbol">duplicate_column</code></td></tr><tr><td><code class="literal">42P03</code></td><td><code class="symbol">duplicate_cursor</code></td></tr><tr><td><code class="literal">42P04</code></td><td><code class="symbol">duplicate_database</code></td></tr><tr><td><code class="literal">42723</code></td><td><code class="symbol">duplicate_function</code></td></tr><tr><td><code class="literal">42P05</code></td><td><code class="symbol">duplicate_prepared_statement</code></td></tr><tr><td><code class="literal">42P06</code></td><td><code class="symbol">duplicate_schema</code></td></tr><tr><td><code class="literal">42P07</code></td><td><code class="symbol">duplicate_table</code></td></tr><tr><td><code class="literal">42712</code></td><td><code class="symbol">duplicate_alias</code></td></tr><tr><td><code class="literal">42710</code></td><td><code class="symbol">duplicate_object</code></td></tr><tr><td><code class="literal">42702</code></td><td><code class="symbol">ambiguous_column</code></td></tr><tr><td><code class="literal">42725</code></td><td><code class="symbol">ambiguous_function</code></td></tr><tr><td><code class="literal">42P08</code></td><td><code class="symbol">ambiguous_parameter</code></td></tr><tr><td><code class="literal">42P09</code></td><td><code class="symbol">ambiguous_alias</code></td></tr><tr><td><code class="literal">42P10</code></td><td><code class="symbol">invalid_column_reference</code></td></tr><tr><td><code class="literal">42611</code></td><td><code class="symbol">invalid_column_definition</code></td></tr><tr><td><code class="literal">42P11</code></td><td><code class="symbol">invalid_cursor_definition</code></td></tr><tr><td><code class="literal">42P12</code></td><td><code class="symbol">invalid_database_definition</code></td></tr><tr><td><code class="literal">42P13</code></td><td><code class="symbol">invalid_function_definition</code></td></tr><tr><td><code class="literal">42P14</code></td><td><code class="symbol">invalid_prepared_statement_definition</code></td></tr><tr><td><code class="literal">42P15</code></td><td><code class="symbol">invalid_schema_definition</code></td></tr><tr><td><code class="literal">42P16</code></td><td><code class="symbol">invalid_table_definition</code></td></tr><tr><td><code class="literal">42P17</code></td><td><code class="symbol">invalid_object_definition</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 44 — WITH CHECK OPTION Violation</strong></span></td></tr><tr><td><code class="literal">44000</code></td><td><code class="symbol">with_check_option_violation</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 53 — Insufficient Resources</strong></span></td></tr><tr><td><code class="literal">53000</code></td><td><code class="symbol">insufficient_resources</code></td></tr><tr><td><code class="literal">53100</code></td><td><code class="symbol">disk_full</code></td></tr><tr><td><code class="literal">53200</code></td><td><code class="symbol">out_of_memory</code></td></tr><tr><td><code class="literal">53300</code></td><td><code class="symbol">too_many_connections</code></td></tr><tr><td><code class="literal">53400</code></td><td><code class="symbol">configuration_limit_exceeded</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 54 — Program Limit Exceeded</strong></span></td></tr><tr><td><code class="literal">54000</code></td><td><code class="symbol">program_limit_exceeded</code></td></tr><tr><td><code class="literal">54001</code></td><td><code class="symbol">statement_too_complex</code></td></tr><tr><td><code class="literal">54011</code></td><td><code class="symbol">too_many_columns</code></td></tr><tr><td><code class="literal">54023</code></td><td><code class="symbol">too_many_arguments</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 55 — Object Not In Prerequisite State</strong></span></td></tr><tr><td><code class="literal">55000</code></td><td><code class="symbol">object_not_in_prerequisite_state</code></td></tr><tr><td><code class="literal">55006</code></td><td><code class="symbol">object_in_use</code></td></tr><tr><td><code class="literal">55P02</code></td><td><code class="symbol">cant_change_runtime_param</code></td></tr><tr><td><code class="literal">55P03</code></td><td><code class="symbol">lock_not_available</code></td></tr><tr><td><code class="literal">55P04</code></td><td><code class="symbol">unsafe_new_enum_value_usage</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 57 — Operator Intervention</strong></span></td></tr><tr><td><code class="literal">57000</code></td><td><code class="symbol">operator_intervention</code></td></tr><tr><td><code class="literal">57014</code></td><td><code class="symbol">query_canceled</code></td></tr><tr><td><code class="literal">57P01</code></td><td><code class="symbol">admin_shutdown</code></td></tr><tr><td><code class="literal">57P02</code></td><td><code class="symbol">crash_shutdown</code></td></tr><tr><td><code class="literal">57P03</code></td><td><code class="symbol">cannot_connect_now</code></td></tr><tr><td><code class="literal">57P04</code></td><td><code class="symbol">database_dropped</code></td></tr><tr><td><code class="literal">57P05</code></td><td><code class="symbol">idle_session_timeout</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 58 — System Error (errors external to <span class="productname">PostgreSQL</span> itself)</strong></span></td></tr><tr><td><code class="literal">58000</code></td><td><code class="symbol">system_error</code></td></tr><tr><td><code class="literal">58030</code></td><td><code class="symbol">io_error</code></td></tr><tr><td><code class="literal">58P01</code></td><td><code class="symbol">undefined_file</code></td></tr><tr><td><code class="literal">58P02</code></td><td><code class="symbol">duplicate_file</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class 72 — Snapshot Failure</strong></span></td></tr><tr><td><code class="literal">72000</code></td><td><code class="symbol">snapshot_too_old</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class F0 — Configuration File Error</strong></span></td></tr><tr><td><code class="literal">F0000</code></td><td><code class="symbol">config_file_error</code></td></tr><tr><td><code class="literal">F0001</code></td><td><code class="symbol">lock_file_exists</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class HV — Foreign Data Wrapper Error (SQL/MED)</strong></span></td></tr><tr><td><code class="literal">HV000</code></td><td><code class="symbol">fdw_error</code></td></tr><tr><td><code class="literal">HV005</code></td><td><code class="symbol">fdw_column_name_not_found</code></td></tr><tr><td><code class="literal">HV002</code></td><td><code class="symbol">fdw_dynamic_parameter_value_needed</code></td></tr><tr><td><code class="literal">HV010</code></td><td><code class="symbol">fdw_function_sequence_error</code></td></tr><tr><td><code class="literal">HV021</code></td><td><code class="symbol">fdw_inconsistent_descriptor_information</code></td></tr><tr><td><code class="literal">HV024</code></td><td><code class="symbol">fdw_invalid_attribute_value</code></td></tr><tr><td><code class="literal">HV007</code></td><td><code class="symbol">fdw_invalid_column_name</code></td></tr><tr><td><code class="literal">HV008</code></td><td><code class="symbol">fdw_invalid_column_number</code></td></tr><tr><td><code class="literal">HV004</code></td><td><code class="symbol">fdw_invalid_data_type</code></td></tr><tr><td><code class="literal">HV006</code></td><td><code class="symbol">fdw_invalid_data_type_descriptors</code></td></tr><tr><td><code class="literal">HV091</code></td><td><code class="symbol">fdw_invalid_descriptor_field_identifier</code></td></tr><tr><td><code class="literal">HV00B</code></td><td><code class="symbol">fdw_invalid_handle</code></td></tr><tr><td><code class="literal">HV00C</code></td><td><code class="symbol">fdw_invalid_option_index</code></td></tr><tr><td><code class="literal">HV00D</code></td><td><code class="symbol">fdw_invalid_option_name</code></td></tr><tr><td><code class="literal">HV090</code></td><td><code class="symbol">fdw_invalid_string_length_or_buffer_length</code></td></tr><tr><td><code class="literal">HV00A</code></td><td><code class="symbol">fdw_invalid_string_format</code></td></tr><tr><td><code class="literal">HV009</code></td><td><code class="symbol">fdw_invalid_use_of_null_pointer</code></td></tr><tr><td><code class="literal">HV014</code></td><td><code class="symbol">fdw_too_many_handles</code></td></tr><tr><td><code class="literal">HV001</code></td><td><code class="symbol">fdw_out_of_memory</code></td></tr><tr><td><code class="literal">HV00P</code></td><td><code class="symbol">fdw_no_schemas</code></td></tr><tr><td><code class="literal">HV00J</code></td><td><code class="symbol">fdw_option_name_not_found</code></td></tr><tr><td><code class="literal">HV00K</code></td><td><code class="symbol">fdw_reply_handle</code></td></tr><tr><td><code class="literal">HV00Q</code></td><td><code class="symbol">fdw_schema_not_found</code></td></tr><tr><td><code class="literal">HV00R</code></td><td><code class="symbol">fdw_table_not_found</code></td></tr><tr><td><code class="literal">HV00L</code></td><td><code class="symbol">fdw_unable_to_create_execution</code></td></tr><tr><td><code class="literal">HV00M</code></td><td><code class="symbol">fdw_unable_to_create_reply</code></td></tr><tr><td><code class="literal">HV00N</code></td><td><code class="symbol">fdw_unable_to_establish_connection</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class P0 — PL/pgSQL Error</strong></span></td></tr><tr><td><code class="literal">P0000</code></td><td><code class="symbol">plpgsql_error</code></td></tr><tr><td><code class="literal">P0001</code></td><td><code class="symbol">raise_exception</code></td></tr><tr><td><code class="literal">P0002</code></td><td><code class="symbol">no_data_found</code></td></tr><tr><td><code class="literal">P0003</code></td><td><code class="symbol">too_many_rows</code></td></tr><tr><td><code class="literal">P0004</code></td><td><code class="symbol">assert_failure</code></td></tr><tr><td colspan="2"><span class="bold"><strong>Class XX — Internal Error</strong></span></td></tr><tr><td><code class="literal">XX000</code></td><td><code class="symbol">internal_error</code></td></tr><tr><td><code class="literal">XX001</code></td><td><code class="symbol">data_corrupted</code></td></tr><tr><td><code class="literal">XX002</code></td><td><code class="symbol">index_corrupted</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendixes.html" title="Part VIII. Appendixes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VIII. Appendixes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix B. Date/Time Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/error-message-reporting.html b/doc/src/sgml/html/error-message-reporting.html
new file mode 100644
index 0000000..b14244f
--- /dev/null
+++ b/doc/src/sgml/html/error-message-reporting.html
@@ -0,0 +1,250 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.2. Reporting Errors Within the Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="source-format.html" title="56.1. Formatting" /><link rel="next" href="error-style-guide.html" title="56.3. Error Message Style Guide" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.2. Reporting Errors Within the Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source-format.html" title="56.1. Formatting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.3. Error Message Style Guide">Next</a></td></tr></table><hr /></div><div class="sect1" id="ERROR-MESSAGE-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.2. Reporting Errors Within the Server</h2></div></div></div><a id="id-1.10.7.3.2" class="indexterm"></a><a id="id-1.10.7.3.3" class="indexterm"></a><p>
+ Error, warning, and log messages generated within the server code
+ should be created using <code class="function">ereport</code>, or its older cousin
+ <code class="function">elog</code>. The use of this function is complex enough to
+ require some explanation.
+ </p><p>
+ There are two required elements for every message: a severity level
+ (ranging from <code class="literal">DEBUG</code> to <code class="literal">PANIC</code>) and a primary
+ message text. In addition there are optional elements, the most
+ common of which is an error identifier code that follows the SQL spec's
+ SQLSTATE conventions.
+ <code class="function">ereport</code> itself is just a shell macro that exists
+ mainly for the syntactic convenience of making message generation
+ look like a single function call in the C source code. The only parameter
+ accepted directly by <code class="function">ereport</code> is the severity level.
+ The primary message text and any optional message elements are
+ generated by calling auxiliary functions, such as <code class="function">errmsg</code>,
+ within the <code class="function">ereport</code> call.
+ </p><p>
+ A typical call to <code class="function">ereport</code> might look like this:
+</p><pre class="programlisting">
+ereport(ERROR,
+ errcode(ERRCODE_DIVISION_BY_ZERO),
+ errmsg("division by zero"));
+</pre><p>
+ This specifies error severity level <code class="literal">ERROR</code> (a run-of-the-mill
+ error). The <code class="function">errcode</code> call specifies the SQLSTATE error code
+ using a macro defined in <code class="filename">src/include/utils/errcodes.h</code>. The
+ <code class="function">errmsg</code> call provides the primary message text.
+ </p><p>
+ You will also frequently see this older style, with an extra set of
+ parentheses surrounding the auxiliary function calls:
+</p><pre class="programlisting">
+ereport(ERROR,
+ (errcode(ERRCODE_DIVISION_BY_ZERO),
+ errmsg("division by zero")));
+</pre><p>
+ The extra parentheses were required
+ before <span class="productname">PostgreSQL</span> version 12, but are now
+ optional.
+ </p><p>
+ Here is a more complex example:
+</p><pre class="programlisting">
+ereport(ERROR,
+ errcode(ERRCODE_AMBIGUOUS_FUNCTION),
+ errmsg("function %s is not unique",
+ func_signature_string(funcname, nargs,
+ NIL, actual_arg_types)),
+ errhint("Unable to choose a best candidate function. "
+ "You might need to add explicit typecasts."));
+</pre><p>
+ This illustrates the use of format codes to embed run-time values into
+ a message text. Also, an optional <span class="quote">“<span class="quote">hint</span>”</span> message is provided.
+ The auxiliary function calls can be written in any order, but
+ conventionally <code class="function">errcode</code>
+ and <code class="function">errmsg</code> appear first.
+ </p><p>
+ If the severity level is <code class="literal">ERROR</code> or higher,
+ <code class="function">ereport</code> aborts execution of the current query
+ and does not return to the caller. If the severity level is
+ lower than <code class="literal">ERROR</code>, <code class="function">ereport</code> returns normally.
+ </p><p>
+ The available auxiliary routines for <code class="function">ereport</code> are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="function">errcode(sqlerrcode)</code> specifies the SQLSTATE error identifier
+ code for the condition. If this routine is not called, the error
+ identifier defaults to
+ <code class="literal">ERRCODE_INTERNAL_ERROR</code> when the error severity level is
+ <code class="literal">ERROR</code> or higher, <code class="literal">ERRCODE_WARNING</code> when the
+ error level is <code class="literal">WARNING</code>, otherwise (for <code class="literal">NOTICE</code>
+ and below) <code class="literal">ERRCODE_SUCCESSFUL_COMPLETION</code>.
+ While these defaults are often convenient, always think whether they
+ are appropriate before omitting the <code class="function">errcode()</code> call.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg(const char *msg, ...)</code> specifies the primary error
+ message text, and possibly run-time values to insert into it. Insertions
+ are specified by <code class="function">sprintf</code>-style format codes. In addition to
+ the standard format codes accepted by <code class="function">sprintf</code>, the format
+ code <code class="literal">%m</code> can be used to insert the error message returned
+ by <code class="function">strerror</code> for the current value of <code class="literal">errno</code>.
+ <a href="#ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><sup class="footnote" id="id-1.10.7.3.10.2.2.1.7">[16]</sup></a>
+ <code class="literal">%m</code> does not require any
+ corresponding entry in the parameter list for <code class="function">errmsg</code>.
+ Note that the message string will be run through <code class="function">gettext</code>
+ for possible localization before format codes are processed.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg_internal(const char *msg, ...)</code> is the same as
+ <code class="function">errmsg</code>, except that the message string will not be
+ translated nor included in the internationalization message dictionary.
+ This should be used for <span class="quote">“<span class="quote">cannot happen</span>”</span> cases that are probably
+ not worth expending translation effort on.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errmsg</code>, but with
+ support for various plural forms of the message.
+ <em class="replaceable"><code>fmt_singular</code></em> is the English singular format,
+ <em class="replaceable"><code>fmt_plural</code></em> is the English plural format,
+ <em class="replaceable"><code>n</code></em> is the integer value that determines which plural
+ form is needed, and the remaining arguments are formatted according
+ to the selected format string. For more information see
+ <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail(const char *msg, ...)</code> supplies an optional
+ <span class="quote">“<span class="quote">detail</span>”</span> message; this is to be used when there is additional
+ information that seems inappropriate to put in the primary message.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_internal(const char *msg, ...)</code> is the same
+ as <code class="function">errdetail</code>, except that the message string will not be
+ translated nor included in the internationalization message dictionary.
+ This should be used for detail messages that are not worth expending
+ translation effort on, for instance because they are too technical to be
+ useful to most users.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errdetail</code>, but with
+ support for various plural forms of the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_log(const char *msg, ...)</code> is the same as
+ <code class="function">errdetail</code> except that this string goes only to the server
+ log, never to the client. If both <code class="function">errdetail</code> (or one of
+ its equivalents above) and
+ <code class="function">errdetail_log</code> are used then one string goes to the client
+ and the other to the log. This is useful for error details that are
+ too security-sensitive or too bulky to include in the report
+ sent to the client.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_log_plural(const char *fmt_singular, const char
+ *fmt_plural, unsigned long n, ...)</code> is like
+ <code class="function">errdetail_log</code>, but with support for various plural forms of
+ the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhint(const char *msg, ...)</code> supplies an optional
+ <span class="quote">“<span class="quote">hint</span>”</span> message; this is to be used when offering suggestions
+ about how to fix the problem, as opposed to factual details about
+ what went wrong.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhint_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errhint</code>, but with
+ support for various plural forms of the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcontext(const char *msg, ...)</code> is not normally called
+ directly from an <code class="function">ereport</code> message site; rather it is used
+ in <code class="literal">error_context_stack</code> callback functions to provide
+ information about the context in which an error occurred, such as the
+ current location in a PL function.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>. Unlike the other auxiliary functions, this can
+ be called more than once per <code class="function">ereport</code> call; the successive
+ strings thus supplied are concatenated with separating newlines.
+ </p></li><li class="listitem"><p>
+ <code class="function">errposition(int cursorpos)</code> specifies the textual location
+ of an error within a query string. Currently it is only useful for
+ errors detected in the lexical and syntactic analysis phases of
+ query processing.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtable(Relation rel)</code> specifies a relation whose
+ name and schema name should be included as auxiliary fields in the error
+ report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtablecol(Relation rel, int attnum)</code> specifies
+ a column whose name, table name, and schema name should be included as
+ auxiliary fields in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtableconstraint(Relation rel, const char *conname)</code>
+ specifies a table constraint whose name, table name, and schema name
+ should be included as auxiliary fields in the error report. Indexes
+ should be considered to be constraints for this purpose, whether or
+ not they have an associated <code class="structname">pg_constraint</code> entry. Be
+ careful to pass the underlying heap relation, not the index itself, as
+ <code class="literal">rel</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdatatype(Oid datatypeOid)</code> specifies a data
+ type whose name and schema name should be included as auxiliary fields
+ in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdomainconstraint(Oid datatypeOid, const char *conname)</code>
+ specifies a domain constraint whose name, domain name, and schema name
+ should be included as auxiliary fields in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcode_for_file_access()</code> is a convenience function that
+ selects an appropriate SQLSTATE error identifier for a failure in a
+ file-access-related system call. It uses the saved
+ <code class="literal">errno</code> to determine which error code to generate.
+ Usually this should be used in combination with <code class="literal">%m</code> in the
+ primary error message text.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcode_for_socket_access()</code> is a convenience function that
+ selects an appropriate SQLSTATE error identifier for a failure in a
+ socket-related system call.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhidestmt(bool hide_stmt)</code> can be called to specify
+ suppression of the <code class="literal">STATEMENT:</code> portion of a message in the
+ postmaster log. Generally this is appropriate if the message text
+ includes the current statement already.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhidecontext(bool hide_ctx)</code> can be called to
+ specify suppression of the <code class="literal">CONTEXT:</code> portion of a message in
+ the postmaster log. This should only be used for verbose debugging
+ messages where the repeated inclusion of context would bloat the log
+ too much.
+ </p></li></ul></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ At most one of the functions <code class="function">errtable</code>,
+ <code class="function">errtablecol</code>, <code class="function">errtableconstraint</code>,
+ <code class="function">errdatatype</code>, or <code class="function">errdomainconstraint</code> should
+ be used in an <code class="function">ereport</code> call. These functions exist to
+ allow applications to extract the name of a database object associated
+ with the error condition without having to examine the
+ potentially-localized error message text.
+ These functions should be used in error reports for which it's likely
+ that applications would wish to have automatic error handling. As of
+ <span class="productname">PostgreSQL</span> 9.3, complete coverage exists only for
+ errors in SQLSTATE class 23 (integrity constraint violation), but this
+ is likely to be expanded in future.
+ </p></div><p>
+ There is an older function <code class="function">elog</code> that is still heavily used.
+ An <code class="function">elog</code> call:
+</p><pre class="programlisting">
+elog(level, "format string", ...);
+</pre><p>
+ is exactly equivalent to:
+</p><pre class="programlisting">
+ereport(level, errmsg_internal("format string", ...));
+</pre><p>
+ Notice that the SQLSTATE error code is always defaulted, and the message
+ string is not subject to translation.
+ Therefore, <code class="function">elog</code> should be used only for internal errors and
+ low-level debug logging. Any message that is likely to be of interest to
+ ordinary users should go through <code class="function">ereport</code>. Nonetheless,
+ there are enough internal <span class="quote">“<span class="quote">cannot happen</span>”</span> error checks in the
+ system that <code class="function">elog</code> is still widely used; it is preferred for
+ those messages for its notational simplicity.
+ </p><p>
+ Advice about writing good error messages can be found in
+ <a class="xref" href="error-style-guide.html" title="56.3. Error Message Style Guide">Section 56.3</a>.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><p><a href="#id-1.10.7.3.10.2.2.1.7" class="para"><sup class="para">[16] </sup></a>
+ That is, the value that was current when the <code class="function">ereport</code> call
+ was reached; changes of <code class="literal">errno</code> within the auxiliary reporting
+ routines will not affect it. That would not be true if you were to
+ write <code class="literal">strerror(errno)</code> explicitly in <code class="function">errmsg</code>'s
+ parameter list; accordingly, do not do so.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source-format.html" title="56.1. Formatting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.3. Error Message Style Guide">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.1. Formatting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.3. Error Message Style Guide</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/error-style-guide.html b/doc/src/sgml/html/error-style-guide.html
new file mode 100644
index 0000000..2d6861b
--- /dev/null
+++ b/doc/src/sgml/html/error-style-guide.html
@@ -0,0 +1,250 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.3. Error Message Style Guide</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server" /><link rel="next" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.3. Error Message Style Guide</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Next</a></td></tr></table><hr /></div><div class="sect1" id="ERROR-STYLE-GUIDE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.3. Error Message Style Guide</h2></div></div></div><p>
+ This style guide is offered in the hope of maintaining a consistent,
+ user-friendly style throughout all the messages generated by
+ <span class="productname">PostgreSQL</span>.
+ </p><div class="simplesect" id="id-1.10.7.4.3"><div class="titlepage"><div><div><h3 class="title">What Goes Where</h3></div></div></div><p>
+ The primary message should be short, factual, and avoid reference to
+ implementation details such as specific function names.
+ <span class="quote">“<span class="quote">Short</span>”</span> means <span class="quote">“<span class="quote">should fit on one line under normal
+ conditions</span>”</span>. Use a detail message if needed to keep the primary
+ message short, or if you feel a need to mention implementation details
+ such as the particular system call that failed. Both primary and detail
+ messages should be factual. Use a hint message for suggestions about what
+ to do to fix the problem, especially if the suggestion might not always be
+ applicable.
+ </p><p>
+ For example, instead of:
+</p><pre class="programlisting">
+IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
+(plus a long addendum that is basically a hint)
+</pre><p>
+ write:
+</p><pre class="programlisting">
+Primary: could not create shared memory segment: %m
+Detail: Failed syscall was shmget(key=%d, size=%u, 0%o).
+Hint: the addendum
+</pre><p>
+ </p><p>
+ Rationale: keeping the primary message short helps keep it to the point,
+ and lets clients lay out screen space on the assumption that one line is
+ enough for error messages. Detail and hint messages can be relegated to a
+ verbose mode, or perhaps a pop-up error-details window. Also, details and
+ hints would normally be suppressed from the server log to save
+ space. Reference to implementation details is best avoided since users
+ aren't expected to know the details.
+ </p></div><div class="simplesect" id="id-1.10.7.4.4"><div class="titlepage"><div><div><h3 class="title">Formatting</h3></div></div></div><p>
+ Don't put any specific assumptions about formatting into the message
+ texts. Expect clients and the server log to wrap lines to fit their own
+ needs. In long messages, newline characters (\n) can be used to indicate
+ suggested paragraph breaks. Don't end a message with a newline. Don't
+ use tabs or other formatting characters. (In error context displays,
+ newlines are automatically added to separate levels of context such as
+ function calls.)
+ </p><p>
+ Rationale: Messages are not necessarily displayed on terminal-type
+ displays. In GUI displays or browsers these formatting instructions are
+ at best ignored.
+ </p></div><div class="simplesect" id="id-1.10.7.4.5"><div class="titlepage"><div><div><h3 class="title">Quotation Marks</h3></div></div></div><p>
+ English text should use double quotes when quoting is appropriate.
+ Text in other languages should consistently use one kind of quotes that is
+ consistent with publishing customs and computer output of other programs.
+ </p><p>
+ Rationale: The choice of double quotes over single quotes is somewhat
+ arbitrary, but tends to be the preferred use. Some have suggested
+ choosing the kind of quotes depending on the type of object according to
+ SQL conventions (namely, strings single quoted, identifiers double
+ quoted). But this is a language-internal technical issue that many users
+ aren't even familiar with, it won't scale to other kinds of quoted terms,
+ it doesn't translate to other languages, and it's pretty pointless, too.
+ </p></div><div class="simplesect" id="id-1.10.7.4.6"><div class="titlepage"><div><div><h3 class="title">Use of Quotes</h3></div></div></div><p>
+ Always use quotes to delimit file names, user-supplied identifiers, and
+ other variables that might contain words. Do not use them to mark up
+ variables that will not contain words (for example, operator names).
+ </p><p>
+ There are functions in the backend that will double-quote their own output
+ as needed (for example, <code class="function">format_type_be()</code>). Do not put
+ additional quotes around the output of such functions.
+ </p><p>
+ Rationale: Objects can have names that create ambiguity when embedded in a
+ message. Be consistent about denoting where a plugged-in name starts and
+ ends. But don't clutter messages with unnecessary or duplicate quote
+ marks.
+ </p></div><div class="simplesect" id="id-1.10.7.4.7"><div class="titlepage"><div><div><h3 class="title">Grammar and Punctuation</h3></div></div></div><p>
+ The rules are different for primary error messages and for detail/hint
+ messages:
+ </p><p>
+ Primary error messages: Do not capitalize the first letter. Do not end a
+ message with a period. Do not even think about ending a message with an
+ exclamation point.
+ </p><p>
+ Detail and hint messages: Use complete sentences, and end each with
+ a period. Capitalize the first word of sentences. Put two spaces after
+ the period if another sentence follows (for English text; might be
+ inappropriate in other languages).
+ </p><p>
+ Error context strings: Do not capitalize the first letter and do
+ not end the string with a period. Context strings should normally
+ not be complete sentences.
+ </p><p>
+ Rationale: Avoiding punctuation makes it easier for client applications to
+ embed the message into a variety of grammatical contexts. Often, primary
+ messages are not grammatically complete sentences anyway. (And if they're
+ long enough to be more than one sentence, they should be split into
+ primary and detail parts.) However, detail and hint messages are longer
+ and might need to include multiple sentences. For consistency, they should
+ follow complete-sentence style even when there's only one sentence.
+ </p></div><div class="simplesect" id="id-1.10.7.4.8"><div class="titlepage"><div><div><h3 class="title">Upper Case vs. Lower Case</h3></div></div></div><p>
+ Use lower case for message wording, including the first letter of a
+ primary error message. Use upper case for SQL commands and key words if
+ they appear in the message.
+ </p><p>
+ Rationale: It's easier to make everything look more consistent this
+ way, since some messages are complete sentences and some not.
+ </p></div><div class="simplesect" id="id-1.10.7.4.9"><div class="titlepage"><div><div><h3 class="title">Avoid Passive Voice</h3></div></div></div><p>
+ Use the active voice. Use complete sentences when there is an acting
+ subject (<span class="quote">“<span class="quote">A could not do B</span>”</span>). Use telegram style without
+ subject if the subject would be the program itself; do not use
+ <span class="quote">“<span class="quote">I</span>”</span> for the program.
+ </p><p>
+ Rationale: The program is not human. Don't pretend otherwise.
+ </p></div><div class="simplesect" id="id-1.10.7.4.10"><div class="titlepage"><div><div><h3 class="title">Present vs. Past Tense</h3></div></div></div><p>
+ Use past tense if an attempt to do something failed, but could perhaps
+ succeed next time (perhaps after fixing some problem). Use present tense
+ if the failure is certainly permanent.
+ </p><p>
+ There is a nontrivial semantic difference between sentences of the form:
+</p><pre class="programlisting">
+could not open file "%s": %m
+</pre><p>
+and:
+</p><pre class="programlisting">
+cannot open file "%s"
+</pre><p>
+ The first one means that the attempt to open the file failed. The
+ message should give a reason, such as <span class="quote">“<span class="quote">disk full</span>”</span> or
+ <span class="quote">“<span class="quote">file doesn't exist</span>”</span>. The past tense is appropriate because
+ next time the disk might not be full anymore or the file in question might
+ exist.
+ </p><p>
+ The second form indicates that the functionality of opening the named file
+ does not exist at all in the program, or that it's conceptually
+ impossible. The present tense is appropriate because the condition will
+ persist indefinitely.
+ </p><p>
+ Rationale: Granted, the average user will not be able to draw great
+ conclusions merely from the tense of the message, but since the language
+ provides us with a grammar we should use it correctly.
+ </p></div><div class="simplesect" id="id-1.10.7.4.11"><div class="titlepage"><div><div><h3 class="title">Type of the Object</h3></div></div></div><p>
+ When citing the name of an object, state what kind of object it is.
+ </p><p>
+ Rationale: Otherwise no one will know what <span class="quote">“<span class="quote">foo.bar.baz</span>”</span>
+ refers to.
+ </p></div><div class="simplesect" id="id-1.10.7.4.12"><div class="titlepage"><div><div><h3 class="title">Brackets</h3></div></div></div><p>
+ Square brackets are only to be used (1) in command synopses to denote
+ optional arguments, or (2) to denote an array subscript.
+ </p><p>
+ Rationale: Anything else does not correspond to widely-known customary
+ usage and will confuse people.
+ </p></div><div class="simplesect" id="id-1.10.7.4.13"><div class="titlepage"><div><div><h3 class="title">Assembling Error Messages</h3></div></div></div><p>
+ When a message includes text that is generated elsewhere, embed it in
+ this style:
+</p><pre class="programlisting">
+could not open file %s: %m
+</pre><p>
+ </p><p>
+ Rationale: It would be difficult to account for all possible error codes
+ to paste this into a single smooth sentence, so some sort of punctuation
+ is needed. Putting the embedded text in parentheses has also been
+ suggested, but it's unnatural if the embedded text is likely to be the
+ most important part of the message, as is often the case.
+ </p></div><div class="simplesect" id="id-1.10.7.4.14"><div class="titlepage"><div><div><h3 class="title">Reasons for Errors</h3></div></div></div><p>
+ Messages should always state the reason why an error occurred.
+ For example:
+</p><pre class="programlisting">
+BAD: could not open file %s
+BETTER: could not open file %s (I/O failure)
+</pre><p>
+ If no reason is known you better fix the code.
+ </p></div><div class="simplesect" id="id-1.10.7.4.15"><div class="titlepage"><div><div><h3 class="title">Function Names</h3></div></div></div><p>
+ Don't include the name of the reporting routine in the error text. We have
+ other mechanisms for finding that out when needed, and for most users it's
+ not helpful information. If the error text doesn't make as much sense
+ without the function name, reword it.
+</p><pre class="programlisting">
+BAD: pg_strtoint32: error in "z": cannot parse "z"
+BETTER: invalid input syntax for type integer: "z"
+</pre><p>
+ </p><p>
+ Avoid mentioning called function names, either; instead say what the code
+ was trying to do:
+</p><pre class="programlisting">
+BAD: open() failed: %m
+BETTER: could not open file %s: %m
+</pre><p>
+ If it really seems necessary, mention the system call in the detail
+ message. (In some cases, providing the actual values passed to the
+ system call might be appropriate information for the detail message.)
+ </p><p>
+ Rationale: Users don't know what all those functions do.
+ </p></div><div class="simplesect" id="id-1.10.7.4.16"><div class="titlepage"><div><div><h3 class="title">Tricky Words to Avoid</h3></div></div></div><p><strong>Unable. </strong>
+ <span class="quote">“<span class="quote">Unable</span>”</span> is nearly the passive voice. Better use
+ <span class="quote">“<span class="quote">cannot</span>”</span> or <span class="quote">“<span class="quote">could not</span>”</span>, as appropriate.
+ </p><p><strong>Bad. </strong>
+ Error messages like <span class="quote">“<span class="quote">bad result</span>”</span> are really hard to interpret
+ intelligently. It's better to write why the result is <span class="quote">“<span class="quote">bad</span>”</span>,
+ e.g., <span class="quote">“<span class="quote">invalid format</span>”</span>.
+ </p><p><strong>Illegal. </strong>
+ <span class="quote">“<span class="quote">Illegal</span>”</span> stands for a violation of the law, the rest is
+ <span class="quote">“<span class="quote">invalid</span>”</span>. Better yet, say why it's invalid.
+ </p><p><strong>Unknown. </strong>
+ Try to avoid <span class="quote">“<span class="quote">unknown</span>”</span>. Consider <span class="quote">“<span class="quote">error: unknown
+ response</span>”</span>. If you don't know what the response is, how do you know
+ it's erroneous? <span class="quote">“<span class="quote">Unrecognized</span>”</span> is often a better choice.
+ Also, be sure to include the value being complained of.
+</p><pre class="programlisting">
+BAD: unknown node type
+BETTER: unrecognized node type: 42
+</pre><p>
+ </p><p><strong>Find vs. Exists. </strong>
+ If the program uses a nontrivial algorithm to locate a resource (e.g., a
+ path search) and that algorithm fails, it is fair to say that the program
+ couldn't <span class="quote">“<span class="quote">find</span>”</span> the resource. If, on the other hand, the
+ expected location of the resource is known but the program cannot access
+ it there then say that the resource doesn't <span class="quote">“<span class="quote">exist</span>”</span>. Using
+ <span class="quote">“<span class="quote">find</span>”</span> in this case sounds weak and confuses the issue.
+ </p><p><strong>May vs. Can vs. Might. </strong>
+ <span class="quote">“<span class="quote">May</span>”</span> suggests permission (e.g., "You may borrow my rake."),
+ and has little use in documentation or error messages.
+ <span class="quote">“<span class="quote">Can</span>”</span> suggests ability (e.g., "I can lift that log."),
+ and <span class="quote">“<span class="quote">might</span>”</span> suggests possibility (e.g., "It might rain
+ today."). Using the proper word clarifies meaning and assists
+ translation.
+ </p><p><strong>Contractions. </strong>
+ Avoid contractions, like <span class="quote">“<span class="quote">can't</span>”</span>; use
+ <span class="quote">“<span class="quote">cannot</span>”</span> instead.
+ </p><p><strong>Non-negative. </strong>
+ Avoid <span class="quote">“<span class="quote">non-negative</span>”</span> as it is ambiguous
+ about whether it accepts zero. It's better to use
+ <span class="quote">“<span class="quote">greater than zero</span>”</span> or
+ <span class="quote">“<span class="quote">greater than or equal to zero</span>”</span>.
+ </p></div><div class="simplesect" id="id-1.10.7.4.17"><div class="titlepage"><div><div><h3 class="title">Proper Spelling</h3></div></div></div><p>
+ Spell out words in full. For instance, avoid:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ spec
+ </p></li><li class="listitem"><p>
+ stats
+ </p></li><li class="listitem"><p>
+ parens
+ </p></li><li class="listitem"><p>
+ auth
+ </p></li><li class="listitem"><p>
+ xact
+ </p></li></ul></div><p>
+ </p><p>
+ Rationale: This will improve consistency.
+ </p></div><div class="simplesect" id="id-1.10.7.4.18"><div class="titlepage"><div><div><h3 class="title">Localization</h3></div></div></div><p>
+ Keep in mind that error message texts need to be translated into other
+ languages. Follow the guidelines in <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>
+ to avoid making life difficult for translators.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.2. Reporting Errors Within the Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.4. Miscellaneous Coding Conventions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-log-registration.html b/doc/src/sgml/html/event-log-registration.html
new file mode 100644
index 0000000..6fa0914
--- /dev/null
+++ b/doc/src/sgml/html/event-log-registration.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.12. Registering Event Log on Windows</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels" /><link rel="next" href="runtime-config.html" title="Chapter 20. Server Configuration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config.html" title="Chapter 20. Server Configuration">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-LOG-REGISTRATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span></h2></div></div></div><a id="id-1.6.6.15.2" class="indexterm"></a><p>
+ To register a <span class="systemitem">Windows</span>
+ <span class="application">event log</span> library with the operating system,
+ issue this command:
+</p><pre class="screen">
+<strong class="userinput"><code>regsvr32 <em class="replaceable"><code>pgsql_library_directory</code></em>/pgevent.dll</code></strong>
+</pre><p>
+ This creates registry entries used by the event viewer, under the default
+ event source named <code class="literal">PostgreSQL</code>.
+ </p><p>
+ To specify a different event source name (see
+ <a class="xref" href="runtime-config-logging.html#GUC-EVENT-SOURCE">event_source</a>), use the <code class="literal">/n</code>
+ and <code class="literal">/i</code> options:
+</p><pre class="screen">
+<strong class="userinput"><code>regsvr32 /n /i:<em class="replaceable"><code>event_source_name</code></em> <em class="replaceable"><code>pgsql_library_directory</code></em>/pgevent.dll</code></strong>
+</pre><p>
+ </p><p>
+ To unregister the <span class="application">event log</span> library from
+ the operating system, issue this command:
+</p><pre class="screen">
+<strong class="userinput"><code>regsvr32 /u [/i:<em class="replaceable"><code>event_source_name</code></em>] <em class="replaceable"><code>pgsql_library_directory</code></em>/pgevent.dll</code></strong>
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ To enable event logging in the database server, modify
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-DESTINATION">log_destination</a> to include
+ <code class="literal">eventlog</code> in <code class="filename">postgresql.conf</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config.html" title="Chapter 20. Server Configuration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 20. Server Configuration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-trigger-definition.html b/doc/src/sgml/html/event-trigger-definition.html
new file mode 100644
index 0000000..83f7ca0
--- /dev/null
+++ b/doc/src/sgml/html/event-trigger-definition.html
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.1. Overview of Event Trigger Behavior</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-triggers.html" title="Chapter 40. Event Triggers" /><link rel="next" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.1. Overview of Event Trigger Behavior</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-triggers.html" title="Chapter 40. Event Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-DEFINITION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.1. Overview of Event Trigger Behavior</h2></div></div></div><p>
+ An event trigger fires whenever the event with which it is associated
+ occurs in the database in which it is defined. Currently, the only
+ supported events are
+ <code class="literal">ddl_command_start</code>,
+ <code class="literal">ddl_command_end</code>,
+ <code class="literal">table_rewrite</code>
+ and <code class="literal">sql_drop</code>.
+ Support for additional events may be added in future releases.
+ </p><p>
+ The <code class="literal">ddl_command_start</code> event occurs just before the
+ execution of a <code class="literal">CREATE</code>, <code class="literal">ALTER</code>, <code class="literal">DROP</code>,
+ <code class="literal">SECURITY LABEL</code>,
+ <code class="literal">COMMENT</code>, <code class="literal">GRANT</code> or <code class="literal">REVOKE</code>
+ command. No check whether the affected object exists or doesn't exist is
+ performed before the event trigger fires.
+ As an exception, however, this event does not occur for
+ DDL commands targeting shared objects — databases, roles, and tablespaces
+ — or for commands targeting event triggers themselves. The event trigger
+ mechanism does not support these object types.
+ <code class="literal">ddl_command_start</code> also occurs just before the execution of a
+ <code class="literal">SELECT INTO</code> command, since this is equivalent to
+ <code class="literal">CREATE TABLE AS</code>.
+ </p><p>
+ The <code class="literal">ddl_command_end</code> event occurs just after the execution of
+ this same set of commands. To obtain more details on the <acronym class="acronym">DDL</acronym>
+ operations that took place, use the set-returning function
+ <code class="literal">pg_event_trigger_ddl_commands()</code> from the
+ <code class="literal">ddl_command_end</code> event trigger code (see
+ <a class="xref" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Section 9.29</a>). 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.
+ </p><p>
+ The <code class="literal">sql_drop</code> event occurs just before the
+ <code class="literal">ddl_command_end</code> event trigger for any operation that drops
+ database objects. To list the objects that have been dropped, use the
+ set-returning function <code class="literal">pg_event_trigger_dropped_objects()</code> from the
+ <code class="literal">sql_drop</code> event trigger code (see
+ <a class="xref" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Section 9.29</a>). 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.
+ </p><p>
+ The <code class="literal">table_rewrite</code> event occurs just before a table is
+ rewritten by some actions of the commands <code class="literal">ALTER TABLE</code> and
+ <code class="literal">ALTER TYPE</code>. While other
+ control statements are available to rewrite a table,
+ like <code class="literal">CLUSTER</code> and <code class="literal">VACUUM</code>,
+ the <code class="literal">table_rewrite</code> event is not triggered by them.
+ </p><p>
+ Event triggers (like other functions) cannot be executed in an aborted
+ transaction. Thus, if a DDL command fails with an error, any associated
+ <code class="literal">ddl_command_end</code> triggers will not be executed. Conversely,
+ if a <code class="literal">ddl_command_start</code> trigger fails with an error, no
+ further event triggers will fire, and no attempt will be made to execute
+ the command itself. Similarly, if a <code class="literal">ddl_command_end</code> trigger
+ fails with an error, the effects of the DDL statement will be rolled
+ back, just as they would be in any other case where the containing
+ transaction aborts.
+ </p><p>
+ For a complete list of commands supported by the event trigger mechanism,
+ see <a class="xref" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Section 40.2</a>.
+ </p><p>
+ Event triggers are created using the command <a class="xref" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER"><span class="refentrytitle">CREATE EVENT TRIGGER</span></a>.
+ In order to create an event trigger, you must first create a function with
+ the special return type <code class="literal">event_trigger</code>. This function
+ need not (and may not) return a value; the return type serves merely as
+ a signal that the function is to be invoked as an event trigger.
+ </p><p>
+ If more than one event trigger is defined for a particular event, they will
+ fire in alphabetical order by trigger name.
+ </p><p>
+ A trigger definition can also specify a <code class="literal">WHEN</code>
+ condition so that, for example, a <code class="literal">ddl_command_start</code>
+ trigger can be fired only for particular commands which the user wishes
+ to intercept. A common use of such triggers is to restrict the range of
+ DDL operations which users may perform.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-triggers.html" title="Chapter 40. Event Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 40. Event Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.2. Event Trigger Firing Matrix</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-trigger-example.html b/doc/src/sgml/html/event-trigger-example.html
new file mode 100644
index 0000000..6c279b7
--- /dev/null
+++ b/doc/src/sgml/html/event-trigger-example.html
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.4. A Complete Event Trigger Example</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C" /><link rel="next" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.4. A Complete Event Trigger Example</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.4. A Complete Event Trigger Example</h2></div></div></div><p>
+ Here is a very simple example of an event trigger function written in C.
+ (Examples of triggers written in procedural languages can be found in
+ the documentation of the procedural languages.)
+ </p><p>
+ The function <code class="function">noddl</code> raises an exception each time it is called.
+ The event trigger definition associated the function with
+ the <code class="literal">ddl_command_start</code> event. The effect is that all DDL
+ commands (with the exceptions mentioned
+ in <a class="xref" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Section 40.1</a>) are prevented from running.
+ </p><p>
+ This is the source code of the trigger function:
+</p><pre class="programlisting">
+#include "postgres.h"
+#include "commands/event_trigger.h"
+
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(noddl);
+
+Datum
+noddl(PG_FUNCTION_ARGS)
+{
+ EventTriggerData *trigdata;
+
+ if (!CALLED_AS_EVENT_TRIGGER(fcinfo)) /* internal error */
+ elog(ERROR, "not fired by event trigger manager");
+
+ trigdata = (EventTriggerData *) fcinfo-&gt;context;
+
+ ereport(ERROR,
+ (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE),
+ errmsg("command \"%s\" denied",
+ GetCommandTagName(trigdata-&gt;tag))));
+
+ PG_RETURN_NULL();
+}
+</pre><p>
+ </p><p>
+ After you have compiled the source code (see <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a>),
+ declare the function and the triggers:
+</p><pre class="programlisting">
+CREATE FUNCTION noddl() RETURNS event_trigger
+ AS 'noddl' LANGUAGE C;
+
+CREATE EVENT TRIGGER noddl ON ddl_command_start
+ EXECUTE FUNCTION noddl();
+</pre><p>
+ </p><p>
+ Now you can test the operation of the trigger:
+</p><pre class="screen">
+=# \dy
+ List of event triggers
+ Name | Event | Owner | Enabled | Function | Tags
+-------+-------------------+-------+---------+----------+------
+ noddl | ddl_command_start | dim | enabled | noddl |
+(1 row)
+
+=# CREATE TABLE foo(id serial);
+ERROR: command "CREATE TABLE" denied
+</pre><p>
+ </p><p>
+ In this situation, in order to be able to run some DDL commands when you
+ need to do so, you have to either drop the event trigger or disable it. It
+ can be convenient to disable the trigger for only the duration of a
+ transaction:
+</p><pre class="programlisting">
+BEGIN;
+ALTER EVENT TRIGGER noddl DISABLE;
+CREATE TABLE foo (id serial);
+ALTER EVENT TRIGGER noddl ENABLE;
+COMMIT;
+</pre><p>
+ (Recall that DDL commands on event triggers themselves are not affected by
+ event triggers.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example">Next</a></td></tr><tr><td width="40%" align="left" valign="top">40.3. Writing Event Trigger Functions in C </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.5. A Table Rewrite Event Trigger Example</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-trigger-interface.html b/doc/src/sgml/html/event-trigger-interface.html
new file mode 100644
index 0000000..1374d38
--- /dev/null
+++ b/doc/src/sgml/html/event-trigger-interface.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.3. Writing Event Trigger Functions in C</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix" /><link rel="next" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.3. Writing Event Trigger Functions in C</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-INTERFACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.3. Writing Event Trigger Functions in C</h2></div></div></div><a id="id-1.8.5.7.2" class="indexterm"></a><p>
+ This section describes the low-level details of the interface to an
+ event trigger function. This information is only needed when writing
+ event trigger functions in C. If you are using a higher-level language
+ then these details are handled for you. In most cases you should
+ consider using a procedural language before writing your event triggers
+ in C. The documentation of each procedural language explains how to
+ write an event trigger in that language.
+ </p><p>
+ Event trigger functions must use the <span class="quote">“<span class="quote">version 1</span>”</span> function
+ manager interface.
+ </p><p>
+ When a function is called by the event trigger manager, it is not passed
+ any normal arguments, but it is passed a <span class="quote">“<span class="quote">context</span>”</span> pointer
+ pointing to a <code class="structname">EventTriggerData</code> structure. C functions can
+ check whether they were called from the event trigger manager or not by
+ executing the macro:
+</p><pre class="programlisting">
+CALLED_AS_EVENT_TRIGGER(fcinfo)
+</pre><p>
+ which expands to:
+</p><pre class="programlisting">
+((fcinfo)-&gt;context != NULL &amp;&amp; IsA((fcinfo)-&gt;context, EventTriggerData))
+</pre><p>
+ If this returns true, then it is safe to cast
+ <code class="literal">fcinfo-&gt;context</code> to type <code class="literal">EventTriggerData
+ *</code> and make use of the pointed-to
+ <code class="structname">EventTriggerData</code> structure. The function must
+ <span class="emphasis"><em>not</em></span> alter the <code class="structname">EventTriggerData</code>
+ structure or any of the data it points to.
+ </p><p>
+ <code class="structname">struct EventTriggerData</code> is defined in
+ <code class="filename">commands/event_trigger.h</code>:
+
+</p><pre class="programlisting">
+typedef struct EventTriggerData
+{
+ NodeTag type;
+ const char *event; /* event name */
+ Node *parsetree; /* parse tree */
+ CommandTag tag; /* command tag */
+} EventTriggerData;
+</pre><p>
+
+ where the members are defined as follows:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="structfield">type</code></span></dt><dd><p>
+ Always <code class="literal">T_EventTriggerData</code>.
+ </p></dd><dt><span class="term"><code class="structfield">event</code></span></dt><dd><p>
+ Describes the event for which the function is called, one of
+ <code class="literal">"ddl_command_start"</code>, <code class="literal">"ddl_command_end"</code>,
+ <code class="literal">"sql_drop"</code>, <code class="literal">"table_rewrite"</code>.
+ See <a class="xref" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Section 40.1</a> for the meaning of these
+ events.
+ </p></dd><dt><span class="term"><code class="structfield">parsetree</code></span></dt><dd><p>
+ A pointer to the parse tree of the command. Check the PostgreSQL
+ source code for details. The parse tree structure is subject to change
+ without notice.
+ </p></dd><dt><span class="term"><code class="structfield">tag</code></span></dt><dd><p>
+ The command tag associated with the event for which the event trigger
+ is run, for example <code class="literal">"CREATE FUNCTION"</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ An event trigger function must return a <code class="symbol">NULL</code> pointer
+ (<span class="emphasis"><em>not</em></span> an SQL null value, that is, do not
+ set <em class="parameter"><code>isNull</code></em> true).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-trigger-matrix.html" title="40.2. Event Trigger Firing Matrix">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example">Next</a></td></tr><tr><td width="40%" align="left" valign="top">40.2. Event Trigger Firing Matrix </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.4. A Complete Event Trigger Example</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-trigger-matrix.html b/doc/src/sgml/html/event-trigger-matrix.html
new file mode 100644
index 0000000..fdfe8c9
--- /dev/null
+++ b/doc/src/sgml/html/event-trigger-matrix.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.2. Event Trigger Firing Matrix</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior" /><link rel="next" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.2. Event Trigger Firing Matrix</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-MATRIX"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.2. Event Trigger Firing Matrix</h2></div></div></div><p>
+ <a class="xref" href="event-trigger-matrix.html#EVENT-TRIGGER-BY-COMMAND-TAG" title="Table 40.1. Event Trigger Support by Command Tag">Table 40.1</a> lists all commands
+ for which event triggers are supported.
+ </p><div class="table" id="EVENT-TRIGGER-BY-COMMAND-TAG"><p class="title"><strong>Table 40.1. Event Trigger Support by Command Tag</strong></p><div class="table-contents"><table class="table" summary="Event Trigger Support by Command Tag" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /><col class="col6" /></colgroup><thead><tr><th>Command Tag</th><th><code class="literal">ddl_​command_​start</code></th><th><code class="literal">ddl_​command_​end</code></th><th><code class="literal">sql_​drop</code></th><th><code class="literal">table_​rewrite</code></th><th>Notes</th></tr></thead><tbody><tr><td align="left"><code class="literal">ALTER AGGREGATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER COLLATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER CONVERSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER DOMAIN</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER DEFAULT PRIVILEGES</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER EXTENSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER FOREIGN DATA WRAPPER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER FOREIGN TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER FUNCTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER LANGUAGE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER LARGE OBJECT</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER MATERIALIZED VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">X</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER OPERATOR</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER OPERATOR CLASS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER OPERATOR FAMILY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER POLICY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER PROCEDURE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER PUBLICATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER ROUTINE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER SCHEMA</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER SEQUENCE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER SERVER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER STATISTICS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER SUBSCRIPTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TEXT SEARCH CONFIGURATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TEXT SEARCH DICTIONARY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TEXT SEARCH PARSER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TEXT SEARCH TEMPLATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TRIGGER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER TYPE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">X</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER USER MAPPING</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">ALTER VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">COMMENT</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left">Only for local objects</td></tr><tr><td align="left"><code class="literal">CREATE ACCESS METHOD</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE AGGREGATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE CAST</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE COLLATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE CONVERSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE DOMAIN</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE EXTENSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE FOREIGN DATA WRAPPER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE FOREIGN TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE FUNCTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE INDEX</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE LANGUAGE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE MATERIALIZED VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE OPERATOR</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE OPERATOR CLASS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE OPERATOR FAMILY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE POLICY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE PROCEDURE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE PUBLICATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE RULE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE SCHEMA</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE SEQUENCE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE SERVER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE STATISTICS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE SUBSCRIPTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TABLE AS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TEXT SEARCH CONFIGURATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TEXT SEARCH DICTIONARY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TEXT SEARCH PARSER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TEXT SEARCH TEMPLATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TRIGGER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE TYPE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE USER MAPPING</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">CREATE VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP ACCESS METHOD</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP AGGREGATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP CAST</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP COLLATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP CONVERSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP DOMAIN</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP EXTENSION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP FOREIGN DATA WRAPPER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP FOREIGN TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP FUNCTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP INDEX</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP LANGUAGE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP MATERIALIZED VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP OPERATOR</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP OPERATOR CLASS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP OPERATOR FAMILY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP OWNED</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP POLICY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP PROCEDURE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP PUBLICATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP ROUTINE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP RULE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP SCHEMA</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP SEQUENCE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP SERVER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP STATISTICS</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP SUBSCRIPTION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TABLE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TEXT SEARCH CONFIGURATION</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TEXT SEARCH DICTIONARY</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TEXT SEARCH PARSER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TEXT SEARCH TEMPLATE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TRIGGER</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP TYPE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP USER MAPPING</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">DROP VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">GRANT</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left">Only for local objects</td></tr><tr><td align="left"><code class="literal">IMPORT FOREIGN SCHEMA</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">REFRESH MATERIALIZED VIEW</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr><tr><td align="left"><code class="literal">REVOKE</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left">Only for local objects</td></tr><tr><td align="left"><code class="literal">SECURITY LABEL</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left">Only for local objects</td></tr><tr><td align="left"><code class="literal">SELECT INTO</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">X</code></td><td align="center"><code class="literal">-</code></td><td align="center"><code class="literal">-</code></td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-interface.html" title="40.3. Writing Event Trigger Functions in C">Next</a></td></tr><tr><td width="40%" align="left" valign="top">40.1. Overview of Event Trigger Behavior </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.3. Writing Event Trigger Functions in C</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-trigger-table-rewrite-example.html b/doc/src/sgml/html/event-trigger-table-rewrite-example.html
new file mode 100644
index 0000000..a007ffc
--- /dev/null
+++ b/doc/src/sgml/html/event-trigger-table-rewrite-example.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.5. A Table Rewrite Event Trigger Example</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example" /><link rel="next" href="rules.html" title="Chapter 41. The Rule System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.5. A Table Rewrite Event Trigger Example</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><th width="60%" align="center">Chapter 40. Event Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules.html" title="Chapter 41. The Rule System">Next</a></td></tr></table><hr /></div><div class="sect1" id="EVENT-TRIGGER-TABLE-REWRITE-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.5. A Table Rewrite Event Trigger Example</h2></div></div></div><p>
+ Thanks to the <code class="literal">table_rewrite</code> event, it is possible to implement
+ a table rewriting policy only allowing the rewrite in maintenance windows.
+ </p><p>
+ Here's an example implementing such a policy.
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION no_rewrite()
+ RETURNS event_trigger
+ LANGUAGE plpgsql AS
+$$
+---
+--- Implement local Table Rewriting policy:
+--- public.foo is not allowed rewriting, ever
+--- other tables are only allowed rewriting between 1am and 6am
+--- unless they have more than 100 blocks
+---
+DECLARE
+ table_oid oid := pg_event_trigger_table_rewrite_oid();
+ current_hour integer := extract('hour' from current_time);
+ pages integer;
+ max_pages integer := 100;
+BEGIN
+ IF pg_event_trigger_table_rewrite_oid() = 'public.foo'::regclass
+ THEN
+ RAISE EXCEPTION 'you''re not allowed to rewrite the table %',
+ table_oid::regclass;
+ END IF;
+
+ SELECT INTO pages relpages FROM pg_class WHERE oid = table_oid;
+ IF pages &gt; max_pages
+ THEN
+ RAISE EXCEPTION 'rewrites only allowed for table with less than % pages',
+ max_pages;
+ END IF;
+
+ IF current_hour NOT BETWEEN 1 AND 6
+ THEN
+ RAISE EXCEPTION 'rewrites only allowed between 1am and 6am';
+ END IF;
+END;
+$$;
+
+CREATE EVENT TRIGGER no_rewrite_allowed
+ ON table_rewrite
+ EXECUTE FUNCTION no_rewrite();
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-trigger-example.html" title="40.4. A Complete Event Trigger Example">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="event-triggers.html" title="Chapter 40. Event Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules.html" title="Chapter 41. The Rule System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">40.4. A Complete Event Trigger Example </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 41. The Rule System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/event-triggers.html b/doc/src/sgml/html/event-triggers.html
new file mode 100644
index 0000000..241b48f
--- /dev/null
+++ b/doc/src/sgml/html/event-triggers.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 40. Event Triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="trigger-example.html" title="39.4. A Complete Trigger Example" /><link rel="next" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 40. Event Triggers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="trigger-example.html" title="39.4. A Complete Trigger Example">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Next</a></td></tr></table><hr /></div><div class="chapter" id="EVENT-TRIGGERS"><div class="titlepage"><div><div><h2 class="title">Chapter 40. Event Triggers</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="event-trigger-definition.html">40.1. Overview of Event Trigger Behavior</a></span></dt><dt><span class="sect1"><a href="event-trigger-matrix.html">40.2. Event Trigger Firing Matrix</a></span></dt><dt><span class="sect1"><a href="event-trigger-interface.html">40.3. Writing Event Trigger Functions in C</a></span></dt><dt><span class="sect1"><a href="event-trigger-example.html">40.4. A Complete Event Trigger Example</a></span></dt><dt><span class="sect1"><a href="event-trigger-table-rewrite-example.html">40.5. A Table Rewrite Event Trigger Example</a></span></dt></dl></div><a id="id-1.8.5.2" class="indexterm"></a><p>
+ To supplement the trigger mechanism discussed in <a class="xref" href="triggers.html" title="Chapter 39. Triggers">Chapter 39</a>,
+ <span class="productname">PostgreSQL</span> 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
+ capturing DDL events.
+ </p><p>
+ Like regular triggers, event triggers can be written in any procedural
+ language that includes event trigger support, or in C, but not in plain
+ SQL.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="trigger-example.html" title="39.4. A Complete Trigger Example">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Next</a></td></tr><tr><td width="40%" align="left" valign="top">39.4. A Complete Trigger Example </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 40.1. Overview of Event Trigger Behavior</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/executor.html b/doc/src/sgml/html/executor.html
new file mode 100644
index 0000000..e5e6c98
--- /dev/null
+++ b/doc/src/sgml/html/executor.html
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.6. Executor</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="planner-optimizer.html" title="52.5. Planner/Optimizer" /><link rel="next" href="catalogs.html" title="Chapter 53. System Catalogs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.6. Executor</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="planner-optimizer.html" title="52.5. Planner/Optimizer">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="catalogs.html" title="Chapter 53. System Catalogs">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXECUTOR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.6. Executor</h2></div></div></div><p>
+ The <em class="firstterm">executor</em> takes the plan created by the
+ planner/optimizer and recursively processes it to extract the required set
+ of rows. This is essentially a demand-pull pipeline mechanism.
+ Each time a plan node is called, it must deliver one more row, or
+ report that it is done delivering rows.
+ </p><p>
+ To provide a concrete example, assume that the top
+ node is a <code class="literal">MergeJoin</code> node.
+ Before any merge can be done two rows have to be fetched (one from
+ each subplan). So the executor recursively calls itself to
+ process the subplans (it starts with the subplan attached to
+ <code class="literal">lefttree</code>). The new top node (the top node of the left
+ subplan) is, let's say, a
+ <code class="literal">Sort</code> node and again recursion is needed to obtain
+ an input row. The child node of the <code class="literal">Sort</code> might
+ be a <code class="literal">SeqScan</code> node, representing actual reading of a table.
+ Execution of this node causes the executor to fetch a row from the
+ table and return it up to the calling node. The <code class="literal">Sort</code>
+ node will repeatedly call its child to obtain all the rows to be sorted.
+ When the input is exhausted (as indicated by the child node returning
+ a NULL instead of a row), the <code class="literal">Sort</code> code performs
+ the sort, and finally is able to return its first output row, namely
+ the first one in sorted order. It keeps the remaining rows stored so
+ that it can deliver them in sorted order in response to later demands.
+ </p><p>
+ The <code class="literal">MergeJoin</code> node similarly demands the first row
+ from its right subplan. Then it compares the two rows to see if they
+ can be joined; if so, it returns a join row to its caller. On the next
+ call, or immediately if it cannot join the current pair of inputs,
+ it advances to the next row of one table
+ or the other (depending on how the comparison came out), and again
+ checks for a match. Eventually, one subplan or the other is exhausted,
+ and the <code class="literal">MergeJoin</code> node returns NULL to indicate that
+ no more join rows can be formed.
+ </p><p>
+ Complex queries can involve many levels of plan nodes, but the general
+ approach is the same: each node computes and returns its next output
+ row each time it is called. Each node is also responsible for applying
+ any selection or projection expressions that were assigned to it by
+ the planner.
+ </p><p>
+ The executor mechanism is used to evaluate all five basic SQL query
+ types: <code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and
+ <code class="command">MERGE</code>.
+ For <code class="command">SELECT</code>, the top-level executor code
+ only needs to send each row returned by the query plan tree
+ off to the client. <code class="command">INSERT ... SELECT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and
+ <code class="command">MERGE</code>
+ are effectively <code class="command">SELECT</code>s under a special
+ top-level plan node called <code class="literal">ModifyTable</code>.
+ </p><p>
+ <code class="command">INSERT ... SELECT</code> feeds the rows up
+ to <code class="literal">ModifyTable</code> for insertion. For
+ <code class="command">UPDATE</code>, the planner arranges that each
+ computed row includes all the updated column values, plus the
+ <em class="firstterm">TID</em> (tuple ID, or row ID) of the original
+ target row; this data is fed up to the <code class="literal">ModifyTable</code>
+ node, which uses the information to create a new updated row and
+ mark the old row deleted. For <code class="command">DELETE</code>, the only
+ column that is actually returned by the plan is the TID, and the
+ <code class="literal">ModifyTable</code> node simply uses the TID to visit each
+ target row and mark it deleted. For <code class="command">MERGE</code>, the
+ planner joins the source and target relations, and includes all
+ column values required by any of the <code class="literal">WHEN</code> clauses,
+ plus the TID of the target row; this data is fed up to the
+ <code class="literal">ModifyTable</code> node, which uses the information to
+ work out which <code class="literal">WHEN</code> clause to execute, and then
+ inserts, updates or deletes the target row, as required.
+ </p><p>
+ A simple <code class="command">INSERT ... VALUES</code> command creates a
+ trivial plan tree consisting of a single <code class="literal">Result</code>
+ node, which computes just one result row, feeding that up
+ to <code class="literal">ModifyTable</code> to perform the insertion.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="planner-optimizer.html" title="52.5. Planner/Optimizer">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="catalogs.html" title="Chapter 53. System Catalogs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.5. Planner/Optimizer </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 53. System Catalogs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/explicit-joins.html b/doc/src/sgml/html/explicit-joins.html
new file mode 100644
index 0000000..8e98484
--- /dev/null
+++ b/doc/src/sgml/html/explicit-joins.html
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>14.3. Controlling the Planner with Explicit JOIN Clauses</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="planner-stats.html" title="14.2. Statistics Used by the Planner" /><link rel="next" href="populate.html" title="14.4. Populating a Database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><th width="60%" align="center">Chapter 14. Performance Tips</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="populate.html" title="14.4. Populating a Database">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXPLICIT-JOINS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses</h2></div></div></div><a id="id-1.5.13.6.2" class="indexterm"></a><p>
+ It is possible
+ to control the query planner to some extent by using the explicit <code class="literal">JOIN</code>
+ syntax. To see why this matters, we first need some background.
+ </p><p>
+ In a simple join query, such as:
+</p><pre class="programlisting">
+SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
+</pre><p>
+ the planner is free to join the given tables in any order. For
+ example, it could generate a query plan that joins A to B, using
+ the <code class="literal">WHERE</code> condition <code class="literal">a.id = b.id</code>, and then
+ joins C to this joined table, using the other <code class="literal">WHERE</code>
+ condition. Or it could join B to C and then join A to that result.
+ Or it could join A to C and then join them with B — but that
+ would be inefficient, since the full Cartesian product of A and C
+ would have to be formed, there being no applicable condition in the
+ <code class="literal">WHERE</code> clause to allow optimization of the join. (All
+ joins in the <span class="productname">PostgreSQL</span> executor happen
+ between two input tables, so it's necessary to build up the result
+ in one or another of these fashions.) The important point is that
+ these different join possibilities give semantically equivalent
+ results but might have hugely different execution costs. Therefore,
+ the planner will explore all of them to try to find the most
+ efficient query plan.
+ </p><p>
+ When a query only involves two or three tables, there aren't many join
+ orders to worry about. But the number of possible join orders grows
+ exponentially as the number of tables expands. Beyond ten or so input
+ tables it's no longer practical to do an exhaustive search of all the
+ possibilities, and even for six or seven tables planning might take an
+ annoyingly long time. When there are too many input tables, the
+ <span class="productname">PostgreSQL</span> planner will switch from exhaustive
+ search to a <em class="firstterm">genetic</em> probabilistic search
+ through a limited number of possibilities. (The switch-over threshold is
+ set by the <a class="xref" href="runtime-config-query.html#GUC-GEQO-THRESHOLD">geqo_threshold</a> run-time
+ parameter.)
+ The genetic search takes less time, but it won't
+ necessarily find the best possible plan.
+ </p><p>
+ When the query involves outer joins, the planner has less freedom
+ than it does for plain (inner) joins. For example, consider:
+</p><pre class="programlisting">
+SELECT * FROM a LEFT JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
+</pre><p>
+ Although this query's restrictions are superficially similar to the
+ previous example, the semantics are different because a row must be
+ emitted for each row of A that has no matching row in the join of B and C.
+ Therefore the planner has no choice of join order here: it must join
+ B to C and then join A to that result. Accordingly, this query takes
+ less time to plan than the previous query. In other cases, the planner
+ might be able to determine that more than one join order is safe.
+ For example, given:
+</p><pre class="programlisting">
+SELECT * FROM a LEFT JOIN b ON (a.bid = b.id) LEFT JOIN c ON (a.cid = c.id);
+</pre><p>
+ it is valid to join A to either B or C first. Currently, only
+ <code class="literal">FULL JOIN</code> completely constrains the join order. Most
+ practical cases involving <code class="literal">LEFT JOIN</code> or <code class="literal">RIGHT JOIN</code>
+ can be rearranged to some extent.
+ </p><p>
+ Explicit inner join syntax (<code class="literal">INNER JOIN</code>, <code class="literal">CROSS
+ JOIN</code>, or unadorned <code class="literal">JOIN</code>) is semantically the same as
+ listing the input relations in <code class="literal">FROM</code>, so it does not
+ constrain the join order.
+ </p><p>
+ Even though most kinds of <code class="literal">JOIN</code> don't completely constrain
+ the join order, it is possible to instruct the
+ <span class="productname">PostgreSQL</span> query planner to treat all
+ <code class="literal">JOIN</code> clauses as constraining the join order anyway.
+ For example, these three queries are logically equivalent:
+</p><pre class="programlisting">
+SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
+SELECT * FROM a CROSS JOIN b CROSS JOIN c WHERE a.id = b.id AND b.ref = c.id;
+SELECT * FROM a JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
+</pre><p>
+ But if we tell the planner to honor the <code class="literal">JOIN</code> order,
+ the second and third take less time to plan than the first. This effect
+ is not worth worrying about for only three tables, but it can be a
+ lifesaver with many tables.
+ </p><p>
+ To force the planner to follow the join order laid out by explicit
+ <code class="literal">JOIN</code>s,
+ set the <a class="xref" href="runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT">join_collapse_limit</a> run-time parameter to 1.
+ (Other possible values are discussed below.)
+ </p><p>
+ You do not need to constrain the join order completely in order to
+ cut search time, because it's OK to use <code class="literal">JOIN</code> operators
+ within items of a plain <code class="literal">FROM</code> list. For example, consider:
+</p><pre class="programlisting">
+SELECT * FROM a CROSS JOIN b, c, d, e WHERE ...;
+</pre><p>
+ With <code class="varname">join_collapse_limit</code> = 1, this
+ forces the planner to join A to B before joining them to other tables,
+ but doesn't constrain its choices otherwise. In this example, the
+ number of possible join orders is reduced by a factor of 5.
+ </p><p>
+ Constraining the planner's search in this way is a useful technique
+ both for reducing planning time and for directing the planner to a
+ good query plan. If the planner chooses a bad join order by default,
+ you can force it to choose a better order via <code class="literal">JOIN</code> syntax
+ — assuming that you know of a better order, that is. Experimentation
+ is recommended.
+ </p><p>
+ A closely related issue that affects planning time is collapsing of
+ subqueries into their parent query. For example, consider:
+</p><pre class="programlisting">
+SELECT *
+FROM x, y,
+ (SELECT * FROM a, b, c WHERE something) AS ss
+WHERE somethingelse;
+</pre><p>
+ This situation might arise from use of a view that contains a join;
+ the view's <code class="literal">SELECT</code> rule will be inserted in place of the view
+ reference, yielding a query much like the above. Normally, the planner
+ will try to collapse the subquery into the parent, yielding:
+</p><pre class="programlisting">
+SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
+</pre><p>
+ This usually results in a better plan than planning the subquery
+ separately. (For example, the outer <code class="literal">WHERE</code> conditions might be such that
+ joining X to A first eliminates many rows of A, thus avoiding the need to
+ form the full logical output of the subquery.) But at the same time,
+ we have increased the planning time; here, we have a five-way join
+ problem replacing two separate three-way join problems. Because of the
+ exponential growth of the number of possibilities, this makes a big
+ difference. The planner tries to avoid getting stuck in huge join search
+ problems by not collapsing a subquery if more than <code class="varname">from_collapse_limit</code>
+ <code class="literal">FROM</code> items would result in the parent
+ query. You can trade off planning time against quality of plan by
+ adjusting this run-time parameter up or down.
+ </p><p>
+ <a class="xref" href="runtime-config-query.html#GUC-FROM-COLLAPSE-LIMIT">from_collapse_limit</a> and <a class="xref" href="runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT">join_collapse_limit</a>
+ are similarly named because they do almost the same thing: one controls
+ when the planner will <span class="quote">“<span class="quote">flatten out</span>”</span> subqueries, and the
+ other controls when it will flatten out explicit joins. Typically
+ you would either set <code class="varname">join_collapse_limit</code> equal to
+ <code class="varname">from_collapse_limit</code> (so that explicit joins and subqueries
+ act similarly) or set <code class="varname">join_collapse_limit</code> to 1 (if you want
+ to control join order with explicit joins). But you might set them
+ differently if you are trying to fine-tune the trade-off between planning
+ time and run time.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="populate.html" title="14.4. Populating a Database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.2. Statistics Used by the Planner </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 14.4. Populating a Database</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/explicit-locking.html b/doc/src/sgml/html/explicit-locking.html
new file mode 100644
index 0000000..9a28c47
--- /dev/null
+++ b/doc/src/sgml/html/explicit-locking.html
@@ -0,0 +1,396 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.3. Explicit Locking</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="transaction-iso.html" title="13.2. Transaction Isolation" /><link rel="next" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.3. Explicit Locking</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="transaction-iso.html" title="13.2. Transaction Isolation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXPLICIT-LOCKING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.3. Explicit Locking</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-TABLES">13.3.1. Table-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-ROWS">13.3.2. Row-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-PAGES">13.3.3. Page-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-DEADLOCKS">13.3.4. Deadlocks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#ADVISORY-LOCKS">13.3.5. Advisory Locks</a></span></dt></dl></div><a id="id-1.5.12.6.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides various lock modes
+ to control concurrent access to data in tables. These modes can
+ be used for application-controlled locking in situations where
+ <acronym class="acronym">MVCC</acronym> does not give the desired behavior. Also,
+ most <span class="productname">PostgreSQL</span> commands automatically
+ acquire locks of appropriate modes to ensure that referenced
+ tables are not dropped or modified in incompatible ways while the
+ command executes. (For example, <code class="command">TRUNCATE</code> cannot safely be
+ executed concurrently with other operations on the same table, so it
+ obtains an <code class="literal">ACCESS EXCLUSIVE</code> lock on the table to
+ enforce that.)
+ </p><p>
+ To examine a list of the currently outstanding locks in a database
+ server, use the
+ <a class="link" href="view-pg-locks.html" title="54.12. pg_locks"><code class="structname">pg_locks</code></a>
+ system view. For more information on monitoring the status of the lock
+ manager subsystem, refer to <a class="xref" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Chapter 28</a>.
+ </p><div class="sect2" id="LOCKING-TABLES"><div class="titlepage"><div><div><h3 class="title">13.3.1. Table-Level Locks</h3></div></div></div><a id="id-1.5.12.6.5.2" class="indexterm"></a><p>
+ The list below shows the available lock modes and the contexts in
+ which they are used automatically by
+ <span class="productname">PostgreSQL</span>. You can also acquire any
+ of these locks explicitly with the command <a class="xref" href="sql-lock.html" title="LOCK"><span class="refentrytitle">LOCK</span></a>.
+ Remember that all of these lock modes are table-level locks,
+ even if the name contains the word
+ <span class="quote">“<span class="quote">row</span>”</span>; the names of the lock modes are historical.
+ To some extent the names reflect the typical usage of each lock
+ mode — but the semantics are all the same. The only real difference
+ between one lock mode and another is the set of lock modes with
+ which each conflicts (see <a class="xref" href="explicit-locking.html#TABLE-LOCK-COMPATIBILITY" title="Table 13.2. Conflicting Lock Modes">Table 13.2</a>).
+ Two transactions cannot hold locks of conflicting
+ modes on the same table at the same time. (However, a transaction
+ never conflicts with itself. For example, it might acquire
+ <code class="literal">ACCESS EXCLUSIVE</code> lock and later acquire
+ <code class="literal">ACCESS SHARE</code> lock on the same table.) Non-conflicting
+ lock modes can be held concurrently by many transactions. Notice in
+ particular that some lock modes are self-conflicting (for example,
+ an <code class="literal">ACCESS EXCLUSIVE</code> lock cannot be held by more than one
+ transaction at a time) while others are not self-conflicting (for example,
+ an <code class="literal">ACCESS SHARE</code> lock can be held by multiple transactions).
+ </p><div class="variablelist"><p class="title"><strong>Table-Level Lock Modes</strong></p><dl class="variablelist"><dt><span class="term">
+ <code class="literal">ACCESS SHARE</code> (<code class="literal">AccessShareLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">ACCESS EXCLUSIVE</code> lock
+ mode only.
+ </p><p>
+ The <code class="command">SELECT</code> command acquires a lock of this mode on
+ referenced tables. In general, any query that only <span class="emphasis"><em>reads</em></span> a table
+ and does not modify it will acquire this lock mode.
+ </p></dd><dt><span class="term">
+ <code class="literal">ROW SHARE</code> (<code class="literal">RowShareLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">EXCLUSIVE</code> and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ </p><p>
+ The <code class="command">SELECT</code> command acquires a lock of this mode
+ on all tables on which one of the <code class="option">FOR UPDATE</code>,
+ <code class="option">FOR NO KEY UPDATE</code>,
+ <code class="option">FOR SHARE</code>, or
+ <code class="option">FOR KEY SHARE</code> options is specified
+ (in addition to <code class="literal">ACCESS SHARE</code> locks on any other
+ tables that are referenced without any explicit
+ <code class="option">FOR ...</code> locking option).
+ </p></dd><dt><span class="term">
+ <code class="literal">ROW EXCLUSIVE</code> (<code class="literal">RowExclusiveLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">SHARE</code>, <code class="literal">SHARE ROW
+ EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ </p><p>
+ The commands <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">INSERT</code>, and
+ <code class="command">MERGE</code>
+ acquire this lock mode on the target table (in addition to
+ <code class="literal">ACCESS SHARE</code> locks on any other referenced
+ tables). In general, this lock mode will be acquired by any
+ command that <span class="emphasis"><em>modifies data</em></span> in a table.
+ </p></dd><dt><span class="term">
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> (<code class="literal">ShareUpdateExclusiveLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">SHARE UPDATE EXCLUSIVE</code>,
+ <code class="literal">SHARE</code>, <code class="literal">SHARE ROW
+ EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ This mode protects a table against
+ concurrent schema changes and <code class="command">VACUUM</code> runs.
+ </p><p>
+ Acquired by <code class="command">VACUUM</code> (without <code class="option">FULL</code>),
+ <code class="command">ANALYZE</code>, <code class="command">CREATE INDEX CONCURRENTLY</code>,
+ <code class="command">CREATE STATISTICS</code>, <code class="command">COMMENT ON</code>,
+ <code class="command">REINDEX CONCURRENTLY</code>,
+ and certain <a class="link" href="sql-alterindex.html" title="ALTER INDEX"><code class="command">ALTER INDEX</code></a>
+ and <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> variants
+ (for full details see the documentation of these commands).
+ </p></dd><dt><span class="term">
+ <code class="literal">SHARE</code> (<code class="literal">ShareLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">ROW EXCLUSIVE</code>,
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code>, <code class="literal">SHARE ROW
+ EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ This mode protects a table against concurrent data changes.
+ </p><p>
+ Acquired by <code class="command">CREATE INDEX</code>
+ (without <code class="option">CONCURRENTLY</code>).
+ </p></dd><dt><span class="term">
+ <code class="literal">SHARE ROW EXCLUSIVE</code> (<code class="literal">ShareRowExclusiveLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">ROW EXCLUSIVE</code>,
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code>,
+ <code class="literal">SHARE</code>, <code class="literal">SHARE ROW
+ EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ This mode protects a table against concurrent data changes, and
+ is self-exclusive so that only one session can hold it at a time.
+ </p><p>
+ Acquired by <code class="command">CREATE TRIGGER</code> and some forms of
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>.
+ </p></dd><dt><span class="term">
+ <code class="literal">EXCLUSIVE</code> (<code class="literal">ExclusiveLock</code>)
+ </span></dt><dd><p>
+ Conflicts with the <code class="literal">ROW SHARE</code>, <code class="literal">ROW
+ EXCLUSIVE</code>, <code class="literal">SHARE UPDATE
+ EXCLUSIVE</code>, <code class="literal">SHARE</code>, <code class="literal">SHARE
+ ROW EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code> lock modes.
+ This mode allows only concurrent <code class="literal">ACCESS SHARE</code> locks,
+ i.e., only reads from the table can proceed in parallel with a
+ transaction holding this lock mode.
+ </p><p>
+ Acquired by <code class="command">REFRESH MATERIALIZED VIEW CONCURRENTLY</code>.
+ </p></dd><dt><span class="term">
+ <code class="literal">ACCESS EXCLUSIVE</code> (<code class="literal">AccessExclusiveLock</code>)
+ </span></dt><dd><p>
+ Conflicts with locks of all modes (<code class="literal">ACCESS
+ SHARE</code>, <code class="literal">ROW SHARE</code>, <code class="literal">ROW
+ EXCLUSIVE</code>, <code class="literal">SHARE UPDATE
+ EXCLUSIVE</code>, <code class="literal">SHARE</code>, <code class="literal">SHARE
+ ROW EXCLUSIVE</code>, <code class="literal">EXCLUSIVE</code>, and
+ <code class="literal">ACCESS EXCLUSIVE</code>).
+ This mode guarantees that the
+ holder is the only transaction accessing the table in any way.
+ </p><p>
+ Acquired by the <code class="command">DROP TABLE</code>,
+ <code class="command">TRUNCATE</code>, <code class="command">REINDEX</code>,
+ <code class="command">CLUSTER</code>, <code class="command">VACUUM FULL</code>,
+ and <code class="command">REFRESH MATERIALIZED VIEW</code> (without
+ <code class="option">CONCURRENTLY</code>)
+ commands. Many forms of <code class="command">ALTER INDEX</code> and <code class="command">ALTER TABLE</code> also acquire
+ a lock at this level. This is also the default lock mode for
+ <code class="command">LOCK TABLE</code> statements that do not specify
+ a mode explicitly.
+ </p></dd></dl></div><div class="tip"><h3 class="title">Tip</h3><p>
+ Only an <code class="literal">ACCESS EXCLUSIVE</code> lock blocks a
+ <code class="command">SELECT</code> (without <code class="option">FOR UPDATE/SHARE</code>)
+ statement.
+ </p></div><p>
+ Once acquired, a lock is normally held until the end of the transaction. But if a
+ lock is acquired after establishing a savepoint, the lock is released
+ immediately if the savepoint is rolled back to. This is consistent with
+ the principle that <code class="command">ROLLBACK</code> cancels all effects of the
+ commands since the savepoint. The same holds for locks acquired within a
+ <span class="application">PL/pgSQL</span> exception block: an error escape from the block
+ releases locks acquired within it.
+ </p><div class="table" id="TABLE-LOCK-COMPATIBILITY"><p class="title"><strong>Table 13.2. Conflicting Lock Modes</strong></p><div class="table-contents"><table class="table" summary="Conflicting Lock Modes" border="1"><colgroup><col /><col class="lockst" /><col /><col /><col /><col /><col /><col /><col class="lockend" /></colgroup><thead><tr><th rowspan="2">Requested Lock Mode</th><th colspan="8" align="center">Existing Lock Mode</th></tr><tr><th><code class="literal">ACCESS SHARE</code></th><th><code class="literal">ROW SHARE</code></th><th><code class="literal">ROW EXCL.</code></th><th><code class="literal">SHARE UPDATE EXCL.</code></th><th><code class="literal">SHARE</code></th><th><code class="literal">SHARE ROW EXCL.</code></th><th><code class="literal">EXCL.</code></th><th><code class="literal">ACCESS EXCL.</code></th></tr></thead><tbody><tr><td><code class="literal">ACCESS SHARE</code></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">X</td></tr><tr><td><code class="literal">ROW SHARE</code></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">ROW EXCL.</code></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">SHARE UPDATE EXCL.</code></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">SHARE</code></td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">SHARE ROW EXCL.</code></td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">EXCL.</code></td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code class="literal">ACCESS EXCL.</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="LOCKING-ROWS"><div class="titlepage"><div><div><h3 class="title">13.3.2. Row-Level Locks</h3></div></div></div><p>
+ In addition to table-level locks, there are row-level locks, which
+ are listed as below with the contexts in which they are used
+ automatically by <span class="productname">PostgreSQL</span>. See
+ <a class="xref" href="explicit-locking.html#ROW-LOCK-COMPATIBILITY" title="Table 13.3. Conflicting Row-Level Locks">Table 13.3</a> for a complete table of
+ row-level lock conflicts. Note that a transaction can hold
+ conflicting locks on the same row, even in different subtransactions;
+ but other than that, two transactions can never hold conflicting locks
+ on the same row. Row-level locks do not affect data querying; they
+ block only <span class="emphasis"><em>writers and lockers</em></span> to the same
+ row. Row-level locks are released at transaction end or during
+ savepoint rollback, just like table-level locks.
+
+ </p><div class="variablelist"><p class="title"><strong>Row-Level Lock Modes</strong></p><dl class="variablelist"><dt><span class="term">
+ <code class="literal">FOR UPDATE</code>
+ </span></dt><dd><p>
+ <code class="literal">FOR UPDATE</code> causes the rows retrieved by the
+ <code class="command">SELECT</code> statement to be locked as though for
+ update. This prevents them from being locked, modified or deleted by
+ other transactions until the current transaction ends. That is,
+ other transactions that attempt <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>,
+ <code class="command">SELECT FOR UPDATE</code>,
+ <code class="command">SELECT FOR NO KEY UPDATE</code>,
+ <code class="command">SELECT FOR SHARE</code> or
+ <code class="command">SELECT FOR KEY SHARE</code>
+ of these rows will be blocked until the current transaction ends;
+ conversely, <code class="command">SELECT FOR UPDATE</code> will wait for a
+ concurrent transaction that has run any of those commands on the
+ same row,
+ and will then lock and return the updated row (or no row, if the
+ row was deleted). Within a <code class="literal">REPEATABLE READ</code> or
+ <code class="literal">SERIALIZABLE</code> transaction,
+ however, an error will be thrown if a row to be locked has changed
+ since the transaction started. For further discussion see
+ <a class="xref" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level">Section 13.4</a>.
+ </p><p>
+ The <code class="literal">FOR UPDATE</code> lock mode
+ is also acquired by any <code class="command">DELETE</code> on a row, and also by an
+ <code class="command">UPDATE</code> that modifies the values of certain columns. Currently,
+ the set of columns considered for the <code class="command">UPDATE</code> case are those that
+ have a unique index on them that can be used in a foreign key (so partial
+ indexes and expressional indexes are not considered), but this may change
+ in the future.
+ </p></dd><dt><span class="term">
+ <code class="literal">FOR NO KEY UPDATE</code>
+ </span></dt><dd><p>
+ Behaves similarly to <code class="literal">FOR UPDATE</code>, except that the lock
+ acquired is weaker: this lock will not block
+ <code class="literal">SELECT FOR KEY SHARE</code> commands that attempt to acquire
+ a lock on the same rows. This lock mode is also acquired by any
+ <code class="command">UPDATE</code> that does not acquire a <code class="literal">FOR UPDATE</code> lock.
+ </p></dd><dt><span class="term">
+ <code class="literal">FOR SHARE</code>
+ </span></dt><dd><p>
+ Behaves similarly to <code class="literal">FOR NO KEY UPDATE</code>, except that it
+ acquires a shared lock rather than exclusive lock on each retrieved
+ row. A shared lock blocks other transactions from performing
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">SELECT FOR UPDATE</code> or
+ <code class="command">SELECT FOR NO KEY UPDATE</code> on these rows, but it does not
+ prevent them from performing <code class="command">SELECT FOR SHARE</code> or
+ <code class="command">SELECT FOR KEY SHARE</code>.
+ </p></dd><dt><span class="term">
+ <code class="literal">FOR KEY SHARE</code>
+ </span></dt><dd><p>
+ Behaves similarly to <code class="literal">FOR SHARE</code>, except that the
+ lock is weaker: <code class="literal">SELECT FOR UPDATE</code> is blocked, but not
+ <code class="literal">SELECT FOR NO KEY UPDATE</code>. A key-shared lock blocks
+ other transactions from performing <code class="command">DELETE</code> or
+ any <code class="command">UPDATE</code> that changes the key values, but not
+ other <code class="command">UPDATE</code>, and neither does it prevent
+ <code class="command">SELECT FOR NO KEY UPDATE</code>, <code class="command">SELECT FOR SHARE</code>,
+ or <code class="command">SELECT FOR KEY SHARE</code>.
+ </p></dd></dl></div><p>
+ <span class="productname">PostgreSQL</span> doesn't remember any
+ information about modified rows in memory, so there is no limit on
+ the number of rows locked at one time. However, locking a row
+ might cause a disk write, e.g., <code class="command">SELECT FOR
+ UPDATE</code> modifies selected rows to mark them locked, and so
+ will result in disk writes.
+ </p><div class="table" id="ROW-LOCK-COMPATIBILITY"><p class="title"><strong>Table 13.3. Conflicting Row-Level Locks</strong></p><div class="table-contents"><table class="table" summary="Conflicting Row-Level Locks" border="1"><colgroup><col class="col1" /><col class="lockst" /><col class="col3" /><col class="col4" /><col class="lockend" /></colgroup><thead><tr><th rowspan="2">Requested Lock Mode</th><th colspan="4">Current Lock Mode</th></tr><tr><th>FOR KEY SHARE</th><th>FOR SHARE</th><th>FOR NO KEY UPDATE</th><th>FOR UPDATE</th></tr></thead><tbody><tr><td>FOR KEY SHARE</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">X</td></tr><tr><td>FOR SHARE</td><td align="center"> </td><td align="center"> </td><td align="center">X</td><td align="center">X</td></tr><tr><td>FOR NO KEY UPDATE</td><td align="center"> </td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td>FOR UPDATE</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="LOCKING-PAGES"><div class="titlepage"><div><div><h3 class="title">13.3.3. Page-Level Locks</h3></div></div></div><p>
+ In addition to table and row locks, page-level share/exclusive locks are
+ used to control read/write access to table pages in the shared buffer
+ pool. These locks are released immediately after a row is fetched or
+ updated. Application developers normally need not be concerned with
+ page-level locks, but they are mentioned here for completeness.
+ </p></div><div class="sect2" id="LOCKING-DEADLOCKS"><div class="titlepage"><div><div><h3 class="title">13.3.4. Deadlocks</h3></div></div></div><a id="id-1.5.12.6.8.2" class="indexterm"></a><p>
+ The use of explicit locking can increase the likelihood of
+ <em class="firstterm">deadlocks</em>, wherein two (or more) transactions each
+ hold locks that the other wants. For example, if transaction 1
+ acquires an exclusive lock on table A and then tries to acquire
+ an exclusive lock on table B, while transaction 2 has already
+ exclusive-locked table B and now wants an exclusive lock on table
+ A, then neither one can proceed.
+ <span class="productname">PostgreSQL</span> automatically detects
+ deadlock situations and resolves them by aborting one of the
+ transactions involved, allowing the other(s) to complete.
+ (Exactly which transaction will be aborted is difficult to
+ predict and should not be relied upon.)
+ </p><p>
+ Note that deadlocks can also occur as the result of row-level
+ locks (and thus, they can occur even if explicit locking is not
+ used). Consider the case in which two concurrent
+ transactions modify a table. The first transaction executes:
+
+</p><pre class="screen">
+UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 11111;
+</pre><p>
+
+ This acquires a row-level lock on the row with the specified
+ account number. Then, the second transaction executes:
+
+</p><pre class="screen">
+UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 22222;
+UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 11111;
+</pre><p>
+
+ The first <code class="command">UPDATE</code> statement successfully
+ acquires a row-level lock on the specified row, so it succeeds in
+ updating that row. However, the second <code class="command">UPDATE</code>
+ statement finds that the row it is attempting to update has
+ already been locked, so it waits for the transaction that
+ acquired the lock to complete. Transaction two is now waiting on
+ transaction one to complete before it continues execution. Now,
+ transaction one executes:
+
+</p><pre class="screen">
+UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
+</pre><p>
+
+ Transaction one attempts to acquire a row-level lock on the
+ specified row, but it cannot: transaction two already holds such
+ a lock. So it waits for transaction two to complete. Thus,
+ transaction one is blocked on transaction two, and transaction
+ two is blocked on transaction one: a deadlock
+ condition. <span class="productname">PostgreSQL</span> will detect this
+ situation and abort one of the transactions.
+ </p><p>
+ The best defense against deadlocks is generally to avoid them by
+ being certain that all applications using a database acquire
+ locks on multiple objects in a consistent order. In the example
+ above, if both transactions
+ had updated the rows in the same order, no deadlock would have
+ occurred. One should also ensure that the first lock acquired on
+ an object in a transaction is the most restrictive mode that will be
+ needed for that object. If it is not feasible to verify this in
+ advance, then deadlocks can be handled on-the-fly by retrying
+ transactions that abort due to deadlocks.
+ </p><p>
+ So long as no deadlock situation is detected, a transaction seeking
+ either a table-level or row-level lock will wait indefinitely for
+ conflicting locks to be released. This means it is a bad idea for
+ applications to hold transactions open for long periods of time
+ (e.g., while waiting for user input).
+ </p></div><div class="sect2" id="ADVISORY-LOCKS"><div class="titlepage"><div><div><h3 class="title">13.3.5. Advisory Locks</h3></div></div></div><a id="id-1.5.12.6.9.2" class="indexterm"></a><a id="id-1.5.12.6.9.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a means for
+ creating locks that have application-defined meanings. These are
+ called <em class="firstterm">advisory locks</em>, because the system does not
+ enforce their use — it is up to the application to use them
+ correctly. Advisory locks can be useful for locking strategies
+ that are an awkward fit for the MVCC model.
+ For example, a common use of advisory locks is to emulate pessimistic
+ locking strategies typical of so-called <span class="quote">“<span class="quote">flat file</span>”</span> data
+ management systems.
+ While a flag stored in a table could be used for the same purpose,
+ advisory locks are faster, avoid table bloat, and are automatically
+ cleaned up by the server at the end of the session.
+ </p><p>
+ There are two ways to acquire an advisory lock in
+ <span class="productname">PostgreSQL</span>: at session level or at
+ transaction level.
+ Once acquired at session level, an advisory lock is held until
+ explicitly released or the session ends. Unlike standard lock requests,
+ session-level advisory lock requests do not honor transaction semantics:
+ a lock acquired during a transaction that is later rolled back will still
+ be held following the rollback, and likewise an unlock is effective even
+ if the calling transaction fails later. A lock can be acquired multiple
+ times by its owning process; for each completed lock request there must
+ be a corresponding unlock request before the lock is actually released.
+ Transaction-level lock requests, on the other hand, behave more like
+ regular lock requests: they are automatically released at the end of the
+ transaction, and there is no explicit unlock operation. This behavior
+ is often more convenient than the session-level behavior for short-term
+ usage of an advisory lock.
+ Session-level and transaction-level lock requests for the same advisory
+ lock identifier will block each other in the expected way.
+ If a session already holds a given advisory lock, additional requests by
+ it will always succeed, even if other sessions are awaiting the lock; this
+ statement is true regardless of whether the existing lock hold and new
+ request are at session level or transaction level.
+ </p><p>
+ Like all locks in
+ <span class="productname">PostgreSQL</span>, a complete list of advisory locks
+ currently held by any session can be found in the <a class="link" href="view-pg-locks.html" title="54.12. pg_locks"><code class="structname">pg_locks</code></a> system
+ view.
+ </p><p>
+ Both advisory locks and regular locks are stored in a shared memory
+ pool whose size is defined by the configuration variables
+ <a class="xref" href="runtime-config-locks.html#GUC-MAX-LOCKS-PER-TRANSACTION">max_locks_per_transaction</a> and
+ <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>.
+ Care must be taken not to exhaust this
+ memory or the server will be unable to grant any locks at all.
+ This imposes an upper limit on the number of advisory locks
+ grantable by the server, typically in the tens to hundreds of thousands
+ depending on how the server is configured.
+ </p><p>
+ In certain cases using advisory locking methods, especially in queries
+ involving explicit ordering and <code class="literal">LIMIT</code> clauses, care must be
+ taken to control the locks acquired because of the order in which SQL
+ expressions are evaluated. For example:
+</p><pre class="screen">
+SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
+SELECT pg_advisory_lock(id) FROM foo WHERE id &gt; 12345 LIMIT 100; -- danger!
+SELECT pg_advisory_lock(q.id) FROM
+(
+ SELECT id FROM foo WHERE id &gt; 12345 LIMIT 100
+) q; -- ok
+</pre><p>
+ In the above queries, the second form is dangerous because the
+ <code class="literal">LIMIT</code> is not guaranteed to be applied before the locking
+ function is executed. This might cause some locks to be acquired
+ that the application was not expecting, and hence would fail to release
+ (until it ends the session).
+ From the point of view of the application, such locks
+ would be dangling, although still viewable in
+ <code class="structname">pg_locks</code>.
+ </p><p>
+ The functions provided to manipulate advisory locks are described in
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS" title="9.27.10. Advisory Lock Functions">Section 9.27.10</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="transaction-iso.html" title="13.2. Transaction Isolation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.2. Transaction Isolation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.4. Data Consistency Checks at the Application Level</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/extend-extensions.html b/doc/src/sgml/html/extend-extensions.html
new file mode 100644
index 0000000..7c68f3e
--- /dev/null
+++ b/doc/src/sgml/html/extend-extensions.html
@@ -0,0 +1,626 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.17. Packaging Related Objects into an Extension</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xindex.html" title="38.16. Interfacing Extensions to Indexes" /><link rel="next" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.17. Packaging Related Objects into an Extension</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-EXTENSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.17. Packaging Related Objects into an Extension</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.11">38.17.1. Extension Files</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-RELOCATION">38.17.2. Extension Relocatability</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-CONFIG-TABLES">38.17.3. Extension Configuration Tables</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.14">38.17.4. Extension Updates</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.15">38.17.5. Installing Extensions Using Update Scripts</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-SECURITY">38.17.6. Security Considerations for Extensions</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE">38.17.7. Extension Example</a></span></dt></dl></div><a id="id-1.8.3.20.2" class="indexterm"></a><p>
+ A useful extension to <span class="productname">PostgreSQL</span> typically includes
+ multiple SQL objects; for example, a new data type will require new
+ functions, new operators, and probably new index operator classes.
+ It is helpful to collect all these objects into a single package
+ to simplify database management. <span class="productname">PostgreSQL</span> calls
+ such a package an <em class="firstterm">extension</em>. To define an extension,
+ you need at least a <em class="firstterm">script file</em> that contains the
+ <acronym class="acronym">SQL</acronym> commands to create the extension's objects, and a
+ <em class="firstterm">control file</em> that specifies a few basic properties
+ 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
+ <a class="link" href="sql-createextension.html" title="CREATE EXTENSION"><code class="command">CREATE EXTENSION</code></a> command loads the objects into
+ your database.
+ </p><p>
+ The main advantage of using an extension, rather than just running the
+ <acronym class="acronym">SQL</acronym> script to load a bunch of <span class="quote">“<span class="quote">loose</span>”</span> objects
+ into your database, is that <span class="productname">PostgreSQL</span> will then
+ understand that the objects of the extension go together. You can
+ drop all the objects with a single <a class="link" href="sql-dropextension.html" title="DROP EXTENSION"><code class="command">DROP EXTENSION</code></a>
+ command (no need to maintain a separate <span class="quote">“<span class="quote">uninstall</span>”</span> script).
+ Even more useful, <span class="application">pg_dump</span> knows that it should not
+ dump the individual member objects of the extension — it will
+ just include a <code class="command">CREATE EXTENSION</code> command in dumps, instead.
+ This vastly simplifies migration to a new version of the extension
+ that might contain more or different objects than the old version.
+ Note however that you must have the extension's control, script, and
+ other files available when loading such a dump into a new database.
+ </p><p>
+ <span class="productname">PostgreSQL</span> will not let you drop an individual object
+ contained in an extension, except by dropping the whole extension.
+ Also, while you can change the definition of an extension member object
+ (for example, via <code class="command">CREATE OR REPLACE FUNCTION</code> for a
+ function), bear in mind that the modified definition will not be dumped
+ by <span class="application">pg_dump</span>. 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 <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-CONFIG-TABLES" title="38.17.3. Extension Configuration Tables">Section 38.17.3</a>.)
+ In production situations, it's generally better to create an extension
+ update script to perform changes to extension member objects.
+ </p><p>
+ The extension script may set privileges on objects that are part of the
+ extension, using <code class="command">GRANT</code> and <code class="command">REVOKE</code>
+ statements. The final set of privileges for each object (if any are set)
+ will be stored in the
+ <a class="link" href="catalog-pg-init-privs.html" title="53.28. pg_init_privs"><code class="structname">pg_init_privs</code></a>
+ system catalog. When <span class="application">pg_dump</span> is used, the
+ <code class="command">CREATE EXTENSION</code> command will be included in the dump, followed
+ by the set of <code class="command">GRANT</code> and <code class="command">REVOKE</code>
+ statements necessary to set the privileges on the objects to what they were
+ at the time the dump was taken.
+ </p><p>
+ <span class="productname">PostgreSQL</span> does not currently support extension scripts
+ issuing <code class="command">CREATE POLICY</code> or <code class="command">SECURITY LABEL</code>
+ statements. These are expected to be set after the extension has been
+ created. All RLS policies and security labels on extension objects will be
+ included in dumps created by <span class="application">pg_dump</span>.
+ </p><p>
+ The extension mechanism also has provisions for packaging modification
+ scripts that adjust the definitions of the SQL objects contained in an
+ extension. For example, if version 1.1 of an extension adds one function
+ and changes the body of another function compared to 1.0, the extension
+ author can provide an <em class="firstterm">update script</em> that makes just those
+ two changes. The <code class="command">ALTER EXTENSION UPDATE</code> command can then
+ be used to apply these changes and track which version of the extension
+ is actually installed in a given database.
+ </p><p>
+ The kinds of SQL objects that can be members of an extension are shown in
+ the description of <a class="link" href="sql-alterextension.html" title="ALTER EXTENSION"><code class="command">ALTER EXTENSION</code></a>. 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
+ such objects, if it does so they will not be tracked as part of the
+ extension.) Also notice that while a table can be a member of an
+ extension, its subsidiary objects such as indexes are not directly
+ considered members of the extension.
+ Another important point is that schemas can belong to extensions, but not
+ vice versa: an extension as such has an unqualified name and does not
+ exist <span class="quote">“<span class="quote">within</span>”</span> any schema. The extension's member objects,
+ however, will belong to schemas whenever appropriate for their object
+ types. It may or may not be appropriate for an extension to own the
+ schema(s) its member objects are within.
+ </p><p>
+ If an extension's script creates any temporary objects (such as temp
+ tables), those objects are treated as extension members for the
+ remainder of the current session, but are automatically dropped at
+ session end, as any temporary object would be. This is an exception
+ to the rule that extension member objects cannot be dropped without
+ dropping the whole extension.
+ </p><div class="sect2" id="id-1.8.3.20.11"><div class="titlepage"><div><div><h3 class="title">38.17.1. Extension Files</h3></div></div></div><a id="id-1.8.3.20.11.2" class="indexterm"></a><p>
+ The <code class="command">CREATE EXTENSION</code> command relies on a control
+ file for each extension, which must be named the same as the extension
+ with a suffix of <code class="literal">.control</code>, and must be placed in the
+ installation's <code class="literal">SHAREDIR/extension</code> directory. There
+ must also be at least one <acronym class="acronym">SQL</acronym> script file, which follows the
+ naming pattern
+ <code class="literal"><em class="replaceable"><code>extension</code></em>--<em class="replaceable"><code>version</code></em>.sql</code>
+ (for example, <code class="literal">foo--1.0.sql</code> for version <code class="literal">1.0</code> of
+ extension <code class="literal">foo</code>). By default, the script file(s) are also
+ placed in the <code class="literal">SHAREDIR/extension</code> directory; but the
+ control file can specify a different directory for the script file(s).
+ </p><p>
+ The file format for an extension control file is the same as for the
+ <code class="filename">postgresql.conf</code> file, namely a list of
+ <em class="replaceable"><code>parameter_name</code></em> <code class="literal">=</code> <em class="replaceable"><code>value</code></em>
+ assignments, one per line. Blank lines and comments introduced by
+ <code class="literal">#</code> are allowed. Be sure to quote any value that is not
+ a single word or number.
+ </p><p>
+ A control file can set the following parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">directory</code> (<code class="type">string</code>)</span></dt><dd><p>
+ The directory containing the extension's <acronym class="acronym">SQL</acronym> script
+ file(s). Unless an absolute path is given, the name is relative to
+ the installation's <code class="literal">SHAREDIR</code> directory. The
+ default behavior is equivalent to specifying
+ <code class="literal">directory = 'extension'</code>.
+ </p></dd><dt><span class="term"><code class="varname">default_version</code> (<code class="type">string</code>)</span></dt><dd><p>
+ The default version of the extension (the one that will be installed
+ if no version is specified in <code class="command">CREATE EXTENSION</code>). Although
+ this can be omitted, that will result in <code class="command">CREATE EXTENSION</code>
+ failing if no <code class="literal">VERSION</code> option appears, so you generally
+ don't want to do that.
+ </p></dd><dt><span class="term"><code class="varname">comment</code> (<code class="type">string</code>)</span></dt><dd><p>
+ A comment (any string) about the extension. The comment is applied
+ when initially creating an extension, but not during extension updates
+ (since that might override user-added comments). Alternatively,
+ the extension's comment can be set by writing
+ a <a class="xref" href="sql-comment.html" title="COMMENT"><span class="refentrytitle">COMMENT</span></a> command in the script file.
+ </p></dd><dt><span class="term"><code class="varname">encoding</code> (<code class="type">string</code>)</span></dt><dd><p>
+ The character set encoding used by the script file(s). This should
+ be specified if the script files contain any non-ASCII characters.
+ Otherwise the files will be assumed to be in the database encoding.
+ </p></dd><dt><span class="term"><code class="varname">module_pathname</code> (<code class="type">string</code>)</span></dt><dd><p>
+ The value of this parameter will be substituted for each occurrence
+ of <code class="literal">MODULE_PATHNAME</code> in the script file(s). If it is not
+ set, no substitution is made. Typically, this is set to
+ <code class="literal">$libdir/<em class="replaceable"><code>shared_library_name</code></em></code> and
+ then <code class="literal">MODULE_PATHNAME</code> is used in <code class="command">CREATE
+ FUNCTION</code> commands for C-language functions, so that the script
+ files do not need to hard-wire the name of the shared library.
+ </p></dd><dt><span class="term"><code class="varname">requires</code> (<code class="type">string</code>)</span></dt><dd><p>
+ A list of names of extensions that this extension depends on,
+ for example <code class="literal">requires = 'foo, bar'</code>. Those
+ extensions must be installed before this one can be installed.
+ </p></dd><dt><span class="term"><code class="varname">superuser</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ If this parameter is <code class="literal">true</code> (which is the default),
+ only superusers can create the extension or update it to a new
+ version (but see also <code class="varname">trusted</code>, below).
+ If it is set to <code class="literal">false</code>, just the privileges
+ required to execute the commands in the installation or update script
+ are required.
+ This should normally be set to <code class="literal">true</code> if any of the
+ script commands require superuser privileges. (Such commands would
+ fail anyway, but it's more user-friendly to give the error up front.)
+ </p></dd><dt><span class="term"><code class="varname">trusted</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This parameter, if set to <code class="literal">true</code> (which is not the
+ default), allows some non-superusers to install an extension that
+ has <code class="varname">superuser</code> set to <code class="literal">true</code>.
+ Specifically, installation will be permitted for anyone who has
+ <code class="literal">CREATE</code> privilege on the current database.
+ When the user executing <code class="command">CREATE EXTENSION</code> is not
+ a superuser but is allowed to install by virtue of this parameter,
+ then the installation or update script is run as the bootstrap
+ superuser, not as the calling user.
+ This parameter is irrelevant if <code class="varname">superuser</code> is
+ <code class="literal">false</code>.
+ Generally, this should not be set true for extensions that could
+ allow access to otherwise-superuser-only abilities, such as
+ file system access.
+ Also, marking an extension trusted requires significant extra effort
+ to write the extension's installation and update script(s) securely;
+ see <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-SECURITY" title="38.17.6. Security Considerations for Extensions">Section 38.17.6</a>.
+ </p></dd><dt><span class="term"><code class="varname">relocatable</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ An extension is <em class="firstterm">relocatable</em> if it is possible to move
+ its contained objects into a different schema after initial creation
+ of the extension. The default is <code class="literal">false</code>, i.e., the
+ extension is not relocatable.
+ See <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-RELOCATION" title="38.17.2. Extension Relocatability">Section 38.17.2</a> for more information.
+ </p></dd><dt><span class="term"><code class="varname">schema</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This parameter can only be set for non-relocatable extensions.
+ It forces the extension to be loaded into exactly the named schema
+ and not any other.
+ The <code class="varname">schema</code> parameter is consulted only when
+ initially creating an extension, not during extension updates.
+ See <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-RELOCATION" title="38.17.2. Extension Relocatability">Section 38.17.2</a> for more information.
+ </p></dd></dl></div><p>
+ In addition to the primary control file
+ <code class="literal"><em class="replaceable"><code>extension</code></em>.control</code>,
+ an extension can have secondary control files named in the style
+ <code class="literal"><em class="replaceable"><code>extension</code></em>--<em class="replaceable"><code>version</code></em>.control</code>.
+ If supplied, these must be located in the script file directory.
+ Secondary control files follow the same format as the primary control
+ file. Any parameters set in a secondary control file override the
+ primary control file when installing or updating to that version of
+ the extension. However, the parameters <code class="varname">directory</code> and
+ <code class="varname">default_version</code> cannot be set in a secondary control file.
+ </p><p>
+ An extension's <acronym class="acronym">SQL</acronym> script files can contain any SQL commands,
+ except for transaction control commands (<code class="command">BEGIN</code>,
+ <code class="command">COMMIT</code>, etc.) and commands that cannot be executed inside a
+ transaction block (such as <code class="command">VACUUM</code>). This is because the
+ script files are implicitly executed within a transaction block.
+ </p><p>
+ An extension's <acronym class="acronym">SQL</acronym> script files can also contain lines
+ beginning with <code class="literal">\echo</code>, which will be ignored (treated as
+ comments) by the extension mechanism. This provision is commonly used
+ to throw an error if the script file is fed to <span class="application">psql</span>
+ rather than being loaded via <code class="command">CREATE EXTENSION</code> (see example
+ script in <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE" title="38.17.7. Extension Example">Section 38.17.7</a>).
+ Without that, users might accidentally load the
+ extension's contents as <span class="quote">“<span class="quote">loose</span>”</span> objects rather than as an
+ extension, a state of affairs that's a bit tedious to recover from.
+ </p><p>
+ If the extension script contains the
+ string <code class="literal">@extowner@</code>, that string is replaced with the
+ (suitably quoted) name of the user calling <code class="command">CREATE
+ EXTENSION</code> or <code class="command">ALTER EXTENSION</code>. Typically
+ this feature is used by extensions that are marked trusted to assign
+ ownership of selected objects to the calling user rather than the
+ bootstrap superuser. (One should be careful about doing so, however.
+ For example, assigning ownership of a C-language function to a
+ non-superuser would create a privilege escalation path for that user.)
+ </p><p>
+ While the script files can contain any characters allowed by the specified
+ encoding, control files should contain only plain ASCII, because there
+ is no way for <span class="productname">PostgreSQL</span> to know what encoding a
+ control file is in. In practice this is only an issue if you want to
+ use non-ASCII characters in the extension's comment. Recommended
+ practice in that case is to not use the control file <code class="varname">comment</code>
+ parameter, but instead use <code class="command">COMMENT ON EXTENSION</code>
+ within a script file to set the comment.
+ </p></div><div class="sect2" id="EXTEND-EXTENSIONS-RELOCATION"><div class="titlepage"><div><div><h3 class="title">38.17.2. Extension Relocatability</h3></div></div></div><p>
+ Users often wish to load the objects contained in an extension into a
+ different schema than the extension's author had in mind. There are
+ three supported levels of relocatability:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A fully relocatable extension can be moved into another schema
+ at any time, even after it's been loaded into a database.
+ This is done with the <code class="command">ALTER EXTENSION SET SCHEMA</code>
+ command, which automatically renames all the member objects into
+ the new schema. Normally, this is only possible if the extension
+ contains no internal assumptions about what schema any of its
+ objects are in. Also, the extension's objects must all be in one
+ schema to begin with (ignoring objects that do not belong to any
+ schema, such as procedural languages). Mark a fully relocatable
+ extension by setting <code class="literal">relocatable = true</code> in its control
+ file.
+ </p></li><li class="listitem"><p>
+ An extension might be relocatable during installation but not
+ afterwards. This is typically the case if the extension's script
+ file needs to reference the target schema explicitly, for example
+ in setting <code class="literal">search_path</code> properties for SQL functions.
+ For such an extension, set <code class="literal">relocatable = false</code> in its
+ control file, and use <code class="literal">@extschema@</code> to refer to the target
+ schema in the script file. All occurrences of this string will be
+ replaced by the actual target schema's name before the script is
+ executed. The user can set the target schema using the
+ <code class="literal">SCHEMA</code> option of <code class="command">CREATE EXTENSION</code>.
+ </p></li><li class="listitem"><p>
+ If the extension does not support relocation at all, set
+ <code class="literal">relocatable = false</code> in its control file, and also set
+ <code class="literal">schema</code> to the name of the intended target schema. This
+ will prevent use of the <code class="literal">SCHEMA</code> option of <code class="command">CREATE
+ EXTENSION</code>, unless it specifies the same schema named in the control
+ file. This choice is typically necessary if the extension contains
+ internal assumptions about schema names that can't be replaced by
+ uses of <code class="literal">@extschema@</code>. The <code class="literal">@extschema@</code>
+ substitution mechanism is available in this case too, although it is
+ of limited use since the schema name is determined by the control file.
+ </p></li></ul></div><p>
+ In all cases, the script file will be executed with
+ <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> initially set to point to the target
+ schema; that is, <code class="command">CREATE EXTENSION</code> does the equivalent of
+ this:
+</p><pre class="programlisting">
+SET LOCAL search_path TO @extschema@, pg_temp;
+</pre><p>
+ This allows the objects created by the script file to go into the target
+ schema. The script file can change <code class="varname">search_path</code> if it wishes,
+ but that is generally undesirable. <code class="varname">search_path</code> is restored
+ to its previous setting upon completion of <code class="command">CREATE EXTENSION</code>.
+ </p><p>
+ The target schema is determined by the <code class="varname">schema</code> parameter in
+ the control file if that is given, otherwise by the <code class="literal">SCHEMA</code>
+ option of <code class="command">CREATE EXTENSION</code> if that is given, otherwise the
+ current default object creation schema (the first one in the caller's
+ <code class="varname">search_path</code>). When the control file <code class="varname">schema</code>
+ parameter is used, the target schema will be created if it doesn't
+ already exist, but in the other two cases it must already exist.
+ </p><p>
+ If any prerequisite extensions are listed in <code class="varname">requires</code>
+ in the control file, their target schemas are added to the initial
+ setting of <code class="varname">search_path</code>, following the new
+ extension's target schema. This allows their objects to be visible to
+ the new extension's script file.
+ </p><p>
+ For security, <code class="literal">pg_temp</code> is automatically appended to
+ the end of <code class="varname">search_path</code> in all cases.
+ </p><p>
+ Although a non-relocatable extension can contain objects spread across
+ multiple schemas, it is usually desirable to place all the objects meant
+ for external use into a single schema, which is considered the extension's
+ target schema. Such an arrangement works conveniently with the default
+ setting of <code class="varname">search_path</code> during creation of dependent
+ extensions.
+ </p></div><div class="sect2" id="EXTEND-EXTENSIONS-CONFIG-TABLES"><div class="titlepage"><div><div><h3 class="title">38.17.3. Extension Configuration Tables</h3></div></div></div><p>
+ Some extensions include configuration tables, which contain data that
+ might be added or changed by the user after installation of the
+ extension. Ordinarily, if a table is part of an extension, neither
+ the table's definition nor its content will be dumped by
+ <span class="application">pg_dump</span>. But that behavior is undesirable for a
+ configuration table; any data changes made by the user need to be
+ included in dumps, or the extension will behave differently after a dump
+ and restore.
+ </p><a id="id-1.8.3.20.13.3" class="indexterm"></a><p>
+ To solve this problem, an extension's script file can mark a table
+ or a sequence it has created as a configuration relation, which will
+ cause <span class="application">pg_dump</span> to include the table's or the sequence's
+ contents (not its definition) in dumps. To do that, call the function
+ <code class="function">pg_extension_config_dump(regclass, text)</code> after creating the
+ table or the sequence, for example
+</p><pre class="programlisting">
+CREATE TABLE my_config (key text, value text);
+CREATE SEQUENCE my_config_seq;
+
+SELECT pg_catalog.pg_extension_config_dump('my_config', '');
+SELECT pg_catalog.pg_extension_config_dump('my_config_seq', '');
+</pre><p>
+ Any number of tables or sequences can be marked this way. Sequences
+ associated with <code class="type">serial</code> or <code class="type">bigserial</code> columns can
+ be marked as well.
+ </p><p>
+ When the second argument of <code class="function">pg_extension_config_dump</code> is
+ an empty string, the entire contents of the table are dumped by
+ <span class="application">pg_dump</span>. This is usually only correct if the table
+ is initially empty as created by the extension script. If there is
+ a mixture of initial data and user-provided data in the table,
+ the second argument of <code class="function">pg_extension_config_dump</code> provides
+ a <code class="literal">WHERE</code> condition that selects the data to be dumped.
+ For example, you might do
+</p><pre class="programlisting">
+CREATE TABLE my_config (key text, value text, standard_entry boolean);
+
+SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');
+</pre><p>
+ and then make sure that <code class="structfield">standard_entry</code> is true only
+ in the rows created by the extension's script.
+ </p><p>
+ For sequences, the second argument of <code class="function">pg_extension_config_dump</code>
+ has no effect.
+ </p><p>
+ More complicated situations, such as initially-provided rows that might
+ be modified by users, can be handled by creating triggers on the
+ configuration table to ensure that modified rows are marked correctly.
+ </p><p>
+ You can alter the filter condition associated with a configuration table
+ by calling <code class="function">pg_extension_config_dump</code> again. (This would
+ typically be useful in an extension update script.) The only way to mark
+ a table as no longer a configuration table is to dissociate it from the
+ extension with <code class="command">ALTER EXTENSION ... DROP TABLE</code>.
+ </p><p>
+ Note that foreign key relationships between these tables will dictate the
+ order in which the tables are dumped out by pg_dump. Specifically, pg_dump
+ will attempt to dump the referenced-by table before the referencing table.
+ As the foreign key relationships are set up at CREATE EXTENSION time (prior
+ to data being loaded into the tables) circular dependencies are not
+ supported. When circular dependencies exist, the data will still be dumped
+ out but the dump will not be able to be restored directly and user
+ intervention will be required.
+ </p><p>
+ Sequences associated with <code class="type">serial</code> or <code class="type">bigserial</code> columns
+ need to be directly marked to dump their state. Marking their parent
+ relation is not enough for this purpose.
+ </p></div><div class="sect2" id="id-1.8.3.20.14"><div class="titlepage"><div><div><h3 class="title">38.17.4. Extension Updates</h3></div></div></div><p>
+ One advantage of the extension mechanism is that it provides convenient
+ ways to manage updates to the SQL commands that define an extension's
+ objects. This is done by associating a version name or number with
+ each released version of the extension's installation script.
+ In addition, if you want users to be able to update their databases
+ dynamically from one version to the next, you should provide
+ <em class="firstterm">update scripts</em> that make the necessary changes to go from
+ one version to the next. Update scripts have names following the pattern
+ <code class="literal"><em class="replaceable"><code>extension</code></em>--<em class="replaceable"><code>old_version</code></em>--<em class="replaceable"><code>target_version</code></em>.sql</code>
+ (for example, <code class="literal">foo--1.0--1.1.sql</code> contains the commands to modify
+ version <code class="literal">1.0</code> of extension <code class="literal">foo</code> into version
+ <code class="literal">1.1</code>).
+ </p><p>
+ Given that a suitable update script is available, the command
+ <code class="command">ALTER EXTENSION UPDATE</code> will update an installed extension
+ to the specified new version. The update script is run in the same
+ environment that <code class="command">CREATE EXTENSION</code> provides for installation
+ scripts: in particular, <code class="varname">search_path</code> is set up in the same
+ way, and any new objects created by the script are automatically added
+ to the extension. Also, if the script chooses to drop extension member
+ objects, they are automatically dissociated from the extension.
+ </p><p>
+ If an extension has secondary control files, the control parameters
+ that are used for an update script are those associated with the script's
+ target (new) version.
+ </p><p>
+ <code class="command">ALTER EXTENSION</code> is able to execute sequences of update
+ script files to achieve a requested update. For example, if only
+ <code class="literal">foo--1.0--1.1.sql</code> and <code class="literal">foo--1.1--2.0.sql</code> are
+ available, <code class="command">ALTER EXTENSION</code> will apply them in sequence if an
+ update to version <code class="literal">2.0</code> is requested when <code class="literal">1.0</code> is
+ currently installed.
+ </p><p>
+ <span class="productname">PostgreSQL</span> doesn't assume anything about the properties
+ of version names: for example, it does not know whether <code class="literal">1.1</code>
+ follows <code class="literal">1.0</code>. It just matches up the available version names
+ and follows the path that requires applying the fewest update scripts.
+ (A version name can actually be any string that doesn't contain
+ <code class="literal">--</code> or leading or trailing <code class="literal">-</code>.)
+ </p><p>
+ Sometimes it is useful to provide <span class="quote">“<span class="quote">downgrade</span>”</span> scripts, for
+ example <code class="literal">foo--1.1--1.0.sql</code> to allow reverting the changes
+ associated with version <code class="literal">1.1</code>. If you do that, be careful
+ of the possibility that a downgrade script might unexpectedly
+ get applied because it yields a shorter path. The risky case is where
+ there is a <span class="quote">“<span class="quote">fast path</span>”</span> update script that jumps ahead several
+ versions as well as a downgrade script to the fast path's start point.
+ It might take fewer steps to apply the downgrade and then the fast
+ path than to move ahead one version at a time. If the downgrade script
+ drops any irreplaceable objects, this will yield undesirable results.
+ </p><p>
+ To check for unexpected update paths, use this command:
+</p><pre class="programlisting">
+SELECT * FROM pg_extension_update_paths('<em class="replaceable"><code>extension_name</code></em>');
+</pre><p>
+ This shows each pair of distinct known version names for the specified
+ extension, together with the update path sequence that would be taken to
+ get from the source version to the target version, or <code class="literal">NULL</code> if
+ there is no available update path. The path is shown in textual form
+ with <code class="literal">--</code> separators. You can use
+ <code class="literal">regexp_split_to_array(path,'--')</code> if you prefer an array
+ format.
+ </p></div><div class="sect2" id="id-1.8.3.20.15"><div class="titlepage"><div><div><h3 class="title">38.17.5. Installing Extensions Using Update Scripts</h3></div></div></div><p>
+ An extension that has been around for awhile will probably exist in
+ several versions, for which the author will need to write update scripts.
+ For example, if you have released a <code class="literal">foo</code> extension in
+ versions <code class="literal">1.0</code>, <code class="literal">1.1</code>, and <code class="literal">1.2</code>, there
+ should be update scripts <code class="filename">foo--1.0--1.1.sql</code>
+ and <code class="filename">foo--1.1--1.2.sql</code>.
+ Before <span class="productname">PostgreSQL</span> 10, it was necessary to also create
+ new script files <code class="filename">foo--1.1.sql</code> and <code class="filename">foo--1.2.sql</code>
+ that directly build the newer extension versions, or else the newer
+ versions could not be installed directly, only by
+ installing <code class="literal">1.0</code> and then updating. That was tedious and
+ duplicative, but now it's unnecessary, because <code class="command">CREATE
+ EXTENSION</code> can follow update chains automatically.
+ For example, if only the script
+ files <code class="filename">foo--1.0.sql</code>, <code class="filename">foo--1.0--1.1.sql</code>,
+ and <code class="filename">foo--1.1--1.2.sql</code> are available then a request to
+ install version <code class="literal">1.2</code> is honored by running those three
+ scripts in sequence. The processing is the same as if you'd first
+ installed <code class="literal">1.0</code> and then updated to <code class="literal">1.2</code>.
+ (As with <code class="command">ALTER EXTENSION UPDATE</code>, if multiple pathways are
+ available then the shortest is preferred.) Arranging an extension's
+ script files in this style can reduce the amount of maintenance effort
+ needed to produce small updates.
+ </p><p>
+ If you use secondary (version-specific) control files with an extension
+ maintained in this style, keep in mind that each version needs a control
+ file even if it has no stand-alone installation script, as that control
+ file will determine how the implicit update to that version is performed.
+ For example, if <code class="filename">foo--1.0.control</code> specifies <code class="literal">requires
+ = 'bar'</code> but <code class="literal">foo</code>'s other control files do not, the
+ extension's dependency on <code class="literal">bar</code> will be dropped when updating
+ from <code class="literal">1.0</code> to another version.
+ </p></div><div class="sect2" id="EXTEND-EXTENSIONS-SECURITY"><div class="titlepage"><div><div><h3 class="title">38.17.6. Security Considerations for Extensions</h3></div></div></div><p>
+ Widely-distributed extensions should assume little about the database
+ they occupy. Therefore, it's appropriate to write functions provided
+ by an extension in a secure style that cannot be compromised by
+ search-path-based attacks.
+ </p><p>
+ An extension that has the <code class="varname">superuser</code> property set to
+ true must also consider security hazards for the actions taken within
+ its installation and update scripts. It is not terribly difficult for
+ a malicious user to create trojan-horse objects that will compromise
+ later execution of a carelessly-written extension script, allowing that
+ user to acquire superuser privileges.
+ </p><p>
+ If an extension is marked <code class="varname">trusted</code>, then its
+ installation schema can be selected by the installing user, who might
+ intentionally use an insecure schema in hopes of gaining superuser
+ privileges. Therefore, a trusted extension is extremely exposed from a
+ security standpoint, and all its script commands must be carefully
+ examined to ensure that no compromise is possible.
+ </p><p>
+ Advice about writing functions securely is provided in
+ <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-SECURITY-FUNCS" title="38.17.6.1. Security Considerations for Extension Functions">Section 38.17.6.1</a> below, and advice
+ about writing installation scripts securely is provided in
+ <a class="xref" href="extend-extensions.html#EXTEND-EXTENSIONS-SECURITY-SCRIPTS" title="38.17.6.2. Security Considerations for Extension Scripts">Section 38.17.6.2</a>.
+ </p><div class="sect3" id="EXTEND-EXTENSIONS-SECURITY-FUNCS"><div class="titlepage"><div><div><h4 class="title">38.17.6.1. Security Considerations for Extension Functions</h4></div></div></div><p>
+ SQL-language and PL-language functions provided by extensions are at
+ risk of search-path-based attacks when they are executed, since
+ parsing of these functions occurs at execution time not creation time.
+ </p><p>
+ The <a class="link" href="sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY" title="Writing SECURITY DEFINER Functions Safely"><code class="command">CREATE
+ FUNCTION</code></a> reference page contains advice about
+ writing <code class="literal">SECURITY DEFINER</code> functions safely. It's
+ good practice to apply those techniques for any function provided by
+ an extension, since the function might be called by a high-privilege
+ user.
+ </p><p>
+ If you cannot set the <code class="varname">search_path</code> to contain only
+ secure schemas, assume that each unqualified name could resolve to an
+ object that a malicious user has defined. Beware of constructs that
+ depend on <code class="varname">search_path</code> implicitly; for
+ example, <code class="token">IN</code>
+ and <code class="literal">CASE <em class="replaceable"><code>expression</code></em> WHEN</code>
+ always select an operator using the search path. In their place, use
+ <code class="literal">OPERATOR(<em class="replaceable"><code>schema</code></em>.=) ANY</code>
+ and <code class="literal">CASE WHEN <em class="replaceable"><code>expression</code></em></code>.
+ </p><p>
+ A general-purpose extension usually should not assume that it's been
+ installed into a secure schema, which means that even schema-qualified
+ references to its own objects are not entirely risk-free. For
+ example, if the extension has defined a
+ function <code class="literal">myschema.myfunc(bigint)</code> then a call such
+ as <code class="literal">myschema.myfunc(42)</code> could be captured by a
+ hostile function <code class="literal">myschema.myfunc(integer)</code>. Be
+ careful that the data types of function and operator parameters exactly
+ match the declared argument types, using explicit casts where necessary.
+ </p></div><div class="sect3" id="EXTEND-EXTENSIONS-SECURITY-SCRIPTS"><div class="titlepage"><div><div><h4 class="title">38.17.6.2. Security Considerations for Extension Scripts</h4></div></div></div><p>
+ An extension installation or update script should be written to guard
+ against search-path-based attacks occurring when the script executes.
+ If an object reference in the script can be made to resolve to some
+ other object than the script author intended, then a compromise might
+ occur immediately, or later when the mis-defined extension object is
+ used.
+ </p><p>
+ DDL commands such as <code class="command">CREATE FUNCTION</code>
+ and <code class="command">CREATE OPERATOR CLASS</code> are generally secure,
+ but beware of any command having a general-purpose expression as a
+ component. For example, <code class="command">CREATE VIEW</code> needs to be
+ vetted, as does a <code class="literal">DEFAULT</code> expression
+ in <code class="command">CREATE FUNCTION</code>.
+ </p><p>
+ Sometimes an extension script might need to execute general-purpose
+ SQL, for example to make catalog adjustments that aren't possible via
+ DDL. Be careful to execute such commands with a
+ secure <code class="varname">search_path</code>; do <span class="emphasis"><em>not</em></span>
+ trust the path provided by <code class="command">CREATE/ALTER EXTENSION</code>
+ to be secure. Best practice is to temporarily
+ set <code class="varname">search_path</code> to <code class="literal">'pg_catalog,
+ pg_temp'</code> and insert references to the extension's
+ installation schema explicitly where needed. (This practice might
+ also be helpful for creating views.) Examples can be found in
+ the <code class="filename">contrib</code> modules in
+ the <span class="productname">PostgreSQL</span> source code distribution.
+ </p><p>
+ Cross-extension references are extremely difficult to make fully
+ secure, partially because of uncertainty about which schema the other
+ extension is in. The hazards are reduced if both extensions are
+ installed in the same schema, because then a hostile object cannot be
+ placed ahead of the referenced extension in the installation-time
+ <code class="varname">search_path</code>. However, no mechanism currently exists
+ to require that. For now, best practice is to not mark an extension
+ trusted if it depends on another one, unless that other one is always
+ installed in <code class="literal">pg_catalog</code>.
+ </p></div></div><div class="sect2" id="EXTEND-EXTENSIONS-EXAMPLE"><div class="titlepage"><div><div><h3 class="title">38.17.7. Extension Example</h3></div></div></div><p>
+ Here is a complete example of an <acronym class="acronym">SQL</acronym>-only
+ extension, a two-element composite type that can store any type of value
+ in its slots, which are named <span class="quote">“<span class="quote">k</span>”</span> and <span class="quote">“<span class="quote">v</span>”</span>. Non-text
+ values are automatically coerced to text for storage.
+ </p><p>
+ The script file <code class="filename">pair--1.0.sql</code> looks like this:
+
+</p><pre class="programlisting">
+-- complain if script is sourced in psql, rather than via CREATE EXTENSION
+\echo Use "CREATE EXTENSION pair" to load this file. \quit
+
+CREATE TYPE pair AS ( k text, v text );
+
+CREATE FUNCTION pair(text, text)
+RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::@extschema@.pair;';
+
+CREATE OPERATOR ~&gt; (LEFTARG = text, RIGHTARG = text, FUNCTION = pair);
+
+-- "SET search_path" is easy to get right, but qualified names perform better.
+CREATE FUNCTION lower(pair)
+RETURNS pair LANGUAGE SQL
+AS 'SELECT ROW(lower($1.k), lower($1.v))::@extschema@.pair;'
+SET search_path = pg_temp;
+
+CREATE FUNCTION pair_concat(pair, pair)
+RETURNS pair LANGUAGE SQL
+AS 'SELECT ROW($1.k OPERATOR(pg_catalog.||) $2.k,
+ $1.v OPERATOR(pg_catalog.||) $2.v)::@extschema@.pair;';
+
+</pre><p>
+ </p><p>
+ The control file <code class="filename">pair.control</code> looks like this:
+
+</p><pre class="programlisting">
+# pair extension
+comment = 'A key/value pair data type'
+default_version = '1.0'
+# cannot be relocatable because of use of @extschema@
+relocatable = false
+</pre><p>
+ </p><p>
+ While you hardly need a makefile to install these two files into the
+ correct directory, you could use a <code class="filename">Makefile</code> containing this:
+
+</p><pre class="programlisting">
+EXTENSION = pair
+DATA = pair--1.0.sql
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)
+</pre><p>
+
+ This makefile relies on <acronym class="acronym">PGXS</acronym>, which is described
+ in <a class="xref" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">Section 38.18</a>. The command <code class="literal">make install</code>
+ will install the control and script files into the correct
+ directory as reported by <span class="application">pg_config</span>.
+ </p><p>
+ Once the files are installed, use the
+ <code class="command">CREATE EXTENSION</code> command to load the objects into
+ any particular database.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.16. Interfacing Extensions to Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.18. Extension Building Infrastructure</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/extend-how.html b/doc/src/sgml/html/extend-how.html
new file mode 100644
index 0000000..e3aeac9
--- /dev/null
+++ b/doc/src/sgml/html/extend-how.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.1. How Extensibility Works</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend.html" title="Chapter 38. Extending SQL" /><link rel="next" href="extend-type-system.html" title="38.2. The PostgreSQL Type System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.1. How Extensibility Works</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend.html" title="Chapter 38. Extending SQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="extend-type-system.html" title="38.2. The PostgreSQL Type System">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-HOW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.1. How Extensibility Works</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> is extensible because its operation is
+ catalog-driven. If you are familiar with standard
+ relational database systems, you know that they store information
+ about databases, tables, columns, etc., in what are
+ commonly known as system catalogs. (Some systems call
+ this the data dictionary.) The catalogs appear to the
+ user as tables like any other, but the <acronym class="acronym">DBMS</acronym> stores
+ its internal bookkeeping in them. One key difference
+ between <span class="productname">PostgreSQL</span> and standard relational database systems is
+ that <span class="productname">PostgreSQL</span> stores much more information in its
+ catalogs: not only information about tables and columns,
+ but also information about data types, functions, access
+ methods, and so on. These tables can be modified by
+ the user, and since <span class="productname">PostgreSQL</span> bases its operation
+ on these tables, this means that <span class="productname">PostgreSQL</span> can be
+ extended by users. By comparison, conventional
+ database systems can only be extended by changing hardcoded
+ procedures in the source code or by loading modules
+ specially written by the <acronym class="acronym">DBMS</acronym> vendor.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> server can moreover
+ incorporate user-written code into itself through dynamic loading.
+ That is, the user can specify an object code file (e.g., a shared
+ library) that implements a new type or function, and
+ <span class="productname">PostgreSQL</span> will load it as required.
+ Code written in <acronym class="acronym">SQL</acronym> is even more trivial to add
+ to the server. This ability to modify its operation <span class="quote">“<span class="quote">on the
+ fly</span>”</span> makes <span class="productname">PostgreSQL</span> uniquely
+ suited for rapid prototyping of new applications and storage
+ structures.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend.html" title="Chapter 38. Extending SQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extend-type-system.html" title="38.2. The PostgreSQL Type System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. Extending <acronym class="acronym">SQL</acronym> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.2. The <span class="productname">PostgreSQL</span> Type System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/extend-pgxs.html b/doc/src/sgml/html/extend-pgxs.html
new file mode 100644
index 0000000..3ca6899
--- /dev/null
+++ b/doc/src/sgml/html/extend-pgxs.html
@@ -0,0 +1,230 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.18. Extension Building Infrastructure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension" /><link rel="next" href="triggers.html" title="Chapter 39. Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.18. Extension Building Infrastructure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 39. Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-PGXS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.18. Extension Building Infrastructure</h2></div></div></div><a id="id-1.8.3.21.2" class="indexterm"></a><p>
+ If you are thinking about distributing your
+ <span class="productname">PostgreSQL</span> extension modules, setting up a
+ portable build system for them can be fairly difficult. Therefore
+ the <span class="productname">PostgreSQL</span> installation provides a build
+ infrastructure for extensions, called <acronym class="acronym">PGXS</acronym>, so
+ that simple extension modules can be built simply against an
+ already installed server. <acronym class="acronym">PGXS</acronym> is mainly intended
+ for extensions that include C code, although it can be used for
+ pure-SQL extensions too. Note that <acronym class="acronym">PGXS</acronym> is not
+ intended to be a universal build system framework that can be used
+ to build any software interfacing to <span class="productname">PostgreSQL</span>;
+ it simply automates common build rules for simple server extension
+ modules. For more complicated packages, you might need to write your
+ own build system.
+ </p><p>
+ To use the <acronym class="acronym">PGXS</acronym> infrastructure for your extension,
+ you must write a simple makefile.
+ In the makefile, you need to set some variables
+ and include the global <acronym class="acronym">PGXS</acronym> makefile.
+ Here is an example that builds an extension module named
+ <code class="literal">isbn_issn</code>, consisting of a shared library containing
+ some C code, an extension control file, an SQL script, an include file
+ (only needed if other modules might need to access the extension functions
+ without going via SQL), and a documentation text file:
+</p><pre class="programlisting">
+MODULES = isbn_issn
+EXTENSION = isbn_issn
+DATA = isbn_issn--1.0.sql
+DOCS = README.isbn_issn
+HEADERS_isbn_issn = isbn_issn.h
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)
+</pre><p>
+ The last three lines should always be the same. Earlier in the
+ file, you assign variables or add custom
+ <span class="application">make</span> rules.
+ </p><p>
+ Set one of these three variables to specify what is built:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">MODULES</code></span></dt><dd><p>
+ list of shared-library objects to be built from source files with same
+ stem (do not include library suffixes in this list)
+ </p></dd><dt><span class="term"><code class="varname">MODULE_big</code></span></dt><dd><p>
+ a shared library to build from multiple source files
+ (list object files in <code class="varname">OBJS</code>)
+ </p></dd><dt><span class="term"><code class="varname">PROGRAM</code></span></dt><dd><p>
+ an executable program to build
+ (list object files in <code class="varname">OBJS</code>)
+ </p></dd></dl></div><p>
+
+ The following variables can also be set:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">EXTENSION</code></span></dt><dd><p>
+ extension name(s); for each name you must provide an
+ <code class="literal"><em class="replaceable"><code>extension</code></em>.control</code> file,
+ which will be installed into
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/extension</code>
+ </p></dd><dt><span class="term"><code class="varname">MODULEDIR</code></span></dt><dd><p>
+ subdirectory of <code class="literal"><em class="replaceable"><code>prefix</code></em>/share</code>
+ into which DATA and DOCS files should be installed
+ (if not set, default is <code class="literal">extension</code> if
+ <code class="varname">EXTENSION</code> is set,
+ or <code class="literal">contrib</code> if not)
+ </p></dd><dt><span class="term"><code class="varname">DATA</code></span></dt><dd><p>
+ random files to install into <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>
+ </p></dd><dt><span class="term"><code class="varname">DATA_built</code></span></dt><dd><p>
+ random files to install into
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>,
+ which need to be built first
+ </p></dd><dt><span class="term"><code class="varname">DATA_TSEARCH</code></span></dt><dd><p>
+ random files to install under
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/tsearch_data</code>
+ </p></dd><dt><span class="term"><code class="varname">DOCS</code></span></dt><dd><p>
+ random files to install under
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/doc/$MODULEDIR</code>
+ </p></dd><dt><span class="term"><code class="varname">HEADERS</code><br /></span><span class="term"><code class="varname">HEADERS_built</code></span></dt><dd><p>
+ Files to (optionally build and) install under
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/include/server/$MODULEDIR/$MODULE_big</code>.
+ </p><p>
+ Unlike <code class="literal">DATA_built</code>, files in <code class="literal">HEADERS_built</code>
+ are not removed by the <code class="literal">clean</code> target; if you want them removed,
+ also add them to <code class="literal">EXTRA_CLEAN</code> or add your own rules to do it.
+ </p></dd><dt><span class="term"><code class="varname">HEADERS_$MODULE</code><br /></span><span class="term"><code class="varname">HEADERS_built_$MODULE</code></span></dt><dd><p>
+ Files to install (after building if specified) under
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/include/server/$MODULEDIR/$MODULE</code>,
+ where <code class="literal">$MODULE</code> must be a module name used
+ in <code class="literal">MODULES</code> or <code class="literal">MODULE_big</code>.
+ </p><p>
+ Unlike <code class="literal">DATA_built</code>, files in <code class="literal">HEADERS_built_$MODULE</code>
+ are not removed by the <code class="literal">clean</code> target; if you want them removed,
+ also add them to <code class="literal">EXTRA_CLEAN</code> or add your own rules to do it.
+ </p><p>
+ It is legal to use both variables for the same module, or any
+ combination, unless you have two module names in the
+ <code class="literal">MODULES</code> list that differ only by the presence of a
+ prefix <code class="literal">built_</code>, which would cause ambiguity. In
+ that (hopefully unlikely) case, you should use only the
+ <code class="literal">HEADERS_built_$MODULE</code> variables.
+ </p></dd><dt><span class="term"><code class="varname">SCRIPTS</code></span></dt><dd><p>
+ script files (not binaries) to install into
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>
+ </p></dd><dt><span class="term"><code class="varname">SCRIPTS_built</code></span></dt><dd><p>
+ script files (not binaries) to install into
+ <code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>,
+ which need to be built first
+ </p></dd><dt><span class="term"><code class="varname">REGRESS</code></span></dt><dd><p>
+ list of regression test cases (without suffix), see below
+ </p></dd><dt><span class="term"><code class="varname">REGRESS_OPTS</code></span></dt><dd><p>
+ additional switches to pass to <span class="application">pg_regress</span>
+ </p></dd><dt><span class="term"><code class="varname">ISOLATION</code></span></dt><dd><p>
+ list of isolation test cases, see below for more details
+ </p></dd><dt><span class="term"><code class="varname">ISOLATION_OPTS</code></span></dt><dd><p>
+ additional switches to pass to
+ <span class="application">pg_isolation_regress</span>
+ </p></dd><dt><span class="term"><code class="varname">TAP_TESTS</code></span></dt><dd><p>
+ switch defining if TAP tests need to be run, see below
+ </p></dd><dt><span class="term"><code class="varname">NO_INSTALL</code></span></dt><dd><p>
+ don't define an <code class="literal">install</code> target, useful for test
+ modules that don't need their build products to be installed
+ </p></dd><dt><span class="term"><code class="varname">NO_INSTALLCHECK</code></span></dt><dd><p>
+ don't define an <code class="literal">installcheck</code> target, useful e.g., if tests require special configuration, or don't use <span class="application">pg_regress</span>
+ </p></dd><dt><span class="term"><code class="varname">EXTRA_CLEAN</code></span></dt><dd><p>
+ extra files to remove in <code class="literal">make clean</code>
+ </p></dd><dt><span class="term"><code class="varname">PG_CPPFLAGS</code></span></dt><dd><p>
+ will be prepended to <code class="varname">CPPFLAGS</code>
+ </p></dd><dt><span class="term"><code class="varname">PG_CFLAGS</code></span></dt><dd><p>
+ will be appended to <code class="varname">CFLAGS</code>
+ </p></dd><dt><span class="term"><code class="varname">PG_CXXFLAGS</code></span></dt><dd><p>
+ will be appended to <code class="varname">CXXFLAGS</code>
+ </p></dd><dt><span class="term"><code class="varname">PG_LDFLAGS</code></span></dt><dd><p>
+ will be prepended to <code class="varname">LDFLAGS</code>
+ </p></dd><dt><span class="term"><code class="varname">PG_LIBS</code></span></dt><dd><p>
+ will be added to <code class="varname">PROGRAM</code> link line
+ </p></dd><dt><span class="term"><code class="varname">SHLIB_LINK</code></span></dt><dd><p>
+ will be added to <code class="varname">MODULE_big</code> link line
+ </p></dd><dt><span class="term"><code class="varname">PG_CONFIG</code></span></dt><dd><p>
+ path to <span class="application">pg_config</span> program for the
+ <span class="productname">PostgreSQL</span> installation to build against
+ (typically just <code class="literal">pg_config</code> to use the first one in your
+ <code class="varname">PATH</code>)
+ </p></dd></dl></div><p>
+ </p><p>
+ Put this makefile as <code class="literal">Makefile</code> in the directory
+ which holds your extension. Then you can do
+ <code class="literal">make</code> to compile, and then <code class="literal">make
+ install</code> to install your module. By default, the extension is
+ compiled and installed for the
+ <span class="productname">PostgreSQL</span> installation that
+ corresponds to the first <code class="command">pg_config</code> program
+ found in your <code class="varname">PATH</code>. You can use a different installation by
+ setting <code class="varname">PG_CONFIG</code> to point to its
+ <code class="command">pg_config</code> program, either within the makefile
+ or on the <code class="literal">make</code> command line.
+ </p><p>
+ You can also run <code class="literal">make</code> in a directory outside the source
+ tree of your extension, if you want to keep the build directory separate.
+ This procedure is also called a
+ <a id="id-1.8.3.21.7.2" class="indexterm"></a><em class="firstterm">VPATH</em>
+ build. Here's how:
+</p><pre class="programlisting">
+mkdir build_dir
+cd build_dir
+make -f /path/to/extension/source/tree/Makefile
+make -f /path/to/extension/source/tree/Makefile install
+</pre><p>
+ </p><p>
+ Alternatively, you can set up a directory for a VPATH build in a similar
+ way to how it is done for the core code. One way to do this is using the
+ core script <code class="filename">config/prep_buildtree</code>. Once this has been done
+ you can build by setting the <code class="literal">make</code> variable
+ <code class="varname">VPATH</code> like this:
+</p><pre class="programlisting">
+make VPATH=/path/to/extension/source/tree
+make VPATH=/path/to/extension/source/tree install
+</pre><p>
+ This procedure can work with a greater variety of directory layouts.
+ </p><p>
+ The scripts listed in the <code class="varname">REGRESS</code> variable are used for
+ regression testing of your module, which can be invoked by <code class="literal">make
+ installcheck</code> after doing <code class="literal">make install</code>. For this to
+ work you must have a running <span class="productname">PostgreSQL</span> server.
+ The script files listed in <code class="varname">REGRESS</code> must appear in a
+ subdirectory named <code class="literal">sql/</code> in your extension's directory.
+ These files must have extension <code class="literal">.sql</code>, which must not be
+ included in the <code class="varname">REGRESS</code> list in the makefile. For each
+ test there should also be a file containing the expected output in a
+ subdirectory named <code class="literal">expected/</code>, with the same stem and
+ extension <code class="literal">.out</code>. <code class="literal">make installcheck</code>
+ executes each test script with <span class="application">psql</span>, and compares the
+ resulting output to the matching expected file. Any differences will be
+ written to the file <code class="literal">regression.diffs</code> in <code class="command">diff
+ -c</code> format. Note that trying to run a test that is missing its
+ expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so make sure you
+ have all expected files.
+ </p><p>
+ The scripts listed in the <code class="varname">ISOLATION</code> variable are used
+ for tests stressing behavior of concurrent session with your module, which
+ can be invoked by <code class="literal">make installcheck</code> after doing
+ <code class="literal">make install</code>. For this to work you must have a
+ running <span class="productname">PostgreSQL</span> server. The script files
+ listed in <code class="varname">ISOLATION</code> must appear in a subdirectory
+ named <code class="literal">specs/</code> in your extension's directory. These files
+ must have extension <code class="literal">.spec</code>, which must not be included
+ in the <code class="varname">ISOLATION</code> list in the makefile. For each test
+ there should also be a file containing the expected output in a
+ subdirectory named <code class="literal">expected/</code>, with the same stem and
+ extension <code class="literal">.out</code>. <code class="literal">make installcheck</code>
+ executes each test script, and compares the resulting output to the
+ matching expected file. Any differences will be written to the file
+ <code class="literal">output_iso/regression.diffs</code> in
+ <code class="command">diff -c</code> format. Note that trying to run a test that is
+ missing its expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so
+ make sure you have all expected files.
+ </p><p>
+ <code class="literal">TAP_TESTS</code> enables the use of TAP tests. Data from each
+ run is present in a subdirectory named <code class="literal">tmp_check/</code>.
+ See also <a class="xref" href="regress-tap.html" title="33.4. TAP Tests">Section 33.4</a> for more details.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The easiest way to create the expected files is to create empty files,
+ then do a test run (which will of course report differences). Inspect
+ the actual result files found in the <code class="literal">results/</code>
+ directory (for tests in <code class="literal">REGRESS</code>), or
+ <code class="literal">output_iso/results/</code> directory (for tests in
+ <code class="literal">ISOLATION</code>), then copy them to
+ <code class="literal">expected/</code> if they match what you expect from the test.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 39. Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.17. Packaging Related Objects into an Extension </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 39. Triggers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/extend-type-system.html b/doc/src/sgml/html/extend-type-system.html
new file mode 100644
index 0000000..2de46d4
--- /dev/null
+++ b/doc/src/sgml/html/extend-type-system.html
@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.2. The PostgreSQL Type System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-how.html" title="38.1. How Extensibility Works" /><link rel="next" href="xfunc.html" title="38.3. User-Defined Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.2. The <span class="productname">PostgreSQL</span> Type System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-how.html" title="38.1. How Extensibility Works">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc.html" title="38.3. User-Defined Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-TYPE-SYSTEM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.2. The <span class="productname">PostgreSQL</span> Type System</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.9">38.2.1. Base Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.10">38.2.2. Container Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-DOMAINS">38.2.3. Domains</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.12">38.2.4. Pseudo-Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">38.2.5. Polymorphic Types</a></span></dt></dl></div><a id="id-1.8.3.5.2" class="indexterm"></a><a id="id-1.8.3.5.3" class="indexterm"></a><a id="id-1.8.3.5.4" class="indexterm"></a><a id="id-1.8.3.5.5" class="indexterm"></a><a id="id-1.8.3.5.6" class="indexterm"></a><a id="id-1.8.3.5.7" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> data types can be divided into base
+ types, container types, domains, and pseudo-types.
+ </p><div class="sect2" id="id-1.8.3.5.9"><div class="titlepage"><div><div><h3 class="title">38.2.1. Base Types</h3></div></div></div><p>
+ Base types are those, like <code class="type">integer</code>, that are
+ implemented below the level of the <acronym class="acronym">SQL</acronym> language
+ (typically in a low-level language such as C). They generally
+ correspond to what are often known as abstract data types.
+ <span class="productname">PostgreSQL</span> can only operate on such
+ 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 <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>.
+ </p><p>
+ Enumerated (enum) types can be considered as a subcategory of base
+ types. The main difference is that they can be created using
+ just <acronym class="acronym">SQL</acronym> commands, without any low-level programming.
+ Refer to <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a> for more information.
+ </p></div><div class="sect2" id="id-1.8.3.5.10"><div class="titlepage"><div><div><h3 class="title">38.2.2. Container Types</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> has three kinds
+ of <span class="quote">“<span class="quote">container</span>”</span> types, which are types that contain multiple
+ values of other types. These are arrays, composites, and ranges.
+ </p><p>
+ Arrays can hold multiple values that are all of the same type. An array
+ 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 <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a> for more
+ information.
+ </p><p>
+ Composite types, or row types, are created whenever the user
+ creates a table. It is also possible to use <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> to
+ define a <span class="quote">“<span class="quote">stand-alone</span>”</span> 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 <a class="xref" href="rowtypes.html" title="8.16. Composite Types">Section 8.16</a>
+ for more information.
+ </p><p>
+ 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 class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>
+ for more information.
+ </p></div><div class="sect2" id="EXTEND-TYPE-SYSTEM-DOMAINS"><div class="titlepage"><div><div><h3 class="title">38.2.3. Domains</h3></div></div></div><p>
+ A domain is based on a particular underlying type and for many purposes
+ 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 <acronym class="acronym">SQL</acronym> command <a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>.
+ Refer to <a class="xref" href="domains.html" title="8.18. Domain Types">Section 8.18</a> for more information.
+ </p></div><div class="sect2" id="id-1.8.3.5.12"><div class="titlepage"><div><div><h3 class="title">38.2.4. Pseudo-Types</h3></div></div></div><p>
+ There are a few <span class="quote">“<span class="quote">pseudo-types</span>”</span> for special purposes.
+ Pseudo-types cannot appear as columns of tables or components of
+ 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. <a class="xref" href="datatype-pseudo.html#DATATYPE-PSEUDOTYPES-TABLE" title="Table 8.27. Pseudo-Types">Table 8.27</a> lists the existing
+ pseudo-types.
+ </p></div><div class="sect2" id="EXTEND-TYPES-POLYMORPHIC"><div class="titlepage"><div><div><h3 class="title">38.2.5. Polymorphic Types</h3></div></div></div><a id="id-1.8.3.5.13.2" class="indexterm"></a><a id="id-1.8.3.5.13.3" class="indexterm"></a><a id="id-1.8.3.5.13.4" class="indexterm"></a><a id="id-1.8.3.5.13.5" class="indexterm"></a><p>
+ Some pseudo-types of special interest are the <em class="firstterm">polymorphic
+ types</em>, which are used to declare <em class="firstterm">polymorphic
+ functions</em>. This powerful feature allows a single function
+ definition to operate on many different data types, with the specific
+ data type(s) being determined by the data types actually passed to it
+ in a particular call. The polymorphic types are shown in
+ <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC-TABLE" title="Table 38.1. Polymorphic Types">Table 38.1</a>. Some examples of
+ their use appear in <a class="xref" href="xfunc-sql.html#XFUNC-SQL-POLYMORPHIC-FUNCTIONS" title="38.5.11. Polymorphic SQL Functions">Section 38.5.11</a>.
+ </p><div class="table" id="EXTEND-TYPES-POLYMORPHIC-TABLE"><p class="title"><strong>Table 38.1. Polymorphic Types</strong></p><div class="table-contents"><table class="table" summary="Polymorphic Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Family</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">anyelement</code></td><td>Simple</td><td>Indicates that a function accepts any data type</td></tr><tr><td><code class="type">anyarray</code></td><td>Simple</td><td>Indicates that a function accepts any array data type</td></tr><tr><td><code class="type">anynonarray</code></td><td>Simple</td><td>Indicates that a function accepts any non-array data type</td></tr><tr><td><code class="type">anyenum</code></td><td>Simple</td><td>Indicates that a function accepts any enum data type
+ (see <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a>)
+ </td></tr><tr><td><code class="type">anyrange</code></td><td>Simple</td><td>Indicates that a function accepts any range data type
+ (see <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>)
+ </td></tr><tr><td><code class="type">anymultirange</code></td><td>Simple</td><td>Indicates that a function accepts any multirange data type
+ (see <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>)
+ </td></tr><tr><td><code class="type">anycompatible</code></td><td>Common</td><td>Indicates that a function accepts any data type,
+ with automatic promotion of multiple arguments to a common data type
+ </td></tr><tr><td><code class="type">anycompatiblearray</code></td><td>Common</td><td>Indicates that a function accepts any array data type,
+ with automatic promotion of multiple arguments to a common data type
+ </td></tr><tr><td><code class="type">anycompatiblenonarray</code></td><td>Common</td><td>Indicates that a function accepts any non-array data type,
+ with automatic promotion of multiple arguments to a common data type
+ </td></tr><tr><td><code class="type">anycompatiblerange</code></td><td>Common</td><td>Indicates that a function accepts any range data type,
+ with automatic promotion of multiple arguments to a common data type
+ </td></tr><tr><td><code class="type">anycompatiblemultirange</code></td><td>Common</td><td>Indicates that a function accepts any multirange data type,
+ with automatic promotion of multiple arguments to a common data type
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Polymorphic arguments and results are tied to each other and are resolved
+ to specific data types when a query calling a polymorphic function is
+ parsed. When there is more than one polymorphic argument, the actual
+ data types of the input values must match up as described below. If the
+ function's result type is polymorphic, or it has output parameters of
+ polymorphic types, the types of those results are deduced from the
+ actual types of the polymorphic inputs as described below.
+ </p><p>
+ For the <span class="quote">“<span class="quote">simple</span>”</span> family of polymorphic types, the
+ matching and deduction rules work like this:
+ </p><p>
+ Each position (either argument or return value) declared as
+ <code class="type">anyelement</code> is allowed to have any specific actual
+ data type, but in any given call they must all be the
+ <span class="emphasis"><em>same</em></span> actual type. Each
+ position declared as <code class="type">anyarray</code> can have any array data type,
+ but similarly they must all be the same type. And similarly,
+ positions declared as <code class="type">anyrange</code> must all be the same range
+ type. Likewise for <code class="type">anymultirange</code>.
+ </p><p>
+ Furthermore, if there are
+ positions declared <code class="type">anyarray</code> and others declared
+ <code class="type">anyelement</code>, the actual array type in the
+ <code class="type">anyarray</code> positions must be an array whose elements are
+ the same type appearing in the <code class="type">anyelement</code> positions.
+ <code class="type">anynonarray</code> is treated exactly the same as <code class="type">anyelement</code>,
+ but adds the additional constraint that the actual type must not be
+ an array type.
+ <code class="type">anyenum</code> is treated exactly the same as <code class="type">anyelement</code>,
+ but adds the additional constraint that the actual type must
+ be an enum type.
+ </p><p>
+ Similarly, if there are positions declared <code class="type">anyrange</code>
+ and others declared <code class="type">anyelement</code> or <code class="type">anyarray</code>,
+ the actual range type in the <code class="type">anyrange</code> positions must be a
+ range whose subtype is the same type appearing in
+ the <code class="type">anyelement</code> positions and the same as the element type
+ of the <code class="type">anyarray</code> positions.
+ If there are positions declared <code class="type">anymultirange</code>,
+ their actual multirange type must contain ranges matching parameters declared
+ <code class="type">anyrange</code> and base elements matching parameters declared
+ <code class="type">anyelement</code> and <code class="type">anyarray</code>.
+ </p><p>
+ Thus, when more than one argument position is declared with a polymorphic
+ type, the net effect is that only certain combinations of actual argument
+ types are allowed. For example, a function declared as
+ <code class="literal">equal(anyelement, anyelement)</code> will take any two input values,
+ so long as they are of the same data type.
+ </p><p>
+ When the return value of a function is declared as a polymorphic type,
+ there must be at least one argument position that is also polymorphic,
+ and the actual data type(s) supplied for the polymorphic arguments
+ determine the actual
+ result type for that call. For example, if there were not already
+ an array subscripting mechanism, one could define a function that
+ implements subscripting as <code class="literal">subscript(anyarray, integer)
+ returns anyelement</code>. This declaration constrains the actual first
+ argument to be an array type, and allows the parser to infer the correct
+ result type from the actual first argument's type. Another example
+ is that a function declared as <code class="literal">f(anyarray) returns anyenum</code>
+ will only accept arrays of enum types.
+ </p><p>
+ In most cases, the parser can infer the actual data type for a
+ polymorphic result type from arguments that are of a different
+ polymorphic type in the same family; for example <code class="type">anyarray</code>
+ can be deduced from <code class="type">anyelement</code> or vice versa.
+ An exception is that a
+ polymorphic result of type <code class="type">anyrange</code> requires an argument
+ of type <code class="type">anyrange</code>; it cannot be deduced
+ from <code class="type">anyarray</code> or <code class="type">anyelement</code> arguments. This
+ is because there could be multiple range types with the same subtype.
+ </p><p>
+ Note that <code class="type">anynonarray</code> and <code class="type">anyenum</code> do not represent
+ separate type variables; they are the same type as
+ <code class="type">anyelement</code>, just with an additional constraint. For
+ example, declaring a function as <code class="literal">f(anyelement, anyenum)</code>
+ is equivalent to declaring it as <code class="literal">f(anyenum, anyenum)</code>:
+ both actual arguments have to be the same enum type.
+ </p><p>
+ For the <span class="quote">“<span class="quote">common</span>”</span> family of polymorphic types, the
+ matching and deduction rules work approximately the same as for
+ the <span class="quote">“<span class="quote">simple</span>”</span> family, with one major difference: the
+ actual types of the arguments need not be identical, so long as they
+ can be implicitly cast to a single common type. The common type is
+ selected following the same rules as for <code class="literal">UNION</code> and
+ related constructs (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
+ Selection of the common type considers the actual types
+ of <code class="type">anycompatible</code> and <code class="type">anycompatiblenonarray</code>
+ inputs, the array element types of <code class="type">anycompatiblearray</code>
+ inputs, the range subtypes of <code class="type">anycompatiblerange</code> inputs,
+ and the multirange subtypes of <code class="type">anycompatiblemultirange</code>
+ inputs. If <code class="type">anycompatiblenonarray</code> is present then the
+ common type is required to be a non-array type. Once a common type is
+ identified, arguments in <code class="type">anycompatible</code>
+ and <code class="type">anycompatiblenonarray</code> positions are automatically
+ cast to that type, and arguments in <code class="type">anycompatiblearray</code>
+ positions are automatically cast to the array type for that type.
+ </p><p>
+ Since there is no way to select a range type knowing only its subtype,
+ use of <code class="type">anycompatiblerange</code> and/or
+ <code class="type">anycompatiblemultirange</code> requires that all arguments declared
+ with that type have the same actual range and/or multirange type, and that
+ that type's subtype agree with the selected common type, so that no casting
+ of the range values is required. As with <code class="type">anyrange</code> and
+ <code class="type">anymultirange</code>, use of <code class="type">anycompatiblerange</code> and
+ <code class="type">anymultirange</code> as a function result type requires that there be
+ an <code class="type">anycompatiblerange</code> or <code class="type">anycompatiblemultirange</code>
+ argument.
+ </p><p>
+ Notice that there is no <code class="type">anycompatibleenum</code> type. Such a
+ type would not be very useful, since there normally are not any
+ implicit casts to enum types, meaning that there would be no way to
+ resolve a common type for dissimilar enum inputs.
+ </p><p>
+ The <span class="quote">“<span class="quote">simple</span>”</span> and <span class="quote">“<span class="quote">common</span>”</span> polymorphic
+ families represent two independent sets of type variables. Consider
+ for example
+</p><pre class="programlisting">
+CREATE FUNCTION myfunc(a anyelement, b anyelement,
+ c anycompatible, d anycompatible)
+RETURNS anycompatible AS ...
+</pre><p>
+ In an actual call of this function, the first two inputs must have
+ exactly the same type. The last two inputs must be promotable to a
+ common type, but this type need not have anything to do with the type
+ of the first two inputs. The result will have the common type of the
+ last two inputs.
+ </p><p>
+ A variadic function (one taking a variable number of arguments, as in
+ <a class="xref" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS" title="38.5.6. SQL Functions with Variable Numbers of Arguments">Section 38.5.6</a>) can be
+ polymorphic: this is accomplished by declaring its last parameter as
+ <code class="literal">VARIADIC</code> <code class="type">anyarray</code> or
+ <code class="literal">VARIADIC</code> <code class="type">anycompatiblearray</code>.
+ For purposes of argument
+ matching and determining the actual result type, such a function behaves
+ the same as if you had written the appropriate number of
+ <code class="type">anynonarray</code> or <code class="type">anycompatiblenonarray</code>
+ parameters.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-how.html" title="38.1. How Extensibility Works">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc.html" title="38.3. User-Defined Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.1. How Extensibility Works </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.3. User-Defined Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/extend.html b/doc/src/sgml/html/extend.html
new file mode 100644
index 0000000..0bb90ac
--- /dev/null
+++ b/doc/src/sgml/html/extend.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 38. Extending SQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="server-programming.html" title="Part V. Server Programming" /><link rel="next" href="extend-how.html" title="38.1. How Extensibility Works" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="server-programming.html" title="Part V. Server Programming">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="extend-how.html" title="38.1. How Extensibility Works">Next</a></td></tr></table><hr /></div><div class="chapter" id="EXTEND"><div class="titlepage"><div><div><h2 class="title">Chapter 38. Extending <acronym class="acronym">SQL</acronym></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="extend-how.html">38.1. How Extensibility Works</a></span></dt><dt><span class="sect1"><a href="extend-type-system.html">38.2. The <span class="productname">PostgreSQL</span> Type System</a></span></dt><dd><dl><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.9">38.2.1. Base Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.10">38.2.2. Container Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-DOMAINS">38.2.3. Domains</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#id-1.8.3.5.12">38.2.4. Pseudo-Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">38.2.5. Polymorphic Types</a></span></dt></dl></dd><dt><span class="sect1"><a href="xfunc.html">38.3. User-Defined Functions</a></span></dt><dt><span class="sect1"><a href="xproc.html">38.4. User-Defined Procedures</a></span></dt><dt><span class="sect1"><a href="xfunc-sql.html">38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS">38.5.1. Arguments for <acronym class="acronym">SQL</acronym> Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-BASE-FUNCTIONS">38.5.2. <acronym class="acronym">SQL</acronym> Functions on Base Types</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-COMPOSITE-FUNCTIONS">38.5.3. <acronym class="acronym">SQL</acronym> Functions on Composite Types</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS">38.5.4. <acronym class="acronym">SQL</acronym> Functions with Output Parameters</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS-PROC">38.5.5. <acronym class="acronym">SQL</acronym> Procedures with Output Parameters</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS">38.5.6. <acronym class="acronym">SQL</acronym> Functions with Variable Numbers of Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-PARAMETER-DEFAULTS">38.5.7. <acronym class="acronym">SQL</acronym> Functions with Default Values for Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-TABLE-FUNCTIONS">38.5.8. <acronym class="acronym">SQL</acronym> Functions as Table Sources</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-SET">38.5.9. <acronym class="acronym">SQL</acronym> Functions Returning Sets</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-TABLE">38.5.10. <acronym class="acronym">SQL</acronym> Functions Returning <code class="literal">TABLE</code></a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-POLYMORPHIC-FUNCTIONS">38.5.11. Polymorphic <acronym class="acronym">SQL</acronym> Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#id-1.8.3.8.21">38.5.12. <acronym class="acronym">SQL</acronym> Functions with Collations</a></span></dt></dl></dd><dt><span class="sect1"><a href="xfunc-overload.html">38.6. Function Overloading</a></span></dt><dt><span class="sect1"><a href="xfunc-volatility.html">38.7. Function Volatility Categories</a></span></dt><dt><span class="sect1"><a href="xfunc-pl.html">38.8. Procedural Language Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-internal.html">38.9. Internal Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-c.html">38.10. C-Language Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-DYNLOAD">38.10.1. Dynamic Loading</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-BASETYPE">38.10.2. Base Types in C-Language Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.7">38.10.3. Version 1 Calling Conventions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.8">38.10.4. Writing Code</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#DFUNC">38.10.5. Compiling and Linking Dynamically-Loaded Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.10">38.10.6. Composite-Type Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.11">38.10.7. Returning Rows (Composite Types)</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-RETURN-SET">38.10.8. Returning Sets</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.13">38.10.9. Polymorphic Arguments and Return Types</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-SHARED-ADDIN">38.10.10. Shared Memory and LWLocks</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#EXTEND-CPP">38.10.11. Using C++ for Extensibility</a></span></dt></dl></dd><dt><span class="sect1"><a href="xfunc-optimization.html">38.11. Function Optimization Information</a></span></dt><dt><span class="sect1"><a href="xaggr.html">38.12. User-Defined Aggregates</a></span></dt><dd><dl><dt><span class="sect2"><a href="xaggr.html#XAGGR-MOVING-AGGREGATES">38.12.1. Moving-Aggregate Mode</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-POLYMORPHIC-AGGREGATES">38.12.2. Polymorphic and Variadic Aggregates</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-ORDERED-SET-AGGREGATES">38.12.3. Ordered-Set Aggregates</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-PARTIAL-AGGREGATES">38.12.4. Partial Aggregation</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-SUPPORT-FUNCTIONS">38.12.5. Support Functions for Aggregates</a></span></dt></dl></dd><dt><span class="sect1"><a href="xtypes.html">38.13. User-Defined Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="xtypes.html#XTYPES-TOAST">38.13.1. TOAST Considerations</a></span></dt></dl></dd><dt><span class="sect1"><a href="xoper.html">38.14. User-Defined Operators</a></span></dt><dt><span class="sect1"><a href="xoper-optimization.html">38.15. Operator Optimization Information</a></span></dt><dd><dl><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.6">38.15.1. <code class="literal">COMMUTATOR</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.7">38.15.2. <code class="literal">NEGATOR</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.8">38.15.3. <code class="literal">RESTRICT</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.9">38.15.4. <code class="literal">JOIN</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.10">38.15.5. <code class="literal">HASHES</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.11">38.15.6. <code class="literal">MERGES</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="xindex.html">38.16. Interfacing Extensions to Indexes</a></span></dt><dd><dl><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS">38.16.1. Index Methods and Operator Classes</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-STRATEGIES">38.16.2. Index Method Strategies</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-SUPPORT">38.16.3. Index Method Support Routines</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-EXAMPLE">38.16.4. An Example</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPFAMILY">38.16.5. Operator Classes and Operator Families</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS-DEPENDENCIES">38.16.6. System Dependencies on Operator Classes</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-ORDERING-OPS">38.16.7. Ordering Operators</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS-FEATURES">38.16.8. Special Features of Operator Classes</a></span></dt></dl></dd><dt><span class="sect1"><a href="extend-extensions.html">38.17. Packaging Related Objects into an Extension</a></span></dt><dd><dl><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.11">38.17.1. Extension Files</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-RELOCATION">38.17.2. Extension Relocatability</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-CONFIG-TABLES">38.17.3. Extension Configuration Tables</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.14">38.17.4. Extension Updates</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#id-1.8.3.20.15">38.17.5. Installing Extensions Using Update Scripts</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-SECURITY">38.17.6. Security Considerations for Extensions</a></span></dt><dt><span class="sect2"><a href="extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE">38.17.7. Extension Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="extend-pgxs.html">38.18. Extension Building Infrastructure</a></span></dt></dl></div><a id="id-1.8.3.2" class="indexterm"></a><p>
+ In the sections that follow, we will discuss how you
+ can extend the <span class="productname">PostgreSQL</span>
+ <acronym class="acronym">SQL</acronym> query language by adding:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ functions (starting in <a class="xref" href="xfunc.html" title="38.3. User-Defined Functions">Section 38.3</a>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ aggregates (starting in <a class="xref" href="xaggr.html" title="38.12. User-Defined Aggregates">Section 38.12</a>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ data types (starting in <a class="xref" href="xtypes.html" title="38.13. User-Defined Types">Section 38.13</a>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ operators (starting in <a class="xref" href="xoper.html" title="38.14. User-Defined Operators">Section 38.14</a>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ operator classes for indexes (starting in <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ packages of related objects (starting in <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a>)
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server-programming.html" title="Part V. Server Programming">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extend-how.html" title="38.1. How Extensibility Works">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part V. Server Programming </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.1. How Extensibility Works</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/external-admin-tools.html b/doc/src/sgml/html/external-admin-tools.html
new file mode 100644
index 0000000..e5206b1
--- /dev/null
+++ b/doc/src/sgml/html/external-admin-tools.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>H.2. Administration Tools</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="external-interfaces.html" title="H.1. Client Interfaces" /><link rel="next" href="external-pl.html" title="H.3. Procedural Languages" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">H.2. Administration Tools</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="external-interfaces.html" title="H.1. Client Interfaces">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><th width="60%" align="center">Appendix H. External Projects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="external-pl.html" title="H.3. Procedural Languages">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTERNAL-ADMIN-TOOLS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">H.2. Administration Tools</h2></div></div></div><a id="id-1.11.9.4.2" class="indexterm"></a><p>
+ There are several administration tools available for
+ <span class="productname">PostgreSQL</span>. The most popular is
+ <span class="application"><a class="ulink" href="https://www.pgadmin.org/" target="_top">pgAdmin</a></span>,
+ and there are several commercially available ones as well.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="external-interfaces.html" title="H.1. Client Interfaces">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="external-pl.html" title="H.3. Procedural Languages">Next</a></td></tr><tr><td width="40%" align="left" valign="top">H.1. Client Interfaces </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> H.3. Procedural Languages</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/external-extensions.html b/doc/src/sgml/html/external-extensions.html
new file mode 100644
index 0000000..7d142dd
--- /dev/null
+++ b/doc/src/sgml/html/external-extensions.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>H.4. Extensions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="external-pl.html" title="H.3. Procedural Languages" /><link rel="next" href="sourcerepo.html" title="Appendix I. The Source Code Repository" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">H.4. Extensions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="external-pl.html" title="H.3. Procedural Languages">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><th width="60%" align="center">Appendix H. External Projects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTERNAL-EXTENSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">H.4. Extensions</h2></div></div></div><a id="id-1.11.9.6.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> is designed to be easily extensible. For
+ this reason, extensions loaded into the database can function
+ just like features that are built in. The
+ <code class="filename">contrib/</code> directory shipped with the source code
+ contains several extensions, which are described in
+ <a class="xref" href="contrib.html" title="Appendix F. Additional Supplied Modules">Appendix F</a>. Other extensions are developed
+ independently, like <span class="application"><a class="ulink" href="https://postgis.net/" target="_top">PostGIS</a></span>. Even
+ <span class="productname">PostgreSQL</span> replication solutions can be developed
+ externally. For example, <span class="application"> <a class="ulink" href="https://www.slony.info" target="_top">Slony-I</a></span> is a popular
+ primary/standby replication solution that is developed independently
+ from the core project.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="external-pl.html" title="H.3. Procedural Languages">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Next</a></td></tr><tr><td width="40%" align="left" valign="top">H.3. Procedural Languages </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix I. The Source Code Repository</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/external-interfaces.html b/doc/src/sgml/html/external-interfaces.html
new file mode 100644
index 0000000..0a89b94
--- /dev/null
+++ b/doc/src/sgml/html/external-interfaces.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>H.1. Client Interfaces</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="external-projects.html" title="Appendix H. External Projects" /><link rel="next" href="external-admin-tools.html" title="H.2. Administration Tools" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">H.1. Client Interfaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="external-projects.html" title="Appendix H. External Projects">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><th width="60%" align="center">Appendix H. External Projects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="external-admin-tools.html" title="H.2. Administration Tools">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTERNAL-INTERFACES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">H.1. Client Interfaces</h2></div></div></div><a id="id-1.11.9.3.2" class="indexterm"></a><p>
+ There are only two client interfaces included in the base
+ <span class="productname">PostgreSQL</span> distribution:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="link" href="libpq.html" title="Chapter 34. libpq — C Library">libpq</a> is included because it is the
+ primary C language interface, and because many other client interfaces
+ are built on top of it.
+ </p></li><li class="listitem"><p>
+ <a class="link" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">ECPG</a> is included because it depends on the
+ server-side SQL grammar, and is therefore sensitive to changes in
+ <span class="productname">PostgreSQL</span> itself.
+ </p></li></ul></div><p>
+
+ All other language interfaces are external projects and are distributed
+ separately. A
+ <a class="ulink" href="https://wiki.postgresql.org/wiki/List_of_drivers" target="_top">list of language interfaces</a>
+ is maintained on the PostgreSQL wiki. Note that some of these packages are
+ not released under the same license as <span class="productname">PostgreSQL</span>.
+ For more information on each language interface, including licensing terms,
+ refer to its website and documentation.
+ </p><p>
+ <a class="ulink" href="https://wiki.postgresql.org/wiki/List_of_drivers" target="_top">https://wiki.postgresql.org/wiki/List_of_drivers</a>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="external-projects.html" title="Appendix H. External Projects">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="external-admin-tools.html" title="H.2. Administration Tools">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix H. External Projects </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> H.2. Administration Tools</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/external-pl.html b/doc/src/sgml/html/external-pl.html
new file mode 100644
index 0000000..4e60555
--- /dev/null
+++ b/doc/src/sgml/html/external-pl.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>H.3. Procedural Languages</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="external-admin-tools.html" title="H.2. Administration Tools" /><link rel="next" href="external-extensions.html" title="H.4. Extensions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">H.3. Procedural Languages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="external-admin-tools.html" title="H.2. Administration Tools">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><th width="60%" align="center">Appendix H. External Projects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="external-extensions.html" title="H.4. Extensions">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTERNAL-PL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">H.3. Procedural Languages</h2></div></div></div><a id="id-1.11.9.5.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> includes several procedural
+ languages with the base distribution: <a class="link" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">PL/pgSQL</a>, <a class="link" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">PL/Tcl</a>,
+ <a class="link" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">PL/Perl</a>, and <a class="link" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">PL/Python</a>.
+ </p><p>
+ In addition, there are a number of procedural languages that are developed
+ and maintained outside the core <span class="productname">PostgreSQL</span>
+ distribution. A list of
+ <a class="ulink" href="https://wiki.postgresql.org/wiki/PL_Matrix" target="_top">procedural languages</a>
+ is maintained on the PostgreSQL wiki. Note that some of these projects are
+ not released under the same license as <span class="productname">PostgreSQL</span>.
+ For more information on each procedural language, including licensing
+ information, refer to its website
+ and documentation.
+ </p><p>
+ <a class="ulink" href="https://wiki.postgresql.org/wiki/PL_Matrix" target="_top">https://wiki.postgresql.org/wiki/PL_Matrix</a>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="external-admin-tools.html" title="H.2. Administration Tools">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="external-projects.html" title="Appendix H. External Projects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="external-extensions.html" title="H.4. Extensions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">H.2. Administration Tools </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> H.4. Extensions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/external-projects.html b/doc/src/sgml/html/external-projects.html
new file mode 100644
index 0000000..f4c9706
--- /dev/null
+++ b/doc/src/sgml/html/external-projects.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix H. External Projects</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-prog-server.html" title="G.2. Server Applications" /><link rel="next" href="external-interfaces.html" title="H.1. Client Interfaces" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix H. External Projects</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-prog-server.html" title="G.2. Server Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="external-interfaces.html" title="H.1. Client Interfaces">Next</a></td></tr></table><hr /></div><div class="appendix" id="EXTERNAL-PROJECTS"><div class="titlepage"><div><div><h2 class="title">Appendix H. External Projects</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="external-interfaces.html">H.1. Client Interfaces</a></span></dt><dt><span class="sect1"><a href="external-admin-tools.html">H.2. Administration Tools</a></span></dt><dt><span class="sect1"><a href="external-pl.html">H.3. Procedural Languages</a></span></dt><dt><span class="sect1"><a href="external-extensions.html">H.4. Extensions</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> is a complex software project,
+ and managing the project is difficult. We have found that many
+ enhancements to <span class="productname">PostgreSQL</span> can be more
+ efficiently developed separately from the core project.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-prog-server.html" title="G.2. Server Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="external-interfaces.html" title="H.1. Client Interfaces">Next</a></td></tr><tr><td width="40%" align="left" valign="top">G.2. Server Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> H.1. Client Interfaces</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdw-callbacks.html b/doc/src/sgml/html/fdw-callbacks.html
new file mode 100644
index 0000000..a515df6
--- /dev/null
+++ b/doc/src/sgml/html/fdw-callbacks.html
@@ -0,0 +1,1257 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>59.2. Foreign Data Wrapper Callback Routines</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions" /><link rel="next" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">59.2. Foreign Data Wrapper Callback Routines</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><th width="60%" align="center">Chapter 59. Writing a Foreign Data Wrapper</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FDW-CALLBACKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">59.2. Foreign Data Wrapper Callback Routines</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-SCAN">59.2.1. FDW Routines for Scanning Foreign Tables</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-JOIN-SCAN">59.2.2. FDW Routines for Scanning Foreign Joins</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-UPPER-PLANNING">59.2.3. FDW Routines for Planning Post-Scan/Join Processing</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-UPDATE">59.2.4. FDW Routines for Updating Foreign Tables</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-TRUNCATE">59.2.5. FDW Routines for <code class="command">TRUNCATE</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ROW-LOCKING">59.2.6. FDW Routines for Row Locking</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-EXPLAIN">59.2.7. FDW Routines for <code class="command">EXPLAIN</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ANALYZE">59.2.8. FDW Routines for <code class="command">ANALYZE</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-IMPORT">59.2.9. FDW Routines for <code class="command">IMPORT FOREIGN SCHEMA</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-PARALLEL">59.2.10. FDW Routines for Parallel Execution</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ASYNC">59.2.11. FDW Routines for Asynchronous Execution</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-REPARAMETERIZE-PATHS">59.2.12. FDW Routines for Reparameterization of Paths</a></span></dt></dl></div><p>
+ The FDW handler function returns a palloc'd <code class="structname">FdwRoutine</code>
+ struct containing pointers to the callback functions described below.
+ The scan-related functions are required, the rest are optional.
+ </p><p>
+ The <code class="structname">FdwRoutine</code> struct type is declared in
+ <code class="filename">src/include/foreign/fdwapi.h</code>, which see for additional
+ details.
+ </p><div class="sect2" id="FDW-CALLBACKS-SCAN"><div class="titlepage"><div><div><h3 class="title">59.2.1. FDW Routines for Scanning Foreign Tables</h3></div></div></div><p>
+</p><pre class="programlisting">
+void
+GetForeignRelSize(PlannerInfo *root,
+ RelOptInfo *baserel,
+ Oid foreigntableid);
+</pre><p>
+
+ Obtain relation size estimates for a foreign table. This is called
+ at the beginning of planning for a query that scans a foreign table.
+ <code class="literal">root</code> is the planner's global information about the query;
+ <code class="literal">baserel</code> is the planner's information about this table; and
+ <code class="literal">foreigntableid</code> is the <code class="structname">pg_class</code> OID of the
+ foreign table. (<code class="literal">foreigntableid</code> could be obtained from the
+ planner data structures, but it's passed explicitly to save effort.)
+ </p><p>
+ This function should update <code class="literal">baserel-&gt;rows</code> to be the
+ expected number of rows returned by the table scan, after accounting for
+ the filtering done by the restriction quals. The initial value of
+ <code class="literal">baserel-&gt;rows</code> is just a constant default estimate, which
+ should be replaced if at all possible. The function may also choose to
+ update <code class="literal">baserel-&gt;width</code> if it can compute a better estimate
+ of the average result row width.
+ (The initial value is based on column data types and on column
+ average-width values measured by the last <code class="command">ANALYZE</code>.)
+ Also, this function may update <code class="literal">baserel-&gt;tuples</code> if
+ it can compute a better estimate of the foreign table's total row count.
+ (The initial value is
+ from <code class="structname">pg_class</code>.<code class="structfield">reltuples</code>
+ which represents the total row count seen by the
+ last <code class="command">ANALYZE</code>; it will be <code class="literal">-1</code> if
+ no <code class="command">ANALYZE</code> has been done on this foreign table.)
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p><p>
+</p><pre class="programlisting">
+void
+GetForeignPaths(PlannerInfo *root,
+ RelOptInfo *baserel,
+ Oid foreigntableid);
+</pre><p>
+
+ Create possible access paths for a scan on a foreign table.
+ This is called during query planning.
+ The parameters are the same as for <code class="function">GetForeignRelSize</code>,
+ which has already been called.
+ </p><p>
+ This function must generate at least one access path
+ (<code class="structname">ForeignPath</code> node) for a scan on the foreign table and
+ must call <code class="function">add_path</code> to add each such path to
+ <code class="literal">baserel-&gt;pathlist</code>. It's recommended to use
+ <code class="function">create_foreignscan_path</code> to build the
+ <code class="structname">ForeignPath</code> nodes. The function can generate multiple
+ access paths, e.g., a path which has valid <code class="literal">pathkeys</code> to
+ represent a pre-sorted result. Each access path must contain cost
+ estimates, and can contain any FDW-private information that is needed to
+ identify the specific scan method intended.
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p><p>
+</p><pre class="programlisting">
+ForeignScan *
+GetForeignPlan(PlannerInfo *root,
+ RelOptInfo *baserel,
+ Oid foreigntableid,
+ ForeignPath *best_path,
+ List *tlist,
+ List *scan_clauses,
+ Plan *outer_plan);
+</pre><p>
+
+ Create a <code class="structname">ForeignScan</code> plan node from the selected foreign
+ access path. This is called at the end of query planning.
+ The parameters are as for <code class="function">GetForeignRelSize</code>, plus
+ the selected <code class="structname">ForeignPath</code> (previously produced by
+ <code class="function">GetForeignPaths</code>, <code class="function">GetForeignJoinPaths</code>,
+ or <code class="function">GetForeignUpperPaths</code>),
+ the target list to be emitted by the plan node,
+ the restriction clauses to be enforced by the plan node,
+ and the outer subplan of the <code class="structname">ForeignScan</code>,
+ which is used for rechecks performed by <code class="function">RecheckForeignScan</code>.
+ (If the path is for a join rather than a base
+ relation, <code class="literal">foreigntableid</code> is <code class="literal">InvalidOid</code>.)
+ </p><p>
+ This function must create and return a <code class="structname">ForeignScan</code> plan
+ node; it's recommended to use <code class="function">make_foreignscan</code> to build the
+ <code class="structname">ForeignScan</code> node.
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p><p>
+</p><pre class="programlisting">
+void
+BeginForeignScan(ForeignScanState *node,
+ int eflags);
+</pre><p>
+
+ Begin executing a foreign scan. This is called during executor startup.
+ It should perform any initialization needed before the scan can start,
+ but not start executing the actual scan (that should be done upon the
+ first call to <code class="function">IterateForeignScan</code>).
+ The <code class="structname">ForeignScanState</code> node has already been created, but
+ its <code class="structfield">fdw_state</code> field is still NULL. Information about
+ the table to scan is accessible through the
+ <code class="structname">ForeignScanState</code> node (in particular, from the underlying
+ <code class="structname">ForeignScan</code> plan node, which contains any FDW-private
+ information provided by <code class="function">GetForeignPlan</code>).
+ <code class="literal">eflags</code> contains flag bits describing the executor's
+ operating mode for this plan node.
+ </p><p>
+ Note that when <code class="literal">(eflags &amp; EXEC_FLAG_EXPLAIN_ONLY)</code> is
+ true, this function should not perform any externally-visible actions;
+ it should only do the minimum required to make the node state valid
+ for <code class="function">ExplainForeignScan</code> and <code class="function">EndForeignScan</code>.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *
+IterateForeignScan(ForeignScanState *node);
+</pre><p>
+
+ Fetch one row from the foreign source, returning it in a tuple table slot
+ (the node's <code class="structfield">ScanTupleSlot</code> should be used for this
+ purpose). Return NULL if no more rows are available. The tuple table
+ slot infrastructure allows either a physical or virtual tuple to be
+ returned; in most cases the latter choice is preferable from a
+ performance standpoint. Note that this is called in a short-lived memory
+ context that will be reset between invocations. Create a memory context
+ in <code class="function">BeginForeignScan</code> if you need longer-lived storage, or use
+ the <code class="structfield">es_query_cxt</code> of the node's <code class="structname">EState</code>.
+ </p><p>
+ The rows returned must match the <code class="structfield">fdw_scan_tlist</code> target
+ list if one was supplied, otherwise they must match the row type of the
+ foreign table being scanned. If you choose to optimize away fetching
+ columns that are not needed, you should insert nulls in those column
+ positions, or else generate a <code class="structfield">fdw_scan_tlist</code> list with
+ those columns omitted.
+ </p><p>
+ Note that <span class="productname">PostgreSQL</span>'s executor doesn't care
+ whether the rows returned violate any constraints that were defined on
+ the foreign table — but the planner does care, and may optimize
+ queries incorrectly if there are rows visible in the foreign table that
+ do not satisfy a declared constraint. If a constraint is violated when
+ the user has declared that the constraint should hold true, it may be
+ appropriate to raise an error (just as you would need to do in the case
+ of a data type mismatch).
+ </p><p>
+</p><pre class="programlisting">
+void
+ReScanForeignScan(ForeignScanState *node);
+</pre><p>
+
+ Restart the scan from the beginning. Note that any parameters the
+ scan depends on may have changed value, so the new scan does not
+ necessarily return exactly the same rows.
+ </p><p>
+</p><pre class="programlisting">
+void
+EndForeignScan(ForeignScanState *node);
+</pre><p>
+
+ End the scan and release resources. It is normally not important
+ to release palloc'd memory, but for example open files and connections
+ to remote servers should be cleaned up.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-JOIN-SCAN"><div class="titlepage"><div><div><h3 class="title">59.2.2. FDW Routines for Scanning Foreign Joins</h3></div></div></div><p>
+ If an FDW supports performing foreign joins remotely (rather than
+ by fetching both tables' data and doing the join locally), it should
+ provide this callback function:
+ </p><p>
+</p><pre class="programlisting">
+void
+GetForeignJoinPaths(PlannerInfo *root,
+ RelOptInfo *joinrel,
+ RelOptInfo *outerrel,
+ RelOptInfo *innerrel,
+ JoinType jointype,
+ JoinPathExtraData *extra);
+</pre><p>
+ Create possible access paths for a join of two (or more) foreign tables
+ that all belong to the same foreign server. This optional
+ function is called during query planning. As
+ with <code class="function">GetForeignPaths</code>, this function should
+ generate <code class="structname">ForeignPath</code> path(s) for the
+ supplied <code class="literal">joinrel</code>
+ (use <code class="function">create_foreign_join_path</code> to build them),
+ and call <code class="function">add_path</code> to add these
+ paths to the set of paths considered for the join. But unlike
+ <code class="function">GetForeignPaths</code>, it is not necessary that this function
+ succeed in creating at least one path, since paths involving local
+ joining are always possible.
+ </p><p>
+ Note that this function will be invoked repeatedly for the same join
+ relation, with different combinations of inner and outer relations; it is
+ the responsibility of the FDW to minimize duplicated work.
+ </p><p>
+ If a <code class="structname">ForeignPath</code> path is chosen for the join, it will
+ represent the entire join process; paths generated for the component
+ tables and subsidiary joins will not be used. Subsequent processing of
+ the join path proceeds much as it does for a path scanning a single
+ foreign table. One difference is that the <code class="structfield">scanrelid</code> of
+ the resulting <code class="structname">ForeignScan</code> plan node should be set to zero,
+ since there is no single relation that it represents; instead,
+ the <code class="structfield">fs_relids</code> field of the <code class="structname">ForeignScan</code>
+ node represents the set of relations that were joined. (The latter field
+ is set up automatically by the core planner code, and need not be filled
+ by the FDW.) Another difference is that, because the column list for a
+ remote join cannot be found from the system catalogs, the FDW must
+ fill <code class="structfield">fdw_scan_tlist</code> with an appropriate list
+ of <code class="structfield">TargetEntry</code> nodes, representing the set of columns
+ it will supply at run time in the tuples it returns.
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-UPPER-PLANNING"><div class="titlepage"><div><div><h3 class="title">59.2.3. FDW Routines for Planning Post-Scan/Join Processing</h3></div></div></div><p>
+ If an FDW supports performing remote post-scan/join processing, such as
+ remote aggregation, it should provide this callback function:
+ </p><p>
+</p><pre class="programlisting">
+void
+GetForeignUpperPaths(PlannerInfo *root,
+ UpperRelationKind stage,
+ RelOptInfo *input_rel,
+ RelOptInfo *output_rel,
+ void *extra);
+</pre><p>
+ Create possible access paths for <em class="firstterm">upper relation</em> processing,
+ which is the planner's term for all post-scan/join query processing, such
+ as aggregation, window functions, sorting, and table updates. This
+ optional function is called during query planning. Currently, it is
+ called only if all base relation(s) involved in the query belong to the
+ same FDW. This function should generate <code class="structname">ForeignPath</code>
+ path(s) for any post-scan/join processing that the FDW knows how to
+ perform remotely
+ (use <code class="function">create_foreign_upper_path</code> to build them),
+ and call <code class="function">add_path</code> to add these paths to
+ the indicated upper relation. As with <code class="function">GetForeignJoinPaths</code>,
+ it is not necessary that this function succeed in creating any paths,
+ since paths involving local processing are always possible.
+ </p><p>
+ The <code class="literal">stage</code> parameter identifies which post-scan/join step is
+ currently being considered. <code class="literal">output_rel</code> is the upper relation
+ that should receive paths representing computation of this step,
+ and <code class="literal">input_rel</code> is the relation representing the input to this
+ step. The <code class="literal">extra</code> parameter provides additional details,
+ currently, it is set only for <code class="literal">UPPERREL_PARTIAL_GROUP_AGG</code>
+ or <code class="literal">UPPERREL_GROUP_AGG</code>, in which case it points to a
+ <code class="literal">GroupPathExtraData</code> structure;
+ or for <code class="literal">UPPERREL_FINAL</code>, in which case it points to a
+ <code class="literal">FinalPathExtraData</code> structure.
+ (Note that <code class="structname">ForeignPath</code> paths added
+ to <code class="literal">output_rel</code> would typically not have any direct dependency
+ on paths of the <code class="literal">input_rel</code>, since their processing is expected
+ to be done externally. However, examining paths previously generated for
+ the previous processing step can be useful to avoid redundant planning
+ work.)
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-UPDATE"><div class="titlepage"><div><div><h3 class="title">59.2.4. FDW Routines for Updating Foreign Tables</h3></div></div></div><p>
+ If an FDW supports writable foreign tables, it should provide
+ some or all of the following callback functions depending on
+ the needs and capabilities of the FDW:
+ </p><p>
+</p><pre class="programlisting">
+void
+AddForeignUpdateTargets(PlannerInfo *root,
+ Index rtindex,
+ RangeTblEntry *target_rte,
+ Relation target_relation);
+</pre><p>
+
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code> operations are performed
+ against rows previously fetched by the table-scanning functions. The
+ FDW may need extra information, such as a row ID or the values of
+ primary-key columns, to ensure that it can identify the exact row to
+ update or delete. To support that, this function can add extra hidden,
+ or <span class="quote">“<span class="quote">junk</span>”</span>, target columns to the list of columns that are to be
+ retrieved from the foreign table during an <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code>.
+ </p><p>
+ To do that, construct a <code class="structname">Var</code> representing
+ an extra value you need, and pass it
+ to <code class="function">add_row_identity_var</code>, along with a name for
+ the junk column. (You can do this more than once if several columns
+ are needed.) You must choose a distinct junk column name for each
+ different <code class="structname">Var</code> you need, except
+ that <code class="structname">Var</code>s that are identical except for
+ the <code class="structfield">varno</code> field can and should share a
+ column name.
+ The core system uses the junk column names
+ <code class="literal">tableoid</code> for a
+ table's <code class="structfield">tableoid</code> column,
+ <code class="literal">ctid</code>
+ or <code class="literal">ctid<em class="replaceable"><code>N</code></em></code>
+ for <code class="structfield">ctid</code>,
+ <code class="literal">wholerow</code>
+ for a whole-row <code class="structname">Var</code> marked with
+ <code class="structfield">vartype</code> = <code class="type">RECORD</code>,
+ and <code class="literal">wholerow<em class="replaceable"><code>N</code></em></code>
+ for a whole-row <code class="structname">Var</code> with
+ <code class="structfield">vartype</code> equal to the table's declared row type.
+ Re-use these names when you can (the planner will combine duplicate
+ requests for identical junk columns). If you need another kind of
+ junk column besides these, it might be wise to choose a name prefixed
+ with your extension name, to avoid conflicts against other FDWs.
+ </p><p>
+ If the <code class="function">AddForeignUpdateTargets</code> pointer is set to
+ <code class="literal">NULL</code>, no extra target expressions are added.
+ (This will make it impossible to implement <code class="command">DELETE</code>
+ operations, though <code class="command">UPDATE</code> may still be feasible if the FDW
+ relies on an unchanging primary key to identify rows.)
+ </p><p>
+</p><pre class="programlisting">
+List *
+PlanForeignModify(PlannerInfo *root,
+ ModifyTable *plan,
+ Index resultRelation,
+ int subplan_index);
+</pre><p>
+
+ Perform any additional planning actions needed for an insert, update, or
+ delete on a foreign table. This function generates the FDW-private
+ information that will be attached to the <code class="structname">ModifyTable</code> plan
+ node that performs the update action. This private information must
+ have the form of a <code class="literal">List</code>, and will be delivered to
+ <code class="function">BeginForeignModify</code> during the execution stage.
+ </p><p>
+ <code class="literal">root</code> is the planner's global information about the query.
+ <code class="literal">plan</code> is the <code class="structname">ModifyTable</code> plan node, which is
+ complete except for the <code class="structfield">fdwPrivLists</code> field.
+ <code class="literal">resultRelation</code> identifies the target foreign table by its
+ range table index. <code class="literal">subplan_index</code> identifies which target of
+ the <code class="structname">ModifyTable</code> plan node this is, counting from zero;
+ use this if you want to index into per-target-relation substructures of the
+ <code class="literal">plan</code> node.
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p><p>
+ If the <code class="function">PlanForeignModify</code> pointer is set to
+ <code class="literal">NULL</code>, no additional plan-time actions are taken, and the
+ <code class="literal">fdw_private</code> list delivered to
+ <code class="function">BeginForeignModify</code> will be NIL.
+ </p><p>
+</p><pre class="programlisting">
+void
+BeginForeignModify(ModifyTableState *mtstate,
+ ResultRelInfo *rinfo,
+ List *fdw_private,
+ int subplan_index,
+ int eflags);
+</pre><p>
+
+ Begin executing a foreign table modification operation. This routine is
+ called during executor startup. It should perform any initialization
+ needed prior to the actual table modifications. Subsequently,
+ <code class="function">ExecForeignInsert/ExecForeignBatchInsert</code>,
+ <code class="function">ExecForeignUpdate</code> or
+ <code class="function">ExecForeignDelete</code> will be called for tuple(s) to be
+ inserted, updated, or deleted.
+ </p><p>
+ <code class="literal">mtstate</code> is the overall state of the
+ <code class="structname">ModifyTable</code> plan node being executed; global data about
+ the plan and execution state is available via this structure.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table. (The <code class="structfield">ri_FdwState</code> field of
+ <code class="structname">ResultRelInfo</code> is available for the FDW to store any
+ private state it needs for this operation.)
+ <code class="literal">fdw_private</code> contains the private data generated by
+ <code class="function">PlanForeignModify</code>, if any.
+ <code class="literal">subplan_index</code> identifies which target of
+ the <code class="structname">ModifyTable</code> plan node this is.
+ <code class="literal">eflags</code> contains flag bits describing the executor's
+ operating mode for this plan node.
+ </p><p>
+ Note that when <code class="literal">(eflags &amp; EXEC_FLAG_EXPLAIN_ONLY)</code> is
+ true, this function should not perform any externally-visible actions;
+ it should only do the minimum required to make the node state valid
+ for <code class="function">ExplainForeignModify</code> and <code class="function">EndForeignModify</code>.
+ </p><p>
+ If the <code class="function">BeginForeignModify</code> pointer is set to
+ <code class="literal">NULL</code>, no action is taken during executor startup.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *
+ExecForeignInsert(EState *estate,
+ ResultRelInfo *rinfo,
+ TupleTableSlot *slot,
+ TupleTableSlot *planSlot);
+</pre><p>
+
+ Insert one tuple into the foreign table.
+ <code class="literal">estate</code> is global execution state for the query.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table.
+ <code class="literal">slot</code> contains the tuple to be inserted; it will match the
+ row-type definition of the foreign table.
+ <code class="literal">planSlot</code> contains the tuple that was generated by the
+ <code class="structname">ModifyTable</code> plan node's subplan; it differs from
+ <code class="literal">slot</code> in possibly containing additional <span class="quote">“<span class="quote">junk</span>”</span>
+ columns. (The <code class="literal">planSlot</code> is typically of little interest
+ for <code class="command">INSERT</code> cases, but is provided for completeness.)
+ </p><p>
+ The return value is either a slot containing the data that was actually
+ inserted (this might differ from the data supplied, for example as a
+ result of trigger actions), or NULL if no row was actually inserted
+ (again, typically as a result of triggers). The passed-in
+ <code class="literal">slot</code> can be re-used for this purpose.
+ </p><p>
+ The data in the returned slot is used only if the <code class="command">INSERT</code>
+ statement has a <code class="literal">RETURNING</code> clause or involves a view
+ <code class="literal">WITH CHECK OPTION</code>; or if the foreign table has
+ an <code class="literal">AFTER ROW</code> trigger. Triggers require all columns,
+ but the FDW could choose to optimize away returning some or all columns
+ depending on the contents of the <code class="literal">RETURNING</code> clause or
+ <code class="literal">WITH CHECK OPTION</code> constraints. Regardless, some slot
+ must be returned to indicate success, or the query's reported row count
+ will be wrong.
+ </p><p>
+ If the <code class="function">ExecForeignInsert</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to insert into the foreign table will fail
+ with an error message.
+ </p><p>
+ Note that this function is also called when inserting routed tuples into
+ a foreign-table partition or executing <code class="command">COPY FROM</code> on
+ a foreign table, in which case it is called in a different way than it
+ is in the <code class="command">INSERT</code> case. See the callback functions
+ described below that allow the FDW to support that.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot **
+ExecForeignBatchInsert(EState *estate,
+ ResultRelInfo *rinfo,
+ TupleTableSlot **slots,
+ TupleTableSlot **planSlots,
+ int *numSlots);
+</pre><p>
+
+ Insert multiple tuples in bulk into the foreign table.
+ The parameters are the same for <code class="function">ExecForeignInsert</code>
+ except <code class="literal">slots</code> and <code class="literal">planSlots</code> contain
+ multiple tuples and <code class="literal">*numSlots</code> specifies the number of
+ tuples in those arrays.
+ </p><p>
+ The return value is an array of slots containing the data that was
+ actually inserted (this might differ from the data supplied, for
+ example as a result of trigger actions.)
+ The passed-in <code class="literal">slots</code> can be re-used for this purpose.
+ The number of successfully inserted tuples is returned in
+ <code class="literal">*numSlots</code>.
+ </p><p>
+ The data in the returned slot is used only if the <code class="command">INSERT</code>
+ statement involves a view
+ <code class="literal">WITH CHECK OPTION</code>; or if the foreign table has
+ an <code class="literal">AFTER ROW</code> trigger. Triggers require all columns,
+ but the FDW could choose to optimize away returning some or all columns
+ depending on the contents of the
+ <code class="literal">WITH CHECK OPTION</code> constraints.
+ </p><p>
+ If the <code class="function">ExecForeignBatchInsert</code> or
+ <code class="function">GetForeignModifyBatchSize</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to insert into the foreign table will
+ use <code class="function">ExecForeignInsert</code>.
+ This function is not used if the <code class="command">INSERT</code> has the
+ <code class="literal">RETURNING</code> clause.
+ </p><p>
+ Note that this function is also called when inserting routed tuples into
+ a foreign-table partition. See the callback functions
+ described below that allow the FDW to support that.
+ </p><p>
+</p><pre class="programlisting">
+int
+GetForeignModifyBatchSize(ResultRelInfo *rinfo);
+</pre><p>
+
+ Report the maximum number of tuples that a single
+ <code class="function">ExecForeignBatchInsert</code> call can handle for
+ the specified foreign table. The executor passes at most
+ the given number of tuples to <code class="function">ExecForeignBatchInsert</code>.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table.
+ The FDW is expected to provide a foreign server and/or foreign
+ table option for the user to set this value, or some hard-coded value.
+ </p><p>
+ If the <code class="function">ExecForeignBatchInsert</code> or
+ <code class="function">GetForeignModifyBatchSize</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to insert into the foreign table will
+ use <code class="function">ExecForeignInsert</code>.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *
+ExecForeignUpdate(EState *estate,
+ ResultRelInfo *rinfo,
+ TupleTableSlot *slot,
+ TupleTableSlot *planSlot);
+</pre><p>
+
+ Update one tuple in the foreign table.
+ <code class="literal">estate</code> is global execution state for the query.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table.
+ <code class="literal">slot</code> contains the new data for the tuple; it will match the
+ row-type definition of the foreign table.
+ <code class="literal">planSlot</code> contains the tuple that was generated by the
+ <code class="structname">ModifyTable</code> plan node's subplan. Unlike
+ <code class="literal">slot</code>, this tuple contains only the new values for
+ columns changed by the query, so do not rely on attribute numbers of the
+ foreign table to index into <code class="literal">planSlot</code>.
+ Also, <code class="literal">planSlot</code> typically contains
+ additional <span class="quote">“<span class="quote">junk</span>”</span> columns. In particular, any junk columns
+ that were requested by <code class="function">AddForeignUpdateTargets</code> will
+ be available from this slot.
+ </p><p>
+ The return value is either a slot containing the row as it was actually
+ updated (this might differ from the data supplied, for example as a
+ result of trigger actions), or NULL if no row was actually updated
+ (again, typically as a result of triggers). The passed-in
+ <code class="literal">slot</code> can be re-used for this purpose.
+ </p><p>
+ The data in the returned slot is used only if the <code class="command">UPDATE</code>
+ statement has a <code class="literal">RETURNING</code> clause or involves a view
+ <code class="literal">WITH CHECK OPTION</code>; or if the foreign table has
+ an <code class="literal">AFTER ROW</code> trigger. Triggers require all columns,
+ but the FDW could choose to optimize away returning some or all columns
+ depending on the contents of the <code class="literal">RETURNING</code> clause or
+ <code class="literal">WITH CHECK OPTION</code> constraints. Regardless, some slot
+ must be returned to indicate success, or the query's reported row count
+ will be wrong.
+ </p><p>
+ If the <code class="function">ExecForeignUpdate</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to update the foreign table will fail
+ with an error message.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *
+ExecForeignDelete(EState *estate,
+ ResultRelInfo *rinfo,
+ TupleTableSlot *slot,
+ TupleTableSlot *planSlot);
+</pre><p>
+
+ Delete one tuple from the foreign table.
+ <code class="literal">estate</code> is global execution state for the query.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table.
+ <code class="literal">slot</code> contains nothing useful upon call, but can be used to
+ hold the returned tuple.
+ <code class="literal">planSlot</code> contains the tuple that was generated by the
+ <code class="structname">ModifyTable</code> plan node's subplan; in particular, it will
+ carry any junk columns that were requested by
+ <code class="function">AddForeignUpdateTargets</code>. The junk column(s) must be used
+ to identify the tuple to be deleted.
+ </p><p>
+ The return value is either a slot containing the row that was deleted,
+ or NULL if no row was deleted (typically as a result of triggers). The
+ passed-in <code class="literal">slot</code> can be used to hold the tuple to be returned.
+ </p><p>
+ The data in the returned slot is used only if the <code class="command">DELETE</code>
+ query has a <code class="literal">RETURNING</code> clause or the foreign table has
+ an <code class="literal">AFTER ROW</code> trigger. Triggers require all columns, but the
+ FDW could choose to optimize away returning some or all columns depending
+ on the contents of the <code class="literal">RETURNING</code> clause. Regardless, some
+ slot must be returned to indicate success, or the query's reported row
+ count will be wrong.
+ </p><p>
+ If the <code class="function">ExecForeignDelete</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to delete from the foreign table will fail
+ with an error message.
+ </p><p>
+</p><pre class="programlisting">
+void
+EndForeignModify(EState *estate,
+ ResultRelInfo *rinfo);
+</pre><p>
+
+ End the table update and release resources. It is normally not important
+ to release palloc'd memory, but for example open files and connections
+ to remote servers should be cleaned up.
+ </p><p>
+ If the <code class="function">EndForeignModify</code> pointer is set to
+ <code class="literal">NULL</code>, no action is taken during executor shutdown.
+ </p><p>
+ Tuples inserted into a partitioned table by <code class="command">INSERT</code> or
+ <code class="command">COPY FROM</code> are routed to partitions. If an FDW
+ supports routable foreign-table partitions, it should also provide the
+ following callback functions. These functions are also called when
+ <code class="command">COPY FROM</code> is executed on a foreign table.
+ </p><p>
+</p><pre class="programlisting">
+void
+BeginForeignInsert(ModifyTableState *mtstate,
+ ResultRelInfo *rinfo);
+</pre><p>
+
+ Begin executing an insert operation on a foreign table. This routine is
+ called right before the first tuple is inserted into the foreign table
+ in both cases when it is the partition chosen for tuple routing and the
+ target specified in a <code class="command">COPY FROM</code> command. It should
+ perform any initialization needed prior to the actual insertion.
+ Subsequently, <code class="function">ExecForeignInsert</code> or
+ <code class="function">ExecForeignBatchInsert</code> will be called for
+ tuple(s) to be inserted into the foreign table.
+ </p><p>
+ <code class="literal">mtstate</code> is the overall state of the
+ <code class="structname">ModifyTable</code> plan node being executed; global data about
+ the plan and execution state is available via this structure.
+ <code class="literal">rinfo</code> is the <code class="structname">ResultRelInfo</code> struct describing
+ the target foreign table. (The <code class="structfield">ri_FdwState</code> field of
+ <code class="structname">ResultRelInfo</code> is available for the FDW to store any
+ private state it needs for this operation.)
+ </p><p>
+ When this is called by a <code class="command">COPY FROM</code> command, the
+ plan-related global data in <code class="literal">mtstate</code> is not provided
+ and the <code class="literal">planSlot</code> parameter of
+ <code class="function">ExecForeignInsert</code> subsequently called for each
+ inserted tuple is <code class="literal">NULL</code>, whether the foreign table is
+ the partition chosen for tuple routing or the target specified in the
+ command.
+ </p><p>
+ If the <code class="function">BeginForeignInsert</code> pointer is set to
+ <code class="literal">NULL</code>, no action is taken for the initialization.
+ </p><p>
+ Note that if the FDW does not support routable foreign-table partitions
+ and/or executing <code class="command">COPY FROM</code> on foreign tables, this
+ function or <code class="function">ExecForeignInsert/ExecForeignBatchInsert</code>
+ subsequently called must throw error as needed.
+ </p><p>
+</p><pre class="programlisting">
+void
+EndForeignInsert(EState *estate,
+ ResultRelInfo *rinfo);
+</pre><p>
+
+ End the insert operation and release resources. It is normally not important
+ to release palloc'd memory, but for example open files and connections
+ to remote servers should be cleaned up.
+ </p><p>
+ If the <code class="function">EndForeignInsert</code> pointer is set to
+ <code class="literal">NULL</code>, no action is taken for the termination.
+ </p><p>
+</p><pre class="programlisting">
+int
+IsForeignRelUpdatable(Relation rel);
+</pre><p>
+
+ Report which update operations the specified foreign table supports.
+ The return value should be a bit mask of rule event numbers indicating
+ which operations are supported by the foreign table, using the
+ <code class="literal">CmdType</code> enumeration; that is,
+ <code class="literal">(1 &lt;&lt; CMD_UPDATE) = 4</code> for <code class="command">UPDATE</code>,
+ <code class="literal">(1 &lt;&lt; CMD_INSERT) = 8</code> for <code class="command">INSERT</code>, and
+ <code class="literal">(1 &lt;&lt; CMD_DELETE) = 16</code> for <code class="command">DELETE</code>.
+ </p><p>
+ If the <code class="function">IsForeignRelUpdatable</code> pointer is set to
+ <code class="literal">NULL</code>, foreign tables are assumed to be insertable, updatable,
+ or deletable if the FDW provides <code class="function">ExecForeignInsert</code>,
+ <code class="function">ExecForeignUpdate</code>, or <code class="function">ExecForeignDelete</code>
+ respectively. This function is only needed if the FDW supports some
+ tables that are updatable and some that are not. (Even then, it's
+ permissible to throw an error in the execution routine instead of
+ checking in this function. However, this function is used to determine
+ updatability for display in the <code class="literal">information_schema</code> views.)
+ </p><p>
+ Some inserts, updates, and deletes to foreign tables can be optimized
+ by implementing an alternative set of interfaces. The ordinary
+ interfaces for inserts, updates, and deletes fetch rows from the remote
+ server and then modify those rows one at a time. In some cases, this
+ row-by-row approach is necessary, but it can be inefficient. If it is
+ possible for the foreign server to determine which rows should be
+ modified without actually retrieving them, and if there are no local
+ structures which would affect the operation (row-level local triggers,
+ stored generated columns, or <code class="literal">WITH CHECK OPTION</code>
+ constraints from parent views), then it is possible to arrange things
+ so that the entire operation is performed on the remote server. The
+ interfaces described below make this possible.
+ </p><p>
+</p><pre class="programlisting">
+bool
+PlanDirectModify(PlannerInfo *root,
+ ModifyTable *plan,
+ Index resultRelation,
+ int subplan_index);
+</pre><p>
+
+ Decide whether it is safe to execute a direct modification
+ on the remote server. If so, return <code class="literal">true</code> after performing
+ planning actions needed for that. Otherwise, return <code class="literal">false</code>.
+ This optional function is called during query planning.
+ If this function succeeds, <code class="function">BeginDirectModify</code>,
+ <code class="function">IterateDirectModify</code> and <code class="function">EndDirectModify</code> will
+ be called at the execution stage, instead. Otherwise, the table
+ modification will be executed using the table-updating functions
+ described above.
+ The parameters are the same as for <code class="function">PlanForeignModify</code>.
+ </p><p>
+ To execute the direct modification on the remote server, this function
+ must rewrite the target subplan with a <code class="structname">ForeignScan</code> plan
+ node that executes the direct modification on the remote server. The
+ <code class="structfield">operation</code> and <code class="structfield">resultRelation</code> fields
+ of the <code class="structname">ForeignScan</code> must be set appropriately.
+ <code class="structfield">operation</code> must be set to the <code class="literal">CmdType</code>
+ enumeration corresponding to the statement kind (that is,
+ <code class="literal">CMD_UPDATE</code> for <code class="command">UPDATE</code>,
+ <code class="literal">CMD_INSERT</code> for <code class="command">INSERT</code>, and
+ <code class="literal">CMD_DELETE</code> for <code class="command">DELETE</code>), and the
+ <code class="literal">resultRelation</code> argument must be copied to the
+ <code class="structfield">resultRelation</code> field.
+ </p><p>
+ See <a class="xref" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Section 59.4</a> for additional information.
+ </p><p>
+ If the <code class="function">PlanDirectModify</code> pointer is set to
+ <code class="literal">NULL</code>, no attempts to execute a direct modification on the
+ remote server are taken.
+ </p><p>
+</p><pre class="programlisting">
+void
+BeginDirectModify(ForeignScanState *node,
+ int eflags);
+</pre><p>
+
+ Prepare to execute a direct modification on the remote server.
+ This is called during executor startup. It should perform any
+ initialization needed prior to the direct modification (that should be
+ done upon the first call to <code class="function">IterateDirectModify</code>).
+ The <code class="structname">ForeignScanState</code> node has already been created, but
+ its <code class="structfield">fdw_state</code> field is still NULL. Information about
+ the table to modify is accessible through the
+ <code class="structname">ForeignScanState</code> node (in particular, from the underlying
+ <code class="structname">ForeignScan</code> plan node, which contains any FDW-private
+ information provided by <code class="function">PlanDirectModify</code>).
+ <code class="literal">eflags</code> contains flag bits describing the executor's
+ operating mode for this plan node.
+ </p><p>
+ Note that when <code class="literal">(eflags &amp; EXEC_FLAG_EXPLAIN_ONLY)</code> is
+ true, this function should not perform any externally-visible actions;
+ it should only do the minimum required to make the node state valid
+ for <code class="function">ExplainDirectModify</code> and <code class="function">EndDirectModify</code>.
+ </p><p>
+ If the <code class="function">BeginDirectModify</code> pointer is set to
+ <code class="literal">NULL</code>, no attempts to execute a direct modification on the
+ remote server are taken.
+ </p><p>
+</p><pre class="programlisting">
+TupleTableSlot *
+IterateDirectModify(ForeignScanState *node);
+</pre><p>
+
+ When the <code class="command">INSERT</code>, <code class="command">UPDATE</code> or <code class="command">DELETE</code>
+ query doesn't have a <code class="literal">RETURNING</code> clause, just return NULL
+ after a direct modification on the remote server.
+ When the query has the clause, fetch one result containing the data
+ needed for the <code class="literal">RETURNING</code> calculation, returning it in a
+ tuple table slot (the node's <code class="structfield">ScanTupleSlot</code> should be
+ used for this purpose). The data that was actually inserted, updated
+ or deleted must be stored in
+ <code class="literal">node-&gt;resultRelInfo-&gt;ri_projectReturning-&gt;pi_exprContext-&gt;ecxt_scantuple</code>.
+ Return NULL if no more rows are available.
+ Note that this is called in a short-lived memory context that will be
+ reset between invocations. Create a memory context in
+ <code class="function">BeginDirectModify</code> if you need longer-lived storage, or use
+ the <code class="structfield">es_query_cxt</code> of the node's <code class="structname">EState</code>.
+ </p><p>
+ The rows returned must match the <code class="structfield">fdw_scan_tlist</code> target
+ list if one was supplied, otherwise they must match the row type of the
+ foreign table being updated. If you choose to optimize away fetching
+ columns that are not needed for the <code class="literal">RETURNING</code> calculation,
+ you should insert nulls in those column positions, or else generate a
+ <code class="structfield">fdw_scan_tlist</code> list with those columns omitted.
+ </p><p>
+ Whether the query has the clause or not, the query's reported row count
+ must be incremented by the FDW itself. When the query doesn't have the
+ clause, the FDW must also increment the row count for the
+ <code class="structname">ForeignScanState</code> node in the <code class="command">EXPLAIN ANALYZE</code>
+ case.
+ </p><p>
+ If the <code class="function">IterateDirectModify</code> pointer is set to
+ <code class="literal">NULL</code>, no attempts to execute a direct modification on the
+ remote server are taken.
+ </p><p>
+</p><pre class="programlisting">
+void
+EndDirectModify(ForeignScanState *node);
+</pre><p>
+
+ Clean up following a direct modification on the remote server. It is
+ normally not important to release palloc'd memory, but for example open
+ files and connections to the remote server should be cleaned up.
+ </p><p>
+ If the <code class="function">EndDirectModify</code> pointer is set to
+ <code class="literal">NULL</code>, no attempts to execute a direct modification on the
+ remote server are taken.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-TRUNCATE"><div class="titlepage"><div><div><h3 class="title">59.2.5. FDW Routines for <code class="command">TRUNCATE</code></h3></div></div></div><p>
+</p><pre class="programlisting">
+void
+ExecForeignTruncate(List *rels,
+ DropBehavior behavior,
+ bool restart_seqs);
+</pre><p>
+
+ Truncate foreign tables. This function is called when
+ <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> is executed on a foreign table.
+ <code class="literal">rels</code> is a list of <code class="structname">Relation</code>
+ data structures of foreign tables to truncate.
+ </p><p>
+ <code class="literal">behavior</code> is either <code class="literal">DROP_RESTRICT</code>
+ or <code class="literal">DROP_CASCADE</code> indicating that the
+ <code class="literal">RESTRICT</code> or <code class="literal">CASCADE</code> option was
+ requested in the original <code class="command">TRUNCATE</code> command,
+ respectively.
+ </p><p>
+ If <code class="literal">restart_seqs</code> is <code class="literal">true</code>,
+ the original <code class="command">TRUNCATE</code> command requested the
+ <code class="literal">RESTART IDENTITY</code> behavior, otherwise the
+ <code class="literal">CONTINUE IDENTITY</code> behavior was requested.
+ </p><p>
+ Note that the <code class="literal">ONLY</code> options specified
+ in the original <code class="command">TRUNCATE</code> command are not passed to
+ <code class="function">ExecForeignTruncate</code>. This behavior is similar to
+ the callback functions of <code class="command">SELECT</code>,
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code> on
+ a foreign table.
+ </p><p>
+ <code class="function">ExecForeignTruncate</code> is invoked once per
+ foreign server for which foreign tables are to be truncated.
+ This means that all foreign tables included in <code class="literal">rels</code>
+ must belong to the same server.
+ </p><p>
+ If the <code class="function">ExecForeignTruncate</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to truncate foreign tables will
+ fail with an error message.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-ROW-LOCKING"><div class="titlepage"><div><div><h3 class="title">59.2.6. FDW Routines for Row Locking</h3></div></div></div><p>
+ If an FDW wishes to support <em class="firstterm">late row locking</em> (as described
+ in <a class="xref" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Section 59.5</a>), it must provide the following
+ callback functions:
+ </p><p>
+</p><pre class="programlisting">
+RowMarkType
+GetForeignRowMarkType(RangeTblEntry *rte,
+ LockClauseStrength strength);
+</pre><p>
+
+ Report which row-marking option to use for a foreign table.
+ <code class="literal">rte</code> is the <code class="structname">RangeTblEntry</code> node for the table
+ and <code class="literal">strength</code> describes the lock strength requested by the
+ relevant <code class="literal">FOR UPDATE/SHARE</code> clause, if any. The result must be
+ a member of the <code class="literal">RowMarkType</code> enum type.
+ </p><p>
+ This function is called during query planning for each foreign table that
+ appears in an <code class="command">UPDATE</code>, <code class="command">DELETE</code>, or <code class="command">SELECT
+ FOR UPDATE/SHARE</code> query and is not the target of <code class="command">UPDATE</code>
+ or <code class="command">DELETE</code>.
+ </p><p>
+ If the <code class="function">GetForeignRowMarkType</code> pointer is set to
+ <code class="literal">NULL</code>, the <code class="literal">ROW_MARK_COPY</code> option is always used.
+ (This implies that <code class="function">RefetchForeignRow</code> will never be called,
+ so it need not be provided either.)
+ </p><p>
+ See <a class="xref" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Section 59.5</a> for more information.
+ </p><p>
+</p><pre class="programlisting">
+void
+RefetchForeignRow(EState *estate,
+ ExecRowMark *erm,
+ Datum rowid,
+ TupleTableSlot *slot,
+ bool *updated);
+</pre><p>
+
+ Re-fetch one tuple slot from the foreign table, after locking it if required.
+ <code class="literal">estate</code> is global execution state for the query.
+ <code class="literal">erm</code> is the <code class="structname">ExecRowMark</code> struct describing
+ the target foreign table and the row lock type (if any) to acquire.
+ <code class="literal">rowid</code> identifies the tuple to be fetched.
+ <code class="literal">slot</code> contains nothing useful upon call, but can be used to
+ hold the returned tuple. <code class="literal">updated</code> is an output parameter.
+ </p><p>
+ This function should store the tuple into the provided slot, or clear it if
+ the row lock couldn't be obtained. The row lock type to acquire is
+ defined by <code class="literal">erm-&gt;markType</code>, which is the value
+ previously returned by <code class="function">GetForeignRowMarkType</code>.
+ (<code class="literal">ROW_MARK_REFERENCE</code> means to just re-fetch the tuple
+ without acquiring any lock, and <code class="literal">ROW_MARK_COPY</code> will
+ never be seen by this routine.)
+ </p><p>
+ In addition, <code class="literal">*updated</code> should be set to <code class="literal">true</code>
+ if what was fetched was an updated version of the tuple rather than
+ the same version previously obtained. (If the FDW cannot be sure about
+ this, always returning <code class="literal">true</code> is recommended.)
+ </p><p>
+ Note that by default, failure to acquire a row lock should result in
+ raising an error; returning with an empty slot is only appropriate if
+ the <code class="literal">SKIP LOCKED</code> option is specified
+ by <code class="literal">erm-&gt;waitPolicy</code>.
+ </p><p>
+ The <code class="literal">rowid</code> is the <code class="structfield">ctid</code> value previously read
+ for the row to be re-fetched. Although the <code class="literal">rowid</code> value is
+ passed as a <code class="type">Datum</code>, it can currently only be a <code class="type">tid</code>. The
+ function API is chosen in hopes that it may be possible to allow other
+ data types for row IDs in future.
+ </p><p>
+ If the <code class="function">RefetchForeignRow</code> pointer is set to
+ <code class="literal">NULL</code>, attempts to re-fetch rows will fail
+ with an error message.
+ </p><p>
+ See <a class="xref" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Section 59.5</a> for more information.
+ </p><p>
+</p><pre class="programlisting">
+bool
+RecheckForeignScan(ForeignScanState *node,
+ TupleTableSlot *slot);
+</pre><p>
+ Recheck that a previously-returned tuple still matches the relevant
+ scan and join qualifiers, and possibly provide a modified version of
+ the tuple. For foreign data wrappers which do not perform join pushdown,
+ it will typically be more convenient to set this to <code class="literal">NULL</code> and
+ instead set <code class="structfield">fdw_recheck_quals</code> appropriately.
+ When outer joins are pushed down, however, it isn't sufficient to
+ reapply the checks relevant to all the base tables to the result tuple,
+ even if all needed attributes are present, because failure to match some
+ qualifier might result in some attributes going to NULL, rather than in
+ no tuple being returned. <code class="literal">RecheckForeignScan</code> can recheck
+ qualifiers and return true if they are still satisfied and false
+ otherwise, but it can also store a replacement tuple into the supplied
+ slot.
+ </p><p>
+ To implement join pushdown, a foreign data wrapper will typically
+ construct an alternative local join plan which is used only for
+ rechecks; this will become the outer subplan of the
+ <code class="literal">ForeignScan</code>. When a recheck is required, this subplan
+ can be executed and the resulting tuple can be stored in the slot.
+ This plan need not be efficient since no base table will return more
+ than one row; for example, it may implement all joins as nested loops.
+ The function <code class="literal">GetExistingLocalJoinPath</code> may be used to search
+ existing paths for a suitable local join path, which can be used as the
+ alternative local join plan. <code class="literal">GetExistingLocalJoinPath</code>
+ searches for an unparameterized path in the path list of the specified
+ join relation. (If it does not find such a path, it returns NULL, in
+ which case a foreign data wrapper may build the local path by itself or
+ may choose not to create access paths for that join.)
+ </p></div><div class="sect2" id="FDW-CALLBACKS-EXPLAIN"><div class="titlepage"><div><div><h3 class="title">59.2.7. FDW Routines for <code class="command">EXPLAIN</code></h3></div></div></div><p>
+</p><pre class="programlisting">
+void
+ExplainForeignScan(ForeignScanState *node,
+ ExplainState *es);
+</pre><p>
+
+ Print additional <code class="command">EXPLAIN</code> output for a foreign table scan.
+ This function can call <code class="function">ExplainPropertyText</code> and
+ related functions to add fields to the <code class="command">EXPLAIN</code> output.
+ The flag fields in <code class="literal">es</code> can be used to determine what to
+ print, and the state of the <code class="structname">ForeignScanState</code> node
+ can be inspected to provide run-time statistics in the <code class="command">EXPLAIN
+ ANALYZE</code> case.
+ </p><p>
+ If the <code class="function">ExplainForeignScan</code> pointer is set to
+ <code class="literal">NULL</code>, no additional information is printed during
+ <code class="command">EXPLAIN</code>.
+ </p><p>
+</p><pre class="programlisting">
+void
+ExplainForeignModify(ModifyTableState *mtstate,
+ ResultRelInfo *rinfo,
+ List *fdw_private,
+ int subplan_index,
+ struct ExplainState *es);
+</pre><p>
+
+ Print additional <code class="command">EXPLAIN</code> output for a foreign table update.
+ This function can call <code class="function">ExplainPropertyText</code> and
+ related functions to add fields to the <code class="command">EXPLAIN</code> output.
+ The flag fields in <code class="literal">es</code> can be used to determine what to
+ print, and the state of the <code class="structname">ModifyTableState</code> node
+ can be inspected to provide run-time statistics in the <code class="command">EXPLAIN
+ ANALYZE</code> case. The first four arguments are the same as for
+ <code class="function">BeginForeignModify</code>.
+ </p><p>
+ If the <code class="function">ExplainForeignModify</code> pointer is set to
+ <code class="literal">NULL</code>, no additional information is printed during
+ <code class="command">EXPLAIN</code>.
+ </p><p>
+</p><pre class="programlisting">
+void
+ExplainDirectModify(ForeignScanState *node,
+ ExplainState *es);
+</pre><p>
+
+ Print additional <code class="command">EXPLAIN</code> output for a direct modification
+ on the remote server.
+ This function can call <code class="function">ExplainPropertyText</code> and
+ related functions to add fields to the <code class="command">EXPLAIN</code> output.
+ The flag fields in <code class="literal">es</code> can be used to determine what to
+ print, and the state of the <code class="structname">ForeignScanState</code> node
+ can be inspected to provide run-time statistics in the <code class="command">EXPLAIN
+ ANALYZE</code> case.
+ </p><p>
+ If the <code class="function">ExplainDirectModify</code> pointer is set to
+ <code class="literal">NULL</code>, no additional information is printed during
+ <code class="command">EXPLAIN</code>.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-ANALYZE"><div class="titlepage"><div><div><h3 class="title">59.2.8. FDW Routines for <code class="command">ANALYZE</code></h3></div></div></div><p>
+</p><pre class="programlisting">
+bool
+AnalyzeForeignTable(Relation relation,
+ AcquireSampleRowsFunc *func,
+ BlockNumber *totalpages);
+</pre><p>
+
+ This function is called when <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a> is executed on
+ a foreign table. If the FDW can collect statistics for this
+ foreign table, it should return <code class="literal">true</code>, and provide a pointer
+ to a function that will collect sample rows from the table in
+ <em class="parameter"><code>func</code></em>, plus the estimated size of the table in pages in
+ <em class="parameter"><code>totalpages</code></em>. Otherwise, return <code class="literal">false</code>.
+ </p><p>
+ If the FDW does not support collecting statistics for any tables, the
+ <code class="function">AnalyzeForeignTable</code> pointer can be set to <code class="literal">NULL</code>.
+ </p><p>
+ If provided, the sample collection function must have the signature
+</p><pre class="programlisting">
+int
+AcquireSampleRowsFunc(Relation relation,
+ int elevel,
+ HeapTuple *rows,
+ int targrows,
+ double *totalrows,
+ double *totaldeadrows);
+</pre><p>
+
+ A random sample of up to <em class="parameter"><code>targrows</code></em> rows should be collected
+ from the table and stored into the caller-provided <em class="parameter"><code>rows</code></em>
+ array. The actual number of rows collected must be returned. In
+ addition, store estimates of the total numbers of live and dead rows in
+ the table into the output parameters <em class="parameter"><code>totalrows</code></em> and
+ <em class="parameter"><code>totaldeadrows</code></em>. (Set <em class="parameter"><code>totaldeadrows</code></em> to zero
+ if the FDW does not have any concept of dead rows.)
+ </p></div><div class="sect2" id="FDW-CALLBACKS-IMPORT"><div class="titlepage"><div><div><h3 class="title">59.2.9. FDW Routines for <code class="command">IMPORT FOREIGN SCHEMA</code></h3></div></div></div><p>
+</p><pre class="programlisting">
+List *
+ImportForeignSchema(ImportForeignSchemaStmt *stmt, Oid serverOid);
+</pre><p>
+
+ Obtain a list of foreign table creation commands. This function is
+ called when executing <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a>, 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 <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a> command.
+ These strings will be parsed and executed by the core server.
+ </p><p>
+ Within the <code class="structname">ImportForeignSchemaStmt</code> struct,
+ <code class="structfield">remote_schema</code> is the name of the remote schema from
+ which tables are to be imported.
+ <code class="structfield">list_type</code> identifies how to filter table names:
+ <code class="literal">FDW_IMPORT_SCHEMA_ALL</code> means that all tables in the remote
+ schema should be imported (in this case <code class="structfield">table_list</code> is
+ empty), <code class="literal">FDW_IMPORT_SCHEMA_LIMIT_TO</code> means to include only
+ tables listed in <code class="structfield">table_list</code>,
+ and <code class="literal">FDW_IMPORT_SCHEMA_EXCEPT</code> means to exclude the tables
+ listed in <code class="structfield">table_list</code>.
+ <code class="structfield">options</code> is a list of options used for the import process.
+ The meanings of the options are up to the FDW.
+ For example, an FDW could use an option to define whether the
+ <code class="literal">NOT NULL</code> attributes of columns should be imported.
+ These options need not have anything to do with those supported by the
+ FDW as database object options.
+ </p><p>
+ The FDW may ignore the <code class="structfield">local_schema</code> field of
+ the <code class="structname">ImportForeignSchemaStmt</code>, because the core server
+ will automatically insert that name into the parsed <code class="command">CREATE
+ FOREIGN TABLE</code> commands.
+ </p><p>
+ The FDW does not have to concern itself with implementing the filtering
+ specified by <code class="structfield">list_type</code> and <code class="structfield">table_list</code>,
+ either, as the core server will automatically skip any returned commands
+ for tables excluded according to those options. However, it's often
+ useful to avoid the work of creating commands for excluded tables in the
+ first place. The function <code class="function">IsImportableForeignTable()</code> may be
+ useful to test whether a given foreign-table name will pass the filter.
+ </p><p>
+ If the FDW does not support importing table definitions, the
+ <code class="function">ImportForeignSchema</code> pointer can be set to <code class="literal">NULL</code>.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-PARALLEL"><div class="titlepage"><div><div><h3 class="title">59.2.10. FDW Routines for Parallel Execution</h3></div></div></div><p>
+ A <code class="structname">ForeignScan</code> node can, optionally, support parallel
+ execution. A parallel <code class="structname">ForeignScan</code> will be executed
+ in multiple processes and must return each row exactly once across
+ all cooperating processes. To do this, processes can coordinate through
+ fixed-size chunks of dynamic shared memory. This shared memory is not
+ guaranteed to be mapped at the same address in every process, so it
+ must not contain pointers. The following functions are all optional,
+ but most are required if parallel execution is to be supported.
+ </p><p>
+</p><pre class="programlisting">
+bool
+IsForeignScanParallelSafe(PlannerInfo *root, RelOptInfo *rel,
+ RangeTblEntry *rte);
+</pre><p>
+ Test whether a scan can be performed within a parallel worker. This
+ function will only be called when the planner believes that a parallel
+ plan might be possible, and should return true if it is safe for that scan
+ to run within a parallel worker. This will generally not be the case if
+ the remote data source has transaction semantics, unless the worker's
+ connection to the data can somehow be made to share the same transaction
+ context as the leader.
+ </p><p>
+ If this function is not defined, it is assumed that the scan must take
+ place within the parallel leader. Note that returning true does not mean
+ that the scan itself can be done in parallel, only that the scan can be
+ performed within a parallel worker. Therefore, it can be useful to define
+ this method even when parallel execution is not supported.
+ </p><p>
+</p><pre class="programlisting">
+Size
+EstimateDSMForeignScan(ForeignScanState *node, ParallelContext *pcxt);
+</pre><p>
+ Estimate the amount of dynamic shared memory that will be required
+ for parallel operation. This may be higher than the amount that will
+ actually be used, but it must not be lower. The return value is in bytes.
+ This function is optional, and can be omitted if not needed; but if it
+ is omitted, the next three functions must be omitted as well, because
+ no shared memory will be allocated for the FDW's use.
+ </p><p>
+</p><pre class="programlisting">
+void
+InitializeDSMForeignScan(ForeignScanState *node, ParallelContext *pcxt,
+ void *coordinate);
+</pre><p>
+ Initialize the dynamic shared memory that will be required for parallel
+ operation. <code class="literal">coordinate</code> points to a shared memory area of
+ size equal to the return value of <code class="function">EstimateDSMForeignScan</code>.
+ This function is optional, and can be omitted if not needed.
+ </p><p>
+</p><pre class="programlisting">
+void
+ReInitializeDSMForeignScan(ForeignScanState *node, ParallelContext *pcxt,
+ void *coordinate);
+</pre><p>
+ Re-initialize the dynamic shared memory required for parallel operation
+ when the foreign-scan plan node is about to be re-scanned.
+ This function is optional, and can be omitted if not needed.
+ Recommended practice is that this function reset only shared state,
+ while the <code class="function">ReScanForeignScan</code> function resets only local
+ state. Currently, this function will be called
+ before <code class="function">ReScanForeignScan</code>, but it's best not to rely on
+ that ordering.
+ </p><p>
+</p><pre class="programlisting">
+void
+InitializeWorkerForeignScan(ForeignScanState *node, shm_toc *toc,
+ void *coordinate);
+</pre><p>
+ Initialize a parallel worker's local state based on the shared state
+ set up by the leader during <code class="function">InitializeDSMForeignScan</code>.
+ This function is optional, and can be omitted if not needed.
+ </p><p>
+</p><pre class="programlisting">
+void
+ShutdownForeignScan(ForeignScanState *node);
+</pre><p>
+ Release resources when it is anticipated the node will not be executed
+ to completion. This is not called in all cases; sometimes,
+ <code class="literal">EndForeignScan</code> may be called without this function having
+ been called first. Since the DSM segment used by parallel query is
+ destroyed just after this callback is invoked, foreign data wrappers that
+ wish to take some action before the DSM segment goes away should implement
+ this method.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-ASYNC"><div class="titlepage"><div><div><h3 class="title">59.2.11. FDW Routines for Asynchronous Execution</h3></div></div></div><p>
+ A <code class="structname">ForeignScan</code> node can, optionally, support
+ asynchronous execution as described in
+ <code class="filename">src/backend/executor/README</code>. The following
+ functions are all optional, but are all required if asynchronous
+ execution is to be supported.
+ </p><p>
+</p><pre class="programlisting">
+bool
+IsForeignPathAsyncCapable(ForeignPath *path);
+</pre><p>
+ Test whether a given <code class="structname">ForeignPath</code> path can scan
+ the underlying foreign relation asynchronously.
+ This function will only be called at the end of query planning when the
+ given path is a direct child of an <code class="structname">AppendPath</code>
+ path and when the planner believes that asynchronous execution improves
+ performance, and should return true if the given path is able to scan the
+ foreign relation asynchronously.
+ </p><p>
+ If this function is not defined, it is assumed that the given path scans
+ the foreign relation using <code class="function">IterateForeignScan</code>.
+ (This implies that the callback functions described below will never be
+ called, so they need not be provided either.)
+ </p><p>
+</p><pre class="programlisting">
+void
+ForeignAsyncRequest(AsyncRequest *areq);
+</pre><p>
+ Produce one tuple asynchronously from the
+ <code class="structname">ForeignScan</code> node. <code class="literal">areq</code> is
+ the <code class="structname">AsyncRequest</code> struct describing the
+ <code class="structname">ForeignScan</code> node and the parent
+ <code class="structname">Append</code> node that requested the tuple from it.
+ This function should store the tuple into the slot specified by
+ <code class="literal">areq-&gt;result</code>, and set
+ <code class="literal">areq-&gt;request_complete</code> to <code class="literal">true</code>;
+ or if it needs to wait on an event external to the core server such as
+ network I/O, and cannot produce any tuple immediately, set the flag to
+ <code class="literal">false</code>, and set
+ <code class="literal">areq-&gt;callback_pending</code> to <code class="literal">true</code>
+ for the <code class="structname">ForeignScan</code> node to get a callback from
+ the callback functions described below. If no more tuples are available,
+ set the slot to NULL or an empty slot, and the
+ <code class="literal">areq-&gt;request_complete</code> flag to
+ <code class="literal">true</code>. It's recommended to use
+ <code class="function">ExecAsyncRequestDone</code> or
+ <code class="function">ExecAsyncRequestPending</code> to set the output parameters
+ in the <code class="literal">areq</code>.
+ </p><p>
+</p><pre class="programlisting">
+void
+ForeignAsyncConfigureWait(AsyncRequest *areq);
+</pre><p>
+ Configure a file descriptor event for which the
+ <code class="structname">ForeignScan</code> node wishes to wait.
+ This function will only be called when the
+ <code class="structname">ForeignScan</code> node has the
+ <code class="literal">areq-&gt;callback_pending</code> flag set, and should add
+ the event to the <code class="structfield">as_eventset</code> of the parent
+ <code class="structname">Append</code> node described by the
+ <code class="literal">areq</code>. See the comments for
+ <code class="function">ExecAsyncConfigureWait</code> in
+ <code class="filename">src/backend/executor/execAsync.c</code> for additional
+ information. When the file descriptor event occurs,
+ <code class="function">ForeignAsyncNotify</code> will be called.
+ </p><p>
+</p><pre class="programlisting">
+void
+ForeignAsyncNotify(AsyncRequest *areq);
+</pre><p>
+ Process a relevant event that has occurred, then produce one tuple
+ asynchronously from the <code class="structname">ForeignScan</code> node.
+ This function should set the output parameters in the
+ <code class="literal">areq</code> in the same way as
+ <code class="function">ForeignAsyncRequest</code>.
+ </p></div><div class="sect2" id="FDW-CALLBACKS-REPARAMETERIZE-PATHS"><div class="titlepage"><div><div><h3 class="title">59.2.12. FDW Routines for Reparameterization of Paths</h3></div></div></div><p>
+</p><pre class="programlisting">
+List *
+ReparameterizeForeignPathByChild(PlannerInfo *root, List *fdw_private,
+ RelOptInfo *child_rel);
+</pre><p>
+ This function is called while converting a path parameterized by the
+ top-most parent of the given child relation <code class="literal">child_rel</code> to be
+ parameterized by the child relation. The function is used to reparameterize
+ any paths or translate any expression nodes saved in the given
+ <code class="literal">fdw_private</code> member of a <code class="structname">ForeignPath</code>. The
+ callback may use <code class="literal">reparameterize_path_by_child</code>,
+ <code class="literal">adjust_appendrel_attrs</code> or
+ <code class="literal">adjust_appendrel_attrs_multilevel</code> as required.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">59.1. Foreign Data Wrapper Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 59.3. Foreign Data Wrapper Helper Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdw-functions.html b/doc/src/sgml/html/fdw-functions.html
new file mode 100644
index 0000000..ab19bdc
--- /dev/null
+++ b/doc/src/sgml/html/fdw-functions.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>59.1. Foreign Data Wrapper Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper" /><link rel="next" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">59.1. Foreign Data Wrapper Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><th width="60%" align="center">Chapter 59. Writing a Foreign Data Wrapper</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines">Next</a></td></tr></table><hr /></div><div class="sect1" id="FDW-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">59.1. Foreign Data Wrapper Functions</h2></div></div></div><p>
+ The FDW author needs to implement a handler function, and optionally
+ 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 <a class="xref" href="xfunc-c.html" title="38.10. C-Language Functions">Section 38.10</a>.
+ </p><p>
+ The handler function simply returns a struct of function pointers to
+ callback functions that will be called by the planner, executor, and
+ various maintenance commands.
+ Most of the effort in writing an FDW is in implementing these callback
+ functions.
+ The handler function must be registered with
+ <span class="productname">PostgreSQL</span> as taking no arguments and
+ returning the special pseudo-type <code class="type">fdw_handler</code>. The
+ callback functions are plain C functions and are not visible or
+ callable at the SQL level. The callback functions are described in
+ <a class="xref" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines">Section 59.2</a>.
+ </p><p>
+ The validator function is responsible for validating options given in
+ <code class="command">CREATE</code> and <code class="command">ALTER</code> commands for its
+ foreign data wrapper, as well as foreign servers, user mappings, and
+ foreign tables using the wrapper.
+ The validator function must be registered as taking two arguments, a
+ text array containing the options to be validated, and an OID
+ representing the type of object the options are associated with (in
+ the form of the OID of the system catalog the object would be stored
+ in, either
+ <code class="literal">ForeignDataWrapperRelationId</code>,
+ <code class="literal">ForeignServerRelationId</code>,
+ <code class="literal">UserMappingRelationId</code>,
+ or <code class="literal">ForeignTableRelationId</code>).
+ If no validator function is supplied, options are not checked at object
+ creation time or object alteration time.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 59. Writing a Foreign Data Wrapper </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 59.2. Foreign Data Wrapper Callback Routines</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdw-helpers.html b/doc/src/sgml/html/fdw-helpers.html
new file mode 100644
index 0000000..b77c43a
--- /dev/null
+++ b/doc/src/sgml/html/fdw-helpers.html
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>59.3. Foreign Data Wrapper Helper Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines" /><link rel="next" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">59.3. Foreign Data Wrapper Helper Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><th width="60%" align="center">Chapter 59. Writing a Foreign Data Wrapper</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Next</a></td></tr></table><hr /></div><div class="sect1" id="FDW-HELPERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">59.3. Foreign Data Wrapper Helper Functions</h2></div></div></div><p>
+ Several helper functions are exported from the core server so that
+ authors of foreign data wrappers can get easy access to attributes of
+ FDW-related objects, such as FDW options.
+ To use any of these functions, you need to include the header file
+ <code class="filename">foreign/foreign.h</code> in your source file.
+ That header also defines the struct types that are returned by
+ these functions.
+ </p><p>
+</p><pre class="programlisting">
+ForeignDataWrapper *
+GetForeignDataWrapperExtended(Oid fdwid, bits16 flags);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignDataWrapper</code>
+ object for the foreign-data wrapper with the given OID. A
+ <code class="structname">ForeignDataWrapper</code> object contains properties
+ of the FDW (see <code class="filename">foreign/foreign.h</code> for details).
+ <code class="structfield">flags</code> is a bitwise-or'd bit mask indicating
+ an extra set of options. It can take the value
+ <code class="literal">FDW_MISSING_OK</code>, in which case a <code class="literal">NULL</code>
+ result is returned to the caller instead of an error for an undefined
+ object.
+ </p><p>
+</p><pre class="programlisting">
+ForeignDataWrapper *
+GetForeignDataWrapper(Oid fdwid);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignDataWrapper</code>
+ object for the foreign-data wrapper with the given OID. A
+ <code class="structname">ForeignDataWrapper</code> object contains properties
+ of the FDW (see <code class="filename">foreign/foreign.h</code> for details).
+ </p><p>
+</p><pre class="programlisting">
+ForeignServer *
+GetForeignServerExtended(Oid serverid, bits16 flags);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignServer</code> object
+ for the foreign server with the given OID. A
+ <code class="structname">ForeignServer</code> object contains properties
+ of the server (see <code class="filename">foreign/foreign.h</code> for details).
+ <code class="structfield">flags</code> is a bitwise-or'd bit mask indicating
+ an extra set of options. It can take the value
+ <code class="literal">FSV_MISSING_OK</code>, in which case a <code class="literal">NULL</code>
+ result is returned to the caller instead of an error for an undefined
+ object.
+ </p><p>
+</p><pre class="programlisting">
+ForeignServer *
+GetForeignServer(Oid serverid);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignServer</code> object
+ for the foreign server with the given OID. A
+ <code class="structname">ForeignServer</code> object contains properties
+ of the server (see <code class="filename">foreign/foreign.h</code> for details).
+ </p><p>
+</p><pre class="programlisting">
+UserMapping *
+GetUserMapping(Oid userid, Oid serverid);
+</pre><p>
+
+ This function returns a <code class="structname">UserMapping</code> object for
+ the user mapping of the given role on the given server. (If there is no
+ mapping for the specific user, it will return the mapping for
+ <code class="literal">PUBLIC</code>, or throw error if there is none.) A
+ <code class="structname">UserMapping</code> object contains properties of the
+ user mapping (see <code class="filename">foreign/foreign.h</code> for details).
+ </p><p>
+</p><pre class="programlisting">
+ForeignTable *
+GetForeignTable(Oid relid);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignTable</code> object for
+ the foreign table with the given OID. A
+ <code class="structname">ForeignTable</code> object contains properties of the
+ foreign table (see <code class="filename">foreign/foreign.h</code> for details).
+ </p><p>
+</p><pre class="programlisting">
+List *
+GetForeignColumnOptions(Oid relid, AttrNumber attnum);
+</pre><p>
+
+ This function returns the per-column FDW options for the column with the
+ given foreign table OID and attribute number, in the form of a list of
+ <code class="structname">DefElem</code>. NIL is returned if the column has no
+ options.
+ </p><p>
+ Some object types have name-based lookup functions in addition to the
+ OID-based ones:
+ </p><p>
+</p><pre class="programlisting">
+ForeignDataWrapper *
+GetForeignDataWrapperByName(const char *name, bool missing_ok);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignDataWrapper</code>
+ object for the foreign-data wrapper with the given name. If the wrapper
+ is not found, return NULL if missing_ok is true, otherwise raise an
+ error.
+ </p><p>
+</p><pre class="programlisting">
+ForeignServer *
+GetForeignServerByName(const char *name, bool missing_ok);
+</pre><p>
+
+ This function returns a <code class="structname">ForeignServer</code> object
+ for the foreign server with the given name. If the server is not found,
+ return NULL if missing_ok is true, otherwise raise an error.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdw-callbacks.html" title="59.2. Foreign Data Wrapper Callback Routines">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Next</a></td></tr><tr><td width="40%" align="left" valign="top">59.2. Foreign Data Wrapper Callback Routines </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 59.4. Foreign Data Wrapper Query Planning</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdw-planning.html b/doc/src/sgml/html/fdw-planning.html
new file mode 100644
index 0000000..314efb4
--- /dev/null
+++ b/doc/src/sgml/html/fdw-planning.html
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>59.4. Foreign Data Wrapper Query Planning</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions" /><link rel="next" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">59.4. Foreign Data Wrapper Query Planning</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><th width="60%" align="center">Chapter 59. Writing a Foreign Data Wrapper</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Next</a></td></tr></table><hr /></div><div class="sect1" id="FDW-PLANNING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">59.4. Foreign Data Wrapper Query Planning</h2></div></div></div><p>
+ The FDW callback functions <code class="function">GetForeignRelSize</code>,
+ <code class="function">GetForeignPaths</code>, <code class="function">GetForeignPlan</code>,
+ <code class="function">PlanForeignModify</code>, <code class="function">GetForeignJoinPaths</code>,
+ <code class="function">GetForeignUpperPaths</code>, and <code class="function">PlanDirectModify</code>
+ must fit into the workings of the <span class="productname">PostgreSQL</span> planner.
+ Here are some notes about what they must do.
+ </p><p>
+ The information in <code class="literal">root</code> and <code class="literal">baserel</code> can be used
+ to reduce the amount of information that has to be fetched from the
+ foreign table (and therefore reduce the cost).
+ <code class="literal">baserel-&gt;baserestrictinfo</code> is particularly interesting, as
+ it contains restriction quals (<code class="literal">WHERE</code> clauses) that should be
+ used to filter the rows to be fetched. (The FDW itself is not required
+ to enforce these quals, as the core executor can check them instead.)
+ <code class="literal">baserel-&gt;reltarget-&gt;exprs</code> can be used to determine which
+ columns need to be fetched; but note that it only lists columns that
+ have to be emitted by the <code class="structname">ForeignScan</code> plan node, not
+ columns that are used in qual evaluation but not output by the query.
+ </p><p>
+ Various private fields are available for the FDW planning functions to
+ keep information in. Generally, whatever you store in FDW private fields
+ should be palloc'd, so that it will be reclaimed at the end of planning.
+ </p><p>
+ <code class="literal">baserel-&gt;fdw_private</code> is a <code class="type">void</code> pointer that is
+ available for FDW planning functions to store information relevant to
+ the particular foreign table. The core planner does not touch it except
+ to initialize it to NULL when the <code class="literal">RelOptInfo</code> node is created.
+ It is useful for passing information forward from
+ <code class="function">GetForeignRelSize</code> to <code class="function">GetForeignPaths</code> and/or
+ <code class="function">GetForeignPaths</code> to <code class="function">GetForeignPlan</code>, thereby
+ avoiding recalculation.
+ </p><p>
+ <code class="function">GetForeignPaths</code> can identify the meaning of different
+ access paths by storing private information in the
+ <code class="structfield">fdw_private</code> field of <code class="structname">ForeignPath</code> nodes.
+ <code class="structfield">fdw_private</code> is declared as a <code class="type">List</code> pointer, but
+ could actually contain anything since the core planner does not touch
+ it. However, best practice is to use a representation that's dumpable
+ by <code class="function">nodeToString</code>, for use with debugging support available
+ in the backend.
+ </p><p>
+ <code class="function">GetForeignPlan</code> can examine the <code class="structfield">fdw_private</code>
+ field of the selected <code class="structname">ForeignPath</code> node, and can generate
+ <code class="structfield">fdw_exprs</code> and <code class="structfield">fdw_private</code> lists to be
+ placed in the <code class="structname">ForeignScan</code> plan node, where they will be
+ available at execution time. Both of these lists must be
+ represented in a form that <code class="function">copyObject</code> knows how to copy.
+ The <code class="structfield">fdw_private</code> list has no other restrictions and is
+ not interpreted by the core backend in any way. The
+ <code class="structfield">fdw_exprs</code> list, if not NIL, is expected to contain
+ expression trees that are intended to be executed at run time. These
+ trees will undergo post-processing by the planner to make them fully
+ executable.
+ </p><p>
+ In <code class="function">GetForeignPlan</code>, generally the passed-in target list can
+ be copied into the plan node as-is. The passed <code class="literal">scan_clauses</code> list
+ contains the same clauses as <code class="literal">baserel-&gt;baserestrictinfo</code>,
+ but may be re-ordered for better execution efficiency. In simple cases
+ the FDW can just strip <code class="structname">RestrictInfo</code> nodes from the
+ <code class="literal">scan_clauses</code> list (using <code class="function">extract_actual_clauses</code>) and put
+ all the clauses into the plan node's qual list, which means that all the
+ clauses will be checked by the executor at run time. More complex FDWs
+ may be able to check some of the clauses internally, in which case those
+ clauses can be removed from the plan node's qual list so that the
+ executor doesn't waste time rechecking them.
+ </p><p>
+ As an example, the FDW might identify some restriction clauses of the
+ form <em class="replaceable"><code>foreign_variable</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>sub_expression</code></em>, which it determines can be executed on
+ the remote server given the locally-evaluated value of the
+ <em class="replaceable"><code>sub_expression</code></em>. The actual identification of such a
+ clause should happen during <code class="function">GetForeignPaths</code>, since it would
+ affect the cost estimate for the path. The path's
+ <code class="structfield">fdw_private</code> field would probably include a pointer to
+ the identified clause's <code class="structname">RestrictInfo</code> node. Then
+ <code class="function">GetForeignPlan</code> would remove that clause from <code class="literal">scan_clauses</code>,
+ but add the <em class="replaceable"><code>sub_expression</code></em> to <code class="structfield">fdw_exprs</code>
+ to ensure that it gets massaged into executable form. It would probably
+ also put control information into the plan node's
+ <code class="structfield">fdw_private</code> field to tell the execution functions what
+ to do at run time. The query transmitted to the remote server would
+ involve something like <code class="literal">WHERE <em class="replaceable"><code>foreign_variable</code></em> =
+ $1</code>, with the parameter value obtained at run time from
+ evaluation of the <code class="structfield">fdw_exprs</code> expression tree.
+ </p><p>
+ Any clauses removed from the plan node's qual list must instead be added
+ to <code class="literal">fdw_recheck_quals</code> or rechecked by
+ <code class="literal">RecheckForeignScan</code> in order to ensure correct behavior
+ at the <code class="literal">READ COMMITTED</code> isolation level. When a concurrent
+ update occurs for some other table involved in the query, the executor
+ may need to verify that all of the original quals are still satisfied for
+ the tuple, possibly against a different set of parameter values. Using
+ <code class="literal">fdw_recheck_quals</code> is typically easier than implementing checks
+ inside <code class="literal">RecheckForeignScan</code>, but this method will be
+ insufficient when outer joins have been pushed down, since the join tuples
+ in that case might have some fields go to NULL without rejecting the
+ tuple entirely.
+ </p><p>
+ Another <code class="structname">ForeignScan</code> field that can be filled by FDWs
+ is <code class="structfield">fdw_scan_tlist</code>, which describes the tuples returned by
+ the FDW for this plan node. For simple foreign table scans this can be
+ set to <code class="literal">NIL</code>, implying that the returned tuples have the
+ row type declared for the foreign table. A non-<code class="symbol">NIL</code> value must be a
+ target list (list of <code class="structname">TargetEntry</code>s) containing Vars and/or
+ expressions representing the returned columns. This might be used, for
+ example, to show that the FDW has omitted some columns that it noticed
+ won't be needed for the query. Also, if the FDW can compute expressions
+ used by the query more cheaply than can be done locally, it could add
+ those expressions to <code class="structfield">fdw_scan_tlist</code>. Note that join
+ plans (created from paths made by <code class="function">GetForeignJoinPaths</code>) must
+ always supply <code class="structfield">fdw_scan_tlist</code> to describe the set of
+ columns they will return.
+ </p><p>
+ The FDW should always construct at least one path that depends only on
+ the table's restriction clauses. In join queries, it might also choose
+ to construct path(s) that depend on join clauses, for example
+ <em class="replaceable"><code>foreign_variable</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>local_variable</code></em>. Such clauses will not be found in
+ <code class="literal">baserel-&gt;baserestrictinfo</code> but must be sought in the
+ relation's join lists. A path using such a clause is called a
+ <span class="quote">“<span class="quote">parameterized path</span>”</span>. It must identify the other relations
+ used in the selected join clause(s) with a suitable value of
+ <code class="literal">param_info</code>; use <code class="function">get_baserel_parampathinfo</code>
+ to compute that value. In <code class="function">GetForeignPlan</code>, the
+ <em class="replaceable"><code>local_variable</code></em> portion of the join clause would be added
+ to <code class="structfield">fdw_exprs</code>, and then at run time the case works the
+ same as for an ordinary restriction clause.
+ </p><p>
+ If an FDW supports remote joins, <code class="function">GetForeignJoinPaths</code> should
+ produce <code class="structname">ForeignPath</code>s for potential remote joins in much
+ the same way as <code class="function">GetForeignPaths</code> works for base tables.
+ Information about the intended join can be passed forward
+ to <code class="function">GetForeignPlan</code> in the same ways described above.
+ However, <code class="structfield">baserestrictinfo</code> is not relevant for join
+ relations; instead, the relevant join clauses for a particular join are
+ passed to <code class="function">GetForeignJoinPaths</code> as a separate parameter
+ (<code class="literal">extra-&gt;restrictlist</code>).
+ </p><p>
+ An FDW might additionally support direct execution of some plan actions
+ that are above the level of scans and joins, such as grouping or
+ aggregation. To offer such options, the FDW should generate paths and
+ insert them into the appropriate <em class="firstterm">upper relation</em>. For
+ example, a path representing remote aggregation should be inserted into
+ the <code class="literal">UPPERREL_GROUP_AGG</code> relation, using <code class="function">add_path</code>.
+ This path will be compared on a cost basis with local aggregation
+ performed by reading a simple scan path for the foreign relation (note
+ that such a path must also be supplied, else there will be an error at
+ plan time). If the remote-aggregation path wins, which it usually would,
+ it will be converted into a plan in the usual way, by
+ calling <code class="function">GetForeignPlan</code>. The recommended place to generate
+ such paths is in the <code class="function">GetForeignUpperPaths</code>
+ callback function, which is called for each upper relation (i.e., each
+ post-scan/join processing step), if all the base relations of the query
+ come from the same FDW.
+ </p><p>
+ <code class="function">PlanForeignModify</code> and the other callbacks described in
+ <a class="xref" href="fdw-callbacks.html#FDW-CALLBACKS-UPDATE" title="59.2.4. FDW Routines for Updating Foreign Tables">Section 59.2.4</a> 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 <code class="literal">ModifyTable</code>
+ plan node. This approach is necessary for the general case where an
+ update requires reading local tables as well as foreign tables.
+ However, if the operation could be executed entirely by the foreign
+ server, the FDW could generate a path representing that and insert it
+ into the <code class="literal">UPPERREL_FINAL</code> upper relation, where it would
+ compete against the <code class="literal">ModifyTable</code> approach. This approach
+ could also be used to implement remote <code class="literal">SELECT FOR UPDATE</code>,
+ rather than using the row locking callbacks described in
+ <a class="xref" href="fdw-callbacks.html#FDW-CALLBACKS-ROW-LOCKING" title="59.2.6. FDW Routines for Row Locking">Section 59.2.6</a>. Keep in mind that a path
+ inserted into <code class="literal">UPPERREL_FINAL</code> is responsible for
+ implementing <span class="emphasis"><em>all</em></span> behavior of the query.
+ </p><p>
+ When planning an <code class="command">UPDATE</code> or <code class="command">DELETE</code>,
+ <code class="function">PlanForeignModify</code> and <code class="function">PlanDirectModify</code>
+ can look up the <code class="structname">RelOptInfo</code>
+ struct for the foreign table and make use of the
+ <code class="literal">baserel-&gt;fdw_private</code> data previously created by the
+ scan-planning functions. However, in <code class="command">INSERT</code> the target
+ table is not scanned so there is no <code class="structname">RelOptInfo</code> for it.
+ The <code class="structname">List</code> returned by <code class="function">PlanForeignModify</code> has
+ the same restrictions as the <code class="structfield">fdw_private</code> list of a
+ <code class="structname">ForeignScan</code> plan node, that is it must contain only
+ structures that <code class="function">copyObject</code> knows how to copy.
+ </p><p>
+ <code class="command">INSERT</code> with an <code class="literal">ON CONFLICT</code> clause does not
+ support specifying the conflict target, as unique constraints or
+ exclusion constraints on remote tables are not locally known. This
+ in turn implies that <code class="literal">ON CONFLICT DO UPDATE</code> is not supported,
+ since the specification is mandatory there.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdw-helpers.html" title="59.3. Foreign Data Wrapper Helper Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">59.3. Foreign Data Wrapper Helper Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 59.5. Row Locking in Foreign Data Wrappers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdw-row-locking.html b/doc/src/sgml/html/fdw-row-locking.html
new file mode 100644
index 0000000..d41ffc3
--- /dev/null
+++ b/doc/src/sgml/html/fdw-row-locking.html
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>59.5. Row Locking in Foreign Data Wrappers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning" /><link rel="next" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">59.5. Row Locking in Foreign Data Wrappers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><th width="60%" align="center">Chapter 59. Writing a Foreign Data Wrapper</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Next</a></td></tr></table><hr /></div><div class="sect1" id="FDW-ROW-LOCKING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">59.5. Row Locking in Foreign Data Wrappers</h2></div></div></div><p>
+ If an FDW's underlying storage mechanism has a concept of locking
+ individual rows to prevent concurrent updates of those rows, it is
+ usually worthwhile for the FDW to perform row-level locking with as
+ close an approximation as practical to the semantics used in
+ ordinary <span class="productname">PostgreSQL</span> tables. There are multiple
+ considerations involved in this.
+ </p><p>
+ One key decision to be made is whether to perform <em class="firstterm">early
+ locking</em> or <em class="firstterm">late locking</em>. In early locking, a row is
+ locked when it is first retrieved from the underlying store, while in
+ late locking, the row is locked only when it is known that it needs to
+ be locked. (The difference arises because some rows may be discarded by
+ locally-checked restriction or join conditions.) Early locking is much
+ simpler and avoids extra round trips to a remote store, but it can cause
+ locking of rows that need not have been locked, resulting in reduced
+ concurrency or even unexpected deadlocks. Also, late locking is only
+ possible if the row to be locked can be uniquely re-identified later.
+ Preferably the row identifier should identify a specific version of the
+ row, as <span class="productname">PostgreSQL</span> TIDs do.
+ </p><p>
+ By default, <span class="productname">PostgreSQL</span> 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 <a class="xref" href="fdw-callbacks.html#FDW-CALLBACKS-ROW-LOCKING" title="59.2.6. FDW Routines for Row Locking">Section 59.2.6</a>, which were added
+ in <span class="productname">PostgreSQL</span> 9.5, allow an FDW to use late locking if
+ it wishes.
+ </p><p>
+ An additional consideration is that in <code class="literal">READ COMMITTED</code>
+ isolation mode, <span class="productname">PostgreSQL</span> may need to re-check
+ restriction and join conditions against an updated version of some
+ target tuple. Rechecking join conditions requires re-obtaining copies
+ of the non-target rows that were previously joined to the target tuple.
+ When working with standard <span class="productname">PostgreSQL</span> tables, this is
+ done by including the TIDs of the non-target tables in the column list
+ projected through the join, and then re-fetching non-target rows when
+ required. This approach keeps the join data set compact, but it
+ requires inexpensive re-fetch capability, as well as a TID that can
+ uniquely identify the row version to be re-fetched. By default,
+ therefore, the approach used with foreign tables is to include a copy of
+ the entire row fetched from a foreign table in the column list projected
+ through the join. This puts no special demands on the FDW but can
+ result in reduced performance of merge and hash joins. An FDW that is
+ capable of meeting the re-fetch requirements can choose to do it the
+ first way.
+ </p><p>
+ For an <code class="command">UPDATE</code> or <code class="command">DELETE</code> on a foreign table, it
+ is recommended that the <code class="literal">ForeignScan</code> operation on the target
+ table perform early locking on the rows that it fetches, perhaps via the
+ equivalent of <code class="command">SELECT FOR UPDATE</code>. An FDW can detect whether
+ a table is an <code class="command">UPDATE</code>/<code class="command">DELETE</code> target at plan time
+ by comparing its relid to <code class="literal">root-&gt;parse-&gt;resultRelation</code>,
+ or at execution time by using <code class="function">ExecRelationIsTargetRelation()</code>.
+ An alternative possibility is to perform late locking within the
+ <code class="function">ExecForeignUpdate</code> or <code class="function">ExecForeignDelete</code>
+ callback, but no special support is provided for this.
+ </p><p>
+ For foreign tables that are specified to be locked by a <code class="command">SELECT
+ FOR UPDATE/SHARE</code> command, the <code class="literal">ForeignScan</code> operation can
+ again perform early locking by fetching tuples with the equivalent
+ of <code class="command">SELECT FOR UPDATE/SHARE</code>. To perform late locking
+ instead, provide the callback functions defined
+ in <a class="xref" href="fdw-callbacks.html#FDW-CALLBACKS-ROW-LOCKING" title="59.2.6. FDW Routines for Row Locking">Section 59.2.6</a>.
+ In <code class="function">GetForeignRowMarkType</code>, select rowmark option
+ <code class="literal">ROW_MARK_EXCLUSIVE</code>, <code class="literal">ROW_MARK_NOKEYEXCLUSIVE</code>,
+ <code class="literal">ROW_MARK_SHARE</code>, or <code class="literal">ROW_MARK_KEYSHARE</code> depending
+ on the requested lock strength. (The core code will act the same
+ regardless of which of these four options you choose.)
+ Elsewhere, you can detect whether a foreign table was specified to be
+ locked by this type of command by using <code class="function">get_plan_rowmark</code> at
+ plan time, or <code class="function">ExecFindRowMark</code> at execution time; you must
+ check not only whether a non-null rowmark struct is returned, but that
+ its <code class="structfield">strength</code> field is not <code class="literal">LCS_NONE</code>.
+ </p><p>
+ Lastly, for foreign tables that are used in an <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code> or <code class="command">SELECT FOR UPDATE/SHARE</code> command but
+ are not specified to be row-locked, you can override the default choice
+ to copy entire rows by having <code class="function">GetForeignRowMarkType</code> select
+ option <code class="literal">ROW_MARK_REFERENCE</code> when it sees lock strength
+ <code class="literal">LCS_NONE</code>. This will cause <code class="function">RefetchForeignRow</code> to
+ be called with that value for <code class="structfield">markType</code>; it should then
+ re-fetch the row without acquiring any new lock. (If you have
+ a <code class="function">GetForeignRowMarkType</code> function but don't wish to re-fetch
+ unlocked rows, select option <code class="literal">ROW_MARK_COPY</code>
+ for <code class="literal">LCS_NONE</code>.)
+ </p><p>
+ See <code class="filename">src/include/nodes/lockoptions.h</code>, the comments
+ for <code class="type">RowMarkType</code> and <code class="type">PlanRowMark</code>
+ in <code class="filename">src/include/nodes/plannodes.h</code>, and the comments for
+ <code class="type">ExecRowMark</code> in <code class="filename">src/include/nodes/execnodes.h</code> for
+ additional information.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdw-planning.html" title="59.4. Foreign Data Wrapper Query Planning">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Next</a></td></tr><tr><td width="40%" align="left" valign="top">59.4. Foreign Data Wrapper Query Planning </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 60. Writing a Table Sampling Method</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fdwhandler.html b/doc/src/sgml/html/fdwhandler.html
new file mode 100644
index 0000000..264c262
--- /dev/null
+++ b/doc/src/sgml/html/fdwhandler.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 59. Writing a Foreign Data Wrapper</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler" /><link rel="next" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 59. Writing a Foreign Data Wrapper</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="FDWHANDLER"><div class="titlepage"><div><div><h2 class="title">Chapter 59. Writing a Foreign Data Wrapper</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="fdw-functions.html">59.1. Foreign Data Wrapper Functions</a></span></dt><dt><span class="sect1"><a href="fdw-callbacks.html">59.2. Foreign Data Wrapper Callback Routines</a></span></dt><dd><dl><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-SCAN">59.2.1. FDW Routines for Scanning Foreign Tables</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-JOIN-SCAN">59.2.2. FDW Routines for Scanning Foreign Joins</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-UPPER-PLANNING">59.2.3. FDW Routines for Planning Post-Scan/Join Processing</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-UPDATE">59.2.4. FDW Routines for Updating Foreign Tables</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-TRUNCATE">59.2.5. FDW Routines for <code class="command">TRUNCATE</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ROW-LOCKING">59.2.6. FDW Routines for Row Locking</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-EXPLAIN">59.2.7. FDW Routines for <code class="command">EXPLAIN</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ANALYZE">59.2.8. FDW Routines for <code class="command">ANALYZE</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-IMPORT">59.2.9. FDW Routines for <code class="command">IMPORT FOREIGN SCHEMA</code></a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-PARALLEL">59.2.10. FDW Routines for Parallel Execution</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-ASYNC">59.2.11. FDW Routines for Asynchronous Execution</a></span></dt><dt><span class="sect2"><a href="fdw-callbacks.html#FDW-CALLBACKS-REPARAMETERIZE-PATHS">59.2.12. FDW Routines for Reparameterization of Paths</a></span></dt></dl></dd><dt><span class="sect1"><a href="fdw-helpers.html">59.3. Foreign Data Wrapper Helper Functions</a></span></dt><dt><span class="sect1"><a href="fdw-planning.html">59.4. Foreign Data Wrapper Query Planning</a></span></dt><dt><span class="sect1"><a href="fdw-row-locking.html">59.5. Row Locking in Foreign Data Wrappers</a></span></dt></dl></div><a id="id-1.10.10.2" class="indexterm"></a><p>
+ All operations on a foreign table are handled through its foreign data
+ wrapper, which consists of a set of functions that the core server
+ calls. The foreign data wrapper is responsible for fetching
+ data from the remote data source and returning it to the
+ <span class="productname">PostgreSQL</span> executor. If updating foreign
+ tables is to be supported, the wrapper must handle that, too.
+ This chapter outlines how to write a new foreign data wrapper.
+ </p><p>
+ The foreign data wrappers included in the standard distribution are good
+ references when trying to write your own. Look into the
+ <code class="filename">contrib</code> subdirectory of the source tree.
+ The <a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a> reference page also has
+ some useful details.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The SQL standard specifies an interface for writing foreign data wrappers.
+ However, PostgreSQL does not implement that API, because the effort to
+ accommodate it into PostgreSQL would be large, and the standard API hasn't
+ gained wide adoption anyway.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdw-functions.html" title="59.1. Foreign Data Wrapper Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 58. Writing a Procedural Language Handler </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 59.1. Foreign Data Wrapper Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/features-sql-standard.html b/doc/src/sgml/html/features-sql-standard.html
new file mode 100644
index 0000000..14d7f5f
--- /dev/null
+++ b/doc/src/sgml/html/features-sql-standard.html
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>D.1. Supported Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="features.html" title="Appendix D. SQL Conformance" /><link rel="next" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">D.1. Supported Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="features.html" title="Appendix D. SQL Conformance">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><th width="60%" align="center">Appendix D. SQL Conformance</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features">Next</a></td></tr></table><hr /></div><div class="sect1" id="FEATURES-SQL-STANDARD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">D.1. Supported Features</h2></div></div></div><p>
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Identifier</th><th>Core?</th><th>Description</th><th>Comment</th></tr></thead><tbody><tr><td>B012</td><td> </td><td>Embedded C</td><td> </td></tr><tr><td>B021</td><td> </td><td>Direct SQL</td><td> </td></tr><tr><td>B128</td><td> </td><td>Routine language SQL</td><td> </td></tr><tr><td>E011</td><td>Core</td><td>Numeric data types</td><td> </td></tr><tr><td>E011-01</td><td>Core</td><td>INTEGER and SMALLINT data types</td><td> </td></tr><tr><td>E011-02</td><td>Core</td><td>REAL, DOUBLE PRECISION, and FLOAT data types</td><td> </td></tr><tr><td>E011-03</td><td>Core</td><td>DECIMAL and NUMERIC data types</td><td> </td></tr><tr><td>E011-04</td><td>Core</td><td>Arithmetic operators</td><td> </td></tr><tr><td>E011-05</td><td>Core</td><td>Numeric comparison</td><td> </td></tr><tr><td>E011-06</td><td>Core</td><td>Implicit casting among the numeric data types</td><td> </td></tr><tr><td>E021</td><td>Core</td><td>Character data types</td><td> </td></tr><tr><td>E021-01</td><td>Core</td><td>CHARACTER data type</td><td> </td></tr><tr><td>E021-02</td><td>Core</td><td>CHARACTER VARYING data type</td><td> </td></tr><tr><td>E021-03</td><td>Core</td><td>Character literals</td><td> </td></tr><tr><td>E021-04</td><td>Core</td><td>CHARACTER_LENGTH function</td><td>trims trailing spaces from CHARACTER values before counting</td></tr><tr><td>E021-05</td><td>Core</td><td>OCTET_LENGTH function</td><td> </td></tr><tr><td>E021-06</td><td>Core</td><td>SUBSTRING function</td><td> </td></tr><tr><td>E021-07</td><td>Core</td><td>Character concatenation</td><td> </td></tr><tr><td>E021-08</td><td>Core</td><td>UPPER and LOWER functions</td><td> </td></tr><tr><td>E021-09</td><td>Core</td><td>TRIM function</td><td> </td></tr><tr><td>E021-10</td><td>Core</td><td>Implicit casting among the character string types</td><td> </td></tr><tr><td>E021-11</td><td>Core</td><td>POSITION function</td><td> </td></tr><tr><td>E021-12</td><td>Core</td><td>Character comparison</td><td> </td></tr><tr><td>E031</td><td>Core</td><td>Identifiers</td><td> </td></tr><tr><td>E031-01</td><td>Core</td><td>Delimited identifiers</td><td> </td></tr><tr><td>E031-02</td><td>Core</td><td>Lower case identifiers</td><td> </td></tr><tr><td>E031-03</td><td>Core</td><td>Trailing underscore</td><td> </td></tr><tr><td>E051</td><td>Core</td><td>Basic query specification</td><td> </td></tr><tr><td>E051-01</td><td>Core</td><td>SELECT DISTINCT</td><td> </td></tr><tr><td>E051-02</td><td>Core</td><td>GROUP BY clause</td><td> </td></tr><tr><td>E051-04</td><td>Core</td><td>GROUP BY can contain columns not in &lt;select list&gt;</td><td> </td></tr><tr><td>E051-05</td><td>Core</td><td>Select list items can be renamed</td><td> </td></tr><tr><td>E051-06</td><td>Core</td><td>HAVING clause</td><td> </td></tr><tr><td>E051-07</td><td>Core</td><td>Qualified * in select list</td><td> </td></tr><tr><td>E051-08</td><td>Core</td><td>Correlation names in the FROM clause</td><td> </td></tr><tr><td>E051-09</td><td>Core</td><td>Rename columns in the FROM clause</td><td> </td></tr><tr><td>E061</td><td>Core</td><td>Basic predicates and search conditions</td><td> </td></tr><tr><td>E061-01</td><td>Core</td><td>Comparison predicate</td><td> </td></tr><tr><td>E061-02</td><td>Core</td><td>BETWEEN predicate</td><td> </td></tr><tr><td>E061-03</td><td>Core</td><td>IN predicate with list of values</td><td> </td></tr><tr><td>E061-04</td><td>Core</td><td>LIKE predicate</td><td> </td></tr><tr><td>E061-05</td><td>Core</td><td>LIKE predicate ESCAPE clause</td><td> </td></tr><tr><td>E061-06</td><td>Core</td><td>NULL predicate</td><td> </td></tr><tr><td>E061-07</td><td>Core</td><td>Quantified comparison predicate</td><td> </td></tr><tr><td>E061-08</td><td>Core</td><td>EXISTS predicate</td><td> </td></tr><tr><td>E061-09</td><td>Core</td><td>Subqueries in comparison predicate</td><td> </td></tr><tr><td>E061-11</td><td>Core</td><td>Subqueries in IN predicate</td><td> </td></tr><tr><td>E061-12</td><td>Core</td><td>Subqueries in quantified comparison predicate</td><td> </td></tr><tr><td>E061-13</td><td>Core</td><td>Correlated subqueries</td><td> </td></tr><tr><td>E061-14</td><td>Core</td><td>Search condition</td><td> </td></tr><tr><td>E071</td><td>Core</td><td>Basic query expressions</td><td> </td></tr><tr><td>E071-01</td><td>Core</td><td>UNION DISTINCT table operator</td><td> </td></tr><tr><td>E071-02</td><td>Core</td><td>UNION ALL table operator</td><td> </td></tr><tr><td>E071-03</td><td>Core</td><td>EXCEPT DISTINCT table operator</td><td> </td></tr><tr><td>E071-05</td><td>Core</td><td>Columns combined via table operators need not have exactly the same data type</td><td> </td></tr><tr><td>E071-06</td><td>Core</td><td>Table operators in subqueries</td><td> </td></tr><tr><td>E081</td><td>Core</td><td>Basic Privileges</td><td> </td></tr><tr><td>E081-01</td><td>Core</td><td>SELECT privilege</td><td> </td></tr><tr><td>E081-02</td><td>Core</td><td>DELETE privilege</td><td> </td></tr><tr><td>E081-03</td><td>Core</td><td>INSERT privilege at the table level</td><td> </td></tr><tr><td>E081-04</td><td>Core</td><td>UPDATE privilege at the table level</td><td> </td></tr><tr><td>E081-05</td><td>Core</td><td>UPDATE privilege at the column level</td><td> </td></tr><tr><td>E081-06</td><td>Core</td><td>REFERENCES privilege at the table level</td><td> </td></tr><tr><td>E081-07</td><td>Core</td><td>REFERENCES privilege at the column level</td><td> </td></tr><tr><td>E081-08</td><td>Core</td><td>WITH GRANT OPTION</td><td> </td></tr><tr><td>E081-09</td><td>Core</td><td>USAGE privilege</td><td> </td></tr><tr><td>E081-10</td><td>Core</td><td>EXECUTE privilege</td><td> </td></tr><tr><td>E091</td><td>Core</td><td>Set functions</td><td> </td></tr><tr><td>E091-01</td><td>Core</td><td>AVG</td><td> </td></tr><tr><td>E091-02</td><td>Core</td><td>COUNT</td><td> </td></tr><tr><td>E091-03</td><td>Core</td><td>MAX</td><td> </td></tr><tr><td>E091-04</td><td>Core</td><td>MIN</td><td> </td></tr><tr><td>E091-05</td><td>Core</td><td>SUM</td><td> </td></tr><tr><td>E091-06</td><td>Core</td><td>ALL quantifier</td><td> </td></tr><tr><td>E091-07</td><td>Core</td><td>DISTINCT quantifier</td><td> </td></tr><tr><td>E101</td><td>Core</td><td>Basic data manipulation</td><td> </td></tr><tr><td>E101-01</td><td>Core</td><td>INSERT statement</td><td> </td></tr><tr><td>E101-03</td><td>Core</td><td>Searched UPDATE statement</td><td> </td></tr><tr><td>E101-04</td><td>Core</td><td>Searched DELETE statement</td><td> </td></tr><tr><td>E111</td><td>Core</td><td>Single row SELECT statement</td><td> </td></tr><tr><td>E121</td><td>Core</td><td>Basic cursor support</td><td> </td></tr><tr><td>E121-01</td><td>Core</td><td>DECLARE CURSOR</td><td> </td></tr><tr><td>E121-02</td><td>Core</td><td>ORDER BY columns need not be in select list</td><td> </td></tr><tr><td>E121-03</td><td>Core</td><td>Value expressions in ORDER BY clause</td><td> </td></tr><tr><td>E121-04</td><td>Core</td><td>OPEN statement</td><td> </td></tr><tr><td>E121-06</td><td>Core</td><td>Positioned UPDATE statement</td><td> </td></tr><tr><td>E121-07</td><td>Core</td><td>Positioned DELETE statement</td><td> </td></tr><tr><td>E121-08</td><td>Core</td><td>CLOSE statement</td><td> </td></tr><tr><td>E121-10</td><td>Core</td><td>FETCH statement implicit NEXT</td><td> </td></tr><tr><td>E121-17</td><td>Core</td><td>WITH HOLD cursors</td><td> </td></tr><tr><td>E131</td><td>Core</td><td>Null value support (nulls in lieu of values)</td><td> </td></tr><tr><td>E141</td><td>Core</td><td>Basic integrity constraints</td><td> </td></tr><tr><td>E141-01</td><td>Core</td><td>NOT NULL constraints</td><td> </td></tr><tr><td>E141-02</td><td>Core</td><td>UNIQUE constraints of NOT NULL columns</td><td> </td></tr><tr><td>E141-03</td><td>Core</td><td>PRIMARY KEY constraints</td><td> </td></tr><tr><td>E141-04</td><td>Core</td><td>Basic FOREIGN KEY constraint with the NO ACTION default for both referential delete action and referential update action</td><td> </td></tr><tr><td>E141-06</td><td>Core</td><td>CHECK constraints</td><td> </td></tr><tr><td>E141-07</td><td>Core</td><td>Column defaults</td><td> </td></tr><tr><td>E141-08</td><td>Core</td><td>NOT NULL inferred on PRIMARY KEY</td><td> </td></tr><tr><td>E141-10</td><td>Core</td><td>Names in a foreign key can be specified in any order</td><td> </td></tr><tr><td>E151</td><td>Core</td><td>Transaction support</td><td> </td></tr><tr><td>E151-01</td><td>Core</td><td>COMMIT statement</td><td> </td></tr><tr><td>E151-02</td><td>Core</td><td>ROLLBACK statement</td><td> </td></tr><tr><td>E152</td><td>Core</td><td>Basic SET TRANSACTION statement</td><td> </td></tr><tr><td>E152-01</td><td>Core</td><td>SET TRANSACTION statement: ISOLATION LEVEL SERIALIZABLE clause</td><td> </td></tr><tr><td>E152-02</td><td>Core</td><td>SET TRANSACTION statement: READ ONLY and READ WRITE clauses</td><td> </td></tr><tr><td>E153</td><td>Core</td><td>Updatable queries with subqueries</td><td> </td></tr><tr><td>E161</td><td>Core</td><td>SQL comments using leading double minus</td><td> </td></tr><tr><td>E171</td><td>Core</td><td>SQLSTATE support</td><td> </td></tr><tr><td>E182</td><td>Core</td><td>Host language binding</td><td> </td></tr><tr><td>F021</td><td>Core</td><td>Basic information schema</td><td> </td></tr><tr><td>F021-01</td><td>Core</td><td>COLUMNS view</td><td> </td></tr><tr><td>F021-02</td><td>Core</td><td>TABLES view</td><td> </td></tr><tr><td>F021-03</td><td>Core</td><td>VIEWS view</td><td> </td></tr><tr><td>F021-04</td><td>Core</td><td>TABLE_CONSTRAINTS view</td><td> </td></tr><tr><td>F021-05</td><td>Core</td><td>REFERENTIAL_CONSTRAINTS view</td><td> </td></tr><tr><td>F021-06</td><td>Core</td><td>CHECK_CONSTRAINTS view</td><td> </td></tr><tr><td>F031</td><td>Core</td><td>Basic schema manipulation</td><td> </td></tr><tr><td>F031-01</td><td>Core</td><td>CREATE TABLE statement to create persistent base tables</td><td> </td></tr><tr><td>F031-02</td><td>Core</td><td>CREATE VIEW statement</td><td> </td></tr><tr><td>F031-03</td><td>Core</td><td>GRANT statement</td><td> </td></tr><tr><td>F031-04</td><td>Core</td><td>ALTER TABLE statement: ADD COLUMN clause</td><td> </td></tr><tr><td>F031-13</td><td>Core</td><td>DROP TABLE statement: RESTRICT clause</td><td> </td></tr><tr><td>F031-16</td><td>Core</td><td>DROP VIEW statement: RESTRICT clause</td><td> </td></tr><tr><td>F031-19</td><td>Core</td><td>REVOKE statement: RESTRICT clause</td><td> </td></tr><tr><td>F032</td><td> </td><td>CASCADE drop behavior</td><td> </td></tr><tr><td>F033</td><td> </td><td>ALTER TABLE statement: DROP COLUMN clause</td><td> </td></tr><tr><td>F034</td><td> </td><td>Extended REVOKE statement</td><td> </td></tr><tr><td>F034-01</td><td> </td><td>REVOKE statement performed by other than the owner of a schema object</td><td> </td></tr><tr><td>F034-02</td><td> </td><td>REVOKE statement: GRANT OPTION FOR clause</td><td> </td></tr><tr><td>F034-03</td><td> </td><td>REVOKE statement to revoke a privilege that the grantee has WITH GRANT OPTION</td><td> </td></tr><tr><td>F041</td><td>Core</td><td>Basic joined table</td><td> </td></tr><tr><td>F041-01</td><td>Core</td><td>Inner join (but not necessarily the INNER keyword)</td><td> </td></tr><tr><td>F041-02</td><td>Core</td><td>INNER keyword</td><td> </td></tr><tr><td>F041-03</td><td>Core</td><td>LEFT OUTER JOIN</td><td> </td></tr><tr><td>F041-04</td><td>Core</td><td>RIGHT OUTER JOIN</td><td> </td></tr><tr><td>F041-05</td><td>Core</td><td>Outer joins can be nested</td><td> </td></tr><tr><td>F041-07</td><td>Core</td><td>The inner table in a left or right outer join can also be used in an inner join</td><td> </td></tr><tr><td>F041-08</td><td>Core</td><td>All comparison operators are supported (rather than just =)</td><td> </td></tr><tr><td>F051</td><td>Core</td><td>Basic date and time</td><td> </td></tr><tr><td>F051-01</td><td>Core</td><td>DATE data type (including support of DATE literal)</td><td> </td></tr><tr><td>F051-02</td><td>Core</td><td>TIME data type (including support of TIME literal) with fractional seconds precision of at least 0</td><td> </td></tr><tr><td>F051-03</td><td>Core</td><td>TIMESTAMP data type (including support of TIMESTAMP literal) with fractional seconds precision of at least 0 and 6</td><td> </td></tr><tr><td>F051-04</td><td>Core</td><td>Comparison predicate on DATE, TIME, and TIMESTAMP data types</td><td> </td></tr><tr><td>F051-05</td><td>Core</td><td>Explicit CAST between datetime types and character string types</td><td> </td></tr><tr><td>F051-06</td><td>Core</td><td>CURRENT_DATE</td><td> </td></tr><tr><td>F051-07</td><td>Core</td><td>LOCALTIME</td><td> </td></tr><tr><td>F051-08</td><td>Core</td><td>LOCALTIMESTAMP</td><td> </td></tr><tr><td>F052</td><td> </td><td>Intervals and datetime arithmetic</td><td> </td></tr><tr><td>F053</td><td> </td><td>OVERLAPS predicate</td><td> </td></tr><tr><td>F081</td><td>Core</td><td>UNION and EXCEPT in views</td><td> </td></tr><tr><td>F111</td><td> </td><td>Isolation levels other than SERIALIZABLE</td><td> </td></tr><tr><td>F111-01</td><td> </td><td>READ UNCOMMITTED isolation level</td><td> </td></tr><tr><td>F111-02</td><td> </td><td>READ COMMITTED isolation level</td><td> </td></tr><tr><td>F111-03</td><td> </td><td>REPEATABLE READ isolation level</td><td> </td></tr><tr><td>F131</td><td>Core</td><td>Grouped operations</td><td> </td></tr><tr><td>F131-01</td><td>Core</td><td>WHERE, GROUP BY, and HAVING clauses supported in queries with grouped views</td><td> </td></tr><tr><td>F131-02</td><td>Core</td><td>Multiple tables supported in queries with grouped views</td><td> </td></tr><tr><td>F131-03</td><td>Core</td><td>Set functions supported in queries with grouped views</td><td> </td></tr><tr><td>F131-04</td><td>Core</td><td>Subqueries with GROUP BY and HAVING clauses and grouped views</td><td> </td></tr><tr><td>F131-05</td><td>Core</td><td>Single row SELECT with GROUP BY and HAVING clauses and grouped views</td><td> </td></tr><tr><td>F171</td><td> </td><td>Multiple schemas per user</td><td> </td></tr><tr><td>F181</td><td>Core</td><td>Multiple module support</td><td> </td></tr><tr><td>F191</td><td> </td><td>Referential delete actions</td><td> </td></tr><tr><td>F200</td><td> </td><td>TRUNCATE TABLE statement</td><td> </td></tr><tr><td>F201</td><td>Core</td><td>CAST function</td><td> </td></tr><tr><td>F202</td><td> </td><td>TRUNCATE TABLE: identity column restart option</td><td> </td></tr><tr><td>F221</td><td>Core</td><td>Explicit defaults</td><td> </td></tr><tr><td>F222</td><td> </td><td>INSERT statement: DEFAULT VALUES clause</td><td> </td></tr><tr><td>F231</td><td> </td><td>Privilege tables</td><td> </td></tr><tr><td>F231-01</td><td> </td><td>TABLE_PRIVILEGES view</td><td> </td></tr><tr><td>F231-02</td><td> </td><td>COLUMN_PRIVILEGES view</td><td> </td></tr><tr><td>F231-03</td><td> </td><td>USAGE_PRIVILEGES view</td><td> </td></tr><tr><td>F251</td><td> </td><td>Domain support</td><td> </td></tr><tr><td>F261</td><td>Core</td><td>CASE expression</td><td> </td></tr><tr><td>F261-01</td><td>Core</td><td>Simple CASE</td><td> </td></tr><tr><td>F261-02</td><td>Core</td><td>Searched CASE</td><td> </td></tr><tr><td>F261-03</td><td>Core</td><td>NULLIF</td><td> </td></tr><tr><td>F261-04</td><td>Core</td><td>COALESCE</td><td> </td></tr><tr><td>F262</td><td> </td><td>Extended CASE expression</td><td> </td></tr><tr><td>F271</td><td> </td><td>Compound character literals</td><td> </td></tr><tr><td>F281</td><td> </td><td>LIKE enhancements</td><td> </td></tr><tr><td>F292</td><td> </td><td>UNIQUE null treatment</td><td>SQL:202x draft</td></tr><tr><td>F302</td><td> </td><td>INTERSECT table operator</td><td> </td></tr><tr><td>F302-01</td><td> </td><td>INTERSECT DISTINCT table operator</td><td> </td></tr><tr><td>F302-02</td><td> </td><td>INTERSECT ALL table operator</td><td> </td></tr><tr><td>F304</td><td> </td><td>EXCEPT ALL table operator</td><td> </td></tr><tr><td>F311</td><td>Core</td><td>Schema definition statement</td><td> </td></tr><tr><td>F311-01</td><td>Core</td><td>CREATE SCHEMA</td><td> </td></tr><tr><td>F311-02</td><td>Core</td><td>CREATE TABLE for persistent base tables</td><td> </td></tr><tr><td>F311-03</td><td>Core</td><td>CREATE VIEW</td><td> </td></tr><tr><td>F311-04</td><td>Core</td><td>CREATE VIEW: WITH CHECK OPTION</td><td> </td></tr><tr><td>F311-05</td><td>Core</td><td>GRANT statement</td><td> </td></tr><tr><td>F312</td><td> </td><td>MERGE statement</td><td> </td></tr><tr><td>F313</td><td> </td><td>Enhanced MERGE statement</td><td> </td></tr><tr><td>F314</td><td> </td><td>MERGE statement with DELETE branch</td><td> </td></tr><tr><td>F321</td><td> </td><td>User authorization</td><td> </td></tr><tr><td>F341</td><td> </td><td>Usage tables</td><td> </td></tr><tr><td>F361</td><td> </td><td>Subprogram support</td><td> </td></tr><tr><td>F381</td><td> </td><td>Extended schema manipulation</td><td> </td></tr><tr><td>F381-01</td><td> </td><td>ALTER TABLE statement: ALTER COLUMN clause</td><td> </td></tr><tr><td>F381-02</td><td> </td><td>ALTER TABLE statement: ADD CONSTRAINT clause</td><td> </td></tr><tr><td>F381-03</td><td> </td><td>ALTER TABLE statement: DROP CONSTRAINT clause</td><td> </td></tr><tr><td>F382</td><td> </td><td>Alter column data type</td><td> </td></tr><tr><td>F383</td><td> </td><td>Set column not null clause</td><td> </td></tr><tr><td>F384</td><td> </td><td>Drop identity property clause</td><td> </td></tr><tr><td>F385</td><td> </td><td>Drop column generation expression clause</td><td> </td></tr><tr><td>F386</td><td> </td><td>Set identity column generation clause</td><td> </td></tr><tr><td>F391</td><td> </td><td>Long identifiers</td><td> </td></tr><tr><td>F392</td><td> </td><td>Unicode escapes in identifiers</td><td> </td></tr><tr><td>F393</td><td> </td><td>Unicode escapes in literals</td><td> </td></tr><tr><td>F394</td><td> </td><td>Optional normal form specification</td><td> </td></tr><tr><td>F401</td><td> </td><td>Extended joined table</td><td> </td></tr><tr><td>F401-01</td><td> </td><td>NATURAL JOIN</td><td> </td></tr><tr><td>F401-02</td><td> </td><td>FULL OUTER JOIN</td><td> </td></tr><tr><td>F401-04</td><td> </td><td>CROSS JOIN</td><td> </td></tr><tr><td>F402</td><td> </td><td>Named column joins for LOBs, arrays, and multisets</td><td> </td></tr><tr><td>F404</td><td> </td><td>Range variable for common column names</td><td> </td></tr><tr><td>F411</td><td> </td><td>Time zone specification</td><td>differences regarding literal interpretation</td></tr><tr><td>F421</td><td> </td><td>National character</td><td> </td></tr><tr><td>F431</td><td> </td><td>Read-only scrollable cursors</td><td> </td></tr><tr><td>F431-01</td><td> </td><td>FETCH with explicit NEXT</td><td> </td></tr><tr><td>F431-02</td><td> </td><td>FETCH FIRST</td><td> </td></tr><tr><td>F431-03</td><td> </td><td>FETCH LAST</td><td> </td></tr><tr><td>F431-04</td><td> </td><td>FETCH PRIOR</td><td> </td></tr><tr><td>F431-05</td><td> </td><td>FETCH ABSOLUTE</td><td> </td></tr><tr><td>F431-06</td><td> </td><td>FETCH RELATIVE</td><td> </td></tr><tr><td>F441</td><td> </td><td>Extended set function support</td><td> </td></tr><tr><td>F442</td><td> </td><td>Mixed column references in set functions</td><td> </td></tr><tr><td>F471</td><td>Core</td><td>Scalar subquery values</td><td> </td></tr><tr><td>F481</td><td>Core</td><td>Expanded NULL predicate</td><td> </td></tr><tr><td>F491</td><td> </td><td>Constraint management</td><td> </td></tr><tr><td>F501</td><td>Core</td><td>Features and conformance views</td><td> </td></tr><tr><td>F501-01</td><td>Core</td><td>SQL_FEATURES view</td><td> </td></tr><tr><td>F501-02</td><td>Core</td><td>SQL_SIZING view</td><td> </td></tr><tr><td>F502</td><td> </td><td>Enhanced documentation tables</td><td> </td></tr><tr><td>F531</td><td> </td><td>Temporary tables</td><td> </td></tr><tr><td>F555</td><td> </td><td>Enhanced seconds precision</td><td> </td></tr><tr><td>F561</td><td> </td><td>Full value expressions</td><td> </td></tr><tr><td>F571</td><td> </td><td>Truth value tests</td><td> </td></tr><tr><td>F591</td><td> </td><td>Derived tables</td><td> </td></tr><tr><td>F611</td><td> </td><td>Indicator data types</td><td> </td></tr><tr><td>F641</td><td> </td><td>Row and table constructors</td><td> </td></tr><tr><td>F651</td><td> </td><td>Catalog name qualifiers</td><td> </td></tr><tr><td>F661</td><td> </td><td>Simple tables</td><td> </td></tr><tr><td>F672</td><td> </td><td>Retrospective check constraints</td><td> </td></tr><tr><td>F690</td><td> </td><td>Collation support</td><td>but no character set support</td></tr><tr><td>F692</td><td> </td><td>Extended collation support</td><td> </td></tr><tr><td>F701</td><td> </td><td>Referential update actions</td><td> </td></tr><tr><td>F711</td><td> </td><td>ALTER domain</td><td> </td></tr><tr><td>F731</td><td> </td><td>INSERT column privileges</td><td> </td></tr><tr><td>F751</td><td> </td><td>View CHECK enhancements</td><td> </td></tr><tr><td>F761</td><td> </td><td>Session management</td><td> </td></tr><tr><td>F762</td><td> </td><td>CURRENT_CATALOG</td><td> </td></tr><tr><td>F763</td><td> </td><td>CURRENT_SCHEMA</td><td> </td></tr><tr><td>F771</td><td> </td><td>Connection management</td><td> </td></tr><tr><td>F781</td><td> </td><td>Self-referencing operations</td><td> </td></tr><tr><td>F791</td><td> </td><td>Insensitive cursors</td><td> </td></tr><tr><td>F801</td><td> </td><td>Full set function</td><td> </td></tr><tr><td>F850</td><td> </td><td>Top-level &lt;order by clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F851</td><td> </td><td>&lt;order by clause&gt; in subqueries</td><td> </td></tr><tr><td>F852</td><td> </td><td>Top-level &lt;order by clause&gt; in views</td><td> </td></tr><tr><td>F855</td><td> </td><td>Nested &lt;order by clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F856</td><td> </td><td>Nested &lt;fetch first clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F857</td><td> </td><td>Top-level &lt;fetch first clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F858</td><td> </td><td>&lt;fetch first clause&gt; in subqueries</td><td> </td></tr><tr><td>F859</td><td> </td><td>Top-level &lt;fetch first clause&gt; in views</td><td> </td></tr><tr><td>F860</td><td> </td><td>&lt;fetch first row count&gt; in &lt;fetch first clause&gt;</td><td> </td></tr><tr><td>F861</td><td> </td><td>Top-level &lt;result offset clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F862</td><td> </td><td>&lt;result offset clause&gt; in subqueries</td><td> </td></tr><tr><td>F863</td><td> </td><td>Nested &lt;result offset clause&gt; in &lt;query expression&gt;</td><td> </td></tr><tr><td>F864</td><td> </td><td>Top-level &lt;result offset clause&gt; in views</td><td> </td></tr><tr><td>F865</td><td> </td><td>&lt;offset row count&gt; in &lt;result offset clause&gt;</td><td> </td></tr><tr><td>F867</td><td> </td><td>FETCH FIRST clause: WITH TIES option</td><td> </td></tr><tr><td>S071</td><td> </td><td>SQL paths in function and type name resolution</td><td> </td></tr><tr><td>S091-01</td><td> </td><td>Arrays of built-in data types</td><td> </td></tr><tr><td>S091-03</td><td> </td><td>Array expressions</td><td> </td></tr><tr><td>S092</td><td> </td><td>Arrays of user-defined types</td><td> </td></tr><tr><td>S095</td><td> </td><td>Array constructors by query</td><td> </td></tr><tr><td>S096</td><td> </td><td>Optional array bounds</td><td> </td></tr><tr><td>S098</td><td> </td><td>ARRAY_AGG</td><td> </td></tr><tr><td>S111</td><td> </td><td>ONLY in query expressions</td><td> </td></tr><tr><td>S201</td><td> </td><td>SQL-invoked routines on arrays</td><td> </td></tr><tr><td>S201-01</td><td> </td><td>Array parameters</td><td> </td></tr><tr><td>S201-02</td><td> </td><td>Array as result type of functions</td><td> </td></tr><tr><td>S211</td><td> </td><td>User-defined cast functions</td><td> </td></tr><tr><td>S301</td><td> </td><td>Enhanced UNNEST</td><td> </td></tr><tr><td>S404</td><td> </td><td>TRIM_ARRAY</td><td> </td></tr><tr><td>T031</td><td> </td><td>BOOLEAN data type</td><td> </td></tr><tr><td>T071</td><td> </td><td>BIGINT data type</td><td> </td></tr><tr><td>T121</td><td> </td><td>WITH (excluding RECURSIVE) in query expression</td><td> </td></tr><tr><td>T122</td><td> </td><td>WITH (excluding RECURSIVE) in subquery</td><td> </td></tr><tr><td>T131</td><td> </td><td>Recursive query</td><td> </td></tr><tr><td>T132</td><td> </td><td>Recursive query in subquery</td><td> </td></tr><tr><td>T133</td><td> </td><td>Enhanced cycle mark values</td><td>SQL:202x draft</td></tr><tr><td>T141</td><td> </td><td>SIMILAR predicate</td><td> </td></tr><tr><td>T151</td><td> </td><td>DISTINCT predicate</td><td> </td></tr><tr><td>T152</td><td> </td><td>DISTINCT predicate with negation</td><td> </td></tr><tr><td>T171</td><td> </td><td>LIKE clause in table definition</td><td> </td></tr><tr><td>T172</td><td> </td><td>AS subquery clause in table definition</td><td> </td></tr><tr><td>T173</td><td> </td><td>Extended LIKE clause in table definition</td><td> </td></tr><tr><td>T174</td><td> </td><td>Identity columns</td><td> </td></tr><tr><td>T177</td><td> </td><td>Sequence generator support: simple restart option</td><td> </td></tr><tr><td>T178</td><td> </td><td>Identity columns: simple restart option</td><td> </td></tr><tr><td>T191</td><td> </td><td>Referential action RESTRICT</td><td> </td></tr><tr><td>T201</td><td> </td><td>Comparable data types for referential constraints</td><td> </td></tr><tr><td>T211-01</td><td> </td><td>Triggers activated on UPDATE, INSERT, or DELETE of one base table</td><td> </td></tr><tr><td>T211-02</td><td> </td><td>BEFORE triggers</td><td> </td></tr><tr><td>T211-03</td><td> </td><td>AFTER triggers</td><td> </td></tr><tr><td>T211-04</td><td> </td><td>FOR EACH ROW triggers</td><td> </td></tr><tr><td>T211-05</td><td> </td><td>Ability to specify a search condition that must be true before the trigger is invoked</td><td> </td></tr><tr><td>T211-07</td><td> </td><td>TRIGGER privilege</td><td> </td></tr><tr><td>T212</td><td> </td><td>Enhanced trigger capability</td><td> </td></tr><tr><td>T213</td><td> </td><td>INSTEAD OF triggers</td><td> </td></tr><tr><td>T241</td><td> </td><td>START TRANSACTION statement</td><td> </td></tr><tr><td>T261</td><td> </td><td>Chained transactions</td><td> </td></tr><tr><td>T271</td><td> </td><td>Savepoints</td><td> </td></tr><tr><td>T281</td><td> </td><td>SELECT privilege with column granularity</td><td> </td></tr><tr><td>T285</td><td> </td><td>Enhanced derived column names</td><td> </td></tr><tr><td>T312</td><td> </td><td>OVERLAY function</td><td> </td></tr><tr><td>T321-01</td><td>Core</td><td>User-defined functions with no overloading</td><td> </td></tr><tr><td>T321-02</td><td>Core</td><td>User-defined stored procedures with no overloading</td><td> </td></tr><tr><td>T321-03</td><td>Core</td><td>Function invocation</td><td> </td></tr><tr><td>T321-04</td><td>Core</td><td>CALL statement</td><td> </td></tr><tr><td>T321-05</td><td>Core</td><td>RETURN statement</td><td> </td></tr><tr><td>T321-06</td><td>Core</td><td>ROUTINES view</td><td> </td></tr><tr><td>T321-07</td><td>Core</td><td>PARAMETERS view</td><td> </td></tr><tr><td>T323</td><td> </td><td>Explicit security for external routines</td><td> </td></tr><tr><td>T325</td><td> </td><td>Qualified SQL parameter references</td><td> </td></tr><tr><td>T331</td><td> </td><td>Basic roles</td><td> </td></tr><tr><td>T332</td><td> </td><td>Extended roles</td><td> </td></tr><tr><td>T341</td><td> </td><td>Overloading of SQL-invoked functions and procedures</td><td> </td></tr><tr><td>T351</td><td> </td><td>Bracketed SQL comments (/*...*/ comments)</td><td> </td></tr><tr><td>T431</td><td> </td><td>Extended grouping capabilities</td><td> </td></tr><tr><td>T432</td><td> </td><td>Nested and concatenated GROUPING SETS</td><td> </td></tr><tr><td>T433</td><td> </td><td>Multiargument GROUPING function</td><td> </td></tr><tr><td>T434</td><td> </td><td>GROUP BY DISTINCT</td><td> </td></tr><tr><td>T441</td><td> </td><td>ABS and MOD functions</td><td> </td></tr><tr><td>T461</td><td> </td><td>Symmetric BETWEEN predicate</td><td> </td></tr><tr><td>T491</td><td> </td><td>LATERAL derived table</td><td> </td></tr><tr><td>T501</td><td> </td><td>Enhanced EXISTS predicate</td><td> </td></tr><tr><td>T521</td><td> </td><td>Named arguments in CALL statement</td><td> </td></tr><tr><td>T523</td><td> </td><td>Default values for INOUT parameters of SQL-invoked procedures</td><td> </td></tr><tr><td>T524</td><td> </td><td>Named arguments in routine invocations other than a CALL statement</td><td> </td></tr><tr><td>T525</td><td> </td><td>Default values for parameters of SQL-invoked functions</td><td> </td></tr><tr><td>T551</td><td> </td><td>Optional key words for default syntax</td><td> </td></tr><tr><td>T581</td><td> </td><td>Regular expression substring function</td><td> </td></tr><tr><td>T591</td><td> </td><td>UNIQUE constraints of possibly null columns</td><td> </td></tr><tr><td>T611</td><td> </td><td>Elementary OLAP operations</td><td> </td></tr><tr><td>T612</td><td> </td><td>Advanced OLAP operations</td><td> </td></tr><tr><td>T613</td><td> </td><td>Sampling</td><td> </td></tr><tr><td>T614</td><td> </td><td>NTILE function</td><td> </td></tr><tr><td>T615</td><td> </td><td>LEAD and LAG functions</td><td> </td></tr><tr><td>T617</td><td> </td><td>FIRST_VALUE and LAST_VALUE function</td><td> </td></tr><tr><td>T620</td><td> </td><td>WINDOW clause: GROUPS option</td><td> </td></tr><tr><td>T621</td><td> </td><td>Enhanced numeric functions</td><td> </td></tr><tr><td>T622</td><td> </td><td>Trigonometric functions</td><td> </td></tr><tr><td>T623</td><td> </td><td>General logarithm functions</td><td> </td></tr><tr><td>T624</td><td> </td><td>Common logarithm functions</td><td> </td></tr><tr><td>T631</td><td>Core</td><td>IN predicate with one list element</td><td> </td></tr><tr><td>T651</td><td> </td><td>SQL-schema statements in SQL routines</td><td> </td></tr><tr><td>T653</td><td> </td><td>SQL-schema statements in external routines</td><td> </td></tr><tr><td>T655</td><td> </td><td>Cyclically dependent routines</td><td> </td></tr><tr><td>T831</td><td> </td><td>SQL/JSON path language: strict mode</td><td> </td></tr><tr><td>T832</td><td> </td><td>SQL/JSON path language: item method</td><td> </td></tr><tr><td>T833</td><td> </td><td>SQL/JSON path language: multiple subscripts</td><td> </td></tr><tr><td>T834</td><td> </td><td>SQL/JSON path language: wildcard member accessor</td><td> </td></tr><tr><td>T835</td><td> </td><td>SQL/JSON path language: filter expressions</td><td> </td></tr><tr><td>T836</td><td> </td><td>SQL/JSON path language: starts with predicate</td><td> </td></tr><tr><td>T837</td><td> </td><td>SQL/JSON path language: regex_like predicate</td><td> </td></tr><tr><td>X010</td><td> </td><td>XML type</td><td> </td></tr><tr><td>X011</td><td> </td><td>Arrays of XML type</td><td> </td></tr><tr><td>X014</td><td> </td><td>Attributes of XML type</td><td> </td></tr><tr><td>X016</td><td> </td><td>Persistent XML values</td><td> </td></tr><tr><td>X020</td><td> </td><td>XMLConcat</td><td> </td></tr><tr><td>X031</td><td> </td><td>XMLElement</td><td> </td></tr><tr><td>X032</td><td> </td><td>XMLForest</td><td> </td></tr><tr><td>X034</td><td> </td><td>XMLAgg</td><td> </td></tr><tr><td>X035</td><td> </td><td>XMLAgg: ORDER BY option</td><td> </td></tr><tr><td>X036</td><td> </td><td>XMLComment</td><td> </td></tr><tr><td>X037</td><td> </td><td>XMLPI</td><td> </td></tr><tr><td>X040</td><td> </td><td>Basic table mapping</td><td> </td></tr><tr><td>X041</td><td> </td><td>Basic table mapping: nulls absent</td><td> </td></tr><tr><td>X042</td><td> </td><td>Basic table mapping: null as nil</td><td> </td></tr><tr><td>X043</td><td> </td><td>Basic table mapping: table as forest</td><td> </td></tr><tr><td>X044</td><td> </td><td>Basic table mapping: table as element</td><td> </td></tr><tr><td>X045</td><td> </td><td>Basic table mapping: with target namespace</td><td> </td></tr><tr><td>X046</td><td> </td><td>Basic table mapping: data mapping</td><td> </td></tr><tr><td>X047</td><td> </td><td>Basic table mapping: metadata mapping</td><td> </td></tr><tr><td>X048</td><td> </td><td>Basic table mapping: base64 encoding of binary strings</td><td> </td></tr><tr><td>X049</td><td> </td><td>Basic table mapping: hex encoding of binary strings</td><td> </td></tr><tr><td>X050</td><td> </td><td>Advanced table mapping</td><td> </td></tr><tr><td>X051</td><td> </td><td>Advanced table mapping: nulls absent</td><td> </td></tr><tr><td>X052</td><td> </td><td>Advanced table mapping: null as nil</td><td> </td></tr><tr><td>X053</td><td> </td><td>Advanced table mapping: table as forest</td><td> </td></tr><tr><td>X054</td><td> </td><td>Advanced table mapping: table as element</td><td> </td></tr><tr><td>X055</td><td> </td><td>Advanced table mapping: with target namespace</td><td> </td></tr><tr><td>X056</td><td> </td><td>Advanced table mapping: data mapping</td><td> </td></tr><tr><td>X057</td><td> </td><td>Advanced table mapping: metadata mapping</td><td> </td></tr><tr><td>X058</td><td> </td><td>Advanced table mapping: base64 encoding of binary strings</td><td> </td></tr><tr><td>X059</td><td> </td><td>Advanced table mapping: hex encoding of binary strings</td><td> </td></tr><tr><td>X060</td><td> </td><td>XMLParse: character string input and CONTENT option</td><td> </td></tr><tr><td>X061</td><td> </td><td>XMLParse: character string input and DOCUMENT option</td><td> </td></tr><tr><td>X070</td><td> </td><td>XMLSerialize: character string serialization and CONTENT option</td><td> </td></tr><tr><td>X071</td><td> </td><td>XMLSerialize: character string serialization and DOCUMENT option</td><td> </td></tr><tr><td>X072</td><td> </td><td>XMLSerialize: character string serialization</td><td> </td></tr><tr><td>X090</td><td> </td><td>XML document predicate</td><td> </td></tr><tr><td>X120</td><td> </td><td>XML parameters in SQL routines</td><td> </td></tr><tr><td>X121</td><td> </td><td>XML parameters in external routines</td><td> </td></tr><tr><td>X221</td><td> </td><td>XML passing mechanism BY VALUE</td><td> </td></tr><tr><td>X301</td><td> </td><td>XMLTable: derived column list option</td><td> </td></tr><tr><td>X302</td><td> </td><td>XMLTable: ordinality column option</td><td> </td></tr><tr><td>X303</td><td> </td><td>XMLTable: column default option</td><td> </td></tr><tr><td>X304</td><td> </td><td>XMLTable: passing a context item</td><td>must be XML DOCUMENT</td></tr><tr><td>X400</td><td> </td><td>Name and identifier mapping</td><td> </td></tr><tr><td>X410</td><td> </td><td>Alter column data type: XML type</td><td> </td></tr></tbody></table></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="features.html" title="Appendix D. SQL Conformance">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix D. SQL Conformance </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> D.2. Unsupported Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/features.html b/doc/src/sgml/html/features.html
new file mode 100644
index 0000000..e332e1d
--- /dev/null
+++ b/doc/src/sgml/html/features.html
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix D. SQL Conformance</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words" /><link rel="next" href="features-sql-standard.html" title="D.1. Supported Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix D. SQL Conformance</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="features-sql-standard.html" title="D.1. Supported Features">Next</a></td></tr></table><hr /></div><div class="appendix" id="FEATURES"><div class="titlepage"><div><div><h2 class="title">Appendix D. SQL Conformance</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="features-sql-standard.html">D.1. Supported Features</a></span></dt><dt><span class="sect1"><a href="unsupported-features-sql-standard.html">D.2. Unsupported Features</a></span></dt><dt><span class="sect1"><a href="xml-limits-conformance.html">D.3. XML Limits and Conformance to SQL/XML</a></span></dt><dd><dl><dt><span class="sect2"><a href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1">D.3.1. Queries Are Restricted to XPath 1.0</a></span></dt><dt><span class="sect2"><a href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL">D.3.2. Incidental Limits of the Implementation</a></span></dt></dl></dd></dl></div><p>
+ This section attempts to outline to what extent
+ <span class="productname">PostgreSQL</span> conforms to the current SQL
+ standard. The following information is not a full statement of
+ conformance, but it presents the main topics in as much detail as is
+ both reasonable and useful for users.
+ </p><p>
+ The formal name of the SQL standard is ISO/IEC 9075 <span class="quote">“<span class="quote">Database
+ Language SQL</span>”</span>. A revised version of the standard is released
+ from time to time; the most recent update appearing in 2016.
+ The 2016 version is referred to as ISO/IEC 9075:2016, or simply as SQL:2016.
+ The versions prior to that were SQL:2011, SQL:2008, SQL:2006, SQL:2003,
+ SQL:1999, and SQL-92. Each version
+ replaces the previous one, so claims of conformance to earlier
+ versions have no official merit.
+ <span class="productname">PostgreSQL</span> development aims for
+ conformance with the latest official version of the standard where
+ such conformance does not contradict traditional features or common
+ sense. Many of the features required by the SQL
+ standard are supported, though sometimes with slightly differing
+ syntax or function. Further moves towards conformance can be
+ expected over time.
+ </p><p>
+ <acronym class="acronym">SQL-92</acronym> defined three feature sets for
+ conformance: Entry, Intermediate, and Full. Most database
+ management systems claiming <acronym class="acronym">SQL</acronym> standard
+ conformance were conforming at only the Entry level, since the
+ entire set of features in the Intermediate and Full levels was
+ either too voluminous or in conflict with legacy behaviors.
+ </p><p>
+ Starting with <acronym class="acronym">SQL:1999</acronym>, the SQL standard defines
+ a large set of individual features rather than the ineffectively
+ broad three levels found in <acronym class="acronym">SQL-92</acronym>. A large
+ subset of these features represents the <span class="quote">“<span class="quote">Core</span>”</span>
+ features, which every conforming SQL implementation must supply.
+ The rest of the features are purely optional.
+ </p><p>
+ The standard versions beginning with <acronym class="acronym">SQL:2003</acronym>
+ are also split into a number
+ of parts. Each is known by a shorthand name. Note that these parts
+ are not consecutively numbered.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>ISO/IEC 9075-1 Framework (SQL/Framework)</p><a id="id-1.11.5.6.2.1.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-2 Foundation (SQL/Foundation)</p><a id="id-1.11.5.6.2.2.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-3 Call Level Interface (SQL/CLI)</p><a id="id-1.11.5.6.2.3.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-4 Persistent Stored Modules (SQL/PSM)</p><a id="id-1.11.5.6.2.4.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-9 Management of External Data (SQL/MED)</p><a id="id-1.11.5.6.2.5.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-10 Object Language Bindings (SQL/OLB)</p><a id="id-1.11.5.6.2.6.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-11 Information and Definition Schemas (SQL/Schemata)</p><a id="id-1.11.5.6.2.7.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-13 Routines and Types using the Java Language (SQL/JRT)</p><a id="id-1.11.5.6.2.8.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-14 XML-related specifications (SQL/XML)</p><a id="id-1.11.5.6.2.9.2" class="indexterm"></a></li><li class="listitem"><p>ISO/IEC 9075-15 Multi-dimensional arrays (SQL/MDA)</p><a id="id-1.11.5.6.2.10.2" class="indexterm"></a></li></ul></div><p>
+ </p><p>
+ The <span class="productname">PostgreSQL</span> core covers parts 1, 2, 9,
+ 11, and 14. Part 3 is covered by the ODBC driver, and part 13 is
+ covered by the PL/Java plug-in, but exact conformance is currently
+ not being verified for these components. There are currently no
+ implementations of parts 4, 10, and 15
+ for <span class="productname">PostgreSQL</span>.
+ </p><p>
+ PostgreSQL supports most of the major features of SQL:2016. Out of
+ 177 mandatory features required for full Core conformance,
+ PostgreSQL conforms to at least 170. In addition, there is a long
+ list of supported optional features. It might be worth noting that at
+ the time of writing, no current version of any database management
+ system claims full conformance to Core SQL:2016.
+ </p><p>
+ In the following two sections, we provide a list of those features
+ that <span class="productname">PostgreSQL</span> supports, followed by a
+ list of the features defined in <acronym class="acronym">SQL:2016</acronym> which
+ are not yet supported in <span class="productname">PostgreSQL</span>.
+ Both of these lists are approximate: There might be minor details that
+ are nonconforming for a feature that is listed as supported, and
+ large parts of an unsupported feature might in fact be implemented.
+ The main body of the documentation always contains the most accurate
+ information about what does and does not work.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Feature codes containing a hyphen are subfeatures. Therefore, if a
+ particular subfeature is not supported, the main feature is listed
+ as unsupported even if some other subfeatures are supported.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="features-sql-standard.html" title="D.1. Supported Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix C. <acronym class="acronym">SQL</acronym> Key Words </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> D.1. Supported Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/file-fdw.html b/doc/src/sgml/html/file-fdw.html
new file mode 100644
index 0000000..4e39a51
--- /dev/null
+++ b/doc/src/sgml/html/file-fdw.html
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.16. file_fdw</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="earthdistance.html" title="F.15. earthdistance" /><link rel="next" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.16. file_fdw</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="earthdistance.html" title="F.15. earthdistance">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch">Next</a></td></tr></table><hr /></div><div class="sect1" id="FILE-FDW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.16. file_fdw</h2></div></div></div><a id="id-1.11.7.25.2" class="indexterm"></a><p>
+ The <code class="filename">file_fdw</code> module provides the foreign-data wrapper
+ <code class="function">file_fdw</code>, which can be used to access data
+ 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 <code class="command">COPY FROM</code>;
+ see <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for details.
+ Access to data files is currently read-only.
+ </p><p>
+ A foreign table created using this wrapper can have the following options:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">filename</code></span></dt><dd><p>
+ Specifies the file to be read. Relative paths are relative to the
+ data directory.
+ Either <code class="literal">filename</code> or <code class="literal">program</code> must be
+ specified, but not both.
+ </p></dd><dt><span class="term"><code class="literal">program</code></span></dt><dd><p>
+ Specifies the command to be executed. The standard output of this
+ command will be read as though <code class="command">COPY FROM PROGRAM</code> were used.
+ Either <code class="literal">program</code> or <code class="literal">filename</code> must be
+ specified, but not both.
+ </p></dd><dt><span class="term"><code class="literal">format</code></span></dt><dd><p>
+ Specifies the data format,
+ the same as <code class="command">COPY</code>'s <code class="literal">FORMAT</code> option.
+ </p></dd><dt><span class="term"><code class="literal">header</code></span></dt><dd><p>
+ Specifies whether the data has a header line,
+ the same as <code class="command">COPY</code>'s <code class="literal">HEADER</code> option.
+ </p></dd><dt><span class="term"><code class="literal">delimiter</code></span></dt><dd><p>
+ Specifies the data delimiter character,
+ the same as <code class="command">COPY</code>'s <code class="literal">DELIMITER</code> option.
+ </p></dd><dt><span class="term"><code class="literal">quote</code></span></dt><dd><p>
+ Specifies the data quote character,
+ the same as <code class="command">COPY</code>'s <code class="literal">QUOTE</code> option.
+ </p></dd><dt><span class="term"><code class="literal">escape</code></span></dt><dd><p>
+ Specifies the data escape character,
+ the same as <code class="command">COPY</code>'s <code class="literal">ESCAPE</code> option.
+ </p></dd><dt><span class="term"><code class="literal">null</code></span></dt><dd><p>
+ Specifies the data null string,
+ the same as <code class="command">COPY</code>'s <code class="literal">NULL</code> option.
+ </p></dd><dt><span class="term"><code class="literal">encoding</code></span></dt><dd><p>
+ Specifies the data encoding,
+ the same as <code class="command">COPY</code>'s <code class="literal">ENCODING</code> option.
+ </p></dd></dl></div><p>
+ Note that while <code class="command">COPY</code> allows options such as <code class="literal">HEADER</code>
+ to be specified without a corresponding value, the foreign table option
+ syntax requires a value to be present in all cases. To activate
+ <code class="command">COPY</code> options typically written without a value, you can pass
+ the value TRUE, since all such options are Booleans.
+ </p><p>
+ A column of a foreign table created using this wrapper can have the
+ following options:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">force_not_null</code></span></dt><dd><p>
+ This is a Boolean option. If true, it specifies that values of the
+ column should not be matched against the null string (that is, the
+ table-level <code class="literal">null</code> option). This has the same effect
+ as listing the column in <code class="command">COPY</code>'s
+ <code class="literal">FORCE_NOT_NULL</code> option.
+ </p></dd><dt><span class="term"><code class="literal">force_null</code></span></dt><dd><p>
+ This is a Boolean option. If true, it specifies that values of the
+ column which match the null string are returned as <code class="literal">NULL</code>
+ even if the value is quoted. Without this option, only unquoted
+ values matching the null string are returned as <code class="literal">NULL</code>.
+ This has the same effect as listing the column in
+ <code class="command">COPY</code>'s <code class="literal">FORCE_NULL</code> option.
+ </p></dd></dl></div><p>
+ <code class="command">COPY</code>'s <code class="literal">FORCE_QUOTE</code> option is
+ currently not supported by <code class="literal">file_fdw</code>.
+ </p><p>
+ These options can only be specified for a foreign table or its columns, not
+ in the options of the <code class="literal">file_fdw</code> foreign-data wrapper, nor in the
+ options of a server or user mapping using the wrapper.
+ </p><p>
+ Changing table-level options requires being a superuser or having the privileges
+ of the role <code class="literal">pg_read_server_files</code> (to use a filename) or
+ the role <code class="literal">pg_execute_server_program</code> (to use a program),
+ for security reasons: only certain users should be able to control which file is
+ read or which program is run. In principle regular users could be allowed to
+ change the other options, but that's not supported at present.
+ </p><p>
+ When specifying the <code class="literal">program</code> option, keep in mind that the option
+ string is executed by the shell. If you need to pass any arguments to the
+ command that come from an untrusted source, you must be careful to strip or
+ escape any characters that might have special meaning to the shell.
+ For security reasons, it is best to use a fixed command string, or at least
+ avoid passing any user input in it.
+ </p><p>
+ For a foreign table using <code class="literal">file_fdw</code>, <code class="command">EXPLAIN</code> shows
+ the name of the file to be read or program to be run.
+ For a file, unless <code class="literal">COSTS OFF</code> is
+ specified, the file size (in bytes) is shown as well.
+ </p><div class="example" id="id-1.11.7.25.14"><p class="title"><strong>Example F.1. Create a Foreign Table for PostgreSQL CSV Logs</strong></p><div class="example-contents"><p>
+ One of the obvious uses for <code class="literal">file_fdw</code> is to make
+ the PostgreSQL activity log available as a table for querying. To
+ do this, first you must be <a class="link" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG" title="20.8.4. Using CSV-Format Log Output">logging to a CSV file,</a>
+ which here we
+ will call <code class="literal">pglog.csv</code>. First, install <code class="literal">file_fdw</code>
+ as an extension:
+ </p><pre class="programlisting">
+CREATE EXTENSION file_fdw;
+</pre><p>
+ Then create a foreign server:
+
+</p><pre class="programlisting">
+CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw;
+</pre><p>
+ </p><p>
+ Now you are ready to create the foreign data table. Using the
+ <code class="command">CREATE FOREIGN TABLE</code> command, you will need to define
+ the columns for the table, the CSV file name, and its format:
+
+</p><pre class="programlisting">
+CREATE FOREIGN TABLE pglog (
+ log_time timestamp(3) with time zone,
+ user_name text,
+ database_name text,
+ process_id integer,
+ connection_from text,
+ session_id text,
+ session_line_num bigint,
+ command_tag text,
+ session_start_time timestamp with time zone,
+ virtual_transaction_id text,
+ transaction_id bigint,
+ error_severity text,
+ sql_state_code text,
+ message text,
+ detail text,
+ hint text,
+ internal_query text,
+ internal_query_pos integer,
+ context text,
+ query text,
+ query_pos integer,
+ location text,
+ application_name text,
+ backend_type text,
+ leader_pid integer,
+ query_id bigint
+) SERVER pglog
+OPTIONS ( filename 'log/pglog.csv', format 'csv' );
+</pre><p>
+ </p><p>
+ That's it — now you can query your log directly. In production, of
+ course, you would need to define some way to deal with log rotation.
+ </p></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="earthdistance.html" title="F.15. earthdistance">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.15. earthdistance </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.17. fuzzystrmatch</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-admin.html b/doc/src/sgml/html/functions-admin.html
new file mode 100644
index 0000000..d24c26f
--- /dev/null
+++ b/doc/src/sgml/html/functions-admin.html
@@ -0,0 +1,1648 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.27. System Administration Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-info.html" title="9.26. System Information Functions and Operators" /><link rel="next" href="functions-trigger.html" title="9.28. Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.27. System Administration Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-info.html" title="9.26. System Information Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-trigger.html" title="9.28. Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-ADMIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.27. System Administration Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SET">9.27.1. Configuration Settings Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">9.27.2. Server Signaling Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">9.27.3. Backup Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">9.27.4. Recovery Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION">9.27.5. Snapshot Synchronization Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-REPLICATION">9.27.6. Replication Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">9.27.7. Database Object Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">9.27.8. Index Maintenance Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">9.27.9. Generic File Access Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">9.27.10. Advisory Lock Functions</a></span></dt></dl></div><p>
+ The functions described in this section are used to control and
+ monitor a <span class="productname">PostgreSQL</span> installation.
+ </p><div class="sect2" id="FUNCTIONS-ADMIN-SET"><div class="titlepage"><div><div><h3 class="title">9.27.1. Configuration Settings Functions</h3></div></div></div><a id="id-1.5.8.33.3.2" class="indexterm"></a><a id="id-1.5.8.33.3.3" class="indexterm"></a><a id="id-1.5.8.33.3.4" class="indexterm"></a><p>
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET-TABLE" title="Table 9.87. Configuration Settings Functions">Table 9.87</a> shows the functions
+ available to query and alter run-time configuration parameters.
+ </p><div class="table" id="FUNCTIONS-ADMIN-SET-TABLE"><p class="title"><strong>Table 9.87. Configuration Settings Functions</strong></p><div class="table-contents"><table class="table" summary="Configuration Settings Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.3.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">current_setting</code> ( <em class="parameter"><code>setting_name</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the current value of the
+ setting <em class="parameter"><code>setting_name</code></em>. If there is no such
+ setting, <code class="function">current_setting</code> throws an error
+ unless <em class="parameter"><code>missing_ok</code></em> is supplied and
+ is <code class="literal">true</code> (in which case NULL is returned).
+ This function corresponds to
+ the <acronym class="acronym">SQL</acronym> command <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a>.
+ </p>
+ <p>
+ <code class="literal">current_setting('datestyle')</code>
+ → <code class="returnvalue">ISO, MDY</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.3.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">set_config</code> (
+ <em class="parameter"><code>setting_name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>new_value</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>is_local</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Sets the parameter <em class="parameter"><code>setting_name</code></em>
+ to <em class="parameter"><code>new_value</code></em>, and returns that value.
+ If <em class="parameter"><code>is_local</code></em> is <code class="literal">true</code>, the new
+ value will only apply during the current transaction. If you want the
+ new value to apply for the rest of the current session,
+ use <code class="literal">false</code> instead. This function corresponds to
+ the SQL command <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>.
+ </p>
+ <p>
+ <code class="literal">set_config('log_statement_stats', 'off', false)</code>
+ → <code class="returnvalue">off</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-SIGNAL"><div class="titlepage"><div><div><h3 class="title">9.27.2. Server Signaling Functions</h3></div></div></div><a id="id-1.5.8.33.4.2" class="indexterm"></a><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL-TABLE" title="Table 9.88. Server Signaling Functions">Table 9.88</a> 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
+ <code class="command">GRANT</code>, with noted exceptions.
+ </p><p>
+ Each of these functions returns <code class="literal">true</code> if
+ the signal was successfully sent and <code class="literal">false</code>
+ if sending the signal failed.
+ </p><div class="table" id="FUNCTIONS-ADMIN-SIGNAL-TABLE"><p class="title"><strong>Table 9.88. Server Signaling Functions</strong></p><div class="table-contents"><table class="table" summary="Server Signaling Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.4.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_cancel_backend</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Cancels the current query of the session whose backend process has the
+ specified process ID. This is also allowed if the
+ calling role is a member of the role whose backend is being canceled or
+ the calling role has privileges of <code class="literal">pg_signal_backend</code>,
+ however only superusers can cancel superuser backends.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.4.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_log_backend_memory_contexts</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Requests to log the memory contexts of the backend with the
+ specified process ID. This function can send the request to
+ backends and auxiliary processes except logger. These memory contexts
+ will be logged at
+ <code class="literal">LOG</code> message level. They will appear in
+ the server log based on the log configuration set
+ (see <a class="xref" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Section 20.8</a> for more information),
+ but will not be sent to the client regardless of
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.4.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_reload_conf</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Causes all processes of the <span class="productname">PostgreSQL</span>
+ server to reload their configuration files. (This is initiated by
+ sending a <span class="systemitem">SIGHUP</span> signal to the postmaster
+ process, which in turn sends <span class="systemitem">SIGHUP</span> to each
+ of its children.) You can use the
+ <a class="link" href="view-pg-file-settings.html" title="54.7. pg_file_settings"><code class="structname">pg_file_settings</code></a>,
+ <a class="link" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a> and
+ <a class="link" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules"><code class="structname">pg_ident_file_mappings</code></a> views
+ to check the configuration files for possible errors, before reloading.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.4.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_rotate_logfile</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Signals the log-file manager to switch to a new output file
+ immediately. This works only when the built-in log collector is
+ running, since otherwise there is no log-file manager subprocess.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.4.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_terminate_backend</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code>, <em class="parameter"><code>timeout</code></em> <code class="type">bigint</code> <code class="literal">DEFAULT</code> <code class="literal">0</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Terminates the session whose backend process has the
+ specified process ID. This is also allowed if the calling role
+ is a member of the role whose backend is being terminated or the
+ calling role has privileges of <code class="literal">pg_signal_backend</code>,
+ however only superusers can terminate superuser backends.
+ </p>
+ <p>
+ If <em class="parameter"><code>timeout</code></em> is not specified or zero, this
+ function returns <code class="literal">true</code> whether the process actually
+ terminates or not, indicating only that the sending of the signal was
+ successful. If the <em class="parameter"><code>timeout</code></em> is specified (in
+ milliseconds) and greater than zero, the function waits until the
+ process is actually terminated or until the given time has passed. If
+ the process is terminated, the function
+ returns <code class="literal">true</code>. On timeout, a warning is emitted and
+ <code class="literal">false</code> is returned.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="function">pg_cancel_backend</code> and <code class="function">pg_terminate_backend</code>
+ send signals (<span class="systemitem">SIGINT</span> or <span class="systemitem">SIGTERM</span>
+ respectively) to backend processes identified by process ID.
+ The process ID of an active backend can be found from
+ the <code class="structfield">pid</code> column of the
+ <code class="structname">pg_stat_activity</code> view, or by listing the
+ <code class="command">postgres</code> processes on the server (using
+ <span class="application">ps</span> on Unix or the <span class="application">Task
+ Manager</span> on <span class="productname">Windows</span>).
+ The role of an active backend can be found from the
+ <code class="structfield">usename</code> column of the
+ <code class="structname">pg_stat_activity</code> view.
+ </p><p>
+ <code class="function">pg_log_backend_memory_contexts</code> can be used
+ to log the memory contexts of a backend process. For example:
+</p><pre class="programlisting">
+postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid());
+ pg_log_backend_memory_contexts
+--------------------------------
+ t
+(1 row)
+</pre><p>
+One message for each memory context will be logged. For example:
+</p><pre class="screen">
+LOG: logging memory contexts of PID 10377
+STATEMENT: SELECT pg_log_backend_memory_contexts(pg_backend_pid());
+LOG: level: 0; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used
+LOG: level: 1; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used
+LOG: level: 1; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used
+LOG: level: 1; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used
+LOG: level: 1; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used
+LOG: level: 1; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used
+LOG: level: 1; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used
+LOG: level: 1; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used
+...
+LOG: level: 1; ErrorContext: 8192 total in 1 blocks; 7928 free (3 chunks); 264 used
+LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 used
+</pre><p>
+ If there are more than 100 child contexts under the same parent, the first
+ 100 child contexts are logged, along with a summary of the remaining contexts.
+ Note that frequent calls to this function could incur significant overhead,
+ because it may generate a large number of log messages.
+ </p></div><div class="sect2" id="FUNCTIONS-ADMIN-BACKUP"><div class="titlepage"><div><div><h3 class="title">9.27.3. Backup Control Functions</h3></div></div></div><a id="id-1.5.8.33.5.2" class="indexterm"></a><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.89. Backup Control Functions">Table 9.89</a> assist in making on-line backups.
+ These functions cannot be executed during recovery (except
+ <code class="function">pg_backup_start</code>,
+ <code class="function">pg_backup_stop</code>,
+ and <code class="function">pg_wal_lsn_diff</code>).
+ </p><p>
+ For details about proper usage of these functions, see
+ <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>.
+ </p><div class="table" id="FUNCTIONS-ADMIN-BACKUP-TABLE"><p class="title"><strong>Table 9.89. Backup Control Functions</strong></p><div class="table-contents"><table class="table" summary="Backup Control Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_create_restore_point</code> ( <em class="parameter"><code>name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Creates a named marker record in the write-ahead log that can later be
+ used as a recovery target, and returns the corresponding write-ahead
+ log location. The given name can then be used with
+ <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-NAME">recovery_target_name</a> 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.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_wal_flush_lsn</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the current write-ahead log flush location (see notes below).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_wal_insert_lsn</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the current write-ahead log insert location (see notes below).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_wal_lsn</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the current write-ahead log write location (see notes below).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_backup_start</code> (
+ <em class="parameter"><code>label</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>fast</code></em> <code class="type">boolean</code>
+ </span>] )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Prepares the server to begin an on-line backup. The only required
+ parameter is an arbitrary user-defined label for the backup.
+ (Typically this would be the name under which the backup dump file
+ will be stored.)
+ If the optional second parameter is given as <code class="literal">true</code>,
+ it specifies executing <code class="function">pg_backup_start</code> as quickly
+ as possible. This forces an immediate checkpoint which will cause a
+ spike in I/O operations, slowing any concurrently executing queries.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_backup_stop</code> (
+ [<span class="optional"><em class="parameter"><code>wait_for_archive</code></em> <code class="type">boolean</code>
+ </span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
+ <em class="parameter"><code>labelfile</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>spcmapfile</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Finishes performing an on-line backup. The desired contents of the
+ backup label file and the tablespace map file are returned as part of
+ the result of the function and must be written to files in the
+ backup area. These files must not be written to the live data directory
+ (doing so will cause PostgreSQL to fail to restart in the event of a
+ crash).
+ </p>
+ <p>
+ There is an optional parameter of type <code class="type">boolean</code>.
+ If false, the function will return immediately after the backup is
+ completed, without waiting for WAL to be archived. This behavior is
+ only useful with backup software that independently monitors WAL
+ archiving. Otherwise, WAL required to make the backup consistent might
+ be missing and make the backup useless. By default or when this
+ parameter is true, <code class="function">pg_backup_stop</code> will wait for
+ WAL to be archived when archiving is enabled. (On a standby, this
+ means that it will wait only when <code class="varname">archive_mode</code> =
+ <code class="literal">always</code>. If write activity on the primary is low,
+ it may be useful to run <code class="function">pg_switch_wal</code> on the
+ primary in order to trigger an immediate segment switch.)
+ </p>
+ <p>
+ When executed on a primary, this function also creates a backup
+ history file in the write-ahead log archive area. The history file
+ includes the label given to <code class="function">pg_backup_start</code>, the
+ starting and ending write-ahead log locations for the backup, and the
+ starting and ending times of the backup. After recording the ending
+ location, the current write-ahead log insertion point is automatically
+ advanced to the next write-ahead log file, so that the ending
+ write-ahead log file can be archived immediately to complete the
+ backup.
+ </p>
+ <p>
+ The result of the function is a single record.
+ The <em class="parameter"><code>lsn</code></em> column holds the backup's ending
+ write-ahead log location (which again can be ignored). The second
+ column returns the contents of the backup label file, and the third
+ column returns the contents of the tablespace map file. These must be
+ stored as part of the backup and are required as part of the restore
+ process.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_switch_wal</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Forces the server to switch to a new write-ahead log file, which
+ allows the current file to be archived (assuming you are using
+ continuous archiving). The result is the ending write-ahead log
+ location plus 1 within the just-completed write-ahead log file. If
+ there has been no write-ahead log activity since the last write-ahead
+ log switch, <code class="function">pg_switch_wal</code> does nothing and
+ returns the start location of the write-ahead log file currently in
+ use.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_walfile_name</code> ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts a write-ahead log location to the name of the WAL file
+ holding that location.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_walfile_name_offset</code> ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>file_name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>file_offset</code></em> <code class="type">integer</code> )
+ </p>
+ <p>
+ Converts a write-ahead log location to a WAL file name and byte offset
+ within that file.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.5.5.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_wal_lsn_diff</code> ( <em class="parameter"><code>lsn1</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>lsn2</code></em> <code class="type">pg_lsn</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Calculates the difference in bytes (<em class="parameter"><code>lsn1</code></em> - <em class="parameter"><code>lsn2</code></em>) between two write-ahead log
+ locations. This can be used
+ with <code class="structname">pg_stat_replication</code> or some of the
+ functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.89. Backup Control Functions">Table 9.89</a> to
+ get the replication lag.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="function">pg_current_wal_lsn</code> displays the current write-ahead
+ log write location in the same format used by the above functions.
+ Similarly, <code class="function">pg_current_wal_insert_lsn</code> displays the
+ current write-ahead log insertion location
+ and <code class="function">pg_current_wal_flush_lsn</code> displays the current
+ write-ahead log flush location. The insertion location is
+ the <span class="quote">“<span class="quote">logical</span>”</span> end of the write-ahead log at any instant,
+ while the write location is the end of what has actually been written out
+ from the server's internal buffers, and the flush location is the last
+ location known to be written to durable storage. The write location is the
+ end of what can be examined from outside the server, and is usually what
+ you want if you are interested in archiving partially-complete write-ahead
+ log files. The insertion and flush locations are made available primarily
+ for server debugging purposes. These are all read-only operations and do
+ not require superuser permissions.
+ </p><p>
+ You can use <code class="function">pg_walfile_name_offset</code> to extract the
+ corresponding write-ahead log file name and byte offset from
+ a <code class="type">pg_lsn</code> value. For example:
+</p><pre class="programlisting">
+postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
+ file_name | file_offset
+--------------------------+-------------
+ 00000001000000000000000D | 4039624
+(1 row)
+</pre><p>
+ Similarly, <code class="function">pg_walfile_name</code> extracts just the write-ahead log file name.
+ When the given write-ahead log location is exactly at a write-ahead log file boundary, both
+ these functions return the name of the preceding write-ahead log file.
+ This is usually the desired behavior for managing write-ahead log archiving
+ behavior, since the preceding file is the last one that currently
+ needs to be archived.
+ </p></div><div class="sect2" id="FUNCTIONS-RECOVERY-CONTROL"><div class="titlepage"><div><div><h3 class="title">9.27.4. Recovery Control Functions</h3></div></div></div><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-INFO-TABLE" title="Table 9.90. Recovery Information Functions">Table 9.90</a> provide information
+ about the current status of a standby server.
+ These functions may be executed both during recovery and in normal running.
+ </p><div class="table" id="FUNCTIONS-RECOVERY-INFO-TABLE"><p class="title"><strong>Table 9.90. Recovery Information Functions</strong></p><div class="table-contents"><table class="table" summary="Recovery Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_is_in_recovery</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if recovery is still in progress.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_last_wal_receive_lsn</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the last write-ahead log location that has been received and
+ synced to disk by streaming replication. While streaming replication
+ is in progress this will increase monotonically. If recovery has
+ completed then this will remain static at the location of the last WAL
+ record received and synced to disk during recovery. If streaming
+ replication is disabled, or if it has not yet started, the function
+ returns <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_last_wal_replay_lsn</code> ()
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the last write-ahead log location that has been replayed
+ during recovery. If recovery is still in progress this will increase
+ monotonically. If recovery has completed then this will remain
+ static at the location of the last WAL record applied during recovery.
+ When the server has been started normally without recovery, the
+ function returns <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_last_xact_replay_timestamp</code> ()
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time stamp of the last transaction replayed during
+ recovery. This is the time at which the commit or abort WAL record
+ for that transaction was generated on the primary. If no transactions
+ have been replayed during recovery, the function
+ returns <code class="literal">NULL</code>. Otherwise, if recovery is still in
+ progress this will increase monotonically. If recovery has completed
+ then this will remain static at the time of the last transaction
+ applied during recovery. When the server has been started normally
+ without recovery, the function returns <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.3.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_wal_resource_managers</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>rm_id</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>rm_name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>rm_builtin</code></em> <code class="type">boolean</code> )
+ </p>
+ <p>
+ Returns the currently-loaded WAL resource managers in the system. The
+ column <em class="parameter"><code>rm_builtin</code></em> indicates whether it's a
+ built-in resource manager, or a custom resource manager loaded by an
+ extension.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE" title="Table 9.91. Recovery Control Functions">Table 9.91</a> control the progress of recovery.
+ These functions may be executed only during recovery.
+ </p><div class="table" id="FUNCTIONS-RECOVERY-CONTROL-TABLE"><p class="title"><strong>Table 9.91. Recovery Control Functions</strong></p><div class="table-contents"><table class="table" summary="Recovery Control Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_is_wal_replay_paused</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if recovery pause is requested.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_wal_replay_pause_state</code> ()
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns recovery pause state. The return values are <code class="literal">
+ not paused</code> if pause is not requested, <code class="literal">
+ pause requested</code> if pause is requested but recovery is
+ not yet paused, and <code class="literal">paused</code> if the recovery is
+ actually paused.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_promote</code> ( <em class="parameter"><code>wait</code></em> <code class="type">boolean</code> <code class="literal">DEFAULT</code> <code class="literal">true</code>, <em class="parameter"><code>wait_seconds</code></em> <code class="type">integer</code> <code class="literal">DEFAULT</code> <code class="literal">60</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Promotes a standby server to primary status.
+ With <em class="parameter"><code>wait</code></em> set to <code class="literal">true</code> (the
+ default), the function waits until promotion is completed
+ or <em class="parameter"><code>wait_seconds</code></em> seconds have passed, and
+ returns <code class="literal">true</code> if promotion is successful
+ and <code class="literal">false</code> otherwise.
+ If <em class="parameter"><code>wait</code></em> is set to <code class="literal">false</code>, the
+ function returns <code class="literal">true</code> immediately after sending a
+ <code class="literal">SIGUSR1</code> signal to the postmaster to trigger
+ promotion.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_wal_replay_pause</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Request to pause recovery. A request doesn't mean that recovery stops
+ right away. If you want a guarantee that recovery is actually paused,
+ you need to check for the recovery pause state returned by
+ <code class="function">pg_get_wal_replay_pause_state()</code>. Note that
+ <code class="function">pg_is_wal_replay_paused()</code> returns whether a request
+ is made. While recovery is paused, no further database changes are applied.
+ If hot standby is active, all new queries will see the same consistent
+ snapshot of the database, and no further query conflicts will be generated
+ until recovery is resumed.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.6.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_wal_replay_resume</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Restarts recovery if it was paused.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="function">pg_wal_replay_pause</code> and
+ <code class="function">pg_wal_replay_resume</code> cannot be executed while
+ a promotion is ongoing. If a promotion is triggered while recovery
+ is paused, the paused state ends and promotion continues.
+ </p><p>
+ If streaming replication is disabled, the paused state may continue
+ indefinitely without a problem. If streaming replication is in
+ progress then WAL records will continue to be received, which will
+ eventually fill available disk space, depending upon the duration of
+ the pause, the rate of WAL generation and available disk space.
+ </p></div><div class="sect2" id="FUNCTIONS-SNAPSHOT-SYNCHRONIZATION"><div class="titlepage"><div><div><h3 class="title">9.27.5. Snapshot Synchronization Functions</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> allows database sessions to synchronize their
+ snapshots. A <em class="firstterm">snapshot</em> determines which data is visible to the
+ transaction that is using the snapshot. Synchronized snapshots are
+ necessary when two or more sessions need to see identical content in the
+ database. If two sessions just start their transactions independently,
+ there is always a possibility that some third transaction commits
+ between the executions of the two <code class="command">START TRANSACTION</code> commands,
+ so that one session sees the effects of that transaction and the other
+ does not.
+ </p><p>
+ To solve this problem, <span class="productname">PostgreSQL</span> allows a transaction to
+ <em class="firstterm">export</em> the snapshot it is using. As long as the exporting
+ transaction remains open, other transactions can <em class="firstterm">import</em> its
+ snapshot, and thereby be guaranteed that they see exactly the same view
+ of the database that the first transaction sees. But note that any
+ database changes made by any one of these transactions remain invisible
+ to the other transactions, as is usual for changes made by uncommitted
+ transactions. So the transactions are synchronized with respect to
+ pre-existing data, but act normally for changes they make themselves.
+ </p><p>
+ Snapshots are exported with the <code class="function">pg_export_snapshot</code> function,
+ shown in <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE" title="Table 9.92. Snapshot Synchronization Functions">Table 9.92</a>, and
+ imported with the <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> command.
+ </p><div class="table" id="FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE"><p class="title"><strong>Table 9.92. Snapshot Synchronization Functions</strong></p><div class="table-contents"><table class="table" summary="Snapshot Synchronization Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.7.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_export_snapshot</code> ()
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Saves the transaction's current snapshot and returns
+ a <code class="type">text</code> string identifying the snapshot. This string must
+ be passed (outside the database) to clients that want to import the
+ snapshot. The snapshot is available for import only until the end of
+ the transaction that exported it.
+ </p>
+ <p>
+ A transaction can export more than one snapshot, if needed. Note that
+ doing so is only useful in <code class="literal">READ COMMITTED</code>
+ transactions, since in <code class="literal">REPEATABLE READ</code> and higher
+ isolation levels, transactions use the same snapshot throughout their
+ lifetime. Once a transaction has exported any snapshots, it cannot be
+ prepared with <a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-REPLICATION"><div class="titlepage"><div><div><h3 class="title">9.27.6. Replication Management Functions</h3></div></div></div><p>
+ The functions shown
+ in <a class="xref" href="functions-admin.html#FUNCTIONS-REPLICATION-TABLE" title="Table 9.93. Replication Management Functions">Table 9.93</a> are for
+ controlling and interacting with replication features.
+ See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>,
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>, and
+ <a class="xref" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Chapter 50</a>
+ for information about the underlying features.
+ Use of functions for replication origin is only allowed to the
+ superuser by default, but may be allowed to other users by using the
+ <code class="literal">GRANT</code> command.
+ Use of functions for replication slots is restricted to superusers
+ and users having <code class="literal">REPLICATION</code> privilege.
+ </p><p>
+ Many of these functions have equivalent commands in the replication
+ protocol; see <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>.
+ </p><p>
+ The functions described in
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP" title="9.27.3. Backup Control Functions">Section 9.27.3</a>,
+ <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL" title="9.27.4. Recovery Control Functions">Section 9.27.4</a>, and
+ <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.27.5. Snapshot Synchronization Functions">Section 9.27.5</a>
+ are also relevant for replication.
+ </p><div class="table" id="FUNCTIONS-REPLICATION-TABLE"><p class="title"><strong>Table 9.93. Replication Management Functions</strong></p><div class="table-contents"><table class="table" summary="Replication Management Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_create_physical_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>immediately_reserve</code></em> <code class="type">boolean</code>, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ </p>
+ <p>
+ Creates a new physical replication slot named
+ <em class="parameter"><code>slot_name</code></em>. The optional second parameter,
+ when <code class="literal">true</code>, specifies that the <acronym class="acronym">LSN</acronym> for this
+ replication slot be reserved immediately; otherwise
+ the <acronym class="acronym">LSN</acronym> 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 <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>. The optional third
+ parameter, <em class="parameter"><code>temporary</code></em>, when set to true, specifies that
+ the slot should not be permanently stored to disk and is only meant
+ for use by the current session. Temporary slots are also
+ released upon any error. This function corresponds
+ to the replication protocol command <code class="literal">CREATE_REPLICATION_SLOT
+ ... PHYSICAL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_drop_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Drops the physical or logical replication slot
+ named <em class="parameter"><code>slot_name</code></em>. Same as replication protocol
+ command <code class="literal">DROP_REPLICATION_SLOT</code>. For logical slots, this must
+ be called while connected to the same database the slot was created on.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_create_logical_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>plugin</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code>, <em class="parameter"><code>twophase</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ </p>
+ <p>
+ Creates a new logical (decoding) replication slot named
+ <em class="parameter"><code>slot_name</code></em> using the output plugin
+ <em class="parameter"><code>plugin</code></em>. The optional third
+ parameter, <em class="parameter"><code>temporary</code></em>, when set to true, specifies that
+ the slot should not be permanently stored to disk and is only meant
+ for use by the current session. Temporary slots are also
+ released upon any error. The optional fourth parameter,
+ <em class="parameter"><code>twophase</code></em>, when set to true, specifies
+ that the decoding of prepared transactions is enabled for this
+ slot. A call to this function has the same effect as the replication
+ protocol command <code class="literal">CREATE_REPLICATION_SLOT ... LOGICAL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_copy_physical_replication_slot</code> ( <em class="parameter"><code>src_slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>dst_slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ </p>
+ <p>
+ Copies an existing physical replication slot named <em class="parameter"><code>src_slot_name</code></em>
+ to a physical replication slot named <em class="parameter"><code>dst_slot_name</code></em>.
+ The copied physical slot starts to reserve WAL from the same <acronym class="acronym">LSN</acronym> as the
+ source slot.
+ <em class="parameter"><code>temporary</code></em> is optional. If <em class="parameter"><code>temporary</code></em>
+ is omitted, the same value as the source slot is used.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_copy_logical_replication_slot</code> ( <em class="parameter"><code>src_slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>dst_slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> [<span class="optional">, <em class="parameter"><code>plugin</code></em> <code class="type">name</code> </span>]</span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ </p>
+ <p>
+ Copies an existing logical replication slot
+ named <em class="parameter"><code>src_slot_name</code></em> to a logical replication
+ slot named <em class="parameter"><code>dst_slot_name</code></em>, optionally changing
+ the output plugin and persistence. The copied logical slot starts
+ from the same <acronym class="acronym">LSN</acronym> as the source logical slot. Both
+ <em class="parameter"><code>temporary</code></em> and <em class="parameter"><code>plugin</code></em> are
+ optional; if they are omitted, the values of the source slot are used.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_logical_slot_get_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
+ <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
+ <em class="parameter"><code>data</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns changes in the slot <em class="parameter"><code>slot_name</code></em>, starting
+ from the point from which changes have been consumed last. If
+ <em class="parameter"><code>upto_lsn</code></em>
+ and <em class="parameter"><code>upto_nchanges</code></em> are NULL,
+ logical decoding will continue until end of WAL. If
+ <em class="parameter"><code>upto_lsn</code></em> is non-NULL, decoding will include only
+ those transactions which commit prior to the specified LSN. If
+ <em class="parameter"><code>upto_nchanges</code></em> is non-NULL, decoding will
+ stop when the number of rows produced by decoding exceeds
+ the specified value. Note, however, that the actual number of
+ rows returned may be larger, since this limit is only checked after
+ adding the rows produced when decoding each new transaction commit.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_logical_slot_peek_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
+ <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
+ <em class="parameter"><code>data</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Behaves just like
+ the <code class="function">pg_logical_slot_get_changes()</code> function,
+ except that changes are not consumed; that is, they will be returned
+ again on future calls.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_logical_slot_get_binary_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
+ <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
+ <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
+ </p>
+ <p>
+ Behaves just like
+ the <code class="function">pg_logical_slot_get_changes()</code> function,
+ except that changes are returned as <code class="type">bytea</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_logical_slot_peek_binary_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
+ <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
+ <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
+ </p>
+ <p>
+ Behaves just like
+ the <code class="function">pg_logical_slot_peek_changes()</code> function,
+ except that changes are returned as <code class="type">bytea</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_slot_advance</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>end_lsn</code></em> <code class="type">pg_lsn</code> )
+ </p>
+ <p>
+ Advances the current confirmed position of a replication slot named
+ <em class="parameter"><code>slot_name</code></em>. The slot will not be moved backwards,
+ and it will not be moved beyond the current insert location. Returns
+ the name of the slot and the actual position that it was advanced to.
+ The updated slot position information is written out at the next
+ checkpoint if any advancing is done. So in the event of a crash, the
+ slot may return to an earlier position.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-CREATE" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_create</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Creates a replication origin with the given external
+ name, and returns the internal ID assigned to it.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-DROP" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_drop</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Deletes a previously-created replication origin, including any
+ associated replay progress.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_oid</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Looks up a replication origin by name and returns the internal ID. If
+ no such replication origin is found, <code class="literal">NULL</code> is
+ returned.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-SESSION-SETUP" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_session_setup</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Marks the current session as replaying from the given
+ origin, allowing replay progress to be tracked.
+ Can only be used if no origin is currently selected.
+ Use <code class="function">pg_replication_origin_session_reset</code> to undo.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_session_reset</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Cancels the effects
+ of <code class="function">pg_replication_origin_session_setup()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_session_is_setup</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if a replication origin has been selected in the
+ current session.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-SESSION-PROGRESS" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_session_progress</code> ( <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the replay location for the replication origin selected in
+ the current session. The parameter <em class="parameter"><code>flush</code></em>
+ determines whether the corresponding local transaction will be
+ guaranteed to have been flushed to disk or not.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-XACT-SETUP" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_xact_setup</code> ( <em class="parameter"><code>origin_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>origin_timestamp</code></em> <code class="type">timestamp with time zone</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Marks the current transaction as replaying a transaction that has
+ committed at the given <acronym class="acronym">LSN</acronym> and timestamp. Can
+ only be called when a replication origin has been selected
+ using <code class="function">pg_replication_origin_session_setup</code>.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-XACT-RESET" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_xact_reset</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Cancels the effects of
+ <code class="function">pg_replication_origin_xact_setup()</code>.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-ADVANCE" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.20.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_advance</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code>, <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Sets replication progress for the given node to the given
+ location. This is primarily useful for setting up the initial
+ location, or setting a new location after configuration changes and
+ similar. Be aware that careless use of this function can lead to
+ inconsistently replicated data.
+ </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-PROGRESS" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">pg_replication_origin_progress</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code>, <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Returns the replay location for the given replication origin. The
+ parameter <em class="parameter"><code>flush</code></em> determines whether the
+ corresponding local transaction will be guaranteed to have been
+ flushed to disk or not.
+ </p></td></tr><tr><td id="PG-LOGICAL-EMIT-MESSAGE" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.8.5.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">pg_logical_emit_message</code> ( <em class="parameter"><code>transactional</code></em> <code class="type">boolean</code>, <em class="parameter"><code>prefix</code></em> <code class="type">text</code>, <em class="parameter"><code>content</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_logical_emit_message</code> ( <em class="parameter"><code>transactional</code></em> <code class="type">boolean</code>, <em class="parameter"><code>prefix</code></em> <code class="type">text</code>, <em class="parameter"><code>content</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">pg_lsn</code>
+ </p>
+ <p>
+ Emits a logical decoding message. This can be used to pass generic
+ messages to logical decoding plugins through
+ WAL. The <em class="parameter"><code>transactional</code></em> parameter specifies if
+ the message should be part of the current transaction, or if it should
+ be written immediately and decoded as soon as the logical decoder
+ reads the record. The <em class="parameter"><code>prefix</code></em> parameter is a
+ textual prefix that can be used by logical decoding plugins to easily
+ recognize messages that are interesting for them.
+ The <em class="parameter"><code>content</code></em> parameter is the content of the
+ message, given either in text or binary form.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-DBOBJECT"><div class="titlepage"><div><div><h3 class="title">9.27.7. Database Object Management Functions</h3></div></div></div><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-DBSIZE" title="Table 9.94. Database Object Size Functions">Table 9.94</a> calculate
+ the disk space usage of database objects, or assist in presentation
+ or understanding of usage results. <code class="literal">bigint</code> results
+ are measured in bytes. If an OID that does
+ not represent an existing object is passed to one of these
+ functions, <code class="literal">NULL</code> is returned.
+ </p><div class="table" id="FUNCTIONS-ADMIN-DBSIZE"><p class="title"><strong>Table 9.94. Database Object Size Functions</strong></p><div class="table-contents"><table class="table" summary="Database Object Size Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_column_size</code> ( <code class="type">"any"</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Shows the number of bytes used to store any individual data value. If
+ applied directly to a table column value, this reflects any
+ compression that was done.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_column_compression</code> ( <code class="type">"any"</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Shows the compression algorithm that was used to compress
+ an individual variable-length value. Returns <code class="literal">NULL</code>
+ if the value is not compressed.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_database_size</code> ( <code class="type">name</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_database_size</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the total disk space used by the database with the specified
+ name or OID. To use this function, you must
+ have <code class="literal">CONNECT</code> privilege on the specified database
+ (which is granted by default) or have privileges of
+ the <code class="literal">pg_read_all_stats</code> role.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_indexes_size</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the total disk space used by indexes attached to the
+ specified table.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_relation_size</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> [<span class="optional">, <em class="parameter"><code>fork</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the disk space used by one <span class="quote">“<span class="quote">fork</span>”</span> of the
+ specified relation. (Note that for most purposes it is more
+ convenient to use the higher-level
+ functions <code class="function">pg_total_relation_size</code>
+ or <code class="function">pg_table_size</code>, which sum the sizes of all
+ forks.) With one argument, this returns the size of the main data
+ fork of the relation. The second argument can be provided to specify
+ which fork to examine:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">main</code> returns the size of the main
+ data fork of the relation.
+ </p></li><li class="listitem"><p>
+ <code class="literal">fsm</code> returns the size of the Free Space Map
+ (see <a class="xref" href="storage-fsm.html" title="73.3. Free Space Map">Section 73.3</a>) associated with the relation.
+ </p></li><li class="listitem"><p>
+ <code class="literal">vm</code> returns the size of the Visibility Map
+ (see <a class="xref" href="storage-vm.html" title="73.4. Visibility Map">Section 73.4</a>) associated with the relation.
+ </p></li><li class="listitem"><p>
+ <code class="literal">init</code> returns the size of the initialization
+ fork, if any, associated with the relation.
+ </p></li></ul></div><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_size_bytes</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Converts a size in human-readable format (as returned
+ by <code class="function">pg_size_pretty</code>) into bytes.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_size_pretty</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_size_pretty</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts a size in bytes into a more easily human-readable format with
+ size units (bytes, kB, MB, GB, TB, or PB as appropriate). Note that the
+ units are powers of 2 rather than powers of 10, so 1kB is 1024 bytes,
+ 1MB is 1024<sup>2</sup> = 1048576 bytes, and so on.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_table_size</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the disk space used by the specified table, excluding indexes
+ (but including its TOAST table if any, free space map, and visibility
+ map).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_tablespace_size</code> ( <code class="type">name</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_tablespace_size</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the total disk space used in the tablespace with the
+ specified name or OID. To use this function, you must
+ have <code class="literal">CREATE</code> privilege on the specified tablespace
+ or have privileges of the <code class="literal">pg_read_all_stats</code> role,
+ unless it is the default tablespace for the current database.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.3.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_total_relation_size</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the total disk space used by the specified table, including
+ all indexes and <acronym class="acronym">TOAST</acronym> data. The result is
+ equivalent to <code class="function">pg_table_size</code>
+ <code class="literal">+</code> <code class="function">pg_indexes_size</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The functions above that operate on tables or indexes accept a
+ <code class="type">regclass</code> argument, which is simply the OID of the table or index
+ in the <code class="structname">pg_class</code> system catalog. You do not have to look up
+ the OID by hand, however, since the <code class="type">regclass</code> data type's input
+ converter will do the work for you. See <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>
+ for details.
+ </p><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-DBLOCATION" title="Table 9.95. Database Object Location Functions">Table 9.95</a> assist
+ in identifying the specific disk files associated with database objects.
+ </p><div class="table" id="FUNCTIONS-ADMIN-DBLOCATION"><p class="title"><strong>Table 9.95. Database Object Location Functions</strong></p><div class="table-contents"><table class="table" summary="Database Object Location Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_relation_filenode</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Returns the <span class="quote">“<span class="quote">filenode</span>”</span> number currently assigned to the
+ specified relation. The filenode is the base component of the file
+ name(s) used for the relation (see
+ <a class="xref" href="storage-file-layout.html" title="73.1. Database File Layout">Section 73.1</a> for more information).
+ For most relations the result is the same as
+ <code class="structname">pg_class</code>.<code class="structfield">relfilenode</code>,
+ but for certain system catalogs <code class="structfield">relfilenode</code>
+ is zero and this function must be used to get the correct value. The
+ function returns NULL if passed a relation that does not have storage,
+ such as a view.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_relation_filepath</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the entire file path name (relative to the database cluster's
+ data directory, <code class="varname">PGDATA</code>) of the relation.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_filenode_relation</code> ( <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code>, <em class="parameter"><code>filenode</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">regclass</code>
+ </p>
+ <p>
+ Returns a relation's OID given the tablespace OID and filenode it is
+ stored under. This is essentially the inverse mapping of
+ <code class="function">pg_relation_filepath</code>. For a relation in the
+ database's default tablespace, the tablespace can be specified as zero.
+ Returns <code class="literal">NULL</code> if no relation in the current database
+ is associated with the given values.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-COLLATION" title="Table 9.96. Collation Management Functions">Table 9.96</a> lists functions used to manage
+ collations.
+ </p><div class="table" id="FUNCTIONS-ADMIN-COLLATION"><p class="title"><strong>Table 9.96. Collation Management Functions</strong></p><div class="table-contents"><table class="table" summary="Collation Management Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.8.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_collation_actual_version</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the actual version of the collation object as it is currently
+ installed in the operating system. If this is different from the
+ value in
+ <code class="structname">pg_collation</code>.<code class="structfield">collversion</code>,
+ then objects depending on the collation might need to be rebuilt. See
+ also <a class="xref" href="sql-altercollation.html" title="ALTER COLLATION"><span class="refentrytitle">ALTER COLLATION</span></a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.8.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_database_collation_actual_version</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the actual version of the database's collation as it is currently
+ installed in the operating system. If this is different from the
+ value in
+ <code class="structname">pg_database</code>.<code class="structfield">datcollversion</code>,
+ then objects depending on the collation might need to be rebuilt. See
+ also <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.8.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_import_system_collations</code> ( <em class="parameter"><code>schema</code></em> <code class="type">regnamespace</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Adds collations to the system
+ catalog <code class="structname">pg_collation</code> based on all the locales
+ it finds in the operating system. This is
+ what <code class="command">initdb</code> uses; see
+ <a class="xref" href="collation.html#COLLATION-MANAGING" title="24.2.2. Managing Collations">Section 24.2.2</a> 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 <code class="structname">pg_collation</code> will be skipped. (But
+ collation objects based on locales that are no longer present in the
+ operating system are not removed by this function.)
+ The <em class="parameter"><code>schema</code></em> parameter would typically
+ be <code class="literal">pg_catalog</code>, but that is not a requirement; the
+ collations could be installed into some other schema as well. The
+ function returns the number of new collation objects it created.
+ Use of this function is restricted to superusers.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-admin.html#FUNCTIONS-INFO-PARTITION" title="Table 9.97. Partitioning Information Functions">Table 9.97</a> lists functions that provide
+ information about the structure of partitioned tables.
+ </p><div class="table" id="FUNCTIONS-INFO-PARTITION"><p class="title"><strong>Table 9.97. Partitioning Information Functions</strong></p><div class="table-contents"><table class="table" summary="Partitioning Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.10.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_partition_tree</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>relid</code></em> <code class="type">regclass</code>,
+ <em class="parameter"><code>parentrelid</code></em> <code class="type">regclass</code>,
+ <em class="parameter"><code>isleaf</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>level</code></em> <code class="type">integer</code> )
+ </p>
+ <p>
+ Lists the tables or indexes in the partition tree of the
+ given partitioned table or partitioned index, with one row for each
+ partition. Information provided includes the OID of the partition,
+ the OID of its immediate parent, a boolean value telling if the
+ partition is a leaf, and an integer telling its level in the hierarchy.
+ The level value is 0 for the input table or index, 1 for its
+ immediate child partitions, 2 for their partitions, and so on.
+ Returns no rows if the relation does not exist or is not a partition
+ or partitioned table.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.10.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_partition_ancestors</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">setof regclass</code>
+ </p>
+ <p>
+ Lists the ancestor relations of the given partition,
+ including the relation itself. Returns no rows if the relation
+ does not exist or is not a partition or partitioned table.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.9.10.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_partition_root</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">regclass</code>
+ </p>
+ <p>
+ Returns the top-most parent of the partition tree to which the given
+ relation belongs. Returns <code class="literal">NULL</code> if the relation
+ does not exist or is not a partition or partitioned table.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For example, to check the total size of the data contained in a
+ partitioned table <code class="structname">measurement</code>, one could use the
+ following query:
+</p><pre class="programlisting">
+SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
+ FROM pg_partition_tree('measurement');
+</pre><p>
+ </p></div><div class="sect2" id="FUNCTIONS-ADMIN-INDEX"><div class="titlepage"><div><div><h3 class="title">9.27.8. Index Maintenance Functions</h3></div></div></div><p>
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX-TABLE" title="Table 9.98. Index Maintenance Functions">Table 9.98</a> shows the functions
+ available for index maintenance tasks. (Note that these maintenance
+ tasks are normally done automatically by autovacuum; use of these
+ functions is only required in special cases.)
+ These functions cannot be executed during recovery.
+ Use of these functions is restricted to superusers and the owner
+ of the given index.
+ </p><div class="table" id="FUNCTIONS-ADMIN-INDEX-TABLE"><p class="title"><strong>Table 9.98. Index Maintenance Functions</strong></p><div class="table-contents"><table class="table" summary="Index Maintenance Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.10.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">brin_summarize_new_values</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Scans the specified BRIN index to find page ranges in the base table
+ that are not currently summarized by the index; for any such range it
+ creates a new summary index tuple by scanning those table pages.
+ Returns the number of new page range summaries that were inserted
+ into the index.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.10.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">brin_summarize_range</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>blockNumber</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Summarizes the page range covering the given block, if not already
+ summarized. This is
+ like <code class="function">brin_summarize_new_values</code> except that it
+ only processes the page range that covers the given table block number.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.10.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">brin_desummarize_range</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>blockNumber</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Removes the BRIN index tuple that summarizes the page range covering
+ the given table block, if there is one.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.10.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">gin_clean_pending_list</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Cleans up the <span class="quote">“<span class="quote">pending</span>”</span> list of the specified GIN index
+ by moving entries in it, in bulk, to the main GIN data structure.
+ Returns the number of pages removed from the pending list.
+ If the argument is a GIN index built with
+ the <code class="literal">fastupdate</code> option disabled, no cleanup happens
+ and the result is zero, because the index doesn't have a pending list.
+ See <a class="xref" href="gin-implementation.html#GIN-FAST-UPDATE" title="70.4.1. GIN Fast Update Technique">Section 70.4.1</a> and <a class="xref" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Section 70.5</a>
+ for details about the pending list and <code class="literal">fastupdate</code>
+ option.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-GENFILE"><div class="titlepage"><div><div><h3 class="title">9.27.9. Generic File Access Functions</h3></div></div></div><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE-TABLE" title="Table 9.99. Generic File Access Functions">Table 9.99</a> provide native access to
+ files on the machine hosting the server. Only files within the
+ database cluster directory and the <code class="varname">log_directory</code> can be
+ accessed, unless the user is a superuser or is granted the role
+ <code class="literal">pg_read_server_files</code>. Use a relative path for files in
+ the cluster directory, and a path matching the <code class="varname">log_directory</code>
+ configuration setting for log files.
+ </p><p>
+ Note that granting users the EXECUTE privilege on
+ <code class="function">pg_read_file()</code>, or related functions, allows them the
+ ability to read any file on the server that the database server process can
+ read; these functions bypass all in-database privilege checks. This means
+ that, for example, a user with such access is able to read the contents of
+ the <code class="structname">pg_authid</code> table where authentication
+ information is stored, as well as read any table data in the database.
+ Therefore, granting access to these functions should be carefully
+ considered.
+ </p><p>
+ Some of these functions take an optional <em class="parameter"><code>missing_ok</code></em>
+ parameter, which specifies the behavior when the file or directory does
+ not exist. If <code class="literal">true</code>, the function
+ returns <code class="literal">NULL</code> or an empty result set, as appropriate.
+ If <code class="literal">false</code>, an error is raised. The default
+ is <code class="literal">false</code>.
+ </p><div class="table" id="FUNCTIONS-ADMIN-GENFILE-TABLE"><p class="title"><strong>Table 9.99. Generic File Access Functions</strong></p><div class="table-contents"><table class="table" summary="Generic File Access Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_dir</code> ( <em class="parameter"><code>dirname</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code>, <em class="parameter"><code>include_dot_dirs</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Returns the names of all files (and directories and other special
+ files) in the specified
+ directory. The <em class="parameter"><code>include_dot_dirs</code></em> parameter
+ indicates whether <span class="quote">“<span class="quote">.</span>”</span> and <span class="quote">“<span class="quote">..</span>”</span> are to be
+ included in the result set; the default is to exclude them. Including
+ them can be useful when <em class="parameter"><code>missing_ok</code></em>
+ is <code class="literal">true</code>, to distinguish an empty directory from a
+ non-existent directory.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_logdir</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's log directory. Filenames beginning with
+ a dot, directories, and other special files are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and roles with privileges of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_waldir</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's write-ahead log (WAL) directory.
+ Filenames beginning with a dot, directories, and other special files
+ are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and roles with privileges of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_logicalmapdir</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's <code class="filename">pg_logical/mappings</code>
+ directory. Filenames beginning with a dot, directories, and other
+ special files are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and members of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_logicalsnapdir</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's <code class="filename">pg_logical/snapshots</code>
+ directory. Filenames beginning with a dot, directories, and other
+ special files are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and members of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_replslotdir</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's <code class="filename">pg_replslot/slot_name</code>
+ directory, where <em class="parameter"><code>slot_name</code></em> is the name of the
+ replication slot provided as input of the function. Filenames beginning
+ with a dot, directories, and other special files are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and members of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_archive_statusdir</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's WAL archive status directory
+ (<code class="filename">pg_wal/archive_status</code>). Filenames beginning
+ with a dot, directories, and other special files are excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and members of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+
+ <a id="id-1.5.8.33.11.5.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ls_tmpdir</code> ( [<span class="optional"> <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code> </span>] )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
+ </p>
+ <p>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the temporary file directory for the
+ specified <em class="parameter"><code>tablespace</code></em>.
+ If <em class="parameter"><code>tablespace</code></em> is not provided,
+ the <code class="literal">pg_default</code> tablespace is examined. Filenames
+ beginning with a dot, directories, and other special files are
+ excluded.
+ </p>
+ <p>
+ This function is restricted to superusers and members of
+ the <code class="literal">pg_monitor</code> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_read_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">bigint</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns all or part of a text file, starting at the
+ given byte <em class="parameter"><code>offset</code></em>, returning at
+ most <em class="parameter"><code>length</code></em> bytes (less if the end of file is
+ reached first). If <em class="parameter"><code>offset</code></em> is negative, it is
+ relative to the end of the file. If <em class="parameter"><code>offset</code></em>
+ and <em class="parameter"><code>length</code></em> are omitted, the entire file is
+ returned. The bytes read from the file are interpreted as a string in
+ the database's encoding; an error is thrown if they are not valid in
+ that encoding.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_read_binary_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">bigint</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Returns all or part of a file. This function is identical to
+ <code class="function">pg_read_file</code> except that it can read arbitrary
+ binary data, returning the result as <code class="type">bytea</code>
+ not <code class="type">text</code>; accordingly, no encoding checks are performed.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p>
+ <p>
+ In combination with the <code class="function">convert_from</code> function,
+ this function can be used to read a text file in a specified encoding
+ and convert to the database's encoding:
+</p><pre class="programlisting">
+SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.11.5.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>access</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>change</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>creation</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>isdir</code></em> <code class="type">boolean</code> )
+ </p>
+ <p>
+ Returns a record containing the file's size, last access time stamp,
+ last modification time stamp, last file status change time stamp (Unix
+ platforms only), file creation time stamp (Windows only), and a flag
+ indicating if it is a directory.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADVISORY-LOCKS"><div class="titlepage"><div><div><h3 class="title">9.27.10. Advisory Lock Functions</h3></div></div></div><p>
+ The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS-TABLE" title="Table 9.100. Advisory Lock Functions">Table 9.100</a>
+ manage advisory locks. For details about proper use of these functions,
+ see <a class="xref" href="explicit-locking.html#ADVISORY-LOCKS" title="13.3.5. Advisory Locks">Section 13.3.5</a>.
+ </p><p>
+ All these functions are intended to be used to lock application-defined
+ resources, which can be identified either by a single 64-bit key value or
+ two 32-bit key values (note that these two key spaces do not overlap).
+ If another session already holds a conflicting lock on the same resource
+ identifier, the functions will either wait until the resource becomes
+ available, or return a <code class="literal">false</code> result, as appropriate for
+ the function.
+ Locks can be either shared or exclusive: a shared lock does not conflict
+ with other shared locks on the same resource, only with exclusive locks.
+ Locks can be taken at session level (so that they are held until released
+ or the session ends) or at transaction level (so that they are held until
+ the current transaction ends; there is no provision for manual release).
+ Multiple session-level lock requests stack, so that if the same resource
+ identifier is locked three times there must then be three unlock requests
+ to release the resource in advance of session end.
+ </p><div class="table" id="FUNCTIONS-ADVISORY-LOCKS-TABLE"><p class="title"><strong>Table 9.100. Advisory Lock Functions</strong></p><div class="table-contents"><table class="table" summary="Advisory Lock Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Obtains an exclusive session-level advisory lock, waiting if necessary.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Obtains a shared session-level advisory lock, waiting if necessary.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_unlock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_unlock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Releases a previously-acquired exclusive session-level advisory lock.
+ Returns <code class="literal">true</code> if the lock is successfully released.
+ If the lock was not held, <code class="literal">false</code> is returned, and in
+ addition, an SQL warning will be reported by the server.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_unlock_all</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Releases all session-level advisory locks held by the current session.
+ (This function is implicitly invoked at session end, even if the
+ client disconnects ungracefully.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_unlock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_unlock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Releases a previously-acquired shared session-level advisory lock.
+ Returns <code class="literal">true</code> if the lock is successfully released.
+ If the lock was not held, <code class="literal">false</code> is returned, and in
+ addition, an SQL warning will be reported by the server.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_xact_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_xact_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Obtains an exclusive transaction-level advisory lock, waiting if
+ necessary.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Obtains a shared transaction-level advisory lock, waiting if
+ necessary.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_try_advisory_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_try_advisory_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Obtains an exclusive session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <code class="literal">true</code>, or return <code class="literal">false</code>
+ without waiting if the lock cannot be acquired immediately.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_try_advisory_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_try_advisory_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Obtains a shared session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <code class="literal">true</code>, or return <code class="literal">false</code>
+ without waiting if the lock cannot be acquired immediately.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_try_advisory_xact_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_try_advisory_xact_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Obtains an exclusive transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <code class="literal">true</code>, or return <code class="literal">false</code>
+ without waiting if the lock cannot be acquired immediately.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.33.12.4.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_try_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">pg_try_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Obtains a shared transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <code class="literal">true</code>, or return <code class="literal">false</code>
+ without waiting if the lock cannot be acquired immediately.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-info.html" title="9.26. System Information Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-trigger.html" title="9.28. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.26. System Information Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.28. Trigger Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-aggregate.html b/doc/src/sgml/html/functions-aggregate.html
new file mode 100644
index 0000000..2485533
--- /dev/null
+++ b/doc/src/sgml/html/functions-aggregate.html
@@ -0,0 +1,729 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.21. Aggregate Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators" /><link rel="next" href="functions-window.html" title="9.22. Window Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.21. Aggregate Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-window.html" title="9.22. Window Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-AGGREGATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.21. Aggregate Functions</h2></div></div></div><a id="id-1.5.8.27.2" class="indexterm"></a><p>
+ <em class="firstterm">Aggregate functions</em> compute a single result
+ from a set of input values. The built-in general-purpose aggregate
+ functions are listed in <a class="xref" href="functions-aggregate.html#FUNCTIONS-AGGREGATE-TABLE" title="Table 9.58. General-Purpose Aggregate Functions">Table 9.58</a>
+ while statistical aggregates are in <a class="xref" href="functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE" title="Table 9.59. Aggregate Functions for Statistics">Table 9.59</a>.
+ The built-in within-group ordered-set aggregate functions
+ are listed in <a class="xref" href="functions-aggregate.html#FUNCTIONS-ORDEREDSET-TABLE" title="Table 9.60. Ordered-Set Aggregate Functions">Table 9.60</a>
+ while the built-in within-group hypothetical-set ones are in <a class="xref" href="functions-aggregate.html#FUNCTIONS-HYPOTHETICAL-TABLE" title="Table 9.61. Hypothetical-Set Aggregate Functions">Table 9.61</a>. Grouping operations,
+ which are closely related to aggregate functions, are listed in
+ <a class="xref" href="functions-aggregate.html#FUNCTIONS-GROUPING-TABLE" title="Table 9.62. Grouping Operations">Table 9.62</a>.
+ The special syntax considerations for aggregate
+ functions are explained in <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a>.
+ Consult <a class="xref" href="tutorial-agg.html" title="2.7. Aggregate Functions">Section 2.7</a> for additional introductory
+ information.
+ </p><p>
+ Aggregate functions that support <em class="firstterm">Partial Mode</em>
+ are eligible to participate in various optimizations, such as parallel
+ aggregation.
+ </p><div class="table" id="FUNCTIONS-AGGREGATE-TABLE"><p class="title"><strong>Table 9.58. General-Purpose Aggregate Functions</strong></p><div class="table-contents"><table class="table" summary="General-Purpose Aggregate Functions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th><th>Partial Mode</th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.1.1.1.1" class="indexterm"></a>
+ <code class="function">array_agg</code> ( <code class="type">anynonarray</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Collects all the input values, including nulls, into an array.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">array_agg</code> ( <code class="type">anyarray</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Concatenates all the input arrays into an array of one higher
+ dimension. (The inputs must all have the same dimensionality, and
+ cannot be empty or null.)
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.3.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.5.2.4.3.1.1.2" class="indexterm"></a>
+ <code class="function">avg</code> ( <code class="type">smallint</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">real</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">avg</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Computes the average (arithmetic mean) of all the non-null input
+ values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.4.1.1.1" class="indexterm"></a>
+ <code class="function">bit_and</code> ( <code class="type">smallint</code> )
+ → <code class="returnvalue">smallint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_and</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_and</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_and</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Computes the bitwise AND of all non-null input values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.5.1.1.1" class="indexterm"></a>
+ <code class="function">bit_or</code> ( <code class="type">smallint</code> )
+ → <code class="returnvalue">smallint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_or</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_or</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_or</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Computes the bitwise OR of all non-null input values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.6.1.1.1" class="indexterm"></a>
+ <code class="function">bit_xor</code> ( <code class="type">smallint</code> )
+ → <code class="returnvalue">smallint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_xor</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_xor</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">bit_xor</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Computes the bitwise exclusive OR of all non-null input values.
+ Can be useful as a checksum for an unordered set of values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.7.1.1.1" class="indexterm"></a>
+ <code class="function">bool_and</code> ( <code class="type">boolean</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if all non-null input values are true, otherwise false.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.8.1.1.1" class="indexterm"></a>
+ <code class="function">bool_or</code> ( <code class="type">boolean</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if any non-null input value is true, otherwise false.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.9.1.1.1" class="indexterm"></a>
+ <code class="function">count</code> ( <code class="literal">*</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the number of input rows.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">count</code> ( <code class="type">"any"</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the number of input rows in which the input value is not
+ null.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.11.1.1.1" class="indexterm"></a>
+ <code class="function">every</code> ( <code class="type">boolean</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ This is the SQL standard's equivalent to <code class="function">bool_and</code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.12.1.1.1" class="indexterm"></a>
+ <code class="function">json_agg</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.12.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_agg</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Collects all the input values, including nulls, into a JSON array.
+ Values are converted to JSON as per <code class="function">to_json</code>
+ or <code class="function">to_jsonb</code>.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.13.1.1.1" class="indexterm"></a>
+ <code class="function">json_object_agg</code> ( <em class="parameter"><code>key</code></em>
+ <code class="type">"any"</code>, <em class="parameter"><code>value</code></em>
+ <code class="type">"any"</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.13.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_object_agg</code> ( <em class="parameter"><code>key</code></em>
+ <code class="type">"any"</code>, <em class="parameter"><code>value</code></em>
+ <code class="type">"any"</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Collects all the key/value pairs into a JSON object. Key arguments
+ are coerced to text; value arguments are converted as
+ per <code class="function">to_json</code> or <code class="function">to_jsonb</code>.
+ Values can be null, but not keys.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.14.1.1.1" class="indexterm"></a>
+ <code class="function">max</code> ( <em class="replaceable"><code>see text</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>same as input type</code></em></code>
+ </p>
+ <p>
+ Computes the maximum of the non-null input
+ values. Available for any numeric, string, date/time, or enum type,
+ as well as <code class="type">inet</code>, <code class="type">interval</code>,
+ <code class="type">money</code>, <code class="type">oid</code>, <code class="type">pg_lsn</code>,
+ <code class="type">tid</code>, <code class="type">xid8</code>,
+ and arrays of any of these types.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.15.1.1.1" class="indexterm"></a>
+ <code class="function">min</code> ( <em class="replaceable"><code>see text</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>same as input type</code></em></code>
+ </p>
+ <p>
+ Computes the minimum of the non-null input
+ values. Available for any numeric, string, date/time, or enum type,
+ as well as <code class="type">inet</code>, <code class="type">interval</code>,
+ <code class="type">money</code>, <code class="type">oid</code>, <code class="type">pg_lsn</code>,
+ <code class="type">tid</code>, <code class="type">xid8</code>,
+ and arrays of any of these types.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.16.1.1.1" class="indexterm"></a>
+ <code class="function">range_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">anyrange</code> )
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">range_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">anymultirange</code> )
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Computes the union of the non-null input values.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.17.1.1.1" class="indexterm"></a>
+ <code class="function">range_intersect_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">anyrange</code> )
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">range_intersect_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">anymultirange</code> )
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Computes the intersection of the non-null input values.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.18.1.1.1" class="indexterm"></a>
+ <code class="function">string_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">text</code>, <em class="parameter"><code>delimiter</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">string_agg</code> ( <em class="parameter"><code>value</code></em>
+ <code class="type">bytea</code>, <em class="parameter"><code>delimiter</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Concatenates the non-null input values into a string. Each value
+ after the first is preceded by the
+ corresponding <em class="parameter"><code>delimiter</code></em> (if it's not null).
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.19.1.1.1" class="indexterm"></a>
+ <code class="function">sum</code> ( <code class="type">smallint</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">real</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sum</code> ( <code class="type">money</code> )
+ → <code class="returnvalue">money</code>
+ </p>
+ <p>
+ Computes the sum of the non-null input values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.5.2.4.20.1.1.1" class="indexterm"></a>
+ <code class="function">xmlagg</code> ( <code class="type">xml</code> )
+ → <code class="returnvalue">xml</code>
+ </p>
+ <p>
+ Concatenates the non-null XML input values (see
+ <a class="xref" href="functions-xml.html#FUNCTIONS-XML-XMLAGG" title="9.15.1.7. xmlagg">Section 9.15.1.7</a>).
+ </p></td><td>No</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ It should be noted that except for <code class="function">count</code>,
+ these functions return a null value when no rows are selected. In
+ particular, <code class="function">sum</code> of no rows returns null, not
+ zero as one might expect, and <code class="function">array_agg</code>
+ returns null rather than an empty array when there are no input
+ rows. The <code class="function">coalesce</code> function can be used to
+ substitute zero or an empty array for null when necessary.
+ </p><p>
+ The aggregate functions <code class="function">array_agg</code>,
+ <code class="function">json_agg</code>, <code class="function">jsonb_agg</code>,
+ <code class="function">json_object_agg</code>, <code class="function">jsonb_object_agg</code>,
+ <code class="function">string_agg</code>,
+ and <code class="function">xmlagg</code>, as well as similar user-defined
+ aggregate functions, produce meaningfully different result values
+ depending on the order of the input values. This ordering is
+ unspecified by default, but can be controlled by writing an
+ <code class="literal">ORDER BY</code> clause within the aggregate call, as shown in
+ <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a>.
+ Alternatively, supplying the input values from a sorted subquery
+ will usually work. For example:
+
+</p><pre class="screen">
+SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
+</pre><p>
+
+ Beware that this approach can fail if the outer query level contains
+ additional processing, such as a join, because that might cause the
+ subquery's output to be reordered before the aggregate is computed.
+ </p><div class="note"><h3 class="title">Note</h3><a id="id-1.5.8.27.8.1" class="indexterm"></a><a id="id-1.5.8.27.8.2" class="indexterm"></a><p>
+ The boolean aggregates <code class="function">bool_and</code> and
+ <code class="function">bool_or</code> correspond to the standard SQL aggregates
+ <code class="function">every</code> and <code class="function">any</code> or
+ <code class="function">some</code>.
+ <span class="productname">PostgreSQL</span>
+ supports <code class="function">every</code>, but not <code class="function">any</code>
+ or <code class="function">some</code>, because there is an ambiguity built into
+ the standard syntax:
+</p><pre class="programlisting">
+SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
+</pre><p>
+ Here <code class="function">ANY</code> can be considered either as introducing
+ a subquery, or as being an aggregate function, if the subquery
+ returns one row with a Boolean value.
+ Thus the standard name cannot be given to these aggregates.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Users accustomed to working with other SQL database management
+ systems might be disappointed by the performance of the
+ <code class="function">count</code> aggregate when it is applied to the
+ entire table. A query like:
+</p><pre class="programlisting">
+SELECT count(*) FROM sometable;
+</pre><p>
+ will require effort proportional to the size of the table:
+ <span class="productname">PostgreSQL</span> will need to scan either the
+ entire table or the entirety of an index that includes all rows in
+ the table.
+ </p></div><p>
+ <a class="xref" href="functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE" title="Table 9.59. Aggregate Functions for Statistics">Table 9.59</a> shows
+ aggregate functions typically used in statistical analysis.
+ (These are separated out merely to avoid cluttering the listing
+ of more-commonly-used aggregates.) Functions shown as
+ accepting <em class="replaceable"><code>numeric_type</code></em> are available for all
+ the types <code class="type">smallint</code>, <code class="type">integer</code>,
+ <code class="type">bigint</code>, <code class="type">numeric</code>, <code class="type">real</code>,
+ and <code class="type">double precision</code>.
+ Where the description mentions
+ <em class="parameter"><code>N</code></em>, it means the
+ number of input rows for which all the input expressions are non-null.
+ In all cases, null is returned if the computation is meaningless,
+ for example when <em class="parameter"><code>N</code></em> is zero.
+ </p><a id="id-1.5.8.27.11" class="indexterm"></a><a id="id-1.5.8.27.12" class="indexterm"></a><div class="table" id="FUNCTIONS-AGGREGATE-STATISTICS-TABLE"><p class="title"><strong>Table 9.59. Aggregate Functions for Statistics</strong></p><div class="table-contents"><table class="table" summary="Aggregate Functions for Statistics" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th><th>Partial Mode</th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.1.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.1.1.1.2" class="indexterm"></a>
+ <code class="function">corr</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the correlation coefficient.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.2.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.2.1.1.2" class="indexterm"></a>
+ <code class="function">covar_pop</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the population covariance.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.3.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.3.1.1.2" class="indexterm"></a>
+ <code class="function">covar_samp</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the sample covariance.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.4.1.1.1" class="indexterm"></a>
+ <code class="function">regr_avgx</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the average of the independent variable,
+ <code class="literal">sum(<em class="parameter"><code>X</code></em>)/<em class="parameter"><code>N</code></em></code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.5.1.1.1" class="indexterm"></a>
+ <code class="function">regr_avgy</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the average of the dependent variable,
+ <code class="literal">sum(<em class="parameter"><code>Y</code></em>)/<em class="parameter"><code>N</code></em></code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.6.1.1.1" class="indexterm"></a>
+ <code class="function">regr_count</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the number of rows in which both inputs are non-null.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.7.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.7.1.1.2" class="indexterm"></a>
+ <code class="function">regr_intercept</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the y-intercept of the least-squares-fit linear equation
+ determined by the
+ (<em class="parameter"><code>X</code></em>, <em class="parameter"><code>Y</code></em>) pairs.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.8.1.1.1" class="indexterm"></a>
+ <code class="function">regr_r2</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the square of the correlation coefficient.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.9.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.9.1.1.2" class="indexterm"></a>
+ <code class="function">regr_slope</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the slope of the least-squares-fit linear equation determined
+ by the (<em class="parameter"><code>X</code></em>, <em class="parameter"><code>Y</code></em>)
+ pairs.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.10.1.1.1" class="indexterm"></a>
+ <code class="function">regr_sxx</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the <span class="quote">“<span class="quote">sum of squares</span>”</span> of the independent
+ variable,
+ <code class="literal">sum(<em class="parameter"><code>X</code></em>^2) - sum(<em class="parameter"><code>X</code></em>)^2/<em class="parameter"><code>N</code></em></code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.11.1.1.1" class="indexterm"></a>
+ <code class="function">regr_sxy</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the <span class="quote">“<span class="quote">sum of products</span>”</span> of independent times
+ dependent variables,
+ <code class="literal">sum(<em class="parameter"><code>X</code></em>*<em class="parameter"><code>Y</code></em>) - sum(<em class="parameter"><code>X</code></em>) * sum(<em class="parameter"><code>Y</code></em>)/<em class="parameter"><code>N</code></em></code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.12.1.1.1" class="indexterm"></a>
+ <code class="function">regr_syy</code> ( <em class="parameter"><code>Y</code></em> <code class="type">double precision</code>, <em class="parameter"><code>X</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the <span class="quote">“<span class="quote">sum of squares</span>”</span> of the dependent
+ variable,
+ <code class="literal">sum(<em class="parameter"><code>Y</code></em>^2) - sum(<em class="parameter"><code>Y</code></em>)^2/<em class="parameter"><code>N</code></em></code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.13.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.13.1.1.2" class="indexterm"></a>
+ <code class="function">stddev</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ This is a historical alias for <code class="function">stddev_samp</code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.14.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.14.1.1.2" class="indexterm"></a>
+ <code class="function">stddev_pop</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ Computes the population standard deviation of the input values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.15.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.15.1.1.2" class="indexterm"></a>
+ <code class="function">stddev_samp</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ Computes the sample standard deviation of the input values.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.16.1.1.1" class="indexterm"></a>
+ <code class="function">variance</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ This is a historical alias for <code class="function">var_samp</code>.
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.17.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.17.1.1.2" class="indexterm"></a>
+ <code class="function">var_pop</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ Computes the population variance of the input values (square of the
+ population standard deviation).
+ </p></td><td>Yes</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.13.2.4.18.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.27.13.2.4.18.1.1.2" class="indexterm"></a>
+ <code class="function">var_samp</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"></code> <code class="type">double precision</code>
+ for <code class="type">real</code> or <code class="type">double precision</code>,
+ otherwise <code class="type">numeric</code>
+ </p>
+ <p>
+ Computes the sample variance of the input values (square of the sample
+ standard deviation).
+ </p></td><td>Yes</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-aggregate.html#FUNCTIONS-ORDEREDSET-TABLE" title="Table 9.60. Ordered-Set Aggregate Functions">Table 9.60</a> shows some
+ aggregate functions that use the <em class="firstterm">ordered-set aggregate</em>
+ syntax. These functions are sometimes referred to as <span class="quote">“<span class="quote">inverse
+ distribution</span>”</span> functions. Their aggregated input is introduced by
+ <code class="literal">ORDER BY</code>, and they may also take a <em class="firstterm">direct
+ argument</em> that is not aggregated, but is computed only once.
+ All these functions ignore null values in their aggregated input.
+ For those that take a <em class="parameter"><code>fraction</code></em> parameter, the
+ fraction value must be between 0 and 1; an error is thrown if not.
+ However, a null <em class="parameter"><code>fraction</code></em> value simply produces a
+ null result.
+ </p><a id="id-1.5.8.27.15" class="indexterm"></a><a id="id-1.5.8.27.16" class="indexterm"></a><div class="table" id="FUNCTIONS-ORDEREDSET-TABLE"><p class="title"><strong>Table 9.60. Ordered-Set Aggregate Functions</strong></p><div class="table-contents"><table class="table" summary="Ordered-Set Aggregate Functions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th><th>Partial Mode</th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.17.2.4.1.1.1.1" class="indexterm"></a>
+ <code class="function">mode</code> () <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">anyelement</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Computes the <em class="firstterm">mode</em>, the most frequent
+ value of the aggregated argument (arbitrarily choosing the first one
+ if there are multiple equally-frequent values). The aggregated
+ argument must be of a sortable type.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.17.2.4.2.1.1.1" class="indexterm"></a>
+ <code class="function">percentile_cont</code> ( <em class="parameter"><code>fraction</code></em> <code class="type">double precision</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">percentile_cont</code> ( <em class="parameter"><code>fraction</code></em> <code class="type">double precision</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Computes the <em class="firstterm">continuous percentile</em>, a value
+ corresponding to the specified <em class="parameter"><code>fraction</code></em>
+ within the ordered set of aggregated argument values. This will
+ interpolate between adjacent input items if needed.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">percentile_cont</code> ( <em class="parameter"><code>fractions</code></em> <code class="type">double precision[]</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision[]</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">percentile_cont</code> ( <em class="parameter"><code>fractions</code></em> <code class="type">double precision[]</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">interval</code> )
+ → <code class="returnvalue">interval[]</code>
+ </p>
+ <p>
+ Computes multiple continuous percentiles. The result is an array of
+ the same dimensions as the <em class="parameter"><code>fractions</code></em>
+ parameter, with each non-null element replaced by the (possibly
+ interpolated) value corresponding to that percentile.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.17.2.4.4.1.1.1" class="indexterm"></a>
+ <code class="function">percentile_disc</code> ( <em class="parameter"><code>fraction</code></em> <code class="type">double precision</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">anyelement</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Computes the <em class="firstterm">discrete percentile</em>, the first
+ value within the ordered set of aggregated argument values whose
+ position in the ordering equals or exceeds the
+ specified <em class="parameter"><code>fraction</code></em>. The aggregated
+ argument must be of a sortable type.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">percentile_disc</code> ( <em class="parameter"><code>fractions</code></em> <code class="type">double precision[]</code> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <code class="type">anyelement</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Computes multiple discrete percentiles. The result is an array of the
+ same dimensions as the <em class="parameter"><code>fractions</code></em> parameter,
+ with each non-null element replaced by the input value corresponding
+ to that percentile.
+ The aggregated argument must be of a sortable type.
+ </p></td><td>No</td></tr></tbody></table></div></div><br class="table-break" /><a id="id-1.5.8.27.18" class="indexterm"></a><p>
+ Each of the <span class="quote">“<span class="quote">hypothetical-set</span>”</span> aggregates listed in
+ <a class="xref" href="functions-aggregate.html#FUNCTIONS-HYPOTHETICAL-TABLE" title="Table 9.61. Hypothetical-Set Aggregate Functions">Table 9.61</a> is associated with a
+ window function of the same name defined in
+ <a class="xref" href="functions-window.html" title="9.22. Window Functions">Section 9.22</a>. In each case, the aggregate's result
+ is the value that the associated window function would have
+ returned for the <span class="quote">“<span class="quote">hypothetical</span>”</span> row constructed from
+ <em class="replaceable"><code>args</code></em>, if such a row had been added to the sorted
+ group of rows represented by the <em class="replaceable"><code>sorted_args</code></em>.
+ For each of these functions, the list of direct arguments
+ given in <em class="replaceable"><code>args</code></em> must match the number and types of
+ the aggregated arguments given in <em class="replaceable"><code>sorted_args</code></em>.
+ Unlike most built-in aggregates, these aggregates are not strict, that is
+ they do not drop input rows containing nulls. Null values sort according
+ to the rule specified in the <code class="literal">ORDER BY</code> clause.
+ </p><div class="table" id="FUNCTIONS-HYPOTHETICAL-TABLE"><p class="title"><strong>Table 9.61. Hypothetical-Set Aggregate Functions</strong></p><div class="table-contents"><table class="table" summary="Hypothetical-Set Aggregate Functions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th><th>Partial Mode</th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.20.2.4.1.1.1.1" class="indexterm"></a>
+ <code class="function">rank</code> ( <em class="replaceable"><code>args</code></em> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <em class="replaceable"><code>sorted_args</code></em> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the rank of the hypothetical row, with gaps; that is, the row
+ number of the first row in its peer group.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.20.2.4.2.1.1.1" class="indexterm"></a>
+ <code class="function">dense_rank</code> ( <em class="replaceable"><code>args</code></em> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <em class="replaceable"><code>sorted_args</code></em> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the rank of the hypothetical row, without gaps; this function
+ effectively counts peer groups.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.20.2.4.3.1.1.1" class="indexterm"></a>
+ <code class="function">percent_rank</code> ( <em class="replaceable"><code>args</code></em> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <em class="replaceable"><code>sorted_args</code></em> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the relative rank of the hypothetical row, that is
+ (<code class="function">rank</code> - 1) / (total rows - 1).
+ The value thus ranges from 0 to 1 inclusive.
+ </p></td><td>No</td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.20.2.4.4.1.1.1" class="indexterm"></a>
+ <code class="function">cume_dist</code> ( <em class="replaceable"><code>args</code></em> ) <code class="literal">WITHIN GROUP</code> ( <code class="literal">ORDER BY</code> <em class="replaceable"><code>sorted_args</code></em> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the cumulative distribution, that is (number of rows
+ preceding or peers with hypothetical row) / (total rows). The value
+ thus ranges from 1/<em class="parameter"><code>N</code></em> to 1.
+ </p></td><td>No</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-GROUPING-TABLE"><p class="title"><strong>Table 9.62. Grouping Operations</strong></p><div class="table-contents"><table class="table" summary="Grouping Operations" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.27.21.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">GROUPING</code> ( <em class="replaceable"><code>group_by_expression(s)</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns a bit mask indicating which <code class="literal">GROUP BY</code>
+ expressions are not included in the current grouping set.
+ Bits are assigned with the rightmost argument corresponding to the
+ least-significant bit; each bit is 0 if the corresponding expression
+ is included in the grouping criteria of the grouping set generating
+ the current result row, and 1 if it is not included.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The grouping operations shown in
+ <a class="xref" href="functions-aggregate.html#FUNCTIONS-GROUPING-TABLE" title="Table 9.62. Grouping Operations">Table 9.62</a> are used in conjunction with
+ grouping sets (see <a class="xref" href="queries-table-expressions.html#QUERIES-GROUPING-SETS" title="7.2.4. GROUPING SETS, CUBE, and ROLLUP">Section 7.2.4</a>) to distinguish
+ result rows. The arguments to the <code class="literal">GROUPING</code> function
+ are not actually evaluated, but they must exactly match expressions given
+ in the <code class="literal">GROUP BY</code> clause of the associated query level.
+ For example:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM items_sold;</code></strong>
+ make | model | sales
+-------+-------+-------
+ Foo | GT | 10
+ Foo | Tour | 20
+ Bar | City | 15
+ Bar | Sport | 5
+(4 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT make, model, GROUPING(make,model), sum(sales) FROM items_sold GROUP BY ROLLUP(make,model);</code></strong>
+ make | model | grouping | sum
+-------+-------+----------+-----
+ Foo | GT | 0 | 10
+ Foo | Tour | 0 | 20
+ Bar | City | 0 | 15
+ Bar | Sport | 0 | 5
+ Foo | | 1 | 30
+ Bar | | 1 | 20
+ | | 3 | 50
+(7 rows)
+</pre><p>
+ Here, the <code class="literal">grouping</code> value <code class="literal">0</code> in the
+ first four rows shows that those have been grouped normally, over both the
+ grouping columns. The value <code class="literal">1</code> indicates
+ that <code class="literal">model</code> was not grouped by in the next-to-last two
+ rows, and the value <code class="literal">3</code> indicates that
+ neither <code class="literal">make</code> nor <code class="literal">model</code> was grouped
+ by in the last row (which therefore is an aggregate over all the input
+ rows).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-window.html" title="9.22. Window Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.20. Range/Multirange Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.22. Window Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-array.html b/doc/src/sgml/html/functions-array.html
new file mode 100644
index 0000000..2eeb231
--- /dev/null
+++ b/doc/src/sgml/html/functions-array.html
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.19. Array Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-conditional.html" title="9.18. Conditional Expressions" /><link rel="next" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.19. Array Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-conditional.html" title="9.18. Conditional Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-ARRAY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.19. Array Functions and Operators</h2></div></div></div><p>
+ <a class="xref" href="functions-array.html#ARRAY-OPERATORS-TABLE" title="Table 9.52. Array Operators">Table 9.52</a> shows the specialized operators
+ available for array types.
+ In addition to those, the usual comparison operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for
+ arrays. The comparison operators compare the array contents
+ element-by-element, using the default B-tree comparison function for
+ the element data type, and sort based on the first difference.
+ In multidimensional arrays the elements are visited in row-major order
+ (last subscript varies most rapidly).
+ If the contents of two arrays are equal but the dimensionality is
+ different, the first difference in the dimensionality information
+ determines the sort order.
+ </p><div class="table" id="ARRAY-OPERATORS-TABLE"><p class="title"><strong>Table 9.52. Array Operators</strong></p><div class="table-contents"><table class="table" summary="Array Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyarray</code> <code class="literal">@&gt;</code> <code class="type">anyarray</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first array contain the second, that is, does each element
+ appearing in the second array equal some element of the first array?
+ (Duplicates are not treated specially,
+ thus <code class="literal">ARRAY[1]</code> and <code class="literal">ARRAY[1,1]</code> are
+ each considered to contain the other.)
+ </p>
+ <p>
+ <code class="literal">ARRAY[1,4,3] @&gt; ARRAY[3,1,3]</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyarray</code> <code class="literal">&lt;@</code> <code class="type">anyarray</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first array contained by the second?
+ </p>
+ <p>
+ <code class="literal">ARRAY[2,2,7] &lt;@ ARRAY[1,7,4,2,6]</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyarray</code> <code class="literal">&amp;&amp;</code> <code class="type">anyarray</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do the arrays overlap, that is, have any elements in common?
+ </p>
+ <p>
+ <code class="literal">ARRAY[1,4,3] &amp;&amp; ARRAY[2,1]</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anycompatiblearray</code> <code class="literal">||</code> <code class="type">anycompatiblearray</code>
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Concatenates the two arrays. Concatenating a null or empty array is a
+ no-op; otherwise the arrays must have the same number of dimensions
+ (as illustrated by the first example) or differ in number of
+ dimensions by one (as illustrated by the second).
+ If the arrays are not of identical element types, they will be coerced
+ to a common type (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
+ </p>
+ <p>
+ <code class="literal">ARRAY[1,2,3] || ARRAY[4,5,6,7]</code>
+ → <code class="returnvalue">{1,2,3,4,5,6,7}</code>
+ </p>
+ <p>
+ <code class="literal">ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9.9]]</code>
+ → <code class="returnvalue">{{1,2,3},{4,5,6},{7,8,9.9}}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anycompatible</code> <code class="literal">||</code> <code class="type">anycompatiblearray</code>
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Concatenates an element onto the front of an array (which must be
+ empty or one-dimensional).
+ </p>
+ <p>
+ <code class="literal">3 || ARRAY[4,5,6]</code>
+ → <code class="returnvalue">{3,4,5,6}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anycompatiblearray</code> <code class="literal">||</code> <code class="type">anycompatible</code>
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Concatenates an element onto the end of an array (which must be
+ empty or one-dimensional).
+ </p>
+ <p>
+ <code class="literal">ARRAY[4,5,6] || 7</code>
+ → <code class="returnvalue">{4,5,6,7}</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ See <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a> for more details about array operator
+ behavior. See <a class="xref" href="indexes-types.html" title="11.2. Index Types">Section 11.2</a> for more details about
+ which operators support indexed operations.
+ </p><p>
+ <a class="xref" href="functions-array.html#ARRAY-FUNCTIONS-TABLE" title="Table 9.53. Array Functions">Table 9.53</a> shows the functions
+ available for use with array types. See <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a>
+ for more information and examples of the use of these functions.
+ </p><div class="table" id="ARRAY-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.53. Array Functions</strong></p><div class="table-contents"><table class="table" summary="Array Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">array_append</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatible</code> )
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Appends an element to the end of an array (same as
+ the <code class="type">anycompatiblearray</code> <code class="literal">||</code> <code class="type">anycompatible</code>
+ operator).
+ </p>
+ <p>
+ <code class="literal">array_append(ARRAY[1,2], 3)</code>
+ → <code class="returnvalue">{1,2,3}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">array_cat</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatiblearray</code> )
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Concatenates two arrays (same as
+ the <code class="type">anycompatiblearray</code> <code class="literal">||</code> <code class="type">anycompatiblearray</code>
+ operator).
+ </p>
+ <p>
+ <code class="literal">array_cat(ARRAY[1,2,3], ARRAY[4,5])</code>
+ → <code class="returnvalue">{1,2,3,4,5}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">array_dims</code> ( <code class="type">anyarray</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns a text representation of the array's dimensions.
+ </p>
+ <p>
+ <code class="literal">array_dims(ARRAY[[1,2,3], [4,5,6]])</code>
+ → <code class="returnvalue">[1:2][1:3]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">array_fill</code> ( <code class="type">anyelement</code>, <code class="type">integer[]</code>
+ [<span class="optional">, <code class="type">integer[]</code> </span>] )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Returns an array filled with copies of the given value, having
+ dimensions of the lengths specified by the second argument.
+ The optional third argument supplies lower-bound values for each
+ dimension (which default to all <code class="literal">1</code>).
+ </p>
+ <p>
+ <code class="literal">array_fill(11, ARRAY[2,3])</code>
+ → <code class="returnvalue">{{11,11,11},{11,11,11}}</code>
+ </p>
+ <p>
+ <code class="literal">array_fill(7, ARRAY[3], ARRAY[2])</code>
+ → <code class="returnvalue">[2:4]={7,7,7}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">array_length</code> ( <code class="type">anyarray</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the length of the requested array dimension.
+ (Produces NULL instead of 0 for empty or missing array dimensions.)
+ </p>
+ <p>
+ <code class="literal">array_length(array[1,2,3], 1)</code>
+ → <code class="returnvalue">3</code>
+ </p>
+ <p>
+ <code class="literal">array_length(array[]::int[], 1)</code>
+ → <code class="returnvalue">NULL</code>
+ </p>
+ <p>
+ <code class="literal">array_length(array['text'], 2)</code>
+ → <code class="returnvalue">NULL</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">array_lower</code> ( <code class="type">anyarray</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the lower bound of the requested array dimension.
+ </p>
+ <p>
+ <code class="literal">array_lower('[0:2]={1,2,3}'::integer[], 1)</code>
+ → <code class="returnvalue">0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">array_ndims</code> ( <code class="type">anyarray</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of dimensions of the array.
+ </p>
+ <p>
+ <code class="literal">array_ndims(ARRAY[[1,2,3], [4,5,6]])</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">array_position</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatible</code> [<span class="optional">, <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the subscript of the first occurrence of the second argument
+ in the array, or <code class="literal">NULL</code> if it's not present.
+ If the third argument is given, the search begins at that subscript.
+ The array must be one-dimensional.
+ Comparisons are done using <code class="literal">IS NOT DISTINCT FROM</code>
+ semantics, so it is possible to search for <code class="literal">NULL</code>.
+ </p>
+ <p>
+ <code class="literal">array_position(ARRAY['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'], 'mon')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">array_positions</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatible</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Returns an array of the subscripts of all occurrences of the second
+ argument in the array given as first argument.
+ The array must be one-dimensional.
+ Comparisons are done using <code class="literal">IS NOT DISTINCT FROM</code>
+ semantics, so it is possible to search for <code class="literal">NULL</code>.
+ <code class="literal">NULL</code> is returned only if the array
+ is <code class="literal">NULL</code>; if the value is not found in the array, an
+ empty array is returned.
+ </p>
+ <p>
+ <code class="literal">array_positions(ARRAY['A','A','B','A'], 'A')</code>
+ → <code class="returnvalue">{1,2,4}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">array_prepend</code> ( <code class="type">anycompatible</code>, <code class="type">anycompatiblearray</code> )
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Prepends an element to the beginning of an array (same as
+ the <code class="type">anycompatible</code> <code class="literal">||</code> <code class="type">anycompatiblearray</code>
+ operator).
+ </p>
+ <p>
+ <code class="literal">array_prepend(1, ARRAY[2,3])</code>
+ → <code class="returnvalue">{1,2,3}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">array_remove</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatible</code> )
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Removes all elements equal to the given value from the array.
+ The array must be one-dimensional.
+ Comparisons are done using <code class="literal">IS NOT DISTINCT FROM</code>
+ semantics, so it is possible to remove <code class="literal">NULL</code>s.
+ </p>
+ <p>
+ <code class="literal">array_remove(ARRAY[1,2,3,2], 2)</code>
+ → <code class="returnvalue">{1,3}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">array_replace</code> ( <code class="type">anycompatiblearray</code>, <code class="type">anycompatible</code>, <code class="type">anycompatible</code> )
+ → <code class="returnvalue">anycompatiblearray</code>
+ </p>
+ <p>
+ Replaces each array element equal to the second argument with the
+ third argument.
+ </p>
+ <p>
+ <code class="literal">array_replace(ARRAY[1,2,5,4], 5, 3)</code>
+ → <code class="returnvalue">{1,2,3,4}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="FUNCTION-ARRAY-TO-STRING" class="indexterm"></a>
+ <code class="function">array_to_string</code> ( <em class="parameter"><code>array</code></em> <code class="type">anyarray</code>, <em class="parameter"><code>delimiter</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>null_string</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts each array element to its text representation, and
+ concatenates those separated by
+ the <em class="parameter"><code>delimiter</code></em> string.
+ If <em class="parameter"><code>null_string</code></em> is given and is
+ not <code class="literal">NULL</code>, then <code class="literal">NULL</code> array
+ entries are represented by that string; otherwise, they are omitted.
+ See also <a class="link" href="functions-string.html#FUNCTION-STRING-TO-ARRAY"><code class="function">string_to_array</code></a>.
+ </p>
+ <p>
+ <code class="literal">array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')</code>
+ → <code class="returnvalue">1,2,3,*,5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">array_upper</code> ( <code class="type">anyarray</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the upper bound of the requested array dimension.
+ </p>
+ <p>
+ <code class="literal">array_upper(ARRAY[1,8,3,7], 1)</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">cardinality</code> ( <code class="type">anyarray</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the total number of elements in the array, or 0 if the array
+ is empty.
+ </p>
+ <p>
+ <code class="literal">cardinality(ARRAY[[1,2],[3,4]])</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">trim_array</code> ( <em class="parameter"><code>array</code></em> <code class="type">anyarray</code>, <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Trims an array by removing the last <em class="parameter"><code>n</code></em> elements.
+ If the array is multidimensional, only the first dimension is trimmed.
+ </p>
+ <p>
+ <code class="literal">trim_array(ARRAY[1,2,3,4,5,6], 2)</code>
+ → <code class="returnvalue">{1,2,3,4}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.25.6.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">unnest</code> ( <code class="type">anyarray</code> )
+ → <code class="returnvalue">setof anyelement</code>
+ </p>
+ <p>
+ Expands an array into a set of rows.
+ The array's elements are read out in storage order.
+ </p>
+ <p>
+ <code class="literal">unnest(ARRAY[1,2])</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ 1
+ 2
+</pre><p>
+ </p>
+ <p>
+ <code class="literal">unnest(ARRAY[['foo','bar'],['baz','quux']])</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ foo
+ bar
+ baz
+ quux
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">unnest</code> ( <code class="type">anyarray</code>, <code class="type">anyarray</code> [<span class="optional">, ... </span>] )
+ → <code class="returnvalue">setof anyelement, anyelement [, ... ]</code>
+ </p>
+ <p>
+ Expands multiple arrays (possibly of different data types) into a set of
+ rows. If the arrays are not all the same length then the shorter ones
+ are padded with <code class="literal">NULL</code>s. This form is only allowed
+ in a query's FROM clause; see <a class="xref" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS" title="7.2.1.4. Table Functions">Section 7.2.1.4</a>.
+ </p>
+ <p>
+ <code class="literal">select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ a | b
+---+-----
+ 1 | foo
+ 2 | bar
+ | baz
+</pre><p>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ See also <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> about the aggregate
+ function <code class="function">array_agg</code> for use with arrays.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-conditional.html" title="9.18. Conditional Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-range.html" title="9.20. Range/Multirange Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.18. Conditional Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.20. Range/Multirange Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-binarystring.html b/doc/src/sgml/html/functions-binarystring.html
new file mode 100644
index 0000000..b1a536e
--- /dev/null
+++ b/doc/src/sgml/html/functions-binarystring.html
@@ -0,0 +1,510 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.5. Binary String Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-string.html" title="9.4. String Functions and Operators" /><link rel="next" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.5. Binary String Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-string.html" title="9.4. String Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-BINARYSTRING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.5. Binary String Functions and Operators</h2></div></div></div><a id="id-1.5.8.11.2" class="indexterm"></a><p>
+ This section describes functions and operators for examining and
+ manipulating binary strings, that is values of type <code class="type">bytea</code>.
+ Many of these are equivalent, in purpose and syntax, to the
+ text-string functions described in the previous section.
+ </p><p>
+ <acronym class="acronym">SQL</acronym> defines some string functions that use
+ key words, rather than commas, to separate
+ arguments. Details are in
+ <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-SQL" title="Table 9.11. SQL Binary String Functions and Operators">Table 9.11</a>.
+ <span class="productname">PostgreSQL</span> also provides versions of these functions
+ that use the regular function invocation syntax
+ (see <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-OTHER" title="Table 9.12. Other Binary String Functions">Table 9.12</a>).
+ </p><div class="table" id="FUNCTIONS-BINARYSTRING-SQL"><p class="title"><strong>Table 9.11. <acronym class="acronym">SQL</acronym> Binary String Functions and Operators</strong></p><div class="table-contents"><table class="table" summary="SQL Binary String Functions and Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function/Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="type">bytea</code> <code class="literal">||</code> <code class="type">bytea</code>
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Concatenates the two binary strings.
+ </p>
+ <p>
+ <code class="literal">'\x123456'::bytea || '\x789a00bcde'::bytea</code>
+ → <code class="returnvalue">\x123456789a00bcde</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">bit_length</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bits in the binary string (8
+ times the <code class="function">octet_length</code>).
+ </p>
+ <p>
+ <code class="literal">bit_length('\x123456'::bytea)</code>
+ → <code class="returnvalue">24</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">octet_length</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bytes in the binary string.
+ </p>
+ <p>
+ <code class="literal">octet_length('\x123456'::bytea)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">overlay</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> <code class="literal">PLACING</code> <em class="parameter"><code>newsubstring</code></em> <code class="type">bytea</code> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Replaces the substring of <em class="parameter"><code>bytes</code></em> that starts at
+ the <em class="parameter"><code>start</code></em>'th byte and extends
+ for <em class="parameter"><code>count</code></em> bytes
+ with <em class="parameter"><code>newsubstring</code></em>.
+ If <em class="parameter"><code>count</code></em> is omitted, it defaults to the length
+ of <em class="parameter"><code>newsubstring</code></em>.
+ </p>
+ <p>
+ <code class="literal">overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)</code>
+ → <code class="returnvalue">\x12020390</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">position</code> ( <em class="parameter"><code>substring</code></em> <code class="type">bytea</code> <code class="literal">IN</code> <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns first starting index of the specified
+ <em class="parameter"><code>substring</code></em> within
+ <em class="parameter"><code>bytes</code></em>, or zero if it's not present.
+ </p>
+ <p>
+ <code class="literal">position('\x5678'::bytea in '\x1234567890'::bytea)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">substring</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> [<span class="optional"> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> </span>] [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Extracts the substring of <em class="parameter"><code>bytes</code></em> starting at
+ the <em class="parameter"><code>start</code></em>'th byte if that is specified,
+ and stopping after <em class="parameter"><code>count</code></em> bytes if that is
+ specified. Provide at least one of <em class="parameter"><code>start</code></em>
+ and <em class="parameter"><code>count</code></em>.
+ </p>
+ <p>
+ <code class="literal">substring('\x1234567890'::bytea from 3 for 2)</code>
+ → <code class="returnvalue">\x5678</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.5.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>]
+ <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> <code class="literal">FROM</code>
+ <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Removes the longest string containing only bytes appearing in
+ <em class="parameter"><code>bytesremoved</code></em> from the start,
+ end, or both ends (<code class="literal">BOTH</code> is the default)
+ of <em class="parameter"><code>bytes</code></em>.
+ </p>
+ <p>
+ <code class="literal">trim('\x9012'::bytea from '\x1234567890'::bytea)</code>
+ → <code class="returnvalue">\x345678</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>] [<span class="optional"> <code class="literal">FROM</code> </span>]
+ <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ This is a non-standard syntax for <code class="function">trim()</code>.
+ </p>
+ <p>
+ <code class="literal">trim(both from '\x1234567890'::bytea, '\x9012'::bytea)</code>
+ → <code class="returnvalue">\x345678</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Additional binary string manipulation functions are available and
+ are listed in <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-OTHER" title="Table 9.12. Other Binary String Functions">Table 9.12</a>. Some
+ of them are used internally to implement the
+ <acronym class="acronym">SQL</acronym>-standard string functions listed in <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-SQL" title="Table 9.11. SQL Binary String Functions and Operators">Table 9.11</a>.
+ </p><div class="table" id="FUNCTIONS-BINARYSTRING-OTHER"><p class="title"><strong>Table 9.12. Other Binary String Functions</strong></p><div class="table-contents"><table class="table" summary="Other Binary String Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.1.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.11.7.2.2.1.1.1.2" class="indexterm"></a>
+ <code class="function">bit_count</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the number of bits set in the binary string (also known as
+ <span class="quote">“<span class="quote">popcount</span>”</span>).
+ </p>
+ <p>
+ <code class="literal">bit_count('\x1234567890'::bytea)</code>
+ → <code class="returnvalue">15</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">btrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Removes the longest string containing only bytes appearing in
+ <em class="parameter"><code>bytesremoved</code></em> from the start and end of
+ <em class="parameter"><code>bytes</code></em>.
+ </p>
+ <p>
+ <code class="literal">btrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+ → <code class="returnvalue">\x345678</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">get_bit</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">bigint</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Extracts <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> bit
+ from binary string.
+ </p>
+ <p>
+ <code class="literal">get_bit('\x1234567890'::bytea, 30)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">get_byte</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Extracts <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> byte
+ from binary string.
+ </p>
+ <p>
+ <code class="literal">get_byte('\x1234567890'::bytea, 4)</code>
+ → <code class="returnvalue">144</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.5.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.11.7.2.2.5.1.1.2" class="indexterm"></a>
+ <a id="id-1.5.8.11.7.2.2.5.1.1.3" class="indexterm"></a>
+ <code class="function">length</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of bytes in the binary string.
+ </p>
+ <p>
+ <code class="literal">length('\x1234567890'::bytea)</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">length</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of characters in the binary string, assuming
+ that it is text in the given <em class="parameter"><code>encoding</code></em>.
+ </p>
+ <p>
+ <code class="literal">length('jose'::bytea, 'UTF8')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">ltrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Removes the longest string containing only bytes appearing in
+ <em class="parameter"><code>bytesremoved</code></em> from the start of
+ <em class="parameter"><code>bytes</code></em>.
+ </p>
+ <p>
+ <code class="literal">ltrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+ → <code class="returnvalue">\x34567890</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">md5</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Computes the MD5 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a> of
+ the binary string, with the result written in hexadecimal.
+ </p>
+ <p>
+ <code class="literal">md5('Th\000omas'::bytea)</code>
+ → <code class="returnvalue">8ab2d3c9689aaf18​b4958c334c82d8b1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">rtrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Removes the longest string containing only bytes appearing in
+ <em class="parameter"><code>bytesremoved</code></em> from the end of
+ <em class="parameter"><code>bytes</code></em>.
+ </p>
+ <p>
+ <code class="literal">rtrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+ → <code class="returnvalue">\x12345678</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">set_bit</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">bigint</code>,
+ <em class="parameter"><code>newvalue</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Sets <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> bit in
+ binary string to <em class="parameter"><code>newvalue</code></em>.
+ </p>
+ <p>
+ <code class="literal">set_bit('\x1234567890'::bytea, 30, 0)</code>
+ → <code class="returnvalue">\x1234563890</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">set_byte</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>newvalue</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Sets <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> byte in
+ binary string to <em class="parameter"><code>newvalue</code></em>.
+ </p>
+ <p>
+ <code class="literal">set_byte('\x1234567890'::bytea, 4, 64)</code>
+ → <code class="returnvalue">\x1234567840</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">sha224</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Computes the SHA-224 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+ of the binary string.
+ </p>
+ <p>
+ <code class="literal">sha224('abc'::bytea)</code>
+ → <code class="returnvalue">\x23097d223405d8228642a477bda2​55b32aadbce4bda0b3f7e36c9da7</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">sha256</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Computes the SHA-256 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+ of the binary string.
+ </p>
+ <p>
+ <code class="literal">sha256('abc'::bytea)</code>
+ → <code class="returnvalue">\xba7816bf8f01cfea414140de5dae2223​b00361a396177a9cb410ff61f20015ad</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">sha384</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Computes the SHA-384 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+ of the binary string.
+ </p>
+ <p>
+ <code class="literal">sha384('abc'::bytea)</code>
+ → <code class="returnvalue">\xcb00753f45a35e8bb5a03d699ac65007​272c32ab0eded1631a8b605a43ff5bed​8086072ba1e7cc2358baeca134c825a7</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">sha512</code> ( <code class="type">bytea</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Computes the SHA-512 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+ of the binary string.
+ </p>
+ <p>
+ <code class="literal">sha512('abc'::bytea)</code>
+ → <code class="returnvalue">\xddaf35a193617abacc417349ae204131​12e6fa4e89a97ea20a9eeee64b55d39a​2192992a274fc1a836ba3c23a3feebbd​454d4423643ce80e2a9ac94fa54ca49f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.7.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">substr</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional">, <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Extracts the substring of <em class="parameter"><code>bytes</code></em> starting at
+ the <em class="parameter"><code>start</code></em>'th byte,
+ and extending for <em class="parameter"><code>count</code></em> bytes if that is
+ specified. (Same
+ as <code class="literal">substring(<em class="parameter"><code>bytes</code></em>
+ from <em class="parameter"><code>start</code></em>
+ for <em class="parameter"><code>count</code></em>)</code>.)
+ </p>
+ <p>
+ <code class="literal">substr('\x1234567890'::bytea, 3, 2)</code>
+ → <code class="returnvalue">\x5678</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p id="FUNCTIONS-ZEROBASED-NOTE">
+ Functions <code class="function">get_byte</code> and <code class="function">set_byte</code>
+ number the first byte of a binary string as byte 0.
+ Functions <code class="function">get_bit</code> and <code class="function">set_bit</code>
+ number bits from the right within each byte; for example bit 0 is the least
+ significant bit of the first byte, and bit 15 is the most significant bit
+ of the second byte.
+ </p><p id="FUNCTIONS-HASH-NOTE">
+ For historical reasons, the function <code class="function">md5</code>
+ returns a hex-encoded value of type <code class="type">text</code> whereas the SHA-2
+ functions return type <code class="type">bytea</code>. Use the functions
+ <a class="link" href="functions-binarystring.html#FUNCTION-ENCODE"><code class="function">encode</code></a>
+ and <a class="link" href="functions-binarystring.html#FUNCTION-DECODE"><code class="function">decode</code></a> to
+ convert between the two. For example write <code class="literal">encode(sha256('abc'),
+ 'hex')</code> to get a hex-encoded text representation,
+ or <code class="literal">decode(md5('abc'), 'hex')</code> to get
+ a <code class="type">bytea</code> value.
+ </p><p>
+ <a id="id-1.5.8.11.10.1" class="indexterm"></a>
+ <a id="id-1.5.8.11.10.2" class="indexterm"></a>
+ Functions for converting strings between different character sets
+ (encodings), and for representing arbitrary binary data in textual
+ form, are shown in
+ <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-CONVERSIONS" title="Table 9.13. Text/Binary String Conversion Functions">Table 9.13</a>. For these
+ functions, an argument or result of type <code class="type">text</code> is expressed
+ in the database's default encoding, while arguments or results of
+ type <code class="type">bytea</code> are in an encoding named by another argument.
+ </p><div class="table" id="FUNCTIONS-BINARYSTRING-CONVERSIONS"><p class="title"><strong>Table 9.13. Text/Binary String Conversion Functions</strong></p><div class="table-contents"><table class="table" summary="Text/Binary String Conversion Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.11.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">convert</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>src_encoding</code></em> <code class="type">name</code>,
+ <em class="parameter"><code>dest_encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Converts a binary string representing text in
+ encoding <em class="parameter"><code>src_encoding</code></em>
+ to a binary string in encoding <em class="parameter"><code>dest_encoding</code></em>
+ (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+ available conversions).
+ </p>
+ <p>
+ <code class="literal">convert('text_in_utf8', 'UTF8', 'LATIN1')</code>
+ → <code class="returnvalue">\x746578745f696e5f75746638</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.11.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">convert_from</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>src_encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts a binary string representing text in
+ encoding <em class="parameter"><code>src_encoding</code></em>
+ to <code class="type">text</code> in the database encoding
+ (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+ available conversions).
+ </p>
+ <p>
+ <code class="literal">convert_from('text_in_utf8', 'UTF8')</code>
+ → <code class="returnvalue">text_in_utf8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.11.11.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">convert_to</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>dest_encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Converts a <code class="type">text</code> string (in the database encoding) to a
+ binary string encoded in encoding <em class="parameter"><code>dest_encoding</code></em>
+ (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+ available conversions).
+ </p>
+ <p>
+ <code class="literal">convert_to('some_text', 'UTF8')</code>
+ → <code class="returnvalue">\x736f6d655f74657874</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="FUNCTION-ENCODE" class="indexterm"></a>
+ <code class="function">encode</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+ <em class="parameter"><code>format</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Encodes binary data into a textual representation; supported
+ <em class="parameter"><code>format</code></em> values are:
+ <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-BASE64"><code class="literal">base64</code></a>,
+ <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-ESCAPE"><code class="literal">escape</code></a>,
+ <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-HEX"><code class="literal">hex</code></a>.
+ </p>
+ <p>
+ <code class="literal">encode('123\000\001', 'base64')</code>
+ → <code class="returnvalue">MTIzAAE=</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="FUNCTION-DECODE" class="indexterm"></a>
+ <code class="function">decode</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>format</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Decodes binary data from a textual representation; supported
+ <em class="parameter"><code>format</code></em> values are the same as
+ for <code class="function">encode</code>.
+ </p>
+ <p>
+ <code class="literal">decode('MTIzAAE=', 'base64')</code>
+ → <code class="returnvalue">\x3132330001</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="function">encode</code> and <code class="function">decode</code>
+ functions support the following textual formats:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="ENCODE-FORMAT-BASE64"><span class="term">base64
+ <a id="id-1.5.8.11.12.3.1.1.1" class="indexterm"></a></span></dt><dd><p>
+ The <code class="literal">base64</code> format is that
+ of <a class="ulink" href="https://tools.ietf.org/html/rfc2045#section-6.8" target="_top">RFC
+ 2045 Section 6.8</a>. As per the <acronym class="acronym">RFC</acronym>, encoded lines are
+ broken at 76 characters. However instead of the MIME CRLF
+ end-of-line marker, only a newline is used for end-of-line.
+ The <code class="function">decode</code> function ignores carriage-return,
+ newline, space, and tab characters. Otherwise, an error is
+ raised when <code class="function">decode</code> is supplied invalid
+ base64 data — including when trailing padding is incorrect.
+ </p></dd><dt id="ENCODE-FORMAT-ESCAPE"><span class="term">escape
+ <a id="id-1.5.8.11.12.3.2.1.1" class="indexterm"></a></span></dt><dd><p>
+ The <code class="literal">escape</code> format converts zero bytes and
+ bytes with the high bit set into octal escape sequences
+ (<code class="literal">\</code><em class="replaceable"><code>nnn</code></em>), and it doubles
+ backslashes. Other byte values are represented literally.
+ The <code class="function">decode</code> function will raise an error if a
+ backslash is not followed by either a second backslash or three
+ octal digits; it accepts other byte values unchanged.
+ </p></dd><dt id="ENCODE-FORMAT-HEX"><span class="term">hex
+ <a id="id-1.5.8.11.12.3.3.1.1" class="indexterm"></a></span></dt><dd><p>
+ The <code class="literal">hex</code> format represents each 4 bits of
+ data as one hexadecimal digit, <code class="literal">0</code>
+ through <code class="literal">f</code>, writing the higher-order digit of
+ each byte first. The <code class="function">encode</code> function outputs
+ the <code class="literal">a</code>-<code class="literal">f</code> hex digits in lower
+ case. Because the smallest unit of data is 8 bits, there are
+ always an even number of characters returned
+ by <code class="function">encode</code>.
+ The <code class="function">decode</code> function
+ accepts the <code class="literal">a</code>-<code class="literal">f</code> characters in
+ either upper or lower case. An error is raised
+ when <code class="function">decode</code> is given invalid hex data
+ — including when given an odd number of characters.
+ </p></dd></dl></div><p>
+ </p><p>
+ See also the aggregate function <code class="function">string_agg</code> in
+ <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> and the large object functions
+ in <a class="xref" href="lo-funcs.html" title="35.4. Server-Side Functions">Section 35.4</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-string.html" title="9.4. String Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.4. String Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.6. Bit String Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-bitstring.html b/doc/src/sgml/html/functions-bitstring.html
new file mode 100644
index 0000000..9a0ffe1
--- /dev/null
+++ b/doc/src/sgml/html/functions-bitstring.html
@@ -0,0 +1,235 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.6. Bit String Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators" /><link rel="next" href="functions-matching.html" title="9.7. Pattern Matching" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.6. Bit String Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-matching.html" title="9.7. Pattern Matching">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-BITSTRING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.6. Bit String Functions and Operators</h2></div></div></div><a id="id-1.5.8.12.2" class="indexterm"></a><p>
+ This section describes functions and operators for examining and
+ manipulating bit strings, that is values of the types
+ <code class="type">bit</code> and <code class="type">bit varying</code>. (While only
+ type <code class="type">bit</code> is mentioned in these tables, values of
+ type <code class="type">bit varying</code> can be used interchangeably.)
+ Bit strings support the usual comparison operators shown in
+ <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>, as well as the
+ operators shown in <a class="xref" href="functions-bitstring.html#FUNCTIONS-BIT-STRING-OP-TABLE" title="Table 9.14. Bit String Operators">Table 9.14</a>.
+ </p><div class="table" id="FUNCTIONS-BIT-STRING-OP-TABLE"><p class="title"><strong>Table 9.14. Bit String Operators</strong></p><div class="table-contents"><table class="table" summary="Bit String Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">||</code> <code class="type">bit</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Concatenation
+ </p>
+ <p>
+ <code class="literal">B'10001' || B'011'</code>
+ → <code class="returnvalue">10001011</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">&amp;</code> <code class="type">bit</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise AND (inputs must be of equal length)
+ </p>
+ <p>
+ <code class="literal">B'10001' &amp; B'01101'</code>
+ → <code class="returnvalue">00001</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">|</code> <code class="type">bit</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise OR (inputs must be of equal length)
+ </p>
+ <p>
+ <code class="literal">B'10001' | B'01101'</code>
+ → <code class="returnvalue">11101</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">#</code> <code class="type">bit</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise exclusive OR (inputs must be of equal length)
+ </p>
+ <p>
+ <code class="literal">B'10001' # B'01101'</code>
+ → <code class="returnvalue">11100</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">~</code> <code class="type">bit</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise NOT
+ </p>
+ <p>
+ <code class="literal">~ B'10001'</code>
+ → <code class="returnvalue">01110</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">&lt;&lt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise shift left
+ (string length is preserved)
+ </p>
+ <p>
+ <code class="literal">B'10001' &lt;&lt; 3</code>
+ → <code class="returnvalue">01000</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bit</code> <code class="literal">&gt;&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Bitwise shift right
+ (string length is preserved)
+ </p>
+ <p>
+ <code class="literal">B'10001' &gt;&gt; 2</code>
+ → <code class="returnvalue">00100</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Some of the functions available for binary strings are also available
+ for bit strings, as shown in <a class="xref" href="functions-bitstring.html#FUNCTIONS-BIT-STRING-TABLE" title="Table 9.15. Bit String Functions">Table 9.15</a>.
+ </p><div class="table" id="FUNCTIONS-BIT-STRING-TABLE"><p class="title"><strong>Table 9.15. Bit String Functions</strong></p><div class="table-contents"><table class="table" summary="Bit String Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">bit_count</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the number of bits set in the bit string (also known as
+ <span class="quote">“<span class="quote">popcount</span>”</span>).
+ </p>
+ <p>
+ <code class="literal">bit_count(B'10111')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">bit_length</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bits in the bit string.
+ </p>
+ <p>
+ <code class="literal">bit_length(B'10111')</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.3.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.12.6.2.2.3.1.1.2" class="indexterm"></a>
+ <code class="function">length</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bits in the bit string.
+ </p>
+ <p>
+ <code class="literal">length(B'10111')</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">octet_length</code> ( <code class="type">bit</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bytes in the bit string.
+ </p>
+ <p>
+ <code class="literal">octet_length(B'1011111011')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">overlay</code> ( <em class="parameter"><code>bits</code></em> <code class="type">bit</code> <code class="literal">PLACING</code> <em class="parameter"><code>newsubstring</code></em> <code class="type">bit</code> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Replaces the substring of <em class="parameter"><code>bits</code></em> that starts at
+ the <em class="parameter"><code>start</code></em>'th bit and extends
+ for <em class="parameter"><code>count</code></em> bits
+ with <em class="parameter"><code>newsubstring</code></em>.
+ If <em class="parameter"><code>count</code></em> is omitted, it defaults to the length
+ of <em class="parameter"><code>newsubstring</code></em>.
+ </p>
+ <p>
+ <code class="literal">overlay(B'01010101010101010' placing B'11111' from 2 for 3)</code>
+ → <code class="returnvalue">0111110101010101010</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">position</code> ( <em class="parameter"><code>substring</code></em> <code class="type">bit</code> <code class="literal">IN</code> <em class="parameter"><code>bits</code></em> <code class="type">bit</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns first starting index of the specified <em class="parameter"><code>substring</code></em>
+ within <em class="parameter"><code>bits</code></em>, or zero if it's not present.
+ </p>
+ <p>
+ <code class="literal">position(B'010' in B'000001101011')</code>
+ → <code class="returnvalue">8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">substring</code> ( <em class="parameter"><code>bits</code></em> <code class="type">bit</code> [<span class="optional"> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> </span>] [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Extracts the substring of <em class="parameter"><code>bits</code></em> starting at
+ the <em class="parameter"><code>start</code></em>'th bit if that is specified,
+ and stopping after <em class="parameter"><code>count</code></em> bits if that is
+ specified. Provide at least one of <em class="parameter"><code>start</code></em>
+ and <em class="parameter"><code>count</code></em>.
+ </p>
+ <p>
+ <code class="literal">substring(B'110010111111' from 3 for 2)</code>
+ → <code class="returnvalue">00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">get_bit</code> ( <em class="parameter"><code>bits</code></em> <code class="type">bit</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Extracts <em class="parameter"><code>n</code></em>'th bit
+ from bit string; the first (leftmost) bit is bit 0.
+ </p>
+ <p>
+ <code class="literal">get_bit(B'101010101010101010', 6)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.12.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">set_bit</code> ( <em class="parameter"><code>bits</code></em> <code class="type">bit</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>newvalue</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">bit</code>
+ </p>
+ <p>
+ Sets <em class="parameter"><code>n</code></em>'th bit in
+ bit string to <em class="parameter"><code>newvalue</code></em>;
+ the first (leftmost) bit is bit 0.
+ </p>
+ <p>
+ <code class="literal">set_bit(B'101010101010101010', 6, 0)</code>
+ → <code class="returnvalue">101010001010101010</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In addition, it is possible to cast integral values to and from type
+ <code class="type">bit</code>.
+ Casting an integer to <code class="type">bit(n)</code> copies the rightmost
+ <code class="literal">n</code> bits. Casting an integer to a bit string width wider
+ than the integer itself will sign-extend on the left.
+ Some examples:
+</p><pre class="programlisting">
+44::bit(10) <em class="lineannotation"><span class="lineannotation">0000101100</span></em>
+44::bit(3) <em class="lineannotation"><span class="lineannotation">100</span></em>
+cast(-44 as bit(12)) <em class="lineannotation"><span class="lineannotation">111111010100</span></em>
+'1110'::bit(4)::integer <em class="lineannotation"><span class="lineannotation">14</span></em>
+</pre><p>
+ Note that casting to just <span class="quote">“<span class="quote">bit</span>”</span> means casting to
+ <code class="literal">bit(1)</code>, and so will deliver only the least significant
+ bit of the integer.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-matching.html" title="9.7. Pattern Matching">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.5. Binary String Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.7. Pattern Matching</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-comparison.html b/doc/src/sgml/html/functions-comparison.html
new file mode 100644
index 0000000..9a4661c
--- /dev/null
+++ b/doc/src/sgml/html/functions-comparison.html
@@ -0,0 +1,400 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.2. Comparison Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-logical.html" title="9.1. Logical Operators" /><link rel="next" href="functions-math.html" title="9.3. Mathematical Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.2. Comparison Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-logical.html" title="9.1. Logical Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-math.html" title="9.3. Mathematical Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-COMPARISON"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.2. Comparison Functions and Operators</h2></div></div></div><a id="id-1.5.8.8.2" class="indexterm"></a><p>
+ The usual comparison operators are available, as shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>.
+ </p><div class="table" id="FUNCTIONS-COMPARISON-OP-TABLE"><p class="title"><strong>Table 9.1. Comparison Operators</strong></p><div class="table-contents"><table class="table" summary="Comparison Operators" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operator</th><th>Description</th></tr></thead><tbody><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Less than</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">&gt;</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Greater than</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">&lt;=</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Less than or equal to</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">&gt;=</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Greater than or equal to</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">=</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Equal</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">&lt;&gt;</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Not equal</td></tr><tr><td>
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">!=</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </td><td>Not equal</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">&lt;&gt;</code> is the standard SQL notation for <span class="quote">“<span class="quote">not
+ equal</span>”</span>. <code class="literal">!=</code> is an alias, which is converted
+ to <code class="literal">&lt;&gt;</code> at a very early stage of parsing.
+ Hence, it is not possible to implement <code class="literal">!=</code>
+ and <code class="literal">&lt;&gt;</code> operators that do different things.
+ </p></div><p>
+ These comparison operators are available for all built-in data types
+ that have a natural ordering, including numeric, string, and date/time
+ types. In addition, arrays, composite types, and ranges can be compared
+ if their component data types are comparable.
+ </p><p>
+ It is usually possible to compare values of related data
+ types as well; for example <code class="type">integer</code> <code class="literal">&gt;</code>
+ <code class="type">bigint</code> will work. Some cases of this sort are implemented
+ directly by <span class="quote">“<span class="quote">cross-type</span>”</span> comparison operators, but if no
+ such operator is available, the parser will coerce the less-general type
+ to the more-general type and apply the latter's comparison operator.
+ </p><p>
+ As shown above, all comparison operators are binary operators that
+ return values of type <code class="type">boolean</code>. Thus, expressions like
+ <code class="literal">1 &lt; 2 &lt; 3</code> are not valid (because there is
+ no <code class="literal">&lt;</code> operator to compare a Boolean value with
+ <code class="literal">3</code>). Use the <code class="literal">BETWEEN</code> predicates
+ shown below to perform range tests.
+ </p><p>
+ There are also some comparison predicates, as shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-PRED-TABLE" title="Table 9.2. Comparison Predicates">Table 9.2</a>. These behave much like
+ operators, but have special syntax mandated by the SQL standard.
+ </p><div class="table" id="FUNCTIONS-COMPARISON-PRED-TABLE"><p class="title"><strong>Table 9.2. Comparison Predicates</strong></p><div class="table-contents"><table class="table" summary="Comparison Predicates" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Predicate
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">BETWEEN</code> <em class="replaceable"><code>datatype</code></em> <code class="literal">AND</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Between (inclusive of the range endpoints).
+ </p>
+ <p>
+ <code class="literal">2 BETWEEN 1 AND 3</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">2 BETWEEN 3 AND 1</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">NOT BETWEEN</code> <em class="replaceable"><code>datatype</code></em> <code class="literal">AND</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Not between (the negation of <code class="literal">BETWEEN</code>).
+ </p>
+ <p>
+ <code class="literal">2 NOT BETWEEN 1 AND 3</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">BETWEEN SYMMETRIC</code> <em class="replaceable"><code>datatype</code></em> <code class="literal">AND</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Between, after sorting the two endpoint values.
+ </p>
+ <p>
+ <code class="literal">2 BETWEEN SYMMETRIC 3 AND 1</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">NOT BETWEEN SYMMETRIC</code> <em class="replaceable"><code>datatype</code></em> <code class="literal">AND</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Not between, after sorting the two endpoint values.
+ </p>
+ <p>
+ <code class="literal">2 NOT BETWEEN SYMMETRIC 3 AND 1</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">IS DISTINCT FROM</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Not equal, treating null as a comparable value.
+ </p>
+ <p>
+ <code class="literal">1 IS DISTINCT FROM NULL</code>
+ → <code class="returnvalue">t</code> (rather than <code class="literal">NULL</code>)
+ </p>
+ <p>
+ <code class="literal">NULL IS DISTINCT FROM NULL</code>
+ → <code class="returnvalue">f</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">IS NOT DISTINCT FROM</code> <em class="replaceable"><code>datatype</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Equal, treating null as a comparable value.
+ </p>
+ <p>
+ <code class="literal">1 IS NOT DISTINCT FROM NULL</code>
+ → <code class="returnvalue">f</code> (rather than <code class="literal">NULL</code>)
+ </p>
+ <p>
+ <code class="literal">NULL IS NOT DISTINCT FROM NULL</code>
+ → <code class="returnvalue">t</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">IS NULL</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether value is null.
+ </p>
+ <p>
+ <code class="literal">1.5 IS NULL</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">IS NOT NULL</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether value is not null.
+ </p>
+ <p>
+ <code class="literal">'null' IS NOT NULL</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">ISNULL</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether value is null (nonstandard syntax).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>datatype</code></em> <code class="literal">NOTNULL</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether value is not null (nonstandard syntax).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS TRUE</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields true.
+ </p>
+ <p>
+ <code class="literal">true IS TRUE</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS TRUE</code>
+ → <code class="returnvalue">f</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS NOT TRUE</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields false or unknown.
+ </p>
+ <p>
+ <code class="literal">true IS NOT TRUE</code>
+ → <code class="returnvalue">f</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS NOT TRUE</code>
+ → <code class="returnvalue">t</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS FALSE</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields false.
+ </p>
+ <p>
+ <code class="literal">true IS FALSE</code>
+ → <code class="returnvalue">f</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS FALSE</code>
+ → <code class="returnvalue">f</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS NOT FALSE</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields true or unknown.
+ </p>
+ <p>
+ <code class="literal">true IS NOT FALSE</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS NOT FALSE</code>
+ → <code class="returnvalue">t</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS UNKNOWN</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields unknown.
+ </p>
+ <p>
+ <code class="literal">true IS UNKNOWN</code>
+ → <code class="returnvalue">f</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS UNKNOWN</code>
+ → <code class="returnvalue">t</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">boolean</code> <code class="literal">IS NOT UNKNOWN</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test whether boolean expression yields true or false.
+ </p>
+ <p>
+ <code class="literal">true IS NOT UNKNOWN</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">NULL::boolean IS NOT UNKNOWN</code>
+ → <code class="returnvalue">f</code> (rather than <code class="literal">NULL</code>)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a id="id-1.5.8.8.11.1" class="indexterm"></a>
+ <a id="id-1.5.8.8.11.2" class="indexterm"></a>
+ The <code class="token">BETWEEN</code> predicate simplifies range tests:
+</p><pre class="synopsis">
+<em class="replaceable"><code>a</code></em> BETWEEN <em class="replaceable"><code>x</code></em> AND <em class="replaceable"><code>y</code></em>
+</pre><p>
+ is equivalent to
+</p><pre class="synopsis">
+<em class="replaceable"><code>a</code></em> &gt;= <em class="replaceable"><code>x</code></em> AND <em class="replaceable"><code>a</code></em> &lt;= <em class="replaceable"><code>y</code></em>
+</pre><p>
+ Notice that <code class="token">BETWEEN</code> treats the endpoint values as included
+ in the range.
+ <code class="literal">BETWEEN SYMMETRIC</code> is like <code class="literal">BETWEEN</code>
+ except there is no requirement that the argument to the left of
+ <code class="literal">AND</code> be less than or equal to the argument on the right.
+ If it is not, those two arguments are automatically swapped, so that
+ a nonempty range is always implied.
+ </p><p>
+ The various variants of <code class="literal">BETWEEN</code> are implemented in
+ terms of the ordinary comparison operators, and therefore will work for
+ any data type(s) that can be compared.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The use of <code class="literal">AND</code> in the <code class="literal">BETWEEN</code>
+ syntax creates an ambiguity with the use of <code class="literal">AND</code> as a
+ logical operator. To resolve this, only a limited set of expression
+ types are allowed as the second argument of a <code class="literal">BETWEEN</code>
+ clause. If you need to write a more complex sub-expression
+ in <code class="literal">BETWEEN</code>, write parentheses around the
+ sub-expression.
+ </p></div><p>
+ <a id="id-1.5.8.8.14.1" class="indexterm"></a>
+ <a id="id-1.5.8.8.14.2" class="indexterm"></a>
+ Ordinary comparison operators yield null (signifying <span class="quote">“<span class="quote">unknown</span>”</span>),
+ not true or false, when either input is null. For example,
+ <code class="literal">7 = NULL</code> yields null, as does <code class="literal">7 &lt;&gt; NULL</code>. When
+ this behavior is not suitable, use the
+ <code class="literal">IS [<span class="optional"> NOT </span>] DISTINCT FROM</code> predicates:
+</p><pre class="synopsis">
+<em class="replaceable"><code>a</code></em> IS DISTINCT FROM <em class="replaceable"><code>b</code></em>
+<em class="replaceable"><code>a</code></em> IS NOT DISTINCT FROM <em class="replaceable"><code>b</code></em>
+</pre><p>
+ For non-null inputs, <code class="literal">IS DISTINCT FROM</code> is
+ the same as the <code class="literal">&lt;&gt;</code> operator. However, if both
+ inputs are null it returns false, and if only one input is
+ null it returns true. Similarly, <code class="literal">IS NOT DISTINCT
+ FROM</code> is identical to <code class="literal">=</code> for non-null
+ inputs, but it returns true when both inputs are null, and false when only
+ one input is null. Thus, these predicates effectively act as though null
+ were a normal data value, rather than <span class="quote">“<span class="quote">unknown</span>”</span>.
+ </p><p>
+ <a id="id-1.5.8.8.15.1" class="indexterm"></a>
+ <a id="id-1.5.8.8.15.2" class="indexterm"></a>
+ <a id="id-1.5.8.8.15.3" class="indexterm"></a>
+ <a id="id-1.5.8.8.15.4" class="indexterm"></a>
+ To check whether a value is or is not null, use the predicates:
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> IS NULL
+<em class="replaceable"><code>expression</code></em> IS NOT NULL
+</pre><p>
+ or the equivalent, but nonstandard, predicates:
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> ISNULL
+<em class="replaceable"><code>expression</code></em> NOTNULL
+</pre><p>
+ <a id="id-1.5.8.8.15.7" class="indexterm"></a>
+ </p><p>
+ Do <span class="emphasis"><em>not</em></span> write
+ <code class="literal"><em class="replaceable"><code>expression</code></em> = NULL</code>
+ because <code class="literal">NULL</code> is not <span class="quote">“<span class="quote">equal to</span>”</span>
+ <code class="literal">NULL</code>. (The null value represents an unknown value,
+ and it is not known whether two unknown values are equal.)
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Some applications might expect that
+ <code class="literal"><em class="replaceable"><code>expression</code></em> = NULL</code>
+ returns true if <em class="replaceable"><code>expression</code></em> 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 <a class="xref" href="runtime-config-compatible.html#GUC-TRANSFORM-NULL-EQUALS">transform_null_equals</a>
+ configuration variable is available. If it is enabled,
+ <span class="productname">PostgreSQL</span> will convert <code class="literal">x =
+ NULL</code> clauses to <code class="literal">x IS NULL</code>.
+ </p></div><p>
+ If the <em class="replaceable"><code>expression</code></em> is row-valued, then
+ <code class="literal">IS NULL</code> is true when the row expression itself is null
+ or when all the row's fields are null, while
+ <code class="literal">IS NOT NULL</code> is true when the row expression itself is non-null
+ and all the row's fields are non-null. Because of this behavior,
+ <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> do not always return
+ inverse results for row-valued expressions; in particular, a row-valued
+ expression that contains both null and non-null fields will return false
+ for both tests. In some cases, it may be preferable to
+ write <em class="replaceable"><code>row</code></em> <code class="literal">IS DISTINCT FROM NULL</code>
+ or <em class="replaceable"><code>row</code></em> <code class="literal">IS NOT DISTINCT FROM NULL</code>,
+ which will simply check whether the overall row value is null without any
+ additional tests on the row fields.
+ </p><p>
+ <a id="id-1.5.8.8.19.1" class="indexterm"></a>
+ <a id="id-1.5.8.8.19.2" class="indexterm"></a>
+ <a id="id-1.5.8.8.19.3" class="indexterm"></a>
+ <a id="id-1.5.8.8.19.4" class="indexterm"></a>
+ <a id="id-1.5.8.8.19.5" class="indexterm"></a>
+ <a id="id-1.5.8.8.19.6" class="indexterm"></a>
+ Boolean values can also be tested using the predicates
+</p><pre class="synopsis">
+<em class="replaceable"><code>boolean_expression</code></em> IS TRUE
+<em class="replaceable"><code>boolean_expression</code></em> IS NOT TRUE
+<em class="replaceable"><code>boolean_expression</code></em> IS FALSE
+<em class="replaceable"><code>boolean_expression</code></em> IS NOT FALSE
+<em class="replaceable"><code>boolean_expression</code></em> IS UNKNOWN
+<em class="replaceable"><code>boolean_expression</code></em> IS NOT UNKNOWN
+</pre><p>
+ These will always return true or false, never a null value, even when the
+ operand is null.
+ A null input is treated as the logical value <span class="quote">“<span class="quote">unknown</span>”</span>.
+ Notice that <code class="literal">IS UNKNOWN</code> and <code class="literal">IS NOT UNKNOWN</code> are
+ effectively the same as <code class="literal">IS NULL</code> and
+ <code class="literal">IS NOT NULL</code>, respectively, except that the input
+ expression must be of Boolean type.
+ </p><p>
+ Some comparison-related functions are also available, as shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-FUNC-TABLE" title="Table 9.3. Comparison Functions">Table 9.3</a>.
+ </p><div class="table" id="FUNCTIONS-COMPARISON-FUNC-TABLE"><p class="title"><strong>Table 9.3. Comparison Functions</strong></p><div class="table-contents"><table class="table" summary="Comparison Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.8.21.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">num_nonnulls</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of non-null arguments.
+ </p>
+ <p>
+ <code class="literal">num_nonnulls(1, NULL, 2)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.8.21.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">num_nulls</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of null arguments.
+ </p>
+ <p>
+ <code class="literal">num_nulls(1, NULL, 2)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-logical.html" title="9.1. Logical Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-math.html" title="9.3. Mathematical Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.1. Logical Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.3. Mathematical Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-comparisons.html b/doc/src/sgml/html/functions-comparisons.html
new file mode 100644
index 0000000..c36de4c
--- /dev/null
+++ b/doc/src/sgml/html/functions-comparisons.html
@@ -0,0 +1,215 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.24. Row and Array Comparisons</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-subquery.html" title="9.23. Subquery Expressions" /><link rel="next" href="functions-srf.html" title="9.25. Set Returning Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.24. Row and Array Comparisons</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-subquery.html" title="9.23. Subquery Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-srf.html" title="9.25. Set Returning Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-COMPARISONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.24. Row and Array Comparisons</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-comparisons.html#FUNCTIONS-COMPARISONS-IN-SCALAR">9.24.1. <code class="literal">IN</code></a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.15">9.24.2. <code class="literal">NOT IN</code></a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.16">9.24.3. <code class="literal">ANY</code>/<code class="literal">SOME</code> (array)</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.17">9.24.4. <code class="literal">ALL</code> (array)</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#ROW-WISE-COMPARISON">9.24.5. Row Constructor Comparison</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#COMPOSITE-TYPE-COMPARISON">9.24.6. Composite Type Comparison</a></span></dt></dl></div><a id="id-1.5.8.30.2" class="indexterm"></a><a id="id-1.5.8.30.3" class="indexterm"></a><a id="id-1.5.8.30.4" class="indexterm"></a><a id="id-1.5.8.30.5" class="indexterm"></a><a id="id-1.5.8.30.6" class="indexterm"></a><a id="id-1.5.8.30.7" class="indexterm"></a><a id="id-1.5.8.30.8" class="indexterm"></a><a id="id-1.5.8.30.9" class="indexterm"></a><a id="id-1.5.8.30.10" class="indexterm"></a><a id="id-1.5.8.30.11" class="indexterm"></a><a id="id-1.5.8.30.12" class="indexterm"></a><p>
+ This section describes several specialized constructs for making
+ multiple comparisons between groups of values. These forms are
+ syntactically related to the subquery forms of the previous section,
+ but do not involve subqueries.
+ The forms involving array subexpressions are
+ <span class="productname">PostgreSQL</span> extensions; the rest are
+ <acronym class="acronym">SQL</acronym>-compliant.
+ All of the expression forms documented in this section return
+ Boolean (true/false) results.
+ </p><div class="sect2" id="FUNCTIONS-COMPARISONS-IN-SCALAR"><div class="titlepage"><div><div><h3 class="title">9.24.1. <code class="literal">IN</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> IN (<em class="replaceable"><code>value</code></em> [<span class="optional">, ...</span>])
+</pre><p>
+ The right-hand side is a parenthesized list
+ of expressions. The result is <span class="quote">“<span class="quote">true</span>”</span> if the left-hand expression's
+ result is equal to any of the right-hand expressions. This is a shorthand
+ notation for
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> = <em class="replaceable"><code>value1</code></em>
+OR
+<em class="replaceable"><code>expression</code></em> = <em class="replaceable"><code>value2</code></em>
+OR
+...
+</pre><p>
+ </p><p>
+ Note that if the left-hand expression yields null, or if there are
+ no equal right-hand values and at least one right-hand expression yields
+ null, the result of the <code class="token">IN</code> construct will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p></div><div class="sect2" id="id-1.5.8.30.15"><div class="titlepage"><div><div><h3 class="title">9.24.2. <code class="literal">NOT IN</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> NOT IN (<em class="replaceable"><code>value</code></em> [<span class="optional">, ...</span>])
+</pre><p>
+ The right-hand side is a parenthesized list
+ of expressions. The result is <span class="quote">“<span class="quote">true</span>”</span> if the left-hand expression's
+ result is unequal to all of the right-hand expressions. This is a shorthand
+ notation for
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> &lt;&gt; <em class="replaceable"><code>value1</code></em>
+AND
+<em class="replaceable"><code>expression</code></em> &lt;&gt; <em class="replaceable"><code>value2</code></em>
+AND
+...
+</pre><p>
+ </p><p>
+ Note that if the left-hand expression yields null, or if there are
+ no equal right-hand values and at least one right-hand expression yields
+ null, the result of the <code class="token">NOT IN</code> construct will be null, not true
+ as one might naively expect.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <code class="literal">x NOT IN y</code> is equivalent to <code class="literal">NOT (x IN y)</code> in all
+ cases. However, null values are much more likely to trip up the novice when
+ working with <code class="token">NOT IN</code> than when working with <code class="token">IN</code>.
+ It is best to express your condition positively if possible.
+ </p></div></div><div class="sect2" id="id-1.5.8.30.16"><div class="titlepage"><div><div><h3 class="title">9.24.3. <code class="literal">ANY</code>/<code class="literal">SOME</code> (array)</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> ANY (<em class="replaceable"><code>array expression</code></em>)
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> SOME (<em class="replaceable"><code>array expression</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized expression, which must yield an
+ array value.
+ The left-hand expression
+ is evaluated and compared to each element of the array using the
+ given <em class="replaceable"><code>operator</code></em>, which must yield a Boolean
+ result.
+ The result of <code class="token">ANY</code> is <span class="quote">“<span class="quote">true</span>”</span> if any true result is obtained.
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if no true result is found (including the
+ case where the array has zero elements).
+ </p><p>
+ If the array expression yields a null array, the result of
+ <code class="token">ANY</code> will be null. If the left-hand expression yields null,
+ the result of <code class="token">ANY</code> is ordinarily null (though a non-strict
+ comparison operator could possibly yield a different result).
+ Also, if the right-hand array contains any null elements and no true
+ comparison result is obtained, the result of <code class="token">ANY</code>
+ will be null, not false (again, assuming a strict comparison operator).
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p><p>
+ <code class="token">SOME</code> is a synonym for <code class="token">ANY</code>.
+ </p></div><div class="sect2" id="id-1.5.8.30.17"><div class="titlepage"><div><div><h3 class="title">9.24.4. <code class="literal">ALL</code> (array)</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> ALL (<em class="replaceable"><code>array expression</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized expression, which must yield an
+ array value.
+ The left-hand expression
+ is evaluated and compared to each element of the array using the
+ given <em class="replaceable"><code>operator</code></em>, which must yield a Boolean
+ result.
+ The result of <code class="token">ALL</code> is <span class="quote">“<span class="quote">true</span>”</span> if all comparisons yield true
+ (including the case where the array has zero elements).
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if any false result is found.
+ </p><p>
+ If the array expression yields a null array, the result of
+ <code class="token">ALL</code> will be null. If the left-hand expression yields null,
+ the result of <code class="token">ALL</code> is ordinarily null (though a non-strict
+ comparison operator could possibly yield a different result).
+ Also, if the right-hand array contains any null elements and no false
+ comparison result is obtained, the result of <code class="token">ALL</code>
+ will be null, not true (again, assuming a strict comparison operator).
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p></div><div class="sect2" id="ROW-WISE-COMPARISON"><div class="titlepage"><div><div><h3 class="title">9.24.5. Row Constructor Comparison</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> <em class="replaceable"><code>operator</code></em> <em class="replaceable"><code>row_constructor</code></em>
+</pre><p>
+ Each side is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ The two row constructors must have the same number of fields.
+ The given <em class="replaceable"><code>operator</code></em> is applied to each pair
+ of corresponding fields. (Since the fields could be of different
+ types, this means that a different specific operator could be selected
+ for each pair.)
+ All the selected operators must be members of some B-tree operator
+ class, or be the negator of an <code class="literal">=</code> member of a B-tree
+ operator class, meaning that row constructor comparison is only
+ possible when the <em class="replaceable"><code>operator</code></em> is
+ <code class="literal">=</code>,
+ <code class="literal">&lt;&gt;</code>,
+ <code class="literal">&lt;</code>,
+ <code class="literal">&lt;=</code>,
+ <code class="literal">&gt;</code>, or
+ <code class="literal">&gt;=</code>,
+ or has semantics similar to one of these.
+ </p><p>
+ The <code class="literal">=</code> and <code class="literal">&lt;&gt;</code> cases work slightly differently
+ from the others. Two rows are considered
+ equal if all their corresponding members are non-null and equal; the rows
+ are unequal if any corresponding members are non-null and unequal;
+ otherwise the result of the row comparison is unknown (null).
+ </p><p>
+ For the <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">&gt;</code> and
+ <code class="literal">&gt;=</code> cases, the row elements are compared left-to-right,
+ stopping as soon as an unequal or null pair of elements is found.
+ If either of this pair of elements is null, the result of the
+ row comparison is unknown (null); otherwise comparison of this pair
+ of elements determines the result. For example,
+ <code class="literal">ROW(1,2,NULL) &lt; ROW(1,3,0)</code>
+ yields true, not null, because the third pair of elements are not
+ considered.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> 8.2, the
+ <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">&gt;</code> and <code class="literal">&gt;=</code>
+ cases were not handled per SQL specification. A comparison like
+ <code class="literal">ROW(a,b) &lt; ROW(c,d)</code>
+ was implemented as
+ <code class="literal">a &lt; c AND b &lt; d</code>
+ whereas the correct behavior is equivalent to
+ <code class="literal">a &lt; c OR (a = c AND b &lt; d)</code>.
+ </p></div><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> IS DISTINCT FROM <em class="replaceable"><code>row_constructor</code></em>
+</pre><p>
+ This construct is similar to a <code class="literal">&lt;&gt;</code> row comparison,
+ but it does not yield null for null inputs. Instead, any null value is
+ considered unequal to (distinct from) any non-null value, and any two
+ nulls are considered equal (not distinct). Thus the result will
+ either be true or false, never null.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> IS NOT DISTINCT FROM <em class="replaceable"><code>row_constructor</code></em>
+</pre><p>
+ This construct is similar to a <code class="literal">=</code> row comparison,
+ but it does not yield null for null inputs. Instead, any null value is
+ considered unequal to (distinct from) any non-null value, and any two
+ nulls are considered equal (not distinct). Thus the result will always
+ be either true or false, never null.
+ </p></div><div class="sect2" id="COMPOSITE-TYPE-COMPARISON"><div class="titlepage"><div><div><h3 class="title">9.24.6. Composite Type Comparison</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>record</code></em> <em class="replaceable"><code>operator</code></em> <em class="replaceable"><code>record</code></em>
+</pre><p>
+ The SQL specification requires row-wise comparison to return NULL if the
+ result depends on comparing two NULL values or a NULL and a non-NULL.
+ <span class="productname">PostgreSQL</span> does this only when comparing the
+ results of two row constructors (as in
+ <a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a>) or comparing a row constructor
+ to the output of a subquery (as in <a class="xref" href="functions-subquery.html" title="9.23. Subquery Expressions">Section 9.23</a>).
+ 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
+ and indexing behavior for composite types.
+ </p><p>
+ Each side is evaluated and they are compared row-wise. Composite type
+ comparisons are allowed when the <em class="replaceable"><code>operator</code></em> is
+ <code class="literal">=</code>,
+ <code class="literal">&lt;&gt;</code>,
+ <code class="literal">&lt;</code>,
+ <code class="literal">&lt;=</code>,
+ <code class="literal">&gt;</code> or
+ <code class="literal">&gt;=</code>,
+ or has semantics similar to one of these. (To be specific, an operator
+ can be a row comparison operator if it is a member of a B-tree operator
+ class, or is the negator of the <code class="literal">=</code> member of a B-tree operator
+ class.) The default behavior of the above operators is the same as for
+ <code class="literal">IS [ NOT ] DISTINCT FROM</code> for row constructors (see
+ <a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a>).
+ </p><p>
+ To support matching of rows which include elements without a default
+ B-tree operator class, the following operators are defined for composite
+ type comparison:
+ <code class="literal">*=</code>,
+ <code class="literal">*&lt;&gt;</code>,
+ <code class="literal">*&lt;</code>,
+ <code class="literal">*&lt;=</code>,
+ <code class="literal">*&gt;</code>, and
+ <code class="literal">*&gt;=</code>.
+ These operators compare the internal binary representation of the two
+ rows. Two rows might have a different binary representation even
+ though comparisons of the two rows with the equality operator is true.
+ The ordering of rows under these comparison operators is deterministic
+ but not otherwise meaningful. These operators are used internally
+ for materialized views and might be useful for other specialized
+ purposes such as replication and B-Tree deduplication (see <a class="xref" href="btree-implementation.html#BTREE-DEDUPLICATION" title="67.4.3. Deduplication">Section 67.4.3</a>). They are not intended to be
+ generally useful for writing queries, though.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-subquery.html" title="9.23. Subquery Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-srf.html" title="9.25. Set Returning Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.23. Subquery Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.25. Set Returning Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-conditional.html b/doc/src/sgml/html/functions-conditional.html
new file mode 100644
index 0000000..0ce4001
--- /dev/null
+++ b/doc/src/sgml/html/functions-conditional.html
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.18. Conditional Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions" /><link rel="next" href="functions-array.html" title="9.19. Array Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.18. Conditional Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-array.html" title="9.19. Array Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-CONDITIONAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.18. Conditional Expressions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-CASE">9.18.1. <code class="literal">CASE</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-COALESCE-NVL-IFNULL">9.18.2. <code class="literal">COALESCE</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-NULLIF">9.18.3. <code class="literal">NULLIF</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-GREATEST-LEAST">9.18.4. <code class="literal">GREATEST</code> and <code class="literal">LEAST</code></a></span></dt></dl></div><a id="id-1.5.8.24.2" class="indexterm"></a><a id="id-1.5.8.24.3" class="indexterm"></a><p>
+ This section describes the <acronym class="acronym">SQL</acronym>-compliant conditional expressions
+ available in <span class="productname">PostgreSQL</span>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If your needs go beyond the capabilities of these conditional
+ expressions, you might want to consider writing a server-side function
+ in a more expressive programming language.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Although <code class="token">COALESCE</code>, <code class="token">GREATEST</code>, and
+ <code class="token">LEAST</code> are syntactically similar to functions, they are
+ not ordinary functions, and thus cannot be used with explicit
+ <code class="token">VARIADIC</code> array arguments.
+ </p></div><div class="sect2" id="FUNCTIONS-CASE"><div class="titlepage"><div><div><h3 class="title">9.18.1. <code class="literal">CASE</code></h3></div></div></div><p>
+ The <acronym class="acronym">SQL</acronym> <code class="token">CASE</code> expression is a
+ generic conditional expression, similar to if/else statements in
+ other programming languages:
+
+</p><pre class="synopsis">
+CASE WHEN <em class="replaceable"><code>condition</code></em> THEN <em class="replaceable"><code>result</code></em>
+ [<span class="optional">WHEN ...</span>]
+ [<span class="optional">ELSE <em class="replaceable"><code>result</code></em></span>]
+END
+</pre><p>
+
+ <code class="token">CASE</code> clauses can be used wherever
+ an expression is valid. Each <em class="replaceable"><code>condition</code></em> is an
+ expression that returns a <code class="type">boolean</code> result. If the condition's
+ result is true, the value of the <code class="token">CASE</code> expression is the
+ <em class="replaceable"><code>result</code></em> that follows the condition, and the
+ remainder of the <code class="token">CASE</code> expression is not processed. If the
+ condition's result is not true, any subsequent <code class="token">WHEN</code> clauses
+ are examined in the same manner. If no <code class="token">WHEN</code>
+ <em class="replaceable"><code>condition</code></em> yields true, the value of the
+ <code class="token">CASE</code> expression is the <em class="replaceable"><code>result</code></em> of the
+ <code class="token">ELSE</code> clause. If the <code class="token">ELSE</code> clause is
+ omitted and no condition is true, the result is null.
+ </p><p>
+ An example:
+</p><pre class="screen">
+SELECT * FROM test;
+
+ a
+---
+ 1
+ 2
+ 3
+
+
+SELECT a,
+ CASE WHEN a=1 THEN 'one'
+ WHEN a=2 THEN 'two'
+ ELSE 'other'
+ END
+ FROM test;
+
+ a | case
+---+-------
+ 1 | one
+ 2 | two
+ 3 | other
+</pre><p>
+ </p><p>
+ The data types of all the <em class="replaceable"><code>result</code></em>
+ expressions must be convertible to a single output type.
+ See <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a> for more details.
+ </p><p>
+ There is a <span class="quote">“<span class="quote">simple</span>”</span> form of <code class="token">CASE</code> expression
+ that is a variant of the general form above:
+
+</p><pre class="synopsis">
+CASE <em class="replaceable"><code>expression</code></em>
+ WHEN <em class="replaceable"><code>value</code></em> THEN <em class="replaceable"><code>result</code></em>
+ [<span class="optional">WHEN ...</span>]
+ [<span class="optional">ELSE <em class="replaceable"><code>result</code></em></span>]
+END
+</pre><p>
+
+ The first
+ <em class="replaceable"><code>expression</code></em> is computed, then compared to
+ each of the <em class="replaceable"><code>value</code></em> expressions in the
+ <code class="token">WHEN</code> clauses until one is found that is equal to it. If
+ no match is found, the <em class="replaceable"><code>result</code></em> of the
+ <code class="token">ELSE</code> clause (or a null value) is returned. This is similar
+ to the <code class="function">switch</code> statement in C.
+ </p><p>
+ The example above can be written using the simple
+ <code class="token">CASE</code> syntax:
+</p><pre class="screen">
+SELECT a,
+ CASE a WHEN 1 THEN 'one'
+ WHEN 2 THEN 'two'
+ ELSE 'other'
+ END
+ FROM test;
+
+ a | case
+---+-------
+ 1 | one
+ 2 | two
+ 3 | other
+</pre><p>
+ </p><p>
+ A <code class="token">CASE</code> expression does not evaluate any subexpressions
+ that are not needed to determine the result. For example, this is a
+ possible way of avoiding a division-by-zero failure:
+</p><pre class="programlisting">
+SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ As described in <a class="xref" href="sql-expressions.html#SYNTAX-EXPRESS-EVAL" title="4.2.14. Expression Evaluation Rules">Section 4.2.14</a>, there are various
+ situations in which subexpressions of an expression are evaluated at
+ different times, so that the principle that <span class="quote">“<span class="quote"><code class="token">CASE</code>
+ evaluates only necessary subexpressions</span>”</span> is not ironclad. For
+ example a constant <code class="literal">1/0</code> subexpression will usually result in
+ a division-by-zero failure at planning time, even if it's within
+ a <code class="token">CASE</code> arm that would never be entered at run time.
+ </p></div></div><div class="sect2" id="FUNCTIONS-COALESCE-NVL-IFNULL"><div class="titlepage"><div><div><h3 class="title">9.18.2. <code class="literal">COALESCE</code></h3></div></div></div><a id="id-1.5.8.24.8.2" class="indexterm"></a><a id="id-1.5.8.24.8.3" class="indexterm"></a><a id="id-1.5.8.24.8.4" class="indexterm"></a><pre class="synopsis">
+<code class="function">COALESCE</code>(<em class="replaceable"><code>value</code></em> [<span class="optional">, ...</span>])
+</pre><p>
+ The <code class="function">COALESCE</code> function returns the first of its
+ arguments that is not null. Null is returned only if all arguments
+ are null. It is often used to substitute a default value for
+ null values when data is retrieved for display, for example:
+</p><pre class="programlisting">
+SELECT COALESCE(description, short_description, '(none)') ...
+</pre><p>
+ This returns <code class="varname">description</code> if it is not null, otherwise
+ <code class="varname">short_description</code> if it is not null, otherwise <code class="literal">(none)</code>.
+ </p><p>
+ The arguments must all be convertible to a common data type, which
+ will be the type of the result (see
+ <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a> for details).
+ </p><p>
+ Like a <code class="token">CASE</code> expression, <code class="function">COALESCE</code> only
+ evaluates the arguments that are needed to determine the result;
+ that is, arguments to the right of the first non-null argument are
+ not evaluated. This SQL-standard function provides capabilities similar
+ to <code class="function">NVL</code> and <code class="function">IFNULL</code>, which are used in some other
+ database systems.
+ </p></div><div class="sect2" id="FUNCTIONS-NULLIF"><div class="titlepage"><div><div><h3 class="title">9.18.3. <code class="literal">NULLIF</code></h3></div></div></div><a id="id-1.5.8.24.9.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">NULLIF</code>(<em class="replaceable"><code>value1</code></em>, <em class="replaceable"><code>value2</code></em>)
+</pre><p>
+ The <code class="function">NULLIF</code> function returns a null value if
+ <em class="replaceable"><code>value1</code></em> equals <em class="replaceable"><code>value2</code></em>;
+ otherwise it returns <em class="replaceable"><code>value1</code></em>.
+ This can be used to perform the inverse operation of the
+ <code class="function">COALESCE</code> example given above:
+</p><pre class="programlisting">
+SELECT NULLIF(value, '(none)') ...
+</pre><p>
+ In this example, if <code class="literal">value</code> is <code class="literal">(none)</code>,
+ null is returned, otherwise the value of <code class="literal">value</code>
+ is returned.
+ </p><p>
+ The two arguments must be of comparable types.
+ To be specific, they are compared exactly as if you had
+ written <code class="literal"><em class="replaceable"><code>value1</code></em>
+ = <em class="replaceable"><code>value2</code></em></code>, so there must be a
+ suitable <code class="literal">=</code> operator available.
+ </p><p>
+ The result has the same type as the first argument — but there is
+ a subtlety. What is actually returned is the first argument of the
+ implied <code class="literal">=</code> operator, and in some cases that will have
+ been promoted to match the second argument's type. For
+ example, <code class="literal">NULLIF(1, 2.2)</code> yields <code class="type">numeric</code>,
+ because there is no <code class="type">integer</code> <code class="literal">=</code>
+ <code class="type">numeric</code> operator,
+ only <code class="type">numeric</code> <code class="literal">=</code> <code class="type">numeric</code>.
+ </p></div><div class="sect2" id="FUNCTIONS-GREATEST-LEAST"><div class="titlepage"><div><div><h3 class="title">9.18.4. <code class="literal">GREATEST</code> and <code class="literal">LEAST</code></h3></div></div></div><a id="id-1.5.8.24.10.2" class="indexterm"></a><a id="id-1.5.8.24.10.3" class="indexterm"></a><pre class="synopsis">
+<code class="function">GREATEST</code>(<em class="replaceable"><code>value</code></em> [<span class="optional">, ...</span>])
+</pre><pre class="synopsis">
+<code class="function">LEAST</code>(<em class="replaceable"><code>value</code></em> [<span class="optional">, ...</span>])
+</pre><p>
+ The <code class="function">GREATEST</code> and <code class="function">LEAST</code> functions select the
+ 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 <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a> for details). NULL values
+ in the list are ignored. The result will be NULL only if all the
+ expressions evaluate to NULL.
+ </p><p>
+ Note that <code class="function">GREATEST</code> and <code class="function">LEAST</code> are not in
+ the SQL standard, but are a common extension. Some other databases
+ make them return NULL if any argument is NULL, rather than only when
+ all are NULL.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-array.html" title="9.19. Array Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.17. Sequence Manipulation Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.19. Array Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-datetime.html b/doc/src/sgml/html/functions-datetime.html
new file mode 100644
index 0000000..a5b5eed
--- /dev/null
+++ b/doc/src/sgml/html/functions-datetime.html
@@ -0,0 +1,1316 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.9. Date/Time Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-formatting.html" title="9.8. Data Type Formatting Functions" /><link rel="next" href="functions-enum.html" title="9.10. Enum Support Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.9. Date/Time Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-enum.html" title="9.10. Enum Support Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-DATETIME"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.9. Date/Time Functions and Operators</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT">9.9.1. <code class="function">EXTRACT</code>, <code class="function">date_part</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC">9.9.2. <code class="function">date_trunc</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-BIN">9.9.3. <code class="function">date_bin</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT">9.9.4. <code class="literal">AT TIME ZONE</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT">9.9.5. Current Date/Time</a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">9.9.6. Delaying Execution</a></span></dt></dl></div><p>
+ <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TABLE" title="Table 9.33. Date/Time Functions">Table 9.33</a> shows the available
+ functions for date/time value processing, with details appearing in
+ the following subsections. <a class="xref" href="functions-datetime.html#OPERATORS-DATETIME-TABLE" title="Table 9.32. Date/Time Operators">Table 9.32</a> illustrates the behaviors of
+ the basic arithmetic operators (<code class="literal">+</code>,
+ <code class="literal">*</code>, etc.). For formatting functions, refer to
+ <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>. You should be familiar with
+ the background information on date/time data types from <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a>.
+ </p><p>
+ In addition, the usual comparison operators shown in
+ <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for the
+ date/time types. Dates and timestamps (with or without time zone) are
+ all comparable, while times (with or without time zone) and intervals
+ can only be compared to other values of the same data type. When
+ comparing a timestamp without time zone to a timestamp with time zone,
+ the former value is assumed to be given in the time zone specified by
+ the <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> configuration parameter, and is
+ rotated to UTC for comparison to the latter value (which is already
+ in UTC internally). Similarly, a date value is assumed to represent
+ midnight in the <code class="varname">TimeZone</code> zone when comparing it
+ to a timestamp.
+ </p><p>
+ All the functions and operators described below that take <code class="type">time</code> or <code class="type">timestamp</code>
+ inputs actually come in two variants: one that takes <code class="type">time with time zone</code> or <code class="type">timestamp
+ with time zone</code>, and one that takes <code class="type">time without time zone</code> or <code class="type">timestamp without time zone</code>.
+ For brevity, these variants are not shown separately. Also, the
+ <code class="literal">+</code> and <code class="literal">*</code> operators come in commutative pairs (for
+ example both <code class="type">date</code> <code class="literal">+</code> <code class="type">integer</code>
+ and <code class="type">integer</code> <code class="literal">+</code> <code class="type">date</code>); we show
+ only one of each such pair.
+ </p><div class="table" id="OPERATORS-DATETIME-TABLE"><p class="title"><strong>Table 9.32. Date/Time Operators</strong></p><div class="table-contents"><table class="table" summary="Date/Time Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">+</code> <code class="type">integer</code>
+ → <code class="returnvalue">date</code>
+ </p>
+ <p>
+ Add a number of days to a date
+ </p>
+ <p>
+ <code class="literal">date '2001-09-28' + 7</code>
+ → <code class="returnvalue">2001-10-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">+</code> <code class="type">interval</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Add an interval to a date
+ </p>
+ <p>
+ <code class="literal">date '2001-09-28' + interval '1 hour'</code>
+ → <code class="returnvalue">2001-09-28 01:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">+</code> <code class="type">time</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Add a time-of-day to a date
+ </p>
+ <p>
+ <code class="literal">date '2001-09-28' + time '03:00'</code>
+ → <code class="returnvalue">2001-09-28 03:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">interval</code> <code class="literal">+</code> <code class="type">interval</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Add intervals
+ </p>
+ <p>
+ <code class="literal">interval '1 day' + interval '1 hour'</code>
+ → <code class="returnvalue">1 day 01:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">timestamp</code> <code class="literal">+</code> <code class="type">interval</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Add an interval to a timestamp
+ </p>
+ <p>
+ <code class="literal">timestamp '2001-09-28 01:00' + interval '23 hours'</code>
+ → <code class="returnvalue">2001-09-29 00:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">time</code> <code class="literal">+</code> <code class="type">interval</code>
+ → <code class="returnvalue">time</code>
+ </p>
+ <p>
+ Add an interval to a time
+ </p>
+ <p>
+ <code class="literal">time '01:00' + interval '3 hours'</code>
+ → <code class="returnvalue">04:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">-</code> <code class="type">interval</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Negate an interval
+ </p>
+ <p>
+ <code class="literal">- interval '23 hours'</code>
+ → <code class="returnvalue">-23:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">-</code> <code class="type">date</code>
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Subtract dates, producing the number of days elapsed
+ </p>
+ <p>
+ <code class="literal">date '2001-10-01' - date '2001-09-28'</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">-</code> <code class="type">integer</code>
+ → <code class="returnvalue">date</code>
+ </p>
+ <p>
+ Subtract a number of days from a date
+ </p>
+ <p>
+ <code class="literal">date '2001-10-01' - 7</code>
+ → <code class="returnvalue">2001-09-24</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">date</code> <code class="literal">-</code> <code class="type">interval</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Subtract an interval from a date
+ </p>
+ <p>
+ <code class="literal">date '2001-09-28' - interval '1 hour'</code>
+ → <code class="returnvalue">2001-09-27 23:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">time</code> <code class="literal">-</code> <code class="type">time</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Subtract times
+ </p>
+ <p>
+ <code class="literal">time '05:00' - time '03:00'</code>
+ → <code class="returnvalue">02:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">time</code> <code class="literal">-</code> <code class="type">interval</code>
+ → <code class="returnvalue">time</code>
+ </p>
+ <p>
+ Subtract an interval from a time
+ </p>
+ <p>
+ <code class="literal">time '05:00' - interval '2 hours'</code>
+ → <code class="returnvalue">03:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">timestamp</code> <code class="literal">-</code> <code class="type">interval</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Subtract an interval from a timestamp
+ </p>
+ <p>
+ <code class="literal">timestamp '2001-09-28 23:00' - interval '23 hours'</code>
+ → <code class="returnvalue">2001-09-28 00:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">interval</code> <code class="literal">-</code> <code class="type">interval</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Subtract intervals
+ </p>
+ <p>
+ <code class="literal">interval '1 day' - interval '1 hour'</code>
+ → <code class="returnvalue">1 day -01:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">timestamp</code> <code class="literal">-</code> <code class="type">timestamp</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Subtract timestamps (converting 24-hour intervals into days,
+ similarly to <code class="function">justify_hours()</code>)
+ </p>
+ <p>
+ <code class="literal">timestamp '2001-09-29 03:00' - timestamp '2001-07-27 12:00'</code>
+ → <code class="returnvalue">63 days 15:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">interval</code> <code class="literal">*</code> <code class="type">double precision</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Multiply an interval by a scalar
+ </p>
+ <p>
+ <code class="literal">interval '1 second' * 900</code>
+ → <code class="returnvalue">00:15:00</code>
+ </p>
+ <p>
+ <code class="literal">interval '1 day' * 21</code>
+ → <code class="returnvalue">21 days</code>
+ </p>
+ <p>
+ <code class="literal">interval '1 hour' * 3.5</code>
+ → <code class="returnvalue">03:30:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">interval</code> <code class="literal">/</code> <code class="type">double precision</code>
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Divide an interval by a scalar
+ </p>
+ <p>
+ <code class="literal">interval '1 hour' / 1.5</code>
+ → <code class="returnvalue">00:40:00</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-DATETIME-TABLE"><p class="title"><strong>Table 9.33. Date/Time Functions</strong></p><div class="table-contents"><table class="table" summary="Date/Time Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">age</code> ( <code class="type">timestamp</code>, <code class="type">timestamp</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Subtract arguments, producing a <span class="quote">“<span class="quote">symbolic</span>”</span> result that
+ uses years and months, rather than just days
+ </p>
+ <p>
+ <code class="literal">age(timestamp '2001-04-10', timestamp '1957-06-13')</code>
+ → <code class="returnvalue">43 years 9 mons 27 days</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">age</code> ( <code class="type">timestamp</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Subtract argument from <code class="function">current_date</code> (at midnight)
+ </p>
+ <p>
+ <code class="literal">age(timestamp '1957-06-13')</code>
+ → <code class="returnvalue">62 years 6 mons 10 days</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">clock_timestamp</code> ( )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (changes during statement execution);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">clock_timestamp()</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">current_date</code>
+ → <code class="returnvalue">date</code>
+ </p>
+ <p>
+ Current date; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">current_date</code>
+ → <code class="returnvalue">2019-12-23</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">current_time</code>
+ → <code class="returnvalue">time with time zone</code>
+ </p>
+ <p>
+ Current time of day; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">current_time</code>
+ → <code class="returnvalue">14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">current_time</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">time with time zone</code>
+ </p>
+ <p>
+ Current time of day, with limited precision;
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">current_time(2)</code>
+ → <code class="returnvalue">14:39:53.66-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">current_timestamp</code>
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (start of current transaction);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">current_timestamp</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">current_timestamp</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (start of current transaction), with limited precision;
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">current_timestamp(0)</code>
+ → <code class="returnvalue">2019-12-23 14:39:53-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">date_bin</code> ( <code class="type">interval</code>, <code class="type">timestamp</code>, <code class="type">timestamp</code> )
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Bin input into specified interval aligned with specified origin; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-BIN" title="9.9.3. date_bin">Section 9.9.3</a>
+ </p>
+ <p>
+ <code class="literal">date_bin('15 minutes', timestamp '2001-02-16 20:38:40', timestamp '2001-02-16 20:05:00')</code>
+ → <code class="returnvalue">2001-02-16 20:35:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">date_part</code> ( <code class="type">text</code>, <code class="type">timestamp</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Get timestamp subfield (equivalent to <code class="function">extract</code>);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
+ </p>
+ <p>
+ <code class="literal">date_part('hour', timestamp '2001-02-16 20:38:40')</code>
+ → <code class="returnvalue">20</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">date_part</code> ( <code class="type">text</code>, <code class="type">interval</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Get interval subfield (equivalent to <code class="function">extract</code>);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
+ </p>
+ <p>
+ <code class="literal">date_part('month', interval '2 years 3 months')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">timestamp</code> )
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Truncate to specified precision; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
+ </p>
+ <p>
+ <code class="literal">date_trunc('hour', timestamp '2001-02-16 20:38:40')</code>
+ → <code class="returnvalue">2001-02-16 20:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">timestamp with time zone</code>, <code class="type">text</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Truncate to specified precision in the specified time zone; see
+ <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
+ </p>
+ <p>
+ <code class="literal">date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</code>
+ → <code class="returnvalue">2001-02-16 13:00:00+00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Truncate to specified precision; see
+ <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
+ </p>
+ <p>
+ <code class="literal">date_trunc('hour', interval '2 days 3 hours 40 minutes')</code>
+ → <code class="returnvalue">2 days 03:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">extract</code> ( <em class="parameter"><code>field</code></em> <code class="literal">from</code> <code class="type">timestamp</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Get timestamp subfield; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
+ </p>
+ <p>
+ <code class="literal">extract(hour from timestamp '2001-02-16 20:38:40')</code>
+ → <code class="returnvalue">20</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">extract</code> ( <em class="parameter"><code>field</code></em> <code class="literal">from</code> <code class="type">interval</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Get interval subfield; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
+ </p>
+ <p>
+ <code class="literal">extract(month from interval '2 years 3 months')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">isfinite</code> ( <code class="type">date</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test for finite date (not +/-infinity)
+ </p>
+ <p>
+ <code class="literal">isfinite(date '2001-02-16')</code>
+ → <code class="returnvalue">true</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">isfinite</code> ( <code class="type">timestamp</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test for finite timestamp (not +/-infinity)
+ </p>
+ <p>
+ <code class="literal">isfinite(timestamp 'infinity')</code>
+ → <code class="returnvalue">false</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">isfinite</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Test for finite interval (currently always true)
+ </p>
+ <p>
+ <code class="literal">isfinite(interval '4 hours')</code>
+ → <code class="returnvalue">true</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.20.1.1.1" class="indexterm"></a>
+ <code class="function">justify_days</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Adjust interval so 30-day time periods are represented as months
+ </p>
+ <p>
+ <code class="literal">justify_days(interval '35 days')</code>
+ → <code class="returnvalue">1 mon 5 days</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">justify_hours</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Adjust interval so 24-hour time periods are represented as days
+ </p>
+ <p>
+ <code class="literal">justify_hours(interval '27 hours')</code>
+ → <code class="returnvalue">1 day 03:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">justify_interval</code> ( <code class="type">interval</code> )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Adjust interval using <code class="function">justify_days</code>
+ and <code class="function">justify_hours</code>, with additional sign
+ adjustments
+ </p>
+ <p>
+ <code class="literal">justify_interval(interval '1 mon -1 hour')</code>
+ → <code class="returnvalue">29 days 23:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">localtime</code>
+ → <code class="returnvalue">time</code>
+ </p>
+ <p>
+ Current time of day;
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">localtime</code>
+ → <code class="returnvalue">14:39:53.662522</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">localtime</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">time</code>
+ </p>
+ <p>
+ Current time of day, with limited precision;
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">localtime(0)</code>
+ → <code class="returnvalue">14:39:53</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">localtimestamp</code>
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Current date and time (start of current transaction);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">localtimestamp</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">localtimestamp</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Current date and time (start of current
+ transaction), with limited precision;
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">localtimestamp(2)</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.66</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.27.1.1.1" class="indexterm"></a>
+ <code class="function">make_date</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>month</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>day</code></em> <code class="type">int</code> )
+ → <code class="returnvalue">date</code>
+ </p>
+ <p>
+ Create date from year, month and day fields
+ (negative years signify BC)
+ </p>
+ <p>
+ <code class="literal">make_date(2013, 7, 15)</code>
+ → <code class="returnvalue">2013-07-15</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature"><a id="id-1.5.8.15.6.2.2.28.1.1.1" class="indexterm"></a>
+ <code class="function">make_interval</code> ( [<span class="optional"> <em class="parameter"><code>years</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>months</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>weeks</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>days</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>hours</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>mins</code></em> <code class="type">int</code>
+ [<span class="optional">, <em class="parameter"><code>secs</code></em> <code class="type">double precision</code>
+ </span>]</span>]</span>]</span>]</span>]</span>]</span>] )
+ → <code class="returnvalue">interval</code>
+ </p>
+ <p>
+ Create interval from years, months, weeks, days, hours, minutes and
+ seconds fields, each of which can default to zero
+ </p>
+ <p>
+ <code class="literal">make_interval(days =&gt; 10)</code>
+ → <code class="returnvalue">10 days</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.29.1.1.1" class="indexterm"></a>
+ <code class="function">make_time</code> ( <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>min</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>sec</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">time</code>
+ </p>
+ <p>
+ Create time from hour, minute and seconds fields
+ </p>
+ <p>
+ <code class="literal">make_time(8, 15, 23.5)</code>
+ → <code class="returnvalue">08:15:23.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.30.1.1.1" class="indexterm"></a>
+ <code class="function">make_timestamp</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>month</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>day</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>min</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>sec</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">timestamp</code>
+ </p>
+ <p>
+ Create timestamp from year, month, day, hour, minute and seconds fields
+ (negative years signify BC)
+ </p>
+ <p>
+ <code class="literal">make_timestamp(2013, 7, 15, 8, 15, 23.5)</code>
+ → <code class="returnvalue">2013-07-15 08:15:23.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.31.1.1.1" class="indexterm"></a>
+ <code class="function">make_timestamptz</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>month</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>day</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>min</code></em> <code class="type">int</code>,
+ <em class="parameter"><code>sec</code></em> <code class="type">double precision</code>
+ [<span class="optional">, <em class="parameter"><code>timezone</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Create timestamp with time zone from year, month, day, hour, minute
+ and seconds fields (negative years signify BC).
+ If <em class="parameter"><code>timezone</code></em> is not
+ specified, the current time zone is used; the examples assume the
+ session time zone is <code class="literal">Europe/London</code>
+ </p>
+ <p>
+ <code class="literal">make_timestamptz(2013, 7, 15, 8, 15, 23.5)</code>
+ → <code class="returnvalue">2013-07-15 08:15:23.5+01</code>
+ </p>
+ <p>
+ <code class="literal">make_timestamptz(2013, 7, 15, 8, 15, 23.5, 'America/New_York')</code>
+ → <code class="returnvalue">2013-07-15 13:15:23.5+01</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.32.1.1.1" class="indexterm"></a>
+ <code class="function">now</code> ( )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (start of current transaction);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">now()</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.33.1.1.1" class="indexterm"></a>
+ <code class="function">statement_timestamp</code> ( )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (start of current statement);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">statement_timestamp()</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.34.1.1.1" class="indexterm"></a>
+ <code class="function">timeofday</code> ( )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Current date and time
+ (like <code class="function">clock_timestamp</code>, but as a <code class="type">text</code> string);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">timeofday()</code>
+ → <code class="returnvalue">Mon Dec 23 14:39:53.662522 2019 EST</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.35.1.1.1" class="indexterm"></a>
+ <code class="function">transaction_timestamp</code> ( )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Current date and time (start of current transaction);
+ see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
+ </p>
+ <p>
+ <code class="literal">transaction_timestamp()</code>
+ → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.15.6.2.2.36.1.1.1" class="indexterm"></a>
+ <code class="function">to_timestamp</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
+ timestamp with time zone
+ </p>
+ <p>
+ <code class="literal">to_timestamp(1284352323)</code>
+ → <code class="returnvalue">2010-09-13 04:32:03+00</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a id="id-1.5.8.15.7.1" class="indexterm"></a>
+ In addition to these functions, the SQL <code class="literal">OVERLAPS</code> operator is
+ supported:
+</p><pre class="synopsis">
+(<em class="replaceable"><code>start1</code></em>, <em class="replaceable"><code>end1</code></em>) OVERLAPS (<em class="replaceable"><code>start2</code></em>, <em class="replaceable"><code>end2</code></em>)
+(<em class="replaceable"><code>start1</code></em>, <em class="replaceable"><code>length1</code></em>) OVERLAPS (<em class="replaceable"><code>start2</code></em>, <em class="replaceable"><code>length2</code></em>)
+</pre><p>
+ This expression yields true when two time periods (defined by their
+ endpoints) overlap, false when they do not overlap. The endpoints
+ can be specified as pairs of dates, times, or time stamps; or as
+ a date, time, or time stamp followed by an interval. When a pair
+ of values is provided, either the start or the end can be written
+ first; <code class="literal">OVERLAPS</code> automatically takes the earlier value
+ of the pair as the start. Each time period is considered to
+ represent the half-open interval <em class="replaceable"><code>start</code></em> <code class="literal">&lt;=</code>
+ <em class="replaceable"><code>time</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>end</code></em>, unless
+ <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em> are equal in which case it
+ represents that single time instant. This means for instance that two
+ time periods with only an endpoint in common do not overlap.
+ </p><pre class="screen">
+SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
+ (DATE '2001-10-30', DATE '2002-10-30');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">true</code>
+SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
+ (DATE '2001-10-30', DATE '2002-10-30');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">false</code>
+SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS
+ (DATE '2001-10-30', DATE '2001-10-31');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">false</code>
+SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
+ (DATE '2001-10-30', DATE '2001-10-31');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">true</code>
+</pre><p>
+ When adding an <code class="type">interval</code> value to (or subtracting an
+ <code class="type">interval</code> value from) a <code class="type">timestamp with time zone</code>
+ value, the days component advances or decrements the date of the
+ <code class="type">timestamp with time zone</code> by the indicated number of days,
+ keeping the time of day the same.
+ Across daylight saving time changes (when the session time zone is set to a
+ time zone that recognizes DST), this means <code class="literal">interval '1 day'</code>
+ does not necessarily equal <code class="literal">interval '24 hours'</code>.
+ For example, with the session time zone set
+ to <code class="literal">America/Denver</code>:
+</p><pre class="screen">
+SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '1 day';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005-04-03 12:00:00-06</code>
+SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '24 hours';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005-04-03 13:00:00-06</code>
+</pre><p>
+ This happens because an hour was skipped due to a change in daylight saving
+ time at <code class="literal">2005-04-03 02:00:00</code> in time zone
+ <code class="literal">America/Denver</code>.
+ </p><p>
+ Note there can be ambiguity in the <code class="literal">months</code> field returned by
+ <code class="function">age</code> because different months have different numbers of
+ days. <span class="productname">PostgreSQL</span>'s approach uses the month from the
+ earlier of the two dates when calculating partial months. For example,
+ <code class="literal">age('2004-06-01', '2004-04-30')</code> uses April to yield
+ <code class="literal">1 mon 1 day</code>, while using May would yield <code class="literal">1 mon 2
+ days</code> because May has 31 days, while April has only 30.
+ </p><p>
+ Subtraction of dates and timestamps can also be complex. One conceptually
+ simple way to perform subtraction is to convert each value to a number
+ of seconds using <code class="literal">EXTRACT(EPOCH FROM ...)</code>, then subtract the
+ results; this produces the
+ number of <span class="emphasis"><em>seconds</em></span> between the two values. This will adjust
+ for the number of days in each month, timezone changes, and daylight
+ saving time adjustments. Subtraction of date or timestamp
+ values with the <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span> operator
+ returns the number of days (24-hours) and hours/minutes/seconds
+ between the values, making the same adjustments. The <code class="function">age</code>
+ function returns years, months, days, and hours/minutes/seconds,
+ performing field-by-field subtraction and then adjusting for negative
+ field values. The following queries illustrate the differences in these
+ approaches. The sample results were produced with <code class="literal">timezone
+ = 'US/Eastern'</code>; there is a daylight saving time change between the
+ two dates used:
+ </p><pre class="screen">
+SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">10537200.000000</code>
+SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
+ / 60 / 60 / 24;
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">121.9583333333333333</code>
+SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">121 days 23:00:00</code>
+SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">4 mons</code>
+</pre><div class="sect2" id="FUNCTIONS-DATETIME-EXTRACT"><div class="titlepage"><div><div><h3 class="title">9.9.1. <code class="function">EXTRACT</code>, <code class="function">date_part</code></h3></div></div></div><a id="id-1.5.8.15.13.2" class="indexterm"></a><a id="id-1.5.8.15.13.3" class="indexterm"></a><pre class="synopsis">
+EXTRACT(<em class="replaceable"><code>field</code></em> FROM <em class="replaceable"><code>source</code></em>)
+</pre><p>
+ The <code class="function">extract</code> function retrieves subfields
+ such as year or hour from date/time values.
+ <em class="replaceable"><code>source</code></em> must be a value expression of
+ type <code class="type">timestamp</code>, <code class="type">time</code>, or <code class="type">interval</code>.
+ (Expressions of type <code class="type">date</code> are
+ cast to <code class="type">timestamp</code> and can therefore be used as
+ well.) <em class="replaceable"><code>field</code></em> is an identifier or
+ string that selects what field to extract from the source value.
+ The <code class="function">extract</code> function returns values of type
+ <code class="type">numeric</code>.
+ The following are valid field names:
+
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">century</code></span></dt><dd><p>
+ The century
+ </p><pre class="screen">
+SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
+SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">21</code>
+</pre><p>
+ The first century starts at 0001-01-01 00:00:00 AD, although
+ they did not know it at the time. This definition applies to all
+ Gregorian calendar countries. There is no century number 0,
+ you go from -1 century to 1 century.
+
+ If you disagree with this, please write your complaint to:
+ Pope, Cathedral Saint-Peter of Roma, Vatican.
+ </p></dd><dt><span class="term"><code class="literal">day</code></span></dt><dd><p>
+ For <code class="type">timestamp</code> values, the day (of the month) field
+ (1–31) ; for <code class="type">interval</code> values, the number of days
+ </p><pre class="screen">
+SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">16</code>
+
+SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">40</code>
+</pre></dd><dt><span class="term"><code class="literal">decade</code></span></dt><dd><p>
+ The year field divided by 10
+ </p><pre class="screen">
+SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">200</code>
+</pre></dd><dt><span class="term"><code class="literal">dow</code></span></dt><dd><p>
+ The day of the week as Sunday (<code class="literal">0</code>) to
+ Saturday (<code class="literal">6</code>)
+ </p><pre class="screen">
+SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">5</code>
+</pre><p>
+ Note that <code class="function">extract</code>'s day of the week numbering
+ differs from that of the <code class="function">to_char(...,
+ 'D')</code> function.
+ </p></dd><dt><span class="term"><code class="literal">doy</code></span></dt><dd><p>
+ The day of the year (1–365/366)
+ </p><pre class="screen">
+SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">47</code>
+</pre></dd><dt><span class="term"><code class="literal">epoch</code></span></dt><dd><p>
+ For <code class="type">timestamp with time zone</code> values, the
+ number of seconds since 1970-01-01 00:00:00 UTC (negative for
+ timestamps before that);
+ for <code class="type">date</code> and <code class="type">timestamp</code> values, the
+ nominal number of seconds since 1970-01-01 00:00:00,
+ without regard to timezone or daylight-savings rules;
+ for <code class="type">interval</code> values, the total number
+ of seconds in the interval
+ </p><pre class="screen">
+SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">982384720.120000</code>
+
+SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">982355920.120000</code>
+
+SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">442800.000000</code>
+</pre><p>
+ You can convert an epoch value back to a <code class="type">timestamp with time zone</code>
+ with <code class="function">to_timestamp</code>:
+ </p><pre class="screen">
+SELECT to_timestamp(982384720.12);
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-17 04:38:40.12+00</code>
+</pre><p>
+ Beware that applying <code class="function">to_timestamp</code> to an epoch
+ extracted from a <code class="type">date</code> or <code class="type">timestamp</code> value
+ could produce a misleading result: the result will effectively
+ assume that the original value had been given in UTC, which might
+ not be the case.
+ </p></dd><dt><span class="term"><code class="literal">hour</code></span></dt><dd><p>
+ The hour field (0–23)
+ </p><pre class="screen">
+SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
+</pre></dd><dt><span class="term"><code class="literal">isodow</code></span></dt><dd><p>
+ The day of the week as Monday (<code class="literal">1</code>) to
+ Sunday (<code class="literal">7</code>)
+ </p><pre class="screen">
+SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">7</code>
+</pre><p>
+ This is identical to <code class="literal">dow</code> except for Sunday. This
+ matches the <acronym class="acronym">ISO</acronym> 8601 day of the week numbering.
+ </p></dd><dt><span class="term"><code class="literal">isoyear</code></span></dt><dd><p>
+ The <acronym class="acronym">ISO</acronym> 8601 week-numbering year that the date
+ falls in (not applicable to intervals)
+ </p><pre class="screen">
+SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005</code>
+SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2006</code>
+</pre><p>
+ Each <acronym class="acronym">ISO</acronym> 8601 week-numbering year begins with the
+ Monday of the week containing the 4th of January, so in early
+ January or late December the <acronym class="acronym">ISO</acronym> year may be
+ different from the Gregorian year. See the <code class="literal">week</code>
+ field for more information.
+ </p><p>
+ This field is not available in PostgreSQL releases prior to 8.3.
+ </p></dd><dt><span class="term"><code class="literal">julian</code></span></dt><dd><p>
+ The <em class="firstterm">Julian Date</em> corresponding to the
+ date or timestamp (not applicable to intervals). Timestamps
+ that are not local midnight result in a fractional value. See
+ <a class="xref" href="datetime-julian-dates.html" title="B.7. Julian Dates">Section B.7</a> for more information.
+ </p><pre class="screen">
+SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2453737</code>
+SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2453737.50000000000000000000</code>
+</pre></dd><dt><span class="term"><code class="literal">microseconds</code></span></dt><dd><p>
+ The seconds field, including fractional parts, multiplied by 1
+ 000 000; note that this includes full seconds
+ </p><pre class="screen">
+SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28500000</code>
+</pre></dd><dt><span class="term"><code class="literal">millennium</code></span></dt><dd><p>
+ The millennium
+ </p><pre class="screen">
+SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3</code>
+</pre><p>
+ Years in the 1900s are in the second millennium.
+ The third millennium started January 1, 2001.
+ </p></dd><dt><span class="term"><code class="literal">milliseconds</code></span></dt><dd><p>
+ The seconds field, including fractional parts, multiplied by
+ 1000. Note that this includes full seconds.
+ </p><pre class="screen">
+SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28500.000</code>
+</pre></dd><dt><span class="term"><code class="literal">minute</code></span></dt><dd><p>
+ The minutes field (0–59)
+ </p><pre class="screen">
+SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">38</code>
+</pre></dd><dt><span class="term"><code class="literal">month</code></span></dt><dd><p>
+ For <code class="type">timestamp</code> values, the number of the month
+ within the year (1–12) ; for <code class="type">interval</code> values,
+ the number of months, modulo 12 (0–11)
+ </p><pre class="screen">
+SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2</code>
+
+SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3</code>
+
+SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
+</pre></dd><dt><span class="term"><code class="literal">quarter</code></span></dt><dd><p>
+ The quarter of the year (1–4) that the date is in
+ </p><pre class="screen">
+SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
+</pre></dd><dt><span class="term"><code class="literal">second</code></span></dt><dd><p>
+ The seconds field, including any fractional seconds
+ </p><pre class="screen">
+SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">40.000000</code>
+
+SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28.500000</code>
+</pre></dd><dt><span class="term"><code class="literal">timezone</code></span></dt><dd><p>
+ The time zone offset from UTC, measured in seconds. Positive values
+ correspond to time zones east of UTC, negative values to
+ zones west of UTC. (Technically,
+ <span class="productname">PostgreSQL</span> does not use UTC because
+ leap seconds are not handled.)
+ </p></dd><dt><span class="term"><code class="literal">timezone_hour</code></span></dt><dd><p>
+ The hour component of the time zone offset
+ </p></dd><dt><span class="term"><code class="literal">timezone_minute</code></span></dt><dd><p>
+ The minute component of the time zone offset
+ </p></dd><dt><span class="term"><code class="literal">week</code></span></dt><dd><p>
+ The number of the <acronym class="acronym">ISO</acronym> 8601 week-numbering week of
+ the year. By definition, ISO weeks start on Mondays and the first
+ week of a year contains January 4 of that year. In other words, the
+ first Thursday of a year is in week 1 of that year.
+ </p><p>
+ In the ISO week-numbering system, it is possible for early-January
+ dates to be part of the 52nd or 53rd week of the previous year, and for
+ late-December dates to be part of the first week of the next year.
+ For example, <code class="literal">2005-01-01</code> is part of the 53rd week of year
+ 2004, and <code class="literal">2006-01-01</code> is part of the 52nd week of year
+ 2005, while <code class="literal">2012-12-31</code> is part of the first week of 2013.
+ It's recommended to use the <code class="literal">isoyear</code> field together with
+ <code class="literal">week</code> to get consistent results.
+ </p><pre class="screen">
+SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">7</code>
+</pre></dd><dt><span class="term"><code class="literal">year</code></span></dt><dd><p>
+ The year field. Keep in mind there is no <code class="literal">0 AD</code>, so subtracting
+ <code class="literal">BC</code> years from <code class="literal">AD</code> years should be done with care.
+ </p><pre class="screen">
+SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001</code>
+</pre></dd></dl></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When the input value is +/-Infinity, <code class="function">extract</code> returns
+ +/-Infinity for monotonically-increasing fields (<code class="literal">epoch</code>,
+ <code class="literal">julian</code>, <code class="literal">year</code>, <code class="literal">isoyear</code>,
+ <code class="literal">decade</code>, <code class="literal">century</code>, and <code class="literal">millennium</code>).
+ For other fields, NULL is returned. <span class="productname">PostgreSQL</span>
+ versions before 9.6 returned zero for all cases of infinite input.
+ </p></div><p>
+ The <code class="function">extract</code> function is primarily intended
+ for computational processing. For formatting date/time values for
+ display, see <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>.
+ </p><p>
+ The <code class="function">date_part</code> function is modeled on the traditional
+ <span class="productname">Ingres</span> equivalent to the
+ <acronym class="acronym">SQL</acronym>-standard function <code class="function">extract</code>:
+</p><pre class="synopsis">
+date_part('<em class="replaceable"><code>field</code></em>', <em class="replaceable"><code>source</code></em>)
+</pre><p>
+ Note that here the <em class="replaceable"><code>field</code></em> parameter needs to
+ be a string value, not a name. The valid field names for
+ <code class="function">date_part</code> are the same as for
+ <code class="function">extract</code>.
+ For historical reasons, the <code class="function">date_part</code> function
+ returns values of type <code class="type">double precision</code>. This can result in
+ a loss of precision in certain uses. Using <code class="function">extract</code>
+ is recommended instead.
+ </p><pre class="screen">
+SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">16</code>
+
+SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">4</code>
+</pre></div><div class="sect2" id="FUNCTIONS-DATETIME-TRUNC"><div class="titlepage"><div><div><h3 class="title">9.9.2. <code class="function">date_trunc</code></h3></div></div></div><a id="id-1.5.8.15.14.2" class="indexterm"></a><p>
+ The function <code class="function">date_trunc</code> is conceptually
+ similar to the <code class="function">trunc</code> function for numbers.
+ </p><p>
+</p><pre class="synopsis">
+date_trunc(<em class="replaceable"><code>field</code></em>, <em class="replaceable"><code>source</code></em> [, <em class="replaceable"><code>time_zone</code></em> ])
+</pre><p>
+ <em class="replaceable"><code>source</code></em> is a value expression of type
+ <code class="type">timestamp</code>, <code class="type">timestamp with time zone</code>,
+ or <code class="type">interval</code>.
+ (Values of type <code class="type">date</code> and
+ <code class="type">time</code> are cast automatically to <code class="type">timestamp</code> or
+ <code class="type">interval</code>, respectively.)
+ <em class="replaceable"><code>field</code></em> selects to which precision to
+ truncate the input value. The return value is likewise of type
+ <code class="type">timestamp</code>, <code class="type">timestamp with time zone</code>,
+ or <code class="type">interval</code>,
+ and it has all fields that are less significant than the
+ selected one set to zero (or one, for day and month).
+ </p><p>
+ Valid values for <em class="replaceable"><code>field</code></em> are:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">microseconds</code></td></tr><tr><td><code class="literal">milliseconds</code></td></tr><tr><td><code class="literal">second</code></td></tr><tr><td><code class="literal">minute</code></td></tr><tr><td><code class="literal">hour</code></td></tr><tr><td><code class="literal">day</code></td></tr><tr><td><code class="literal">week</code></td></tr><tr><td><code class="literal">month</code></td></tr><tr><td><code class="literal">quarter</code></td></tr><tr><td><code class="literal">year</code></td></tr><tr><td><code class="literal">decade</code></td></tr><tr><td><code class="literal">century</code></td></tr><tr><td><code class="literal">millennium</code></td></tr></table><p>
+ </p><p>
+ When the input value is of type <code class="type">timestamp with time zone</code>,
+ the truncation is performed with respect to a particular time zone;
+ for example, truncation to <code class="literal">day</code> produces a value that
+ is midnight in that zone. By default, truncation is done with respect
+ to the current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting, but the
+ optional <em class="replaceable"><code>time_zone</code></em> argument can be provided
+ to specify a different time zone. The time zone name can be specified
+ in any of the ways described in <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>.
+ </p><p>
+ A time zone cannot be specified when processing <code class="type">timestamp without
+ time zone</code> or <code class="type">interval</code> inputs. These are always
+ taken at face value.
+ </p><p>
+ Examples (assuming the local time zone is <code class="literal">America/New_York</code>):
+</p><pre class="screen">
+SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 20:00:00</code>
+
+SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-01-01 00:00:00</code>
+
+SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 00:00:00-05</code>
+
+SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/Sydney');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 08:00:00-05</code>
+
+SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3 days 02:00:00</code>
+</pre><p>
+ </p></div><div class="sect2" id="FUNCTIONS-DATETIME-BIN"><div class="titlepage"><div><div><h3 class="title">9.9.3. <code class="function">date_bin</code></h3></div></div></div><a id="id-1.5.8.15.15.2" class="indexterm"></a><p>
+ The function <code class="function">date_bin</code> <span class="quote">“<span class="quote">bins</span>”</span> the input
+ timestamp into the specified interval (the <em class="firstterm">stride</em>)
+ aligned with a specified origin.
+ </p><p>
+</p><pre class="synopsis">
+date_bin(<em class="replaceable"><code>stride</code></em>, <em class="replaceable"><code>source</code></em>, <em class="replaceable"><code>origin</code></em>)
+</pre><p>
+ <em class="replaceable"><code>source</code></em> is a value expression of type
+ <code class="type">timestamp</code> or <code class="type">timestamp with time zone</code>. (Values
+ of type <code class="type">date</code> are cast automatically to
+ <code class="type">timestamp</code>.) <em class="replaceable"><code>stride</code></em> is a value
+ expression of type <code class="type">interval</code>. The return value is likewise
+ of type <code class="type">timestamp</code> or <code class="type">timestamp with time zone</code>,
+ and it marks the beginning of the bin into which the
+ <em class="replaceable"><code>source</code></em> is placed.
+ </p><p>
+ Examples:
+</p><pre class="screen">
+SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2020-02-11 15:30:00</code>
+
+SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00:02:30');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2020-02-11 15:32:30</code>
+</pre><p>
+ </p><p>
+ In the case of full units (1 minute, 1 hour, etc.), it gives the same result as
+ the analogous <code class="function">date_trunc</code> call, but the difference is
+ that <code class="function">date_bin</code> can truncate to an arbitrary interval.
+ </p><p>
+ The <em class="parameter"><code>stride</code></em> interval must be greater than zero and
+ cannot contain units of month or larger.
+ </p></div><div class="sect2" id="FUNCTIONS-DATETIME-ZONECONVERT"><div class="titlepage"><div><div><h3 class="title">9.9.4. <code class="literal">AT TIME ZONE</code></h3></div></div></div><a id="id-1.5.8.15.16.2" class="indexterm"></a><a id="id-1.5.8.15.16.3" class="indexterm"></a><p>
+ The <code class="literal">AT TIME ZONE</code> operator converts time
+ stamp <span class="emphasis"><em>without</em></span> time zone to/from
+ time stamp <span class="emphasis"><em>with</em></span> time zone, and
+ <code class="type">time with time zone</code> values to different time
+ zones. <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT-TABLE" title="Table 9.34. AT TIME ZONE Variants">Table 9.34</a> shows its
+ variants.
+ </p><div class="table" id="FUNCTIONS-DATETIME-ZONECONVERT-TABLE"><p class="title"><strong>Table 9.34. <code class="literal">AT TIME ZONE</code> Variants</strong></p><div class="table-contents"><table class="table" summary="AT TIME ZONE Variants" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">timestamp without time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Converts given time stamp <span class="emphasis"><em>without</em></span> time zone to
+ time stamp <span class="emphasis"><em>with</em></span> time zone, assuming the given
+ value is in the named time zone.
+ </p>
+ <p>
+ <code class="literal">timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'</code>
+ → <code class="returnvalue">2001-02-17 03:38:40+00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">timestamp with time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
+ → <code class="returnvalue">timestamp without time zone</code>
+ </p>
+ <p>
+ Converts given time stamp <span class="emphasis"><em>with</em></span> time zone to
+ time stamp <span class="emphasis"><em>without</em></span> time zone, as the time would
+ appear in that zone.
+ </p>
+ <p>
+ <code class="literal">timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'</code>
+ → <code class="returnvalue">2001-02-16 18:38:40</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">time with time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
+ → <code class="returnvalue">time with time zone</code>
+ </p>
+ <p>
+ Converts given time <span class="emphasis"><em>with</em></span> time zone to a new time
+ zone. Since no date is supplied, this uses the currently active UTC
+ offset for the named destination zone.
+ </p>
+ <p>
+ <code class="literal">time with time zone '05:34:17-05' at time zone 'UTC'</code>
+ → <code class="returnvalue">10:34:17+00</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In these expressions, the desired time zone <em class="replaceable"><code>zone</code></em> can be
+ specified either as a text value (e.g., <code class="literal">'America/Los_Angeles'</code>)
+ or as an interval (e.g., <code class="literal">INTERVAL '-08:00'</code>).
+ In the text case, a time zone name can be specified in any of the ways
+ described in <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>.
+ The interval case is only useful for zones that have fixed offsets from
+ UTC, so it is not very common in practice.
+ </p><p>
+ Examples (assuming the current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting
+ is <code class="literal">America/Los_Angeles</code>):
+</p><pre class="screen">
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 19:38:40-08</code>
+
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 18:38:40</code>
+
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 05:38:40</code>
+</pre><p>
+ The first example adds a time zone to a value that lacks it, and
+ displays the value using the current <code class="varname">TimeZone</code>
+ setting. The second example shifts the time stamp with time zone value
+ to the specified time zone, and returns the value without a time zone.
+ This allows storage and display of values different from the current
+ <code class="varname">TimeZone</code> setting. The third example converts
+ Tokyo time to Chicago time.
+ </p><p>
+ The function <code class="literal"><code class="function">timezone</code>(<em class="replaceable"><code>zone</code></em>,
+ <em class="replaceable"><code>timestamp</code></em>)</code> is equivalent to the SQL-conforming construct
+ <code class="literal"><em class="replaceable"><code>timestamp</code></em> AT TIME ZONE
+ <em class="replaceable"><code>zone</code></em></code>.
+ </p></div><div class="sect2" id="FUNCTIONS-DATETIME-CURRENT"><div class="titlepage"><div><div><h3 class="title">9.9.5. Current Date/Time</h3></div></div></div><a id="id-1.5.8.15.17.2" class="indexterm"></a><a id="id-1.5.8.15.17.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a number of functions
+ that return values related to the current date and time. These
+ SQL-standard functions all return values based on the start time of
+ the current transaction:
+</p><pre class="synopsis">
+CURRENT_DATE
+CURRENT_TIME
+CURRENT_TIMESTAMP
+CURRENT_TIME(<em class="replaceable"><code>precision</code></em>)
+CURRENT_TIMESTAMP(<em class="replaceable"><code>precision</code></em>)
+LOCALTIME
+LOCALTIMESTAMP
+LOCALTIME(<em class="replaceable"><code>precision</code></em>)
+LOCALTIMESTAMP(<em class="replaceable"><code>precision</code></em>)
+</pre><p>
+ </p><p>
+ <code class="function">CURRENT_TIME</code> and
+ <code class="function">CURRENT_TIMESTAMP</code> deliver values with time zone;
+ <code class="function">LOCALTIME</code> and
+ <code class="function">LOCALTIMESTAMP</code> deliver values without time zone.
+ </p><p>
+ <code class="function">CURRENT_TIME</code>,
+ <code class="function">CURRENT_TIMESTAMP</code>,
+ <code class="function">LOCALTIME</code>, and
+ <code class="function">LOCALTIMESTAMP</code>
+ can optionally take
+ a precision parameter, which causes the result to be rounded
+ to that many fractional digits in the seconds field. Without a precision parameter,
+ the result is given to the full available precision.
+ </p><p>
+ Some examples:
+</p><pre class="screen">
+SELECT CURRENT_TIME;
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">14:39:53.662522-05</code>
+
+SELECT CURRENT_DATE;
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23</code>
+
+SELECT CURRENT_TIMESTAMP;
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.662522-05</code>
+
+SELECT CURRENT_TIMESTAMP(2);
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.66-05</code>
+
+SELECT LOCALTIMESTAMP;
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.662522</code>
+</pre><p>
+ </p><p>
+ Since these functions return
+ the start time of the current transaction, their values do not
+ change during the transaction. This is considered a feature:
+ the intent is to allow a single transaction to have a consistent
+ notion of the <span class="quote">“<span class="quote">current</span>”</span> time, so that multiple
+ modifications within the same transaction bear the same
+ time stamp.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Other database systems might advance these values more
+ frequently.
+ </p></div><p>
+ <span class="productname">PostgreSQL</span> also provides functions that
+ return the start time of the current statement, as well as the actual
+ current time at the instant the function is called. The complete list
+ of non-SQL-standard time functions is:
+</p><pre class="synopsis">
+transaction_timestamp()
+statement_timestamp()
+clock_timestamp()
+timeofday()
+now()
+</pre><p>
+ </p><p>
+ <code class="function">transaction_timestamp()</code> is equivalent to
+ <code class="function">CURRENT_TIMESTAMP</code>, but is named to clearly reflect
+ what it returns.
+ <code class="function">statement_timestamp()</code> returns the start time of the current
+ statement (more specifically, the time of receipt of the latest command
+ message from the client).
+ <code class="function">statement_timestamp()</code> and <code class="function">transaction_timestamp()</code>
+ return the same value during the first command of a transaction, but might
+ differ during subsequent commands.
+ <code class="function">clock_timestamp()</code> returns the actual current time, and
+ therefore its value changes even within a single SQL command.
+ <code class="function">timeofday()</code> is a historical
+ <span class="productname">PostgreSQL</span> function. Like
+ <code class="function">clock_timestamp()</code>, it returns the actual current time,
+ but as a formatted <code class="type">text</code> string rather than a <code class="type">timestamp
+ with time zone</code> value.
+ <code class="function">now()</code> is a traditional <span class="productname">PostgreSQL</span>
+ equivalent to <code class="function">transaction_timestamp()</code>.
+ </p><p>
+ All the date/time data types also accept the special literal value
+ <code class="literal">now</code> to specify the current date and time (again,
+ interpreted as the transaction start time). Thus,
+ the following three all return the same result:
+</p><pre class="programlisting">
+SELECT CURRENT_TIMESTAMP;
+SELECT now();
+SELECT TIMESTAMP 'now'; -- but see tip below
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Do not use the third form when specifying a value to be evaluated later,
+ for example in a <code class="literal">DEFAULT</code> clause for a table column.
+ The system will convert <code class="literal">now</code>
+ to a <code class="type">timestamp</code> as soon as the constant is parsed, so that when
+ the default value is needed,
+ the time of the table creation would be used! The first two
+ forms will not be evaluated until the default value is used,
+ because they are function calls. Thus they will give the desired
+ behavior of defaulting to the time of row insertion.
+ (See also <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-VALUES" title="8.5.1.4. Special Values">Section 8.5.1.4</a>.)
+ </p></div></div><div class="sect2" id="FUNCTIONS-DATETIME-DELAY"><div class="titlepage"><div><div><h3 class="title">9.9.6. Delaying Execution</h3></div></div></div><a id="id-1.5.8.15.18.2" class="indexterm"></a><a id="id-1.5.8.15.18.3" class="indexterm"></a><a id="id-1.5.8.15.18.4" class="indexterm"></a><a id="id-1.5.8.15.18.5" class="indexterm"></a><a id="id-1.5.8.15.18.6" class="indexterm"></a><p>
+ The following functions are available to delay execution of the server
+ process:
+</p><pre class="synopsis">
+pg_sleep ( <code class="type">double precision</code> )
+pg_sleep_for ( <code class="type">interval</code> )
+pg_sleep_until ( <code class="type">timestamp with time zone</code> )
+</pre><p>
+
+ <code class="function">pg_sleep</code> makes the current session's process
+ sleep until the given number of seconds have
+ elapsed. Fractional-second delays can be specified.
+ <code class="function">pg_sleep_for</code> is a convenience function to
+ allow the sleep time to be specified as an <code class="type">interval</code>.
+ <code class="function">pg_sleep_until</code> is a convenience function for when
+ a specific wake-up time is desired.
+ For example:
+
+</p><pre class="programlisting">
+SELECT pg_sleep(1.5);
+SELECT pg_sleep_for('5 minutes');
+SELECT pg_sleep_until('tomorrow 03:00');
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The effective resolution of the sleep interval is platform-specific;
+ 0.01 seconds is a common value. The sleep delay will be at least as long
+ as specified. It might be longer depending on factors such as server load.
+ In particular, <code class="function">pg_sleep_until</code> is not guaranteed to
+ wake up exactly at the specified time, but it will not wake up any earlier.
+ </p></div><div class="warning"><h3 class="title">Warning</h3><p>
+ Make sure that your session does not hold more locks than necessary
+ when calling <code class="function">pg_sleep</code> or its variants. Otherwise
+ other sessions might have to wait for your sleeping process, slowing down
+ the entire system.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-enum.html" title="9.10. Enum Support Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.8. Data Type Formatting Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.10. Enum Support Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-enum.html b/doc/src/sgml/html/functions-enum.html
new file mode 100644
index 0000000..1e55029
--- /dev/null
+++ b/doc/src/sgml/html/functions-enum.html
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.10. Enum Support Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators" /><link rel="next" href="functions-geometry.html" title="9.11. Geometric Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.10. Enum Support Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-ENUM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.10. Enum Support Functions</h2></div></div></div><p>
+ For enum types (described in <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a>),
+ there are several functions that allow cleaner programming without
+ hard-coding particular values of an enum type.
+ These are listed in <a class="xref" href="functions-enum.html#FUNCTIONS-ENUM-TABLE" title="Table 9.35. Enum Support Functions">Table 9.35</a>. The examples
+ assume an enum type created as:
+
+</p><pre class="programlisting">
+CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
+</pre><p>
+
+ </p><div class="table" id="FUNCTIONS-ENUM-TABLE"><p class="title"><strong>Table 9.35. Enum Support Functions</strong></p><div class="table-contents"><table class="table" summary="Enum Support Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.16.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">enum_first</code> ( <code class="type">anyenum</code> )
+ → <code class="returnvalue">anyenum</code>
+ </p>
+ <p>
+ Returns the first value of the input enum type.
+ </p>
+ <p>
+ <code class="literal">enum_first(null::rainbow)</code>
+ → <code class="returnvalue">red</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.16.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">enum_last</code> ( <code class="type">anyenum</code> )
+ → <code class="returnvalue">anyenum</code>
+ </p>
+ <p>
+ Returns the last value of the input enum type.
+ </p>
+ <p>
+ <code class="literal">enum_last(null::rainbow)</code>
+ → <code class="returnvalue">purple</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.16.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">enum_range</code> ( <code class="type">anyenum</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Returns all values of the input enum type in an ordered array.
+ </p>
+ <p>
+ <code class="literal">enum_range(null::rainbow)</code>
+ → <code class="returnvalue">{red,orange,yellow,​green,blue,purple}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">enum_range</code> ( <code class="type">anyenum</code>, <code class="type">anyenum</code> )
+ → <code class="returnvalue">anyarray</code>
+ </p>
+ <p>
+ Returns the range between the two given enum values, as an ordered
+ array. The values must be from the same enum type. If the first
+ parameter is null, the result will start with the first value of
+ the enum type.
+ If the second parameter is null, the result will end with the last
+ value of the enum type.
+ </p>
+ <p>
+ <code class="literal">enum_range('orange'::rainbow, 'green'::rainbow)</code>
+ → <code class="returnvalue">{orange,yellow,green}</code>
+ </p>
+ <p>
+ <code class="literal">enum_range(NULL, 'green'::rainbow)</code>
+ → <code class="returnvalue">{red,orange,​yellow,green}</code>
+ </p>
+ <p>
+ <code class="literal">enum_range('orange'::rainbow, NULL)</code>
+ → <code class="returnvalue">{orange,yellow,green,​blue,purple}</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Notice that except for the two-argument form of <code class="function">enum_range</code>,
+ these functions disregard the specific value passed to them; they care
+ only about its declared data type. Either null or a specific value of
+ the type can be passed, with the same result. It is more common to
+ apply these functions to a table column or function argument than to
+ a hardwired type name as used in the examples.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.9. Date/Time Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.11. Geometric Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-event-triggers.html b/doc/src/sgml/html/functions-event-triggers.html
new file mode 100644
index 0000000..de23b5f
--- /dev/null
+++ b/doc/src/sgml/html/functions-event-triggers.html
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.29. Event Trigger Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-trigger.html" title="9.28. Trigger Functions" /><link rel="next" href="functions-statistics.html" title="9.30. Statistics Information Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.29. Event Trigger Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-trigger.html" title="9.28. Trigger Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-statistics.html" title="9.30. Statistics Information Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-EVENT-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.29. Event Trigger Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS">9.29.1. Capturing Changes at Command End</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS">9.29.2. Processing Objects Dropped by a DDL Command</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS">9.29.3. Handling a Table Rewrite Event</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> provides these helper functions
+ to retrieve information from event triggers.
+ </p><p>
+ For more information about event triggers,
+ see <a class="xref" href="event-triggers.html" title="Chapter 40. Event Triggers">Chapter 40</a>.
+ </p><div class="sect2" id="PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.29.1. Capturing Changes at Command End</h3></div></div></div><a id="id-1.5.8.35.4.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">pg_event_trigger_ddl_commands</code> () → <code class="returnvalue">setof record</code>
+</pre><p>
+ <code class="function">pg_event_trigger_ddl_commands</code> returns a list of
+ <acronym class="acronym">DDL</acronym> commands executed by each user action,
+ when invoked in a function attached to a
+ <code class="literal">ddl_command_end</code> event trigger. If called in any other
+ context, an error is raised.
+ <code class="function">pg_event_trigger_ddl_commands</code> returns one row for each
+ base command executed; some commands that are a single SQL sentence
+ may return more than one row. This function returns the following
+ columns:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">classid</code></td><td><code class="type">oid</code></td><td>OID of catalog the object belongs in</td></tr><tr><td><code class="literal">objid</code></td><td><code class="type">oid</code></td><td>OID of the object itself</td></tr><tr><td><code class="literal">objsubid</code></td><td><code class="type">integer</code></td><td>Sub-object ID (e.g., attribute number for a column)</td></tr><tr><td><code class="literal">command_tag</code></td><td><code class="type">text</code></td><td>Command tag</td></tr><tr><td><code class="literal">object_type</code></td><td><code class="type">text</code></td><td>Type of the object</td></tr><tr><td><code class="literal">schema_name</code></td><td><code class="type">text</code></td><td>
+ Name of the schema the object belongs in, if any; otherwise <code class="literal">NULL</code>.
+ No quoting is applied.
+ </td></tr><tr><td><code class="literal">object_identity</code></td><td><code class="type">text</code></td><td>
+ Text rendering of the object identity, schema-qualified. Each
+ identifier included in the identity is quoted if necessary.
+ </td></tr><tr><td><code class="literal">in_extension</code></td><td><code class="type">boolean</code></td><td>True if the command is part of an extension script</td></tr><tr><td><code class="literal">command</code></td><td><code class="type">pg_ddl_command</code></td><td>
+ A complete representation of the command, in internal format.
+ This cannot be output directly, but it can be passed to other
+ functions to obtain different pieces of information about the
+ command.
+ </td></tr></tbody></table></div><p>
+ </p></div><div class="sect2" id="PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.29.2. Processing Objects Dropped by a DDL Command</h3></div></div></div><a id="id-1.5.8.35.5.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">pg_event_trigger_dropped_objects</code> () → <code class="returnvalue">setof record</code>
+</pre><p>
+ <code class="function">pg_event_trigger_dropped_objects</code> returns a list of all objects
+ dropped by the command in whose <code class="literal">sql_drop</code> event it is called.
+ If called in any other context, an error is raised.
+ This function returns the following columns:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">classid</code></td><td><code class="type">oid</code></td><td>OID of catalog the object belonged in</td></tr><tr><td><code class="literal">objid</code></td><td><code class="type">oid</code></td><td>OID of the object itself</td></tr><tr><td><code class="literal">objsubid</code></td><td><code class="type">integer</code></td><td>Sub-object ID (e.g., attribute number for a column)</td></tr><tr><td><code class="literal">original</code></td><td><code class="type">boolean</code></td><td>True if this was one of the root object(s) of the deletion</td></tr><tr><td><code class="literal">normal</code></td><td><code class="type">boolean</code></td><td>
+ True if there was a normal dependency relationship
+ in the dependency graph leading to this object
+ </td></tr><tr><td><code class="literal">is_temporary</code></td><td><code class="type">boolean</code></td><td>
+ True if this was a temporary object
+ </td></tr><tr><td><code class="literal">object_type</code></td><td><code class="type">text</code></td><td>Type of the object</td></tr><tr><td><code class="literal">schema_name</code></td><td><code class="type">text</code></td><td>
+ Name of the schema the object belonged in, if any; otherwise <code class="literal">NULL</code>.
+ No quoting is applied.
+ </td></tr><tr><td><code class="literal">object_name</code></td><td><code class="type">text</code></td><td>
+ Name of the object, if the combination of schema and name can be
+ used as a unique identifier for the object; otherwise <code class="literal">NULL</code>.
+ No quoting is applied, and name is never schema-qualified.
+ </td></tr><tr><td><code class="literal">object_identity</code></td><td><code class="type">text</code></td><td>
+ Text rendering of the object identity, schema-qualified. Each
+ identifier included in the identity is quoted if necessary.
+ </td></tr><tr><td><code class="literal">address_names</code></td><td><code class="type">text[]</code></td><td>
+ An array that, together with <code class="literal">object_type</code> and
+ <code class="literal">address_args</code>, can be used by
+ the <code class="function">pg_get_object_address</code> function to
+ recreate the object address in a remote server containing an
+ identically named object of the same kind.
+ </td></tr><tr><td><code class="literal">address_args</code></td><td><code class="type">text[]</code></td><td>
+ Complement for <code class="literal">address_names</code>
+ </td></tr></tbody></table></div><p>
+ </p><p>
+ The <code class="function">pg_event_trigger_dropped_objects</code> function can be used
+ in an event trigger like this:
+</p><pre class="programlisting">
+CREATE FUNCTION test_event_trigger_for_drops()
+ RETURNS event_trigger LANGUAGE plpgsql AS $$
+DECLARE
+ obj record;
+BEGIN
+ FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects()
+ LOOP
+ RAISE NOTICE '% dropped object: % %.% %',
+ tg_tag,
+ obj.object_type,
+ obj.schema_name,
+ obj.object_name,
+ obj.object_identity;
+ END LOOP;
+END;
+$$;
+CREATE EVENT TRIGGER test_event_trigger_for_drops
+ ON sql_drop
+ EXECUTE FUNCTION test_event_trigger_for_drops();
+</pre><p>
+ </p></div><div class="sect2" id="PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">9.29.3. Handling a Table Rewrite Event</h3></div></div></div><p>
+ The functions shown in
+ <a class="xref" href="functions-event-triggers.html#FUNCTIONS-EVENT-TRIGGER-TABLE-REWRITE" title="Table 9.102. Table Rewrite Information Functions">Table 9.102</a>
+ provide information about a table for which a
+ <code class="literal">table_rewrite</code> event has just been called.
+ If called in any other context, an error is raised.
+ </p><div class="table" id="FUNCTIONS-EVENT-TRIGGER-TABLE-REWRITE"><p class="title"><strong>Table 9.102. Table Rewrite Information Functions</strong></p><div class="table-contents"><table class="table" summary="Table Rewrite Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.35.6.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_event_trigger_table_rewrite_oid</code> ()
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Returns the OID of the table about to be rewritten.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.35.6.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_event_trigger_table_rewrite_reason</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns a code explaining the reason(s) for rewriting. The exact
+ meaning of the codes is release dependent.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ These functions can be used in an event trigger like this:
+</p><pre class="programlisting">
+CREATE FUNCTION test_event_trigger_table_rewrite_oid()
+ RETURNS event_trigger
+ LANGUAGE plpgsql AS
+$$
+BEGIN
+ RAISE NOTICE 'rewriting table % for reason %',
+ pg_event_trigger_table_rewrite_oid()::regclass,
+ pg_event_trigger_table_rewrite_reason();
+END;
+$$;
+
+CREATE EVENT TRIGGER test_table_rewrite_oid
+ ON table_rewrite
+ EXECUTE FUNCTION test_event_trigger_table_rewrite_oid();
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-trigger.html" title="9.28. Trigger Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-statistics.html" title="9.30. Statistics Information Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.28. Trigger Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.30. Statistics Information Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-formatting.html b/doc/src/sgml/html/functions-formatting.html
new file mode 100644
index 0000000..089e24e
--- /dev/null
+++ b/doc/src/sgml/html/functions-formatting.html
@@ -0,0 +1,410 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.8. Data Type Formatting Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-matching.html" title="9.7. Pattern Matching" /><link rel="next" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.8. Data Type Formatting Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-matching.html" title="9.7. Pattern Matching">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-FORMATTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.8. Data Type Formatting Functions</h2></div></div></div><a id="id-1.5.8.14.2" class="indexterm"></a><p>
+ The <span class="productname">PostgreSQL</span> formatting functions
+ 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.
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-TABLE" title="Table 9.26. Formatting Functions">Table 9.26</a> 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.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-TABLE"><p class="title"><strong>Table 9.26. Formatting Functions</strong></p><div class="table-contents"><table class="table" summary="Formatting Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.14.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">to_char</code> ( <code class="type">timestamp</code>, <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">to_char</code> ( <code class="type">timestamp with time zone</code>, <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts time stamp to string according to the given format.
+ </p>
+ <p>
+ <code class="literal">to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')</code>
+ → <code class="returnvalue">05:31:12</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">to_char</code> ( <code class="type">interval</code>, <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts interval to string according to the given format.
+ </p>
+ <p>
+ <code class="literal">to_char(interval '15h 2m 12s', 'HH24:MI:SS')</code>
+ → <code class="returnvalue">15:02:12</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">to_char</code> ( <em class="replaceable"><code>numeric_type</code></em>, <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts number to string according to the given format; available
+ for <code class="type">integer</code>, <code class="type">bigint</code>, <code class="type">numeric</code>,
+ <code class="type">real</code>, <code class="type">double precision</code>.
+ </p>
+ <p>
+ <code class="literal">to_char(125, '999')</code>
+ → <code class="returnvalue">125</code>
+ </p>
+ <p>
+ <code class="literal">to_char(125.8::real, '999D9')</code>
+ → <code class="returnvalue">125.8</code>
+ </p>
+ <p>
+ <code class="literal">to_char(-125.8, '999D99S')</code>
+ → <code class="returnvalue">125.80-</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.14.4.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">to_date</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">date</code>
+ </p>
+ <p>
+ Converts string to date according to the given format.
+ </p>
+ <p>
+ <code class="literal">to_date('05 Dec 2000', 'DD Mon YYYY')</code>
+ → <code class="returnvalue">2000-12-05</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.14.4.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">to_number</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Converts string to numeric according to the given format.
+ </p>
+ <p>
+ <code class="literal">to_number('12,454.8-', '99G999D9S')</code>
+ → <code class="returnvalue">-12454.8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.14.4.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">to_timestamp</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Converts string to time stamp according to the given format.
+ (See also <code class="function">to_timestamp(double precision)</code> in
+ <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TABLE" title="Table 9.33. Date/Time Functions">Table 9.33</a>.)
+ </p>
+ <p>
+ <code class="literal">to_timestamp('05 Dec 2000', 'DD Mon YYYY')</code>
+ → <code class="returnvalue">2000-12-05 00:00:00-05</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="tip"><h3 class="title">Tip</h3><p>
+ <code class="function">to_timestamp</code> and <code class="function">to_date</code>
+ exist to handle input formats that cannot be converted by
+ simple casting. For most standard date/time formats, simply casting the
+ source string to the required data type works, and is much easier.
+ Similarly, <code class="function">to_number</code> is unnecessary for standard numeric
+ representations.
+ </p></div><p>
+ In a <code class="function">to_char</code> output template string, there are certain
+ patterns that are recognized and replaced with appropriately-formatted
+ data based on the given value. Any text that is not a template pattern is
+ simply copied verbatim. Similarly, in an input template string (for the
+ other functions), template patterns identify the values to be supplied by
+ the input data string. If there are characters in the template string
+ that are not template patterns, the corresponding characters in the input
+ data string are simply skipped over (whether or not they are equal to the
+ template string characters).
+ </p><p>
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-DATETIME-TABLE" title="Table 9.27. Template Patterns for Date/Time Formatting">Table 9.27</a> shows the
+ template patterns available for formatting date and time values.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-DATETIME-TABLE"><p class="title"><strong>Table 9.27. Template Patterns for Date/Time Formatting</strong></p><div class="table-contents"><table class="table" summary="Template Patterns for Date/Time Formatting" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Pattern</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">HH</code></td><td>hour of day (01–12)</td></tr><tr><td><code class="literal">HH12</code></td><td>hour of day (01–12)</td></tr><tr><td><code class="literal">HH24</code></td><td>hour of day (00–23)</td></tr><tr><td><code class="literal">MI</code></td><td>minute (00–59)</td></tr><tr><td><code class="literal">SS</code></td><td>second (00–59)</td></tr><tr><td><code class="literal">MS</code></td><td>millisecond (000–999)</td></tr><tr><td><code class="literal">US</code></td><td>microsecond (000000–999999)</td></tr><tr><td><code class="literal">FF1</code></td><td>tenth of second (0–9)</td></tr><tr><td><code class="literal">FF2</code></td><td>hundredth of second (00–99)</td></tr><tr><td><code class="literal">FF3</code></td><td>millisecond (000–999)</td></tr><tr><td><code class="literal">FF4</code></td><td>tenth of a millisecond (0000–9999)</td></tr><tr><td><code class="literal">FF5</code></td><td>hundredth of a millisecond (00000–99999)</td></tr><tr><td><code class="literal">FF6</code></td><td>microsecond (000000–999999)</td></tr><tr><td><code class="literal">SSSS</code>, <code class="literal">SSSSS</code></td><td>seconds past midnight (0–86399)</td></tr><tr><td><code class="literal">AM</code>, <code class="literal">am</code>,
+ <code class="literal">PM</code> or <code class="literal">pm</code></td><td>meridiem indicator (without periods)</td></tr><tr><td><code class="literal">A.M.</code>, <code class="literal">a.m.</code>,
+ <code class="literal">P.M.</code> or <code class="literal">p.m.</code></td><td>meridiem indicator (with periods)</td></tr><tr><td><code class="literal">Y,YYY</code></td><td>year (4 or more digits) with comma</td></tr><tr><td><code class="literal">YYYY</code></td><td>year (4 or more digits)</td></tr><tr><td><code class="literal">YYY</code></td><td>last 3 digits of year</td></tr><tr><td><code class="literal">YY</code></td><td>last 2 digits of year</td></tr><tr><td><code class="literal">Y</code></td><td>last digit of year</td></tr><tr><td><code class="literal">IYYY</code></td><td>ISO 8601 week-numbering year (4 or more digits)</td></tr><tr><td><code class="literal">IYY</code></td><td>last 3 digits of ISO 8601 week-numbering year</td></tr><tr><td><code class="literal">IY</code></td><td>last 2 digits of ISO 8601 week-numbering year</td></tr><tr><td><code class="literal">I</code></td><td>last digit of ISO 8601 week-numbering year</td></tr><tr><td><code class="literal">BC</code>, <code class="literal">bc</code>,
+ <code class="literal">AD</code> or <code class="literal">ad</code></td><td>era indicator (without periods)</td></tr><tr><td><code class="literal">B.C.</code>, <code class="literal">b.c.</code>,
+ <code class="literal">A.D.</code> or <code class="literal">a.d.</code></td><td>era indicator (with periods)</td></tr><tr><td><code class="literal">MONTH</code></td><td>full upper case month name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">Month</code></td><td>full capitalized month name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">month</code></td><td>full lower case month name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">MON</code></td><td>abbreviated upper case month name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">Mon</code></td><td>abbreviated capitalized month name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">mon</code></td><td>abbreviated lower case month name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">MM</code></td><td>month number (01–12)</td></tr><tr><td><code class="literal">DAY</code></td><td>full upper case day name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">Day</code></td><td>full capitalized day name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">day</code></td><td>full lower case day name (blank-padded to 9 chars)</td></tr><tr><td><code class="literal">DY</code></td><td>abbreviated upper case day name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">Dy</code></td><td>abbreviated capitalized day name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">dy</code></td><td>abbreviated lower case day name (3 chars in English, localized lengths vary)</td></tr><tr><td><code class="literal">DDD</code></td><td>day of year (001–366)</td></tr><tr><td><code class="literal">IDDD</code></td><td>day of ISO 8601 week-numbering year (001–371; day 1 of the year is Monday of the first ISO week)</td></tr><tr><td><code class="literal">DD</code></td><td>day of month (01–31)</td></tr><tr><td><code class="literal">D</code></td><td>day of the week, Sunday (<code class="literal">1</code>) to Saturday (<code class="literal">7</code>)</td></tr><tr><td><code class="literal">ID</code></td><td>ISO 8601 day of the week, Monday (<code class="literal">1</code>) to Sunday (<code class="literal">7</code>)</td></tr><tr><td><code class="literal">W</code></td><td>week of month (1–5) (the first week starts on the first day of the month)</td></tr><tr><td><code class="literal">WW</code></td><td>week number of year (1–53) (the first week starts on the first day of the year)</td></tr><tr><td><code class="literal">IW</code></td><td>week number of ISO 8601 week-numbering year (01–53; the first Thursday of the year is in week 1)</td></tr><tr><td><code class="literal">CC</code></td><td>century (2 digits) (the twenty-first century starts on 2001-01-01)</td></tr><tr><td><code class="literal">J</code></td><td>Julian Date (integer days since November 24, 4714 BC at local
+ midnight; see <a class="xref" href="datetime-julian-dates.html" title="B.7. Julian Dates">Section B.7</a>)</td></tr><tr><td><code class="literal">Q</code></td><td>quarter</td></tr><tr><td><code class="literal">RM</code></td><td>month in upper case Roman numerals (I–XII; I=January)</td></tr><tr><td><code class="literal">rm</code></td><td>month in lower case Roman numerals (i–xii; i=January)</td></tr><tr><td><code class="literal">TZ</code></td><td>upper case time-zone abbreviation
+ (only supported in <code class="function">to_char</code>)</td></tr><tr><td><code class="literal">tz</code></td><td>lower case time-zone abbreviation
+ (only supported in <code class="function">to_char</code>)</td></tr><tr><td><code class="literal">TZH</code></td><td>time-zone hours</td></tr><tr><td><code class="literal">TZM</code></td><td>time-zone minutes</td></tr><tr><td><code class="literal">OF</code></td><td>time-zone offset from UTC
+ (only supported in <code class="function">to_char</code>)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Modifiers can be applied to any template pattern to alter its
+ behavior. For example, <code class="literal">FMMonth</code>
+ is the <code class="literal">Month</code> pattern with the
+ <code class="literal">FM</code> modifier.
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-DATETIMEMOD-TABLE" title="Table 9.28. Template Pattern Modifiers for Date/Time Formatting">Table 9.28</a> shows the
+ modifier patterns for date/time formatting.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-DATETIMEMOD-TABLE"><p class="title"><strong>Table 9.28. Template Pattern Modifiers for Date/Time Formatting</strong></p><div class="table-contents"><table class="table" summary="Template Pattern Modifiers for Date/Time Formatting" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Modifier</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code class="literal">FM</code> prefix</td><td>fill mode (suppress leading zeroes and padding blanks)</td><td><code class="literal">FMMonth</code></td></tr><tr><td><code class="literal">TH</code> suffix</td><td>upper case ordinal number suffix</td><td><code class="literal">DDTH</code>, e.g., <code class="literal">12TH</code></td></tr><tr><td><code class="literal">th</code> suffix</td><td>lower case ordinal number suffix</td><td><code class="literal">DDth</code>, e.g., <code class="literal">12th</code></td></tr><tr><td><code class="literal">FX</code> prefix</td><td>fixed format global option (see usage notes)</td><td><code class="literal">FX Month DD Day</code></td></tr><tr><td><code class="literal">TM</code> prefix</td><td>translation mode (use localized day and month names based on
+ <a class="xref" href="runtime-config-client.html#GUC-LC-TIME">lc_time</a>)</td><td><code class="literal">TMMonth</code></td></tr><tr><td><code class="literal">SP</code> suffix</td><td>spell mode (not implemented)</td><td><code class="literal">DDSP</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Usage notes for date/time formatting:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">FM</code> suppresses leading zeroes and trailing blanks
+ that would otherwise be added to make the output of a pattern be
+ fixed-width. In <span class="productname">PostgreSQL</span>,
+ <code class="literal">FM</code> modifies only the next specification, while in
+ Oracle <code class="literal">FM</code> affects all subsequent
+ specifications, and repeated <code class="literal">FM</code> modifiers
+ toggle fill mode on and off.
+ </p></li><li class="listitem"><p>
+ <code class="literal">TM</code> suppresses trailing blanks whether or
+ not <code class="literal">FM</code> is specified.
+ </p></li><li class="listitem"><p>
+ <code class="function">to_timestamp</code> and <code class="function">to_date</code>
+ ignore letter case in the input; so for
+ example <code class="literal">MON</code>, <code class="literal">Mon</code>,
+ and <code class="literal">mon</code> all accept the same strings. When using
+ the <code class="literal">TM</code> modifier, case-folding is done according to
+ the rules of the function's input collation (see
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>).
+ </p></li><li class="listitem"><p>
+ <code class="function">to_timestamp</code> and <code class="function">to_date</code>
+ skip multiple blank spaces at the beginning of the input string and
+ around date and time values unless the <code class="literal">FX</code> option is used. For example,
+ <code class="literal">to_timestamp(' 2000    JUN', 'YYYY MON')</code> and
+ <code class="literal">to_timestamp('2000 - JUN', 'YYYY-MON')</code> work, but
+ <code class="literal">to_timestamp('2000    JUN', 'FXYYYY MON')</code> returns an error
+ because <code class="function">to_timestamp</code> expects only a single space.
+ <code class="literal">FX</code> must be specified as the first item in
+ the template.
+ </p></li><li class="listitem"><p>
+ A separator (a space or non-letter/non-digit character) in the template string of
+ <code class="function">to_timestamp</code> and <code class="function">to_date</code>
+ matches any single separator in the input string or is skipped,
+ unless the <code class="literal">FX</code> option is used.
+ For example, <code class="literal">to_timestamp('2000JUN', 'YYYY///MON')</code> and
+ <code class="literal">to_timestamp('2000/JUN', 'YYYY MON')</code> work, but
+ <code class="literal">to_timestamp('2000//JUN', 'YYYY/MON')</code>
+ returns an error because the number of separators in the input string
+ exceeds the number of separators in the template.
+ </p><p>
+ If <code class="literal">FX</code> is specified, a separator in the template string
+ matches exactly one character in the input string. But note that the
+ input string character is not required to be the same as the separator from the template string.
+ For example, <code class="literal">to_timestamp('2000/JUN', 'FXYYYY MON')</code>
+ works, but <code class="literal">to_timestamp('2000/JUN', 'FXYYYY  MON')</code>
+ returns an error because the second space in the template string consumes
+ the letter <code class="literal">J</code> from the input string.
+ </p></li><li class="listitem"><p>
+ A <code class="literal">TZH</code> template pattern can match a signed number.
+ Without the <code class="literal">FX</code> option, minus signs may be ambiguous,
+ and could be interpreted as a separator.
+ This ambiguity is resolved as follows: If the number of separators before
+ <code class="literal">TZH</code> in the template string is less than the number of
+ separators before the minus sign in the input string, the minus sign
+ is interpreted as part of <code class="literal">TZH</code>.
+ Otherwise, the minus sign is considered to be a separator between values.
+ For example, <code class="literal">to_timestamp('2000 -10', 'YYYY TZH')</code> matches
+ <code class="literal">-10</code> to <code class="literal">TZH</code>, but
+ <code class="literal">to_timestamp('2000 -10', 'YYYY  TZH')</code>
+ matches <code class="literal">10</code> to <code class="literal">TZH</code>.
+ </p></li><li class="listitem"><p>
+ Ordinary text is allowed in <code class="function">to_char</code>
+ templates and will be output literally. You can put a substring
+ in double quotes to force it to be interpreted as literal text
+ even if it contains template patterns. For example, in
+ <code class="literal">'"Hello Year "YYYY'</code>, the <code class="literal">YYYY</code>
+ will be replaced by the year data, but the single <code class="literal">Y</code> in <code class="literal">Year</code>
+ will not be.
+ In <code class="function">to_date</code>, <code class="function">to_number</code>,
+ and <code class="function">to_timestamp</code>, literal text and double-quoted
+ strings result in skipping the number of characters contained in the
+ string; for example <code class="literal">"XX"</code> skips two input characters
+ (whether or not they are <code class="literal">XX</code>).
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> 12, it was possible to
+ skip arbitrary text in the input string using non-letter or non-digit
+ characters. For example,
+ <code class="literal">to_timestamp('2000y6m1d', 'yyyy-MM-DD')</code> used to
+ work. Now you can only use letter characters for this purpose. For example,
+ <code class="literal">to_timestamp('2000y6m1d', 'yyyytMMtDDt')</code> and
+ <code class="literal">to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"')</code>
+ skip <code class="literal">y</code>, <code class="literal">m</code>, and
+ <code class="literal">d</code>.
+ </p></div></li><li class="listitem"><p>
+ If you want to have a double quote in the output you must
+ precede it with a backslash, for example <code class="literal">'\"YYYY
+ Month\"'</code>.
+ Backslashes are not otherwise special outside of double-quoted
+ strings. Within a double-quoted string, a backslash causes the
+ next character to be taken literally, whatever it is (but this
+ has no special effect unless the next character is a double quote
+ or another backslash).
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ if the year format specification is less than four digits, e.g.,
+ <code class="literal">YYY</code>, and the supplied year is less than four digits,
+ the year will be adjusted to be nearest to the year 2020, e.g.,
+ <code class="literal">95</code> becomes 1995.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ negative years are treated as signifying BC. If you write both a
+ negative year and an explicit <code class="literal">BC</code> field, you get AD
+ again. An input of year zero is treated as 1 BC.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ the <code class="literal">YYYY</code> conversion has a restriction when
+ processing years with more than 4 digits. You must
+ use some non-digit character or template after <code class="literal">YYYY</code>,
+ otherwise the year is always interpreted as 4 digits. For example
+ (with the year 20000):
+ <code class="literal">to_date('200001131', 'YYYYMMDD')</code> will be
+ interpreted as a 4-digit year; instead use a non-digit
+ separator after the year, like
+ <code class="literal">to_date('20000-1131', 'YYYY-MMDD')</code> or
+ <code class="literal">to_date('20000Nov31', 'YYYYMonDD')</code>.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ the <code class="literal">CC</code> (century) field is accepted but ignored
+ if there is a <code class="literal">YYY</code>, <code class="literal">YYYY</code> or
+ <code class="literal">Y,YYY</code> field. If <code class="literal">CC</code> is used with
+ <code class="literal">YY</code> or <code class="literal">Y</code> then the result is
+ computed as that year in the specified century. If the century is
+ specified but the year is not, the first year of the century
+ is assumed.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ weekday names or numbers (<code class="literal">DAY</code>, <code class="literal">D</code>,
+ and related field types) are accepted but are ignored for purposes of
+ computing the result. The same is true for quarter
+ (<code class="literal">Q</code>) fields.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code> and <code class="function">to_date</code>,
+ an ISO 8601 week-numbering date (as distinct from a Gregorian date)
+ can be specified in one of two ways:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ Year, week number, and weekday: for
+ example <code class="literal">to_date('2006-42-4', 'IYYY-IW-ID')</code>
+ returns the date <code class="literal">2006-10-19</code>.
+ If you omit the weekday it is assumed to be 1 (Monday).
+ </p></li><li class="listitem"><p>
+ Year and day of year: for example <code class="literal">to_date('2006-291',
+ 'IYYY-IDDD')</code> also returns <code class="literal">2006-10-19</code>.
+ </p></li></ul></div><p>
+ </p><p>
+ Attempting to enter a date using a mixture of ISO 8601 week-numbering
+ fields and Gregorian date fields is nonsensical, and will cause an
+ error. In the context of an ISO 8601 week-numbering year, the
+ concept of a <span class="quote">“<span class="quote">month</span>”</span> or <span class="quote">“<span class="quote">day of month</span>”</span> has no
+ meaning. In the context of a Gregorian year, the ISO week has no
+ meaning.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ While <code class="function">to_date</code> will reject a mixture of
+ Gregorian and ISO week-numbering date
+ fields, <code class="function">to_char</code> will not, since output format
+ specifications like <code class="literal">YYYY-MM-DD (IYYY-IDDD)</code> can be
+ useful. But avoid writing something like <code class="literal">IYYY-MM-DD</code>;
+ that would yield surprising results near the start of the year.
+ (See <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a> for more
+ information.)
+ </p></div></li><li class="listitem"><p>
+ In <code class="function">to_timestamp</code>, millisecond
+ (<code class="literal">MS</code>) or microsecond (<code class="literal">US</code>)
+ fields are used as the
+ seconds digits after the decimal point. For example
+ <code class="literal">to_timestamp('12.3', 'SS.MS')</code> is not 3 milliseconds,
+ but 300, because the conversion treats it as 12 + 0.3 seconds.
+ So, for the format <code class="literal">SS.MS</code>, the input values
+ <code class="literal">12.3</code>, <code class="literal">12.30</code>,
+ and <code class="literal">12.300</code> specify the
+ same number of milliseconds. To get three milliseconds, one must write
+ <code class="literal">12.003</code>, which the conversion treats as
+ 12 + 0.003 = 12.003 seconds.
+ </p><p>
+ Here is a more
+ complex example:
+ <code class="literal">to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')</code>
+ is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
+ 1230 microseconds = 2.021230 seconds.
+ </p></li><li class="listitem"><p>
+ <code class="function">to_char(..., 'ID')</code>'s day of the week numbering
+ matches the <code class="function">extract(isodow from ...)</code> function, but
+ <code class="function">to_char(..., 'D')</code>'s does not match
+ <code class="function">extract(dow from ...)</code>'s day numbering.
+ </p></li><li class="listitem"><p>
+ <code class="function">to_char(interval)</code> formats <code class="literal">HH</code> and
+ <code class="literal">HH12</code> as shown on a 12-hour clock, for example zero hours
+ and 36 hours both output as <code class="literal">12</code>, while <code class="literal">HH24</code>
+ outputs the full hour value, which can exceed 23 in
+ an <code class="type">interval</code> value.
+ </p></li></ul></div><p>
+ </p><p>
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-NUMERIC-TABLE" title="Table 9.29. Template Patterns for Numeric Formatting">Table 9.29</a> shows the
+ template patterns available for formatting numeric values.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-NUMERIC-TABLE"><p class="title"><strong>Table 9.29. Template Patterns for Numeric Formatting</strong></p><div class="table-contents"><table class="table" summary="Template Patterns for Numeric Formatting" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Pattern</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">9</code></td><td>digit position (can be dropped if insignificant)</td></tr><tr><td><code class="literal">0</code></td><td>digit position (will not be dropped, even if insignificant)</td></tr><tr><td><code class="literal">.</code> (period)</td><td>decimal point</td></tr><tr><td><code class="literal">,</code> (comma)</td><td>group (thousands) separator</td></tr><tr><td><code class="literal">PR</code></td><td>negative value in angle brackets</td></tr><tr><td><code class="literal">S</code></td><td>sign anchored to number (uses locale)</td></tr><tr><td><code class="literal">L</code></td><td>currency symbol (uses locale)</td></tr><tr><td><code class="literal">D</code></td><td>decimal point (uses locale)</td></tr><tr><td><code class="literal">G</code></td><td>group separator (uses locale)</td></tr><tr><td><code class="literal">MI</code></td><td>minus sign in specified position (if number &lt; 0)</td></tr><tr><td><code class="literal">PL</code></td><td>plus sign in specified position (if number &gt; 0)</td></tr><tr><td><code class="literal">SG</code></td><td>plus/minus sign in specified position</td></tr><tr><td><code class="literal">RN</code></td><td>Roman numeral (input between 1 and 3999)</td></tr><tr><td><code class="literal">TH</code> or <code class="literal">th</code></td><td>ordinal number suffix</td></tr><tr><td><code class="literal">V</code></td><td>shift specified number of digits (see notes)</td></tr><tr><td><code class="literal">EEEE</code></td><td>exponent for scientific notation</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Usage notes for numeric formatting:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">0</code> specifies a digit position that will always be printed,
+ even if it contains a leading/trailing zero. <code class="literal">9</code> also
+ specifies a digit position, but if it is a leading zero then it will
+ be replaced by a space, while if it is a trailing zero and fill mode
+ is specified then it will be deleted. (For <code class="function">to_number()</code>,
+ these two pattern characters are equivalent.)
+ </p></li><li class="listitem"><p>
+ If the format provides fewer fractional digits than the number being
+ formatted, <code class="function">to_char()</code> will round the number to
+ the specified number of fractional digits.
+ </p></li><li class="listitem"><p>
+ The pattern characters <code class="literal">S</code>, <code class="literal">L</code>, <code class="literal">D</code>,
+ and <code class="literal">G</code> represent the sign, currency symbol, decimal point,
+ and thousands separator characters defined by the current locale
+ (see <a class="xref" href="runtime-config-client.html#GUC-LC-MONETARY">lc_monetary</a>
+ and <a class="xref" href="runtime-config-client.html#GUC-LC-NUMERIC">lc_numeric</a>). The pattern characters period
+ and comma represent those exact characters, with the meanings of
+ decimal point and thousands separator, regardless of locale.
+ </p></li><li class="listitem"><p>
+ If no explicit provision is made for a sign
+ in <code class="function">to_char()</code>'s pattern, one column will be reserved for
+ the sign, and it will be anchored to (appear just left of) the
+ number. If <code class="literal">S</code> appears just left of some <code class="literal">9</code>'s,
+ it will likewise be anchored to the number.
+ </p></li><li class="listitem"><p>
+ A sign formatted using <code class="literal">SG</code>, <code class="literal">PL</code>, or
+ <code class="literal">MI</code> is not anchored to
+ the number; for example,
+ <code class="literal">to_char(-12, 'MI9999')</code> produces <code class="literal">'-  12'</code>
+ but <code class="literal">to_char(-12, 'S9999')</code> produces <code class="literal">'  -12'</code>.
+ (The Oracle implementation does not allow the use of
+ <code class="literal">MI</code> before <code class="literal">9</code>, but rather
+ requires that <code class="literal">9</code> precede
+ <code class="literal">MI</code>.)
+ </p></li><li class="listitem"><p>
+ <code class="literal">TH</code> does not convert values less than zero
+ and does not convert fractional numbers.
+ </p></li><li class="listitem"><p>
+ <code class="literal">PL</code>, <code class="literal">SG</code>, and
+ <code class="literal">TH</code> are <span class="productname">PostgreSQL</span>
+ extensions.
+ </p></li><li class="listitem"><p>
+ In <code class="function">to_number</code>, if non-data template patterns such
+ as <code class="literal">L</code> or <code class="literal">TH</code> are used, the
+ corresponding number of input characters are skipped, whether or not
+ they match the template pattern, unless they are data characters
+ (that is, digits, sign, decimal point, or comma). For
+ example, <code class="literal">TH</code> would skip two non-data characters.
+ </p></li><li class="listitem"><p>
+ <code class="literal">V</code> with <code class="function">to_char</code>
+ multiplies the input values by
+ <code class="literal">10^<em class="replaceable"><code>n</code></em></code>, where
+ <em class="replaceable"><code>n</code></em> is the number of digits following
+ <code class="literal">V</code>. <code class="literal">V</code> with
+ <code class="function">to_number</code> divides in a similar manner.
+ <code class="function">to_char</code> and <code class="function">to_number</code>
+ do not support the use of
+ <code class="literal">V</code> combined with a decimal point
+ (e.g., <code class="literal">99.9V99</code> is not allowed).
+ </p></li><li class="listitem"><p>
+ <code class="literal">EEEE</code> (scientific notation) cannot be used in
+ combination with any of the other formatting patterns or
+ modifiers other than digit and decimal point patterns, and must be at the end of the format string
+ (e.g., <code class="literal">9.99EEEE</code> is a valid pattern).
+ </p></li></ul></div><p>
+ </p><p>
+ Certain modifiers can be applied to any template pattern to alter its
+ behavior. For example, <code class="literal">FM99.99</code>
+ is the <code class="literal">99.99</code> pattern with the
+ <code class="literal">FM</code> modifier.
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-NUMERICMOD-TABLE" title="Table 9.30. Template Pattern Modifiers for Numeric Formatting">Table 9.30</a> shows the
+ modifier patterns for numeric formatting.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-NUMERICMOD-TABLE"><p class="title"><strong>Table 9.30. Template Pattern Modifiers for Numeric Formatting</strong></p><div class="table-contents"><table class="table" summary="Template Pattern Modifiers for Numeric Formatting" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Modifier</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code class="literal">FM</code> prefix</td><td>fill mode (suppress trailing zeroes and padding blanks)</td><td><code class="literal">FM99.99</code></td></tr><tr><td><code class="literal">TH</code> suffix</td><td>upper case ordinal number suffix</td><td><code class="literal">999TH</code></td></tr><tr><td><code class="literal">th</code> suffix</td><td>lower case ordinal number suffix</td><td><code class="literal">999th</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-formatting.html#FUNCTIONS-FORMATTING-EXAMPLES-TABLE" title="Table 9.31. to_char Examples">Table 9.31</a> shows some
+ examples of the use of the <code class="function">to_char</code> function.
+ </p><div class="table" id="FUNCTIONS-FORMATTING-EXAMPLES-TABLE"><p class="title"><strong>Table 9.31. <code class="function">to_char</code> Examples</strong></p><div class="table-contents"><table class="table" summary="to_char Examples" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Expression</th><th>Result</th></tr></thead><tbody><tr><td><code class="literal">to_char(current_timestamp, 'Day, DD  HH12:MI:SS')</code></td><td><code class="literal">'Tuesday  , 06  05:39:18'</code></td></tr><tr><td><code class="literal">to_char(current_timestamp, 'FMDay, FMDD  HH12:MI:SS')</code></td><td><code class="literal">'Tuesday, 6  05:39:18'</code></td></tr><tr><td><code class="literal">to_char(-0.1, '99.99')</code></td><td><code class="literal">'  -.10'</code></td></tr><tr><td><code class="literal">to_char(-0.1, 'FM9.99')</code></td><td><code class="literal">'-.1'</code></td></tr><tr><td><code class="literal">to_char(-0.1, 'FM90.99')</code></td><td><code class="literal">'-0.1'</code></td></tr><tr><td><code class="literal">to_char(0.1, '0.9')</code></td><td><code class="literal">' 0.1'</code></td></tr><tr><td><code class="literal">to_char(12, '9990999.9')</code></td><td><code class="literal">'    0012.0'</code></td></tr><tr><td><code class="literal">to_char(12, 'FM9990999.9')</code></td><td><code class="literal">'0012.'</code></td></tr><tr><td><code class="literal">to_char(485, '999')</code></td><td><code class="literal">' 485'</code></td></tr><tr><td><code class="literal">to_char(-485, '999')</code></td><td><code class="literal">'-485'</code></td></tr><tr><td><code class="literal">to_char(485, '9 9 9')</code></td><td><code class="literal">' 4 8 5'</code></td></tr><tr><td><code class="literal">to_char(1485, '9,999')</code></td><td><code class="literal">' 1,485'</code></td></tr><tr><td><code class="literal">to_char(1485, '9G999')</code></td><td><code class="literal">' 1 485'</code></td></tr><tr><td><code class="literal">to_char(148.5, '999.999')</code></td><td><code class="literal">' 148.500'</code></td></tr><tr><td><code class="literal">to_char(148.5, 'FM999.999')</code></td><td><code class="literal">'148.5'</code></td></tr><tr><td><code class="literal">to_char(148.5, 'FM999.990')</code></td><td><code class="literal">'148.500'</code></td></tr><tr><td><code class="literal">to_char(148.5, '999D999')</code></td><td><code class="literal">' 148,500'</code></td></tr><tr><td><code class="literal">to_char(3148.5, '9G999D999')</code></td><td><code class="literal">' 3 148,500'</code></td></tr><tr><td><code class="literal">to_char(-485, '999S')</code></td><td><code class="literal">'485-'</code></td></tr><tr><td><code class="literal">to_char(-485, '999MI')</code></td><td><code class="literal">'485-'</code></td></tr><tr><td><code class="literal">to_char(485, '999MI')</code></td><td><code class="literal">'485 '</code></td></tr><tr><td><code class="literal">to_char(485, 'FM999MI')</code></td><td><code class="literal">'485'</code></td></tr><tr><td><code class="literal">to_char(485, 'PL999')</code></td><td><code class="literal">'+485'</code></td></tr><tr><td><code class="literal">to_char(485, 'SG999')</code></td><td><code class="literal">'+485'</code></td></tr><tr><td><code class="literal">to_char(-485, 'SG999')</code></td><td><code class="literal">'-485'</code></td></tr><tr><td><code class="literal">to_char(-485, '9SG99')</code></td><td><code class="literal">'4-85'</code></td></tr><tr><td><code class="literal">to_char(-485, '999PR')</code></td><td><code class="literal">'&lt;485&gt;'</code></td></tr><tr><td><code class="literal">to_char(485, 'L999')</code></td><td><code class="literal">'DM 485'</code></td></tr><tr><td><code class="literal">to_char(485, 'RN')</code></td><td><code class="literal">'        CDLXXXV'</code></td></tr><tr><td><code class="literal">to_char(485, 'FMRN')</code></td><td><code class="literal">'CDLXXXV'</code></td></tr><tr><td><code class="literal">to_char(5.2, 'FMRN')</code></td><td><code class="literal">'V'</code></td></tr><tr><td><code class="literal">to_char(482, '999th')</code></td><td><code class="literal">' 482nd'</code></td></tr><tr><td><code class="literal">to_char(485, '"Good number:"999')</code></td><td><code class="literal">'Good number: 485'</code></td></tr><tr><td><code class="literal">to_char(485.8, '"Pre:"999" Post:" .999')</code></td><td><code class="literal">'Pre: 485 Post: .800'</code></td></tr><tr><td><code class="literal">to_char(12, '99V999')</code></td><td><code class="literal">' 12000'</code></td></tr><tr><td><code class="literal">to_char(12.4, '99V999')</code></td><td><code class="literal">' 12400'</code></td></tr><tr><td><code class="literal">to_char(12.45, '99V9')</code></td><td><code class="literal">' 125'</code></td></tr><tr><td><code class="literal">to_char(0.0004859, '9.99EEEE')</code></td><td><code class="literal">' 4.86e-04'</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-matching.html" title="9.7. Pattern Matching">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-datetime.html" title="9.9. Date/Time Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.7. Pattern Matching </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.9. Date/Time Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-geometry.html b/doc/src/sgml/html/functions-geometry.html
new file mode 100644
index 0000000..6379b7a
--- /dev/null
+++ b/doc/src/sgml/html/functions-geometry.html
@@ -0,0 +1,886 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.11. Geometric Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-enum.html" title="9.10. Enum Support Functions" /><link rel="next" href="functions-net.html" title="9.12. Network Address Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.11. Geometric Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-enum.html" title="9.10. Enum Support Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-net.html" title="9.12. Network Address Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-GEOMETRY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.11. Geometric Functions and Operators</h2></div></div></div><p>
+ The geometric types <code class="type">point</code>, <code class="type">box</code>,
+ <code class="type">lseg</code>, <code class="type">line</code>, <code class="type">path</code>,
+ <code class="type">polygon</code>, and <code class="type">circle</code> have a large set of
+ native support functions and operators, shown in <a class="xref" href="functions-geometry.html#FUNCTIONS-GEOMETRY-OP-TABLE" title="Table 9.36. Geometric Operators">Table 9.36</a>, <a class="xref" href="functions-geometry.html#FUNCTIONS-GEOMETRY-FUNC-TABLE" title="Table 9.37. Geometric Functions">Table 9.37</a>, and <a class="xref" href="functions-geometry.html#FUNCTIONS-GEOMETRY-CONV-TABLE" title="Table 9.38. Geometric Type Conversion Functions">Table 9.38</a>.
+ </p><div class="table" id="FUNCTIONS-GEOMETRY-OP-TABLE"><p class="title"><strong>Table 9.36. Geometric Operators</strong></p><div class="table-contents"><table class="table" summary="Geometric Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">+</code> <code class="type">point</code>
+ → <code class="returnvalue"><em class="replaceable"><code>geometric_type</code></em></code>
+ </p>
+ <p>
+ Adds the coordinates of the second <code class="type">point</code> to those of each
+ point of the first argument, thus performing translation.
+ Available for <code class="type">point</code>, <code class="type">box</code>, <code class="type">path</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(1,1),(0,0)' + point '(2,0)'</code>
+ → <code class="returnvalue">(3,1),(2,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">path</code> <code class="literal">+</code> <code class="type">path</code>
+ → <code class="returnvalue">path</code>
+ </p>
+ <p>
+ Concatenates two open paths (returns NULL if either path is closed).
+ </p>
+ <p>
+ <code class="literal">path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]'</code>
+ → <code class="returnvalue">[(0,0),(1,1),(2,2),(3,3),(4,4)]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">-</code> <code class="type">point</code>
+ → <code class="returnvalue"><em class="replaceable"><code>geometric_type</code></em></code>
+ </p>
+ <p>
+ Subtracts the coordinates of the second <code class="type">point</code> from those
+ of each point of the first argument, thus performing translation.
+ Available for <code class="type">point</code>, <code class="type">box</code>, <code class="type">path</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(1,1),(0,0)' - point '(2,0)'</code>
+ → <code class="returnvalue">(-1,1),(-2,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">*</code> <code class="type">point</code>
+ → <code class="returnvalue"><em class="replaceable"><code>geometric_type</code></em></code>
+ </p>
+ <p>
+ Multiplies each point of the first argument by the second
+ <code class="type">point</code> (treating a point as being a complex number
+ represented by real and imaginary parts, and performing standard
+ complex multiplication). If one interprets
+ the second <code class="type">point</code> as a vector, this is equivalent to
+ scaling the object's size and distance from the origin by the length
+ of the vector, and rotating it counterclockwise around the origin by
+ the vector's angle from the <em class="replaceable"><code>x</code></em> axis.
+ Available for <code class="type">point</code>, <code class="type">box</code>,<a href="#ftn.FUNCTIONS-GEOMETRY-ROTATION-FN" class="footnote"><sup class="footnote" id="FUNCTIONS-GEOMETRY-ROTATION-FN">[a]</sup></a>
+ <code class="type">path</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">path '((0,0),(1,0),(1,1))' * point '(3.0,0)'</code>
+ → <code class="returnvalue">((0,0),(3,0),(3,3))</code>
+ </p>
+ <p>
+ <code class="literal">path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45))</code>
+ → <code class="returnvalue">((0,0),​(0.7071067811865475,0.7071067811865475),​(0,1.414213562373095))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">/</code> <code class="type">point</code>
+ → <code class="returnvalue"><em class="replaceable"><code>geometric_type</code></em></code>
+ </p>
+ <p>
+ Divides each point of the first argument by the second
+ <code class="type">point</code> (treating a point as being a complex number
+ represented by real and imaginary parts, and performing standard
+ complex division). If one interprets
+ the second <code class="type">point</code> as a vector, this is equivalent to
+ scaling the object's size and distance from the origin down by the
+ length of the vector, and rotating it clockwise around the origin by
+ the vector's angle from the <em class="replaceable"><code>x</code></em> axis.
+ Available for <code class="type">point</code>, <code class="type">box</code>,<a href="functions-geometry.html#ftn.FUNCTIONS-GEOMETRY-ROTATION-FN" class="footnoteref"><sup class="footnoteref">[a]</sup></a> <code class="type">path</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">path '((0,0),(1,0),(1,1))' / point '(2.0,0)'</code>
+ → <code class="returnvalue">((0,0),(0.5,0),(0.5,0.5))</code>
+ </p>
+ <p>
+ <code class="literal">path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45))</code>
+ → <code class="returnvalue">((0,0),​(0.7071067811865476,-0.7071067811865476),​(1.4142135623730951,0))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">@-@</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the total length.
+ Available for <code class="type">lseg</code>, <code class="type">path</code>.
+ </p>
+ <p>
+ <code class="literal">@-@ path '[(0,0),(1,0),(1,1)]'</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">@@</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes the center point.
+ Available for <code class="type">box</code>, <code class="type">lseg</code>,
+ <code class="type">polygon</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">@@ box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">(1,1)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">#</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of points.
+ Available for <code class="type">path</code>, <code class="type">polygon</code>.
+ </p>
+ <p>
+ <code class="literal"># path '((1,0),(0,1),(-1,0))'</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">#</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes the point of intersection, or NULL if there is none.
+ Available for <code class="type">lseg</code>, <code class="type">line</code>.
+ </p>
+ <p>
+ <code class="literal">lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]'</code>
+ → <code class="returnvalue">(0.5,0.5)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">box</code> <code class="literal">#</code> <code class="type">box</code>
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Computes the intersection of two boxes, or NULL if there is none.
+ </p>
+ <p>
+ <code class="literal">box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)'</code>
+ → <code class="returnvalue">(1,1),(-1,-1)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">##</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes the closest point to the first object on the second object.
+ Available for these pairs of types:
+ (<code class="type">point</code>, <code class="type">box</code>),
+ (<code class="type">point</code>, <code class="type">lseg</code>),
+ (<code class="type">point</code>, <code class="type">line</code>),
+ (<code class="type">lseg</code>, <code class="type">box</code>),
+ (<code class="type">lseg</code>, <code class="type">lseg</code>),
+ (<code class="type">line</code>, <code class="type">lseg</code>).
+ </p>
+ <p>
+ <code class="literal">point '(0,0)' ## lseg '[(2,0),(0,2)]'</code>
+ → <code class="returnvalue">(1,1)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&lt;-&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the distance between the objects.
+ Available for all seven geometric types, for all combinations
+ of <code class="type">point</code> with another geometric type, and for
+ these additional pairs of types:
+ (<code class="type">box</code>, <code class="type">lseg</code>),
+ (<code class="type">lseg</code>, <code class="type">line</code>),
+ (<code class="type">polygon</code>, <code class="type">circle</code>)
+ (and the commutator cases).
+ </p>
+ <p>
+ <code class="literal">circle '&lt;(0,0),1&gt;' &lt;-&gt; circle '&lt;(5,0),1&gt;'</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">@&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first object contain second?
+ Available for these pairs of types:
+ (<code class="literal">box</code>, <code class="literal">point</code>),
+ (<code class="literal">box</code>, <code class="literal">box</code>),
+ (<code class="literal">path</code>, <code class="literal">point</code>),
+ (<code class="literal">polygon</code>, <code class="literal">point</code>),
+ (<code class="literal">polygon</code>, <code class="literal">polygon</code>),
+ (<code class="literal">circle</code>, <code class="literal">point</code>),
+ (<code class="literal">circle</code>, <code class="literal">circle</code>).
+ </p>
+ <p>
+ <code class="literal">circle '&lt;(0,0),2&gt;' @&gt; point '(1,1)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&lt;@</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object contained in or on second?
+ Available for these pairs of types:
+ (<code class="literal">point</code>, <code class="literal">box</code>),
+ (<code class="literal">point</code>, <code class="literal">lseg</code>),
+ (<code class="literal">point</code>, <code class="literal">line</code>),
+ (<code class="literal">point</code>, <code class="literal">path</code>),
+ (<code class="literal">point</code>, <code class="literal">polygon</code>),
+ (<code class="literal">point</code>, <code class="literal">circle</code>),
+ (<code class="literal">box</code>, <code class="literal">box</code>),
+ (<code class="literal">lseg</code>, <code class="literal">box</code>),
+ (<code class="literal">lseg</code>, <code class="literal">line</code>),
+ (<code class="literal">polygon</code>, <code class="literal">polygon</code>),
+ (<code class="literal">circle</code>, <code class="literal">circle</code>).
+ </p>
+ <p>
+ <code class="literal">point '(1,1)' &lt;@ circle '&lt;(0,0),2&gt;'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&amp;&amp;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do these objects overlap? (One point in common makes this true.)
+ Available for <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(1,1),(0,0)' &amp;&amp; box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&lt;&lt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object strictly left of second?
+ Available for <code class="type">point</code>, <code class="type">box</code>,
+ <code class="type">polygon</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">circle '&lt;(0,0),1&gt;' &lt;&lt; circle '&lt;(5,0),1&gt;'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&gt;&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object strictly right of second?
+ Available for <code class="type">point</code>, <code class="type">box</code>,
+ <code class="type">polygon</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">circle '&lt;(5,0),1&gt;' &gt;&gt; circle '&lt;(0,0),1&gt;'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&amp;&lt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first object not extend to the right of second?
+ Available for <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(1,1),(0,0)' &amp;&lt; box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&amp;&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first object not extend to the left of second?
+ Available for <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(3,3),(0,0)' &amp;&gt; box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&lt;&lt;|</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object strictly below second?
+ Available for <code class="type">point</code>, <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(3,3),(0,0)' &lt;&lt;| box '(5,5),(3,4)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">|&gt;&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object strictly above second?
+ Available for <code class="type">point</code>, <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(5,5),(3,4)' |&gt;&gt; box '(3,3),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">&amp;&lt;|</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first object not extend above second?
+ Available for <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(1,1),(0,0)' &amp;&lt;| box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">|&amp;&gt;</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first object not extend below second?
+ Available for <code class="type">box</code>, <code class="type">polygon</code>,
+ <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">box '(3,3),(0,0)' |&amp;&gt; box '(2,2),(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">box</code> <code class="literal">&lt;^</code> <code class="type">box</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object below second (allows edges to touch)?
+ </p>
+ <p>
+ <code class="literal">box '((1,1),(0,0))' &lt;^ box '((2,2),(1,1))'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">box</code> <code class="literal">&gt;^</code> <code class="type">box</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first object above second (allows edges to touch)?
+ </p>
+ <p>
+ <code class="literal">box '((2,2),(1,1))' &gt;^ box '((1,1),(0,0))'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">?#</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do these objects intersect?
+ Available for these pairs of types:
+ (<code class="type">box</code>, <code class="type">box</code>),
+ (<code class="type">lseg</code>, <code class="type">box</code>),
+ (<code class="type">lseg</code>, <code class="type">lseg</code>),
+ (<code class="type">lseg</code>, <code class="type">line</code>),
+ (<code class="type">line</code>, <code class="type">box</code>),
+ (<code class="type">line</code>, <code class="type">line</code>),
+ (<code class="type">path</code>, <code class="type">path</code>).
+ </p>
+ <p>
+ <code class="literal">lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">?-</code> <code class="type">line</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="literal">?-</code> <code class="type">lseg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is line horizontal?
+ </p>
+ <p>
+ <code class="literal">?- lseg '[(-1,0),(1,0)]'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">point</code> <code class="literal">?-</code> <code class="type">point</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are points horizontally aligned (that is, have same y coordinate)?
+ </p>
+ <p>
+ <code class="literal">point '(1,0)' ?- point '(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">?|</code> <code class="type">line</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="literal">?|</code> <code class="type">lseg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is line vertical?
+ </p>
+ <p>
+ <code class="literal">?| lseg '[(-1,0),(1,0)]'</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">point</code> <code class="literal">?|</code> <code class="type">point</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are points vertically aligned (that is, have same x coordinate)?
+ </p>
+ <p>
+ <code class="literal">point '(0,1)' ?| point '(0,0)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">line</code> <code class="literal">?-|</code> <code class="type">line</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lseg</code> <code class="literal">?-|</code> <code class="type">lseg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are lines perpendicular?
+ </p>
+ <p>
+ <code class="literal">lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">line</code> <code class="literal">?||</code> <code class="type">line</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lseg</code> <code class="literal">?||</code> <code class="type">lseg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are lines parallel?
+ </p>
+ <p>
+ <code class="literal">lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>geometric_type</code></em> <code class="literal">~=</code> <em class="replaceable"><code>geometric_type</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are these objects the same?
+ Available for <code class="type">point</code>, <code class="type">box</code>,
+ <code class="type">polygon</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr></tbody><tbody class="footnotes"><tr><td colspan="1"><div id="ftn.FUNCTIONS-GEOMETRY-ROTATION-FN" class="footnote"><p><a href="#FUNCTIONS-GEOMETRY-ROTATION-FN" class="para"><sup class="para">[a] </sup></a><span class="quote">“<span class="quote">Rotating</span>”</span> a
+ box with these operators only moves its corner points: the box is
+ still considered to have sides parallel to the axes. Hence the box's
+ size is not preserved, as a true rotation would do.</p></div></td></tr></tbody></table></div></div><br class="table-break" /><div class="caution"><h3 class="title">Caution</h3><p>
+ Note that the <span class="quote">“<span class="quote">same as</span>”</span> operator, <code class="literal">~=</code>,
+ represents the usual notion of equality for the <code class="type">point</code>,
+ <code class="type">box</code>, <code class="type">polygon</code>, and <code class="type">circle</code> types.
+ Some of the geometric types also have an <code class="literal">=</code> operator, but
+ <code class="literal">=</code> compares for equal <span class="emphasis"><em>areas</em></span> only.
+ The other scalar comparison operators (<code class="literal">&lt;=</code> and so
+ on), where available for these types, likewise compare areas.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 14, the point
+ is strictly below/above comparison operators <code class="type">point</code>
+ <code class="literal">&lt;&lt;|</code> <code class="type">point</code> and <code class="type">point</code>
+ <code class="literal">|&gt;&gt;</code> <code class="type">point</code> were respectively
+ called <code class="literal">&lt;^</code> and <code class="literal">&gt;^</code>. These
+ names are still available, but are deprecated and will eventually be
+ removed.
+ </p></div><div class="table" id="FUNCTIONS-GEOMETRY-FUNC-TABLE"><p class="title"><strong>Table 9.37. Geometric Functions</strong></p><div class="table-contents"><table class="table" summary="Geometric Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">area</code> ( <em class="replaceable"><code>geometric_type</code></em> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes area.
+ Available for <code class="type">box</code>, <code class="type">path</code>, <code class="type">circle</code>.
+ A <code class="type">path</code> input must be closed, else NULL is returned.
+ Also, if the <code class="type">path</code> is self-intersecting, the result may be
+ meaningless.
+ </p>
+ <p>
+ <code class="literal">area(box '(2,2),(0,0)')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">center</code> ( <em class="replaceable"><code>geometric_type</code></em> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes center point.
+ Available for <code class="type">box</code>, <code class="type">circle</code>.
+ </p>
+ <p>
+ <code class="literal">center(box '(1,2),(0,0)')</code>
+ → <code class="returnvalue">(0.5,1)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">diagonal</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">lseg</code>
+ </p>
+ <p>
+ Extracts box's diagonal as a line segment
+ (same as <code class="function">lseg(box)</code>).
+ </p>
+ <p>
+ <code class="literal">diagonal(box '(1,2),(0,0)')</code>
+ → <code class="returnvalue">[(1,2),(0,0)]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">diameter</code> ( <code class="type">circle</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes diameter of circle.
+ </p>
+ <p>
+ <code class="literal">diameter(circle '&lt;(0,0),2&gt;')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">height</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes vertical size of box.
+ </p>
+ <p>
+ <code class="literal">height(box '(1,2),(0,0)')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">isclosed</code> ( <code class="type">path</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is path closed?
+ </p>
+ <p>
+ <code class="literal">isclosed(path '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">isopen</code> ( <code class="type">path</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is path open?
+ </p>
+ <p>
+ <code class="literal">isopen(path '[(0,0),(1,1),(2,0)]')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">length</code> ( <em class="replaceable"><code>geometric_type</code></em> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes the total length.
+ Available for <code class="type">lseg</code>, <code class="type">path</code>.
+ </p>
+ <p>
+ <code class="literal">length(path '((-1,0),(1,0))')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">npoints</code> ( <em class="replaceable"><code>geometric_type</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of points.
+ Available for <code class="type">path</code>, <code class="type">polygon</code>.
+ </p>
+ <p>
+ <code class="literal">npoints(path '[(0,0),(1,1),(2,0)]')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pclose</code> ( <code class="type">path</code> )
+ → <code class="returnvalue">path</code>
+ </p>
+ <p>
+ Converts path to closed form.
+ </p>
+ <p>
+ <code class="literal">pclose(path '[(0,0),(1,1),(2,0)]')</code>
+ → <code class="returnvalue">((0,0),(1,1),(2,0))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">popen</code> ( <code class="type">path</code> )
+ → <code class="returnvalue">path</code>
+ </p>
+ <p>
+ Converts path to open form.
+ </p>
+ <p>
+ <code class="literal">popen(path '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">[(0,0),(1,1),(2,0)]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">radius</code> ( <code class="type">circle</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes radius of circle.
+ </p>
+ <p>
+ <code class="literal">radius(circle '&lt;(0,0),2&gt;')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">slope</code> ( <code class="type">point</code>, <code class="type">point</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes slope of a line drawn through the two points.
+ </p>
+ <p>
+ <code class="literal">slope(point '(0,0)', point '(2,1)')</code>
+ → <code class="returnvalue">0.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.6.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">width</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Computes horizontal size of box.
+ </p>
+ <p>
+ <code class="literal">width(box '(1,2),(0,0)')</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-GEOMETRY-CONV-TABLE"><p class="title"><strong>Table 9.38. Geometric Type Conversion Functions</strong></p><div class="table-contents"><table class="table" summary="Geometric Type Conversion Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">box</code> ( <code class="type">circle</code> )
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Computes box inscribed within the circle.
+ </p>
+ <p>
+ <code class="literal">box(circle '&lt;(0,0),2&gt;')</code>
+ → <code class="returnvalue">(1.414213562373095,1.414213562373095),​(-1.414213562373095,-1.414213562373095)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">box</code> ( <code class="type">point</code> )
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Converts point to empty box.
+ </p>
+ <p>
+ <code class="literal">box(point '(1,0)')</code>
+ → <code class="returnvalue">(1,0),(1,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">box</code> ( <code class="type">point</code>, <code class="type">point</code> )
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Converts any two corner points to box.
+ </p>
+ <p>
+ <code class="literal">box(point '(0,1)', point '(1,0)')</code>
+ → <code class="returnvalue">(1,1),(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">box</code> ( <code class="type">polygon</code> )
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Computes bounding box of polygon.
+ </p>
+ <p>
+ <code class="literal">box(polygon '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">(2,1),(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">bound_box</code> ( <code class="type">box</code>, <code class="type">box</code> )
+ → <code class="returnvalue">box</code>
+ </p>
+ <p>
+ Computes bounding box of two boxes.
+ </p>
+ <p>
+ <code class="literal">bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)')</code>
+ → <code class="returnvalue">(4,4),(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">circle</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">circle</code>
+ </p>
+ <p>
+ Computes smallest circle enclosing box.
+ </p>
+ <p>
+ <code class="literal">circle(box '(1,1),(0,0)')</code>
+ → <code class="returnvalue">&lt;(0.5,0.5),0.7071067811865476&gt;</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">circle</code> ( <code class="type">point</code>, <code class="type">double precision</code> )
+ → <code class="returnvalue">circle</code>
+ </p>
+ <p>
+ Constructs circle from center and radius.
+ </p>
+ <p>
+ <code class="literal">circle(point '(0,0)', 2.0)</code>
+ → <code class="returnvalue">&lt;(0,0),2&gt;</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">circle</code> ( <code class="type">polygon</code> )
+ → <code class="returnvalue">circle</code>
+ </p>
+ <p>
+ Converts polygon to circle. The circle's center is the mean of the
+ positions of the polygon's points, and the radius is the average
+ distance of the polygon's points from that center.
+ </p>
+ <p>
+ <code class="literal">circle(polygon '((0,0),(1,3),(2,0))')</code>
+ → <code class="returnvalue">&lt;(1,1),1.6094757082487299&gt;</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">line</code> ( <code class="type">point</code>, <code class="type">point</code> )
+ → <code class="returnvalue">line</code>
+ </p>
+ <p>
+ Converts two points to the line through them.
+ </p>
+ <p>
+ <code class="literal">line(point '(-1,0)', point '(1,0)')</code>
+ → <code class="returnvalue">{0,-1,0}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">lseg</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">lseg</code>
+ </p>
+ <p>
+ Extracts box's diagonal as a line segment.
+ </p>
+ <p>
+ <code class="literal">lseg(box '(1,0),(-1,0)')</code>
+ → <code class="returnvalue">[(1,0),(-1,0)]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">lseg</code> ( <code class="type">point</code>, <code class="type">point</code> )
+ → <code class="returnvalue">lseg</code>
+ </p>
+ <p>
+ Constructs line segment from two endpoints.
+ </p>
+ <p>
+ <code class="literal">lseg(point '(-1,0)', point '(1,0)')</code>
+ → <code class="returnvalue">[(-1,0),(1,0)]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">path</code> ( <code class="type">polygon</code> )
+ → <code class="returnvalue">path</code>
+ </p>
+ <p>
+ Converts polygon to a closed path with the same list of points.
+ </p>
+ <p>
+ <code class="literal">path(polygon '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">((0,0),(1,1),(2,0))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">point</code> ( <code class="type">double precision</code>, <code class="type">double precision</code> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Constructs point from its coordinates.
+ </p>
+ <p>
+ <code class="literal">point(23.4, -44.5)</code>
+ → <code class="returnvalue">(23.4,-44.5)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">point</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes center of box.
+ </p>
+ <p>
+ <code class="literal">point(box '(1,0),(-1,0)')</code>
+ → <code class="returnvalue">(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">point</code> ( <code class="type">circle</code> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes center of circle.
+ </p>
+ <p>
+ <code class="literal">point(circle '&lt;(0,0),2&gt;')</code>
+ → <code class="returnvalue">(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">point</code> ( <code class="type">lseg</code> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes center of line segment.
+ </p>
+ <p>
+ <code class="literal">point(lseg '[(-1,0),(1,0)]')</code>
+ → <code class="returnvalue">(0,0)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">point</code> ( <code class="type">polygon</code> )
+ → <code class="returnvalue">point</code>
+ </p>
+ <p>
+ Computes center of polygon (the mean of the
+ positions of the polygon's points).
+ </p>
+ <p>
+ <code class="literal">point(polygon '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">(1,0.3333333333333333)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.17.7.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">polygon</code> ( <code class="type">box</code> )
+ → <code class="returnvalue">polygon</code>
+ </p>
+ <p>
+ Converts box to a 4-point polygon.
+ </p>
+ <p>
+ <code class="literal">polygon(box '(1,1),(0,0)')</code>
+ → <code class="returnvalue">((0,0),(0,1),(1,1),(1,0))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">polygon</code> ( <code class="type">circle</code> )
+ → <code class="returnvalue">polygon</code>
+ </p>
+ <p>
+ Converts circle to a 12-point polygon.
+ </p>
+ <p>
+ <code class="literal">polygon(circle '&lt;(0,0),2&gt;')</code>
+ → <code class="returnvalue">((-2,0),​(-1.7320508075688774,0.9999999999999999),​(-1.0000000000000002,1.7320508075688772),​(-1.2246063538223773e-16,2),​(0.9999999999999996,1.7320508075688774),​(1.732050807568877,1.0000000000000007),​(2,2.4492127076447545e-16),​(1.7320508075688776,-0.9999999999999994),​(1.0000000000000009,-1.7320508075688767),​(3.673819061467132e-16,-2),​(-0.9999999999999987,-1.732050807568878),​(-1.7320508075688767,-1.0000000000000009))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">polygon</code> ( <code class="type">integer</code>, <code class="type">circle</code> )
+ → <code class="returnvalue">polygon</code>
+ </p>
+ <p>
+ Converts circle to an <em class="replaceable"><code>n</code></em>-point polygon.
+ </p>
+ <p>
+ <code class="literal">polygon(4, circle '&lt;(3,0),1&gt;')</code>
+ → <code class="returnvalue">((2,0),​(3,1),​(4,1.2246063538223773e-16),​(3,-1))</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">polygon</code> ( <code class="type">path</code> )
+ → <code class="returnvalue">polygon</code>
+ </p>
+ <p>
+ Converts closed path to a polygon with the same list of points.
+ </p>
+ <p>
+ <code class="literal">polygon(path '((0,0),(1,1),(2,0))')</code>
+ → <code class="returnvalue">((0,0),(1,1),(2,0))</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ It is possible to access the two component numbers of a <code class="type">point</code>
+ as though the point were an array with indexes 0 and 1. For example, if
+ <code class="literal">t.p</code> is a <code class="type">point</code> column then
+ <code class="literal">SELECT p[0] FROM t</code> retrieves the X coordinate and
+ <code class="literal">UPDATE t SET p[1] = ...</code> changes the Y coordinate.
+ In the same way, a value of type <code class="type">box</code> or <code class="type">lseg</code> can be treated
+ as an array of two <code class="type">point</code> values.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-enum.html" title="9.10. Enum Support Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-net.html" title="9.12. Network Address Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.10. Enum Support Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.12. Network Address Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-info.html b/doc/src/sgml/html/functions-info.html
new file mode 100644
index 0000000..51268ad
--- /dev/null
+++ b/doc/src/sgml/html/functions-info.html
@@ -0,0 +1,1774 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.26. System Information Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-srf.html" title="9.25. Set Returning Functions" /><link rel="next" href="functions-admin.html" title="9.27. System Administration Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.26. System Information Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-srf.html" title="9.25. Set Returning Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-admin.html" title="9.27. System Administration Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-INFO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.26. System Information Functions and Operators</h2></div></div></div><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-SESSION-TABLE" title="Table 9.66. Session Information Functions">Table 9.66</a> shows several
+ functions that extract session and system information.
+ </p><p>
+ 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 <a class="xref" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS" title="28.2.24. Statistics Functions">Section 28.2.24</a> for more
+ information.
+ </p><div class="table" id="FUNCTIONS-INFO-SESSION-TABLE"><p class="title"><strong>Table 9.66. Session Information Functions</strong></p><div class="table-contents"><table class="table" summary="Session Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">current_catalog</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.1.1.2.1" class="indexterm"></a>
+ <code class="function">current_database</code> ()
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns the name of the current database. (Databases are
+ called <span class="quote">“<span class="quote">catalogs</span>”</span> in the SQL standard,
+ so <code class="function">current_catalog</code> is the standard's
+ spelling.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">current_query</code> ()
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the text of the currently executing query, as submitted
+ by the client (which might contain more than one statement).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">current_role</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ This is equivalent to <code class="function">current_user</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.4.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.4.1.1.2" class="indexterm"></a>
+ <code class="function">current_schema</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">current_schema</code> ()
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns the name of the schema that is first in the search path (or a
+ null value if the search path is empty). This is the schema that will
+ be used for any tables or other named objects that are created without
+ specifying a target schema.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.5.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.5.1.1.2" class="indexterm"></a>
+ <code class="function">current_schemas</code> ( <em class="parameter"><code>include_implicit</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">name[]</code>
+ </p>
+ <p>
+ Returns an array of the names of all schemas presently in the
+ effective search path, in their priority order. (Items in the current
+ <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> setting that do not correspond to
+ existing, searchable schemas are omitted.) If the Boolean argument
+ is <code class="literal">true</code>, then implicitly-searched system schemas
+ such as <code class="literal">pg_catalog</code> are included in the result.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.6.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.6.1.1.2" class="indexterm"></a>
+ <code class="function">current_user</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns the user name of the current execution context.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">inet_client_addr</code> ()
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Returns the IP address of the current client,
+ or <code class="literal">NULL</code> if the current connection is via a
+ Unix-domain socket.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">inet_client_port</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the IP port number of the current client,
+ or <code class="literal">NULL</code> if the current connection is via a
+ Unix-domain socket.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">inet_server_addr</code> ()
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Returns the IP address on which the server accepted the current
+ connection,
+ or <code class="literal">NULL</code> if the current connection is via a
+ Unix-domain socket.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">inet_server_port</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the IP port number on which the server accepted the current
+ connection,
+ or <code class="literal">NULL</code> if the current connection is via a
+ Unix-domain socket.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_backend_pid</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the process ID of the server process attached to the current
+ session.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_blocking_pids</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Returns an array of the process ID(s) of the sessions that are
+ blocking the server process with the specified process ID from
+ acquiring a lock, or an empty array if there is no such server process
+ or it is not blocked.
+ </p>
+ <p>
+ One server process blocks another if it either holds a lock that
+ conflicts with the blocked process's lock request (hard block), or is
+ waiting for a lock that would conflict with the blocked process's lock
+ request and is ahead of it in the wait queue (soft block). When using
+ parallel queries the result always lists client-visible process IDs
+ (that is, <code class="function">pg_backend_pid</code> results) even if the
+ actual lock is held or awaited by a child worker process. As a result
+ of that, there may be duplicated PIDs in the result. Also note that
+ when a prepared transaction holds a conflicting lock, it will be
+ represented by a zero process ID.
+ </p>
+ <p>
+ Frequent calls to this function could have some impact on database
+ performance, because it needs exclusive access to the lock manager's
+ shared state for a short time.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">pg_conf_load_time</code> ()
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time when the server configuration files were last loaded.
+ If the current session was alive at the time, this will be the time
+ when the session itself re-read the configuration files (so the
+ reading will vary a little in different sessions). Otherwise it is
+ the time when the postmaster process re-read the configuration files.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.14.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.14.1.1.2" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.14.1.1.3" class="indexterm"></a>
+ <a id="id-1.5.8.32.4.2.2.14.1.1.4" class="indexterm"></a>
+ <code class="function">pg_current_logfile</code> ( [<span class="optional"> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the path name of the log file currently in use by the logging
+ collector. The path includes the <a class="xref" href="runtime-config-logging.html#GUC-LOG-DIRECTORY">log_directory</a>
+ directory and the individual log file name. The result
+ is <code class="literal">NULL</code> if the logging collector is disabled.
+ When multiple log files exist, each in a different
+ format, <code class="function">pg_current_logfile</code> without an argument
+ returns the path of the file having the first format found in the
+ ordered list: <code class="literal">stderr</code>,
+ <code class="literal">csvlog</code>, <code class="literal">jsonlog</code>.
+ <code class="literal">NULL</code> is returned if no log file has any of these
+ formats.
+ To request information about a specific log file format, supply
+ either <code class="literal">csvlog</code>, <code class="literal">jsonlog</code> or
+ <code class="literal">stderr</code> as the
+ value of the optional parameter. The result is <code class="literal">NULL</code>
+ if the log format requested is not configured in
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-DESTINATION">log_destination</a>.
+ The result reflects the contents of
+ the <code class="filename">current_logfiles</code> file.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">pg_my_temp_schema</code> ()
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Returns the OID of the current session's temporary schema, or zero if
+ it has none (because it has not created any temporary tables).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">pg_is_other_temp_schema</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if the given OID is the OID of another session's
+ temporary schema. (This can be useful, for example, to exclude other
+ sessions' temporary tables from a catalog display.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">pg_jit_available</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if a <acronym class="acronym">JIT</acronym> compiler extension is
+ available (see <a class="xref" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Chapter 32</a>) and the
+ <a class="xref" href="runtime-config-query.html#GUC-JIT">jit</a> configuration parameter is set to
+ <code class="literal">on</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">pg_listening_channels</code> ()
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Returns the set of names of asynchronous notification channels that
+ the current session is listening to.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">pg_notification_queue_usage</code> ()
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Returns the fraction (0–1) of the asynchronous notification
+ queue's maximum size that is currently occupied by notifications that
+ are waiting to be processed.
+ See <a class="xref" href="sql-listen.html" title="LISTEN"><span class="refentrytitle">LISTEN</span></a> and <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>
+ for more information.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.20.1.1.1" class="indexterm"></a>
+ <code class="function">pg_postmaster_start_time</code> ()
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time when the server started.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">pg_safe_snapshot_blocking_pids</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Returns an array of the process ID(s) of the sessions that are blocking
+ the server process with the specified process ID from acquiring a safe
+ snapshot, or an empty array if there is no such server process or it
+ is not blocked.
+ </p>
+ <p>
+ A session running a <code class="literal">SERIALIZABLE</code> transaction blocks
+ a <code class="literal">SERIALIZABLE READ ONLY DEFERRABLE</code> transaction
+ from acquiring a snapshot until the latter determines that it is safe
+ to avoid taking any predicate locks. See
+ <a class="xref" href="transaction-iso.html#XACT-SERIALIZABLE" title="13.2.3. Serializable Isolation Level">Section 13.2.3</a> for more information about
+ serializable and deferrable transactions.
+ </p>
+ <p>
+ Frequent calls to this function could have some impact on database
+ performance, because it needs access to the predicate lock manager's
+ shared state for a short time.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">pg_trigger_depth</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the current nesting level
+ of <span class="productname">PostgreSQL</span> triggers (0 if not called,
+ directly or indirectly, from inside a trigger).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">session_user</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns the session user's name.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.24.1.1.1" class="indexterm"></a>
+ <code class="function">user</code>
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ This is equivalent to <code class="function">current_user</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.4.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">version</code> ()
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns a string describing the <span class="productname">PostgreSQL</span>
+ server's version. You can also get this information from
+ <a class="xref" href="runtime-config-preset.html#GUC-SERVER-VERSION">server_version</a>, or for a machine-readable
+ version use <a class="xref" href="runtime-config-preset.html#GUC-SERVER-VERSION-NUM">server_version_num</a>. Software
+ developers should use <code class="varname">server_version_num</code> (available
+ since 8.2) or <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a> instead of
+ parsing the text version.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">current_catalog</code>,
+ <code class="function">current_role</code>,
+ <code class="function">current_schema</code>,
+ <code class="function">current_user</code>,
+ <code class="function">session_user</code>,
+ and <code class="function">user</code> have special syntactic status
+ in <acronym class="acronym">SQL</acronym>: they must be called without trailing
+ parentheses. In PostgreSQL, parentheses can optionally be used with
+ <code class="function">current_schema</code>, but not with the others.
+ </p></div><p>
+ The <code class="function">session_user</code> is normally the user who initiated
+ the current database connection; but superusers can change this setting
+ with <a class="xref" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION"><span class="refentrytitle">SET SESSION AUTHORIZATION</span></a>.
+ The <code class="function">current_user</code> is the user identifier
+ that is applicable for permission checking. Normally it is equal
+ to the session user, but it can be changed with
+ <a class="xref" href="sql-set-role.html" title="SET ROLE"><span class="refentrytitle">SET ROLE</span></a>.
+ It also changes during the execution of
+ functions with the attribute <code class="literal">SECURITY DEFINER</code>.
+ In Unix parlance, the session user is the <span class="quote">“<span class="quote">real user</span>”</span> and
+ the current user is the <span class="quote">“<span class="quote">effective user</span>”</span>.
+ <code class="function">current_role</code> and <code class="function">user</code> are
+ synonyms for <code class="function">current_user</code>. (The SQL standard draws
+ a distinction between <code class="function">current_role</code>
+ and <code class="function">current_user</code>, but <span class="productname">PostgreSQL</span>
+ does not, since it unifies users and roles into a single kind of entity.)
+ </p><a id="id-1.5.8.32.7" class="indexterm"></a><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-ACCESS-TABLE" title="Table 9.67. Access Privilege Inquiry Functions">Table 9.67</a> lists functions that
+ allow querying object access privileges programmatically.
+ (See <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for more information about
+ privileges.)
+ In these functions, the user whose privileges are being inquired about
+ can be specified by name or by OID
+ (<code class="structname">pg_authid</code>.<code class="structfield">oid</code>), or if
+ the name is given as <code class="literal">public</code> then the privileges of the
+ PUBLIC pseudo-role are checked. Also, the <em class="parameter"><code>user</code></em>
+ argument can be omitted entirely, in which case
+ the <code class="function">current_user</code> is assumed.
+ The object that is being inquired about can be specified either by name or
+ by OID, too. When specifying by name, a schema name can be included if
+ relevant.
+ The access privilege of interest is specified by a text string, which must
+ evaluate to one of the appropriate privilege keywords for the object's type
+ (e.g., <code class="literal">SELECT</code>). Optionally, <code class="literal">WITH GRANT
+ OPTION</code> can be added to a privilege type to test whether the
+ privilege is held with grant option. Also, multiple privilege types can be
+ listed separated by commas, in which case the result will be true if any of
+ the listed privileges is held. (Case of the privilege string is not
+ significant, and extra whitespace is allowed between but not within
+ privilege names.)
+ Some examples:
+</p><pre class="programlisting">
+SELECT has_table_privilege('myschema.mytable', 'select');
+SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
+</pre><p>
+ </p><div class="table" id="FUNCTIONS-INFO-ACCESS-TABLE"><p class="title"><strong>Table 9.67. Access Privilege Inquiry Functions</strong></p><div class="table-contents"><table class="table" summary="Access Privilege Inquiry Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">has_any_column_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>table</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for any column of table?
+ This succeeds either if the privilege is held for the whole table, or
+ if there is a column-level grant of the privilege for at least one
+ column.
+ Allowable privilege types are
+ <code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, and <code class="literal">REFERENCES</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">has_column_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>table</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>column</code></em> <code class="type">text</code> or <code class="type">smallint</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for the specified table column?
+ This succeeds either if the privilege is held for the whole table, or
+ if there is a column-level grant of the privilege for the column.
+ The column can be specified by name or by attribute number
+ (<code class="structname">pg_attribute</code>.<code class="structfield">attnum</code>).
+ Allowable privilege types are
+ <code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, and <code class="literal">REFERENCES</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">has_database_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>database</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for database?
+ Allowable privilege types are
+ <code class="literal">CREATE</code>,
+ <code class="literal">CONNECT</code>,
+ <code class="literal">TEMPORARY</code>, and
+ <code class="literal">TEMP</code> (which is equivalent to
+ <code class="literal">TEMPORARY</code>).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">has_foreign_data_wrapper_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>fdw</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for foreign-data wrapper?
+ The only allowable privilege type is <code class="literal">USAGE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">has_function_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>function</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for function?
+ The only allowable privilege type is <code class="literal">EXECUTE</code>.
+ </p>
+ <p>
+ When specifying a function by name rather than by OID, the allowed
+ input is the same as for the <code class="type">regprocedure</code> data type (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>).
+ An example is:
+</p><pre class="programlisting">
+SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">has_language_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>language</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for language?
+ The only allowable privilege type is <code class="literal">USAGE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">has_parameter_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>parameter</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for configuration parameter?
+ The parameter name is case-insensitive.
+ Allowable privilege types are <code class="literal">SET</code>
+ and <code class="literal">ALTER SYSTEM</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">has_schema_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>schema</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for schema?
+ Allowable privilege types are
+ <code class="literal">CREATE</code> and
+ <code class="literal">USAGE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">has_sequence_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>sequence</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for sequence?
+ Allowable privilege types are
+ <code class="literal">USAGE</code>,
+ <code class="literal">SELECT</code>, and
+ <code class="literal">UPDATE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">has_server_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>server</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for foreign server?
+ The only allowable privilege type is <code class="literal">USAGE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">has_table_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>table</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for table?
+ Allowable privilege types
+ are <code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>,
+ <code class="literal">TRUNCATE</code>, <code class="literal">REFERENCES</code>,
+ and <code class="literal">TRIGGER</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">has_tablespace_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>tablespace</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for tablespace?
+ The only allowable privilege type is <code class="literal">CREATE</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">has_type_privilege</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>type</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for data type?
+ The only allowable privilege type is <code class="literal">USAGE</code>.
+ When specifying a type by name rather than by OID, the allowed input
+ is the same as for the <code class="type">regtype</code> data type (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">pg_has_role</code> (
+ [<span class="optional"> <em class="parameter"><code>user</code></em> <code class="type">name</code> or <code class="type">oid</code>, </span>]
+ <em class="parameter"><code>role</code></em> <code class="type">text</code> or <code class="type">oid</code>,
+ <em class="parameter"><code>privilege</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does user have privilege for role?
+ Allowable privilege types are
+ <code class="literal">MEMBER</code> and <code class="literal">USAGE</code>.
+ <code class="literal">MEMBER</code> denotes direct or indirect membership in
+ the role (that is, the right to do <code class="command">SET ROLE</code>), while
+ <code class="literal">USAGE</code> denotes whether the privileges of the role
+ are immediately available without doing <code class="command">SET ROLE</code>.
+ This function does not allow the special case of
+ setting <em class="parameter"><code>user</code></em> to <code class="literal">public</code>,
+ because the PUBLIC pseudo-role can never be a member of real roles.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.9.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">row_security_active</code> (
+ <em class="parameter"><code>table</code></em> <code class="type">text</code> or <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is row-level security active for the specified table in the context of
+ the current user and current environment?
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-ACLITEM-OP-TABLE" title="Table 9.68. aclitem Operators">Table 9.68</a> shows the operators
+ available for the <code class="type">aclitem</code> type, which is the catalog
+ representation of access privileges. See <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>
+ for information about how to read access privilege values.
+ </p><div class="table" id="FUNCTIONS-ACLITEM-OP-TABLE"><p class="title"><strong>Table 9.68. <code class="type">aclitem</code> Operators</strong></p><div class="table-contents"><table class="table" summary="aclitem Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.11.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="type">aclitem</code> <code class="literal">=</code> <code class="type">aclitem</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are <code class="type">aclitem</code>s equal? (Notice that
+ type <code class="type">aclitem</code> lacks the usual set of comparison
+ operators; it has only equality. In turn, <code class="type">aclitem</code>
+ arrays can only be compared for equality.)
+ </p>
+ <p>
+ <code class="literal">'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.11.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="type">aclitem[]</code> <code class="literal">@&gt;</code> <code class="type">aclitem</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array contain the specified privileges? (This is true if there
+ is an array entry that matches the <code class="type">aclitem</code>'s grantee and
+ grantor, and has at least the specified set of privileges.)
+ </p>
+ <p>
+ <code class="literal">'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @&gt; 'calvin=r*/hobbes'::aclitem</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">aclitem[]</code> <code class="literal">~</code> <code class="type">aclitem</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ This is a deprecated alias for <code class="literal">@&gt;</code>.
+ </p>
+ <p>
+ <code class="literal">'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-ACLITEM-FN-TABLE" title="Table 9.69. aclitem Functions">Table 9.69</a> shows some additional
+ functions to manage the <code class="type">aclitem</code> type.
+ </p><div class="table" id="FUNCTIONS-ACLITEM-FN-TABLE"><p class="title"><strong>Table 9.69. <code class="type">aclitem</code> Functions</strong></p><div class="table-contents"><table class="table" summary="aclitem Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.13.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">acldefault</code> (
+ <em class="parameter"><code>type</code></em> <code class="type">"char"</code>,
+ <em class="parameter"><code>ownerId</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">aclitem[]</code>
+ </p>
+ <p>
+ Constructs an <code class="type">aclitem</code> array holding the default access
+ privileges for an object of type <em class="parameter"><code>type</code></em> belonging
+ to the role with OID <em class="parameter"><code>ownerId</code></em>. This represents
+ the access privileges that will be assumed when an object's ACL entry
+ is null. (The default access privileges are described in
+ <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.)
+ The <em class="parameter"><code>type</code></em> parameter must be one of
+ 'c' for <code class="literal">COLUMN</code>,
+ 'r' for <code class="literal">TABLE</code> and table-like objects,
+ 's' for <code class="literal">SEQUENCE</code>,
+ 'd' for <code class="literal">DATABASE</code>,
+ 'f' for <code class="literal">FUNCTION</code> or <code class="literal">PROCEDURE</code>,
+ 'l' for <code class="literal">LANGUAGE</code>,
+ 'L' for <code class="literal">LARGE OBJECT</code>,
+ 'n' for <code class="literal">SCHEMA</code>,
+ 'p' for <code class="literal">PARAMETER</code>,
+ 't' for <code class="literal">TABLESPACE</code>,
+ 'F' for <code class="literal">FOREIGN DATA WRAPPER</code>,
+ 'S' for <code class="literal">FOREIGN SERVER</code>,
+ or
+ 'T' for <code class="literal">TYPE</code> or <code class="literal">DOMAIN</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.13.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">aclexplode</code> ( <code class="type">aclitem[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>grantor</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>grantee</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>privilege_type</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>is_grantable</code></em> <code class="type">boolean</code> )
+ </p>
+ <p>
+ Returns the <code class="type">aclitem</code> array as a set of rows.
+ If the grantee is the pseudo-role PUBLIC, it is represented by zero in
+ the <em class="parameter"><code>grantee</code></em> column. Each granted privilege is
+ represented as <code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ etc. Note that each privilege is broken out as a separate row, so
+ only one keyword appears in the <em class="parameter"><code>privilege_type</code></em>
+ column.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.13.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">makeaclitem</code> (
+ <em class="parameter"><code>grantee</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>grantor</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>privileges</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>is_grantable</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">aclitem</code>
+ </p>
+ <p>
+ Constructs an <code class="type">aclitem</code> with the given properties.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-SCHEMA-TABLE" title="Table 9.70. Schema Visibility Inquiry Functions">Table 9.70</a> shows functions that
+ determine whether a certain object is <em class="firstterm">visible</em> in the
+ current schema search path.
+ For example, a table is said to be visible if its
+ containing schema is in the search path and no table of the same
+ name appears earlier in the search path. This is equivalent to the
+ statement that the table can be referenced by name without explicit
+ schema qualification. Thus, to list the names of all visible tables:
+</p><pre class="programlisting">
+SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
+</pre><p>
+ For functions and operators, an object in the search path is said to be
+ visible if there is no object of the same name <span class="emphasis"><em>and argument data
+ type(s)</em></span> earlier in the path. For operator classes and families,
+ both the name and the associated index access method are considered.
+ </p><a id="id-1.5.8.32.15" class="indexterm"></a><div class="table" id="FUNCTIONS-INFO-SCHEMA-TABLE"><p class="title"><strong>Table 9.70. Schema Visibility Inquiry Functions</strong></p><div class="table-contents"><table class="table" summary="Schema Visibility Inquiry Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_collation_is_visible</code> ( <em class="parameter"><code>collation</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is collation visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_conversion_is_visible</code> ( <em class="parameter"><code>conversion</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is conversion visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_function_is_visible</code> ( <em class="parameter"><code>function</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is function visible in search path?
+ (This also works for procedures and aggregates.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_opclass_is_visible</code> ( <em class="parameter"><code>opclass</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is operator class visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_operator_is_visible</code> ( <em class="parameter"><code>operator</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is operator visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_opfamily_is_visible</code> ( <em class="parameter"><code>opclass</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is operator family visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_statistics_obj_is_visible</code> ( <em class="parameter"><code>stat</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is statistics object visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_table_is_visible</code> ( <em class="parameter"><code>table</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is table visible in search path?
+ (This works for all types of relations, including views, materialized
+ views, indexes, sequences and foreign tables.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ts_config_is_visible</code> ( <em class="parameter"><code>config</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is text search configuration visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ts_dict_is_visible</code> ( <em class="parameter"><code>dict</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is text search dictionary visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ts_parser_is_visible</code> ( <em class="parameter"><code>parser</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is text search parser visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_ts_template_is_visible</code> ( <em class="parameter"><code>template</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is text search template visible in search path?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.16.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">pg_type_is_visible</code> ( <em class="parameter"><code>type</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is type (or domain) visible in search path?
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ All these functions require object OIDs to identify the object to be
+ checked. If you want to test an object by name, it is convenient to use
+ the OID alias types (<code class="type">regclass</code>, <code class="type">regtype</code>,
+ <code class="type">regprocedure</code>, <code class="type">regoperator</code>, <code class="type">regconfig</code>,
+ or <code class="type">regdictionary</code>),
+ for example:
+</p><pre class="programlisting">
+SELECT pg_type_is_visible('myschema.widget'::regtype);
+</pre><p>
+ Note that it would not make much sense to test a non-schema-qualified
+ type name in this way — if the name can be recognized at all, it must be visible.
+ </p><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-CATALOG-TABLE" title="Table 9.71. System Catalog Information Functions">Table 9.71</a> lists functions that
+ extract information from the system catalogs.
+ </p><div class="table" id="FUNCTIONS-INFO-CATALOG-TABLE"><p class="title"><strong>Table 9.71. System Catalog Information Functions</strong></p><div class="table-contents"><table class="table" summary="System Catalog Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">format_type</code> ( <em class="parameter"><code>type</code></em> <code class="type">oid</code>, <em class="parameter"><code>typemod</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the SQL name for a data type that is identified by its type
+ OID and possibly a type modifier. Pass NULL for the type modifier if
+ no specific modifier is known.
+ </p></td></tr><tr><td id="PG-CHAR-TO-ENCODING" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_char_to_encoding</code> ( <em class="parameter"><code>encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Converts the supplied encoding name into an integer representing the
+ internal identifier used in some system catalog tables.
+ Returns <code class="literal">-1</code> if an unknown encoding name is provided.
+ </p></td></tr><tr><td id="PG-ENCODING-TO-CHAR" class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_encoding_to_char</code> ( <em class="parameter"><code>encoding</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Converts the integer used as the internal identifier of an encoding in some
+ system catalog tables into a human-readable string.
+ Returns an empty string if an invalid encoding number is provided.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_catalog_foreign_keys</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>fktable</code></em> <code class="type">regclass</code>,
+ <em class="parameter"><code>fkcols</code></em> <code class="type">text[]</code>,
+ <em class="parameter"><code>pktable</code></em> <code class="type">regclass</code>,
+ <em class="parameter"><code>pkcols</code></em> <code class="type">text[]</code>,
+ <em class="parameter"><code>is_array</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>is_opt</code></em> <code class="type">boolean</code> )
+ </p>
+ <p>
+ Returns a set of records describing the foreign key relationships
+ that exist within the <span class="productname">PostgreSQL</span> system
+ catalogs.
+ The <em class="parameter"><code>fktable</code></em> column contains the name of the
+ referencing catalog, and the <em class="parameter"><code>fkcols</code></em> column
+ contains the name(s) of the referencing column(s). Similarly,
+ the <em class="parameter"><code>pktable</code></em> column contains the name of the
+ referenced catalog, and the <em class="parameter"><code>pkcols</code></em> column
+ contains the name(s) of the referenced column(s).
+ If <em class="parameter"><code>is_array</code></em> is true, the last referencing
+ column is an array, each of whose elements should match some entry
+ in the referenced catalog.
+ If <em class="parameter"><code>is_opt</code></em> is true, the referencing column(s)
+ are allowed to contain zeroes instead of a valid reference.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_constraintdef</code> ( <em class="parameter"><code>constraint</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for a constraint.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_expr</code> ( <em class="parameter"><code>expr</code></em> <code class="type">pg_node_tree</code>, <em class="parameter"><code>relation</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Decompiles the internal form of an expression stored in the system
+ catalogs, such as the default value for a column. If the expression
+ might contain Vars, specify the OID of the relation they refer to as
+ the second parameter; if no Vars are expected, passing zero is
+ sufficient.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_functiondef</code> ( <em class="parameter"><code>func</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for a function or procedure.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ The result is a complete <code class="command">CREATE OR REPLACE FUNCTION</code>
+ or <code class="command">CREATE OR REPLACE PROCEDURE</code> statement.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_function_arguments</code> ( <em class="parameter"><code>func</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the argument list of a function or procedure, in the form
+ it would need to appear in within <code class="command">CREATE FUNCTION</code>
+ (including default values).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_function_identity_arguments</code> ( <em class="parameter"><code>func</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the argument list necessary to identify a function or
+ procedure, in the form it would need to appear in within commands such
+ as <code class="command">ALTER FUNCTION</code>. This form omits default values.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_function_result</code> ( <em class="parameter"><code>func</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the <code class="literal">RETURNS</code> clause of a function, in
+ the form it would need to appear in within <code class="command">CREATE
+ FUNCTION</code>. Returns <code class="literal">NULL</code> for a procedure.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_indexdef</code> ( <em class="parameter"><code>index</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>column</code></em> <code class="type">integer</code>, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for an index.
+ (This is a decompiled reconstruction, not the original text
+ of the command.) If <em class="parameter"><code>column</code></em> is supplied and is
+ not zero, only the definition of that column is reconstructed.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_keywords</code> ()
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>word</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>catcode</code></em> <code class="type">"char"</code>,
+ <em class="parameter"><code>barelabel</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>catdesc</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>baredesc</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns a set of records describing the SQL keywords recognized by the
+ server. The <em class="parameter"><code>word</code></em> column contains the
+ keyword. The <em class="parameter"><code>catcode</code></em> column contains a
+ category code: <code class="literal">U</code> for an unreserved
+ keyword, <code class="literal">C</code> for a keyword that can be a column
+ name, <code class="literal">T</code> for a keyword that can be a type or
+ function name, or <code class="literal">R</code> for a fully reserved keyword.
+ The <em class="parameter"><code>barelabel</code></em> column
+ contains <code class="literal">true</code> if the keyword can be used as
+ a <span class="quote">“<span class="quote">bare</span>”</span> column label in <code class="command">SELECT</code> lists,
+ or <code class="literal">false</code> if it can only be used
+ after <code class="literal">AS</code>.
+ The <em class="parameter"><code>catdesc</code></em> column contains a
+ possibly-localized string describing the keyword's category.
+ The <em class="parameter"><code>baredesc</code></em> column contains a
+ possibly-localized string describing the keyword's column label status.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_ruledef</code> ( <em class="parameter"><code>rule</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for a rule.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_serial_sequence</code> ( <em class="parameter"><code>table</code></em> <code class="type">text</code>, <em class="parameter"><code>column</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the name of the sequence associated with a column,
+ or NULL if no sequence is associated with the column.
+ If the column is an identity column, the associated sequence is the
+ sequence internally created for that column.
+ For columns created using one of the serial types
+ (<code class="type">serial</code>, <code class="type">smallserial</code>, <code class="type">bigserial</code>),
+ it is the sequence created for that serial column definition.
+ In the latter case, the association can be modified or removed
+ with <code class="command">ALTER SEQUENCE OWNED BY</code>.
+ (This function probably should have been
+ called <code class="function">pg_get_owned_sequence</code>; its current name
+ reflects the fact that it has historically been used with serial-type
+ columns.) The first parameter is a table name with optional
+ schema, and the second parameter is a column name. Because the first
+ parameter potentially contains both schema and table names, it is
+ parsed per usual SQL rules, meaning it is lower-cased by default.
+ The second parameter, being just a column name, is treated literally
+ and so has its case preserved. The result is suitably formatted
+ for passing to the sequence functions (see
+ <a class="xref" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Section 9.17</a>).
+ </p>
+ <p>
+ A typical use is in reading the current value of the sequence for an
+ identity or serial column, for example:
+</p><pre class="programlisting">
+SELECT currval(pg_get_serial_sequence('sometable', 'id'));
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_statisticsobjdef</code> ( <em class="parameter"><code>statobj</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for an extended statistics object.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.16.1.1.1" class="indexterm"></a>
+<code class="function">pg_get_triggerdef</code> ( <em class="parameter"><code>trigger</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the creating command for a trigger.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_userbyid</code> ( <em class="parameter"><code>role</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns a role's name given its OID.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_viewdef</code> ( <em class="parameter"><code>view</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the underlying <code class="command">SELECT</code> command for a
+ view or materialized view. (This is a decompiled reconstruction, not
+ the original text of the command.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_get_viewdef</code> ( <em class="parameter"><code>view</code></em> <code class="type">oid</code>, <em class="parameter"><code>wrap_column</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the underlying <code class="command">SELECT</code> command for a
+ view or materialized view. (This is a decompiled reconstruction, not
+ the original text of the command.) In this form of the function,
+ pretty-printing is always enabled, and long lines are wrapped to try
+ to keep them shorter than the specified number of columns.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_get_viewdef</code> ( <em class="parameter"><code>view</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>pretty</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reconstructs the underlying <code class="command">SELECT</code> command for a
+ view or materialized view, working from a textual name for the view
+ rather than its OID. (This is deprecated; use the OID variant
+ instead.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">pg_index_column_has_property</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>column</code></em> <code class="type">integer</code>, <em class="parameter"><code>property</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether an index column has the named property.
+ Common index column properties are listed in
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-INDEX-COLUMN-PROPS" title="Table 9.72. Index Column Properties">Table 9.72</a>.
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ <code class="literal">NULL</code> 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.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">pg_index_has_property</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>property</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether an index has the named property.
+ Common index properties are listed in
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-INDEX-PROPS" title="Table 9.73. Index Properties">Table 9.73</a>.
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ <code class="literal">NULL</code> is returned if the property name is not known
+ or does not apply to the particular object, or if the OID does not
+ identify a valid object.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">pg_indexam_has_property</code> ( <em class="parameter"><code>am</code></em> <code class="type">oid</code>, <em class="parameter"><code>property</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether an index access method has the named property.
+ Access method properties are listed in
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-INDEXAM-PROPS" title="Table 9.74. Index Access Method Properties">Table 9.74</a>.
+ <code class="literal">NULL</code> is returned if the property name is not known
+ or does not apply to the particular object, or if the OID does not
+ identify a valid object.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.24.1.1.1" class="indexterm"></a>
+ <code class="function">pg_options_to_table</code> ( <em class="parameter"><code>options_array</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>option_name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>option_value</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns the set of storage options represented by a value from
+ <code class="structname">pg_class</code>.<code class="structfield">reloptions</code> or
+ <code class="structname">pg_attribute</code>.<code class="structfield">attoptions</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">pg_settings_get_flags</code> ( <em class="parameter"><code>guc</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Returns an array of the flags associated with the given GUC, or
+ <code class="literal">NULL</code> if it does not exist. The result is
+ an empty array if the GUC exists but there are no flags to show.
+ Only the most useful flags listed in
+ <a class="xref" href="functions-info.html#FUNCTIONS-PG-SETTINGS-FLAGS" title="Table 9.75. GUC Flags">Table 9.75</a> are exposed.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.26.1.1.1" class="indexterm"></a>
+ <code class="function">pg_tablespace_databases</code> ( <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">setof oid</code>
+ </p>
+ <p>
+ Returns the set of OIDs of databases that have objects stored in the
+ specified tablespace. If this function returns any rows, the
+ tablespace is not empty and cannot be dropped. To identify the specific
+ objects populating the tablespace, you will need to connect to the
+ database(s) identified by <code class="function">pg_tablespace_databases</code>
+ and query their <code class="structname">pg_class</code> catalogs.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.27.1.1.1" class="indexterm"></a>
+ <code class="function">pg_tablespace_location</code> ( <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the file system path that this tablespace is located in.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.28.1.1.1" class="indexterm"></a>
+ <code class="function">pg_typeof</code> ( <code class="type">"any"</code> )
+ → <code class="returnvalue">regtype</code>
+ </p>
+ <p>
+ Returns the OID of the data type of the value that is passed to it.
+ This can be helpful for troubleshooting or dynamically constructing
+ SQL queries. The function is declared as
+ returning <code class="type">regtype</code>, which is an OID alias type (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); this means that it is the same as an
+ OID for comparison purposes but displays as a type name.
+ </p>
+ <p>
+ For example:
+</p><pre class="programlisting">
+SELECT pg_typeof(33);
+ pg_typeof
+-----------
+ integer
+
+SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
+ typlen
+--------
+ 4
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.29.1.1.1" class="indexterm"></a>
+ <code class="function">COLLATION FOR</code> ( <code class="type">"any"</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the name of the collation of the value that is passed to it.
+ The value is quoted and schema-qualified if necessary. If no
+ collation was derived for the argument expression,
+ then <code class="literal">NULL</code> is returned. If the argument is not of a
+ collatable data type, then an error is raised.
+ </p>
+ <p>
+ For example:
+</p><pre class="programlisting">
+SELECT collation for (description) FROM pg_description LIMIT 1;
+ pg_collation_for
+------------------
+ "default"
+
+SELECT collation for ('foo' COLLATE "de_DE");
+ pg_collation_for
+------------------
+ "de_DE"
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.30.1.1.1" class="indexterm"></a>
+ <code class="function">to_regclass</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regclass</code>
+ </p>
+ <p>
+ Translates a textual relation name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regclass</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.31.1.1.1" class="indexterm"></a>
+ <code class="function">to_regcollation</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regcollation</code>
+ </p>
+ <p>
+ Translates a textual collation name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regcollation</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.32.1.1.1" class="indexterm"></a>
+ <code class="function">to_regnamespace</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regnamespace</code>
+ </p>
+ <p>
+ Translates a textual schema name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regnamespace</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.33.1.1.1" class="indexterm"></a>
+ <code class="function">to_regoper</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regoper</code>
+ </p>
+ <p>
+ Translates a textual operator name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regoper</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found or is ambiguous. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.34.1.1.1" class="indexterm"></a>
+ <code class="function">to_regoperator</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regoperator</code>
+ </p>
+ <p>
+ Translates a textual operator name (with parameter types) to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regoperator</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.35.1.1.1" class="indexterm"></a>
+ <code class="function">to_regproc</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regproc</code>
+ </p>
+ <p>
+ Translates a textual function or procedure name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regproc</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found or is ambiguous. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.36.1.1.1" class="indexterm"></a>
+ <code class="function">to_regprocedure</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regprocedure</code>
+ </p>
+ <p>
+ Translates a textual function or procedure name (with argument types) to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regprocedure</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.37.1.1.1" class="indexterm"></a>
+ <code class="function">to_regrole</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regrole</code>
+ </p>
+ <p>
+ Translates a textual role name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regrole</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.19.2.2.38.1.1.1" class="indexterm"></a>
+ <code class="function">to_regtype</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">regtype</code>
+ </p>
+ <p>
+ Translates a textual type name to its OID. A similar result is
+ obtained by casting the string to type <code class="type">regtype</code> (see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>); however, this function will return
+ <code class="literal">NULL</code> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Most of the functions that reconstruct (decompile) database objects
+ have an optional <em class="parameter"><code>pretty</code></em> flag, which
+ if <code class="literal">true</code> causes the result to
+ be <span class="quote">“<span class="quote">pretty-printed</span>”</span>. Pretty-printing suppresses unnecessary
+ parentheses and adds whitespace for legibility.
+ The pretty-printed format is more readable, but the default format
+ is more likely to be interpreted the same way by future versions of
+ <span class="productname">PostgreSQL</span>; so avoid using pretty-printed output
+ for dump purposes. Passing <code class="literal">false</code> for
+ the <em class="parameter"><code>pretty</code></em> parameter yields the same result as
+ omitting the parameter.
+ </p><div class="table" id="FUNCTIONS-INFO-INDEX-COLUMN-PROPS"><p class="title"><strong>Table 9.72. Index Column Properties</strong></p><div class="table-contents"><table class="table" summary="Index Column Properties" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">asc</code></td><td>Does the column sort in ascending order on a forward scan?
+ </td></tr><tr><td><code class="literal">desc</code></td><td>Does the column sort in descending order on a forward scan?
+ </td></tr><tr><td><code class="literal">nulls_first</code></td><td>Does the column sort with nulls first on a forward scan?
+ </td></tr><tr><td><code class="literal">nulls_last</code></td><td>Does the column sort with nulls last on a forward scan?
+ </td></tr><tr><td><code class="literal">orderable</code></td><td>Does the column possess any defined sort ordering?
+ </td></tr><tr><td><code class="literal">distance_orderable</code></td><td>Can the column be scanned in order by a <span class="quote">“<span class="quote">distance</span>”</span>
+ operator, for example <code class="literal">ORDER BY col &lt;-&gt; constant</code> ?
+ </td></tr><tr><td><code class="literal">returnable</code></td><td>Can the column value be returned by an index-only scan?
+ </td></tr><tr><td><code class="literal">search_array</code></td><td>Does the column natively support <code class="literal">col = ANY(array)</code>
+ searches?
+ </td></tr><tr><td><code class="literal">search_nulls</code></td><td>Does the column support <code class="literal">IS NULL</code> and
+ <code class="literal">IS NOT NULL</code> searches?
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-INFO-INDEX-PROPS"><p class="title"><strong>Table 9.73. Index Properties</strong></p><div class="table-contents"><table class="table" summary="Index Properties" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">clusterable</code></td><td>Can the index be used in a <code class="literal">CLUSTER</code> command?
+ </td></tr><tr><td><code class="literal">index_scan</code></td><td>Does the index support plain (non-bitmap) scans?
+ </td></tr><tr><td><code class="literal">bitmap_scan</code></td><td>Does the index support bitmap scans?
+ </td></tr><tr><td><code class="literal">backward_scan</code></td><td>Can the scan direction be changed in mid-scan (to
+ support <code class="literal">FETCH BACKWARD</code> on a cursor without
+ needing materialization)?
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-INFO-INDEXAM-PROPS"><p class="title"><strong>Table 9.74. Index Access Method Properties</strong></p><div class="table-contents"><table class="table" summary="Index Access Method Properties" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">can_order</code></td><td>Does the access method support <code class="literal">ASC</code>,
+ <code class="literal">DESC</code> and related keywords in
+ <code class="literal">CREATE INDEX</code>?
+ </td></tr><tr><td><code class="literal">can_unique</code></td><td>Does the access method support unique indexes?
+ </td></tr><tr><td><code class="literal">can_multi_col</code></td><td>Does the access method support indexes with multiple columns?
+ </td></tr><tr><td><code class="literal">can_exclude</code></td><td>Does the access method support exclusion constraints?
+ </td></tr><tr><td><code class="literal">can_include</code></td><td>Does the access method support the <code class="literal">INCLUDE</code>
+ clause of <code class="literal">CREATE INDEX</code>?
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-PG-SETTINGS-FLAGS"><p class="title"><strong>Table 9.75. GUC Flags</strong></p><div class="table-contents"><table class="table" summary="GUC Flags" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Flag</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">EXPLAIN</code></td><td>Parameters with this flag are included in
+ <code class="command">EXPLAIN (SETTINGS)</code> commands.
+ </td></tr><tr><td><code class="literal">NO_SHOW_ALL</code></td><td>Parameters with this flag are excluded from
+ <code class="command">SHOW ALL</code> commands.
+ </td></tr><tr><td><code class="literal">NO_RESET_ALL</code></td><td>Parameters with this flag are excluded from
+ <code class="command">RESET ALL</code> commands.
+ </td></tr><tr><td><code class="literal">NOT_IN_SAMPLE</code></td><td>Parameters with this flag are not included in
+ <code class="filename">postgresql.conf</code> by default.
+ </td></tr><tr><td><code class="literal">RUNTIME_COMPUTED</code></td><td>Parameters with this flag are runtime-computed ones.
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-info.html#FUNCTIONS-INFO-OBJECT-TABLE" title="Table 9.76. Object Information and Addressing Functions">Table 9.76</a> lists functions related to
+ database object identification and addressing.
+ </p><div class="table" id="FUNCTIONS-INFO-OBJECT-TABLE"><p class="title"><strong>Table 9.76. Object Information and Addressing Functions</strong></p><div class="table-contents"><table class="table" summary="Object Information and Addressing Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.26.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_describe_object</code> ( <em class="parameter"><code>classid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objsubid</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns a textual description of a database object identified by
+ catalog OID, object OID, and sub-object ID (such as a column number
+ within a table; the sub-object ID is zero when referring to a whole
+ object). This description is intended to be human-readable, and might
+ be translated, depending on server configuration. This is especially
+ useful to determine the identity of an object referenced in the
+ <code class="structname">pg_depend</code> catalog. This function returns
+ <code class="literal">NULL</code> values for undefined objects.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.26.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_identify_object</code> ( <em class="parameter"><code>classid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objsubid</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>type</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>schema</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>identity</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by catalog OID, object OID and sub-object
+ ID.
+ This information is intended to be machine-readable, and is never
+ translated.
+ <em class="parameter"><code>type</code></em> identifies the type of database object;
+ <em class="parameter"><code>schema</code></em> is the schema name that the object
+ belongs in, or <code class="literal">NULL</code> for object types that do not
+ belong to schemas;
+ <em class="parameter"><code>name</code></em> is the name of the object, quoted if
+ necessary, if the name (along with schema name, if pertinent) is
+ sufficient to uniquely identify the object,
+ otherwise <code class="literal">NULL</code>;
+ <em class="parameter"><code>identity</code></em> is the complete object identity, with
+ the precise format depending on object type, and each name within the
+ format being schema-qualified and quoted as necessary. Undefined
+ objects are identified with <code class="literal">NULL</code> values.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.26.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_identify_object_as_address</code> ( <em class="parameter"><code>classid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objid</code></em> <code class="type">oid</code>, <em class="parameter"><code>objsubid</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>type</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>object_names</code></em> <code class="type">text[]</code>,
+ <em class="parameter"><code>object_args</code></em> <code class="type">text[]</code> )
+ </p>
+ <p>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by catalog OID, object OID and sub-object
+ ID.
+ The returned information is independent of the current server, that
+ is, it could be used to identify an identically named object in
+ another server.
+ <em class="parameter"><code>type</code></em> identifies the type of database object;
+ <em class="parameter"><code>object_names</code></em> and
+ <em class="parameter"><code>object_args</code></em>
+ are text arrays that together form a reference to the object.
+ These three values can be passed
+ to <code class="function">pg_get_object_address</code> to obtain the internal
+ address of the object.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.26.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_get_object_address</code> ( <em class="parameter"><code>type</code></em> <code class="type">text</code>, <em class="parameter"><code>object_names</code></em> <code class="type">text[]</code>, <em class="parameter"><code>object_args</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>classid</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>objid</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>objsubid</code></em> <code class="type">integer</code> )
+ </p>
+ <p>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by a type code and object name and argument
+ arrays.
+ The returned values are the ones that would be used in system catalogs
+ such as <code class="structname">pg_depend</code>; they can be passed to
+ other system functions such as <code class="function">pg_describe_object</code>
+ or <code class="function">pg_identify_object</code>.
+ <em class="parameter"><code>classid</code></em> is the OID of the system catalog
+ containing the object;
+ <em class="parameter"><code>objid</code></em> is the OID of the object itself, and
+ <em class="parameter"><code>objsubid</code></em> is the sub-object ID, or zero if none.
+ This function is the inverse
+ of <code class="function">pg_identify_object_as_address</code>.
+ Undefined objects are identified with <code class="literal">NULL</code> values.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><a id="id-1.5.8.32.27" class="indexterm"></a><p>
+ The functions shown in <a class="xref" href="functions-info.html#FUNCTIONS-INFO-COMMENT-TABLE" title="Table 9.77. Comment Information Functions">Table 9.77</a>
+ extract comments previously stored with the <a class="xref" href="sql-comment.html" title="COMMENT"><span class="refentrytitle">COMMENT</span></a>
+ command. A null value is returned if no
+ comment could be found for the specified parameters.
+ </p><div class="table" id="FUNCTIONS-INFO-COMMENT-TABLE"><p class="title"><strong>Table 9.77. Comment Information Functions</strong></p><div class="table-contents"><table class="table" summary="Comment Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.29.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">col_description</code> ( <em class="parameter"><code>table</code></em> <code class="type">oid</code>, <em class="parameter"><code>column</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the comment for a table column, which is specified by the OID
+ of its table and its column number.
+ (<code class="function">obj_description</code> cannot be used for table
+ columns, since columns do not have OIDs of their own.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.29.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">obj_description</code> ( <em class="parameter"><code>object</code></em> <code class="type">oid</code>, <em class="parameter"><code>catalog</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the comment for a database object specified by its OID and the
+ name of the containing system catalog. For
+ example, <code class="literal">obj_description(123456, 'pg_class')</code> would
+ retrieve the comment for the table with OID 123456.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">obj_description</code> ( <em class="parameter"><code>object</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the comment for a database object specified by its OID alone.
+ This is <span class="emphasis"><em>deprecated</em></span> since there is no guarantee
+ that OIDs are unique across different system catalogs; therefore, the
+ wrong comment might be returned.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.29.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">shobj_description</code> ( <em class="parameter"><code>object</code></em> <code class="type">oid</code>, <em class="parameter"><code>catalog</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the comment for a shared database object specified by its OID
+ and the name of the containing system catalog. This is just
+ like <code class="function">obj_description</code> except that it is used for
+ retrieving comments on shared objects (that is, databases, roles, and
+ tablespaces). Some system catalogs are global to all databases within
+ each cluster, and the descriptions for objects in them are stored
+ globally as well.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The functions shown in <a class="xref" href="functions-info.html#FUNCTIONS-PG-SNAPSHOT" title="Table 9.78. Transaction ID and Snapshot Information Functions">Table 9.78</a>
+ provide server transaction information in an exportable form. The main
+ use of these functions is to determine which transactions were committed
+ between two snapshots.
+ </p><div class="table" id="FUNCTIONS-PG-SNAPSHOT"><p class="title"><strong>Table 9.78. Transaction ID and Snapshot Information Functions</strong></p><div class="table-contents"><table class="table" summary="Transaction ID and Snapshot Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_xact_id</code> ()
+ → <code class="returnvalue">xid8</code>
+ </p>
+ <p>
+ Returns the current transaction's ID. It will assign a new one if the
+ current transaction does not have one already (because it has not
+ performed any database updates).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_xact_id_if_assigned</code> ()
+ → <code class="returnvalue">xid8</code>
+ </p>
+ <p>
+ Returns the current transaction's ID, or <code class="literal">NULL</code> if no
+ ID is assigned yet. (It's best to use this variant if the transaction
+ might otherwise be read-only, to avoid unnecessary consumption of an
+ XID.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_xact_status</code> ( <code class="type">xid8</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reports the commit status of a recent transaction.
+ The result is one of <code class="literal">in progress</code>,
+ <code class="literal">committed</code>, or <code class="literal">aborted</code>,
+ provided that the transaction is recent enough that the system retains
+ the commit status of that transaction.
+ If it is old enough that no references to the transaction survive in
+ the system and the commit status information has been discarded, the
+ result is <code class="literal">NULL</code>.
+ Applications might use this function, for example, to determine
+ whether their transaction committed or aborted after the application
+ and database server become disconnected while
+ a <code class="literal">COMMIT</code> is in progress.
+ Note that prepared transactions are reported as <code class="literal">in
+ progress</code>; applications must check <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a>
+ if they need to determine whether a transaction ID belongs to a
+ prepared transaction.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_current_snapshot</code> ()
+ → <code class="returnvalue">pg_snapshot</code>
+ </p>
+ <p>
+ Returns a current <em class="firstterm">snapshot</em>, a data structure
+ showing which transaction IDs are now in-progress.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_snapshot_xip</code> ( <code class="type">pg_snapshot</code> )
+ → <code class="returnvalue">setof xid8</code>
+ </p>
+ <p>
+ Returns the set of in-progress transaction IDs contained in a snapshot.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_snapshot_xmax</code> ( <code class="type">pg_snapshot</code> )
+ → <code class="returnvalue">xid8</code>
+ </p>
+ <p>
+ Returns the <code class="structfield">xmax</code> of a snapshot.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_snapshot_xmin</code> ( <code class="type">pg_snapshot</code> )
+ → <code class="returnvalue">xid8</code>
+ </p>
+ <p>
+ Returns the <code class="structfield">xmin</code> of a snapshot.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.31.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_visible_in_snapshot</code> ( <code class="type">xid8</code>, <code class="type">pg_snapshot</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the given transaction ID <em class="firstterm">visible</em> according
+ to this snapshot (that is, was it completed before the snapshot was
+ taken)? Note that this function will not give the correct answer for
+ a subtransaction ID.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The internal transaction ID type <code class="type">xid</code> is 32 bits wide and
+ wraps around every 4 billion transactions. However,
+ the functions shown in <a class="xref" href="functions-info.html#FUNCTIONS-PG-SNAPSHOT" title="Table 9.78. Transaction ID and Snapshot Information Functions">Table 9.78</a> use a
+ 64-bit type <code class="type">xid8</code> that does not wrap around during the life
+ of an installation, and can be converted to <code class="type">xid</code> by casting if
+ required. The data type <code class="type">pg_snapshot</code> stores information about
+ transaction ID visibility at a particular moment in time. Its components
+ are described in <a class="xref" href="functions-info.html#FUNCTIONS-PG-SNAPSHOT-PARTS" title="Table 9.79. Snapshot Components">Table 9.79</a>.
+ <code class="type">pg_snapshot</code>'s textual representation is
+ <code class="literal"><em class="replaceable"><code>xmin</code></em>:<em class="replaceable"><code>xmax</code></em>:<em class="replaceable"><code>xip_list</code></em></code>.
+ For example <code class="literal">10:20:10,14,15</code> means
+ <code class="literal">xmin=10, xmax=20, xip_list=10, 14, 15</code>.
+ </p><div class="table" id="FUNCTIONS-PG-SNAPSHOT-PARTS"><p class="title"><strong>Table 9.79. Snapshot Components</strong></p><div class="table-contents"><table class="table" summary="Snapshot Components" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">xmin</code></td><td>
+ Lowest transaction ID that was still active. All transaction IDs
+ less than <code class="structfield">xmin</code> are either committed and visible,
+ or rolled back and dead.
+ </td></tr><tr><td><code class="structfield">xmax</code></td><td>
+ One past the highest completed transaction ID. All transaction IDs
+ greater than or equal to <code class="structfield">xmax</code> had not yet
+ completed as of the time of the snapshot, and thus are invisible.
+ </td></tr><tr><td><code class="structfield">xip_list</code></td><td>
+ Transactions in progress at the time of the snapshot. A transaction
+ ID that is <code class="literal">xmin &lt;= <em class="replaceable"><code>X</code></em> &lt;
+ xmax</code> and not in this list was already completed at the time
+ of the snapshot, and thus is either visible or dead according to its
+ commit status. This list does not include the transaction IDs of
+ subtransactions.
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In releases of <span class="productname">PostgreSQL</span> before 13 there was
+ no <code class="type">xid8</code> type, so variants of these functions were provided
+ that used <code class="type">bigint</code> to represent a 64-bit XID, with a
+ correspondingly distinct snapshot data type <code class="type">txid_snapshot</code>.
+ These older functions have <code class="literal">txid</code> in their names. They
+ are still supported for backward compatibility, but may be removed from a
+ future release. See <a class="xref" href="functions-info.html#FUNCTIONS-TXID-SNAPSHOT" title="Table 9.80. Deprecated Transaction ID and Snapshot Information Functions">Table 9.80</a>.
+ </p><div class="table" id="FUNCTIONS-TXID-SNAPSHOT"><p class="title"><strong>Table 9.80. Deprecated Transaction ID and Snapshot Information Functions</strong></p><div class="table-contents"><table class="table" summary="Deprecated Transaction ID and Snapshot Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">txid_current</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ See <code class="function">pg_current_xact_id()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">txid_current_if_assigned</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ See <code class="function">pg_current_xact_id_if_assigned()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">txid_current_snapshot</code> ()
+ → <code class="returnvalue">txid_snapshot</code>
+ </p>
+ <p>
+ See <code class="function">pg_current_snapshot()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">txid_snapshot_xip</code> ( <code class="type">txid_snapshot</code> )
+ → <code class="returnvalue">setof bigint</code>
+ </p>
+ <p>
+ See <code class="function">pg_snapshot_xip()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">txid_snapshot_xmax</code> ( <code class="type">txid_snapshot</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ See <code class="function">pg_snapshot_xmax()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">txid_snapshot_xmin</code> ( <code class="type">txid_snapshot</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ See <code class="function">pg_snapshot_xmin()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">txid_visible_in_snapshot</code> ( <code class="type">bigint</code>, <code class="type">txid_snapshot</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ See <code class="function">pg_visible_in_snapshot()</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.35.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">txid_status</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ See <code class="function">pg_xact_status()</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The functions shown in <a class="xref" href="functions-info.html#FUNCTIONS-COMMIT-TIMESTAMP" title="Table 9.81. Committed Transaction Information Functions">Table 9.81</a>
+ provide information about when past transactions were committed.
+ They only provide useful data when the
+ <a class="xref" href="runtime-config-replication.html#GUC-TRACK-COMMIT-TIMESTAMP">track_commit_timestamp</a> configuration option is
+ enabled, and only for transactions that were committed after it was
+ enabled.
+ </p><div class="table" id="FUNCTIONS-COMMIT-TIMESTAMP"><p class="title"><strong>Table 9.81. Committed Transaction Information Functions</strong></p><div class="table-contents"><table class="table" summary="Committed Transaction Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.37.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_xact_commit_timestamp</code> ( <code class="type">xid</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the commit timestamp of a transaction.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.37.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_xact_commit_timestamp_origin</code> ( <code class="type">xid</code> )
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>timestamp</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>roident</code></em> <code class="type">oid</code>)
+ </p>
+ <p>
+ Returns the commit timestamp and replication origin of a transaction.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.37.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_last_committed_xact</code> ()
+ → <code class="returnvalue">record</code>
+ ( <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
+ <em class="parameter"><code>timestamp</code></em> <code class="type">timestamp with time zone</code>,
+ <em class="parameter"><code>roident</code></em> <code class="type">oid</code> )
+ </p>
+ <p>
+ Returns the transaction ID, commit timestamp and replication origin
+ of the latest committed transaction.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The functions shown in <a class="xref" href="functions-info.html#FUNCTIONS-CONTROLDATA" title="Table 9.82. Control Data Functions">Table 9.82</a>
+ print information initialized during <code class="command">initdb</code>, such
+ as the catalog version. They also show information about write-ahead
+ logging and checkpoint processing. This information is cluster-wide,
+ not specific to any one database. These functions provide most of the same
+ information, from the same source, as the
+ <a class="xref" href="app-pgcontroldata.html" title="pg_controldata"><span class="refentrytitle"><span class="application">pg_controldata</span></span></a> application.
+ </p><div class="table" id="FUNCTIONS-CONTROLDATA"><p class="title"><strong>Table 9.82. Control Data Functions</strong></p><div class="table-contents"><table class="table" summary="Control Data Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.39.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_control_checkpoint</code> ()
+ → <code class="returnvalue">record</code>
+ </p>
+ <p>
+ Returns information about current checkpoint state, as shown in
+ <a class="xref" href="functions-info.html#FUNCTIONS-PG-CONTROL-CHECKPOINT" title="Table 9.83. pg_control_checkpoint Output Columns">Table 9.83</a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.39.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_control_system</code> ()
+ → <code class="returnvalue">record</code>
+ </p>
+ <p>
+ Returns information about current control file state, as shown in
+ <a class="xref" href="functions-info.html#FUNCTIONS-PG-CONTROL-SYSTEM" title="Table 9.84. pg_control_system Output Columns">Table 9.84</a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.39.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_control_init</code> ()
+ → <code class="returnvalue">record</code>
+ </p>
+ <p>
+ Returns information about cluster initialization state, as shown in
+ <a class="xref" href="functions-info.html#FUNCTIONS-PG-CONTROL-INIT" title="Table 9.85. pg_control_init Output Columns">Table 9.85</a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.32.39.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_control_recovery</code> ()
+ → <code class="returnvalue">record</code>
+ </p>
+ <p>
+ Returns information about recovery state, as shown in
+ <a class="xref" href="functions-info.html#FUNCTIONS-PG-CONTROL-RECOVERY" title="Table 9.86. pg_control_recovery Output Columns">Table 9.86</a>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-PG-CONTROL-CHECKPOINT"><p class="title"><strong>Table 9.83. <code class="function">pg_control_checkpoint</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_control_checkpoint Output Columns" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Column Name</th><th>Data Type</th></tr></thead><tbody><tr><td><code class="structfield">checkpoint_lsn</code></td><td><code class="type">pg_lsn</code></td></tr><tr><td><code class="structfield">redo_lsn</code></td><td><code class="type">pg_lsn</code></td></tr><tr><td><code class="structfield">redo_wal_file</code></td><td><code class="type">text</code></td></tr><tr><td><code class="structfield">timeline_id</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">prev_timeline_id</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">full_page_writes</code></td><td><code class="type">boolean</code></td></tr><tr><td><code class="structfield">next_xid</code></td><td><code class="type">text</code></td></tr><tr><td><code class="structfield">next_oid</code></td><td><code class="type">oid</code></td></tr><tr><td><code class="structfield">next_multixact_id</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">next_multi_offset</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">oldest_xid</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">oldest_xid_dbid</code></td><td><code class="type">oid</code></td></tr><tr><td><code class="structfield">oldest_active_xid</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">oldest_multi_xid</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">oldest_multi_dbid</code></td><td><code class="type">oid</code></td></tr><tr><td><code class="structfield">oldest_commit_ts_xid</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">newest_commit_ts_xid</code></td><td><code class="type">xid</code></td></tr><tr><td><code class="structfield">checkpoint_time</code></td><td><code class="type">timestamp with time zone</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-PG-CONTROL-SYSTEM"><p class="title"><strong>Table 9.84. <code class="function">pg_control_system</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_control_system Output Columns" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Column Name</th><th>Data Type</th></tr></thead><tbody><tr><td><code class="structfield">pg_control_version</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">catalog_version_no</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">system_identifier</code></td><td><code class="type">bigint</code></td></tr><tr><td><code class="structfield">pg_control_last_modified</code></td><td><code class="type">timestamp with time zone</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-PG-CONTROL-INIT"><p class="title"><strong>Table 9.85. <code class="function">pg_control_init</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_control_init Output Columns" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Column Name</th><th>Data Type</th></tr></thead><tbody><tr><td><code class="structfield">max_data_alignment</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">database_block_size</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">blocks_per_segment</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">wal_block_size</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">bytes_per_wal_segment</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">max_identifier_length</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">max_index_columns</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">max_toast_chunk_size</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">large_object_chunk_size</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">float8_pass_by_value</code></td><td><code class="type">boolean</code></td></tr><tr><td><code class="structfield">data_page_checksum_version</code></td><td><code class="type">integer</code></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-PG-CONTROL-RECOVERY"><p class="title"><strong>Table 9.86. <code class="function">pg_control_recovery</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_control_recovery Output Columns" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Column Name</th><th>Data Type</th></tr></thead><tbody><tr><td><code class="structfield">min_recovery_end_lsn</code></td><td><code class="type">pg_lsn</code></td></tr><tr><td><code class="structfield">min_recovery_end_timeline</code></td><td><code class="type">integer</code></td></tr><tr><td><code class="structfield">backup_start_lsn</code></td><td><code class="type">pg_lsn</code></td></tr><tr><td><code class="structfield">backup_end_lsn</code></td><td><code class="type">pg_lsn</code></td></tr><tr><td><code class="structfield">end_of_backup_record_required</code></td><td><code class="type">boolean</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-srf.html" title="9.25. Set Returning Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-admin.html" title="9.27. System Administration Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.25. Set Returning Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.27. System Administration Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-json.html b/doc/src/sgml/html/functions-json.html
new file mode 100644
index 0000000..5f454a1
--- /dev/null
+++ b/doc/src/sgml/html/functions-json.html
@@ -0,0 +1,1781 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.16. JSON Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-xml.html" title="9.15. XML Functions" /><link rel="next" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.16. JSON Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-xml.html" title="9.15. XML Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-JSON"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.16. JSON Functions and Operators</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-JSON-PROCESSING">9.16.1. Processing and Creating JSON Data</a></span></dt><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-SQLJSON-PATH">9.16.2. The SQL/JSON Path Language</a></span></dt></dl></div><a id="id-1.5.8.22.2" class="indexterm"></a><p>
+ This section describes:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ functions and operators for processing and creating JSON data
+ </p></li><li class="listitem"><p>
+ the SQL/JSON path language
+ </p></li></ul></div><p>
+ </p><p>
+ To learn more about the SQL/JSON standard, see
+ <a class="xref" href="biblio.html#SQLTR-19075-6" title="SQL Technical Report">[sqltr-19075-6]</a>. For details on JSON types
+ supported in <span class="productname">PostgreSQL</span>,
+ see <a class="xref" href="datatype-json.html" title="8.14. JSON Types">Section 8.14</a>.
+ </p><div class="sect2" id="FUNCTIONS-JSON-PROCESSING"><div class="titlepage"><div><div><h3 class="title">9.16.1. Processing and Creating JSON Data</h3></div></div></div><p>
+ <a class="xref" href="functions-json.html#FUNCTIONS-JSON-OP-TABLE" title="Table 9.45. json and jsonb Operators">Table 9.45</a> shows the operators that
+ are available for use with JSON data types (see <a class="xref" href="datatype-json.html" title="8.14. JSON Types">Section 8.14</a>).
+ In addition, the usual comparison operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for
+ <code class="type">jsonb</code>, though not for <code class="type">json</code>. The comparison
+ operators follow the ordering rules for B-tree operations outlined in
+ <a class="xref" href="datatype-json.html#JSON-INDEXING" title="8.14.4. jsonb Indexing">Section 8.14.4</a>.
+ See also <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> for the aggregate
+ function <code class="function">json_agg</code> which aggregates record
+ values as JSON, the aggregate function
+ <code class="function">json_object_agg</code> which aggregates pairs of values
+ into a JSON object, and their <code class="type">jsonb</code> equivalents,
+ <code class="function">jsonb_agg</code> and <code class="function">jsonb_object_agg</code>.
+ </p><div class="table" id="FUNCTIONS-JSON-OP-TABLE"><p class="title"><strong>Table 9.45. <code class="type">json</code> and <code class="type">jsonb</code> Operators</strong></p><div class="table-contents"><table class="table" summary="json and jsonb Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">-&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Extracts <em class="parameter"><code>n</code></em>'th element of JSON array
+ (array elements are indexed from zero, but negative integers count
+ from the end).
+ </p>
+ <p>
+ <code class="literal">'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -&gt; 2</code>
+ → <code class="returnvalue">{"c":"baz"}</code>
+ </p>
+ <p>
+ <code class="literal">'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -&gt; -3</code>
+ → <code class="returnvalue">{"a":"foo"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Extracts JSON object field with the given key.
+ </p>
+ <p>
+ <code class="literal">'{"a": {"b":"foo"}}'::json -&gt; 'a'</code>
+ → <code class="returnvalue">{"b":"foo"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">-&gt;&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-&gt;&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts <em class="parameter"><code>n</code></em>'th element of JSON array,
+ as <code class="type">text</code>.
+ </p>
+ <p>
+ <code class="literal">'[1,2,3]'::json -&gt;&gt; 2</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">-&gt;&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-&gt;&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts JSON object field with the given key, as <code class="type">text</code>.
+ </p>
+ <p>
+ <code class="literal">'{"a":1,"b":2}'::json -&gt;&gt; 'b'</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">#&gt;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">#&gt;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Extracts JSON sub-object at the specified path, where path elements
+ can be either field keys or array indexes.
+ </p>
+ <p>
+ <code class="literal">'{"a": {"b": ["foo","bar"]}}'::json #&gt; '{a,b,1}'</code>
+ → <code class="returnvalue">"bar"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">json</code> <code class="literal">#&gt;&gt;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">#&gt;&gt;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts JSON sub-object at the specified path as <code class="type">text</code>.
+ </p>
+ <p>
+ <code class="literal">'{"a": {"b": ["foo","bar"]}}'::json #&gt;&gt; '{a,b,1}'</code>
+ → <code class="returnvalue">bar</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The field/element/path extraction operators return NULL, rather than
+ failing, if the JSON input does not have the right structure to match
+ the request; for example if no such key or array element exists.
+ </p></div><p>
+ Some further operators exist only for <code class="type">jsonb</code>, as shown
+ in <a class="xref" href="functions-json.html#FUNCTIONS-JSONB-OP-TABLE" title="Table 9.46. Additional jsonb Operators">Table 9.46</a>.
+ <a class="xref" href="datatype-json.html#JSON-INDEXING" title="8.14.4. jsonb Indexing">Section 8.14.4</a>
+ describes how these operators can be used to effectively search indexed
+ <code class="type">jsonb</code> data.
+ </p><div class="table" id="FUNCTIONS-JSONB-OP-TABLE"><p class="title"><strong>Table 9.46. Additional <code class="type">jsonb</code> Operators</strong></p><div class="table-contents"><table class="table" summary="Additional jsonb Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">@&gt;</code> <code class="type">jsonb</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first JSON value contain the second?
+ (See <a class="xref" href="datatype-json.html#JSON-CONTAINMENT" title="8.14.3. jsonb Containment and Existence">Section 8.14.3</a> for details about containment.)
+ </p>
+ <p>
+ <code class="literal">'{"a":1, "b":2}'::jsonb @&gt; '{"b":2}'::jsonb</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">&lt;@</code> <code class="type">jsonb</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first JSON value contained in the second?
+ </p>
+ <p>
+ <code class="literal">'{"b":2}'::jsonb &lt;@ '{"a":1, "b":2}'::jsonb</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">?</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the text string exist as a top-level key or array element within
+ the JSON value?
+ </p>
+ <p>
+ <code class="literal">'{"a":1, "b":2}'::jsonb ? 'b'</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">'["a", "b", "c"]'::jsonb ? 'b'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">?|</code> <code class="type">text[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do any of the strings in the text array exist as top-level keys or
+ array elements?
+ </p>
+ <p>
+ <code class="literal">'{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'd']</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">?&amp;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do all of the strings in the text array exist as top-level keys or
+ array elements?
+ </p>
+ <p>
+ <code class="literal">'["a", "b", "c"]'::jsonb ?&amp; array['a', 'b']</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">||</code> <code class="type">jsonb</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Concatenates two <code class="type">jsonb</code> values.
+ Concatenating two arrays generates an array containing all the
+ elements of each input. Concatenating two objects generates an
+ object containing the union of their
+ keys, taking the second object's value when there are duplicate keys.
+ All other cases are treated by converting a non-array input into a
+ single-element array, and then proceeding as for two arrays.
+ Does not operate recursively: only the top-level array or object
+ structure is merged.
+ </p>
+ <p>
+ <code class="literal">'["a", "b"]'::jsonb || '["a", "d"]'::jsonb</code>
+ → <code class="returnvalue">["a", "b", "a", "d"]</code>
+ </p>
+ <p>
+ <code class="literal">'{"a": "b"}'::jsonb || '{"c": "d"}'::jsonb</code>
+ → <code class="returnvalue">{"a": "b", "c": "d"}</code>
+ </p>
+ <p>
+ <code class="literal">'[1, 2]'::jsonb || '3'::jsonb</code>
+ → <code class="returnvalue">[1, 2, 3]</code>
+ </p>
+ <p>
+ <code class="literal">'{"a": "b"}'::jsonb || '42'::jsonb</code>
+ → <code class="returnvalue">[{"a": "b"}, 42]</code>
+ </p>
+ <p>
+ To append an array to another array as a single entry, wrap it
+ in an additional layer of array, for example:
+ </p>
+ <p>
+ <code class="literal">'[1, 2]'::jsonb || jsonb_build_array('[3, 4]'::jsonb)</code>
+ → <code class="returnvalue">[1, 2, [3, 4]]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-</code> <code class="type">text</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Deletes a key (and its value) from a JSON object, or matching string
+ value(s) from a JSON array.
+ </p>
+ <p>
+ <code class="literal">'{"a": "b", "c": "d"}'::jsonb - 'a'</code>
+ → <code class="returnvalue">{"c": "d"}</code>
+ </p>
+ <p>
+ <code class="literal">'["a", "b", "c", "b"]'::jsonb - 'b'</code>
+ → <code class="returnvalue">["a", "c"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-</code> <code class="type">text[]</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Deletes all matching keys or array elements from the left operand.
+ </p>
+ <p>
+ <code class="literal">'{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[]</code>
+ → <code class="returnvalue">{}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">-</code> <code class="type">integer</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Deletes the array element with specified index (negative
+ integers count from the end). Throws an error if JSON value
+ is not an array.
+ </p>
+ <p>
+ <code class="literal">'["a", "b"]'::jsonb - 1 </code>
+ → <code class="returnvalue">["a"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">#-</code> <code class="type">text[]</code>
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Deletes the field or array element at the specified path, where path
+ elements can be either field keys or array indexes.
+ </p>
+ <p>
+ <code class="literal">'["a", {"b":1}]'::jsonb #- '{1,b}'</code>
+ → <code class="returnvalue">["a", {}]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">@?</code> <code class="type">jsonpath</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does JSON path return any item for the specified JSON value?
+ </p>
+ <p>
+ <code class="literal">'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ &gt; 2)'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">jsonb</code> <code class="literal">@@</code> <code class="type">jsonpath</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns the result of a JSON path predicate check for the
+ specified JSON value. Only the first item of the result is taken into
+ account. If the result is not Boolean, then <code class="literal">NULL</code>
+ is returned.
+ </p>
+ <p>
+ <code class="literal">'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] &gt; 2'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="type">jsonpath</code> operators <code class="literal">@?</code>
+ and <code class="literal">@@</code> suppress the following errors: missing object
+ field or array element, unexpected JSON item type, datetime and numeric
+ errors. The <code class="type">jsonpath</code>-related functions described below can
+ also be told to suppress these types of errors. This behavior might be
+ helpful when searching JSON document collections of varying structure.
+ </p></div><p>
+ <a class="xref" href="functions-json.html#FUNCTIONS-JSON-CREATION-TABLE" title="Table 9.47. JSON Creation Functions">Table 9.47</a> shows the functions that are
+ available for constructing <code class="type">json</code> and <code class="type">jsonb</code> values.
+ </p><div class="table" id="FUNCTIONS-JSON-CREATION-TABLE"><p class="title"><strong>Table 9.47. JSON Creation Functions</strong></p><div class="table-contents"><table class="table" summary="JSON Creation Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">to_json</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.1.1.2.1" class="indexterm"></a>
+ <code class="function">to_jsonb</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Converts any SQL value to <code class="type">json</code> or <code class="type">jsonb</code>.
+ Arrays and composites are converted recursively to arrays and
+ objects (multidimensional arrays become arrays of arrays in JSON).
+ Otherwise, if there is a cast from the SQL data type
+ to <code class="type">json</code>, the cast function will be used to perform the
+ conversion;<a href="#ftn.id-1.5.8.22.5.9.2.2.1.1.3.4" class="footnote"><sup class="footnote" id="id-1.5.8.22.5.9.2.2.1.1.3.4">[a]</sup></a>
+ otherwise, a scalar JSON value is produced. For any scalar other than
+ a number, a Boolean, or a null value, the text representation will be
+ used, with escaping as necessary to make it a valid JSON string value.
+ </p>
+ <p>
+ <code class="literal">to_json('Fred said "Hi."'::text)</code>
+ → <code class="returnvalue">"Fred said \"Hi.\""</code>
+ </p>
+ <p>
+ <code class="literal">to_jsonb(row(42, 'Fred said "Hi."'::text))</code>
+ → <code class="returnvalue">{"f1": 42, "f2": "Fred said \"Hi.\""}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">array_to_json</code> ( <code class="type">anyarray</code> [<span class="optional">, <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p>
+ Converts an SQL array to a JSON array. The behavior is the same
+ as <code class="function">to_json</code> except that line feeds will be added
+ between top-level array elements if the optional boolean parameter is
+ true.
+ </p>
+ <p>
+ <code class="literal">array_to_json('{{1,5},{99,100}}'::int[])</code>
+ → <code class="returnvalue">[[1,5],[99,100]]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">row_to_json</code> ( <code class="type">record</code> [<span class="optional">, <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p>
+ Converts an SQL composite value to a JSON object. The behavior is the
+ same as <code class="function">to_json</code> except that line feeds will be
+ added between top-level elements if the optional boolean parameter is
+ true.
+ </p>
+ <p>
+ <code class="literal">row_to_json(row(1,'foo'))</code>
+ → <code class="returnvalue">{"f1":1,"f2":"foo"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">json_build_array</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.4.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_build_array</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Builds a possibly-heterogeneously-typed JSON array out of a variadic
+ argument list. Each argument is converted as
+ per <code class="function">to_json</code> or <code class="function">to_jsonb</code>.
+ </p>
+ <p>
+ <code class="literal">json_build_array(1, 2, 'foo', 4, 5)</code>
+ → <code class="returnvalue">[1, 2, "foo", 4, 5]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">json_build_object</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.5.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_build_object</code> ( <code class="literal">VARIADIC</code> <code class="type">"any"</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Builds a JSON object out of a variadic argument list. By convention,
+ the argument list consists of alternating keys and values. Key
+ arguments are coerced to text; value arguments are converted as
+ per <code class="function">to_json</code> or <code class="function">to_jsonb</code>.
+ </p>
+ <p>
+ <code class="literal">json_build_object('foo', 1, 2, row(3,'bar'))</code>
+ → <code class="returnvalue">{"foo" : 1, "2" : {"f1":3,"f2":"bar"}}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">json_object</code> ( <code class="type">text[]</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.9.2.2.6.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_object</code> ( <code class="type">text[]</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Builds a JSON object out of a text array. The array must have either
+ exactly one dimension with an even number of members, in which case
+ they are taken as alternating key/value pairs, or two dimensions
+ such that each inner array has exactly two elements, which
+ are taken as a key/value pair. All values are converted to JSON
+ strings.
+ </p>
+ <p>
+ <code class="literal">json_object('{a, 1, b, "def", c, 3.5}')</code>
+ → <code class="returnvalue">{"a" : "1", "b" : "def", "c" : "3.5"}</code>
+ </p>
+ <p><code class="literal">json_object('{{a, 1}, {b, "def"}, {c, 3.5}}')</code>
+ → <code class="returnvalue">{"a" : "1", "b" : "def", "c" : "3.5"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">json_object</code> ( <em class="parameter"><code>keys</code></em> <code class="type">text[]</code>, <em class="parameter"><code>values</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">jsonb_object</code> ( <em class="parameter"><code>keys</code></em> <code class="type">text[]</code>, <em class="parameter"><code>values</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ This form of <code class="function">json_object</code> takes keys and values
+ pairwise from separate text arrays. Otherwise it is identical to
+ the one-argument form.
+ </p>
+ <p>
+ <code class="literal">json_object('{a,b}', '{1,2}')</code>
+ → <code class="returnvalue">{"a": "1", "b": "2"}</code>
+ </p></td></tr></tbody><tbody class="footnotes"><tr><td colspan="1"><div id="ftn.id-1.5.8.22.5.9.2.2.1.1.3.4" class="footnote"><p><a href="#id-1.5.8.22.5.9.2.2.1.1.3.4" class="para"><sup class="para">[a] </sup></a>
+ For example, the <a class="xref" href="hstore.html" title="F.18. hstore">hstore</a> extension has a cast
+ from <code class="type">hstore</code> to <code class="type">json</code>, so that
+ <code class="type">hstore</code> values converted via the JSON creation functions
+ will be represented as JSON objects, not as primitive string values.
+ </p></div></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-json.html#FUNCTIONS-JSON-PROCESSING-TABLE" title="Table 9.48. JSON Processing Functions">Table 9.48</a> shows the functions that
+ are available for processing <code class="type">json</code> and <code class="type">jsonb</code> values.
+ </p><div class="table" id="FUNCTIONS-JSON-PROCESSING-TABLE"><p class="title"><strong>Table 9.48. JSON Processing Functions</strong></p><div class="table-contents"><table class="table" summary="JSON Processing Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">json_array_elements</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.1.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_array_elements</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof jsonb</code>
+ </p>
+ <p>
+ Expands the top-level JSON array into a set of JSON values.
+ </p>
+ <p>
+ <code class="literal">select * from json_array_elements('[1,true, [2,false]]')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ value
+-----------
+ 1
+ true
+ [2,false]
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">json_array_elements_text</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.2.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_array_elements_text</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Expands the top-level JSON array into a set of <code class="type">text</code> values.
+ </p>
+ <p>
+ <code class="literal">select * from json_array_elements_text('["foo", "bar"]')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ value
+-----------
+ foo
+ bar
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">json_array_length</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.3.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_array_length</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of elements in the top-level JSON array.
+ </p>
+ <p>
+ <code class="literal">json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]')</code>
+ → <code class="returnvalue">5</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_array_length('[]')</code>
+ → <code class="returnvalue">0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">json_each</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>key</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>value</code></em> <code class="type">json</code> )
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.4.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_each</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>key</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>value</code></em> <code class="type">jsonb</code> )
+ </p>
+ <p>
+ Expands the top-level JSON object into a set of key/value pairs.
+ </p>
+ <p>
+ <code class="literal">select * from json_each('{"a":"foo", "b":"bar"}')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ key | value
+-----+-------
+ a | "foo"
+ b | "bar"
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">json_each_text</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>key</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>value</code></em> <code class="type">text</code> )
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.5.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_each_text</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>key</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>value</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Expands the top-level JSON object into a set of key/value pairs.
+ The returned <em class="parameter"><code>value</code></em>s will be of
+ type <code class="type">text</code>.
+ </p>
+ <p>
+ <code class="literal">select * from json_each_text('{"a":"foo", "b":"bar"}')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ key | value
+-----+-------
+ a | foo
+ b | bar
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">json_extract_path</code> ( <em class="parameter"><code>from_json</code></em> <code class="type">json</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>path_elems</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.6.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_extract_path</code> ( <em class="parameter"><code>from_json</code></em> <code class="type">jsonb</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>path_elems</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Extracts JSON sub-object at the specified path.
+ (This is functionally equivalent to the <code class="literal">#&gt;</code>
+ operator, but writing the path out as a variadic list can be more
+ convenient in some cases.)
+ </p>
+ <p>
+ <code class="literal">json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')</code>
+ → <code class="returnvalue">"foo"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">json_extract_path_text</code> ( <em class="parameter"><code>from_json</code></em> <code class="type">json</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>path_elems</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.7.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_extract_path_text</code> ( <em class="parameter"><code>from_json</code></em> <code class="type">jsonb</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>path_elems</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts JSON sub-object at the specified path as <code class="type">text</code>.
+ (This is functionally equivalent to the <code class="literal">#&gt;&gt;</code>
+ operator.)
+ </p>
+ <p>
+ <code class="literal">json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')</code>
+ → <code class="returnvalue">foo</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">json_object_keys</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.8.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_object_keys</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Returns the set of keys in the top-level JSON object.
+ </p>
+ <p>
+ <code class="literal">select * from json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ json_object_keys
+------------------
+ f1
+ f2
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">json_populate_record</code> ( <em class="parameter"><code>base</code></em> <code class="type">anyelement</code>, <em class="parameter"><code>from_json</code></em> <code class="type">json</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.9.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_populate_record</code> ( <em class="parameter"><code>base</code></em> <code class="type">anyelement</code>, <em class="parameter"><code>from_json</code></em> <code class="type">jsonb</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Expands the top-level JSON object to a row having the composite type
+ of the <em class="parameter"><code>base</code></em> argument. The JSON object
+ is scanned for fields whose names match column names of the output row
+ type, and their values are inserted into those columns of the output.
+ (Fields that do not correspond to any output column name are ignored.)
+ In typical use, the value of <em class="parameter"><code>base</code></em> is just
+ <code class="literal">NULL</code>, which means that any output columns that do
+ not match any object field will be filled with nulls. However,
+ if <em class="parameter"><code>base</code></em> isn't <code class="literal">NULL</code> then
+ the values it contains will be used for unmatched columns.
+ </p>
+ <p>
+ To convert a JSON value to the SQL type of an output column, the
+ following rules are applied in sequence:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ A JSON null value is converted to an SQL null in all cases.
+ </p></li><li class="listitem"><p>
+ If the output column is of type <code class="type">json</code>
+ or <code class="type">jsonb</code>, the JSON value is just reproduced exactly.
+ </p></li><li class="listitem"><p>
+ If the output column is a composite (row) type, and the JSON value
+ is a JSON object, the fields of the object are converted to columns
+ of the output row type by recursive application of these rules.
+ </p></li><li class="listitem"><p>
+ Likewise, if the output column is an array type and the JSON value
+ is a JSON array, the elements of the JSON array are converted to
+ elements of the output array by recursive application of these
+ rules.
+ </p></li><li class="listitem"><p>
+ Otherwise, if the JSON value is a string, the contents of the
+ string are fed to the input conversion function for the column's
+ data type.
+ </p></li><li class="listitem"><p>
+ Otherwise, the ordinary text representation of the JSON value is
+ fed to the input conversion function for the column's data type.
+ </p></li></ul></div><p>
+ </p>
+ <p>
+ While the example below uses a constant JSON value, typical use would
+ be to reference a <code class="type">json</code> or <code class="type">jsonb</code> column
+ laterally from another table in the query's <code class="literal">FROM</code>
+ clause. Writing <code class="function">json_populate_record</code> in
+ the <code class="literal">FROM</code> clause is good practice, since all of the
+ extracted columns are available for use without duplicate function
+ calls.
+ </p>
+ <p>
+ <code class="literal">create type subrowtype as (d int, e text);</code>
+ <code class="literal">create type myrowtype as (a int, b text[], c subrowtype);</code>
+ </p>
+ <p>
+ <code class="literal">select * from json_populate_record(null::myrowtype,
+ '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}, "x": "foo"}')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ a | b | c
+---+-----------+-------------
+ 1 | {2,"a b"} | (4,"a b c")
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">json_populate_recordset</code> ( <em class="parameter"><code>base</code></em> <code class="type">anyelement</code>, <em class="parameter"><code>from_json</code></em> <code class="type">json</code> )
+ → <code class="returnvalue">setof anyelement</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.10.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_populate_recordset</code> ( <em class="parameter"><code>base</code></em> <code class="type">anyelement</code>, <em class="parameter"><code>from_json</code></em> <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof anyelement</code>
+ </p>
+ <p>
+ Expands the top-level JSON array of objects to a set of rows having
+ the composite type of the <em class="parameter"><code>base</code></em> argument.
+ Each element of the JSON array is processed as described above
+ for <code class="function">json[b]_populate_record</code>.
+ </p>
+ <p>
+ <code class="literal">create type twoints as (a int, b int);</code>
+ </p>
+ <p>
+ <code class="literal">select * from json_populate_recordset(null::twoints, '[{"a":1,"b":2}, {"a":3,"b":4}]')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ a | b
+---+---
+ 1 | 2
+ 3 | 4
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">json_to_record</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">record</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.11.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_to_record</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">record</code>
+ </p>
+ <p>
+ Expands the top-level JSON object to a row having the composite type
+ defined by an <code class="literal">AS</code> clause. (As with all functions
+ returning <code class="type">record</code>, the calling query must explicitly
+ define the structure of the record with an <code class="literal">AS</code>
+ clause.) The output record is filled from fields of the JSON object,
+ in the same way as described above
+ for <code class="function">json[b]_populate_record</code>. Since there is no
+ input record value, unmatched columns are always filled with nulls.
+ </p>
+ <p>
+ <code class="literal">create type myrowtype as (a int, b text);</code>
+ </p>
+ <p>
+ <code class="literal">select * from json_to_record('{"a":1,"b":[1,2,3],"c":[1,2,3],"e":"bar","r": {"a": 123, "b": "a b c"}}') as x(a int, b text, c int[], d text, r myrowtype)</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ a | b | c | d | r
+---+---------+---------+---+---------------
+ 1 | [1,2,3] | {1,2,3} | | (123,"a b c")
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">json_to_recordset</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.12.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_to_recordset</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Expands the top-level JSON array of objects to a set of rows having
+ the composite type defined by an <code class="literal">AS</code> clause. (As
+ with all functions returning <code class="type">record</code>, the calling query
+ must explicitly define the structure of the record with
+ an <code class="literal">AS</code> clause.) Each element of the JSON array is
+ processed as described above
+ for <code class="function">json[b]_populate_record</code>.
+ </p>
+ <p>
+ <code class="literal">select * from json_to_recordset('[{"a":1,"b":"foo"}, {"a":"2","c":"bar"}]') as x(a int, b text)</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ a | b
+---+-----
+ 1 | foo
+ 2 |
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_set</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">text[]</code>, <em class="parameter"><code>new_value</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>create_if_missing</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>target</code></em>
+ with the item designated by <em class="parameter"><code>path</code></em>
+ replaced by <em class="parameter"><code>new_value</code></em>, or with
+ <em class="parameter"><code>new_value</code></em> added if
+ <em class="parameter"><code>create_if_missing</code></em> is true (which is the
+ default) and the item designated by <em class="parameter"><code>path</code></em>
+ does not exist.
+ All earlier steps in the path must exist, or
+ the <em class="parameter"><code>target</code></em> is returned unchanged.
+ As with the path oriented operators, negative integers that
+ appear in the <em class="parameter"><code>path</code></em> count from the end
+ of JSON arrays.
+ If the last path step is an array index that is out of range,
+ and <em class="parameter"><code>create_if_missing</code></em> is true, the new
+ value is added at the beginning of the array if the index is negative,
+ or at the end of the array if it is positive.
+ </p>
+ <p>
+ <code class="literal">jsonb_set('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', '[2,3,4]', false)</code>
+ → <code class="returnvalue">[{"f1": [2, 3, 4], "f2": null}, 2, null, 3]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_set('[{"f1":1,"f2":null},2]', '{0,f3}', '[2,3,4]')</code>
+ → <code class="returnvalue">[{"f1": 1, "f2": null, "f3": [2, 3, 4]}, 2]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_set_lax</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">text[]</code>, <em class="parameter"><code>new_value</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>create_if_missing</code></em> <code class="type">boolean</code> [<span class="optional">, <em class="parameter"><code>null_value_treatment</code></em> <code class="type">text</code> </span>]</span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ If <em class="parameter"><code>new_value</code></em> is not <code class="literal">NULL</code>,
+ behaves identically to <code class="literal">jsonb_set</code>. Otherwise behaves
+ according to the value
+ of <em class="parameter"><code>null_value_treatment</code></em> which must be one
+ of <code class="literal">'raise_exception'</code>,
+ <code class="literal">'use_json_null'</code>, <code class="literal">'delete_key'</code>, or
+ <code class="literal">'return_target'</code>. The default is
+ <code class="literal">'use_json_null'</code>.
+ </p>
+ <p>
+ <code class="literal">jsonb_set_lax('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', null)</code>
+ → <code class="returnvalue">[{"f1": null, "f2": null}, 2, null, 3]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_set_lax('[{"f1":99,"f2":null},2]', '{0,f3}', null, true, 'return_target')</code>
+ → <code class="returnvalue">[{"f1": 99, "f2": null}, 2]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_insert</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">text[]</code>, <em class="parameter"><code>new_value</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>insert_after</code></em> <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>target</code></em>
+ with <em class="parameter"><code>new_value</code></em> inserted. If the item
+ designated by the <em class="parameter"><code>path</code></em> is an array
+ element, <em class="parameter"><code>new_value</code></em> will be inserted before
+ that item if <em class="parameter"><code>insert_after</code></em> is false (which
+ is the default), or after it
+ if <em class="parameter"><code>insert_after</code></em> is true. If the item
+ designated by the <em class="parameter"><code>path</code></em> is an object
+ field, <em class="parameter"><code>new_value</code></em> will be inserted only if
+ the object does not already contain that key.
+ All earlier steps in the path must exist, or
+ the <em class="parameter"><code>target</code></em> is returned unchanged.
+ As with the path oriented operators, negative integers that
+ appear in the <em class="parameter"><code>path</code></em> count from the end
+ of JSON arrays.
+ If the last path step is an array index that is out of range, the new
+ value is added at the beginning of the array if the index is negative,
+ or at the end of the array if it is positive.
+ </p>
+ <p>
+ <code class="literal">jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"')</code>
+ → <code class="returnvalue">{"a": [0, "new_value", 1, 2]}</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"', true)</code>
+ → <code class="returnvalue">{"a": [0, 1, "new_value", 2]}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">json_strip_nulls</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.16.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_strip_nulls</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Deletes all object fields that have null values from the given JSON
+ value, recursively. Null values that are not object fields are
+ untouched.
+ </p>
+ <p>
+ <code class="literal">json_strip_nulls('[{"f1":1, "f2":null}, 2, null, 3]')</code>
+ → <code class="returnvalue">[{"f1":1},2,null,3]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_exists</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Checks whether the JSON path returns any item for the specified JSON
+ value.
+ If the <em class="parameter"><code>vars</code></em> argument is specified, it must
+ be a JSON object, and its fields provide named values to be
+ substituted into the <code class="type">jsonpath</code> expression.
+ If the <em class="parameter"><code>silent</code></em> argument is specified and
+ is <code class="literal">true</code>, the function suppresses the same errors
+ as the <code class="literal">@?</code> and <code class="literal">@@</code> operators do.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_exists('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_match</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns the result of a JSON path predicate check for the specified
+ JSON value. Only the first item of the result is taken into account.
+ If the result is not Boolean, then <code class="literal">NULL</code> is returned.
+ The optional <em class="parameter"><code>vars</code></em>
+ and <em class="parameter"><code>silent</code></em> arguments act the same as
+ for <code class="function">jsonb_path_exists</code>.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_match('{"a":[1,2,3,4,5]}', 'exists($.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max))', '{"min":2, "max":4}')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">setof jsonb</code>
+ </p>
+ <p>
+ Returns all JSON items returned by the JSON path for the specified
+ JSON value.
+ The optional <em class="parameter"><code>vars</code></em>
+ and <em class="parameter"><code>silent</code></em> arguments act the same as
+ for <code class="function">jsonb_path_exists</code>.
+ </p>
+ <p>
+ <code class="literal">select * from jsonb_path_query('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ jsonb_path_query
+------------------
+ 2
+ 3
+ 4
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.20.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query_array</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Returns all JSON items returned by the JSON path for the specified
+ JSON value, as a JSON array.
+ The optional <em class="parameter"><code>vars</code></em>
+ and <em class="parameter"><code>silent</code></em> arguments act the same as
+ for <code class="function">jsonb_path_exists</code>.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</code>
+ → <code class="returnvalue">[2, 3, 4]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query_first</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Returns the first JSON item returned by the JSON path for the
+ specified JSON value. Returns <code class="literal">NULL</code> if there are no
+ results.
+ The optional <em class="parameter"><code>vars</code></em>
+ and <em class="parameter"><code>silent</code></em> arguments act the same as
+ for <code class="function">jsonb_path_exists</code>.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ &gt;= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_path_exists_tz</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.22.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_path_match_tz</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.22.1.3.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query_tz</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">setof jsonb</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.22.1.4.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query_array_tz</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.22.1.5.1" class="indexterm"></a>
+ <code class="function">jsonb_path_query_first_tz</code> ( <em class="parameter"><code>target</code></em> <code class="type">jsonb</code>, <em class="parameter"><code>path</code></em> <code class="type">jsonpath</code> [<span class="optional">, <em class="parameter"><code>vars</code></em> <code class="type">jsonb</code> [<span class="optional">, <em class="parameter"><code>silent</code></em> <code class="type">boolean</code> </span>]</span>] )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ These functions act like their counterparts described above without
+ the <code class="literal">_tz</code> suffix, except that these functions support
+ comparisons of date/time values that require timezone-aware
+ conversions. The example below requires interpretation of the
+ date-only value <code class="literal">2015-08-02</code> as a timestamp with time
+ zone, so the result depends on the current
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting. Due to this dependency, these
+ functions are marked as stable, which means these functions cannot be
+ used in indexes. Their counterparts are immutable, and so can be used
+ in indexes; but they will throw errors if asked to make such
+ comparisons.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]', '$[*] ? (@.datetime() &lt; "2015-08-02".datetime())')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">jsonb_pretty</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the given JSON value to pretty-printed, indented text.
+ </p>
+ <p>
+ <code class="literal">jsonb_pretty('[{"f1":1,"f2":null}, 2]')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+[
+ {
+ "f1": 1,
+ "f2": null
+ },
+ 2
+]
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.24.1.1.1" class="indexterm"></a>
+ <code class="function">json_typeof</code> ( <code class="type">json</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.22.5.11.2.2.24.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_typeof</code> ( <code class="type">jsonb</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the type of the top-level JSON value as a text string.
+ Possible types are
+ <code class="literal">object</code>, <code class="literal">array</code>,
+ <code class="literal">string</code>, <code class="literal">number</code>,
+ <code class="literal">boolean</code>, and <code class="literal">null</code>.
+ (The <code class="literal">null</code> result should not be confused
+ with an SQL NULL; see the examples.)
+ </p>
+ <p>
+ <code class="literal">json_typeof('-123.4')</code>
+ → <code class="returnvalue">number</code>
+ </p>
+ <p>
+ <code class="literal">json_typeof('null'::json)</code>
+ → <code class="returnvalue">null</code>
+ </p>
+ <p>
+ <code class="literal">json_typeof(NULL::json) IS NULL</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-SQLJSON-PATH"><div class="titlepage"><div><div><h3 class="title">9.16.2. The SQL/JSON Path Language</h3></div></div></div><a id="id-1.5.8.22.6.2" class="indexterm"></a><p>
+ SQL/JSON path expressions specify the items to be retrieved
+ from the JSON data, similar to XPath expressions used
+ for SQL access to XML. In <span class="productname">PostgreSQL</span>,
+ path expressions are implemented as the <code class="type">jsonpath</code>
+ data type and can use any elements described in
+ <a class="xref" href="datatype-json.html#DATATYPE-JSONPATH" title="8.14.7. jsonpath Type">Section 8.14.7</a>.
+ </p><p>
+ JSON query functions and operators
+ pass the provided path expression to the <em class="firstterm">path engine</em>
+ for evaluation. If the expression matches the queried JSON data,
+ the corresponding JSON item, or set of items, is returned.
+ Path expressions are written in the SQL/JSON path language
+ and can include arithmetic expressions and functions.
+ </p><p>
+ A path expression consists of a sequence of elements allowed
+ by the <code class="type">jsonpath</code> data type.
+ The path expression is normally evaluated from left to right, but
+ you can use parentheses to change the order of operations.
+ If the evaluation is successful, a sequence of JSON items is produced,
+ and the evaluation result is returned to the JSON query function
+ that completes the specified computation.
+ </p><p>
+ To refer to the JSON value being queried (the
+ <em class="firstterm">context item</em>), use the <code class="literal">$</code> variable
+ in the path expression. It can be followed by one or more
+ <a class="link" href="datatype-json.html#TYPE-JSONPATH-ACCESSORS" title="Table 8.25. jsonpath Accessors">accessor operators</a>,
+ which go down the JSON structure level by level to retrieve sub-items
+ of the context item. Each operator that follows deals with the
+ result of the previous evaluation step.
+ </p><p>
+ For example, suppose you have some JSON data from a GPS tracker that you
+ would like to parse, such as:
+</p><pre class="programlisting">
+{
+ "track": {
+ "segments": [
+ {
+ "location": [ 47.763, 13.4034 ],
+ "start time": "2018-10-14 10:05:14",
+ "HR": 73
+ },
+ {
+ "location": [ 47.706, 13.2635 ],
+ "start time": "2018-10-14 10:39:21",
+ "HR": 135
+ }
+ ]
+ }
+}
+</pre><p>
+ </p><p>
+ To retrieve the available track segments, you need to use the
+ <code class="literal">.<em class="replaceable"><code>key</code></em></code> accessor
+ operator to descend through surrounding JSON objects:
+</p><pre class="programlisting">
+$.track.segments
+</pre><p>
+ </p><p>
+ To retrieve the contents of an array, you typically use the
+ <code class="literal">[*]</code> operator. For example,
+ the following path will return the location coordinates for all
+ the available track segments:
+</p><pre class="programlisting">
+$.track.segments[*].location
+</pre><p>
+ </p><p>
+ To return the coordinates of the first segment only, you can
+ specify the corresponding subscript in the <code class="literal">[]</code>
+ accessor operator. Recall that JSON array indexes are 0-relative:
+</p><pre class="programlisting">
+$.track.segments[0].location
+</pre><p>
+ </p><p>
+ The result of each path evaluation step can be processed
+ by one or more <code class="type">jsonpath</code> operators and methods
+ listed in <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS" title="9.16.2.2. SQL/JSON Path Operators and Methods">Section 9.16.2.2</a>.
+ Each method name must be preceded by a dot. For example,
+ you can get the size of an array:
+</p><pre class="programlisting">
+$.track.segments.size()
+</pre><p>
+ More examples of using <code class="type">jsonpath</code> operators
+ and methods within path expressions appear below in
+ <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-PATH-OPERATORS" title="9.16.2.2. SQL/JSON Path Operators and Methods">Section 9.16.2.2</a>.
+ </p><p>
+ When defining a path, you can also use one or more
+ <em class="firstterm">filter expressions</em> that work similarly to the
+ <code class="literal">WHERE</code> clause in SQL. A filter expression begins with
+ a question mark and provides a condition in parentheses:
+
+</p><pre class="programlisting">
+? (<em class="replaceable"><code>condition</code></em>)
+</pre><p>
+ </p><p>
+ Filter expressions must be written just after the path evaluation step
+ to which they should apply. The result of that step is filtered to include
+ only those items that satisfy the provided condition. SQL/JSON defines
+ three-valued logic, so the condition can be <code class="literal">true</code>, <code class="literal">false</code>,
+ or <code class="literal">unknown</code>. The <code class="literal">unknown</code> value
+ plays the same role as SQL <code class="literal">NULL</code> and can be tested
+ for with the <code class="literal">is unknown</code> predicate. Further path
+ evaluation steps use only those items for which the filter expression
+ returned <code class="literal">true</code>.
+ </p><p>
+ The functions and operators that can be used in filter expressions are
+ listed in <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-FILTER-EX-TABLE" title="Table 9.50. jsonpath Filter Expression Elements">Table 9.50</a>. Within a
+ filter expression, the <code class="literal">@</code> variable denotes the value
+ being filtered (i.e., one result of the preceding path step). You can
+ write accessor operators after <code class="literal">@</code> to retrieve component
+ items.
+ </p><p>
+ For example, suppose you would like to retrieve all heart rate values higher
+ than 130. You can achieve this using the following expression:
+</p><pre class="programlisting">
+$.track.segments[*].HR ? (@ &gt; 130)
+</pre><p>
+ </p><p>
+ To get the start times of segments with such values, you have to
+ filter out irrelevant segments before returning the start times, so the
+ filter expression is applied to the previous step, and the path used
+ in the condition is different:
+</p><pre class="programlisting">
+$.track.segments[*] ? (@.HR &gt; 130)."start time"
+</pre><p>
+ </p><p>
+ You can use several filter expressions in sequence, if required. For
+ example, the following expression selects start times of all segments that
+ contain locations with relevant coordinates and high heart rate values:
+</p><pre class="programlisting">
+$.track.segments[*] ? (@.location[1] &lt; 13.4) ? (@.HR &gt; 130)."start time"
+</pre><p>
+ </p><p>
+ Using filter expressions at different nesting levels is also allowed.
+ The following example first filters all segments by location, and then
+ returns high heart rate values for these segments, if available:
+</p><pre class="programlisting">
+$.track.segments[*] ? (@.location[1] &lt; 13.4).HR ? (@ &gt; 130)
+</pre><p>
+ </p><p>
+ You can also nest filter expressions within each other:
+</p><pre class="programlisting">
+$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size()
+</pre><p>
+ This expression returns the size of the track if it contains any
+ segments with high heart rate values, or an empty sequence otherwise.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s implementation of the SQL/JSON path
+ language has the following deviations from the SQL/JSON standard:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A path expression can be a Boolean predicate, although the SQL/JSON
+ standard allows predicates only in filters. This is necessary for
+ implementation of the <code class="literal">@@</code> operator. For example,
+ the following <code class="type">jsonpath</code> expression is valid in
+ <span class="productname">PostgreSQL</span>:
+</p><pre class="programlisting">
+$.track.segments[*].HR &lt; 70
+</pre><p>
+ </p></li><li class="listitem"><p>
+ There are minor differences in the interpretation of regular
+ expression patterns used in <code class="literal">like_regex</code> filters, as
+ described in <a class="xref" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS" title="9.16.2.3. SQL/JSON Regular Expressions">Section 9.16.2.3</a>.
+ </p></li></ul></div><div class="sect3" id="STRICT-AND-LAX-MODES"><div class="titlepage"><div><div><h4 class="title">9.16.2.1. Strict and Lax Modes</h4></div></div></div><p>
+ When you query JSON data, the path expression may not match the
+ actual JSON data structure. An attempt to access a non-existent
+ member of an object or element of an array results in a
+ structural error. SQL/JSON path expressions have two modes
+ of handling structural errors:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ lax (default) — the path engine implicitly adapts
+ the queried data to the specified path.
+ Any remaining structural errors are suppressed and converted
+ to empty SQL/JSON sequences.
+ </p></li><li class="listitem"><p>
+ strict — if a structural error occurs, an error is raised.
+ </p></li></ul></div><p>
+ The lax mode facilitates matching of a JSON document structure and path
+ expression if the JSON data does not conform to the expected schema.
+ If an operand does not match the requirements of a particular operation,
+ it can be automatically wrapped as an SQL/JSON array or unwrapped by
+ converting its elements into an SQL/JSON sequence before performing
+ this operation. Besides, comparison operators automatically unwrap their
+ operands in the lax mode, so you can compare SQL/JSON arrays
+ out-of-the-box. An array of size 1 is considered equal to its sole element.
+ Automatic unwrapping is not performed only when:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The path expression contains <code class="literal">type()</code> or
+ <code class="literal">size()</code> methods that return the type
+ and the number of elements in the array, respectively.
+ </p></li><li class="listitem"><p>
+ The queried JSON data contain nested arrays. In this case, only
+ the outermost array is unwrapped, while all the inner arrays
+ remain unchanged. Thus, implicit unwrapping can only go one
+ level down within each path evaluation step.
+ </p></li></ul></div><p>
+ </p><p>
+ For example, when querying the GPS data listed above, you can
+ abstract from the fact that it stores an array of segments
+ when using the lax mode:
+</p><pre class="programlisting">
+lax $.track.segments.location
+</pre><p>
+ </p><p>
+ In the strict mode, the specified path must exactly match the structure of
+ the queried JSON document to return an SQL/JSON item, so using this
+ path expression will cause an error. To get the same result as in
+ the lax mode, you have to explicitly unwrap the
+ <code class="literal">segments</code> array:
+</p><pre class="programlisting">
+strict $.track.segments[*].location
+</pre><p>
+ </p><p>
+ The <code class="literal">.**</code> accessor can lead to surprising results
+ when using the lax mode. For instance, the following query selects every
+ <code class="literal">HR</code> value twice:
+</p><pre class="programlisting">
+lax $.**.HR
+</pre><p>
+ This happens because the <code class="literal">.**</code> accessor selects both
+ the <code class="literal">segments</code> array and each of its elements, while
+ the <code class="literal">.HR</code> accessor automatically unwraps arrays when
+ using the lax mode. To avoid surprising results, we recommend using
+ the <code class="literal">.**</code> accessor only in the strict mode. The
+ following query selects each <code class="literal">HR</code> value just once:
+</p><pre class="programlisting">
+strict $.**.HR
+</pre><p>
+ </p></div><div class="sect3" id="FUNCTIONS-SQLJSON-PATH-OPERATORS"><div class="titlepage"><div><div><h4 class="title">9.16.2.2. SQL/JSON Path Operators and Methods</h4></div></div></div><p>
+ <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-OP-TABLE" title="Table 9.49. jsonpath Operators and Methods">Table 9.49</a> shows the operators and
+ methods available in <code class="type">jsonpath</code>. Note that while the unary
+ operators and methods can be applied to multiple values resulting from a
+ preceding path step, the binary operators (addition etc.) can only be
+ applied to single values.
+ </p><div class="table" id="FUNCTIONS-SQLJSON-OP-TABLE"><p class="title"><strong>Table 9.49. <code class="type">jsonpath</code> Operators and Methods</strong></p><div class="table-contents"><table class="table" summary="jsonpath Operators and Methods" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator/Method
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">+</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Addition
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[2]', '$[0] + 3')</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">+</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Unary plus (no operation); unlike addition, this can iterate over
+ multiple values
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('{"x": [2,3,4]}', '+ $.x')</code>
+ → <code class="returnvalue">[2, 3, 4]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">-</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Subtraction
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[2]', '7 - $[0]')</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">-</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Negation; unlike subtraction, this can iterate over
+ multiple values
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('{"x": [2,3,4]}', '- $.x')</code>
+ → <code class="returnvalue">[-2, -3, -4]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">*</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Multiplication
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[4]', '2 * $[0]')</code>
+ → <code class="returnvalue">8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">/</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Division
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[8.5]', '$[0] / 2')</code>
+ → <code class="returnvalue">4.2500000000000000</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">%</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Modulo (remainder)
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[32]', '$[0] % 10')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">.</code> <code class="literal">type()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>string</code></em></code>
+ </p>
+ <p>
+ Type of the JSON item (see <code class="function">json_typeof</code>)
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, "2", {}]', '$[*].type()')</code>
+ → <code class="returnvalue">["number", "string", "object"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">.</code> <code class="literal">size()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Size of the JSON item (number of array elements, or 1 if not an
+ array)
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"m": [11, 15]}', '$.m.size()')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">.</code> <code class="literal">double()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Approximate floating-point number converted from a JSON number or
+ string
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"len": "1.9"}', '$.len.double() * 2')</code>
+ → <code class="returnvalue">3.8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">.</code> <code class="literal">ceiling()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Nearest integer greater than or equal to the given number
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"h": 1.3}', '$.h.ceiling()')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">.</code> <code class="literal">floor()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Nearest integer less than or equal to the given number
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"h": 1.7}', '$.h.floor()')</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">.</code> <code class="literal">abs()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Absolute value of the given number
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"z": -0.3}', '$.z.abs()')</code>
+ → <code class="returnvalue">0.3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>string</code></em> <code class="literal">.</code> <code class="literal">datetime()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>datetime_type</code></em></code>
+ (see note)
+ </p>
+ <p>
+ Date/time value converted from a string
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('["2015-8-1", "2015-08-12"]', '$[*] ? (@.datetime() &lt; "2015-08-2".datetime())')</code>
+ → <code class="returnvalue">"2015-8-1"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>string</code></em> <code class="literal">.</code> <code class="literal">datetime(<em class="replaceable"><code>template</code></em>)</code>
+ → <code class="returnvalue"><em class="replaceable"><code>datetime_type</code></em></code>
+ (see note)
+ </p>
+ <p>
+ Date/time value converted from a string using the
+ specified <code class="function">to_timestamp</code> template
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('["12:30", "18:40"]', '$[*].datetime("HH24:MI")')</code>
+ → <code class="returnvalue">["12:30:00", "18:40:00"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>object</code></em> <code class="literal">.</code> <code class="literal">keyvalue()</code>
+ → <code class="returnvalue"><em class="replaceable"><code>array</code></em></code>
+ </p>
+ <p>
+ The object's key-value pairs, represented as an array of objects
+ containing three fields: <code class="literal">"key"</code>,
+ <code class="literal">"value"</code>, and <code class="literal">"id"</code>;
+ <code class="literal">"id"</code> is a unique identifier of the object the
+ key-value pair belongs to
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('{"x": "20", "y": 32}', '$.keyvalue()')</code>
+ → <code class="returnvalue">[{"id": 0, "key": "x", "value": "20"}, {"id": 0, "key": "y", "value": 32}]</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The result type of the <code class="literal">datetime()</code> and
+ <code class="literal">datetime(<em class="replaceable"><code>template</code></em>)</code>
+ methods can be <code class="type">date</code>, <code class="type">timetz</code>, <code class="type">time</code>,
+ <code class="type">timestamptz</code>, or <code class="type">timestamp</code>.
+ Both methods determine their result type dynamically.
+ </p><p>
+ The <code class="literal">datetime()</code> method sequentially tries to
+ match its input string to the ISO formats
+ for <code class="type">date</code>, <code class="type">timetz</code>, <code class="type">time</code>,
+ <code class="type">timestamptz</code>, and <code class="type">timestamp</code>. It stops on
+ the first matching format and emits the corresponding data type.
+ </p><p>
+ The <code class="literal">datetime(<em class="replaceable"><code>template</code></em>)</code>
+ method determines the result type according to the fields used in the
+ provided template string.
+ </p><p>
+ The <code class="literal">datetime()</code> and
+ <code class="literal">datetime(<em class="replaceable"><code>template</code></em>)</code> methods
+ use the same parsing rules as the <code class="literal">to_timestamp</code> SQL
+ function does (see <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>), with three
+ exceptions. First, these methods don't allow unmatched template
+ patterns. Second, only the following separators are allowed in the
+ template string: minus sign, period, solidus (slash), comma, apostrophe,
+ semicolon, colon and space. Third, separators in the template string
+ must exactly match the input string.
+ </p><p>
+ If different date/time types need to be compared, an implicit cast is
+ applied. A <code class="type">date</code> value can be cast to <code class="type">timestamp</code>
+ or <code class="type">timestamptz</code>, <code class="type">timestamp</code> can be cast to
+ <code class="type">timestamptz</code>, and <code class="type">time</code> to <code class="type">timetz</code>.
+ However, all but the first of these conversions depend on the current
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting, and thus can only be performed
+ within timezone-aware <code class="type">jsonpath</code> functions.
+ </p></div><p>
+ <a class="xref" href="functions-json.html#FUNCTIONS-SQLJSON-FILTER-EX-TABLE" title="Table 9.50. jsonpath Filter Expression Elements">Table 9.50</a> shows the available
+ filter expression elements.
+ </p><div class="table" id="FUNCTIONS-SQLJSON-FILTER-EX-TABLE"><p class="title"><strong>Table 9.50. <code class="type">jsonpath</code> Filter Expression Elements</strong></p><div class="table-contents"><table class="table" summary="jsonpath Filter Expression Elements" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Predicate/Value
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">==</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Equality comparison (this, and the other comparison operators, work on
+ all JSON scalar values)
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, "a", 1, 3]', '$[*] ? (@ == 1)')</code>
+ → <code class="returnvalue">[1, 1]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, "a", 1, 3]', '$[*] ? (@ == "a")')</code>
+ → <code class="returnvalue">["a"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">!=</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">&lt;&gt;</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Non-equality comparison
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, 2, 1, 3]', '$[*] ? (@ != 1)')</code>
+ → <code class="returnvalue">[2, 3]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('["a", "b", "c"]', '$[*] ? (@ &lt;&gt; "b")')</code>
+ → <code class="returnvalue">["a", "c"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Less-than comparison
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, 2, 3]', '$[*] ? (@ &lt; 2)')</code>
+ → <code class="returnvalue">[1]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">&lt;=</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Less-than-or-equal-to comparison
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('["a", "b", "c"]', '$[*] ? (@ &lt;= "b")')</code>
+ → <code class="returnvalue">["a", "b"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">&gt;</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Greater-than comparison
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, 2, 3]', '$[*] ? (@ &gt; 2)')</code>
+ → <code class="returnvalue">[3]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">&gt;=</code> <em class="replaceable"><code>value</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Greater-than-or-equal-to comparison
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('[1, 2, 3]', '$[*] ? (@ &gt;= 2)')</code>
+ → <code class="returnvalue">[2, 3]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">true</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ JSON constant <code class="literal">true</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[{"name": "John", "parent": false}, {"name": "Chris", "parent": true}]', '$[*] ? (@.parent == true)')</code>
+ → <code class="returnvalue">{"name": "Chris", "parent": true}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">false</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ JSON constant <code class="literal">false</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[{"name": "John", "parent": false}, {"name": "Chris", "parent": true}]', '$[*] ? (@.parent == false)')</code>
+ → <code class="returnvalue">{"name": "John", "parent": false}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">null</code>
+ → <code class="returnvalue"><em class="replaceable"><code>value</code></em></code>
+ </p>
+ <p>
+ JSON constant <code class="literal">null</code> (note that, unlike in SQL,
+ comparison to <code class="literal">null</code> works normally)
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[{"name": "Mary", "job": null}, {"name": "Michael", "job": "driver"}]', '$[*] ? (@.job == null) .name')</code>
+ → <code class="returnvalue">"Mary"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">&amp;&amp;</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Boolean AND
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[1, 3, 7]', '$[*] ? (@ &gt; 1 &amp;&amp; @ &lt; 5)')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">||</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Boolean OR
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[1, 3, 7]', '$[*] ? (@ &lt; 1 || @ &gt; 5)')</code>
+ → <code class="returnvalue">7</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">!</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Boolean NOT
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[1, 3, 7]', '$[*] ? (!(@ &lt; 5))')</code>
+ → <code class="returnvalue">7</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">is unknown</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether a Boolean condition is <code class="literal">unknown</code>.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('[-1, 2, 7, "foo"]', '$[*] ? ((@ &gt; 0) is unknown)')</code>
+ → <code class="returnvalue">"foo"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>string</code></em> <code class="literal">like_regex</code> <em class="replaceable"><code>string</code></em> [<span class="optional"> <code class="literal">flag</code> <em class="replaceable"><code>string</code></em> </span>]
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether the first operand matches the regular expression
+ given by the second operand, optionally with modifications
+ described by a string of <code class="literal">flag</code> characters (see
+ <a class="xref" href="functions-json.html#JSONPATH-REGULAR-EXPRESSIONS" title="9.16.2.3. SQL/JSON Regular Expressions">Section 9.16.2.3</a>).
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('["abc", "abd", "aBdC", "abdacb", "babc"]', '$[*] ? (@ like_regex "^ab.*c")')</code>
+ → <code class="returnvalue">["abc", "abdacb"]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('["abc", "abd", "aBdC", "abdacb", "babc"]', '$[*] ? (@ like_regex "^ab.*c" flag "i")')</code>
+ → <code class="returnvalue">["abc", "aBdC", "abdacb"]</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>string</code></em> <code class="literal">starts with</code> <em class="replaceable"><code>string</code></em>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether the second operand is an initial substring of the first
+ operand.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('["John Smith", "Mary Stone", "Bob Johnson"]', '$[*] ? (@ starts with "John")')</code>
+ → <code class="returnvalue">"John Smith"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">exists</code> <code class="literal">(</code> <em class="replaceable"><code>path_expression</code></em> <code class="literal">)</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether a path expression matches at least one SQL/JSON item.
+ Returns <code class="literal">unknown</code> if the path expression would result
+ in an error; the second example uses this to avoid a no-such-key error
+ in strict mode.
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query('{"x": [1, 2], "y": [2, 4]}', 'strict $.* ? (exists (@ ? (@[*] &gt; 2)))')</code>
+ → <code class="returnvalue">[2, 4]</code>
+ </p>
+ <p>
+ <code class="literal">jsonb_path_query_array('{"value": 41}', 'strict $ ? (exists (@.name)) .name')</code>
+ → <code class="returnvalue">[]</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect3" id="JSONPATH-REGULAR-EXPRESSIONS"><div class="titlepage"><div><div><h4 class="title">9.16.2.3. SQL/JSON Regular Expressions</h4></div></div></div><a id="id-1.5.8.22.6.24.2" class="indexterm"></a><p>
+ SQL/JSON path expressions allow matching text to a regular expression
+ with the <code class="literal">like_regex</code> filter. For example, the
+ following SQL/JSON path query would case-insensitively match all
+ strings in an array that start with an English vowel:
+</p><pre class="programlisting">
+$[*] ? (@ like_regex "^[aeiou]" flag "i")
+</pre><p>
+ </p><p>
+ The optional <code class="literal">flag</code> string may include one or more of
+ the characters
+ <code class="literal">i</code> for case-insensitive match,
+ <code class="literal">m</code> to allow <code class="literal">^</code>
+ and <code class="literal">$</code> to match at newlines,
+ <code class="literal">s</code> to allow <code class="literal">.</code> to match a newline,
+ and <code class="literal">q</code> to quote the whole pattern (reducing the
+ behavior to a simple substring match).
+ </p><p>
+ The SQL/JSON standard borrows its definition for regular expressions
+ from the <code class="literal">LIKE_REGEX</code> operator, which in turn uses the
+ XQuery standard. PostgreSQL does not currently support the
+ <code class="literal">LIKE_REGEX</code> operator. Therefore,
+ the <code class="literal">like_regex</code> filter is implemented using the
+ POSIX regular expression engine described in
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>. This leads to various minor
+ discrepancies from standard SQL/JSON behavior, which are cataloged in
+ <a class="xref" href="functions-matching.html#POSIX-VS-XQUERY" title="9.7.3.8. Differences from SQL Standard and XQuery">Section 9.7.3.8</a>.
+ Note, however, that the flag-letter incompatibilities described there
+ do not apply to SQL/JSON, as it translates the XQuery flag letters to
+ match what the POSIX engine expects.
+ </p><p>
+ Keep in mind that the pattern argument of <code class="literal">like_regex</code>
+ is a JSON path string literal, written according to the rules given in
+ <a class="xref" href="datatype-json.html#DATATYPE-JSONPATH" title="8.14.7. jsonpath Type">Section 8.14.7</a>. This means in particular that any
+ backslashes you want to use in the regular expression must be doubled.
+ For example, to match string values of the root document that contain
+ only digits:
+</p><pre class="programlisting">
+$.* ? (@ like_regex "^\\d+$")
+</pre><p>
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-xml.html" title="9.15. XML Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.15. XML Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.17. Sequence Manipulation Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-logical.html b/doc/src/sgml/html/functions-logical.html
new file mode 100644
index 0000000..452db72
--- /dev/null
+++ b/doc/src/sgml/html/functions-logical.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.1. Logical Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions.html" title="Chapter 9. Functions and Operators" /><link rel="next" href="functions-comparison.html" title="9.2. Comparison Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.1. Logical Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions.html" title="Chapter 9. Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-LOGICAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.1. Logical Operators</h2></div></div></div><a id="id-1.5.8.7.2" class="indexterm"></a><a id="id-1.5.8.7.3" class="indexterm"></a><p>
+ The usual logical operators are available:
+
+ <a id="id-1.5.8.7.4.1" class="indexterm"></a>
+
+ <a id="id-1.5.8.7.4.2" class="indexterm"></a>
+
+ <a id="id-1.5.8.7.4.3" class="indexterm"></a>
+
+ <a id="id-1.5.8.7.4.4" class="indexterm"></a>
+
+ <a id="id-1.5.8.7.4.5" class="indexterm"></a>
+
+ <a id="id-1.5.8.7.4.6" class="indexterm"></a>
+
+</p><pre class="synopsis">
+<code class="type">boolean</code> <code class="literal">AND</code> <code class="type">boolean</code> → <code class="returnvalue">boolean</code>
+<code class="type">boolean</code> <code class="literal">OR</code> <code class="type">boolean</code> → <code class="returnvalue">boolean</code>
+<code class="literal">NOT</code> <code class="type">boolean</code> → <code class="returnvalue">boolean</code>
+</pre><p>
+
+ <acronym class="acronym">SQL</acronym> uses a three-valued logic system with true,
+ false, and <code class="literal">null</code>, which represents <span class="quote">“<span class="quote">unknown</span>”</span>.
+ Observe the following truth tables:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th><em class="replaceable"><code>a</code></em></th><th><em class="replaceable"><code>b</code></em></th><th><em class="replaceable"><code>a</code></em> AND <em class="replaceable"><code>b</code></em></th><th><em class="replaceable"><code>a</code></em> OR <em class="replaceable"><code>b</code></em></th></tr></thead><tbody><tr><td>TRUE</td><td>TRUE</td><td>TRUE</td><td>TRUE</td></tr><tr><td>TRUE</td><td>FALSE</td><td>FALSE</td><td>TRUE</td></tr><tr><td>TRUE</td><td>NULL</td><td>NULL</td><td>TRUE</td></tr><tr><td>FALSE</td><td>FALSE</td><td>FALSE</td><td>FALSE</td></tr><tr><td>FALSE</td><td>NULL</td><td>FALSE</td><td>NULL</td></tr><tr><td>NULL</td><td>NULL</td><td>NULL</td><td>NULL</td></tr></tbody></table></div><p>
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><em class="replaceable"><code>a</code></em></th><th>NOT <em class="replaceable"><code>a</code></em></th></tr></thead><tbody><tr><td>TRUE</td><td>FALSE</td></tr><tr><td>FALSE</td><td>TRUE</td></tr><tr><td>NULL</td><td>NULL</td></tr></tbody></table></div><p>
+ </p><p>
+ The operators <code class="literal">AND</code> and <code class="literal">OR</code> are
+ commutative, that is, you can switch the left and right operands
+ without affecting the result. (However, it is not guaranteed that
+ the left operand is evaluated before the right operand. See <a class="xref" href="sql-expressions.html#SYNTAX-EXPRESS-EVAL" title="4.2.14. Expression Evaluation Rules">Section 4.2.14</a> for more information about the
+ order of evaluation of subexpressions.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions.html" title="Chapter 9. Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.2. Comparison Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-matching.html b/doc/src/sgml/html/functions-matching.html
new file mode 100644
index 0000000..840fa71
--- /dev/null
+++ b/doc/src/sgml/html/functions-matching.html
@@ -0,0 +1,1415 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.7. Pattern Matching</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators" /><link rel="next" href="functions-formatting.html" title="9.8. Data Type Formatting Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.7. Pattern Matching</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-MATCHING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.7. Pattern Matching</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-LIKE">9.7.1. <code class="function">LIKE</code></a></span></dt><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP">9.7.2. <code class="function">SIMILAR TO</code> Regular Expressions</a></span></dt><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">9.7.3. <acronym class="acronym">POSIX</acronym> Regular Expressions</a></span></dt></dl></div><a id="id-1.5.8.13.2" class="indexterm"></a><p>
+ There are three separate approaches to pattern matching provided
+ by <span class="productname">PostgreSQL</span>: the traditional
+ <acronym class="acronym">SQL</acronym> <code class="function">LIKE</code> operator, the
+ more recent <code class="function">SIMILAR TO</code> operator (added in
+ SQL:1999), and <acronym class="acronym">POSIX</acronym>-style regular
+ expressions. Aside from the basic <span class="quote">“<span class="quote">does this string match
+ this pattern?</span>”</span> operators, functions are available to extract
+ or replace matching substrings and to split a string at matching
+ locations.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If you have pattern matching needs that go beyond this,
+ consider writing a user-defined function in Perl or Tcl.
+ </p></div><div class="caution"><h3 class="title">Caution</h3><p>
+ While most regular-expression searches can be executed very quickly,
+ regular expressions can be contrived that take arbitrary amounts of
+ time and memory to process. Be wary of accepting regular-expression
+ search patterns from hostile sources. If you must do so, it is
+ advisable to impose a statement timeout.
+ </p><p>
+ Searches using <code class="function">SIMILAR TO</code> patterns have the same
+ security hazards, since <code class="function">SIMILAR TO</code> provides many
+ of the same capabilities as <acronym class="acronym">POSIX</acronym>-style regular
+ expressions.
+ </p><p>
+ <code class="function">LIKE</code> searches, being much simpler than the other
+ two options, are safer to use with possibly-hostile pattern sources.
+ </p></div><p>
+ The pattern matching operators of all three kinds do not support
+ nondeterministic collations. If required, apply a different collation to
+ the expression to work around this limitation.
+ </p><div class="sect2" id="FUNCTIONS-LIKE"><div class="titlepage"><div><div><h3 class="title">9.7.1. <code class="function">LIKE</code></h3></div></div></div><a id="id-1.5.8.13.7.2" class="indexterm"></a><pre class="synopsis">
+<em class="replaceable"><code>string</code></em> LIKE <em class="replaceable"><code>pattern</code></em> [<span class="optional">ESCAPE <em class="replaceable"><code>escape-character</code></em></span>]
+<em class="replaceable"><code>string</code></em> NOT LIKE <em class="replaceable"><code>pattern</code></em> [<span class="optional">ESCAPE <em class="replaceable"><code>escape-character</code></em></span>]
+</pre><p>
+ The <code class="function">LIKE</code> expression returns true if the
+ <em class="replaceable"><code>string</code></em> matches the supplied
+ <em class="replaceable"><code>pattern</code></em>. (As
+ expected, the <code class="function">NOT LIKE</code> expression returns
+ false if <code class="function">LIKE</code> returns true, and vice versa.
+ An equivalent expression is
+ <code class="literal">NOT (<em class="replaceable"><code>string</code></em> LIKE
+ <em class="replaceable"><code>pattern</code></em>)</code>.)
+ </p><p>
+ If <em class="replaceable"><code>pattern</code></em> does not contain percent
+ signs or underscores, then the pattern only represents the string
+ itself; in that case <code class="function">LIKE</code> acts like the
+ equals operator. An underscore (<code class="literal">_</code>) in
+ <em class="replaceable"><code>pattern</code></em> stands for (matches) any single
+ character; a percent sign (<code class="literal">%</code>) matches any sequence
+ of zero or more characters.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+'abc' LIKE 'abc' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abc' LIKE 'a%' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abc' LIKE '_b_' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abc' LIKE 'c' <em class="lineannotation"><span class="lineannotation">false</span></em>
+</pre><p>
+ </p><p>
+ <code class="function">LIKE</code> pattern matching always covers the entire
+ string. Therefore, if it's desired to match a sequence anywhere within
+ a string, the pattern must start and end with a percent sign.
+ </p><p>
+ To match a literal underscore or percent sign without matching
+ other characters, the respective character in
+ <em class="replaceable"><code>pattern</code></em> must be
+ preceded by the escape character. The default escape
+ character is the backslash but a different one can be selected by
+ using the <code class="literal">ESCAPE</code> clause. To match the escape
+ character itself, write two escape characters.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If you have <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> turned off,
+ any backslashes you write in literal string constants will need to be
+ doubled. See <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> for more information.
+ </p></div><p>
+ It's also possible to select no escape character by writing
+ <code class="literal">ESCAPE ''</code>. This effectively disables the
+ escape mechanism, which makes it impossible to turn off the
+ special meaning of underscore and percent signs in the pattern.
+ </p><p>
+ According to the SQL standard, omitting <code class="literal">ESCAPE</code>
+ means there is no escape character (rather than defaulting to a
+ backslash), and a zero-length <code class="literal">ESCAPE</code> value is
+ disallowed. <span class="productname">PostgreSQL</span>'s behavior in
+ this regard is therefore slightly nonstandard.
+ </p><p>
+ The key word <code class="token">ILIKE</code> can be used instead of
+ <code class="token">LIKE</code> to make the match case-insensitive according
+ to the active locale. This is not in the <acronym class="acronym">SQL</acronym> standard but is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p><p>
+ The operator <code class="literal">~~</code> is equivalent to
+ <code class="function">LIKE</code>, and <code class="literal">~~*</code> corresponds to
+ <code class="function">ILIKE</code>. There are also
+ <code class="literal">!~~</code> and <code class="literal">!~~*</code> operators that
+ represent <code class="function">NOT LIKE</code> and <code class="function">NOT
+ ILIKE</code>, respectively. All of these operators are
+ <span class="productname">PostgreSQL</span>-specific. You may see these
+ operator names in <code class="command">EXPLAIN</code> output and similar
+ places, since the parser actually translates <code class="function">LIKE</code>
+ et al. to these operators.
+ </p><p>
+ The phrases <code class="function">LIKE</code>, <code class="function">ILIKE</code>,
+ <code class="function">NOT LIKE</code>, and <code class="function">NOT ILIKE</code> are
+ generally treated as operators
+ in <span class="productname">PostgreSQL</span> syntax; for example they can
+ be used in <em class="replaceable"><code>expression</code></em>
+ <em class="replaceable"><code>operator</code></em> ANY
+ (<em class="replaceable"><code>subquery</code></em>) constructs, although
+ an <code class="literal">ESCAPE</code> clause cannot be included there. In some
+ obscure cases it may be necessary to use the underlying operator names
+ instead.
+ </p><p>
+ Also see the starts-with operator <code class="literal">^@</code> and the
+ corresponding <code class="function">starts_with()</code> function, which are
+ useful in cases where simply matching the beginning of a string is
+ needed.
+ </p></div><div class="sect2" id="FUNCTIONS-SIMILARTO-REGEXP"><div class="titlepage"><div><div><h3 class="title">9.7.2. <code class="function">SIMILAR TO</code> Regular Expressions</h3></div></div></div><a id="id-1.5.8.13.8.2" class="indexterm"></a><a id="id-1.5.8.13.8.3" class="indexterm"></a><a id="id-1.5.8.13.8.4" class="indexterm"></a><pre class="synopsis">
+<em class="replaceable"><code>string</code></em> SIMILAR TO <em class="replaceable"><code>pattern</code></em> [<span class="optional">ESCAPE <em class="replaceable"><code>escape-character</code></em></span>]
+<em class="replaceable"><code>string</code></em> NOT SIMILAR TO <em class="replaceable"><code>pattern</code></em> [<span class="optional">ESCAPE <em class="replaceable"><code>escape-character</code></em></span>]
+</pre><p>
+ The <code class="function">SIMILAR TO</code> operator returns true or
+ false depending on whether its pattern matches the given string.
+ It is similar to <code class="function">LIKE</code>, except that it
+ interprets the pattern using the SQL standard's definition of a
+ regular expression. SQL regular expressions are a curious cross
+ between <code class="function">LIKE</code> notation and common (POSIX) regular
+ expression notation.
+ </p><p>
+ Like <code class="function">LIKE</code>, the <code class="function">SIMILAR TO</code>
+ operator succeeds only if its pattern matches the entire string;
+ this is unlike common regular expression behavior where the pattern
+ can match any part of the string.
+ Also like
+ <code class="function">LIKE</code>, <code class="function">SIMILAR TO</code> uses
+ <code class="literal">_</code> and <code class="literal">%</code> as wildcard characters denoting
+ any single character and any string, respectively (these are
+ comparable to <code class="literal">.</code> and <code class="literal">.*</code> in POSIX regular
+ expressions).
+ </p><p>
+ In addition to these facilities borrowed from <code class="function">LIKE</code>,
+ <code class="function">SIMILAR TO</code> supports these pattern-matching
+ metacharacters borrowed from POSIX regular expressions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">|</code> denotes alternation (either of two alternatives).
+ </p></li><li class="listitem"><p>
+ <code class="literal">*</code> denotes repetition of the previous item zero
+ or more times.
+ </p></li><li class="listitem"><p>
+ <code class="literal">+</code> denotes repetition of the previous item one
+ or more times.
+ </p></li><li class="listitem"><p>
+ <code class="literal">?</code> denotes repetition of the previous item zero
+ or one time.
+ </p></li><li class="listitem"><p>
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}</code> denotes repetition
+ of the previous item exactly <em class="replaceable"><code>m</code></em> times.
+ </p></li><li class="listitem"><p>
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,}</code> denotes repetition
+ of the previous item <em class="replaceable"><code>m</code></em> or more times.
+ </p></li><li class="listitem"><p>
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}</code>
+ denotes repetition of the previous item at least <em class="replaceable"><code>m</code></em> and
+ not more than <em class="replaceable"><code>n</code></em> times.
+ </p></li><li class="listitem"><p>
+ Parentheses <code class="literal">()</code> can be used to group items into
+ a single logical item.
+ </p></li><li class="listitem"><p>
+ A bracket expression <code class="literal">[...]</code> specifies a character
+ class, just as in POSIX regular expressions.
+ </p></li></ul></div><p>
+
+ Notice that the period (<code class="literal">.</code>) is not a metacharacter
+ for <code class="function">SIMILAR TO</code>.
+ </p><p>
+ As with <code class="function">LIKE</code>, a backslash disables the special
+ meaning of any of these metacharacters. A different escape character
+ can be specified with <code class="literal">ESCAPE</code>, or the escape
+ capability can be disabled by writing <code class="literal">ESCAPE ''</code>.
+ </p><p>
+ According to the SQL standard, omitting <code class="literal">ESCAPE</code>
+ means there is no escape character (rather than defaulting to a
+ backslash), and a zero-length <code class="literal">ESCAPE</code> value is
+ disallowed. <span class="productname">PostgreSQL</span>'s behavior in
+ this regard is therefore slightly nonstandard.
+ </p><p>
+ Another nonstandard extension is that following the escape character
+ with a letter or digit provides access to the escape sequences
+ defined for POSIX regular expressions; see
+ <a class="xref" href="functions-matching.html#POSIX-CHARACTER-ENTRY-ESCAPES-TABLE" title="Table 9.20. Regular Expression Character-Entry Escapes">Table 9.20</a>,
+ <a class="xref" href="functions-matching.html#POSIX-CLASS-SHORTHAND-ESCAPES-TABLE" title="Table 9.21. Regular Expression Class-Shorthand Escapes">Table 9.21</a>, and
+ <a class="xref" href="functions-matching.html#POSIX-CONSTRAINT-ESCAPES-TABLE" title="Table 9.22. Regular Expression Constraint Escapes">Table 9.22</a> below.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+'abc' SIMILAR TO 'abc' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abc' SIMILAR TO 'a' <em class="lineannotation"><span class="lineannotation">false</span></em>
+'abc' SIMILAR TO '%(b|d)%' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abc' SIMILAR TO '(b|c)%' <em class="lineannotation"><span class="lineannotation">false</span></em>
+'-abc-' SIMILAR TO '%\mabc\M%' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'xabcy' SIMILAR TO '%\mabc\M%' <em class="lineannotation"><span class="lineannotation">false</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">substring</code> function with three parameters
+ provides extraction of a substring that matches an SQL
+ regular expression pattern. The function can be written according
+ to standard SQL syntax:
+</p><pre class="synopsis">
+substring(<em class="replaceable"><code>string</code></em> similar <em class="replaceable"><code>pattern</code></em> escape <em class="replaceable"><code>escape-character</code></em>)
+</pre><p>
+ or using the now obsolete SQL:1999 syntax:
+</p><pre class="synopsis">
+substring(<em class="replaceable"><code>string</code></em> from <em class="replaceable"><code>pattern</code></em> for <em class="replaceable"><code>escape-character</code></em>)
+</pre><p>
+ or as a plain three-argument function:
+</p><pre class="synopsis">
+substring(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>, <em class="replaceable"><code>escape-character</code></em>)
+</pre><p>
+ As with <code class="literal">SIMILAR TO</code>, the
+ specified pattern must match the entire data string, or else the
+ function fails and returns null. To indicate the part of the
+ pattern for which the matching data sub-string is of interest,
+ the pattern should contain
+ two occurrences of the escape character followed by a double quote
+ (<code class="literal">"</code>).
+ The text matching the portion of the pattern
+ between these separators is returned when the match is successful.
+ </p><p>
+ The escape-double-quote separators actually
+ divide <code class="function">substring</code>'s pattern into three independent
+ regular expressions; for example, a vertical bar (<code class="literal">|</code>)
+ in any of the three sections affects only that section. Also, the first
+ and third of these regular expressions are defined to match the smallest
+ possible amount of text, not the largest, when there is any ambiguity
+ about how much of the data string matches which pattern. (In POSIX
+ parlance, the first and third regular expressions are forced to be
+ non-greedy.)
+ </p><p>
+ As an extension to the SQL standard, <span class="productname">PostgreSQL</span>
+ allows there to be just one escape-double-quote separator, in which case
+ the third regular expression is taken as empty; or no separators, in which
+ case the first and third regular expressions are taken as empty.
+ </p><p>
+ Some examples, with <code class="literal">#"</code> delimiting the return string:
+</p><pre class="programlisting">
+substring('foobar' similar '%#"o_b#"%' escape '#') <em class="lineannotation"><span class="lineannotation">oob</span></em>
+substring('foobar' similar '#"o_b#"%' escape '#') <em class="lineannotation"><span class="lineannotation">NULL</span></em>
+</pre><p>
+ </p></div><div class="sect2" id="FUNCTIONS-POSIX-REGEXP"><div class="titlepage"><div><div><h3 class="title">9.7.3. <acronym class="acronym">POSIX</acronym> Regular Expressions</h3></div></div></div><a id="id-1.5.8.13.9.2" class="indexterm"></a><a id="id-1.5.8.13.9.3" class="indexterm"></a><a id="id-1.5.8.13.9.4" class="indexterm"></a><a id="id-1.5.8.13.9.5" class="indexterm"></a><a id="id-1.5.8.13.9.6" class="indexterm"></a><a id="id-1.5.8.13.9.7" class="indexterm"></a><a id="id-1.5.8.13.9.8" class="indexterm"></a><a id="id-1.5.8.13.9.9" class="indexterm"></a><a id="id-1.5.8.13.9.10" class="indexterm"></a><a id="id-1.5.8.13.9.11" class="indexterm"></a><a id="id-1.5.8.13.9.12" class="indexterm"></a><p>
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-TABLE" title="Table 9.16. Regular Expression Match Operators">Table 9.16</a> lists the available
+ operators for pattern matching using POSIX regular expressions.
+ </p><div class="table" id="FUNCTIONS-POSIX-TABLE"><p class="title"><strong>Table 9.16. Regular Expression Match Operators</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Match Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">~</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ String matches regular expression, case sensitively
+ </p>
+ <p>
+ <code class="literal">'thomas' ~ 't.*ma'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">~*</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ String matches regular expression, case insensitively
+ </p>
+ <p>
+ <code class="literal">'thomas' ~* 'T.*ma'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">!~</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ String does not match regular expression, case sensitively
+ </p>
+ <p>
+ <code class="literal">'thomas' !~ 't.*max'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">!~*</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ String does not match regular expression, case insensitively
+ </p>
+ <p>
+ <code class="literal">'thomas' !~* 'T.*ma'</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <acronym class="acronym">POSIX</acronym> regular expressions provide a more
+ powerful means for pattern matching than the <code class="function">LIKE</code> and
+ <code class="function">SIMILAR TO</code> operators.
+ Many Unix tools such as <code class="command">egrep</code>,
+ <code class="command">sed</code>, or <code class="command">awk</code> use a pattern
+ matching language that is similar to the one described here.
+ </p><p>
+ A regular expression is a character sequence that is an
+ abbreviated definition of a set of strings (a <em class="firstterm">regular
+ set</em>). A string is said to match a regular expression
+ if it is a member of the regular set described by the regular
+ expression. As with <code class="function">LIKE</code>, pattern characters
+ match string characters exactly unless they are special characters
+ in the regular expression language — but regular expressions use
+ different special characters than <code class="function">LIKE</code> does.
+ Unlike <code class="function">LIKE</code> patterns, a
+ regular expression is allowed to match anywhere within a string, unless
+ the regular expression is explicitly anchored to the beginning or
+ end of the string.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+'abcd' ~ 'bc' <em class="lineannotation"><span class="lineannotation">true</span></em>
+'abcd' ~ 'a.c' <em class="lineannotation"><span class="lineannotation">true — dot matches any character</span></em>
+'abcd' ~ 'a.*d' <em class="lineannotation"><span class="lineannotation">true — <code class="literal">*</code> repeats the preceding pattern item</span></em>
+'abcd' ~ '(b|x)' <em class="lineannotation"><span class="lineannotation">true — <code class="literal">|</code> means OR, parentheses group</span></em>
+'abcd' ~ '^a' <em class="lineannotation"><span class="lineannotation">true — <code class="literal">^</code> anchors to start of string</span></em>
+'abcd' ~ '^(b|c)' <em class="lineannotation"><span class="lineannotation">false — would match except for anchoring</span></em>
+</pre><p>
+ </p><p>
+ The <acronym class="acronym">POSIX</acronym> pattern language is described in much
+ greater detail below.
+ </p><p>
+ The <code class="function">substring</code> function with two parameters,
+ <code class="function">substring(<em class="replaceable"><code>string</code></em> from
+ <em class="replaceable"><code>pattern</code></em>)</code>, provides extraction of a
+ substring
+ that matches a POSIX regular expression pattern. It returns null if
+ there is no match, otherwise the first portion of the text that matched the
+ pattern. But if the pattern contains any parentheses, the portion
+ of the text that matched the first parenthesized subexpression (the
+ one whose left parenthesis comes first) is
+ returned. You can put parentheses around the whole expression
+ if you want to use parentheses within it without triggering this
+ exception. If you need parentheses in the pattern before the
+ subexpression you want to extract, see the non-capturing parentheses
+ described below.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+substring('foobar' from 'o.b') <em class="lineannotation"><span class="lineannotation">oob</span></em>
+substring('foobar' from 'o(.)b') <em class="lineannotation"><span class="lineannotation">o</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">regexp_count</code> function counts the number of
+ places where a POSIX regular expression pattern matches a string.
+ It has the syntax
+ <code class="function">regexp_count</code>(<em class="replaceable"><code>string</code></em>,
+ <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>start</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em>
+ </span>]</span>]).
+ <em class="replaceable"><code>pattern</code></em> is searched for
+ in <em class="replaceable"><code>string</code></em>, normally from the beginning of
+ the string, but if the <em class="replaceable"><code>start</code></em> parameter is
+ provided then beginning from that character index.
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. For example, including <code class="literal">i</code> in
+ <em class="replaceable"><code>flags</code></em> specifies case-insensitive matching.
+ Supported flags are described in
+ <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+regexp_count('ABCABCAXYaxy', 'A.') <em class="lineannotation"><span class="lineannotation">3</span></em>
+regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') <em class="lineannotation"><span class="lineannotation">4</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">regexp_instr</code> function returns the starting or
+ ending position of the <em class="replaceable"><code>N</code></em>'th match of a
+ POSIX regular expression pattern to a string, or zero if there is no
+ such match. It has the syntax
+ <code class="function">regexp_instr</code>(<em class="replaceable"><code>string</code></em>,
+ <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>start</code></em>
+ [<span class="optional">, <em class="replaceable"><code>N</code></em>
+ [<span class="optional">, <em class="replaceable"><code>endoption</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em>
+ [<span class="optional">, <em class="replaceable"><code>subexpr</code></em>
+ </span>]</span>]</span>]</span>]</span>]).
+ <em class="replaceable"><code>pattern</code></em> is searched for
+ in <em class="replaceable"><code>string</code></em>, normally from the beginning of
+ the string, but if the <em class="replaceable"><code>start</code></em> parameter is
+ provided then beginning from that character index.
+ If <em class="replaceable"><code>N</code></em> is specified
+ then the <em class="replaceable"><code>N</code></em>'th match of the pattern
+ is located, otherwise the first match is located.
+ If the <em class="replaceable"><code>endoption</code></em> parameter is omitted or
+ specified as zero, the function returns the position of the first
+ character of the match. Otherwise, <em class="replaceable"><code>endoption</code></em>
+ must be one, and the function returns the position of the character
+ following the match.
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ For a pattern containing parenthesized
+ subexpressions, <em class="replaceable"><code>subexpr</code></em> is an integer
+ indicating which subexpression is of interest: the result identifies
+ the position of the substring matching that subexpression.
+ Subexpressions are numbered in the order of their leading parentheses.
+ When <em class="replaceable"><code>subexpr</code></em> is omitted or zero, the result
+ identifies the position of the whole match regardless of
+ parenthesized subexpressions.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2)
+ <em class="lineannotation"><span class="lineannotation">23</span></em>
+regexp_instr('ABCDEFGHI', '(c..)(...)', 1, 1, 0, 'i', 2)
+ <em class="lineannotation"><span class="lineannotation">6</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">regexp_like</code> function checks whether a match
+ of a POSIX regular expression pattern occurs within a string,
+ returning boolean true or false. It has the syntax
+ <code class="function">regexp_like</code>(<em class="replaceable"><code>string</code></em>,
+ <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em> </span>]).
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ This function has the same results as the <code class="literal">~</code>
+ operator if no flags are specified. If only the <code class="literal">i</code>
+ flag is specified, it has the same results as
+ the <code class="literal">~*</code> operator.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+regexp_like('Hello World', 'world') <em class="lineannotation"><span class="lineannotation">false</span></em>
+regexp_like('Hello World', 'world', 'i') <em class="lineannotation"><span class="lineannotation">true</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">regexp_match</code> function returns a text array of
+ matching substring(s) within the first match of a POSIX
+ regular expression pattern to a string. It has the syntax
+ <code class="function">regexp_match</code>(<em class="replaceable"><code>string</code></em>,
+ <em class="replaceable"><code>pattern</code></em> [<span class="optional">, <em class="replaceable"><code>flags</code></em> </span>]).
+ If there is no match, the result is <code class="literal">NULL</code>.
+ If a match is found, and the <em class="replaceable"><code>pattern</code></em> contains no
+ parenthesized subexpressions, then the result is a single-element text
+ array containing the substring matching the whole pattern.
+ If a match is found, and the <em class="replaceable"><code>pattern</code></em> contains
+ parenthesized subexpressions, then the result is a text array
+ whose <em class="replaceable"><code>n</code></em>'th element is the substring matching
+ the <em class="replaceable"><code>n</code></em>'th parenthesized subexpression of
+ the <em class="replaceable"><code>pattern</code></em> (not counting <span class="quote">“<span class="quote">non-capturing</span>”</span>
+ parentheses; see below for details).
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text string
+ containing zero or more single-letter flags that change the function's
+ behavior. Supported flags are described
+ in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+SELECT regexp_match('foobarbequebaz', 'bar.*que');
+ regexp_match
+--------------
+ {barbeque}
+(1 row)
+
+SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
+ regexp_match
+--------------
+ {bar,beque}
+(1 row)
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ In the common case where you just want the whole matching substring
+ or <code class="literal">NULL</code> for no match, the best solution is to
+ use <code class="function">regexp_substr()</code>.
+ However, <code class="function">regexp_substr()</code> only exists
+ in <span class="productname">PostgreSQL</span> version 15 and up. When
+ working in older versions, you can extract the first element
+ of <code class="function">regexp_match()</code>'s result, for example:
+</p><pre class="programlisting">
+SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1];
+ regexp_match
+--------------
+ barbeque
+(1 row)
+</pre><p>
+ </p></div><p>
+ The <code class="function">regexp_matches</code> function returns a set of text arrays
+ of matching substring(s) within matches of a POSIX regular
+ expression pattern to a string. It has the same syntax as
+ <code class="function">regexp_match</code>.
+ This function returns no rows if there is no match, one row if there is
+ a match and the <code class="literal">g</code> flag is not given, or <em class="replaceable"><code>N</code></em>
+ rows if there are <em class="replaceable"><code>N</code></em> matches and the <code class="literal">g</code> flag
+ is given. Each returned row is a text array containing the whole
+ matched substring or the substrings matching parenthesized
+ subexpressions of the <em class="replaceable"><code>pattern</code></em>, just as described above
+ for <code class="function">regexp_match</code>.
+ <code class="function">regexp_matches</code> accepts all the flags shown
+ in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>, plus
+ the <code class="literal">g</code> flag which commands it to return all matches, not
+ just the first one.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+SELECT regexp_matches('foo', 'not there');
+ regexp_matches
+----------------
+(0 rows)
+
+SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
+ regexp_matches
+----------------
+ {bar,beque}
+ {bazil,barf}
+(2 rows)
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ In most cases <code class="function">regexp_matches()</code> should be used with
+ the <code class="literal">g</code> flag, since if you only want the first match, it's
+ easier and more efficient to use <code class="function">regexp_match()</code>.
+ However, <code class="function">regexp_match()</code> only exists
+ in <span class="productname">PostgreSQL</span> version 10 and up. When working in older
+ versions, a common trick is to place a <code class="function">regexp_matches()</code>
+ call in a sub-select, for example:
+</p><pre class="programlisting">
+SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
+</pre><p>
+ This produces a text array if there's a match, or <code class="literal">NULL</code> if
+ not, the same as <code class="function">regexp_match()</code> would do. Without the
+ sub-select, this query would produce no output at all for table rows
+ without a match, which is typically not the desired behavior.
+ </p></div><p>
+ The <code class="function">regexp_replace</code> function provides substitution of
+ new text for substrings that match POSIX regular expression patterns.
+ It has the syntax
+ <code class="function">regexp_replace</code>(<em class="replaceable"><code>source</code></em>,
+ <em class="replaceable"><code>pattern</code></em>, <em class="replaceable"><code>replacement</code></em>
+ [<span class="optional">, <em class="replaceable"><code>start</code></em>
+ [<span class="optional">, <em class="replaceable"><code>N</code></em>
+ </span>]</span>]
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em> </span>]).
+ (Notice that <em class="replaceable"><code>N</code></em> cannot be specified
+ unless <em class="replaceable"><code>start</code></em> is,
+ but <em class="replaceable"><code>flags</code></em> can be given in any case.)
+ The <em class="replaceable"><code>source</code></em> string is returned unchanged if
+ there is no match to the <em class="replaceable"><code>pattern</code></em>. If there is a
+ match, the <em class="replaceable"><code>source</code></em> string is returned with the
+ <em class="replaceable"><code>replacement</code></em> string substituted for the matching
+ substring. The <em class="replaceable"><code>replacement</code></em> string can contain
+ <code class="literal">\</code><em class="replaceable"><code>n</code></em>, where <em class="replaceable"><code>n</code></em> is 1
+ through 9, to indicate that the source substring matching the
+ <em class="replaceable"><code>n</code></em>'th parenthesized subexpression of the pattern should be
+ inserted, and it can contain <code class="literal">\&amp;</code> to indicate that the
+ substring matching the entire pattern should be inserted. Write
+ <code class="literal">\\</code> if you need to put a literal backslash in the replacement
+ text.
+ <em class="replaceable"><code>pattern</code></em> is searched for
+ in <em class="replaceable"><code>string</code></em>, normally from the beginning of
+ the string, but if the <em class="replaceable"><code>start</code></em> parameter is
+ provided then beginning from that character index.
+ By default, only the first match of the pattern is replaced.
+ If <em class="replaceable"><code>N</code></em> is specified and is greater than zero,
+ then the <em class="replaceable"><code>N</code></em>'th match of the pattern
+ is replaced.
+ If the <code class="literal">g</code> flag is given, or
+ if <em class="replaceable"><code>N</code></em> is specified and is zero, then all
+ matches at or after the <em class="replaceable"><code>start</code></em> position are
+ replaced. (The <code class="literal">g</code> flag is ignored
+ when <em class="replaceable"><code>N</code></em> is specified.)
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags (though
+ not <code class="literal">g</code>) are
+ described in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+regexp_replace('foobarbaz', 'b..', 'X')
+ <em class="lineannotation"><span class="lineannotation">fooXbaz</span></em>
+regexp_replace('foobarbaz', 'b..', 'X', 'g')
+ <em class="lineannotation"><span class="lineannotation">fooXX</span></em>
+regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g')
+ <em class="lineannotation"><span class="lineannotation">fooXarYXazY</span></em>
+regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i')
+ <em class="lineannotation"><span class="lineannotation">X PXstgrXSQL fXnctXXn</span></em>
+regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 3, 'i')
+ <em class="lineannotation"><span class="lineannotation">A PostgrXSQL function</span></em>
+</pre><p>
+ </p><p>
+ The <code class="function">regexp_split_to_table</code> function splits a string using a POSIX
+ regular expression pattern as a delimiter. It has the syntax
+ <code class="function">regexp_split_to_table</code>(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em> </span>]).
+ If there is no match to the <em class="replaceable"><code>pattern</code></em>, the function returns the
+ <em class="replaceable"><code>string</code></em>. If there is at least one match, for each match it returns
+ the text from the end of the last match (or the beginning of the string)
+ to the beginning of the match. When there are no more matches, it
+ returns the text from the end of the last match to the end of the string.
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text string containing
+ zero or more single-letter flags that change the function's behavior.
+ <code class="function">regexp_split_to_table</code> supports the flags described in
+ <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ </p><p>
+ The <code class="function">regexp_split_to_array</code> function behaves the same as
+ <code class="function">regexp_split_to_table</code>, except that <code class="function">regexp_split_to_array</code>
+ returns its result as an array of <code class="type">text</code>. It has the syntax
+ <code class="function">regexp_split_to_array</code>(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em> </span>]).
+ The parameters are the same as for <code class="function">regexp_split_to_table</code>.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+SELECT foo FROM regexp_split_to_table('the quick brown fox jumps over the lazy dog', '\s+') AS foo;
+ foo
+-------
+ the
+ quick
+ brown
+ fox
+ jumps
+ over
+ the
+ lazy
+ dog
+(9 rows)
+
+SELECT regexp_split_to_array('the quick brown fox jumps over the lazy dog', '\s+');
+ regexp_split_to_array
+-----------------------------------------------
+ {the,quick,brown,fox,jumps,over,the,lazy,dog}
+(1 row)
+
+SELECT foo FROM regexp_split_to_table('the quick brown fox', '\s*') AS foo;
+ foo
+-----
+ t
+ h
+ e
+ q
+ u
+ i
+ c
+ k
+ b
+ r
+ o
+ w
+ n
+ f
+ o
+ x
+(16 rows)
+</pre><p>
+ </p><p>
+ As the last example demonstrates, the regexp split functions ignore
+ zero-length matches that occur at the start or end of the string
+ or immediately after a previous match. This is contrary to the strict
+ definition of regexp matching that is implemented by
+ the other regexp functions, but is usually the most convenient behavior
+ in practice. Other software systems such as Perl use similar definitions.
+ </p><p>
+ The <code class="function">regexp_substr</code> function returns the substring
+ that matches a POSIX regular expression pattern,
+ or <code class="literal">NULL</code> if there is no match. It has the syntax
+ <code class="function">regexp_substr</code>(<em class="replaceable"><code>string</code></em>,
+ <em class="replaceable"><code>pattern</code></em>
+ [<span class="optional">, <em class="replaceable"><code>start</code></em>
+ [<span class="optional">, <em class="replaceable"><code>N</code></em>
+ [<span class="optional">, <em class="replaceable"><code>flags</code></em>
+ [<span class="optional">, <em class="replaceable"><code>subexpr</code></em>
+ </span>]</span>]</span>]</span>]).
+ <em class="replaceable"><code>pattern</code></em> is searched for
+ in <em class="replaceable"><code>string</code></em>, normally from the beginning of
+ the string, but if the <em class="replaceable"><code>start</code></em> parameter is
+ provided then beginning from that character index.
+ If <em class="replaceable"><code>N</code></em> is specified
+ then the <em class="replaceable"><code>N</code></em>'th match of the pattern
+ is returned, otherwise the first match is returned.
+ The <em class="replaceable"><code>flags</code></em> parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ For a pattern containing parenthesized
+ subexpressions, <em class="replaceable"><code>subexpr</code></em> is an integer
+ indicating which subexpression is of interest: the result is the
+ substring matching that subexpression.
+ Subexpressions are numbered in the order of their leading parentheses.
+ When <em class="replaceable"><code>subexpr</code></em> is omitted or zero, the result
+ is the whole match regardless of parenthesized subexpressions.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+regexp_substr('number of your street, town zip, FR', '[^,]+', 1, 2)
+ <em class="lineannotation"><span class="lineannotation"> town zip</span></em>
+regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
+ <em class="lineannotation"><span class="lineannotation">FGH</span></em>
+</pre><p>
+ </p><div class="sect3" id="POSIX-SYNTAX-DETAILS"><div class="titlepage"><div><div><h4 class="title">9.7.3.1. Regular Expression Details</h4></div></div></div><p>
+ <span class="productname">PostgreSQL</span>'s regular expressions are implemented
+ using a software package written by Henry Spencer. Much of
+ the description of regular expressions below is copied verbatim from his
+ manual.
+ </p><p>
+ Regular expressions (<acronym class="acronym">RE</acronym>s), as defined in
+ <acronym class="acronym">POSIX</acronym> 1003.2, come in two forms:
+ <em class="firstterm">extended</em> <acronym class="acronym">RE</acronym>s or <acronym class="acronym">ERE</acronym>s
+ (roughly those of <code class="command">egrep</code>), and
+ <em class="firstterm">basic</em> <acronym class="acronym">RE</acronym>s or <acronym class="acronym">BRE</acronym>s
+ (roughly those of <code class="command">ed</code>).
+ <span class="productname">PostgreSQL</span> supports both forms, and
+ also implements some extensions
+ that are not in the POSIX standard, but have become widely used
+ due to their availability in programming languages such as Perl and Tcl.
+ <acronym class="acronym">RE</acronym>s using these non-POSIX extensions are called
+ <em class="firstterm">advanced</em> <acronym class="acronym">RE</acronym>s or <acronym class="acronym">ARE</acronym>s
+ in this documentation. AREs are almost an exact superset of EREs,
+ but BREs have several notational incompatibilities (as well as being
+ much more limited).
+ We first describe the ARE and ERE forms, noting features that apply
+ only to AREs, and then describe how BREs differ.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> 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 <em class="firstterm">embedded option</em>
+ to the RE pattern, as described in <a class="xref" href="functions-matching.html#POSIX-METASYNTAX" title="9.7.3.4. Regular Expression Metasyntax">Section 9.7.3.4</a>.
+ This can be useful for compatibility with applications that expect
+ exactly the <acronym class="acronym">POSIX</acronym> 1003.2 rules.
+ </p></div><p>
+ A regular expression is defined as one or more
+ <em class="firstterm">branches</em>, separated by
+ <code class="literal">|</code>. It matches anything that matches one of the
+ branches.
+ </p><p>
+ A branch is zero or more <em class="firstterm">quantified atoms</em> or
+ <em class="firstterm">constraints</em>, concatenated.
+ It matches a match for the first, followed by a match for the second, etc.;
+ an empty branch matches the empty string.
+ </p><p>
+ A quantified atom is an <em class="firstterm">atom</em> possibly followed
+ by a single <em class="firstterm">quantifier</em>.
+ Without a quantifier, it matches a match for the atom.
+ With a quantifier, it can match some number of matches of the atom.
+ An <em class="firstterm">atom</em> can be any of the possibilities
+ shown in <a class="xref" href="functions-matching.html#POSIX-ATOMS-TABLE" title="Table 9.17. Regular Expression Atoms">Table 9.17</a>.
+ The possible quantifiers and their meanings are shown in
+ <a class="xref" href="functions-matching.html#POSIX-QUANTIFIERS-TABLE" title="Table 9.18. Regular Expression Quantifiers">Table 9.18</a>.
+ </p><p>
+ A <em class="firstterm">constraint</em> matches an empty string, but matches only when
+ 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
+ <a class="xref" href="functions-matching.html#POSIX-CONSTRAINTS-TABLE" title="Table 9.19. Regular Expression Constraints">Table 9.19</a>;
+ some more constraints are described later.
+ </p><div class="table" id="POSIX-ATOMS-TABLE"><p class="title"><strong>Table 9.17. Regular Expression Atoms</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Atoms" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Atom</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">(</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> (where <em class="replaceable"><code>re</code></em> is any regular expression)
+ matches a match for
+ <em class="replaceable"><code>re</code></em>, with the match noted for possible reporting </td></tr><tr><td> <code class="literal">(?:</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> as above, but the match is not noted for reporting
+ (a <span class="quote">“<span class="quote">non-capturing</span>”</span> set of parentheses)
+ (AREs only) </td></tr><tr><td> <code class="literal">.</code> </td><td> matches any single character </td></tr><tr><td> <code class="literal">[</code><em class="replaceable"><code>chars</code></em><code class="literal">]</code> </td><td> a <em class="firstterm">bracket expression</em>,
+ matching any one of the <em class="replaceable"><code>chars</code></em> (see
+ <a class="xref" href="functions-matching.html#POSIX-BRACKET-EXPRESSIONS" title="9.7.3.2. Bracket Expressions">Section 9.7.3.2</a> for more detail) </td></tr><tr><td> <code class="literal">\</code><em class="replaceable"><code>k</code></em> </td><td> (where <em class="replaceable"><code>k</code></em> is a non-alphanumeric character)
+ matches that character taken as an ordinary character,
+ e.g., <code class="literal">\\</code> matches a backslash character </td></tr><tr><td> <code class="literal">\</code><em class="replaceable"><code>c</code></em> </td><td> where <em class="replaceable"><code>c</code></em> is alphanumeric
+ (possibly followed by other characters)
+ is an <em class="firstterm">escape</em>, see <a class="xref" href="functions-matching.html#POSIX-ESCAPE-SEQUENCES" title="9.7.3.3. Regular Expression Escapes">Section 9.7.3.3</a>
+ (AREs only; in EREs and BREs, this matches <em class="replaceable"><code>c</code></em>) </td></tr><tr><td> <code class="literal">{</code> </td><td> when followed by a character other than a digit,
+ matches the left-brace character <code class="literal">{</code>;
+ when followed by a digit, it is the beginning of a
+ <em class="replaceable"><code>bound</code></em> (see below) </td></tr><tr><td> <em class="replaceable"><code>x</code></em> </td><td> where <em class="replaceable"><code>x</code></em> is a single character with no other
+ significance, matches that character </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ An RE cannot end with a backslash (<code class="literal">\</code>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If you have <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> turned off,
+ any backslashes you write in literal string constants will need to be
+ doubled. See <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> for more information.
+ </p></div><div class="table" id="POSIX-QUANTIFIERS-TABLE"><p class="title"><strong>Table 9.18. Regular Expression Quantifiers</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Quantifiers" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Quantifier</th><th>Matches</th></tr></thead><tbody><tr><td> <code class="literal">*</code> </td><td> a sequence of 0 or more matches of the atom </td></tr><tr><td> <code class="literal">+</code> </td><td> a sequence of 1 or more matches of the atom </td></tr><tr><td> <code class="literal">?</code> </td><td> a sequence of 0 or 1 matches of the atom </td></tr><tr><td> <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}</code> </td><td> a sequence of exactly <em class="replaceable"><code>m</code></em> matches of the atom </td></tr><tr><td> <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,}</code> </td><td> a sequence of <em class="replaceable"><code>m</code></em> or more matches of the atom </td></tr><tr><td>
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}</code> </td><td> a sequence of <em class="replaceable"><code>m</code></em> through <em class="replaceable"><code>n</code></em>
+ (inclusive) matches of the atom; <em class="replaceable"><code>m</code></em> cannot exceed
+ <em class="replaceable"><code>n</code></em> </td></tr><tr><td> <code class="literal">*?</code> </td><td> non-greedy version of <code class="literal">*</code> </td></tr><tr><td> <code class="literal">+?</code> </td><td> non-greedy version of <code class="literal">+</code> </td></tr><tr><td> <code class="literal">??</code> </td><td> non-greedy version of <code class="literal">?</code> </td></tr><tr><td> <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}?</code> </td><td> non-greedy version of <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}</code> </td></tr><tr><td> <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,}?</code> </td><td> non-greedy version of <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,}</code> </td></tr><tr><td>
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}?</code> </td><td> non-greedy version of <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}</code> </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The forms using <code class="literal">{</code><em class="replaceable"><code>...</code></em><code class="literal">}</code>
+ are known as <em class="firstterm">bounds</em>.
+ The numbers <em class="replaceable"><code>m</code></em> and <em class="replaceable"><code>n</code></em> within a bound are
+ unsigned decimal integers with permissible values from 0 to 255 inclusive.
+ </p><p>
+ <em class="firstterm">Non-greedy</em> quantifiers (available in AREs only) match the
+ same possibilities as their corresponding normal (<em class="firstterm">greedy</em>)
+ counterparts, but prefer the smallest number rather than the largest
+ number of matches.
+ See <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a> for more detail.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A quantifier cannot immediately follow another quantifier, e.g.,
+ <code class="literal">**</code> is invalid.
+ A quantifier cannot
+ begin an expression or subexpression or follow
+ <code class="literal">^</code> or <code class="literal">|</code>.
+ </p></div><div class="table" id="POSIX-CONSTRAINTS-TABLE"><p class="title"><strong>Table 9.19. Regular Expression Constraints</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Constraints" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Constraint</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">^</code> </td><td> matches at the beginning of the string </td></tr><tr><td> <code class="literal">$</code> </td><td> matches at the end of the string </td></tr><tr><td> <code class="literal">(?=</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> <em class="firstterm">positive lookahead</em> matches at any point
+ where a substring matching <em class="replaceable"><code>re</code></em> begins
+ (AREs only) </td></tr><tr><td> <code class="literal">(?!</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> <em class="firstterm">negative lookahead</em> matches at any point
+ where no substring matching <em class="replaceable"><code>re</code></em> begins
+ (AREs only) </td></tr><tr><td> <code class="literal">(?&lt;=</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> <em class="firstterm">positive lookbehind</em> matches at any point
+ where a substring matching <em class="replaceable"><code>re</code></em> ends
+ (AREs only) </td></tr><tr><td> <code class="literal">(?&lt;!</code><em class="replaceable"><code>re</code></em><code class="literal">)</code> </td><td> <em class="firstterm">negative lookbehind</em> matches at any point
+ where no substring matching <em class="replaceable"><code>re</code></em> ends
+ (AREs only) </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Lookahead and lookbehind constraints cannot contain <em class="firstterm">back
+ references</em> (see <a class="xref" href="functions-matching.html#POSIX-ESCAPE-SEQUENCES" title="9.7.3.3. Regular Expression Escapes">Section 9.7.3.3</a>),
+ and all parentheses within them are considered non-capturing.
+ </p></div><div class="sect3" id="POSIX-BRACKET-EXPRESSIONS"><div class="titlepage"><div><div><h4 class="title">9.7.3.2. Bracket Expressions</h4></div></div></div><p>
+ A <em class="firstterm">bracket expression</em> is a list of
+ characters enclosed in <code class="literal">[]</code>. It normally matches
+ any single character from the list (but see below). If the list
+ begins with <code class="literal">^</code>, it matches any single character
+ <span class="emphasis"><em>not</em></span> from the rest of the list.
+ If two characters
+ in the list are separated by <code class="literal">-</code>, this is
+ shorthand for the full range of characters between those two
+ (inclusive) in the collating sequence,
+ e.g., <code class="literal">[0-9]</code> in <acronym class="acronym">ASCII</acronym> matches
+ any decimal digit. It is illegal for two ranges to share an
+ endpoint, e.g., <code class="literal">a-c-e</code>. Ranges are very
+ collating-sequence-dependent, so portable programs should avoid
+ relying on them.
+ </p><p>
+ To include a literal <code class="literal">]</code> in the list, make it the
+ first character (after <code class="literal">^</code>, if that is used). To
+ include a literal <code class="literal">-</code>, make it the first or last
+ character, or the second endpoint of a range. To use a literal
+ <code class="literal">-</code> as the first endpoint of a range, enclose it
+ in <code class="literal">[.</code> and <code class="literal">.]</code> to make it a
+ collating element (see below). With the exception of these characters,
+ some combinations using <code class="literal">[</code>
+ (see next paragraphs), and escapes (AREs only), all other special
+ characters lose their special significance within a bracket expression.
+ In particular, <code class="literal">\</code> is not special when following
+ ERE or BRE rules, though it is special (as introducing an escape)
+ in AREs.
+ </p><p>
+ Within a bracket expression, a collating element (a character, a
+ multiple-character sequence that collates as if it were a single
+ character, or a collating-sequence name for either) enclosed in
+ <code class="literal">[.</code> and <code class="literal">.]</code> stands for the
+ sequence of characters of that collating element. The sequence is
+ treated as a single element of the bracket expression's list. This
+ allows a bracket
+ expression containing a multiple-character collating element to
+ match more than one character, e.g., if the collating sequence
+ includes a <code class="literal">ch</code> collating element, then the RE
+ <code class="literal">[[.ch.]]*c</code> matches the first five characters of
+ <code class="literal">chchcc</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> currently does not support multi-character collating
+ elements. This information describes possible future behavior.
+ </p></div><p>
+ Within a bracket expression, a collating element enclosed in
+ <code class="literal">[=</code> and <code class="literal">=]</code> is an <em class="firstterm">equivalence
+ class</em>, standing for the sequences of characters of all collating
+ elements equivalent to that one, including itself. (If there are
+ no other equivalent collating elements, the treatment is as if the
+ enclosing delimiters were <code class="literal">[.</code> and
+ <code class="literal">.]</code>.) For example, if <code class="literal">o</code> and
+ <code class="literal">^</code> are the members of an equivalence class, then
+ <code class="literal">[[=o=]]</code>, <code class="literal">[[=^=]]</code>, and
+ <code class="literal">[o^]</code> are all synonymous. An equivalence class
+ cannot be an endpoint of a range.
+ </p><p>
+ Within a bracket expression, the name of a character class
+ enclosed in <code class="literal">[:</code> and <code class="literal">:]</code> stands
+ for the list of all characters belonging to that class. A character
+ class cannot be used as an endpoint of a range.
+ The <acronym class="acronym">POSIX</acronym> standard defines these character class
+ names:
+ <code class="literal">alnum</code> (letters and numeric digits),
+ <code class="literal">alpha</code> (letters),
+ <code class="literal">blank</code> (space and tab),
+ <code class="literal">cntrl</code> (control characters),
+ <code class="literal">digit</code> (numeric digits),
+ <code class="literal">graph</code> (printable characters except space),
+ <code class="literal">lower</code> (lower-case letters),
+ <code class="literal">print</code> (printable characters including space),
+ <code class="literal">punct</code> (punctuation),
+ <code class="literal">space</code> (any white space),
+ <code class="literal">upper</code> (upper-case letters),
+ and <code class="literal">xdigit</code> (hexadecimal digits).
+ The behavior of these standard character classes is generally
+ consistent across platforms for characters in the 7-bit ASCII set.
+ Whether a given non-ASCII character is considered to belong to one
+ of these classes depends on the <em class="firstterm">collation</em>
+ that is used for the regular-expression function or operator
+ (see <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>), or by default on the
+ database's <code class="envar">LC_CTYPE</code> locale setting (see
+ <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>). The classification of non-ASCII
+ characters can vary across platforms even in similarly-named
+ locales. (But the <code class="literal">C</code> locale never considers any
+ non-ASCII characters to belong to any of these classes.)
+ In addition to these standard character
+ classes, <span class="productname">PostgreSQL</span> defines
+ the <code class="literal">word</code> character class, which is the same as
+ <code class="literal">alnum</code> plus the underscore (<code class="literal">_</code>)
+ character, and
+ the <code class="literal">ascii</code> character class, which contains exactly
+ the 7-bit ASCII set.
+ </p><p>
+ There are two special cases of bracket expressions: the bracket
+ expressions <code class="literal">[[:&lt;:]]</code> and
+ <code class="literal">[[:&gt;:]]</code> are constraints,
+ matching empty strings at the beginning
+ and end of a word respectively. A word is defined as a sequence
+ of word characters that is neither preceded nor followed by word
+ characters. A word character is any character belonging to the
+ <code class="literal">word</code> character class, that is, any letter, digit,
+ or underscore. This is an extension, compatible with but not
+ specified by <acronym class="acronym">POSIX</acronym> 1003.2, and should be used with
+ caution in software intended to be portable to other systems.
+ The constraint escapes described below are usually preferable; they
+ are no more standard, but are easier to type.
+ </p></div><div class="sect3" id="POSIX-ESCAPE-SEQUENCES"><div class="titlepage"><div><div><h4 class="title">9.7.3.3. Regular Expression Escapes</h4></div></div></div><p>
+ <em class="firstterm">Escapes</em> are special sequences beginning with <code class="literal">\</code>
+ followed by an alphanumeric character. Escapes come in several varieties:
+ character entry, class shorthands, constraint escapes, and back references.
+ A <code class="literal">\</code> followed by an alphanumeric character but not constituting
+ a valid escape is illegal in AREs.
+ In EREs, there are no escapes: outside a bracket expression,
+ a <code class="literal">\</code> followed by an alphanumeric character merely stands for
+ that character as an ordinary character, and inside a bracket expression,
+ <code class="literal">\</code> is an ordinary character.
+ (The latter is the one actual incompatibility between EREs and AREs.)
+ </p><p>
+ <em class="firstterm">Character-entry escapes</em> exist to make it easier to specify
+ non-printing and other inconvenient characters in REs. They are
+ shown in <a class="xref" href="functions-matching.html#POSIX-CHARACTER-ENTRY-ESCAPES-TABLE" title="Table 9.20. Regular Expression Character-Entry Escapes">Table 9.20</a>.
+ </p><p>
+ <em class="firstterm">Class-shorthand escapes</em> provide shorthands for certain
+ commonly-used character classes. They are
+ shown in <a class="xref" href="functions-matching.html#POSIX-CLASS-SHORTHAND-ESCAPES-TABLE" title="Table 9.21. Regular Expression Class-Shorthand Escapes">Table 9.21</a>.
+ </p><p>
+ A <em class="firstterm">constraint escape</em> is a constraint,
+ matching the empty string if specific conditions are met,
+ written as an escape. They are
+ shown in <a class="xref" href="functions-matching.html#POSIX-CONSTRAINT-ESCAPES-TABLE" title="Table 9.22. Regular Expression Constraint Escapes">Table 9.22</a>.
+ </p><p>
+ A <em class="firstterm">back reference</em> (<code class="literal">\</code><em class="replaceable"><code>n</code></em>) matches the
+ same string matched by the previous parenthesized subexpression specified
+ by the number <em class="replaceable"><code>n</code></em>
+ (see <a class="xref" href="functions-matching.html#POSIX-CONSTRAINT-BACKREF-TABLE" title="Table 9.23. Regular Expression Back References">Table 9.23</a>). For example,
+ <code class="literal">([bc])\1</code> matches <code class="literal">bb</code> or <code class="literal">cc</code>
+ but not <code class="literal">bc</code> or <code class="literal">cb</code>.
+ The subexpression must entirely precede the back reference in the RE.
+ Subexpressions are numbered in the order of their leading parentheses.
+ Non-capturing parentheses do not define subexpressions.
+ The back reference considers only the string characters matched by the
+ referenced subexpression, not any constraints contained in it. For
+ example, <code class="literal">(^\d)\1</code> will match <code class="literal">22</code>.
+ </p><div class="table" id="POSIX-CHARACTER-ENTRY-ESCAPES-TABLE"><p class="title"><strong>Table 9.20. Regular Expression Character-Entry Escapes</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Character-Entry Escapes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Escape</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">\a</code> </td><td> alert (bell) character, as in C </td></tr><tr><td> <code class="literal">\b</code> </td><td> backspace, as in C </td></tr><tr><td> <code class="literal">\B</code> </td><td> synonym for backslash (<code class="literal">\</code>) to help reduce the need for backslash
+ doubling </td></tr><tr><td> <code class="literal">\c</code><em class="replaceable"><code>X</code></em> </td><td> (where <em class="replaceable"><code>X</code></em> is any character) the character whose
+ low-order 5 bits are the same as those of
+ <em class="replaceable"><code>X</code></em>, and whose other bits are all zero </td></tr><tr><td> <code class="literal">\e</code> </td><td> the character whose collating-sequence name
+ is <code class="literal">ESC</code>,
+ or failing that, the character with octal value <code class="literal">033</code> </td></tr><tr><td> <code class="literal">\f</code> </td><td> form feed, as in C </td></tr><tr><td> <code class="literal">\n</code> </td><td> newline, as in C </td></tr><tr><td> <code class="literal">\r</code> </td><td> carriage return, as in C </td></tr><tr><td> <code class="literal">\t</code> </td><td> horizontal tab, as in C </td></tr><tr><td> <code class="literal">\u</code><em class="replaceable"><code>wxyz</code></em> </td><td> (where <em class="replaceable"><code>wxyz</code></em> is exactly four hexadecimal digits)
+ the character whose hexadecimal value is
+ <code class="literal">0x</code><em class="replaceable"><code>wxyz</code></em>
+ </td></tr><tr><td> <code class="literal">\U</code><em class="replaceable"><code>stuvwxyz</code></em> </td><td> (where <em class="replaceable"><code>stuvwxyz</code></em> is exactly eight hexadecimal
+ digits)
+ the character whose hexadecimal value is
+ <code class="literal">0x</code><em class="replaceable"><code>stuvwxyz</code></em>
+ </td></tr><tr><td> <code class="literal">\v</code> </td><td> vertical tab, as in C </td></tr><tr><td> <code class="literal">\x</code><em class="replaceable"><code>hhh</code></em> </td><td> (where <em class="replaceable"><code>hhh</code></em> is any sequence of hexadecimal
+ digits)
+ the character whose hexadecimal value is
+ <code class="literal">0x</code><em class="replaceable"><code>hhh</code></em>
+ (a single character no matter how many hexadecimal digits are used)
+ </td></tr><tr><td> <code class="literal">\0</code> </td><td> the character whose value is <code class="literal">0</code> (the null byte)</td></tr><tr><td> <code class="literal">\</code><em class="replaceable"><code>xy</code></em> </td><td> (where <em class="replaceable"><code>xy</code></em> is exactly two octal digits,
+ and is not a <em class="firstterm">back reference</em>)
+ the character whose octal value is
+ <code class="literal">0</code><em class="replaceable"><code>xy</code></em> </td></tr><tr><td> <code class="literal">\</code><em class="replaceable"><code>xyz</code></em> </td><td> (where <em class="replaceable"><code>xyz</code></em> is exactly three octal digits,
+ and is not a <em class="firstterm">back reference</em>)
+ the character whose octal value is
+ <code class="literal">0</code><em class="replaceable"><code>xyz</code></em> </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Hexadecimal digits are <code class="literal">0</code>-<code class="literal">9</code>,
+ <code class="literal">a</code>-<code class="literal">f</code>, and <code class="literal">A</code>-<code class="literal">F</code>.
+ Octal digits are <code class="literal">0</code>-<code class="literal">7</code>.
+ </p><p>
+ Numeric character-entry escapes specifying values outside the ASCII range
+ (0–127) have meanings dependent on the database encoding. When the
+ encoding is UTF-8, escape values are equivalent to Unicode code points,
+ for example <code class="literal">\u1234</code> means the character <code class="literal">U+1234</code>.
+ For other multibyte encodings, character-entry escapes usually just
+ specify the concatenation of the byte values for the character. If the
+ escape value does not correspond to any legal character in the database
+ encoding, no error will be raised, but it will never match any data.
+ </p><p>
+ The character-entry escapes are always taken as ordinary characters.
+ For example, <code class="literal">\135</code> is <code class="literal">]</code> in ASCII, but
+ <code class="literal">\135</code> does not terminate a bracket expression.
+ </p><div class="table" id="POSIX-CLASS-SHORTHAND-ESCAPES-TABLE"><p class="title"><strong>Table 9.21. Regular Expression Class-Shorthand Escapes</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Class-Shorthand Escapes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Escape</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">\d</code> </td><td> matches any digit, like
+ <code class="literal">[[:digit:]]</code> </td></tr><tr><td> <code class="literal">\s</code> </td><td> matches any whitespace character, like
+ <code class="literal">[[:space:]]</code> </td></tr><tr><td> <code class="literal">\w</code> </td><td> matches any word character, like
+ <code class="literal">[[:word:]]</code> </td></tr><tr><td> <code class="literal">\D</code> </td><td> matches any non-digit, like
+ <code class="literal">[^[:digit:]]</code> </td></tr><tr><td> <code class="literal">\S</code> </td><td> matches any non-whitespace character, like
+ <code class="literal">[^[:space:]]</code> </td></tr><tr><td> <code class="literal">\W</code> </td><td> matches any non-word character, like
+ <code class="literal">[^[:word:]]</code> </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The class-shorthand escapes also work within bracket expressions,
+ although the definitions shown above are not quite syntactically
+ valid in that context.
+ For example, <code class="literal">[a-c\d]</code> is equivalent to
+ <code class="literal">[a-c[:digit:]]</code>.
+ </p><div class="table" id="POSIX-CONSTRAINT-ESCAPES-TABLE"><p class="title"><strong>Table 9.22. Regular Expression Constraint Escapes</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Constraint Escapes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Escape</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">\A</code> </td><td> matches only at the beginning of the string
+ (see <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a> for how this differs from
+ <code class="literal">^</code>) </td></tr><tr><td> <code class="literal">\m</code> </td><td> matches only at the beginning of a word </td></tr><tr><td> <code class="literal">\M</code> </td><td> matches only at the end of a word </td></tr><tr><td> <code class="literal">\y</code> </td><td> matches only at the beginning or end of a word </td></tr><tr><td> <code class="literal">\Y</code> </td><td> matches only at a point that is not the beginning or end of a
+ word </td></tr><tr><td> <code class="literal">\Z</code> </td><td> matches only at the end of the string
+ (see <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a> for how this differs from
+ <code class="literal">$</code>) </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ A word is defined as in the specification of
+ <code class="literal">[[:&lt;:]]</code> and <code class="literal">[[:&gt;:]]</code> above.
+ Constraint escapes are illegal within bracket expressions.
+ </p><div class="table" id="POSIX-CONSTRAINT-BACKREF-TABLE"><p class="title"><strong>Table 9.23. Regular Expression Back References</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Back References" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Escape</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">\</code><em class="replaceable"><code>m</code></em> </td><td> (where <em class="replaceable"><code>m</code></em> is a nonzero digit)
+ a back reference to the <em class="replaceable"><code>m</code></em>'th subexpression </td></tr><tr><td> <code class="literal">\</code><em class="replaceable"><code>mnn</code></em> </td><td> (where <em class="replaceable"><code>m</code></em> is a nonzero digit, and
+ <em class="replaceable"><code>nn</code></em> is some more digits, and the decimal value
+ <em class="replaceable"><code>mnn</code></em> is not greater than the number of closing capturing
+ parentheses seen so far)
+ a back reference to the <em class="replaceable"><code>mnn</code></em>'th subexpression </td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ There is an inherent ambiguity between octal character-entry
+ escapes and back references, which is resolved by the following heuristics,
+ as hinted at above.
+ A leading zero always indicates an octal escape.
+ A single non-zero digit, not followed by another digit,
+ is always taken as a back reference.
+ A multi-digit sequence not starting with a zero is taken as a back
+ reference if it comes after a suitable subexpression
+ (i.e., the number is in the legal range for a back reference),
+ and otherwise is taken as octal.
+ </p></div></div><div class="sect3" id="POSIX-METASYNTAX"><div class="titlepage"><div><div><h4 class="title">9.7.3.4. Regular Expression Metasyntax</h4></div></div></div><p>
+ In addition to the main syntax described above, there are some special
+ forms and miscellaneous syntactic facilities available.
+ </p><p>
+ An RE can begin with one of two special <em class="firstterm">director</em> prefixes.
+ If an RE begins with <code class="literal">***:</code>,
+ the rest of the RE is taken as an ARE. (This normally has no effect in
+ <span class="productname">PostgreSQL</span>, since REs are assumed to be AREs;
+ but it does have an effect if ERE or BRE mode had been specified by
+ the <em class="replaceable"><code>flags</code></em> parameter to a regex function.)
+ If an RE begins with <code class="literal">***=</code>,
+ the rest of the RE is taken to be a literal string,
+ with all characters considered ordinary characters.
+ </p><p>
+ An ARE can begin with <em class="firstterm">embedded options</em>:
+ a sequence <code class="literal">(?</code><em class="replaceable"><code>xyz</code></em><code class="literal">)</code>
+ (where <em class="replaceable"><code>xyz</code></em> is one or more alphabetic characters)
+ specifies options affecting the rest of the RE.
+ These options override any previously determined options —
+ in particular, they can override the case-sensitivity behavior implied by
+ a regex operator, or the <em class="replaceable"><code>flags</code></em> parameter to a regex
+ function.
+ The available option letters are
+ shown in <a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>.
+ Note that these same option letters are used in the <em class="replaceable"><code>flags</code></em>
+ parameters of regex functions.
+ </p><div class="table" id="POSIX-EMBEDDED-OPTIONS-TABLE"><p class="title"><strong>Table 9.24. ARE Embedded-Option Letters</strong></p><div class="table-contents"><table class="table" summary="ARE Embedded-Option Letters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">b</code> </td><td> rest of RE is a BRE </td></tr><tr><td> <code class="literal">c</code> </td><td> case-sensitive matching (overrides operator type) </td></tr><tr><td> <code class="literal">e</code> </td><td> rest of RE is an ERE </td></tr><tr><td> <code class="literal">i</code> </td><td> case-insensitive matching (see
+ <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a>) (overrides operator type) </td></tr><tr><td> <code class="literal">m</code> </td><td> historical synonym for <code class="literal">n</code> </td></tr><tr><td> <code class="literal">n</code> </td><td> newline-sensitive matching (see
+ <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a>) </td></tr><tr><td> <code class="literal">p</code> </td><td> partial newline-sensitive matching (see
+ <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a>) </td></tr><tr><td> <code class="literal">q</code> </td><td> rest of RE is a literal (<span class="quote">“<span class="quote">quoted</span>”</span>) string, all ordinary
+ characters </td></tr><tr><td> <code class="literal">s</code> </td><td> non-newline-sensitive matching (default) </td></tr><tr><td> <code class="literal">t</code> </td><td> tight syntax (default; see below) </td></tr><tr><td> <code class="literal">w</code> </td><td> inverse partial newline-sensitive (<span class="quote">“<span class="quote">weird</span>”</span>) matching
+ (see <a class="xref" href="functions-matching.html#POSIX-MATCHING-RULES" title="9.7.3.5. Regular Expression Matching Rules">Section 9.7.3.5</a>) </td></tr><tr><td> <code class="literal">x</code> </td><td> expanded syntax (see below) </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Embedded options take effect at the <code class="literal">)</code> terminating the sequence.
+ They can appear only at the start of an ARE (after the
+ <code class="literal">***:</code> director if any).
+ </p><p>
+ In addition to the usual (<em class="firstterm">tight</em>) RE syntax, in which all
+ characters are significant, there is an <em class="firstterm">expanded</em> syntax,
+ available by specifying the embedded <code class="literal">x</code> option.
+ In the expanded syntax,
+ white-space characters in the RE are ignored, as are
+ all characters between a <code class="literal">#</code>
+ and the following newline (or the end of the RE). This
+ permits paragraphing and commenting a complex RE.
+ There are three exceptions to that basic rule:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ a white-space character or <code class="literal">#</code> preceded by <code class="literal">\</code> is
+ retained
+ </p></li><li class="listitem"><p>
+ white space or <code class="literal">#</code> within a bracket expression is retained
+ </p></li><li class="listitem"><p>
+ white space and comments cannot appear within multi-character symbols,
+ such as <code class="literal">(?:</code>
+ </p></li></ul></div><p>
+
+ For this purpose, white-space characters are blank, tab, newline, and
+ any character that belongs to the <em class="replaceable"><code>space</code></em> character class.
+ </p><p>
+ Finally, in an ARE, outside bracket expressions, the sequence
+ <code class="literal">(?#</code><em class="replaceable"><code>ttt</code></em><code class="literal">)</code>
+ (where <em class="replaceable"><code>ttt</code></em> is any text not containing a <code class="literal">)</code>)
+ is a comment, completely ignored.
+ Again, this is not allowed between the characters of
+ multi-character symbols, like <code class="literal">(?:</code>.
+ Such comments are more a historical artifact than a useful facility,
+ and their use is deprecated; use the expanded syntax instead.
+ </p><p>
+ <span class="emphasis"><em>None</em></span> of these metasyntax extensions is available if
+ an initial <code class="literal">***=</code> director
+ has specified that the user's input be treated as a literal string
+ rather than as an RE.
+ </p></div><div class="sect3" id="POSIX-MATCHING-RULES"><div class="titlepage"><div><div><h4 class="title">9.7.3.5. Regular Expression Matching Rules</h4></div></div></div><p>
+ In the event that an RE could match more than one substring of a given
+ string, the RE matches the one starting earliest in the string.
+ If the RE could match more than one substring starting at that point,
+ either the longest possible match or the shortest possible match will
+ be taken, depending on whether the RE is <em class="firstterm">greedy</em> or
+ <em class="firstterm">non-greedy</em>.
+ </p><p>
+ Whether an RE is greedy or not is determined by the following rules:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Most atoms, and all constraints, have no greediness attribute (because
+ they cannot match variable amounts of text anyway).
+ </p></li><li class="listitem"><p>
+ Adding parentheses around an RE does not change its greediness.
+ </p></li><li class="listitem"><p>
+ A quantified atom with a fixed-repetition quantifier
+ (<code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}</code>
+ or
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">}?</code>)
+ has the same greediness (possibly none) as the atom itself.
+ </p></li><li class="listitem"><p>
+ A quantified atom with other normal quantifiers (including
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}</code>
+ with <em class="replaceable"><code>m</code></em> equal to <em class="replaceable"><code>n</code></em>)
+ is greedy (prefers longest match).
+ </p></li><li class="listitem"><p>
+ A quantified atom with a non-greedy quantifier (including
+ <code class="literal">{</code><em class="replaceable"><code>m</code></em><code class="literal">,</code><em class="replaceable"><code>n</code></em><code class="literal">}?</code>
+ with <em class="replaceable"><code>m</code></em> equal to <em class="replaceable"><code>n</code></em>)
+ is non-greedy (prefers shortest match).
+ </p></li><li class="listitem"><p>
+ A branch — that is, an RE that has no top-level
+ <code class="literal">|</code> operator — has the same greediness as the first
+ quantified atom in it that has a greediness attribute.
+ </p></li><li class="listitem"><p>
+ An RE consisting of two or more branches connected by the
+ <code class="literal">|</code> operator is always greedy.
+ </p></li></ul></div><p>
+ </p><p>
+ The above rules associate greediness attributes not only with individual
+ quantified atoms, but with branches and entire REs that contain quantified
+ atoms. What that means is that the matching is done in such a way that
+ the branch, or whole RE, matches the longest or shortest possible
+ substring <span class="emphasis"><em>as a whole</em></span>. Once the length of the entire match
+ is determined, the part of it that matches any particular subexpression
+ is determined on the basis of the greediness attribute of that
+ subexpression, with subexpressions starting earlier in the RE taking
+ priority over ones starting later.
+ </p><p>
+ An example of what this means:
+</p><pre class="screen">
+SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">123</code>
+SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
+</pre><p>
+ In the first case, the RE as a whole is greedy because <code class="literal">Y*</code>
+ is greedy. It can match beginning at the <code class="literal">Y</code>, and it matches
+ the longest possible string starting there, i.e., <code class="literal">Y123</code>.
+ The output is the parenthesized part of that, or <code class="literal">123</code>.
+ In the second case, the RE as a whole is non-greedy because <code class="literal">Y*?</code>
+ is non-greedy. It can match beginning at the <code class="literal">Y</code>, and it matches
+ the shortest possible string starting there, i.e., <code class="literal">Y1</code>.
+ The subexpression <code class="literal">[0-9]{1,3}</code> is greedy but it cannot change
+ the decision as to the overall match length; so it is forced to match
+ just <code class="literal">1</code>.
+ </p><p>
+ In short, when an RE contains both greedy and non-greedy subexpressions,
+ the total match length is either as long as possible or as short as
+ possible, according to the attribute assigned to the whole RE. The
+ attributes assigned to the subexpressions only affect how much of that
+ match they are allowed to <span class="quote">“<span class="quote">eat</span>”</span> relative to each other.
+ </p><p>
+ The quantifiers <code class="literal">{1,1}</code> and <code class="literal">{1,1}?</code>
+ can be used to force greediness or non-greediness, respectively,
+ on a subexpression or a whole RE.
+ This is useful when you need the whole RE to have a greediness attribute
+ different from what's deduced from its elements. As an example,
+ suppose that we are trying to separate a string containing some digits
+ into the digits and the parts before and after them. We might try to
+ do that like this:
+</p><pre class="screen">
+SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">{abc0123,4,xyz}</code>
+</pre><p>
+ That didn't work: the first <code class="literal">.*</code> is greedy so
+ it <span class="quote">“<span class="quote">eats</span>”</span> as much as it can, leaving the <code class="literal">\d+</code> to
+ match at the last possible place, the last digit. We might try to fix
+ that by making it non-greedy:
+</p><pre class="screen">
+SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">{abc,0,""}</code>
+</pre><p>
+ That didn't work either, because now the RE as a whole is non-greedy
+ and so it ends the overall match as soon as possible. We can get what
+ we want by forcing the RE as a whole to be greedy:
+</p><pre class="screen">
+SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">{abc,01234,xyz}</code>
+</pre><p>
+ Controlling the RE's overall greediness separately from its components'
+ greediness allows great flexibility in handling variable-length patterns.
+ </p><p>
+ When deciding what is a longer or shorter match,
+ match lengths are measured in characters, not collating elements.
+ An empty string is considered longer than no match at all.
+ For example:
+ <code class="literal">bb*</code>
+ matches the three middle characters of <code class="literal">abbbc</code>;
+ <code class="literal">(week|wee)(night|knights)</code>
+ matches all ten characters of <code class="literal">weeknights</code>;
+ when <code class="literal">(.*).*</code>
+ is matched against <code class="literal">abc</code> the parenthesized subexpression
+ matches all three characters; and when
+ <code class="literal">(a*)*</code> is matched against <code class="literal">bc</code>
+ both the whole RE and the parenthesized
+ subexpression match an empty string.
+ </p><p>
+ If case-independent matching is specified,
+ the effect is much as if all case distinctions had vanished from the
+ alphabet.
+ When an alphabetic that exists in multiple cases appears as an
+ ordinary character outside a bracket expression, it is effectively
+ transformed into a bracket expression containing both cases,
+ e.g., <code class="literal">x</code> becomes <code class="literal">[xX]</code>.
+ When it appears inside a bracket expression, all case counterparts
+ of it are added to the bracket expression, e.g.,
+ <code class="literal">[x]</code> becomes <code class="literal">[xX]</code>
+ and <code class="literal">[^x]</code> becomes <code class="literal">[^xX]</code>.
+ </p><p>
+ If newline-sensitive matching is specified, <code class="literal">.</code>
+ and bracket expressions using <code class="literal">^</code>
+ will never match the newline character
+ (so that matches will not cross lines unless the RE
+ explicitly includes a newline)
+ and <code class="literal">^</code> and <code class="literal">$</code>
+ will match the empty string after and before a newline
+ respectively, in addition to matching at beginning and end of string
+ respectively.
+ But the ARE escapes <code class="literal">\A</code> and <code class="literal">\Z</code>
+ continue to match beginning or end of string <span class="emphasis"><em>only</em></span>.
+ Also, the character class shorthands <code class="literal">\D</code>
+ and <code class="literal">\W</code> will match a newline regardless of this mode.
+ (Before <span class="productname">PostgreSQL</span> 14, they did not match
+ newlines when in newline-sensitive mode.
+ Write <code class="literal">[^[:digit:]]</code>
+ or <code class="literal">[^[:word:]]</code> to get the old behavior.)
+ </p><p>
+ If partial newline-sensitive matching is specified,
+ this affects <code class="literal">.</code> and bracket expressions
+ as with newline-sensitive matching, but not <code class="literal">^</code>
+ and <code class="literal">$</code>.
+ </p><p>
+ If inverse partial newline-sensitive matching is specified,
+ this affects <code class="literal">^</code> and <code class="literal">$</code>
+ as with newline-sensitive matching, but not <code class="literal">.</code>
+ and bracket expressions.
+ This isn't very useful but is provided for symmetry.
+ </p></div><div class="sect3" id="POSIX-LIMITS-COMPATIBILITY"><div class="titlepage"><div><div><h4 class="title">9.7.3.6. Limits and Compatibility</h4></div></div></div><p>
+ No particular limit is imposed on the length of REs in this
+ implementation. However,
+ programs intended to be highly portable should not employ REs longer
+ than 256 bytes,
+ as a POSIX-compliant implementation can refuse to accept such REs.
+ </p><p>
+ The only feature of AREs that is actually incompatible with
+ POSIX EREs is that <code class="literal">\</code> does not lose its special
+ significance inside bracket expressions.
+ All other ARE features use syntax which is illegal or has
+ undefined or unspecified effects in POSIX EREs;
+ the <code class="literal">***</code> syntax of directors likewise is outside the POSIX
+ syntax for both BREs and EREs.
+ </p><p>
+ Many of the ARE extensions are borrowed from Perl, but some have
+ been changed to clean them up, and a few Perl extensions are not present.
+ Incompatibilities of note include <code class="literal">\b</code>, <code class="literal">\B</code>,
+ the lack of special treatment for a trailing newline,
+ the addition of complemented bracket expressions to the things
+ affected by newline-sensitive matching,
+ the restrictions on parentheses and back references in lookahead/lookbehind
+ constraints, and the longest/shortest-match (rather than first-match)
+ matching semantics.
+ </p></div><div class="sect3" id="POSIX-BASIC-REGEXES"><div class="titlepage"><div><div><h4 class="title">9.7.3.7. Basic Regular Expressions</h4></div></div></div><p>
+ BREs differ from EREs in several respects.
+ In BREs, <code class="literal">|</code>, <code class="literal">+</code>, and <code class="literal">?</code>
+ are ordinary characters and there is no equivalent
+ for their functionality.
+ The delimiters for bounds are
+ <code class="literal">\{</code> and <code class="literal">\}</code>,
+ with <code class="literal">{</code> and <code class="literal">}</code>
+ by themselves ordinary characters.
+ The parentheses for nested subexpressions are
+ <code class="literal">\(</code> and <code class="literal">\)</code>,
+ with <code class="literal">(</code> and <code class="literal">)</code> by themselves ordinary characters.
+ <code class="literal">^</code> is an ordinary character except at the beginning of the
+ RE or the beginning of a parenthesized subexpression,
+ <code class="literal">$</code> is an ordinary character except at the end of the
+ RE or the end of a parenthesized subexpression,
+ and <code class="literal">*</code> is an ordinary character if it appears at the beginning
+ of the RE or the beginning of a parenthesized subexpression
+ (after a possible leading <code class="literal">^</code>).
+ Finally, single-digit back references are available, and
+ <code class="literal">\&lt;</code> and <code class="literal">\&gt;</code>
+ are synonyms for
+ <code class="literal">[[:&lt;:]]</code> and <code class="literal">[[:&gt;:]]</code>
+ respectively; no other escapes are available in BREs.
+ </p></div><div class="sect3" id="POSIX-VS-XQUERY"><div class="titlepage"><div><div><h4 class="title">9.7.3.8. Differences from SQL Standard and XQuery</h4></div></div></div><a id="id-1.5.8.13.9.48.2" class="indexterm"></a><a id="id-1.5.8.13.9.48.3" class="indexterm"></a><a id="id-1.5.8.13.9.48.4" class="indexterm"></a><a id="id-1.5.8.13.9.48.5" class="indexterm"></a><a id="id-1.5.8.13.9.48.6" class="indexterm"></a><a id="id-1.5.8.13.9.48.7" class="indexterm"></a><p>
+ Since SQL:2008, the SQL standard includes regular expression operators
+ and functions that performs pattern
+ matching according to the XQuery regular expression
+ standard:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">LIKE_REGEX</code></p></li><li class="listitem"><p><code class="literal">OCCURRENCES_REGEX</code></p></li><li class="listitem"><p><code class="literal">POSITION_REGEX</code></p></li><li class="listitem"><p><code class="literal">SUBSTRING_REGEX</code></p></li><li class="listitem"><p><code class="literal">TRANSLATE_REGEX</code></p></li></ul></div><p>
+ <span class="productname">PostgreSQL</span> does not currently implement these
+ operators and functions. You can get approximately equivalent
+ functionality in each case as shown in <a class="xref" href="functions-matching.html#FUNCTIONS-REGEXP-SQL-TABLE" title="Table 9.25. Regular Expression Functions Equivalencies">Table 9.25</a>. (Various optional clauses on
+ both sides have been omitted in this table.)
+ </p><div class="table" id="FUNCTIONS-REGEXP-SQL-TABLE"><p class="title"><strong>Table 9.25. Regular Expression Functions Equivalencies</strong></p><div class="table-contents"><table class="table" summary="Regular Expression Functions Equivalencies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>SQL standard</th><th>PostgreSQL</th></tr></thead><tbody><tr><td><code class="literal"><em class="replaceable"><code>string</code></em> LIKE_REGEX <em class="replaceable"><code>pattern</code></em></code></td><td><code class="literal">regexp_like(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>)</code> or <code class="literal"><em class="replaceable"><code>string</code></em> ~ <em class="replaceable"><code>pattern</code></em></code></td></tr><tr><td><code class="literal">OCCURRENCES_REGEX(<em class="replaceable"><code>pattern</code></em> IN <em class="replaceable"><code>string</code></em>)</code></td><td><code class="literal">regexp_count(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>)</code></td></tr><tr><td><code class="literal">POSITION_REGEX(<em class="replaceable"><code>pattern</code></em> IN <em class="replaceable"><code>string</code></em>)</code></td><td><code class="literal">regexp_instr(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>)</code></td></tr><tr><td><code class="literal">SUBSTRING_REGEX(<em class="replaceable"><code>pattern</code></em> IN <em class="replaceable"><code>string</code></em>)</code></td><td><code class="literal">regexp_substr(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>)</code></td></tr><tr><td><code class="literal">TRANSLATE_REGEX(<em class="replaceable"><code>pattern</code></em> IN <em class="replaceable"><code>string</code></em> WITH <em class="replaceable"><code>replacement</code></em>)</code></td><td><code class="literal">regexp_replace(<em class="replaceable"><code>string</code></em>, <em class="replaceable"><code>pattern</code></em>, <em class="replaceable"><code>replacement</code></em>)</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Regular expression functions similar to those provided by PostgreSQL are
+ also available in a number of other SQL implementations, whereas the
+ SQL-standard functions are not as widely implemented. Some of the
+ details of the regular expression syntax will likely differ in each
+ implementation.
+ </p><p>
+ The SQL-standard operators and functions use XQuery regular expressions,
+ which are quite close to the ARE syntax described above.
+ Notable differences between the existing POSIX-based
+ regular-expression feature and XQuery regular expressions include:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ XQuery character class subtraction is not supported. An example of
+ this feature is using the following to match only English
+ consonants: <code class="literal">[a-z-[aeiou]]</code>.
+ </p></li><li class="listitem"><p>
+ XQuery character class shorthands <code class="literal">\c</code>,
+ <code class="literal">\C</code>, <code class="literal">\i</code>,
+ and <code class="literal">\I</code> are not supported.
+ </p></li><li class="listitem"><p>
+ XQuery character class elements
+ using <code class="literal">\p{UnicodeProperty}</code> or the
+ inverse <code class="literal">\P{UnicodeProperty}</code> are not supported.
+ </p></li><li class="listitem"><p>
+ POSIX interprets character classes such as <code class="literal">\w</code>
+ (see <a class="xref" href="functions-matching.html#POSIX-CLASS-SHORTHAND-ESCAPES-TABLE" title="Table 9.21. Regular Expression Class-Shorthand Escapes">Table 9.21</a>)
+ according to the prevailing locale (which you can control by
+ attaching a <code class="literal">COLLATE</code> clause to the operator or
+ function). XQuery specifies these classes by reference to Unicode
+ character properties, so equivalent behavior is obtained only with
+ a locale that follows the Unicode rules.
+ </p></li><li class="listitem"><p>
+ The SQL standard (not XQuery itself) attempts to cater for more
+ variants of <span class="quote">“<span class="quote">newline</span>”</span> than POSIX does. The
+ newline-sensitive matching options described above consider only
+ ASCII NL (<code class="literal">\n</code>) to be a newline, but SQL would have
+ us treat CR (<code class="literal">\r</code>), CRLF (<code class="literal">\r\n</code>)
+ (a Windows-style newline), and some Unicode-only characters like
+ LINE SEPARATOR (U+2028) as newlines as well.
+ Notably, <code class="literal">.</code> and <code class="literal">\s</code> should
+ count <code class="literal">\r\n</code> as one character not two according to
+ SQL.
+ </p></li><li class="listitem"><p>
+ Of the character-entry escapes described in
+ <a class="xref" href="functions-matching.html#POSIX-CHARACTER-ENTRY-ESCAPES-TABLE" title="Table 9.20. Regular Expression Character-Entry Escapes">Table 9.20</a>,
+ XQuery supports only <code class="literal">\n</code>, <code class="literal">\r</code>,
+ and <code class="literal">\t</code>.
+ </p></li><li class="listitem"><p>
+ XQuery does not support
+ the <code class="literal">[:<em class="replaceable"><code>name</code></em>:]</code> syntax
+ for character classes within bracket expressions.
+ </p></li><li class="listitem"><p>
+ XQuery does not have lookahead or lookbehind constraints,
+ nor any of the constraint escapes described in
+ <a class="xref" href="functions-matching.html#POSIX-CONSTRAINT-ESCAPES-TABLE" title="Table 9.22. Regular Expression Constraint Escapes">Table 9.22</a>.
+ </p></li><li class="listitem"><p>
+ The metasyntax forms described in <a class="xref" href="functions-matching.html#POSIX-METASYNTAX" title="9.7.3.4. Regular Expression Metasyntax">Section 9.7.3.4</a>
+ do not exist in XQuery.
+ </p></li><li class="listitem"><p>
+ The regular expression flag letters defined by XQuery are
+ related to but not the same as the option letters for POSIX
+ (<a class="xref" href="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE" title="Table 9.24. ARE Embedded-Option Letters">Table 9.24</a>). While the
+ <code class="literal">i</code> and <code class="literal">q</code> options behave the
+ same, others do not:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ XQuery's <code class="literal">s</code> (allow dot to match newline)
+ and <code class="literal">m</code> (allow <code class="literal">^</code>
+ and <code class="literal">$</code> to match at newlines) flags provide
+ access to the same behaviors as
+ POSIX's <code class="literal">n</code>, <code class="literal">p</code>
+ and <code class="literal">w</code> flags, but they
+ do <span class="emphasis"><em>not</em></span> match the behavior of
+ POSIX's <code class="literal">s</code> and <code class="literal">m</code> flags.
+ Note in particular that dot-matches-newline is the default
+ behavior in POSIX but not XQuery.
+ </p></li><li class="listitem"><p>
+ XQuery's <code class="literal">x</code> (ignore whitespace in pattern) flag
+ is noticeably different from POSIX's expanded-mode flag.
+ POSIX's <code class="literal">x</code> flag also
+ allows <code class="literal">#</code> to begin a comment in the pattern,
+ and POSIX will not ignore a whitespace character after a
+ backslash.
+ </p></li></ul></div><p>
+ </p></li></ul></div><p>
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.6. Bit String Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.8. Data Type Formatting Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-math.html b/doc/src/sgml/html/functions-math.html
new file mode 100644
index 0000000..c748a0d
--- /dev/null
+++ b/doc/src/sgml/html/functions-math.html
@@ -0,0 +1,1001 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.3. Mathematical Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-comparison.html" title="9.2. Comparison Functions and Operators" /><link rel="next" href="functions-string.html" title="9.4. String Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.3. Mathematical Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-string.html" title="9.4. String Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-MATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.3. Mathematical Functions and Operators</h2></div></div></div><p>
+ Mathematical operators are provided for many
+ <span class="productname">PostgreSQL</span> types. For types without
+ standard mathematical conventions
+ (e.g., date/time types) we
+ describe the actual behavior in subsequent sections.
+ </p><p>
+ <a class="xref" href="functions-math.html#FUNCTIONS-MATH-OP-TABLE" title="Table 9.4. Mathematical Operators">Table 9.4</a> shows the mathematical
+ operators that are available for the standard numeric types.
+ Unless otherwise noted, operators shown as
+ accepting <em class="replaceable"><code>numeric_type</code></em> are available for all
+ the types <code class="type">smallint</code>, <code class="type">integer</code>,
+ <code class="type">bigint</code>, <code class="type">numeric</code>, <code class="type">real</code>,
+ and <code class="type">double precision</code>.
+ Operators shown as accepting <em class="replaceable"><code>integral_type</code></em>
+ are available for the types <code class="type">smallint</code>, <code class="type">integer</code>,
+ and <code class="type">bigint</code>.
+ Except where noted, each form of an operator returns the same data type
+ as its argument(s). Calls involving multiple argument data types, such
+ as <code class="type">integer</code> <code class="literal">+</code> <code class="type">numeric</code>,
+ are resolved by using the type appearing later in these lists.
+ </p><div class="table" id="FUNCTIONS-MATH-OP-TABLE"><p class="title"><strong>Table 9.4. Mathematical Operators</strong></p><div class="table-contents"><table class="table" summary="Mathematical Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>numeric_type</code></em> <code class="literal">+</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Addition
+ </p>
+ <p>
+ <code class="literal">2 + 3</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">+</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Unary plus (no operation)
+ </p>
+ <p>
+ <code class="literal">+ 3.5</code>
+ → <code class="returnvalue">3.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>numeric_type</code></em> <code class="literal">-</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Subtraction
+ </p>
+ <p>
+ <code class="literal">2 - 3</code>
+ → <code class="returnvalue">-1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">-</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Negation
+ </p>
+ <p>
+ <code class="literal">- (-4)</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>numeric_type</code></em> <code class="literal">*</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Multiplication
+ </p>
+ <p>
+ <code class="literal">2 * 3</code>
+ → <code class="returnvalue">6</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>numeric_type</code></em> <code class="literal">/</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Division (for integral types, division truncates the result towards
+ zero)
+ </p>
+ <p>
+ <code class="literal">5.0 / 2</code>
+ → <code class="returnvalue">2.5000000000000000</code>
+ </p>
+ <p>
+ <code class="literal">5 / 2</code>
+ → <code class="returnvalue">2</code>
+ </p>
+ <p>
+ <code class="literal">(-5) / 2</code>
+ → <code class="returnvalue">-2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>numeric_type</code></em> <code class="literal">%</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Modulo (remainder); available for <code class="type">smallint</code>,
+ <code class="type">integer</code>, <code class="type">bigint</code>, and <code class="type">numeric</code>
+ </p>
+ <p>
+ <code class="literal">5 % 4</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">numeric</code> <code class="literal">^</code> <code class="type">numeric</code>
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">double precision</code> <code class="literal">^</code> <code class="type">double precision</code>
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Exponentiation
+ </p>
+ <p>
+ <code class="literal">2 ^ 3</code>
+ → <code class="returnvalue">8</code>
+ </p>
+ <p>
+ Unlike typical mathematical practice, multiple uses of
+ <code class="literal">^</code> will associate left to right by default:
+ </p>
+ <p>
+ <code class="literal">2 ^ 3 ^ 3</code>
+ → <code class="returnvalue">512</code>
+ </p>
+ <p>
+ <code class="literal">2 ^ (3 ^ 3)</code>
+ → <code class="returnvalue">134217728</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">|/</code> <code class="type">double precision</code>
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Square root
+ </p>
+ <p>
+ <code class="literal">|/ 25.0</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">||/</code> <code class="type">double precision</code>
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cube root
+ </p>
+ <p>
+ <code class="literal">||/ 64.0</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">@</code> <em class="replaceable"><code>numeric_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Absolute value
+ </p>
+ <p>
+ <code class="literal">@ -5.0</code>
+ → <code class="returnvalue">5.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integral_type</code></em> <code class="literal">&amp;</code> <em class="replaceable"><code>integral_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise AND
+ </p>
+ <p>
+ <code class="literal">91 &amp; 15</code>
+ → <code class="returnvalue">11</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integral_type</code></em> <code class="literal">|</code> <em class="replaceable"><code>integral_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise OR
+ </p>
+ <p>
+ <code class="literal">32 | 3</code>
+ → <code class="returnvalue">35</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integral_type</code></em> <code class="literal">#</code> <em class="replaceable"><code>integral_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise exclusive OR
+ </p>
+ <p>
+ <code class="literal">17 # 5</code>
+ → <code class="returnvalue">20</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">~</code> <em class="replaceable"><code>integral_type</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise NOT
+ </p>
+ <p>
+ <code class="literal">~1</code>
+ → <code class="returnvalue">-2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integral_type</code></em> <code class="literal">&lt;&lt;</code> <code class="type">integer</code>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise shift left
+ </p>
+ <p>
+ <code class="literal">1 &lt;&lt; 4</code>
+ → <code class="returnvalue">16</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integral_type</code></em> <code class="literal">&gt;&gt;</code> <code class="type">integer</code>
+ → <code class="returnvalue"><em class="replaceable"><code>integral_type</code></em></code>
+ </p>
+ <p>
+ Bitwise shift right
+ </p>
+ <p>
+ <code class="literal">8 &gt;&gt; 2</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-math.html#FUNCTIONS-MATH-FUNC-TABLE" title="Table 9.5. Mathematical Functions">Table 9.5</a> shows the available
+ mathematical functions.
+ Many of these functions are provided in multiple forms with different
+ argument types.
+ Except where noted, any given form of a function returns the same
+ data type as its argument(s); cross-type cases are resolved in the
+ same way as explained above for operators.
+ The functions working with <code class="type">double precision</code> data are mostly
+ implemented on top of the host system's C library; accuracy and behavior in
+ boundary cases can therefore vary depending on the host system.
+ </p><div class="table" id="FUNCTIONS-MATH-FUNC-TABLE"><p class="title"><strong>Table 9.5. Mathematical Functions</strong></p><div class="table-contents"><table class="table" summary="Mathematical Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">abs</code> ( <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Absolute value
+ </p>
+ <p>
+ <code class="literal">abs(-17.4)</code>
+ → <code class="returnvalue">17.4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">cbrt</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cube root
+ </p>
+ <p>
+ <code class="literal">cbrt(64.0)</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">ceil</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">ceil</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Nearest integer greater than or equal to argument
+ </p>
+ <p>
+ <code class="literal">ceil(42.2)</code>
+ → <code class="returnvalue">43</code>
+ </p>
+ <p>
+ <code class="literal">ceil(-42.8)</code>
+ → <code class="returnvalue">-42</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">ceiling</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">ceiling</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Nearest integer greater than or equal to argument (same
+ as <code class="function">ceil</code>)
+ </p>
+ <p>
+ <code class="literal">ceiling(95.3)</code>
+ → <code class="returnvalue">96</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">degrees</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Converts radians to degrees
+ </p>
+ <p>
+ <code class="literal">degrees(0.5)</code>
+ → <code class="returnvalue">28.64788975654116</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">div</code> ( <em class="parameter"><code>y</code></em> <code class="type">numeric</code>,
+ <em class="parameter"><code>x</code></em> <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Integer quotient of <em class="parameter"><code>y</code></em>/<em class="parameter"><code>x</code></em>
+ (truncates towards zero)
+ </p>
+ <p>
+ <code class="literal">div(9, 4)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">exp</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">exp</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Exponential (<code class="literal">e</code> raised to the given power)
+ </p>
+ <p>
+ <code class="literal">exp(1.0)</code>
+ → <code class="returnvalue">2.7182818284590452</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="FUNCTION-FACTORIAL" class="indexterm"></a>
+ <code class="function">factorial</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Factorial
+ </p>
+ <p>
+ <code class="literal">factorial(5)</code>
+ → <code class="returnvalue">120</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">floor</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">floor</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Nearest integer less than or equal to argument
+ </p>
+ <p>
+ <code class="literal">floor(42.8)</code>
+ → <code class="returnvalue">42</code>
+ </p>
+ <p>
+ <code class="literal">floor(-42.8)</code>
+ → <code class="returnvalue">-43</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">gcd</code> ( <em class="replaceable"><code>numeric_type</code></em>, <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Greatest common divisor (the largest positive number that divides both
+ inputs with no remainder); returns <code class="literal">0</code> if both inputs
+ are zero; available for <code class="type">integer</code>, <code class="type">bigint</code>,
+ and <code class="type">numeric</code>
+ </p>
+ <p>
+ <code class="literal">gcd(1071, 462)</code>
+ → <code class="returnvalue">21</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">lcm</code> ( <em class="replaceable"><code>numeric_type</code></em>, <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Least common multiple (the smallest strictly positive number that is
+ an integral multiple of both inputs); returns <code class="literal">0</code> if
+ either input is zero; available for <code class="type">integer</code>,
+ <code class="type">bigint</code>, and <code class="type">numeric</code>
+ </p>
+ <p>
+ <code class="literal">lcm(1071, 462)</code>
+ → <code class="returnvalue">23562</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">ln</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">ln</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Natural logarithm
+ </p>
+ <p>
+ <code class="literal">ln(2.0)</code>
+ → <code class="returnvalue">0.6931471805599453</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">log</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">log</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Base 10 logarithm
+ </p>
+ <p>
+ <code class="literal">log(100)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">log10</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">log10</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Base 10 logarithm (same as <code class="function">log</code>)
+ </p>
+ <p>
+ <code class="literal">log10(1000)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">log</code> ( <em class="parameter"><code>b</code></em> <code class="type">numeric</code>,
+ <em class="parameter"><code>x</code></em> <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Logarithm of <em class="parameter"><code>x</code></em> to base <em class="parameter"><code>b</code></em>
+ </p>
+ <p>
+ <code class="literal">log(2.0, 64.0)</code>
+ → <code class="returnvalue">6.0000000000000000</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">min_scale</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Minimum scale (number of fractional decimal digits) needed
+ to represent the supplied value precisely
+ </p>
+ <p>
+ <code class="literal">min_scale(8.4100)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">mod</code> ( <em class="parameter"><code>y</code></em> <em class="replaceable"><code>numeric_type</code></em>,
+ <em class="parameter"><code>x</code></em> <em class="replaceable"><code>numeric_type</code></em> )
+ → <code class="returnvalue"><em class="replaceable"><code>numeric_type</code></em></code>
+ </p>
+ <p>
+ Remainder of <em class="parameter"><code>y</code></em>/<em class="parameter"><code>x</code></em>;
+ available for <code class="type">smallint</code>, <code class="type">integer</code>,
+ <code class="type">bigint</code>, and <code class="type">numeric</code>
+ </p>
+ <p>
+ <code class="literal">mod(9, 4)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">pi</code> ( )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Approximate value of <span class="symbol_font">π</span>
+ </p>
+ <p>
+ <code class="literal">pi()</code>
+ → <code class="returnvalue">3.141592653589793</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">power</code> ( <em class="parameter"><code>a</code></em> <code class="type">numeric</code>,
+ <em class="parameter"><code>b</code></em> <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">power</code> ( <em class="parameter"><code>a</code></em> <code class="type">double precision</code>,
+ <em class="parameter"><code>b</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ <em class="parameter"><code>a</code></em> raised to the power of <em class="parameter"><code>b</code></em>
+ </p>
+ <p>
+ <code class="literal">power(9, 3)</code>
+ → <code class="returnvalue">729</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.20.1.1.1" class="indexterm"></a>
+ <code class="function">radians</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Converts degrees to radians
+ </p>
+ <p>
+ <code class="literal">radians(45.0)</code>
+ → <code class="returnvalue">0.7853981633974483</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">round</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">round</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Rounds to nearest integer. For <code class="type">numeric</code>, ties are
+ broken by rounding away from zero. For <code class="type">double precision</code>,
+ the tie-breaking behavior is platform dependent, but
+ <span class="quote">“<span class="quote">round to nearest even</span>”</span> is the most common rule.
+ </p>
+ <p>
+ <code class="literal">round(42.4)</code>
+ → <code class="returnvalue">42</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">round</code> ( <em class="parameter"><code>v</code></em> <code class="type">numeric</code>, <em class="parameter"><code>s</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Rounds <em class="parameter"><code>v</code></em> to <em class="parameter"><code>s</code></em> decimal
+ places. Ties are broken by rounding away from zero.
+ </p>
+ <p>
+ <code class="literal">round(42.4382, 2)</code>
+ → <code class="returnvalue">42.44</code>
+ </p>
+ <p>
+ <code class="literal">round(1234.56, -1)</code>
+ → <code class="returnvalue">1230</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">scale</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Scale of the argument (the number of decimal digits in the fractional part)
+ </p>
+ <p>
+ <code class="literal">scale(8.4100)</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.24.1.1.1" class="indexterm"></a>
+ <code class="function">sign</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sign</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Sign of the argument (-1, 0, or +1)
+ </p>
+ <p>
+ <code class="literal">sign(-8.4)</code>
+ → <code class="returnvalue">-1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">sqrt</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">sqrt</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Square root
+ </p>
+ <p>
+ <code class="literal">sqrt(2)</code>
+ → <code class="returnvalue">1.4142135623730951</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.26.1.1.1" class="indexterm"></a>
+ <code class="function">trim_scale</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Reduces the value's scale (number of fractional decimal digits) by
+ removing trailing zeroes
+ </p>
+ <p>
+ <code class="literal">trim_scale(8.4100)</code>
+ → <code class="returnvalue">8.41</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.27.1.1.1" class="indexterm"></a>
+ <code class="function">trunc</code> ( <code class="type">numeric</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">trunc</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Truncates to integer (towards zero)
+ </p>
+ <p>
+ <code class="literal">trunc(42.8)</code>
+ → <code class="returnvalue">42</code>
+ </p>
+ <p>
+ <code class="literal">trunc(-42.8)</code>
+ → <code class="returnvalue">-42</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">trunc</code> ( <em class="parameter"><code>v</code></em> <code class="type">numeric</code>, <em class="parameter"><code>s</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">numeric</code>
+ </p>
+ <p>
+ Truncates <em class="parameter"><code>v</code></em> to <em class="parameter"><code>s</code></em>
+ decimal places
+ </p>
+ <p>
+ <code class="literal">trunc(42.4382, 2)</code>
+ → <code class="returnvalue">42.43</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.6.2.2.29.1.1.1" class="indexterm"></a>
+ <code class="function">width_bucket</code> ( <em class="parameter"><code>operand</code></em> <code class="type">numeric</code>, <em class="parameter"><code>low</code></em> <code class="type">numeric</code>, <em class="parameter"><code>high</code></em> <code class="type">numeric</code>, <em class="parameter"><code>count</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">width_bucket</code> ( <em class="parameter"><code>operand</code></em> <code class="type">double precision</code>, <em class="parameter"><code>low</code></em> <code class="type">double precision</code>, <em class="parameter"><code>high</code></em> <code class="type">double precision</code>, <em class="parameter"><code>count</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of the bucket in
+ which <em class="parameter"><code>operand</code></em> falls in a histogram
+ having <em class="parameter"><code>count</code></em> equal-width buckets spanning the
+ range <em class="parameter"><code>low</code></em> to <em class="parameter"><code>high</code></em>.
+ Returns <code class="literal">0</code>
+ or <code class="literal"><em class="parameter"><code>count</code></em>+1</code> for an input
+ outside that range.
+ </p>
+ <p>
+ <code class="literal">width_bucket(5.35, 0.024, 10.06, 5)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">width_bucket</code> ( <em class="parameter"><code>operand</code></em> <code class="type">anycompatible</code>, <em class="parameter"><code>thresholds</code></em> <code class="type">anycompatiblearray</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of the bucket in
+ which <em class="parameter"><code>operand</code></em> falls given an array listing the
+ lower bounds of the buckets. Returns <code class="literal">0</code> for an
+ input less than the first lower
+ bound. <em class="parameter"><code>operand</code></em> and the array elements can be
+ of any type having standard comparison operators.
+ The <em class="parameter"><code>thresholds</code></em> array <span class="emphasis"><em>must be
+ sorted</em></span>, smallest first, or unexpected results will be
+ obtained.
+ </p>
+ <p>
+ <code class="literal">width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <a class="xref" href="functions-math.html#FUNCTIONS-MATH-RANDOM-TABLE" title="Table 9.6. Random Functions">Table 9.6</a> shows functions for
+ generating random numbers.
+ </p><div class="table" id="FUNCTIONS-MATH-RANDOM-TABLE"><p class="title"><strong>Table 9.6. Random Functions</strong></p><div class="table-contents"><table class="table" summary="Random Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.8.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">random</code> ( )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Returns a random value in the range 0.0 &lt;= x &lt; 1.0
+ </p>
+ <p>
+ <code class="literal">random()</code>
+ → <code class="returnvalue">0.897124072839091</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.8.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">setseed</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Sets the seed for subsequent <code class="literal">random()</code> calls;
+ argument must be between -1.0 and 1.0, inclusive
+ </p>
+ <p>
+ <code class="literal">setseed(0.12345)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="function">random()</code> function uses a deterministic
+ pseudo-random number generator.
+ It is fast but not suitable for cryptographic
+ applications; see the <a class="xref" href="pgcrypto.html" title="F.28. pgcrypto">pgcrypto</a> module for a more
+ secure alternative.
+ If <code class="function">setseed()</code> is called, the series of results of
+ subsequent <code class="function">random()</code> calls in the current session
+ can be repeated by re-issuing <code class="function">setseed()</code> with the same
+ argument.
+ Without any prior <code class="function">setseed()</code> call in the same
+ session, the first <code class="function">random()</code> call obtains a seed
+ from a platform-dependent source of random bits.
+ </p><p>
+ <a class="xref" href="functions-math.html#FUNCTIONS-MATH-TRIG-TABLE" title="Table 9.7. Trigonometric Functions">Table 9.7</a> shows the
+ available trigonometric functions. Each of these functions comes in
+ two variants, one that measures angles in radians and one that
+ measures angles in degrees.
+ </p><div class="table" id="FUNCTIONS-MATH-TRIG-TABLE"><p class="title"><strong>Table 9.7. Trigonometric Functions</strong></p><div class="table-contents"><table class="table" summary="Trigonometric Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">acos</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse cosine, result in radians
+ </p>
+ <p>
+ <code class="literal">acos(1)</code>
+ → <code class="returnvalue">0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">acosd</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse cosine, result in degrees
+ </p>
+ <p>
+ <code class="literal">acosd(0.5)</code>
+ → <code class="returnvalue">60</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">asin</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse sine, result in radians
+ </p>
+ <p>
+ <code class="literal">asin(1)</code>
+ → <code class="returnvalue">1.5707963267948966</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">asind</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse sine, result in degrees
+ </p>
+ <p>
+ <code class="literal">asind(0.5)</code>
+ → <code class="returnvalue">30</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">atan</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse tangent, result in radians
+ </p>
+ <p>
+ <code class="literal">atan(1)</code>
+ → <code class="returnvalue">0.7853981633974483</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">atand</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse tangent, result in degrees
+ </p>
+ <p>
+ <code class="literal">atand(1)</code>
+ → <code class="returnvalue">45</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">atan2</code> ( <em class="parameter"><code>y</code></em> <code class="type">double precision</code>,
+ <em class="parameter"><code>x</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse tangent of
+ <em class="parameter"><code>y</code></em>/<em class="parameter"><code>x</code></em>,
+ result in radians
+ </p>
+ <p>
+ <code class="literal">atan2(1, 0)</code>
+ → <code class="returnvalue">1.5707963267948966</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">atan2d</code> ( <em class="parameter"><code>y</code></em> <code class="type">double precision</code>,
+ <em class="parameter"><code>x</code></em> <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse tangent of
+ <em class="parameter"><code>y</code></em>/<em class="parameter"><code>x</code></em>,
+ result in degrees
+ </p>
+ <p>
+ <code class="literal">atan2d(1, 0)</code>
+ → <code class="returnvalue">90</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">cos</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cosine, argument in radians
+ </p>
+ <p>
+ <code class="literal">cos(0)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">cosd</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cosine, argument in degrees
+ </p>
+ <p>
+ <code class="literal">cosd(60)</code>
+ → <code class="returnvalue">0.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">cot</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cotangent, argument in radians
+ </p>
+ <p>
+ <code class="literal">cot(0.5)</code>
+ → <code class="returnvalue">1.830487721712452</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">cotd</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Cotangent, argument in degrees
+ </p>
+ <p>
+ <code class="literal">cotd(45)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">sin</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Sine, argument in radians
+ </p>
+ <p>
+ <code class="literal">sin(1)</code>
+ → <code class="returnvalue">0.8414709848078965</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">sind</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Sine, argument in degrees
+ </p>
+ <p>
+ <code class="literal">sind(30)</code>
+ → <code class="returnvalue">0.5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">tan</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Tangent, argument in radians
+ </p>
+ <p>
+ <code class="literal">tan(1)</code>
+ → <code class="returnvalue">1.5574077246549023</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.11.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">tand</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Tangent, argument in degrees
+ </p>
+ <p>
+ <code class="literal">tand(45)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ Another way to work with angles measured in degrees is to use the unit
+ transformation functions <code class="literal"><code class="function">radians()</code></code>
+ and <code class="literal"><code class="function">degrees()</code></code> shown earlier.
+ However, using the degree-based trigonometric functions is preferred,
+ as that way avoids round-off error for special cases such
+ as <code class="literal">sind(30)</code>.
+ </p></div><p>
+ <a class="xref" href="functions-math.html#FUNCTIONS-MATH-HYP-TABLE" title="Table 9.8. Hyperbolic Functions">Table 9.8</a> shows the
+ available hyperbolic functions.
+ </p><div class="table" id="FUNCTIONS-MATH-HYP-TABLE"><p class="title"><strong>Table 9.8. Hyperbolic Functions</strong></p><div class="table-contents"><table class="table" summary="Hyperbolic Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">sinh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Hyperbolic sine
+ </p>
+ <p>
+ <code class="literal">sinh(1)</code>
+ → <code class="returnvalue">1.1752011936438014</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">cosh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Hyperbolic cosine
+ </p>
+ <p>
+ <code class="literal">cosh(0)</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">tanh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Hyperbolic tangent
+ </p>
+ <p>
+ <code class="literal">tanh(1)</code>
+ → <code class="returnvalue">0.7615941559557649</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">asinh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse hyperbolic sine
+ </p>
+ <p>
+ <code class="literal">asinh(1)</code>
+ → <code class="returnvalue">0.881373587019543</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">acosh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse hyperbolic cosine
+ </p>
+ <p>
+ <code class="literal">acosh(1)</code>
+ → <code class="returnvalue">0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.9.14.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">atanh</code> ( <code class="type">double precision</code> )
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Inverse hyperbolic tangent
+ </p>
+ <p>
+ <code class="literal">atanh(0.5)</code>
+ → <code class="returnvalue">0.5493061443340548</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-string.html" title="9.4. String Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.2. Comparison Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.4. String Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-net.html b/doc/src/sgml/html/functions-net.html
new file mode 100644
index 0000000..e26739b
--- /dev/null
+++ b/doc/src/sgml/html/functions-net.html
@@ -0,0 +1,397 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.12. Network Address Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-geometry.html" title="9.11. Geometric Functions and Operators" /><link rel="next" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.12. Network Address Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-NET"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.12. Network Address Functions and Operators</h2></div></div></div><p>
+ The IP network address types, <code class="type">cidr</code> and <code class="type">inet</code>,
+ support the usual comparison operators shown in
+ <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>
+ as well as the specialized operators and functions shown in
+ <a class="xref" href="functions-net.html#CIDR-INET-OPERATORS-TABLE" title="Table 9.39. IP Address Operators">Table 9.39</a> and
+ <a class="xref" href="functions-net.html#CIDR-INET-FUNCTIONS-TABLE" title="Table 9.40. IP Address Functions">Table 9.40</a>.
+ </p><p>
+ Any <code class="type">cidr</code> value can be cast to <code class="type">inet</code> implicitly;
+ therefore, the operators and functions shown below as operating on
+ <code class="type">inet</code> also work on <code class="type">cidr</code> values. (Where there are
+ separate functions for <code class="type">inet</code> and <code class="type">cidr</code>, it is
+ because the behavior should be different for the two cases.)
+ Also, it is permitted to cast an <code class="type">inet</code> value
+ to <code class="type">cidr</code>. When this is done, any bits to the right of the
+ netmask are silently zeroed to create a valid <code class="type">cidr</code> value.
+ </p><div class="table" id="CIDR-INET-OPERATORS-TABLE"><p class="title"><strong>Table 9.39. IP Address Operators</strong></p><div class="table-contents"><table class="table" summary="IP Address Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&lt;&lt;</code> <code class="type">inet</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is subnet strictly contained by subnet?
+ This operator, and the next four, test for subnet inclusion. They
+ consider only the network parts of the two addresses (ignoring any
+ bits to the right of the netmasks) and determine whether one network
+ is identical to or a subnet of the other.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">inet '192.168.0.5' &lt;&lt; inet '192.168.1/24'</code>
+ → <code class="returnvalue">f</code>
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &lt;&lt; inet '192.168.1/24'</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&lt;&lt;=</code> <code class="type">inet</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is subnet contained by or equal to subnet?
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&gt;&gt;</code> <code class="type">inet</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does subnet strictly contain subnet?
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&gt;&gt;=</code> <code class="type">inet</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does subnet contain or equal subnet?
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&amp;&amp;</code> <code class="type">inet</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does either subnet contain or equal the other?
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1/24' &amp;&amp; inet '192.168.2.0/28'</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">~</code> <code class="type">inet</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes bitwise NOT.
+ </p>
+ <p>
+ <code class="literal">~ inet '192.168.1.6'</code>
+ → <code class="returnvalue">63.87.254.249</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">&amp;</code> <code class="type">inet</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes bitwise AND.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.6' &amp; inet '0.0.0.255'</code>
+ → <code class="returnvalue">0.0.0.6</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">|</code> <code class="type">inet</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes bitwise OR.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.6' | inet '0.0.0.255'</code>
+ → <code class="returnvalue">192.168.1.255</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">+</code> <code class="type">bigint</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Adds an offset to an address.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.6' + 25</code>
+ → <code class="returnvalue">192.168.1.31</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">bigint</code> <code class="literal">+</code> <code class="type">inet</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Adds an offset to an address.
+ </p>
+ <p>
+ <code class="literal">200 + inet '::ffff:fff0:1'</code>
+ → <code class="returnvalue">::ffff:255.240.0.201</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">-</code> <code class="type">bigint</code>
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Subtracts an offset from an address.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.43' - 36</code>
+ → <code class="returnvalue">192.168.1.7</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">inet</code> <code class="literal">-</code> <code class="type">inet</code>
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Computes the difference of two addresses.
+ </p>
+ <p>
+ <code class="literal">inet '192.168.1.43' - inet '192.168.1.19'</code>
+ → <code class="returnvalue">24</code>
+ </p>
+ <p>
+ <code class="literal">inet '::1' - inet '::ffff:1'</code>
+ → <code class="returnvalue">-4294901760</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="CIDR-INET-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.40. IP Address Functions</strong></p><div class="table-contents"><table class="table" summary="IP Address Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">abbrev</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Creates an abbreviated display format as text.
+ (The result is the same as the <code class="type">inet</code> output function
+ produces; it is <span class="quote">“<span class="quote">abbreviated</span>”</span> only in comparison to the
+ result of an explicit cast to <code class="type">text</code>, which for historical
+ reasons will never suppress the netmask part.)
+ </p>
+ <p>
+ <code class="literal">abbrev(inet '10.1.0.0/32')</code>
+ → <code class="returnvalue">10.1.0.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">abbrev</code> ( <code class="type">cidr</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Creates an abbreviated display format as text.
+ (The abbreviation consists of dropping all-zero octets to the right
+ of the netmask; more examples are in
+ <a class="xref" href="datatype-net-types.html#DATATYPE-NET-CIDR-TABLE" title="Table 8.22. cidr Type Input Examples">Table 8.22</a>.)
+ </p>
+ <p>
+ <code class="literal">abbrev(cidr '10.1.0.0/16')</code>
+ → <code class="returnvalue">10.1/16</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">broadcast</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes the broadcast address for the address's network.
+ </p>
+ <p>
+ <code class="literal">broadcast(inet '192.168.1.5/24')</code>
+ → <code class="returnvalue">192.168.1.255/24</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">family</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the address's family: <code class="literal">4</code> for IPv4,
+ <code class="literal">6</code> for IPv6.
+ </p>
+ <p>
+ <code class="literal">family(inet '::1')</code>
+ → <code class="returnvalue">6</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">host</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the IP address as text, ignoring the netmask.
+ </p>
+ <p>
+ <code class="literal">host(inet '192.168.1.0/24')</code>
+ → <code class="returnvalue">192.168.1.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">hostmask</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes the host mask for the address's network.
+ </p>
+ <p>
+ <code class="literal">hostmask(inet '192.168.23.20/30')</code>
+ → <code class="returnvalue">0.0.0.3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">inet_merge</code> ( <code class="type">inet</code>, <code class="type">inet</code> )
+ → <code class="returnvalue">cidr</code>
+ </p>
+ <p>
+ Computes the smallest network that includes both of the given networks.
+ </p>
+ <p>
+ <code class="literal">inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')</code>
+ → <code class="returnvalue">192.168.0.0/22</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">inet_same_family</code> ( <code class="type">inet</code>, <code class="type">inet</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Tests whether the addresses belong to the same IP family.
+ </p>
+ <p>
+ <code class="literal">inet_same_family(inet '192.168.1.5/24', inet '::1')</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">masklen</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the netmask length in bits.
+ </p>
+ <p>
+ <code class="literal">masklen(inet '192.168.1.5/24')</code>
+ → <code class="returnvalue">24</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">netmask</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Computes the network mask for the address's network.
+ </p>
+ <p>
+ <code class="literal">netmask(inet '192.168.1.5/24')</code>
+ → <code class="returnvalue">255.255.255.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">network</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">cidr</code>
+ </p>
+ <p>
+ Returns the network part of the address, zeroing out
+ whatever is to the right of the netmask.
+ (This is equivalent to casting the value to <code class="type">cidr</code>.)
+ </p>
+ <p>
+ <code class="literal">network(inet '192.168.1.5/24')</code>
+ → <code class="returnvalue">192.168.1.0/24</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">set_masklen</code> ( <code class="type">inet</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Sets the netmask length for an <code class="type">inet</code> value.
+ The address part does not change.
+ </p>
+ <p>
+ <code class="literal">set_masklen(inet '192.168.1.5/24', 16)</code>
+ → <code class="returnvalue">192.168.1.5/16</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">set_masklen</code> ( <code class="type">cidr</code>, <code class="type">integer</code> )
+ → <code class="returnvalue">cidr</code>
+ </p>
+ <p>
+ Sets the netmask length for a <code class="type">cidr</code> value.
+ Address bits to the right of the new netmask are set to zero.
+ </p>
+ <p>
+ <code class="literal">set_masklen(cidr '192.168.1.0/24', 16)</code>
+ → <code class="returnvalue">192.168.0.0/16</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.5.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">text</code> ( <code class="type">inet</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the unabbreviated IP address and netmask length as text.
+ (This has the same result as an explicit cast to <code class="type">text</code>.)
+ </p>
+ <p>
+ <code class="literal">text(inet '192.168.1.5')</code>
+ → <code class="returnvalue">192.168.1.5/32</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="tip"><h3 class="title">Tip</h3><p>
+ The <code class="function">abbrev</code>, <code class="function">host</code>,
+ and <code class="function">text</code> functions are primarily intended to offer
+ alternative display formats for IP addresses.
+ </p></div><p>
+ The MAC address types, <code class="type">macaddr</code> and <code class="type">macaddr8</code>,
+ support the usual comparison operators shown in
+ <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>
+ as well as the specialized functions shown in
+ <a class="xref" href="functions-net.html#MACADDR-FUNCTIONS-TABLE" title="Table 9.41. MAC Address Functions">Table 9.41</a>.
+ In addition, they support the bitwise logical operators
+ <code class="literal">~</code>, <code class="literal">&amp;</code> and <code class="literal">|</code>
+ (NOT, AND and OR), just as shown above for IP addresses.
+ </p><div class="table" id="MACADDR-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.41. MAC Address Functions</strong></p><div class="table-contents"><table class="table" summary="MAC Address Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.8.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">trunc</code> ( <code class="type">macaddr</code> )
+ → <code class="returnvalue">macaddr</code>
+ </p>
+ <p>
+ Sets the last 3 bytes of the address to zero. The remaining prefix
+ can be associated with a particular manufacturer (using data not
+ included in <span class="productname">PostgreSQL</span>).
+ </p>
+ <p>
+ <code class="literal">trunc(macaddr '12:34:56:78:90:ab')</code>
+ → <code class="returnvalue">12:34:56:00:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">trunc</code> ( <code class="type">macaddr8</code> )
+ → <code class="returnvalue">macaddr8</code>
+ </p>
+ <p>
+ Sets the last 5 bytes of the address to zero. The remaining prefix
+ can be associated with a particular manufacturer (using data not
+ included in <span class="productname">PostgreSQL</span>).
+ </p>
+ <p>
+ <code class="literal">trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</code>
+ → <code class="returnvalue">12:34:56:00:00:00:00:00</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.18.8.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">macaddr8_set7bit</code> ( <code class="type">macaddr8</code> )
+ → <code class="returnvalue">macaddr8</code>
+ </p>
+ <p>
+ Sets the 7th bit of the address to one, creating what is known as
+ modified EUI-64, for inclusion in an IPv6 address.
+ </p>
+ <p>
+ <code class="literal">macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</code>
+ → <code class="returnvalue">02:34:56:ff:fe:ab:cd:ef</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.11. Geometric Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.13. Text Search Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-range.html b/doc/src/sgml/html/functions-range.html
new file mode 100644
index 0000000..e6c161a
--- /dev/null
+++ b/doc/src/sgml/html/functions-range.html
@@ -0,0 +1,707 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.20. Range/Multirange Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-array.html" title="9.19. Array Functions and Operators" /><link rel="next" href="functions-aggregate.html" title="9.21. Aggregate Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.20. Range/Multirange Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-array.html" title="9.19. Array Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-aggregate.html" title="9.21. Aggregate Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-RANGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.20. Range/Multirange Functions and Operators</h2></div></div></div><p>
+ See <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a> for an overview of range types.
+ </p><p>
+ <a class="xref" href="functions-range.html#RANGE-OPERATORS-TABLE" title="Table 9.54. Range Operators">Table 9.54</a> shows the specialized operators
+ available for range types.
+ <a class="xref" href="functions-range.html#MULTIRANGE-OPERATORS-TABLE" title="Table 9.55. Multirange Operators">Table 9.55</a> shows the specialized operators
+ available for multirange types.
+ In addition to those, the usual comparison operators shown in
+ <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for range
+ and multirange types. The comparison operators order first by the range lower
+ bounds, and only if those are equal do they compare the upper bounds. The
+ multirange operators compare each range until one is unequal. This
+ does not usually result in a useful overall ordering, but the operators are
+ provided to allow unique indexes to be constructed on ranges.
+ </p><div class="table" id="RANGE-OPERATORS-TABLE"><p class="title"><strong>Table 9.54. Range Operators</strong></p><div class="table-contents"><table class="table" summary="Range Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">@&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first range contain the second?
+ </p>
+ <p>
+ <code class="literal">int4range(2,4) @&gt; int4range(2,3)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">@&gt;</code> <code class="type">anyelement</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the range contain the element?
+ </p>
+ <p>
+ <code class="literal">'[2011-01-01,2011-03-01)'::tsrange @&gt; '2011-01-10'::timestamp</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&lt;@</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first range contained by the second?
+ </p>
+ <p>
+ <code class="literal">int4range(2,4) &lt;@ int4range(1,7)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyelement</code> <code class="literal">&lt;@</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the element contained in the range?
+ </p>
+ <p>
+ <code class="literal">42 &lt;@ int4range(1,7)</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&amp;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do the ranges overlap, that is, have any elements in common?
+ </p>
+ <p>
+ <code class="literal">int8range(3,7) &amp;&amp; int8range(4,12)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&lt;&lt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first range strictly left of the second?
+ </p>
+ <p>
+ <code class="literal">int8range(1,10) &lt;&lt; int8range(100,110)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&gt;&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first range strictly right of the second?
+ </p>
+ <p>
+ <code class="literal">int8range(50,60) &gt;&gt; int8range(20,30)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&lt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first range not extend to the right of the second?
+ </p>
+ <p>
+ <code class="literal">int8range(1,20) &amp;&lt; int8range(18,20)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first range not extend to the left of the second?
+ </p>
+ <p>
+ <code class="literal">int8range(7,20) &amp;&gt; int8range(5,10)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">-|-</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are the ranges adjacent?
+ </p>
+ <p>
+ <code class="literal">numrange(1.1,2.2) -|- numrange(2.2,3.3)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">+</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p>
+ Computes the union of the ranges. The ranges must overlap or be
+ adjacent, so that the union is a single range (but
+ see <code class="function">range_merge()</code>).
+ </p>
+ <p>
+ <code class="literal">numrange(5,15) + numrange(10,20)</code>
+ → <code class="returnvalue">[5,20)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">*</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p>
+ Computes the intersection of the ranges.
+ </p>
+ <p>
+ <code class="literal">int8range(5,15) * int8range(10,20)</code>
+ → <code class="returnvalue">[10,15)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">-</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p>
+ Computes the difference of the ranges. The second range must not be
+ contained in the first in such a way that the difference would not be
+ a single range.
+ </p>
+ <p>
+ <code class="literal">int8range(5,15) - int8range(10,20)</code>
+ → <code class="returnvalue">[5,10)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="MULTIRANGE-OPERATORS-TABLE"><p class="title"><strong>Table 9.55. Multirange Operators</strong></p><div class="table-contents"><table class="table" summary="Multirange Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">@&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first multirange contain the second?
+ </p>
+ <p>
+ <code class="literal">'{[2,4)}'::int4multirange @&gt; '{[2,3)}'::int4multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">@&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the multirange contain the range?
+ </p>
+ <p>
+ <code class="literal">'{[2,4)}'::int4multirange @&gt; int4range(2,3)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">@&gt;</code> <code class="type">anyelement</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the multirange contain the element?
+ </p>
+ <p>
+ <code class="literal">'{[2011-01-01,2011-03-01)}'::tsmultirange @&gt; '2011-01-10'::timestamp</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">@&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the range contain the multirange?
+ </p>
+ <p>
+ <code class="literal">'[2,4)'::int4range @&gt; '{[2,3)}'::int4multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&lt;@</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first multirange contained by the second?
+ </p>
+ <p>
+ <code class="literal">'{[2,4)}'::int4multirange &lt;@ '{[1,7)}'::int4multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&lt;@</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange contained by the range?
+ </p>
+ <p>
+ <code class="literal">'{[2,4)}'::int4multirange &lt;@ int4range(1,7)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&lt;@</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range contained by the multirange?
+ </p>
+ <p>
+ <code class="literal">int4range(2,4) &lt;@ '{[1,7)}'::int4multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyelement</code> <code class="literal">&lt;@</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the element contained by the multirange?
+ </p>
+ <p>
+ <code class="literal">4 &lt;@ '{[1,7)}'::int4multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&amp;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do the multiranges overlap, that is, have any elements in common?
+ </p>
+ <p>
+ <code class="literal">'{[3,7)}'::int8multirange &amp;&amp; '{[4,12)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&amp;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the multirange overlap the range?
+ </p>
+ <p>
+ <code class="literal">'{[3,7)}'::int8multirange &amp;&amp; int8range(4,12)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&amp;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the range overlap the multirange?
+ </p>
+ <p>
+ <code class="literal">int8range(3,7) &amp;&amp; '{[4,12)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&lt;&lt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first multirange strictly left of the second?
+ </p>
+ <p>
+ <code class="literal">'{[1,10)}'::int8multirange &lt;&lt; '{[100,110)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&lt;&lt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange strictly left of the range?
+ </p>
+ <p>
+ <code class="literal">'{[1,10)}'::int8multirange &lt;&lt; int8range(100,110)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&lt;&lt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range strictly left of the multirange?
+ </p>
+ <p>
+ <code class="literal">int8range(1,10) &lt;&lt; '{[100,110)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&gt;&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first multirange strictly right of the second?
+ </p>
+ <p>
+ <code class="literal">'{[50,60)}'::int8multirange &gt;&gt; '{[20,30)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&gt;&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange strictly right of the range?
+ </p>
+ <p>
+ <code class="literal">'{[50,60)}'::int8multirange &gt;&gt; int8range(20,30)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&gt;&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range strictly right of the multirange?
+ </p>
+ <p>
+ <code class="literal">int8range(50,60) &gt;&gt; '{[20,30)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&lt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first multirange not extend to the right of the second?
+ </p>
+ <p>
+ <code class="literal">'{[1,20)}'::int8multirange &amp;&lt; '{[18,20)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&lt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the multirange not extend to the right of the range?
+ </p>
+ <p>
+ <code class="literal">'{[1,20)}'::int8multirange &amp;&lt; int8range(18,20)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&lt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the range not extend to the right of the multirange?
+ </p>
+ <p>
+ <code class="literal">int8range(1,20) &amp;&lt; '{[18,20)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first multirange not extend to the left of the second?
+ </p>
+ <p>
+ <code class="literal">'{[7,20)}'::int8multirange &amp;&gt; '{[5,10)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">&amp;&gt;</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the multirange not extend to the left of the range?
+ </p>
+ <p>
+ <code class="literal">'{[7,20)}'::int8multirange &amp;&gt; int8range(5,10)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">&amp;&gt;</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the range not extend to the left of the multirange?
+ </p>
+ <p>
+ <code class="literal">int8range(7,20) &amp;&gt; '{[5,10)}'::int8multirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">-|-</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are the multiranges adjacent?
+ </p>
+ <p>
+ <code class="literal">'{[1.1,2.2)}'::nummultirange -|- '{[2.2,3.3)}'::nummultirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">-|-</code> <code class="type">anyrange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange adjacent to the range?
+ </p>
+ <p>
+ <code class="literal">'{[1.1,2.2)}'::nummultirange -|- numrange(2.2,3.3)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyrange</code> <code class="literal">-|-</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range adjacent to the multirange?
+ </p>
+ <p>
+ <code class="literal">numrange(1.1,2.2) -|- '{[2.2,3.3)}'::nummultirange</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">+</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Computes the union of the multiranges. The multiranges need not overlap
+ or be adjacent.
+ </p>
+ <p>
+ <code class="literal">'{[5,10)}'::nummultirange + '{[15,20)}'::nummultirange</code>
+ → <code class="returnvalue">{[5,10), [15,20)}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">*</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Computes the intersection of the multiranges.
+ </p>
+ <p>
+ <code class="literal">'{[5,15)}'::int8multirange * '{[10,20)}'::int8multirange</code>
+ → <code class="returnvalue">{[10,15)}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anymultirange</code> <code class="literal">-</code> <code class="type">anymultirange</code>
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Computes the difference of the multiranges.
+ </p>
+ <p>
+ <code class="literal">'{[5,20)}'::int8multirange - '{[10,15)}'::int8multirange</code>
+ → <code class="returnvalue">{[5,10), [15,20)}</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The left-of/right-of/adjacent operators always return false when an empty
+ range or multirange is involved; that is, an empty range is not considered to
+ be either before or after any other range.
+ </p><p>
+ Elsewhere empty ranges and multiranges are treated as the additive identity:
+ anything unioned with an empty value is itself. Anything minus an empty
+ value is itself. An empty multirange has exactly the same points as an empty
+ range. Every range contains the empty range. Every multirange contains as many
+ empty ranges as you like.
+ </p><p>
+ The range union and difference operators will fail if the resulting range would
+ need to contain two disjoint sub-ranges, as such a range cannot be
+ represented. There are separate operators for union and difference that take
+ multirange parameters and return a multirange, and they do not fail even if
+ their arguments are disjoint. So if you need a union or difference operation
+ for ranges that may be disjoint, you can avoid errors by first casting your
+ ranges to multiranges.
+ </p><p>
+ <a class="xref" href="functions-range.html#RANGE-FUNCTIONS-TABLE" title="Table 9.56. Range Functions">Table 9.56</a> shows the functions
+ available for use with range types.
+ <a class="xref" href="functions-range.html#MULTIRANGE-FUNCTIONS-TABLE" title="Table 9.57. Multirange Functions">Table 9.57</a> shows the functions
+ available for use with multirange types.
+ </p><div class="table" id="RANGE-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.56. Range Functions</strong></p><div class="table-contents"><table class="table" summary="Range Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">lower</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Extracts the lower bound of the range (<code class="literal">NULL</code> if the
+ range is empty or the lower bound is infinite).
+ </p>
+ <p>
+ <code class="literal">lower(numrange(1.1,2.2))</code>
+ → <code class="returnvalue">1.1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">upper</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Extracts the upper bound of the range (<code class="literal">NULL</code> if the
+ range is empty or the upper bound is infinite).
+ </p>
+ <p>
+ <code class="literal">upper(numrange(1.1,2.2))</code>
+ → <code class="returnvalue">2.2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">isempty</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range empty?
+ </p>
+ <p>
+ <code class="literal">isempty(numrange(1.1,2.2))</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">lower_inc</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range's lower bound inclusive?
+ </p>
+ <p>
+ <code class="literal">lower_inc(numrange(1.1,2.2))</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">upper_inc</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range's upper bound inclusive?
+ </p>
+ <p>
+ <code class="literal">upper_inc(numrange(1.1,2.2))</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">lower_inf</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range's lower bound infinite?
+ </p>
+ <p>
+ <code class="literal">lower_inf('(,)'::daterange)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">upper_inf</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the range's upper bound infinite?
+ </p>
+ <p>
+ <code class="literal">upper_inf('(,)'::daterange)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.10.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">range_merge</code> ( <code class="type">anyrange</code>, <code class="type">anyrange</code> )
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p>
+ Computes the smallest range that includes both of the given ranges.
+ </p>
+ <p>
+ <code class="literal">range_merge('[1,2)'::int4range, '[3,4)'::int4range)</code>
+ → <code class="returnvalue">[1,4)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="MULTIRANGE-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.57. Multirange Functions</strong></p><div class="table-contents"><table class="table" summary="Multirange Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">lower</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Extracts the lower bound of the multirange (<code class="literal">NULL</code> if the
+ multirange is empty or the lower bound is infinite).
+ </p>
+ <p>
+ <code class="literal">lower('{[1.1,2.2)}'::nummultirange)</code>
+ → <code class="returnvalue">1.1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">upper</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Extracts the upper bound of the multirange (<code class="literal">NULL</code> if the
+ multirange is empty or the upper bound is infinite).
+ </p>
+ <p>
+ <code class="literal">upper('{[1.1,2.2)}'::nummultirange)</code>
+ → <code class="returnvalue">2.2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">isempty</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange empty?
+ </p>
+ <p>
+ <code class="literal">isempty('{[1.1,2.2)}'::nummultirange)</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">lower_inc</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange's lower bound inclusive?
+ </p>
+ <p>
+ <code class="literal">lower_inc('{[1.1,2.2)}'::nummultirange)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">upper_inc</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange's upper bound inclusive?
+ </p>
+ <p>
+ <code class="literal">upper_inc('{[1.1,2.2)}'::nummultirange)</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">lower_inf</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange's lower bound infinite?
+ </p>
+ <p>
+ <code class="literal">lower_inf('{(,)}'::datemultirange)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">upper_inf</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the multirange's upper bound infinite?
+ </p>
+ <p>
+ <code class="literal">upper_inf('{(,)}'::datemultirange)</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">range_merge</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">anyrange</code>
+ </p>
+ <p>
+ Computes the smallest range that includes the entire multirange.
+ </p>
+ <p>
+ <code class="literal">range_merge('{[1,2), [3,4)}'::int4multirange)</code>
+ → <code class="returnvalue">[1,4)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">multirange</code> ( <code class="type">anyrange</code> )
+ → <code class="returnvalue">anymultirange</code>
+ </p>
+ <p>
+ Returns a multirange containing just the given range.
+ </p>
+ <p>
+ <code class="literal">multirange('[1,2)'::int4range)</code>
+ → <code class="returnvalue">{[1,2)}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.26.11.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">unnest</code> ( <code class="type">anymultirange</code> )
+ → <code class="returnvalue">setof anyrange</code>
+ </p>
+ <p>
+ Expands a multirange into a set of ranges.
+ The ranges are read out in storage order (ascending).
+ </p>
+ <p>
+ <code class="literal">unnest('{[1,2), [3,4)}'::int4multirange)</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ [1,2)
+ [3,4)
+</pre><p>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="function">lower_inc</code>, <code class="function">upper_inc</code>,
+ <code class="function">lower_inf</code>, and <code class="function">upper_inf</code>
+ functions all return false for an empty range or multirange.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-array.html" title="9.19. Array Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-aggregate.html" title="9.21. Aggregate Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.19. Array Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.21. Aggregate Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-sequence.html b/doc/src/sgml/html/functions-sequence.html
new file mode 100644
index 0000000..612edd4
--- /dev/null
+++ b/doc/src/sgml/html/functions-sequence.html
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.17. Sequence Manipulation Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-json.html" title="9.16. JSON Functions and Operators" /><link rel="next" href="functions-conditional.html" title="9.18. Conditional Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.17. Sequence Manipulation Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-json.html" title="9.16. JSON Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-conditional.html" title="9.18. Conditional Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-SEQUENCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.17. Sequence Manipulation Functions</h2></div></div></div><a id="id-1.5.8.23.2" class="indexterm"></a><p>
+ This section describes functions for operating on <em class="firstterm">sequence
+ objects</em>, also called sequence generators or just sequences.
+ Sequence objects are special single-row tables created with <a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a>.
+ Sequence objects are commonly used to generate unique identifiers
+ for rows of a table. The sequence functions, listed in <a class="xref" href="functions-sequence.html#FUNCTIONS-SEQUENCE-TABLE" title="Table 9.51. Sequence Functions">Table 9.51</a>, provide simple, multiuser-safe
+ methods for obtaining successive sequence values from sequence
+ objects.
+ </p><div class="table" id="FUNCTIONS-SEQUENCE-TABLE"><p class="title"><strong>Table 9.51. Sequence Functions</strong></p><div class="table-contents"><table class="table" summary="Sequence Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.23.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">nextval</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Advances the sequence object to its next value and returns that value.
+ This is done atomically: even if multiple sessions
+ execute <code class="function">nextval</code> concurrently, each will safely
+ receive a distinct sequence value.
+ If the sequence object has been created with default parameters,
+ successive <code class="function">nextval</code> calls will return successive
+ values beginning with 1. Other behaviors can be obtained by using
+ appropriate parameters in the <a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a>
+ command.
+ </p>
+ <p>
+ This function requires <code class="literal">USAGE</code>
+ or <code class="literal">UPDATE</code> privilege on the sequence.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.23.4.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">setval</code> ( <code class="type">regclass</code>, <code class="type">bigint</code> [<span class="optional">, <code class="type">boolean</code> </span>] )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Sets the sequence object's current value, and optionally
+ its <code class="literal">is_called</code> flag. The two-parameter
+ form sets the sequence's <code class="literal">last_value</code> field to the
+ specified value and sets its <code class="literal">is_called</code> field to
+ <code class="literal">true</code>, meaning that the next
+ <code class="function">nextval</code> will advance the sequence before
+ returning a value. The value that will be reported
+ by <code class="function">currval</code> is also set to the specified value.
+ In the three-parameter form, <code class="literal">is_called</code> can be set
+ to either <code class="literal">true</code>
+ or <code class="literal">false</code>. <code class="literal">true</code> has the same
+ effect as the two-parameter form. If it is set
+ to <code class="literal">false</code>, the next <code class="function">nextval</code>
+ will return exactly the specified value, and sequence advancement
+ commences with the following <code class="function">nextval</code>.
+ Furthermore, the value reported by <code class="function">currval</code> is not
+ changed in this case. For example,
+</p><pre class="programlisting">
+SELECT setval('myseq', 42); <em class="lineannotation"><span class="lineannotation">Next <code class="function">nextval</code> will return 43</span></em>
+SELECT setval('myseq', 42, true); <em class="lineannotation"><span class="lineannotation">Same as above</span></em>
+SELECT setval('myseq', 42, false); <em class="lineannotation"><span class="lineannotation">Next <code class="function">nextval</code> will return 42</span></em>
+</pre><p>
+ The result returned by <code class="function">setval</code> is just the value of its
+ second argument.
+ </p>
+ <p>
+ This function requires <code class="literal">UPDATE</code> privilege on the
+ sequence.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.23.4.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">currval</code> ( <code class="type">regclass</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the value most recently obtained
+ by <code class="function">nextval</code> for this sequence in the current
+ session. (An error is reported if <code class="function">nextval</code> has
+ never been called for this sequence in this session.) Because this is
+ returning a session-local value, it gives a predictable answer whether
+ or not other sessions have executed <code class="function">nextval</code> since
+ the current session did.
+ </p>
+ <p>
+ This function requires <code class="literal">USAGE</code>
+ or <code class="literal">SELECT</code> privilege on the sequence.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.23.4.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">lastval</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the value most recently returned by
+ <code class="function">nextval</code> in the current session. This function is
+ identical to <code class="function">currval</code>, except that instead
+ of taking the sequence name as an argument it refers to whichever
+ sequence <code class="function">nextval</code> was most recently applied to
+ in the current session. It is an error to call
+ <code class="function">lastval</code> if <code class="function">nextval</code>
+ has not yet been called in the current session.
+ </p>
+ <p>
+ This function requires <code class="literal">USAGE</code>
+ or <code class="literal">SELECT</code> privilege on the last used sequence.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="caution"><h3 class="title">Caution</h3><p>
+ To avoid blocking concurrent transactions that obtain numbers from
+ the same sequence, the value obtained by <code class="function">nextval</code>
+ is not reclaimed for re-use if the calling transaction later aborts.
+ This means that transaction aborts or database crashes can result in
+ gaps in the sequence of assigned values. That can happen without a
+ transaction abort, too. For example an <code class="command">INSERT</code> with
+ an <code class="literal">ON CONFLICT</code> clause will compute the to-be-inserted
+ tuple, including doing any required <code class="function">nextval</code>
+ calls, before detecting any conflict that would cause it to follow
+ the <code class="literal">ON CONFLICT</code> rule instead.
+ Thus, <span class="productname">PostgreSQL</span> sequence
+ objects <span class="emphasis"><em>cannot be used to obtain <span class="quote">“<span class="quote">gapless</span>”</span>
+ sequences</em></span>.
+ </p><p>
+ Likewise, sequence state changes made by <code class="function">setval</code>
+ are immediately visible to other transactions, and are not undone if
+ the calling transaction rolls back.
+ </p><p>
+ If the database cluster crashes before committing a transaction
+ containing a <code class="function">nextval</code>
+ or <code class="function">setval</code> call, the sequence state change might
+ not have made its way to persistent storage, so that it is uncertain
+ whether the sequence will have its original or updated state after the
+ cluster restarts. This is harmless for usage of the sequence within
+ the database, since other effects of uncommitted transactions will not
+ be visible either. However, if you wish to use a sequence value for
+ persistent outside-the-database purposes, make sure that the
+ <code class="function">nextval</code> call has been committed before doing so.
+ </p></div><p>
+ The sequence to be operated on by a sequence function is specified by
+ a <code class="type">regclass</code> argument, which is simply the OID of the sequence in the
+ <code class="structname">pg_class</code> system catalog. You do not have to look up the
+ OID by hand, however, since the <code class="type">regclass</code> data type's input
+ converter will do the work for you. See <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>
+ for details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-json.html" title="9.16. JSON Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-conditional.html" title="9.18. Conditional Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.16. JSON Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.18. Conditional Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-srf.html b/doc/src/sgml/html/functions-srf.html
new file mode 100644
index 0000000..2bc266c
--- /dev/null
+++ b/doc/src/sgml/html/functions-srf.html
@@ -0,0 +1,218 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.25. Set Returning Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-comparisons.html" title="9.24. Row and Array Comparisons" /><link rel="next" href="functions-info.html" title="9.26. System Information Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.25. Set Returning Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-info.html" title="9.26. System Information Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-SRF"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.25. Set Returning Functions</h2></div></div></div><a id="id-1.5.8.31.2" class="indexterm"></a><p>
+ 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 <a class="xref" href="functions-srf.html#FUNCTIONS-SRF-SERIES" title="Table 9.64. Series Generating Functions">Table 9.64</a> and
+ <a class="xref" href="functions-srf.html#FUNCTIONS-SRF-SUBSCRIPTS" title="Table 9.65. Subscript Generating Functions">Table 9.65</a>. Other, more specialized
+ set-returning functions are described elsewhere in this manual.
+ See <a class="xref" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS" title="7.2.1.4. Table Functions">Section 7.2.1.4</a> for ways to combine multiple
+ set-returning functions.
+ </p><div class="table" id="FUNCTIONS-SRF-SERIES"><p class="title"><strong>Table 9.64. Series Generating Functions</strong></p><div class="table-contents"><table class="table" summary="Series Generating Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.31.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">generate_series</code> ( <em class="parameter"><code>start</code></em> <code class="type">integer</code>, <em class="parameter"><code>stop</code></em> <code class="type">integer</code> [<span class="optional">, <em class="parameter"><code>step</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">setof integer</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">generate_series</code> ( <em class="parameter"><code>start</code></em> <code class="type">bigint</code>, <em class="parameter"><code>stop</code></em> <code class="type">bigint</code> [<span class="optional">, <em class="parameter"><code>step</code></em> <code class="type">bigint</code> </span>] )
+ → <code class="returnvalue">setof bigint</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">generate_series</code> ( <em class="parameter"><code>start</code></em> <code class="type">numeric</code>, <em class="parameter"><code>stop</code></em> <code class="type">numeric</code> [<span class="optional">, <em class="parameter"><code>step</code></em> <code class="type">numeric</code> </span>] )
+ → <code class="returnvalue">setof numeric</code>
+ </p>
+ <p>
+ Generates a series of values from <em class="parameter"><code>start</code></em>
+ to <em class="parameter"><code>stop</code></em>, with a step size
+ of <em class="parameter"><code>step</code></em>. <em class="parameter"><code>step</code></em>
+ defaults to 1.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">generate_series</code> ( <em class="parameter"><code>start</code></em> <code class="type">timestamp</code>, <em class="parameter"><code>stop</code></em> <code class="type">timestamp</code>, <em class="parameter"><code>step</code></em> <code class="type">interval</code> )
+ → <code class="returnvalue">setof timestamp</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">generate_series</code> ( <em class="parameter"><code>start</code></em> <code class="type">timestamp with time zone</code>, <em class="parameter"><code>stop</code></em> <code class="type">timestamp with time zone</code>, <em class="parameter"><code>step</code></em> <code class="type">interval</code> )
+ → <code class="returnvalue">setof timestamp with time zone</code>
+ </p>
+ <p>
+ Generates a series of values from <em class="parameter"><code>start</code></em>
+ to <em class="parameter"><code>stop</code></em>, with a step size
+ of <em class="parameter"><code>step</code></em>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ When <em class="parameter"><code>step</code></em> is positive, zero rows are returned if
+ <em class="parameter"><code>start</code></em> is greater than <em class="parameter"><code>stop</code></em>.
+ Conversely, when <em class="parameter"><code>step</code></em> is negative, zero rows are
+ returned if <em class="parameter"><code>start</code></em> is less than <em class="parameter"><code>stop</code></em>.
+ Zero rows are also returned if any input is <code class="literal">NULL</code>.
+ It is an error
+ for <em class="parameter"><code>step</code></em> to be zero. Some examples follow:
+</p><pre class="programlisting">
+SELECT * FROM generate_series(2,4);
+ generate_series
+-----------------
+ 2
+ 3
+ 4
+(3 rows)
+
+SELECT * FROM generate_series(5,1,-2);
+ generate_series
+-----------------
+ 5
+ 3
+ 1
+(3 rows)
+
+SELECT * FROM generate_series(4,3);
+ generate_series
+-----------------
+(0 rows)
+
+SELECT generate_series(1.1, 4, 1.3);
+ generate_series
+-----------------
+ 1.1
+ 2.4
+ 3.7
+(3 rows)
+
+-- this example relies on the date-plus-integer operator:
+SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a);
+ dates
+------------
+ 2004-02-05
+ 2004-02-12
+ 2004-02-19
+(3 rows)
+
+SELECT * FROM generate_series('2008-03-01 00:00'::timestamp,
+ '2008-03-04 12:00', '10 hours');
+ generate_series
+---------------------
+ 2008-03-01 00:00:00
+ 2008-03-01 10:00:00
+ 2008-03-01 20:00:00
+ 2008-03-02 06:00:00
+ 2008-03-02 16:00:00
+ 2008-03-03 02:00:00
+ 2008-03-03 12:00:00
+ 2008-03-03 22:00:00
+ 2008-03-04 08:00:00
+(9 rows)
+</pre><p>
+ </p><div class="table" id="FUNCTIONS-SRF-SUBSCRIPTS"><p class="title"><strong>Table 9.65. Subscript Generating Functions</strong></p><div class="table-contents"><table class="table" summary="Subscript Generating Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.31.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">generate_subscripts</code> ( <em class="parameter"><code>array</code></em> <code class="type">anyarray</code>, <em class="parameter"><code>dim</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">setof integer</code>
+ </p>
+ <p>
+ Generates a series comprising the valid subscripts of
+ the <em class="parameter"><code>dim</code></em>'th dimension of the given array.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">generate_subscripts</code> ( <em class="parameter"><code>array</code></em> <code class="type">anyarray</code>, <em class="parameter"><code>dim</code></em> <code class="type">integer</code>, <em class="parameter"><code>reverse</code></em> <code class="type">boolean</code> )
+ → <code class="returnvalue">setof integer</code>
+ </p>
+ <p>
+ Generates a series comprising the valid subscripts of
+ the <em class="parameter"><code>dim</code></em>'th dimension of the given array.
+ When <em class="parameter"><code>reverse</code></em> is true, returns the series in
+ reverse order.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="function">generate_subscripts</code> is a convenience function that generates
+ the set of valid subscripts for the specified dimension of the given
+ array.
+ Zero rows are returned for arrays that do not have the requested dimension,
+ or if any input is <code class="literal">NULL</code>.
+ Some examples follow:
+</p><pre class="programlisting">
+-- basic usage:
+SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s;
+ s
+---
+ 1
+ 2
+ 3
+ 4
+(4 rows)
+
+-- presenting an array, the subscript and the subscripted
+-- value requires a subquery:
+SELECT * FROM arrays;
+ a
+--------------------
+ {-1,-2}
+ {100,200,300}
+(2 rows)
+
+SELECT a AS array, s AS subscript, a[s] AS value
+FROM (SELECT generate_subscripts(a, 1) AS s, a FROM arrays) foo;
+ array | subscript | value
+---------------+-----------+-------
+ {-1,-2} | 1 | -1
+ {-1,-2} | 2 | -2
+ {100,200,300} | 1 | 100
+ {100,200,300} | 2 | 200
+ {100,200,300} | 3 | 300
+(5 rows)
+
+-- unnest a 2D array:
+CREATE OR REPLACE FUNCTION unnest2(anyarray)
+RETURNS SETOF anyelement AS $$
+select $1[i][j]
+ from generate_subscripts($1,1) g1(i),
+ generate_subscripts($1,2) g2(j);
+$$ LANGUAGE sql IMMUTABLE;
+CREATE FUNCTION
+SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]);
+ unnest2
+---------
+ 1
+ 2
+ 3
+ 4
+(4 rows)
+</pre><p>
+ </p><a id="id-1.5.8.31.8" class="indexterm"></a><p>
+ When a function in the <code class="literal">FROM</code> clause is suffixed
+ by <code class="literal">WITH ORDINALITY</code>, a <code class="type">bigint</code> column is
+ appended to the function's output column(s), which starts from 1 and
+ increments by 1 for each row of the function's output.
+ This is most useful in the case of set returning
+ functions such as <code class="function">unnest()</code>.
+
+</p><pre class="programlisting">
+-- set returning function WITH ORDINALITY:
+SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
+ ls | n
+-----------------+----
+ pg_serial | 1
+ pg_twophase | 2
+ postmaster.opts | 3
+ pg_notify | 4
+ postgresql.conf | 5
+ pg_tblspc | 6
+ logfile | 7
+ base | 8
+ postmaster.pid | 9
+ pg_ident.conf | 10
+ global | 11
+ pg_xact | 12
+ pg_snapshots | 13
+ pg_multixact | 14
+ PG_VERSION | 15
+ pg_wal | 16
+ pg_hba.conf | 17
+ pg_stat_tmp | 18
+ pg_subtrans | 19
+(19 rows)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-info.html" title="9.26. System Information Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.24. Row and Array Comparisons </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.26. System Information Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-statistics.html b/doc/src/sgml/html/functions-statistics.html
new file mode 100644
index 0000000..210bb3f
--- /dev/null
+++ b/doc/src/sgml/html/functions-statistics.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.30. Statistics Information Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-event-triggers.html" title="9.29. Event Trigger Functions" /><link rel="next" href="typeconv.html" title="Chapter 10. Type Conversion" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.30. Statistics Information Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv.html" title="Chapter 10. Type Conversion">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-STATISTICS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.30. Statistics Information Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-statistics.html#FUNCTIONS-STATISTICS-MCV">9.30.1. Inspecting MCV Lists</a></span></dt></dl></div><a id="id-1.5.8.36.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a function to inspect complex
+ statistics defined using the <code class="command">CREATE STATISTICS</code> command.
+ </p><div class="sect2" id="FUNCTIONS-STATISTICS-MCV"><div class="titlepage"><div><div><h3 class="title">9.30.1. Inspecting MCV Lists</h3></div></div></div><a id="id-1.5.8.36.4.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">pg_mcv_list_items</code> ( <code class="type">pg_mcv_list</code> ) → <code class="returnvalue">setof record</code>
+</pre><p>
+ <code class="function">pg_mcv_list_items</code> returns a set of records describing
+ all items stored in a multi-column <acronym class="acronym">MCV</acronym> list. It
+ returns the following columns:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">index</code></td><td><code class="type">integer</code></td><td>index of the item in the <acronym class="acronym">MCV</acronym> list</td></tr><tr><td><code class="literal">values</code></td><td><code class="type">text[]</code></td><td>values stored in the MCV item</td></tr><tr><td><code class="literal">nulls</code></td><td><code class="type">boolean[]</code></td><td>flags identifying <code class="literal">NULL</code> values</td></tr><tr><td><code class="literal">frequency</code></td><td><code class="type">double precision</code></td><td>frequency of this <acronym class="acronym">MCV</acronym> item</td></tr><tr><td><code class="literal">base_frequency</code></td><td><code class="type">double precision</code></td><td>base frequency of this <acronym class="acronym">MCV</acronym> item</td></tr></tbody></table></div><p>
+ </p><p>
+ The <code class="function">pg_mcv_list_items</code> function can be used like this:
+
+</p><pre class="programlisting">
+SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
+ pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts';
+</pre><p>
+
+ Values of the <code class="type">pg_mcv_list</code> type can be obtained only from the
+ <code class="structname">pg_statistic_ext_data</code>.<code class="structfield">stxdmcv</code>
+ column.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv.html" title="Chapter 10. Type Conversion">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.29. Event Trigger Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Type Conversion</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-string.html b/doc/src/sgml/html/functions-string.html
new file mode 100644
index 0000000..8f480d1
--- /dev/null
+++ b/doc/src/sgml/html/functions-string.html
@@ -0,0 +1,1208 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.4. String Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-math.html" title="9.3. Mathematical Functions and Operators" /><link rel="next" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.4. String Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-math.html" title="9.3. Mathematical Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-STRING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.4. String Functions and Operators</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-string.html#FUNCTIONS-STRING-FORMAT">9.4.1. <code class="function">format</code></a></span></dt></dl></div><p>
+ This section describes functions and operators for examining and
+ manipulating string values. Strings in this context include values
+ of the types <code class="type">character</code>, <code class="type">character varying</code>,
+ and <code class="type">text</code>. Except where noted, these functions and operators
+ are declared to accept and return type <code class="type">text</code>. They will
+ interchangeably accept <code class="type">character varying</code> arguments.
+ Values of type <code class="type">character</code> will be converted
+ to <code class="type">text</code> before the function or operator is applied, resulting
+ in stripping any trailing spaces in the <code class="type">character</code> value.
+ </p><p>
+ <acronym class="acronym">SQL</acronym> defines some string functions that use
+ key words, rather than commas, to separate
+ arguments. Details are in
+ <a class="xref" href="functions-string.html#FUNCTIONS-STRING-SQL" title="Table 9.9. SQL String Functions and Operators">Table 9.9</a>.
+ <span class="productname">PostgreSQL</span> also provides versions of these functions
+ that use the regular function invocation syntax
+ (see <a class="xref" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators">Table 9.10</a>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The string concatenation operator (<code class="literal">||</code>) will accept
+ non-string input, so long as at least one input is of string type, as shown
+ in <a class="xref" href="functions-string.html#FUNCTIONS-STRING-SQL" title="Table 9.9. SQL String Functions and Operators">Table 9.9</a>. For other cases, inserting an
+ explicit coercion to <code class="type">text</code> can be used to have non-string input
+ accepted.
+ </p></div><div class="table" id="FUNCTIONS-STRING-SQL"><p class="title"><strong>Table 9.9. <acronym class="acronym">SQL</acronym> String Functions and Operators</strong></p><div class="table-contents"><table class="table" summary="SQL String Functions and Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function/Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="type">text</code> <code class="literal">||</code> <code class="type">text</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Concatenates the two strings.
+ </p>
+ <p>
+ <code class="literal">'Post' || 'greSQL'</code>
+ → <code class="returnvalue">PostgreSQL</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">||</code> <code class="type">anynonarray</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">anynonarray</code> <code class="literal">||</code> <code class="type">text</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the non-string input to text, then concatenates the two
+ strings. (The non-string input cannot be of an array type, because
+ that would create ambiguity with the array <code class="literal">||</code>
+ operators. If you want to concatenate an array's text equivalent,
+ cast it to <code class="type">text</code> explicitly.)
+ </p>
+ <p>
+ <code class="literal">'Value: ' || 42</code>
+ → <code class="returnvalue">Value: 42</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.3.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.10.5.2.2.3.1.1.2" class="indexterm"></a>
+ <code class="type">text</code> <code class="literal">IS</code> [<span class="optional"><code class="literal">NOT</code></span>] [<span class="optional"><em class="parameter"><code>form</code></em></span>] <code class="literal">NORMALIZED</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Checks whether the string is in the specified Unicode normalization
+ form. The optional <em class="parameter"><code>form</code></em> key word specifies the
+ form: <code class="literal">NFC</code> (the default), <code class="literal">NFD</code>,
+ <code class="literal">NFKC</code>, or <code class="literal">NFKD</code>. This expression can
+ only be used when the server encoding is <code class="literal">UTF8</code>. Note
+ that checking for normalization using this expression is often faster
+ than normalizing possibly already normalized strings.
+ </p>
+ <p>
+ <code class="literal">U&amp;'\0061\0308bc' IS NFD NORMALIZED</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">bit_length</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bits in the string (8
+ times the <code class="function">octet_length</code>).
+ </p>
+ <p>
+ <code class="literal">bit_length('jose')</code>
+ → <code class="returnvalue">32</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.5.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.10.5.2.2.5.1.1.2" class="indexterm"></a>
+ <a id="id-1.5.8.10.5.2.2.5.1.1.3" class="indexterm"></a>
+ <code class="function">char_length</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.5.1.2.1" class="indexterm"></a>
+ <code class="function">character_length</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of characters in the string.
+ </p>
+ <p>
+ <code class="literal">char_length('josé')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">lower</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the string to all lower case, according to the rules of the
+ database's locale.
+ </p>
+ <p>
+ <code class="literal">lower('TOM')</code>
+ → <code class="returnvalue">tom</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.7.1.1.1" class="indexterm"></a>
+ <a id="id-1.5.8.10.5.2.2.7.1.1.2" class="indexterm"></a>
+ <code class="function">normalize</code> ( <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>form</code></em> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the string to the specified Unicode
+ normalization form. The optional <em class="parameter"><code>form</code></em> key word
+ specifies the form: <code class="literal">NFC</code> (the default),
+ <code class="literal">NFD</code>, <code class="literal">NFKC</code>, or
+ <code class="literal">NFKD</code>. This function can only be used when the
+ server encoding is <code class="literal">UTF8</code>.
+ </p>
+ <p>
+ <code class="literal">normalize(U&amp;'\0061\0308bc', NFC)</code>
+ → <code class="returnvalue">U&amp;'\00E4bc'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">octet_length</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bytes in the string.
+ </p>
+ <p>
+ <code class="literal">octet_length('josé')</code>
+ → <code class="returnvalue">5</code> (if server encoding is UTF8)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">octet_length</code> ( <code class="type">character</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of bytes in the string. Since this version of the
+ function accepts type <code class="type">character</code> directly, it will not
+ strip trailing spaces.
+ </p>
+ <p>
+ <code class="literal">octet_length('abc '::character(4))</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">overlay</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> <code class="literal">PLACING</code> <em class="parameter"><code>newsubstring</code></em> <code class="type">text</code> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Replaces the substring of <em class="parameter"><code>string</code></em> that starts at
+ the <em class="parameter"><code>start</code></em>'th character and extends
+ for <em class="parameter"><code>count</code></em> characters
+ with <em class="parameter"><code>newsubstring</code></em>.
+ If <em class="parameter"><code>count</code></em> is omitted, it defaults to the length
+ of <em class="parameter"><code>newsubstring</code></em>.
+ </p>
+ <p>
+ <code class="literal">overlay('Txxxxas' placing 'hom' from 2 for 4)</code>
+ → <code class="returnvalue">Thomas</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">position</code> ( <em class="parameter"><code>substring</code></em> <code class="type">text</code> <code class="literal">IN</code> <em class="parameter"><code>string</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns first starting index of the specified
+ <em class="parameter"><code>substring</code></em> within
+ <em class="parameter"><code>string</code></em>, or zero if it's not present.
+ </p>
+ <p>
+ <code class="literal">position('om' in 'Thomas')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">substring</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> [<span class="optional"> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> </span>] [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts the substring of <em class="parameter"><code>string</code></em> starting at
+ the <em class="parameter"><code>start</code></em>'th character if that is specified,
+ and stopping after <em class="parameter"><code>count</code></em> characters if that is
+ specified. Provide at least one of <em class="parameter"><code>start</code></em>
+ and <em class="parameter"><code>count</code></em>.
+ </p>
+ <p>
+ <code class="literal">substring('Thomas' from 2 for 3)</code>
+ → <code class="returnvalue">hom</code>
+ </p>
+ <p>
+ <code class="literal">substring('Thomas' from 3)</code>
+ → <code class="returnvalue">omas</code>
+ </p>
+ <p>
+ <code class="literal">substring('Thomas' for 2)</code>
+ → <code class="returnvalue">Th</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">substring</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> <code class="literal">FROM</code> <em class="parameter"><code>pattern</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts the first substring matching POSIX regular expression; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">substring('Thomas' from '...$')</code>
+ → <code class="returnvalue">mas</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">substring</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> <code class="literal">SIMILAR</code> <em class="parameter"><code>pattern</code></em> <code class="type">text</code> <code class="literal">ESCAPE</code> <em class="parameter"><code>escape</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">substring</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> <code class="literal">FROM</code> <em class="parameter"><code>pattern</code></em> <code class="type">text</code> <code class="literal">FOR</code> <em class="parameter"><code>escape</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts the first substring matching <acronym class="acronym">SQL</acronym> regular expression;
+ see <a class="xref" href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP" title="9.7.2. SIMILAR TO Regular Expressions">Section 9.7.2</a>. The first form has
+ been specified since SQL:2003; the second form was only in SQL:1999
+ and should be considered obsolete.
+ </p>
+ <p>
+ <code class="literal">substring('Thomas' similar '%#"o_a#"_' escape '#')</code>
+ → <code class="returnvalue">oma</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>]
+ [<span class="optional"> <em class="parameter"><code>characters</code></em> <code class="type">text</code> </span>] <code class="literal">FROM</code>
+ <em class="parameter"><code>string</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Removes the longest string containing only characters in
+ <em class="parameter"><code>characters</code></em> (a space by default) from the
+ start, end, or both ends (<code class="literal">BOTH</code> is the default)
+ of <em class="parameter"><code>string</code></em>.
+ </p>
+ <p>
+ <code class="literal">trim(both 'xyz' from 'yxTomxx')</code>
+ → <code class="returnvalue">Tom</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>] [<span class="optional"> <code class="literal">FROM</code> </span>]
+ <em class="parameter"><code>string</code></em> <code class="type">text</code> [<span class="optional">,
+ <em class="parameter"><code>characters</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ This is a non-standard syntax for <code class="function">trim()</code>.
+ </p>
+ <p>
+ <code class="literal">trim(both from 'yxTomxx', 'xyz')</code>
+ → <code class="returnvalue">Tom</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.5.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">upper</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the string to all upper case, according to the rules of the
+ database's locale.
+ </p>
+ <p>
+ <code class="literal">upper('tom')</code>
+ → <code class="returnvalue">TOM</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Additional string manipulation functions and operators are available
+ and are listed in <a class="xref" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators">Table 9.10</a>. (Some of
+ these are used internally to implement
+ the <acronym class="acronym">SQL</acronym>-standard string functions listed in
+ <a class="xref" href="functions-string.html#FUNCTIONS-STRING-SQL" title="Table 9.9. SQL String Functions and Operators">Table 9.9</a>.)
+ There are also pattern-matching operators, which are described in
+ <a class="xref" href="functions-matching.html" title="9.7. Pattern Matching">Section 9.7</a>, and operators for full-text
+ search, which are described in <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a>.
+ </p><div class="table" id="FUNCTIONS-STRING-OTHER"><p class="title"><strong>Table 9.10. Other String Functions and Operators</strong></p><div class="table-contents"><table class="table" summary="Other String Functions and Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function/Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="type">text</code> <code class="literal">^@</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if the first string starts with the second string
+ (equivalent to the <code class="function">starts_with()</code> function).
+ </p>
+ <p>
+ <code class="literal">'alphabet' ^@ 'alph'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">ascii</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the numeric code of the first character of the argument.
+ In <acronym class="acronym">UTF8</acronym> encoding, returns the Unicode code point
+ of the character. In other multibyte encodings, the argument must
+ be an <acronym class="acronym">ASCII</acronym> character.
+ </p>
+ <p>
+ <code class="literal">ascii('x')</code>
+ → <code class="returnvalue">120</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">btrim</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>characters</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Removes the longest string containing only characters
+ in <em class="parameter"><code>characters</code></em> (a space by default)
+ from the start and end of <em class="parameter"><code>string</code></em>.
+ </p>
+ <p>
+ <code class="literal">btrim('xyxtrimyyx', 'xyz')</code>
+ → <code class="returnvalue">trim</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">chr</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the character with the given code. In <acronym class="acronym">UTF8</acronym>
+ encoding the argument is treated as a Unicode code point. In other
+ multibyte encodings the argument must designate
+ an <acronym class="acronym">ASCII</acronym> character. <code class="literal">chr(0)</code> is
+ disallowed because text data types cannot store that character.
+ </p>
+ <p>
+ <code class="literal">chr(65)</code>
+ → <code class="returnvalue">A</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">concat</code> ( <em class="parameter"><code>val1</code></em> <code class="type">"any"</code>
+ [, <em class="parameter"><code>val2</code></em> <code class="type">"any"</code> [, ...] ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Concatenates the text representations of all the arguments.
+ NULL arguments are ignored.
+ </p>
+ <p>
+ <code class="literal">concat('abcde', 2, NULL, 22)</code>
+ → <code class="returnvalue">abcde222</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">concat_ws</code> ( <em class="parameter"><code>sep</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>val1</code></em> <code class="type">"any"</code>
+ [, <em class="parameter"><code>val2</code></em> <code class="type">"any"</code> [, ...] ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Concatenates all but the first argument, with separators. The first
+ argument is used as the separator string, and should not be NULL.
+ Other NULL arguments are ignored.
+ </p>
+ <p>
+ <code class="literal">concat_ws(',', 'abcde', 2, NULL, 22)</code>
+ → <code class="returnvalue">abcde,2,22</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">format</code> ( <em class="parameter"><code>formatstr</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>formatarg</code></em> <code class="type">"any"</code> [, ...] ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Formats arguments according to a format string;
+ see <a class="xref" href="functions-string.html#FUNCTIONS-STRING-FORMAT" title="9.4.1. format">Section 9.4.1</a>.
+ This function is similar to the C function <code class="function">sprintf</code>.
+ </p>
+ <p>
+ <code class="literal">format('Hello %s, %1$s', 'World')</code>
+ → <code class="returnvalue">Hello World, World</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">initcap</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the first letter of each word to upper case and the
+ rest to lower case. Words are sequences of alphanumeric
+ characters separated by non-alphanumeric characters.
+ </p>
+ <p>
+ <code class="literal">initcap('hi THOMAS')</code>
+ → <code class="returnvalue">Hi Thomas</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">left</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns first <em class="parameter"><code>n</code></em> characters in the
+ string, or when <em class="parameter"><code>n</code></em> is negative, returns
+ all but last |<em class="parameter"><code>n</code></em>| characters.
+ </p>
+ <p>
+ <code class="literal">left('abcde', 2)</code>
+ → <code class="returnvalue">ab</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">length</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of characters in the string.
+ </p>
+ <p>
+ <code class="literal">length('jose')</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">lpad</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>length</code></em> <code class="type">integer</code>
+ [<span class="optional">, <em class="parameter"><code>fill</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extends the <em class="parameter"><code>string</code></em> to length
+ <em class="parameter"><code>length</code></em> by prepending the characters
+ <em class="parameter"><code>fill</code></em> (a space by default). If the
+ <em class="parameter"><code>string</code></em> is already longer than
+ <em class="parameter"><code>length</code></em> then it is truncated (on the right).
+ </p>
+ <p>
+ <code class="literal">lpad('hi', 5, 'xy')</code>
+ → <code class="returnvalue">xyxhi</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">ltrim</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>characters</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Removes the longest string containing only characters in
+ <em class="parameter"><code>characters</code></em> (a space by default) from the start of
+ <em class="parameter"><code>string</code></em>.
+ </p>
+ <p>
+ <code class="literal">ltrim('zzzytest', 'xyz')</code>
+ → <code class="returnvalue">test</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">md5</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Computes the MD5 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a> of
+ the argument, with the result written in hexadecimal.
+ </p>
+ <p>
+ <code class="literal">md5('abc')</code>
+ → <code class="returnvalue">900150983cd24fb0​d6963f7d28e17f72</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">parse_ident</code> ( <em class="parameter"><code>qualified_identifier</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>strict_mode</code></em> <code class="type">boolean</code> <code class="literal">DEFAULT</code> <code class="literal">true</code> ] )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Splits <em class="parameter"><code>qualified_identifier</code></em> into an array of
+ identifiers, removing any quoting of individual identifiers. By
+ default, extra characters after the last identifier are considered an
+ error; but if the second parameter is <code class="literal">false</code>, then such
+ extra characters are ignored. (This behavior is useful for parsing
+ names for objects like functions.) Note that this function does not
+ truncate over-length identifiers. If you want truncation you can cast
+ the result to <code class="type">name[]</code>.
+ </p>
+ <p>
+ <code class="literal">parse_ident('"SomeSchema".someTable')</code>
+ → <code class="returnvalue">{SomeSchema,sometable}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">pg_client_encoding</code> ( )
+ → <code class="returnvalue">name</code>
+ </p>
+ <p>
+ Returns current client encoding name.
+ </p>
+ <p>
+ <code class="literal">pg_client_encoding()</code>
+ → <code class="returnvalue">UTF8</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">quote_ident</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the given string suitably quoted to be used as an identifier
+ in an <acronym class="acronym">SQL</acronym> statement string.
+ 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 <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values in Dynamic Queries">Example 43.1</a>.
+ </p>
+ <p>
+ <code class="literal">quote_ident('Foo bar')</code>
+ → <code class="returnvalue">"Foo bar"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">quote_literal</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the given string suitably quoted to be used as a string literal
+ in an <acronym class="acronym">SQL</acronym> statement string.
+ Embedded single-quotes and backslashes are properly doubled.
+ Note that <code class="function">quote_literal</code> returns null on null
+ input; if the argument might be null,
+ <code class="function">quote_nullable</code> is often more suitable.
+ See also <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values in Dynamic Queries">Example 43.1</a>.
+ </p>
+ <p>
+ <code class="literal">quote_literal(E'O\'Reilly')</code>
+ → <code class="returnvalue">'O''Reilly'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">quote_literal</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the given value to text and then quotes it as a literal.
+ Embedded single-quotes and backslashes are properly doubled.
+ </p>
+ <p>
+ <code class="literal">quote_literal(42.5)</code>
+ → <code class="returnvalue">'42.5'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">quote_nullable</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the given string suitably quoted to be used as a string literal
+ in an <acronym class="acronym">SQL</acronym> statement string; or, if the argument
+ is null, returns <code class="literal">NULL</code>.
+ Embedded single-quotes and backslashes are properly doubled.
+ See also <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values in Dynamic Queries">Example 43.1</a>.
+ </p>
+ <p>
+ <code class="literal">quote_nullable(NULL)</code>
+ → <code class="returnvalue">NULL</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">quote_nullable</code> ( <code class="type">anyelement</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the given value to text and then quotes it as a literal;
+ or, if the argument is null, returns <code class="literal">NULL</code>.
+ Embedded single-quotes and backslashes are properly doubled.
+ </p>
+ <p>
+ <code class="literal">quote_nullable(42.5)</code>
+ → <code class="returnvalue">'42.5'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_count</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>start</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] ] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of times the POSIX regular
+ expression <em class="parameter"><code>pattern</code></em> matches in
+ the <em class="parameter"><code>string</code></em>; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_count('123456789012', '\d\d\d', 2)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_instr</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>start</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>N</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>endoption</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>subexpr</code></em> <code class="type">integer</code> ] ] ] ] ] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the position within <em class="parameter"><code>string</code></em> where
+ the <em class="parameter"><code>N</code></em>'th match of the POSIX regular
+ expression <em class="parameter"><code>pattern</code></em> occurs, or zero if there is
+ no such match; see <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i')</code>
+ → <code class="returnvalue">3</code>
+ </p>
+ <p>
+ <code class="literal">regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i', 2)</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_like</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Checks whether a match of the POSIX regular
+ expression <em class="parameter"><code>pattern</code></em> occurs
+ within <em class="parameter"><code>string</code></em>; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_like('Hello World', 'world$', 'i')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.24.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_match</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code> [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Returns substrings within the first match of the POSIX regular
+ expression <em class="parameter"><code>pattern</code></em> to
+ the <em class="parameter"><code>string</code></em>; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_match('foobarbequebaz', '(bar)(beque)')</code>
+ → <code class="returnvalue">{bar,beque}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_matches</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code> [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">setof text[]</code>
+ </p>
+ <p>
+ Returns substrings within the first match of the POSIX regular
+ expression <em class="parameter"><code>pattern</code></em> to
+ the <em class="parameter"><code>string</code></em>, or substrings within all
+ such matches if the <code class="literal">g</code> flag is used;
+ see <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_matches('foobarbequebaz', 'ba.', 'g')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ {bar}
+ {baz}
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.26.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_replace</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>, <em class="parameter"><code>replacement</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>start</code></em> <code class="type">integer</code> ]
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Replaces the substring that is the first match to the POSIX
+ regular expression <em class="parameter"><code>pattern</code></em>, or all such
+ matches if the <code class="literal">g</code> flag is used; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_replace('Thomas', '.[mN]a.', 'M')</code>
+ → <code class="returnvalue">ThM</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">regexp_replace</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>, <em class="parameter"><code>replacement</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>start</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>N</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Replaces the substring that is the <em class="parameter"><code>N</code></em>'th
+ match to the POSIX regular expression <em class="parameter"><code>pattern</code></em>,
+ or all such matches if <em class="parameter"><code>N</code></em> is zero; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_replace('Thomas', '.', 'X', 3, 2)</code>
+ → <code class="returnvalue">ThoXas</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.28.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_split_to_array</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code> [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Splits <em class="parameter"><code>string</code></em> using a POSIX regular
+ expression as the delimiter, producing an array of results; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_split_to_array('hello world', '\s+')</code>
+ → <code class="returnvalue">{hello,world}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.29.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_split_to_table</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code> [, <em class="parameter"><code>flags</code></em> <code class="type">text</code> ] )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Splits <em class="parameter"><code>string</code></em> using a POSIX regular
+ expression as the delimiter, producing a set of results; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_split_to_table('hello world', '\s+')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ hello
+ world
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.30.1.1.1" class="indexterm"></a>
+ <code class="function">regexp_substr</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>pattern</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>start</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>N</code></em> <code class="type">integer</code>
+ [, <em class="parameter"><code>flags</code></em> <code class="type">text</code>
+ [, <em class="parameter"><code>subexpr</code></em> <code class="type">integer</code> ] ] ] ] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the substring within <em class="parameter"><code>string</code></em> that
+ matches the <em class="parameter"><code>N</code></em>'th occurrence of the POSIX
+ regular expression <em class="parameter"><code>pattern</code></em>,
+ or <code class="literal">NULL</code> if there is no such match; see
+ <a class="xref" href="functions-matching.html#FUNCTIONS-POSIX-REGEXP" title="9.7.3. POSIX Regular Expressions">Section 9.7.3</a>.
+ </p>
+ <p>
+ <code class="literal">regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i')</code>
+ → <code class="returnvalue">CDEF</code>
+ </p>
+ <p>
+ <code class="literal">regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i', 2)</code>
+ → <code class="returnvalue">EF</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.31.1.1.1" class="indexterm"></a>
+ <code class="function">repeat</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>number</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Repeats <em class="parameter"><code>string</code></em> the specified
+ <em class="parameter"><code>number</code></em> of times.
+ </p>
+ <p>
+ <code class="literal">repeat('Pg', 4)</code>
+ → <code class="returnvalue">PgPgPgPg</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.32.1.1.1" class="indexterm"></a>
+ <code class="function">replace</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>from</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>to</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Replaces all occurrences in <em class="parameter"><code>string</code></em> of
+ substring <em class="parameter"><code>from</code></em> with
+ substring <em class="parameter"><code>to</code></em>.
+ </p>
+ <p>
+ <code class="literal">replace('abcdefabcdef', 'cd', 'XX')</code>
+ → <code class="returnvalue">abXXefabXXef</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.33.1.1.1" class="indexterm"></a>
+ <code class="function">reverse</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Reverses the order of the characters in the string.
+ </p>
+ <p>
+ <code class="literal">reverse('abcde')</code>
+ → <code class="returnvalue">edcba</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.34.1.1.1" class="indexterm"></a>
+ <code class="function">right</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns last <em class="parameter"><code>n</code></em> characters in the string,
+ or when <em class="parameter"><code>n</code></em> is negative, returns all but
+ first |<em class="parameter"><code>n</code></em>| characters.
+ </p>
+ <p>
+ <code class="literal">right('abcde', 2)</code>
+ → <code class="returnvalue">de</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.35.1.1.1" class="indexterm"></a>
+ <code class="function">rpad</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>length</code></em> <code class="type">integer</code>
+ [<span class="optional">, <em class="parameter"><code>fill</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extends the <em class="parameter"><code>string</code></em> to length
+ <em class="parameter"><code>length</code></em> by appending the characters
+ <em class="parameter"><code>fill</code></em> (a space by default). If the
+ <em class="parameter"><code>string</code></em> is already longer than
+ <em class="parameter"><code>length</code></em> then it is truncated.
+ </p>
+ <p>
+ <code class="literal">rpad('hi', 5, 'xy')</code>
+ → <code class="returnvalue">hixyx</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.36.1.1.1" class="indexterm"></a>
+ <code class="function">rtrim</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>characters</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Removes the longest string containing only characters in
+ <em class="parameter"><code>characters</code></em> (a space by default) from the end of
+ <em class="parameter"><code>string</code></em>.
+ </p>
+ <p>
+ <code class="literal">rtrim('testxxzx', 'xyz')</code>
+ → <code class="returnvalue">test</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.37.1.1.1" class="indexterm"></a>
+ <code class="function">split_part</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>delimiter</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Splits <em class="parameter"><code>string</code></em> at occurrences
+ of <em class="parameter"><code>delimiter</code></em> and returns
+ the <em class="parameter"><code>n</code></em>'th field (counting from one),
+ or when <em class="parameter"><code>n</code></em> is negative, returns
+ the |<em class="parameter"><code>n</code></em>|'th-from-last field.
+ </p>
+ <p>
+ <code class="literal">split_part('abc~@~def~@~ghi', '~@~', 2)</code>
+ → <code class="returnvalue">def</code>
+ </p>
+ <p>
+ <code class="literal">split_part('abc,def,ghi,jkl', ',', -2)</code>
+ → <code class="returnvalue">ghi</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.38.1.1.1" class="indexterm"></a>
+ <code class="function">starts_with</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>prefix</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns true if <em class="parameter"><code>string</code></em> starts
+ with <em class="parameter"><code>prefix</code></em>.
+ </p>
+ <p>
+ <code class="literal">starts_with('alphabet', 'alph')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="FUNCTION-STRING-TO-ARRAY" class="indexterm"></a>
+ <code class="function">string_to_array</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>delimiter</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>null_string</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Splits the <em class="parameter"><code>string</code></em> at occurrences
+ of <em class="parameter"><code>delimiter</code></em> and forms the resulting fields
+ into a <code class="type">text</code> array.
+ If <em class="parameter"><code>delimiter</code></em> is <code class="literal">NULL</code>,
+ each character in the <em class="parameter"><code>string</code></em> will become a
+ separate element in the array.
+ If <em class="parameter"><code>delimiter</code></em> is an empty string, then
+ the <em class="parameter"><code>string</code></em> is treated as a single field.
+ If <em class="parameter"><code>null_string</code></em> is supplied and is
+ not <code class="literal">NULL</code>, fields matching that string are
+ replaced by <code class="literal">NULL</code>.
+ See also <a class="link" href="functions-array.html#FUNCTION-ARRAY-TO-STRING"><code class="function">array_to_string</code></a>.
+ </p>
+ <p>
+ <code class="literal">string_to_array('xx~~yy~~zz', '~~', 'yy')</code>
+ → <code class="returnvalue">{xx,NULL,zz}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.40.1.1.1" class="indexterm"></a>
+ <code class="function">string_to_table</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>delimiter</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>null_string</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Splits the <em class="parameter"><code>string</code></em> at occurrences
+ of <em class="parameter"><code>delimiter</code></em> and returns the resulting fields
+ as a set of <code class="type">text</code> rows.
+ If <em class="parameter"><code>delimiter</code></em> is <code class="literal">NULL</code>,
+ each character in the <em class="parameter"><code>string</code></em> will become a
+ separate row of the result.
+ If <em class="parameter"><code>delimiter</code></em> is an empty string, then
+ the <em class="parameter"><code>string</code></em> is treated as a single field.
+ If <em class="parameter"><code>null_string</code></em> is supplied and is
+ not <code class="literal">NULL</code>, fields matching that string are
+ replaced by <code class="literal">NULL</code>.
+ </p>
+ <p>
+ <code class="literal">string_to_table('xx~^~yy~^~zz', '~^~', 'yy')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ xx
+ NULL
+ zz
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.41.1.1.1" class="indexterm"></a>
+ <code class="function">strpos</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>substring</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns first starting index of the specified <em class="parameter"><code>substring</code></em>
+ within <em class="parameter"><code>string</code></em>, or zero if it's not present.
+ (Same as <code class="literal">position(<em class="parameter"><code>substring</code></em> in
+ <em class="parameter"><code>string</code></em>)</code>, but note the reversed
+ argument order.)
+ </p>
+ <p>
+ <code class="literal">strpos('high', 'ig')</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.42.1.1.1" class="indexterm"></a>
+ <code class="function">substr</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional">, <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Extracts the substring of <em class="parameter"><code>string</code></em> starting at
+ the <em class="parameter"><code>start</code></em>'th character,
+ and extending for <em class="parameter"><code>count</code></em> characters if that is
+ specified. (Same
+ as <code class="literal">substring(<em class="parameter"><code>string</code></em>
+ from <em class="parameter"><code>start</code></em>
+ for <em class="parameter"><code>count</code></em>)</code>.)
+ </p>
+ <p>
+ <code class="literal">substr('alphabet', 3)</code>
+ → <code class="returnvalue">phabet</code>
+ </p>
+ <p>
+ <code class="literal">substr('alphabet', 3, 2)</code>
+ → <code class="returnvalue">ph</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.43.1.1.1" class="indexterm"></a>
+ <code class="function">to_ascii</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">to_ascii</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>encoding</code></em> <code class="type">name</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">to_ascii</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>encoding</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts <em class="parameter"><code>string</code></em> to <acronym class="acronym">ASCII</acronym>
+ from another encoding, which may be identified by name or number.
+ If <em class="parameter"><code>encoding</code></em> is omitted the database encoding
+ is assumed (which in practice is the only useful case).
+ The conversion consists primarily of dropping accents.
+ Conversion is only supported
+ from <code class="literal">LATIN1</code>, <code class="literal">LATIN2</code>,
+ <code class="literal">LATIN9</code>, and <code class="literal">WIN1250</code> encodings.
+ (See the <a class="xref" href="unaccent.html" title="F.48. unaccent">unaccent</a> module for another, more flexible
+ solution.)
+ </p>
+ <p>
+ <code class="literal">to_ascii('Karél')</code>
+ → <code class="returnvalue">Karel</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.44.1.1.1" class="indexterm"></a>
+ <code class="function">to_hex</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">to_hex</code> ( <code class="type">bigint</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Converts the number to its equivalent hexadecimal representation.
+ </p>
+ <p>
+ <code class="literal">to_hex(2147483647)</code>
+ → <code class="returnvalue">7fffffff</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.45.1.1.1" class="indexterm"></a>
+ <code class="function">translate</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>from</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>to</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Replaces each character in <em class="parameter"><code>string</code></em> that
+ matches a character in the <em class="parameter"><code>from</code></em> set with the
+ corresponding character in the <em class="parameter"><code>to</code></em>
+ set. If <em class="parameter"><code>from</code></em> is longer than
+ <em class="parameter"><code>to</code></em>, occurrences of the extra characters in
+ <em class="parameter"><code>from</code></em> are deleted.
+ </p>
+ <p>
+ <code class="literal">translate('12345', '143', 'ax')</code>
+ → <code class="returnvalue">a2x5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.10.7.2.2.46.1.1.1" class="indexterm"></a>
+ <code class="function">unistr</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Evaluate escaped Unicode characters in the argument. Unicode characters
+ can be specified as
+ <code class="literal">\<em class="replaceable"><code>XXXX</code></em></code> (4 hexadecimal
+ digits), <code class="literal">\+<em class="replaceable"><code>XXXXXX</code></em></code> (6
+ hexadecimal digits),
+ <code class="literal">\u<em class="replaceable"><code>XXXX</code></em></code> (4 hexadecimal
+ digits), or <code class="literal">\U<em class="replaceable"><code>XXXXXXXX</code></em></code>
+ (8 hexadecimal digits). To specify a backslash, write two
+ backslashes. All other characters are taken literally.
+ </p>
+
+ <p>
+ If the server encoding is not UTF-8, the Unicode code point identified
+ by one of these escape sequences is converted to the actual server
+ encoding; an error is reported if that's not possible.
+ </p>
+
+ <p>
+ This function provides a (non-standard) alternative to string
+ constants with Unicode escapes (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-UESCAPE" title="4.1.2.3. String Constants with Unicode Escapes">Section 4.1.2.3</a>).
+ </p>
+
+ <p>
+ <code class="literal">unistr('d\0061t\+000061')</code>
+ → <code class="returnvalue">data</code>
+ </p>
+ <p>
+ <code class="literal">unistr('d\u0061t\U00000061')</code>
+ → <code class="returnvalue">data</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="function">concat</code>, <code class="function">concat_ws</code> and
+ <code class="function">format</code> functions are variadic, so it is possible to
+ pass the values to be concatenated or formatted as an array marked with
+ the <code class="literal">VARIADIC</code> keyword (see <a class="xref" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS" title="38.5.6. SQL Functions with Variable Numbers of Arguments">Section 38.5.6</a>). The array's elements are
+ treated as if they were separate ordinary arguments to the function.
+ If the variadic array argument is NULL, <code class="function">concat</code>
+ and <code class="function">concat_ws</code> return NULL, but
+ <code class="function">format</code> treats a NULL as a zero-element array.
+ </p><p>
+ See also the aggregate function <code class="function">string_agg</code> in
+ <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a>, and the functions for
+ converting between strings and the <code class="type">bytea</code> type in
+ <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-CONVERSIONS" title="Table 9.13. Text/Binary String Conversion Functions">Table 9.13</a>.
+ </p><div class="sect2" id="FUNCTIONS-STRING-FORMAT"><div class="titlepage"><div><div><h3 class="title">9.4.1. <code class="function">format</code></h3></div></div></div><a id="id-1.5.8.10.10.2" class="indexterm"></a><p>
+ The function <code class="function">format</code> produces output formatted according to
+ a format string, in a style similar to the C function
+ <code class="function">sprintf</code>.
+ </p><p>
+</p><pre class="synopsis">
+<code class="function">format</code>(<em class="parameter"><code>formatstr</code></em> <code class="type">text</code> [, <em class="parameter"><code>formatarg</code></em> <code class="type">"any"</code> [, ...] ])
+</pre><p>
+ <em class="parameter"><code>formatstr</code></em> is a format string that specifies how the
+ result should be formatted. Text in the format string is copied
+ directly to the result, except where <em class="firstterm">format specifiers</em> are
+ used. Format specifiers act as placeholders in the string, defining how
+ subsequent function arguments should be formatted and inserted into the
+ result. Each <em class="parameter"><code>formatarg</code></em> argument is converted to text
+ according to the usual output rules for its data type, and then formatted
+ and inserted into the result string according to the format specifier(s).
+ </p><p>
+ Format specifiers are introduced by a <code class="literal">%</code> character and have
+ the form
+</p><pre class="synopsis">
+%[<em class="parameter"><code>position</code></em>][<em class="parameter"><code>flags</code></em>][<em class="parameter"><code>width</code></em>]<em class="parameter"><code>type</code></em>
+</pre><p>
+ where the component fields are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>position</code></em> (optional)</span></dt><dd><p>
+ A string of the form <code class="literal"><em class="parameter"><code>n</code></em>$</code> where
+ <em class="parameter"><code>n</code></em> is the index of the argument to print.
+ Index 1 means the first argument after
+ <em class="parameter"><code>formatstr</code></em>. If the <em class="parameter"><code>position</code></em> is
+ omitted, the default is to use the next argument in sequence.
+ </p></dd><dt><span class="term"><em class="parameter"><code>flags</code></em> (optional)</span></dt><dd><p>
+ Additional options controlling how the format specifier's output is
+ formatted. Currently the only supported flag is a minus sign
+ (<code class="literal">-</code>) which will cause the format specifier's output to be
+ left-justified. This has no effect unless the <em class="parameter"><code>width</code></em>
+ field is also specified.
+ </p></dd><dt><span class="term"><em class="parameter"><code>width</code></em> (optional)</span></dt><dd><p>
+ Specifies the <span class="emphasis"><em>minimum</em></span> number of characters to use to
+ display the format specifier's output. The output is padded on the
+ left or right (depending on the <code class="literal">-</code> flag) with spaces as
+ needed to fill the width. A too-small width does not cause
+ truncation of the output, but is simply ignored. The width may be
+ specified using any of the following: a positive integer; an
+ asterisk (<code class="literal">*</code>) to use the next function argument as the
+ width; or a string of the form <code class="literal">*<em class="parameter"><code>n</code></em>$</code> to
+ use the <em class="parameter"><code>n</code></em>th function argument as the width.
+ </p><p>
+ If the width comes from a function argument, that argument is
+ consumed before the argument that is used for the format specifier's
+ value. If the width argument is negative, the result is left
+ aligned (as if the <code class="literal">-</code> flag had been specified) within a
+ field of length <code class="function">abs</code>(<em class="parameter"><code>width</code></em>).
+ </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em> (required)</span></dt><dd><p>
+ The type of format conversion to use to produce the format
+ specifier's output. The following types are supported:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">s</code> formats the argument value as a simple
+ string. A null value is treated as an empty string.
+ </p></li><li class="listitem"><p>
+ <code class="literal">I</code> treats the argument value as an SQL
+ identifier, double-quoting it if necessary.
+ It is an error for the value to be null (equivalent to
+ <code class="function">quote_ident</code>).
+ </p></li><li class="listitem"><p>
+ <code class="literal">L</code> quotes the argument value as an SQL literal.
+ A null value is displayed as the string <code class="literal">NULL</code>, without
+ quotes (equivalent to <code class="function">quote_nullable</code>).
+ </p></li></ul></div><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ In addition to the format specifiers described above, the special sequence
+ <code class="literal">%%</code> may be used to output a literal <code class="literal">%</code> character.
+ </p><p>
+ Here are some examples of the basic format conversions:
+
+</p><pre class="screen">
+SELECT format('Hello %s', 'World');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">Hello World</code>
+
+SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">Testing one, two, three, %</code>
+
+SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">INSERT INTO "Foo bar" VALUES('O''Reilly')</code>
+
+SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">INSERT INTO locations VALUES('C:\Program Files')</code>
+</pre><p>
+ </p><p>
+ Here are examples using <em class="parameter"><code>width</code></em> fields
+ and the <code class="literal">-</code> flag:
+
+</p><pre class="screen">
+SELECT format('|%10s|', 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">| foo|</code>
+
+SELECT format('|%-10s|', 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">|foo |</code>
+
+SELECT format('|%*s|', 10, 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">| foo|</code>
+
+SELECT format('|%*s|', -10, 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">|foo |</code>
+
+SELECT format('|%-*s|', 10, 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">|foo |</code>
+
+SELECT format('|%-*s|', -10, 'foo');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">|foo |</code>
+</pre><p>
+ </p><p>
+ These examples show use of <em class="parameter"><code>position</code></em> fields:
+
+</p><pre class="screen">
+SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">Testing three, two, one</code>
+
+SELECT format('|%*2$s|', 'foo', 10, 'bar');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">| bar|</code>
+
+SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">| foo|</code>
+</pre><p>
+ </p><p>
+ Unlike the standard C function <code class="function">sprintf</code>,
+ <span class="productname">PostgreSQL</span>'s <code class="function">format</code> function allows format
+ specifiers with and without <em class="parameter"><code>position</code></em> fields to be mixed
+ in the same format string. A format specifier without a
+ <em class="parameter"><code>position</code></em> field always uses the next argument after the
+ last argument consumed.
+ In addition, the <code class="function">format</code> function does not require all
+ function arguments to be used in the format string.
+ For example:
+
+</p><pre class="screen">
+SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
+<em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">Testing three, two, three</code>
+</pre><p>
+ </p><p>
+ The <code class="literal">%I</code> and <code class="literal">%L</code> format specifiers are particularly
+ useful for safely constructing dynamic SQL statements. See
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values in Dynamic Queries">Example 43.1</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-math.html" title="9.3. Mathematical Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-binarystring.html" title="9.5. Binary String Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.3. Mathematical Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.5. Binary String Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-subquery.html b/doc/src/sgml/html/functions-subquery.html
new file mode 100644
index 0000000..addb6f2
--- /dev/null
+++ b/doc/src/sgml/html/functions-subquery.html
@@ -0,0 +1,213 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.23. Subquery Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-window.html" title="9.22. Window Functions" /><link rel="next" href="functions-comparisons.html" title="9.24. Row and Array Comparisons" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.23. Subquery Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-window.html" title="9.22. Window Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-SUBQUERY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.23. Subquery Expressions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-EXISTS">9.23.1. <code class="literal">EXISTS</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-IN">9.23.2. <code class="literal">IN</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-NOTIN">9.23.3. <code class="literal">NOT IN</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-ANY-SOME">9.23.4. <code class="literal">ANY</code>/<code class="literal">SOME</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-ALL">9.23.5. <code class="literal">ALL</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#id-1.5.8.29.15">9.23.6. Single-Row Comparison</a></span></dt></dl></div><a id="id-1.5.8.29.2" class="indexterm"></a><a id="id-1.5.8.29.3" class="indexterm"></a><a id="id-1.5.8.29.4" class="indexterm"></a><a id="id-1.5.8.29.5" class="indexterm"></a><a id="id-1.5.8.29.6" class="indexterm"></a><a id="id-1.5.8.29.7" class="indexterm"></a><a id="id-1.5.8.29.8" class="indexterm"></a><p>
+ This section describes the <acronym class="acronym">SQL</acronym>-compliant subquery
+ expressions available in <span class="productname">PostgreSQL</span>.
+ All of the expression forms documented in this section return
+ Boolean (true/false) results.
+ </p><div class="sect2" id="FUNCTIONS-SUBQUERY-EXISTS"><div class="titlepage"><div><div><h3 class="title">9.23.1. <code class="literal">EXISTS</code></h3></div></div></div><pre class="synopsis">
+EXISTS (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The argument of <code class="token">EXISTS</code> is an arbitrary <code class="command">SELECT</code> statement,
+ or <em class="firstterm">subquery</em>. The
+ subquery is evaluated to determine whether it returns any rows.
+ If it returns at least one row, the result of <code class="token">EXISTS</code> is
+ <span class="quote">“<span class="quote">true</span>”</span>; if the subquery returns no rows, the result of <code class="token">EXISTS</code>
+ is <span class="quote">“<span class="quote">false</span>”</span>.
+ </p><p>
+ The subquery can refer to variables from the surrounding query,
+ which will act as constants during any one evaluation of the subquery.
+ </p><p>
+ The subquery will generally only be executed long enough to determine
+ whether at least one row is returned, not all the way to completion.
+ It is unwise to write a subquery that has side effects (such as
+ calling sequence functions); whether the side effects occur
+ might be unpredictable.
+ </p><p>
+ Since the result depends only on whether any rows are returned,
+ and not on the contents of those rows, the output list of the
+ subquery is normally unimportant. A common coding convention is
+ to write all <code class="literal">EXISTS</code> tests in the form
+ <code class="literal">EXISTS(SELECT 1 WHERE ...)</code>. There are exceptions to
+ this rule however, such as subqueries that use <code class="token">INTERSECT</code>.
+ </p><p>
+ This simple example is like an inner join on <code class="literal">col2</code>, but
+ it produces at most one output row for each <code class="literal">tab1</code> row,
+ even if there are several matching <code class="literal">tab2</code> rows:
+</p><pre class="screen">
+SELECT col1
+FROM tab1
+WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
+</pre><p>
+ </p></div><div class="sect2" id="FUNCTIONS-SUBQUERY-IN"><div class="titlepage"><div><div><h3 class="title">9.23.2. <code class="literal">IN</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> IN (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized
+ subquery, which must return exactly one column. The left-hand expression
+ is evaluated and compared to each row of the subquery result.
+ The result of <code class="token">IN</code> is <span class="quote">“<span class="quote">true</span>”</span> if any equal subquery row is found.
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if no equal row is found (including the
+ case where the subquery returns no rows).
+ </p><p>
+ Note that if the left-hand expression yields null, or if there are
+ no equal right-hand values and at least one right-hand row yields
+ null, the result of the <code class="token">IN</code> construct will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p><p>
+ As with <code class="token">EXISTS</code>, it's unwise to assume that the subquery will
+ be evaluated completely.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> IN (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The left-hand side of this form of <code class="token">IN</code> is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ 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
+ evaluated and compared row-wise to each row of the subquery result.
+ The result of <code class="token">IN</code> is <span class="quote">“<span class="quote">true</span>”</span> if any equal subquery row is found.
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if no equal row is found (including the
+ case where the subquery returns no rows).
+ </p><p>
+ As usual, null values in the rows are combined per
+ the normal rules of SQL Boolean expressions. Two rows are considered
+ equal if all their corresponding members are non-null and equal; the rows
+ are unequal if any corresponding members are non-null and unequal;
+ otherwise the result of that row comparison is unknown (null).
+ If all the per-row results are either unequal or null, with at least one
+ null, then the result of <code class="token">IN</code> is null.
+ </p></div><div class="sect2" id="FUNCTIONS-SUBQUERY-NOTIN"><div class="titlepage"><div><div><h3 class="title">9.23.3. <code class="literal">NOT IN</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> NOT IN (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized
+ subquery, which must return exactly one column. The left-hand expression
+ is evaluated and compared to each row of the subquery result.
+ The result of <code class="token">NOT IN</code> is <span class="quote">“<span class="quote">true</span>”</span> if only unequal subquery rows
+ are found (including the case where the subquery returns no rows).
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if any equal row is found.
+ </p><p>
+ Note that if the left-hand expression yields null, or if there are
+ no equal right-hand values and at least one right-hand row yields
+ null, the result of the <code class="token">NOT IN</code> construct will be null, not true.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p><p>
+ As with <code class="token">EXISTS</code>, it's unwise to assume that the subquery will
+ be evaluated completely.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> NOT IN (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The left-hand side of this form of <code class="token">NOT IN</code> is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ 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
+ evaluated and compared row-wise to each row of the subquery result.
+ The result of <code class="token">NOT IN</code> is <span class="quote">“<span class="quote">true</span>”</span> if only unequal subquery rows
+ are found (including the case where the subquery returns no rows).
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if any equal row is found.
+ </p><p>
+ As usual, null values in the rows are combined per
+ the normal rules of SQL Boolean expressions. Two rows are considered
+ equal if all their corresponding members are non-null and equal; the rows
+ are unequal if any corresponding members are non-null and unequal;
+ otherwise the result of that row comparison is unknown (null).
+ If all the per-row results are either unequal or null, with at least one
+ null, then the result of <code class="token">NOT IN</code> is null.
+ </p></div><div class="sect2" id="FUNCTIONS-SUBQUERY-ANY-SOME"><div class="titlepage"><div><div><h3 class="title">9.23.4. <code class="literal">ANY</code>/<code class="literal">SOME</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> ANY (<em class="replaceable"><code>subquery</code></em>)
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> SOME (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized
+ subquery, which must return exactly one column. The left-hand expression
+ is evaluated and compared to each row of the subquery result using the
+ given <em class="replaceable"><code>operator</code></em>, which must yield a Boolean
+ result.
+ The result of <code class="token">ANY</code> is <span class="quote">“<span class="quote">true</span>”</span> if any true result is obtained.
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if no true result is found (including the
+ case where the subquery returns no rows).
+ </p><p>
+ <code class="token">SOME</code> is a synonym for <code class="token">ANY</code>.
+ <code class="token">IN</code> is equivalent to <code class="literal">= ANY</code>.
+ </p><p>
+ Note that if there are no successes and at least one right-hand row yields
+ null for the operator's result, the result of the <code class="token">ANY</code> construct
+ will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+ </p><p>
+ As with <code class="token">EXISTS</code>, it's unwise to assume that the subquery will
+ be evaluated completely.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> <em class="replaceable"><code>operator</code></em> ANY (<em class="replaceable"><code>subquery</code></em>)
+<em class="replaceable"><code>row_constructor</code></em> <em class="replaceable"><code>operator</code></em> SOME (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The left-hand side of this form of <code class="token">ANY</code> is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ 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
+ evaluated and compared row-wise to each row of the subquery result,
+ using the given <em class="replaceable"><code>operator</code></em>.
+ The result of <code class="token">ANY</code> is <span class="quote">“<span class="quote">true</span>”</span> if the comparison
+ returns true for any subquery row.
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if the comparison returns false for every
+ subquery row (including the case where the subquery returns no
+ rows).
+ The result is NULL if no comparison with a subquery row returns true,
+ and at least one comparison returns NULL.
+ </p><p>
+ See <a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a> for details about the meaning
+ of a row constructor comparison.
+ </p></div><div class="sect2" id="FUNCTIONS-SUBQUERY-ALL"><div class="titlepage"><div><div><h3 class="title">9.23.5. <code class="literal">ALL</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> ALL (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The right-hand side is a parenthesized
+ subquery, which must return exactly one column. The left-hand expression
+ is evaluated and compared to each row of the subquery result using the
+ given <em class="replaceable"><code>operator</code></em>, which must yield a Boolean
+ result.
+ The result of <code class="token">ALL</code> is <span class="quote">“<span class="quote">true</span>”</span> if all rows yield true
+ (including the case where the subquery returns no rows).
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if any false result is found.
+ The result is NULL if no comparison with a subquery row returns false,
+ and at least one comparison returns NULL.
+ </p><p>
+ <code class="token">NOT IN</code> is equivalent to <code class="literal">&lt;&gt; ALL</code>.
+ </p><p>
+ As with <code class="token">EXISTS</code>, it's unwise to assume that the subquery will
+ be evaluated completely.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> <em class="replaceable"><code>operator</code></em> ALL (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The left-hand side of this form of <code class="token">ALL</code> is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ 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
+ evaluated and compared row-wise to each row of the subquery result,
+ using the given <em class="replaceable"><code>operator</code></em>.
+ The result of <code class="token">ALL</code> is <span class="quote">“<span class="quote">true</span>”</span> if the comparison
+ returns true for all subquery rows (including the
+ case where the subquery returns no rows).
+ The result is <span class="quote">“<span class="quote">false</span>”</span> if the comparison returns false for any
+ subquery row.
+ The result is NULL if no comparison with a subquery row returns false,
+ and at least one comparison returns NULL.
+ </p><p>
+ See <a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a> for details about the meaning
+ of a row constructor comparison.
+ </p></div><div class="sect2" id="id-1.5.8.29.15"><div class="titlepage"><div><div><h3 class="title">9.23.6. Single-Row Comparison</h3></div></div></div><a id="id-1.5.8.29.15.2" class="indexterm"></a><pre class="synopsis">
+<em class="replaceable"><code>row_constructor</code></em> <em class="replaceable"><code>operator</code></em> (<em class="replaceable"><code>subquery</code></em>)
+</pre><p>
+ The left-hand side is a row constructor,
+ as described in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ 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,
+ the result is taken to be null.) The left-hand side is evaluated and
+ compared row-wise to the single subquery result row.
+ </p><p>
+ See <a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a> for details about the meaning
+ of a row constructor comparison.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-window.html" title="9.22. Window Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.22. Window Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.24. Row and Array Comparisons</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-textsearch.html b/doc/src/sgml/html/functions-textsearch.html
new file mode 100644
index 0000000..5dd4f66
--- /dev/null
+++ b/doc/src/sgml/html/functions-textsearch.html
@@ -0,0 +1,763 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.13. Text Search Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-net.html" title="9.12. Network Address Functions and Operators" /><link rel="next" href="functions-uuid.html" title="9.14. UUID Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.13. Text Search Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-net.html" title="9.12. Network Address Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-uuid.html" title="9.14. UUID Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-TEXTSEARCH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.13. Text Search Functions and Operators</h2></div></div></div><a id="id-1.5.8.19.2" class="indexterm"></a><a id="id-1.5.8.19.3" class="indexterm"></a><p>
+ <a class="xref" href="functions-textsearch.html#TEXTSEARCH-OPERATORS-TABLE" title="Table 9.42. Text Search Operators">Table 9.42</a>,
+ <a class="xref" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-TABLE" title="Table 9.43. Text Search Functions">Table 9.43</a> and
+ <a class="xref" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-DEBUG-TABLE" title="Table 9.44. Text Search Debugging Functions">Table 9.44</a>
+ summarize the functions and operators that are provided
+ for full text searching. See <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for a detailed
+ explanation of <span class="productname">PostgreSQL</span>'s text search
+ facility.
+ </p><div class="table" id="TEXTSEARCH-OPERATORS-TABLE"><p class="title"><strong>Table 9.42. Text Search Operators</strong></p><div class="table-contents"><table class="table" summary="Text Search Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsvector</code> <code class="literal">@@</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">@@</code> <code class="type">tsvector</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">tsvector</code> match <code class="type">tsquery</code>?
+ (The arguments can be given in either order.)
+ </p>
+ <p>
+ <code class="literal">to_tsvector('fat cats ate rats') @@ to_tsquery('cat &amp; rat')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">@@</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does text string, after implicit invocation
+ of <code class="function">to_tsvector()</code>, match <code class="type">tsquery</code>?
+ </p>
+ <p>
+ <code class="literal">'fat cats ate rats' @@ to_tsquery('cat &amp; rat')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsvector</code> <code class="literal">@@@</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">@@@</code> <code class="type">tsvector</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ This is a deprecated synonym for <code class="literal">@@</code>.
+ </p>
+ <p>
+ <code class="literal">to_tsvector('fat cats ate rats') @@@ to_tsquery('cat &amp; rat')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsvector</code> <code class="literal">||</code> <code class="type">tsvector</code>
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Concatenates two <code class="type">tsvector</code>s. If both inputs contain
+ lexeme positions, the second input's positions are adjusted
+ accordingly.
+ </p>
+ <p>
+ <code class="literal">'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</code>
+ → <code class="returnvalue">'a':1 'b':2,5 'c':3 'd':4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">&amp;&amp;</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ ANDs two <code class="type">tsquery</code>s together, producing a query that
+ matches documents that match both input queries.
+ </p>
+ <p>
+ <code class="literal">'fat | rat'::tsquery &amp;&amp; 'cat'::tsquery</code>
+ → <code class="returnvalue">( 'fat' | 'rat' ) &amp; 'cat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">||</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ ORs two <code class="type">tsquery</code>s together, producing a query that
+ matches documents that match either input query.
+ </p>
+ <p>
+ <code class="literal">'fat | rat'::tsquery || 'cat'::tsquery</code>
+ → <code class="returnvalue">'fat' | 'rat' | 'cat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">!!</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Negates a <code class="type">tsquery</code>, producing a query that matches
+ documents that do not match the input query.
+ </p>
+ <p>
+ <code class="literal">!! 'cat'::tsquery</code>
+ → <code class="returnvalue">!'cat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">&lt;-&gt;</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Constructs a phrase query, which matches if the two input queries
+ match at successive lexemes.
+ </p>
+ <p>
+ <code class="literal">to_tsquery('fat') &lt;-&gt; to_tsquery('rat')</code>
+ → <code class="returnvalue">'fat' &lt;-&gt; 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">@&gt;</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does first <code class="type">tsquery</code> contain the second? (This considers
+ only whether all the lexemes appearing in one query appear in the
+ other, ignoring the combining operators.)
+ </p>
+ <p>
+ <code class="literal">'cat'::tsquery @&gt; 'cat &amp; rat'::tsquery</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">tsquery</code> <code class="literal">&lt;@</code> <code class="type">tsquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is first <code class="type">tsquery</code> contained in the second? (This
+ considers only whether all the lexemes appearing in one query appear
+ in the other, ignoring the combining operators.)
+ </p>
+ <p>
+ <code class="literal">'cat'::tsquery &lt;@ 'cat &amp; rat'::tsquery</code>
+ → <code class="returnvalue">t</code>
+ </p>
+ <p>
+ <code class="literal">'cat'::tsquery &lt;@ '!cat &amp; rat'::tsquery</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In addition to these specialized operators, the usual comparison
+ operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are
+ available for types <code class="type">tsvector</code> and <code class="type">tsquery</code>.
+ These are not very
+ useful for text searching but allow, for example, unique indexes to be
+ built on columns of these types.
+ </p><div class="table" id="TEXTSEARCH-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.43. Text Search Functions</strong></p><div class="table-contents"><table class="table" summary="Text Search Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">array_to_tsvector</code> ( <code class="type">text[]</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Converts an array of text strings to a <code class="type">tsvector</code>.
+ The given strings are used as lexemes as-is, without further
+ processing. Array elements must not be empty strings
+ or <code class="literal">NULL</code>.
+ </p>
+ <p>
+ <code class="literal">array_to_tsvector('{fat,cat,rat}'::text[])</code>
+ → <code class="returnvalue">'cat' 'fat' 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">get_current_ts_config</code> ( )
+ → <code class="returnvalue">regconfig</code>
+ </p>
+ <p>
+ Returns the OID of the current default text search configuration
+ (as set by <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a>).
+ </p>
+ <p>
+ <code class="literal">get_current_ts_config()</code>
+ → <code class="returnvalue">english</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">length</code> ( <code class="type">tsvector</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of lexemes in the <code class="type">tsvector</code>.
+ </p>
+ <p>
+ <code class="literal">length('fat:2,4 cat:3 rat:5A'::tsvector)</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">numnode</code> ( <code class="type">tsquery</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of lexemes plus operators in
+ the <code class="type">tsquery</code>.
+ </p>
+ <p>
+ <code class="literal">numnode('(fat &amp; rat) | cat'::tsquery)</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">plainto_tsquery</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Converts text to a <code class="type">tsquery</code>, normalizing words according to
+ the specified or default configuration. Any punctuation in the string
+ is ignored (it does not determine query operators). The resulting
+ query matches documents containing all non-stopwords in the text.
+ </p>
+ <p>
+ <code class="literal">plainto_tsquery('english', 'The Fat Rats')</code>
+ → <code class="returnvalue">'fat' &amp; 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">phraseto_tsquery</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Converts text to a <code class="type">tsquery</code>, normalizing words according to
+ the specified or default configuration. Any punctuation in the string
+ is ignored (it does not determine query operators). The resulting
+ query matches phrases containing all non-stopwords in the text.
+ </p>
+ <p>
+ <code class="literal">phraseto_tsquery('english', 'The Fat Rats')</code>
+ → <code class="returnvalue">'fat' &lt;-&gt; 'rat'</code>
+ </p>
+ <p>
+ <code class="literal">phraseto_tsquery('english', 'The Cat and Rats')</code>
+ → <code class="returnvalue">'cat' &lt;2&gt; 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">websearch_to_tsquery</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Converts text to a <code class="type">tsquery</code>, normalizing words according
+ to the specified or default configuration. Quoted word sequences are
+ converted to phrase tests. The word <span class="quote">“<span class="quote">or</span>”</span> is understood
+ as producing an OR operator, and a dash produces a NOT operator;
+ other punctuation is ignored.
+ This approximates the behavior of some common web search tools.
+ </p>
+ <p>
+ <code class="literal">websearch_to_tsquery('english', '"fat rat" or cat dog')</code>
+ → <code class="returnvalue">'fat' &lt;-&gt; 'rat' | 'cat' &amp; 'dog'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">querytree</code> ( <code class="type">tsquery</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Produces a representation of the indexable portion of
+ a <code class="type">tsquery</code>. A result that is empty or
+ just <code class="literal">T</code> indicates a non-indexable query.
+ </p>
+ <p>
+ <code class="literal">querytree('foo &amp; ! bar'::tsquery)</code>
+ → <code class="returnvalue">'foo'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">setweight</code> ( <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>, <em class="parameter"><code>weight</code></em> <code class="type">"char"</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Assigns the specified <em class="parameter"><code>weight</code></em> to each element
+ of the <em class="parameter"><code>vector</code></em>.
+ </p>
+ <p>
+ <code class="literal">setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</code>
+ → <code class="returnvalue">'cat':3A 'fat':2A,4A 'rat':5A</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">setweight</code> ( <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>, <em class="parameter"><code>weight</code></em> <code class="type">"char"</code>, <em class="parameter"><code>lexemes</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Assigns the specified <em class="parameter"><code>weight</code></em> to elements
+ of the <em class="parameter"><code>vector</code></em> that are listed
+ in <em class="parameter"><code>lexemes</code></em>.
+ The strings in <em class="parameter"><code>lexemes</code></em> are taken as lexemes
+ as-is, without further processing. Strings that do not match any
+ lexeme in <em class="parameter"><code>vector</code></em> are ignored.
+ </p>
+ <p>
+ <code class="literal">setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}')</code>
+ → <code class="returnvalue">'cat':3A 'fat':2,4 'rat':5A,6A</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">strip</code> ( <code class="type">tsvector</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Removes positions and weights from the <code class="type">tsvector</code>.
+ </p>
+ <p>
+ <code class="literal">strip('fat:2,4 cat:3 rat:5A'::tsvector)</code>
+ → <code class="returnvalue">'cat' 'fat' 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">to_tsquery</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Converts text to a <code class="type">tsquery</code>, normalizing words according to
+ the specified or default configuration. The words must be combined
+ by valid <code class="type">tsquery</code> operators.
+ </p>
+ <p>
+ <code class="literal">to_tsquery('english', 'The &amp; Fat &amp; Rats')</code>
+ → <code class="returnvalue">'fat' &amp; 'rat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">to_tsvector</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Converts text to a <code class="type">tsvector</code>, normalizing words according
+ to the specified or default configuration. Position information is
+ included in the result.
+ </p>
+ <p>
+ <code class="literal">to_tsvector('english', 'The Fat Rats')</code>
+ → <code class="returnvalue">'fat':2 'rat':3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">to_tsvector</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">json</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">to_tsvector</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">jsonb</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Converts each string value in the JSON document to
+ a <code class="type">tsvector</code>, normalizing words according to the specified
+ or default configuration. The results are then concatenated in
+ document order to produce the output. Position information is
+ generated as though one stopword exists between each pair of string
+ values. (Beware that <span class="quote">“<span class="quote">document order</span>”</span> of the fields of a
+ JSON object is implementation-dependent when the input
+ is <code class="type">jsonb</code>; observe the difference in the examples.)
+ </p>
+ <p>
+ <code class="literal">to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json)</code>
+ → <code class="returnvalue">'dog':5 'fat':2 'rat':3</code>
+ </p>
+ <p>
+ <code class="literal">to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb)</code>
+ → <code class="returnvalue">'dog':1 'fat':4 'rat':5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">json_to_tsvector</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">json</code>,
+ <em class="parameter"><code>filter</code></em> <code class="type">jsonb</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.15.1.2.1" class="indexterm"></a>
+ <code class="function">jsonb_to_tsvector</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">jsonb</code>,
+ <em class="parameter"><code>filter</code></em> <code class="type">jsonb</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Selects each item in the JSON document that is requested by
+ the <em class="parameter"><code>filter</code></em> and converts each one to
+ a <code class="type">tsvector</code>, normalizing words according to the specified
+ or default configuration. The results are then concatenated in
+ document order to produce the output. Position information is
+ generated as though one stopword exists between each pair of selected
+ items. (Beware that <span class="quote">“<span class="quote">document order</span>”</span> of the fields of a
+ JSON object is implementation-dependent when the input
+ is <code class="type">jsonb</code>.)
+ The <em class="parameter"><code>filter</code></em> must be a <code class="type">jsonb</code>
+ array containing zero or more of these keywords:
+ <code class="literal">"string"</code> (to include all string values),
+ <code class="literal">"numeric"</code> (to include all numeric values),
+ <code class="literal">"boolean"</code> (to include all boolean values),
+ <code class="literal">"key"</code> (to include all keys), or
+ <code class="literal">"all"</code> (to include all the above).
+ As a special case, the <em class="parameter"><code>filter</code></em> can also be a
+ simple JSON value that is one of these keywords.
+ </p>
+ <p>
+ <code class="literal">json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]')</code>
+ → <code class="returnvalue">'123':5 'fat':2 'rat':3</code>
+ </p>
+ <p>
+ <code class="literal">json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"')</code>
+ → <code class="returnvalue">'123':9 'cat':1 'dog':7 'fat':4 'rat':5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">ts_delete</code> ( <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>, <em class="parameter"><code>lexeme</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Removes any occurrence of the given <em class="parameter"><code>lexeme</code></em>
+ from the <em class="parameter"><code>vector</code></em>.
+ The <em class="parameter"><code>lexeme</code></em> string is treated as a lexeme as-is,
+ without further processing.
+ </p>
+ <p>
+ <code class="literal">ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')</code>
+ → <code class="returnvalue">'cat':3 'rat':5A</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ts_delete</code> ( <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>, <em class="parameter"><code>lexemes</code></em> <code class="type">text[]</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Removes any occurrences of the lexemes
+ in <em class="parameter"><code>lexemes</code></em>
+ from the <em class="parameter"><code>vector</code></em>.
+ The strings in <em class="parameter"><code>lexemes</code></em> are taken as lexemes
+ as-is, without further processing. Strings that do not match any
+ lexeme in <em class="parameter"><code>vector</code></em> are ignored.
+ </p>
+ <p>
+ <code class="literal">ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])</code>
+ → <code class="returnvalue">'cat':3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">ts_filter</code> ( <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>, <em class="parameter"><code>weights</code></em> <code class="type">"char"[]</code> )
+ → <code class="returnvalue">tsvector</code>
+ </p>
+ <p>
+ Selects only elements with the given <em class="parameter"><code>weights</code></em>
+ from the <em class="parameter"><code>vector</code></em>.
+ </p>
+ <p>
+ <code class="literal">ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}')</code>
+ → <code class="returnvalue">'cat':3B 'rat':5A</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">ts_headline</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>
+ [<span class="optional">, <em class="parameter"><code>options</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Displays, in an abbreviated form, the match(es) for
+ the <em class="parameter"><code>query</code></em> in
+ the <em class="parameter"><code>document</code></em>, which must be raw text not
+ a <code class="type">tsvector</code>. Words in the document are normalized
+ according to the specified or default configuration before matching to
+ the query. Use of this function is discussed in
+ <a class="xref" href="textsearch-controls.html#TEXTSEARCH-HEADLINE" title="12.3.4. Highlighting Results">Section 12.3.4</a>, which also describes the
+ available <em class="parameter"><code>options</code></em>.
+ </p>
+ <p>
+ <code class="literal">ts_headline('The fat cat ate the rat.', 'cat')</code>
+ → <code class="returnvalue">The fat &lt;b&gt;cat&lt;/b&gt; ate the rat.</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ts_headline</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">json</code>,
+ <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>
+ [<span class="optional">, <em class="parameter"><code>options</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">ts_headline</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">jsonb</code>,
+ <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>
+ [<span class="optional">, <em class="parameter"><code>options</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Displays, in an abbreviated form, match(es) for
+ the <em class="parameter"><code>query</code></em> that occur in string values
+ within the JSON <em class="parameter"><code>document</code></em>.
+ See <a class="xref" href="textsearch-controls.html#TEXTSEARCH-HEADLINE" title="12.3.4. Highlighting Results">Section 12.3.4</a> for more details.
+ </p>
+ <p>
+ <code class="literal">ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat')</code>
+ → <code class="returnvalue">{"cat": "raining &lt;b&gt;cats&lt;/b&gt; and dogs"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.21.1.1.1" class="indexterm"></a>
+ <code class="function">ts_rank</code> (
+ [<span class="optional"> <em class="parameter"><code>weights</code></em> <code class="type">real[]</code>, </span>]
+ <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>,
+ <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>
+ [<span class="optional">, <em class="parameter"><code>normalization</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Computes a score showing how well
+ the <em class="parameter"><code>vector</code></em> matches
+ the <em class="parameter"><code>query</code></em>. See
+ <a class="xref" href="textsearch-controls.html#TEXTSEARCH-RANKING" title="12.3.3. Ranking Search Results">Section 12.3.3</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_rank(to_tsvector('raining cats and dogs'), 'cat')</code>
+ → <code class="returnvalue">0.06079271</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">ts_rank_cd</code> (
+ [<span class="optional"> <em class="parameter"><code>weights</code></em> <code class="type">real[]</code>, </span>]
+ <em class="parameter"><code>vector</code></em> <code class="type">tsvector</code>,
+ <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>
+ [<span class="optional">, <em class="parameter"><code>normalization</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Computes a score showing how well
+ the <em class="parameter"><code>vector</code></em> matches
+ the <em class="parameter"><code>query</code></em>, using a cover density
+ algorithm. See <a class="xref" href="textsearch-controls.html#TEXTSEARCH-RANKING" title="12.3.3. Ranking Search Results">Section 12.3.3</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat')</code>
+ → <code class="returnvalue">0.1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.23.1.1.1" class="indexterm"></a>
+ <code class="function">ts_rewrite</code> ( <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>,
+ <em class="parameter"><code>target</code></em> <code class="type">tsquery</code>,
+ <em class="parameter"><code>substitute</code></em> <code class="type">tsquery</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Replaces occurrences of <em class="parameter"><code>target</code></em>
+ with <em class="parameter"><code>substitute</code></em>
+ within the <em class="parameter"><code>query</code></em>.
+ See <a class="xref" href="textsearch-features.html#TEXTSEARCH-QUERY-REWRITING" title="12.4.2.1. Query Rewriting">Section 12.4.2.1</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_rewrite('a &amp; b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</code>
+ → <code class="returnvalue">'b' &amp; ( 'foo' | 'bar' )</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ts_rewrite</code> ( <em class="parameter"><code>query</code></em> <code class="type">tsquery</code>,
+ <em class="parameter"><code>select</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Replaces portions of the <em class="parameter"><code>query</code></em> according to
+ target(s) and substitute(s) obtained by executing
+ a <code class="command">SELECT</code> command.
+ See <a class="xref" href="textsearch-features.html#TEXTSEARCH-QUERY-REWRITING" title="12.4.2.1. Query Rewriting">Section 12.4.2.1</a> for details.
+ </p>
+ <p>
+ <code class="literal">SELECT ts_rewrite('a &amp; b'::tsquery, 'SELECT t,s FROM aliases')</code>
+ → <code class="returnvalue">'b' &amp; ( 'foo' | 'bar' )</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.25.1.1.1" class="indexterm"></a>
+ <code class="function">tsquery_phrase</code> ( <em class="parameter"><code>query1</code></em> <code class="type">tsquery</code>, <em class="parameter"><code>query2</code></em> <code class="type">tsquery</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Constructs a phrase query that searches
+ for matches of <em class="parameter"><code>query1</code></em>
+ and <em class="parameter"><code>query2</code></em> at successive lexemes (same
+ as <code class="literal">&lt;-&gt;</code> operator).
+ </p>
+ <p>
+ <code class="literal">tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))</code>
+ → <code class="returnvalue">'fat' &lt;-&gt; 'cat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">tsquery_phrase</code> ( <em class="parameter"><code>query1</code></em> <code class="type">tsquery</code>, <em class="parameter"><code>query2</code></em> <code class="type">tsquery</code>, <em class="parameter"><code>distance</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">tsquery</code>
+ </p>
+ <p>
+ Constructs a phrase query that searches
+ for matches of <em class="parameter"><code>query1</code></em> and
+ <em class="parameter"><code>query2</code></em> that occur exactly
+ <em class="parameter"><code>distance</code></em> lexemes apart.
+ </p>
+ <p>
+ <code class="literal">tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</code>
+ → <code class="returnvalue">'fat' &lt;10&gt; 'cat'</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.27.1.1.1" class="indexterm"></a>
+ <code class="function">tsvector_to_array</code> ( <code class="type">tsvector</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Converts a <code class="type">tsvector</code> to an array of lexemes.
+ </p>
+ <p>
+ <code class="literal">tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)</code>
+ → <code class="returnvalue">{cat,fat,rat}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.7.2.2.28.1.1.1" class="indexterm"></a>
+ <code class="function">unnest</code> ( <code class="type">tsvector</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>lexeme</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>positions</code></em> <code class="type">smallint[]</code>,
+ <em class="parameter"><code>weights</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Expands a <code class="type">tsvector</code> into a set of rows, one per lexeme.
+ </p>
+ <p>
+ <code class="literal">select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector)</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ lexeme | positions | weights
+--------+-----------+---------
+ cat | {3} | {D}
+ fat | {2,4} | {D,D}
+ rat | {5} | {A}
+</pre><p>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ All the text search functions that accept an optional <code class="type">regconfig</code>
+ argument will use the configuration specified by
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a>
+ when that argument is omitted.
+ </p></div><p>
+ The functions in
+ <a class="xref" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-DEBUG-TABLE" title="Table 9.44. Text Search Debugging Functions">Table 9.44</a>
+ are listed separately because they are not usually used in everyday text
+ searching operations. They are primarily helpful for development and
+ debugging of new text search configurations.
+ </p><div class="table" id="TEXTSEARCH-FUNCTIONS-DEBUG-TABLE"><p class="title"><strong>Table 9.44. Text Search Debugging Functions</strong></p><div class="table-contents"><table class="table" summary="Text Search Debugging Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.10.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">ts_debug</code> (
+ [<span class="optional"> <em class="parameter"><code>config</code></em> <code class="type">regconfig</code>, </span>]
+ <em class="parameter"><code>document</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>alias</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>description</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>token</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>dictionaries</code></em> <code class="type">regdictionary[]</code>,
+ <em class="parameter"><code>dictionary</code></em> <code class="type">regdictionary</code>,
+ <em class="parameter"><code>lexemes</code></em> <code class="type">text[]</code> )
+ </p>
+ <p>
+ Extracts and normalizes tokens from
+ the <em class="parameter"><code>document</code></em> according to the specified or
+ default text search configuration, and returns information about how
+ each token was processed.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-CONFIGURATION-TESTING" title="12.8.1. Configuration Testing">Section 12.8.1</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_debug('english', 'The Brightest supernovaes')</code>
+ → <code class="returnvalue">(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.10.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">ts_lexize</code> ( <em class="parameter"><code>dict</code></em> <code class="type">regdictionary</code>, <em class="parameter"><code>token</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Returns an array of replacement lexemes if the input token is known to
+ the dictionary, or an empty array if the token is known to the
+ dictionary but it is a stop word, or NULL if it is not a known word.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-DICTIONARY-TESTING" title="12.8.3. Dictionary Testing">Section 12.8.3</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_lexize('english_stem', 'stars')</code>
+ → <code class="returnvalue">{star}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.10.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">ts_parse</code> ( <em class="parameter"><code>parser_name</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>document</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>tokid</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>token</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Extracts tokens from the <em class="parameter"><code>document</code></em> using the
+ named parser.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING" title="12.8.2. Parser Testing">Section 12.8.2</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_parse('default', 'foo - bar')</code>
+ → <code class="returnvalue">(1,foo) ...</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ts_parse</code> ( <em class="parameter"><code>parser_oid</code></em> <code class="type">oid</code>,
+ <em class="parameter"><code>document</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>tokid</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>token</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Extracts tokens from the <em class="parameter"><code>document</code></em> using a
+ parser specified by OID.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING" title="12.8.2. Parser Testing">Section 12.8.2</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_parse(3722, 'foo - bar')</code>
+ → <code class="returnvalue">(1,foo) ...</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.10.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">ts_token_type</code> ( <em class="parameter"><code>parser_name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>tokid</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>alias</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>description</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns a table that describes each type of token the named parser can
+ recognize.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING" title="12.8.2. Parser Testing">Section 12.8.2</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_token_type('default')</code>
+ → <code class="returnvalue">(1,asciiword,"Word, all ASCII") ...</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ts_token_type</code> ( <em class="parameter"><code>parser_oid</code></em> <code class="type">oid</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>tokid</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>alias</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>description</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Returns a table that describes each type of token a parser specified
+ by OID can recognize.
+ See <a class="xref" href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING" title="12.8.2. Parser Testing">Section 12.8.2</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_token_type(3722)</code>
+ → <code class="returnvalue">(1,asciiword,"Word, all ASCII") ...</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.19.10.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">ts_stat</code> ( <em class="parameter"><code>sqlquery</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>weights</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>word</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>ndoc</code></em> <code class="type">integer</code>,
+ <em class="parameter"><code>nentry</code></em> <code class="type">integer</code> )
+ </p>
+ <p>
+ Executes the <em class="parameter"><code>sqlquery</code></em>, which must return a
+ single <code class="type">tsvector</code> column, and returns statistics about each
+ distinct lexeme contained in the data.
+ See <a class="xref" href="textsearch-features.html#TEXTSEARCH-STATISTICS" title="12.4.4. Gathering Document Statistics">Section 12.4.4</a> for details.
+ </p>
+ <p>
+ <code class="literal">ts_stat('SELECT vector FROM apod')</code>
+ → <code class="returnvalue">(foo,10,15) ...</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-net.html" title="9.12. Network Address Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-uuid.html" title="9.14. UUID Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.12. Network Address Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.14. UUID Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-trigger.html b/doc/src/sgml/html/functions-trigger.html
new file mode 100644
index 0000000..a631e94
--- /dev/null
+++ b/doc/src/sgml/html/functions-trigger.html
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.28. Trigger Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-admin.html" title="9.27. System Administration Functions" /><link rel="next" href="functions-event-triggers.html" title="9.29. Event Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.28. Trigger Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-admin.html" title="9.27. System Administration Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.28. Trigger Functions</h2></div></div></div><p>
+ While many uses of triggers involve user-written trigger functions,
+ <span class="productname">PostgreSQL</span> provides a few built-in trigger
+ functions that can be used directly in user-defined triggers. These
+ are summarized in <a class="xref" href="functions-trigger.html#BUILTIN-TRIGGERS-TABLE" title="Table 9.101. Built-In Trigger Functions">Table 9.101</a>.
+ (Additional built-in trigger functions exist, which implement foreign
+ key constraints and deferred index constraints. Those are not documented
+ here since users need not use them directly.)
+ </p><p>
+ For more information about creating triggers, see
+ <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>.
+ </p><div class="table" id="BUILTIN-TRIGGERS-TABLE"><p class="title"><strong>Table 9.101. Built-In Trigger Functions</strong></p><div class="table-contents"><table class="table" summary="Built-In Trigger Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example Usage
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.34.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">suppress_redundant_updates_trigger</code> ( )
+ → <code class="returnvalue">trigger</code>
+ </p>
+ <p>
+ Suppresses do-nothing update operations. See below for details.
+ </p>
+ <p>
+ <code class="literal">CREATE TRIGGER ... suppress_redundant_updates_trigger()</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.34.4.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">tsvector_update_trigger</code> ( )
+ → <code class="returnvalue">trigger</code>
+ </p>
+ <p>
+ Automatically updates a <code class="type">tsvector</code> column from associated
+ plain-text document column(s). The text search configuration to use
+ is specified by name as a trigger argument. See
+ <a class="xref" href="textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS" title="12.4.3. Triggers for Automatic Updates">Section 12.4.3</a> for details.
+ </p>
+ <p>
+ <code class="literal">CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.34.4.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">tsvector_update_trigger_column</code> ( )
+ → <code class="returnvalue">trigger</code>
+ </p>
+ <p>
+ Automatically updates a <code class="type">tsvector</code> column from associated
+ plain-text document column(s). The text search configuration to use
+ is taken from a <code class="type">regconfig</code> column of the table. See
+ <a class="xref" href="textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS" title="12.4.3. Triggers for Automatic Updates">Section 12.4.3</a> for details.
+ </p>
+ <p>
+ <code class="literal">CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="function">suppress_redundant_updates_trigger</code> function,
+ when applied as a row-level <code class="literal">BEFORE UPDATE</code> trigger,
+ will prevent any update that does not actually change the data in the
+ row from taking place. This overrides the normal behavior which always
+ performs a physical row update
+ regardless of whether or not the data has changed. (This normal behavior
+ makes updates run faster, since no checking is required, and is also
+ useful in certain cases.)
+ </p><p>
+ Ideally, you should avoid running updates that don't actually
+ change the data in the record. Redundant updates can cost considerable
+ unnecessary time, especially if there are lots of indexes to alter,
+ and space in dead rows that will eventually have to be vacuumed.
+ However, detecting such situations in client code is not
+ always easy, or even possible, and writing expressions to detect
+ them can be error-prone. An alternative is to use
+ <code class="function">suppress_redundant_updates_trigger</code>, which will skip
+ updates that don't change the data. You should use this with care,
+ however. The trigger takes a small but non-trivial time for each record,
+ so if most of the records affected by updates do actually change,
+ use of this trigger will make updates run slower on average.
+ </p><p>
+ The <code class="function">suppress_redundant_updates_trigger</code> function can be
+ added to a table like this:
+</p><pre class="programlisting">
+CREATE TRIGGER z_min_update
+BEFORE UPDATE ON tablename
+FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
+</pre><p>
+ In most cases, you need to fire this trigger last for each row, so that
+ it does not override other triggers that might wish to alter the row.
+ Bearing in mind that triggers fire in name order, you would therefore
+ choose a trigger name that comes after the name of any other trigger
+ you might have on the table. (Hence the <span class="quote">“<span class="quote">z</span>”</span> prefix in the
+ example.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-admin.html" title="9.27. System Administration Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-event-triggers.html" title="9.29. Event Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.27. System Administration Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.29. Event Trigger Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-uuid.html b/doc/src/sgml/html/functions-uuid.html
new file mode 100644
index 0000000..57e46a2
--- /dev/null
+++ b/doc/src/sgml/html/functions-uuid.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.14. UUID Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators" /><link rel="next" href="functions-xml.html" title="9.15. XML Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.14. UUID Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-xml.html" title="9.15. XML Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-UUID"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.14. UUID Functions</h2></div></div></div><a id="id-1.5.8.20.2" class="indexterm"></a><a id="id-1.5.8.20.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> includes one function to generate a UUID:
+</p><pre class="synopsis">
+<code class="function">gen_random_uuid</code> () → <code class="returnvalue">uuid</code>
+</pre><p>
+ This function returns a version 4 (random) UUID. This is the most commonly
+ used type of UUID and is appropriate for most applications.
+ </p><p>
+ The <a class="xref" href="uuid-ossp.html" title="F.49. uuid-ossp">uuid-ossp</a> module provides additional functions that
+ implement other standard algorithms for generating UUIDs.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also provides the usual comparison
+ operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> for
+ UUIDs.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-xml.html" title="9.15. XML Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.13. Text Search Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.15. XML Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-window.html b/doc/src/sgml/html/functions-window.html
new file mode 100644
index 0000000..0e4f272
--- /dev/null
+++ b/doc/src/sgml/html/functions-window.html
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.22. Window Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-aggregate.html" title="9.21. Aggregate Functions" /><link rel="next" href="functions-subquery.html" title="9.23. Subquery Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.22. Window Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-aggregate.html" title="9.21. Aggregate Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-subquery.html" title="9.23. Subquery Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-WINDOW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.22. Window Functions</h2></div></div></div><a id="id-1.5.8.28.2" class="indexterm"></a><p>
+ <em class="firstterm">Window functions</em> provide the ability to perform
+ calculations across sets of rows that are related to the current query
+ row. See <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a> for an introduction to this
+ feature, and <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a> for syntax
+ details.
+ </p><p>
+ The built-in window functions are listed in
+ <a class="xref" href="functions-window.html#FUNCTIONS-WINDOW-TABLE" title="Table 9.63. General-Purpose Window Functions">Table 9.63</a>. Note that these functions
+ <span class="emphasis"><em>must</em></span> be invoked using window function syntax, i.e., an
+ <code class="literal">OVER</code> clause is required.
+ </p><p>
+ In addition to these functions, any built-in or user-defined
+ ordinary aggregate (i.e., not ordered-set or hypothetical-set aggregates)
+ can be used as a window function; see
+ <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> for a list of the built-in aggregates.
+ Aggregate functions act as window functions only when an <code class="literal">OVER</code>
+ clause follows the call; otherwise they act as plain aggregates
+ and return a single row for the entire set.
+ </p><div class="table" id="FUNCTIONS-WINDOW-TABLE"><p class="title"><strong>Table 9.63. General-Purpose Window Functions</strong></p><div class="table-contents"><table class="table" summary="General-Purpose Window Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">row_number</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the number of the current row within its partition, counting
+ from 1.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">rank</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the rank of the current row, with gaps; that is,
+ the <code class="function">row_number</code> of the first row in its peer
+ group.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">dense_rank</code> ()
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the rank of the current row, without gaps; this function
+ effectively counts peer groups.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">percent_rank</code> ()
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Returns the relative rank of the current row, that is
+ (<code class="function">rank</code> - 1) / (total partition rows - 1).
+ The value thus ranges from 0 to 1 inclusive.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">cume_dist</code> ()
+ → <code class="returnvalue">double precision</code>
+ </p>
+ <p>
+ Returns the cumulative distribution, that is (number of partition rows
+ preceding or peers with current row) / (total partition rows).
+ The value thus ranges from 1/<em class="parameter"><code>N</code></em> to 1.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">ntile</code> ( <em class="parameter"><code>num_buckets</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns an integer ranging from 1 to the argument value, dividing the
+ partition as equally as possible.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">lag</code> ( <em class="parameter"><code>value</code></em> <code class="type">anycompatible</code>
+ [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">integer</code>
+ [<span class="optional">, <em class="parameter"><code>default</code></em> <code class="type">anycompatible</code> </span>]</span>] )
+ → <code class="returnvalue">anycompatible</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>value</code></em> evaluated at
+ the row that is <em class="parameter"><code>offset</code></em>
+ rows before the current row within the partition; if there is no such
+ row, instead returns <em class="parameter"><code>default</code></em>
+ (which must be of a type compatible with
+ <em class="parameter"><code>value</code></em>).
+ Both <em class="parameter"><code>offset</code></em> and
+ <em class="parameter"><code>default</code></em> are evaluated
+ with respect to the current row. If omitted,
+ <em class="parameter"><code>offset</code></em> defaults to 1 and
+ <em class="parameter"><code>default</code></em> to <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">lead</code> ( <em class="parameter"><code>value</code></em> <code class="type">anycompatible</code>
+ [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">integer</code>
+ [<span class="optional">, <em class="parameter"><code>default</code></em> <code class="type">anycompatible</code> </span>]</span>] )
+ → <code class="returnvalue">anycompatible</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>value</code></em> evaluated at
+ the row that is <em class="parameter"><code>offset</code></em>
+ rows after the current row within the partition; if there is no such
+ row, instead returns <em class="parameter"><code>default</code></em>
+ (which must be of a type compatible with
+ <em class="parameter"><code>value</code></em>).
+ Both <em class="parameter"><code>offset</code></em> and
+ <em class="parameter"><code>default</code></em> are evaluated
+ with respect to the current row. If omitted,
+ <em class="parameter"><code>offset</code></em> defaults to 1 and
+ <em class="parameter"><code>default</code></em> to <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">first_value</code> ( <em class="parameter"><code>value</code></em> <code class="type">anyelement</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>value</code></em> evaluated
+ at the row that is the first row of the window frame.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">last_value</code> ( <em class="parameter"><code>value</code></em> <code class="type">anyelement</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>value</code></em> evaluated
+ at the row that is the last row of the window frame.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.5.8.28.6.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">nth_value</code> ( <em class="parameter"><code>value</code></em> <code class="type">anyelement</code>, <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Returns <em class="parameter"><code>value</code></em> evaluated
+ at the row that is the <em class="parameter"><code>n</code></em>'th
+ row of the window frame (counting from 1);
+ returns <code class="literal">NULL</code> if there is no such row.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ All of the functions listed in
+ <a class="xref" href="functions-window.html#FUNCTIONS-WINDOW-TABLE" title="Table 9.63. General-Purpose Window Functions">Table 9.63</a> depend on the sort ordering
+ specified by the <code class="literal">ORDER BY</code> clause of the associated window
+ definition. Rows that are not distinct when considering only the
+ <code class="literal">ORDER BY</code> columns are said to be <em class="firstterm">peers</em>.
+ The four ranking functions (including <code class="function">cume_dist</code>) are
+ defined so that they give the same answer for all rows of a peer group.
+ </p><p>
+ Note that <code class="function">first_value</code>, <code class="function">last_value</code>, and
+ <code class="function">nth_value</code> consider only the rows within the <span class="quote">“<span class="quote">window
+ frame</span>”</span>, which by default contains the rows from the start of the
+ partition through the last peer of the current row. This is
+ likely to give unhelpful results for <code class="function">last_value</code> and
+ sometimes also <code class="function">nth_value</code>. You can redefine the frame by
+ adding a suitable frame specification (<code class="literal">RANGE</code>,
+ <code class="literal">ROWS</code> or <code class="literal">GROUPS</code>) to
+ the <code class="literal">OVER</code> clause.
+ See <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a> for more information
+ about frame specifications.
+ </p><p>
+ When an aggregate function is used as a window function, it aggregates
+ over the rows within the current row's window frame.
+ An aggregate used with <code class="literal">ORDER BY</code> and the default window frame
+ definition produces a <span class="quote">“<span class="quote">running sum</span>”</span> type of behavior, which may or
+ may not be what's wanted. To obtain
+ aggregation over the whole partition, omit <code class="literal">ORDER BY</code> or use
+ <code class="literal">ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</code>.
+ Other frame specifications can be used to obtain other effects.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The SQL standard defines a <code class="literal">RESPECT NULLS</code> or
+ <code class="literal">IGNORE NULLS</code> option for <code class="function">lead</code>, <code class="function">lag</code>,
+ <code class="function">first_value</code>, <code class="function">last_value</code>, and
+ <code class="function">nth_value</code>. This is not implemented in
+ <span class="productname">PostgreSQL</span>: the behavior is always the
+ same as the standard's default, namely <code class="literal">RESPECT NULLS</code>.
+ Likewise, the standard's <code class="literal">FROM FIRST</code> or <code class="literal">FROM LAST</code>
+ option for <code class="function">nth_value</code> is not implemented: only the
+ default <code class="literal">FROM FIRST</code> behavior is supported. (You can achieve
+ the result of <code class="literal">FROM LAST</code> by reversing the <code class="literal">ORDER BY</code>
+ ordering.)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-aggregate.html" title="9.21. Aggregate Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-subquery.html" title="9.23. Subquery Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.21. Aggregate Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.23. Subquery Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions-xml.html b/doc/src/sgml/html/functions-xml.html
new file mode 100644
index 0000000..86bc911
--- /dev/null
+++ b/doc/src/sgml/html/functions-xml.html
@@ -0,0 +1,912 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.15. XML Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-uuid.html" title="9.14. UUID Functions" /><link rel="next" href="functions-json.html" title="9.16. JSON Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.15. XML Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-uuid.html" title="9.14. UUID Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-json.html" title="9.16. JSON Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.15. XML Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-PRODUCING-XML">9.15.1. Producing XML Content</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PREDICATES">9.15.2. XML Predicates</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PROCESSING">9.15.3. Processing XML</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-MAPPING">9.15.4. Mapping Tables to XML</a></span></dt></dl></div><a id="id-1.5.8.21.2" class="indexterm"></a><p>
+ The functions and function-like expressions described in this
+ section operate on values of type <code class="type">xml</code>. See <a class="xref" href="datatype-xml.html" title="8.13. XML Type">Section 8.13</a> for information about the <code class="type">xml</code>
+ type. The function-like expressions <code class="function">xmlparse</code>
+ and <code class="function">xmlserialize</code> for converting to and from
+ type <code class="type">xml</code> are documented there, not in this section.
+ </p><p>
+ Use of most of these functions
+ requires <span class="productname">PostgreSQL</span> to have been built
+ with <code class="command">configure --with-libxml</code>.
+ </p><div class="sect2" id="FUNCTIONS-PRODUCING-XML"><div class="titlepage"><div><div><h3 class="title">9.15.1. Producing XML Content</h3></div></div></div><p>
+ A set of functions and function-like expressions is available for
+ producing XML content from SQL data. As such, they are
+ particularly suitable for formatting query results into XML
+ documents for processing in client applications.
+ </p><div class="sect3" id="id-1.5.8.21.5.3"><div class="titlepage"><div><div><h4 class="title">9.15.1.1. <code class="literal">xmlcomment</code></h4></div></div></div><a id="id-1.5.8.21.5.3.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlcomment</code> ( <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The function <code class="function">xmlcomment</code> creates an XML value
+ containing an XML comment with the specified text as content.
+ The text cannot contain <span class="quote">“<span class="quote"><code class="literal">--</code></span>”</span> or end with a
+ <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span>, otherwise the resulting construct
+ would not be a valid XML comment.
+ If the argument is null, the result is null.
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xmlcomment('hello');
+
+ xmlcomment
+--------------
+ &lt;!--hello--&gt;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.5.8.21.5.4"><div class="titlepage"><div><div><h4 class="title">9.15.1.2. <code class="literal">xmlconcat</code></h4></div></div></div><a id="id-1.5.8.21.5.4.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlconcat</code> ( <code class="type">xml</code> [<span class="optional">, ...</span>] ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The function <code class="function">xmlconcat</code> concatenates a list
+ of individual XML values to create a single value containing an
+ XML content fragment. Null values are omitted; the result is
+ only null if there are no nonnull arguments.
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xmlconcat('&lt;abc/&gt;', '&lt;bar&gt;foo&lt;/bar&gt;');
+
+ xmlconcat
+----------------------
+ &lt;abc/&gt;&lt;bar&gt;foo&lt;/bar&gt;
+</pre><p>
+ </p><p>
+ XML declarations, if present, are combined as follows. If all
+ argument values have the same XML version declaration, that
+ version is used in the result, else no version is used. If all
+ argument values have the standalone declaration value
+ <span class="quote">“<span class="quote">yes</span>”</span>, then that value is used in the result. If
+ all argument values have a standalone declaration value and at
+ least one is <span class="quote">“<span class="quote">no</span>”</span>, then that is used in the result.
+ Else the result will have no standalone declaration. If the
+ result is determined to require a standalone declaration but no
+ version declaration, a version declaration with version 1.0 will
+ be used because XML requires an XML declaration to contain a
+ version declaration. Encoding declarations are ignored and
+ removed in all cases.
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xmlconcat('&lt;?xml version="1.1"?&gt;&lt;foo/&gt;', '&lt;?xml version="1.1" standalone="no"?&gt;&lt;bar/&gt;');
+
+ xmlconcat
+-----------------------------------
+ &lt;?xml version="1.1"?&gt;&lt;foo/&gt;&lt;bar/&gt;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.5.8.21.5.5"><div class="titlepage"><div><div><h4 class="title">9.15.1.3. <code class="literal">xmlelement</code></h4></div></div></div><a id="id-1.5.8.21.5.5.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlelement</code> ( <code class="literal">NAME</code> <em class="replaceable"><code>name</code></em> [<span class="optional">, <code class="literal">XMLATTRIBUTES</code> ( <em class="replaceable"><code>attvalue</code></em> [<span class="optional"> <code class="literal">AS</code> <em class="replaceable"><code>attname</code></em> </span>] [<span class="optional">, ...</span>] ) </span>] [<span class="optional">, <em class="replaceable"><code>content</code></em> [<span class="optional">, ...</span>]</span>] ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The <code class="function">xmlelement</code> expression produces an XML
+ element with the given name, attributes, and content.
+ The <em class="replaceable"><code>name</code></em>
+ and <em class="replaceable"><code>attname</code></em> items shown in the syntax are
+ simple identifiers, not values. The <em class="replaceable"><code>attvalue</code></em>
+ and <em class="replaceable"><code>content</code></em> items are expressions, which can
+ yield any <span class="productname">PostgreSQL</span> data type. The
+ argument(s) within <code class="literal">XMLATTRIBUTES</code> generate attributes
+ of the XML element; the <em class="replaceable"><code>content</code></em> value(s) are
+ concatenated to form its content.
+ </p><p>
+ Examples:
+</p><pre class="screen">
+SELECT xmlelement(name foo);
+
+ xmlelement
+------------
+ &lt;foo/&gt;
+
+SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
+
+ xmlelement
+------------------
+ &lt;foo bar="xyz"/&gt;
+
+SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
+
+ xmlelement
+-------------------------------------
+ &lt;foo bar="2007-01-26"&gt;content&lt;/foo&gt;
+</pre><p>
+ </p><p>
+ Element and attribute names that are not valid XML names are
+ escaped by replacing the offending characters by the sequence
+ <code class="literal">_x<em class="replaceable"><code>HHHH</code></em>_</code>, where
+ <em class="replaceable"><code>HHHH</code></em> is the character's Unicode
+ codepoint in hexadecimal notation. For example:
+</p><pre class="screen">
+SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&amp;b"));
+
+ xmlelement
+----------------------------------
+ &lt;foo_x0024_bar a_x0026_b="xyz"/&gt;
+</pre><p>
+ </p><p>
+ An explicit attribute name need not be specified if the attribute
+ value is a column reference, in which case the column's name will
+ be used as the attribute name by default. In other cases, the
+ attribute must be given an explicit name. So this example is
+ valid:
+</p><pre class="screen">
+CREATE TABLE test (a xml, b xml);
+SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
+</pre><p>
+ But these are not:
+</p><pre class="screen">
+SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
+SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
+</pre><p>
+ </p><p>
+ Element content, if specified, will be formatted according to
+ its data type. If the content is itself of type <code class="type">xml</code>,
+ complex XML documents can be constructed. For example:
+</p><pre class="screen">
+SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
+ xmlelement(name abc),
+ xmlcomment('test'),
+ xmlelement(name xyz));
+
+ xmlelement
+----------------------------------------------
+ &lt;foo bar="xyz"&gt;&lt;abc/&gt;&lt;!--test--&gt;&lt;xyz/&gt;&lt;/foo&gt;
+</pre><p>
+
+ Content of other types will be formatted into valid XML character
+ data. This means in particular that the characters &lt;, &gt;,
+ and &amp; will be converted to entities. Binary data (data type
+ <code class="type">bytea</code>) will be represented in base64 or hex
+ encoding, depending on the setting of the configuration parameter
+ <a class="xref" href="runtime-config-client.html#GUC-XMLBINARY">xmlbinary</a>. The particular behavior for
+ individual data types is expected to evolve in order to align the
+ PostgreSQL mappings with those specified in SQL:2006 and later,
+ as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-CASTS" title="D.3.1.3. Mappings between SQL and XML Data Types and Values">Section D.3.1.3</a>.
+ </p></div><div class="sect3" id="id-1.5.8.21.5.6"><div class="titlepage"><div><div><h4 class="title">9.15.1.4. <code class="literal">xmlforest</code></h4></div></div></div><a id="id-1.5.8.21.5.6.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlforest</code> ( <em class="replaceable"><code>content</code></em> [<span class="optional"> <code class="literal">AS</code> <em class="replaceable"><code>name</code></em> </span>] [<span class="optional">, ...</span>] ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The <code class="function">xmlforest</code> expression produces an XML
+ forest (sequence) of elements using the given names and content.
+ As for <code class="function">xmlelement</code>,
+ each <em class="replaceable"><code>name</code></em> must be a simple identifier, while
+ the <em class="replaceable"><code>content</code></em> expressions can have any data
+ type.
+ </p><p>
+ Examples:
+</p><pre class="screen">
+SELECT xmlforest('abc' AS foo, 123 AS bar);
+
+ xmlforest
+------------------------------
+ &lt;foo&gt;abc&lt;/foo&gt;&lt;bar&gt;123&lt;/bar&gt;
+
+
+SELECT xmlforest(table_name, column_name)
+FROM information_schema.columns
+WHERE table_schema = 'pg_catalog';
+
+ xmlforest
+------------------------------------​-----------------------------------
+ &lt;table_name&gt;pg_authid&lt;/table_name&gt;​&lt;column_name&gt;rolname&lt;/column_name&gt;
+ &lt;table_name&gt;pg_authid&lt;/table_name&gt;​&lt;column_name&gt;rolsuper&lt;/column_name&gt;
+ ...
+</pre><p>
+
+ As seen in the second example, the element name can be omitted if
+ the content value is a column reference, in which case the column
+ name is used by default. Otherwise, a name must be specified.
+ </p><p>
+ Element names that are not valid XML names are escaped as shown
+ for <code class="function">xmlelement</code> above. Similarly, content
+ data is escaped to make valid XML content, unless it is already
+ of type <code class="type">xml</code>.
+ </p><p>
+ Note that XML forests are not valid XML documents if they consist
+ of more than one element, so it might be useful to wrap
+ <code class="function">xmlforest</code> expressions in
+ <code class="function">xmlelement</code>.
+ </p></div><div class="sect3" id="id-1.5.8.21.5.7"><div class="titlepage"><div><div><h4 class="title">9.15.1.5. <code class="literal">xmlpi</code></h4></div></div></div><a id="id-1.5.8.21.5.7.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlpi</code> ( <code class="literal">NAME</code> <em class="replaceable"><code>name</code></em> [<span class="optional">, <em class="replaceable"><code>content</code></em> </span>] ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The <code class="function">xmlpi</code> expression creates an XML
+ processing instruction.
+ As for <code class="function">xmlelement</code>,
+ the <em class="replaceable"><code>name</code></em> must be a simple identifier, while
+ the <em class="replaceable"><code>content</code></em> expression can have any data type.
+ The <em class="replaceable"><code>content</code></em>, if present, must not contain the
+ character sequence <code class="literal">?&gt;</code>.
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xmlpi(name php, 'echo "hello world";');
+
+ xmlpi
+-----------------------------
+ &lt;?php echo "hello world";?&gt;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.5.8.21.5.8"><div class="titlepage"><div><div><h4 class="title">9.15.1.6. <code class="literal">xmlroot</code></h4></div></div></div><a id="id-1.5.8.21.5.8.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlroot</code> ( <code class="type">xml</code>, <code class="literal">VERSION</code> {<code class="type">text</code>|<code class="literal">NO VALUE</code>} [<span class="optional">, <code class="literal">STANDALONE</code> {<code class="literal">YES</code>|<code class="literal">NO</code>|<code class="literal">NO VALUE</code>} </span>] ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The <code class="function">xmlroot</code> expression alters the properties
+ of the root node of an XML value. If a version is specified,
+ it replaces the value in the root node's version declaration; if a
+ standalone setting is specified, it replaces the value in the
+ root node's standalone declaration.
+ </p><p>
+</p><pre class="screen">
+SELECT xmlroot(xmlparse(document '&lt;?xml version="1.1"?&gt;&lt;content&gt;abc&lt;/content&gt;'),
+ version '1.0', standalone yes);
+
+ xmlroot
+----------------------------------------
+ &lt;?xml version="1.0" standalone="yes"?&gt;
+ &lt;content&gt;abc&lt;/content&gt;
+</pre><p>
+ </p></div><div class="sect3" id="FUNCTIONS-XML-XMLAGG"><div class="titlepage"><div><div><h4 class="title">9.15.1.7. <code class="literal">xmlagg</code></h4></div></div></div><a id="id-1.5.8.21.5.9.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xmlagg</code> ( <code class="type">xml</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+ The function <code class="function">xmlagg</code> is, unlike the other
+ functions described here, an aggregate function. It concatenates the
+ input values to the aggregate function call,
+ much like <code class="function">xmlconcat</code> does, except that concatenation
+ occurs across rows rather than across expressions in a single row.
+ See <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> for additional information
+ about aggregate functions.
+ </p><p>
+ Example:
+</p><pre class="screen">
+CREATE TABLE test (y int, x xml);
+INSERT INTO test VALUES (1, '&lt;foo&gt;abc&lt;/foo&gt;');
+INSERT INTO test VALUES (2, '&lt;bar/&gt;');
+SELECT xmlagg(x) FROM test;
+ xmlagg
+----------------------
+ &lt;foo&gt;abc&lt;/foo&gt;&lt;bar/&gt;
+</pre><p>
+ </p><p>
+ To determine the order of the concatenation, an <code class="literal">ORDER BY</code>
+ clause may be added to the aggregate call as described in
+ <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a>. For example:
+
+</p><pre class="screen">
+SELECT xmlagg(x ORDER BY y DESC) FROM test;
+ xmlagg
+----------------------
+ &lt;bar/&gt;&lt;foo&gt;abc&lt;/foo&gt;
+</pre><p>
+ </p><p>
+ The following non-standard approach used to be recommended
+ in previous versions, and may still be useful in specific
+ cases:
+
+</p><pre class="screen">
+SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
+ xmlagg
+----------------------
+ &lt;bar/&gt;&lt;foo&gt;abc&lt;/foo&gt;
+</pre><p>
+ </p></div></div><div class="sect2" id="FUNCTIONS-XML-PREDICATES"><div class="titlepage"><div><div><h3 class="title">9.15.2. XML Predicates</h3></div></div></div><p>
+ The expressions described in this section check properties
+ of <code class="type">xml</code> values.
+ </p><div class="sect3" id="id-1.5.8.21.6.3"><div class="titlepage"><div><div><h4 class="title">9.15.2.1. <code class="literal">IS DOCUMENT</code></h4></div></div></div><a id="id-1.5.8.21.6.3.2" class="indexterm"></a><pre class="synopsis">
+<code class="type">xml</code> <code class="literal">IS DOCUMENT</code> → <code class="returnvalue">boolean</code>
+</pre><p>
+ The expression <code class="literal">IS DOCUMENT</code> 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 <a class="xref" href="datatype-xml.html" title="8.13. XML Type">Section 8.13</a> about the difference
+ between documents and content fragments.
+ </p></div><div class="sect3" id="id-1.5.8.21.6.4"><div class="titlepage"><div><div><h4 class="title">9.15.2.2. <code class="literal">IS NOT DOCUMENT</code></h4></div></div></div><a id="id-1.5.8.21.6.4.2" class="indexterm"></a><pre class="synopsis">
+<code class="type">xml</code> <code class="literal">IS NOT DOCUMENT</code> → <code class="returnvalue">boolean</code>
+</pre><p>
+ The expression <code class="literal">IS NOT DOCUMENT</code> returns false if the
+ argument XML value is a proper XML document, true if it is not (that is,
+ it is a content fragment), or null if the argument is null.
+ </p></div><div class="sect3" id="XML-EXISTS"><div class="titlepage"><div><div><h4 class="title">9.15.2.3. <code class="literal">XMLEXISTS</code></h4></div></div></div><a id="id-1.5.8.21.6.5.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">XMLEXISTS</code> ( <code class="type">text</code> <code class="literal">PASSING</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] <code class="type">xml</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] ) → <code class="returnvalue">boolean</code>
+</pre><p>
+ The function <code class="function">xmlexists</code> evaluates an XPath 1.0
+ expression (the first argument), with the passed XML value as its context
+ item. The function returns false if the result of that evaluation
+ yields an empty node-set, true if it yields any other value. The
+ function returns null if any argument is null. A nonnull value
+ passed as the context item must be an XML document, not a content
+ fragment or any non-XML value.
+ </p><p>
+ Example:
+ </p><pre class="screen">
+SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY VALUE '&lt;towns&gt;&lt;town&gt;Toronto&lt;/town&gt;&lt;town&gt;Ottawa&lt;/town&gt;&lt;/towns&gt;');
+
+ xmlexists
+------------
+ t
+(1 row)
+</pre><p>
+ </p><p>
+ The <code class="literal">BY REF</code> and <code class="literal">BY VALUE</code> clauses
+ are accepted in <span class="productname">PostgreSQL</span>, but are ignored,
+ as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL" title="D.3.2. Incidental Limits of the Implementation">Section D.3.2</a>.
+ </p><p>
+ In the SQL standard, the <code class="function">xmlexists</code> function
+ evaluates an expression in the XML Query language,
+ but <span class="productname">PostgreSQL</span> allows only an XPath 1.0
+ expression, as discussed in
+ <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1" title="D.3.1. Queries Are Restricted to XPath 1.0">Section D.3.1</a>.
+ </p></div><div class="sect3" id="XML-IS-WELL-FORMED"><div class="titlepage"><div><div><h4 class="title">9.15.2.4. <code class="literal">xml_is_well_formed</code></h4></div></div></div><a id="id-1.5.8.21.6.6.2" class="indexterm"></a><a id="id-1.5.8.21.6.6.3" class="indexterm"></a><a id="id-1.5.8.21.6.6.4" class="indexterm"></a><pre class="synopsis">
+<code class="function">xml_is_well_formed</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
+<code class="function">xml_is_well_formed_document</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
+<code class="function">xml_is_well_formed_content</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
+</pre><p>
+ These functions check whether a <code class="type">text</code> string represents
+ well-formed XML, returning a Boolean result.
+ <code class="function">xml_is_well_formed_document</code> checks for a well-formed
+ document, while <code class="function">xml_is_well_formed_content</code> checks
+ for well-formed content. <code class="function">xml_is_well_formed</code> does
+ the former if the <a class="xref" href="runtime-config-client.html#GUC-XMLOPTION">xmloption</a> configuration
+ parameter is set to <code class="literal">DOCUMENT</code>, or the latter if it is set to
+ <code class="literal">CONTENT</code>. This means that
+ <code class="function">xml_is_well_formed</code> is useful for seeing whether
+ a simple cast to type <code class="type">xml</code> will succeed, whereas the other two
+ functions are useful for seeing whether the corresponding variants of
+ <code class="function">XMLPARSE</code> will succeed.
+ </p><p>
+ Examples:
+
+</p><pre class="screen">
+SET xmloption TO DOCUMENT;
+SELECT xml_is_well_formed('&lt;&gt;');
+ xml_is_well_formed
+--------------------
+ f
+(1 row)
+
+SELECT xml_is_well_formed('&lt;abc/&gt;');
+ xml_is_well_formed
+--------------------
+ t
+(1 row)
+
+SET xmloption TO CONTENT;
+SELECT xml_is_well_formed('abc');
+ xml_is_well_formed
+--------------------
+ t
+(1 row)
+
+SELECT xml_is_well_formed_document('&lt;pg:foo xmlns:pg="http://postgresql.org/stuff"&gt;bar&lt;/pg:foo&gt;');
+ xml_is_well_formed_document
+-----------------------------
+ t
+(1 row)
+
+SELECT xml_is_well_formed_document('&lt;pg:foo xmlns:pg="http://postgresql.org/stuff"&gt;bar&lt;/my:foo&gt;');
+ xml_is_well_formed_document
+-----------------------------
+ f
+(1 row)
+</pre><p>
+
+ The last example shows that the checks include whether
+ namespaces are correctly matched.
+ </p></div></div><div class="sect2" id="FUNCTIONS-XML-PROCESSING"><div class="titlepage"><div><div><h3 class="title">9.15.3. Processing XML</h3></div></div></div><p>
+ To process values of data type <code class="type">xml</code>, PostgreSQL offers
+ the functions <code class="function">xpath</code> and
+ <code class="function">xpath_exists</code>, which evaluate XPath 1.0
+ expressions, and the <code class="function">XMLTABLE</code>
+ table function.
+ </p><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XPATH"><div class="titlepage"><div><div><h4 class="title">9.15.3.1. <code class="literal">xpath</code></h4></div></div></div><a id="id-1.5.8.21.7.3.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xpath</code> ( <em class="parameter"><code>xpath</code></em> <code class="type">text</code>, <em class="parameter"><code>xml</code></em> <code class="type">xml</code> [<span class="optional">, <em class="parameter"><code>nsarray</code></em> <code class="type">text[]</code> </span>] ) → <code class="returnvalue">xml[]</code>
+</pre><p>
+ The function <code class="function">xpath</code> evaluates the XPath 1.0
+ expression <em class="parameter"><code>xpath</code></em> (given as text)
+ against the XML value
+ <em class="parameter"><code>xml</code></em>. It returns an array of XML values
+ corresponding to the node-set produced by the XPath expression.
+ If the XPath expression returns a scalar value rather than a node-set,
+ a single-element array is returned.
+ </p><p>
+ The second argument must be a well formed XML document. In particular,
+ it must have a single root node element.
+ </p><p>
+ The optional third argument of the function is an array of namespace
+ mappings. This array should be a two-dimensional <code class="type">text</code> array with
+ the length of the second axis being equal to 2 (i.e., it should be an
+ array of arrays, each of which consists of exactly 2 elements).
+ The first element of each array entry is the namespace name (alias), the
+ second the namespace URI. It is not required that aliases provided in
+ this array be the same as those being used in the XML document itself (in
+ other words, both in the XML document and in the <code class="function">xpath</code>
+ function context, aliases are <span class="emphasis"><em>local</em></span>).
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xpath('/my:a/text()', '&lt;my:a xmlns:my="http://example.com"&gt;test&lt;/my:a&gt;',
+ ARRAY[ARRAY['my', 'http://example.com']]);
+
+ xpath
+--------
+ {test}
+(1 row)
+</pre><p>
+ </p><p>
+ To deal with default (anonymous) namespaces, do something like this:
+</p><pre class="screen">
+SELECT xpath('//mydefns:b/text()', '&lt;a xmlns="http://example.com"&gt;&lt;b&gt;test&lt;/b&gt;&lt;/a&gt;',
+ ARRAY[ARRAY['mydefns', 'http://example.com']]);
+
+ xpath
+--------
+ {test}
+(1 row)
+</pre><p>
+ </p></div><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XPATH-EXISTS"><div class="titlepage"><div><div><h4 class="title">9.15.3.2. <code class="literal">xpath_exists</code></h4></div></div></div><a id="id-1.5.8.21.7.4.2" class="indexterm"></a><pre class="synopsis">
+<code class="function">xpath_exists</code> ( <em class="parameter"><code>xpath</code></em> <code class="type">text</code>, <em class="parameter"><code>xml</code></em> <code class="type">xml</code> [<span class="optional">, <em class="parameter"><code>nsarray</code></em> <code class="type">text[]</code> </span>] ) → <code class="returnvalue">boolean</code>
+</pre><p>
+ The function <code class="function">xpath_exists</code> is a specialized form
+ of the <code class="function">xpath</code> function. Instead of returning the
+ individual XML values that satisfy the XPath 1.0 expression, this function
+ returns a Boolean indicating whether the query was satisfied or not
+ (specifically, whether it produced any value other than an empty node-set).
+ This function is equivalent to the <code class="literal">XMLEXISTS</code> predicate,
+ except that it also offers support for a namespace mapping argument.
+ </p><p>
+ Example:
+</p><pre class="screen">
+SELECT xpath_exists('/my:a/text()', '&lt;my:a xmlns:my="http://example.com"&gt;test&lt;/my:a&gt;',
+ ARRAY[ARRAY['my', 'http://example.com']]);
+
+ xpath_exists
+--------------
+ t
+(1 row)
+</pre><p>
+ </p></div><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XMLTABLE"><div class="titlepage"><div><div><h4 class="title">9.15.3.3. <code class="literal">xmltable</code></h4></div></div></div><a id="id-1.5.8.21.7.5.2" class="indexterm"></a><a id="id-1.5.8.21.7.5.3" class="indexterm"></a><pre class="synopsis">
+<code class="function">XMLTABLE</code> (
+ [<span class="optional"> <code class="literal">XMLNAMESPACES</code> ( <em class="replaceable"><code>namespace_uri</code></em> <code class="literal">AS</code> <em class="replaceable"><code>namespace_name</code></em> [<span class="optional">, ...</span>] ), </span>]
+ <em class="replaceable"><code>row_expression</code></em> <code class="literal">PASSING</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] <em class="replaceable"><code>document_expression</code></em> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>]
+ <code class="literal">COLUMNS</code> <em class="replaceable"><code>name</code></em> { <em class="replaceable"><code>type</code></em> [<span class="optional"><code class="literal">PATH</code> <em class="replaceable"><code>column_expression</code></em></span>] [<span class="optional"><code class="literal">DEFAULT</code> <em class="replaceable"><code>default_expression</code></em></span>] [<span class="optional"><code class="literal">NOT NULL</code> | <code class="literal">NULL</code></span>]
+ | <code class="literal">FOR ORDINALITY</code> }
+ [<span class="optional">, ...</span>]
+) → <code class="returnvalue">setof record</code>
+</pre><p>
+ The <code class="function">xmltable</code> expression produces a table based
+ on an XML value, an XPath filter to extract rows, and a
+ set of column definitions.
+ Although it syntactically resembles a function, it can only appear
+ as a table in a query's <code class="literal">FROM</code> clause.
+ </p><p>
+ The optional <code class="literal">XMLNAMESPACES</code> clause gives a
+ comma-separated list of namespace definitions, where
+ each <em class="replaceable"><code>namespace_uri</code></em> is a <code class="type">text</code>
+ expression and each <em class="replaceable"><code>namespace_name</code></em> is a simple
+ identifier. It specifies the XML namespaces used in the document and
+ their aliases. A default namespace specification is not currently
+ supported.
+ </p><p>
+ The required <em class="replaceable"><code>row_expression</code></em> argument is an
+ XPath 1.0 expression (given as <code class="type">text</code>) that is evaluated,
+ passing the XML value <em class="replaceable"><code>document_expression</code></em> as
+ its context item, to obtain a set of XML nodes. These nodes are what
+ <code class="function">xmltable</code> transforms into output rows. No rows
+ will be produced if the <em class="replaceable"><code>document_expression</code></em>
+ is null, nor if the <em class="replaceable"><code>row_expression</code></em> produces
+ an empty node-set or any value other than a node-set.
+ </p><p>
+ <em class="replaceable"><code>document_expression</code></em> provides the context
+ item for the <em class="replaceable"><code>row_expression</code></em>. It must be a
+ well-formed XML document; fragments/forests are not accepted.
+ The <code class="literal">BY REF</code> and <code class="literal">BY VALUE</code> clauses
+ are accepted but ignored, as discussed in
+ <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL" title="D.3.2. Incidental Limits of the Implementation">Section D.3.2</a>.
+ </p><p>
+ In the SQL standard, the <code class="function">xmltable</code> function
+ evaluates expressions in the XML Query language,
+ but <span class="productname">PostgreSQL</span> allows only XPath 1.0
+ expressions, as discussed in
+ <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1" title="D.3.1. Queries Are Restricted to XPath 1.0">Section D.3.1</a>.
+ </p><p>
+ The required <code class="literal">COLUMNS</code> clause specifies the
+ column(s) that will be produced in the output table.
+ See the syntax summary above for the format.
+ A name is required for each column, as is a data type
+ (unless <code class="literal">FOR ORDINALITY</code> is specified, in which case
+ type <code class="type">integer</code> is implicit). The path, default and
+ nullability clauses are optional.
+ </p><p>
+ A column marked <code class="literal">FOR ORDINALITY</code> will be populated
+ with row numbers, starting with 1, in the order of nodes retrieved from
+ the <em class="replaceable"><code>row_expression</code></em>'s result node-set.
+ At most one column may be marked <code class="literal">FOR ORDINALITY</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ XPath 1.0 does not specify an order for nodes in a node-set, so code
+ that relies on a particular order of the results will be
+ implementation-dependent. Details can be found in
+ <a class="xref" href="xml-limits-conformance.html#XML-XPATH-1-SPECIFICS" title="D.3.1.2. Restriction of XPath to 1.0">Section D.3.1.2</a>.
+ </p></div><p>
+ The <em class="replaceable"><code>column_expression</code></em> for a column is an
+ XPath 1.0 expression that is evaluated for each row, with the current
+ node from the <em class="replaceable"><code>row_expression</code></em> result as its
+ context item, to find the value of the column. If
+ no <em class="replaceable"><code>column_expression</code></em> is given, then the
+ column name is used as an implicit path.
+ </p><p>
+ If a column's XPath expression returns a non-XML value (which is limited
+ to string, boolean, or double in XPath 1.0) and the column has a
+ PostgreSQL type other than <code class="type">xml</code>, the column will be set
+ as if by assigning the value's string representation to the PostgreSQL
+ type. (If the value is a boolean, its string representation is taken
+ to be <code class="literal">1</code> or <code class="literal">0</code> if the output
+ column's type category is numeric, otherwise <code class="literal">true</code> or
+ <code class="literal">false</code>.)
+ </p><p>
+ If a column's XPath expression returns a non-empty set of XML nodes
+ and the column's PostgreSQL type is <code class="type">xml</code>, the column will
+ be assigned the expression result exactly, if it is of document or
+ content form.
+ <a href="#ftn.id-1.5.8.21.7.5.15.2" class="footnote"><sup class="footnote" id="id-1.5.8.21.7.5.15.2">[8]</sup></a>
+ </p><p>
+ A non-XML result assigned to an <code class="type">xml</code> output column produces
+ content, a single text node with the string value of the result.
+ An XML result assigned to a column of any other type may not have more than
+ one node, or an error is raised. If there is exactly one node, the column
+ will be set as if by assigning the node's string
+ value (as defined for the XPath 1.0 <code class="function">string</code> function)
+ to the PostgreSQL type.
+ </p><p>
+ The string value of an XML element is the concatenation, in document order,
+ of all text nodes contained in that element and its descendants. The string
+ value of an element with no descendant text nodes is an
+ empty string (not <code class="literal">NULL</code>).
+ Any <code class="literal">xsi:nil</code> attributes are ignored.
+ Note that the whitespace-only <code class="literal">text()</code> node between two non-text
+ elements is preserved, and that leading whitespace on a <code class="literal">text()</code>
+ node is not flattened.
+ The XPath 1.0 <code class="function">string</code> function may be consulted for the
+ rules defining the string value of other XML node types and non-XML values.
+ </p><p>
+ The conversion rules presented here are not exactly those of the SQL
+ standard, as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-CASTS" title="D.3.1.3. Mappings between SQL and XML Data Types and Values">Section D.3.1.3</a>.
+ </p><p>
+ If the path expression returns an empty node-set
+ (typically, when it does not match)
+ for a given row, the column will be set to <code class="literal">NULL</code>, unless
+ a <em class="replaceable"><code>default_expression</code></em> is specified; then the
+ value resulting from evaluating that expression is used.
+ </p><p>
+ A <em class="replaceable"><code>default_expression</code></em>, rather than being
+ evaluated immediately when <code class="function">xmltable</code> is called,
+ is evaluated each time a default is needed for the column.
+ If the expression qualifies as stable or immutable, the repeat
+ evaluation may be skipped.
+ This means that you can usefully use volatile functions like
+ <code class="function">nextval</code> in
+ <em class="replaceable"><code>default_expression</code></em>.
+ </p><p>
+ Columns may be marked <code class="literal">NOT NULL</code>. If the
+ <em class="replaceable"><code>column_expression</code></em> for a <code class="literal">NOT
+ NULL</code> column does not match anything and there is
+ no <code class="literal">DEFAULT</code> or
+ the <em class="replaceable"><code>default_expression</code></em> also evaluates to null,
+ an error is reported.
+ </p><p>
+ Examples:
+ </p><pre class="screen">
+CREATE TABLE xmldata AS SELECT
+xml $$
+&lt;ROWS&gt;
+ &lt;ROW id="1"&gt;
+ &lt;COUNTRY_ID&gt;AU&lt;/COUNTRY_ID&gt;
+ &lt;COUNTRY_NAME&gt;Australia&lt;/COUNTRY_NAME&gt;
+ &lt;/ROW&gt;
+ &lt;ROW id="5"&gt;
+ &lt;COUNTRY_ID&gt;JP&lt;/COUNTRY_ID&gt;
+ &lt;COUNTRY_NAME&gt;Japan&lt;/COUNTRY_NAME&gt;
+ &lt;PREMIER_NAME&gt;Shinzo Abe&lt;/PREMIER_NAME&gt;
+ &lt;SIZE unit="sq_mi"&gt;145935&lt;/SIZE&gt;
+ &lt;/ROW&gt;
+ &lt;ROW id="6"&gt;
+ &lt;COUNTRY_ID&gt;SG&lt;/COUNTRY_ID&gt;
+ &lt;COUNTRY_NAME&gt;Singapore&lt;/COUNTRY_NAME&gt;
+ &lt;SIZE unit="sq_km"&gt;697&lt;/SIZE&gt;
+ &lt;/ROW&gt;
+&lt;/ROWS&gt;
+$$ AS data;
+
+SELECT xmltable.*
+ FROM xmldata,
+ XMLTABLE('//ROWS/ROW'
+ PASSING data
+ COLUMNS id int PATH '@id',
+ ordinality FOR ORDINALITY,
+ "COUNTRY_NAME" text,
+ country_id text PATH 'COUNTRY_ID',
+ size_sq_km float PATH 'SIZE[@unit = "sq_km"]',
+ size_other text PATH
+ 'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)',
+ premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified');
+
+ id | ordinality | COUNTRY_NAME | country_id | size_sq_km | size_other | premier_name
+----+------------+--------------+------------+------------+--------------+---------------
+ 1 | 1 | Australia | AU | | | not specified
+ 5 | 2 | Japan | JP | | 145935 sq_mi | Shinzo Abe
+ 6 | 3 | Singapore | SG | 697 | | not specified
+</pre><p>
+
+ The following example shows concatenation of multiple text() nodes,
+ usage of the column name as XPath filter, and the treatment of whitespace,
+ XML comments and processing instructions:
+
+ </p><pre class="screen">
+CREATE TABLE xmlelements AS SELECT
+xml $$
+ &lt;root&gt;
+ &lt;element&gt; Hello&lt;!-- xyxxz --&gt;2a2&lt;?aaaaa?&gt; &lt;!--x--&gt; bbb&lt;x&gt;xxx&lt;/x&gt;CC &lt;/element&gt;
+ &lt;/root&gt;
+$$ AS data;
+
+SELECT xmltable.*
+ FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
+ element
+-------------------------
+ Hello2a2 bbbxxxCC
+</pre><p>
+ </p><p>
+ The following example illustrates how
+ the <code class="literal">XMLNAMESPACES</code> clause can be used to specify
+ a list of namespaces
+ used in the XML document as well as in the XPath expressions:
+
+ </p><pre class="screen">
+WITH xmldata(data) AS (VALUES ('
+&lt;example xmlns="http://example.com/myns" xmlns:B="http://example.com/b"&gt;
+ &lt;item foo="1" B:bar="2"/&gt;
+ &lt;item foo="3" B:bar="4"/&gt;
+ &lt;item foo="4" B:bar="5"/&gt;
+&lt;/example&gt;'::xml)
+)
+SELECT xmltable.*
+ FROM XMLTABLE(XMLNAMESPACES('http://example.com/myns' AS x,
+ 'http://example.com/b' AS "B"),
+ '/x:example/x:item'
+ PASSING (SELECT data FROM xmldata)
+ COLUMNS foo int PATH '@foo',
+ bar int PATH '@B:bar');
+ foo | bar
+-----+-----
+ 1 | 2
+ 3 | 4
+ 4 | 5
+(3 rows)
+</pre><p>
+ </p></div></div><div class="sect2" id="FUNCTIONS-XML-MAPPING"><div class="titlepage"><div><div><h3 class="title">9.15.4. Mapping Tables to XML</h3></div></div></div><a id="id-1.5.8.21.8.2" class="indexterm"></a><p>
+ The following functions map the contents of relational tables to
+ XML values. They can be thought of as XML export functionality:
+</p><pre class="synopsis">
+<code class="function">table_to_xml</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">query_to_xml</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">cursor_to_xml</code> ( <em class="parameter"><code>cursor</code></em> <code class="type">refcursor</code>, <em class="parameter"><code>count</code></em> <code class="type">integer</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+ </p><p>
+ <code class="function">table_to_xml</code> maps the content of the named
+ table, passed as parameter <em class="parameter"><code>table</code></em>. The
+ <code class="type">regclass</code> type accepts strings identifying tables using the
+ usual notation, including optional schema qualification and
+ double quotes (see <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a> for details).
+ <code class="function">query_to_xml</code> executes the
+ query whose text is passed as parameter
+ <em class="parameter"><code>query</code></em> and maps the result set.
+ <code class="function">cursor_to_xml</code> fetches the indicated number of
+ rows from the cursor specified by the parameter
+ <em class="parameter"><code>cursor</code></em>. This variant is recommended if
+ large tables have to be mapped, because the result value is built
+ up in memory by each function.
+ </p><p>
+ If <em class="parameter"><code>tableforest</code></em> is false, then the resulting
+ XML document looks like this:
+</p><pre class="screen">
+&lt;tablename&gt;
+ &lt;row&gt;
+ &lt;columnname1&gt;data&lt;/columnname1&gt;
+ &lt;columnname2&gt;data&lt;/columnname2&gt;
+ &lt;/row&gt;
+
+ &lt;row&gt;
+ ...
+ &lt;/row&gt;
+
+ ...
+&lt;/tablename&gt;
+</pre><p>
+
+ If <em class="parameter"><code>tableforest</code></em> is true, the result is an
+ XML content fragment that looks like this:
+</p><pre class="screen">
+&lt;tablename&gt;
+ &lt;columnname1&gt;data&lt;/columnname1&gt;
+ &lt;columnname2&gt;data&lt;/columnname2&gt;
+&lt;/tablename&gt;
+
+&lt;tablename&gt;
+ ...
+&lt;/tablename&gt;
+
+...
+</pre><p>
+
+ If no table name is available, that is, when mapping a query or a
+ cursor, the string <code class="literal">table</code> is used in the first
+ format, <code class="literal">row</code> in the second format.
+ </p><p>
+ The choice between these formats is up to the user. The first
+ format is a proper XML document, which will be important in many
+ applications. The second format tends to be more useful in the
+ <code class="function">cursor_to_xml</code> function if the result values are to be
+ reassembled into one document later on. The functions for
+ producing XML content discussed above, in particular
+ <code class="function">xmlelement</code>, can be used to alter the results
+ to taste.
+ </p><p>
+ The data values are mapped in the same way as described for the
+ function <code class="function">xmlelement</code> above.
+ </p><p>
+ The parameter <em class="parameter"><code>nulls</code></em> determines whether null
+ values should be included in the output. If true, null values in
+ columns are represented as:
+</p><pre class="screen">
+&lt;columnname xsi:nil="true"/&gt;
+</pre><p>
+ where <code class="literal">xsi</code> is the XML namespace prefix for XML
+ Schema Instance. An appropriate namespace declaration will be
+ added to the result value. If false, columns containing null
+ values are simply omitted from the output.
+ </p><p>
+ The parameter <em class="parameter"><code>targetns</code></em> specifies the
+ desired XML namespace of the result. If no particular namespace
+ is wanted, an empty string should be passed.
+ </p><p>
+ The following functions return XML Schema documents describing the
+ mappings performed by the corresponding functions above:
+</p><pre class="synopsis">
+<code class="function">table_to_xmlschema</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">query_to_xmlschema</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">cursor_to_xmlschema</code> ( <em class="parameter"><code>cursor</code></em> <code class="type">refcursor</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+ It is essential that the same parameters are passed in order to
+ obtain matching XML data mappings and XML Schema documents.
+ </p><p>
+ The following functions produce XML data mappings and the
+ corresponding XML Schema in one document (or forest), linked
+ together. They can be useful where self-contained and
+ self-describing results are wanted:
+</p><pre class="synopsis">
+<code class="function">table_to_xml_and_xmlschema</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">query_to_xml_and_xmlschema</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+ </p><p>
+ In addition, the following functions are available to produce
+ analogous mappings of entire schemas or the entire current
+ database:
+</p><pre class="synopsis">
+<code class="function">schema_to_xml</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">schema_to_xmlschema</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">schema_to_xml_and_xmlschema</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+
+<code class="function">database_to_xml</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">database_to_xmlschema</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+<code class="function">database_to_xml_and_xmlschema</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
+ <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
+</pre><p>
+
+ These functions ignore tables that are not readable by the current user.
+ The database-wide functions additionally ignore schemas that the current
+ user does not have <code class="literal">USAGE</code> (lookup) privilege for.
+ </p><p>
+ Note that these potentially produce a lot of data, which needs to
+ be built up in memory. When requesting content mappings of large
+ schemas or databases, it might be worthwhile to consider mapping the
+ tables separately instead, possibly even through a cursor.
+ </p><p>
+ The result of a schema content mapping looks like this:
+
+</p><pre class="screen">
+&lt;schemaname&gt;
+
+table1-mapping
+
+table2-mapping
+
+...
+
+&lt;/schemaname&gt;</pre><p>
+
+ where the format of a table mapping depends on the
+ <em class="parameter"><code>tableforest</code></em> parameter as explained above.
+ </p><p>
+ The result of a database content mapping looks like this:
+
+</p><pre class="screen">
+&lt;dbname&gt;
+
+&lt;schema1name&gt;
+ ...
+&lt;/schema1name&gt;
+
+&lt;schema2name&gt;
+ ...
+&lt;/schema2name&gt;
+
+...
+
+&lt;/dbname&gt;</pre><p>
+
+ where the schema mapping is as above.
+ </p><p>
+ As an example of using the output produced by these functions,
+ <a class="xref" href="functions-xml.html#XSLT-XML-HTML" title="Example 9.1. XSLT Stylesheet for Converting SQL/XML Output to HTML">Example 9.1</a> shows an XSLT stylesheet that
+ converts the output of
+ <code class="function">table_to_xml_and_xmlschema</code> to an HTML
+ document containing a tabular rendition of the table data. In a
+ similar manner, the results from these functions can be
+ converted into other XML-based formats.
+ </p><div class="example" id="XSLT-XML-HTML"><p class="title"><strong>Example 9.1. XSLT Stylesheet for Converting SQL/XML Output to HTML</strong></p><div class="example-contents"><pre class="programlisting">
+&lt;?xml version="1.0"?&gt;
+&lt;xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://www.w3.org/1999/xhtml"
+&gt;
+
+ &lt;xsl:output method="xml"
+ doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
+ doctype-public="-//W3C/DTD XHTML 1.0 Strict//EN"
+ indent="yes"/&gt;
+
+ &lt;xsl:template match="/*"&gt;
+ &lt;xsl:variable name="schema" select="//xsd:schema"/&gt;
+ &lt;xsl:variable name="tabletypename"
+ select="$schema/xsd:element[@name=name(current())]/@type"/&gt;
+ &lt;xsl:variable name="rowtypename"
+ select="$schema/xsd:complexType[@name=$tabletypename]/xsd:sequence/xsd:element[@name='row']/@type"/&gt;
+
+ &lt;html&gt;
+ &lt;head&gt;
+ &lt;title&gt;&lt;xsl:value-of select="name(current())"/&gt;&lt;/title&gt;
+ &lt;/head&gt;
+ &lt;body&gt;
+ &lt;table&gt;
+ &lt;tr&gt;
+ &lt;xsl:for-each select="$schema/xsd:complexType[@name=$rowtypename]/xsd:sequence/xsd:element/@name"&gt;
+ &lt;th&gt;&lt;xsl:value-of select="."/&gt;&lt;/th&gt;
+ &lt;/xsl:for-each&gt;
+ &lt;/tr&gt;
+
+ &lt;xsl:for-each select="row"&gt;
+ &lt;tr&gt;
+ &lt;xsl:for-each select="*"&gt;
+ &lt;td&gt;&lt;xsl:value-of select="."/&gt;&lt;/td&gt;
+ &lt;/xsl:for-each&gt;
+ &lt;/tr&gt;
+ &lt;/xsl:for-each&gt;
+ &lt;/table&gt;
+ &lt;/body&gt;
+ &lt;/html&gt;
+ &lt;/xsl:template&gt;
+
+&lt;/xsl:stylesheet&gt;
+</pre></div></div><br class="example-break" /></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.8.21.7.5.15.2" class="footnote"><p><a href="#id-1.5.8.21.7.5.15.2" class="para"><sup class="para">[8] </sup></a>
+ A result containing more than one element node at the top level, or
+ non-whitespace text outside of an element, is an example of content form.
+ An XPath result can be of neither form, for example if it returns an
+ attribute node selected from the element that contains it. Such a result
+ will be put into content form with each such disallowed node replaced by
+ its string value, as defined for the XPath 1.0
+ <code class="function">string</code> function.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-uuid.html" title="9.14. UUID Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-json.html" title="9.16. JSON Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.14. UUID Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.16. JSON Functions and Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/functions.html b/doc/src/sgml/html/functions.html
new file mode 100644
index 0000000..dd1de51
--- /dev/null
+++ b/doc/src/sgml/html/functions.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 9. Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-pseudo.html" title="8.21. Pseudo-Types" /><link rel="next" href="functions-logical.html" title="9.1. Logical Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 9. Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-pseudo.html" title="8.21. Pseudo-Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-logical.html" title="9.1. Logical Operators">Next</a></td></tr></table><hr /></div><div class="chapter" id="FUNCTIONS"><div class="titlepage"><div><div><h2 class="title">Chapter 9. Functions and Operators</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="functions-logical.html">9.1. Logical Operators</a></span></dt><dt><span class="sect1"><a href="functions-comparison.html">9.2. Comparison Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-math.html">9.3. Mathematical Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-string.html">9.4. String Functions and Operators</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-string.html#FUNCTIONS-STRING-FORMAT">9.4.1. <code class="function">format</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-binarystring.html">9.5. Binary String Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-bitstring.html">9.6. Bit String Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-matching.html">9.7. Pattern Matching</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-LIKE">9.7.1. <code class="function">LIKE</code></a></span></dt><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-SIMILARTO-REGEXP">9.7.2. <code class="function">SIMILAR TO</code> Regular Expressions</a></span></dt><dt><span class="sect2"><a href="functions-matching.html#FUNCTIONS-POSIX-REGEXP">9.7.3. <acronym class="acronym">POSIX</acronym> Regular Expressions</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-formatting.html">9.8. Data Type Formatting Functions</a></span></dt><dt><span class="sect1"><a href="functions-datetime.html">9.9. Date/Time Functions and Operators</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT">9.9.1. <code class="function">EXTRACT</code>, <code class="function">date_part</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC">9.9.2. <code class="function">date_trunc</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-BIN">9.9.3. <code class="function">date_bin</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT">9.9.4. <code class="literal">AT TIME ZONE</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT">9.9.5. Current Date/Time</a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">9.9.6. Delaying Execution</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-enum.html">9.10. Enum Support Functions</a></span></dt><dt><span class="sect1"><a href="functions-geometry.html">9.11. Geometric Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-net.html">9.12. Network Address Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-textsearch.html">9.13. Text Search Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-uuid.html">9.14. UUID Functions</a></span></dt><dt><span class="sect1"><a href="functions-xml.html">9.15. XML Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-PRODUCING-XML">9.15.1. Producing XML Content</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PREDICATES">9.15.2. XML Predicates</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PROCESSING">9.15.3. Processing XML</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-MAPPING">9.15.4. Mapping Tables to XML</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-json.html">9.16. JSON Functions and Operators</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-JSON-PROCESSING">9.16.1. Processing and Creating JSON Data</a></span></dt><dt><span class="sect2"><a href="functions-json.html#FUNCTIONS-SQLJSON-PATH">9.16.2. The SQL/JSON Path Language</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-sequence.html">9.17. Sequence Manipulation Functions</a></span></dt><dt><span class="sect1"><a href="functions-conditional.html">9.18. Conditional Expressions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-CASE">9.18.1. <code class="literal">CASE</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-COALESCE-NVL-IFNULL">9.18.2. <code class="literal">COALESCE</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-NULLIF">9.18.3. <code class="literal">NULLIF</code></a></span></dt><dt><span class="sect2"><a href="functions-conditional.html#FUNCTIONS-GREATEST-LEAST">9.18.4. <code class="literal">GREATEST</code> and <code class="literal">LEAST</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-array.html">9.19. Array Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-range.html">9.20. Range/Multirange Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-aggregate.html">9.21. Aggregate Functions</a></span></dt><dt><span class="sect1"><a href="functions-window.html">9.22. Window Functions</a></span></dt><dt><span class="sect1"><a href="functions-subquery.html">9.23. Subquery Expressions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-EXISTS">9.23.1. <code class="literal">EXISTS</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-IN">9.23.2. <code class="literal">IN</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-NOTIN">9.23.3. <code class="literal">NOT IN</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-ANY-SOME">9.23.4. <code class="literal">ANY</code>/<code class="literal">SOME</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#FUNCTIONS-SUBQUERY-ALL">9.23.5. <code class="literal">ALL</code></a></span></dt><dt><span class="sect2"><a href="functions-subquery.html#id-1.5.8.29.15">9.23.6. Single-Row Comparison</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-comparisons.html">9.24. Row and Array Comparisons</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-comparisons.html#FUNCTIONS-COMPARISONS-IN-SCALAR">9.24.1. <code class="literal">IN</code></a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.15">9.24.2. <code class="literal">NOT IN</code></a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.16">9.24.3. <code class="literal">ANY</code>/<code class="literal">SOME</code> (array)</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#id-1.5.8.30.17">9.24.4. <code class="literal">ALL</code> (array)</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#ROW-WISE-COMPARISON">9.24.5. Row Constructor Comparison</a></span></dt><dt><span class="sect2"><a href="functions-comparisons.html#COMPOSITE-TYPE-COMPARISON">9.24.6. Composite Type Comparison</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-srf.html">9.25. Set Returning Functions</a></span></dt><dt><span class="sect1"><a href="functions-info.html">9.26. System Information Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-admin.html">9.27. System Administration Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SET">9.27.1. Configuration Settings Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">9.27.2. Server Signaling Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">9.27.3. Backup Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">9.27.4. Recovery Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION">9.27.5. Snapshot Synchronization Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-REPLICATION">9.27.6. Replication Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">9.27.7. Database Object Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">9.27.8. Index Maintenance Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">9.27.9. Generic File Access Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">9.27.10. Advisory Lock Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-trigger.html">9.28. Trigger Functions</a></span></dt><dt><span class="sect1"><a href="functions-event-triggers.html">9.29. Event Trigger Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS">9.29.1. Capturing Changes at Command End</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-SQL-DROP-FUNCTIONS">9.29.2. Processing Objects Dropped by a DDL Command</a></span></dt><dt><span class="sect2"><a href="functions-event-triggers.html#PG-EVENT-TRIGGER-TABLE-REWRITE-FUNCTIONS">9.29.3. Handling a Table Rewrite Event</a></span></dt></dl></dd><dt><span class="sect1"><a href="functions-statistics.html">9.30. Statistics Information Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="functions-statistics.html#FUNCTIONS-STATISTICS-MCV">9.30.1. Inspecting MCV Lists</a></span></dt></dl></dd></dl></div><a id="id-1.5.8.2" class="indexterm"></a><a id="id-1.5.8.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a large number of
+ functions and operators for the built-in data types. This chapter
+ describes most of them, although additional special-purpose functions
+ appear in relevant sections of the manual. Users can also
+ define their own functions and operators, as described in
+ <a class="xref" href="server-programming.html" title="Part V. Server Programming">Part V</a>. The
+ <span class="application">psql</span> commands <code class="command">\df</code> and
+ <code class="command">\do</code> can be used to list all
+ available functions and operators, respectively.
+ </p><p>
+ The notation used throughout this chapter to describe the argument and
+ result data types of a function or operator is like this:
+</p><pre class="synopsis">
+<code class="function">repeat</code> ( <code class="type">text</code>, <code class="type">integer</code> ) → <code class="returnvalue">text</code>
+</pre><p>
+ which says that the function <code class="function">repeat</code> takes one text and
+ one integer argument and returns a result of type text. The right arrow
+ is also used to indicate the result of an example, thus:
+</p><pre class="programlisting">
+repeat('Pg', 4) → <code class="returnvalue">PgPgPgPg</code>
+</pre><p>
+ </p><p>
+ If you are concerned about portability then note that most of
+ the functions and operators described in this chapter, with the
+ exception of the most trivial arithmetic and comparison operators
+ and some explicitly marked functions, are not specified by the
+ <acronym class="acronym">SQL</acronym> standard. Some of this extended functionality
+ is present in other <acronym class="acronym">SQL</acronym> database management
+ systems, and in many cases this functionality is compatible and
+ consistent between the various implementations.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-pseudo.html" title="8.21. Pseudo-Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-logical.html" title="9.1. Logical Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.21. Pseudo-Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.1. Logical Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/fuzzystrmatch.html b/doc/src/sgml/html/fuzzystrmatch.html
new file mode 100644
index 0000000..e8efbaf
--- /dev/null
+++ b/doc/src/sgml/html/fuzzystrmatch.html
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.17. fuzzystrmatch</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="file-fdw.html" title="F.16. file_fdw" /><link rel="next" href="hstore.html" title="F.18. hstore" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.17. fuzzystrmatch</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="file-fdw.html" title="F.16. file_fdw">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="hstore.html" title="F.18. hstore">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUZZYSTRMATCH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.17. fuzzystrmatch</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.6">F.17.1. Soundex</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.7">F.17.2. Levenshtein</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.8">F.17.3. Metaphone</a></span></dt><dt><span class="sect2"><a href="fuzzystrmatch.html#id-1.11.7.26.9">F.17.4. Double Metaphone</a></span></dt></dl></div><a id="id-1.11.7.26.2" class="indexterm"></a><p>
+ The <code class="filename">fuzzystrmatch</code> module provides several
+ functions to determine similarities and distance between strings.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ At present, the <code class="function">soundex</code>, <code class="function">metaphone</code>,
+ <code class="function">dmetaphone</code>, and <code class="function">dmetaphone_alt</code> functions do
+ not work well with multibyte encodings (such as UTF-8).
+ </p></div><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.26.6"><div class="titlepage"><div><div><h3 class="title">F.17.1. Soundex</h3></div></div></div><p>
+ The Soundex system is a method of matching similar-sounding names
+ by converting them to the same code. It was initially used by the
+ United States Census in 1880, 1900, and 1910. Note that Soundex
+ is not very useful for non-English names.
+ </p><p>
+ The <code class="filename">fuzzystrmatch</code> module provides two functions
+ for working with Soundex codes:
+ </p><a id="id-1.11.7.26.6.4" class="indexterm"></a><a id="id-1.11.7.26.6.5" class="indexterm"></a><pre class="synopsis">
+soundex(text) returns text
+difference(text, text) returns int
+</pre><p>
+ The <code class="function">soundex</code> function converts a string to its Soundex code.
+ The <code class="function">difference</code> function converts two strings to their Soundex
+ codes and then reports the number of matching code positions. Since
+ Soundex codes have four characters, the result ranges from zero to four,
+ with zero being no match and four being an exact match. (Thus, the
+ function is misnamed — <code class="function">similarity</code> would have been
+ a better name.)
+ </p><p>
+ Here are some usage examples:
+ </p><pre class="programlisting">
+SELECT soundex('hello world!');
+
+SELECT soundex('Anne'), soundex('Ann'), difference('Anne', 'Ann');
+SELECT soundex('Anne'), soundex('Andrew'), difference('Anne', 'Andrew');
+SELECT soundex('Anne'), soundex('Margaret'), difference('Anne', 'Margaret');
+
+CREATE TABLE s (nm text);
+
+INSERT INTO s VALUES ('john');
+INSERT INTO s VALUES ('joan');
+INSERT INTO s VALUES ('wobbly');
+INSERT INTO s VALUES ('jack');
+
+SELECT * FROM s WHERE soundex(nm) = soundex('john');
+
+SELECT * FROM s WHERE difference(s.nm, 'john') &gt; 2;
+</pre></div><div class="sect2" id="id-1.11.7.26.7"><div class="titlepage"><div><div><h3 class="title">F.17.2. Levenshtein</h3></div></div></div><p>
+ This function calculates the Levenshtein distance between two strings:
+ </p><a id="id-1.11.7.26.7.3" class="indexterm"></a><a id="id-1.11.7.26.7.4" class="indexterm"></a><pre class="synopsis">
+levenshtein(text source, text target, int ins_cost, int del_cost, int sub_cost) returns int
+levenshtein(text source, text target) returns int
+levenshtein_less_equal(text source, text target, int ins_cost, int del_cost, int sub_cost, int max_d) returns int
+levenshtein_less_equal(text source, text target, int max_d) returns int
+</pre><p>
+ Both <code class="literal">source</code> and <code class="literal">target</code> can be any
+ non-null string, with a maximum of 255 characters. The cost parameters
+ specify how much to charge for a character insertion, deletion, or
+ substitution, respectively. You can omit the cost parameters, as in
+ the second version of the function; in that case they all default to 1.
+ </p><p>
+ <code class="function">levenshtein_less_equal</code> is an accelerated version of the
+ Levenshtein function for use when only small distances are of interest.
+ If the actual distance is less than or equal to <code class="literal">max_d</code>,
+ then <code class="function">levenshtein_less_equal</code> returns the correct
+ distance; otherwise it returns some value greater than <code class="literal">max_d</code>.
+ If <code class="literal">max_d</code> is negative then the behavior is the same as
+ <code class="function">levenshtein</code>.
+ </p><p>
+ Examples:
+ </p><pre class="screen">
+test=# SELECT levenshtein('GUMBO', 'GAMBOL');
+ levenshtein
+-------------
+ 2
+(1 row)
+
+test=# SELECT levenshtein('GUMBO', 'GAMBOL', 2, 1, 1);
+ levenshtein
+-------------
+ 3
+(1 row)
+
+test=# SELECT levenshtein_less_equal('extensive', 'exhaustive', 2);
+ levenshtein_less_equal
+------------------------
+ 3
+(1 row)
+
+test=# SELECT levenshtein_less_equal('extensive', 'exhaustive', 4);
+ levenshtein_less_equal
+------------------------
+ 4
+(1 row)
+</pre></div><div class="sect2" id="id-1.11.7.26.8"><div class="titlepage"><div><div><h3 class="title">F.17.3. Metaphone</h3></div></div></div><p>
+ Metaphone, like Soundex, is based on the idea of constructing a
+ representative code for an input string. Two strings are then
+ deemed similar if they have the same codes.
+ </p><p>
+ This function calculates the metaphone code of an input string:
+ </p><a id="id-1.11.7.26.8.4" class="indexterm"></a><pre class="synopsis">
+metaphone(text source, int max_output_length) returns text
+</pre><p>
+ <code class="literal">source</code> has to be a non-null string with a maximum of
+ 255 characters. <code class="literal">max_output_length</code> sets the maximum
+ length of the output metaphone code; if longer, the output is truncated
+ to this length.
+ </p><p>
+ Example:
+ </p><pre class="screen">
+test=# SELECT metaphone('GUMBO', 4);
+ metaphone
+-----------
+ KM
+(1 row)
+</pre></div><div class="sect2" id="id-1.11.7.26.9"><div class="titlepage"><div><div><h3 class="title">F.17.4. Double Metaphone</h3></div></div></div><p>
+ The Double Metaphone system computes two <span class="quote">“<span class="quote">sounds like</span>”</span> strings
+ for a given input string — a <span class="quote">“<span class="quote">primary</span>”</span> and an
+ <span class="quote">“<span class="quote">alternate</span>”</span>. In most cases they are the same, but for non-English
+ names especially they can be a bit different, depending on pronunciation.
+ These functions compute the primary and alternate codes:
+ </p><a id="id-1.11.7.26.9.3" class="indexterm"></a><a id="id-1.11.7.26.9.4" class="indexterm"></a><pre class="synopsis">
+dmetaphone(text source) returns text
+dmetaphone_alt(text source) returns text
+</pre><p>
+ There is no length limit on the input strings.
+ </p><p>
+ Example:
+ </p><pre class="screen">
+test=# SELECT dmetaphone('gumbo');
+ dmetaphone
+------------
+ KMP
+(1 row)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="file-fdw.html" title="F.16. file_fdw">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hstore.html" title="F.18. hstore">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.16. file_fdw </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.18. hstore</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/generic-wal.html b/doc/src/sgml/html/generic-wal.html
new file mode 100644
index 0000000..14cadc6
--- /dev/null
+++ b/doc/src/sgml/html/generic-wal.html
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 65. Generic WAL Records</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions" /><link rel="next" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 65. Generic WAL Records</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Next</a></td></tr></table><hr /></div><div class="chapter" id="GENERIC-WAL"><div class="titlepage"><div><div><h2 class="title">Chapter 65. Generic WAL Records</h2></div></div></div><p>
+ Although all built-in WAL-logged modules have their own types of WAL
+ records, there is also a generic WAL record type, which describes changes
+ to pages in a generic way. This is useful for extensions that provide
+ custom access methods.
+ </p><p>
+ In comparison with <a class="link" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Custom WAL Resource
+ Managers</a>, Generic WAL is simpler for an extension to implement and
+ does not require the extension library to be loaded in order to apply the
+ records.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Generic WAL records are ignored during <a class="link" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Logical Decoding</a>. If logical decoding is
+ required for your extension, consider a Custom WAL Resource Manager.
+ </p></div><p>
+ The API for constructing generic WAL records is defined in
+ <code class="filename">access/generic_xlog.h</code> and implemented
+ in <code class="filename">access/transam/generic_xlog.c</code>.
+ </p><p>
+ To perform a WAL-logged data update using the generic WAL record
+ facility, follow these steps:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ <code class="function">state = GenericXLogStart(relation)</code> — start
+ construction of a generic WAL record for the given relation.
+ </p></li><li class="listitem"><p>
+ <code class="function">page = GenericXLogRegisterBuffer(state, buffer, flags)</code>
+ — register a buffer to be modified within the current generic WAL
+ record. This function returns a pointer to a temporary copy of the
+ buffer's page, where modifications should be made. (Do not modify the
+ buffer's contents directly.) The third argument is a bit mask of flags
+ applicable to the operation. Currently the only such flag is
+ <code class="literal">GENERIC_XLOG_FULL_IMAGE</code>, which indicates that a full-page
+ image rather than a delta update should be included in the WAL record.
+ Typically this flag would be set if the page is new or has been
+ rewritten completely.
+ <code class="function">GenericXLogRegisterBuffer</code> can be repeated if the
+ WAL-logged action needs to modify multiple pages.
+ </p></li><li class="listitem"><p>
+ Apply modifications to the page images obtained in the previous step.
+ </p></li><li class="listitem"><p>
+ <code class="function">GenericXLogFinish(state)</code> — apply the changes to
+ the buffers and emit the generic WAL record.
+ </p></li></ol></div><p>
+ </p><p>
+ WAL record construction can be canceled between any of the above steps by
+ calling <code class="function">GenericXLogAbort(state)</code>. This will discard all
+ changes to the page image copies.
+ </p><p>
+ Please note the following points when using the generic WAL record
+ facility:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ No direct modifications of buffers are allowed! All modifications must
+ be done in copies acquired from <code class="function">GenericXLogRegisterBuffer()</code>.
+ In other words, code that makes generic WAL records should never call
+ <code class="function">BufferGetPage()</code> for itself. However, it remains the
+ caller's responsibility to pin/unpin and lock/unlock the buffers at
+ appropriate times. Exclusive lock must be held on each target buffer
+ from before <code class="function">GenericXLogRegisterBuffer()</code> until after
+ <code class="function">GenericXLogFinish()</code>.
+ </p></li><li class="listitem"><p>
+ Registrations of buffers (step 2) and modifications of page images
+ (step 3) can be mixed freely, i.e., both steps may be repeated in any
+ sequence. Keep in mind that buffers should be registered in the same
+ order in which locks are to be obtained on them during replay.
+ </p></li><li class="listitem"><p>
+ The maximum number of buffers that can be registered for a generic WAL
+ record is <code class="literal">MAX_GENERIC_XLOG_PAGES</code>. An error will be thrown
+ if this limit is exceeded.
+ </p></li><li class="listitem"><p>
+ Generic WAL assumes that the pages to be modified have standard
+ layout, and in particular that there is no useful data between
+ <code class="structfield">pd_lower</code> and <code class="structfield">pd_upper</code>.
+ </p></li><li class="listitem"><p>
+ Since you are modifying copies of buffer
+ pages, <code class="function">GenericXLogStart()</code> does not start a critical
+ section. Thus, you can safely do memory allocation, error throwing,
+ etc. between <code class="function">GenericXLogStart()</code> and
+ <code class="function">GenericXLogFinish()</code>. The only actual critical section is
+ present inside <code class="function">GenericXLogFinish()</code>. There is no need to
+ worry about calling <code class="function">GenericXLogAbort()</code> during an error
+ exit, either.
+ </p></li><li class="listitem"><p>
+ <code class="function">GenericXLogFinish()</code> takes care of marking buffers dirty
+ and setting their LSNs. You do not need to do this explicitly.
+ </p></li><li class="listitem"><p>
+ For unlogged relations, everything works the same except that no
+ actual WAL record is emitted. Thus, you typically do not need to do
+ any explicit checks for unlogged relations.
+ </p></li><li class="listitem"><p>
+ The generic WAL redo function will acquire exclusive locks to buffers
+ in the same order as they were registered. After redoing all changes,
+ the locks will be released in the same order.
+ </p></li><li class="listitem"><p>
+ If <code class="literal">GENERIC_XLOG_FULL_IMAGE</code> is not specified for a
+ registered buffer, the generic WAL record contains a delta between
+ the old and the new page images. This delta is based on byte-by-byte
+ comparison. This is not very compact for the case of moving data
+ within a page, and might be improved in the future.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.6. Index Cost Estimation Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 66. Custom WAL Resource Managers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/genetic-algorithm.svg b/doc/src/sgml/html/genetic-algorithm.svg
new file mode 100644
index 0000000..fb9fdd1
--- /dev/null
+++ b/doc/src/sgml/html/genetic-algorithm.svg
@@ -0,0 +1,140 @@
+<?xml version="1.0"?>
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: %3 Pages: 1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="583pt" height="580pt" viewBox="0.00 0.00 583.00 580.30">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(72 544.3026)">
+<title>%3</title>
+<polygon fill="#f5f5f5" stroke="none" points="-72,36 -72,-544.3026 511,-544.3026 511,36 -72,36"/>
+<!-- a1 -->
+<g id="node1" class="node">
+<title>a1</title>
+<polygon fill="#ffffff" stroke="#000000" points="187,-508.3026 101,-508.3026 101,-472.3026 187,-472.3026 187,-508.3026"/>
+<text text-anchor="middle" x="144" y="-488.4026" font-family="sans-serif" font-size="8.00" fill="#000000">INITIALIZE t := 0</text>
+</g>
+<!-- a2 -->
+<g id="node2" class="node">
+<title>a2</title>
+<polygon fill="#ffffff" stroke="#000000" points="182,-450.3026 106,-450.3026 106,-414.3026 182,-414.3026 182,-450.3026"/>
+<text text-anchor="middle" x="144" y="-430.4026" font-family="sans-serif" font-size="8.00" fill="#000000">INITIALIZE P(t)</text>
+</g>
+<!-- a1&#45;&gt;a2 -->
+<g id="edge1" class="edge">
+<title>a1-&gt;a2</title>
+<path fill="none" stroke="#000000" d="M144,-472.269C144,-472.269 144,-460.5248 144,-460.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-460.5248 144,-450.5248 140.5001,-460.5249 147.5001,-460.5248"/>
+</g>
+<!-- a3 -->
+<g id="node3" class="node">
+<title>a3</title>
+<polygon fill="#ffffff" stroke="#000000" points="203.5,-392.3026 84.5,-392.3026 84.5,-356.3026 203.5,-356.3026 203.5,-392.3026"/>
+<text text-anchor="middle" x="144" y="-372.4026" font-family="sans-serif" font-size="8.00" fill="#000000">evaluate FITNESS of P(t)</text>
+</g>
+<!-- a2&#45;&gt;a3 -->
+<g id="edge2" class="edge">
+<title>a2-&gt;a3</title>
+<path fill="none" stroke="#000000" d="M144,-414.269C144,-414.269 144,-402.5248 144,-402.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-402.5248 144,-392.5248 140.5001,-402.5249 147.5001,-402.5248"/>
+</g>
+<!-- a4 -->
+<g id="node4" class="node">
+<title>a4</title>
+<polygon fill="#ffffff" stroke="#000000" points="144,-334.3026 0,-316.3026 144,-298.3026 288,-316.3026 144,-334.3026"/>
+<text text-anchor="middle" x="144" y="-314.4026" font-family="sans-serif" font-size="8.00" fill="#000000">STOPPING CRITERION</text>
+</g>
+<!-- a3&#45;&gt;a4 -->
+<g id="edge3" class="edge">
+<title>a3-&gt;a4</title>
+<path fill="none" stroke="#000000" d="M144,-356.269C144,-356.269 144,-344.5248 144,-344.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-344.5248 144,-334.5248 140.5001,-344.5249 147.5001,-344.5248"/>
+</g>
+<!-- a9 -->
+<g id="node5" class="node">
+<title>a9</title>
+<polygon fill="#ffffff" stroke="#000000" points="106,-40.1513 50,-40.1513 50,-4.1513 106,-4.1513 106,-40.1513"/>
+<text text-anchor="middle" x="78" y="-20.2513" font-family="sans-serif" font-size="8.00" fill="#000000">t := t + 1</text>
+</g>
+<!-- a4&#45;&gt;a9 -->
+<g id="edge10" class="edge">
+<title>a4-&gt;a9</title>
+<path fill="none" stroke="#000000" d="M56.75,-299.0314C56.75,-299.0314 56.75,-40.524 56.75,-40.524"/>
+<polygon fill="#000000" stroke="#000000" points="53.2501,-299.0314 56.75,-309.0314 60.2501,-299.0314 53.2501,-299.0314"/>
+</g>
+<!-- end -->
+<g id="node6" class="node">
+<title>end</title>
+<ellipse fill="#ffffff" stroke="#000000" cx="259" cy="-22.1513" rx="18.2761" ry="18.2761"/>
+<ellipse fill="none" stroke="#000000" cx="259" cy="-22.1513" rx="22.3036" ry="22.3036"/>
+<text text-anchor="middle" x="259" y="-20.2513" font-family="sans-serif" font-size="8.00" fill="#000000">end</text>
+</g>
+<!-- a4&#45;&gt;end -->
+<g id="edge5" class="edge">
+<title>a4-&gt;end</title>
+<path fill="none" stroke="#000000" d="M259,-312.5834C259,-312.5834 259,-54.659 259,-54.659"/>
+<polygon fill="#000000" stroke="#000000" points="262.5001,-54.659 259,-44.659 255.5001,-54.6591 262.5001,-54.659"/>
+<text text-anchor="middle" x="246" y="-186.6212" font-family="sans-serif" font-size="10.00" fill="#000000">true  </text>
+</g>
+<!-- a5 -->
+<g id="node7" class="node">
+<title>a5</title>
+<polygon fill="#ffffff" stroke="#000000" points="216,-276.3026 72,-276.3026 72,-240.3026 216,-240.3026 216,-276.3026"/>
+<text text-anchor="middle" x="144" y="-256.4026" font-family="sans-serif" font-size="8.00" fill="#000000">P'(t) := RECOMBINATION{P(t)}</text>
+</g>
+<!-- a4&#45;&gt;a5 -->
+<g id="edge4" class="edge">
+<title>a4-&gt;a5</title>
+<path fill="none" stroke="#000000" d="M144,-298.269C144,-298.269 144,-286.5248 144,-286.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-286.5248 144,-276.5248 140.5001,-286.5249 147.5001,-286.5248"/>
+<text text-anchor="middle" x="127" y="-284.3969" font-family="sans-serif" font-size="10.00" fill="#000000">false   </text>
+</g>
+<!-- a6 -->
+<g id="node8" class="node">
+<title>a6</title>
+<polygon fill="#ffffff" stroke="#000000" points="204.5,-218.3026 83.5,-218.3026 83.5,-182.3026 204.5,-182.3026 204.5,-218.3026"/>
+<text text-anchor="middle" x="144" y="-198.4026" font-family="sans-serif" font-size="8.00" fill="#000000">P''(t) := MUTATION{P'(t)}</text>
+</g>
+<!-- a5&#45;&gt;a6 -->
+<g id="edge6" class="edge">
+<title>a5-&gt;a6</title>
+<path fill="none" stroke="#000000" d="M144,-240.269C144,-240.269 144,-228.5248 144,-228.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-228.5248 144,-218.5248 140.5001,-228.5249 147.5001,-228.5248"/>
+</g>
+<!-- a7 -->
+<g id="node9" class="node">
+<title>a7</title>
+<polygon fill="#ffffff" stroke="#000000" points="224.5,-160.3026 63.5,-160.3026 63.5,-124.3026 224.5,-124.3026 224.5,-160.3026"/>
+<text text-anchor="middle" x="144" y="-140.4026" font-family="sans-serif" font-size="8.00" fill="#000000">P(t+1) := SELECTION{P''(t) + P(t)}</text>
+</g>
+<!-- a6&#45;&gt;a7 -->
+<g id="edge7" class="edge">
+<title>a6-&gt;a7</title>
+<path fill="none" stroke="#000000" d="M144,-182.269C144,-182.269 144,-170.5248 144,-170.5248"/>
+<polygon fill="#000000" stroke="#000000" points="147.5001,-170.5248 144,-160.5248 140.5001,-170.5249 147.5001,-170.5248"/>
+</g>
+<!-- a8 -->
+<g id="node10" class="node">
+<title>a8</title>
+<polygon fill="#ffffff" stroke="#000000" points="196.5,-102.3026 73.5,-102.3026 73.5,-66.3026 196.5,-66.3026 196.5,-102.3026"/>
+<text text-anchor="middle" x="135" y="-82.4026" font-family="sans-serif" font-size="8.00" fill="#000000">evaluate FITNESS of P''(t)</text>
+</g>
+<!-- a7&#45;&gt;a8 -->
+<g id="edge8" class="edge">
+<title>a7-&gt;a8</title>
+<path fill="none" stroke="#000000" d="M135,-124.269C135,-124.269 135,-112.5248 135,-112.5248"/>
+<polygon fill="#000000" stroke="#000000" points="138.5001,-112.5248 135,-102.5248 131.5001,-112.5249 138.5001,-112.5248"/>
+</g>
+<!-- a8&#45;&gt;a9 -->
+<g id="edge9" class="edge">
+<title>a8-&gt;a9</title>
+<path fill="none" stroke="#000000" d="M89.75,-65.9913C89.75,-65.9913 89.75,-50.5465 89.75,-50.5465"/>
+<polygon fill="#000000" stroke="#000000" points="93.2501,-50.5464 89.75,-40.5465 86.2501,-50.5465 93.2501,-50.5464"/>
+</g>
+<!-- expl -->
+<g id="node11" class="node">
+<title>expl</title>
+<polygon fill="#f5f5f5" stroke="none" points="439,-508.3026 209,-508.3026 209,-472.3026 439,-472.3026 439,-508.3026"/>
+<text text-anchor="start" x="217" y="-493.3026" font-family="sans-serif" font-size="10.00" fill="#000000">P(t): generation of ancestors at a time t</text>
+<text text-anchor="start" x="217" y="-482.3026" font-family="sans-serif" font-size="10.00" fill="#000000">P''(t): generation of descendants at a time t</text>
+</g>
+</g>
+</svg>
diff --git a/doc/src/sgml/html/geqo-biblio.html b/doc/src/sgml/html/geqo-biblio.html
new file mode 100644
index 0000000..07416a5
--- /dev/null
+++ b/doc/src/sgml/html/geqo-biblio.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>62.4. Further Reading</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL" /><link rel="next" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">62.4. Further Reading</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><th width="60%" align="center">Chapter 62. Genetic Query Optimizer</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Next</a></td></tr></table><hr /></div><div class="sect1" id="GEQO-BIBLIO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">62.4. Further Reading</h2></div></div></div><p>
+ The following resources contain additional information about
+ genetic algorithms:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="ulink" href="http://www.faqs.org/faqs/ai-faq/genetic/part1/" target="_top">
+ The Hitch-Hiker's Guide to Evolutionary Computation</a>, (FAQ for <a class="ulink" href="news://comp.ai.genetic" target="_top">news://comp.ai.genetic</a>)
+ </p></li><li class="listitem"><p>
+ <a class="ulink" href="https://www.red3d.com/cwr/evolve.html" target="_top">
+ Evolutionary Computation and its application to art and design</a>, by
+ Craig Reynolds
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="biblio.html#ELMA04" title="Fundamentals of Database Systems">[elma04]</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="biblio.html#FONG" title="The design and implementation of the POSTGRES query optimizer">[fong]</a>
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Next</a></td></tr><tr><td width="40%" align="left" valign="top">62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 63. Table Access Method Interface Definition</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/geqo-intro.html b/doc/src/sgml/html/geqo-intro.html
new file mode 100644
index 0000000..bfbf675
--- /dev/null
+++ b/doc/src/sgml/html/geqo-intro.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>62.1. Query Handling as a Complex Optimization Problem</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo.html" title="Chapter 62. Genetic Query Optimizer" /><link rel="next" href="geqo-intro2.html" title="62.2. Genetic Algorithms" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">62.1. Query Handling as a Complex Optimization Problem</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><th width="60%" align="center">Chapter 62. Genetic Query Optimizer</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo-intro2.html" title="62.2. Genetic Algorithms">Next</a></td></tr></table><hr /></div><div class="sect1" id="GEQO-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">62.1. Query Handling as a Complex Optimization Problem</h2></div></div></div><p>
+ Among all relational operators the most difficult one to process
+ and optimize is the <em class="firstterm">join</em>. The number of
+ possible query plans grows exponentially with the
+ number of joins in the query. Further optimization effort is
+ caused by the support of a variety of <em class="firstterm">join
+ methods</em> (e.g., nested loop, hash join, merge join in
+ <span class="productname">PostgreSQL</span>) to process individual joins
+ and a diversity of <em class="firstterm">indexes</em> (e.g.,
+ B-tree, hash, GiST and GIN in <span class="productname">PostgreSQL</span>) as
+ access paths for relations.
+ </p><p>
+ The normal <span class="productname">PostgreSQL</span> query optimizer
+ performs a <em class="firstterm">near-exhaustive search</em> over the
+ space of alternative strategies. This algorithm, first introduced
+ in IBM's System R database, produces a near-optimal join order,
+ but can take an enormous amount of time and memory space when the
+ number of joins in the query grows large. This makes the ordinary
+ <span class="productname">PostgreSQL</span> query optimizer
+ inappropriate for queries that join a large number of tables.
+ </p><p>
+ The Institute of Automatic Control at the University of Mining and
+ Technology, in Freiberg, Germany, encountered some problems when
+ it wanted to use <span class="productname">PostgreSQL</span> as the
+ backend for a decision support knowledge based system for the
+ maintenance of an electrical power grid. The DBMS needed to handle
+ large join queries for the inference machine of the knowledge
+ based system. The number of joins in these queries made using the
+ normal query optimizer infeasible.
+ </p><p>
+ In the following we describe the implementation of a
+ <em class="firstterm">genetic algorithm</em> to solve the join
+ ordering problem in a manner that is efficient for queries
+ involving large numbers of joins.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo-intro2.html" title="62.2. Genetic Algorithms">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 62. Genetic Query Optimizer </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 62.2. Genetic Algorithms</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/geqo-intro2.html b/doc/src/sgml/html/geqo-intro2.html
new file mode 100644
index 0000000..75c54ca
--- /dev/null
+++ b/doc/src/sgml/html/geqo-intro2.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>62.2. Genetic Algorithms</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem" /><link rel="next" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">62.2. Genetic Algorithms</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><th width="60%" align="center">Chapter 62. Genetic Query Optimizer</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="GEQO-INTRO2"><div class="titlepage"><div><div><h2 class="title" style="clear: both">62.2. Genetic Algorithms</h2></div></div></div><p>
+ The genetic algorithm (<acronym class="acronym">GA</acronym>) is a heuristic optimization method which
+ operates through randomized search. The set of possible solutions for the
+ optimization problem is considered as a
+ <em class="firstterm">population</em> of <em class="firstterm">individuals</em>.
+ The degree of adaptation of an individual to its environment is specified
+ by its <em class="firstterm">fitness</em>.
+ </p><p>
+ The coordinates of an individual in the search space are represented
+ by <em class="firstterm">chromosomes</em>, in essence a set of character
+ strings. A <em class="firstterm">gene</em> is a
+ subsection of a chromosome which encodes the value of a single parameter
+ being optimized. Typical encodings for a gene could be <em class="firstterm">binary</em> or
+ <em class="firstterm">integer</em>.
+ </p><p>
+ Through simulation of the evolutionary operations <em class="firstterm">recombination</em>,
+ <em class="firstterm">mutation</em>, and
+ <em class="firstterm">selection</em> new generations of search points are found
+ that show a higher average fitness than their ancestors. <a class="xref" href="geqo-intro2.html#GEQO-FIGURE" title="Figure 62.1. Structure of a Genetic Algorithm">Figure 62.1</a>
+ illustrates these steps.
+ </p><div class="figure" id="GEQO-FIGURE"><p class="title"><strong>Figure 62.1. Structure of a Genetic Algorithm</strong></p><div class="figure-contents"><div class="mediaobject"><object type="image/svg+xml" data="genetic-algorithm.svg" width="100%"></object></div></div></div><br class="figure-break" /><p>
+ According to the <span class="systemitem">comp.ai.genetic</span> <acronym class="acronym">FAQ</acronym> it cannot be stressed too
+ strongly that a <acronym class="acronym">GA</acronym> is not a pure random search for a solution to a
+ problem. A <acronym class="acronym">GA</acronym> uses stochastic processes, but the result is distinctly
+ non-random (better than random).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo-pg-intro.html" title="62.3. Genetic Query Optimization (GEQO) in PostgreSQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">62.1. Query Handling as a Complex Optimization Problem </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/geqo-pg-intro.html b/doc/src/sgml/html/geqo-pg-intro.html
new file mode 100644
index 0000000..991acc1
--- /dev/null
+++ b/doc/src/sgml/html/geqo-pg-intro.html
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>62.3. Genetic Query Optimization (GEQO) in PostgreSQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo-intro2.html" title="62.2. Genetic Algorithms" /><link rel="next" href="geqo-biblio.html" title="62.4. Further Reading" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo-intro2.html" title="62.2. Genetic Algorithms">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><th width="60%" align="center">Chapter 62. Genetic Query Optimizer</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo-biblio.html" title="62.4. Further Reading">Next</a></td></tr></table><hr /></div><div class="sect1" id="GEQO-PG-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="geqo-pg-intro.html#id-1.10.13.5.6">62.3.1. Generating Possible Plans with <acronym class="acronym">GEQO</acronym></a></span></dt><dt><span class="sect2"><a href="geqo-pg-intro.html#GEQO-FUTURE">62.3.2. Future Implementation Tasks for
+ <span class="productname">PostgreSQL</span> <acronym class="acronym">GEQO</acronym></a></span></dt></dl></div><p>
+ The <acronym class="acronym">GEQO</acronym> module approaches the query
+ optimization problem as though it were the well-known traveling salesman
+ problem (<acronym class="acronym">TSP</acronym>).
+ Possible query plans are encoded as integer strings. Each string
+ represents the join order from one relation of the query to the next.
+ For example, the join tree
+</p><pre class="literallayout">
+ /\
+ /\ 2
+ /\ 3
+4 1
+</pre><p>
+ is encoded by the integer string '4-1-3-2',
+ which means, first join relation '4' and '1', then '3', and
+ then '2', where 1, 2, 3, 4 are relation IDs within the
+ <span class="productname">PostgreSQL</span> optimizer.
+ </p><p>
+ Specific characteristics of the <acronym class="acronym">GEQO</acronym>
+ implementation in <span class="productname">PostgreSQL</span>
+ are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ Usage of a <em class="firstterm">steady state</em> <acronym class="acronym">GA</acronym> (replacement of the least fit
+ individuals in a population, not whole-generational replacement)
+ allows fast convergence towards improved query plans. This is
+ essential for query handling with reasonable time;
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Usage of <em class="firstterm">edge recombination crossover</em>
+ which is especially suited to keep edge losses low for the
+ solution of the <acronym class="acronym">TSP</acronym> by means of a
+ <acronym class="acronym">GA</acronym>;
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Mutation as genetic operator is deprecated so that no repair
+ mechanisms are needed to generate legal <acronym class="acronym">TSP</acronym> tours.
+ </p></li></ul></div><p>
+ </p><p>
+ Parts of the <acronym class="acronym">GEQO</acronym> module are adapted from D. Whitley's
+ Genitor algorithm.
+ </p><p>
+ The <acronym class="acronym">GEQO</acronym> module allows
+ the <span class="productname">PostgreSQL</span> query optimizer to
+ support large join queries effectively through
+ non-exhaustive search.
+ </p><div class="sect2" id="id-1.10.13.5.6"><div class="titlepage"><div><div><h3 class="title">62.3.1. Generating Possible Plans with <acronym class="acronym">GEQO</acronym></h3></div></div></div><p>
+ The <acronym class="acronym">GEQO</acronym> planning process uses the standard planner
+ code to generate plans for scans of individual relations. Then join
+ plans are developed using the genetic approach. As shown above, each
+ candidate join plan is represented by a sequence in which to join
+ the base relations. In the initial stage, the <acronym class="acronym">GEQO</acronym>
+ code simply generates some possible join sequences at random. For each
+ join sequence considered, the standard planner code is invoked to
+ estimate the cost of performing the query using that join sequence.
+ (For each step of the join sequence, all three possible join strategies
+ are considered; and all the initially-determined relation scan plans
+ are available. The estimated cost is the cheapest of these
+ possibilities.) Join sequences with lower estimated cost are considered
+ <span class="quote">“<span class="quote">more fit</span>”</span> than those with higher cost. The genetic algorithm
+ discards the least fit candidates. Then new candidates are generated
+ by combining genes of more-fit candidates — that is, by using
+ randomly-chosen portions of known low-cost join sequences to create
+ new sequences for consideration. This process is repeated until a
+ preset number of join sequences have been considered; then the best
+ one found at any time during the search is used to generate the finished
+ plan.
+ </p><p>
+ This process is inherently nondeterministic, because of the randomized
+ choices made during both the initial population selection and subsequent
+ <span class="quote">“<span class="quote">mutation</span>”</span> 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 <a class="xref" href="runtime-config-query.html#GUC-GEQO-SEED">geqo_seed</a>
+ parameter setting. As long as <code class="varname">geqo_seed</code> 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
+ with different search paths, try changing <code class="varname">geqo_seed</code>.
+ </p></div><div class="sect2" id="GEQO-FUTURE"><div class="titlepage"><div><div><h3 class="title">62.3.2. Future Implementation Tasks for
+ <span class="productname">PostgreSQL</span> <acronym class="acronym">GEQO</acronym></h3></div></div></div><p>
+ Work is still needed to improve the genetic algorithm parameter
+ settings.
+ In file <code class="filename">src/backend/optimizer/geqo/geqo_main.c</code>,
+ routines
+ <code class="function">gimme_pool_size</code> and <code class="function">gimme_number_generations</code>,
+ we have to find a compromise for the parameter settings
+ to satisfy two competing demands:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ Optimality of the query plan
+ </p></li><li class="listitem"><p>
+ Computing time
+ </p></li></ul></div><p>
+ </p><p>
+ In the current implementation, the fitness of each candidate join
+ sequence is estimated by running the standard planner's join selection
+ and cost estimation code from scratch. To the extent that different
+ candidates use similar sub-sequences of joins, a great deal of work
+ will be repeated. This could be made significantly faster by retaining
+ cost estimates for sub-joins. The problem is to avoid expending
+ unreasonable amounts of memory on retaining that state.
+ </p><p>
+ At a more basic level, it is not clear that solving query optimization
+ with a GA algorithm designed for TSP is appropriate. In the TSP case,
+ the cost associated with any substring (partial tour) is independent
+ of the rest of the tour, but this is certainly not true for query
+ optimization. Thus it is questionable whether edge recombination
+ crossover is the most effective mutation procedure.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo-intro2.html" title="62.2. Genetic Algorithms">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo-biblio.html" title="62.4. Further Reading">Next</a></td></tr><tr><td width="40%" align="left" valign="top">62.2. Genetic Algorithms </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 62.4. Further Reading</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/geqo.html b/doc/src/sgml/html/geqo.html
new file mode 100644
index 0000000..70adc1c
--- /dev/null
+++ b/doc/src/sgml/html/geqo.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 62. Genetic Query Optimizer</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="custom-scan-execution.html" title="61.3. Executing Custom Scans" /><link rel="next" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 62. Genetic Query Optimizer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="custom-scan-execution.html" title="61.3. Executing Custom Scans">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem">Next</a></td></tr></table><hr /></div><div class="chapter" id="GEQO"><div class="titlepage"><div><div><h2 class="title">Chapter 62. Genetic Query Optimizer</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="geqo-intro.html">62.1. Query Handling as a Complex Optimization Problem</a></span></dt><dt><span class="sect1"><a href="geqo-intro2.html">62.2. Genetic Algorithms</a></span></dt><dt><span class="sect1"><a href="geqo-pg-intro.html">62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL</a></span></dt><dd><dl><dt><span class="sect2"><a href="geqo-pg-intro.html#id-1.10.13.5.6">62.3.1. Generating Possible Plans with <acronym class="acronym">GEQO</acronym></a></span></dt><dt><span class="sect2"><a href="geqo-pg-intro.html#GEQO-FUTURE">62.3.2. Future Implementation Tasks for
+ <span class="productname">PostgreSQL</span> <acronym class="acronym">GEQO</acronym></a></span></dt></dl></dd><dt><span class="sect1"><a href="geqo-biblio.html">62.4. Further Reading</a></span></dt></dl></div><p>
+ </p><div class="note"><h3 class="title">Author</h3><p>
+ Written by Martin Utesch (<code class="email">&lt;<a class="email" href="mailto:utesch@aut.tu-freiberg.de">utesch@aut.tu-freiberg.de</a>&gt;</code>)
+ for the Institute of Automatic Control at the University of Mining and Technology in Freiberg, Germany.
+ </p></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="custom-scan-execution.html" title="61.3. Executing Custom Scans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="geqo-intro.html" title="62.1. Query Handling as a Complex Optimization Problem">Next</a></td></tr><tr><td width="40%" align="left" valign="top">61.3. Executing Custom Scans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 62.1. Query Handling as a Complex Optimization Problem</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-builtin-opclasses.html b/doc/src/sgml/html/gin-builtin-opclasses.html
new file mode 100644
index 0000000..ee1b76c
--- /dev/null
+++ b/doc/src/sgml/html/gin-builtin-opclasses.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.2. Built-in Operator Classes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-intro.html" title="70.1. Introduction" /><link rel="next" href="gin-extensibility.html" title="70.3. Extensibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.2. Built-in Operator Classes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-intro.html" title="70.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-extensibility.html" title="70.3. Extensibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-BUILTIN-OPCLASSES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.2. Built-in Operator Classes</h2></div></div></div><p>
+ The core <span class="productname">PostgreSQL</span> distribution
+ includes the <acronym class="acronym">GIN</acronym> operator classes shown in
+ <a class="xref" href="gin-builtin-opclasses.html#GIN-BUILTIN-OPCLASSES-TABLE" title="Table 70.1. Built-in GIN Operator Classes">Table 70.1</a>.
+ (Some of the optional modules described in <a class="xref" href="contrib.html" title="Appendix F. Additional Supplied Modules">Appendix F</a>
+ provide additional <acronym class="acronym">GIN</acronym> operator classes.)
+ </p><div class="table" id="GIN-BUILTIN-OPCLASSES-TABLE"><p class="title"><strong>Table 70.1. Built-in <acronym class="acronym">GIN</acronym> Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Built-in GIN Operator Classes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Indexable Operators</th></tr></thead><tbody><tr><td rowspan="4" valign="middle"><code class="literal">array_ops</code></td><td><code class="literal">&amp;&amp; (anyarray,anyarray)</code></td></tr><tr><td><code class="literal">@&gt; (anyarray,anyarray)</code></td></tr><tr><td><code class="literal">&lt;@ (anyarray,anyarray)</code></td></tr><tr><td><code class="literal">= (anyarray,anyarray)</code></td></tr><tr><td rowspan="6" valign="middle"><code class="literal">jsonb_ops</code></td><td><code class="literal">@&gt; (jsonb,jsonb)</code></td></tr><tr><td><code class="literal">@? (jsonb,jsonpath)</code></td></tr><tr><td><code class="literal">@@ (jsonb,jsonpath)</code></td></tr><tr><td><code class="literal">? (jsonb,text)</code></td></tr><tr><td><code class="literal">?| (jsonb,text[])</code></td></tr><tr><td><code class="literal">?&amp; (jsonb,text[])</code></td></tr><tr><td rowspan="3" valign="middle"><code class="literal">jsonb_path_ops</code></td><td><code class="literal">@&gt; (jsonb,jsonb)</code></td></tr><tr><td><code class="literal">@? (jsonb,jsonpath)</code></td></tr><tr><td><code class="literal">@@ (jsonb,jsonpath)</code></td></tr><tr><td rowspan="2" valign="middle"><code class="literal">tsvector_ops</code></td><td><code class="literal">@@ (tsvector,tsquery)</code></td></tr><tr><td><code class="literal">@@@ (tsvector,tsquery)</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Of the two operator classes for type <code class="type">jsonb</code>, <code class="literal">jsonb_ops</code>
+ is the default. <code class="literal">jsonb_path_ops</code> supports fewer operators but
+ offers better performance for those operators.
+ See <a class="xref" href="datatype-json.html#JSON-INDEXING" title="8.14.4. jsonb Indexing">Section 8.14.4</a> for details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-intro.html" title="70.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-extensibility.html" title="70.3. Extensibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.3. Extensibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-examples.html b/doc/src/sgml/html/gin-examples.html
new file mode 100644
index 0000000..7b97169
--- /dev/null
+++ b/doc/src/sgml/html/gin-examples.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.7. Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-limit.html" title="70.6. Limitations" /><link rel="next" href="brin.html" title="Chapter 71. BRIN Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.7. Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-limit.html" title="70.6. Limitations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="brin.html" title="Chapter 71. BRIN Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.7. Examples</h2></div></div></div><p>
+ The core <span class="productname">PostgreSQL</span> distribution
+ includes the <acronym class="acronym">GIN</acronym> operator classes previously shown in
+ <a class="xref" href="gin-builtin-opclasses.html#GIN-BUILTIN-OPCLASSES-TABLE" title="Table 70.1. Built-in GIN Operator Classes">Table 70.1</a>.
+ The following <code class="filename">contrib</code> modules also contain
+ <acronym class="acronym">GIN</acronym> operator classes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">btree_gin</code></span></dt><dd><p>B-tree equivalent functionality for several data types</p></dd><dt><span class="term"><code class="filename">hstore</code></span></dt><dd><p>Module for storing (key, value) pairs</p></dd><dt><span class="term"><code class="filename">intarray</code></span></dt><dd><p>Enhanced support for <code class="type">int[]</code></p></dd><dt><span class="term"><code class="filename">pg_trgm</code></span></dt><dd><p>Text similarity using trigram matching</p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-limit.html" title="70.6. Limitations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="brin.html" title="Chapter 71. BRIN Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.6. Limitations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 71. BRIN Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-extensibility.html b/doc/src/sgml/html/gin-extensibility.html
new file mode 100644
index 0000000..f7ec4d4
--- /dev/null
+++ b/doc/src/sgml/html/gin-extensibility.html
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.3. Extensibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes" /><link rel="next" href="gin-implementation.html" title="70.4. Implementation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.3. Extensibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-implementation.html" title="70.4. Implementation">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-EXTENSIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.3. Extensibility</h2></div></div></div><p>
+ The <acronym class="acronym">GIN</acronym> interface has a high level of abstraction,
+ requiring the access method implementer only to implement the semantics of
+ the data type being accessed. The <acronym class="acronym">GIN</acronym> layer itself
+ takes care of concurrency, logging and searching the tree structure.
+ </p><p>
+ All it takes to get a <acronym class="acronym">GIN</acronym> access method working is to
+ implement a few user-defined methods, which define the behavior of
+ keys in the tree and the relationships between keys, indexed items,
+ and indexable queries. In short, <acronym class="acronym">GIN</acronym> combines
+ extensibility with generality, code reuse, and a clean interface.
+ </p><p>
+ There are two methods that an operator class for
+ <acronym class="acronym">GIN</acronym> must provide:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">Datum *extractValue(Datum itemValue, int32 *nkeys,
+ bool **nullFlags)</code></span></dt><dd><p>
+ Returns a palloc'd array of keys given an item to be indexed. The
+ number of returned keys must be stored into <code class="literal">*nkeys</code>.
+ If any of the keys can be null, also palloc an array of
+ <code class="literal">*nkeys</code> <code class="type">bool</code> fields, store its address at
+ <code class="literal">*nullFlags</code>, and set these null flags as needed.
+ <code class="literal">*nullFlags</code> can be left <code class="symbol">NULL</code> (its initial value)
+ if all keys are non-null.
+ The return value can be <code class="symbol">NULL</code> if the item contains no keys.
+ </p></dd><dt><span class="term"><code class="function">Datum *extractQuery(Datum query, int32 *nkeys,
+ StrategyNumber n, bool **pmatch, Pointer **extra_data,
+ bool **nullFlags, int32 *searchMode)</code></span></dt><dd><p>
+ Returns a palloc'd array of keys given a value to be queried; that is,
+ <code class="literal">query</code> is the value on the right-hand side of an
+ indexable operator whose left-hand side is the indexed column.
+ <code class="literal">n</code> is the strategy number of the operator within the
+ operator class (see <a class="xref" href="xindex.html#XINDEX-STRATEGIES" title="38.16.2. Index Method Strategies">Section 38.16.2</a>).
+ Often, <code class="function">extractQuery</code> will need
+ to consult <code class="literal">n</code> to determine the data type of
+ <code class="literal">query</code> and the method it should use to extract key values.
+ The number of returned keys must be stored into <code class="literal">*nkeys</code>.
+ If any of the keys can be null, also palloc an array of
+ <code class="literal">*nkeys</code> <code class="type">bool</code> fields, store its address at
+ <code class="literal">*nullFlags</code>, and set these null flags as needed.
+ <code class="literal">*nullFlags</code> can be left <code class="symbol">NULL</code> (its initial value)
+ if all keys are non-null.
+ The return value can be <code class="symbol">NULL</code> if the <code class="literal">query</code> contains no keys.
+ </p><p>
+ <code class="literal">searchMode</code> is an output argument that allows
+ <code class="function">extractQuery</code> to specify details about how the search
+ will be done.
+ If <code class="literal">*searchMode</code> is set to
+ <code class="literal">GIN_SEARCH_MODE_DEFAULT</code> (which is the value it is
+ initialized to before call), only items that match at least one of
+ the returned keys are considered candidate matches.
+ If <code class="literal">*searchMode</code> is set to
+ <code class="literal">GIN_SEARCH_MODE_INCLUDE_EMPTY</code>, then in addition to items
+ containing at least one matching key, items that contain no keys at
+ all are considered candidate matches. (This mode is useful for
+ implementing is-subset-of operators, for example.)
+ If <code class="literal">*searchMode</code> is set to <code class="literal">GIN_SEARCH_MODE_ALL</code>,
+ then all non-null items in the index are considered candidate
+ matches, whether they match any of the returned keys or not. (This
+ mode is much slower than the other two choices, since it requires
+ scanning essentially the entire index, but it may be necessary to
+ implement corner cases correctly. An operator that needs this mode
+ in most cases is probably not a good candidate for a GIN operator
+ class.)
+ The symbols to use for setting this mode are defined in
+ <code class="filename">access/gin.h</code>.
+ </p><p>
+ <code class="literal">pmatch</code> is an output argument for use when partial match
+ is supported. To use it, <code class="function">extractQuery</code> must allocate
+ an array of <code class="literal">*nkeys</code> <code class="type">bool</code>s and store its address at
+ <code class="literal">*pmatch</code>. Each element of the array should be set to true
+ if the corresponding key requires partial match, false if not.
+ If <code class="literal">*pmatch</code> is set to <code class="symbol">NULL</code> then GIN assumes partial match
+ is not required. The variable is initialized to <code class="symbol">NULL</code> before call,
+ so this argument can simply be ignored by operator classes that do
+ not support partial match.
+ </p><p>
+ <code class="literal">extra_data</code> is an output argument that allows
+ <code class="function">extractQuery</code> to pass additional data to the
+ <code class="function">consistent</code> and <code class="function">comparePartial</code> methods.
+ To use it, <code class="function">extractQuery</code> must allocate
+ an array of <code class="literal">*nkeys</code> pointers and store its address at
+ <code class="literal">*extra_data</code>, then store whatever it wants to into the
+ individual pointers. The variable is initialized to <code class="symbol">NULL</code> before
+ call, so this argument can simply be ignored by operator classes that
+ do not require extra data. If <code class="literal">*extra_data</code> is set, the
+ whole array is passed to the <code class="function">consistent</code> method, and
+ the appropriate element to the <code class="function">comparePartial</code> method.
+ </p></dd></dl></div><p>
+
+ An operator class must also provide a function to check if an indexed item
+ matches the query. It comes in two flavors, a Boolean <code class="function">consistent</code>
+ function, and a ternary <code class="function">triConsistent</code> function.
+ <code class="function">triConsistent</code> covers the functionality of both, so providing
+ <code class="function">triConsistent</code> alone is sufficient. However, if the Boolean
+ variant is significantly cheaper to calculate, it can be advantageous to
+ provide both. If only the Boolean variant is provided, some optimizations
+ that depend on refuting index items before fetching all the keys are
+ disabled.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">bool consistent(bool check[], StrategyNumber n, Datum query,
+ int32 nkeys, Pointer extra_data[], bool *recheck,
+ Datum queryKeys[], bool nullFlags[])</code></span></dt><dd><p>
+ Returns true if an indexed item satisfies the query operator with
+ strategy number <code class="literal">n</code> (or might satisfy it, if the recheck
+ indication is returned). This function does not have direct access
+ to the indexed item's value, since <acronym class="acronym">GIN</acronym> does not
+ store items explicitly. Rather, what is available is knowledge
+ about which key values extracted from the query appear in a given
+ indexed item. The <code class="literal">check</code> array has length
+ <code class="literal">nkeys</code>, which is the same as the number of keys previously
+ returned by <code class="function">extractQuery</code> for this <code class="literal">query</code> datum.
+ Each element of the
+ <code class="literal">check</code> array is true if the indexed item contains the
+ corresponding query key, i.e., if (check[i] == true) the i-th key of the
+ <code class="function">extractQuery</code> result array is present in the indexed item.
+ The original <code class="literal">query</code> datum is
+ passed in case the <code class="function">consistent</code> method needs to consult it,
+ and so are the <code class="literal">queryKeys[]</code> and <code class="literal">nullFlags[]</code>
+ arrays previously returned by <code class="function">extractQuery</code>.
+ <code class="literal">extra_data</code> is the extra-data array returned by
+ <code class="function">extractQuery</code>, or <code class="symbol">NULL</code> if none.
+ </p><p>
+ When <code class="function">extractQuery</code> returns a null key in
+ <code class="literal">queryKeys[]</code>, the corresponding <code class="literal">check[]</code> element
+ is true if the indexed item contains a null key; that is, the
+ semantics of <code class="literal">check[]</code> are like <code class="literal">IS NOT DISTINCT
+ FROM</code>. The <code class="function">consistent</code> function can examine the
+ corresponding <code class="literal">nullFlags[]</code> element if it needs to tell
+ the difference between a regular value match and a null match.
+ </p><p>
+ On success, <code class="literal">*recheck</code> should be set to true if the heap
+ tuple needs to be rechecked against the query operator, or false if
+ the index test is exact. That is, a false return value guarantees
+ that the heap tuple does not match the query; a true return value with
+ <code class="literal">*recheck</code> set to false guarantees that the heap tuple does
+ match the query; and a true return value with
+ <code class="literal">*recheck</code> set to true means that the heap tuple might match
+ the query, so it needs to be fetched and rechecked by evaluating the
+ query operator directly against the originally indexed item.
+ </p></dd><dt><span class="term"><code class="function">GinTernaryValue triConsistent(GinTernaryValue check[], StrategyNumber n, Datum query,
+ int32 nkeys, Pointer extra_data[],
+ Datum queryKeys[], bool nullFlags[])</code></span></dt><dd><p>
+ <code class="function">triConsistent</code> is similar to <code class="function">consistent</code>,
+ but instead of Booleans in the <code class="literal">check</code> vector, there are
+ three possible values for each
+ key: <code class="literal">GIN_TRUE</code>, <code class="literal">GIN_FALSE</code> and
+ <code class="literal">GIN_MAYBE</code>. <code class="literal">GIN_FALSE</code> and <code class="literal">GIN_TRUE</code>
+ have the same meaning as regular Boolean values, while
+ <code class="literal">GIN_MAYBE</code> means that the presence of that key is not known.
+ When <code class="literal">GIN_MAYBE</code> values are present, the function should only
+ return <code class="literal">GIN_TRUE</code> if the item certainly matches whether or
+ not the index item contains the corresponding query keys. Likewise, the
+ function must return <code class="literal">GIN_FALSE</code> only if the item certainly
+ does not match, whether or not it contains the <code class="literal">GIN_MAYBE</code>
+ keys. If the result depends on the <code class="literal">GIN_MAYBE</code> entries, i.e.,
+ the match cannot be confirmed or refuted based on the known query keys,
+ the function must return <code class="literal">GIN_MAYBE</code>.
+ </p><p>
+ When there are no <code class="literal">GIN_MAYBE</code> values in the <code class="literal">check</code>
+ vector, a <code class="literal">GIN_MAYBE</code> return value is the equivalent of
+ setting the <code class="literal">recheck</code> flag in the
+ Boolean <code class="function">consistent</code> function.
+ </p></dd></dl></div><p>
+ </p><p>
+ In addition, GIN must have a way to sort the key values stored in the index.
+ The operator class can define the sort ordering by specifying a comparison
+ method:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">int compare(Datum a, Datum b)</code></span></dt><dd><p>
+ Compares two keys (not indexed items!) and returns an integer less than
+ zero, zero, or greater than zero, indicating whether the first key is
+ less than, equal to, or greater than the second. Null keys are never
+ passed to this function.
+ </p></dd></dl></div><p>
+
+ Alternatively, if the operator class does not provide a <code class="function">compare</code>
+ method, GIN will look up the default btree operator class for the index
+ key data type, and use its comparison function. It is recommended to
+ specify the comparison function in a GIN operator class that is meant for
+ just one data type, as looking up the btree operator class costs a few
+ cycles. However, polymorphic GIN operator classes (such
+ as <code class="literal">array_ops</code>) typically cannot specify a single comparison
+ function.
+ </p><p>
+ An operator class for <acronym class="acronym">GIN</acronym> can optionally supply the
+ following methods:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">int comparePartial(Datum partial_key, Datum key, StrategyNumber n,
+ Pointer extra_data)</code></span></dt><dd><p>
+ Compare a partial-match query key to an index key. Returns an integer
+ whose sign indicates the result: less than zero means the index key
+ does not match the query, but the index scan should continue; zero
+ means that the index key does match the query; greater than zero
+ indicates that the index scan should stop because no more matches
+ are possible. The strategy number <code class="literal">n</code> of the operator
+ that generated the partial match query is provided, in case its
+ semantics are needed to determine when to end the scan. Also,
+ <code class="literal">extra_data</code> is the corresponding element of the extra-data
+ array made by <code class="function">extractQuery</code>, or <code class="symbol">NULL</code> if none.
+ Null keys are never passed to this function.
+ </p></dd><dt><span class="term"><code class="function">void options(local_relopts *relopts)</code></span></dt><dd><p>
+ Defines a set of user-visible parameters that control operator class
+ behavior.
+ </p><p>
+ The <code class="function">options</code> function is passed a pointer to a
+ <code class="structname">local_relopts</code> struct, which needs to be
+ filled with a set of operator class specific options. The options
+ can be accessed from other support functions using the
+ <code class="literal">PG_HAS_OPCLASS_OPTIONS()</code> and
+ <code class="literal">PG_GET_OPCLASS_OPTIONS()</code> macros.
+ </p><p>
+ Since both key extraction of indexed values and representation of the
+ key in <acronym class="acronym">GIN</acronym> are flexible, they may depend on
+ user-specified parameters.
+ </p></dd></dl></div><p>
+ </p><p>
+ To support <span class="quote">“<span class="quote">partial match</span>”</span> queries, an operator class must
+ provide the <code class="function">comparePartial</code> method, and its
+ <code class="function">extractQuery</code> method must set the <code class="literal">pmatch</code>
+ parameter when a partial-match query is encountered. See
+ <a class="xref" href="gin-implementation.html#GIN-PARTIAL-MATCH" title="70.4.2. Partial Match Algorithm">Section 70.4.2</a> for details.
+ </p><p>
+ The actual data types of the various <code class="literal">Datum</code> values mentioned
+ above vary depending on the operator class. The item values passed to
+ <code class="function">extractValue</code> are always of the operator class's input type, and
+ all key values must be of the class's <code class="literal">STORAGE</code> type. The type of
+ the <code class="literal">query</code> argument passed to <code class="function">extractQuery</code>,
+ <code class="function">consistent</code> and <code class="function">triConsistent</code> is whatever is the
+ right-hand input type of the class member operator identified by the
+ strategy number. This need not be the same as the indexed type, so long as
+ key values of the correct type can be extracted from it. However, it is
+ recommended that the SQL declarations of these three support functions use
+ the opclass's indexed data type for the <code class="literal">query</code> argument, even
+ though the actual type might be something else depending on the operator.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-implementation.html" title="70.4. Implementation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.2. Built-in Operator Classes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.4. Implementation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-implementation.html b/doc/src/sgml/html/gin-implementation.html
new file mode 100644
index 0000000..e0b1853
--- /dev/null
+++ b/doc/src/sgml/html/gin-implementation.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.4. Implementation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-extensibility.html" title="70.3. Extensibility" /><link rel="next" href="gin-tips.html" title="70.5. GIN Tips and Tricks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.4. Implementation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-extensibility.html" title="70.3. Extensibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.4. Implementation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="gin-implementation.html#GIN-FAST-UPDATE">70.4.1. GIN Fast Update Technique</a></span></dt><dt><span class="sect2"><a href="gin-implementation.html#GIN-PARTIAL-MATCH">70.4.2. Partial Match Algorithm</a></span></dt></dl></div><p>
+ Internally, a <acronym class="acronym">GIN</acronym> index contains a B-tree index
+ constructed over keys, where each key is an element of one or more indexed
+ items (a member of an array, for example) and where each tuple in a leaf
+ page contains either a pointer to a B-tree of heap pointers (a
+ <span class="quote">“<span class="quote">posting tree</span>”</span>), or a simple list of heap pointers (a <span class="quote">“<span class="quote">posting
+ list</span>”</span>) when the list is small enough to fit into a single index tuple along
+ with the key value. <a class="xref" href="gin-implementation.html#GIN-INTERNALS-FIGURE" title="Figure 70.1. GIN Internals">Figure 70.1</a> illustrates
+ these components of a GIN index.
+ </p><p>
+ As of <span class="productname">PostgreSQL</span> 9.1, null key values can be
+ included in the index. Also, placeholder nulls are included in the index
+ for indexed items that are null or contain no keys according to
+ <code class="function">extractValue</code>. This allows searches that should find empty
+ items to do so.
+ </p><p>
+ Multicolumn <acronym class="acronym">GIN</acronym> indexes are implemented by building
+ a single B-tree over composite values (column number, key value). The
+ key values for different columns can be of different types.
+ </p><div class="figure" id="GIN-INTERNALS-FIGURE"><p class="title"><strong>Figure 70.1. GIN Internals</strong></p><div class="figure-contents"><div class="mediaobject"><object type="image/svg+xml" data="gin.svg" width="100%"></object></div></div></div><br class="figure-break" /><div class="sect2" id="GIN-FAST-UPDATE"><div class="titlepage"><div><div><h3 class="title">70.4.1. GIN Fast Update Technique</h3></div></div></div><p>
+ Updating a <acronym class="acronym">GIN</acronym> index tends to be slow because of the
+ intrinsic nature of inverted indexes: inserting or updating one heap row
+ can cause many inserts into the index (one for each key extracted
+ from the indexed item).
+ <acronym class="acronym">GIN</acronym> is capable of postponing much of this work by inserting
+ new tuples into a temporary, unsorted list of pending entries.
+ When the table is vacuumed or autoanalyzed, or when
+ <code class="function">gin_clean_pending_list</code> function is called, or if the
+ pending list becomes larger than
+ <a class="xref" href="runtime-config-client.html#GUC-GIN-PENDING-LIST-LIMIT">gin_pending_list_limit</a>, the entries are moved to the
+ main <acronym class="acronym">GIN</acronym> data structure using the same bulk insert
+ techniques used during initial index creation. This greatly improves
+ <acronym class="acronym">GIN</acronym> index update speed, even counting the additional
+ vacuum overhead. Moreover the overhead work can be done by a background
+ process instead of in foreground query processing.
+ </p><p>
+ The main disadvantage of this approach is that searches must scan the list
+ of pending entries in addition to searching the regular index, and so
+ a large list of pending entries will slow searches significantly.
+ Another disadvantage is that, while most updates are fast, an update
+ that causes the pending list to become <span class="quote">“<span class="quote">too large</span>”</span> will incur an
+ immediate cleanup cycle and thus be much slower than other updates.
+ Proper use of autovacuum can minimize both of these problems.
+ </p><p>
+ If consistent response time is more important than update speed,
+ use of pending entries can be disabled by turning off the
+ <code class="literal">fastupdate</code> storage parameter for a
+ <acronym class="acronym">GIN</acronym> index. See <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>
+ for details.
+ </p></div><div class="sect2" id="GIN-PARTIAL-MATCH"><div class="titlepage"><div><div><h3 class="title">70.4.2. Partial Match Algorithm</h3></div></div></div><p>
+ GIN can support <span class="quote">“<span class="quote">partial match</span>”</span> queries, in which the query
+ does not determine an exact match for one or more keys, but the possible
+ matches fall within a reasonably narrow range of key values (within the
+ key sorting order determined by the <code class="function">compare</code> support method).
+ The <code class="function">extractQuery</code> method, instead of returning a key value
+ to be matched exactly, returns a key value that is the lower bound of
+ the range to be searched, and sets the <code class="literal">pmatch</code> flag true.
+ The key range is then scanned using the <code class="function">comparePartial</code>
+ method. <code class="function">comparePartial</code> must return zero for a matching
+ index key, less than zero for a non-match that is still within the range
+ to be searched, or greater than zero if the index key is past the range
+ that could match.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-extensibility.html" title="70.3. Extensibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.3. Extensibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.5. GIN Tips and Tricks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-intro.html b/doc/src/sgml/html/gin-intro.html
new file mode 100644
index 0000000..715fc6a
--- /dev/null
+++ b/doc/src/sgml/html/gin-intro.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin.html" title="Chapter 70. GIN Indexes" /><link rel="next" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin.html" title="Chapter 70. GIN Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.1. Introduction</h2></div></div></div><p>
+ <acronym class="acronym">GIN</acronym> stands for Generalized Inverted Index.
+ <acronym class="acronym">GIN</acronym> is designed for handling cases where the items
+ to be indexed are composite values, and the queries to be handled by
+ the index need to search for element values that appear within
+ the composite items. For example, the items could be documents,
+ and the queries could be searches for documents containing specific words.
+ </p><p>
+ We use the word <em class="firstterm">item</em> to refer to a composite value that
+ is to be indexed, and the word <em class="firstterm">key</em> to refer to an element
+ value. <acronym class="acronym">GIN</acronym> always stores and searches for keys,
+ not item values per se.
+ </p><p>
+ A <acronym class="acronym">GIN</acronym> index stores a set of (key, posting list) pairs,
+ where a <em class="firstterm">posting list</em> is a set of row IDs in which the key
+ occurs. The same row ID can appear in multiple posting lists, since
+ an item can contain more than one key. Each key value is stored only
+ once, so a <acronym class="acronym">GIN</acronym> index is very compact for cases
+ where the same key appears many times.
+ </p><p>
+ <acronym class="acronym">GIN</acronym> is generalized in the sense that the
+ <acronym class="acronym">GIN</acronym> access method code does not need to know the
+ specific operations that it accelerates.
+ Instead, it uses custom strategies defined for particular data types.
+ The strategy defines how keys are extracted from indexed items and
+ query conditions, and how to determine whether a row that contains
+ some of the key values in a query actually satisfies the query.
+ </p><p>
+ One advantage of <acronym class="acronym">GIN</acronym> is that it allows the development
+ of custom data types with the appropriate access methods, by
+ an expert in the domain of the data type, rather than a database expert.
+ This is much the same advantage as using <acronym class="acronym">GiST</acronym>.
+ </p><p>
+ The <acronym class="acronym">GIN</acronym>
+ implementation in <span class="productname">PostgreSQL</span> is primarily
+ maintained by Teodor Sigaev and Oleg Bartunov. There is more
+ information about <acronym class="acronym">GIN</acronym> on their
+ <a class="ulink" href="http://www.sai.msu.su/~megera/wiki/Gin" target="_top">website</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin.html" title="Chapter 70. GIN Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-builtin-opclasses.html" title="70.2. Built-in Operator Classes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 70. GIN Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.2. Built-in Operator Classes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-limit.html b/doc/src/sgml/html/gin-limit.html
new file mode 100644
index 0000000..5d9a32d
--- /dev/null
+++ b/doc/src/sgml/html/gin-limit.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.6. Limitations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-tips.html" title="70.5. GIN Tips and Tricks" /><link rel="next" href="gin-examples.html" title="70.7. Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.6. Limitations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-examples.html" title="70.7. Examples">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-LIMIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.6. Limitations</h2></div></div></div><p>
+ <acronym class="acronym">GIN</acronym> assumes that indexable operators are strict. This
+ means that <code class="function">extractValue</code> will not be called at all on a null
+ item value (instead, a placeholder index entry is created automatically),
+ and <code class="function">extractQuery</code> will not be called on a null query
+ value either (instead, the query is presumed to be unsatisfiable). Note
+ however that null key values contained within a non-null composite item
+ or query value are supported.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-examples.html" title="70.7. Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.5. GIN Tips and Tricks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.7. Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin-tips.html b/doc/src/sgml/html/gin-tips.html
new file mode 100644
index 0000000..2f51799
--- /dev/null
+++ b/doc/src/sgml/html/gin-tips.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>70.5. GIN Tips and Tricks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gin-implementation.html" title="70.4. Implementation" /><link rel="next" href="gin-limit.html" title="70.6. Limitations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">70.5. GIN Tips and Tricks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gin-implementation.html" title="70.4. Implementation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><th width="60%" align="center">Chapter 70. GIN Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-limit.html" title="70.6. Limitations">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIN-TIPS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">70.5. GIN Tips and Tricks</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Create vs. insert</span></dt><dd><p>
+ Insertion into a <acronym class="acronym">GIN</acronym> index can be slow
+ due to the likelihood of many keys being inserted for each item.
+ So, for bulk insertions into a table it is advisable to drop the GIN
+ index and recreate it after finishing bulk insertion.
+ </p><p>
+ When <code class="literal">fastupdate</code> is enabled for <acronym class="acronym">GIN</acronym>
+ (see <a class="xref" href="gin-implementation.html#GIN-FAST-UPDATE" title="70.4.1. GIN Fast Update Technique">Section 70.4.1</a> for details), the penalty is
+ less than when it is not. But for very large updates it may still be
+ best to drop and recreate the index.
+ </p></dd><dt><span class="term"><a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a></span></dt><dd><p>
+ Build time for a <acronym class="acronym">GIN</acronym> index is very sensitive to
+ the <code class="varname">maintenance_work_mem</code> setting; it doesn't pay to
+ skimp on work memory during index creation.
+ </p></dd><dt><span class="term"><a class="xref" href="runtime-config-client.html#GUC-GIN-PENDING-LIST-LIMIT">gin_pending_list_limit</a></span></dt><dd><p>
+ During a series of insertions into an existing <acronym class="acronym">GIN</acronym>
+ index that has <code class="literal">fastupdate</code> enabled, the system will clean up
+ the pending-entry list whenever the list grows larger than
+ <code class="varname">gin_pending_list_limit</code>. To avoid fluctuations in observed
+ response time, it's desirable to have pending-list cleanup occur in the
+ background (i.e., via autovacuum). Foreground cleanup operations
+ can be avoided by increasing <code class="varname">gin_pending_list_limit</code>
+ or making autovacuum more aggressive.
+ However, enlarging the threshold of the cleanup operation means that
+ if a foreground cleanup does occur, it will take even longer.
+ </p><p>
+ <code class="varname">gin_pending_list_limit</code> can be overridden for individual
+ GIN indexes by changing storage parameters, which allows each
+ GIN index to have its own cleanup threshold.
+ For example, it's possible to increase the threshold only for the GIN
+ index which can be updated heavily, and decrease it otherwise.
+ </p></dd><dt><span class="term"><a class="xref" href="runtime-config-client.html#GUC-GIN-FUZZY-SEARCH-LIMIT">gin_fuzzy_search_limit</a></span></dt><dd><p>
+ The primary goal of developing <acronym class="acronym">GIN</acronym> indexes was
+ to create support for highly scalable full-text search in
+ <span class="productname">PostgreSQL</span>, and there are often situations when
+ a full-text search returns a very large set of results. Moreover, this
+ often happens when the query contains very frequent words, so that the
+ large result set is not even useful. Since reading many
+ tuples from the disk and sorting them could take a lot of time, this is
+ unacceptable for production. (Note that the index search itself is very
+ fast.)
+ </p><p>
+ To facilitate controlled execution of such queries,
+ <acronym class="acronym">GIN</acronym> has a configurable soft upper limit on the
+ number of rows returned: the
+ <code class="varname">gin_fuzzy_search_limit</code> configuration parameter.
+ It is set to 0 (meaning no limit) by default.
+ If a non-zero limit is set, then the returned set is a subset of
+ the whole result set, chosen at random.
+ </p><p>
+ <span class="quote">“<span class="quote">Soft</span>”</span> means that the actual number of returned results
+ could differ somewhat from the specified limit, depending on the query
+ and the quality of the system's random number generator.
+ </p><p>
+ From experience, values in the thousands (e.g., 5000 — 20000)
+ work well.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gin-implementation.html" title="70.4. Implementation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gin.html" title="Chapter 70. GIN Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-limit.html" title="70.6. Limitations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">70.4. Implementation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.6. Limitations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin.html b/doc/src/sgml/html/gin.html
new file mode 100644
index 0000000..06062bc
--- /dev/null
+++ b/doc/src/sgml/html/gin.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 70. GIN Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist-examples.html" title="69.5. Examples" /><link rel="next" href="gin-intro.html" title="70.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 70. GIN Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist-examples.html" title="69.5. Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin-intro.html" title="70.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="GIN"><div class="titlepage"><div><div><h2 class="title">Chapter 70. GIN Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="gin-intro.html">70.1. Introduction</a></span></dt><dt><span class="sect1"><a href="gin-builtin-opclasses.html">70.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="gin-extensibility.html">70.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="gin-implementation.html">70.4. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="gin-implementation.html#GIN-FAST-UPDATE">70.4.1. GIN Fast Update Technique</a></span></dt><dt><span class="sect2"><a href="gin-implementation.html#GIN-PARTIAL-MATCH">70.4.2. Partial Match Algorithm</a></span></dt></dl></dd><dt><span class="sect1"><a href="gin-tips.html">70.5. GIN Tips and Tricks</a></span></dt><dt><span class="sect1"><a href="gin-limit.html">70.6. Limitations</a></span></dt><dt><span class="sect1"><a href="gin-examples.html">70.7. Examples</a></span></dt></dl></div><a id="id-1.10.21.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist-examples.html" title="69.5. Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin-intro.html" title="70.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">69.5. Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 70.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gin.svg b/doc/src/sgml/html/gin.svg
new file mode 100644
index 0000000..04fe85b
--- /dev/null
+++ b/doc/src/sgml/html/gin.svg
@@ -0,0 +1,317 @@
+<?xml version="1.0"?>
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: gin Pages: 1 -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="836pt" height="432pt" viewBox="0.00 0.00 836.00 432.00">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 428)">
+<title>gin</title>
+<polygon fill="#ffffff" stroke="none" points="-4,4 -4,-428 832,-428 832,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster01</title>
+<polygon fill="none" stroke="#000000" points="100,-162 100,-380 694,-380 694,-162 100,-162"/>
+<text text-anchor="middle" x="397" y="-364.8" font-family="Times,serif" font-size="14.00" fill="#000000">entry tree</text>
+</g>
+<g id="clust5" class="cluster">
+<title>cluster02</title>
+<polygon fill="none" stroke="#000000" points="8,-8 8,-154 245,-154 245,-8 8,-8"/>
+<text text-anchor="middle" x="126.5" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust8" class="cluster">
+<title>cluster03</title>
+<polygon fill="none" stroke="#000000" points="279,-80 279,-154 397,-154 397,-80 279,-80"/>
+<text text-anchor="middle" x="338" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust10" class="cluster">
+<title>cluster04</title>
+<polygon fill="none" stroke="#000000" points="405,-8 405,-154 642,-154 642,-8 405,-8"/>
+<text text-anchor="middle" x="523.5" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust13" class="cluster">
+<title>cluster05</title>
+<polygon fill="none" stroke="#000000" points="702,-80 702,-380 820,-380 820,-80 702,-80"/>
+<text text-anchor="middle" x="761" y="-364.8" font-family="Times,serif" font-size="14.00" fill="#000000">pending list</text>
+</g>
+<!-- m1 -->
+<g id="node1" class="node">
+<title>m1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="688.5,-424 587.5,-424 587.5,-388 688.5,-388 688.5,-424"/>
+<text text-anchor="middle" x="638" y="-401.8" font-family="Times,serif" font-size="14.00" fill="#000000">meta page</text>
+</g>
+<!-- e1 -->
+<g id="node2" class="node">
+<title>e1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="506.5,-350 405.5,-350 405.5,-314 506.5,-314 506.5,-350"/>
+</g>
+<!-- m1&#45;&gt;e1 -->
+<g id="edge24" class="edge">
+<title>m1-&gt;e1</title>
+<path fill="none" stroke="#000000" d="M593.4778,-387.8976C568.2655,-377.6464 536.5468,-364.7498 509.931,-353.928"/>
+<polygon fill="#000000" stroke="#000000" points="510.9595,-350.568 500.3776,-350.0436 508.3229,-357.0525 510.9595,-350.568"/>
+</g>
+<!-- n1 -->
+<g id="node18" class="node">
+<title>n1</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-350 710.5,-350 710.5,-314 811.5,-314 811.5,-350"/>
+</g>
+<!-- m1&#45;&gt;n1 -->
+<g id="edge28" class="edge">
+<title>m1-&gt;n1</title>
+<path fill="none" stroke="#000000" d="M683.1514,-387.8551C688.2504,-385.3905 693.2983,-382.7547 698,-380 709.7018,-373.1438 721.7385,-364.4455 732.115,-356.3423"/>
+<polygon fill="#000000" stroke="#000000" points="734.4083,-358.9902 740.0427,-350.0178 730.0428,-353.5181 734.4083,-358.9902"/>
+</g>
+<!-- e2 -->
+<g id="node3" class="node">
+<title>e2</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="328.5,-278 227.5,-278 227.5,-242 328.5,-242 328.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e2 -->
+<g id="edge9" class="edge">
+<title>e1-&gt;e2</title>
+<path fill="none" stroke="#000000" d="M411.0831,-313.8314C387.065,-304.1162 357.3166,-292.0831 332.0408,-281.8592"/>
+<polygon fill="#000000" stroke="#000000" points="333.1767,-278.5432 322.5939,-278.038 330.5518,-285.0325 333.1767,-278.5432"/>
+</g>
+<!-- e3 -->
+<g id="node4" class="node">
+<title>e3</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="447.5,-278 346.5,-278 346.5,-242 447.5,-242 447.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e3 -->
+<g id="edge8" class="edge">
+<title>e1-&gt;e3</title>
+<path fill="none" stroke="#000000" d="M441.1118,-313.8314C434.247,-305.454 425.9699,-295.3531 418.4489,-286.1749"/>
+<polygon fill="#000000" stroke="#000000" points="421.1341,-283.9297 412.0886,-278.4133 415.7197,-288.3665 421.1341,-283.9297"/>
+</g>
+<!-- e4 -->
+<g id="node5" class="node">
+<title>e4</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="566.5,-278 465.5,-278 465.5,-242 566.5,-242 566.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e4 -->
+<g id="edge7" class="edge">
+<title>e1-&gt;e4</title>
+<path fill="none" stroke="#000000" d="M471.1405,-313.8314C478.1217,-305.454 486.5391,-295.3531 494.1876,-286.1749"/>
+<polygon fill="#000000" stroke="#000000" points="496.9425,-288.3362 500.6556,-278.4133 491.5649,-283.8548 496.9425,-288.3362"/>
+</g>
+<!-- e2&#45;&gt;e3 -->
+<g id="edge1" class="edge">
+<title>e2-&gt;e3</title>
+<path fill="none" stroke="#000000" d="M328.668,-260C331.1453,-260 333.6227,-260 336.1001,-260"/>
+<polygon fill="#000000" stroke="#000000" points="336.2849,-263.5001 346.2848,-260 336.2848,-256.5001 336.2849,-263.5001"/>
+</g>
+<!-- e5 -->
+<g id="node6" class="node">
+<title>e5</title>
+<polygon fill="#008b00" stroke="#000000" points="209.5,-206 108.5,-206 108.5,-170 209.5,-170 209.5,-206"/>
+</g>
+<!-- e2&#45;&gt;e5 -->
+<g id="edge10" class="edge">
+<title>e2-&gt;e5</title>
+<path fill="none" stroke="#000000" d="M247.9713,-241.8314C232.7504,-232.6221 214.0872,-221.3301 197.7917,-211.4706"/>
+<polygon fill="#000000" stroke="#000000" points="199.3868,-208.345 189.0191,-206.1628 195.7631,-214.3341 199.3868,-208.345"/>
+</g>
+<!-- e6 -->
+<g id="node7" class="node">
+<title>e6</title>
+<polygon fill="#00ff00" stroke="#000000" points="328.5,-206 227.5,-206 227.5,-170 328.5,-170 328.5,-206"/>
+<text text-anchor="middle" x="278" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e2&#45;&gt;e6 -->
+<g id="edge11" class="edge">
+<title>e2-&gt;e6</title>
+<path fill="none" stroke="#000000" d="M278,-241.8314C278,-234.131 278,-224.9743 278,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="281.5001,-216.4132 278,-206.4133 274.5001,-216.4133 281.5001,-216.4132"/>
+</g>
+<!-- e3&#45;&gt;e4 -->
+<g id="edge2" class="edge">
+<title>e3-&gt;e4</title>
+<path fill="none" stroke="#000000" d="M447.668,-260C450.1453,-260 452.6227,-260 455.1001,-260"/>
+<polygon fill="#000000" stroke="#000000" points="455.2849,-263.5001 465.2848,-260 455.2848,-256.5001 455.2849,-263.5001"/>
+</g>
+<!-- e7 -->
+<g id="node8" class="node">
+<title>e7</title>
+<polygon fill="#008b00" stroke="#000000" points="447.5,-206 346.5,-206 346.5,-170 447.5,-170 447.5,-206"/>
+</g>
+<!-- e3&#45;&gt;e7 -->
+<g id="edge12" class="edge">
+<title>e3-&gt;e7</title>
+<path fill="none" stroke="#000000" d="M397,-241.8314C397,-234.131 397,-224.9743 397,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="400.5001,-216.4132 397,-206.4133 393.5001,-216.4133 400.5001,-216.4132"/>
+</g>
+<!-- e8 -->
+<g id="node9" class="node">
+<title>e8</title>
+<polygon fill="#00ff00" stroke="#000000" points="566.5,-206 465.5,-206 465.5,-170 566.5,-170 566.5,-206"/>
+<text text-anchor="middle" x="516" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e4&#45;&gt;e8 -->
+<g id="edge13" class="edge">
+<title>e4-&gt;e8</title>
+<path fill="none" stroke="#000000" d="M516,-241.8314C516,-234.131 516,-224.9743 516,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="519.5001,-216.4132 516,-206.4133 512.5001,-216.4133 519.5001,-216.4132"/>
+</g>
+<!-- e9 -->
+<g id="node10" class="node">
+<title>e9</title>
+<polygon fill="#00ff00" stroke="#000000" points="685.5,-206 584.5,-206 584.5,-170 685.5,-170 685.5,-206"/>
+<text text-anchor="middle" x="635" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e4&#45;&gt;e9 -->
+<g id="edge14" class="edge">
+<title>e4-&gt;e9</title>
+<path fill="none" stroke="#000000" d="M546.0287,-241.8314C561.2496,-232.6221 579.9128,-221.3301 596.2083,-211.4706"/>
+<polygon fill="#000000" stroke="#000000" points="598.2369,-214.3341 604.9809,-206.1628 594.6132,-208.345 598.2369,-214.3341"/>
+</g>
+<!-- e5&#45;&gt;e6 -->
+<g id="edge3" class="edge">
+<title>e5-&gt;e6</title>
+<path fill="none" stroke="#000000" d="M209.668,-188C212.1453,-188 214.6227,-188 217.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="217.2849,-191.5001 227.2848,-188 217.2848,-184.5001 217.2849,-191.5001"/>
+</g>
+<!-- p1 -->
+<g id="node11" class="node">
+<title>p1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="209.5,-124 108.5,-124 108.5,-88 209.5,-88 209.5,-124"/>
+</g>
+<!-- e5&#45;&gt;p1 -->
+<g id="edge25" class="edge">
+<title>e5-&gt;p1</title>
+<path fill="none" stroke="#000000" d="M159,-169.8015C159,-159.3976 159,-146.1215 159,-134.3768"/>
+<polygon fill="#000000" stroke="#000000" points="162.5001,-134.1476 159,-124.1476 155.5001,-134.1476 162.5001,-134.1476"/>
+</g>
+<!-- e6&#45;&gt;e7 -->
+<g id="edge4" class="edge">
+<title>e6-&gt;e7</title>
+<path fill="none" stroke="#000000" d="M328.668,-188C331.1453,-188 333.6227,-188 336.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="336.2849,-191.5001 346.2848,-188 336.2848,-184.5001 336.2849,-191.5001"/>
+</g>
+<!-- e7&#45;&gt;e8 -->
+<g id="edge5" class="edge">
+<title>e7-&gt;e8</title>
+<path fill="none" stroke="#000000" d="M447.668,-188C450.1453,-188 452.6227,-188 455.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="455.2849,-191.5001 465.2848,-188 455.2848,-184.5001 455.2849,-191.5001"/>
+</g>
+<!-- p4 -->
+<g id="node14" class="node">
+<title>p4</title>
+<polygon fill="#00ff00" stroke="#000000" points="388.5,-124 287.5,-124 287.5,-88 388.5,-88 388.5,-124"/>
+<text text-anchor="middle" x="338" y="-101.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- e7&#45;&gt;p4 -->
+<g id="edge26" class="edge">
+<title>e7-&gt;p4</title>
+<path fill="none" stroke="#000000" d="M383.906,-169.8015C376.0383,-158.8668 365.8878,-144.7593 357.133,-132.5916"/>
+<polygon fill="#000000" stroke="#000000" points="359.7389,-130.2207 351.0574,-124.1476 354.0569,-134.309 359.7389,-130.2207"/>
+</g>
+<!-- p5 -->
+<g id="node15" class="node">
+<title>p5</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="514.5,-124 413.5,-124 413.5,-88 514.5,-88 514.5,-124"/>
+</g>
+<!-- e7&#45;&gt;p5 -->
+<g id="edge27" class="edge">
+<title>e7-&gt;p5</title>
+<path fill="none" stroke="#000000" d="M411.8695,-169.8015C420.8907,-158.7606 432.5549,-144.4851 442.5618,-132.2378"/>
+<polygon fill="#000000" stroke="#000000" points="445.5552,-134.1059 449.1721,-124.1476 440.1345,-129.6768 445.5552,-134.1059"/>
+</g>
+<!-- e8&#45;&gt;e9 -->
+<g id="edge6" class="edge">
+<title>e8-&gt;e9</title>
+<path fill="none" stroke="#000000" d="M566.668,-188C569.1453,-188 571.6227,-188 574.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="574.2849,-191.5001 584.2848,-188 574.2848,-184.5001 574.2849,-191.5001"/>
+</g>
+<!-- p2 -->
+<g id="node12" class="node">
+<title>p2</title>
+<polygon fill="#00ff00" stroke="#000000" points="117.5,-52 16.5,-52 16.5,-16 117.5,-16 117.5,-52"/>
+<text text-anchor="middle" x="67" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p1&#45;&gt;p2 -->
+<g id="edge16" class="edge">
+<title>p1-&gt;p2</title>
+<path fill="none" stroke="#000000" d="M135.7845,-87.8314C124.453,-78.9632 110.6536,-68.1637 98.3973,-58.5718"/>
+<polygon fill="#000000" stroke="#000000" points="100.2402,-55.5697 90.2081,-52.1628 95.926,-61.0822 100.2402,-55.5697"/>
+</g>
+<!-- p3 -->
+<g id="node13" class="node">
+<title>p3</title>
+<polygon fill="#00ff00" stroke="#000000" points="236.5,-52 135.5,-52 135.5,-16 236.5,-16 236.5,-52"/>
+<text text-anchor="middle" x="186" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p1&#45;&gt;p3 -->
+<g id="edge17" class="edge">
+<title>p1-&gt;p3</title>
+<path fill="none" stroke="#000000" d="M165.8132,-87.8314C168.7644,-79.9617 172.2858,-70.5712 175.555,-61.8533"/>
+<polygon fill="#000000" stroke="#000000" points="178.8609,-63.0055 179.095,-52.4133 172.3066,-60.5476 178.8609,-63.0055"/>
+</g>
+<!-- p2&#45;&gt;p3 -->
+<g id="edge15" class="edge">
+<title>p2-&gt;p3</title>
+<path fill="none" stroke="#000000" d="M117.668,-34C120.1453,-34 122.6227,-34 125.1001,-34"/>
+<polygon fill="#000000" stroke="#000000" points="125.2849,-37.5001 135.2848,-34 125.2848,-30.5001 125.2849,-37.5001"/>
+</g>
+<!-- p6 -->
+<g id="node16" class="node">
+<title>p6</title>
+<polygon fill="#00ff00" stroke="#000000" points="514.5,-52 413.5,-52 413.5,-16 514.5,-16 514.5,-52"/>
+<text text-anchor="middle" x="464" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p5&#45;&gt;p6 -->
+<g id="edge19" class="edge">
+<title>p5-&gt;p6</title>
+<path fill="none" stroke="#000000" d="M464,-87.8314C464,-80.131 464,-70.9743 464,-62.4166"/>
+<polygon fill="#000000" stroke="#000000" points="467.5001,-62.4132 464,-52.4133 460.5001,-62.4133 467.5001,-62.4132"/>
+</g>
+<!-- p7 -->
+<g id="node17" class="node">
+<title>p7</title>
+<polygon fill="#00ff00" stroke="#000000" points="633.5,-52 532.5,-52 532.5,-16 633.5,-16 633.5,-52"/>
+<text text-anchor="middle" x="583" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p5&#45;&gt;p7 -->
+<g id="edge20" class="edge">
+<title>p5-&gt;p7</title>
+<path fill="none" stroke="#000000" d="M494.0287,-87.8314C509.2496,-78.6221 527.9128,-67.3301 544.2083,-57.4706"/>
+<polygon fill="#000000" stroke="#000000" points="546.2369,-60.3341 552.9809,-52.1628 542.6132,-54.345 546.2369,-60.3341"/>
+</g>
+<!-- p6&#45;&gt;p7 -->
+<g id="edge18" class="edge">
+<title>p6-&gt;p7</title>
+<path fill="none" stroke="#000000" d="M514.668,-34C517.1453,-34 519.6227,-34 522.1001,-34"/>
+<polygon fill="#000000" stroke="#000000" points="522.2849,-37.5001 532.2848,-34 522.2848,-30.5001 522.2849,-37.5001"/>
+</g>
+<!-- n2 -->
+<g id="node19" class="node">
+<title>n2</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-278 710.5,-278 710.5,-242 811.5,-242 811.5,-278"/>
+</g>
+<!-- n1&#45;&gt;n2 -->
+<g id="edge21" class="edge">
+<title>n1-&gt;n2</title>
+<path fill="none" stroke="#000000" d="M761,-313.8314C761,-306.131 761,-296.9743 761,-288.4166"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-288.4132 761,-278.4133 757.5001,-288.4133 764.5001,-288.4132"/>
+</g>
+<!-- n3 -->
+<g id="node20" class="node">
+<title>n3</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-206 710.5,-206 710.5,-170 811.5,-170 811.5,-206"/>
+</g>
+<!-- n2&#45;&gt;n3 -->
+<g id="edge22" class="edge">
+<title>n2-&gt;n3</title>
+<path fill="none" stroke="#000000" d="M761,-241.8314C761,-234.131 761,-224.9743 761,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-216.4132 761,-206.4133 757.5001,-216.4133 764.5001,-216.4132"/>
+</g>
+<!-- n4 -->
+<g id="node21" class="node">
+<title>n4</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-124 710.5,-124 710.5,-88 811.5,-88 811.5,-124"/>
+</g>
+<!-- n3&#45;&gt;n4 -->
+<g id="edge23" class="edge">
+<title>n3-&gt;n4</title>
+<path fill="none" stroke="#000000" d="M761,-169.8015C761,-159.3976 761,-146.1215 761,-134.3768"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-134.1476 761,-124.1476 757.5001,-134.1476 764.5001,-134.1476"/>
+</g>
+</g>
+</svg>
diff --git a/doc/src/sgml/html/gist-builtin-opclasses.html b/doc/src/sgml/html/gist-builtin-opclasses.html
new file mode 100644
index 0000000..1fba3d7
--- /dev/null
+++ b/doc/src/sgml/html/gist-builtin-opclasses.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.2. Built-in Operator Classes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist-intro.html" title="68.1. Introduction" /><link rel="next" href="gist-extensibility.html" title="68.3. Extensibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.2. Built-in Operator Classes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist-intro.html" title="68.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 68. GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist-extensibility.html" title="68.3. Extensibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIST-BUILTIN-OPCLASSES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.2. Built-in Operator Classes</h2></div></div></div><p>
+ The core <span class="productname">PostgreSQL</span> distribution
+ includes the <acronym class="acronym">GiST</acronym> operator classes shown in
+ <a class="xref" href="gist-builtin-opclasses.html#GIST-BUILTIN-OPCLASSES-TABLE" title="Table 68.1. Built-in GiST Operator Classes">Table 68.1</a>.
+ (Some of the optional modules described in <a class="xref" href="contrib.html" title="Appendix F. Additional Supplied Modules">Appendix F</a>
+ provide additional <acronym class="acronym">GiST</acronym> operator classes.)
+ </p><div class="table" id="GIST-BUILTIN-OPCLASSES-TABLE"><p class="title"><strong>Table 68.1. Built-in <acronym class="acronym">GiST</acronym> Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Built-in GiST Operator Classes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Indexable Operators</th><th>Ordering Operators</th></tr></thead><tbody><tr><td rowspan="14" valign="middle"><code class="literal">box_ops</code></td><td><code class="literal">&lt;&lt; (box, box)</code></td><td rowspan="14" valign="middle"><code class="literal">&lt;-&gt; (box, point)</code></td></tr><tr><td><code class="literal">&amp;&lt; (box, box)</code></td></tr><tr><td><code class="literal">&amp;&amp; (box, box)</code></td></tr><tr><td><code class="literal">&amp;&gt; (box, box)</code></td></tr><tr><td><code class="literal">&gt;&gt; (box, box)</code></td></tr><tr><td><code class="literal">~= (box, box)</code></td></tr><tr><td><code class="literal">@&gt; (box, box)</code></td></tr><tr><td><code class="literal">&lt;@ (box, box)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (box, box)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (box, box)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (box, box)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (box, box)</code></td></tr><tr><td><code class="literal">~ (box, box)</code></td></tr><tr><td><code class="literal">@ (box, box)</code></td></tr><tr><td rowspan="14" valign="middle"><code class="literal">circle_ops</code></td><td><code class="literal">&lt;&lt; (circle, circle)</code></td><td rowspan="14" valign="middle"><code class="literal">&lt;-&gt; (circle, point)</code></td></tr><tr><td><code class="literal">&amp;&lt; (circle, circle)</code></td></tr><tr><td><code class="literal">&amp;&gt; (circle, circle)</code></td></tr><tr><td><code class="literal">&gt;&gt; (circle, circle)</code></td></tr><tr><td><code class="literal">&lt;@ (circle, circle)</code></td></tr><tr><td><code class="literal">@&gt; (circle, circle)</code></td></tr><tr><td><code class="literal">~= (circle, circle)</code></td></tr><tr><td><code class="literal">&amp;&amp; (circle, circle)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (circle, circle)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (circle, circle)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (circle, circle)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (circle, circle)</code></td></tr><tr><td><code class="literal">@ (circle, circle)</code></td></tr><tr><td><code class="literal">~ (circle, circle)</code></td></tr><tr><td rowspan="11" valign="middle"><code class="literal">inet_ops</code></td><td><code class="literal">&lt;&lt; (inet, inet)</code></td><td rowspan="11" valign="middle"> </td></tr><tr><td><code class="literal">&lt;&lt;= (inet, inet)</code></td></tr><tr><td><code class="literal">&gt;&gt; (inet, inet)</code></td></tr><tr><td><code class="literal">&gt;&gt;= (inet, inet)</code></td></tr><tr><td><code class="literal">= (inet, inet)</code></td></tr><tr><td><code class="literal">&lt;&gt; (inet, inet)</code></td></tr><tr><td><code class="literal">&lt; (inet, inet)</code></td></tr><tr><td><code class="literal">&lt;= (inet, inet)</code></td></tr><tr><td><code class="literal">&gt; (inet, inet)</code></td></tr><tr><td><code class="literal">&gt;= (inet, inet)</code></td></tr><tr><td><code class="literal">&amp;&amp; (inet, inet)</code></td></tr><tr><td rowspan="18" valign="middle"><code class="literal">multirange_ops</code></td><td><code class="literal">= (anymultirange, anymultirange)</code></td><td rowspan="18" valign="middle"> </td></tr><tr><td><code class="literal">&amp;&amp; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&amp;&amp; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">@&gt; (anymultirange, anyelement)</code></td></tr><tr><td><code class="literal">@&gt; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">@&gt; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">&lt;@ (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&lt;@ (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anymultirange, anyrange)</code></td></tr><tr><td><code class="literal">-|- (anymultirange, anymultirange)</code></td></tr><tr><td><code class="literal">-|- (anymultirange, anyrange)</code></td></tr><tr><td rowspan="8" valign="middle"><code class="literal">point_ops</code></td><td><code class="literal">|&gt;&gt; (point, point)</code></td><td rowspan="8" valign="middle"><code class="literal">&lt;-&gt; (point, point)</code></td></tr><tr><td><code class="literal">&lt;&lt; (point, point)</code></td></tr><tr><td><code class="literal">&gt;&gt; (point, point)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (point, point)</code></td></tr><tr><td><code class="literal">~= (point, point)</code></td></tr><tr><td><code class="literal">&lt;@ (point, box)</code></td></tr><tr><td><code class="literal">&lt;@ (point, polygon)</code></td></tr><tr><td><code class="literal">&lt;@ (point, circle)</code></td></tr><tr><td rowspan="14" valign="middle"><code class="literal">poly_ops</code></td><td><code class="literal">&lt;&lt; (polygon, polygon)</code></td><td rowspan="14" valign="middle"><code class="literal">&lt;-&gt; (polygon, point)</code></td></tr><tr><td><code class="literal">&amp;&lt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">&amp;&gt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">&gt;&gt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">&lt;@ (polygon, polygon)</code></td></tr><tr><td><code class="literal">@&gt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">~= (polygon, polygon)</code></td></tr><tr><td><code class="literal">&amp;&amp; (polygon, polygon)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (polygon, polygon)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (polygon, polygon)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (polygon, polygon)</code></td></tr><tr><td><code class="literal">@ (polygon, polygon)</code></td></tr><tr><td><code class="literal">~ (polygon, polygon)</code></td></tr><tr><td rowspan="18" valign="middle"><code class="literal">range_ops</code></td><td><code class="literal">= (anyrange, anyrange)</code></td><td rowspan="18" valign="middle"> </td></tr><tr><td><code class="literal">&amp;&amp; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&amp;&amp; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange, anyelement)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">&lt;@ (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&lt;@ (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anyrange, anymultirange)</code></td></tr><tr><td><code class="literal">-|- (anyrange, anyrange)</code></td></tr><tr><td><code class="literal">-|- (anyrange, anymultirange)</code></td></tr><tr><td rowspan="2" valign="middle"><code class="literal">tsquery_ops</code></td><td><code class="literal">&lt;@ (tsquery, tsquery)</code></td><td rowspan="2" valign="middle"> </td></tr><tr><td><code class="literal">@&gt; (tsquery, tsquery)</code></td></tr><tr><td valign="middle"><code class="literal">tsvector_ops</code></td><td><code class="literal">@@ (tsvector, tsquery)</code></td><td> </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For historical reasons, the <code class="literal">inet_ops</code> operator class is
+ not the default class for types <code class="type">inet</code> and <code class="type">cidr</code>.
+ To use it, mention the class name in <code class="command">CREATE INDEX</code>,
+ for example
+</p><pre class="programlisting">
+CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist-intro.html" title="68.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist-extensibility.html" title="68.3. Extensibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">68.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.3. Extensibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gist-examples.html b/doc/src/sgml/html/gist-examples.html
new file mode 100644
index 0000000..91b8c72
--- /dev/null
+++ b/doc/src/sgml/html/gist-examples.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.5. Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist-implementation.html" title="68.4. Implementation" /><link rel="next" href="spgist.html" title="Chapter 69. SP-GiST Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.5. Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist-implementation.html" title="68.4. Implementation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 68. GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIST-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.5. Examples</h2></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> source distribution includes
+ several examples of index methods implemented using
+ <acronym class="acronym">GiST</acronym>. The core system currently provides text search
+ support (indexing for <code class="type">tsvector</code> and <code class="type">tsquery</code>) as well as
+ R-Tree equivalent functionality for some of the built-in geometric data types
+ (see <code class="filename">src/backend/access/gist/gistproc.c</code>). The following
+ <code class="filename">contrib</code> modules also contain <acronym class="acronym">GiST</acronym>
+ operator classes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">btree_gist</code></span></dt><dd><p>B-tree equivalent functionality for several data types</p></dd><dt><span class="term"><code class="filename">cube</code></span></dt><dd><p>Indexing for multidimensional cubes</p></dd><dt><span class="term"><code class="filename">hstore</code></span></dt><dd><p>Module for storing (key, value) pairs</p></dd><dt><span class="term"><code class="filename">intarray</code></span></dt><dd><p>RD-Tree for one-dimensional array of int4 values</p></dd><dt><span class="term"><code class="filename">ltree</code></span></dt><dd><p>Indexing for tree-like structures</p></dd><dt><span class="term"><code class="filename">pg_trgm</code></span></dt><dd><p>Text similarity using trigram matching</p></dd><dt><span class="term"><code class="filename">seg</code></span></dt><dd><p>Indexing for <span class="quote">“<span class="quote">float ranges</span>”</span></p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist-implementation.html" title="68.4. Implementation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">68.4. Implementation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 69. SP-GiST Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gist-extensibility.html b/doc/src/sgml/html/gist-extensibility.html
new file mode 100644
index 0000000..b9af0e8
--- /dev/null
+++ b/doc/src/sgml/html/gist-extensibility.html
@@ -0,0 +1,813 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.3. Extensibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes" /><link rel="next" href="gist-implementation.html" title="68.4. Implementation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.3. Extensibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 68. GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist-implementation.html" title="68.4. Implementation">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIST-EXTENSIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.3. Extensibility</h2></div></div></div><p>
+ Traditionally, implementing a new index access method meant a lot of
+ difficult work. It was necessary to understand the inner workings of the
+ database, such as the lock manager and Write-Ahead Log. The
+ <acronym class="acronym">GiST</acronym> interface has a high level of abstraction,
+ requiring the access method implementer only to implement the semantics of
+ the data type being accessed. The <acronym class="acronym">GiST</acronym> layer itself
+ takes care of concurrency, logging and searching the tree structure.
+ </p><p>
+ This extensibility should not be confused with the extensibility of the
+ other standard search trees in terms of the data they can handle. For
+ example, <span class="productname">PostgreSQL</span> supports extensible B-trees
+ and hash indexes. That means that you can use
+ <span class="productname">PostgreSQL</span> to build a B-tree or hash over any
+ data type you want. But B-trees only support range predicates
+ (<code class="literal">&lt;</code>, <code class="literal">=</code>, <code class="literal">&gt;</code>),
+ and hash indexes only support equality queries.
+ </p><p>
+ So if you index, say, an image collection with a
+ <span class="productname">PostgreSQL</span> B-tree, you can only issue queries
+ such as <span class="quote">“<span class="quote">is imagex equal to imagey</span>”</span>, <span class="quote">“<span class="quote">is imagex less
+ than imagey</span>”</span> and <span class="quote">“<span class="quote">is imagex greater than imagey</span>”</span>.
+ Depending on how you define <span class="quote">“<span class="quote">equals</span>”</span>, <span class="quote">“<span class="quote">less than</span>”</span>
+ and <span class="quote">“<span class="quote">greater than</span>”</span> in this context, this could be useful.
+ However, by using a <acronym class="acronym">GiST</acronym> based index, you could create
+ ways to ask domain-specific questions, perhaps <span class="quote">“<span class="quote">find all images of
+ horses</span>”</span> or <span class="quote">“<span class="quote">find all over-exposed images</span>”</span>.
+ </p><p>
+ All it takes to get a <acronym class="acronym">GiST</acronym> access method up and running
+ is to implement several user-defined methods, which define the behavior of
+ keys in the tree. Of course these methods have to be pretty fancy to
+ support fancy queries, but for all the standard queries (B-trees,
+ R-trees, etc.) they're relatively straightforward. In short,
+ <acronym class="acronym">GiST</acronym> combines extensibility along with generality, code
+ reuse, and a clean interface.
+ </p><p>
+ There are five methods that an index operator class for
+ <acronym class="acronym">GiST</acronym> must provide, and six that are optional.
+ Correctness of the index is ensured
+ by proper implementation of the <code class="function">same</code>, <code class="function">consistent</code>
+ and <code class="function">union</code> methods, while efficiency (size and speed) of the
+ index will depend on the <code class="function">penalty</code> and <code class="function">picksplit</code>
+ methods.
+ Two optional methods are <code class="function">compress</code> and
+ <code class="function">decompress</code>, which allow an index to have internal tree data of
+ a different type than the data it indexes. The leaves are to be of the
+ indexed data type, while the other tree nodes can be of any C struct (but
+ you still have to follow <span class="productname">PostgreSQL</span> data type rules here,
+ see about <code class="literal">varlena</code> for variable sized data). If the tree's
+ internal data type exists at the SQL level, the <code class="literal">STORAGE</code> option
+ of the <code class="command">CREATE OPERATOR CLASS</code> command can be used.
+ The optional eighth method is <code class="function">distance</code>, which is needed
+ if the operator class wishes to support ordered scans (nearest-neighbor
+ searches). The optional ninth method <code class="function">fetch</code> is needed if the
+ operator class wishes to support index-only scans, except when the
+ <code class="function">compress</code> method is omitted. The optional tenth method
+ <code class="function">options</code> is needed if the operator class has
+ user-specified parameters.
+ The optional eleventh method <code class="function">sortsupport</code> is used to
+ speed up building a <acronym class="acronym">GiST</acronym> index.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">consistent</code></span></dt><dd><p>
+ Given an index entry <code class="literal">p</code> and a query value <code class="literal">q</code>,
+ this function determines whether the index entry is
+ <span class="quote">“<span class="quote">consistent</span>”</span> with the query; that is, could the predicate
+ <span class="quote">“<span class="quote"><em class="replaceable"><code>indexed_column</code></em>
+ <em class="replaceable"><code>indexable_operator</code></em> <code class="literal">q</code></span>”</span> be true for
+ any row represented by the index entry? For a leaf index entry this is
+ equivalent to testing the indexable condition, while for an internal
+ tree node this determines whether it is necessary to scan the subtree
+ of the index represented by the tree node. When the result is
+ <code class="literal">true</code>, a <code class="literal">recheck</code> flag must also be returned.
+ This indicates whether the predicate is certainly true or only possibly
+ true. If <code class="literal">recheck</code> = <code class="literal">false</code> then the index has
+ tested the predicate condition exactly, whereas if <code class="literal">recheck</code>
+ = <code class="literal">true</code> the row is only a candidate match. In that case the
+ system will automatically evaluate the
+ <em class="replaceable"><code>indexable_operator</code></em> against the actual row value to see
+ if it is really a match. This convention allows
+ <acronym class="acronym">GiST</acronym> to support both lossless and lossy index
+ structures.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_consistent(internal, data_type, smallint, oid, internal)
+RETURNS bool
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_consistent);
+
+Datum
+my_consistent(PG_FUNCTION_ARGS)
+{
+ GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
+ data_type *query = PG_GETARG_DATA_TYPE_P(1);
+ StrategyNumber strategy = (StrategyNumber) PG_GETARG_UINT16(2);
+ /* Oid subtype = PG_GETARG_OID(3); */
+ bool *recheck = (bool *) PG_GETARG_POINTER(4);
+ data_type *key = DatumGetDataType(entry-&gt;key);
+ bool retval;
+
+ /*
+ * determine return value as a function of strategy, key and query.
+ *
+ * Use GIST_LEAF(entry) to know where you're called in the index tree,
+ * which comes handy when supporting the = operator for example (you could
+ * check for non empty union() in non-leaf nodes and equality in leaf
+ * nodes).
+ */
+
+ *recheck = true; /* or false if check is exact */
+
+ PG_RETURN_BOOL(retval);
+}
+</pre><p>
+
+ Here, <code class="varname">key</code> is an element in the index and <code class="varname">query</code>
+ the value being looked up in the index. The <code class="literal">StrategyNumber</code>
+ parameter indicates which operator of your operator class is being
+ applied — it matches one of the operator numbers in the
+ <code class="command">CREATE OPERATOR CLASS</code> command.
+ </p><p>
+ Depending on which operators you have included in the class, the data
+ type of <code class="varname">query</code> could vary with the operator, since it will
+ be whatever type is on the right-hand side of the operator, which might
+ be different from the indexed data type appearing on the left-hand side.
+ (The above code skeleton assumes that only one type is possible; if
+ not, fetching the <code class="varname">query</code> argument value would have to depend
+ on the operator.) It is recommended that the SQL declaration of
+ the <code class="function">consistent</code> function use the opclass's indexed data
+ type for the <code class="varname">query</code> argument, even though the actual type
+ might be something else depending on the operator.
+ </p></dd><dt><span class="term"><code class="function">union</code></span></dt><dd><p>
+ This method consolidates information in the tree. Given a set of
+ entries, this function generates a new index entry that represents
+ all the given entries.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_union(internal, internal)
+RETURNS storage_type
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_union);
+
+Datum
+my_union(PG_FUNCTION_ARGS)
+{
+ GistEntryVector *entryvec = (GistEntryVector *) PG_GETARG_POINTER(0);
+ GISTENTRY *ent = entryvec-&gt;vector;
+ data_type *out,
+ *tmp,
+ *old;
+ int numranges,
+ i = 0;
+
+ numranges = entryvec-&gt;n;
+ tmp = DatumGetDataType(ent[0].key);
+ out = tmp;
+
+ if (numranges == 1)
+ {
+ out = data_type_deep_copy(tmp);
+
+ PG_RETURN_DATA_TYPE_P(out);
+ }
+
+ for (i = 1; i &lt; numranges; i++)
+ {
+ old = out;
+ tmp = DatumGetDataType(ent[i].key);
+ out = my_union_implementation(out, tmp);
+ }
+
+ PG_RETURN_DATA_TYPE_P(out);
+}
+</pre><p>
+ </p><p>
+ As you can see, in this skeleton we're dealing with a data type
+ where <code class="literal">union(X, Y, Z) = union(union(X, Y), Z)</code>. It's easy
+ enough to support data types where this is not the case, by
+ implementing the proper union algorithm in this
+ <acronym class="acronym">GiST</acronym> support method.
+ </p><p>
+ The result of the <code class="function">union</code> function must be a value of the
+ index's storage type, whatever that is (it might or might not be
+ different from the indexed column's type). The <code class="function">union</code>
+ function should return a pointer to newly <code class="function">palloc()</code>ed
+ memory. You can't just return the input value as-is, even if there is
+ no type change.
+ </p><p>
+ As shown above, the <code class="function">union</code> function's
+ first <code class="type">internal</code> argument is actually
+ a <code class="structname">GistEntryVector</code> pointer. The second argument is a
+ pointer to an integer variable, which can be ignored. (It used to be
+ required that the <code class="function">union</code> function store the size of its
+ result value into that variable, but this is no longer necessary.)
+ </p></dd><dt><span class="term"><code class="function">compress</code></span></dt><dd><p>
+ Converts a data item into a format suitable for physical storage in
+ an index page.
+ If the <code class="function">compress</code> method is omitted, data items are stored
+ in the index without modification.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_compress(internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_compress);
+
+Datum
+my_compress(PG_FUNCTION_ARGS)
+{
+ GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
+ GISTENTRY *retval;
+
+ if (entry-&gt;leafkey)
+ {
+ /* replace entry-&gt;key with a compressed version */
+ compressed_data_type *compressed_data = palloc(sizeof(compressed_data_type));
+
+ /* fill *compressed_data from entry-&gt;key ... */
+
+ retval = palloc(sizeof(GISTENTRY));
+ gistentryinit(*retval, PointerGetDatum(compressed_data),
+ entry-&gt;rel, entry-&gt;page, entry-&gt;offset, FALSE);
+ }
+ else
+ {
+ /* typically we needn't do anything with non-leaf entries */
+ retval = entry;
+ }
+
+ PG_RETURN_POINTER(retval);
+}
+</pre><p>
+ </p><p>
+ You have to adapt <em class="replaceable"><code>compressed_data_type</code></em> to the specific
+ type you're converting to in order to compress your leaf nodes, of
+ course.
+ </p></dd><dt><span class="term"><code class="function">decompress</code></span></dt><dd><p>
+ Converts the stored representation of a data item into a format that
+ can be manipulated by the other GiST methods in the operator class.
+ If the <code class="function">decompress</code> method is omitted, it is assumed that
+ the other GiST methods can work directly on the stored data format.
+ (<code class="function">decompress</code> is not necessarily the reverse of
+ the <code class="function">compress</code> method; in particular,
+ if <code class="function">compress</code> is lossy then it's impossible
+ for <code class="function">decompress</code> to exactly reconstruct the original
+ data. <code class="function">decompress</code> is not necessarily equivalent
+ to <code class="function">fetch</code>, either, since the other GiST methods might not
+ require full reconstruction of the data.)
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_decompress(internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_decompress);
+
+Datum
+my_decompress(PG_FUNCTION_ARGS)
+{
+ PG_RETURN_POINTER(PG_GETARG_POINTER(0));
+}
+</pre><p>
+
+ The above skeleton is suitable for the case where no decompression
+ is needed. (But, of course, omitting the method altogether is even
+ easier, and is recommended in such cases.)
+ </p></dd><dt><span class="term"><code class="function">penalty</code></span></dt><dd><p>
+ Returns a value indicating the <span class="quote">“<span class="quote">cost</span>”</span> of inserting the new
+ entry into a particular branch of the tree. Items will be inserted
+ down the path of least <code class="function">penalty</code> in the tree.
+ Values returned by <code class="function">penalty</code> should be non-negative.
+ If a negative value is returned, it will be treated as zero.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_penalty(internal, internal, internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT; -- in some cases penalty functions need not be strict
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_penalty);
+
+Datum
+my_penalty(PG_FUNCTION_ARGS)
+{
+ GISTENTRY *origentry = (GISTENTRY *) PG_GETARG_POINTER(0);
+ GISTENTRY *newentry = (GISTENTRY *) PG_GETARG_POINTER(1);
+ float *penalty = (float *) PG_GETARG_POINTER(2);
+ data_type *orig = DatumGetDataType(origentry-&gt;key);
+ data_type *new = DatumGetDataType(newentry-&gt;key);
+
+ *penalty = my_penalty_implementation(orig, new);
+ PG_RETURN_POINTER(penalty);
+}
+</pre><p>
+
+ For historical reasons, the <code class="function">penalty</code> function doesn't
+ just return a <code class="type">float</code> result; instead it has to store the value
+ at the location indicated by the third argument. The return
+ value per se is ignored, though it's conventional to pass back the
+ address of that argument.
+ </p><p>
+ The <code class="function">penalty</code> function is crucial to good performance of
+ the index. It'll get used at insertion time to determine which branch
+ to follow when choosing where to add the new entry in the tree. At
+ query time, the more balanced the index, the quicker the lookup.
+ </p></dd><dt><span class="term"><code class="function">picksplit</code></span></dt><dd><p>
+ When an index page split is necessary, this function decides which
+ entries on the page are to stay on the old page, and which are to move
+ to the new page.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_picksplit(internal, internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_picksplit);
+
+Datum
+my_picksplit(PG_FUNCTION_ARGS)
+{
+ GistEntryVector *entryvec = (GistEntryVector *) PG_GETARG_POINTER(0);
+ GIST_SPLITVEC *v = (GIST_SPLITVEC *) PG_GETARG_POINTER(1);
+ OffsetNumber maxoff = entryvec-&gt;n - 1;
+ GISTENTRY *ent = entryvec-&gt;vector;
+ int i,
+ nbytes;
+ OffsetNumber *left,
+ *right;
+ data_type *tmp_union;
+ data_type *unionL;
+ data_type *unionR;
+ GISTENTRY **raw_entryvec;
+
+ maxoff = entryvec-&gt;n - 1;
+ nbytes = (maxoff + 1) * sizeof(OffsetNumber);
+
+ v-&gt;spl_left = (OffsetNumber *) palloc(nbytes);
+ left = v-&gt;spl_left;
+ v-&gt;spl_nleft = 0;
+
+ v-&gt;spl_right = (OffsetNumber *) palloc(nbytes);
+ right = v-&gt;spl_right;
+ v-&gt;spl_nright = 0;
+
+ unionL = NULL;
+ unionR = NULL;
+
+ /* Initialize the raw entry vector. */
+ raw_entryvec = (GISTENTRY **) malloc(entryvec-&gt;n * sizeof(void *));
+ for (i = FirstOffsetNumber; i &lt;= maxoff; i = OffsetNumberNext(i))
+ raw_entryvec[i] = &amp;(entryvec-&gt;vector[i]);
+
+ for (i = FirstOffsetNumber; i &lt;= maxoff; i = OffsetNumberNext(i))
+ {
+ int real_index = raw_entryvec[i] - entryvec-&gt;vector;
+
+ tmp_union = DatumGetDataType(entryvec-&gt;vector[real_index].key);
+ Assert(tmp_union != NULL);
+
+ /*
+ * Choose where to put the index entries and update unionL and unionR
+ * accordingly. Append the entries to either v-&gt;spl_left or
+ * v-&gt;spl_right, and care about the counters.
+ */
+
+ if (my_choice_is_left(unionL, curl, unionR, curr))
+ {
+ if (unionL == NULL)
+ unionL = tmp_union;
+ else
+ unionL = my_union_implementation(unionL, tmp_union);
+
+ *left = real_index;
+ ++left;
+ ++(v-&gt;spl_nleft);
+ }
+ else
+ {
+ /*
+ * Same on the right
+ */
+ }
+ }
+
+ v-&gt;spl_ldatum = DataTypeGetDatum(unionL);
+ v-&gt;spl_rdatum = DataTypeGetDatum(unionR);
+ PG_RETURN_POINTER(v);
+}
+</pre><p>
+
+ Notice that the <code class="function">picksplit</code> function's result is delivered
+ by modifying the passed-in <code class="structname">v</code> structure. The return
+ value per se is ignored, though it's conventional to pass back the
+ address of <code class="structname">v</code>.
+ </p><p>
+ Like <code class="function">penalty</code>, the <code class="function">picksplit</code> function
+ is crucial to good performance of the index. Designing suitable
+ <code class="function">penalty</code> and <code class="function">picksplit</code> implementations
+ is where the challenge of implementing well-performing
+ <acronym class="acronym">GiST</acronym> indexes lies.
+ </p></dd><dt><span class="term"><code class="function">same</code></span></dt><dd><p>
+ Returns true if two index entries are identical, false otherwise.
+ (An <span class="quote">“<span class="quote">index entry</span>”</span> is a value of the index's storage type,
+ not necessarily the original indexed column's type.)
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_same(storage_type, storage_type, internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_same);
+
+Datum
+my_same(PG_FUNCTION_ARGS)
+{
+ prefix_range *v1 = PG_GETARG_PREFIX_RANGE_P(0);
+ prefix_range *v2 = PG_GETARG_PREFIX_RANGE_P(1);
+ bool *result = (bool *) PG_GETARG_POINTER(2);
+
+ *result = my_eq(v1, v2);
+ PG_RETURN_POINTER(result);
+}
+</pre><p>
+
+ For historical reasons, the <code class="function">same</code> function doesn't
+ just return a Boolean result; instead it has to store the flag
+ at the location indicated by the third argument. The return
+ value per se is ignored, though it's conventional to pass back the
+ address of that argument.
+ </p></dd><dt><span class="term"><code class="function">distance</code></span></dt><dd><p>
+ Given an index entry <code class="literal">p</code> and a query value <code class="literal">q</code>,
+ this function determines the index entry's
+ <span class="quote">“<span class="quote">distance</span>”</span> from the query value. This function must be
+ supplied if the operator class contains any ordering operators.
+ A query using the ordering operator will be implemented by returning
+ index entries with the smallest <span class="quote">“<span class="quote">distance</span>”</span> values first,
+ so the results must be consistent with the operator's semantics.
+ For a leaf index entry the result just represents the distance to
+ the index entry; for an internal tree node, the result must be the
+ smallest distance that any child entry could have.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_distance(internal, data_type, smallint, oid, internal)
+RETURNS float8
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ And the matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_distance);
+
+Datum
+my_distance(PG_FUNCTION_ARGS)
+{
+ GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
+ data_type *query = PG_GETARG_DATA_TYPE_P(1);
+ StrategyNumber strategy = (StrategyNumber) PG_GETARG_UINT16(2);
+ /* Oid subtype = PG_GETARG_OID(3); */
+ /* bool *recheck = (bool *) PG_GETARG_POINTER(4); */
+ data_type *key = DatumGetDataType(entry-&gt;key);
+ double retval;
+
+ /*
+ * determine return value as a function of strategy, key and query.
+ */
+
+ PG_RETURN_FLOAT8(retval);
+}
+</pre><p>
+
+ The arguments to the <code class="function">distance</code> function are identical to
+ the arguments of the <code class="function">consistent</code> function.
+ </p><p>
+ Some approximation is allowed when determining the distance, so long
+ as the result is never greater than the entry's actual distance. Thus,
+ for example, distance to a bounding box is usually sufficient in
+ geometric applications. For an internal tree node, the distance
+ returned must not be greater than the distance to any of the child
+ nodes. If the returned distance is not exact, the function must set
+ <code class="literal">*recheck</code> to true. (This is not necessary for internal tree
+ nodes; for them, the calculation is always assumed to be inexact.) In
+ this case the executor will calculate the accurate distance after
+ fetching the tuple from the heap, and reorder the tuples if necessary.
+ </p><p>
+ If the distance function returns <code class="literal">*recheck = true</code> for any
+ leaf node, the original ordering operator's return type must
+ be <code class="type">float8</code> or <code class="type">float4</code>, and the distance function's
+ result values must be comparable to those of the original ordering
+ operator, since the executor will sort using both distance function
+ results and recalculated ordering-operator results. Otherwise, the
+ distance function's result values can be any finite <code class="type">float8</code>
+ values, so long as the relative order of the result values matches the
+ order returned by the ordering operator. (Infinity and minus infinity
+ are used internally to handle cases such as nulls, so it is not
+ recommended that <code class="function">distance</code> functions return these values.)
+ </p></dd><dt><span class="term"><code class="function">fetch</code></span></dt><dd><p>
+ Converts the compressed index representation of a data item into the
+ original data type, for index-only scans. The returned data must be an
+ exact, non-lossy copy of the originally indexed value.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_fetch(internal)
+RETURNS internal
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ The argument is a pointer to a <code class="structname">GISTENTRY</code> struct. On
+ entry, its <code class="structfield">key</code> field contains a non-NULL leaf datum in
+ compressed form. The return value is another <code class="structname">GISTENTRY</code>
+ struct, whose <code class="structfield">key</code> field contains the same datum in its
+ original, uncompressed form. If the opclass's compress function does
+ nothing for leaf entries, the <code class="function">fetch</code> method can return the
+ argument as-is. Or, if the opclass does not have a compress function,
+ the <code class="function">fetch</code> method can be omitted as well, since it would
+ necessarily be a no-op.
+ </p><p>
+ The matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_fetch);
+
+Datum
+my_fetch(PG_FUNCTION_ARGS)
+{
+ GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
+ input_data_type *in = DatumGetPointer(entry-&gt;key);
+ fetched_data_type *fetched_data;
+ GISTENTRY *retval;
+
+ retval = palloc(sizeof(GISTENTRY));
+ fetched_data = palloc(sizeof(fetched_data_type));
+
+ /*
+ * Convert 'fetched_data' into the a Datum of the original datatype.
+ */
+
+ /* fill *retval from fetched_data. */
+ gistentryinit(*retval, PointerGetDatum(converted_datum),
+ entry-&gt;rel, entry-&gt;page, entry-&gt;offset, FALSE);
+
+ PG_RETURN_POINTER(retval);
+}
+</pre><p>
+ </p><p>
+ If the compress method is lossy for leaf entries, the operator class
+ cannot support index-only scans, and must not define
+ a <code class="function">fetch</code> function.
+ </p></dd><dt><span class="term"><code class="function">options</code></span></dt><dd><p>
+ Allows definition of user-visible parameters that control operator
+ class behavior.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+ </p><p>
+ The function is passed a pointer to a <code class="structname">local_relopts</code>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using the <code class="literal">PG_HAS_OPCLASS_OPTIONS()</code> and
+ <code class="literal">PG_GET_OPCLASS_OPTIONS()</code> macros.
+ </p><p>
+ An example implementation of my_options() and parameters use
+ from other support functions are given below:
+
+</p><pre class="programlisting">
+typedef enum MyEnumType
+{
+ MY_ENUM_ON,
+ MY_ENUM_OFF,
+ MY_ENUM_AUTO
+} MyEnumType;
+
+typedef struct
+{
+ int32 vl_len_; /* varlena header (do not touch directly!) */
+ int int_param; /* integer parameter */
+ double real_param; /* real parameter */
+ MyEnumType enum_param; /* enum parameter */
+ int str_param; /* string parameter */
+} MyOptionsStruct;
+
+/* String representation of enum values */
+static relopt_enum_elt_def myEnumValues[] =
+{
+ {"on", MY_ENUM_ON},
+ {"off", MY_ENUM_OFF},
+ {"auto", MY_ENUM_AUTO},
+ {(const char *) NULL} /* list terminator */
+};
+
+static char *str_param_default = "default";
+
+/*
+ * Sample validator: checks that string is not longer than 8 bytes.
+ */
+static void
+validate_my_string_relopt(const char *value)
+{
+ if (strlen(value) &gt; 8)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ errmsg("str_param must be at most 8 bytes")));
+}
+
+/*
+ * Sample filler: switches characters to lower case.
+ */
+static Size
+fill_my_string_relopt(const char *value, void *ptr)
+{
+ char *tmp = str_tolower(value, strlen(value), DEFAULT_COLLATION_OID);
+ int len = strlen(tmp);
+
+ if (ptr)
+ strcpy((char *) ptr, tmp);
+
+ pfree(tmp);
+ return len + 1;
+}
+
+PG_FUNCTION_INFO_V1(my_options);
+
+Datum
+my_options(PG_FUNCTION_ARGS)
+{
+ local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0);
+
+ init_local_reloptions(relopts, sizeof(MyOptionsStruct));
+ add_local_int_reloption(relopts, "int_param", "integer parameter",
+ 100, 0, 1000000,
+ offsetof(MyOptionsStruct, int_param));
+ add_local_real_reloption(relopts, "real_param", "real parameter",
+ 1.0, 0.0, 1000000.0,
+ offsetof(MyOptionsStruct, real_param));
+ add_local_enum_reloption(relopts, "enum_param", "enum parameter",
+ myEnumValues, MY_ENUM_ON,
+ "Valid values are: \"on\", \"off\" and \"auto\".",
+ offsetof(MyOptionsStruct, enum_param));
+ add_local_string_reloption(relopts, "str_param", "string parameter",
+ str_param_default,
+ &amp;validate_my_string_relopt,
+ &amp;fill_my_string_relopt,
+ offsetof(MyOptionsStruct, str_param));
+
+ PG_RETURN_VOID();
+}
+
+PG_FUNCTION_INFO_V1(my_compress);
+
+Datum
+my_compress(PG_FUNCTION_ARGS)
+{
+ int int_param = 100;
+ double real_param = 1.0;
+ MyEnumType enum_param = MY_ENUM_ON;
+ char *str_param = str_param_default;
+
+ /*
+ * Normally, when opclass contains 'options' method, then options are always
+ * passed to support functions. However, if you add 'options' method to
+ * existing opclass, previously defined indexes have no options, so the
+ * check is required.
+ */
+ if (PG_HAS_OPCLASS_OPTIONS())
+ {
+ MyOptionsStruct *options = (MyOptionsStruct *) PG_GET_OPCLASS_OPTIONS();
+
+ int_param = options-&gt;int_param;
+ real_param = options-&gt;real_param;
+ enum_param = options-&gt;enum_param;
+ str_param = GET_STRING_RELOPTION(options, str_param);
+ }
+
+ /* the rest implementation of support function */
+}
+
+</pre><p>
+ </p><p>
+ Since the representation of the key in <acronym class="acronym">GiST</acronym> is
+ flexible, it may depend on user-specified parameters. For instance,
+ the length of key signature may be specified. See
+ <code class="literal">gtsvector_options()</code> for example.
+ </p></dd><dt><span class="term"><code class="function">sortsupport</code></span></dt><dd><p>
+ Returns a comparator function to sort data in a way that preserves
+ locality. It is used by <code class="command">CREATE INDEX</code> and
+ <code class="command">REINDEX</code> commands. The quality of the created index
+ depends on how well the sort order determined by the comparator function
+ preserves locality of the inputs.
+ </p><p>
+ The <code class="function">sortsupport</code> method is optional. If it is not
+ provided, <code class="command">CREATE INDEX</code> builds the index by inserting
+ each tuple to the tree using the <code class="function">penalty</code> and
+ <code class="function">picksplit</code> functions, which is much slower.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like
+ this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_sortsupport(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+
+ The argument is a pointer to a <code class="structname">SortSupport</code>
+ struct. At a minimum, the function must fill in its comparator field.
+ The comparator takes three arguments: two Datums to compare, and
+ a pointer to the <code class="structname">SortSupport</code> struct. The
+ Datums are the two indexed values in the format that they are stored
+ in the index; that is, in the format returned by the
+ <code class="function">compress</code> method. The full API is defined in
+ <code class="filename">src/include/utils/sortsupport.h</code>.
+ </p><p>
+ The matching code in the C module could then follow this skeleton:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(my_sortsupport);
+
+static int
+my_fastcmp(Datum x, Datum y, SortSupport ssup)
+{
+ /* establish order between x and y by computing some sorting value z */
+
+ int z1 = ComputeSpatialCode(x);
+ int z2 = ComputeSpatialCode(y);
+
+ return z1 == z2 ? 0 : z1 &gt; z2 ? 1 : -1;
+}
+
+Datum
+my_sortsupport(PG_FUNCTION_ARGS)
+{
+ SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);
+
+ ssup-&gt;comparator = my_fastcmp;
+ PG_RETURN_VOID();
+}
+</pre><p>
+ </p></dd></dl></div><p>
+ All the GiST support methods are normally called in short-lived memory
+ contexts; that is, <code class="varname">CurrentMemoryContext</code> will get reset after
+ each tuple is processed. It is therefore not very important to worry about
+ pfree'ing everything you palloc. However, in some cases it's useful for a
+ support method to cache data across repeated calls. To do that, allocate
+ the longer-lived data in <code class="literal">fcinfo-&gt;flinfo-&gt;fn_mcxt</code>, and
+ keep a pointer to it in <code class="literal">fcinfo-&gt;flinfo-&gt;fn_extra</code>. Such
+ data will survive for the life of the index operation (e.g., a single GiST
+ index scan, index build, or index tuple insertion). Be careful to pfree
+ the previous value when replacing a <code class="literal">fn_extra</code> value, or the leak
+ will accumulate for the duration of the operation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist-implementation.html" title="68.4. Implementation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">68.2. Built-in Operator Classes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.4. Implementation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gist-implementation.html b/doc/src/sgml/html/gist-implementation.html
new file mode 100644
index 0000000..2ac2b9e
--- /dev/null
+++ b/doc/src/sgml/html/gist-implementation.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.4. Implementation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist-extensibility.html" title="68.3. Extensibility" /><link rel="next" href="gist-examples.html" title="68.5. Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.4. Implementation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist-extensibility.html" title="68.3. Extensibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 68. GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist-examples.html" title="68.5. Examples">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIST-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.4. Implementation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="gist-implementation.html#GIST-BUFFERING-BUILD">68.4.1. GiST Index Build Methods</a></span></dt></dl></div><div class="sect2" id="GIST-BUFFERING-BUILD"><div class="titlepage"><div><div><h3 class="title">68.4.1. GiST Index Build Methods</h3></div></div></div><p>
+ The simplest way to build a GiST index is just to insert all the entries,
+ one by one. This tends to be slow for large indexes, because if the
+ index tuples are scattered across the index and the index is large enough
+ to not fit in cache, a lot of random I/O will be
+ needed. <span class="productname">PostgreSQL</span> supports two alternative
+ methods for initial build of a GiST index: <em class="firstterm">sorted</em>
+ and <em class="firstterm">buffered</em> modes.
+ </p><p>
+ The sorted method is only available if each of the opclasses used by the
+ index provides a <code class="function">sortsupport</code> function, as described
+ in <a class="xref" href="gist-extensibility.html" title="68.3. Extensibility">Section 68.3</a>. If they do, this method is
+ usually the best, so it is used by default.
+ </p><p>
+ The buffered method works by not inserting tuples directly into the index
+ right away. It can dramatically reduce the amount of random I/O needed
+ for non-ordered data sets. For well-ordered data sets the benefit is
+ smaller or non-existent, because only a small number of pages receive new
+ tuples at a time, and those pages fit in cache even if the index as a
+ whole does not.
+ </p><p>
+ The buffered method needs to call the <code class="function">penalty</code>
+ function more often than the simple method does, which consumes some
+ extra CPU resources. Also, the buffers need temporary disk space, up to
+ the size of the resulting index. Buffering can also influence the quality
+ of the resulting index, in both positive and negative directions. That
+ influence depends on various factors, like the distribution of the input
+ data and the operator class implementation.
+ </p><p>
+ If sorting is not possible, then by default a GiST index build switches
+ to the buffering method when the index size reaches
+ <a class="xref" href="runtime-config-query.html#GUC-EFFECTIVE-CACHE-SIZE">effective_cache_size</a>. Buffering can be manually
+ forced or prevented by the <code class="literal">buffering</code> 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 data
+ is ordered.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist-extensibility.html" title="68.3. Extensibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist-examples.html" title="68.5. Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">68.3. Extensibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.5. Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gist-intro.html b/doc/src/sgml/html/gist-intro.html
new file mode 100644
index 0000000..c0589cf
--- /dev/null
+++ b/doc/src/sgml/html/gist-intro.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist.html" title="Chapter 68. GiST Indexes" /><link rel="next" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist.html" title="Chapter 68. GiST Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 68. GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIST-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.1. Introduction</h2></div></div></div><p>
+ <acronym class="acronym">GiST</acronym> stands for Generalized Search Tree. It is a
+ balanced, tree-structured access method, that acts as a base template in
+ which to implement arbitrary indexing schemes. B-trees, R-trees and many
+ other indexing schemes can be implemented in <acronym class="acronym">GiST</acronym>.
+ </p><p>
+ One advantage of <acronym class="acronym">GiST</acronym> is that it allows the development
+ of custom data types with the appropriate access methods, by
+ an expert in the domain of the data type, rather than a database expert.
+ </p><p>
+ Some of the information here is derived from the University of California
+ at Berkeley's GiST Indexing Project
+ <a class="ulink" href="http://gist.cs.berkeley.edu/" target="_top">web site</a> and
+ Marcel Kornacker's thesis,
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/papers/concurrency/access-methods-for-next-generation.pdf.gz" target="_top">
+ Access Methods for Next-Generation Database Systems</a>.
+ The <acronym class="acronym">GiST</acronym>
+ implementation in <span class="productname">PostgreSQL</span> is primarily
+ maintained by Teodor Sigaev and Oleg Bartunov, and there is more
+ information on their
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">web site</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist.html" title="Chapter 68. GiST Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gist.html" title="Chapter 68. GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist-builtin-opclasses.html" title="68.2. Built-in Operator Classes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 68. GiST Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.2. Built-in Operator Classes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gist.html b/doc/src/sgml/html/gist.html
new file mode 100644
index 0000000..b433703
--- /dev/null
+++ b/doc/src/sgml/html/gist.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 68. GiST Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="btree-implementation.html" title="67.4. Implementation" /><link rel="next" href="gist-intro.html" title="68.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 68. GiST Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-implementation.html" title="67.4. Implementation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gist-intro.html" title="68.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="GIST"><div class="titlepage"><div><div><h2 class="title">Chapter 68. GiST Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="gist-intro.html">68.1. Introduction</a></span></dt><dt><span class="sect1"><a href="gist-builtin-opclasses.html">68.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="gist-extensibility.html">68.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="gist-implementation.html">68.4. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="gist-implementation.html#GIST-BUFFERING-BUILD">68.4.1. GiST Index Build Methods</a></span></dt></dl></dd><dt><span class="sect1"><a href="gist-examples.html">68.5. Examples</a></span></dt></dl></div><a id="id-1.10.19.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-implementation.html" title="67.4. Implementation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gist-intro.html" title="68.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">67.4. Implementation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/git.html b/doc/src/sgml/html/git.html
new file mode 100644
index 0000000..975e1ab
--- /dev/null
+++ b/doc/src/sgml/html/git.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>I.1. Getting the Source via Git</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sourcerepo.html" title="Appendix I. The Source Code Repository" /><link rel="next" href="docguide.html" title="Appendix J. Documentation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">I.1. Getting the Source via <span class="productname">Git</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Up</a></td><th width="60%" align="center">Appendix I. The Source Code Repository</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="docguide.html" title="Appendix J. Documentation">Next</a></td></tr></table><hr /></div><div class="sect1" id="GIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">I.1. Getting the Source via <span class="productname">Git</span></h2></div></div></div><p>
+ With <span class="productname">Git</span> you will make a copy of the entire code repository
+ on your local machine, so you will have access to all history and branches
+ offline. This is the fastest and most flexible way to develop or test
+ patches.
+ </p><div class="procedure" id="id-1.11.10.5.3"><p class="title"><strong>Git</strong></p><ol class="procedure" type="1"><li class="step"><p>
+ You will need an installed version of <span class="productname">Git</span>, which you can
+ get from <a class="ulink" href="https://git-scm.com" target="_top">https://git-scm.com</a>. Many systems already
+ have a recent version of <span class="application">Git</span> installed by default, or
+ available in their package distribution system.
+ </p></li><li class="step"><p>
+ To begin using the Git repository, make a clone of the official mirror:
+
+</p><pre class="programlisting">
+git clone https://git.postgresql.org/git/postgresql.git
+</pre><p>
+
+ This will copy the full repository to your local machine, so it may take
+ a while to complete, especially if you have a slow Internet connection.
+ The files will be placed in a new subdirectory <code class="filename">postgresql</code> of
+ your current directory.
+ </p><p>
+ The Git mirror can also be reached via the Git protocol. Just change the URL
+ prefix to <code class="literal">git</code>, as in:
+
+</p><pre class="programlisting">
+git clone git://git.postgresql.org/git/postgresql.git
+</pre><p>
+
+ </p></li><li class="step"><p>
+ Whenever you want to get the latest updates in the system, <code class="command">cd</code>
+ into the repository, and run:
+
+</p><pre class="programlisting">
+git fetch
+</pre><p>
+ </p></li></ol></div><p>
+ <span class="productname">Git</span> can do a lot more things than just fetch the source. For
+ more information, consult the <span class="productname">Git</span> man pages, or see the
+ website at <a class="ulink" href="https://git-scm.com" target="_top">https://git-scm.com</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sourcerepo.html" title="Appendix I. The Source Code Repository">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="docguide.html" title="Appendix J. Documentation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix I. The Source Code Repository </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix J. Documentation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/glossary.html b/doc/src/sgml/html/glossary.html
new file mode 100644
index 0000000..0ca28c0
--- /dev/null
+++ b/doc/src/sgml/html/glossary.html
@@ -0,0 +1,1061 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix M. Glossary</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="acronyms.html" title="Appendix L. Acronyms" /><link rel="next" href="color.html" title="Appendix N. Color Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix M. Glossary</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="acronyms.html" title="Appendix L. Acronyms">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="color.html" title="Appendix N. Color Support">Next</a></td></tr></table><hr /></div><div class="appendix" id="GLOSSARY"><div class="titlepage"><div><div><h2 class="title">Appendix M. Glossary</h2></div></div></div><p>
+ This is a list of terms and their meaning in the context of
+ <span class="productname">PostgreSQL</span> and relational database
+ systems in general.
+ </p><div class="glosslist"><dl><dt id="GLOSSARY-ACID"><span class="glossterm">ACID</span></dt><dd class="glossdef"><p>
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATOMICITY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATOMICITY" title="Atomicity">Atomicity</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-CONSISTENCY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSISTENCY" title="Consistency">Consistency</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-ISOLATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ISOLATION" title="Isolation">Isolation</a></em></a>, and
+ <a class="glossterm" href="glossary.html#GLOSSARY-DURABILITY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DURABILITY" title="Durability">Durability</a></em></a>.
+ This set of properties of database transactions is intended to
+ guarantee validity in concurrent operation and even in event of
+ errors, power failures, etc.
+ </p></dd><dt id="GLOSSARY-AGGREGATE"><span class="glossterm">Aggregate function (routine)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">function</a></em></a> that
+ combines (<em class="firstterm">aggregates</em>) multiple input values,
+ for example by counting, averaging or adding,
+ yielding a single output value.
+ </p><p>
+ For more information, see
+ <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a>.
+ </p><p>See Also <a class="glossseealso" href="glossary.html#GLOSSARY-WINDOW-FUNCTION">Window function (routine)</a>.</p></dd><dt><span class="glossterm">Analytic function</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-WINDOW-FUNCTION">Window function (routine)</a>.</p></dd><dt id="GLOSSARY-ANALYZE"><span class="glossterm">Analyze (operation)</span></dt><dd class="glossdef"><p>
+ The act of collecting statistics from data in
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">tables</a></em></a>
+ and other <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relations</a></em></a>
+ to help the <a class="glossterm" href="glossary.html#GLOSSARY-PLANNER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PLANNER" title="Query planner">query planner</a></em></a>
+ to make decisions about how to execute
+ <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">queries</a></em></a>.
+ </p><p>
+ (Don't confuse this term with the <code class="literal">ANALYZE</code> option
+ to the <a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a> command.)
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>.
+ </p></dd><dt id="GLOSSARY-ATOMIC"><span class="glossterm">Atomic</span></dt><dd class="glossdef"><p>
+ In reference to a <a class="glossterm" href="glossary.html#GLOSSARY-DATUM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATUM" title="Datum">datum</a></em></a>:
+ the fact that its value cannot be broken down into smaller
+ components.
+ </p></dd><dd class="glossdef"><p>
+ In reference to a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">database transaction</a></em></a>:
+ see <a class="glossterm" href="glossary.html#GLOSSARY-ATOMICITY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATOMICITY" title="Atomicity">atomicity</a></em></a>.
+ </p></dd><dt id="GLOSSARY-ATOMICITY"><span class="glossterm">Atomicity</span></dt><dd class="glossdef"><p>
+ The property of a <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a>
+ that either all its operations complete as a single unit or none do.
+ In addition, if a system failure occurs during the execution of a
+ transaction, no partial results are visible after recovery.
+ This is one of the <acronym class="acronym">ACID</acronym> properties.
+ </p></dd><dt id="GLOSSARY-ATTRIBUTE"><span class="glossterm">Attribute</span></dt><dd class="glossdef"><p>
+ An element with a certain name and data type found within a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">tuple</a></em></a>.
+ </p></dd><dt id="GLOSSARY-AUTOVACUUM"><span class="glossterm">Autovacuum (process)</span></dt><dd class="glossdef"><p>
+ A set of background processes that routinely perform
+ <a class="glossterm" href="glossary.html#GLOSSARY-VACUUM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VACUUM" title="Vacuum">vacuum</a></em></a>
+ and <a class="glossterm" href="glossary.html#GLOSSARY-ANALYZE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ANALYZE" title="Analyze (operation)">analyze</a></em></a> operations.
+ The <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ that coordinates the work and is always present (unless autovacuum
+ is disabled) is known as the <em class="firstterm">autovacuum launcher</em>,
+ and the processes that carry out the tasks are known as the
+ <em class="firstterm">autovacuum workers</em>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>.
+ </p></dd><dt id="GLOSSARY-AUXILIARY-PROC"><span class="glossterm">Auxiliary process</span></dt><dd class="glossdef"><p>
+ A process within an <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>
+ that is in charge of some specific background task for the instance.
+ The auxiliary processes consist of
+
+ the <a class="glossterm" href="glossary.html#GLOSSARY-AUTOVACUUM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUTOVACUUM" title="Autovacuum (process)">autovacuum launcher</a></em></a>
+ (but not the autovacuum workers),
+ the <a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WRITER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WRITER" title="Background writer (process)">background writer</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINTER" title="Checkpointer (process)">checkpointer</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-LOGGER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-LOGGER" title="Logger (process)">logger</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-STARTUP-PROCESS"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-STARTUP-PROCESS" title="Startup process">startup process</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-WAL-ARCHIVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-ARCHIVER" title="WAL archiver (process)">WAL archiver</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECEIVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECEIVER" title="WAL receiver (process)">WAL receiver</a></em></a>
+ (but not the <a class="glossterm" href="glossary.html#GLOSSARY-WAL-SENDER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-SENDER" title="WAL sender (process)">WAL senders</a></em></a>),
+ and the <a class="glossterm" href="glossary.html#GLOSSARY-WAL-WRITER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-WRITER" title="WAL writer (process)">WAL writer</a></em></a>.
+ </p></dd><dt id="GLOSSARY-BACKEND"><span class="glossterm">Backend (process)</span></dt><dd class="glossdef"><p>
+ Process of an <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>
+ which acts on behalf of a <a class="glossterm" href="glossary.html#GLOSSARY-SESSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SESSION" title="Session">client session</a></em></a>
+ and handles its requests.
+ </p><p>
+ (Don't confuse this term with the similar terms
+ <a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WORKER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WORKER" title="Background worker (process)">Background Worker</a></em></a> or
+ <a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WRITER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKGROUND-WRITER" title="Background writer (process)">Background Writer</a></em></a>).
+ </p></dd><dt id="GLOSSARY-BACKGROUND-WORKER"><span class="glossterm">Background worker (process)</span></dt><dd class="glossdef"><p>
+ Process within an <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>,
+ which runs system- or user-supplied code.
+ Serves as infrastructure for several features in
+ <span class="productname">PostgreSQL</span>, such as
+ <a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION" title="Replication">logical replication</a></em></a>
+ and <a class="glossterm" href="glossary.html#GLOSSARY-PARALLEL-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PARALLEL-QUERY" title="Parallel query">parallel queries</a></em></a>.
+ In addition, <a class="glossterm" href="glossary.html#GLOSSARY-EXTENSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-EXTENSION" title="Extension">Extensions</a></em></a> can add
+ custom background worker processes.
+ </p><p>
+ For more information, see
+ <a class="xref" href="bgworker.html" title="Chapter 48. Background Worker Processes">Chapter 48</a>.
+ </p></dd><dt id="GLOSSARY-BACKGROUND-WRITER"><span class="glossterm">Background writer (process)</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ that writes dirty
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATA-PAGE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATA-PAGE" title="Data page">data pages</a></em></a> from
+ <a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY" title="Shared memory">shared memory</a></em></a> to
+ the file system. It wakes up periodically, but works only for a short
+ period in order to distribute its expensive <acronym class="acronym">I/O</acronym>
+ activity over time to avoid generating larger
+ <acronym class="acronym">I/O</acronym> peaks which could block other processes.
+ </p><p>
+ For more information, see
+ <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER" title="20.4.5. Background Writer">Section 20.4.5</a>.
+ </p></dd><dt id="GLOSSARY-BASEBACKUP"><span class="glossterm">Base Backup</span></dt><dd class="glossdef"><p>
+ A binary copy of all
+ <a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER" title="Database cluster">database cluster</a></em></a>
+ files. It is generated by the tool <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a>.
+ In combination with WAL files it can be used as the starting point
+ for recovery, log shipping, or streaming replication.
+ </p></dd><dt id="GLOSSARY-BLOAT"><span class="glossterm">Bloat</span></dt><dd class="glossdef"><p>
+ Space in data pages which does not contain current row versions,
+ such as unused (free) space or outdated row versions.
+ </p></dd><dt id="GLOSSARY-CAST"><span class="glossterm">Cast</span></dt><dd class="glossdef"><p>
+ A conversion of a <a class="glossterm" href="glossary.html#GLOSSARY-DATUM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATUM" title="Datum">datum</a></em></a>
+ from its current data type to another data type.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>.
+ </p></dd><dt id="GLOSSARY-CATALOG"><span class="glossterm">Catalog</span></dt><dd class="glossdef"><p>
+ The <acronym class="acronym">SQL</acronym> standard uses this term to
+ indicate what is called a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> in
+ <span class="productname">PostgreSQL</span>'s terminology.
+ </p><p>
+ (Don't confuse this term with
+ <a class="glossterm" href="glossary.html#GLOSSARY-SYSTEM-CATALOG"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SYSTEM-CATALOG" title="System catalog">system catalog</a></em></a>).
+ </p><p>
+ For more information, see
+ <a class="xref" href="manage-ag-overview.html" title="23.1. Overview">Section 23.1</a>.
+ </p></dd><dt id="GLOSSARY-CHECK-CONSTRAINT"><span class="glossterm">Check constraint</span></dt><dd class="glossdef"><p>
+ A type of <a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT" title="Constraint">constraint</a></em></a>
+ defined on a <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>
+ which restricts the values allowed in one or more
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>. The
+ check constraint can make reference to any attribute of the same row in
+ the relation, but cannot reference other rows of the same relation or
+ other relations.
+ </p><p>
+ For more information, see
+ <a class="xref" href="ddl-constraints.html" title="5.4. Constraints">Section 5.4</a>.
+ </p></dd><dt id="GLOSSARY-CHECKPOINT"><span class="glossterm">Checkpoint</span></dt><dd class="glossdef"><p>
+ A point in the <a class="glossterm" href="glossary.html#GLOSSARY-WAL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL" title="Write-ahead log">WAL</a></em></a> sequence
+ at which it is guaranteed that the heap and index data files have been
+ updated with all information from
+ <a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY" title="Shared memory">shared memory</a></em></a>
+ modified before that checkpoint;
+ a <em class="firstterm">checkpoint record</em> is written and flushed to WAL
+ to mark that point.
+ </p><p>
+ A checkpoint is also the act of carrying out all the actions that
+ are necessary to reach a checkpoint as defined above.
+ This process is initiated when predefined conditions are met,
+ such as a specified amount of time has passed, or a certain volume
+ of records has been written; or it can be invoked by the user
+ with the command <code class="command">CHECKPOINT</code>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a>.
+ </p></dd><dt id="GLOSSARY-CHECKPOINTER"><span class="glossterm">Checkpointer (process)</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ that is responsible for executing
+ <a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINT" title="Checkpoint">checkpoints</a></em></a>.
+ </p></dd><dt><span class="glossterm">Class (archaic)</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-RELATION">Relation</a>.</p></dd><dt id="GLOSSARY-CLIENT"><span class="glossterm">Client (process)</span></dt><dd class="glossdef"><p>
+ Any process, possibly remote, that establishes a
+ <a class="glossterm" href="glossary.html#GLOSSARY-SESSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SESSION" title="Session">session</a></em></a>
+ by <a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION" title="Connection">connecting</a></em></a> to an
+ <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>
+ to interact with a <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>.
+ </p></dd><dt id="GLOSSARY-COLUMN"><span class="glossterm">Column</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attribute</a></em></a> found in
+ a <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> or
+ <a class="glossterm" href="glossary.html#GLOSSARY-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VIEW" title="View">view</a></em></a>.
+ </p></dd><dt id="GLOSSARY-COMMIT"><span class="glossterm">Commit</span></dt><dd class="glossdef"><p>
+ The act of finalizing a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a> within
+ the <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>, which
+ makes it visible to other transactions and assures its
+ <a class="glossterm" href="glossary.html#GLOSSARY-DURABILITY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DURABILITY" title="Durability">durability</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>.
+ </p></dd><dt id="GLOSSARY-CONCURRENCY"><span class="glossterm">Concurrency</span></dt><dd class="glossdef"><p>
+ The concept that multiple independent operations happen within the
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> at the same time.
+ In <span class="productname">PostgreSQL</span>, concurrency is controlled by
+ the <a class="glossterm" href="glossary.html#GLOSSARY-MVCC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-MVCC" title="Multi-version concurrency control (MVCC)">multiversion concurrency control</a></em></a>
+ mechanism.
+ </p></dd><dt id="GLOSSARY-CONNECTION"><span class="glossterm">Connection</span></dt><dd class="glossdef"><p>
+ An established line of communication between a client process and a
+ <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend</a></em></a> process,
+ usually over a network, supporting a
+ <a class="glossterm" href="glossary.html#GLOSSARY-SESSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SESSION" title="Session">session</a></em></a>. This term is
+ sometimes used as a synonym for session.
+ </p><p>
+ For more information, see
+ <a class="xref" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Section 20.3</a>.
+ </p></dd><dt id="GLOSSARY-CONSISTENCY"><span class="glossterm">Consistency</span></dt><dd class="glossdef"><p>
+ The property that the data in the
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>
+ is always in compliance with
+ <a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT" title="Constraint">integrity constraints</a></em></a>.
+ Transactions may be allowed to violate some of the constraints
+ transiently before it commits, but if such violations are not resolved
+ by the time it commits, such a transaction is automatically
+ <a class="glossterm" href="glossary.html#GLOSSARY-ROLLBACK"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ROLLBACK" title="Rollback">rolled back</a></em></a>.
+ This is one of the <acronym class="acronym">ACID</acronym> properties.
+ </p></dd><dt id="GLOSSARY-CONSTRAINT"><span class="glossterm">Constraint</span></dt><dd class="glossdef"><p>
+ A restriction on the values of data allowed within a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>,
+ or in attributes of a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="ddl-constraints.html" title="5.4. Constraints">Section 5.4</a>.
+ </p></dd><dt id="GLOSSARY-CUMULATIVE-STATISTICS"><span class="glossterm">Cumulative Statistics System</span></dt><dd class="glossdef"><p>
+ A system which, if enabled, accumulates statistical information
+ about the <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>'s
+ activities.
+ </p><p>
+ For more information, see
+ <a class="xref" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Section 28.2</a>.
+ </p></dd><dt><span class="glossterm">Data area</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-DATA-DIRECTORY">Data directory</a>.</p></dd><dt id="GLOSSARY-DATABASE"><span class="glossterm">Database</span></dt><dd class="glossdef"><p>
+ A named collection of
+ <a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT" title="SQL object">local SQL objects</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="manage-ag-overview.html" title="23.1. Overview">Section 23.1</a>.
+ </p></dd><dt id="GLOSSARY-DB-CLUSTER"><span class="glossterm">Database cluster</span></dt><dd class="glossdef"><p>
+ A collection of databases and global SQL objects,
+ and their common static and dynamic metadata.
+ Sometimes referred to as a
+ <em class="firstterm">cluster</em>.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, the term
+ <em class="firstterm">cluster</em> is also sometimes used to refer to an instance.
+ (Don't confuse this term with the SQL command <code class="command">CLUSTER</code>.)
+ </p></dd><dt><span class="glossterm">Database server</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-INSTANCE">Instance</a>.</p></dd><dt id="GLOSSARY-DATA-DIRECTORY"><span class="glossterm">Data directory</span></dt><dd class="glossdef"><p>
+ The base directory on the file system of a
+ <a class="glossterm" href="glossary.html#GLOSSARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SERVER" title="Server">server</a></em></a> that contains all
+ data files and subdirectories associated with a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER" title="Database cluster">database cluster</a></em></a>
+ (with the exception of
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLESPACE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLESPACE" title="Tablespace">tablespaces</a></em></a>,
+ and optionally <a class="glossterm" href="glossary.html#GLOSSARY-WAL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL" title="Write-ahead log">WAL</a></em></a>).
+ The environment variable <code class="literal">PGDATA</code> is commonly used to
+ refer to the data directory.
+ </p><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER" title="Database cluster">cluster</a></em></a>'s storage
+ space comprises the data directory plus any additional tablespaces.
+ </p><p>
+ For more information, see
+ <a class="xref" href="storage-file-layout.html" title="73.1. Database File Layout">Section 73.1</a>.
+ </p></dd><dt id="GLOSSARY-DATA-PAGE"><span class="glossterm">Data page</span></dt><dd class="glossdef"><p>
+ The basic structure used to store relation data.
+ All pages are of the same size.
+ Data pages are typically stored on disk, each in a specific file,
+ and can be read to <a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY" title="Shared memory">shared buffers</a></em></a>
+ where they can be modified, becoming
+ <em class="firstterm">dirty</em>. They become clean when written
+ to disk. New pages, which initially exist in memory only, are also
+ dirty until written.
+ </p></dd><dt id="GLOSSARY-DATUM"><span class="glossterm">Datum</span></dt><dd class="glossdef"><p>
+ The internal representation of one value of an <acronym class="acronym">SQL</acronym>
+ data type.
+ </p></dd><dt id="GLOSSARY-DELETE"><span class="glossterm">Delete</span></dt><dd class="glossdef"><p>
+ An <acronym class="acronym">SQL</acronym> command which removes
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">rows</a></em></a> from a given
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>
+ or <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a>.
+ </p></dd><dt id="GLOSSARY-DOMAIN"><span class="glossterm">Domain</span></dt><dd class="glossdef"><p>
+ A user-defined data type that is based on another underlying data type.
+ It acts the same as the underlying type except for possibly restricting
+ the set of allowed values.
+ </p><p>
+ For more information, see <a class="xref" href="domains.html" title="8.18. Domain Types">Section 8.18</a>.
+ </p></dd><dt id="GLOSSARY-DURABILITY"><span class="glossterm">Durability</span></dt><dd class="glossdef"><p>
+ The assurance that once a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a> has
+ been <a class="glossterm" href="glossary.html#GLOSSARY-COMMIT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-COMMIT" title="Commit">committed</a></em></a>, the
+ changes remain even after a system failure or crash.
+ This is one of the <acronym class="acronym">ACID</acronym> properties.
+ </p></dd><dt><span class="glossterm">Epoch</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-XID">Transaction ID</a>.</p></dd><dt id="GLOSSARY-EXTENSION"><span class="glossterm">Extension</span></dt><dd class="glossdef"><p>
+ A software add-on package that can be installed on an
+ <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a> to
+ get extra features.
+ </p><p>
+ For more information, see
+ <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a>.
+ </p></dd><dt id="GLOSSARY-FILE-SEGMENT"><span class="glossterm">File segment</span></dt><dd class="glossdef"><p>
+ A physical file which stores data for a given
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>.
+ File segments are limited in size by a configuration value
+ (typically 1 gigabyte),
+ so if a relation exceeds that size, it is split into multiple segments.
+ </p><p>
+ For more information, see
+ <a class="xref" href="storage-file-layout.html" title="73.1. Database File Layout">Section 73.1</a>.
+ </p><p>
+ (Don't confuse this term with the similar term
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE" title="WAL file">WAL segment</a></em></a>).
+ </p></dd><dt id="GLOSSARY-FOREIGN-DATA-WRAPPER"><span class="glossterm">Foreign data wrapper</span></dt><dd class="glossdef"><p>
+ A means of representing data that is not contained in the local
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> so that it appears as if were in local
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table(s)</a></em></a>. With a foreign data wrapper it is
+ possible to define a <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-SERVER" title="Foreign server">foreign server</a></em></a> and
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE" title="Foreign table (relation)">foreign tables</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>.
+ </p></dd><dt id="GLOSSARY-FOREIGN-KEY"><span class="glossterm">Foreign key</span></dt><dd class="glossdef"><p>
+ A type of <a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT" title="Constraint">constraint</a></em></a>
+ defined on one or more <a class="glossterm" href="glossary.html#GLOSSARY-COLUMN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-COLUMN" title="Column">columns</a></em></a>
+ in a <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> which
+ requires the value(s) in those <a class="glossterm" href="glossary.html#GLOSSARY-COLUMN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-COLUMN" title="Column">columns</a></em></a> to
+ identify zero or one <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">row</a></em></a>
+ in another (or, infrequently, the same)
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>.
+ </p></dd><dt id="GLOSSARY-FOREIGN-SERVER"><span class="glossterm">Foreign server</span></dt><dd class="glossdef"><p>
+ A named collection of
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE" title="Foreign table (relation)">foreign tables</a></em></a> which
+ all use the same
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER" title="Foreign data wrapper">foreign data wrapper</a></em></a>
+ and have other configuration values in common.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>.
+ </p></dd><dt id="GLOSSARY-FOREIGN-TABLE"><span class="glossterm">Foreign table (relation)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> which appears to have
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">rows</a></em></a> and
+ <a class="glossterm" href="glossary.html#GLOSSARY-COLUMN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-COLUMN" title="Column">columns</a></em></a> similar to a
+ regular <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>, but will forward
+ requests for data through its
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER" title="Foreign data wrapper">foreign data wrapper</a></em></a>,
+ which will return <a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET" title="Result set">result sets</a></em></a>
+ structured according to the definition of the
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE" title="Foreign table (relation)">foreign table</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>.
+ </p></dd><dt id="GLOSSARY-FORK"><span class="glossterm">Fork</span></dt><dd class="glossdef"><p>
+ Each of the separate segmented file sets in which a relation is stored.
+ The <em class="firstterm">main fork</em> is where the actual data resides.
+ There also exist two secondary forks for metadata:
+ the <a class="glossterm" href="glossary.html#GLOSSARY-FSM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FSM" title="Free space map (fork)">free space map</a></em></a>
+ and the <a class="glossterm" href="glossary.html#GLOSSARY-VM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VM" title="Visibility map (fork)">visibility map</a></em></a>.
+ <a class="glossterm" href="glossary.html#GLOSSARY-UNLOGGED"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-UNLOGGED" title="Unlogged">Unlogged relations</a></em></a>
+ also have an <em class="firstterm">init fork</em>.
+ </p></dd><dt id="GLOSSARY-FSM"><span class="glossterm">Free space map (fork)</span></dt><dd class="glossdef"><p>
+ A storage structure that keeps metadata about each data page of a table's
+ main fork. The free space map entry for each page stores the
+ amount of free space that's available for future tuples, and is structured
+ to be efficiently searched for available space for a new tuple of a given
+ size.
+ </p><p>
+ For more information, see
+ <a class="xref" href="storage-fsm.html" title="73.3. Free Space Map">Section 73.3</a>.
+ </p></dd><dt id="GLOSSARY-FUNCTION"><span class="glossterm">Function (routine)</span></dt><dd class="glossdef"><p>
+ A type of routine that receives zero or more arguments, returns zero or more
+ output values, and is constrained to run within one transaction.
+ Functions are invoked as part of a query, for example via
+ <code class="command">SELECT</code>.
+ Certain functions can return
+ <a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET" title="Result set">sets</a></em></a>; those are
+ called <em class="firstterm">set-returning functions</em>.
+ </p><p>
+ Functions can also be used for
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRIGGER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRIGGER" title="Trigger">triggers</a></em></a> to invoke.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>.
+ </p></dd><dt id="GLOSSARY-GRANT"><span class="glossterm">Grant</span></dt><dd class="glossdef"><p>
+ An <acronym class="acronym">SQL</acronym> command that is used to allow a
+ <a class="glossterm" href="glossary.html#GLOSSARY-USER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-USER" title="User">user</a></em></a> or
+ <a class="glossterm" href="glossary.html#GLOSSARY-ROLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ROLE" title="Role">role</a></em></a> to access
+ specific objects within the <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>.
+ </p></dd><dt id="GLOSSARY-HEAP"><span class="glossterm">Heap</span></dt><dd class="glossdef"><p>
+ Contains the values of <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">row</a></em></a>
+ attributes (i.e., the data) for a
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>.
+ The heap is realized within one or more
+ <a class="glossterm" href="glossary.html#GLOSSARY-FILE-SEGMENT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FILE-SEGMENT" title="File segment">file segments</a></em></a>
+ in the relation's <a class="glossterm" href="glossary.html#GLOSSARY-FORK"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FORK" title="Fork">main fork</a></em></a>.
+ </p></dd><dt id="GLOSSARY-HOST"><span class="glossterm">Host</span></dt><dd class="glossdef"><p>
+ A computer that communicates with other computers over a network.
+ This is sometimes used as a synonym for
+ <a class="glossterm" href="glossary.html#GLOSSARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SERVER" title="Server">server</a></em></a>.
+ It is also used to refer to a computer where
+ <a class="glossterm" href="glossary.html#GLOSSARY-CLIENT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CLIENT" title="Client (process)">client processes</a></em></a> run.
+ </p></dd><dt id="GLOSSARY-INDEX"><span class="glossterm">Index (relation)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> that contains
+ data derived from a <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>
+ or <a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW" title="Materialized view (relation)">materialized view</a></em></a>.
+ Its internal structure supports fast retrieval of and access to the original
+ data.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>.
+ </p></dd><dt id="GLOSSARY-INSERT"><span class="glossterm">Insert</span></dt><dd class="glossdef"><p>
+ An <acronym class="acronym">SQL</acronym> command used to add new data into a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>.
+ </p></dd><dt id="GLOSSARY-INSTANCE"><span class="glossterm">Instance</span></dt><dd class="glossdef"><p>
+ A group of <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend</a></em></a> and
+ <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary processes</a></em></a>
+ that communicate using a common shared memory area. One
+ <a class="glossterm" href="glossary.html#GLOSSARY-POSTMASTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-POSTMASTER" title="Postmaster (process)">postmaster process</a></em></a>
+ manages the instance; one instance manages exactly one
+ <a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER" title="Database cluster">database cluster</a></em></a>
+ with all its databases. Many instances can run on the same
+ <a class="glossterm" href="glossary.html#GLOSSARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SERVER" title="Server">server</a></em></a>
+ as long as their <acronym class="acronym">TCP</acronym> ports do not conflict.
+ </p><p>
+ The instance handles all key features of a <acronym class="acronym">DBMS</acronym>:
+ read and write access to files and shared memory,
+ assurance of the <acronym class="acronym">ACID</acronym> properties,
+ <a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION" title="Connection">connections</a></em></a> to
+ <a class="glossterm" href="glossary.html#GLOSSARY-CLIENT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CLIENT" title="Client (process)">client processes</a></em></a>,
+ privilege verification, crash recovery, replication, etc.
+ </p></dd><dt id="GLOSSARY-ISOLATION"><span class="glossterm">Isolation</span></dt><dd class="glossdef"><p>
+ The property that the effects of a transaction are not visible to
+ <a class="glossterm" href="glossary.html#GLOSSARY-CONCURRENCY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONCURRENCY" title="Concurrency">concurrent transactions</a></em></a>
+ before it commits.
+ This is one of the <acronym class="acronym">ACID</acronym> properties.
+ </p><p>
+ For more information, see <a class="xref" href="transaction-iso.html" title="13.2. Transaction Isolation">Section 13.2</a>.
+ </p></dd><dt id="GLOSSARY-JOIN"><span class="glossterm">Join</span></dt><dd class="glossdef"><p>
+ An operation and <acronym class="acronym">SQL</acronym> keyword used in
+ <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">queries</a></em></a>
+ for combining data from multiple
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relations</a></em></a>.
+ </p></dd><dt id="GLOSSARY-KEY"><span class="glossterm">Key</span></dt><dd class="glossdef"><p>
+ A means of identifying a <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">row</a></em></a> within a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> or
+ other <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> by
+ values contained within one or more
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>
+ in that relation.
+ </p></dd><dt id="GLOSSARY-LOCK"><span class="glossterm">Lock</span></dt><dd class="glossdef"><p>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </p></dd><dt id="GLOSSARY-LOG-FILE"><span class="glossterm">Log file</span></dt><dd class="glossdef"><p>
+ Log files contain human-readable text lines about events.
+ Examples include login failures, long-running queries, etc.
+ </p><p>
+ For more information, see
+ <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a>.
+ </p></dd><dt id="GLOSSARY-LOGGED"><span class="glossterm">Logged</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> is considered
+ <a class="glossterm" href="glossary.html#GLOSSARY-LOGGED"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-LOGGED" title="Logged">logged</a></em></a> if changes to it are sent to the
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL" title="Write-ahead log">WAL</a></em></a>. By default, all regular
+ tables are logged. A table can be specified as
+ <a class="glossterm" href="glossary.html#GLOSSARY-UNLOGGED"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-UNLOGGED" title="Unlogged">unlogged</a></em></a> either at
+ creation time or via the <code class="command">ALTER TABLE</code> command.
+ </p></dd><dt id="GLOSSARY-LOGGER"><span class="glossterm">Logger (process)</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ which, if enabled, writes information about database events into the current
+ <a class="glossterm" href="glossary.html#GLOSSARY-LOG-FILE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-LOG-FILE" title="Log file">log file</a></em></a>.
+ When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <em class="firstterm">syslogger</em>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Section 20.8</a>.
+ </p></dd><dt id="GLOSSARY-LOG-RECORD"><span class="glossterm">Log record</span></dt><dd class="glossdef"><p>
+ Archaic term for a <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD" title="WAL record">WAL record</a></em></a>.
+ </p></dd><dt><span class="glossterm">Master (server)</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-PRIMARY-SERVER">Primary (server)</a>.</p></dd><dt id="GLOSSARY-MATERIALIZED"><span class="glossterm">Materialized</span></dt><dd class="glossdef"><p>
+ The property that some information has been pre-computed and stored
+ for later use, rather than computing it on-the-fly.
+ </p><p>
+ This term is used in
+ <a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW" title="Materialized view (relation)">materialized view</a></em></a>,
+ to mean that the data derived from the view's query is stored on
+ disk separately from the sources of that data.
+ </p><p>
+ This term is also used to refer to some multi-step queries to mean that
+ the data resulting from executing a given step is stored in memory
+ (with the possibility of spilling to disk), so that it can be read multiple
+ times by another step.
+ </p></dd><dt id="GLOSSARY-MATERIALIZED-VIEW"><span class="glossterm">Materialized view (relation)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> that is
+ defined by a <code class="command">SELECT</code> statement
+ (just like a <a class="glossterm" href="glossary.html#GLOSSARY-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VIEW" title="View">view</a></em></a>),
+ but stores data in the same way that a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> does. It cannot be
+ modified via <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> operations.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a>.
+ </p></dd><dt id="GLOSSARY-MVCC"><span class="glossterm">Multi-version concurrency control (MVCC)</span></dt><dd class="glossdef"><p>
+ A mechanism designed to allow several
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transactions</a></em></a> to be
+ reading and writing the same rows without one process causing other
+ processes to stall.
+ In <span class="productname">PostgreSQL</span>, MVCC is implemented by
+ creating copies (<em class="firstterm">versions</em>) of
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">tuples</a></em></a> as they are
+ modified; after transactions that can see the old versions terminate,
+ those old versions need to be removed.
+ </p></dd><dt id="GLOSSARY-NULL"><span class="glossterm">Null</span></dt><dd class="glossdef"><p>
+ A concept of non-existence that is a central tenet of relational
+ database theory. It represents the absence of a definite value.
+ </p></dd><dt><span class="glossterm">Optimizer</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-PLANNER">Query planner</a>.</p></dd><dt id="GLOSSARY-PARALLEL-QUERY"><span class="glossterm">Parallel query</span></dt><dd class="glossdef"><p>
+ The ability to handle parts of executing a
+ <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">query</a></em></a> to take advantage
+ of parallel processes on servers with multiple <acronym class="acronym">CPU</acronym>s.
+ </p></dd><dt id="GLOSSARY-PARTITION"><span class="glossterm">Partition</span></dt><dd class="glossdef"><p>
+ One of several disjoint (not overlapping) subsets of a larger set.
+ </p></dd><dd class="glossdef"><p>
+ In reference to a
+ <a class="glossterm" href="glossary.html#GLOSSARY-PARTITIONED-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PARTITIONED-TABLE" title="Partitioned table (relation)">partitioned table</a></em></a>:
+ One of the tables that each contain part of the data of the partitioned table,
+ which is said to be the <em class="firstterm">parent</em>.
+ The partition is itself a table, so it can also be queried directly;
+ at the same time, a partition can sometimes be a partitioned table,
+ allowing hierarchies to be created.
+ </p></dd><dd class="glossdef"><p>
+ In reference to a <a class="glossterm" href="glossary.html#GLOSSARY-WINDOW-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WINDOW-FUNCTION" title="Window function (routine)">window function</a></em></a>
+ in a <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">query</a></em></a>,
+ a partition is a user-defined criterion that identifies which neighboring
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">rows</a></em></a>
+ of the <a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET" title="Result set">query's result set</a></em></a>
+ can be considered by the function.
+ </p></dd><dt id="GLOSSARY-PARTITIONED-TABLE"><span class="glossterm">Partitioned table (relation)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> that is
+ in semantic terms the same as a <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>,
+ but whose storage is distributed across several
+ <a class="glossterm" href="glossary.html#GLOSSARY-PARTITION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PARTITION" title="Partition">partitions</a></em></a>.
+ </p></dd><dt id="GLOSSARY-POSTMASTER"><span class="glossterm">Postmaster (process)</span></dt><dd class="glossdef"><p>
+ The very first process of an <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>.
+ It starts and manages the
+ <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary processes</a></em></a>
+ and creates <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend processes</a></em></a>
+ on demand.
+ </p><p>
+ For more information, see
+ <a class="xref" href="server-start.html" title="19.3. Starting the Database Server">Section 19.3</a>.
+ </p></dd><dt id="GLOSSARY-PRIMARY-KEY"><span class="glossterm">Primary key</span></dt><dd class="glossdef"><p>
+ A special case of a
+ <a class="glossterm" href="glossary.html#GLOSSARY-UNIQUE-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-UNIQUE-CONSTRAINT" title="Unique constraint">unique constraint</a></em></a>
+ defined on a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> or other
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> that also
+ guarantees that all of the
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>
+ within the <a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-KEY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-KEY" title="Primary key">primary key</a></em></a>
+ do not have <a class="glossterm" href="glossary.html#GLOSSARY-NULL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-NULL" title="Null">null</a></em></a> values.
+ As the name implies, there can be only one
+ primary key per table, though it is possible to have multiple unique
+ constraints that also have no null-capable attributes.
+ </p></dd><dt id="GLOSSARY-PRIMARY-SERVER"><span class="glossterm">Primary (server)</span></dt><dd class="glossdef"><p>
+ When two or more <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">databases</a></em></a>
+ are linked via <a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION" title="Replication">replication</a></em></a>,
+ the <a class="glossterm" href="glossary.html#GLOSSARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SERVER" title="Server">server</a></em></a>
+ that is considered the authoritative source of information is called
+ the <em class="firstterm">primary</em>,
+ also known as a <em class="firstterm">master</em>.
+ </p></dd><dt id="GLOSSARY-PROCEDURE"><span class="glossterm">Procedure (routine)</span></dt><dd class="glossdef"><p>
+ A type of routine.
+ Their distinctive qualities are that they do not return values,
+ and that they are allowed to make transactional statements such
+ as <code class="command">COMMIT</code> and <code class="command">ROLLBACK</code>.
+ They are invoked via the <code class="command">CALL</code> command.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a>.
+ </p></dd><dt id="GLOSSARY-QUERY"><span class="glossterm">Query</span></dt><dd class="glossdef"><p>
+ A request sent by a client to a <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend</a></em></a>,
+ usually to return results or to modify data on the database.
+ </p></dd><dt id="GLOSSARY-PLANNER"><span class="glossterm">Query planner</span></dt><dd class="glossdef"><p>
+ The part of <span class="productname">PostgreSQL</span> that is devoted to
+ determining (<em class="firstterm">planning</em>) the most efficient way to
+ execute <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">queries</a></em></a>.
+ Also known as <em class="firstterm">query optimizer</em>,
+ <em class="firstterm">optimizer</em>, or simply <em class="firstterm">planner</em>.
+ </p></dd><dt><span class="glossterm">Record</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-TUPLE">Tuple</a>.</p></dd><dt><span class="glossterm">Recycling</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-WAL-FILE">WAL file</a>.</p></dd><dt id="GLOSSARY-REFERENTIAL-INTEGRITY"><span class="glossterm">Referential integrity</span></dt><dd class="glossdef"><p>
+ A means of restricting data in one <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>
+ by a <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-KEY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-KEY" title="Foreign key">foreign key</a></em></a>
+ so that it must have matching data in another
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>.
+ </p></dd><dt id="GLOSSARY-RELATION"><span class="glossterm">Relation</span></dt><dd class="glossdef"><p>
+ The generic term for all objects in a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>
+ that have a name and a list of
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>
+ defined in a specific order.
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">Tables</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-SEQUENCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SEQUENCE" title="Sequence (relation)">sequences</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VIEW" title="View">views</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-TABLE" title="Foreign table (relation)">foreign tables</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-MATERIALIZED-VIEW" title="Materialized view (relation)">materialized views</a></em></a>,
+ composite types, and
+ <a class="glossterm" href="glossary.html#GLOSSARY-INDEX"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INDEX" title="Index (relation)">indexes</a></em></a> are all relations.
+ </p><p>
+ More generically, a relation is a set of tuples; for example,
+ the result of a query is also a relation.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>,
+ <em class="firstterm">Class</em> is an archaic synonym for
+ <em class="firstterm">relation</em>.
+ </p></dd><dt id="GLOSSARY-REPLICA"><span class="glossterm">Replica (server)</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> that is paired
+ with a <a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER" title="Primary (server)">primary</a></em></a>
+ database and is maintaining a copy of some or all of the primary database's
+ data. The foremost reasons for doing this are to allow for greater access
+ to that data, and to maintain availability of the data in the event that
+ the <a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER" title="Primary (server)">primary</a></em></a>
+ becomes unavailable.
+ </p></dd><dt id="GLOSSARY-REPLICATION"><span class="glossterm">Replication</span></dt><dd class="glossdef"><p>
+ The act of reproducing data on one
+ <a class="glossterm" href="glossary.html#GLOSSARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SERVER" title="Server">server</a></em></a> onto another
+ server called a <a class="glossterm" href="glossary.html#GLOSSARY-REPLICA"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICA" title="Replica (server)">replica</a></em></a>.
+ This can take the form of <em class="firstterm">physical replication</em>,
+ where all file changes from one server are copied verbatim,
+ or <em class="firstterm">logical replication</em> where a defined subset
+ of data changes are conveyed using a higher-level representation.
+ </p></dd><dt id="GLOSSARY-RESULT-SET"><span class="glossterm">Result set</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> transmitted
+ from a <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend process</a></em></a>
+ to a <a class="glossterm" href="glossary.html#GLOSSARY-CLIENT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CLIENT" title="Client (process)">client</a></em></a> upon the
+ completion of an <acronym class="acronym">SQL</acronym> command, usually a
+ <code class="command">SELECT</code> but it can be an
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> command if the <code class="literal">RETURNING</code>
+ clause is specified.
+ </p><p>
+ The fact that a result set is a relation means that a query can be used
+ in the definition of another query, becoming a
+ <em class="firstterm">subquery</em>.
+ </p></dd><dd class="glossdef"><p>
+ </p></dd><dt id="GLOSSARY-REVOKE"><span class="glossterm">Revoke</span></dt><dd class="glossdef"><p>
+ A command to prevent access to a named set of
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> objects for a
+ named list of <a class="glossterm" href="glossary.html#GLOSSARY-ROLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ROLE" title="Role">roles</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>.
+ </p></dd><dt id="GLOSSARY-ROLE"><span class="glossterm">Role</span></dt><dd class="glossdef"><p>
+ A collection of access privileges to the
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">instance</a></em></a>.
+ Roles are themselves a privilege that can be granted to other roles.
+ This is often done for convenience or to ensure completeness
+ when multiple <a class="glossterm" href="glossary.html#GLOSSARY-USER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-USER" title="User">users</a></em></a> need
+ the same privileges.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>.
+ </p></dd><dt id="GLOSSARY-ROLLBACK"><span class="glossterm">Rollback</span></dt><dd class="glossdef"><p>
+ A command to undo all of the operations performed since the beginning
+ of a <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>.
+ </p></dd><dt id="GLOSSARY-ROUTINE"><span class="glossterm">Routine</span></dt><dd class="glossdef"><p>
+ A defined set of instructions stored in the database system
+ that can be invoked for execution.
+ A routine can be written in a variety of programming
+ languages. Routines can be
+ <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">functions</a></em></a>
+ (including set-returning functions and
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRIGGER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRIGGER" title="Trigger">trigger functions</a></em></a>),
+ <a class="glossterm" href="glossary.html#GLOSSARY-AGGREGATE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AGGREGATE" title="Aggregate function (routine)">aggregate functions</a></em></a>,
+ and <a class="glossterm" href="glossary.html#GLOSSARY-PROCEDURE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PROCEDURE" title="Procedure (routine)">procedures</a></em></a>.
+ </p><p>
+ Many routines are already defined within <span class="productname">PostgreSQL</span>
+ itself, but user-defined ones can also be added.
+ </p></dd><dt><span class="glossterm">Row</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-TUPLE">Tuple</a>.</p></dd><dt id="GLOSSARY-SAVEPOINT"><span class="glossterm">Savepoint</span></dt><dd class="glossdef"><p>
+ A special mark in the sequence of steps in a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a>.
+ Data modifications after this point in time may be reverted
+ to the time of the savepoint.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a>.
+ </p></dd><dt id="GLOSSARY-SCHEMA"><span class="glossterm">Schema</span></dt><dd class="glossdef"><p>
+ A schema is a namespace for
+ <a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT" title="SQL object">SQL objects</a></em></a>,
+ which all reside in the same
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>.
+ Each SQL object must reside in exactly one schema.
+ </p><p>
+ All system-defined SQL objects reside in schema <code class="literal">pg_catalog</code>.
+ </p></dd><dd class="glossdef"><p>
+ More generically, the term <em class="firstterm">schema</em> is used to mean
+ all data descriptions (<a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a> definitions,
+ <a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT" title="Constraint">constraints</a></em></a>, comments, etc.)
+ for a given <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> or
+ subset thereof.
+ </p><p>
+ For more information, see
+ <a class="xref" href="ddl-schemas.html" title="5.9. Schemas">Section 5.9</a>.
+ </p></dd><dt><span class="glossterm">Segment</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-FILE-SEGMENT">File segment</a>.</p></dd><dt id="GLOSSARY-SELECT"><span class="glossterm">Select</span></dt><dd class="glossdef"><p>
+ The <acronym class="acronym">SQL</acronym> command used to request data from a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>.
+ Normally, <code class="command">SELECT</code> commands are not expected to modify the
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> in any way,
+ but it is possible that
+ <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">functions</a></em></a> invoked within
+ the query could have side effects that do modify data.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>.
+ </p></dd><dt id="GLOSSARY-SEQUENCE"><span class="glossterm">Sequence (relation)</span></dt><dd class="glossdef"><p>
+ A type of relation that is used to generate values.
+ Typically the generated values are sequential non-repeating numbers.
+ They are commonly used to generate surrogate
+ <a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-KEY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-KEY" title="Primary key">primary key</a></em></a>
+ values.
+ </p></dd><dt id="GLOSSARY-SERVER"><span class="glossterm">Server</span></dt><dd class="glossdef"><p>
+ A computer on which <span class="productname">PostgreSQL</span>
+ <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instances</a></em></a> run.
+ The term <em class="firstterm">server</em> denotes real hardware, a
+ container, or a <em class="firstterm">virtual machine</em>.
+ </p><p>
+ This term is sometimes used to refer to an instance or to a host.
+ </p></dd><dt id="GLOSSARY-SESSION"><span class="glossterm">Session</span></dt><dd class="glossdef"><p>
+ A state that allows a client and a backend to interact,
+ communicating over a <a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONNECTION" title="Connection">connection</a></em></a>.
+ </p></dd><dt id="GLOSSARY-SHARED-MEMORY"><span class="glossterm">Shared memory</span></dt><dd class="glossdef"><p>
+ <acronym class="acronym">RAM</acronym> which is used by the processes common to an
+ <a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-INSTANCE" title="Instance">instance</a></em></a>.
+ It mirrors parts of <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a>
+ files, provides a transient area for
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD" title="WAL record">WAL records</a></em></a>,
+ and stores additional common information.
+ Note that shared memory belongs to the complete instance, not to a single
+ database.
+ </p><p>
+ The largest part of shared memory is known as <em class="firstterm">shared buffers</em>
+ and is used to mirror part of data files, organized into pages.
+ When a page is modified, it is called a dirty page until it is
+ written back to the file system.
+ </p><p>
+ For more information, see
+ <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY" title="20.4.1. Memory">Section 20.4.1</a>.
+ </p></dd><dt id="GLOSSARY-SQL-OBJECT"><span class="glossterm">SQL object</span></dt><dd class="glossdef"><p>
+ Any object that can be created with a <code class="command">CREATE</code>
+ command. Most objects are specific to one database, and are commonly
+ known as <em class="firstterm">local objects</em>.
+ </p><p>
+ Most local objects reside in a specific
+ <a class="glossterm" href="glossary.html#GLOSSARY-SCHEMA"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SCHEMA" title="Schema">schema</a></em></a> in their
+ containing database, such as
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relations</a></em></a> (all types),
+ <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">routines</a></em></a> (all types),
+ data types, etc.
+ The names of such objects of the same type in the same schema
+ are enforced to be unique.
+ </p><p>
+ There also exist local objects that do not reside in schemas; some examples are
+ <a class="glossterm" href="glossary.html#GLOSSARY-EXTENSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-EXTENSION" title="Extension">extensions</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-CAST"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CAST" title="Cast">data type casts</a></em></a>, and
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER" title="Foreign data wrapper">foreign data wrappers</a></em></a>.
+ The names of such objects of the same type are enforced to be unique
+ within the database.
+ </p><p>
+ Other object types, such as
+ <a class="glossterm" href="glossary.html#GLOSSARY-ROLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ROLE" title="Role">roles</a></em></a>,
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLESPACE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLESPACE" title="Tablespace">tablespaces</a></em></a>,
+ replication origins, subscriptions for logical replication, and
+ databases themselves are not local SQL objects since they exist
+ entirely outside of any specific database;
+ they are called <em class="firstterm">global objects</em>.
+ The names of such objects are enforced to be unique within the whole
+ database cluster.
+ </p><p>
+ For more information, see
+ <a class="xref" href="manage-ag-overview.html" title="23.1. Overview">Section 23.1</a>.
+ </p></dd><dt id="GLOSSARY-SQL-STANDARD"><span class="glossterm">SQL standard</span></dt><dd class="glossdef"><p>
+ A series of documents that define the <acronym class="acronym">SQL</acronym> language.
+ </p></dd><dt><span class="glossterm">Standby (server)</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-REPLICA">Replica (server)</a>.</p></dd><dt id="GLOSSARY-STARTUP-PROCESS"><span class="glossterm">Startup process</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ that replays WAL during crash recovery and in a
+ <a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICATION" title="Replication">physical replica</a></em></a>.
+ </p><p>
+ (The name is historical: the startup process was named before
+ replication was implemented; the name refers to its task as it
+ relates to the server startup following a crash.)
+ </p></dd><dt id="GLOSSARY-SYSTEM-CATALOG"><span class="glossterm">System catalog</span></dt><dd class="glossdef"><p>
+ A collection of <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">tables</a></em></a>
+ which describe the structure of all
+ <a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT" title="SQL object">SQL objects</a></em></a>
+ of the instance.
+ The system catalog resides in the schema <code class="literal">pg_catalog</code>.
+ These tables contain data in internal representation and are
+ not typically considered useful for user examination;
+ a number of user-friendlier <a class="glossterm" href="glossary.html#GLOSSARY-VIEW"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-VIEW" title="View">views</a></em></a>,
+ also in schema <code class="literal">pg_catalog</code>, offer more convenient access to
+ some of that information, while additional tables and views
+ exist in schema <code class="literal">information_schema</code>
+ (see <a class="xref" href="information-schema.html" title="Chapter 37. The Information Schema">Chapter 37</a>) that expose some
+ of the same and additional information as mandated by the
+ <a class="glossterm" href="glossary.html#GLOSSARY-SQL-STANDARD"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SQL-STANDARD" title="SQL standard">SQL standard</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="ddl-schemas.html" title="5.9. Schemas">Section 5.9</a>.
+ </p></dd><dt id="GLOSSARY-TABLE"><span class="glossterm">Table</span></dt><dd class="glossdef"><p>
+ A collection of <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">tuples</a></em></a> having
+ a common data structure (the same number of
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>, in the same
+ order, having the same name and type per position).
+ A table is the most common form of
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> in
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>.
+ </p></dd><dt id="GLOSSARY-TABLESPACE"><span class="glossterm">Tablespace</span></dt><dd class="glossdef"><p>
+ A named location on the server file system.
+ All <a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SQL-OBJECT" title="SQL object">SQL objects</a></em></a>
+ which require storage beyond their definition in the
+ <a class="glossterm" href="glossary.html#GLOSSARY-SYSTEM-CATALOG"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SYSTEM-CATALOG" title="System catalog">system catalog</a></em></a>
+ must belong to a single tablespace.
+ Initially, a database cluster contains a single usable tablespace which is
+ used as the default for all SQL objects, called <code class="literal">pg_default</code>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Section 23.6</a>.
+ </p></dd><dt id="GLOSSARY-TEMPORARY-TABLE"><span class="glossterm">Temporary table</span></dt><dd class="glossdef"><p>
+ <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">Tables</a></em></a> that exist either
+ for the lifetime of a
+ <a class="glossterm" href="glossary.html#GLOSSARY-SESSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SESSION" title="Session">session</a></em></a> or a
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a>, as
+ specified at the time of creation.
+ The data in them is not visible to other sessions, and is not
+ <a class="glossterm" href="glossary.html#GLOSSARY-LOGGED"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-LOGGED" title="Logged">logged</a></em></a>.
+ Temporary tables are often used to store intermediate data for a
+ multi-step operation.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>.
+ </p></dd><dt id="GLOSSARY-TOAST"><span class="glossterm">TOAST</span></dt><dd class="glossdef"><p>
+ A mechanism by which large attributes of table rows are split and
+ stored in a secondary table, called the <em class="firstterm">TOAST table</em>.
+ Each relation with large attributes has its own TOAST table.
+ </p><p>
+ For more information, see
+ <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>.
+ </p></dd><dt id="GLOSSARY-TRANSACTION"><span class="glossterm">Transaction</span></dt><dd class="glossdef"><p>
+ A combination of commands that must act as a single
+ <a class="glossterm" href="glossary.html#GLOSSARY-ATOMIC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATOMIC" title="Atomic">atomic</a></em></a> command: they all
+ succeed or all fail as a single unit, and their effects are not visible to
+ other <a class="glossterm" href="glossary.html#GLOSSARY-SESSION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SESSION" title="Session">sessions</a></em></a> until
+ the transaction is complete, and possibly even later, depending on the
+ isolation level.
+ </p><p>
+ For more information, see
+ <a class="xref" href="transaction-iso.html" title="13.2. Transaction Isolation">Section 13.2</a>.
+ </p></dd><dt id="GLOSSARY-XID"><span class="glossterm">Transaction ID</span></dt><dd class="glossdef"><p>
+ The numerical, unique, sequentially-assigned identifier that each
+ transaction receives when it first causes a database modification.
+ Frequently abbreviated as <em class="firstterm">xid</em>.
+ When stored on disk, xids are only 32-bits wide, so only
+ approximately four billion write transaction IDs can be generated;
+ to permit the system to run for longer than that,
+ <em class="firstterm">epochs</em> are used, also 32 bits wide.
+ When the counter reaches the maximum xid value, it starts over at
+ <code class="literal">3</code> (values under that are reserved) and the
+ epoch value is incremented by one.
+ In some contexts, the epoch and xid values are
+ considered together as a single 64-bit value.
+ </p><p>
+ For more information, see
+ <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>.
+ </p></dd><dt id="GLOSSARY-TPS"><span class="glossterm">Transactions per second (TPS)</span></dt><dd class="glossdef"><p>
+ Average number of transactions that are executed per second,
+ totaled across all sessions active for a measured run.
+ This is used as a measure of the performance characteristics of
+ an instance.
+ </p></dd><dt id="GLOSSARY-TRIGGER"><span class="glossterm">Trigger</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">function</a></em></a> which can
+ be defined to execute whenever a certain operation (<code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">TRUNCATE</code>) is applied to a
+ <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>.
+ A trigger executes within the same
+ <a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TRANSACTION" title="Transaction">transaction</a></em></a> as the
+ statement which invoked it, and if the function fails, then the invoking
+ statement also fails.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>.
+ </p></dd><dt id="GLOSSARY-TUPLE"><span class="glossterm">Tuple</span></dt><dd class="glossdef"><p>
+ A collection of <a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ATTRIBUTE" title="Attribute">attributes</a></em></a>
+ in a fixed order.
+ That order may be defined by the <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>
+ (or other <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>)
+ where the tuple is contained, in which case the tuple is often called a
+ <em class="firstterm">row</em>. It may also be defined by the structure of a
+ result set, in which case it is sometimes called a <em class="firstterm">record</em>.
+ </p></dd><dt id="GLOSSARY-UNIQUE-CONSTRAINT"><span class="glossterm">Unique constraint</span></dt><dd class="glossdef"><p>
+ A type of <a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CONSTRAINT" title="Constraint">constraint</a></em></a>
+ defined on a <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a>
+ which restricts the values allowed in one or a combination of columns
+ so that each value or combination of values can only appear once in the
+ relation — that is, no other row in the relation contains values
+ that are equal to those.
+ </p><p>
+ Because <a class="glossterm" href="glossary.html#GLOSSARY-NULL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-NULL" title="Null">null values</a></em></a> are
+ not considered equal to each other, multiple rows with null values are
+ allowed to exist without violating the unique constraint.
+ </p></dd><dt id="GLOSSARY-UNLOGGED"><span class="glossterm">Unlogged</span></dt><dd class="glossdef"><p>
+ The property of certain <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relations</a></em></a>
+ that the changes to them are not reflected in the
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL" title="Write-ahead log">WAL</a></em></a>.
+ This disables replication and crash recovery for these relations.
+ </p><p>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </p><p>
+ <a class="glossterm" href="glossary.html#GLOSSARY-TEMPORARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TEMPORARY-TABLE" title="Temporary table">Temporary tables</a></em></a>
+ are always unlogged.
+ </p></dd><dt id="GLOSSARY-UPDATE"><span class="glossterm">Update</span></dt><dd class="glossdef"><p>
+ An <acronym class="acronym">SQL</acronym> command used to modify
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">rows</a></em></a>
+ that may already exist in a specified <a class="glossterm" href="glossary.html#GLOSSARY-TABLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TABLE" title="Table">table</a></em></a>.
+ It cannot create or remove rows.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a>.
+ </p></dd><dt id="GLOSSARY-USER"><span class="glossterm">User</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-ROLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-ROLE" title="Role">role</a></em></a> that has the
+ <code class="literal">LOGIN</code> privilege.
+ </p></dd><dt id="GLOSSARY-USER-MAPPING"><span class="glossterm">User mapping</span></dt><dd class="glossdef"><p>
+ The translation of login credentials in the local
+ <a class="glossterm" href="glossary.html#GLOSSARY-DATABASE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DATABASE" title="Database">database</a></em></a> to credentials
+ in a remote data system defined by a
+ <a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FOREIGN-DATA-WRAPPER" title="Foreign data wrapper">foreign data wrapper</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>.
+ </p></dd><dt id="GLOSSARY-VACUUM"><span class="glossterm">Vacuum</span></dt><dd class="glossdef"><p>
+ The process of removing outdated
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">tuple versions</a></em></a>
+ from tables or materialized views, and other closely related
+ processing required by <span class="productname">PostgreSQL</span>'s
+ implementation of <a class="glossterm" href="glossary.html#GLOSSARY-MVCC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-MVCC" title="Multi-version concurrency control (MVCC)">MVCC</a></em></a>.
+ This can be initiated through the use of
+ the <code class="command">VACUUM</code> command, but can also be handled automatically
+ via <a class="glossterm" href="glossary.html#GLOSSARY-AUTOVACUUM"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUTOVACUUM" title="Autovacuum (process)">autovacuum</a></em></a> processes.
+ </p><p>
+ For more information, see
+ <a class="xref" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Section 25.1</a> .
+ </p></dd><dt id="GLOSSARY-VIEW"><span class="glossterm">View</span></dt><dd class="glossdef"><p>
+ A <a class="glossterm" href="glossary.html#GLOSSARY-RELATION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RELATION" title="Relation">relation</a></em></a> that is defined by a
+ <code class="command">SELECT</code> statement, but has no storage of its own.
+ Any time a query references a view, the definition of the view is
+ substituted into the query as if the user had typed it as a subquery
+ instead of the name of the view.
+ </p><p>
+ For more information, see
+ <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a>.
+ </p></dd><dt id="GLOSSARY-VM"><span class="glossterm">Visibility map (fork)</span></dt><dd class="glossdef"><p>
+ A storage structure that keeps metadata about each data page
+ of a table's main fork. The visibility map entry for
+ each page stores two bits: the first one
+ (<code class="literal">all-visible</code>) indicates that all tuples
+ in the page are visible to all transactions. The second one
+ (<code class="literal">all-frozen</code>) indicates that all tuples
+ in the page are marked frozen.
+ </p></dd><dt><span class="glossterm">WAL</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-WAL">Write-ahead log</a>.</p></dd><dt id="GLOSSARY-WAL-ARCHIVER"><span class="glossterm">WAL archiver (process)</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ which, if enabled, saves copies of
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE" title="WAL file">WAL files</a></em></a>
+ for the purpose of creating backups or keeping
+ <a class="glossterm" href="glossary.html#GLOSSARY-REPLICA"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICA" title="Replica (server)">replicas</a></em></a> current.
+ </p><p>
+ For more information, see
+ <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>.
+ </p></dd><dt id="GLOSSARY-WAL-FILE"><span class="glossterm">WAL file</span></dt><dd class="glossdef"><p>
+ Also known as <em class="firstterm">WAL segment</em> or
+ <em class="firstterm">WAL segment file</em>.
+ Each of the sequentially-numbered files that provide storage space for
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL" title="Write-ahead log">WAL</a></em></a>.
+ The files are all of the same predefined size
+ and are written in sequential order, interspersing changes
+ as they occur in multiple simultaneous sessions.
+ If the system crashes, the files are read in order, and each of the
+ changes is replayed to restore the system to the state it was in
+ before the crash.
+ </p><p>
+ Each WAL file can be released after a
+ <a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINT"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-CHECKPOINT" title="Checkpoint">checkpoint</a></em></a>
+ writes all the changes in it to the corresponding data files.
+ Releasing the file can be done either by deleting it, or by changing its
+ name so that it will be used in the future, which is called
+ <em class="firstterm">recycling</em>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="wal-internals.html" title="30.6. WAL Internals">Section 30.6</a>.
+ </p></dd><dt id="GLOSSARY-WAL-RECORD"><span class="glossterm">WAL record</span></dt><dd class="glossdef"><p>
+ A low-level description of an individual data change.
+ It contains sufficient information for the data change to be
+ re-executed (<em class="firstterm">replayed</em>) in case a system failure
+ causes the change to be lost.
+ WAL records use a non-printable binary format.
+ </p><p>
+ For more information, see
+ <a class="xref" href="wal-internals.html" title="30.6. WAL Internals">Section 30.6</a>.
+ </p></dd><dt id="GLOSSARY-WAL-RECEIVER"><span class="glossterm">WAL receiver (process)</span></dt><dd class="glossdef"><p>
+ An <a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AUXILIARY-PROC" title="Auxiliary process">auxiliary process</a></em></a>
+ that runs on a <a class="glossterm" href="glossary.html#GLOSSARY-REPLICA"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICA" title="Replica (server)">replica</a></em></a>
+ to receive WAL from the
+ <a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PRIMARY-SERVER" title="Primary (server)">primary server</a></em></a>
+ for replay by the
+ <a class="glossterm" href="glossary.html#GLOSSARY-STARTUP-PROCESS"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-STARTUP-PROCESS" title="Startup process">startup process</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>.
+ </p></dd><dt><span class="glossterm">WAL segment</span></dt><dd><p>See <a class="glosssee" href="glossary.html#GLOSSARY-WAL-FILE">WAL file</a>.</p></dd><dt id="GLOSSARY-WAL-SENDER"><span class="glossterm">WAL sender (process)</span></dt><dd class="glossdef"><p>
+ A special <a class="glossterm" href="glossary.html#GLOSSARY-BACKEND"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-BACKEND" title="Backend (process)">backend process</a></em></a>
+ that streams WAL over a network. The receiving end can be a
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECEIVER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECEIVER" title="WAL receiver (process)">WAL receiver</a></em></a>
+ in a <a class="glossterm" href="glossary.html#GLOSSARY-REPLICA"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-REPLICA" title="Replica (server)">replica</a></em></a>,
+ <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a>, or any other client program
+ that speaks the replication protocol.
+ </p></dd><dt id="GLOSSARY-WAL-WRITER"><span class="glossterm">WAL writer (process)</span></dt><dd class="glossdef"><p>
+ A process that writes <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD" title="WAL record">WAL records</a></em></a>
+ from <a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-SHARED-MEMORY" title="Shared memory">shared memory</a></em></a> to
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE" title="WAL file">WAL files</a></em></a>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="runtime-config-wal.html" title="20.5. Write Ahead Log">Section 20.5</a>.
+ </p></dd><dt id="GLOSSARY-WINDOW-FUNCTION"><span class="glossterm">Window function (routine)</span></dt><dd class="glossdef"><p>
+ A type of <a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-FUNCTION" title="Function (routine)">function</a></em></a>
+ used in a <a class="glossterm" href="glossary.html#GLOSSARY-QUERY"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-QUERY" title="Query">query</a></em></a>
+ that applies to a <a class="glossterm" href="glossary.html#GLOSSARY-PARTITION"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-PARTITION" title="Partition">partition</a></em></a>
+ of the query's <a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-RESULT-SET" title="Result set">result set</a></em></a>;
+ the function's result is based on values found in
+ <a class="glossterm" href="glossary.html#GLOSSARY-TUPLE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-TUPLE" title="Tuple">rows</a></em></a> of the same partition or frame.
+ </p><p>
+ All <a class="glossterm" href="glossary.html#GLOSSARY-AGGREGATE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-AGGREGATE" title="Aggregate function (routine)">aggregate functions</a></em></a>
+ can be used as window functions, but window functions can also be
+ used to, for example, give ranks to each of the rows in the partition.
+ Also known as <em class="firstterm">analytic functions</em>.
+ </p><p>
+ For more information, see
+ <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a>.
+ </p></dd><dt id="GLOSSARY-WAL"><span class="glossterm">Write-ahead log</span></dt><dd class="glossdef"><p>
+ The journal that keeps track of the changes in the
+ <a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DB-CLUSTER" title="Database cluster">database cluster</a></em></a>
+ as user- and system-invoked operations take place.
+ It comprises many individual
+ <a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-RECORD" title="WAL record">WAL records</a></em></a> written
+ sequentially to <a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-WAL-FILE" title="WAL file">WAL files</a></em></a>.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acronyms.html" title="Appendix L. Acronyms">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="color.html" title="Appendix N. Color Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix L. Acronyms </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix N. Color Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gssapi-auth.html b/doc/src/sgml/html/gssapi-auth.html
new file mode 100644
index 0000000..ff292bc
--- /dev/null
+++ b/doc/src/sgml/html/gssapi-auth.html
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.6. GSSAPI Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="auth-password.html" title="21.5. Password Authentication" /><link rel="next" href="sspi-auth.html" title="21.7. SSPI Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.6. GSSAPI Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="auth-password.html" title="21.5. Password Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sspi-auth.html" title="21.7. SSPI Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="GSSAPI-AUTH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.6. GSSAPI Authentication</h2></div></div></div><a id="id-1.6.8.13.2" class="indexterm"></a><p>
+ <span class="productname">GSSAPI</span> is an industry-standard protocol
+ for secure authentication defined in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc2743" target="_top">RFC 2743</a>.
+ <span class="productname">PostgreSQL</span>
+ supports <span class="productname">GSSAPI</span> for authentication,
+ communications encryption, or both.
+ <span class="productname">GSSAPI</span> provides automatic authentication
+ (single sign-on) for systems that support it. The authentication itself is
+ secure. If <span class="productname">GSSAPI</span> encryption
+ or <acronym class="acronym">SSL</acronym> encryption is
+ used, the data sent along the database connection will be encrypted;
+ otherwise, it will not.
+ </p><p>
+ GSSAPI support has to be enabled when <span class="productname">PostgreSQL</span> is built;
+ see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a> for more information.
+ </p><p>
+ When <span class="productname">GSSAPI</span> uses
+ <span class="productname">Kerberos</span>, it uses a standard service
+ principal (authentication identity) name in the format
+ <code class="literal"><em class="replaceable"><code>servicename</code></em>/<em class="replaceable"><code>hostname</code></em>@<em class="replaceable"><code>realm</code></em></code>.
+ The principal name used by a particular installation is not encoded in
+ the <span class="productname">PostgreSQL</span> server in any way; rather it
+ is specified in the <em class="firstterm">keytab</em> file that the server
+ reads to determine its identity. If multiple principals are listed in
+ the keytab file, the server will accept any one of them.
+ The server's realm name is the preferred realm specified in the Kerberos
+ configuration file(s) accessible to the server.
+ </p><p>
+ When connecting, the client must know the principal name of the server
+ it intends to connect to. The <em class="replaceable"><code>servicename</code></em>
+ part of the principal is ordinarily <code class="literal">postgres</code>,
+ but another value can be selected via <span class="application">libpq</span>'s
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-KRBSRVNAME">krbsrvname</a> connection parameter.
+ The <em class="replaceable"><code>hostname</code></em> part is the fully qualified
+ host name that <span class="application">libpq</span> is told to connect to.
+ The realm name is the preferred realm specified in the Kerberos
+ configuration file(s) accessible to the client.
+ </p><p>
+ The client will also have a principal name for its own identity
+ (and it must have a valid ticket for this principal). To
+ use <span class="productname">GSSAPI</span> for authentication, the client
+ principal must be associated with
+ a <span class="productname">PostgreSQL</span> database user name.
+ The <code class="filename">pg_ident.conf</code> configuration file can be used
+ to map principals to user names; for example,
+ <code class="literal">pgusername@realm</code> could be mapped to just <code class="literal">pgusername</code>.
+ Alternatively, you can use the full <code class="literal">username@realm</code> principal as
+ the role name in <span class="productname">PostgreSQL</span> without any mapping.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also supports mapping
+ client principals to user names by just stripping the realm from
+ the principal. This method is supported for backwards compatibility and is
+ strongly discouraged as it is then impossible to distinguish different users
+ with the same user name but coming from different realms. To enable this,
+ set <code class="literal">include_realm</code> to 0. For simple single-realm
+ installations, doing that combined with setting the
+ <code class="literal">krb_realm</code> parameter (which checks that the principal's realm
+ matches exactly what is in the <code class="literal">krb_realm</code> parameter)
+ is still secure; but this is a
+ less capable approach compared to specifying an explicit mapping in
+ <code class="filename">pg_ident.conf</code>.
+ </p><p>
+ The location of the server's keytab file is specified by the <a class="xref" href="runtime-config-connection.html#GUC-KRB-SERVER-KEYFILE">krb_server_keyfile</a> configuration parameter.
+ For security reasons, it is recommended to use a separate keytab
+ just for the <span class="productname">PostgreSQL</span> server rather
+ than allowing the server to read the system keytab file.
+ Make sure that your server keytab file is readable (and preferably
+ only readable, not writable) by the <span class="productname">PostgreSQL</span>
+ server account. (See also <a class="xref" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Section 19.1</a>.)
+ </p><p>
+ The keytab file is generated using the Kerberos software; see the
+ Kerberos documentation for details. The following example shows
+ doing this using the <span class="application">kadmin</span> tool of
+ MIT-compatible Kerberos 5 implementations:
+</p><pre class="screen">
+<code class="prompt">kadmin% </code><strong class="userinput"><code>addprinc -randkey postgres/server.my.domain.org</code></strong>
+<code class="prompt">kadmin% </code><strong class="userinput"><code>ktadd -k krb5.keytab postgres/server.my.domain.org</code></strong>
+</pre><p>
+ </p><p>
+ The following authentication options are supported for
+ the <span class="productname">GSSAPI</span> authentication method:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">include_realm</code></span></dt><dd><p>
+ If set to 0, the realm name from the authenticated user principal is
+ stripped off before being passed through the user name mapping
+ (<a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a>). This is discouraged and is
+ primarily available for backwards compatibility, as it is not secure
+ in multi-realm environments unless <code class="literal">krb_realm</code> is
+ also used. It is recommended to
+ leave <code class="literal">include_realm</code> set to the default (1) and to
+ provide an explicit mapping in <code class="filename">pg_ident.conf</code> to convert
+ principal names to <span class="productname">PostgreSQL</span> user names.
+ </p></dd><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
+ Allows mapping from client principals to database user names. See
+ <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details. For a GSSAPI/Kerberos
+ principal, such as <code class="literal">username@EXAMPLE.COM</code> (or, less
+ commonly, <code class="literal">username/hostbased@EXAMPLE.COM</code>), the
+ user name used for mapping is
+ <code class="literal">username@EXAMPLE.COM</code> (or
+ <code class="literal">username/hostbased@EXAMPLE.COM</code>, respectively),
+ unless <code class="literal">include_realm</code> has been set to 0, in which case
+ <code class="literal">username</code> (or <code class="literal">username/hostbased</code>)
+ is what is seen as the system user name when mapping.
+ </p></dd><dt><span class="term"><code class="literal">krb_realm</code></span></dt><dd><p>
+ Sets the realm to match user principal names against. If this parameter
+ is set, only users of that realm will be accepted. If it is not set,
+ users of any realm can connect, subject to whatever user name mapping
+ is done.
+ </p></dd></dl></div><p>
+ </p><p>
+ In addition to these settings, which can be different for
+ different <code class="filename">pg_hba.conf</code> entries, there is the
+ server-wide <a class="xref" href="runtime-config-connection.html#GUC-KRB-CASEINS-USERS">krb_caseins_users</a> configuration
+ parameter. If that is set to true, client principals are matched to
+ user map entries case-insensitively. <code class="literal">krb_realm</code>, if
+ set, is also matched case-insensitively.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auth-password.html" title="21.5. Password Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sspi-auth.html" title="21.7. SSPI Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.5. Password Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.7. SSPI Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/gssapi-enc.html b/doc/src/sgml/html/gssapi-enc.html
new file mode 100644
index 0000000..026d1e7
--- /dev/null
+++ b/doc/src/sgml/html/gssapi-enc.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.10. Secure TCP/IP Connections with GSSAPI Encryption</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL" /><link rel="next" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.10. Secure TCP/IP Connections with GSSAPI Encryption</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels">Next</a></td></tr></table><hr /></div><div class="sect1" id="GSSAPI-ENC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.10. Secure TCP/IP Connections with GSSAPI Encryption</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="gssapi-enc.html#GSSAPI-SETUP">19.10.1. Basic Setup</a></span></dt></dl></div><a id="id-1.6.6.13.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> also has native support for
+ using <acronym class="acronym">GSSAPI</acronym> to encrypt client/server communications for
+ increased security. Support requires that a <acronym class="acronym">GSSAPI</acronym>
+ implementation (such as MIT Kerberos) is installed on both client and server
+ systems, and that support in <span class="productname">PostgreSQL</span> is
+ enabled at build time (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>).
+ </p><div class="sect2" id="GSSAPI-SETUP"><div class="titlepage"><div><div><h3 class="title">19.10.1. Basic Setup</h3></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> server will listen for both
+ normal and <acronym class="acronym">GSSAPI</acronym>-encrypted connections on the same TCP
+ port, and will negotiate with any connecting client whether to
+ use <acronym class="acronym">GSSAPI</acronym> for encryption (and for authentication). By
+ default, this decision is up to the client (which means it can be
+ downgraded by an attacker); see <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a> about
+ setting up the server to require the use of <acronym class="acronym">GSSAPI</acronym> for
+ some or all connections.
+ </p><p>
+ When using <acronym class="acronym">GSSAPI</acronym> for encryption, it is common to
+ use <acronym class="acronym">GSSAPI</acronym> for authentication as well, since the
+ underlying mechanism will determine both client and server identities
+ (according to the <acronym class="acronym">GSSAPI</acronym> implementation) in any
+ case. But this is not required;
+ another <span class="productname">PostgreSQL</span> authentication method
+ can be chosen to perform additional verification.
+ </p><p>
+ Other than configuration of the negotiation
+ behavior, <acronym class="acronym">GSSAPI</acronym> encryption requires no setup beyond
+ that which is necessary for GSSAPI authentication. (For more information
+ on configuring that, see <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>.)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ssh-tunnels.html" title="19.11. Secure TCP/IP Connections with SSH Tunnels">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.9. Secure TCP/IP Connections with SSL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/hash-implementation.html b/doc/src/sgml/html/hash-implementation.html
new file mode 100644
index 0000000..ea547a2
--- /dev/null
+++ b/doc/src/sgml/html/hash-implementation.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>72.2. Implementation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="hash-intro.html" title="72.1. Overview" /><link rel="next" href="storage.html" title="Chapter 73. Database Physical Storage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">72.2. Implementation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="hash-intro.html" title="72.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="hash-index.html" title="Chapter 72. Hash Indexes">Up</a></td><th width="60%" align="center">Chapter 72. Hash Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage.html" title="Chapter 73. Database Physical Storage">Next</a></td></tr></table><hr /></div><div class="sect1" id="HASH-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">72.2. Implementation</h2></div></div></div><p>
+ There are four kinds of pages in a hash index: the meta page (page zero),
+ which contains statically allocated control information; primary bucket
+ pages; overflow pages; and bitmap pages, which keep track of overflow
+ pages that have been freed and are available for re-use. For addressing
+ purposes, bitmap pages are regarded as a subset of the overflow pages.
+ </p><p>
+ Both scanning the index and inserting tuples require locating the bucket
+ where a given tuple ought to be located. To do this, we need the bucket
+ count, highmask, and lowmask from the metapage; however, it's undesirable
+ for performance reasons to have to have to lock and pin the metapage for
+ every such operation. Instead, we retain a cached copy of the metapage
+ in each backend's relcache entry. This will produce the correct bucket
+ mapping as long as the target bucket hasn't been split since the last
+ cache refresh.
+ </p><p>
+ Primary bucket pages and overflow pages are allocated independently since
+ any given index might need more or fewer overflow pages relative to its
+ number of buckets. The hash code uses an interesting set of addressing
+ rules to support a variable number of overflow pages while not having to
+ move primary bucket pages around after they are created.
+ </p><p>
+ Each row in the table indexed is represented by a single index tuple in
+ the hash index. Hash index tuples are stored in bucket pages, and if
+ they exist, overflow pages. We speed up searches by keeping the index entries
+ in any one index page sorted by hash code, thus allowing binary search to be
+ used within an index page. Note however that there is *no* assumption about
+ the relative ordering of hash codes across different index pages of a bucket.
+ </p><p>
+ The bucket splitting algorithms to expand the hash index are too complex to
+ be worthy of mention here, though are described in more detail in
+ <code class="filename">src/backend/access/hash/README</code>.
+ The split algorithm is crash safe and can be restarted if not completed
+ successfully.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="hash-intro.html" title="72.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="hash-index.html" title="Chapter 72. Hash Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage.html" title="Chapter 73. Database Physical Storage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">72.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 73. Database Physical Storage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/hash-index.html b/doc/src/sgml/html/hash-index.html
new file mode 100644
index 0000000..23bea86
--- /dev/null
+++ b/doc/src/sgml/html/hash-index.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 72. Hash Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="brin-extensibility.html" title="71.3. Extensibility" /><link rel="next" href="hash-intro.html" title="72.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 72. Hash Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="brin-extensibility.html" title="71.3. Extensibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="hash-intro.html" title="72.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="HASH-INDEX"><div class="titlepage"><div><div><h2 class="title">Chapter 72. Hash Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="hash-intro.html">72.1. Overview</a></span></dt><dt><span class="sect1"><a href="hash-implementation.html">72.2. Implementation</a></span></dt></dl></div><a id="id-1.10.23.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="brin-extensibility.html" title="71.3. Extensibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hash-intro.html" title="72.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">71.3. Extensibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 72.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/hash-intro.html b/doc/src/sgml/html/hash-intro.html
new file mode 100644
index 0000000..ce9232b
--- /dev/null
+++ b/doc/src/sgml/html/hash-intro.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>72.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="hash-index.html" title="Chapter 72. Hash Indexes" /><link rel="next" href="hash-implementation.html" title="72.2. Implementation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">72.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="hash-index.html" title="Chapter 72. Hash Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="hash-index.html" title="Chapter 72. Hash Indexes">Up</a></td><th width="60%" align="center">Chapter 72. Hash Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="hash-implementation.html" title="72.2. Implementation">Next</a></td></tr></table><hr /></div><div class="sect1" id="HASH-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">72.1. Overview</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span>
+ includes an implementation of persistent on-disk hash indexes,
+ which are fully crash recoverable. Any data type can be indexed by a
+ hash index, including data types that do not have a well-defined linear
+ ordering. Hash indexes store only the hash value of the data being
+ indexed, thus there are no restrictions on the size of the data column
+ being indexed.
+ </p><p>
+ Hash indexes support only single-column indexes and do not allow
+ uniqueness checking.
+ </p><p>
+ Hash indexes support only the <code class="literal">=</code> operator,
+ so WHERE clauses that specify range operations will not be able to take
+ advantage of hash indexes.
+ </p><p>
+ Each hash index tuple stores just the 4-byte hash value, not the actual
+ column value. As a result, hash indexes may be much smaller than B-trees
+ when indexing longer data items such as UUIDs, URLs, etc. The absence of
+ the column value also makes all hash index scans lossy. Hash indexes may
+ take part in bitmap index scans and backward scans.
+ </p><p>
+ Hash indexes are best optimized for SELECT and UPDATE-heavy workloads
+ that use equality scans on larger tables. In a B-tree index, searches must
+ descend through the tree until the leaf page is found. In tables with
+ millions of rows, this descent can increase access time to data. The
+ equivalent of a leaf page in a hash index is referred to as a bucket page. In
+ contrast, a hash index allows accessing the bucket pages directly,
+ thereby potentially reducing index access time in larger tables. This
+ reduction in "logical I/O" becomes even more pronounced on indexes/data
+ larger than shared_buffers/RAM.
+ </p><p>
+ Hash indexes have been designed to cope with uneven distributions of
+ hash values. Direct access to the bucket pages works well if the hash
+ values are evenly distributed. When inserts mean that the bucket page
+ becomes full, additional overflow pages are chained to that specific
+ bucket page, locally expanding the storage for index tuples that match
+ that hash value. When scanning a hash bucket during queries, we need to
+ scan through all of the overflow pages. Thus an unbalanced hash index
+ might actually be worse than a B-tree in terms of number of block
+ accesses required, for some data.
+ </p><p>
+ As a result of the overflow cases, we can say that hash indexes are
+ most suitable for unique, nearly unique data or data with a low number
+ of rows per hash bucket.
+ One possible way to avoid problems is to exclude highly non-unique
+ values from the index using a partial index condition, but this may
+ not be suitable in many cases.
+ </p><p>
+ Like B-Trees, hash indexes perform simple index tuple deletion. This
+ is a deferred maintenance operation that deletes index tuples that are
+ known to be safe to delete (those whose item identifier's LP_DEAD bit
+ is already set). If an insert finds no space is available on a page we
+ try to avoid creating a new overflow page by attempting to remove dead
+ index tuples. Removal cannot occur if the page is pinned at that time.
+ Deletion of dead index pointers also occurs during VACUUM.
+ </p><p>
+ If it can, VACUUM will also try to squeeze the index tuples onto as
+ few overflow pages as possible, minimizing the overflow chain. If an
+ overflow page becomes empty, overflow pages can be recycled for reuse
+ in other buckets, though we never return them to the operating system.
+ There is currently no provision to shrink a hash index, other than by
+ rebuilding it with REINDEX.
+ There is no provision for reducing the number of buckets, either.
+ </p><p>
+ Hash indexes may expand the number of bucket pages as the number of
+ rows indexed grows. The hash key-to-bucket-number mapping is chosen so that
+ the index can be incrementally expanded. When a new bucket is to be added to
+ the index, exactly one existing bucket will need to be "split", with some of
+ its tuples being transferred to the new bucket according to the updated
+ key-to-bucket-number mapping.
+ </p><p>
+ The expansion occurs in the foreground, which could increase execution
+ time for user inserts. Thus, hash indexes may not be suitable for tables
+ with rapidly increasing number of rows.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="hash-index.html" title="Chapter 72. Hash Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="hash-index.html" title="Chapter 72. Hash Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hash-implementation.html" title="72.2. Implementation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 72. Hash Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 72.2. Implementation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/high-availability.html b/doc/src/sgml/html/high-availability.html
new file mode 100644
index 0000000..608f0ac
--- /dev/null
+++ b/doc/src/sgml/html/high-availability.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 27. High Availability, Load Balancing, and Replication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)" /><link rel="next" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 27. High Availability, Load Balancing, and Replication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions">Next</a></td></tr></table><hr /></div><div class="chapter" id="HIGH-AVAILABILITY"><div class="titlepage"><div><div><h2 class="title">Chapter 27. High Availability, Load Balancing, and Replication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="different-replication-solutions.html">27.1. Comparison of Different Solutions</a></span></dt><dt><span class="sect1"><a href="warm-standby.html">27.2. Log-Shipping Standby Servers</a></span></dt><dd><dl><dt><span class="sect2"><a href="warm-standby.html#STANDBY-PLANNING">27.2.1. Planning</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STANDBY-SERVER-OPERATION">27.2.2. Standby Server Operation</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#PREPARING-PRIMARY-FOR-STANDBY">27.2.3. Preparing the Primary for Standby Servers</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STANDBY-SERVER-SETUP">27.2.4. Setting Up a Standby Server</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STREAMING-REPLICATION">27.2.5. Streaming Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STREAMING-REPLICATION-SLOTS">27.2.6. Replication Slots</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#CASCADING-REPLICATION">27.2.7. Cascading Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#SYNCHRONOUS-REPLICATION">27.2.8. Synchronous Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#CONTINUOUS-ARCHIVING-IN-STANDBY">27.2.9. Continuous Archiving in Standby</a></span></dt></dl></dd><dt><span class="sect1"><a href="warm-standby-failover.html">27.3. Failover</a></span></dt><dt><span class="sect1"><a href="hot-standby.html">27.4. Hot Standby</a></span></dt><dd><dl><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-USERS">27.4.1. User's Overview</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-CONFLICT">27.4.2. Handling Query Conflicts</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-ADMIN">27.4.3. Administrator's Overview</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-PARAMETERS">27.4.4. Hot Standby Parameter Reference</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-CAVEATS">27.4.5. Caveats</a></span></dt></dl></dd></dl></div><a id="id-1.6.14.2" class="indexterm"></a><a id="id-1.6.14.3" class="indexterm"></a><a id="id-1.6.14.4" class="indexterm"></a><a id="id-1.6.14.5" class="indexterm"></a><a id="id-1.6.14.6" class="indexterm"></a><a id="id-1.6.14.7" class="indexterm"></a><p>
+ Database servers can work together to allow a second server to
+ take over quickly if the primary server fails (high
+ availability), or to allow several computers to serve the same
+ data (load balancing). Ideally, database servers could work
+ together seamlessly. Web servers serving static web pages can
+ be combined quite easily by merely load-balancing web requests
+ to multiple machines. In fact, read-only database servers can
+ be combined relatively easily too. Unfortunately, most database
+ servers have a read/write mix of requests, and read/write servers
+ are much harder to combine. This is because though read-only
+ data needs to be placed on each server only once, a write to any
+ server has to be propagated to all servers so that future read
+ requests to those servers return consistent results.
+ </p><p>
+ This synchronization problem is the fundamental difficulty for
+ servers working together. Because there is no single solution
+ that eliminates the impact of the sync problem for all use cases,
+ there are multiple solutions. Each solution addresses this
+ problem in a different way, and minimizes its impact for a specific
+ workload.
+ </p><p>
+ Some solutions deal with synchronization by allowing only one
+ server to modify the data. Servers that can modify data are
+ called read/write, <em class="firstterm">master</em> or <em class="firstterm">primary</em> servers.
+ Servers that track changes in the primary are called <em class="firstterm">standby</em>
+ or <em class="firstterm">secondary</em> servers. A standby server that cannot be connected
+ to until it is promoted to a primary server is called a <em class="firstterm">warm
+ standby</em> server, and one that can accept connections and serves read-only
+ queries is called a <em class="firstterm">hot standby</em> server.
+ </p><p>
+ Some solutions are synchronous,
+ meaning that a data-modifying transaction is not considered
+ committed until all servers have committed the transaction. This
+ guarantees that a failover will not lose any data and that all
+ load-balanced servers will return consistent results no matter
+ which server is queried. In contrast, asynchronous solutions allow some
+ delay between the time of a commit and its propagation to the other servers,
+ opening the possibility that some transactions might be lost in
+ the switch to a backup server, and that load balanced servers
+ might return slightly stale results. Asynchronous communication
+ is used when synchronous would be too slow.
+ </p><p>
+ Solutions can also be categorized by their granularity. Some solutions
+ can deal only with an entire database server, while others allow control
+ at the per-table or per-database level.
+ </p><p>
+ Performance must be considered in any choice. There is usually a
+ trade-off between functionality and
+ performance. For example, a fully synchronous solution over a slow
+ network might cut performance by more than half, while an asynchronous
+ one might have a minimal performance impact.
+ </p><p>
+ The remainder of this section outlines various failover, replication,
+ and load balancing solutions.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">26.3. Continuous Archiving and Point-in-Time Recovery (PITR) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 27.1. Comparison of Different Solutions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/history.html b/doc/src/sgml/html/history.html
new file mode 100644
index 0000000..737e231
--- /dev/null
+++ b/doc/src/sgml/html/history.html
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2. A Brief History of PostgreSQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="intro-whatis.html" title="1.  What Is PostgreSQL?" /><link rel="next" href="notation.html" title="3. Conventions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2. A Brief History of <span class="productname">PostgreSQL</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="intro-whatis.html" title="1.  What Is PostgreSQL?">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="notation.html" title="3. Conventions">Next</a></td></tr></table><hr /></div><div class="sect1" id="HISTORY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2. A Brief History of <span class="productname">PostgreSQL</span></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="history.html#HISTORY-BERKELEY">2.1. The Berkeley <span class="productname">POSTGRES</span> Project</a></span></dt><dt><span class="sect2"><a href="history.html#HISTORY-POSTGRES95">2.2. <span class="productname">Postgres95</span></a></span></dt><dt><span class="sect2"><a href="history.html#id-1.3.5.6">2.3. <span class="productname">PostgreSQL</span></a></span></dt></dl></div><a id="id-1.3.5.2" class="indexterm"></a><p>
+ The object-relational database management system now known as
+ <span class="productname">PostgreSQL</span> is derived from the
+ <span class="productname">POSTGRES</span> package written at the
+ University of California at Berkeley. With decades of
+ development behind it, <span class="productname">PostgreSQL</span> is now
+ the most advanced open-source database available anywhere.
+ </p><div class="sect2" id="HISTORY-BERKELEY"><div class="titlepage"><div><div><h3 class="title">2.1. The Berkeley <span class="productname">POSTGRES</span> Project</h3></div></div></div><a id="id-1.3.5.4.2" class="indexterm"></a><p>
+ The <span class="productname">POSTGRES</span> project, led by Professor
+ Michael Stonebraker, was sponsored by the Defense Advanced Research
+ Projects Agency (<acronym class="acronym">DARPA</acronym>), the Army Research
+ Office (<acronym class="acronym">ARO</acronym>), the National Science Foundation
+ (<acronym class="acronym">NSF</acronym>), and ESL, Inc. The implementation of
+ <span class="productname">POSTGRES</span> began in 1986. The initial
+ concepts for the system were presented in <a class="xref" href="biblio.html#STON86">[ston86]</a>,
+ and the definition of the initial data model appeared in <a class="xref" href="biblio.html#ROWE87">[rowe87]</a>. The design of the rule system at that time was
+ described in <a class="xref" href="biblio.html#STON87A">[ston87a]</a>. The rationale and
+ architecture of the storage manager were detailed in <a class="xref" href="biblio.html#STON87B">[ston87b]</a>.
+ </p><p>
+ <span class="productname">POSTGRES</span> has undergone several major
+ releases since then. The first <span class="quote">“<span class="quote">demoware</span>”</span> system
+ became operational in 1987 and was shown at the 1988
+ <acronym class="acronym">ACM-SIGMOD</acronym> Conference. Version 1, described in
+ <a class="xref" href="biblio.html#STON90A">[ston90a]</a>, was released to a few external users in
+ June 1989. In response to a critique of the first rule system
+ (<a class="xref" href="biblio.html#STON89">[ston89]</a>), the rule system was redesigned (<a class="xref" href="biblio.html#STON90B">[ston90b]</a>), 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
+ until <span class="productname">Postgres95</span> (see below) focused on
+ portability and reliability.
+ </p><p>
+ <span class="productname">POSTGRES</span> has been used to implement many
+ different research and production applications. These include: a
+ financial data analysis system, a jet engine performance monitoring
+ package, an asteroid tracking database, a medical information
+ database, and several geographic information systems.
+ <span class="productname">POSTGRES</span> has also been used as an
+ educational tool at several universities. Finally, Illustra
+ Information Technologies (later merged into
+ <a class="ulink" href="https://www.ibm.com/analytics/informix" target="_top"><span class="productname">Informix</span></a>,
+ which is now owned by <a class="ulink" href="https://www.ibm.com/" target="_top">IBM</a>) picked up the code and
+ commercialized it. In late 1992,
+ <span class="productname">POSTGRES</span> became the primary data manager
+ for the
+ <a class="ulink" href="http://meteora.ucsd.edu/s2k/s2k_home.html" target="_top">
+ Sequoia 2000 scientific computing project</a>.
+ </p><p>
+ The size of the external user community nearly doubled during 1993.
+ It became increasingly obvious that maintenance of the prototype
+ code and support was taking up large amounts of time that should
+ have been devoted to database research. In an effort to reduce
+ this support burden, the Berkeley
+ <span class="productname">POSTGRES</span> project officially ended with
+ Version 4.2.
+ </p></div><div class="sect2" id="HISTORY-POSTGRES95"><div class="titlepage"><div><div><h3 class="title">2.2. <span class="productname">Postgres95</span></h3></div></div></div><a id="id-1.3.5.5.2" class="indexterm"></a><p>
+ In 1994, Andrew Yu and Jolly Chen added an SQL language interpreter
+ to <span class="productname">POSTGRES</span>. Under a new name,
+ <span class="productname">Postgres95</span> was subsequently released to
+ the web to find its own way in the world as an open-source
+ descendant of the original <span class="productname">POSTGRES</span>
+ Berkeley code.
+ </p><p>
+ <span class="productname">Postgres95</span> code was completely ANSI C
+ and trimmed in size by 25%. Many internal changes improved
+ performance and
+ maintainability. <span class="productname">Postgres95</span> release
+ 1.0.x ran about 30–50% faster on the Wisconsin Benchmark compared
+ to <span class="productname">POSTGRES</span>, Version 4.2. Apart from
+ bug fixes, the following were the major enhancements:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The query language PostQUEL was replaced with
+ <acronym class="acronym">SQL</acronym> (implemented in the server). (Interface
+ library <a class="link" href="libpq.html" title="Chapter 34. libpq — C Library">libpq</a> was named after PostQUEL.)
+ Subqueries
+ were not supported until <span class="productname">PostgreSQL</span>
+ (see below), but they could be imitated in
+ <span class="productname">Postgres95</span> with user-defined
+ <acronym class="acronym">SQL</acronym> functions. Aggregate functions were
+ re-implemented. Support for the <code class="literal">GROUP BY</code>
+ query clause was also added.
+ </p></li><li class="listitem"><p>
+ A new program
+ (<span class="application">psql</span>) was provided for interactive
+ SQL queries, which used <acronym class="acronym">GNU</acronym>
+ <span class="application">Readline</span>. This largely superseded
+ the old <span class="application">monitor</span> program.
+ </p></li><li class="listitem"><p>
+ A new front-end library, <code class="filename">libpgtcl</code>,
+ supported <acronym class="acronym">Tcl</acronym>-based clients. A sample shell,
+ <code class="command">pgtclsh</code>, provided new Tcl commands to
+ interface <span class="application">Tcl</span> programs with the
+ <span class="productname">Postgres95</span> server.
+ </p></li><li class="listitem"><p>
+ The large-object interface was overhauled. The inversion large
+ objects were the only mechanism for storing large objects. (The
+ inversion file system was removed.)
+ </p></li><li class="listitem"><p>
+ The instance-level rule system was removed. Rules were still
+ available as rewrite rules.
+ </p></li><li class="listitem"><p>
+ A short tutorial introducing regular <acronym class="acronym">SQL</acronym>
+ features as well as those of
+ <span class="productname">Postgres95</span> was distributed with the
+ source code
+ </p></li><li class="listitem"><p>
+ <acronym class="acronym">GNU</acronym> make (instead of <acronym class="acronym">BSD</acronym>
+ make) was used for the build. Also,
+ <span class="productname">Postgres95</span> could be compiled with an
+ unpatched <span class="productname">GCC</span> (data alignment of
+ doubles was fixed).
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="id-1.3.5.6"><div class="titlepage"><div><div><h3 class="title">2.3. <span class="productname">PostgreSQL</span></h3></div></div></div><p>
+ By 1996, it became clear that the name <span class="quote">“<span class="quote">Postgres95</span>”</span>
+ would not stand the test of time. We chose a new name,
+ <span class="productname">PostgreSQL</span>, to reflect the relationship
+ between the original <span class="productname">POSTGRES</span> and the
+ more recent versions with <acronym class="acronym">SQL</acronym> capability. At
+ the same time, we set the version numbering to start at 6.0,
+ putting the numbers back into the sequence originally begun by the
+ Berkeley <span class="productname">POSTGRES</span> project.
+ </p><p>
+ Many people continue to refer to
+ <span class="productname">PostgreSQL</span> as <span class="quote">“<span class="quote">Postgres</span>”</span>
+ (now rarely in all capital letters) because of tradition or because
+ it is easier to pronounce. This usage is widely accepted as a
+ nickname or alias.
+ </p><p>
+ The emphasis during development of
+ <span class="productname">Postgres95</span> was on identifying and
+ understanding existing problems in the server code. With
+ <span class="productname">PostgreSQL</span>, the emphasis has shifted to
+ augmenting features and capabilities, although work continues in
+ all areas.
+ </p><p>
+ Details about what has happened in <span class="productname">PostgreSQL</span> since
+ then can be found in <a class="xref" href="release.html" title="Appendix E. Release Notes">Appendix E</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro-whatis.html" title="1.  What Is PostgreSQL?">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="notation.html" title="3. Conventions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.  What Is <span class="productname">PostgreSQL</span>? </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3. Conventions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/hot-standby.html b/doc/src/sgml/html/hot-standby.html
new file mode 100644
index 0000000..adab809
--- /dev/null
+++ b/doc/src/sgml/html/hot-standby.html
@@ -0,0 +1,575 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>27.4. Hot Standby</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="warm-standby-failover.html" title="27.3. Failover" /><link rel="next" href="monitoring.html" title="Chapter 28. Monitoring Database Activity" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">27.4. Hot Standby</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="warm-standby-failover.html" title="27.3. Failover">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><th width="60%" align="center">Chapter 27. High Availability, Load Balancing, and Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Next</a></td></tr></table><hr /></div><div class="sect1" id="HOT-STANDBY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">27.4. Hot Standby</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-USERS">27.4.1. User's Overview</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-CONFLICT">27.4.2. Handling Query Conflicts</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-ADMIN">27.4.3. Administrator's Overview</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-PARAMETERS">27.4.4. Hot Standby Parameter Reference</a></span></dt><dt><span class="sect2"><a href="hot-standby.html#HOT-STANDBY-CAVEATS">27.4.5. Caveats</a></span></dt></dl></div><a id="id-1.6.14.18.2" class="indexterm"></a><p>
+ Hot standby is the term used to describe the ability to connect to
+ the server and run read-only queries while the server is in archive
+ recovery or standby mode. This
+ is useful both for replication purposes and for restoring a backup
+ to a desired state with great precision.
+ The term hot standby also refers to the ability of the server to move
+ from recovery through to normal operation while users continue running
+ queries and/or keep their connections open.
+ </p><p>
+ Running queries in hot standby mode is similar to normal query operation,
+ though there are several usage and administrative differences
+ explained below.
+ </p><div class="sect2" id="HOT-STANDBY-USERS"><div class="titlepage"><div><div><h3 class="title">27.4.1. User's Overview</h3></div></div></div><p>
+ When the <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a> 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.
+ </p><p>
+ The data on the standby takes some time to arrive from the primary server
+ so there will be a measurable delay between primary and standby. Running the
+ same query nearly simultaneously on both primary and standby might therefore
+ return differing results. We say that data on the standby is
+ <em class="firstterm">eventually consistent</em> with the primary. Once the
+ commit record for a transaction is replayed on the standby, the changes
+ 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 <a class="xref" href="transaction-iso.html" title="13.2. Transaction Isolation">Section 13.2</a>.
+ </p><p>
+ Transactions started during hot standby may issue the following commands:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Query access: <code class="command">SELECT</code>, <code class="command">COPY TO</code>
+ </p></li><li class="listitem"><p>
+ Cursor commands: <code class="command">DECLARE</code>, <code class="command">FETCH</code>, <code class="command">CLOSE</code>
+ </p></li><li class="listitem"><p>
+ Settings: <code class="command">SHOW</code>, <code class="command">SET</code>, <code class="command">RESET</code>
+ </p></li><li class="listitem"><p>
+ Transaction management commands:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ <code class="command">BEGIN</code>, <code class="command">END</code>, <code class="command">ABORT</code>, <code class="command">START TRANSACTION</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">SAVEPOINT</code>, <code class="command">RELEASE</code>, <code class="command">ROLLBACK TO SAVEPOINT</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">EXCEPTION</code> blocks and other internal subtransactions
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ <code class="command">LOCK TABLE</code>, though only when explicitly in one of these modes:
+ <code class="literal">ACCESS SHARE</code>, <code class="literal">ROW SHARE</code> or <code class="literal">ROW EXCLUSIVE</code>.
+ </p></li><li class="listitem"><p>
+ Plans and resources: <code class="command">PREPARE</code>, <code class="command">EXECUTE</code>,
+ <code class="command">DEALLOCATE</code>, <code class="command">DISCARD</code>
+ </p></li><li class="listitem"><p>
+ Plugins and extensions: <code class="command">LOAD</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">UNLISTEN</code>
+ </p></li></ul></div><p>
+ </p><p>
+ Transactions started during hot standby will never be assigned a
+ transaction ID and cannot write to the system write-ahead log.
+ Therefore, the following actions will produce error messages:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Data Manipulation Language (DML): <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">MERGE</code>, <code class="command">COPY FROM</code>,
+ <code class="command">TRUNCATE</code>.
+ Note that there are no allowed actions that result in a trigger
+ being executed during recovery. This restriction applies even to
+ temporary tables, because table rows cannot be read or written without
+ assigning a transaction ID, which is currently not possible in a
+ hot standby environment.
+ </p></li><li class="listitem"><p>
+ Data Definition Language (DDL): <code class="command">CREATE</code>,
+ <code class="command">DROP</code>, <code class="command">ALTER</code>, <code class="command">COMMENT</code>.
+ This restriction applies even to temporary tables, because carrying
+ out these operations would require updating the system catalog tables.
+ </p></li><li class="listitem"><p>
+ <code class="command">SELECT ... FOR SHARE | UPDATE</code>, because row locks cannot be
+ taken without updating the underlying data files.
+ </p></li><li class="listitem"><p>
+ Rules on <code class="command">SELECT</code> statements that generate DML commands.
+ </p></li><li class="listitem"><p>
+ <code class="command">LOCK</code> that explicitly requests a mode higher than <code class="literal">ROW EXCLUSIVE MODE</code>.
+ </p></li><li class="listitem"><p>
+ <code class="command">LOCK</code> in short default form, since it requests <code class="literal">ACCESS EXCLUSIVE MODE</code>.
+ </p></li><li class="listitem"><p>
+ Transaction management commands that explicitly set non-read-only state:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ <code class="command">BEGIN READ WRITE</code>,
+ <code class="command">START TRANSACTION READ WRITE</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">SET TRANSACTION READ WRITE</code>,
+ <code class="command">SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">SET transaction_read_only = off</code>
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ Two-phase commit commands: <code class="command">PREPARE TRANSACTION</code>,
+ <code class="command">COMMIT PREPARED</code>, <code class="command">ROLLBACK PREPARED</code>
+ because even read-only transactions need to write WAL in the
+ prepare phase (the first phase of two phase commit).
+ </p></li><li class="listitem"><p>
+ Sequence updates: <code class="function">nextval()</code>, <code class="function">setval()</code>
+ </p></li><li class="listitem"><p>
+ <code class="command">LISTEN</code>, <code class="command">NOTIFY</code>
+ </p></li></ul></div><p>
+ </p><p>
+ In normal operation, <span class="quote">“<span class="quote">read-only</span>”</span> transactions are allowed to
+ use <code class="command">LISTEN</code> and <code class="command">NOTIFY</code>,
+ so hot standby sessions operate under slightly tighter
+ restrictions than ordinary read-only sessions. It is possible that some
+ of these restrictions might be loosened in a future release.
+ </p><p>
+ During hot standby, the parameter <code class="varname">transaction_read_only</code> is always
+ true and may not be changed. But as long as no attempt is made to modify
+ the database, connections during hot standby will act much like any other
+ database connection. If failover or switchover occurs, the database will
+ switch to normal processing mode. Sessions will remain connected while the
+ server changes mode. Once hot standby finishes, it will be possible to
+ initiate read-write transactions (even from a session begun during
+ hot standby).
+ </p><p>
+ Users can determine whether hot standby is currently active for their
+ session by issuing <code class="command">SHOW in_hot_standby</code>.
+ (In server versions before 14, the <code class="varname">in_hot_standby</code>
+ parameter did not exist; a workable substitute method for older servers
+ is <code class="command">SHOW transaction_read_only</code>.) In addition, a set of
+ functions (<a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-INFO-TABLE" title="Table 9.90. Recovery Information Functions">Table 9.90</a>) 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
+ write complex programs that restore the database to particular states.
+ </p></div><div class="sect2" id="HOT-STANDBY-CONFLICT"><div class="titlepage"><div><div><h3 class="title">27.4.2. Handling Query Conflicts</h3></div></div></div><p>
+ The primary and standby servers are in many ways loosely connected. Actions
+ on the primary will have an effect on the standby. As a result, there is
+ potential for negative interactions or conflicts between them. The easiest
+ conflict to understand is performance: if a huge data load is taking place
+ on the primary then this will generate a similar stream of WAL records on the
+ standby, so standby queries may contend for system resources, such as I/O.
+ </p><p>
+ There are also additional types of conflict that can occur with hot standby.
+ These conflicts are <span class="emphasis"><em>hard conflicts</em></span> in the sense that queries
+ might need to be canceled and, in some cases, sessions disconnected to resolve them.
+ The user is provided with several ways to handle these
+ conflicts. Conflict cases include:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Access Exclusive locks taken on the primary server, including both
+ explicit <code class="command">LOCK</code> commands and various <acronym class="acronym">DDL</acronym>
+ actions, conflict with table accesses in standby queries.
+ </p></li><li class="listitem"><p>
+ Dropping a tablespace on the primary conflicts with standby queries
+ using that tablespace for temporary work files.
+ </p></li><li class="listitem"><p>
+ Dropping a database on the primary conflicts with sessions connected
+ to that database on the standby.
+ </p></li><li class="listitem"><p>
+ Application of a vacuum cleanup record from WAL conflicts with
+ standby transactions whose snapshots can still <span class="quote">“<span class="quote">see</span>”</span> any of
+ the rows to be removed.
+ </p></li><li class="listitem"><p>
+ Application of a vacuum cleanup record from WAL conflicts with
+ queries accessing the target page on the standby, whether or not
+ the data to be removed is visible.
+ </p></li></ul></div><p>
+ </p><p>
+ On the primary server, these cases simply result in waiting; and the
+ user might choose to cancel either of the conflicting actions. However,
+ on the standby there is no choice: the WAL-logged action already occurred
+ on the primary so the standby must not fail to apply it. Furthermore,
+ allowing WAL application to wait indefinitely may be very undesirable,
+ because the standby's state will become increasingly far behind the
+ primary's. Therefore, a mechanism is provided to forcibly cancel standby
+ queries that conflict with to-be-applied WAL records.
+ </p><p>
+ An example of the problem situation is an administrator on the primary
+ server running <code class="command">DROP TABLE</code> on a table that is currently being
+ queried on the standby server. Clearly the standby query cannot continue
+ if the <code class="command">DROP TABLE</code> is applied on the standby. If this situation
+ occurred on the primary, the <code class="command">DROP TABLE</code> would wait until the
+ other query had finished. But when <code class="command">DROP TABLE</code> is run on the
+ primary, the primary doesn't have information about what queries are
+ running on the standby, so it will not wait for any such standby
+ queries. The WAL change records come through to the standby while the
+ standby query is still running, causing a conflict. The standby server
+ must either delay application of the WAL records (and everything after
+ them, too) or else cancel the conflicting query so that the <code class="command">DROP
+ TABLE</code> can be applied.
+ </p><p>
+ 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, <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-ARCHIVE-DELAY">max_standby_archive_delay</a> and <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-STREAMING-DELAY">max_standby_streaming_delay</a>, 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
+ values can be specified for the case of reading WAL data from an archive
+ (i.e., initial recovery from a base backup or <span class="quote">“<span class="quote">catching up</span>”</span> a
+ standby server that has fallen far behind) versus reading WAL data via
+ streaming replication.
+ </p><p>
+ In a standby server that exists primarily for high availability, it's
+ best to set the delay parameters relatively short, so that the server
+ cannot fall far behind the primary due to delays caused by standby
+ queries. However, if the standby server is meant for executing
+ long-running queries, then a high or even infinite delay value may be
+ preferable. Keep in mind however that a long-running query could
+ cause other sessions on the standby server to not see recent changes
+ on the primary, if it delays application of WAL records.
+ </p><p>
+ Once the delay specified by <code class="varname">max_standby_archive_delay</code> or
+ <code class="varname">max_standby_streaming_delay</code> has been exceeded, conflicting
+ queries will be canceled. This usually results just in a cancellation
+ error, although in the case of replaying a <code class="command">DROP DATABASE</code>
+ the entire conflicting session will be terminated. Also, if the conflict
+ is over a lock held by an idle transaction, the conflicting session is
+ terminated (this behavior might change in the future).
+ </p><p>
+ Canceled queries may be retried immediately (after beginning a new
+ transaction, of course). Since query cancellation depends on
+ the nature of the WAL records being replayed, a query that was
+ canceled may well succeed if it is executed again.
+ </p><p>
+ Keep in mind that the delay parameters are compared to the elapsed time
+ since the WAL data was received by the standby server. Thus, the grace
+ period allowed to any one query on the standby is never more than the
+ delay parameter, and could be considerably less if the standby has already
+ fallen behind as a result of waiting for previous queries to complete, or
+ as a result of being unable to keep up with a heavy update load.
+ </p><p>
+ The most common reason for conflict between standby queries and WAL replay
+ is <span class="quote">“<span class="quote">early cleanup</span>”</span>. Normally, <span class="productname">PostgreSQL</span> allows
+ cleanup of old row versions when there are no transactions that need to
+ see them to ensure correct visibility of data according to MVCC rules.
+ However, this rule can only be applied for transactions executing on the
+ primary. So it is possible that cleanup on the primary will remove row
+ versions that are still visible to a transaction on the standby.
+ </p><p>
+ Experienced users should note that both row version cleanup and row version
+ freezing will potentially conflict with standby queries. Running a manual
+ <code class="command">VACUUM FREEZE</code> is likely to cause conflicts even on tables with
+ no updated or deleted rows.
+ </p><p>
+ Users should be clear that tables that are regularly and heavily updated
+ on the primary server will quickly cause cancellation of longer running
+ queries on the standby. In such cases the setting of a finite value for
+ <code class="varname">max_standby_archive_delay</code> or
+ <code class="varname">max_standby_streaming_delay</code> can be considered similar to
+ setting <code class="varname">statement_timeout</code>.
+ </p><p>
+ Remedial possibilities exist if the number of standby-query cancellations
+ is found to be unacceptable. The first option is to set the parameter
+ <code class="varname">hot_standby_feedback</code>, which prevents <code class="command">VACUUM</code> from
+ removing recently-dead rows and so cleanup conflicts do not occur.
+ If you do this, you
+ should note that this will delay cleanup of dead rows on the primary,
+ which may result in undesirable table bloat. However, the cleanup
+ situation will be no worse than if the standby queries were running
+ directly on the primary server, and you are still getting the benefit of
+ off-loading execution onto the standby.
+ If standby servers connect and disconnect frequently, you
+ might want to make adjustments to handle the period when
+ <code class="varname">hot_standby_feedback</code> feedback is not being provided.
+ For example, consider increasing <code class="varname">max_standby_archive_delay</code>
+ so that queries are not rapidly canceled by conflicts in WAL archive
+ files during disconnected periods. You should also consider increasing
+ <code class="varname">max_standby_streaming_delay</code> to avoid rapid cancellations
+ by newly-arrived streaming WAL entries after reconnection.
+ </p><p>
+ Another option is to increase <a class="xref" href="runtime-config-replication.html#GUC-VACUUM-DEFER-CLEANUP-AGE">vacuum_defer_cleanup_age</a>
+ 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
+ a high <code class="varname">max_standby_streaming_delay</code>. However it is
+ difficult to guarantee any specific execution-time window with this
+ approach, since <code class="varname">vacuum_defer_cleanup_age</code> is measured in
+ transactions executed on the primary server.
+ </p><p>
+ The number of query cancels and the reason for them can be viewed using
+ the <code class="structname">pg_stat_database_conflicts</code> system view on the standby
+ server. The <code class="structname">pg_stat_database</code> system view also contains
+ summary information.
+ </p><p>
+ Users can control whether a log message is produced when WAL replay is waiting
+ longer than <code class="varname">deadlock_timeout</code> for conflicts. This
+ is controlled by the <a class="xref" href="runtime-config-logging.html#GUC-LOG-RECOVERY-CONFLICT-WAITS">log_recovery_conflict_waits</a> parameter.
+ </p></div><div class="sect2" id="HOT-STANDBY-ADMIN"><div class="titlepage"><div><div><h3 class="title">27.4.3. Administrator's Overview</h3></div></div></div><p>
+ If <code class="varname">hot_standby</code> is <code class="literal">on</code> in <code class="filename">postgresql.conf</code>
+ (the default value) and there is a
+ <a class="link" href="warm-standby.html#FILE-STANDBY-SIGNAL"><code class="filename">standby.signal</code></a><a id="id-1.6.14.18.7.2.5" class="indexterm"></a>
+ file present, the server will run in hot standby mode.
+ However, it may take some time for hot standby connections to be allowed,
+ because the server will not accept connections until it has completed
+ sufficient recovery to provide a consistent state against which queries
+ can run. During this period,
+ clients that attempt to connect will be refused with an error message.
+ To confirm the server has come up, either loop trying to connect from
+ the application, or look for these messages in the server logs:
+
+</p><pre class="programlisting">
+LOG: entering standby mode
+
+... then some time later ...
+
+LOG: consistent recovery state reached
+LOG: database system is ready to accept read-only connections
+</pre><p>
+
+ Consistency information is recorded once per checkpoint on the primary.
+ It is not possible to enable hot standby when reading WAL
+ written during a period when <code class="varname">wal_level</code> was not set to
+ <code class="literal">replica</code> or <code class="literal">logical</code> on the primary. Reaching
+ a consistent state can also be delayed in the presence of both of these
+ conditions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A write transaction has more than 64 subtransactions
+ </p></li><li class="listitem"><p>
+ Very long-lived write transactions
+ </p></li></ul></div><p>
+
+ If you are running file-based log shipping ("warm standby"), you might need
+ to wait until the next WAL file arrives, which could be as long as the
+ <code class="varname">archive_timeout</code> setting on the primary.
+ </p><p>
+ The settings of some parameters determine the size of shared memory for
+ tracking transaction IDs, locks, and prepared transactions. These shared
+ memory structures must be no smaller on a standby than on the primary in
+ order to ensure that the standby does not run out of shared memory during
+ recovery. For example, if the primary had used a prepared transaction but
+ the standby had not allocated any shared memory for tracking prepared
+ transactions, then recovery could not continue until the standby's
+ configuration is changed. The parameters affected are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="varname">max_connections</code>
+ </p></li><li class="listitem"><p>
+ <code class="varname">max_prepared_transactions</code>
+ </p></li><li class="listitem"><p>
+ <code class="varname">max_locks_per_transaction</code>
+ </p></li><li class="listitem"><p>
+ <code class="varname">max_wal_senders</code>
+ </p></li><li class="listitem"><p>
+ <code class="varname">max_worker_processes</code>
+ </p></li></ul></div><p>
+
+ The easiest way to ensure this does not become a problem is to have these
+ parameters set on the standbys to values equal to or greater than on the
+ primary. Therefore, if you want to increase these values, you should do
+ so on all standby servers first, before applying the changes to the
+ primary server. Conversely, if you want to decrease these values, you
+ should do so on the primary server first, before applying the changes to
+ all standby servers. Keep in mind that when a standby is promoted, it
+ becomes the new reference for the required parameter settings for the
+ standbys that follow it. Therefore, to avoid this becoming a problem
+ during a switchover or failover, it is recommended to keep these settings
+ the same on all standby servers.
+ </p><p>
+ The WAL tracks changes to these parameters on the
+ primary. If a hot standby processes WAL that indicates that the current
+ value on the primary is higher than its own value, it will log a warning
+ and pause recovery, for example:
+</p><pre class="screen">
+WARNING: hot standby is not possible because of insufficient parameter settings
+DETAIL: max_connections = 80 is a lower setting than on the primary server, where its value was 100.
+LOG: recovery has paused
+DETAIL: If recovery is unpaused, the server will shut down.
+HINT: You can then restart the server after making the necessary configuration changes.
+</pre><p>
+ At that point, the settings on the standby need to be updated and the
+ instance restarted before recovery can continue. If the standby is not a
+ hot standby, then when it encounters the incompatible parameter change, it
+ will shut down immediately without pausing, since there is then no value
+ in keeping it up.
+ </p><p>
+ It is important that the administrator select appropriate settings for
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-ARCHIVE-DELAY">max_standby_archive_delay</a> and <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-STREAMING-DELAY">max_standby_streaming_delay</a>. 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
+ the standby server is tasked as an additional server for decision support
+ queries then it might be acceptable to set the maximum delay values to
+ many hours, or even -1 which means wait forever for queries to complete.
+ </p><p>
+ Transaction status "hint bits" written on the primary are not WAL-logged,
+ so data on the standby will likely re-write the hints again on the standby.
+ Thus, the standby server will still perform disk writes even though
+ all users are read-only; no changes occur to the data values
+ themselves. Users will still write large sort temporary files and
+ re-generate relcache info files, so no part of the database
+ is truly read-only during hot standby mode.
+ Note also that writes to remote databases using
+ <span class="application">dblink</span> module, and other operations outside the
+ database using PL functions will still be possible, even though the
+ transaction is read-only locally.
+ </p><p>
+ The following types of administration commands are not accepted
+ during recovery mode:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Data Definition Language (DDL): e.g., <code class="command">CREATE INDEX</code>
+ </p></li><li class="listitem"><p>
+ Privilege and Ownership: <code class="command">GRANT</code>, <code class="command">REVOKE</code>,
+ <code class="command">REASSIGN</code>
+ </p></li><li class="listitem"><p>
+ Maintenance commands: <code class="command">ANALYZE</code>, <code class="command">VACUUM</code>,
+ <code class="command">CLUSTER</code>, <code class="command">REINDEX</code>
+ </p></li></ul></div><p>
+ </p><p>
+ Again, note that some of these commands are actually allowed during
+ "read only" mode transactions on the primary.
+ </p><p>
+ As a result, you cannot create additional indexes that exist solely
+ on the standby, nor statistics that exist solely on the standby.
+ If these administration commands are needed, they should be executed
+ on the primary, and eventually those changes will propagate to the
+ standby.
+ </p><p>
+ <code class="function">pg_cancel_backend()</code>
+ and <code class="function">pg_terminate_backend()</code> will work on user backends,
+ but not the startup process, which performs
+ recovery. <code class="structname">pg_stat_activity</code> does not show
+ recovering transactions as active. As a result,
+ <code class="structname">pg_prepared_xacts</code> is always empty during
+ recovery. If you wish to resolve in-doubt prepared transactions, view
+ <code class="literal">pg_prepared_xacts</code> on the primary and issue commands to
+ resolve transactions there or resolve them after the end of recovery.
+ </p><p>
+ <code class="structname">pg_locks</code> will show locks held by backends,
+ as normal. <code class="structname">pg_locks</code> also shows
+ a virtual transaction managed by the startup process that owns all
+ <code class="literal">AccessExclusiveLocks</code> held by transactions being replayed by recovery.
+ Note that the startup process does not acquire locks to
+ make database changes, and thus locks other than <code class="literal">AccessExclusiveLocks</code>
+ do not show in <code class="structname">pg_locks</code> for the Startup
+ process; they are just presumed to exist.
+ </p><p>
+ The <span class="productname">Nagios</span> plugin <span class="productname">check_pgsql</span> will
+ work, because the simple information it checks for exists.
+ The <span class="productname">check_postgres</span> monitoring script will also work,
+ though some reported values could give different or confusing results.
+ For example, last vacuum time will not be maintained, since no
+ vacuum occurs on the standby. Vacuums running on the primary
+ do still send their changes to the standby.
+ </p><p>
+ WAL file control commands will not work during recovery,
+ e.g., <code class="function">pg_backup_start</code>, <code class="function">pg_switch_wal</code> etc.
+ </p><p>
+ Dynamically loadable modules work, including <code class="structname">pg_stat_statements</code>.
+ </p><p>
+ Advisory locks work normally in recovery, including deadlock detection.
+ Note that advisory locks are never WAL logged, so it is impossible for
+ an advisory lock on either the primary or the standby to conflict with WAL
+ replay. Nor is it possible to acquire an advisory lock on the primary
+ and have it initiate a similar advisory lock on the standby. Advisory
+ locks relate only to the server on which they are acquired.
+ </p><p>
+ Trigger-based replication systems such as <span class="productname">Slony</span>,
+ <span class="productname">Londiste</span> and <span class="productname">Bucardo</span> won't run on the
+ standby at all, though they will run happily on the primary server as
+ long as the changes are not sent to standby servers to be applied.
+ WAL replay is not trigger-based so you cannot relay from the
+ standby to any system that requires additional database writes or
+ relies on the use of triggers.
+ </p><p>
+ New OIDs cannot be assigned, though some <acronym class="acronym">UUID</acronym> generators may still
+ work as long as they do not rely on writing new status to the database.
+ </p><p>
+ Currently, temporary table creation is not allowed during read-only
+ transactions, so in some cases existing scripts will not run correctly.
+ This restriction might be relaxed in a later release. This is
+ both an SQL standard compliance issue and a technical issue.
+ </p><p>
+ <code class="command">DROP TABLESPACE</code> can only succeed if the tablespace is empty.
+ Some standby users may be actively using the tablespace via their
+ <code class="varname">temp_tablespaces</code> parameter. If there are temporary files in the
+ tablespace, all active queries are canceled to ensure that temporary
+ files are removed, so the tablespace can be removed and WAL replay
+ can continue.
+ </p><p>
+ Running <code class="command">DROP DATABASE</code> or <code class="command">ALTER DATABASE ... SET
+ TABLESPACE</code> on the primary
+ will generate a WAL entry that will cause all users connected to that
+ database on the standby to be forcibly disconnected. This action occurs
+ immediately, whatever the setting of
+ <code class="varname">max_standby_streaming_delay</code>. Note that
+ <code class="command">ALTER DATABASE ... RENAME</code> does not disconnect users, which
+ in most cases will go unnoticed, though might in some cases cause a
+ program confusion if it depends in some way upon database name.
+ </p><p>
+ In normal (non-recovery) mode, if you issue <code class="command">DROP USER</code> or <code class="command">DROP ROLE</code>
+ for a role with login capability while that user is still connected then
+ nothing happens to the connected user — they remain connected. The user cannot
+ reconnect however. This behavior applies in recovery also, so a
+ <code class="command">DROP USER</code> on the primary does not disconnect that user on the standby.
+ </p><p>
+ The cumulative statistics system is active during recovery. All scans,
+ reads, blocks, index usage, etc., will be recorded normally on the
+ standby. However, WAL replay will not increment relation and database
+ specific counters. I.e. replay will not increment pg_stat_all_tables
+ columns (like n_tup_ins), nor will reads or writes performed by the
+ startup process be tracked in the pg_statio views, nor will associated
+ pg_stat_database columns be incremented.
+ </p><p>
+ Autovacuum is not active during recovery. It will start normally at the
+ end of recovery.
+ </p><p>
+ The checkpointer process and the background writer process are active during
+ recovery. The checkpointer process will perform restartpoints (similar to
+ checkpoints on the primary) and the background writer process will perform
+ normal block cleaning activities. This can include updates of the hint bit
+ information stored on the standby server.
+ The <code class="command">CHECKPOINT</code> command is accepted during recovery,
+ though it performs a restartpoint rather than a new checkpoint.
+ </p></div><div class="sect2" id="HOT-STANDBY-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">27.4.4. Hot Standby Parameter Reference</h3></div></div></div><p>
+ Various parameters have been mentioned above in
+ <a class="xref" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="27.4.2. Handling Query Conflicts">Section 27.4.2</a> and
+ <a class="xref" href="hot-standby.html#HOT-STANDBY-ADMIN" title="27.4.3. Administrator's Overview">Section 27.4.3</a>.
+ </p><p>
+ On the primary, parameters <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> and
+ <a class="xref" href="runtime-config-replication.html#GUC-VACUUM-DEFER-CLEANUP-AGE">vacuum_defer_cleanup_age</a> can be used.
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-ARCHIVE-DELAY">max_standby_archive_delay</a> and
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-STREAMING-DELAY">max_standby_streaming_delay</a> have no effect if set on
+ the primary.
+ </p><p>
+ On the standby, parameters <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a>,
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-ARCHIVE-DELAY">max_standby_archive_delay</a> and
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-STANDBY-STREAMING-DELAY">max_standby_streaming_delay</a> can be used.
+ <a class="xref" href="runtime-config-replication.html#GUC-VACUUM-DEFER-CLEANUP-AGE">vacuum_defer_cleanup_age</a> has no effect
+ as long as the server remains in standby mode, though it will
+ become relevant if the standby becomes primary.
+ </p></div><div class="sect2" id="HOT-STANDBY-CAVEATS"><div class="titlepage"><div><div><h3 class="title">27.4.5. Caveats</h3></div></div></div><p>
+ There are several limitations of hot standby.
+ These can and probably will be fixed in future releases:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Full knowledge of running transactions is required before snapshots
+ can be taken. Transactions that use large numbers of subtransactions
+ (currently greater than 64) will delay the start of read-only
+ connections until the completion of the longest running write transaction.
+ If this situation occurs, explanatory messages will be sent to the server log.
+ </p></li><li class="listitem"><p>
+ Valid starting points for standby queries are generated at each
+ checkpoint on the primary. If the standby is shut down while the primary
+ is in a shutdown state, it might not be possible to re-enter hot standby
+ until the primary is started up, so that it generates further starting
+ points in the WAL logs. This situation isn't a problem in the most
+ common situations where it might happen. Generally, if the primary is
+ shut down and not available anymore, that's likely due to a serious
+ failure that requires the standby being converted to operate as
+ the new primary anyway. And in situations where the primary is
+ being intentionally taken down, coordinating to make sure the standby
+ becomes the new primary smoothly is also standard procedure.
+ </p></li><li class="listitem"><p>
+ At the end of recovery, <code class="literal">AccessExclusiveLocks</code> held by prepared transactions
+ will require twice the normal number of lock table entries. If you plan
+ on running either a large number of concurrent prepared transactions
+ that normally take <code class="literal">AccessExclusiveLocks</code>, or you plan on having one
+ large transaction that takes many <code class="literal">AccessExclusiveLocks</code>, you are
+ advised to select a larger value of <code class="varname">max_locks_per_transaction</code>,
+ perhaps as much as twice the value of the parameter on
+ the primary server. You need not consider this at all if
+ your setting of <code class="varname">max_prepared_transactions</code> is 0.
+ </p></li><li class="listitem"><p>
+ The Serializable transaction isolation level is not yet available in hot
+ standby. (See <a class="xref" href="transaction-iso.html#XACT-SERIALIZABLE" title="13.2.3. Serializable Isolation Level">Section 13.2.3</a> and
+ <a class="xref" href="applevel-consistency.html#SERIALIZABLE-CONSISTENCY" title="13.4.1. Enforcing Consistency with Serializable Transactions">Section 13.4.1</a> for details.)
+ An attempt to set a transaction to the serializable isolation level in
+ hot standby mode will generate an error.
+ </p></li></ul></div><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="warm-standby-failover.html" title="27.3. Failover">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Next</a></td></tr><tr><td width="40%" align="left" valign="top">27.3. Failover </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 28. Monitoring Database Activity</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/how-parallel-query-works.html b/doc/src/sgml/html/how-parallel-query-works.html
new file mode 100644
index 0000000..92a0e2d
--- /dev/null
+++ b/doc/src/sgml/html/how-parallel-query-works.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.1. How Parallel Query Works</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="parallel-query.html" title="Chapter 15. Parallel Query" /><link rel="next" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.1. How Parallel Query Works</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="parallel-query.html" title="Chapter 15. Parallel Query">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?">Next</a></td></tr></table><hr /></div><div class="sect1" id="HOW-PARALLEL-QUERY-WORKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.1. How Parallel Query Works</h2></div></div></div><p>
+ When the optimizer determines that parallel query is the fastest execution
+ strategy for a particular query, it will create a query plan that includes
+ a <em class="firstterm">Gather</em> or <em class="firstterm">Gather Merge</em>
+ node. Here is a simple example:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
+ QUERY PLAN
+-------------------------------------------------------------------​------------------
+ Gather (cost=1000.00..217018.43 rows=1 width=97)
+ Workers Planned: 2
+ -&gt; Parallel Seq Scan on pgbench_accounts (cost=0.00..216018.33 rows=1 width=97)
+ Filter: (filler ~~ '%x%'::text)
+(4 rows)
+</pre><p>
+ </p><p>
+ In all cases, the <code class="literal">Gather</code> or
+ <code class="literal">Gather Merge</code> node will have exactly one
+ child plan, which is the portion of the plan that will be executed in
+ parallel. If the <code class="literal">Gather</code> or <code class="literal">Gather Merge</code> node is
+ at the very top of the plan tree, then the entire query will execute in
+ parallel. If it is somewhere else in the plan tree, then only the portion
+ of the plan below it will run in parallel. In the example above, the
+ query accesses only one table, so there is only one plan node other than
+ the <code class="literal">Gather</code> node itself; since that plan node is a child of the
+ <code class="literal">Gather</code> node, it will run in parallel.
+ </p><p>
+ <a class="link" href="using-explain.html" title="14.1. Using EXPLAIN">Using EXPLAIN</a>, you can see the number of
+ workers chosen by the planner. When the <code class="literal">Gather</code> node is reached
+ during query execution, the process that is implementing the user's
+ session will request a number of <a class="link" href="bgworker.html" title="Chapter 48. Background Worker Processes">background
+ worker processes</a> equal to the number
+ of workers chosen by the planner. The number of background workers that
+ the planner will consider using is limited to at most
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a>. The total number
+ of background workers that can exist at any one time is limited by both
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a> and
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>. Therefore, it is possible for a
+ parallel query to run with fewer workers than planned, or even with
+ no workers at all. The optimal plan may depend on the number of workers
+ that are available, so this can result in poor query performance. If this
+ occurrence is frequent, consider increasing
+ <code class="varname">max_worker_processes</code> and <code class="varname">max_parallel_workers</code>
+ so that more workers can be run simultaneously or alternatively reducing
+ <code class="varname">max_parallel_workers_per_gather</code> so that the planner
+ requests fewer workers.
+ </p><p>
+ Every background worker process that is successfully started for a given
+ parallel query will execute the parallel portion of the plan. The leader
+ will also execute that portion of the plan, but it has an additional
+ responsibility: it must also read all of the tuples generated by the
+ workers. When the parallel portion of the plan generates only a small
+ number of tuples, the leader will often behave very much like an additional
+ worker, speeding up query execution. Conversely, when the parallel portion
+ of the plan generates a large number of tuples, the leader may be almost
+ entirely occupied with reading the tuples generated by the workers and
+ performing any further processing steps that are required by plan nodes
+ above the level of the <code class="literal">Gather</code> node or
+ <code class="literal">Gather Merge</code> node. In such cases, the leader will
+ do very little of the work of executing the parallel portion of the plan.
+ </p><p>
+ When the node at the top of the parallel portion of the plan is
+ <code class="literal">Gather Merge</code> rather than <code class="literal">Gather</code>, it indicates that
+ each process executing the parallel portion of the plan is producing
+ tuples in sorted order, and that the leader is performing an
+ order-preserving merge. In contrast, <code class="literal">Gather</code> reads tuples
+ from the workers in whatever order is convenient, destroying any sort
+ order that may have existed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel-query.html" title="Chapter 15. Parallel Query">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. Parallel Query </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 15.2. When Can Parallel Query Be Used?</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/hstore.html b/doc/src/sgml/html/hstore.html
new file mode 100644
index 0000000..1b5c7ff
--- /dev/null
+++ b/doc/src/sgml/html/hstore.html
@@ -0,0 +1,699 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.18. hstore</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch" /><link rel="next" href="intagg.html" title="F.19. intagg" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.18. hstore</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="intagg.html" title="F.19. intagg">Next</a></td></tr></table><hr /></div><div class="sect1" id="HSTORE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.18. hstore</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.5">F.18.1. <code class="type">hstore</code> External Representation</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.6">F.18.2. <code class="type">hstore</code> Operators and Functions</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.7">F.18.3. Indexes</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.8">F.18.4. Examples</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.9">F.18.5. Statistics</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.10">F.18.6. Compatibility</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.11">F.18.7. Transforms</a></span></dt><dt><span class="sect2"><a href="hstore.html#id-1.11.7.27.12">F.18.8. Authors</a></span></dt></dl></div><a id="id-1.11.7.27.2" class="indexterm"></a><p>
+ This module implements the <code class="type">hstore</code> data type for storing sets of
+ key/value pairs within a single <span class="productname">PostgreSQL</span> value.
+ This can be useful in various scenarios, such as rows with many attributes
+ that are rarely examined, or semi-structured data. Keys and values are
+ simply text strings.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.27.5"><div class="titlepage"><div><div><h3 class="title">F.18.1. <code class="type">hstore</code> External Representation</h3></div></div></div><p>
+
+ The text representation of an <code class="type">hstore</code>, used for input and output,
+ includes zero or more <em class="replaceable"><code>key</code></em> <code class="literal">=&gt;</code>
+ <em class="replaceable"><code>value</code></em> pairs separated by commas. Some examples:
+
+</p><pre class="synopsis">
+k =&gt; v
+foo =&gt; bar, baz =&gt; whatever
+"1-a" =&gt; "anything at all"
+</pre><p>
+
+ The order of the pairs is not significant (and may not be reproduced on
+ output). Whitespace between pairs or around the <code class="literal">=&gt;</code> sign is
+ ignored. Double-quote keys and values that include whitespace, commas,
+ <code class="literal">=</code>s or <code class="literal">&gt;</code>s. To include a double quote or a
+ backslash in a key or value, escape it with a backslash.
+ </p><p>
+ Each key in an <code class="type">hstore</code> is unique. If you declare an <code class="type">hstore</code>
+ with duplicate keys, only one will be stored in the <code class="type">hstore</code> and
+ there is no guarantee as to which will be kept:
+
+</p><pre class="programlisting">
+SELECT 'a=&gt;1,a=&gt;2'::hstore;
+ hstore
+----------
+ "a"=&gt;"1"
+</pre><p>
+ </p><p>
+ A value (but not a key) can be an SQL <code class="literal">NULL</code>. For example:
+
+</p><pre class="programlisting">
+key =&gt; NULL
+</pre><p>
+
+ The <code class="literal">NULL</code> keyword is case-insensitive. Double-quote the
+ <code class="literal">NULL</code> to treat it as the ordinary string <span class="quote">“<span class="quote">NULL</span>”</span>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Keep in mind that the <code class="type">hstore</code> text format, when used for input,
+ applies <span class="emphasis"><em>before</em></span> any required quoting or escaping. If you are
+ passing an <code class="type">hstore</code> literal via a parameter, then no additional
+ processing is needed. But if you're passing it as a quoted literal
+ constant, then any single-quote characters and (depending on the setting of
+ the <code class="varname">standard_conforming_strings</code> configuration parameter)
+ backslash characters need to be escaped correctly. See
+ <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> for more on the handling of string
+ constants.
+ </p></div><p>
+ On output, double quotes always surround keys and values, even when it's
+ not strictly necessary.
+ </p></div><div class="sect2" id="id-1.11.7.27.6"><div class="titlepage"><div><div><h3 class="title">F.18.2. <code class="type">hstore</code> Operators and Functions</h3></div></div></div><p>
+ The operators provided by the <code class="literal">hstore</code> module are
+ shown in <a class="xref" href="hstore.html#HSTORE-OP-TABLE" title="Table F.7. hstore Operators">Table F.7</a>, the functions
+ in <a class="xref" href="hstore.html#HSTORE-FUNC-TABLE" title="Table F.8. hstore Functions">Table F.8</a>.
+ </p><div class="table" id="HSTORE-OP-TABLE"><p class="title"><strong>Table F.7. <code class="type">hstore</code> Operators</strong></p><div class="table-contents"><table class="table" summary="hstore Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns value associated with given key, or <code class="literal">NULL</code> if
+ not present.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;x, b=&gt;y'::hstore -&gt; 'a'</code>
+ → <code class="returnvalue">x</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">-&gt;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Returns values associated with given keys, or <code class="literal">NULL</code>
+ if not present.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;x, b=&gt;y, c=&gt;z'::hstore -&gt; ARRAY['c','a']</code>
+ → <code class="returnvalue">{"z","x"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">||</code> <code class="type">hstore</code>
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Concatenates two <code class="type">hstore</code>s.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;b, c=&gt;d'::hstore || 'c=&gt;x, d=&gt;q'::hstore</code>
+ → <code class="returnvalue">"a"=&gt;"b", "c"=&gt;"x", "d"=&gt;"q"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">?</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">hstore</code> contain key?
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1'::hstore ? 'a'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">?&amp;</code> <code class="type">text[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">hstore</code> contain all the specified keys?
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1,b=&gt;2'::hstore ?&amp; ARRAY['a','b']</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">?|</code> <code class="type">text[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">hstore</code> contain any of the specified keys?
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1,b=&gt;2'::hstore ?| ARRAY['b','c']</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">@&gt;</code> <code class="type">hstore</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does left operand contain right?
+ </p>
+ <p>
+ <code class="literal">'a=&gt;b, b=&gt;1, c=&gt;NULL'::hstore @&gt; 'b=&gt;1'</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">&lt;@</code> <code class="type">hstore</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is left operand contained in right?
+ </p>
+ <p>
+ <code class="literal">'a=&gt;c'::hstore &lt;@ 'a=&gt;b, b=&gt;1, c=&gt;NULL'</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">-</code> <code class="type">text</code>
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes key from left operand.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1, b=&gt;2, c=&gt;3'::hstore - 'b'::text</code>
+ → <code class="returnvalue">"a"=&gt;"1", "c"=&gt;"3"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">-</code> <code class="type">text[]</code>
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes keys from left operand.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1, b=&gt;2, c=&gt;3'::hstore - ARRAY['a','b']</code>
+ → <code class="returnvalue">"c"=&gt;"3"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">hstore</code> <code class="literal">-</code> <code class="type">hstore</code>
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes pairs from left operand that match pairs in the right operand.
+ </p>
+ <p>
+ <code class="literal">'a=&gt;1, b=&gt;2, c=&gt;3'::hstore - 'a=&gt;4, b=&gt;2'::hstore</code>
+ → <code class="returnvalue">"a"=&gt;"1", "c"=&gt;"3"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">anyelement</code> <code class="literal">#=</code> <code class="type">hstore</code>
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Replaces fields in the left operand (which must be a composite type)
+ with matching values from <code class="type">hstore</code>.
+ </p>
+ <p>
+ <code class="literal">ROW(1,3) #= 'f1=&gt;11'::hstore</code>
+ → <code class="returnvalue">(11,3)</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">%%</code> <code class="type">hstore</code>
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Converts <code class="type">hstore</code> to an array of alternating keys and
+ values.
+ </p>
+ <p>
+ <code class="literal">%% 'a=&gt;foo, b=&gt;bar'::hstore</code>
+ → <code class="returnvalue">{a,foo,b,bar}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">%#</code> <code class="type">hstore</code>
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Converts <code class="type">hstore</code> to a two-dimensional key/value array.
+ </p>
+ <p>
+ <code class="literal">%# 'a=&gt;foo, b=&gt;bar'::hstore</code>
+ → <code class="returnvalue">{{a,foo},{b,bar}}</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="HSTORE-FUNC-TABLE"><p class="title"><strong>Table F.8. <code class="type">hstore</code> Functions</strong></p><div class="table-contents"><table class="table" summary="hstore Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">hstore</code> ( <code class="type">record</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Constructs an <code class="type">hstore</code> from a record or row.
+ </p>
+ <p>
+ <code class="literal">hstore(ROW(1,2))</code>
+ → <code class="returnvalue">"f1"=&gt;"1", "f2"=&gt;"2"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hstore</code> ( <code class="type">text[]</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Constructs an <code class="type">hstore</code> from an array, which may be either
+ a key/value array, or a two-dimensional array.
+ </p>
+ <p>
+ <code class="literal">hstore(ARRAY['a','1','b','2'])</code>
+ → <code class="returnvalue">"a"=&gt;"1", "b"=&gt;"2"</code>
+ </p>
+ <p>
+ <code class="literal">hstore(ARRAY[['c','3'],['d','4']])</code>
+ → <code class="returnvalue">"c"=&gt;"3", "d"=&gt;"4"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hstore</code> ( <code class="type">text[]</code>, <code class="type">text[]</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Constructs an <code class="type">hstore</code> from separate key and value arrays.
+ </p>
+ <p>
+ <code class="literal">hstore(ARRAY['a','b'], ARRAY['1','2'])</code>
+ → <code class="returnvalue">"a"=&gt;"1", "b"=&gt;"2"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hstore</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Makes a single-item <code class="type">hstore</code>.
+ </p>
+ <p>
+ <code class="literal">hstore('a', 'b')</code>
+ → <code class="returnvalue">"a"=&gt;"b"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">akeys</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s keys as an array.
+ </p>
+ <p>
+ <code class="literal">akeys('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue">{a,b}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">skeys</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s keys as a set.
+ </p>
+ <p>
+ <code class="literal">skeys('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+a
+b
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">avals</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s values as an array.
+ </p>
+ <p>
+ <code class="literal">avals('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue">{1,2}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">svals</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">setof text</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s values as a set.
+ </p>
+ <p>
+ <code class="literal">svals('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+1
+2
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_array</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s keys and values as an array of
+ alternating keys and values.
+ </p>
+ <p>
+ <code class="literal">hstore_to_array('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue">{a,1,b,2}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_matrix</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s keys and values as a two-dimensional
+ array.
+ </p>
+ <p>
+ <code class="literal">hstore_to_matrix('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue">{{a,1},{b,2}}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_json</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p>
+ Converts an <code class="type">hstore</code> to a <code class="type">json</code> value,
+ converting all non-null values to JSON strings.
+ </p>
+ <p>
+ This function is used implicitly when an <code class="type">hstore</code> value is
+ cast to <code class="type">json</code>.
+ </p>
+ <p>
+ <code class="literal">hstore_to_json('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</code>
+ → <code class="returnvalue">{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_jsonb</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Converts an <code class="type">hstore</code> to a <code class="type">jsonb</code> value,
+ converting all non-null values to JSON strings.
+ </p>
+ <p>
+ This function is used implicitly when an <code class="type">hstore</code> value is
+ cast to <code class="type">jsonb</code>.
+ </p>
+ <p>
+ <code class="literal">hstore_to_jsonb('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</code>
+ → <code class="returnvalue">{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_json_loose</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">json</code>
+ </p>
+ <p>
+ Converts an <code class="type">hstore</code> to a <code class="type">json</code> value, but
+ attempts to distinguish numerical and Boolean values so they are
+ unquoted in the JSON.
+ </p>
+ <p>
+ <code class="literal">hstore_to_json_loose('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</code>
+ → <code class="returnvalue">{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.14.1.1.1" class="indexterm"></a>
+ <code class="function">hstore_to_jsonb_loose</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">jsonb</code>
+ </p>
+ <p>
+ Converts an <code class="type">hstore</code> to a <code class="type">jsonb</code> value, but
+ attempts to distinguish numerical and Boolean values so they are
+ unquoted in the JSON.
+ </p>
+ <p>
+ <code class="literal">hstore_to_jsonb_loose('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</code>
+ → <code class="returnvalue">{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.15.1.1.1" class="indexterm"></a>
+ <code class="function">slice</code> ( <code class="type">hstore</code>, <code class="type">text[]</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Extracts a subset of an <code class="type">hstore</code> containing only the
+ specified keys.
+ </p>
+ <p>
+ <code class="literal">slice('a=&gt;1,b=&gt;2,c=&gt;3'::hstore, ARRAY['b','c','x'])</code>
+ → <code class="returnvalue">"b"=&gt;"2", "c"=&gt;"3"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.16.1.1.1" class="indexterm"></a>
+ <code class="function">each</code> ( <code class="type">hstore</code> )
+ → <code class="returnvalue">setof record</code>
+ ( <em class="parameter"><code>key</code></em> <code class="type">text</code>,
+ <em class="parameter"><code>value</code></em> <code class="type">text</code> )
+ </p>
+ <p>
+ Extracts an <code class="type">hstore</code>'s keys and values as a set of records.
+ </p>
+ <p>
+ <code class="literal">select * from each('a=&gt;1,b=&gt;2')</code>
+ → <code class="returnvalue"></code>
+</p><pre class="programlisting">
+ key | value
+-----+-------
+ a | 1
+ b | 2
+</pre><p>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.17.1.1.1" class="indexterm"></a>
+ <code class="function">exist</code> ( <code class="type">hstore</code>, <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">hstore</code> contain key?
+ </p>
+ <p>
+ <code class="literal">exist('a=&gt;1', 'a')</code>
+ → <code class="returnvalue">t</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.18.1.1.1" class="indexterm"></a>
+ <code class="function">defined</code> ( <code class="type">hstore</code>, <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">hstore</code> contain a non-<code class="literal">NULL</code> value
+ for key?
+ </p>
+ <p>
+ <code class="literal">defined('a=&gt;NULL', 'a')</code>
+ → <code class="returnvalue">f</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.19.1.1.1" class="indexterm"></a>
+ <code class="function">delete</code> ( <code class="type">hstore</code>, <code class="type">text</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes pair with matching key.
+ </p>
+ <p>
+ <code class="literal">delete('a=&gt;1,b=&gt;2', 'b')</code>
+ → <code class="returnvalue">"a"=&gt;"1"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">delete</code> ( <code class="type">hstore</code>, <code class="type">text[]</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes pairs with matching keys.
+ </p>
+ <p>
+ <code class="literal">delete('a=&gt;1,b=&gt;2,c=&gt;3', ARRAY['a','b'])</code>
+ → <code class="returnvalue">"c"=&gt;"3"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">delete</code> ( <code class="type">hstore</code>, <code class="type">hstore</code> )
+ → <code class="returnvalue">hstore</code>
+ </p>
+ <p>
+ Deletes pairs matching those in the second argument.
+ </p>
+ <p>
+ <code class="literal">delete('a=&gt;1,b=&gt;2', 'a=&gt;4,b=&gt;2'::hstore)</code>
+ → <code class="returnvalue">"a"=&gt;"1"</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.27.6.4.2.2.22.1.1.1" class="indexterm"></a>
+ <code class="function">populate_record</code> ( <code class="type">anyelement</code>, <code class="type">hstore</code> )
+ → <code class="returnvalue">anyelement</code>
+ </p>
+ <p>
+ Replaces fields in the left operand (which must be a composite type)
+ with matching values from <code class="type">hstore</code>.
+ </p>
+ <p>
+ <code class="literal">populate_record(ROW(1,2), 'f1=&gt;42'::hstore)</code>
+ → <code class="returnvalue">(42,2)</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In addition to these operators and functions, values of
+ the <code class="type">hstore</code> type can be subscripted, allowing them to act
+ like associative arrays. Only a single subscript of type <code class="type">text</code>
+ can be specified; it is interpreted as a key and the corresponding
+ value is fetched or stored. For example,
+
+</p><pre class="programlisting">
+CREATE TABLE mytable (h hstore);
+INSERT INTO mytable VALUES ('a=&gt;b, c=&gt;d');
+SELECT h['a'] FROM mytable;
+ h
+---
+ b
+(1 row)
+
+UPDATE mytable SET h['c'] = 'new';
+SELECT h FROM mytable;
+ h
+----------------------
+ "a"=&gt;"b", "c"=&gt;"new"
+(1 row)
+</pre><p>
+
+ A subscripted fetch returns <code class="literal">NULL</code> if the subscript
+ is <code class="literal">NULL</code> or that key does not exist in
+ the <code class="type">hstore</code>. (Thus, a subscripted fetch is not greatly
+ different from the <code class="literal">-&gt;</code> operator.)
+ A subscripted update fails if the subscript is <code class="literal">NULL</code>;
+ otherwise, it replaces the value for that key, adding an entry to
+ the <code class="type">hstore</code> if the key does not already exist.
+ </p></div><div class="sect2" id="id-1.11.7.27.7"><div class="titlepage"><div><div><h3 class="title">F.18.3. Indexes</h3></div></div></div><p>
+ <code class="type">hstore</code> has GiST and GIN index support for the <code class="literal">@&gt;</code>,
+ <code class="literal">?</code>, <code class="literal">?&amp;</code> and <code class="literal">?|</code> operators. For example:
+ </p><pre class="programlisting">
+CREATE INDEX hidx ON testhstore USING GIST (h);
+
+CREATE INDEX hidx ON testhstore USING GIN (h);
+</pre><p>
+ <code class="literal">gist_hstore_ops</code> GiST opclass approximates a set of
+ key/value pairs as a bitmap signature. Its optional integer parameter
+ <code class="literal">siglen</code> determines the
+ signature length in bytes. The default length is 16 bytes.
+ Valid values of signature length are between 1 and 2024 bytes. Longer
+ signatures lead to a more precise search (scanning a smaller fraction of the index and
+ fewer heap pages), at the cost of a larger index.
+ </p><p>
+ Example of creating such an index with a signature length of 32 bytes:
+</p><pre class="programlisting">
+CREATE INDEX hidx ON testhstore USING GIST (h gist_hstore_ops(siglen=32));
+</pre><p>
+ </p><p>
+ <code class="type">hstore</code> also supports <code class="type">btree</code> or <code class="type">hash</code> indexes for
+ the <code class="literal">=</code> operator. This allows <code class="type">hstore</code> columns to be
+ declared <code class="literal">UNIQUE</code>, or to be used in <code class="literal">GROUP BY</code>,
+ <code class="literal">ORDER BY</code> or <code class="literal">DISTINCT</code> expressions. The sort ordering
+ for <code class="type">hstore</code> values is not particularly useful, but these indexes
+ may be useful for equivalence lookups. Create indexes for <code class="literal">=</code>
+ comparisons as follows:
+ </p><pre class="programlisting">
+CREATE INDEX hidx ON testhstore USING BTREE (h);
+
+CREATE INDEX hidx ON testhstore USING HASH (h);
+</pre></div><div class="sect2" id="id-1.11.7.27.8"><div class="titlepage"><div><div><h3 class="title">F.18.4. Examples</h3></div></div></div><p>
+ Add a key, or update an existing key with a new value:
+</p><pre class="programlisting">
+UPDATE tab SET h['c'] = '3';
+</pre><p>
+ Another way to do the same thing is:
+</p><pre class="programlisting">
+UPDATE tab SET h = h || hstore('c', '3');
+</pre><p>
+ If multiple keys are to be added or changed in one operation,
+ the concatenation approach is more efficient than subscripting:
+</p><pre class="programlisting">
+UPDATE tab SET h = h || hstore(array['q', 'w'], array['11', '12']);
+</pre><p>
+ </p><p>
+ Delete a key:
+</p><pre class="programlisting">
+UPDATE tab SET h = delete(h, 'k1');
+</pre><p>
+ </p><p>
+ Convert a <code class="type">record</code> to an <code class="type">hstore</code>:
+</p><pre class="programlisting">
+CREATE TABLE test (col1 integer, col2 text, col3 text);
+INSERT INTO test VALUES (123, 'foo', 'bar');
+
+SELECT hstore(t) FROM test AS t;
+ hstore
+---------------------------------------------
+ "col1"=&gt;"123", "col2"=&gt;"foo", "col3"=&gt;"bar"
+(1 row)
+</pre><p>
+ </p><p>
+ Convert an <code class="type">hstore</code> to a predefined <code class="type">record</code> type:
+</p><pre class="programlisting">
+CREATE TABLE test (col1 integer, col2 text, col3 text);
+
+SELECT * FROM populate_record(null::test,
+ '"col1"=&gt;"456", "col2"=&gt;"zzz"');
+ col1 | col2 | col3
+------+------+------
+ 456 | zzz |
+(1 row)
+</pre><p>
+ </p><p>
+ Modify an existing record using the values from an <code class="type">hstore</code>:
+</p><pre class="programlisting">
+CREATE TABLE test (col1 integer, col2 text, col3 text);
+INSERT INTO test VALUES (123, 'foo', 'bar');
+
+SELECT (r).* FROM (SELECT t #= '"col3"=&gt;"baz"' AS r FROM test t) s;
+ col1 | col2 | col3
+------+------+------
+ 123 | foo | baz
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.27.9"><div class="titlepage"><div><div><h3 class="title">F.18.5. Statistics</h3></div></div></div><p>
+ The <code class="type">hstore</code> type, because of its intrinsic liberality, could
+ contain a lot of different keys. Checking for valid keys is the task of the
+ application. The following examples demonstrate several techniques for
+ checking keys and obtaining statistics.
+ </p><p>
+ Simple example:
+</p><pre class="programlisting">
+SELECT * FROM each('aaa=&gt;bq, b=&gt;NULL, ""=&gt;1');
+</pre><p>
+ </p><p>
+ Using a table:
+</p><pre class="programlisting">
+CREATE TABLE stat AS SELECT (each(h)).key, (each(h)).value FROM testhstore;
+</pre><p>
+ </p><p>
+ Online statistics:
+</p><pre class="programlisting">
+SELECT key, count(*) FROM
+ (SELECT (each(h)).key FROM testhstore) AS stat
+ GROUP BY key
+ ORDER BY count DESC, key;
+ key | count
+-----------+-------
+ line | 883
+ query | 207
+ pos | 203
+ node | 202
+ space | 197
+ status | 195
+ public | 194
+ title | 190
+ org | 189
+...................
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.27.10"><div class="titlepage"><div><div><h3 class="title">F.18.6. Compatibility</h3></div></div></div><p>
+ As of PostgreSQL 9.0, <code class="type">hstore</code> uses a different internal
+ representation than previous versions. This presents no obstacle for
+ dump/restore upgrades since the text representation (used in the dump) is
+ unchanged.
+ </p><p>
+ In the event of a binary upgrade, upward compatibility is maintained by
+ having the new code recognize old-format data. This will entail a slight
+ performance penalty when processing data that has not yet been modified by
+ the new code. It is possible to force an upgrade of all values in a table
+ column by doing an <code class="literal">UPDATE</code> statement as follows:
+</p><pre class="programlisting">
+UPDATE tablename SET hstorecol = hstorecol || '';
+</pre><p>
+ </p><p>
+ Another way to do it is:
+</p><pre class="programlisting">
+ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
+</pre><p>
+ The <code class="command">ALTER TABLE</code> method requires an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the table,
+ but does not result in bloating the table with old row versions.
+ </p></div><div class="sect2" id="id-1.11.7.27.11"><div class="titlepage"><div><div><h3 class="title">F.18.7. Transforms</h3></div></div></div><p>
+ Additional extensions are available that implement transforms for
+ the <code class="type">hstore</code> type for the languages PL/Perl and PL/Python. The
+ extensions for PL/Perl are called <code class="literal">hstore_plperl</code>
+ and <code class="literal">hstore_plperlu</code>, for trusted and untrusted PL/Perl.
+ If you install these transforms and specify them when creating a
+ function, <code class="type">hstore</code> values are mapped to Perl hashes. The
+ extension for PL/Python is called <code class="literal">hstore_plpython3u</code>.
+ If you use it, <code class="type">hstore</code> values are mapped to Python dictionaries.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is strongly recommended that the transform extensions be installed in
+ the same schema as <code class="filename">hstore</code>. Otherwise there are
+ installation-time security hazards if a transform extension's schema
+ contains objects defined by a hostile user.
+ </p></div></div><div class="sect2" id="id-1.11.7.27.12"><div class="titlepage"><div><div><h3 class="title">F.18.8. Authors</h3></div></div></div><p>
+ Oleg Bartunov <code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>, Moscow, Moscow University, Russia
+ </p><p>
+ Teodor Sigaev <code class="email">&lt;<a class="email" href="mailto:teodor@sigaev.ru">teodor@sigaev.ru</a>&gt;</code>, Moscow, Delta-Soft Ltd., Russia
+ </p><p>
+ Additional enhancements by Andrew Gierth <code class="email">&lt;<a class="email" href="mailto:andrew@tao11.riddles.org.uk">andrew@tao11.riddles.org.uk</a>&gt;</code>,
+ United Kingdom
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fuzzystrmatch.html" title="F.17. fuzzystrmatch">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="intagg.html" title="F.19. intagg">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.17. fuzzystrmatch </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.19. intagg</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-api.html b/doc/src/sgml/html/index-api.html
new file mode 100644
index 0000000..a6bd971
--- /dev/null
+++ b/doc/src/sgml/html/index-api.html
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.1. Basic API Structure for Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition" /><link rel="next" href="index-functions.html" title="64.2. Index Access Method Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.1. Basic API Structure for Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-functions.html" title="64.2. Index Access Method Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-API"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.1. Basic API Structure for Indexes</h2></div></div></div><p>
+ Each index access method is described by a row in the
+ <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>
+ system catalog. The <code class="structname">pg_am</code> entry
+ specifies a name and a <em class="firstterm">handler function</em> for the index
+ access method. These entries can be created and deleted using the
+ <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and
+ <a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a> SQL commands.
+ </p><p>
+ An index access method handler function must be declared to accept a
+ single argument of type <code class="type">internal</code> and to return the
+ pseudo-type <code class="type">index_am_handler</code>. The argument is a dummy value that
+ simply serves to prevent handler functions from being called directly from
+ SQL commands. The result of the function must be a palloc'd struct of
+ type <code class="structname">IndexAmRoutine</code>, which contains everything
+ that the core code needs to know to make use of the index access method.
+ The <code class="structname">IndexAmRoutine</code> struct, also called the access
+ method's <em class="firstterm">API struct</em>, includes fields specifying assorted
+ fixed properties of the access method, such as whether it can support
+ multicolumn indexes. More importantly, it contains pointers to support
+ 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 <a class="xref" href="index-functions.html" title="64.2. Index Access Method Functions">Section 64.2</a>.
+ </p><p>
+ The structure <code class="structname">IndexAmRoutine</code> is defined thus:
+</p><pre class="programlisting">
+typedef struct IndexAmRoutine
+{
+ NodeTag type;
+
+ /*
+ * Total number of strategies (operators) by which we can traverse/search
+ * this AM. Zero if AM does not have a fixed set of strategy assignments.
+ */
+ uint16 amstrategies;
+ /* total number of support functions that this AM uses */
+ uint16 amsupport;
+ /* opclass options support function number or 0 */
+ uint16 amoptsprocnum;
+ /* does AM support ORDER BY indexed column's value? */
+ bool amcanorder;
+ /* does AM support ORDER BY result of an operator on indexed column? */
+ bool amcanorderbyop;
+ /* does AM support backward scanning? */
+ bool amcanbackward;
+ /* does AM support UNIQUE indexes? */
+ bool amcanunique;
+ /* does AM support multi-column indexes? */
+ bool amcanmulticol;
+ /* does AM require scans to have a constraint on the first index column? */
+ bool amoptionalkey;
+ /* does AM handle ScalarArrayOpExpr quals? */
+ bool amsearcharray;
+ /* does AM handle IS NULL/IS NOT NULL quals? */
+ bool amsearchnulls;
+ /* can index storage data type differ from column data type? */
+ bool amstorage;
+ /* can an index of this type be clustered on? */
+ bool amclusterable;
+ /* does AM handle predicate locks? */
+ bool ampredlocks;
+ /* does AM support parallel scan? */
+ bool amcanparallel;
+ /* does AM support columns included with clause INCLUDE? */
+ bool amcaninclude;
+ /* does AM use maintenance_work_mem? */
+ bool amusemaintenanceworkmem;
+ /* OR of parallel vacuum flags */
+ uint8 amparallelvacuumoptions;
+ /* type of data stored in index, or InvalidOid if variable */
+ Oid amkeytype;
+
+ /* interface functions */
+ ambuild_function ambuild;
+ ambuildempty_function ambuildempty;
+ aminsert_function aminsert;
+ ambulkdelete_function ambulkdelete;
+ amvacuumcleanup_function amvacuumcleanup;
+ amcanreturn_function amcanreturn; /* can be NULL */
+ amcostestimate_function amcostestimate;
+ amoptions_function amoptions;
+ amproperty_function amproperty; /* can be NULL */
+ ambuildphasename_function ambuildphasename; /* can be NULL */
+ amvalidate_function amvalidate;
+ amadjustmembers_function amadjustmembers; /* can be NULL */
+ ambeginscan_function ambeginscan;
+ amrescan_function amrescan;
+ amgettuple_function amgettuple; /* can be NULL */
+ amgetbitmap_function amgetbitmap; /* can be NULL */
+ amendscan_function amendscan;
+ ammarkpos_function ammarkpos; /* can be NULL */
+ amrestrpos_function amrestrpos; /* can be NULL */
+
+ /* interface functions to support parallel index scans */
+ amestimateparallelscan_function amestimateparallelscan; /* can be NULL */
+ aminitparallelscan_function aminitparallelscan; /* can be NULL */
+ amparallelrescan_function amparallelrescan; /* can be NULL */
+} IndexAmRoutine;
+</pre><p>
+ </p><p>
+ To be useful, an index access method must also have one or more
+ <em class="firstterm">operator families</em> and
+ <em class="firstterm">operator classes</em> defined in
+ <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>,
+ <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>,
+ <a class="link" href="catalog-pg-amop.html" title="53.4. pg_amop"><code class="structname">pg_amop</code></a>, and
+ <a class="link" href="catalog-pg-amproc.html" title="53.5. pg_amproc"><code class="structname">pg_amproc</code></a>.
+ 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 <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>, which is prerequisite material for reading
+ this chapter.
+ </p><p>
+ An individual index is defined by a
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>
+ entry that describes it as a physical relation, plus a
+ <a class="link" href="catalog-pg-index.html" title="53.26. pg_index"><code class="structname">pg_index</code></a>
+ entry that shows the logical content of the index — that is, the set
+ of index columns it has and the semantics of those columns, as captured by
+ the associated operator classes. The index columns (key values) can be
+ either simple columns of the underlying table or expressions over the table
+ rows. The index access method normally has no interest in where the index
+ key values come from (it is always handed precomputed key values) but it
+ will be very interested in the operator class information in
+ <code class="structname">pg_index</code>. Both of these catalog entries can be
+ accessed as part of the <code class="structname">Relation</code> data structure that is
+ passed to all operations on the index.
+ </p><p>
+ Some of the flag fields of <code class="structname">IndexAmRoutine</code> have nonobvious
+ implications. The requirements of <code class="structfield">amcanunique</code>
+ are discussed in <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a>.
+ The <code class="structfield">amcanmulticol</code> flag asserts that the
+ access method supports multi-key-column indexes, while
+ <code class="structfield">amoptionalkey</code> asserts that it allows scans
+ where no indexable restriction clause is given for the first index column.
+ When <code class="structfield">amcanmulticol</code> is false,
+ <code class="structfield">amoptionalkey</code> essentially says whether the
+ access method supports full-index scans without any restriction clause.
+ Access methods that support multiple index columns <span class="emphasis"><em>must</em></span>
+ support scans that omit restrictions on any or all of the columns after
+ the first; however they are permitted to require some restriction to
+ appear for the first index column, and this is signaled by setting
+ <code class="structfield">amoptionalkey</code> false.
+ One reason that an index AM might set
+ <code class="structfield">amoptionalkey</code> false is if it doesn't index
+ null values. Since most indexable operators are
+ strict and hence cannot return true for null inputs,
+ it is at first sight attractive to not store index entries for null values:
+ they could never be returned by an index scan anyway. However, this
+ argument fails when an index scan has no restriction clause for a given
+ index column. In practice this means that
+ indexes that have <code class="structfield">amoptionalkey</code> true must
+ index nulls, since the planner might decide to use such an index
+ with no scan keys at all. A related restriction is that an index
+ access method that supports multiple index columns <span class="emphasis"><em>must</em></span>
+ support indexing null values in columns after the first, because the planner
+ will assume the index can be used for queries that do not restrict
+ these columns. For example, consider an index on (a,b) and a query with
+ <code class="literal">WHERE a = 4</code>. The system will assume the index can be
+ used to scan for rows with <code class="literal">a = 4</code>, which is wrong if the
+ index omits rows where <code class="literal">b</code> is null.
+ It is, however, OK to omit rows where the first indexed column is null.
+ An index access method that does index nulls may also set
+ <code class="structfield">amsearchnulls</code>, indicating that it supports
+ <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> clauses as search
+ conditions.
+ </p><p>
+ The <code class="structfield">amcaninclude</code> flag indicates whether the
+ access method supports <span class="quote">“<span class="quote">included</span>”</span> columns, that is it can
+ store (without processing) additional columns beyond the key column(s).
+ The requirements of the preceding paragraph apply only to the key
+ columns. In particular, the combination
+ of <code class="structfield">amcanmulticol</code>=<code class="literal">false</code>
+ and <code class="structfield">amcaninclude</code>=<code class="literal">true</code> is
+ sensible: it means that there can only be one key column, but there can
+ also be included column(s). Also, included columns must be allowed to be
+ null, independently of <code class="structfield">amoptionalkey</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-functions.html" title="64.2. Index Access Method Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 64. Index Access Method Interface Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.2. Index Access Method Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-cost-estimation.html b/doc/src/sgml/html/index-cost-estimation.html
new file mode 100644
index 0000000..fe706e8
--- /dev/null
+++ b/doc/src/sgml/html/index-cost-estimation.html
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.6. Index Cost Estimation Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks" /><link rel="next" href="generic-wal.html" title="Chapter 65. Generic WAL Records" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.6. Index Cost Estimation Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-COST-ESTIMATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.6. Index Cost Estimation Functions</h2></div></div></div><p>
+ The <code class="function">amcostestimate</code> function is given information describing
+ a possible index scan, including lists of WHERE and ORDER BY clauses that
+ have been determined to be usable with the index. It must return estimates
+ of the cost of accessing the index and the selectivity of the WHERE
+ clauses (that is, the fraction of parent-table rows that will be
+ retrieved during the index scan). For simple cases, nearly all the
+ work of the cost estimator can be done by calling standard routines
+ in the optimizer; the point of having an <code class="function">amcostestimate</code> function is
+ to allow index access methods to provide index-type-specific knowledge,
+ in case it is possible to improve on the standard estimates.
+ </p><p>
+ Each <code class="function">amcostestimate</code> function must have the signature:
+
+</p><pre class="programlisting">
+void
+amcostestimate (PlannerInfo *root,
+ IndexPath *path,
+ double loop_count,
+ Cost *indexStartupCost,
+ Cost *indexTotalCost,
+ Selectivity *indexSelectivity,
+ double *indexCorrelation,
+ double *indexPages);
+</pre><p>
+
+ The first three parameters are inputs:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>root</code></em></span></dt><dd><p>
+ The planner's information about the query being processed.
+ </p></dd><dt><span class="term"><em class="parameter"><code>path</code></em></span></dt><dd><p>
+ The index access path being considered. All fields except cost and
+ selectivity values are valid.
+ </p></dd><dt><span class="term"><em class="parameter"><code>loop_count</code></em></span></dt><dd><p>
+ The number of repetitions of the index scan that should be factored
+ into the cost estimates. This will typically be greater than one when
+ considering a parameterized scan for use in the inside of a nestloop
+ join. Note that the cost estimates should still be for just one scan;
+ a larger <em class="parameter"><code>loop_count</code></em> means that it may be appropriate
+ to allow for some caching effects across multiple scans.
+ </p></dd></dl></div><p>
+ </p><p>
+ The last five parameters are pass-by-reference outputs:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>*indexStartupCost</code></em></span></dt><dd><p>
+ Set to cost of index start-up processing
+ </p></dd><dt><span class="term"><em class="parameter"><code>*indexTotalCost</code></em></span></dt><dd><p>
+ Set to total cost of index processing
+ </p></dd><dt><span class="term"><em class="parameter"><code>*indexSelectivity</code></em></span></dt><dd><p>
+ Set to index selectivity
+ </p></dd><dt><span class="term"><em class="parameter"><code>*indexCorrelation</code></em></span></dt><dd><p>
+ Set to correlation coefficient between index scan order and
+ underlying table's order
+ </p></dd><dt><span class="term"><em class="parameter"><code>*indexPages</code></em></span></dt><dd><p>
+ Set to number of index leaf pages
+ </p></dd></dl></div><p>
+ </p><p>
+ Note that cost estimate functions must be written in C, not in SQL or
+ any available procedural language, because they must access internal
+ data structures of the planner/optimizer.
+ </p><p>
+ The index access costs should be computed using the parameters used by
+ <code class="filename">src/backend/optimizer/path/costsize.c</code>: a sequential
+ disk block fetch has cost <code class="varname">seq_page_cost</code>, a nonsequential fetch
+ has cost <code class="varname">random_page_cost</code>, and the cost of processing one index
+ row should usually be taken as <code class="varname">cpu_index_tuple_cost</code>. In
+ addition, an appropriate multiple of <code class="varname">cpu_operator_cost</code> should
+ be charged for any comparison operators invoked during index processing
+ (especially evaluation of the indexquals themselves).
+ </p><p>
+ The access costs should include all disk and CPU costs associated with
+ scanning the index itself, but <span class="emphasis"><em>not</em></span> the costs of retrieving or
+ processing the parent-table rows that are identified by the index.
+ </p><p>
+ The <span class="quote">“<span class="quote">start-up cost</span>”</span> is the part of the total scan cost that
+ must be expended before we can begin to fetch the first row. For most
+ indexes this can be taken as zero, but an index type with a high start-up
+ cost might want to set it nonzero.
+ </p><p>
+ The <em class="parameter"><code>indexSelectivity</code></em> should be set to the estimated fraction of the parent
+ table rows that will be retrieved during the index scan. In the case
+ of a lossy query, this will typically be higher than the fraction of
+ rows that actually pass the given qual conditions.
+ </p><p>
+ The <em class="parameter"><code>indexCorrelation</code></em> should be set to the correlation (ranging between
+ -1.0 and 1.0) between the index order and the table order. This is used
+ to adjust the estimate for the cost of fetching rows from the parent
+ table.
+ </p><p>
+ The <em class="parameter"><code>indexPages</code></em> should be set to the number of leaf pages.
+ This is used to estimate the number of workers for parallel index scan.
+ </p><p>
+ When <em class="parameter"><code>loop_count</code></em> is greater than one, the returned numbers
+ should be averages expected for any one scan of the index.
+ </p><div class="procedure" id="id-1.10.15.12.13"><p class="title"><strong>Cost Estimation</strong></p><p>
+ A typical cost estimator will proceed as follows:
+ </p><ol class="procedure" type="1"><li class="step"><p>
+ Estimate and return the fraction of parent-table rows that will be visited
+ based on the given qual conditions. In the absence of any index-type-specific
+ knowledge, use the standard optimizer function <code class="function">clauselist_selectivity()</code>:
+
+</p><pre class="programlisting">
+*indexSelectivity = clauselist_selectivity(root, path-&gt;indexquals,
+ path-&gt;indexinfo-&gt;rel-&gt;relid,
+ JOIN_INNER, NULL);
+</pre><p>
+ </p></li><li class="step"><p>
+ Estimate the number of index rows that will be visited during the
+ scan. For many index types this is the same as <em class="parameter"><code>indexSelectivity</code></em> times
+ the number of rows in the index, but it might be more. (Note that the
+ index's size in pages and rows is available from the
+ <code class="literal">path-&gt;indexinfo</code> struct.)
+ </p></li><li class="step"><p>
+ Estimate the number of index pages that will be retrieved during the scan.
+ This might be just <em class="parameter"><code>indexSelectivity</code></em> times the index's size in pages.
+ </p></li><li class="step"><p>
+ Compute the index access cost. A generic estimator might do this:
+
+</p><pre class="programlisting">
+/*
+ * Our generic assumption is that the index pages will be read
+ * sequentially, so they cost seq_page_cost each, not random_page_cost.
+ * Also, we charge for evaluation of the indexquals at each index row.
+ * All the costs are assumed to be paid incrementally during the scan.
+ */
+cost_qual_eval(&amp;index_qual_cost, path-&gt;indexquals, root);
+*indexStartupCost = index_qual_cost.startup;
+*indexTotalCost = seq_page_cost * numIndexPages +
+ (cpu_index_tuple_cost + index_qual_cost.per_tuple) * numIndexTuples;
+</pre><p>
+
+ However, the above does not account for amortization of index reads
+ across repeated index scans.
+ </p></li><li class="step"><p>
+ Estimate the index correlation. For a simple ordered index on a single
+ field, this can be retrieved from pg_statistic. If the correlation
+ is not known, the conservative estimate is zero (no correlation).
+ </p></li></ol></div><p>
+ Examples of cost estimator functions can be found in
+ <code class="filename">src/backend/utils/adt/selfuncs.c</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.5. Index Uniqueness Checks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 65. Generic WAL Records</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-functions.html b/doc/src/sgml/html/index-functions.html
new file mode 100644
index 0000000..8e748fc
--- /dev/null
+++ b/doc/src/sgml/html/index-functions.html
@@ -0,0 +1,487 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.2. Index Access Method Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-api.html" title="64.1. Basic API Structure for Indexes" /><link rel="next" href="index-scanning.html" title="64.3. Index Scanning" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.2. Index Access Method Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-api.html" title="64.1. Basic API Structure for Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-scanning.html" title="64.3. Index Scanning">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.2. Index Access Method Functions</h2></div></div></div><p>
+ The index construction and maintenance functions that an index access
+ method must provide in <code class="structname">IndexAmRoutine</code> are:
+ </p><p>
+</p><pre class="programlisting">
+IndexBuildResult *
+ambuild (Relation heapRelation,
+ Relation indexRelation,
+ IndexInfo *indexInfo);
+</pre><p>
+ Build a new index. The index relation has been physically created,
+ but is empty. It must be filled in with whatever fixed data the
+ access method requires, plus entries for all tuples already existing
+ in the table. Ordinarily the <code class="function">ambuild</code> function will call
+ <code class="function">table_index_build_scan()</code> to scan the table for existing tuples
+ and compute the keys that need to be inserted into the index.
+ The function must return a palloc'd struct containing statistics about
+ the new index.
+ </p><p>
+</p><pre class="programlisting">
+void
+ambuildempty (Relation indexRelation);
+</pre><p>
+ Build an empty index, and write it to the initialization fork (<code class="symbol">INIT_FORKNUM</code>)
+ of the given relation. This method is called only for unlogged indexes; the
+ empty index written to the initialization fork will be copied over the main
+ relation fork on each server restart.
+ </p><p>
+</p><pre class="programlisting">
+bool
+aminsert (Relation indexRelation,
+ Datum *values,
+ bool *isnull,
+ ItemPointer heap_tid,
+ Relation heapRelation,
+ IndexUniqueCheck checkUnique,
+ bool indexUnchanged,
+ IndexInfo *indexInfo);
+</pre><p>
+ Insert a new tuple into an existing index. The <code class="literal">values</code> and
+ <code class="literal">isnull</code> arrays give the key values to be indexed, and
+ <code class="literal">heap_tid</code> is the TID to be indexed.
+ If the access method supports unique indexes (its
+ <code class="structfield">amcanunique</code> flag is true) then
+ <code class="literal">checkUnique</code> indicates the type of uniqueness check to
+ perform. This varies depending on whether the unique constraint is
+ deferrable; see <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a> for details.
+ Normally the access method only needs the <code class="literal">heapRelation</code>
+ parameter when performing uniqueness checking (since then it will have to
+ look into the heap to verify tuple liveness).
+ </p><p>
+ The <code class="literal">indexUnchanged</code> Boolean value gives a hint
+ about the nature of the tuple to be indexed. When it is true,
+ the tuple is a duplicate of some existing tuple in the index. The
+ new tuple is a logically unchanged successor MVCC tuple version. This
+ happens when an <code class="command">UPDATE</code> takes place that does not
+ modify any columns covered by the index, but nevertheless requires a
+ new version in the index. The index AM may use this hint to decide
+ to apply bottom-up index deletion in parts of the index where many
+ versions of the same logical row accumulate. Note that updating a non-key
+ column or a column that only appears in a partial index predicate does not
+ affect the value of <code class="literal">indexUnchanged</code>. The core code
+ determines each tuple's <code class="literal">indexUnchanged</code> value using a low
+ overhead approach that allows both false positives and false negatives.
+ Index AMs must not treat <code class="literal">indexUnchanged</code> as an
+ authoritative source of information about tuple visibility or versioning.
+ </p><p>
+ The function's Boolean result value is significant only when
+ <code class="literal">checkUnique</code> is <code class="literal">UNIQUE_CHECK_PARTIAL</code>.
+ In this case a true result means the new entry is known unique, whereas
+ false means it might be non-unique (and a deferred uniqueness check must
+ be scheduled). For other cases a constant false result is recommended.
+ </p><p>
+ Some indexes might not index all tuples. If the tuple is not to be
+ indexed, <code class="function">aminsert</code> should just return without doing anything.
+ </p><p>
+ If the index AM wishes to cache data across successive index insertions
+ within an SQL statement, it can allocate space
+ in <code class="literal">indexInfo-&gt;ii_Context</code> and store a pointer to the
+ data in <code class="literal">indexInfo-&gt;ii_AmCache</code> (which will be NULL
+ initially).
+ </p><p>
+</p><pre class="programlisting">
+IndexBulkDeleteResult *
+ambulkdelete (IndexVacuumInfo *info,
+ IndexBulkDeleteResult *stats,
+ IndexBulkDeleteCallback callback,
+ void *callback_state);
+</pre><p>
+ Delete tuple(s) from the index. This is a <span class="quote">“<span class="quote">bulk delete</span>”</span> operation
+ that is intended to be implemented by scanning the whole index and checking
+ each entry to see if it should be deleted.
+ The passed-in <code class="literal">callback</code> function must be called, in the style
+ <code class="literal">callback(<em class="replaceable"><code>TID</code></em>, callback_state) returns bool</code>,
+ to determine whether any particular index entry, as identified by its
+ referenced TID, is to be deleted. Must return either NULL or a palloc'd
+ struct containing statistics about the effects of the deletion operation.
+ It is OK to return NULL if no information needs to be passed on to
+ <code class="function">amvacuumcleanup</code>.
+ </p><p>
+ Because of limited <code class="varname">maintenance_work_mem</code>,
+ <code class="function">ambulkdelete</code> might need to be called more than once when many
+ tuples are to be deleted. The <code class="literal">stats</code> argument is the result
+ of the previous call for this index (it is NULL for the first call within a
+ <code class="command">VACUUM</code> operation). This allows the AM to accumulate statistics
+ across the whole operation. Typically, <code class="function">ambulkdelete</code> will
+ modify and return the same struct if the passed <code class="literal">stats</code> is not
+ null.
+ </p><p>
+</p><pre class="programlisting">
+IndexBulkDeleteResult *
+amvacuumcleanup (IndexVacuumInfo *info,
+ IndexBulkDeleteResult *stats);
+</pre><p>
+ Clean up after a <code class="command">VACUUM</code> operation (zero or more
+ <code class="function">ambulkdelete</code> calls). This does not have to do anything
+ beyond returning index statistics, but it might perform bulk cleanup
+ such as reclaiming empty index pages. <code class="literal">stats</code> is whatever the
+ last <code class="function">ambulkdelete</code> call returned, or NULL if
+ <code class="function">ambulkdelete</code> was not called because no tuples needed to be
+ deleted. If the result is not NULL it must be a palloc'd struct.
+ The statistics it contains will be used to update <code class="structname">pg_class</code>,
+ and will be reported by <code class="command">VACUUM</code> if <code class="literal">VERBOSE</code> is given.
+ It is OK to return NULL if the index was not changed at all during the
+ <code class="command">VACUUM</code> operation, but otherwise correct stats should
+ be returned.
+ </p><p>
+ <code class="function">amvacuumcleanup</code> will also be called at completion of an
+ <code class="command">ANALYZE</code> operation. In this case <code class="literal">stats</code> is always
+ NULL and any return value will be ignored. This case can be distinguished
+ by checking <code class="literal">info-&gt;analyze_only</code>. It is recommended
+ that the access method do nothing except post-insert cleanup in such a
+ call, and that only in an autovacuum worker process.
+ </p><p>
+</p><pre class="programlisting">
+bool
+amcanreturn (Relation indexRelation, int attno);
+</pre><p>
+ Check whether the index can support <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes"><em class="firstterm">index-only scans</em></a> on
+ the given column, by returning the column's original indexed value.
+ The attribute number is 1-based, i.e., the first column's attno is 1.
+ Returns true if supported, else false.
+ This function should always return true for included columns
+ (if those are supported), since there's little point in an included
+ column that can't be retrieved.
+ If the access method does not support index-only scans at all,
+ the <code class="structfield">amcanreturn</code> field in its <code class="structname">IndexAmRoutine</code>
+ struct can be set to NULL.
+ </p><p>
+</p><pre class="programlisting">
+void
+amcostestimate (PlannerInfo *root,
+ IndexPath *path,
+ double loop_count,
+ Cost *indexStartupCost,
+ Cost *indexTotalCost,
+ Selectivity *indexSelectivity,
+ double *indexCorrelation,
+ double *indexPages);
+</pre><p>
+ Estimate the costs of an index scan. This function is described fully
+ in <a class="xref" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Section 64.6</a>, below.
+ </p><p>
+</p><pre class="programlisting">
+bytea *
+amoptions (ArrayType *reloptions,
+ bool validate);
+</pre><p>
+ Parse and validate the reloptions array for an index. This is called only
+ when a non-null reloptions array exists for the index.
+ <em class="parameter"><code>reloptions</code></em> is a <code class="type">text</code> array containing entries of the
+ form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em>.
+ The function should construct a <code class="type">bytea</code> value, which will be copied
+ into the <code class="structfield">rd_options</code> field of the index's relcache entry.
+ The data contents of the <code class="type">bytea</code> value are open for the access
+ method to define; most of the standard access methods use struct
+ <code class="structname">StdRdOptions</code>.
+ When <em class="parameter"><code>validate</code></em> is true, the function should report a suitable
+ error message if any of the options are unrecognized or have invalid
+ values; when <em class="parameter"><code>validate</code></em> is false, invalid entries should be
+ silently ignored. (<em class="parameter"><code>validate</code></em> is false when loading options
+ already stored in <code class="structname">pg_catalog</code>; an invalid entry could only
+ be found if the access method has changed its rules for options, and in
+ that case ignoring obsolete entries is appropriate.)
+ It is OK to return NULL if default behavior is wanted.
+ </p><p>
+</p><pre class="programlisting">
+bool
+amproperty (Oid index_oid, int attno,
+ IndexAMProperty prop, const char *propname,
+ bool *res, bool *isnull);
+</pre><p>
+ The <code class="function">amproperty</code> method allows index access methods to override
+ the default behavior of <code class="function">pg_index_column_has_property</code>
+ and related functions.
+ If the access method does not have any special behavior for index property
+ inquiries, the <code class="structfield">amproperty</code> field in
+ its <code class="structname">IndexAmRoutine</code> struct can be set to NULL.
+ Otherwise, the <code class="function">amproperty</code> method will be called with
+ <em class="parameter"><code>index_oid</code></em> and <em class="parameter"><code>attno</code></em> both zero for
+ <code class="function">pg_indexam_has_property</code> calls,
+ or with <em class="parameter"><code>index_oid</code></em> valid and <em class="parameter"><code>attno</code></em> zero for
+ <code class="function">pg_index_has_property</code> calls,
+ or with <em class="parameter"><code>index_oid</code></em> valid and <em class="parameter"><code>attno</code></em> greater than
+ zero for <code class="function">pg_index_column_has_property</code> calls.
+ <em class="parameter"><code>prop</code></em> is an enum value identifying the property being tested,
+ while <em class="parameter"><code>propname</code></em> is the original property name string.
+ If the core code does not recognize the property name
+ then <em class="parameter"><code>prop</code></em> is <code class="literal">AMPROP_UNKNOWN</code>.
+ Access methods can define custom property names by
+ checking <em class="parameter"><code>propname</code></em> for a match (use <code class="function">pg_strcasecmp</code>
+ to match, for consistency with the core code); for names known to the core
+ code, it's better to inspect <em class="parameter"><code>prop</code></em>.
+ If the <code class="structfield">amproperty</code> method returns <code class="literal">true</code> then
+ it has determined the property test result: it must set <code class="literal">*res</code>
+ to the Boolean value to return, or set <code class="literal">*isnull</code>
+ to <code class="literal">true</code> to return a NULL. (Both of the referenced variables
+ are initialized to <code class="literal">false</code> before the call.)
+ If the <code class="structfield">amproperty</code> method returns <code class="literal">false</code> then
+ the core code will proceed with its normal logic for determining the
+ property test result.
+ </p><p>
+ Access methods that support ordering operators should
+ implement <code class="literal">AMPROP_DISTANCE_ORDERABLE</code> property testing, as the
+ core code does not know how to do that and will return NULL. It may
+ also be advantageous to implement <code class="literal">AMPROP_RETURNABLE</code> testing,
+ if that can be done more cheaply than by opening the index and calling
+ <code class="function">amcanreturn</code>, which is the core code's default behavior.
+ The default behavior should be satisfactory for all other standard
+ properties.
+ </p><p>
+</p><pre class="programlisting">
+char *
+ambuildphasename (int64 phasenum);
+</pre><p>
+ Return the textual name of the given build phase number.
+ The phase numbers are those reported during an index build via the
+ <code class="function">pgstat_progress_update_param</code> interface.
+ The phase names are then exposed in the
+ <code class="structname">pg_stat_progress_create_index</code> view.
+ </p><p>
+</p><pre class="programlisting">
+bool
+amvalidate (Oid opclassoid);
+</pre><p>
+ Validate the catalog entries for the specified operator class, so far as
+ the access method can reasonably do that. For example, this might include
+ testing that all required support functions are provided.
+ The <code class="function">amvalidate</code> function must return false if the opclass is
+ invalid. Problems should be reported with <code class="function">ereport</code>
+ messages, typically at <code class="literal">INFO</code> level.
+ </p><p>
+</p><pre class="programlisting">
+void
+amadjustmembers (Oid opfamilyoid,
+ Oid opclassoid,
+ List *operators,
+ List *functions);
+</pre><p>
+ Validate proposed new operator and function members of an operator family,
+ so far as the access method can reasonably do that, and set their
+ dependency types if the default is not satisfactory. This is called
+ during <code class="command">CREATE OPERATOR CLASS</code> and during
+ <code class="command">ALTER OPERATOR FAMILY ADD</code>; in the latter
+ case <em class="parameter"><code>opclassoid</code></em> is <code class="literal">InvalidOid</code>.
+ The <code class="type">List</code> arguments are lists
+ of <code class="structname">OpFamilyMember</code> structs, as defined
+ in <code class="filename">amapi.h</code>.
+
+ Tests done by this function will typically be a subset of those
+ performed by <code class="function">amvalidate</code>,
+ since <code class="function">amadjustmembers</code> cannot assume that it is
+ seeing a complete set of members. For example, it would be reasonable
+ to check the signature of a support function, but not to check whether
+ all required support functions are provided. Any problems can be
+ reported by throwing an error.
+
+ The dependency-related fields of
+ the <code class="structname">OpFamilyMember</code> structs are initialized by
+ the core code to create hard dependencies on the opclass if this
+ is <code class="command">CREATE OPERATOR CLASS</code>, or soft dependencies on the
+ opfamily if this is <code class="command">ALTER OPERATOR FAMILY ADD</code>.
+ <code class="function">amadjustmembers</code> can adjust these fields if some other
+ behavior is more appropriate. For example, GIN, GiST, and SP-GiST
+ always set operator members to have soft dependencies on the opfamily,
+ since the connection between an operator and an opclass is relatively
+ weak in these index types; so it is reasonable to allow operator members
+ to be added and removed freely. Optional support functions are typically
+ also given soft dependencies, so that they can be removed if necessary.
+ </p><p>
+ The purpose of an index, of course, is to support scans for tuples matching
+ an indexable <code class="literal">WHERE</code> condition, often called a
+ <em class="firstterm">qualifier</em> or <em class="firstterm">scan key</em>. The semantics of
+ index scanning are described more fully in <a class="xref" href="index-scanning.html" title="64.3. Index Scanning">Section 64.3</a>,
+ below. An index access method can support <span class="quote">“<span class="quote">plain</span>”</span> index scans,
+ <span class="quote">“<span class="quote">bitmap</span>”</span> index scans, or both. The scan-related functions that an
+ index access method must or may provide are:
+ </p><p>
+</p><pre class="programlisting">
+IndexScanDesc
+ambeginscan (Relation indexRelation,
+ int nkeys,
+ int norderbys);
+</pre><p>
+ Prepare for an index scan. The <code class="literal">nkeys</code> and <code class="literal">norderbys</code>
+ parameters indicate the number of quals and ordering operators that will be
+ used in the scan; these may be useful for space allocation purposes.
+ Note that the actual values of the scan keys aren't provided yet.
+ The result must be a palloc'd struct.
+ For implementation reasons the index access method
+ <span class="emphasis"><em>must</em></span> create this struct by calling
+ <code class="function">RelationGetIndexScan()</code>. In most cases
+ <code class="function">ambeginscan</code> does little beyond making that call and perhaps
+ acquiring locks;
+ the interesting parts of index-scan startup are in <code class="function">amrescan</code>.
+ </p><p>
+</p><pre class="programlisting">
+void
+amrescan (IndexScanDesc scan,
+ ScanKey keys,
+ int nkeys,
+ ScanKey orderbys,
+ int norderbys);
+</pre><p>
+ Start or restart an index scan, possibly with new scan keys. (To restart
+ using previously-passed keys, NULL is passed for <code class="literal">keys</code> and/or
+ <code class="literal">orderbys</code>.) Note that it is not allowed for
+ the number of keys or order-by operators to be larger than
+ what was passed to <code class="function">ambeginscan</code>. In practice the restart
+ feature is used when a new outer tuple is selected by a nested-loop join
+ and so a new key comparison value is needed, but the scan key structure
+ remains the same.
+ </p><p>
+</p><pre class="programlisting">
+bool
+amgettuple (IndexScanDesc scan,
+ ScanDirection direction);
+</pre><p>
+ Fetch the next tuple in the given scan, moving in the given
+ direction (forward or backward in the index). Returns true if a tuple was
+ obtained, false if no matching tuples remain. In the true case the tuple
+ TID is stored into the <code class="literal">scan</code> structure. Note that
+ <span class="quote">“<span class="quote">success</span>”</span> means only that the index contains an entry that matches
+ the scan keys, not that the tuple necessarily still exists in the heap or
+ will pass the caller's snapshot test. On success, <code class="function">amgettuple</code>
+ must also set <code class="literal">scan-&gt;xs_recheck</code> to true or false.
+ False means it is certain that the index entry matches the scan keys.
+ True means this is not certain, and the conditions represented by the
+ scan keys must be rechecked against the heap tuple after fetching it.
+ This provision supports <span class="quote">“<span class="quote">lossy</span>”</span> index operators.
+ Note that rechecking will extend only to the scan conditions; a partial
+ index predicate (if any) is never rechecked by <code class="function">amgettuple</code>
+ callers.
+ </p><p>
+ If the index supports <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">index-only
+ scans</a> (i.e., <code class="function">amcanreturn</code> returns true for any
+ of its columns),
+ then on success the AM must also check <code class="literal">scan-&gt;xs_want_itup</code>,
+ and if that is true it must return the originally indexed data for the
+ index entry. Columns for which <code class="function">amcanreturn</code> returns
+ false can be returned as nulls.
+ The data can be returned in the form of an
+ <code class="structname">IndexTuple</code> pointer stored at <code class="literal">scan-&gt;xs_itup</code>,
+ with tuple descriptor <code class="literal">scan-&gt;xs_itupdesc</code>; or in the form of
+ a <code class="structname">HeapTuple</code> pointer stored at <code class="literal">scan-&gt;xs_hitup</code>,
+ with tuple descriptor <code class="literal">scan-&gt;xs_hitupdesc</code>. (The latter
+ format should be used when reconstructing data that might possibly not fit
+ into an <code class="structname">IndexTuple</code>.) In either case,
+ management of the data referenced by the pointer is the access method's
+ responsibility. The data must remain good at least until the next
+ <code class="function">amgettuple</code>, <code class="function">amrescan</code>, or <code class="function">amendscan</code>
+ call for the scan.
+ </p><p>
+ The <code class="function">amgettuple</code> function need only be provided if the access
+ method supports <span class="quote">“<span class="quote">plain</span>”</span> index scans. If it doesn't, the
+ <code class="structfield">amgettuple</code> field in its <code class="structname">IndexAmRoutine</code>
+ struct must be set to NULL.
+ </p><p>
+</p><pre class="programlisting">
+int64
+amgetbitmap (IndexScanDesc scan,
+ TIDBitmap *tbm);
+</pre><p>
+ Fetch all tuples in the given scan and add them to the caller-supplied
+ <code class="type">TIDBitmap</code> (that is, OR the set of tuple IDs into whatever set is already
+ in the bitmap). The number of tuples fetched is returned (this might be
+ just an approximate count, for instance some AMs do not detect duplicates).
+ While inserting tuple IDs into the bitmap, <code class="function">amgetbitmap</code> can
+ indicate that rechecking of the scan conditions is required for specific
+ tuple IDs. This is analogous to the <code class="literal">xs_recheck</code> output parameter
+ of <code class="function">amgettuple</code>. Note: in the current implementation, support
+ for this feature is conflated with support for lossy storage of the bitmap
+ itself, and therefore callers recheck both the scan conditions and the
+ partial index predicate (if any) for recheckable tuples. That might not
+ always be true, however.
+ <code class="function">amgetbitmap</code> and
+ <code class="function">amgettuple</code> cannot be used in the same index scan; there
+ are other restrictions too when using <code class="function">amgetbitmap</code>, as explained
+ in <a class="xref" href="index-scanning.html" title="64.3. Index Scanning">Section 64.3</a>.
+ </p><p>
+ The <code class="function">amgetbitmap</code> function need only be provided if the access
+ method supports <span class="quote">“<span class="quote">bitmap</span>”</span> index scans. If it doesn't, the
+ <code class="structfield">amgetbitmap</code> field in its <code class="structname">IndexAmRoutine</code>
+ struct must be set to NULL.
+ </p><p>
+</p><pre class="programlisting">
+void
+amendscan (IndexScanDesc scan);
+</pre><p>
+ End a scan and release resources. The <code class="literal">scan</code> struct itself
+ should not be freed, but any locks or pins taken internally by the
+ access method must be released, as well as any other memory allocated
+ by <code class="function">ambeginscan</code> and other scan-related functions.
+ </p><p>
+</p><pre class="programlisting">
+void
+ammarkpos (IndexScanDesc scan);
+</pre><p>
+ Mark current scan position. The access method need only support one
+ remembered scan position per scan.
+ </p><p>
+ The <code class="function">ammarkpos</code> function need only be provided if the access
+ method supports ordered scans. If it doesn't,
+ the <code class="structfield">ammarkpos</code> field in its <code class="structname">IndexAmRoutine</code>
+ struct may be set to NULL.
+ </p><p>
+</p><pre class="programlisting">
+void
+amrestrpos (IndexScanDesc scan);
+</pre><p>
+ Restore the scan to the most recently marked position.
+ </p><p>
+ The <code class="function">amrestrpos</code> function need only be provided if the access
+ method supports ordered scans. If it doesn't,
+ the <code class="structfield">amrestrpos</code> field in its <code class="structname">IndexAmRoutine</code>
+ struct may be set to NULL.
+ </p><p>
+ In addition to supporting ordinary index scans, some types of index
+ may wish to support <em class="firstterm">parallel index scans</em>, which allow
+ multiple backends to cooperate in performing an index scan. The
+ index access method should arrange things so that each cooperating
+ process returns a subset of the tuples that would be performed by
+ an ordinary, non-parallel index scan, but in such a way that the
+ union of those subsets is equal to the set of tuples that would be
+ returned by an ordinary, non-parallel index scan. Furthermore, while
+ there need not be any global ordering of tuples returned by a parallel
+ scan, the ordering of that subset of tuples returned within each
+ cooperating backend must match the requested ordering. The following
+ functions may be implemented to support parallel index scans:
+ </p><p>
+</p><pre class="programlisting">
+Size
+amestimateparallelscan (void);
+</pre><p>
+ Estimate and return the number of bytes of dynamic shared memory which
+ the access method will be needed to perform a parallel scan. (This number
+ is in addition to, not in lieu of, the amount of space needed for
+ AM-independent data in <code class="structname">ParallelIndexScanDescData</code>.)
+ </p><p>
+ It is not necessary to implement this function for access methods which
+ do not support parallel scans or for which the number of additional bytes
+ of storage required is zero.
+ </p><p>
+</p><pre class="programlisting">
+void
+aminitparallelscan (void *target);
+</pre><p>
+ This function will be called to initialize dynamic shared memory at the
+ beginning of a parallel scan. <em class="parameter"><code>target</code></em> will point to at least
+ the number of bytes previously returned by
+ <code class="function">amestimateparallelscan</code>, and this function may use that
+ amount of space to store whatever data it wishes.
+ </p><p>
+ It is not necessary to implement this function for access methods which
+ do not support parallel scans or in cases where the shared memory space
+ required needs no initialization.
+ </p><p>
+</p><pre class="programlisting">
+void
+amparallelrescan (IndexScanDesc scan);
+</pre><p>
+ This function, if implemented, will be called when a parallel index scan
+ must be restarted. It should reset any shared state set up by
+ <code class="function">aminitparallelscan</code> such that the scan will be restarted from
+ the beginning.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-api.html" title="64.1. Basic API Structure for Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-scanning.html" title="64.3. Index Scanning">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.1. Basic API Structure for Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.3. Index Scanning</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-locking.html b/doc/src/sgml/html/index-locking.html
new file mode 100644
index 0000000..b744013
--- /dev/null
+++ b/doc/src/sgml/html/index-locking.html
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.4. Index Locking Considerations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-scanning.html" title="64.3. Index Scanning" /><link rel="next" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.4. Index Locking Considerations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-scanning.html" title="64.3. Index Scanning">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-LOCKING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.4. Index Locking Considerations</h2></div></div></div><p>
+ Index access methods must handle concurrent updates
+ of the index by multiple processes.
+ The core <span class="productname">PostgreSQL</span> system obtains
+ <code class="literal">AccessShareLock</code> on the index during an index scan, and
+ <code class="literal">RowExclusiveLock</code> when updating the index (including plain
+ <code class="command">VACUUM</code>). Since these lock types do not conflict, the access
+ method is responsible for handling any fine-grained locking it might need.
+ An <code class="literal">ACCESS EXCLUSIVE</code> lock on the index as a whole will be
+ taken only during index creation, destruction, or <code class="command">REINDEX</code>
+ (<code class="literal">SHARE UPDATE EXCLUSIVE</code> is taken instead with
+ <code class="literal">CONCURRENTLY</code>).
+ </p><p>
+ Building an index type that supports concurrent updates usually requires
+ extensive and subtle analysis of the required behavior. For the b-tree
+ and hash index types, you can read about the design decisions involved in
+ <code class="filename">src/backend/access/nbtree/README</code> and
+ <code class="filename">src/backend/access/hash/README</code>.
+ </p><p>
+ Aside from the index's own internal consistency requirements, concurrent
+ updates create issues about consistency between the parent table (the
+ <em class="firstterm">heap</em>) and the index. Because
+ <span class="productname">PostgreSQL</span> separates accesses
+ and updates of the heap from those of the index, there are windows in
+ which the index might be inconsistent with the heap. We handle this problem
+ with the following rules:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 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 <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a>.)
+ </p></li><li class="listitem"><p>
+ When a heap entry is to be deleted (by <code class="command">VACUUM</code>), all its
+ index entries must be removed first.
+ </p></li><li class="listitem"><p>
+ An index scan must maintain a pin
+ on the index page holding the item last returned by
+ <code class="function">amgettuple</code>, and <code class="function">ambulkdelete</code> cannot delete
+ entries from pages that are pinned by other backends. The need
+ for this rule is explained below.
+ </p></li></ul></div><p>
+
+ Without the third rule, it is possible for an index reader to
+ see an index entry just before it is removed by <code class="command">VACUUM</code>, and
+ then to arrive at the corresponding heap entry after that was removed by
+ <code class="command">VACUUM</code>.
+ This creates no serious problems if that item
+ number is still unused when the reader reaches it, since an empty
+ item slot will be ignored by <code class="function">heap_fetch()</code>. But what if a
+ third backend has already re-used the item slot for something else?
+ When using an MVCC-compliant snapshot, there is no problem because
+ the new occupant of the slot is certain to be too new to pass the
+ snapshot test. However, with a non-MVCC-compliant snapshot (such as
+ <code class="literal">SnapshotAny</code>), it would be possible to accept and return
+ a row that does not in fact match the scan keys. We could defend
+ against this scenario by requiring the scan keys to be rechecked
+ against the heap row in all cases, but that is too expensive. Instead,
+ we use a pin on an index page as a proxy to indicate that the reader
+ might still be <span class="quote">“<span class="quote">in flight</span>”</span> from the index entry to the matching
+ heap entry. Making <code class="function">ambulkdelete</code> block on such a pin ensures
+ that <code class="command">VACUUM</code> cannot delete the heap entry before the reader
+ is done with it. This solution costs little in run time, and adds blocking
+ overhead only in the rare cases where there actually is a conflict.
+ </p><p>
+ This solution requires that index scans be <span class="quote">“<span class="quote">synchronous</span>”</span>: we have
+ to fetch each heap tuple immediately after scanning the corresponding index
+ entry. This is expensive for a number of reasons. An
+ <span class="quote">“<span class="quote">asynchronous</span>”</span> scan in which we collect many TIDs from the index,
+ and only visit the heap tuples sometime later, requires much less index
+ locking overhead and can allow a more efficient heap access pattern.
+ Per the above analysis, we must use the synchronous approach for
+ non-MVCC-compliant snapshots, but an asynchronous scan is workable
+ for a query using an MVCC snapshot.
+ </p><p>
+ In an <code class="function">amgetbitmap</code> index scan, the access method does not
+ keep an index pin on any of the returned tuples. Therefore
+ it is only safe to use such scans with MVCC-compliant snapshots.
+ </p><p>
+ When the <code class="structfield">ampredlocks</code> flag is not set, any scan using that
+ index access method within a serializable transaction will acquire a
+ nonblocking predicate lock on the full index. This will generate a
+ read-write conflict with the insert of any tuple into that index by a
+ concurrent serializable transaction. If certain patterns of read-write
+ conflicts are detected among a set of concurrent serializable
+ transactions, one of those transactions may be canceled to protect data
+ integrity. When the flag is set, it indicates that the index access
+ method implements finer-grained predicate locking, which will tend to
+ reduce the frequency of such transaction cancellations.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-scanning.html" title="64.3. Index Scanning">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.3. Index Scanning </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.5. Index Uniqueness Checks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-scanning.html b/doc/src/sgml/html/index-scanning.html
new file mode 100644
index 0000000..5d3fdd5
--- /dev/null
+++ b/doc/src/sgml/html/index-scanning.html
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.3. Index Scanning</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-functions.html" title="64.2. Index Access Method Functions" /><link rel="next" href="index-locking.html" title="64.4. Index Locking Considerations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.3. Index Scanning</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-functions.html" title="64.2. Index Access Method Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-locking.html" title="64.4. Index Locking Considerations">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-SCANNING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.3. Index Scanning</h2></div></div></div><p>
+ In an index scan, the index access method is responsible for regurgitating
+ the TIDs of all the tuples it has been told about that match the
+ <em class="firstterm">scan keys</em>. The access method is <span class="emphasis"><em>not</em></span> involved in
+ actually fetching those tuples from the index's parent table, nor in
+ determining whether they pass the scan's visibility test or other
+ conditions.
+ </p><p>
+ A scan key is the internal representation of a <code class="literal">WHERE</code> clause of
+ the form <em class="replaceable"><code>index_key</code></em> <em class="replaceable"><code>operator</code></em>
+ <em class="replaceable"><code>constant</code></em>, where the index key is one of the columns of the
+ index and the operator is one of the members of the operator family
+ associated with that index column. An index scan has zero or more scan
+ keys, which are implicitly ANDed — the returned tuples are expected
+ to satisfy all the indicated conditions.
+ </p><p>
+ The access method can report that the index is <em class="firstterm">lossy</em>, or
+ requires rechecks, for a particular query. This implies that the index
+ scan will return all the entries that pass the scan key, plus possibly
+ additional entries that do not. The core system's index-scan machinery
+ will then apply the index conditions again to the heap tuple to verify
+ whether or not it really should be selected. If the recheck option is not
+ specified, the index scan must return exactly the set of matching entries.
+ </p><p>
+ Note that it is entirely up to the access method to ensure that it
+ correctly finds all and only the entries passing all the given scan keys.
+ Also, the core system will simply hand off all the <code class="literal">WHERE</code>
+ clauses that match the index keys and operator families, without any
+ semantic analysis to determine whether they are redundant or
+ contradictory. As an example, given
+ <code class="literal">WHERE x &gt; 4 AND x &gt; 14</code> where <code class="literal">x</code> is a b-tree
+ indexed column, it is left to the b-tree <code class="function">amrescan</code> function
+ to realize that the first scan key is redundant and can be discarded.
+ The extent of preprocessing needed during <code class="function">amrescan</code> will
+ depend on the extent to which the index access method needs to reduce
+ the scan keys to a <span class="quote">“<span class="quote">normalized</span>”</span> form.
+ </p><p>
+ Some access methods return index entries in a well-defined order, others
+ do not. There are actually two different ways that an access method can
+ support sorted output:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Access methods that always return entries in the natural ordering
+ of their data (such as btree) should set
+ <code class="structfield">amcanorder</code> to true.
+ Currently, such access methods must use btree-compatible strategy
+ numbers for their equality and ordering operators.
+ </p></li><li class="listitem"><p>
+ Access methods that support ordering operators should set
+ <code class="structfield">amcanorderbyop</code> to true.
+ This indicates that the index is capable of returning entries in
+ an order satisfying <code class="literal">ORDER BY</code> <em class="replaceable"><code>index_key</code></em>
+ <em class="replaceable"><code>operator</code></em> <em class="replaceable"><code>constant</code></em>. Scan modifiers
+ of that form can be passed to <code class="function">amrescan</code> as described
+ previously.
+ </p></li></ul></div><p>
+ </p><p>
+ The <code class="function">amgettuple</code> function has a <code class="literal">direction</code> argument,
+ which can be either <code class="literal">ForwardScanDirection</code> (the normal case)
+ or <code class="literal">BackwardScanDirection</code>. If the first call after
+ <code class="function">amrescan</code> specifies <code class="literal">BackwardScanDirection</code>, then the
+ set of matching index entries is to be scanned back-to-front rather than in
+ the normal front-to-back direction, so <code class="function">amgettuple</code> must return
+ the last matching tuple in the index, rather than the first one as it
+ normally would. (This will only occur for access
+ methods that set <code class="structfield">amcanorder</code> to true.) After the
+ first call, <code class="function">amgettuple</code> must be prepared to advance the scan in
+ either direction from the most recently returned entry. (But if
+ <code class="structfield">amcanbackward</code> is false, all subsequent
+ calls will have the same direction as the first one.)
+ </p><p>
+ Access methods that support ordered scans must support <span class="quote">“<span class="quote">marking</span>”</span> a
+ position in a scan and later returning to the marked position. The same
+ position might be restored multiple times. However, only one position need
+ be remembered per scan; a new <code class="function">ammarkpos</code> call overrides the
+ previously marked position. An access method that does not support ordered
+ scans need not provide <code class="function">ammarkpos</code> and <code class="function">amrestrpos</code>
+ functions in <code class="structname">IndexAmRoutine</code>; set those pointers to NULL
+ instead.
+ </p><p>
+ Both the scan position and the mark position (if any) must be maintained
+ consistently in the face of concurrent insertions or deletions in the
+ index. It is OK if a freshly-inserted entry is not returned by a scan that
+ would have found the entry if it had existed when the scan started, or for
+ the scan to return such an entry upon rescanning or backing
+ up even though it had not been returned the first time through. Similarly,
+ a concurrent delete might or might not be reflected in the results of a scan.
+ What is important is that insertions or deletions not cause the scan to
+ miss or multiply return entries that were not themselves being inserted or
+ deleted.
+ </p><p>
+ If the index stores the original indexed data values (and not some lossy
+ representation of them), it is useful to
+ support <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">index-only scans</a>, in
+ which the index returns the actual data not just the TID of the heap tuple.
+ This will only avoid I/O if the visibility map shows that the TID is on an
+ all-visible page; else the heap tuple must be visited anyway to check
+ MVCC visibility. But that is no concern of the access method's.
+ </p><p>
+ Instead of using <code class="function">amgettuple</code>, an index scan can be done with
+ <code class="function">amgetbitmap</code> to fetch all tuples in one call. This can be
+ noticeably more efficient than <code class="function">amgettuple</code> because it allows
+ avoiding lock/unlock cycles within the access method. In principle
+ <code class="function">amgetbitmap</code> should have the same effects as repeated
+ <code class="function">amgettuple</code> calls, but we impose several restrictions to
+ simplify matters. First of all, <code class="function">amgetbitmap</code> returns all
+ tuples at once and marking or restoring scan positions isn't
+ supported. Secondly, the tuples are returned in a bitmap which doesn't
+ have any specific ordering, which is why <code class="function">amgetbitmap</code> doesn't
+ take a <code class="literal">direction</code> argument. (Ordering operators will never be
+ supplied for such a scan, either.)
+ Also, there is no provision for index-only scans with
+ <code class="function">amgetbitmap</code>, since there is no way to return the contents of
+ index tuples.
+ Finally, <code class="function">amgetbitmap</code>
+ does not guarantee any locking of the returned tuples, with implications
+ spelled out in <a class="xref" href="index-locking.html" title="64.4. Index Locking Considerations">Section 64.4</a>.
+ </p><p>
+ Note that it is permitted for an access method to implement only
+ <code class="function">amgetbitmap</code> and not <code class="function">amgettuple</code>, or vice versa,
+ if its internal implementation is unsuited to one API or the other.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-functions.html" title="64.2. Index Access Method Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-locking.html" title="64.4. Index Locking Considerations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.2. Index Access Method Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.4. Index Locking Considerations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index-unique-checks.html b/doc/src/sgml/html/index-unique-checks.html
new file mode 100644
index 0000000..d136039
--- /dev/null
+++ b/doc/src/sgml/html/index-unique-checks.html
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.5. Index Uniqueness Checks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-locking.html" title="64.4. Index Locking Considerations" /><link rel="next" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.5. Index Uniqueness Checks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-locking.html" title="64.4. Index Locking Considerations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-UNIQUE-CHECKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.5. Index Uniqueness Checks</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> enforces SQL uniqueness constraints
+ using <em class="firstterm">unique indexes</em>, which are indexes that disallow
+ multiple entries with identical keys. An access method that supports this
+ feature sets <code class="structfield">amcanunique</code> true.
+ (At present, only b-tree supports it.) Columns listed in the
+ <code class="literal">INCLUDE</code> clause are not considered when enforcing
+ uniqueness.
+ </p><p>
+ Because of MVCC, it is always necessary to allow duplicate entries to
+ exist physically in an index: the entries might refer to successive
+ versions of a single logical row. The behavior we actually want to
+ enforce is that no MVCC snapshot could include two rows with equal
+ index keys. This breaks down into the following cases that must be
+ checked when inserting a new row into a unique index:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If a conflicting valid row has been deleted by the current transaction,
+ it's okay. (In particular, since an UPDATE always deletes the old row
+ version before inserting the new version, this will allow an UPDATE on
+ a row without changing the key.)
+ </p></li><li class="listitem"><p>
+ If a conflicting row has been inserted by an as-yet-uncommitted
+ transaction, the would-be inserter must wait to see if that transaction
+ commits. If it rolls back then there is no conflict. If it commits
+ without deleting the conflicting row again, there is a uniqueness
+ violation. (In practice we just wait for the other transaction to
+ end and then redo the visibility check in toto.)
+ </p></li><li class="listitem"><p>
+ Similarly, if a conflicting valid row has been deleted by an
+ as-yet-uncommitted transaction, the would-be inserter must wait
+ for that transaction to commit or abort, and then repeat the test.
+ </p></li></ul></div><p>
+ </p><p>
+ Furthermore, immediately before reporting a uniqueness violation
+ according to the above rules, the access method must recheck the
+ liveness of the row being inserted. If it is committed dead then
+ no violation should be reported. (This case cannot occur during the
+ ordinary scenario of inserting a row that's just been created by
+ the current transaction. It can happen during
+ <code class="command">CREATE UNIQUE INDEX CONCURRENTLY</code>, however.)
+ </p><p>
+ We require the index access method to apply these tests itself, which
+ means that it must reach into the heap to check the commit status of
+ any row that is shown to have a duplicate key according to the index
+ contents. This is without a doubt ugly and non-modular, but it saves
+ redundant work: if we did a separate probe then the index lookup for
+ a conflicting row would be essentially repeated while finding the place to
+ insert the new row's index entry. What's more, there is no obvious way
+ to avoid race conditions unless the conflict check is an integral part
+ of insertion of the new index entry.
+ </p><p>
+ If the unique constraint is deferrable, there is additional complexity:
+ we need to be able to insert an index entry for a new row, but defer any
+ uniqueness-violation error until end of statement or even later. To
+ avoid unnecessary repeat searches of the index, the index access method
+ should do a preliminary uniqueness check during the initial insertion.
+ If this shows that there is definitely no conflicting live tuple, we
+ are done. Otherwise, we schedule a recheck to occur when it is time to
+ enforce the constraint. If, at the time of the recheck, both the inserted
+ tuple and some other tuple with the same key are live, then the error
+ must be reported. (Note that for this purpose, <span class="quote">“<span class="quote">live</span>”</span> actually
+ means <span class="quote">“<span class="quote">any tuple in the index entry's HOT chain is live</span>”</span>.)
+ To implement this, the <code class="function">aminsert</code> function is passed a
+ <code class="literal">checkUnique</code> parameter having one of the following values:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">UNIQUE_CHECK_NO</code> indicates that no uniqueness checking
+ should be done (this is not a unique index).
+ </p></li><li class="listitem"><p>
+ <code class="literal">UNIQUE_CHECK_YES</code> indicates that this is a non-deferrable
+ unique index, and the uniqueness check must be done immediately, as
+ described above.
+ </p></li><li class="listitem"><p>
+ <code class="literal">UNIQUE_CHECK_PARTIAL</code> indicates that the unique
+ constraint is deferrable. <span class="productname">PostgreSQL</span>
+ will use this mode to insert each row's index entry. The access
+ method must allow duplicate entries into the index, and report any
+ potential duplicates by returning false from <code class="function">aminsert</code>.
+ For each row for which false is returned, a deferred recheck will
+ be scheduled.
+ </p><p>
+ The access method must identify any rows which might violate the
+ unique constraint, but it is not an error for it to report false
+ positives. This allows the check to be done without waiting for other
+ transactions to finish; conflicts reported here are not treated as
+ errors and will be rechecked later, by which time they may no longer
+ be conflicts.
+ </p></li><li class="listitem"><p>
+ <code class="literal">UNIQUE_CHECK_EXISTING</code> indicates that this is a deferred
+ recheck of a row that was reported as a potential uniqueness violation.
+ Although this is implemented by calling <code class="function">aminsert</code>, the
+ access method must <span class="emphasis"><em>not</em></span> insert a new index entry in this
+ case. The index entry is already present. Rather, the access method
+ must check to see if there is another live index entry. If so, and
+ if the target row is also still live, report error.
+ </p><p>
+ It is recommended that in a <code class="literal">UNIQUE_CHECK_EXISTING</code> call,
+ the access method further verify that the target row actually does
+ have an existing entry in the index, and report error if not. This
+ is a good idea because the index tuple values passed to
+ <code class="function">aminsert</code> will have been recomputed. If the index
+ definition involves functions that are not really immutable, we
+ might be checking the wrong area of the index. Checking that the
+ target row is found in the recheck verifies that we are scanning
+ for the same tuple values as were used in the original insertion.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-locking.html" title="64.4. Index Locking Considerations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.4. Index Locking Considerations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.6. Index Cost Estimation Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/index.html b/doc/src/sgml/html/index.html
new file mode 100644
index 0000000..a86ab7b
--- /dev/null
+++ b/doc/src/sgml/html/index.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PostgreSQL 15.5 Documentation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="next" href="preface.html" title="Preface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PostgreSQL 15.5 Documentation</th></tr><tr><td width="10%" align="left"> </td><td width="10%" align="left"> </td><th width="60%" align="center"> </th><td width="10%" align="right"> </td><td width="10%" align="right"> <a accesskey="n" href="preface.html" title="Preface">Next</a></td></tr></table><hr /></div><div class="book" id="POSTGRES"><div class="titlepage"><div><div><h1 class="title">PostgreSQL 15.5 Documentation</h1></div><div><h3 class="corpauthor">The PostgreSQL Global Development Group</h3></div><div><p class="copyright">Copyright © 1996–2023 The PostgreSQL Global Development Group</p></div><div><a href="legalnotice.html">Legal Notice</a></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="preface.html">Preface</a></span></dt><dd><dl><dt><span class="sect1"><a href="intro-whatis.html">1. What Is <span class="productname">PostgreSQL</span>?</a></span></dt><dt><span class="sect1"><a href="history.html">2. A Brief History of <span class="productname">PostgreSQL</span></a></span></dt><dt><span class="sect1"><a href="notation.html">3. Conventions</a></span></dt><dt><span class="sect1"><a href="resources.html">4. Further Information</a></span></dt><dt><span class="sect1"><a href="bug-reporting.html">5. Bug Reporting Guidelines</a></span></dt></dl></dd><dt><span class="part"><a href="tutorial.html">I. Tutorial</a></span></dt><dd><dl><dt><span class="chapter"><a href="tutorial-start.html">1. Getting Started</a></span></dt><dt><span class="chapter"><a href="tutorial-sql.html">2. The <acronym class="acronym">SQL</acronym> Language</a></span></dt><dt><span class="chapter"><a href="tutorial-advanced.html">3. Advanced Features</a></span></dt></dl></dd><dt><span class="part"><a href="sql.html">II. The SQL Language</a></span></dt><dd><dl><dt><span class="chapter"><a href="sql-syntax.html">4. SQL Syntax</a></span></dt><dt><span class="chapter"><a href="ddl.html">5. Data Definition</a></span></dt><dt><span class="chapter"><a href="dml.html">6. Data Manipulation</a></span></dt><dt><span class="chapter"><a href="queries.html">7. Queries</a></span></dt><dt><span class="chapter"><a href="datatype.html">8. Data Types</a></span></dt><dt><span class="chapter"><a href="functions.html">9. Functions and Operators</a></span></dt><dt><span class="chapter"><a href="typeconv.html">10. Type Conversion</a></span></dt><dt><span class="chapter"><a href="indexes.html">11. Indexes</a></span></dt><dt><span class="chapter"><a href="textsearch.html">12. Full Text Search</a></span></dt><dt><span class="chapter"><a href="mvcc.html">13. Concurrency Control</a></span></dt><dt><span class="chapter"><a href="performance-tips.html">14. Performance Tips</a></span></dt><dt><span class="chapter"><a href="parallel-query.html">15. Parallel Query</a></span></dt></dl></dd><dt><span class="part"><a href="admin.html">III. Server Administration</a></span></dt><dd><dl><dt><span class="chapter"><a href="install-binaries.html">16. Installation from Binaries</a></span></dt><dt><span class="chapter"><a href="installation.html">17. Installation from Source Code</a></span></dt><dt><span class="chapter"><a href="install-windows.html">18. Installation from Source Code on <span class="productname">Windows</span></a></span></dt><dt><span class="chapter"><a href="runtime.html">19. Server Setup and Operation</a></span></dt><dt><span class="chapter"><a href="runtime-config.html">20. Server Configuration</a></span></dt><dt><span class="chapter"><a href="client-authentication.html">21. Client Authentication</a></span></dt><dt><span class="chapter"><a href="user-manag.html">22. Database Roles</a></span></dt><dt><span class="chapter"><a href="managing-databases.html">23. Managing Databases</a></span></dt><dt><span class="chapter"><a href="charset.html">24. Localization</a></span></dt><dt><span class="chapter"><a href="maintenance.html">25. Routine Database Maintenance Tasks</a></span></dt><dt><span class="chapter"><a href="backup.html">26. Backup and Restore</a></span></dt><dt><span class="chapter"><a href="high-availability.html">27. High Availability, Load Balancing, and Replication</a></span></dt><dt><span class="chapter"><a href="monitoring.html">28. Monitoring Database Activity</a></span></dt><dt><span class="chapter"><a href="diskusage.html">29. Monitoring Disk Usage</a></span></dt><dt><span class="chapter"><a href="wal.html">30. Reliability and the Write-Ahead Log</a></span></dt><dt><span class="chapter"><a href="logical-replication.html">31. Logical Replication</a></span></dt><dt><span class="chapter"><a href="jit.html">32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</a></span></dt><dt><span class="chapter"><a href="regress.html">33. Regression Tests</a></span></dt></dl></dd><dt><span class="part"><a href="client-interfaces.html">IV. Client Interfaces</a></span></dt><dd><dl><dt><span class="chapter"><a href="libpq.html">34. <span class="application">libpq</span> — C Library</a></span></dt><dt><span class="chapter"><a href="largeobjects.html">35. Large Objects</a></span></dt><dt><span class="chapter"><a href="ecpg.html">36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</a></span></dt><dt><span class="chapter"><a href="information-schema.html">37. The Information Schema</a></span></dt></dl></dd><dt><span class="part"><a href="server-programming.html">V. Server Programming</a></span></dt><dd><dl><dt><span class="chapter"><a href="extend.html">38. Extending <acronym class="acronym">SQL</acronym></a></span></dt><dt><span class="chapter"><a href="triggers.html">39. Triggers</a></span></dt><dt><span class="chapter"><a href="event-triggers.html">40. Event Triggers</a></span></dt><dt><span class="chapter"><a href="rules.html">41. The Rule System</a></span></dt><dt><span class="chapter"><a href="xplang.html">42. Procedural Languages</a></span></dt><dt><span class="chapter"><a href="plpgsql.html">43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</a></span></dt><dt><span class="chapter"><a href="pltcl.html">44. PL/Tcl — Tcl Procedural Language</a></span></dt><dt><span class="chapter"><a href="plperl.html">45. PL/Perl — Perl Procedural Language</a></span></dt><dt><span class="chapter"><a href="plpython.html">46. PL/Python — Python Procedural Language</a></span></dt><dt><span class="chapter"><a href="spi.html">47. Server Programming Interface</a></span></dt><dt><span class="chapter"><a href="bgworker.html">48. Background Worker Processes</a></span></dt><dt><span class="chapter"><a href="logicaldecoding.html">49. Logical Decoding</a></span></dt><dt><span class="chapter"><a href="replication-origins.html">50. Replication Progress Tracking</a></span></dt><dt><span class="chapter"><a href="archive-modules.html">51. Archive Modules</a></span></dt></dl></dd><dt><span class="part"><a href="reference.html">VI. Reference</a></span></dt><dd><dl><dt><span class="reference"><a href="sql-commands.html">I. SQL Commands</a></span></dt><dt><span class="reference"><a href="reference-client.html">II. PostgreSQL Client Applications</a></span></dt><dt><span class="reference"><a href="reference-server.html">III. PostgreSQL Server Applications</a></span></dt></dl></dd><dt><span class="part"><a href="internals.html">VII. Internals</a></span></dt><dd><dl><dt><span class="chapter"><a href="overview.html">52. Overview of PostgreSQL Internals</a></span></dt><dt><span class="chapter"><a href="catalogs.html">53. System Catalogs</a></span></dt><dt><span class="chapter"><a href="views.html">54. System Views</a></span></dt><dt><span class="chapter"><a href="protocol.html">55. Frontend/Backend Protocol</a></span></dt><dt><span class="chapter"><a href="source.html">56. PostgreSQL Coding Conventions</a></span></dt><dt><span class="chapter"><a href="nls.html">57. Native Language Support</a></span></dt><dt><span class="chapter"><a href="plhandler.html">58. Writing a Procedural Language Handler</a></span></dt><dt><span class="chapter"><a href="fdwhandler.html">59. Writing a Foreign Data Wrapper</a></span></dt><dt><span class="chapter"><a href="tablesample-method.html">60. Writing a Table Sampling Method</a></span></dt><dt><span class="chapter"><a href="custom-scan.html">61. Writing a Custom Scan Provider</a></span></dt><dt><span class="chapter"><a href="geqo.html">62. Genetic Query Optimizer</a></span></dt><dt><span class="chapter"><a href="tableam.html">63. Table Access Method Interface Definition</a></span></dt><dt><span class="chapter"><a href="indexam.html">64. Index Access Method Interface Definition</a></span></dt><dt><span class="chapter"><a href="generic-wal.html">65. Generic WAL Records</a></span></dt><dt><span class="chapter"><a href="custom-rmgr.html">66. Custom WAL Resource Managers</a></span></dt><dt><span class="chapter"><a href="btree.html">67. B-Tree Indexes</a></span></dt><dt><span class="chapter"><a href="gist.html">68. GiST Indexes</a></span></dt><dt><span class="chapter"><a href="spgist.html">69. SP-GiST Indexes</a></span></dt><dt><span class="chapter"><a href="gin.html">70. GIN Indexes</a></span></dt><dt><span class="chapter"><a href="brin.html">71. BRIN Indexes</a></span></dt><dt><span class="chapter"><a href="hash-index.html">72. Hash Indexes</a></span></dt><dt><span class="chapter"><a href="storage.html">73. Database Physical Storage</a></span></dt><dt><span class="chapter"><a href="bki.html">74. System Catalog Declarations and Initial Contents</a></span></dt><dt><span class="chapter"><a href="planner-stats-details.html">75. How the Planner Uses Statistics</a></span></dt><dt><span class="chapter"><a href="backup-manifest-format.html">76. Backup Manifest Format</a></span></dt></dl></dd><dt><span class="part"><a href="appendixes.html">VIII. Appendixes</a></span></dt><dd><dl><dt><span class="appendix"><a href="errcodes-appendix.html">A. <span class="productname">PostgreSQL</span> Error Codes</a></span></dt><dt><span class="appendix"><a href="datetime-appendix.html">B. Date/Time Support</a></span></dt><dt><span class="appendix"><a href="sql-keywords-appendix.html">C. <acronym class="acronym">SQL</acronym> Key Words</a></span></dt><dt><span class="appendix"><a href="features.html">D. SQL Conformance</a></span></dt><dt><span class="appendix"><a href="release.html">E. Release Notes</a></span></dt><dt><span class="appendix"><a href="contrib.html">F. Additional Supplied Modules</a></span></dt><dt><span class="appendix"><a href="contrib-prog.html">G. Additional Supplied Programs</a></span></dt><dt><span class="appendix"><a href="external-projects.html">H. External Projects</a></span></dt><dt><span class="appendix"><a href="sourcerepo.html">I. The Source Code Repository</a></span></dt><dt><span class="appendix"><a href="docguide.html">J. Documentation</a></span></dt><dt><span class="appendix"><a href="limits.html">K. <span class="productname">PostgreSQL</span> Limits</a></span></dt><dt><span class="appendix"><a href="acronyms.html">L. Acronyms</a></span></dt><dt><span class="appendix"><a href="glossary.html">M. Glossary</a></span></dt><dt><span class="appendix"><a href="color.html">N. Color Support</a></span></dt><dt><span class="appendix"><a href="appendix-obsolete.html">O. Obsolete or Renamed Features</a></span></dt></dl></dd><dt><span class="bibliography"><a href="biblio.html">Bibliography</a></span></dt><dt><span class="index"><a href="bookindex.html">Index</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="preface.html" title="Preface">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Preface</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexam.html b/doc/src/sgml/html/indexam.html
new file mode 100644
index 0000000..b77c2eb
--- /dev/null
+++ b/doc/src/sgml/html/indexam.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 64. Index Access Method Interface Definition</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition" /><link rel="next" href="index-api.html" title="64.1. Basic API Structure for Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 64. Index Access Method Interface Definition</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-api.html" title="64.1. Basic API Structure for Indexes">Next</a></td></tr></table><hr /></div><div class="chapter" id="INDEXAM"><div class="titlepage"><div><div><h2 class="title">Chapter 64. Index Access Method Interface Definition</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="index-api.html">64.1. Basic API Structure for Indexes</a></span></dt><dt><span class="sect1"><a href="index-functions.html">64.2. Index Access Method Functions</a></span></dt><dt><span class="sect1"><a href="index-scanning.html">64.3. Index Scanning</a></span></dt><dt><span class="sect1"><a href="index-locking.html">64.4. Index Locking Considerations</a></span></dt><dt><span class="sect1"><a href="index-unique-checks.html">64.5. Index Uniqueness Checks</a></span></dt><dt><span class="sect1"><a href="index-cost-estimation.html">64.6. Index Cost Estimation Functions</a></span></dt></dl></div><a id="id-1.10.15.2" class="indexterm"></a><a id="id-1.10.15.3" class="indexterm"></a><p>
+ This chapter defines the interface between the core
+ <span class="productname">PostgreSQL</span> system and <em class="firstterm">index access
+ methods</em>, which manage individual index types. The core system
+ knows nothing about indexes beyond what is specified here, so it is
+ possible to develop entirely new index types by writing add-on code.
+ </p><p>
+ All indexes in <span class="productname">PostgreSQL</span> are what are known
+ technically as <em class="firstterm">secondary indexes</em>; that is, the index is
+ physically separate from the table file that it describes. Each index
+ is stored as its own physical <em class="firstterm">relation</em> and so is described
+ by an entry in the <code class="structname">pg_class</code> catalog. The contents of an
+ index are entirely under the control of its index access method. In
+ practice, all index access methods divide indexes into standard-size
+ 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 <a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>, and most use the same format for index
+ tuple headers; but these decisions are not forced on an access method.)
+ </p><p>
+ An index is effectively a mapping from some data key values to
+ <em class="firstterm">tuple identifiers</em>, or <acronym class="acronym">TIDs</acronym>, 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 <a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>). 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
+ an independent object that needs its own index entry. Thus, an
+ update of a row always creates all-new index entries for the row, even if
+ the key values did not change. (<a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">HOT
+ tuples</a> are an exception to this
+ statement; but indexes do not deal with those, either.) Index entries for
+ dead tuples are reclaimed (by vacuuming) when the dead tuples themselves
+ are reclaimed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-api.html" title="64.1. Basic API Structure for Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 63. Table Access Method Interface Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.1. Basic API Structure for Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-bitmap-scans.html b/doc/src/sgml/html/indexes-bitmap-scans.html
new file mode 100644
index 0000000..4793b13
--- /dev/null
+++ b/doc/src/sgml/html/indexes-bitmap-scans.html
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.5. Combining Multiple Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY" /><link rel="next" href="indexes-unique.html" title="11.6. Unique Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.5. Combining Multiple Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-unique.html" title="11.6. Unique Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-BITMAP-SCANS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.5. Combining Multiple Indexes</h2></div></div></div><a id="id-1.5.10.8.2" class="indexterm"></a><a id="id-1.5.10.8.3" class="indexterm"></a><p>
+ A single index scan can only use query clauses that use the index's
+ columns with operators of its operator class and are joined with
+ <code class="literal">AND</code>. For example, given an index on <code class="literal">(a, b)</code>
+ a query condition like <code class="literal">WHERE a = 5 AND b = 6</code> could
+ use the index, but a query like <code class="literal">WHERE a = 5 OR b = 6</code> could not
+ directly use the index.
+ </p><p>
+ Fortunately,
+ <span class="productname">PostgreSQL</span> has the ability to combine multiple indexes
+ (including multiple uses of the same index) to handle cases that cannot
+ be implemented by single index scans. The system can form <code class="literal">AND</code>
+ and <code class="literal">OR</code> conditions across several index scans. For example,
+ a query like <code class="literal">WHERE x = 42 OR x = 47 OR x = 53 OR x = 99</code>
+ could be broken down into four separate scans of an index on <code class="literal">x</code>,
+ each scan using one of the query clauses. The results of these scans are
+ then ORed together to produce the result. Another example is that if we
+ have separate indexes on <code class="literal">x</code> and <code class="literal">y</code>, one possible
+ implementation of a query like <code class="literal">WHERE x = 5 AND y = 6</code> is to
+ use each index with the appropriate query clause and then AND together
+ the index results to identify the result rows.
+ </p><p>
+ To combine multiple indexes, the system scans each needed index and
+ prepares a <em class="firstterm">bitmap</em> in memory giving the locations of
+ table rows that are reported as matching that index's conditions.
+ The bitmaps are then ANDed and ORed together as needed by the query.
+ Finally, the actual table rows are visited and returned. The table rows
+ are visited in physical order, because that is how the bitmap is laid
+ out; this means that any ordering of the original indexes is lost, and
+ so a separate sort step will be needed if the query has an <code class="literal">ORDER
+ BY</code> clause. For this reason, and because each additional index scan
+ adds extra time, the planner will sometimes choose to use a simple index
+ scan even though additional indexes are available that could have been
+ used as well.
+ </p><p>
+ In all but the simplest applications, there are various combinations of
+ indexes that might be useful, and the database developer must make
+ trade-offs to decide which indexes to provide. Sometimes multicolumn
+ indexes are best, but sometimes it's better to create separate indexes
+ and rely on the index-combination feature. For example, if your
+ workload includes a mix of queries that sometimes involve only column
+ <code class="literal">x</code>, sometimes only column <code class="literal">y</code>, and sometimes both
+ columns, you might choose to create two separate indexes on
+ <code class="literal">x</code> and <code class="literal">y</code>, relying on index combination to
+ process the queries that use both columns. You could also create a
+ multicolumn index on <code class="literal">(x, y)</code>. This index would typically be
+ more efficient than index combination for queries involving both
+ columns, but as discussed in <a class="xref" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Section 11.3</a>, it
+ would be almost useless for queries involving only <code class="literal">y</code>, so it
+ should not be the only index. A combination of the multicolumn index
+ and a separate index on <code class="literal">y</code> would serve reasonably well. For
+ queries involving only <code class="literal">x</code>, the multicolumn index could be
+ used, though it would be larger and hence slower than an index on
+ <code class="literal">x</code> alone. The last alternative is to create all three
+ indexes, but this is probably only reasonable if the table is searched
+ much more often than it is updated and all three types of query are
+ common. If one of the types of query is much less common than the
+ others, you'd probably settle for creating just the two indexes that
+ best match the common types.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-unique.html" title="11.6. Unique Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.4. Indexes and <code class="literal">ORDER BY</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.6. Unique Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-collations.html b/doc/src/sgml/html/indexes-collations.html
new file mode 100644
index 0000000..32221f1
--- /dev/null
+++ b/doc/src/sgml/html/indexes-collations.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.11. Indexes and Collations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families" /><link rel="next" href="indexes-examine.html" title="11.12. Examining Index Usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.11. Indexes and Collations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-examine.html" title="11.12. Examining Index Usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-COLLATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.11. Indexes and Collations</h2></div></div></div><p>
+ An index can support only one collation per index column.
+ If multiple collations are of interest, multiple indexes may be needed.
+ </p><p>
+ Consider these statements:
+</p><pre class="programlisting">
+CREATE TABLE test1c (
+ id integer,
+ content varchar COLLATE "x"
+);
+
+CREATE INDEX test1c_content_index ON test1c (content);
+</pre><p>
+ The index automatically uses the collation of the
+ underlying column. So a query of the form
+</p><pre class="programlisting">
+SELECT * FROM test1c WHERE content &gt; <em class="replaceable"><code>constant</code></em>;
+</pre><p>
+ could use the index, because the comparison will by default use the
+ collation of the column. However, this index cannot accelerate queries
+ that involve some other collation. So if queries of the form, say,
+</p><pre class="programlisting">
+SELECT * FROM test1c WHERE content &gt; <em class="replaceable"><code>constant</code></em> COLLATE "y";
+</pre><p>
+ are also of interest, an additional index could be created that supports
+ the <code class="literal">"y"</code> collation, like this:
+</p><pre class="programlisting">
+CREATE INDEX test1c_content_y_index ON test1c (content COLLATE "y");
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-examine.html" title="11.12. Examining Index Usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.10. Operator Classes and Operator Families </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.12. Examining Index Usage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-examine.html b/doc/src/sgml/html/indexes-examine.html
new file mode 100644
index 0000000..487d9ae
--- /dev/null
+++ b/doc/src/sgml/html/indexes-examine.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.12. Examining Index Usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-collations.html" title="11.11. Indexes and Collations" /><link rel="next" href="textsearch.html" title="Chapter 12. Full Text Search" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.12. Examining Index Usage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-collations.html" title="11.11. Indexes and Collations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch.html" title="Chapter 12. Full Text Search">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-EXAMINE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.12. Examining Index Usage</h2></div></div></div><a id="id-1.5.10.15.2" class="indexterm"></a><p>
+ Although indexes in <span class="productname">PostgreSQL</span> do not need
+ 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
+ <a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a>
+ command; its application for this purpose is
+ illustrated in <a class="xref" href="using-explain.html" title="14.1. Using EXPLAIN">Section 14.1</a>.
+ It is also possible to gather overall statistics about index usage
+ in a running server, as described in <a class="xref" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Section 28.2</a>.
+ </p><p>
+ It is difficult to formulate a general procedure for determining
+ which indexes to create. There are a number of typical cases that
+ have been shown in the examples throughout the previous sections.
+ A good deal of experimentation is often necessary.
+ The rest of this section gives some tips for that:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Always run <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>
+ first. This command
+ collects statistics about the distribution of the values in the
+ table. This information is required to estimate the number of rows
+ returned by a query, which is needed by the planner to assign
+ realistic costs to each possible query plan. In absence of any
+ real statistics, some default values are assumed, which are
+ almost certain to be inaccurate. Examining an application's
+ index usage without having run <code class="command">ANALYZE</code> is
+ therefore a lost cause.
+ See <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>
+ and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ </p></li><li class="listitem"><p>
+ Use real data for experimentation. Using test data for setting
+ up indexes will tell you what indexes you need for the test data,
+ but that is all.
+ </p><p>
+ It is especially fatal to use very small test data sets.
+ While selecting 1000 out of 100000 rows could be a candidate for
+ an index, selecting 1 out of 100 rows will hardly be, because the
+ 100 rows probably fit within a single disk page, and there
+ is no plan that can beat sequentially fetching 1 disk page.
+ </p><p>
+ Also be careful when making up test data, which is often
+ unavoidable when the application is not yet in production.
+ Values that are very similar, completely random, or inserted in
+ sorted order will skew the statistics away from the distribution
+ that real data would have.
+ </p></li><li class="listitem"><p>
+ 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 <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE" title="20.7.1. Planner Method Configuration">Section 20.7.1</a>).
+ For instance, turning off sequential scans
+ (<code class="varname">enable_seqscan</code>) and nested-loop joins
+ (<code class="varname">enable_nestloop</code>), which are the most basic plans,
+ will force the system to use a different plan. If the system
+ still chooses a sequential scan or nested-loop join then there is
+ probably a more fundamental reason why the index is not being
+ used; for example, the query condition does not match the index.
+ (What kind of query can use what kind of index is explained in
+ the previous sections.)
+ </p></li><li class="listitem"><p>
+ If forcing index usage does use the index, then there are two
+ possibilities: Either the system is right and using the index is
+ indeed not appropriate, or the cost estimates of the query plans
+ are not reflecting reality. So you should time your query with
+ and without indexes. The <code class="command">EXPLAIN ANALYZE</code>
+ command can be useful here.
+ </p></li><li class="listitem"><p>
+ If it turns out that the cost estimates are wrong, there are,
+ again, two possibilities. The total cost is computed from the
+ 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 <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS" title="20.7.2. Planner Cost Constants">Section 20.7.2</a>).
+ An inaccurate selectivity estimate is due to
+ insufficient statistics. It might be possible to improve this by
+ tuning the statistics-gathering parameters (see
+ <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>).
+ </p><p>
+ If you do not succeed in adjusting the costs to be more
+ appropriate, then you might have to resort to forcing index usage
+ explicitly. You might also want to contact the
+ <span class="productname">PostgreSQL</span> developers to examine the issue.
+ </p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-collations.html" title="11.11. Indexes and Collations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch.html" title="Chapter 12. Full Text Search">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.11. Indexes and Collations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. Full Text Search</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-expressional.html b/doc/src/sgml/html/indexes-expressional.html
new file mode 100644
index 0000000..d3b643c
--- /dev/null
+++ b/doc/src/sgml/html/indexes-expressional.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.7. Indexes on Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-unique.html" title="11.6. Unique Indexes" /><link rel="next" href="indexes-partial.html" title="11.8. Partial Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.7. Indexes on Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-unique.html" title="11.6. Unique Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-partial.html" title="11.8. Partial Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-EXPRESSIONAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.7. Indexes on Expressions</h2></div></div></div><a id="id-1.5.10.10.2" class="indexterm"></a><p>
+ An index column need not be just a column of the underlying table,
+ but can be a function or scalar expression computed from one or
+ more columns of the table. This feature is useful to obtain fast
+ access to tables based on the results of computations.
+ </p><p>
+ For example, a common way to do case-insensitive comparisons is to
+ use the <code class="function">lower</code> function:
+</p><pre class="programlisting">
+SELECT * FROM test1 WHERE lower(col1) = 'value';
+</pre><p>
+ This query can use an index if one has been
+ defined on the result of the <code class="literal">lower(col1)</code>
+ function:
+</p><pre class="programlisting">
+CREATE INDEX test1_lower_col1_idx ON test1 (lower(col1));
+</pre><p>
+ </p><p>
+ If we were to declare this index <code class="literal">UNIQUE</code>, it would prevent
+ creation of rows whose <code class="literal">col1</code> values differ only in case,
+ as well as rows whose <code class="literal">col1</code> values are actually identical.
+ Thus, indexes on expressions can be used to enforce constraints that
+ are not definable as simple unique constraints.
+ </p><p>
+ As another example, if one often does queries like:
+</p><pre class="programlisting">
+SELECT * FROM people WHERE (first_name || ' ' || last_name) = 'John Smith';
+</pre><p>
+ then it might be worth creating an index like this:
+</p><pre class="programlisting">
+CREATE INDEX people_names ON people ((first_name || ' ' || last_name));
+</pre><p>
+ </p><p>
+ The syntax of the <code class="command">CREATE INDEX</code> command normally requires
+ writing parentheses around index expressions, as shown in the second
+ example. The parentheses can be omitted when the expression is just
+ a function call, as in the first example.
+ </p><p>
+ Index expressions are relatively expensive to maintain, because the
+ derived expression(s) must be computed for each row insertion
+ and <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">non-HOT update.</a> However, the index expressions are
+ <span class="emphasis"><em>not</em></span> recomputed during an indexed search, since they are
+ already stored in the index. In both examples above, the system
+ sees the query as just <code class="literal">WHERE indexedcolumn = 'constant'</code>
+ and so the speed of the search is equivalent to any other simple index
+ query. Thus, indexes on expressions are useful when retrieval speed
+ is more important than insertion and update speed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-unique.html" title="11.6. Unique Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-partial.html" title="11.8. Partial Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.6. Unique Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.8. Partial Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-index-only-scans.html b/doc/src/sgml/html/indexes-index-only-scans.html
new file mode 100644
index 0000000..f9a4e11
--- /dev/null
+++ b/doc/src/sgml/html/indexes-index-only-scans.html
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.9. Index-Only Scans and Covering Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-partial.html" title="11.8. Partial Indexes" /><link rel="next" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.9. Index-Only Scans and Covering Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-partial.html" title="11.8. Partial Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-INDEX-ONLY-SCANS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.9. Index-Only Scans and Covering Indexes</h2></div></div></div><a id="id-1.5.10.12.2" class="indexterm"></a><a id="id-1.5.10.12.3" class="indexterm"></a><a id="id-1.5.10.12.4" class="indexterm"></a><a id="id-1.5.10.12.5" class="indexterm"></a><p>
+ All indexes in <span class="productname">PostgreSQL</span>
+ are <em class="firstterm">secondary</em> indexes, meaning that each index is
+ stored separately from the table's main data area (which is called the
+ table's <em class="firstterm">heap</em>
+ in <span class="productname">PostgreSQL</span> terminology). This means that
+ in an ordinary index scan, each row retrieval requires fetching data from
+ both the index and the heap. Furthermore, while the index entries that
+ match a given indexable <code class="literal">WHERE</code> condition are usually
+ close together in 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
+ <a class="xref" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Section 11.5</a>, bitmap scans try to alleviate
+ this cost by doing the heap accesses in sorted order, but that only goes
+ so far.)
+ </p><p>
+ To solve this performance problem, <span class="productname">PostgreSQL</span>
+ supports <em class="firstterm">index-only scans</em>, which can answer
+ queries from an index alone without any heap access. The basic idea is
+ to return values directly out of each index entry instead of consulting
+ the associated heap entry. There are two fundamental restrictions on
+ when this method can be used:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ The index type must support index-only scans. B-tree indexes always
+ do. GiST and SP-GiST indexes support index-only scans for some
+ operator classes but not others. Other index types have no support.
+ The underlying requirement is that the index must physically store, or
+ else be able to reconstruct, the original data value for each index
+ entry. As a counterexample, GIN indexes cannot support index-only
+ scans because each index entry typically holds only part of the
+ original data value.
+ </p></li><li class="listitem"><p>
+ The query must reference only columns stored in the index. For
+ example, given an index on columns <code class="literal">x</code>
+ and <code class="literal">y</code> of a table that also has a
+ column <code class="literal">z</code>, these queries could use index-only scans:
+</p><pre class="programlisting">
+SELECT x, y FROM tab WHERE x = 'key';
+SELECT x FROM tab WHERE x = 'key' AND y &lt; 42;
+</pre><p>
+ but these queries could not:
+</p><pre class="programlisting">
+SELECT x, z FROM tab WHERE x = 'key';
+SELECT x FROM tab WHERE x = 'key' AND z &lt; 42;
+</pre><p>
+ (Expression indexes and partial indexes complicate this rule,
+ as discussed below.)
+ </p></li></ol></div><p>
+ </p><p>
+ If these two fundamental requirements are met, then all the data values
+ required by the query are available from the index, so an index-only scan
+ is physically possible. But there is an additional requirement for any
+ table scan in <span class="productname">PostgreSQL</span>: it must verify that
+ each retrieved row be <span class="quote">“<span class="quote">visible</span>”</span> to the query's MVCC
+ snapshot, as discussed in <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>. 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, for seldom-changing data there is a way around this
+ problem. <span class="productname">PostgreSQL</span> tracks, for each page in
+ a table's heap, whether all rows stored in that page are old enough to be
+ visible to all current and future transactions. This information is
+ stored in a bit in the table's <em class="firstterm">visibility map</em>. An
+ index-only scan, after finding a candidate index entry, checks the
+ visibility map bit for the corresponding heap page. If it's set, the row
+ is known visible and so the data can be returned with no further work.
+ If it's not set, the heap entry must be visited to find out whether it's
+ visible, so no performance advantage is gained over a standard index
+ scan. Even in the successful case, this approach trades visibility map
+ accesses for heap accesses; but since the visibility map is four orders
+ of magnitude smaller than the heap it describes, far less physical I/O is
+ needed to access it. In most situations the visibility map remains
+ cached in memory all the time.
+ </p><p>
+ In short, while an index-only scan is possible given the two fundamental
+ requirements, it will be a win only if a significant fraction of the
+ table's heap pages have their all-visible map bits set. But tables in
+ which a large fraction of the rows are unchanging are common enough to
+ make this type of scan very useful in practice.
+ </p><p>
+ <a id="id-1.5.10.12.10.1" class="indexterm"></a>
+ To make effective use of the index-only scan feature, you might choose to
+ create a <em class="firstterm">covering index</em>, which is an index
+ specifically designed to include the columns needed by a particular
+ type of query that you run frequently. Since queries typically need to
+ retrieve more columns than just the ones they search
+ on, <span class="productname">PostgreSQL</span> allows you to create an index
+ in which some columns are just <span class="quote">“<span class="quote">payload</span>”</span> and are not part
+ of the search key. This is done by adding an <code class="literal">INCLUDE</code>
+ clause listing the extra columns. For example, if you commonly run
+ queries like
+</p><pre class="programlisting">
+SELECT y FROM tab WHERE x = 'key';
+</pre><p>
+ the traditional approach to speeding up such queries would be to create
+ an index on <code class="literal">x</code> only. However, an index defined as
+</p><pre class="programlisting">
+CREATE INDEX tab_x_y ON tab(x) INCLUDE (y);
+</pre><p>
+ could handle these queries as index-only scans,
+ because <code class="literal">y</code> can be obtained from the index without
+ visiting the heap.
+ </p><p>
+ Because column <code class="literal">y</code> is not part of the index's search
+ key, it does not have to be of a data type that the index can handle;
+ it's merely stored in the index and is not interpreted by the index
+ machinery. Also, if the index is a unique index, that is
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX tab_x_y ON tab(x) INCLUDE (y);
+</pre><p>
+ the uniqueness condition applies to just column <code class="literal">x</code>,
+ not to the combination of <code class="literal">x</code> and <code class="literal">y</code>.
+ (An <code class="literal">INCLUDE</code> clause can also be written
+ in <code class="literal">UNIQUE</code> and <code class="literal">PRIMARY KEY</code>
+ constraints, providing alternative syntax for setting up an index like
+ this.)
+ </p><p>
+ It's wise to be conservative about adding non-key payload columns to an
+ index, especially wide columns. If an index tuple exceeds the
+ maximum size allowed for the index type, data insertion will fail.
+ In any case, non-key columns duplicate data from the index's table
+ and bloat the size of the index, thus potentially slowing searches.
+ And remember that there is little point in including payload columns in an
+ index unless the table changes slowly enough that an index-only scan is
+ likely to not need to access the heap. If the heap tuple must be visited
+ anyway, it costs nothing more to get the column's value from there.
+ Other restrictions are that expressions are not currently supported as
+ included columns, and that only B-tree, GiST and SP-GiST indexes currently
+ support included columns.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> had
+ the <code class="literal">INCLUDE</code> feature, people sometimes made covering
+ indexes by writing the payload columns as ordinary index columns,
+ that is writing
+</p><pre class="programlisting">
+CREATE INDEX tab_x_y ON tab(x, y);
+</pre><p>
+ even though they had no intention of ever using <code class="literal">y</code> as
+ part of a <code class="literal">WHERE</code> clause. This works fine as long as
+ the extra columns are trailing columns; making them be leading columns is
+ unwise for the reasons explained in <a class="xref" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Section 11.3</a>.
+ However, this method doesn't support the case where you want the index to
+ enforce uniqueness on the key column(s).
+ </p><p>
+ <em class="firstterm">Suffix truncation</em> always removes non-key
+ columns from upper B-Tree levels. As payload columns, they are
+ never used to guide index scans. The truncation process also
+ removes one or more trailing key column(s) when the remaining
+ prefix of key column(s) happens to be sufficient to describe tuples
+ on the lowest B-Tree level. In practice, covering indexes without
+ an <code class="literal">INCLUDE</code> clause often avoid storing columns
+ that are effectively payload in the upper levels. However,
+ explicitly defining payload columns as non-key columns
+ <span class="emphasis"><em>reliably</em></span> keeps the tuples in upper levels
+ small.
+ </p><p>
+ In principle, index-only scans can be used with expression indexes.
+ For example, given an index on <code class="literal">f(x)</code>
+ where <code class="literal">x</code> is a table column, it should be possible to
+ execute
+</p><pre class="programlisting">
+SELECT f(x) FROM tab WHERE f(x) &lt; 1;
+</pre><p>
+ as an index-only scan; and this is very attractive
+ if <code class="literal">f()</code> is an expensive-to-compute function.
+ However, <span class="productname">PostgreSQL</span>'s planner is currently not
+ very smart about such cases. It considers a query to be potentially
+ executable by index-only scan only when all <span class="emphasis"><em>columns</em></span>
+ needed by the query are available from the index. In this
+ example, <code class="literal">x</code> is not needed except in the
+ context <code class="literal">f(x)</code>, but the planner does not notice that and
+ concludes that an index-only scan is not possible. If an index-only scan
+ seems sufficiently worthwhile, this can be worked around by
+ adding <code class="literal">x</code> as an included column, for example
+</p><pre class="programlisting">
+CREATE INDEX tab_f_x ON tab (f(x)) INCLUDE (x);
+</pre><p>
+ An additional caveat, if the goal is to avoid
+ recalculating <code class="literal">f(x)</code>, is that the planner won't
+ necessarily match uses of <code class="literal">f(x)</code> that aren't in
+ indexable <code class="literal">WHERE</code> clauses to the index column. It will
+ usually get this right in simple queries such as shown above, but not in
+ queries that involve joins. These deficiencies may be remedied in future
+ versions of <span class="productname">PostgreSQL</span>.
+ </p><p>
+ Partial indexes also have interesting interactions with index-only scans.
+ Consider the partial index shown in <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX3" title="Example 11.3. Setting up a Partial Unique Index">Example 11.3</a>:
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
+ WHERE success;
+</pre><p>
+ In principle, we could do an index-only scan on this index to satisfy a
+ query like
+</p><pre class="programlisting">
+SELECT target FROM tests WHERE subject = 'some-subject' AND success;
+</pre><p>
+ But there's a problem: the <code class="literal">WHERE</code> clause refers
+ to <code class="literal">success</code> which is not available as a result column
+ of the index. Nonetheless, an index-only scan is possible because the
+ plan does not need to recheck that part of the <code class="literal">WHERE</code>
+ clause at run time: all entries found in the index necessarily
+ have <code class="literal">success = true</code> so this need not be explicitly
+ checked in the plan. <span class="productname">PostgreSQL</span> versions 9.6
+ and later will recognize such cases and allow index-only scans to be
+ generated, but older versions will not.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-partial.html" title="11.8. Partial Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.8. Partial Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.10. Operator Classes and Operator Families</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-intro.html b/doc/src/sgml/html/indexes-intro.html
new file mode 100644
index 0000000..acdb0c6
--- /dev/null
+++ b/doc/src/sgml/html/indexes-intro.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes.html" title="Chapter 11. Indexes" /><link rel="next" href="indexes-types.html" title="11.2. Index Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes.html" title="Chapter 11. Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-types.html" title="11.2. Index Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.1. Introduction</h2></div></div></div><p>
+ Suppose we have a table similar to this:
+</p><pre class="programlisting">
+CREATE TABLE test1 (
+ id integer,
+ content varchar
+);
+</pre><p>
+ and the application issues many queries of the form:
+</p><pre class="programlisting">
+SELECT content FROM test1 WHERE id = <em class="replaceable"><code>constant</code></em>;
+</pre><p>
+ With no advance preparation, the system would have to scan the entire
+ <code class="structname">test1</code> table, row by row, to find all
+ matching entries. If there are many rows in
+ <code class="structname">test1</code> and only a few rows (perhaps zero
+ or one) that would be returned by such a query, this is clearly an
+ inefficient method. But if the system has been instructed to maintain an
+ index on the <code class="structfield">id</code> column, it can use a more
+ efficient method for locating matching rows. For instance, it
+ might only have to walk a few levels deep into a search tree.
+ </p><p>
+ A similar approach is used in most non-fiction books: terms and
+ concepts that are frequently looked up by readers are collected in
+ an alphabetic index at the end of the book. The interested reader
+ can scan the index relatively quickly and flip to the appropriate
+ page(s), rather than having to read the entire book to find the
+ material of interest. Just as it is the task of the author to
+ anticipate the items that readers are likely to look up,
+ it is the task of the database programmer to foresee which indexes
+ will be useful.
+ </p><p>
+ The following command can be used to create an index on the
+ <code class="structfield">id</code> column, as discussed:
+</p><pre class="programlisting">
+CREATE INDEX test1_id_index ON test1 (id);
+</pre><p>
+ The name <code class="structname">test1_id_index</code> can be chosen
+ freely, but you should pick something that enables you to remember
+ later what the index was for.
+ </p><p>
+ To remove an index, use the <code class="command">DROP INDEX</code> command.
+ Indexes can be added to and removed from tables at any time.
+ </p><p>
+ Once an index is created, no further intervention is required: the
+ system will update the index when the table is modified, and it will
+ use the index in queries when it thinks doing so would be more efficient
+ than a sequential table scan. But you might have to run the
+ <code class="command">ANALYZE</code> command regularly to update
+ statistics to allow the query planner to make educated decisions.
+ See <a class="xref" href="performance-tips.html" title="Chapter 14. Performance Tips">Chapter 14</a> for information about
+ how to find out whether an index is used and when and why the
+ planner might choose <span class="emphasis"><em>not</em></span> to use an index.
+ </p><p>
+ Indexes can also benefit <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code> commands with search conditions.
+ Indexes can moreover be used in join searches. Thus,
+ an index defined on a column that is part of a join condition can
+ also significantly speed up queries with joins.
+ </p><p>
+ Creating an index on a large table can take a long time. By default,
+ <span class="productname">PostgreSQL</span> allows reads (<code class="command">SELECT</code> statements) to occur
+ on the table in parallel with index creation, but writes (<code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>) are blocked until the index build is finished.
+ In production environments this is often unacceptable.
+ 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 <a class="xref" href="sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY" title="Building Indexes Concurrently">Building Indexes Concurrently</a>.
+ </p><p>
+ After an index is created, the system has to keep it synchronized with the
+ table. This adds overhead to data manipulation operations. Indexes can
+ also prevent the creation of <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">heap-only
+ tuples</a>.
+ Therefore indexes that are seldom or never used in queries
+ should be removed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes.html" title="Chapter 11. Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-types.html" title="11.2. Index Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.2. Index Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-multicolumn.html b/doc/src/sgml/html/indexes-multicolumn.html
new file mode 100644
index 0000000..e0d0182
--- /dev/null
+++ b/doc/src/sgml/html/indexes-multicolumn.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.3. Multicolumn Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-types.html" title="11.2. Index Types" /><link rel="next" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.3. Multicolumn Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-types.html" title="11.2. Index Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-MULTICOLUMN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.3. Multicolumn Indexes</h2></div></div></div><a id="id-1.5.10.6.2" class="indexterm"></a><p>
+ An index can be defined on more than one column of a table. For example, if
+ you have a table of this form:
+</p><pre class="programlisting">
+CREATE TABLE test2 (
+ major int,
+ minor int,
+ name varchar
+);
+</pre><p>
+ (say, you keep your <code class="filename">/dev</code>
+ directory in a database...) and you frequently issue queries like:
+</p><pre class="programlisting">
+SELECT name FROM test2 WHERE major = <em class="replaceable"><code>constant</code></em> AND minor = <em class="replaceable"><code>constant</code></em>;
+</pre><p>
+ then it might be appropriate to define an index on the columns
+ <code class="structfield">major</code> and
+ <code class="structfield">minor</code> together, e.g.:
+</p><pre class="programlisting">
+CREATE INDEX test2_mm_idx ON test2 (major, minor);
+</pre><p>
+ </p><p>
+ Currently, only the B-tree, GiST, GIN, and BRIN index types support
+ multiple-key-column indexes. Whether there can be multiple key
+ columns is independent of whether <code class="literal">INCLUDE</code> columns
+ can be added to the index. Indexes can have up to 32 columns,
+ including <code class="literal">INCLUDE</code> columns. (This limit can be
+ altered when building <span class="productname">PostgreSQL</span>; see the
+ file <code class="filename">pg_config_manual.h</code>.)
+ </p><p>
+ A multicolumn B-tree index can be used with query conditions that
+ involve any subset of the index's columns, but the index is most
+ efficient when there are constraints on the leading (leftmost) columns.
+ The exact rule is that equality constraints on leading columns, plus
+ any inequality constraints on the first column that does not have an
+ equality constraint, will be used to limit the portion of the index
+ that is scanned. Constraints on columns to the right of these columns
+ are checked in the index, so they save visits to the table proper, but
+ they do not reduce the portion of the index that has to be scanned.
+ For example, given an index on <code class="literal">(a, b, c)</code> and a
+ query condition <code class="literal">WHERE a = 5 AND b &gt;= 42 AND c &lt; 77</code>,
+ the index would have to be scanned from the first entry with
+ <code class="literal">a</code> = 5 and <code class="literal">b</code> = 42 up through the last entry with
+ <code class="literal">a</code> = 5. Index entries with <code class="literal">c</code> &gt;= 77 would be
+ skipped, but they'd still have to be scanned through.
+ This index could in principle be used for queries that have constraints
+ on <code class="literal">b</code> and/or <code class="literal">c</code> with no constraint on <code class="literal">a</code>
+ — but the entire index would have to be scanned, so in most cases
+ the planner would prefer a sequential table scan over using the index.
+ </p><p>
+ A multicolumn GiST index can be used with query conditions that
+ involve any subset of the index's columns. Conditions on additional
+ columns restrict the entries returned by the index, but the condition on
+ the first column is the most important one for determining how much of
+ the index needs to be scanned. A GiST index will be relatively
+ ineffective if its first column has only a few distinct values, even if
+ there are many distinct values in additional columns.
+ </p><p>
+ A multicolumn GIN index can be used with query conditions that
+ involve any subset of the index's columns. Unlike B-tree or GiST,
+ index search effectiveness is the same regardless of which index column(s)
+ the query conditions use.
+ </p><p>
+ A multicolumn BRIN index can be used with query conditions that
+ involve any subset of the index's columns. Like GIN and unlike B-tree or
+ GiST, index search effectiveness is the same regardless of which index
+ column(s) the query conditions use. The only reason to have multiple BRIN
+ indexes instead of one multicolumn BRIN index on a single table is to have
+ a different <code class="literal">pages_per_range</code> storage parameter.
+ </p><p>
+ Of course, each column must be used with operators appropriate to the index
+ type; clauses that involve other operators will not be considered.
+ </p><p>
+ Multicolumn indexes should be used sparingly. In most situations,
+ 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
+ <a class="xref" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Section 11.5</a> and
+ <a class="xref" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Section 11.9</a> for some discussion of the
+ merits of different index configurations.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-types.html" title="11.2. Index Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-ordering.html" title="11.4. Indexes and ORDER BY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.2. Index Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.4. Indexes and <code class="literal">ORDER BY</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-opclass.html b/doc/src/sgml/html/indexes-opclass.html
new file mode 100644
index 0000000..b7fd890
--- /dev/null
+++ b/doc/src/sgml/html/indexes-opclass.html
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.10. Operator Classes and Operator Families</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes" /><link rel="next" href="indexes-collations.html" title="11.11. Indexes and Collations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.10. Operator Classes and Operator Families</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-collations.html" title="11.11. Indexes and Collations">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-OPCLASS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.10. Operator Classes and Operator Families</h2></div></div></div><a id="id-1.5.10.13.2" class="indexterm"></a><a id="id-1.5.10.13.3" class="indexterm"></a><p>
+ An index definition can specify an <em class="firstterm">operator
+ class</em> for each column of an index.
+</p><pre class="synopsis">
+CREATE INDEX <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table</code></em> (<em class="replaceable"><code>column</code></em> <em class="replaceable"><code>opclass</code></em> [ ( <em class="replaceable"><code>opclass_options</code></em> ) ] [<span class="optional"><em class="replaceable"><code>sort options</code></em></span>] [<span class="optional">, ...</span>]);
+</pre><p>
+ The operator class identifies the operators to be used by the index
+ for that column. For example, a B-tree index on the type <code class="type">int4</code>
+ would use the <code class="literal">int4_ops</code> class; this operator
+ class includes comparison functions for values of type <code class="type">int4</code>.
+ In practice the default operator class for the column's data type is
+ usually sufficient. The main reason for having operator classes is
+ that for some data types, there could be more than one meaningful
+ index behavior. For example, we might want to sort a complex-number data
+ type either by absolute value or by real part. We could do this by
+ defining two operator classes for the data type and then selecting
+ the proper class when making an index. The operator class determines
+ the basic sort ordering (which can then be modified by adding sort options
+ <code class="literal">COLLATE</code>,
+ <code class="literal">ASC</code>/<code class="literal">DESC</code> and/or
+ <code class="literal">NULLS FIRST</code>/<code class="literal">NULLS LAST</code>).
+ </p><p>
+ There are also some built-in operator classes besides the default ones:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The operator classes <code class="literal">text_pattern_ops</code>,
+ <code class="literal">varchar_pattern_ops</code>, and
+ <code class="literal">bpchar_pattern_ops</code> support B-tree indexes on
+ the types <code class="type">text</code>, <code class="type">varchar</code>, and
+ <code class="type">char</code> respectively. The
+ difference from the default operator classes is that the values
+ are compared strictly character by character rather than
+ according to the locale-specific collation rules. This makes
+ these operator classes suitable for use by queries involving
+ pattern matching expressions (<code class="literal">LIKE</code> or POSIX
+ regular expressions) when the database does not use the standard
+ <span class="quote">“<span class="quote">C</span>”</span> locale. As an example, you might index a
+ <code class="type">varchar</code> column like this:
+</p><pre class="programlisting">
+CREATE INDEX test_index ON test_table (col varchar_pattern_ops);
+</pre><p>
+ Note that you should also create an index with the default operator
+ class if you want queries involving ordinary <code class="literal">&lt;</code>,
+ <code class="literal">&lt;=</code>, <code class="literal">&gt;</code>, or <code class="literal">&gt;=</code> comparisons
+ to use an index. Such queries cannot use the
+ <code class="literal"><em class="replaceable"><code>xxx</code></em>_pattern_ops</code>
+ operator classes. (Ordinary equality comparisons can use these
+ operator classes, however.) It is possible to create multiple
+ indexes on the same column with different operator classes.
+ If you do use the C locale, you do not need the
+ <code class="literal"><em class="replaceable"><code>xxx</code></em>_pattern_ops</code>
+ operator classes, because an index with the default operator class
+ is usable for pattern-matching queries in the C locale.
+ </p></li></ul></div><p>
+ </p><p>
+ The following query shows all defined operator classes:
+
+</p><pre class="programlisting">
+SELECT am.amname AS index_method,
+ opc.opcname AS opclass_name,
+ opc.opcintype::regtype AS indexed_type,
+ opc.opcdefault AS is_default
+ FROM pg_am am, pg_opclass opc
+ WHERE opc.opcmethod = am.oid
+ ORDER BY index_method, opclass_name;
+</pre><p>
+ </p><p>
+ An operator class is actually just a subset of a larger structure called an
+ <em class="firstterm">operator family</em>. In cases where several data types have
+ similar behaviors, it is frequently useful to define cross-data-type
+ operators and allow these to work with indexes. To do this, the operator
+ classes for each of the types must be grouped into the same operator
+ family. The cross-type operators are members of the family, but are not
+ associated with any single class within the family.
+ </p><p>
+ This expanded version of the previous query shows the operator family
+ each operator class belongs to:
+</p><pre class="programlisting">
+SELECT am.amname AS index_method,
+ opc.opcname AS opclass_name,
+ opf.opfname AS opfamily_name,
+ opc.opcintype::regtype AS indexed_type,
+ opc.opcdefault AS is_default
+ FROM pg_am am, pg_opclass opc, pg_opfamily opf
+ WHERE opc.opcmethod = am.oid AND
+ opc.opcfamily = opf.oid
+ ORDER BY index_method, opclass_name;
+</pre><p>
+ </p><p>
+ This query shows all defined operator families and all
+ the operators included in each family:
+</p><pre class="programlisting">
+SELECT am.amname AS index_method,
+ opf.opfname AS opfamily_name,
+ amop.amopopr::regoperator AS opfamily_operator
+ FROM pg_am am, pg_opfamily opf, pg_amop amop
+ WHERE opf.opfmethod = am.oid AND
+ amop.amopfamily = opf.oid
+ ORDER BY index_method, opfamily_name, opfamily_operator;
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> has
+ commands <code class="command">\dAc</code>, <code class="command">\dAf</code>,
+ and <code class="command">\dAo</code>, which provide slightly more sophisticated
+ versions of these queries.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-collations.html" title="11.11. Indexes and Collations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.9. Index-Only Scans and Covering Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.11. Indexes and Collations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-ordering.html b/doc/src/sgml/html/indexes-ordering.html
new file mode 100644
index 0000000..d465eb3
--- /dev/null
+++ b/doc/src/sgml/html/indexes-ordering.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.4. Indexes and ORDER BY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes" /><link rel="next" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.4. Indexes and <code class="literal">ORDER BY</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-ORDERING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.4. Indexes and <code class="literal">ORDER BY</code></h2></div></div></div><a id="id-1.5.10.7.2" class="indexterm"></a><p>
+ In addition to simply finding the rows to be returned by a query,
+ an index may be able to deliver them in a specific sorted order.
+ This allows a query's <code class="literal">ORDER BY</code> specification to be honored
+ without a separate sorting step. Of the index types currently
+ supported by <span class="productname">PostgreSQL</span>, only B-tree
+ can produce sorted output — the other index types return
+ matching rows in an unspecified, implementation-dependent order.
+ </p><p>
+ The planner will consider satisfying an <code class="literal">ORDER BY</code> specification
+ either by scanning an available index that matches the specification,
+ or by scanning the table in physical order and doing an explicit
+ sort. For a query that requires scanning a large fraction of the
+ table, an explicit sort is likely to be faster than using an index
+ because it requires
+ less disk I/O due to following a sequential access pattern. Indexes are
+ more useful when only a few rows need be fetched. An important
+ special case is <code class="literal">ORDER BY</code> in combination with
+ <code class="literal">LIMIT</code> <em class="replaceable"><code>n</code></em>: an explicit sort will have to process
+ all the data to identify the first <em class="replaceable"><code>n</code></em> rows, but if there is
+ an index matching the <code class="literal">ORDER BY</code>, the first <em class="replaceable"><code>n</code></em>
+ rows can be retrieved directly, without scanning the remainder at all.
+ </p><p>
+ By default, B-tree indexes store their entries in ascending order
+ with nulls last (table TID is treated as a tiebreaker column among
+ otherwise equal entries). This means that a forward scan of an
+ index on column <code class="literal">x</code> produces output satisfying <code class="literal">ORDER BY x</code>
+ (or more verbosely, <code class="literal">ORDER BY x ASC NULLS LAST</code>). The
+ index can also be scanned backward, producing output satisfying
+ <code class="literal">ORDER BY x DESC</code>
+ (or more verbosely, <code class="literal">ORDER BY x DESC NULLS FIRST</code>, since
+ <code class="literal">NULLS FIRST</code> is the default for <code class="literal">ORDER BY DESC</code>).
+ </p><p>
+ You can adjust the ordering of a B-tree index by including the
+ options <code class="literal">ASC</code>, <code class="literal">DESC</code>, <code class="literal">NULLS FIRST</code>,
+ and/or <code class="literal">NULLS LAST</code> when creating the index; for example:
+</p><pre class="programlisting">
+CREATE INDEX test2_info_nulls_low ON test2 (info NULLS FIRST);
+CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST);
+</pre><p>
+ An index stored in ascending order with nulls first can satisfy
+ either <code class="literal">ORDER BY x ASC NULLS FIRST</code> or
+ <code class="literal">ORDER BY x DESC NULLS LAST</code> depending on which direction
+ it is scanned in.
+ </p><p>
+ You might wonder why bother providing all four options, when two
+ options together with the possibility of backward scan would cover
+ all the variants of <code class="literal">ORDER BY</code>. In single-column indexes
+ the options are indeed redundant, but in multicolumn indexes they can be
+ useful. Consider a two-column index on <code class="literal">(x, y)</code>: this can
+ satisfy <code class="literal">ORDER BY x, y</code> if we scan forward, or
+ <code class="literal">ORDER BY x DESC, y DESC</code> if we scan backward.
+ But it might be that the application frequently needs to use
+ <code class="literal">ORDER BY x ASC, y DESC</code>. There is no way to get that
+ ordering from a plain index, but it is possible if the index is defined
+ as <code class="literal">(x ASC, y DESC)</code> or <code class="literal">(x DESC, y ASC)</code>.
+ </p><p>
+ Obviously, indexes with non-default sort orderings are a fairly
+ specialized feature, but sometimes they can produce tremendous
+ speedups for certain queries. Whether it's worth maintaining such an
+ index depends on how often you use queries that require a special
+ sort ordering.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.3. Multicolumn Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.5. Combining Multiple Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-partial.html b/doc/src/sgml/html/indexes-partial.html
new file mode 100644
index 0000000..5199cf0
--- /dev/null
+++ b/doc/src/sgml/html/indexes-partial.html
@@ -0,0 +1,212 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.8. Partial Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-expressional.html" title="11.7. Indexes on Expressions" /><link rel="next" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.8. Partial Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-PARTIAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.8. Partial Indexes</h2></div></div></div><a id="id-1.5.10.11.2" class="indexterm"></a><p>
+ A <em class="firstterm">partial index</em> is an index built over a
+ subset of a table; the subset is defined by a conditional
+ expression (called the <em class="firstterm">predicate</em> of the
+ partial index). The index contains entries only for those table
+ rows that satisfy the predicate. Partial indexes are a specialized
+ feature, but there are several situations in which they are useful.
+ </p><p>
+ One major reason for using a partial index is to avoid indexing common
+ values. Since a query searching for a common value (one that
+ accounts for more than a few percent of all the table rows) will not
+ use the index anyway, there is no point in keeping those rows in the
+ 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. <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX1" title="Example 11.1. Setting up a Partial Index to Exclude Common Values">Example 11.1</a> shows a
+ possible application of this idea.
+ </p><div class="example" id="INDEXES-PARTIAL-EX1"><p class="title"><strong>Example 11.1. Setting up a Partial Index to Exclude Common Values</strong></p><div class="example-contents"><p>
+ Suppose you are storing web server access logs in a database.
+ Most accesses originate from the IP address range of your organization but
+ some are from elsewhere (say, employees on dial-up connections).
+ If your searches by IP are primarily for outside accesses,
+ you probably do not need to index the IP range that corresponds to your
+ organization's subnet.
+ </p><p>
+ Assume a table like this:
+</p><pre class="programlisting">
+CREATE TABLE access_log (
+ url varchar,
+ client_ip inet,
+ ...
+);
+</pre><p>
+ </p><p>
+ To create a partial index that suits our example, use a command
+ such as this:
+</p><pre class="programlisting">
+CREATE INDEX access_log_client_ip_ix ON access_log (client_ip)
+WHERE NOT (client_ip &gt; inet '192.168.100.0' AND
+ client_ip &lt; inet '192.168.100.255');
+</pre><p>
+ </p><p>
+ A typical query that can use this index would be:
+</p><pre class="programlisting">
+SELECT *
+FROM access_log
+WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';
+</pre><p>
+ Here the query's IP address is covered by the partial index. The
+ following query cannot use the partial index, as it uses an IP address
+ that is excluded from the index:
+</p><pre class="programlisting">
+SELECT *
+FROM access_log
+WHERE url = '/index.html' AND client_ip = inet '192.168.100.23';
+</pre><p>
+ </p><p>
+ Observe that this kind of partial index requires that the common
+ values be predetermined, so such partial indexes are best used for
+ data distributions that do not change. Such indexes can be recreated
+ occasionally to adjust for new data distributions, but this adds
+ maintenance effort.
+ </p></div></div><br class="example-break" /><p>
+ 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 <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX2" title="Example 11.2. Setting up a Partial Index to Exclude Uninteresting Values">Example 11.2</a>. This results in the same
+ advantages as listed above, but it prevents the
+ <span class="quote">“<span class="quote">uninteresting</span>”</span> values from being accessed via that
+ index, even if an index scan might be profitable in that
+ case. Obviously, setting up partial indexes for this kind of
+ scenario will require a lot of care and experimentation.
+ </p><div class="example" id="INDEXES-PARTIAL-EX2"><p class="title"><strong>Example 11.2. Setting up a Partial Index to Exclude Uninteresting Values</strong></p><div class="example-contents"><p>
+ If you have a table that contains both billed and unbilled orders,
+ where the unbilled orders take up a small fraction of the total
+ table and yet those are the most-accessed rows, you can improve
+ performance by creating an index on just the unbilled rows. The
+ command to create the index would look like this:
+</p><pre class="programlisting">
+CREATE INDEX orders_unbilled_index ON orders (order_nr)
+ WHERE billed is not true;
+</pre><p>
+ </p><p>
+ A possible query to use this index would be:
+</p><pre class="programlisting">
+SELECT * FROM orders WHERE billed is not true AND order_nr &lt; 10000;
+</pre><p>
+ However, the index can also be used in queries that do not involve
+ <code class="structfield">order_nr</code> at all, e.g.:
+</p><pre class="programlisting">
+SELECT * FROM orders WHERE billed is not true AND amount &gt; 5000.00;
+</pre><p>
+ This is not as efficient as a partial index on the
+ <code class="structfield">amount</code> column would be, since the system has to
+ scan the entire index. Yet, if there are relatively few unbilled
+ orders, using this partial index just to find the unbilled orders
+ could be a win.
+ </p><p>
+ Note that this query cannot use this index:
+</p><pre class="programlisting">
+SELECT * FROM orders WHERE order_nr = 3501;
+</pre><p>
+ The order 3501 might be among the billed or unbilled
+ orders.
+ </p></div></div><br class="example-break" /><p>
+ <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX2" title="Example 11.2. Setting up a Partial Index to Exclude Uninteresting Values">Example 11.2</a> also illustrates that the
+ indexed column and the column used in the predicate do not need to
+ match. <span class="productname">PostgreSQL</span> supports partial
+ indexes with arbitrary predicates, so long as only columns of the
+ table being indexed are involved. However, keep in mind that the
+ predicate must match the conditions used in the queries that
+ are supposed to benefit from the index. To be precise, a partial
+ index can be used in a query only if the system can recognize that
+ the <code class="literal">WHERE</code> condition of the query mathematically implies
+ the predicate of the index.
+ <span class="productname">PostgreSQL</span> does not have a sophisticated
+ theorem prover that can recognize mathematically equivalent
+ expressions that are written in different forms. (Not
+ only is such a general theorem prover extremely difficult to
+ create, it would probably be too slow to be of any real use.)
+ The system can recognize simple inequality implications, for example
+ <span class="quote">“<span class="quote">x &lt; 1</span>”</span> implies <span class="quote">“<span class="quote">x &lt; 2</span>”</span>; otherwise
+ the predicate condition must exactly match part of the query's
+ <code class="literal">WHERE</code> condition
+ or the index will not be recognized as usable. Matching takes
+ place at query planning time, not at run time. As a result,
+ parameterized query clauses do not work with a partial index. For
+ example a prepared query with a parameter might specify
+ <span class="quote">“<span class="quote">x &lt; ?</span>”</span> which will never imply
+ <span class="quote">“<span class="quote">x &lt; 2</span>”</span> for all possible values of the parameter.
+ </p><p>
+ 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 <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX3" title="Example 11.3. Setting up a Partial Unique Index">Example 11.3</a>. This enforces uniqueness
+ among the rows that satisfy the index predicate, without constraining
+ those that do not.
+ </p><div class="example" id="INDEXES-PARTIAL-EX3"><p class="title"><strong>Example 11.3. Setting up a Partial Unique Index</strong></p><div class="example-contents"><p>
+ Suppose that we have a table describing test outcomes. We wish
+ to ensure that there is only one <span class="quote">“<span class="quote">successful</span>”</span> entry for
+ a given subject and target combination, but there might be any number of
+ <span class="quote">“<span class="quote">unsuccessful</span>”</span> entries. Here is one way to do it:
+</p><pre class="programlisting">
+CREATE TABLE tests (
+ subject text,
+ target text,
+ success boolean,
+ ...
+);
+
+CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
+ WHERE success;
+</pre><p>
+ This is a particularly efficient approach when there are few
+ successful tests and many unsuccessful ones. It is also possible to
+ allow only one null in a column by creating a unique partial index
+ with an <code class="literal">IS NULL</code> restriction.
+ </p></div></div><br class="example-break" /><p>
+ Finally, a partial index can also be used to override the system's
+ query plan choices. Also, data sets with peculiar
+ distributions might cause the system to use an index when it really
+ should not. In that case the index can be set up so that it is not
+ available for the offending query. Normally,
+ <span class="productname">PostgreSQL</span> makes reasonable choices about index
+ usage (e.g., it avoids them when retrieving common values, so the
+ earlier example really only saves index size, it is not required to
+ avoid index usage), and grossly incorrect plan choices are cause
+ for a bug report.
+ </p><p>
+ Keep in mind that setting up a partial index indicates that you
+ know at least as much as the query planner knows, in particular you
+ know when an index might be profitable. Forming this knowledge
+ requires experience and understanding of how indexes in
+ <span class="productname">PostgreSQL</span> work. In most cases, the
+ advantage of a partial index over a regular index will be minimal.
+ There are cases where they are quite counterproductive, as in <a class="xref" href="indexes-partial.html#INDEXES-PARTIAL-EX4" title="Example 11.4. Do Not Use Partial Indexes as a Substitute for Partitioning">Example 11.4</a>.
+ </p><div class="example" id="INDEXES-PARTIAL-EX4"><p class="title"><strong>Example 11.4. Do Not Use Partial Indexes as a Substitute for Partitioning</strong></p><div class="example-contents"><p>
+ You might be tempted to create a large set of non-overlapping partial
+ indexes, for example
+
+</p><pre class="programlisting">
+CREATE INDEX mytable_cat_1 ON mytable (data) WHERE category = 1;
+CREATE INDEX mytable_cat_2 ON mytable (data) WHERE category = 2;
+CREATE INDEX mytable_cat_3 ON mytable (data) WHERE category = 3;
+...
+CREATE INDEX mytable_cat_<em class="replaceable"><code>N</code></em> ON mytable (data) WHERE category = <em class="replaceable"><code>N</code></em>;
+</pre><p>
+
+ This is a bad idea! Almost certainly, you'll be better off with a
+ single non-partial index, declared like
+
+</p><pre class="programlisting">
+CREATE INDEX mytable_cat_data ON mytable (category, data);
+</pre><p>
+
+ (Put the category column first, for the reasons described in
+ <a class="xref" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Section 11.3</a>.) While a search in this larger
+ index might have to descend through a couple more tree levels than a
+ search in a smaller index, that's almost certainly going to be cheaper
+ than the planner effort needed to select the appropriate one of the
+ partial indexes. The core of the problem is that the system does not
+ understand the relationship among the partial indexes, and will
+ laboriously test each one to see if it's applicable to the current
+ query.
+ </p><p>
+ If your table is large enough that a single index really is a bad idea,
+ you should look into using partitioning instead (see
+ <a class="xref" href="ddl-partitioning.html" title="5.11. Table Partitioning">Section 5.11</a>). With that mechanism, the system
+ does understand that the tables and indexes are non-overlapping, so
+ far better performance is possible.
+ </p></div></div><br class="example-break" /><p>
+ More information about partial indexes can be found in <a class="xref" href="biblio.html#STON89B">[ston89b]</a>, <a class="xref" href="biblio.html#OLSON93" title="Partial indexing in POSTGRES: research project">[olson93]</a>, and <a class="xref" href="biblio.html#SESHADRI95">[seshadri95]</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.7. Indexes on Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.9. Index-Only Scans and Covering Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-types.html b/doc/src/sgml/html/indexes-types.html
new file mode 100644
index 0000000..e043b7b
--- /dev/null
+++ b/doc/src/sgml/html/indexes-types.html
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.2. Index Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-intro.html" title="11.1. Introduction" /><link rel="next" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.2. Index Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-intro.html" title="11.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-TYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.2. Index Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-BTREE">11.2.1. B-Tree</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-HASH">11.2.2. Hash</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPE-GIST">11.2.3. GiST</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPE-SPGIST">11.2.4. SP-GiST</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-GIN">11.2.5. GIN</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-BRIN">11.2.6. BRIN</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> provides several index types:
+ B-tree, Hash, GiST, SP-GiST, GIN, BRIN, and the extension <a class="link" href="bloom.html" title="F.7. bloom">bloom</a>.
+ Each index type uses a different
+ algorithm that is best suited to different types of queries.
+ By default, the <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE
+ INDEX</code></a> command creates
+ B-tree indexes, which fit the most common situations.
+ The other index types are selected by writing the keyword
+ <code class="literal">USING</code> followed by the index type name.
+ For example, to create a Hash index:
+</p><pre class="programlisting">
+CREATE INDEX <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table</code></em> USING HASH (<em class="replaceable"><code>column</code></em>);
+</pre><p>
+ </p><div class="sect2" id="INDEXES-TYPES-BTREE"><div class="titlepage"><div><div><h3 class="title">11.2.1. B-Tree</h3></div></div></div><a id="id-1.5.10.5.3.2" class="indexterm"></a><a id="id-1.5.10.5.3.3" class="indexterm"></a><p>
+ B-trees can handle equality and range queries on data that can be sorted
+ into some ordering.
+ In particular, the <span class="productname">PostgreSQL</span> query planner
+ will consider using a B-tree index whenever an indexed column is
+ involved in a comparison using one of these operators:
+
+</p><pre class="synopsis">
+&lt;   &lt;=   =   &gt;=   &gt;
+</pre><p>
+
+ Constructs equivalent to combinations of these operators, such as
+ <code class="literal">BETWEEN</code> and <code class="literal">IN</code>, can also be implemented with
+ a B-tree index search. Also, an <code class="literal">IS NULL</code> or <code class="literal">IS NOT
+ NULL</code> condition on an index column can be used with a B-tree index.
+ </p><p>
+ The optimizer can also use a B-tree index for queries involving the
+ pattern matching operators <code class="literal">LIKE</code> and <code class="literal">~</code>
+ <span class="emphasis"><em>if</em></span> the pattern is a constant and is anchored to
+ the beginning of the string — for example, <code class="literal">col LIKE
+ 'foo%'</code> or <code class="literal">col ~ '^foo'</code>, but not
+ <code class="literal">col LIKE '%bar'</code>. 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
+ <a class="xref" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Section 11.10</a> below. It is also possible to use
+ B-tree indexes for <code class="literal">ILIKE</code> and
+ <code class="literal">~*</code>, but only if the pattern starts with
+ non-alphabetic characters, i.e., characters that are not affected by
+ upper/lower case conversion.
+ </p><p>
+ B-tree indexes can also be used to retrieve data in sorted order.
+ This is not always faster than a simple scan and sort, but it is
+ often helpful.
+ </p></div><div class="sect2" id="INDEXES-TYPES-HASH"><div class="titlepage"><div><div><h3 class="title">11.2.2. Hash</h3></div></div></div><a id="id-1.5.10.5.4.2" class="indexterm"></a><a id="id-1.5.10.5.4.3" class="indexterm"></a><p>
+ Hash indexes store a 32-bit hash code derived from the
+ value of the indexed column. Hence,
+ such indexes can only handle simple equality comparisons.
+ The query planner will consider using a hash index whenever an
+ indexed column is involved in a comparison using the
+ equal operator:
+
+</p><pre class="synopsis">
+=
+</pre><p>
+ </p></div><div class="sect2" id="INDEXES-TYPE-GIST"><div class="titlepage"><div><div><h3 class="title">11.2.3. GiST</h3></div></div></div><a id="id-1.5.10.5.5.2" class="indexterm"></a><a id="id-1.5.10.5.5.3" class="indexterm"></a><p>
+ GiST indexes are not a single kind of index, but rather an infrastructure
+ within which many different indexing strategies can be implemented.
+ Accordingly, the particular operators with which a GiST index can be
+ used vary depending on the indexing strategy (the <em class="firstterm">operator
+ class</em>). As an example, the standard distribution of
+ <span class="productname">PostgreSQL</span> includes GiST operator classes
+ for several two-dimensional geometric data types, which support indexed
+ queries using these operators:
+
+</p><pre class="synopsis">
+&lt;&lt;   &amp;&lt;   &amp;&gt;   &gt;&gt;   &lt;&lt;|   &amp;&lt;|   |&amp;&gt;   |&gt;&gt;   @&gt;   &lt;@   ~=   &amp;&amp;
+</pre><p>
+
+ (See <a class="xref" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Section 9.11</a> for the meaning of
+ these operators.)
+ The GiST operator classes included in the standard distribution are
+ documented in <a class="xref" href="gist-builtin-opclasses.html#GIST-BUILTIN-OPCLASSES-TABLE" title="Table 68.1. Built-in GiST Operator Classes">Table 68.1</a>.
+ Many other GiST operator
+ classes are available in the <code class="literal">contrib</code> collection or as separate
+ projects. For more information see <a class="xref" href="gist.html" title="Chapter 68. GiST Indexes">Chapter 68</a>.
+ </p><p>
+ GiST indexes are also capable of optimizing <span class="quote">“<span class="quote">nearest-neighbor</span>”</span>
+ searches, such as
+</p><pre class="programlisting">
+SELECT * FROM places ORDER BY location &lt;-&gt; point '(101,456)' LIMIT 10;
+
+</pre><p>
+ 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 <a class="xref" href="gist-builtin-opclasses.html#GIST-BUILTIN-OPCLASSES-TABLE" title="Table 68.1. Built-in GiST Operator Classes">Table 68.1</a>, operators that can be
+ used in this way are listed in the column <span class="quote">“<span class="quote">Ordering Operators</span>”</span>.
+ </p></div><div class="sect2" id="INDEXES-TYPE-SPGIST"><div class="titlepage"><div><div><h3 class="title">11.2.4. SP-GiST</h3></div></div></div><a id="id-1.5.10.5.6.2" class="indexterm"></a><a id="id-1.5.10.5.6.3" class="indexterm"></a><p>
+ SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
+ various kinds of searches. SP-GiST permits implementation of a wide range
+ of different non-balanced disk-based data structures, such as quadtrees,
+ k-d trees, and radix trees (tries). As an example, the standard distribution of
+ <span class="productname">PostgreSQL</span> includes SP-GiST operator classes
+ for two-dimensional points, which support indexed
+ queries using these operators:
+
+</p><pre class="synopsis">
+&lt;&lt;   &gt;&gt;   ~=   &lt;@   &lt;&lt;|   |&gt;&gt;
+</pre><p>
+
+ (See <a class="xref" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Section 9.11</a> for the meaning of
+ these operators.)
+ The SP-GiST operator classes included in the standard distribution are
+ documented in <a class="xref" href="spgist-builtin-opclasses.html#SPGIST-BUILTIN-OPCLASSES-TABLE" title="Table 69.1. Built-in SP-GiST Operator Classes">Table 69.1</a>.
+ For more information see <a class="xref" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Chapter 69</a>.
+ </p><p>
+ Like GiST, SP-GiST supports <span class="quote">“<span class="quote">nearest-neighbor</span>”</span> searches.
+ For SP-GiST operator classes that support distance ordering, the
+ corresponding operator is listed in the <span class="quote">“<span class="quote">Ordering Operators</span>”</span>
+ column in <a class="xref" href="spgist-builtin-opclasses.html#SPGIST-BUILTIN-OPCLASSES-TABLE" title="Table 69.1. Built-in SP-GiST Operator Classes">Table 69.1</a>.
+ </p></div><div class="sect2" id="INDEXES-TYPES-GIN"><div class="titlepage"><div><div><h3 class="title">11.2.5. GIN</h3></div></div></div><a id="id-1.5.10.5.7.2" class="indexterm"></a><a id="id-1.5.10.5.7.3" class="indexterm"></a><p>
+ GIN indexes are <span class="quote">“<span class="quote">inverted indexes</span>”</span> which are appropriate for
+ data values that contain multiple component values, such as arrays. An
+ inverted index contains a separate entry for each component value, and
+ can efficiently handle queries that test for the presence of specific
+ component values.
+ </p><p>
+ Like GiST and SP-GiST, GIN can support
+ many different user-defined indexing strategies, and the particular
+ operators with which a GIN index can be used vary depending on the
+ indexing strategy.
+ As an example, the standard distribution of
+ <span class="productname">PostgreSQL</span> includes a GIN operator class
+ for arrays, which supports indexed queries using these operators:
+
+</p><pre class="synopsis">
+&lt;@   @&gt;   =   &amp;&amp;
+</pre><p>
+
+ (See <a class="xref" href="functions-array.html" title="9.19. Array Functions and Operators">Section 9.19</a> for the meaning of
+ these operators.)
+ The GIN operator classes included in the standard distribution are
+ documented in <a class="xref" href="gin-builtin-opclasses.html#GIN-BUILTIN-OPCLASSES-TABLE" title="Table 70.1. Built-in GIN Operator Classes">Table 70.1</a>.
+ Many other GIN operator
+ classes are available in the <code class="literal">contrib</code> collection or as separate
+ projects. For more information see <a class="xref" href="gin.html" title="Chapter 70. GIN Indexes">Chapter 70</a>.
+ </p></div><div class="sect2" id="INDEXES-TYPES-BRIN"><div class="titlepage"><div><div><h3 class="title">11.2.6. BRIN</h3></div></div></div><a id="id-1.5.10.5.8.2" class="indexterm"></a><a id="id-1.5.10.5.8.3" class="indexterm"></a><p>
+ BRIN indexes (a shorthand for Block Range INdexes) store summaries about
+ the values stored in consecutive physical block ranges of a table.
+ Thus, they are most effective for columns whose values are well-correlated
+ with the physical order of the table rows.
+ Like GiST, SP-GiST and GIN,
+ BRIN can support many different indexing strategies,
+ and the particular operators with which a BRIN index can be used
+ vary depending on the indexing strategy.
+ For data types that have a linear sort order, the indexed data
+ corresponds to the minimum and maximum values of the
+ values in the column for each block range. This supports indexed queries
+ using these operators:
+
+</p><pre class="synopsis">
+&lt;   &lt;=   =   &gt;=   &gt;
+</pre><p>
+
+ The BRIN operator classes included in the standard distribution are
+ documented in <a class="xref" href="brin-builtin-opclasses.html#BRIN-BUILTIN-OPCLASSES-TABLE" title="Table 71.1. Built-in BRIN Operator Classes">Table 71.1</a>.
+ For more information see <a class="xref" href="brin.html" title="Chapter 71. BRIN Indexes">Chapter 71</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-intro.html" title="11.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-multicolumn.html" title="11.3. Multicolumn Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.3. Multicolumn Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes-unique.html b/doc/src/sgml/html/indexes-unique.html
new file mode 100644
index 0000000..0292b08
--- /dev/null
+++ b/doc/src/sgml/html/indexes-unique.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>11.6. Unique Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes" /><link rel="next" href="indexes-expressional.html" title="11.7. Indexes on Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">11.6. Unique Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><th width="60%" align="center">Chapter 11. Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEXES-UNIQUE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">11.6. Unique Indexes</h2></div></div></div><a id="id-1.5.10.9.2" class="indexterm"></a><p>
+ Indexes can also be used to enforce uniqueness of a column's value,
+ or the uniqueness of the combined values of more than one column.
+</p><pre class="synopsis">
+CREATE UNIQUE INDEX <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table</code></em> (<em class="replaceable"><code>column</code></em> [<span class="optional">, ...</span>]) [<span class="optional"> NULLS [<span class="optional"> NOT </span>] DISTINCT </span>];
+</pre><p>
+ Currently, only B-tree indexes can be declared unique.
+ </p><p>
+ When an index is declared unique, multiple table rows with equal
+ indexed values are not allowed. By default, null values in a unique column
+ are not considered equal, allowing multiple nulls in the column. The
+ <code class="literal">NULLS NOT DISTINCT</code> option modifies this and causes the
+ index to treat nulls as equal. A multicolumn unique index will only reject
+ cases where all indexed columns are equal in multiple rows.
+ </p><p>
+ <span class="productname">PostgreSQL</span> automatically creates a unique
+ index when a unique constraint or primary key is defined for a table.
+ The index covers the columns that make up the primary key or unique
+ constraint (a multicolumn index, if appropriate), and is the mechanism
+ that enforces the constraint.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ There's no need to manually
+ create indexes on unique columns; doing so would just duplicate
+ the automatically-created index.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-bitmap-scans.html" title="11.5. Combining Multiple Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexes.html" title="Chapter 11. Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.5. Combining Multiple Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.7. Indexes on Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/indexes.html b/doc/src/sgml/html/indexes.html
new file mode 100644
index 0000000..9435142
--- /dev/null
+++ b/doc/src/sgml/html/indexes.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 11. Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-select.html" title="10.6. SELECT Output Columns" /><link rel="next" href="indexes-intro.html" title="11.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 11. Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-select.html" title="10.6. SELECT Output Columns">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes-intro.html" title="11.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="INDEXES"><div class="titlepage"><div><div><h2 class="title">Chapter 11. Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="indexes-intro.html">11.1. Introduction</a></span></dt><dt><span class="sect1"><a href="indexes-types.html">11.2. Index Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-BTREE">11.2.1. B-Tree</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-HASH">11.2.2. Hash</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPE-GIST">11.2.3. GiST</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPE-SPGIST">11.2.4. SP-GiST</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-GIN">11.2.5. GIN</a></span></dt><dt><span class="sect2"><a href="indexes-types.html#INDEXES-TYPES-BRIN">11.2.6. BRIN</a></span></dt></dl></dd><dt><span class="sect1"><a href="indexes-multicolumn.html">11.3. Multicolumn Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-ordering.html">11.4. Indexes and <code class="literal">ORDER BY</code></a></span></dt><dt><span class="sect1"><a href="indexes-bitmap-scans.html">11.5. Combining Multiple Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-unique.html">11.6. Unique Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-expressional.html">11.7. Indexes on Expressions</a></span></dt><dt><span class="sect1"><a href="indexes-partial.html">11.8. Partial Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-index-only-scans.html">11.9. Index-Only Scans and Covering Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-opclass.html">11.10. Operator Classes and Operator Families</a></span></dt><dt><span class="sect1"><a href="indexes-collations.html">11.11. Indexes and Collations</a></span></dt><dt><span class="sect1"><a href="indexes-examine.html">11.12. Examining Index Usage</a></span></dt></dl></div><a id="id-1.5.10.2" class="indexterm"></a><p>
+ Indexes are a common way to enhance database performance. An index
+ allows the database server to find and retrieve specific rows much
+ faster than it could do without an index. But indexes also add
+ overhead to the database system as a whole, so they should be used
+ sensibly.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-select.html" title="10.6. SELECT Output Columns">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes-intro.html" title="11.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.6. <code class="literal">SELECT</code> Output Columns </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 11.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/information-schema.html b/doc/src/sgml/html/information-schema.html
new file mode 100644
index 0000000..4a67c76
--- /dev/null
+++ b/doc/src/sgml/html/information-schema.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 37. The Information Schema</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ecpg-develop.html" title="36.17. Internals" /><link rel="next" href="infoschema-schema.html" title="37.1. The Schema" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 37. The Information Schema</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ecpg-develop.html" title="36.17. Internals">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><th width="60%" align="center">Part IV. Client Interfaces</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-schema.html" title="37.1. The Schema">Next</a></td></tr></table><hr /></div><div class="chapter" id="INFORMATION-SCHEMA"><div class="titlepage"><div><div><h2 class="title">Chapter 37. The Information Schema</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="infoschema-schema.html">37.1. The Schema</a></span></dt><dt><span class="sect1"><a href="infoschema-datatypes.html">37.2. Data Types</a></span></dt><dt><span class="sect1"><a href="infoschema-information-schema-catalog-name.html">37.3. <code class="literal">information_schema_catalog_name</code></a></span></dt><dt><span class="sect1"><a href="infoschema-administrable-role-authorizations.html">37.4. <code class="literal">administrable_role_​authorizations</code></a></span></dt><dt><span class="sect1"><a href="infoschema-applicable-roles.html">37.5. <code class="literal">applicable_roles</code></a></span></dt><dt><span class="sect1"><a href="infoschema-attributes.html">37.6. <code class="literal">attributes</code></a></span></dt><dt><span class="sect1"><a href="infoschema-character-sets.html">37.7. <code class="literal">character_sets</code></a></span></dt><dt><span class="sect1"><a href="infoschema-check-constraint-routine-usage.html">37.8. <code class="literal">check_constraint_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-check-constraints.html">37.9. <code class="literal">check_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-collations.html">37.10. <code class="literal">collations</code></a></span></dt><dt><span class="sect1"><a href="infoschema-collation-character-set-applicab.html">37.11. <code class="literal">collation_character_set_​applicability</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-column-usage.html">37.12. <code class="literal">column_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-domain-usage.html">37.13. <code class="literal">column_domain_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-options.html">37.14. <code class="literal">column_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-privileges.html">37.15. <code class="literal">column_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-column-udt-usage.html">37.16. <code class="literal">column_udt_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-columns.html">37.17. <code class="literal">columns</code></a></span></dt><dt><span class="sect1"><a href="infoschema-constraint-column-usage.html">37.18. <code class="literal">constraint_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-constraint-table-usage.html">37.19. <code class="literal">constraint_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-data-type-privileges.html">37.20. <code class="literal">data_type_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domain-constraints.html">37.21. <code class="literal">domain_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domain-udt-usage.html">37.22. <code class="literal">domain_udt_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-domains.html">37.23. <code class="literal">domains</code></a></span></dt><dt><span class="sect1"><a href="infoschema-element-types.html">37.24. <code class="literal">element_types</code></a></span></dt><dt><span class="sect1"><a href="infoschema-enabled-roles.html">37.25. <code class="literal">enabled_roles</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-data-wrapper-options.html">37.26. <code class="literal">foreign_data_wrapper_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-data-wrappers.html">37.27. <code class="literal">foreign_data_wrappers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-server-options.html">37.28. <code class="literal">foreign_server_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-servers.html">37.29. <code class="literal">foreign_servers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-table-options.html">37.30. <code class="literal">foreign_table_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-foreign-tables.html">37.31. <code class="literal">foreign_tables</code></a></span></dt><dt><span class="sect1"><a href="infoschema-key-column-usage.html">37.32. <code class="literal">key_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-parameters.html">37.33. <code class="literal">parameters</code></a></span></dt><dt><span class="sect1"><a href="infoschema-referential-constraints.html">37.34. <code class="literal">referential_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-column-grants.html">37.35. <code class="literal">role_column_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-routine-grants.html">37.36. <code class="literal">role_routine_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-table-grants.html">37.37. <code class="literal">role_table_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-udt-grants.html">37.38. <code class="literal">role_udt_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-role-usage-grants.html">37.39. <code class="literal">role_usage_grants</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-column-usage.html">37.40. <code class="literal">routine_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-privileges.html">37.41. <code class="literal">routine_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-routine-usage.html">37.42. <code class="literal">routine_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-sequence-usage.html">37.43. <code class="literal">routine_sequence_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routine-table-usage.html">37.44. <code class="literal">routine_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-routines.html">37.45. <code class="literal">routines</code></a></span></dt><dt><span class="sect1"><a href="infoschema-schemata.html">37.46. <code class="literal">schemata</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sequences.html">37.47. <code class="literal">sequences</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-features.html">37.48. <code class="literal">sql_features</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-implementation-info.html">37.49. <code class="literal">sql_implementation_info</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-parts.html">37.50. <code class="literal">sql_parts</code></a></span></dt><dt><span class="sect1"><a href="infoschema-sql-sizing.html">37.51. <code class="literal">sql_sizing</code></a></span></dt><dt><span class="sect1"><a href="infoschema-table-constraints.html">37.52. <code class="literal">table_constraints</code></a></span></dt><dt><span class="sect1"><a href="infoschema-table-privileges.html">37.53. <code class="literal">table_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-tables.html">37.54. <code class="literal">tables</code></a></span></dt><dt><span class="sect1"><a href="infoschema-transforms.html">37.55. <code class="literal">transforms</code></a></span></dt><dt><span class="sect1"><a href="infoschema-triggered-update-columns.html">37.56. <code class="literal">triggered_update_columns</code></a></span></dt><dt><span class="sect1"><a href="infoschema-triggers.html">37.57. <code class="literal">triggers</code></a></span></dt><dt><span class="sect1"><a href="infoschema-udt-privileges.html">37.58. <code class="literal">udt_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-usage-privileges.html">37.59. <code class="literal">usage_privileges</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-defined-types.html">37.60. <code class="literal">user_defined_types</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-mapping-options.html">37.61. <code class="literal">user_mapping_options</code></a></span></dt><dt><span class="sect1"><a href="infoschema-user-mappings.html">37.62. <code class="literal">user_mappings</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-column-usage.html">37.63. <code class="literal">view_column_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-routine-usage.html">37.64. <code class="literal">view_routine_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-view-table-usage.html">37.65. <code class="literal">view_table_usage</code></a></span></dt><dt><span class="sect1"><a href="infoschema-views.html">37.66. <code class="literal">views</code></a></span></dt></dl></div><a id="id-1.7.6.2" class="indexterm"></a><p>
+ The information schema consists of a set of views that contain
+ information about the objects defined in the current database. The
+ information schema is defined in the SQL standard and can therefore
+ be expected to be portable and remain stable — unlike the system
+ catalogs, which are specific to
+ <span class="productname">PostgreSQL</span> and are modeled after
+ implementation concerns. The information schema views do not,
+ however, contain information about
+ <span class="productname">PostgreSQL</span>-specific features; to inquire
+ about those you need to query the system catalogs or other
+ <span class="productname">PostgreSQL</span>-specific views.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When querying the database for constraint information, it is possible
+ for a standard-compliant query that expects to return one row to
+ return several. This is because the SQL standard requires constraint
+ names to be unique within a schema, but
+ <span class="productname">PostgreSQL</span> does not enforce this
+ restriction. <span class="productname">PostgreSQL</span>
+ automatically-generated constraint names avoid duplicates in the
+ same schema, but users can specify such duplicate names.
+ </p><p>
+ This problem can appear when querying information schema views such
+ as <code class="literal">check_constraint_routine_usage</code>,
+ <code class="literal">check_constraints</code>, <code class="literal">domain_constraints</code>, and
+ <code class="literal">referential_constraints</code>. Some other views have similar
+ issues but contain the table name to help distinguish duplicate
+ rows, e.g., <code class="literal">constraint_column_usage</code>,
+ <code class="literal">constraint_table_usage</code>, <code class="literal">table_constraints</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ecpg-develop.html" title="36.17. Internals">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-schema.html" title="37.1. The Schema">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.17. Internals </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.1. The Schema</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-administrable-role-authorizations.html b/doc/src/sgml/html/infoschema-administrable-role-authorizations.html
new file mode 100644
index 0000000..fd33aa2
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-administrable-role-authorizations.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.4. administrable_role_​authorizations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name" /><link rel="next" href="infoschema-applicable-roles.html" title="37.5. applicable_roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.4. <code class="literal">administrable_role_​authorizations</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-applicable-roles.html" title="37.5. applicable_roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ADMINISTRABLE-ROLE-AUTHORIZATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.4. <code class="literal">administrable_role_​authorizations</code></h2></div></div></div><p>
+ The view <code class="literal">administrable_role_authorizations</code>
+ identifies all roles that the current user has the admin option
+ for.
+ </p><div class="table" id="id-1.7.6.8.3"><p class="title"><strong>Table 37.2. <code class="structname">administrable_role_authorizations</code> Columns</strong></p><div class="table-contents"><table class="table" summary="administrable_role_authorizations Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role to which this role membership was granted (can
+ be the current user, or a different role in case of nested role
+ memberships)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">role_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of a role
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Always <code class="literal">YES</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-applicable-roles.html" title="37.5. applicable_roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.3. <code class="literal">information_schema_catalog_name</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.5. <code class="literal">applicable_roles</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-applicable-roles.html b/doc/src/sgml/html/infoschema-applicable-roles.html
new file mode 100644
index 0000000..0b2d49e
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-applicable-roles.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.5. applicable_roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations" /><link rel="next" href="infoschema-attributes.html" title="37.6. attributes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.5. <code class="literal">applicable_roles</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-attributes.html" title="37.6. attributes">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-APPLICABLE-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.5. <code class="literal">applicable_roles</code></h2></div></div></div><p>
+ The view <code class="literal">applicable_roles</code> identifies all roles
+ whose privileges the current user can use. This means there is
+ some chain of role grants from the current user to the role in
+ question. The current user itself is also an applicable role. The
+ set of applicable roles is generally used for permission checking.
+ <a id="id-1.7.6.9.2.2" class="indexterm"></a>
+ <a id="id-1.7.6.9.2.3" class="indexterm"></a>
+ </p><div class="table" id="id-1.7.6.9.3"><p class="title"><strong>Table 37.3. <code class="structname">applicable_roles</code> Columns</strong></p><div class="table-contents"><table class="table" summary="applicable_roles Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role to which this role membership was granted (can
+ be the current user, or a different role in case of nested role
+ memberships)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">role_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of a role
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the grantee has the admin option on
+ the role, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-attributes.html" title="37.6. attributes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.4. <code class="literal">administrable_role_​authorizations</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.6. <code class="literal">attributes</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-attributes.html b/doc/src/sgml/html/infoschema-attributes.html
new file mode 100644
index 0000000..30c039d
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-attributes.html
@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.6. attributes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-applicable-roles.html" title="37.5. applicable_roles" /><link rel="next" href="infoschema-character-sets.html" title="37.7. character_sets" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.6. <code class="literal">attributes</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-applicable-roles.html" title="37.5. applicable_roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-character-sets.html" title="37.7. character_sets">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ATTRIBUTES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.6. <code class="literal">attributes</code></h2></div></div></div><p>
+ The view <code class="literal">attributes</code> contains information about
+ the attributes of composite data types defined in the database.
+ (Note that the view does not give information about table columns,
+ which are sometimes called attributes in PostgreSQL contexts.)
+ Only those attributes are shown that the current user has access to (by way
+ of being the owner of or having some privilege on the type).
+ </p><div class="table" id="id-1.7.6.10.3"><p class="title"><strong>Table 37.4. <code class="structname">attributes</code> Columns</strong></p><div class="table-contents"><table class="table" summary="attributes Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the data type (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attribute_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the attribute
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordinal_position</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Ordinal position of the attribute within the data type (count starts at 1)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attribute_default</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Default expression of the attribute
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_nullable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the attribute is possibly nullable,
+ <code class="literal">NO</code> if it is known not nullable.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Data type of the attribute, if it is a built-in type, or
+ <code class="literal">ARRAY</code> if it is some array (in that case, see
+ the view <code class="literal">element_types</code>), else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">attribute_udt_name</code> and
+ associated columns).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a character or bit
+ string type, the declared maximum length; null for all other
+ data types or if no maximum length was declared.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a character type,
+ the maximum possible length in octets (bytes) of a datum; null
+ for all other data types. The maximum octet length depends on
+ the declared character maximum length (see above) and the
+ server encoding.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation of the attribute
+ (always the current database), null if default or the data type
+ of the attribute is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation of the attribute,
+ null if default or the data type of the attribute is not
+ collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the collation of the attribute, null if default or the
+ data type of the attribute is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a numeric type, this
+ column contains the (declared or implicit) precision of the
+ type for this attribute. The precision indicates the number of
+ significant digits. It can be expressed in decimal (base 10)
+ or binary (base 2) terms, as specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a numeric type, this
+ column indicates in which base the values in the columns
+ <code class="literal">numeric_precision</code> and
+ <code class="literal">numeric_scale</code> are expressed. The value is
+ either 2 or 10. For all other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies an exact numeric
+ type, this column contains the (declared or implicit) scale of
+ the type for this attribute. The scale indicates the number of
+ significant digits to the right of the decimal point. It can
+ be expressed in decimal (base 10) or binary (base 2) terms, as
+ specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a date, time,
+ timestamp, or interval type, this column contains the (declared
+ or implicit) fractional seconds precision of the type for this
+ attribute, that is, the number of decimal digits maintained
+ following the decimal point in the seconds value. For all
+ other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies an interval type,
+ this column contains the specification which fields the
+ intervals include for this attribute, e.g., <code class="literal">YEAR TO
+ MONTH</code>, <code class="literal">DAY TO SECOND</code>, etc. If no
+ field restrictions were specified (that is, the interval
+ accepts all fields), and for all other data types, this field
+ is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available
+ in <span class="productname">PostgreSQL</span>
+ (see <code class="literal">datetime_precision</code> for the fractional
+ seconds precision of interval type attributes)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attribute_udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the attribute data type is defined in
+ (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attribute_udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the attribute data type is defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attribute_udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the attribute data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the column, unique
+ among the data type descriptors pertaining to the table. This
+ is mainly useful for joining with other instances of such
+ identifiers. (The specific format of the identifier is not
+ defined and not guaranteed to remain the same in future
+ versions.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_derived_reference_attribute</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ See also under <a class="xref" href="infoschema-columns.html" title="37.17. columns">Section 37.17</a>, a similarly
+ structured view, for further information on some of the columns.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-applicable-roles.html" title="37.5. applicable_roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-character-sets.html" title="37.7. character_sets">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.5. <code class="literal">applicable_roles</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.7. <code class="literal">character_sets</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-character-sets.html b/doc/src/sgml/html/infoschema-character-sets.html
new file mode 100644
index 0000000..ea75a22
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-character-sets.html
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.7. character_sets</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-attributes.html" title="37.6. attributes" /><link rel="next" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.7. <code class="literal">character_sets</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-attributes.html" title="37.6. attributes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-CHARACTER-SETS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.7. <code class="literal">character_sets</code></h2></div></div></div><p>
+ The view <code class="literal">character_sets</code> identifies the character
+ sets available in the current database. Since PostgreSQL does not
+ support multiple character sets within one database, this view only
+ shows one, which is the database encoding.
+ </p><p>
+ Take note of how the following terms are used in the SQL standard:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">character repertoire</span></dt><dd><p>
+ An abstract collection of characters, for
+ example <code class="literal">UNICODE</code>, <code class="literal">UCS</code>, or
+ <code class="literal">LATIN1</code>. Not exposed as an SQL object, but
+ visible in this view.
+ </p></dd><dt><span class="term">character encoding form</span></dt><dd><p>
+ An encoding of some character repertoire. Most older character
+ repertoires only use one encoding form, and so there are no
+ separate names for them (e.g., <code class="literal">LATIN1</code> is an
+ encoding form applicable to the <code class="literal">LATIN1</code>
+ repertoire). But for example Unicode has the encoding forms
+ <code class="literal">UTF8</code>, <code class="literal">UTF16</code>, etc. (not
+ all supported by PostgreSQL). Encoding forms are not exposed
+ as an SQL object, but are visible in this view.
+ </p></dd><dt><span class="term">character set</span></dt><dd><p>
+ A named SQL object that identifies a character repertoire, a
+ character encoding, and a default collation. A predefined
+ character set would typically have the same name as an encoding
+ form, but users could define other names. For example, the
+ character set <code class="literal">UTF8</code> would typically identify
+ the character repertoire <code class="literal">UCS</code>, encoding
+ form <code class="literal">UTF8</code>, and some default collation.
+ </p></dd></dl></div><p>
+
+ You can think of an <span class="quote">“<span class="quote">encoding</span>”</span> in PostgreSQL either as
+ a character set or a character encoding form. They will have the
+ same name, and there can only be one in one database.
+ </p><div class="table" id="id-1.7.6.11.4"><p class="title"><strong>Table 37.5. <code class="structname">character_sets</code> Columns</strong></p><div class="table-contents"><table class="table" summary="character_sets Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character sets are currently not implemented as schema objects, so this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character sets are currently not implemented as schema objects, so this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the character set, currently implemented as showing the name of the database encoding
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_repertoire</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character repertoire, showing <code class="literal">UCS</code> if the encoding is <code class="literal">UTF8</code>, else just the encoding name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">form_of_use</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character encoding form, same as the database encoding
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_collate_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the default collation (always the current database, if any collation is identified)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_collate_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the default collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_collate_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the default collation. The default collation is
+ identified as the collation that matches
+ the <code class="literal">COLLATE</code> and <code class="literal">CTYPE</code>
+ settings of the current database. If there is no such
+ collation, then this column and the associated schema and
+ catalog columns are null.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-attributes.html" title="37.6. attributes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.6. <code class="literal">attributes</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.8. <code class="literal">check_constraint_routine_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-check-constraint-routine-usage.html b/doc/src/sgml/html/infoschema-check-constraint-routine-usage.html
new file mode 100644
index 0000000..e11d7e1
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-check-constraint-routine-usage.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.8. check_constraint_routine_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-character-sets.html" title="37.7. character_sets" /><link rel="next" href="infoschema-check-constraints.html" title="37.9. check_constraints" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.8. <code class="literal">check_constraint_routine_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-character-sets.html" title="37.7. character_sets">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-check-constraints.html" title="37.9. check_constraints">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-CHECK-CONSTRAINT-ROUTINE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.8. <code class="literal">check_constraint_routine_usage</code></h2></div></div></div><p>
+ The view <code class="literal">check_constraint_routine_usage</code>
+ identifies routines (functions and procedures) that are used by a
+ check constraint. Only those routines are shown that are owned by
+ a currently enabled role.
+ </p><div class="table" id="id-1.7.6.12.3"><p class="title"><strong>Table 37.6. <code class="structname">check_constraint_routine_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="check_constraint_routine_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-character-sets.html" title="37.7. character_sets">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-check-constraints.html" title="37.9. check_constraints">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.7. <code class="literal">character_sets</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.9. <code class="literal">check_constraints</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-check-constraints.html b/doc/src/sgml/html/infoschema-check-constraints.html
new file mode 100644
index 0000000..54aa4d6
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-check-constraints.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.9. check_constraints</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage" /><link rel="next" href="infoschema-collations.html" title="37.10. collations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.9. <code class="literal">check_constraints</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-collations.html" title="37.10. collations">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-CHECK-CONSTRAINTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.9. <code class="literal">check_constraints</code></h2></div></div></div><p>
+ The view <code class="literal">check_constraints</code> contains all check
+ constraints, either defined on a table or on a domain, that are
+ owned by a currently enabled role. (The owner of the table or
+ domain is the owner of the constraint.)
+ </p><div class="table" id="id-1.7.6.13.3"><p class="title"><strong>Table 37.7. <code class="structname">check_constraints</code> Columns</strong></p><div class="table-contents"><table class="table" summary="check_constraints Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">check_clause</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The check expression of the check constraint
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-check-constraint-routine-usage.html" title="37.8. check_constraint_routine_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-collations.html" title="37.10. collations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.8. <code class="literal">check_constraint_routine_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.10. <code class="literal">collations</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-collation-character-set-applicab.html b/doc/src/sgml/html/infoschema-collation-character-set-applicab.html
new file mode 100644
index 0000000..852b699
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-collation-character-set-applicab.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.11. collation_character_set_​applicability</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-collations.html" title="37.10. collations" /><link rel="next" href="infoschema-column-column-usage.html" title="37.12. column_column_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.11. <code class="literal">collation_character_set_​applicability</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-collations.html" title="37.10. collations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-column-column-usage.html" title="37.12. column_column_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLLATION-CHARACTER-SET-APPLICAB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.11. <code class="literal">collation_character_set_​applicability</code></h2></div></div></div><p>
+ The view <code class="literal">collation_character_set_applicability</code>
+ identifies which character set the available collations are
+ applicable to. In PostgreSQL, there is only one character set per
+ database (see explanation
+ in <a class="xref" href="infoschema-character-sets.html" title="37.7. character_sets">Section 37.7</a>), so this view does
+ not provide much useful information.
+ </p><div class="table" id="id-1.7.6.15.3"><p class="title"><strong>Table 37.9. <code class="structname">collation_character_set_applicability</code> Columns</strong></p><div class="table-contents"><table class="table" summary="collation_character_set_applicability Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the default collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character sets are currently not implemented as schema objects, so this column is null
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Character sets are currently not implemented as schema objects, so this column is null
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the character set
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-collations.html" title="37.10. collations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-column-column-usage.html" title="37.12. column_column_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.10. <code class="literal">collations</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.12. <code class="literal">column_column_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-collations.html b/doc/src/sgml/html/infoschema-collations.html
new file mode 100644
index 0000000..5b7cdaa
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-collations.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.10. collations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-check-constraints.html" title="37.9. check_constraints" /><link rel="next" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.10. <code class="literal">collations</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-check-constraints.html" title="37.9. check_constraints">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLLATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.10. <code class="literal">collations</code></h2></div></div></div><p>
+ The view <code class="literal">collations</code> contains the collations
+ available in the current database.
+ </p><div class="table" id="id-1.7.6.14.3"><p class="title"><strong>Table 37.8. <code class="structname">collations</code> Columns</strong></p><div class="table-contents"><table class="table" summary="collations Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the default collation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pad_attribute</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">NO PAD</code> (The alternative <code class="literal">PAD
+ SPACE</code> is not supported by PostgreSQL.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-check-constraints.html" title="37.9. check_constraints">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.9. <code class="literal">check_constraints</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.11. <code class="literal">collation_character_set_​applicability</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-column-column-usage.html b/doc/src/sgml/html/infoschema-column-column-usage.html
new file mode 100644
index 0000000..a2e6bc4
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-column-column-usage.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.12. column_column_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability" /><link rel="next" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.12. <code class="literal">column_column_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMN-COLUMN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.12. <code class="literal">column_column_usage</code></h2></div></div></div><p>
+ The view <code class="literal">column_column_usage</code> identifies all generated
+ columns that depend on another base column in the same table. Only tables
+ owned by a currently enabled role are included.
+ </p><div class="table" id="id-1.7.6.16.3"><p class="title"><strong>Table 37.10. <code class="structname">column_column_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="column_column_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the base column that a generated column depends on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dependent_column</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the generated column
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-collation-character-set-applicab.html" title="37.11. collation_character_set_​applicability">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.11. <code class="literal">collation_character_set_​applicability</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.13. <code class="literal">column_domain_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-column-domain-usage.html b/doc/src/sgml/html/infoschema-column-domain-usage.html
new file mode 100644
index 0000000..f0ba135
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-column-domain-usage.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.13. column_domain_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-column-column-usage.html" title="37.12. column_column_usage" /><link rel="next" href="infoschema-column-options.html" title="37.14. column_options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.13. <code class="literal">column_domain_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-column-column-usage.html" title="37.12. column_column_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-column-options.html" title="37.14. column_options">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMN-DOMAIN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.13. <code class="literal">column_domain_usage</code></h2></div></div></div><p>
+ The view <code class="literal">column_domain_usage</code> identifies all
+ columns (of a table or a view) that make use of some domain defined
+ in the current database and owned by a currently enabled role.
+ </p><div class="table" id="id-1.7.6.17.3"><p class="title"><strong>Table 37.11. <code class="structname">column_domain_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="column_domain_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the domain (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-column-column-usage.html" title="37.12. column_column_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-column-options.html" title="37.14. column_options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.12. <code class="literal">column_column_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.14. <code class="literal">column_options</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-column-options.html b/doc/src/sgml/html/infoschema-column-options.html
new file mode 100644
index 0000000..faf5fdb
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-column-options.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.14. column_options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage" /><link rel="next" href="infoschema-column-privileges.html" title="37.15. column_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.14. <code class="literal">column_options</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-column-privileges.html" title="37.15. column_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMN-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.14. <code class="literal">column_options</code></h2></div></div></div><p>
+ The view <code class="literal">column_options</code> contains all the
+ options defined for foreign table columns in the current database. Only
+ those foreign table columns are shown that the current user has access to
+ (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.18.3"><p class="title"><strong>Table 37.12. <code class="structname">column_options</code> Columns</strong></p><div class="table-contents"><table class="table" summary="column_options Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the foreign table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of an option
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the option
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-column-domain-usage.html" title="37.13. column_domain_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-column-privileges.html" title="37.15. column_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.13. <code class="literal">column_domain_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.15. <code class="literal">column_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-column-privileges.html b/doc/src/sgml/html/infoschema-column-privileges.html
new file mode 100644
index 0000000..d54c026
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-column-privileges.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.15. column_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-column-options.html" title="37.14. column_options" /><link rel="next" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.15. <code class="literal">column_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-column-options.html" title="37.14. column_options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMN-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.15. <code class="literal">column_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">column_privileges</code> identifies all
+ privileges granted on columns to a currently enabled role or by a
+ currently enabled role. There is one row for each combination of
+ column, grantor, and grantee.
+ </p><p>
+ If a privilege has been granted on an entire table, it will show up in
+ this view as a grant for each column, but only for the
+ privilege types where column granularity is possible:
+ <code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, <code class="literal">REFERENCES</code>.
+ </p><div class="table" id="id-1.7.6.19.4"><p class="title"><strong>Table 37.13. <code class="structname">column_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="column_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that contains the column (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that contains the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that contains the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the privilege: <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or
+ <code class="literal">REFERENCES</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-column-options.html" title="37.14. column_options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.14. <code class="literal">column_options</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.16. <code class="literal">column_udt_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-column-udt-usage.html b/doc/src/sgml/html/infoschema-column-udt-usage.html
new file mode 100644
index 0000000..14a7cd3
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-column-udt-usage.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.16. column_udt_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-column-privileges.html" title="37.15. column_privileges" /><link rel="next" href="infoschema-columns.html" title="37.17. columns" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.16. <code class="literal">column_udt_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-column-privileges.html" title="37.15. column_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-columns.html" title="37.17. columns">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMN-UDT-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.16. <code class="literal">column_udt_usage</code></h2></div></div></div><p>
+ The view <code class="literal">column_udt_usage</code> identifies all columns
+ that use data types owned by a currently enabled role. Note that in
+ <span class="productname">PostgreSQL</span>, built-in data types behave
+ like user-defined types, so they are included here as well. See
+ also <a class="xref" href="infoschema-columns.html" title="37.17. columns">Section 37.17</a> for details.
+ </p><div class="table" id="id-1.7.6.20.3"><p class="title"><strong>Table 37.14. <code class="structname">column_udt_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="column_udt_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the column data type (the underlying
+ type of the domain, if applicable) is defined in (always the
+ current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the column data type (the underlying
+ type of the domain, if applicable) is defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column data type (the underlying type of the
+ domain, if applicable)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-column-privileges.html" title="37.15. column_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-columns.html" title="37.17. columns">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.15. <code class="literal">column_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.17. <code class="literal">columns</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-columns.html b/doc/src/sgml/html/infoschema-columns.html
new file mode 100644
index 0000000..f17f323
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-columns.html
@@ -0,0 +1,337 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.17. columns</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage" /><link rel="next" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.17. <code class="literal">columns</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-COLUMNS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.17. <code class="literal">columns</code></h2></div></div></div><p>
+ The view <code class="literal">columns</code> contains information about all
+ table columns (or view columns) in the database. System columns
+ (<code class="literal">ctid</code>, etc.) are not included. Only those columns are
+ shown that the current user has access to (by way of being the
+ owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.21.3"><p class="title"><strong>Table 37.15. <code class="structname">columns</code> Columns</strong></p><div class="table-contents"><table class="table" summary="columns Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordinal_position</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Ordinal position of the column within the table (count starts at 1)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_default</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Default expression of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_nullable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the column is possibly nullable,
+ <code class="literal">NO</code> if it is known not nullable. A not-null
+ constraint is one way a column can be known not nullable, but
+ there can be others.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Data type of the column, if it is a built-in type, or
+ <code class="literal">ARRAY</code> if it is some array (in that case, see
+ the view <code class="literal">element_types</code>), else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">udt_name</code> and associated
+ columns). If the column is based on a domain, this column
+ refers to the type underlying the domain (and the domain is
+ identified in <code class="literal">domain_name</code> and associated
+ columns).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a character or bit
+ string type, the declared maximum length; null for all other
+ data types or if no maximum length was declared.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a character type,
+ the maximum possible length in octets (bytes) of a datum; null
+ for all other data types. The maximum octet length depends on
+ the declared character maximum length (see above) and the
+ server encoding.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a numeric type, this
+ column contains the (declared or implicit) precision of the
+ type for this column. The precision indicates the number of
+ significant digits. It can be expressed in decimal (base 10)
+ or binary (base 2) terms, as specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a numeric type, this
+ column indicates in which base the values in the columns
+ <code class="literal">numeric_precision</code> and
+ <code class="literal">numeric_scale</code> are expressed. The value is
+ either 2 or 10. For all other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies an exact numeric
+ type, this column contains the (declared or implicit) scale of
+ the type for this column. The scale indicates the number of
+ significant digits to the right of the decimal point. It can
+ be expressed in decimal (base 10) or binary (base 2) terms, as
+ specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a date, time,
+ timestamp, or interval type, this column contains the (declared
+ or implicit) fractional seconds precision of the type for this
+ column, that is, the number of decimal digits maintained
+ following the decimal point in the seconds value. For all
+ other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies an interval type,
+ this column contains the specification which fields the
+ intervals include for this column, e.g., <code class="literal">YEAR TO
+ MONTH</code>, <code class="literal">DAY TO SECOND</code>, etc. If no
+ field restrictions were specified (that is, the interval
+ accepts all fields), and for all other data types, this field
+ is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available
+ in <span class="productname">PostgreSQL</span>
+ (see <code class="literal">datetime_precision</code> for the fractional
+ seconds precision of interval type columns)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation of the column
+ (always the current database), null if default or the data type
+ of the column is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation of the column, null
+ if default or the data type of the column is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the collation of the column, null if default or the
+ data type of the column is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the column has a domain type, the name of the database that
+ the domain is defined in (always the current database), else
+ null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the column has a domain type, the name of the schema that
+ the domain is defined in, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the column has a domain type, the name of the domain, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the column data type (the underlying
+ type of the domain, if applicable) is defined in (always the
+ current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the column data type (the underlying
+ type of the domain, if applicable) is defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column data type (the underlying type of the
+ domain, if applicable)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the column, unique
+ among the data type descriptors pertaining to the table. This
+ is mainly useful for joining with other instances of such
+ identifiers. (The specific format of the identifier is not
+ defined and not guaranteed to remain the same in future
+ versions.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_self_referencing</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_identity</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ If the column is an identity column, then <code class="literal">YES</code>,
+ else <code class="literal">NO</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_generation</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is an identity column, then <code class="literal">ALWAYS</code>
+ or <code class="literal">BY DEFAULT</code>, reflecting the definition of the
+ column.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_start</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is an identity column, then the start value of the
+ internal sequence, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_increment</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is an identity column, then the increment of the internal
+ sequence, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_maximum</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is an identity column, then the maximum value of the
+ internal sequence, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_minimum</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is an identity column, then the minimum value of the
+ internal sequence, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">identity_cycle</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ If the column is an identity column, then <code class="literal">YES</code> if the
+ internal sequence cycles or <code class="literal">NO</code> if it does not;
+ otherwise null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_generated</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is a generated column, then <code class="literal">ALWAYS</code>,
+ else <code class="literal">NEVER</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">generation_expression</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the column is a generated column, then the generation expression,
+ else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_updatable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the column is updatable,
+ <code class="literal">NO</code> if not (Columns in base tables are always
+ updatable, columns in views not necessarily)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Since data types can be defined in a variety of ways in SQL, and
+ <span class="productname">PostgreSQL</span> contains additional ways to
+ define data types, their representation in the information schema
+ can be somewhat difficult. The column <code class="literal">data_type</code>
+ is supposed to identify the underlying built-in type of the column.
+ In <span class="productname">PostgreSQL</span>, this means that the type
+ is defined in the system catalog schema
+ <code class="literal">pg_catalog</code>. This column might be useful if the
+ application can handle the well-known built-in types specially (for
+ example, format the numeric types differently or use the data in
+ the precision columns). The columns <code class="literal">udt_name</code>,
+ <code class="literal">udt_schema</code>, and <code class="literal">udt_catalog</code>
+ always identify the underlying data type of the column, even if the
+ column is based on a domain. (Since
+ <span class="productname">PostgreSQL</span> treats built-in types like
+ user-defined types, built-in types appear here as well. This is an
+ extension of the SQL standard.) These columns should be used if an
+ application wants to process data differently according to the
+ type, because in that case it wouldn't matter if the column is
+ really based on a domain. If the column is based on a domain, the
+ identity of the domain is stored in the columns
+ <code class="literal">domain_name</code>, <code class="literal">domain_schema</code>,
+ and <code class="literal">domain_catalog</code>. If you want to pair up
+ columns with their associated data types and treat domains as
+ separate types, you could write <code class="literal">coalesce(domain_name,
+ udt_name)</code>, etc.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-column-udt-usage.html" title="37.16. column_udt_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.16. <code class="literal">column_udt_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.18. <code class="literal">constraint_column_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-constraint-column-usage.html b/doc/src/sgml/html/infoschema-constraint-column-usage.html
new file mode 100644
index 0000000..c19d338
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-constraint-column-usage.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.18. constraint_column_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-columns.html" title="37.17. columns" /><link rel="next" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.18. <code class="literal">constraint_column_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-columns.html" title="37.17. columns">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-CONSTRAINT-COLUMN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.18. <code class="literal">constraint_column_usage</code></h2></div></div></div><p>
+ The view <code class="literal">constraint_column_usage</code> identifies all
+ columns in the current database that are used by some constraint.
+ Only those columns are shown that are contained in a table owned by
+ a currently enabled role. For a check constraint, this view
+ identifies the columns that are used in the check expression. For
+ a foreign key constraint, this view identifies the columns that the
+ foreign key references. For a unique or primary key constraint,
+ this view identifies the constrained columns.
+ </p><div class="table" id="id-1.7.6.22.3"><p class="title"><strong>Table 37.16. <code class="structname">constraint_column_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="constraint_column_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that contains the
+ column that is used by some constraint (always the current
+ database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that contains the
+ column that is used by some constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that contains the column that is used by some
+ constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column that is used by some constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-columns.html" title="37.17. columns">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.17. <code class="literal">columns</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.19. <code class="literal">constraint_table_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-constraint-table-usage.html b/doc/src/sgml/html/infoschema-constraint-table-usage.html
new file mode 100644
index 0000000..9899278
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-constraint-table-usage.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.19. constraint_table_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage" /><link rel="next" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.19. <code class="literal">constraint_table_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-CONSTRAINT-TABLE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.19. <code class="literal">constraint_table_usage</code></h2></div></div></div><p>
+ The view <code class="literal">constraint_table_usage</code> identifies all
+ tables in the current database that are used by some constraint and
+ are owned by a currently enabled role. (This is different from the
+ view <code class="literal">table_constraints</code>, which identifies all
+ table constraints along with the table they are defined on.) For a
+ foreign key constraint, this view identifies the table that the
+ foreign key references. For a unique or primary key constraint,
+ this view simply identifies the table the constraint belongs to.
+ Check constraints and not-null constraints are not included in this
+ view.
+ </p><div class="table" id="id-1.7.6.23.3"><p class="title"><strong>Table 37.17. <code class="structname">constraint_table_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="constraint_table_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that is used by
+ some constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that is used by some
+ constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that is used by some constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-constraint-column-usage.html" title="37.18. constraint_column_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.18. <code class="literal">constraint_column_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.20. <code class="literal">data_type_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-data-type-privileges.html b/doc/src/sgml/html/infoschema-data-type-privileges.html
new file mode 100644
index 0000000..811ab2d
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-data-type-privileges.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.20. data_type_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage" /><link rel="next" href="infoschema-domain-constraints.html" title="37.21. domain_constraints" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.20. <code class="literal">data_type_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-domain-constraints.html" title="37.21. domain_constraints">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-DATA-TYPE-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.20. <code class="literal">data_type_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">data_type_privileges</code> identifies all
+ data type descriptors that the current user has access to, by way
+ of being the owner of the described object or having some privilege
+ for it. A data type descriptor is generated whenever a data type
+ is used in the definition of a table column, a domain, or a
+ function (as parameter or return type) and stores some information
+ about how the data type is used in that instance (for example, the
+ declared maximum length, if applicable). Each data type
+ descriptor is assigned an arbitrary identifier that is unique
+ among the data type descriptor identifiers assigned for one object
+ (table, domain, function). This view is probably not useful for
+ applications, but it is used to define some other views in the
+ information schema.
+ </p><div class="table" id="id-1.7.6.24.3"><p class="title"><strong>Table 37.18. <code class="structname">data_type_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="data_type_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the described object (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the described object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the described object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The type of the described object: one of
+ <code class="literal">TABLE</code> (the data type descriptor pertains to
+ a column of that table), <code class="literal">DOMAIN</code> (the data
+ type descriptors pertains to that domain),
+ <code class="literal">ROUTINE</code> (the data type descriptor pertains
+ to a parameter or the return data type of that function).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The identifier of the data type descriptor, which is unique
+ among the data type descriptors for that same object.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-constraint-table-usage.html" title="37.19. constraint_table_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-domain-constraints.html" title="37.21. domain_constraints">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.19. <code class="literal">constraint_table_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.21. <code class="literal">domain_constraints</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-datatypes.html b/doc/src/sgml/html/infoschema-datatypes.html
new file mode 100644
index 0000000..be6021e
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-datatypes.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.2. Data Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-schema.html" title="37.1. The Schema" /><link rel="next" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.2. Data Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-schema.html" title="37.1. The Schema">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-DATATYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.2. Data Types</h2></div></div></div><p>
+ The columns of the information schema views use special data types
+ that are defined in the information schema. These are defined as
+ simple domains over ordinary built-in types. You should not use
+ these types for work outside the information schema, but your
+ applications must be prepared for them if they select from the
+ information schema.
+ </p><p>
+ These types are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="type">cardinal_number</code></span></dt><dd><p>
+ A nonnegative integer.
+ </p></dd><dt><span class="term"><code class="type">character_data</code></span></dt><dd><p>
+ A character string (without specific maximum length).
+ </p></dd><dt><span class="term"><code class="type">sql_identifier</code></span></dt><dd><p>
+ A character string. This type is used for SQL identifiers, the
+ type <code class="type">character_data</code> is used for any other kind of
+ text data.
+ </p></dd><dt><span class="term"><code class="type">time_stamp</code></span></dt><dd><p>
+ A domain over the type <code class="type">timestamp with time zone</code>
+ </p></dd><dt><span class="term"><code class="type">yes_or_no</code></span></dt><dd><p>
+ A character string domain that contains
+ either <code class="literal">YES</code> or <code class="literal">NO</code>. This
+ is used to represent Boolean (true/false) data in the
+ information schema. (The information schema was invented
+ before the type <code class="type">boolean</code> was added to the SQL
+ standard, so this convention is necessary to keep the
+ information schema backward compatible.)
+ </p></dd></dl></div><p>
+
+ Every column in the information schema has one of these five types.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-schema.html" title="37.1. The Schema">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-information-schema-catalog-name.html" title="37.3. information_schema_catalog_name">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.1. The Schema </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.3. <code class="literal">information_schema_catalog_name</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-domain-constraints.html b/doc/src/sgml/html/infoschema-domain-constraints.html
new file mode 100644
index 0000000..a46a0e7
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-domain-constraints.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.21. domain_constraints</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges" /><link rel="next" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.21. <code class="literal">domain_constraints</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-DOMAIN-CONSTRAINTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.21. <code class="literal">domain_constraints</code></h2></div></div></div><p>
+ The view <code class="literal">domain_constraints</code> contains all constraints
+ belonging to domains defined in the current database. Only those domains
+ are shown that the current user has access to (by way of being the owner or
+ having some privilege).
+ </p><div class="table" id="id-1.7.6.25.3"><p class="title"><strong>Table 37.19. <code class="structname">domain_constraints</code> Columns</strong></p><div class="table-contents"><table class="table" summary="domain_constraints Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the domain (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_deferrable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the constraint is deferrable, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">initially_deferred</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the constraint is deferrable and initially deferred, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-data-type-privileges.html" title="37.20. data_type_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.20. <code class="literal">data_type_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.22. <code class="literal">domain_udt_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-domain-udt-usage.html b/doc/src/sgml/html/infoschema-domain-udt-usage.html
new file mode 100644
index 0000000..5335780
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-domain-udt-usage.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.22. domain_udt_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-domain-constraints.html" title="37.21. domain_constraints" /><link rel="next" href="infoschema-domains.html" title="37.23. domains" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.22. <code class="literal">domain_udt_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-domain-constraints.html" title="37.21. domain_constraints">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-domains.html" title="37.23. domains">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-DOMAIN-UDT-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.22. <code class="literal">domain_udt_usage</code></h2></div></div></div><p>
+ The view <code class="literal">domain_udt_usage</code> identifies all domains
+ that are based on data types owned by a currently enabled role.
+ Note that in <span class="productname">PostgreSQL</span>, built-in data
+ types behave like user-defined types, so they are included here as
+ well.
+ </p><div class="table" id="id-1.7.6.26.3"><p class="title"><strong>Table 37.20. <code class="structname">domain_udt_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="domain_udt_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the domain data type is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the domain data type is defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the domain (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-domain-constraints.html" title="37.21. domain_constraints">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-domains.html" title="37.23. domains">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.21. <code class="literal">domain_constraints</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.23. <code class="literal">domains</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-domains.html b/doc/src/sgml/html/infoschema-domains.html
new file mode 100644
index 0000000..f829624
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-domains.html
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.23. domains</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage" /><link rel="next" href="infoschema-element-types.html" title="37.24. element_types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.23. <code class="literal">domains</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-element-types.html" title="37.24. element_types">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-DOMAINS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.23. <code class="literal">domains</code></h2></div></div></div><p>
+ The view <code class="literal">domains</code> contains all
+ <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domains</a></em></a> defined in the
+ current database. Only those domains are shown that the current user has
+ access to (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.27.3"><p class="title"><strong>Table 37.21. <code class="structname">domains</code> Columns</strong></p><div class="table-contents"><table class="table" summary="domains Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the domain (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Data type of the domain, if it is a built-in type, or
+ <code class="literal">ARRAY</code> if it is some array (in that case, see
+ the view <code class="literal">element_types</code>), else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">udt_name</code> and associated
+ columns).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If the domain has a character or bit string type, the declared
+ maximum length; null for all other data types or if no maximum
+ length was declared.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If the domain has a character type, the maximum possible length
+ in octets (bytes) of a datum; null for all other data types.
+ The maximum octet length depends on the declared character
+ maximum length (see above) and the server encoding.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation of the domain
+ (always the current database), null if default or the data type
+ of the domain is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation of the domain, null
+ if default or the data type of the domain is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the collation of the domain, null if default or the
+ data type of the domain is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If the domain has a numeric type, this column contains the
+ (declared or implicit) precision of the type for this domain.
+ The precision indicates the number of significant digits. It
+ can be expressed in decimal (base 10) or binary (base 2) terms,
+ as specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If the domain has a numeric type, this column indicates in
+ which base the values in the columns
+ <code class="literal">numeric_precision</code> and
+ <code class="literal">numeric_scale</code> are expressed. The value is
+ either 2 or 10. For all other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If the domain has an exact numeric type, this column contains
+ the (declared or implicit) scale of the type for this domain.
+ The scale indicates the number of significant digits to the
+ right of the decimal point. It can be expressed in decimal
+ (base 10) or binary (base 2) terms, as specified in the column
+ <code class="literal">numeric_precision_radix</code>. For all other data
+ types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies a date, time,
+ timestamp, or interval type, this column contains the (declared
+ or implicit) fractional seconds precision of the type for this
+ domain, that is, the number of decimal digits maintained
+ following the decimal point in the seconds value. For all
+ other data types, this column is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If <code class="literal">data_type</code> identifies an interval type,
+ this column contains the specification which fields the
+ intervals include for this domain, e.g., <code class="literal">YEAR TO
+ MONTH</code>, <code class="literal">DAY TO SECOND</code>, etc. If no
+ field restrictions were specified (that is, the interval
+ accepts all fields), and for all other data types, this field
+ is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available
+ in <span class="productname">PostgreSQL</span>
+ (see <code class="literal">datetime_precision</code> for the fractional
+ seconds precision of interval type domains)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_default</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Default expression of the domain
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the domain data type is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the domain data type is defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the domain data type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the domain, unique
+ among the data type descriptors pertaining to the domain (which
+ is trivial, because a domain only contains one data type
+ descriptor). This is mainly useful for joining with other
+ instances of such identifiers. (The specific format of the
+ identifier is not defined and not guaranteed to remain the same
+ in future versions.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-domain-udt-usage.html" title="37.22. domain_udt_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-element-types.html" title="37.24. element_types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.22. <code class="literal">domain_udt_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.24. <code class="literal">element_types</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-element-types.html b/doc/src/sgml/html/infoschema-element-types.html
new file mode 100644
index 0000000..c513cc3
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-element-types.html
@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.24. element_types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-domains.html" title="37.23. domains" /><link rel="next" href="infoschema-enabled-roles.html" title="37.25. enabled_roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.24. <code class="literal">element_types</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-domains.html" title="37.23. domains">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-enabled-roles.html" title="37.25. enabled_roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ELEMENT-TYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.24. <code class="literal">element_types</code></h2></div></div></div><p>
+ The view <code class="literal">element_types</code> contains the data type
+ descriptors of the elements of arrays. When a table column, composite-type attribute,
+ domain, function parameter, or function return value is defined to
+ be of an array type, the respective information schema view only
+ contains <code class="literal">ARRAY</code> in the column
+ <code class="literal">data_type</code>. To obtain information on the element
+ type of the array, you can join the respective view with this view.
+ For example, to show the columns of a table with data types and
+ array element types, if applicable, you could do:
+</p><pre class="programlisting">
+SELECT c.column_name, c.data_type, e.data_type AS element_type
+FROM information_schema.columns c LEFT JOIN information_schema.element_types e
+ ON ((c.table_catalog, c.table_schema, c.table_name, 'TABLE', c.dtd_identifier)
+ = (e.object_catalog, e.object_schema, e.object_name, e.object_type, e.collection_type_identifier))
+WHERE c.table_schema = '...' AND c.table_name = '...'
+ORDER BY c.ordinal_position;
+</pre><p>
+ This view only includes objects that the current user has access
+ to, by way of being the owner or having some privilege.
+ </p><div class="table" id="id-1.7.6.28.3"><p class="title"><strong>Table 37.22. <code class="structname">element_types</code> Columns</strong></p><div class="table-contents"><table class="table" summary="element_types Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the object that uses the
+ array being described (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the object that uses the array
+ being described
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the object that uses the array being described
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The type of the object that uses the array being described: one
+ of <code class="literal">TABLE</code> (the array is used by a column of
+ that table), <code class="literal">USER-DEFINED TYPE</code> (the array is
+ used by an attribute of that composite type),
+ <code class="literal">DOMAIN</code> (the array is used by that domain),
+ <code class="literal">ROUTINE</code> (the array is used by a parameter or
+ the return data type of that function).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collection_type_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The identifier of the data type descriptor of the array being
+ described. Use this to join with the
+ <code class="literal">dtd_identifier</code> columns of other information
+ schema views.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Data type of the array elements, if it is a built-in type, else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">udt_name</code> and associated
+ columns).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the collation of the element
+ type (always the current database), null if default or the data
+ type of the element is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the collation of the element
+ type, null if default or the data type of the element is not
+ collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the collation of the element type, null if default or
+ the data type of the element is not collatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to array element data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">domain_default</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Not yet implemented
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the data type of the elements is
+ defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the data type of the elements is
+ defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the data type of the elements
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the element. This
+ is currently not useful.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-domains.html" title="37.23. domains">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-enabled-roles.html" title="37.25. enabled_roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.23. <code class="literal">domains</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.25. <code class="literal">enabled_roles</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-enabled-roles.html b/doc/src/sgml/html/infoschema-enabled-roles.html
new file mode 100644
index 0000000..9143758
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-enabled-roles.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.25. enabled_roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-element-types.html" title="37.24. element_types" /><link rel="next" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.25. <code class="literal">enabled_roles</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-element-types.html" title="37.24. element_types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ENABLED-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.25. <code class="literal">enabled_roles</code></h2></div></div></div><p>
+ The view <code class="literal">enabled_roles</code> identifies the currently
+ <span class="quote">“<span class="quote">enabled roles</span>”</span>. The enabled roles are recursively
+ defined as the current user together with all roles that have been
+ granted to the enabled roles with automatic inheritance. In other
+ words, these are all roles that the current user has direct or
+ indirect, automatically inheriting membership in.
+ <a id="id-1.7.6.29.2.3" class="indexterm"></a>
+ <a id="id-1.7.6.29.2.4" class="indexterm"></a>
+ </p><p>
+ For permission checking, the set of <span class="quote">“<span class="quote">applicable roles</span>”</span>
+ is applied, which can be broader than the set of enabled roles. So
+ generally, it is better to use the view
+ <code class="literal">applicable_roles</code> instead of this one; See
+ <a class="xref" href="infoschema-applicable-roles.html" title="37.5. applicable_roles">Section 37.5</a> for details on
+ <code class="literal">applicable_roles</code> view.
+ </p><div class="table" id="id-1.7.6.29.4"><p class="title"><strong>Table 37.23. <code class="structname">enabled_roles</code> Columns</strong></p><div class="table-contents"><table class="table" summary="enabled_roles Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">role_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of a role
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-element-types.html" title="37.24. element_types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.24. <code class="literal">element_types</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.26. <code class="literal">foreign_data_wrapper_options</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-data-wrapper-options.html b/doc/src/sgml/html/infoschema-foreign-data-wrapper-options.html
new file mode 100644
index 0000000..eef12cd
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-data-wrapper-options.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.26. foreign_data_wrapper_options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-enabled-roles.html" title="37.25. enabled_roles" /><link rel="next" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.26. <code class="literal">foreign_data_wrapper_options</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-enabled-roles.html" title="37.25. enabled_roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-DATA-WRAPPER-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.26. <code class="literal">foreign_data_wrapper_options</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_data_wrapper_options</code> contains
+ all the options defined for foreign-data wrappers in the current
+ database. Only those foreign-data wrappers are shown that the
+ current user has access to (by way of being the owner or having
+ some privilege).
+ </p><div class="table" id="id-1.7.6.30.3"><p class="title"><strong>Table 37.24. <code class="structname">foreign_data_wrapper_options</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_data_wrapper_options Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign-data wrapper is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign-data wrapper
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of an option
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the option
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-enabled-roles.html" title="37.25. enabled_roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.25. <code class="literal">enabled_roles</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.27. <code class="literal">foreign_data_wrappers</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-data-wrappers.html b/doc/src/sgml/html/infoschema-foreign-data-wrappers.html
new file mode 100644
index 0000000..e8405b9
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-data-wrappers.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.27. foreign_data_wrappers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options" /><link rel="next" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.27. <code class="literal">foreign_data_wrappers</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-DATA-WRAPPERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.27. <code class="literal">foreign_data_wrappers</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_data_wrappers</code> contains all
+ foreign-data wrappers defined in the current database. Only those
+ foreign-data wrappers are shown that the current user has access to
+ (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.31.3"><p class="title"><strong>Table 37.25. <code class="structname">foreign_data_wrappers</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_data_wrappers Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the foreign-data
+ wrapper (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign-data wrapper
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">authorization_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the owner of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">library_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ File name of the library that implementing this foreign-data wrapper
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_language</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Language used to implement this foreign-data wrapper
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-data-wrapper-options.html" title="37.26. foreign_data_wrapper_options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.26. <code class="literal">foreign_data_wrapper_options</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.28. <code class="literal">foreign_server_options</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-server-options.html b/doc/src/sgml/html/infoschema-foreign-server-options.html
new file mode 100644
index 0000000..9f7315e
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-server-options.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.28. foreign_server_options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers" /><link rel="next" href="infoschema-foreign-servers.html" title="37.29. foreign_servers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.28. <code class="literal">foreign_server_options</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-servers.html" title="37.29. foreign_servers">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-SERVER-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.28. <code class="literal">foreign_server_options</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_server_options</code> contains all the
+ options defined for foreign servers in the current database. Only
+ those foreign servers are shown that the current user has access to
+ (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.32.3"><p class="title"><strong>Table 37.26. <code class="structname">foreign_server_options</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_server_options Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign server is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of an option
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the option
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-data-wrappers.html" title="37.27. foreign_data_wrappers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-servers.html" title="37.29. foreign_servers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.27. <code class="literal">foreign_data_wrappers</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.29. <code class="literal">foreign_servers</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-servers.html b/doc/src/sgml/html/infoschema-foreign-servers.html
new file mode 100644
index 0000000..7929bb5
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-servers.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.29. foreign_servers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options" /><link rel="next" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.29. <code class="literal">foreign_servers</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-SERVERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.29. <code class="literal">foreign_servers</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_servers</code> contains all foreign
+ servers defined in the current database. Only those foreign
+ servers are shown that the current user has access to (by way of
+ being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.33.3"><p class="title"><strong>Table 37.27. <code class="structname">foreign_servers</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_servers Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign server is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the foreign-data
+ wrapper used by the foreign server (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_data_wrapper_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign-data wrapper used by the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Foreign server type information, if specified upon creation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_version</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Foreign server version information, if specified upon creation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">authorization_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the owner of the foreign server
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-server-options.html" title="37.28. foreign_server_options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.28. <code class="literal">foreign_server_options</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.30. <code class="literal">foreign_table_options</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-table-options.html b/doc/src/sgml/html/infoschema-foreign-table-options.html
new file mode 100644
index 0000000..157e0b5
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-table-options.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.30. foreign_table_options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-servers.html" title="37.29. foreign_servers" /><link rel="next" href="infoschema-foreign-tables.html" title="37.31. foreign_tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.30. <code class="literal">foreign_table_options</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-servers.html" title="37.29. foreign_servers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-foreign-tables.html" title="37.31. foreign_tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-TABLE-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.30. <code class="literal">foreign_table_options</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_table_options</code> contains all the
+ options defined for foreign tables in the current database. Only
+ those foreign tables are shown that the current user has access to
+ (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.34.3"><p class="title"><strong>Table 37.28. <code class="structname">foreign_table_options</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_table_options Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the foreign table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of an option
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the option
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-servers.html" title="37.29. foreign_servers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-foreign-tables.html" title="37.31. foreign_tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.29. <code class="literal">foreign_servers</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.31. <code class="literal">foreign_tables</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-foreign-tables.html b/doc/src/sgml/html/infoschema-foreign-tables.html
new file mode 100644
index 0000000..f77ada4
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-foreign-tables.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.31. foreign_tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options" /><link rel="next" href="infoschema-key-column-usage.html" title="37.32. key_column_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.31. <code class="literal">foreign_tables</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-key-column-usage.html" title="37.32. key_column_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-FOREIGN-TABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.31. <code class="literal">foreign_tables</code></h2></div></div></div><p>
+ The view <code class="literal">foreign_tables</code> contains all foreign
+ tables defined in the current database. Only those foreign
+ tables are shown that the current user has access to (by way of
+ being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.35.3"><p class="title"><strong>Table 37.29. <code class="structname">foreign_tables</code> Columns</strong></p><div class="table-contents"><table class="table" summary="foreign_tables Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign table is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign server is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign server
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-table-options.html" title="37.30. foreign_table_options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-key-column-usage.html" title="37.32. key_column_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.30. <code class="literal">foreign_table_options</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.32. <code class="literal">key_column_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-information-schema-catalog-name.html b/doc/src/sgml/html/infoschema-information-schema-catalog-name.html
new file mode 100644
index 0000000..cf30a9f
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-information-schema-catalog-name.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.3. information_schema_catalog_name</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-datatypes.html" title="37.2. Data Types" /><link rel="next" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.3. <code class="literal">information_schema_catalog_name</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-datatypes.html" title="37.2. Data Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-INFORMATION-SCHEMA-CATALOG-NAME"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.3. <code class="literal">information_schema_catalog_name</code></h2></div></div></div><p>
+ <code class="literal">information_schema_catalog_name</code> is a table that
+ always contains one row and one column containing the name of the
+ current database (current catalog, in SQL terminology).
+ </p><div class="table" id="id-1.7.6.7.3"><p class="title"><strong>Table 37.1. <code class="structname">information_schema_catalog_name</code> Columns</strong></p><div class="table-contents"><table class="table" summary="information_schema_catalog_name Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">catalog_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains this information schema
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-datatypes.html" title="37.2. Data Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-administrable-role-authorizations.html" title="37.4. administrable_role_​authorizations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.2. Data Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.4. <code class="literal">administrable_role_​authorizations</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-key-column-usage.html b/doc/src/sgml/html/infoschema-key-column-usage.html
new file mode 100644
index 0000000..0c4546e
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-key-column-usage.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.32. key_column_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-foreign-tables.html" title="37.31. foreign_tables" /><link rel="next" href="infoschema-parameters.html" title="37.33. parameters" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.32. <code class="literal">key_column_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-foreign-tables.html" title="37.31. foreign_tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-parameters.html" title="37.33. parameters">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-KEY-COLUMN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.32. <code class="literal">key_column_usage</code></h2></div></div></div><p>
+ The view <code class="literal">key_column_usage</code> identifies all columns
+ in the current database that are restricted by some unique, primary
+ key, or foreign key constraint. Check constraints are not included
+ in this view. Only those columns are shown that the current user
+ has access to, by way of being the owner or having some privilege.
+ </p><div class="table" id="id-1.7.6.36.3"><p class="title"><strong>Table 37.30. <code class="structname">key_column_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="key_column_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that contains the
+ column that is restricted by this constraint (always the
+ current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that contains the
+ column that is restricted by this constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that contains the column that is restricted
+ by this constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column that is restricted by this constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordinal_position</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Ordinal position of the column within the constraint key (count
+ starts at 1)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">position_in_unique_constraint</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ For a foreign-key constraint, ordinal position of the referenced
+ column within its unique constraint (count starts at 1);
+ otherwise null
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-foreign-tables.html" title="37.31. foreign_tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-parameters.html" title="37.33. parameters">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.31. <code class="literal">foreign_tables</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.33. <code class="literal">parameters</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-parameters.html b/doc/src/sgml/html/infoschema-parameters.html
new file mode 100644
index 0000000..9125f99
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-parameters.html
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.33. parameters</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-key-column-usage.html" title="37.32. key_column_usage" /><link rel="next" href="infoschema-referential-constraints.html" title="37.34. referential_constraints" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.33. <code class="literal">parameters</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-key-column-usage.html" title="37.32. key_column_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-referential-constraints.html" title="37.34. referential_constraints">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-PARAMETERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.33. <code class="literal">parameters</code></h2></div></div></div><p>
+ The view <code class="literal">parameters</code> contains information about
+ the parameters (arguments) of all functions in the current database.
+ Only those functions are shown that the current user has access to
+ (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.37.3"><p class="title"><strong>Table 37.31. <code class="structname">parameters</code> Columns</strong></p><div class="table-contents"><table class="table" summary="parameters Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordinal_position</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Ordinal position of the parameter in the argument list of the
+ function (count starts at 1)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parameter_mode</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">IN</code> for input parameter,
+ <code class="literal">OUT</code> for output parameter,
+ and <code class="literal">INOUT</code> for input/output parameter.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_result</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">as_locator</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parameter_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the parameter, or null if the parameter has no name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Data type of the parameter, if it is a built-in type, or
+ <code class="literal">ARRAY</code> if it is some array (in that case, see
+ the view <code class="literal">element_types</code>), else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">udt_name</code> and associated
+ columns).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to parameter data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the data type of the parameter is
+ defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the data type of the parameter is
+ defined in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the data type of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the parameter,
+ unique among the data type descriptors pertaining to the
+ function. This is mainly useful for joining with other
+ instances of such identifiers. (The specific format of the
+ identifier is not defined and not guaranteed to remain the same
+ in future versions.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parameter_default</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The default expression of the parameter, or null if none or if the
+ function is not owned by a currently enabled role.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-key-column-usage.html" title="37.32. key_column_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-referential-constraints.html" title="37.34. referential_constraints">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.32. <code class="literal">key_column_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.34. <code class="literal">referential_constraints</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-referential-constraints.html b/doc/src/sgml/html/infoschema-referential-constraints.html
new file mode 100644
index 0000000..788c124
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-referential-constraints.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.34. referential_constraints</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-parameters.html" title="37.33. parameters" /><link rel="next" href="infoschema-role-column-grants.html" title="37.35. role_column_grants" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.34. <code class="literal">referential_constraints</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-parameters.html" title="37.33. parameters">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-role-column-grants.html" title="37.35. role_column_grants">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-REFERENTIAL-CONSTRAINTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.34. <code class="literal">referential_constraints</code></h2></div></div></div><p>
+ The view <code class="literal">referential_constraints</code> contains all
+ referential (foreign key) constraints in the current database.
+ Only those constraints are shown for which the current user has
+ write access to the referencing table (by way of being the
+ owner or having some privilege other than <code class="literal">SELECT</code>).
+ </p><div class="table" id="id-1.7.6.38.3"><p class="title"><strong>Table 37.32. <code class="structname">referential_constraints</code> Columns</strong></p><div class="table-contents"><table class="table" summary="referential_constraints Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">unique_constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the unique or primary key
+ constraint that the foreign key constraint references (always
+ the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">unique_constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the unique or primary key
+ constraint that the foreign key constraint references
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">unique_constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the unique or primary key constraint that the foreign
+ key constraint references
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">match_option</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Match option of the foreign key constraint:
+ <code class="literal">FULL</code>, <code class="literal">PARTIAL</code>, or
+ <code class="literal">NONE</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">update_rule</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Update rule of the foreign key constraint:
+ <code class="literal">CASCADE</code>, <code class="literal">SET NULL</code>,
+ <code class="literal">SET DEFAULT</code>, <code class="literal">RESTRICT</code>, or
+ <code class="literal">NO ACTION</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">delete_rule</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Delete rule of the foreign key constraint:
+ <code class="literal">CASCADE</code>, <code class="literal">SET NULL</code>,
+ <code class="literal">SET DEFAULT</code>, <code class="literal">RESTRICT</code>, or
+ <code class="literal">NO ACTION</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-parameters.html" title="37.33. parameters">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-role-column-grants.html" title="37.35. role_column_grants">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.33. <code class="literal">parameters</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.35. <code class="literal">role_column_grants</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-role-column-grants.html b/doc/src/sgml/html/infoschema-role-column-grants.html
new file mode 100644
index 0000000..65b794a
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-role-column-grants.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.35. role_column_grants</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-referential-constraints.html" title="37.34. referential_constraints" /><link rel="next" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.35. <code class="literal">role_column_grants</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-referential-constraints.html" title="37.34. referential_constraints">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROLE-COLUMN-GRANTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.35. <code class="literal">role_column_grants</code></h2></div></div></div><p>
+ The view <code class="literal">role_column_grants</code> identifies all
+ privileges granted on columns where the grantor or grantee is a
+ currently enabled role. Further information can be found under
+ <code class="literal">column_privileges</code>. The only effective
+ difference between this view
+ and <code class="literal">column_privileges</code> is that this view omits
+ columns that have been made accessible to the current user by way
+ of a grant to <code class="literal">PUBLIC</code>.
+ </p><div class="table" id="id-1.7.6.39.3"><p class="title"><strong>Table 37.33. <code class="structname">role_column_grants</code> Columns</strong></p><div class="table-contents"><table class="table" summary="role_column_grants Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that contains the column (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that contains the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that contains the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the privilege: <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or
+ <code class="literal">REFERENCES</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-referential-constraints.html" title="37.34. referential_constraints">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.34. <code class="literal">referential_constraints</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.36. <code class="literal">role_routine_grants</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-role-routine-grants.html b/doc/src/sgml/html/infoschema-role-routine-grants.html
new file mode 100644
index 0000000..055e656
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-role-routine-grants.html
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.36. role_routine_grants</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-role-column-grants.html" title="37.35. role_column_grants" /><link rel="next" href="infoschema-role-table-grants.html" title="37.37. role_table_grants" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.36. <code class="literal">role_routine_grants</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-role-column-grants.html" title="37.35. role_column_grants">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-role-table-grants.html" title="37.37. role_table_grants">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROLE-ROUTINE-GRANTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.36. <code class="literal">role_routine_grants</code></h2></div></div></div><p>
+ The view <code class="literal">role_routine_grants</code> identifies all
+ privileges granted on functions where the grantor or grantee is a
+ currently enabled role. Further information can be found under
+ <code class="literal">routine_privileges</code>. The only effective
+ difference between this view
+ and <code class="literal">routine_privileges</code> is that this view omits
+ functions that have been made accessible to the current user by way
+ of a grant to <code class="literal">PUBLIC</code>.
+ </p><div class="table" id="id-1.7.6.40.3"><p class="title"><strong>Table 37.34. <code class="structname">role_routine_grants</code> Columns</strong></p><div class="table-contents"><table class="table" summary="role_routine_grants Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">EXECUTE</code> (the only privilege type for functions)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-role-column-grants.html" title="37.35. role_column_grants">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-role-table-grants.html" title="37.37. role_table_grants">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.35. <code class="literal">role_column_grants</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.37. <code class="literal">role_table_grants</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-role-table-grants.html b/doc/src/sgml/html/infoschema-role-table-grants.html
new file mode 100644
index 0000000..f809778
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-role-table-grants.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.37. role_table_grants</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants" /><link rel="next" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.37. <code class="literal">role_table_grants</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROLE-TABLE-GRANTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.37. <code class="literal">role_table_grants</code></h2></div></div></div><p>
+ The view <code class="literal">role_table_grants</code> identifies all
+ privileges granted on tables or views where the grantor or grantee
+ is a currently enabled role. Further information can be found
+ under <code class="literal">table_privileges</code>. The only effective
+ difference between this view
+ and <code class="literal">table_privileges</code> is that this view omits
+ tables that have been made accessible to the current user by way of
+ a grant to <code class="literal">PUBLIC</code>.
+ </p><div class="table" id="id-1.7.6.41.3"><p class="title"><strong>Table 37.35. <code class="structname">role_table_grants</code> Columns</strong></p><div class="table-contents"><table class="table" summary="role_table_grants Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the privilege: <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, <code class="literal">TRUNCATE</code>,
+ <code class="literal">REFERENCES</code>, or <code class="literal">TRIGGER</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">with_hierarchy</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ In the SQL standard, <code class="literal">WITH HIERARCHY OPTION</code>
+ is a separate (sub-)privilege allowing certain operations on
+ table inheritance hierarchies. In PostgreSQL, this is included
+ in the <code class="literal">SELECT</code> privilege, so this column
+ shows <code class="literal">YES</code> if the privilege
+ is <code class="literal">SELECT</code>, else <code class="literal">NO</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-role-routine-grants.html" title="37.36. role_routine_grants">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.36. <code class="literal">role_routine_grants</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.38. <code class="literal">role_udt_grants</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-role-udt-grants.html b/doc/src/sgml/html/infoschema-role-udt-grants.html
new file mode 100644
index 0000000..b82614c
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-role-udt-grants.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.38. role_udt_grants</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-role-table-grants.html" title="37.37. role_table_grants" /><link rel="next" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.38. <code class="literal">role_udt_grants</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-role-table-grants.html" title="37.37. role_table_grants">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROLE-UDT-GRANTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.38. <code class="literal">role_udt_grants</code></h2></div></div></div><p>
+ The view <code class="literal">role_udt_grants</code> is intended to identify
+ <code class="literal">USAGE</code> privileges granted on user-defined types
+ where the grantor or grantee is a currently enabled role. Further
+ information can be found under
+ <code class="literal">udt_privileges</code>. The only effective difference
+ between this view and <code class="literal">udt_privileges</code> is that
+ this view omits objects that have been made accessible to the
+ current user by way of a grant to <code class="literal">PUBLIC</code>. Since
+ data types do not have real privileges in PostgreSQL, but only an
+ implicit grant to <code class="literal">PUBLIC</code>, this view is empty.
+ </p><div class="table" id="id-1.7.6.42.3"><p class="title"><strong>Table 37.36. <code class="structname">role_udt_grants</code> Columns</strong></p><div class="table-contents"><table class="table" summary="role_udt_grants Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the type (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">TYPE USAGE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-role-table-grants.html" title="37.37. role_table_grants">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.37. <code class="literal">role_table_grants</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.39. <code class="literal">role_usage_grants</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-role-usage-grants.html b/doc/src/sgml/html/infoschema-role-usage-grants.html
new file mode 100644
index 0000000..4c12b77
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-role-usage-grants.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.39. role_usage_grants</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants" /><link rel="next" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.39. <code class="literal">role_usage_grants</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROLE-USAGE-GRANTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.39. <code class="literal">role_usage_grants</code></h2></div></div></div><p>
+ The view <code class="literal">role_usage_grants</code> identifies
+ <code class="literal">USAGE</code> privileges granted on various kinds of
+ objects where the grantor or grantee is a currently enabled role.
+ Further information can be found under
+ <code class="literal">usage_privileges</code>. The only effective difference
+ between this view and <code class="literal">usage_privileges</code> is that
+ this view omits objects that have been made accessible to the
+ current user by way of a grant to <code class="literal">PUBLIC</code>.
+ </p><div class="table" id="id-1.7.6.43.3"><p class="title"><strong>Table 37.37. <code class="structname">role_usage_grants</code> Columns</strong></p><div class="table-contents"><table class="table" summary="role_usage_grants Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the object (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the object, if applicable,
+ else an empty string
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">COLLATION</code> or <code class="literal">DOMAIN</code> or <code class="literal">FOREIGN DATA WRAPPER</code> or <code class="literal">FOREIGN SERVER</code> or <code class="literal">SEQUENCE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">USAGE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-role-udt-grants.html" title="37.38. role_udt_grants">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.38. <code class="literal">role_udt_grants</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.40. <code class="literal">routine_column_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routine-column-usage.html b/doc/src/sgml/html/infoschema-routine-column-usage.html
new file mode 100644
index 0000000..f093e7b
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routine-column-usage.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.40. routine_column_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants" /><link rel="next" href="infoschema-routine-privileges.html" title="37.41. routine_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.40. <code class="literal">routine_column_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routine-privileges.html" title="37.41. routine_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINE-COLUMN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.40. <code class="literal">routine_column_usage</code></h2></div></div></div><p>
+ The view <code class="literal">routine_column_usage</code> is meant to identify all
+ columns that are used by a function or procedure. This information is
+ currently not tracked by <span class="productname">PostgreSQL</span>.
+ </p><div class="table" id="id-1.7.6.44.3"><p class="title"><strong>Table 37.38. <code class="literal">routine_column_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routine_column_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that is used by the
+ function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that is used by the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that is used by the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column that is used by the function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-role-usage-grants.html" title="37.39. role_usage_grants">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routine-privileges.html" title="37.41. routine_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.39. <code class="literal">role_usage_grants</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.41. <code class="literal">routine_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routine-privileges.html b/doc/src/sgml/html/infoschema-routine-privileges.html
new file mode 100644
index 0000000..216a21c
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routine-privileges.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.41. routine_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage" /><link rel="next" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.41. <code class="literal">routine_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINE-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.41. <code class="literal">routine_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">routine_privileges</code> identifies all
+ privileges granted on functions to a currently enabled role or by a
+ currently enabled role. There is one row for each combination of function,
+ grantor, and grantee.
+ </p><div class="table" id="id-1.7.6.45.3"><p class="title"><strong>Table 37.39. <code class="structname">routine_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routine_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">EXECUTE</code> (the only privilege type for functions)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routine-column-usage.html" title="37.40. routine_column_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.40. <code class="literal">routine_column_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.42. <code class="literal">routine_routine_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routine-routine-usage.html b/doc/src/sgml/html/infoschema-routine-routine-usage.html
new file mode 100644
index 0000000..f6ffe71
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routine-routine-usage.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.42. routine_routine_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routine-privileges.html" title="37.41. routine_privileges" /><link rel="next" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.42. <code class="literal">routine_routine_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routine-privileges.html" title="37.41. routine_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINE-ROUTINE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.42. <code class="literal">routine_routine_usage</code></h2></div></div></div><p>
+ The view <code class="literal">routine_routine_usage</code> is meant to identify all
+ functions or procedures that are used by another (or the same) function or
+ procedure, either in the body or in parameter default expressions.
+ Currently, only functions used in parameter default expressions are
+ tracked. An entry is included here only if the used function is owned by a
+ currently enabled role. (There is no such restriction on the using
+ function.)
+ </p><p>
+ Note that the entries for both functions in the view refer to the
+ <span class="quote">“<span class="quote">specific</span>”</span> name of the routine, even though the column names
+ are used in a way that is inconsistent with other information schema views
+ about routines. This is per SQL standard, although it is arguably a
+ misdesign. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information
+ about specific names.
+ </p><div class="table" id="id-1.7.6.46.4"><p class="title"><strong>Table 37.40. <code class="literal">routine_routine_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routine_routine_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the using function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the using function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the using function.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the function that is used by the
+ first function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the function that is used by the first
+ function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function that is used by the
+ first function.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routine-privileges.html" title="37.41. routine_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.41. <code class="literal">routine_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.43. <code class="literal">routine_sequence_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routine-sequence-usage.html b/doc/src/sgml/html/infoschema-routine-sequence-usage.html
new file mode 100644
index 0000000..b560633
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routine-sequence-usage.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.43. routine_sequence_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage" /><link rel="next" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.43. <code class="literal">routine_sequence_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINE-SEQUENCE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.43. <code class="literal">routine_sequence_usage</code></h2></div></div></div><p>
+ The view <code class="literal">routine_sequence_usage</code> is meant to identify all
+ sequences that are used by a function or procedure, either in the body or
+ in parameter default expressions. Currently, only sequences used in
+ parameter default expressions are tracked. A sequence is only included if
+ that sequence is owned by a currently enabled role.
+ </p><div class="table" id="id-1.7.6.47.3"><p class="title"><strong>Table 37.41. <code class="literal">routine_sequence_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routine_sequence_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schema_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the sequence that is used by the
+ function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequence_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the sequence that is used by the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequence_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the sequence that is used by the function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routine-routine-usage.html" title="37.42. routine_routine_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.42. <code class="literal">routine_routine_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.44. <code class="literal">routine_table_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routine-table-usage.html b/doc/src/sgml/html/infoschema-routine-table-usage.html
new file mode 100644
index 0000000..85227cb
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routine-table-usage.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.44. routine_table_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage" /><link rel="next" href="infoschema-routines.html" title="37.45. routines" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.44. <code class="literal">routine_table_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-routines.html" title="37.45. routines">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINE-TABLE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.44. <code class="literal">routine_table_usage</code></h2></div></div></div><p>
+ The view <code class="literal">routine_table_usage</code> is meant to identify all
+ tables that are used by a function or procedure. This information is
+ currently not tracked by <span class="productname">PostgreSQL</span>.
+ </p><div class="table" id="id-1.7.6.48.3"><p class="title"><strong>Table 37.42. <code class="literal">routine_table_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routine_table_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that is used by the
+ function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that is used by the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that is used by the function
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routine-sequence-usage.html" title="37.43. routine_sequence_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-routines.html" title="37.45. routines">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.43. <code class="literal">routine_sequence_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.45. <code class="literal">routines</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-routines.html b/doc/src/sgml/html/infoschema-routines.html
new file mode 100644
index 0000000..d394434
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-routines.html
@@ -0,0 +1,464 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.45. routines</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage" /><link rel="next" href="infoschema-schemata.html" title="37.46. schemata" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.45. <code class="literal">routines</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-schemata.html" title="37.46. schemata">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-ROUTINES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.45. <code class="literal">routines</code></h2></div></div></div><p>
+ The view <code class="literal">routines</code> contains all functions and procedures in the
+ current database. Only those functions and procedures are shown that the current
+ user has access to (by way of being the owner or having some
+ privilege).
+ </p><div class="table" id="id-1.7.6.49.3"><p class="title"><strong>Table 37.43. <code class="structname">routines</code> Columns</strong></p><div class="table-contents"><table class="table" summary="routines Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. This is a
+ name that uniquely identifies the function in the schema, even
+ if the real name of the function is overloaded. The format of
+ the specific name is not defined, it should only be used to
+ compare it to other instances of specific routine names.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the function (might be duplicated in case of overloading)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">FUNCTION</code> for a
+ function, <code class="literal">PROCEDURE</code> for a procedure
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">module_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">module_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">module_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Return data type of the function, if it is a built-in type, or
+ <code class="literal">ARRAY</code> if it is some array (in that case, see
+ the view <code class="literal">element_types</code>), else
+ <code class="literal">USER-DEFINED</code> (in that case, the type is
+ identified in <code class="literal">type_udt_name</code> and associated
+ columns). Null for a procedure.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, since this information is not applied to return data types in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">type_udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the return data type of the function
+ is defined in (always the current database). Null for a procedure.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">type_udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that the return data type of the function is
+ defined in. Null for a procedure.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">type_udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the return data type of the function. Null for a procedure.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Always null, because arrays always have unlimited maximum cardinality in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ An identifier of the data type descriptor of the return data
+ type of this function, unique among the data type descriptors
+ pertaining to the function. This is mainly useful for joining
+ with other instances of such identifiers. (The specific format
+ of the identifier is not defined and not guaranteed to remain
+ the same in future versions.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_body</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the function is an SQL function, then
+ <code class="literal">SQL</code>, else <code class="literal">EXTERNAL</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">routine_definition</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The source text of the function (null if the function is not
+ owned by a currently enabled role). (According to the SQL
+ standard, this column is only applicable if
+ <code class="literal">routine_body</code> is <code class="literal">SQL</code>, but
+ in <span class="productname">PostgreSQL</span> it will contain
+ whatever source text was specified when the function was
+ created.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">external_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If this function is a C function, then the external name (link
+ symbol) of the function; else null. (This works out to be the
+ same value that is shown in
+ <code class="literal">routine_definition</code>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">external_language</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The language the function is written in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parameter_style</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">GENERAL</code> (The SQL standard defines
+ other parameter styles, which are not available in <span class="productname">PostgreSQL</span>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_deterministic</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ If the function is declared immutable (called deterministic in
+ the SQL standard), then <code class="literal">YES</code>, else
+ <code class="literal">NO</code>. (You cannot query the other volatility
+ levels available in <span class="productname">PostgreSQL</span> through the information schema.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sql_data_access</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">MODIFIES</code>, meaning that the function
+ possibly modifies SQL data. This information is not useful for
+ <span class="productname">PostgreSQL</span>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_null_call</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ If the function automatically returns null if any of its
+ arguments are null, then <code class="literal">YES</code>, else
+ <code class="literal">NO</code>. Null for a procedure.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sql_path</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schema_level_routine</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Always <code class="literal">YES</code> (The opposite would be a method
+ of a user-defined type, which is a feature not available in
+ <span class="productname">PostgreSQL</span>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_dynamic_result_sets</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_user_defined_cast</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_implicitly_invocable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">security_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ If the function runs with the privileges of the current user,
+ then <code class="literal">INVOKER</code>, if the function runs with the
+ privileges of the user who defined it, then
+ <code class="literal">DEFINER</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">to_sql_specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">to_sql_specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">to_sql_specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">as_locator</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">created</code> <code class="type">time_stamp</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_altered</code> <code class="type">time_stamp</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">new_savepoint_level</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_udt_dependent</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Currently always <code class="literal">NO</code>. The alternative
+ <code class="literal">YES</code> applies to a feature not available in
+ <span class="productname">PostgreSQL</span>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_from_data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_as_locator</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_char_max_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_char_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_char_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_char_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_char_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_type_udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_type_udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_type_udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_scope_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_scope_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_scope_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_maximum_cardinality</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">result_cast_dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routine-table-usage.html" title="37.44. routine_table_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-schemata.html" title="37.46. schemata">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.44. <code class="literal">routine_table_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.46. <code class="literal">schemata</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-schema.html b/doc/src/sgml/html/infoschema-schema.html
new file mode 100644
index 0000000..9bfbb93
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-schema.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.1. The Schema</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="information-schema.html" title="Chapter 37. The Information Schema" /><link rel="next" href="infoschema-datatypes.html" title="37.2. Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.1. The Schema</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="information-schema.html" title="Chapter 37. The Information Schema">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-datatypes.html" title="37.2. Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SCHEMA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.1. The Schema</h2></div></div></div><p>
+ The information schema itself is a schema named
+ <code class="literal">information_schema</code>. This schema automatically
+ exists in all databases. The owner of this schema is the initial
+ database user in the cluster, and that user naturally has all the
+ privileges on this schema, including the ability to drop it (but
+ the space savings achieved by that are minuscule).
+ </p><p>
+ By default, the information schema is not in the schema search
+ path, so you need to access all objects in it through qualified
+ names. Since the names of some of the objects in the information
+ schema are generic names that might occur in user applications, you
+ should be careful if you want to put the information schema in the
+ path.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="information-schema.html" title="Chapter 37. The Information Schema">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-datatypes.html" title="37.2. Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 37. The Information Schema </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.2. Data Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-schemata.html b/doc/src/sgml/html/infoschema-schemata.html
new file mode 100644
index 0000000..13f314d
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-schemata.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.46. schemata</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-routines.html" title="37.45. routines" /><link rel="next" href="infoschema-sequences.html" title="37.47. sequences" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.46. <code class="literal">schemata</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-routines.html" title="37.45. routines">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-sequences.html" title="37.47. sequences">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SCHEMATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.46. <code class="literal">schemata</code></h2></div></div></div><p>
+ The view <code class="literal">schemata</code> contains all schemas in the current
+ database that the current user has access to (by way of being the owner or
+ having some privilege).
+ </p><div class="table" id="id-1.7.6.50.3"><p class="title"><strong>Table 37.44. <code class="structname">schemata</code> Columns</strong></p><div class="table-contents"><table class="table" summary="schemata Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">catalog_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the schema is contained in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schema_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schema_owner</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the owner of the schema
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sql_path</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-routines.html" title="37.45. routines">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-sequences.html" title="37.47. sequences">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.45. <code class="literal">routines</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.47. <code class="literal">sequences</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-sequences.html b/doc/src/sgml/html/infoschema-sequences.html
new file mode 100644
index 0000000..57bb6ff
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-sequences.html
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.47. sequences</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-schemata.html" title="37.46. schemata" /><link rel="next" href="infoschema-sql-features.html" title="37.48. sql_features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.47. <code class="literal">sequences</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-schemata.html" title="37.46. schemata">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-sql-features.html" title="37.48. sql_features">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SEQUENCES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.47. <code class="literal">sequences</code></h2></div></div></div><p>
+ The view <code class="literal">sequences</code> contains all sequences
+ defined in the current database. Only those sequences are shown
+ that the current user has access to (by way of being the owner or
+ having some privilege).
+ </p><div class="table" id="id-1.7.6.51.3"><p class="title"><strong>Table 37.45. <code class="structname">sequences</code> Columns</strong></p><div class="table-contents"><table class="table" summary="sequences Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequence_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the sequence (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequence_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequence_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The data type of the sequence.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ This column contains the (declared or implicit) precision of
+ the sequence data type (see above). The precision indicates
+ the number of significant digits. It can be expressed in
+ decimal (base 10) or binary (base 2) terms, as specified in the
+ column <code class="literal">numeric_precision_radix</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ This column indicates in which base the values in the columns
+ <code class="literal">numeric_precision</code> and
+ <code class="literal">numeric_scale</code> are expressed. The value is
+ either 2 or 10.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ This column contains the (declared or implicit) scale of the
+ sequence data type (see above). The scale indicates the number
+ of significant digits to the right of the decimal point. It
+ can be expressed in decimal (base 10) or binary (base 2) terms,
+ as specified in the column
+ <code class="literal">numeric_precision_radix</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">start_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The start value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">minimum_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The minimum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maximum_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The maximum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">increment</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ The increment of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cycle_option</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the sequence cycles, else <code class="literal">NO</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Note that in accordance with the SQL standard, the start, minimum,
+ maximum, and increment values are returned as character strings.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-schemata.html" title="37.46. schemata">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-sql-features.html" title="37.48. sql_features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.46. <code class="literal">schemata</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.48. <code class="literal">sql_features</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-sql-features.html b/doc/src/sgml/html/infoschema-sql-features.html
new file mode 100644
index 0000000..4bf038d
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-sql-features.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.48. sql_features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-sequences.html" title="37.47. sequences" /><link rel="next" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.48. <code class="literal">sql_features</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-sequences.html" title="37.47. sequences">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SQL-FEATURES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.48. <code class="literal">sql_features</code></h2></div></div></div><p>
+ The table <code class="literal">sql_features</code> contains information
+ about which formal features defined in the SQL standard are
+ supported by <span class="productname">PostgreSQL</span>. This is the
+ same information that is presented in <a class="xref" href="features.html" title="Appendix D. SQL Conformance">Appendix D</a>.
+ There you can also find some additional background information.
+ </p><div class="table" id="id-1.7.6.52.3"><p class="title"><strong>Table 37.46. <code class="structname">sql_features</code> Columns</strong></p><div class="table-contents"><table class="table" summary="sql_features Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">feature_id</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Identifier string of the feature
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">feature_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Descriptive name of the feature
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sub_feature_id</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Identifier string of the subfeature, or a zero-length string if not a subfeature
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sub_feature_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Descriptive name of the subfeature, or a zero-length string if not a subfeature
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_supported</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the feature is fully supported by the
+ current version of <span class="productname">PostgreSQL</span>, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_verified_by</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always null, since the <span class="productname">PostgreSQL</span> development group does not
+ perform formal testing of feature conformance
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comments</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Possibly a comment about the supported status of the feature
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-sequences.html" title="37.47. sequences">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.47. <code class="literal">sequences</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.49. <code class="literal">sql_implementation_info</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-sql-implementation-info.html b/doc/src/sgml/html/infoschema-sql-implementation-info.html
new file mode 100644
index 0000000..8419995
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-sql-implementation-info.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.49. sql_implementation_info</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-sql-features.html" title="37.48. sql_features" /><link rel="next" href="infoschema-sql-parts.html" title="37.50. sql_parts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.49. <code class="literal">sql_implementation_info</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-sql-features.html" title="37.48. sql_features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-sql-parts.html" title="37.50. sql_parts">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SQL-IMPLEMENTATION-INFO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.49. <code class="literal">sql_implementation_info</code></h2></div></div></div><p>
+ The table <code class="literal">sql_implementation_info</code> contains
+ information about various aspects that are left
+ implementation-defined by the SQL standard. This information is
+ primarily intended for use in the context of the ODBC interface;
+ users of other interfaces will probably find this information to be
+ of little use. For this reason, the individual implementation
+ information items are not described here; you will find them in the
+ description of the ODBC interface.
+ </p><div class="table" id="id-1.7.6.53.3"><p class="title"><strong>Table 37.47. <code class="structname">sql_implementation_info</code> Columns</strong></p><div class="table-contents"><table class="table" summary="sql_implementation_info Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">implementation_info_id</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Identifier string of the implementation information item
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">implementation_info_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Descriptive name of the implementation information item
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">integer_value</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Value of the implementation information item, or null if the
+ value is contained in the column
+ <code class="literal">character_value</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the implementation information item, or null if the
+ value is contained in the column
+ <code class="literal">integer_value</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comments</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Possibly a comment pertaining to the implementation information item
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-sql-features.html" title="37.48. sql_features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-sql-parts.html" title="37.50. sql_parts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.48. <code class="literal">sql_features</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.50. <code class="literal">sql_parts</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-sql-parts.html b/doc/src/sgml/html/infoschema-sql-parts.html
new file mode 100644
index 0000000..fe8b191
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-sql-parts.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.50. sql_parts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info" /><link rel="next" href="infoschema-sql-sizing.html" title="37.51. sql_sizing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.50. <code class="literal">sql_parts</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-sql-sizing.html" title="37.51. sql_sizing">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SQL-PARTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.50. <code class="literal">sql_parts</code></h2></div></div></div><p>
+ The table <code class="literal">sql_parts</code> contains information about
+ which of the several parts of the SQL standard are supported by
+ <span class="productname">PostgreSQL</span>.
+ </p><div class="table" id="id-1.7.6.54.3"><p class="title"><strong>Table 37.48. <code class="structname">sql_parts</code> Columns</strong></p><div class="table-contents"><table class="table" summary="sql_parts Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">feature_id</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ An identifier string containing the number of the part
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">feature_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Descriptive name of the part
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_supported</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the part is fully supported by the
+ current version of <span class="productname">PostgreSQL</span>,
+ <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_verified_by</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always null, since the <span class="productname">PostgreSQL</span> development group does not
+ perform formal testing of feature conformance
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comments</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Possibly a comment about the supported status of the part
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-sql-implementation-info.html" title="37.49. sql_implementation_info">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-sql-sizing.html" title="37.51. sql_sizing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.49. <code class="literal">sql_implementation_info</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.51. <code class="literal">sql_sizing</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-sql-sizing.html b/doc/src/sgml/html/infoschema-sql-sizing.html
new file mode 100644
index 0000000..ed78ef9
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-sql-sizing.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.51. sql_sizing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-sql-parts.html" title="37.50. sql_parts" /><link rel="next" href="infoschema-table-constraints.html" title="37.52. table_constraints" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.51. <code class="literal">sql_sizing</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-sql-parts.html" title="37.50. sql_parts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-table-constraints.html" title="37.52. table_constraints">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-SQL-SIZING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.51. <code class="literal">sql_sizing</code></h2></div></div></div><p>
+ The table <code class="literal">sql_sizing</code> contains information about
+ various size limits and maximum values in
+ <span class="productname">PostgreSQL</span>. This information is
+ primarily intended for use in the context of the ODBC interface;
+ users of other interfaces will probably find this information to be
+ of little use. For this reason, the individual sizing items are
+ not described here; you will find them in the description of the
+ ODBC interface.
+ </p><div class="table" id="id-1.7.6.55.3"><p class="title"><strong>Table 37.49. <code class="structname">sql_sizing</code> Columns</strong></p><div class="table-contents"><table class="table" summary="sql_sizing Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sizing_id</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Identifier of the sizing item
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sizing_name</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Descriptive name of the sizing item
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">supported_value</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Value of the sizing item, or 0 if the size is unlimited or
+ cannot be determined, or null if the features for which the
+ sizing item is applicable are not supported
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comments</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Possibly a comment pertaining to the sizing item
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-sql-parts.html" title="37.50. sql_parts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-table-constraints.html" title="37.52. table_constraints">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.50. <code class="literal">sql_parts</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.52. <code class="literal">table_constraints</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-table-constraints.html b/doc/src/sgml/html/infoschema-table-constraints.html
new file mode 100644
index 0000000..a82b03c
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-table-constraints.html
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.52. table_constraints</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-sql-sizing.html" title="37.51. sql_sizing" /><link rel="next" href="infoschema-table-privileges.html" title="37.53. table_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.52. <code class="literal">table_constraints</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-sql-sizing.html" title="37.51. sql_sizing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-table-privileges.html" title="37.53. table_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TABLE-CONSTRAINTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.52. <code class="literal">table_constraints</code></h2></div></div></div><p>
+ The view <code class="literal">table_constraints</code> contains all
+ constraints belonging to tables that the current user owns or has
+ some privilege other than <code class="literal">SELECT</code> on.
+ </p><div class="table" id="id-1.7.6.56.3"><p class="title"><strong>Table 37.50. <code class="structname">table_constraints</code> Columns</strong></p><div class="table-contents"><table class="table" summary="table_constraints Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the constraint (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the constraint
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">constraint_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the constraint: <code class="literal">CHECK</code>,
+ <code class="literal">FOREIGN KEY</code>, <code class="literal">PRIMARY KEY</code>,
+ or <code class="literal">UNIQUE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_deferrable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the constraint is deferrable, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">initially_deferred</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the constraint is deferrable and initially deferred, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">enforced</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in
+ <span class="productname">PostgreSQL</span> (currently always
+ <code class="literal">YES</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">nulls_distinct</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ If the constraint is a unique constraint, then <code class="literal">YES</code>
+ if the constraint treats nulls as distinct or <code class="literal">NO</code> if
+ it treats nulls as not distinct, otherwise null for other types of
+ constraints.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-sql-sizing.html" title="37.51. sql_sizing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-table-privileges.html" title="37.53. table_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.51. <code class="literal">sql_sizing</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.53. <code class="literal">table_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-table-privileges.html b/doc/src/sgml/html/infoschema-table-privileges.html
new file mode 100644
index 0000000..291f778
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-table-privileges.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.53. table_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-table-constraints.html" title="37.52. table_constraints" /><link rel="next" href="infoschema-tables.html" title="37.54. tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.53. <code class="literal">table_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-table-constraints.html" title="37.52. table_constraints">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-tables.html" title="37.54. tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TABLE-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.53. <code class="literal">table_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">table_privileges</code> identifies all
+ privileges granted on tables or views to a currently enabled role
+ or by a currently enabled role. There is one row for each
+ combination of table, grantor, and grantee.
+ </p><div class="table" id="id-1.7.6.57.3"><p class="title"><strong>Table 37.51. <code class="structname">table_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="table_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the privilege: <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, <code class="literal">TRUNCATE</code>,
+ <code class="literal">REFERENCES</code>, or <code class="literal">TRIGGER</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">with_hierarchy</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ In the SQL standard, <code class="literal">WITH HIERARCHY OPTION</code>
+ is a separate (sub-)privilege allowing certain operations on
+ table inheritance hierarchies. In PostgreSQL, this is included
+ in the <code class="literal">SELECT</code> privilege, so this column
+ shows <code class="literal">YES</code> if the privilege
+ is <code class="literal">SELECT</code>, else <code class="literal">NO</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-table-constraints.html" title="37.52. table_constraints">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-tables.html" title="37.54. tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.52. <code class="literal">table_constraints</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.54. <code class="literal">tables</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-tables.html b/doc/src/sgml/html/infoschema-tables.html
new file mode 100644
index 0000000..384efd2
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-tables.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.54. tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-table-privileges.html" title="37.53. table_privileges" /><link rel="next" href="infoschema-transforms.html" title="37.55. transforms" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.54. <code class="literal">tables</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-table-privileges.html" title="37.53. table_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-transforms.html" title="37.55. transforms">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.54. <code class="literal">tables</code></h2></div></div></div><p>
+ The view <code class="literal">tables</code> contains all tables and views
+ defined in the current database. Only those tables and views are
+ shown that the current user has access to (by way of being the
+ owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.58.3"><p class="title"><strong>Table 37.52. <code class="structname">tables</code> Columns</strong></p><div class="table-contents"><table class="table" summary="tables Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Type of the table: <code class="literal">BASE TABLE</code> for a
+ persistent base table (the normal table type),
+ <code class="literal">VIEW</code> for a view, <code class="literal">FOREIGN</code>
+ for a foreign table, or
+ <code class="literal">LOCAL TEMPORARY</code> for a temporary table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">self_referencing_column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reference_generation</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the table is a typed table, the name of the database that
+ contains the underlying data type (always the current
+ database), else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the table is a typed table, the name of the schema that
+ contains the underlying data type, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ If the table is a typed table, the name of the underlying data
+ type, else null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_insertable_into</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the table is insertable into,
+ <code class="literal">NO</code> if not (Base tables are always insertable
+ into, views not necessarily.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_typed</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the table is a typed table, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">commit_action</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Not yet implemented
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-table-privileges.html" title="37.53. table_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-transforms.html" title="37.55. transforms">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.53. <code class="literal">table_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.55. <code class="literal">transforms</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-transforms.html b/doc/src/sgml/html/infoschema-transforms.html
new file mode 100644
index 0000000..c3676d1
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-transforms.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.55. transforms</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-tables.html" title="37.54. tables" /><link rel="next" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.55. <code class="literal">transforms</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-tables.html" title="37.54. tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TRANSFORMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.55. <code class="literal">transforms</code></h2></div></div></div><p>
+ The view <code class="literal">transforms</code> contains information about the
+ transforms defined in the current database. More precisely, it contains a
+ row for each function contained in a transform (the <span class="quote">“<span class="quote">from SQL</span>”</span>
+ or <span class="quote">“<span class="quote">to SQL</span>”</span> function).
+ </p><div class="table" id="id-1.7.6.59.3"><p class="title"><strong>Table 37.53. <code class="structname">transforms</code> Columns</strong></p><div class="table-contents"><table class="table" summary="transforms Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the type the transform is for (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the type the transform is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the type the transform is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">group_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The SQL standard allows defining transforms in <span class="quote">“<span class="quote">groups</span>”</span>,
+ and selecting a group at run time. PostgreSQL does not support this.
+ Instead, transforms are specific to a language. As a compromise, this
+ field contains the language the transform is for.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">transform_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">FROM SQL</code> or <code class="literal">TO SQL</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-tables.html" title="37.54. tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.54. <code class="literal">tables</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.56. <code class="literal">triggered_update_columns</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-triggered-update-columns.html b/doc/src/sgml/html/infoschema-triggered-update-columns.html
new file mode 100644
index 0000000..3a510d8
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-triggered-update-columns.html
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.56. triggered_update_columns</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-transforms.html" title="37.55. transforms" /><link rel="next" href="infoschema-triggers.html" title="37.57. triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.56. <code class="literal">triggered_update_columns</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-transforms.html" title="37.55. transforms">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-triggers.html" title="37.57. triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TRIGGERED-UPDATE-COLUMNS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.56. <code class="literal">triggered_update_columns</code></h2></div></div></div><p>
+ For triggers in the current database that specify a column list
+ (like <code class="literal">UPDATE OF column1, column2</code>), the
+ view <code class="literal">triggered_update_columns</code> identifies these
+ columns. Triggers that do not specify a column list are not
+ included in this view. Only those columns are shown that the
+ current user owns or has some privilege other than
+ <code class="literal">SELECT</code> on.
+ </p><div class="table" id="id-1.7.6.60.3"><p class="title"><strong>Table 37.54. <code class="structname">triggered_update_columns</code> Columns</strong></p><div class="table-contents"><table class="table" summary="triggered_update_columns Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the trigger (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the trigger
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the trigger
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that the trigger
+ is defined on (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that the trigger is defined on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_table</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that the trigger is defined on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_column</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column that the trigger is defined on
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-transforms.html" title="37.55. transforms">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-triggers.html" title="37.57. triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.55. <code class="literal">transforms</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.57. <code class="literal">triggers</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-triggers.html b/doc/src/sgml/html/infoschema-triggers.html
new file mode 100644
index 0000000..c91b404
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-triggers.html
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.57. triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns" /><link rel="next" href="infoschema-udt-privileges.html" title="37.58. udt_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.57. <code class="literal">triggers</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-udt-privileges.html" title="37.58. udt_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.57. <code class="literal">triggers</code></h2></div></div></div><p>
+ The view <code class="literal">triggers</code> contains all triggers defined
+ in the current database on tables and views that the current user owns
+ or has some privilege other than <code class="literal">SELECT</code> on.
+ </p><div class="table" id="id-1.7.6.61.3"><p class="title"><strong>Table 37.55. <code class="structname">triggers</code> Columns</strong></p><div class="table-contents"><table class="table" summary="triggers Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the trigger (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the trigger
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trigger_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the trigger
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_manipulation</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Event that fires the trigger (<code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, or <code class="literal">DELETE</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that the trigger
+ is defined on (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that the trigger is defined on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">event_object_table</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that the trigger is defined on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_order</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Firing order among triggers on the same table having the same
+ <code class="literal">event_manipulation</code>,
+ <code class="literal">action_timing</code>, and
+ <code class="literal">action_orientation</code>. In
+ <span class="productname">PostgreSQL</span>, triggers are fired in name
+ order, so this column reflects that.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_condition</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">WHEN</code> condition of the trigger, null if none
+ (also null if the table is not owned by a currently enabled
+ role)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_statement</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Statement that is executed by the trigger (currently always
+ <code class="literal">EXECUTE FUNCTION
+ <em class="replaceable"><code>function</code></em>(...)</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_orientation</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Identifies whether the trigger fires once for each processed
+ row or once for each statement (<code class="literal">ROW</code> or
+ <code class="literal">STATEMENT</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_timing</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Time at which the trigger fires (<code class="literal">BEFORE</code>,
+ <code class="literal">AFTER</code>, or <code class="literal">INSTEAD OF</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_reference_old_table</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the <span class="quote">“<span class="quote">old</span>”</span> transition table, or null if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_reference_new_table</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the <span class="quote">“<span class="quote">new</span>”</span> transition table, or null if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_reference_old_row</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">action_reference_new_row</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">created</code> <code class="type">time_stamp</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Triggers in <span class="productname">PostgreSQL</span> have two
+ incompatibilities with the SQL standard that affect the
+ representation in the information schema. First, trigger names are
+ local to each table in <span class="productname">PostgreSQL</span>, rather
+ than being independent schema objects. Therefore there can be duplicate
+ trigger names defined in one schema, so long as they belong to
+ different tables. (<code class="literal">trigger_catalog</code> and
+ <code class="literal">trigger_schema</code> are really the values pertaining
+ to the table that the trigger is defined on.) Second, triggers can
+ be defined to fire on multiple events in
+ <span class="productname">PostgreSQL</span> (e.g., <code class="literal">ON INSERT OR
+ UPDATE</code>), whereas the SQL standard only allows one. If a
+ trigger is defined to fire on multiple events, it is represented as
+ multiple rows in the information schema, one for each type of
+ event. As a consequence of these two issues, the primary key of
+ the view <code class="literal">triggers</code> is really
+ <code class="literal">(trigger_catalog, trigger_schema, event_object_table,
+ trigger_name, event_manipulation)</code> instead of
+ <code class="literal">(trigger_catalog, trigger_schema, trigger_name)</code>,
+ which is what the SQL standard specifies. Nonetheless, if you
+ define your triggers in a manner that conforms with the SQL
+ standard (trigger names unique in the schema and only one event
+ type per trigger), this will not affect you.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> 9.1, this view's columns
+ <code class="structfield">action_timing</code>,
+ <code class="structfield">action_reference_old_table</code>,
+ <code class="structfield">action_reference_new_table</code>,
+ <code class="structfield">action_reference_old_row</code>, and
+ <code class="structfield">action_reference_new_row</code>
+ were named
+ <code class="structfield">condition_timing</code>,
+ <code class="structfield">condition_reference_old_table</code>,
+ <code class="structfield">condition_reference_new_table</code>,
+ <code class="structfield">condition_reference_old_row</code>, and
+ <code class="structfield">condition_reference_new_row</code>
+ respectively.
+ That was how they were named in the SQL:1999 standard.
+ The new naming conforms to SQL:2003 and later.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-triggered-update-columns.html" title="37.56. triggered_update_columns">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-udt-privileges.html" title="37.58. udt_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.56. <code class="literal">triggered_update_columns</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.58. <code class="literal">udt_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-udt-privileges.html b/doc/src/sgml/html/infoschema-udt-privileges.html
new file mode 100644
index 0000000..f5d6ba4
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-udt-privileges.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.58. udt_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-triggers.html" title="37.57. triggers" /><link rel="next" href="infoschema-usage-privileges.html" title="37.59. usage_privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.58. <code class="literal">udt_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-triggers.html" title="37.57. triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-usage-privileges.html" title="37.59. usage_privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-UDT-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.58. <code class="literal">udt_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">udt_privileges</code> identifies
+ <code class="literal">USAGE</code> 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 <a class="xref" href="infoschema-user-defined-types.html" title="37.60. user_defined_types">Section 37.60</a>
+ for why); see
+ <a class="xref" href="infoschema-usage-privileges.html" title="37.59. usage_privileges">Section 37.59</a> for domain privileges.
+ </p><div class="table" id="id-1.7.6.62.3"><p class="title"><strong>Table 37.56. <code class="structname">udt_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="udt_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the type (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">udt_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">TYPE USAGE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-triggers.html" title="37.57. triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-usage-privileges.html" title="37.59. usage_privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.57. <code class="literal">triggers</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.59. <code class="literal">usage_privileges</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-usage-privileges.html b/doc/src/sgml/html/infoschema-usage-privileges.html
new file mode 100644
index 0000000..ea56254
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-usage-privileges.html
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.59. usage_privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-udt-privileges.html" title="37.58. udt_privileges" /><link rel="next" href="infoschema-user-defined-types.html" title="37.60. user_defined_types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.59. <code class="literal">usage_privileges</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-udt-privileges.html" title="37.58. udt_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-user-defined-types.html" title="37.60. user_defined_types">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-USAGE-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.59. <code class="literal">usage_privileges</code></h2></div></div></div><p>
+ The view <code class="literal">usage_privileges</code> identifies
+ <code class="literal">USAGE</code> privileges granted on various kinds of
+ objects to a currently enabled role or by a currently enabled role.
+ In <span class="productname">PostgreSQL</span>, this currently applies to
+ collations, domains, foreign-data wrappers, foreign servers, and sequences. There is one
+ row for each combination of object, grantor, and grantee.
+ </p><p>
+ Since collations do not have real privileges
+ in <span class="productname">PostgreSQL</span>, this view shows implicit
+ non-grantable <code class="literal">USAGE</code> privileges granted by the
+ owner to <code class="literal">PUBLIC</code> for all collations. The other
+ object types, however, show real privileges.
+ </p><p>
+ In PostgreSQL, sequences also support <code class="literal">SELECT</code>
+ and <code class="literal">UPDATE</code> privileges in addition to
+ the <code class="literal">USAGE</code> privilege. These are nonstandard and therefore
+ not visible in the information schema.
+ </p><div class="table" id="id-1.7.6.63.5"><p class="title"><strong>Table 37.57. <code class="structname">usage_privileges</code> Columns</strong></p><div class="table-contents"><table class="table" summary="usage_privileges Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantor</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that granted the privilege
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grantee</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the role that the privilege was granted to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the object (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the object, if applicable,
+ else an empty string
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">object_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">COLLATION</code> or <code class="literal">DOMAIN</code> or <code class="literal">FOREIGN DATA WRAPPER</code> or <code class="literal">FOREIGN SERVER</code> or <code class="literal">SEQUENCE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">privilege_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Always <code class="literal">USAGE</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_grantable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the privilege is grantable, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-udt-privileges.html" title="37.58. udt_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-user-defined-types.html" title="37.60. user_defined_types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.58. <code class="literal">udt_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.60. <code class="literal">user_defined_types</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-user-defined-types.html b/doc/src/sgml/html/infoschema-user-defined-types.html
new file mode 100644
index 0000000..3f7ca33
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-user-defined-types.html
@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.60. user_defined_types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-usage-privileges.html" title="37.59. usage_privileges" /><link rel="next" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.60. <code class="literal">user_defined_types</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-usage-privileges.html" title="37.59. usage_privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-USER-DEFINED-TYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.60. <code class="literal">user_defined_types</code></h2></div></div></div><p>
+ The view <code class="literal">user_defined_types</code> currently contains
+ all composite types defined in the current database.
+ Only those types are shown that the current user has access to (by way
+ of being the owner or having some privilege).
+ </p><p>
+ SQL knows about two kinds of user-defined types: structured types
+ (also known as composite types
+ in <span class="productname">PostgreSQL</span>) and distinct types (not
+ implemented in <span class="productname">PostgreSQL</span>). To be
+ future-proof, use the
+ column <code class="literal">user_defined_type_category</code> to
+ differentiate between these. Other user-defined types such as base
+ types and enums, which are <span class="productname">PostgreSQL</span>
+ extensions, are not shown here. For domains,
+ see <a class="xref" href="infoschema-domains.html" title="37.23. domains">Section 37.23</a> instead.
+ </p><div class="table" id="id-1.7.6.64.4"><p class="title"><strong>Table 37.58. <code class="structname">user_defined_types</code> Columns</strong></p><div class="table-contents"><table class="table" summary="user_defined_types Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the type (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the type
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_defined_type_category</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Currently always <code class="literal">STRUCTURED</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_instantiable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_final</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordering_form</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordering_category</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordering_routine_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordering_routine_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ordering_routine_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reference_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_maximum_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_octet_length</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">character_set_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">collation_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_precision_radix</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numeric_scale</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datetime_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_type</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">interval_precision</code> <code class="type">cardinal_number</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">source_dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ref_dtd_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Applies to a feature not available in <span class="productname">PostgreSQL</span>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-usage-privileges.html" title="37.59. usage_privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.59. <code class="literal">usage_privileges</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.61. <code class="literal">user_mapping_options</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-user-mapping-options.html b/doc/src/sgml/html/infoschema-user-mapping-options.html
new file mode 100644
index 0000000..0abde01
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-user-mapping-options.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.61. user_mapping_options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-user-defined-types.html" title="37.60. user_defined_types" /><link rel="next" href="infoschema-user-mappings.html" title="37.62. user_mappings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.61. <code class="literal">user_mapping_options</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-user-defined-types.html" title="37.60. user_defined_types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-user-mappings.html" title="37.62. user_mappings">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-USER-MAPPING-OPTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.61. <code class="literal">user_mapping_options</code></h2></div></div></div><p>
+ The view <code class="literal">user_mapping_options</code> contains all the
+ options defined for user mappings in the current database. Only
+ those user mappings are shown where the current user has access to
+ the corresponding foreign server (by way of being the owner or
+ having some privilege).
+ </p><div class="table" id="id-1.7.6.65.3"><p class="title"><strong>Table 37.59. <code class="structname">user_mapping_options</code> Columns</strong></p><div class="table-contents"><table class="table" summary="user_mapping_options Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">authorization_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the user being mapped,
+ or <code class="literal">PUBLIC</code> if the mapping is public
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign server used by this
+ mapping is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign server used by this mapping
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of an option
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">option_value</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Value of the option. This column will show as null
+ unless the current user is the user being mapped, or the mapping
+ is for <code class="literal">PUBLIC</code> and the current user is the
+ server owner, or the current user is a superuser. The intent is
+ to protect password information stored as user mapping
+ option.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-user-defined-types.html" title="37.60. user_defined_types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-user-mappings.html" title="37.62. user_mappings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.60. <code class="literal">user_defined_types</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.62. <code class="literal">user_mappings</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-user-mappings.html b/doc/src/sgml/html/infoschema-user-mappings.html
new file mode 100644
index 0000000..de98c45
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-user-mappings.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.62. user_mappings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options" /><link rel="next" href="infoschema-view-column-usage.html" title="37.63. view_column_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.62. <code class="literal">user_mappings</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-view-column-usage.html" title="37.63. view_column_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-USER-MAPPINGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.62. <code class="literal">user_mappings</code></h2></div></div></div><p>
+ The view <code class="literal">user_mappings</code> contains all user
+ mappings defined in the current database. Only those user mappings
+ are shown where the current user has access to the corresponding
+ foreign server (by way of being the owner or having some
+ privilege).
+ </p><div class="table" id="id-1.7.6.66.3"><p class="title"><strong>Table 37.60. <code class="structname">user_mappings</code> Columns</strong></p><div class="table-contents"><table class="table" summary="user_mappings Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">authorization_identifier</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the user being mapped,
+ or <code class="literal">PUBLIC</code> if the mapping is public
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that the foreign server used by this
+ mapping is defined in (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">foreign_server_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the foreign server used by this mapping
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-user-mapping-options.html" title="37.61. user_mapping_options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-view-column-usage.html" title="37.63. view_column_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.61. <code class="literal">user_mapping_options</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.63. <code class="literal">view_column_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-view-column-usage.html b/doc/src/sgml/html/infoschema-view-column-usage.html
new file mode 100644
index 0000000..0313df6
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-view-column-usage.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.63. view_column_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-user-mappings.html" title="37.62. user_mappings" /><link rel="next" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.63. <code class="literal">view_column_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-user-mappings.html" title="37.62. user_mappings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-VIEW-COLUMN-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.63. <code class="literal">view_column_usage</code></h2></div></div></div><p>
+ The view <code class="literal">view_column_usage</code> identifies all
+ columns that are used in the query expression of a view (the
+ <code class="command">SELECT</code> statement that defines the view). A
+ column is only included if the table that contains the column is
+ owned by a currently enabled role.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Columns of system tables are not included. This should be fixed
+ sometime.
+ </p></div><div class="table" id="id-1.7.6.67.4"><p class="title"><strong>Table 37.61. <code class="structname">view_column_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="view_column_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that contains the
+ column that is used by the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that contains the
+ column that is used by the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that contains the column that is used by the
+ view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">column_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the column that is used by the view
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-user-mappings.html" title="37.62. user_mappings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.62. <code class="literal">user_mappings</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.64. <code class="literal">view_routine_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-view-routine-usage.html b/doc/src/sgml/html/infoschema-view-routine-usage.html
new file mode 100644
index 0000000..fb87806
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-view-routine-usage.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.64. view_routine_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-view-column-usage.html" title="37.63. view_column_usage" /><link rel="next" href="infoschema-view-table-usage.html" title="37.65. view_table_usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.64. <code class="literal">view_routine_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-view-column-usage.html" title="37.63. view_column_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-view-table-usage.html" title="37.65. view_table_usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-VIEW-ROUTINE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.64. <code class="literal">view_routine_usage</code></h2></div></div></div><p>
+ The view <code class="literal">view_routine_usage</code> identifies all
+ routines (functions and procedures) that are used in the query
+ expression of a view (the <code class="command">SELECT</code> statement that
+ defines the view). A routine is only included if that routine is
+ owned by a currently enabled role.
+ </p><div class="table" id="id-1.7.6.68.3"><p class="title"><strong>Table 37.62. <code class="structname">view_routine_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="view_routine_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database containing the function (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema containing the function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">specific_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ The <span class="quote">“<span class="quote">specific name</span>”</span> of the function. See <a class="xref" href="infoschema-routines.html" title="37.45. routines">Section 37.45</a> for more information.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-view-column-usage.html" title="37.63. view_column_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-view-table-usage.html" title="37.65. view_table_usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.63. <code class="literal">view_column_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.65. <code class="literal">view_table_usage</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-view-table-usage.html b/doc/src/sgml/html/infoschema-view-table-usage.html
new file mode 100644
index 0000000..511b2c6
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-view-table-usage.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.65. view_table_usage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage" /><link rel="next" href="infoschema-views.html" title="37.66. views" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.65. <code class="literal">view_table_usage</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="infoschema-views.html" title="37.66. views">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-VIEW-TABLE-USAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.65. <code class="literal">view_table_usage</code></h2></div></div></div><p>
+ The view <code class="literal">view_table_usage</code> identifies all tables
+ that are used in the query expression of a view (the
+ <code class="command">SELECT</code> statement that defines the view). A
+ table is only included if that table is owned by a currently
+ enabled role.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ System tables are not included. This should be fixed sometime.
+ </p></div><div class="table" id="id-1.7.6.69.4"><p class="title"><strong>Table 37.63. <code class="structname">view_table_usage</code> Columns</strong></p><div class="table-contents"><table class="table" summary="view_table_usage Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the table that is
+ used by the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the table that is used by the
+ view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the table that is used by the view
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-view-routine-usage.html" title="37.64. view_routine_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="infoschema-views.html" title="37.66. views">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.64. <code class="literal">view_routine_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 37.66. <code class="literal">views</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/infoschema-views.html b/doc/src/sgml/html/infoschema-views.html
new file mode 100644
index 0000000..bf61004
--- /dev/null
+++ b/doc/src/sgml/html/infoschema-views.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>37.66. views</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-view-table-usage.html" title="37.65. view_table_usage" /><link rel="next" href="server-programming.html" title="Part V. Server Programming" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.66. <code class="literal">views</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-view-table-usage.html" title="37.65. view_table_usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><th width="60%" align="center">Chapter 37. The Information Schema</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="server-programming.html" title="Part V. Server Programming">Next</a></td></tr></table><hr /></div><div class="sect1" id="INFOSCHEMA-VIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.66. <code class="literal">views</code></h2></div></div></div><p>
+ The view <code class="literal">views</code> contains all views defined in the
+ current database. Only those views are shown that the current user
+ has access to (by way of being the owner or having some privilege).
+ </p><div class="table" id="id-1.7.6.70.3"><p class="title"><strong>Table 37.64. <code class="structname">views</code> Columns</strong></p><div class="table-contents"><table class="table" summary="views Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_catalog</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the database that contains the view (always the current database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_schema</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the schema that contains the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">table_name</code> <code class="type">sql_identifier</code>
+ </p>
+ <p>
+ Name of the view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">view_definition</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ Query expression defining the view (null if the view is not
+ owned by a currently enabled role)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">check_option</code> <code class="type">character_data</code>
+ </p>
+ <p>
+ <code class="literal">CASCADED</code> or <code class="literal">LOCAL</code> if the view
+ has a <code class="literal">CHECK OPTION</code> defined on it,
+ <code class="literal">NONE</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_updatable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the view is updatable (allows
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code>),
+ <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_insertable_into</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the view is insertable into (allows
+ <code class="command">INSERT</code>), <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_trigger_updatable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the view has an <code class="literal">INSTEAD OF</code>
+ <code class="command">UPDATE</code> trigger defined on it, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_trigger_deletable</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the view has an <code class="literal">INSTEAD OF</code>
+ <code class="command">DELETE</code> trigger defined on it, <code class="literal">NO</code> if not
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_trigger_insertable_into</code> <code class="type">yes_or_no</code>
+ </p>
+ <p>
+ <code class="literal">YES</code> if the view has an <code class="literal">INSTEAD OF</code>
+ <code class="command">INSERT</code> trigger defined on it, <code class="literal">NO</code> if not
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-view-table-usage.html" title="37.65. view_table_usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="information-schema.html" title="Chapter 37. The Information Schema">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="server-programming.html" title="Part V. Server Programming">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.65. <code class="literal">view_table_usage</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part V. Server Programming</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-binaries.html b/doc/src/sgml/html/install-binaries.html
new file mode 100644
index 0000000..12bbf70
--- /dev/null
+++ b/doc/src/sgml/html/install-binaries.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 16. Installation from Binaries</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="admin.html" title="Part III. Server Administration" /><link rel="next" href="installation.html" title="Chapter 17. Installation from Source Code" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 16. Installation from Binaries</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="admin.html" title="Part III. Server Administration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="installation.html" title="Chapter 17. Installation from Source Code">Next</a></td></tr></table><hr /></div><div class="chapter" id="INSTALL-BINARIES"><div class="titlepage"><div><div><h2 class="title">Chapter 16. Installation from Binaries</h2></div></div></div><a id="id-1.6.3.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> is available in the form of binary
+ packages for most common operating systems today. When available, this is
+ the recommended way to install PostgreSQL for users of the system. Building
+ from source (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>) is only recommended for
+ people developing <span class="productname">PostgreSQL</span> or extensions.
+ </p><p>
+ For an updated list of platforms providing binary packages, please visit
+ the download section on the <span class="productname">PostgreSQL</span> website at
+ <a class="ulink" href="https://www.postgresql.org/download/" target="_top">https://www.postgresql.org/download/</a> and follow the
+ instructions for the specific platform.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="admin.html" title="Part III. Server Administration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="installation.html" title="Chapter 17. Installation from Source Code">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part III. Server Administration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 17. Installation from Source Code</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-getsource.html b/doc/src/sgml/html/install-getsource.html
new file mode 100644
index 0000000..6cdf477
--- /dev/null
+++ b/doc/src/sgml/html/install-getsource.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.3. Getting the Source</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-requirements.html" title="17.2. Requirements" /><link rel="next" href="install-procedure.html" title="17.4. Installation Procedure" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.3. Getting the Source</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-requirements.html" title="17.2. Requirements">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-procedure.html" title="17.4. Installation Procedure">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-GETSOURCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.3. Getting the Source</h2></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> source code for released versions
+ can be obtained from the download section of our website:
+ <a class="ulink" href="https://www.postgresql.org/ftp/source/" target="_top">https://www.postgresql.org/ftp/source/</a>.
+ Download the
+ <code class="filename">postgresql-<em class="replaceable"><code>version</code></em>.tar.gz</code>
+ or <code class="filename">postgresql-<em class="replaceable"><code>version</code></em>.tar.bz2</code>
+ file you're interested in, then unpack it:
+</p><pre class="screen">
+<strong class="userinput"><code>tar xf postgresql-<em class="replaceable"><code>version</code></em>.tar.bz2</code></strong>
+</pre><p>
+ This will create a directory
+ <code class="filename">postgresql-<em class="replaceable"><code>version</code></em></code> under
+ the current directory with the <span class="productname">PostgreSQL</span> sources.
+ Change into that directory for the rest of the installation procedure.
+ </p><p>
+ Alternatively, you can use the Git version control system; see
+ <a class="xref" href="git.html" title="I.1. Getting the Source via Git">Section I.1</a> for more information.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-requirements.html" title="17.2. Requirements">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-procedure.html" title="17.4. Installation Procedure">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.2. Requirements </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.4. Installation Procedure</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-post.html b/doc/src/sgml/html/install-post.html
new file mode 100644
index 0000000..f443757
--- /dev/null
+++ b/doc/src/sgml/html/install-post.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.5. Post-Installation Setup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-procedure.html" title="17.4. Installation Procedure" /><link rel="next" href="supported-platforms.html" title="17.6. Supported Platforms" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.5. Post-Installation Setup</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-procedure.html" title="17.4. Installation Procedure">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="supported-platforms.html" title="17.6. Supported Platforms">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-POST"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.5. Post-Installation Setup</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="install-post.html#INSTALL-POST-SHLIBS">17.5.1. Shared Libraries</a></span></dt><dt><span class="sect2"><a href="install-post.html#id-1.6.4.9.3">17.5.2. Environment Variables</a></span></dt></dl></div><div class="sect2" id="INSTALL-POST-SHLIBS"><div class="titlepage"><div><div><h3 class="title">17.5.1. Shared Libraries</h3></div></div></div><a id="id-1.6.4.9.2.2" class="indexterm"></a><p>
+ On some systems with shared libraries
+ you need to tell the system how to find the newly installed
+ shared libraries. The systems on which this is
+ <span class="emphasis"><em>not</em></span> necessary include
+ <span class="systemitem">FreeBSD</span>,
+ <span class="systemitem">HP-UX</span>,
+ <span class="systemitem">Linux</span>,
+ <span class="systemitem">NetBSD</span>, <span class="systemitem">OpenBSD</span>, and
+ <span class="systemitem">Solaris</span>.
+ </p><p>
+ The method to set the shared library search path varies between
+ platforms, but the most widely-used method is to set the
+ environment variable <code class="envar">LD_LIBRARY_PATH</code> like so: In Bourne
+ shells (<code class="command">sh</code>, <code class="command">ksh</code>, <code class="command">bash</code>, <code class="command">zsh</code>):
+</p><pre class="programlisting">
+LD_LIBRARY_PATH=/usr/local/pgsql/lib
+export LD_LIBRARY_PATH
+</pre><p>
+ or in <code class="command">csh</code> or <code class="command">tcsh</code>:
+</p><pre class="programlisting">
+setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+</pre><p>
+ Replace <code class="literal">/usr/local/pgsql/lib</code> with whatever you set
+ <code class="option"><code class="literal">--libdir</code></code> to in <a class="xref" href="install-procedure.html#CONFIGURE" title="Configuration">Step 1</a>.
+ You should put these commands into a shell start-up file such as
+ <code class="filename">/etc/profile</code> or <code class="filename">~/.bash_profile</code>. Some
+ good information about the caveats associated with this method can
+ be found at <a class="ulink" href="http://xahlee.info/UnixResource_dir/_/ldpath.html" target="_top">http://xahlee.info/UnixResource_dir/_/ldpath.html</a>.
+ </p><p>
+ On some systems it might be preferable to set the environment
+ variable <code class="envar">LD_RUN_PATH</code> <span class="emphasis"><em>before</em></span>
+ building.
+ </p><p>
+ On <span class="systemitem">Cygwin</span>, put the library
+ directory in the <code class="envar">PATH</code> or move the
+ <code class="filename">.dll</code> files into the <code class="filename">bin</code>
+ directory.
+ </p><p>
+ If in doubt, refer to the manual pages of your system (perhaps
+ <code class="command">ld.so</code> or <code class="command">rld</code>). If you later
+ get a message like:
+</p><pre class="screen">
+psql: error in loading shared libraries
+libpq.so.2.1: cannot open shared object file: No such file or directory
+</pre><p>
+ then this step was necessary. Simply take care of it then.
+ </p><p>
+ <a id="id-1.6.4.9.2.8.1" class="indexterm"></a>
+ If you are on <span class="systemitem">Linux</span> and you have root
+ access, you can run:
+</p><pre class="programlisting">
+/sbin/ldconfig /usr/local/pgsql/lib
+</pre><p>
+ (or equivalent directory) after installation to enable the
+ run-time linker to find the shared libraries faster. Refer to the
+ manual page of <code class="command">ldconfig</code> for more information. On
+ <span class="systemitem">FreeBSD</span>, <span class="systemitem">NetBSD</span>, and <span class="systemitem">OpenBSD</span> the command is:
+</p><pre class="programlisting">
+/sbin/ldconfig -m /usr/local/pgsql/lib
+</pre><p>
+ instead. Other systems are not known to have an equivalent
+ command.
+ </p></div><div class="sect2" id="id-1.6.4.9.3"><div class="titlepage"><div><div><h3 class="title">17.5.2. Environment Variables</h3></div></div></div><a id="id-1.6.4.9.3.2" class="indexterm"></a><p>
+ If you installed into <code class="filename">/usr/local/pgsql</code> or some other
+ location that is not searched for programs by default, you should
+ add <code class="filename">/usr/local/pgsql/bin</code> (or whatever you set
+ <code class="option"><code class="literal">--bindir</code></code> to in <a class="xref" href="install-procedure.html#CONFIGURE" title="Configuration">Step 1</a>)
+ into your <code class="envar">PATH</code>. Strictly speaking, this is not
+ necessary, but it will make the use of <span class="productname">PostgreSQL</span>
+ much more convenient.
+ </p><p>
+ To do this, add the following to your shell start-up file, such as
+ <code class="filename">~/.bash_profile</code> (or <code class="filename">/etc/profile</code>, if you
+ want it to affect all users):
+</p><pre class="programlisting">
+PATH=/usr/local/pgsql/bin:$PATH
+export PATH
+</pre><p>
+ If you are using <code class="command">csh</code> or <code class="command">tcsh</code>, then use this command:
+</p><pre class="programlisting">
+set path = ( /usr/local/pgsql/bin $path )
+</pre><p>
+ </p><p>
+ <a id="id-1.6.4.9.3.5.1" class="indexterm"></a>
+ To enable your system to find the <span class="application">man</span>
+ documentation, you need to add lines like the following to a
+ shell start-up file unless you installed into a location that is
+ searched by default:
+</p><pre class="programlisting">
+MANPATH=/usr/local/pgsql/share/man:$MANPATH
+export MANPATH
+</pre><p>
+ </p><p>
+ The environment variables <code class="envar">PGHOST</code> and <code class="envar">PGPORT</code>
+ specify to client applications the host and port of the database
+ server, overriding the compiled-in defaults. If you are going to
+ run client applications remotely then it is convenient if every
+ user that plans to use the database sets <code class="envar">PGHOST</code>. This
+ is not required, however; the settings can be communicated via command
+ line options to most client programs.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-procedure.html" title="17.4. Installation Procedure">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="supported-platforms.html" title="17.6. Supported Platforms">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.4. Installation Procedure </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.6. Supported Platforms</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-procedure.html b/doc/src/sgml/html/install-procedure.html
new file mode 100644
index 0000000..6dbc451
--- /dev/null
+++ b/doc/src/sgml/html/install-procedure.html
@@ -0,0 +1,818 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.4. Installation Procedure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-getsource.html" title="17.3. Getting the Source" /><link rel="next" href="install-post.html" title="17.5. Post-Installation Setup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.4. Installation Procedure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-getsource.html" title="17.3. Getting the Source">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-post.html" title="17.5. Post-Installation Setup">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-PROCEDURE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.4. Installation Procedure</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="install-procedure.html#CONFIGURE-OPTIONS">17.4.1. <code class="filename">configure</code> Options</a></span></dt><dt><span class="sect2"><a href="install-procedure.html#CONFIGURE-ENVVARS">17.4.2. <code class="filename">configure</code> Environment Variables</a></span></dt></dl></div><div class="procedure"><ol class="procedure" type="1"><li class="step" id="CONFIGURE"><p class="title"><strong>Configuration</strong></p><a id="id-1.6.4.8.2.1.2" class="indexterm"></a><p>
+ The first step of the installation procedure is to configure the
+ source tree for your system and choose the options you would like.
+ This is done by running the <code class="filename">configure</code> script. For a
+ default installation simply enter:
+</p><pre class="screen">
+<strong class="userinput"><code>./configure</code></strong>
+</pre><p>
+ This script will run a number of tests to determine values for various
+ system dependent variables and detect any quirks of your
+ operating system, and finally will create several files in the
+ build tree to record what it found.
+ </p><p>
+ You can also run <code class="filename">configure</code> in a directory outside
+ the source tree, and then build there, if you want to keep the build
+ directory separate from the original source files. This procedure is
+ called a
+ <a id="id-1.6.4.8.2.1.4.2" class="indexterm"></a><em class="firstterm">VPATH</em>
+ build. Here's how:
+</p><pre class="screen">
+<strong class="userinput"><code>mkdir build_dir</code></strong>
+<strong class="userinput"><code>cd build_dir</code></strong>
+<strong class="userinput"><code>/path/to/source/tree/configure [options go here]</code></strong>
+<strong class="userinput"><code>make</code></strong>
+</pre><p>
+ </p><p>
+ The default configuration will build the server and utilities, as
+ well as all client applications and interfaces that require only a
+ C compiler. All files will be installed under
+ <code class="filename">/usr/local/pgsql</code> by default.
+ </p><p>
+ You can customize the build and installation process by supplying one
+ or more command line options to <code class="filename">configure</code>.
+ Typically you would customize the install location, or the set of
+ optional features that are built. <code class="filename">configure</code>
+ has a large number of options, which are described in
+ <a class="xref" href="install-procedure.html#CONFIGURE-OPTIONS" title="17.4.1. configure Options">Section 17.4.1</a>.
+ </p><p>
+ Also, <code class="filename">configure</code> responds to certain environment
+ variables, as described in <a class="xref" href="install-procedure.html#CONFIGURE-ENVVARS" title="17.4.2. configure Environment Variables">Section 17.4.2</a>.
+ These provide additional ways to customize the configuration.
+ </p></li><li class="step" id="BUILD"><p class="title"><strong>Build</strong></p><p>
+ To start the build, type either of:
+</p><pre class="screen">
+<strong class="userinput"><code>make</code></strong>
+<strong class="userinput"><code>make all</code></strong>
+</pre><p>
+ (Remember to use <acronym class="acronym">GNU</acronym> <span class="application">make</span>.)
+ The build will take a few minutes depending on your
+ hardware.
+ </p><p>
+ If you want to build everything that can be built, including the
+ documentation (HTML and man pages), and the additional modules
+ (<code class="filename">contrib</code>), type instead:
+</p><pre class="screen">
+<strong class="userinput"><code>make world</code></strong>
+</pre><p>
+ </p><p>
+ If you want to build everything that can be built, including the
+ additional modules (<code class="filename">contrib</code>), but without
+ the documentation, type instead:
+</p><pre class="screen">
+<strong class="userinput"><code>make world-bin</code></strong>
+</pre><p>
+ </p><p>
+ If you want to invoke the build from another makefile rather than
+ manually, you must unset <code class="varname">MAKELEVEL</code> or set it to zero,
+ for instance like this:
+</p><pre class="programlisting">
+build-postgresql:
+ $(MAKE) -C postgresql MAKELEVEL=0 all
+</pre><p>
+ Failure to do that can lead to strange error messages, typically about
+ missing header files.
+ </p></li><li class="step"><p class="title"><strong>Regression Tests</strong></p><a id="id-1.6.4.8.2.3.2" class="indexterm"></a><p>
+ If you want to test the newly built server before you install it,
+ you can run the regression tests at this point. The regression
+ tests are a test suite to verify that <span class="productname">PostgreSQL</span>
+ runs on your machine in the way the developers expected it
+ to. Type:
+</p><pre class="screen">
+<strong class="userinput"><code>make check</code></strong>
+</pre><p>
+ (This won't work as root; do it as an unprivileged user.)
+ See <a class="xref" href="regress.html" title="Chapter 33. Regression Tests">Chapter 33</a> for
+ detailed information about interpreting the test results. You can
+ repeat this test at any later time by issuing the same command.
+ </p></li><li class="step" id="INSTALL"><p class="title"><strong>Installing the Files</strong></p><div class="note"><h3 class="title">Note</h3><p>
+ If you are upgrading an existing system be sure to read
+ <a class="xref" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Section 19.6</a>,
+ which has instructions about upgrading a
+ cluster.
+ </p></div><p>
+ To install <span class="productname">PostgreSQL</span> enter:
+</p><pre class="screen">
+<strong class="userinput"><code>make install</code></strong>
+</pre><p>
+ This will install files into the directories that were specified
+ in <a class="xref" href="install-procedure.html#CONFIGURE" title="Configuration">Step 1</a>. 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
+ be granted.
+ </p><p>
+ To install the documentation (HTML and man pages), enter:
+</p><pre class="screen">
+<strong class="userinput"><code>make install-docs</code></strong>
+</pre><p>
+ </p><p>
+ If you built the world above, type instead:
+</p><pre class="screen">
+<strong class="userinput"><code>make install-world</code></strong>
+</pre><p>
+ This also installs the documentation.
+ </p><p>
+ If you built the world without the documentation above, type instead:
+</p><pre class="screen">
+<strong class="userinput"><code>make install-world-bin</code></strong>
+</pre><p>
+ </p><p>
+ You can use <code class="literal">make install-strip</code> instead of
+ <code class="literal">make install</code> to strip the executable files and
+ libraries as they are installed. This will save some space. If
+ you built with debugging support, stripping will effectively
+ remove the debugging support, so it should only be done if
+ debugging is no longer needed. <code class="literal">install-strip</code>
+ tries to do a reasonable job saving space, but it does not have
+ perfect knowledge of how to strip every unneeded byte from an
+ executable file, so if you want to save all the disk space you
+ possibly can, you will have to do manual work.
+ </p><p>
+ The standard installation provides all the header files needed for client
+ application development as well as for server-side program
+ development, such as custom functions or data types written in C.
+ </p><p><strong>Client-only installation: </strong>
+ If you want to install only the client applications and
+ interface libraries, then you can use these commands:
+</p><pre class="screen">
+<strong class="userinput"><code>make -C src/bin install</code></strong>
+<strong class="userinput"><code>make -C src/include install</code></strong>
+<strong class="userinput"><code>make -C src/interfaces install</code></strong>
+<strong class="userinput"><code>make -C doc install</code></strong>
+</pre><p>
+ <code class="filename">src/bin</code> has a few binaries for server-only use,
+ but they are small.
+ </p></li></ol></div><p><strong>Uninstallation: </strong>
+ To undo the installation use the command <code class="command">make
+ uninstall</code>. However, this will not remove any created directories.
+ </p><p><strong>Cleaning: </strong>
+ After the installation you can free disk space by removing the built
+ files from the source tree with the command <code class="command">make
+ clean</code>. This will preserve the files made by the <code class="command">configure</code>
+ program, so that you can rebuild everything with <code class="command">make</code>
+ later on. To reset the source tree to the state in which it was
+ distributed, use <code class="command">make distclean</code>. If you are going to
+ build for several platforms within the same source tree you must do
+ this and re-configure for each platform. (Alternatively, use
+ a separate build tree for each platform, so that the source tree
+ remains unmodified.)
+ </p><p>
+ If you perform a build and then discover that your <code class="command">configure</code>
+ options were wrong, or if you change anything that <code class="command">configure</code>
+ investigates (for example, software upgrades), then it's a good
+ idea to do <code class="command">make distclean</code> before reconfiguring and
+ rebuilding. Without this, your changes in configuration choices
+ might not propagate everywhere they need to.
+ </p><div class="sect2" id="CONFIGURE-OPTIONS"><div class="titlepage"><div><div><h3 class="title">17.4.1. <code class="filename">configure</code> Options</h3></div></div></div><a id="id-1.6.4.8.6.2" class="indexterm"></a><p>
+ <code class="command">configure</code>'s command line options are explained below.
+ This list is not exhaustive (use <code class="literal">./configure --help</code>
+ to get one that is). The options not covered here are meant for
+ advanced use-cases such as cross-compilation, and are documented in
+ the standard Autoconf documentation.
+ </p><div class="sect3" id="CONFIGURE-OPTIONS-LOCATIONS"><div class="titlepage"><div><div><h4 class="title">17.4.1.1. Installation Locations</h4></div></div></div><p>
+ These options control where <code class="literal">make install</code> will put
+ the files. The <code class="option">--prefix</code> option is sufficient for
+ most cases. If you have special needs, you can customize the
+ installation subdirectories with the other options described in this
+ section. Beware however that changing the relative locations of the
+ different subdirectories may render the installation non-relocatable,
+ meaning you won't be able to move it after installation.
+ (The <code class="literal">man</code> and <code class="literal">doc</code> locations are
+ not affected by this restriction.) For relocatable installs, you
+ might want to use the <code class="literal">--disable-rpath</code> option
+ described later.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--prefix=<em class="replaceable"><code>PREFIX</code></em></code></span></dt><dd><p>
+ Install all files under the directory <em class="replaceable"><code>PREFIX</code></em>
+ instead of <code class="filename">/usr/local/pgsql</code>. The actual
+ files will be installed into various subdirectories; no files
+ will ever be installed directly into the
+ <em class="replaceable"><code>PREFIX</code></em> directory.
+ </p></dd><dt><span class="term"><code class="option">--exec-prefix=<em class="replaceable"><code>EXEC-PREFIX</code></em></code></span></dt><dd><p>
+ You can install architecture-dependent files under a
+ different prefix, <em class="replaceable"><code>EXEC-PREFIX</code></em>, than what
+ <em class="replaceable"><code>PREFIX</code></em> was set to. This can be useful to
+ share architecture-independent files between hosts. If you
+ omit this, then <em class="replaceable"><code>EXEC-PREFIX</code></em> is set equal to
+ <em class="replaceable"><code>PREFIX</code></em> and both architecture-dependent and
+ independent files will be installed under the same tree,
+ which is probably what you want.
+ </p></dd><dt><span class="term"><code class="option">--bindir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Specifies the directory for executable programs. The default
+ is <code class="filename"><em class="replaceable"><code>EXEC-PREFIX</code></em>/bin</code>, which
+ normally means <code class="filename">/usr/local/pgsql/bin</code>.
+ </p></dd><dt><span class="term"><code class="option">--sysconfdir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the directory for various configuration files,
+ <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/etc</code> by default.
+ </p></dd><dt><span class="term"><code class="option">--libdir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the location to install libraries and dynamically loadable
+ modules. The default is
+ <code class="filename"><em class="replaceable"><code>EXEC-PREFIX</code></em>/lib</code>.
+ </p></dd><dt><span class="term"><code class="option">--includedir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the directory for installing C and C++ header files. The
+ default is <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/include</code>.
+ </p></dd><dt><span class="term"><code class="option">--datarootdir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the root directory for various types of read-only data
+ files. This only sets the default for some of the following
+ options. The default is
+ <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/share</code>.
+ </p></dd><dt><span class="term"><code class="option">--datadir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the directory for read-only data files used by the
+ installed programs. The default is
+ <code class="filename"><em class="replaceable"><code>DATAROOTDIR</code></em></code>. Note that this has
+ nothing to do with where your database files will be placed.
+ </p></dd><dt><span class="term"><code class="option">--localedir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the directory for installing locale data, in particular
+ message translation catalog files. The default is
+ <code class="filename"><em class="replaceable"><code>DATAROOTDIR</code></em>/locale</code>.
+ </p></dd><dt><span class="term"><code class="option">--mandir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ The man pages that come with <span class="productname">PostgreSQL</span> will be installed under
+ this directory, in their respective
+ <code class="filename">man<em class="replaceable"><code>x</code></em></code> subdirectories.
+ The default is <code class="filename"><em class="replaceable"><code>DATAROOTDIR</code></em>/man</code>.
+ </p></dd><dt><span class="term"><code class="option">--docdir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Sets the root directory for installing documentation files,
+ except <span class="quote">“<span class="quote">man</span>”</span> pages. This only sets the default for
+ the following options. The default value for this option is
+ <code class="filename"><em class="replaceable"><code>DATAROOTDIR</code></em>/doc/postgresql</code>.
+ </p></dd><dt><span class="term"><code class="option">--htmldir=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ The HTML-formatted documentation for
+ <span class="productname">PostgreSQL</span> will be installed under
+ this directory. The default is
+ <code class="filename"><em class="replaceable"><code>DATAROOTDIR</code></em></code>.
+ </p></dd></dl></div><div class="note"><h3 class="title">Note</h3><p>
+ Care has been taken to make it possible to install
+ <span class="productname">PostgreSQL</span> into shared installation locations
+ (such as <code class="filename">/usr/local/include</code>) without
+ interfering with the namespace of the rest of the system. First,
+ the string <span class="quote">“<span class="quote"><code class="literal">/postgresql</code></span>”</span> is
+ automatically appended to <code class="varname">datadir</code>,
+ <code class="varname">sysconfdir</code>, and <code class="varname">docdir</code>,
+ unless the fully expanded directory name already contains the
+ string <span class="quote">“<span class="quote"><code class="literal">postgres</code></span>”</span> or
+ <span class="quote">“<span class="quote"><code class="literal">pgsql</code></span>”</span>. For example, if you choose
+ <code class="filename">/usr/local</code> as prefix, the documentation will
+ be installed in <code class="filename">/usr/local/doc/postgresql</code>,
+ but if the prefix is <code class="filename">/opt/postgres</code>, then it
+ will be in <code class="filename">/opt/postgres/doc</code>. The public C
+ header files of the client interfaces are installed into
+ <code class="varname">includedir</code> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under <code class="varname">includedir</code>. See
+ the documentation of each interface for information about how to
+ access its header files. Finally, a private subdirectory will
+ also be created, if appropriate, under <code class="varname">libdir</code>
+ for dynamically loadable modules.
+ </p></div></div><div class="sect3" id="CONFIGURE-OPTIONS-FEATURES"><div class="titlepage"><div><div><h4 class="title">17.4.1.2. <span class="productname">PostgreSQL</span> Features</h4></div></div></div><p>
+ The options described in this section enable building of
+ various <span class="productname">PostgreSQL</span> features that are not
+ built by default. Most of these are non-default only because they
+ require additional software, as described in
+ <a class="xref" href="install-requirements.html" title="17.2. Requirements">Section 17.2</a>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--enable-nls[<span class="optional">=<em class="replaceable"><code>LANGUAGES</code></em></span>]</code></span></dt><dd><p>
+ Enables Native Language Support (<acronym class="acronym">NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English.
+ <em class="replaceable"><code>LANGUAGES</code></em> is an optional space-separated
+ list of codes of the languages that you want supported, for
+ example <code class="literal">--enable-nls='de fr'</code>. (The intersection
+ between your list and the set of actually provided
+ translations will be computed automatically.) If you do not
+ specify a list, then all available translations are
+ installed.
+ </p><p>
+ To use this option, you will need an implementation of the
+ <span class="application">Gettext</span> API.
+ </p></dd><dt><span class="term"><code class="option">--with-perl</code></span></dt><dd><p>
+ Build the <span class="application">PL/Perl</span> server-side language.
+ </p></dd><dt><span class="term"><code class="option">--with-python</code></span></dt><dd><p>
+ Build the <span class="application">PL/Python</span> server-side language.
+ </p></dd><dt><span class="term"><code class="option">--with-tcl</code></span></dt><dd><p>
+ Build the <span class="application">PL/Tcl</span> server-side language.
+ </p></dd><dt><span class="term"><code class="option">--with-tclconfig=<em class="replaceable"><code>DIRECTORY</code></em></code></span></dt><dd><p>
+ Tcl installs the file <code class="filename">tclConfig.sh</code>, which
+ contains configuration information needed to build modules
+ interfacing to Tcl. This file is normally found automatically
+ at a well-known location, but if you want to use a different
+ version of Tcl you can specify the directory in which to look
+ for <code class="filename">tclConfig.sh</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-icu</code></span></dt><dd><p>
+ Build with support for
+ the <span class="productname">ICU</span><a id="id-1.6.4.8.6.5.3.6.2.1.2" class="indexterm"></a>
+ library, enabling use of ICU collation
+ features<span class="phrase"> (see
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>)</span>.
+ This requires the <span class="productname">ICU4C</span> package
+ to be installed. The minimum required version
+ of <span class="productname">ICU4C</span> is currently 4.2.
+ </p><p>
+ By default,
+ <span class="productname">pkg-config</span><a id="id-1.6.4.8.6.5.3.6.2.2.2" class="indexterm"></a>
+ will be used to find the required compilation options. This is
+ supported for <span class="productname">ICU4C</span> version 4.6 and later.
+ For older versions, or if <span class="productname">pkg-config</span> is
+ not available, the variables <code class="envar">ICU_CFLAGS</code>
+ and <code class="envar">ICU_LIBS</code> can be specified
+ to <code class="filename">configure</code>, like in this example:
+</p><pre class="programlisting">
+./configure ... --with-icu ICU_CFLAGS='-I/some/where/include' ICU_LIBS='-L/some/where/lib -licui18n -licuuc -licudata'
+</pre><p>
+ (If <span class="productname">ICU4C</span> is in the default search path
+ for the compiler, then you still need to specify nonempty strings in
+ order to avoid use of <span class="productname">pkg-config</span>, for
+ example, <code class="literal">ICU_CFLAGS=' '</code>.)
+ </p></dd><dt id="CONFIGURE-WITH-LLVM"><span class="term"><code class="option">--with-llvm</code></span></dt><dd><p>
+ Build with support for <span class="productname">LLVM</span> based
+ <acronym class="acronym">JIT</acronym> compilation<span class="phrase"> (see <a class="xref" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Chapter 32</a>)</span>. This
+ requires the <span class="productname">LLVM</span> library to be installed.
+ The minimum required version of <span class="productname">LLVM</span> is
+ currently 3.9.
+ </p><p>
+ <code class="command">llvm-config</code><a id="id-1.6.4.8.6.5.3.7.2.2.2" class="indexterm"></a>
+ will be used to find the required compilation options.
+ <code class="command">llvm-config</code>, and then
+ <code class="command">llvm-config-$major-$minor</code> for all supported
+ versions, will be searched for in your <code class="envar">PATH</code>. If
+ that would not yield the desired program,
+ use <code class="envar">LLVM_CONFIG</code> to specify a path to the
+ correct <code class="command">llvm-config</code>. For example
+</p><pre class="programlisting">
+./configure ... --with-llvm LLVM_CONFIG='/path/to/llvm/bin/llvm-config'
+</pre><p>
+ </p><p>
+ <span class="productname">LLVM</span> support requires a compatible
+ <code class="command">clang</code> compiler (specified, if necessary, using the
+ <code class="envar">CLANG</code> environment variable), and a working C++
+ compiler (specified, if necessary, using the <code class="envar">CXX</code>
+ environment variable).
+ </p></dd><dt><span class="term"><code class="option">--with-lz4</code></span></dt><dd><p>
+ Build with <span class="productname">LZ4</span> compression support.
+ </p></dd><dt><span class="term"><code class="option">--with-zstd</code></span></dt><dd><p>
+ Build with <span class="productname">Zstandard</span> compression support.
+ </p></dd><dt><span class="term"><code class="option">--with-ssl=<em class="replaceable"><code>LIBRARY</code></em></code>
+ <a id="id-1.6.4.8.6.5.3.10.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Build with support for <acronym class="acronym">SSL</acronym> (encrypted)
+ connections. The only <em class="replaceable"><code>LIBRARY</code></em>
+ supported is <code class="option">openssl</code>. This requires the
+ <span class="productname">OpenSSL</span> package to be installed.
+ <code class="filename">configure</code> will check for the required
+ header files and libraries to make sure that your
+ <span class="productname">OpenSSL</span> installation is sufficient
+ before proceeding.
+ </p></dd><dt><span class="term"><code class="option">--with-openssl</code></span></dt><dd><p>
+ Obsolete equivalent of <code class="literal">--with-ssl=openssl</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-gssapi</code></span></dt><dd><p>
+ Build with support for GSSAPI authentication. On many systems, the
+ GSSAPI system (usually a part of the Kerberos installation) is not
+ installed in a location
+ that is searched by default (e.g., <code class="filename">/usr/include</code>,
+ <code class="filename">/usr/lib</code>), so you must use the options
+ <code class="option">--with-includes</code> and <code class="option">--with-libraries</code> in
+ addition to this option. <code class="filename">configure</code> will check
+ for the required header files and libraries to make sure that
+ your GSSAPI installation is sufficient before proceeding.
+ </p></dd><dt><span class="term"><code class="option">--with-ldap</code></span></dt><dd><p>
+ Build with <acronym class="acronym">LDAP</acronym><a id="id-1.6.4.8.6.5.3.13.2.1.2" class="indexterm"></a>
+ support for authentication and connection parameter lookup (see
+ <span id="INSTALL-LDAP-LINKS" class="phrase"><a class="xref" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Section 34.18</a> and
+ <a class="xref" href="auth-ldap.html" title="21.10. LDAP Authentication">Section 21.10</a></span> for more information). On Unix,
+ this requires the <span class="productname">OpenLDAP</span> package to be
+ installed. On Windows, the default <span class="productname">WinLDAP</span>
+ library is used. <code class="filename">configure</code> will check for the required
+ header files and libraries to make sure that your
+ <span class="productname">OpenLDAP</span> installation is sufficient before
+ proceeding.
+ </p></dd><dt><span class="term"><code class="option">--with-pam</code></span></dt><dd><p>
+ Build with <acronym class="acronym">PAM</acronym><a id="id-1.6.4.8.6.5.3.14.2.1.2" class="indexterm"></a>
+ (Pluggable Authentication Modules) support.
+ </p></dd><dt><span class="term"><code class="option">--with-bsd-auth</code></span></dt><dd><p>
+ Build with BSD Authentication support.
+ (The BSD Authentication framework is
+ currently only available on OpenBSD.)
+ </p></dd><dt><span class="term"><code class="option">--with-systemd</code></span></dt><dd><p>
+ Build with support
+ for <span class="application">systemd</span><a id="id-1.6.4.8.6.5.3.16.2.1.2" class="indexterm"></a>
+ service notifications. This improves integration if the server
+ is started under <span class="application">systemd</span> but has no impact
+ otherwise<span class="phrase">; see <a class="xref" href="server-start.html" title="19.3. Starting the Database Server">Section 19.3</a> for more
+ information</span>. <span class="application">libsystemd</span> and the
+ associated header files need to be installed to use this option.
+ </p></dd><dt><span class="term"><code class="option">--with-bonjour</code></span></dt><dd><p>
+ Build with support for Bonjour automatic service discovery.
+ This requires Bonjour support in your operating system.
+ Recommended on macOS.
+ </p></dd><dt><span class="term"><code class="option">--with-uuid=<em class="replaceable"><code>LIBRARY</code></em></code></span></dt><dd><p>
+ Build the <a class="xref" href="uuid-ossp.html" title="F.49. uuid-ossp">uuid-ossp</a> module
+ (which provides functions to generate UUIDs), using the specified
+ UUID library.<a id="id-1.6.4.8.6.5.3.18.2.1.2" class="indexterm"></a>
+ <em class="replaceable"><code>LIBRARY</code></em> must be one of:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="option">bsd</code> to use the UUID functions found in FreeBSD
+ and some other BSD-derived systems
+ </p></li><li class="listitem"><p>
+ <code class="option">e2fs</code> to use the UUID library created by
+ the <code class="literal">e2fsprogs</code> project; this library is present in most
+ Linux systems and in macOS, and can be obtained for other
+ platforms as well
+ </p></li><li class="listitem"><p>
+ <code class="option">ossp</code> to use the <a class="ulink" href="http://www.ossp.org/pkg/lib/uuid/" target="_top">OSSP UUID library</a>
+ </p></li></ul></div></dd><dt><span class="term"><code class="option">--with-ossp-uuid</code></span></dt><dd><p>
+ Obsolete equivalent of <code class="literal">--with-uuid=ossp</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-libxml</code></span></dt><dd><p>
+ Build with libxml2, enabling SQL/XML support. Libxml2 version 2.6.23 or
+ later is required for this feature.
+ </p><p>
+ To detect the required compiler and linker options, PostgreSQL will
+ query <code class="command">pkg-config</code>, if that is installed and knows
+ about libxml2. Otherwise the program <code class="command">xml2-config</code>,
+ which is installed by libxml2, will be used if it is found. Use
+ of <code class="command">pkg-config</code> is preferred, because it can deal
+ with multi-architecture installations better.
+ </p><p>
+ To use a libxml2 installation that is in an unusual location, you
+ can set <code class="command">pkg-config</code>-related environment
+ variables (see its documentation), or set the environment variable
+ <code class="envar">XML2_CONFIG</code> to point to
+ the <code class="command">xml2-config</code> program belonging to the libxml2
+ installation, or set the variables <code class="envar">XML2_CFLAGS</code>
+ and <code class="envar">XML2_LIBS</code>. (If <code class="command">pkg-config</code> is
+ installed, then to override its idea of where libxml2 is you must
+ either set <code class="envar">XML2_CONFIG</code> or set
+ both <code class="envar">XML2_CFLAGS</code> and <code class="envar">XML2_LIBS</code> to
+ nonempty strings.)
+ </p></dd><dt><span class="term"><code class="option">--with-libxslt</code></span></dt><dd><p>
+ Build with libxslt, enabling the
+ <a class="xref" href="xml2.html" title="F.50. xml2">xml2</a>
+ module to perform XSL transformations of XML.
+ <code class="option">--with-libxml</code> must be specified as well.
+ </p></dd></dl></div></div><div class="sect3" id="CONFIGURE-OPTIONS-ANTI-FEATURES"><div class="titlepage"><div><div><h4 class="title">17.4.1.3. Anti-Features</h4></div></div></div><p>
+ The options described in this section allow disabling
+ certain <span class="productname">PostgreSQL</span> features that are built
+ by default, but which might need to be turned off if the required
+ software or system features are not available. Using these options is
+ not recommended unless really necessary.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--without-readline</code></span></dt><dd><p>
+ Prevents use of the <span class="application">Readline</span> library
+ (and <span class="application">libedit</span> as well). This option disables
+ command-line editing and history in
+ <span class="application">psql</span>.
+ </p></dd><dt><span class="term"><code class="option">--with-libedit-preferred</code></span></dt><dd><p>
+ Favors the use of the BSD-licensed <span class="application">libedit</span> library
+ rather than GPL-licensed <span class="application">Readline</span>. This option
+ is significant only if you have both libraries installed; the
+ default in that case is to use <span class="application">Readline</span>.
+ </p></dd><dt><span class="term"><code class="option">--without-zlib</code></span></dt><dd><p>
+ <a id="id-1.6.4.8.6.6.3.3.2.1.1" class="indexterm"></a>
+ Prevents use of the <span class="application">Zlib</span> library.
+ This disables
+ support for compressed archives in <span class="application">pg_dump</span>
+ and <span class="application">pg_restore</span>.
+ </p></dd><dt><span class="term"><code class="option">--disable-spinlocks</code></span></dt><dd><p>
+ Allow the build to succeed even if <span class="productname">PostgreSQL</span>
+ has no CPU spinlock support for the platform. The lack of
+ spinlock support will result in very poor performance; therefore,
+ this option should only be used if the build aborts and
+ informs you that the platform lacks spinlock support. If this
+ option is required to build <span class="productname">PostgreSQL</span> on
+ your platform, please report the problem to the
+ <span class="productname">PostgreSQL</span> developers.
+ </p></dd><dt><span class="term"><code class="option">--disable-atomics</code></span></dt><dd><p>
+ Disable use of CPU atomic operations. This option does nothing on
+ platforms that lack such operations. On platforms that do have
+ them, this will result in poor performance. This option is only
+ useful for debugging or making performance comparisons.
+ </p></dd><dt><span class="term"><code class="option">--disable-thread-safety</code></span></dt><dd><p>
+ Disable the thread-safety of client libraries. This prevents
+ concurrent threads in <span class="application">libpq</span> and
+ <span class="application">ECPG</span> programs from safely controlling
+ their private connection handles. Use this only on platforms
+ with deficient threading support.
+ </p></dd></dl></div></div><div class="sect3" id="CONFIGURE-OPTIONS-BUILD-PROCESS"><div class="titlepage"><div><div><h4 class="title">17.4.1.4. Build Process Details</h4></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--with-includes=<em class="replaceable"><code>DIRECTORIES</code></em></code></span></dt><dd><p>
+ <em class="replaceable"><code>DIRECTORIES</code></em> is a colon-separated list of
+ directories that will be added to the list the compiler
+ searches for header files. If you have optional packages
+ (such as GNU <span class="application">Readline</span>) installed in a non-standard
+ location,
+ you have to use this option and probably also the corresponding
+ <code class="option">--with-libraries</code> option.
+ </p><p>
+ Example: <code class="literal">--with-includes=/opt/gnu/include:/usr/sup/include</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-libraries=<em class="replaceable"><code>DIRECTORIES</code></em></code></span></dt><dd><p>
+ <em class="replaceable"><code>DIRECTORIES</code></em> is a colon-separated list of
+ directories to search for libraries. You will probably have
+ to use this option (and the corresponding
+ <code class="option">--with-includes</code> option) if you have packages
+ installed in non-standard locations.
+ </p><p>
+ Example: <code class="literal">--with-libraries=/opt/gnu/lib:/usr/sup/lib</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-system-tzdata=<em class="replaceable"><code>DIRECTORY</code></em></code>
+ <a id="id-1.6.4.8.6.7.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <span class="productname">PostgreSQL</span> includes its own time zone database,
+ which it requires for date and time operations. This time zone
+ database is in fact compatible with the IANA time zone
+ database provided by many operating systems such as FreeBSD,
+ Linux, and Solaris, so it would be redundant to install it again.
+ When this option is used, the system-supplied time zone database
+ in <em class="replaceable"><code>DIRECTORY</code></em> is used instead of the one
+ included in the PostgreSQL source distribution.
+ <em class="replaceable"><code>DIRECTORY</code></em> must be specified as an
+ absolute path. <code class="filename">/usr/share/zoneinfo</code> is a
+ likely directory on some operating systems. Note that the
+ installation routine will not detect mismatching or erroneous time
+ zone data. If you use this option, you are advised to run the
+ regression tests to verify that the time zone data you have
+ pointed to works correctly with <span class="productname">PostgreSQL</span>.
+ </p><a id="id-1.6.4.8.6.7.2.3.2.2" class="indexterm"></a><p>
+ This option is mainly aimed at binary package distributors
+ who know their target operating system well. The main
+ advantage of using this option is that the PostgreSQL package
+ won't need to be upgraded whenever any of the many local
+ daylight-saving time rules change. Another advantage is that
+ PostgreSQL can be cross-compiled more straightforwardly if the
+ time zone database files do not need to be built during the
+ installation.
+ </p></dd><dt><span class="term"><code class="option">--with-extra-version=<em class="replaceable"><code>STRING</code></em></code></span></dt><dd><p>
+ Append <em class="replaceable"><code>STRING</code></em> to the PostgreSQL version number. You
+ can use this, for example, to mark binaries built from unreleased Git
+ snapshots or containing custom patches with an extra version string,
+ such as a <code class="command">git describe</code> identifier or a
+ distribution package release number.
+ </p></dd><dt><span class="term"><code class="option">--disable-rpath</code></span></dt><dd><p>
+ Do not mark <span class="productname">PostgreSQL</span>'s executables
+ to indicate that they should search for shared libraries in the
+ installation's library directory (see <code class="option">--libdir</code>).
+ On most platforms, this marking uses an absolute path to the
+ library directory, so that it will be unhelpful if you relocate
+ the installation later. However, you will then need to provide
+ some other way for the executables to find the shared libraries.
+ Typically this requires configuring the operating system's
+ dynamic linker to search the library directory; see
+ <a class="xref" href="install-post.html#INSTALL-POST-SHLIBS" title="17.5.1. Shared Libraries">Section 17.5.1</a> for more detail.
+ </p></dd></dl></div></div><div class="sect3" id="CONFIGURE-OPTIONS-MISC"><div class="titlepage"><div><div><h4 class="title">17.4.1.5. Miscellaneous</h4></div></div></div><p>
+ It's fairly common, particularly for test builds, to adjust the
+ default port number with <code class="option">--with-pgport</code>.
+ The other options in this section are recommended only for advanced
+ users.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--with-pgport=<em class="replaceable"><code>NUMBER</code></em></code></span></dt><dd><p>
+ Set <em class="replaceable"><code>NUMBER</code></em> as the default port number for
+ server and clients. The default is 5432. The port can always
+ be changed later on, but if you specify it here then both
+ server and clients will have the same default compiled in,
+ which can be very convenient. Usually the only good reason
+ to select a non-default value is if you intend to run multiple
+ <span class="productname">PostgreSQL</span> servers on the same machine.
+ </p></dd><dt><span class="term"><code class="option">--with-krb-srvnam=<em class="replaceable"><code>NAME</code></em></code></span></dt><dd><p>
+ The default name of the Kerberos service principal used
+ by GSSAPI.
+ <code class="literal">postgres</code> is the default. There's usually no
+ reason to change this unless you are building for a Windows
+ environment, in which case it must be set to upper case
+ <code class="literal">POSTGRES</code>.
+ </p></dd><dt><span class="term"><code class="option">--with-segsize=<em class="replaceable"><code>SEGSIZE</code></em></code></span></dt><dd><p>
+ Set the <em class="firstterm">segment size</em>, in gigabytes. Large tables are
+ divided into multiple operating-system files, each of size equal
+ to the segment size. This avoids problems with file size limits
+ that exist on many platforms. The default segment size, 1 gigabyte,
+ is safe on all supported platforms. If your operating system has
+ <span class="quote">“<span class="quote">largefile</span>”</span> support (which most do, nowadays), you can use
+ a larger segment size. This can be helpful to reduce the number of
+ file descriptors consumed when working with very large tables.
+ But be careful not to select a value larger than is supported
+ by your platform and the file systems you intend to use. Other
+ tools you might wish to use, such as <span class="application">tar</span>, could
+ also set limits on the usable file size.
+ It is recommended, though not absolutely required, that this value
+ be a power of 2.
+ Note that changing this value breaks on-disk database compatibility,
+ meaning you cannot use <code class="command">pg_upgrade</code> to upgrade to
+ a build with a different segment size.
+ </p></dd><dt><span class="term"><code class="option">--with-blocksize=<em class="replaceable"><code>BLOCKSIZE</code></em></code></span></dt><dd><p>
+ Set the <em class="firstterm">block size</em>, in kilobytes. This is the unit
+ of storage and I/O within tables. The default, 8 kilobytes,
+ is suitable for most situations; but other values may be useful
+ in special cases.
+ The value must be a power of 2 between 1 and 32 (kilobytes).
+ Note that changing this value breaks on-disk database compatibility,
+ meaning you cannot use <code class="command">pg_upgrade</code> to upgrade to
+ a build with a different block size.
+ </p></dd><dt><span class="term"><code class="option">--with-wal-blocksize=<em class="replaceable"><code>BLOCKSIZE</code></em></code></span></dt><dd><p>
+ Set the <em class="firstterm">WAL block size</em>, in kilobytes. This is the unit
+ of storage and I/O within the WAL log. The default, 8 kilobytes,
+ is suitable for most situations; but other values may be useful
+ in special cases.
+ The value must be a power of 2 between 1 and 64 (kilobytes).
+ Note that changing this value breaks on-disk database compatibility,
+ meaning you cannot use <code class="command">pg_upgrade</code> to upgrade to
+ a build with a different WAL block size.
+ </p></dd></dl></div></div><div class="sect3" id="CONFIGURE-OPTIONS-DEVEL"><div class="titlepage"><div><div><h4 class="title">17.4.1.6. Developer Options</h4></div></div></div><p>
+ Most of the options in this section are only of interest for
+ developing or debugging <span class="productname">PostgreSQL</span>.
+ They are not recommended for production builds, except
+ for <code class="option">--enable-debug</code>, which can be useful to enable
+ detailed bug reports in the unlucky event that you encounter a bug.
+ On platforms supporting DTrace, <code class="option">--enable-dtrace</code>
+ may also be reasonable to use in production.
+ </p><p>
+ When building an installation that will be used to develop code inside
+ the server, it is recommended to use at least the
+ options <code class="option">--enable-debug</code>
+ and <code class="option">--enable-cassert</code>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--enable-debug</code></span></dt><dd><p>
+ Compiles all programs and libraries with debugging symbols.
+ This means that you can run the programs in a debugger
+ to analyze problems. This enlarges the size of the installed
+ executables considerably, and on non-GCC compilers it usually
+ also disables compiler optimization, causing slowdowns. However,
+ having the symbols available is extremely helpful for dealing
+ with any problems that might arise. Currently, this option is
+ recommended for production installations only if you use GCC.
+ But you should always have it on if you are doing development work
+ or running a beta version.
+ </p></dd><dt><span class="term"><code class="option">--enable-cassert</code></span></dt><dd><p>
+ Enables <em class="firstterm">assertion</em> checks in the server, which test for
+ many <span class="quote">“<span class="quote">cannot happen</span>”</span> conditions. This is invaluable for
+ code development purposes, but the tests can slow down the
+ server significantly.
+ Also, having the tests turned on won't necessarily enhance the
+ stability of your server! The assertion checks are not categorized
+ for severity, and so what might be a relatively harmless bug will
+ still lead to server restarts if it triggers an assertion
+ failure. This option is not recommended for production use, but
+ you should have it on for development work or when running a beta
+ version.
+ </p></dd><dt><span class="term"><code class="option">--enable-tap-tests</code></span></dt><dd><p>
+ Enable tests using the Perl TAP tools. This requires a Perl
+ installation and the Perl module <code class="literal">IPC::Run</code>.
+ <span class="phrase">See <a class="xref" href="regress-tap.html" title="33.4. TAP Tests">Section 33.4</a> for more information.</span>
+ </p></dd><dt><span class="term"><code class="option">--enable-depend</code></span></dt><dd><p>
+ Enables automatic dependency tracking. With this option, the
+ makefiles are set up so that all affected object files will
+ be rebuilt when any header file is changed. This is useful
+ if you are doing development work, but is just wasted overhead
+ if you intend only to compile once and install. At present,
+ this option only works with GCC.
+ </p></dd><dt><span class="term"><code class="option">--enable-coverage</code></span></dt><dd><p>
+ If using GCC, all programs and libraries are compiled with
+ code coverage testing instrumentation. When run, they
+ generate files in the build directory with code coverage
+ metrics.
+ <span class="phrase">See <a class="xref" href="regress-coverage.html" title="33.5. Test Coverage Examination">Section 33.5</a>
+ for more information.</span> This option is for use only with GCC
+ and when doing development work.
+ </p></dd><dt><span class="term"><code class="option">--enable-profiling</code></span></dt><dd><p>
+ If using GCC, all programs and libraries are compiled so they
+ can be profiled. On backend exit, a subdirectory will be created
+ that contains the <code class="filename">gmon.out</code> file containing
+ profile data.
+ This option is for use only with GCC and when doing development work.
+ </p></dd><dt><span class="term"><code class="option">--enable-dtrace</code></span></dt><dd><p>
+ <a id="id-1.6.4.8.6.9.4.7.2.1.1" class="indexterm"></a>
+ Compiles <span class="productname">PostgreSQL</span> with support for the
+ dynamic tracing tool DTrace.
+ <span class="phrase">See <a class="xref" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Section 28.5</a>
+ for more information.</span>
+ </p><p>
+ To point to the <code class="command">dtrace</code> program, the
+ environment variable <code class="envar">DTRACE</code> can be set. This
+ will often be necessary because <code class="command">dtrace</code> is
+ typically installed under <code class="filename">/usr/sbin</code>,
+ which might not be in your <code class="envar">PATH</code>.
+ </p><p>
+ Extra command-line options for the <code class="command">dtrace</code> program
+ can be specified in the environment variable
+ <code class="envar">DTRACEFLAGS</code>. On Solaris,
+ to include DTrace support in a 64-bit binary, you must specify
+ <code class="literal">DTRACEFLAGS="-64"</code>. For example,
+ using the GCC compiler:
+</p><pre class="screen">
+./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
+</pre><p>
+ Using Sun's compiler:
+</p><pre class="screen">
+./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ...
+</pre><p>
+ </p></dd></dl></div></div></div><div class="sect2" id="CONFIGURE-ENVVARS"><div class="titlepage"><div><div><h3 class="title">17.4.2. <code class="filename">configure</code> Environment Variables</h3></div></div></div><a id="id-1.6.4.8.7.2" class="indexterm"></a><p>
+ In addition to the ordinary command-line options described above,
+ <code class="filename">configure</code> responds to a number of environment
+ variables.
+ You can specify environment variables on the
+ <code class="filename">configure</code> command line, for example:
+</p><pre class="screen">
+<strong class="userinput"><code>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</code></strong>
+</pre><p>
+ In this usage an environment variable is little different from a
+ command-line option.
+ You can also set such variables beforehand:
+</p><pre class="screen">
+<strong class="userinput"><code>export CC=/opt/bin/gcc</code></strong>
+<strong class="userinput"><code>export CFLAGS='-O2 -pipe'</code></strong>
+<strong class="userinput"><code>./configure</code></strong>
+</pre><p>
+ This usage can be convenient because many programs' configuration
+ scripts respond to these variables in similar ways.
+ </p><p>
+ The most commonly used of these environment variables are
+ <code class="envar">CC</code> and <code class="envar">CFLAGS</code>.
+ If you prefer a C compiler different from the one
+ <code class="filename">configure</code> picks, you can set the
+ variable <code class="envar">CC</code> to the program of your choice.
+ By default, <code class="filename">configure</code> will pick
+ <code class="filename">gcc</code> if available, else the platform's
+ default (usually <code class="filename">cc</code>). Similarly, you can override the
+ default compiler flags if needed with the <code class="envar">CFLAGS</code> variable.
+ </p><p>
+ Here is a list of the significant variables that can be set in
+ this manner:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">BISON</code></span></dt><dd><p>
+ Bison program
+ </p></dd><dt><span class="term"><code class="envar">CC</code></span></dt><dd><p>
+ C compiler
+ </p></dd><dt><span class="term"><code class="envar">CFLAGS</code></span></dt><dd><p>
+ options to pass to the C compiler
+ </p></dd><dt><span class="term"><code class="envar">CLANG</code></span></dt><dd><p>
+ path to <code class="command">clang</code> program used to process source code
+ for inlining when compiling with <code class="literal">--with-llvm</code>
+ </p></dd><dt><span class="term"><code class="envar">CPP</code></span></dt><dd><p>
+ C preprocessor
+ </p></dd><dt><span class="term"><code class="envar">CPPFLAGS</code></span></dt><dd><p>
+ options to pass to the C preprocessor
+ </p></dd><dt><span class="term"><code class="envar">CXX</code></span></dt><dd><p>
+ C++ compiler
+ </p></dd><dt><span class="term"><code class="envar">CXXFLAGS</code></span></dt><dd><p>
+ options to pass to the C++ compiler
+ </p></dd><dt><span class="term"><code class="envar">DTRACE</code></span></dt><dd><p>
+ location of the <code class="command">dtrace</code> program
+ </p></dd><dt><span class="term"><code class="envar">DTRACEFLAGS</code></span></dt><dd><p>
+ options to pass to the <code class="command">dtrace</code> program
+ </p></dd><dt><span class="term"><code class="envar">FLEX</code></span></dt><dd><p>
+ Flex program
+ </p></dd><dt><span class="term"><code class="envar">LDFLAGS</code></span></dt><dd><p>
+ options to use when linking either executables or shared libraries
+ </p></dd><dt><span class="term"><code class="envar">LDFLAGS_EX</code></span></dt><dd><p>
+ additional options for linking executables only
+ </p></dd><dt><span class="term"><code class="envar">LDFLAGS_SL</code></span></dt><dd><p>
+ additional options for linking shared libraries only
+ </p></dd><dt><span class="term"><code class="envar">LLVM_CONFIG</code></span></dt><dd><p>
+ <code class="command">llvm-config</code> program used to locate the
+ <span class="productname">LLVM</span> installation
+ </p></dd><dt><span class="term"><code class="envar">MSGFMT</code></span></dt><dd><p>
+ <code class="command">msgfmt</code> program for native language support
+ </p></dd><dt><span class="term"><code class="envar">PERL</code></span></dt><dd><p>
+ Perl interpreter program. This will be used to determine the
+ dependencies for building PL/Perl. The default is
+ <code class="command">perl</code>.
+ </p></dd><dt><span class="term"><code class="envar">PYTHON</code></span></dt><dd><p>
+ Python interpreter program. This will be used to determine the
+ dependencies for building PL/Python. If this is not set, the
+ following are probed in this order:
+ <code class="literal">python3 python</code>.
+ </p></dd><dt><span class="term"><code class="envar">TCLSH</code></span></dt><dd><p>
+ Tcl interpreter program. This will be used to
+ determine the dependencies for building PL/Tcl.
+ If this is not set, the following are probed in this
+ order: <code class="literal">tclsh tcl tclsh8.6 tclsh86 tclsh8.5 tclsh85
+ tclsh8.4 tclsh84</code>.
+ </p></dd><dt><span class="term"><code class="envar">XML2_CONFIG</code></span></dt><dd><p>
+ <code class="command">xml2-config</code> program used to locate the
+ libxml2 installation
+ </p></dd></dl></div><p>
+ </p><p>
+ Sometimes it is useful to add compiler flags after-the-fact to the set
+ that were chosen by <code class="filename">configure</code>. An important example is
+ that <span class="application">gcc</span>'s <code class="option">-Werror</code> option cannot be included
+ in the <code class="envar">CFLAGS</code> passed to <code class="filename">configure</code>, because
+ it will break many of <code class="filename">configure</code>'s built-in tests. To add
+ such flags, include them in the <code class="envar">COPT</code> environment variable
+ while running <code class="filename">make</code>. The contents of <code class="envar">COPT</code>
+ are added to both the <code class="envar">CFLAGS</code> and <code class="envar">LDFLAGS</code>
+ options set up by <code class="filename">configure</code>. For example, you could do
+</p><pre class="screen">
+<strong class="userinput"><code>make COPT='-Werror'</code></strong>
+</pre><p>
+ or
+</p><pre class="screen">
+<strong class="userinput"><code>export COPT='-Werror'</code></strong>
+<strong class="userinput"><code>make</code></strong>
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If using GCC, it is best to build with an optimization level of
+ at least <code class="option">-O1</code>, because using no optimization
+ (<code class="option">-O0</code>) disables some important compiler warnings (such
+ as the use of uninitialized variables). However, non-zero
+ optimization levels can complicate debugging because stepping
+ through compiled code will usually not match up one-to-one with
+ source code lines. If you get confused while trying to debug
+ optimized code, recompile the specific files of interest with
+ <code class="option">-O0</code>. An easy way to do this is by passing an option
+ to <span class="application">make</span>: <code class="command">make PROFILE=-O0 file.o</code>.
+ </p><p>
+ The <code class="envar">COPT</code> and <code class="envar">PROFILE</code> environment variables are
+ actually handled identically by the <span class="productname">PostgreSQL</span>
+ makefiles. Which to use is a matter of preference, but a common habit
+ among developers is to use <code class="envar">PROFILE</code> for one-time flag
+ adjustments, while <code class="envar">COPT</code> might be kept set all the time.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-getsource.html" title="17.3. Getting the Source">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-post.html" title="17.5. Post-Installation Setup">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.3. Getting the Source </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.5. Post-Installation Setup</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-requirements.html b/doc/src/sgml/html/install-requirements.html
new file mode 100644
index 0000000..4921e5d
--- /dev/null
+++ b/doc/src/sgml/html/install-requirements.html
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.2. Requirements</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-short.html" title="17.1. Short Version" /><link rel="next" href="install-getsource.html" title="17.3. Getting the Source" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.2. Requirements</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-short.html" title="17.1. Short Version">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-getsource.html" title="17.3. Getting the Source">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-REQUIREMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.2. Requirements</h2></div></div></div><p>
+ In general, a modern Unix-compatible platform should be able to run
+ <span class="productname">PostgreSQL</span>.
+ The platforms that had received specific testing at the
+ time of release are described in <a class="xref" href="supported-platforms.html" title="17.6. Supported Platforms">Section 17.6</a>
+ below.
+ </p><p>
+ The following software packages are required for building
+ <span class="productname">PostgreSQL</span>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a id="id-1.6.4.6.3.2.1.1.1" class="indexterm"></a>
+
+ <acronym class="acronym">GNU</acronym> <span class="application">make</span> version 3.81 or newer is required; other
+ <span class="application">make</span> programs or older <acronym class="acronym">GNU</acronym> <span class="application">make</span> versions will <span class="emphasis"><em>not</em></span> work.
+ (<acronym class="acronym">GNU</acronym> <span class="application">make</span> is sometimes installed under
+ the name <code class="filename">gmake</code>.) To test for <acronym class="acronym">GNU</acronym>
+ <span class="application">make</span> enter:
+</p><pre class="screen">
+<strong class="userinput"><code>make --version</code></strong>
+</pre><p>
+ </p></li><li class="listitem"><p>
+ You need an <acronym class="acronym">ISO</acronym>/<acronym class="acronym">ANSI</acronym> C compiler (at least
+ C99-compliant). Recent
+ versions of <span class="productname">GCC</span> are recommended, but
+ <span class="productname">PostgreSQL</span> is known to build using a wide variety
+ of compilers from different vendors.
+ </p></li><li class="listitem"><p>
+ <span class="application">tar</span> is required to unpack the source
+ distribution, in addition to either
+ <span class="application">gzip</span> or <span class="application">bzip2</span>.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.6.4.6.3.2.4.1.1" class="indexterm"></a>
+ <a id="id-1.6.4.6.3.2.4.1.2" class="indexterm"></a>
+
+ The <acronym class="acronym">GNU</acronym> <span class="productname">Readline</span> library is used by
+ default. It allows <span class="application">psql</span> (the
+ PostgreSQL command line SQL interpreter) to remember each
+ command you type, and allows you to use arrow keys to recall and
+ edit previous commands. This is very helpful and is strongly
+ recommended. If you don't want to use it then you must specify
+ the <code class="option">--without-readline</code> option to
+ <code class="filename">configure</code>. As an alternative, you can often use the
+ BSD-licensed <code class="filename">libedit</code> library, originally
+ developed on <span class="productname">NetBSD</span>. The
+ <code class="filename">libedit</code> library is
+ GNU <span class="productname">Readline</span>-compatible and is used if
+ <code class="filename">libreadline</code> is not found, or if
+ <code class="option">--with-libedit-preferred</code> is used as an
+ option to <code class="filename">configure</code>. If you are using a package-based
+ Linux distribution, be aware that you need both the
+ <code class="literal">readline</code> and <code class="literal">readline-devel</code> packages, if
+ those are separate in your distribution.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.6.4.6.3.2.5.1.1" class="indexterm"></a>
+
+ The <span class="productname">zlib</span> compression library is
+ used by default. If you don't want to use it then you must
+ specify the <code class="option">--without-zlib</code> option to
+ <code class="filename">configure</code>. Using this option disables
+ support for compressed archives in <span class="application">pg_dump</span> and
+ <span class="application">pg_restore</span>.
+ </p></li></ul></div><p>
+ </p><p>
+ The following packages are optional. They are not required in the
+ default configuration, but they are needed when certain build
+ options are enabled, as explained below:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ To build the server programming language
+ <span class="application">PL/Perl</span> you need a full
+ <span class="productname">Perl</span> installation, including the
+ <code class="filename">libperl</code> library and the header files.
+ The minimum required version is <span class="productname">Perl</span> 5.8.3.
+ Since <span class="application">PL/Perl</span> will be a shared
+ library, the <a id="id-1.6.4.6.4.1.1.1.6" class="indexterm"></a>
+ <code class="filename">libperl</code> library must be a shared library
+ also on most platforms. This appears to be the default in
+ recent <span class="productname">Perl</span> versions, but it was not
+ in earlier versions, and in any case it is the choice of whomever
+ installed Perl at your site. <code class="filename">configure</code> will fail
+ if building <span class="application">PL/Perl</span> is selected but it cannot
+ find a shared <code class="filename">libperl</code>. In that case, you will have
+ to rebuild and install <span class="productname">Perl</span> manually to be
+ able to build <span class="application">PL/Perl</span>. During the
+ configuration process for <span class="productname">Perl</span>, request a
+ shared library.
+ </p><p>
+ If you intend to make more than incidental use of
+ <span class="application">PL/Perl</span>, you should ensure that the
+ <span class="productname">Perl</span> installation was built with the
+ <code class="literal">usemultiplicity</code> option enabled (<code class="literal">perl -V</code>
+ will show whether this is the case).
+ </p></li><li class="listitem"><p>
+ To build the <span class="application">PL/Python</span> server programming
+ language, you need a <span class="productname">Python</span>
+ installation with the header files and
+ the <span class="application">sysconfig</span> module. The minimum
+ required version is <span class="productname">Python</span> 3.2.
+ </p><p>
+ Since <span class="application">PL/Python</span> will be a shared
+ library, the <a id="id-1.6.4.6.4.1.2.2.2" class="indexterm"></a>
+ <code class="filename">libpython</code> library must be a shared library
+ also on most platforms. This is not the case in a default
+ <span class="productname">Python</span> installation built from source, but a
+ shared library is available in many operating system
+ distributions. <code class="filename">configure</code> will fail if
+ building <span class="application">PL/Python</span> is selected but it cannot
+ find a shared <code class="filename">libpython</code>. That might mean that you
+ either have to install additional packages or rebuild (part of) your
+ <span class="productname">Python</span> installation to provide this shared
+ library. When building from source, run <span class="productname">Python</span>'s
+ configure with the <code class="literal">--enable-shared</code> flag.
+ </p></li><li class="listitem"><p>
+ To build the <span class="application">PL/Tcl</span>
+ procedural language, you of course need a <span class="productname">Tcl</span>
+ installation. The minimum required version is
+ <span class="productname">Tcl</span> 8.4.
+ </p></li><li class="listitem"><p>
+ To enable Native Language Support (<acronym class="acronym">NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the
+ <span class="application">Gettext</span> <acronym class="acronym">API</acronym>. Some operating
+ systems have this built-in (e.g., <span class="systemitem">Linux</span>, <span class="systemitem">NetBSD</span>,
+ <span class="systemitem">Solaris</span>), for other systems you
+ can download an add-on package from <a class="ulink" href="https://www.gnu.org/software/gettext/" target="_top">https://www.gnu.org/software/gettext/</a>.
+ If you are using the <span class="application">Gettext</span> implementation in
+ the <acronym class="acronym">GNU</acronym> C library then you will additionally
+ need the <span class="productname">GNU Gettext</span> package for some
+ utility programs. For any of the other implementations you will
+ not need it.
+ </p></li><li class="listitem"><p>
+ You need <span class="productname">OpenSSL</span>, if you want to support
+ encrypted client connections. <span class="productname">OpenSSL</span> is
+ also required for random number generation on platforms that do not
+ have <code class="filename">/dev/urandom</code> (except Windows). The minimum
+ required version is 1.0.1.
+ </p></li><li class="listitem"><p>
+ You need <span class="application">Kerberos</span>, <span class="productname">OpenLDAP</span>,
+ and/or <span class="application">PAM</span>, if you want to support authentication
+ using those services.
+ </p></li><li class="listitem"><p>
+ You need <span class="productname">LZ4</span>, if you want to support
+ compression of data with that method; see
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TOAST-COMPRESSION">default_toast_compression</a> and
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-COMPRESSION">wal_compression</a>.
+ </p></li><li class="listitem"><p>
+ You need <span class="productname">Zstandard</span>, if you want to support
+ compression of data with that method; see
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-COMPRESSION">wal_compression</a>.
+ The minimum required version is 1.4.0.
+ </p></li><li class="listitem"><p>
+ To build the <span class="productname">PostgreSQL</span> documentation,
+ there is a separate set of requirements; see
+ <a class="xref" href="docguide-toolsets.html" title="J.2. Tool Sets">Section J.2</a>.
+ </p></li></ul></div><p>
+ </p><p>
+ If you are building from a <span class="productname">Git</span> tree instead of
+ using a released source package, or if you want to do server development,
+ you also need the following packages:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a id="id-1.6.4.6.5.2.1.1.1" class="indexterm"></a>
+ <a id="id-1.6.4.6.5.2.1.1.2" class="indexterm"></a>
+ <a id="id-1.6.4.6.5.2.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.4.6.5.2.1.1.4" class="indexterm"></a>
+
+ <span class="application">Flex</span> and <span class="application">Bison</span>
+ are needed to build from a Git checkout, or if you changed the actual
+ scanner and parser definition files. If you need them, be sure
+ to get <span class="application">Flex</span> 2.5.31 or later and
+ <span class="application">Bison</span> 1.875 or later. Other <span class="application">lex</span>
+ and <span class="application">yacc</span> programs cannot be used.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.6.4.6.5.2.2.1.1" class="indexterm"></a>
+
+ <span class="application">Perl</span> 5.8.3 or later is needed to build from a Git checkout,
+ or if you changed the input files for any of the build steps that
+ use Perl scripts. If building on Windows you will need
+ <span class="application">Perl</span> in any case. <span class="application">Perl</span> is
+ also required to run some test suites.
+ </p></li></ul></div><p>
+ </p><p>
+ If you need to get a <acronym class="acronym">GNU</acronym> package, you can find
+ it at your local <acronym class="acronym">GNU</acronym> mirror site (see <a class="ulink" href="https://www.gnu.org/prep/ftp" target="_top">https://www.gnu.org/prep/ftp</a>
+ for a list) or at <a class="ulink" href="ftp://ftp.gnu.org/gnu/" target="_top">ftp://ftp.gnu.org/gnu/</a>.
+ </p><p>
+ Also check that you have sufficient disk space. You will need about
+ 350 MB for the source tree during compilation and about 60 MB for
+ the installation directory. An empty database cluster takes about
+ 40 MB; databases take about five times the amount of space that a
+ flat text file with the same data would take. If you are going to
+ run the regression tests you will temporarily need up to an extra
+ 300 MB. Use the <code class="command">df</code> command to check free disk
+ space.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-short.html" title="17.1. Short Version">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-getsource.html" title="17.3. Getting the Source">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.1. Short Version </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.3. Getting the Source</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-short.html b/doc/src/sgml/html/install-short.html
new file mode 100644
index 0000000..700f5de
--- /dev/null
+++ b/doc/src/sgml/html/install-short.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.1. Short Version</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="installation.html" title="Chapter 17. Installation from Source Code" /><link rel="next" href="install-requirements.html" title="17.2. Requirements" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.1. Short Version</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="installation.html" title="Chapter 17. Installation from Source Code">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-requirements.html" title="17.2. Requirements">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-SHORT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.1. Short Version</h2></div></div></div><p>
+</p><pre class="synopsis">
+./configure
+make
+su
+make install
+adduser postgres
+mkdir -p /usr/local/pgsql/data
+chown postgres /usr/local/pgsql/data
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
+/usr/local/pgsql/bin/createdb test
+/usr/local/pgsql/bin/psql test
+</pre><p>
+ The long version is the rest of this
+ <span class="phrase">chapter</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation.html" title="Chapter 17. Installation from Source Code">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-requirements.html" title="17.2. Requirements">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 17. Installation from Source Code </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.2. Requirements</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-windows-full.html b/doc/src/sgml/html/install-windows-full.html
new file mode 100644
index 0000000..ba963fa
--- /dev/null
+++ b/doc/src/sgml/html/install-windows-full.html
@@ -0,0 +1,341 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>18.1. Building with Visual C++ or the Microsoft Windows SDK</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows" /><link rel="next" href="runtime.html" title="Chapter 19. Server Setup and Operation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Up</a></td><th width="60%" align="center">Chapter 18. Installation from Source Code on <span class="productname">Windows</span></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime.html" title="Chapter 19. Server Setup and Operation">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALL-WINDOWS-FULL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.8">18.1.1. Requirements</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.9">18.1.2. Special Considerations for 64-Bit Windows</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.10">18.1.3. Building</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.11">18.1.4. Cleaning and Installing</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.12">18.1.5. Running the Regression Tests</a></span></dt></dl></div><p>
+ PostgreSQL can be built using the Visual C++ compiler suite from Microsoft.
+ These compilers can be either from <span class="productname">Visual Studio</span>,
+ <span class="productname">Visual Studio Express</span> or some versions of the
+ <span class="productname">Microsoft Windows SDK</span>. If you do not already have a
+ <span class="productname">Visual Studio</span> environment set up, the easiest
+ ways are to use the compilers from
+ <span class="productname">Visual Studio 2022</span> or those in the
+ <span class="productname">Windows SDK 10</span>, which are both free downloads
+ from Microsoft.
+ </p><p>
+ Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite.
+ 32-bit PostgreSQL builds are possible with
+ <span class="productname">Visual Studio 2013</span> to
+ <span class="productname">Visual Studio 2022</span>,
+ as well as standalone Windows SDK releases 8.1a to 10.
+ 64-bit PostgreSQL builds are supported with
+ <span class="productname">Microsoft Windows SDK</span> version 8.1a to 10 or
+ <span class="productname">Visual Studio 2013</span> and above. Compilation
+ is supported down to <span class="productname">Windows 7</span> and
+ <span class="productname">Windows Server 2008 R2 SP1</span> when building with
+ <span class="productname">Visual Studio 2013</span> to
+ <span class="productname">Visual Studio 2022</span>.
+
+ </p><p>
+ The tools for building using <span class="productname">Visual C++</span> or
+ <span class="productname">Platform SDK</span> are in the
+ <code class="filename">src\tools\msvc</code> directory. When building, make sure
+ there are no tools from <span class="productname">MinGW</span> or
+ <span class="productname">Cygwin</span> present in your system PATH. Also, make
+ sure you have all the required Visual C++ tools available in the PATH. In
+ <span class="productname">Visual Studio</span>, start the
+ <span class="application">Visual Studio Command Prompt</span>.
+ If you wish to build a 64-bit version, you must use the 64-bit version of
+ the command, and vice versa.
+ Starting with <span class="productname">Visual Studio 2017</span> this can be
+ done from the command line using <code class="command">VsDevCmd.bat</code>, see
+ <code class="command">-help</code> for the available options and their default values.
+ <code class="command">vsvars32.bat</code> is available in
+ <span class="productname">Visual Studio 2015</span> and earlier versions for the
+ same purpose.
+ From the <span class="application">Visual Studio Command Prompt</span>, you can
+ change the targeted CPU architecture, build type, and target OS by using the
+ <code class="command">vcvarsall.bat</code> command, e.g.,
+ <code class="command">vcvarsall.bat x64 10.0.10240.0</code> to target Windows 10
+ with a 64-bit release build. See <code class="command">-help</code> for the other
+ options of <code class="command">vcvarsall.bat</code>. All commands should be run from
+ the <code class="filename">src\tools\msvc</code> directory.
+ </p><p>
+ Before you build, you can create the file <code class="filename">config.pl</code>
+ to reflect any configuration options you want to change, or the paths to
+ any third party libraries to use. The complete configuration is determined
+ by first reading and parsing the file <code class="filename">config_default.pl</code>,
+ and then apply any changes from <code class="filename">config.pl</code>. For example,
+ to specify the location of your <span class="productname">Python</span> installation,
+ put the following in <code class="filename">config.pl</code>:
+</p><pre class="programlisting">
+$config-&gt;{python} = 'c:\python310';
+</pre><p>
+ You only need to specify those parameters that are different from what's in
+ <code class="filename">config_default.pl</code>.
+ </p><p>
+ If you need to set any other environment variables, create a file called
+ <code class="filename">buildenv.pl</code> and put the required commands there. For
+ example, to add the path for bison when it's not in the PATH, create a file
+ containing:
+</p><pre class="programlisting">
+$ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
+</pre><p>
+ </p><p>
+ To pass additional command line arguments to the Visual Studio build
+ command (msbuild or vcbuild):
+</p><pre class="programlisting">
+$ENV{MSBFLAGS}="/m";
+</pre><p>
+ </p><div class="sect2" id="id-1.6.5.8.8"><div class="titlepage"><div><div><h3 class="title">18.1.1. Requirements</h3></div></div></div><p>
+ The following additional products are required to build
+ <span class="productname">PostgreSQL</span>. Use the
+ <code class="filename">config.pl</code> file to specify which directories the libraries
+ are available in.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="productname">Microsoft Windows SDK</span></span></dt><dd><p>
+ If your build environment doesn't ship with a supported version of the
+ <span class="productname">Microsoft Windows SDK</span> it
+ is recommended that you upgrade to the latest version (currently
+ version 10), available for download from
+ <a class="ulink" href="https://www.microsoft.com/download" target="_top">https://www.microsoft.com/download</a>.
+ </p><p>
+ You must always include the
+ <span class="application">Windows Headers and Libraries</span> part of the SDK.
+ If you install a <span class="productname">Windows SDK</span>
+ including the <span class="application">Visual C++ Compilers</span>,
+ you don't need <span class="productname">Visual Studio</span> to build.
+ Note that as of Version 8.0a the Windows SDK no longer ships with a
+ complete command-line build environment.
+ </p></dd><dt><span class="term"><span class="productname">ActiveState Perl</span></span></dt><dd><p>
+ ActiveState Perl is required to run the build generation scripts. MinGW
+ or Cygwin Perl will not work. It must also be present in the PATH.
+ Binaries can be downloaded from
+ <a class="ulink" href="https://www.activestate.com" target="_top">https://www.activestate.com</a>
+ (Note: version 5.8.3 or later is required,
+ the free Standard Distribution is sufficient).
+ </p></dd></dl></div><p>
+ </p><p>
+ The following additional products are not required to get started,
+ but are required to build the complete package. Use the
+ <code class="filename">config.pl</code> file to specify which directories the libraries
+ are available in.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="productname">ActiveState TCL</span></span></dt><dd><p>
+ Required for building <span class="application">PL/Tcl</span> (Note: version
+ 8.4 is required, the free Standard Distribution is sufficient).
+ </p></dd><dt><span class="term"><span class="productname">Bison</span> and
+ <span class="productname">Flex</span></span></dt><dd><p>
+ <span class="productname">Bison</span> and <span class="productname">Flex</span> are
+ required to build from Git, but not required when building from a release
+ file. Only <span class="productname">Bison</span> 1.875 or versions 2.2 and later
+ will work. <span class="productname">Flex</span> must be version 2.5.31 or later.
+ </p><p>
+ Both <span class="productname">Bison</span> and <span class="productname">Flex</span>
+ are included in the <span class="productname">msys</span> tool suite, available
+ from <a class="ulink" href="http://www.mingw.org/wiki/MSYS" target="_top">http://www.mingw.org/wiki/MSYS</a> as part of the
+ <span class="productname">MinGW</span> compiler suite.
+ </p><p>
+ You will need to add the directory containing
+ <code class="filename">flex.exe</code> and <code class="filename">bison.exe</code> to the
+ PATH environment variable in <code class="filename">buildenv.pl</code> unless
+ they are already in PATH. In the case of MinGW, the directory is the
+ <code class="filename">\msys\1.0\bin</code> subdirectory of your MinGW
+ installation directory.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The Bison distribution from GnuWin32 appears to have a bug that
+ causes Bison to malfunction when installed in a directory with
+ spaces in the name, such as the default location on English
+ installations <code class="filename">C:\Program Files\GnuWin32</code>.
+ Consider installing into <code class="filename">C:\GnuWin32</code> or use the
+ NTFS short name path to GnuWin32 in your PATH environment setting
+ (e.g., <code class="filename">C:\PROGRA~1\GnuWin32</code>).
+ </p></div></dd><dt><span class="term"><span class="productname">Diff</span></span></dt><dd><p>
+ Diff is required to run the regression tests, and can be downloaded
+ from <a class="ulink" href="http://gnuwin32.sourceforge.net" target="_top">http://gnuwin32.sourceforge.net</a>.
+ </p></dd><dt><span class="term"><span class="productname">Gettext</span></span></dt><dd><p>
+ Gettext is required to build with NLS support, and can be downloaded
+ from <a class="ulink" href="http://gnuwin32.sourceforge.net" target="_top">http://gnuwin32.sourceforge.net</a>. Note that binaries,
+ dependencies and developer files are all needed.
+ </p></dd><dt><span class="term"><span class="productname">MIT Kerberos</span></span></dt><dd><p>
+ Required for GSSAPI authentication support. MIT Kerberos can be
+ downloaded from
+ <a class="ulink" href="https://web.mit.edu/Kerberos/dist/index.html" target="_top">https://web.mit.edu/Kerberos/dist/index.html</a>.
+ </p></dd><dt><span class="term"><span class="productname">libxml2</span> and
+ <span class="productname">libxslt</span></span></dt><dd><p>
+ Required for XML support. Binaries can be downloaded from
+ <a class="ulink" href="https://zlatkovic.com/pub/libxml" target="_top">https://zlatkovic.com/pub/libxml</a> or source from
+ <a class="ulink" href="http://xmlsoft.org" target="_top">http://xmlsoft.org</a>. Note that libxml2 requires iconv,
+ which is available from the same download location.
+ </p></dd><dt><span class="term"><span class="productname">LZ4</span></span></dt><dd><p>
+ Required for supporting <span class="productname">LZ4</span> compression.
+ Binaries and source can be downloaded from
+ <a class="ulink" href="https://github.com/lz4/lz4/releases" target="_top">https://github.com/lz4/lz4/releases</a>.
+ </p></dd><dt><span class="term"><span class="productname">Zstandard</span></span></dt><dd><p>
+ Required for supporting <span class="productname">Zstandard</span> compression.
+ Binaries and source can be downloaded from
+ <a class="ulink" href="https://github.com/facebook/zstd/releases" target="_top">https://github.com/facebook/zstd/releases</a>.
+ </p></dd><dt><span class="term"><span class="productname">OpenSSL</span></span></dt><dd><p>
+ Required for SSL support. Binaries can be downloaded from
+ <a class="ulink" href="https://slproweb.com/products/Win32OpenSSL.html" target="_top">https://slproweb.com/products/Win32OpenSSL.html</a>
+ or source from <a class="ulink" href="https://www.openssl.org" target="_top">https://www.openssl.org</a>.
+ </p></dd><dt><span class="term"><span class="productname">ossp-uuid</span></span></dt><dd><p>
+ Required for UUID-OSSP support (contrib only). Source can be
+ downloaded from
+ <a class="ulink" href="http://www.ossp.org/pkg/lib/uuid/" target="_top">http://www.ossp.org/pkg/lib/uuid/</a>.
+ </p></dd><dt><span class="term"><span class="productname">Python</span></span></dt><dd><p>
+ Required for building <span class="application">PL/Python</span>. Binaries can
+ be downloaded from <a class="ulink" href="https://www.python.org" target="_top">https://www.python.org</a>.
+ </p></dd><dt><span class="term"><span class="productname">zlib</span></span></dt><dd><p>
+ Required for compression support in <span class="application">pg_dump</span>
+ and <span class="application">pg_restore</span>. Binaries can be downloaded
+ from <a class="ulink" href="https://www.zlib.net" target="_top">https://www.zlib.net</a>.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="id-1.6.5.8.9"><div class="titlepage"><div><div><h3 class="title">18.1.2. Special Considerations for 64-Bit Windows</h3></div></div></div><p>
+ PostgreSQL will only build for the x64 architecture on 64-bit Windows, there
+ is no support for Itanium processors.
+ </p><p>
+ Mixing 32- and 64-bit versions in the same build tree is not supported.
+ The build system will automatically detect if it's running in a 32- or
+ 64-bit environment, and build PostgreSQL accordingly. For this reason, it
+ is important to start the correct command prompt before building.
+ </p><p>
+ To use a server-side third party library such as <span class="productname">Python</span> or
+ <span class="productname">OpenSSL</span>, this library <span class="emphasis"><em>must</em></span> also be
+ 64-bit. There is no support for loading a 32-bit library in a 64-bit
+ server. Several of the third party libraries that PostgreSQL supports may
+ only be available in 32-bit versions, in which case they cannot be used with
+ 64-bit PostgreSQL.
+ </p></div><div class="sect2" id="id-1.6.5.8.10"><div class="titlepage"><div><div><h3 class="title">18.1.3. Building</h3></div></div></div><p>
+ To build all of PostgreSQL in release configuration (the default), run the
+ command:
+</p><pre class="screen">
+<strong class="userinput"><code>build</code></strong>
+</pre><p>
+ To build all of PostgreSQL in debug configuration, run the command:
+</p><pre class="screen">
+<strong class="userinput"><code>build DEBUG</code></strong>
+</pre><p>
+ To build just a single project, for example psql, run the commands:
+</p><pre class="screen">
+<strong class="userinput"><code>build psql</code></strong>
+<strong class="userinput"><code>build DEBUG psql</code></strong>
+</pre><p>
+ To change the default build configuration to debug, put the following
+ in the <code class="filename">buildenv.pl</code> file:
+</p><pre class="programlisting">
+$ENV{CONFIG}="Debug";
+</pre><p>
+ </p><p>
+ It is also possible to build from inside the Visual Studio GUI. In this
+ case, you need to run:
+</p><pre class="screen">
+<strong class="userinput"><code>perl mkvcbuild.pl</code></strong>
+</pre><p>
+ from the command prompt, and then open the generated
+ <code class="filename">pgsql.sln</code> (in the root directory of the source tree)
+ in Visual Studio.
+ </p></div><div class="sect2" id="id-1.6.5.8.11"><div class="titlepage"><div><div><h3 class="title">18.1.4. Cleaning and Installing</h3></div></div></div><p>
+ Most of the time, the automatic dependency tracking in Visual Studio will
+ handle changed files. But if there have been large changes, you may need
+ to clean the installation. To do this, simply run the
+ <code class="filename">clean.bat</code> command, which will automatically clean out
+ all generated files. You can also run it with the
+ <em class="parameter"><code>dist</code></em> parameter, in which case it will behave like
+ <strong class="userinput"><code>make distclean</code></strong> and remove the flex/bison output files
+ as well.
+ </p><p>
+ By default, all files are written into a subdirectory of the
+ <code class="filename">debug</code> or <code class="filename">release</code> directories. To
+ install these files using the standard layout, and also generate the files
+ required to initialize and use the database, run the command:
+</p><pre class="screen">
+<strong class="userinput"><code>install c:\destination\directory</code></strong>
+</pre><p>
+ </p><p>
+ If you want to install only the client applications and
+ interface libraries, then you can use these commands:
+</p><pre class="screen">
+<strong class="userinput"><code>install c:\destination\directory client</code></strong>
+</pre><p>
+ </p></div><div class="sect2" id="id-1.6.5.8.12"><div class="titlepage"><div><div><h3 class="title">18.1.5. Running the Regression Tests</h3></div></div></div><p>
+ To run the regression tests, make sure you have completed the build of all
+ required parts first. Also, make sure that the DLLs required to load all
+ parts of the system (such as the Perl and Python DLLs for the procedural
+ languages) are present in the system path. If they are not, set it through
+ the <code class="filename">buildenv.pl</code> file. To run the tests, run one of
+ the following commands from the <code class="filename">src\tools\msvc</code>
+ directory:
+</p><pre class="screen">
+<strong class="userinput"><code>vcregress check</code></strong>
+<strong class="userinput"><code>vcregress installcheck</code></strong>
+<strong class="userinput"><code>vcregress plcheck</code></strong>
+<strong class="userinput"><code>vcregress contribcheck</code></strong>
+<strong class="userinput"><code>vcregress modulescheck</code></strong>
+<strong class="userinput"><code>vcregress ecpgcheck</code></strong>
+<strong class="userinput"><code>vcregress isolationcheck</code></strong>
+<strong class="userinput"><code>vcregress bincheck</code></strong>
+<strong class="userinput"><code>vcregress recoverycheck</code></strong>
+<strong class="userinput"><code>vcregress taptest</code></strong>
+</pre><p>
+
+ To change the schedule used (default is parallel), append it to the
+ command line like:
+</p><pre class="screen">
+<strong class="userinput"><code>vcregress check serial</code></strong>
+</pre><p>
+
+ <code class="command">vcregress taptest</code> can be used to run the TAP tests
+ of a target directory, like:
+</p><pre class="screen">
+<strong class="userinput"><code>vcregress taptest src\bin\initdb\</code></strong>
+</pre><p>
+
+ For more information about the regression tests, see
+ <a class="xref" href="regress.html" title="Chapter 33. Regression Tests">Chapter 33</a>.
+ </p><p>
+ Running the regression tests on client programs with
+ <code class="command">vcregress bincheck</code>, on recovery tests with
+ <code class="command">vcregress recoverycheck</code>, or TAP tests specified with
+ <code class="command">vcregress taptest</code> requires an additional Perl module
+ to be installed:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="productname">IPC::Run</span></span></dt><dd><p>
+ As of this writing, <code class="literal">IPC::Run</code> is not included in the
+ ActiveState Perl installation, nor in the ActiveState Perl Package
+ Manager (PPM) library. To install, download the
+ <code class="filename">IPC-Run-&lt;version&gt;.tar.gz</code> source archive from CPAN,
+ at <a class="ulink" href="https://metacpan.org/release/IPC-Run" target="_top">https://metacpan.org/release/IPC-Run</a>, and
+ uncompress. Edit the <code class="filename">buildenv.pl</code> file, and add a PERL5LIB
+ variable to point to the <code class="filename">lib</code> subdirectory from the
+ extracted archive. For example:
+</p><pre class="programlisting">
+$ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib';
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ The TAP tests run with <code class="command">vcregress</code> support the
+ environment variables <code class="varname">PROVE_TESTS</code>, that is expanded
+ automatically using the name patterns given, and
+ <code class="varname">PROVE_FLAGS</code>. These can be set on a Windows terminal,
+ before running <code class="command">vcregress</code>:
+</p><pre class="programlisting">
+set PROVE_FLAGS=--timer --jobs 2
+set PROVE_TESTS=t/020*.pl t/010*.pl
+</pre><p>
+ It is also possible to set up those parameters in
+ <code class="filename">buildenv.pl</code>:
+</p><pre class="programlisting">
+$ENV{PROVE_FLAGS}='--timer --jobs 2'
+$ENV{PROVE_TESTS}='t/020*.pl t/010*.pl'
+</pre><p>
+ </p><p>
+ Some of the TAP tests depend on a set of external commands that would
+ optionally trigger tests related to them. Each one of those variables
+ can be set or unset in <code class="filename">buildenv.pl</code>:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">GZIP_PROGRAM</code></span></dt><dd><p>
+ Path to a <span class="application">gzip</span> command. The default is
+ <code class="literal">gzip</code>, which will search for a command by that
+ name in the configured <code class="envar">PATH</code>.
+ </p></dd><dt><span class="term"><code class="varname">LZ4</code></span></dt><dd><p>
+ Path to a <span class="application">lz4</span> command. The default is
+ <code class="literal">lz4</code>, which will search for a command by that
+ name in the configured <code class="envar">PATH</code>.
+ </p></dd><dt><span class="term"><code class="varname">TAR</code></span></dt><dd><p>
+ Path to a <span class="application">tar</span> command. The default is
+ <code class="literal">tar</code>, which will search for a command by that
+ name in the configured <code class="envar">PATH</code>.
+ </p></dd><dt><span class="term"><code class="varname">ZSTD</code></span></dt><dd><p>
+ Path to a <span class="application">zstd</span> command. The default is
+ <code class="literal">zstd</code>, which will search for a command by that
+ name in the configured <code class="envar">PATH</code>.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime.html" title="Chapter 19. Server Setup and Operation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 18. Installation from Source Code on <span class="productname">Windows</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 19. Server Setup and Operation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/install-windows.html b/doc/src/sgml/html/install-windows.html
new file mode 100644
index 0000000..0ac486d
--- /dev/null
+++ b/doc/src/sgml/html/install-windows.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 18. Installation from Source Code on Windows</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes" /><link rel="next" href="install-windows-full.html" title="18.1. Building with Visual C++ or the Microsoft Windows SDK" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 18. Installation from Source Code on <span class="productname">Windows</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-windows-full.html" title="18.1. Building with Visual C++ or the&#10; Microsoft Windows SDK">Next</a></td></tr></table><hr /></div><div class="chapter" id="INSTALL-WINDOWS"><div class="titlepage"><div><div><h2 class="title">Chapter 18. Installation from Source Code on <span class="productname">Windows</span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="install-windows-full.html">18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.8">18.1.1. Requirements</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.9">18.1.2. Special Considerations for 64-Bit Windows</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.10">18.1.3. Building</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.11">18.1.4. Cleaning and Installing</a></span></dt><dt><span class="sect2"><a href="install-windows-full.html#id-1.6.5.8.12">18.1.5. Running the Regression Tests</a></span></dt></dl></dd></dl></div><a id="id-1.6.5.2" class="indexterm"></a><p>
+ It is recommended that most users download the binary distribution for
+ Windows, available as a graphical installer package
+ from the <span class="productname">PostgreSQL</span> website at
+ <a class="ulink" href="https://www.postgresql.org/download/" target="_top">https://www.postgresql.org/download/</a>. Building from source
+ is only intended for people developing <span class="productname">PostgreSQL</span>
+ or extensions.
+ </p><p>
+ There are several different ways of building PostgreSQL on
+ <span class="productname">Windows</span>. The simplest way to build with
+ Microsoft tools is to install <span class="productname">Visual Studio 2022</span>
+ and use the included compiler. It is also possible to build with the full
+ <span class="productname">Microsoft Visual C++ 2013 to 2022</span>.
+ In some cases that requires the installation of the
+ <span class="productname">Windows SDK</span> in addition to the compiler.
+ </p><p>
+ It is also possible to build PostgreSQL using the GNU compiler tools
+ provided by <span class="productname">MinGW</span>, or using
+ <span class="productname">Cygwin</span> for older versions of
+ <span class="productname">Windows</span>.
+ </p><p>
+ Building using <span class="productname">MinGW</span> or
+ <span class="productname">Cygwin</span> uses the normal build system, see
+ <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a> and the specific notes in
+ <a class="xref" href="installation-platform-notes.html#INSTALLATION-NOTES-MINGW" title="17.7.4. MinGW/Native Windows">Section 17.7.4</a> and <a class="xref" href="installation-platform-notes.html#INSTALLATION-NOTES-CYGWIN" title="17.7.2. Cygwin">Section 17.7.2</a>.
+ To produce native 64 bit binaries in these environments, use the tools from
+ <span class="productname">MinGW-w64</span>. These tools can also be used to
+ cross-compile for 32 bit and 64 bit <span class="productname">Windows</span>
+ targets on other hosts, such as <span class="productname">Linux</span> and
+ <span class="productname">macOS</span>.
+ <span class="productname">Cygwin</span> is not recommended for running a
+ production server, and it should only be used for running on
+ older versions of <span class="productname">Windows</span> where
+ the native build does not work. The official
+ binaries are built using <span class="productname">Visual Studio</span>.
+ </p><p>
+ Native builds of <span class="application">psql</span> don't support command
+ line editing. The <span class="productname">Cygwin</span> build does support
+ command line editing, so it should be used where psql is needed for
+ interactive use on <span class="productname">Windows</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-windows-full.html" title="18.1. Building with Visual C++ or the&#10; Microsoft Windows SDK">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.7. Platform-Specific Notes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/installation-platform-notes.html b/doc/src/sgml/html/installation-platform-notes.html
new file mode 100644
index 0000000..cac1c72
--- /dev/null
+++ b/doc/src/sgml/html/installation-platform-notes.html
@@ -0,0 +1,314 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.7. Platform-Specific Notes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="supported-platforms.html" title="17.6. Supported Platforms" /><link rel="next" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.7. Platform-Specific Notes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="supported-platforms.html" title="17.6. Supported Platforms">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Next</a></td></tr></table><hr /></div><div class="sect1" id="INSTALLATION-PLATFORM-NOTES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.7. Platform-Specific Notes</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-AIX">17.7.1. AIX</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-CYGWIN">17.7.2. Cygwin</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-MACOS">17.7.3. macOS</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-MINGW">17.7.4. MinGW/Native Windows</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-SOLARIS">17.7.5. Solaris</a></span></dt></dl></div><p>
+ This section documents additional platform-specific issues
+ regarding the installation and setup of PostgreSQL. Be sure to
+ read the installation instructions, and in
+ particular <a class="xref" href="install-requirements.html" title="17.2. Requirements">Section 17.2</a> as well. Also,
+ check <a class="xref" href="regress.html" title="Chapter 33. Regression Tests">Chapter 33</a> regarding the
+ interpretation of regression test results.
+ </p><p>
+ Platforms that are not covered here have no known platform-specific
+ installation issues.
+ </p><div class="sect2" id="INSTALLATION-NOTES-AIX"><div class="titlepage"><div><div><h3 class="title">17.7.1. AIX</h3></div></div></div><a id="id-1.6.4.11.4.2" class="indexterm"></a><p>
+ You can use GCC or the native IBM compiler <code class="command">xlc</code>
+ to build <span class="productname">PostgreSQL</span>
+ on <span class="productname">AIX</span>.
+ </p><p>
+ <span class="productname">AIX</span> versions before 7.1 are no longer
+ tested nor supported by the <span class="productname">PostgreSQL</span>
+ community.
+ </p><div class="sect3" id="id-1.6.4.11.4.5"><div class="titlepage"><div><div><h4 class="title">17.7.1.1. Memory Management</h4></div></div></div><p>
+ AIX can be somewhat peculiar with regards to the way it does
+ memory management. You can have a server with many multiples of
+ gigabytes of RAM free, but still get out of memory or address
+ space errors when running applications. One example
+ is loading of extensions failing with unusual errors.
+ For example, running as the owner of the PostgreSQL installation:
+</p><pre class="screen">
+=# CREATE EXTENSION plperl;
+ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": A memory address is not in the address space for the process.
+</pre><p>
+ Running as a non-owner in the group possessing the PostgreSQL
+ installation:
+</p><pre class="screen">
+=# CREATE EXTENSION plperl;
+ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address
+</pre><p>
+ Another example is out of memory errors in the PostgreSQL server
+ logs, with every memory allocation near or greater than 256 MB
+ failing.
+ </p><p>
+ The overall cause of all these problems is the default bittedness
+ and memory model used by the server process. By default, all
+ binaries built on AIX are 32-bit. This does not depend upon
+ hardware type or kernel in use. These 32-bit processes are
+ limited to 4 GB of memory laid out in 256 MB segments using one
+ of a few models. The default allows for less than 256 MB in the
+ heap as it shares a single segment with the stack.
+ </p><p>
+ In the case of the <code class="literal">plperl</code> example, above,
+ check your umask and the permissions of the binaries in your
+ PostgreSQL installation. The binaries involved in that example
+ were 32-bit and installed as mode 750 instead of 755. Due to the
+ permissions being set in this fashion, only the owner or a member
+ of the possessing group can load the library. Since it isn't
+ world-readable, the loader places the object into the process'
+ heap instead of the shared library segments where it would
+ otherwise be placed.
+ </p><p>
+ The <span class="quote">“<span class="quote">ideal</span>”</span> solution for this is to use a 64-bit
+ build of PostgreSQL, but that is not always practical, because
+ systems with 32-bit processors can build, but not run, 64-bit
+ binaries.
+ </p><p>
+ If a 32-bit binary is desired, set <code class="symbol">LDR_CNTRL</code> to
+ <code class="literal">MAXDATA=0x<em class="replaceable"><code>n</code></em>0000000</code>,
+ where 1 &lt;= n &lt;= 8, before starting the PostgreSQL server,
+ and try different values and <code class="filename">postgresql.conf</code>
+ settings to find a configuration that works satisfactorily. This
+ use of <code class="symbol">LDR_CNTRL</code> tells AIX that you want the
+ server to have <code class="symbol">MAXDATA</code> bytes set aside for the
+ heap, allocated in 256 MB segments. When you find a workable
+ configuration,
+ <code class="command">ldedit</code> can be used to modify the binaries so
+ that they default to using the desired heap size. PostgreSQL can
+ also be rebuilt, passing <code class="literal">configure
+ LDFLAGS="-Wl,-bmaxdata:0x<em class="replaceable"><code>n</code></em>0000000"</code>
+ to achieve the same effect.
+ </p><p>
+ For a 64-bit build, set <code class="envar">OBJECT_MODE</code> to 64 and
+ pass <code class="literal">CC="gcc -maix64"</code>
+ and <code class="literal">LDFLAGS="-Wl,-bbigtoc"</code>
+ to <code class="command">configure</code>. (Options for
+ <code class="command">xlc</code> might differ.) If you omit the export of
+ <code class="envar">OBJECT_MODE</code>, your build may fail with linker errors. When
+ <code class="envar">OBJECT_MODE</code> is set, it tells AIX's build utilities
+ such as <code class="command">ar</code>, <code class="command">as</code>, and <code class="command">ld</code> what
+ type of objects to default to handling.
+ </p><p>
+ By default, overcommit of paging space can happen. While we have
+ not seen this occur, AIX will kill processes when it runs out of
+ memory and the overcommit is accessed. The closest to this that
+ we have seen is fork failing because the system decided that
+ there was not enough memory for another process. Like many other
+ parts of AIX, the paging space allocation method and
+ out-of-memory kill is configurable on a system- or process-wide
+ basis if this becomes a problem.
+ </p></div></div><div class="sect2" id="INSTALLATION-NOTES-CYGWIN"><div class="titlepage"><div><div><h3 class="title">17.7.2. Cygwin</h3></div></div></div><a id="id-1.6.4.11.5.2" class="indexterm"></a><p>
+ PostgreSQL can be built using Cygwin, a Linux-like environment for
+ Windows, but that method is inferior to the native Windows build
+ <span class="phrase">(see <a class="xref" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Chapter 18</a>)</span> and
+ running a server under Cygwin is no longer recommended.
+ </p><p>
+ When building from source, proceed according to the Unix-style
+ installation procedure (i.e., <code class="literal">./configure;
+ make</code>; etc.), noting the following Cygwin-specific
+ differences:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Set your path to use the Cygwin bin directory before the
+ Windows utilities. This will help prevent problems with
+ compilation.
+ </p></li><li class="listitem"><p>
+ The <code class="command">adduser</code> command is not supported; use
+ the appropriate user management application on Windows NT,
+ 2000, or XP. Otherwise, skip this step.
+ </p></li><li class="listitem"><p>
+ The <code class="command">su</code> command is not supported; use ssh to
+ simulate su on Windows NT, 2000, or XP. Otherwise, skip this
+ step.
+ </p></li><li class="listitem"><p>
+ <span class="productname">OpenSSL</span> is not supported.
+ </p></li><li class="listitem"><p>
+ Start <code class="command">cygserver</code> for shared memory support.
+ To do this, enter the command <code class="literal">/usr/sbin/cygserver
+ &amp;</code>. This program needs to be running anytime you
+ start the PostgreSQL server or initialize a database cluster
+ (<code class="command">initdb</code>). The
+ default <code class="command">cygserver</code> configuration may need to
+ be changed (e.g., increase <code class="symbol">SEMMNS</code>) to prevent
+ PostgreSQL from failing due to a lack of system resources.
+ </p></li><li class="listitem"><p>
+ Building might fail on some systems where a locale other than
+ C is in use. To fix this, set the locale to C by doing
+ <code class="command">export LANG=C.utf8</code> before building, and then
+ setting it back to the previous setting after you have installed
+ PostgreSQL.
+ </p></li><li class="listitem"><p>
+ The parallel regression tests (<code class="literal">make check</code>)
+ can generate spurious regression test failures due to
+ overflowing the <code class="function">listen()</code> backlog queue
+ which causes connection refused errors or hangs. You can limit
+ the number of connections using the make
+ variable <code class="varname">MAX_CONNECTIONS</code> thus:
+</p><pre class="programlisting">
+make MAX_CONNECTIONS=5 check
+</pre><p>
+ (On some systems you can have up to about 10 simultaneous
+ connections.)
+ </p></li></ul></div><p>
+ </p><p>
+ It is possible to install <code class="command">cygserver</code> and the
+ PostgreSQL server as Windows NT services. For information on how
+ to do this, please refer to the <code class="filename">README</code>
+ document included with the PostgreSQL binary package on Cygwin.
+ It is installed in the
+ directory <code class="filename">/usr/share/doc/Cygwin</code>.
+ </p></div><div class="sect2" id="INSTALLATION-NOTES-MACOS"><div class="titlepage"><div><div><h3 class="title">17.7.3. macOS</h3></div></div></div><a id="id-1.6.4.11.6.2" class="indexterm"></a><p>
+ To build <span class="productname">PostgreSQL</span> from source
+ on <span class="productname">macOS</span>, you will need to install Apple's
+ command line developer tools, which can be done by issuing
+</p><pre class="programlisting">
+xcode-select --install
+</pre><p>
+ (note that this will pop up a GUI dialog window for confirmation).
+ You may or may not wish to also install Xcode.
+ </p><p>
+ On recent <span class="productname">macOS</span> releases, it's necessary to
+ embed the <span class="quote">“<span class="quote">sysroot</span>”</span> path in the include switches used to
+ find some system header files. This results in the outputs of
+ the <span class="application">configure</span> script varying depending on
+ which SDK version was used during <span class="application">configure</span>.
+ That shouldn't pose any problem in simple scenarios, but if you are
+ trying to do something like building an extension on a different machine
+ than the server code was built on, you may need to force use of a
+ different sysroot path. To do that, set <code class="varname">PG_SYSROOT</code>,
+ for example
+</p><pre class="programlisting">
+make PG_SYSROOT=<em class="replaceable"><code>/desired/path</code></em> all
+</pre><p>
+ To find out the appropriate path on your machine, run
+</p><pre class="programlisting">
+xcrun --show-sdk-path
+</pre><p>
+ Note that building an extension using a different sysroot version than
+ was used to build the core server is not really recommended; in the
+ worst case it could result in hard-to-debug ABI inconsistencies.
+ </p><p>
+ You can also select a non-default sysroot path when configuring, by
+ specifying <code class="varname">PG_SYSROOT</code>
+ to <span class="application">configure</span>:
+</p><pre class="programlisting">
+./configure ... PG_SYSROOT=<em class="replaceable"><code>/desired/path</code></em>
+</pre><p>
+ This would primarily be useful to cross-compile for some other
+ macOS version. There is no guarantee that the resulting executables
+ will run on the current host.
+ </p><p>
+ To suppress the <code class="option">-isysroot</code> options altogether, use
+</p><pre class="programlisting">
+./configure ... PG_SYSROOT=none
+</pre><p>
+ (any nonexistent pathname will work). This might be useful if you wish
+ to build with a non-Apple compiler, but beware that that case is not
+ tested or supported by the PostgreSQL developers.
+ </p><p>
+ <span class="productname">macOS</span>'s <span class="quote">“<span class="quote">System Integrity
+ Protection</span>”</span> (SIP) feature breaks <code class="literal">make check</code>,
+ because it prevents passing the needed setting
+ of <code class="literal">DYLD_LIBRARY_PATH</code> down to the executables being
+ tested. You can work around that by doing <code class="literal">make
+ install</code> before <code class="literal">make check</code>.
+ Most PostgreSQL developers just turn off SIP, though.
+ </p></div><div class="sect2" id="INSTALLATION-NOTES-MINGW"><div class="titlepage"><div><div><h3 class="title">17.7.4. MinGW/Native Windows</h3></div></div></div><a id="id-1.6.4.11.7.2" class="indexterm"></a><p>
+ PostgreSQL for Windows can be built using MinGW, a Unix-like build
+ environment for Microsoft operating systems, or using
+ Microsoft's <span class="productname">Visual C++</span> compiler suite.
+ The MinGW build procedure uses the normal build system described in
+ this chapter; the Visual C++ build works completely differently
+ and is described in <a class="xref" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Chapter 18</a>.
+ </p><p>
+ The native Windows port requires a 32 or 64-bit version of Windows
+ 2000 or later. Earlier operating systems do
+ not have sufficient infrastructure (but Cygwin may be used on
+ those). MinGW, the Unix-like build tools, and MSYS, a collection
+ of Unix tools required to run shell scripts
+ like <code class="command">configure</code>, can be downloaded
+ from <a class="ulink" href="http://www.mingw.org/" target="_top">http://www.mingw.org/</a>. Neither is
+ required to run the resulting binaries; they are needed only for
+ creating the binaries.
+ </p><p>
+ To build 64 bit binaries using MinGW, install the 64 bit tool set
+ from <a class="ulink" href="https://mingw-w64.org/" target="_top">https://mingw-w64.org/</a>, put its bin
+ directory in the <code class="envar">PATH</code>, and run
+ <code class="command">configure</code> with the
+ <code class="command">--host=x86_64-w64-mingw32</code> option.
+ </p><p>
+ After you have everything installed, it is suggested that you
+ run <span class="application">psql</span>
+ under <code class="command">CMD.EXE</code>, as the MSYS console has
+ buffering issues.
+ </p><div class="sect3" id="WINDOWS-CRASH-DUMPS"><div class="titlepage"><div><div><h4 class="title">17.7.4.1. Collecting Crash Dumps on Windows</h4></div></div></div><p>
+ If PostgreSQL on Windows crashes, it has the ability to generate
+ <span class="productname">minidumps</span> that can be used to track down the cause
+ for the crash, similar to core dumps on Unix. These dumps can be
+ read using the <span class="productname">Windows Debugger Tools</span> or using
+ <span class="productname">Visual Studio</span>. To enable the generation of dumps
+ on Windows, create a subdirectory named <code class="filename">crashdumps</code>
+ inside the cluster data directory. The dumps will then be written
+ into this directory with a unique name based on the identifier of
+ the crashing process and the current time of the crash.
+ </p></div></div><div class="sect2" id="INSTALLATION-NOTES-SOLARIS"><div class="titlepage"><div><div><h3 class="title">17.7.5. Solaris</h3></div></div></div><a id="id-1.6.4.11.8.2" class="indexterm"></a><p>
+ PostgreSQL is well-supported on Solaris. The more up to date your
+ operating system, the fewer issues you will experience.
+ </p><div class="sect3" id="id-1.6.4.11.8.4"><div class="titlepage"><div><div><h4 class="title">17.7.5.1. Required Tools</h4></div></div></div><p>
+ You can build with either GCC or Sun's compiler suite. For
+ better code optimization, Sun's compiler is strongly recommended
+ on the SPARC architecture. If
+ you are using Sun's compiler, be careful not to select
+ <code class="filename">/usr/ucb/cc</code>;
+ use <code class="filename">/opt/SUNWspro/bin/cc</code>.
+ </p><p>
+ You can download Sun Studio
+ from <a class="ulink" href="https://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/" target="_top">https://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/</a>.
+ Many GNU tools are integrated into Solaris 10, or they are
+ present on the Solaris companion CD. If you need packages for
+ older versions of Solaris, you can find these tools
+ at <a class="ulink" href="http://www.sunfreeware.com" target="_top">http://www.sunfreeware.com</a>.
+ If you prefer
+ sources, look
+ at <a class="ulink" href="https://www.gnu.org/prep/ftp" target="_top">https://www.gnu.org/prep/ftp</a>.
+ </p></div><div class="sect3" id="id-1.6.4.11.8.5"><div class="titlepage"><div><div><h4 class="title">17.7.5.2. configure Complains About a Failed Test Program</h4></div></div></div><p>
+ If <code class="command">configure</code> complains about a failed test
+ program, this is probably a case of the run-time linker being
+ unable to find some library, probably libz, libreadline or some
+ other non-standard library such as libssl. To point it to the
+ right location, set the <code class="envar">LDFLAGS</code> environment
+ variable on the <code class="command">configure</code> command line, e.g.,
+</p><pre class="programlisting">
+configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
+</pre><p>
+ See
+ the <span class="citerefentry"><span class="refentrytitle">ld</span></span>
+ man page for more information.
+ </p></div><div class="sect3" id="id-1.6.4.11.8.6"><div class="titlepage"><div><div><h4 class="title">17.7.5.3. Compiling for Optimal Performance</h4></div></div></div><p>
+ On the SPARC architecture, Sun Studio is strongly recommended for
+ compilation. Try using the <code class="option">-xO5</code> optimization
+ flag to generate significantly faster binaries. Do not use any
+ flags that modify behavior of floating-point operations
+ and <code class="varname">errno</code> processing (e.g.,
+ <code class="option">-fast</code>).
+ </p><p>
+ If you do not have a reason to use 64-bit binaries on SPARC,
+ prefer the 32-bit version. The 64-bit operations are slower and
+ 64-bit binaries are slower than the 32-bit variants. On the
+ other hand, 32-bit code on the AMD64 CPU family is not native,
+ so 32-bit code is significantly slower on that CPU family.
+ </p></div><div class="sect3" id="id-1.6.4.11.8.7"><div class="titlepage"><div><div><h4 class="title">17.7.5.4. Using DTrace for Tracing PostgreSQL</h4></div></div></div><p>
+ Yes, using DTrace is possible. See <a class="xref" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Section 28.5</a> for
+ further information.
+ </p><p>
+ If you see the linking of the <code class="command">postgres</code> executable abort with an
+ error message like:
+</p><pre class="screen">
+Undefined first referenced
+ symbol in file
+AbortTransaction utils/probes.o
+CommitTransaction utils/probes.o
+ld: fatal: Symbol referencing errors. No output written to postgres
+collect2: ld returned 1 exit status
+make: *** [postgres] Error 1
+</pre><p>
+ your DTrace installation is too old to handle probes in static
+ functions. You need Solaris 10u4 or newer to use DTrace.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="supported-platforms.html" title="17.6. Supported Platforms">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.6. Supported Platforms </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 18. Installation from Source Code on <span class="productname">Windows</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/installation.html b/doc/src/sgml/html/installation.html
new file mode 100644
index 0000000..6123b02
--- /dev/null
+++ b/doc/src/sgml/html/installation.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 17. Installation from Source Code</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-binaries.html" title="Chapter 16. Installation from Binaries" /><link rel="next" href="install-short.html" title="17.1. Short Version" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 17. Installation from Source Code</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-binaries.html" title="Chapter 16. Installation from Binaries">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="install-short.html" title="17.1. Short Version">Next</a></td></tr></table><hr /></div><div class="chapter" id="INSTALLATION"><div class="titlepage"><div><div><h2 class="title">Chapter 17. Installation from Source Code</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="install-short.html">17.1. Short Version</a></span></dt><dt><span class="sect1"><a href="install-requirements.html">17.2. Requirements</a></span></dt><dt><span class="sect1"><a href="install-getsource.html">17.3. Getting the Source</a></span></dt><dt><span class="sect1"><a href="install-procedure.html">17.4. Installation Procedure</a></span></dt><dd><dl><dt><span class="sect2"><a href="install-procedure.html#CONFIGURE-OPTIONS">17.4.1. <code class="filename">configure</code> Options</a></span></dt><dt><span class="sect2"><a href="install-procedure.html#CONFIGURE-ENVVARS">17.4.2. <code class="filename">configure</code> Environment Variables</a></span></dt></dl></dd><dt><span class="sect1"><a href="install-post.html">17.5. Post-Installation Setup</a></span></dt><dd><dl><dt><span class="sect2"><a href="install-post.html#INSTALL-POST-SHLIBS">17.5.1. Shared Libraries</a></span></dt><dt><span class="sect2"><a href="install-post.html#id-1.6.4.9.3">17.5.2. Environment Variables</a></span></dt></dl></dd><dt><span class="sect1"><a href="supported-platforms.html">17.6. Supported Platforms</a></span></dt><dt><span class="sect1"><a href="installation-platform-notes.html">17.7. Platform-Specific Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-AIX">17.7.1. AIX</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-CYGWIN">17.7.2. Cygwin</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-MACOS">17.7.3. macOS</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-MINGW">17.7.4. MinGW/Native Windows</a></span></dt><dt><span class="sect2"><a href="installation-platform-notes.html#INSTALLATION-NOTES-SOLARIS">17.7.5. Solaris</a></span></dt></dl></dd></dl></div><a id="id-1.6.4.2" class="indexterm"></a><p>
+ This chapter describes the installation of
+ <span class="productname">PostgreSQL</span> using the source code
+ distribution. If you are installing a pre-packaged distribution,
+ such as an RPM or Debian package, ignore this chapter
+ and see <a class="xref" href="install-binaries.html" title="Chapter 16. Installation from Binaries">Chapter 16</a> instead.
+ </p><p>
+ If you are building <span class="productname">PostgreSQL</span> for Microsoft
+ Windows, read this chapter if you intend to build with MinGW or Cygwin;
+ but if you intend to build with Microsoft's <span class="productname">Visual
+ C++</span>, see <a class="xref" href="install-windows.html" title="Chapter 18. Installation from Source Code on Windows">Chapter 18</a> instead.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-binaries.html" title="Chapter 16. Installation from Binaries">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="install-short.html" title="17.1. Short Version">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16. Installation from Binaries </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.1. Short Version</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/intagg.html b/doc/src/sgml/html/intagg.html
new file mode 100644
index 0000000..0b1735b
--- /dev/null
+++ b/doc/src/sgml/html/intagg.html
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.19. intagg</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="hstore.html" title="F.18. hstore" /><link rel="next" href="intarray.html" title="F.20. intarray" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.19. intagg</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="hstore.html" title="F.18. hstore">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="intarray.html" title="F.20. intarray">Next</a></td></tr></table><hr /></div><div class="sect1" id="INTAGG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.19. intagg</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="intagg.html#id-1.11.7.28.4">F.19.1. Functions</a></span></dt><dt><span class="sect2"><a href="intagg.html#id-1.11.7.28.5">F.19.2. Sample Uses</a></span></dt></dl></div><a id="id-1.11.7.28.2" class="indexterm"></a><p>
+ The <code class="filename">intagg</code> module provides an integer aggregator and an
+ enumerator. <code class="filename">intagg</code> is now obsolete, because there
+ are built-in functions that provide a superset of its capabilities.
+ However, the module is still provided as a compatibility wrapper around
+ the built-in functions.
+ </p><div class="sect2" id="id-1.11.7.28.4"><div class="titlepage"><div><div><h3 class="title">F.19.1. Functions</h3></div></div></div><a id="id-1.11.7.28.4.2" class="indexterm"></a><a id="id-1.11.7.28.4.3" class="indexterm"></a><p>
+ The aggregator is an aggregate function
+ <code class="function">int_array_aggregate(integer)</code>
+ that produces an integer array
+ containing exactly the integers it is fed.
+ This is a wrapper around <code class="function">array_agg</code>,
+ which does the same thing for any array type.
+ </p><a id="id-1.11.7.28.4.5" class="indexterm"></a><p>
+ The enumerator is a function
+ <code class="function">int_array_enum(integer[])</code>
+ that returns <code class="type">setof integer</code>. It is essentially the reverse
+ operation of the aggregator: given an array of integers, expand it
+ into a set of rows. This is a wrapper around <code class="function">unnest</code>,
+ which does the same thing for any array type.
+ </p></div><div class="sect2" id="id-1.11.7.28.5"><div class="titlepage"><div><div><h3 class="title">F.19.2. Sample Uses</h3></div></div></div><p>
+ Many database systems have the notion of a one to many table. Such a table
+ usually sits between two indexed tables, for example:
+
+</p><pre class="programlisting">
+CREATE TABLE left (id INT PRIMARY KEY, ...);
+CREATE TABLE right (id INT PRIMARY KEY, ...);
+CREATE TABLE one_to_many(left INT REFERENCES left, right INT REFERENCES right);
+</pre><p>
+
+ It is typically used like this:
+
+</p><pre class="programlisting">
+SELECT right.* from right JOIN one_to_many ON (right.id = one_to_many.right)
+ WHERE one_to_many.left = <em class="replaceable"><code>item</code></em>;
+</pre><p>
+
+ This will return all the items in the right hand table for an entry
+ in the left hand table. This is a very common construct in SQL.
+ </p><p>
+ Now, this methodology can be cumbersome with a very large number of
+ entries in the <code class="structname">one_to_many</code> table. Often,
+ a join like this would result in an index scan
+ and a fetch for each right hand entry in the table for a particular
+ left hand entry. If you have a very dynamic system, there is not much you
+ can do. However, if you have some data which is fairly static, you can
+ create a summary table with the aggregator.
+
+</p><pre class="programlisting">
+CREATE TABLE summary AS
+ SELECT left, int_array_aggregate(right) AS right
+ FROM one_to_many
+ GROUP BY left;
+</pre><p>
+
+ This will create a table with one row per left item, and an array
+ of right items. Now this is pretty useless without some way of using
+ the array; that's why there is an array enumerator. You can do
+
+</p><pre class="programlisting">
+SELECT left, int_array_enum(right) FROM summary WHERE left = <em class="replaceable"><code>item</code></em>;
+</pre><p>
+
+ The above query using <code class="function">int_array_enum</code> produces the same results
+ as
+
+</p><pre class="programlisting">
+SELECT left, right FROM one_to_many WHERE left = <em class="replaceable"><code>item</code></em>;
+</pre><p>
+
+ The difference is that the query against the summary table has to get
+ only one row from the table, whereas the direct query against
+ <code class="structname">one_to_many</code> must index scan and fetch a row for each entry.
+ </p><p>
+ On one system, an <code class="command">EXPLAIN</code> showed a query with a cost of 8488 was
+ reduced to a cost of 329. The original query was a join involving the
+ <code class="structname">one_to_many</code> table, which was replaced by:
+
+</p><pre class="programlisting">
+SELECT right, count(right) FROM
+ ( SELECT left, int_array_enum(right) AS right
+ FROM summary JOIN (SELECT left FROM left_table WHERE left = <em class="replaceable"><code>item</code></em>) AS lefts
+ ON (summary.left = lefts.left)
+ ) AS list
+ GROUP BY right
+ ORDER BY count DESC;
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="hstore.html" title="F.18. hstore">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="intarray.html" title="F.20. intarray">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.18. hstore </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.20. intarray</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/intarray.html b/doc/src/sgml/html/intarray.html
new file mode 100644
index 0000000..bbc4e1c
--- /dev/null
+++ b/doc/src/sgml/html/intarray.html
@@ -0,0 +1,321 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.20. intarray</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="intagg.html" title="F.19. intagg" /><link rel="next" href="isn.html" title="F.21. isn" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.20. intarray</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="intagg.html" title="F.19. intagg">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="isn.html" title="F.21. isn">Next</a></td></tr></table><hr /></div><div class="sect1" id="INTARRAY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.20. intarray</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.7">F.20.1. <code class="filename">intarray</code> Functions and Operators</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.8">F.20.2. Index Support</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.9">F.20.3. Example</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.10">F.20.4. Benchmark</a></span></dt><dt><span class="sect2"><a href="intarray.html#id-1.11.7.29.11">F.20.5. Authors</a></span></dt></dl></div><a id="id-1.11.7.29.2" class="indexterm"></a><p>
+ The <code class="filename">intarray</code> module provides a number of useful functions
+ and operators for manipulating null-free arrays of integers.
+ There is also support for indexed searches using some of the operators.
+ </p><p>
+ All of these operations will throw an error if a supplied array contains any
+ NULL elements.
+ </p><p>
+ Many of these operations are only sensible for one-dimensional arrays.
+ Although they will accept input arrays of more dimensions, the data is
+ treated as though it were a linear array in storage order.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.29.7"><div class="titlepage"><div><div><h3 class="title">F.20.1. <code class="filename">intarray</code> Functions and Operators</h3></div></div></div><p>
+ The functions provided by the <code class="filename">intarray</code> module
+ are shown in <a class="xref" href="intarray.html#INTARRAY-FUNC-TABLE" title="Table F.9. intarray Functions">Table F.9</a>, the operators
+ in <a class="xref" href="intarray.html#INTARRAY-OP-TABLE" title="Table F.10. intarray Operators">Table F.10</a>.
+ </p><div class="table" id="INTARRAY-FUNC-TABLE"><p class="title"><strong>Table F.9. <code class="filename">intarray</code> Functions</strong></p><div class="table-contents"><table class="table" summary="intarray Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">icount</code> ( <code class="type">integer[]</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of elements in the array.
+ </p>
+ <p>
+ <code class="literal">icount('{1,2,3}'::integer[])</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">sort</code> ( <code class="type">integer[]</code>, <em class="parameter"><code>dir</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Sorts the array in either ascending or descending order.
+ <em class="parameter"><code>dir</code></em> must be <code class="literal">asc</code>
+ or <code class="literal">desc</code>.
+ </p>
+ <p>
+ <code class="literal">sort('{1,3,2}'::integer[], 'desc')</code>
+ → <code class="returnvalue">{3,2,1}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sort</code> ( <code class="type">integer[]</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.3.1.2.1" class="indexterm"></a>
+ <code class="function">sort_asc</code> ( <code class="type">integer[]</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Sorts in ascending order.
+ </p>
+ <p>
+ <code class="literal">sort(array[11,77,44])</code>
+ → <code class="returnvalue">{11,44,77}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">sort_desc</code> ( <code class="type">integer[]</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Sorts in descending order.
+ </p>
+ <p>
+ <code class="literal">sort_desc(array[11,77,44])</code>
+ → <code class="returnvalue">{77,44,11}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">uniq</code> ( <code class="type">integer[]</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Removes adjacent duplicates.
+ Often used with <code class="function">sort</code> to remove all duplicates.
+ </p>
+ <p>
+ <code class="literal">uniq('{1,2,2,3,1,1}'::integer[])</code>
+ → <code class="returnvalue">{1,2,3,1}</code>
+ </p>
+ <p>
+ <code class="literal">uniq(sort('{1,2,3,2,1}'::integer[]))</code>
+ → <code class="returnvalue">{1,2,3}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">idx</code> ( <code class="type">integer[]</code>, <em class="parameter"><code>item</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns index of the first array element
+ matching <em class="parameter"><code>item</code></em>, or 0 if no match.
+ </p>
+ <p>
+ <code class="literal">idx(array[11,22,33,22,11], 22)</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">subarray</code> ( <code class="type">integer[]</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code>, <em class="parameter"><code>len</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Extracts the portion of the array starting at
+ position <em class="parameter"><code>start</code></em>, with <em class="parameter"><code>len</code></em>
+ elements.
+ </p>
+ <p>
+ <code class="literal">subarray('{1,2,3,2,1}'::integer[], 2, 3)</code>
+ → <code class="returnvalue">{2,3,2}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">subarray</code> ( <code class="type">integer[]</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Extracts the portion of the array starting at
+ position <em class="parameter"><code>start</code></em>.
+ </p>
+ <p>
+ <code class="literal">subarray('{1,2,3,2,1}'::integer[], 2)</code>
+ → <code class="returnvalue">{2,3,2,1}</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.29.7.3.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">intset</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Makes a single-element array.
+ </p>
+ <p>
+ <code class="literal">intset(42)</code>
+ → <code class="returnvalue">{42}</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="INTARRAY-OP-TABLE"><p class="title"><strong>Table F.10. <code class="filename">intarray</code> Operators</strong></p><div class="table-contents"><table class="table" summary="intarray Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">&amp;&amp;</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do arrays overlap (have at least one element in common)?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">@&gt;</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does left array contain right array?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">&lt;@</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is left array contained in right array?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type"></code> <code class="literal">#</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the number of elements in the array.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">#</code> <code class="type">integer</code>
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns index of the first array element
+ matching the right argument, or 0 if no match.
+ (Same as <code class="function">idx</code> function.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">+</code> <code class="type">integer</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Adds element to end of array.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">+</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Concatenates the arrays.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">-</code> <code class="type">integer</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Removes entries matching the right argument from the array.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">-</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Removes elements of the right array from the left array.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">|</code> <code class="type">integer</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Computes the union of the arguments.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">|</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Computes the union of the arguments.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">&amp;</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">integer[]</code>
+ </p>
+ <p>
+ Computes the intersection of the arguments.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">integer[]</code> <code class="literal">@@</code> <code class="type">query_int</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array satisfy query? (see below)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">query_int</code> <code class="literal">~~</code> <code class="type">integer[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array satisfy query? (commutator of <code class="literal">@@</code>)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The operators <code class="literal">&amp;&amp;</code>, <code class="literal">@&gt;</code> and
+ <code class="literal">&lt;@</code> are equivalent to <span class="productname">PostgreSQL</span>'s built-in
+ operators of the same names, except that they work only on integer arrays
+ that do not contain nulls, while the built-in operators work for any array
+ type. This restriction makes them faster than the built-in operators
+ in many cases.
+ </p><p>
+ The <code class="literal">@@</code> and <code class="literal">~~</code> operators test whether an array
+ satisfies a <em class="firstterm">query</em>, which is expressed as a value of a
+ specialized data type <code class="type">query_int</code>. A <em class="firstterm">query</em>
+ consists of integer values that are checked against the elements of
+ the array, possibly combined using the operators <code class="literal">&amp;</code>
+ (AND), <code class="literal">|</code> (OR), and <code class="literal">!</code> (NOT). Parentheses
+ can be used as needed. For example,
+ the query <code class="literal">1&amp;(2|3)</code> matches arrays that contain 1
+ and also contain either 2 or 3.
+ </p></div><div class="sect2" id="id-1.11.7.29.8"><div class="titlepage"><div><div><h3 class="title">F.20.2. Index Support</h3></div></div></div><p>
+ <code class="filename">intarray</code> provides index support for the
+ <code class="literal">&amp;&amp;</code>, <code class="literal">@&gt;</code>,
+ and <code class="literal">@@</code> operators, as well as regular array equality.
+ </p><p>
+ Two parameterized GiST index operator classes are provided:
+ <code class="literal">gist__int_ops</code> (used by default) is suitable for
+ small- to medium-size data sets, while
+ <code class="literal">gist__intbig_ops</code> uses a larger signature and is more
+ suitable for indexing large data sets (i.e., columns containing
+ a large number of distinct array values).
+ The implementation uses an RD-tree data structure with
+ built-in lossy compression.
+ </p><p>
+ <code class="literal">gist__int_ops</code> approximates an integer set as an array of
+ integer ranges. Its optional integer parameter <code class="literal">numranges</code>
+ determines the maximum number of ranges in
+ one index key. The default value of <code class="literal">numranges</code> is 100.
+ Valid values are between 1 and 253. Using larger arrays as GiST index
+ keys leads to a more precise search (scanning a smaller fraction of the index and
+ fewer heap pages), at the cost of a larger index.
+ </p><p>
+ <code class="literal">gist__intbig_ops</code> approximates an integer set as a bitmap
+ signature. Its optional integer parameter <code class="literal">siglen</code>
+ determines the signature length in bytes.
+ The default signature length is 16 bytes. Valid values of signature length
+ are between 1 and 2024 bytes. Longer signatures lead to a more precise
+ search (scanning a smaller fraction of the index and fewer heap pages), at
+ the cost of a larger index.
+ </p><p>
+ There is also a non-default GIN operator class
+ <code class="literal">gin__int_ops</code>, which supports these operators as well
+ as <code class="literal">&lt;@</code>.
+ </p><p>
+ The choice between GiST and GIN indexing depends on the relative
+ performance characteristics of GiST and GIN, which are discussed elsewhere.
+ </p></div><div class="sect2" id="id-1.11.7.29.9"><div class="titlepage"><div><div><h3 class="title">F.20.3. Example</h3></div></div></div><pre class="programlisting">
+-- a message can be in one or more <span class="quote">“<span class="quote">sections</span>”</span>
+CREATE TABLE message (mid INT PRIMARY KEY, sections INT[], ...);
+
+-- create specialized index with signature length of 32 bytes
+CREATE INDEX message_rdtree_idx ON message USING GIST (sections gist__intbig_ops (siglen = 32));
+
+-- select messages in section 1 OR 2 - OVERLAP operator
+SELECT message.mid FROM message WHERE message.sections &amp;&amp; '{1,2}';
+
+-- select messages in sections 1 AND 2 - CONTAINS operator
+SELECT message.mid FROM message WHERE message.sections @&gt; '{1,2}';
+
+-- the same, using QUERY operator
+SELECT message.mid FROM message WHERE message.sections @@ '1&amp;2'::query_int;
+</pre></div><div class="sect2" id="id-1.11.7.29.10"><div class="titlepage"><div><div><h3 class="title">F.20.4. Benchmark</h3></div></div></div><p>
+ The source directory <code class="filename">contrib/intarray/bench</code> contains a
+ benchmark test suite, which can be run against an installed
+ <span class="productname">PostgreSQL</span> server. (It also requires <code class="filename">DBD::Pg</code>
+ to be installed.) To run:
+ </p><pre class="programlisting">
+cd .../contrib/intarray/bench
+createdb TEST
+psql -c "CREATE EXTENSION intarray" TEST
+./create_test.pl | psql TEST
+./bench.pl
+</pre><p>
+ The <code class="filename">bench.pl</code> script has numerous options, which
+ are displayed when it is run without any arguments.
+ </p></div><div class="sect2" id="id-1.11.7.29.11"><div class="titlepage"><div><div><h3 class="title">F.20.5. Authors</h3></div></div></div><p>
+ All work was done by Teodor Sigaev (<code class="email">&lt;<a class="email" href="mailto:teodor@sigaev.ru">teodor@sigaev.ru</a>&gt;</code>) and
+ Oleg Bartunov (<code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>). See
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/</a> for
+ additional information. Andrey Oktyabrski did a great work on adding new
+ functions and operations.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intagg.html" title="F.19. intagg">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="isn.html" title="F.21. isn">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.19. intagg </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.21. isn</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/internals.html b/doc/src/sgml/html/internals.html
new file mode 100644
index 0000000..e5cd755
--- /dev/null
+++ b/doc/src/sgml/html/internals.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part VII. Internals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-postmaster.html" title="postmaster" /><link rel="next" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part VII. Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-postmaster.html" title="postmaster">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Next</a></td></tr></table><hr /></div><div class="part" id="INTERNALS"><div class="titlepage"><div><div><h1 class="title">Part VII. Internals</h1></div></div></div><div class="partintro" id="id-1.10.2"><div></div><p>
+ This part contains assorted information that might be of use to
+ <span class="productname">PostgreSQL</span> developers.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="overview.html">52. Overview of PostgreSQL Internals</a></span></dt><dd><dl><dt><span class="sect1"><a href="query-path.html">52.1. The Path of a Query</a></span></dt><dt><span class="sect1"><a href="connect-estab.html">52.2. How Connections Are Established</a></span></dt><dt><span class="sect1"><a href="parser-stage.html">52.3. The Parser Stage</a></span></dt><dt><span class="sect1"><a href="rule-system.html">52.4. The <span class="productname">PostgreSQL</span> Rule System</a></span></dt><dt><span class="sect1"><a href="planner-optimizer.html">52.5. Planner/Optimizer</a></span></dt><dt><span class="sect1"><a href="executor.html">52.6. Executor</a></span></dt></dl></dd><dt><span class="chapter"><a href="catalogs.html">53. System Catalogs</a></span></dt><dd><dl><dt><span class="sect1"><a href="catalogs-overview.html">53.1. Overview</a></span></dt><dt><span class="sect1"><a href="catalog-pg-aggregate.html">53.2. <code class="structname">pg_aggregate</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-am.html">53.3. <code class="structname">pg_am</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-amop.html">53.4. <code class="structname">pg_amop</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-amproc.html">53.5. <code class="structname">pg_amproc</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-attrdef.html">53.6. <code class="structname">pg_attrdef</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-attribute.html">53.7. <code class="structname">pg_attribute</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-authid.html">53.8. <code class="structname">pg_authid</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-auth-members.html">53.9. <code class="structname">pg_auth_members</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-cast.html">53.10. <code class="structname">pg_cast</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-class.html">53.11. <code class="structname">pg_class</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-collation.html">53.12. <code class="structname">pg_collation</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-constraint.html">53.13. <code class="structname">pg_constraint</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-conversion.html">53.14. <code class="structname">pg_conversion</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-database.html">53.15. <code class="structname">pg_database</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-db-role-setting.html">53.16. <code class="structname">pg_db_role_setting</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-default-acl.html">53.17. <code class="structname">pg_default_acl</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-depend.html">53.18. <code class="structname">pg_depend</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-description.html">53.19. <code class="structname">pg_description</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-enum.html">53.20. <code class="structname">pg_enum</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-event-trigger.html">53.21. <code class="structname">pg_event_trigger</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-extension.html">53.22. <code class="structname">pg_extension</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-data-wrapper.html">53.23. <code class="structname">pg_foreign_data_wrapper</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-server.html">53.24. <code class="structname">pg_foreign_server</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-foreign-table.html">53.25. <code class="structname">pg_foreign_table</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-index.html">53.26. <code class="structname">pg_index</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-inherits.html">53.27. <code class="structname">pg_inherits</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-init-privs.html">53.28. <code class="structname">pg_init_privs</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-language.html">53.29. <code class="structname">pg_language</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-largeobject.html">53.30. <code class="structname">pg_largeobject</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-largeobject-metadata.html">53.31. <code class="structname">pg_largeobject_metadata</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-namespace.html">53.32. <code class="structname">pg_namespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-opclass.html">53.33. <code class="structname">pg_opclass</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-operator.html">53.34. <code class="structname">pg_operator</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-opfamily.html">53.35. <code class="structname">pg_opfamily</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-parameter-acl.html">53.36. <code class="structname">pg_parameter_acl</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-partitioned-table.html">53.37. <code class="structname">pg_partitioned_table</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-policy.html">53.38. <code class="structname">pg_policy</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-proc.html">53.39. <code class="structname">pg_proc</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication.html">53.40. <code class="structname">pg_publication</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication-namespace.html">53.41. <code class="structname">pg_publication_namespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-publication-rel.html">53.42. <code class="structname">pg_publication_rel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-range.html">53.43. <code class="structname">pg_range</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-replication-origin.html">53.44. <code class="structname">pg_replication_origin</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-rewrite.html">53.45. <code class="structname">pg_rewrite</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-seclabel.html">53.46. <code class="structname">pg_seclabel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-sequence.html">53.47. <code class="structname">pg_sequence</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shdepend.html">53.48. <code class="structname">pg_shdepend</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shdescription.html">53.49. <code class="structname">pg_shdescription</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-shseclabel.html">53.50. <code class="structname">pg_shseclabel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic.html">53.51. <code class="structname">pg_statistic</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic-ext.html">53.52. <code class="structname">pg_statistic_ext</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-statistic-ext-data.html">53.53. <code class="structname">pg_statistic_ext_data</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-subscription.html">53.54. <code class="structname">pg_subscription</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-subscription-rel.html">53.55. <code class="structname">pg_subscription_rel</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-tablespace.html">53.56. <code class="structname">pg_tablespace</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-transform.html">53.57. <code class="structname">pg_transform</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-trigger.html">53.58. <code class="structname">pg_trigger</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-config.html">53.59. <code class="structname">pg_ts_config</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-config-map.html">53.60. <code class="structname">pg_ts_config_map</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-dict.html">53.61. <code class="structname">pg_ts_dict</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-parser.html">53.62. <code class="structname">pg_ts_parser</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-ts-template.html">53.63. <code class="structname">pg_ts_template</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-type.html">53.64. <code class="structname">pg_type</code></a></span></dt><dt><span class="sect1"><a href="catalog-pg-user-mapping.html">53.65. <code class="structname">pg_user_mapping</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="views.html">54. System Views</a></span></dt><dd><dl><dt><span class="sect1"><a href="views-overview.html">54.1. Overview</a></span></dt><dt><span class="sect1"><a href="view-pg-available-extensions.html">54.2. <code class="structname">pg_available_extensions</code></a></span></dt><dt><span class="sect1"><a href="view-pg-available-extension-versions.html">54.3. <code class="structname">pg_available_extension_versions</code></a></span></dt><dt><span class="sect1"><a href="view-pg-backend-memory-contexts.html">54.4. <code class="structname">pg_backend_memory_contexts</code></a></span></dt><dt><span class="sect1"><a href="view-pg-config.html">54.5. <code class="structname">pg_config</code></a></span></dt><dt><span class="sect1"><a href="view-pg-cursors.html">54.6. <code class="structname">pg_cursors</code></a></span></dt><dt><span class="sect1"><a href="view-pg-file-settings.html">54.7. <code class="structname">pg_file_settings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-group.html">54.8. <code class="structname">pg_group</code></a></span></dt><dt><span class="sect1"><a href="view-pg-hba-file-rules.html">54.9. <code class="structname">pg_hba_file_rules</code></a></span></dt><dt><span class="sect1"><a href="view-pg-ident-file-mappings.html">54.10. <code class="structname">pg_ident_file_mappings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-indexes.html">54.11. <code class="structname">pg_indexes</code></a></span></dt><dt><span class="sect1"><a href="view-pg-locks.html">54.12. <code class="structname">pg_locks</code></a></span></dt><dt><span class="sect1"><a href="view-pg-matviews.html">54.13. <code class="structname">pg_matviews</code></a></span></dt><dt><span class="sect1"><a href="view-pg-policies.html">54.14. <code class="structname">pg_policies</code></a></span></dt><dt><span class="sect1"><a href="view-pg-prepared-statements.html">54.15. <code class="structname">pg_prepared_statements</code></a></span></dt><dt><span class="sect1"><a href="view-pg-prepared-xacts.html">54.16. <code class="structname">pg_prepared_xacts</code></a></span></dt><dt><span class="sect1"><a href="view-pg-publication-tables.html">54.17. <code class="structname">pg_publication_tables</code></a></span></dt><dt><span class="sect1"><a href="view-pg-replication-origin-status.html">54.18. <code class="structname">pg_replication_origin_status</code></a></span></dt><dt><span class="sect1"><a href="view-pg-replication-slots.html">54.19. <code class="structname">pg_replication_slots</code></a></span></dt><dt><span class="sect1"><a href="view-pg-roles.html">54.20. <code class="structname">pg_roles</code></a></span></dt><dt><span class="sect1"><a href="view-pg-rules.html">54.21. <code class="structname">pg_rules</code></a></span></dt><dt><span class="sect1"><a href="view-pg-seclabels.html">54.22. <code class="structname">pg_seclabels</code></a></span></dt><dt><span class="sect1"><a href="view-pg-sequences.html">54.23. <code class="structname">pg_sequences</code></a></span></dt><dt><span class="sect1"><a href="view-pg-settings.html">54.24. <code class="structname">pg_settings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-shadow.html">54.25. <code class="structname">pg_shadow</code></a></span></dt><dt><span class="sect1"><a href="view-pg-shmem-allocations.html">54.26. <code class="structname">pg_shmem_allocations</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats.html">54.27. <code class="structname">pg_stats</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats-ext.html">54.28. <code class="structname">pg_stats_ext</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats-ext-exprs.html">54.29. <code class="structname">pg_stats_ext_exprs</code></a></span></dt><dt><span class="sect1"><a href="view-pg-tables.html">54.30. <code class="structname">pg_tables</code></a></span></dt><dt><span class="sect1"><a href="view-pg-timezone-abbrevs.html">54.31. <code class="structname">pg_timezone_abbrevs</code></a></span></dt><dt><span class="sect1"><a href="view-pg-timezone-names.html">54.32. <code class="structname">pg_timezone_names</code></a></span></dt><dt><span class="sect1"><a href="view-pg-user.html">54.33. <code class="structname">pg_user</code></a></span></dt><dt><span class="sect1"><a href="view-pg-user-mappings.html">54.34. <code class="structname">pg_user_mappings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-views.html">54.35. <code class="structname">pg_views</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="protocol.html">55. Frontend/Backend Protocol</a></span></dt><dd><dl><dt><span class="sect1"><a href="protocol-overview.html">55.1. Overview</a></span></dt><dt><span class="sect1"><a href="protocol-flow.html">55.2. Message Flow</a></span></dt><dt><span class="sect1"><a href="sasl-authentication.html">55.3. SASL Authentication</a></span></dt><dt><span class="sect1"><a href="protocol-replication.html">55.4. Streaming Replication Protocol</a></span></dt><dt><span class="sect1"><a href="protocol-logical-replication.html">55.5. Logical Streaming Replication Protocol</a></span></dt><dt><span class="sect1"><a href="protocol-message-types.html">55.6. Message Data Types</a></span></dt><dt><span class="sect1"><a href="protocol-message-formats.html">55.7. Message Formats</a></span></dt><dt><span class="sect1"><a href="protocol-error-fields.html">55.8. Error and Notice Message Fields</a></span></dt><dt><span class="sect1"><a href="protocol-logicalrep-message-formats.html">55.9. Logical Replication Message Formats</a></span></dt><dt><span class="sect1"><a href="protocol-changes.html">55.10. Summary of Changes since Protocol 2.0</a></span></dt></dl></dd><dt><span class="chapter"><a href="source.html">56. PostgreSQL Coding Conventions</a></span></dt><dd><dl><dt><span class="sect1"><a href="source-format.html">56.1. Formatting</a></span></dt><dt><span class="sect1"><a href="error-message-reporting.html">56.2. Reporting Errors Within the Server</a></span></dt><dt><span class="sect1"><a href="error-style-guide.html">56.3. Error Message Style Guide</a></span></dt><dt><span class="sect1"><a href="source-conventions.html">56.4. Miscellaneous Coding Conventions</a></span></dt></dl></dd><dt><span class="chapter"><a href="nls.html">57. Native Language Support</a></span></dt><dd><dl><dt><span class="sect1"><a href="nls-translator.html">57.1. For the Translator</a></span></dt><dt><span class="sect1"><a href="nls-programmer.html">57.2. For the Programmer</a></span></dt></dl></dd><dt><span class="chapter"><a href="plhandler.html">58. Writing a Procedural Language Handler</a></span></dt><dt><span class="chapter"><a href="fdwhandler.html">59. Writing a Foreign Data Wrapper</a></span></dt><dd><dl><dt><span class="sect1"><a href="fdw-functions.html">59.1. Foreign Data Wrapper Functions</a></span></dt><dt><span class="sect1"><a href="fdw-callbacks.html">59.2. Foreign Data Wrapper Callback Routines</a></span></dt><dt><span class="sect1"><a href="fdw-helpers.html">59.3. Foreign Data Wrapper Helper Functions</a></span></dt><dt><span class="sect1"><a href="fdw-planning.html">59.4. Foreign Data Wrapper Query Planning</a></span></dt><dt><span class="sect1"><a href="fdw-row-locking.html">59.5. Row Locking in Foreign Data Wrappers</a></span></dt></dl></dd><dt><span class="chapter"><a href="tablesample-method.html">60. Writing a Table Sampling Method</a></span></dt><dd><dl><dt><span class="sect1"><a href="tablesample-support-functions.html">60.1. Sampling Method Support Functions</a></span></dt></dl></dd><dt><span class="chapter"><a href="custom-scan.html">61. Writing a Custom Scan Provider</a></span></dt><dd><dl><dt><span class="sect1"><a href="custom-scan-path.html">61.1. Creating Custom Scan Paths</a></span></dt><dt><span class="sect1"><a href="custom-scan-plan.html">61.2. Creating Custom Scan Plans</a></span></dt><dt><span class="sect1"><a href="custom-scan-execution.html">61.3. Executing Custom Scans</a></span></dt></dl></dd><dt><span class="chapter"><a href="geqo.html">62. Genetic Query Optimizer</a></span></dt><dd><dl><dt><span class="sect1"><a href="geqo-intro.html">62.1. Query Handling as a Complex Optimization Problem</a></span></dt><dt><span class="sect1"><a href="geqo-intro2.html">62.2. Genetic Algorithms</a></span></dt><dt><span class="sect1"><a href="geqo-pg-intro.html">62.3. Genetic Query Optimization (<acronym class="acronym">GEQO</acronym>) in PostgreSQL</a></span></dt><dt><span class="sect1"><a href="geqo-biblio.html">62.4. Further Reading</a></span></dt></dl></dd><dt><span class="chapter"><a href="tableam.html">63. Table Access Method Interface Definition</a></span></dt><dt><span class="chapter"><a href="indexam.html">64. Index Access Method Interface Definition</a></span></dt><dd><dl><dt><span class="sect1"><a href="index-api.html">64.1. Basic API Structure for Indexes</a></span></dt><dt><span class="sect1"><a href="index-functions.html">64.2. Index Access Method Functions</a></span></dt><dt><span class="sect1"><a href="index-scanning.html">64.3. Index Scanning</a></span></dt><dt><span class="sect1"><a href="index-locking.html">64.4. Index Locking Considerations</a></span></dt><dt><span class="sect1"><a href="index-unique-checks.html">64.5. Index Uniqueness Checks</a></span></dt><dt><span class="sect1"><a href="index-cost-estimation.html">64.6. Index Cost Estimation Functions</a></span></dt></dl></dd><dt><span class="chapter"><a href="generic-wal.html">65. Generic WAL Records</a></span></dt><dt><span class="chapter"><a href="custom-rmgr.html">66. Custom WAL Resource Managers</a></span></dt><dt><span class="chapter"><a href="btree.html">67. B-Tree Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="btree-intro.html">67.1. Introduction</a></span></dt><dt><span class="sect1"><a href="btree-behavior.html">67.2. Behavior of B-Tree Operator Classes</a></span></dt><dt><span class="sect1"><a href="btree-support-funcs.html">67.3. B-Tree Support Functions</a></span></dt><dt><span class="sect1"><a href="btree-implementation.html">67.4. Implementation</a></span></dt></dl></dd><dt><span class="chapter"><a href="gist.html">68. GiST Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="gist-intro.html">68.1. Introduction</a></span></dt><dt><span class="sect1"><a href="gist-builtin-opclasses.html">68.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="gist-extensibility.html">68.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="gist-implementation.html">68.4. Implementation</a></span></dt><dt><span class="sect1"><a href="gist-examples.html">68.5. Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="spgist.html">69. SP-GiST Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="spgist-intro.html">69.1. Introduction</a></span></dt><dt><span class="sect1"><a href="spgist-builtin-opclasses.html">69.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="spgist-extensibility.html">69.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="spgist-implementation.html">69.4. Implementation</a></span></dt><dt><span class="sect1"><a href="spgist-examples.html">69.5. Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="gin.html">70. GIN Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="gin-intro.html">70.1. Introduction</a></span></dt><dt><span class="sect1"><a href="gin-builtin-opclasses.html">70.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="gin-extensibility.html">70.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="gin-implementation.html">70.4. Implementation</a></span></dt><dt><span class="sect1"><a href="gin-tips.html">70.5. GIN Tips and Tricks</a></span></dt><dt><span class="sect1"><a href="gin-limit.html">70.6. Limitations</a></span></dt><dt><span class="sect1"><a href="gin-examples.html">70.7. Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="brin.html">71. BRIN Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="brin-intro.html">71.1. Introduction</a></span></dt><dt><span class="sect1"><a href="brin-builtin-opclasses.html">71.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="brin-extensibility.html">71.3. Extensibility</a></span></dt></dl></dd><dt><span class="chapter"><a href="hash-index.html">72. Hash Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="hash-intro.html">72.1. Overview</a></span></dt><dt><span class="sect1"><a href="hash-implementation.html">72.2. Implementation</a></span></dt></dl></dd><dt><span class="chapter"><a href="storage.html">73. Database Physical Storage</a></span></dt><dd><dl><dt><span class="sect1"><a href="storage-file-layout.html">73.1. Database File Layout</a></span></dt><dt><span class="sect1"><a href="storage-toast.html">73.2. TOAST</a></span></dt><dt><span class="sect1"><a href="storage-fsm.html">73.3. Free Space Map</a></span></dt><dt><span class="sect1"><a href="storage-vm.html">73.4. Visibility Map</a></span></dt><dt><span class="sect1"><a href="storage-init.html">73.5. The Initialization Fork</a></span></dt><dt><span class="sect1"><a href="storage-page-layout.html">73.6. Database Page Layout</a></span></dt><dt><span class="sect1"><a href="storage-hot.html">73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>)</a></span></dt></dl></dd><dt><span class="chapter"><a href="bki.html">74. System Catalog Declarations and Initial Contents</a></span></dt><dd><dl><dt><span class="sect1"><a href="system-catalog-declarations.html">74.1. System Catalog Declaration Rules</a></span></dt><dt><span class="sect1"><a href="system-catalog-initial-data.html">74.2. System Catalog Initial Data</a></span></dt><dt><span class="sect1"><a href="bki-format.html">74.3. <acronym class="acronym">BKI</acronym> File Format</a></span></dt><dt><span class="sect1"><a href="bki-commands.html">74.4. <acronym class="acronym">BKI</acronym> Commands</a></span></dt><dt><span class="sect1"><a href="bki-structure.html">74.5. Structure of the Bootstrap <acronym class="acronym">BKI</acronym> File</a></span></dt><dt><span class="sect1"><a href="bki-example.html">74.6. BKI Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="planner-stats-details.html">75. How the Planner Uses Statistics</a></span></dt><dd><dl><dt><span class="sect1"><a href="row-estimation-examples.html">75.1. Row Estimation Examples</a></span></dt><dt><span class="sect1"><a href="multivariate-statistics-examples.html">75.2. Multivariate Statistics Examples</a></span></dt><dt><span class="sect1"><a href="planner-stats-security.html">75.3. Planner Statistics and Security</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup-manifest-format.html">76. Backup Manifest Format</a></span></dt><dd><dl><dt><span class="sect1"><a href="backup-manifest-toplevel.html">76.1. Backup Manifest Top-level Object</a></span></dt><dt><span class="sect1"><a href="backup-manifest-files.html">76.2. Backup Manifest File Object</a></span></dt><dt><span class="sect1"><a href="backup-manifest-wal-ranges.html">76.3. Backup Manifest WAL Range Object</a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-postmaster.html" title="postmaster">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">postmaster</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 52. Overview of PostgreSQL Internals</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/intro-whatis.html b/doc/src/sgml/html/intro-whatis.html
new file mode 100644
index 0000000..b596a3c
--- /dev/null
+++ b/doc/src/sgml/html/intro-whatis.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>1.  What Is PostgreSQL?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="preface.html" title="Preface" /><link rel="next" href="history.html" title="2. A Brief History of PostgreSQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">1.  What Is <span class="productname">PostgreSQL</span>?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="preface.html" title="Preface">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="history.html" title="2. A Brief History of PostgreSQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="INTRO-WHATIS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.  What Is <span class="productname">PostgreSQL</span>?</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> is an object-relational
+ database management system (<acronym class="acronym">ORDBMS</acronym>) based on
+ <a class="ulink" href="https://dsf.berkeley.edu/postgres.html" target="_top">
+ <span class="productname">POSTGRES, Version 4.2</span></a>,
+ developed at the University of California at Berkeley Computer Science
+ Department. POSTGRES pioneered many concepts that only became
+ available in some commercial database systems much later.
+ </p><p>
+ <span class="productname">PostgreSQL</span> is an open-source descendant
+ of this original Berkeley code. It supports a large part of the SQL
+ standard and offers many modern features:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">complex queries</li><li class="listitem">foreign keys</li><li class="listitem">triggers</li><li class="listitem">updatable views</li><li class="listitem">transactional integrity</li><li class="listitem">multiversion concurrency control</li></ul></div><p>
+
+ Also, <span class="productname">PostgreSQL</span> can be extended by the
+ user in many ways, for example by adding new
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">data types</li><li class="listitem">functions</li><li class="listitem">operators</li><li class="listitem">aggregate functions</li><li class="listitem">index methods</li><li class="listitem">procedural languages</li></ul></div><p>
+ </p><p>
+ And because of the liberal license,
+ <span class="productname">PostgreSQL</span> can be used, modified, and
+ distributed by anyone free of charge for any purpose, be it
+ private, commercial, or academic.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="preface.html" title="Preface">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="history.html" title="2. A Brief History of PostgreSQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Preface </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2. A Brief History of <span class="productname">PostgreSQL</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/isn.html b/doc/src/sgml/html/isn.html
new file mode 100644
index 0000000..d1b5642
--- /dev/null
+++ b/doc/src/sgml/html/isn.html
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.21. isn</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="intarray.html" title="F.20. intarray" /><link rel="next" href="lo.html" title="F.22. lo" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.21. isn</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="intarray.html" title="F.20. intarray">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo.html" title="F.22. lo">Next</a></td></tr></table><hr /></div><div class="sect1" id="ISN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.21. isn</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.5">F.21.1. Data Types</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.6">F.21.2. Casts</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.7">F.21.3. Functions and Operators</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.8">F.21.4. Examples</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.9">F.21.5. Bibliography</a></span></dt><dt><span class="sect2"><a href="isn.html#id-1.11.7.30.10">F.21.6. Author</a></span></dt></dl></div><a id="id-1.11.7.30.2" class="indexterm"></a><p>
+ The <code class="filename">isn</code> module provides data types for the following
+ international product numbering standards: EAN13, UPC, ISBN (books), ISMN
+ (music), and ISSN (serials). Numbers are validated on input according to a
+ hard-coded list of prefixes; this list of prefixes is also used to hyphenate
+ numbers on output. Since new prefixes are assigned from time to time, the
+ list of prefixes may be out of date. It is hoped that a future version of
+ this module will obtain the prefix list from one or more tables that
+ can be easily updated by users as needed; however, at present, the
+ list can only be updated by modifying the source code and recompiling.
+ Alternatively, prefix validation and hyphenation support may be
+ dropped from a future version of this module.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.30.5"><div class="titlepage"><div><div><h3 class="title">F.21.1. Data Types</h3></div></div></div><p>
+ <a class="xref" href="isn.html#ISN-DATATYPES" title="Table F.11. isn Data Types">Table F.11</a> shows the data types provided by
+ the <code class="filename">isn</code> module.
+ </p><div class="table" id="ISN-DATATYPES"><p class="title"><strong>Table F.11. <code class="filename">isn</code> Data Types</strong></p><div class="table-contents"><table class="table" summary="isn Data Types" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">EAN13</code></td><td>
+ European Article Numbers, always displayed in the EAN13 display format
+ </td></tr><tr><td><code class="type">ISBN13</code></td><td>
+ International Standard Book Numbers to be displayed in
+ the new EAN13 display format
+ </td></tr><tr><td><code class="type">ISMN13</code></td><td>
+ International Standard Music Numbers to be displayed in
+ the new EAN13 display format
+ </td></tr><tr><td><code class="type">ISSN13</code></td><td>
+ International Standard Serial Numbers to be displayed in the new
+ EAN13 display format
+ </td></tr><tr><td><code class="type">ISBN</code></td><td>
+ International Standard Book Numbers to be displayed in the old
+ short display format
+ </td></tr><tr><td><code class="type">ISMN</code></td><td>
+ International Standard Music Numbers to be displayed in the
+ old short display format
+ </td></tr><tr><td><code class="type">ISSN</code></td><td>
+ International Standard Serial Numbers to be displayed in the
+ old short display format
+ </td></tr><tr><td><code class="type">UPC</code></td><td>
+ Universal Product Codes
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Some notes:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>ISBN13, ISMN13, ISSN13 numbers are all EAN13 numbers.</p></li><li class="listitem"><p>EAN13 numbers aren't always ISBN13, ISMN13 or ISSN13 (some
+ are).</p></li><li class="listitem"><p>Some ISBN13 numbers can be displayed as ISBN.</p></li><li class="listitem"><p>Some ISMN13 numbers can be displayed as ISMN.</p></li><li class="listitem"><p>Some ISSN13 numbers can be displayed as ISSN.</p></li><li class="listitem"><p>UPC numbers are a subset of the EAN13 numbers (they are basically
+ EAN13 without the first <code class="literal">0</code> digit).</p></li><li class="listitem"><p>All UPC, ISBN, ISMN and ISSN numbers can be represented as EAN13
+ numbers.</p></li></ol></div><p>
+ Internally, all these types use the same representation (a 64-bit
+ integer), and all are interchangeable. Multiple types are provided
+ to control display formatting and to permit tighter validity checking
+ of input that is supposed to denote one particular type of number.
+ </p><p>
+ The <code class="type">ISBN</code>, <code class="type">ISMN</code>, and <code class="type">ISSN</code> types will display the
+ short version of the number (ISxN 10) whenever it's possible, and will show
+ ISxN 13 format for numbers that do not fit in the short version.
+ The <code class="type">EAN13</code>, <code class="type">ISBN13</code>, <code class="type">ISMN13</code> and
+ <code class="type">ISSN13</code> types will always display the long version of the ISxN
+ (EAN13).
+ </p></div><div class="sect2" id="id-1.11.7.30.6"><div class="titlepage"><div><div><h3 class="title">F.21.2. Casts</h3></div></div></div><p>
+ The <code class="filename">isn</code> module provides the following pairs of type casts:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ ISBN13 &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISMN13 &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISSN13 &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISBN &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISMN &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISSN &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ UPC &lt;=&gt; EAN13
+ </p></li><li class="listitem"><p>
+ ISBN &lt;=&gt; ISBN13
+ </p></li><li class="listitem"><p>
+ ISMN &lt;=&gt; ISMN13
+ </p></li><li class="listitem"><p>
+ ISSN &lt;=&gt; ISSN13
+ </p></li></ul></div><p>
+ When casting from <code class="type">EAN13</code> to another type, there is a run-time
+ check that the value is within the domain of the other type, and an error
+ is thrown if not. The other casts are simply relabelings that will
+ always succeed.
+ </p></div><div class="sect2" id="id-1.11.7.30.7"><div class="titlepage"><div><div><h3 class="title">F.21.3. Functions and Operators</h3></div></div></div><p>
+ The <code class="filename">isn</code> 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 <a class="xref" href="isn.html#ISN-FUNCTIONS" title="Table F.12. isn Functions">Table F.12</a>.
+ In this table,
+ <code class="type">isn</code> means any one of the module's data types.
+ </p><div class="table" id="ISN-FUNCTIONS"><p class="title"><strong>Table F.12. <code class="filename">isn</code> Functions</strong></p><div class="table-contents"><table class="table" summary="isn Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.30.7.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">isn_weak</code> ( <code class="type">boolean</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Sets the weak input mode, and returns new setting.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">isn_weak</code> ()
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns the current status of the weak mode.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.30.7.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">make_valid</code> ( <code class="type">isn</code> )
+ → <code class="returnvalue">isn</code>
+ </p>
+ <p>
+ Validates an invalid number (clears the invalid flag).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.30.7.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">is_valid</code> ( <code class="type">isn</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Checks for the presence of the invalid flag.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <em class="firstterm">Weak</em> mode is used to be able to insert invalid data
+ into a table. Invalid means the check digit is wrong, not that there are
+ missing numbers.
+ </p><p>
+ Why would you want to use the weak mode? Well, it could be that
+ you have a huge collection of ISBN numbers, and that there are so many of
+ them that for weird reasons some have the wrong check digit (perhaps the
+ numbers were scanned from a printed list and the OCR got the numbers wrong,
+ perhaps the numbers were manually captured... who knows). Anyway, the point
+ is you might want to clean the mess up, but you still want to be able to
+ have all the numbers in your database and maybe use an external tool to
+ locate the invalid numbers in the database so you can verify the
+ information and validate it more easily; so for example you'd want to
+ select all the invalid numbers in the table.
+ </p><p>
+ When you insert invalid numbers in a table using the weak mode, the number
+ will be inserted with the corrected check digit, but it will be displayed
+ with an exclamation mark (<code class="literal">!</code>) at the end, for example
+ <code class="literal">0-11-000322-5!</code>. This invalid marker can be checked with
+ the <code class="function">is_valid</code> function and cleared with the
+ <code class="function">make_valid</code> function.
+ </p><p>
+ You can also force the insertion of invalid numbers even when not in the
+ weak mode, by appending the <code class="literal">!</code> character at the end of the
+ number.
+ </p><p>
+ Another special feature is that during input, you can write
+ <code class="literal">?</code> in place of the check digit, and the correct check digit
+ will be inserted automatically.
+ </p></div><div class="sect2" id="id-1.11.7.30.8"><div class="titlepage"><div><div><h3 class="title">F.21.4. Examples</h3></div></div></div><pre class="programlisting">
+--Using the types directly:
+SELECT isbn('978-0-393-04002-9');
+SELECT isbn13('0901690546');
+SELECT issn('1436-4522');
+
+--Casting types:
+-- note that you can only cast from ean13 to another type when the
+-- number would be valid in the realm of the target type;
+-- thus, the following will NOT work: select isbn(ean13('0220356483481'));
+-- but these will:
+SELECT upc(ean13('0220356483481'));
+SELECT ean13(upc('220356483481'));
+
+--Create a table with a single column to hold ISBN numbers:
+CREATE TABLE test (id isbn);
+INSERT INTO test VALUES('9780393040029');
+
+--Automatically calculate check digits (observe the '?'):
+INSERT INTO test VALUES('220500896?');
+INSERT INTO test VALUES('978055215372?');
+
+SELECT issn('3251231?');
+SELECT ismn('979047213542?');
+
+--Using the weak mode:
+SELECT isn_weak(true);
+INSERT INTO test VALUES('978-0-11-000533-4');
+INSERT INTO test VALUES('9780141219307');
+INSERT INTO test VALUES('2-205-00876-X');
+SELECT isn_weak(false);
+
+SELECT id FROM test WHERE NOT is_valid(id);
+UPDATE test SET id = make_valid(id) WHERE id = '2-205-00876-X!';
+
+SELECT * FROM test;
+
+SELECT isbn13(id) FROM test;
+</pre></div><div class="sect2" id="id-1.11.7.30.9"><div class="titlepage"><div><div><h3 class="title">F.21.5. Bibliography</h3></div></div></div><p>
+ The information to implement this module was collected from
+ several sites, including:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.isbn-international.org/" target="_top">https://www.isbn-international.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.issn.org/" target="_top">https://www.issn.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.ismn-international.org/" target="_top">https://www.ismn-international.org/</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.wikipedia.org/" target="_top">https://www.wikipedia.org/</a></p></li></ul></div><p>
+
+ The prefixes used for hyphenation were also compiled from:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.gs1.org/standards/id-keys" target="_top">https://www.gs1.org/standards/id-keys</a></p></li><li class="listitem"><p><a class="ulink" href="https://en.wikipedia.org/wiki/List_of_ISBN_identifier_groups" target="_top">https://en.wikipedia.org/wiki/List_of_ISBN_identifier_groups</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.isbn-international.org/content/isbn-users-manual" target="_top">https://www.isbn-international.org/content/isbn-users-manual</a></p></li><li class="listitem"><p><a class="ulink" href="https://en.wikipedia.org/wiki/International_Standard_Music_Number" target="_top">https://en.wikipedia.org/wiki/International_Standard_Music_Number</a></p></li><li class="listitem"><p><a class="ulink" href="https://www.ismn-international.org/ranges.html" target="_top">https://www.ismn-international.org/ranges.html</a></p></li></ul></div><p>
+
+ Care was taken during the creation of the algorithms and they
+ were meticulously verified against the suggested algorithms
+ in the official ISBN, ISMN, ISSN User Manuals.
+ </p></div><div class="sect2" id="id-1.11.7.30.10"><div class="titlepage"><div><div><h3 class="title">F.21.6. Author</h3></div></div></div><p>
+ Germán Méndez Bravo (Kronuz), 2004–2006
+ </p><p>
+ This module was inspired by Garrett A. Wollman's
+ <code class="filename">isbn_issn</code> code.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intarray.html" title="F.20. intarray">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo.html" title="F.22. lo">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.20. intarray </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.22. lo</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/jit-configuration.html b/doc/src/sgml/html/jit-configuration.html
new file mode 100644
index 0000000..feab98d
--- /dev/null
+++ b/doc/src/sgml/html/jit-configuration.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.3. Configuration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="jit-decision.html" title="32.2. When to JIT?" /><link rel="next" href="jit-extensibility.html" title="32.4. Extensibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.3. Configuration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="jit-decision.html" title="32.2. When to JIT?">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><th width="60%" align="center">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="jit-extensibility.html" title="32.4. Extensibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="JIT-CONFIGURATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.3. Configuration</h2></div></div></div><p>
+ The configuration variable
+ <a class="xref" href="runtime-config-query.html#GUC-JIT">jit</a> determines whether <acronym class="acronym">JIT</acronym>
+ compilation is enabled or disabled.
+ If it is enabled, the configuration variables
+ <a class="xref" href="runtime-config-query.html#GUC-JIT-ABOVE-COST">jit_above_cost</a>, <a class="xref" href="runtime-config-query.html#GUC-JIT-INLINE-ABOVE-COST">jit_inline_above_cost</a>, and <a class="xref" href="runtime-config-query.html#GUC-JIT-OPTIMIZE-ABOVE-COST">jit_optimize_above_cost</a> determine
+ whether <acronym class="acronym">JIT</acronym> compilation is performed for a query,
+ and how much effort is spent doing so.
+ </p><p>
+ <a class="xref" href="runtime-config-client.html#GUC-JIT-PROVIDER">jit_provider</a> determines which <acronym class="acronym">JIT</acronym>
+ implementation is used. It is rarely required to be changed. See <a class="xref" href="jit-extensibility.html#JIT-PLUGGABLE" title="32.4.2. Pluggable JIT Providers">Section 32.4.2</a>.
+ </p><p>
+ For development and debugging purposes a few additional configuration
+ parameters exist, as described in
+ <a class="xref" href="runtime-config-developer.html" title="20.17. Developer Options">Section 20.17</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jit-decision.html" title="32.2. When to JIT?">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jit-extensibility.html" title="32.4. Extensibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.2. When to <acronym class="acronym">JIT</acronym>? </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.4. Extensibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/jit-decision.html b/doc/src/sgml/html/jit-decision.html
new file mode 100644
index 0000000..e5999f0
--- /dev/null
+++ b/doc/src/sgml/html/jit-decision.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.2. When to JIT?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="jit-reason.html" title="32.1. What Is JIT compilation?" /><link rel="next" href="jit-configuration.html" title="32.3. Configuration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.2. When to <acronym class="acronym">JIT</acronym>?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="jit-reason.html" title="32.1. What Is JIT compilation?">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><th width="60%" align="center">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="jit-configuration.html" title="32.3. Configuration">Next</a></td></tr></table><hr /></div><div class="sect1" id="JIT-DECISION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.2. When to <acronym class="acronym">JIT</acronym>?</h2></div></div></div><p>
+ <acronym class="acronym">JIT</acronym> compilation is beneficial primarily for long-running
+ CPU-bound queries. Frequently these will be analytical queries. For short
+ queries the added overhead of performing <acronym class="acronym">JIT</acronym> compilation
+ will often be higher than the time it can save.
+ </p><p>
+ To determine whether <acronym class="acronym">JIT</acronym> compilation should be used,
+ the total estimated cost of a query (see
+ <a class="xref" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Chapter 75</a> and
+ <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS" title="20.7.2. Planner Cost Constants">Section 20.7.2</a>) is used.
+ The estimated cost of the query will be compared with the setting of <a class="xref" href="runtime-config-query.html#GUC-JIT-ABOVE-COST">jit_above_cost</a>. If the cost is higher,
+ <acronym class="acronym">JIT</acronym> compilation will be performed.
+ Two further decisions are then needed.
+ Firstly, if the estimated cost is more
+ than the setting of <a class="xref" href="runtime-config-query.html#GUC-JIT-INLINE-ABOVE-COST">jit_inline_above_cost</a>, short
+ functions and operators used in the query will be inlined.
+ Secondly, if the estimated cost is more than the setting of <a class="xref" href="runtime-config-query.html#GUC-JIT-OPTIMIZE-ABOVE-COST">jit_optimize_above_cost</a>, expensive optimizations are
+ applied to improve the generated code.
+ Each of these options increases the <acronym class="acronym">JIT</acronym> compilation
+ overhead, but can reduce query execution time considerably.
+ </p><p>
+ These cost-based decisions will be made at plan time, not execution
+ time. This means that when prepared statements are in use, and a generic
+ plan is used (see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>), the values of the
+ configuration parameters in effect at prepare time control the decisions,
+ not the settings at execution time.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If <a class="xref" href="runtime-config-query.html#GUC-JIT">jit</a> is set to <code class="literal">off</code>, or if no
+ <acronym class="acronym">JIT</acronym> implementation is available (for example because
+ the server was compiled without <code class="literal">--with-llvm</code>),
+ <acronym class="acronym">JIT</acronym> will not be performed, even if it would be
+ beneficial based on the above criteria. Setting <a class="xref" href="runtime-config-query.html#GUC-JIT">jit</a>
+ to <code class="literal">off</code> has effects at both plan and execution time.
+ </p></div><p>
+ <a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a> can be used to see whether
+ <acronym class="acronym">JIT</acronym> is used or not. As an example, here is a query that
+ is not using <acronym class="acronym">JIT</acronym>:
+</p><pre class="screen">
+=# EXPLAIN ANALYZE SELECT SUM(relpages) FROM pg_class;
+ QUERY PLAN
+-------------------------------------------------------------------​------------------------------------------
+ Aggregate (cost=16.27..16.29 rows=1 width=8) (actual time=0.303..0.303 rows=1 loops=1)
+ -&gt; Seq Scan on pg_class (cost=0.00..15.42 rows=342 width=4) (actual time=0.017..0.111 rows=356 loops=1)
+ Planning Time: 0.116 ms
+ Execution Time: 0.365 ms
+(4 rows)
+</pre><p>
+ Given the cost of the plan, it is entirely reasonable that no
+ <acronym class="acronym">JIT</acronym> was used; the cost of <acronym class="acronym">JIT</acronym> would
+ have been bigger than the potential savings. Adjusting the cost limits
+ will lead to <acronym class="acronym">JIT</acronym> use:
+</p><pre class="screen">
+=# SET jit_above_cost = 10;
+SET
+=# EXPLAIN ANALYZE SELECT SUM(relpages) FROM pg_class;
+ QUERY PLAN
+-------------------------------------------------------------------​------------------------------------------
+ Aggregate (cost=16.27..16.29 rows=1 width=8) (actual time=6.049..6.049 rows=1 loops=1)
+ -&gt; Seq Scan on pg_class (cost=0.00..15.42 rows=342 width=4) (actual time=0.019..0.052 rows=356 loops=1)
+ Planning Time: 0.133 ms
+ JIT:
+ Functions: 3
+ Options: Inlining false, Optimization false, Expressions true, Deforming true
+ Timing: Generation 1.259 ms, Inlining 0.000 ms, Optimization 0.797 ms, Emission 5.048 ms, Total 7.104 ms
+ Execution Time: 7.416 ms
+</pre><p>
+ As visible here, <acronym class="acronym">JIT</acronym> was used, but inlining and
+ expensive optimization were not. If <a class="xref" href="runtime-config-query.html#GUC-JIT-INLINE-ABOVE-COST">jit_inline_above_cost</a> or <a class="xref" href="runtime-config-query.html#GUC-JIT-OPTIMIZE-ABOVE-COST">jit_optimize_above_cost</a> were also lowered,
+ that would change.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jit-reason.html" title="32.1. What Is JIT compilation?">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jit-configuration.html" title="32.3. Configuration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.1. What Is <acronym class="acronym">JIT</acronym> compilation? </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.3. Configuration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/jit-extensibility.html b/doc/src/sgml/html/jit-extensibility.html
new file mode 100644
index 0000000..3c2dd01
--- /dev/null
+++ b/doc/src/sgml/html/jit-extensibility.html
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.4. Extensibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="jit-configuration.html" title="32.3. Configuration" /><link rel="next" href="regress.html" title="Chapter 33. Regression Tests" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.4. Extensibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="jit-configuration.html" title="32.3. Configuration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><th width="60%" align="center">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress.html" title="Chapter 33. Regression Tests">Next</a></td></tr></table><hr /></div><div class="sect1" id="JIT-EXTENSIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.4. Extensibility</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="jit-extensibility.html#JIT-EXTENSIBILITY-BITCODE">32.4.1. Inlining Support for Extensions</a></span></dt><dt><span class="sect2"><a href="jit-extensibility.html#JIT-PLUGGABLE">32.4.2. Pluggable <acronym class="acronym">JIT</acronym> Providers</a></span></dt></dl></div><div class="sect2" id="JIT-EXTENSIBILITY-BITCODE"><div class="titlepage"><div><div><h3 class="title">32.4.1. Inlining Support for Extensions</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span>'s <acronym class="acronym">JIT</acronym>
+ implementation can inline the bodies of functions
+ of types <code class="literal">C</code> and <code class="literal">internal</code>, as well as
+ operators based on such functions. To do so for functions in extensions,
+ the definitions of those functions need to be made available.
+ When using <a class="link" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">PGXS</a> to build an extension
+ against a server that has been compiled with LLVM JIT support, the
+ relevant files will be built and installed automatically.
+ </p><p>
+ The relevant files have to be installed into
+ <code class="filename">$pkglibdir/bitcode/$extension/</code> and a summary of them
+ into <code class="filename">$pkglibdir/bitcode/$extension.index.bc</code>, where
+ <code class="literal">$pkglibdir</code> is the directory returned by
+ <code class="literal">pg_config --pkglibdir</code> and <code class="literal">$extension</code>
+ is the base name of the extension's shared library.
+
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ For functions built into <span class="productname">PostgreSQL</span> itself,
+ the bitcode is installed into
+ <code class="literal">$pkglibdir/bitcode/postgres</code>.
+ </p></div><p>
+ </p></div><div class="sect2" id="JIT-PLUGGABLE"><div class="titlepage"><div><div><h3 class="title">32.4.2. Pluggable <acronym class="acronym">JIT</acronym> Providers</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides a <acronym class="acronym">JIT</acronym>
+ implementation based on <span class="productname">LLVM</span>. The interface to
+ the <acronym class="acronym">JIT</acronym> provider is pluggable and the provider can be
+ changed without recompiling (although currently, the build process only
+ provides inlining support data for <span class="productname">LLVM</span>).
+ The active provider is chosen via the setting
+ <a class="xref" href="runtime-config-client.html#GUC-JIT-PROVIDER">jit_provider</a>.
+ </p><div class="sect3" id="id-1.6.19.8.3.3"><div class="titlepage"><div><div><h4 class="title">32.4.2.1. <acronym class="acronym">JIT</acronym> Provider Interface</h4></div></div></div><p>
+ A <acronym class="acronym">JIT</acronym> provider is loaded by dynamically loading the
+ named shared library. The normal library search path is used to locate
+ the library. To provide the required <acronym class="acronym">JIT</acronym> provider
+ callbacks and to indicate that the library is actually a
+ <acronym class="acronym">JIT</acronym> provider, it needs to provide a C function named
+ <code class="function">_PG_jit_provider_init</code>. This function is passed a
+ struct that needs to be filled with the callback function pointers for
+ individual actions:
+</p><pre class="programlisting">
+struct JitProviderCallbacks
+{
+ JitProviderResetAfterErrorCB reset_after_error;
+ JitProviderReleaseContextCB release_context;
+ JitProviderCompileExprCB compile_expr;
+};
+
+extern void _PG_jit_provider_init(JitProviderCallbacks *cb);
+</pre><p>
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jit-configuration.html" title="32.3. Configuration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress.html" title="Chapter 33. Regression Tests">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.3. Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 33. Regression Tests</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/jit-reason.html b/doc/src/sgml/html/jit-reason.html
new file mode 100644
index 0000000..0af7fe1
--- /dev/null
+++ b/doc/src/sgml/html/jit-reason.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.1. What Is JIT compilation?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)" /><link rel="next" href="jit-decision.html" title="32.2. When to JIT?" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.1. What Is <acronym class="acronym">JIT</acronym> compilation?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><th width="60%" align="center">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="jit-decision.html" title="32.2. When to JIT?">Next</a></td></tr></table><hr /></div><div class="sect1" id="JIT-REASON"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.1. What Is <acronym class="acronym">JIT</acronym> compilation?</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="jit-reason.html#JIT-ACCELERATED-OPERATIONS">32.1.1. <acronym class="acronym">JIT</acronym> Accelerated Operations</a></span></dt><dt><span class="sect2"><a href="jit-reason.html#JIT-INLINING">32.1.2. Inlining</a></span></dt><dt><span class="sect2"><a href="jit-reason.html#JIT-OPTIMIZATION">32.1.3. Optimization</a></span></dt></dl></div><p>
+ Just-in-Time (<acronym class="acronym">JIT</acronym>) compilation is the process of turning
+ some form of interpreted program evaluation into a native program, and
+ doing so at run time.
+ For example, instead of using general-purpose code that can evaluate
+ arbitrary SQL expressions to evaluate a particular SQL predicate
+ like <code class="literal">WHERE a.col = 3</code>, it is possible to generate a
+ function that is specific to that expression and can be natively executed
+ by the CPU, yielding a speedup.
+ </p><p>
+ <span class="productname">PostgreSQL</span> has builtin support to perform
+ <acronym class="acronym">JIT</acronym> compilation using <a class="ulink" href="https://llvm.org/" target="_top"><span class="productname">LLVM</span></a> when
+ <span class="productname">PostgreSQL</span> is built with
+ <a class="link" href="install-procedure.html#CONFIGURE-WITH-LLVM"><code class="literal">--with-llvm</code></a>.
+ </p><p>
+ See <code class="filename">src/backend/jit/README</code> for further details.
+ </p><div class="sect2" id="JIT-ACCELERATED-OPERATIONS"><div class="titlepage"><div><div><h3 class="title">32.1.1. <acronym class="acronym">JIT</acronym> Accelerated Operations</h3></div></div></div><p>
+ Currently <span class="productname">PostgreSQL</span>'s <acronym class="acronym">JIT</acronym>
+ implementation has support for accelerating expression evaluation and
+ tuple deforming. Several other operations could be accelerated in the
+ future.
+ </p><p>
+ Expression evaluation is used to evaluate <code class="literal">WHERE</code>
+ clauses, target lists, aggregates and projections. It can be accelerated
+ by generating code specific to each case.
+ </p><p>
+ Tuple deforming is the process of transforming an on-disk tuple (see <a class="xref" href="storage-page-layout.html#STORAGE-TUPLE-LAYOUT" title="73.6.1. Table Row Layout">Section 73.6.1</a>) into its in-memory representation.
+ It can be accelerated by creating a function specific to the table layout
+ and the number of columns to be extracted.
+ </p></div><div class="sect2" id="JIT-INLINING"><div class="titlepage"><div><div><h3 class="title">32.1.2. Inlining</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> is very extensible and allows new
+ data types, functions, operators and other database objects to be defined;
+ see <a class="xref" href="extend.html" title="Chapter 38. Extending SQL">Chapter 38</a>. In fact the built-in objects are implemented
+ using nearly the same mechanisms. This extensibility implies some
+ overhead, for example due to function calls (see <a class="xref" href="xfunc.html" title="38.3. User-Defined Functions">Section 38.3</a>).
+ To reduce that overhead, <acronym class="acronym">JIT</acronym> compilation can inline the
+ bodies of small functions into the expressions using them. That allows a
+ significant percentage of the overhead to be optimized away.
+ </p></div><div class="sect2" id="JIT-OPTIMIZATION"><div class="titlepage"><div><div><h3 class="title">32.1.3. Optimization</h3></div></div></div><p>
+ <span class="productname">LLVM</span> has support for optimizing generated
+ code. Some of the optimizations are cheap enough to be performed whenever
+ <acronym class="acronym">JIT</acronym> is used, while others are only beneficial for
+ longer-running queries.
+ See <a class="ulink" href="https://llvm.org/docs/Passes.html#transform-passes" target="_top">https://llvm.org/docs/Passes.html#transform-passes</a> for
+ more details about optimizations.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jit-decision.html" title="32.2. When to JIT?">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.2. When to <acronym class="acronym">JIT</acronym>?</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/jit.html b/doc/src/sgml/html/jit.html
new file mode 100644
index 0000000..910ae55
--- /dev/null
+++ b/doc/src/sgml/html/jit.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 32. Just-in-Time Compilation (JIT)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-quick-setup.html" title="31.11. Quick Setup" /><link rel="next" href="jit-reason.html" title="32.1. What Is JIT compilation?" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-quick-setup.html" title="31.11. Quick Setup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="jit-reason.html" title="32.1. What Is JIT compilation?">Next</a></td></tr></table><hr /></div><div class="chapter" id="JIT"><div class="titlepage"><div><div><h2 class="title">Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="jit-reason.html">32.1. What Is <acronym class="acronym">JIT</acronym> compilation?</a></span></dt><dd><dl><dt><span class="sect2"><a href="jit-reason.html#JIT-ACCELERATED-OPERATIONS">32.1.1. <acronym class="acronym">JIT</acronym> Accelerated Operations</a></span></dt><dt><span class="sect2"><a href="jit-reason.html#JIT-INLINING">32.1.2. Inlining</a></span></dt><dt><span class="sect2"><a href="jit-reason.html#JIT-OPTIMIZATION">32.1.3. Optimization</a></span></dt></dl></dd><dt><span class="sect1"><a href="jit-decision.html">32.2. When to <acronym class="acronym">JIT</acronym>?</a></span></dt><dt><span class="sect1"><a href="jit-configuration.html">32.3. Configuration</a></span></dt><dt><span class="sect1"><a href="jit-extensibility.html">32.4. Extensibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="jit-extensibility.html#JIT-EXTENSIBILITY-BITCODE">32.4.1. Inlining Support for Extensions</a></span></dt><dt><span class="sect2"><a href="jit-extensibility.html#JIT-PLUGGABLE">32.4.2. Pluggable <acronym class="acronym">JIT</acronym> Providers</a></span></dt></dl></dd></dl></div><a id="id-1.6.19.2" class="indexterm"></a><a id="id-1.6.19.3" class="indexterm"></a><p>
+ This chapter explains what just-in-time compilation is, and how it can be
+ configured in <span class="productname">PostgreSQL</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-quick-setup.html" title="31.11. Quick Setup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jit-reason.html" title="32.1. What Is JIT compilation?">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.11. Quick Setup </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.1. What Is <acronym class="acronym">JIT</acronym> compilation?</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/kernel-resources.html b/doc/src/sgml/html/kernel-resources.html
new file mode 100644
index 0000000..79471cd
--- /dev/null
+++ b/doc/src/sgml/html/kernel-resources.html
@@ -0,0 +1,553 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.4. Managing Kernel Resources</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="server-start.html" title="19.3. Starting the Database Server" /><link rel="next" href="server-shutdown.html" title="19.5. Shutting Down the Server" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.4. Managing Kernel Resources</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="server-start.html" title="19.3. Starting the Database Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="server-shutdown.html" title="19.5. Shutting Down the Server">Next</a></td></tr></table><hr /></div><div class="sect1" id="KERNEL-RESOURCES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.4. Managing Kernel Resources</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="kernel-resources.html#SYSVIPC">19.4.1. Shared Memory and Semaphores</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#SYSTEMD-REMOVEIPC">19.4.2. systemd RemoveIPC</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#id-1.6.6.7.5">19.4.3. Resource Limits</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">19.4.4. Linux Memory Overcommit</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-HUGE-PAGES">19.4.5. Linux Huge Pages</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> can sometimes exhaust various operating system
+ resource limits, especially when multiple copies of the server are running
+ on the same system, or in very large installations. This section explains
+ the kernel resources used by <span class="productname">PostgreSQL</span> and the steps you
+ can take to resolve problems related to kernel resource consumption.
+ </p><div class="sect2" id="SYSVIPC"><div class="titlepage"><div><div><h3 class="title">19.4.1. Shared Memory and Semaphores</h3></div></div></div><a id="id-1.6.6.7.3.2" class="indexterm"></a><a id="id-1.6.6.7.3.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> requires the operating system to provide
+ inter-process communication (<acronym class="acronym">IPC</acronym>) features, specifically
+ shared memory and semaphores. Unix-derived systems typically provide
+ <span class="quote">“<span class="quote"><span class="systemitem">System V</span></span>”</span> <acronym class="acronym">IPC</acronym>,
+ <span class="quote">“<span class="quote"><span class="systemitem">POSIX</span></span>”</span> <acronym class="acronym">IPC</acronym>, or both.
+ <span class="systemitem">Windows</span> has its own implementation of
+ these features and is not discussed here.
+ </p><p>
+ By default, <span class="productname">PostgreSQL</span> allocates
+ a very small amount of System V shared memory, as well as a much larger
+ amount of anonymous <code class="function">mmap</code> shared memory.
+ Alternatively, a single large System V shared memory region can be used
+ (see <a class="xref" href="runtime-config-resource.html#GUC-SHARED-MEMORY-TYPE">shared_memory_type</a>).
+
+ In addition a significant number of semaphores, which can be either
+ System V or POSIX style, are created at server startup. Currently,
+ POSIX semaphores are used on Linux and FreeBSD systems while other
+ platforms use System V semaphores.
+ </p><p>
+ System V <acronym class="acronym">IPC</acronym> features are typically constrained by
+ system-wide allocation limits.
+ When <span class="productname">PostgreSQL</span> exceeds one of these limits,
+ the server will refuse to start and
+ should leave an instructive error message describing the problem
+ and what to do about it. (See also <a class="xref" href="server-start.html#SERVER-START-FAILURES" title="19.3.1. Server Start-up Failures">Section 19.3.1</a>.) The relevant kernel
+ parameters are named consistently across different systems; <a class="xref" href="kernel-resources.html#SYSVIPC-PARAMETERS" title="Table 19.1. System V IPC Parameters">Table 19.1</a> gives an overview. The methods to set
+ them, however, vary. Suggestions for some platforms are given below.
+ </p><div class="table" id="SYSVIPC-PARAMETERS"><p class="title"><strong>Table 19.1. <span class="systemitem">System V</span> <acronym class="acronym">IPC</acronym> Parameters</strong></p><div class="table-contents"><table class="table" summary="System V IPC Parameters" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Description</th><th>Values needed to run one <span class="productname">PostgreSQL</span> instance</th></tr></thead><tbody><tr><td><code class="varname">SHMMAX</code></td><td>Maximum size of shared memory segment (bytes)</td><td>at least 1kB, but the default is usually much higher</td></tr><tr><td><code class="varname">SHMMIN</code></td><td>Minimum size of shared memory segment (bytes)</td><td>1</td></tr><tr><td><code class="varname">SHMALL</code></td><td>Total amount of shared memory available (bytes or pages)</td><td>same as <code class="varname">SHMMAX</code> if bytes,
+ or <code class="literal">ceil(SHMMAX/PAGE_SIZE)</code> if pages,
+ plus room for other applications</td></tr><tr><td><code class="varname">SHMSEG</code></td><td>Maximum number of shared memory segments per process</td><td>only 1 segment is needed, but the default is much higher</td></tr><tr><td><code class="varname">SHMMNI</code></td><td>Maximum number of shared memory segments system-wide</td><td>like <code class="varname">SHMSEG</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMNI</code></td><td>Maximum number of semaphore identifiers (i.e., sets)</td><td>at least <code class="literal">ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16)</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMNS</code></td><td>Maximum number of semaphores system-wide</td><td><code class="literal">ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16) * 17</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMSL</code></td><td>Maximum number of semaphores per set</td><td>at least 17</td></tr><tr><td><code class="varname">SEMMAP</code></td><td>Number of entries in semaphore map</td><td>see text</td></tr><tr><td><code class="varname">SEMVMX</code></td><td>Maximum value of semaphore</td><td>at least 1000 (The default is often 32767; do not change unless necessary)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <span class="productname">PostgreSQL</span> requires a few bytes of System V shared memory
+ (typically 48 bytes, on 64-bit platforms) for each copy of the server.
+ On most modern operating systems, this amount can easily be allocated.
+ However, if you are running many copies of the server or you explicitly
+ configure the server to use large amounts of System V shared memory (see
+ <a class="xref" href="runtime-config-resource.html#GUC-SHARED-MEMORY-TYPE">shared_memory_type</a> and <a class="xref" href="runtime-config-resource.html#GUC-DYNAMIC-SHARED-MEMORY-TYPE">dynamic_shared_memory_type</a>), it may be necessary to
+ increase <code class="varname">SHMALL</code>, which is the total amount of System V shared
+ memory system-wide. Note that <code class="varname">SHMALL</code> is measured in pages
+ rather than bytes on many systems.
+ </p><p>
+ Less likely to cause problems is the minimum size for shared
+ memory segments (<code class="varname">SHMMIN</code>), which should be at most
+ approximately 32 bytes for <span class="productname">PostgreSQL</span> (it is
+ usually just 1). The maximum number of segments system-wide
+ (<code class="varname">SHMMNI</code>) or per-process (<code class="varname">SHMSEG</code>) are unlikely
+ to cause a problem unless your system has them set to zero.
+ </p><p>
+ When using System V semaphores,
+ <span class="productname">PostgreSQL</span> uses one semaphore per allowed connection
+ (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), allowed autovacuum worker process
+ (<a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MAX-WORKERS">autovacuum_max_workers</a>) and allowed background
+ process (<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>), in sets of 16.
+ Each such set will
+ also contain a 17th semaphore which contains a <span class="quote">“<span class="quote">magic
+ number</span>”</span>, to detect collision with semaphore sets used by
+ other applications. The maximum number of semaphores in the system
+ is set by <code class="varname">SEMMNS</code>, which consequently must be at least
+ as high as <code class="varname">max_connections</code> plus
+ <code class="varname">autovacuum_max_workers</code> plus <code class="varname">max_wal_senders</code>,
+ plus <code class="varname">max_worker_processes</code>, plus one extra for each 16
+ allowed connections plus workers (see the formula in <a class="xref" href="kernel-resources.html#SYSVIPC-PARAMETERS" title="Table 19.1. System V IPC Parameters">Table 19.1</a>). The parameter <code class="varname">SEMMNI</code>
+ determines the limit on the number of semaphore sets that can
+ exist on the system at one time. Hence this parameter must be at
+ least <code class="literal">ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16)</code>.
+ Lowering the number
+ of allowed connections is a temporary workaround for failures,
+ which are usually confusingly worded <span class="quote">“<span class="quote">No space
+ left on device</span>”</span>, from the function <code class="function">semget</code>.
+ </p><p>
+ In some cases it might also be necessary to increase
+ <code class="varname">SEMMAP</code> to be at least on the order of
+ <code class="varname">SEMMNS</code>. If the system has this parameter
+ (many do not), it defines the size of the semaphore
+ resource map, in which each contiguous block of available semaphores
+ needs an entry. When a semaphore set is freed it is either added to
+ an existing entry that is adjacent to the freed block or it is
+ registered under a new map entry. If the map is full, the freed
+ semaphores get lost (until reboot). Fragmentation of the semaphore
+ space could over time lead to fewer available semaphores than there
+ should be.
+ </p><p>
+ Various other settings related to <span class="quote">“<span class="quote">semaphore undo</span>”</span>, such as
+ <code class="varname">SEMMNU</code> and <code class="varname">SEMUME</code>, do not affect
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ When using POSIX semaphores, the number of semaphores needed is the
+ same as for System V, that is one semaphore per allowed connection
+ (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), allowed autovacuum worker process
+ (<a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MAX-WORKERS">autovacuum_max_workers</a>) and allowed background
+ process (<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>).
+ On the platforms where this option is preferred, there is no specific
+ kernel limit on the number of POSIX semaphores.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="systemitem">AIX</span>
+ <a id="id-1.6.6.7.3.14.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ It should not be necessary to do
+ any special configuration for such parameters as
+ <code class="varname">SHMMAX</code>, as it appears this is configured to
+ allow all memory to be used as shared memory. That is the
+ sort of configuration commonly used for other databases such
+ as <span class="application">DB/2</span>.</p><p> It might, however, be necessary to modify the global
+ <code class="command">ulimit</code> information in
+ <code class="filename">/etc/security/limits</code>, as the default hard
+ limits for file sizes (<code class="varname">fsize</code>) and numbers of
+ files (<code class="varname">nofiles</code>) might be too low.
+ </p></dd><dt><span class="term"><span class="systemitem">FreeBSD</span>
+ <a id="id-1.6.6.7.3.14.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default shared memory settings are usually good enough, unless
+ you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
+ System V semaphores are not used on this platform.
+ </p><p>
+ The default IPC settings can be changed using
+ the <code class="command">sysctl</code> or
+ <code class="command">loader</code> interfaces. The following
+ parameters can be set using <code class="command">sysctl</code>:
+</p><pre class="screen">
+<code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.ipc.shmall=32768</code></strong>
+<code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.ipc.shmmax=134217728</code></strong>
+</pre><p>
+ To make these settings persist over reboots, modify
+ <code class="filename">/etc/sysctl.conf</code>.
+ </p><p>
+ If you have set <code class="literal">shared_memory_type</code> to
+ <code class="literal">sysv</code>, you might also want to configure your kernel
+ to lock System V shared memory into RAM and prevent it from being paged
+ out to swap. This can be accomplished using the <code class="command">sysctl</code>
+ setting <code class="literal">kern.ipc.shm_use_phys</code>.
+ </p><p>
+ If running in a FreeBSD jail, you should set its
+ <code class="literal">sysvshm</code> parameter to <code class="literal">new</code>, so that
+ it has its own separate System V shared memory namespace.
+ (Before FreeBSD 11.0, it was necessary to enable shared access to
+ the host's IPC namespace from jails, and take measures to avoid
+ collisions.)
+ </p></dd><dt><span class="term"><span class="systemitem">NetBSD</span>
+ <a id="id-1.6.6.7.3.14.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default shared memory settings are usually good enough, unless
+ you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
+ You will usually want to increase <code class="literal">kern.ipc.semmni</code>
+ and <code class="literal">kern.ipc.semmns</code>,
+ as <span class="systemitem">NetBSD</span>'s default settings
+ for these are uncomfortably small.
+ </p><p>
+ IPC parameters can be adjusted using <code class="command">sysctl</code>,
+ for example:
+</p><pre class="screen">
+<code class="prompt">#</code> <strong class="userinput"><code>sysctl -w kern.ipc.semmni=100</code></strong>
+</pre><p>
+ To make these settings persist over reboots, modify
+ <code class="filename">/etc/sysctl.conf</code>.
+ </p><p>
+ If you have set <code class="literal">shared_memory_type</code> to
+ <code class="literal">sysv</code>, you might also want to configure your kernel
+ to lock System V shared memory into RAM and prevent it from being paged
+ out to swap. This can be accomplished using the <code class="command">sysctl</code>
+ setting <code class="literal">kern.ipc.shm_use_phys</code>.
+ </p></dd><dt><span class="term"><span class="systemitem">OpenBSD</span>
+ <a id="id-1.6.6.7.3.14.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default shared memory settings are usually good enough, unless
+ you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
+ You will usually want to
+ increase <code class="literal">kern.seminfo.semmni</code>
+ and <code class="literal">kern.seminfo.semmns</code>,
+ as <span class="systemitem">OpenBSD</span>'s default settings
+ for these are uncomfortably small.
+ </p><p>
+ IPC parameters can be adjusted using <code class="command">sysctl</code>,
+ for example:
+</p><pre class="screen">
+<code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.seminfo.semmni=100</code></strong>
+</pre><p>
+ To make these settings persist over reboots, modify
+ <code class="filename">/etc/sysctl.conf</code>.
+ </p></dd><dt><span class="term"><span class="systemitem">HP-UX</span>
+ <a id="id-1.6.6.7.3.14.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default settings tend to suffice for normal installations.
+ </p><p>
+ <acronym class="acronym">IPC</acronym> parameters can be set in the <span class="application">System
+ Administration Manager</span> (<acronym class="acronym">SAM</acronym>) under
+ <span class="guimenu">Kernel
+ Configuration</span> → <span class="guimenuitem">Configurable Parameters</span>. Choose
+ <span class="guibutton">Create A New Kernel</span> when you're done.
+ </p></dd><dt><span class="term"><span class="systemitem">Linux</span>
+ <a id="id-1.6.6.7.3.14.6.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default shared memory settings are usually good enough, unless
+ you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>,
+ and even then only on older kernel versions that shipped with low defaults.
+ System V semaphores are not used on this platform.
+ </p><p>
+ The shared memory size settings can be changed via the
+ <code class="command">sysctl</code> interface. For example, to allow 16 GB:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>sysctl -w kernel.shmmax=17179869184</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>sysctl -w kernel.shmall=4194304</code></strong>
+</pre><p>
+ To make these settings persist over reboots, see
+ <code class="filename">/etc/sysctl.conf</code>.
+ </p></dd><dt><span class="term"><span class="systemitem">macOS</span>
+ <a id="id-1.6.6.7.3.14.7.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The default shared memory and semaphore settings are usually good enough, unless
+ you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
+ </p><p>
+ The recommended method for configuring shared memory in macOS
+ is to create a file named <code class="filename">/etc/sysctl.conf</code>,
+ containing variable assignments such as:
+</p><pre class="programlisting">
+kern.sysv.shmmax=4194304
+kern.sysv.shmmin=1
+kern.sysv.shmmni=32
+kern.sysv.shmseg=8
+kern.sysv.shmall=1024
+</pre><p>
+ Note that in some macOS versions,
+ <span class="emphasis"><em>all five</em></span> shared-memory parameters must be set in
+ <code class="filename">/etc/sysctl.conf</code>, else the values will be ignored.
+ </p><p>
+ <code class="varname">SHMMAX</code> can only be set to a multiple of 4096.
+ </p><p>
+ <code class="varname">SHMALL</code> is measured in 4 kB pages on this platform.
+ </p><p>
+ It is possible to change all but <code class="varname">SHMMNI</code> on the fly, using
+ <span class="application">sysctl</span>. But it's still best to set up your preferred
+ values via <code class="filename">/etc/sysctl.conf</code>, so that the values will be
+ kept across reboots.
+ </p></dd><dt><span class="term"><span class="systemitem">Solaris</span><br /></span><span class="term"><span class="systemitem">illumos</span></span></dt><dd><p>
+ The default shared memory and semaphore settings are usually good enough for most
+ <span class="productname">PostgreSQL</span> applications. Solaris defaults
+ to a <code class="varname">SHMMAX</code> of one-quarter of system <acronym class="acronym">RAM</acronym>.
+ To further adjust this setting, use a project setting associated
+ with the <code class="literal">postgres</code> user. For example, run the
+ following as <code class="literal">root</code>:
+</p><pre class="programlisting">
+projadd -c "PostgreSQL DB User" -K "project.max-shm-memory=(privileged,8GB,deny)" -U postgres -G postgres user.postgres
+</pre><p>
+ </p><p>
+ This command adds the <code class="literal">user.postgres</code> project and
+ sets the shared memory maximum for the <code class="literal">postgres</code>
+ user to 8GB, and takes effect the next time that user logs
+ in, or when you restart <span class="productname">PostgreSQL</span> (not reload).
+ The above assumes that <span class="productname">PostgreSQL</span> is run by
+ the <code class="literal">postgres</code> user in the <code class="literal">postgres</code>
+ group. No server reboot is required.
+ </p><p>
+ Other recommended kernel setting changes for database servers which will
+ have a large number of connections are:
+</p><pre class="programlisting">
+project.max-shm-ids=(priv,32768,deny)
+project.max-sem-ids=(priv,4096,deny)
+project.max-msg-ids=(priv,4096,deny)
+</pre><p>
+ </p><p>
+ Additionally, if you are running <span class="productname">PostgreSQL</span>
+ inside a zone, you may need to raise the zone resource usage
+ limits as well. See "Chapter2: Projects and Tasks" in the
+ <em class="citetitle">System Administrator's Guide</em> for more
+ information on <code class="literal">projects</code> and <code class="command">prctl</code>.
+ </p></dd></dl></div></div><div class="sect2" id="SYSTEMD-REMOVEIPC"><div class="titlepage"><div><div><h3 class="title">19.4.2. systemd RemoveIPC</h3></div></div></div><a id="id-1.6.6.7.4.2" class="indexterm"></a><p>
+ If <span class="productname">systemd</span> is in use, some care must be taken
+ that IPC resources (including shared memory) are not prematurely
+ removed by the operating system. This is especially of concern when
+ installing PostgreSQL from source. Users of distribution packages of
+ PostgreSQL are less likely to be affected, as
+ the <code class="literal">postgres</code> user is then normally created as a system
+ user.
+ </p><p>
+ The setting <code class="literal">RemoveIPC</code>
+ in <code class="filename">logind.conf</code> controls whether IPC objects are
+ removed when a user fully logs out. System users are exempt. This
+ setting defaults to on in stock <span class="productname">systemd</span>, but
+ some operating system distributions default it to off.
+ </p><p>
+ A typical observed effect when this setting is on is that shared memory
+ objects used for parallel query execution are removed at apparently random
+ times, leading to errors and warnings while attempting to open and remove
+ them, like
+</p><pre class="screen">
+WARNING: could not remove shared memory segment "/PostgreSQL.1450751626": No such file or directory
+</pre><p>
+ Different types of IPC objects (shared memory vs. semaphores, System V
+ vs. POSIX) are treated slightly differently
+ by <span class="productname">systemd</span>, so one might observe that some IPC
+ resources are not removed in the same way as others. But it is not
+ advisable to rely on these subtle differences.
+ </p><p>
+ A <span class="quote">“<span class="quote">user logging out</span>”</span> might happen as part of a maintenance
+ job or manually when an administrator logs in as
+ the <code class="literal">postgres</code> user or something similar, so it is hard
+ to prevent in general.
+ </p><p>
+ What is a <span class="quote">“<span class="quote">system user</span>”</span> is determined
+ at <span class="productname">systemd</span> compile time from
+ the <code class="symbol">SYS_UID_MAX</code> setting
+ in <code class="filename">/etc/login.defs</code>.
+ </p><p>
+ Packaging and deployment scripts should be careful to create
+ the <code class="literal">postgres</code> user as a system user by
+ using <code class="literal">useradd -r</code>, <code class="literal">adduser --system</code>,
+ or equivalent.
+ </p><p>
+ Alternatively, if the user account was created incorrectly or cannot be
+ changed, it is recommended to set
+</p><pre class="programlisting">
+RemoveIPC=no
+</pre><p>
+ in <code class="filename">/etc/systemd/logind.conf</code> or another appropriate
+ configuration file.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ At least one of these two things has to be ensured, or the PostgreSQL
+ server will be very unreliable.
+ </p></div></div><div class="sect2" id="id-1.6.6.7.5"><div class="titlepage"><div><div><h3 class="title">19.4.3. Resource Limits</h3></div></div></div><p>
+ Unix-like operating systems enforce various kinds of resource limits
+ that might interfere with the operation of your
+ <span class="productname">PostgreSQL</span> server. Of particular
+ importance are limits on the number of processes per user, the
+ number of open files per process, and the amount of memory available
+ to each process. Each of these have a <span class="quote">“<span class="quote">hard</span>”</span> and a
+ <span class="quote">“<span class="quote">soft</span>”</span> limit. The soft limit is what actually counts
+ but it can be changed by the user up to the hard limit. The hard
+ limit can only be changed by the root user. The system call
+ <code class="function">setrlimit</code> is responsible for setting these
+ parameters. The shell's built-in command <code class="command">ulimit</code>
+ (Bourne shells) or <code class="command">limit</code> (<span class="application">csh</span>) is
+ used to control the resource limits from the command line. On
+ BSD-derived systems the file <code class="filename">/etc/login.conf</code>
+ controls the various resource limits set during login. See the
+ operating system documentation for details. The relevant
+ parameters are <code class="varname">maxproc</code>,
+ <code class="varname">openfiles</code>, and <code class="varname">datasize</code>. For
+ example:
+</p><pre class="programlisting">
+default:\
+...
+ :datasize-cur=256M:\
+ :maxproc-cur=256:\
+ :openfiles-cur=256:\
+...
+</pre><p>
+ (<code class="literal">-cur</code> is the soft limit. Append
+ <code class="literal">-max</code> to set the hard limit.)
+ </p><p>
+ Kernels can also have system-wide limits on some resources.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ On <span class="productname">Linux</span> the kernel parameter
+ <code class="varname">fs.file-max</code> determines the maximum number of open
+ files that the kernel will support. It can be changed with
+ <code class="literal">sysctl -w fs.file-max=<em class="replaceable"><code>N</code></em></code>.
+ To make the setting persist across reboots, add an assignment
+ in <code class="filename">/etc/sysctl.conf</code>.
+ The maximum limit of files per process is fixed at the time the
+ kernel is compiled; see
+ <code class="filename">/usr/src/linux/Documentation/proc.txt</code> for
+ more information.
+ </p></li></ul></div><p>
+ </p><p>
+ The <span class="productname">PostgreSQL</span> server uses one process
+ per connection so you should provide for at least as many processes
+ as allowed connections, in addition to what you need for the rest
+ of your system. This is usually not a problem but if you run
+ several servers on one machine things might get tight.
+ </p><p>
+ The factory default limit on open files is often set to
+ <span class="quote">“<span class="quote">socially friendly</span>”</span> values that allow many users to
+ coexist on a machine without using an inappropriate fraction of
+ the system resources. If you run many servers on a machine this
+ is perhaps what you want, but on dedicated servers you might want to
+ raise this limit.
+ </p><p>
+ On the other side of the coin, some systems allow individual
+ processes to open large numbers of files; if more than a few
+ processes do so then the system-wide limit can easily be exceeded.
+ If you find this happening, and you do not want to alter the
+ system-wide limit, you can set <span class="productname">PostgreSQL</span>'s <a class="xref" href="runtime-config-resource.html#GUC-MAX-FILES-PER-PROCESS">max_files_per_process</a> configuration parameter to
+ limit the consumption of open files.
+ </p><p>
+ Another kernel limit that may be of concern when supporting large
+ numbers of client connections is the maximum socket connection queue
+ length. If more than that many connection requests arrive within a very
+ short period, some may get rejected before the postmaster can service
+ the requests, with those clients receiving unhelpful connection failure
+ errors such as <span class="quote">“<span class="quote">Resource temporarily unavailable</span>”</span> or
+ <span class="quote">“<span class="quote">Connection refused</span>”</span>. The default queue length limit is 128
+ on many platforms. To raise it, adjust the appropriate kernel parameter
+ via <span class="application">sysctl</span>, then restart the postmaster.
+ The parameter is variously named <code class="varname">net.core.somaxconn</code>
+ on Linux, <code class="varname">kern.ipc.soacceptqueue</code> on newer FreeBSD,
+ and <code class="varname">kern.ipc.somaxconn</code> on macOS and other BSD
+ variants.
+ </p></div><div class="sect2" id="LINUX-MEMORY-OVERCOMMIT"><div class="titlepage"><div><div><h3 class="title">19.4.4. Linux Memory Overcommit</h3></div></div></div><a id="id-1.6.6.7.6.2" class="indexterm"></a><a id="id-1.6.6.7.6.3" class="indexterm"></a><a id="id-1.6.6.7.6.4" class="indexterm"></a><p>
+ The default virtual memory behavior on Linux is not
+ optimal for <span class="productname">PostgreSQL</span>. Because of the
+ way that the kernel implements memory overcommit, the kernel might
+ terminate the <span class="productname">PostgreSQL</span> postmaster (the
+ supervisor server process) if the memory demands of either
+ <span class="productname">PostgreSQL</span> or another process cause the
+ system to run out of virtual memory.
+ </p><p>
+ If this happens, you will see a kernel message that looks like
+ this (consult your system documentation and configuration on where
+ to look for such a message):
+</p><pre class="programlisting">
+Out of Memory: Killed process 12345 (postgres).
+</pre><p>
+ This indicates that the <code class="filename">postgres</code> process
+ has been terminated due to memory pressure.
+ Although existing database connections will continue to function
+ normally, no new connections will be accepted. To recover,
+ <span class="productname">PostgreSQL</span> will need to be restarted.
+ </p><p>
+ One way to avoid this problem is to run
+ <span class="productname">PostgreSQL</span> on a machine where you can
+ be sure that other processes will not run the machine out of
+ memory. If memory is tight, increasing the swap space of the
+ operating system can help avoid the problem, because the
+ out-of-memory (OOM) killer is invoked only when physical memory and
+ swap space are exhausted.
+ </p><p>
+ If <span class="productname">PostgreSQL</span> itself is the cause of the
+ system running out of memory, you can avoid the problem by changing
+ your configuration. In some cases, it may help to lower memory-related
+ configuration parameters, particularly
+ <a class="link" href="runtime-config-resource.html#GUC-SHARED-BUFFERS"><code class="varname">shared_buffers</code></a>,
+ <a class="link" href="runtime-config-resource.html#GUC-WORK-MEM"><code class="varname">work_mem</code></a>, and
+ <a class="link" href="runtime-config-resource.html#GUC-HASH-MEM-MULTIPLIER"><code class="varname">hash_mem_multiplier</code></a>.
+ In other cases, the problem may be caused by allowing too many
+ connections to the database server itself. In many cases, it may
+ be better to reduce
+ <a class="link" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS"><code class="varname">max_connections</code></a>
+ and instead make use of external connection-pooling software.
+ </p><p>
+ It is possible to modify the
+ kernel's behavior so that it will not <span class="quote">“<span class="quote">overcommit</span>”</span> memory.
+ Although this setting will not prevent the <a class="ulink" href="https://lwn.net/Articles/104179/" target="_top">OOM killer</a> from being invoked
+ altogether, it will lower the chances significantly and will therefore
+ lead to more robust system behavior. This is done by selecting strict
+ overcommit mode via <code class="command">sysctl</code>:
+</p><pre class="programlisting">
+sysctl -w vm.overcommit_memory=2
+</pre><p>
+ or placing an equivalent entry in <code class="filename">/etc/sysctl.conf</code>.
+ You might also wish to modify the related setting
+ <code class="varname">vm.overcommit_ratio</code>. For details see the kernel documentation
+ file <a class="ulink" href="https://www.kernel.org/doc/Documentation/vm/overcommit-accounting" target="_top">https://www.kernel.org/doc/Documentation/vm/overcommit-accounting</a>.
+ </p><p>
+ Another approach, which can be used with or without altering
+ <code class="varname">vm.overcommit_memory</code>, is to set the process-specific
+ <em class="firstterm">OOM score adjustment</em> value for the postmaster process to
+ <code class="literal">-1000</code>, thereby guaranteeing it will not be targeted by the OOM
+ killer. The simplest way to do this is to execute
+</p><pre class="programlisting">
+echo -1000 &gt; /proc/self/oom_score_adj
+</pre><p>
+ in the postmaster's startup script just before invoking the postmaster.
+ Note that this action must be done as root, or it will have no effect;
+ so a root-owned startup script is the easiest place to do it. If you
+ do this, you should also set these environment variables in the startup
+ script before invoking the postmaster:
+</p><pre class="programlisting">
+export PG_OOM_ADJUST_FILE=/proc/self/oom_score_adj
+export PG_OOM_ADJUST_VALUE=0
+</pre><p>
+ These settings will cause postmaster child processes to run with the
+ normal OOM score adjustment of zero, so that the OOM killer can still
+ target them at need. You could use some other value for
+ <code class="envar">PG_OOM_ADJUST_VALUE</code> if you want the child processes to run
+ with some other OOM score adjustment. (<code class="envar">PG_OOM_ADJUST_VALUE</code>
+ can also be omitted, in which case it defaults to zero.) If you do not
+ set <code class="envar">PG_OOM_ADJUST_FILE</code>, the child processes will run with the
+ same OOM score adjustment as the postmaster, which is unwise since the
+ whole point is to ensure that the postmaster has a preferential setting.
+ </p></div><div class="sect2" id="LINUX-HUGE-PAGES"><div class="titlepage"><div><div><h3 class="title">19.4.5. Linux Huge Pages</h3></div></div></div><p>
+ Using huge pages reduces overhead when using large contiguous chunks of
+ memory, as <span class="productname">PostgreSQL</span> does, particularly when
+ using large values of <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>. To use this
+ feature in <span class="productname">PostgreSQL</span> you need a kernel
+ with <code class="varname">CONFIG_HUGETLBFS=y</code> and
+ <code class="varname">CONFIG_HUGETLB_PAGE=y</code>. You will also have to configure
+ the operating system to provide enough huge pages of the desired size.
+ To determine the number of huge pages needed, use the
+ <code class="command">postgres</code> command to see the value of
+ <a class="xref" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE-IN-HUGE-PAGES">shared_memory_size_in_huge_pages</a>. Note that the
+ server must be shut down to view this runtime-computed parameter.
+ This might look like:
+</p><pre class="programlisting">
+$ <strong class="userinput"><code>postgres -D $PGDATA -C shared_memory_size_in_huge_pages</code></strong>
+3170
+$ <strong class="userinput"><code>grep ^Hugepagesize /proc/meminfo</code></strong>
+Hugepagesize: 2048 kB
+$ <strong class="userinput"><code>ls /sys/kernel/mm/hugepages</code></strong>
+hugepages-1048576kB hugepages-2048kB
+</pre><p>
+
+ In this example the default is 2MB, but you can also explicitly request
+ either 2MB or 1GB with <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGE-SIZE">huge_page_size</a> to adapt
+ the number of pages calculated by
+ <code class="varname">shared_memory_size_in_huge_pages</code>.
+
+ While we need at least <code class="literal">3170</code> huge pages in this example,
+ a larger setting would be appropriate if other programs on the machine
+ also need huge pages.
+ We can set this with:
+</p><pre class="programlisting">
+# <strong class="userinput"><code>sysctl -w vm.nr_hugepages=3170</code></strong>
+</pre><p>
+ Don't forget to add this setting to <code class="filename">/etc/sysctl.conf</code>
+ so that it is reapplied after reboots. For non-default huge page sizes,
+ we can instead use:
+</p><pre class="programlisting">
+# <strong class="userinput"><code>echo 3170 &gt; /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</code></strong>
+</pre><p>
+ It is also possible to provide these settings at boot time using
+ kernel parameters such as <code class="literal">hugepagesz=2M hugepages=3170</code>.
+ </p><p>
+ Sometimes the kernel is not able to allocate the desired number of huge
+ pages immediately due to fragmentation, so it might be necessary
+ to repeat the command or to reboot. (Immediately after a reboot, most of
+ the machine's memory should be available to convert into huge pages.)
+ To verify the huge page allocation situation for a given size, use:
+</p><pre class="programlisting">
+$ <strong class="userinput"><code>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</code></strong>
+</pre><p>
+ </p><p>
+ It may also be necessary to give the database server's operating system
+ user permission to use huge pages by setting
+ <code class="varname">vm.hugetlb_shm_group</code> via <span class="application">sysctl</span>, and/or
+ give permission to lock memory with <code class="command">ulimit -l</code>.
+ </p><p>
+ The default behavior for huge pages in
+ <span class="productname">PostgreSQL</span> is to use them when possible, with
+ the system's default huge page size, and
+ to fall back to normal pages on failure. To enforce the use of huge
+ pages, you can set <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGES">huge_pages</a>
+ to <code class="literal">on</code> in <code class="filename">postgresql.conf</code>.
+ Note that with this setting <span class="productname">PostgreSQL</span> will fail to
+ start if not enough huge pages are available.
+ </p><p>
+ For a detailed description of the <span class="productname">Linux</span> huge
+ pages feature have a look
+ at <a class="ulink" href="https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt" target="_top">https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server-start.html" title="19.3. Starting the Database Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="server-shutdown.html" title="19.5. Shutting Down the Server">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.3. Starting the Database Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.5. Shutting Down the Server</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/largeobjects.html b/doc/src/sgml/html/largeobjects.html
new file mode 100644
index 0000000..a6a60b4
--- /dev/null
+++ b/doc/src/sgml/html/largeobjects.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 35. Large Objects</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-example.html" title="34.22. Example Programs" /><link rel="next" href="lo-intro.html" title="35.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 35. Large Objects</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-example.html" title="34.22. Example Programs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><th width="60%" align="center">Part IV. Client Interfaces</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-intro.html" title="35.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="LARGEOBJECTS"><div class="titlepage"><div><div><h2 class="title">Chapter 35. Large Objects</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="lo-intro.html">35.1. Introduction</a></span></dt><dt><span class="sect1"><a href="lo-implementation.html">35.2. Implementation Features</a></span></dt><dt><span class="sect1"><a href="lo-interfaces.html">35.3. Client Interfaces</a></span></dt><dd><dl><dt><span class="sect2"><a href="lo-interfaces.html#LO-CREATE">35.3.1. Creating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-IMPORT">35.3.2. Importing a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-EXPORT">35.3.3. Exporting a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-OPEN">35.3.4. Opening an Existing Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-WRITE">35.3.5. Writing Data to a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-READ">35.3.6. Reading Data from a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-SEEK">35.3.7. Seeking in a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TELL">35.3.8. Obtaining the Seek Position of a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TRUNCATE">35.3.9. Truncating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-CLOSE">35.3.10. Closing a Large Object Descriptor</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-UNLINK">35.3.11. Removing a Large Object</a></span></dt></dl></dd><dt><span class="sect1"><a href="lo-funcs.html">35.4. Server-Side Functions</a></span></dt><dt><span class="sect1"><a href="lo-examplesect.html">35.5. Example Program</a></span></dt></dl></div><a id="id-1.7.4.2" class="indexterm"></a><a id="id-1.7.4.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> has a <em class="firstterm">large object</em>
+ facility, which provides stream-style access to user data that is stored
+ in a special large-object structure. Streaming access is useful
+ when working with data values that are too large to manipulate
+ conveniently as a whole.
+ </p><p>
+ This chapter describes the implementation and the programming and
+ query language interfaces to <span class="productname">PostgreSQL</span>
+ large object data. We use the <span class="application">libpq</span> C
+ library for the examples in this chapter, but most programming
+ interfaces native to <span class="productname">PostgreSQL</span> support
+ equivalent functionality. Other interfaces might use the large
+ object interface internally to provide generic support for large
+ values. This is not described here.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-example.html" title="34.22. Example Programs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-intro.html" title="35.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.22. Example Programs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/legalnotice.html b/doc/src/sgml/html/legalnotice.html
new file mode 100644
index 0000000..8fec481
--- /dev/null
+++ b/doc/src/sgml/html/legalnotice.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Legal Notice</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body id="docContent" class="container-fluid col-10"><div class="legalnotice" id="LEGALNOTICE"><p class="legalnotice-title"><strong>Legal Notice</strong></p><p>
+ <span class="productname">PostgreSQL</span> is Copyright © 1996–2023
+ by the PostgreSQL Global Development Group.
+ </p><p>
+ <span class="productname">Postgres95</span> is Copyright © 1994–5
+ by the Regents of the University of California.
+ </p><p>
+ Permission to use, copy, modify, and distribute this software and
+ its documentation for any purpose, without fee, and without a
+ written agreement is hereby granted, provided that the above
+ copyright notice and this paragraph and the following two paragraphs
+ appear in all copies.
+ </p><p>
+ IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
+ PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
+ DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS
+ SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
+ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ </p><p>
+ THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+ INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
+ PROVIDED HEREUNDER IS ON AN <span class="quote">“<span class="quote">AS-IS</span>”</span> BASIS, AND THE UNIVERSITY OF
+ CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
+ UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+ </p></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-async.html b/doc/src/sgml/html/libpq-async.html
new file mode 100644
index 0000000..2a07108
--- /dev/null
+++ b/doc/src/sgml/html/libpq-async.html
@@ -0,0 +1,337 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.4. Asynchronous Command Processing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-exec.html" title="34.3. Command Execution Functions" /><link rel="next" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.4. Asynchronous Command Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-exec.html" title="34.3. Command Execution Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-ASYNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.4. Asynchronous Command Processing</h2></div></div></div><a id="id-1.7.3.11.2" class="indexterm"></a><p>
+ The <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> function is adequate for submitting
+ commands in normal, synchronous applications. It has a few
+ deficiencies, however, that can be of importance to some users:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> waits for the command to be completed.
+ The application might have other work to do (such as maintaining a
+ user interface), in which case it won't want to block waiting for
+ the response.
+ </p></li><li class="listitem"><p>
+ Since the execution of the client application is suspended while it
+ waits for the result, it is hard for the application to decide that
+ it would like to try to cancel the ongoing command. (It can be done
+ from a signal handler, but not otherwise.)
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> can return only one
+ <code class="structname">PGresult</code> structure. If the submitted command
+ string contains multiple <acronym class="acronym">SQL</acronym> commands, all but
+ the last <code class="structname">PGresult</code> are discarded by
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> always collects the command's entire result,
+ buffering it in a single <code class="structname">PGresult</code>. While
+ this simplifies error-handling logic for the application, it can be
+ impractical for results containing many rows.
+ </p></li></ul></div><p>
+ </p><p>
+ Applications that do not like these limitations can instead use the
+ underlying functions that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> is built from:
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.
+ There are also
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>, and
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>,
+ which can be used with <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to duplicate
+ the functionality of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>, and
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>
+ respectively.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSENDQUERY"><span class="term"><code class="function">PQsendQuery</code><a id="id-1.7.3.11.4.15.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a command to the server without waiting for the result(s).
+ 1 is returned if the command was successfully dispatched and 0 if
+ not (in which case, use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more
+ information about the failure).
+</p><pre class="synopsis">
+int PQsendQuery(PGconn *conn, const char *command);
+</pre><p>
+
+ After successfully calling <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> one or more times to obtain the
+ results. <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> cannot be called again
+ (on the same connection) until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
+ has returned a null pointer, indicating that the command is done.
+ </p><p>
+ In pipeline mode, this function is disallowed.
+ </p></dd><dt id="LIBPQ-PQSENDQUERYPARAMS"><span class="term"><code class="function">PQsendQueryParams</code><a id="id-1.7.3.11.4.15.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a command and separate parameters to the server without
+ waiting for the result(s).
+</p><pre class="synopsis">
+int PQsendQueryParams(PGconn *conn,
+ const char *command,
+ int nParams,
+ const Oid *paramTypes,
+ const char * const *paramValues,
+ const int *paramLengths,
+ const int *paramFormats,
+ int resultFormat);
+</pre><p>
+
+ This is equivalent to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> except that
+ query parameters can be specified separately from the query string.
+ The function's parameters are handled identically to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>. Like
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, it allows only one command in the
+ query string.
+ </p></dd><dt id="LIBPQ-PQSENDPREPARE"><span class="term"><code class="function">PQsendPrepare</code><a id="id-1.7.3.11.4.15.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a request to create a prepared statement with the given
+ parameters, without waiting for completion.
+</p><pre class="synopsis">
+int PQsendPrepare(PGconn *conn,
+ const char *stmtName,
+ const char *query,
+ int nParams,
+ const Oid *paramTypes);
+</pre><p>
+
+ This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>: it
+ returns 1 if it was able to dispatch the request, and 0 if not.
+ After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
+ determine whether the server successfully created the prepared
+ statement. The function's parameters are handled identically to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>.
+ </p></dd><dt id="LIBPQ-PQSENDQUERYPREPARED"><span class="term"><code class="function">PQsendQueryPrepared</code><a id="id-1.7.3.11.4.15.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a request to execute a prepared statement with given
+ parameters, without waiting for the result(s).
+</p><pre class="synopsis">
+int PQsendQueryPrepared(PGconn *conn,
+ const char *stmtName,
+ int nParams,
+ const char * const *paramValues,
+ const int *paramLengths,
+ const int *paramFormats,
+ int resultFormat);
+</pre><p>
+
+ This is similar to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, but
+ the command to be executed is specified by naming a
+ previously-prepared statement, instead of giving a query string.
+ The function's parameters are handled identically to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>.
+ </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPREPARED"><span class="term"><code class="function">PQsendDescribePrepared</code><a id="id-1.7.3.11.4.15.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a request to obtain information about the specified
+ prepared statement, without waiting for completion.
+</p><pre class="synopsis">
+int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
+</pre><p>
+
+ This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>:
+ it returns 1 if it was able to dispatch the request, and 0 if not.
+ After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
+ obtain the results. The function's parameters are handled
+ identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>.
+ </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPORTAL"><span class="term"><code class="function">PQsendDescribePortal</code><a id="id-1.7.3.11.4.15.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a request to obtain information about the specified
+ portal, without waiting for completion.
+</p><pre class="synopsis">
+int PQsendDescribePortal(PGconn *conn, const char *portalName);
+</pre><p>
+
+ This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>:
+ it returns 1 if it was able to dispatch the request, and 0 if not.
+ After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
+ obtain the results. The function's parameters are handled
+ identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>.
+ </p></dd><dt id="LIBPQ-PQGETRESULT"><span class="term"><code class="function">PQgetResult</code><a id="id-1.7.3.11.4.15.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Waits for the next result from a prior
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>, or
+ <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a>
+ call, and returns it.
+ A null pointer is returned when the command is complete and there
+ will be no more results.
+</p><pre class="synopsis">
+PGresult *PQgetResult(PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> must be called repeatedly until
+ it returns a null pointer, indicating that the command is done.
+ (If called when no command is active,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will just return a null pointer
+ at once.) Each non-null result from
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be processed using the
+ same <code class="structname">PGresult</code> accessor functions previously
+ described. Don't forget to free each result object with
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when done with it. Note that
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will block only if a command is
+ active and the necessary response data has not yet been read by
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>.
+ </p><p>
+ In pipeline mode, <code class="function">PQgetResult</code> will return normally
+ unless an error occurs; for any subsequent query sent after the one
+ that caused the error until (and excluding) the next synchronization point,
+ a special result of type <code class="literal">PGRES_PIPELINE_ABORTED</code> will
+ be returned, and a null pointer will be returned after it.
+ When the pipeline synchronization point is reached, a result of type
+ <code class="literal">PGRES_PIPELINE_SYNC</code> will be returned.
+ The result of the next query after the synchronization point follows
+ immediately (that is, no null pointer is returned after
+ the synchronization point.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Even when <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> indicates a fatal
+ error, <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be called until it
+ returns a null pointer, to allow <span class="application">libpq</span> to
+ process the error information completely.
+ </p></div></dd></dl></div><p>
+ </p><p>
+ Using <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> solves one of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>'s problems: If a command string contains
+ multiple <acronym class="acronym">SQL</acronym> commands, the results of those commands
+ can be obtained individually. (This allows a simple form of overlapped
+ processing, by the way: the client can be handling the results of one
+ command while the server is still working on later queries in the same
+ command string.)
+ </p><p>
+ Another frequently-desired feature that can be obtained with
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
+ is retrieving large query results a row at a time. This is discussed
+ in <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>.
+ </p><p>
+ By itself, calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
+ will still cause the client to block until the server completes the
+ next <acronym class="acronym">SQL</acronym> command. This can be avoided by proper
+ use of two more functions:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONSUMEINPUT"><span class="term"><code class="function">PQconsumeInput</code><a id="id-1.7.3.11.7.3.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ If input is available from the server, consume it.
+</p><pre class="synopsis">
+int PQconsumeInput(PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> normally returns 1 indicating
+ <span class="quote">“<span class="quote">no error</span>”</span>, but returns 0 if there was some kind of
+ trouble (in which case <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> can be
+ consulted). Note that the result does not say whether any input
+ data was actually collected. After calling
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>, the application can check
+ <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> and/or
+ <code class="function">PQnotifies</code> to see if their state has changed.
+ </p><p>
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> can be called even if the
+ application is not prepared to deal with a result or notification
+ just yet. The function will read available data and save it in
+ a buffer, thereby causing a <code class="function">select()</code>
+ read-ready indication to go away. The application can thus use
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> to clear the
+ <code class="function">select()</code> condition immediately, and then
+ examine the results at leisure.
+ </p></dd><dt id="LIBPQ-PQISBUSY"><span class="term"><code class="function">PQisBusy</code><a id="id-1.7.3.11.7.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns 1 if a command is busy, that is,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> would block waiting for input.
+ A 0 return indicates that <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> can be
+ called with assurance of not blocking.
+</p><pre class="synopsis">
+int PQisBusy(PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> will not itself attempt to read data
+ from the server; therefore <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>
+ must be invoked first, or the busy state will never end.
+ </p></dd></dl></div><p>
+ </p><p>
+ A typical application using these functions will have a main loop that
+ uses <code class="function">select()</code> or <code class="function">poll()</code> to wait for
+ all the conditions that it must respond to. One of the conditions
+ will be input available from the server, which in terms of
+ <code class="function">select()</code> means readable data on the file
+ descriptor identified by <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>. When the main
+ loop detects input ready, it should call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> to read the input. It can then
+ call <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>, followed by
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> if <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>
+ returns false (0). It can also call <code class="function">PQnotifies</code>
+ to detect <code class="command">NOTIFY</code> messages (see <a class="xref" href="libpq-notify.html" title="34.9. Asynchronous Notification">Section 34.9</a>).
+ </p><p>
+ A client that uses
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>/<a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
+ can also attempt to cancel a command that is still being processed
+ by the server; see <a class="xref" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Section 34.7</a>. But regardless of
+ the return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>, the application
+ must continue with the normal result-reading sequence using
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>. A successful cancellation will
+ simply cause the command to terminate sooner than it would have
+ otherwise.
+ </p><p>
+ By using the functions described above, it is possible to avoid
+ blocking while waiting for input from the database server. However,
+ it is still possible that the application will block waiting to send
+ output to the server. This is relatively uncommon but can happen if
+ very long SQL commands or data values are sent. (It is much more
+ probable if the application sends data via <code class="command">COPY IN</code>,
+ however.) To prevent this possibility and achieve completely
+ nonblocking database operation, the following additional functions
+ can be used.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETNONBLOCKING"><span class="term"><code class="function">PQsetnonblocking</code><a id="id-1.7.3.11.10.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets the nonblocking status of the connection.
+</p><pre class="synopsis">
+int PQsetnonblocking(PGconn *conn, int arg);
+</pre><p>
+ </p><p>
+ Sets the state of the connection to nonblocking if
+ <em class="parameter"><code>arg</code></em> is 1, or blocking if
+ <em class="parameter"><code>arg</code></em> is 0. Returns 0 if OK, -1 if error.
+ </p><p>
+ In the nonblocking state, calls to
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a>,
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTNBYTES"><code class="function">PQputnbytes</code></a>, <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYDATA"><code class="function">PQputCopyData</code></a>,
+ and <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> will not block but instead return
+ an error if they need to be called again.
+ </p><p>
+ Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> does not honor nonblocking
+ mode; if it is called, it will act in blocking fashion anyway.
+ </p></dd><dt id="LIBPQ-PQISNONBLOCKING"><span class="term"><code class="function">PQisnonblocking</code><a id="id-1.7.3.11.10.2.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the blocking status of the database connection.
+</p><pre class="synopsis">
+int PQisnonblocking(const PGconn *conn);
+</pre><p>
+ </p><p>
+ Returns 1 if the connection is set to nonblocking mode and 0 if
+ blocking.
+ </p></dd><dt id="LIBPQ-PQFLUSH"><span class="term"><code class="function">PQflush</code><a id="id-1.7.3.11.10.2.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Attempts to flush any queued output data to the server. Returns
+ 0 if successful (or if the send queue is empty), -1 if it failed
+ for some reason, or 1 if it was unable to send all the data in
+ the send queue yet (this case can only occur if the connection
+ is nonblocking).
+</p><pre class="synopsis">
+int PQflush(PGconn *conn);
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ After sending any command or data on a nonblocking connection, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>. If it returns 1, wait for the socket
+ to become read- or write-ready. If it becomes write-ready, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again. If it becomes read-ready, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>, then call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again. Repeat until
+ <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0. (It is necessary to check for
+ read-ready and drain the input with <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>,
+ because the server can block trying to send us data, e.g., NOTICE
+ messages, and won't read our data until we read its.) Once
+ <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0, wait for the socket to be
+ read-ready and then read the response as described above.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-exec.html" title="34.3. Command Execution Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.3. Command Execution Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.5. Pipeline Mode</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-build.html b/doc/src/sgml/html/libpq-build.html
new file mode 100644
index 0000000..fc0018c
--- /dev/null
+++ b/doc/src/sgml/html/libpq-build.html
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.21. Building libpq Programs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs" /><link rel="next" href="libpq-example.html" title="34.22. Example Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.21. Building <span class="application">libpq</span> Programs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-example.html" title="34.22. Example Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-BUILD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.21. Building <span class="application">libpq</span> Programs</h2></div></div></div><a id="id-1.7.3.28.2" class="indexterm"></a><p>
+ To build (i.e., compile and link) a program using
+ <span class="application">libpq</span> you need to do all of the following
+ things:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Include the <code class="filename">libpq-fe.h</code> header file:
+</p><pre class="programlisting">
+#include &lt;libpq-fe.h&gt;
+</pre><p>
+ If you failed to do that then you will normally get error messages
+ from your compiler similar to:
+</p><pre class="screen">
+foo.c: In function `main':
+foo.c:34: `PGconn' undeclared (first use in this function)
+foo.c:35: `PGresult' undeclared (first use in this function)
+foo.c:54: `CONNECTION_BAD' undeclared (first use in this function)
+foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function)
+foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function)
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Point your compiler to the directory where the <span class="productname">PostgreSQL</span> header
+ files were installed, by supplying the
+ <code class="literal">-I<em class="replaceable"><code>directory</code></em></code> option
+ to your compiler. (In some cases the compiler will look into
+ the directory in question by default, so you can omit this
+ option.) For instance, your compile command line could look
+ like:
+</p><pre class="programlisting">
+cc -c -I/usr/local/pgsql/include testprog.c
+</pre><p>
+ If you are using makefiles then add the option to the
+ <code class="varname">CPPFLAGS</code> variable:
+</p><pre class="programlisting">
+CPPFLAGS += -I/usr/local/pgsql/include
+</pre><p>
+ </p><p>
+ If there is any chance that your program might be compiled by
+ other users then you should not hardcode the directory location
+ like that. Instead, you can run the utility
+ <code class="command">pg_config</code><a id="id-1.7.3.28.3.2.2.2.2" class="indexterm"></a> to find out where the header
+ files are on the local system:
+</p><pre class="screen">
+<code class="prompt">$</code> pg_config --includedir
+<code class="computeroutput">/usr/local/include</code>
+</pre><p>
+ </p><p>
+ If you
+ have <code class="command">pkg-config</code><a id="id-1.7.3.28.3.2.2.3.2" class="indexterm"></a> installed, you can run instead:
+</p><pre class="screen">
+<code class="prompt">$</code> pkg-config --cflags libpq
+<code class="computeroutput">-I/usr/local/include</code>
+</pre><p>
+ Note that this will already include the <code class="option">-I</code> in front of
+ the path.
+ </p><p>
+ Failure to specify the correct option to the compiler will
+ result in an error message such as:
+</p><pre class="screen">
+testlibpq.c:8:22: libpq-fe.h: No such file or directory
+</pre><p>
+ </p></li><li class="listitem"><p>
+ When linking the final program, specify the option
+ <code class="literal">-lpq</code> so that the <span class="application">libpq</span>
+ library gets pulled in, as well as the option
+ <code class="literal">-L<em class="replaceable"><code>directory</code></em></code> to point
+ the compiler to the directory where the
+ <span class="application">libpq</span> library resides. (Again, the
+ compiler will search some directories by default.) For maximum
+ portability, put the <code class="option">-L</code> option before the
+ <code class="option">-lpq</code> option. For example:
+</p><pre class="programlisting">
+cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
+</pre><p>
+ </p><p>
+ You can find out the library directory using
+ <code class="command">pg_config</code> as well:
+</p><pre class="screen">
+<code class="prompt">$</code> pg_config --libdir
+<code class="computeroutput">/usr/local/pgsql/lib</code>
+</pre><p>
+ </p><p>
+ Or again use <code class="command">pkg-config</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> pkg-config --libs libpq
+<code class="computeroutput">-L/usr/local/pgsql/lib -lpq</code>
+</pre><p>
+ Note again that this prints the full options, not only the path.
+ </p><p>
+ Error messages that point to problems in this area could look like
+ the following:
+</p><pre class="screen">
+testlibpq.o: In function `main':
+testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin'
+testlibpq.o(.text+0x71): undefined reference to `PQstatus'
+testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
+</pre><p>
+ This means you forgot <code class="option">-lpq</code>.
+</p><pre class="screen">
+/usr/bin/ld: cannot find -lpq
+</pre><p>
+ This means you forgot the <code class="option">-L</code> option or did not
+ specify the right directory.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-example.html" title="34.22. Example Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.20. Behavior in Threaded Programs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.22. Example Programs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-cancel.html b/doc/src/sgml/html/libpq-cancel.html
new file mode 100644
index 0000000..56bb7ae
--- /dev/null
+++ b/doc/src/sgml/html/libpq-cancel.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.7. Canceling Queries in Progress</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row" /><link rel="next" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.7. Canceling Queries in Progress</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CANCEL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.7. Canceling Queries in Progress</h2></div></div></div><a id="id-1.7.3.14.2" class="indexterm"></a><p>
+ A client application can request cancellation of a command that is
+ still being processed by the server, using the functions described in
+ this section.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETCANCEL"><span class="term"><code class="function">PQgetCancel</code><a id="id-1.7.3.14.3.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Creates a data structure containing the information needed to cancel
+ a command issued through a particular database connection.
+</p><pre class="synopsis">
+PGcancel *PQgetCancel(PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a> creates a
+ <code class="structname">PGcancel</code><a id="id-1.7.3.14.3.1.1.2.2.3" class="indexterm"></a> object
+ given a <code class="structname">PGconn</code> connection object. It will return
+ <code class="symbol">NULL</code> if the given <em class="parameter"><code>conn</code></em> is <code class="symbol">NULL</code> or an invalid
+ connection. The <code class="structname">PGcancel</code> object is an opaque
+ structure that is not meant to be accessed directly by the
+ application; it can only be passed to <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>
+ or <a class="xref" href="libpq-cancel.html#LIBPQ-PQFREECANCEL"><code class="function">PQfreeCancel</code></a>.
+ </p></dd><dt id="LIBPQ-PQFREECANCEL"><span class="term"><code class="function">PQfreeCancel</code><a id="id-1.7.3.14.3.1.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Frees a data structure created by <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a>.
+</p><pre class="synopsis">
+void PQfreeCancel(PGcancel *cancel);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-cancel.html#LIBPQ-PQFREECANCEL"><code class="function">PQfreeCancel</code></a> frees a data object previously created
+ by <a class="xref" href="libpq-cancel.html#LIBPQ-PQGETCANCEL"><code class="function">PQgetCancel</code></a>.
+ </p></dd><dt id="LIBPQ-PQCANCEL"><span class="term"><code class="function">PQcancel</code><a id="id-1.7.3.14.3.1.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Requests that the server abandon processing of the current command.
+</p><pre class="synopsis">
+int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
+</pre><p>
+ </p><p>
+ The return value is 1 if the cancel request was successfully
+ dispatched and 0 if not. If not, <em class="parameter"><code>errbuf</code></em> is filled
+ with an explanatory error message. <em class="parameter"><code>errbuf</code></em>
+ must be a char array of size <em class="parameter"><code>errbufsize</code></em> (the
+ recommended size is 256 bytes).
+ </p><p>
+ Successful dispatch is no guarantee that the request will have
+ any effect, however. If the cancellation is effective, the current
+ command will terminate early and return an error result. If the
+ cancellation fails (say, because the server was already done
+ processing the command), then there will be no visible result at
+ all.
+ </p><p>
+ <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> can safely be invoked from a signal
+ handler, if the <em class="parameter"><code>errbuf</code></em> is a local variable in the
+ signal handler. The <code class="structname">PGcancel</code> object is read-only
+ as far as <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a> is concerned, so it can
+ also be invoked from a thread that is separate from the one
+ manipulating the <code class="structname">PGconn</code> object.
+ </p></dd></dl></div><p>
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQREQUESTCANCEL"><span class="term"><code class="function">PQrequestCancel</code><a id="id-1.7.3.14.3.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a> is a deprecated variant of
+ <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>.
+</p><pre class="synopsis">
+int PQrequestCancel(PGconn *conn);
+</pre><p>
+ </p><p>
+ Requests that the server abandon processing of the current
+ command. It operates directly on the
+ <code class="structname">PGconn</code> object, and in case of failure stores the
+ error message in the <code class="structname">PGconn</code> object (whence it can
+ be retrieved by <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a>). Although
+ the functionality is the same, this approach is not safe within
+ multiple-thread programs or signal handlers, since it is possible
+ that overwriting the <code class="structname">PGconn</code>'s error message will
+ mess up the operation currently in progress on the connection.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.6. Retrieving Query Results Row-by-Row </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.8. The Fast-Path Interface</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-connect.html b/doc/src/sgml/html/libpq-connect.html
new file mode 100644
index 0000000..28df8d2
--- /dev/null
+++ b/doc/src/sgml/html/libpq-connect.html
@@ -0,0 +1,1134 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.1. Database Connection Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq.html" title="Chapter 34. libpq — C Library" /><link rel="next" href="libpq-status.html" title="34.2. Connection Status Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.1. Database Connection Control Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">34.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></span></dt></dl></div><p>
+ The following functions deal with making a connection to a
+ <span class="productname">PostgreSQL</span> backend server. An
+ application program can have several backend connections open at
+ one time. (One reason to do that is to access more than one
+ database.) Each connection is represented by a
+ <code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which
+ is obtained from the function <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>,
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, or
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>. Note that these functions will always
+ return a non-null object pointer, unless perhaps there is too
+ little memory even to allocate the <code class="structname">PGconn</code> object.
+ The <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a> function should be called to check
+ the return value for a successful connection before queries are sent
+ via the connection object.
+
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ If untrusted users have access to a database that has not adopted a
+ <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
+ begin each session by removing publicly-writable schemas from
+ <code class="varname">search_path</code>. One can set parameter key
+ word <code class="literal">options</code> to
+ value <code class="literal">-csearch_path=</code>. Alternately, one can
+ issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT
+ pg_catalog.set_config('search_path', '', false)")</code> after
+ connecting. This consideration is not specific
+ to <span class="application">libpq</span>; it applies to every interface for
+ executing arbitrary SQL commands.
+ </p></div><p>
+
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ On Unix, forking a process with open libpq connections can lead to
+ unpredictable results because the parent and child processes share
+ the same sockets and operating system resources. For this reason,
+ such usage is not recommended, though doing an <code class="function">exec</code> from
+ the child process to load a new executable is safe.
+ </p></div><p>
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONNECTDBPARAMS"><span class="term"><code class="function">PQconnectdbParams</code><a id="id-1.7.3.8.2.11.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Makes a new connection to the database server.
+
+</p><pre class="synopsis">
+PGconn *PQconnectdbParams(const char * const *keywords,
+ const char * const *values,
+ int expand_dbname);
+</pre><p>
+ </p><p>
+ This function opens a new database connection using the parameters taken
+ from two <code class="symbol">NULL</code>-terminated arrays. The first,
+ <code class="literal">keywords</code>, is defined as an array of strings, each one
+ being a key word. The second, <code class="literal">values</code>, gives the value
+ for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter
+ set can be extended without changing the function signature, so use of
+ this function (or its nonblocking analogs <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>
+ and <code class="function">PQconnectPoll</code>) is preferred for new application
+ programming.
+ </p><p>
+ The currently recognized parameter key words are listed in
+ <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.
+ </p><p>
+ The passed arrays can be empty to use all default parameters, or can
+ contain one or more parameter settings. They must be matched in length.
+ Processing will stop at the first <code class="symbol">NULL</code> entry
+ in the <code class="literal">keywords</code> array.
+ Also, if the <code class="literal">values</code> entry associated with a
+ non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is
+ <code class="symbol">NULL</code> or an empty string, that entry is ignored and
+ processing continues with the next pair of array entries.
+ </p><p>
+ When <code class="literal">expand_dbname</code> is non-zero, the value for
+ the first <em class="parameter"><code>dbname</code></em> key word is checked to see
+ if it is a <em class="firstterm">connection string</em>. If so, it
+ is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection
+ parameters extracted from the string. The value is considered to
+ be a connection string, rather than just a database name, if it
+ contains an equal sign (<code class="literal">=</code>) or it begins with a
+ URI scheme designator. (More details on connection string formats
+ appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.) Only the first
+ occurrence of <em class="parameter"><code>dbname</code></em> is treated in this way;
+ any subsequent <em class="parameter"><code>dbname</code></em> parameter is processed
+ as a plain database name.
+ </p><p>
+ In general the parameter arrays are processed from start to end.
+ If any key word is repeated, the last value (that is
+ not <code class="symbol">NULL</code> or empty) is used. This rule applies in
+ particular when a key word found in a connection string conflicts
+ with one appearing in the <code class="literal">keywords</code> array. Thus,
+ the programmer may determine whether array entries can override or
+ be overridden by values taken from a connection string. Array
+ entries appearing before an expanded <em class="parameter"><code>dbname</code></em>
+ entry can be overridden by fields of the connection string, and in
+ turn those fields are overridden by array entries appearing
+ after <em class="parameter"><code>dbname</code></em> (but, again, only if those
+ entries supply non-empty values).
+ </p><p>
+ After processing all the array entries and any expanded connection
+ string, any connection parameters that remain unset are filled with
+ default values. If an unset parameter's corresponding environment
+ variable (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>) is set, its value is
+ used. If the environment variable is not set either, then the
+ parameter's built-in default value is used.
+ </p></dd><dt id="LIBPQ-PQCONNECTDB"><span class="term"><code class="function">PQconnectdb</code><a id="id-1.7.3.8.2.11.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Makes a new connection to the database server.
+
+</p><pre class="synopsis">
+PGconn *PQconnectdb(const char *conninfo);
+</pre><p>
+ </p><p>
+ This function opens a new database connection using the parameters taken
+ from the string <code class="literal">conninfo</code>.
+ </p><p>
+ 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 <acronym class="acronym">URI</acronym>.
+ See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for details.
+ </p></dd><dt id="LIBPQ-PQSETDBLOGIN"><span class="term"><code class="function">PQsetdbLogin</code><a id="id-1.7.3.8.2.11.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Makes a new connection to the database server.
+</p><pre class="synopsis">
+PGconn *PQsetdbLogin(const char *pghost,
+ const char *pgport,
+ const char *pgoptions,
+ const char *pgtty,
+ const char *dbName,
+ const char *login,
+ const char *pwd);
+</pre><p>
+ </p><p>
+ This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed
+ set of parameters. It has the same functionality except that the
+ missing parameters will always take on default values. Write <code class="symbol">NULL</code> or an
+ empty string for any one of the fixed parameters that is to be defaulted.
+ </p><p>
+ If the <em class="parameter"><code>dbName</code></em> contains
+ an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it
+ is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as
+ if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining
+ parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
+ </p><p>
+ <code class="literal">pgtty</code> is no longer used and any value passed will
+ be ignored.
+ </p></dd><dt id="LIBPQ-PQSETDB"><span class="term"><code class="function">PQsetdb</code><a id="id-1.7.3.8.2.11.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Makes a new connection to the database server.
+</p><pre class="synopsis">
+PGconn *PQsetdb(char *pghost,
+ char *pgport,
+ char *pgoptions,
+ char *pgtty,
+ char *dbName);
+</pre><p>
+ </p><p>
+ This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers
+ for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters. It is provided
+ for backward compatibility with very old programs.
+ </p></dd><dt id="LIBPQ-PQCONNECTSTARTPARAMS"><span class="term"><code class="function">PQconnectStartParams</code><a id="id-1.7.3.8.2.11.5.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectStart</code><a id="id-1.7.3.8.2.11.5.2.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.11.5.3.2" class="indexterm"></a></span></dt><dd><p>
+ <a id="id-1.7.3.8.2.11.5.4.1.1" class="indexterm"></a>
+ Make a connection to the database server in a nonblocking manner.
+
+</p><pre class="synopsis">
+PGconn *PQconnectStartParams(const char * const *keywords,
+ const char * const *values,
+ int expand_dbname);
+
+PGconn *PQconnectStart(const char *conninfo);
+
+PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+</pre><p>
+ </p><p>
+ These three functions are used to open a connection to a database server such
+ that your application's thread of execution is not blocked on remote I/O
+ whilst doing so. The point of this approach is that the waits for I/O to
+ complete can occur in the application's main loop, rather than down inside
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and so the
+ application can manage this operation in parallel with other activities.
+ </p><p>
+ With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made
+ using the parameters taken from the <code class="literal">keywords</code> and
+ <code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>,
+ as described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
+ </p><p>
+ With <code class="function">PQconnectStart</code>, the database connection is made
+ using the parameters taken from the string <code class="literal">conninfo</code> as
+ described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
+ </p><p>
+ Neither <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> nor <code class="function">PQconnectStart</code>
+ nor <code class="function">PQconnectPoll</code> will block, so long as a number of
+ restrictions are met:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <code class="literal">hostaddr</code> parameter must be used appropriately
+ to prevent DNS queries from being made. See the documentation of
+ this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for details.
+ </p></li><li class="listitem"><p>
+ If you call <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>, ensure that the stream object
+ into which you trace will not block.
+ </p></li><li class="listitem"><p>
+ You must ensure that the socket is in the appropriate state
+ before calling <code class="function">PQconnectPoll</code>, as described below.
+ </p></li></ul></div><p>
+ </p><p>
+ To begin a nonblocking connection request,
+ call <code class="function">PQconnectStart</code>
+ or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>. If the result is null,
+ then <span class="application">libpq</span> has been unable to allocate a
+ new <code class="structname">PGconn</code> structure. Otherwise, a
+ valid <code class="structname">PGconn</code> pointer is returned (though not
+ yet representing a valid connection to the database). Next
+ call <code class="literal">PQstatus(conn)</code>. If the result
+ is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already
+ failed, typically because of invalid connection parameters.
+ </p><p>
+ If <code class="function">PQconnectStart</code>
+ or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> succeeds, the next stage
+ is to poll <span class="application">libpq</span> so that it can proceed with
+ the connection sequence.
+ Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the
+ socket underlying the database connection.
+ (Caution: do not assume that the socket remains the same
+ across <code class="function">PQconnectPoll</code> calls.)
+ Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned
+ <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to
+ read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or
+ similar system function).
+ Then call <code class="function">PQconnectPoll(conn)</code> again.
+ Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned
+ <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready
+ to write, then call <code class="function">PQconnectPoll(conn)</code> again.
+ On the first iteration, i.e., if you have yet to call
+ <code class="function">PQconnectPoll</code>, behave as if it last returned
+ <code class="symbol">PGRES_POLLING_WRITING</code>. Continue this loop until
+ <code class="function">PQconnectPoll(conn)</code> returns
+ <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure
+ has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection
+ has been successfully made.
+ </p><p>
+ At any time during connection, the status of the connection can be
+ checked by calling <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the
+ connection procedure has failed; if the call returns <code class="function">CONNECTION_OK</code>, then the
+ connection is ready. Both of these states are equally detectable
+ from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur
+ during (and only during) an asynchronous connection procedure. These
+ indicate the current stage of the connection procedure and might be useful
+ to provide feedback to the user for example. These statuses are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECTION-STARTED"><span class="term"><code class="symbol">CONNECTION_STARTED</code></span></dt><dd><p>
+ Waiting for connection to be made.
+ </p></dd><dt id="LIBPQ-CONNECTION-MADE"><span class="term"><code class="symbol">CONNECTION_MADE</code></span></dt><dd><p>
+ Connection OK; waiting to send.
+ </p></dd><dt id="LIBPQ-CONNECTION-AWAITING-RESPONSE"><span class="term"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></span></dt><dd><p>
+ Waiting for a response from the server.
+ </p></dd><dt id="LIBPQ-CONNECTION-AUTH-OK"><span class="term"><code class="symbol">CONNECTION_AUTH_OK</code></span></dt><dd><p>
+ Received authentication; waiting for backend start-up to finish.
+ </p></dd><dt id="LIBPQ-CONNECTION-SSL-STARTUP"><span class="term"><code class="symbol">CONNECTION_SSL_STARTUP</code></span></dt><dd><p>
+ Negotiating SSL encryption.
+ </p></dd><dt id="LIBPQ-CONNECTION-SETENV"><span class="term"><code class="symbol">CONNECTION_SETENV</code></span></dt><dd><p>
+ Negotiating environment-driven parameter settings.
+ </p></dd><dt id="LIBPQ-CONNECTION-CHECK-WRITABLE"><span class="term"><code class="symbol">CONNECTION_CHECK_WRITABLE</code></span></dt><dd><p>
+ Checking if connection is able to handle write transactions.
+ </p></dd><dt id="LIBPQ-CONNECTION-CONSUME"><span class="term"><code class="symbol">CONNECTION_CONSUME</code></span></dt><dd><p>
+ Consuming any remaining response messages on connection.
+ </p></dd></dl></div><p>
+
+ Note that, although these constants will remain (in order to maintain
+ compatibility), an application should never rely upon these occurring in a
+ particular order, or at all, or on the status always being one of these
+ documented values. An application might do something like this:
+</p><pre class="programlisting">
+switch(PQstatus(conn))
+{
+ case CONNECTION_STARTED:
+ feedback = "Connecting...";
+ break;
+
+ case CONNECTION_MADE:
+ feedback = "Connected to server...";
+ break;
+.
+.
+.
+ default:
+ feedback = "Connecting...";
+}
+</pre><p>
+ </p><p>
+ The <code class="literal">connect_timeout</code> connection parameter is ignored
+ when using <code class="function">PQconnectPoll</code>; it is the application's
+ responsibility to decide whether an excessive amount of time has elapsed.
+ Otherwise, <code class="function">PQconnectStart</code> followed by a
+ <code class="function">PQconnectPoll</code> loop is equivalent to
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
+ </p><p>
+ Note that when <code class="function">PQconnectStart</code>
+ or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null
+ pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are
+ finished with it, in order to dispose of the structure and any
+ associated memory blocks. This must be done even if the connection
+ attempt fails or is abandoned.
+ </p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the default connection options.
+</p><pre class="synopsis">
+PQconninfoOption *PQconndefaults(void);
+
+typedef struct
+{
+ char *keyword; /* The keyword of the option */
+ char *envvar; /* Fallback environment variable name */
+ char *compiled; /* Fallback compiled in default value */
+ char *val; /* Option's current value, or NULL */
+ char *label; /* Label for field in connect dialog */
+ char *dispchar; /* Indicates how to display this field
+ in a connect dialog. Values are:
+ "" Display entered value as is
+ "*" Password field - hide value
+ "D" Debug option - don't show by default */
+ int dispsize; /* Field size in characters for dialog */
+} PQconninfoOption;
+</pre><p>
+ </p><p>
+ Returns a connection options array. This can be used to determine
+ all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their
+ current default values. The return value points to an array of
+ <code class="structname">PQconninfoOption</code> structures, which ends
+ with an entry having a null <code class="structfield">keyword</code> pointer. The
+ null pointer is returned if memory could not be allocated. Note that
+ the current default values (<code class="structfield">val</code> fields)
+ will depend on environment variables and other context. A
+ missing or invalid service file will be silently ignored. Callers
+ must treat the connection options data as read-only.
+ </p><p>
+ After processing the options array, free it by passing it to
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, a small amount of memory
+ is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>.
+ </p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the connection options used by a live connection.
+</p><pre class="synopsis">
+PQconninfoOption *PQconninfo(PGconn *conn);
+</pre><p>
+ </p><p>
+ Returns a connection options array. This can be used to determine
+ all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the
+ values that were used to connect to the server. The return
+ value points to an array of <code class="structname">PQconninfoOption</code>
+ structures, which ends with an entry having a null <code class="structfield">keyword</code>
+ pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also
+ apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>.
+ </p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns parsed connection options from the provided connection string.
+
+</p><pre class="synopsis">
+PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
+</pre><p>
+ </p><p>
+ Parses a connection string and returns the resulting options as an
+ array; or returns <code class="symbol">NULL</code> if there is a problem with the connection
+ string. This function can be used to extract
+ the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided
+ connection string. The return value points to an array of
+ <code class="structname">PQconninfoOption</code> structures, which ends
+ with an entry having a null <code class="structfield">keyword</code> pointer.
+ </p><p>
+ All legal options will be present in the result array, but the
+ <code class="literal">PQconninfoOption</code> for any option not present
+ in the connection string will have <code class="literal">val</code> set to
+ <code class="literal">NULL</code>; default values are not inserted.
+ </p><p>
+ If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set
+ to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining
+ the problem. (It is also possible for <code class="literal">*errmsg</code> to be
+ set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;
+ this indicates an out-of-memory condition.)
+ </p><p>
+ After processing the options array, free it by passing it to
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, some memory
+ is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
+ Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,
+ be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>.
+ </p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span></dt><dd><p>
+ Closes the connection to the server. Also frees
+ memory used by the <code class="structname">PGconn</code> object.
+</p><pre class="synopsis">
+void PQfinish(PGconn *conn);
+</pre><p>
+ </p><p>
+ Note that even if the server connection attempt fails (as
+ indicated by <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>), the application should call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>
+ to free the memory used by the <code class="structname">PGconn</code> object.
+ The <code class="structname">PGconn</code> pointer must not be used again after
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called.
+ </p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span></dt><dd><p>
+ Resets the communication channel to the server.
+</p><pre class="synopsis">
+void PQreset(PGconn *conn);
+</pre><p>
+ </p><p>
+ This function will close the connection
+ to the server and attempt to establish a new
+ connection, using all the same
+ parameters previously used. This might be useful for
+ error recovery if a working connection is lost.
+ </p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.11.2.2" class="indexterm"></a></span></dt><dd><p>
+ Reset the communication channel to the server, in a nonblocking manner.
+
+</p><pre class="synopsis">
+int PQresetStart(PGconn *conn);
+
+PostgresPollingStatusType PQresetPoll(PGconn *conn);
+</pre><p>
+ </p><p>
+ These functions will close the connection to the server and attempt to
+ establish a new connection, using all the same
+ parameters previously used. This can be useful for error recovery if a
+ working connection is lost. They differ from <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> (above) in that they
+ act in a nonblocking manner. These functions suffer from the same
+ restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
+ and <code class="function">PQconnectPoll</code>.
+ </p><p>
+ To initiate a connection reset, call
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has
+ failed. If it returns 1, poll the reset using
+ <code class="function">PQresetPoll</code> in exactly the same way as you
+ would create the connection using <code class="function">PQconnectPoll</code>.
+ </p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the
+ server. It accepts connection parameters identical to those of
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above. It is not
+ necessary to supply correct user name, password, or database name
+ values to obtain the server status; however, if incorrect values
+ are provided, the server will log a failed connection attempt.
+
+</p><pre class="synopsis">
+PGPing PQpingParams(const char * const *keywords,
+ const char * const *values,
+ int expand_dbname);
+</pre><p>
+
+ The function returns one of the following values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPINGPARAMS-PQPING_OK"><span class="term"><code class="literal">PQPING_OK</code></span></dt><dd><p>
+ The server is running and appears to be accepting connections.
+ </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_REJECT"><span class="term"><code class="literal">PQPING_REJECT</code></span></dt><dd><p>
+ The server is running but is in a state that disallows connections
+ (startup, shutdown, or crash recovery).
+ </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE"><span class="term"><code class="literal">PQPING_NO_RESPONSE</code></span></dt><dd><p>
+ The server could not be contacted. This might indicate that the
+ server is not running, or that there is something wrong with the
+ given connection parameters (for example, wrong port number), or
+ that there is a network connectivity problem (for example, a
+ firewall blocking the connection request).
+ </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT"><span class="term"><code class="literal">PQPING_NO_ATTEMPT</code></span></dt><dd><p>
+ No attempt was made to contact the server, because the supplied
+ parameters were obviously incorrect or there was some client-side
+ problem (for example, out of memory).
+ </p></dd></dl></div><p>
+
+ </p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the
+ server. It accepts connection parameters identical to those of
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above. It is not
+ necessary to supply correct user name, password, or database name
+ values to obtain the server status; however, if incorrect values
+ are provided, the server will log a failed connection attempt.
+
+</p><pre class="synopsis">
+PGPing PQping(const char *conninfo);
+</pre><p>
+ </p><p>
+ The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>.
+ </p></dd><dt id="LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.14.1.2" class="indexterm"></a></span></dt><dd><p>
+ <code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override
+ <span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="34.19.2. Client Certificates">default
+ handling of encrypted client certificate key files</a> using
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting.
+
+</p><pre class="synopsis">
+void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
+</pre><p>
+
+ The application passes a pointer to a callback function with signature:
+</p><pre class="programlisting">
+int callback_fn(char *buf, int size, PGconn *conn);
+</pre><p>
+ which <span class="application">libpq</span> will then call
+ <span class="emphasis"><em>instead of</em></span> its default
+ <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The
+ callback should determine the password for the key and copy it to
+ result-buffer <em class="parameter"><code>buf</code></em> of size
+ <em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em>
+ must be null-terminated. The callback must return the length of the
+ password stored in <em class="parameter"><code>buf</code></em> excluding the null
+ terminator. On failure, the callback should set
+ <code class="literal">buf[0] = '\0'</code> and return 0. See
+ <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in
+ <span class="application">libpq</span>'s source code for an example.
+ </p><p>
+ If the user specified an explicit key location,
+ its path will be in <code class="literal">conn-&gt;sslkey</code> when the callback
+ is invoked. This will be empty if the default key path is being used.
+ For keys that are engine specifiers, it is up to engine implementations
+ whether they use the <span class="productname">OpenSSL</span> password
+ callback or define their own handling.
+ </p><p>
+ The app callback may choose to delegate unhandled cases to
+ <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>,
+ or call it first and try something else if it returns 0, or completely override it.
+ </p><p>
+ The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions,
+ <code class="function">longjmp(...)</code>, etc. It must return normally.
+ </p></dd><dt id="LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQgetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.15.1.2" class="indexterm"></a></span></dt><dd><p>
+ <code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current
+ client certificate key password hook, or <code class="literal">NULL</code>
+ if none has been set.
+
+</p><pre class="synopsis">
+PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">34.1.1. Connection Strings</h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a><p>
+ Several <span class="application">libpq</span> functions parse a user-specified string to obtain
+ connection parameters. There are two accepted formats for these strings:
+ plain keyword/value strings
+ and URIs. URIs generally follow
+ <a class="ulink" href="https://tools.ietf.org/html/rfc3986" target="_top">RFC
+ 3986</a>, except that multi-host connection strings are allowed
+ as further described below.
+ </p><div class="sect3" id="id-1.7.3.8.3.5"><div class="titlepage"><div><div><h4 class="title">34.1.1.1. Keyword/Value Connection Strings</h4></div></div></div><p>
+ In the keyword/value format, each parameter setting is in the form
+ <em class="replaceable"><code>keyword</code></em> <code class="literal">=</code>
+ <em class="replaceable"><code>value</code></em>, with space(s) between settings.
+ Spaces around a setting's equal sign are
+ optional. To write an empty value, or a value containing spaces, surround it
+ with single quotes, for example <code class="literal">keyword = 'a value'</code>.
+ Single quotes and backslashes within
+ a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and
+ <code class="literal">\\</code>.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+host=localhost port=5432 dbname=mydb connect_timeout=10
+</pre><p>
+ </p><p>
+ The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.
+ </p></div><div class="sect3" id="id-1.7.3.8.3.6"><div class="titlepage"><div><div><h4 class="title">34.1.1.2. Connection URIs</h4></div></div></div><p>
+ The general form for a connection <acronym class="acronym">URI</acronym> is:
+</p><pre class="synopsis">
+postgresql://[<span class="optional"><em class="replaceable"><code>userspec</code></em>@</span>][<span class="optional"><em class="replaceable"><code>hostspec</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>paramspec</code></em></span>]
+
+<span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span>
+
+<em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>]
+
+<span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span>
+
+[<span class="optional"><em class="replaceable"><code>host</code></em></span>][<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">,...</span>]
+
+<span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span>
+
+<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&amp;...</span>]
+</pre><p>
+ </p><p>
+ The <acronym class="acronym">URI</acronym> scheme designator can be either
+ <code class="literal">postgresql://</code> or <code class="literal">postgres://</code>. Each
+ of the remaining <acronym class="acronym">URI</acronym> parts is optional. The
+ following examples illustrate valid <acronym class="acronym">URI</acronym> syntax:
+</p><pre class="programlisting">
+postgresql://
+postgresql://localhost
+postgresql://localhost:5433
+postgresql://localhost/mydb
+postgresql://user@localhost
+postgresql://user:secret@localhost
+postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
+postgresql://host1:123,host2:456/somedb?target_session_attrs=any&amp;application_name=myapp
+</pre><p>
+ Values that would normally appear in the hierarchical part of
+ the <acronym class="acronym">URI</acronym> can alternatively be given as named
+ parameters. For example:
+</p><pre class="programlisting">
+postgresql:///mydb?host=localhost&amp;port=5433
+</pre><p>
+ All named parameters must match key words listed in
+ <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>, except that for compatibility
+ with JDBC connection <acronym class="acronym">URI</acronym>s, instances
+ of <code class="literal">ssl=true</code> are translated into
+ <code class="literal">sslmode=require</code>.
+ </p><p>
+ The connection <acronym class="acronym">URI</acronym> needs to be encoded with <a class="ulink" href="https://tools.ietf.org/html/rfc3986#section-2.1" target="_top">percent-encoding</a>
+ if it includes symbols with special meaning in any of its parts. Here is
+ an example where the equal sign (<code class="literal">=</code>) is replaced with
+ <code class="literal">%3D</code> and the space character with
+ <code class="literal">%20</code>:
+</p><pre class="programlisting">
+postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
+</pre><p>
+ </p><p>
+ The host part may be either a host name or an IP address. To specify an
+ IPv6 address, enclose it in square brackets:
+</p><pre class="synopsis">
+postgresql://[2001:db8::1234]/database
+</pre><p>
+ </p><p>
+ The host part is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>. In particular, a Unix-domain socket
+ connection is chosen if the host part is either empty or looks like an
+ absolute path name,
+ 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
+ specify a non-standard Unix-domain socket directory, either omit the host
+ part of the URI and specify the host as a named parameter, or
+ percent-encode the path in the host part of the URI:
+</p><pre class="programlisting">
+postgresql:///dbname?host=/var/lib/postgresql
+postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
+</pre><p>
+ </p><p>
+ It is possible to specify multiple host components, each with an optional
+ port component, in a single URI. A URI of the form
+ <code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>
+ is equivalent to a connection string of the form
+ <code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>.
+ As further described below, each
+ host will be tried in turn until a connection is successfully established.
+ </p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">34.1.1.3. Specifying Multiple Hosts</h4></div></div></div><p>
+ It is possible to specify multiple hosts to connect to, so that they are
+ tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,
+ <code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated
+ lists of values. The same number of elements must be given in each
+ option that is specified, such
+ that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name,
+ the second <code class="literal">hostaddr</code> corresponds to the second host name, and so
+ forth. As an exception, if only one <code class="literal">port</code> is specified, it
+ applies to all the hosts.
+ </p><p>
+ In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs
+ separated by commas in the <code class="literal">host</code> component of the URI.
+ </p><p>
+ In either format, a single host name can translate to multiple network
+ addresses. A common example of this is a host that has both an IPv4 and
+ an IPv6 address.
+ </p><p>
+ When multiple hosts are specified, or when a single host name is
+ translated to multiple addresses, all the hosts and addresses will be
+ tried in order, until one succeeds. If none of the hosts can be reached,
+ the connection fails. If a connection is established successfully, but
+ authentication fails, the remaining hosts in the list are not tried.
+ </p><p>
+ If a password file is used, you can have different passwords for
+ different hosts. All the other connection options are the same for every
+ host in the list; it is not possible to e.g., specify different
+ usernames for different hosts.
+ </p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">34.1.2. Parameter Key Words</h3></div></div></div><p>
+ The currently recognized parameter key words are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECT-HOST"><span class="term"><code class="literal">host</code></span></dt><dd><p>
+ Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a> If a host name looks like an absolute path
+ name, it specifies Unix-domain communication rather than TCP/IP
+ communication; the value is the name of the directory in which the
+ socket file is stored. (On Unix, an absolute path name begins with a
+ slash. On Windows, paths starting with drive letters are also
+ recognized.) If the host name starts with <code class="literal">@</code>, it is
+ taken as a Unix-domain socket in the abstract namespace (currently
+ supported on Linux and Windows).
+ The default behavior when <code class="literal">host</code> is not
+ specified, or is empty, is to connect to a Unix-domain
+ socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in
+ <code class="filename">/tmp</code> (or whatever socket directory was specified
+ when <span class="productname">PostgreSQL</span> was built). On Windows and
+ on machines without Unix-domain sockets, the default is to connect to
+ <code class="literal">localhost</code>.
+ </p><p>
+ A comma-separated list of host names is also accepted, in which case
+ each host name in the list is tried in order; an empty item in the
+ list selects the default behavior as explained above. See
+ <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.
+ </p></dd><dt id="LIBPQ-CONNECT-HOSTADDR"><span class="term"><code class="literal">hostaddr</code></span></dt><dd><p>
+ Numeric IP address of host to connect to. This should be in the
+ standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>. If
+ your machine supports IPv6, you can also use those addresses.
+ TCP/IP communication is
+ always used when a nonempty string is specified for this parameter.
+ If this parameter is not specified, the value of <code class="literal">host</code>
+ will be looked up to find the corresponding IP address — or, if
+ <code class="literal">host</code> specifies an IP address, that value will be
+ used directly.
+ </p><p>
+ Using <code class="literal">hostaddr</code> allows the
+ application to avoid a host name look-up, which might be important
+ in applications with time constraints. However, a host name is
+ required for GSSAPI or SSPI authentication
+ methods, as well as for <code class="literal">verify-full</code> SSL
+ certificate verification. The following rules are used:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If <code class="literal">host</code> is specified
+ without <code class="literal">hostaddr</code>, a host name lookup occurs.
+ (When using <code class="function">PQconnectPoll</code>, the lookup occurs
+ when <code class="function">PQconnectPoll</code> first considers this host
+ name, and it may cause <code class="function">PQconnectPoll</code> to block
+ for a significant amount of time.)
+ </p></li><li class="listitem"><p>
+ If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,
+ the value for <code class="literal">hostaddr</code> gives the server network address.
+ The connection attempt will fail if the authentication
+ method requires a host name.
+ </p></li><li class="listitem"><p>
+ If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,
+ the value for <code class="literal">hostaddr</code> gives the server network address.
+ The value for <code class="literal">host</code> is ignored unless the
+ authentication method requires it, in which case it will be
+ used as the host name.
+ </p></li></ul></div><p>
+ Note that authentication is likely to fail if <code class="literal">host</code>
+ is not the name of the server at network address <code class="literal">hostaddr</code>.
+ Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code>
+ are specified, <code class="literal">host</code>
+ is used to identify the connection in a password file (see
+ <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
+ </p><p>
+ A comma-separated list of <code class="literal">hostaddr</code> values is also
+ accepted, in which case each host in the list is tried in order.
+ An empty item in the list causes the corresponding host name to be
+ used, or the default host name if that is empty as well. See
+ <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.
+ </p><p>
+ Without either a host name or host address,
+ <span class="application">libpq</span> will connect using a local
+ Unix-domain socket; or on Windows and on machines without Unix-domain
+ sockets, it will attempt to connect to <code class="literal">localhost</code>.
+ </p></dd><dt id="LIBPQ-CONNECT-PORT"><span class="term"><code class="literal">port</code></span></dt><dd><p>
+ Port number to connect to at the server host, or socket file
+ name extension for Unix-domain
+ connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>
+ If multiple hosts were given in the <code class="literal">host</code> or
+ <code class="literal">hostaddr</code> parameters, this parameter may specify a
+ comma-separated list of ports of the same length as the host list, or
+ it may specify a single port number to be used for all hosts.
+ An empty string, or an empty item in a comma-separated list,
+ specifies the default port number established
+ when <span class="productname">PostgreSQL</span> was built.
+ </p></dd><dt id="LIBPQ-CONNECT-DBNAME"><span class="term"><code class="literal">dbname</code></span></dt><dd><p>
+ The database name. Defaults to be the same as the user name.
+ In certain contexts, the value is checked for extended
+ formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for more details on
+ those.
+ </p></dd><dt id="LIBPQ-CONNECT-USER"><span class="term"><code class="literal">user</code></span></dt><dd><p>
+ <span class="productname">PostgreSQL</span> user name to connect as.
+ Defaults to be the same as the operating system name of the user
+ running the application.
+ </p></dd><dt id="LIBPQ-CONNECT-PASSWORD"><span class="term"><code class="literal">password</code></span></dt><dd><p>
+ Password to be used if the server demands password authentication.
+ </p></dd><dt id="LIBPQ-CONNECT-PASSFILE"><span class="term"><code class="literal">passfile</code></span></dt><dd><p>
+ Specifies the name of the file used to store passwords
+ (see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
+ Defaults to <code class="filename">~/.pgpass</code>, or
+ <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.
+ (No error is reported if this file does not exist.)
+ </p></dd><dt id="LIBPQ-CONNECT-CHANNEL-BINDING"><span class="term"><code class="literal">channel_binding</code></span></dt><dd><p>
+ This option controls the client's use of channel binding. A setting
+ of <code class="literal">require</code> means that the connection must employ
+ channel binding, <code class="literal">prefer</code> means that the client will
+ choose channel binding if available, and <code class="literal">disable</code>
+ prevents the use of channel binding. The default
+ is <code class="literal">prefer</code> if
+ <span class="productname">PostgreSQL</span> is compiled with SSL support;
+ otherwise the default is <code class="literal">disable</code>.
+ </p><p>
+ Channel binding is a method for the server to authenticate itself to
+ the client. It is only supported over SSL connections
+ with <span class="productname">PostgreSQL</span> 11 or later servers using
+ the <code class="literal">SCRAM</code> authentication method.
+ </p></dd><dt id="LIBPQ-CONNECT-CONNECT-TIMEOUT"><span class="term"><code class="literal">connect_timeout</code></span></dt><dd><p>
+ Maximum time to wait while connecting, in seconds (write as a decimal integer,
+ e.g., <code class="literal">10</code>). Zero, negative, or not specified means
+ wait indefinitely. The minimum allowed timeout is 2 seconds, therefore
+ a value of <code class="literal">1</code> is interpreted as <code class="literal">2</code>.
+ This timeout applies separately to each host name or IP address.
+ For example, if you specify two hosts and <code class="literal">connect_timeout</code>
+ is 5, each host will time out if no connection is made within 5
+ seconds, so the total time spent waiting for a connection might be
+ up to 10 seconds.
+ </p></dd><dt id="LIBPQ-CONNECT-CLIENT-ENCODING"><span class="term"><code class="literal">client_encoding</code></span></dt><dd><p>
+ This sets the <code class="varname">client_encoding</code>
+ configuration parameter for this connection. In addition to
+ the values accepted by the corresponding server option, you
+ can use <code class="literal">auto</code> to determine the right
+ encoding from the current locale in the client
+ (<code class="envar">LC_CTYPE</code> environment variable on Unix
+ systems).
+ </p></dd><dt id="LIBPQ-CONNECT-OPTIONS"><span class="term"><code class="literal">options</code></span></dt><dd><p>
+ Specifies command-line options to send to the server at connection
+ start. For example, setting this to <code class="literal">-c geqo=off</code> sets the
+ session's value of the <code class="varname">geqo</code> parameter to
+ <code class="literal">off</code>. Spaces within this string are considered to
+ separate command-line arguments, unless escaped with a backslash
+ (<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal
+ backslash. For a detailed discussion of the available
+ options, consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.
+ </p></dd><dt id="LIBPQ-CONNECT-APPLICATION-NAME"><span class="term"><code class="literal">application_name</code></span></dt><dd><p>
+ Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>
+ configuration parameter.
+ </p></dd><dt id="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME"><span class="term"><code class="literal">fallback_application_name</code></span></dt><dd><p>
+ Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.
+ This value will be used if no value has been given for
+ <code class="literal">application_name</code> via a connection parameter or the
+ <code class="envar">PGAPPNAME</code> environment variable. Specifying
+ a fallback name is useful in generic utility programs that
+ wish to set a default application name but allow it to be
+ overridden by the user.
+ </p></dd><dt id="LIBPQ-KEEPALIVES"><span class="term"><code class="literal">keepalives</code></span></dt><dd><p>
+ Controls whether client-side TCP keepalives are used. The default
+ value is 1, meaning on, but you can change this to 0, meaning off,
+ if keepalives are not wanted. This parameter is ignored for
+ connections made via a Unix-domain socket.
+ </p></dd><dt id="LIBPQ-KEEPALIVES-IDLE"><span class="term"><code class="literal">keepalives_idle</code></span></dt><dd><p>
+ Controls the number of seconds of inactivity after which TCP should
+ send a keepalive message to the server. A value of zero uses the
+ system default. This parameter is ignored for connections made via a
+ Unix-domain socket, or if keepalives are disabled.
+ It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or
+ an equivalent socket option is available, and on Windows; on other
+ systems, it has no effect.
+ </p></dd><dt id="LIBPQ-KEEPALIVES-INTERVAL"><span class="term"><code class="literal">keepalives_interval</code></span></dt><dd><p>
+ Controls the number of seconds after which a TCP keepalive message
+ that is not acknowledged by the server should be retransmitted. A
+ value of zero uses the system default. This parameter is ignored for
+ connections made via a Unix-domain socket, or if keepalives are disabled.
+ It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or
+ an equivalent socket option is available, and on Windows; on other
+ systems, it has no effect.
+ </p></dd><dt id="LIBPQ-KEEPALIVES-COUNT"><span class="term"><code class="literal">keepalives_count</code></span></dt><dd><p>
+ Controls the number of TCP keepalives that can be lost before the
+ client's connection to the server is considered dead. A value of
+ zero uses the system default. This parameter is ignored for
+ connections made via a Unix-domain socket, or if keepalives are disabled.
+ It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or
+ an equivalent socket option is available; on other systems, it has no
+ effect.
+ </p></dd><dt id="LIBPQ-TCP-USER-TIMEOUT"><span class="term"><code class="literal">tcp_user_timeout</code></span></dt><dd><p>
+ Controls the number of milliseconds that transmitted data may
+ remain unacknowledged before a connection is forcibly closed.
+ A value of zero uses the system default. This parameter is
+ ignored for connections made via a Unix-domain socket.
+ It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code>
+ is available; on other systems, it has no effect.
+ </p></dd><dt id="LIBPQ-CONNECT-REPLICATION"><span class="term"><code class="literal">replication</code></span></dt><dd><p>
+ This option determines whether the connection should use the
+ replication protocol instead of the normal protocol. This is what
+ PostgreSQL replication connections as well as tools such as
+ <span class="application">pg_basebackup</span> use internally, but it can
+ also be used by third-party applications. For a description of the
+ replication protocol, consult <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>.
+ </p><p>
+ The following values, which are case-insensitive, are supported:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal">true</code>, <code class="literal">on</code>,
+ <code class="literal">yes</code>, <code class="literal">1</code>
+ </span></dt><dd><p>
+ The connection goes into physical replication mode.
+ </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>
+ The connection goes into logical replication mode, connecting to
+ the database specified in the <code class="literal">dbname</code> parameter.
+ </p></dd><dt><span class="term">
+ <code class="literal">false</code>, <code class="literal">off</code>,
+ <code class="literal">no</code>, <code class="literal">0</code>
+ </span></dt><dd><p>
+ The connection is a regular one, which is the default behavior.
+ </p></dd></dl></div><p>
+ </p><p>
+ In physical or logical replication mode, only the simple query protocol
+ can be used.
+ </p></dd><dt id="LIBPQ-CONNECT-GSSENCMODE"><span class="term"><code class="literal">gssencmode</code></span></dt><dd><p>
+ This option determines whether or with what priority a secure
+ <acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the
+ server. There are three modes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
+ only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection
+ </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
+ if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e.,
+ in a credentials cache), first try
+ a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or
+ there are no credentials, try a
+ non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection. This is the
+ default when <span class="productname">PostgreSQL</span> has been
+ compiled with <acronym class="acronym">GSSAPI</acronym> support.
+ </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
+ only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection
+ </p></dd></dl></div><p>
+ </p><p>
+ <code class="literal">gssencmode</code> is ignored for Unix domain socket
+ communication. If <span class="productname">PostgreSQL</span> is compiled
+ without GSSAPI support, using the <code class="literal">require</code> option
+ will cause an error, while <code class="literal">prefer</code> will be accepted
+ but <span class="application">libpq</span> will not actually attempt
+ a <acronym class="acronym">GSSAPI</acronym>-encrypted
+ connection.<a id="id-1.7.3.8.4.2.1.20.2.2.7" class="indexterm"></a>
+ </p></dd><dt id="LIBPQ-CONNECT-SSLMODE"><span class="term"><code class="literal">sslmode</code></span></dt><dd><p>
+ This option determines whether or with what priority a secure
+ <acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the
+ server. There are six modes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
+ only try a non-<acronym class="acronym">SSL</acronym> connection
+ </p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p>
+ first try a non-<acronym class="acronym">SSL</acronym> connection; if that
+ fails, try an <acronym class="acronym">SSL</acronym> connection
+ </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
+ first try an <acronym class="acronym">SSL</acronym> connection; if that fails,
+ try a non-<acronym class="acronym">SSL</acronym> connection
+ </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
+ only try an <acronym class="acronym">SSL</acronym> connection. If a root CA
+ file is present, verify the certificate in the same way as
+ if <code class="literal">verify-ca</code> was specified
+ </p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p>
+ only try an <acronym class="acronym">SSL</acronym> connection, and verify that
+ the server certificate is issued by a trusted
+ certificate authority (<acronym class="acronym">CA</acronym>)
+ </p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p>
+ only try an <acronym class="acronym">SSL</acronym> connection, verify that the
+ server certificate is issued by a
+ trusted <acronym class="acronym">CA</acronym> and that the requested server host name
+ matches that in the certificate
+ </p></dd></dl></div><p>
+
+ See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a detailed description of how
+ these options work.
+ </p><p>
+ <code class="literal">sslmode</code> is ignored for Unix domain socket
+ communication.
+ If <span class="productname">PostgreSQL</span> is compiled without SSL support,
+ using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or
+ <code class="literal">verify-full</code> will cause an error, while
+ options <code class="literal">allow</code> and <code class="literal">prefer</code> will be
+ accepted but <span class="application">libpq</span> will not actually attempt
+ an <acronym class="acronym">SSL</acronym>
+ connection.<a id="id-1.7.3.8.4.2.1.21.2.2.10" class="indexterm"></a>
+ </p><p>
+ Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible,
+ that will be used in preference to <acronym class="acronym">SSL</acronym>
+ encryption, regardless of the value of <code class="literal">sslmode</code>.
+ To force use of <acronym class="acronym">SSL</acronym> encryption in an
+ environment that has working <acronym class="acronym">GSSAPI</acronym>
+ infrastructure (such as a Kerberos server), also
+ set <code class="literal">gssencmode</code> to <code class="literal">disable</code>.
+ </p></dd><dt id="LIBPQ-CONNECT-REQUIRESSL"><span class="term"><code class="literal">requiressl</code></span></dt><dd><p>
+ This option is deprecated in favor of the <code class="literal">sslmode</code>
+ setting.
+ </p><p>
+ If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server
+ is required (this is equivalent to <code class="literal">sslmode</code>
+ <code class="literal">require</code>). <span class="application">libpq</span> will then refuse
+ to connect if the server does not accept an
+ <acronym class="acronym">SSL</acronym> connection. If set to 0 (default),
+ <span class="application">libpq</span> will negotiate the connection type with
+ the server (equivalent to <code class="literal">sslmode</code>
+ <code class="literal">prefer</code>). This option is only available if
+ <span class="productname">PostgreSQL</span> is compiled with SSL support.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><span class="term"><code class="literal">sslcompression</code></span></dt><dd><p>
+ If set to 1, data sent over SSL connections will be compressed. If
+ set to 0, compression will be disabled. The default is 0. This
+ parameter is ignored if a connection without SSL is made.
+ </p><p>
+ SSL compression is nowadays considered insecure and its use is no
+ longer recommended. <span class="productname">OpenSSL</span> 1.1.0 disables
+ compression by default, and many operating system distributions
+ disable it in prior versions as well, so setting this parameter to on
+ will not have any effect if the server does not accept compression.
+ <span class="productname">PostgreSQL</span> 14 disables compression
+ completely in the backend.
+ </p><p>
+ If security is not a primary concern, compression can improve
+ throughput if the network is the bottleneck. Disabling compression
+ can improve response time and throughput if CPU performance is the
+ limiting factor.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLCERT"><span class="term"><code class="literal">sslcert</code></span></dt><dd><p>
+ This parameter specifies the file name of the client SSL
+ certificate, replacing the default
+ <code class="filename">~/.postgresql/postgresql.crt</code>.
+ This parameter is ignored if an SSL connection is not made.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLKEY"><span class="term"><code class="literal">sslkey</code></span></dt><dd><p>
+ This parameter specifies the location for the secret key used for
+ the client certificate. It can either specify a file name that will
+ be used instead of the default
+ <code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key
+ obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are
+ <span class="productname">OpenSSL</span> loadable modules). An external engine
+ specification should consist of a colon-separated engine name and
+ an engine-specific key identifier. This parameter is ignored if an
+ SSL connection is not made.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLPASSWORD"><span class="term"><code class="literal">sslpassword</code></span></dt><dd><p>
+ This parameter specifies the password for the secret key specified in
+ <code class="literal">sslkey</code>, allowing client certificate private keys
+ to be stored in encrypted form on disk even when interactive passphrase
+ input is not practical.
+ </p><p>
+ Specifying this parameter with any non-empty value suppresses the
+ <code class="literal">Enter PEM pass phrase:</code>
+ prompt that <span class="productname">OpenSSL</span> will emit by default
+ when an encrypted client certificate key is provided to
+ <code class="literal">libpq</code>.
+ </p><p>
+ If the key is not encrypted this parameter is ignored. The parameter
+ has no effect on keys specified by <span class="productname">OpenSSL</span>
+ engines unless the engine uses the <span class="productname">OpenSSL</span>
+ password callback mechanism for prompts.
+ </p><p>
+ There is no environment variable equivalent to this option, and no
+ facility for looking it up in <code class="filename">.pgpass</code>. It can be
+ used in a service file connection definition. Users with
+ more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and
+ tools like PKCS#11 or USB crypto offload devices.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLROOTCERT"><span class="term"><code class="literal">sslrootcert</code></span></dt><dd><p>
+ This parameter specifies the name of a file containing SSL
+ certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).
+ If the file exists, the server's certificate will be verified
+ to be signed by one of these authorities. The default is
+ <code class="filename">~/.postgresql/root.crt</code>.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLCRL"><span class="term"><code class="literal">sslcrl</code></span></dt><dd><p>
+ This parameter specifies the file name of the SSL server certificate
+ revocation list (CRL). Certificates listed in this file, if it
+ exists, will be rejected while attempting to authenticate the
+ server's certificate. If neither
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is
+ taken as
+ <code class="filename">~/.postgresql/root.crl</code>.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLCRLDIR"><span class="term"><code class="literal">sslcrldir</code></span></dt><dd><p>
+ This parameter specifies the directory name of the SSL server certificate
+ revocation list (CRL). Certificates listed in the files in this
+ directory, if it exists, will be rejected while attempting to
+ authenticate the server's certificate.
+ </p><p>
+ The directory needs to be prepared with the
+ <span class="productname">OpenSSL</span> command
+ <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See
+ its documentation for details.
+ </p><p>
+ Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be
+ specified together.
+ </p></dd><dt id="LIBPQ-CONNECT-SSLSNI"><span class="term"><code class="literal">sslsni</code><a id="id-1.7.3.8.4.2.1.30.1.2" class="indexterm"></a></span></dt><dd><p>
+ If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name
+ Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections.
+ By setting this parameter to 0, this is turned off.
+ </p><p>
+ The Server Name Indication can be used by SSL-aware proxies to route
+ connections without having to decrypt the SSL stream. (Note that this
+ requires a proxy that is aware of the PostgreSQL protocol handshake,
+ not just any SSL proxy.) However, <acronym class="acronym">SNI</acronym> makes the
+ destination host name appear in cleartext in the network traffic, so
+ it might be undesirable in some cases.
+ </p></dd><dt id="LIBPQ-CONNECT-REQUIREPEER"><span class="term"><code class="literal">requirepeer</code></span></dt><dd><p>
+ This parameter specifies the operating-system user name of the
+ server, for example <code class="literal">requirepeer=postgres</code>.
+ When making a Unix-domain socket connection, if this
+ parameter is set, the client checks at the beginning of the
+ connection that the server process is running under the specified
+ user name; if it is not, the connection is aborted with an error.
+ This parameter can be used to provide server authentication similar
+ to that available with SSL certificates on TCP/IP connections.
+ (Note that if the Unix-domain socket is in
+ <code class="filename">/tmp</code> or another publicly writable location,
+ any user could start a server listening there. Use this parameter
+ to ensure that you are connected to a server run by a trusted user.)
+ This option is only supported on platforms for which the
+ <code class="literal">peer</code> authentication method is implemented; see
+ <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a>.
+ </p></dd><dt id="LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_min_protocol_version</code></span></dt><dd><p>
+ This parameter specifies the minimum SSL/TLS protocol version to allow
+ for the connection. Valid values are <code class="literal">TLSv1</code>,
+ <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
+ <code class="literal">TLSv1.3</code>. The supported protocols depend on the
+ version of <span class="productname">OpenSSL</span> used, older versions
+ not supporting the most modern protocol versions. If not specified,
+ the default is <code class="literal">TLSv1.2</code>, which satisfies industry
+ best practices as of this writing.
+ </p></dd><dt id="LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_max_protocol_version</code></span></dt><dd><p>
+ This parameter specifies the maximum SSL/TLS protocol version to allow
+ for the connection. Valid values are <code class="literal">TLSv1</code>,
+ <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
+ <code class="literal">TLSv1.3</code>. The supported protocols depend on the
+ version of <span class="productname">OpenSSL</span> used, older versions
+ not supporting the most modern protocol versions. If not set, this
+ parameter is ignored and the connection will use the maximum bound
+ defined by the backend, if set. Setting the maximum protocol version
+ is mainly useful for testing or if some component has issues working
+ with a newer protocol.
+ </p></dd><dt id="LIBPQ-CONNECT-KRBSRVNAME"><span class="term"><code class="literal">krbsrvname</code></span></dt><dd><p>
+ 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
+ <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>.)
+ The default value is normally <code class="literal">postgres</code>,
+ but that can be changed when
+ building <span class="productname">PostgreSQL</span> via
+ the <code class="option">--with-krb-srvnam</code> option
+ of <span class="application">configure</span>.
+ In most environments, this parameter never needs to be changed.
+ Some Kerberos implementations might require a different service name,
+ such as Microsoft Active Directory which requires the service name
+ to be in upper case (<code class="literal">POSTGRES</code>).
+ </p></dd><dt id="LIBPQ-CONNECT-GSSLIB"><span class="term"><code class="literal">gsslib</code></span></dt><dd><p>
+ GSS library to use for GSSAPI authentication.
+ Currently this is disregarded except on Windows builds that include
+ both GSSAPI and SSPI support. In that case, set
+ this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI
+ library for authentication instead of the default SSPI.
+ </p></dd><dt id="LIBPQ-CONNECT-SERVICE"><span class="term"><code class="literal">service</code></span></dt><dd><p>
+ Service name to use for additional parameters. It specifies a service
+ name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.
+ This allows applications to specify only a service name so connection parameters
+ can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>.
+ </p></dd><dt id="LIBPQ-CONNECT-TARGET-SESSION-ATTRS"><span class="term"><code class="literal">target_session_attrs</code></span></dt><dd><p>
+ This option determines whether the session must have certain
+ properties to be acceptable. It's typically used in combination
+ with multiple host names to select the first acceptable alternative
+ among several hosts. There are six modes:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">any</code> (default)</span></dt><dd><p>
+ any successful connection is acceptable
+ </p></dd><dt><span class="term"><code class="literal">read-write</code></span></dt><dd><p>
+ session must accept read-write transactions by default (that
+ is, the server must not be in hot standby mode and
+ the <code class="varname">default_transaction_read_only</code> parameter
+ must be <code class="literal">off</code>)
+ </p></dd><dt><span class="term"><code class="literal">read-only</code></span></dt><dd><p>
+ session must not accept read-write transactions by default (the
+ converse)
+ </p></dd><dt><span class="term"><code class="literal">primary</code></span></dt><dd><p>
+ server must not be in hot standby mode
+ </p></dd><dt><span class="term"><code class="literal">standby</code></span></dt><dd><p>
+ server must be in hot standby mode
+ </p></dd><dt><span class="term"><code class="literal">prefer-standby</code></span></dt><dd><p>
+ first try to find a standby server, but if none of the listed
+ hosts is a standby server, try again in <code class="literal">any</code>
+ mode
+ </p></dd></dl></div><p>
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. <span class="application">libpq</span> — C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.2. Connection Status Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-control.html b/doc/src/sgml/html/libpq-control.html
new file mode 100644
index 0000000..e6fa345
--- /dev/null
+++ b/doc/src/sgml/html/libpq-control.html
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.11. Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command" /><link rel="next" href="libpq-misc.html" title="34.12. Miscellaneous Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.11. Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONTROL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.11. Control Functions</h2></div></div></div><p>
+ These functions control miscellaneous details of <span class="application">libpq</span>'s
+ behavior.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCLIENTENCODING"><span class="term"><code class="function">PQclientEncoding</code><a id="id-1.7.3.18.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the client encoding.
+</p><pre class="synopsis">
+int PQclientEncoding(const PGconn *<em class="replaceable"><code>conn</code></em>);
+</pre><p>
+
+ Note that it returns the encoding ID, not a symbolic string
+ such as <code class="literal">EUC_JP</code>. If unsuccessful, it returns -1.
+ To convert an encoding ID to an encoding name, you
+ can use:
+
+</p><pre class="synopsis">
+char *pg_encoding_to_char(int <em class="replaceable"><code>encoding_id</code></em>);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQSETCLIENTENCODING"><span class="term"><code class="function">PQsetClientEncoding</code><a id="id-1.7.3.18.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets the client encoding.
+</p><pre class="synopsis">
+int PQsetClientEncoding(PGconn *<em class="replaceable"><code>conn</code></em>, const char *<em class="replaceable"><code>encoding</code></em>);
+</pre><p>
+
+ <em class="replaceable"><code>conn</code></em> is a connection to the server,
+ and <em class="replaceable"><code>encoding</code></em> is the encoding you want to
+ use. If the function successfully sets the encoding, it returns 0,
+ otherwise -1. The current encoding for this connection can be
+ determined by using <a class="xref" href="libpq-control.html#LIBPQ-PQCLIENTENCODING"><code class="function">PQclientEncoding</code></a>.
+ </p></dd><dt id="LIBPQ-PQSETERRORVERBOSITY"><span class="term"><code class="function">PQsetErrorVerbosity</code><a id="id-1.7.3.18.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Determines the verbosity of messages returned by
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> and <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>.
+</p><pre class="synopsis">
+typedef enum
+{
+ PQERRORS_TERSE,
+ PQERRORS_DEFAULT,
+ PQERRORS_VERBOSE,
+ PQERRORS_SQLSTATE
+} PGVerbosity;
+
+PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
+</pre><p>
+
+ <a class="xref" href="libpq-control.html#LIBPQ-PQSETERRORVERBOSITY"><code class="function">PQsetErrorVerbosity</code></a> sets the verbosity mode,
+ returning the connection's previous setting.
+ In <em class="firstterm">TERSE</em> mode, returned messages include
+ severity, primary text, and position only; this will normally fit on a
+ single line. The <em class="firstterm">DEFAULT</em> mode produces messages
+ that include the above plus any detail, hint, or context fields (these
+ might span multiple lines). The <em class="firstterm">VERBOSE</em> mode
+ includes all available fields. The <em class="firstterm">SQLSTATE</em>
+ mode includes only the error severity and the <code class="symbol">SQLSTATE</code>
+ error code, if one is available (if not, the output is like
+ <em class="firstterm">TERSE</em> mode).
+ </p><p>
+ Changing the verbosity setting does not affect the messages available
+ from already-existing <code class="structname">PGresult</code> objects, only
+ subsequently-created ones.
+ (But see <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> if you
+ want to print a previous error with a different verbosity.)
+ </p></dd><dt id="LIBPQ-PQSETERRORCONTEXTVISIBILITY"><span class="term"><code class="function">PQsetErrorContextVisibility</code><a id="id-1.7.3.18.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Determines the handling of <code class="literal">CONTEXT</code> fields in messages
+ returned by <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a>
+ and <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>.
+</p><pre class="synopsis">
+typedef enum
+{
+ PQSHOW_CONTEXT_NEVER,
+ PQSHOW_CONTEXT_ERRORS,
+ PQSHOW_CONTEXT_ALWAYS
+} PGContextVisibility;
+
+PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);
+</pre><p>
+
+ <a class="xref" href="libpq-control.html#LIBPQ-PQSETERRORCONTEXTVISIBILITY"><code class="function">PQsetErrorContextVisibility</code></a> sets the context display mode,
+ returning the connection's previous setting. This mode controls
+ whether the <code class="literal">CONTEXT</code> field is included in messages.
+ The <em class="firstterm">NEVER</em> mode
+ never includes <code class="literal">CONTEXT</code>, while <em class="firstterm">ALWAYS</em> always
+ includes it if available. In <em class="firstterm">ERRORS</em> mode (the
+ default), <code class="literal">CONTEXT</code> fields are included only in error
+ messages, not in notices and warnings.
+ (However, if the verbosity setting is <em class="firstterm">TERSE</em>
+ or <em class="firstterm">SQLSTATE</em>, <code class="literal">CONTEXT</code> fields
+ are omitted regardless of the context display mode.)
+ </p><p>
+ Changing this mode does not
+ affect the messages available from
+ already-existing <code class="structname">PGresult</code> objects, only
+ subsequently-created ones.
+ (But see <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> if you
+ want to print a previous error with a different display mode.)
+ </p></dd><dt id="LIBPQ-PQTRACE"><span class="term"><code class="function">PQtrace</code><a id="id-1.7.3.18.3.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Enables tracing of the client/server communication to a debugging file
+ stream.
+</p><pre class="synopsis">
+void PQtrace(PGconn *conn, FILE *stream);
+</pre><p>
+ </p><p>
+ Each line consists of: an optional timestamp, a direction indicator
+ (<code class="literal">F</code> for messages from client to server
+ or <code class="literal">B</code> for messages from server to client),
+ message length, message type, and message contents.
+ Non-message contents fields (timestamp, direction, length and message type)
+ are separated by a tab. Message contents are separated by a space.
+ Protocol strings are enclosed in double quotes, while strings used as data
+ values are enclosed in single quotes. Non-printable chars are printed as
+ hexadecimal escapes.
+ Further message-type-specific detail can be found in
+ <a class="xref" href="protocol-message-formats.html" title="55.7. Message Formats">Section 55.7</a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On Windows, if the <span class="application">libpq</span> library and an application are
+ compiled with different flags, this function call will crash the
+ application because the internal representation of the <code class="literal">FILE</code>
+ pointers differ. Specifically, multithreaded/single-threaded,
+ release/debug, and static/dynamic flags should be the same for the
+ library and all applications using that library.
+ </p></div></dd><dt id="LIBPQ-PQSETTRACEFLAGS"><span class="term"><code class="function">PQsetTraceFlags</code><a id="id-1.7.3.18.3.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Controls the tracing behavior of client/server communication.
+</p><pre class="synopsis">
+void PQsetTraceFlags(PGconn *conn, int flags);
+</pre><p>
+ </p><p>
+ <code class="literal">flags</code> contains flag bits describing the operating mode
+ of tracing.
+ If <code class="literal">flags</code> contains <code class="literal">PQTRACE_SUPPRESS_TIMESTAMPS</code>,
+ then the timestamp is not included when printing each message.
+ If <code class="literal">flags</code> contains <code class="literal">PQTRACE_REGRESS_MODE</code>,
+ then some fields are redacted when printing each message, such as object
+ OIDs, to make the output more convenient to use in testing frameworks.
+ This function must be called after calling <code class="function">PQtrace</code>.
+ </p></dd><dt id="LIBPQ-PQUNTRACE"><span class="term"><code class="function">PQuntrace</code><a id="id-1.7.3.18.3.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Disables tracing started by <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>.
+</p><pre class="synopsis">
+void PQuntrace(PGconn *conn);
+</pre><p>
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.10. Functions Associated with the <code class="command">COPY</code> Command </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.12. Miscellaneous Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-copy.html b/doc/src/sgml/html/libpq-copy.html
new file mode 100644
index 0000000..8530822
--- /dev/null
+++ b/doc/src/sgml/html/libpq-copy.html
@@ -0,0 +1,300 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.10. Functions Associated with the COPY Command</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-notify.html" title="34.9. Asynchronous Notification" /><link rel="next" href="libpq-control.html" title="34.11. Control Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.10. Functions Associated with the <code class="command">COPY</code> Command</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-notify.html" title="34.9. Asynchronous Notification">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-control.html" title="34.11. Control Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-COPY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.10. Functions Associated with the <code class="command">COPY</code> Command</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-SEND">34.10.1. Functions for Sending <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-RECEIVE">34.10.2. Functions for Receiving <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">34.10.3. Obsolete Functions for <code class="command">COPY</code></a></span></dt></dl></div><a id="id-1.7.3.17.2" class="indexterm"></a><p>
+ The <code class="command">COPY</code> command in
+ <span class="productname">PostgreSQL</span> has options to read from or write
+ to the network connection used by <span class="application">libpq</span>.
+ The functions described in this section allow applications to take
+ advantage of this capability by supplying or consuming copied data.
+ </p><p>
+ The overall process is that the application first issues the SQL
+ <code class="command">COPY</code> command via <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or one
+ of the equivalent functions. The response to this (if there is no
+ error in the command) will be a <code class="structname">PGresult</code> object bearing
+ a status code of <code class="literal">PGRES_COPY_OUT</code> or
+ <code class="literal">PGRES_COPY_IN</code> (depending on the specified copy
+ direction). The application should then use the functions of this
+ section to receive or transmit data rows. When the data transfer is
+ complete, another <code class="structname">PGresult</code> object is returned to indicate
+ success or failure of the transfer. Its status will be
+ <code class="literal">PGRES_COMMAND_OK</code> for success or
+ <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.
+ At this point further SQL commands can be issued via
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>. (It is not possible to execute other SQL
+ commands using the same connection while the <code class="command">COPY</code>
+ operation is in progress.)
+ </p><p>
+ If a <code class="command">COPY</code> command is issued via
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> in a string that could contain additional
+ commands, the application must continue fetching results via
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> after completing the <code class="command">COPY</code>
+ sequence. Only when <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> returns
+ <code class="symbol">NULL</code> is it certain that the <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>
+ command string is done and it is safe to issue more commands.
+ </p><p>
+ The functions of this section should be executed only after obtaining
+ a result status of <code class="literal">PGRES_COPY_OUT</code> or
+ <code class="literal">PGRES_COPY_IN</code> from <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.
+ </p><p>
+ A <code class="structname">PGresult</code> object bearing one of these status values
+ carries some additional data about the <code class="command">COPY</code> operation
+ that is starting. This additional data is available using functions
+ that are also used in connection with query results:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQNFIELDS-1"><span class="term"><code class="function">PQnfields</code><a id="id-1.7.3.17.7.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the number of columns (fields) to be copied.
+ </p></dd><dt id="LIBPQ-PQBINARYTUPLES-1"><span class="term"><code class="function">PQbinaryTuples</code><a id="id-1.7.3.17.7.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ 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 <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for more information.
+ </p></dd><dt id="LIBPQ-PQFFORMAT-1"><span class="term"><code class="function">PQfformat</code><a id="id-1.7.3.17.7.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the format code (0 for text, 1 for binary) associated with
+ each column of the copy operation. The per-column format codes
+ will always be zero when the overall copy format is textual, but
+ the binary format can support both text and binary columns.
+ (However, as of the current implementation of <code class="command">COPY</code>,
+ only binary columns appear in a binary copy; so the per-column
+ formats always match the overall format at present.)
+ </p></dd></dl></div><p>
+ </p><div class="sect2" id="LIBPQ-COPY-SEND"><div class="titlepage"><div><div><h3 class="title">34.10.1. Functions for Sending <code class="command">COPY</code> Data</h3></div></div></div><p>
+ These functions are used to send data during <code class="literal">COPY FROM
+ STDIN</code>. They will fail if called when the connection is not in
+ <code class="literal">COPY_IN</code> state.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPUTCOPYDATA"><span class="term"><code class="function">PQputCopyData</code><a id="id-1.7.3.17.8.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends data to the server during <code class="literal">COPY_IN</code> state.
+</p><pre class="synopsis">
+int PQputCopyData(PGconn *conn,
+ const char *buffer,
+ int nbytes);
+</pre><p>
+ </p><p>
+ Transmits the <code class="command">COPY</code> data in the specified
+ <em class="parameter"><code>buffer</code></em>, of length <em class="parameter"><code>nbytes</code></em>, to the server.
+ The result is 1 if the data was queued, zero if it was not queued
+ because of full buffers (this will only happen in nonblocking mode),
+ or -1 if an error occurred.
+ (Use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to retrieve details if
+ the return value is -1. If the value is zero, wait for write-ready
+ and try again.)
+ </p><p>
+ The application can divide the <code class="command">COPY</code> data stream
+ 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
+ <code class="command">COPY</code> command; see <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for details.
+ </p></dd><dt id="LIBPQ-PQPUTCOPYEND"><span class="term"><code class="function">PQputCopyEnd</code><a id="id-1.7.3.17.8.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends end-of-data indication to the server during <code class="literal">COPY_IN</code> state.
+</p><pre class="synopsis">
+int PQputCopyEnd(PGconn *conn,
+ const char *errormsg);
+</pre><p>
+ </p><p>
+ Ends the <code class="literal">COPY_IN</code> operation successfully if
+ <em class="parameter"><code>errormsg</code></em> is <code class="symbol">NULL</code>. If
+ <em class="parameter"><code>errormsg</code></em> is not <code class="symbol">NULL</code> then the
+ <code class="command">COPY</code> is forced to fail, with the string pointed to by
+ <em class="parameter"><code>errormsg</code></em> used as the error message. (One should not
+ assume that this exact error message will come back from the server,
+ however, as the server might have already failed the
+ <code class="command">COPY</code> for its own reasons.)
+ </p><p>
+ The result is 1 if the termination message was sent; or in
+ nonblocking mode, this may only indicate that the termination
+ message was successfully queued. (In nonblocking mode, to be
+ certain that the data has been sent, you should next wait for
+ write-ready and call <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>, repeating until it
+ returns zero.) Zero indicates that the function could not queue
+ the termination message because of full buffers; this will only
+ happen in nonblocking mode. (In this case, wait for
+ write-ready and try the <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYEND"><code class="function">PQputCopyEnd</code></a> call
+ again.) If a hard error occurs, -1 is returned; you can use
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to retrieve details.
+ </p><p>
+ After successfully calling <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYEND"><code class="function">PQputCopyEnd</code></a>, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to obtain the final result status of the
+ <code class="command">COPY</code> command. One can wait for this result to be
+ available in the usual way. Then return to normal operation.
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-COPY-RECEIVE"><div class="titlepage"><div><div><h3 class="title">34.10.2. Functions for Receiving <code class="command">COPY</code> Data</h3></div></div></div><p>
+ These functions are used to receive data during <code class="literal">COPY TO
+ STDOUT</code>. They will fail if called when the connection is not in
+ <code class="literal">COPY_OUT</code> state.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETCOPYDATA"><span class="term"><code class="function">PQgetCopyData</code><a id="id-1.7.3.17.9.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Receives data from the server during <code class="literal">COPY_OUT</code> state.
+</p><pre class="synopsis">
+int PQgetCopyData(PGconn *conn,
+ char **buffer,
+ int async);
+</pre><p>
+ </p><p>
+ Attempts to obtain another row of data from the server during a
+ <code class="command">COPY</code>. Data is always returned one data row at
+ a time; if only a partial row is available, it is not returned.
+ Successful return of a data row involves allocating a chunk of
+ memory to hold the data. The <em class="parameter"><code>buffer</code></em> parameter must
+ be non-<code class="symbol">NULL</code>. <em class="parameter"><code>*buffer</code></em> is set to
+ point to the allocated memory, or to <code class="symbol">NULL</code> in cases
+ where no buffer is returned. A non-<code class="symbol">NULL</code> result
+ buffer should be freed using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> when no longer
+ needed.
+ </p><p>
+ When a row is successfully returned, the return value is the number
+ of data bytes in the row (this will always be greater than zero).
+ The returned string is always null-terminated, though this is
+ probably only useful for textual <code class="command">COPY</code>. A result
+ of zero indicates that the <code class="command">COPY</code> is still in
+ progress, but no row is yet available (this is only possible when
+ <em class="parameter"><code>async</code></em> is true). A result of -1 indicates that the
+ <code class="command">COPY</code> is done. A result of -2 indicates that an
+ error occurred (consult <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> for the reason).
+ </p><p>
+ When <em class="parameter"><code>async</code></em> is true (not zero),
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> will not block waiting for input; it
+ will return zero if the <code class="command">COPY</code> is still in progress
+ but no complete row is available. (In this case wait for read-ready
+ and then call <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> before calling
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> again.) When <em class="parameter"><code>async</code></em> is
+ false (zero), <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> will block until data is
+ available or the operation completes.
+ </p><p>
+ After <a class="xref" href="libpq-copy.html#LIBPQ-PQGETCOPYDATA"><code class="function">PQgetCopyData</code></a> returns -1, call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to obtain the final result status of the
+ <code class="command">COPY</code> command. One can wait for this result to be
+ available in the usual way. Then return to normal operation.
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-COPY-DEPRECATED"><div class="titlepage"><div><div><h3 class="title">34.10.3. Obsolete Functions for <code class="command">COPY</code></h3></div></div></div><p>
+ These functions represent older methods of handling <code class="command">COPY</code>.
+ Although they still work, they are deprecated due to poor error handling,
+ inconvenient methods of detecting end-of-data, and lack of support for binary
+ or nonblocking transfers.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQGETLINE"><span class="term"><code class="function">PQgetline</code><a id="id-1.7.3.17.10.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Reads a newline-terminated line of characters (transmitted
+ by the server) into a buffer string of size <em class="parameter"><code>length</code></em>.
+</p><pre class="synopsis">
+int PQgetline(PGconn *conn,
+ char *buffer,
+ int length);
+</pre><p>
+ </p><p>
+ This function copies up to <em class="parameter"><code>length</code></em>-1 characters into
+ the buffer and converts the terminating newline into a zero byte.
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a> returns <code class="symbol">EOF</code> at the
+ end of input, 0 if the entire line has been read, and 1 if the
+ buffer is full but the terminating newline has not yet been read.
+ </p><p>
+ Note that the application must check to see if a new line consists
+ of the two characters <code class="literal">\.</code>, which indicates
+ that the server has finished sending the results of the
+ <code class="command">COPY</code> command. If the application might receive
+ lines that are more than <em class="parameter"><code>length</code></em>-1 characters long,
+ care is needed to be sure it recognizes the <code class="literal">\.</code>
+ line correctly (and does not, for example, mistake the end of a
+ long data line for a terminator line).
+ </p></dd><dt id="LIBPQ-PQGETLINEASYNC"><span class="term"><code class="function">PQgetlineAsync</code><a id="id-1.7.3.17.10.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Reads a row of <code class="command">COPY</code> data (transmitted by the
+ server) into a buffer without blocking.
+</p><pre class="synopsis">
+int PQgetlineAsync(PGconn *conn,
+ char *buffer,
+ int bufsize);
+</pre><p>
+ </p><p>
+ This function is similar to <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a>, but it can be used
+ by applications
+ that must read <code class="command">COPY</code> data asynchronously, that is, without blocking.
+ Having issued the <code class="command">COPY</code> command and gotten a <code class="literal">PGRES_COPY_OUT</code>
+ response, the
+ application should call <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> and
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a> until the
+ end-of-data signal is detected.
+ </p><p>
+ Unlike <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a>, this function takes
+ responsibility for detecting end-of-data.
+ </p><p>
+ On each call, <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a> will return data if a
+ complete data row is available in <span class="application">libpq</span>'s input buffer.
+ Otherwise, no data is returned until the rest of the row arrives.
+ The function returns -1 if the end-of-copy-data marker has been recognized,
+ or 0 if no data is available, or a positive number giving the number of
+ bytes of data returned. If -1 is returned, the caller must next call
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>, and then return to normal processing.
+ </p><p>
+ The data returned will not extend beyond a data-row boundary. If possible
+ a whole row will be returned at one time. But if the buffer offered by
+ the caller is too small to hold a row sent by the server, then a partial
+ data row will be returned. With textual data this can be detected by testing
+ whether the last returned byte is <code class="literal">\n</code> or not. (In a binary
+ <code class="command">COPY</code>, actual parsing of the <code class="command">COPY</code> data format will be needed to make the
+ equivalent determination.)
+ The returned string is not null-terminated. (If you want to add a
+ terminating null, be sure to pass a <em class="parameter"><code>bufsize</code></em> one smaller
+ than the room actually available.)
+ </p></dd><dt id="LIBPQ-PQPUTLINE"><span class="term"><code class="function">PQputline</code><a id="id-1.7.3.17.10.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a null-terminated string to the server. Returns 0 if
+ OK and <code class="symbol">EOF</code> if unable to send the string.
+</p><pre class="synopsis">
+int PQputline(PGconn *conn,
+ const char *string);
+</pre><p>
+ </p><p>
+ The <code class="command">COPY</code> data stream sent by a series of calls
+ to <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> has the same format as that
+ returned by <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINEASYNC"><code class="function">PQgetlineAsync</code></a>, except that
+ applications are not obliged to send exactly one data row per
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> call; it is okay to send a partial
+ line or multiple lines per call.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> protocol 3.0, it was necessary
+ for the application to explicitly send the two characters
+ <code class="literal">\.</code> as a final line to indicate to the server that it had
+ finished sending <code class="command">COPY</code> data. While this still works, it is deprecated and the
+ special meaning of <code class="literal">\.</code> can be expected to be removed in a
+ future release. It is sufficient to call <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> after
+ having sent the actual data.
+ </p></div></dd><dt id="LIBPQ-PQPUTNBYTES"><span class="term"><code class="function">PQputnbytes</code><a id="id-1.7.3.17.10.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a non-null-terminated string to the server. Returns
+ 0 if OK and <code class="symbol">EOF</code> if unable to send the string.
+</p><pre class="synopsis">
+int PQputnbytes(PGconn *conn,
+ const char *buffer,
+ int nbytes);
+</pre><p>
+ </p><p>
+ This is exactly like <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a>, except that the data
+ buffer need not be null-terminated since the number of bytes to send is
+ specified directly. Use this procedure when sending binary data.
+ </p></dd><dt id="LIBPQ-PQENDCOPY"><span class="term"><code class="function">PQendcopy</code><a id="id-1.7.3.17.10.3.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Synchronizes with the server.
+</p><pre class="synopsis">
+int PQendcopy(PGconn *conn);
+</pre><p>
+ This function waits until the server has finished the copying.
+ It should either be issued when the last string has been sent
+ to the server using <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> or when the
+ last string has been received from the server using
+ <code class="function">PQgetline</code>. It must be issued or the server
+ will get <span class="quote">“<span class="quote">out of sync</span>”</span> with the client. Upon return
+ from this function, the server is ready to receive the next SQL
+ command. The return value is 0 on successful completion,
+ nonzero otherwise. (Use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to
+ retrieve details if the return value is nonzero.)
+ </p><p>
+ When using <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>, the application should
+ respond to a <code class="literal">PGRES_COPY_OUT</code> result by executing
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQGETLINE"><code class="function">PQgetline</code></a> repeatedly, followed by
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> after the terminator line is seen.
+ It should then return to the <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> loop
+ until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> returns a null pointer.
+ Similarly a <code class="literal">PGRES_COPY_IN</code> result is processed
+ by a series of <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a> calls followed by
+ <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>, then return to the
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> loop. This arrangement will
+ ensure that a <code class="command">COPY</code> command embedded in a series
+ of <acronym class="acronym">SQL</acronym> commands will be executed correctly.
+ </p><p>
+ Older applications are likely to submit a <code class="command">COPY</code>
+ via <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> and assume that the transaction
+ is done after <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a>. This will work
+ correctly only if the <code class="command">COPY</code> is the only
+ <acronym class="acronym">SQL</acronym> command in the command string.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-notify.html" title="34.9. Asynchronous Notification">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-control.html" title="34.11. Control Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.9. Asynchronous Notification </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.11. Control Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-envars.html b/doc/src/sgml/html/libpq-envars.html
new file mode 100644
index 0000000..e236bcc
--- /dev/null
+++ b/doc/src/sgml/html/libpq-envars.html
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.15. Environment Variables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-events.html" title="34.14. Event System" /><link rel="next" href="libpq-pgpass.html" title="34.16. The Password File" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.15. Environment Variables</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-events.html" title="34.14. Event System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-pgpass.html" title="34.16. The Password File">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-ENVARS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.15. Environment Variables</h2></div></div></div><a id="id-1.7.3.22.2" class="indexterm"></a><p>
+ The following environment variables can be used to select default
+ connection parameter values, which will be used by
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> and
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDB"><code class="function">PQsetdb</code></a> if no value is directly specified by the calling
+ code. These are useful to avoid hard-coding database connection
+ information into simple client applications, for example.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.1.1.1" class="indexterm"></a>
+ <code class="envar">PGHOST</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.2.1.1" class="indexterm"></a>
+ <code class="envar">PGHOSTADDR</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOSTADDR">hostaddr</a> connection parameter.
+ This can be set instead of or in addition to <code class="envar">PGHOST</code>
+ to avoid DNS lookup overhead.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.3.1.1" class="indexterm"></a>
+ <code class="envar">PGPORT</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-PORT">port</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.4.1.1" class="indexterm"></a>
+ <code class="envar">PGDATABASE</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-DBNAME">dbname</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.5.1.1" class="indexterm"></a>
+ <code class="envar">PGUSER</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-USER">user</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.6.1.1" class="indexterm"></a>
+ <code class="envar">PGPASSWORD</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-PASSWORD">password</a> 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
+ <span class="application">ps</span>; instead consider using a password file
+ (see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.7.1.1" class="indexterm"></a>
+ <code class="envar">PGPASSFILE</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-PASSFILE">passfile</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.8.1.1" class="indexterm"></a>
+ <code class="envar">PGCHANNELBINDING</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CHANNEL-BINDING">channel_binding</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.9.1.1" class="indexterm"></a>
+ <code class="envar">PGSERVICE</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SERVICE">service</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.10.1.1" class="indexterm"></a>
+ <code class="envar">PGSERVICEFILE</code> specifies the name of the per-user
+ connection service file
+ (see <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>).
+ Defaults to <code class="filename">~/.pg_service.conf</code>, or
+ <code class="filename">%APPDATA%\postgresql\.pg_service.conf</code> on
+ Microsoft Windows.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.11.1.1" class="indexterm"></a>
+ <code class="envar">PGOPTIONS</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-OPTIONS">options</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.12.1.1" class="indexterm"></a>
+ <code class="envar">PGAPPNAME</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-APPLICATION-NAME">application_name</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.13.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLMODE</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLMODE">sslmode</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.14.1.1" class="indexterm"></a>
+ <code class="envar">PGREQUIRESSL</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-REQUIRESSL">requiressl</a> connection parameter.
+ This environment variable is deprecated in favor of the
+ <code class="envar">PGSSLMODE</code> variable; setting both variables suppresses the
+ effect of this one.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.15.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLCOMPRESSION</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCOMPRESSION">sslcompression</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.16.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLCERT</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCERT">sslcert</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.17.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLKEY</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLKEY">sslkey</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.18.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLROOTCERT</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLROOTCERT">sslrootcert</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.19.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLCRL</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.20.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLCRLDIR</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.21.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLSNI</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLSNI">sslsni</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.22.1.1" class="indexterm"></a>
+ <code class="envar">PGREQUIREPEER</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-REQUIREPEER">requirepeer</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.23.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLMINPROTOCOLVERSION</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION">ssl_min_protocol_version</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.24.1.1" class="indexterm"></a>
+ <code class="envar">PGSSLMAXPROTOCOLVERSION</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION">ssl_max_protocol_version</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.25.1.1" class="indexterm"></a>
+ <code class="envar">PGGSSENCMODE</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE">gssencmode</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.26.1.1" class="indexterm"></a>
+ <code class="envar">PGKRBSRVNAME</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-KRBSRVNAME">krbsrvname</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.27.1.1" class="indexterm"></a>
+ <code class="envar">PGGSSLIB</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSLIB">gsslib</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.28.1.1" class="indexterm"></a>
+ <code class="envar">PGCONNECT_TIMEOUT</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">connect_timeout</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.29.1.1" class="indexterm"></a>
+ <code class="envar">PGCLIENTENCODING</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CLIENT-ENCODING">client_encoding</a> connection parameter.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.3.4.30.1.1" class="indexterm"></a>
+ <code class="envar">PGTARGETSESSIONATTRS</code> behaves the same as the <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS">target_session_attrs</a> connection parameter.
+ </p></li></ul></div><p>
+ </p><p>
+ The following environment variables can be used to specify default
+ behavior for each <span class="productname">PostgreSQL</span> session. (See
+ also the <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>
+ and <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>
+ commands for ways to set default behavior on a per-user or per-database
+ basis.)
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a id="id-1.7.3.22.4.4.1.1.1" class="indexterm"></a>
+ <code class="envar">PGDATESTYLE</code> sets the default style of date/time
+ representation. (Equivalent to <code class="literal">SET datestyle TO
+ ...</code>.)
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.4.4.2.1.1" class="indexterm"></a>
+ <code class="envar">PGTZ</code> sets the default time zone. (Equivalent to
+ <code class="literal">SET timezone TO ...</code>.)
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.4.4.3.1.1" class="indexterm"></a>
+ <code class="envar">PGGEQO</code> sets the default mode for the genetic query
+ optimizer. (Equivalent to <code class="literal">SET geqo TO ...</code>.)
+ </p></li></ul></div><p>
+
+ Refer to the <acronym class="acronym">SQL</acronym> command <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>
+ for information on correct values for these
+ environment variables.
+ </p><p>
+ The following environment variables determine internal behavior of
+ <span class="application">libpq</span>; they override compiled-in defaults.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a id="id-1.7.3.22.5.2.1.1.1" class="indexterm"></a>
+ <code class="envar">PGSYSCONFDIR</code> sets the directory containing the
+ <code class="filename">pg_service.conf</code> file and in a future version
+ possibly other system-wide configuration files.
+ </p></li><li class="listitem"><p>
+ <a id="id-1.7.3.22.5.2.2.1.1" class="indexterm"></a>
+ <code class="envar">PGLOCALEDIR</code> sets the directory containing the
+ <code class="literal">locale</code> files for message localization.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-events.html" title="34.14. Event System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-pgpass.html" title="34.16. The Password File">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.14. Event System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.16. The Password File</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-events.html b/doc/src/sgml/html/libpq-events.html
new file mode 100644
index 0000000..5bf9c3c
--- /dev/null
+++ b/doc/src/sgml/html/libpq-events.html
@@ -0,0 +1,425 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.14. Event System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-notice-processing.html" title="34.13. Notice Processing" /><link rel="next" href="libpq-envars.html" title="34.15. Environment Variables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.14. Event System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-notice-processing.html" title="34.13. Notice Processing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-envars.html" title="34.15. Environment Variables">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-EVENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.14. Event System</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-TYPES">34.14.1. Event Types</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-PROC">34.14.2. Event Callback Procedure</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-FUNCS">34.14.3. Event Support Functions</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-EXAMPLE">34.14.4. Event Example</a></span></dt></dl></div><p>
+ <span class="application">libpq</span>'s event system is designed to notify
+ registered event handlers about interesting
+ <span class="application">libpq</span> events, such as the creation or
+ destruction of <code class="structname">PGconn</code> and
+ <code class="structname">PGresult</code> objects. A principal use case is that
+ this allows applications to associate their own data with a
+ <code class="structname">PGconn</code> or <code class="structname">PGresult</code>
+ and ensure that that data is freed at an appropriate time.
+ </p><p>
+ Each registered event handler is associated with two pieces of data,
+ known to <span class="application">libpq</span> only as opaque <code class="literal">void *</code>
+ pointers. There is a <em class="firstterm">pass-through</em> pointer that is provided
+ by the application when the event handler is registered with a
+ <code class="structname">PGconn</code>. The pass-through pointer never changes for the
+ life of the <code class="structname">PGconn</code> and all <code class="structname">PGresult</code>s
+ generated from it; so if used, it must point to long-lived data.
+ In addition there is an <em class="firstterm">instance data</em> pointer, which starts
+ out <code class="symbol">NULL</code> in every <code class="structname">PGconn</code> and <code class="structname">PGresult</code>.
+ This pointer can be manipulated using the
+ <a class="xref" href="libpq-events.html#LIBPQ-PQINSTANCEDATA"><code class="function">PQinstanceData</code></a>,
+ <a class="xref" href="libpq-events.html#LIBPQ-PQSETINSTANCEDATA"><code class="function">PQsetInstanceData</code></a>,
+ <a class="xref" href="libpq-events.html#LIBPQ-PQRESULTINSTANCEDATA"><code class="function">PQresultInstanceData</code></a> and
+ <a class="xref" href="libpq-events.html#LIBPQ-PQRESULTSETINSTANCEDATA"><code class="function">PQresultSetInstanceData</code></a> functions. Note that
+ unlike the pass-through pointer, instance data of a <code class="structname">PGconn</code>
+ is not automatically inherited by <code class="structname">PGresult</code>s created from
+ it. <span class="application">libpq</span> does not know what pass-through
+ and instance data pointers point to (if anything) and will never attempt
+ to free them — that is the responsibility of the event handler.
+ </p><div class="sect2" id="LIBPQ-EVENTS-TYPES"><div class="titlepage"><div><div><h3 class="title">34.14.1. Event Types</h3></div></div></div><p>
+ The enum <code class="literal">PGEventId</code> names the types of events handled by
+ the event system. All its values have names beginning with
+ <code class="literal">PGEVT</code>. For each event type, there is a corresponding
+ event info structure that carries the parameters passed to the event
+ handlers. The event types are:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PGEVT-REGISTER"><span class="term"><code class="literal">PGEVT_REGISTER</code></span></dt><dd><p>
+ The register event occurs when <a class="xref" href="libpq-events.html#LIBPQ-PQREGISTEREVENTPROC"><code class="function">PQregisterEventProc</code></a>
+ is called. It is the ideal time to initialize any
+ <code class="literal">instanceData</code> an event procedure may need. Only one
+ register event will be fired per event handler per connection. If the
+ event procedure fails (returns zero), the registration is cancelled.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ PGconn *conn;
+} PGEventRegister;
+</pre><p>
+
+ When a <code class="literal">PGEVT_REGISTER</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventRegister *</code>. This structure contains a
+ <code class="structname">PGconn</code> that should be in the
+ <code class="literal">CONNECTION_OK</code> status; guaranteed if one calls
+ <a class="xref" href="libpq-events.html#LIBPQ-PQREGISTEREVENTPROC"><code class="function">PQregisterEventProc</code></a> right after obtaining a good
+ <code class="structname">PGconn</code>. When returning a failure code, all
+ cleanup must be performed as no <code class="literal">PGEVT_CONNDESTROY</code>
+ event will be sent.
+ </p></dd><dt id="LIBPQ-PGEVT-CONNRESET"><span class="term"><code class="literal">PGEVT_CONNRESET</code></span></dt><dd><p>
+ The connection reset event is fired on completion of
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> or <code class="function">PQresetPoll</code>. In
+ both cases, the event is only fired if the reset was successful.
+ The return value of the event procedure is ignored
+ in <span class="productname">PostgreSQL</span> v15 and later.
+ With earlier versions, however, it's important to return success
+ (nonzero) or the connection will be aborted.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ PGconn *conn;
+} PGEventConnReset;
+</pre><p>
+
+ When a <code class="literal">PGEVT_CONNRESET</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventConnReset *</code>. Although the contained
+ <code class="structname">PGconn</code> was just reset, all event data remains
+ unchanged. This event should be used to reset/reload/requery any
+ associated <code class="literal">instanceData</code>. Note that even if the
+ event procedure fails to process <code class="literal">PGEVT_CONNRESET</code>, it will
+ still receive a <code class="literal">PGEVT_CONNDESTROY</code> event when the connection
+ is closed.
+ </p></dd><dt id="LIBPQ-PGEVT-CONNDESTROY"><span class="term"><code class="literal">PGEVT_CONNDESTROY</code></span></dt><dd><p>
+ The connection destroy event is fired in response to
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>. It is the event procedure's
+ responsibility to properly clean up its event data as libpq has no
+ ability to manage this memory. Failure to clean up will lead
+ to memory leaks.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ PGconn *conn;
+} PGEventConnDestroy;
+</pre><p>
+
+ When a <code class="literal">PGEVT_CONNDESTROY</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventConnDestroy *</code>. This event is fired
+ prior to <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> performing any other cleanup.
+ The return value of the event procedure is ignored since there is no
+ way of indicating a failure from <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>. Also,
+ an event procedure failure should not abort the process of cleaning up
+ unwanted memory.
+ </p></dd><dt id="LIBPQ-PGEVT-RESULTCREATE"><span class="term"><code class="literal">PGEVT_RESULTCREATE</code></span></dt><dd><p>
+ The result creation event is fired in response to any query execution
+ function that generates a result, including
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>. This event will only be fired after
+ the result has been created successfully.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ PGconn *conn;
+ PGresult *result;
+} PGEventResultCreate;
+</pre><p>
+
+ When a <code class="literal">PGEVT_RESULTCREATE</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventResultCreate *</code>. The
+ <em class="parameter"><code>conn</code></em> is the connection used to generate the
+ result. This is the ideal place to initialize any
+ <code class="literal">instanceData</code> that needs to be associated with the
+ result. If an event procedure fails (returns zero), that event
+ procedure will be ignored for the remaining lifetime of the result;
+ that is, it will not receive <code class="literal">PGEVT_RESULTCOPY</code>
+ or <code class="literal">PGEVT_RESULTDESTROY</code> events for this result or
+ results copied from it.
+ </p></dd><dt id="LIBPQ-PGEVT-RESULTCOPY"><span class="term"><code class="literal">PGEVT_RESULTCOPY</code></span></dt><dd><p>
+ The result copy event is fired in response to
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQCOPYRESULT"><code class="function">PQcopyResult</code></a>. This event will only be fired after
+ the copy is complete. Only event procedures that have
+ successfully handled the <code class="literal">PGEVT_RESULTCREATE</code>
+ or <code class="literal">PGEVT_RESULTCOPY</code> event for the source result
+ will receive <code class="literal">PGEVT_RESULTCOPY</code> events.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ const PGresult *src;
+ PGresult *dest;
+} PGEventResultCopy;
+</pre><p>
+
+ When a <code class="literal">PGEVT_RESULTCOPY</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventResultCopy *</code>. The
+ <em class="parameter"><code>src</code></em> result is what was copied while the
+ <em class="parameter"><code>dest</code></em> result is the copy destination. This event
+ can be used to provide a deep copy of <code class="literal">instanceData</code>,
+ since <code class="literal">PQcopyResult</code> cannot do that. If an event
+ procedure fails (returns zero), that event procedure will be
+ ignored for the remaining lifetime of the new result; that is, it
+ will not receive <code class="literal">PGEVT_RESULTCOPY</code>
+ or <code class="literal">PGEVT_RESULTDESTROY</code> events for that result or
+ results copied from it.
+ </p></dd><dt id="LIBPQ-PGEVT-RESULTDESTROY"><span class="term"><code class="literal">PGEVT_RESULTDESTROY</code></span></dt><dd><p>
+ The result destroy event is fired in response to a
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>. It is the event procedure's
+ responsibility to properly clean up its event data as libpq has no
+ ability to manage this memory. Failure to clean up will lead
+ to memory leaks.
+
+</p><pre class="synopsis">
+typedef struct
+{
+ PGresult *result;
+} PGEventResultDestroy;
+</pre><p>
+
+ When a <code class="literal">PGEVT_RESULTDESTROY</code> event is received, the
+ <em class="parameter"><code>evtInfo</code></em> pointer should be cast to a
+ <code class="structname">PGEventResultDestroy *</code>. This event is fired
+ prior to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> performing any other cleanup.
+ The return value of the event procedure is ignored since there is no
+ way of indicating a failure from <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>. Also,
+ an event procedure failure should not abort the process of cleaning up
+ unwanted memory.
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EVENTS-PROC"><div class="titlepage"><div><div><h3 class="title">34.14.2. Event Callback Procedure</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PGEVENTPROC"><span class="term"><code class="literal">PGEventProc</code><a id="id-1.7.3.21.5.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ <code class="literal">PGEventProc</code> is a typedef for a pointer to an
+ event procedure, that is, the user callback function that receives
+ events from libpq. The signature of an event procedure must be
+
+</p><pre class="synopsis">
+int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
+</pre><p>
+
+ The <em class="parameter"><code>evtId</code></em> parameter indicates which
+ <code class="literal">PGEVT</code> event occurred. The
+ <em class="parameter"><code>evtInfo</code></em> pointer must be cast to the appropriate
+ structure type to obtain further information about the event.
+ The <em class="parameter"><code>passThrough</code></em> parameter is the pointer
+ provided to <a class="xref" href="libpq-events.html#LIBPQ-PQREGISTEREVENTPROC"><code class="function">PQregisterEventProc</code></a> when the event
+ procedure was registered. The function should return a non-zero value
+ if it succeeds and zero if it fails.
+ </p><p>
+ A particular event procedure can be registered only once in any
+ <code class="structname">PGconn</code>. This is because the address of the procedure
+ is used as a lookup key to identify the associated instance data.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ On Windows, functions can have two different addresses: one visible
+ from outside a DLL and another visible from inside the DLL. One
+ should be careful that only one of these addresses is used with
+ <span class="application">libpq</span>'s event-procedure functions, else confusion will
+ result. The simplest rule for writing code that will work is to
+ ensure that event procedures are declared <code class="literal">static</code>. If the
+ procedure's address must be available outside its own source file,
+ expose a separate function to return the address.
+ </p></div></dd></dl></div></div><div class="sect2" id="LIBPQ-EVENTS-FUNCS"><div class="titlepage"><div><div><h3 class="title">34.14.3. Event Support Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQREGISTEREVENTPROC"><span class="term"><code class="function">PQregisterEventProc</code><a id="id-1.7.3.21.6.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Registers an event callback procedure with libpq.
+
+</p><pre class="synopsis">
+int PQregisterEventProc(PGconn *conn, PGEventProc proc,
+ const char *name, void *passThrough);
+</pre><p>
+ </p><p>
+ An event procedure must be registered once on each
+ <code class="structname">PGconn</code> you want to receive events about. There is no
+ limit, other than memory, on the number of event procedures that
+ can be registered with a connection. The function returns a non-zero
+ value if it succeeds and zero if it fails.
+ </p><p>
+ The <em class="parameter"><code>proc</code></em> argument will be called when a libpq
+ event is fired. Its memory address is also used to lookup
+ <code class="literal">instanceData</code>. The <em class="parameter"><code>name</code></em>
+ argument is used to refer to the event procedure in error messages.
+ This value cannot be <code class="symbol">NULL</code> or a zero-length string. The name string is
+ copied into the <code class="structname">PGconn</code>, so what is passed need not be
+ long-lived. The <em class="parameter"><code>passThrough</code></em> pointer is passed
+ to the <em class="parameter"><code>proc</code></em> whenever an event occurs. This
+ argument can be <code class="symbol">NULL</code>.
+ </p></dd><dt id="LIBPQ-PQSETINSTANCEDATA"><span class="term"><code class="function">PQsetInstanceData</code><a id="id-1.7.3.21.6.2.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets the connection <em class="parameter"><code>conn</code></em>'s <code class="literal">instanceData</code>
+ for procedure <em class="parameter"><code>proc</code></em> to <em class="parameter"><code>data</code></em>. This
+ returns non-zero for success and zero for failure. (Failure is
+ only possible if <em class="parameter"><code>proc</code></em> has not been properly
+ registered in <em class="parameter"><code>conn</code></em>.)
+
+</p><pre class="synopsis">
+int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQINSTANCEDATA"><span class="term"><code class="function">PQinstanceData</code><a id="id-1.7.3.21.6.2.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the
+ connection <em class="parameter"><code>conn</code></em>'s <code class="literal">instanceData</code>
+ associated with procedure <em class="parameter"><code>proc</code></em>,
+ or <code class="symbol">NULL</code> if there is none.
+
+</p><pre class="synopsis">
+void *PQinstanceData(const PGconn *conn, PGEventProc proc);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQRESULTSETINSTANCEDATA"><span class="term"><code class="function">PQresultSetInstanceData</code><a id="id-1.7.3.21.6.2.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets the result's <code class="literal">instanceData</code>
+ for <em class="parameter"><code>proc</code></em> to <em class="parameter"><code>data</code></em>. This returns
+ non-zero for success and zero for failure. (Failure is only
+ possible if <em class="parameter"><code>proc</code></em> has not been properly registered
+ in the result.)
+
+</p><pre class="synopsis">
+int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);
+</pre><p>
+ </p><p>
+ Beware that any storage represented by <em class="parameter"><code>data</code></em>
+ will not be accounted for by <a class="xref" href="libpq-misc.html#LIBPQ-PQRESULTMEMORYSIZE"><code class="function">PQresultMemorySize</code></a>,
+ unless it is allocated using <a class="xref" href="libpq-misc.html#LIBPQ-PQRESULTALLOC"><code class="function">PQresultAlloc</code></a>.
+ (Doing so is recommendable because it eliminates the need to free
+ such storage explicitly when the result is destroyed.)
+ </p></dd><dt id="LIBPQ-PQRESULTINSTANCEDATA"><span class="term"><code class="function">PQresultInstanceData</code><a id="id-1.7.3.21.6.2.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the result's <code class="literal">instanceData</code> associated with <em class="parameter"><code>proc</code></em>, or <code class="symbol">NULL</code>
+ if there is none.
+
+</p><pre class="synopsis">
+void *PQresultInstanceData(const PGresult *res, PGEventProc proc);
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EVENTS-EXAMPLE"><div class="titlepage"><div><div><h3 class="title">34.14.4. Event Example</h3></div></div></div><p>
+ Here is a skeleton example of managing private data associated with
+ libpq connections and results.
+ </p><pre class="programlisting">
+
+/* required header for libpq events (note: includes libpq-fe.h) */
+#include &lt;libpq-events.h&gt;
+
+/* The instanceData */
+typedef struct
+{
+ int n;
+ char *str;
+} mydata;
+
+/* PGEventProc */
+static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);
+
+int
+main(void)
+{
+ mydata *data;
+ PGresult *res;
+ PGconn *conn =
+ PQconnectdb("dbname=postgres options=-csearch_path=");
+
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ /* PQerrorMessage's result includes a trailing newline */
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ PQfinish(conn);
+ return 1;
+ }
+
+ /* called once on any connection that should receive events.
+ * Sends a PGEVT_REGISTER to myEventProc.
+ */
+ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
+ {
+ fprintf(stderr, "Cannot register PGEventProc\n");
+ PQfinish(conn);
+ return 1;
+ }
+
+ /* conn instanceData is available */
+ data = PQinstanceData(conn, myEventProc);
+
+ /* Sends a PGEVT_RESULTCREATE to myEventProc */
+ res = PQexec(conn, "SELECT 1 + 1");
+
+ /* result instanceData is available */
+ data = PQresultInstanceData(res, myEventProc);
+
+ /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */
+ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);
+
+ /* result instanceData is available if PG_COPYRES_EVENTS was
+ * used during the PQcopyResult call.
+ */
+ data = PQresultInstanceData(res_copy, myEventProc);
+
+ /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */
+ PQclear(res);
+ PQclear(res_copy);
+
+ /* Sends a PGEVT_CONNDESTROY to myEventProc */
+ PQfinish(conn);
+
+ return 0;
+}
+
+static int
+myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
+{
+ switch (evtId)
+ {
+ case PGEVT_REGISTER:
+ {
+ PGEventRegister *e = (PGEventRegister *)evtInfo;
+ mydata *data = get_mydata(e-&gt;conn);
+
+ /* associate app specific data with connection */
+ PQsetInstanceData(e-&gt;conn, myEventProc, data);
+ break;
+ }
+
+ case PGEVT_CONNRESET:
+ {
+ PGEventConnReset *e = (PGEventConnReset *)evtInfo;
+ mydata *data = PQinstanceData(e-&gt;conn, myEventProc);
+
+ if (data)
+ memset(data, 0, sizeof(mydata));
+ break;
+ }
+
+ case PGEVT_CONNDESTROY:
+ {
+ PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
+ mydata *data = PQinstanceData(e-&gt;conn, myEventProc);
+
+ /* free instance data because the conn is being destroyed */
+ if (data)
+ free_mydata(data);
+ break;
+ }
+
+ case PGEVT_RESULTCREATE:
+ {
+ PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
+ mydata *conn_data = PQinstanceData(e-&gt;conn, myEventProc);
+ mydata *res_data = dup_mydata(conn_data);
+
+ /* associate app specific data with result (copy it from conn) */
+ PQresultSetInstanceData(e-&gt;result, myEventProc, res_data);
+ break;
+ }
+
+ case PGEVT_RESULTCOPY:
+ {
+ PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
+ mydata *src_data = PQresultInstanceData(e-&gt;src, myEventProc);
+ mydata *dest_data = dup_mydata(src_data);
+
+ /* associate app specific data with result (copy it from a result) */
+ PQresultSetInstanceData(e-&gt;dest, myEventProc, dest_data);
+ break;
+ }
+
+ case PGEVT_RESULTDESTROY:
+ {
+ PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
+ mydata *data = PQresultInstanceData(e-&gt;result, myEventProc);
+
+ /* free instance data because the result is being destroyed */
+ if (data)
+ free_mydata(data);
+ break;
+ }
+
+ /* unknown event ID, just return true. */
+ default:
+ break;
+ }
+
+ return true; /* event processing succeeded */
+}
+
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-notice-processing.html" title="34.13. Notice Processing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-envars.html" title="34.15. Environment Variables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.13. Notice Processing </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.15. Environment Variables</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-example.html b/doc/src/sgml/html/libpq-example.html
new file mode 100644
index 0000000..2546b4c
--- /dev/null
+++ b/doc/src/sgml/html/libpq-example.html
@@ -0,0 +1,529 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.22. Example Programs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-build.html" title="34.21. Building libpq Programs" /><link rel="next" href="largeobjects.html" title="Chapter 35. Large Objects" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.22. Example Programs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-build.html" title="34.21. Building libpq Programs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="largeobjects.html" title="Chapter 35. Large Objects">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.22. Example Programs</h2></div></div></div><p>
+ These examples and others can be found in the
+ directory <code class="filename">src/test/examples</code> in the source code
+ distribution.
+ </p><div class="example" id="LIBPQ-EXAMPLE-1"><p class="title"><strong>Example 34.1. <span class="application">libpq</span> Example Program 1</strong></p><div class="example-contents"><pre class="programlisting">
+
+/*
+ * src/test/examples/testlibpq.c
+ *
+ *
+ * testlibpq.c
+ *
+ * Test the C version of libpq, the PostgreSQL frontend library.
+ */
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include "libpq-fe.h"
+
+static void
+exit_nicely(PGconn *conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+int
+main(int argc, char **argv)
+{
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ int nFields;
+ int i,
+ j;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc &gt; 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* Set always-secure search path, so malicious users can't take control. */
+ res = PQexec(conn,
+ "SELECT pg_catalog.set_config('search_path', '', false)");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SET failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * Should PQclear PGresult whenever it is no longer needed to avoid memory
+ * leaks
+ */
+ PQclear(res);
+
+ /*
+ * Our test case here involves using a cursor, for which we must be inside
+ * a transaction block. We could do the whole thing with a single
+ * PQexec() of "select * from pg_database", but that's too trivial to make
+ * a good example.
+ */
+
+ /* Start a transaction block */
+ res = PQexec(conn, "BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ /*
+ * Fetch rows from pg_database, the system catalog of databases
+ */
+ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ res = PQexec(conn, "FETCH ALL in myportal");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /* first, print out the attribute names */
+ nFields = PQnfields(res);
+ for (i = 0; i &lt; nFields; i++)
+ printf("%-15s", PQfname(res, i));
+ printf("\n\n");
+
+ /* next, print out the rows */
+ for (i = 0; i &lt; PQntuples(res); i++)
+ {
+ for (j = 0; j &lt; nFields; j++)
+ printf("%-15s", PQgetvalue(res, i, j));
+ printf("\n");
+ }
+
+ PQclear(res);
+
+ /* close the portal ... we don't bother to check for errors ... */
+ res = PQexec(conn, "CLOSE myportal");
+ PQclear(res);
+
+ /* end the transaction */
+ res = PQexec(conn, "END");
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+ return 0;
+}
+
+</pre></div></div><br class="example-break" /><div class="example" id="LIBPQ-EXAMPLE-2"><p class="title"><strong>Example 34.2. <span class="application">libpq</span> Example Program 2</strong></p><div class="example-contents"><pre class="programlisting">
+
+/*
+ * src/test/examples/testlibpq2.c
+ *
+ *
+ * testlibpq2.c
+ * Test of the asynchronous notification interface
+ *
+ * Start this program, then from psql in another window do
+ * NOTIFY TBL2;
+ * Repeat four times to get this program to exit.
+ *
+ * Or, if you want to get fancy, try this:
+ * populate a database with the following commands
+ * (provided in src/test/examples/testlibpq2.sql):
+ *
+ * CREATE SCHEMA TESTLIBPQ2;
+ * SET search_path = TESTLIBPQ2;
+ * CREATE TABLE TBL1 (i int4);
+ * CREATE TABLE TBL2 (i int4);
+ * CREATE RULE r1 AS ON INSERT TO TBL1 DO
+ * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2);
+ *
+ * Start this program, then from psql do this four times:
+ *
+ * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10);
+ */
+
+#ifdef WIN32
+#include &lt;windows.h&gt;
+#endif
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;string.h&gt;
+#include &lt;errno.h&gt;
+#include &lt;sys/time.h&gt;
+#include &lt;sys/types.h&gt;
+#ifdef HAVE_SYS_SELECT_H
+#include &lt;sys/select.h&gt;
+#endif
+
+#include "libpq-fe.h"
+
+static void
+exit_nicely(PGconn *conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+int
+main(int argc, char **argv)
+{
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ PGnotify *notify;
+ int nnotifies;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc &gt; 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* Set always-secure search path, so malicious users can't take control. */
+ res = PQexec(conn,
+ "SELECT pg_catalog.set_config('search_path', '', false)");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SET failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * Should PQclear PGresult whenever it is no longer needed to avoid memory
+ * leaks
+ */
+ PQclear(res);
+
+ /*
+ * Issue LISTEN command to enable notifications from the rule's NOTIFY.
+ */
+ res = PQexec(conn, "LISTEN TBL2");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "LISTEN command failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ /* Quit after four notifies are received. */
+ nnotifies = 0;
+ while (nnotifies &lt; 4)
+ {
+ /*
+ * Sleep until something happens on the connection. We use select(2)
+ * to wait for input, but you could also use poll() or similar
+ * facilities.
+ */
+ int sock;
+ fd_set input_mask;
+
+ sock = PQsocket(conn);
+
+ if (sock &lt; 0)
+ break; /* shouldn't happen */
+
+ FD_ZERO(&amp;input_mask);
+ FD_SET(sock, &amp;input_mask);
+
+ if (select(sock + 1, &amp;input_mask, NULL, NULL, NULL) &lt; 0)
+ {
+ fprintf(stderr, "select() failed: %s\n", strerror(errno));
+ exit_nicely(conn);
+ }
+
+ /* Now check for input */
+ PQconsumeInput(conn);
+ while ((notify = PQnotifies(conn)) != NULL)
+ {
+ fprintf(stderr,
+ "ASYNC NOTIFY of '%s' received from backend PID %d\n",
+ notify-&gt;relname, notify-&gt;be_pid);
+ PQfreemem(notify);
+ nnotifies++;
+ PQconsumeInput(conn);
+ }
+ }
+
+ fprintf(stderr, "Done.\n");
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+ return 0;
+}
+
+</pre></div></div><br class="example-break" /><div class="example" id="LIBPQ-EXAMPLE-3"><p class="title"><strong>Example 34.3. <span class="application">libpq</span> Example Program 3</strong></p><div class="example-contents"><pre class="programlisting">
+
+/*
+ * src/test/examples/testlibpq3.c
+ *
+ *
+ * testlibpq3.c
+ * Test out-of-line parameters and binary I/O.
+ *
+ * Before running this, populate a database with the following commands
+ * (provided in src/test/examples/testlibpq3.sql):
+ *
+ * CREATE SCHEMA testlibpq3;
+ * SET search_path = testlibpq3;
+ * SET standard_conforming_strings = ON;
+ * CREATE TABLE test1 (i int4, t text, b bytea);
+ * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004');
+ * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000');
+ *
+ * The expected output is:
+ *
+ * tuple 0: got
+ * i = (4 bytes) 1
+ * t = (11 bytes) 'joe's place'
+ * b = (5 bytes) \000\001\002\003\004
+ *
+ * tuple 0: got
+ * i = (4 bytes) 2
+ * t = (8 bytes) 'ho there'
+ * b = (5 bytes) \004\003\002\001\000
+ */
+
+#ifdef WIN32
+#include &lt;windows.h&gt;
+#endif
+
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdint.h&gt;
+#include &lt;string.h&gt;
+#include &lt;sys/types.h&gt;
+#include "libpq-fe.h"
+
+/* for ntohl/htonl */
+#include &lt;netinet/in.h&gt;
+#include &lt;arpa/inet.h&gt;
+
+
+static void
+exit_nicely(PGconn *conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+/*
+ * This function prints a query result that is a binary-format fetch from
+ * a table defined as in the comment above. We split it out because the
+ * main() function uses it twice.
+ */
+static void
+show_binary_results(PGresult *res)
+{
+ int i,
+ j;
+ int i_fnum,
+ t_fnum,
+ b_fnum;
+
+ /* Use PQfnumber to avoid assumptions about field order in result */
+ i_fnum = PQfnumber(res, "i");
+ t_fnum = PQfnumber(res, "t");
+ b_fnum = PQfnumber(res, "b");
+
+ for (i = 0; i &lt; PQntuples(res); i++)
+ {
+ char *iptr;
+ char *tptr;
+ char *bptr;
+ int blen;
+ int ival;
+
+ /* Get the field values (we ignore possibility they are null!) */
+ iptr = PQgetvalue(res, i, i_fnum);
+ tptr = PQgetvalue(res, i, t_fnum);
+ bptr = PQgetvalue(res, i, b_fnum);
+
+ /*
+ * The binary representation of INT4 is in network byte order, which
+ * we'd better coerce to the local byte order.
+ */
+ ival = ntohl(*((uint32_t *) iptr));
+
+ /*
+ * The binary representation of TEXT is, well, text, and since libpq
+ * was nice enough to append a zero byte to it, it'll work just fine
+ * as a C string.
+ *
+ * The binary representation of BYTEA is a bunch of bytes, which could
+ * include embedded nulls so we have to pay attention to field length.
+ */
+ blen = PQgetlength(res, i, b_fnum);
+
+ printf("tuple %d: got\n", i);
+ printf(" i = (%d bytes) %d\n",
+ PQgetlength(res, i, i_fnum), ival);
+ printf(" t = (%d bytes) '%s'\n",
+ PQgetlength(res, i, t_fnum), tptr);
+ printf(" b = (%d bytes) ", blen);
+ for (j = 0; j &lt; blen; j++)
+ printf("\\%03o", bptr[j]);
+ printf("\n\n");
+ }
+}
+
+int
+main(int argc, char **argv)
+{
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ const char *paramValues[1];
+ int paramLengths[1];
+ int paramFormats[1];
+ uint32_t binaryIntVal;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc &gt; 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* Set always-secure search path, so malicious users can't take control. */
+ res = PQexec(conn, "SET search_path = testlibpq3");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "SET failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ /*
+ * The point of this program is to illustrate use of PQexecParams() with
+ * out-of-line parameters, as well as binary transmission of data.
+ *
+ * This first example transmits the parameters as text, but receives the
+ * results in binary format. By using out-of-line parameters we can avoid
+ * a lot of tedious mucking about with quoting and escaping, even though
+ * the data is text. Notice how we don't have to do anything special with
+ * the quote mark in the parameter value.
+ */
+
+ /* Here is our out-of-line parameter value */
+ paramValues[0] = "joe's place";
+
+ res = PQexecParams(conn,
+ "SELECT * FROM test1 WHERE t = $1",
+ 1, /* one param */
+ NULL, /* let the backend deduce param type */
+ paramValues,
+ NULL, /* don't need param lengths since text */
+ NULL, /* default to all text params */
+ 1); /* ask for binary results */
+
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ show_binary_results(res);
+
+ PQclear(res);
+
+ /*
+ * In this second example we transmit an integer parameter in binary form,
+ * and again retrieve the results in binary form.
+ *
+ * Although we tell PQexecParams we are letting the backend deduce
+ * parameter type, we really force the decision by casting the parameter
+ * symbol in the query text. This is a good safety measure when sending
+ * binary parameters.
+ */
+
+ /* Convert integer value "2" to network byte order */
+ binaryIntVal = htonl((uint32_t) 2);
+
+ /* Set up parameter arrays for PQexecParams */
+ paramValues[0] = (char *) &amp;binaryIntVal;
+ paramLengths[0] = sizeof(binaryIntVal);
+ paramFormats[0] = 1; /* binary */
+
+ res = PQexecParams(conn,
+ "SELECT * FROM test1 WHERE i = $1::int4",
+ 1, /* one param */
+ NULL, /* let the backend deduce param type */
+ paramValues,
+ paramLengths,
+ paramFormats,
+ 1); /* ask for binary results */
+
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ show_binary_results(res);
+
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+ return 0;
+}
+
+</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-build.html" title="34.21. Building libpq Programs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="largeobjects.html" title="Chapter 35. Large Objects">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.21. Building <span class="application">libpq</span> Programs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 35. Large Objects</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-exec.html b/doc/src/sgml/html/libpq-exec.html
new file mode 100644
index 0000000..ad92536
--- /dev/null
+++ b/doc/src/sgml/html/libpq-exec.html
@@ -0,0 +1,1050 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.3. Command Execution Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-status.html" title="34.2. Connection Status Functions" /><link rel="next" href="libpq-async.html" title="34.4. Asynchronous Command Processing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.3. Command Execution Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-status.html" title="34.2. Connection Status Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-EXEC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.3. Command Execution Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-MAIN">34.3.1. Main Functions</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">34.3.2. Retrieving Query Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">34.3.3. Retrieving Other Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">34.3.4. Escaping Strings for Inclusion in SQL Commands</a></span></dt></dl></div><p>
+ Once a connection to a database server has been successfully
+ established, the functions described here are used to perform
+ SQL queries and commands.
+ </p><div class="sect2" id="LIBPQ-EXEC-MAIN"><div class="titlepage"><div><div><h3 class="title">34.3.1. Main Functions</h3></div></div></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXEC"><span class="term"><code class="function">PQexec</code><a id="id-1.7.3.10.3.2.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a command to the server and waits for the result.
+
+</p><pre class="synopsis">
+PGresult *PQexec(PGconn *conn, const char *command);
+</pre><p>
+ </p><p>
+ Returns a <code class="structname">PGresult</code> pointer or possibly a null
+ pointer. A non-null pointer will generally be returned except in
+ out-of-memory conditions or serious errors such as inability to send
+ the command to the server. The <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> function
+ should be called to check the return value for any errors (including
+ the value of a null pointer, in which case it will return
+ <code class="symbol">PGRES_FATAL_ERROR</code>). Use
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more information about such
+ errors.
+ </p></dd></dl></div><p>
+
+ The command string can include multiple SQL commands
+ (separated by semicolons). Multiple queries sent in a single
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> call are processed in a single transaction, unless
+ there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>
+ commands included in the query string to divide it into multiple
+ transactions. (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="55.2.2.1. Multiple Statements in a Simple Query">Section 55.2.2.1</a>
+ for more details about how the server handles multi-query strings.)
+ Note however that the returned
+ <code class="structname">PGresult</code> structure describes only the result
+ of the last command executed from the string. Should one of the
+ commands fail, processing of the string stops with it and the returned
+ <code class="structname">PGresult</code> describes the error condition.
+ </p><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPARAMS"><span class="term"><code class="function">PQexecParams</code><a id="id-1.7.3.10.3.3.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a command to the server and waits for the result,
+ with the ability to pass parameters separately from the SQL
+ command text.
+
+</p><pre class="synopsis">
+PGresult *PQexecParams(PGconn *conn,
+ const char *command,
+ int nParams,
+ const Oid *paramTypes,
+ const char * const *paramValues,
+ const int *paramLengths,
+ const int *paramFormats,
+ int resultFormat);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> is like <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, but offers additional
+ functionality: parameter values can be specified separately from the command
+ string proper, and query results can be requested in either text or binary
+ format.
+ </p><p>
+ The function arguments are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>conn</code></em></span></dt><dd><p>
+ The connection object to send the command through.
+ </p></dd><dt><span class="term"><em class="parameter"><code>command</code></em></span></dt><dd><p>
+ The SQL command string to be executed. If parameters are used,
+ they are referred to in the command string as <code class="literal">$1</code>,
+ <code class="literal">$2</code>, etc.
+ </p></dd><dt><span class="term"><em class="parameter"><code>nParams</code></em></span></dt><dd><p>
+ The number of parameters supplied; it is the length of the arrays
+ <em class="parameter"><code>paramTypes[]</code></em>, <em class="parameter"><code>paramValues[]</code></em>,
+ <em class="parameter"><code>paramLengths[]</code></em>, and <em class="parameter"><code>paramFormats[]</code></em>. (The
+ array pointers can be <code class="symbol">NULL</code> when <em class="parameter"><code>nParams</code></em>
+ is zero.)
+ </p></dd><dt><span class="term"><em class="parameter"><code>paramTypes[]</code></em></span></dt><dd><p>
+ Specifies, by OID, the data types to be assigned to the
+ parameter symbols. If <em class="parameter"><code>paramTypes</code></em> is
+ <code class="symbol">NULL</code>, or any particular element in the array
+ is zero, the server infers a data type for the parameter symbol
+ in the same way it would do for an untyped literal string.
+ </p></dd><dt><span class="term"><em class="parameter"><code>paramValues[]</code></em></span></dt><dd><p>
+ Specifies the actual values of the parameters. A null pointer
+ in this array means the corresponding parameter is null;
+ otherwise the pointer points to a zero-terminated text string
+ (for text format) or binary data in the format expected by the
+ server (for binary format).
+ </p></dd><dt><span class="term"><em class="parameter"><code>paramLengths[]</code></em></span></dt><dd><p>
+ Specifies the actual data lengths of binary-format parameters.
+ It is ignored for null parameters and text-format parameters.
+ The array pointer can be null when there are no binary parameters.
+ </p></dd><dt><span class="term"><em class="parameter"><code>paramFormats[]</code></em></span></dt><dd><p>
+ Specifies whether parameters are text (put a zero in the
+ array entry for the corresponding parameter) or binary (put
+ a one in the array entry for the corresponding parameter).
+ If the array pointer is null then all parameters are presumed
+ to be text strings.
+ </p><p>
+ Values passed in binary format require knowledge of
+ the internal representation expected by the backend.
+ For example, integers must be passed in network byte
+ order. Passing <code class="type">numeric</code> values requires
+ knowledge of the server storage format, as implemented
+ in
+ <code class="filename">src/backend/utils/adt/numeric.c::numeric_send()</code> and
+ <code class="filename">src/backend/utils/adt/numeric.c::numeric_recv()</code>.
+ </p></dd><dt><span class="term"><em class="parameter"><code>resultFormat</code></em></span></dt><dd><p>
+ Specify zero to obtain results in text format, or one to obtain
+ results in binary format. (There is not currently a provision
+ to obtain different result columns in different formats,
+ although that is possible in the underlying protocol.)
+ </p></dd></dl></div><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ The primary advantage of <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> over
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> is that parameter values can be separated from the
+ command string, thus avoiding the need for tedious and error-prone
+ quoting and escaping.
+ </p><p>
+ Unlike <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> allows at most
+ one SQL command in the given string. (There can be semicolons in it,
+ but not more than one nonempty command.) This is a limitation of the
+ underlying protocol, but has some usefulness as an extra defense against
+ SQL-injection attacks.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Specifying parameter types via OIDs is tedious, particularly if you prefer
+ not to hard-wire particular OID values into your program. However, you can
+ avoid doing so even in cases where the server by itself cannot determine the
+ type of the parameter, or chooses a different type than you want. In the
+ SQL command text, attach an explicit cast to the parameter symbol to show what
+ data type you will send. For example:
+</p><pre class="programlisting">
+SELECT * FROM mytable WHERE x = $1::bigint;
+</pre><p>
+ This forces parameter <code class="literal">$1</code> to be treated as <code class="type">bigint</code>, whereas
+ by default it would be assigned the same type as <code class="literal">x</code>. Forcing the
+ parameter type decision, either this way or by specifying a numeric type OID,
+ is strongly recommended when sending parameter values in binary format, because
+ binary format has less redundancy than text format and so there is less chance
+ that the server will detect a type mismatch mistake for you.
+ </p></div><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPREPARE"><span class="term"><code class="function">PQprepare</code><a id="id-1.7.3.10.3.7.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a request to create a prepared statement with the
+ given parameters, and waits for completion.
+</p><pre class="synopsis">
+PGresult *PQprepare(PGconn *conn,
+ const char *stmtName,
+ const char *query,
+ int nParams,
+ const Oid *paramTypes);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a> creates a prepared statement for later
+ execution with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>. This feature allows
+ commands to be executed repeatedly without being parsed and
+ planned each time; see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for details.
+ </p><p>
+ The function creates a prepared statement named
+ <em class="parameter"><code>stmtName</code></em> from the <em class="parameter"><code>query</code></em> string, which
+ must contain a single SQL command. <em class="parameter"><code>stmtName</code></em> can be
+ <code class="literal">""</code> to create an unnamed statement, in which case any
+ pre-existing unnamed statement is automatically replaced; otherwise
+ it is an error if the statement name is already defined in the
+ current session. If any parameters are used, they are referred
+ to in the query as <code class="literal">$1</code>, <code class="literal">$2</code>, etc.
+ <em class="parameter"><code>nParams</code></em> is the number of parameters for which types
+ are pre-specified in the array <em class="parameter"><code>paramTypes[]</code></em>. (The
+ array pointer can be <code class="symbol">NULL</code> when
+ <em class="parameter"><code>nParams</code></em> is zero.) <em class="parameter"><code>paramTypes[]</code></em>
+ specifies, by OID, the data types to be assigned to the parameter
+ symbols. If <em class="parameter"><code>paramTypes</code></em> is <code class="symbol">NULL</code>,
+ or any particular element in the array is zero, the server assigns
+ a data type to the parameter symbol in the same way it would do
+ for an untyped literal string. Also, the query can use parameter
+ symbols with numbers higher than <em class="parameter"><code>nParams</code></em>; data types
+ will be inferred for these symbols as well. (See
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a> for a means to find out
+ what data types were inferred.)
+ </p><p>
+ As with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, the result is normally a
+ <code class="structname">PGresult</code> object whose contents indicate
+ server-side success or failure. A null result indicates
+ out-of-memory or inability to send the command at all. Use
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more information about
+ such errors.
+ </p></dd></dl></div><p>
+
+ Prepared statements for use with <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a> can also
+ be created by executing SQL <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>
+ statements. Also, although there is no <span class="application">libpq</span>
+ function for deleting a prepared statement, the SQL <a class="xref" href="sql-deallocate.html" title="DEALLOCATE"><span class="refentrytitle">DEALLOCATE</span></a> statement
+ can be used for that purpose.
+ </p><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQEXECPREPARED"><span class="term"><code class="function">PQexecPrepared</code><a id="id-1.7.3.10.3.8.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a request to execute a prepared statement with given
+ parameters, and waits for the result.
+</p><pre class="synopsis">
+PGresult *PQexecPrepared(PGconn *conn,
+ const char *stmtName,
+ int nParams,
+ const char * const *paramValues,
+ const int *paramLengths,
+ const int *paramFormats,
+ int resultFormat);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a> is like <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>,
+ but the command to be executed is specified by naming a
+ previously-prepared statement, instead of giving a query string.
+ This feature allows commands that will be used repeatedly to be
+ parsed and planned just once, rather than each time they are
+ executed. The statement must have been prepared previously in
+ the current session.
+ </p><p>
+ The parameters are identical to <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, except that the
+ name of a prepared statement is given instead of a query string, and the
+ <em class="parameter"><code>paramTypes[]</code></em> parameter is not present (it is not needed since
+ the prepared statement's parameter types were determined when it was created).
+ </p></dd><dt id="LIBPQ-PQDESCRIBEPREPARED"><span class="term"><code class="function">PQdescribePrepared</code><a id="id-1.7.3.10.3.8.1.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a request to obtain information about the specified
+ prepared statement, and waits for completion.
+</p><pre class="synopsis">
+PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a> allows an application to obtain
+ information about a previously prepared statement.
+ </p><p>
+ <em class="parameter"><code>stmtName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference
+ the unnamed statement, otherwise it must be the name of an existing
+ prepared statement. On success, a <code class="structname">PGresult</code> with
+ status <code class="literal">PGRES_COMMAND_OK</code> is returned. The
+ functions <a class="xref" href="libpq-exec.html#LIBPQ-PQNPARAMS"><code class="function">PQnparams</code></a> and
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQPARAMTYPE"><code class="function">PQparamtype</code></a> can be applied to this
+ <code class="structname">PGresult</code> to obtain information about the parameters
+ of the prepared statement, and the functions
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQNFIELDS"><code class="function">PQnfields</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQFNAME"><code class="function">PQfname</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>, etc. provide information about the
+ result columns (if any) of the statement.
+ </p></dd><dt id="LIBPQ-PQDESCRIBEPORTAL"><span class="term"><code class="function">PQdescribePortal</code><a id="id-1.7.3.10.3.8.1.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Submits a request to obtain information about the specified
+ portal, and waits for completion.
+</p><pre class="synopsis">
+PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a> allows an application to obtain
+ information about a previously created portal.
+ (<span class="application">libpq</span> does not provide any direct access to
+ portals, but you can use this function to inspect the properties
+ of a cursor created with a <code class="command">DECLARE CURSOR</code> SQL command.)
+ </p><p>
+ <em class="parameter"><code>portalName</code></em> can be <code class="literal">""</code> or <code class="symbol">NULL</code> to reference
+ the unnamed portal, otherwise it must be the name of an existing
+ portal. On success, a <code class="structname">PGresult</code> with status
+ <code class="literal">PGRES_COMMAND_OK</code> is returned. The functions
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQNFIELDS"><code class="function">PQnfields</code></a>, <a class="xref" href="libpq-exec.html#LIBPQ-PQFNAME"><code class="function">PQfname</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQFTYPE"><code class="function">PQftype</code></a>, etc. can be applied to the
+ <code class="structname">PGresult</code> to obtain information about the result
+ columns (if any) of the portal.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="structname">PGresult</code><a id="id-1.7.3.10.3.9.2" class="indexterm"></a>
+ structure encapsulates the result returned by the server.
+ <span class="application">libpq</span> application programmers should be
+ careful to maintain the <code class="structname">PGresult</code> abstraction.
+ Use the accessor functions below to get at the contents of
+ <code class="structname">PGresult</code>. Avoid directly referencing the
+ fields of the <code class="structname">PGresult</code> structure because they
+ are subject to change in the future.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQRESULTSTATUS"><span class="term"><code class="function">PQresultStatus</code><a id="id-1.7.3.10.3.9.7.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the result status of the command.
+</p><pre class="synopsis">
+ExecStatusType PQresultStatus(const PGresult *res);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> can return one of the following values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PGRES-EMPTY-QUERY"><span class="term"><code class="literal">PGRES_EMPTY_QUERY</code></span></dt><dd><p>
+ The string sent to the server was empty.
+ </p></dd><dt id="LIBPQ-PGRES-COMMAND-OK"><span class="term"><code class="literal">PGRES_COMMAND_OK</code></span></dt><dd><p>
+ Successful completion of a command returning no data.
+ </p></dd><dt id="LIBPQ-PGRES-TUPLES-OK"><span class="term"><code class="literal">PGRES_TUPLES_OK</code></span></dt><dd><p>
+ Successful completion of a command returning data (such as
+ a <code class="command">SELECT</code> or <code class="command">SHOW</code>).
+ </p></dd><dt id="LIBPQ-PGRES-COPY-OUT"><span class="term"><code class="literal">PGRES_COPY_OUT</code></span></dt><dd><p>
+ Copy Out (from server) data transfer started.
+ </p></dd><dt id="LIBPQ-PGRES-COPY-IN"><span class="term"><code class="literal">PGRES_COPY_IN</code></span></dt><dd><p>
+ Copy In (to server) data transfer started.
+ </p></dd><dt id="LIBPQ-PGRES-BAD-RESPONSE"><span class="term"><code class="literal">PGRES_BAD_RESPONSE</code></span></dt><dd><p>
+ The server's response was not understood.
+ </p></dd><dt id="LIBPQ-PGRES-NONFATAL-ERROR"><span class="term"><code class="literal">PGRES_NONFATAL_ERROR</code></span></dt><dd><p>
+ A nonfatal error (a notice or warning) occurred.
+ </p></dd><dt id="LIBPQ-PGRES-FATAL-ERROR"><span class="term"><code class="literal">PGRES_FATAL_ERROR</code></span></dt><dd><p>
+ A fatal error occurred.
+ </p></dd><dt id="LIBPQ-PGRES-COPY-BOTH"><span class="term"><code class="literal">PGRES_COPY_BOTH</code></span></dt><dd><p>
+ Copy In/Out (to and from server) data transfer started. This
+ feature is currently used only for streaming replication,
+ so this status should not occur in ordinary applications.
+ </p></dd><dt id="LIBPQ-PGRES-SINGLE-TUPLE"><span class="term"><code class="literal">PGRES_SINGLE_TUPLE</code></span></dt><dd><p>
+ The <code class="structname">PGresult</code> contains a single result tuple
+ from the current command. This status occurs only when
+ single-row mode has been selected for the query
+ (see <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>).
+ </p></dd><dt id="LIBPQ-PGRES-PIPELINE-SYNC"><span class="term"><code class="literal">PGRES_PIPELINE_SYNC</code></span></dt><dd><p>
+ The <code class="structname">PGresult</code> represents a
+ synchronization point in pipeline mode, requested by
+ <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a>.
+ This status occurs only when pipeline mode has been selected.
+ </p></dd><dt id="LIBPQ-PGRES-PIPELINE-ABORTED"><span class="term"><code class="literal">PGRES_PIPELINE_ABORTED</code></span></dt><dd><p>
+ The <code class="structname">PGresult</code> represents a pipeline that has
+ received an error from the server. <code class="function">PQgetResult</code>
+ must be called repeatedly, and each time it will return this status code
+ until the end of the current pipeline, at which point it will return
+ <code class="literal">PGRES_PIPELINE_SYNC</code> and normal processing can
+ resume.
+ </p></dd></dl></div><p>
+
+ If the result status is <code class="literal">PGRES_TUPLES_OK</code> or
+ <code class="literal">PGRES_SINGLE_TUPLE</code>, then
+ the functions described below can be used to retrieve the rows
+ returned by the query. Note that a <code class="command">SELECT</code>
+ command that happens to retrieve zero rows still shows
+ <code class="literal">PGRES_TUPLES_OK</code>.
+ <code class="literal">PGRES_COMMAND_OK</code> is for commands that can never
+ return rows (<code class="command">INSERT</code> or <code class="command">UPDATE</code>
+ without a <code class="literal">RETURNING</code> clause,
+ etc.). A response of <code class="literal">PGRES_EMPTY_QUERY</code> might
+ indicate a bug in the client software.
+ </p><p>
+ A result of status <code class="symbol">PGRES_NONFATAL_ERROR</code> will
+ never be returned directly by <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or other
+ query execution functions; results of this kind are instead passed
+ to the notice processor (see <a class="xref" href="libpq-notice-processing.html" title="34.13. Notice Processing">Section 34.13</a>).
+ </p></dd><dt id="LIBPQ-PQRESSTATUS"><span class="term"><code class="function">PQresStatus</code><a id="id-1.7.3.10.3.9.7.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Converts the enumerated type returned by
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> into a string constant describing the
+ status code. The caller should not free the result.
+
+</p><pre class="synopsis">
+char *PQresStatus(ExecStatusType status);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQRESULTERRORMESSAGE"><span class="term"><code class="function">PQresultErrorMessage</code><a id="id-1.7.3.10.3.9.7.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the error message associated with the command, or an empty string
+ if there was no error.
+</p><pre class="synopsis">
+char *PQresultErrorMessage(const PGresult *res);
+</pre><p>
+ If there was an error, the returned string will include a trailing
+ newline. The caller should not free the result directly. It will
+ be freed when the associated <code class="structname">PGresult</code> handle is
+ passed to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+ </p><p>
+ Immediately following a <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> or
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> call,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> (on the connection) will return
+ the same string as <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> (on
+ the result). However, a <code class="structname">PGresult</code> will
+ retain its error message until destroyed, whereas the connection's
+ error message will change when subsequent operations are done.
+ Use <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> when you want to
+ know the status associated with a particular
+ <code class="structname">PGresult</code>; use
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> when you want to know the
+ status from the latest operation on the connection.
+ </p></dd><dt id="LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><span class="term"><code class="function">PQresultVerboseErrorMessage</code><a id="id-1.7.3.10.3.9.7.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns a reformatted version of the error message associated with
+ a <code class="structname">PGresult</code> object.
+</p><pre class="synopsis">
+char *PQresultVerboseErrorMessage(const PGresult *res,
+ PGVerbosity verbosity,
+ PGContextVisibility show_context);
+</pre><p>
+ In some situations a client might wish to obtain a more detailed
+ version of a previously-reported error.
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> addresses this need
+ by computing the message that would have been produced
+ by <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> if the specified
+ verbosity settings had been in effect for the connection when the
+ given <code class="structname">PGresult</code> was generated. If
+ the <code class="structname">PGresult</code> is not an error result,
+ <span class="quote">“<span class="quote">PGresult is not an error result</span>”</span> is reported instead.
+ The returned string includes a trailing newline.
+ </p><p>
+ Unlike most other functions for extracting data from
+ a <code class="structname">PGresult</code>, the result of this function is a freshly
+ allocated string. The caller must free it
+ using <code class="function">PQfreemem()</code> when the string is no longer needed.
+ </p><p>
+ A NULL return is possible if there is insufficient memory.
+ </p></dd><dt id="LIBPQ-PQRESULTERRORFIELD"><span class="term"><code class="function">PQresultErrorField</code><a id="id-1.7.3.10.3.9.7.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns an individual field of an error report.
+</p><pre class="synopsis">
+char *PQresultErrorField(const PGresult *res, int fieldcode);
+</pre><p>
+ <em class="parameter"><code>fieldcode</code></em> is an error field identifier; see the symbols
+ listed below. <code class="symbol">NULL</code> is returned if the
+ <code class="structname">PGresult</code> is not an error or warning result,
+ or does not include the specified field. Field values will normally
+ not include a trailing newline. The caller should not free the
+ result directly. It will be freed when the
+ associated <code class="structname">PGresult</code> handle is passed to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+ </p><p>
+ The following field codes are available:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PG-DIAG-SEVERITY"><span class="term"><code class="symbol">PG_DIAG_SEVERITY</code></span></dt><dd><p>
+ The severity; the field contents are <code class="literal">ERROR</code>,
+ <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),
+ or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,
+ <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message), or
+ a localized translation of one of these. Always present.
+ </p></dd><dt id="LIBPQ-PG-DIAG-SEVERITY-NONLOCALIZED"><span class="term"><code class="symbol">PG_DIAG_SEVERITY_NONLOCALIZED</code></span></dt><dd><p>
+ The severity; the field contents are <code class="literal">ERROR</code>,
+ <code class="literal">FATAL</code>, or <code class="literal">PANIC</code> (in an error message),
+ or <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,
+ <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message).
+ This is identical to the <code class="symbol">PG_DIAG_SEVERITY</code> field except
+ that the contents are never localized. This is present only in
+ reports generated by <span class="productname">PostgreSQL</span> versions 9.6
+ and later.
+ </p></dd><dt id="LIBPQ-PG-DIAG-SQLSTATE"><span class="term"><code class="symbol">PG_DIAG_SQLSTATE</code><a id="id-1.7.3.10.3.9.7.5.2.2.1.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ The SQLSTATE code for the error. The SQLSTATE code identifies
+ the type of error that has occurred; it can be used by
+ 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 <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>. This field is not localizable,
+ and is always present.
+ </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-PRIMARY"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_PRIMARY</code></span></dt><dd><p>
+ The primary human-readable error message (typically one line).
+ Always present.
+ </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-DETAIL"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_DETAIL</code></span></dt><dd><p>
+ Detail: an optional secondary error message carrying more
+ detail about the problem. Might run to multiple lines.
+ </p></dd><dt id="LIBPQ-PG-DIAG-MESSAGE-HINT"><span class="term"><code class="symbol">PG_DIAG_MESSAGE_HINT</code></span></dt><dd><p>
+ Hint: an optional suggestion what to do about the problem.
+ This is intended to differ from detail in that it offers advice
+ (potentially inappropriate) rather than hard facts. Might
+ run to multiple lines.
+ </p></dd><dt id="LIBPQ-PG-DIAG-STATEMENT-POSITION"><span class="term"><code class="symbol">PG_DIAG_STATEMENT_POSITION</code></span></dt><dd><p>
+ A string containing a decimal integer indicating an error cursor
+ position as an index into the original statement string. The
+ first character has index 1, and positions are measured in
+ characters not bytes.
+ </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-POSITION"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_POSITION</code></span></dt><dd><p>
+ This is defined the same as the
+ <code class="symbol">PG_DIAG_STATEMENT_POSITION</code> field, but it is used
+ when the cursor position refers to an internally generated
+ command rather than the one submitted by the client. The
+ <code class="symbol">PG_DIAG_INTERNAL_QUERY</code> field will always appear when
+ this field appears.
+ </p></dd><dt id="LIBPQ-PG-DIAG-INTERNAL-QUERY"><span class="term"><code class="symbol">PG_DIAG_INTERNAL_QUERY</code></span></dt><dd><p>
+ The text of a failed internally-generated command. This could
+ be, for example, an SQL query issued by a PL/pgSQL function.
+ </p></dd><dt id="LIBPQ-PG-DIAG-CONTEXT"><span class="term"><code class="symbol">PG_DIAG_CONTEXT</code></span></dt><dd><p>
+ An indication of the context in which the error occurred.
+ Presently this includes a call stack traceback of active
+ procedural language functions and internally-generated queries.
+ The trace is one entry per line, most recent first.
+ </p></dd><dt id="LIBPQ-PG-DIAG-SCHEMA-NAME"><span class="term"><code class="symbol">PG_DIAG_SCHEMA_NAME</code></span></dt><dd><p>
+ If the error was associated with a specific database object,
+ the name of the schema containing that object, if any.
+ </p></dd><dt id="LIBPQ-PG-DIAG-TABLE-NAME"><span class="term"><code class="symbol">PG_DIAG_TABLE_NAME</code></span></dt><dd><p>
+ If the error was associated with a specific table, the name of the
+ table. (Refer to the schema name field for the name of the
+ table's schema.)
+ </p></dd><dt id="LIBPQ-PG-DIAG-COLUMN-NAME"><span class="term"><code class="symbol">PG_DIAG_COLUMN_NAME</code></span></dt><dd><p>
+ If the error was associated with a specific table column, the name
+ of the column. (Refer to the schema and table name fields to
+ identify the table.)
+ </p></dd><dt id="LIBPQ-PG-DIAG-DATATYPE-NAME"><span class="term"><code class="symbol">PG_DIAG_DATATYPE_NAME</code></span></dt><dd><p>
+ If the error was associated with a specific data type, the name of
+ the data type. (Refer to the schema name field for the name of
+ the data type's schema.)
+ </p></dd><dt id="LIBPQ-PG-DIAG-CONSTRAINT-NAME"><span class="term"><code class="symbol">PG_DIAG_CONSTRAINT_NAME</code></span></dt><dd><p>
+ If the error was associated with a specific constraint, the name
+ of the constraint. Refer to fields listed above for the
+ associated table or domain. (For this purpose, indexes are
+ treated as constraints, even if they weren't created with
+ constraint syntax.)
+ </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FILE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FILE</code></span></dt><dd><p>
+ The file name of the source-code location where the error was
+ reported.
+ </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-LINE"><span class="term"><code class="symbol">PG_DIAG_SOURCE_LINE</code></span></dt><dd><p>
+ The line number of the source-code location where the error
+ was reported.
+ </p></dd><dt id="LIBPQ-PG-DIAG-SOURCE-FUNCTION"><span class="term"><code class="symbol">PG_DIAG_SOURCE_FUNCTION</code></span></dt><dd><p>
+ The name of the source-code function reporting the error.
+ </p></dd></dl></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ 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 <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>. 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
+ ways. In the same vein, do not assume that these fields denote
+ contemporary objects in the current database.
+ </p></div><p>
+ The client is responsible for formatting displayed information to meet
+ its needs; in particular it should break long lines as needed.
+ Newline characters appearing in the error message fields should be
+ treated as paragraph breaks, not line breaks.
+ </p><p>
+ Errors generated internally by <span class="application">libpq</span> will
+ have severity and primary message, but typically no other fields.
+ </p><p>
+ Note that error fields are only available from
+ <code class="structname">PGresult</code> objects, not
+ <code class="structname">PGconn</code> objects; there is no
+ <code class="function">PQerrorField</code> function.
+ </p></dd><dt id="LIBPQ-PQCLEAR"><span class="term"><code class="function">PQclear</code><a id="id-1.7.3.10.3.9.7.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Frees the storage associated with a
+ <code class="structname">PGresult</code>. Every command result should be
+ freed via <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when it is no longer
+ needed.
+
+</p><pre class="synopsis">
+void PQclear(PGresult *res);
+</pre><p>
+ </p><p>
+ You can keep a <code class="structname">PGresult</code> object around for
+ as long as you need it; it does not go away when you issue a new
+ command, nor even if you close the connection. To get rid of it,
+ you must call <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>. Failure to do this
+ will result in memory leaks in your application.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="LIBPQ-EXEC-SELECT-INFO"><div class="titlepage"><div><div><h3 class="title">34.3.2. Retrieving Query Result Information</h3></div></div></div><p>
+ These functions are used to extract information from a
+ <code class="structname">PGresult</code> object that represents a successful
+ query result (that is, one that has status
+ <code class="literal">PGRES_TUPLES_OK</code> or <code class="literal">PGRES_SINGLE_TUPLE</code>).
+ They can also be used to extract
+ information from a successful Describe operation: a Describe's result
+ has all the same column information that actual execution of the query
+ would provide, but it has zero rows. For objects with other status values,
+ these functions will act as though the result has zero rows and zero columns.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQNTUPLES"><span class="term"><code class="function">PQntuples</code><a id="id-1.7.3.10.4.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the number of rows (tuples) in the query result.
+ (Note that <code class="structname">PGresult</code> objects are limited to no more
+ than <code class="literal">INT_MAX</code> rows, so an <code class="type">int</code> result is
+ sufficient.)
+
+</p><pre class="synopsis">
+int PQntuples(const PGresult *res);
+</pre><p>
+
+ </p></dd><dt id="LIBPQ-PQNFIELDS"><span class="term"><code class="function">PQnfields</code><a id="id-1.7.3.10.4.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the number of columns (fields) in each row of the query
+ result.
+
+</p><pre class="synopsis">
+int PQnfields(const PGresult *res);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQFNAME"><span class="term"><code class="function">PQfname</code><a id="id-1.7.3.10.4.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the column name associated with the given column number.
+ Column numbers start at 0. The caller should not free the result
+ directly. It will be freed when the associated
+ <code class="structname">PGresult</code> handle is passed to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+</p><pre class="synopsis">
+char *PQfname(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ <code class="symbol">NULL</code> is returned if the column number is out of range.
+ </p></dd><dt id="LIBPQ-PQFNUMBER"><span class="term"><code class="function">PQfnumber</code><a id="id-1.7.3.10.4.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the column number associated with the given column name.
+</p><pre class="synopsis">
+int PQfnumber(const PGresult *res,
+ const char *column_name);
+</pre><p>
+ </p><p>
+ -1 is returned if the given name does not match any column.
+ </p><p>
+ The given name is treated like an identifier in an SQL command,
+ that is, it is downcased unless double-quoted. For example, given
+ a query result generated from the SQL command:
+</p><pre class="programlisting">
+SELECT 1 AS FOO, 2 AS "BAR";
+</pre><p>
+ we would have the results:
+</p><pre class="programlisting">
+PQfname(res, 0) <em class="lineannotation"><span class="lineannotation">foo</span></em>
+PQfname(res, 1) <em class="lineannotation"><span class="lineannotation">BAR</span></em>
+PQfnumber(res, "FOO") <em class="lineannotation"><span class="lineannotation">0</span></em>
+PQfnumber(res, "foo") <em class="lineannotation"><span class="lineannotation">0</span></em>
+PQfnumber(res, "BAR") <em class="lineannotation"><span class="lineannotation">-1</span></em>
+PQfnumber(res, "\"BAR\"") <em class="lineannotation"><span class="lineannotation">1</span></em>
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQFTABLE"><span class="term"><code class="function">PQftable</code><a id="id-1.7.3.10.4.3.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the OID of the table from which the given column was
+ fetched. Column numbers start at 0.
+</p><pre class="synopsis">
+Oid PQftable(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ <code class="literal">InvalidOid</code> is returned if the column number is out of range,
+ or if the specified column is not a simple reference to a table column.
+ You can query the system table <code class="literal">pg_class</code> to determine
+ exactly which table is referenced.
+ </p><p>
+ The type <code class="type">Oid</code> and the constant
+ <code class="literal">InvalidOid</code> will be defined when you include
+ the <span class="application">libpq</span> header file. They will both
+ be some integer type.
+ </p></dd><dt id="LIBPQ-PQFTABLECOL"><span class="term"><code class="function">PQftablecol</code><a id="id-1.7.3.10.4.3.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the column number (within its table) of the column making
+ up the specified query result column. Query-result column numbers
+ start at 0, but table columns have nonzero numbers.
+</p><pre class="synopsis">
+int PQftablecol(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ Zero is returned if the column number is out of range, or if the
+ specified column is not a simple reference to a table column.
+ </p></dd><dt id="LIBPQ-PQFFORMAT"><span class="term"><code class="function">PQfformat</code><a id="id-1.7.3.10.4.3.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the format code indicating the format of the given
+ column. Column numbers start at 0.
+</p><pre class="synopsis">
+int PQfformat(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ Format code zero indicates textual data representation, while format
+ code one indicates binary representation. (Other codes are reserved
+ for future definition.)
+ </p></dd><dt id="LIBPQ-PQFTYPE"><span class="term"><code class="function">PQftype</code><a id="id-1.7.3.10.4.3.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the data type associated with the given column number.
+ The integer returned is the internal OID number of the type.
+ Column numbers start at 0.
+</p><pre class="synopsis">
+Oid PQftype(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ You can query the system table <code class="literal">pg_type</code> to
+ obtain the names and properties of the various data types. The
+ <acronym class="acronym">OID</acronym>s of the built-in data types are defined
+ in the file <code class="filename">catalog/pg_type_d.h</code>
+ in the <span class="productname">PostgreSQL</span>
+ installation's <code class="filename">include</code> directory.
+ </p></dd><dt id="LIBPQ-PQFMOD"><span class="term"><code class="function">PQfmod</code><a id="id-1.7.3.10.4.3.9.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the type modifier of the column associated with the
+ given column number. Column numbers start at 0.
+</p><pre class="synopsis">
+int PQfmod(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ The interpretation of modifier values is type-specific; they
+ typically indicate precision or size limits. The value -1 is
+ used to indicate <span class="quote">“<span class="quote">no information available</span>”</span>. Most data
+ types do not use modifiers, in which case the value is always
+ -1.
+ </p></dd><dt id="LIBPQ-PQFSIZE"><span class="term"><code class="function">PQfsize</code><a id="id-1.7.3.10.4.3.10.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the size in bytes of the column associated with the
+ given column number. Column numbers start at 0.
+</p><pre class="synopsis">
+int PQfsize(const PGresult *res,
+ int column_number);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQFSIZE"><code class="function">PQfsize</code></a> returns the space allocated for this column
+ in a database row, in other words the size of the server's
+ internal representation of the data type. (Accordingly, it is
+ not really very useful to clients.) A negative value indicates
+ the data type is variable-length.
+ </p></dd><dt id="LIBPQ-PQBINARYTUPLES"><span class="term"><code class="function">PQbinaryTuples</code><a id="id-1.7.3.10.4.3.11.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns 1 if the <code class="structname">PGresult</code> contains binary data
+ and 0 if it contains text data.
+</p><pre class="synopsis">
+int PQbinaryTuples(const PGresult *res);
+</pre><p>
+ </p><p>
+ This function is deprecated (except for its use in connection with
+ <code class="command">COPY</code>), because it is possible for a single
+ <code class="structname">PGresult</code> to contain text data in some columns and
+ binary data in others. <a class="xref" href="libpq-exec.html#LIBPQ-PQFFORMAT"><code class="function">PQfformat</code></a> is preferred.
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQBINARYTUPLES"><code class="function">PQbinaryTuples</code></a> returns 1 only if all columns of the
+ result are binary (format 1).
+ </p></dd><dt id="LIBPQ-PQGETVALUE"><span class="term"><code class="function">PQgetvalue</code><a id="id-1.7.3.10.4.3.12.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns a single field value of one row of a
+ <code class="structname">PGresult</code>. Row and column numbers start
+ at 0. The caller should not free the result directly. It will
+ be freed when the associated <code class="structname">PGresult</code> handle is
+ passed to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+</p><pre class="synopsis">
+char *PQgetvalue(const PGresult *res,
+ int row_number,
+ int column_number);
+</pre><p>
+ </p><p>
+ For data in text format, the value returned by
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> is a null-terminated character
+ string representation of the field value. For data in binary
+ format, the value is in the binary representation determined by
+ the data type's <code class="function">typsend</code> and <code class="function">typreceive</code>
+ functions. (The value is actually followed by a zero byte in
+ this case too, but that is not ordinarily useful, since the
+ value is likely to contain embedded nulls.)
+ </p><p>
+ An empty string is returned if the field value is null. See
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQGETISNULL"><code class="function">PQgetisnull</code></a> to distinguish null values from
+ empty-string values.
+ </p><p>
+ The pointer returned by <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> points
+ to storage that is part of the <code class="structname">PGresult</code>
+ structure. One should not modify the data it points to, and one
+ must explicitly copy the data into other storage if it is to be
+ used past the lifetime of the <code class="structname">PGresult</code>
+ structure itself.
+ </p></dd><dt id="LIBPQ-PQGETISNULL"><span class="term"><code class="function">PQgetisnull</code><a id="id-1.7.3.10.4.3.13.1.2" class="indexterm"></a><a id="id-1.7.3.10.4.3.13.1.3" class="indexterm"></a></span></dt><dd><p>
+ Tests a field for a null value. Row and column numbers start
+ at 0.
+</p><pre class="synopsis">
+int PQgetisnull(const PGresult *res,
+ int row_number,
+ int column_number);
+</pre><p>
+ </p><p>
+ This function returns 1 if the field is null and 0 if it
+ contains a non-null value. (Note that
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> will return an empty string,
+ not a null pointer, for a null field.)
+ </p></dd><dt id="LIBPQ-PQGETLENGTH"><span class="term"><code class="function">PQgetlength</code><a id="id-1.7.3.10.4.3.14.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the actual length of a field value in bytes. Row and
+ column numbers start at 0.
+</p><pre class="synopsis">
+int PQgetlength(const PGresult *res,
+ int row_number,
+ int column_number);
+</pre><p>
+ </p><p>
+ This is the actual data length for the particular data value,
+ that is, the size of the object pointed to by
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>. For text data format this is
+ the same as <code class="function">strlen()</code>. For binary format this is
+ essential information. Note that one should <span class="emphasis"><em>not</em></span>
+ rely on <a class="xref" href="libpq-exec.html#LIBPQ-PQFSIZE"><code class="function">PQfsize</code></a> to obtain the actual data
+ length.
+ </p></dd><dt id="LIBPQ-PQNPARAMS"><span class="term"><code class="function">PQnparams</code><a id="id-1.7.3.10.4.3.15.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the number of parameters of a prepared statement.
+</p><pre class="synopsis">
+int PQnparams(const PGresult *res);
+</pre><p>
+ </p><p>
+ This function is only useful when inspecting the result of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>. For other types of queries it
+ will return zero.
+ </p></dd><dt id="LIBPQ-PQPARAMTYPE"><span class="term"><code class="function">PQparamtype</code><a id="id-1.7.3.10.4.3.16.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the data type of the indicated statement parameter.
+ Parameter numbers start at 0.
+</p><pre class="synopsis">
+Oid PQparamtype(const PGresult *res, int param_number);
+</pre><p>
+ </p><p>
+ This function is only useful when inspecting the result of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>. For other types of queries it
+ will return zero.
+ </p></dd><dt id="LIBPQ-PQPRINT"><span class="term"><code class="function">PQprint</code><a id="id-1.7.3.10.4.3.17.1.2" class="indexterm"></a></span></dt><dd><p>
+ Prints out all the rows and, optionally, the column names to
+ the specified output stream.
+</p><pre class="synopsis">
+void PQprint(FILE *fout, /* output stream */
+ const PGresult *res,
+ const PQprintOpt *po);
+typedef struct
+{
+ pqbool header; /* print output field headings and row count */
+ pqbool align; /* fill align the fields */
+ pqbool standard; /* old brain dead format */
+ pqbool html3; /* output HTML tables */
+ pqbool expanded; /* expand tables */
+ pqbool pager; /* use pager for output if needed */
+ char *fieldSep; /* field separator */
+ char *tableOpt; /* attributes for HTML table element */
+ char *caption; /* HTML table caption */
+ char **fieldName; /* null-terminated array of replacement field names */
+} PQprintOpt;
+</pre><p>
+ </p><p>
+ This function was formerly used by <span class="application">psql</span>
+ to print query results, but this is no longer the case. Note
+ that it assumes all the data is in text format.
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-NONSELECT"><div class="titlepage"><div><div><h3 class="title">34.3.3. Retrieving Other Result Information</h3></div></div></div><p>
+ These functions are used to extract other information from
+ <code class="structname">PGresult</code> objects.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCMDSTATUS"><span class="term"><code class="function">PQcmdStatus</code><a id="id-1.7.3.10.5.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the command status tag from the SQL command that generated
+ the <code class="structname">PGresult</code>.
+</p><pre class="synopsis">
+char *PQcmdStatus(PGresult *res);
+</pre><p>
+ </p><p>
+ Commonly this is just the name of the command, but it might include
+ additional data such as the number of rows processed. The caller
+ should not free the result directly. It will be freed when the
+ associated <code class="structname">PGresult</code> handle is passed to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+ </p></dd><dt id="LIBPQ-PQCMDTUPLES"><span class="term"><code class="function">PQcmdTuples</code><a id="id-1.7.3.10.5.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the number of rows affected by the SQL command.
+</p><pre class="synopsis">
+char *PQcmdTuples(PGresult *res);
+</pre><p>
+ </p><p>
+ This function returns a string containing the number of rows
+ affected by the <acronym class="acronym">SQL</acronym> statement that generated the
+ <code class="structname">PGresult</code>. This function can only be used following
+ the execution of a <code class="command">SELECT</code>, <code class="command">CREATE TABLE AS</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">MERGE</code>, <code class="command">MOVE</code>, <code class="command">FETCH</code>,
+ or <code class="command">COPY</code> statement, or an <code class="command">EXECUTE</code> of a
+ prepared query that contains an <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ or <code class="command">MERGE</code> statement.
+ If the command that generated the <code class="structname">PGresult</code> was anything
+ else, <a class="xref" href="libpq-exec.html#LIBPQ-PQCMDTUPLES"><code class="function">PQcmdTuples</code></a> returns an empty string. The caller
+ should not free the return value directly. It will be freed when
+ the associated <code class="structname">PGresult</code> handle is passed to
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+ </p></dd><dt id="LIBPQ-PQOIDVALUE"><span class="term"><code class="function">PQoidValue</code><a id="id-1.7.3.10.5.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the OID<a id="id-1.7.3.10.5.3.3.2.1.1" class="indexterm"></a>
+ of the inserted row, if the <acronym class="acronym">SQL</acronym> command was an
+ <code class="command">INSERT</code> that inserted exactly one row into a table that
+ has OIDs, or a <code class="command">EXECUTE</code> of a prepared query containing
+ a suitable <code class="command">INSERT</code> statement. Otherwise, this function
+ returns <code class="literal">InvalidOid</code>. This function will also
+ return <code class="literal">InvalidOid</code> if the table affected by the
+ <code class="command">INSERT</code> statement does not contain OIDs.
+</p><pre class="synopsis">
+Oid PQoidValue(const PGresult *res);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQOIDSTATUS"><span class="term"><code class="function">PQoidStatus</code><a id="id-1.7.3.10.5.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ This function is deprecated in favor of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDVALUE"><code class="function">PQoidValue</code></a> and is not thread-safe.
+ It returns a string with the OID of the inserted row, while
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDVALUE"><code class="function">PQoidValue</code></a> returns the OID value.
+</p><pre class="synopsis">
+char *PQoidStatus(const PGresult *res);
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-EXEC-ESCAPE-STRING"><div class="titlepage"><div><div><h3 class="title">34.3.4. Escaping Strings for Inclusion in SQL Commands</h3></div></div></div><a id="id-1.7.3.10.6.2" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQESCAPELITERAL"><span class="term"><code class="function">PQescapeLiteral</code><a id="id-1.7.3.10.6.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+</p><pre class="synopsis">
+char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> escapes a string for
+ use within an SQL command. This is useful when inserting data
+ values as literal constants in SQL commands. Certain characters
+ (such as quotes and backslashes) must be escaped to prevent them
+ from being interpreted specially by the SQL parser.
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> performs this operation.
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> returns an escaped version of the
+ <em class="parameter"><code>str</code></em> parameter in memory allocated with
+ <code class="function">malloc()</code>. This memory should be freed using
+ <code class="function">PQfreemem()</code> when the result is no longer needed.
+ A terminating zero byte is not required, and should not be
+ counted in <em class="parameter"><code>length</code></em>. (If a terminating zero byte is found
+ before <em class="parameter"><code>length</code></em> bytes are processed,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> stops at the zero; the behavior is
+ thus rather like <code class="function">strncpy</code>.) The
+ return string has all special characters replaced so that they can
+ be properly processed by the <span class="productname">PostgreSQL</span>
+ string literal parser. A terminating zero byte is also added. The
+ single quotes that must surround <span class="productname">PostgreSQL</span>
+ string literals are included in the result string.
+ </p><p>
+ On error, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a> returns <code class="symbol">NULL</code> and a suitable
+ message is stored in the <em class="parameter"><code>conn</code></em> object.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ It is especially important to do proper escaping when handling
+ strings that were received from an untrustworthy source.
+ Otherwise there is a security risk: you are vulnerable to
+ <span class="quote">“<span class="quote">SQL injection</span>”</span> attacks wherein unwanted SQL commands are
+ fed to your database.
+ </p></div><p>
+ Note that it is neither necessary nor correct to do escaping when a data
+ value is passed as a separate parameter in <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a> or
+ its sibling routines.
+ </p></dd><dt id="LIBPQ-PQESCAPEIDENTIFIER"><span class="term"><code class="function">PQescapeIdentifier</code><a id="id-1.7.3.10.6.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+</p><pre class="synopsis">
+char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> escapes a string for
+ use as an SQL identifier, such as a table, column, or function name.
+ This is useful when a user-supplied identifier might contain
+ special characters that would otherwise not be interpreted as part
+ of the identifier by the SQL parser, or when the identifier might
+ contain upper case characters whose case should be preserved.
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> returns a version of the
+ <em class="parameter"><code>str</code></em> parameter escaped as an SQL identifier
+ in memory allocated with <code class="function">malloc()</code>. This memory must be
+ freed using <code class="function">PQfreemem()</code> when the result is no longer
+ needed. A terminating zero byte is not required, and should not be
+ counted in <em class="parameter"><code>length</code></em>. (If a terminating zero byte is found
+ before <em class="parameter"><code>length</code></em> bytes are processed,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> stops at the zero; the behavior is
+ thus rather like <code class="function">strncpy</code>.) The
+ return string has all special characters replaced so that it
+ will be properly processed as an SQL identifier. A terminating zero byte
+ is also added. The return string will also be surrounded by double
+ quotes.
+ </p><p>
+ On error, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER"><code class="function">PQescapeIdentifier</code></a> returns <code class="symbol">NULL</code> and a suitable
+ message is stored in the <em class="parameter"><code>conn</code></em> object.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ As with string literals, to prevent SQL injection attacks,
+ SQL identifiers must be escaped when they are received from an
+ untrustworthy source.
+ </p></div></dd><dt id="LIBPQ-PQESCAPESTRINGCONN"><span class="term"><code class="function">PQescapeStringConn</code><a id="id-1.7.3.10.6.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+</p><pre class="synopsis">
+size_t PQescapeStringConn(PGconn *conn,
+ char *to, const char *from, size_t length,
+ int *error);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> escapes string literals, much like
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a>. Unlike <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPELITERAL"><code class="function">PQescapeLiteral</code></a>,
+ the caller is responsible for providing an appropriately sized buffer.
+ Furthermore, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> does not generate the
+ single quotes that must surround <span class="productname">PostgreSQL</span> string
+ literals; they should be provided in the SQL command that the
+ result is inserted into. The parameter <em class="parameter"><code>from</code></em> points to
+ the first character of the string that is to be escaped, and the
+ <em class="parameter"><code>length</code></em> parameter gives the number of bytes in this
+ string. A terminating zero byte is not required, and should not be
+ counted in <em class="parameter"><code>length</code></em>. (If a terminating zero byte is found
+ before <em class="parameter"><code>length</code></em> bytes are processed,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> stops at the zero; the behavior is
+ thus rather like <code class="function">strncpy</code>.) <em class="parameter"><code>to</code></em> shall point
+ to a buffer that is able to hold at least one more byte than twice
+ the value of <em class="parameter"><code>length</code></em>, otherwise the behavior is undefined.
+ Behavior is likewise undefined if the <em class="parameter"><code>to</code></em> and
+ <em class="parameter"><code>from</code></em> strings overlap.
+ </p><p>
+ If the <em class="parameter"><code>error</code></em> parameter is not <code class="symbol">NULL</code>, then
+ <code class="literal">*error</code> is set to zero on success, nonzero on error.
+ Presently the only possible error conditions involve invalid multibyte
+ encoding in the source string. The output string is still generated
+ on error, but it can be expected that the server will reject it as
+ malformed. On error, a suitable message is stored in the
+ <em class="parameter"><code>conn</code></em> object, whether or not <em class="parameter"><code>error</code></em> is <code class="symbol">NULL</code>.
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> returns the number of bytes written
+ to <em class="parameter"><code>to</code></em>, not including the terminating zero byte.
+ </p></dd><dt id="LIBPQ-PQESCAPESTRING"><span class="term"><code class="function">PQescapeString</code><a id="id-1.7.3.10.6.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> is an older, deprecated version of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>.
+</p><pre class="synopsis">
+size_t PQescapeString (char *to, const char *from, size_t length);
+</pre><p>
+ </p><p>
+ The only difference from <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a> is that
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> does not take <code class="structname">PGconn</code>
+ or <em class="parameter"><code>error</code></em> parameters.
+ Because of this, it cannot adjust its behavior depending on the
+ connection properties (such as character encoding) and therefore
+ <span class="emphasis"><em>it might give the wrong results</em></span>. Also, it has no way
+ to report error conditions.
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRING"><code class="function">PQescapeString</code></a> can be used safely in
+ client programs that work with only one <span class="productname">PostgreSQL</span>
+ connection at a time (in this case it can find out what it needs to
+ know <span class="quote">“<span class="quote">behind the scenes</span>”</span>). In other contexts it is a security
+ hazard and should be avoided in favor of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>.
+ </p></dd><dt id="LIBPQ-PQESCAPEBYTEACONN"><span class="term"><code class="function">PQescapeByteaConn</code><a id="id-1.7.3.10.6.3.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Escapes binary data for use within an SQL command with the type
+ <code class="type">bytea</code>. As with <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPESTRINGCONN"><code class="function">PQescapeStringConn</code></a>,
+ this is only used when inserting data directly into an SQL command string.
+</p><pre class="synopsis">
+unsigned char *PQescapeByteaConn(PGconn *conn,
+ const unsigned char *from,
+ size_t from_length,
+ size_t *to_length);
+</pre><p>
+ </p><p>
+ Certain byte values must be escaped when used as part of a
+ <code class="type">bytea</code> literal in an <acronym class="acronym">SQL</acronym> statement.
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> escapes bytes using
+ either hex encoding or backslash escaping. See <a class="xref" href="datatype-binary.html" title="8.4. Binary Data Types">Section 8.4</a> for more information.
+ </p><p>
+ The <em class="parameter"><code>from</code></em> parameter points to the first
+ byte of the string that is to be escaped, and the
+ <em class="parameter"><code>from_length</code></em> parameter gives the number of
+ bytes in this binary string. (A terminating zero byte is
+ neither necessary nor counted.) The <em class="parameter"><code>to_length</code></em>
+ parameter points to a variable that will hold the resultant
+ escaped string length. This result string length includes the terminating
+ zero byte of the result.
+ </p><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> returns an escaped version of the
+ <em class="parameter"><code>from</code></em> parameter binary string in memory
+ allocated with <code class="function">malloc()</code>. This memory should be freed using
+ <code class="function">PQfreemem()</code> when the result is no longer needed. The
+ return string has all special characters replaced so that they can
+ be properly processed by the <span class="productname">PostgreSQL</span>
+ string literal parser, and the <code class="type">bytea</code> input function. A
+ terminating zero byte is also added. The single quotes that must
+ surround <span class="productname">PostgreSQL</span> string literals are
+ not part of the result string.
+ </p><p>
+ On error, a null pointer is returned, and a suitable error message
+ is stored in the <em class="parameter"><code>conn</code></em> object. Currently, the only
+ possible error is insufficient memory for the result string.
+ </p></dd><dt id="LIBPQ-PQESCAPEBYTEA"><span class="term"><code class="function">PQescapeBytea</code><a id="id-1.7.3.10.6.3.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> is an older, deprecated version of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a>.
+</p><pre class="synopsis">
+unsigned char *PQescapeBytea(const unsigned char *from,
+ size_t from_length,
+ size_t *to_length);
+</pre><p>
+ </p><p>
+ The only difference from <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> is that
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> does not take a <code class="structname">PGconn</code>
+ parameter. Because of this, <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a> can
+ only be used safely in client programs that use a single
+ <span class="productname">PostgreSQL</span> connection at a time (in this case
+ it can find out what it needs to know <span class="quote">“<span class="quote">behind the
+ scenes</span>”</span>). It <span class="emphasis"><em>might give the wrong results</em></span> if
+ used in programs that use multiple database connections (use
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a> in such cases).
+ </p></dd><dt id="LIBPQ-PQUNESCAPEBYTEA"><span class="term"><code class="function">PQunescapeBytea</code><a id="id-1.7.3.10.6.3.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Converts a string representation of binary data into binary data
+ — the reverse of <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>. This
+ is needed when retrieving <code class="type">bytea</code> data in text format,
+ but not when retrieving it in binary format.
+
+</p><pre class="synopsis">
+unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
+</pre><p>
+ </p><p>
+ The <em class="parameter"><code>from</code></em> parameter points to a string
+ such as might be returned by <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a> when applied
+ to a <code class="type">bytea</code> column. <a class="xref" href="libpq-exec.html#LIBPQ-PQUNESCAPEBYTEA"><code class="function">PQunescapeBytea</code></a>
+ converts this string representation into its binary representation.
+ It returns a pointer to a buffer allocated with
+ <code class="function">malloc()</code>, or <code class="symbol">NULL</code> on error, and puts the size of
+ the buffer in <em class="parameter"><code>to_length</code></em>. The result must be
+ freed using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> when it is no longer needed.
+ </p><p>
+ This conversion is not exactly the inverse of
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>, because the string is not expected
+ to be <span class="quote">“<span class="quote">escaped</span>”</span> when received from <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>.
+ In particular this means there is no need for string quoting considerations,
+ and so no need for a <code class="structname">PGconn</code> parameter.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-status.html" title="34.2. Connection Status Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.2. Connection Status Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.4. Asynchronous Command Processing</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-fastpath.html b/doc/src/sgml/html/libpq-fastpath.html
new file mode 100644
index 0000000..e0db72c
--- /dev/null
+++ b/doc/src/sgml/html/libpq-fastpath.html
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.8. The Fast-Path Interface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress" /><link rel="next" href="libpq-notify.html" title="34.9. Asynchronous Notification" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.8. The Fast-Path Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notify.html" title="34.9. Asynchronous Notification">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-FASTPATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.8. The Fast-Path Interface</h2></div></div></div><a id="id-1.7.3.15.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a fast-path interface
+ to send simple function calls to the server.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ This interface is somewhat obsolete, as one can achieve similar
+ performance and greater functionality by setting up a prepared
+ statement to define the function call. Then, executing the statement
+ with binary transmission of parameters and results substitutes for a
+ fast-path function call.
+ </p></div><p>
+ The function <code class="function" id="LIBPQ-PQFN">PQfn</code><a id="id-1.7.3.15.5.2" class="indexterm"></a>
+ requests execution of a server function via the fast-path interface:
+</p><pre class="synopsis">
+PGresult *PQfn(PGconn *conn,
+ int fnid,
+ int *result_buf,
+ int *result_len,
+ int result_is_int,
+ const PQArgBlock *args,
+ int nargs);
+
+typedef struct
+{
+ int len;
+ int isint;
+ union
+ {
+ int *ptr;
+ int integer;
+ } u;
+} PQArgBlock;
+</pre><p>
+ </p><p>
+ The <em class="parameter"><code>fnid</code></em> argument is the OID of the function to be
+ executed. <em class="parameter"><code>args</code></em> and <em class="parameter"><code>nargs</code></em> define the
+ parameters to be passed to the function; they must match the declared
+ function argument list. When the <em class="parameter"><code>isint</code></em> field of a
+ parameter structure is true, the <em class="parameter"><code>u.integer</code></em> value is sent
+ to the server as an integer of the indicated length (this must be
+ 2 or 4 bytes); proper byte-swapping occurs. When <em class="parameter"><code>isint</code></em>
+ is false, the indicated number of bytes at <em class="parameter"><code>*u.ptr</code></em> are
+ sent with no processing; the data must be in the format expected by
+ the server for binary transmission of the function's argument data
+ type. (The declaration of <em class="parameter"><code>u.ptr</code></em> as being of
+ type <code class="type">int *</code> is historical; it would be better to consider
+ it <code class="type">void *</code>.)
+ <em class="parameter"><code>result_buf</code></em> points to the buffer in which to place
+ the function's return value. The caller must have allocated sufficient
+ space to store the return value. (There is no check!) The actual result
+ length in bytes will be returned in the integer pointed to by
+ <em class="parameter"><code>result_len</code></em>. If a 2- or 4-byte integer result
+ is expected, set <em class="parameter"><code>result_is_int</code></em> to 1, otherwise
+ set it to 0. Setting <em class="parameter"><code>result_is_int</code></em> to 1 causes
+ <span class="application">libpq</span> to byte-swap the value if necessary, so that it
+ is delivered as a proper <code class="type">int</code> value for the client machine;
+ note that a 4-byte integer is delivered into <em class="parameter"><code>*result_buf</code></em>
+ for either allowed result size.
+ When <em class="parameter"><code>result_is_int</code></em> is 0, the binary-format byte string
+ sent by the server is returned unmodified. (In this case it's better
+ to consider <em class="parameter"><code>result_buf</code></em> as being of
+ type <code class="type">void *</code>.)
+ </p><p>
+ <code class="function">PQfn</code> always returns a valid
+ <code class="structname">PGresult</code> pointer, with
+ status <code class="literal">PGRES_COMMAND_OK</code> for success
+ or <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.
+ The result status should be
+ checked before the result is used. The caller is responsible for
+ freeing the <code class="structname">PGresult</code> with
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when it is no longer needed.
+ </p><p>
+ To pass a NULL argument to the function, set
+ the <em class="parameter"><code>len</code></em> field of that parameter structure
+ to <code class="literal">-1</code>; the <em class="parameter"><code>isint</code></em>
+ and <em class="parameter"><code>u</code></em> fields are then irrelevant.
+ </p><p>
+ If the function returns NULL, <em class="parameter"><code>*result_len</code></em> is set
+ to <code class="literal">-1</code>, and <em class="parameter"><code>*result_buf</code></em> is not
+ modified.
+ </p><p>
+ Note that it is not possible to handle set-valued results when using
+ this interface. Also, the function must be a plain function, not an
+ aggregate, window function, or procedure.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notify.html" title="34.9. Asynchronous Notification">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.7. Canceling Queries in Progress </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.9. Asynchronous Notification</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-ldap.html b/doc/src/sgml/html/libpq-ldap.html
new file mode 100644
index 0000000..8321032
--- /dev/null
+++ b/doc/src/sgml/html/libpq-ldap.html
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.18. LDAP Lookup of Connection Parameters</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-pgservice.html" title="34.17. The Connection Service File" /><link rel="next" href="libpq-ssl.html" title="34.19. SSL Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.18. LDAP Lookup of Connection Parameters</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-pgservice.html" title="34.17. The Connection Service File">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-ssl.html" title="34.19. SSL Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-LDAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.18. LDAP Lookup of Connection Parameters</h2></div></div></div><a id="id-1.7.3.25.2" class="indexterm"></a><p>
+ If <span class="application">libpq</span> has been compiled with LDAP support (option
+ <code class="literal"><code class="option">--with-ldap</code></code> for <code class="command">configure</code>)
+ it is possible to retrieve connection options like <code class="literal">host</code>
+ or <code class="literal">dbname</code> via LDAP from a central server.
+ The advantage is that if the connection parameters for a database change,
+ the connection information doesn't have to be updated on all client machines.
+ </p><p>
+ LDAP connection parameter lookup uses the connection service file
+ <code class="filename">pg_service.conf</code> (see <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>). A line in a
+ <code class="filename">pg_service.conf</code> stanza that starts with
+ <code class="literal">ldap://</code> will be recognized as an LDAP URL and an
+ LDAP query will be performed. The result must be a list of
+ <code class="literal">keyword = value</code> pairs which will be used to set
+ connection options. The URL must conform to
+ <a class="ulink" href="https://tools.ietf.org/html/rfc1959" target="_top">RFC 1959</a>
+ and be of the form
+</p><pre class="synopsis">
+ldap://[<em class="replaceable"><code>hostname</code></em>[:<em class="replaceable"><code>port</code></em>]]/<em class="replaceable"><code>search_base</code></em>?<em class="replaceable"><code>attribute</code></em>?<em class="replaceable"><code>search_scope</code></em>?<em class="replaceable"><code>filter</code></em>
+</pre><p>
+ where <em class="replaceable"><code>hostname</code></em> defaults to
+ <code class="literal">localhost</code> and <em class="replaceable"><code>port</code></em>
+ defaults to 389.
+ </p><p>
+ Processing of <code class="filename">pg_service.conf</code> is terminated after
+ a successful LDAP lookup, but is continued if the LDAP server cannot
+ be contacted. This is to provide a fallback with further LDAP URL
+ lines that point to different LDAP servers, classical <code class="literal">keyword
+ = value</code> pairs, or default connection options. If you would
+ rather get an error message in this case, add a syntactically incorrect
+ line after the LDAP URL.
+ </p><p>
+ A sample LDAP entry that has been created with the LDIF file
+</p><pre class="programlisting">
+version:1
+dn:cn=mydatabase,dc=mycompany,dc=com
+changetype:add
+objectclass:top
+objectclass:device
+cn:mydatabase
+description:host=dbserver.mycompany.com
+description:port=5439
+description:dbname=mydb
+description:user=mydb_user
+description:sslmode=require
+</pre><p>
+ might be queried with the following LDAP URL:
+</p><pre class="programlisting">
+ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase)
+</pre><p>
+ </p><p>
+ You can also mix regular service file entries with LDAP lookups.
+ A complete example for a stanza in <code class="filename">pg_service.conf</code>
+ would be:
+</p><pre class="programlisting">
+# only host and port are stored in LDAP, specify dbname and user explicitly
+[customerdb]
+dbname=customer
+user=appuser
+ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-pgservice.html" title="34.17. The Connection Service File">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-ssl.html" title="34.19. SSL Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.17. The Connection Service File </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.19. SSL Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-misc.html b/doc/src/sgml/html/libpq-misc.html
new file mode 100644
index 0000000..c9bc085
--- /dev/null
+++ b/doc/src/sgml/html/libpq-misc.html
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.12. Miscellaneous Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-control.html" title="34.11. Control Functions" /><link rel="next" href="libpq-notice-processing.html" title="34.13. Notice Processing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.12. Miscellaneous Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-control.html" title="34.11. Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="34.13. Notice Processing">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-MISC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.12. Miscellaneous Functions</h2></div></div></div><p>
+ As always, there are some functions that just don't fit anywhere.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQFREEMEM"><span class="term"><code class="function">PQfreemem</code><a id="id-1.7.3.19.3.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Frees memory allocated by <span class="application">libpq</span>.
+</p><pre class="synopsis">
+void PQfreemem(void *ptr);
+</pre><p>
+ </p><p>
+ Frees memory allocated by <span class="application">libpq</span>, particularly
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEACONN"><code class="function">PQescapeByteaConn</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQESCAPEBYTEA"><code class="function">PQescapeBytea</code></a>,
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQUNESCAPEBYTEA"><code class="function">PQunescapeBytea</code></a>,
+ and <code class="function">PQnotifies</code>.
+ It is particularly important that this function, rather than
+ <code class="function">free()</code>, be used on Microsoft Windows. This is because
+ allocating memory in a DLL and releasing it in the application works
+ only if multithreaded/single-threaded, release/debug, and static/dynamic
+ flags are the same for the DLL and the application. On non-Microsoft
+ Windows platforms, this function is the same as the standard library
+ function <code class="function">free()</code>.
+ </p></dd><dt id="LIBPQ-PQCONNINFOFREE"><span class="term"><code class="function">PQconninfoFree</code><a id="id-1.7.3.19.3.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Frees the data structures allocated by
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
+</p><pre class="synopsis">
+void PQconninfoFree(PQconninfoOption *connOptions);
+</pre><p>
+ </p><p>
+ A simple <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> will not do for this, since
+ the array contains references to subsidiary strings.
+ </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORDCONN"><span class="term"><code class="function">PQencryptPasswordConn</code><a id="id-1.7.3.19.3.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Prepares the encrypted form of a <span class="productname">PostgreSQL</span> password.
+</p><pre class="synopsis">
+char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
+</pre><p>
+ This function is intended to be used by client applications that
+ wish to send commands like <code class="literal">ALTER USER joe PASSWORD
+ 'pwd'</code>. It is good practice not to send the original cleartext
+ password in such a command, because it might be exposed in command
+ logs, activity displays, and so on. Instead, use this function to
+ convert the password to encrypted form before it is sent.
+ </p><p>
+ The <em class="parameter"><code>passwd</code></em> and <em class="parameter"><code>user</code></em> arguments
+ are the cleartext password, and the SQL name of the user it is for.
+ <em class="parameter"><code>algorithm</code></em> specifies the encryption algorithm
+ to use to encrypt the password. Currently supported algorithms are
+ <code class="literal">md5</code> and <code class="literal">scram-sha-256</code> (<code class="literal">on</code> and
+ <code class="literal">off</code> are also accepted as aliases for <code class="literal">md5</code>, for
+ compatibility with older server versions). Note that support for
+ <code class="literal">scram-sha-256</code> was introduced in <span class="productname">PostgreSQL</span>
+ version 10, and will not work correctly with older server versions. If
+ <em class="parameter"><code>algorithm</code></em> is <code class="symbol">NULL</code>, this function will query
+ the server for the current value of the
+ <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a> 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
+ <code class="varname">password_encryption</code> yourself before calling
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>, and pass that value as the
+ <em class="parameter"><code>algorithm</code></em>.
+ </p><p>
+ The return value is a string allocated by <code class="function">malloc</code>.
+ The caller can assume the string doesn't contain any special characters
+ that would require escaping. Use <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a> to free the
+ result when done with it. On error, returns <code class="symbol">NULL</code>, and
+ a suitable message is stored in the connection object.
+ </p></dd><dt id="LIBPQ-PQENCRYPTPASSWORD"><span class="term"><code class="function">PQencryptPassword</code><a id="id-1.7.3.19.3.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Prepares the md5-encrypted form of a <span class="productname">PostgreSQL</span> password.
+</p><pre class="synopsis">
+char *PQencryptPassword(const char *passwd, const char *user);
+</pre><p>
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> is an older, deprecated version of
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN"><code class="function">PQencryptPasswordConn</code></a>. The difference is that
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD"><code class="function">PQencryptPassword</code></a> does not
+ require a connection object, and <code class="literal">md5</code> is always used as the
+ encryption algorithm.
+ </p></dd><dt id="LIBPQ-PQMAKEEMPTYPGRESULT"><span class="term"><code class="function">PQmakeEmptyPGresult</code><a id="id-1.7.3.19.3.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Constructs an empty <code class="structname">PGresult</code> object with the given status.
+</p><pre class="synopsis">
+PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
+</pre><p>
+ </p><p>
+ This is <span class="application">libpq</span>'s internal function to allocate and
+ initialize an empty <code class="structname">PGresult</code> object. This
+ function returns <code class="symbol">NULL</code> if memory could not be allocated. It is
+ exported because some applications find it useful to generate result
+ objects (particularly objects with error status) themselves. If
+ <em class="parameter"><code>conn</code></em> is not null and <em class="parameter"><code>status</code></em>
+ indicates an error, the current error message of the specified
+ connection is copied into the <code class="structname">PGresult</code>.
+ Also, if <em class="parameter"><code>conn</code></em> is not null, any event procedures
+ registered in the connection are copied into the
+ <code class="structname">PGresult</code>. (They do not get
+ <code class="literal">PGEVT_RESULTCREATE</code> calls, but see
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQFIRERESULTCREATEEVENTS"><code class="function">PQfireResultCreateEvents</code></a>.)
+ Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> should eventually be called
+ on the object, just as with a <code class="structname">PGresult</code>
+ returned by <span class="application">libpq</span> itself.
+ </p></dd><dt id="LIBPQ-PQFIRERESULTCREATEEVENTS"><span class="term"><code class="function">PQfireResultCreateEvents</code><a id="id-1.7.3.19.3.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Fires a <code class="literal">PGEVT_RESULTCREATE</code> event (see <a class="xref" href="libpq-events.html" title="34.14. Event System">Section 34.14</a>) for each event procedure registered in the
+ <code class="structname">PGresult</code> object. Returns non-zero for success,
+ zero if any event procedure fails.
+
+</p><pre class="synopsis">
+int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
+</pre><p>
+ </p><p>
+ The <code class="literal">conn</code> argument is passed through to event procedures
+ but not used directly. It can be <code class="symbol">NULL</code> if the event
+ procedures won't use it.
+ </p><p>
+ Event procedures that have already received a
+ <code class="literal">PGEVT_RESULTCREATE</code> or <code class="literal">PGEVT_RESULTCOPY</code> event
+ for this object are not fired again.
+ </p><p>
+ The main reason that this function is separate from
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQMAKEEMPTYPGRESULT"><code class="function">PQmakeEmptyPGresult</code></a> is that it is often appropriate
+ to create a <code class="structname">PGresult</code> and fill it with data
+ before invoking the event procedures.
+ </p></dd><dt id="LIBPQ-PQCOPYRESULT"><span class="term"><code class="function">PQcopyResult</code><a id="id-1.7.3.19.3.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Makes a copy of a <code class="structname">PGresult</code> object. The copy is
+ not linked to the source result in any way and
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> must be called when the copy is no longer
+ needed. If the function fails, <code class="symbol">NULL</code> is returned.
+
+</p><pre class="synopsis">
+PGresult *PQcopyResult(const PGresult *src, int flags);
+</pre><p>
+ </p><p>
+ This is not intended to make an exact copy. The returned result is
+ always put into <code class="literal">PGRES_TUPLES_OK</code> status, and does not
+ copy any error message in the source. (It does copy the command status
+ string, however.) The <em class="parameter"><code>flags</code></em> argument determines
+ what else is copied. It is a bitwise OR of several flags.
+ <code class="literal">PG_COPYRES_ATTRS</code> specifies copying the source
+ result's attributes (column definitions).
+ <code class="literal">PG_COPYRES_TUPLES</code> specifies copying the source
+ result's tuples. (This implies copying the attributes, too.)
+ <code class="literal">PG_COPYRES_NOTICEHOOKS</code> specifies
+ copying the source result's notify hooks.
+ <code class="literal">PG_COPYRES_EVENTS</code> specifies copying the source
+ result's events. (But any instance data associated with the source
+ is not copied.)
+ The event procedures receive <code class="literal">PGEVT_RESULTCOPY</code> events.
+ </p></dd><dt id="LIBPQ-PQSETRESULTATTRS"><span class="term"><code class="function">PQsetResultAttrs</code><a id="id-1.7.3.19.3.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets the attributes of a <code class="structname">PGresult</code> object.
+</p><pre class="synopsis">
+int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
+</pre><p>
+ </p><p>
+ The provided <em class="parameter"><code>attDescs</code></em> are copied into the result.
+ If the <em class="parameter"><code>attDescs</code></em> pointer is <code class="symbol">NULL</code> or
+ <em class="parameter"><code>numAttributes</code></em> is less than one, the request is
+ ignored and the function succeeds. If <em class="parameter"><code>res</code></em>
+ already contains attributes, the function will fail. If the function
+ fails, the return value is zero. If the function succeeds, the return
+ value is non-zero.
+ </p></dd><dt id="LIBPQ-PQSETVALUE"><span class="term"><code class="function">PQsetvalue</code><a id="id-1.7.3.19.3.9.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sets a tuple field value of a <code class="structname">PGresult</code> object.
+</p><pre class="synopsis">
+int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
+</pre><p>
+ </p><p>
+ The function will automatically grow the result's internal tuples array
+ as needed. However, the <em class="parameter"><code>tup_num</code></em> argument must be
+ less than or equal to <a class="xref" href="libpq-exec.html#LIBPQ-PQNTUPLES"><code class="function">PQntuples</code></a>, meaning this
+ function can only grow the tuples array one tuple at a time. But any
+ field of any existing tuple can be modified in any order. If a value at
+ <em class="parameter"><code>field_num</code></em> already exists, it will be overwritten.
+ If <em class="parameter"><code>len</code></em> is -1 or
+ <em class="parameter"><code>value</code></em> is <code class="symbol">NULL</code>, the field value
+ will be set to an SQL null value. The
+ <em class="parameter"><code>value</code></em> is copied into the result's private storage,
+ thus is no longer needed after the function
+ returns. If the function fails, the return value is zero. If the
+ function succeeds, the return value is non-zero.
+ </p></dd><dt id="LIBPQ-PQRESULTALLOC"><span class="term"><code class="function">PQresultAlloc</code><a id="id-1.7.3.19.3.10.1.2" class="indexterm"></a></span></dt><dd><p>
+ Allocate subsidiary storage for a <code class="structname">PGresult</code> object.
+</p><pre class="synopsis">
+void *PQresultAlloc(PGresult *res, size_t nBytes);
+</pre><p>
+ </p><p>
+ Any memory allocated with this function will be freed when
+ <em class="parameter"><code>res</code></em> is cleared. If the function fails,
+ the return value is <code class="symbol">NULL</code>. The result is
+ guaranteed to be adequately aligned for any type of data,
+ just as for <code class="function">malloc</code>.
+ </p></dd><dt id="LIBPQ-PQRESULTMEMORYSIZE"><span class="term"><code class="function">PQresultMemorySize</code><a id="id-1.7.3.19.3.11.1.2" class="indexterm"></a></span></dt><dd><p>
+ Retrieves the number of bytes allocated for
+ a <code class="structname">PGresult</code> object.
+</p><pre class="synopsis">
+size_t PQresultMemorySize(const PGresult *res);
+</pre><p>
+ </p><p>
+ This value is the sum of all <code class="function">malloc</code> requests
+ associated with the <code class="structname">PGresult</code> object, that is,
+ all the space that will be freed by <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a>.
+ This information can be useful for managing memory consumption.
+ </p></dd><dt id="LIBPQ-PQLIBVERSION"><span class="term"><code class="function">PQlibVersion</code><a id="id-1.7.3.19.3.12.1.2" class="indexterm"></a></span></dt><dd><p>
+ Return the version of <span class="productname">libpq</span> that is being used.
+</p><pre class="synopsis">
+int PQlibVersion(void);
+</pre><p>
+ </p><p>
+ The result of this function can be used to determine, at
+ run time, whether specific functionality is available in the currently
+ loaded version of libpq. The function can be used, for example,
+ to determine which connection options are available in
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
+ </p><p>
+ The result is formed by multiplying the library's major version
+ number by 10000 and adding the minor version number. For example,
+ version 10.1 will be returned as 100001, and version 11.0 will be
+ returned as 110000.
+ </p><p>
+ Prior to major version 10, <span class="productname">PostgreSQL</span> used
+ three-part version numbers in which the first two parts together
+ represented the major version. For those
+ versions, <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a> uses two digits for each
+ part; for example version 9.1.5 will be returned as 90105, and
+ version 9.2.0 will be returned as 90200.
+ </p><p>
+ Therefore, for purposes of determining feature compatibility,
+ applications should divide the result of <a class="xref" href="libpq-misc.html#LIBPQ-PQLIBVERSION"><code class="function">PQlibVersion</code></a>
+ by 100 not 10000 to determine a logical major version number.
+ In all release series, only the last two digits differ between
+ minor releases (bug-fix releases).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This function appeared in <span class="productname">PostgreSQL</span> version 9.1, so
+ it cannot be used to detect required functionality in earlier
+ versions, since calling it will create a link dependency
+ on version 9.1 or later.
+ </p></div></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-control.html" title="34.11. Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notice-processing.html" title="34.13. Notice Processing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.11. Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.13. Notice Processing</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-notice-processing.html b/doc/src/sgml/html/libpq-notice-processing.html
new file mode 100644
index 0000000..3203dd7
--- /dev/null
+++ b/doc/src/sgml/html/libpq-notice-processing.html
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.13. Notice Processing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-misc.html" title="34.12. Miscellaneous Functions" /><link rel="next" href="libpq-events.html" title="34.14. Event System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.13. Notice Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-events.html" title="34.14. Event System">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-NOTICE-PROCESSING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.13. Notice Processing</h2></div></div></div><a id="id-1.7.3.20.2" class="indexterm"></a><p>
+ Notice and warning messages generated by the server are not returned
+ by the query execution functions, since they do not imply failure of
+ the query. Instead they are passed to a notice handling function, and
+ execution continues normally after the handler returns. The default
+ notice handling function prints the message on
+ <code class="filename">stderr</code>, but the application can override this
+ behavior by supplying its own handling function.
+ </p><p>
+ For historical reasons, there are two levels of notice handling, called
+ the notice receiver and notice processor. The default behavior is for
+ the notice receiver to format the notice and pass a string to the notice
+ processor for printing. However, an application that chooses to provide
+ its own notice receiver will typically ignore the notice processor
+ layer and just do all the work in the notice receiver.
+ </p><p>
+ The function <code class="function" id="LIBPQ-PQSETNOTICERECEIVER">PQsetNoticeReceiver</code>
+ <a id="id-1.7.3.20.5.2" class="indexterm"></a>
+ <a id="id-1.7.3.20.5.3" class="indexterm"></a> sets or
+ examines the current notice receiver for a connection object.
+ Similarly, <code class="function" id="LIBPQ-PQSETNOTICEPROCESSOR">PQsetNoticeProcessor</code>
+ <a id="id-1.7.3.20.5.5" class="indexterm"></a>
+ <a id="id-1.7.3.20.5.6" class="indexterm"></a> sets or
+ examines the current notice processor.
+
+</p><pre class="synopsis">
+typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+
+PQnoticeReceiver
+PQsetNoticeReceiver(PGconn *conn,
+ PQnoticeReceiver proc,
+ void *arg);
+
+typedef void (*PQnoticeProcessor) (void *arg, const char *message);
+
+PQnoticeProcessor
+PQsetNoticeProcessor(PGconn *conn,
+ PQnoticeProcessor proc,
+ void *arg);
+</pre><p>
+
+ Each of these functions returns the previous notice receiver or
+ processor function pointer, and sets the new value. If you supply a
+ null function pointer, no action is taken, but the current pointer is
+ returned.
+ </p><p>
+ When a notice or warning message is received from the server, or
+ generated internally by <span class="application">libpq</span>, the notice
+ receiver function is called. It is passed the message in the form of
+ a <code class="symbol">PGRES_NONFATAL_ERROR</code>
+ <code class="structname">PGresult</code>. (This allows the receiver to extract
+ individual fields using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORFIELD"><code class="function">PQresultErrorField</code></a>, or obtain a
+ complete preformatted message using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>
+ or <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a>.) The same
+ void pointer passed to <code class="function">PQsetNoticeReceiver</code> is also
+ passed. (This pointer can be used to access application-specific state
+ if needed.)
+ </p><p>
+ The default notice receiver simply extracts the message (using
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>) and passes it to the notice
+ processor.
+ </p><p>
+ The notice processor is responsible for handling a notice or warning
+ message given in text form. It is passed the string text of the message
+ (including a trailing newline), plus a void pointer that is the same
+ one passed to <code class="function">PQsetNoticeProcessor</code>. (This pointer
+ can be used to access application-specific state if needed.)
+ </p><p>
+ The default notice processor is simply:
+</p><pre class="programlisting">
+static void
+defaultNoticeProcessor(void *arg, const char *message)
+{
+ fprintf(stderr, "%s", message);
+}
+</pre><p>
+ </p><p>
+ Once you have set a notice receiver or processor, you should expect
+ that that function could be called as long as either the
+ <code class="structname">PGconn</code> object or <code class="structname">PGresult</code> objects made
+ from it exist. At creation of a <code class="structname">PGresult</code>, the
+ <code class="structname">PGconn</code>'s current notice handling pointers are copied
+ into the <code class="structname">PGresult</code> for possible use by functions like
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-events.html" title="34.14. Event System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.12. Miscellaneous Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.14. Event System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-notify.html b/doc/src/sgml/html/libpq-notify.html
new file mode 100644
index 0000000..e0021ac
--- /dev/null
+++ b/doc/src/sgml/html/libpq-notify.html
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.9. Asynchronous Notification</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface" /><link rel="next" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.9. Asynchronous Notification</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-NOTIFY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.9. Asynchronous Notification</h2></div></div></div><a id="id-1.7.3.16.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> offers asynchronous notification
+ via the <code class="command">LISTEN</code> and <code class="command">NOTIFY</code>
+ commands. A client session registers its interest in a particular
+ notification channel with the <code class="command">LISTEN</code> command (and
+ can stop listening with the <code class="command">UNLISTEN</code> command). All
+ sessions listening on a particular channel will be notified
+ asynchronously when a <code class="command">NOTIFY</code> command with that
+ channel name is executed by any session. A <span class="quote">“<span class="quote">payload</span>”</span> string can
+ be passed to communicate additional data to the listeners.
+ </p><p>
+ <span class="application">libpq</span> applications submit
+ <code class="command">LISTEN</code>, <code class="command">UNLISTEN</code>,
+ and <code class="command">NOTIFY</code> commands as
+ ordinary SQL commands. The arrival of <code class="command">NOTIFY</code>
+ messages can subsequently be detected by calling
+ <code class="function" id="LIBPQ-PQNOTIFIES">PQnotifies</code>.<a id="id-1.7.3.16.4.7" class="indexterm"></a>
+ </p><p>
+ The function <code class="function">PQnotifies</code> returns the next notification
+ from a list of unhandled notification messages received from the server.
+ It returns a null pointer if there are no pending notifications. Once a
+ notification is returned from <code class="function">PQnotifies</code>, it is considered
+ handled and will be removed from the list of notifications.
+
+</p><pre class="synopsis">
+PGnotify *PQnotifies(PGconn *conn);
+
+typedef struct pgNotify
+{
+ char *relname; /* notification channel name */
+ int be_pid; /* process ID of notifying server process */
+ char *extra; /* notification payload string */
+} PGnotify;
+</pre><p>
+
+ After processing a <code class="structname">PGnotify</code> object returned
+ by <code class="function">PQnotifies</code>, be sure to free it with
+ <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>. It is sufficient to free the
+ <code class="structname">PGnotify</code> pointer; the
+ <code class="structfield">relname</code> and <code class="structfield">extra</code>
+ fields do not represent separate allocations. (The names of these fields
+ are historical; in particular, channel names need not have anything to
+ do with relation names.)
+ </p><p>
+ <a class="xref" href="libpq-example.html#LIBPQ-EXAMPLE-2" title="Example 34.2. libpq Example Program 2">Example 34.2</a> gives a sample program that illustrates
+ the use of asynchronous notification.
+ </p><p>
+ <code class="function">PQnotifies</code> does not actually read data from the
+ server; it just returns messages previously absorbed by another
+ <span class="application">libpq</span> function. In ancient releases of
+ <span class="application">libpq</span>, the only way to ensure timely receipt
+ of <code class="command">NOTIFY</code> messages was to constantly submit commands, even
+ empty ones, and then check <code class="function">PQnotifies</code> after each
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>. While this still works, it is deprecated
+ as a waste of processing power.
+ </p><p>
+ A better way to check for <code class="command">NOTIFY</code> messages when you have no
+ useful commands to execute is to call
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a>, then check
+ <code class="function">PQnotifies</code>. You can use
+ <code class="function">select()</code> to wait for data to arrive from the
+ server, thereby using no <acronym class="acronym">CPU</acronym> power unless there is
+ something to do. (See <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a> to obtain the file
+ descriptor number to use with <code class="function">select()</code>.) Note that
+ this will work OK whether you submit commands with
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>/<a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> or
+ simply use <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>. You should, however, remember
+ to check <code class="function">PQnotifies</code> after each
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> or <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>, to
+ see if any notifications came in during the processing of the command.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-fastpath.html" title="34.8. The Fast-Path Interface">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-copy.html" title="34.10. Functions Associated with the COPY Command">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.8. The Fast-Path Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.10. Functions Associated with the <code class="command">COPY</code> Command</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-pgpass.html b/doc/src/sgml/html/libpq-pgpass.html
new file mode 100644
index 0000000..a34cb93
--- /dev/null
+++ b/doc/src/sgml/html/libpq-pgpass.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.16. The Password File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-envars.html" title="34.15. Environment Variables" /><link rel="next" href="libpq-pgservice.html" title="34.17. The Connection Service File" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.16. The Password File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-envars.html" title="34.15. Environment Variables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-pgservice.html" title="34.17. The Connection Service File">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-PGPASS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.16. The Password File</h2></div></div></div><a id="id-1.7.3.23.2" class="indexterm"></a><a id="id-1.7.3.23.3" class="indexterm"></a><p>
+ The file <code class="filename">.pgpass</code> in a user's home directory can
+ contain passwords to
+ be used if the connection requires a password (and no password has been
+ specified otherwise). On Microsoft Windows the file is named
+ <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> (where
+ <code class="filename">%APPDATA%</code> refers to the Application Data subdirectory in
+ the user's profile).
+ Alternatively, the password file to use can be specified
+ using the connection parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-PASSFILE">passfile</a>
+ or the environment variable <code class="envar">PGPASSFILE</code>.
+ </p><p>
+ This file should contain lines of the following format:
+</p><pre class="synopsis">
+<em class="replaceable"><code>hostname</code></em>:<em class="replaceable"><code>port</code></em>:<em class="replaceable"><code>database</code></em>:<em class="replaceable"><code>username</code></em>:<em class="replaceable"><code>password</code></em>
+</pre><p>
+ (You can add a reminder comment to the file by copying the line above and
+ preceding it with <code class="literal">#</code>.)
+ Each of the first four fields can be a literal value, or
+ <code class="literal">*</code>, which matches anything. The password field from
+ the first line that matches the current connection parameters will be
+ used. (Therefore, put more-specific entries first when you are using
+ wildcards.) If an entry needs to contain <code class="literal">:</code> or
+ <code class="literal">\</code>, escape this character with <code class="literal">\</code>.
+ The host name field is matched to the <code class="literal">host</code> connection
+ parameter if that is specified, otherwise to
+ the <code class="literal">hostaddr</code> parameter if that is specified; if neither
+ are given then the host name <code class="literal">localhost</code> is searched for.
+ The host name <code class="literal">localhost</code> is also searched for when
+ the connection is a Unix-domain socket connection and
+ the <code class="literal">host</code> parameter
+ matches <span class="application">libpq</span>'s default socket directory path.
+ In a standby server, a database field of <code class="literal">replication</code>
+ matches streaming replication connections made to the primary server.
+ The database field is of limited usefulness otherwise, because users have
+ the same password for all databases in the same cluster.
+ </p><p>
+ On Unix systems, the permissions on a password file must
+ disallow any access to world or group; achieve this by a command such as
+ <code class="command">chmod 0600 ~/.pgpass</code>. If the permissions are less
+ strict than this, the file will be ignored. On Microsoft Windows, it
+ is assumed that the file is stored in a directory that is secure, so
+ no special permissions check is made.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-envars.html" title="34.15. Environment Variables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-pgservice.html" title="34.17. The Connection Service File">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.15. Environment Variables </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.17. The Connection Service File</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-pgservice.html b/doc/src/sgml/html/libpq-pgservice.html
new file mode 100644
index 0000000..da7c597
--- /dev/null
+++ b/doc/src/sgml/html/libpq-pgservice.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.17. The Connection Service File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-pgpass.html" title="34.16. The Password File" /><link rel="next" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.17. The Connection Service File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-pgpass.html" title="34.16. The Password File">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-PGSERVICE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.17. The Connection Service File</h2></div></div></div><a id="id-1.7.3.24.2" class="indexterm"></a><a id="id-1.7.3.24.3" class="indexterm"></a><a id="id-1.7.3.24.4" class="indexterm"></a><p>
+ The connection service file allows libpq connection parameters to be
+ associated with a single service name. That service name can then be
+ specified in a libpq connection string, and the associated settings will be
+ used. This allows connection parameters to be modified without requiring
+ a recompile of the libpq-using application. The service name can also be
+ specified using the <code class="envar">PGSERVICE</code> environment variable.
+ </p><p>
+ Service names can be defined in either a per-user service file or a
+ system-wide file. If the same service name exists in both the user
+ and the system file, the user file takes precedence.
+ By default, the per-user service file is named
+ <code class="filename">~/.pg_service.conf</code>.
+ On Microsoft Windows, it is named
+ <code class="filename">%APPDATA%\postgresql\.pg_service.conf</code> (where
+ <code class="filename">%APPDATA%</code> refers to the Application Data subdirectory
+ in the user's profile). A different file name can be specified by
+ setting the environment variable <code class="envar">PGSERVICEFILE</code>.
+ The system-wide file is named <code class="filename">pg_service.conf</code>.
+ By default it is sought in the <code class="filename">etc</code> directory
+ of the <span class="productname">PostgreSQL</span> installation
+ (use <code class="literal">pg_config --sysconfdir</code> to identify this
+ directory precisely). Another directory, but not a different file
+ name, can be specified by setting the environment variable
+ <code class="envar">PGSYSCONFDIR</code>.
+ </p><p>
+ Either service file uses an <span class="quote">“<span class="quote">INI file</span>”</span> format where the section
+ name is the service name and the parameters are connection
+ parameters; see <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for a list. For
+ example:
+</p><pre class="programlisting">
+# comment
+[mydb]
+host=somehost
+port=5433
+user=admin
+</pre><p>
+ An example file is provided in
+ the <span class="productname">PostgreSQL</span> installation at
+ <code class="filename">share/pg_service.conf.sample</code>.
+ </p><p>
+ Connection parameters obtained from a service file are combined with
+ parameters obtained from other sources. A service file setting
+ overrides the corresponding environment variable, and in turn can be
+ overridden by a value given directly in the connection string.
+ For example, using the above service file, a connection string
+ <code class="literal">service=mydb port=5434</code> will use
+ host <code class="literal">somehost</code>, port <code class="literal">5434</code>,
+ user <code class="literal">admin</code>, and other parameters as set by
+ environment variables or built-in defaults.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-pgpass.html" title="34.16. The Password File">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.16. The Password File </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.18. LDAP Lookup of Connection Parameters</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-pipeline-mode.html b/doc/src/sgml/html/libpq-pipeline-mode.html
new file mode 100644
index 0000000..c97dfa0
--- /dev/null
+++ b/doc/src/sgml/html/libpq-pipeline-mode.html
@@ -0,0 +1,327 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.5. Pipeline Mode</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-async.html" title="34.4. Asynchronous Command Processing" /><link rel="next" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.5. Pipeline Mode</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-PIPELINE-MODE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.5. Pipeline Mode</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-USING">34.5.1. Using Pipeline Mode</a></span></dt><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">34.5.2. Functions Associated with Pipeline Mode</a></span></dt><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-TIPS">34.5.3. When to Use Pipeline Mode</a></span></dt></dl></div><a id="id-1.7.3.12.2" class="indexterm"></a><a id="id-1.7.3.12.3" class="indexterm"></a><a id="id-1.7.3.12.4" class="indexterm"></a><p>
+ <span class="application">libpq</span> pipeline mode allows applications to
+ send a query without having to read the result of the previously
+ sent query. Taking advantage of the pipeline mode, a client will wait
+ less for the server, since multiple queries/results can be
+ sent/received in a single network transaction.
+ </p><p>
+ While pipeline mode provides a significant performance boost, writing
+ clients using the pipeline mode is more complex because it involves
+ managing a queue of pending queries and finding which result
+ corresponds to which query in the queue.
+ </p><p>
+ Pipeline mode also generally consumes more memory on both the client and server,
+ though careful and aggressive management of the send/receive queue can mitigate
+ this. This applies whether or not the connection is in blocking or non-blocking
+ mode.
+ </p><p>
+ While <span class="application">libpq</span>'s pipeline API was introduced in
+ <span class="productname">PostgreSQL</span> 14, it is a client-side feature
+ which doesn't require special server support and works on any server
+ that supports the v3 extended query protocol. For more information see
+ <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-PIPELINING" title="55.2.4. Pipelining">Section 55.2.4</a>.
+ </p><div class="sect2" id="LIBPQ-PIPELINE-USING"><div class="titlepage"><div><div><h3 class="title">34.5.1. Using Pipeline Mode</h3></div></div></div><p>
+ To issue pipelines, the application must switch the connection
+ into pipeline mode,
+ which is done with <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQENTERPIPELINEMODE"><code class="function">PQenterPipelineMode</code></a>.
+ <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESTATUS"><code class="function">PQpipelineStatus</code></a> can be used
+ to test whether pipeline mode is active.
+ In pipeline mode, only <a class="link" href="libpq-async.html" title="34.4. Asynchronous Command Processing">asynchronous operations</a>
+ that utilize the extended query protocol
+ are permitted, command strings containing multiple SQL commands are
+ disallowed, and so is <code class="literal">COPY</code>.
+ Using synchronous command execution functions
+ such as <code class="function">PQfn</code>,
+ <code class="function">PQexec</code>,
+ <code class="function">PQexecParams</code>,
+ <code class="function">PQprepare</code>,
+ <code class="function">PQexecPrepared</code>,
+ <code class="function">PQdescribePrepared</code>,
+ <code class="function">PQdescribePortal</code>,
+ is an error condition.
+ <code class="function">PQsendQuery</code> is
+ also disallowed, because it uses the simple query protocol.
+ Once all dispatched commands have had their results processed, and
+ the end pipeline result has been consumed, the application may return
+ to non-pipelined mode with <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQEXITPIPELINEMODE"><code class="function">PQexitPipelineMode</code></a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ It is best to use pipeline mode with <span class="application">libpq</span> in
+ <a class="link" href="libpq-async.html#LIBPQ-PQSETNONBLOCKING">non-blocking mode</a>. If used
+ in blocking mode it is possible for a client/server deadlock to occur.
+ <a href="#ftn.id-1.7.3.12.9.3.1.3" class="footnote"><sup class="footnote" id="id-1.7.3.12.9.3.1.3">[15]</sup></a>
+ </p></div><div class="sect3" id="LIBPQ-PIPELINE-SENDING"><div class="titlepage"><div><div><h4 class="title">34.5.1.1. Issuing Queries</h4></div></div></div><p>
+ After entering pipeline mode, the application dispatches requests using
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>
+ or its prepared-query sibling
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>.
+ These requests are queued on the client-side until flushed to the server;
+ this occurs when <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a> is used to
+ establish a synchronization point in the pipeline,
+ or when <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> is called.
+ The functions <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>, and
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a> also work in pipeline mode.
+ Result processing is described below.
+ </p><p>
+ The server executes statements, and returns results, in the order the
+ client sends them. The server will begin executing the commands in the
+ pipeline immediately, not waiting for the end of the pipeline.
+ Note that results are buffered on the server side; the server flushes
+ that buffer when a synchronization point is established with
+ <code class="function">PQpipelineSync</code>, or when
+ <code class="function">PQsendFlushRequest</code> is called.
+ If any statement encounters an error, the server aborts the current
+ transaction and does not execute any subsequent command in the queue
+ until the next synchronization point;
+ a <code class="literal">PGRES_PIPELINE_ABORTED</code> result is produced for
+ each such command.
+ (This remains true even if the commands in the pipeline would rollback
+ the transaction.)
+ Query processing resumes after the synchronization point.
+ </p><p>
+ It's fine for one operation to depend on the results of a
+ prior one; for example, one query may define a table that the next
+ query in the same pipeline uses. Similarly, an application may
+ create a named prepared statement and execute it with later
+ statements in the same pipeline.
+ </p></div><div class="sect3" id="LIBPQ-PIPELINE-RESULTS"><div class="titlepage"><div><div><h4 class="title">34.5.1.2. Processing Results</h4></div></div></div><p>
+ To process the result of one query in a pipeline, the application calls
+ <code class="function">PQgetResult</code> repeatedly and handles each result
+ until <code class="function">PQgetResult</code> returns null.
+ The result from the next query in the pipeline may then be retrieved using
+ <code class="function">PQgetResult</code> again and the cycle repeated.
+ The application handles individual statement results as normal.
+ When the results of all the queries in the pipeline have been
+ returned, <code class="function">PQgetResult</code> returns a result
+ containing the status value <code class="literal">PGRES_PIPELINE_SYNC</code>
+ </p><p>
+ The client may choose to defer result processing until the complete
+ pipeline has been sent, or interleave that with sending further
+ queries in the pipeline; see <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-INTERLEAVE" title="34.5.1.4. Interleaving Result Processing and Query Dispatch">Section 34.5.1.4</a>.
+ </p><p>
+ To enter single-row mode, call <code class="function">PQsetSingleRowMode</code>
+ before retrieving results with <code class="function">PQgetResult</code>.
+ This mode selection is effective only for the query currently
+ being processed. For more information on the use of
+ <code class="function">PQsetSingleRowMode</code>,
+ refer to <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>.
+ </p><p>
+ <code class="function">PQgetResult</code> behaves the same as for normal
+ asynchronous processing except that it may contain the new
+ <code class="type">PGresult</code> types <code class="literal">PGRES_PIPELINE_SYNC</code>
+ and <code class="literal">PGRES_PIPELINE_ABORTED</code>.
+ <code class="literal">PGRES_PIPELINE_SYNC</code> is reported exactly once for each
+ <code class="function">PQpipelineSync</code> at the corresponding point
+ in the pipeline.
+ <code class="literal">PGRES_PIPELINE_ABORTED</code> is emitted in place of a normal
+ query result for the first error and all subsequent results
+ until the next <code class="literal">PGRES_PIPELINE_SYNC</code>;
+ see <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-ERRORS" title="34.5.1.3. Error Handling">Section 34.5.1.3</a>.
+ </p><p>
+ <code class="function">PQisBusy</code>, <code class="function">PQconsumeInput</code>, etc
+ operate as normal when processing pipeline results. In particular,
+ a call to <code class="function">PQisBusy</code> in the middle of a pipeline
+ returns 0 if the results for all the queries issued so far have been
+ consumed.
+ </p><p>
+ <span class="application">libpq</span> does not provide any information to the
+ application about the query currently being processed (except that
+ <code class="function">PQgetResult</code> returns null to indicate that we start
+ returning the results of next query). The application must keep track
+ of the order in which it sent queries, to associate them with their
+ corresponding results.
+ Applications will typically use a state machine or a FIFO queue for this.
+ </p></div><div class="sect3" id="LIBPQ-PIPELINE-ERRORS"><div class="titlepage"><div><div><h4 class="title">34.5.1.3. Error Handling</h4></div></div></div><p>
+ From the client's perspective, after <code class="function">PQresultStatus</code>
+ returns <code class="literal">PGRES_FATAL_ERROR</code>,
+ the pipeline is flagged as aborted.
+ <code class="function">PQresultStatus</code> will report a
+ <code class="literal">PGRES_PIPELINE_ABORTED</code> result for each remaining queued
+ operation in an aborted pipeline. The result for
+ <code class="function">PQpipelineSync</code> is reported as
+ <code class="literal">PGRES_PIPELINE_SYNC</code> to signal the end of the aborted pipeline
+ and resumption of normal result processing.
+ </p><p>
+ The client <span class="emphasis"><em>must</em></span> process results with
+ <code class="function">PQgetResult</code> during error recovery.
+ </p><p>
+ If the pipeline used an implicit transaction, then operations that have
+ already executed are rolled back and operations that were queued to follow
+ the failed operation are skipped entirely. The same behavior holds if the
+ pipeline starts and commits a single explicit transaction (i.e. the first
+ statement is <code class="literal">BEGIN</code> and the last is
+ <code class="literal">COMMIT</code>) except that the session remains in an aborted
+ transaction state at the end of the pipeline. If a pipeline contains
+ <span class="emphasis"><em>multiple explicit transactions</em></span>, all transactions that
+ committed prior to the error remain committed, the currently in-progress
+ transaction is aborted, and all subsequent operations are skipped completely,
+ including subsequent transactions. If a pipeline synchronization point
+ occurs with an explicit transaction block in aborted state, the next pipeline
+ will become aborted immediately unless the next command puts the transaction
+ in normal mode with <code class="command">ROLLBACK</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The client must not assume that work is committed when it
+ <span class="emphasis"><em>sends</em></span> a <code class="literal">COMMIT</code> — only when the
+ corresponding result is received to confirm the commit is complete.
+ Because errors arrive asynchronously, the application needs to be able to
+ restart from the last <span class="emphasis"><em>received</em></span> committed change and
+ resend work done after that point if something goes wrong.
+ </p></div></div><div class="sect3" id="LIBPQ-PIPELINE-INTERLEAVE"><div class="titlepage"><div><div><h4 class="title">34.5.1.4. Interleaving Result Processing and Query Dispatch</h4></div></div></div><p>
+ To avoid deadlocks on large pipelines the client should be structured
+ around a non-blocking event loop using operating system facilities
+ such as <code class="function">select</code>, <code class="function">poll</code>,
+ <code class="function">WaitForMultipleObjectEx</code>, etc.
+ </p><p>
+ The client application should generally maintain a queue of work
+ remaining to be dispatched and a queue of work that has been dispatched
+ but not yet had its results processed. When the socket is writable
+ it should dispatch more work. When the socket is readable it should
+ read results and process them, matching them up to the next entry in
+ its corresponding results queue. Based on available memory, results from the
+ socket should be read frequently: there's no need to wait until the
+ pipeline end to read the results. Pipelines should be scoped to logical
+ units of work, usually (but not necessarily) one transaction per pipeline.
+ There's no need to exit pipeline mode and re-enter it between pipelines,
+ or to wait for one pipeline to finish before sending the next.
+ </p><p>
+ An example using <code class="function">select()</code> and a simple state
+ machine to track sent and received work is in
+ <code class="filename">src/test/modules/libpq_pipeline/libpq_pipeline.c</code>
+ in the PostgreSQL source distribution.
+ </p></div></div><div class="sect2" id="LIBPQ-PIPELINE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">34.5.2. Functions Associated with Pipeline Mode</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPIPELINESTATUS"><span class="term"><code class="function">PQpipelineStatus</code><a id="id-1.7.3.12.10.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the current pipeline mode status of the
+ <span class="application">libpq</span> connection.
+</p><pre class="synopsis">
+PGpipelineStatus PQpipelineStatus(const PGconn *conn);
+</pre><p>
+ </p><p>
+ <code class="function">PQpipelineStatus</code> can return one of the following values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal">PQ_PIPELINE_ON</code>
+ </span></dt><dd><p>
+ The <span class="application">libpq</span> connection is in
+ pipeline mode.
+ </p></dd><dt><span class="term">
+ <code class="literal">PQ_PIPELINE_OFF</code>
+ </span></dt><dd><p>
+ The <span class="application">libpq</span> connection is
+ <span class="emphasis"><em>not</em></span> in pipeline mode.
+ </p></dd><dt><span class="term">
+ <code class="literal">PQ_PIPELINE_ABORTED</code>
+ </span></dt><dd><p>
+ The <span class="application">libpq</span> connection is in pipeline
+ mode and an error occurred while processing the current pipeline.
+ The aborted flag is cleared when <code class="function">PQgetResult</code>
+ returns a result of type <code class="literal">PGRES_PIPELINE_SYNC</code>.
+ </p></dd></dl></div><p>
+ </p></dd><dt id="LIBPQ-PQENTERPIPELINEMODE"><span class="term"><code class="function">PQenterPipelineMode</code><a id="id-1.7.3.12.10.2.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Causes a connection to enter pipeline mode if it is currently idle or
+ already in pipeline mode.
+
+</p><pre class="synopsis">
+int PQenterPipelineMode(PGconn *conn);
+</pre><p>
+
+ </p><p>
+ Returns 1 for success.
+ Returns 0 and has no effect if the connection is not currently
+ idle, i.e., it has a result ready, or it is waiting for more
+ input from the server, etc.
+ This function does not actually send anything to the server,
+ it just changes the <span class="application">libpq</span> connection
+ state.
+ </p></dd><dt id="LIBPQ-PQEXITPIPELINEMODE"><span class="term"><code class="function">PQexitPipelineMode</code><a id="id-1.7.3.12.10.2.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Causes a connection to exit pipeline mode if it is currently in pipeline mode
+ with an empty queue and no pending results.
+</p><pre class="synopsis">
+int PQexitPipelineMode(PGconn *conn);
+</pre><p>
+ </p><p>
+ Returns 1 for success. Returns 1 and takes no action if not in
+ pipeline mode. If the current statement isn't finished processing,
+ or <code class="function">PQgetResult</code> has not been called to collect
+ results from all previously sent query, returns 0 (in which case,
+ use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more information
+ about the failure).
+ </p></dd><dt id="LIBPQ-PQPIPELINESYNC"><span class="term"><code class="function">PQpipelineSync</code><a id="id-1.7.3.12.10.2.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Marks a synchronization point in a pipeline by sending a
+ <a class="link" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="55.2.3. Extended Query">sync message</a>
+ and flushing the send buffer. This serves as
+ the delimiter of an implicit transaction and an error recovery
+ point; see <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-ERRORS" title="34.5.1.3. Error Handling">Section 34.5.1.3</a>.
+
+</p><pre class="synopsis">
+int PQpipelineSync(PGconn *conn);
+</pre><p>
+ </p><p>
+ Returns 1 for success. Returns 0 if the connection is not in
+ pipeline mode or sending a
+ <a class="link" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="55.2.3. Extended Query">sync message</a>
+ failed.
+ </p></dd><dt id="LIBPQ-PQSENDFLUSHREQUEST"><span class="term"><code class="function">PQsendFlushRequest</code><a id="id-1.7.3.12.10.2.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Sends a request for the server to flush its output buffer.
+</p><pre class="synopsis">
+int PQsendFlushRequest(PGconn *conn);
+</pre><p>
+ </p><p>
+ Returns 1 for success. Returns 0 on any failure.
+ </p><p>
+ The server flushes its output buffer automatically as a result of
+ <code class="function">PQpipelineSync</code> being called, or
+ on any request when not in pipeline mode; this function is useful
+ to cause the server to flush its output buffer in pipeline mode
+ without establishing a synchronization point.
+ Note that the request is not itself flushed to the server automatically;
+ use <code class="function">PQflush</code> if necessary.
+ </p></dd></dl></div></div><div class="sect2" id="LIBPQ-PIPELINE-TIPS"><div class="titlepage"><div><div><h3 class="title">34.5.3. When to Use Pipeline Mode</h3></div></div></div><p>
+ Much like asynchronous query mode, there is no meaningful performance
+ overhead when using pipeline mode. It increases client application complexity,
+ and extra caution is required to prevent client/server deadlocks, but
+ pipeline mode can offer considerable performance improvements, in exchange for
+ increased memory usage from leaving state around longer.
+ </p><p>
+ Pipeline mode is most useful when the server is distant, i.e., network latency
+ (<span class="quote">“<span class="quote">ping time</span>”</span>) is high, and also when many small operations
+ are being performed in rapid succession. There is usually less benefit
+ in using pipelined commands when each query takes many multiples of the client/server
+ round-trip time to execute. A 100-statement operation run on a server
+ 300 ms round-trip-time away would take 30 seconds in network latency alone
+ without pipelining; with pipelining it may spend as little as 0.3 s waiting for
+ results from the server.
+ </p><p>
+ Use pipelined commands when your application does lots of small
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code> and
+ <code class="literal">DELETE</code> operations that can't easily be transformed
+ into operations on sets, or into a <code class="literal">COPY</code> operation.
+ </p><p>
+ Pipeline mode is not useful when information from one operation is required by
+ the client to produce the next operation. In such cases, the client
+ would have to introduce a synchronization point and wait for a full client/server
+ round-trip to get the results it needs. However, it's often possible to
+ adjust the client design to exchange the required information server-side.
+ Read-modify-write cycles are especially good candidates; for example:
+</p><pre class="programlisting">
+BEGIN;
+SELECT x FROM mytable WHERE id = 42 FOR UPDATE;
+-- result: x=2
+-- client adds 1 to x:
+UPDATE mytable SET x = 3 WHERE id = 42;
+COMMIT;
+</pre><p>
+ could be much more efficiently done with:
+</p><pre class="programlisting">
+UPDATE mytable SET x = x + 1 WHERE id = 42;
+</pre><p>
+ </p><p>
+ Pipelining is less useful, and more complex, when a single pipeline contains
+ multiple transactions (see <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-ERRORS" title="34.5.1.3. Error Handling">Section 34.5.1.3</a>).
+ </p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.7.3.12.9.3.1.3" class="footnote"><p><a href="#id-1.7.3.12.9.3.1.3" class="para"><sup class="para">[15] </sup></a>
+ The client will block trying to send queries to the server, but the
+ server will block trying to send results to the client from queries
+ it has already processed. This only occurs when the client sends
+ enough queries to fill both its output buffer and the server's receive
+ buffer before it switches to processing input from the server,
+ but it's hard to predict exactly when that will happen.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.4. Asynchronous Command Processing </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.6. Retrieving Query Results Row-by-Row</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-single-row-mode.html b/doc/src/sgml/html/libpq-single-row-mode.html
new file mode 100644
index 0000000..599a239
--- /dev/null
+++ b/doc/src/sgml/html/libpq-single-row-mode.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.6. Retrieving Query Results Row-by-Row</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode" /><link rel="next" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.6. Retrieving Query Results Row-by-Row</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-SINGLE-ROW-MODE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.6. Retrieving Query Results Row-by-Row</h2></div></div></div><a id="id-1.7.3.13.2" class="indexterm"></a><p>
+ Ordinarily, <span class="application">libpq</span> collects an SQL command's
+ entire result and returns it to the application as a single
+ <code class="structname">PGresult</code>. This can be unworkable for commands
+ that return a large number of rows. For such cases, applications can use
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> in
+ <em class="firstterm">single-row mode</em>. In this mode, the result row(s) are
+ returned to the application one at a time, as they are received from the
+ server.
+ </p><p>
+ To enter single-row mode, call <a class="xref" href="libpq-single-row-mode.html#LIBPQ-PQSETSINGLEROWMODE"><code class="function">PQsetSingleRowMode</code></a>
+ immediately after a successful call of <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>
+ (or a sibling function). This mode selection is effective only for the
+ currently executing query. Then call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
+ repeatedly, until it returns null, as documented in <a class="xref" href="libpq-async.html" title="34.4. Asynchronous Command Processing">Section 34.4</a>. If the query returns any rows, they are returned
+ as individual <code class="structname">PGresult</code> objects, which look like
+ normal query results except for having status code
+ <code class="literal">PGRES_SINGLE_TUPLE</code> instead of
+ <code class="literal">PGRES_TUPLES_OK</code>. After the last row, or immediately if
+ the query returns zero rows, a zero-row object with status
+ <code class="literal">PGRES_TUPLES_OK</code> is returned; this is the signal that no
+ more rows will arrive. (But note that it is still necessary to continue
+ calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> until it returns null.) All of
+ these <code class="structname">PGresult</code> objects will contain the same row
+ description data (column names, types, etc.) that an ordinary
+ <code class="structname">PGresult</code> object for the query would have.
+ Each object should be freed with <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> as usual.
+ </p><p>
+ When using pipeline mode, single-row mode needs to be activated for each
+ query in the pipeline before retrieving results for that query
+ with <code class="function">PQgetResult</code>.
+ See <a class="xref" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Section 34.5</a> for more information.
+ </p><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETSINGLEROWMODE"><span class="term"><code class="function">PQsetSingleRowMode</code><a id="id-1.7.3.13.6.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Select single-row mode for the currently-executing query.
+
+</p><pre class="synopsis">
+int PQsetSingleRowMode(PGconn *conn);
+</pre><p>
+ </p><p>
+ This function can only be called immediately after
+ <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> or one of its sibling functions,
+ before any other operation on the connection such as
+ <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
+ </a> or
+ <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>. If called at the correct time,
+ the function activates single-row mode for the current query and
+ returns 1. Otherwise the mode stays unchanged and the function
+ returns 0. In any case, the mode reverts to normal after
+ completion of the current query.
+ </p></dd></dl></div><p>
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ While processing a query, the server may return some rows and then
+ encounter an error, causing the query to be aborted. Ordinarily,
+ <span class="application">libpq</span> discards any such rows and reports only the
+ error. But in single-row mode, those rows will have already been
+ returned to the application. Hence, the application will see some
+ <code class="literal">PGRES_SINGLE_TUPLE</code> <code class="structname">PGresult</code>
+ objects followed by a <code class="literal">PGRES_FATAL_ERROR</code> object. For
+ proper transactional behavior, the application must be designed to
+ discard or undo whatever has been done with the previously-processed
+ rows, if the query ultimately fails.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.5. Pipeline Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.7. Canceling Queries in Progress</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-ssl.html b/doc/src/sgml/html/libpq-ssl.html
new file mode 100644
index 0000000..7b36dad
--- /dev/null
+++ b/doc/src/sgml/html/libpq-ssl.html
@@ -0,0 +1,273 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.19. SSL Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters" /><link rel="next" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.19. SSL Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-SSL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.19. SSL Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-ssl.html#LIBQ-SSL-CERTIFICATES">34.19.1. Client Verification of Server Certificates</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT">34.19.2. Client Certificates</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-PROTECTION">34.19.3. Protection Provided in Different Modes</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-FILEUSAGE">34.19.4. SSL Client File Usage</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-INITIALIZE">34.19.5. SSL Library Initialization</a></span></dt></dl></div><a id="id-1.7.3.26.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> has native support for using <acronym class="acronym">SSL</acronym>
+ connections to encrypt client/server communications using
+ <acronym class="acronym">TLS</acronym> protocols for increased security.
+ See <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for details about the server-side
+ <acronym class="acronym">SSL</acronym> functionality.
+ </p><p>
+ <span class="application">libpq</span> reads the system-wide
+ <span class="productname">OpenSSL</span> configuration file. By default, this
+ file is named <code class="filename">openssl.cnf</code> and is located in the
+ directory reported by <code class="literal">openssl version -d</code>. This default
+ can be overridden by setting environment variable
+ <code class="envar">OPENSSL_CONF</code> to the name of the desired configuration
+ file.
+ </p><div class="sect2" id="LIBQ-SSL-CERTIFICATES"><div class="titlepage"><div><div><h3 class="title">34.19.1. Client Verification of Server Certificates</h3></div></div></div><p>
+ By default, <span class="productname">PostgreSQL</span> will not perform any verification of
+ the server certificate. This means that it is possible to spoof the server
+ identity (for example by modifying a DNS record or by taking over the server
+ IP address) without the client knowing. In order to prevent spoofing,
+ the client must be able to verify the server's identity via a chain of
+ trust. A chain of trust is established by placing a root (self-signed)
+ certificate authority (<acronym class="acronym">CA</acronym>) certificate on one
+ computer and a leaf certificate <span class="emphasis"><em>signed</em></span> by the
+ root certificate on another computer. It is also possible to use an
+ <span class="quote">“<span class="quote">intermediate</span>”</span> certificate which is signed by the root
+ certificate and signs leaf certificates.
+ </p><p>
+ To allow the client to verify the identity of the server, place a root
+ certificate on the client and a leaf certificate signed by the root
+ certificate on the server. To allow the server to verify the identity
+ of the client, place a root certificate on the server and a leaf
+ certificate signed by the root certificate on the client. One or more
+ intermediate certificates (usually stored with the leaf certificate)
+ can also be used to link the leaf certificate to the root certificate.
+ </p><p>
+ Once a chain of trust has been established, there are two ways for
+ the client to validate the leaf certificate sent by the server.
+ If the parameter <code class="literal">sslmode</code> is set to <code class="literal">verify-ca</code>,
+ libpq will verify that the server is trustworthy by checking the
+ certificate chain up to the root certificate stored on the client.
+ If <code class="literal">sslmode</code> is set to <code class="literal">verify-full</code>,
+ libpq will <span class="emphasis"><em>also</em></span> verify that the server host
+ name matches the name stored in the server certificate. The
+ SSL connection will fail if the server certificate cannot be
+ verified. <code class="literal">verify-full</code> is recommended in most
+ security-sensitive environments.
+ </p><p>
+ In <code class="literal">verify-full</code> mode, the host name is matched against the
+ certificate's Subject Alternative Name attribute(s) (SAN), or against the
+ Common Name attribute if no SAN of type <code class="literal">dNSName</code> is
+ present. If the certificate's name attribute starts with an asterisk
+ (<code class="literal">*</code>), the asterisk will be treated as
+ a wildcard, which will match all characters <span class="emphasis"><em>except</em></span> a dot
+ (<code class="literal">.</code>). This means the certificate will not match subdomains.
+ If the connection is made using an IP address instead of a host name, the
+ IP address will be matched (without doing any DNS lookups) against SANs of
+ type <code class="literal">iPAddress</code> or <code class="literal">dNSName</code>. If no
+ <code class="literal">iPAddress</code> SAN is present and no
+ matching <code class="literal">dNSName</code> SAN is present, the host IP address is
+ matched against the Common Name attribute.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ For backward compatibility with earlier versions of PostgreSQL, the host
+ IP address is verified in a manner different
+ from <a class="ulink" href="https://tools.ietf.org/html/rfc6125" target="_top">RFC 6125</a>.
+ The host IP address is always matched against <code class="literal">dNSName</code>
+ SANs as well as <code class="literal">iPAddress</code> SANs, and can be matched
+ against the Common Name attribute if no relevant SANs exist.
+ </p></div><p>
+ To allow server certificate verification, one or more root certificates
+ must be placed in the file <code class="filename">~/.postgresql/root.crt</code>
+ in the user's home directory. (On Microsoft Windows the file is named
+ <code class="filename">%APPDATA%\postgresql\root.crt</code>.) Intermediate
+ certificates should also be added to the file if they are needed to link
+ the certificate chain sent by the server to the root certificates
+ stored on the client.
+ </p><p>
+ Certificate Revocation List (CRL) entries are also checked
+ if the file <code class="filename">~/.postgresql/root.crl</code> exists
+ (<code class="filename">%APPDATA%\postgresql\root.crl</code> on Microsoft
+ Windows).
+ </p><p>
+ The location of the root certificate file and the CRL can be changed by
+ setting
+ the connection parameters <code class="literal">sslrootcert</code> and <code class="literal">sslcrl</code>
+ or the environment variables <code class="envar">PGSSLROOTCERT</code> and <code class="envar">PGSSLCRL</code>.
+ <code class="literal">sslcrldir</code> or the environment variable <code class="envar">PGSSLCRLDIR</code>
+ can also be used to specify a directory containing CRL files.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ For backwards compatibility with earlier versions of PostgreSQL, if a
+ root CA file exists, the behavior of
+ <code class="literal">sslmode</code>=<code class="literal">require</code> will be the same
+ as that of <code class="literal">verify-ca</code>, meaning the server certificate
+ is validated against the CA. Relying on this behavior is discouraged,
+ and applications that need certificate validation should always use
+ <code class="literal">verify-ca</code> or <code class="literal">verify-full</code>.
+ </p></div></div><div class="sect2" id="LIBPQ-SSL-CLIENTCERT"><div class="titlepage"><div><div><h3 class="title">34.19.2. Client Certificates</h3></div></div></div><p>
+ If the server attempts to verify the identity of the
+ client by requesting the client's leaf certificate,
+ <span class="application">libpq</span> will send the certificate(s) stored in
+ file <code class="filename">~/.postgresql/postgresql.crt</code> in the user's home
+ directory. The certificates must chain to the root certificate trusted
+ by the server. A matching
+ private key file <code class="filename">~/.postgresql/postgresql.key</code> must also
+ be present.
+ On Microsoft Windows these files are named
+ <code class="filename">%APPDATA%\postgresql\postgresql.crt</code> and
+ <code class="filename">%APPDATA%\postgresql\postgresql.key</code>.
+ The location of the certificate and key files can be overridden by the
+ connection parameters <code class="literal">sslcert</code>
+ and <code class="literal">sslkey</code>, or by the
+ environment variables <code class="envar">PGSSLCERT</code> and <code class="envar">PGSSLKEY</code>.
+ </p><p>
+ On Unix systems, the permissions on the private key file must disallow
+ any access to world or group; achieve this by a command such as
+ <code class="command">chmod 0600 ~/.postgresql/postgresql.key</code>.
+ Alternatively, the file can be owned by root and have group read access
+ (that is, <code class="literal">0640</code> permissions). That setup is intended
+ for installations where certificate and key files are managed by the
+ operating system. The user of <span class="application">libpq</span> should
+ then be made a member of the group that has access to those certificate
+ and key files. (On Microsoft Windows, there is no file permissions
+ check, since the <code class="filename">%APPDATA%\postgresql</code> directory is
+ presumed secure.)
+ </p><p>
+ The first certificate in <code class="filename">postgresql.crt</code> must be the
+ client's certificate because it must match the client's private key.
+ <span class="quote">“<span class="quote">Intermediate</span>”</span> certificates can be optionally appended
+ to the file — doing so avoids requiring storage of intermediate
+ certificates on the server (<a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a>).
+ </p><p>
+ The certificate and key may be in PEM or ASN.1 DER format.
+ </p><p>
+ The key may be
+ stored in cleartext or encrypted with a passphrase using any algorithm
+ supported by <span class="productname">OpenSSL</span>, like AES-128. If the key
+ is stored encrypted, then the passphrase may be provided in the
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> connection option. If an
+ encrypted key is supplied and the <code class="literal">sslpassword</code> option
+ is absent or blank, a password will be prompted for interactively by
+ <span class="productname">OpenSSL</span> with a
+ <code class="literal">Enter PEM pass phrase:</code> prompt if a TTY is available.
+ Applications can override the client certificate prompt and the handling
+ of the <code class="literal">sslpassword</code> parameter by supplying their own
+ key password callback; see
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code></a>.
+ </p><p>
+ For instructions on creating certificates, see <a class="xref" href="ssl-tcp.html#SSL-CERTIFICATE-CREATION" title="19.9.5. Creating Certificates">Section 19.9.5</a>.
+ </p></div><div class="sect2" id="LIBPQ-SSL-PROTECTION"><div class="titlepage"><div><div><h3 class="title">34.19.3. Protection Provided in Different Modes</h3></div></div></div><p>
+ The different values for the <code class="literal">sslmode</code> parameter provide different
+ levels of protection. SSL can provide
+ protection against three types of attacks:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Eavesdropping</span></dt><dd><p>If a third party can examine the network traffic between the
+ client and the server, it can read both connection information (including
+ the user name and password) and the data that is passed. <acronym class="acronym">SSL</acronym>
+ uses encryption to prevent this.
+ </p></dd><dt><span class="term">Man-in-the-middle (<acronym class="acronym">MITM</acronym>)</span></dt><dd><p>If a third party can modify the data while passing between the
+ client and server, it can pretend to be the server and therefore see and
+ modify data <span class="emphasis"><em>even if it is encrypted</em></span>. The third party can then
+ forward the connection information and data to the original server,
+ making it impossible to detect this attack. Common vectors to do this
+ include DNS poisoning and address hijacking, whereby the client is directed
+ to a different server than intended. There are also several other
+ attack methods that can accomplish this. <acronym class="acronym">SSL</acronym> uses certificate
+ verification to prevent this, by authenticating the server to the client.
+ </p></dd><dt><span class="term">Impersonation</span></dt><dd><p>If a third party can pretend to be an authorized client, it can
+ simply access data it should not have access to. Typically this can
+ happen through insecure password management. <acronym class="acronym">SSL</acronym> uses
+ client certificates to prevent this, by making sure that only holders
+ of valid certificates can access the server.
+ </p></dd></dl></div><p>
+ </p><p>
+ For a connection to be known SSL-secured, SSL usage must be configured
+ on <span class="emphasis"><em>both the client and the server</em></span> before the connection
+ is made. If it is only configured on the server, the client may end up
+ sending sensitive information (e.g., passwords) before
+ it knows that the server requires high security. In libpq, secure
+ connections can be ensured
+ by setting the <code class="literal">sslmode</code> parameter to <code class="literal">verify-full</code> or
+ <code class="literal">verify-ca</code>, and providing the system with a root certificate to
+ verify against. This is analogous to using an <code class="literal">https</code>
+ <acronym class="acronym">URL</acronym> for encrypted web browsing.
+ </p><p>
+ Once the server has been authenticated, the client can pass sensitive data.
+ This means that up until this point, the client does not need to know if
+ certificates will be used for authentication, making it safe to specify that
+ only in the server configuration.
+ </p><p>
+ All <acronym class="acronym">SSL</acronym> options carry overhead in the form of encryption and
+ key-exchange, so there is a trade-off that has to be made between performance
+ and security. <a class="xref" href="libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS" title="Table 34.1. SSL Mode Descriptions">Table 34.1</a>
+ illustrates the risks the different <code class="literal">sslmode</code> values
+ protect against, and what statement they make about security and overhead.
+ </p><div class="table" id="LIBPQ-SSL-SSLMODE-STATEMENTS"><p class="title"><strong>Table 34.1. SSL Mode Descriptions</strong></p><div class="table-contents"><table class="table" summary="SSL Mode Descriptions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th><code class="literal">sslmode</code></th><th>Eavesdropping protection</th><th><acronym class="acronym">MITM</acronym> protection</th><th>Statement</th></tr></thead><tbody><tr><td><code class="literal">disable</code></td><td>No</td><td>No</td><td>I don't care about security, and I don't want to pay the overhead
+ of encryption.
+ </td></tr><tr><td><code class="literal">allow</code></td><td>Maybe</td><td>No</td><td>I don't care about security, but I will pay the overhead of
+ encryption if the server insists on it.
+ </td></tr><tr><td><code class="literal">prefer</code></td><td>Maybe</td><td>No</td><td>I don't care about encryption, but I wish to pay the overhead of
+ encryption if the server supports it.
+ </td></tr><tr><td><code class="literal">require</code></td><td>Yes</td><td>No</td><td>I want my data to be encrypted, and I accept the overhead. I trust
+ that the network will make sure I always connect to the server I want.
+ </td></tr><tr><td><code class="literal">verify-ca</code></td><td>Yes</td><td>Depends on CA policy</td><td>I want my data encrypted, and I accept the overhead. I want to be
+ sure that I connect to a server that I trust.
+ </td></tr><tr><td><code class="literal">verify-full</code></td><td>Yes</td><td>Yes</td><td>I want my data encrypted, and I accept the overhead. I want to be
+ sure that I connect to a server I trust, and that it's the one I
+ specify.
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The difference between <code class="literal">verify-ca</code> and <code class="literal">verify-full</code>
+ depends on the policy of the root <acronym class="acronym">CA</acronym>. If a public
+ <acronym class="acronym">CA</acronym> is used, <code class="literal">verify-ca</code> allows connections to a server
+ that <span class="emphasis"><em>somebody else</em></span> may have registered with the <acronym class="acronym">CA</acronym>.
+ In this case, <code class="literal">verify-full</code> should always be used. If
+ a local <acronym class="acronym">CA</acronym> is used, or even a self-signed certificate, using
+ <code class="literal">verify-ca</code> often provides enough protection.
+ </p><p>
+ The default value for <code class="literal">sslmode</code> is <code class="literal">prefer</code>. As is shown
+ in the table, this makes no sense from a security point of view, and it only
+ promises performance overhead if possible. It is only provided as the default
+ for backward compatibility, and is not recommended in secure deployments.
+ </p></div><div class="sect2" id="LIBPQ-SSL-FILEUSAGE"><div class="titlepage"><div><div><h3 class="title">34.19.4. SSL Client File Usage</h3></div></div></div><p>
+ <a class="xref" href="libpq-ssl.html#LIBPQ-SSL-FILE-USAGE" title="Table 34.2. Libpq/Client SSL File Usage">Table 34.2</a> summarizes the files that are
+ relevant to the SSL setup on the client.
+ </p><div class="table" id="LIBPQ-SSL-FILE-USAGE"><p class="title"><strong>Table 34.2. Libpq/Client SSL File Usage</strong></p><div class="table-contents"><table class="table" summary="Libpq/Client SSL File Usage" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>File</th><th>Contents</th><th>Effect</th></tr></thead><tbody><tr><td><code class="filename">~/.postgresql/postgresql.crt</code></td><td>client certificate</td><td>sent to server</td></tr><tr><td><code class="filename">~/.postgresql/postgresql.key</code></td><td>client private key</td><td>proves client certificate sent by owner; does not indicate
+ certificate owner is trustworthy</td></tr><tr><td><code class="filename">~/.postgresql/root.crt</code></td><td>trusted certificate authorities</td><td>checks that server certificate is signed by a trusted certificate
+ authority</td></tr><tr><td><code class="filename">~/.postgresql/root.crl</code></td><td>certificates revoked by certificate authorities</td><td>server certificate must not be on this list</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="LIBPQ-SSL-INITIALIZE"><div class="titlepage"><div><div><h3 class="title">34.19.5. SSL Library Initialization</h3></div></div></div><p>
+ If your application initializes <code class="literal">libssl</code> and/or
+ <code class="literal">libcrypto</code> libraries and <span class="application">libpq</span>
+ is built with <acronym class="acronym">SSL</acronym> support, you should call
+ <a class="xref" href="libpq-ssl.html#LIBPQ-PQINITOPENSSL"><code class="function">PQinitOpenSSL</code></a> to tell <span class="application">libpq</span>
+ that the <code class="literal">libssl</code> and/or <code class="literal">libcrypto</code> libraries
+ have been initialized by your application, so that
+ <span class="application">libpq</span> will not also initialize those libraries.
+ However, this is unnecessary when using <span class="productname">OpenSSL</span>
+ version 1.1.0 or later, as duplicate initializations are no longer problematic.
+ </p><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQINITOPENSSL"><span class="term"><code class="function">PQinitOpenSSL</code><a id="id-1.7.3.26.9.3.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Allows applications to select which security libraries to initialize.
+</p><pre class="synopsis">
+void PQinitOpenSSL(int do_ssl, int do_crypto);
+</pre><p>
+ </p><p>
+ When <em class="parameter"><code>do_ssl</code></em> is non-zero, <span class="application">libpq</span>
+ will initialize the <span class="productname">OpenSSL</span> library before first
+ opening a database connection. When <em class="parameter"><code>do_crypto</code></em> is
+ non-zero, the <code class="literal">libcrypto</code> library will be initialized. By
+ default (if <a class="xref" href="libpq-ssl.html#LIBPQ-PQINITOPENSSL"><code class="function">PQinitOpenSSL</code></a> is not called), both libraries
+ are initialized. When SSL support is not compiled in, this function is
+ present but does nothing.
+ </p><p>
+ If your application uses and initializes either <span class="productname">OpenSSL</span>
+ or its underlying <code class="literal">libcrypto</code> library, you <span class="emphasis"><em>must</em></span>
+ call this function with zeroes for the appropriate parameter(s)
+ before first opening a database connection. Also be sure that you
+ have done that initialization before opening a database connection.
+ </p></dd><dt id="LIBPQ-PQINITSSL"><span class="term"><code class="function">PQinitSSL</code><a id="id-1.7.3.26.9.3.1.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Allows applications to select which security libraries to initialize.
+</p><pre class="synopsis">
+void PQinitSSL(int do_ssl);
+</pre><p>
+ </p><p>
+ This function is equivalent to
+ <code class="literal">PQinitOpenSSL(do_ssl, do_ssl)</code>.
+ It is sufficient for applications that initialize both or neither
+ of <span class="productname">OpenSSL</span> and <code class="literal">libcrypto</code>.
+ </p><p>
+ <a class="xref" href="libpq-ssl.html#LIBPQ-PQINITSSL"><code class="function">PQinitSSL</code></a> has been present since
+ <span class="productname">PostgreSQL</span> 8.0, while <a class="xref" href="libpq-ssl.html#LIBPQ-PQINITOPENSSL"><code class="function">PQinitOpenSSL</code></a>
+ was added in <span class="productname">PostgreSQL</span> 8.4, so <a class="xref" href="libpq-ssl.html#LIBPQ-PQINITSSL"><code class="function">PQinitSSL</code></a>
+ might be preferable for applications that need to work with older
+ versions of <span class="application">libpq</span>.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-threading.html" title="34.20. Behavior in Threaded Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.18. LDAP Lookup of Connection Parameters </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.20. Behavior in Threaded Programs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-status.html b/doc/src/sgml/html/libpq-status.html
new file mode 100644
index 0000000..b4a968e
--- /dev/null
+++ b/doc/src/sgml/html/libpq-status.html
@@ -0,0 +1,427 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.2. Connection Status Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-connect.html" title="34.1. Database Connection Control Functions" /><link rel="next" href="libpq-exec.html" title="34.3. Command Execution Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.2. Connection Status Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-exec.html" title="34.3. Command Execution Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-STATUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.2. Connection Status Functions</h2></div></div></div><p>
+ These functions can be used to interrogate the status
+ of an existing database connection object.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <a id="id-1.7.3.9.3.1.1" class="indexterm"></a>
+ <a id="id-1.7.3.9.3.1.2" class="indexterm"></a>
+ <span class="application">libpq</span> application programmers should be careful to
+ maintain the <code class="structname">PGconn</code> abstraction. Use the accessor
+ functions described below to get at the contents of <code class="structname">PGconn</code>.
+ Reference to internal <code class="structname">PGconn</code> fields using
+ <code class="filename">libpq-int.h</code> is not recommended because they are subject to change
+ in the future.
+ </p></div><p>
+ The following functions return parameter values established at connection.
+ These values are fixed for the life of the connection. If a multi-host
+ connection string is used, the values of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a>,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a>, and <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> can change if a new connection
+ is established using the same <code class="structname">PGconn</code> object. Other values
+ are fixed for the lifetime of the <code class="structname">PGconn</code> object.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQDB"><span class="term"><code class="function">PQdb</code><a id="id-1.7.3.9.4.6.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the database name of the connection.
+</p><pre class="synopsis">
+char *PQdb(const PGconn *conn);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQUSER"><span class="term"><code class="function">PQuser</code><a id="id-1.7.3.9.4.6.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the user name of the connection.
+</p><pre class="synopsis">
+char *PQuser(const PGconn *conn);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQPASS"><span class="term"><code class="function">PQpass</code><a id="id-1.7.3.9.4.6.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the password of the connection.
+</p><pre class="synopsis">
+char *PQpass(const PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> will return either the password specified
+ in the connection parameters, or if there was none and the password
+ was obtained from the <a class="link" href="libpq-pgpass.html" title="34.16. The Password File">password
+ file</a>, it will return that. In the latter case,
+ if multiple hosts were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </p></dd><dt id="LIBPQ-PQHOST"><span class="term"><code class="function">PQhost</code><a id="id-1.7.3.9.4.6.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the server host name of the active connection.
+ This can be a host name, an IP address, or a directory path if the
+ connection is via Unix socket. (The path case can be distinguished
+ because it will always be an absolute path, beginning
+ with <code class="literal">/</code>.)
+</p><pre class="synopsis">
+char *PQhost(const PGconn *conn);
+</pre><p>
+ </p><p>
+ If the connection parameters specified both <code class="literal">host</code> and
+ <code class="literal">hostaddr</code>, then <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> will
+ return the <code class="literal">host</code> information. If only
+ <code class="literal">hostaddr</code> was specified, then that is returned.
+ If multiple hosts were specified in the connection parameters,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns the host actually connected to.
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ Otherwise, if there is an error producing the host information (perhaps
+ if the connection has not been fully established or there was an
+ error), it returns an empty string.
+ </p><p>
+ If multiple hosts were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </p></dd><dt id="LIBPQ-PQHOSTADDR"><span class="term"><code class="function">PQhostaddr</code><a id="id-1.7.3.9.4.6.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the server IP address of the active connection.
+ This can be the address that a host name resolved to,
+ or an IP address provided through the <code class="literal">hostaddr</code>
+ parameter.
+</p><pre class="synopsis">
+char *PQhostaddr(const PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOSTADDR"><code class="function">PQhostaddr</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ Otherwise, if there is an error producing the host information
+ (perhaps if the connection has not been fully established or
+ there was an error), it returns an empty string.
+ </p></dd><dt id="LIBPQ-PQPORT"><span class="term"><code class="function">PQport</code><a id="id-1.7.3.9.4.6.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the port of the active connection.
+
+</p><pre class="synopsis">
+char *PQport(const PGconn *conn);
+</pre><p>
+ </p><p>
+ If multiple ports were specified in the connection parameters,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns the port actually connected to.
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ Otherwise, if there is an error producing the port information (perhaps
+ if the connection has not been fully established or there was an
+ error), it returns an empty string.
+ </p><p>
+ If multiple ports were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </p></dd><dt id="LIBPQ-PQTTY"><span class="term"><code class="function">PQtty</code><a id="id-1.7.3.9.4.6.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ This function no longer does anything, but it remains for backwards
+ compatibility. The function always return an empty string, or
+ <code class="symbol">NULL</code> if the <em class="parameter"><code>conn</code></em> argument is
+ <code class="symbol">NULL</code>.
+
+</p><pre class="synopsis">
+char *PQtty(const PGconn *conn);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQOPTIONS"><span class="term"><code class="function">PQoptions</code><a id="id-1.7.3.9.4.6.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the command-line options passed in the connection request.
+</p><pre class="synopsis">
+char *PQoptions(const PGconn *conn);
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ The following functions return status data that can change as operations
+ are executed on the <code class="structname">PGconn</code> object.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSTATUS"><span class="term"><code class="function">PQstatus</code><a id="id-1.7.3.9.5.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the status of the connection.
+</p><pre class="synopsis">
+ConnStatusType PQstatus(const PGconn *conn);
+</pre><p>
+ </p><p>
+ The status can be one of a number of values. However, only two of
+ these are seen outside of an asynchronous connection procedure:
+ <code class="literal">CONNECTION_OK</code> and
+ <code class="literal">CONNECTION_BAD</code>. A good connection to the database
+ has the status <code class="literal">CONNECTION_OK</code>. A failed
+ connection attempt is signaled by status
+ <code class="literal">CONNECTION_BAD</code>. Ordinarily, an OK status will
+ remain so until <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>, but a communications
+ failure might result in the status changing to
+ <code class="literal">CONNECTION_BAD</code> prematurely. In that case the
+ application could try to recover by calling
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a>.
+ </p><p>
+ See the entry for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
+ and <code class="function">PQconnectPoll</code> with regards to other status codes that
+ might be returned.
+ </p></dd><dt id="LIBPQ-PQTRANSACTIONSTATUS"><span class="term"><code class="function">PQtransactionStatus</code><a id="id-1.7.3.9.5.2.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the current in-transaction status of the server.
+
+</p><pre class="synopsis">
+PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
+</pre><p>
+
+ The status can be <code class="literal">PQTRANS_IDLE</code> (currently idle),
+ <code class="literal">PQTRANS_ACTIVE</code> (a command is in progress),
+ <code class="literal">PQTRANS_INTRANS</code> (idle, in a valid transaction block),
+ or <code class="literal">PQTRANS_INERROR</code> (idle, in a failed transaction block).
+ <code class="literal">PQTRANS_UNKNOWN</code> is reported if the connection is bad.
+ <code class="literal">PQTRANS_ACTIVE</code> is reported only when a query
+ has been sent to the server and not yet completed.
+ </p></dd><dt id="LIBPQ-PQPARAMETERSTATUS"><span class="term"><code class="function">PQparameterStatus</code><a id="id-1.7.3.9.5.2.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Looks up a current parameter setting of the server.
+
+</p><pre class="synopsis">
+const char *PQparameterStatus(const PGconn *conn, const char *paramName);
+</pre><p>
+
+ Certain parameter values are reported by the server automatically at
+ connection startup or whenever their values change.
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPARAMETERSTATUS"><code class="function">PQparameterStatus</code></a> can be used to interrogate these settings.
+ It returns the current value of a parameter if known, or <code class="symbol">NULL</code>
+ if the parameter is not known.
+ </p><p>
+ Parameters reported as of the current release include
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code>,
+ <code class="varname">client_encoding</code>,
+ <code class="varname">application_name</code>,
+ <code class="varname">default_transaction_read_only</code>,
+ <code class="varname">in_hot_standby</code>,
+ <code class="varname">is_superuser</code>,
+ <code class="varname">session_authorization</code>,
+ <code class="varname">DateStyle</code>,
+ <code class="varname">IntervalStyle</code>,
+ <code class="varname">TimeZone</code>,
+ <code class="varname">integer_datetimes</code>, and
+ <code class="varname">standard_conforming_strings</code>.
+ (<code class="varname">server_encoding</code>, <code class="varname">TimeZone</code>, and
+ <code class="varname">integer_datetimes</code> were not reported by releases before 8.0;
+ <code class="varname">standard_conforming_strings</code> was not reported by releases
+ before 8.1;
+ <code class="varname">IntervalStyle</code> was not reported by releases before 8.4;
+ <code class="varname">application_name</code> was not reported by releases before
+ 9.0;
+ <code class="varname">default_transaction_read_only</code> and
+ <code class="varname">in_hot_standby</code> were not reported by releases before
+ 14.)
+ Note that
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code> and
+ <code class="varname">integer_datetimes</code>
+ cannot change after startup.
+ </p><p>
+ If no value for <code class="varname">standard_conforming_strings</code> is reported,
+ applications can assume it is <code class="literal">off</code>, that is, backslashes
+ are treated as escapes in string literals. Also, the presence of
+ this parameter can be taken as an indication that the escape string
+ syntax (<code class="literal">E'...'</code>) is accepted.
+ </p><p>
+ Although the returned pointer is declared <code class="literal">const</code>, it in fact
+ points to mutable storage associated with the <code class="literal">PGconn</code> structure.
+ It is unwise to assume the pointer will remain valid across queries.
+ </p></dd><dt id="LIBPQ-PQPROTOCOLVERSION"><span class="term"><code class="function">PQprotocolVersion</code><a id="id-1.7.3.9.5.2.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Interrogates the frontend/backend protocol being used.
+</p><pre class="synopsis">
+int PQprotocolVersion(const PGconn *conn);
+</pre><p>
+ Applications might wish to use this function to determine whether certain
+ features are supported. Currently, the possible values are 3
+ (3.0 protocol), or zero (connection bad). The protocol version will
+ not change after connection startup is complete, but it could
+ theoretically change during a connection reset. The 3.0 protocol is
+ supported by <span class="productname">PostgreSQL</span> server versions 7.4
+ and above.
+ </p></dd><dt id="LIBPQ-PQSERVERVERSION"><span class="term"><code class="function">PQserverVersion</code><a id="id-1.7.3.9.5.2.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns an integer representing the server version.
+</p><pre class="synopsis">
+int PQserverVersion(const PGconn *conn);
+</pre><p>
+ </p><p>
+ Applications might use this function to determine the version of the
+ database server they are connected to. The result is formed by
+ multiplying the server's major version number by 10000 and adding
+ the minor version number. For example, version 10.1 will be
+ returned as 100001, and version 11.0 will be returned as 110000.
+ Zero is returned if the connection is bad.
+ </p><p>
+ Prior to major version 10, <span class="productname">PostgreSQL</span> used
+ three-part version numbers in which the first two parts together
+ represented the major version. For those
+ versions, <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a> uses two digits for each
+ part; for example version 9.1.5 will be returned as 90105, and
+ version 9.2.0 will be returned as 90200.
+ </p><p>
+ Therefore, for purposes of determining feature compatibility,
+ applications should divide the result of <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a>
+ by 100 not 10000 to determine a logical major version number.
+ In all release series, only the last two digits differ between
+ minor releases (bug-fix releases).
+ </p></dd><dt id="LIBPQ-PQERRORMESSAGE"><span class="term"><code class="function">PQerrorMessage</code><a id="id-1.7.3.9.5.2.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a id="id-1.7.3.9.5.2.6.2.1.1" class="indexterm"></a> Returns the error message
+ most recently generated by an operation on the connection.
+
+</p><pre class="synopsis">
+char *PQerrorMessage(const PGconn *conn);
+</pre><p>
+
+ </p><p>
+ Nearly all <span class="application">libpq</span> functions will set a message for
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> if they fail. Note that by
+ <span class="application">libpq</span> convention, a nonempty
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> result can consist of multiple lines,
+ and will include a trailing newline. The caller should not free
+ the result directly. It will be freed when the associated
+ <code class="structname">PGconn</code> handle is passed to
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>. The result string should not be
+ expected to remain the same across operations on the
+ <code class="literal">PGconn</code> structure.
+ </p></dd><dt id="LIBPQ-PQSOCKET"><span class="term"><code class="function">PQsocket</code><a id="id-1.7.3.9.5.2.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Obtains the file descriptor number of the connection socket to
+ the server. A valid descriptor will be greater than or equal
+ to 0; a result of -1 indicates that no server connection is
+ currently open. (This will not change during normal operation,
+ but could change during connection setup or reset.)
+
+</p><pre class="synopsis">
+int PQsocket(const PGconn *conn);
+</pre><p>
+
+ </p></dd><dt id="LIBPQ-PQBACKENDPID"><span class="term"><code class="function">PQbackendPID</code><a id="id-1.7.3.9.5.2.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the process <acronym class="acronym">ID</acronym> (PID)<a id="id-1.7.3.9.5.2.8.2.1.2" class="indexterm"></a>
+ of the backend process handling this connection.
+
+</p><pre class="synopsis">
+int PQbackendPID(const PGconn *conn);
+</pre><p>
+ </p><p>
+ The backend <acronym class="acronym">PID</acronym> is useful for debugging
+ purposes and for comparison to <code class="command">NOTIFY</code>
+ messages (which include the <acronym class="acronym">PID</acronym> of the
+ notifying backend process). Note that the
+ <acronym class="acronym">PID</acronym> belongs to a process executing on the
+ database server host, not the local host!
+ </p></dd><dt id="LIBPQ-PQCONNECTIONNEEDSPASSWORD"><span class="term"><code class="function">PQconnectionNeedsPassword</code><a id="id-1.7.3.9.5.2.9.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns true (1) if the connection authentication method
+ required a password, but none was available.
+ Returns false (0) if not.
+
+</p><pre class="synopsis">
+int PQconnectionNeedsPassword(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function can be applied after a failed connection attempt
+ to decide whether to prompt the user for a password.
+ </p></dd><dt id="LIBPQ-PQCONNECTIONUSEDPASSWORD"><span class="term"><code class="function">PQconnectionUsedPassword</code><a id="id-1.7.3.9.5.2.10.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns true (1) if the connection authentication method
+ used a password. Returns false (0) if not.
+
+</p><pre class="synopsis">
+int PQconnectionUsedPassword(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function can be applied after either a failed or successful
+ connection attempt to detect whether the server demanded a password.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following functions return information related to SSL. This information
+ usually doesn't change after a connection is established.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSSLINUSE"><span class="term"><code class="function">PQsslInUse</code><a id="id-1.7.3.9.6.1.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns true (1) if the connection uses SSL, false (0) if not.
+
+</p><pre class="synopsis">
+int PQsslInUse(const PGconn *conn);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQSSLATTRIBUTE"><span class="term"><code class="function">PQsslAttribute</code><a id="id-1.7.3.9.6.1.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns SSL-related information about the connection.
+
+</p><pre class="synopsis">
+const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
+</pre><p>
+ </p><p>
+ The list of available attributes varies depending on the SSL library
+ being used and the type of connection. Returns NULL if the connection
+ does not use SSL or the specified attribute name is not defined for the
+ library in use.
+ </p><p>
+ The following attributes are commonly available:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">library</code></span></dt><dd><p>
+ Name of the SSL implementation in use. (Currently, only
+ <code class="literal">"OpenSSL"</code> is implemented)
+ </p></dd><dt><span class="term"><code class="literal">protocol</code></span></dt><dd><p>
+ SSL/TLS version in use. Common values
+ are <code class="literal">"TLSv1"</code>, <code class="literal">"TLSv1.1"</code>
+ and <code class="literal">"TLSv1.2"</code>, but an implementation may
+ return other strings if some other protocol is used.
+ </p></dd><dt><span class="term"><code class="literal">key_bits</code></span></dt><dd><p>
+ Number of key bits used by the encryption algorithm.
+ </p></dd><dt><span class="term"><code class="literal">cipher</code></span></dt><dd><p>
+ A short name of the ciphersuite used, e.g.,
+ <code class="literal">"DHE-RSA-DES-CBC3-SHA"</code>. The names are specific
+ to each SSL implementation.
+ </p></dd><dt><span class="term"><code class="literal">compression</code></span></dt><dd><p>
+ Returns "on" if SSL compression is in use, else it returns "off".
+ </p></dd></dl></div><p>
+ </p><p>
+ As a special case, the <code class="literal">library</code> attribute may be
+ queried without a connection by passing NULL as
+ the <code class="literal">conn</code> argument. The result will be the default
+ SSL library name, or NULL if <span class="application">libpq</span> was
+ compiled without any SSL support. (Prior
+ to <span class="productname">PostgreSQL</span> version 15, passing NULL as
+ the <code class="literal">conn</code> argument always resulted in NULL.
+ Client programs needing to differentiate between the newer and older
+ implementations of this case may check the
+ <code class="literal">LIBPQ_HAS_SSL_LIBRARY_DETECTION</code> feature macro.)
+ </p></dd><dt id="LIBPQ-PQSSLATTRIBUTENAMES"><span class="term"><code class="function">PQsslAttributeNames</code><a id="id-1.7.3.9.6.1.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns an array of SSL attribute names available.
+ The array is terminated by a NULL pointer.
+</p><pre class="synopsis">
+const char * const * PQsslAttributeNames(const PGconn *conn);
+</pre><p>
+ </p></dd><dt id="LIBPQ-PQSSLSTRUCT"><span class="term"><code class="function">PQsslStruct</code><a id="id-1.7.3.9.6.1.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns a pointer to an SSL-implementation-specific object describing
+ the connection. Returns NULL if the connection is not encrypted
+ or the requested type of object is not available from the connection's
+ SSL implementation.
+</p><pre class="synopsis">
+void *PQsslStruct(const PGconn *conn, const char *struct_name);
+</pre><p>
+ </p><p>
+ The struct(s) available depend on the SSL implementation in use.
+ For <span class="productname">OpenSSL</span>, there is one struct,
+ available under the name <code class="literal">OpenSSL</code>,
+ and it returns a pointer to
+ <span class="productname">OpenSSL</span>'s <code class="literal">SSL</code> struct.
+ To use this function, code along the following lines could be used:
+</p><pre class="programlisting">
+#include &lt;libpq-fe.h&gt;
+#include &lt;openssl/ssl.h&gt;
+
+...
+
+ SSL *ssl;
+
+ dbconn = PQconnectdb(...);
+ ...
+
+ ssl = PQsslStruct(dbconn, "OpenSSL");
+ if (ssl)
+ {
+ /* use OpenSSL functions to access ssl */
+ }
+</pre><p>
+ </p><p>
+ This structure can be used to verify encryption levels, check server
+ certificates, and more. Refer to the <span class="productname">OpenSSL</span>
+ documentation for information about this structure.
+ </p></dd><dt id="LIBPQ-PQGETSSL"><span class="term"><code class="function">PQgetssl</code><a id="id-1.7.3.9.6.1.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a id="id-1.7.3.9.6.1.5.2.1.1" class="indexterm"></a>
+ Returns the SSL structure used in the connection, or NULL
+ if SSL is not in use.
+
+</p><pre class="synopsis">
+void *PQgetssl(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function is equivalent to <code class="literal">PQsslStruct(conn, "OpenSSL")</code>. It should
+ not be used in new applications, because the returned struct is
+ specific to <span class="productname">OpenSSL</span> and will not be
+ available if another <acronym class="acronym">SSL</acronym> implementation is used.
+ To check if a connection uses SSL, call
+ <a class="xref" href="libpq-status.html#LIBPQ-PQSSLINUSE"><code class="function">PQsslInUse</code></a> instead, and for more details about the
+ connection, use <a class="xref" href="libpq-status.html#LIBPQ-PQSSLATTRIBUTE"><code class="function">PQsslAttribute</code></a>.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-exec.html" title="34.3. Command Execution Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.1. Database Connection Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.3. Command Execution Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq-threading.html b/doc/src/sgml/html/libpq-threading.html
new file mode 100644
index 0000000..d3132d7
--- /dev/null
+++ b/doc/src/sgml/html/libpq-threading.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.20. Behavior in Threaded Programs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-ssl.html" title="34.19. SSL Support" /><link rel="next" href="libpq-build.html" title="34.21. Building libpq Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.20. Behavior in Threaded Programs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-ssl.html" title="34.19. SSL Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-build.html" title="34.21. Building libpq Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-THREADING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.20. Behavior in Threaded Programs</h2></div></div></div><a id="id-1.7.3.27.2" class="indexterm"></a><p>
+ <span class="application">libpq</span> is reentrant and thread-safe by default.
+ You might need to use special compiler command-line
+ options when you compile your application code. Refer to your
+ system's documentation for information about how to build
+ thread-enabled applications, or look in
+ <code class="filename">src/Makefile.global</code> for <code class="literal">PTHREAD_CFLAGS</code>
+ and <code class="literal">PTHREAD_LIBS</code>. This function allows the querying of
+ <span class="application">libpq</span>'s thread-safe status:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQISTHREADSAFE"><span class="term"><code class="function">PQisthreadsafe</code><a id="id-1.7.3.27.4.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the thread safety status of the
+ <span class="application">libpq</span> library.
+</p><pre class="synopsis">
+int PQisthreadsafe();
+</pre><p>
+ </p><p>
+ Returns 1 if the <span class="application">libpq</span> is thread-safe
+ and 0 if it is not.
+ </p></dd></dl></div><p>
+ One thread restriction is that no two threads attempt to manipulate
+ the same <code class="structname">PGconn</code> object at the same time. In particular,
+ you cannot issue concurrent commands from different threads through
+ the same connection object. (If you need to run concurrent commands,
+ use multiple connections.)
+ </p><p>
+ <code class="structname">PGresult</code> objects are normally read-only after creation,
+ and so can be passed around freely between threads. However, if you use
+ any of the <code class="structname">PGresult</code>-modifying functions described in
+ <a class="xref" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Section 34.12</a> or <a class="xref" href="libpq-events.html" title="34.14. Event System">Section 34.14</a>, it's up
+ to you to avoid concurrent operations on the same <code class="structname">PGresult</code>,
+ too.
+ </p><p>
+ The deprecated functions <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a> and
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDSTATUS"><code class="function">PQoidStatus</code></a> are not thread-safe and should not be
+ used in multithread programs. <a class="xref" href="libpq-cancel.html#LIBPQ-PQREQUESTCANCEL"><code class="function">PQrequestCancel</code></a>
+ can be replaced by <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>.
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDSTATUS"><code class="function">PQoidStatus</code></a> can be replaced by
+ <a class="xref" href="libpq-exec.html#LIBPQ-PQOIDVALUE"><code class="function">PQoidValue</code></a>.
+ </p><p>
+ If you are using Kerberos inside your application (in addition to inside
+ <span class="application">libpq</span>), you will need to do locking around
+ Kerberos calls because Kerberos functions are not thread-safe. See
+ function <code class="function">PQregisterThreadLock</code> in the
+ <span class="application">libpq</span> source code for a way to do cooperative
+ locking between <span class="application">libpq</span> and your application.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-ssl.html" title="34.19. SSL Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-build.html" title="34.21. Building libpq Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.19. SSL Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.21. Building <span class="application">libpq</span> Programs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/libpq.html b/doc/src/sgml/html/libpq.html
new file mode 100644
index 0000000..65527c2
--- /dev/null
+++ b/doc/src/sgml/html/libpq.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 34. libpq — C Library</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="client-interfaces.html" title="Part IV. Client Interfaces" /><link rel="next" href="libpq-connect.html" title="34.1. Database Connection Control Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="client-interfaces.html" title="Part IV. Client Interfaces">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><th width="60%" align="center">Part IV. Client Interfaces</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="LIBPQ"><div class="titlepage"><div><div><h2 class="title">Chapter 34. <span class="application">libpq</span> — C Library</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="libpq-connect.html">34.1. Database Connection Control Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">34.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-status.html">34.2. Connection Status Functions</a></span></dt><dt><span class="sect1"><a href="libpq-exec.html">34.3. Command Execution Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-MAIN">34.3.1. Main Functions</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-SELECT-INFO">34.3.2. Retrieving Query Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-NONSELECT">34.3.3. Retrieving Other Result Information</a></span></dt><dt><span class="sect2"><a href="libpq-exec.html#LIBPQ-EXEC-ESCAPE-STRING">34.3.4. Escaping Strings for Inclusion in SQL Commands</a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-async.html">34.4. Asynchronous Command Processing</a></span></dt><dt><span class="sect1"><a href="libpq-pipeline-mode.html">34.5. Pipeline Mode</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-USING">34.5.1. Using Pipeline Mode</a></span></dt><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-FUNCTIONS">34.5.2. Functions Associated with Pipeline Mode</a></span></dt><dt><span class="sect2"><a href="libpq-pipeline-mode.html#LIBPQ-PIPELINE-TIPS">34.5.3. When to Use Pipeline Mode</a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-single-row-mode.html">34.6. Retrieving Query Results Row-by-Row</a></span></dt><dt><span class="sect1"><a href="libpq-cancel.html">34.7. Canceling Queries in Progress</a></span></dt><dt><span class="sect1"><a href="libpq-fastpath.html">34.8. The Fast-Path Interface</a></span></dt><dt><span class="sect1"><a href="libpq-notify.html">34.9. Asynchronous Notification</a></span></dt><dt><span class="sect1"><a href="libpq-copy.html">34.10. Functions Associated with the <code class="command">COPY</code> Command</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-SEND">34.10.1. Functions for Sending <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-RECEIVE">34.10.2. Functions for Receiving <code class="command">COPY</code> Data</a></span></dt><dt><span class="sect2"><a href="libpq-copy.html#LIBPQ-COPY-DEPRECATED">34.10.3. Obsolete Functions for <code class="command">COPY</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-control.html">34.11. Control Functions</a></span></dt><dt><span class="sect1"><a href="libpq-misc.html">34.12. Miscellaneous Functions</a></span></dt><dt><span class="sect1"><a href="libpq-notice-processing.html">34.13. Notice Processing</a></span></dt><dt><span class="sect1"><a href="libpq-events.html">34.14. Event System</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-TYPES">34.14.1. Event Types</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-PROC">34.14.2. Event Callback Procedure</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-FUNCS">34.14.3. Event Support Functions</a></span></dt><dt><span class="sect2"><a href="libpq-events.html#LIBPQ-EVENTS-EXAMPLE">34.14.4. Event Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-envars.html">34.15. Environment Variables</a></span></dt><dt><span class="sect1"><a href="libpq-pgpass.html">34.16. The Password File</a></span></dt><dt><span class="sect1"><a href="libpq-pgservice.html">34.17. The Connection Service File</a></span></dt><dt><span class="sect1"><a href="libpq-ldap.html">34.18. LDAP Lookup of Connection Parameters</a></span></dt><dt><span class="sect1"><a href="libpq-ssl.html">34.19. SSL Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="libpq-ssl.html#LIBQ-SSL-CERTIFICATES">34.19.1. Client Verification of Server Certificates</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT">34.19.2. Client Certificates</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-PROTECTION">34.19.3. Protection Provided in Different Modes</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-FILEUSAGE">34.19.4. SSL Client File Usage</a></span></dt><dt><span class="sect2"><a href="libpq-ssl.html#LIBPQ-SSL-INITIALIZE">34.19.5. SSL Library Initialization</a></span></dt></dl></dd><dt><span class="sect1"><a href="libpq-threading.html">34.20. Behavior in Threaded Programs</a></span></dt><dt><span class="sect1"><a href="libpq-build.html">34.21. Building <span class="application">libpq</span> Programs</a></span></dt><dt><span class="sect1"><a href="libpq-example.html">34.22. Example Programs</a></span></dt></dl></div><a id="id-1.7.3.2" class="indexterm"></a><a id="id-1.7.3.3" class="indexterm"></a><p>
+ <span class="application">libpq</span> is the <acronym class="acronym">C</acronym>
+ application programmer's interface to <span class="productname">PostgreSQL</span>.
+ <span class="application">libpq</span> is a set of library functions that allow
+ client programs to pass queries to the <span class="productname">PostgreSQL</span>
+ backend server and to receive the results of these queries.
+ </p><p>
+ <span class="application">libpq</span> is also the underlying engine for several
+ other <span class="productname">PostgreSQL</span> application interfaces, including
+ those written for C++, Perl, Python, Tcl and <span class="application">ECPG</span>.
+ So some aspects of <span class="application">libpq</span>'s behavior will be
+ important to you if you use one of those packages. In particular,
+ <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>,
+ <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> and
+ <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a>
+ describe behavior that is visible to the user of any application
+ that uses <span class="application">libpq</span>.
+ </p><p>
+ Some short programs are included at the end of this chapter (<a class="xref" href="libpq-example.html" title="34.22. Example Programs">Section 34.22</a>) to show how
+ to write programs that use <span class="application">libpq</span>. There are also several
+ complete examples of <span class="application">libpq</span> applications in the
+ directory <code class="filename">src/test/examples</code> in the source code distribution.
+ </p><p>
+ Client programs that use <span class="application">libpq</span> must
+ include the header file
+ <code class="filename">libpq-fe.h</code><a id="id-1.7.3.7.3" class="indexterm"></a>
+ and must link with the <span class="application">libpq</span> library.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="client-interfaces.html" title="Part IV. Client Interfaces">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-interfaces.html" title="Part IV. Client Interfaces">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part IV. Client Interfaces </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.1. Database Connection Control Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/limits.html b/doc/src/sgml/html/limits.html
new file mode 100644
index 0000000..16c4008
--- /dev/null
+++ b/doc/src/sgml/html/limits.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix K. PostgreSQL Limits</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="docguide-style.html" title="J.5. Style Guide" /><link rel="next" href="acronyms.html" title="Appendix L. Acronyms" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix K. <span class="productname">PostgreSQL</span> Limits</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="docguide-style.html" title="J.5. Style Guide">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="acronyms.html" title="Appendix L. Acronyms">Next</a></td></tr></table><hr /></div><div class="appendix" id="LIMITS"><div class="titlepage"><div><div><h2 class="title">Appendix K. <span class="productname">PostgreSQL</span> Limits</h2></div></div></div><p>
+ <a class="xref" href="limits.html#LIMITS-TABLE" title="Table K.1. PostgreSQL Limitations">Table K.1</a> describes various hard limits of
+ <span class="productname">PostgreSQL</span>. However, practical limits, such as
+ performance limitations or available disk space may apply before absolute
+ hard limits are reached.
+ </p><div class="table" id="LIMITS-TABLE"><p class="title"><strong>Table K.1. <span class="productname">PostgreSQL</span> Limitations</strong></p><div class="table-contents"><table class="table" summary="PostgreSQL Limitations" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Item</th><th>Upper Limit</th><th>Comment</th></tr></thead><tbody><tr><td>database size</td><td>unlimited</td><td> </td></tr><tr><td>number of databases</td><td>4,294,950,911</td><td> </td></tr><tr><td>relations per database</td><td>1,431,650,303</td><td> </td></tr><tr><td>relation size</td><td>32 TB</td><td>with the default <code class="symbol">BLCKSZ</code> of 8192 bytes</td></tr><tr><td>rows per table</td><td>limited by the number of tuples that can fit onto 4,294,967,295 pages</td><td> </td></tr><tr><td>columns per table</td><td>1,600</td><td>further limited by tuple size fitting on a single page; see note
+ below</td></tr><tr><td>columns in a result set</td><td>1,664</td><td> </td></tr><tr><td>field size</td><td>1 GB</td><td> </td></tr><tr><td>indexes per table</td><td>unlimited</td><td>constrained by maximum relations per database</td></tr><tr><td>columns per index</td><td>32</td><td>can be increased by recompiling <span class="productname">PostgreSQL</span></td></tr><tr><td>partition keys</td><td>32</td><td>can be increased by recompiling <span class="productname">PostgreSQL</span></td></tr><tr><td>identifier length</td><td>63 bytes</td><td>can be increased by recompiling <span class="productname">PostgreSQL</span></td></tr><tr><td>function arguments</td><td>100</td><td>can be increased by recompiling <span class="productname">PostgreSQL</span></td></tr><tr><td>query parameters</td><td>65,535</td><td> </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The maximum number of columns for a table is further reduced as the tuple
+ being stored must fit in a single 8192-byte heap page. For example,
+ excluding the tuple header, a tuple made up of 1,600 <code class="type">int</code> columns
+ would consume 6400 bytes and could be stored in a heap page, but a tuple of
+ 1,600 <code class="type">bigint</code> columns would consume 12800 bytes and would
+ therefore not fit inside a heap page.
+ Variable-length fields of
+ types such as <code class="type">text</code>, <code class="type">varchar</code>, and <code class="type">char</code>
+ can have their values stored out of line in the table's TOAST table when the
+ values are large enough to require it. Only an 18-byte pointer must remain
+ inside the tuple in the table's heap. For shorter length variable-length
+ fields, either a 4-byte or 1-byte field header is used and the value is
+ stored inside the heap tuple.
+ </p><p>
+ Columns that have been dropped from the table also contribute to the maximum
+ column limit. Moreover, although the dropped column values for newly
+ created tuples are internally marked as null in the tuple's null bitmap, the
+ null bitmap also occupies space.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docguide-style.html" title="J.5. Style Guide">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="acronyms.html" title="Appendix L. Acronyms">Next</a></td></tr><tr><td width="40%" align="left" valign="top">J.5. Style Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix L. Acronyms</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo-examplesect.html b/doc/src/sgml/html/lo-examplesect.html
new file mode 100644
index 0000000..c54b0c7
--- /dev/null
+++ b/doc/src/sgml/html/lo-examplesect.html
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>35.5. Example Program</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-funcs.html" title="35.4. Server-Side Functions" /><link rel="next" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">35.5. Example Program</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-funcs.html" title="35.4. Server-Side Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-EXAMPLESECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.5. Example Program</h2></div></div></div><p>
+ <a class="xref" href="lo-examplesect.html#LO-EXAMPLE" title="Example 35.1. Large Objects with libpq Example Program">Example 35.1</a> is a sample program which shows how the large object
+ interface
+ in <span class="application">libpq</span> can be used. Parts of the program are
+ commented out but are left in the source for the reader's
+ benefit. This program can also be found in
+ <code class="filename">src/test/examples/testlo.c</code> in the source distribution.
+</p><div class="example" id="LO-EXAMPLE"><p class="title"><strong>Example 35.1. Large Objects with <span class="application">libpq</span> Example Program</strong></p><div class="example-contents"><pre class="programlisting">
+/*-----------------------------------------------------------------
+ *
+ * testlo.c
+ * test using large objects with libpq
+ *
+ * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ * src/test/examples/testlo.c
+ *
+ *-----------------------------------------------------------------
+ */
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+
+#include &lt;sys/types.h&gt;
+#include &lt;sys/stat.h&gt;
+#include &lt;fcntl.h&gt;
+#include &lt;unistd.h&gt;
+
+#include "libpq-fe.h"
+#include "libpq/libpq-fs.h"
+
+#define BUFSIZE 1024
+
+/*
+ * importFile -
+ * import file "in_filename" into database as large object "lobjOid"
+ *
+ */
+static Oid
+importFile(PGconn *conn, char *filename)
+{
+ Oid lobjId;
+ int lobj_fd;
+ char buf[BUFSIZE];
+ int nbytes,
+ tmp;
+ int fd;
+
+ /*
+ * open the file to be read in
+ */
+ fd = open(filename, O_RDONLY, 0666);
+ if (fd &lt; 0)
+ { /* error */
+ fprintf(stderr, "cannot open unix file\"%s\"\n", filename);
+ }
+
+ /*
+ * create the large object
+ */
+ lobjId = lo_creat(conn, INV_READ | INV_WRITE);
+ if (lobjId == 0)
+ fprintf(stderr, "cannot create large object");
+
+ lobj_fd = lo_open(conn, lobjId, INV_WRITE);
+
+ /*
+ * read in from the Unix file and write to the inversion file
+ */
+ while ((nbytes = read(fd, buf, BUFSIZE)) &gt; 0)
+ {
+ tmp = lo_write(conn, lobj_fd, buf, nbytes);
+ if (tmp &lt; nbytes)
+ fprintf(stderr, "error while reading \"%s\"", filename);
+ }
+
+ close(fd);
+ lo_close(conn, lobj_fd);
+
+ return lobjId;
+}
+
+static void
+pickout(PGconn *conn, Oid lobjId, int start, int len)
+{
+ int lobj_fd;
+ char *buf;
+ int nbytes;
+ int nread;
+
+ lobj_fd = lo_open(conn, lobjId, INV_READ);
+ if (lobj_fd &lt; 0)
+ fprintf(stderr, "cannot open large object %u", lobjId);
+
+ lo_lseek(conn, lobj_fd, start, SEEK_SET);
+ buf = malloc(len + 1);
+
+ nread = 0;
+ while (len - nread &gt; 0)
+ {
+ nbytes = lo_read(conn, lobj_fd, buf, len - nread);
+ buf[nbytes] = '\0';
+ fprintf(stderr, "&gt;&gt;&gt; %s", buf);
+ nread += nbytes;
+ if (nbytes &lt;= 0)
+ break; /* no more data? */
+ }
+ free(buf);
+ fprintf(stderr, "\n");
+ lo_close(conn, lobj_fd);
+}
+
+static void
+overwrite(PGconn *conn, Oid lobjId, int start, int len)
+{
+ int lobj_fd;
+ char *buf;
+ int nbytes;
+ int nwritten;
+ int i;
+
+ lobj_fd = lo_open(conn, lobjId, INV_WRITE);
+ if (lobj_fd &lt; 0)
+ fprintf(stderr, "cannot open large object %u", lobjId);
+
+ lo_lseek(conn, lobj_fd, start, SEEK_SET);
+ buf = malloc(len + 1);
+
+ for (i = 0; i &lt; len; i++)
+ buf[i] = 'X';
+ buf[i] = '\0';
+
+ nwritten = 0;
+ while (len - nwritten &gt; 0)
+ {
+ nbytes = lo_write(conn, lobj_fd, buf + nwritten, len - nwritten);
+ nwritten += nbytes;
+ if (nbytes &lt;= 0)
+ {
+ fprintf(stderr, "\nWRITE FAILED!\n");
+ break;
+ }
+ }
+ free(buf);
+ fprintf(stderr, "\n");
+ lo_close(conn, lobj_fd);
+}
+
+
+/*
+ * exportFile -
+ * export large object "lobjOid" to file "out_filename"
+ *
+ */
+static void
+exportFile(PGconn *conn, Oid lobjId, char *filename)
+{
+ int lobj_fd;
+ char buf[BUFSIZE];
+ int nbytes,
+ tmp;
+ int fd;
+
+ /*
+ * open the large object
+ */
+ lobj_fd = lo_open(conn, lobjId, INV_READ);
+ if (lobj_fd &lt; 0)
+ fprintf(stderr, "cannot open large object %u", lobjId);
+
+ /*
+ * open the file to be written to
+ */
+ fd = open(filename, O_CREAT | O_WRONLY | O_TRUNC, 0666);
+ if (fd &lt; 0)
+ { /* error */
+ fprintf(stderr, "cannot open unix file\"%s\"",
+ filename);
+ }
+
+ /*
+ * read in from the inversion file and write to the Unix file
+ */
+ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) &gt; 0)
+ {
+ tmp = write(fd, buf, nbytes);
+ if (tmp &lt; nbytes)
+ {
+ fprintf(stderr, "error while writing \"%s\"",
+ filename);
+ }
+ }
+
+ lo_close(conn, lobj_fd);
+ close(fd);
+}
+
+static void
+exit_nicely(PGconn *conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+int
+main(int argc, char **argv)
+{
+ char *in_filename,
+ *out_filename;
+ char *database;
+ Oid lobjOid;
+ PGconn *conn;
+ PGresult *res;
+
+ if (argc != 4)
+ {
+ fprintf(stderr, "Usage: %s database_name in_filename out_filename\n",
+ argv[0]);
+ exit(1);
+ }
+
+ database = argv[1];
+ in_filename = argv[2];
+ out_filename = argv[3];
+
+ /*
+ * set up the connection
+ */
+ conn = PQsetdb(NULL, NULL, NULL, NULL, database);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "%s", PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* Set always-secure search path, so malicious users can't take control. */
+ res = PQexec(conn,
+ "SELECT pg_catalog.set_config('search_path', '', false)");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SET failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ res = PQexec(conn, "begin");
+ PQclear(res);
+ printf("importing file \"%s\" ...\n", in_filename);
+/* lobjOid = importFile(conn, in_filename); */
+ lobjOid = lo_import(conn, in_filename);
+ if (lobjOid == 0)
+ fprintf(stderr, "%s\n", PQerrorMessage(conn));
+ else
+ {
+ printf("\tas large object %u.\n", lobjOid);
+
+ printf("picking out bytes 1000-2000 of the large object\n");
+ pickout(conn, lobjOid, 1000, 1000);
+
+ printf("overwriting bytes 1000-2000 of the large object with X's\n");
+ overwrite(conn, lobjOid, 1000, 1000);
+
+ printf("exporting large object to file \"%s\" ...\n", out_filename);
+/* exportFile(conn, lobjOid, out_filename); */
+ if (lo_export(conn, lobjOid, out_filename) &lt; 0)
+ fprintf(stderr, "%s\n", PQerrorMessage(conn));
+ }
+
+ res = PQexec(conn, "end");
+ PQclear(res);
+ PQfinish(conn);
+ return 0;
+}
+
+</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-funcs.html" title="35.4. Server-Side Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.4. Server-Side Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 36. <span class="application">ECPG</span> — Embedded <acronym class="acronym">SQL</acronym> in C</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo-funcs.html b/doc/src/sgml/html/lo-funcs.html
new file mode 100644
index 0000000..0f4ce2b
--- /dev/null
+++ b/doc/src/sgml/html/lo-funcs.html
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>35.4. Server-Side Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-interfaces.html" title="35.3. Client Interfaces" /><link rel="next" href="lo-examplesect.html" title="35.5. Example Program" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">35.4. Server-Side Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-interfaces.html" title="35.3. Client Interfaces">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-examplesect.html" title="35.5. Example Program">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.4. Server-Side Functions</h2></div></div></div><p>
+ Server-side functions tailored for manipulating large objects from SQL are
+ listed in <a class="xref" href="lo-funcs.html#LO-FUNCS-TABLE" title="Table 35.1. SQL-Oriented Large Object Functions">Table 35.1</a>.
+ </p><div class="table" id="LO-FUNCS-TABLE"><p class="title"><strong>Table 35.1. SQL-Oriented Large Object Functions</strong></p><div class="table-contents"><table class="table" summary="SQL-Oriented Large Object Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.7.4.9.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">lo_from_bytea</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code>, <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Creates a large object and stores <em class="parameter"><code>data</code></em> in it.
+ If <em class="parameter"><code>loid</code></em> is zero then the system will choose a
+ free OID, otherwise that OID is used (with an error if some large
+ object already has that OID). On success, the large object's OID is
+ returned.
+ </p>
+ <p>
+ <code class="literal">lo_from_bytea(0, '\xffffff00')</code>
+ → <code class="returnvalue">24528</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.7.4.9.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">lo_put</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code>, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Writes <em class="parameter"><code>data</code></em> starting at the given offset within
+ the large object; the large object is enlarged if necessary.
+ </p>
+ <p>
+ <code class="literal">lo_put(24528, 1, '\xaa')</code>
+ → <code class="returnvalue"></code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.7.4.9.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">lo_get</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">integer</code> </span>] )
+ → <code class="returnvalue">bytea</code>
+ </p>
+ <p>
+ Extracts the large object's contents, or a substring thereof.
+ </p>
+ <p>
+ <code class="literal">lo_get(24528, 0, 3)</code>
+ → <code class="returnvalue">\xffaaff</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ There are additional server-side functions corresponding to each of the
+ client-side functions described earlier; indeed, for the most part the
+ client-side functions are simply interfaces to the equivalent server-side
+ functions. The ones just as convenient to call via SQL commands are
+ <code class="function">lo_creat</code><a id="id-1.7.4.9.4.2" class="indexterm"></a>,
+ <code class="function">lo_create</code>,
+ <code class="function">lo_unlink</code><a id="id-1.7.4.9.4.5" class="indexterm"></a>,
+ <code class="function">lo_import</code><a id="id-1.7.4.9.4.7" class="indexterm"></a>, and
+ <code class="function">lo_export</code><a id="id-1.7.4.9.4.9" class="indexterm"></a>.
+ Here are examples of their use:
+
+</p><pre class="programlisting">
+CREATE TABLE image (
+ name text,
+ raster oid
+);
+
+SELECT lo_creat(-1); -- returns OID of new, empty large object
+
+SELECT lo_create(43213); -- attempts to create large object with OID 43213
+
+SELECT lo_unlink(173454); -- deletes large object with OID 173454
+
+INSERT INTO image (name, raster)
+ VALUES ('beautiful image', lo_import('/etc/motd'));
+
+INSERT INTO image (name, raster) -- same as above, but specify OID to use
+ VALUES ('beautiful image', lo_import('/etc/motd', 68583));
+
+SELECT lo_export(image.raster, '/tmp/motd') FROM image
+ WHERE name = 'beautiful image';
+</pre><p>
+ </p><p>
+ The server-side <code class="function">lo_import</code> and
+ <code class="function">lo_export</code> functions behave considerably differently
+ from their client-side analogs. These two functions read and write files
+ in the server's file system, using the permissions of the database's
+ owning user. Therefore, by default their use is restricted to superusers.
+ In contrast, the client-side import and export functions read and write
+ files in the client's file system, using the permissions of the client
+ program. The client-side functions do not require any database
+ privileges, except the privilege to read or write the large object in
+ question.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is possible to <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> use of the
+ server-side <code class="function">lo_import</code>
+ and <code class="function">lo_export</code> functions to non-superusers, but
+ careful consideration of the security implications is required. A
+ malicious user of such privileges could easily parlay them into becoming
+ superuser (for example by rewriting server configuration files), or could
+ attack the rest of the server's file system without bothering to obtain
+ database superuser privileges as such. <span class="emphasis"><em>Access to roles having
+ such privilege must therefore be guarded just as carefully as access to
+ superuser roles.</em></span> Nonetheless, if use of
+ server-side <code class="function">lo_import</code>
+ or <code class="function">lo_export</code> is needed for some routine task, it's
+ safer to use a role with such privileges than one with full superuser
+ privileges, as that helps to reduce the risk of damage from accidental
+ errors.
+ </p></div><p>
+ The functionality of <code class="function">lo_read</code> and
+ <code class="function">lo_write</code> is also available via server-side calls,
+ but the names of the server-side functions differ from the client side
+ interfaces in that they do not contain underscores. You must call
+ these functions as <code class="function">loread</code> and <code class="function">lowrite</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-interfaces.html" title="35.3. Client Interfaces">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-examplesect.html" title="35.5. Example Program">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.3. Client Interfaces </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.5. Example Program</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo-implementation.html b/doc/src/sgml/html/lo-implementation.html
new file mode 100644
index 0000000..32a942e
--- /dev/null
+++ b/doc/src/sgml/html/lo-implementation.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>35.2. Implementation Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-intro.html" title="35.1. Introduction" /><link rel="next" href="lo-interfaces.html" title="35.3. Client Interfaces" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">35.2. Implementation Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-intro.html" title="35.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-interfaces.html" title="35.3. Client Interfaces">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.2. Implementation Features</h2></div></div></div><p>
+ The large object implementation breaks large
+ objects up into <span class="quote">“<span class="quote">chunks</span>”</span> and stores the chunks in
+ rows in the database. A B-tree index guarantees fast
+ searches for the correct chunk number when doing random
+ access reads and writes.
+ </p><p>
+ The chunks stored for a large object do not have to be contiguous.
+ For example, if an application opens a new large object, seeks to offset
+ 1000000, and writes a few bytes there, this does not result in allocation
+ of 1000000 bytes worth of storage; only of chunks covering the range of
+ data bytes actually written. A read operation will, however, read out
+ zeroes for any unallocated locations preceding the last existing chunk.
+ This corresponds to the common behavior of <span class="quote">“<span class="quote">sparsely allocated</span>”</span>
+ files in <acronym class="acronym">Unix</acronym> file systems.
+ </p><p>
+ As of <span class="productname">PostgreSQL</span> 9.0, large objects have an owner
+ and a set of access permissions, which can be managed using
+ <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> and
+ <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>.
+ <code class="literal">SELECT</code> privileges are required to read a large
+ object, and
+ <code class="literal">UPDATE</code> privileges are required to write or
+ truncate it.
+ Only the large object's owner (or a database superuser) can delete,
+ comment on, or change the owner of a large object.
+ To adjust this behavior for compatibility with prior releases, see the
+ <a class="xref" href="runtime-config-compatible.html#GUC-LO-COMPAT-PRIVILEGES">lo_compat_privileges</a> run-time parameter.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-intro.html" title="35.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-interfaces.html" title="35.3. Client Interfaces">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.3. Client Interfaces</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo-interfaces.html b/doc/src/sgml/html/lo-interfaces.html
new file mode 100644
index 0000000..b67c23c
--- /dev/null
+++ b/doc/src/sgml/html/lo-interfaces.html
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>35.3. Client Interfaces</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-implementation.html" title="35.2. Implementation Features" /><link rel="next" href="lo-funcs.html" title="35.4. Server-Side Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">35.3. Client Interfaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-implementation.html" title="35.2. Implementation Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-funcs.html" title="35.4. Server-Side Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-INTERFACES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.3. Client Interfaces</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="lo-interfaces.html#LO-CREATE">35.3.1. Creating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-IMPORT">35.3.2. Importing a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-EXPORT">35.3.3. Exporting a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-OPEN">35.3.4. Opening an Existing Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-WRITE">35.3.5. Writing Data to a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-READ">35.3.6. Reading Data from a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-SEEK">35.3.7. Seeking in a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TELL">35.3.8. Obtaining the Seek Position of a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TRUNCATE">35.3.9. Truncating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-CLOSE">35.3.10. Closing a Large Object Descriptor</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-UNLINK">35.3.11. Removing a Large Object</a></span></dt></dl></div><p>
+ This section describes the facilities that
+ <span class="productname">PostgreSQL</span>'s <span class="application">libpq</span>
+ client interface library provides for accessing large objects.
+ The <span class="productname">PostgreSQL</span> large object interface is
+ modeled after the <acronym class="acronym">Unix</acronym> file-system interface, with
+ analogues of <code class="function">open</code>, <code class="function">read</code>,
+ <code class="function">write</code>,
+ <code class="function">lseek</code>, etc.
+ </p><p>
+ All large object manipulation using these functions
+ <span class="emphasis"><em>must</em></span> take place within an SQL transaction block,
+ since large object file descriptors are only valid for the duration of
+ a transaction.
+ </p><p>
+ If an error occurs while executing any one of these functions, the
+ function will return an otherwise-impossible value, typically 0 or -1.
+ A message describing the error is stored in the connection object and
+ can be retrieved with <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a>.
+ </p><p>
+ Client applications that use these functions should include the header file
+ <code class="filename">libpq/libpq-fs.h</code> and link with the
+ <span class="application">libpq</span> library.
+ </p><p>
+ Client applications cannot use these functions while a libpq connection is in pipeline mode.
+ </p><div class="sect2" id="LO-CREATE"><div class="titlepage"><div><div><h3 class="title">35.3.1. Creating a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.7.2.1" class="indexterm"></a>
+ The function
+</p><pre class="synopsis">
+Oid lo_create(PGconn *conn, Oid lobjId);
+</pre><p>
+ creates a new large object. The OID to be assigned can be
+ specified by <em class="replaceable"><code>lobjId</code></em>;
+ if so, failure occurs if that OID is already in use for some large
+ object. If <em class="replaceable"><code>lobjId</code></em>
+ is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_create</code>
+ assigns an unused OID.
+ The return value is the OID that was assigned to the new large object,
+ or <code class="symbol">InvalidOid</code> (zero) on failure.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+inv_oid = lo_create(conn, desired_oid);
+</pre><p>
+ </p><p>
+ <a id="id-1.7.4.8.7.4.1" class="indexterm"></a>
+ The older function
+</p><pre class="synopsis">
+Oid lo_creat(PGconn *conn, int mode);
+</pre><p>
+ also creates a new large object, always assigning an unused OID.
+ The return value is the OID that was assigned to the new large object,
+ or <code class="symbol">InvalidOid</code> (zero) on failure.
+ </p><p>
+ In <span class="productname">PostgreSQL</span> releases 8.1 and later,
+ the <em class="replaceable"><code>mode</code></em> is ignored,
+ so that <code class="function">lo_creat</code> is exactly equivalent to
+ <code class="function">lo_create</code> with a zero second argument.
+ However, there is little reason to use <code class="function">lo_creat</code>
+ unless you need to work with servers older than 8.1.
+ To work with such an old server, you must
+ use <code class="function">lo_creat</code> not <code class="function">lo_create</code>,
+ and you must set <em class="replaceable"><code>mode</code></em> to
+ one of <code class="symbol">INV_READ</code>, <code class="symbol">INV_WRITE</code>,
+ or <code class="symbol">INV_READ</code> <code class="literal">|</code> <code class="symbol">INV_WRITE</code>.
+ (These symbolic constants are defined
+ in the header file <code class="filename">libpq/libpq-fs.h</code>.)
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
+</pre><p>
+ </p></div><div class="sect2" id="LO-IMPORT"><div class="titlepage"><div><div><h3 class="title">35.3.2. Importing a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.8.2.1" class="indexterm"></a>
+ To import an operating system file as a large object, call
+</p><pre class="synopsis">
+Oid lo_import(PGconn *conn, const char *filename);
+</pre><p>
+ <em class="replaceable"><code>filename</code></em>
+ specifies the operating system name of
+ the file to be imported as a large object.
+ The return value is the OID that was assigned to the new large object,
+ or <code class="symbol">InvalidOid</code> (zero) on failure.
+ Note that the file is read by the client interface library, not by
+ the server; so it must exist in the client file system and be readable
+ by the client application.
+ </p><p>
+ <a id="id-1.7.4.8.8.3.1" class="indexterm"></a>
+ The function
+</p><pre class="synopsis">
+Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
+</pre><p>
+ also imports a new large object. The OID to be assigned can be
+ specified by <em class="replaceable"><code>lobjId</code></em>;
+ if so, failure occurs if that OID is already in use for some large
+ object. If <em class="replaceable"><code>lobjId</code></em>
+ is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_import_with_oid</code> assigns an unused
+ OID (this is the same behavior as <code class="function">lo_import</code>).
+ The return value is the OID that was assigned to the new large object,
+ or <code class="symbol">InvalidOid</code> (zero) on failure.
+ </p><p>
+ <code class="function">lo_import_with_oid</code> is new as of <span class="productname">PostgreSQL</span>
+ 8.4 and uses <code class="function">lo_create</code> internally which is new in 8.1; if this function is run against 8.0 or before, it will
+ fail and return <code class="symbol">InvalidOid</code>.
+ </p></div><div class="sect2" id="LO-EXPORT"><div class="titlepage"><div><div><h3 class="title">35.3.3. Exporting a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.9.2.1" class="indexterm"></a>
+ To export a large object
+ into an operating system file, call
+</p><pre class="synopsis">
+int lo_export(PGconn *conn, Oid lobjId, const char *filename);
+</pre><p>
+ The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large
+ object to export and the <em class="parameter"><code>filename</code></em> argument
+ specifies the operating system name of the file. Note that the file is
+ written by the client interface library, not by the server. Returns 1
+ on success, -1 on failure.
+ </p></div><div class="sect2" id="LO-OPEN"><div class="titlepage"><div><div><h3 class="title">35.3.4. Opening an Existing Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.10.2.1" class="indexterm"></a>
+ To open an existing large object for reading or writing, call
+</p><pre class="synopsis">
+int lo_open(PGconn *conn, Oid lobjId, int mode);
+</pre><p>
+ The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large
+ object to open. The <em class="parameter"><code>mode</code></em> bits control whether the
+ object is opened for reading (<code class="symbol">INV_READ</code>), writing
+ (<code class="symbol">INV_WRITE</code>), or both.
+ (These symbolic constants are defined
+ in the header file <code class="filename">libpq/libpq-fs.h</code>.)
+ <code class="function">lo_open</code> returns a (non-negative) large object
+ descriptor for later use in <code class="function">lo_read</code>,
+ <code class="function">lo_write</code>, <code class="function">lo_lseek</code>,
+ <code class="function">lo_lseek64</code>, <code class="function">lo_tell</code>,
+ <code class="function">lo_tell64</code>, <code class="function">lo_truncate</code>,
+ <code class="function">lo_truncate64</code>, and <code class="function">lo_close</code>.
+ The descriptor is only valid for
+ the duration of the current transaction.
+ On failure, -1 is returned.
+ </p><p>
+ The server currently does not distinguish between modes
+ <code class="symbol">INV_WRITE</code> and <code class="symbol">INV_READ</code> <code class="literal">|</code>
+ <code class="symbol">INV_WRITE</code>: you are allowed to read from the descriptor
+ in either case. However there is a significant difference between
+ these modes and <code class="symbol">INV_READ</code> alone: with <code class="symbol">INV_READ</code>
+ you cannot write on the descriptor, and the data read from it will
+ reflect the contents of the large object at the time of the transaction
+ snapshot that was active when <code class="function">lo_open</code> was executed,
+ regardless of later writes by this or other transactions. Reading
+ from a descriptor opened with <code class="symbol">INV_WRITE</code> returns
+ data that reflects all writes of other committed transactions as well
+ as writes of the current transaction. This is similar to the behavior
+ of <code class="literal">REPEATABLE READ</code> versus <code class="literal">READ COMMITTED</code> transaction
+ modes for ordinary SQL <code class="command">SELECT</code> commands.
+ </p><p>
+ <code class="function">lo_open</code> will fail if <code class="literal">SELECT</code>
+ privilege is not available for the large object, or
+ if <code class="symbol">INV_WRITE</code> is specified and <code class="literal">UPDATE</code>
+ privilege is not available.
+ (Prior to <span class="productname">PostgreSQL</span> 11, these privilege
+ checks were instead performed at the first actual read or write call
+ using the descriptor.)
+ These privilege checks can be disabled with the
+ <a class="xref" href="runtime-config-compatible.html#GUC-LO-COMPAT-PRIVILEGES">lo_compat_privileges</a> run-time parameter.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
+</pre><p>
+ </p></div><div class="sect2" id="LO-WRITE"><div class="titlepage"><div><div><h3 class="title">35.3.5. Writing Data to a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.11.2.1" class="indexterm"></a>
+ The function
+</p><pre class="synopsis">
+int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
+</pre><p>
+ writes <em class="parameter"><code>len</code></em> bytes from <em class="parameter"><code>buf</code></em>
+ (which must be of size <em class="parameter"><code>len</code></em>) to large object
+ descriptor <em class="parameter"><code>fd</code></em>. The <em class="parameter"><code>fd</code></em> argument must
+ have been returned by a previous <code class="function">lo_open</code>. The
+ number of bytes actually written is returned (in the current
+ implementation, this will always equal <em class="parameter"><code>len</code></em> unless
+ there is an error). In the event of an error, the return value is -1.
+</p><p>
+ Although the <em class="parameter"><code>len</code></em> parameter is declared as
+ <code class="type">size_t</code>, this function will reject length values larger than
+ <code class="literal">INT_MAX</code>. In practice, it's best to transfer data in chunks
+ of at most a few megabytes anyway.
+</p></div><div class="sect2" id="LO-READ"><div class="titlepage"><div><div><h3 class="title">35.3.6. Reading Data from a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.12.2.1" class="indexterm"></a>
+ The function
+</p><pre class="synopsis">
+int lo_read(PGconn *conn, int fd, char *buf, size_t len);
+</pre><p>
+ reads up to <em class="parameter"><code>len</code></em> bytes from large object descriptor
+ <em class="parameter"><code>fd</code></em> into <em class="parameter"><code>buf</code></em> (which must be
+ of size <em class="parameter"><code>len</code></em>). The <em class="parameter"><code>fd</code></em>
+ argument must have been returned by a previous
+ <code class="function">lo_open</code>. The number of bytes actually read is
+ returned; this will be less than <em class="parameter"><code>len</code></em> if the end of
+ the large object is reached first. In the event of an error, the return
+ value is -1.
+</p><p>
+ Although the <em class="parameter"><code>len</code></em> parameter is declared as
+ <code class="type">size_t</code>, this function will reject length values larger than
+ <code class="literal">INT_MAX</code>. In practice, it's best to transfer data in chunks
+ of at most a few megabytes anyway.
+</p></div><div class="sect2" id="LO-SEEK"><div class="titlepage"><div><div><h3 class="title">35.3.7. Seeking in a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.13.2.1" class="indexterm"></a>
+ To change the current read or write location associated with a
+ large object descriptor, call
+</p><pre class="synopsis">
+int lo_lseek(PGconn *conn, int fd, int offset, int whence);
+</pre><p>
+ This function moves the
+ current location pointer for the large object descriptor identified by
+ <em class="parameter"><code>fd</code></em> to the new location specified by
+ <em class="parameter"><code>offset</code></em>. The valid values for <em class="parameter"><code>whence</code></em>
+ are <code class="symbol">SEEK_SET</code> (seek from object start),
+ <code class="symbol">SEEK_CUR</code> (seek from current position), and
+ <code class="symbol">SEEK_END</code> (seek from object end). The return value is
+ the new location pointer, or -1 on error.
+</p><p>
+ <a id="id-1.7.4.8.13.3.1" class="indexterm"></a>
+ When dealing with large objects that might exceed 2GB in size,
+ instead use
+</p><pre class="synopsis">
+pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence);
+</pre><p>
+ This function has the same behavior
+ as <code class="function">lo_lseek</code>, but it can accept an
+ <em class="parameter"><code>offset</code></em> larger than 2GB and/or deliver a result larger
+ than 2GB.
+ Note that <code class="function">lo_lseek</code> will fail if the new location
+ pointer would be greater than 2GB.
+</p><p>
+ <code class="function">lo_lseek64</code> is new as of <span class="productname">PostgreSQL</span>
+ 9.3. If this function is run against an older server version, it will
+ fail and return -1.
+</p></div><div class="sect2" id="LO-TELL"><div class="titlepage"><div><div><h3 class="title">35.3.8. Obtaining the Seek Position of a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.14.2.1" class="indexterm"></a>
+ To obtain the current read or write location of a large object descriptor,
+ call
+</p><pre class="synopsis">
+int lo_tell(PGconn *conn, int fd);
+</pre><p>
+ If there is an error, the return value is -1.
+</p><p>
+ <a id="id-1.7.4.8.14.3.1" class="indexterm"></a>
+ When dealing with large objects that might exceed 2GB in size,
+ instead use
+</p><pre class="synopsis">
+pg_int64 lo_tell64(PGconn *conn, int fd);
+</pre><p>
+ This function has the same behavior
+ as <code class="function">lo_tell</code>, but it can deliver a result larger
+ than 2GB.
+ Note that <code class="function">lo_tell</code> will fail if the current
+ read/write location is greater than 2GB.
+</p><p>
+ <code class="function">lo_tell64</code> is new as of <span class="productname">PostgreSQL</span>
+ 9.3. If this function is run against an older server version, it will
+ fail and return -1.
+</p></div><div class="sect2" id="LO-TRUNCATE"><div class="titlepage"><div><div><h3 class="title">35.3.9. Truncating a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.15.2.1" class="indexterm"></a>
+ To truncate a large object to a given length, call
+</p><pre class="synopsis">
+int lo_truncate(PGconn *conn, int fd, size_t len);
+</pre><p>
+ This function truncates the large object
+ descriptor <em class="parameter"><code>fd</code></em> to length <em class="parameter"><code>len</code></em>. The
+ <em class="parameter"><code>fd</code></em> argument must have been returned by a
+ previous <code class="function">lo_open</code>. If <em class="parameter"><code>len</code></em> is
+ greater than the large object's current length, the large object
+ is extended to the specified length with null bytes ('\0').
+ On success, <code class="function">lo_truncate</code> returns
+ zero. On error, the return value is -1.
+</p><p>
+ The read/write location associated with the descriptor
+ <em class="parameter"><code>fd</code></em> is not changed.
+</p><p>
+ Although the <em class="parameter"><code>len</code></em> parameter is declared as
+ <code class="type">size_t</code>, <code class="function">lo_truncate</code> will reject length
+ values larger than <code class="literal">INT_MAX</code>.
+</p><p>
+ <a id="id-1.7.4.8.15.5.1" class="indexterm"></a>
+ When dealing with large objects that might exceed 2GB in size,
+ instead use
+</p><pre class="synopsis">
+int lo_truncate64(PGconn *conn, int fd, pg_int64 len);
+</pre><p>
+ This function has the same
+ behavior as <code class="function">lo_truncate</code>, but it can accept a
+ <em class="parameter"><code>len</code></em> value exceeding 2GB.
+</p><p>
+ <code class="function">lo_truncate</code> is new as of <span class="productname">PostgreSQL</span>
+ 8.3; if this function is run against an older server version, it will
+ fail and return -1.
+</p><p>
+ <code class="function">lo_truncate64</code> is new as of <span class="productname">PostgreSQL</span>
+ 9.3; if this function is run against an older server version, it will
+ fail and return -1.
+</p></div><div class="sect2" id="LO-CLOSE"><div class="titlepage"><div><div><h3 class="title">35.3.10. Closing a Large Object Descriptor</h3></div></div></div><p>
+ <a id="id-1.7.4.8.16.2.1" class="indexterm"></a>
+ A large object descriptor can be closed by calling
+</p><pre class="synopsis">
+int lo_close(PGconn *conn, int fd);
+</pre><p>
+ where <em class="parameter"><code>fd</code></em> is a
+ large object descriptor returned by <code class="function">lo_open</code>.
+ On success, <code class="function">lo_close</code> returns zero. On
+ error, the return value is -1.
+</p><p>
+ Any large object descriptors that remain open at the end of a
+ transaction will be closed automatically.
+</p></div><div class="sect2" id="LO-UNLINK"><div class="titlepage"><div><div><h3 class="title">35.3.11. Removing a Large Object</h3></div></div></div><p>
+ <a id="id-1.7.4.8.17.2.1" class="indexterm"></a>
+ To remove a large object from the database, call
+</p><pre class="synopsis">
+int lo_unlink(PGconn *conn, Oid lobjId);
+</pre><p>
+ The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the
+ large object to remove. Returns 1 if successful, -1 on failure.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-implementation.html" title="35.2. Implementation Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-funcs.html" title="35.4. Server-Side Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.2. Implementation Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.4. Server-Side Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo-intro.html b/doc/src/sgml/html/lo-intro.html
new file mode 100644
index 0000000..0dd81f4
--- /dev/null
+++ b/doc/src/sgml/html/lo-intro.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>35.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="largeobjects.html" title="Chapter 35. Large Objects" /><link rel="next" href="lo-implementation.html" title="35.2. Implementation Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">35.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="largeobjects.html" title="Chapter 35. Large Objects">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-implementation.html" title="35.2. Implementation Features">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.1. Introduction</h2></div></div></div><a id="id-1.7.4.6.2" class="indexterm"></a><p>
+ All large objects are stored in a single system table named <a class="link" href="catalog-pg-largeobject.html" title="53.30. pg_largeobject"><code class="structname">pg_largeobject</code></a>.
+ Each large object also has an entry in the system table <a class="link" href="catalog-pg-largeobject-metadata.html" title="53.31. pg_largeobject_metadata"><code class="structname">pg_largeobject_metadata</code></a>.
+ Large objects can be created, modified, and deleted using a read/write API
+ that is similar to standard operations on files.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also supports a storage system called
+ <a class="link" href="storage-toast.html" title="73.2. TOAST"><span class="quote">“<span class="quote"><acronym class="acronym">TOAST</acronym></span>”</span></a>,
+ which automatically stores values
+ larger than a single database page into a secondary storage area per table.
+ This makes the large object facility partially obsolete. One
+ remaining advantage of the large object facility is that it allows values
+ up to 4 TB in size, whereas <acronym class="acronym">TOAST</acronym>ed fields can be at
+ most 1 GB. Also, reading and updating portions of a large object can be
+ done efficiently, while most operations on a <acronym class="acronym">TOAST</acronym>ed
+ field will read or write the whole value as a unit.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="largeobjects.html" title="Chapter 35. Large Objects">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-implementation.html" title="35.2. Implementation Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 35. Large Objects </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.2. Implementation Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/lo.html b/doc/src/sgml/html/lo.html
new file mode 100644
index 0000000..5fa432e
--- /dev/null
+++ b/doc/src/sgml/html/lo.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.22. lo</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="isn.html" title="F.21. isn" /><link rel="next" href="ltree.html" title="F.23. ltree" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.22. lo</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="isn.html" title="F.21. isn">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ltree.html" title="F.23. ltree">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.22. lo</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.5">F.22.1. Rationale</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.6">F.22.2. How to Use It</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.7">F.22.3. Limitations</a></span></dt><dt><span class="sect2"><a href="lo.html#id-1.11.7.31.8">F.22.4. Author</a></span></dt></dl></div><a id="id-1.11.7.31.2" class="indexterm"></a><p>
+ The <code class="filename">lo</code> module provides support for managing Large Objects
+ (also called LOs or BLOBs). This includes a data type <code class="type">lo</code>
+ and a trigger <code class="function">lo_manage</code>.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.31.5"><div class="titlepage"><div><div><h3 class="title">F.22.1. Rationale</h3></div></div></div><p>
+ One of the problems with the JDBC driver (and this affects the ODBC driver
+ also), is that the specification assumes that references to BLOBs (Binary
+ Large OBjects) are stored within a table, and if that entry is changed, the
+ associated BLOB is deleted from the database.
+ </p><p>
+ As <span class="productname">PostgreSQL</span> stands, this doesn't occur. Large objects
+ are treated as objects in their own right; a table entry can reference a
+ large object by OID, but there can be multiple table entries referencing
+ the same large object OID, so the system doesn't delete the large object
+ just because you change or remove one such entry.
+ </p><p>
+ Now this is fine for <span class="productname">PostgreSQL</span>-specific applications, but
+ standard code using JDBC or ODBC won't delete the objects, resulting in
+ orphan objects — objects that are not referenced by anything, and
+ simply occupy disk space.
+ </p><p>
+ The <code class="filename">lo</code> module allows fixing this by attaching a trigger
+ to tables that contain LO reference columns. The trigger essentially just
+ does a <code class="function">lo_unlink</code> whenever you delete or modify a value
+ referencing a large object. When you use this trigger, you are assuming
+ that there is only one database reference to any large object that is
+ referenced in a trigger-controlled column!
+ </p><p>
+ The module also provides a data type <code class="type">lo</code>, which is really just
+ a <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain</a></em></a> over
+ the <code class="type">oid</code> type. This is useful for differentiating
+ database columns that hold large object references from those that are
+ OIDs of other things. You don't have to use the <code class="type">lo</code> type to
+ use the trigger, but it may be convenient to use it to keep track of which
+ columns in your database represent large objects that you are managing with
+ the trigger. It is also rumored that the ODBC driver gets confused if you
+ don't use <code class="type">lo</code> for BLOB columns.
+ </p></div><div class="sect2" id="id-1.11.7.31.6"><div class="titlepage"><div><div><h3 class="title">F.22.2. How to Use It</h3></div></div></div><p>
+ Here's a simple example of usage:
+ </p><pre class="programlisting">
+CREATE TABLE image (title text, raster lo);
+
+CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
+ FOR EACH ROW EXECUTE FUNCTION lo_manage(raster);
+</pre><p>
+ For each column that will contain unique references to large objects,
+ create a <code class="literal">BEFORE UPDATE OR DELETE</code> trigger, and give the column
+ name as the sole trigger argument. You can also restrict the trigger
+ to only execute on updates to the column by using <code class="literal">BEFORE UPDATE
+ OF</code> <em class="replaceable"><code>column_name</code></em>.
+ If you need multiple <code class="type">lo</code>
+ columns in the same table, create a separate trigger for each one,
+ remembering to give a different name to each trigger on the same table.
+ </p></div><div class="sect2" id="id-1.11.7.31.7"><div class="titlepage"><div><div><h3 class="title">F.22.3. Limitations</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Dropping a table will still orphan any objects it contains, as the trigger
+ is not executed. You can avoid this by preceding the <code class="command">DROP
+ TABLE</code> with <code class="command">DELETE FROM <em class="replaceable"><code>table</code></em></code>.
+ </p><p>
+ <code class="command">TRUNCATE</code> has the same hazard.
+ </p><p>
+ If you already have, or suspect you have, orphaned large objects, see the
+ <a class="xref" href="vacuumlo.html" title="vacuumlo"><span class="refentrytitle"><span class="application">vacuumlo</span></span></a> module to help
+ you clean them up. It's a good idea to run <span class="application">vacuumlo</span>
+ occasionally as a back-stop to the <code class="function">lo_manage</code> trigger.
+ </p></li><li class="listitem"><p>
+ Some frontends may create their own tables, and will not create the
+ associated trigger(s). Also, users may not remember (or know) to create
+ the triggers.
+ </p></li></ul></div></div><div class="sect2" id="id-1.11.7.31.8"><div class="titlepage"><div><div><h3 class="title">F.22.4. Author</h3></div></div></div><p>
+ Peter Mount <code class="email">&lt;<a class="email" href="mailto:peter@retep.org.uk">peter@retep.org.uk</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="isn.html" title="F.21. isn">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ltree.html" title="F.23. ltree">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.21. isn </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.23. ltree</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/locale.html b/doc/src/sgml/html/locale.html
new file mode 100644
index 0000000..f1ac763
--- /dev/null
+++ b/doc/src/sgml/html/locale.html
@@ -0,0 +1,246 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>24.1. Locale Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="charset.html" title="Chapter 24. Localization" /><link rel="next" href="collation.html" title="24.2. Collation Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">24.1. Locale Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="charset.html" title="Chapter 24. Localization">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><th width="60%" align="center">Chapter 24. Localization</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="collation.html" title="24.2. Collation Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOCALE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">24.1. Locale Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.4">24.1.1. Overview</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.5">24.1.2. Behavior</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.6">24.1.3. Selecting Locales</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.7">24.1.4. Locale Providers</a></span></dt><dt><span class="sect2"><a href="locale.html#id-1.6.11.3.8">24.1.5. Problems</a></span></dt></dl></div><a id="id-1.6.11.3.2" class="indexterm"></a><p>
+ <em class="firstterm">Locale</em> support refers to an application respecting
+ cultural preferences regarding alphabets, sorting, number
+ formatting, etc. <span class="productname">PostgreSQL</span> uses the standard ISO
+ C and <acronym class="acronym">POSIX</acronym> locale facilities provided by the server operating
+ system. For additional information refer to the documentation of your
+ system.
+ </p><div class="sect2" id="id-1.6.11.3.4"><div class="titlepage"><div><div><h3 class="title">24.1.1. Overview</h3></div></div></div><p>
+ Locale support is automatically initialized when a database
+ cluster is created using <code class="command">initdb</code>.
+ <code class="command">initdb</code> will initialize the database cluster
+ with the locale setting of its execution environment by default,
+ so if your system is already set to use the locale that you want
+ in your database cluster then there is nothing else you need to
+ do. If you want to use a different locale (or you are not sure
+ which locale your system is set to), you can instruct
+ <code class="command">initdb</code> exactly which locale to use by
+ specifying the <code class="option">--locale</code> option. For example:
+</p><pre class="screen">
+initdb --locale=sv_SE
+</pre><p>
+ </p><p>
+ This example for Unix systems sets the locale to Swedish
+ (<code class="literal">sv</code>) as spoken
+ in Sweden (<code class="literal">SE</code>). Other possibilities might include
+ <code class="literal">en_US</code> (U.S. English) and <code class="literal">fr_CA</code> (French
+ Canadian). If more than one character set can be used for a
+ locale then the specifications can take the form
+ <em class="replaceable"><code>language_territory.codeset</code></em>. For example,
+ <code class="literal">fr_BE.UTF-8</code> represents the French language (fr) as
+ spoken in Belgium (BE), with a <acronym class="acronym">UTF-8</acronym> character set
+ encoding.
+ </p><p>
+ What locales are available on your
+ system under what names depends on what was provided by the operating
+ system vendor and what was installed. On most Unix systems, the command
+ <code class="literal">locale -a</code> will provide a list of available locales.
+ Windows uses more verbose locale names, such as <code class="literal">German_Germany</code>
+ or <code class="literal">Swedish_Sweden.1252</code>, but the principles are the same.
+ </p><p>
+ Occasionally it is useful to mix rules from several locales, e.g.,
+ use English collation rules but Spanish messages. To support that, a
+ set of locale subcategories exist that control only certain
+ aspects of the localization rules:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><tbody><tr><td><code class="envar">LC_COLLATE</code></td><td>String sort order</td></tr><tr><td><code class="envar">LC_CTYPE</code></td><td>Character classification (What is a letter? Its upper-case equivalent?)</td></tr><tr><td><code class="envar">LC_MESSAGES</code></td><td>Language of messages</td></tr><tr><td><code class="envar">LC_MONETARY</code></td><td>Formatting of currency amounts</td></tr><tr><td><code class="envar">LC_NUMERIC</code></td><td>Formatting of numbers</td></tr><tr><td><code class="envar">LC_TIME</code></td><td>Formatting of dates and times</td></tr></tbody></table></div><p>
+
+ The category names translate into names of
+ <code class="command">initdb</code> options to override the locale choice
+ for a specific category. For instance, to set the locale to
+ French Canadian, but use U.S. rules for formatting currency, use
+ <code class="literal">initdb --locale=fr_CA --lc-monetary=en_US</code>.
+ </p><p>
+ If you want the system to behave as if it had no locale support,
+ use the special locale name <code class="literal">C</code>, or equivalently
+ <code class="literal">POSIX</code>.
+ </p><p>
+ Some locale categories must have their values
+ fixed when the database is created. You can use different settings
+ for different databases, but once a database is created, you cannot
+ change them for that database anymore. <code class="literal">LC_COLLATE</code>
+ and <code class="literal">LC_CTYPE</code> are these categories. They affect
+ 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 <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>.)
+ The default values for these
+ categories are determined when <code class="command">initdb</code> is run, and
+ those values are used when new databases are created, unless
+ specified otherwise in the <code class="command">CREATE DATABASE</code> command.
+ </p><p>
+ 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 <a class="xref" href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT" title="20.11.2. Locale and Formatting">Section 20.11.2</a> for details). The values
+ that are chosen by <code class="command">initdb</code> are actually only written
+ into the configuration file <code class="filename">postgresql.conf</code> to
+ serve as defaults when the server is started. If you remove these
+ assignments from <code class="filename">postgresql.conf</code> then the
+ server will inherit the settings from its execution environment.
+ </p><p>
+ Note that the locale behavior of the server is determined by the
+ environment variables seen by the server, not by the environment
+ of any client. Therefore, be careful to configure the correct locale settings
+ before starting the server. A consequence of this is that if
+ client and server are set up in different locales, messages might
+ appear in different languages depending on where they originated.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When we speak of inheriting the locale from the execution
+ environment, this means the following on most operating systems:
+ For a given locale category, say the collation, the following
+ environment variables are consulted in this order until one is
+ found to be set: <code class="envar">LC_ALL</code>, <code class="envar">LC_COLLATE</code>
+ (or the variable corresponding to the respective category),
+ <code class="envar">LANG</code>. If none of these environment variables are
+ set then the locale defaults to <code class="literal">C</code>.
+ </p><p>
+ Some message localization libraries also look at the environment
+ variable <code class="envar">LANGUAGE</code> which overrides all other locale
+ settings for the purpose of setting the language of messages. If
+ in doubt, please refer to the documentation of your operating
+ system, in particular the documentation about
+ <span class="application">gettext</span>.
+ </p></div><p>
+ To enable messages to be translated to the user's preferred language,
+ <acronym class="acronym">NLS</acronym> must have been selected at build time
+ (<code class="literal">configure --enable-nls</code>). All other locale support is
+ built in automatically.
+ </p></div><div class="sect2" id="id-1.6.11.3.5"><div class="titlepage"><div><div><h3 class="title">24.1.2. Behavior</h3></div></div></div><p>
+ The locale settings influence the following SQL features:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Sort order in queries using <code class="literal">ORDER BY</code> or the standard
+ comparison operators on textual data
+ <a id="id-1.6.11.3.5.2.1.1.1.2" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ The <code class="function">upper</code>, <code class="function">lower</code>, and <code class="function">initcap</code>
+ functions
+ <a id="id-1.6.11.3.5.2.1.2.1.4" class="indexterm"></a>
+ <a id="id-1.6.11.3.5.2.1.2.1.5" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ Pattern matching operators (<code class="literal">LIKE</code>, <code class="literal">SIMILAR TO</code>,
+ and POSIX-style regular expressions); locales affect both case
+ insensitive matching and the classification of characters by
+ character-class regular expressions
+ <a id="id-1.6.11.3.5.2.1.3.1.3" class="indexterm"></a>
+ <a id="id-1.6.11.3.5.2.1.3.1.4" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ The <code class="function">to_char</code> family of functions
+ <a id="id-1.6.11.3.5.2.1.4.1.2" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ The ability to use indexes with <code class="literal">LIKE</code> clauses
+ </p></li></ul></div><p>
+ </p><p>
+ The drawback of using locales other than <code class="literal">C</code> or
+ <code class="literal">POSIX</code> in <span class="productname">PostgreSQL</span> is its performance
+ impact. It slows character handling and prevents ordinary indexes
+ from being used by <code class="literal">LIKE</code>. For this reason use locales
+ only if you actually need them.
+ </p><p>
+ As a workaround to allow <span class="productname">PostgreSQL</span> to use indexes
+ with <code class="literal">LIKE</code> 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 <a class="xref" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Section 11.10</a>
+ for more information. Another approach is to create indexes using
+ the <code class="literal">C</code> collation, as discussed in
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>.
+ </p></div><div class="sect2" id="id-1.6.11.3.6"><div class="titlepage"><div><div><h3 class="title">24.1.3. Selecting Locales</h3></div></div></div><p>
+ Locales can be selected in different scopes depending on requirements.
+ The above overview showed how locales are specified using
+ <code class="command">initdb</code> to set the defaults for the entire cluster. The
+ following list shows where locales can be selected. Each item provides
+ the defaults for the subsequent items, and each lower item allows
+ overriding the defaults on a finer granularity.
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ As explained above, the environment of the operating system provides the
+ defaults for the locales of a newly initialized database cluster. In
+ many cases, this is enough: If the operating system is configured for
+ the desired language/territory, then
+ <span class="productname">PostgreSQL</span> will by default also behave
+ according to that locale.
+ </p></li><li class="listitem"><p>
+ As shown above, command-line options for <code class="command">initdb</code>
+ specify the locale settings for a newly initialized database cluster.
+ Use this if the operating system does not have the locale configuration
+ you want for your database system.
+ </p></li><li class="listitem"><p>
+ A locale can be selected separately for each database. The SQL command
+ <code class="command">CREATE DATABASE</code> and its command-line equivalent
+ <code class="command">createdb</code> have options for that. Use this for example
+ if a database cluster houses databases for multiple tenants with
+ different requirements.
+ </p></li><li class="listitem"><p>
+ Locale settings can be made for individual table columns. This uses an
+ SQL object called <em class="firstterm">collation</em> and is explained in
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>. Use this for example to sort data in
+ different languages or customize the sort order of a particular table.
+ </p></li><li class="listitem"><p>
+ Finally, locales can be selected for an individual query. Again, this
+ uses SQL collation objects. This could be used to change the sort order
+ based on run-time choices or for ad-hoc experimentation.
+ </p></li></ol></div></div><div class="sect2" id="id-1.6.11.3.7"><div class="titlepage"><div><div><h3 class="title">24.1.4. Locale Providers</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> supports multiple <em class="firstterm">locale
+ providers</em>. This specifies which library supplies the locale
+ data. One standard provider name is <code class="literal">libc</code>, which uses
+ the locales provided by the operating system C library. These are the
+ locales used by most tools provided by the operating system. Another
+ provider is <code class="literal">icu</code>, which uses the external
+ ICU<a id="id-1.6.11.3.7.2.5" class="indexterm"></a> library. ICU locales can
+ only be used if support for ICU was configured when PostgreSQL was built.
+ </p><p>
+ The commands and tools that select the locale settings, as described
+ above, each have an option to select the locale provider. The examples
+ shown earlier all use the <code class="literal">libc</code> provider, which is the
+ default. Here is an example to initialize a database cluster using the
+ ICU provider:
+</p><pre class="programlisting">
+initdb --locale-provider=icu --icu-locale=en
+</pre><p>
+ See the description of the respective commands and programs for
+ details. Note that you can mix locale providers at different
+ granularities, for example use <code class="literal">libc</code> by default for the
+ cluster but have one database that uses the <code class="literal">icu</code>
+ provider, and then have collation objects using either provider within
+ those databases.
+ </p><p>
+ Which locale provider to use depends on individual requirements. For most
+ basic uses, either provider will give adequate results. For the libc
+ provider, it depends on what the operating system offers; some operating
+ systems are better than others. For advanced uses, ICU offers more locale
+ variants and customization options.
+ </p></div><div class="sect2" id="id-1.6.11.3.8"><div class="titlepage"><div><div><h3 class="title">24.1.5. Problems</h3></div></div></div><p>
+ If locale support doesn't work according to the explanation above,
+ check that the locale support in your operating system is
+ correctly configured. To check what locales are installed on your
+ system, you can use the command <code class="literal">locale -a</code> if
+ your operating system provides it.
+ </p><p>
+ Check that <span class="productname">PostgreSQL</span> is actually using the locale
+ that you think it is. The <code class="envar">LC_COLLATE</code> and <code class="envar">LC_CTYPE</code>
+ settings are determined when a database is created, and cannot be
+ changed except by creating a new database. Other locale
+ settings including <code class="envar">LC_MESSAGES</code> and <code class="envar">LC_MONETARY</code>
+ are initially determined by the environment the server is started
+ in, but can be changed on-the-fly. You can check the active locale
+ settings using the <code class="command">SHOW</code> command.
+ </p><p>
+ The directory <code class="filename">src/test/locale</code> in the source
+ distribution contains a test suite for
+ <span class="productname">PostgreSQL</span>'s locale support.
+ </p><p>
+ Client applications that handle server-side errors by parsing the
+ text of the error message will obviously have problems when the
+ server's messages are in a different language. Authors of such
+ applications are advised to make use of the error code scheme
+ instead.
+ </p><p>
+ Maintaining catalogs of message translations requires the on-going
+ efforts of many volunteers that want to see
+ <span class="productname">PostgreSQL</span> 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 <a class="xref" href="nls.html" title="Chapter 57. Native Language Support">Chapter 57</a> or write to the developers'
+ mailing list.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="charset.html" title="Chapter 24. Localization">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="collation.html" title="24.2. Collation Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Localization </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 24.2. Collation Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/locking-indexes.html b/doc/src/sgml/html/locking-indexes.html
new file mode 100644
index 0000000..557db0f
--- /dev/null
+++ b/doc/src/sgml/html/locking-indexes.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.7. Locking and Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="mvcc-caveats.html" title="13.6. Caveats" /><link rel="next" href="performance-tips.html" title="Chapter 14. Performance Tips" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.7. Locking and Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="mvcc-caveats.html" title="13.6. Caveats">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="performance-tips.html" title="Chapter 14. Performance Tips">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOCKING-INDEXES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.7. Locking and Indexes</h2></div></div></div><a id="id-1.5.12.10.2" class="indexterm"></a><p>
+ Though <span class="productname">PostgreSQL</span>
+ provides nonblocking read/write access to table
+ data, nonblocking read/write access is not currently offered for every
+ index access method implemented
+ in <span class="productname">PostgreSQL</span>.
+ The various index types are handled as follows:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ B-tree, <acronym class="acronym">GiST</acronym> and <acronym class="acronym">SP-GiST</acronym> indexes
+ </span></dt><dd><p>
+ Short-term share/exclusive page-level locks are used for
+ read/write access. Locks are released immediately after each
+ index row is fetched or inserted. These index types provide
+ the highest concurrency without deadlock conditions.
+ </p></dd><dt><span class="term">
+ Hash indexes
+ </span></dt><dd><p>
+ Share/exclusive hash-bucket-level locks are used for read/write
+ access. Locks are released after the whole bucket is processed.
+ Bucket-level locks provide better concurrency than index-level
+ ones, but deadlock is possible since the locks are held longer
+ than one index operation.
+ </p></dd><dt><span class="term">
+ <acronym class="acronym">GIN</acronym> indexes
+ </span></dt><dd><p>
+ Short-term share/exclusive page-level locks are used for
+ read/write access. Locks are released immediately after each
+ index row is fetched or inserted. But note that insertion of a
+ GIN-indexed value usually produces several index key insertions
+ per row, so GIN might do substantial work for a single value's
+ insertion.
+ </p></dd></dl></div><p>
+ </p><p>
+ Currently, B-tree indexes offer the best performance for concurrent
+ applications; since they also have more features than hash
+ indexes, they are the recommended index type for concurrent
+ applications that need to index scalar data. When dealing with
+ non-scalar data, B-trees are not useful, and GiST, SP-GiST or GIN
+ indexes should be used instead.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mvcc-caveats.html" title="13.6. Caveats">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="performance-tips.html" title="Chapter 14. Performance Tips">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.6. Caveats </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. Performance Tips</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logfile-maintenance.html b/doc/src/sgml/html/logfile-maintenance.html
new file mode 100644
index 0000000..cf1d2aa
--- /dev/null
+++ b/doc/src/sgml/html/logfile-maintenance.html
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>25.3. Log File Maintenance</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="routine-reindex.html" title="25.2. Routine Reindexing" /><link rel="next" href="backup.html" title="Chapter 26. Backup and Restore" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">25.3. Log File Maintenance</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="routine-reindex.html" title="25.2. Routine Reindexing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><th width="60%" align="center">Chapter 25. Routine Database Maintenance Tasks</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup.html" title="Chapter 26. Backup and Restore">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGFILE-MAINTENANCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">25.3. Log File Maintenance</h2></div></div></div><a id="id-1.6.12.12.2" class="indexterm"></a><p>
+ It is a good idea to save the database server's log output
+ somewhere, rather than just discarding it via <code class="filename">/dev/null</code>.
+ The log output is invaluable when diagnosing
+ problems.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The server log can contain sensitive information and needs to be protected,
+ no matter how or where it is stored, or the destination to which it is routed.
+ For example, some DDL statements might contain plaintext passwords or other
+ authentication details. Logged statements at the <code class="literal">ERROR</code>
+ level might show the SQL source code for applications
+ and might also contain some parts of data rows. Recording data, events and
+ related information is the intended function of this facility, so this is
+ not a leakage or a bug. Please ensure the server logs are visible only to
+ appropriately authorized people.
+ </p></div><p>
+ Log output tends to be voluminous
+ (especially at higher debug levels) so you won't want to save it
+ indefinitely. You need to <span class="emphasis"><em>rotate</em></span> the log files so that
+ new log files are started and old ones removed after a reasonable
+ period of time.
+ </p><p>
+ If you simply direct the <span class="systemitem">stderr</span> of
+ <code class="command">postgres</code> into a
+ file, you will have log output, but
+ the only way to truncate the log file is to stop and restart
+ the server. This might be acceptable if you are using
+ <span class="productname">PostgreSQL</span> in a development environment,
+ but few production servers would find this behavior acceptable.
+ </p><p>
+ A better approach is to send the server's
+ <span class="systemitem">stderr</span> output to some type of log rotation program.
+ There is a built-in log rotation facility, which you can use by
+ setting the configuration parameter <code class="varname">logging_collector</code> to
+ <code class="literal">true</code> in <code class="filename">postgresql.conf</code>. The control
+ parameters for this program are described in <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE" title="20.8.1. Where to Log">Section 20.8.1</a>. You can also use this approach
+ to capture the log data in machine readable <acronym class="acronym">CSV</acronym>
+ (comma-separated values) format.
+ </p><p>
+ Alternatively, you might prefer to use an external log rotation
+ program if you have one that you are already using with other
+ server software. For example, the <span class="application">rotatelogs</span>
+ tool included in the <span class="productname">Apache</span> distribution
+ can be used with <span class="productname">PostgreSQL</span>. One way to
+ do this is to pipe the server's
+ <span class="systemitem">stderr</span> output to the desired program.
+ If you start the server with
+ <code class="command">pg_ctl</code>, then <span class="systemitem">stderr</span>
+ is already redirected to <span class="systemitem">stdout</span>, so you just need a
+ pipe command, for example:
+
+</p><pre class="programlisting">
+pg_ctl start | rotatelogs /var/log/pgsql_log 86400
+</pre><p>
+ </p><p>
+ You can combine these approaches by setting up <span class="application">logrotate</span>
+ to collect log files produced by <span class="productname">PostgreSQL</span> built-in
+ logging collector. In this case, the logging collector defines the names and
+ location of the log files, while <span class="application">logrotate</span>
+ periodically archives these files. When initiating log rotation,
+ <span class="application">logrotate</span> must ensure that the application
+ sends further output to the new file. This is commonly done with a
+ <code class="literal">postrotate</code> script that sends a <code class="literal">SIGHUP</code>
+ signal to the application, which then reopens the log file.
+ In <span class="productname">PostgreSQL</span>, you can run <code class="command">pg_ctl</code>
+ with the <code class="literal">logrotate</code> option instead. When the server receives
+ this command, the server either switches to a new log file or reopens the
+ existing file, depending on the logging configuration
+ (see <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE" title="20.8.1. Where to Log">Section 20.8.1</a>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When using static log file names, the server might fail to reopen the log
+ file if the max open file limit is reached or a file table overflow occurs.
+ In this case, log messages are sent to the old log file until a
+ successful log rotation. If <span class="application">logrotate</span> is
+ configured to compress the log file and delete it, the server may lose
+ the messages logged in this time frame. To avoid this issue, you can
+ configure the logging collector to dynamically assign log file names
+ and use a <code class="literal">prerotate</code> script to ignore open log files.
+ </p></div><p>
+ Another production-grade approach to managing log output is to
+ send it to <span class="application">syslog</span> and let
+ <span class="application">syslog</span> deal with file rotation. To do this, set the
+ configuration parameter <code class="varname">log_destination</code> to <code class="literal">syslog</code>
+ (to log to <span class="application">syslog</span> only) in
+ <code class="filename">postgresql.conf</code>. Then you can send a <code class="literal">SIGHUP</code>
+ signal to the <span class="application">syslog</span> daemon whenever you want to force it
+ to start writing a new log file. If you want to automate log
+ rotation, the <span class="application">logrotate</span> program can be
+ configured to work with log files from
+ <span class="application">syslog</span>.
+ </p><p>
+ On many systems, however, <span class="application">syslog</span> is not very reliable,
+ particularly with large log messages; it might truncate or drop messages
+ just when you need them the most. Also, on <span class="productname">Linux</span>,
+ <span class="application">syslog</span> will flush each message to disk, yielding poor
+ performance. (You can use a <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span> at the start of the file name
+ in the <span class="application">syslog</span> configuration file to disable syncing.)
+ </p><p>
+ Note that all the solutions described above take care of starting new
+ log files at configurable intervals, but they do not handle deletion
+ of old, no-longer-useful log files. You will probably want to set
+ up a batch job to periodically delete old log files. Another possibility
+ is to configure the rotation program so that old log files are overwritten
+ cyclically.
+ </p><p>
+ <a class="ulink" href="https://pgbadger.darold.net/" target="_top"><span class="productname">pgBadger</span></a>
+ is an external project that does sophisticated log file analysis.
+ <a class="ulink" href="https://bucardo.org/check_postgres/" target="_top"><span class="productname">check_postgres</span></a>
+ provides Nagios alerts when important messages appear in the log
+ files, as well as detection of many other extraordinary conditions.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="routine-reindex.html" title="25.2. Routine Reindexing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup.html" title="Chapter 26. Backup and Restore">Next</a></td></tr><tr><td width="40%" align="left" valign="top">25.2. Routine Reindexing </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 26. Backup and Restore</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-architecture.html b/doc/src/sgml/html/logical-replication-architecture.html
new file mode 100644
index 0000000..be23888
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-architecture.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.7. Architecture</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-restrictions.html" title="31.6. Restrictions" /><link rel="next" href="logical-replication-monitoring.html" title="31.8. Monitoring" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.7. Architecture</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-restrictions.html" title="31.6. Restrictions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-monitoring.html" title="31.8. Monitoring">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-ARCHITECTURE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.7. Architecture</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logical-replication-architecture.html#LOGICAL-REPLICATION-SNAPSHOT">31.7.1. Initial Snapshot</a></span></dt></dl></div><p>
+ Logical replication starts by copying a snapshot of the data on the
+ publisher database. Once that is done, changes on the publisher are sent
+ to the subscriber as they occur in real time. The subscriber applies data
+ in the order in which commits were made on the publisher so that
+ transactional consistency is guaranteed for the publications within any
+ single subscription.
+ </p><p>
+ Logical replication is built with an architecture similar to physical
+ streaming replication (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>). It is
+ implemented by <span class="quote">“<span class="quote">walsender</span>”</span> and <span class="quote">“<span class="quote">apply</span>”</span>
+ processes. The walsender process starts logical decoding (described
+ in <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>) of the WAL and loads the standard
+ logical decoding plugin (pgoutput). The plugin transforms the changes read
+ from WAL to the logical replication protocol
+ (see <a class="xref" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Section 55.5</a>) and filters the data
+ according to the publication specification. The data is then continuously
+ transferred using the streaming replication protocol to the apply worker,
+ which maps the data to local tables and applies the individual changes as
+ they are received, in correct transactional order.
+ </p><p>
+ The apply process on the subscriber database always runs with
+ <a class="link" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE"><code class="varname">session_replication_role</code></a>
+ set to <code class="literal">replica</code>. This means that, by default,
+ triggers and rules will not fire on a subscriber. Users can optionally choose to
+ enable triggers and rules on a table using the
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> command
+ and the <code class="literal">ENABLE TRIGGER</code> and <code class="literal">ENABLE RULE</code>
+ clauses.
+ </p><p>
+ The logical replication apply process currently only fires row triggers,
+ not statement triggers. The initial table synchronization, however, is
+ implemented like a <code class="command">COPY</code> command and thus fires both row
+ and statement triggers for <code class="command">INSERT</code>.
+ </p><div class="sect2" id="LOGICAL-REPLICATION-SNAPSHOT"><div class="titlepage"><div><div><h3 class="title">31.7.1. Initial Snapshot</h3></div></div></div><p>
+ The initial data in existing subscribed tables are snapshotted and
+ copied in a parallel instance of a special kind of apply process.
+ This process will create its own replication slot and copy the existing
+ data. As soon as the copy is finished the table contents will become
+ visible to other backends. Once existing data is copied, the worker
+ enters synchronization mode, which ensures that the table is brought
+ up to a synchronized state with the main apply process by streaming
+ any changes that happened during the initial data copy using standard
+ logical replication. During this synchronization phase, the changes
+ are applied and committed in the same order as they happened on the
+ publisher. Once synchronization is done, control of the
+ replication of the table is given back to the main apply process where
+ replication continues as normal.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The publication <code class="literal">publish</code> parameter only affects what
+ DML operations will be replicated. The initial data synchronization does
+ not take this parameter into account when copying the existing table data.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-restrictions.html" title="31.6. Restrictions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-monitoring.html" title="31.8. Monitoring">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.6. Restrictions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.8. Monitoring</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-col-lists.html b/doc/src/sgml/html/logical-replication-col-lists.html
new file mode 100644
index 0000000..26436f0
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-col-lists.html
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.4. Column Lists</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-row-filter.html" title="31.3. Row Filters" /><link rel="next" href="logical-replication-conflicts.html" title="31.5. Conflicts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.4. Column Lists</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-row-filter.html" title="31.3. Row Filters">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-conflicts.html" title="31.5. Conflicts">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-COL-LISTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.4. Column Lists</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logical-replication-col-lists.html#LOGICAL-REPLICATION-COL-LIST-EXAMPLES">31.4.1. Examples</a></span></dt></dl></div><p>
+ Each publication can optionally specify which columns of each table are
+ replicated to subscribers. The table on the subscriber side must have at
+ least all the columns that are published. If no column list is specified,
+ then all columns on the publisher are replicated.
+ See <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a> for details on the syntax.
+ </p><p>
+ The choice of columns can be based on behavioral or performance reasons.
+ However, do not rely on this feature for security: a malicious subscriber
+ is able to obtain data from columns that are not specifically
+ published. If security is a consideration, protections can be applied
+ at the publisher side.
+ </p><p>
+ If no column list is specified, any columns added later are automatically
+ replicated. This means that having a column list which names all columns
+ is not the same as having no column list at all.
+ </p><p>
+ A column list can contain only simple column references. The order
+ of columns in the list is not preserved.
+ </p><p>
+ Specifying a column list when the publication also publishes
+ <code class="literal">FOR TABLES IN SCHEMA</code> is not supported.
+ </p><p>
+ For partitioned tables, the publication parameter
+ <code class="literal">publish_via_partition_root</code> determines which column list
+ is used. If <code class="literal">publish_via_partition_root</code> is
+ <code class="literal">true</code>, the root partitioned table's column list is used.
+ Otherwise, if <code class="literal">publish_via_partition_root</code> is
+ <code class="literal">false</code> (the default), each partition's column list is used.
+ </p><p>
+ If a publication publishes <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> operations, any column list must include the
+ table's replica identity columns (see
+ <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY"><code class="literal">REPLICA IDENTITY</code></a>).
+ If a publication publishes only <code class="command">INSERT</code> operations, then
+ the column list may omit replica identity columns.
+ </p><p>
+ Column lists have no effect for the <code class="literal">TRUNCATE</code> command.
+ </p><p>
+ During initial data synchronization, only the published columns are
+ copied. However, if the subscriber is from a release prior to 15, then
+ all the columns in the table are copied during initial data synchronization,
+ ignoring any column lists.
+ </p><div class="warning" id="LOGICAL-REPLICATION-COL-LIST-COMBINING"><h3 class="title">Warning: Combining Column Lists from Multiple Publications</h3><p>
+ There's currently no support for subscriptions comprising several
+ publications where the same table has been published with different
+ column lists. <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a> disallows
+ creating such subscriptions, but it is still possible to get into
+ that situation by adding or altering column lists on the publication
+ side after a subscription has been created.
+ </p><p>
+ This means changing the column lists of tables on publications that are
+ already subscribed could lead to errors being thrown on the subscriber
+ side.
+ </p><p>
+ If a subscription is affected by this problem, the only way to resume
+ replication is to adjust one of the column lists on the publication
+ side so that they all match; and then either recreate the subscription,
+ or use <code class="literal">ALTER SUBSCRIPTION ... DROP PUBLICATION</code> to
+ remove one of the offending publications and add it again.
+ </p></div><div class="sect2" id="LOGICAL-REPLICATION-COL-LIST-EXAMPLES"><div class="titlepage"><div><div><h3 class="title">31.4.1. Examples</h3></div></div></div><p>
+ Create a table <code class="literal">t1</code> to be used in the following example.
+</p><pre class="programlisting">
+test_pub=# CREATE TABLE t1(id int, a text, b text, c text, d text, e text, PRIMARY KEY(id));
+CREATE TABLE
+</pre><p>
+ Create a publication <code class="literal">p1</code>. A column list is defined for
+ table <code class="literal">t1</code> to reduce the number of columns that will be
+ replicated. Notice that the order of column names in the column list does
+ not matter.
+</p><pre class="programlisting">
+test_pub=# CREATE PUBLICATION p1 FOR TABLE t1 (id, b, a, d);
+CREATE PUBLICATION
+</pre><p>
+ <code class="literal">psql</code> can be used to show the column lists (if defined)
+ for each publication.
+</p><pre class="programlisting">
+test_pub=# \dRp+
+ Publication p1
+ Owner | All tables | Inserts | Updates | Deletes | Truncates | Via root
+----------+------------+---------+---------+---------+-----------+----------
+ postgres | f | t | t | t | t | f
+Tables:
+ "public.t1" (id, a, b, d)
+</pre><p>
+ <code class="literal">psql</code> can be used to show the column lists (if defined)
+ for each table.
+</p><pre class="programlisting">
+test_pub=# \d t1
+ Table "public.t1"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ id | integer | | not null |
+ a | text | | |
+ b | text | | |
+ c | text | | |
+ d | text | | |
+ e | text | | |
+Indexes:
+ "t1_pkey" PRIMARY KEY, btree (id)
+Publications:
+ "p1" (id, a, b, d)
+</pre><p>
+ On the subscriber node, create a table <code class="literal">t1</code> which now
+ only needs a subset of the columns that were on the publisher table
+ <code class="literal">t1</code>, and also create the subscription
+ <code class="literal">s1</code> that subscribes to the publication
+ <code class="literal">p1</code>.
+</p><pre class="programlisting">
+test_sub=# CREATE TABLE t1(id int, b text, a text, d text, PRIMARY KEY(id));
+CREATE TABLE
+test_sub=# CREATE SUBSCRIPTION s1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=s1'
+test_sub-# PUBLICATION p1;
+CREATE SUBSCRIPTION
+</pre><p>
+ On the publisher node, insert some rows to table <code class="literal">t1</code>.
+</p><pre class="programlisting">
+test_pub=# INSERT INTO t1 VALUES(1, 'a-1', 'b-1', 'c-1', 'd-1', 'e-1');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES(2, 'a-2', 'b-2', 'c-2', 'd-2', 'e-2');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES(3, 'a-3', 'b-3', 'c-3', 'd-3', 'e-3');
+INSERT 0 1
+test_pub=# SELECT * FROM t1 ORDER BY id;
+ id | a | b | c | d | e
+----+-----+-----+-----+-----+-----
+ 1 | a-1 | b-1 | c-1 | d-1 | e-1
+ 2 | a-2 | b-2 | c-2 | d-2 | e-2
+ 3 | a-3 | b-3 | c-3 | d-3 | e-3
+(3 rows)
+</pre><p>
+ Only data from the column list of publication <code class="literal">p1</code> is
+ replicated.
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1 ORDER BY id;
+ id | b | a | d
+----+-----+-----+-----
+ 1 | b-1 | a-1 | d-1
+ 2 | b-2 | a-2 | d-2
+ 3 | b-3 | a-3 | d-3
+(3 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-row-filter.html" title="31.3. Row Filters">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-conflicts.html" title="31.5. Conflicts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.3. Row Filters </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.5. Conflicts</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-config.html b/doc/src/sgml/html/logical-replication-config.html
new file mode 100644
index 0000000..3db4fe3
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-config.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.10. Configuration Settings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-security.html" title="31.9. Security" /><link rel="next" href="logical-replication-quick-setup.html" title="31.11. Quick Setup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.10. Configuration Settings</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-security.html" title="31.9. Security">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-quick-setup.html" title="31.11. Quick Setup">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.10. Configuration Settings</h2></div></div></div><p>
+ Logical replication requires several configuration options to be set.
+ </p><p>
+ On the publisher side, <code class="varname">wal_level</code> must be set to
+ <code class="literal">logical</code>, and <code class="varname">max_replication_slots</code>
+ must be set to at least the number of subscriptions expected to connect,
+ plus some reserve for table synchronization. And
+ <code class="varname">max_wal_senders</code> should be set to at least the same as
+ <code class="varname">max_replication_slots</code> plus the number of physical
+ replicas that are connected at the same time.
+ </p><p>
+ <code class="varname">max_replication_slots</code> must also be set on the subscriber.
+ It should be set to at least the number of subscriptions that will be added
+ to the subscriber, plus some reserve for table synchronization.
+ <code class="varname">max_logical_replication_workers</code> must be set to at least
+ the number of subscriptions, again plus some reserve for the table
+ synchronization. Additionally the <code class="varname">max_worker_processes</code>
+ may need to be adjusted to accommodate for replication workers, at least
+ (<code class="varname">max_logical_replication_workers</code>
+ + <code class="literal">1</code>). Note that some extensions and parallel queries
+ also take worker slots from <code class="varname">max_worker_processes</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-security.html" title="31.9. Security">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-quick-setup.html" title="31.11. Quick Setup">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.9. Security </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.11. Quick Setup</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-conflicts.html b/doc/src/sgml/html/logical-replication-conflicts.html
new file mode 100644
index 0000000..99b8a79
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-conflicts.html
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.5. Conflicts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-col-lists.html" title="31.4. Column Lists" /><link rel="next" href="logical-replication-restrictions.html" title="31.6. Restrictions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.5. Conflicts</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-col-lists.html" title="31.4. Column Lists">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-restrictions.html" title="31.6. Restrictions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-CONFLICTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.5. Conflicts</h2></div></div></div><p>
+ Logical replication behaves similarly to normal DML operations in that
+ the data will be updated even if it was changed locally on the subscriber
+ node. If incoming data violates any constraints the replication will
+ stop. This is referred to as a <em class="firstterm">conflict</em>. When
+ replicating <code class="command">UPDATE</code> or <code class="command">DELETE</code>
+ operations, missing data will not produce a conflict and such operations
+ will simply be skipped.
+ </p><p>
+ Logical replication operations are performed with the privileges of the role
+ which owns the subscription. Permissions failures on target tables will
+ cause replication conflicts, as will enabled
+ <a class="link" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">row-level security</a> on target tables
+ that the subscription owner is subject to, without regard to whether any
+ policy would ordinarily reject the <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code> or
+ <code class="command">TRUNCATE</code> which is being replicated. This restriction on
+ row-level security may be lifted in a future version of
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ A conflict will produce an error and will stop the replication; it must be
+ resolved manually by the user. Details about the conflict can be found in
+ the subscriber's server log.
+ </p><p>
+ The resolution can be done either by changing data or permissions on the subscriber so
+ that it does not conflict with the incoming change or by skipping the
+ transaction that conflicts with the existing data. When a conflict produces
+ an error, the replication won't proceed, and the logical replication worker will
+ emit the following kind of message to the subscriber's server log:
+</p><pre class="screen">
+ERROR: duplicate key value violates unique constraint "test_pkey"
+DETAIL: Key (c)=(1) already exists.
+CONTEXT: processing remote data for replication origin "pg_16395" during "INSERT" for replication target relation "public.test" in transaction 725 finished at 0/14C0378
+</pre><p>
+ The LSN of the transaction that contains the change violating the constraint and
+ the replication origin name can be found from the server log (LSN 0/14C0378 and
+ replication origin <code class="literal">pg_16395</code> in the above case). The
+ transaction that produced the conflict can be skipped by using
+ <code class="command">ALTER SUBSCRIPTION ... SKIP</code> with the finish LSN
+ (i.e., LSN 0/14C0378). The finish LSN could be an LSN at which the transaction
+ is committed or prepared on the publisher. Alternatively, the transaction can
+ also be skipped by calling the <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-ADVANCE">
+ <code class="function">pg_replication_origin_advance()</code></a> function.
+ Before using this function, the subscription needs to be disabled temporarily
+ either by <code class="command">ALTER SUBSCRIPTION ... DISABLE</code> or, the
+ subscription can be used with the <code class="literal">disable_on_error</code> option.
+ Then, you can use <code class="function">pg_replication_origin_advance()</code> function
+ with the <em class="parameter"><code>node_name</code></em> (i.e., <code class="literal">pg_16395</code>)
+ and the next LSN of the finish LSN (i.e., 0/14C0379). The current position of
+ origins can be seen in the <a class="link" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">
+ <code class="structname">pg_replication_origin_status</code></a> system view.
+ Please note that skipping the whole transaction includes skipping changes that
+ might not violate any constraint. This can easily make the subscriber
+ inconsistent.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-col-lists.html" title="31.4. Column Lists">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-restrictions.html" title="31.6. Restrictions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.4. Column Lists </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.6. Restrictions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-monitoring.html b/doc/src/sgml/html/logical-replication-monitoring.html
new file mode 100644
index 0000000..6675143
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-monitoring.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.8. Monitoring</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-architecture.html" title="31.7. Architecture" /><link rel="next" href="logical-replication-security.html" title="31.9. Security" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.8. Monitoring</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-architecture.html" title="31.7. Architecture">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-security.html" title="31.9. Security">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-MONITORING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.8. Monitoring</h2></div></div></div><p>
+ Because logical replication is based on a similar architecture as
+ <a class="link" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">physical streaming replication</a>,
+ the monitoring on a publication node is similar to monitoring of a
+ physical replication primary
+ (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-MONITORING" title="27.2.5.2. Monitoring">Section 27.2.5.2</a>).
+ </p><p>
+ The monitoring information about subscription is visible in
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION" title="28.2.8. pg_stat_subscription">
+ <code class="structname">pg_stat_subscription</code></a>.
+ This view contains one row for every subscription worker. A subscription
+ can have zero or more active subscription workers depending on its state.
+ </p><p>
+ Normally, there is a single apply process running for an enabled
+ subscription. A disabled subscription or a crashed subscription will have
+ zero rows in this view. If the initial data synchronization of any
+ table is in progress, there will be additional workers for the tables
+ being synchronized.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-architecture.html" title="31.7. Architecture">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-security.html" title="31.9. Security">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.7. Architecture </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.9. Security</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-publication.html b/doc/src/sgml/html/logical-replication-publication.html
new file mode 100644
index 0000000..8726a87
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-publication.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.1. Publication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication.html" title="Chapter 31. Logical Replication" /><link rel="next" href="logical-replication-subscription.html" title="31.2. Subscription" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.1. Publication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication.html" title="Chapter 31. Logical Replication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-subscription.html" title="31.2. Subscription">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-PUBLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.1. Publication</h2></div></div></div><p>
+ A <em class="firstterm">publication</em> can be defined on any physical
+ replication primary. The node where a publication is defined is referred to
+ as <em class="firstterm">publisher</em>. A publication is a set of changes
+ generated from a table or a group of tables, and might also be described as
+ a change set or replication set. Each publication exists in only one database.
+ </p><p>
+ Publications are different from schemas and do not affect how the table is
+ accessed. Each table can be added to multiple publications if needed.
+ Publications may currently only contain tables and all tables in schema.
+ Objects must be added explicitly, except when a publication is created for
+ <code class="literal">ALL TABLES</code>.
+ </p><p>
+ Publications can choose to limit the changes they produce to
+ any combination of <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, and <code class="command">TRUNCATE</code>, similar to how triggers are fired by
+ particular event types. By default, all operation types are replicated.
+ These publication specifications apply only for DML operations; they do not affect the initial
+ data synchronization copy. (Row filters have no effect for
+ <code class="command">TRUNCATE</code>. See <a class="xref" href="logical-replication-row-filter.html" title="31.3. Row Filters">Section 31.3</a>).
+ </p><p>
+ A published table must have a <span class="quote">“<span class="quote">replica identity</span>”</span> configured in
+ order to be able to replicate <code class="command">UPDATE</code>
+ and <code class="command">DELETE</code> operations, so that appropriate rows to
+ update or delete can be identified on the subscriber side. By default,
+ this is the primary key, if there is one. Another unique index (with
+ certain additional requirements) can also be set to be the replica
+ identity. If the table does not have any suitable key, then it can be set
+ to replica identity <span class="quote">“<span class="quote">full</span>”</span>, which means the entire row becomes
+ the key. This, however, is very inefficient and should only be used as a
+ fallback if no other solution is possible. If a replica identity other
+ than <span class="quote">“<span class="quote">full</span>”</span> is set on the publisher side, a replica identity
+ comprising the same or fewer columns must also be set on the subscriber
+ side. See <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY"><code class="literal">REPLICA IDENTITY</code></a> for details on
+ how to set the replica identity. If a table without a replica identity is
+ added to a publication that replicates <code class="command">UPDATE</code>
+ or <code class="command">DELETE</code> operations then
+ subsequent <code class="command">UPDATE</code> or <code class="command">DELETE</code>
+ operations will cause an error on the publisher. <code class="command">INSERT</code>
+ operations can proceed regardless of any replica identity.
+ </p><p>
+ Every publication can have multiple subscribers.
+ </p><p>
+ A publication is created using the <a class="link" href="sql-createpublication.html" title="CREATE PUBLICATION"><code class="command">CREATE PUBLICATION</code></a>
+ command and may later be altered or dropped using corresponding commands.
+ </p><p>
+ The individual tables can be added and removed dynamically using
+ <a class="link" href="sql-alterpublication.html" title="ALTER PUBLICATION"><code class="command">ALTER PUBLICATION</code></a>. Both the <code class="literal">ADD
+ TABLE</code> and <code class="literal">DROP TABLE</code> operations are
+ transactional; so the table will start or stop replicating at the correct
+ snapshot once the transaction has committed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication.html" title="Chapter 31. Logical Replication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-subscription.html" title="31.2. Subscription">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 31. Logical Replication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.2. Subscription</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-quick-setup.html b/doc/src/sgml/html/logical-replication-quick-setup.html
new file mode 100644
index 0000000..cc1e9bb
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-quick-setup.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.11. Quick Setup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-config.html" title="31.10. Configuration Settings" /><link rel="next" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.11. Quick Setup</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-config.html" title="31.10. Configuration Settings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-QUICK-SETUP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.11. Quick Setup</h2></div></div></div><p>
+ First set the configuration options in <code class="filename">postgresql.conf</code>:
+</p><pre class="programlisting">
+wal_level = logical
+</pre><p>
+ The other required settings have default values that are sufficient for a
+ basic setup.
+ </p><p>
+ <code class="filename">pg_hba.conf</code> needs to be adjusted to allow replication
+ (the values here depend on your actual network configuration and user you
+ want to use for connecting):
+</p><pre class="programlisting">
+host all repuser 0.0.0.0/0 md5
+</pre><p>
+ </p><p>
+ Then on the publisher database:
+</p><pre class="programlisting">
+CREATE PUBLICATION mypub FOR TABLE users, departments;
+</pre><p>
+ </p><p>
+ And on the subscriber database:
+</p><pre class="programlisting">
+CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar user=repuser' PUBLICATION mypub;
+</pre><p>
+ </p><p>
+ The above will start the replication process, which synchronizes the
+ initial table contents of the tables <code class="literal">users</code> and
+ <code class="literal">departments</code> and then starts replicating
+ incremental changes to those tables.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-config.html" title="31.10. Configuration Settings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.10. Configuration Settings </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 32. Just-in-Time Compilation (<acronym class="acronym">JIT</acronym>)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-restrictions.html b/doc/src/sgml/html/logical-replication-restrictions.html
new file mode 100644
index 0000000..a51f325
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-restrictions.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.6. Restrictions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-conflicts.html" title="31.5. Conflicts" /><link rel="next" href="logical-replication-architecture.html" title="31.7. Architecture" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.6. Restrictions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-conflicts.html" title="31.5. Conflicts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-architecture.html" title="31.7. Architecture">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-RESTRICTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.6. Restrictions</h2></div></div></div><p>
+ Logical replication currently has the following restrictions or missing
+ functionality. These might be addressed in future releases.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The database schema and DDL commands are not replicated. The initial
+ schema can be copied by hand using <code class="literal">pg_dump
+ --schema-only</code>. Subsequent schema changes would need to be kept
+ in sync manually. (Note, however, that there is no need for the schemas
+ to be absolutely the same on both sides.) Logical replication is robust
+ when schema definitions change in a live database: When the schema is
+ changed on the publisher and replicated data starts arriving at the
+ subscriber but does not fit into the table schema, replication will error
+ until the schema is updated. In many cases, intermittent errors can be
+ avoided by applying additive schema changes to the subscriber first.
+ </p></li><li class="listitem"><p>
+ Sequence data is not replicated. The data in serial or identity columns
+ backed by sequences will of course be replicated as part of the table,
+ but the sequence itself would still show the start value on the
+ subscriber. If the subscriber is used as a read-only database, then this
+ should typically not be a problem. If, however, some kind of switchover
+ or failover to the subscriber database is intended, then the sequences
+ would need to be updated to the latest values, either by copying the
+ current data from the publisher (perhaps
+ using <code class="command">pg_dump</code>) or by determining a sufficiently high
+ value from the tables themselves.
+ </p></li><li class="listitem"><p>
+ Replication of <code class="command">TRUNCATE</code> commands is supported, but
+ some care must be taken when truncating groups of tables connected by
+ foreign keys. When replicating a truncate action, the subscriber will
+ truncate the same group of tables that was truncated on the publisher,
+ either explicitly specified or implicitly collected via
+ <code class="literal">CASCADE</code>, minus tables that are not part of the
+ subscription. This will work correctly if all affected tables are part
+ of the same subscription. But if some tables to be truncated on the
+ subscriber have foreign-key links to tables that are not part of the same
+ (or any) subscription, then the application of the truncate action on the
+ subscriber will fail.
+ </p></li><li class="listitem"><p>
+ Large objects (see <a class="xref" href="largeobjects.html" title="Chapter 35. Large Objects">Chapter 35</a>) are not replicated.
+ There is no workaround for that, other than storing data in normal
+ tables.
+ </p></li><li class="listitem"><p>
+ Replication is only supported by tables, including partitioned tables.
+ Attempts to replicate other types of relations, such as views, materialized
+ views, or foreign tables, will result in an error.
+ </p></li><li class="listitem"><p>
+ When replicating between partitioned tables, the actual replication
+ originates, by default, from the leaf partitions on the publisher, so
+ partitions on the publisher must also exist on the subscriber as valid
+ target tables. (They could either be leaf partitions themselves, or they
+ could be further subpartitioned, or they could even be independent
+ tables.) Publications can also specify that changes are to be replicated
+ using the identity and schema of the partitioned root table instead of
+ that of the individual leaf partitions in which the changes actually
+ originate (see <a class="link" href="sql-createpublication.html" title="CREATE PUBLICATION"><code class="command">CREATE PUBLICATION</code></a>).
+ </p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-conflicts.html" title="31.5. Conflicts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-architecture.html" title="31.7. Architecture">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.5. Conflicts </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.7. Architecture</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-row-filter.html b/doc/src/sgml/html/logical-replication-row-filter.html
new file mode 100644
index 0000000..87102cc
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-row-filter.html
@@ -0,0 +1,440 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.3. Row Filters</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-subscription.html" title="31.2. Subscription" /><link rel="next" href="logical-replication-col-lists.html" title="31.4. Column Lists" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.3. Row Filters</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-subscription.html" title="31.2. Subscription">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-col-lists.html" title="31.4. Column Lists">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-ROW-FILTER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.3. Row Filters</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-RULES">31.3.1. Row Filter Rules</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-RESTRICTIONS">31.3.2. Expression Restrictions</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-TRANSFORMATIONS">31.3.3. UPDATE Transformations</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-PARTITIONED-TABLE">31.3.4. Partitioned Tables</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-INITIAL-DATA-SYNC">31.3.5. Initial Data Synchronization</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-COMBINING">31.3.6. Combining Multiple Row Filters</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-EXAMPLES">31.3.7. Examples</a></span></dt></dl></div><p>
+ By default, all data from all published tables will be replicated to the
+ appropriate subscribers. The replicated data can be reduced by using a
+ <em class="firstterm">row filter</em>. A user might choose to use row filters
+ for behavioral, security or performance reasons. If a published table sets a
+ row filter, a row is replicated only if its data satisfies the row filter
+ expression. This allows a set of tables to be partially replicated. The row
+ filter is defined per table. Use a <code class="literal">WHERE</code> clause after the
+ table name for each published table that requires data to be filtered out.
+ The <code class="literal">WHERE</code> clause must be enclosed by parentheses. See
+ <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a> for details.
+ </p><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-RULES"><div class="titlepage"><div><div><h3 class="title">31.3.1. Row Filter Rules</h3></div></div></div><p>
+ Row filters are applied <span class="emphasis"><em>before</em></span> publishing the changes.
+ If the row filter evaluates to <code class="literal">false</code> or <code class="literal">NULL</code>
+ then the row is not replicated. The <code class="literal">WHERE</code> clause expression
+ is evaluated with the same role used for the replication connection (i.e.
+ the role specified in the <code class="literal">CONNECTION</code> clause of the
+ <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>). Row filters have no effect for
+ <code class="command">TRUNCATE</code> command.
+ </p></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-RESTRICTIONS"><div class="titlepage"><div><div><h3 class="title">31.3.2. Expression Restrictions</h3></div></div></div><p>
+ The <code class="literal">WHERE</code> clause allows only simple expressions. It
+ cannot contain user-defined functions, operators, types, and collations,
+ system column references or non-immutable built-in functions.
+ </p><p>
+ If a publication publishes <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> operations, the row filter <code class="literal">WHERE</code>
+ clause must contain only columns that are covered by the replica identity
+ (see <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY"><code class="literal">REPLICA IDENTITY</code></a>). If a publication
+ publishes only <code class="command">INSERT</code> operations, the row filter
+ <code class="literal">WHERE</code> clause can use any column.
+ </p></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-TRANSFORMATIONS"><div class="titlepage"><div><div><h3 class="title">31.3.3. UPDATE Transformations</h3></div></div></div><p>
+ Whenever an <code class="command">UPDATE</code> is processed, the row filter
+ expression is evaluated for both the old and new row (i.e. using the data
+ before and after the update). If both evaluations are <code class="literal">true</code>,
+ it replicates the <code class="command">UPDATE</code> change. If both evaluations are
+ <code class="literal">false</code>, it doesn't replicate the change. If only one of
+ the old/new rows matches the row filter expression, the <code class="command">UPDATE</code>
+ is transformed to <code class="command">INSERT</code> or <code class="command">DELETE</code>, to
+ avoid any data inconsistency. The row on the subscriber should reflect what
+ is defined by the row filter expression on the publisher.
+ </p><p>
+ If the old row satisfies the row filter expression (it was sent to the
+ subscriber) but the new row doesn't, then, from a data consistency
+ perspective the old row should be removed from the subscriber.
+ So the <code class="command">UPDATE</code> is transformed into a <code class="command">DELETE</code>.
+ </p><p>
+ If the old row doesn't satisfy the row filter expression (it wasn't sent
+ to the subscriber) but the new row does, then, from a data consistency
+ perspective the new row should be added to the subscriber.
+ So the <code class="command">UPDATE</code> is transformed into an <code class="command">INSERT</code>.
+ </p><p>
+ <a class="xref" href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-TRANSFORMATIONS-SUMMARY" title="Table 31.1. UPDATE Transformation Summary">Table 31.1</a>
+ summarizes the applied transformations.
+ </p><div class="table" id="LOGICAL-REPLICATION-ROW-FILTER-TRANSFORMATIONS-SUMMARY"><p class="title"><strong>Table 31.1. <code class="command">UPDATE</code> Transformation Summary</strong></p><div class="table-contents"><table class="table" summary="UPDATE Transformation Summary" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Old row</th><th>New row</th><th>Transformation</th></tr></thead><tbody><tr><td>no match</td><td>no match</td><td>don't replicate</td></tr><tr><td>no match</td><td>match</td><td><code class="literal">INSERT</code></td></tr><tr><td>match</td><td>no match</td><td><code class="literal">DELETE</code></td></tr><tr><td>match</td><td>match</td><td><code class="literal">UPDATE</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-PARTITIONED-TABLE"><div class="titlepage"><div><div><h3 class="title">31.3.4. Partitioned Tables</h3></div></div></div><p>
+ If the publication contains a partitioned table, the publication parameter
+ <code class="literal">publish_via_partition_root</code> determines which row filter
+ is used. If <code class="literal">publish_via_partition_root</code> is <code class="literal">true</code>,
+ the <span class="emphasis"><em>root partitioned table's</em></span> row filter is used. Otherwise,
+ if <code class="literal">publish_via_partition_root</code> is <code class="literal">false</code>
+ (default), each <span class="emphasis"><em>partition's</em></span> row filter is used.
+ </p></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-INITIAL-DATA-SYNC"><div class="titlepage"><div><div><h3 class="title">31.3.5. Initial Data Synchronization</h3></div></div></div><p>
+ If the subscription requires copying pre-existing table data
+ and a publication contains <code class="literal">WHERE</code> clauses, only data that
+ satisfies the row filter expressions is copied to the subscriber.
+ </p><p>
+ If the subscription has several publications in which a table has been
+ published with different <code class="literal">WHERE</code> clauses, rows that satisfy
+ <span class="emphasis"><em>any</em></span> of the expressions will be copied. See
+ <a class="xref" href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-COMBINING" title="31.3.6. Combining Multiple Row Filters">Section 31.3.6</a> for details.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ Because initial data synchronization does not take into account the
+ <code class="literal">publish</code> parameter when copying existing table data,
+ some rows may be copied that would not be replicated using DML. Refer to
+ <a class="xref" href="logical-replication-architecture.html#LOGICAL-REPLICATION-SNAPSHOT" title="31.7.1. Initial Snapshot">Section 31.7.1</a>, and see
+ <a class="xref" href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-EXAMPLES" title="31.2.2. Examples">Section 31.2.2</a> for examples.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ If the subscriber is in a release prior to 15, copy pre-existing data
+ doesn't use row filters even if they are defined in the publication.
+ This is because old releases can only copy the entire table data.
+ </p></div></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-COMBINING"><div class="titlepage"><div><div><h3 class="title">31.3.6. Combining Multiple Row Filters</h3></div></div></div><p>
+ If the subscription has several publications in which the same table has
+ been published with different row filters (for the same <code class="literal">publish</code>
+ operation), those expressions get ORed together, so that rows satisfying
+ <span class="emphasis"><em>any</em></span> of the expressions will be replicated. This means all
+ the other row filters for the same table become redundant if:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ One of the publications has no row filter.
+ </p></li><li class="listitem"><p>
+ One of the publications was created using <code class="literal">FOR ALL TABLES</code>.
+ This clause does not allow row filters.
+ </p></li><li class="listitem"><p>
+ One of the publications was created using
+ <code class="literal">FOR TABLES IN SCHEMA</code> and the table belongs to
+ the referred schema. This clause does not allow row filters.
+ </p></li></ul></div></div><div class="sect2" id="LOGICAL-REPLICATION-ROW-FILTER-EXAMPLES"><div class="titlepage"><div><div><h3 class="title">31.3.7. Examples</h3></div></div></div><p>
+ Create some tables to be used in the following examples.
+</p><pre class="programlisting">
+test_pub=# CREATE TABLE t1(a int, b int, c text, PRIMARY KEY(a,c));
+CREATE TABLE
+test_pub=# CREATE TABLE t2(d int, e int, f int, PRIMARY KEY(d));
+CREATE TABLE
+test_pub=# CREATE TABLE t3(g int, h int, i int, PRIMARY KEY(g));
+CREATE TABLE
+</pre><p>
+ Create some publications. Publication <code class="literal">p1</code> has one table
+ (<code class="literal">t1</code>) and that table has a row filter. Publication
+ <code class="literal">p2</code> has two tables. Table <code class="literal">t1</code> has no row
+ filter, and table <code class="literal">t2</code> has a row filter. Publication
+ <code class="literal">p3</code> has two tables, and both of them have a row filter.
+</p><pre class="programlisting">
+test_pub=# CREATE PUBLICATION p1 FOR TABLE t1 WHERE (a &gt; 5 AND c = 'NSW');
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION p2 FOR TABLE t1, t2 WHERE (e = 99);
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION p3 FOR TABLE t2 WHERE (d = 10), t3 WHERE (g = 10);
+CREATE PUBLICATION
+</pre><p>
+ <code class="command">psql</code> can be used to show the row filter expressions (if
+ defined) for each publication.
+</p><pre class="programlisting">
+test_pub=# \dRp+
+ Publication p1
+ Owner | All tables | Inserts | Updates | Deletes | Truncates | Via root
+----------+------------+---------+---------+---------+-----------+----------
+ postgres | f | t | t | t | t | f
+Tables:
+ "public.t1" WHERE ((a &gt; 5) AND (c = 'NSW'::text))
+
+ Publication p2
+ Owner | All tables | Inserts | Updates | Deletes | Truncates | Via root
+----------+------------+---------+---------+---------+-----------+----------
+ postgres | f | t | t | t | t | f
+Tables:
+ "public.t1"
+ "public.t2" WHERE (e = 99)
+
+ Publication p3
+ Owner | All tables | Inserts | Updates | Deletes | Truncates | Via root
+----------+------------+---------+---------+---------+-----------+----------
+ postgres | f | t | t | t | t | f
+Tables:
+ "public.t2" WHERE (d = 10)
+ "public.t3" WHERE (g = 10)
+</pre><p>
+ <code class="command">psql</code> can be used to show the row filter expressions (if
+ defined) for each table. See that table <code class="literal">t1</code> is a member
+ of two publications, but has a row filter only in <code class="literal">p1</code>.
+ See that table <code class="literal">t2</code> is a member of two publications, and
+ has a different row filter in each of them.
+</p><pre class="programlisting">
+test_pub=# \d t1
+ Table "public.t1"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ a | integer | | not null |
+ b | integer | | |
+ c | text | | not null |
+Indexes:
+ "t1_pkey" PRIMARY KEY, btree (a, c)
+Publications:
+ "p1" WHERE ((a &gt; 5) AND (c = 'NSW'::text))
+ "p2"
+
+test_pub=# \d t2
+ Table "public.t2"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ d | integer | | not null |
+ e | integer | | |
+ f | integer | | |
+Indexes:
+ "t2_pkey" PRIMARY KEY, btree (d)
+Publications:
+ "p2" WHERE (e = 99)
+ "p3" WHERE (d = 10)
+
+test_pub=# \d t3
+ Table "public.t3"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ g | integer | | not null |
+ h | integer | | |
+ i | integer | | |
+Indexes:
+ "t3_pkey" PRIMARY KEY, btree (g)
+Publications:
+ "p3" WHERE (g = 10)
+</pre><p>
+ On the subscriber node, create a table <code class="literal">t1</code> with the same
+ definition as the one on the publisher, and also create the subscription
+ <code class="literal">s1</code> that subscribes to the publication <code class="literal">p1</code>.
+</p><pre class="programlisting">
+test_sub=# CREATE TABLE t1(a int, b int, c text, PRIMARY KEY(a,c));
+CREATE TABLE
+test_sub=# CREATE SUBSCRIPTION s1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=s1'
+test_sub-# PUBLICATION p1;
+CREATE SUBSCRIPTION
+</pre><p>
+ Insert some rows. Only the rows satisfying the <code class="literal">t1 WHERE</code>
+ clause of publication <code class="literal">p1</code> are replicated.
+</p><pre class="programlisting">
+test_pub=# INSERT INTO t1 VALUES (2, 102, 'NSW');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (3, 103, 'QLD');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (4, 104, 'VIC');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (5, 105, 'ACT');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (6, 106, 'NSW');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (7, 107, 'NT');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (8, 108, 'QLD');
+INSERT 0 1
+test_pub=# INSERT INTO t1 VALUES (9, 109, 'NSW');
+INSERT 0 1
+
+test_pub=# SELECT * FROM t1;
+ a | b | c
+---+-----+-----
+ 2 | 102 | NSW
+ 3 | 103 | QLD
+ 4 | 104 | VIC
+ 5 | 105 | ACT
+ 6 | 106 | NSW
+ 7 | 107 | NT
+ 8 | 108 | QLD
+ 9 | 109 | NSW
+(8 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b | c
+---+-----+-----
+ 6 | 106 | NSW
+ 9 | 109 | NSW
+(2 rows)
+</pre><p>
+ Update some data, where the old and new row values both
+ satisfy the <code class="literal">t1 WHERE</code> clause of publication
+ <code class="literal">p1</code>. The <code class="command">UPDATE</code> replicates
+ the change as normal.
+</p><pre class="programlisting">
+test_pub=# UPDATE t1 SET b = 999 WHERE a = 6;
+UPDATE 1
+
+test_pub=# SELECT * FROM t1;
+ a | b | c
+---+-----+-----
+ 2 | 102 | NSW
+ 3 | 103 | QLD
+ 4 | 104 | VIC
+ 5 | 105 | ACT
+ 7 | 107 | NT
+ 8 | 108 | QLD
+ 9 | 109 | NSW
+ 6 | 999 | NSW
+(8 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b | c
+---+-----+-----
+ 9 | 109 | NSW
+ 6 | 999 | NSW
+(2 rows)
+</pre><p>
+ Update some data, where the old row values did not satisfy
+ the <code class="literal">t1 WHERE</code> clause of publication <code class="literal">p1</code>,
+ but the new row values do satisfy it. The <code class="command">UPDATE</code> is
+ transformed into an <code class="command">INSERT</code> and the change is replicated.
+ See the new row on the subscriber.
+</p><pre class="programlisting">
+test_pub=# UPDATE t1 SET a = 555 WHERE a = 2;
+UPDATE 1
+
+test_pub=# SELECT * FROM t1;
+ a | b | c
+-----+-----+-----
+ 3 | 103 | QLD
+ 4 | 104 | VIC
+ 5 | 105 | ACT
+ 7 | 107 | NT
+ 8 | 108 | QLD
+ 9 | 109 | NSW
+ 6 | 999 | NSW
+ 555 | 102 | NSW
+(8 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b | c
+-----+-----+-----
+ 9 | 109 | NSW
+ 6 | 999 | NSW
+ 555 | 102 | NSW
+(3 rows)
+</pre><p>
+ Update some data, where the old row values satisfied
+ the <code class="literal">t1 WHERE</code> clause of publication <code class="literal">p1</code>,
+ but the new row values do not satisfy it. The <code class="command">UPDATE</code> is
+ transformed into a <code class="command">DELETE</code> and the change is replicated.
+ See that the row is removed from the subscriber.
+</p><pre class="programlisting">
+test_pub=# UPDATE t1 SET c = 'VIC' WHERE a = 9;
+UPDATE 1
+
+test_pub=# SELECT * FROM t1;
+ a | b | c
+-----+-----+-----
+ 3 | 103 | QLD
+ 4 | 104 | VIC
+ 5 | 105 | ACT
+ 7 | 107 | NT
+ 8 | 108 | QLD
+ 6 | 999 | NSW
+ 555 | 102 | NSW
+ 9 | 109 | VIC
+(8 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b | c
+-----+-----+-----
+ 6 | 999 | NSW
+ 555 | 102 | NSW
+(2 rows)
+</pre><p>
+ The following examples show how the publication parameter
+ <code class="literal">publish_via_partition_root</code> determines whether the row
+ filter of the parent or child table will be used in the case of partitioned
+ tables.
+ </p><p>
+ Create a partitioned table on the publisher.
+</p><pre class="programlisting">
+test_pub=# CREATE TABLE parent(a int PRIMARY KEY) PARTITION BY RANGE(a);
+CREATE TABLE
+test_pub=# CREATE TABLE child PARTITION OF parent DEFAULT;
+CREATE TABLE
+</pre><p>
+ Create the same tables on the subscriber.
+</p><pre class="programlisting">
+test_sub=# CREATE TABLE parent(a int PRIMARY KEY) PARTITION BY RANGE(a);
+CREATE TABLE
+test_sub=# CREATE TABLE child PARTITION OF parent DEFAULT;
+CREATE TABLE
+</pre><p>
+ Create a publication <code class="literal">p4</code>, and then subscribe to it. The
+ publication parameter <code class="literal">publish_via_partition_root</code> is set
+ as true. There are row filters defined on both the partitioned table
+ (<code class="literal">parent</code>), and on the partition (<code class="literal">child</code>).
+</p><pre class="programlisting">
+test_pub=# CREATE PUBLICATION p4 FOR TABLE parent WHERE (a &lt; 5), child WHERE (a &gt;= 5)
+test_pub-# WITH (publish_via_partition_root=true);
+CREATE PUBLICATION
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# CREATE SUBSCRIPTION s4
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=s4'
+test_sub-# PUBLICATION p4;
+CREATE SUBSCRIPTION
+</pre><p>
+ Insert some values directly into the <code class="literal">parent</code> and
+ <code class="literal">child</code> tables. They replicate using the row filter of
+ <code class="literal">parent</code> (because <code class="literal">publish_via_partition_root</code>
+ is true).
+</p><pre class="programlisting">
+test_pub=# INSERT INTO parent VALUES (2), (4), (6);
+INSERT 0 3
+test_pub=# INSERT INTO child VALUES (3), (5), (7);
+INSERT 0 3
+
+test_pub=# SELECT * FROM parent ORDER BY a;
+ a
+---
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+(6 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM parent ORDER BY a;
+ a
+---
+ 2
+ 3
+ 4
+(3 rows)
+</pre><p>
+ Repeat the same test, but with a different value for <code class="literal">publish_via_partition_root</code>.
+ The publication parameter <code class="literal">publish_via_partition_root</code> is
+ set as false. A row filter is defined on the partition (<code class="literal">child</code>).
+</p><pre class="programlisting">
+test_pub=# DROP PUBLICATION p4;
+DROP PUBLICATION
+test_pub=# CREATE PUBLICATION p4 FOR TABLE parent, child WHERE (a &gt;= 5)
+test_pub-# WITH (publish_via_partition_root=false);
+CREATE PUBLICATION
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# ALTER SUBSCRIPTION s4 REFRESH PUBLICATION;
+ALTER SUBSCRIPTION
+</pre><p>
+ Do the inserts on the publisher same as before. They replicate using the
+ row filter of <code class="literal">child</code> (because
+ <code class="literal">publish_via_partition_root</code> is false).
+</p><pre class="programlisting">
+test_pub=# TRUNCATE parent;
+TRUNCATE TABLE
+test_pub=# INSERT INTO parent VALUES (2), (4), (6);
+INSERT 0 3
+test_pub=# INSERT INTO child VALUES (3), (5), (7);
+INSERT 0 3
+
+test_pub=# SELECT * FROM parent ORDER BY a;
+ a
+---
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+(6 rows)
+</pre><p>
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM child ORDER BY a;
+ a
+---
+ 5
+ 6
+ 7
+(3 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-subscription.html" title="31.2. Subscription">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-col-lists.html" title="31.4. Column Lists">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.2. Subscription </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.4. Column Lists</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-security.html b/doc/src/sgml/html/logical-replication-security.html
new file mode 100644
index 0000000..40d7060
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-security.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.9. Security</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-monitoring.html" title="31.8. Monitoring" /><link rel="next" href="logical-replication-config.html" title="31.10. Configuration Settings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.9. Security</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-monitoring.html" title="31.8. Monitoring">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-config.html" title="31.10. Configuration Settings">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-SECURITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.9. Security</h2></div></div></div><p>
+ A user able to modify the schema of subscriber-side tables can execute
+ arbitrary code as the role which owns any subscription which modifies those tables. Limit ownership
+ and <code class="literal">TRIGGER</code> privilege on such tables to trusted roles.
+ Moreover, if untrusted users can create tables, use only
+ publications that list tables explicitly. That is to say, create a
+ subscription <code class="literal">FOR ALL TABLES</code> or
+ <code class="literal">FOR TABLES IN SCHEMA</code> only when superusers trust
+ every user permitted to create a non-temp table on the publisher or the
+ subscriber.
+ </p><p>
+ The role used for the replication connection must have
+ the <code class="literal">REPLICATION</code> attribute (or be a superuser). If the
+ role lacks <code class="literal">SUPERUSER</code> and <code class="literal">BYPASSRLS</code>,
+ publisher row security policies can execute. If the role does not trust
+ all table owners, include <code class="literal">options=-crow_security=off</code> in
+ the connection string; if a table owner then adds a row security policy,
+ that setting will cause replication to halt rather than execute the policy.
+ Access for the role must be configured in <code class="filename">pg_hba.conf</code>
+ and it must have the <code class="literal">LOGIN</code> attribute.
+ </p><p>
+ In order to be able to copy the initial table data, the role used for the
+ replication connection must have the <code class="literal">SELECT</code> privilege on
+ a published table (or be a superuser).
+ </p><p>
+ To create a publication, the user must have the <code class="literal">CREATE</code>
+ privilege in the database.
+ </p><p>
+ To add tables to a publication, the user must have ownership rights on the
+ table. To add all tables in schema to a publication, the user must be a
+ superuser. To create a publication that publishes all tables or all tables in
+ schema automatically, the user must be a superuser.
+ </p><p>
+ To create a subscription, the user must be a superuser.
+ </p><p>
+ The subscription apply process will run in the local database with the
+ privileges of the subscription owner.
+ </p><p>
+ On the publisher, privileges are only checked once at the start of a
+ replication connection and are not re-checked as each change record is read.
+ </p><p>
+ On the subscriber, the subscription owner's privileges are re-checked for
+ each transaction when applied. If a worker is in the process of applying a
+ transaction when the ownership of the subscription is changed by a
+ concurrent transaction, the application of the current transaction will
+ continue under the old owner's privileges.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-monitoring.html" title="31.8. Monitoring">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-config.html" title="31.10. Configuration Settings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.8. Monitoring </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.10. Configuration Settings</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication-subscription.html b/doc/src/sgml/html/logical-replication-subscription.html
new file mode 100644
index 0000000..3b3e543
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication-subscription.html
@@ -0,0 +1,278 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>31.2. Subscription</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logical-replication-publication.html" title="31.1. Publication" /><link rel="next" href="logical-replication-row-filter.html" title="31.3. Row Filters" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.2. Subscription</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-publication.html" title="31.1. Publication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-row-filter.html" title="31.3. Row Filters">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICAL-REPLICATION-SUBSCRIPTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.2. Subscription</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-SLOT">31.2.1. Replication Slot Management</a></span></dt><dt><span class="sect2"><a href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-EXAMPLES">31.2.2. Examples</a></span></dt></dl></div><p>
+ A <em class="firstterm">subscription</em> is the downstream side of logical
+ replication. The node where a subscription is defined is referred to as
+ the <em class="firstterm">subscriber</em>. A subscription defines the connection
+ to another database and set of publications (one or more) to which it wants
+ to subscribe.
+ </p><p>
+ The subscriber database behaves in the same way as any other PostgreSQL
+ instance and can be used as a publisher for other databases by defining its
+ own publications.
+ </p><p>
+ A subscriber node may have multiple subscriptions if desired. It is
+ possible to define multiple subscriptions between a single
+ publisher-subscriber pair, in which case care must be taken to ensure
+ that the subscribed publication objects don't overlap.
+ </p><p>
+ Each subscription will receive changes via one replication slot (see
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>). Additional replication
+ slots may be required for the initial data synchronization of
+ pre-existing table data and those will be dropped at the end of data
+ synchronization.
+ </p><p>
+ A logical replication subscription can be a standby for synchronous
+ replication (see <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">Section 27.2.8</a>). The standby
+ name is by default the subscription name. An alternative name can be
+ specified as <code class="literal">application_name</code> in the connection
+ information of the subscription.
+ </p><p>
+ Subscriptions are dumped by <code class="command">pg_dump</code> if the current user
+ is a superuser. Otherwise a warning is written and subscriptions are
+ skipped, because non-superusers cannot read all subscription information
+ from the <code class="structname">pg_subscription</code> catalog.
+ </p><p>
+ The subscription is added using <a class="link" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><code class="command">CREATE SUBSCRIPTION</code></a> and
+ can be stopped/resumed at any time using the
+ <a class="link" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><code class="command">ALTER SUBSCRIPTION</code></a> command and removed using
+ <a class="link" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION"><code class="command">DROP SUBSCRIPTION</code></a>.
+ </p><p>
+ When a subscription is dropped and recreated, the synchronization
+ information is lost. This means that the data has to be resynchronized
+ afterwards.
+ </p><p>
+ The schema definitions are not replicated, and the published tables must
+ exist on the subscriber. Only regular tables may be
+ the target of replication. For example, you can't replicate to a view.
+ </p><p>
+ The tables are matched between the publisher and the subscriber using the
+ fully qualified table name. Replication to differently-named tables on the
+ subscriber is not supported.
+ </p><p>
+ Columns of a table are also matched by name. The order of columns in the
+ subscriber table does not need to match that of the publisher. The data
+ types of the columns do not need to match, as long as the text
+ representation of the data can be converted to the target type. For
+ example, you can replicate from a column of type <code class="type">integer</code> to a
+ column of type <code class="type">bigint</code>. The target table can also have
+ additional columns not provided by the published table. Any such columns
+ will be filled with the default value as specified in the definition of the
+ target table.
+ </p><div class="sect2" id="LOGICAL-REPLICATION-SUBSCRIPTION-SLOT"><div class="titlepage"><div><div><h3 class="title">31.2.1. Replication Slot Management</h3></div></div></div><p>
+ As mentioned earlier, each (active) subscription receives changes from a
+ replication slot on the remote (publishing) side.
+ </p><p>
+ Additional table synchronization slots are normally transient, created
+ internally to perform initial table synchronization and dropped
+ automatically when they are no longer needed. These table synchronization
+ slots have generated names: <span class="quote">“<span class="quote"><code class="literal">pg_%u_sync_%u_%llu</code></span>”</span>
+ (parameters: Subscription <em class="parameter"><code>oid</code></em>,
+ Table <em class="parameter"><code>relid</code></em>, system identifier <em class="parameter"><code>sysid</code></em>)
+ </p><p>
+ Normally, the remote replication slot is created automatically when the
+ subscription is created using <code class="command">CREATE SUBSCRIPTION</code> and it
+ is dropped automatically when the subscription is dropped using
+ <code class="command">DROP SUBSCRIPTION</code>. In some situations, however, it can
+ be useful or necessary to manipulate the subscription and the underlying
+ replication slot separately. Here are some scenarios:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ When creating a subscription, the replication slot already exists. In
+ that case, the subscription can be created using
+ the <code class="literal">create_slot = false</code> option to associate with the
+ existing slot.
+ </p></li><li class="listitem"><p>
+ When creating a subscription, the remote host is not reachable or in an
+ unclear state. In that case, the subscription can be created using
+ the <code class="literal">connect = false</code> option. The remote host will then not
+ be contacted at all. This is what <span class="application">pg_dump</span>
+ uses. The remote replication slot will then have to be created
+ manually before the subscription can be activated.
+ </p></li><li class="listitem"><p>
+ When dropping a subscription, the replication slot should be kept.
+ This could be useful when the subscriber database is being moved to a
+ different host and will be activated from there. In that case,
+ disassociate the slot from the subscription using <code class="command">ALTER
+ SUBSCRIPTION</code> before attempting to drop the subscription.
+ </p></li><li class="listitem"><p>
+ When dropping a subscription, the remote host is not reachable. In
+ that case, disassociate the slot from the subscription
+ using <code class="command">ALTER SUBSCRIPTION</code> before attempting to drop
+ the subscription. If the remote database instance no longer exists, no
+ further action is then necessary. If, however, the remote database
+ instance is just unreachable, the replication slot (and any still
+ remaining table synchronization slots) should then be
+ dropped manually; otherwise it/they would continue to reserve WAL and might
+ eventually cause the disk to fill up. Such cases should be carefully
+ investigated.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="LOGICAL-REPLICATION-SUBSCRIPTION-EXAMPLES"><div class="titlepage"><div><div><h3 class="title">31.2.2. Examples</h3></div></div></div><p>
+ Create some test tables on the publisher.
+</p><pre class="programlisting">
+test_pub=# CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
+CREATE TABLE
+test_pub=# CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
+CREATE TABLE
+test_pub=# CREATE TABLE t3(e int, f text, PRIMARY KEY(e));
+CREATE TABLE
+</pre><p>
+ Create the same tables on the subscriber.
+</p><pre class="programlisting">
+test_sub=# CREATE TABLE t1(a int, b text, PRIMARY KEY(a));
+CREATE TABLE
+test_sub=# CREATE TABLE t2(c int, d text, PRIMARY KEY(c));
+CREATE TABLE
+test_sub=# CREATE TABLE t3(e int, f text, PRIMARY KEY(e));
+CREATE TABLE
+</pre><p>
+ Insert data to the tables at the publisher side.
+</p><pre class="programlisting">
+test_pub=# INSERT INTO t1 VALUES (1, 'one'), (2, 'two'), (3, 'three');
+INSERT 0 3
+test_pub=# INSERT INTO t2 VALUES (1, 'A'), (2, 'B'), (3, 'C');
+INSERT 0 3
+test_pub=# INSERT INTO t3 VALUES (1, 'i'), (2, 'ii'), (3, 'iii');
+INSERT 0 3
+</pre><p>
+ Create publications for the tables. The publications <code class="literal">pub2</code>
+ and <code class="literal">pub3a</code> disallow some <code class="literal">publish</code>
+ operations. The publication <code class="literal">pub3b</code> has a row filter (see
+ <a class="xref" href="logical-replication-row-filter.html" title="31.3. Row Filters">Section 31.3</a>).
+</p><pre class="programlisting">
+test_pub=# CREATE PUBLICATION pub1 FOR TABLE t1;
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION pub2 FOR TABLE t2 WITH (publish = 'truncate');
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION pub3a FOR TABLE t3 WITH (publish = 'truncate');
+CREATE PUBLICATION
+test_pub=# CREATE PUBLICATION pub3b FOR TABLE t3 WHERE (e &gt; 5);
+CREATE PUBLICATION
+</pre><p>
+ Create subscriptions for the publications. The subscription
+ <code class="literal">sub3</code> subscribes to both <code class="literal">pub3a</code> and
+ <code class="literal">pub3b</code>. All subscriptions will copy initial data by default.
+</p><pre class="programlisting">
+test_sub=# CREATE SUBSCRIPTION sub1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=sub1'
+test_sub-# PUBLICATION pub1;
+CREATE SUBSCRIPTION
+test_sub=# CREATE SUBSCRIPTION sub2
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=sub2'
+test_sub-# PUBLICATION pub2;
+CREATE SUBSCRIPTION
+test_sub=# CREATE SUBSCRIPTION sub3
+test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=sub3'
+test_sub-# PUBLICATION pub3a, pub3b;
+CREATE SUBSCRIPTION
+</pre><p>
+ Observe that initial table data is copied, regardless of the
+ <code class="literal">publish</code> operation of the publication.
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b
+---+-------
+ 1 | one
+ 2 | two
+ 3 | three
+(3 rows)
+
+test_sub=# SELECT * FROM t2;
+ c | d
+---+---
+ 1 | A
+ 2 | B
+ 3 | C
+(3 rows)
+</pre><p>
+ Furthermore, because the initial data copy ignores the <code class="literal">publish</code>
+ operation, and because publication <code class="literal">pub3a</code> has no row filter,
+ it means the copied table <code class="literal">t3</code> contains all rows even when
+ they do not match the row filter of publication <code class="literal">pub3b</code>.
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t3;
+ e | f
+---+-----
+ 1 | i
+ 2 | ii
+ 3 | iii
+(3 rows)
+</pre><p>
+ Insert more data to the tables at the publisher side.
+</p><pre class="programlisting">
+test_pub=# INSERT INTO t1 VALUES (4, 'four'), (5, 'five'), (6, 'six');
+INSERT 0 3
+test_pub=# INSERT INTO t2 VALUES (4, 'D'), (5, 'E'), (6, 'F');
+INSERT 0 3
+test_pub=# INSERT INTO t3 VALUES (4, 'iv'), (5, 'v'), (6, 'vi');
+INSERT 0 3
+</pre><p>
+ Now the publisher side data looks like:
+</p><pre class="programlisting">
+test_pub=# SELECT * FROM t1;
+ a | b
+---+-------
+ 1 | one
+ 2 | two
+ 3 | three
+ 4 | four
+ 5 | five
+ 6 | six
+(6 rows)
+
+test_pub=# SELECT * FROM t2;
+ c | d
+---+---
+ 1 | A
+ 2 | B
+ 3 | C
+ 4 | D
+ 5 | E
+ 6 | F
+(6 rows)
+
+test_pub=# SELECT * FROM t3;
+ e | f
+---+-----
+ 1 | i
+ 2 | ii
+ 3 | iii
+ 4 | iv
+ 5 | v
+ 6 | vi
+(6 rows)
+</pre><p>
+ Observe that during normal replication the appropriate
+ <code class="literal">publish</code> operations are used. This means publications
+ <code class="literal">pub2</code> and <code class="literal">pub3a</code> will not replicate the
+ <code class="literal">INSERT</code>. Also, publication <code class="literal">pub3b</code> will
+ only replicate data that matches the row filter of <code class="literal">pub3b</code>.
+ Now the subscriber side data looks like:
+</p><pre class="programlisting">
+test_sub=# SELECT * FROM t1;
+ a | b
+---+-------
+ 1 | one
+ 2 | two
+ 3 | three
+ 4 | four
+ 5 | five
+ 6 | six
+(6 rows)
+
+test_sub=# SELECT * FROM t2;
+ c | d
+---+---
+ 1 | A
+ 2 | B
+ 3 | C
+(3 rows)
+
+test_sub=# SELECT * FROM t3;
+ e | f
+---+-----
+ 1 | i
+ 2 | ii
+ 3 | iii
+ 6 | vi
+(4 rows)
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-publication.html" title="31.1. Publication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-row-filter.html" title="31.3. Row Filters">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.1. Publication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.3. Row Filters</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logical-replication.html b/doc/src/sgml/html/logical-replication.html
new file mode 100644
index 0000000..f63e748
--- /dev/null
+++ b/doc/src/sgml/html/logical-replication.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 31. Logical Replication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-internals.html" title="30.6. WAL Internals" /><link rel="next" href="logical-replication-publication.html" title="31.1. Publication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 31. Logical Replication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-internals.html" title="30.6. WAL Internals">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-publication.html" title="31.1. Publication">Next</a></td></tr></table><hr /></div><div class="chapter" id="LOGICAL-REPLICATION"><div class="titlepage"><div><div><h2 class="title">Chapter 31. Logical Replication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="logical-replication-publication.html">31.1. Publication</a></span></dt><dt><span class="sect1"><a href="logical-replication-subscription.html">31.2. Subscription</a></span></dt><dd><dl><dt><span class="sect2"><a href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-SLOT">31.2.1. Replication Slot Management</a></span></dt><dt><span class="sect2"><a href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-EXAMPLES">31.2.2. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="logical-replication-row-filter.html">31.3. Row Filters</a></span></dt><dd><dl><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-RULES">31.3.1. Row Filter Rules</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-RESTRICTIONS">31.3.2. Expression Restrictions</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-TRANSFORMATIONS">31.3.3. UPDATE Transformations</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-PARTITIONED-TABLE">31.3.4. Partitioned Tables</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-INITIAL-DATA-SYNC">31.3.5. Initial Data Synchronization</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-COMBINING">31.3.6. Combining Multiple Row Filters</a></span></dt><dt><span class="sect2"><a href="logical-replication-row-filter.html#LOGICAL-REPLICATION-ROW-FILTER-EXAMPLES">31.3.7. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="logical-replication-col-lists.html">31.4. Column Lists</a></span></dt><dd><dl><dt><span class="sect2"><a href="logical-replication-col-lists.html#LOGICAL-REPLICATION-COL-LIST-EXAMPLES">31.4.1. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="logical-replication-conflicts.html">31.5. Conflicts</a></span></dt><dt><span class="sect1"><a href="logical-replication-restrictions.html">31.6. Restrictions</a></span></dt><dt><span class="sect1"><a href="logical-replication-architecture.html">31.7. Architecture</a></span></dt><dd><dl><dt><span class="sect2"><a href="logical-replication-architecture.html#LOGICAL-REPLICATION-SNAPSHOT">31.7.1. Initial Snapshot</a></span></dt></dl></dd><dt><span class="sect1"><a href="logical-replication-monitoring.html">31.8. Monitoring</a></span></dt><dt><span class="sect1"><a href="logical-replication-security.html">31.9. Security</a></span></dt><dt><span class="sect1"><a href="logical-replication-config.html">31.10. Configuration Settings</a></span></dt><dt><span class="sect1"><a href="logical-replication-quick-setup.html">31.11. Quick Setup</a></span></dt></dl></div><p>
+ Logical replication is a method of replicating data objects and their
+ changes, based upon their replication identity (usually a primary key). We
+ use the term logical in contrast to physical replication, which uses exact
+ block addresses and byte-by-byte replication. PostgreSQL supports both
+ mechanisms concurrently, see <a class="xref" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Chapter 27</a>. Logical
+ replication allows fine-grained control over both data replication and
+ security.
+ </p><p>
+ Logical replication uses a <em class="firstterm">publish</em>
+ and <em class="firstterm">subscribe</em> model with one or
+ more <em class="firstterm">subscribers</em> subscribing to one or more
+ <em class="firstterm">publications</em> on a <em class="firstterm">publisher</em>
+ node. Subscribers pull data from the publications they subscribe to and may
+ subsequently re-publish data to allow cascading replication or more complex
+ configurations.
+ </p><p>
+ Logical replication of a table typically starts with taking a snapshot
+ of the data on the publisher database and copying that to the subscriber.
+ Once that is done, the changes on the publisher are sent to the subscriber
+ as they occur in real-time. The subscriber applies the data in the same
+ order as the publisher so that transactional consistency is guaranteed for
+ publications within a single subscription. This method of data replication
+ is sometimes referred to as transactional replication.
+ </p><p>
+ The typical use-cases for logical replication are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Sending incremental changes in a single database or a subset of a
+ database to subscribers as they occur.
+ </p></li><li class="listitem"><p>
+ Firing triggers for individual changes as they arrive on the
+ subscriber.
+ </p></li><li class="listitem"><p>
+ Consolidating multiple databases into a single one (for example for
+ analytical purposes).
+ </p></li><li class="listitem"><p>
+ Replicating between different major versions of PostgreSQL.
+ </p></li><li class="listitem"><p>
+ Replicating between PostgreSQL instances on different platforms (for
+ example Linux to Windows)
+ </p></li><li class="listitem"><p>
+ Giving access to replicated data to different groups of users.
+ </p></li><li class="listitem"><p>
+ Sharing a subset of the database between multiple databases.
+ </p></li></ul></div><p>
+ </p><p>
+ The subscriber database behaves in the same way as any other PostgreSQL
+ instance and can be used as a publisher for other databases by defining its
+ own publications. When the subscriber is treated as read-only by
+ application, there will be no conflicts from a single subscription. On the
+ other hand, if there are other writes done either by an application or by other
+ subscribers to the same set of tables, conflicts can arise.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-internals.html" title="30.6. WAL Internals">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-publication.html" title="31.1. Publication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.6. WAL Internals </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 31.1. Publication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-catalogs.html b/doc/src/sgml/html/logicaldecoding-catalogs.html
new file mode 100644
index 0000000..663c563
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-catalogs.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.5. System Catalogs Related to Logical Decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface" /><link rel="next" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.5. System Catalogs Related to Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-CATALOGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.5. System Catalogs Related to Logical Decoding</h2></div></div></div><p>
+ The <a class="link" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots"><code class="structname">pg_replication_slots</code></a>
+ view and the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication">
+ <code class="structname">pg_stat_replication</code></a>
+ view provide information about the current state of replication slots and
+ streaming replication connections respectively. These views apply to both physical and
+ logical replication. The
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW" title="28.2.5. pg_stat_replication_slots">
+ <code class="structname">pg_stat_replication_slots</code></a>
+ view provides statistics information about the logical replication slots.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.6. Logical Decoding Output Plugins</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-example.html b/doc/src/sgml/html/logicaldecoding-example.html
new file mode 100644
index 0000000..393b6b8
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-example.html
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.1. Logical Decoding Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding.html" title="Chapter 49. Logical Decoding" /><link rel="next" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.1. Logical Decoding Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.1. Logical Decoding Examples</h2></div></div></div><p>
+ The following example demonstrates controlling logical decoding using the
+ SQL interface.
+ </p><p>
+ Before you can use logical decoding, you must set
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> to <code class="literal">logical</code> and
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS">max_replication_slots</a> to at least 1. Then, you
+ should connect to the target database (in the example
+ below, <code class="literal">postgres</code>) as a superuser.
+ </p><pre class="programlisting">
+postgres=# -- Create a slot named 'regression_slot' using the output plugin 'test_decoding'
+postgres=# SELECT * FROM pg_create_logical_replication_slot('regression_slot', 'test_decoding', false, true);
+ slot_name | lsn
+-----------------+-----------
+ regression_slot | 0/16B1970
+(1 row)
+
+postgres=# SELECT slot_name, plugin, slot_type, database, active, restart_lsn, confirmed_flush_lsn FROM pg_replication_slots;
+ slot_name | plugin | slot_type | database | active | restart_lsn | confirmed_flush_lsn
+-----------------+---------------+-----------+----------+--------+-------------+-----------------
+ regression_slot | test_decoding | logical | postgres | f | 0/16A4408 | 0/16A4440
+(1 row)
+
+postgres=# -- There are no changes to see yet
+postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----+-----+------
+(0 rows)
+
+postgres=# CREATE TABLE data(id serial primary key, data text);
+CREATE TABLE
+
+postgres=# -- DDL isn't replicated, so all you'll see is the transaction
+postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-------+--------------
+ 0/BA2DA58 | 10297 | BEGIN 10297
+ 0/BA5A5A0 | 10297 | COMMIT 10297
+(2 rows)
+
+postgres=# -- Once changes are read, they're consumed and not emitted
+postgres=# -- in a subsequent call:
+postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----+-----+------
+(0 rows)
+
+postgres=# BEGIN;
+postgres=*# INSERT INTO data(data) VALUES('1');
+postgres=*# INSERT INTO data(data) VALUES('2');
+postgres=*# COMMIT;
+
+postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-------+---------------------------------------------------------
+ 0/BA5A688 | 10298 | BEGIN 10298
+ 0/BA5A6F0 | 10298 | table public.data: INSERT: id[integer]:1 data[text]:'1'
+ 0/BA5A7F8 | 10298 | table public.data: INSERT: id[integer]:2 data[text]:'2'
+ 0/BA5A8A8 | 10298 | COMMIT 10298
+(4 rows)
+
+postgres=# INSERT INTO data(data) VALUES('3');
+
+postgres=# -- You can also peek ahead in the change stream without consuming changes
+postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-------+---------------------------------------------------------
+ 0/BA5A8E0 | 10299 | BEGIN 10299
+ 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/BA5A990 | 10299 | COMMIT 10299
+(3 rows)
+
+postgres=# -- The next call to pg_logical_slot_peek_changes() returns the same changes again
+postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-------+---------------------------------------------------------
+ 0/BA5A8E0 | 10299 | BEGIN 10299
+ 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/BA5A990 | 10299 | COMMIT 10299
+(3 rows)
+
+postgres=# -- options can be passed to output plugin, to influence the formatting
+postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'include-timestamp', 'on');
+ lsn | xid | data
+-----------+-------+---------------------------------------------------------
+ 0/BA5A8E0 | 10299 | BEGIN 10299
+ 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/BA5A990 | 10299 | COMMIT 10299 (at 2017-05-10 12:07:21.272494-04)
+(3 rows)
+
+postgres=# -- Remember to destroy a slot you no longer need to stop it consuming
+postgres=# -- server resources:
+postgres=# SELECT pg_drop_replication_slot('regression_slot');
+ pg_drop_replication_slot
+-----------------------
+
+(1 row)
+</pre><p>
+ The following examples shows how logical decoding is controlled over the
+ streaming replication protocol, using the
+ program <a class="xref" href="app-pgrecvlogical.html" title="pg_recvlogical"><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></a> included in the PostgreSQL
+ distribution. This requires that client authentication is set up to allow
+ replication connections
+ (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-AUTHENTICATION" title="27.2.5.1. Authentication">Section 27.2.5.1</a>) and
+ that <code class="varname">max_wal_senders</code> is set sufficiently high to allow
+ an additional connection. The second example shows how to stream two-phase
+ transactions. Before you use two-phase commands, you must set
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a> to at least 1.
+ </p><pre class="programlisting">
+Example 1:
+$ pg_recvlogical -d postgres --slot=test --create-slot
+$ pg_recvlogical -d postgres --slot=test --start -f -
+<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>Z</strong></span>
+$ psql -d postgres -c "INSERT INTO data(data) VALUES('4');"
+$ fg
+BEGIN 693
+table public.data: INSERT: id[integer]:4 data[text]:'4'
+COMMIT 693
+<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>
+$ pg_recvlogical -d postgres --slot=test --drop-slot
+
+Example 2:
+$ pg_recvlogical -d postgres --slot=test --create-slot --two-phase
+$ pg_recvlogical -d postgres --slot=test --start -f -
+<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>Z</strong></span>
+$ psql -d postgres -c "BEGIN;INSERT INTO data(data) VALUES('5');PREPARE TRANSACTION 'test';"
+$ fg
+BEGIN 694
+table public.data: INSERT: id[integer]:5 data[text]:'5'
+PREPARE TRANSACTION 'test', txid 694
+<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>Z</strong></span>
+$ psql -d postgres -c "COMMIT PREPARED 'test';"
+$ fg
+COMMIT PREPARED 'test', txid 694
+<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>
+$ pg_recvlogical -d postgres --slot=test --drop-slot
+</pre><p>
+ The following example shows SQL interface that can be used to decode prepared
+ transactions. Before you use two-phase commit commands, you must set
+ <code class="varname">max_prepared_transactions</code> to at least 1. You must also have
+ set the two-phase parameter as 'true' while creating the slot using
+ <code class="function">pg_create_logical_replication_slot</code>
+ Note that we will stream the entire transaction after the commit if it
+ is not already decoded.
+ </p><pre class="programlisting">
+postgres=# BEGIN;
+postgres=*# INSERT INTO data(data) VALUES('5');
+postgres=*# PREPARE TRANSACTION 'test_prepared1';
+
+postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-----+---------------------------------------------------------
+ 0/1689DC0 | 529 | BEGIN 529
+ 0/1689DC0 | 529 | table public.data: INSERT: id[integer]:3 data[text]:'5'
+ 0/1689FC0 | 529 | PREPARE TRANSACTION 'test_prepared1', txid 529
+(3 rows)
+
+postgres=# COMMIT PREPARED 'test_prepared1';
+postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-----+--------------------------------------------
+ 0/168A060 | 529 | COMMIT PREPARED 'test_prepared1', txid 529
+(4 row)
+
+postgres=#-- you can also rollback a prepared transaction
+postgres=# BEGIN;
+postgres=*# INSERT INTO data(data) VALUES('6');
+postgres=*# PREPARE TRANSACTION 'test_prepared2';
+postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-----+---------------------------------------------------------
+ 0/168A180 | 530 | BEGIN 530
+ 0/168A1E8 | 530 | table public.data: INSERT: id[integer]:4 data[text]:'6'
+ 0/168A430 | 530 | PREPARE TRANSACTION 'test_prepared2', txid 530
+(3 rows)
+
+postgres=# ROLLBACK PREPARED 'test_prepared2';
+postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NULL);
+ lsn | xid | data
+-----------+-----+----------------------------------------------
+ 0/168A4B8 | 530 | ROLLBACK PREPARED 'test_prepared2', txid 530
+(1 row)
+</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 49. Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.2. Logical Decoding Concepts</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-explanation.html b/doc/src/sgml/html/logicaldecoding-explanation.html
new file mode 100644
index 0000000..5de44dd
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-explanation.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.2. Logical Decoding Concepts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples" /><link rel="next" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.2. Logical Decoding Concepts</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-EXPLANATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.2. Logical Decoding Concepts</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.2">49.2.1. Logical Decoding</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS">49.2.2. Replication Slots</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.4">49.2.3. Output Plugins</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.5">49.2.4. Exported Snapshots</a></span></dt></dl></div><div class="sect2" id="id-1.8.14.8.2"><div class="titlepage"><div><div><h3 class="title">49.2.1. Logical Decoding</h3></div></div></div><a id="id-1.8.14.8.2.2" class="indexterm"></a><p>
+ Logical decoding is the process of extracting all persistent changes
+ to a database's tables into a coherent, easy to understand format which
+ can be interpreted without detailed knowledge of the database's internal
+ state.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, logical decoding is implemented
+ by decoding the contents of the <a class="link" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">write-ahead
+ log</a>, which describe changes on a storage level, into an
+ application-specific form such as a stream of tuples or SQL statements.
+ </p></div><div class="sect2" id="LOGICALDECODING-REPLICATION-SLOTS"><div class="titlepage"><div><div><h3 class="title">49.2.2. Replication Slots</h3></div></div></div><a id="id-1.8.14.8.3.2" class="indexterm"></a><p>
+ In the context of logical replication, a slot represents a stream of
+ changes that can be replayed to a client in the order they were made on
+ the origin server. Each slot streams a sequence of changes from a single
+ database.
+ </p><div class="note"><h3 class="title">Note</h3><p><span class="productname">PostgreSQL</span> also has streaming replication slots
+ (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>), but they are used somewhat
+ differently there.
+ </p></div><p>
+ A replication slot has an identifier that is unique across all databases
+ in a <span class="productname">PostgreSQL</span> cluster. Slots persist
+ independently of the connection using them and are crash-safe.
+ </p><p>
+ A logical slot will emit each change just once in normal operation.
+ The current position of each slot is persisted only at checkpoint, so in
+ the case of a crash the slot may return to an earlier LSN, which will
+ then cause recent changes to be sent again when the server restarts.
+ Logical decoding clients are responsible for avoiding ill effects from
+ handling the same message more than once. Clients may wish to record
+ the last LSN they saw when decoding and skip over any repeated data or
+ (when using the replication protocol) request that decoding start from
+ that LSN rather than letting the server determine the start point.
+ The Replication Progress Tracking feature is designed for this purpose,
+ refer to <a class="link" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">replication origins</a>.
+ </p><p>
+ Multiple independent slots may exist for a single database. Each slot has
+ its own state, allowing different consumers to receive changes from
+ different points in the database change stream. For most applications, a
+ separate slot will be required for each consumer.
+ </p><p>
+ A logical replication slot knows nothing about the state of the
+ receiver(s). It's even possible to have multiple different receivers using
+ the same slot at different times; they'll just get the changes following
+ on from when the last receiver stopped consuming them. Only one receiver
+ may consume changes from a slot at any given time.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Replication slots persist across crashes and know nothing about the state
+ of their consumer(s). They will prevent removal of required resources
+ even when there is no connection using them. This consumes storage
+ because neither required WAL nor required rows from the system catalogs
+ can be removed by <code class="command">VACUUM</code> as long as they are required by a replication
+ slot. In extreme cases this could cause the database to shut down to prevent
+ transaction ID wraparound (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>).
+ So if a slot is no longer required it should be dropped.
+ </p></div></div><div class="sect2" id="id-1.8.14.8.4"><div class="titlepage"><div><div><h3 class="title">49.2.3. Output Plugins</h3></div></div></div><p>
+ Output plugins transform the data from the write-ahead log's internal
+ representation into the format the consumer of a replication slot desires.
+ </p></div><div class="sect2" id="id-1.8.14.8.5"><div class="titlepage"><div><div><h3 class="title">49.2.4. Exported Snapshots</h3></div></div></div><p>
+ When a new replication slot is created using the streaming replication
+ interface (see <a class="xref" href="protocol-replication.html#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT">CREATE_REPLICATION_SLOT</a>), a
+ snapshot is exported
+ (see <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.27.5. Snapshot Synchronization Functions">Section 9.27.5</a>), which will show
+ exactly the state of the database after which all changes will be
+ included in the change stream. This can be used to create a new replica by
+ using <a class="link" href="sql-set-transaction.html" title="SET TRANSACTION"><code class="literal">SET TRANSACTION
+ SNAPSHOT</code></a> to read the state of the database at the moment
+ the slot was created. This transaction can then be used to dump the
+ database's state at that point in time, which afterwards can be updated
+ using the slot's contents without losing any changes.
+ </p><p>
+ Creation of a snapshot is not always possible. In particular, it will
+ fail when connected to a hot standby. Applications that do not require
+ snapshot export may suppress it with the <code class="literal">NOEXPORT_SNAPSHOT</code>
+ option.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.1. Logical Decoding Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.3. Streaming Replication Protocol Interface</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-output-plugin.html b/doc/src/sgml/html/logicaldecoding-output-plugin.html
new file mode 100644
index 0000000..c800931
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-output-plugin.html
@@ -0,0 +1,471 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.6. Logical Decoding Output Plugins</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding" /><link rel="next" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.6. Logical Decoding Output Plugins</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-OUTPUT-PLUGIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.6. Logical Decoding Output Plugins</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-INIT">49.6.1. Initialization Function</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES">49.6.2. Capabilities</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE">49.6.3. Output Modes</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS">49.6.4. Output Plugin Callbacks</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT">49.6.5. Functions for Producing Output</a></span></dt></dl></div><p>
+ An example output plugin can be found in the
+ <a class="link" href="test-decoding.html" title="F.45. test_decoding">
+ <code class="filename">contrib/test_decoding</code>
+ </a>
+ subdirectory of the PostgreSQL source tree.
+ </p><div class="sect2" id="LOGICALDECODING-OUTPUT-INIT"><div class="titlepage"><div><div><h3 class="title">49.6.1. Initialization Function</h3></div></div></div><a id="id-1.8.14.12.3.2" class="indexterm"></a><p>
+ An output plugin is loaded by dynamically loading a shared library with
+ the output plugin's name as the library base name. The normal library
+ search path is used to locate the library. To provide the required output
+ plugin callbacks and to indicate that the library is actually an output
+ plugin it needs to provide a function named
+ <code class="function">_PG_output_plugin_init</code>. This function is passed a
+ struct that needs to be filled with the callback function pointers for
+ individual actions.
+</p><pre class="programlisting">
+typedef struct OutputPluginCallbacks
+{
+ LogicalDecodeStartupCB startup_cb;
+ LogicalDecodeBeginCB begin_cb;
+ LogicalDecodeChangeCB change_cb;
+ LogicalDecodeTruncateCB truncate_cb;
+ LogicalDecodeCommitCB commit_cb;
+ LogicalDecodeMessageCB message_cb;
+ LogicalDecodeFilterByOriginCB filter_by_origin_cb;
+ LogicalDecodeShutdownCB shutdown_cb;
+ LogicalDecodeFilterPrepareCB filter_prepare_cb;
+ LogicalDecodeBeginPrepareCB begin_prepare_cb;
+ LogicalDecodePrepareCB prepare_cb;
+ LogicalDecodeCommitPreparedCB commit_prepared_cb;
+ LogicalDecodeRollbackPreparedCB rollback_prepared_cb;
+ LogicalDecodeStreamStartCB stream_start_cb;
+ LogicalDecodeStreamStopCB stream_stop_cb;
+ LogicalDecodeStreamAbortCB stream_abort_cb;
+ LogicalDecodeStreamPrepareCB stream_prepare_cb;
+ LogicalDecodeStreamCommitCB stream_commit_cb;
+ LogicalDecodeStreamChangeCB stream_change_cb;
+ LogicalDecodeStreamMessageCB stream_message_cb;
+ LogicalDecodeStreamTruncateCB stream_truncate_cb;
+} OutputPluginCallbacks;
+
+typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
+</pre><p>
+ The <code class="function">begin_cb</code>, <code class="function">change_cb</code>
+ and <code class="function">commit_cb</code> callbacks are required,
+ while <code class="function">startup_cb</code>,
+ <code class="function">filter_by_origin_cb</code>, <code class="function">truncate_cb</code>,
+ and <code class="function">shutdown_cb</code> are optional.
+ If <code class="function">truncate_cb</code> is not set but a
+ <code class="command">TRUNCATE</code> is to be decoded, the action will be ignored.
+ </p><p>
+ An output plugin may also define functions to support streaming of large,
+ in-progress transactions. The <code class="function">stream_start_cb</code>,
+ <code class="function">stream_stop_cb</code>, <code class="function">stream_abort_cb</code>,
+ <code class="function">stream_commit_cb</code>, <code class="function">stream_change_cb</code>,
+ and <code class="function">stream_prepare_cb</code>
+ are required, while <code class="function">stream_message_cb</code> and
+ <code class="function">stream_truncate_cb</code> are optional.
+ </p><p>
+ An output plugin may also define functions to support two-phase commits,
+ which allows actions to be decoded on the <code class="command">PREPARE TRANSACTION</code>.
+ The <code class="function">begin_prepare_cb</code>, <code class="function">prepare_cb</code>,
+ <code class="function">stream_prepare_cb</code>,
+ <code class="function">commit_prepared_cb</code> and <code class="function">rollback_prepared_cb</code>
+ callbacks are required, while <code class="function">filter_prepare_cb</code> is optional.
+ </p></div><div class="sect2" id="LOGICALDECODING-CAPABILITIES"><div class="titlepage"><div><div><h3 class="title">49.6.2. Capabilities</h3></div></div></div><p>
+ To decode, format and output changes, output plugins can use most of the
+ backend's normal infrastructure, including calling output functions. Read
+ only access to relations is permitted as long as only relations are
+ accessed that either have been created by <code class="command">initdb</code> in
+ the <code class="literal">pg_catalog</code> schema, or have been marked as user
+ provided catalog tables using
+</p><pre class="programlisting">
+ALTER TABLE user_catalog_table SET (user_catalog_table = true);
+CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true);
+</pre><p>
+ Note that access to user catalog tables or regular system catalog tables
+ in the output plugins has to be done via the <code class="literal">systable_*</code>
+ scan APIs only. Access via the <code class="literal">heap_*</code> scan APIs will
+ error out. Additionally, any actions leading to transaction ID assignment
+ are prohibited. That, among others, includes writing to tables, performing
+ DDL changes, and calling <code class="literal">pg_current_xact_id()</code>.
+ </p></div><div class="sect2" id="LOGICALDECODING-OUTPUT-MODE"><div class="titlepage"><div><div><h3 class="title">49.6.3. Output Modes</h3></div></div></div><p>
+ Output plugin callbacks can pass data to the consumer in nearly arbitrary
+ formats. For some use cases, like viewing the changes via SQL, returning
+ data in a data type that can contain arbitrary data (e.g., <code class="type">bytea</code>) is
+ cumbersome. If the output plugin only outputs textual data in the
+ server's encoding, it can declare that by
+ setting <code class="literal">OutputPluginOptions.output_type</code>
+ to <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code> instead
+ of <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code> in
+ the <a class="link" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-STARTUP" title="49.6.4.1. Startup Callback">startup
+ callback</a>. In that case, all the data has to be in the server's encoding
+ so that a <code class="type">text</code> datum can contain it. This is checked in assertion-enabled
+ builds.
+ </p></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">49.6.4. Output Plugin Callbacks</h3></div></div></div><p>
+ An output plugin gets notified about changes that are happening via
+ various callbacks it needs to provide.
+ </p><p>
+ Concurrent transactions are decoded in commit order, and only changes
+ belonging to a specific transaction are decoded between
+ the <code class="literal">begin</code> and <code class="literal">commit</code>
+ callbacks. Transactions that were rolled back explicitly or implicitly
+ never get
+ decoded. Successful savepoints are
+ folded into the transaction containing them in the order they were
+ executed within that transaction. A transaction that is prepared for
+ a two-phase commit using <code class="command">PREPARE TRANSACTION</code> will
+ also be decoded if the output plugin callbacks needed for decoding
+ them are provided. It is possible that the current prepared transaction
+ which is being decoded is aborted concurrently via a
+ <code class="command">ROLLBACK PREPARED</code> command. In that case, the logical
+ decoding of this transaction will be aborted too. All the changes of such
+ a transaction are skipped once the abort is detected and the
+ <code class="function">prepare_cb</code> callback is invoked. Thus even in case of
+ a concurrent abort, enough information is provided to the output plugin
+ for it to properly deal with <code class="command">ROLLBACK PREPARED</code> once
+ that is decoded.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Only transactions that have already safely been flushed to disk will be
+ decoded. That can lead to a <code class="command">COMMIT</code> not immediately being decoded in a
+ directly following <code class="literal">pg_logical_slot_get_changes()</code>
+ when <code class="varname">synchronous_commit</code> is set
+ to <code class="literal">off</code>.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STARTUP"><div class="titlepage"><div><div><h4 class="title">49.6.4.1. Startup Callback</h4></div></div></div><p>
+ The optional <code class="function">startup_cb</code> callback is called whenever
+ a replication slot is created or asked to stream changes, independent
+ of the number of changes that are ready to be put out.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStartupCB) (struct LogicalDecodingContext *ctx,
+ OutputPluginOptions *options,
+ bool is_init);
+</pre><p>
+ The <code class="literal">is_init</code> parameter will be true when the
+ replication slot is being created and false
+ otherwise. <em class="parameter"><code>options</code></em> points to a struct of options
+ that output plugins can set:
+</p><pre class="programlisting">
+typedef struct OutputPluginOptions
+{
+ OutputPluginOutputType output_type;
+ bool receive_rewrites;
+} OutputPluginOptions;
+</pre><p>
+ <code class="literal">output_type</code> has to either be set to
+ <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code>
+ or <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code>. See also
+ <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE" title="49.6.3. Output Modes">Section 49.6.3</a>.
+ If <code class="literal">receive_rewrites</code> is true, the output plugin will
+ also be called for changes made by heap rewrites during certain DDL
+ operations. These are of interest to plugins that handle DDL
+ replication, but they require special handling.
+ </p><p>
+ The startup callback should validate the options present in
+ <code class="literal">ctx-&gt;output_plugin_options</code>. If the output plugin
+ needs to have a state, it can
+ use <code class="literal">ctx-&gt;output_plugin_private</code> to store it.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-SHUTDOWN"><div class="titlepage"><div><div><h4 class="title">49.6.4.2. Shutdown Callback</h4></div></div></div><p>
+ The optional <code class="function">shutdown_cb</code> callback is called
+ whenever a formerly active replication slot is not used anymore and can
+ be used to deallocate resources private to the output plugin. The slot
+ isn't necessarily being dropped, streaming is just being stopped.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeShutdownCB) (struct LogicalDecodingContext *ctx);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-BEGIN"><div class="titlepage"><div><div><h4 class="title">49.6.4.3. Transaction Begin Callback</h4></div></div></div><p>
+ The required <code class="function">begin_cb</code> callback is called whenever a
+ start of a committed transaction has been decoded. Aborted transactions
+ and their contents never get decoded.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeBeginCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn);
+</pre><p>
+ The <em class="parameter"><code>txn</code></em> parameter contains meta information about
+ the transaction, like the time stamp at which it has been committed and
+ its XID.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT"><div class="titlepage"><div><div><h4 class="title">49.6.4.4. Transaction End Callback</h4></div></div></div><p>
+ The required <code class="function">commit_cb</code> callback is called whenever
+ a transaction commit has been
+ decoded. The <code class="function">change_cb</code> callbacks for all modified
+ rows will have been called before this, if there have been any modified
+ rows.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeCommitCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr commit_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-CHANGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.5. Change Callback</h4></div></div></div><p>
+ The required <code class="function">change_cb</code> callback is called for every
+ individual row modification inside a transaction, may it be
+ an <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ or <code class="command">DELETE</code>. Even if the original command modified
+ several rows at once the callback will be called individually for each
+ row. The <code class="function">change_cb</code> callback may access system or
+ user catalog tables to aid in the process of outputting the row
+ modification details. In case of decoding a prepared (but yet
+ uncommitted) transaction or decoding of an uncommitted transaction, this
+ change callback might also error out due to simultaneous rollback of
+ this very same transaction. In that case, the logical decoding of this
+ aborted transaction is stopped gracefully.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ Relation relation,
+ ReorderBufferChange *change);
+</pre><p>
+ The <em class="parameter"><code>ctx</code></em> and <em class="parameter"><code>txn</code></em> parameters
+ have the same contents as for the <code class="function">begin_cb</code>
+ and <code class="function">commit_cb</code> callbacks, but additionally the
+ relation descriptor <em class="parameter"><code>relation</code></em> points to the
+ relation the row belongs to and a struct
+ <em class="parameter"><code>change</code></em> describing the row modification are passed
+ in.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Only changes in user defined tables that are not unlogged
+ (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-UNLOGGED"><code class="literal">UNLOGGED</code></a>) and not temporary
+ (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-TEMPORARY"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></a>) can be extracted using
+ logical decoding.
+ </p></div></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">49.6.4.6. Truncate Callback</h4></div></div></div><p>
+ The <code class="function">truncate_cb</code> callback is called for a
+ <code class="command">TRUNCATE</code> command.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ int nrelations,
+ Relation relations[],
+ ReorderBufferChange *change);
+</pre><p>
+ The parameters are analogous to the <code class="function">change_cb</code>
+ callback. However, because <code class="command">TRUNCATE</code> actions on
+ tables connected by foreign keys need to be executed together, this
+ callback receives an array of relations instead of just a single one.
+ See the description of the <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> statement for
+ details.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN"><div class="titlepage"><div><div><h4 class="title">49.6.4.7. Origin Filter Callback</h4></div></div></div><p>
+ The optional <code class="function">filter_by_origin_cb</code> callback
+ is called to determine whether data that has been replayed
+ from <em class="parameter"><code>origin_id</code></em> is of interest to the
+ output plugin.
+</p><pre class="programlisting">
+typedef bool (*LogicalDecodeFilterByOriginCB) (struct LogicalDecodingContext *ctx,
+ RepOriginId origin_id);
+</pre><p>
+ The <em class="parameter"><code>ctx</code></em> parameter has the same contents
+ as for the other callbacks. No information but the origin is
+ available. To signal that changes originating on the passed in
+ node are irrelevant, return true, causing them to be filtered
+ away; false otherwise. The other callbacks will not be called
+ for transactions and changes that have been filtered away.
+ </p><p>
+ This is useful when implementing cascading or multidirectional
+ replication solutions. Filtering by the origin allows to
+ prevent replicating the same changes back and forth in such
+ setups. While transactions and changes also carry information
+ about the origin, filtering via this callback is noticeably
+ more efficient.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-MESSAGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.8. Generic Message Callback</h4></div></div></div><p>
+ The optional <code class="function">message_cb</code> callback is called whenever
+ a logical decoding message has been decoded.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeMessageCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr message_lsn,
+ bool transactional,
+ const char *prefix,
+ Size message_size,
+ const char *message);
+</pre><p>
+ The <em class="parameter"><code>txn</code></em> parameter contains meta information about
+ the transaction, like the time stamp at which it has been committed and
+ its XID. Note however that it can be NULL when the message is
+ non-transactional and the XID was not assigned yet in the transaction
+ which logged the message. The <em class="parameter"><code>lsn</code></em> has WAL
+ location of the message. The <em class="parameter"><code>transactional</code></em> says
+ if the message was sent as transactional or not. Similar to the change
+ callback, in case of decoding a prepared (but yet uncommitted)
+ transaction or decoding of an uncommitted transaction, this message
+ callback might also error out due to simultaneous rollback of
+ this very same transaction. In that case, the logical decoding of this
+ aborted transaction is stopped gracefully.
+
+ The <em class="parameter"><code>prefix</code></em> is arbitrary null-terminated prefix
+ which can be used for identifying interesting messages for the current
+ plugin. And finally the <em class="parameter"><code>message</code></em> parameter holds
+ the actual message of <em class="parameter"><code>message_size</code></em> size.
+ </p><p>
+ Extra care should be taken to ensure that the prefix the output plugin
+ considers interesting is unique. Using name of the extension or the
+ output plugin itself is often a good choice.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.9. Prepare Filter Callback</h4></div></div></div><p>
+ The optional <code class="function">filter_prepare_cb</code> callback
+ is called to determine whether data that is part of the current
+ two-phase commit transaction should be considered for decoding
+ at this prepare stage or later as a regular one-phase transaction at
+ <code class="command">COMMIT PREPARED</code> time. To signal that
+ decoding should be skipped, return <code class="literal">true</code>;
+ <code class="literal">false</code> otherwise. When the callback is not
+ defined, <code class="literal">false</code> is assumed (i.e. no filtering, all
+ transactions using two-phase commit are decoded in two phases as well).
+</p><pre class="programlisting">
+typedef bool (*LogicalDecodeFilterPrepareCB) (struct LogicalDecodingContext *ctx,
+ TransactionId xid,
+ const char *gid);
+</pre><p>
+ The <em class="parameter"><code>ctx</code></em> parameter has the same contents as for
+ the other callbacks. The parameters <em class="parameter"><code>xid</code></em>
+ and <em class="parameter"><code>gid</code></em> provide two different ways to identify
+ the transaction. The later <code class="command">COMMIT PREPARED</code> or
+ <code class="command">ROLLBACK PREPARED</code> carries both identifiers,
+ providing an output plugin the choice of what to use.
+ </p><p>
+ The callback may be invoked multiple times per transaction to decode
+ and must provide the same static answer for a given pair of
+ <em class="parameter"><code>xid</code></em> and <em class="parameter"><code>gid</code></em> every time
+ it is called.
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-BEGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.10. Transaction Begin Prepare Callback</h4></div></div></div><p>
+ The required <code class="function">begin_prepare_cb</code> callback is called
+ whenever the start of a prepared transaction has been decoded. The
+ <em class="parameter"><code>gid</code></em> field, which is part of the
+ <em class="parameter"><code>txn</code></em> parameter, can be used in this callback to
+ check if the plugin has already received this <code class="command">PREPARE</code>
+ in which case it can either error out or skip the remaining changes of
+ the transaction.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeBeginPrepareCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.11. Transaction Prepare Callback</h4></div></div></div><p>
+ The required <code class="function">prepare_cb</code> callback is called whenever
+ a transaction which is prepared for two-phase commit has been
+ decoded. The <code class="function">change_cb</code> callback for all modified
+ rows will have been called before this, if there have been any modified
+ rows. The <em class="parameter"><code>gid</code></em> field, which is part of the
+ <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodePrepareCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr prepare_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT-PREPARED"><div class="titlepage"><div><div><h4 class="title">49.6.4.12. Transaction Commit Prepared Callback</h4></div></div></div><p>
+ The required <code class="function">commit_prepared_cb</code> callback is called
+ whenever a transaction <code class="command">COMMIT PREPARED</code> has been decoded.
+ The <em class="parameter"><code>gid</code></em> field, which is part of the
+ <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeCommitPreparedCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr commit_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-ROLLBACK-PREPARED"><div class="titlepage"><div><div><h4 class="title">49.6.4.13. Transaction Rollback Prepared Callback</h4></div></div></div><p>
+ The required <code class="function">rollback_prepared_cb</code> callback is called
+ whenever a transaction <code class="command">ROLLBACK PREPARED</code> has been
+ decoded. The <em class="parameter"><code>gid</code></em> field, which is part of the
+ <em class="parameter"><code>txn</code></em> parameter, can be used in this callback. The
+ parameters <em class="parameter"><code>prepare_end_lsn</code></em> and
+ <em class="parameter"><code>prepare_time</code></em> can be used to check if the plugin
+ has received this <code class="command">PREPARE TRANSACTION</code> in which case
+ it can apply the rollback, otherwise, it can skip the rollback operation. The
+ <em class="parameter"><code>gid</code></em> alone is not sufficient because the downstream
+ node can have a prepared transaction with same identifier.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr prepare_end_lsn,
+ TimestampTz prepare_time);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-START"><div class="titlepage"><div><div><h4 class="title">49.6.4.14. Stream Start Callback</h4></div></div></div><p>
+ The <code class="function">stream_start_cb</code> callback is called when opening
+ a block of streamed changes from an in-progress transaction.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-STOP"><div class="titlepage"><div><div><h4 class="title">49.6.4.15. Stream Stop Callback</h4></div></div></div><p>
+ The <code class="function">stream_stop_cb</code> callback is called when closing
+ a block of streamed changes from an in-progress transaction.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-ABORT"><div class="titlepage"><div><div><h4 class="title">49.6.4.16. Stream Abort Callback</h4></div></div></div><p>
+ The <code class="function">stream_abort_cb</code> callback is called to abort
+ a previously streamed transaction.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr abort_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.17. Stream Prepare Callback</h4></div></div></div><p>
+ The <code class="function">stream_prepare_cb</code> callback is called to prepare
+ a previously streamed transaction as part of a two-phase commit.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr prepare_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-COMMIT"><div class="titlepage"><div><div><h4 class="title">49.6.4.18. Stream Commit Callback</h4></div></div></div><p>
+ The <code class="function">stream_commit_cb</code> callback is called to commit
+ a previously streamed transaction.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr commit_lsn);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-CHANGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.19. Stream Change Callback</h4></div></div></div><p>
+ The <code class="function">stream_change_cb</code> callback is called when sending
+ a change in a block of streamed changes (demarcated by
+ <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).
+ The actual changes are not displayed as the transaction can abort at a later
+ point in time and we don't decode changes for aborted transactions.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ Relation relation,
+ ReorderBufferChange *change);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-MESSAGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.20. Stream Message Callback</h4></div></div></div><p>
+ The <code class="function">stream_message_cb</code> callback is called when sending
+ a generic message in a block of streamed changes (demarcated by
+ <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).
+ The message contents for transactional messages are not displayed as the transaction
+ can abort at a later point in time and we don't decode changes for aborted
+ transactions.
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamMessageCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ XLogRecPtr message_lsn,
+ bool transactional,
+ const char *prefix,
+ Size message_size,
+ const char *message);
+</pre><p>
+ </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">49.6.4.21. Stream Truncate Callback</h4></div></div></div><p>
+ The <code class="function">stream_truncate_cb</code> callback is called for a
+ <code class="command">TRUNCATE</code> command in a block of streamed changes
+ (demarcated by <code class="function">stream_start_cb</code> and
+ <code class="function">stream_stop_cb</code> calls).
+</p><pre class="programlisting">
+typedef void (*LogicalDecodeStreamTruncateCB) (struct LogicalDecodingContext *ctx,
+ ReorderBufferTXN *txn,
+ int nrelations,
+ Relation relations[],
+ ReorderBufferChange *change);
+</pre><p>
+ The parameters are analogous to the <code class="function">stream_change_cb</code>
+ callback. However, because <code class="command">TRUNCATE</code> actions on
+ tables connected by foreign keys need to be executed together, this
+ callback receives an array of relations instead of just a single one.
+ See the description of the <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> statement for
+ details.
+ </p></div></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT"><div class="titlepage"><div><div><h3 class="title">49.6.5. Functions for Producing Output</h3></div></div></div><p>
+ To actually produce output, output plugins can write data to
+ the <code class="literal">StringInfo</code> output buffer
+ in <code class="literal">ctx-&gt;out</code> when inside
+ the <code class="function">begin_cb</code>, <code class="function">commit_cb</code>,
+ or <code class="function">change_cb</code> callbacks. Before writing to the output
+ buffer, <code class="function">OutputPluginPrepareWrite(ctx, last_write)</code> has
+ to be called, and after finishing writing to the
+ buffer, <code class="function">OutputPluginWrite(ctx, last_write)</code> has to be
+ called to perform the write. The <em class="parameter"><code>last_write</code></em>
+ indicates whether a particular write was the callback's last write.
+ </p><p>
+ The following example shows how to output data to the consumer of an
+ output plugin:
+</p><pre class="programlisting">
+OutputPluginPrepareWrite(ctx, true);
+appendStringInfo(ctx-&gt;out, "BEGIN %u", txn-&gt;xid);
+OutputPluginWrite(ctx, true);
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.5. System Catalogs Related to Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.7. Logical Decoding Output Writers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-sql.html b/doc/src/sgml/html/logicaldecoding-sql.html
new file mode 100644
index 0000000..5f38059
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-sql.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.4. Logical Decoding SQL Interface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface" /><link rel="next" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-SQL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface</h2></div></div></div><p>
+ See <a class="xref" href="functions-admin.html#FUNCTIONS-REPLICATION" title="9.27.6. Replication Management Functions">Section 9.27.6</a> for detailed documentation on
+ the SQL-level API for interacting with logical decoding.
+ </p><p>
+ Synchronous replication (see <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">Section 27.2.8</a>) is
+ only supported on replication slots used over the streaming replication interface. The
+ function interface and additional, non-core interfaces do not support
+ synchronous replication.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.3. Streaming Replication Protocol Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.5. System Catalogs Related to Logical Decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-streaming.html b/doc/src/sgml/html/logicaldecoding-streaming.html
new file mode 100644
index 0000000..c1ca812
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-streaming.html
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.9. Streaming of Large Transactions for Logical Decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding" /><link rel="next" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.9. Streaming of Large Transactions for Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-STREAMING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.9. Streaming of Large Transactions for Logical Decoding</h2></div></div></div><p>
+ The basic output plugin callbacks (e.g., <code class="function">begin_cb</code>,
+ <code class="function">change_cb</code>, <code class="function">commit_cb</code> and
+ <code class="function">message_cb</code>) are only invoked when the transaction
+ actually commits. The changes are still decoded from the transaction
+ log, but are only passed to the output plugin at commit (and discarded
+ if the transaction aborts).
+ </p><p>
+ This means that while the decoding happens incrementally, and may spill
+ to disk to keep memory usage under control, all the decoded changes have
+ to be transmitted when the transaction finally commits (or more precisely,
+ when the commit is decoded from the transaction log). Depending on the
+ size of the transaction and network bandwidth, the transfer time may
+ significantly increase the apply lag.
+ </p><p>
+ To reduce the apply lag caused by large transactions, an output plugin
+ may provide additional callback to support incremental streaming of
+ in-progress transactions. There are multiple required streaming callbacks
+ (<code class="function">stream_start_cb</code>, <code class="function">stream_stop_cb</code>,
+ <code class="function">stream_abort_cb</code>, <code class="function">stream_commit_cb</code>
+ and <code class="function">stream_change_cb</code>) and two optional callbacks
+ (<code class="function">stream_message_cb</code> and <code class="function">stream_truncate_cb</code>).
+ Also, if streaming of two-phase commands is to be supported, then additional
+ callbacks must be provided. (See <a class="xref" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Section 49.10</a>
+ for details).
+ </p><p>
+ When streaming an in-progress transaction, the changes (and messages) are
+ streamed in blocks demarcated by <code class="function">stream_start_cb</code>
+ and <code class="function">stream_stop_cb</code> callbacks. Once all the decoded
+ changes are transmitted, the transaction can be committed using the
+ <code class="function">stream_commit_cb</code> callback
+ (or possibly aborted using the <code class="function">stream_abort_cb</code> callback).
+ If two-phase commits are supported, the transaction can be prepared using the
+ <code class="function">stream_prepare_cb</code> callback,
+ <code class="command">COMMIT PREPARED</code> using the
+ <code class="function">commit_prepared_cb</code> callback or aborted using the
+ <code class="function">rollback_prepared_cb</code>.
+ </p><p>
+ One example sequence of streaming callback calls for one transaction may
+ look like this:
+</p><pre class="programlisting">
+stream_start_cb(...); &lt;-- start of first block of changes
+ stream_change_cb(...);
+ stream_change_cb(...);
+ stream_message_cb(...);
+ stream_change_cb(...);
+ ...
+ stream_change_cb(...);
+stream_stop_cb(...); &lt;-- end of first block of changes
+
+stream_start_cb(...); &lt;-- start of second block of changes
+ stream_change_cb(...);
+ stream_change_cb(...);
+ stream_change_cb(...);
+ ...
+ stream_message_cb(...);
+ stream_change_cb(...);
+stream_stop_cb(...); &lt;-- end of second block of changes
+
+
+[a. when using normal commit]
+stream_commit_cb(...); &lt;-- commit of the streamed transaction
+
+[b. when using two-phase commit]
+stream_prepare_cb(...); &lt;-- prepare the streamed transaction
+commit_prepared_cb(...); &lt;-- commit of the prepared transaction
+</pre><p>
+ </p><p>
+ The actual sequence of callback calls may be more complicated, of course.
+ There may be blocks for multiple streamed transactions, some of the
+ transactions may get aborted, etc.
+ </p><p>
+ Similar to spill-to-disk behavior, streaming is triggered when the total
+ amount of changes decoded from the WAL (for all in-progress transactions)
+ exceeds the limit defined by <code class="varname">logical_decoding_work_mem</code> setting.
+ At that point, the largest top-level transaction (measured by the amount of memory
+ currently used for decoded changes) is selected and streamed. However, in
+ some cases we still have to spill to disk even if streaming is enabled
+ because we exceed the memory threshold but still have not decoded the
+ complete tuple e.g., only decoded toast table insert but not the main table
+ insert.
+ </p><p>
+ Even when streaming large transactions, the changes are still applied in
+ commit order, preserving the same guarantees as the non-streaming mode.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.8. Synchronous Replication Support for Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.10. Two-phase Commit Support for Logical Decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-synchronous.html b/doc/src/sgml/html/logicaldecoding-synchronous.html
new file mode 100644
index 0000000..6bfef14
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-synchronous.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.8. Synchronous Replication Support for Logical Decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers" /><link rel="next" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.8. Synchronous Replication Support for Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-SYNCHRONOUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.8. Synchronous Replication Support for Logical Decoding</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logicaldecoding-synchronous.html#id-1.8.14.14.2">49.8.1. Overview</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-synchronous.html#LOGICALDECODING-SYNCHRONOUS-CAVEATS">49.8.2. Caveats</a></span></dt></dl></div><div class="sect2" id="id-1.8.14.14.2"><div class="titlepage"><div><div><h3 class="title">49.8.1. Overview</h3></div></div></div><p>
+ Logical decoding can be used to build
+ <a class="link" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">synchronous
+ replication</a> solutions with the same user interface as synchronous
+ replication for <a class="link" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">streaming
+ replication</a>. To do this, the streaming replication interface
+ (see <a class="xref" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Section 49.3</a>) must be used to stream out
+ data. Clients have to send <code class="literal">Standby status update (F)</code>
+ (see <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>) messages, just like streaming
+ replication clients do.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A synchronous replica receiving changes via logical decoding will work in
+ the scope of a single database. Since, in contrast to
+ that, <em class="parameter"><code>synchronous_standby_names</code></em> currently is
+ server wide, this means this technique will not work properly if more
+ than one database is actively used.
+ </p></div></div><div class="sect2" id="LOGICALDECODING-SYNCHRONOUS-CAVEATS"><div class="titlepage"><div><div><h3 class="title">49.8.2. Caveats</h3></div></div></div><p>
+ In synchronous replication setup, a deadlock can happen, if the transaction
+ has locked [user] catalog tables exclusively. See
+ <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES" title="49.6.2. Capabilities">Section 49.6.2</a> for information on user
+ catalog tables. This is because logical decoding of transactions can lock
+ catalog tables to access them. To avoid this users must refrain from taking
+ an exclusive lock on [user] catalog tables. This can happen in the following
+ ways:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Issuing an explicit <code class="command">LOCK</code> on <code class="structname">pg_class</code>
+ in a transaction.
+ </p></li><li class="listitem"><p>
+ Perform <code class="command">CLUSTER</code> on <code class="structname">pg_class</code> in
+ a transaction.
+ </p></li><li class="listitem"><p>
+ <code class="command">PREPARE TRANSACTION</code> after <code class="command">LOCK</code> command
+ on <code class="structname">pg_class</code> and allow logical decoding of two-phase
+ transactions.
+ </p></li><li class="listitem"><p>
+ <code class="command">PREPARE TRANSACTION</code> after <code class="command">CLUSTER</code>
+ command on <code class="structname">pg_trigger</code> and allow logical decoding of
+ two-phase transactions. This will lead to deadlock only when published table
+ have a trigger.
+ </p></li><li class="listitem"><p>
+ Executing <code class="command">TRUNCATE</code> on [user] catalog table in a
+ transaction.
+ </p></li></ul></div><p>
+
+ Note that these commands that can cause deadlock apply to not only explicitly
+ indicated system catalog tables above but also to any other [user] catalog
+ table.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.7. Logical Decoding Output Writers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.9. Streaming of Large Transactions for Logical Decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-two-phase-commits.html b/doc/src/sgml/html/logicaldecoding-two-phase-commits.html
new file mode 100644
index 0000000..ac2c4ce
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-two-phase-commits.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.10. Two-phase Commit Support for Logical Decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding" /><link rel="next" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.10. Two-phase Commit Support for Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-TWO-PHASE-COMMITS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.10. Two-phase Commit Support for Logical Decoding</h2></div></div></div><p>
+ With the basic output plugin callbacks (eg., <code class="function">begin_cb</code>,
+ <code class="function">change_cb</code>, <code class="function">commit_cb</code> and
+ <code class="function">message_cb</code>) two-phase commit commands like
+ <code class="command">PREPARE TRANSACTION</code>, <code class="command">COMMIT PREPARED</code>
+ and <code class="command">ROLLBACK PREPARED</code> are not decoded. While the
+ <code class="command">PREPARE TRANSACTION</code> is ignored,
+ <code class="command">COMMIT PREPARED</code> is decoded as a <code class="command">COMMIT</code>
+ and <code class="command">ROLLBACK PREPARED</code> is decoded as a
+ <code class="command">ROLLBACK</code>.
+ </p><p>
+ To support the streaming of two-phase commands, an output plugin needs to
+ provide additional callbacks. There are multiple two-phase commit callbacks
+ that are required, (<code class="function">begin_prepare_cb</code>,
+ <code class="function">prepare_cb</code>, <code class="function">commit_prepared_cb</code>,
+ <code class="function">rollback_prepared_cb</code> and
+ <code class="function">stream_prepare_cb</code>) and an optional callback
+ (<code class="function">filter_prepare_cb</code>).
+ </p><p>
+ If the output plugin callbacks for decoding two-phase commit commands are
+ provided, then on <code class="command">PREPARE TRANSACTION</code>, the changes of
+ that transaction are decoded, passed to the output plugin, and the
+ <code class="function">prepare_cb</code> callback is invoked. This differs from the
+ basic decoding setup where changes are only passed to the output plugin
+ when a transaction is committed. The start of a prepared transaction is
+ indicated by the <code class="function">begin_prepare_cb</code> callback.
+ </p><p>
+ When a prepared transaction is rolled back using the
+ <code class="command">ROLLBACK PREPARED</code>, then the
+ <code class="function">rollback_prepared_cb</code> callback is invoked and when the
+ prepared transaction is committed using <code class="command">COMMIT PREPARED</code>,
+ then the <code class="function">commit_prepared_cb</code> callback is invoked.
+ </p><p>
+ Optionally the output plugin can define filtering rules via
+ <code class="function">filter_prepare_cb</code> to decode only specific transaction
+ in two phases. This can be achieved by pattern matching on the
+ <em class="parameter"><code>gid</code></em> or via lookups using the
+ <em class="parameter"><code>xid</code></em>.
+ </p><p>
+ The users that want to decode prepared transactions need to be careful about
+ below mentioned points:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If the prepared transaction has locked [user] catalog tables exclusively
+ then decoding prepare can block till the main transaction is committed.
+ </p></li><li class="listitem"><p>
+ The logical replication solution that builds distributed two phase commit
+ using this feature can deadlock if the prepared transaction has locked
+ [user] catalog tables exclusively. To avoid this users must refrain from
+ having locks on catalog tables (e.g. explicit <code class="command">LOCK</code> command)
+ in such transactions.
+ See <a class="xref" href="logicaldecoding-synchronous.html#LOGICALDECODING-SYNCHRONOUS-CAVEATS" title="49.8.2. Caveats">Section 49.8.2</a> for the details.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-streaming.html" title="49.9. Streaming of Large Transactions for Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.9. Streaming of Large Transactions for Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 50. Replication Progress Tracking</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-walsender.html b/doc/src/sgml/html/logicaldecoding-walsender.html
new file mode 100644
index 0000000..8c4facf
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-walsender.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.3. Streaming Replication Protocol Interface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts" /><link rel="next" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.3. Streaming Replication Protocol Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-WALSENDER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.3. Streaming Replication Protocol Interface</h2></div></div></div><p>
+ The commands
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">CREATE_REPLICATION_SLOT <em class="replaceable"><code>slot_name</code></em> LOGICAL <em class="replaceable"><code>output_plugin</code></em></code></p></li><li class="listitem"><p><code class="literal">DROP_REPLICATION_SLOT <em class="replaceable"><code>slot_name</code></em></code> [<span class="optional"> <code class="literal">WAIT</code> </span>]</p></li><li class="listitem"><p><code class="literal">START_REPLICATION SLOT <em class="replaceable"><code>slot_name</code></em> LOGICAL ...</code></p></li></ul></div><p>
+ are used to create, drop, and stream changes from a replication
+ slot, respectively. These commands are only available over a replication
+ connection; they cannot be used via SQL.
+ See <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> for details on these commands.
+ </p><p>
+ The command <a class="xref" href="app-pgrecvlogical.html" title="pg_recvlogical"><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></a> can be used to control
+ logical decoding over a streaming replication connection. (It uses
+ these commands internally.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-explanation.html" title="49.2. Logical Decoding Concepts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.2. Logical Decoding Concepts </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding-writer.html b/doc/src/sgml/html/logicaldecoding-writer.html
new file mode 100644
index 0000000..e55ad21
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding-writer.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>49.7. Logical Decoding Output Writers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins" /><link rel="next" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">49.7. Logical Decoding Output Writers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-WRITER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">49.7. Logical Decoding Output Writers</h2></div></div></div><p>
+ It is possible to add more output methods for logical decoding.
+ For details, see
+ <code class="filename">src/backend/replication/logical/logicalfuncs.c</code>.
+ Essentially, three functions need to be provided: one to read WAL, one to
+ prepare writing output, and one to write the output
+ (see <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT" title="49.6.5. Functions for Producing Output">Section 49.6.5</a>).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-synchronous.html" title="49.8. Synchronous Replication Support for Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.6. Logical Decoding Output Plugins </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.8. Synchronous Replication Support for Logical Decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/logicaldecoding.html b/doc/src/sgml/html/logicaldecoding.html
new file mode 100644
index 0000000..7112f75
--- /dev/null
+++ b/doc/src/sgml/html/logicaldecoding.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 49. Logical Decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bgworker.html" title="Chapter 48. Background Worker Processes" /><link rel="next" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 49. Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bgworker.html" title="Chapter 48. Background Worker Processes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples">Next</a></td></tr></table><hr /></div><div class="chapter" id="LOGICALDECODING"><div class="titlepage"><div><div><h2 class="title">Chapter 49. Logical Decoding</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="logicaldecoding-example.html">49.1. Logical Decoding Examples</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-explanation.html">49.2. Logical Decoding Concepts</a></span></dt><dd><dl><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.2">49.2.1. Logical Decoding</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS">49.2.2. Replication Slots</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.4">49.2.3. Output Plugins</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#id-1.8.14.8.5">49.2.4. Exported Snapshots</a></span></dt></dl></dd><dt><span class="sect1"><a href="logicaldecoding-walsender.html">49.3. Streaming Replication Protocol Interface</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-sql.html">49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-catalogs.html">49.5. System Catalogs Related to Logical Decoding</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-output-plugin.html">49.6. Logical Decoding Output Plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-INIT">49.6.1. Initialization Function</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES">49.6.2. Capabilities</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE">49.6.3. Output Modes</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS">49.6.4. Output Plugin Callbacks</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT">49.6.5. Functions for Producing Output</a></span></dt></dl></dd><dt><span class="sect1"><a href="logicaldecoding-writer.html">49.7. Logical Decoding Output Writers</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-synchronous.html">49.8. Synchronous Replication Support for Logical Decoding</a></span></dt><dd><dl><dt><span class="sect2"><a href="logicaldecoding-synchronous.html#id-1.8.14.14.2">49.8.1. Overview</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-synchronous.html#LOGICALDECODING-SYNCHRONOUS-CAVEATS">49.8.2. Caveats</a></span></dt></dl></dd><dt><span class="sect1"><a href="logicaldecoding-streaming.html">49.9. Streaming of Large Transactions for Logical Decoding</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-two-phase-commits.html">49.10. Two-phase Commit Support for Logical Decoding</a></span></dt></dl></div><a id="id-1.8.14.2" class="indexterm"></a><p>
+ PostgreSQL provides infrastructure to stream the modifications performed
+ via SQL to external consumers. This functionality can be used for a
+ variety of purposes, including replication solutions and auditing.
+ </p><p>
+ Changes are sent out in streams identified by logical replication slots.
+ </p><p>
+ The format in which those changes are streamed is determined by the output
+ plugin used. An example plugin is provided in the PostgreSQL distribution.
+ Additional plugins can be
+ written to extend the choice of available formats without modifying any
+ core code.
+ Every output plugin has access to each individual new row produced
+ by <code class="command">INSERT</code> and the new row version created
+ by <code class="command">UPDATE</code>. Availability of old row versions for
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code> depends on
+ the configured replica identity (see <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY"><code class="literal">REPLICA IDENTITY</code></a>).
+ </p><p>
+ Changes can be consumed either using the streaming replication protocol
+ (see <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> and
+ <a class="xref" href="logicaldecoding-walsender.html" title="49.3. Streaming Replication Protocol Interface">Section 49.3</a>), or by calling functions
+ via SQL (see <a class="xref" href="logicaldecoding-sql.html" title="49.4. Logical Decoding SQL Interface">Section 49.4</a>). It is also possible
+ to write additional methods of consuming the output of a replication slot
+ without modifying core code
+ (see <a class="xref" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Section 49.7</a>).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bgworker.html" title="Chapter 48. Background Worker Processes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-example.html" title="49.1. Logical Decoding Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 48. Background Worker Processes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.1. Logical Decoding Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ltree.html b/doc/src/sgml/html/ltree.html
new file mode 100644
index 0000000..cb2a5ed
--- /dev/null
+++ b/doc/src/sgml/html/ltree.html
@@ -0,0 +1,582 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.23. ltree</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo.html" title="F.22. lo" /><link rel="next" href="oldsnapshot.html" title="F.24. old_snapshot" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.23. ltree</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo.html" title="F.22. lo">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="oldsnapshot.html" title="F.24. old_snapshot">Next</a></td></tr></table><hr /></div><div class="sect1" id="LTREE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.23. ltree</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.5">F.23.1. Definitions</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.6">F.23.2. Operators and Functions</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.7">F.23.3. Indexes</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.8">F.23.4. Example</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.9">F.23.5. Transforms</a></span></dt><dt><span class="sect2"><a href="ltree.html#id-1.11.7.32.10">F.23.6. Authors</a></span></dt></dl></div><a id="id-1.11.7.32.2" class="indexterm"></a><p>
+ This module implements a data type <code class="type">ltree</code> for representing
+ labels of data stored in a hierarchical tree-like structure.
+ Extensive facilities for searching through label trees are provided.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.32.5"><div class="titlepage"><div><div><h3 class="title">F.23.1. Definitions</h3></div></div></div><p>
+ A <em class="firstterm">label</em> is a sequence of alphanumeric characters
+ and underscores (for example, in C locale the characters
+ <code class="literal">A-Za-z0-9_</code> are allowed).
+ Labels must be less than 256 characters long.
+ </p><p>
+ Examples: <code class="literal">42</code>, <code class="literal">Personal_Services</code>
+ </p><p>
+ A <em class="firstterm">label path</em> is a sequence of zero or more
+ labels separated by dots, for example <code class="literal">L1.L2.L3</code>, representing
+ a path from the root of a hierarchical tree to a particular node. The
+ length of a label path cannot exceed 65535 labels.
+ </p><p>
+ Example: <code class="literal">Top.Countries.Europe.Russia</code>
+ </p><p>
+ The <code class="filename">ltree</code> module provides several data types:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="type">ltree</code> stores a label path.
+ </p></li><li class="listitem"><p>
+ <code class="type">lquery</code> represents a regular-expression-like pattern
+ for matching <code class="type">ltree</code> values. A simple word matches that
+ label within a path. A star symbol (<code class="literal">*</code>) matches zero
+ or more labels. These can be joined with dots to form a pattern that
+ must match the whole label path. For example:
+</p><pre class="synopsis">
+foo <em class="lineannotation"><span class="lineannotation">Match the exact label path <code class="literal">foo</code></span></em>
+*.foo.* <em class="lineannotation"><span class="lineannotation">Match any label path containing the label <code class="literal">foo</code></span></em>
+*.foo <em class="lineannotation"><span class="lineannotation">Match any label path whose last label is <code class="literal">foo</code></span></em>
+</pre><p>
+ </p><p>
+ Both star symbols and simple words can be quantified to restrict how many
+ labels they can match:
+</p><pre class="synopsis">
+*{<em class="replaceable"><code>n</code></em>} <em class="lineannotation"><span class="lineannotation">Match exactly <em class="replaceable"><code>n</code></em> labels</span></em>
+*{<em class="replaceable"><code>n</code></em>,} <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> labels</span></em>
+*{<em class="replaceable"><code>n</code></em>,<em class="replaceable"><code>m</code></em>} <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> but not more than <em class="replaceable"><code>m</code></em> labels</span></em>
+*{,<em class="replaceable"><code>m</code></em>} <em class="lineannotation"><span class="lineannotation">Match at most <em class="replaceable"><code>m</code></em> labels — same as </span></em>*{0,<em class="replaceable"><code>m</code></em>}
+foo{<em class="replaceable"><code>n</code></em>,<em class="replaceable"><code>m</code></em>} <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> but not more than <em class="replaceable"><code>m</code></em> occurrences of <code class="literal">foo</code></span></em>
+foo{,} <em class="lineannotation"><span class="lineannotation">Match any number of occurrences of <code class="literal">foo</code>, including zero</span></em>
+</pre><p>
+ In the absence of any explicit quantifier, the default for a star symbol
+ is to match any number of labels (that is, <code class="literal">{,}</code>) while
+ the default for a non-star item is to match exactly once (that
+ is, <code class="literal">{1}</code>).
+ </p><p>
+ There are several modifiers that can be put at the end of a non-star
+ <code class="type">lquery</code> item to make it match more than just the exact match:
+</p><pre class="synopsis">
+@ <em class="lineannotation"><span class="lineannotation">Match case-insensitively, for example <code class="literal">a@</code> matches <code class="literal">A</code></span></em>
+* <em class="lineannotation"><span class="lineannotation">Match any label with this prefix, for example <code class="literal">foo*</code> matches <code class="literal">foobar</code></span></em>
+% <em class="lineannotation"><span class="lineannotation">Match initial underscore-separated words</span></em>
+</pre><p>
+ The behavior of <code class="literal">%</code> is a bit complicated. It tries to match
+ words rather than the entire label. For example
+ <code class="literal">foo_bar%</code> matches <code class="literal">foo_bar_baz</code> but not
+ <code class="literal">foo_barbaz</code>. If combined with <code class="literal">*</code>, prefix
+ matching applies to each word separately, for example
+ <code class="literal">foo_bar%*</code> matches <code class="literal">foo1_bar2_baz</code> but
+ not <code class="literal">foo1_br2_baz</code>.
+ </p><p>
+ Also, you can write several possibly-modified non-star items separated with
+ <code class="literal">|</code> (OR) to match any of those items, and you can put
+ <code class="literal">!</code> (NOT) at the start of a non-star group to match any
+ label that doesn't match any of the alternatives. A quantifier, if any,
+ goes at the end of the group; it means some number of matches for the
+ group as a whole (that is, some number of labels matching or not matching
+ any of the alternatives).
+ </p><p>
+ Here's an annotated example of <code class="type">lquery</code>:
+</p><pre class="programlisting">
+Top.*{0,2}.sport*@.!football|tennis{1,}.Russ*|Spain
+a. b. c. d. e.
+</pre><p>
+ This query will match any label path that:
+ </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
+ begins with the label <code class="literal">Top</code>
+ </p></li><li class="listitem"><p>
+ and next has zero to two labels before
+ </p></li><li class="listitem"><p>
+ a label beginning with the case-insensitive prefix <code class="literal">sport</code>
+ </p></li><li class="listitem"><p>
+ then has one or more labels, none of which
+ match <code class="literal">football</code> nor <code class="literal">tennis</code>
+ </p></li><li class="listitem"><p>
+ and then ends with a label beginning with <code class="literal">Russ</code> or
+ exactly matching <code class="literal">Spain</code>.
+ </p></li></ol></div></li><li class="listitem"><p><code class="type">ltxtquery</code> represents a full-text-search-like
+ pattern for matching <code class="type">ltree</code> values. An
+ <code class="type">ltxtquery</code> value contains words, possibly with the
+ modifiers <code class="literal">@</code>, <code class="literal">*</code>, <code class="literal">%</code> at the end;
+ the modifiers have the same meanings as in <code class="type">lquery</code>.
+ Words can be combined with <code class="literal">&amp;</code> (AND),
+ <code class="literal">|</code> (OR), <code class="literal">!</code> (NOT), and parentheses.
+ The key difference from
+ <code class="type">lquery</code> is that <code class="type">ltxtquery</code> matches words without
+ regard to their position in the label path.
+ </p><p>
+ Here's an example <code class="type">ltxtquery</code>:
+</p><pre class="programlisting">
+Europe &amp; Russia*@ &amp; !Transportation
+</pre><p>
+ This will match paths that contain the label <code class="literal">Europe</code> and
+ any label beginning with <code class="literal">Russia</code> (case-insensitive),
+ but not paths containing the label <code class="literal">Transportation</code>.
+ The location of these words within the path is not important.
+ Also, when <code class="literal">%</code> is used, the word can be matched to any
+ underscore-separated word within a label, regardless of position.
+ </p></li></ul></div><p>
+ Note: <code class="type">ltxtquery</code> allows whitespace between symbols, but
+ <code class="type">ltree</code> and <code class="type">lquery</code> do not.
+ </p></div><div class="sect2" id="id-1.11.7.32.6"><div class="titlepage"><div><div><h3 class="title">F.23.2. Operators and Functions</h3></div></div></div><p>
+ Type <code class="type">ltree</code> has the usual comparison operators
+ <code class="literal">=</code>, <code class="literal">&lt;&gt;</code>,
+ <code class="literal">&lt;</code>, <code class="literal">&gt;</code>, <code class="literal">&lt;=</code>, <code class="literal">&gt;=</code>.
+ Comparison sorts in the order of a tree traversal, with the children
+ of a node sorted by label text. In addition, the specialized
+ operators shown in <a class="xref" href="ltree.html#LTREE-OP-TABLE" title="Table F.13. ltree Operators">Table F.13</a> are available.
+ </p><div class="table" id="LTREE-OP-TABLE"><p class="title"><strong>Table F.13. <code class="type">ltree</code> Operators</strong></p><div class="table-contents"><table class="table" summary="ltree Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">@&gt;</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is left argument an ancestor of right (or equal)?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">&lt;@</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is left argument a descendant of right (or equal)?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">~</code> <code class="type">lquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lquery</code> <code class="literal">~</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">ltree</code> match <code class="type">lquery</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">?</code> <code class="type">lquery[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lquery[]</code> <code class="literal">?</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">ltree</code> match any <code class="type">lquery</code> in array?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">@</code> <code class="type">ltxtquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">ltxtquery</code> <code class="literal">@</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">ltree</code> match <code class="type">ltxtquery</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">||</code> <code class="type">ltree</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Concatenates <code class="type">ltree</code> paths.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">||</code> <code class="type">text</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">text</code> <code class="literal">||</code> <code class="type">ltree</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Converts text to <code class="type">ltree</code> and concatenates.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">@&gt;</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">&lt;@</code> <code class="type">ltree[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array contain an ancestor of <code class="type">ltree</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">&lt;@</code> <code class="type">ltree</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">ltree</code> <code class="literal">@&gt;</code> <code class="type">ltree[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array contain a descendant of <code class="type">ltree</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">~</code> <code class="type">lquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lquery</code> <code class="literal">~</code> <code class="type">ltree[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array contain any path matching <code class="type">lquery</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">?</code> <code class="type">lquery[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">lquery[]</code> <code class="literal">?</code> <code class="type">ltree[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does <code class="type">ltree</code> array contain any path matching
+ any <code class="type">lquery</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">@</code> <code class="type">ltxtquery</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p class="func_signature">
+ <code class="type">ltxtquery</code> <code class="literal">@</code> <code class="type">ltree[]</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does array contain any path matching <code class="type">ltxtquery</code>?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">?@&gt;</code> <code class="type">ltree</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns first array entry that is an ancestor of <code class="type">ltree</code>,
+ or <code class="literal">NULL</code> if none.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">?&lt;@</code> <code class="type">ltree</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns first array entry that is a descendant of <code class="type">ltree</code>,
+ or <code class="literal">NULL</code> if none.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">?~</code> <code class="type">lquery</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns first array entry that matches <code class="type">lquery</code>,
+ or <code class="literal">NULL</code> if none.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">ltree[]</code> <code class="literal">?@</code> <code class="type">ltxtquery</code>
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns first array entry that matches <code class="type">ltxtquery</code>,
+ or <code class="literal">NULL</code> if none.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The operators <code class="literal">&lt;@</code>, <code class="literal">@&gt;</code>,
+ <code class="literal">@</code> and <code class="literal">~</code> have analogues
+ <code class="literal">^&lt;@</code>, <code class="literal">^@&gt;</code>, <code class="literal">^@</code>,
+ <code class="literal">^~</code>, which are the same except they do not use
+ indexes. These are useful only for testing purposes.
+ </p><p>
+ The available functions are shown in <a class="xref" href="ltree.html#LTREE-FUNC-TABLE" title="Table F.14. ltree Functions">Table F.14</a>.
+ </p><div class="table" id="LTREE-FUNC-TABLE"><p class="title"><strong>Table F.14. <code class="type">ltree</code> Functions</strong></p><div class="table-contents"><table class="table" summary="ltree Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">subltree</code> ( <code class="type">ltree</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code>, <em class="parameter"><code>end</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns subpath of <code class="type">ltree</code> from
+ position <em class="parameter"><code>start</code></em> to
+ position <em class="parameter"><code>end</code></em>-1 (counting from 0).
+ </p>
+ <p>
+ <code class="literal">subltree('Top.Child1.Child2', 1, 2)</code>
+ → <code class="returnvalue">Child1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">subpath</code> ( <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code>, <em class="parameter"><code>len</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns subpath of <code class="type">ltree</code> starting at
+ position <em class="parameter"><code>offset</code></em>, with
+ length <em class="parameter"><code>len</code></em>. If <em class="parameter"><code>offset</code></em>
+ is negative, subpath starts that far from the end of the path.
+ If <em class="parameter"><code>len</code></em> is negative, leaves that many labels off
+ the end of the path.
+ </p>
+ <p>
+ <code class="literal">subpath('Top.Child1.Child2', 0, 2)</code>
+ → <code class="returnvalue">Top.Child1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">subpath</code> ( <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Returns subpath of <code class="type">ltree</code> starting at
+ position <em class="parameter"><code>offset</code></em>, extending to end of path.
+ If <em class="parameter"><code>offset</code></em> is negative, subpath starts that far
+ from the end of the path.
+ </p>
+ <p>
+ <code class="literal">subpath('Top.Child1.Child2', 1)</code>
+ → <code class="returnvalue">Child1.Child2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">nlevel</code> ( <code class="type">ltree</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns number of labels in path.
+ </p>
+ <p>
+ <code class="literal">nlevel('Top.Child1.Child2')</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">index</code> ( <em class="parameter"><code>a</code></em> <code class="type">ltree</code>, <em class="parameter"><code>b</code></em> <code class="type">ltree</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns position of first occurrence of <em class="parameter"><code>b</code></em> in
+ <em class="parameter"><code>a</code></em>, or -1 if not found.
+ </p>
+ <p>
+ <code class="literal">index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6')</code>
+ → <code class="returnvalue">6</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">index</code> ( <em class="parameter"><code>a</code></em> <code class="type">ltree</code>, <em class="parameter"><code>b</code></em> <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns position of first occurrence of <em class="parameter"><code>b</code></em>
+ in <em class="parameter"><code>a</code></em>, or -1 if not found. The search starts at
+ position <em class="parameter"><code>offset</code></em>;
+ negative <em class="parameter"><code>offset</code></em> means
+ start <em class="parameter"><code>-offset</code></em> labels from the end of the path.
+ </p>
+ <p>
+ <code class="literal">index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6', -4)</code>
+ → <code class="returnvalue">9</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">text2ltree</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Casts <code class="type">text</code> to <code class="type">ltree</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">ltree2text</code> ( <code class="type">ltree</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Casts <code class="type">ltree</code> to <code class="type">text</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.32.6.6.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">lca</code> ( <code class="type">ltree</code> [<span class="optional">, <code class="type">ltree</code> [<span class="optional">, ... </span>]</span>] )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Computes longest common ancestor of paths
+ (up to 8 arguments are supported).
+ </p>
+ <p>
+ <code class="literal">lca('1.2.3', '1.2.3.4.5.6')</code>
+ → <code class="returnvalue">1.2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">lca</code> ( <code class="type">ltree[]</code> )
+ → <code class="returnvalue">ltree</code>
+ </p>
+ <p>
+ Computes longest common ancestor of paths in array.
+ </p>
+ <p>
+ <code class="literal">lca(array['1.2.3'::ltree,'1.2.3.4'])</code>
+ → <code class="returnvalue">1.2</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.32.7"><div class="titlepage"><div><div><h3 class="title">F.23.3. Indexes</h3></div></div></div><p>
+ <code class="filename">ltree</code> supports several types of indexes that can speed
+ up the indicated operators:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ B-tree index over <code class="type">ltree</code>:
+ <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">=</code>,
+ <code class="literal">&gt;=</code>, <code class="literal">&gt;</code>
+ </p></li><li class="listitem"><p>
+ GiST index over <code class="type">ltree</code> (<code class="literal">gist_ltree_ops</code>
+ opclass):
+ <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">=</code>,
+ <code class="literal">&gt;=</code>, <code class="literal">&gt;</code>,
+ <code class="literal">@&gt;</code>, <code class="literal">&lt;@</code>,
+ <code class="literal">@</code>, <code class="literal">~</code>, <code class="literal">?</code>
+ </p><p>
+ <code class="literal">gist_ltree_ops</code> GiST opclass approximates a set of
+ path labels as a bitmap signature. Its optional integer parameter
+ <code class="literal">siglen</code> determines the
+ signature length in bytes. The default signature length is 8 bytes.
+ The length must be a positive multiple of <code class="type">int</code> alignment
+ (4 bytes on most machines)) up to 2024. Longer
+ signatures lead to a more precise search (scanning a smaller fraction of the index and
+ fewer heap pages), at the cost of a larger index.
+ </p><p>
+ Example of creating such an index with the default signature length of 8 bytes:
+ </p><pre class="programlisting">
+CREATE INDEX path_gist_idx ON test USING GIST (path);
+</pre><p>
+ Example of creating such an index with a signature length of 100 bytes:
+ </p><pre class="programlisting">
+CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100));
+</pre></li><li class="listitem"><p>
+ GiST index over <code class="type">ltree[]</code> (<code class="literal">gist__ltree_ops</code>
+ opclass):
+ <code class="literal">ltree[] &lt;@ ltree</code>, <code class="literal">ltree @&gt; ltree[]</code>,
+ <code class="literal">@</code>, <code class="literal">~</code>, <code class="literal">?</code>
+ </p><p>
+ <code class="literal">gist__ltree_ops</code> GiST opclass works similarly to
+ <code class="literal">gist_ltree_ops</code> and also takes signature length as
+ a parameter. The default value of <code class="literal">siglen</code> in
+ <code class="literal">gist__ltree_ops</code> is 28 bytes.
+ </p><p>
+ Example of creating such an index with the default signature length of 28 bytes:
+ </p><pre class="programlisting">
+CREATE INDEX path_gist_idx ON test USING GIST (array_path);
+</pre><p>
+ Example of creating such an index with a signature length of 100 bytes:
+ </p><pre class="programlisting">
+CREATE INDEX path_gist_idx ON test USING GIST (array_path gist__ltree_ops(siglen=100));
+</pre><p>
+ Note: This index type is lossy.
+ </p></li></ul></div></div><div class="sect2" id="id-1.11.7.32.8"><div class="titlepage"><div><div><h3 class="title">F.23.4. Example</h3></div></div></div><p>
+ This example uses the following data (also available in file
+ <code class="filename">contrib/ltree/ltreetest.sql</code> in the source distribution):
+ </p><pre class="programlisting">
+CREATE TABLE test (path ltree);
+INSERT INTO test VALUES ('Top');
+INSERT INTO test VALUES ('Top.Science');
+INSERT INTO test VALUES ('Top.Science.Astronomy');
+INSERT INTO test VALUES ('Top.Science.Astronomy.Astrophysics');
+INSERT INTO test VALUES ('Top.Science.Astronomy.Cosmology');
+INSERT INTO test VALUES ('Top.Hobbies');
+INSERT INTO test VALUES ('Top.Hobbies.Amateurs_Astronomy');
+INSERT INTO test VALUES ('Top.Collections');
+INSERT INTO test VALUES ('Top.Collections.Pictures');
+INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy');
+INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Stars');
+INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Galaxies');
+INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Astronauts');
+CREATE INDEX path_gist_idx ON test USING GIST (path);
+CREATE INDEX path_idx ON test USING BTREE (path);
+</pre><p>
+ Now, we have a table <code class="structname">test</code> populated with data describing
+ the hierarchy shown below:
+ </p><pre class="literallayout">
+ Top
+ / | \
+ Science Hobbies Collections
+ / | \
+ Astronomy Amateurs_Astronomy Pictures
+ / \ |
+Astrophysics Cosmology Astronomy
+ / | \
+ Galaxies Stars Astronauts
+</pre><p>
+ We can do inheritance:
+</p><pre class="screen">
+ltreetest=&gt; SELECT path FROM test WHERE path &lt;@ 'Top.Science';
+ path
+------------------------------------
+ Top.Science
+ Top.Science.Astronomy
+ Top.Science.Astronomy.Astrophysics
+ Top.Science.Astronomy.Cosmology
+(4 rows)
+</pre><p>
+ </p><p>
+ Here are some examples of path matching:
+</p><pre class="screen">
+ltreetest=&gt; SELECT path FROM test WHERE path ~ '*.Astronomy.*';
+ path
+-----------------------------------------------
+ Top.Science.Astronomy
+ Top.Science.Astronomy.Astrophysics
+ Top.Science.Astronomy.Cosmology
+ Top.Collections.Pictures.Astronomy
+ Top.Collections.Pictures.Astronomy.Stars
+ Top.Collections.Pictures.Astronomy.Galaxies
+ Top.Collections.Pictures.Astronomy.Astronauts
+(7 rows)
+
+ltreetest=&gt; SELECT path FROM test WHERE path ~ '*.!pictures@.Astronomy.*';
+ path
+------------------------------------
+ Top.Science.Astronomy
+ Top.Science.Astronomy.Astrophysics
+ Top.Science.Astronomy.Cosmology
+(3 rows)
+</pre><p>
+ </p><p>
+ Here are some examples of full text search:
+</p><pre class="screen">
+ltreetest=&gt; SELECT path FROM test WHERE path @ 'Astro*% &amp; !pictures@';
+ path
+------------------------------------
+ Top.Science.Astronomy
+ Top.Science.Astronomy.Astrophysics
+ Top.Science.Astronomy.Cosmology
+ Top.Hobbies.Amateurs_Astronomy
+(4 rows)
+
+ltreetest=&gt; SELECT path FROM test WHERE path @ 'Astro* &amp; !pictures@';
+ path
+------------------------------------
+ Top.Science.Astronomy
+ Top.Science.Astronomy.Astrophysics
+ Top.Science.Astronomy.Cosmology
+(3 rows)
+</pre><p>
+ </p><p>
+ Path construction using functions:
+</p><pre class="screen">
+ltreetest=&gt; SELECT subpath(path,0,2)||'Space'||subpath(path,2) FROM test WHERE path &lt;@ 'Top.Science.Astronomy';
+ ?column?
+------------------------------------------
+ Top.Science.Space.Astronomy
+ Top.Science.Space.Astronomy.Astrophysics
+ Top.Science.Space.Astronomy.Cosmology
+(3 rows)
+</pre><p>
+ </p><p>
+ We could simplify this by creating an SQL function that inserts a label
+ at a specified position in a path:
+</p><pre class="screen">
+CREATE FUNCTION ins_label(ltree, int, text) RETURNS ltree
+ AS 'select subpath($1,0,$2) || $3 || subpath($1,$2);'
+ LANGUAGE SQL IMMUTABLE;
+
+ltreetest=&gt; SELECT ins_label(path,2,'Space') FROM test WHERE path &lt;@ 'Top.Science.Astronomy';
+ ins_label
+------------------------------------------
+ Top.Science.Space.Astronomy
+ Top.Science.Space.Astronomy.Astrophysics
+ Top.Science.Space.Astronomy.Cosmology
+(3 rows)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.32.9"><div class="titlepage"><div><div><h3 class="title">F.23.5. Transforms</h3></div></div></div><p>
+ The <code class="literal">ltree_plpython3u</code> extension implements transforms for
+ the <code class="type">ltree</code> type for PL/Python. If installed and specified when
+ creating a function, <code class="type">ltree</code> values are mapped to Python lists.
+ (The reverse is currently not supported, however.)
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is strongly recommended that the transform extension be installed in
+ the same schema as <code class="filename">ltree</code>. Otherwise there are
+ installation-time security hazards if a transform extension's schema
+ contains objects defined by a hostile user.
+ </p></div></div><div class="sect2" id="id-1.11.7.32.10"><div class="titlepage"><div><div><h3 class="title">F.23.6. Authors</h3></div></div></div><p>
+ All work was done by Teodor Sigaev (<code class="email">&lt;<a class="email" href="mailto:teodor@stack.net">teodor@stack.net</a>&gt;</code>) and
+ Oleg Bartunov (<code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>). See
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/</a> for
+ additional information. Authors would like to thank Eugeny Rodichev for
+ helpful discussions. Comments and bug reports are welcome.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo.html" title="F.22. lo">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="oldsnapshot.html" title="F.24. old_snapshot">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.22. lo </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.24. old_snapshot</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/maintenance.html b/doc/src/sgml/html/maintenance.html
new file mode 100644
index 0000000..13f3b77
--- /dev/null
+++ b/doc/src/sgml/html/maintenance.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 25. Routine Database Maintenance Tasks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="multibyte.html" title="24.3. Character Set Support" /><link rel="next" href="routine-vacuuming.html" title="25.1. Routine Vacuuming" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 25. Routine Database Maintenance Tasks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="multibyte.html" title="24.3. Character Set Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Next</a></td></tr></table><hr /></div><div class="chapter" id="MAINTENANCE"><div class="titlepage"><div><div><h2 class="title">Chapter 25. Routine Database Maintenance Tasks</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="routine-vacuuming.html">25.1. Routine Vacuuming</a></span></dt><dd><dl><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-BASICS">25.1.1. Vacuuming Basics</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-SPACE-RECOVERY">25.1.2. Recovering Disk Space</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-STATISTICS">25.1.3. Updating Planner Statistics</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-VISIBILITY-MAP">25.1.4. Updating the Visibility Map</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND">25.1.5. Preventing Transaction ID Wraparound Failures</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#AUTOVACUUM">25.1.6. The Autovacuum Daemon</a></span></dt></dl></dd><dt><span class="sect1"><a href="routine-reindex.html">25.2. Routine Reindexing</a></span></dt><dt><span class="sect1"><a href="logfile-maintenance.html">25.3. Log File Maintenance</a></span></dt></dl></div><a id="id-1.6.12.2" class="indexterm"></a><a id="id-1.6.12.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span>, like any database software, requires that certain tasks
+ be performed regularly to achieve optimum performance. The tasks
+ discussed here are <span class="emphasis"><em>required</em></span>, but they
+ are repetitive in nature and can easily be automated using standard
+ tools such as <span class="application">cron</span> scripts or
+ Windows' <span class="application">Task Scheduler</span>. It is the database
+ administrator's responsibility to set up appropriate scripts, and to
+ check that they execute successfully.
+ </p><p>
+ One obvious maintenance task is the creation of backup copies of the data on a
+ regular schedule. Without a recent backup, you have no chance of recovery
+ after a catastrophe (disk failure, fire, mistakenly dropping a critical
+ table, etc.). The backup and recovery mechanisms available in
+ <span class="productname">PostgreSQL</span> are discussed at length in
+ <a class="xref" href="backup.html" title="Chapter 26. Backup and Restore">Chapter 26</a>.
+ </p><p>
+ The other main category of maintenance task is periodic <span class="quote">“<span class="quote">vacuuming</span>”</span>
+ of the database. This activity is discussed in
+ <a class="xref" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Section 25.1</a>. Closely related to this is updating
+ the statistics that will be used by the query planner, as discussed in
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>.
+ </p><p>
+ Another task that might need periodic attention is log file management.
+ This is discussed in <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a>.
+ </p><p>
+ <a class="ulink" href="https://bucardo.org/check_postgres/" target="_top"><span class="application">check_postgres</span></a>
+ is available for monitoring database health and reporting unusual
+ conditions. <span class="application">check_postgres</span> integrates with
+ Nagios and MRTG, but can be run standalone too.
+ </p><p>
+ <span class="productname">PostgreSQL</span> is low-maintenance compared
+ to some other database management systems. Nonetheless,
+ appropriate attention to these tasks will go far towards ensuring a
+ pleasant and productive experience with the system.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multibyte.html" title="24.3. Character Set Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Next</a></td></tr><tr><td width="40%" align="left" valign="top">24.3. Character Set Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 25.1. Routine Vacuuming</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-config.html b/doc/src/sgml/html/manage-ag-config.html
new file mode 100644
index 0000000..7a4f21c
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-config.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.4. Database Configuration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-templatedbs.html" title="23.3. Template Databases" /><link rel="next" href="manage-ag-dropdb.html" title="23.5. Destroying a Database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.4. Database Configuration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-dropdb.html" title="23.5. Destroying a Database">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.4. Database Configuration</h2></div></div></div><p>
+ Recall from <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> that the
+ <span class="productname">PostgreSQL</span> server provides a large number of
+ run-time configuration variables. You can set database-specific
+ default values for many of these settings.
+ </p><p>
+ For example, if for some reason you want to disable the
+ <acronym class="acronym">GEQO</acronym> optimizer for a given database, you'd
+ ordinarily have to either disable it for all databases or make sure
+ that every connecting client is careful to issue <code class="literal">SET geqo
+ TO off</code>. To make this setting the default within a particular
+ database, you can execute the command:
+</p><pre class="programlisting">
+ALTER DATABASE mydb SET geqo TO off;
+</pre><p>
+ This will save the setting (but not set it immediately). In
+ subsequent connections to this database it will appear as though
+ <code class="literal">SET geqo TO off;</code> had been executed just before the
+ session started.
+ Note that users can still alter this setting during their sessions; it
+ will only be the default. To undo any such setting, use
+ <code class="literal">ALTER DATABASE <em class="replaceable"><code>dbname</code></em> RESET
+ <em class="replaceable"><code>varname</code></em></code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-dropdb.html" title="23.5. Destroying a Database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.3. Template Databases </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.5. Destroying a Database</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-createdb.html b/doc/src/sgml/html/manage-ag-createdb.html
new file mode 100644
index 0000000..72591e2
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-createdb.html
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.2. Creating a Database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-overview.html" title="23.1. Overview" /><link rel="next" href="manage-ag-templatedbs.html" title="23.3. Template Databases" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.2. Creating a Database</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-overview.html" title="23.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-CREATEDB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.2. Creating a Database</h2></div></div></div><a id="id-1.6.10.5.2" class="indexterm"></a><p>
+ In order to create a database, the <span class="productname">PostgreSQL</span>
+ server must be up and running (see <a class="xref" href="server-start.html" title="19.3. Starting the Database Server">Section 19.3</a>).
+ </p><p>
+ Databases are created with the SQL command
+ <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>:
+</p><pre class="synopsis">
+CREATE DATABASE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ where <em class="replaceable"><code>name</code></em> follows the usual rules for
+ <acronym class="acronym">SQL</acronym> identifiers. The current role automatically
+ becomes the owner of the new database. It is the privilege of the
+ owner of a database to remove it later (which also removes all
+ the objects in it, even if they have a different owner).
+ </p><p>
+ The creation of databases is a restricted operation. See <a class="xref" href="role-attributes.html" title="22.2. Role Attributes">Section 22.2</a> for how to grant permission.
+ </p><p>
+ Since you need to be connected to the database server in order to
+ execute the <code class="command">CREATE DATABASE</code> command, the
+ question remains how the <span class="emphasis"><em>first</em></span> database at any given
+ site can be created. The first database is always created by the
+ <code class="command">initdb</code> command when the data storage area is
+ initialized. (See <a class="xref" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Section 19.2</a>.) This
+ database is called
+ <code class="literal">postgres</code>.<a id="id-1.6.10.5.6.6" class="indexterm"></a> So to
+ create the first <span class="quote">“<span class="quote">ordinary</span>”</span> database you can connect to
+ <code class="literal">postgres</code>.
+ </p><p>
+ Two additional databases,
+ <code class="literal">template1</code><a id="id-1.6.10.5.7.2" class="indexterm"></a>
+ and
+ <code class="literal">template0</code>,<a id="id-1.6.10.5.7.4" class="indexterm"></a>
+ are also created during database cluster initialization. Whenever a
+ new database is created within the
+ cluster, <code class="literal">template1</code> is essentially cloned.
+ This means that any changes you make in <code class="literal">template1</code> are
+ propagated to all subsequently created databases. Because of this,
+ avoid creating objects in <code class="literal">template1</code> unless you want them
+ propagated to every newly created database.
+ <code class="literal">template0</code> is meant as a pristine copy of the original
+ contents of <code class="literal">template1</code>. It can be cloned instead
+ of <code class="literal">template1</code> when it is important to make a database
+ without any such site-local additions. More details
+ appear in <a class="xref" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Section 23.3</a>.
+ </p><p>
+ As a convenience, there is a program you can
+ execute from the shell to create new databases,
+ <code class="command">createdb</code>.<a id="id-1.6.10.5.8.2" class="indexterm"></a>
+
+</p><pre class="synopsis">
+createdb <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ <code class="command">createdb</code> does no magic. It connects to the <code class="literal">postgres</code>
+ database and issues the <code class="command">CREATE DATABASE</code> command,
+ exactly as described above.
+ The <a class="xref" href="app-createdb.html" title="createdb"><span class="refentrytitle"><span class="application">createdb</span></span></a> reference page contains the invocation
+ details. Note that <code class="command">createdb</code> without any arguments will create
+ a database with the current user name.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> contains information about
+ how to restrict who can connect to a given database.
+ </p></div><p>
+ Sometimes you want to create a database for someone else, and have them
+ become the owner of the new database, so they can
+ configure and manage it themselves. To achieve that, use one of the
+ following commands:
+</p><pre class="programlisting">
+CREATE DATABASE <em class="replaceable"><code>dbname</code></em> OWNER <em class="replaceable"><code>rolename</code></em>;
+</pre><p>
+ from the SQL environment, or:
+</p><pre class="programlisting">
+createdb -O <em class="replaceable"><code>rolename</code></em> <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+ from the shell.
+ Only the superuser is allowed to create a database for
+ someone else (that is, for a role you are not a member of).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-overview.html" title="23.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.3. Template Databases</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-dropdb.html b/doc/src/sgml/html/manage-ag-dropdb.html
new file mode 100644
index 0000000..55215da
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-dropdb.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.5. Destroying a Database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-config.html" title="23.4. Database Configuration" /><link rel="next" href="manage-ag-tablespaces.html" title="23.6. Tablespaces" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.5. Destroying a Database</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-config.html" title="23.4. Database Configuration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-DROPDB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.5. Destroying a Database</h2></div></div></div><p>
+ Databases are destroyed with the command
+ <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a>:<a id="id-1.6.10.8.2.2" class="indexterm"></a>
+</p><pre class="synopsis">
+DROP DATABASE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ Only the owner of the database, or
+ a superuser, can drop a database. Dropping a database removes all objects
+ that were
+ contained within the database. The destruction of a database cannot
+ be undone.
+ </p><p>
+ You cannot execute the <code class="command">DROP DATABASE</code> command
+ while connected to the victim database. You can, however, be
+ connected to any other database, including the <code class="literal">template1</code>
+ database.
+ <code class="literal">template1</code> would be the only option for dropping the last user database of a
+ given cluster.
+ </p><p>
+ For convenience, there is also a shell program to drop
+ databases, <a class="xref" href="app-dropdb.html" title="dropdb"><span class="refentrytitle"><span class="application">dropdb</span></span></a>:<a id="id-1.6.10.8.4.2" class="indexterm"></a>
+</p><pre class="synopsis">
+dropdb <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+ (Unlike <code class="command">createdb</code>, it is not the default action to drop
+ the database with the current user name.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-config.html" title="23.4. Database Configuration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.4. Database Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.6. Tablespaces</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-overview.html b/doc/src/sgml/html/manage-ag-overview.html
new file mode 100644
index 0000000..4f07288
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-overview.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="managing-databases.html" title="Chapter 23. Managing Databases" /><link rel="next" href="manage-ag-createdb.html" title="23.2. Creating a Database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="managing-databases.html" title="Chapter 23. Managing Databases">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-createdb.html" title="23.2. Creating a Database">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.1. Overview</h2></div></div></div><a id="id-1.6.10.4.2" class="indexterm"></a><p>
+ A small number of objects, like role, database, and tablespace
+ names, are defined at the cluster level and stored in the
+ <code class="literal">pg_global</code> tablespace. Inside the cluster are
+ multiple databases, which are isolated from each other but can access
+ cluster-level objects. Inside each database are multiple schemas,
+ which contain objects like tables and functions. So the full hierarchy
+ is: cluster, database, schema, table (or some other kind of object,
+ such as a function).
+ </p><p>
+ When connecting to the database server, a client must specify the
+ database name in its connection request.
+ It is not possible to access more than one database per
+ connection. However, clients can open multiple connections to
+ the same database, or different databases.
+ Database-level security has two components: access control
+ (see <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a>), managed at the
+ connection level, and authorization control
+ (see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>), managed via the grant system.
+ Foreign data wrappers (see <a class="xref" href="postgres-fdw.html" title="F.38. postgres_fdw">postgres_fdw</a>)
+ allow for objects within one database to act as proxies for objects in
+ other database or clusters.
+ The older dblink module (see <a class="xref" href="dblink.html" title="F.12. dblink">dblink</a>) provides a similar capability.
+ By default, all users can connect to all databases using all connection methods.
+ </p><p>
+ If one <span class="productname">PostgreSQL</span> server cluster is planned to contain
+ unrelated projects or users that should be, for the most part, unaware
+ of each other, it is recommended to put them into separate databases and
+ adjust authorizations and access controls accordingly.
+ If the projects or users are interrelated, and thus should be able to use
+ each other's resources, they should be put in the same database but probably
+ into separate schemas; this provides a modular structure with namespace
+ isolation and authorization control.
+ More information about managing schemas is in <a class="xref" href="ddl-schemas.html" title="5.9. Schemas">Section 5.9</a>.
+ </p><p>
+ While multiple databases can be created within a single cluster, it is advised
+ to consider carefully whether the benefits outweigh the risks and limitations.
+ In particular, the impact that having a shared WAL (see <a class="xref" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Chapter 30</a>)
+ has on backup and recovery options. While individual databases in the cluster
+ are isolated when considered from the user's perspective, they are closely bound
+ from the database administrator's point-of-view.
+ </p><p>
+ Databases are created with the <code class="command">CREATE DATABASE</code> command
+ (see <a class="xref" href="manage-ag-createdb.html" title="23.2. Creating a Database">Section 23.2</a>) and destroyed with the
+ <code class="command">DROP DATABASE</code> command
+ (see <a class="xref" href="manage-ag-dropdb.html" title="23.5. Destroying a Database">Section 23.5</a>).
+ To determine the set of existing databases, examine the
+ <code class="structname">pg_database</code> system catalog, for example
+</p><pre class="synopsis">
+SELECT datname FROM pg_database;
+</pre><p>
+ The <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> program's <code class="literal">\l</code> meta-command
+ and <code class="option">-l</code> command-line option are also useful for listing the
+ existing databases.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <acronym class="acronym">SQL</acronym> standard calls databases <span class="quote">“<span class="quote">catalogs</span>”</span>, but there
+ is no difference in practice.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="managing-databases.html" title="Chapter 23. Managing Databases">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-createdb.html" title="23.2. Creating a Database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 23. Managing Databases </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.2. Creating a Database</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-tablespaces.html b/doc/src/sgml/html/manage-ag-tablespaces.html
new file mode 100644
index 0000000..af955f8
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-tablespaces.html
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.6. Tablespaces</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-dropdb.html" title="23.5. Destroying a Database" /><link rel="next" href="charset.html" title="Chapter 24. Localization" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.6. Tablespaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-dropdb.html" title="23.5. Destroying a Database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="charset.html" title="Chapter 24. Localization">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-TABLESPACES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.6. Tablespaces</h2></div></div></div><a id="id-1.6.10.9.2" class="indexterm"></a><p>
+ Tablespaces in <span class="productname">PostgreSQL</span> allow database administrators to
+ define locations in the file system where the files representing
+ database objects can be stored. Once created, a tablespace can be referred
+ to by name when creating database objects.
+ </p><p>
+ By using tablespaces, an administrator can control the disk layout
+ of a <span class="productname">PostgreSQL</span> installation. This is useful in at
+ least two ways. First, if the partition or volume on which the
+ cluster was initialized runs out of space and cannot be extended,
+ a tablespace can be created on a different partition and used
+ until the system can be reconfigured.
+ </p><p>
+ Second, tablespaces allow an administrator to use knowledge of the
+ usage pattern of database objects to optimize performance. For
+ example, an index which is very heavily used can be placed on a
+ very fast, highly available disk, such as an expensive solid state
+ device. At the same time a table storing archived data which is
+ rarely used or not performance critical could be stored on a less
+ expensive, slower disk system.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ Even though located outside the main PostgreSQL data directory,
+ tablespaces are an integral part of the database cluster and
+ <span class="emphasis"><em>cannot</em></span> be treated as an autonomous collection
+ of data files. They are dependent on metadata contained in the main
+ data directory, and therefore cannot be attached to a different
+ database cluster or backed up individually. Similarly, if you lose
+ a tablespace (file deletion, disk failure, etc.), the database cluster
+ might become unreadable or unable to start. Placing a tablespace
+ on a temporary file system like a RAM disk risks the reliability of
+ the entire cluster.
+ </p></div><p>
+ To define a tablespace, use the <a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>
+ command, for example:<a id="id-1.6.10.9.7.2" class="indexterm"></a>:
+</p><pre class="programlisting">
+CREATE TABLESPACE fastspace LOCATION '/ssd1/postgresql/data';
+</pre><p>
+ The location must be an existing, empty directory that is owned by
+ the <span class="productname">PostgreSQL</span> operating system user. All objects subsequently
+ created within the tablespace will be stored in files underneath this
+ directory. The location must not be on removable or transient storage,
+ as the cluster might fail to function if the tablespace is missing
+ or lost.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ There is usually not much point in making more than one
+ tablespace per logical file system, since you cannot control the location
+ of individual files within a logical file system. However,
+ <span class="productname">PostgreSQL</span> does not enforce any such limitation, and
+ indeed it is not directly aware of the file system boundaries on your
+ system. It just stores files in the directories you tell it to use.
+ </p></div><p>
+ Creation of the tablespace itself must be done as a database superuser,
+ but after that you can allow ordinary database users to use it.
+ To do that, grant them the <code class="literal">CREATE</code> privilege on it.
+ </p><p>
+ Tables, indexes, and entire databases can be assigned to
+ particular tablespaces. To do so, a user with the <code class="literal">CREATE</code>
+ privilege on a given tablespace must pass the tablespace name as a
+ parameter to the relevant command. For example, the following creates
+ a table in the tablespace <code class="literal">space1</code>:
+</p><pre class="programlisting">
+CREATE TABLE foo(i int) TABLESPACE space1;
+</pre><p>
+ </p><p>
+ Alternatively, use the <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> parameter:
+</p><pre class="programlisting">
+SET default_tablespace = space1;
+CREATE TABLE foo(i int);
+</pre><p>
+ When <code class="varname">default_tablespace</code> is set to anything but an empty
+ string, it supplies an implicit <code class="literal">TABLESPACE</code> clause for
+ <code class="command">CREATE TABLE</code> and <code class="command">CREATE INDEX</code> commands that
+ do not have an explicit one.
+ </p><p>
+ There is also a <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> parameter, which
+ determines the placement of temporary tables and indexes, as well as
+ temporary files that are used for purposes such as sorting large data
+ sets. This can be a list of tablespace names, rather than only one,
+ so that the load associated with temporary objects can be spread over
+ multiple tablespaces. A random member of the list is picked each time
+ a temporary object is to be created.
+ </p><p>
+ The tablespace associated with a database is used to store the system
+ catalogs of that database. Furthermore, it is the default tablespace
+ used for tables, indexes, and temporary files created within the database,
+ if no <code class="literal">TABLESPACE</code> clause is given and no other selection is
+ specified by <code class="varname">default_tablespace</code> or
+ <code class="varname">temp_tablespaces</code> (as appropriate).
+ If a database is created without specifying a tablespace for it,
+ it uses the same tablespace as the template database it is copied from.
+ </p><p>
+ Two tablespaces are automatically created when the database cluster
+ is initialized. The
+ <code class="literal">pg_global</code> tablespace is used for shared system catalogs. The
+ <code class="literal">pg_default</code> tablespace is the default tablespace of the
+ <code class="literal">template1</code> and <code class="literal">template0</code> databases (and, therefore,
+ will be the default tablespace for other databases as well, unless
+ overridden by a <code class="literal">TABLESPACE</code> clause in <code class="command">CREATE
+ DATABASE</code>).
+ </p><p>
+ Once created, a tablespace can be used from any database, provided
+ the requesting user has sufficient privilege. This means that a tablespace
+ cannot be dropped until all objects in all databases using the tablespace
+ have been removed.
+ </p><p>
+ To remove an empty tablespace, use the <a class="xref" href="sql-droptablespace.html" title="DROP TABLESPACE"><span class="refentrytitle">DROP TABLESPACE</span></a>
+ command.
+ </p><p>
+ To determine the set of existing tablespaces, examine the
+ <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code>
+ </a> system catalog, for example
+</p><pre class="synopsis">
+SELECT spcname FROM pg_tablespace;
+</pre><p>
+ The <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> program's <code class="literal">\db</code> meta-command
+ is also useful for listing the existing tablespaces.
+ </p><p>
+ <span class="productname">PostgreSQL</span> makes use of symbolic links
+ to simplify the implementation of tablespaces. This
+ means that tablespaces can be used <span class="emphasis"><em>only</em></span> on systems
+ that support symbolic links.
+ </p><p>
+ The directory <code class="filename">$PGDATA/pg_tblspc</code> contains symbolic links that
+ point to each of the non-built-in tablespaces defined in the cluster.
+ Although not recommended, it is possible to adjust the tablespace
+ layout by hand by redefining these links. Under no circumstances perform
+ this operation while the server is running. Note that in PostgreSQL 9.1
+ and earlier you will also need to update the <code class="structname">pg_tablespace</code>
+ catalog with the new locations. (If you do not, <code class="literal">pg_dump</code> will
+ continue to output the old tablespace locations.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-dropdb.html" title="23.5. Destroying a Database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="charset.html" title="Chapter 24. Localization">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.5. Destroying a Database </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 24. Localization</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/manage-ag-templatedbs.html b/doc/src/sgml/html/manage-ag-templatedbs.html
new file mode 100644
index 0000000..3740c9d
--- /dev/null
+++ b/doc/src/sgml/html/manage-ag-templatedbs.html
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>23.3. Template Databases</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="manage-ag-createdb.html" title="23.2. Creating a Database" /><link rel="next" href="manage-ag-config.html" title="23.4. Database Configuration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">23.3. Template Databases</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="manage-ag-createdb.html" title="23.2. Creating a Database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><th width="60%" align="center">Chapter 23. Managing Databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-config.html" title="23.4. Database Configuration">Next</a></td></tr></table><hr /></div><div class="sect1" id="MANAGE-AG-TEMPLATEDBS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">23.3. Template Databases</h2></div></div></div><p>
+ <code class="command">CREATE DATABASE</code> actually works by copying an existing
+ database. By default, it copies the standard system database named
+ <code class="literal">template1</code>.<a id="id-1.6.10.6.2.3" class="indexterm"></a> Thus that
+ database is the <span class="quote">“<span class="quote">template</span>”</span> from which new databases are
+ made. If you add objects to <code class="literal">template1</code>, these objects
+ will be copied into subsequently created user databases. This
+ behavior allows site-local modifications to the standard set of
+ objects in databases. For example, if you install the procedural
+ language <span class="application">PL/Perl</span> in <code class="literal">template1</code>, it will
+ automatically be available in user databases without any extra
+ action being taken when those databases are created.
+ </p><p>
+ However, <code class="command">CREATE DATABASE</code> does not copy database-level
+ <code class="command">GRANT</code> permissions attached to the source database.
+ The new database has default database-level permissions.
+ </p><p>
+ There is a second standard system database named
+ <code class="literal">template0</code>.<a id="id-1.6.10.6.4.2" class="indexterm"></a> This
+ database contains the same data as the initial contents of
+ <code class="literal">template1</code>, that is, only the standard objects
+ predefined by your version of
+ <span class="productname">PostgreSQL</span>. <code class="literal">template0</code>
+ should never be changed after the database cluster has been
+ initialized. By instructing
+ <code class="command">CREATE DATABASE</code> to copy <code class="literal">template0</code> instead
+ of <code class="literal">template1</code>, you can create a <span class="quote">“<span class="quote">pristine</span>”</span> user
+ database (one where no user-defined objects exist and where the system
+ objects have not been altered) that contains none of the site-local additions in
+ <code class="literal">template1</code>. This is particularly handy when restoring a
+ <code class="literal">pg_dump</code> dump: the dump script should be restored in a
+ pristine database to ensure that one recreates the correct contents
+ of the dumped database, without conflicting with objects that
+ might have been added to <code class="literal">template1</code> later on.
+ </p><p>
+ Another common reason for copying <code class="literal">template0</code> instead
+ of <code class="literal">template1</code> is that new encoding and locale settings
+ can be specified when copying <code class="literal">template0</code>, whereas a copy
+ of <code class="literal">template1</code> must use the same settings it does.
+ This is because <code class="literal">template1</code> might contain encoding-specific
+ or locale-specific data, while <code class="literal">template0</code> is known not to.
+ </p><p>
+ To create a database by copying <code class="literal">template0</code>, use:
+</p><pre class="programlisting">
+CREATE DATABASE <em class="replaceable"><code>dbname</code></em> TEMPLATE template0;
+</pre><p>
+ from the SQL environment, or:
+</p><pre class="programlisting">
+createdb -T template0 <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+ from the shell.
+ </p><p>
+ It is possible to create additional template databases, and indeed
+ one can copy any database in a cluster by specifying its name
+ as the template for <code class="command">CREATE DATABASE</code>. It is important to
+ understand, however, that this is not (yet) intended as
+ a general-purpose <span class="quote">“<span class="quote"><code class="command">COPY DATABASE</code></span>”</span> facility.
+ The principal limitation is that no other sessions can be connected to
+ the source database while it is being copied. <code class="command">CREATE
+ DATABASE</code> will fail if any other connection exists when it starts;
+ during the copy operation, new connections to the source database
+ are prevented.
+ </p><p>
+ Two useful flags exist in <code class="literal">pg_database</code><a id="id-1.6.10.6.8.2" class="indexterm"></a> for each
+ database: the columns <code class="literal">datistemplate</code> and
+ <code class="literal">datallowconn</code>. <code class="literal">datistemplate</code>
+ can be set to indicate that a database is intended as a template for
+ <code class="command">CREATE DATABASE</code>. If this flag is set, the database can be
+ cloned by any user with <code class="literal">CREATEDB</code> privileges; if it is not set,
+ only superusers and the owner of the database can clone it.
+ If <code class="literal">datallowconn</code> is false, then no new connections
+ to that database will be allowed (but existing sessions are not terminated
+ simply by setting the flag false). The <code class="literal">template0</code>
+ database is normally marked <code class="literal">datallowconn = false</code> to prevent its modification.
+ Both <code class="literal">template0</code> and <code class="literal">template1</code>
+ should always be marked with <code class="literal">datistemplate = true</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">template1</code> and <code class="literal">template0</code> do not have any special
+ status beyond the fact that the name <code class="literal">template1</code> is the default
+ source database name for <code class="command">CREATE DATABASE</code>.
+ For example, one could drop <code class="literal">template1</code> and recreate it from
+ <code class="literal">template0</code> without any ill effects. This course of action
+ might be advisable if one has carelessly added a bunch of junk in
+ <code class="literal">template1</code>. (To delete <code class="literal">template1</code>,
+ it must have <code class="literal">pg_database.datistemplate = false</code>.)
+ </p><p>
+ The <code class="literal">postgres</code> database is also created when a database
+ cluster is initialized. This database is meant as a default database for
+ users and applications to connect to. It is simply a copy of
+ <code class="literal">template1</code> and can be dropped and recreated if necessary.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manage-ag-createdb.html" title="23.2. Creating a Database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="managing-databases.html" title="Chapter 23. Managing Databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-config.html" title="23.4. Database Configuration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.2. Creating a Database </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.4. Database Configuration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/managing-databases.html b/doc/src/sgml/html/managing-databases.html
new file mode 100644
index 0000000..5326315
--- /dev/null
+++ b/doc/src/sgml/html/managing-databases.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 23. Managing Databases</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="perm-functions.html" title="22.6. Function Security" /><link rel="next" href="manage-ag-overview.html" title="23.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 23. Managing Databases</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="perm-functions.html" title="22.6. Function Security">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="manage-ag-overview.html" title="23.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="MANAGING-DATABASES"><div class="titlepage"><div><div><h2 class="title">Chapter 23. Managing Databases</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="manage-ag-overview.html">23.1. Overview</a></span></dt><dt><span class="sect1"><a href="manage-ag-createdb.html">23.2. Creating a Database</a></span></dt><dt><span class="sect1"><a href="manage-ag-templatedbs.html">23.3. Template Databases</a></span></dt><dt><span class="sect1"><a href="manage-ag-config.html">23.4. Database Configuration</a></span></dt><dt><span class="sect1"><a href="manage-ag-dropdb.html">23.5. Destroying a Database</a></span></dt><dt><span class="sect1"><a href="manage-ag-tablespaces.html">23.6. Tablespaces</a></span></dt></dl></div><a id="id-1.6.10.2" class="indexterm"></a><p>
+ Every instance of a running <span class="productname">PostgreSQL</span>
+ server manages one or more databases. Databases are therefore the
+ topmost hierarchical level for organizing <acronym class="acronym">SQL</acronym>
+ objects (<span class="quote">“<span class="quote">database objects</span>”</span>). This chapter describes
+ the properties of databases, and how to create, manage, and destroy
+ them.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="perm-functions.html" title="22.6. Function Security">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="manage-ag-overview.html" title="23.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.6. Function Security </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 23.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/monitoring-locks.html b/doc/src/sgml/html/monitoring-locks.html
new file mode 100644
index 0000000..aa5acb2
--- /dev/null
+++ b/doc/src/sgml/html/monitoring-locks.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>28.3. Viewing Locks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System" /><link rel="next" href="progress-reporting.html" title="28.4. Progress Reporting" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">28.3. Viewing Locks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="progress-reporting.html" title="28.4. Progress Reporting">Next</a></td></tr></table><hr /></div><div class="sect1" id="MONITORING-LOCKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">28.3. Viewing Locks</h2></div></div></div><a id="id-1.6.15.8.2" class="indexterm"></a><p>
+ Another useful tool for monitoring database activity is the
+ <code class="structname">pg_locks</code> system table. It allows the
+ database administrator to view information about the outstanding
+ locks in the lock manager. For example, this capability can be used
+ to:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ View all the locks currently outstanding, all the locks on
+ relations in a particular database, all the locks on a
+ particular relation, or all the locks held by a particular
+ <span class="productname">PostgreSQL</span> session.
+ </p></li><li class="listitem"><p>
+ Determine the relation in the current database with the most
+ ungranted locks (which might be a source of contention among
+ database clients).
+ </p></li><li class="listitem"><p>
+ Determine the effect of lock contention on overall database
+ performance, as well as the extent to which contention varies
+ with overall database traffic.
+ </p></li></ul></div><p>
+
+ Details of the <code class="structname">pg_locks</code> view appear in
+ <a class="xref" href="view-pg-locks.html" title="54.12. pg_locks">Section 54.12</a>.
+ For more information on locking and managing concurrency with
+ <span class="productname">PostgreSQL</span>, refer to <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="progress-reporting.html" title="28.4. Progress Reporting">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.2. The Cumulative Statistics System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 28.4. Progress Reporting</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/monitoring-ps.html b/doc/src/sgml/html/monitoring-ps.html
new file mode 100644
index 0000000..a611166
--- /dev/null
+++ b/doc/src/sgml/html/monitoring-ps.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>28.1. Standard Unix Tools</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="monitoring.html" title="Chapter 28. Monitoring Database Activity" /><link rel="next" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">28.1. Standard Unix Tools</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Next</a></td></tr></table><hr /></div><div class="sect1" id="MONITORING-PS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">28.1. Standard Unix Tools</h2></div></div></div><a id="id-1.6.15.6.2" class="indexterm"></a><p>
+ On most Unix platforms, <span class="productname">PostgreSQL</span> modifies its
+ command title as reported by <code class="command">ps</code>, so that individual server
+ processes can readily be identified. A sample display is
+
+</p><pre class="screen">
+$ ps auxww | grep ^postgres
+postgres 15551 0.0 0.1 57536 7132 pts/0 S 18:02 0:00 postgres -i
+postgres 15554 0.0 0.0 57536 1184 ? Ss 18:02 0:00 postgres: background writer
+postgres 15555 0.0 0.0 57536 916 ? Ss 18:02 0:00 postgres: checkpointer
+postgres 15556 0.0 0.0 57536 916 ? Ss 18:02 0:00 postgres: walwriter
+postgres 15557 0.0 0.0 58504 2244 ? Ss 18:02 0:00 postgres: autovacuum launcher
+postgres 15582 0.0 0.0 58772 3080 ? Ss 18:04 0:00 postgres: joe runbug 127.0.0.1 idle
+postgres 15606 0.0 0.0 58772 3052 ? Ss 18:07 0:00 postgres: tgl regression [local] SELECT waiting
+postgres 15610 0.0 0.0 58772 3056 ? Ss 18:07 0:00 postgres: tgl regression [local] idle in transaction
+</pre><p>
+
+ (The appropriate invocation of <code class="command">ps</code> varies across different
+ platforms, as do the details of what is shown. This example is from a
+ recent Linux system.) The first process listed here is the
+ primary server process. The command arguments
+ shown for it are the same ones used when it was launched. The next four
+ processes are background worker processes automatically launched by the
+ primary process. (The <span class="quote">“<span class="quote">autovacuum launcher</span>”</span> process will not
+ be present if you have set the system not to run autovacuum.)
+ Each of the remaining
+ processes is a server process handling one client connection. Each such
+ process sets its command line display in the form
+
+</p><pre class="screen">
+postgres: <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>host</code></em> <em class="replaceable"><code>activity</code></em>
+</pre><p>
+
+ The user, database, and (client) host items remain the same for
+ the life of the client connection, but the activity indicator changes.
+ The activity can be <code class="literal">idle</code> (i.e., waiting for a client command),
+ <code class="literal">idle in transaction</code> (waiting for client inside a <code class="command">BEGIN</code> block),
+ or a command type name such as <code class="literal">SELECT</code>. Also,
+ <code class="literal">waiting</code> is appended if the server process is presently waiting
+ on a lock held by another session. In the above example we can infer
+ that process 15606 is waiting for process 15610 to complete its transaction
+ and thereby release some lock. (Process 15610 must be the blocker, because
+ there is no other active session. In more complicated cases it would be
+ necessary to look into the
+ <a class="link" href="view-pg-locks.html" title="54.12. pg_locks"><code class="structname">pg_locks</code></a>
+ system view to determine who is blocking whom.)
+ </p><p>
+ If <a class="xref" href="runtime-config-logging.html#GUC-CLUSTER-NAME">cluster_name</a> has been configured the
+ cluster name will also be shown in <code class="command">ps</code> output:
+</p><pre class="screen">
+$ psql -c 'SHOW cluster_name'
+ cluster_name
+--------------
+ server1
+(1 row)
+
+$ ps aux|grep server1
+postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: server1: background writer
+...
+</pre><p>
+ </p><p>
+ If you have turned off <a class="xref" href="runtime-config-logging.html#GUC-UPDATE-PROCESS-TITLE">update_process_title</a> then the
+ activity indicator is not updated; the process title is set only once
+ when a new process is launched. On some platforms this saves a measurable
+ amount of per-command overhead; on others it's insignificant.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <span class="productname">Solaris</span> requires special handling. You must
+ use <code class="command">/usr/ucb/ps</code>, rather than
+ <code class="command">/bin/ps</code>. You also must use two <code class="option">w</code>
+ flags, not just one. In addition, your original invocation of the
+ <code class="command">postgres</code> command must have a shorter
+ <code class="command">ps</code> status display than that provided by each
+ server process. If you fail to do all three things, the <code class="command">ps</code>
+ output for each server process will be the original <code class="command">postgres</code>
+ command line.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 28. Monitoring Database Activity </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 28.2. The Cumulative Statistics System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/monitoring-stats.html b/doc/src/sgml/html/monitoring-stats.html
new file mode 100644
index 0000000..ba45c56
--- /dev/null
+++ b/doc/src/sgml/html/monitoring-stats.html
@@ -0,0 +1,2470 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>28.2. The Cumulative Statistics System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="monitoring-ps.html" title="28.1. Standard Unix Tools" /><link rel="next" href="monitoring-locks.html" title="28.3. Viewing Locks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">28.2. The Cumulative Statistics System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="monitoring-locks.html" title="28.3. Viewing Locks">Next</a></td></tr></table><hr /></div><div class="sect1" id="MONITORING-STATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">28.2. The Cumulative Statistics System</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-SETUP">28.2.1. Statistics Collection Configuration</a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-VIEWS">28.2.2. Viewing Statistics</a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW">28.2.3. <code class="structname">pg_stat_activity</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW">28.2.4. <code class="structname">pg_stat_replication</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW">28.2.5. <code class="structname">pg_stat_replication_slots</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-WAL-RECEIVER-VIEW">28.2.6. <code class="structname">pg_stat_wal_receiver</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-RECOVERY-PREFETCH">28.2.7. <code class="structname">pg_stat_recovery_prefetch</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION">28.2.8. <code class="structname">pg_stat_subscription</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION-STATS">28.2.9. <code class="structname">pg_stat_subscription_stats</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW">28.2.10. <code class="structname">pg_stat_ssl</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-GSSAPI-VIEW">28.2.11. <code class="structname">pg_stat_gssapi</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ARCHIVER-VIEW">28.2.12. <code class="structname">pg_stat_archiver</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-BGWRITER-VIEW">28.2.13. <code class="structname">pg_stat_bgwriter</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-WAL-VIEW">28.2.14. <code class="structname">pg_stat_wal</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW">28.2.15. <code class="structname">pg_stat_database</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW">28.2.16. <code class="structname">pg_stat_database_conflicts</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW">28.2.17. <code class="structname">pg_stat_all_tables</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ALL-INDEXES-VIEW">28.2.18. <code class="structname">pg_stat_all_indexes</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-TABLES-VIEW">28.2.19. <code class="structname">pg_statio_all_tables</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-INDEXES-VIEW">28.2.20. <code class="structname">pg_statio_all_indexes</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-SEQUENCES-VIEW">28.2.21. <code class="structname">pg_statio_all_sequences</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-USER-FUNCTIONS-VIEW">28.2.22. <code class="structname">pg_stat_user_functions</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SLRU-VIEW">28.2.23. <code class="structname">pg_stat_slru</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">28.2.24. Statistics Functions</a></span></dt></dl></div><a id="id-1.6.15.7.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span>'s <em class="firstterm">cumulative statistics
+ system</em> supports collection and reporting of information about
+ server activity. Presently, accesses to tables and indexes in both
+ disk-block and individual-row terms are counted. The total number of rows
+ in each table, and information about vacuum and analyze actions for each
+ table are also counted. If enabled, calls to user-defined functions and
+ the total time spent in each one are counted as well.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also supports reporting dynamic
+ information about exactly what is going on in the system right now, such as
+ the exact command currently being executed by other server processes, and
+ which other connections exist in the system. This facility is independent
+ of the cumulative statistics system.
+ </p><div class="sect2" id="MONITORING-STATS-SETUP"><div class="titlepage"><div><div><h3 class="title">28.2.1. Statistics Collection Configuration</h3></div></div></div><p>
+ Since collection of statistics adds some overhead to query execution,
+ the system can be configured to collect or not collect information.
+ This is controlled by configuration parameters that are normally set in
+ <code class="filename">postgresql.conf</code>. (See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for
+ details about setting configuration parameters.)
+ </p><p>
+ The parameter <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-ACTIVITIES">track_activities</a> enables monitoring
+ of the current command being executed by any server process.
+ </p><p>
+ The parameter <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-COUNTS">track_counts</a> controls whether
+ cumulative statistics are collected about table and index accesses.
+ </p><p>
+ The parameter <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-FUNCTIONS">track_functions</a> enables tracking of
+ usage of user-defined functions.
+ </p><p>
+ The parameter <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> enables monitoring
+ of block read and write times.
+ </p><p>
+ The parameter <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-WAL-IO-TIMING">track_wal_io_timing</a> enables monitoring
+ of WAL write times.
+ </p><p>
+ Normally these parameters are set in <code class="filename">postgresql.conf</code> so
+ that they apply to all server processes, but it is possible to turn
+ them on or off in individual sessions using the <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> command. (To prevent
+ ordinary users from hiding their activity from the administrator,
+ only superusers are allowed to change these parameters with
+ <code class="command">SET</code>.)
+ </p><p>
+ Cumulative statistics are collected in shared memory. Every
+ <span class="productname">PostgreSQL</span> process collects statistics locally,
+ then updates the shared data at appropriate intervals. When a server,
+ including a physical replica, shuts down cleanly, a permanent copy of the
+ statistics data is stored in the <code class="filename">pg_stat</code> subdirectory,
+ so that statistics can be retained across server restarts. In contrast,
+ when starting from an unclean shutdown (e.g., after an immediate shutdown,
+ a server crash, starting from a base backup, and point-in-time recovery),
+ all statistics counters are reset.
+ </p></div><div class="sect2" id="MONITORING-STATS-VIEWS"><div class="titlepage"><div><div><h3 class="title">28.2.2. Viewing Statistics</h3></div></div></div><p>
+ Several predefined views, listed in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-DYNAMIC-VIEWS-TABLE" title="Table 28.1. Dynamic Statistics Views">Table 28.1</a>, are available to show
+ the current state of the system. There are also several other
+ views, listed in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-VIEWS-TABLE" title="Table 28.2. Collected Statistics Views">Table 28.2</a>, available to show the accumulated
+ statistics. Alternatively, one can
+ build custom views using the underlying cumulative statistics functions, as
+ discussed in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS" title="28.2.24. Statistics Functions">Section 28.2.24</a>.
+ </p><p>
+ When using the cumulative statistics views and functions to monitor
+ collected data, it is important to realize that the information does not
+ update instantaneously. Each individual server process flushes out
+ accumulated statistics to shared memory just before going idle, but not
+ more frequently than once per <code class="varname">PGSTAT_MIN_INTERVAL</code>
+ milliseconds (1 second unless altered while building the server); so a
+ query or transaction still in progress does not affect the displayed totals
+ and the displayed information lags behind actual activity. However,
+ current-query information collected by <code class="varname">track_activities</code>
+ is always up-to-date.
+ </p><p>
+ Another important point is that when a server process is asked to display
+ any of the accumulated statistics, accessed values are cached until the end
+ of its current transaction in the default configuration. So the statistics
+ will show static information as long as you continue the current
+ transaction. Similarly, information about the current queries of all
+ sessions is collected when any such information is first requested within a
+ transaction, and the same information will be displayed throughout the
+ transaction. This is a feature, not a bug, because it allows you to perform
+ several queries on the statistics and correlate the results without
+ worrying that the numbers are changing underneath you.
+
+ When analyzing statistics interactively, or with expensive queries, the
+ time delta between accesses to individual statistics can lead to
+ significant skew in the cached statistics. To minimize skew,
+ <code class="varname">stats_fetch_consistency</code> can be set to
+ <code class="literal">snapshot</code>, at the price of increased memory usage for
+ caching not-needed statistics data. Conversely, if it's known that
+ statistics are only accessed once, caching accessed statistics is
+ unnecessary and can be avoided by setting
+ <code class="varname">stats_fetch_consistency</code> to <code class="literal">none</code>.
+
+ You can invoke <code class="function">pg_stat_clear_snapshot</code>() to discard the
+ current transaction's statistics snapshot or cached values (if any). The
+ next use of statistical information will (when in snapshot mode) cause a
+ new snapshot to be built or (when in cache mode) accessed statistics to be
+ cached.
+ </p><p>
+ A transaction can also see its own statistics (not yet flushed out to the
+ shared memory statistics) in the views
+ <code class="structname">pg_stat_xact_all_tables</code>,
+ <code class="structname">pg_stat_xact_sys_tables</code>,
+ <code class="structname">pg_stat_xact_user_tables</code>, and
+ <code class="structname">pg_stat_xact_user_functions</code>. These numbers do not act as
+ stated above; instead they update continuously throughout the transaction.
+ </p><p>
+ Some of the information in the dynamic statistics views shown in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-DYNAMIC-VIEWS-TABLE" title="Table 28.1. Dynamic Statistics Views">Table 28.1</a> is security restricted.
+ Ordinary users can only see all the information about their own sessions
+ (sessions belonging to a role that they are a member of). In rows about
+ other sessions, many columns will be null. Note, however, that the
+ existence of a session and its general properties such as its sessions user
+ and database are visible to all users. Superusers and roles with privileges of
+ built-in role <code class="literal">pg_read_all_stats</code> (see also <a class="xref" href="predefined-roles.html" title="22.5. Predefined Roles">Section 22.5</a>) can see all the information about all sessions.
+ </p><div class="table" id="MONITORING-STATS-DYNAMIC-VIEWS-TABLE"><p class="title"><strong>Table 28.1. Dynamic Statistics Views</strong></p><div class="table-contents"><table class="table" summary="Dynamic Statistics Views" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>View Name</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="structname">pg_stat_activity</code>
+ <a id="id-1.6.15.7.6.7.2.2.1.1.2" class="indexterm"></a>
+ </td><td>
+ One row per server process, showing information related to
+ the current activity of that process, such as state and current query.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">
+ <code class="structname">pg_stat_activity</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_replication</code><a id="id-1.6.15.7.6.7.2.2.2.1.2" class="indexterm"></a></td><td>One row per WAL sender process, showing statistics about
+ replication to that sender's connected standby server.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication">
+ <code class="structname">pg_stat_replication</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_wal_receiver</code><a id="id-1.6.15.7.6.7.2.2.3.1.2" class="indexterm"></a></td><td>Only one row, showing statistics about the WAL receiver from
+ that receiver's connected server.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-RECEIVER-VIEW" title="28.2.6. pg_stat_wal_receiver">
+ <code class="structname">pg_stat_wal_receiver</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_recovery_prefetch</code><a id="id-1.6.15.7.6.7.2.2.4.1.2" class="indexterm"></a></td><td>Only one row, showing statistics about blocks prefetched during recovery.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-RECOVERY-PREFETCH" title="28.2.7. pg_stat_recovery_prefetch">
+ <code class="structname">pg_stat_recovery_prefetch</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_subscription</code><a id="id-1.6.15.7.6.7.2.2.5.1.2" class="indexterm"></a></td><td>At least one row per subscription, showing information about
+ the subscription workers.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION" title="28.2.8. pg_stat_subscription">
+ <code class="structname">pg_stat_subscription</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_ssl</code><a id="id-1.6.15.7.6.7.2.2.6.1.2" class="indexterm"></a></td><td>One row per connection (regular and replication), showing information about
+ SSL used on this connection.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW" title="28.2.10. pg_stat_ssl">
+ <code class="structname">pg_stat_ssl</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_gssapi</code><a id="id-1.6.15.7.6.7.2.2.7.1.2" class="indexterm"></a></td><td>One row per connection (regular and replication), showing information about
+ GSSAPI authentication and encryption used on this connection.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-GSSAPI-VIEW" title="28.2.11. pg_stat_gssapi">
+ <code class="structname">pg_stat_gssapi</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_analyze</code><a id="id-1.6.15.7.6.7.2.2.8.1.2" class="indexterm"></a></td><td>One row for each backend (including autovacuum worker processes) running
+ <code class="command">ANALYZE</code>, showing current progress.
+ See <a class="xref" href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING" title="28.4.1. ANALYZE Progress Reporting">Section 28.4.1</a>.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_create_index</code><a id="id-1.6.15.7.6.7.2.2.9.1.2" class="indexterm"></a></td><td>One row for each backend running <code class="command">CREATE INDEX</code> or <code class="command">REINDEX</code>, showing
+ current progress.
+ See <a class="xref" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING" title="28.4.2. CREATE INDEX Progress Reporting">Section 28.4.2</a>.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_vacuum</code><a id="id-1.6.15.7.6.7.2.2.10.1.2" class="indexterm"></a></td><td>One row for each backend (including autovacuum worker processes) running
+ <code class="command">VACUUM</code>, showing current progress.
+ See <a class="xref" href="progress-reporting.html#VACUUM-PROGRESS-REPORTING" title="28.4.3. VACUUM Progress Reporting">Section 28.4.3</a>.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_cluster</code><a id="id-1.6.15.7.6.7.2.2.11.1.2" class="indexterm"></a></td><td>One row for each backend running
+ <code class="command">CLUSTER</code> or <code class="command">VACUUM FULL</code>, showing current progress.
+ See <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a>.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_basebackup</code><a id="id-1.6.15.7.6.7.2.2.12.1.2" class="indexterm"></a></td><td>One row for each WAL sender process streaming a base backup,
+ showing current progress.
+ See <a class="xref" href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING" title="28.4.5. Base Backup Progress Reporting">Section 28.4.5</a>.
+ </td></tr><tr><td><code class="structname">pg_stat_progress_copy</code><a id="id-1.6.15.7.6.7.2.2.13.1.2" class="indexterm"></a></td><td>One row for each backend running <code class="command">COPY</code>, showing current progress.
+ See <a class="xref" href="progress-reporting.html#COPY-PROGRESS-REPORTING" title="28.4.6. COPY Progress Reporting">Section 28.4.6</a>.
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="MONITORING-STATS-VIEWS-TABLE"><p class="title"><strong>Table 28.2. Collected Statistics Views</strong></p><div class="table-contents"><table class="table" summary="Collected Statistics Views" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>View Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="structname">pg_stat_archiver</code><a id="id-1.6.15.7.6.8.2.2.1.1.2" class="indexterm"></a></td><td>One row only, showing statistics about the
+ WAL archiver process's activity. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ARCHIVER-VIEW" title="28.2.12. pg_stat_archiver">
+ <code class="structname">pg_stat_archiver</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_bgwriter</code><a id="id-1.6.15.7.6.8.2.2.2.1.2" class="indexterm"></a></td><td>One row only, showing statistics about the
+ background writer process's activity. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-BGWRITER-VIEW" title="28.2.13. pg_stat_bgwriter">
+ <code class="structname">pg_stat_bgwriter</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_wal</code><a id="id-1.6.15.7.6.8.2.2.3.1.2" class="indexterm"></a></td><td>One row only, showing statistics about WAL activity. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-VIEW" title="28.2.14. pg_stat_wal">
+ <code class="structname">pg_stat_wal</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_database</code><a id="id-1.6.15.7.6.8.2.2.4.1.2" class="indexterm"></a></td><td>One row per database, showing database-wide statistics. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW" title="28.2.15. pg_stat_database">
+ <code class="structname">pg_stat_database</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_database_conflicts</code><a id="id-1.6.15.7.6.8.2.2.5.1.2" class="indexterm"></a></td><td>
+ One row per database, showing database-wide statistics about
+ query cancels due to conflict with recovery on standby servers.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW" title="28.2.16. pg_stat_database_conflicts">
+ <code class="structname">pg_stat_database_conflicts</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_all_tables</code><a id="id-1.6.15.7.6.8.2.2.6.1.2" class="indexterm"></a></td><td>
+ One row for each table in the current database, showing statistics
+ about accesses to that specific table.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW" title="28.2.17. pg_stat_all_tables">
+ <code class="structname">pg_stat_all_tables</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_sys_tables</code><a id="id-1.6.15.7.6.8.2.2.7.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_all_tables</code>, except that only
+ system tables are shown.</td></tr><tr><td><code class="structname">pg_stat_user_tables</code><a id="id-1.6.15.7.6.8.2.2.8.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_all_tables</code>, except that only user
+ tables are shown.</td></tr><tr><td><code class="structname">pg_stat_xact_all_tables</code><a id="id-1.6.15.7.6.8.2.2.9.1.2" class="indexterm"></a></td><td>Similar to <code class="structname">pg_stat_all_tables</code>, but counts actions
+ taken so far within the current transaction (which are <span class="emphasis"><em>not</em></span>
+ yet included in <code class="structname">pg_stat_all_tables</code> and related views).
+ The columns for numbers of live and dead rows and vacuum and
+ analyze actions are not present in this view.</td></tr><tr><td><code class="structname">pg_stat_xact_sys_tables</code><a id="id-1.6.15.7.6.8.2.2.10.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_xact_all_tables</code>, except that only
+ system tables are shown.</td></tr><tr><td><code class="structname">pg_stat_xact_user_tables</code><a id="id-1.6.15.7.6.8.2.2.11.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_xact_all_tables</code>, except that only
+ user tables are shown.</td></tr><tr><td><code class="structname">pg_stat_all_indexes</code><a id="id-1.6.15.7.6.8.2.2.12.1.2" class="indexterm"></a></td><td>
+ One row for each index in the current database, showing statistics
+ about accesses to that specific index.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ALL-INDEXES-VIEW" title="28.2.18. pg_stat_all_indexes">
+ <code class="structname">pg_stat_all_indexes</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_sys_indexes</code><a id="id-1.6.15.7.6.8.2.2.13.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_all_indexes</code>, except that only
+ indexes on system tables are shown.</td></tr><tr><td><code class="structname">pg_stat_user_indexes</code><a id="id-1.6.15.7.6.8.2.2.14.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_stat_all_indexes</code>, except that only
+ indexes on user tables are shown.</td></tr><tr><td><code class="structname">pg_statio_all_tables</code><a id="id-1.6.15.7.6.8.2.2.15.1.2" class="indexterm"></a></td><td>
+ One row for each table in the current database, showing statistics
+ about I/O on that specific table.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-TABLES-VIEW" title="28.2.19. pg_statio_all_tables">
+ <code class="structname">pg_statio_all_tables</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_statio_sys_tables</code><a id="id-1.6.15.7.6.8.2.2.16.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_tables</code>, except that only
+ system tables are shown.</td></tr><tr><td><code class="structname">pg_statio_user_tables</code><a id="id-1.6.15.7.6.8.2.2.17.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_tables</code>, except that only
+ user tables are shown.</td></tr><tr><td><code class="structname">pg_statio_all_indexes</code><a id="id-1.6.15.7.6.8.2.2.18.1.2" class="indexterm"></a></td><td>
+ One row for each index in the current database,
+ showing statistics about I/O on that specific index.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-INDEXES-VIEW" title="28.2.20. pg_statio_all_indexes">
+ <code class="structname">pg_statio_all_indexes</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_statio_sys_indexes</code><a id="id-1.6.15.7.6.8.2.2.19.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_indexes</code>, except that only
+ indexes on system tables are shown.</td></tr><tr><td><code class="structname">pg_statio_user_indexes</code><a id="id-1.6.15.7.6.8.2.2.20.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_indexes</code>, except that only
+ indexes on user tables are shown.</td></tr><tr><td><code class="structname">pg_statio_all_sequences</code><a id="id-1.6.15.7.6.8.2.2.21.1.2" class="indexterm"></a></td><td>
+ One row for each sequence in the current database,
+ showing statistics about I/O on that specific sequence.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-SEQUENCES-VIEW" title="28.2.21. pg_statio_all_sequences">
+ <code class="structname">pg_statio_all_sequences</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_statio_sys_sequences</code><a id="id-1.6.15.7.6.8.2.2.22.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_sequences</code>, except that only
+ system sequences are shown. (Presently, no system sequences are defined,
+ so this view is always empty.)</td></tr><tr><td><code class="structname">pg_statio_user_sequences</code><a id="id-1.6.15.7.6.8.2.2.23.1.2" class="indexterm"></a></td><td>Same as <code class="structname">pg_statio_all_sequences</code>, except that only
+ user sequences are shown.</td></tr><tr><td><code class="structname">pg_stat_user_functions</code><a id="id-1.6.15.7.6.8.2.2.24.1.2" class="indexterm"></a></td><td>
+ One row for each tracked function, showing statistics
+ about executions of that function. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-USER-FUNCTIONS-VIEW" title="28.2.22. pg_stat_user_functions">
+ <code class="structname">pg_stat_user_functions</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_xact_user_functions</code><a id="id-1.6.15.7.6.8.2.2.25.1.2" class="indexterm"></a></td><td>Similar to <code class="structname">pg_stat_user_functions</code>, but counts only
+ calls during the current transaction (which are <span class="emphasis"><em>not</em></span>
+ yet included in <code class="structname">pg_stat_user_functions</code>).</td></tr><tr><td><code class="structname">pg_stat_slru</code><a id="id-1.6.15.7.6.8.2.2.26.1.2" class="indexterm"></a></td><td>One row per SLRU, showing statistics of operations. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SLRU-VIEW" title="28.2.23. pg_stat_slru">
+ <code class="structname">pg_stat_slru</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_replication_slots</code><a id="id-1.6.15.7.6.8.2.2.27.1.2" class="indexterm"></a></td><td>One row per replication slot, showing statistics about the
+ replication slot's usage. See
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW" title="28.2.5. pg_stat_replication_slots">
+ <code class="structname">pg_stat_replication_slots</code></a> for details.
+ </td></tr><tr><td><code class="structname">pg_stat_subscription_stats</code><a id="id-1.6.15.7.6.8.2.2.28.1.2" class="indexterm"></a></td><td>One row per subscription, showing statistics about errors.
+ See <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION-STATS" title="28.2.9. pg_stat_subscription_stats">
+ <code class="structname">pg_stat_subscription_stats</code></a> for details.
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The per-index statistics are particularly useful to determine which
+ indexes are being used and how effective they are.
+ </p><p>
+ The <code class="structname">pg_statio_</code> views are primarily useful to
+ determine the effectiveness of the buffer cache. When the number
+ of actual disk reads is much smaller than the number of buffer
+ hits, then the cache is satisfying most read requests without
+ invoking a kernel call. However, these statistics do not give the
+ entire story: due to the way in which <span class="productname">PostgreSQL</span>
+ handles disk I/O, data that is not in the
+ <span class="productname">PostgreSQL</span> buffer cache might still reside in the
+ kernel's I/O cache, and might therefore still be fetched without
+ requiring a physical read. Users interested in obtaining more
+ detailed information on <span class="productname">PostgreSQL</span> I/O behavior are
+ advised to use the <span class="productname">PostgreSQL</span> statistics views
+ in combination with operating system utilities that allow insight
+ into the kernel's handling of I/O.
+ </p></div><div class="sect2" id="MONITORING-PG-STAT-ACTIVITY-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.3. <code class="structname">pg_stat_activity</code></h3></div></div></div><a id="id-1.6.15.7.7.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_activity</code> view will have one row
+ per server process, showing information related to
+ the current activity of that process.
+ </p><div class="table" id="PG-STAT-ACTIVITY-VIEW"><p class="title"><strong>Table 28.3. <code class="structname">pg_stat_activity</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_activity View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database this backend is connected to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database this backend is connected to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of this backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">leader_pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of the parallel group leader, if this process is a
+ parallel query worker. <code class="literal">NULL</code> if this process is a
+ parallel group leader or does not participate in parallel query.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesysid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the user logged into this backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usename</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the user logged into this backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">application_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the application that is connected
+ to this backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_addr</code> <code class="type">inet</code>
+ </p>
+ <p>
+ IP address of the client connected to this backend.
+ If this field is null, it indicates either that the client is
+ connected via a Unix socket on the server machine or that this is an
+ internal process such as autovacuum.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_hostname</code> <code class="type">text</code>
+ </p>
+ <p>
+ Host name of the connected client, as reported by a
+ reverse DNS lookup of <code class="structfield">client_addr</code>. This field will
+ only be non-null for IP connections, and only when <a class="xref" href="runtime-config-logging.html#GUC-LOG-HOSTNAME">log_hostname</a> is enabled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_port</code> <code class="type">integer</code>
+ </p>
+ <p>
+ TCP port number that the client is using for communication
+ with this backend, or <code class="literal">-1</code> if a Unix socket is used.
+ If this field is null, it indicates that this is an internal server process.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_start</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time when this process was started. For client backends,
+ this is the time the client connected to the server.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">xact_start</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time when this process' current transaction was started, or null
+ if no transaction is active. If the current
+ query is the first of its transaction, this column is equal to the
+ <code class="structfield">query_start</code> column.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">query_start</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time when the currently active query was started, or if
+ <code class="structfield">state</code> is not <code class="literal">active</code>, when the last query
+ was started
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">state_change</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time when the <code class="structfield">state</code> was last changed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wait_event_type</code> <code class="type">text</code>
+ </p>
+ <p>
+ The type of event for which the backend is waiting, if any;
+ otherwise NULL. See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-TABLE" title="Table 28.4. Wait Event Types">Table 28.4</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wait_event</code> <code class="type">text</code>
+ </p>
+ <p>
+ Wait event name if backend is currently waiting, otherwise NULL.
+ See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-ACTIVITY-TABLE" title="Table 28.5. Wait Events of Type Activity">Table 28.5</a> through
+ <a class="xref" href="monitoring-stats.html#WAIT-EVENT-TIMEOUT-TABLE" title="Table 28.13. Wait Events of Type Timeout">Table 28.13</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">state</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current overall state of this backend.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">active</code>: The backend is executing a query.
+ </p></li><li class="listitem"><p>
+ <code class="literal">idle</code>: The backend is waiting for a new client command.
+ </p></li><li class="listitem"><p>
+ <code class="literal">idle in transaction</code>: The backend is in a transaction,
+ but is not currently executing a query.
+ </p></li><li class="listitem"><p>
+ <code class="literal">idle in transaction (aborted)</code>: This state is similar to
+ <code class="literal">idle in transaction</code>, except one of the statements in
+ the transaction caused an error.
+ </p></li><li class="listitem"><p>
+ <code class="literal">fastpath function call</code>: The backend is executing a
+ fast-path function.
+ </p></li><li class="listitem"><p>
+ <code class="literal">disabled</code>: This state is reported if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-ACTIVITIES">track_activities</a> is disabled in this backend.
+ </p></li></ul></div><p>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_xid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ Top-level transaction identifier of this backend, if any.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_xmin</code> <code class="type">xid</code>
+ </p>
+ <p>
+ The current backend's <code class="literal">xmin</code> horizon.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">query_id</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Identifier of this backend's most recent query. If
+ <code class="structfield">state</code> is <code class="literal">active</code> this
+ field shows the identifier of the currently executing query. In
+ all other states, it shows the identifier of last query that was
+ executed. Query identifiers are not computed by default so this
+ field will be null unless <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a>
+ parameter is enabled or a third-party module that computes query
+ identifiers is configured.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">query</code> <code class="type">text</code>
+ </p>
+ <p>
+ Text of this backend's most recent query. If
+ <code class="structfield">state</code> is <code class="literal">active</code> this field shows the
+ currently executing query. In all other states, it shows the last query
+ that was executed. By default the query text is truncated at 1024
+ bytes; this value can be changed via the parameter
+ <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-ACTIVITY-QUERY-SIZE">track_activity_query_size</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_type</code> <code class="type">text</code>
+ </p>
+ <p>
+ Type of current backend. Possible types are
+ <code class="literal">autovacuum launcher</code>, <code class="literal">autovacuum worker</code>,
+ <code class="literal">logical replication launcher</code>,
+ <code class="literal">logical replication worker</code>,
+ <code class="literal">parallel worker</code>, <code class="literal">background writer</code>,
+ <code class="literal">client backend</code>, <code class="literal">checkpointer</code>,
+ <code class="literal">archiver</code>,
+ <code class="literal">startup</code>, <code class="literal">walreceiver</code>,
+ <code class="literal">walsender</code> and <code class="literal">walwriter</code>.
+ In addition, background workers registered by extensions may have
+ additional types.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="structfield">wait_event</code> and <code class="structfield">state</code> columns are
+ independent. If a backend is in the <code class="literal">active</code> state,
+ it may or may not be <code class="literal">waiting</code> on some event. If the state
+ is <code class="literal">active</code> and <code class="structfield">wait_event</code> is non-null, it
+ means that a query is being executed, but is being blocked somewhere
+ in the system.
+ </p></div><div class="table" id="WAIT-EVENT-TABLE"><p class="title"><strong>Table 28.4. Wait Event Types</strong></p><div class="table-contents"><table class="table" summary="Wait Event Types" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Wait Event Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">Activity</code></td><td>The server process is idle. This event type indicates a process
+ waiting for activity in its main processing loop.
+ <code class="literal">wait_event</code> will identify the specific wait point;
+ see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-ACTIVITY-TABLE" title="Table 28.5. Wait Events of Type Activity">Table 28.5</a>.
+ </td></tr><tr><td><code class="literal">BufferPin</code></td><td>The server process is waiting for exclusive access to
+ a data buffer. Buffer pin waits can be protracted if
+ another process holds an open cursor that last read data from the
+ buffer in question. See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-BUFFERPIN-TABLE" title="Table 28.6. Wait Events of Type BufferPin">Table 28.6</a>.
+ </td></tr><tr><td><code class="literal">Client</code></td><td>The server process is waiting for activity on a socket
+ connected to a user application. Thus, the server expects something
+ to happen that is independent of its internal processes.
+ <code class="literal">wait_event</code> will identify the specific wait point;
+ see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-CLIENT-TABLE" title="Table 28.7. Wait Events of Type Client">Table 28.7</a>.
+ </td></tr><tr><td><code class="literal">Extension</code></td><td>The server process is waiting for some condition defined by an
+ extension module.
+ See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-EXTENSION-TABLE" title="Table 28.8. Wait Events of Type Extension">Table 28.8</a>.
+ </td></tr><tr><td><code class="literal">IO</code></td><td>The server process is waiting for an I/O operation to complete.
+ <code class="literal">wait_event</code> will identify the specific wait point;
+ see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-IO-TABLE" title="Table 28.9. Wait Events of Type IO">Table 28.9</a>.
+ </td></tr><tr><td><code class="literal">IPC</code></td><td>The server process is waiting for some interaction with
+ another server process. <code class="literal">wait_event</code> will
+ identify the specific wait point;
+ see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-IPC-TABLE" title="Table 28.10. Wait Events of Type IPC">Table 28.10</a>.
+ </td></tr><tr><td><code class="literal">Lock</code></td><td>The server process is waiting for a heavyweight lock.
+ Heavyweight locks, also known as lock manager locks or simply locks,
+ primarily protect SQL-visible objects such as tables. However,
+ they are also used to ensure mutual exclusion for certain internal
+ operations such as relation extension. <code class="literal">wait_event</code>
+ will identify the type of lock awaited;
+ see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-LOCK-TABLE" title="Table 28.11. Wait Events of Type Lock">Table 28.11</a>.
+ </td></tr><tr><td><code class="literal">LWLock</code></td><td> The server process is waiting for a lightweight lock.
+ Most such locks protect a particular data structure in shared memory.
+ <code class="literal">wait_event</code> will contain a name identifying the purpose
+ of the lightweight lock. (Some locks have specific names; others
+ are part of a group of locks each with a similar purpose.)
+ See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-LWLOCK-TABLE" title="Table 28.12. Wait Events of Type LWLock">Table 28.12</a>.
+ </td></tr><tr><td><code class="literal">Timeout</code></td><td>The server process is waiting for a timeout
+ to expire. <code class="literal">wait_event</code> will identify the specific wait
+ point; see <a class="xref" href="monitoring-stats.html#WAIT-EVENT-TIMEOUT-TABLE" title="Table 28.13. Wait Events of Type Timeout">Table 28.13</a>.
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-ACTIVITY-TABLE"><p class="title"><strong>Table 28.5. Wait Events of Type <code class="literal">Activity</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type Activity" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">Activity</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">ArchiverMain</code></td><td>Waiting in main loop of archiver process.</td></tr><tr><td><code class="literal">AutoVacuumMain</code></td><td>Waiting in main loop of autovacuum launcher process.</td></tr><tr><td><code class="literal">BgWriterHibernate</code></td><td>Waiting in background writer process, hibernating.</td></tr><tr><td><code class="literal">BgWriterMain</code></td><td>Waiting in main loop of background writer process.</td></tr><tr><td><code class="literal">CheckpointerMain</code></td><td>Waiting in main loop of checkpointer process.</td></tr><tr><td><code class="literal">LogicalApplyMain</code></td><td>Waiting in main loop of logical replication apply process.</td></tr><tr><td><code class="literal">LogicalLauncherMain</code></td><td>Waiting in main loop of logical replication launcher process.</td></tr><tr><td><code class="literal">RecoveryWalStream</code></td><td>Waiting in main loop of startup process for WAL to arrive, during
+ streaming recovery.</td></tr><tr><td><code class="literal">SysLoggerMain</code></td><td>Waiting in main loop of syslogger process.</td></tr><tr><td><code class="literal">WalReceiverMain</code></td><td>Waiting in main loop of WAL receiver process.</td></tr><tr><td><code class="literal">WalSenderMain</code></td><td>Waiting in main loop of WAL sender process.</td></tr><tr><td><code class="literal">WalWriterMain</code></td><td>Waiting in main loop of WAL writer process.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-BUFFERPIN-TABLE"><p class="title"><strong>Table 28.6. Wait Events of Type <code class="literal">BufferPin</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type BufferPin" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">BufferPin</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">BufferPin</code></td><td>Waiting to acquire an exclusive pin on a buffer.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-CLIENT-TABLE"><p class="title"><strong>Table 28.7. Wait Events of Type <code class="literal">Client</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type Client" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">Client</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">ClientRead</code></td><td>Waiting to read data from the client.</td></tr><tr><td><code class="literal">ClientWrite</code></td><td>Waiting to write data to the client.</td></tr><tr><td><code class="literal">GSSOpenServer</code></td><td>Waiting to read data from the client while establishing a GSSAPI
+ session.</td></tr><tr><td><code class="literal">LibPQWalReceiverConnect</code></td><td>Waiting in WAL receiver to establish connection to remote
+ server.</td></tr><tr><td><code class="literal">LibPQWalReceiverReceive</code></td><td>Waiting in WAL receiver to receive data from remote server.</td></tr><tr><td><code class="literal">SSLOpenServer</code></td><td>Waiting for SSL while attempting connection.</td></tr><tr><td><code class="literal">WalSenderWaitForWAL</code></td><td>Waiting for WAL to be flushed in WAL sender process.</td></tr><tr><td><code class="literal">WalSenderWriteData</code></td><td>Waiting for any activity when processing replies from WAL
+ receiver in WAL sender process.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-EXTENSION-TABLE"><p class="title"><strong>Table 28.8. Wait Events of Type <code class="literal">Extension</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type Extension" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">Extension</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">Extension</code></td><td>Waiting in an extension.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-IO-TABLE"><p class="title"><strong>Table 28.9. Wait Events of Type <code class="literal">IO</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type IO" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">IO</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">BaseBackupRead</code></td><td>Waiting for base backup to read from a file.</td></tr><tr><td><code class="literal">BaseBackupSync</code></td><td>Waiting for data written by a base backup to reach durable storage.</td></tr><tr><td><code class="literal">BaseBackupWrite</code></td><td>Waiting for base backup to write to a file.</td></tr><tr><td><code class="literal">BufFileRead</code></td><td>Waiting for a read from a buffered file.</td></tr><tr><td><code class="literal">BufFileWrite</code></td><td>Waiting for a write to a buffered file.</td></tr><tr><td><code class="literal">BufFileTruncate</code></td><td>Waiting for a buffered file to be truncated.</td></tr><tr><td><code class="literal">ControlFileRead</code></td><td>Waiting for a read from the <code class="filename">pg_control</code>
+ file.</td></tr><tr><td><code class="literal">ControlFileSync</code></td><td>Waiting for the <code class="filename">pg_control</code> file to reach
+ durable storage.</td></tr><tr><td><code class="literal">ControlFileSyncUpdate</code></td><td>Waiting for an update to the <code class="filename">pg_control</code> file
+ to reach durable storage.</td></tr><tr><td><code class="literal">ControlFileWrite</code></td><td>Waiting for a write to the <code class="filename">pg_control</code>
+ file.</td></tr><tr><td><code class="literal">ControlFileWriteUpdate</code></td><td>Waiting for a write to update the <code class="filename">pg_control</code>
+ file.</td></tr><tr><td><code class="literal">CopyFileRead</code></td><td>Waiting for a read during a file copy operation.</td></tr><tr><td><code class="literal">CopyFileWrite</code></td><td>Waiting for a write during a file copy operation.</td></tr><tr><td><code class="literal">DSMFillZeroWrite</code></td><td>Waiting to fill a dynamic shared memory backing file with
+ zeroes.</td></tr><tr><td><code class="literal">DataFileExtend</code></td><td>Waiting for a relation data file to be extended.</td></tr><tr><td><code class="literal">DataFileFlush</code></td><td>Waiting for a relation data file to reach durable storage.</td></tr><tr><td><code class="literal">DataFileImmediateSync</code></td><td>Waiting for an immediate synchronization of a relation data file to
+ durable storage.</td></tr><tr><td><code class="literal">DataFilePrefetch</code></td><td>Waiting for an asynchronous prefetch from a relation data
+ file.</td></tr><tr><td><code class="literal">DataFileRead</code></td><td>Waiting for a read from a relation data file.</td></tr><tr><td><code class="literal">DataFileSync</code></td><td>Waiting for changes to a relation data file to reach durable storage.</td></tr><tr><td><code class="literal">DataFileTruncate</code></td><td>Waiting for a relation data file to be truncated.</td></tr><tr><td><code class="literal">DataFileWrite</code></td><td>Waiting for a write to a relation data file.</td></tr><tr><td><code class="literal">LockFileAddToDataDirRead</code></td><td>Waiting for a read while adding a line to the data directory lock
+ file.</td></tr><tr><td><code class="literal">LockFileAddToDataDirSync</code></td><td>Waiting for data to reach durable storage while adding a line to the
+ data directory lock file.</td></tr><tr><td><code class="literal">LockFileAddToDataDirWrite</code></td><td>Waiting for a write while adding a line to the data directory
+ lock file.</td></tr><tr><td><code class="literal">LockFileCreateRead</code></td><td>Waiting to read while creating the data directory lock
+ file.</td></tr><tr><td><code class="literal">LockFileCreateSync</code></td><td>Waiting for data to reach durable storage while creating the data
+ directory lock file.</td></tr><tr><td><code class="literal">LockFileCreateWrite</code></td><td>Waiting for a write while creating the data directory lock
+ file.</td></tr><tr><td><code class="literal">LockFileReCheckDataDirRead</code></td><td>Waiting for a read during recheck of the data directory lock
+ file.</td></tr><tr><td><code class="literal">LogicalRewriteCheckpointSync</code></td><td>Waiting for logical rewrite mappings to reach durable storage
+ during a checkpoint.</td></tr><tr><td><code class="literal">LogicalRewriteMappingSync</code></td><td>Waiting for mapping data to reach durable storage during a logical
+ rewrite.</td></tr><tr><td><code class="literal">LogicalRewriteMappingWrite</code></td><td>Waiting for a write of mapping data during a logical
+ rewrite.</td></tr><tr><td><code class="literal">LogicalRewriteSync</code></td><td>Waiting for logical rewrite mappings to reach durable
+ storage.</td></tr><tr><td><code class="literal">LogicalRewriteTruncate</code></td><td>Waiting for truncate of mapping data during a logical
+ rewrite.</td></tr><tr><td><code class="literal">LogicalRewriteWrite</code></td><td>Waiting for a write of logical rewrite mappings.</td></tr><tr><td><code class="literal">RelationMapRead</code></td><td>Waiting for a read of the relation map file.</td></tr><tr><td><code class="literal">RelationMapSync</code></td><td>Waiting for the relation map file to reach durable storage.</td></tr><tr><td><code class="literal">RelationMapWrite</code></td><td>Waiting for a write to the relation map file.</td></tr><tr><td><code class="literal">ReorderBufferRead</code></td><td>Waiting for a read during reorder buffer management.</td></tr><tr><td><code class="literal">ReorderBufferWrite</code></td><td>Waiting for a write during reorder buffer management.</td></tr><tr><td><code class="literal">ReorderLogicalMappingRead</code></td><td>Waiting for a read of a logical mapping during reorder buffer
+ management.</td></tr><tr><td><code class="literal">ReplicationSlotRead</code></td><td>Waiting for a read from a replication slot control file.</td></tr><tr><td><code class="literal">ReplicationSlotRestoreSync</code></td><td>Waiting for a replication slot control file to reach durable storage
+ while restoring it to memory.</td></tr><tr><td><code class="literal">ReplicationSlotSync</code></td><td>Waiting for a replication slot control file to reach durable
+ storage.</td></tr><tr><td><code class="literal">ReplicationSlotWrite</code></td><td>Waiting for a write to a replication slot control file.</td></tr><tr><td><code class="literal">SLRUFlushSync</code></td><td>Waiting for SLRU data to reach durable storage during a checkpoint
+ or database shutdown.</td></tr><tr><td><code class="literal">SLRURead</code></td><td>Waiting for a read of an SLRU page.</td></tr><tr><td><code class="literal">SLRUSync</code></td><td>Waiting for SLRU data to reach durable storage following a page
+ write.</td></tr><tr><td><code class="literal">SLRUWrite</code></td><td>Waiting for a write of an SLRU page.</td></tr><tr><td><code class="literal">SnapbuildRead</code></td><td>Waiting for a read of a serialized historical catalog
+ snapshot.</td></tr><tr><td><code class="literal">SnapbuildSync</code></td><td>Waiting for a serialized historical catalog snapshot to reach
+ durable storage.</td></tr><tr><td><code class="literal">SnapbuildWrite</code></td><td>Waiting for a write of a serialized historical catalog
+ snapshot.</td></tr><tr><td><code class="literal">TimelineHistoryFileSync</code></td><td>Waiting for a timeline history file received via streaming
+ replication to reach durable storage.</td></tr><tr><td><code class="literal">TimelineHistoryFileWrite</code></td><td>Waiting for a write of a timeline history file received via
+ streaming replication.</td></tr><tr><td><code class="literal">TimelineHistoryRead</code></td><td>Waiting for a read of a timeline history file.</td></tr><tr><td><code class="literal">TimelineHistorySync</code></td><td>Waiting for a newly created timeline history file to reach durable
+ storage.</td></tr><tr><td><code class="literal">TimelineHistoryWrite</code></td><td>Waiting for a write of a newly created timeline history
+ file.</td></tr><tr><td><code class="literal">TwophaseFileRead</code></td><td>Waiting for a read of a two phase state file.</td></tr><tr><td><code class="literal">TwophaseFileSync</code></td><td>Waiting for a two phase state file to reach durable storage.</td></tr><tr><td><code class="literal">TwophaseFileWrite</code></td><td>Waiting for a write of a two phase state file.</td></tr><tr><td><code class="literal">VersionFileWrite</code></td><td>Waiting for the version file to be written while creating a database.</td></tr><tr><td><code class="literal">WALBootstrapSync</code></td><td>Waiting for WAL to reach durable storage during
+ bootstrapping.</td></tr><tr><td><code class="literal">WALBootstrapWrite</code></td><td>Waiting for a write of a WAL page during bootstrapping.</td></tr><tr><td><code class="literal">WALCopyRead</code></td><td>Waiting for a read when creating a new WAL segment by copying an
+ existing one.</td></tr><tr><td><code class="literal">WALCopySync</code></td><td>Waiting for a new WAL segment created by copying an existing one to
+ reach durable storage.</td></tr><tr><td><code class="literal">WALCopyWrite</code></td><td>Waiting for a write when creating a new WAL segment by copying an
+ existing one.</td></tr><tr><td><code class="literal">WALInitSync</code></td><td>Waiting for a newly initialized WAL file to reach durable
+ storage.</td></tr><tr><td><code class="literal">WALInitWrite</code></td><td>Waiting for a write while initializing a new WAL file.</td></tr><tr><td><code class="literal">WALRead</code></td><td>Waiting for a read from a WAL file.</td></tr><tr><td><code class="literal">WALSenderTimelineHistoryRead</code></td><td>Waiting for a read from a timeline history file during a walsender
+ timeline command.</td></tr><tr><td><code class="literal">WALSync</code></td><td>Waiting for a WAL file to reach durable storage.</td></tr><tr><td><code class="literal">WALSyncMethodAssign</code></td><td>Waiting for data to reach durable storage while assigning a new
+ WAL sync method.</td></tr><tr><td><code class="literal">WALWrite</code></td><td>Waiting for a write to a WAL file.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-IPC-TABLE"><p class="title"><strong>Table 28.10. Wait Events of Type <code class="literal">IPC</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type IPC" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">IPC</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">AppendReady</code></td><td>Waiting for subplan nodes of an <code class="literal">Append</code> plan
+ node to be ready.</td></tr><tr><td><code class="literal">ArchiveCleanupCommand</code></td><td>Waiting for <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-COMMAND">archive_cleanup_command</a> to
+ complete.</td></tr><tr><td><code class="literal">ArchiveCommand</code></td><td>Waiting for <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> to
+ complete.</td></tr><tr><td><code class="literal">BackendTermination</code></td><td>Waiting for the termination of another backend.</td></tr><tr><td><code class="literal">BackupWaitWalArchive</code></td><td>Waiting for WAL files required for a backup to be successfully
+ archived.</td></tr><tr><td><code class="literal">BgWorkerShutdown</code></td><td>Waiting for background worker to shut down.</td></tr><tr><td><code class="literal">BgWorkerStartup</code></td><td>Waiting for background worker to start up.</td></tr><tr><td><code class="literal">BtreePage</code></td><td>Waiting for the page number needed to continue a parallel B-tree
+ scan to become available.</td></tr><tr><td><code class="literal">BufferIO</code></td><td>Waiting for buffer I/O to complete.</td></tr><tr><td><code class="literal">CheckpointDone</code></td><td>Waiting for a checkpoint to complete.</td></tr><tr><td><code class="literal">CheckpointStart</code></td><td>Waiting for a checkpoint to start.</td></tr><tr><td><code class="literal">ExecuteGather</code></td><td>Waiting for activity from a child process while
+ executing a <code class="literal">Gather</code> plan node.</td></tr><tr><td><code class="literal">HashBatchAllocate</code></td><td>Waiting for an elected Parallel Hash participant to allocate a hash
+ table.</td></tr><tr><td><code class="literal">HashBatchElect</code></td><td>Waiting to elect a Parallel Hash participant to allocate a hash
+ table.</td></tr><tr><td><code class="literal">HashBatchLoad</code></td><td>Waiting for other Parallel Hash participants to finish loading a
+ hash table.</td></tr><tr><td><code class="literal">HashBuildAllocate</code></td><td>Waiting for an elected Parallel Hash participant to allocate the
+ initial hash table.</td></tr><tr><td><code class="literal">HashBuildElect</code></td><td>Waiting to elect a Parallel Hash participant to allocate the
+ initial hash table.</td></tr><tr><td><code class="literal">HashBuildHashInner</code></td><td>Waiting for other Parallel Hash participants to finish hashing the
+ inner relation.</td></tr><tr><td><code class="literal">HashBuildHashOuter</code></td><td>Waiting for other Parallel Hash participants to finish partitioning
+ the outer relation.</td></tr><tr><td><code class="literal">HashGrowBatchesAllocate</code></td><td>Waiting for an elected Parallel Hash participant to allocate more
+ batches.</td></tr><tr><td><code class="literal">HashGrowBatchesDecide</code></td><td>Waiting to elect a Parallel Hash participant to decide on future
+ batch growth.</td></tr><tr><td><code class="literal">HashGrowBatchesElect</code></td><td>Waiting to elect a Parallel Hash participant to allocate more
+ batches.</td></tr><tr><td><code class="literal">HashGrowBatchesFinish</code></td><td>Waiting for an elected Parallel Hash participant to decide on
+ future batch growth.</td></tr><tr><td><code class="literal">HashGrowBatchesRepartition</code></td><td>Waiting for other Parallel Hash participants to finish
+ repartitioning.</td></tr><tr><td><code class="literal">HashGrowBucketsAllocate</code></td><td>Waiting for an elected Parallel Hash participant to finish
+ allocating more buckets.</td></tr><tr><td><code class="literal">HashGrowBucketsElect</code></td><td>Waiting to elect a Parallel Hash participant to allocate more
+ buckets.</td></tr><tr><td><code class="literal">HashGrowBucketsReinsert</code></td><td>Waiting for other Parallel Hash participants to finish inserting
+ tuples into new buckets.</td></tr><tr><td><code class="literal">LogicalSyncData</code></td><td>Waiting for a logical replication remote server to send data for
+ initial table synchronization.</td></tr><tr><td><code class="literal">LogicalSyncStateChange</code></td><td>Waiting for a logical replication remote server to change
+ state.</td></tr><tr><td><code class="literal">MessageQueueInternal</code></td><td>Waiting for another process to be attached to a shared message
+ queue.</td></tr><tr><td><code class="literal">MessageQueuePutMessage</code></td><td>Waiting to write a protocol message to a shared message queue.</td></tr><tr><td><code class="literal">MessageQueueReceive</code></td><td>Waiting to receive bytes from a shared message queue.</td></tr><tr><td><code class="literal">MessageQueueSend</code></td><td>Waiting to send bytes to a shared message queue.</td></tr><tr><td><code class="literal">ParallelBitmapScan</code></td><td>Waiting for parallel bitmap scan to become initialized.</td></tr><tr><td><code class="literal">ParallelCreateIndexScan</code></td><td>Waiting for parallel <code class="command">CREATE INDEX</code> workers to
+ finish heap scan.</td></tr><tr><td><code class="literal">ParallelFinish</code></td><td>Waiting for parallel workers to finish computing.</td></tr><tr><td><code class="literal">ProcArrayGroupUpdate</code></td><td>Waiting for the group leader to clear the transaction ID at
+ end of a parallel operation.</td></tr><tr><td><code class="literal">ProcSignalBarrier</code></td><td>Waiting for a barrier event to be processed by all
+ backends.</td></tr><tr><td><code class="literal">Promote</code></td><td>Waiting for standby promotion.</td></tr><tr><td><code class="literal">RecoveryConflictSnapshot</code></td><td>Waiting for recovery conflict resolution for a vacuum
+ cleanup.</td></tr><tr><td><code class="literal">RecoveryConflictTablespace</code></td><td>Waiting for recovery conflict resolution for dropping a
+ tablespace.</td></tr><tr><td><code class="literal">RecoveryEndCommand</code></td><td>Waiting for <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-END-COMMAND">recovery_end_command</a> to
+ complete.</td></tr><tr><td><code class="literal">RecoveryPause</code></td><td>Waiting for recovery to be resumed.</td></tr><tr><td><code class="literal">ReplicationOriginDrop</code></td><td>Waiting for a replication origin to become inactive so it can be
+ dropped.</td></tr><tr><td><code class="literal">ReplicationSlotDrop</code></td><td>Waiting for a replication slot to become inactive so it can be
+ dropped.</td></tr><tr><td><code class="literal">RestoreCommand</code></td><td>Waiting for <a class="xref" href="runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a> to
+ complete.</td></tr><tr><td><code class="literal">SafeSnapshot</code></td><td>Waiting to obtain a valid snapshot for a <code class="literal">READ ONLY
+ DEFERRABLE</code> transaction.</td></tr><tr><td><code class="literal">SyncRep</code></td><td>Waiting for confirmation from a remote server during synchronous
+ replication.</td></tr><tr><td><code class="literal">WalReceiverExit</code></td><td>Waiting for the WAL receiver to exit.</td></tr><tr><td><code class="literal">WalReceiverWaitStart</code></td><td>Waiting for startup process to send initial data for streaming
+ replication.</td></tr><tr><td><code class="literal">XactGroupUpdate</code></td><td>Waiting for the group leader to update transaction status at
+ end of a parallel operation.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-LOCK-TABLE"><p class="title"><strong>Table 28.11. Wait Events of Type <code class="literal">Lock</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type Lock" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">Lock</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">advisory</code></td><td>Waiting to acquire an advisory user lock.</td></tr><tr><td><code class="literal">extend</code></td><td>Waiting to extend a relation.</td></tr><tr><td><code class="literal">frozenid</code></td><td>Waiting to
+ update <code class="structname">pg_database</code>.<code class="structfield">datfrozenxid</code>
+ and <code class="structname">pg_database</code>.<code class="structfield">datminmxid</code>.</td></tr><tr><td><code class="literal">object</code></td><td>Waiting to acquire a lock on a non-relation database object.</td></tr><tr><td><code class="literal">page</code></td><td>Waiting to acquire a lock on a page of a relation.</td></tr><tr><td><code class="literal">relation</code></td><td>Waiting to acquire a lock on a relation.</td></tr><tr><td><code class="literal">spectoken</code></td><td>Waiting to acquire a speculative insertion lock.</td></tr><tr><td><code class="literal">transactionid</code></td><td>Waiting for a transaction to finish.</td></tr><tr><td><code class="literal">tuple</code></td><td>Waiting to acquire a lock on a tuple.</td></tr><tr><td><code class="literal">userlock</code></td><td>Waiting to acquire a user lock.</td></tr><tr><td><code class="literal">virtualxid</code></td><td>Waiting to acquire a virtual transaction ID lock.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="WAIT-EVENT-LWLOCK-TABLE"><p class="title"><strong>Table 28.12. Wait Events of Type <code class="literal">LWLock</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type LWLock" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">LWLock</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">AddinShmemInit</code></td><td>Waiting to manage an extension's space allocation in shared
+ memory.</td></tr><tr><td><code class="literal">AutoFile</code></td><td>Waiting to update the <code class="filename">postgresql.auto.conf</code>
+ file.</td></tr><tr><td><code class="literal">Autovacuum</code></td><td>Waiting to read or update the current state of autovacuum
+ workers.</td></tr><tr><td><code class="literal">AutovacuumSchedule</code></td><td>Waiting to ensure that a table selected for autovacuum
+ still needs vacuuming.</td></tr><tr><td><code class="literal">BackgroundWorker</code></td><td>Waiting to read or update background worker state.</td></tr><tr><td><code class="literal">BtreeVacuum</code></td><td>Waiting to read or update vacuum-related information for a
+ B-tree index.</td></tr><tr><td><code class="literal">BufferContent</code></td><td>Waiting to access a data page in memory.</td></tr><tr><td><code class="literal">BufferMapping</code></td><td>Waiting to associate a data block with a buffer in the buffer
+ pool.</td></tr><tr><td><code class="literal">CheckpointerComm</code></td><td>Waiting to manage fsync requests.</td></tr><tr><td><code class="literal">CommitTs</code></td><td>Waiting to read or update the last value set for a
+ transaction commit timestamp.</td></tr><tr><td><code class="literal">CommitTsBuffer</code></td><td>Waiting for I/O on a commit timestamp SLRU buffer.</td></tr><tr><td><code class="literal">CommitTsSLRU</code></td><td>Waiting to access the commit timestamp SLRU cache.</td></tr><tr><td><code class="literal">ControlFile</code></td><td>Waiting to read or update the <code class="filename">pg_control</code>
+ file or create a new WAL file.</td></tr><tr><td><code class="literal">DynamicSharedMemoryControl</code></td><td>Waiting to read or update dynamic shared memory allocation
+ information.</td></tr><tr><td><code class="literal">LockFastPath</code></td><td>Waiting to read or update a process' fast-path lock
+ information.</td></tr><tr><td><code class="literal">LockManager</code></td><td>Waiting to read or update information
+ about <span class="quote">“<span class="quote">heavyweight</span>”</span> locks.</td></tr><tr><td><code class="literal">LogicalRepWorker</code></td><td>Waiting to read or update the state of logical replication
+ workers.</td></tr><tr><td><code class="literal">MultiXactGen</code></td><td>Waiting to read or update shared multixact state.</td></tr><tr><td><code class="literal">MultiXactMemberBuffer</code></td><td>Waiting for I/O on a multixact member SLRU buffer.</td></tr><tr><td><code class="literal">MultiXactMemberSLRU</code></td><td>Waiting to access the multixact member SLRU cache.</td></tr><tr><td><code class="literal">MultiXactOffsetBuffer</code></td><td>Waiting for I/O on a multixact offset SLRU buffer.</td></tr><tr><td><code class="literal">MultiXactOffsetSLRU</code></td><td>Waiting to access the multixact offset SLRU cache.</td></tr><tr><td><code class="literal">MultiXactTruncation</code></td><td>Waiting to read or truncate multixact information.</td></tr><tr><td><code class="literal">NotifyBuffer</code></td><td>Waiting for I/O on a <code class="command">NOTIFY</code> message SLRU
+ buffer.</td></tr><tr><td><code class="literal">NotifyQueue</code></td><td>Waiting to read or update <code class="command">NOTIFY</code> messages.</td></tr><tr><td><code class="literal">NotifyQueueTail</code></td><td>Waiting to update limit on <code class="command">NOTIFY</code> message
+ storage.</td></tr><tr><td><code class="literal">NotifySLRU</code></td><td>Waiting to access the <code class="command">NOTIFY</code> message SLRU
+ cache.</td></tr><tr><td><code class="literal">OidGen</code></td><td>Waiting to allocate a new OID.</td></tr><tr><td><code class="literal">OldSnapshotTimeMap</code></td><td>Waiting to read or update old snapshot control information.</td></tr><tr><td><code class="literal">ParallelAppend</code></td><td>Waiting to choose the next subplan during Parallel Append plan
+ execution.</td></tr><tr><td><code class="literal">ParallelHashJoin</code></td><td>Waiting to synchronize workers during Parallel Hash Join plan
+ execution.</td></tr><tr><td><code class="literal">ParallelQueryDSA</code></td><td>Waiting for parallel query dynamic shared memory allocation.</td></tr><tr><td><code class="literal">PerSessionDSA</code></td><td>Waiting for parallel query dynamic shared memory allocation.</td></tr><tr><td><code class="literal">PerSessionRecordType</code></td><td>Waiting to access a parallel query's information about composite
+ types.</td></tr><tr><td><code class="literal">PerSessionRecordTypmod</code></td><td>Waiting to access a parallel query's information about type
+ modifiers that identify anonymous record types.</td></tr><tr><td><code class="literal">PerXactPredicateList</code></td><td>Waiting to access the list of predicate locks held by the current
+ serializable transaction during a parallel query.</td></tr><tr><td><code class="literal">PredicateLockManager</code></td><td>Waiting to access predicate lock information used by
+ serializable transactions.</td></tr><tr><td><code class="literal">ProcArray</code></td><td>Waiting to access the shared per-process data structures
+ (typically, to get a snapshot or report a session's transaction
+ ID).</td></tr><tr><td><code class="literal">RelationMapping</code></td><td>Waiting to read or update
+ a <code class="filename">pg_filenode.map</code> file (used to track the
+ filenode assignments of certain system catalogs).</td></tr><tr><td><code class="literal">RelCacheInit</code></td><td>Waiting to read or update a <code class="filename">pg_internal.init</code>
+ relation cache initialization file.</td></tr><tr><td><code class="literal">ReplicationOrigin</code></td><td>Waiting to create, drop or use a replication origin.</td></tr><tr><td><code class="literal">ReplicationOriginState</code></td><td>Waiting to read or update the progress of one replication
+ origin.</td></tr><tr><td><code class="literal">ReplicationSlotAllocation</code></td><td>Waiting to allocate or free a replication slot.</td></tr><tr><td><code class="literal">ReplicationSlotControl</code></td><td>Waiting to read or update replication slot state.</td></tr><tr><td><code class="literal">ReplicationSlotIO</code></td><td>Waiting for I/O on a replication slot.</td></tr><tr><td><code class="literal">SerialBuffer</code></td><td>Waiting for I/O on a serializable transaction conflict SLRU
+ buffer.</td></tr><tr><td><code class="literal">SerializableFinishedList</code></td><td>Waiting to access the list of finished serializable
+ transactions.</td></tr><tr><td><code class="literal">SerializablePredicateList</code></td><td>Waiting to access the list of predicate locks held by
+ serializable transactions.</td></tr><tr><td><code class="literal">PgStatsDSA</code></td><td>Waiting for stats dynamic shared memory allocator access</td></tr><tr><td><code class="literal">PgStatsHash</code></td><td>Waiting for stats shared memory hash table access</td></tr><tr><td><code class="literal">PgStatsData</code></td><td>Waiting for shared memory stats data access</td></tr><tr><td><code class="literal">SerializableXactHash</code></td><td>Waiting to read or update information about serializable
+ transactions.</td></tr><tr><td><code class="literal">SerialSLRU</code></td><td>Waiting to access the serializable transaction conflict SLRU
+ cache.</td></tr><tr><td><code class="literal">SharedTidBitmap</code></td><td>Waiting to access a shared TID bitmap during a parallel bitmap
+ index scan.</td></tr><tr><td><code class="literal">SharedTupleStore</code></td><td>Waiting to access a shared tuple store during parallel
+ query.</td></tr><tr><td><code class="literal">ShmemIndex</code></td><td>Waiting to find or allocate space in shared memory.</td></tr><tr><td><code class="literal">SInvalRead</code></td><td>Waiting to retrieve messages from the shared catalog invalidation
+ queue.</td></tr><tr><td><code class="literal">SInvalWrite</code></td><td>Waiting to add a message to the shared catalog invalidation
+ queue.</td></tr><tr><td><code class="literal">SubtransBuffer</code></td><td>Waiting for I/O on a sub-transaction SLRU buffer.</td></tr><tr><td><code class="literal">SubtransSLRU</code></td><td>Waiting to access the sub-transaction SLRU cache.</td></tr><tr><td><code class="literal">SyncRep</code></td><td>Waiting to read or update information about the state of
+ synchronous replication.</td></tr><tr><td><code class="literal">SyncScan</code></td><td>Waiting to select the starting location of a synchronized table
+ scan.</td></tr><tr><td><code class="literal">TablespaceCreate</code></td><td>Waiting to create or drop a tablespace.</td></tr><tr><td><code class="literal">TwoPhaseState</code></td><td>Waiting to read or update the state of prepared transactions.</td></tr><tr><td><code class="literal">WALBufMapping</code></td><td>Waiting to replace a page in WAL buffers.</td></tr><tr><td><code class="literal">WALInsert</code></td><td>Waiting to insert WAL data into a memory buffer.</td></tr><tr><td><code class="literal">WALWrite</code></td><td>Waiting for WAL buffers to be written to disk.</td></tr><tr><td><code class="literal">WrapLimitsVacuum</code></td><td>Waiting to update limits on transaction id and multixact
+ consumption.</td></tr><tr><td><code class="literal">XactBuffer</code></td><td>Waiting for I/O on a transaction status SLRU buffer.</td></tr><tr><td><code class="literal">XactSLRU</code></td><td>Waiting to access the transaction status SLRU cache.</td></tr><tr><td><code class="literal">XactTruncation</code></td><td>Waiting to execute <code class="function">pg_xact_status</code> or update
+ the oldest transaction ID available to it.</td></tr><tr><td><code class="literal">XidGen</code></td><td>Waiting to allocate a new transaction ID.</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ Extensions can add <code class="literal">LWLock</code> types to the list shown in
+ <a class="xref" href="monitoring-stats.html#WAIT-EVENT-LWLOCK-TABLE" title="Table 28.12. Wait Events of Type LWLock">Table 28.12</a>. In some cases, the name
+ assigned by an extension will not be available in all server processes;
+ so an <code class="literal">LWLock</code> wait event might be reported as
+ just <span class="quote">“<span class="quote"><code class="literal">extension</code></span>”</span> rather than the
+ extension-assigned name.
+ </p></div><div class="table" id="WAIT-EVENT-TIMEOUT-TABLE"><p class="title"><strong>Table 28.13. Wait Events of Type <code class="literal">Timeout</code></strong></p><div class="table-contents"><table class="table" summary="Wait Events of Type Timeout" border="1"><colgroup><col /><col /></colgroup><thead><tr><th><code class="literal">Timeout</code> Wait Event</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">BaseBackupThrottle</code></td><td>Waiting during base backup when throttling activity.</td></tr><tr><td><code class="literal">CheckpointWriteDelay</code></td><td>Waiting between writes while performing a checkpoint.</td></tr><tr><td><code class="literal">PgSleep</code></td><td>Waiting due to a call to <code class="function">pg_sleep</code> or
+ a sibling function.</td></tr><tr><td><code class="literal">RecoveryApplyDelay</code></td><td>Waiting to apply WAL during recovery because of a delay
+ setting.</td></tr><tr><td><code class="literal">RecoveryRetrieveRetryInterval</code></td><td>Waiting during recovery when WAL data is not available from any
+ source (<code class="filename">pg_wal</code>, archive or stream).</td></tr><tr><td><code class="literal">RegisterSyncRequest</code></td><td>Waiting while sending synchronization requests to the
+ checkpointer, because the request queue is full.</td></tr><tr><td><code class="literal">VacuumDelay</code></td><td>Waiting in a cost-based vacuum delay point.</td></tr><tr><td><code class="literal">VacuumTruncate</code></td><td>Waiting to acquire an exclusive lock to truncate off any
+ empty pages at the end of a table vacuumed.</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Here is an example of how wait events can be viewed:
+
+</p><pre class="programlisting">
+SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event is NOT NULL;
+ pid | wait_event_type | wait_event
+------+-----------------+------------
+ 2540 | Lock | relation
+ 6644 | LWLock | ProcArray
+(2 rows)
+</pre><p>
+ </p></div><div class="sect2" id="MONITORING-PG-STAT-REPLICATION-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.4. <code class="structname">pg_stat_replication</code></h3></div></div></div><a id="id-1.6.15.7.8.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_replication</code> view will contain one row
+ per WAL sender process, showing statistics about replication to that
+ sender's connected standby server. Only directly connected standbys are
+ listed; no information is available about downstream standby servers.
+ </p><div class="table" id="PG-STAT-REPLICATION-VIEW"><p class="title"><strong>Table 28.14. <code class="structname">pg_stat_replication</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_replication View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of a WAL sender process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesysid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the user logged into this WAL sender process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usename</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the user logged into this WAL sender process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">application_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the application that is connected
+ to this WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_addr</code> <code class="type">inet</code>
+ </p>
+ <p>
+ IP address of the client connected to this WAL sender.
+ If this field is null, it indicates that the client is
+ connected via a Unix socket on the server machine.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_hostname</code> <code class="type">text</code>
+ </p>
+ <p>
+ Host name of the connected client, as reported by a
+ reverse DNS lookup of <code class="structfield">client_addr</code>. This field will
+ only be non-null for IP connections, and only when <a class="xref" href="runtime-config-logging.html#GUC-LOG-HOSTNAME">log_hostname</a> is enabled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_port</code> <code class="type">integer</code>
+ </p>
+ <p>
+ TCP port number that the client is using for communication
+ with this WAL sender, or <code class="literal">-1</code> if a Unix socket is used
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_start</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time when this process was started, i.e., when the
+ client connected to this WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backend_xmin</code> <code class="type">xid</code>
+ </p>
+ <p>
+ This standby's <code class="literal">xmin</code> horizon reported
+ by <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY-FEEDBACK">hot_standby_feedback</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">state</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current WAL sender state.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">startup</code>: This WAL sender is starting up.
+ </p></li><li class="listitem"><p>
+ <code class="literal">catchup</code>: This WAL sender's connected standby is
+ catching up with the primary.
+ </p></li><li class="listitem"><p>
+ <code class="literal">streaming</code>: This WAL sender is streaming changes
+ after its connected standby server has caught up with the primary.
+ </p></li><li class="listitem"><p>
+ <code class="literal">backup</code>: This WAL sender is sending a backup.
+ </p></li><li class="listitem"><p>
+ <code class="literal">stopping</code>: This WAL sender is stopping.
+ </p></li></ul></div><p>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sent_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location sent on this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">write_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location written to disk by this standby
+ server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">flush_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location flushed to disk by this standby
+ server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">replay_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location replayed into the database on this
+ standby server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">write_lag</code> <code class="type">interval</code>
+ </p>
+ <p>
+ Time elapsed between flushing recent WAL locally and receiving
+ notification that this standby server has written it (but not yet
+ flushed it or applied it). This can be used to gauge the delay that
+ <code class="literal">synchronous_commit</code> level
+ <code class="literal">remote_write</code> incurred while committing if this
+ server was configured as a synchronous standby.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">flush_lag</code> <code class="type">interval</code>
+ </p>
+ <p>
+ Time elapsed between flushing recent WAL locally and receiving
+ notification that this standby server has written and flushed it
+ (but not yet applied it). This can be used to gauge the delay that
+ <code class="literal">synchronous_commit</code> level
+ <code class="literal">on</code> incurred while committing if this
+ server was configured as a synchronous standby.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">replay_lag</code> <code class="type">interval</code>
+ </p>
+ <p>
+ Time elapsed between flushing recent WAL locally and receiving
+ notification that this standby server has written, flushed and
+ applied it. This can be used to gauge the delay that
+ <code class="literal">synchronous_commit</code> level
+ <code class="literal">remote_apply</code> incurred while committing if this
+ server was configured as a synchronous standby.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sync_priority</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Priority of this standby server for being chosen as the
+ synchronous standby in a priority-based synchronous replication.
+ This has no effect in a quorum-based synchronous replication.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sync_state</code> <code class="type">text</code>
+ </p>
+ <p>
+ Synchronous state of this standby server.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">async</code>: This standby server is asynchronous.
+ </p></li><li class="listitem"><p>
+ <code class="literal">potential</code>: This standby server is now asynchronous,
+ but can potentially become synchronous if one of current
+ synchronous ones fails.
+ </p></li><li class="listitem"><p>
+ <code class="literal">sync</code>: This standby server is synchronous.
+ </p></li><li class="listitem"><p>
+ <code class="literal">quorum</code>: This standby server is considered as a candidate
+ for quorum standbys.
+ </p></li></ul></div><p>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reply_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Send time of last reply message received from standby server
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The lag times reported in the <code class="structname">pg_stat_replication</code>
+ view are measurements of the time taken for recent WAL to be written,
+ flushed and replayed and for the sender to know about it. These times
+ represent the commit delay that was (or would have been) introduced by each
+ synchronous commit level, if the remote server was configured as a
+ synchronous standby. For an asynchronous standby, the
+ <code class="structfield">replay_lag</code> column approximates the delay
+ before recent transactions became visible to queries. If the standby
+ server has entirely caught up with the sending server and there is no more
+ WAL activity, the most recently measured lag times will continue to be
+ displayed for a short time and then show NULL.
+ </p><p>
+ Lag times work automatically for physical replication. Logical decoding
+ plugins may optionally emit tracking messages; if they do not, the tracking
+ mechanism will simply display NULL lag.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The reported lag times are not predictions of how long it will take for
+ the standby to catch up with the sending server assuming the current
+ rate of replay. Such a system would show similar times while new WAL is
+ being generated, but would differ when the sender becomes idle. In
+ particular, when the standby has caught up completely,
+ <code class="structname">pg_stat_replication</code> shows the time taken to
+ write, flush and replay the most recent reported WAL location rather than
+ zero as some users might expect. This is consistent with the goal of
+ measuring synchronous commit and transaction visibility delays for
+ recent write transactions.
+ To reduce confusion for users expecting a different model of lag, the
+ lag columns revert to NULL after a short time on a fully replayed idle
+ system. Monitoring systems should choose whether to represent this
+ as missing data, zero or continue to display the last known value.
+ </p></div></div><div class="sect2" id="MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.5. <code class="structname">pg_stat_replication_slots</code></h3></div></div></div><a id="id-1.6.15.7.9.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_replication_slots</code> view will contain
+ one row per logical replication slot, showing statistics about its usage.
+ </p><div class="table" id="PG-STAT-REPLICATION-SLOTS-VIEW"><p class="title"><strong>Table 28.15. <code class="structname">pg_stat_replication_slots</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_replication_slots View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">slot_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ A unique, cluster-wide identifier for the replication slot
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spill_txns</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of transactions spilled to disk once the memory used by
+ logical decoding to decode changes from WAL has exceeded
+ <code class="literal">logical_decoding_work_mem</code>. The counter gets
+ incremented for both top-level transactions and subtransactions.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spill_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times transactions were spilled to disk while decoding
+ changes from WAL for this slot. This counter is incremented each time
+ a transaction is spilled, and the same transaction may be spilled
+ multiple times.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">spill_bytes</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Amount of decoded transaction data spilled to disk while performing
+ decoding of changes from WAL for this slot. This and other spill
+ counters can be used to gauge the I/O which occurred during logical
+ decoding and allow tuning <code class="literal">logical_decoding_work_mem</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stream_txns</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of in-progress transactions streamed to the decoding output
+ plugin after the memory used by logical decoding to decode changes
+ from WAL for this slot has exceeded
+ <code class="literal">logical_decoding_work_mem</code>. Streaming only
+ works with top-level transactions (subtransactions can't be streamed
+ independently), so the counter is not incremented for subtransactions.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stream_count</code><code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times in-progress transactions were streamed to the decoding
+ output plugin while decoding changes from WAL for this slot. This
+ counter is incremented each time a transaction is streamed, and the
+ same transaction may be streamed multiple times.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stream_bytes</code><code class="type">bigint</code>
+ </p>
+ <p>
+ Amount of transaction data decoded for streaming in-progress
+ transactions to the decoding output plugin while decoding changes from
+ WAL for this slot. This and other streaming counters for this slot can
+ be used to tune <code class="literal">logical_decoding_work_mem</code>.
+ </p>
+ </td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_txns</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of decoded transactions sent to the decoding output plugin for
+ this slot. This counts top-level transactions only, and is not incremented
+ for subtransactions. Note that this includes the transactions that are
+ streamed and/or spilled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_bytes</code><code class="type">bigint</code>
+ </p>
+ <p>
+ Amount of transaction data decoded for sending transactions to the
+ decoding output plugin while decoding changes from WAL for this slot.
+ Note that this includes data that is streamed and/or spilled.
+ </p>
+ </td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-WAL-RECEIVER-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.6. <code class="structname">pg_stat_wal_receiver</code></h3></div></div></div><a id="id-1.6.15.7.10.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_wal_receiver</code> view will contain only
+ one row, showing statistics about the WAL receiver from that receiver's
+ connected server.
+ </p><div class="table" id="PG-STAT-WAL-RECEIVER-VIEW"><p class="title"><strong>Table 28.16. <code class="structname">pg_stat_wal_receiver</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_wal_receiver View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of the WAL receiver process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">status</code> <code class="type">text</code>
+ </p>
+ <p>
+ Activity status of the WAL receiver process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">receive_start_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ First write-ahead log location used when WAL receiver is
+ started
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">receive_start_tli</code> <code class="type">integer</code>
+ </p>
+ <p>
+ First timeline number used when WAL receiver is started
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">written_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location already received and written to disk,
+ but not flushed. This should not be used for data integrity checks.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">flushed_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location already received and flushed to
+ disk, the initial value of this field being the first log location used
+ when WAL receiver is started
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">received_tli</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Timeline number of last write-ahead log location received and
+ flushed to disk, the initial value of this field being the timeline
+ number of the first log location used when WAL receiver is started
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_msg_send_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Send time of last message received from origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_msg_receipt_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Receipt time of last message received from origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">latest_end_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location reported to origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">latest_end_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time of last write-ahead log location reported to origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">slot_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Replication slot name used by this WAL receiver
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sender_host</code> <code class="type">text</code>
+ </p>
+ <p>
+ Host of the <span class="productname">PostgreSQL</span> instance
+ this WAL receiver is connected to. This can be a host name,
+ an IP address, or a directory path if the connection is via
+ Unix socket. (The path case can be distinguished because it
+ will always be an absolute path, beginning with <code class="literal">/</code>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sender_port</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Port number of the <span class="productname">PostgreSQL</span> instance
+ this WAL receiver is connected to.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conninfo</code> <code class="type">text</code>
+ </p>
+ <p>
+ Connection string used by this WAL receiver,
+ with security-sensitive fields obfuscated.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-RECOVERY-PREFETCH"><div class="titlepage"><div><div><h3 class="title">28.2.7. <code class="structname">pg_stat_recovery_prefetch</code></h3></div></div></div><a id="id-1.6.15.7.11.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_recovery_prefetch</code> view will contain
+ only one row. The columns <code class="structfield">wal_distance</code>,
+ <code class="structfield">block_distance</code> and
+ <code class="structfield">io_depth</code> show current values, and the
+ other columns show cumulative counters that can be reset
+ with the <code class="function">pg_stat_reset_shared</code> function.
+ </p><div class="table" id="PG-STAT-RECOVERY-PREFETCH-VIEW"><p class="title"><strong>Table 28.17. <code class="structname">pg_stat_recovery_prefetch</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_recovery_prefetch View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">prefetch</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks prefetched because they were not in the buffer pool
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks not prefetched because they were already in the buffer pool
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">skip_init</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks not prefetched because they would be zero-initialized
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">skip_new</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks not prefetched because they didn't exist yet
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">skip_fpw</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks not prefetched because a full page image was included in the WAL
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">skip_rep</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks not prefetched because they were already recently prefetched
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">wal_distance</code> <code class="type">int</code>
+ </p>
+ <p>
+ How many bytes ahead the prefetcher is looking
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">block_distance</code> <code class="type">int</code>
+ </p>
+ <p>
+ How many blocks ahead the prefetcher is looking
+ </p>
+ </td></tr><tr><td class="catalog_table_entry">
+ <p class="column_definition">
+ <code class="structfield">io_depth</code> <code class="type">int</code>
+ </p>
+ <p>
+ How many prefetches have been initiated but are not yet known to have completed
+ </p>
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-SUBSCRIPTION"><div class="titlepage"><div><div><h3 class="title">28.2.8. <code class="structname">pg_stat_subscription</code></h3></div></div></div><a id="id-1.6.15.7.12.2" class="indexterm"></a><div class="table" id="PG-STAT-SUBSCRIPTION"><p class="title"><strong>Table 28.18. <code class="structname">pg_stat_subscription</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_subscription View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of the subscription worker process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the relation that the worker is synchronizing; null for the
+ main apply worker
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">received_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location received, the initial value of
+ this field being 0
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_msg_send_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Send time of last message received from origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_msg_receipt_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Receipt time of last message received from origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">latest_end_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ Last write-ahead log location reported to origin WAL sender
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">latest_end_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time of last write-ahead log location reported to origin WAL
+ sender
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-SUBSCRIPTION-STATS"><div class="titlepage"><div><div><h3 class="title">28.2.9. <code class="structname">pg_stat_subscription_stats</code></h3></div></div></div><a id="id-1.6.15.7.13.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_subscription_stats</code> view will contain
+ one row per subscription.
+ </p><div class="table" id="PG-STAT-SUBSCRIPTION-STATS"><p class="title"><strong>Table 28.19. <code class="structname">pg_stat_subscription_stats</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_subscription_stats View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">subname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the subscription
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">apply_error_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times an error occurred while applying changes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sync_error_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times an error occurred during the initial table
+ synchronization
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-SSL-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.10. <code class="structname">pg_stat_ssl</code></h3></div></div></div><a id="id-1.6.15.7.14.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_ssl</code> view will contain one row per
+ backend or WAL sender process, showing statistics about SSL usage on
+ this connection. It can be joined to <code class="structname">pg_stat_activity</code>
+ or <code class="structname">pg_stat_replication</code> on the
+ <code class="structfield">pid</code> column to get more details about the
+ connection.
+ </p><div class="table" id="PG-STAT-SSL-VIEW"><p class="title"><strong>Table 28.20. <code class="structname">pg_stat_ssl</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_ssl View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of a backend or WAL sender process
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ssl</code> <code class="type">boolean</code>
+ </p>
+ <p>
+ True if SSL is used on this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">version</code> <code class="type">text</code>
+ </p>
+ <p>
+ Version of SSL in use, or NULL if SSL is not in use
+ on this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cipher</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of SSL cipher in use, or NULL if SSL is not in use
+ on this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">bits</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Number of bits in the encryption algorithm used, or NULL
+ if SSL is not used on this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_dn</code> <code class="type">text</code>
+ </p>
+ <p>
+ Distinguished Name (DN) field from the client certificate
+ used, or NULL if no client certificate was supplied or if SSL
+ is not in use on this connection. This field is truncated if the
+ DN field is longer than <code class="symbol">NAMEDATALEN</code> (64 characters
+ in a standard build).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">client_serial</code> <code class="type">numeric</code>
+ </p>
+ <p>
+ Serial number of the client certificate, or NULL if no client
+ certificate was supplied or if SSL is not in use on this connection. The
+ combination of certificate serial number and certificate issuer uniquely
+ identifies a certificate (unless the issuer erroneously reuses serial
+ numbers).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">issuer_dn</code> <code class="type">text</code>
+ </p>
+ <p>
+ DN of the issuer of the client certificate, or NULL if no client
+ certificate was supplied or if SSL is not in use on this connection.
+ This field is truncated like <code class="structfield">client_dn</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-GSSAPI-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.11. <code class="structname">pg_stat_gssapi</code></h3></div></div></div><a id="id-1.6.15.7.15.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_gssapi</code> view will contain one row per
+ backend, showing information about GSSAPI usage on this connection. It can
+ be joined to <code class="structname">pg_stat_activity</code> or
+ <code class="structname">pg_stat_replication</code> on the
+ <code class="structfield">pid</code> column to get more details about the
+ connection.
+ </p><div class="table" id="PG-STAT-GSSAPI-VIEW"><p class="title"><strong>Table 28.21. <code class="structname">pg_stat_gssapi</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_gssapi View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of a backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">gss_authenticated</code> <code class="type">boolean</code>
+ </p>
+ <p>
+ True if GSSAPI authentication was used for this connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">principal</code> <code class="type">text</code>
+ </p>
+ <p>
+ Principal used to authenticate this connection, or NULL
+ if GSSAPI was not used to authenticate this connection. This
+ field is truncated if the principal is longer than
+ <code class="symbol">NAMEDATALEN</code> (64 characters in a standard build).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">encrypted</code> <code class="type">boolean</code>
+ </p>
+ <p>
+ True if GSSAPI encryption is in use on this connection
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-ARCHIVER-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.12. <code class="structname">pg_stat_archiver</code></h3></div></div></div><a id="id-1.6.15.7.16.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_archiver</code> view will always have a
+ single row, containing data about the archiver process of the cluster.
+ </p><div class="table" id="PG-STAT-ARCHIVER-VIEW"><p class="title"><strong>Table 28.22. <code class="structname">pg_stat_archiver</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_archiver View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">archived_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of WAL files that have been successfully archived
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_archived_wal</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the WAL file most recently successfully archived
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_archived_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time of the most recent successful archive operation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">failed_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of failed attempts for archiving WAL files
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_failed_wal</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the WAL file of the most recent failed archival operation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_failed_time</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time of the most recent failed archival operation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Normally, WAL files are archived in order, oldest to newest, but that is
+ not guaranteed, and does not hold under special circumstances like when
+ promoting a standby or after crash recovery. Therefore it is not safe to
+ assume that all files older than
+ <code class="structfield">last_archived_wal</code> have also been successfully
+ archived.
+ </p></div><div class="sect2" id="MONITORING-PG-STAT-BGWRITER-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.13. <code class="structname">pg_stat_bgwriter</code></h3></div></div></div><a id="id-1.6.15.7.17.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_bgwriter</code> view will always have a
+ single row, containing global data for the cluster.
+ </p><div class="table" id="PG-STAT-BGWRITER-VIEW"><p class="title"><strong>Table 28.23. <code class="structname">pg_stat_bgwriter</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_bgwriter View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checkpoints_timed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of scheduled checkpoints that have been performed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checkpoints_req</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of requested checkpoints that have been performed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checkpoint_write_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total amount of time that has been spent in the portion of
+ checkpoint processing where files are written to disk, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checkpoint_sync_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total amount of time that has been spent in the portion of
+ checkpoint processing where files are synchronized to disk, in
+ milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">buffers_checkpoint</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffers written during checkpoints
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">buffers_clean</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffers written by the background writer
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">maxwritten_clean</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times the background writer stopped a cleaning
+ scan because it had written too many buffers
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">buffers_backend</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffers written directly by a backend
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">buffers_backend_fsync</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times a backend had to execute its own
+ <code class="function">fsync</code> call (normally the background writer handles those
+ even when the backend does its own write)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">buffers_alloc</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffers allocated
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-WAL-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.14. <code class="structname">pg_stat_wal</code></h3></div></div></div><a id="id-1.6.15.7.18.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_wal</code> view will always have a
+ single row, containing data about WAL activity of the cluster.
+ </p><div class="table" id="PG-STAT-WAL-VIEW"><p class="title"><strong>Table 28.24. <code class="structname">pg_stat_wal</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_wal View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_records</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of WAL records generated
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_fpi</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of WAL full page images generated
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_bytes</code> <code class="type">numeric</code>
+ </p>
+ <p>
+ Total amount of WAL generated in bytes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_buffers_full</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times WAL data was written to disk because WAL buffers became full
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_write</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times WAL buffers were written out to disk via
+ <code class="function">XLogWrite</code> request.
+ See <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a> for more information about
+ the internal WAL function <code class="function">XLogWrite</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_sync</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times WAL files were synced to disk via
+ <code class="function">issue_xlog_fsync</code> request
+ (if <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> is <code class="literal">on</code> and
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a> is either
+ <code class="literal">fdatasync</code>, <code class="literal">fsync</code> or
+ <code class="literal">fsync_writethrough</code>, otherwise zero).
+ See <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a> for more information about
+ the internal WAL function <code class="function">issue_xlog_fsync</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_write_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total amount of time spent writing WAL buffers to disk via
+ <code class="function">XLogWrite</code> request, in milliseconds
+ (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-WAL-IO-TIMING">track_wal_io_timing</a> is enabled,
+ otherwise zero). This includes the sync time when
+ <code class="varname">wal_sync_method</code> is either
+ <code class="literal">open_datasync</code> or <code class="literal">open_sync</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_sync_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total amount of time spent syncing WAL files to disk via
+ <code class="function">issue_xlog_fsync</code> request, in milliseconds
+ (if <code class="varname">track_wal_io_timing</code> is enabled,
+ <code class="varname">fsync</code> is <code class="literal">on</code>, and
+ <code class="varname">wal_sync_method</code> is either
+ <code class="literal">fdatasync</code>, <code class="literal">fsync</code> or
+ <code class="literal">fsync_writethrough</code>, otherwise zero).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-DATABASE-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.15. <code class="structname">pg_stat_database</code></h3></div></div></div><a id="id-1.6.15.7.19.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_database</code> view will contain one row
+ for each database in the cluster, plus one for shared objects, showing
+ database-wide statistics.
+ </p><div class="table" id="PG-STAT-DATABASE-VIEW"><p class="title"><strong>Table 28.25. <code class="structname">pg_stat_database</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_database View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of this database, or 0 for objects belonging to a shared
+ relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this database, or <code class="literal">NULL</code> for shared
+ objects.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">numbackends</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Number of backends currently connected to this database, or
+ <code class="literal">NULL</code> for shared objects. This is the only column
+ in this view that returns a value reflecting current state; all other
+ columns return the accumulated values since the last reset.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">xact_commit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of transactions in this database that have been
+ committed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">xact_rollback</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of transactions in this database that have been
+ rolled back
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times disk blocks were found already in the buffer
+ cache, so that a read was not necessary (this only includes hits in the
+ PostgreSQL buffer cache, not the operating system's file system cache)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tup_returned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of live rows fetched by sequential scans and index entries returned by index scans in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tup_fetched</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of live rows fetched by index scans in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tup_inserted</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows inserted by queries in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tup_updated</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows updated by queries in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tup_deleted</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows deleted by queries in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">conflicts</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries canceled due to conflicts with recovery
+ in this database. (Conflicts occur only on standby servers; see
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW" title="28.2.16. pg_stat_database_conflicts">
+ <code class="structname">pg_stat_database_conflicts</code></a> for details.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_files</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of temporary files created by queries in this database.
+ All temporary files are counted, regardless of why the temporary file
+ was created (e.g., sorting or hashing), and regardless of the
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-TEMP-FILES">log_temp_files</a> setting.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_bytes</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total amount of data written to temporary files by queries in
+ this database. All temporary files are counted, regardless of why
+ the temporary file was created, and
+ regardless of the <a class="xref" href="runtime-config-logging.html#GUC-LOG-TEMP-FILES">log_temp_files</a> setting.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">deadlocks</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of deadlocks detected in this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checksum_failures</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of data page checksum failures detected in this
+ database (or on a shared object), or NULL if data checksums are not
+ enabled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">checksum_last_failure</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which the last data page checksum failure was detected in
+ this database (or on a shared object), or NULL if data checksums are not
+ enabled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blk_read_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Time spent reading data file blocks by backends in this database,
+ in milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blk_write_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Time spent writing data file blocks by backends in this database,
+ in milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">session_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Time spent by database sessions in this database, in milliseconds
+ (note that statistics are only updated when the state of a session
+ changes, so if sessions have been idle for a long time, this idle time
+ won't be included)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">active_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Time spent executing SQL statements in this database, in milliseconds
+ (this corresponds to the states <code class="literal">active</code> and
+ <code class="literal">fastpath function call</code> in
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">
+ <code class="structname">pg_stat_activity</code></a>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idle_in_transaction_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Time spent idling while in a transaction in this database, in milliseconds
+ (this corresponds to the states <code class="literal">idle in transaction</code> and
+ <code class="literal">idle in transaction (aborted)</code> in
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">
+ <code class="structname">pg_stat_activity</code></a>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sessions</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of sessions established to this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sessions_abandoned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of database sessions to this database that were terminated
+ because connection to the client was lost
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sessions_fatal</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of database sessions to this database that were terminated
+ by fatal errors
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sessions_killed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of database sessions to this database that were terminated
+ by operator intervention
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.16. <code class="structname">pg_stat_database_conflicts</code></h3></div></div></div><a id="id-1.6.15.7.20.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_database_conflicts</code> view will contain
+ one row per database, showing database-wide statistics about
+ query cancels occurring due to conflicts with recovery on standby servers.
+ This view will only contain information on standby servers, since
+ conflicts do not occur on primary servers.
+ </p><div class="table" id="PG-STAT-DATABASE-CONFLICTS-VIEW"><p class="title"><strong>Table 28.26. <code class="structname">pg_stat_database_conflicts</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_database_conflicts View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of a database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this database
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confl_tablespace</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries in this database that have been canceled due to
+ dropped tablespaces
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confl_lock</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries in this database that have been canceled due to
+ lock timeouts
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confl_snapshot</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries in this database that have been canceled due to
+ old snapshots
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confl_bufferpin</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries in this database that have been canceled due to
+ pinned buffers
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confl_deadlock</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of queries in this database that have been canceled due to
+ deadlocks
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-ALL-TABLES-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.17. <code class="structname">pg_stat_all_tables</code></h3></div></div></div><a id="id-1.6.15.7.21.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_all_tables</code> view will contain
+ one row for each table in the current database (including TOAST
+ tables), showing statistics about accesses to that specific table. The
+ <code class="structname">pg_stat_user_tables</code> and
+ <code class="structname">pg_stat_sys_tables</code> views
+ contain the same information,
+ but filtered to only show user and system tables respectively.
+ </p><div class="table" id="PG-STAT-ALL-TABLES-VIEW"><p class="title"><strong>Table 28.27. <code class="structname">pg_stat_all_tables</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_all_tables View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of a table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema that this table is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seq_scan</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of sequential scans initiated on this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seq_tup_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of live rows fetched by sequential scans
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_scan</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of index scans initiated on this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_tup_fetch</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of live rows fetched by index scans
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_tup_ins</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows inserted
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_tup_upd</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows updated (includes <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">HOT updated rows</a>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_tup_del</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows deleted
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_tup_hot_upd</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of rows HOT updated (i.e., with no separate index
+ update required)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_live_tup</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Estimated number of live rows
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_dead_tup</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Estimated number of dead rows
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_mod_since_analyze</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Estimated number of rows modified since this table was last analyzed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_ins_since_vacuum</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Estimated number of rows inserted since this table was last vacuumed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_vacuum</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Last time at which this table was manually vacuumed
+ (not counting <code class="command">VACUUM FULL</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_autovacuum</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Last time at which this table was vacuumed by the autovacuum
+ daemon
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_analyze</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Last time at which this table was manually analyzed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_autoanalyze</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Last time at which this table was analyzed by the autovacuum
+ daemon
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">vacuum_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times this table has been manually vacuumed
+ (not counting <code class="command">VACUUM FULL</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">autovacuum_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times this table has been vacuumed by the autovacuum
+ daemon
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">analyze_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times this table has been manually analyzed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">autoanalyze_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times this table has been analyzed by the autovacuum
+ daemon
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-ALL-INDEXES-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.18. <code class="structname">pg_stat_all_indexes</code></h3></div></div></div><a id="id-1.6.15.7.22.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_all_indexes</code> view will contain
+ one row for each index in the current database,
+ showing statistics about accesses to that specific index. The
+ <code class="structname">pg_stat_user_indexes</code> and
+ <code class="structname">pg_stat_sys_indexes</code> views
+ contain the same information,
+ but filtered to only show user and system indexes respectively.
+ </p><div class="table" id="PG-STAT-ALL-INDEXES-VIEW"><p class="title"><strong>Table 28.28. <code class="structname">pg_stat_all_indexes</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_all_indexes View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table for this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexrelid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema this index is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the table for this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexrelname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_scan</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of index scans initiated on this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_tup_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of index entries returned by scans on this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_tup_fetch</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of live table rows fetched by simple index scans using this
+ index
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Indexes can be used by simple index scans, <span class="quote">“<span class="quote">bitmap</span>”</span> index scans,
+ and the optimizer. In a bitmap scan
+ the output of several indexes can be combined via AND or OR rules,
+ so it is difficult to associate individual heap row fetches
+ with specific indexes when a bitmap scan is used. Therefore, a bitmap
+ scan increments the
+ <code class="structname">pg_stat_all_indexes</code>.<code class="structfield">idx_tup_read</code>
+ count(s) for the index(es) it uses, and it increments the
+ <code class="structname">pg_stat_all_tables</code>.<code class="structfield">idx_tup_fetch</code>
+ count for the table, but it does not affect
+ <code class="structname">pg_stat_all_indexes</code>.<code class="structfield">idx_tup_fetch</code>.
+ The optimizer also accesses indexes to check for supplied constants
+ whose values are outside the recorded range of the optimizer statistics
+ because the optimizer statistics might be stale.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="structfield">idx_tup_read</code> and <code class="structfield">idx_tup_fetch</code> counts
+ can be different even without any use of bitmap scans,
+ because <code class="structfield">idx_tup_read</code> counts
+ index entries retrieved from the index while <code class="structfield">idx_tup_fetch</code>
+ counts live rows fetched from the table. The latter will be less if any
+ dead or not-yet-committed rows are fetched using the index, or if any
+ heap fetches are avoided by means of an index-only scan.
+ </p></div></div><div class="sect2" id="MONITORING-PG-STATIO-ALL-TABLES-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.19. <code class="structname">pg_statio_all_tables</code></h3></div></div></div><a id="id-1.6.15.7.23.2" class="indexterm"></a><p>
+ The <code class="structname">pg_statio_all_tables</code> view will contain
+ one row for each table in the current database (including TOAST
+ tables), showing statistics about I/O on that specific table. The
+ <code class="structname">pg_statio_user_tables</code> and
+ <code class="structname">pg_statio_sys_tables</code> views
+ contain the same information,
+ but filtered to only show user and system tables respectively.
+ </p><div class="table" id="PG-STATIO-ALL-TABLES-VIEW"><p class="title"><strong>Table 28.29. <code class="structname">pg_statio_all_tables</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_statio_all_tables View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of a table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema that this table is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from all indexes on this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in all indexes on this table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">toast_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from this table's TOAST table (if any)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">toast_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in this table's TOAST table (if any)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tidx_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from this table's TOAST table indexes (if any)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tidx_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in this table's TOAST table indexes (if any)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STATIO-ALL-INDEXES-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.20. <code class="structname">pg_statio_all_indexes</code></h3></div></div></div><a id="id-1.6.15.7.24.2" class="indexterm"></a><p>
+ The <code class="structname">pg_statio_all_indexes</code> view will contain
+ one row for each index in the current database,
+ showing statistics about I/O on that specific index. The
+ <code class="structname">pg_statio_user_indexes</code> and
+ <code class="structname">pg_statio_sys_indexes</code> views
+ contain the same information,
+ but filtered to only show user and system indexes respectively.
+ </p><div class="table" id="PG-STATIO-ALL-INDEXES-VIEW"><p class="title"><strong>Table 28.30. <code class="structname">pg_statio_all_indexes</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_statio_all_indexes View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table for this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexrelid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema this index is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the table for this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexrelname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from this index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">idx_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in this index
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STATIO-ALL-SEQUENCES-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.21. <code class="structname">pg_statio_all_sequences</code></h3></div></div></div><a id="id-1.6.15.7.25.2" class="indexterm"></a><p>
+ The <code class="structname">pg_statio_all_sequences</code> view will contain
+ one row for each sequence in the current database,
+ showing statistics about I/O on that specific sequence.
+ </p><div class="table" id="PG-STATIO-ALL-SEQUENCES-VIEW"><p class="title"><strong>Table 28.31. <code class="structname">pg_statio_all_sequences</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_statio_all_sequences View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of a sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema this sequence is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read from this sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of buffer hits in this sequence
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-USER-FUNCTIONS-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.22. <code class="structname">pg_stat_user_functions</code></h3></div></div></div><a id="id-1.6.15.7.26.2" class="indexterm"></a><p>
+ The <code class="structname">pg_stat_user_functions</code> view will contain
+ one row for each tracked function, showing statistics about executions of
+ that function. The <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-FUNCTIONS">track_functions</a> parameter
+ controls exactly which functions are tracked.
+ </p><div class="table" id="PG-STAT-USER-FUNCTIONS-VIEW"><p class="title"><strong>Table 28.32. <code class="structname">pg_stat_user_functions</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_user_functions View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">funcid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of a function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema this function is in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">funcname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of this function
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">calls</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times this function has been called
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent in this function and all other functions
+ called by it, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">self_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent in this function itself, not including
+ other functions called by it, in milliseconds
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-PG-STAT-SLRU-VIEW"><div class="titlepage"><div><div><h3 class="title">28.2.23. <code class="structname">pg_stat_slru</code></h3></div></div></div><a id="id-1.6.15.7.27.2" class="indexterm"></a><a id="id-1.6.15.7.27.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> accesses certain on-disk information
+ via <em class="firstterm">SLRU</em> (simple least-recently-used) caches.
+ The <code class="structname">pg_stat_slru</code> view will contain
+ one row for each tracked SLRU cache, showing statistics about access
+ to cached pages.
+ </p><div class="table" id="PG-STAT-SLRU-VIEW"><p class="title"><strong>Table 28.33. <code class="structname">pg_stat_slru</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_slru View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_zeroed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks zeroed during initializations
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times disk blocks were found already in the SLRU,
+ so that a read was not necessary (this only includes hits in the
+ SLRU, not the operating system's file system cache)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks read for this SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_written</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of disk blocks written for this SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blks_exists</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks checked for existence for this SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">flushes</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of flushes of dirty data for this SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">truncates</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of truncates for this SLRU
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which these statistics were last reset
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="MONITORING-STATS-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">28.2.24. Statistics Functions</h3></div></div></div><p>
+ Other ways of looking at the statistics can be set up by writing
+ queries that use the same underlying statistics access functions used by
+ the standard views shown above. For details such as the functions' names,
+ consult the definitions of the standard views. (For example, in
+ <span class="application">psql</span> you could issue <code class="literal">\d+ pg_stat_activity</code>.)
+ The access functions for per-database statistics take a database OID as an
+ argument to identify which database to report on.
+ The per-table and per-index functions take a table or index OID.
+ The functions for per-function statistics take a function OID.
+ Note that only tables, indexes, and functions in the current database
+ can be seen with these functions.
+ </p><p>
+ Additional functions related to the cumulative statistics system are listed
+ in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-FUNCS-TABLE" title="Table 28.34. Additional Statistics Functions">Table 28.34</a>.
+ </p><div class="table" id="MONITORING-STATS-FUNCS-TABLE"><p class="title"><strong>Table 28.34. Additional Statistics Functions</strong></p><div class="table-contents"><table class="table" summary="Additional Statistics Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pg_backend_pid</code> ()
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the process ID of the server process attached to the current
+ session.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_activity</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Returns a record of information about the backend with the specified
+ process ID, or one record for each active backend in the system
+ if <code class="literal">NULL</code> is specified. The fields returned are a
+ subset of those in the <code class="structname">pg_stat_activity</code> view.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_snapshot_timestamp</code> ()
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the timestamp of the current statistics snapshot, or NULL if
+ no statistics snapshot has been taken. A snapshot is taken the first
+ time cumulative statistics are accessed in a transaction if
+ <code class="varname">stats_fetch_consistency</code> is set to
+ <code class="literal">snapshot</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_xact_blocks_fetched</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the number of block read requests for table or index, in the
+ current transaction. This number minus
+ <code class="function">pg_stat_get_xact_blocks_hit</code> gives the number of
+ kernel <code class="function">read()</code> calls; the number of actual
+ physical reads is usually lower due to kernel-level buffering.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_xact_blocks_hit</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">bigint</code>
+ </p>
+ <p>
+ Returns the number of block read requests for table or index, in the
+ current transaction, found in cache (not triggering kernel
+ <code class="function">read()</code> calls).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_clear_snapshot</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Discards the current statistics snapshot or cached information.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset</code> ()
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets all statistics counters for the current database to zero.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_shared</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets some cluster-wide statistics counters to zero, depending on the
+ argument. The argument can be <code class="literal">bgwriter</code> to reset
+ all the counters shown in
+ the <code class="structname">pg_stat_bgwriter</code>
+ view, <code class="literal">archiver</code> to reset all the counters shown in
+ the <code class="structname">pg_stat_archiver</code> view,
+ <code class="literal">wal</code> to reset all the counters shown in the
+ <code class="structname">pg_stat_wal</code> view or
+ <code class="literal">recovery_prefetch</code> to reset all the counters shown
+ in the <code class="structname">pg_stat_recovery_prefetch</code> view.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_single_table_counters</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets statistics for a single table or index in the current database
+ or shared across all databases in the cluster to zero.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_single_function_counters</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets statistics for a single function in the current database to
+ zero.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_slru</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets statistics to zero for a single SLRU cache, or for all SLRUs in
+ the cluster. If the argument is NULL, all counters shown in
+ the <code class="structname">pg_stat_slru</code> view for all SLRU caches are
+ reset. The argument can be one of
+ <code class="literal">CommitTs</code>,
+ <code class="literal">MultiXactMember</code>,
+ <code class="literal">MultiXactOffset</code>,
+ <code class="literal">Notify</code>,
+ <code class="literal">Serial</code>,
+ <code class="literal">Subtrans</code>, or
+ <code class="literal">Xact</code>
+ to reset the counters for only that entry.
+ If the argument is <code class="literal">other</code> (or indeed, any
+ unrecognized name), then the counters for all other SLRU caches, such
+ as extension-defined caches, are reset.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_replication_slot</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets statistics of the replication slot defined by the argument. If
+ the argument is <code class="literal">NULL</code>, resets statistics for all
+ the replication slots.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.4.2.2.13.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_reset_subscription_stats</code> ( <code class="type">oid</code> )
+ → <code class="returnvalue">void</code>
+ </p>
+ <p>
+ Resets statistics for a single subscription shown in the
+ <code class="structname">pg_stat_subscription_stats</code> view to zero. If
+ the argument is <code class="literal">NULL</code>, reset statistics for all
+ subscriptions.
+ </p>
+ <p>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="warning"><h3 class="title">Warning</h3><p>
+ Using <code class="function">pg_stat_reset()</code> also resets counters that
+ autovacuum uses to determine when to trigger a vacuum or an analyze.
+ Resetting these counters can cause autovacuum to not perform necessary
+ work, which can cause problems such as table bloat or out-dated
+ table statistics. A database-wide <code class="command">ANALYZE</code> is
+ recommended after the statistics have been reset.
+ </p></div><p>
+ <code class="function">pg_stat_get_activity</code>, the underlying function of
+ the <code class="structname">pg_stat_activity</code> view, returns a set of records
+ containing all the available information about each backend process.
+ Sometimes it may be more convenient to obtain just a subset of this
+ information. In such cases, an older set of per-backend statistics
+ access functions can be used; these are shown in <a class="xref" href="monitoring-stats.html#MONITORING-STATS-BACKEND-FUNCS-TABLE" title="Table 28.35. Per-Backend Statistics Functions">Table 28.35</a>.
+ These access functions use a backend ID number, which ranges from one
+ to the number of currently active backends.
+ The function <code class="function">pg_stat_get_backend_idset</code> provides a
+ convenient way to generate one row for each active backend for
+ invoking these functions. For example, to show the <acronym class="acronym">PID</acronym>s and
+ current queries of all backends:
+
+</p><pre class="programlisting">
+SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
+ pg_stat_get_backend_activity(s.backendid) AS query
+ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
+</pre><p>
+ </p><div class="table" id="MONITORING-STATS-BACKEND-FUNCS-TABLE"><p class="title"><strong>Table 28.35. Per-Backend Statistics Functions</strong></p><div class="table-contents"><table class="table" summary="Per-Backend Statistics Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_idset</code> ()
+ → <code class="returnvalue">setof integer</code>
+ </p>
+ <p>
+ Returns the set of currently active backend ID numbers (from 1 to the
+ number of active backends).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_activity</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the text of this backend's most recent query.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_activity_start</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time when the backend's most recent query was started.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_client_addr</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">inet</code>
+ </p>
+ <p>
+ Returns the IP address of the client connected to this backend.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_client_port</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the TCP port number that the client is using for communication.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_dbid</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Returns the OID of the database this backend is connected to.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.7.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_pid</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Returns the process ID of this backend.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.8.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_start</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time when this process was started.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.9.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_userid</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">oid</code>
+ </p>
+ <p>
+ Returns the OID of the user logged into this backend.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.10.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_wait_event_type</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the wait event type name if this backend is currently waiting,
+ otherwise NULL. See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-TABLE" title="Table 28.4. Wait Event Types">Table 28.4</a> for details.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.11.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_wait_event</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the wait event name if this backend is currently waiting,
+ otherwise NULL. See <a class="xref" href="monitoring-stats.html#WAIT-EVENT-ACTIVITY-TABLE" title="Table 28.5. Wait Events of Type Activity">Table 28.5</a> through
+ <a class="xref" href="monitoring-stats.html#WAIT-EVENT-TIMEOUT-TABLE" title="Table 28.13. Wait Events of Type Timeout">Table 28.13</a>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.6.15.7.28.7.2.2.12.1.1.1" class="indexterm"></a>
+ <code class="function">pg_stat_get_backend_xact_start</code> ( <code class="type">integer</code> )
+ → <code class="returnvalue">timestamp with time zone</code>
+ </p>
+ <p>
+ Returns the time when the backend's current transaction was started.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="monitoring-locks.html" title="28.3. Viewing Locks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.1. Standard Unix Tools </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 28.3. Viewing Locks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/monitoring.html b/doc/src/sgml/html/monitoring.html
new file mode 100644
index 0000000..5ab0adf
--- /dev/null
+++ b/doc/src/sgml/html/monitoring.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 28. Monitoring Database Activity</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="hot-standby.html" title="27.4. Hot Standby" /><link rel="next" href="monitoring-ps.html" title="28.1. Standard Unix Tools" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 28. Monitoring Database Activity</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="hot-standby.html" title="27.4. Hot Standby">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Next</a></td></tr></table><hr /></div><div class="chapter" id="MONITORING"><div class="titlepage"><div><div><h2 class="title">Chapter 28. Monitoring Database Activity</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="monitoring-ps.html">28.1. Standard Unix Tools</a></span></dt><dt><span class="sect1"><a href="monitoring-stats.html">28.2. The Cumulative Statistics System</a></span></dt><dd><dl><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-SETUP">28.2.1. Statistics Collection Configuration</a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-VIEWS">28.2.2. Viewing Statistics</a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW">28.2.3. <code class="structname">pg_stat_activity</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW">28.2.4. <code class="structname">pg_stat_replication</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-SLOTS-VIEW">28.2.5. <code class="structname">pg_stat_replication_slots</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-WAL-RECEIVER-VIEW">28.2.6. <code class="structname">pg_stat_wal_receiver</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-RECOVERY-PREFETCH">28.2.7. <code class="structname">pg_stat_recovery_prefetch</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION">28.2.8. <code class="structname">pg_stat_subscription</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION-STATS">28.2.9. <code class="structname">pg_stat_subscription_stats</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW">28.2.10. <code class="structname">pg_stat_ssl</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-GSSAPI-VIEW">28.2.11. <code class="structname">pg_stat_gssapi</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ARCHIVER-VIEW">28.2.12. <code class="structname">pg_stat_archiver</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-BGWRITER-VIEW">28.2.13. <code class="structname">pg_stat_bgwriter</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-WAL-VIEW">28.2.14. <code class="structname">pg_stat_wal</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW">28.2.15. <code class="structname">pg_stat_database</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-CONFLICTS-VIEW">28.2.16. <code class="structname">pg_stat_database_conflicts</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW">28.2.17. <code class="structname">pg_stat_all_tables</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-ALL-INDEXES-VIEW">28.2.18. <code class="structname">pg_stat_all_indexes</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-TABLES-VIEW">28.2.19. <code class="structname">pg_statio_all_tables</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-INDEXES-VIEW">28.2.20. <code class="structname">pg_statio_all_indexes</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-SEQUENCES-VIEW">28.2.21. <code class="structname">pg_statio_all_sequences</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-USER-FUNCTIONS-VIEW">28.2.22. <code class="structname">pg_stat_user_functions</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-PG-STAT-SLRU-VIEW">28.2.23. <code class="structname">pg_stat_slru</code></a></span></dt><dt><span class="sect2"><a href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS">28.2.24. Statistics Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="monitoring-locks.html">28.3. Viewing Locks</a></span></dt><dt><span class="sect1"><a href="progress-reporting.html">28.4. Progress Reporting</a></span></dt><dd><dl><dt><span class="sect2"><a href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING">28.4.1. ANALYZE Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING">28.4.2. CREATE INDEX Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#VACUUM-PROGRESS-REPORTING">28.4.3. VACUUM Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING">28.4.4. CLUSTER Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING">28.4.5. Base Backup Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#COPY-PROGRESS-REPORTING">28.4.6. COPY Progress Reporting</a></span></dt></dl></dd><dt><span class="sect1"><a href="dynamic-trace.html">28.5. Dynamic Tracing</a></span></dt><dd><dl><dt><span class="sect2"><a href="dynamic-trace.html#COMPILING-FOR-TRACE">28.5.1. Compiling for Dynamic Tracing</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#TRACE-POINTS">28.5.2. Built-in Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#USING-TRACE-POINTS">28.5.3. Using Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#DEFINING-TRACE-POINTS">28.5.4. Defining New Probes</a></span></dt></dl></dd></dl></div><a id="id-1.6.15.2" class="indexterm"></a><a id="id-1.6.15.3" class="indexterm"></a><p>
+ A database administrator frequently wonders, <span class="quote">“<span class="quote">What is the system
+ doing right now?</span>”</span>
+ This chapter discusses how to find that out.
+ </p><p>
+ Several tools are available for monitoring database activity and
+ analyzing performance. Most of this chapter is devoted to describing
+ <span class="productname">PostgreSQL</span>'s cumulative statistics system,
+ but one should not neglect regular Unix monitoring programs such as
+ <code class="command">ps</code>, <code class="command">top</code>, <code class="command">iostat</code>, and <code class="command">vmstat</code>.
+ Also, once one has identified a
+ poorly-performing query, further investigation might be needed using
+ <span class="productname">PostgreSQL</span>'s <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN</code></a> command.
+ <a class="xref" href="using-explain.html" title="14.1. Using EXPLAIN">Section 14.1</a> discusses <code class="command">EXPLAIN</code>
+ and other methods for understanding the behavior of an individual
+ query.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="hot-standby.html" title="27.4. Hot Standby">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Next</a></td></tr><tr><td width="40%" align="left" valign="top">27.4. Hot Standby </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 28.1. Standard Unix Tools</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/multibyte.html b/doc/src/sgml/html/multibyte.html
new file mode 100644
index 0000000..1a15f68
--- /dev/null
+++ b/doc/src/sgml/html/multibyte.html
@@ -0,0 +1,351 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>24.3. Character Set Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="collation.html" title="24.2. Collation Support" /><link rel="next" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">24.3. Character Set Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="collation.html" title="24.2. Collation Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><th width="60%" align="center">Chapter 24. Localization</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Next</a></td></tr></table><hr /></div><div class="sect1" id="MULTIBYTE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">24.3. Character Set Support</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED">24.3.1. Supported Character Sets</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.6">24.3.2. Setting the Character Set</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.7">24.3.3. Automatic Character Set Conversion Between Server and Client</a></span></dt><dt><span class="sect2"><a href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED">24.3.4. Available Character Set Conversions</a></span></dt><dt><span class="sect2"><a href="multibyte.html#id-1.6.11.5.9">24.3.5. Further Reading</a></span></dt></dl></div><a id="id-1.6.11.5.2" class="indexterm"></a><p>
+ The character set support in <span class="productname">PostgreSQL</span>
+ allows you to store text in a variety of character sets (also called
+ encodings), including
+ single-byte character sets such as the ISO 8859 series and
+ multiple-byte character sets such as <acronym class="acronym">EUC</acronym> (Extended Unix
+ Code), UTF-8, and Mule internal code. All supported character sets
+ can be used transparently by clients, but a few are not supported
+ for use within the server (that is, as a server-side encoding).
+ The default character set is selected while
+ initializing your <span class="productname">PostgreSQL</span> database
+ cluster using <code class="command">initdb</code>. It can be overridden when you
+ create a database, so you can have multiple
+ databases each with a different character set.
+ </p><p>
+ An important restriction, however, is that each database's character set
+ must be compatible with the database's <code class="envar">LC_CTYPE</code> (character
+ classification) and <code class="envar">LC_COLLATE</code> (string sort order) locale
+ settings. For <code class="literal">C</code> or
+ <code class="literal">POSIX</code> locale, any character set is allowed, but for other
+ libc-provided locales there is only one character set that will work
+ correctly.
+ (On Windows, however, UTF-8 encoding can be used with any locale.)
+ If you have ICU support configured, ICU-provided locales can be used
+ with most but not all server-side encodings.
+ </p><div class="sect2" id="MULTIBYTE-CHARSET-SUPPORTED"><div class="titlepage"><div><div><h3 class="title">24.3.1. Supported Character Sets</h3></div></div></div><p>
+ <a class="xref" href="multibyte.html#CHARSET-TABLE" title="Table 24.1. PostgreSQL Character Sets">Table 24.1</a> shows the character sets available
+ for use in <span class="productname">PostgreSQL</span>.
+ </p><div class="table" id="CHARSET-TABLE"><p class="title"><strong>Table 24.1. <span class="productname">PostgreSQL</span> Character Sets</strong></p><div class="table-contents"><table class="table" summary="PostgreSQL Character Sets" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /><col class="col6" /><col class="col7" /></colgroup><thead><tr><th>Name</th><th>Description</th><th>Language</th><th>Server?</th><th>ICU?</th><th>Bytes/​Char</th><th>Aliases</th></tr></thead><tbody><tr><td><code class="literal">BIG5</code></td><td>Big Five</td><td>Traditional Chinese</td><td>No</td><td>No</td><td>1–2</td><td><code class="literal">WIN950</code>, <code class="literal">Windows950</code></td></tr><tr><td><code class="literal">EUC_CN</code></td><td>Extended UNIX Code-CN</td><td>Simplified Chinese</td><td>Yes</td><td>Yes</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">EUC_JP</code></td><td>Extended UNIX Code-JP</td><td>Japanese</td><td>Yes</td><td>Yes</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">EUC_JIS_2004</code></td><td>Extended UNIX Code-JP, JIS X 0213</td><td>Japanese</td><td>Yes</td><td>No</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">EUC_KR</code></td><td>Extended UNIX Code-KR</td><td>Korean</td><td>Yes</td><td>Yes</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">EUC_TW</code></td><td>Extended UNIX Code-TW</td><td>Traditional Chinese, Taiwanese</td><td>Yes</td><td>Yes</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">GB18030</code></td><td>National Standard</td><td>Chinese</td><td>No</td><td>No</td><td>1–4</td><td> </td></tr><tr><td><code class="literal">GBK</code></td><td>Extended National Standard</td><td>Simplified Chinese</td><td>No</td><td>No</td><td>1–2</td><td><code class="literal">WIN936</code>, <code class="literal">Windows936</code></td></tr><tr><td><code class="literal">ISO_8859_5</code></td><td>ISO 8859-5, <acronym class="acronym">ECMA</acronym> 113</td><td>Latin/Cyrillic</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">ISO_8859_6</code></td><td>ISO 8859-6, <acronym class="acronym">ECMA</acronym> 114</td><td>Latin/Arabic</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">ISO_8859_7</code></td><td>ISO 8859-7, <acronym class="acronym">ECMA</acronym> 118</td><td>Latin/Greek</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">ISO_8859_8</code></td><td>ISO 8859-8, <acronym class="acronym">ECMA</acronym> 121</td><td>Latin/Hebrew</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">JOHAB</code></td><td><acronym class="acronym">JOHAB</acronym></td><td>Korean (Hangul)</td><td>No</td><td>No</td><td>1–3</td><td> </td></tr><tr><td><code class="literal">KOI8R</code></td><td><acronym class="acronym">KOI</acronym>8-R</td><td>Cyrillic (Russian)</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">KOI8</code></td></tr><tr><td><code class="literal">KOI8U</code></td><td><acronym class="acronym">KOI</acronym>8-U</td><td>Cyrillic (Ukrainian)</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">LATIN1</code></td><td>ISO 8859-1, <acronym class="acronym">ECMA</acronym> 94</td><td>Western European</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO88591</code></td></tr><tr><td><code class="literal">LATIN2</code></td><td>ISO 8859-2, <acronym class="acronym">ECMA</acronym> 94</td><td>Central European</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO88592</code></td></tr><tr><td><code class="literal">LATIN3</code></td><td>ISO 8859-3, <acronym class="acronym">ECMA</acronym> 94</td><td>South European</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO88593</code></td></tr><tr><td><code class="literal">LATIN4</code></td><td>ISO 8859-4, <acronym class="acronym">ECMA</acronym> 94</td><td>North European</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO88594</code></td></tr><tr><td><code class="literal">LATIN5</code></td><td>ISO 8859-9, <acronym class="acronym">ECMA</acronym> 128</td><td>Turkish</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO88599</code></td></tr><tr><td><code class="literal">LATIN6</code></td><td>ISO 8859-10, <acronym class="acronym">ECMA</acronym> 144</td><td>Nordic</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO885910</code></td></tr><tr><td><code class="literal">LATIN7</code></td><td>ISO 8859-13</td><td>Baltic</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO885913</code></td></tr><tr><td><code class="literal">LATIN8</code></td><td>ISO 8859-14</td><td>Celtic</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO885914</code></td></tr><tr><td><code class="literal">LATIN9</code></td><td>ISO 8859-15</td><td>LATIN1 with Euro and accents</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ISO885915</code></td></tr><tr><td><code class="literal">LATIN10</code></td><td>ISO 8859-16, <acronym class="acronym">ASRO</acronym> SR 14111</td><td>Romanian</td><td>Yes</td><td>No</td><td>1</td><td><code class="literal">ISO885916</code></td></tr><tr><td><code class="literal">MULE_INTERNAL</code></td><td>Mule internal code</td><td>Multilingual Emacs</td><td>Yes</td><td>No</td><td>1–4</td><td> </td></tr><tr><td><code class="literal">SJIS</code></td><td>Shift JIS</td><td>Japanese</td><td>No</td><td>No</td><td>1–2</td><td><code class="literal">Mskanji</code>, <code class="literal">ShiftJIS</code>, <code class="literal">WIN932</code>, <code class="literal">Windows932</code></td></tr><tr><td><code class="literal">SHIFT_JIS_2004</code></td><td>Shift JIS, JIS X 0213</td><td>Japanese</td><td>No</td><td>No</td><td>1–2</td><td> </td></tr><tr><td><code class="literal">SQL_ASCII</code></td><td>unspecified (see text)</td><td><span class="emphasis"><em>any</em></span></td><td>Yes</td><td>No</td><td>1</td><td> </td></tr><tr><td><code class="literal">UHC</code></td><td>Unified Hangul Code</td><td>Korean</td><td>No</td><td>No</td><td>1–2</td><td><code class="literal">WIN949</code>, <code class="literal">Windows949</code></td></tr><tr><td><code class="literal">UTF8</code></td><td>Unicode, 8-bit</td><td><span class="emphasis"><em>all</em></span></td><td>Yes</td><td>Yes</td><td>1–4</td><td><code class="literal">Unicode</code></td></tr><tr><td><code class="literal">WIN866</code></td><td>Windows CP866</td><td>Cyrillic</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ALT</code></td></tr><tr><td><code class="literal">WIN874</code></td><td>Windows CP874</td><td>Thai</td><td>Yes</td><td>No</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1250</code></td><td>Windows CP1250</td><td>Central European</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1251</code></td><td>Windows CP1251</td><td>Cyrillic</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">WIN</code></td></tr><tr><td><code class="literal">WIN1252</code></td><td>Windows CP1252</td><td>Western European</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1253</code></td><td>Windows CP1253</td><td>Greek</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1254</code></td><td>Windows CP1254</td><td>Turkish</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1255</code></td><td>Windows CP1255</td><td>Hebrew</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1256</code></td><td>Windows CP1256</td><td>Arabic</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1257</code></td><td>Windows CP1257</td><td>Baltic</td><td>Yes</td><td>Yes</td><td>1</td><td> </td></tr><tr><td><code class="literal">WIN1258</code></td><td>Windows CP1258</td><td>Vietnamese</td><td>Yes</td><td>Yes</td><td>1</td><td><code class="literal">ABC</code>, <code class="literal">TCVN</code>, <code class="literal">TCVN5712</code>, <code class="literal">VSCII</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Not all client <acronym class="acronym">API</acronym>s support all the listed character sets. For example, the
+ <span class="productname">PostgreSQL</span>
+ JDBC driver does not support <code class="literal">MULE_INTERNAL</code>, <code class="literal">LATIN6</code>,
+ <code class="literal">LATIN8</code>, and <code class="literal">LATIN10</code>.
+ </p><p>
+ The <code class="literal">SQL_ASCII</code> setting behaves considerably differently
+ from the other settings. When the server character set is
+ <code class="literal">SQL_ASCII</code>, the server interprets byte values 0–127
+ according to the ASCII standard, while byte values 128–255 are taken
+ as uninterpreted characters. No encoding conversion will be done when
+ the setting is <code class="literal">SQL_ASCII</code>. Thus, this setting is not so
+ much a declaration that a specific encoding is in use, as a declaration
+ of ignorance about the encoding. In most cases, if you are
+ working with any non-ASCII data, it is unwise to use the
+ <code class="literal">SQL_ASCII</code> setting because
+ <span class="productname">PostgreSQL</span> will be unable to help you by
+ converting or validating non-ASCII characters.
+ </p></div><div class="sect2" id="id-1.6.11.5.6"><div class="titlepage"><div><div><h3 class="title">24.3.2. Setting the Character Set</h3></div></div></div><p>
+ <code class="command">initdb</code> defines the default character set (encoding)
+ for a <span class="productname">PostgreSQL</span> cluster. For example,
+
+</p><pre class="screen">
+initdb -E EUC_JP
+</pre><p>
+
+ sets the default character set to
+ <code class="literal">EUC_JP</code> (Extended Unix Code for Japanese). You
+ can use <code class="option">--encoding</code> instead of
+ <code class="option">-E</code> if you prefer longer option strings.
+ If no <code class="option">-E</code> or <code class="option">--encoding</code> option is
+ given, <code class="command">initdb</code> attempts to determine the appropriate
+ encoding to use based on the specified or default locale.
+ </p><p>
+ You can specify a non-default encoding at database creation time,
+ provided that the encoding is compatible with the selected locale:
+
+</p><pre class="screen">
+createdb -E EUC_KR -T template0 --lc-collate=ko_KR.euckr --lc-ctype=ko_KR.euckr korean
+</pre><p>
+
+ This will create a database named <code class="literal">korean</code> that
+ uses the character set <code class="literal">EUC_KR</code>, and locale <code class="literal">ko_KR</code>.
+ Another way to accomplish this is to use this SQL command:
+
+</p><pre class="programlisting">
+CREATE DATABASE korean WITH ENCODING 'EUC_KR' LC_COLLATE='ko_KR.euckr' LC_CTYPE='ko_KR.euckr' TEMPLATE=template0;
+</pre><p>
+
+ Notice that the above commands specify copying the <code class="literal">template0</code>
+ 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
+ <a class="xref" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Section 23.3</a>.
+ </p><p>
+ The encoding for a database is stored in the system catalog
+ <code class="literal">pg_database</code>. You can see it by using the
+ <code class="command">psql</code> <code class="option">-l</code> option or the
+ <code class="command">\l</code> command.
+
+</p><pre class="screen">
+$ <strong class="userinput"><code>psql -l</code></strong>
+ List of databases
+ Name | Owner | Encoding | Collation | Ctype | Access Privileges
+-----------+----------+-----------+-------------+-------------+-------------------------------------
+ clocaledb | hlinnaka | SQL_ASCII | C | C |
+ englishdb | hlinnaka | UTF8 | en_GB.UTF8 | en_GB.UTF8 |
+ japanese | hlinnaka | UTF8 | ja_JP.UTF8 | ja_JP.UTF8 |
+ korean | hlinnaka | EUC_KR | ko_KR.euckr | ko_KR.euckr |
+ postgres | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 |
+ template0 | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 | {=c/hlinnaka,hlinnaka=CTc/hlinnaka}
+ template1 | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 | {=c/hlinnaka,hlinnaka=CTc/hlinnaka}
+(7 rows)
+</pre><p>
+ </p><div class="important"><h3 class="title">Important</h3><p>
+ On most modern operating systems, <span class="productname">PostgreSQL</span>
+ can determine which character set is implied by the <code class="envar">LC_CTYPE</code>
+ setting, and it will enforce that only the matching database encoding is
+ used. On older systems it is your responsibility to ensure that you use
+ the encoding expected by the locale you have selected. A mistake in
+ this area is likely to lead to strange behavior of locale-dependent
+ operations such as sorting.
+ </p><p>
+ <span class="productname">PostgreSQL</span> will allow superusers to create
+ databases with <code class="literal">SQL_ASCII</code> encoding even when
+ <code class="envar">LC_CTYPE</code> is not <code class="literal">C</code> or <code class="literal">POSIX</code>. As noted
+ above, <code class="literal">SQL_ASCII</code> does not enforce that the data stored in
+ the database has any particular encoding, and so this choice poses risks
+ of locale-dependent misbehavior. Using this combination of settings is
+ deprecated and may someday be forbidden altogether.
+ </p></div></div><div class="sect2" id="id-1.6.11.5.7"><div class="titlepage"><div><div><h3 class="title">24.3.3. Automatic Character Set Conversion Between Server and Client</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> supports automatic character
+ set conversion between server and client for many combinations of
+ character sets (<a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a>
+ shows which ones).
+ </p><p>
+ To enable automatic character set conversion, you have to
+ tell <span class="productname">PostgreSQL</span> the character set
+ (encoding) you would like to use in the client. There are several
+ ways to accomplish this:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Using the <code class="command">\encoding</code> command in
+ <span class="application">psql</span>.
+ <code class="command">\encoding</code> allows you to change client
+ encoding on the fly. For
+ example, to change the encoding to <code class="literal">SJIS</code>, type:
+
+</p><pre class="programlisting">
+\encoding SJIS
+</pre><p>
+ </p></li><li class="listitem"><p>
+ <span class="application">libpq</span> (<a class="xref" href="libpq-control.html" title="34.11. Control Functions">Section 34.11</a>) has functions to control the client encoding.
+ </p></li><li class="listitem"><p>
+ Using <code class="command">SET client_encoding TO</code>.
+
+ Setting the client encoding can be done with this SQL command:
+
+</p><pre class="programlisting">
+SET CLIENT_ENCODING TO '<em class="replaceable"><code>value</code></em>';
+</pre><p>
+
+ Also you can use the standard SQL syntax <code class="literal">SET NAMES</code>
+ for this purpose:
+
+</p><pre class="programlisting">
+SET NAMES '<em class="replaceable"><code>value</code></em>';
+</pre><p>
+
+ To query the current client encoding:
+
+</p><pre class="programlisting">
+SHOW client_encoding;
+</pre><p>
+
+ To return to the default encoding:
+
+</p><pre class="programlisting">
+RESET client_encoding;
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Using <code class="envar">PGCLIENTENCODING</code>. If the environment variable
+ <code class="envar">PGCLIENTENCODING</code> is defined in the client's
+ environment, that client encoding is automatically selected
+ when a connection to the server is made. (This can
+ subsequently be overridden using any of the other methods
+ mentioned above.)
+ </p></li><li class="listitem"><p>
+ Using the configuration variable <a class="xref" href="runtime-config-client.html#GUC-CLIENT-ENCODING">client_encoding</a>. If the
+ <code class="varname">client_encoding</code> variable is set, that client
+ encoding is automatically selected when a connection to the
+ server is made. (This can subsequently be overridden using any
+ of the other methods mentioned above.)
+ </p></li></ul></div><p>
+ </p><p>
+ If the conversion of a particular character is not possible
+ — suppose you chose <code class="literal">EUC_JP</code> for the
+ server and <code class="literal">LATIN1</code> for the client, and some
+ Japanese characters are returned that do not have a representation in
+ <code class="literal">LATIN1</code> — an error is reported.
+ </p><p>
+ If the client character set is defined as <code class="literal">SQL_ASCII</code>,
+ encoding conversion is disabled, regardless of the server's character
+ set. (However, if the server's character set is
+ not <code class="literal">SQL_ASCII</code>, the server will still check that
+ incoming data is valid for that encoding; so the net effect is as
+ though the client character set were the same as the server's.)
+ Just as for the server, use of <code class="literal">SQL_ASCII</code> is unwise
+ unless you are working with all-ASCII data.
+ </p></div><div class="sect2" id="MULTIBYTE-CONVERSIONS-SUPPORTED"><div class="titlepage"><div><div><h3 class="title">24.3.4. Available Character Set Conversions</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> allows conversion between any
+ two character sets for which a conversion function is listed in the
+ <a class="link" href="catalog-pg-conversion.html" title="53.14. pg_conversion"><code class="structname">pg_conversion</code></a>
+ system catalog. <span class="productname">PostgreSQL</span> comes with
+ some predefined conversions, as summarized in
+ <a class="xref" href="multibyte.html#MULTIBYTE-TRANSLATION-TABLE" title="Table 24.2. Built-in Client/Server Character Set Conversions">Table 24.2</a> and shown in more
+ detail in <a class="xref" href="multibyte.html#BUILTIN-CONVERSIONS-TABLE" title="Table 24.3. All Built-in Character Set Conversions">Table 24.3</a>. You can
+ create a new conversion using the SQL command
+ <a class="xref" href="sql-createconversion.html" title="CREATE CONVERSION"><span class="refentrytitle">CREATE CONVERSION</span></a>. (To be used for automatic
+ client/server conversions, a conversion must be marked
+ as <span class="quote">“<span class="quote">default</span>”</span> for its character set pair.)
+ </p><div class="table" id="MULTIBYTE-TRANSLATION-TABLE"><p class="title"><strong>Table 24.2. Built-in Client/Server Character Set Conversions</strong></p><div class="table-contents"><table class="table" summary="Built-in Client/Server Character Set Conversions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Server Character Set</th><th>Available Client Character Sets</th></tr></thead><tbody><tr><td><code class="literal">BIG5</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">EUC_CN</code></td><td><span class="emphasis"><em>EUC_CN</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">EUC_JP</code></td><td><span class="emphasis"><em>EUC_JP</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">SJIS</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">EUC_JIS_2004</code></td><td><span class="emphasis"><em>EUC_JIS_2004</em></span>,
+ <code class="literal">SHIFT_JIS_2004</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">EUC_KR</code></td><td><span class="emphasis"><em>EUC_KR</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">EUC_TW</code></td><td><span class="emphasis"><em>EUC_TW</em></span>,
+ <code class="literal">BIG5</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">GB18030</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">GBK</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">ISO_8859_5</code></td><td><span class="emphasis"><em>ISO_8859_5</em></span>,
+ <code class="literal">KOI8R</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>,
+ <code class="literal">WIN866</code>,
+ <code class="literal">WIN1251</code>
+ </td></tr><tr><td><code class="literal">ISO_8859_6</code></td><td><span class="emphasis"><em>ISO_8859_6</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">ISO_8859_7</code></td><td><span class="emphasis"><em>ISO_8859_7</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">ISO_8859_8</code></td><td><span class="emphasis"><em>ISO_8859_8</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">JOHAB</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">KOI8R</code></td><td><span class="emphasis"><em>KOI8R</em></span>,
+ <code class="literal">ISO_8859_5</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>,
+ <code class="literal">WIN866</code>,
+ <code class="literal">WIN1251</code>
+ </td></tr><tr><td><code class="literal">KOI8U</code></td><td><span class="emphasis"><em>KOI8U</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN1</code></td><td><span class="emphasis"><em>LATIN1</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN2</code></td><td><span class="emphasis"><em>LATIN2</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>,
+ <code class="literal">WIN1250</code>
+ </td></tr><tr><td><code class="literal">LATIN3</code></td><td><span class="emphasis"><em>LATIN3</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN4</code></td><td><span class="emphasis"><em>LATIN4</em></span>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN5</code></td><td><span class="emphasis"><em>LATIN5</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN6</code></td><td><span class="emphasis"><em>LATIN6</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN7</code></td><td><span class="emphasis"><em>LATIN7</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN8</code></td><td><span class="emphasis"><em>LATIN8</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN9</code></td><td><span class="emphasis"><em>LATIN9</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">LATIN10</code></td><td><span class="emphasis"><em>LATIN10</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">MULE_INTERNAL</code></td><td><span class="emphasis"><em>MULE_INTERNAL</em></span>,
+ <code class="literal">BIG5</code>,
+ <code class="literal">EUC_CN</code>,
+ <code class="literal">EUC_JP</code>,
+ <code class="literal">EUC_KR</code>,
+ <code class="literal">EUC_TW</code>,
+ <code class="literal">ISO_8859_5</code>,
+ <code class="literal">KOI8R</code>,
+ <code class="literal">LATIN1</code> to <code class="literal">LATIN4</code>,
+ <code class="literal">SJIS</code>,
+ <code class="literal">WIN866</code>,
+ <code class="literal">WIN1250</code>,
+ <code class="literal">WIN1251</code>
+ </td></tr><tr><td><code class="literal">SJIS</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">SHIFT_JIS_2004</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">SQL_ASCII</code></td><td><span class="emphasis"><em>any (no conversion will be performed)</em></span>
+ </td></tr><tr><td><code class="literal">UHC</code></td><td><span class="emphasis"><em>not supported as a server encoding</em></span>
+ </td></tr><tr><td><code class="literal">UTF8</code></td><td><span class="emphasis"><em>all supported encodings</em></span>
+ </td></tr><tr><td><code class="literal">WIN866</code></td><td><span class="emphasis"><em>WIN866</em></span>,
+ <code class="literal">ISO_8859_5</code>,
+ <code class="literal">KOI8R</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>,
+ <code class="literal">WIN1251</code>
+ </td></tr><tr><td><code class="literal">WIN874</code></td><td><span class="emphasis"><em>WIN874</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1250</code></td><td><span class="emphasis"><em>WIN1250</em></span>,
+ <code class="literal">LATIN2</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1251</code></td><td><span class="emphasis"><em>WIN1251</em></span>,
+ <code class="literal">ISO_8859_5</code>,
+ <code class="literal">KOI8R</code>,
+ <code class="literal">MULE_INTERNAL</code>,
+ <code class="literal">UTF8</code>,
+ <code class="literal">WIN866</code>
+ </td></tr><tr><td><code class="literal">WIN1252</code></td><td><span class="emphasis"><em>WIN1252</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1253</code></td><td><span class="emphasis"><em>WIN1253</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1254</code></td><td><span class="emphasis"><em>WIN1254</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1255</code></td><td><span class="emphasis"><em>WIN1255</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1256</code></td><td><span class="emphasis"><em>WIN1256</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1257</code></td><td><span class="emphasis"><em>WIN1257</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr><tr><td><code class="literal">WIN1258</code></td><td><span class="emphasis"><em>WIN1258</em></span>,
+ <code class="literal">UTF8</code>
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="BUILTIN-CONVERSIONS-TABLE"><p class="title"><strong>Table 24.3. All Built-in Character Set Conversions</strong></p><div class="table-contents"><table class="table" summary="All Built-in Character Set Conversions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Conversion Name
+ <a href="#ftn.id-1.6.11.5.8.4.2.4.1.1.1" class="footnote"><sup class="footnote" id="id-1.6.11.5.8.4.2.4.1.1.1">[a]</sup></a>
+ </th><th>Source Encoding</th><th>Destination Encoding</th></tr></thead><tbody><tr><td><code class="literal">big5_to_euc_tw</code></td><td><code class="literal">BIG5</code></td><td><code class="literal">EUC_TW</code></td></tr><tr><td><code class="literal">big5_to_mic</code></td><td><code class="literal">BIG5</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">big5_to_utf8</code></td><td><code class="literal">BIG5</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">euc_cn_to_mic</code></td><td><code class="literal">EUC_CN</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">euc_cn_to_utf8</code></td><td><code class="literal">EUC_CN</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">euc_jp_to_mic</code></td><td><code class="literal">EUC_JP</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">euc_jp_to_sjis</code></td><td><code class="literal">EUC_JP</code></td><td><code class="literal">SJIS</code></td></tr><tr><td><code class="literal">euc_jp_to_utf8</code></td><td><code class="literal">EUC_JP</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">euc_kr_to_mic</code></td><td><code class="literal">EUC_KR</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">euc_kr_to_utf8</code></td><td><code class="literal">EUC_KR</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">euc_tw_to_big5</code></td><td><code class="literal">EUC_TW</code></td><td><code class="literal">BIG5</code></td></tr><tr><td><code class="literal">euc_tw_to_mic</code></td><td><code class="literal">EUC_TW</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">euc_tw_to_utf8</code></td><td><code class="literal">EUC_TW</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">gb18030_to_utf8</code></td><td><code class="literal">GB18030</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">gbk_to_utf8</code></td><td><code class="literal">GBK</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_10_to_utf8</code></td><td><code class="literal">LATIN6</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_13_to_utf8</code></td><td><code class="literal">LATIN7</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_14_to_utf8</code></td><td><code class="literal">LATIN8</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_15_to_utf8</code></td><td><code class="literal">LATIN9</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_16_to_utf8</code></td><td><code class="literal">LATIN10</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_1_to_mic</code></td><td><code class="literal">LATIN1</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">iso_8859_1_to_utf8</code></td><td><code class="literal">LATIN1</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_2_to_mic</code></td><td><code class="literal">LATIN2</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">iso_8859_2_to_utf8</code></td><td><code class="literal">LATIN2</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_2_to_windows_1250</code></td><td><code class="literal">LATIN2</code></td><td><code class="literal">WIN1250</code></td></tr><tr><td><code class="literal">iso_8859_3_to_mic</code></td><td><code class="literal">LATIN3</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">iso_8859_3_to_utf8</code></td><td><code class="literal">LATIN3</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_4_to_mic</code></td><td><code class="literal">LATIN4</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">iso_8859_4_to_utf8</code></td><td><code class="literal">LATIN4</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_5_to_koi8_r</code></td><td><code class="literal">ISO_8859_5</code></td><td><code class="literal">KOI8R</code></td></tr><tr><td><code class="literal">iso_8859_5_to_mic</code></td><td><code class="literal">ISO_8859_5</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">iso_8859_5_to_utf8</code></td><td><code class="literal">ISO_8859_5</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_5_to_windows_1251</code></td><td><code class="literal">ISO_8859_5</code></td><td><code class="literal">WIN1251</code></td></tr><tr><td><code class="literal">iso_8859_5_to_windows_866</code></td><td><code class="literal">ISO_8859_5</code></td><td><code class="literal">WIN866</code></td></tr><tr><td><code class="literal">iso_8859_6_to_utf8</code></td><td><code class="literal">ISO_8859_6</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_7_to_utf8</code></td><td><code class="literal">ISO_8859_7</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_8_to_utf8</code></td><td><code class="literal">ISO_8859_8</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">iso_8859_9_to_utf8</code></td><td><code class="literal">LATIN5</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">johab_to_utf8</code></td><td><code class="literal">JOHAB</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">koi8_r_to_iso_8859_5</code></td><td><code class="literal">KOI8R</code></td><td><code class="literal">ISO_8859_5</code></td></tr><tr><td><code class="literal">koi8_r_to_mic</code></td><td><code class="literal">KOI8R</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">koi8_r_to_utf8</code></td><td><code class="literal">KOI8R</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">koi8_r_to_windows_1251</code></td><td><code class="literal">KOI8R</code></td><td><code class="literal">WIN1251</code></td></tr><tr><td><code class="literal">koi8_r_to_windows_866</code></td><td><code class="literal">KOI8R</code></td><td><code class="literal">WIN866</code></td></tr><tr><td><code class="literal">koi8_u_to_utf8</code></td><td><code class="literal">KOI8U</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">mic_to_big5</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">BIG5</code></td></tr><tr><td><code class="literal">mic_to_euc_cn</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">EUC_CN</code></td></tr><tr><td><code class="literal">mic_to_euc_jp</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td><code class="literal">mic_to_euc_kr</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">EUC_KR</code></td></tr><tr><td><code class="literal">mic_to_euc_tw</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">EUC_TW</code></td></tr><tr><td><code class="literal">mic_to_iso_8859_1</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">LATIN1</code></td></tr><tr><td><code class="literal">mic_to_iso_8859_2</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">LATIN2</code></td></tr><tr><td><code class="literal">mic_to_iso_8859_3</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">LATIN3</code></td></tr><tr><td><code class="literal">mic_to_iso_8859_4</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">LATIN4</code></td></tr><tr><td><code class="literal">mic_to_iso_8859_5</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">ISO_8859_5</code></td></tr><tr><td><code class="literal">mic_to_koi8_r</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">KOI8R</code></td></tr><tr><td><code class="literal">mic_to_sjis</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">SJIS</code></td></tr><tr><td><code class="literal">mic_to_windows_1250</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">WIN1250</code></td></tr><tr><td><code class="literal">mic_to_windows_1251</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">WIN1251</code></td></tr><tr><td><code class="literal">mic_to_windows_866</code></td><td><code class="literal">MULE_INTERNAL</code></td><td><code class="literal">WIN866</code></td></tr><tr><td><code class="literal">sjis_to_euc_jp</code></td><td><code class="literal">SJIS</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td><code class="literal">sjis_to_mic</code></td><td><code class="literal">SJIS</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">sjis_to_utf8</code></td><td><code class="literal">SJIS</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_1258_to_utf8</code></td><td><code class="literal">WIN1258</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">uhc_to_utf8</code></td><td><code class="literal">UHC</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">utf8_to_big5</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">BIG5</code></td></tr><tr><td><code class="literal">utf8_to_euc_cn</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">EUC_CN</code></td></tr><tr><td><code class="literal">utf8_to_euc_jp</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td><code class="literal">utf8_to_euc_kr</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">EUC_KR</code></td></tr><tr><td><code class="literal">utf8_to_euc_tw</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">EUC_TW</code></td></tr><tr><td><code class="literal">utf8_to_gb18030</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">GB18030</code></td></tr><tr><td><code class="literal">utf8_to_gbk</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">GBK</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_1</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN1</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_10</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN6</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_13</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN7</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_14</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN8</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_15</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN9</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_16</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN10</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_2</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN2</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_3</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN3</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_4</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN4</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_5</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">ISO_8859_5</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_6</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">ISO_8859_6</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_7</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">ISO_8859_7</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_8</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">ISO_8859_8</code></td></tr><tr><td><code class="literal">utf8_to_iso_8859_9</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">LATIN5</code></td></tr><tr><td><code class="literal">utf8_to_johab</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">JOHAB</code></td></tr><tr><td><code class="literal">utf8_to_koi8_r</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">KOI8R</code></td></tr><tr><td><code class="literal">utf8_to_koi8_u</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">KOI8U</code></td></tr><tr><td><code class="literal">utf8_to_sjis</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">SJIS</code></td></tr><tr><td><code class="literal">utf8_to_windows_1258</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1258</code></td></tr><tr><td><code class="literal">utf8_to_uhc</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">UHC</code></td></tr><tr><td><code class="literal">utf8_to_windows_1250</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1250</code></td></tr><tr><td><code class="literal">utf8_to_windows_1251</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1251</code></td></tr><tr><td><code class="literal">utf8_to_windows_1252</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1252</code></td></tr><tr><td><code class="literal">utf8_to_windows_1253</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1253</code></td></tr><tr><td><code class="literal">utf8_to_windows_1254</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1254</code></td></tr><tr><td><code class="literal">utf8_to_windows_1255</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1255</code></td></tr><tr><td><code class="literal">utf8_to_windows_1256</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1256</code></td></tr><tr><td><code class="literal">utf8_to_windows_1257</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN1257</code></td></tr><tr><td><code class="literal">utf8_to_windows_866</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN866</code></td></tr><tr><td><code class="literal">utf8_to_windows_874</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">WIN874</code></td></tr><tr><td><code class="literal">windows_1250_to_iso_8859_2</code></td><td><code class="literal">WIN1250</code></td><td><code class="literal">LATIN2</code></td></tr><tr><td><code class="literal">windows_1250_to_mic</code></td><td><code class="literal">WIN1250</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">windows_1250_to_utf8</code></td><td><code class="literal">WIN1250</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_1251_to_iso_8859_5</code></td><td><code class="literal">WIN1251</code></td><td><code class="literal">ISO_8859_5</code></td></tr><tr><td><code class="literal">windows_1251_to_koi8_r</code></td><td><code class="literal">WIN1251</code></td><td><code class="literal">KOI8R</code></td></tr><tr><td><code class="literal">windows_1251_to_mic</code></td><td><code class="literal">WIN1251</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">windows_1251_to_utf8</code></td><td><code class="literal">WIN1251</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_1251_to_windows_866</code></td><td><code class="literal">WIN1251</code></td><td><code class="literal">WIN866</code></td></tr><tr><td><code class="literal">windows_1252_to_utf8</code></td><td><code class="literal">WIN1252</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_1256_to_utf8</code></td><td><code class="literal">WIN1256</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_866_to_iso_8859_5</code></td><td><code class="literal">WIN866</code></td><td><code class="literal">ISO_8859_5</code></td></tr><tr><td><code class="literal">windows_866_to_koi8_r</code></td><td><code class="literal">WIN866</code></td><td><code class="literal">KOI8R</code></td></tr><tr><td><code class="literal">windows_866_to_mic</code></td><td><code class="literal">WIN866</code></td><td><code class="literal">MULE_INTERNAL</code></td></tr><tr><td><code class="literal">windows_866_to_utf8</code></td><td><code class="literal">WIN866</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">windows_866_to_windows_1251</code></td><td><code class="literal">WIN866</code></td><td><code class="literal">WIN</code></td></tr><tr><td><code class="literal">windows_874_to_utf8</code></td><td><code class="literal">WIN874</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">euc_jis_2004_to_utf8</code></td><td><code class="literal">EUC_JIS_2004</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">utf8_to_euc_jis_2004</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">EUC_JIS_2004</code></td></tr><tr><td><code class="literal">shift_jis_2004_to_utf8</code></td><td><code class="literal">SHIFT_JIS_2004</code></td><td><code class="literal">UTF8</code></td></tr><tr><td><code class="literal">utf8_to_shift_jis_2004</code></td><td><code class="literal">UTF8</code></td><td><code class="literal">SHIFT_JIS_2004</code></td></tr><tr><td><code class="literal">euc_jis_2004_to_shift_jis_2004</code></td><td><code class="literal">EUC_JIS_2004</code></td><td><code class="literal">SHIFT_JIS_2004</code></td></tr><tr><td><code class="literal">shift_jis_2004_to_euc_jis_2004</code></td><td><code class="literal">SHIFT_JIS_2004</code></td><td><code class="literal">EUC_JIS_2004</code></td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div id="ftn.id-1.6.11.5.8.4.2.4.1.1.1" class="footnote"><p><a href="#id-1.6.11.5.8.4.2.4.1.1.1" class="para"><sup class="para">[a] </sup></a>
+ The conversion names follow a standard naming scheme: The
+ official name of the source encoding with all
+ non-alphanumeric characters replaced by underscores, followed
+ by <code class="literal">_to_</code>, followed by the similarly processed
+ destination encoding name. Therefore, these names sometimes
+ deviate from the customary encoding names shown in
+ <a class="xref" href="multibyte.html#CHARSET-TABLE" title="Table 24.1. PostgreSQL Character Sets">Table 24.1</a>.
+ </p></div></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.6.11.5.9"><div class="titlepage"><div><div><h3 class="title">24.3.5. Further Reading</h3></div></div></div><p>
+ These are good sources to start learning about various kinds of encoding
+ systems.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="citetitle">CJKV Information Processing: Chinese, Japanese, Korean &amp; Vietnamese Computing</em></span></dt><dd><p>
+ Contains detailed explanations of <code class="literal">EUC_JP</code>,
+ <code class="literal">EUC_CN</code>, <code class="literal">EUC_KR</code>,
+ <code class="literal">EUC_TW</code>.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://www.unicode.org/" target="_top">https://www.unicode.org/</a></span></dt><dd><p>
+ The web site of the Unicode Consortium.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://tools.ietf.org/html/rfc3629" target="_top">RFC 3629</a></span></dt><dd><p>
+ <acronym class="acronym">UTF</acronym>-8 (8-bit UCS/Unicode Transformation
+ Format) is defined here.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="collation.html" title="24.2. Collation Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="charset.html" title="Chapter 24. Localization">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">24.2. Collation Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 25. Routine Database Maintenance Tasks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/multivariate-statistics-examples.html b/doc/src/sgml/html/multivariate-statistics-examples.html
new file mode 100644
index 0000000..62c0ba3
--- /dev/null
+++ b/doc/src/sgml/html/multivariate-statistics-examples.html
@@ -0,0 +1,210 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>75.2. Multivariate Statistics Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="row-estimation-examples.html" title="75.1. Row Estimation Examples" /><link rel="next" href="planner-stats-security.html" title="75.3. Planner Statistics and Security" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">75.2. Multivariate Statistics Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="row-estimation-examples.html" title="75.1. Row Estimation Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><th width="60%" align="center">Chapter 75. How the Planner Uses Statistics</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="planner-stats-security.html" title="75.3. Planner Statistics and Security">Next</a></td></tr></table><hr /></div><div class="sect1" id="MULTIVARIATE-STATISTICS-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">75.2. Multivariate Statistics Examples</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="multivariate-statistics-examples.html#FUNCTIONAL-DEPENDENCIES">75.2.1. Functional Dependencies</a></span></dt><dt><span class="sect2"><a href="multivariate-statistics-examples.html#MULTIVARIATE-NDISTINCT-COUNTS">75.2.2. Multivariate N-Distinct Counts</a></span></dt><dt><span class="sect2"><a href="multivariate-statistics-examples.html#MCV-LISTS">75.2.3. MCV Lists</a></span></dt></dl></div><a id="id-1.10.26.5.2" class="indexterm"></a><div class="sect2" id="FUNCTIONAL-DEPENDENCIES"><div class="titlepage"><div><div><h3 class="title">75.2.1. Functional Dependencies</h3></div></div></div><p>
+ Multivariate correlation can be demonstrated with a very simple data set
+ — a table with two columns, both containing the same values:
+
+</p><pre class="programlisting">
+CREATE TABLE t (a INT, b INT);
+INSERT INTO t SELECT i % 100, i % 100 FROM generate_series(1, 10000) s(i);
+ANALYZE t;
+</pre><p>
+
+ As explained in <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>, the planner can determine
+ cardinality of <code class="structname">t</code> using the number of pages and
+ rows obtained from <code class="structname">pg_class</code>:
+
+</p><pre class="programlisting">
+SELECT relpages, reltuples FROM pg_class WHERE relname = 't';
+
+ relpages | reltuples
+----------+-----------
+ 45 | 10000
+</pre><p>
+
+ The data distribution is very simple; there are only 100 distinct values
+ in each column, uniformly distributed.
+ </p><p>
+ The following example shows the result of estimating a <code class="literal">WHERE</code>
+ condition on the <code class="structfield">a</code> column:
+
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1;
+ QUERY PLAN
+-------------------------------------------------------------------​------------
+ Seq Scan on t (cost=0.00..170.00 rows=100 width=8) (actual rows=100 loops=1)
+ Filter: (a = 1)
+ Rows Removed by Filter: 9900
+</pre><p>
+
+ The planner examines the condition and determines the selectivity
+ of this clause to be 1%. By comparing this estimate and the actual
+ number of rows, we see that the estimate is very accurate
+ (in fact exact, as the table is very small). Changing the
+ <code class="literal">WHERE</code> condition to use the <code class="structfield">b</code> column, an
+ identical plan is generated. But observe what happens if we apply the same
+ condition on both columns, combining them with <code class="literal">AND</code>:
+
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
+ QUERY PLAN
+-------------------------------------------------------------------​----------
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=100 loops=1)
+ Filter: ((a = 1) AND (b = 1))
+ Rows Removed by Filter: 9900
+</pre><p>
+
+ The planner estimates the selectivity for each condition individually,
+ arriving at the same 1% estimates as above. Then it assumes that the
+ conditions are independent, and so it multiplies their selectivities,
+ producing a final selectivity estimate of just 0.01%.
+ This is a significant underestimate, as the actual number of rows
+ matching the conditions (100) is two orders of magnitude higher.
+ </p><p>
+ This problem can be fixed by creating a statistics object that
+ directs <code class="command">ANALYZE</code> to calculate functional-dependency
+ multivariate statistics on the two columns:
+
+</p><pre class="programlisting">
+CREATE STATISTICS stts (dependencies) ON a, b FROM t;
+ANALYZE t;
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
+ QUERY PLAN
+-------------------------------------------------------------------​------------
+ Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100 loops=1)
+ Filter: ((a = 1) AND (b = 1))
+ Rows Removed by Filter: 9900
+</pre><p>
+ </p></div><div class="sect2" id="MULTIVARIATE-NDISTINCT-COUNTS"><div class="titlepage"><div><div><h3 class="title">75.2.2. Multivariate N-Distinct Counts</h3></div></div></div><p>
+ A similar problem occurs with estimation of the cardinality of sets of
+ multiple columns, such as the number of groups that would be generated by
+ a <code class="command">GROUP BY</code> clause. When <code class="command">GROUP BY</code>
+ lists a single column, the n-distinct estimate (which is visible as the
+ estimated number of rows returned by the HashAggregate node) is very
+ accurate:
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a;
+ QUERY PLAN
+-------------------------------------------------------------------​----------------------
+ HashAggregate (cost=195.00..196.00 rows=100 width=12) (actual rows=100 loops=1)
+ Group Key: a
+ -&gt; Seq Scan on t (cost=0.00..145.00 rows=10000 width=4) (actual rows=10000 loops=1)
+</pre><p>
+ But without multivariate statistics, the estimate for the number of
+ groups in a query with two columns in <code class="command">GROUP BY</code>, as
+ in the following example, is off by an order of magnitude:
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------------
+ HashAggregate (cost=220.00..230.00 rows=1000 width=16) (actual rows=100 loops=1)
+ Group Key: a, b
+ -&gt; Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1)
+</pre><p>
+ By redefining the statistics object to include n-distinct counts for the
+ two columns, the estimate is much improved:
+</p><pre class="programlisting">
+DROP STATISTICS stts;
+CREATE STATISTICS stts (dependencies, ndistinct) ON a, b FROM t;
+ANALYZE t;
+EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------------
+ HashAggregate (cost=220.00..221.00 rows=100 width=16) (actual rows=100 loops=1)
+ Group Key: a, b
+ -&gt; Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1)
+</pre><p>
+ </p></div><div class="sect2" id="MCV-LISTS"><div class="titlepage"><div><div><h3 class="title">75.2.3. MCV Lists</h3></div></div></div><p>
+ As explained in <a class="xref" href="multivariate-statistics-examples.html#FUNCTIONAL-DEPENDENCIES" title="75.2.1. Functional Dependencies">Section 75.2.1</a>, functional
+ dependencies are very cheap and efficient type of statistics, but their
+ main limitation is their global nature (only tracking dependencies at
+ the column level, not between individual column values).
+ </p><p>
+ This section introduces multivariate variant of <acronym class="acronym">MCV</acronym>
+ (most-common values) lists, a straightforward extension of the per-column
+ statistics described in <a class="xref" href="row-estimation-examples.html" title="75.1. Row Estimation Examples">Section 75.1</a>. These
+ statistics address the limitation by storing individual values, but it is
+ naturally more expensive, both in terms of building the statistics in
+ <code class="command">ANALYZE</code>, storage and planning time.
+ </p><p>
+ Let's look at the query from <a class="xref" href="multivariate-statistics-examples.html#FUNCTIONAL-DEPENDENCIES" title="75.2.1. Functional Dependencies">Section 75.2.1</a>
+ again, but this time with a <acronym class="acronym">MCV</acronym> list created on the
+ same set of columns (be sure to drop the functional dependencies, to
+ make sure the planner uses the newly created statistics).
+
+</p><pre class="programlisting">
+DROP STATISTICS stts;
+CREATE STATISTICS stts2 (mcv) ON a, b FROM t;
+ANALYZE t;
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
+ QUERY PLAN
+-------------------------------------------------------------------​------------
+ Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100 loops=1)
+ Filter: ((a = 1) AND (b = 1))
+ Rows Removed by Filter: 9900
+</pre><p>
+
+ The estimate is as accurate as with the functional dependencies, mostly
+ thanks to the table being fairly small and having a simple distribution
+ with a low number of distinct values. Before looking at the second query,
+ which was not handled by functional dependencies particularly well,
+ let's inspect the <acronym class="acronym">MCV</acronym> list a bit.
+ </p><p>
+ Inspecting the <acronym class="acronym">MCV</acronym> list is possible using
+ <code class="function">pg_mcv_list_items</code> set-returning function.
+
+</p><pre class="programlisting">
+SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
+ pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts2';
+ index | values | nulls | frequency | base_frequency
+-------+----------+-------+-----------+----------------
+ 0 | {0, 0} | {f,f} | 0.01 | 0.0001
+ 1 | {1, 1} | {f,f} | 0.01 | 0.0001
+ ...
+ 49 | {49, 49} | {f,f} | 0.01 | 0.0001
+ 50 | {50, 50} | {f,f} | 0.01 | 0.0001
+ ...
+ 97 | {97, 97} | {f,f} | 0.01 | 0.0001
+ 98 | {98, 98} | {f,f} | 0.01 | 0.0001
+ 99 | {99, 99} | {f,f} | 0.01 | 0.0001
+(100 rows)
+</pre><p>
+
+ This confirms there are 100 distinct combinations in the two columns, and
+ all of them are about equally likely (1% frequency for each one). The
+ base frequency is the frequency computed from per-column statistics, as if
+ there were no multi-column statistics. Had there been any null values in
+ either of the columns, this would be identified in the
+ <code class="structfield">nulls</code> column.
+ </p><p>
+ When estimating the selectivity, the planner applies all the conditions
+ on items in the <acronym class="acronym">MCV</acronym> list, and then sums the frequencies
+ of the matching ones. See <code class="function">mcv_clauselist_selectivity</code>
+ in <code class="filename">src/backend/statistics/mcv.c</code> for details.
+ </p><p>
+ Compared to functional dependencies, <acronym class="acronym">MCV</acronym> lists have two
+ major advantages. Firstly, the list stores actual values, making it possible
+ to decide which combinations are compatible.
+
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 10;
+ QUERY PLAN
+-------------------------------------------------------------------​--------
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0 loops=1)
+ Filter: ((a = 1) AND (b = 10))
+ Rows Removed by Filter: 10000
+</pre><p>
+
+ Secondly, <acronym class="acronym">MCV</acronym> lists handle a wider range of clause types,
+ not just equality clauses like functional dependencies. For example,
+ consider the following range query for the same table:
+
+</p><pre class="programlisting">
+EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a &lt;= 49 AND b &gt; 49;
+ QUERY PLAN
+-------------------------------------------------------------------​--------
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0 loops=1)
+ Filter: ((a &lt;= 49) AND (b &gt; 49))
+ Rows Removed by Filter: 10000
+</pre><p>
+
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="row-estimation-examples.html" title="75.1. Row Estimation Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="planner-stats-security.html" title="75.3. Planner Statistics and Security">Next</a></td></tr><tr><td width="40%" align="left" valign="top">75.1. Row Estimation Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 75.3. Planner Statistics and Security</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/mvcc-caveats.html b/doc/src/sgml/html/mvcc-caveats.html
new file mode 100644
index 0000000..086d6a7
--- /dev/null
+++ b/doc/src/sgml/html/mvcc-caveats.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.6. Caveats</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling" /><link rel="next" href="locking-indexes.html" title="13.7. Locking and Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.6. Caveats</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="locking-indexes.html" title="13.7. Locking and Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="MVCC-CAVEATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.6. Caveats</h2></div></div></div><p>
+ Some DDL commands, currently only <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a> and the
+ table-rewriting forms of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>, are not
+ MVCC-safe. This means that after the truncation or rewrite commits, the
+ table will appear empty to concurrent transactions, if they are using a
+ snapshot taken before the DDL command committed. This will only be an
+ issue for a transaction that did not access the table in question
+ before the DDL command started — any transaction that has done so
+ would hold at least an <code class="literal">ACCESS SHARE</code> table lock,
+ which would block the DDL command until that transaction completes.
+ So these commands will not cause any apparent inconsistency in the
+ table contents for successive queries on the target table, but they
+ could cause visible inconsistency between the contents of the target
+ table and other tables in the database.
+ </p><p>
+ Support for the Serializable transaction isolation level has not yet
+ been added to hot standby replication targets (described in
+ <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a>). The strictest isolation level currently
+ supported in hot standby mode is Repeatable Read. While performing all
+ permanent database writes within Serializable transactions on the
+ primary will ensure that all standbys will eventually reach a consistent
+ state, a Repeatable Read transaction run on the standby can sometimes
+ see a transient state that is inconsistent with any serial execution
+ of the transactions on the primary.
+ </p><p>
+ Internal access to the system catalogs is not done using the isolation
+ level of the current transaction. This means that newly created database
+ objects such as tables are visible to concurrent Repeatable Read and
+ Serializable transactions, even though the rows they contain are not. In
+ contrast, queries that explicitly examine the system catalogs don't see
+ rows representing concurrently created database objects, in the higher
+ isolation levels.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mvcc-serialization-failure-handling.html" title="13.5. Serialization Failure Handling">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="locking-indexes.html" title="13.7. Locking and Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.5. Serialization Failure Handling </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.7. Locking and Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/mvcc-intro.html b/doc/src/sgml/html/mvcc-intro.html
new file mode 100644
index 0000000..b8e498c
--- /dev/null
+++ b/doc/src/sgml/html/mvcc-intro.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="mvcc.html" title="Chapter 13. Concurrency Control" /><link rel="next" href="transaction-iso.html" title="13.2. Transaction Isolation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="mvcc.html" title="Chapter 13. Concurrency Control">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="transaction-iso.html" title="13.2. Transaction Isolation">Next</a></td></tr></table><hr /></div><div class="sect1" id="MVCC-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.1. Introduction</h2></div></div></div><a id="id-1.5.12.4.2" class="indexterm"></a><a id="id-1.5.12.4.3" class="indexterm"></a><a id="id-1.5.12.4.4" class="indexterm"></a><a id="id-1.5.12.4.5" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a rich set of tools
+ for developers to manage concurrent access to data. Internally,
+ data consistency is maintained by using a multiversion
+ model (Multiversion Concurrency Control, <acronym class="acronym">MVCC</acronym>).
+ This means that each SQL statement sees
+ a snapshot of data (a <em class="firstterm">database version</em>)
+ as it was some
+ time ago, regardless of the current state of the underlying data.
+ This prevents statements from viewing inconsistent data produced
+ by concurrent transactions performing updates on the same
+ data rows, providing <em class="firstterm">transaction isolation</em>
+ for each database session. <acronym class="acronym">MVCC</acronym>, by eschewing
+ the locking methodologies of traditional database systems,
+ minimizes lock contention in order to allow for reasonable
+ performance in multiuser environments.
+ </p><p>
+ The main advantage of using the <acronym class="acronym">MVCC</acronym> model of
+ concurrency control rather than locking is that in
+ <acronym class="acronym">MVCC</acronym> locks acquired for querying (reading) data
+ do not conflict with locks acquired for writing data, and so
+ reading never blocks writing and writing never blocks reading.
+ <span class="productname">PostgreSQL</span> maintains this guarantee
+ even when providing the strictest level of transaction
+ isolation through the use of an innovative <em class="firstterm">Serializable
+ Snapshot Isolation</em> (<acronym class="acronym">SSI</acronym>) level.
+ </p><p>
+ Table- and row-level locking facilities are also available in
+ <span class="productname">PostgreSQL</span> for applications which don't
+ generally need full transaction isolation and prefer to explicitly
+ manage particular points of conflict. However, proper
+ use of <acronym class="acronym">MVCC</acronym> will generally provide better
+ performance than locks. In addition, application-defined advisory
+ locks provide a mechanism for acquiring locks that are not tied
+ to a single transaction.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mvcc.html" title="Chapter 13. Concurrency Control">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="transaction-iso.html" title="13.2. Transaction Isolation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. Concurrency Control </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.2. Transaction Isolation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/mvcc-serialization-failure-handling.html b/doc/src/sgml/html/mvcc-serialization-failure-handling.html
new file mode 100644
index 0000000..bca37b2
--- /dev/null
+++ b/doc/src/sgml/html/mvcc-serialization-failure-handling.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.5. Serialization Failure Handling</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level" /><link rel="next" href="mvcc-caveats.html" title="13.6. Caveats" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.5. Serialization Failure Handling</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="mvcc-caveats.html" title="13.6. Caveats">Next</a></td></tr></table><hr /></div><div class="sect1" id="MVCC-SERIALIZATION-FAILURE-HANDLING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.5. Serialization Failure Handling</h2></div></div></div><a id="id-1.5.12.8.2" class="indexterm"></a><a id="id-1.5.12.8.3" class="indexterm"></a><p>
+ Both Repeatable Read and Serializable isolation levels can produce
+ errors that are designed to prevent serialization anomalies. As
+ previously stated, applications using these levels must be prepared to
+ retry transactions that fail due to serialization errors. Such an
+ error's message text will vary according to the precise circumstances,
+ but it will always have the SQLSTATE code <code class="literal">40001</code>
+ (<code class="literal">serialization_failure</code>).
+ </p><p>
+ It may also be advisable to retry deadlock failures.
+ These have the SQLSTATE code <code class="literal">40P01</code>
+ (<code class="literal">deadlock_detected</code>).
+ </p><p>
+ In some cases it is also appropriate to retry unique-key failures,
+ which have SQLSTATE code <code class="literal">23505</code>
+ (<code class="literal">unique_violation</code>), and exclusion constraint
+ failures, which have SQLSTATE code <code class="literal">23P01</code>
+ (<code class="literal">exclusion_violation</code>). For example, if the
+ application selects a new value for a primary key column after
+ inspecting the currently stored keys, it could get a unique-key
+ failure because another application instance selected the same new key
+ concurrently. This is effectively a serialization failure, but the
+ server will not detect it as such because it cannot <span class="quote">“<span class="quote">see</span>”</span>
+ the connection between the inserted value and the previous reads.
+ There are also some corner cases in which the server will issue a
+ unique-key or exclusion constraint error even though in principle it
+ has enough information to determine that a serialization problem
+ is the underlying cause. While it's recommendable to just
+ retry <code class="literal">serialization_failure</code> errors unconditionally,
+ more care is needed when retrying these other error codes, since they
+ might represent persistent error conditions rather than transient
+ failures.
+ </p><p>
+ It is important to retry the complete transaction, including all logic
+ that decides which SQL to issue and/or which values to use.
+ Therefore, <span class="productname">PostgreSQL</span> does not offer an
+ automatic retry facility, since it cannot do so with any guarantee of
+ correctness.
+ </p><p>
+ Transaction retry does not guarantee that the retried transaction will
+ complete; multiple retries may be needed. In cases with very high
+ contention, it is possible that completion of a transaction may take
+ many attempts. In cases involving a conflicting prepared transaction,
+ it may not be possible to make progress until the prepared transaction
+ commits or rolls back.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="applevel-consistency.html" title="13.4. Data Consistency Checks at the Application Level">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mvcc-caveats.html" title="13.6. Caveats">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.4. Data Consistency Checks at the Application Level </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.6. Caveats</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/mvcc.html b/doc/src/sgml/html/mvcc.html
new file mode 100644
index 0000000..2fa8478
--- /dev/null
+++ b/doc/src/sgml/html/mvcc.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 13. Concurrency Control</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-limitations.html" title="12.11. Limitations" /><link rel="next" href="mvcc-intro.html" title="13.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 13. Concurrency Control</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-limitations.html" title="12.11. Limitations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="mvcc-intro.html" title="13.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="MVCC"><div class="titlepage"><div><div><h2 class="title">Chapter 13. Concurrency Control</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="mvcc-intro.html">13.1. Introduction</a></span></dt><dt><span class="sect1"><a href="transaction-iso.html">13.2. Transaction Isolation</a></span></dt><dd><dl><dt><span class="sect2"><a href="transaction-iso.html#XACT-READ-COMMITTED">13.2.1. Read Committed Isolation Level</a></span></dt><dt><span class="sect2"><a href="transaction-iso.html#XACT-REPEATABLE-READ">13.2.2. Repeatable Read Isolation Level</a></span></dt><dt><span class="sect2"><a href="transaction-iso.html#XACT-SERIALIZABLE">13.2.3. Serializable Isolation Level</a></span></dt></dl></dd><dt><span class="sect1"><a href="explicit-locking.html">13.3. Explicit Locking</a></span></dt><dd><dl><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-TABLES">13.3.1. Table-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-ROWS">13.3.2. Row-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-PAGES">13.3.3. Page-Level Locks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#LOCKING-DEADLOCKS">13.3.4. Deadlocks</a></span></dt><dt><span class="sect2"><a href="explicit-locking.html#ADVISORY-LOCKS">13.3.5. Advisory Locks</a></span></dt></dl></dd><dt><span class="sect1"><a href="applevel-consistency.html">13.4. Data Consistency Checks at the Application Level</a></span></dt><dd><dl><dt><span class="sect2"><a href="applevel-consistency.html#SERIALIZABLE-CONSISTENCY">13.4.1. Enforcing Consistency with Serializable Transactions</a></span></dt><dt><span class="sect2"><a href="applevel-consistency.html#NON-SERIALIZABLE-CONSISTENCY">13.4.2. Enforcing Consistency with Explicit Blocking Locks</a></span></dt></dl></dd><dt><span class="sect1"><a href="mvcc-serialization-failure-handling.html">13.5. Serialization Failure Handling</a></span></dt><dt><span class="sect1"><a href="mvcc-caveats.html">13.6. Caveats</a></span></dt><dt><span class="sect1"><a href="locking-indexes.html">13.7. Locking and Indexes</a></span></dt></dl></div><a id="id-1.5.12.2" class="indexterm"></a><p>
+ This chapter describes the behavior of the
+ <span class="productname">PostgreSQL</span> database system when two or
+ more sessions try to access the same data at the same time. The
+ goals in that situation are to allow efficient access for all
+ sessions while maintaining strict data integrity. Every developer
+ of database applications should be familiar with the topics covered
+ in this chapter.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-limitations.html" title="12.11. Limitations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mvcc-intro.html" title="13.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.11. Limitations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/nls-programmer.html b/doc/src/sgml/html/nls-programmer.html
new file mode 100644
index 0000000..d64c217
--- /dev/null
+++ b/doc/src/sgml/html/nls-programmer.html
@@ -0,0 +1,154 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>57.2. For the Programmer</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="nls-translator.html" title="57.1. For the Translator" /><link rel="next" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">57.2. For the Programmer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-translator.html" title="57.1. For the Translator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><th width="60%" align="center">Chapter 57. Native Language Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Next</a></td></tr></table><hr /></div><div class="sect1" id="NLS-PROGRAMMER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">57.2. For the Programmer</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="nls-programmer.html#NLS-MECHANICS">57.2.1. Mechanics</a></span></dt><dt><span class="sect2"><a href="nls-programmer.html#NLS-GUIDELINES">57.2.2. Message-Writing Guidelines</a></span></dt></dl></div><div class="sect2" id="NLS-MECHANICS"><div class="titlepage"><div><div><h3 class="title">57.2.1. Mechanics</h3></div></div></div><p>
+ This section describes how to implement native language support in a
+ program or library that is part of the
+ <span class="productname">PostgreSQL</span> distribution.
+ Currently, it only applies to C programs.
+ </p><div class="procedure" id="id-1.10.8.3.2.3"><p class="title"><strong>Adding NLS Support to a Program</strong></p><ol class="procedure" type="1"><li class="step"><p>
+ Insert this code into the start-up sequence of the program:
+</p><pre class="programlisting">
+#ifdef ENABLE_NLS
+#include &lt;locale.h&gt;
+#endif
+
+...
+
+#ifdef ENABLE_NLS
+setlocale(LC_ALL, "");
+bindtextdomain("<em class="replaceable"><code>progname</code></em>", LOCALEDIR);
+textdomain("<em class="replaceable"><code>progname</code></em>");
+#endif
+</pre><p>
+ (The <em class="replaceable"><code>progname</code></em> can actually be chosen
+ freely.)
+ </p></li><li class="step"><p>
+ Wherever a message that is a candidate for translation is found,
+ a call to <code class="function">gettext()</code> needs to be inserted. E.g.:
+</p><pre class="programlisting">
+fprintf(stderr, "panic level %d\n", lvl);
+</pre><p>
+ would be changed to:
+</p><pre class="programlisting">
+fprintf(stderr, gettext("panic level %d\n"), lvl);
+</pre><p>
+ (<code class="symbol">gettext</code> is defined as a no-op if NLS support is
+ not configured.)
+ </p><p>
+ This tends to add a lot of clutter. One common shortcut is to use:
+</p><pre class="programlisting">
+#define _(x) gettext(x)
+</pre><p>
+ Another solution is feasible if the program does much of its
+ communication through one or a few functions, such as
+ <code class="function">ereport()</code> in the backend. Then you make this
+ function call <code class="function">gettext</code> internally on all
+ input strings.
+ </p></li><li class="step"><p>
+ Add a file <code class="filename">nls.mk</code> in the directory with the
+ program sources. This file will be read as a makefile. The
+ following variable assignments need to be made here:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">CATALOG_NAME</code></span></dt><dd><p>
+ The program name, as provided in the
+ <code class="function">textdomain()</code> call.
+ </p></dd><dt><span class="term"><code class="varname">AVAIL_LANGUAGES</code></span></dt><dd><p>
+ List of provided translations — initially empty.
+ </p></dd><dt><span class="term"><code class="varname">GETTEXT_FILES</code></span></dt><dd><p>
+ List of files that contain translatable strings, i.e., those
+ marked with <code class="function">gettext</code> or an alternative
+ solution. Eventually, this will include nearly all source
+ files of the program. If this list gets too long you can
+ make the first <span class="quote">“<span class="quote">file</span>”</span> be a <code class="literal">+</code>
+ and the second word be a file that contains one file name per
+ line.
+ </p></dd><dt><span class="term"><code class="varname">GETTEXT_TRIGGERS</code></span></dt><dd><p>
+ The tools that generate message catalogs for the translators
+ to work on need to know what function calls contain
+ translatable strings. By default, only
+ <code class="function">gettext()</code> calls are known. If you used
+ <code class="function">_</code> or other identifiers you need to list
+ them here. If the translatable string is not the first
+ argument, the item needs to be of the form
+ <code class="literal">func:2</code> (for the second argument).
+ If you have a function that supports pluralized messages,
+ the item should look like <code class="literal">func:1,2</code>
+ (identifying the singular and plural message arguments).
+ </p></dd></dl></div><p>
+ </p></li></ol></div><p>
+ The build system will automatically take care of building and
+ installing the message catalogs.
+ </p></div><div class="sect2" id="NLS-GUIDELINES"><div class="titlepage"><div><div><h3 class="title">57.2.2. Message-Writing Guidelines</h3></div></div></div><p>
+ Here are some guidelines for writing messages that are easily
+ translatable.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Do not construct sentences at run-time, like:
+</p><pre class="programlisting">
+printf("Files were %s.\n", flag ? "copied" : "removed");
+</pre><p>
+ The word order within the sentence might be different in other
+ languages. Also, even if you remember to call <code class="function">gettext()</code> on
+ each fragment, the fragments might not translate well separately. It's
+ better to duplicate a little code so that each message to be
+ translated is a coherent whole. Only numbers, file names, and
+ such-like run-time variables should be inserted at run time into
+ a message text.
+ </p></li><li class="listitem"><p>
+ For similar reasons, this won't work:
+</p><pre class="programlisting">
+printf("copied %d file%s", n, n!=1 ? "s" : "");
+</pre><p>
+ because it assumes how the plural is formed. If you figured you
+ could solve it like this:
+</p><pre class="programlisting">
+if (n==1)
+ printf("copied 1 file");
+else
+ printf("copied %d files", n):
+</pre><p>
+ then be disappointed. Some languages have more than two forms,
+ with some peculiar rules. It's often best to design the message
+ to avoid the issue altogether, for instance like this:
+</p><pre class="programlisting">
+printf("number of copied files: %d", n);
+</pre><p>
+ </p><p>
+ If you really want to construct a properly pluralized message,
+ there is support for this, but it's a bit awkward. When generating
+ a primary or detail error message in <code class="function">ereport()</code>, you can
+ write something like this:
+</p><pre class="programlisting">
+errmsg_plural("copied %d file",
+ "copied %d files",
+ n,
+ n)
+</pre><p>
+ The first argument is the format string appropriate for English
+ singular form, the second is the format string appropriate for
+ English plural form, and the third is the integer control value
+ that determines which plural form to use. Subsequent arguments
+ are formatted per the format string as usual. (Normally, the
+ pluralization control value will also be one of the values to be
+ formatted, so it has to be written twice.) In English it only
+ matters whether <em class="replaceable"><code>n</code></em> is 1 or not 1, but in other
+ languages there can be many different plural forms. The translator
+ sees the two English forms as a group and has the opportunity to
+ supply multiple substitute strings, with the appropriate one being
+ selected based on the run-time value of <em class="replaceable"><code>n</code></em>.
+ </p><p>
+ If you need to pluralize a message that isn't going directly to an
+ <code class="function">errmsg</code> or <code class="function">errdetail</code> report, you have to use
+ the underlying function <code class="function">ngettext</code>. See the gettext
+ documentation.
+ </p></li><li class="listitem"><p>
+ If you want to communicate something to the translator, such as
+ about how a message is intended to line up with other output,
+ precede the occurrence of the string with a comment that starts
+ with <code class="literal">translator</code>, e.g.:
+</p><pre class="programlisting">
+/* translator: This message is not what it seems to be. */
+</pre><p>
+ These comments are copied to the message catalog files so that
+ the translators can see them.
+ </p></li></ul></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls-translator.html" title="57.1. For the Translator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Next</a></td></tr><tr><td width="40%" align="left" valign="top">57.1. For the Translator </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 58. Writing a Procedural Language Handler</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/nls-translator.html b/doc/src/sgml/html/nls-translator.html
new file mode 100644
index 0000000..d3292bb
--- /dev/null
+++ b/doc/src/sgml/html/nls-translator.html
@@ -0,0 +1,218 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>57.1. For the Translator</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="nls.html" title="Chapter 57. Native Language Support" /><link rel="next" href="nls-programmer.html" title="57.2. For the Programmer" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">57.1. For the Translator</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls.html" title="Chapter 57. Native Language Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><th width="60%" align="center">Chapter 57. Native Language Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="nls-programmer.html" title="57.2. For the Programmer">Next</a></td></tr></table><hr /></div><div class="sect1" id="NLS-TRANSLATOR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">57.1. For the Translator</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.3">57.1.1. Requirements</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.4">57.1.2. Concepts</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.5">57.1.3. Creating and Maintaining Message Catalogs</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.6">57.1.4. Editing the PO Files</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span>
+ programs (server and client) can issue their messages in
+ your favorite language — if the messages have been translated.
+ Creating and maintaining translated message sets needs the help of
+ people who speak their own language well and want to contribute to
+ the <span class="productname">PostgreSQL</span> effort. You do not have to be a
+ programmer at all
+ to do this. This section explains how to help.
+ </p><div class="sect2" id="id-1.10.8.2.3"><div class="titlepage"><div><div><h3 class="title">57.1.1. Requirements</h3></div></div></div><p>
+ We won't judge your language skills — this section is about
+ software tools. Theoretically, you only need a text editor. But
+ this is only in the unlikely event that you do not want to try out
+ your translated messages. When you configure your source tree, be
+ sure to use the <code class="option">--enable-nls</code> option. This will
+ also check for the <span class="application">libintl</span> library and the
+ <code class="filename">msgfmt</code> program, which all end users will need
+ anyway. To try out your work, follow the applicable portions of
+ the installation instructions.
+ </p><p>
+ If you want to start a new translation effort or want to do a
+ message catalog merge (described later), you will need the
+ programs <code class="filename">xgettext</code> and
+ <code class="filename">msgmerge</code>, respectively, in a GNU-compatible
+ implementation. Later, we will try to arrange it so that if you
+ use a packaged source distribution, you won't need
+ <code class="filename">xgettext</code>. (If working from Git, you will still need
+ it.) <span class="application">GNU Gettext 0.10.36</span> or later is currently recommended.
+ </p><p>
+ Your local gettext implementation should come with its own
+ documentation. Some of that is probably duplicated in what
+ follows, but for additional details you should look there.
+ </p></div><div class="sect2" id="id-1.10.8.2.4"><div class="titlepage"><div><div><h3 class="title">57.1.2. Concepts</h3></div></div></div><p>
+ The pairs of original (English) messages and their (possibly)
+ translated equivalents are kept in <em class="firstterm">message
+ catalogs</em>, one for each program (although related
+ programs can share a message catalog) and for each target
+ language. There are two file formats for message catalogs: The
+ first is the <span class="quote">“<span class="quote">PO</span>”</span> file (for Portable Object), which
+ is a plain text file with special syntax that translators edit.
+ The second is the <span class="quote">“<span class="quote">MO</span>”</span> file (for Machine Object),
+ which is a binary file generated from the respective PO file and
+ is used while the internationalized program is run. Translators
+ do not deal with MO files; in fact hardly anyone does.
+ </p><p>
+ The extension of the message catalog file is to no surprise either
+ <code class="filename">.po</code> or <code class="filename">.mo</code>. The base
+ name is either the name of the program it accompanies, or the
+ language the file is for, depending on the situation. This is a
+ bit confusing. Examples are <code class="filename">psql.po</code> (PO file
+ for psql) or <code class="filename">fr.mo</code> (MO file in French).
+ </p><p>
+ The file format of the PO files is illustrated here:
+</p><pre class="programlisting">
+# comment
+
+msgid "original string"
+msgstr "translated string"
+
+msgid "more original"
+msgstr "another translated"
+"string can be broken up like this"
+
+...
+</pre><p>
+ The msgid lines are extracted from the program source. (They need not
+ be, but this is the most common way.) The msgstr lines are
+ initially empty and are filled in with useful strings by the
+ translator. The strings can contain C-style escape characters and
+ can be continued across lines as illustrated. (The next line must
+ start at the beginning of the line.)
+ </p><p>
+ The # character introduces a comment. If whitespace immediately
+ follows the # character, then this is a comment maintained by the
+ translator. There can also be automatic comments, which have a
+ non-whitespace character immediately following the #. These are
+ maintained by the various tools that operate on the PO files and
+ are intended to aid the translator.
+</p><pre class="programlisting">
+#. automatic comment
+#: filename.c:1023
+#, flags, flags
+</pre><p>
+ The #. style comments are extracted from the source file where the
+ message is used. Possibly the programmer has inserted information
+ for the translator, such as about expected alignment. The #:
+ comments indicate the exact locations where the message is used
+ in the source. The translator need not look at the program
+ source, but can if there is doubt about the correct
+ translation. The #, comments contain flags that describe the
+ message in some way. There are currently two flags:
+ <code class="literal">fuzzy</code> is set if the message has possibly been
+ outdated because of changes in the program source. The translator
+ can then verify this and possibly remove the fuzzy flag. Note
+ that fuzzy messages are not made available to the end user. The
+ other flag is <code class="literal">c-format</code>, which indicates that
+ the message is a <code class="function">printf</code>-style format
+ template. This means that the translation should also be a format
+ string with the same number and type of placeholders. There are
+ tools that can verify this, which key off the c-format flag.
+ </p></div><div class="sect2" id="id-1.10.8.2.5"><div class="titlepage"><div><div><h3 class="title">57.1.3. Creating and Maintaining Message Catalogs</h3></div></div></div><p>
+ OK, so how does one create a <span class="quote">“<span class="quote">blank</span>”</span> message
+ catalog? First, go into the directory that contains the program
+ whose messages you want to translate. If there is a file
+ <code class="filename">nls.mk</code>, then this program has been prepared
+ for translation.
+ </p><p>
+ If there are already some <code class="filename">.po</code> files, then
+ someone has already done some translation work. The files are
+ named <code class="filename"><em class="replaceable"><code>language</code></em>.po</code>,
+ where <em class="replaceable"><code>language</code></em> is the
+ <a class="ulink" href="https://www.loc.gov/standards/iso639-2/php/English_list.php" target="_top">
+ ISO 639-1 two-letter language code (in lower case)</a>, e.g.,
+ <code class="filename">fr.po</code> for French. If there is really a need
+ for more than one translation effort per language then the files
+ can also be named
+ <code class="filename"><em class="replaceable"><code>language</code></em>_<em class="replaceable"><code>region</code></em>.po</code>
+ where <em class="replaceable"><code>region</code></em> is the
+ <a class="ulink" href="https://www.iso.org/iso-3166-country-codes.html" target="_top">
+ ISO 3166-1 two-letter country code (in upper case)</a>,
+ e.g.,
+ <code class="filename">pt_BR.po</code> for Portuguese in Brazil. If you
+ find the language you wanted you can just start working on that
+ file.
+ </p><p>
+ If you need to start a new translation effort, then first run the
+ command:
+</p><pre class="programlisting">
+make init-po
+</pre><p>
+ This will create a file
+ <code class="filename"><em class="replaceable"><code>progname</code></em>.pot</code>.
+ (<code class="filename">.pot</code> to distinguish it from PO files that
+ are <span class="quote">“<span class="quote">in production</span>”</span>. The <code class="literal">T</code> stands for
+ <span class="quote">“<span class="quote">template</span>”</span>.)
+ Copy this file to
+ <code class="filename"><em class="replaceable"><code>language</code></em>.po</code> and
+ edit it. To make it known that the new language is available,
+ also edit the file <code class="filename">nls.mk</code> and add the
+ language (or language and country) code to the line that looks like:
+</p><pre class="programlisting">
+AVAIL_LANGUAGES := de fr
+</pre><p>
+ (Other languages can appear, of course.)
+ </p><p>
+ As the underlying program or library changes, messages might be
+ changed or added by the programmers. In this case you do not need
+ to start from scratch. Instead, run the command:
+</p><pre class="programlisting">
+make update-po
+</pre><p>
+ which will create a new blank message catalog file (the pot file
+ you started with) and will merge it with the existing PO files.
+ If the merge algorithm is not sure about a particular message it
+ marks it <span class="quote">“<span class="quote">fuzzy</span>”</span> as explained above. The new PO file
+ is saved with a <code class="filename">.po.new</code> extension.
+ </p></div><div class="sect2" id="id-1.10.8.2.6"><div class="titlepage"><div><div><h3 class="title">57.1.4. Editing the PO Files</h3></div></div></div><p>
+ The PO files can be edited with a regular text editor. The
+ translator should only change the area between the quotes after
+ the msgstr directive, add comments, and alter the fuzzy flag.
+ There is (unsurprisingly) a PO mode for Emacs, which I find quite
+ useful.
+ </p><p>
+ The PO files need not be completely filled in. The software will
+ automatically fall back to the original string if no translation
+ (or an empty translation) is available. It is no problem to
+ submit incomplete translations for inclusions in the source tree;
+ that gives room for other people to pick up your work. However,
+ you are encouraged to give priority to removing fuzzy entries
+ after doing a merge. Remember that fuzzy entries will not be
+ installed; they only serve as reference for what might be the right
+ translation.
+ </p><p>
+ Here are some things to keep in mind while editing the
+ translations:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Make sure that if the original ends with a newline, the
+ translation does, too. Similarly for tabs, etc.
+ </p></li><li class="listitem"><p>
+ If the original is a <code class="function">printf</code> format string, the translation
+ also needs to be. The translation also needs to have the same
+ format specifiers in the same order. Sometimes the natural
+ rules of the language make this impossible or at least awkward.
+ In that case you can modify the format specifiers like this:
+</p><pre class="programlisting">
+msgstr "Die Datei %2$s hat %1$u Zeichen."
+</pre><p>
+ Then the first placeholder will actually use the second
+ argument from the list. The
+ <code class="literal"><em class="replaceable"><code>digits</code></em>$</code> needs to
+ follow the % immediately, before any other format manipulators.
+ (This feature really exists in the <code class="function">printf</code>
+ family of functions. You might not have heard of it before because
+ there is little use for it outside of message
+ internationalization.)
+ </p></li><li class="listitem"><p>
+ If the original string contains a linguistic mistake, report
+ that (or fix it yourself in the program source) and translate
+ normally. The corrected string can be merged in when the
+ program sources have been updated. If the original string
+ contains a factual mistake, report that (or fix it yourself)
+ and do not translate it. Instead, you can mark the string with
+ a comment in the PO file.
+ </p></li><li class="listitem"><p>
+ Maintain the style and tone of the original string.
+ Specifically, messages that are not sentences (<code class="literal">cannot
+ open file %s</code>) should probably not start with a
+ capital letter (if your language distinguishes letter case) or
+ end with a period (if your language uses punctuation marks).
+ It might help to read <a class="xref" href="error-style-guide.html" title="56.3. Error Message Style Guide">Section 56.3</a>.
+ </p></li><li class="listitem"><p>
+ If you don't know what a message means, or if it is ambiguous,
+ ask on the developers' mailing list. Chances are that English
+ speaking end users might also not understand it or find it
+ ambiguous, so it's best to improve the message.
+ </p></li></ul></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls.html" title="Chapter 57. Native Language Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="nls-programmer.html" title="57.2. For the Programmer">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 57. Native Language Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 57.2. For the Programmer</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/nls.html b/doc/src/sgml/html/nls.html
new file mode 100644
index 0000000..ee828ee
--- /dev/null
+++ b/doc/src/sgml/html/nls.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 57. Native Language Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions" /><link rel="next" href="nls-translator.html" title="57.1. For the Translator" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 57. Native Language Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="nls-translator.html" title="57.1. For the Translator">Next</a></td></tr></table><hr /></div><div class="chapter" id="NLS"><div class="titlepage"><div><div><h2 class="title">Chapter 57. Native Language Support</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="nls-translator.html">57.1. For the Translator</a></span></dt><dd><dl><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.3">57.1.1. Requirements</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.4">57.1.2. Concepts</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.5">57.1.3. Creating and Maintaining Message Catalogs</a></span></dt><dt><span class="sect2"><a href="nls-translator.html#id-1.10.8.2.6">57.1.4. Editing the PO Files</a></span></dt></dl></dd><dt><span class="sect1"><a href="nls-programmer.html">57.2. For the Programmer</a></span></dt><dd><dl><dt><span class="sect2"><a href="nls-programmer.html#NLS-MECHANICS">57.2.1. Mechanics</a></span></dt><dt><span class="sect2"><a href="nls-programmer.html#NLS-GUIDELINES">57.2.2. Message-Writing Guidelines</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source-conventions.html" title="56.4. Miscellaneous Coding Conventions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="nls-translator.html" title="57.1. For the Translator">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.4. Miscellaneous Coding Conventions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 57.1. For the Translator</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/non-durability.html b/doc/src/sgml/html/non-durability.html
new file mode 100644
index 0000000..b47dd75
--- /dev/null
+++ b/doc/src/sgml/html/non-durability.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>14.5. Non-Durable Settings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="populate.html" title="14.4. Populating a Database" /><link rel="next" href="parallel-query.html" title="Chapter 15. Parallel Query" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">14.5. Non-Durable Settings</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="populate.html" title="14.4. Populating a Database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><th width="60%" align="center">Chapter 14. Performance Tips</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parallel-query.html" title="Chapter 15. Parallel Query">Next</a></td></tr></table><hr /></div><div class="sect1" id="NON-DURABILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">14.5. Non-Durable Settings</h2></div></div></div><a id="id-1.5.13.8.2" class="indexterm"></a><p>
+ Durability is a database feature that guarantees the recording of
+ committed transactions even if the server crashes or loses
+ power. However, durability adds significant database overhead,
+ so if your site does not require such a guarantee,
+ <span class="productname">PostgreSQL</span> can be configured to run
+ much faster. The following are configuration changes you can make
+ to improve performance in such cases. Except as noted below, durability
+ is still guaranteed in case of a crash of the database software;
+ only an abrupt operating system crash creates a risk of data loss
+ or corruption when these settings are used.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Place the database cluster's data directory in a memory-backed
+ file system (i.e., <acronym class="acronym">RAM</acronym> disk). This eliminates all
+ database disk I/O, but limits data storage to the amount of
+ available memory (and perhaps swap).
+ </p></li><li class="listitem"><p>
+ Turn off <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a>; there is no need to flush
+ data to disk.
+ </p></li><li class="listitem"><p>
+ Turn off <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a>; there might be no
+ need to force <acronym class="acronym">WAL</acronym> writes to disk on every
+ commit. This setting does risk transaction loss (though not data
+ corruption) in case of a crash of the <span class="emphasis"><em>database</em></span>.
+ </p></li><li class="listitem"><p>
+ Turn off <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a>; there is no need
+ to guard against partial page writes.
+ </p></li><li class="listitem"><p>
+ Increase <a class="xref" href="runtime-config-wal.html#GUC-MAX-WAL-SIZE">max_wal_size</a> and <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-TIMEOUT">checkpoint_timeout</a>; this reduces the frequency
+ of checkpoints, but increases the storage requirements of
+ <code class="filename">/pg_wal</code>.
+ </p></li><li class="listitem"><p>
+ Create <a class="link" href="sql-createtable.html#SQL-CREATETABLE-UNLOGGED">unlogged
+ tables</a> to avoid <acronym class="acronym">WAL</acronym> writes, though it
+ makes the tables non-crash-safe.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="populate.html" title="14.4. Populating a Database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel-query.html" title="Chapter 15. Parallel Query">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.4. Populating a Database </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Parallel Query</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/notation.html b/doc/src/sgml/html/notation.html
new file mode 100644
index 0000000..218d748
--- /dev/null
+++ b/doc/src/sgml/html/notation.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3. Conventions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="history.html" title="2. A Brief History of PostgreSQL" /><link rel="next" href="resources.html" title="4. Further Information" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3. Conventions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="history.html" title="2. A Brief History of PostgreSQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="resources.html" title="4. Further Information">Next</a></td></tr></table><hr /></div><div class="sect1" id="NOTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3. Conventions</h2></div></div></div><p>
+ The following conventions are used in the synopsis of a command:
+ brackets (<code class="literal">[</code> and <code class="literal">]</code>) indicate
+ optional parts. Braces
+ (<code class="literal">{</code> and <code class="literal">}</code>) and vertical lines
+ (<code class="literal">|</code>) indicate that you must choose one
+ alternative. Dots (<code class="literal">...</code>) mean that the preceding element
+ can be repeated. All other symbols, including parentheses, should be
+ taken literally.
+ </p><p>
+ Where it enhances the clarity, SQL commands are preceded by the
+ prompt <code class="literal">=&gt;</code>, and shell commands are preceded by the
+ prompt <code class="literal">$</code>. Normally, prompts are not shown, though.
+ </p><p>
+ An <em class="firstterm">administrator</em> is generally a person who is
+ in charge of installing and running the server. A <em class="firstterm">user</em>
+ could be anyone who is using, or wants to use, any part of the
+ <span class="productname">PostgreSQL</span> system. These terms should not
+ be interpreted too narrowly; this book does not have fixed
+ presumptions about system administration procedures.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="history.html" title="2. A Brief History of PostgreSQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="resources.html" title="4. Further Information">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. A Brief History of <span class="productname">PostgreSQL</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 4. Further Information</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/oid2name.html b/doc/src/sgml/html/oid2name.html
new file mode 100644
index 0000000..50d1835
--- /dev/null
+++ b/doc/src/sgml/html/oid2name.html
@@ -0,0 +1,192 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>oid2name</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-prog-client.html" title="G.1. Client Applications" /><link rel="next" href="vacuumlo.html" title="vacuumlo" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">oid2name</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-prog-client.html" title="G.1. Client Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib-prog-client.html" title="G.1. Client Applications">Up</a></td><th width="60%" align="center">G.1. Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="vacuumlo.html" title="vacuumlo">Next</a></td></tr></table><hr /></div><div class="refentry" id="OID2NAME"><div class="titlepage"></div><a id="id-1.11.8.4.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">oid2name</span></h2><p>oid2name — resolve OIDs and file nodes in a <span class="productname">PostgreSQL</span> data directory</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.11.8.4.3.4.1"><code class="command">oid2name</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.11.8.4.3.5"><h2>Description</h2><p>
+ <span class="application">oid2name</span> is a utility program that helps administrators to
+ examine the file structure used by PostgreSQL. To make use of it, you need
+ to be familiar with the database file structure, which is described in
+ <a class="xref" href="storage.html" title="Chapter 73. Database Physical Storage">Chapter 73</a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The name <span class="quote">“<span class="quote">oid2name</span>”</span> is historical, and is actually rather
+ misleading, since most of the time when you use it, you will really
+ be concerned with tables' filenode numbers (which are the file names
+ visible in the database directories). Be sure you understand the
+ difference between table OIDs and table filenodes!
+ </p></div><p>
+ <span class="application">oid2name</span> connects to a target database and
+ extracts OID, filenode, and/or table name information. You can also have
+ it show database OIDs or tablespace OIDs.
+ </p></div><div class="refsect1" id="id-1.11.8.4.3.6"><h2>Options</h2><p>
+ <span class="application">oid2name</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-f <em class="replaceable"><code>filenode</code></em></code><br /></span><span class="term"><code class="option">--filenode=<em class="replaceable"><code>filenode</code></em></code></span></dt><dd><p>show info for table with filenode <em class="replaceable"><code>filenode</code></em>.</p></dd><dt><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--indexes</code></span></dt><dd><p>include indexes and sequences in the listing.</p></dd><dt><span class="term"><code class="option">-o <em class="replaceable"><code>oid</code></em></code><br /></span><span class="term"><code class="option">--oid=<em class="replaceable"><code>oid</code></em></code></span></dt><dd><p>show info for table with OID <em class="replaceable"><code>oid</code></em>.</p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>omit headers (useful for scripting).</p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--tablespaces</code></span></dt><dd><p>show tablespace OIDs.</p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--system-objects</code></span></dt><dd><p>include system objects (those in
+ <code class="option">information_schema</code>, <code class="option">pg_toast</code>
+ and <code class="option">pg_catalog</code> schemas).
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>tablename_pattern</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>tablename_pattern</code></em></code></span></dt><dd><p>show info for table(s) matching <em class="replaceable"><code>tablename_pattern</code></em>.</p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">oid2name</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--extended</code></span></dt><dd><p>display more information about each object shown: tablespace name,
+ schema name, and OID.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">oid2name</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">oid2name</span> also accepts the following command-line
+ arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>database</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>database</code></em></code></span></dt><dd><p>database to connect to.</p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>database server's host.</p></dd><dt><span class="term"><code class="option">-H <em class="replaceable"><code>host</code></em></code></span></dt><dd><p>database server's host. Use of this parameter is
+ <span class="emphasis"><em>deprecated</em></span> as of
+ <span class="productname">PostgreSQL</span> 12.</p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>database server's port.</p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>user name to connect as.</p></dd></dl></div><p>
+ </p><p>
+ To display specific tables, select which tables to show by
+ using <code class="option">-o</code>, <code class="option">-f</code> and/or <code class="option">-t</code>.
+ <code class="option">-o</code> takes an OID,
+ <code class="option">-f</code> takes a filenode,
+ and <code class="option">-t</code> takes a table name (actually, it's a <code class="literal">LIKE</code>
+ pattern, so you can use things like <code class="literal">foo%</code>).
+ You can use as many
+ of these options as you like, and the listing will include all objects
+ matched by any of the options. But note that these options can only
+ show objects in the database given by <code class="option">-d</code>.
+ </p><p>
+ If you don't give any of <code class="option">-o</code>, <code class="option">-f</code> or <code class="option">-t</code>,
+ but do give <code class="option">-d</code>, it will list all tables in the database
+ named by <code class="option">-d</code>. In this mode, the <code class="option">-S</code> and
+ <code class="option">-i</code> options control what gets listed.
+ </p><p>
+ If you don't give <code class="option">-d</code> either, it will show a listing of database
+ OIDs. Alternatively you can give <code class="option">-s</code> to get a tablespace
+ listing.
+ </p></div><div class="refsect1" id="id-1.11.8.4.3.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span>
+ utilities, also uses the environment variables supported by
+ <span class="application">libpq</span> (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.11.8.4.3.8"><h2>Notes</h2><p>
+ <span class="application">oid2name</span> requires a running database server with
+ non-corrupt system catalogs. It is therefore of only limited use
+ for recovering from catastrophic database corruption situations.
+ </p></div><div class="refsect1" id="id-1.11.8.4.3.9"><h2>Examples</h2><pre class="screen">
+$ # what's in this database server, anyway?
+$ oid2name
+All databases:
+ Oid Database Name Tablespace
+----------------------------------
+ 17228 alvherre pg_default
+ 17255 regression pg_default
+ 17227 template0 pg_default
+ 1 template1 pg_default
+
+$ oid2name -s
+All tablespaces:
+ Oid Tablespace Name
+-------------------------
+ 1663 pg_default
+ 1664 pg_global
+ 155151 fastdisk
+ 155152 bigdisk
+
+$ # OK, let's look into database alvherre
+$ cd $PGDATA/base/17228
+
+$ # get top 10 db objects in the default tablespace, ordered by size
+$ ls -lS * | head -10
+-rw------- 1 alvherre alvherre 136536064 sep 14 09:51 155173
+-rw------- 1 alvherre alvherre 17965056 sep 14 09:51 1155291
+-rw------- 1 alvherre alvherre 1204224 sep 14 09:51 16717
+-rw------- 1 alvherre alvherre 581632 sep 6 17:51 1255
+-rw------- 1 alvherre alvherre 237568 sep 14 09:50 16674
+-rw------- 1 alvherre alvherre 212992 sep 14 09:51 1249
+-rw------- 1 alvherre alvherre 204800 sep 14 09:51 16684
+-rw------- 1 alvherre alvherre 196608 sep 14 09:50 16700
+-rw------- 1 alvherre alvherre 163840 sep 14 09:50 16699
+-rw------- 1 alvherre alvherre 122880 sep 6 17:51 16751
+
+$ # I wonder what file 155173 is ...
+$ oid2name -d alvherre -f 155173
+From database "alvherre":
+ Filenode Table Name
+----------------------
+ 155173 accounts
+
+$ # you can ask for more than one object
+$ oid2name -d alvherre -f 155173 -f 1155291
+From database "alvherre":
+ Filenode Table Name
+-------------------------
+ 155173 accounts
+ 1155291 accounts_pkey
+
+$ # you can mix the options, and get more details with -x
+$ oid2name -d alvherre -t accounts -f 1155291 -x
+From database "alvherre":
+ Filenode Table Name Oid Schema Tablespace
+------------------------------------------------------
+ 155173 accounts 155173 public pg_default
+ 1155291 accounts_pkey 1155291 public pg_default
+
+$ # show disk space for every db object
+$ du [0-9]* |
+&gt; while read SIZE FILENODE
+&gt; do
+&gt; echo "$SIZE `oid2name -q -d alvherre -i -f $FILENODE`"
+&gt; done
+16 1155287 branches_pkey
+16 1155289 tellers_pkey
+17561 1155291 accounts_pkey
+...
+
+$ # same, but sort by size
+$ du [0-9]* | sort -rn | while read SIZE FN
+&gt; do
+&gt; echo "$SIZE `oid2name -q -d alvherre -f $FN`"
+&gt; done
+133466 155173 accounts
+17561 1155291 accounts_pkey
+1177 16717 pg_proc_proname_args_nsp_index
+...
+
+$ # If you want to see what's in tablespaces, use the pg_tblspc directory
+$ cd $PGDATA/pg_tblspc
+$ oid2name -s
+All tablespaces:
+ Oid Tablespace Name
+-------------------------
+ 1663 pg_default
+ 1664 pg_global
+ 155151 fastdisk
+ 155152 bigdisk
+
+$ # what databases have objects in tablespace "fastdisk"?
+$ ls -d 155151/*
+155151/17228/ 155151/PG_VERSION
+
+$ # Oh, what was database 17228 again?
+$ oid2name
+All databases:
+ Oid Database Name Tablespace
+----------------------------------
+ 17228 alvherre pg_default
+ 17255 regression pg_default
+ 17227 template0 pg_default
+ 1 template1 pg_default
+
+$ # Let's see what objects does this database have in the tablespace.
+$ cd 155151/17228
+$ ls -l
+total 0
+-rw------- 1 postgres postgres 0 sep 13 23:20 155156
+
+$ # OK, this is a pretty small table ... but which one is it?
+$ oid2name -d alvherre -f 155156
+From database "alvherre":
+ Filenode Table Name
+----------------------
+ 155156 foo
+</pre></div><div class="refsect1" id="id-1.11.8.4.3.10"><h2>Author</h2><p>
+ B. Palmer <code class="email">&lt;<a class="email" href="mailto:bpalmer@crimelabs.net">bpalmer@crimelabs.net</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-prog-client.html" title="G.1. Client Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib-prog-client.html" title="G.1. Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vacuumlo.html" title="vacuumlo">Next</a></td></tr><tr><td width="40%" align="left" valign="top">G.1. Client Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">vacuumlo</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/oldsnapshot.html b/doc/src/sgml/html/oldsnapshot.html
new file mode 100644
index 0000000..51a77a7
--- /dev/null
+++ b/doc/src/sgml/html/oldsnapshot.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.24. old_snapshot</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="ltree.html" title="F.23. ltree" /><link rel="next" href="pageinspect.html" title="F.25. pageinspect" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.24. old_snapshot</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="ltree.html" title="F.23. ltree">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pageinspect.html" title="F.25. pageinspect">Next</a></td></tr></table><hr /></div><div class="sect1" id="OLDSNAPSHOT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.24. old_snapshot</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="oldsnapshot.html#id-1.11.7.33.4">F.24.1. Functions</a></span></dt></dl></div><a id="id-1.11.7.33.2" class="indexterm"></a><p>
+ The <code class="filename">old_snapshot</code> module allows inspection
+ of the server state that is used to implement
+ <a class="xref" href="runtime-config-resource.html#GUC-OLD-SNAPSHOT-THRESHOLD">old_snapshot_threshold</a>.
+ </p><div class="sect2" id="id-1.11.7.33.4"><div class="titlepage"><div><div><h3 class="title">F.24.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">pg_old_snapshot_time_mapping(array_offset OUT int4, end_timestamp OUT timestamptz, newest_xmin OUT xid) returns setof record</code></span></dt><dd><p>
+ Returns all of the entries in the server's timestamp to XID mapping.
+ Each entry represents the newest xmin of any snapshot taken in the
+ corresponding minute.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ltree.html" title="F.23. ltree">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pageinspect.html" title="F.25. pageinspect">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.23. ltree </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.25. pageinspect</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/overview.html b/doc/src/sgml/html/overview.html
new file mode 100644
index 0000000..dda4d14
--- /dev/null
+++ b/doc/src/sgml/html/overview.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 52. Overview of PostgreSQL Internals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="internals.html" title="Part VII. Internals" /><link rel="next" href="query-path.html" title="52.1. The Path of a Query" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 52. Overview of PostgreSQL Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="internals.html" title="Part VII. Internals">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="query-path.html" title="52.1. The Path of a Query">Next</a></td></tr></table><hr /></div><div class="chapter" id="OVERVIEW"><div class="titlepage"><div><div><h2 class="title">Chapter 52. Overview of PostgreSQL Internals</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="query-path.html">52.1. The Path of a Query</a></span></dt><dt><span class="sect1"><a href="connect-estab.html">52.2. How Connections Are Established</a></span></dt><dt><span class="sect1"><a href="parser-stage.html">52.3. The Parser Stage</a></span></dt><dd><dl><dt><span class="sect2"><a href="parser-stage.html#id-1.10.3.6.3">52.3.1. Parser</a></span></dt><dt><span class="sect2"><a href="parser-stage.html#id-1.10.3.6.4">52.3.2. Transformation Process</a></span></dt></dl></dd><dt><span class="sect1"><a href="rule-system.html">52.4. The <span class="productname">PostgreSQL</span> Rule System</a></span></dt><dt><span class="sect1"><a href="planner-optimizer.html">52.5. Planner/Optimizer</a></span></dt><dd><dl><dt><span class="sect2"><a href="planner-optimizer.html#id-1.10.3.8.5">52.5.1. Generating Possible Plans</a></span></dt></dl></dd><dt><span class="sect1"><a href="executor.html">52.6. Executor</a></span></dt></dl></div><div class="note"><h3 class="title">Author</h3><p>
+ This chapter originated as part of
+ <a class="xref" href="biblio.html#SIM98" title="Enhancement of the ANSI SQL Implementation of PostgreSQL">[sim98]</a> 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.
+ </p></div><p>
+ This chapter gives an overview of the internal structure of the
+ backend of <span class="productname">PostgreSQL</span>. After having
+ read the following sections you should have an idea of how a query
+ is processed. This chapter is intended to help the reader
+ understand the general sequence of operations that occur within the
+ backend from the point at which a query is received, to the point
+ at which the results are returned to the client.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="internals.html" title="Part VII. Internals">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="query-path.html" title="52.1. The Path of a Query">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VII. Internals </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.1. The Path of a Query</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pageinspect.html b/doc/src/sgml/html/pageinspect.html
new file mode 100644
index 0000000..4c34e37
--- /dev/null
+++ b/doc/src/sgml/html/pageinspect.html
@@ -0,0 +1,567 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.25. pageinspect</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="oldsnapshot.html" title="F.24. old_snapshot" /><link rel="next" href="passwordcheck.html" title="F.26. passwordcheck" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.25. pageinspect</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="oldsnapshot.html" title="F.24. old_snapshot">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="passwordcheck.html" title="F.26. passwordcheck">Next</a></td></tr></table><hr /></div><div class="sect1" id="PAGEINSPECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.25. pageinspect</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.4">F.25.1. General Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.5">F.25.2. Heap Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.6">F.25.3. B-Tree Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.7">F.25.4. BRIN Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.8">F.25.5. GIN Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.9">F.25.6. GiST Functions</a></span></dt><dt><span class="sect2"><a href="pageinspect.html#id-1.11.7.34.10">F.25.7. Hash Functions</a></span></dt></dl></div><a id="id-1.11.7.34.2" class="indexterm"></a><p>
+ The <code class="filename">pageinspect</code> module provides functions that allow you to
+ inspect the contents of database pages at a low level, which is useful for
+ debugging purposes. All of these functions may be used only by superusers.
+ </p><div class="sect2" id="id-1.11.7.34.4"><div class="titlepage"><div><div><h3 class="title">F.25.1. General Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">get_raw_page(relname text, fork text, blkno bigint) returns bytea</code>
+ <a id="id-1.11.7.34.4.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">get_raw_page</code> reads the specified block of the named
+ relation and returns a copy as a <code class="type">bytea</code> value. This allows a
+ single time-consistent copy of the block to be obtained.
+ <em class="replaceable"><code>fork</code></em> should be <code class="literal">'main'</code> for
+ the main data fork, <code class="literal">'fsm'</code> for the
+ <a class="link" href="storage-fsm.html" title="73.3. Free Space Map">free space map</a>,
+ <code class="literal">'vm'</code> for the
+ <a class="link" href="storage-vm.html" title="73.4. Visibility Map">visibility map</a>, or
+ <code class="literal">'init'</code> for the initialization fork.
+ </p></dd><dt><span class="term">
+ <code class="function">get_raw_page(relname text, blkno bigint) returns bytea</code>
+ </span></dt><dd><p>
+ A shorthand version of <code class="function">get_raw_page</code>, for reading
+ from the main fork. Equivalent to
+ <code class="literal">get_raw_page(relname, 'main', blkno)</code>
+ </p></dd><dt><span class="term">
+ <code class="function">page_header(page bytea) returns record</code>
+ <a id="id-1.11.7.34.4.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">page_header</code> shows fields that are common to all
+ <span class="productname">PostgreSQL</span> heap and index pages.
+ </p><p>
+ A page image obtained with <code class="function">get_raw_page</code> should be
+ passed as argument. For example:
+</p><pre class="screen">
+test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
+ lsn | checksum | flags | lower | upper | special | pagesize | version | prune_xid
+-----------+----------+--------+-------+-------+---------+----------+---------+-----------
+ 0/24A1B50 | 0 | 1 | 232 | 368 | 8192 | 8192 | 4 | 0
+</pre><p>
+ The returned columns correspond to the fields in the
+ <code class="structname">PageHeaderData</code> struct.
+ See <code class="filename">src/include/storage/bufpage.h</code> for details.
+ </p><p>
+ The <code class="structfield">checksum</code> field is the checksum stored in
+ the page, which might be incorrect if the page is somehow corrupted. If
+ data checksums are not enabled for this instance, then the value stored
+ is meaningless.
+ </p></dd><dt><span class="term">
+ <code class="function">page_checksum(page bytea, blkno bigint) returns smallint</code>
+ <a id="id-1.11.7.34.4.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">page_checksum</code> computes the checksum for the page, as if
+ it was located at the given block.
+ </p><p>
+ A page image obtained with <code class="function">get_raw_page</code> should be
+ passed as argument. For example:
+</p><pre class="screen">
+test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
+ page_checksum
+---------------
+ 13443
+</pre><p>
+ Note that the checksum depends on the block number, so matching block
+ numbers should be passed (except when doing esoteric debugging).
+ </p><p>
+ The checksum computed with this function can be compared with
+ the <code class="structfield">checksum</code> result field of the
+ function <code class="function">page_header</code>. If data checksums are
+ enabled for this instance, then the two values should be equal.
+ </p></dd><dt><span class="term">
+ <code class="function">fsm_page_contents(page bytea) returns text</code>
+ <a id="id-1.11.7.34.4.2.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">fsm_page_contents</code> shows the internal node structure
+ of an <acronym class="acronym">FSM</acronym> page. For example:
+</p><pre class="screen">
+test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
+</pre><p>
+ The output is a multiline string, with one line per node in the binary
+ tree within the page. Only those nodes that are not zero are printed.
+ The so-called "next" pointer, which points to the next slot to be
+ returned from the page, is also printed.
+ </p><p>
+ See <code class="filename">src/backend/storage/freespace/README</code> for more
+ information on the structure of an <acronym class="acronym">FSM</acronym> page.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.5"><div class="titlepage"><div><div><h3 class="title">F.25.2. Heap Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">heap_page_items(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.5.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">heap_page_items</code> shows all line pointers on a heap
+ page. For those line pointers that are in use, tuple headers as well
+ as tuple raw data are also shown. All tuples are shown, whether or not
+ the tuples were visible to an MVCC snapshot at the time the raw page
+ was copied.
+ </p><p>
+ A heap page image obtained with <code class="function">get_raw_page</code> should
+ be passed as argument. For example:
+</p><pre class="screen">
+test=# SELECT * FROM heap_page_items(get_raw_page('pg_class', 0));
+</pre><p>
+ See <code class="filename">src/include/storage/itemid.h</code> and
+ <code class="filename">src/include/access/htup_details.h</code> for explanations of the fields
+ returned.
+ </p><p>
+ The <code class="function">heap_tuple_infomask_flags</code> function can be
+ used to unpack the flag bits of <code class="structfield">t_infomask</code>
+ and <code class="structfield">t_infomask2</code> for heap tuples.
+ </p></dd><dt><span class="term">
+ <code class="function">tuple_data_split(rel_oid oid, t_data bytea, t_infomask integer, t_infomask2 integer, t_bits text [, do_detoast bool]) returns bytea[]</code>
+ <a id="id-1.11.7.34.5.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">tuple_data_split</code> splits tuple data into attributes
+ in the same way as backend internals.
+</p><pre class="screen">
+test=# SELECT tuple_data_split('pg_class'::regclass, t_data, t_infomask, t_infomask2, t_bits) FROM heap_page_items(get_raw_page('pg_class', 0));
+</pre><p>
+ This function should be called with the same arguments as the return
+ attributes of <code class="function">heap_page_items</code>.
+ </p><p>
+ If <em class="parameter"><code>do_detoast</code></em> is <code class="literal">true</code>,
+ attributes will be detoasted as needed. Default value is
+ <code class="literal">false</code>.
+ </p></dd><dt><span class="term">
+ <code class="function">heap_page_item_attrs(page bytea, rel_oid regclass [, do_detoast bool]) returns setof record</code>
+ <a id="id-1.11.7.34.5.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">heap_page_item_attrs</code> is equivalent to
+ <code class="function">heap_page_items</code> except that it returns
+ tuple raw data as an array of attributes that can optionally
+ be detoasted by <em class="parameter"><code>do_detoast</code></em> which is
+ <code class="literal">false</code> by default.
+ </p><p>
+ A heap page image obtained with <code class="function">get_raw_page</code> should
+ be passed as argument. For example:
+</p><pre class="screen">
+test=# SELECT * FROM heap_page_item_attrs(get_raw_page('pg_class', 0), 'pg_class'::regclass);
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">heap_tuple_infomask_flags(t_infomask integer, t_infomask2 integer) returns record</code>
+ <a id="id-1.11.7.34.5.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">heap_tuple_infomask_flags</code> decodes the
+ <code class="structfield">t_infomask</code> and
+ <code class="structfield">t_infomask2</code> returned by
+ <code class="function">heap_page_items</code> into a human-readable
+ set of arrays made of flag names, with one column for all
+ the flags and one column for combined flags. For example:
+</p><pre class="screen">
+test=# SELECT t_ctid, raw_flags, combined_flags
+ FROM heap_page_items(get_raw_page('pg_class', 0)),
+ LATERAL heap_tuple_infomask_flags(t_infomask, t_infomask2)
+ WHERE t_infomask IS NOT NULL OR t_infomask2 IS NOT NULL;
+</pre><p>
+ This function should be called with the same arguments as the return
+ attributes of <code class="function">heap_page_items</code>.
+ </p><p>
+ Combined flags are displayed for source-level macros that take into
+ account the value of more than one raw bit, such as
+ <code class="literal">HEAP_XMIN_FROZEN</code>.
+ </p><p>
+ See <code class="filename">src/include/access/htup_details.h</code> for
+ explanations of the flag names returned.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.6"><div class="titlepage"><div><div><h3 class="title">F.25.3. B-Tree Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">bt_metap(relname text) returns record</code>
+ <a id="id-1.11.7.34.6.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">bt_metap</code> returns information about a B-tree
+ index's metapage. For example:
+</p><pre class="screen">
+test=# SELECT * FROM bt_metap('pg_cast_oid_index');
+-[ RECORD 1 ]-------------+-------
+magic | 340322
+version | 4
+root | 1
+level | 0
+fastroot | 1
+fastlevel | 0
+last_cleanup_num_delpages | 0
+last_cleanup_num_tuples | 230
+allequalimage | f
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">bt_page_stats(relname text, blkno bigint) returns record</code>
+ <a id="id-1.11.7.34.6.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">bt_page_stats</code> returns summary information about
+ single pages of B-tree indexes. For example:
+</p><pre class="screen">
+test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
+-[ RECORD 1 ]-+-----
+blkno | 1
+type | l
+live_items | 224
+dead_items | 0
+avg_item_size | 16
+page_size | 8192
+free_size | 3668
+btpo_prev | 0
+btpo_next | 0
+btpo_level | 0
+btpo_flags | 3
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">bt_page_items(relname text, blkno bigint) returns setof record</code>
+ <a id="id-1.11.7.34.6.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">bt_page_items</code> returns detailed information about
+ all of the items on a B-tree index page. For example:
+</p><pre class="screen">
+test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
+ FROM bt_page_items('tenk2_hundred', 5);
+ itemoffset | ctid | itemlen | nulls | vars | data | dead | htid | some_tids
+------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
+ 1 | (16,1) | 16 | f | f | 30 00 00 00 00 00 00 00 | | |
+ 2 | (16,8292) | 616 | f | f | 24 00 00 00 00 00 00 00 | f | (1,6) | {"(1,6)","(10,22)"}
+ 3 | (16,8292) | 616 | f | f | 25 00 00 00 00 00 00 00 | f | (1,18) | {"(1,18)","(4,22)"}
+ 4 | (16,8292) | 616 | f | f | 26 00 00 00 00 00 00 00 | f | (4,18) | {"(4,18)","(6,17)"}
+ 5 | (16,8292) | 616 | f | f | 27 00 00 00 00 00 00 00 | f | (1,2) | {"(1,2)","(1,19)"}
+ 6 | (16,8292) | 616 | f | f | 28 00 00 00 00 00 00 00 | f | (2,24) | {"(2,24)","(4,11)"}
+ 7 | (16,8292) | 616 | f | f | 29 00 00 00 00 00 00 00 | f | (2,17) | {"(2,17)","(11,2)"}
+ 8 | (16,8292) | 616 | f | f | 2a 00 00 00 00 00 00 00 | f | (0,25) | {"(0,25)","(3,20)"}
+ 9 | (16,8292) | 616 | f | f | 2b 00 00 00 00 00 00 00 | f | (0,10) | {"(0,10)","(0,14)"}
+ 10 | (16,8292) | 616 | f | f | 2c 00 00 00 00 00 00 00 | f | (1,3) | {"(1,3)","(3,9)"}
+ 11 | (16,8292) | 616 | f | f | 2d 00 00 00 00 00 00 00 | f | (6,28) | {"(6,28)","(11,1)"}
+ 12 | (16,8292) | 616 | f | f | 2e 00 00 00 00 00 00 00 | f | (0,27) | {"(0,27)","(1,13)"}
+ 13 | (16,8292) | 616 | f | f | 2f 00 00 00 00 00 00 00 | f | (4,17) | {"(4,17)","(4,21)"}
+(13 rows)
+</pre><p>
+ This is a B-tree leaf page. All tuples that point to the table
+ happen to be posting list tuples (all of which store a total of
+ 100 6 byte TIDs). There is also a <span class="quote">“<span class="quote">high key</span>”</span> tuple
+ at <code class="literal">itemoffset</code> number 1.
+ <code class="structfield">ctid</code> is used to store encoded
+ information about each tuple in this example, though leaf page
+ tuples often store a heap TID directly in the
+ <code class="structfield">ctid</code> field instead.
+ <code class="structfield">tids</code> is the list of TIDs stored as a
+ posting list.
+ </p><p>
+ In an internal page (not shown), the block number part of
+ <code class="structfield">ctid</code> is a <span class="quote">“<span class="quote">downlink</span>”</span>,
+ which is a block number of another page in the index itself.
+ The offset part (the second number) of
+ <code class="structfield">ctid</code> stores encoded information about
+ the tuple, such as the number of columns present (suffix
+ truncation may have removed unneeded suffix columns). Truncated
+ columns are treated as having the value <span class="quote">“<span class="quote">minus
+ infinity</span>”</span>.
+ </p><p>
+ <code class="structfield">htid</code> shows a heap TID for the tuple,
+ regardless of the underlying tuple representation. This value
+ may match <code class="structfield">ctid</code>, or may be decoded
+ from the alternative representations used by posting list tuples
+ and tuples from internal pages. Tuples in internal pages
+ usually have the implementation level heap TID column truncated
+ away, which is represented as a NULL
+ <code class="structfield">htid</code> value.
+ </p><p>
+ Note that the first item on any non-rightmost page (any page with
+ a non-zero value in the <code class="structfield">btpo_next</code> field) is the
+ page's <span class="quote">“<span class="quote">high key</span>”</span>, meaning its <code class="structfield">data</code>
+ serves as an upper bound on all items appearing on the page, while
+ its <code class="structfield">ctid</code> field does not point to
+ another block. Also, on internal pages, the first real data
+ item (the first item that is not a high key) reliably has every
+ column truncated away, leaving no actual value in its
+ <code class="structfield">data</code> field. Such an item does have a
+ valid downlink in its <code class="structfield">ctid</code> field,
+ however.
+ </p><p>
+ For more details about the structure of B-tree indexes, see
+ <a class="xref" href="btree-implementation.html#BTREE-STRUCTURE" title="67.4.1. B-Tree Structure">Section 67.4.1</a>. For more details about
+ deduplication and posting lists, see <a class="xref" href="btree-implementation.html#BTREE-DEDUPLICATION" title="67.4.3. Deduplication">Section 67.4.3</a>.
+ </p></dd><dt><span class="term">
+ <code class="function">bt_page_items(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.6.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ It is also possible to pass a page to <code class="function">bt_page_items</code>
+ as a <code class="type">bytea</code> value. A page image obtained
+ with <code class="function">get_raw_page</code> should be passed as argument. So
+ the last example could also be rewritten like this:
+</p><pre class="screen">
+test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
+ FROM bt_page_items(get_raw_page('tenk2_hundred', 5));
+ itemoffset | ctid | itemlen | nulls | vars | data | dead | htid | some_tids
+------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
+ 1 | (16,1) | 16 | f | f | 30 00 00 00 00 00 00 00 | | |
+ 2 | (16,8292) | 616 | f | f | 24 00 00 00 00 00 00 00 | f | (1,6) | {"(1,6)","(10,22)"}
+ 3 | (16,8292) | 616 | f | f | 25 00 00 00 00 00 00 00 | f | (1,18) | {"(1,18)","(4,22)"}
+ 4 | (16,8292) | 616 | f | f | 26 00 00 00 00 00 00 00 | f | (4,18) | {"(4,18)","(6,17)"}
+ 5 | (16,8292) | 616 | f | f | 27 00 00 00 00 00 00 00 | f | (1,2) | {"(1,2)","(1,19)"}
+ 6 | (16,8292) | 616 | f | f | 28 00 00 00 00 00 00 00 | f | (2,24) | {"(2,24)","(4,11)"}
+ 7 | (16,8292) | 616 | f | f | 29 00 00 00 00 00 00 00 | f | (2,17) | {"(2,17)","(11,2)"}
+ 8 | (16,8292) | 616 | f | f | 2a 00 00 00 00 00 00 00 | f | (0,25) | {"(0,25)","(3,20)"}
+ 9 | (16,8292) | 616 | f | f | 2b 00 00 00 00 00 00 00 | f | (0,10) | {"(0,10)","(0,14)"}
+ 10 | (16,8292) | 616 | f | f | 2c 00 00 00 00 00 00 00 | f | (1,3) | {"(1,3)","(3,9)"}
+ 11 | (16,8292) | 616 | f | f | 2d 00 00 00 00 00 00 00 | f | (6,28) | {"(6,28)","(11,1)"}
+ 12 | (16,8292) | 616 | f | f | 2e 00 00 00 00 00 00 00 | f | (0,27) | {"(0,27)","(1,13)"}
+ 13 | (16,8292) | 616 | f | f | 2f 00 00 00 00 00 00 00 | f | (4,17) | {"(4,17)","(4,21)"}
+(13 rows)
+</pre><p>
+ All the other details are the same as explained in the previous item.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.7"><div class="titlepage"><div><div><h3 class="title">F.25.4. BRIN Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">brin_page_type(page bytea) returns text</code>
+ <a id="id-1.11.7.34.7.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">brin_page_type</code> returns the page type of the given
+ <acronym class="acronym">BRIN</acronym> index page, or throws an error if the page is
+ not a valid <acronym class="acronym">BRIN</acronym> page. For example:
+</p><pre class="screen">
+test=# SELECT brin_page_type(get_raw_page('brinidx', 0));
+ brin_page_type
+----------------
+ meta
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">brin_metapage_info(page bytea) returns record</code>
+ <a id="id-1.11.7.34.7.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">brin_metapage_info</code> returns assorted information
+ about a <acronym class="acronym">BRIN</acronym> index metapage. For example:
+</p><pre class="screen">
+test=# SELECT * FROM brin_metapage_info(get_raw_page('brinidx', 0));
+ magic | version | pagesperrange | lastrevmappage
+------------+---------+---------------+----------------
+ 0xA8109CFA | 1 | 4 | 2
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">brin_revmap_data(page bytea) returns setof tid</code>
+ <a id="id-1.11.7.34.7.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">brin_revmap_data</code> returns the list of tuple
+ identifiers in a <acronym class="acronym">BRIN</acronym> index range map page.
+ For example:
+</p><pre class="screen">
+test=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) LIMIT 5;
+ pages
+---------
+ (6,137)
+ (6,138)
+ (6,139)
+ (6,140)
+ (6,141)
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">brin_page_items(page bytea, index oid) returns setof record</code>
+ <a id="id-1.11.7.34.7.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">brin_page_items</code> returns the data stored in the
+ <acronym class="acronym">BRIN</acronym> data page. For example:
+</p><pre class="screen">
+test=# SELECT * FROM brin_page_items(get_raw_page('brinidx', 5),
+ 'brinidx')
+ ORDER BY blknum, attnum LIMIT 6;
+ itemoffset | blknum | attnum | allnulls | hasnulls | placeholder | value
+------------+--------+--------+----------+----------+-------------+--------------
+ 137 | 0 | 1 | t | f | f |
+ 137 | 0 | 2 | f | f | f | {1 .. 88}
+ 138 | 4 | 1 | t | f | f |
+ 138 | 4 | 2 | f | f | f | {89 .. 176}
+ 139 | 8 | 1 | t | f | f |
+ 139 | 8 | 2 | f | f | f | {177 .. 264}
+</pre><p>
+ The returned columns correspond to the fields in the
+ <code class="structname">BrinMemTuple</code> and <code class="structname">BrinValues</code> structs.
+ See <code class="filename">src/include/access/brin_tuple.h</code> for details.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.8"><div class="titlepage"><div><div><h3 class="title">F.25.5. GIN Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">gin_metapage_info(page bytea) returns record</code>
+ <a id="id-1.11.7.34.8.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">gin_metapage_info</code> returns information about
+ a <acronym class="acronym">GIN</acronym> index metapage. For example:
+</p><pre class="screen">
+test=# SELECT * FROM gin_metapage_info(get_raw_page('gin_index', 0));
+-[ RECORD 1 ]----+-----------
+pending_head | 4294967295
+pending_tail | 4294967295
+tail_free_size | 0
+n_pending_pages | 0
+n_pending_tuples | 0
+n_total_pages | 7
+n_entry_pages | 6
+n_data_pages | 0
+n_entries | 693
+version | 2
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">gin_page_opaque_info(page bytea) returns record</code>
+ <a id="id-1.11.7.34.8.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">gin_page_opaque_info</code> returns information about
+ a <acronym class="acronym">GIN</acronym> index opaque area, like the page type.
+ For example:
+</p><pre class="screen">
+test=# SELECT * FROM gin_page_opaque_info(get_raw_page('gin_index', 2));
+ rightlink | maxoff | flags
+-----------+--------+------------------------
+ 5 | 0 | {data,leaf,compressed}
+(1 row)
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">gin_leafpage_items(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.8.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">gin_leafpage_items</code> returns information about
+ the data stored in a <acronym class="acronym">GIN</acronym> leaf page. For example:
+</p><pre class="screen">
+test=# SELECT first_tid, nbytes, tids[0:5] AS some_tids
+ FROM gin_leafpage_items(get_raw_page('gin_test_idx', 2));
+ first_tid | nbytes | some_tids
+-----------+--------+----------------------------------------------------------
+ (8,41) | 244 | {"(8,41)","(8,43)","(8,44)","(8,45)","(8,46)"}
+ (10,45) | 248 | {"(10,45)","(10,46)","(10,47)","(10,48)","(10,49)"}
+ (12,52) | 248 | {"(12,52)","(12,53)","(12,54)","(12,55)","(12,56)"}
+ (14,59) | 320 | {"(14,59)","(14,60)","(14,61)","(14,62)","(14,63)"}
+ (167,16) | 376 | {"(167,16)","(167,17)","(167,18)","(167,19)","(167,20)"}
+ (170,30) | 376 | {"(170,30)","(170,31)","(170,32)","(170,33)","(170,34)"}
+ (173,44) | 197 | {"(173,44)","(173,45)","(173,46)","(173,47)","(173,48)"}
+(7 rows)
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.9"><div class="titlepage"><div><div><h3 class="title">F.25.6. GiST Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">gist_page_opaque_info(page bytea) returns record</code>
+ <a id="id-1.11.7.34.9.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">gist_page_opaque_info</code> returns information from
+ a <acronym class="acronym">GiST</acronym> index page's opaque area, such as the NSN,
+ rightlink and page type.
+ For example:
+</p><pre class="screen">
+test=# SELECT * FROM gist_page_opaque_info(get_raw_page('test_gist_idx', 2));
+ lsn | nsn | rightlink | flags
+-----+-----+-----------+--------
+ 0/1 | 0/0 | 1 | {leaf}
+(1 row)
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">gist_page_items(page bytea, index_oid regclass) returns setof record</code>
+ <a id="id-1.11.7.34.9.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">gist_page_items</code> returns information about
+ the data stored in a page of a <acronym class="acronym">GiST</acronym> index. For example:
+</p><pre class="screen">
+test=# SELECT * FROM gist_page_items(get_raw_page('test_gist_idx', 0), 'test_gist_idx');
+ itemoffset | ctid | itemlen | dead | keys
+------------+-----------+---------+------+-------------------------------
+ 1 | (1,65535) | 40 | f | (p)=("(185,185),(1,1)")
+ 2 | (2,65535) | 40 | f | (p)=("(370,370),(186,186)")
+ 3 | (3,65535) | 40 | f | (p)=("(555,555),(371,371)")
+ 4 | (4,65535) | 40 | f | (p)=("(740,740),(556,556)")
+ 5 | (5,65535) | 40 | f | (p)=("(870,870),(741,741)")
+ 6 | (6,65535) | 40 | f | (p)=("(1000,1000),(871,871)")
+(6 rows)
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">gist_page_items_bytea(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.9.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Same as <code class="function">gist_page_items</code>, but returns the key data
+ as a raw <code class="type">bytea</code> blob. Since it does not attempt to decode
+ the key, it does not need to know which index is involved. For
+ example:
+</p><pre class="screen">
+test=# SELECT * FROM gist_page_items_bytea(get_raw_page('test_gist_idx', 0));
+ itemoffset | ctid | itemlen | dead | key_data
+------------+-----------+---------+------+-----------------------------------------​-------------------------------------------
+ 1 | (1,65535) | 40 | f | \x00000100ffff28000000000000c0644000000000​00c06440000000000000f03f000000000000f03f
+ 2 | (2,65535) | 40 | f | \x00000200ffff28000000000000c0744000000000​00c074400000000000e064400000000000e06440
+ 3 | (3,65535) | 40 | f | \x00000300ffff28000000000000207f4000000000​00207f400000000000d074400000000000d07440
+ 4 | (4,65535) | 40 | f | \x00000400ffff28000000000000c0844000000000​00c084400000000000307f400000000000307f40
+ 5 | (5,65535) | 40 | f | \x00000500ffff28000000000000f0894000000000​00f089400000000000c884400000000000c88440
+ 6 | (6,65535) | 40 | f | \x00000600ffff28000000000000208f4000000000​00208f400000000000f889400000000000f88940
+ 7 | (7,65535) | 40 | f | \x00000700ffff28000000000000408f4000000000​00408f400000000000288f400000000000288f40
+(7 rows)
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.34.10"><div class="titlepage"><div><div><h3 class="title">F.25.7. Hash Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">hash_page_type(page bytea) returns text</code>
+ <a id="id-1.11.7.34.10.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">hash_page_type</code> returns page type of
+ the given <acronym class="acronym">HASH</acronym> index page. For example:
+</p><pre class="screen">
+test=# SELECT hash_page_type(get_raw_page('con_hash_index', 0));
+ hash_page_type
+----------------
+ metapage
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">hash_page_stats(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.10.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">hash_page_stats</code> returns information about
+ a bucket or overflow page of a <acronym class="acronym">HASH</acronym> index.
+ For example:
+</p><pre class="screen">
+test=# SELECT * FROM hash_page_stats(get_raw_page('con_hash_index', 1));
+-[ RECORD 1 ]---+-----------
+live_items | 407
+dead_items | 0
+page_size | 8192
+free_size | 8
+hasho_prevblkno | 4096
+hasho_nextblkno | 8474
+hasho_bucket | 0
+hasho_flag | 66
+hasho_page_id | 65408
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">hash_page_items(page bytea) returns setof record</code>
+ <a id="id-1.11.7.34.10.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">hash_page_items</code> returns information about
+ the data stored in a bucket or overflow page of a <acronym class="acronym">HASH</acronym>
+ index page. For example:
+</p><pre class="screen">
+test=# SELECT * FROM hash_page_items(get_raw_page('con_hash_index', 1)) LIMIT 5;
+ itemoffset | ctid | data
+------------+-----------+------------
+ 1 | (899,77) | 1053474816
+ 2 | (897,29) | 1053474816
+ 3 | (894,207) | 1053474816
+ 4 | (892,159) | 1053474816
+ 5 | (890,111) | 1053474816
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">hash_bitmap_info(index oid, blkno bigint) returns record</code>
+ <a id="id-1.11.7.34.10.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">hash_bitmap_info</code> shows the status of a bit
+ in the bitmap page for a particular overflow page of <acronym class="acronym">HASH</acronym>
+ index. For example:
+</p><pre class="screen">
+test=# SELECT * FROM hash_bitmap_info('con_hash_index', 2052);
+ bitmapblkno | bitmapbit | bitstatus
+-------------+-----------+-----------
+ 65 | 3 | t
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">hash_metapage_info(page bytea) returns record</code>
+ <a id="id-1.11.7.34.10.2.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">hash_metapage_info</code> returns information stored
+ in the meta page of a <acronym class="acronym">HASH</acronym> index. For example:
+</p><pre class="screen">
+test=# SELECT magic, version, ntuples, ffactor, bsize, bmsize, bmshift,
+test-# maxbucket, highmask, lowmask, ovflpoint, firstfree, nmaps, procid,
+test-# regexp_replace(spares::text, '(,0)*}', '}') as spares,
+test-# regexp_replace(mapp::text, '(,0)*}', '}') as mapp
+test-# FROM hash_metapage_info(get_raw_page('con_hash_index', 0));
+-[ RECORD 1 ]-------------------------------------------------​------------------------------
+magic | 105121344
+version | 4
+ntuples | 500500
+ffactor | 40
+bsize | 8152
+bmsize | 4096
+bmshift | 15
+maxbucket | 12512
+highmask | 16383
+lowmask | 8191
+ovflpoint | 28
+firstfree | 1204
+nmaps | 1
+procid | 450
+spares | {0,0,0,0,0,0,1,1,1,1,1,1,1,1,3,4,4,4,45,55,58,59,​508,567,628,704,1193,1202,1204}
+mapp | {65}
+</pre><p>
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oldsnapshot.html" title="F.24. old_snapshot">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="passwordcheck.html" title="F.26. passwordcheck">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.24. old_snapshot </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.26. passwordcheck</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pagelayout.svg b/doc/src/sgml/html/pagelayout.svg
new file mode 100644
index 0000000..5b2caaf
--- /dev/null
+++ b/doc/src/sgml/html/pagelayout.svg
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 610 210" width="610" height="210" shape-rendering="geometricPrecision" version="1.0">
+ <defs>
+ <filter id="f2" x="0" y="0" width="200%" height="200%">
+ <feOffset result="offOut" in="SourceGraphic" dx="5" dy="5"/>
+ <feGaussianBlur result="blurOut" in="offOut" stdDeviation="3"/>
+ <feBlend in="SourceGraphic" in2="blurOut" mode="normal"/>
+ </filter>
+ </defs>
+ <g stroke-width="1" stroke-linecap="square" stroke-linejoin="round">
+ <rect x="0" y="0" width="610" height="210" style="fill: #ffffff"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M25.0 35.0 L25.0 175.0 L585.0 175.0 L585.0 35.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M305.0 175.0 L485.0 175.0 L485.0 147.0 L305.0 147.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M25.0 35.0 L25.0 63.0 L195.0 63.0 L195.0 35.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M305.0 147.0 L305.0 175.0 L195.0 175.0 L195.0 147.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M325.0 63.0 L325.0 91.0 L265.0 91.0 L265.0 105.0 L235.0 105.0 L235.0 63.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M585.0 147.0 L585.0 175.0 L485.0 175.0 L485.0 147.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M195.0 35.0 L285.0 35.0 L285.0 63.0 L195.0 63.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="white" d="M375.0 35.0 L375.0 63.0 L285.0 63.0 L285.0 35.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="none" d="M335.0 133.0 L335.0 105.0 L265.0 105.0 "/>
+ <path stroke="none" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="#000000" d="M470.0 42.0 L480.0 49.0 L470.0 56.0 z"/>
+ <path stroke="none" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="#000000" d="M260.0 126.0 L265.0 140.0 L270.0 126.0 z"/>
+ <path stroke="none" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="#000000" d="M330.0 126.0 L335.0 140.0 L340.0 126.0 z"/>
+ <path stroke="none" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="#000000" d="M140.0 154.0 L130.0 161.0 L140.0 168.0 z"/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-linecap="round" stroke-linejoin="round" fill="none" d="M265.0 105.0 L265.0 133.0 "/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-dasharray="5.000000,5.000000" stroke-miterlimit="0" stroke-linecap="butt" stroke-linejoin="round" fill="white" d="M375.0 49.0 L475.0 49.0 "/>
+ <path stroke="#000000" stroke-width="1.000000" stroke-dasharray="5.000000,5.000000" stroke-miterlimit="0" stroke-linecap="butt" stroke-linejoin="round" fill="white" d="M135.0 161.0 L195.0 161.0 "/>
+ <text x="48" y="54" font-family="Courier" font-size="15" stroke="none" fill="#000000">PageHeaderData</text>
+ <text x="214" y="166" font-family="Courier" font-size="15" stroke="none" fill="#000000">Item</text>
+ <text x="216" y="54" font-family="Courier" font-size="15" stroke="none" fill="#000000">ItemId</text>
+ <text x="306" y="54" font-family="Courier" font-size="15" stroke="none" fill="#000000">ItemId</text>
+ <text x="324" y="166" font-family="Courier" font-size="15" stroke="none" fill="#000000">Item</text>
+ <text x="509" y="166" font-family="Courier" font-size="15" stroke="none" fill="#000000">Special</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/html/parallel-plans.html b/doc/src/sgml/html/parallel-plans.html
new file mode 100644
index 0000000..771bac3
--- /dev/null
+++ b/doc/src/sgml/html/parallel-plans.html
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.3. Parallel Plans</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?" /><link rel="next" href="parallel-safety.html" title="15.4. Parallel Safety" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.3. Parallel Plans</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parallel-safety.html" title="15.4. Parallel Safety">Next</a></td></tr></table><hr /></div><div class="sect1" id="PARALLEL-PLANS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.3. Parallel Plans</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-SCANS">15.3.1. Parallel Scans</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-JOINS">15.3.2. Parallel Joins</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-AGGREGATION">15.3.3. Parallel Aggregation</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-APPEND">15.3.4. Parallel Append</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-PLAN-TIPS">15.3.5. Parallel Plan Tips</a></span></dt></dl></div><p>
+ Because each worker executes the parallel portion of the plan to
+ completion, it is not possible to simply take an ordinary query plan
+ and run it using multiple workers. Each worker would produce a full
+ copy of the output result set, so the query would not run any faster
+ than normal but would produce incorrect results. Instead, the parallel
+ portion of the plan must be what is known internally to the query
+ optimizer as a <em class="firstterm">partial plan</em>; that is, it must be constructed
+ so that each process that executes the plan will generate only a
+ subset of the output rows in such a way that each required output row
+ is guaranteed to be generated by exactly one of the cooperating processes.
+ Generally, this means that the scan on the driving table of the query
+ must be a parallel-aware scan.
+ </p><div class="sect2" id="PARALLEL-SCANS"><div class="titlepage"><div><div><h3 class="title">15.3.1. Parallel Scans</h3></div></div></div><p>
+ The following types of parallel-aware table scans are currently supported.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ In a <span class="emphasis"><em>parallel sequential scan</em></span>, the table's blocks will
+ be divided into ranges and shared among the cooperating processes. Each
+ worker process will complete the scanning of its given range of blocks before
+ requesting an additional range of blocks.
+ </p></li><li class="listitem"><p>
+ In a <span class="emphasis"><em>parallel bitmap heap scan</em></span>, one process is chosen
+ as the leader. That process performs a scan of one or more indexes
+ and builds a bitmap indicating which table blocks need to be visited.
+ These blocks are then divided among the cooperating processes as in
+ a parallel sequential scan. In other words, the heap scan is performed
+ in parallel, but the underlying index scan is not.
+ </p></li><li class="listitem"><p>
+ In a <span class="emphasis"><em>parallel index scan</em></span> or <span class="emphasis"><em>parallel index-only
+ scan</em></span>, the cooperating processes take turns reading data from the
+ index. Currently, parallel index scans are supported only for
+ btree indexes. Each process will claim a single index block and will
+ scan and return all tuples referenced by that block; other processes can
+ at the same time be returning tuples from a different index block.
+ The results of a parallel btree scan are returned in sorted order
+ within each worker process.
+ </p></li></ul></div><p>
+
+ Other scan types, such as scans of non-btree indexes, may support
+ parallel scans in the future.
+ </p></div><div class="sect2" id="PARALLEL-JOINS"><div class="titlepage"><div><div><h3 class="title">15.3.2. Parallel Joins</h3></div></div></div><p>
+ Just as in a non-parallel plan, the driving table may be joined to one or
+ more other tables using a nested loop, hash join, or merge join. The
+ inner side of the join may be any kind of non-parallel plan that is
+ otherwise supported by the planner provided that it is safe to run within
+ a parallel worker. Depending on the join type, the inner side may also be
+ a parallel plan.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ In a <span class="emphasis"><em>nested loop join</em></span>, the inner side is always
+ non-parallel. Although it is executed in full, this is efficient if
+ the inner side is an index scan, because the outer tuples and thus
+ the loops that look up values in the index are divided over the
+ cooperating processes.
+ </p></li><li class="listitem"><p>
+ In a <span class="emphasis"><em>merge join</em></span>, the inner side is always
+ a non-parallel plan and therefore executed in full. This may be
+ inefficient, especially if a sort must be performed, because the work
+ and resulting data are duplicated in every cooperating process.
+ </p></li><li class="listitem"><p>
+ In a <span class="emphasis"><em>hash join</em></span> (without the "parallel" prefix),
+ the inner side is executed in full by every cooperating process
+ to build identical copies of the hash table. This may be inefficient
+ if the hash table is large or the plan is expensive. In a
+ <span class="emphasis"><em>parallel hash join</em></span>, the inner side is a
+ <span class="emphasis"><em>parallel hash</em></span> that divides the work of building
+ a shared hash table over the cooperating processes.
+ </p></li></ul></div></div><div class="sect2" id="PARALLEL-AGGREGATION"><div class="titlepage"><div><div><h3 class="title">15.3.3. Parallel Aggregation</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> supports parallel aggregation by aggregating in
+ two stages. First, each process participating in the parallel portion of
+ the query performs an aggregation step, producing a partial result for
+ each group of which that process is aware. This is reflected in the plan
+ as a <code class="literal">Partial Aggregate</code> node. Second, the partial results are
+ transferred to the leader via <code class="literal">Gather</code> or <code class="literal">Gather
+ Merge</code>. Finally, the leader re-aggregates the results across all
+ workers in order to produce the final result. This is reflected in the
+ plan as a <code class="literal">Finalize Aggregate</code> node.
+ </p><p>
+ Because the <code class="literal">Finalize Aggregate</code> node runs on the leader
+ process, queries that produce a relatively large number of groups in
+ comparison to the number of input rows will appear less favorable to the
+ query planner. For example, in the worst-case scenario the number of
+ groups seen by the <code class="literal">Finalize Aggregate</code> node could be as many as
+ the number of input rows that were seen by all worker processes in the
+ <code class="literal">Partial Aggregate</code> stage. For such cases, there is clearly
+ going to be no performance benefit to using parallel aggregation. The
+ query planner takes this into account during the planning process and is
+ unlikely to choose parallel aggregate in this scenario.
+ </p><p>
+ Parallel aggregation is not supported in all situations. Each aggregate
+ must be <a class="link" href="parallel-safety.html" title="15.4. Parallel Safety">safe</a> for parallelism and must
+ have a combine function. If the aggregate has a transition state of type
+ <code class="literal">internal</code>, it must have serialization and deserialization
+ functions. See <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a> for more details.
+ Parallel aggregation is not supported if any aggregate function call
+ contains <code class="literal">DISTINCT</code> or <code class="literal">ORDER BY</code> clause and is also
+ not supported for ordered set aggregates or when the query involves
+ <code class="literal">GROUPING SETS</code>. It can only be used when all joins involved in
+ the query are also part of the parallel portion of the plan.
+ </p></div><div class="sect2" id="PARALLEL-APPEND"><div class="titlepage"><div><div><h3 class="title">15.3.4. Parallel Append</h3></div></div></div><p>
+ Whenever <span class="productname">PostgreSQL</span> needs to combine rows
+ from multiple sources into a single result set, it uses an
+ <code class="literal">Append</code> or <code class="literal">MergeAppend</code> plan node.
+ This commonly happens when implementing <code class="literal">UNION ALL</code> or
+ when scanning a partitioned table. Such nodes can be used in parallel
+ plans just as they can in any other plan. However, in a parallel plan,
+ the planner may instead use a <code class="literal">Parallel Append</code> node.
+ </p><p>
+ When an <code class="literal">Append</code> node is used in a parallel plan, each
+ process will execute the child plans in the order in which they appear,
+ so that all participating processes cooperate to execute the first child
+ plan until it is complete and then move to the second plan at around the
+ same time. When a <code class="literal">Parallel Append</code> is used instead, the
+ executor will instead spread out the participating processes as evenly as
+ possible across its child plans, so that multiple child plans are executed
+ simultaneously. This avoids contention, and also avoids paying the startup
+ cost of a child plan in those processes that never execute it.
+ </p><p>
+ Also, unlike a regular <code class="literal">Append</code> node, which can only have
+ partial children when used within a parallel plan, a <code class="literal">Parallel
+ Append</code> node can have both partial and non-partial child plans.
+ Non-partial children will be scanned by only a single process, since
+ scanning them more than once would produce duplicate results. Plans that
+ involve appending multiple results sets can therefore achieve
+ coarse-grained parallelism even when efficient partial plans are not
+ available. For example, consider a query against a partitioned table
+ that can only be implemented efficiently by using an index that does
+ not support parallel scans. The planner might choose a <code class="literal">Parallel
+ Append</code> of regular <code class="literal">Index Scan</code> plans; each
+ individual index scan would have to be executed to completion by a single
+ process, but different scans could be performed at the same time by
+ different processes.
+ </p><p>
+ <a class="xref" href="runtime-config-query.html#GUC-ENABLE-PARALLEL-APPEND">enable_parallel_append</a> can be used to disable
+ this feature.
+ </p></div><div class="sect2" id="PARALLEL-PLAN-TIPS"><div class="titlepage"><div><div><h3 class="title">15.3.5. Parallel Plan Tips</h3></div></div></div><p>
+ If a query that is expected to do so does not produce a parallel plan,
+ you can try reducing <a class="xref" href="runtime-config-query.html#GUC-PARALLEL-SETUP-COST">parallel_setup_cost</a> or
+ <a class="xref" href="runtime-config-query.html#GUC-PARALLEL-TUPLE-COST">parallel_tuple_cost</a>. Of course, this plan may turn
+ out to be slower than the serial plan that the planner preferred, but
+ this will not always be the case. If you don't get a parallel
+ plan even with very small values of these settings (e.g., after setting
+ them both to zero), there may be some reason why the query planner is
+ unable to generate a parallel plan for your query. See
+ <a class="xref" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?">Section 15.2</a> and
+ <a class="xref" href="parallel-safety.html" title="15.4. Parallel Safety">Section 15.4</a> for information on why this may be
+ the case.
+ </p><p>
+ When executing a parallel plan, you can use <code class="literal">EXPLAIN (ANALYZE,
+ VERBOSE)</code> to display per-worker statistics for each plan node.
+ This may be useful in determining whether the work is being evenly
+ distributed between all plan nodes and more generally in understanding the
+ performance characteristics of the plan.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="when-can-parallel-query-be-used.html" title="15.2. When Can Parallel Query Be Used?">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel-safety.html" title="15.4. Parallel Safety">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.2. When Can Parallel Query Be Used? </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 15.4. Parallel Safety</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/parallel-query.html b/doc/src/sgml/html/parallel-query.html
new file mode 100644
index 0000000..0ae2614
--- /dev/null
+++ b/doc/src/sgml/html/parallel-query.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 15. Parallel Query</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="non-durability.html" title="14.5. Non-Durable Settings" /><link rel="next" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 15. Parallel Query</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="non-durability.html" title="14.5. Non-Durable Settings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Next</a></td></tr></table><hr /></div><div class="chapter" id="PARALLEL-QUERY"><div class="titlepage"><div><div><h2 class="title">Chapter 15. Parallel Query</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="how-parallel-query-works.html">15.1. How Parallel Query Works</a></span></dt><dt><span class="sect1"><a href="when-can-parallel-query-be-used.html">15.2. When Can Parallel Query Be Used?</a></span></dt><dt><span class="sect1"><a href="parallel-plans.html">15.3. Parallel Plans</a></span></dt><dd><dl><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-SCANS">15.3.1. Parallel Scans</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-JOINS">15.3.2. Parallel Joins</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-AGGREGATION">15.3.3. Parallel Aggregation</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-APPEND">15.3.4. Parallel Append</a></span></dt><dt><span class="sect2"><a href="parallel-plans.html#PARALLEL-PLAN-TIPS">15.3.5. Parallel Plan Tips</a></span></dt></dl></dd><dt><span class="sect1"><a href="parallel-safety.html">15.4. Parallel Safety</a></span></dt><dd><dl><dt><span class="sect2"><a href="parallel-safety.html#PARALLEL-LABELING">15.4.1. Parallel Labeling for Functions and Aggregates</a></span></dt></dl></dd></dl></div><a id="id-1.5.14.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> can devise query plans that can leverage
+ multiple CPUs in order to answer queries faster. This feature is known
+ as parallel query. Many queries cannot benefit from parallel query, either
+ due to limitations of the current implementation or because there is no
+ imaginable query plan that is any faster than the serial query plan.
+ However, for queries that can benefit, the speedup from parallel query
+ is often very significant. Many queries can run more than twice as fast
+ when using parallel query, and some queries can run four times faster or
+ even more. Queries that touch a large amount of data but return only a
+ few rows to the user will typically benefit most. This chapter explains
+ some details of how parallel query works and in which situations it can be
+ used so that users who wish to make use of it can understand what to expect.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="non-durability.html" title="14.5. Non-Durable Settings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.5. Non-Durable Settings </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 15.1. How Parallel Query Works</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/parallel-safety.html b/doc/src/sgml/html/parallel-safety.html
new file mode 100644
index 0000000..a7f874b
--- /dev/null
+++ b/doc/src/sgml/html/parallel-safety.html
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.4. Parallel Safety</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="parallel-plans.html" title="15.3. Parallel Plans" /><link rel="next" href="admin.html" title="Part III. Server Administration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.4. Parallel Safety</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="parallel-plans.html" title="15.3. Parallel Plans">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="admin.html" title="Part III. Server Administration">Next</a></td></tr></table><hr /></div><div class="sect1" id="PARALLEL-SAFETY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.4. Parallel Safety</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="parallel-safety.html#PARALLEL-LABELING">15.4.1. Parallel Labeling for Functions and Aggregates</a></span></dt></dl></div><p>
+ The planner classifies operations involved in a query as either
+ <em class="firstterm">parallel safe</em>, <em class="firstterm">parallel restricted</em>,
+ or <em class="firstterm">parallel unsafe</em>. A parallel safe operation is one that
+ does not conflict with the use of parallel query. A parallel restricted
+ operation is one that cannot be performed in a parallel worker, but that
+ can be performed in the leader while parallel query is in use. Therefore,
+ parallel restricted operations can never occur below a <code class="literal">Gather</code>
+ or <code class="literal">Gather Merge</code> node, but can occur elsewhere in a plan that
+ contains such a node. A parallel unsafe operation is one that cannot
+ be performed while parallel query is in use, not even in the leader.
+ When a query contains anything that is parallel unsafe, parallel query
+ is completely disabled for that query.
+ </p><p>
+ The following operations are always parallel restricted:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Scans of common table expressions (CTEs).
+ </p></li><li class="listitem"><p>
+ Scans of temporary tables.
+ </p></li><li class="listitem"><p>
+ Scans of foreign tables, unless the foreign data wrapper has
+ an <code class="literal">IsForeignScanParallelSafe</code> API that indicates otherwise.
+ </p></li><li class="listitem"><p>
+ Plan nodes to which an <code class="literal">InitPlan</code> is attached.
+ </p></li><li class="listitem"><p>
+ Plan nodes that reference a correlated <code class="literal">SubPlan</code>.
+ </p></li></ul></div><div class="sect2" id="PARALLEL-LABELING"><div class="titlepage"><div><div><h3 class="title">15.4.1. Parallel Labeling for Functions and Aggregates</h3></div></div></div><p>
+ The planner cannot automatically determine whether a user-defined
+ function or aggregate is parallel safe, parallel restricted, or parallel
+ unsafe, because this would require predicting every operation that the
+ function could possibly perform. In general, this is equivalent to the
+ Halting Problem and therefore impossible. Even for simple functions
+ where it could conceivably be done, we do not try, since this would be expensive
+ and error-prone. Instead, all user-defined functions are assumed to
+ be parallel unsafe unless otherwise marked. When using
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> or
+ <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, markings can be set by specifying
+ <code class="literal">PARALLEL SAFE</code>, <code class="literal">PARALLEL RESTRICTED</code>, or
+ <code class="literal">PARALLEL UNSAFE</code> as appropriate. When using
+ <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a>, the
+ <code class="literal">PARALLEL</code> option can be specified with <code class="literal">SAFE</code>,
+ <code class="literal">RESTRICTED</code>, or <code class="literal">UNSAFE</code> as the corresponding value.
+ </p><p>
+ Functions and aggregates must be marked <code class="literal">PARALLEL UNSAFE</code> if
+ they write to the database, access sequences, change the transaction state
+ even temporarily (e.g., a PL/pgSQL function that establishes an
+ <code class="literal">EXCEPTION</code> block to catch errors), or make persistent changes to
+ settings. Similarly, functions must be marked <code class="literal">PARALLEL
+ RESTRICTED</code> if they access temporary tables, client connection state,
+ cursors, prepared statements, or miscellaneous backend-local state that
+ the system cannot synchronize across workers. For example,
+ <code class="literal">setseed</code> and <code class="literal">random</code> are parallel restricted for
+ this last reason.
+ </p><p>
+ In general, if a function is labeled as being safe when it is restricted or
+ unsafe, or if it is labeled as being restricted when it is in fact unsafe,
+ it may throw errors or produce wrong answers when used in a parallel query.
+ C-language functions could in theory exhibit totally undefined behavior if
+ mislabeled, since there is no way for the system to protect itself against
+ arbitrary C code, but in most likely cases the result will be no worse than
+ for any other function. If in doubt, it is probably best to label functions
+ as <code class="literal">UNSAFE</code>.
+ </p><p>
+ If a function executed within a parallel worker acquires locks that are
+ not held by the leader, for example by querying a table not referenced in
+ the query, those locks will be released at worker exit, not end of
+ transaction. If you write a function that does this, and this behavior
+ difference is important to you, mark such functions as
+ <code class="literal">PARALLEL RESTRICTED</code>
+ to ensure that they execute only in the leader.
+ </p><p>
+ Note that the query planner does not consider deferring the evaluation of
+ parallel-restricted functions or aggregates involved in the query in
+ order to obtain a superior plan. So, for example, if a <code class="literal">WHERE</code>
+ clause applied to a particular table is parallel restricted, the query
+ planner will not consider performing a scan of that table in the parallel
+ portion of a plan. In some cases, it would be
+ possible (and perhaps even efficient) to include the scan of that table in
+ the parallel portion of the query and defer the evaluation of the
+ <code class="literal">WHERE</code> clause so that it happens above the <code class="literal">Gather</code>
+ node. However, the planner does not do this.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel-plans.html" title="15.3. Parallel Plans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="admin.html" title="Part III. Server Administration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.3. Parallel Plans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part III. Server Administration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/parser-stage.html b/doc/src/sgml/html/parser-stage.html
new file mode 100644
index 0000000..2e41c9a
--- /dev/null
+++ b/doc/src/sgml/html/parser-stage.html
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.3. The Parser Stage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="connect-estab.html" title="52.2. How Connections Are Established" /><link rel="next" href="rule-system.html" title="52.4. The PostgreSQL Rule System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.3. The Parser Stage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="connect-estab.html" title="52.2. How Connections Are Established">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rule-system.html" title="52.4. The PostgreSQL Rule System">Next</a></td></tr></table><hr /></div><div class="sect1" id="PARSER-STAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.3. The Parser Stage</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="parser-stage.html#id-1.10.3.6.3">52.3.1. Parser</a></span></dt><dt><span class="sect2"><a href="parser-stage.html#id-1.10.3.6.4">52.3.2. Transformation Process</a></span></dt></dl></div><p>
+ The <em class="firstterm">parser stage</em> consists of two parts:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The <em class="firstterm">parser</em> defined in
+ <code class="filename">gram.y</code> and <code class="filename">scan.l</code> is
+ built using the Unix tools <span class="application">bison</span>
+ and <span class="application">flex</span>.
+ </p></li><li class="listitem"><p>
+ The <em class="firstterm">transformation process</em> does
+ modifications and augmentations to the data structures returned by the parser.
+ </p></li></ul></div><p>
+ </p><div class="sect2" id="id-1.10.3.6.3"><div class="titlepage"><div><div><h3 class="title">52.3.1. Parser</h3></div></div></div><p>
+ The parser has to check the query string (which arrives as plain
+ text) for valid syntax. If the syntax is correct a
+ <em class="firstterm">parse tree</em> is built up and handed back;
+ otherwise an error is returned. The parser and lexer are
+ implemented using the well-known Unix tools <span class="application">bison</span>
+ and <span class="application">flex</span>.
+ </p><p>
+ The <em class="firstterm">lexer</em> is defined in the file
+ <code class="filename">scan.l</code> and is responsible
+ for recognizing <em class="firstterm">identifiers</em>,
+ the <em class="firstterm">SQL key words</em> etc. For
+ every key word or identifier that is found, a <em class="firstterm">token</em>
+ is generated and handed to the parser.
+ </p><p>
+ The parser is defined in the file <code class="filename">gram.y</code> and
+ consists of a set of <em class="firstterm">grammar rules</em> and
+ <em class="firstterm">actions</em> that are executed whenever a rule
+ is fired. The code of the actions (which is actually C code) is
+ used to build up the parse tree.
+ </p><p>
+ The file <code class="filename">scan.l</code> is transformed to the C
+ source file <code class="filename">scan.c</code> using the program
+ <span class="application">flex</span> and <code class="filename">gram.y</code> is
+ transformed to <code class="filename">gram.c</code> using
+ <span class="application">bison</span>. After these transformations
+ have taken place a normal C compiler can be used to create the
+ parser. Never make any changes to the generated C files as they
+ will be overwritten the next time <span class="application">flex</span>
+ or <span class="application">bison</span> is called.
+
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The mentioned transformations and compilations are normally done
+ automatically using the <em class="firstterm">makefiles</em>
+ shipped with the <span class="productname">PostgreSQL</span>
+ source distribution.
+ </p></div><p>
+ </p><p>
+ A detailed description of <span class="application">bison</span> or
+ the grammar rules given in <code class="filename">gram.y</code> would be
+ beyond the scope of this manual. There are many books and
+ documents dealing with <span class="application">flex</span> and
+ <span class="application">bison</span>. You should be familiar with
+ <span class="application">bison</span> before you start to study the
+ grammar given in <code class="filename">gram.y</code> otherwise you won't
+ understand what happens there.
+ </p></div><div class="sect2" id="id-1.10.3.6.4"><div class="titlepage"><div><div><h3 class="title">52.3.2. Transformation Process</h3></div></div></div><p>
+ The parser stage creates a parse tree using only fixed rules about
+ the syntactic structure of SQL. It does not make any lookups in the
+ system catalogs, so there is no possibility to understand the detailed
+ semantics of the requested operations. After the parser completes,
+ the <em class="firstterm">transformation process</em> takes the tree handed
+ back by the parser as input and does the semantic interpretation needed
+ to understand which tables, functions, and operators are referenced by
+ the query. The data structure that is built to represent this
+ information is called the <em class="firstterm">query tree</em>.
+ </p><p>
+ The reason for separating raw parsing from semantic analysis is that
+ system catalog lookups can only be done within a transaction, and we
+ do not wish to start a transaction immediately upon receiving a query
+ string. The raw parsing stage is sufficient to identify the transaction
+ control commands (<code class="command">BEGIN</code>, <code class="command">ROLLBACK</code>, etc.), and
+ these can then be correctly executed without any further analysis.
+ Once we know that we are dealing with an actual query (such as
+ <code class="command">SELECT</code> or <code class="command">UPDATE</code>), it is okay to
+ start a transaction if we're not already in one. Only then can the
+ transformation process be invoked.
+ </p><p>
+ The query tree created by the transformation process is structurally
+ similar to the raw parse tree in most places, but it has many differences
+ in detail. For example, a <code class="structname">FuncCall</code> node in the
+ parse tree represents something that looks syntactically like a function
+ call. This might be transformed to either a <code class="structname">FuncExpr</code>
+ or <code class="structname">Aggref</code> node depending on whether the referenced
+ name turns out to be an ordinary function or an aggregate function.
+ Also, information about the actual data types of columns and expression
+ results is added to the query tree.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="connect-estab.html" title="52.2. How Connections Are Established">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rule-system.html" title="52.4. The PostgreSQL Rule System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.2. How Connections Are Established </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.4. The <span class="productname">PostgreSQL</span> Rule System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/passwordcheck.html b/doc/src/sgml/html/passwordcheck.html
new file mode 100644
index 0000000..2f86e30
--- /dev/null
+++ b/doc/src/sgml/html/passwordcheck.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.26. passwordcheck</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pageinspect.html" title="F.25. pageinspect" /><link rel="next" href="pgbuffercache.html" title="F.27. pg_buffercache" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.26. passwordcheck</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pageinspect.html" title="F.25. pageinspect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgbuffercache.html" title="F.27. pg_buffercache">Next</a></td></tr></table><hr /></div><div class="sect1" id="PASSWORDCHECK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.26. passwordcheck</h2></div></div></div><a id="id-1.11.7.35.2" class="indexterm"></a><p>
+ The <code class="filename">passwordcheck</code> module checks users' passwords
+ whenever they are set with
+ <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a> or
+ <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>.
+ If a password is considered too weak, it will be rejected and
+ the command will terminate with an error.
+ </p><p>
+ To enable this module, add <code class="literal">'$libdir/passwordcheck'</code>
+ to <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> in
+ <code class="filename">postgresql.conf</code>, then restart the server.
+ </p><p>
+ You can adapt this module to your needs by changing the source code.
+ For example, you can use
+ <a class="ulink" href="https://github.com/cracklib/cracklib" target="_top">CrackLib</a>
+ to check passwords — this only requires uncommenting
+ two lines in the <code class="filename">Makefile</code> and rebuilding the
+ module. (We cannot include <span class="productname">CrackLib</span>
+ by default for license reasons.)
+ Without <span class="productname">CrackLib</span>, the module enforces a few
+ simple rules for password strength, which you can modify or extend
+ as you see fit.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ To prevent unencrypted passwords from being sent across the network,
+ written to the server log or otherwise stolen by a database administrator,
+ <span class="productname">PostgreSQL</span> allows the user to supply
+ pre-encrypted passwords. Many client programs make use of this
+ functionality and encrypt the password before sending it to the server.
+ </p><p>
+ This limits the usefulness of the <code class="filename">passwordcheck</code>
+ module, because in that case it can only try to guess the password.
+ For this reason, <code class="filename">passwordcheck</code> is not
+ recommended if your security requirements are high.
+ It is more secure to use an external authentication method such as GSSAPI
+ (see <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>) than to rely on
+ passwords within the database.
+ </p><p>
+ Alternatively, you could modify <code class="filename">passwordcheck</code>
+ to reject pre-encrypted passwords, but forcing users to set their
+ passwords in clear text carries its own security risks.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pageinspect.html" title="F.25. pageinspect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgbuffercache.html" title="F.27. pg_buffercache">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.25. pageinspect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.27. pg_buffercache</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/performance-tips.html b/doc/src/sgml/html/performance-tips.html
new file mode 100644
index 0000000..b50a10b
--- /dev/null
+++ b/doc/src/sgml/html/performance-tips.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 14. Performance Tips</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="locking-indexes.html" title="13.7. Locking and Indexes" /><link rel="next" href="using-explain.html" title="14.1. Using EXPLAIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 14. Performance Tips</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="locking-indexes.html" title="13.7. Locking and Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="using-explain.html" title="14.1. Using EXPLAIN">Next</a></td></tr></table><hr /></div><div class="chapter" id="PERFORMANCE-TIPS"><div class="titlepage"><div><div><h2 class="title">Chapter 14. Performance Tips</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="using-explain.html">14.1. Using <code class="command">EXPLAIN</code></a></span></dt><dd><dl><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-BASICS">14.1.1. <code class="command">EXPLAIN</code> Basics</a></span></dt><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-ANALYZE">14.1.2. <code class="command">EXPLAIN ANALYZE</code></a></span></dt><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-CAVEATS">14.1.3. Caveats</a></span></dt></dl></dd><dt><span class="sect1"><a href="planner-stats.html">14.2. Statistics Used by the Planner</a></span></dt><dd><dl><dt><span class="sect2"><a href="planner-stats.html#id-1.5.13.5.3">14.2.1. Single-Column Statistics</a></span></dt><dt><span class="sect2"><a href="planner-stats.html#PLANNER-STATS-EXTENDED">14.2.2. Extended Statistics</a></span></dt></dl></dd><dt><span class="sect1"><a href="explicit-joins.html">14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses</a></span></dt><dt><span class="sect1"><a href="populate.html">14.4. Populating a Database</a></span></dt><dd><dl><dt><span class="sect2"><a href="populate.html#DISABLE-AUTOCOMMIT">14.4.1. Disable Autocommit</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-COPY-FROM">14.4.2. Use <code class="command">COPY</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-RM-INDEXES">14.4.3. Remove Indexes</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-RM-FKEYS">14.4.4. Remove Foreign Key Constraints</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-WORK-MEM">14.4.5. Increase <code class="varname">maintenance_work_mem</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-MAX-WAL-SIZE">14.4.6. Increase <code class="varname">max_wal_size</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-PITR">14.4.7. Disable WAL Archival and Streaming Replication</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-ANALYZE">14.4.8. Run <code class="command">ANALYZE</code> Afterwards</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-PG-DUMP">14.4.9. Some Notes about <span class="application">pg_dump</span></a></span></dt></dl></dd><dt><span class="sect1"><a href="non-durability.html">14.5. Non-Durable Settings</a></span></dt></dl></div><a id="id-1.5.13.2" class="indexterm"></a><p>
+ Query performance can be affected by many things. Some of these can
+ be controlled by the user, while others are fundamental to the underlying
+ design of the system. This chapter provides some hints about understanding
+ and tuning <span class="productname">PostgreSQL</span> performance.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="locking-indexes.html" title="13.7. Locking and Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using-explain.html" title="14.1. Using EXPLAIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.7. Locking and Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 14.1. Using <code class="command">EXPLAIN</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/perm-functions.html b/doc/src/sgml/html/perm-functions.html
new file mode 100644
index 0000000..4cb60f0
--- /dev/null
+++ b/doc/src/sgml/html/perm-functions.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.6. Function Security</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="predefined-roles.html" title="22.5. Predefined Roles" /><link rel="next" href="managing-databases.html" title="Chapter 23. Managing Databases" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.6. Function Security</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="predefined-roles.html" title="22.5. Predefined Roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="managing-databases.html" title="Chapter 23. Managing Databases">Next</a></td></tr></table><hr /></div><div class="sect1" id="PERM-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.6. Function Security</h2></div></div></div><p>
+ Functions, triggers and row-level security policies allow users to insert
+ code into the backend server that other users might execute
+ unintentionally. Hence, these mechanisms permit users to <span class="quote">“<span class="quote">Trojan
+ horse</span>”</span> others with relative ease. The strongest protection is tight
+ control over who can define objects. Where that is infeasible, write
+ queries referring only to objects having trusted owners. Remove
+ from <code class="varname">search_path</code> any schemas that permit untrusted users
+ to create objects.
+ </p><p>
+ Functions run inside the backend
+ server process with the operating system permissions of the
+ database server daemon. If the programming language
+ used for the function allows unchecked memory accesses, it is
+ possible to change the server's internal data structures.
+ Hence, among many other things, such functions can circumvent any
+ system access controls. Function languages that allow such access
+ are considered <span class="quote">“<span class="quote">untrusted</span>”</span>, and
+ <span class="productname">PostgreSQL</span> allows only superusers to
+ create functions written in those languages.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="predefined-roles.html" title="22.5. Predefined Roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="managing-databases.html" title="Chapter 23. Managing Databases">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.5. Predefined Roles </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 23. Managing Databases</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgarchivecleanup.html b/doc/src/sgml/html/pgarchivecleanup.html
new file mode 100644
index 0000000..c96ee74
--- /dev/null
+++ b/doc/src/sgml/html/pgarchivecleanup.html
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_archivecleanup</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-initdb.html" title="initdb" /><link rel="next" href="app-pgchecksums.html" title="pg_checksums" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_archivecleanup</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-initdb.html" title="initdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgchecksums.html" title="pg_checksums">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGARCHIVECLEANUP"><div class="titlepage"></div><a id="id-1.9.5.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_archivecleanup</span></span></h2><p>pg_archivecleanup — clean up <span class="productname">PostgreSQL</span> WAL archive files</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.4.4.1"><code class="command">pg_archivecleanup</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>archivelocation</code></em> <em class="replaceable"><code>oldestkeptwalfile</code></em> </p></div></div><div class="refsect1" id="id-1.9.5.4.5"><h2>Description</h2><p>
+ <span class="application">pg_archivecleanup</span> is designed to be used as an
+ <code class="literal">archive_cleanup_command</code> to clean up WAL file archives when
+ running as a standby server (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
+ <span class="application">pg_archivecleanup</span> can also be used as a standalone program to
+ clean WAL file archives.
+ </p><p>
+ To configure a standby
+ server to use <span class="application">pg_archivecleanup</span>, put this into its
+ <code class="filename">postgresql.conf</code> configuration file:
+</p><pre class="programlisting">
+archive_cleanup_command = 'pg_archivecleanup <em class="replaceable"><code>archivelocation</code></em> %r'
+</pre><p>
+ where <em class="replaceable"><code>archivelocation</code></em> is the directory from which WAL segment
+ files should be removed.
+ </p><p>
+ When used within <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-COMMAND">archive_cleanup_command</a>, all WAL files
+ logically preceding the value of the <code class="literal">%r</code> argument will be removed
+ from <em class="replaceable"><code>archivelocation</code></em>. This minimizes the number of files
+ that need to be retained, while preserving crash-restart capability. Use of
+ this parameter is appropriate if the <em class="replaceable"><code>archivelocation</code></em> is a
+ transient staging area for this particular standby server, but
+ <span class="emphasis"><em>not</em></span> when the <em class="replaceable"><code>archivelocation</code></em> is intended as a
+ long-term WAL archive area, or when multiple standby servers are recovering
+ from the same archive location.
+ </p><p>
+ When used as a standalone program all WAL files logically preceding the
+ <em class="replaceable"><code>oldestkeptwalfile</code></em> will be removed from <em class="replaceable"><code>archivelocation</code></em>.
+ In this mode, if you specify a <code class="filename">.partial</code> or <code class="filename">.backup</code>
+ file name, then only the file prefix will be used as the
+ <em class="replaceable"><code>oldestkeptwalfile</code></em>. This treatment of <code class="filename">.backup</code>
+ file name allows you to remove
+ all WAL files archived prior to a specific base backup without error.
+ For example, the following example will remove all files older than
+ WAL file name <code class="filename">000000010000003700000010</code>:
+</p><pre class="programlisting">
+pg_archivecleanup -d archive 000000010000003700000010.00000020.backup
+
+pg_archivecleanup: keep WAL file "archive/000000010000003700000010" and later
+pg_archivecleanup: removing file "archive/00000001000000370000000F"
+pg_archivecleanup: removing file "archive/00000001000000370000000E"
+</pre><p>
+ </p><p>
+ <span class="application">pg_archivecleanup</span> assumes that
+ <em class="replaceable"><code>archivelocation</code></em> is a directory readable and writable by the
+ server-owning user.
+ </p></div><div class="refsect1" id="id-1.9.5.4.6"><h2>Options</h2><p>
+ <span class="application">pg_archivecleanup</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d</code></span></dt><dd><p>
+ Print lots of debug logging output on <code class="filename">stderr</code>.
+ </p></dd><dt><span class="term"><code class="option">-n</code></span></dt><dd><p>
+ Print the names of the files that would have been removed on <code class="filename">stdout</code> (performs a dry run).
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_archivecleanup</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-x</code> <em class="replaceable"><code>extension</code></em></span></dt><dd><p>
+ Provide an extension
+ that will be stripped from all file names before deciding if they
+ should be deleted. This is typically useful for cleaning up archives
+ that have been compressed during storage, and therefore have had an
+ extension added by the compression program. For example: <code class="literal">-x
+ .gz</code>.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_archivecleanup</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.4.7"><h2>Environment</h2><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.4.8"><h2>Notes</h2><p>
+ <span class="application">pg_archivecleanup</span> is designed to work with
+ <span class="productname">PostgreSQL</span> 8.0 and later when used as a standalone utility,
+ or with <span class="productname">PostgreSQL</span> 9.0 and later when used as an
+ archive cleanup command.
+ </p><p>
+ <span class="application">pg_archivecleanup</span> is written in C and has an
+ easy-to-modify source code, with specifically designated sections to modify
+ for your own needs
+ </p></div><div class="refsect1" id="id-1.9.5.4.9"><h2>Examples</h2><p>On Linux or Unix systems, you might use:
+</p><pre class="programlisting">
+archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2&gt;&gt;cleanup.log'
+</pre><p>
+ where the archive directory is physically located on the standby server,
+ so that the <code class="varname">archive_command</code> is accessing it across NFS,
+ but the files are local to the standby.
+ This will:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ produce debugging output in <code class="filename">cleanup.log</code>
+ </p></li><li class="listitem"><p>
+ remove no-longer-needed files from the archive directory
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-initdb.html" title="initdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgchecksums.html" title="pg_checksums">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">initdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_checksums</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgbench.html b/doc/src/sgml/html/pgbench.html
new file mode 100644
index 0000000..a7386e0
--- /dev/null
+++ b/doc/src/sgml/html/pgbench.html
@@ -0,0 +1,1721 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pgbench</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgbasebackup.html" title="pg_basebackup" /><link rel="next" href="app-pgconfig.html" title="pg_config" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pgbench</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgbasebackup.html" title="pg_basebackup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgconfig.html" title="pg_config">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGBENCH"><div class="titlepage"></div><a id="id-1.9.4.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pgbench</span></span></h2><p>pgbench — run a benchmark test on <span class="productname">PostgreSQL</span></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.11.4.1"><code class="command">pgbench</code> <code class="option">-i</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div><div class="cmdsynopsis"><p id="id-1.9.4.11.4.2"><code class="command">pgbench</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.11.5"><h2>Description</h2><p>
+ <span class="application">pgbench</span> is a simple program for running benchmark
+ tests on <span class="productname">PostgreSQL</span>. It runs the same sequence of SQL
+ commands over and over, possibly in multiple concurrent database sessions,
+ and then calculates the average transaction rate (transactions per second).
+ By default, <span class="application">pgbench</span> tests a scenario that is
+ loosely based on TPC-B, involving five <code class="command">SELECT</code>,
+ <code class="command">UPDATE</code>, and <code class="command">INSERT</code> commands per transaction.
+ However, it is easy to test other cases by writing your own transaction
+ script files.
+ </p><p>
+ Typical output from <span class="application">pgbench</span> looks like:
+
+</p><pre class="screen">
+transaction type: &lt;builtin: TPC-B (sort of)&gt;
+scaling factor: 10
+query mode: simple
+number of clients: 10
+number of threads: 1
+maximum number of tries: 1
+number of transactions per client: 1000
+number of transactions actually processed: 10000/10000
+number of failed transactions: 0 (0.000%)
+latency average = 11.013 ms
+latency stddev = 7.351 ms
+initial connection time = 45.758 ms
+tps = 896.967014 (without initial connection time)
+</pre><p>
+
+ The first seven lines report some of the most important parameter
+ settings.
+ The sixth line reports the maximum number of tries for transactions with
+ serialization or deadlock errors (see <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>
+ for more information).
+ The eighth line reports the number of transactions completed
+ and intended (the latter being just the product of number of clients
+ and number of transactions per client); these will be equal unless the run
+ failed before completion or some SQL command(s) failed. (In
+ <code class="option">-T</code> mode, only the actual number of transactions is printed.)
+ The next line reports the number of failed transactions due to
+ serialization or deadlock errors (see <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>
+ for more information).
+ The last line reports the number of transactions per second.
+ </p><p>
+ The default TPC-B-like transaction test requires specific tables to be
+ set up beforehand. <span class="application">pgbench</span> should be invoked with
+ the <code class="option">-i</code> (initialize) option to create and populate these
+ tables. (When you are testing a custom script, you don't need this
+ step, but will instead need to do whatever setup your test needs.)
+ Initialization looks like:
+
+</p><pre class="programlisting">
+pgbench -i [<span class="optional"> <em class="replaceable"><code>other-options</code></em> </span>] <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ where <em class="replaceable"><code>dbname</code></em> is the name of the already-created
+ database to test in. (You may also need <code class="option">-h</code>,
+ <code class="option">-p</code>, and/or <code class="option">-U</code> options to specify how to
+ connect to the database server.)
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ <code class="literal">pgbench -i</code> creates four tables <code class="structname">pgbench_accounts</code>,
+ <code class="structname">pgbench_branches</code>, <code class="structname">pgbench_history</code>, and
+ <code class="structname">pgbench_tellers</code>,
+ destroying any existing tables of these names.
+ Be very careful to use another database if you have tables having these
+ names!
+ </p></div><p>
+ At the default <span class="quote">“<span class="quote">scale factor</span>”</span> of 1, the tables initially
+ contain this many rows:
+</p><pre class="screen">
+table # of rows
+---------------------------------
+pgbench_branches 1
+pgbench_tellers 10
+pgbench_accounts 100000
+pgbench_history 0
+</pre><p>
+ You can (and, for most purposes, probably should) increase the number
+ of rows by using the <code class="option">-s</code> (scale factor) option. The
+ <code class="option">-F</code> (fillfactor) option might also be used at this point.
+ </p><p>
+ Once you have done the necessary setup, you can run your benchmark
+ with a command that doesn't include <code class="option">-i</code>, that is
+
+</p><pre class="programlisting">
+pgbench [<span class="optional"> <em class="replaceable"><code>options</code></em> </span>] <em class="replaceable"><code>dbname</code></em>
+</pre><p>
+
+ In nearly all cases, you'll need some options to make a useful test.
+ The most important options are <code class="option">-c</code> (number of clients),
+ <code class="option">-t</code> (number of transactions), <code class="option">-T</code> (time limit),
+ and <code class="option">-f</code> (specify a custom script file).
+ See below for a full list.
+ </p></div><div class="refsect1" id="id-1.9.4.11.6"><h2>Options</h2><p>
+ The following is divided into three subsections. Different options are
+ used during database initialization and while running benchmarks, but some
+ options are useful in both cases.
+ </p><div class="refsect2" id="PGBENCH-INIT-OPTIONS"><h3>Initialization Options</h3><p>
+ <span class="application">pgbench</span> accepts the following command-line
+ initialization arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
+ Specifies the name of the database to test in. If this is
+ not specified, the environment variable
+ <code class="envar">PGDATABASE</code> is used. If that is not set, the
+ user name specified for the connection is used.
+ </p></dd><dt><span class="term"><code class="option">-i</code><br /></span><span class="term"><code class="option">--initialize</code></span></dt><dd><p>
+ Required to invoke initialization mode.
+ </p></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>init_steps</code></em></code><br /></span><span class="term"><code class="option">--init-steps=<em class="replaceable"><code>init_steps</code></em></code></span></dt><dd><p>
+ Perform just a selected set of the normal initialization steps.
+ <em class="replaceable"><code>init_steps</code></em> specifies the
+ initialization steps to be performed, using one character per step.
+ Each step is invoked in the specified order.
+ The default is <code class="literal">dtgvp</code>.
+ The available steps are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">d</code> (Drop)</span></dt><dd><p>
+ Drop any existing <span class="application">pgbench</span> tables.
+ </p></dd><dt><span class="term"><code class="literal">t</code> (create Tables)</span></dt><dd><p>
+ Create the tables used by the
+ standard <span class="application">pgbench</span> scenario, namely
+ <code class="structname">pgbench_accounts</code>,
+ <code class="structname">pgbench_branches</code>,
+ <code class="structname">pgbench_history</code>, and
+ <code class="structname">pgbench_tellers</code>.
+ </p></dd><dt><span class="term"><code class="literal">g</code> or <code class="literal">G</code> (Generate data, client-side or server-side)</span></dt><dd><p>
+ Generate data and load it into the standard tables,
+ replacing any data already present.
+ </p><p>
+ With <code class="literal">g</code> (client-side data generation),
+ data is generated in <code class="command">pgbench</code> client and then
+ sent to the server. This uses the client/server bandwidth
+ extensively through a <code class="command">COPY</code>.
+ <code class="command">pgbench</code> uses the FREEZE option with version 14 or later
+ of <span class="productname">PostgreSQL</span> to speed up
+ subsequent <code class="command">VACUUM</code>, unless partitions are enabled.
+ Using <code class="literal">g</code> causes logging to print one message
+ every 100,000 rows while generating data for the
+ <code class="structname">pgbench_accounts</code> table.
+ </p><p>
+ With <code class="literal">G</code> (server-side data generation),
+ only small queries are sent from the <code class="command">pgbench</code>
+ client and then data is actually generated in the server.
+ No significant bandwidth is required for this variant, but
+ the server will do more work.
+ Using <code class="literal">G</code> causes logging not to print any progress
+ message while generating data.
+ </p><p>
+ The default initialization behavior uses client-side data
+ generation (equivalent to <code class="literal">g</code>).
+ </p></dd><dt><span class="term"><code class="literal">v</code> (Vacuum)</span></dt><dd><p>
+ Invoke <code class="command">VACUUM</code> on the standard tables.
+ </p></dd><dt><span class="term"><code class="literal">p</code> (create Primary keys)</span></dt><dd><p>
+ Create primary key indexes on the standard tables.
+ </p></dd><dt><span class="term"><code class="literal">f</code> (create Foreign keys)</span></dt><dd><p>
+ Create foreign key constraints between the standard tables.
+ (Note that this step is not performed by default.)
+ </p></dd></dl></div></dd><dt><span class="term"><code class="option">-F</code> <em class="replaceable"><code>fillfactor</code></em><br /></span><span class="term"><code class="option">--fillfactor=</code><em class="replaceable"><code>fillfactor</code></em></span></dt><dd><p>
+ Create the <code class="structname">pgbench_accounts</code>,
+ <code class="structname">pgbench_tellers</code> and
+ <code class="structname">pgbench_branches</code> tables with the given fillfactor.
+ Default is 100.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-vacuum</code></span></dt><dd><p>
+ Perform no vacuuming during initialization.
+ (This option suppresses the <code class="literal">v</code> initialization step,
+ even if it was specified in <code class="option">-I</code>.)
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Switch logging to quiet mode, producing only one progress message per 5
+ seconds. The default logging prints one message each 100,000 rows, which
+ often outputs many lines per second (especially on good hardware).
+ </p><p>
+ This setting has no effect if <code class="literal">G</code> is specified
+ in <code class="option">-I</code>.
+ </p></dd><dt><span class="term"><code class="option">-s</code> <em class="replaceable"><code>scale_factor</code></em><br /></span><span class="term"><code class="option">--scale=</code><em class="replaceable"><code>scale_factor</code></em></span></dt><dd><p>
+ Multiply the number of rows generated by the scale factor.
+ For example, <code class="literal">-s 100</code> will create 10,000,000 rows
+ in the <code class="structname">pgbench_accounts</code> table. Default is 1.
+ When the scale is 20,000 or larger, the columns used to
+ hold account identifiers (<code class="structfield">aid</code> columns)
+ will switch to using larger integers (<code class="type">bigint</code>),
+ in order to be big enough to hold the range of account
+ identifiers.
+ </p></dd><dt><span class="term"><code class="option">--foreign-keys</code></span></dt><dd><p>
+ Create foreign key constraints between the standard tables.
+ (This option adds the <code class="literal">f</code> step to the initialization
+ step sequence, if it is not already present.)
+ </p></dd><dt><span class="term"><code class="option">--index-tablespace=<em class="replaceable"><code>index_tablespace</code></em></code></span></dt><dd><p>
+ Create indexes in the specified tablespace, rather than the default
+ tablespace.
+ </p></dd><dt><span class="term"><code class="option">--partition-method=<em class="replaceable"><code>NAME</code></em></code></span></dt><dd><p>
+ Create a partitioned <code class="literal">pgbench_accounts</code> table with
+ <em class="replaceable"><code>NAME</code></em> method.
+ Expected values are <code class="literal">range</code> or <code class="literal">hash</code>.
+ This option requires that <code class="option">--partitions</code> is set to non-zero.
+ If unspecified, default is <code class="literal">range</code>.
+ </p></dd><dt><span class="term"><code class="option">--partitions=<em class="replaceable"><code>NUM</code></em></code></span></dt><dd><p>
+ Create a partitioned <code class="literal">pgbench_accounts</code> table with
+ <em class="replaceable"><code>NUM</code></em> partitions of nearly equal size for
+ the scaled number of accounts.
+ Default is <code class="literal">0</code>, meaning no partitioning.
+ </p></dd><dt><span class="term"><code class="option">--tablespace=<em class="replaceable"><code>tablespace</code></em></code></span></dt><dd><p>
+ Create tables in the specified tablespace, rather than the default
+ tablespace.
+ </p></dd><dt><span class="term"><code class="option">--unlogged-tables</code></span></dt><dd><p>
+ Create all tables as unlogged tables, rather than permanent tables.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect2" id="PGBENCH-RUN-OPTIONS"><h3>Benchmarking Options</h3><p>
+ <span class="application">pgbench</span> accepts the following command-line
+ benchmarking arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-b</code> <em class="replaceable"><code>scriptname[@weight]</code></em><br /></span><span class="term"><code class="option">--builtin</code>=<em class="replaceable"><code>scriptname[@weight]</code></em></span></dt><dd><p>
+ Add the specified built-in script to the list of scripts to be executed.
+ Available built-in scripts are: <code class="literal">tpcb-like</code>,
+ <code class="literal">simple-update</code> and <code class="literal">select-only</code>.
+ Unambiguous prefixes of built-in names are accepted.
+ With the special name <code class="literal">list</code>, show the list of built-in scripts
+ and exit immediately.
+ </p><p>
+ Optionally, write an integer weight after <code class="literal">@</code> to
+ adjust the probability of selecting this script versus other ones.
+ The default weight is 1.
+ See below for details.
+ </p></dd><dt><span class="term"><code class="option">-c</code> <em class="replaceable"><code>clients</code></em><br /></span><span class="term"><code class="option">--client=</code><em class="replaceable"><code>clients</code></em></span></dt><dd><p>
+ Number of clients simulated, that is, number of concurrent database
+ sessions. Default is 1.
+ </p></dd><dt><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--connect</code></span></dt><dd><p>
+ Establish a new connection for each transaction, rather than
+ doing it just once per client session.
+ This is useful to measure the connection overhead.
+ </p></dd><dt><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--debug</code></span></dt><dd><p>
+ Print debugging output.
+ </p></dd><dt><span class="term"><code class="option">-D</code> <em class="replaceable"><code>varname</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em><br /></span><span class="term"><code class="option">--define=</code><em class="replaceable"><code>varname</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ Define a variable for use by a custom script (see below).
+ Multiple <code class="option">-D</code> options are allowed.
+ </p></dd><dt><span class="term"><code class="option">-f</code> <em class="replaceable"><code>filename[@weight]</code></em><br /></span><span class="term"><code class="option">--file=</code><em class="replaceable"><code>filename[@weight]</code></em></span></dt><dd><p>
+ Add a transaction script read from <em class="replaceable"><code>filename</code></em>
+ to the list of scripts to be executed.
+ </p><p>
+ Optionally, write an integer weight after <code class="literal">@</code> to
+ adjust the probability of selecting this script versus other ones.
+ The default weight is 1.
+ (To use a script file name that includes an <code class="literal">@</code>
+ character, append a weight so that there is no ambiguity, for
+ example <code class="literal">filen@me@1</code>.)
+ See below for details.
+ </p></dd><dt><span class="term"><code class="option">-j</code> <em class="replaceable"><code>threads</code></em><br /></span><span class="term"><code class="option">--jobs=</code><em class="replaceable"><code>threads</code></em></span></dt><dd><p>
+ Number of worker threads within <span class="application">pgbench</span>.
+ Using more than one thread can be helpful on multi-CPU machines.
+ Clients are distributed as evenly as possible among available threads.
+ Default is 1.
+ </p></dd><dt><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--log</code></span></dt><dd><p>
+ Write information about each transaction to a log file.
+ See below for details.
+ </p></dd><dt><span class="term"><code class="option">-L</code> <em class="replaceable"><code>limit</code></em><br /></span><span class="term"><code class="option">--latency-limit=</code><em class="replaceable"><code>limit</code></em></span></dt><dd><p>
+ Transactions that last more than <em class="replaceable"><code>limit</code></em> milliseconds
+ are counted and reported separately, as <em class="firstterm">late</em>.
+ </p><p>
+ When throttling is used (<code class="option">--rate=...</code>), transactions that
+ lag behind schedule by more than <em class="replaceable"><code>limit</code></em> ms, and thus
+ have no hope of meeting the latency limit, are not sent to the server
+ at all. They are counted and reported separately as
+ <em class="firstterm">skipped</em>.
+ </p><p>
+ When the <code class="option">--max-tries</code> option is used, a transaction
+ which fails due to a serialization anomaly or from a deadlock will not
+ be retried if the total time of all its tries is greater than
+ <em class="replaceable"><code>limit</code></em> ms. To limit only the time of tries
+ and not their number, use <code class="literal">--max-tries=0</code>. By
+ default, the option <code class="option">--max-tries</code> is set to 1 and
+ transactions with serialization/deadlock errors are not retried. See
+ <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information about
+ retrying such transactions.
+ </p></dd><dt><span class="term"><code class="option">-M</code> <em class="replaceable"><code>querymode</code></em><br /></span><span class="term"><code class="option">--protocol=</code><em class="replaceable"><code>querymode</code></em></span></dt><dd><p>
+ Protocol to use for submitting queries to the server:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">simple</code>: use simple query protocol.</p></li><li class="listitem"><p><code class="literal">extended</code>: use extended query protocol.</p></li><li class="listitem"><p><code class="literal">prepared</code>: use extended query protocol with prepared statements.</p></li></ul></div><p>
+
+ In the <code class="literal">prepared</code> mode, <span class="application">pgbench</span>
+ reuses the parse analysis result starting from the second query
+ iteration, so <span class="application">pgbench</span> runs faster
+ than in other modes.
+ </p><p>
+ The default is simple query protocol. (See <a class="xref" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Chapter 55</a>
+ for more information.)
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-vacuum</code></span></dt><dd><p>
+ Perform no vacuuming before running the test.
+ This option is <span class="emphasis"><em>necessary</em></span>
+ if you are running a custom test scenario that does not include
+ the standard tables <code class="structname">pgbench_accounts</code>,
+ <code class="structname">pgbench_branches</code>, <code class="structname">pgbench_history</code>, and
+ <code class="structname">pgbench_tellers</code>.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--skip-some-updates</code></span></dt><dd><p>
+ Run built-in simple-update script.
+ Shorthand for <code class="option">-b simple-update</code>.
+ </p></dd><dt><span class="term"><code class="option">-P</code> <em class="replaceable"><code>sec</code></em><br /></span><span class="term"><code class="option">--progress=</code><em class="replaceable"><code>sec</code></em></span></dt><dd><p>
+ Show progress report every <em class="replaceable"><code>sec</code></em> seconds. The report
+ includes the time since the beginning of the run, the TPS since the
+ last report, and the transaction latency average, standard deviation,
+ and the number of failed transactions since the last report. Under
+ throttling (<code class="option">-R</code>), the latency is computed with respect
+ to the transaction scheduled start time, not the actual transaction
+ beginning time, thus it also includes the average schedule lag time.
+ When <code class="option">--max-tries</code> is used to enable transaction retries
+ after serialization/deadlock errors, the report includes the number of
+ retried transactions and the sum of all retries.
+ </p></dd><dt><span class="term"><code class="option">-r</code><br /></span><span class="term"><code class="option">--report-per-command</code></span></dt><dd><p>
+ Report the following statistics for each command after the benchmark
+ finishes: the average per-statement latency (execution time from the
+ perspective of the client), the number of failures, and the number of
+ retries after serialization or deadlock errors in this command. The
+ report displays retry statistics only if the
+ <code class="option">--max-tries</code> option is not equal to 1.
+ </p></dd><dt><span class="term"><code class="option">-R</code> <em class="replaceable"><code>rate</code></em><br /></span><span class="term"><code class="option">--rate=</code><em class="replaceable"><code>rate</code></em></span></dt><dd><p>
+ Execute transactions targeting the specified rate instead of running
+ as fast as possible (the default). The rate is given in transactions
+ per second. If the targeted rate is above the maximum possible rate,
+ the rate limit won't impact the results.
+ </p><p>
+ The rate is targeted by starting transactions along a
+ Poisson-distributed schedule time line. The expected start time
+ schedule moves forward based on when the client first started, not
+ when the previous transaction ended. That approach means that when
+ transactions go past their original scheduled end time, it is
+ possible for later ones to catch up again.
+ </p><p>
+ When throttling is active, the transaction latency reported at the
+ end of the run is calculated from the scheduled start times, so it
+ includes the time each transaction had to wait for the previous
+ transaction to finish. The wait time is called the schedule lag time,
+ and its average and maximum are also reported separately. The
+ transaction latency with respect to the actual transaction start time,
+ i.e., the time spent executing the transaction in the database, can be
+ computed by subtracting the schedule lag time from the reported
+ latency.
+ </p><p>
+ If <code class="option">--latency-limit</code> is used together with <code class="option">--rate</code>,
+ a transaction can lag behind so much that it is already over the
+ latency limit when the previous transaction ends, because the latency
+ is calculated from the scheduled start time. Such transactions are
+ not sent to the server, but are skipped altogether and counted
+ separately.
+ </p><p>
+ A high schedule lag time is an indication that the system cannot
+ process transactions at the specified rate, with the chosen number of
+ clients and threads. When the average transaction execution time is
+ longer than the scheduled interval between each transaction, each
+ successive transaction will fall further behind, and the schedule lag
+ time will keep increasing the longer the test run is. When that
+ happens, you will have to reduce the specified transaction rate.
+ </p></dd><dt><span class="term"><code class="option">-s</code> <em class="replaceable"><code>scale_factor</code></em><br /></span><span class="term"><code class="option">--scale=</code><em class="replaceable"><code>scale_factor</code></em></span></dt><dd><p>
+ Report the specified scale factor in <span class="application">pgbench</span>'s
+ output. With the built-in tests, this is not necessary; the
+ correct scale factor will be detected by counting the number of
+ rows in the <code class="structname">pgbench_branches</code> table.
+ However, when testing only custom benchmarks (<code class="option">-f</code> option),
+ the scale factor will be reported as 1 unless this option is used.
+ </p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--select-only</code></span></dt><dd><p>
+ Run built-in select-only script.
+ Shorthand for <code class="option">-b select-only</code>.
+ </p></dd><dt><span class="term"><code class="option">-t</code> <em class="replaceable"><code>transactions</code></em><br /></span><span class="term"><code class="option">--transactions=</code><em class="replaceable"><code>transactions</code></em></span></dt><dd><p>
+ Number of transactions each client runs. Default is 10.
+ </p></dd><dt><span class="term"><code class="option">-T</code> <em class="replaceable"><code>seconds</code></em><br /></span><span class="term"><code class="option">--time=</code><em class="replaceable"><code>seconds</code></em></span></dt><dd><p>
+ Run the test for this many seconds, rather than a fixed number of
+ transactions per client. <code class="option">-t</code> and
+ <code class="option">-T</code> are mutually exclusive.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--vacuum-all</code></span></dt><dd><p>
+ Vacuum all four standard tables before running the test.
+ With neither <code class="option">-n</code> nor <code class="option">-v</code>, <span class="application">pgbench</span> will vacuum the
+ <code class="structname">pgbench_tellers</code> and <code class="structname">pgbench_branches</code>
+ tables, and will truncate <code class="structname">pgbench_history</code>.
+ </p></dd><dt><span class="term"><code class="option">--aggregate-interval=<em class="replaceable"><code>seconds</code></em></code></span></dt><dd><p>
+ Length of aggregation interval (in seconds). May be used only
+ with <code class="option">-l</code> option. With this option, the log contains
+ per-interval summary data, as described below.
+ </p></dd><dt><span class="term"><code class="option">--failures-detailed</code></span></dt><dd><p>
+ Report failures in per-transaction and aggregation logs, as well as in
+ the main and per-script reports, grouped by the following types:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>serialization failures;</p></li><li class="listitem"><p>deadlock failures;</p></li></ul></div><p>
+ See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.
+ </p></dd><dt><span class="term"><code class="option">--log-prefix=<em class="replaceable"><code>prefix</code></em></code></span></dt><dd><p>
+ Set the filename prefix for the log files created by
+ <code class="option">--log</code>. The default is <code class="literal">pgbench_log</code>.
+ </p></dd><dt><span class="term"><code class="option">--max-tries=<em class="replaceable"><code>number_of_tries</code></em></code></span></dt><dd><p>
+ Enable retries for transactions with serialization/deadlock errors and
+ set the maximum number of these tries. This option can be combined with
+ the <code class="option">--latency-limit</code> option which limits the total time
+ of all transaction tries; moreover, you cannot use an unlimited number
+ of tries (<code class="literal">--max-tries=0</code>) without
+ <code class="option">--latency-limit</code> or <code class="option">--time</code>.
+ The default value is 1 and transactions with serialization/deadlock
+ errors are not retried. See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a>
+ for more information about retrying such transactions.
+ </p></dd><dt><span class="term"><code class="option">--progress-timestamp</code></span></dt><dd><p>
+ When showing progress (option <code class="option">-P</code>), use a timestamp
+ (Unix epoch) instead of the number of seconds since the
+ beginning of the run. The unit is in seconds, with millisecond
+ precision after the dot.
+ This helps compare logs generated by various tools.
+ </p></dd><dt><span class="term"><code class="option">--random-seed=</code><em class="replaceable"><code>seed</code></em></span></dt><dd><p>
+ Set random generator seed. Seeds the system random number generator,
+ which then produces a sequence of initial generator states, one for
+ each thread.
+ Values for <em class="replaceable"><code>seed</code></em> may be:
+ <code class="literal">time</code> (the default, the seed is based on the current time),
+ <code class="literal">rand</code> (use a strong random source, failing if none
+ is available), or an unsigned decimal integer value.
+ The random generator is invoked explicitly from a pgbench script
+ (<code class="literal">random...</code> functions) or implicitly (for instance option
+ <code class="option">--rate</code> uses it to schedule transactions).
+ When explicitly set, the value used for seeding is shown on the terminal.
+ Any value allowed for <em class="replaceable"><code>seed</code></em> may also be
+ provided through the environment variable
+ <code class="literal">PGBENCH_RANDOM_SEED</code>.
+ To ensure that the provided seed impacts all possible uses, put this option
+ first or use the environment variable.
+ </p><p>
+ Setting the seed explicitly allows to reproduce a <code class="command">pgbench</code>
+ run exactly, as far as random numbers are concerned.
+ As the random state is managed per thread, this means the exact same
+ <code class="command">pgbench</code> run for an identical invocation if there is one
+ client per thread and there are no external or data dependencies.
+ From a statistical viewpoint reproducing runs exactly is a bad idea because
+ it can hide the performance variability or improve performance unduly,
+ e.g., by hitting the same pages as a previous run.
+ However, it may also be of great help for debugging, for instance
+ re-running a tricky case which leads to an error.
+ Use wisely.
+ </p></dd><dt><span class="term"><code class="option">--sampling-rate=<em class="replaceable"><code>rate</code></em></code></span></dt><dd><p>
+ Sampling rate, used when writing data into the log, to reduce the
+ amount of log generated. If this option is given, only the specified
+ fraction of transactions are logged. 1.0 means all transactions will
+ be logged, 0.05 means only 5% of the transactions will be logged.
+ </p><p>
+ Remember to take the sampling rate into account when processing the
+ log file. For example, when computing TPS values, you need to multiply
+ the numbers accordingly (e.g., with 0.01 sample rate, you'll only get
+ 1/100 of the actual TPS).
+ </p></dd><dt><span class="term"><code class="option">--show-script=</code><em class="replaceable"><code>scriptname</code></em></span></dt><dd><p>
+ Show the actual code of builtin script <em class="replaceable"><code>scriptname</code></em>
+ on stderr, and exit immediately.
+ </p></dd><dt><span class="term"><code class="option">--verbose-errors</code></span></dt><dd><p>
+ Print messages about all errors and failures (errors without retrying)
+ including which limit for retries was exceeded and how far it was
+ exceeded for the serialization/deadlock failures. (Note that in this
+ case the output can be significantly increased.).
+ See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect2" id="PGBENCH-COMMON-OPTIONS"><h3>Common Options</h3><p>
+ <span class="application">pgbench</span> also accepts the following common command-line
+ arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h</code> <em class="replaceable"><code>hostname</code></em><br /></span><span class="term"><code class="option">--host=</code><em class="replaceable"><code>hostname</code></em></span></dt><dd><p>
+ The database server's host name
+ </p></dd><dt><span class="term"><code class="option">-p</code> <em class="replaceable"><code>port</code></em><br /></span><span class="term"><code class="option">--port=</code><em class="replaceable"><code>port</code></em></span></dt><dd><p>
+ The database server's port number
+ </p></dd><dt><span class="term"><code class="option">-U</code> <em class="replaceable"><code>login</code></em><br /></span><span class="term"><code class="option">--username=</code><em class="replaceable"><code>login</code></em></span></dt><dd><p>
+ The user name to connect as
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pgbench</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pgbench</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div></div><div class="refsect1" id="id-1.9.4.11.7"><h2>Exit Status</h2><p>
+ A successful run will exit with status 0. Exit status 1 indicates static
+ problems such as invalid command-line options or internal errors which
+ are supposed to never occur. Early errors that occur when starting
+ benchmark such as initial connection failures also exit with status 1.
+ Errors during the run such as database errors or problems in the script
+ will result in exit status 2. In the latter case,
+ <span class="application">pgbench</span> will print partial results.
+ </p></div><div class="refsect1" id="id-1.9.4.11.8"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.4.11.9"><h2>Notes</h2><div class="refsect2" id="TRANSACTIONS-AND-SCRIPTS"><h3>What Is the <span class="quote">“<span class="quote">Transaction</span>”</span> Actually Performed in <span class="application">pgbench</span>?</h3><p>
+ <span class="application">pgbench</span> executes test scripts chosen randomly
+ from a specified list.
+ The scripts may include built-in scripts specified with <code class="option">-b</code>
+ and user-provided scripts specified with <code class="option">-f</code>.
+ Each script may be given a relative weight specified after an
+ <code class="literal">@</code> so as to change its selection probability.
+ The default weight is <code class="literal">1</code>.
+ Scripts with a weight of <code class="literal">0</code> are ignored.
+ </p><p>
+ The default built-in transaction script (also invoked with <code class="option">-b tpcb-like</code>)
+ issues seven commands per transaction over randomly chosen <code class="literal">aid</code>,
+ <code class="literal">tid</code>, <code class="literal">bid</code> and <code class="literal">delta</code>.
+ The scenario is inspired by the TPC-B benchmark, but is not actually TPC-B,
+ hence the name.
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><code class="literal">BEGIN;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;</code></p></li><li class="listitem"><p><code class="literal">SELECT abalance FROM pgbench_accounts WHERE aid = :aid;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;</code></p></li><li class="listitem"><p><code class="literal">UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;</code></p></li><li class="listitem"><p><code class="literal">INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);</code></p></li><li class="listitem"><p><code class="literal">END;</code></p></li></ol></div><p>
+ If you select the <code class="literal">simple-update</code> built-in (also <code class="option">-N</code>),
+ steps 4 and 5 aren't included in the transaction.
+ This will avoid update contention on these tables, but
+ it makes the test case even less like TPC-B.
+ </p><p>
+ If you select the <code class="literal">select-only</code> built-in (also <code class="option">-S</code>),
+ only the <code class="command">SELECT</code> is issued.
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.3"><h3>Custom Scripts</h3><p>
+ <span class="application">pgbench</span> has support for running custom
+ benchmark scenarios by replacing the default transaction script
+ (described above) with a transaction script read from a file
+ (<code class="option">-f</code> option). In this case a <span class="quote">“<span class="quote">transaction</span>”</span>
+ counts as one execution of a script file.
+ </p><p>
+ A script file contains one or more SQL commands terminated by
+ semicolons. Empty lines and lines beginning with
+ <code class="literal">--</code> are ignored. Script files can also contain
+ <span class="quote">“<span class="quote">meta commands</span>”</span>, which are interpreted by <span class="application">pgbench</span>
+ itself, as described below.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 9.6, SQL commands in script files
+ were terminated by newlines, and so they could not be continued across
+ lines. Now a semicolon is <span class="emphasis"><em>required</em></span> to separate consecutive
+ SQL commands (though an SQL command does not need one if it is followed
+ by a meta command). If you need to create a script file that works with
+ both old and new versions of <span class="application">pgbench</span>, be sure to write
+ each SQL command on a single line ending with a semicolon.
+ </p><p>
+ It is assumed that pgbench scripts do not contain incomplete blocks of SQL
+ transactions. If at runtime the client reaches the end of the script without
+ completing the last transaction block, it will be aborted.
+ </p></div><p>
+ There is a simple variable-substitution facility for script files.
+ Variable names must consist of letters (including non-Latin letters),
+ digits, and underscores, with the first character not being a digit.
+ Variables can be set by the command-line <code class="option">-D</code> option,
+ explained above, or by the meta commands explained below.
+ In addition to any variables preset by <code class="option">-D</code> command-line options,
+ there are a few variables that are preset automatically, listed in
+ <a class="xref" href="pgbench.html#PGBENCH-AUTOMATIC-VARIABLES" title="Table 288. pgbench Automatic Variables">Table 288</a>. A value specified for these
+ variables using <code class="option">-D</code> takes precedence over the automatic presets.
+ Once set, a variable's
+ value can be inserted into an SQL command by writing
+ <code class="literal">:</code><em class="replaceable"><code>variablename</code></em>. When running more than
+ one client session, each session has its own set of variables.
+ <span class="application">pgbench</span> supports up to 255 variable uses in one
+ statement.
+ </p><div class="table" id="PGBENCH-AUTOMATIC-VARIABLES"><p class="title"><strong>Table 288. pgbench Automatic Variables</strong></p><div class="table-contents"><table class="table" summary="pgbench Automatic Variables" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td> <code class="literal">client_id</code> </td><td>unique number identifying the client session (starts from zero)</td></tr><tr><td> <code class="literal">default_seed</code> </td><td>seed used in hash and pseudorandom permutation functions by default</td></tr><tr><td> <code class="literal">random_seed</code> </td><td>random generator seed (unless overwritten with <code class="option">-D</code>)</td></tr><tr><td> <code class="literal">scale</code> </td><td>current scale factor</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Script file meta commands begin with a backslash (<code class="literal">\</code>) and
+ normally extend to the end of the line, although they can be continued
+ to additional lines by writing backslash-return.
+ Arguments to a meta command are separated by white space.
+ These meta commands are supported:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PGBENCH-METACOMMAND-GSET"><span class="term">
+ <code class="literal">\gset [<em class="replaceable"><code>prefix</code></em>]</code>
+ <code class="literal">\aset [<em class="replaceable"><code>prefix</code></em>]</code>
+ </span></dt><dd><p>
+ These commands may be used to end SQL queries, taking the place of the
+ terminating semicolon (<code class="literal">;</code>).
+ </p><p>
+ When the <code class="literal">\gset</code> command is used, the preceding SQL query is
+ expected to return one row, the columns of which are stored into variables
+ named after column names, and prefixed with <em class="replaceable"><code>prefix</code></em>
+ if provided.
+ </p><p>
+ When the <code class="literal">\aset</code> command is used, all combined SQL queries
+ (separated by <code class="literal">\;</code>) have their columns stored into variables
+ named after column names, and prefixed with <em class="replaceable"><code>prefix</code></em>
+ if provided. If a query returns no row, no assignment is made and the variable
+ can be tested for existence to detect this. If a query returns more than one
+ row, the last value is kept.
+ </p><p>
+ <code class="literal">\gset</code> and <code class="literal">\aset</code> cannot be used in
+ pipeline mode, since the query results are not yet available by the time
+ the commands would need them.
+ </p><p>
+ The following example puts the final account balance from the first query
+ into variable <em class="replaceable"><code>abalance</code></em>, and fills variables
+ <em class="replaceable"><code>p_two</code></em> and <em class="replaceable"><code>p_three</code></em>
+ with integers from the third query.
+ The result of the second query is discarded.
+ The result of the two last combined queries are stored in variables
+ <em class="replaceable"><code>four</code></em> and <em class="replaceable"><code>five</code></em>.
+</p><pre class="programlisting">
+UPDATE pgbench_accounts
+ SET abalance = abalance + :delta
+ WHERE aid = :aid
+ RETURNING abalance \gset
+-- compound of two queries
+SELECT 1 \;
+SELECT 2 AS two, 3 AS three \gset p_
+SELECT 4 AS four \; SELECT 5 AS five \aset
+</pre></dd><dt><span class="term"><code class="literal">\if</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\elif</code> <em class="replaceable"><code>expression</code></em><br /></span><span class="term"><code class="literal">\else</code><br /></span><span class="term"><code class="literal">\endif</code></span></dt><dd><p>
+ This group of commands implements nestable conditional blocks,
+ similarly to <code class="literal">psql</code>'s <a class="xref" href="app-psql.html#PSQL-METACOMMAND-IF"><code class="literal">\if</code> <em class="replaceable"><code>expression</code></em></a>.
+ Conditional expressions are identical to those with <code class="literal">\set</code>,
+ with non-zero values interpreted as true.
+ </p></dd><dt id="PGBENCH-METACOMMAND-SET"><span class="term">
+ <code class="literal">\set <em class="replaceable"><code>varname</code></em> <em class="replaceable"><code>expression</code></em></code>
+ </span></dt><dd><p>
+ Sets variable <em class="replaceable"><code>varname</code></em> to a value calculated
+ from <em class="replaceable"><code>expression</code></em>.
+ The expression may contain the <code class="literal">NULL</code> constant,
+ Boolean constants <code class="literal">TRUE</code> and <code class="literal">FALSE</code>,
+ integer constants such as <code class="literal">5432</code>,
+ double constants such as <code class="literal">3.14159</code>,
+ references to variables <code class="literal">:</code><em class="replaceable"><code>variablename</code></em>,
+ <a class="link" href="pgbench.html#PGBENCH-BUILTIN-OPERATORS" title="Built-in Operators">operators</a>
+ with their usual SQL precedence and associativity,
+ <a class="link" href="pgbench.html#PGBENCH-BUILTIN-FUNCTIONS" title="Built-In Functions">function calls</a>,
+ SQL <a class="link" href="functions-conditional.html#FUNCTIONS-CASE" title="9.18.1. CASE"><code class="token">CASE</code> generic conditional
+ expressions</a> and parentheses.
+ </p><p>
+ Functions and most operators return <code class="literal">NULL</code> on
+ <code class="literal">NULL</code> input.
+ </p><p>
+ For conditional purposes, non zero numerical values are
+ <code class="literal">TRUE</code>, zero numerical values and <code class="literal">NULL</code>
+ are <code class="literal">FALSE</code>.
+ </p><p>
+ Too large or small integer and double constants, as well as
+ integer arithmetic operators (<code class="literal">+</code>,
+ <code class="literal">-</code>, <code class="literal">*</code> and <code class="literal">/</code>)
+ raise errors on overflows.
+ </p><p>
+ When no final <code class="token">ELSE</code> clause is provided to a
+ <code class="token">CASE</code>, the default value is <code class="literal">NULL</code>.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+\set ntellers 10 * :scale
+\set aid (1021 * random(1, 100000 * :scale)) % \
+ (100000 * :scale) + 1
+\set divx CASE WHEN :x &lt;&gt; 0 THEN :y/:x ELSE NULL END
+</pre></dd><dt><span class="term">
+ <code class="literal">\sleep <em class="replaceable"><code>number</code></em> [ us | ms | s ]</code>
+ </span></dt><dd><p>
+ Causes script execution to sleep for the specified duration in
+ microseconds (<code class="literal">us</code>), milliseconds (<code class="literal">ms</code>) or seconds
+ (<code class="literal">s</code>). If the unit is omitted then seconds are the default.
+ <em class="replaceable"><code>number</code></em> can be either an integer constant or a
+ <code class="literal">:</code><em class="replaceable"><code>variablename</code></em> reference to a variable
+ having an integer value.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+\sleep 10 ms
+</pre></dd><dt><span class="term">
+ <code class="literal">\setshell <em class="replaceable"><code>varname</code></em> <em class="replaceable"><code>command</code></em> [ <em class="replaceable"><code>argument</code></em> ... ]</code>
+ </span></dt><dd><p>
+ Sets variable <em class="replaceable"><code>varname</code></em> to the result of the shell command
+ <em class="replaceable"><code>command</code></em> with the given <em class="replaceable"><code>argument</code></em>(s).
+ The command must return an integer value through its standard output.
+ </p><p>
+ <em class="replaceable"><code>command</code></em> and each <em class="replaceable"><code>argument</code></em> can be either
+ a text constant or a <code class="literal">:</code><em class="replaceable"><code>variablename</code></em> reference
+ to a variable. If you want to use an <em class="replaceable"><code>argument</code></em> starting
+ with a colon, write an additional colon at the beginning of
+ <em class="replaceable"><code>argument</code></em>.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+\setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon
+</pre></dd><dt><span class="term">
+ <code class="literal">\shell <em class="replaceable"><code>command</code></em> [ <em class="replaceable"><code>argument</code></em> ... ]</code>
+ </span></dt><dd><p>
+ Same as <code class="literal">\setshell</code>, but the result of the command
+ is discarded.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+\shell command literal_argument :variable ::literal_starting_with_colon
+</pre></dd><dt id="PGBENCH-METACOMMAND-PIPELINE"><span class="term"><code class="literal">\startpipeline</code><br /></span><span class="term"><code class="literal">\endpipeline</code></span></dt><dd><p>
+ These commands delimit the start and end of a pipeline of SQL
+ statements. In pipeline mode, statements are sent to the server
+ without waiting for the results of previous statements. See
+ <a class="xref" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Section 34.5</a> for more details.
+ Pipeline mode requires the use of extended query protocol.
+ </p></dd></dl></div></div><div class="refsect2" id="PGBENCH-BUILTIN-OPERATORS"><h3>Built-in Operators</h3><p>
+ The arithmetic, bitwise, comparison and logical operators listed in
+ <a class="xref" href="pgbench.html#PGBENCH-OPERATORS" title="Table 289. pgbench Operators">Table 289</a> are built into <span class="application">pgbench</span>
+ and may be used in expressions appearing in
+ <a class="link" href="pgbench.html#PGBENCH-METACOMMAND-SET"><code class="literal">\set</code></a>.
+ The operators are listed in increasing precedence order.
+ Except as noted, operators taking two numeric inputs will produce
+ a double value if either input is double, otherwise they produce
+ an integer result.
+ </p><div class="table" id="PGBENCH-OPERATORS"><p class="title"><strong>Table 289. pgbench Operators</strong></p><div class="table-contents"><table class="table" summary="pgbench Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">OR</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Logical OR
+ </p>
+ <p>
+ <code class="literal">5 or 0</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">AND</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Logical AND
+ </p>
+ <p>
+ <code class="literal">3 and 0</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">NOT</code> <em class="replaceable"><code>boolean</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Logical NOT
+ </p>
+ <p>
+ <code class="literal">not false</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>boolean</code></em> <code class="literal">IS [NOT] (NULL|TRUE|FALSE)</code>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Boolean value tests
+ </p>
+ <p>
+ <code class="literal">1 is null</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>value</code></em> <code class="literal">ISNULL|NOTNULL</code>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Nullness tests
+ </p>
+ <p>
+ <code class="literal">1 notnull</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">=</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Equal
+ </p>
+ <p>
+ <code class="literal">5 = 4</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">&lt;&gt;</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Not equal
+ </p>
+ <p>
+ <code class="literal">5 &lt;&gt; 4</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">!=</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Not equal
+ </p>
+ <p>
+ <code class="literal">5 != 5</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Less than
+ </p>
+ <p>
+ <code class="literal">5 &lt; 4</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">&lt;=</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Less than or equal to
+ </p>
+ <p>
+ <code class="literal">5 &lt;= 4</code>
+ → <code class="returnvalue">FALSE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">&gt;</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Greater than
+ </p>
+ <p>
+ <code class="literal">5 &gt; 4</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">&gt;=</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>boolean</code></em></code>
+ </p>
+ <p>
+ Greater than or equal to
+ </p>
+ <p>
+ <code class="literal">5 &gt;= 4</code>
+ → <code class="returnvalue">TRUE</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">|</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise OR
+ </p>
+ <p>
+ <code class="literal">1 | 2</code>
+ → <code class="returnvalue">3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">#</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise XOR
+ </p>
+ <p>
+ <code class="literal">1 # 3</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">&amp;</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise AND
+ </p>
+ <p>
+ <code class="literal">1 &amp; 3</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">~</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise NOT
+ </p>
+ <p>
+ <code class="literal">~ 1</code>
+ → <code class="returnvalue">-2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">&lt;&lt;</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise shift left
+ </p>
+ <p>
+ <code class="literal">1 &lt;&lt; 2</code>
+ → <code class="returnvalue">4</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">&gt;&gt;</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Bitwise shift right
+ </p>
+ <p>
+ <code class="literal">8 &gt;&gt; 2</code>
+ → <code class="returnvalue">2</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">+</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Addition
+ </p>
+ <p>
+ <code class="literal">5 + 4</code>
+ → <code class="returnvalue">9</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">-</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Subtraction
+ </p>
+ <p>
+ <code class="literal">3 - 2.0</code>
+ → <code class="returnvalue">1.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">*</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Multiplication
+ </p>
+ <p>
+ <code class="literal">5 * 4</code>
+ → <code class="returnvalue">20</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>number</code></em> <code class="literal">/</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Division (truncates the result towards zero if both inputs are integers)
+ </p>
+ <p>
+ <code class="literal">5 / 3</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <em class="replaceable"><code>integer</code></em> <code class="literal">%</code> <em class="replaceable"><code>integer</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>integer</code></em></code>
+ </p>
+ <p>
+ Modulo (remainder)
+ </p>
+ <p>
+ <code class="literal">3 % 2</code>
+ → <code class="returnvalue">1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="literal">-</code> <em class="replaceable"><code>number</code></em>
+ → <code class="returnvalue"><em class="replaceable"><code>number</code></em></code>
+ </p>
+ <p>
+ Negation
+ </p>
+ <p>
+ <code class="literal">- 2.0</code>
+ → <code class="returnvalue">-2.0</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="refsect2" id="PGBENCH-BUILTIN-FUNCTIONS"><h3>Built-In Functions</h3><p>
+ The functions listed in <a class="xref" href="pgbench.html#PGBENCH-FUNCTIONS" title="Table 290. pgbench Functions">Table 290</a> are built
+ into <span class="application">pgbench</span> and may be used in expressions appearing in
+ <a class="link" href="pgbench.html#PGBENCH-METACOMMAND-SET"><code class="literal">\set</code></a>.
+ </p><div class="table" id="PGBENCH-FUNCTIONS"><p class="title"><strong>Table 290. pgbench Functions</strong></p><div class="table-contents"><table class="table" summary="pgbench Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p>
+ <p>
+ Example(s)
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">abs</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue"></code> same type as input
+ </p>
+ <p>
+ Absolute value
+ </p>
+ <p>
+ <code class="literal">abs(-17)</code>
+ → <code class="returnvalue">17</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">debug</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue"></code> same type as input
+ </p>
+ <p>
+ Prints the argument to <span class="systemitem">stderr</span>,
+ and returns the argument.
+ </p>
+ <p>
+ <code class="literal">debug(5432.1)</code>
+ → <code class="returnvalue">5432.1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">double</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ Casts to double.
+ </p>
+ <p>
+ <code class="literal">double(5432)</code>
+ → <code class="returnvalue">5432.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">exp</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ Exponential (<code class="literal">e</code> raised to the given power)
+ </p>
+ <p>
+ <code class="literal">exp(1.0)</code>
+ → <code class="returnvalue">2.718281828459045</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">greatest</code> ( <em class="replaceable"><code>number</code></em> [<span class="optional">, <code class="literal">...</code> </span>] )
+ → <code class="returnvalue"></code> <code class="type">double</code> if any argument is double, else <code class="type">integer</code>
+ </p>
+ <p>
+ Selects the largest value among the arguments.
+ </p>
+ <p>
+ <code class="literal">greatest(5, 4, 3, 2)</code>
+ → <code class="returnvalue">5</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hash</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ This is an alias for <code class="function">hash_murmur2</code>.
+ </p>
+ <p>
+ <code class="literal">hash(10, 5432)</code>
+ → <code class="returnvalue">-5817877081768721676</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hash_fnv1a</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes <a class="ulink" href="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function" target="_top">FNV-1a hash</a>.
+ </p>
+ <p>
+ <code class="literal">hash_fnv1a(10, 5432)</code>
+ → <code class="returnvalue">-7793829335365542153</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">hash_murmur2</code> ( <em class="parameter"><code>value</code></em> [<span class="optional">, <em class="parameter"><code>seed</code></em> </span>] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes <a class="ulink" href="https://en.wikipedia.org/wiki/MurmurHash" target="_top">MurmurHash2 hash</a>.
+ </p>
+ <p>
+ <code class="literal">hash_murmur2(10, 5432)</code>
+ → <code class="returnvalue">-5817877081768721676</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">int</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Casts to integer.
+ </p>
+ <p>
+ <code class="literal">int(5.4 + 3.8)</code>
+ → <code class="returnvalue">9</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">least</code> ( <em class="replaceable"><code>number</code></em> [<span class="optional">, <code class="literal">...</code> </span>] )
+ → <code class="returnvalue"></code> <code class="type">double</code> if any argument is double, else <code class="type">integer</code>
+ </p>
+ <p>
+ Selects the smallest value among the arguments.
+ </p>
+ <p>
+ <code class="literal">least(5, 4, 3, 2.1)</code>
+ → <code class="returnvalue">2.1</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">ln</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ Natural logarithm
+ </p>
+ <p>
+ <code class="literal">ln(2.718281828459045)</code>
+ → <code class="returnvalue">1.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+<code class="function">mod</code> ( <em class="replaceable"><code>integer</code></em>, <em class="replaceable"><code>integer</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Modulo (remainder)
+ </p>
+ <p>
+ <code class="literal">mod(54, 32)</code>
+ → <code class="returnvalue">22</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">permute</code> ( <em class="parameter"><code>i</code></em>, <em class="parameter"><code>size</code></em> [, <em class="parameter"><code>seed</code></em> ] )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Permuted value of <em class="parameter"><code>i</code></em>, in the range
+ <code class="literal">[0, size)</code>. This is the new position of
+ <em class="parameter"><code>i</code></em> (modulo <em class="parameter"><code>size</code></em>) in a
+ pseudorandom permutation of the integers <code class="literal">0...size-1</code>,
+ parameterized by <em class="parameter"><code>seed</code></em>, see below.
+ </p>
+ <p>
+ <code class="literal">permute(0, 4)</code>
+ → <code class="returnvalue">an integer between 0 and 3</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pi</code> ()
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ Approximate value of <span class="symbol_font">π</span>
+ </p>
+ <p>
+ <code class="literal">pi()</code>
+ → <code class="returnvalue">3.14159265358979323846</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">pow</code> ( <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p class="func_signature">
+ <code class="function">power</code> ( <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ <em class="parameter"><code>x</code></em> raised to the power of <em class="parameter"><code>y</code></em>
+ </p>
+ <p>
+ <code class="literal">pow(2.0, 10)</code>
+ → <code class="returnvalue">1024.0</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">random</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes a uniformly-distributed random integer in <code class="literal">[lb,
+ ub]</code>.
+ </p>
+ <p>
+ <code class="literal">random(1, 10)</code>
+ → <code class="returnvalue">an integer between 1 and 10</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">random_exponential</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes an exponentially-distributed random integer in <code class="literal">[lb,
+ ub]</code>, see below.
+ </p>
+ <p>
+ <code class="literal">random_exponential(1, 10, 3.0)</code>
+ → <code class="returnvalue">an integer between 1 and 10</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">random_gaussian</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes a Gaussian-distributed random integer in <code class="literal">[lb,
+ ub]</code>, see below.
+ </p>
+ <p>
+ <code class="literal">random_gaussian(1, 10, 2.5)</code>
+ → <code class="returnvalue">an integer between 1 and 10</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">random_zipfian</code> ( <em class="parameter"><code>lb</code></em>, <em class="parameter"><code>ub</code></em>, <em class="parameter"><code>parameter</code></em> )
+ → <code class="returnvalue">integer</code>
+ </p>
+ <p>
+ Computes a Zipfian-distributed random integer in <code class="literal">[lb,
+ ub]</code>, see below.
+ </p>
+ <p>
+ <code class="literal">random_zipfian(1, 10, 1.5)</code>
+ → <code class="returnvalue">an integer between 1 and 10</code>
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sqrt</code> ( <em class="replaceable"><code>number</code></em> )
+ → <code class="returnvalue">double</code>
+ </p>
+ <p>
+ Square root
+ </p>
+ <p>
+ <code class="literal">sqrt(2.0)</code>
+ → <code class="returnvalue">1.414213562</code>
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="literal">random</code> function generates values using a uniform
+ distribution, that is all the values are drawn within the specified
+ range with equal probability. The <code class="literal">random_exponential</code>,
+ <code class="literal">random_gaussian</code> and <code class="literal">random_zipfian</code>
+ functions require an additional double parameter which determines the precise
+ shape of the distribution.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ For an exponential distribution, <em class="replaceable"><code>parameter</code></em>
+ controls the distribution by truncating a quickly-decreasing
+ exponential distribution at <em class="replaceable"><code>parameter</code></em>, and then
+ projecting onto integers between the bounds.
+ To be precise, with
+</p><div class="literallayout"><p><br />
+f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter))<br />
+</p></div><p>
+ Then value <em class="replaceable"><code>i</code></em> between <em class="replaceable"><code>min</code></em> and
+ <em class="replaceable"><code>max</code></em> inclusive is drawn with probability:
+ <code class="literal">f(i) - f(i + 1)</code>.
+ </p><p>
+ Intuitively, the larger the <em class="replaceable"><code>parameter</code></em>, the more
+ frequently values close to <em class="replaceable"><code>min</code></em> are accessed, and the
+ less frequently values close to <em class="replaceable"><code>max</code></em> are accessed.
+ The closer to 0 <em class="replaceable"><code>parameter</code></em> is, the flatter (more
+ uniform) the access distribution.
+ A crude approximation of the distribution is that the most frequent 1%
+ values in the range, close to <em class="replaceable"><code>min</code></em>, are drawn
+ <em class="replaceable"><code>parameter</code></em>% of the time.
+ The <em class="replaceable"><code>parameter</code></em> value must be strictly positive.
+ </p></li><li class="listitem"><p>
+ For a Gaussian distribution, the interval is mapped onto a standard
+ normal distribution (the classical bell-shaped Gaussian curve) truncated
+ at <code class="literal">-parameter</code> on the left and <code class="literal">+parameter</code>
+ on the right.
+ Values in the middle of the interval are more likely to be drawn.
+ To be precise, if <code class="literal">PHI(x)</code> is the cumulative distribution
+ function of the standard normal distribution, with mean <code class="literal">mu</code>
+ defined as <code class="literal">(max + min) / 2.0</code>, with
+</p><div class="literallayout"><p><br />
+f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) /<br />
+       (2.0 * PHI(parameter) - 1)<br />
+</p></div><p>
+ then value <em class="replaceable"><code>i</code></em> between <em class="replaceable"><code>min</code></em> and
+ <em class="replaceable"><code>max</code></em> inclusive is drawn with probability:
+ <code class="literal">f(i + 0.5) - f(i - 0.5)</code>.
+ Intuitively, the larger the <em class="replaceable"><code>parameter</code></em>, the more
+ frequently values close to the middle of the interval are drawn, and the
+ less frequently values close to the <em class="replaceable"><code>min</code></em> and
+ <em class="replaceable"><code>max</code></em> bounds. About 67% of values are drawn from the
+ middle <code class="literal">1.0 / parameter</code>, that is a relative
+ <code class="literal">0.5 / parameter</code> around the mean, and 95% in the middle
+ <code class="literal">2.0 / parameter</code>, that is a relative
+ <code class="literal">1.0 / parameter</code> around the mean; for instance, if
+ <em class="replaceable"><code>parameter</code></em> is 4.0, 67% of values are drawn from the
+ middle quarter (1.0 / 4.0) of the interval (i.e., from
+ <code class="literal">3.0 / 8.0</code> to <code class="literal">5.0 / 8.0</code>) and 95% from
+ the middle half (<code class="literal">2.0 / 4.0</code>) of the interval (second and third
+ quartiles). The minimum allowed <em class="replaceable"><code>parameter</code></em>
+ value is 2.0.
+ </p></li><li class="listitem"><p>
+ <code class="literal">random_zipfian</code> generates a bounded Zipfian
+ distribution.
+ <em class="replaceable"><code>parameter</code></em> defines how skewed the distribution
+ is. The larger the <em class="replaceable"><code>parameter</code></em>, the more
+ frequently values closer to the beginning of the interval are drawn.
+ The distribution is such that, assuming the range starts from 1,
+ the ratio of the probability of drawing <em class="replaceable"><code>k</code></em>
+ versus drawing <em class="replaceable"><code>k+1</code></em> is
+ <code class="literal">((<em class="replaceable"><code>k</code></em>+1)/<em class="replaceable"><code>k</code></em>)**<em class="replaceable"><code>parameter</code></em></code>.
+ For example, <code class="literal">random_zipfian(1, ..., 2.5)</code> produces
+ the value <code class="literal">1</code> about <code class="literal">(2/1)**2.5 =
+ 5.66</code> times more frequently than <code class="literal">2</code>, which
+ itself is produced <code class="literal">(3/2)**2.5 = 2.76</code> times more
+ frequently than <code class="literal">3</code>, and so on.
+ </p><p>
+ <span class="application">pgbench</span>'s implementation is based on
+ "Non-Uniform Random Variate Generation", Luc Devroye, p. 550-551,
+ Springer 1986. Due to limitations of that algorithm,
+ the <em class="replaceable"><code>parameter</code></em> value is restricted to
+ the range [1.001, 1000].
+ </p></li></ul></div><div class="note"><h3 class="title">Note</h3><p>
+ When designing a benchmark which selects rows non-uniformly, be aware
+ that the rows chosen may be correlated with other data such as IDs from
+ a sequence or the physical row ordering, which may skew performance
+ measurements.
+ </p><p>
+ To avoid this, you may wish to use the <code class="function">permute</code>
+ function, or some other additional step with similar effect, to shuffle
+ the selected rows and remove such correlations.
+ </p></div><p>
+ Hash functions <code class="literal">hash</code>, <code class="literal">hash_murmur2</code> and
+ <code class="literal">hash_fnv1a</code> accept an input value and an optional seed parameter.
+ In case the seed isn't provided the value of <code class="literal">:default_seed</code>
+ is used, which is initialized randomly unless set by the command-line
+ <code class="literal">-D</code> option.
+ </p><p>
+ <code class="literal">permute</code> accepts an input value, a size, and an optional
+ seed parameter. It generates a pseudorandom permutation of integers in
+ the range <code class="literal">[0, size)</code>, and returns the index of the input
+ value in the permuted values. The permutation chosen is parameterized by
+ the seed, which defaults to <code class="literal">:default_seed</code>, if not
+ specified. Unlike the hash functions, <code class="literal">permute</code> ensures
+ that there are no collisions or holes in the output values. Input values
+ outside the interval are interpreted modulo the size. The function raises
+ an error if the size is not positive. <code class="function">permute</code> can be
+ used to scatter the distribution of non-uniform random functions such as
+ <code class="literal">random_zipfian</code> or <code class="literal">random_exponential</code>
+ so that values drawn more often are not trivially correlated. For
+ instance, the following <span class="application">pgbench</span> script
+ simulates a possible real world workload typical for social media and
+ blogging platforms where a few accounts generate excessive load:
+
+</p><pre class="programlisting">
+\set size 1000000
+\set r random_zipfian(1, :size, 1.07)
+\set k 1 + permute(:r, :size)
+</pre><p>
+
+ In some cases several distinct distributions are needed which don't correlate
+ with each other and this is when the optional seed parameter comes in handy:
+
+</p><pre class="programlisting">
+\set k1 1 + permute(:r, :size, :default_seed + 123)
+\set k2 1 + permute(:r, :size, :default_seed + 321)
+</pre><p>
+
+ A similar behavior can also be approximated with <code class="function">hash</code>:
+
+</p><pre class="programlisting">
+\set size 1000000
+\set r random_zipfian(1, 100 * :size, 1.07)
+\set k 1 + abs(hash(:r)) % :size
+</pre><p>
+
+ However, since <code class="function">hash</code> generates collisions, some values
+ will not be reachable and others will be more frequent than expected from
+ the original distribution.
+ </p><p>
+ As an example, the full definition of the built-in TPC-B-like
+ transaction is:
+
+</p><pre class="programlisting">
+\set aid random(1, 100000 * :scale)
+\set bid random(1, 1 * :scale)
+\set tid random(1, 10 * :scale)
+\set delta random(-5000, 5000)
+BEGIN;
+UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
+SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
+UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
+UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
+INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
+END;
+</pre><p>
+
+ This script allows each iteration of the transaction to reference
+ different, randomly-chosen rows. (This example also shows why it's
+ important for each client session to have its own variables —
+ otherwise they'd not be independently touching different rows.)
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.6"><h3>Per-Transaction Logging</h3><p>
+ With the <code class="option">-l</code> option (but without
+ the <code class="option">--aggregate-interval</code> option),
+ <span class="application">pgbench</span> writes information about each transaction
+ to a log file. The log file will be named
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>.<em class="replaceable"><code>nnn</code></em></code>,
+ where <em class="replaceable"><code>prefix</code></em> defaults to <code class="literal">pgbench_log</code>, and
+ <em class="replaceable"><code>nnn</code></em> is the PID of the
+ <span class="application">pgbench</span> process.
+ The prefix can be changed by using the <code class="option">--log-prefix</code> option.
+ If the <code class="option">-j</code> option is 2 or higher, so that there are multiple
+ worker threads, each will have its own log file. The first worker will
+ use the same name for its log file as in the standard single worker case.
+ The additional log files for the other workers will be named
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>.<em class="replaceable"><code>nnn</code></em>.<em class="replaceable"><code>mmm</code></em></code>,
+ where <em class="replaceable"><code>mmm</code></em> is a sequential number for each worker starting
+ with 1.
+ </p><p>
+ Each line in a log file describes one transaction.
+ It contains the following space-separated fields:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>client_id</code></em></span></dt><dd><p>
+ identifies the client session that ran the transaction
+ </p></dd><dt><span class="term"><em class="replaceable"><code>transaction_no</code></em></span></dt><dd><p>
+ counts how many transactions have been run by that session
+ </p></dd><dt><span class="term"><em class="replaceable"><code>time</code></em></span></dt><dd><p>
+ transaction's elapsed time, in microseconds
+ </p></dd><dt><span class="term"><em class="replaceable"><code>script_no</code></em></span></dt><dd><p>
+ identifies the script file that was used for the transaction
+ (useful when multiple scripts are specified
+ with <code class="option">-f</code> or <code class="option">-b</code>)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>time_epoch</code></em></span></dt><dd><p>
+ transaction's completion time, as a Unix-epoch time stamp
+ </p></dd><dt><span class="term"><em class="replaceable"><code>time_us</code></em></span></dt><dd><p>
+ fractional-second part of transaction's completion time, in
+ microseconds
+ </p></dd><dt><span class="term"><em class="replaceable"><code>schedule_lag</code></em></span></dt><dd><p>
+ transaction start delay, that is the difference between the
+ transaction's scheduled start time and the time it actually
+ started, in microseconds
+ (present only if <code class="option">--rate</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>retries</code></em></span></dt><dd><p>
+ count of retries after serialization or deadlock errors during the
+ transaction
+ (present only if <code class="option">--max-tries</code> is not equal to one)
+ </p></dd></dl></div><p>
+ </p><p>
+ When both <code class="option">--rate</code> and <code class="option">--latency-limit</code> are used,
+ the <em class="replaceable"><code>time</code></em> for a skipped transaction will be reported as
+ <code class="literal">skipped</code>.
+ If the transaction ends with a failure, its <em class="replaceable"><code>time</code></em>
+ will be reported as <code class="literal">failed</code>. If you use the
+ <code class="option">--failures-detailed</code> option, the
+ <em class="replaceable"><code>time</code></em> of the failed transaction will be reported as
+ <code class="literal">serialization</code> or
+ <code class="literal">deadlock</code> depending on the type of failure (see
+ <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information).
+ </p><p>
+ Here is a snippet of a log file generated in a single-client run:
+</p><pre class="screen">
+0 199 2241 0 1175850568 995598
+0 200 2465 0 1175850568 998079
+0 201 2513 0 1175850569 608
+0 202 2038 0 1175850569 2663
+</pre><p>
+
+ Another example with <code class="literal">--rate=100</code>
+ and <code class="literal">--latency-limit=5</code> (note the additional
+ <em class="replaceable"><code>schedule_lag</code></em> column):
+</p><pre class="screen">
+0 81 4621 0 1412881037 912698 3005
+0 82 6173 0 1412881037 914578 4304
+0 83 skipped 0 1412881037 914578 5217
+0 83 skipped 0 1412881037 914578 5099
+0 83 4722 0 1412881037 916203 3108
+0 84 4142 0 1412881037 918023 2333
+0 85 2465 0 1412881037 919759 740
+</pre><p>
+ In this example, transaction 82 was late, because its latency (6.173 ms) was
+ over the 5 ms limit. The next two transactions were skipped, because they
+ were already late before they were even started.
+ </p><p>
+ The following example shows a snippet of a log file with failures and
+ retries, with the maximum number of tries set to 10 (note the additional
+ <em class="replaceable"><code>retries</code></em> column):
+</p><pre class="screen">
+3 0 47423 0 1499414498 34501 3
+3 1 8333 0 1499414498 42848 0
+3 2 8358 0 1499414498 51219 0
+4 0 72345 0 1499414498 59433 6
+1 3 41718 0 1499414498 67879 4
+1 4 8416 0 1499414498 76311 0
+3 3 33235 0 1499414498 84469 3
+0 0 failed 0 1499414498 84905 9
+2 0 failed 0 1499414498 86248 9
+3 4 8307 0 1499414498 92788 0
+</pre><p>
+ </p><p>
+ If the <code class="option">--failures-detailed</code> option is used, the type of
+ failure is reported in the <em class="replaceable"><code>time</code></em> like this:
+</p><pre class="screen">
+3 0 47423 0 1499414498 34501 3
+3 1 8333 0 1499414498 42848 0
+3 2 8358 0 1499414498 51219 0
+4 0 72345 0 1499414498 59433 6
+1 3 41718 0 1499414498 67879 4
+1 4 8416 0 1499414498 76311 0
+3 3 33235 0 1499414498 84469 3
+0 0 serialization 0 1499414498 84905 9
+2 0 serialization 0 1499414498 86248 9
+3 4 8307 0 1499414498 92788 0
+</pre><p>
+ </p><p>
+ When running a long test on hardware that can handle a lot of transactions,
+ the log files can become very large. The <code class="option">--sampling-rate</code> option
+ can be used to log only a random sample of transactions.
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.7"><h3>Aggregated Logging</h3><p>
+ With the <code class="option">--aggregate-interval</code> option, a different
+ format is used for the log files. Each log line describes one
+ aggregation interval. It contains the following space-separated
+ fields:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>interval_start</code></em></span></dt><dd><p>
+ start time of the interval, as a Unix-epoch time stamp
+ </p></dd><dt><span class="term"><em class="replaceable"><code>num_transactions</code></em></span></dt><dd><p>
+ number of transactions within the interval
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sum_latency</code></em></span></dt><dd><p>
+ sum of transaction latencies
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sum_latency_2</code></em></span></dt><dd><p>
+ sum of squares of transaction latencies
+ </p></dd><dt><span class="term"><em class="replaceable"><code>min_latency</code></em></span></dt><dd><p>
+ minimum transaction latency
+ </p></dd><dt><span class="term"><em class="replaceable"><code>max_latency</code></em></span></dt><dd><p>
+ maximum transaction latency
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sum_lag</code></em></span></dt><dd><p>
+ sum of transaction start delays
+ (zero unless <code class="option">--rate</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sum_lag_2</code></em></span></dt><dd><p>
+ sum of squares of transaction start delays
+ (zero unless <code class="option">--rate</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>min_lag</code></em></span></dt><dd><p>
+ minimum transaction start delay
+ (zero unless <code class="option">--rate</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>max_lag</code></em></span></dt><dd><p>
+ maximum transaction start delay
+ (zero unless <code class="option">--rate</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>skipped</code></em></span></dt><dd><p>
+ number of transactions skipped because they would have started too late
+ (zero unless <code class="option">--rate</code>
+ and <code class="option">--latency-limit</code> are specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>retried</code></em></span></dt><dd><p>
+ number of retried transactions
+ (zero unless <code class="option">--max-tries</code> is not equal to one)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>retries</code></em></span></dt><dd><p>
+ number of retries after serialization or deadlock errors
+ (zero unless <code class="option">--max-tries</code> is not equal to one)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>serialization_failures</code></em></span></dt><dd><p>
+ number of transactions that got a serialization error and were not
+ retried afterwards
+ (zero unless <code class="option">--failures-detailed</code> is specified)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>deadlock_failures</code></em></span></dt><dd><p>
+ number of transactions that got a deadlock error and were not
+ retried afterwards
+ (zero unless <code class="option">--failures-detailed</code> is specified)
+ </p></dd></dl></div><p>
+ </p><p>
+ Here is some example output generated with these options:
+</p><pre class="screen">
+<strong class="userinput"><code>pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test</code></strong>
+
+1650260552 5178 26171317 177284491527 1136 44462 2647617 7321113867 0 9866 64 7564 28340 4148 0
+1650260562 4808 25573984 220121792172 1171 62083 3037380 9666800914 0 9998 598 7392 26621 4527 0
+</pre><p>
+ </p><p>
+ Notice that while the plain (unaggregated) log format shows which script
+ was used for each transaction, the aggregated format does not. Therefore if
+ you need per-script data, you need to aggregate the data on your own.
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.8"><h3>Per-Statement Report</h3><p>
+ With the <code class="option">-r</code> option, <span class="application">pgbench</span>
+ collects the following statistics for each statement:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">latency</code> — elapsed transaction time for each
+ statement. <span class="application">pgbench</span> reports an average value
+ of all successful runs of the statement.
+ </p></li><li class="listitem"><p>
+ The number of failures in this statement. See
+ <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.
+ </p></li><li class="listitem"><p>
+ The number of retries after a serialization or a deadlock error in this
+ statement. See <a class="xref" href="pgbench.html#FAILURES-AND-RETRIES" title="Failures and Serialization/Deadlock Retries">Failures and Serialization/Deadlock Retries</a> for more information.
+ </p></li></ul></div><p>
+ </p><p>
+ The report displays retry statistics only if the <code class="option">--max-tries</code>
+ option is not equal to 1.
+ </p><p>
+ All values are computed for each statement executed by every client and are
+ reported after the benchmark has finished.
+ </p><p>
+ For the default script, the output will look similar to this:
+</p><pre class="screen">
+starting vacuum...end.
+transaction type: &lt;builtin: TPC-B (sort of)&gt;
+scaling factor: 1
+query mode: simple
+number of clients: 10
+number of threads: 1
+maximum number of tries: 1
+number of transactions per client: 1000
+number of transactions actually processed: 10000/10000
+number of failed transactions: 0 (0.000%)
+number of transactions above the 50.0 ms latency limit: 1311/10000 (13.110 %)
+latency average = 28.488 ms
+latency stddev = 21.009 ms
+initial connection time = 69.068 ms
+tps = 346.224794 (without initial connection time)
+statement latencies in milliseconds and failures:
+ 0.012 0 \set aid random(1, 100000 * :scale)
+ 0.002 0 \set bid random(1, 1 * :scale)
+ 0.002 0 \set tid random(1, 10 * :scale)
+ 0.002 0 \set delta random(-5000, 5000)
+ 0.319 0 BEGIN;
+ 0.834 0 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
+ 0.641 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
+ 11.126 0 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
+ 12.961 0 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
+ 0.634 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
+ 1.957 0 END;
+</pre><p>
+
+ Another example of output for the default script using serializable default
+ transaction isolation level (<code class="command">PGOPTIONS='-c
+ default_transaction_isolation=serializable' pgbench ...</code>):
+</p><pre class="screen">
+starting vacuum...end.
+transaction type: &lt;builtin: TPC-B (sort of)&gt;
+scaling factor: 1
+query mode: simple
+number of clients: 10
+number of threads: 1
+maximum number of tries: 10
+number of transactions per client: 1000
+number of transactions actually processed: 6317/10000
+number of failed transactions: 3683 (36.830%)
+number of transactions retried: 7667 (76.670%)
+total number of retries: 45339
+number of transactions above the 50.0 ms latency limit: 106/6317 (1.678 %)
+latency average = 17.016 ms
+latency stddev = 13.283 ms
+initial connection time = 45.017 ms
+tps = 186.792667 (without initial connection time)
+statement latencies in milliseconds, failures and retries:
+ 0.006 0 0 \set aid random(1, 100000 * :scale)
+ 0.001 0 0 \set bid random(1, 1 * :scale)
+ 0.001 0 0 \set tid random(1, 10 * :scale)
+ 0.001 0 0 \set delta random(-5000, 5000)
+ 0.385 0 0 BEGIN;
+ 0.773 0 1 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
+ 0.624 0 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
+ 1.098 320 3762 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
+ 0.582 3363 41576 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
+ 0.465 0 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
+ 1.933 0 0 END;
+</pre><p>
+ If multiple script files are specified, all statistics are reported
+ separately for each script file.
+ </p><p>
+ Note that collecting the additional timing information needed for
+ per-statement latency computation adds some overhead. This will slow
+ average execution speed and lower the computed TPS. The amount
+ of slowdown varies significantly depending on platform and hardware.
+ Comparing average TPS values with and without latency reporting enabled
+ is a good way to measure if the timing overhead is significant.
+ </p></div><div class="refsect2" id="FAILURES-AND-RETRIES"><h3>Failures and Serialization/Deadlock Retries</h3><p>
+ When executing <span class="application">pgbench</span>, there are three main types
+ of errors:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Errors of the main program. They are the most serious and always result
+ in an immediate exit from <span class="application">pgbench</span> with the
+ corresponding error message. They include:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ errors at the beginning of <span class="application">pgbench</span>
+ (e.g. an invalid option value);
+ </p></li><li class="listitem"><p>
+ errors in the initialization mode (e.g. the query to create
+ tables for built-in scripts fails);
+ </p></li><li class="listitem"><p>
+ errors before starting threads (e.g. could not connect to the
+ database server, syntax error in the meta command, thread
+ creation failure);
+ </p></li><li class="listitem"><p>
+ internal <span class="application">pgbench</span> errors (which are
+ supposed to never occur...).
+ </p></li></ul></div></li><li class="listitem"><p>
+ Errors when the thread manages its clients (e.g. the client could not
+ start a connection to the database server / the socket for connecting
+ the client to the database server has become invalid). In such cases
+ all clients of this thread stop while other threads continue to work.
+ </p></li><li class="listitem"><p>
+ Direct client errors. They lead to immediate exit from
+ <span class="application">pgbench</span> with the corresponding error message
+ only in the case of an internal <span class="application">pgbench</span>
+ error (which are supposed to never occur...). Otherwise in the worst
+ case they only lead to the abortion of the failed client while other
+ clients continue their run (but some client errors are handled without
+ an abortion of the client and reported separately, see below). Later in
+ this section it is assumed that the discussed errors are only the
+ direct client errors and they are not internal
+ <span class="application">pgbench</span> errors.
+ </p></li></ul></div><p>
+ </p><p>
+ A client's run is aborted in case of a serious error; for example, the
+ connection with the database server was lost or the end of script was reached
+ without completing the last transaction. In addition, if execution of an SQL
+ or meta command fails for reasons other than serialization or deadlock errors,
+ the client is aborted. Otherwise, if an SQL command fails with serialization or
+ deadlock errors, the client is not aborted. In such cases, the current
+ transaction is rolled back, which also includes setting the client variables
+ as they were before the run of this transaction (it is assumed that one
+ transaction script contains only one transaction; see
+ <a class="xref" href="pgbench.html#TRANSACTIONS-AND-SCRIPTS" title="What Is the “Transaction” Actually Performed in pgbench?">What Is the "Transaction" Actually Performed in pgbench?</a> for more information).
+ Transactions with serialization or deadlock errors are repeated after
+ rollbacks until they complete successfully or reach the maximum
+ number of tries (specified by the <code class="option">--max-tries</code> option) / the maximum
+ time of retries (specified by the <code class="option">--latency-limit</code> option) / the end
+ of benchmark (specified by the <code class="option">--time</code> option). If
+ the last trial run fails, this transaction will be reported as failed but
+ the client is not aborted and continues to work.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Without specifying the <code class="option">--max-tries</code> option, a transaction will
+ never be retried after a serialization or deadlock error because its default
+ value is 1. Use an unlimited number of tries (<code class="literal">--max-tries=0</code>)
+ and the <code class="option">--latency-limit</code> option to limit only the maximum time
+ of tries. You can also use the <code class="option">--time</code> option to limit the
+ benchmark duration under an unlimited number of tries.
+ </p><p>
+ Be careful when repeating scripts that contain multiple transactions: the
+ script is always retried completely, so successful transactions can be
+ performed several times.
+ </p><p>
+ Be careful when repeating transactions with shell commands. Unlike the
+ results of SQL commands, the results of shell commands are not rolled back,
+ except for the variable value of the <code class="command">\setshell</code> command.
+ </p></div><p>
+ The latency of a successful transaction includes the entire time of
+ transaction execution with rollbacks and retries. The latency is measured
+ only for successful transactions and commands but not for failed transactions
+ or commands.
+ </p><p>
+ The main report contains the number of failed transactions. If the
+ <code class="option">--max-tries</code> option is not equal to 1, the main report also
+ contains statistics related to retries: the total number of retried
+ transactions and total number of retries. The per-script report inherits all
+ these fields from the main report. The per-statement report displays retry
+ statistics only if the <code class="option">--max-tries</code> option is not equal to 1.
+ </p><p>
+ If you want to group failures by basic types in per-transaction and
+ aggregation logs, as well as in the main and per-script reports, use the
+ <code class="option">--failures-detailed</code> option. If you also want to distinguish
+ all errors and failures (errors without retrying) by type including which
+ limit for retries was exceeded and how much it was exceeded by for the
+ serialization/deadlock failures, use the <code class="option">--verbose-errors</code>
+ option.
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.10"><h3>Good Practices</h3><p>
+ It is very easy to use <span class="application">pgbench</span> to produce completely
+ meaningless numbers. Here are some guidelines to help you get useful
+ results.
+ </p><p>
+ In the first place, <span class="emphasis"><em>never</em></span> believe any test that runs
+ for only a few seconds. Use the <code class="option">-t</code> or <code class="option">-T</code> option
+ to make the run last at least a few minutes, so as to average out noise.
+ In some cases you could need hours to get numbers that are reproducible.
+ It's a good idea to try the test run a few times, to find out if your
+ numbers are reproducible or not.
+ </p><p>
+ For the default TPC-B-like test scenario, the initialization scale factor
+ (<code class="option">-s</code>) should be at least as large as the largest number of
+ clients you intend to test (<code class="option">-c</code>); else you'll mostly be
+ measuring update contention. There are only <code class="option">-s</code> rows in
+ the <code class="structname">pgbench_branches</code> table, and every transaction wants to
+ update one of them, so <code class="option">-c</code> values in excess of <code class="option">-s</code>
+ will undoubtedly result in lots of transactions blocked waiting for
+ other transactions.
+ </p><p>
+ The default test scenario is also quite sensitive to how long it's been
+ since the tables were initialized: accumulation of dead rows and dead space
+ in the tables changes the results. To understand the results you must keep
+ track of the total number of updates and when vacuuming happens. If
+ autovacuum is enabled it can result in unpredictable changes in measured
+ performance.
+ </p><p>
+ A limitation of <span class="application">pgbench</span> is that it can itself become
+ the bottleneck when trying to test a large number of client sessions.
+ This can be alleviated by running <span class="application">pgbench</span> on a different
+ machine from the database server, although low network latency will be
+ essential. It might even be useful to run several <span class="application">pgbench</span>
+ instances concurrently, on several client machines, against the same
+ database server.
+ </p></div><div class="refsect2" id="id-1.9.4.11.9.11"><h3>Security</h3><p>
+ If untrusted users have access to a database that has not adopted a
+ <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,
+ do not run <span class="application">pgbench</span> in that
+ database. <span class="application">pgbench</span> uses unqualified names and
+ does not manipulate the search path.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgbasebackup.html" title="pg_basebackup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgconfig.html" title="pg_config">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_basebackup</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_config</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgbuffercache.html b/doc/src/sgml/html/pgbuffercache.html
new file mode 100644
index 0000000..a1c8139
--- /dev/null
+++ b/doc/src/sgml/html/pgbuffercache.html
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.27. pg_buffercache</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="passwordcheck.html" title="F.26. passwordcheck" /><link rel="next" href="pgcrypto.html" title="F.28. pgcrypto" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.27. pg_buffercache</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="passwordcheck.html" title="F.26. passwordcheck">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgcrypto.html" title="F.28. pgcrypto">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGBUFFERCACHE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.27. pg_buffercache</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.7">F.27.1. The <code class="structname">pg_buffercache</code> View</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.8">F.27.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#id-1.11.7.36.9">F.27.3. Authors</a></span></dt></dl></div><a id="id-1.11.7.36.2" class="indexterm"></a><p>
+ The <code class="filename">pg_buffercache</code> module provides a means for
+ examining what's happening in the shared buffer cache in real time.
+ </p><a id="id-1.11.7.36.4" class="indexterm"></a><p>
+ The module provides a C function <code class="function">pg_buffercache_pages</code>
+ that returns a set of records, plus a view
+ <code class="structname">pg_buffercache</code> that wraps the function for
+ convenient use.
+ </p><p>
+ By default, use is restricted to superusers and roles with privileges of the
+ <code class="literal">pg_monitor</code> role. Access may be granted to others
+ using <code class="command">GRANT</code>.
+ </p><div class="sect2" id="id-1.11.7.36.7"><div class="titlepage"><div><div><h3 class="title">F.27.1. The <code class="structname">pg_buffercache</code> View</h3></div></div></div><p>
+ The definitions of the columns exposed by the view are shown in <a class="xref" href="pgbuffercache.html#PGBUFFERCACHE-COLUMNS" title="Table F.15. pg_buffercache Columns">Table F.15</a>.
+ </p><div class="table" id="PGBUFFERCACHE-COLUMNS"><p class="title"><strong>Table F.15. <code class="structname">pg_buffercache</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_buffercache Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">bufferid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ ID, in the range 1..<code class="varname">shared_buffers</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relfilenode</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relfilenode</code>)
+ </p>
+ <p>
+ Filenode number of the relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reltablespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Tablespace OID of the relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reldatabase</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Database OID of the relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relforknumber</code> <code class="type">smallint</code>
+ </p>
+ <p>
+ Fork number within the relation; see
+ <code class="filename">common/relpath.h</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relblocknumber</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Page number within the relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">isdirty</code> <code class="type">boolean</code>
+ </p>
+ <p>
+ Is the page dirty?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usagecount</code> <code class="type">smallint</code>
+ </p>
+ <p>
+ Clock-sweep access count
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pinning_backends</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Number of backends pinning this buffer
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ There is one row for each buffer in the shared cache. Unused buffers are
+ shown with all fields null except <code class="structfield">bufferid</code>. Shared system
+ catalogs are shown as belonging to database zero.
+ </p><p>
+ Because the cache is shared by all the databases, there will normally be
+ pages from relations not belonging to the current database. This means
+ that there may not be matching join rows in <code class="structname">pg_class</code> for
+ some rows, or that there could even be incorrect joins. If you are
+ trying to join against <code class="structname">pg_class</code>, it's a good idea to
+ restrict the join to rows having <code class="structfield">reldatabase</code> equal to
+ the current database's OID or zero.
+ </p><p>
+ Since buffer manager locks are not taken to copy the buffer state data that
+ the view will display, accessing <code class="structname">pg_buffercache</code> view
+ has less impact on normal buffer activity but it doesn't provide a consistent
+ set of results across all buffers. However, we ensure that the information of
+ each buffer is self-consistent.
+ </p></div><div class="sect2" id="id-1.11.7.36.8"><div class="titlepage"><div><div><h3 class="title">F.27.2. Sample Output</h3></div></div></div><pre class="screen">
+regression=# SELECT n.nspname, c.relname, count(*) AS buffers
+ FROM pg_buffercache b JOIN pg_class c
+ ON b.relfilenode = pg_relation_filenode(c.oid) AND
+ b.reldatabase IN (0, (SELECT oid FROM pg_database
+ WHERE datname = current_database()))
+ JOIN pg_namespace n ON n.oid = c.relnamespace
+ GROUP BY n.nspname, c.relname
+ ORDER BY 3 DESC
+ LIMIT 10;
+
+ nspname | relname | buffers
+------------+------------------------+---------
+ public | delete_test_table | 593
+ public | delete_test_table_pkey | 494
+ pg_catalog | pg_attribute | 472
+ public | quad_poly_tbl | 353
+ public | tenk2 | 349
+ public | tenk1 | 349
+ public | gin_test_idx | 306
+ pg_catalog | pg_largeobject | 206
+ public | gin_test_tbl | 188
+ public | spgist_text_tbl | 182
+(10 rows)
+</pre></div><div class="sect2" id="id-1.11.7.36.9"><div class="titlepage"><div><div><h3 class="title">F.27.3. Authors</h3></div></div></div><p>
+ Mark Kirkwood <code class="email">&lt;<a class="email" href="mailto:markir@paradise.net.nz">markir@paradise.net.nz</a>&gt;</code>
+ </p><p>
+ Design suggestions: Neil Conway <code class="email">&lt;<a class="email" href="mailto:neilc@samurai.com">neilc@samurai.com</a>&gt;</code>
+ </p><p>
+ Debugging advice: Tom Lane <code class="email">&lt;<a class="email" href="mailto:tgl@sss.pgh.pa.us">tgl@sss.pgh.pa.us</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="passwordcheck.html" title="F.26. passwordcheck">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgcrypto.html" title="F.28. pgcrypto">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.26. passwordcheck </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.28. pgcrypto</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgcrypto.html b/doc/src/sgml/html/pgcrypto.html
new file mode 100644
index 0000000..582ac48
--- /dev/null
+++ b/doc/src/sgml/html/pgcrypto.html
@@ -0,0 +1,544 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.28. pgcrypto</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgbuffercache.html" title="F.27. pg_buffercache" /><link rel="next" href="pgfreespacemap.html" title="F.29. pg_freespacemap" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.28. pgcrypto</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgbuffercache.html" title="F.27. pg_buffercache">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgfreespacemap.html" title="F.29. pg_freespacemap">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGCRYPTO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.28. pgcrypto</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.7">F.28.1. General Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.8">F.28.2. Password Hashing Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.9">F.28.3. PGP Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.10">F.28.4. Raw Encryption Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.11">F.28.5. Random-Data Functions</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.12">F.28.6. Notes</a></span></dt><dt><span class="sect2"><a href="pgcrypto.html#id-1.11.7.37.13">F.28.7. Author</a></span></dt></dl></div><a id="id-1.11.7.37.2" class="indexterm"></a><a id="id-1.11.7.37.3" class="indexterm"></a><p>
+ The <code class="filename">pgcrypto</code> module provides cryptographic functions for
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><p>
+ <code class="filename">pgcrypto</code> requires OpenSSL and won't be installed if
+ OpenSSL support was not selected when PostgreSQL was built.
+ </p><div class="sect2" id="id-1.11.7.37.7"><div class="titlepage"><div><div><h3 class="title">F.28.1. General Hashing Functions</h3></div></div></div><div class="sect3" id="id-1.11.7.37.7.2"><div class="titlepage"><div><div><h4 class="title">F.28.1.1. <code class="function">digest()</code></h4></div></div></div><a id="id-1.11.7.37.7.2.2" class="indexterm"></a><pre class="synopsis">
+digest(data text, type text) returns bytea
+digest(data bytea, type text) returns bytea
+</pre><p>
+ Computes a binary hash of the given <em class="parameter"><code>data</code></em>.
+ <em class="parameter"><code>type</code></em> is the algorithm to use.
+ Standard algorithms are <code class="literal">md5</code>, <code class="literal">sha1</code>,
+ <code class="literal">sha224</code>, <code class="literal">sha256</code>,
+ <code class="literal">sha384</code> and <code class="literal">sha512</code>.
+ Moreover, any digest algorithm <span class="productname">OpenSSL</span> supports
+ is automatically picked up.
+ </p><p>
+ If you want the digest as a hexadecimal string, use
+ <code class="function">encode()</code> on the result. For example:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
+ SELECT encode(digest($1, 'sha1'), 'hex')
+$$ LANGUAGE SQL STRICT IMMUTABLE;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.11.7.37.7.3"><div class="titlepage"><div><div><h4 class="title">F.28.1.2. <code class="function">hmac()</code></h4></div></div></div><a id="id-1.11.7.37.7.3.2" class="indexterm"></a><pre class="synopsis">
+hmac(data text, key text, type text) returns bytea
+hmac(data bytea, key bytea, type text) returns bytea
+</pre><p>
+ Calculates hashed MAC for <em class="parameter"><code>data</code></em> with key <em class="parameter"><code>key</code></em>.
+ <em class="parameter"><code>type</code></em> is the same as in <code class="function">digest()</code>.
+ </p><p>
+ This is similar to <code class="function">digest()</code> but the hash can only be
+ recalculated knowing the key. This prevents the scenario of someone
+ altering data and also changing the hash to match.
+ </p><p>
+ If the key is larger than the hash block size it will first be hashed and
+ the result will be used as key.
+ </p></div></div><div class="sect2" id="id-1.11.7.37.8"><div class="titlepage"><div><div><h3 class="title">F.28.2. Password Hashing Functions</h3></div></div></div><p>
+ The functions <code class="function">crypt()</code> and <code class="function">gen_salt()</code>
+ are specifically designed for hashing passwords.
+ <code class="function">crypt()</code> does the hashing and <code class="function">gen_salt()</code>
+ prepares algorithm parameters for it.
+ </p><p>
+ The algorithms in <code class="function">crypt()</code> differ from the usual
+ MD5 or SHA1 hashing algorithms in the following respects:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ They are slow. As the amount of data is so small, this is the only
+ way to make brute-forcing passwords hard.
+ </p></li><li class="listitem"><p>
+ They use a random value, called the <em class="firstterm">salt</em>, so that users
+ having the same password will have different encrypted passwords.
+ This is also an additional defense against reversing the algorithm.
+ </p></li><li class="listitem"><p>
+ They include the algorithm type in the result, so passwords hashed with
+ different algorithms can co-exist.
+ </p></li><li class="listitem"><p>
+ Some of them are adaptive — that means when computers get
+ faster, you can tune the algorithm to be slower, without
+ introducing incompatibility with existing passwords.
+ </p></li></ol></div><p>
+ <a class="xref" href="pgcrypto.html#PGCRYPTO-CRYPT-ALGORITHMS" title="Table F.16. Supported Algorithms for crypt()">Table F.16</a> lists the algorithms
+ supported by the <code class="function">crypt()</code> function.
+ </p><div class="table" id="PGCRYPTO-CRYPT-ALGORITHMS"><p class="title"><strong>Table F.16. Supported Algorithms for <code class="function">crypt()</code></strong></p><div class="table-contents"><table class="table" summary="Supported Algorithms for crypt()" border="1"><colgroup><col /><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Max Password Length</th><th>Adaptive?</th><th>Salt Bits</th><th>Output Length</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">bf</code></td><td>72</td><td>yes</td><td>128</td><td>60</td><td>Blowfish-based, variant 2a</td></tr><tr><td><code class="literal">md5</code></td><td>unlimited</td><td>no</td><td>48</td><td>34</td><td>MD5-based crypt</td></tr><tr><td><code class="literal">xdes</code></td><td>8</td><td>yes</td><td>24</td><td>20</td><td>Extended DES</td></tr><tr><td><code class="literal">des</code></td><td>8</td><td>no</td><td>12</td><td>13</td><td>Original UNIX crypt</td></tr></tbody></table></div></div><br class="table-break" /><div class="sect3" id="id-1.11.7.37.8.7"><div class="titlepage"><div><div><h4 class="title">F.28.2.1. <code class="function">crypt()</code></h4></div></div></div><a id="id-1.11.7.37.8.7.2" class="indexterm"></a><pre class="synopsis">
+crypt(password text, salt text) returns text
+</pre><p>
+ Calculates a crypt(3)-style hash of <em class="parameter"><code>password</code></em>.
+ When storing a new password, you need to use
+ <code class="function">gen_salt()</code> to generate a new <em class="parameter"><code>salt</code></em> value.
+ To check a password, pass the stored hash value as <em class="parameter"><code>salt</code></em>,
+ and test whether the result matches the stored value.
+ </p><p>
+ Example of setting a new password:
+</p><pre class="programlisting">
+UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));
+</pre><p>
+ </p><p>
+ Example of authentication:
+</p><pre class="programlisting">
+SELECT (pswhash = crypt('entered password', pswhash)) AS pswmatch FROM ... ;
+</pre><p>
+ This returns <code class="literal">true</code> if the entered password is correct.
+ </p></div><div class="sect3" id="id-1.11.7.37.8.8"><div class="titlepage"><div><div><h4 class="title">F.28.2.2. <code class="function">gen_salt()</code></h4></div></div></div><a id="id-1.11.7.37.8.8.2" class="indexterm"></a><pre class="synopsis">
+gen_salt(type text [, iter_count integer ]) returns text
+</pre><p>
+ Generates a new random salt string for use in <code class="function">crypt()</code>.
+ The salt string also tells <code class="function">crypt()</code> which algorithm to use.
+ </p><p>
+ The <em class="parameter"><code>type</code></em> parameter specifies the hashing algorithm.
+ The accepted types are: <code class="literal">des</code>, <code class="literal">xdes</code>,
+ <code class="literal">md5</code> and <code class="literal">bf</code>.
+ </p><p>
+ The <em class="parameter"><code>iter_count</code></em> parameter lets the user specify the iteration
+ count, for algorithms that have one.
+ The higher the count, the more time it takes to hash
+ the password and therefore the more time to break it. Although with
+ too high a count the time to calculate a hash may be several years
+ — which is somewhat impractical. If the <em class="parameter"><code>iter_count</code></em>
+ parameter is omitted, the default iteration count is used.
+ Allowed values for <em class="parameter"><code>iter_count</code></em> depend on the algorithm and
+ are shown in <a class="xref" href="pgcrypto.html#PGCRYPTO-ICFC-TABLE" title="Table F.17. Iteration Counts for crypt()">Table F.17</a>.
+ </p><div class="table" id="PGCRYPTO-ICFC-TABLE"><p class="title"><strong>Table F.17. Iteration Counts for <code class="function">crypt()</code></strong></p><div class="table-contents"><table class="table" summary="Iteration Counts for crypt()" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Default</th><th>Min</th><th>Max</th></tr></thead><tbody><tr><td><code class="literal">xdes</code></td><td>725</td><td>1</td><td>16777215</td></tr><tr><td><code class="literal">bf</code></td><td>6</td><td>4</td><td>31</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For <code class="literal">xdes</code> there is an additional limitation that the
+ iteration count must be an odd number.
+ </p><p>
+ To pick an appropriate iteration count, consider that
+ the original DES crypt was designed to have the speed of 4 hashes per
+ second on the hardware of that time.
+ Slower than 4 hashes per second would probably dampen usability.
+ Faster than 100 hashes per second is probably too fast.
+ </p><p>
+ <a class="xref" href="pgcrypto.html#PGCRYPTO-HASH-SPEED-TABLE" title="Table F.18. Hash Algorithm Speeds">Table F.18</a> gives an overview of the relative slowness
+ of different hashing algorithms.
+ The table shows how much time it would take to try all
+ combinations of characters in an 8-character password, assuming
+ that the password contains either only lower case letters, or
+ upper- and lower-case letters and numbers.
+ In the <code class="literal">crypt-bf</code> entries, the number after a slash is
+ the <em class="parameter"><code>iter_count</code></em> parameter of
+ <code class="function">gen_salt</code>.
+ </p><div class="table" id="PGCRYPTO-HASH-SPEED-TABLE"><p class="title"><strong>Table F.18. Hash Algorithm Speeds</strong></p><div class="table-contents"><table class="table" summary="Hash Algorithm Speeds" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Hashes/sec</th><th>For <code class="literal">[a-z]</code></th><th>For <code class="literal">[A-Za-z0-9]</code></th><th>Duration relative to <code class="literal">md5 hash</code></th></tr></thead><tbody><tr><td><code class="literal">crypt-bf/8</code></td><td>1792</td><td>4 years</td><td>3927 years</td><td>100k</td></tr><tr><td><code class="literal">crypt-bf/7</code></td><td>3648</td><td>2 years</td><td>1929 years</td><td>50k</td></tr><tr><td><code class="literal">crypt-bf/6</code></td><td>7168</td><td>1 year</td><td>982 years</td><td>25k</td></tr><tr><td><code class="literal">crypt-bf/5</code></td><td>13504</td><td>188 days</td><td>521 years</td><td>12.5k</td></tr><tr><td><code class="literal">crypt-md5</code></td><td>171584</td><td>15 days</td><td>41 years</td><td>1k</td></tr><tr><td><code class="literal">crypt-des</code></td><td>23221568</td><td>157.5 minutes</td><td>108 days</td><td>7</td></tr><tr><td><code class="literal">sha1</code></td><td>37774272</td><td>90 minutes</td><td>68 days</td><td>4</td></tr><tr><td><code class="literal">md5</code> (hash)</td><td>150085504</td><td>22.5 minutes</td><td>17 days</td><td>1</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Notes:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The machine used is an Intel Mobile Core i3.
+ </p></li><li class="listitem"><p>
+ <code class="literal">crypt-des</code> and <code class="literal">crypt-md5</code> algorithm numbers are
+ taken from John the Ripper v1.6.38 <code class="literal">-test</code> output.
+ </p></li><li class="listitem"><p>
+ <code class="literal">md5 hash</code> numbers are from mdcrack 1.2.
+ </p></li><li class="listitem"><p>
+ <code class="literal">sha1</code> numbers are from lcrack-20031130-beta.
+ </p></li><li class="listitem"><p>
+ <code class="literal">crypt-bf</code> numbers are taken using a simple program that
+ loops over 1000 8-character passwords. That way I can show the speed
+ with different numbers of iterations. For reference: <code class="literal">john
+ -test</code> shows 13506 loops/sec for <code class="literal">crypt-bf/5</code>.
+ (The very small
+ difference in results is in accordance with the fact that the
+ <code class="literal">crypt-bf</code> implementation in <code class="filename">pgcrypto</code>
+ is the same one used in John the Ripper.)
+ </p></li></ul></div><p>
+ Note that <span class="quote">“<span class="quote">try all combinations</span>”</span> is not a realistic exercise.
+ Usually password cracking is done with the help of dictionaries, which
+ contain both regular words and various mutations of them. So, even
+ somewhat word-like passwords could be cracked much faster than the above
+ numbers suggest, while a 6-character non-word-like password may escape
+ cracking. Or not.
+ </p></div></div><div class="sect2" id="id-1.11.7.37.9"><div class="titlepage"><div><div><h3 class="title">F.28.3. PGP Encryption Functions</h3></div></div></div><p>
+ The functions here implement the encryption part of the OpenPGP
+ (<a class="ulink" href="https://tools.ietf.org/html/rfc4880" target="_top">RFC 4880</a>)
+ standard. Supported are both symmetric-key and public-key encryption.
+ </p><p>
+ An encrypted PGP message consists of 2 parts, or <em class="firstterm">packets</em>:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Packet containing a session key — either symmetric-key or public-key
+ encrypted.
+ </p></li><li class="listitem"><p>
+ Packet containing data encrypted with the session key.
+ </p></li></ul></div><p>
+ When encrypting with a symmetric key (i.e., a password):
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ The given password is hashed using a String2Key (S2K) algorithm. This is
+ rather similar to <code class="function">crypt()</code> algorithms — purposefully
+ slow and with random salt — but it produces a full-length binary
+ key.
+ </p></li><li class="listitem"><p>
+ If a separate session key is requested, a new random key will be
+ generated. Otherwise the S2K key will be used directly as the session
+ key.
+ </p></li><li class="listitem"><p>
+ If the S2K key is to be used directly, then only S2K settings will be put
+ into the session key packet. Otherwise the session key will be encrypted
+ with the S2K key and put into the session key packet.
+ </p></li></ol></div><p>
+ When encrypting with a public key:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ A new random session key is generated.
+ </p></li><li class="listitem"><p>
+ It is encrypted using the public key and put into the session key packet.
+ </p></li></ol></div><p>
+ In either case the data to be encrypted is processed as follows:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Optional data-manipulation: compression, conversion to UTF-8,
+ and/or conversion of line-endings.
+ </p></li><li class="listitem"><p>
+ The data is prefixed with a block of random bytes. This is equivalent
+ to using a random IV.
+ </p></li><li class="listitem"><p>
+ A SHA1 hash of the random prefix and data is appended.
+ </p></li><li class="listitem"><p>
+ All this is encrypted with the session key and placed in the data packet.
+ </p></li></ol></div><div class="sect3" id="id-1.11.7.37.9.11"><div class="titlepage"><div><div><h4 class="title">F.28.3.1. <code class="function">pgp_sym_encrypt()</code></h4></div></div></div><a id="id-1.11.7.37.9.11.2" class="indexterm"></a><a id="id-1.11.7.37.9.11.3" class="indexterm"></a><pre class="synopsis">
+pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
+pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea
+</pre><p>
+ Encrypt <em class="parameter"><code>data</code></em> with a symmetric PGP key <em class="parameter"><code>psw</code></em>.
+ The <em class="parameter"><code>options</code></em> parameter can contain option settings,
+ as described below.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.12"><div class="titlepage"><div><div><h4 class="title">F.28.3.2. <code class="function">pgp_sym_decrypt()</code></h4></div></div></div><a id="id-1.11.7.37.9.12.2" class="indexterm"></a><a id="id-1.11.7.37.9.12.3" class="indexterm"></a><pre class="synopsis">
+pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
+pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea
+</pre><p>
+ Decrypt a symmetric-key-encrypted PGP message.
+ </p><p>
+ Decrypting <code class="type">bytea</code> data with <code class="function">pgp_sym_decrypt</code> is disallowed.
+ This is to avoid outputting invalid character data. Decrypting
+ originally textual data with <code class="function">pgp_sym_decrypt_bytea</code> is fine.
+ </p><p>
+ The <em class="parameter"><code>options</code></em> parameter can contain option settings,
+ as described below.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.13"><div class="titlepage"><div><div><h4 class="title">F.28.3.3. <code class="function">pgp_pub_encrypt()</code></h4></div></div></div><a id="id-1.11.7.37.9.13.2" class="indexterm"></a><a id="id-1.11.7.37.9.13.3" class="indexterm"></a><pre class="synopsis">
+pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
+pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea
+</pre><p>
+ Encrypt <em class="parameter"><code>data</code></em> with a public PGP key <em class="parameter"><code>key</code></em>.
+ Giving this function a secret key will produce an error.
+ </p><p>
+ The <em class="parameter"><code>options</code></em> parameter can contain option settings,
+ as described below.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.14"><div class="titlepage"><div><div><h4 class="title">F.28.3.4. <code class="function">pgp_pub_decrypt()</code></h4></div></div></div><a id="id-1.11.7.37.9.14.2" class="indexterm"></a><a id="id-1.11.7.37.9.14.3" class="indexterm"></a><pre class="synopsis">
+pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text ]]) returns text
+pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text ]]) returns bytea
+</pre><p>
+ Decrypt a public-key-encrypted message. <em class="parameter"><code>key</code></em> must be the
+ secret key corresponding to the public key that was used to encrypt.
+ If the secret key is password-protected, you must give the password in
+ <em class="parameter"><code>psw</code></em>. If there is no password, but you want to specify
+ options, you need to give an empty password.
+ </p><p>
+ Decrypting <code class="type">bytea</code> data with <code class="function">pgp_pub_decrypt</code> is disallowed.
+ This is to avoid outputting invalid character data. Decrypting
+ originally textual data with <code class="function">pgp_pub_decrypt_bytea</code> is fine.
+ </p><p>
+ The <em class="parameter"><code>options</code></em> parameter can contain option settings,
+ as described below.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.15"><div class="titlepage"><div><div><h4 class="title">F.28.3.5. <code class="function">pgp_key_id()</code></h4></div></div></div><a id="id-1.11.7.37.9.15.2" class="indexterm"></a><pre class="synopsis">
+pgp_key_id(bytea) returns text
+</pre><p>
+ <code class="function">pgp_key_id</code> extracts the key ID of a PGP public or secret key.
+ Or it gives the key ID that was used for encrypting the data, if given
+ an encrypted message.
+ </p><p>
+ It can return 2 special key IDs:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">SYMKEY</code>
+ </p><p>
+ The message is encrypted with a symmetric key.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ANYKEY</code>
+ </p><p>
+ The message is public-key encrypted, but the key ID has been removed.
+ That means you will need to try all your secret keys on it to see
+ which one decrypts it. <code class="filename">pgcrypto</code> itself does not produce
+ such messages.
+ </p></li></ul></div><p>
+ Note that different keys may have the same ID. This is rare but a normal
+ event. The client application should then try to decrypt with each one,
+ to see which fits — like handling <code class="literal">ANYKEY</code>.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.16"><div class="titlepage"><div><div><h4 class="title">F.28.3.6. <code class="function">armor()</code>, <code class="function">dearmor()</code></h4></div></div></div><a id="id-1.11.7.37.9.16.2" class="indexterm"></a><a id="id-1.11.7.37.9.16.3" class="indexterm"></a><pre class="synopsis">
+armor(data bytea [ , keys text[], values text[] ]) returns text
+dearmor(data text) returns bytea
+</pre><p>
+ These functions wrap/unwrap binary data into PGP ASCII-armor format,
+ which is basically Base64 with CRC and additional formatting.
+ </p><p>
+ If the <em class="parameter"><code>keys</code></em> and <em class="parameter"><code>values</code></em> arrays are specified,
+ an <em class="firstterm">armor header</em> is added to the armored format for each
+ key/value pair. Both arrays must be single-dimensional, and they must
+ be of the same length. The keys and values cannot contain any non-ASCII
+ characters.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.17"><div class="titlepage"><div><div><h4 class="title">F.28.3.7. <code class="function">pgp_armor_headers</code></h4></div></div></div><a id="id-1.11.7.37.9.17.2" class="indexterm"></a><pre class="synopsis">
+pgp_armor_headers(data text, key out text, value out text) returns setof record
+</pre><p>
+ <code class="function">pgp_armor_headers()</code> extracts the armor headers from
+ <em class="parameter"><code>data</code></em>. The return value is a set of rows with two columns,
+ key and value. If the keys or values contain any non-ASCII characters,
+ they are treated as UTF-8.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.18"><div class="titlepage"><div><div><h4 class="title">F.28.3.8. Options for PGP Functions</h4></div></div></div><p>
+ Options are named to be similar to GnuPG. An option's value should be
+ given after an equal sign; separate options from each other with commas.
+ For example:
+</p><pre class="programlisting">
+pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')
+</pre><p>
+ </p><p>
+ All of the options except <code class="literal">convert-crlf</code> apply only to
+ encrypt functions. Decrypt functions get the parameters from the PGP
+ data.
+ </p><p>
+ The most interesting options are probably
+ <code class="literal">compress-algo</code> and <code class="literal">unicode-mode</code>.
+ The rest should have reasonable defaults.
+ </p><div class="sect4" id="id-1.11.7.37.9.18.5"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.1. cipher-algo</h5></div></div></div><p>
+ Which cipher algorithm to use.
+ </p><div class="literallayout"><p><br />
+Values: bf, aes128, aes192, aes256, 3des, cast5<br />
+Default: aes128<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.6"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.2. compress-algo</h5></div></div></div><p>
+ Which compression algorithm to use. Only available if
+ <span class="productname">PostgreSQL</span> was built with zlib.
+ </p><div class="literallayout"><p><br />
+Values:<br />
+  0 - no compression<br />
+  1 - ZIP compression<br />
+  2 - ZLIB compression (= ZIP plus meta-data and block CRCs)<br />
+Default: 0<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.7"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.3. compress-level</h5></div></div></div><p>
+ How much to compress. Higher levels compress smaller but are slower.
+ 0 disables compression.
+ </p><div class="literallayout"><p><br />
+Values: 0, 1-9<br />
+Default: 6<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.8"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.4. convert-crlf</h5></div></div></div><p>
+ Whether to convert <code class="literal">\n</code> into <code class="literal">\r\n</code> when
+ encrypting and <code class="literal">\r\n</code> to <code class="literal">\n</code> when
+ decrypting. <acronym class="acronym">RFC</acronym> 4880 specifies that text data should be stored using
+ <code class="literal">\r\n</code> line-feeds. Use this to get fully RFC-compliant
+ behavior.
+ </p><div class="literallayout"><p><br />
+Values: 0, 1<br />
+Default: 0<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.9"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.5. disable-mdc</h5></div></div></div><p>
+ Do not protect data with SHA-1. The only good reason to use this
+ option is to achieve compatibility with ancient PGP products, predating
+ the addition of SHA-1 protected packets to <acronym class="acronym">RFC</acronym> 4880.
+ Recent gnupg.org and pgp.com software supports it fine.
+ </p><div class="literallayout"><p><br />
+Values: 0, 1<br />
+Default: 0<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.10"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.6. sess-key</h5></div></div></div><p>
+ Use separate session key. Public-key encryption always uses a separate
+ session key; this option is for symmetric-key encryption, which by default
+ uses the S2K key directly.
+ </p><div class="literallayout"><p><br />
+Values: 0, 1<br />
+Default: 0<br />
+Applies to: pgp_sym_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.11"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.7. s2k-mode</h5></div></div></div><p>
+ Which S2K algorithm to use.
+ </p><div class="literallayout"><p><br />
+Values:<br />
+  0 - Without salt.  Dangerous!<br />
+  1 - With salt but with fixed iteration count.<br />
+  3 - Variable iteration count.<br />
+Default: 3<br />
+Applies to: pgp_sym_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.12"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.8. s2k-count</h5></div></div></div><p>
+ The number of iterations of the S2K algorithm to use. It must
+ be a value between 1024 and 65011712, inclusive.
+ </p><div class="literallayout"><p><br />
+Default: A random value between 65536 and 253952<br />
+Applies to: pgp_sym_encrypt, only with s2k-mode=3<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.13"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.9. s2k-digest-algo</h5></div></div></div><p>
+ Which digest algorithm to use in S2K calculation.
+ </p><div class="literallayout"><p><br />
+Values: md5, sha1<br />
+Default: sha1<br />
+Applies to: pgp_sym_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.14"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.10. s2k-cipher-algo</h5></div></div></div><p>
+ Which cipher to use for encrypting separate session key.
+ </p><div class="literallayout"><p><br />
+Values: bf, aes, aes128, aes192, aes256<br />
+Default: use cipher-algo<br />
+Applies to: pgp_sym_encrypt<br />
+</p></div></div><div class="sect4" id="id-1.11.7.37.9.18.15"><div class="titlepage"><div><div><h5 class="title">F.28.3.8.11. unicode-mode</h5></div></div></div><p>
+ Whether to convert textual data from database internal encoding to
+ UTF-8 and back. If your database already is UTF-8, no conversion will
+ be done, but the message will be tagged as UTF-8. Without this option
+ it will not be.
+ </p><div class="literallayout"><p><br />
+Values: 0, 1<br />
+Default: 0<br />
+Applies to: pgp_sym_encrypt, pgp_pub_encrypt<br />
+</p></div></div></div><div class="sect3" id="id-1.11.7.37.9.19"><div class="titlepage"><div><div><h4 class="title">F.28.3.9. Generating PGP Keys with GnuPG</h4></div></div></div><p>
+ To generate a new key:
+</p><pre class="programlisting">
+gpg --gen-key
+</pre><p>
+ </p><p>
+ The preferred key type is <span class="quote">“<span class="quote">DSA and Elgamal</span>”</span>.
+ </p><p>
+ For RSA encryption you must create either DSA or RSA sign-only key
+ as master and then add an RSA encryption subkey with
+ <code class="literal">gpg --edit-key</code>.
+ </p><p>
+ To list keys:
+</p><pre class="programlisting">
+gpg --list-secret-keys
+</pre><p>
+ </p><p>
+ To export a public key in ASCII-armor format:
+</p><pre class="programlisting">
+gpg -a --export KEYID &gt; public.key
+</pre><p>
+ </p><p>
+ To export a secret key in ASCII-armor format:
+</p><pre class="programlisting">
+gpg -a --export-secret-keys KEYID &gt; secret.key
+</pre><p>
+ </p><p>
+ You need to use <code class="function">dearmor()</code> on these keys before giving them to
+ the PGP functions. Or if you can handle binary data, you can drop
+ <code class="literal">-a</code> from the command.
+ </p><p>
+ For more details see <code class="literal">man gpg</code>,
+ <a class="ulink" href="https://www.gnupg.org/gph/en/manual.html" target="_top">The GNU
+ Privacy Handbook</a> and other documentation on
+ <a class="ulink" href="https://www.gnupg.org/" target="_top">https://www.gnupg.org/</a>.
+ </p></div><div class="sect3" id="id-1.11.7.37.9.20"><div class="titlepage"><div><div><h4 class="title">F.28.3.10. Limitations of PGP Code</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ No support for signing. That also means that it is not checked
+ whether the encryption subkey belongs to the master key.
+ </p></li><li class="listitem"><p>
+ No support for encryption key as master key. As such practice
+ is generally discouraged, this should not be a problem.
+ </p></li><li class="listitem"><p>
+ No support for several subkeys. This may seem like a problem, as this
+ is common practice. On the other hand, you should not use your regular
+ GPG/PGP keys with <code class="filename">pgcrypto</code>, but create new ones,
+ as the usage scenario is rather different.
+ </p></li></ul></div></div></div><div class="sect2" id="id-1.11.7.37.10"><div class="titlepage"><div><div><h3 class="title">F.28.4. Raw Encryption Functions</h3></div></div></div><p>
+ These functions only run a cipher over data; they don't have any advanced
+ features of PGP encryption. Therefore they have some major problems:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ They use user key directly as cipher key.
+ </p></li><li class="listitem"><p>
+ They don't provide any integrity checking, to see
+ if the encrypted data was modified.
+ </p></li><li class="listitem"><p>
+ They expect that users manage all encryption parameters
+ themselves, even IV.
+ </p></li><li class="listitem"><p>
+ They don't handle text.
+ </p></li></ol></div><p>
+ So, with the introduction of PGP encryption, usage of raw
+ encryption functions is discouraged.
+ </p><a id="id-1.11.7.37.10.5" class="indexterm"></a><a id="id-1.11.7.37.10.6" class="indexterm"></a><a id="id-1.11.7.37.10.7" class="indexterm"></a><a id="id-1.11.7.37.10.8" class="indexterm"></a><pre class="synopsis">
+encrypt(data bytea, key bytea, type text) returns bytea
+decrypt(data bytea, key bytea, type text) returns bytea
+
+encrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
+decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
+</pre><p>
+ Encrypt/decrypt data using the cipher method specified by
+ <em class="parameter"><code>type</code></em>. The syntax of the
+ <em class="parameter"><code>type</code></em> string is:
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>algorithm</code></em> [<span class="optional"> <code class="literal">-</code> <em class="replaceable"><code>mode</code></em> </span>] [<span class="optional"> <code class="literal">/pad:</code> <em class="replaceable"><code>padding</code></em> </span>]
+</pre><p>
+ where <em class="replaceable"><code>algorithm</code></em> is one of:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">bf</code> — Blowfish</p></li><li class="listitem"><p><code class="literal">aes</code> — AES (Rijndael-128, -192 or -256)</p></li></ul></div><p>
+ and <em class="replaceable"><code>mode</code></em> is one of:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">cbc</code> — next block depends on previous (default)
+ </p></li><li class="listitem"><p>
+ <code class="literal">ecb</code> — each block is encrypted separately (for
+ testing only)
+ </p></li></ul></div><p>
+ and <em class="replaceable"><code>padding</code></em> is one of:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">pkcs</code> — data may be any length (default)
+ </p></li><li class="listitem"><p>
+ <code class="literal">none</code> — data must be multiple of cipher block size
+ </p></li></ul></div><p>
+ </p><p>
+ So, for example, these are equivalent:
+</p><pre class="programlisting">
+encrypt(data, 'fooz', 'bf')
+encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
+</pre><p>
+ </p><p>
+ In <code class="function">encrypt_iv</code> and <code class="function">decrypt_iv</code>, the
+ <em class="parameter"><code>iv</code></em> parameter is the initial value for the CBC mode;
+ it is ignored for ECB.
+ It is clipped or padded with zeroes if not exactly block size.
+ It defaults to all zeroes in the functions without this parameter.
+ </p></div><div class="sect2" id="id-1.11.7.37.11"><div class="titlepage"><div><div><h3 class="title">F.28.5. Random-Data Functions</h3></div></div></div><a id="id-1.11.7.37.11.2" class="indexterm"></a><pre class="synopsis">
+gen_random_bytes(count integer) returns bytea
+</pre><p>
+ Returns <em class="parameter"><code>count</code></em> cryptographically strong random bytes.
+ At most 1024 bytes can be extracted at a time. This is to avoid
+ draining the randomness generator pool.
+ </p><a id="id-1.11.7.37.11.5" class="indexterm"></a><pre class="synopsis">
+gen_random_uuid() returns uuid
+</pre><p>
+ Returns a version 4 (random) UUID. (Obsolete, this function
+ internally calls the <a class="link" href="functions-uuid.html" title="9.14. UUID Functions">core
+ function</a> of the same name.)
+ </p></div><div class="sect2" id="id-1.11.7.37.12"><div class="titlepage"><div><div><h3 class="title">F.28.6. Notes</h3></div></div></div><div class="sect3" id="id-1.11.7.37.12.2"><div class="titlepage"><div><div><h4 class="title">F.28.6.1. Configuration</h4></div></div></div><p>
+ <code class="filename">pgcrypto</code> configures itself according to the findings of the
+ main PostgreSQL <code class="literal">configure</code> script. The options that
+ affect it are <code class="literal">--with-zlib</code> and
+ <code class="literal">--with-ssl=openssl</code>.
+ </p><p>
+ When compiled with zlib, PGP encryption functions are able to
+ compress data before encrypting.
+ </p><p>
+ <code class="filename">pgcrypto</code> requires <span class="productname">OpenSSL</span>.
+ Otherwise, it will not be built or installed.
+ </p><p>
+ When compiled against <span class="productname">OpenSSL</span> 3.0.0 and later
+ versions, the legacy provider must be activated in the
+ <code class="filename">openssl.cnf</code> configuration file in order to use older
+ ciphers like DES or Blowfish.
+ </p></div><div class="sect3" id="id-1.11.7.37.12.3"><div class="titlepage"><div><div><h4 class="title">F.28.6.2. NULL Handling</h4></div></div></div><p>
+ As is standard in SQL, all functions return NULL, if any of the arguments
+ are NULL. This may create security risks on careless usage.
+ </p></div><div class="sect3" id="id-1.11.7.37.12.4"><div class="titlepage"><div><div><h4 class="title">F.28.6.3. Security Limitations</h4></div></div></div><p>
+ All <code class="filename">pgcrypto</code> functions run inside the database server.
+ That means that all
+ the data and passwords move between <code class="filename">pgcrypto</code> and client
+ applications in clear text. Thus you must:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Connect locally or use SSL connections.</p></li><li class="listitem"><p>Trust both system and database administrator.</p></li></ol></div><p>
+ If you cannot, then better do crypto inside client application.
+ </p><p>
+ The implementation does not resist
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Side-channel_attack" target="_top">side-channel
+ attacks</a>. For example, the time required for
+ a <code class="filename">pgcrypto</code> decryption function to complete varies among
+ ciphertexts of a given size.
+ </p></div><div class="sect3" id="id-1.11.7.37.12.5"><div class="titlepage"><div><div><h4 class="title">F.28.6.4. Useful Reading</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.gnupg.org/gph/en/manual.html" target="_top">https://www.gnupg.org/gph/en/manual.html</a></p><p>The GNU Privacy Handbook.</p></li><li class="listitem"><p><a class="ulink" href="https://www.openwall.com/crypt/" target="_top">https://www.openwall.com/crypt/</a></p><p>Describes the crypt-blowfish algorithm.</p></li><li class="listitem"><p>
+ <a class="ulink" href="https://www.iusmentis.com/security/passphrasefaq/" target="_top">https://www.iusmentis.com/security/passphrasefaq/</a>
+ </p><p>How to choose a good password.</p></li><li class="listitem"><p><a class="ulink" href="http://world.std.com/~reinhold/diceware.html" target="_top">http://world.std.com/~reinhold/diceware.html</a></p><p>Interesting idea for picking passwords.</p></li><li class="listitem"><p>
+ <a class="ulink" href="http://www.interhack.net/people/cmcurtin/snake-oil-faq.html" target="_top">http://www.interhack.net/people/cmcurtin/snake-oil-faq.html</a>
+ </p><p>Describes good and bad cryptography.</p></li></ul></div></div><div class="sect3" id="id-1.11.7.37.12.6"><div class="titlepage"><div><div><h4 class="title">F.28.6.5. Technical References</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://tools.ietf.org/html/rfc4880" target="_top">https://tools.ietf.org/html/rfc4880</a></p><p>OpenPGP message format.</p></li><li class="listitem"><p><a class="ulink" href="https://tools.ietf.org/html/rfc1321" target="_top">https://tools.ietf.org/html/rfc1321</a></p><p>The MD5 Message-Digest Algorithm.</p></li><li class="listitem"><p><a class="ulink" href="https://tools.ietf.org/html/rfc2104" target="_top">https://tools.ietf.org/html/rfc2104</a></p><p>HMAC: Keyed-Hashing for Message Authentication.</p></li><li class="listitem"><p>
+ <a class="ulink" href="https://www.usenix.org/legacy/events/usenix99/provos.html" target="_top">https://www.usenix.org/legacy/events/usenix99/provos.html</a>
+ </p><p>Comparison of crypt-des, crypt-md5 and bcrypt algorithms.</p></li><li class="listitem"><p>
+ <a class="ulink" href="https://en.wikipedia.org/wiki/Fortuna_(PRNG)" target="_top">https://en.wikipedia.org/wiki/Fortuna_(PRNG)</a>
+ </p><p>Description of Fortuna CSPRNG.</p></li><li class="listitem"><p><a class="ulink" href="https://jlcooke.ca/random/" target="_top">https://jlcooke.ca/random/</a></p><p>Jean-Luc Cooke Fortuna-based <code class="filename">/dev/random</code> driver for Linux.</p></li></ul></div></div></div><div class="sect2" id="id-1.11.7.37.13"><div class="titlepage"><div><div><h3 class="title">F.28.7. Author</h3></div></div></div><p>
+ Marko Kreen <code class="email">&lt;<a class="email" href="mailto:markokr@gmail.com">markokr@gmail.com</a>&gt;</code>
+ </p><p>
+ <code class="filename">pgcrypto</code> uses code from the following sources:
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Algorithm</th><th>Author</th><th>Source origin</th></tr></thead><tbody><tr><td>DES crypt</td><td>David Burren and others</td><td>FreeBSD libcrypt</td></tr><tr><td>MD5 crypt</td><td>Poul-Henning Kamp</td><td>FreeBSD libcrypt</td></tr><tr><td>Blowfish crypt</td><td>Solar Designer</td><td>www.openwall.com</td></tr></tbody></table></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgbuffercache.html" title="F.27. pg_buffercache">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgfreespacemap.html" title="F.29. pg_freespacemap">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.27. pg_buffercache </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.29. pg_freespacemap</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgfreespacemap.html b/doc/src/sgml/html/pgfreespacemap.html
new file mode 100644
index 0000000..72483cc
--- /dev/null
+++ b/doc/src/sgml/html/pgfreespacemap.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.29. pg_freespacemap</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgcrypto.html" title="F.28. pgcrypto" /><link rel="next" href="pgprewarm.html" title="F.30. pg_prewarm" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.29. pg_freespacemap</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgcrypto.html" title="F.28. pgcrypto">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgprewarm.html" title="F.30. pg_prewarm">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGFREESPACEMAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.29. pg_freespacemap</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.5">F.29.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.6">F.29.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgfreespacemap.html#id-1.11.7.38.7">F.29.3. Author</a></span></dt></dl></div><a id="id-1.11.7.38.2" class="indexterm"></a><p>
+ The <code class="filename">pg_freespacemap</code> module provides a means for examining the
+ <a class="link" href="storage-fsm.html" title="73.3. Free Space Map">free space map</a> (<acronym class="acronym">FSM</acronym>).
+ It provides a function called <code class="function">pg_freespace</code>, or two
+ overloaded functions, to be precise. The functions show the value recorded in
+ the free space map for a given page, or for all pages in the relation.
+ </p><p>
+ By default use is restricted to superusers and roles with privileges of the
+ <code class="literal">pg_stat_scan_tables</code> role. Access may be granted to others
+ using <code class="command">GRANT</code>.
+ </p><div class="sect2" id="id-1.11.7.38.5"><div class="titlepage"><div><div><h3 class="title">F.29.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">pg_freespace(rel regclass IN, blkno bigint IN) returns int2</code>
+ <a id="id-1.11.7.38.5.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the amount of free space on the page of the relation, specified
+ by <code class="literal">blkno</code>, according to the <acronym class="acronym">FSM</acronym>.
+ </p></dd><dt><span class="term">
+ <code class="function">pg_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)</code>
+ </span></dt><dd><p>
+ Displays the amount of free space on each page of the relation,
+ according to the <acronym class="acronym">FSM</acronym>. A set of
+ <code class="literal">(blkno bigint, avail int2)</code>
+ tuples is returned, one tuple for each page in the relation.
+ </p></dd></dl></div><p>
+ The values stored in the free space map are not exact. They're rounded
+ to precision of 1/256th of <code class="symbol">BLCKSZ</code> (32 bytes with default <code class="symbol">BLCKSZ</code>), and
+ they're not kept fully up-to-date as tuples are inserted and updated.
+ </p><p>
+ For indexes, what is tracked is entirely-unused pages, rather than free
+ space within pages. Therefore, the values are not meaningful, just
+ whether a page is full or empty.
+ </p></div><div class="sect2" id="id-1.11.7.38.6"><div class="titlepage"><div><div><h3 class="title">F.29.2. Sample Output</h3></div></div></div><pre class="screen">
+postgres=# SELECT * FROM pg_freespace('foo');
+ blkno | avail
+-------+-------
+ 0 | 0
+ 1 | 0
+ 2 | 0
+ 3 | 32
+ 4 | 704
+ 5 | 704
+ 6 | 704
+ 7 | 1216
+ 8 | 704
+ 9 | 704
+ 10 | 704
+ 11 | 704
+ 12 | 704
+ 13 | 704
+ 14 | 704
+ 15 | 704
+ 16 | 704
+ 17 | 704
+ 18 | 704
+ 19 | 3648
+(20 rows)
+
+postgres=# SELECT * FROM pg_freespace('foo', 7);
+ pg_freespace
+--------------
+ 1216
+(1 row)
+</pre></div><div class="sect2" id="id-1.11.7.38.7"><div class="titlepage"><div><div><h3 class="title">F.29.3. Author</h3></div></div></div><p>
+ Original version by Mark Kirkwood <code class="email">&lt;<a class="email" href="mailto:markir@paradise.net.nz">markir@paradise.net.nz</a>&gt;</code>.
+ Rewritten in version 8.4 to suit new <acronym class="acronym">FSM</acronym> implementation
+ by Heikki Linnakangas <code class="email">&lt;<a class="email" href="mailto:heikki@enterprisedb.com">heikki@enterprisedb.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgcrypto.html" title="F.28. pgcrypto">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgprewarm.html" title="F.30. pg_prewarm">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.28. pgcrypto </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.30. pg_prewarm</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgprewarm.html b/doc/src/sgml/html/pgprewarm.html
new file mode 100644
index 0000000..4d9a4a2
--- /dev/null
+++ b/doc/src/sgml/html/pgprewarm.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.30. pg_prewarm</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgfreespacemap.html" title="F.29. pg_freespacemap" /><link rel="next" href="pgrowlocks.html" title="F.31. pgrowlocks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.30. pg_prewarm</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgfreespacemap.html" title="F.29. pg_freespacemap">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgrowlocks.html" title="F.31. pgrowlocks">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGPREWARM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.30. pg_prewarm</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.4">F.30.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.5">F.30.2. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#id-1.11.7.39.6">F.30.3. Author</a></span></dt></dl></div><a id="id-1.11.7.39.2" class="indexterm"></a><p>
+ The <code class="filename">pg_prewarm</code> module provides a convenient way
+ to load relation data into either the operating system buffer cache
+ or the <span class="productname">PostgreSQL</span> buffer cache. Prewarming
+ can be performed manually using the <code class="filename">pg_prewarm</code> function,
+ or can be performed automatically by including <code class="literal">pg_prewarm</code> in
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>. In the latter case, the
+ system will run a background worker which periodically records the contents
+ of shared buffers in a file called <code class="filename">autoprewarm.blocks</code> and
+ will, using 2 background workers, reload those same blocks after a restart.
+ </p><div class="sect2" id="id-1.11.7.39.4"><div class="titlepage"><div><div><h3 class="title">F.30.1. Functions</h3></div></div></div><pre class="synopsis">
+pg_prewarm(regclass, mode text default 'buffer', fork text default 'main',
+ first_block int8 default null,
+ last_block int8 default null) RETURNS int8
+</pre><p>
+ The first argument is the relation to be prewarmed. The second argument
+ is the prewarming method to be used, as further discussed below; the third
+ is the relation fork to be prewarmed, usually <code class="literal">main</code>.
+ The fourth argument is the first block number to prewarm
+ (<code class="literal">NULL</code> is accepted as a synonym for zero). The fifth
+ argument is the last block number to prewarm (<code class="literal">NULL</code>
+ means prewarm through the last block in the relation). The return value
+ is the number of blocks prewarmed.
+ </p><p>
+ There are three available prewarming methods. <code class="literal">prefetch</code>
+ issues asynchronous prefetch requests to the operating system, if this is
+ supported, or throws an error otherwise. <code class="literal">read</code> reads
+ the requested range of blocks; unlike <code class="literal">prefetch</code>, this is
+ synchronous and supported on all platforms and builds, but may be slower.
+ <code class="literal">buffer</code> reads the requested range of blocks into the
+ database buffer cache.
+ </p><p>
+ Note that with any of these methods, attempting to prewarm more blocks than
+ can be cached — by the OS when using <code class="literal">prefetch</code> or
+ <code class="literal">read</code>, or by <span class="productname">PostgreSQL</span> when
+ using <code class="literal">buffer</code> — will likely result in lower-numbered
+ blocks being evicted as higher numbered blocks are read in. Prewarmed data
+ also enjoys no special protection from cache evictions, so it is possible
+ that other system activity may evict the newly prewarmed blocks shortly
+ after they are read; conversely, prewarming may also evict other data from
+ cache. For these reasons, prewarming is typically most useful at startup,
+ when caches are largely empty.
+ </p><pre class="synopsis">
+autoprewarm_start_worker() RETURNS void
+</pre><p>
+ Launch the main autoprewarm worker. This will normally happen
+ automatically, but is useful if automatic prewarm was not configured at
+ server startup time and you wish to start up the worker at a later time.
+ </p><pre class="synopsis">
+autoprewarm_dump_now() RETURNS int8
+</pre><p>
+ Update <code class="filename">autoprewarm.blocks</code> immediately. This may be useful
+ if the autoprewarm worker is not running but you anticipate running it
+ after the next restart. The return value is the number of records written
+ to <code class="filename">autoprewarm.blocks</code>.
+ </p></div><div class="sect2" id="id-1.11.7.39.5"><div class="titlepage"><div><div><h3 class="title">F.30.2. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">pg_prewarm.autoprewarm</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.39.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls whether the server should run the autoprewarm worker. This is
+ on by default. This parameter can only be set at server start.
+ </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">pg_prewarm.autoprewarm_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.11.7.39.5.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This is the interval between updates to <code class="literal">autoprewarm.blocks</code>.
+ The default is 300 seconds. If set to 0, the file will not be
+ dumped at regular intervals, but only when the server is shut down.
+ </p></dd></dl></div><p>
+ These parameters must be set in <code class="filename">postgresql.conf</code>.
+ Typical usage might be:
+ </p><pre class="programlisting">
+# postgresql.conf
+shared_preload_libraries = 'pg_prewarm'
+
+pg_prewarm.autoprewarm = true
+pg_prewarm.autoprewarm_interval = 300s
+
+</pre></div><div class="sect2" id="id-1.11.7.39.6"><div class="titlepage"><div><div><h3 class="title">F.30.3. Author</h3></div></div></div><p>
+ Robert Haas <code class="email">&lt;<a class="email" href="mailto:rhaas@postgresql.org">rhaas@postgresql.org</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgfreespacemap.html" title="F.29. pg_freespacemap">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgrowlocks.html" title="F.31. pgrowlocks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.29. pg_freespacemap </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.31. pgrowlocks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgrowlocks.html b/doc/src/sgml/html/pgrowlocks.html
new file mode 100644
index 0000000..54e4e0b
--- /dev/null
+++ b/doc/src/sgml/html/pgrowlocks.html
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.31. pgrowlocks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgprewarm.html" title="F.30. pg_prewarm" /><link rel="next" href="pgstatstatements.html" title="F.32. pg_stat_statements" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.31. pgrowlocks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgprewarm.html" title="F.30. pg_prewarm">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgstatstatements.html" title="F.32. pg_stat_statements">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGROWLOCKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.31. pgrowlocks</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.5">F.31.1. Overview</a></span></dt><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.6">F.31.2. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgrowlocks.html#id-1.11.7.40.7">F.31.3. Author</a></span></dt></dl></div><a id="id-1.11.7.40.2" class="indexterm"></a><p>
+ The <code class="filename">pgrowlocks</code> module provides a function to show row
+ locking information for a specified table.
+ </p><p>
+ By default use is restricted to superusers, roles with privileges of the
+ <code class="literal">pg_stat_scan_tables</code> role, and users with
+ <code class="literal">SELECT</code> permissions on the table.
+ </p><div class="sect2" id="id-1.11.7.40.5"><div class="titlepage"><div><div><h3 class="title">F.31.1. Overview</h3></div></div></div><a id="id-1.11.7.40.5.2" class="indexterm"></a><pre class="synopsis">
+pgrowlocks(text) returns setof record
+</pre><p>
+ The parameter is the name of a table. The result is a set of records,
+ with one row for each locked row within the table. The output columns
+ are shown in <a class="xref" href="pgrowlocks.html#PGROWLOCKS-COLUMNS" title="Table F.19. pgrowlocks Output Columns">Table F.19</a>.
+ </p><div class="table" id="PGROWLOCKS-COLUMNS"><p class="title"><strong>Table F.19. <code class="function">pgrowlocks</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pgrowlocks Output Columns" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">locked_row</code></td><td><code class="type">tid</code></td><td>Tuple ID (TID) of locked row</td></tr><tr><td><code class="structfield">locker</code></td><td><code class="type">xid</code></td><td>Transaction ID of locker, or multixact ID if multitransaction</td></tr><tr><td><code class="structfield">multi</code></td><td><code class="type">boolean</code></td><td>True if locker is a multitransaction</td></tr><tr><td><code class="structfield">xids</code></td><td><code class="type">xid[]</code></td><td>Transaction IDs of lockers (more than one if multitransaction)</td></tr><tr><td><code class="structfield">modes</code></td><td><code class="type">text[]</code></td><td>Lock mode of lockers (more than one if multitransaction),
+ an array of <code class="literal">Key Share</code>, <code class="literal">Share</code>,
+ <code class="literal">For No Key Update</code>, <code class="literal">No Key Update</code>,
+ <code class="literal">For Update</code>, <code class="literal">Update</code>.</td></tr><tr><td><code class="structfield">pids</code></td><td><code class="type">integer[]</code></td><td>Process IDs of locking backends (more than one if multitransaction)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="function">pgrowlocks</code> takes <code class="literal">AccessShareLock</code> for the
+ target table and reads each row one by one to collect the row locking
+ information. This is not very speedy for a large table. Note that:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ If an <code class="literal">ACCESS EXCLUSIVE</code> lock is taken on the table,
+ <code class="function">pgrowlocks</code> will be blocked.
+ </p></li><li class="listitem"><p>
+ <code class="function">pgrowlocks</code> is not guaranteed to produce a
+ self-consistent snapshot. It is possible that a new row lock is taken,
+ or an old lock is freed, during its execution.
+ </p></li></ol></div><p>
+ <code class="function">pgrowlocks</code> does not show the contents of locked
+ rows. If you want to take a look at the row contents at the same time, you
+ could do something like this:
+
+</p><pre class="programlisting">
+SELECT * FROM accounts AS a, pgrowlocks('accounts') AS p
+ WHERE p.locked_row = a.ctid;
+</pre><p>
+
+ Be aware however that such a query will be very inefficient.
+ </p></div><div class="sect2" id="id-1.11.7.40.6"><div class="titlepage"><div><div><h3 class="title">F.31.2. Sample Output</h3></div></div></div><pre class="screen">
+=# SELECT * FROM pgrowlocks('t1');
+ locked_row | locker | multi | xids | modes | pids
+------------+--------+-------+-------+----------------+--------
+ (0,1) | 609 | f | {609} | {"For Share"} | {3161}
+ (0,2) | 609 | f | {609} | {"For Share"} | {3161}
+ (0,3) | 607 | f | {607} | {"For Update"} | {3107}
+ (0,4) | 607 | f | {607} | {"For Update"} | {3107}
+(4 rows)
+</pre></div><div class="sect2" id="id-1.11.7.40.7"><div class="titlepage"><div><div><h3 class="title">F.31.3. Author</h3></div></div></div><p>
+ Tatsuo Ishii
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgprewarm.html" title="F.30. pg_prewarm">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgstatstatements.html" title="F.32. pg_stat_statements">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.30. pg_prewarm </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.32. pg_stat_statements</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgstatstatements.html b/doc/src/sgml/html/pgstatstatements.html
new file mode 100644
index 0000000..c4766c4
--- /dev/null
+++ b/doc/src/sgml/html/pgstatstatements.html
@@ -0,0 +1,613 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.32. pg_stat_statements</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgrowlocks.html" title="F.31. pgrowlocks" /><link rel="next" href="pgstattuple.html" title="F.33. pgstattuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.32. pg_stat_statements</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgrowlocks.html" title="F.31. pgrowlocks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgstattuple.html" title="F.33. pgstattuple">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGSTATSTATEMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.32. pg_stat_statements</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.6">F.32.1. The <code class="structname">pg_stat_statements</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.7">F.32.2. The <code class="structname">pg_stat_statements_info</code> View</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.8">F.32.3. Functions</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.9">F.32.4. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.10">F.32.5. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgstatstatements.html#id-1.11.7.41.11">F.32.6. Authors</a></span></dt></dl></div><a id="id-1.11.7.41.2" class="indexterm"></a><p>
+ The <code class="filename">pg_stat_statements</code> module provides a means for
+ tracking planning and execution statistics of all SQL statements executed by
+ a server.
+ </p><p>
+ The module must be loaded by adding <code class="literal">pg_stat_statements</code> to
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> in
+ <code class="filename">postgresql.conf</code>, because it requires additional shared memory.
+ This means that a server restart is needed to add or remove the module.
+ In addition, query identifier calculation must be enabled in order for the
+ module to be active, which is done automatically if <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a>
+ is set to <code class="literal">auto</code> or <code class="literal">on</code>, or any third-party
+ module that calculates query identifiers is loaded.
+ </p><p>
+ When <code class="filename">pg_stat_statements</code> is active, it tracks
+ statistics across all databases of the server. To access and manipulate
+ these statistics, the module provides views
+ <code class="structname">pg_stat_statements</code> and
+ <code class="structname">pg_stat_statements_info</code>,
+ and the utility functions <code class="function">pg_stat_statements_reset</code> and
+ <code class="function">pg_stat_statements</code>. These are not available globally but
+ can be enabled for a specific database with
+ <code class="command">CREATE EXTENSION pg_stat_statements</code>.
+ </p><div class="sect2" id="id-1.11.7.41.6"><div class="titlepage"><div><div><h3 class="title">F.32.1. The <code class="structname">pg_stat_statements</code> View</h3></div></div></div><p>
+ The statistics gathered by the module are made available via a
+ view named <code class="structname">pg_stat_statements</code>. This view
+ contains one row for each distinct combination of database ID, user
+ ID, query ID and whether it's a top-level statement or not (up to
+ the maximum number of distinct statements that the module can track).
+ The columns of the view are shown in
+ <a class="xref" href="pgstatstatements.html#PGSTATSTATEMENTS-COLUMNS" title="Table F.20. pg_stat_statements Columns">Table F.20</a>.
+ </p><div class="table" id="PGSTATSTATEMENTS-COLUMNS"><p class="title"><strong>Table F.20. <code class="structname">pg_stat_statements</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stat_statements Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">userid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of user who executed the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dbid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of database in which the statement was executed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">toplevel</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the query was executed as a top-level statement
+ (always true if <code class="varname">pg_stat_statements.track</code> is set to
+ <code class="literal">top</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">queryid</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Hash code to identify identical normalized queries.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">query</code> <code class="type">text</code>
+ </p>
+ <p>
+ Text of a representative statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">plans</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times the statement was planned
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_plan_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent planning the statement, in milliseconds
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">min_plan_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Minimum time spent planning the statement, in milliseconds
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_plan_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Maximum time spent planning the statement, in milliseconds
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mean_plan_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Mean time spent planning the statement, in milliseconds
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stddev_plan_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Population standard deviation of time spent planning the statement,
+ in milliseconds
+ (if <code class="varname">pg_stat_statements.track_planning</code> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">calls</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times the statement was executed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_exec_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent executing the statement, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">min_exec_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Minimum time spent executing the statement, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_exec_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Maximum time spent executing the statement, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mean_exec_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Mean time spent executing the statement, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stddev_exec_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Population standard deviation of time spent executing the statement, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rows</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of rows retrieved or affected by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">shared_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of shared block cache hits by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">shared_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of shared blocks read by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">shared_blks_dirtied</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of shared blocks dirtied by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">shared_blks_written</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of shared blocks written by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_blks_hit</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of local block cache hits by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of local blocks read by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_blks_dirtied</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of local blocks dirtied by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_blks_written</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of local blocks written by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_blks_read</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of temp blocks read by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_blks_written</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of temp blocks written by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blk_read_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time the statement spent reading data file blocks, in milliseconds
+ (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blk_write_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time the statement spent writing data file blocks, in milliseconds
+ (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled, otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_blk_read_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time the statement spent reading temporary file blocks, in
+ milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temp_blk_write_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time the statement spent writing temporary file blocks, in
+ milliseconds (if <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled,
+ otherwise zero)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_records</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of WAL records generated by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_fpi</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of WAL full page images generated by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_bytes</code> <code class="type">numeric</code>
+ </p>
+ <p>
+ Total amount of WAL generated by the statement in bytes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_functions</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of functions JIT-compiled by the statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_generation_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent by the statement on generating JIT code, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_inlining_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times functions have been inlined
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_inlining_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent by the statement on inlining functions, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_optimization_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times the statement has been optimized
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_optimization_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent by the statement on optimizing, in milliseconds
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_emission_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of times code has been emitted
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">jit_emission_time</code> <code class="type">double precision</code>
+ </p>
+ <p>
+ Total time spent by the statement on emitting code, in milliseconds
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ For security reasons, only superusers and roles with privileges of the
+ <code class="literal">pg_read_all_stats</code> role are allowed to see the SQL text and
+ <code class="structfield">queryid</code> of queries executed by other users.
+ Other users can see the statistics, however, if the view has been installed
+ in their database.
+ </p><p>
+ Plannable queries (that is, <code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and <code class="command">MERGE</code>) are combined into a single
+ <code class="structname">pg_stat_statements</code> entry whenever they have identical query
+ structures according to an internal hash calculation. Typically, two
+ queries will be considered the same for this purpose if they are
+ semantically equivalent except for the values of literal constants
+ appearing in the query. Utility commands (that is, all other commands)
+ are compared strictly on the basis of their textual query strings, however.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The following details about constant replacement and
+ <code class="structfield">queryid</code> only apply when <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a> is enabled. If you use an external
+ module instead to compute <code class="structfield">queryid</code>, you
+ should refer to its documentation for details.
+ </p></div><p>
+ When a constant's value has been ignored for purposes of matching the query
+ to other queries, the constant is replaced by a parameter symbol, such
+ as <code class="literal">$1</code>, in the <code class="structname">pg_stat_statements</code>
+ display.
+ The rest of the query text is that of the first query that had the
+ particular <code class="structfield">queryid</code> hash value associated with the
+ <code class="structname">pg_stat_statements</code> entry.
+ </p><p>
+ In some cases, queries with visibly different texts might get merged into a
+ single <code class="structname">pg_stat_statements</code> entry. Normally this will happen
+ only for semantically equivalent queries, but there is a small chance of
+ hash collisions causing unrelated queries to be merged into one entry.
+ (This cannot happen for queries belonging to different users or databases,
+ however.)
+ </p><p>
+ Since the <code class="structfield">queryid</code> hash value is computed on the
+ post-parse-analysis representation of the queries, the opposite is
+ also possible: queries with identical texts might appear as
+ separate entries, if they have different meanings as a result of
+ factors such as different <code class="varname">search_path</code> settings.
+ </p><p>
+ Consumers of <code class="structname">pg_stat_statements</code> may wish to use
+ <code class="structfield">queryid</code> (perhaps in combination with
+ <code class="structfield">dbid</code> and <code class="structfield">userid</code>) as a more stable
+ and reliable identifier for each entry than its query text.
+ However, it is important to understand that there are only limited
+ guarantees around the stability of the <code class="structfield">queryid</code> hash
+ value. Since the identifier is derived from the
+ post-parse-analysis tree, its value is a function of, among other
+ things, the internal object identifiers appearing in this representation.
+ This has some counterintuitive implications. For example,
+ <code class="filename">pg_stat_statements</code> will consider two apparently-identical
+ queries to be distinct, if they reference a table that was dropped
+ and recreated between the executions of the two queries.
+ The hashing process is also sensitive to differences in
+ machine architecture and other facets of the platform.
+ Furthermore, it is not safe to assume that <code class="structfield">queryid</code>
+ will be stable across major versions of <span class="productname">PostgreSQL</span>.
+ </p><p>
+ As a rule of thumb, <code class="structfield">queryid</code> values can be assumed to be
+ stable and comparable only so long as the underlying server version and
+ catalog metadata details stay exactly the same. Two servers
+ participating in replication based on physical WAL replay can be expected
+ to have identical <code class="structfield">queryid</code> values for the same query.
+ However, logical replication schemes do not promise to keep replicas
+ identical in all relevant details, so <code class="structfield">queryid</code> will
+ not be a useful identifier for accumulating costs across a set of logical
+ replicas. If in doubt, direct testing is recommended.
+ </p><p>
+ The parameter symbols used to replace constants in
+ representative query texts start from the next number after the
+ highest <code class="literal">$</code><em class="replaceable"><code>n</code></em> parameter in the original query
+ text, or <code class="literal">$1</code> if there was none. It's worth noting that in
+ some cases there may be hidden parameter symbols that affect this
+ numbering. For example, <span class="application">PL/pgSQL</span> uses hidden parameter
+ symbols to insert values of function local variables into queries, so that
+ a <span class="application">PL/pgSQL</span> statement like <code class="literal">SELECT i + 1 INTO j</code>
+ would have representative text like <code class="literal">SELECT i + $2</code>.
+ </p><p>
+ The representative query texts are kept in an external disk file, and do
+ not consume shared memory. Therefore, even very lengthy query texts can
+ be stored successfully. However, if many long query texts are
+ accumulated, the external file might grow unmanageably large. As a
+ recovery method if that happens, <code class="filename">pg_stat_statements</code> may
+ choose to discard the query texts, whereupon all existing entries in
+ the <code class="structname">pg_stat_statements</code> view will show
+ null <code class="structfield">query</code> fields, though the statistics associated with
+ each <code class="structfield">queryid</code> are preserved. If this happens, consider
+ reducing <code class="varname">pg_stat_statements.max</code> to prevent
+ recurrences.
+ </p><p>
+ <code class="structfield">plans</code> and <code class="structfield">calls</code> aren't
+ always expected to match because planning and execution statistics are
+ updated at their respective end phase, and only for successful operations.
+ For example, if a statement is successfully planned but fails during
+ the execution phase, only its planning statistics will be updated.
+ If planning is skipped because a cached plan is used, only its execution
+ statistics will be updated.
+ </p></div><div class="sect2" id="id-1.11.7.41.7"><div class="titlepage"><div><div><h3 class="title">F.32.2. The <code class="structname">pg_stat_statements_info</code> View</h3></div></div></div><a id="id-1.11.7.41.7.2" class="indexterm"></a><p>
+ The statistics of the <code class="filename">pg_stat_statements</code> module
+ itself are tracked and made available via a view named
+ <code class="structname">pg_stat_statements_info</code>. This view contains
+ only a single row. The columns of the view are shown in
+ <a class="xref" href="pgstatstatements.html#PGSTATSTATEMENTSINFO-COLUMNS" title="Table F.21. pg_stat_statements_info Columns">Table F.21</a>.
+ </p><div class="table" id="PGSTATSTATEMENTSINFO-COLUMNS"><p class="title"><strong>Table F.21. <code class="structname">pg_stat_statements_info</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stat_statements_info Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dealloc</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of times <code class="structname">pg_stat_statements</code>
+ entries about the least-executed statements were deallocated
+ because more distinct statements than
+ <code class="varname">pg_stat_statements.max</code> were observed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">stats_reset</code> <code class="type">timestamp with time zone</code>
+ </p>
+ <p>
+ Time at which all statistics in the
+ <code class="structname">pg_stat_statements</code> view were last reset.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.41.8"><div class="titlepage"><div><div><h3 class="title">F.32.3. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">pg_stat_statements_reset(userid Oid, dbid Oid, queryid bigint) returns void</code>
+ <a id="id-1.11.7.41.8.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">pg_stat_statements_reset</code> discards statistics
+ gathered so far by <code class="filename">pg_stat_statements</code> corresponding
+ to the specified <code class="structfield">userid</code>, <code class="structfield">dbid</code>
+ and <code class="structfield">queryid</code>. If any of the parameters are not
+ specified, the default value <code class="literal">0</code>(invalid) is used for
+ each of them and the statistics that match with other parameters will be
+ reset. If no parameter is specified or all the specified parameters are
+ <code class="literal">0</code>(invalid), it will discard all statistics.
+ If all statistics in the <code class="filename">pg_stat_statements</code>
+ view are discarded, it will also reset the statistics in the
+ <code class="structname">pg_stat_statements_info</code> view.
+ By default, this function can only be executed by superusers.
+ Access may be granted to others using <code class="command">GRANT</code>.
+ </p></dd><dt><span class="term">
+ <code class="function">pg_stat_statements(showtext boolean) returns setof record</code>
+ <a id="id-1.11.7.41.8.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The <code class="structname">pg_stat_statements</code> view is defined in
+ terms of a function also named <code class="function">pg_stat_statements</code>.
+ It is possible for clients to call
+ the <code class="function">pg_stat_statements</code> function directly, and by
+ specifying <code class="literal">showtext := false</code> have query text be
+ omitted (that is, the <code class="literal">OUT</code> argument that corresponds
+ to the view's <code class="structfield">query</code> column will return nulls). This
+ feature is intended to support external tools that might wish to avoid
+ the overhead of repeatedly retrieving query texts of indeterminate
+ length. Such tools can instead cache the first query text observed
+ for each entry themselves, since that is
+ all <code class="filename">pg_stat_statements</code> itself does, and then retrieve
+ query texts only as needed. Since the server stores query texts in a
+ file, this approach may reduce physical I/O for repeated examination
+ of the <code class="structname">pg_stat_statements</code> data.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.41.9"><div class="titlepage"><div><div><h3 class="title">F.32.4. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="varname">pg_stat_statements.max</code> (<code class="type">integer</code>)
+ <a id="id-1.11.7.41.9.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">pg_stat_statements.max</code> is the maximum number of
+ statements tracked by the module (i.e., the maximum number of rows
+ in the <code class="structname">pg_stat_statements</code> view). If more distinct
+ statements than that are observed, information about the least-executed
+ statements is discarded. The number of times such information was
+ discarded can be seen in the
+ <code class="structname">pg_stat_statements_info</code> view.
+ The default value is 5000.
+ This parameter can only be set at server start.
+ </p></dd><dt><span class="term">
+ <code class="varname">pg_stat_statements.track</code> (<code class="type">enum</code>)
+ <a id="id-1.11.7.41.9.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">pg_stat_statements.track</code> controls which statements
+ are counted by the module.
+ Specify <code class="literal">top</code> to track top-level statements (those issued
+ directly by clients), <code class="literal">all</code> to also track nested statements
+ (such as statements invoked within functions), or <code class="literal">none</code> to
+ disable statement statistics collection.
+ The default value is <code class="literal">top</code>.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">pg_stat_statements.track_utility</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.41.9.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">pg_stat_statements.track_utility</code> controls whether
+ utility commands are tracked by the module. Utility commands are
+ all those other than <code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and <code class="command">MERGE</code>.
+ The default value is <code class="literal">on</code>.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">pg_stat_statements.track_planning</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.41.9.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">pg_stat_statements.track_planning</code> controls whether
+ planning operations and duration are tracked by the module.
+ Enabling this parameter may incur a noticeable performance penalty,
+ especially when statements with identical query structure are executed
+ by many concurrent connections which compete to update a small number of
+ <code class="structname">pg_stat_statements</code> entries.
+ The default value is <code class="literal">off</code>.
+ Only superusers can change this setting.
+ </p></dd><dt><span class="term">
+ <code class="varname">pg_stat_statements.save</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.41.9.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">pg_stat_statements.save</code> specifies whether to
+ save statement statistics across server shutdowns.
+ If it is <code class="literal">off</code> then statistics are not saved at
+ shutdown nor reloaded at server start.
+ The default value is <code class="literal">on</code>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div><p>
+ The module requires additional shared memory proportional to
+ <code class="varname">pg_stat_statements.max</code>. Note that this
+ memory is consumed whenever the module is loaded, even if
+ <code class="varname">pg_stat_statements.track</code> is set to <code class="literal">none</code>.
+ </p><p>
+ These parameters must be set in <code class="filename">postgresql.conf</code>.
+ Typical usage might be:
+
+</p><pre class="programlisting">
+# postgresql.conf
+shared_preload_libraries = 'pg_stat_statements'
+
+compute_query_id = on
+pg_stat_statements.max = 10000
+pg_stat_statements.track = all
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.41.10"><div class="titlepage"><div><div><h3 class="title">F.32.5. Sample Output</h3></div></div></div><pre class="screen">
+bench=# SELECT pg_stat_statements_reset();
+
+$ pgbench -i bench
+$ pgbench -c10 -t300 bench
+
+bench=# \x
+bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
+ nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
+ FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
+-[ RECORD 1 ]---+--------------------------------------------------​------------------
+query | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2
+calls | 3000
+total_exec_time | 25565.855387
+rows | 3000
+hit_percent | 100.0000000000000000
+-[ RECORD 2 ]---+--------------------------------------------------​------------------
+query | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
+calls | 3000
+total_exec_time | 20756.669379
+rows | 3000
+hit_percent | 100.0000000000000000
+-[ RECORD 3 ]---+--------------------------------------------------​------------------
+query | copy pgbench_accounts from stdin
+calls | 1
+total_exec_time | 291.865911
+rows | 100000
+hit_percent | 100.0000000000000000
+-[ RECORD 4 ]---+--------------------------------------------------​------------------
+query | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
+calls | 3000
+total_exec_time | 271.232977
+rows | 3000
+hit_percent | 98.8454011741682975
+-[ RECORD 5 ]---+--------------------------------------------------​------------------
+query | alter table pgbench_accounts add primary key (aid)
+calls | 1
+total_exec_time | 160.588563
+rows | 0
+hit_percent | 100.0000000000000000
+
+
+bench=# SELECT pg_stat_statements_reset(0,0,s.queryid) FROM pg_stat_statements AS s
+ WHERE s.query = 'UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2';
+
+bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
+ nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
+ FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
+-[ RECORD 1 ]---+--------------------------------------------------​------------------
+query | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
+calls | 3000
+total_exec_time | 20756.669379
+rows | 3000
+hit_percent | 100.0000000000000000
+-[ RECORD 2 ]---+--------------------------------------------------​------------------
+query | copy pgbench_accounts from stdin
+calls | 1
+total_exec_time | 291.865911
+rows | 100000
+hit_percent | 100.0000000000000000
+-[ RECORD 3 ]---+--------------------------------------------------​------------------
+query | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
+calls | 3000
+total_exec_time | 271.232977
+rows | 3000
+hit_percent | 98.8454011741682975
+-[ RECORD 4 ]---+--------------------------------------------------​------------------
+query | alter table pgbench_accounts add primary key (aid)
+calls | 1
+total_exec_time | 160.588563
+rows | 0
+hit_percent | 100.0000000000000000
+-[ RECORD 5 ]---+--------------------------------------------------​------------------
+query | vacuum analyze pgbench_accounts
+calls | 1
+total_exec_time | 136.448116
+rows | 0
+hit_percent | 99.9201915403032721
+
+bench=# SELECT pg_stat_statements_reset(0,0,0);
+
+bench=# SELECT query, calls, total_exec_time, rows, 100.0 * shared_blks_hit /
+ nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent
+ FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;
+-[ RECORD 1 ]---+--------------------------------------------------​---------------------------
+query | SELECT pg_stat_statements_reset(0,0,0)
+calls | 1
+total_exec_time | 0.189497
+rows | 1
+hit_percent |
+-[ RECORD 2 ]---+--------------------------------------------------​---------------------------
+query | SELECT query, calls, total_exec_time, rows, $1 * shared_blks_hit / +
+ | nullif(shared_blks_hit + shared_blks_read, $2) AS hit_percent+
+ | FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT $3
+calls | 0
+total_exec_time | 0
+rows | 0
+hit_percent |
+
+</pre></div><div class="sect2" id="id-1.11.7.41.11"><div class="titlepage"><div><div><h3 class="title">F.32.6. Authors</h3></div></div></div><p>
+ Takahiro Itagaki <code class="email">&lt;<a class="email" href="mailto:itagaki.takahiro@oss.ntt.co.jp">itagaki.takahiro@oss.ntt.co.jp</a>&gt;</code>.
+ Query normalization added by Peter Geoghegan <code class="email">&lt;<a class="email" href="mailto:peter@2ndquadrant.com">peter@2ndquadrant.com</a>&gt;</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgrowlocks.html" title="F.31. pgrowlocks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgstattuple.html" title="F.33. pgstattuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.31. pgrowlocks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.33. pgstattuple</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgstattuple.html b/doc/src/sgml/html/pgstattuple.html
new file mode 100644
index 0000000..decbc32
--- /dev/null
+++ b/doc/src/sgml/html/pgstattuple.html
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.33. pgstattuple</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgstatstatements.html" title="F.32. pg_stat_statements" /><link rel="next" href="pgsurgery.html" title="F.34. pg_surgery" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.33. pgstattuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgstatstatements.html" title="F.32. pg_stat_statements">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgsurgery.html" title="F.34. pg_surgery">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGSTATTUPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.33. pgstattuple</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgstattuple.html#id-1.11.7.42.5">F.33.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgstattuple.html#id-1.11.7.42.6">F.33.2. Authors</a></span></dt></dl></div><a id="id-1.11.7.42.2" class="indexterm"></a><p>
+ The <code class="filename">pgstattuple</code> module provides various functions to
+ obtain tuple-level statistics.
+ </p><p>
+ Because these functions return detailed page-level information, access is
+ restricted by default. By default, only the
+ role <code class="literal">pg_stat_scan_tables</code> has <code class="literal">EXECUTE</code>
+ privilege. Superusers of course bypass this restriction. After the
+ extension has been installed, users may issue <code class="command">GRANT</code>
+ commands to change the privileges on the functions to allow others to
+ execute them. However, it might be preferable to add those users to
+ the <code class="literal">pg_stat_scan_tables</code> role instead.
+ </p><div class="sect2" id="id-1.11.7.42.5"><div class="titlepage"><div><div><h3 class="title">F.33.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.1.1.1" class="indexterm"></a>
+ <code class="function">pgstattuple(regclass) returns record</code>
+ </span></dt><dd><p>
+ <code class="function">pgstattuple</code> returns a relation's physical length,
+ percentage of <span class="quote">“<span class="quote">dead</span>”</span> tuples, and other info. This may help users
+ to determine whether vacuum is necessary or not. The argument is the
+ target relation's name (optionally schema-qualified) or OID.
+ For example:
+</p><pre class="programlisting">
+test=&gt; SELECT * FROM pgstattuple('pg_catalog.pg_proc');
+-[ RECORD 1 ]------+-------
+table_len | 458752
+tuple_count | 1470
+tuple_len | 438896
+tuple_percent | 95.67
+dead_tuple_count | 11
+dead_tuple_len | 3157
+dead_tuple_percent | 0.69
+free_space | 8932
+free_percent | 1.95
+</pre><p>
+ The output columns are described in <a class="xref" href="pgstattuple.html#PGSTATTUPLE-COLUMNS" title="Table F.22. pgstattuple Output Columns">Table F.22</a>.
+ </p><div class="table" id="PGSTATTUPLE-COLUMNS"><p class="title"><strong>Table F.22. <code class="function">pgstattuple</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pgstattuple Output Columns" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">table_len</code></td><td><code class="type">bigint</code></td><td>Physical relation length in bytes</td></tr><tr><td><code class="structfield">tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of live tuples</td></tr><tr><td><code class="structfield">tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of live tuples in bytes</td></tr><tr><td><code class="structfield">tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of live tuples</td></tr><tr><td><code class="structfield">dead_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples</td></tr><tr><td><code class="structfield">dead_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of dead tuples in bytes</td></tr><tr><td><code class="structfield">dead_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of dead tuples</td></tr><tr><td><code class="structfield">free_space</code></td><td><code class="type">bigint</code></td><td>Total free space in bytes</td></tr><tr><td><code class="structfield">free_percent</code></td><td><code class="type">float8</code></td><td>Percentage of free space</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="literal">table_len</code> will always be greater than the sum
+ of the <code class="literal">tuple_len</code>, <code class="literal">dead_tuple_len</code>
+ and <code class="literal">free_space</code>. The difference is accounted for by
+ fixed page overhead, the per-page table of pointers to tuples, and
+ padding to ensure that tuples are correctly aligned.
+ </p></div><p>
+ <code class="function">pgstattuple</code> acquires only a read lock on the
+ relation. So the results do not reflect an instantaneous snapshot;
+ concurrent updates will affect them.
+ </p><p>
+ <code class="function">pgstattuple</code> judges a tuple is <span class="quote">“<span class="quote">dead</span>”</span> if
+ <code class="function">HeapTupleSatisfiesDirty</code> returns false.
+ </p></dd><dt><span class="term">
+ <code class="function">pgstattuple(text) returns record</code>
+ </span></dt><dd><p>
+ This is the same as <code class="function">pgstattuple(regclass)</code>, except
+ that the target relation is specified as TEXT. This function is kept
+ because of backward-compatibility so far, and will be deprecated in
+ some future release.
+ </p></dd><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.3.1.1" class="indexterm"></a>
+ <code class="function">pgstatindex(regclass) returns record</code>
+ </span></dt><dd><p>
+ <code class="function">pgstatindex</code> returns a record showing information
+ about a B-tree index. For example:
+</p><pre class="programlisting">
+test=&gt; SELECT * FROM pgstatindex('pg_cast_oid_index');
+-[ RECORD 1 ]------+------
+version | 2
+tree_level | 0
+index_size | 16384
+root_block_no | 1
+internal_pages | 0
+leaf_pages | 1
+empty_pages | 0
+deleted_pages | 0
+avg_leaf_density | 54.27
+leaf_fragmentation | 0
+</pre><p>
+ </p><p>
+ The output columns are:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>B-tree version number</td></tr><tr><td><code class="structfield">tree_level</code></td><td><code class="type">integer</code></td><td>Tree level of the root page</td></tr><tr><td><code class="structfield">index_size</code></td><td><code class="type">bigint</code></td><td>Total index size in bytes</td></tr><tr><td><code class="structfield">root_block_no</code></td><td><code class="type">bigint</code></td><td>Location of root page (zero if none)</td></tr><tr><td><code class="structfield">internal_pages</code></td><td><code class="type">bigint</code></td><td>Number of <span class="quote">“<span class="quote">internal</span>”</span> (upper-level) pages</td></tr><tr><td><code class="structfield">leaf_pages</code></td><td><code class="type">bigint</code></td><td>Number of leaf pages</td></tr><tr><td><code class="structfield">empty_pages</code></td><td><code class="type">bigint</code></td><td>Number of empty pages</td></tr><tr><td><code class="structfield">deleted_pages</code></td><td><code class="type">bigint</code></td><td>Number of deleted pages</td></tr><tr><td><code class="structfield">avg_leaf_density</code></td><td><code class="type">float8</code></td><td>Average density of leaf pages</td></tr><tr><td><code class="structfield">leaf_fragmentation</code></td><td><code class="type">float8</code></td><td>Leaf page fragmentation</td></tr></tbody></table></div><p>
+ </p><p>
+ The reported <code class="literal">index_size</code> will normally correspond to one more
+ page than is accounted for by <code class="literal">internal_pages + leaf_pages +
+ empty_pages + deleted_pages</code>, because it also includes the
+ index's metapage.
+ </p><p>
+ As with <code class="function">pgstattuple</code>, the results are accumulated
+ page-by-page, and should not be expected to represent an
+ instantaneous snapshot of the whole index.
+ </p></dd><dt><span class="term">
+ <code class="function">pgstatindex(text) returns record</code>
+ </span></dt><dd><p>
+ This is the same as <code class="function">pgstatindex(regclass)</code>, except
+ that the target index is specified as TEXT. This function is kept
+ because of backward-compatibility so far, and will be deprecated in
+ some future release.
+ </p></dd><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.5.1.1" class="indexterm"></a>
+ <code class="function">pgstatginindex(regclass) returns record</code>
+ </span></dt><dd><p>
+ <code class="function">pgstatginindex</code> returns a record showing information
+ about a GIN index. For example:
+</p><pre class="programlisting">
+test=&gt; SELECT * FROM pgstatginindex('test_gin_index');
+-[ RECORD 1 ]--+--
+version | 1
+pending_pages | 0
+pending_tuples | 0
+</pre><p>
+ </p><p>
+ The output columns are:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>GIN version number</td></tr><tr><td><code class="structfield">pending_pages</code></td><td><code class="type">integer</code></td><td>Number of pages in the pending list</td></tr><tr><td><code class="structfield">pending_tuples</code></td><td><code class="type">bigint</code></td><td>Number of tuples in the pending list</td></tr></tbody></table></div><p>
+ </p></dd><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.6.1.1" class="indexterm"></a>
+ <code class="function">pgstathashindex(regclass) returns record</code>
+ </span></dt><dd><p>
+ <code class="function">pgstathashindex</code> returns a record showing information
+ about a HASH index. For example:
+</p><pre class="programlisting">
+test=&gt; select * from pgstathashindex('con_hash_index');
+-[ RECORD 1 ]--+-----------------
+version | 4
+bucket_pages | 33081
+overflow_pages | 0
+bitmap_pages | 1
+unused_pages | 32455
+live_items | 10204006
+dead_items | 0
+free_percent | 61.8005949100872
+</pre><p>
+ </p><p>
+ The output columns are:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">version</code></td><td><code class="type">integer</code></td><td>HASH version number</td></tr><tr><td><code class="structfield">bucket_pages</code></td><td><code class="type">bigint</code></td><td>Number of bucket pages</td></tr><tr><td><code class="structfield">overflow_pages</code></td><td><code class="type">bigint</code></td><td>Number of overflow pages</td></tr><tr><td><code class="structfield">bitmap_pages</code></td><td><code class="type">bigint</code></td><td>Number of bitmap pages</td></tr><tr><td><code class="structfield">unused_pages</code></td><td><code class="type">bigint</code></td><td>Number of unused pages</td></tr><tr><td><code class="structfield">live_items</code></td><td><code class="type">bigint</code></td><td>Number of live tuples</td></tr><tr><td><code class="structfield">dead_tuples</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples</td></tr><tr><td><code class="structfield">free_percent</code></td><td><code class="type">float</code></td><td>Percentage of free space</td></tr></tbody></table></div><p>
+ </p></dd><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.7.1.1" class="indexterm"></a>
+ <code class="function">pg_relpages(regclass) returns bigint</code>
+ </span></dt><dd><p>
+ <code class="function">pg_relpages</code> returns the number of pages in the
+ relation.
+ </p></dd><dt><span class="term">
+ <code class="function">pg_relpages(text) returns bigint</code>
+ </span></dt><dd><p>
+ This is the same as <code class="function">pg_relpages(regclass)</code>, except
+ that the target relation is specified as TEXT. This function is kept
+ because of backward-compatibility so far, and will be deprecated in
+ some future release.
+ </p></dd><dt><span class="term">
+ <a id="id-1.11.7.42.5.2.9.1.1" class="indexterm"></a>
+ <code class="function">pgstattuple_approx(regclass) returns record</code>
+ </span></dt><dd><p>
+ <code class="function">pgstattuple_approx</code> is a faster alternative to
+ <code class="function">pgstattuple</code> that returns approximate results.
+ The argument is the target relation's name or OID.
+ For example:
+</p><pre class="programlisting">
+test=&gt; SELECT * FROM pgstattuple_approx('pg_catalog.pg_proc'::regclass);
+-[ RECORD 1 ]--------+-------
+table_len | 573440
+scanned_percent | 2
+approx_tuple_count | 2740
+approx_tuple_len | 561210
+approx_tuple_percent | 97.87
+dead_tuple_count | 0
+dead_tuple_len | 0
+dead_tuple_percent | 0
+approx_free_space | 11996
+approx_free_percent | 2.09
+</pre><p>
+ The output columns are described in <a class="xref" href="pgstattuple.html#PGSTATAPPROX-COLUMNS" title="Table F.23. pgstattuple_approx Output Columns">Table F.23</a>.
+ </p><p>
+ Whereas <code class="function">pgstattuple</code> always performs a
+ full-table scan and returns an exact count of live and dead tuples
+ (and their sizes) and free space, <code class="function">pgstattuple_approx</code>
+ tries to avoid the full-table scan and returns exact dead tuple
+ statistics along with an approximation of the number and
+ size of live tuples and free space.
+ </p><p>
+ It does this by skipping pages that have only visible tuples
+ according to the visibility map (if a page has the corresponding VM
+ bit set, then it is assumed to contain no dead tuples). For such
+ pages, it derives the free space value from the free space map, and
+ assumes that the rest of the space on the page is taken up by live
+ tuples.
+ </p><p>
+ For pages that cannot be skipped, it scans each tuple, recording its
+ presence and size in the appropriate counters, and adding up the
+ free space on the page. At the end, it estimates the total number of
+ live tuples based on the number of pages and tuples scanned (in the
+ same way that VACUUM estimates pg_class.reltuples).
+ </p><div class="table" id="PGSTATAPPROX-COLUMNS"><p class="title"><strong>Table F.23. <code class="function">pgstattuple_approx</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pgstattuple_approx Output Columns" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Column</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="structfield">table_len</code></td><td><code class="type">bigint</code></td><td>Physical relation length in bytes (exact)</td></tr><tr><td><code class="structfield">scanned_percent</code></td><td><code class="type">float8</code></td><td>Percentage of table scanned</td></tr><tr><td><code class="structfield">approx_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of live tuples (estimated)</td></tr><tr><td><code class="structfield">approx_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of live tuples in bytes (estimated)</td></tr><tr><td><code class="structfield">approx_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of live tuples</td></tr><tr><td><code class="structfield">dead_tuple_count</code></td><td><code class="type">bigint</code></td><td>Number of dead tuples (exact)</td></tr><tr><td><code class="structfield">dead_tuple_len</code></td><td><code class="type">bigint</code></td><td>Total length of dead tuples in bytes (exact)</td></tr><tr><td><code class="structfield">dead_tuple_percent</code></td><td><code class="type">float8</code></td><td>Percentage of dead tuples</td></tr><tr><td><code class="structfield">approx_free_space</code></td><td><code class="type">bigint</code></td><td>Total free space in bytes (estimated)</td></tr><tr><td><code class="structfield">approx_free_percent</code></td><td><code class="type">float8</code></td><td>Percentage of free space</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In the above output, the free space figures may not match the
+ <code class="function">pgstattuple</code> output exactly, because the free
+ space map gives us an exact figure, but is not guaranteed to be
+ accurate to the byte.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.42.6"><div class="titlepage"><div><div><h3 class="title">F.33.2. Authors</h3></div></div></div><p>
+ Tatsuo Ishii, Satoshi Nagayasu and Abhijit Menon-Sen
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgstatstatements.html" title="F.32. pg_stat_statements">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgsurgery.html" title="F.34. pg_surgery">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.32. pg_stat_statements </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.34. pg_surgery</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgsurgery.html b/doc/src/sgml/html/pgsurgery.html
new file mode 100644
index 0000000..80f0497
--- /dev/null
+++ b/doc/src/sgml/html/pgsurgery.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.34. pg_surgery</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgstattuple.html" title="F.33. pgstattuple" /><link rel="next" href="pgtrgm.html" title="F.35. pg_trgm" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.34. pg_surgery</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgstattuple.html" title="F.33. pgstattuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgtrgm.html" title="F.35. pg_trgm">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGSURGERY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.34. pg_surgery</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgsurgery.html#id-1.11.7.43.4">F.34.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgsurgery.html#id-1.11.7.43.5">F.34.2. Authors</a></span></dt></dl></div><a id="id-1.11.7.43.2" class="indexterm"></a><p>
+ The <code class="filename">pg_surgery</code> module provides various functions to
+ perform surgery on a damaged relation. These functions are unsafe by design
+ and using them may corrupt (or further corrupt) your database. For example,
+ these functions can easily be used to make a table inconsistent with its
+ own indexes, to cause <code class="literal">UNIQUE</code> or
+ <code class="literal">FOREIGN KEY</code> constraint violations, or even to make
+ tuples visible which, when read, will cause a database server crash.
+ They should be used with great caution and only as a last resort.
+ </p><div class="sect2" id="id-1.11.7.43.4"><div class="titlepage"><div><div><h3 class="title">F.34.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">heap_force_kill(regclass, tid[]) returns void</code>
+ </span></dt><dd><p>
+ <code class="function">heap_force_kill</code> marks <span class="quote">“<span class="quote">used</span>”</span> line
+ pointers as <span class="quote">“<span class="quote">dead</span>”</span> without examining the tuples. The
+ intended use of this function is to forcibly remove tuples that are not
+ otherwise accessible. For example:
+</p><pre class="programlisting">
+test=&gt; select * from t1 where ctid = '(0, 1)';
+ERROR: could not access status of transaction 4007513275
+DETAIL: Could not open file "pg_xact/0EED": No such file or directory.
+
+test=# select heap_force_kill('t1'::regclass, ARRAY['(0, 1)']::tid[]);
+ heap_force_kill
+-----------------
+
+(1 row)
+
+test=# select * from t1 where ctid = '(0, 1)';
+(0 rows)
+
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">heap_force_freeze(regclass, tid[]) returns void</code>
+ </span></dt><dd><p>
+ <code class="function">heap_force_freeze</code> marks tuples as frozen without
+ examining the tuple data. The intended use of this function is to
+ make accessible tuples which are inaccessible due to corrupted
+ visibility information, or which prevent the table from being
+ successfully vacuumed due to corrupted visibility information.
+ For example:
+</p><pre class="programlisting">
+test=&gt; vacuum t1;
+ERROR: found xmin 507 from before relfrozenxid 515
+CONTEXT: while scanning block 0 of relation "public.t1"
+
+test=# select ctid from t1 where xmin = 507;
+ ctid
+-------
+ (0,3)
+(1 row)
+
+test=# select heap_force_freeze('t1'::regclass, ARRAY['(0, 3)']::tid[]);
+ heap_force_freeze
+-------------------
+
+(1 row)
+
+test=# select ctid from t1 where xmin = 2;
+ ctid
+-------
+ (0,3)
+(1 row)
+
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.43.5"><div class="titlepage"><div><div><h3 class="title">F.34.2. Authors</h3></div></div></div><p>
+ Ashutosh Sharma <code class="email">&lt;<a class="email" href="mailto:ashu.coek88@gmail.com">ashu.coek88@gmail.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgstattuple.html" title="F.33. pgstattuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgtrgm.html" title="F.35. pg_trgm">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.33. pgstattuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.35. pg_trgm</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgtestfsync.html b/doc/src/sgml/html/pgtestfsync.html
new file mode 100644
index 0000000..28dca2d
--- /dev/null
+++ b/doc/src/sgml/html/pgtestfsync.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_test_fsync</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgrewind.html" title="pg_rewind" /><link rel="next" href="pgtesttiming.html" title="pg_test_timing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_test_fsync</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgrewind.html" title="pg_rewind">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgtesttiming.html" title="pg_test_timing">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGTESTFSYNC"><div class="titlepage"></div><a id="id-1.9.5.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_test_fsync</span></span></h2><p>pg_test_fsync — determine fastest <code class="varname">wal_sync_method</code> for <span class="productname">PostgreSQL</span></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.10.4.1"><code class="command">pg_test_fsync</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.5.10.5"><h2>Description</h2><p>
+ <span class="application">pg_test_fsync</span> is intended to give you a reasonable
+ idea of what the fastest <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a> is on your
+ specific system,
+ as well as supplying diagnostic information in the event of an identified I/O
+ problem. However, differences shown by
+ <span class="application">pg_test_fsync</span> might not make any significant
+ difference in real database throughput, especially since many database servers
+ are not speed-limited by their write-ahead logs.
+ <span class="application">pg_test_fsync</span> reports average file sync operation
+ time in microseconds for each <code class="literal">wal_sync_method</code>, which can also be used to
+ inform efforts to optimize the value of <a class="xref" href="runtime-config-wal.html#GUC-COMMIT-DELAY">commit_delay</a>.
+ </p></div><div class="refsect1" id="id-1.9.5.10.6"><h2>Options</h2><p>
+ <span class="application">pg_test_fsync</span> accepts the following
+ command-line options:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--filename</code></span></dt><dd><p>
+ Specifies the file name to write test data in.
+ This file should be in the same file system that the
+ <code class="filename">pg_wal</code> directory is or will be placed in.
+ (<code class="filename">pg_wal</code> contains the <acronym class="acronym">WAL</acronym> files.)
+ The default is <code class="filename">pg_test_fsync.out</code> in the current
+ directory.
+ </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--secs-per-test</code></span></dt><dd><p>
+ Specifies the number of seconds for each test. The more time
+ per test, the greater the test's accuracy, but the longer it takes
+ to run. The default is 5 seconds, which allows the program to
+ complete in under 2 minutes.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_test_fsync</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_test_fsync</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.10.7"><h2>Environment</h2><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.10.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgrewind.html" title="pg_rewind">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgtesttiming.html" title="pg_test_timing">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_rewind</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_test_timing</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgtesttiming.html b/doc/src/sgml/html/pgtesttiming.html
new file mode 100644
index 0000000..46e2442
--- /dev/null
+++ b/doc/src/sgml/html/pgtesttiming.html
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_test_timing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgtestfsync.html" title="pg_test_fsync" /><link rel="next" href="pgupgrade.html" title="pg_upgrade" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_test_timing</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgtestfsync.html" title="pg_test_fsync">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgupgrade.html" title="pg_upgrade">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGTESTTIMING"><div class="titlepage"></div><a id="id-1.9.5.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_test_timing</span></span></h2><p>pg_test_timing — measure timing overhead</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.11.4.1"><code class="command">pg_test_timing</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.5.11.5"><h2>Description</h2><p>
+ <span class="application">pg_test_timing</span> is a tool to measure the timing overhead
+ on your system and confirm that the system time never moves backwards.
+ Systems that are slow to collect timing data can give less accurate
+ <code class="command">EXPLAIN ANALYZE</code> results.
+ </p></div><div class="refsect1" id="id-1.9.5.11.6"><h2>Options</h2><p>
+ <span class="application">pg_test_timing</span> accepts the following
+ command-line options:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>duration</code></em></code><br /></span><span class="term"><code class="option">--duration=<em class="replaceable"><code>duration</code></em></code></span></dt><dd><p>
+ Specifies the test duration, in seconds. Longer durations
+ give slightly better accuracy, and are more likely to discover
+ problems with the system clock moving backwards. The default
+ test duration is 3 seconds.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_test_timing</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_test_timing</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.11.7"><h2>Usage</h2><div class="refsect2" id="id-1.9.5.11.7.2"><h3>Interpreting Results</h3><p>
+ Good results will show most (&gt;90%) individual timing calls take less than
+ one microsecond. Average per loop overhead will be even lower, below 100
+ nanoseconds. This example from an Intel i7-860 system using a TSC clock
+ source shows excellent performance:
+
+</p><pre class="screen">
+Testing timing overhead for 3 seconds.
+Per loop time including overhead: 35.96 ns
+Histogram of timing durations:
+ &lt; us % of total count
+ 1 96.40465 80435604
+ 2 3.59518 2999652
+ 4 0.00015 126
+ 8 0.00002 13
+ 16 0.00000 2
+</pre><p>
+ </p><p>
+ Note that different units are used for the per loop time than the
+ histogram. The loop can have resolution within a few nanoseconds (ns),
+ while the individual timing calls can only resolve down to one microsecond
+ (us).
+ </p></div><div class="refsect2" id="id-1.9.5.11.7.3"><h3>Measuring Executor Timing Overhead</h3><p>
+ When the query executor is running a statement using
+ <code class="command">EXPLAIN ANALYZE</code>, individual operations are timed as well
+ as showing a summary. The overhead of your system can be checked by
+ counting rows with the <span class="application">psql</span> program:
+
+</p><pre class="screen">
+CREATE TABLE t AS SELECT * FROM generate_series(1,100000);
+\timing
+SELECT COUNT(*) FROM t;
+EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
+</pre><p>
+ </p><p>
+ The i7-860 system measured runs the count query in 9.8 ms while
+ the <code class="command">EXPLAIN ANALYZE</code> version takes 16.6 ms, each
+ processing just over 100,000 rows. That 6.8 ms difference means the timing
+ overhead per row is 68 ns, about twice what pg_test_timing estimated it
+ would be. Even that relatively small amount of overhead is making the fully
+ timed count statement take almost 70% longer. On more substantial queries,
+ the timing overhead would be less problematic.
+ </p></div><div class="refsect2" id="id-1.9.5.11.7.4"><h3>Changing Time Sources</h3><p>
+ On some newer Linux systems, it's possible to change the clock source used
+ to collect timing data at any time. A second example shows the slowdown
+ possible from switching to the slower acpi_pm time source, on the same
+ system used for the fast results above:
+
+</p><pre class="screen">
+# cat /sys/devices/system/clocksource/clocksource0/available_clocksource
+tsc hpet acpi_pm
+# echo acpi_pm &gt; /sys/devices/system/clocksource/clocksource0/current_clocksource
+# pg_test_timing
+Per loop time including overhead: 722.92 ns
+Histogram of timing durations:
+ &lt; us % of total count
+ 1 27.84870 1155682
+ 2 72.05956 2990371
+ 4 0.07810 3241
+ 8 0.01357 563
+ 16 0.00007 3
+</pre><p>
+ </p><p>
+ In this configuration, the sample <code class="command">EXPLAIN ANALYZE</code> above
+ takes 115.9 ms. That's 1061 ns of timing overhead, again a small multiple
+ of what's measured directly by this utility. That much timing overhead
+ means the actual query itself is only taking a tiny fraction of the
+ accounted for time, most of it is being consumed in overhead instead. In
+ this configuration, any <code class="command">EXPLAIN ANALYZE</code> totals involving
+ many timed operations would be inflated significantly by timing overhead.
+ </p><p>
+ FreeBSD also allows changing the time source on the fly, and it logs
+ information about the timer selected during boot:
+
+</p><pre class="screen">
+# dmesg | grep "Timecounter"
+Timecounter "ACPI-fast" frequency 3579545 Hz quality 900
+Timecounter "i8254" frequency 1193182 Hz quality 0
+Timecounters tick every 10.000 msec
+Timecounter "TSC" frequency 2531787134 Hz quality 800
+# sysctl kern.timecounter.hardware=TSC
+kern.timecounter.hardware: ACPI-fast -&gt; TSC
+</pre><p>
+ </p><p>
+ Other systems may only allow setting the time source on boot. On older
+ Linux systems the "clock" kernel setting is the only way to make this sort
+ of change. And even on some more recent ones, the only option you'll see
+ for a clock source is "jiffies". Jiffies are the older Linux software clock
+ implementation, which can have good resolution when it's backed by fast
+ enough timing hardware, as in this example:
+
+</p><pre class="screen">
+$ cat /sys/devices/system/clocksource/clocksource0/available_clocksource
+jiffies
+$ dmesg | grep time.c
+time.c: Using 3.579545 MHz WALL PM GTOD PIT/TSC timer.
+time.c: Detected 2400.153 MHz processor.
+$ pg_test_timing
+Testing timing overhead for 3 seconds.
+Per timing duration including loop overhead: 97.75 ns
+Histogram of timing durations:
+ &lt; us % of total count
+ 1 90.23734 27694571
+ 2 9.75277 2993204
+ 4 0.00981 3010
+ 8 0.00007 22
+ 16 0.00000 1
+ 32 0.00000 1
+</pre></div><div class="refsect2" id="id-1.9.5.11.7.5"><h3>Clock Hardware and Timing Accuracy</h3><p>
+ Collecting accurate timing information is normally done on computers using
+ hardware clocks with various levels of accuracy. With some hardware the
+ operating systems can pass the system clock time almost directly to
+ programs. A system clock can also be derived from a chip that simply
+ provides timing interrupts, periodic ticks at some known time interval. In
+ either case, operating system kernels provide a clock source that hides
+ these details. But the accuracy of that clock source and how quickly it can
+ return results varies based on the underlying hardware.
+ </p><p>
+ Inaccurate time keeping can result in system instability. Test any change
+ to the clock source very carefully. Operating system defaults are sometimes
+ made to favor reliability over best accuracy. And if you are using a virtual
+ machine, look into the recommended time sources compatible with it. Virtual
+ hardware faces additional difficulties when emulating timers, and there are
+ often per operating system settings suggested by vendors.
+ </p><p>
+ The Time Stamp Counter (TSC) clock source is the most accurate one available
+ on current generation CPUs. It's the preferred way to track the system time
+ when it's supported by the operating system and the TSC clock is
+ reliable. There are several ways that TSC can fail to provide an accurate
+ timing source, making it unreliable. Older systems can have a TSC clock that
+ varies based on the CPU temperature, making it unusable for timing. Trying
+ to use TSC on some older multicore CPUs can give a reported time that's
+ inconsistent among multiple cores. This can result in the time going
+ backwards, a problem this program checks for. And even the newest systems
+ can fail to provide accurate TSC timing with very aggressive power saving
+ configurations.
+ </p><p>
+ Newer operating systems may check for the known TSC problems and switch to a
+ slower, more stable clock source when they are seen. If your system
+ supports TSC time but doesn't default to that, it may be disabled for a good
+ reason. And some operating systems may not detect all the possible problems
+ correctly, or will allow using TSC even in situations where it's known to be
+ inaccurate.
+ </p><p>
+ The High Precision Event Timer (HPET) is the preferred timer on systems
+ where it's available and TSC is not accurate. The timer chip itself is
+ programmable to allow up to 100 nanosecond resolution, but you may not see
+ that much accuracy in your system clock.
+ </p><p>
+ Advanced Configuration and Power Interface (ACPI) provides a Power
+ Management (PM) Timer, which Linux refers to as the acpi_pm. The clock
+ derived from acpi_pm will at best provide 300 nanosecond resolution.
+ </p><p>
+ Timers used on older PC hardware include the 8254 Programmable Interval
+ Timer (PIT), the real-time clock (RTC), the Advanced Programmable Interrupt
+ Controller (APIC) timer, and the Cyclone timer. These timers aim for
+ millisecond resolution.
+ </p></div></div><div class="refsect1" id="id-1.9.5.11.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgtestfsync.html" title="pg_test_fsync">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgupgrade.html" title="pg_upgrade">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_test_fsync</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_upgrade</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgtrgm.html b/doc/src/sgml/html/pgtrgm.html
new file mode 100644
index 0000000..dbdf95c
--- /dev/null
+++ b/doc/src/sgml/html/pgtrgm.html
@@ -0,0 +1,424 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.35. pg_trgm</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgsurgery.html" title="F.34. pg_surgery" /><link rel="next" href="pgvisibility.html" title="F.36. pg_visibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.35. pg_trgm</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgsurgery.html" title="F.34. pg_surgery">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgvisibility.html" title="F.36. pg_visibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGTRGM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.35. pg_trgm</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.5">F.35.1. Trigram (or Trigraph) Concepts</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.6">F.35.2. Functions and Operators</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.7">F.35.3. GUC Parameters</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.8">F.35.4. Index Support</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.9">F.35.5. Text Search Integration</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.10">F.35.6. References</a></span></dt><dt><span class="sect2"><a href="pgtrgm.html#id-1.11.7.44.11">F.35.7. Authors</a></span></dt></dl></div><a id="id-1.11.7.44.2" class="indexterm"></a><p>
+ The <code class="filename">pg_trgm</code> module provides functions and operators
+ for determining the similarity of
+ alphanumeric text based on trigram matching, as
+ well as index operator classes that support fast searching for similar
+ strings.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.44.5"><div class="titlepage"><div><div><h3 class="title">F.35.1. Trigram (or Trigraph) Concepts</h3></div></div></div><p>
+ A trigram is a group of three consecutive characters taken
+ from a string. We can measure the similarity of two strings by
+ counting the number of trigrams they share. This simple idea
+ turns out to be very effective for measuring the similarity of
+ words in many natural languages.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="filename">pg_trgm</code> ignores non-word characters
+ (non-alphanumerics) when extracting trigrams from a string.
+ Each word is considered to have two spaces
+ prefixed and one space suffixed when determining the set
+ of trigrams contained in the string.
+ For example, the set of trigrams in the string
+ <span class="quote">“<span class="quote"><code class="literal">cat</code></span>”</span> is
+ <span class="quote">“<span class="quote"><code class="literal"> c</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal"> ca</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">cat</code></span>”</span>, and
+ <span class="quote">“<span class="quote"><code class="literal">at </code></span>”</span>.
+ The set of trigrams in the string
+ <span class="quote">“<span class="quote"><code class="literal">foo|bar</code></span>”</span> is
+ <span class="quote">“<span class="quote"><code class="literal"> f</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal"> fo</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">foo</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">oo </code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal"> b</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal"> ba</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">bar</code></span>”</span>, and
+ <span class="quote">“<span class="quote"><code class="literal">ar </code></span>”</span>.
+ </p></div></div><div class="sect2" id="id-1.11.7.44.6"><div class="titlepage"><div><div><h3 class="title">F.35.2. Functions and Operators</h3></div></div></div><p>
+ The functions provided by the <code class="filename">pg_trgm</code> module
+ are shown in <a class="xref" href="pgtrgm.html#PGTRGM-FUNC-TABLE" title="Table F.24. pg_trgm Functions">Table F.24</a>, the operators
+ in <a class="xref" href="pgtrgm.html#PGTRGM-OP-TABLE" title="Table F.25. pg_trgm Operators">Table F.25</a>.
+ </p><div class="table" id="PGTRGM-FUNC-TABLE"><p class="title"><strong>Table F.24. <code class="filename">pg_trgm</code> Functions</strong></p><div class="table-contents"><table class="table" summary="pg_trgm Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">similarity</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns a number that indicates how similar the two arguments are.
+ The range of the result is zero (indicating that the two strings are
+ completely dissimilar) to one (indicating that the two strings are
+ identical).
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">show_trgm</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text[]</code>
+ </p>
+ <p>
+ Returns an array of all the trigrams in the given string.
+ (In practice this is seldom useful except for debugging.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">word_similarity</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns a number that indicates the greatest similarity between
+ the set of trigrams in the first string and any continuous extent
+ of an ordered set of trigrams in the second string. For details, see
+ the explanation below.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.4.1.1.1" class="indexterm"></a>
+ <code class="function">strict_word_similarity</code> ( <code class="type">text</code>, <code class="type">text</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Same as <code class="function">word_similarity</code>, but forces
+ extent boundaries to match word boundaries. Since we don't have
+ cross-word trigrams, this function actually returns greatest similarity
+ between first string and any continuous extent of words of the second
+ string.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.5.1.1.1" class="indexterm"></a>
+ <code class="function">show_limit</code> ()
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns the current similarity threshold used by the <code class="literal">%</code>
+ operator. This sets the minimum similarity between
+ two words for them to be considered similar enough to
+ be misspellings of each other, for example.
+ (<span class="emphasis"><em>Deprecated</em></span>; instead use <code class="command">SHOW</code>
+ <code class="varname">pg_trgm.similarity_threshold</code>.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.44.6.3.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">set_limit</code> ( <code class="type">real</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Sets the current similarity threshold that is used by the <code class="literal">%</code>
+ operator. The threshold must be between 0 and 1 (default is 0.3).
+ Returns the same value passed in.
+ (<span class="emphasis"><em>Deprecated</em></span>; instead use <code class="command">SET</code>
+ <code class="varname">pg_trgm.similarity_threshold</code>.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Consider the following example:
+
+</p><pre class="programlisting">
+# SELECT word_similarity('word', 'two words');
+ word_similarity
+-----------------
+ 0.8
+(1 row)
+</pre><p>
+
+ In the first string, the set of trigrams is
+ <code class="literal">{" w"," wo","wor","ord","rd "}</code>.
+ In the second string, the ordered set of trigrams is
+ <code class="literal">{" t"," tw","two","wo "," w"," wo","wor","ord","rds","ds "}</code>.
+ The most similar extent of an ordered set of trigrams in the second string
+ is <code class="literal">{" w"," wo","wor","ord"}</code>, and the similarity is
+ <code class="literal">0.8</code>.
+ </p><p>
+ This function returns a value that can be approximately understood as the
+ greatest similarity between the first string and any substring of the second
+ string. However, this function does not add padding to the boundaries of
+ the extent. Thus, the number of additional characters present in the
+ second string is not considered, except for the mismatched word boundaries.
+ </p><p>
+ At the same time, <code class="function">strict_word_similarity</code>
+ selects an extent of words in the second string. In the example above,
+ <code class="function">strict_word_similarity</code> would select the
+ extent of a single word <code class="literal">'words'</code>, whose set of trigrams is
+ <code class="literal">{" w"," wo","wor","ord","rds","ds "}</code>.
+
+</p><pre class="programlisting">
+# SELECT strict_word_similarity('word', 'two words'), similarity('word', 'words');
+ strict_word_similarity | similarity
+------------------------+------------
+ 0.571429 | 0.571429
+(1 row)
+</pre><p>
+ </p><p>
+ Thus, the <code class="function">strict_word_similarity</code> function
+ is useful for finding the similarity to whole words, while
+ <code class="function">word_similarity</code> is more suitable for
+ finding the similarity for parts of words.
+ </p><div class="table" id="PGTRGM-OP-TABLE"><p class="title"><strong>Table F.25. <code class="filename">pg_trgm</code> Operators</strong></p><div class="table-contents"><table class="table" summary="pg_trgm Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">%</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns <code class="literal">true</code> if its arguments have a similarity
+ that is greater than the current similarity threshold set by
+ <code class="varname">pg_trgm.similarity_threshold</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;%</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns <code class="literal">true</code> if the similarity between the trigram
+ set in the first argument and a continuous extent of an ordered trigram
+ set in the second argument is greater than the current word similarity
+ threshold set by <code class="varname">pg_trgm.word_similarity_threshold</code>
+ parameter.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">%&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Commutator of the <code class="literal">&lt;%</code> operator.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;&lt;%</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Returns <code class="literal">true</code> if its second argument has a continuous
+ extent of an ordered trigram set that matches word boundaries,
+ and its similarity to the trigram set of the first argument is greater
+ than the current strict word similarity threshold set by the
+ <code class="varname">pg_trgm.strict_word_similarity_threshold</code> parameter.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">%&gt;&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Commutator of the <code class="literal">&lt;&lt;%</code> operator.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns the <span class="quote">“<span class="quote">distance</span>”</span> between the arguments, that is
+ one minus the <code class="function">similarity()</code> value.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;&lt;-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns the <span class="quote">“<span class="quote">distance</span>”</span> between the arguments, that is
+ one minus the <code class="function">word_similarity()</code> value.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;-&gt;&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Commutator of the <code class="literal">&lt;&lt;-&gt;</code> operator.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;&lt;&lt;-&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Returns the <span class="quote">“<span class="quote">distance</span>”</span> between the arguments, that is
+ one minus the <code class="function">strict_word_similarity()</code> value.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">text</code> <code class="literal">&lt;-&gt;&gt;&gt;</code> <code class="type">text</code>
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Commutator of the <code class="literal">&lt;&lt;&lt;-&gt;</code> operator.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.44.7"><div class="titlepage"><div><div><h3 class="title">F.35.3. GUC Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-PGTRGM-SIMILARITY-THRESHOLD"><span class="term">
+ <code class="varname">pg_trgm.similarity_threshold</code> (<code class="type">real</code>)
+ <a id="id-1.11.7.44.7.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the current similarity threshold that is used by the <code class="literal">%</code>
+ operator. The threshold must be between 0 and 1 (default is 0.3).
+ </p></dd><dt id="GUC-PGTRGM-WORD-SIMILARITY-THRESHOLD"><span class="term">
+ <code class="varname">pg_trgm.word_similarity_threshold</code> (<code class="type">real</code>)
+ <a id="id-1.11.7.44.7.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the current word similarity threshold that is used by the
+ <code class="literal">&lt;%</code> and <code class="literal">%&gt;</code> operators. The threshold
+ must be between 0 and 1 (default is 0.6).
+ </p></dd><dt id="GUC-PGTRGM-STRICT-WORD-SIMILARITY-THRESHOLD"><span class="term">
+ <code class="varname">pg_trgm.strict_word_similarity_threshold</code> (<code class="type">real</code>)
+ <a id="id-1.11.7.44.7.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the current strict word similarity threshold that is used by the
+ <code class="literal">&lt;&lt;%</code> and <code class="literal">%&gt;&gt;</code> operators. The threshold
+ must be between 0 and 1 (default is 0.5).
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.44.8"><div class="titlepage"><div><div><h3 class="title">F.35.4. Index Support</h3></div></div></div><p>
+ The <code class="filename">pg_trgm</code> module provides GiST and GIN index
+ operator classes that allow you to create an index over a text column for
+ the purpose of very fast similarity searches. These index types support
+ the above-described similarity operators, and additionally support
+ trigram-based index searches for <code class="literal">LIKE</code>, <code class="literal">ILIKE</code>,
+ <code class="literal">~</code>, <code class="literal">~*</code> and <code class="literal">=</code> queries.
+ Inequality operators are not supported.
+ Note that those indexes may not be as efficient as regular B-tree indexes
+ for equality operator.
+ </p><p>
+ Example:
+
+</p><pre class="programlisting">
+CREATE TABLE test_trgm (t text);
+CREATE INDEX trgm_idx ON test_trgm USING GIST (t gist_trgm_ops);
+</pre><p>
+or
+</p><pre class="programlisting">
+CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops);
+</pre><p>
+ </p><p>
+ <code class="literal">gist_trgm_ops</code> GiST opclass approximates a set of
+ trigrams as a bitmap signature. Its optional integer parameter
+ <code class="literal">siglen</code> determines the
+ signature length in bytes. The default length is 12 bytes.
+ Valid values of signature length are between 1 and 2024 bytes. Longer
+ signatures lead to a more precise search (scanning a smaller fraction of the index and
+ fewer heap pages), at the cost of a larger index.
+ </p><p>
+ Example of creating such an index with a signature length of 32 bytes:
+ </p><pre class="programlisting">
+CREATE INDEX trgm_idx ON test_trgm USING GIST (t gist_trgm_ops(siglen=32));
+</pre><p>
+ At this point, you will have an index on the <code class="structfield">t</code> column that
+ you can use for similarity searching. A typical query is
+</p><pre class="programlisting">
+SELECT t, similarity(t, '<em class="replaceable"><code>word</code></em>') AS sml
+ FROM test_trgm
+ WHERE t % '<em class="replaceable"><code>word</code></em>'
+ ORDER BY sml DESC, t;
+</pre><p>
+ This will return all values in the text column that are sufficiently
+ similar to <em class="replaceable"><code>word</code></em>, sorted from best match to worst. The
+ index will be used to make this a fast operation even over very large data
+ sets.
+ </p><p>
+ A variant of the above query is
+</p><pre class="programlisting">
+SELECT t, t &lt;-&gt; '<em class="replaceable"><code>word</code></em>' AS dist
+ FROM test_trgm
+ ORDER BY dist LIMIT 10;
+</pre><p>
+ This can be implemented quite efficiently by GiST indexes, but not
+ by GIN indexes. It will usually beat the first formulation when only
+ a small number of the closest matches is wanted.
+ </p><p>
+ Also you can use an index on the <code class="structfield">t</code> column for word
+ similarity or strict word similarity. Typical queries are:
+</p><pre class="programlisting">
+SELECT t, word_similarity('<em class="replaceable"><code>word</code></em>', t) AS sml
+ FROM test_trgm
+ WHERE '<em class="replaceable"><code>word</code></em>' &lt;% t
+ ORDER BY sml DESC, t;
+</pre><p>
+ and
+</p><pre class="programlisting">
+SELECT t, strict_word_similarity('<em class="replaceable"><code>word</code></em>', t) AS sml
+ FROM test_trgm
+ WHERE '<em class="replaceable"><code>word</code></em>' &lt;&lt;% t
+ ORDER BY sml DESC, t;
+</pre><p>
+ This will return all values in the text column for which there is a
+ continuous extent in the corresponding ordered trigram set that is
+ sufficiently similar to the trigram set of <em class="replaceable"><code>word</code></em>,
+ sorted from best match to worst. The index will be used to make this
+ a fast operation even over very large data sets.
+ </p><p>
+ Possible variants of the above queries are:
+</p><pre class="programlisting">
+SELECT t, '<em class="replaceable"><code>word</code></em>' &lt;&lt;-&gt; t AS dist
+ FROM test_trgm
+ ORDER BY dist LIMIT 10;
+</pre><p>
+ and
+</p><pre class="programlisting">
+SELECT t, '<em class="replaceable"><code>word</code></em>' &lt;&lt;&lt;-&gt; t AS dist
+ FROM test_trgm
+ ORDER BY dist LIMIT 10;
+</pre><p>
+ This can be implemented quite efficiently by GiST indexes, but not
+ by GIN indexes.
+ </p><p>
+ Beginning in <span class="productname">PostgreSQL</span> 9.1, these index types also support
+ index searches for <code class="literal">LIKE</code> and <code class="literal">ILIKE</code>, for example
+</p><pre class="programlisting">
+SELECT * FROM test_trgm WHERE t LIKE '%foo%bar';
+</pre><p>
+ The index search works by extracting trigrams from the search string
+ and then looking these up in the index. The more trigrams in the search
+ string, the more effective the index search is. Unlike B-tree based
+ searches, the search string need not be left-anchored.
+ </p><p>
+ Beginning in <span class="productname">PostgreSQL</span> 9.3, these index types also support
+ index searches for regular-expression matches
+ (<code class="literal">~</code> and <code class="literal">~*</code> operators), for example
+</p><pre class="programlisting">
+SELECT * FROM test_trgm WHERE t ~ '(foo|bar)';
+</pre><p>
+ The index search works by extracting trigrams from the regular expression
+ and then looking these up in the index. The more trigrams that can be
+ extracted from the regular expression, the more effective the index search
+ is. Unlike B-tree based searches, the search string need not be
+ left-anchored.
+ </p><p>
+ For both <code class="literal">LIKE</code> and regular-expression searches, keep in mind
+ that a pattern with no extractable trigrams will degenerate to a full-index
+ scan.
+ </p><p>
+ The choice between GiST and GIN indexing depends on the relative
+ performance characteristics of GiST and GIN, which are discussed elsewhere.
+ </p></div><div class="sect2" id="id-1.11.7.44.9"><div class="titlepage"><div><div><h3 class="title">F.35.5. Text Search Integration</h3></div></div></div><p>
+ Trigram matching is a very useful tool when used in conjunction
+ with a full text index. In particular it can help to recognize
+ misspelled input words that will not be matched directly by the
+ full text search mechanism.
+ </p><p>
+ The first step is to generate an auxiliary table containing all
+ the unique words in the documents:
+
+</p><pre class="programlisting">
+CREATE TABLE words AS SELECT word FROM
+ ts_stat('SELECT to_tsvector(''simple'', bodytext) FROM documents');
+</pre><p>
+
+ where <code class="structname">documents</code> is a table that has a text field
+ <code class="structfield">bodytext</code> that we wish to search. The reason for using
+ the <code class="literal">simple</code> configuration with the <code class="function">to_tsvector</code>
+ function, instead of using a language-specific configuration,
+ is that we want a list of the original (unstemmed) words.
+ </p><p>
+ Next, create a trigram index on the word column:
+
+</p><pre class="programlisting">
+CREATE INDEX words_idx ON words USING GIN (word gin_trgm_ops);
+</pre><p>
+
+ Now, a <code class="command">SELECT</code> query similar to the previous example can
+ be used to suggest spellings for misspelled words in user search terms.
+ A useful extra test is to require that the selected words are also of
+ similar length to the misspelled word.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Since the <code class="structname">words</code> table has been generated as a separate,
+ static table, it will need to be periodically regenerated so that
+ it remains reasonably up-to-date with the document collection.
+ Keeping it exactly current is usually unnecessary.
+ </p></div></div><div class="sect2" id="id-1.11.7.44.10"><div class="titlepage"><div><div><h3 class="title">F.35.6. References</h3></div></div></div><p>
+ GiST Development Site
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/</a>
+ </p><p>
+ Tsearch2 Development Site
+ <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/</a>
+ </p></div><div class="sect2" id="id-1.11.7.44.11"><div class="titlepage"><div><div><h3 class="title">F.35.7. Authors</h3></div></div></div><p>
+ Oleg Bartunov <code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>, Moscow, Moscow University, Russia
+ </p><p>
+ Teodor Sigaev <code class="email">&lt;<a class="email" href="mailto:teodor@sigaev.ru">teodor@sigaev.ru</a>&gt;</code>, Moscow, Delta-Soft Ltd.,Russia
+ </p><p>
+ Alexander Korotkov <code class="email">&lt;<a class="email" href="mailto:a.korotkov@postgrespro.ru">a.korotkov@postgrespro.ru</a>&gt;</code>, Moscow, Postgres Professional, Russia
+ </p><p>
+ Documentation: Christopher Kings-Lynne
+ </p><p>
+ This module is sponsored by Delta-Soft Ltd., Moscow, Russia.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgsurgery.html" title="F.34. pg_surgery">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgvisibility.html" title="F.36. pg_visibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.34. pg_surgery </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.36. pg_visibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgupgrade.html b/doc/src/sgml/html/pgupgrade.html
new file mode 100644
index 0000000..6920586
--- /dev/null
+++ b/doc/src/sgml/html/pgupgrade.html
@@ -0,0 +1,432 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_upgrade</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgtesttiming.html" title="pg_test_timing" /><link rel="next" href="pgwaldump.html" title="pg_waldump" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_upgrade</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgtesttiming.html" title="pg_test_timing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgwaldump.html" title="pg_waldump">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGUPGRADE"><div class="titlepage"></div><a id="id-1.9.5.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_upgrade</span></span></h2><p>pg_upgrade — upgrade a <span class="productname">PostgreSQL</span> server instance</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.12.4.1"><code class="command">pg_upgrade</code> <code class="option">-b</code> <em class="replaceable"><code>oldbindir</code></em> [<code class="option">-B</code> <em class="replaceable"><code>newbindir</code></em>] <code class="option">-d</code> <em class="replaceable"><code>oldconfigdir</code></em> <code class="option">-D</code> <em class="replaceable"><code>newconfigdir</code></em> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.5.12.5"><h2>Description</h2><p>
+ <span class="application">pg_upgrade</span> (formerly called <span class="application">pg_migrator</span>) allows data
+ stored in <span class="productname">PostgreSQL</span> data files to be upgraded to a later <span class="productname">PostgreSQL</span>
+ major version without the data dump/restore typically required for
+ major version upgrades, e.g., from 9.5.8 to 9.6.4 or from 10.7 to 11.2.
+ It is not required for minor version upgrades, e.g., from 9.6.2 to 9.6.3
+ or from 10.1 to 10.2.
+ </p><p>
+ Major PostgreSQL releases regularly add new features that often
+ change the layout of the system tables, but the internal data storage
+ format rarely changes. <span class="application">pg_upgrade</span> uses this fact
+ to perform rapid upgrades by creating new system tables and simply
+ reusing the old user data files. If a future major release ever
+ changes the data storage format in a way that makes the old data
+ format unreadable, <span class="application">pg_upgrade</span> will not be usable
+ for such upgrades. (The community will attempt to avoid such
+ situations.)
+ </p><p>
+ <span class="application">pg_upgrade</span> does its best to
+ make sure the old and new clusters are binary-compatible, e.g., by
+ checking for compatible compile-time settings, including 32/64-bit
+ binaries. It is important that
+ any external modules are also binary compatible, though this cannot
+ be checked by <span class="application">pg_upgrade</span>.
+ </p><p>
+ pg_upgrade supports upgrades from 9.2.X and later to the current
+ major release of <span class="productname">PostgreSQL</span>, including snapshot and beta releases.
+ </p></div><div class="refsect1" id="id-1.9.5.12.6"><h2>Options</h2><p>
+ <span class="application">pg_upgrade</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-b</code> <em class="replaceable"><code>bindir</code></em><br /></span><span class="term"><code class="option">--old-bindir=</code><em class="replaceable"><code>bindir</code></em></span></dt><dd><p>the old PostgreSQL executable directory;
+ environment variable <code class="envar">PGBINOLD</code></p></dd><dt><span class="term"><code class="option">-B</code> <em class="replaceable"><code>bindir</code></em><br /></span><span class="term"><code class="option">--new-bindir=</code><em class="replaceable"><code>bindir</code></em></span></dt><dd><p>the new PostgreSQL executable directory;
+ default is the directory where <span class="application">pg_upgrade</span> resides;
+ environment variable <code class="envar">PGBINNEW</code></p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--check</code></span></dt><dd><p>check clusters only, don't change any data</p></dd><dt><span class="term"><code class="option">-d</code> <em class="replaceable"><code>configdir</code></em><br /></span><span class="term"><code class="option">--old-datadir=</code><em class="replaceable"><code>configdir</code></em></span></dt><dd><p>the old database cluster configuration directory; environment
+ variable <code class="envar">PGDATAOLD</code></p></dd><dt><span class="term"><code class="option">-D</code> <em class="replaceable"><code>configdir</code></em><br /></span><span class="term"><code class="option">--new-datadir=</code><em class="replaceable"><code>configdir</code></em></span></dt><dd><p>the new database cluster configuration directory; environment
+ variable <code class="envar">PGDATANEW</code></p></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>njobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>njobs</code></em></code></span></dt><dd><p>number of simultaneous processes or threads to use
+ </p></dd><dt><span class="term"><code class="option">-k</code><br /></span><span class="term"><code class="option">--link</code></span></dt><dd><p>use hard links instead of copying files to the new
+ cluster</p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">pg_upgrade</code> will wait for all files
+ of the upgraded cluster to be written safely to disk. This option
+ causes <code class="command">pg_upgrade</code> to return without waiting, which
+ is faster, but means that a subsequent operating system crash can leave
+ the data directory corrupt. Generally, this option is
+ useful for testing but should not be used on a production
+ installation.
+ </p></dd><dt><span class="term"><code class="option">-o</code> <em class="replaceable"><code>options</code></em><br /></span><span class="term"><code class="option">--old-options</code> <em class="replaceable"><code>options</code></em></span></dt><dd><p>options to be passed directly to the
+ old <code class="command">postgres</code> command; multiple
+ option invocations are appended</p></dd><dt><span class="term"><code class="option">-O</code> <em class="replaceable"><code>options</code></em><br /></span><span class="term"><code class="option">--new-options</code> <em class="replaceable"><code>options</code></em></span></dt><dd><p>options to be passed directly to the
+ new <code class="command">postgres</code> command; multiple
+ option invocations are appended</p></dd><dt><span class="term"><code class="option">-p</code> <em class="replaceable"><code>port</code></em><br /></span><span class="term"><code class="option">--old-port=</code><em class="replaceable"><code>port</code></em></span></dt><dd><p>the old cluster port number; environment
+ variable <code class="envar">PGPORTOLD</code></p></dd><dt><span class="term"><code class="option">-P</code> <em class="replaceable"><code>port</code></em><br /></span><span class="term"><code class="option">--new-port=</code><em class="replaceable"><code>port</code></em></span></dt><dd><p>the new cluster port number; environment
+ variable <code class="envar">PGPORTNEW</code></p></dd><dt><span class="term"><code class="option">-r</code><br /></span><span class="term"><code class="option">--retain</code></span></dt><dd><p>retain SQL and log files even after successful completion
+ </p></dd><dt><span class="term"><code class="option">-s</code> <em class="replaceable"><code>dir</code></em><br /></span><span class="term"><code class="option">--socketdir=</code><em class="replaceable"><code>dir</code></em></span></dt><dd><p>directory to use for postmaster sockets during upgrade;
+ default is current working directory; environment
+ variable <code class="envar">PGSOCKETDIR</code></p></dd><dt><span class="term"><code class="option">-U</code> <em class="replaceable"><code>username</code></em><br /></span><span class="term"><code class="option">--username=</code><em class="replaceable"><code>username</code></em></span></dt><dd><p>cluster's install user name; environment
+ variable <code class="envar">PGUSER</code></p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>enable verbose internal logging</p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>display version information, then exit</p></dd><dt><span class="term"><code class="option">--clone</code></span></dt><dd><p>
+ Use efficient file cloning (also known as <span class="quote">“<span class="quote">reflinks</span>”</span> on
+ some systems) instead of copying files to the new cluster. This can
+ result in near-instantaneous copying of the data files, giving the
+ speed advantages of <code class="option">-k</code>/<code class="option">--link</code> while
+ leaving the old cluster untouched.
+ </p><p>
+ File cloning is only supported on some operating systems and file
+ systems. If it is selected but not supported, the
+ <span class="application">pg_upgrade</span> run will error. At present, it
+ is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
+ file systems created with reflink support), and on macOS with APFS.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>show help, then exit</p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.12.7"><h2>Usage</h2><p>
+ These are the steps to perform an upgrade
+ with <span class="application">pg_upgrade</span>:
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p class="title"><strong>Optionally move the old cluster</strong></p><p>
+ If you are using a version-specific installation directory, e.g.,
+ <code class="filename">/opt/PostgreSQL/15</code>, you do not need to move the old cluster. The
+ graphical installers all use version-specific installation directories.
+ </p><p>
+ If your installation directory is not version-specific, e.g.,
+ <code class="filename">/usr/local/pgsql</code>, it is necessary to move the current PostgreSQL install
+ directory so it does not interfere with the new <span class="productname">PostgreSQL</span> installation.
+ Once the current <span class="productname">PostgreSQL</span> server is shut down, it is safe to rename the
+ PostgreSQL installation directory; assuming the old directory is
+ <code class="filename">/usr/local/pgsql</code>, you can do:
+
+</p><pre class="programlisting">
+mv /usr/local/pgsql /usr/local/pgsql.old
+</pre><p>
+ to rename the directory.
+ </p></li><li class="step"><p class="title"><strong>For source installs, build the new version</strong></p><p>
+ Build the new PostgreSQL source with <code class="command">configure</code> flags that are compatible
+ with the old cluster. <span class="application">pg_upgrade</span> will check <code class="command">pg_controldata</code> to make
+ sure all settings are compatible before starting the upgrade.
+ </p></li><li class="step"><p class="title"><strong>Install the new PostgreSQL binaries</strong></p><p>
+ Install the new server's binaries and support
+ files. <span class="application">pg_upgrade</span> is included in a default installation.
+ </p><p>
+ For source installs, if you wish to install the new server in a custom
+ location, use the <code class="literal">prefix</code> variable:
+
+</p><pre class="programlisting">
+make prefix=/usr/local/pgsql.new install
+</pre></li><li class="step"><p class="title"><strong>Initialize the new PostgreSQL cluster</strong></p><p>
+ Initialize the new cluster using <code class="command">initdb</code>.
+ Again, use compatible <code class="command">initdb</code>
+ flags that match the old cluster. Many
+ prebuilt installers do this step automatically. There is no need to
+ start the new cluster.
+ </p></li><li class="step"><p class="title"><strong>Install extension shared object files</strong></p><p>
+ Many extensions and custom modules, whether from
+ <code class="filename">contrib</code> or another source, use shared object
+ files (or DLLs), e.g., <code class="filename">pgcrypto.so</code>. If the old
+ cluster used these, shared object files matching the new server binary
+ must be installed in the new cluster, usually via operating system
+ commands. Do not load the schema definitions, e.g., <code class="command">CREATE
+ EXTENSION pgcrypto</code>, because these will be duplicated from
+ the old cluster. If extension updates are available,
+ <span class="application">pg_upgrade</span> will report this and create
+ a script that can be run later to update them.
+ </p></li><li class="step"><p class="title"><strong>Copy custom full-text search files</strong></p><p>
+ Copy any custom full text search files (dictionary, synonym,
+ thesaurus, stop words) from the old to the new cluster.
+ </p></li><li class="step"><p class="title"><strong>Adjust authentication</strong></p><p>
+ <code class="command">pg_upgrade</code> will connect to the old and new servers several
+ times, so you might want to set authentication to <code class="literal">peer</code>
+ in <code class="filename">pg_hba.conf</code> or use a <code class="filename">~/.pgpass</code> file
+ (see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).
+ </p></li><li class="step"><p class="title"><strong>Stop both servers</strong></p><p>
+ Make sure both database servers are stopped using, on Unix, e.g.:
+
+</p><pre class="programlisting">
+pg_ctl -D /opt/PostgreSQL/9.6 stop
+pg_ctl -D /opt/PostgreSQL/15 stop
+</pre><p>
+
+ or on Windows, using the proper service names:
+
+</p><pre class="programlisting">
+NET STOP postgresql-9.6
+NET STOP postgresql-15
+</pre><p>
+ </p><p>
+ Streaming replication and log-shipping standby servers must be
+ running during this shutdown so they receive all changes.
+ </p></li><li class="step"><p class="title"><strong>Prepare for standby server upgrades</strong></p><p>
+ If you are upgrading standby servers using methods outlined in section <a class="xref" href="pgupgrade.html#PGUPGRADE-STEP-REPLICAS" title="Upgrade streaming replication and log-shipping standby servers">Step 11</a>, verify that the old standby
+ servers are caught up by running <span class="application">pg_controldata</span>
+ against the old primary and standby clusters. Verify that the
+ <span class="quote">“<span class="quote">Latest checkpoint location</span>”</span> values match in all clusters.
+ Also, make sure <code class="varname">wal_level</code> is not set to
+ <code class="literal">minimal</code> in the <code class="filename">postgresql.conf</code> file on the
+ new primary cluster.
+ </p></li><li class="step"><p class="title"><strong>Run <span class="application">pg_upgrade</span></strong></p><p>
+ Always run the <span class="application">pg_upgrade</span> binary of the new server, not the old one.
+ <span class="application">pg_upgrade</span> requires the specification of the old and new cluster's
+ data and executable (<code class="filename">bin</code>) directories. You can also specify
+ user and port values, and whether you want the data files linked or cloned
+ instead of the default copy behavior.
+ </p><p>
+ If you use link mode, the upgrade will be much faster (no file
+ copying) and use less disk space, but you will not be able to access
+ your old cluster
+ once you start the new cluster after the upgrade. Link mode also
+ requires that the old and new cluster data directories be in the
+ same file system. (Tablespaces and <code class="filename">pg_wal</code> can be on
+ different file systems.)
+ Clone mode provides the same speed and disk space advantages but
+ does not cause the old cluster to be unusable once the new cluster
+ is started. Clone mode also requires that the old and new data
+ directories be in the same file system. This mode is only available
+ on certain operating systems and file systems.
+ </p><p>
+ The <code class="option">--jobs</code> option allows multiple CPU cores to be used
+ for copying/linking of files and to dump and restore database schemas
+ in parallel; a good place to start is the maximum of the number of
+ CPU cores and tablespaces. This option can dramatically reduce the
+ time to upgrade a multi-database server running on a multiprocessor
+ machine.
+ </p><p>
+ For Windows users, you must be logged into an administrative account, and
+ then start a shell as the <code class="literal">postgres</code> user and set the proper path:
+
+</p><pre class="programlisting">
+RUNAS /USER:postgres "CMD.EXE"
+SET PATH=%PATH%;C:\Program Files\PostgreSQL\15\bin;
+</pre><p>
+
+ and then run <span class="application">pg_upgrade</span> with quoted directories, e.g.:
+
+</p><pre class="programlisting">
+pg_upgrade.exe
+ --old-datadir "C:/Program Files/PostgreSQL/9.6/data"
+ --new-datadir "C:/Program Files/PostgreSQL/15/data"
+ --old-bindir "C:/Program Files/PostgreSQL/9.6/bin"
+ --new-bindir "C:/Program Files/PostgreSQL/15/bin"
+</pre><p>
+
+ Once started, <code class="command">pg_upgrade</code> will verify the two clusters are compatible
+ and then do the upgrade. You can use <code class="command">pg_upgrade --check</code>
+ to perform only the checks, even if the old server is still
+ running. <code class="command">pg_upgrade --check</code> will also outline any
+ manual adjustments you will need to make after the upgrade. If you
+ are going to be using link or clone mode, you should use the option
+ <code class="option">--link</code> or <code class="option">--clone</code> with
+ <code class="option">--check</code> to enable mode-specific checks.
+ <code class="command">pg_upgrade</code> requires write permission in the current directory.
+ </p><p>
+ Obviously, no one should be accessing the clusters during the
+ upgrade. <span class="application">pg_upgrade</span> defaults to running servers
+ on port 50432 to avoid unintended client connections.
+ You can use the same port number for both clusters when doing an
+ upgrade because the old and new clusters will not be running at the
+ same time. However, when checking an old running server, the old
+ and new port numbers must be different.
+ </p><p>
+ If an error occurs while restoring the database schema, <code class="command">pg_upgrade</code> will
+ exit and you will have to revert to the old cluster as outlined in <a class="xref" href="pgupgrade.html#PGUPGRADE-STEP-REVERT" title="Reverting to old cluster">Step 17</a>
+ below. To try <code class="command">pg_upgrade</code> again, you will need to modify the old
+ cluster so the pg_upgrade schema restore succeeds. If the problem is a
+ <code class="filename">contrib</code> module, you might need to uninstall the <code class="filename">contrib</code> module from
+ the old cluster and install it in the new cluster after the upgrade,
+ assuming the module is not being used to store user data.
+ </p></li><li class="step" id="PGUPGRADE-STEP-REPLICAS"><p class="title"><strong>Upgrade streaming replication and log-shipping standby servers</strong></p><p>
+ If you used link mode and have Streaming Replication (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>) or Log-Shipping (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>) standby servers, you can follow these steps to
+ quickly upgrade them. You will not be running <span class="application">pg_upgrade</span> on
+ the standby servers, but rather <span class="application">rsync</span> on the primary.
+ Do not start any servers yet.
+ </p><p>
+ If you did <span class="emphasis"><em>not</em></span> use link mode, do not have or do not
+ want to use <span class="application">rsync</span>, or want an easier solution, skip
+ the instructions in this section and simply recreate the standby
+ servers once <span class="application">pg_upgrade</span> completes and the new primary
+ is running.
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p class="title"><strong>Install the new PostgreSQL binaries on standby servers</strong></p><p>
+ Make sure the new binaries and support files are installed on all
+ standby servers.
+ </p></li><li class="step"><p class="title"><strong>Make sure the new standby data directories do <span class="emphasis"><em>not</em></span> exist</strong></p><p>
+ Make sure the new standby data directories do <span class="emphasis"><em>not</em></span>
+ exist or are empty. If <span class="application">initdb</span> was run, delete
+ the standby servers' new data directories.
+ </p></li><li class="step"><p class="title"><strong>Install extension shared object files</strong></p><p>
+ Install the same extension shared object files on the new standbys
+ that you installed in the new primary cluster.
+ </p></li><li class="step"><p class="title"><strong>Stop standby servers</strong></p><p>
+ If the standby servers are still running, stop them now using the
+ above instructions.
+ </p></li><li class="step"><p class="title"><strong>Save configuration files</strong></p><p>
+ Save any configuration files from the old standbys' configuration
+ directories you need to keep, e.g., <code class="filename">postgresql.conf</code>
+ (and any files included by it), <code class="filename">postgresql.auto.conf</code>,
+ <code class="literal">pg_hba.conf</code>, because these will be overwritten
+ or removed in the next step.
+ </p></li><li class="step"><p class="title"><strong>Run <span class="application">rsync</span></strong></p><p>
+ When using link mode, standby servers can be quickly upgraded using
+ <span class="application">rsync</span>. To accomplish this, from a directory on
+ the primary server that is above the old and new database cluster
+ directories, run this on the <span class="emphasis"><em>primary</em></span> for each standby
+ server:
+
+</p><pre class="programlisting">
+rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
+</pre><p>
+
+ where <code class="option">old_cluster</code> and <code class="option">new_cluster</code> are relative
+ to the current directory on the primary, and <code class="option">remote_dir</code>
+ is <span class="emphasis"><em>above</em></span> the old and new cluster directories
+ on the standby. The directory structure under the specified
+ directories on the primary and standbys must match. Consult the
+ <span class="application">rsync</span> manual page for details on specifying the
+ remote directory, e.g.,
+
+</p><pre class="programlisting">
+rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \
+ /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL
+</pre><p>
+
+ You can verify what the command will do using
+ <span class="application">rsync</span>'s <code class="option">--dry-run</code> option. While
+ <span class="application">rsync</span> must be run on the primary for at least one
+ standby, it is possible to run <span class="application">rsync</span> on an upgraded
+ standby to upgrade other standbys, as long as the upgraded standby
+ has not been started.
+ </p><p>
+ What this does is to record the links created by
+ <span class="application">pg_upgrade</span>'s link mode that connect files in the
+ old and new clusters on the primary server. It then finds matching
+ files in the standby's old cluster and creates links for them in the
+ standby's new cluster. Files that were not linked on the primary
+ are copied from the primary to the standby. (They are usually
+ small.) This provides rapid standby upgrades. Unfortunately,
+ <span class="application">rsync</span> needlessly copies files associated with
+ temporary and unlogged tables because these files don't normally
+ exist on standby servers.
+ </p><p>
+ If you have tablespaces, you will need to run a similar
+ <span class="application">rsync</span> command for each tablespace directory, e.g.:
+
+</p><pre class="programlisting">
+rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \
+ /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
+</pre><p>
+
+ If you have relocated <code class="filename">pg_wal</code> outside the data
+ directories, <span class="application">rsync</span> must be run on those directories
+ too.
+ </p></li><li class="step"><p class="title"><strong>Configure streaming replication and log-shipping standby servers</strong></p><p>
+ Configure the servers for log shipping. (You do not need to run
+ <code class="function">pg_backup_start()</code> and <code class="function">pg_backup_stop()</code>
+ or take a file system backup as the standbys are still synchronized
+ with the primary.) Replication slots are not copied and must
+ be recreated.
+ </p></li></ol></div></li><li class="step"><p class="title"><strong>Restore <code class="filename">pg_hba.conf</code></strong></p><p>
+ If you modified <code class="filename">pg_hba.conf</code>, restore its original settings.
+ It might also be necessary to adjust other configuration files in the new
+ cluster to match the old cluster, e.g., <code class="filename">postgresql.conf</code>
+ (and any files included by it), <code class="filename">postgresql.auto.conf</code>.
+ </p></li><li class="step"><p class="title"><strong>Start the new server</strong></p><p>
+ The new server can now be safely started, and then any
+ <span class="application">rsync</span>'ed standby servers.
+ </p></li><li class="step"><p class="title"><strong>Post-upgrade processing</strong></p><p>
+ If any post-upgrade processing is required, pg_upgrade will issue
+ warnings as it completes. It will also generate script files that must
+ be run by the administrator. The script files will connect to each
+ database that needs post-upgrade processing. Each script should be
+ run using:
+
+</p><pre class="programlisting">
+psql --username=postgres --file=script.sql postgres
+</pre><p>
+
+ The scripts can be run in any order and can be deleted once they have
+ been run.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ In general it is unsafe to access tables referenced in rebuild scripts
+ until the rebuild scripts have run to completion; doing so could yield
+ incorrect results or poor performance. Tables not referenced in rebuild
+ scripts can be accessed immediately.
+ </p></div></li><li class="step"><p class="title"><strong>Statistics</strong></p><p>
+ Because optimizer statistics are not transferred by <code class="command">pg_upgrade</code>, you will
+ be instructed to run a command to regenerate that information at the end
+ of the upgrade. You might need to set connection parameters to
+ match your new cluster.
+ </p></li><li class="step"><p class="title"><strong>Delete old cluster</strong></p><p>
+ Once you are satisfied with the upgrade, you can delete the old
+ cluster's data directories by running the script mentioned when
+ <code class="command">pg_upgrade</code> completes. (Automatic deletion is not
+ possible if you have user-defined tablespaces inside the old data
+ directory.) You can also delete the old installation directories
+ (e.g., <code class="filename">bin</code>, <code class="filename">share</code>).
+ </p></li><li class="step" id="PGUPGRADE-STEP-REVERT"><p class="title"><strong>Reverting to old cluster</strong></p><p>
+ If, after running <code class="command">pg_upgrade</code>, you wish to revert to the old cluster,
+ there are several options:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If the <code class="option">--check</code> option was used, the old cluster
+ was unmodified; it can be restarted.
+ </p></li><li class="listitem"><p>
+ If the <code class="option">--link</code> option was <span class="emphasis"><em>not</em></span>
+ used, the old cluster was unmodified; it can be restarted.
+ </p></li><li class="listitem"><p>
+ If the <code class="option">--link</code> option was used, the data
+ files might be shared between the old and new cluster:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ If <code class="command">pg_upgrade</code> aborted before linking started,
+ the old cluster was unmodified; it can be restarted.
+ </p></li><li class="listitem"><p>
+ If you did <span class="emphasis"><em>not</em></span> start the new cluster, the old
+ cluster was unmodified except that, when linking started, a
+ <code class="literal">.old</code> suffix was appended to
+ <code class="filename">$PGDATA/global/pg_control</code>. To reuse the old
+ cluster, remove the <code class="filename">.old</code> suffix from
+ <code class="filename">$PGDATA/global/pg_control</code>; you can then restart
+ the old cluster.
+ </p></li><li class="listitem"><p>
+ If you did start the new cluster, it has written to shared files
+ and it is unsafe to use the old cluster. The old cluster will
+ need to be restored from backup in this case.
+ </p></li></ul></div></li></ul></div></li></ol></div></div><div class="refsect1" id="id-1.9.5.12.8"><h2>Notes</h2><p>
+ <span class="application">pg_upgrade</span> creates various working files, such
+ as schema dumps, stored within <code class="filename">pg_upgrade_output.d</code> in
+ the directory of the new cluster. Each run creates a new subdirectory named
+ with a timestamp formatted as per ISO 8601
+ (<code class="literal">%Y%m%dT%H%M%S</code>), where all its generated files are
+ stored.
+ <code class="filename">pg_upgrade_output.d</code> and its contained files will be
+ removed automatically if <span class="application">pg_upgrade</span> completes
+ successfully; but in the event of trouble, the files there may provide
+ useful debugging information.
+ </p><p>
+ <span class="application">pg_upgrade</span> launches short-lived postmasters in
+ the old and new data directories. Temporary Unix socket files for
+ communication with these postmasters are, by default, made in the current
+ working directory. In some situations the path name for the current
+ directory might be too long to be a valid socket name. In that case you
+ can use the <code class="option">-s</code> option to put the socket files in some
+ directory with a shorter path name. For security, be sure that that
+ directory is not readable or writable by any other users.
+ (This is not supported on Windows.)
+ </p><p>
+ All failure, rebuild, and reindex cases will be reported by
+ <span class="application">pg_upgrade</span> if they affect your installation;
+ post-upgrade scripts to rebuild tables and indexes will be
+ generated automatically. If you are trying to automate the upgrade
+ of many clusters, you should find that clusters with identical database
+ schemas require the same post-upgrade steps for all cluster upgrades;
+ this is because the post-upgrade steps are based on the database
+ schemas, and not user data.
+ </p><p>
+ For deployment testing, create a schema-only copy of the old cluster,
+ insert dummy data, and upgrade that.
+ </p><p>
+ <span class="application">pg_upgrade</span> does not support upgrading of databases
+ containing table columns using these <code class="type">reg*</code> OID-referencing system data types:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="type">regcollation</code></td></tr><tr><td><code class="type">regconfig</code></td></tr><tr><td><code class="type">regdictionary</code></td></tr><tr><td><code class="type">regnamespace</code></td></tr><tr><td><code class="type">regoper</code></td></tr><tr><td><code class="type">regoperator</code></td></tr><tr><td><code class="type">regproc</code></td></tr><tr><td><code class="type">regprocedure</code></td></tr></table><p>
+ (<code class="type">regclass</code>, <code class="type">regrole</code>, and <code class="type">regtype</code> can be upgraded.)
+ </p><p>
+ If you want to use link mode and you do not want your old cluster
+ to be modified when the new cluster is started, consider using the clone mode.
+ If that is not available, make a copy of the
+ old cluster and upgrade that in link mode. To make a valid copy
+ of the old cluster, use <code class="command">rsync</code> to create a dirty
+ copy of the old cluster while the server is running, then shut down
+ the old server and run <code class="command">rsync --checksum</code> again to update the
+ copy with any changes to make it consistent. (<code class="option">--checksum</code>
+ is necessary because <code class="command">rsync</code> only has file modification-time
+ granularity of one second.) You might want to exclude some
+ files, e.g., <code class="filename">postmaster.pid</code>, as documented in <a class="xref" href="continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP" title="26.3.3. Making a Base Backup Using the Low Level API">Section 26.3.3</a>. If your file system supports
+ file system snapshots or copy-on-write file copies, you can use that
+ to make a backup of the old cluster and tablespaces, though the snapshot
+ and copies must be created simultaneously or while the database server
+ is down.
+ </p></div><div class="refsect1" id="id-1.9.5.12.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>, <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>, <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a>, <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgtesttiming.html" title="pg_test_timing">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgwaldump.html" title="pg_waldump">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_test_timing</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_waldump</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgvisibility.html b/doc/src/sgml/html/pgvisibility.html
new file mode 100644
index 0000000..64ef650
--- /dev/null
+++ b/doc/src/sgml/html/pgvisibility.html
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.36. pg_visibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgtrgm.html" title="F.35. pg_trgm" /><link rel="next" href="pgwalinspect.html" title="F.37. pg_walinspect" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.36. pg_visibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgtrgm.html" title="F.35. pg_trgm">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgwalinspect.html" title="F.37. pg_walinspect">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGVISIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.36. pg_visibility</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgvisibility.html#id-1.11.7.45.6">F.36.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgvisibility.html#id-1.11.7.45.7">F.36.2. Author</a></span></dt></dl></div><a id="id-1.11.7.45.2" class="indexterm"></a><p>
+ The <code class="filename">pg_visibility</code> module provides a means for examining the
+ visibility map (VM) and page-level visibility information of a table.
+ It also provides functions to check the integrity of a visibility map and to
+ force it to be rebuilt.
+ </p><p>
+ Three different bits are used to store information about page-level
+ visibility. The all-visible bit in the visibility map indicates that every
+ tuple in the corresponding page of the relation is visible to every current
+ and future transaction. The all-frozen bit in the visibility map indicates
+ that every tuple in the page is frozen; that is, no future vacuum will need
+ to modify the page until such time as a tuple is inserted, updated, deleted,
+ or locked on that page.
+ The page header's <code class="literal">PD_ALL_VISIBLE</code> bit has the
+ same meaning as the all-visible bit in the visibility map, but is stored
+ within the data page itself rather than in a separate data structure.
+ These two bits will normally agree, but the page's all-visible bit can
+ sometimes be set while the visibility map bit is clear after a crash
+ recovery. The reported values can also disagree because of a change that
+ occurs after <code class="literal">pg_visibility</code> examines the visibility map and
+ before it examines the data page. Any event that causes data corruption
+ can also cause these bits to disagree.
+ </p><p>
+ Functions that display information about <code class="literal">PD_ALL_VISIBLE</code> bits
+ are much more costly than those that only consult the visibility map,
+ because they must read the relation's data blocks rather than only the
+ (much smaller) visibility map. Functions that check the relation's
+ data blocks are similarly expensive.
+ </p><div class="sect2" id="id-1.11.7.45.6"><div class="titlepage"><div><div><h3 class="title">F.36.1. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">pg_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</code></span></dt><dd><p>
+ Returns the all-visible and all-frozen bits in the visibility map for
+ the given block of the given relation.
+ </p></dd><dt><span class="term"><code class="function">pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</code></span></dt><dd><p>
+ Returns the all-visible and all-frozen bits in the visibility map for
+ the given block of the given relation, plus the
+ <code class="literal">PD_ALL_VISIBLE</code> bit of that block.
+ </p></dd><dt><span class="term"><code class="function">pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</code></span></dt><dd><p>
+ Returns the all-visible and all-frozen bits in the visibility map for
+ each block of the given relation.
+ </p></dd><dt><span class="term"><code class="function">pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</code></span></dt><dd><p>
+ Returns the all-visible and all-frozen bits in the visibility map for
+ each block of the given relation, plus the <code class="literal">PD_ALL_VISIBLE</code>
+ bit of each block.
+ </p></dd><dt><span class="term"><code class="function">pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</code></span></dt><dd><p>
+ Returns the number of all-visible pages and the number of all-frozen
+ pages in the relation according to the visibility map.
+ </p></dd><dt><span class="term"><code class="function">pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</code></span></dt><dd><p>
+ Returns the TIDs of non-frozen tuples stored in pages marked all-frozen
+ in the visibility map. If this function returns a non-empty set of
+ TIDs, the visibility map is corrupt.
+ </p></dd><dt><span class="term"><code class="function">pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</code></span></dt><dd><p>
+ Returns the TIDs of non-all-visible tuples stored in pages marked
+ all-visible in the visibility map. If this function returns a non-empty
+ set of TIDs, the visibility map is corrupt.
+ </p></dd><dt><span class="term"><code class="function">pg_truncate_visibility_map(relation regclass) returns void</code></span></dt><dd><p>
+ Truncates the visibility map for the given relation. This function is
+ useful if you believe that the visibility map for the relation is
+ corrupt and wish to force rebuilding it. The first <code class="command">VACUUM</code>
+ executed on the given relation after this function is executed will scan
+ every page in the relation and rebuild the visibility map. (Until that
+ is done, queries will treat the visibility map as containing all zeroes.)
+ </p></dd></dl></div><p>
+ By default, these functions are executable only by superusers and roles with privileges
+ of the <code class="literal">pg_stat_scan_tables</code> role, with the exception of
+ <code class="function">pg_truncate_visibility_map(relation regclass)</code> which can only
+ be executed by superusers.
+ </p></div><div class="sect2" id="id-1.11.7.45.7"><div class="titlepage"><div><div><h3 class="title">F.36.2. Author</h3></div></div></div><p>
+ Robert Haas <code class="email">&lt;<a class="email" href="mailto:rhaas@postgresql.org">rhaas@postgresql.org</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgtrgm.html" title="F.35. pg_trgm">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgwalinspect.html" title="F.37. pg_walinspect">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.35. pg_trgm </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.37. pg_walinspect</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgwaldump.html b/doc/src/sgml/html/pgwaldump.html
new file mode 100644
index 0000000..9346c1b
--- /dev/null
+++ b/doc/src/sgml/html/pgwaldump.html
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_waldump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgupgrade.html" title="pg_upgrade" /><link rel="next" href="app-postgres.html" title="postgres" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_waldump</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgupgrade.html" title="pg_upgrade">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-postgres.html" title="postgres">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGWALDUMP"><div class="titlepage"></div><a id="id-1.9.5.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_waldump</span></span></h2><p>pg_waldump — display a human-readable rendering of the write-ahead log of a <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.13.4.1"><code class="command">pg_waldump</code> [<code class="option">option</code>...] [<code class="option">startseg</code> [<code class="option">endseg</code>]]</p></div></div><div class="refsect1" id="R1-APP-PGWALDUMP-1"><h2>Description</h2><p>
+ <code class="command">pg_waldump</code> displays the write-ahead log (WAL) and is mainly
+ useful for debugging or educational purposes.
+ </p><p>
+ This utility can only be run by the user who installed the server, because
+ it requires read-only access to the data directory.
+ </p></div><div class="refsect1" id="id-1.9.5.13.6"><h2>Options</h2><p>
+ The following command-line options control the location and format of the
+ output:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>startseg</code></em></span></dt><dd><p>
+ Start reading at the specified log segment file. This implicitly determines
+ the path in which files will be searched for, and the timeline to use.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>endseg</code></em></span></dt><dd><p>
+ Stop after reading the specified log segment file.
+ </p></dd><dt><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--bkp-details</code></span></dt><dd><p>
+ Output detailed information about backup blocks.
+ </p></dd><dt><span class="term"><code class="option">-B <em class="replaceable"><code>block</code></em></code><br /></span><span class="term"><code class="option">--block=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
+ Only display records that modify the given block. The relation must
+ also be provided with <code class="option">--relation</code> or
+ <code class="option">-R</code>.
+ </p></dd><dt><span class="term"><code class="option">-e <em class="replaceable"><code>end</code></em></code><br /></span><span class="term"><code class="option">--end=<em class="replaceable"><code>end</code></em></code></span></dt><dd><p>
+ Stop reading at the specified WAL location, instead of reading to the
+ end of the log stream.
+ </p></dd><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--follow</code></span></dt><dd><p>
+ After reaching the end of valid WAL, keep polling once per second for
+ new WAL to appear.
+ </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>fork</code></em></code><br /></span><span class="term"><code class="option">--fork=<em class="replaceable"><code>fork</code></em></code></span></dt><dd><p>
+ If provided, only display records that modify blocks in the given fork.
+ The valid values are <code class="literal">main</code> for the main fork,
+ <code class="literal">fsm</code> for the free space map,
+ <code class="literal">vm</code> for the visibility map,
+ and <code class="literal">init</code> for the init fork.
+ </p></dd><dt><span class="term"><code class="option">-n <em class="replaceable"><code>limit</code></em></code><br /></span><span class="term"><code class="option">--limit=<em class="replaceable"><code>limit</code></em></code></span></dt><dd><p>
+ Display the specified number of records, then stop.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--path=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
+ Specifies a directory to search for log segment files or a
+ directory with a <code class="literal">pg_wal</code> subdirectory that
+ contains such files. The default is to search in the current
+ directory, the <code class="literal">pg_wal</code> subdirectory of the
+ current directory, and the <code class="literal">pg_wal</code> subdirectory
+ of <code class="envar">PGDATA</code>.
+ </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
+ Do not print any output, except for errors. This option can be useful
+ when you want to know whether a range of WAL records can be
+ successfully parsed but don't care about the record contents.
+ </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>rmgr</code></em></code><br /></span><span class="term"><code class="option">--rmgr=<em class="replaceable"><code>rmgr</code></em></code></span></dt><dd><p>
+ Only display records generated by the specified resource manager. You can
+ specify the option multiple times to select multiple resource managers.
+ If <code class="literal">list</code> is passed as name, print a list of valid resource manager
+ names, and exit.
+ </p><p>
+ Extensions may define custom resource managers, but pg_waldump does
+ not load the extension module and therefore does not recognize custom
+ resource managers by name. Instead, you can specify the custom
+ resource managers as <code class="literal">custom###</code> where
+ "<code class="literal">###</code>" is the three-digit resource manager ID. Names
+ of this form will always be considered valid.
+ </p></dd><dt><span class="term"><code class="option">-R <em class="replaceable"><code>tblspc</code></em>/<em class="replaceable"><code>db</code></em>/<em class="replaceable"><code>rel</code></em></code><br /></span><span class="term"><code class="option">--relation=<em class="replaceable"><code>tblspc</code></em>/<em class="replaceable"><code>db</code></em>/<em class="replaceable"><code>rel</code></em></code></span></dt><dd><p>
+ Only display records that modify blocks in the given relation. The
+ relation is specified with tablespace OID, database OID, and relfilenode
+ separated by slashes, for example <code class="literal">1234/12345/12345</code>.
+ This is the same format used for relations in the program's output.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>start</code></em></code><br /></span><span class="term"><code class="option">--start=<em class="replaceable"><code>start</code></em></code></span></dt><dd><p>
+ WAL location at which to start reading. The default is to start reading
+ the first valid log record found in the earliest file found.
+ </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>timeline</code></em></code><br /></span><span class="term"><code class="option">--timeline=<em class="replaceable"><code>timeline</code></em></code></span></dt><dd><p>
+ Timeline from which to read log records. The default is to use the
+ value in <em class="replaceable"><code>startseg</code></em>, if that is specified; otherwise, the
+ default is 1.
+ </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_waldump</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--fullpage</code></span></dt><dd><p>
+ Only display records that include full page images.
+ </p></dd><dt><span class="term"><code class="option">-x <em class="replaceable"><code>xid</code></em></code><br /></span><span class="term"><code class="option">--xid=<em class="replaceable"><code>xid</code></em></code></span></dt><dd><p>
+ Only display records marked with the given transaction ID.
+ </p></dd><dt><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--stats[=record]</code></span></dt><dd><p>
+ Display summary statistics (number and size of records and
+ full-page images) instead of individual records. Optionally
+ generate statistics per-record instead of per-rmgr.
+ </p><p>
+ If <span class="application">pg_waldump</span> is terminated by signal
+ <span class="systemitem">SIGINT</span>
+ (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>),
+ the summary of the statistics computed is displayed up to the
+ termination point. This operation is not supported on
+ <span class="productname">Windows</span>.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_waldump</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.13.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Data directory; see also the <code class="option">-p</code> option.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.13.8"><h2>Notes</h2><p>
+ Can give wrong results when the server is running.
+ </p><p>
+ Only the specified timeline is displayed (or the default, if none is
+ specified). Records in other timelines are ignored.
+ </p><p>
+ <span class="application">pg_waldump</span> cannot read WAL files with suffix
+ <code class="literal">.partial</code>. If those files need to be read, <code class="literal">.partial</code>
+ suffix needs to be removed from the file name.
+ </p></div><div class="refsect1" id="id-1.9.5.13.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="wal-internals.html" title="30.6. WAL Internals">Section 30.6</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgupgrade.html" title="pg_upgrade">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-postgres.html" title="postgres">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_upgrade</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">postgres</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgwalinspect.html b/doc/src/sgml/html/pgwalinspect.html
new file mode 100644
index 0000000..b26b30c
--- /dev/null
+++ b/doc/src/sgml/html/pgwalinspect.html
@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.37. pg_walinspect</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgvisibility.html" title="F.36. pg_visibility" /><link rel="next" href="postgres-fdw.html" title="F.38. postgres_fdw" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.37. pg_walinspect</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgvisibility.html" title="F.36. pg_visibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="postgres-fdw.html" title="F.38. postgres_fdw">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGWALINSPECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.37. pg_walinspect</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgwalinspect.html#id-1.11.7.46.8">F.37.1. General Functions</a></span></dt><dt><span class="sect2"><a href="pgwalinspect.html#id-1.11.7.46.9">F.37.2. Author</a></span></dt></dl></div><a id="id-1.11.7.46.2" class="indexterm"></a><p>
+ The <code class="filename">pg_walinspect</code> module provides SQL functions that
+ allow you to inspect the contents of write-ahead log of
+ a running <span class="productname">PostgreSQL</span> database cluster at a low
+ level, which is useful for debugging, analytical, reporting or
+ educational purposes. It is similar to <a class="xref" href="pgwaldump.html" title="pg_waldump"><span class="refentrytitle"><span class="application">pg_waldump</span></span></a>, but
+ accessible through SQL rather than a separate utility.
+ </p><p>
+ All the functions of this module will provide the WAL information using the
+ current server's timeline ID.
+ </p><p>
+ All the functions of this module will try to find the first valid WAL record
+ that is at or after the given <em class="replaceable"><code>in_lsn</code></em> or
+ <em class="replaceable"><code>start_lsn</code></em> and will emit error if no such record
+ is available. Similarly, the <em class="replaceable"><code>end_lsn</code></em> must be
+ available, and if it falls in the middle of a record, the entire record must
+ be available.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Some functions, such as <code class="function"><a class="link" href="functions-admin.html#PG-LOGICAL-EMIT-MESSAGE">pg_logical_emit_message</a></code>,
+ return the LSN <span class="emphasis"><em>after</em></span> the record just
+ inserted. Therefore, if you pass that LSN as
+ <em class="replaceable"><code>in_lsn</code></em> or <em class="replaceable"><code>start_lsn</code></em>
+ to one of these functions, it will return the <span class="emphasis"><em>next</em></span>
+ record.
+ </p></div><p>
+ By default, use of these functions is restricted to superusers and members of
+ the <code class="literal">pg_read_server_files</code> role. Access may be granted by
+ superusers to others using <code class="command">GRANT</code>.
+ </p><div class="sect2" id="id-1.11.7.46.8"><div class="titlepage"><div><div><h3 class="title">F.37.1. General Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">pg_get_wal_record_info(in_lsn pg_lsn) returns record</code>
+ </span></dt><dd><p>
+ Gets WAL record information of a given LSN. If the given LSN isn't
+ at the start of a WAL record, it gives the information of the next
+ available valid WAL record; or an error if no such record is found.
+ For example, usage of the function is as
+ follows:
+</p><pre class="screen">
+postgres=# SELECT * FROM pg_get_wal_record_info('0/1E826E98');
+-[ RECORD 1 ]----+----------------------------------------------------
+start_lsn | 0/1E826F20
+end_lsn | 0/1E826F60
+prev_lsn | 0/1E826C80
+xid | 0
+resource_manager | Heap2
+record_type | PRUNE
+record_length | 58
+main_data_length | 8
+fpi_length | 0
+description | snapshotConflictHorizon 33748 nredirected 0 ndead 2
+block_ref | blkref #0: rel 1663/5/60221 fork main blk 2
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">
+ pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn)
+ returns setof record
+ </code>
+ </span></dt><dd><p>
+ Gets information of all the valid WAL records between
+ <em class="replaceable"><code>start_lsn</code></em> and <em class="replaceable"><code>end_lsn</code></em>.
+ Returns one row per WAL record. If <em class="replaceable"><code>start_lsn</code></em>
+ or <em class="replaceable"><code>end_lsn</code></em> are not yet available, the
+ function will raise an error. For example:
+</p><pre class="screen">
+postgres=# SELECT * FROM pg_get_wal_records_info('0/1E913618', '0/1E913740') LIMIT 1;
+-[ RECORD 1 ]----+--------------------------------------------------------------
+start_lsn | 0/1E913618
+end_lsn | 0/1E913650
+prev_lsn | 0/1E9135A0
+xid | 0
+resource_manager | Standby
+record_type | RUNNING_XACTS
+record_length | 50
+main_data_length | 24
+fpi_length | 0
+description | nextXid 33775 latestCompletedXid 33774 oldestRunningXid 33775
+block_ref |
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">
+ pg_get_wal_records_info_till_end_of_wal(start_lsn pg_lsn)
+ returns setof record
+ </code>
+ </span></dt><dd><p>
+ This function is the same as <code class="function">pg_get_wal_records_info()</code>,
+ except that it gets information of all the valid WAL records from
+ <em class="replaceable"><code>start_lsn</code></em> till the end of WAL.
+ </p></dd><dt><span class="term">
+ <code class="function">
+ pg_get_wal_stats(start_lsn pg_lsn, end_lsn pg_lsn, per_record boolean DEFAULT false)
+ returns setof record
+ </code>
+ </span></dt><dd><p>
+ Gets statistics of all the valid WAL records between
+ <em class="replaceable"><code>start_lsn</code></em> and
+ <em class="replaceable"><code>end_lsn</code></em>. By default, it returns one row per
+ <em class="replaceable"><code>resource_manager</code></em> type. When
+ <em class="replaceable"><code>per_record</code></em> is set to <code class="literal">true</code>,
+ it returns one row per <em class="replaceable"><code>record_type</code></em>.
+ If <em class="replaceable"><code>start_lsn</code></em>
+ or <em class="replaceable"><code>end_lsn</code></em> are not yet available, the
+ function will raise an error. For example:
+</p><pre class="screen">
+postgres=# SELECT * FROM pg_get_wal_stats('0/1E847D00', '0/1E84F500')
+ WHERE count &gt; 0 AND
+ "resource_manager/record_type" = 'Transaction'
+ LIMIT 1;
+-[ RECORD 1 ]----------------+-------------------
+resource_manager/record_type | Transaction
+count | 2
+count_percentage | 8
+record_size | 875
+record_size_percentage | 41.23468426013195
+fpi_size | 0
+fpi_size_percentage | 0
+combined_size | 875
+combined_size_percentage | 2.8634072910530795
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="function">
+ pg_get_wal_stats_till_end_of_wal(start_lsn pg_lsn, per_record boolean DEFAULT false)
+ returns setof record
+ </code>
+ </span></dt><dd><p>
+ This function is the same as <code class="function">pg_get_wal_stats()</code>,
+ except that it gets statistics of all the valid WAL records from
+ <em class="replaceable"><code>start_lsn</code></em> till end of WAL.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.46.9"><div class="titlepage"><div><div><h3 class="title">F.37.2. Author</h3></div></div></div><p>
+ Bharath Rupireddy <code class="email">&lt;<a class="email" href="mailto:bharath.rupireddyforpostgres@gmail.com">bharath.rupireddyforpostgres@gmail.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgvisibility.html" title="F.36. pg_visibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres-fdw.html" title="F.38. postgres_fdw">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.36. pg_visibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.38. postgres_fdw</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pgxlogdump.html b/doc/src/sgml/html/pgxlogdump.html
new file mode 100644
index 0000000..1680f69
--- /dev/null
+++ b/doc/src/sgml/html/pgxlogdump.html
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>O.3. pg_xlogdump renamed to pg_waldump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles" /><link rel="next" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><th width="60%" align="center">Appendix O. Obsolete or Renamed Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGXLOGDUMP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">O.3. <code class="command">pg_xlogdump</code> renamed to <code class="command">pg_waldump</code></h2></div></div></div><a id="id-1.11.16.5.2" class="indexterm"></a><p>
+ PostgreSQL 9.6 and below provided a command named
+ <code class="command">pg_xlogdump</code>
+ <a id="id-1.11.16.5.3.2" class="indexterm"></a>
+ to read write-ahead-log (WAL) files. This command was renamed to <code class="command">pg_waldump</code>, see
+ <a class="xref" href="pgwaldump.html" title="pg_waldump"><span class="refentrytitle"><span class="application">pg_waldump</span></span></a> for documentation of <code class="command">pg_waldump</code> and see
+ <a class="link" href="release-prior.html" title="E.7. Prior Releases">the release notes for PostgreSQL 10</a> for details
+ on this change.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgresetxlog.html" title="O.4. pg_resetxlog renamed to pg_resetwal">Next</a></td></tr><tr><td width="40%" align="left" valign="top">O.2. Default Roles Renamed to Predefined Roles </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> O.4. <code class="command">pg_resetxlog</code> renamed to <code class="command">pg_resetwal</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/planner-optimizer.html b/doc/src/sgml/html/planner-optimizer.html
new file mode 100644
index 0000000..da8e3a1
--- /dev/null
+++ b/doc/src/sgml/html/planner-optimizer.html
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.5. Planner/Optimizer</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rule-system.html" title="52.4. The PostgreSQL Rule System" /><link rel="next" href="executor.html" title="52.6. Executor" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.5. Planner/Optimizer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rule-system.html" title="52.4. The PostgreSQL Rule System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="executor.html" title="52.6. Executor">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLANNER-OPTIMIZER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.5. Planner/Optimizer</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="planner-optimizer.html#id-1.10.3.8.5">52.5.1. Generating Possible Plans</a></span></dt></dl></div><p>
+ The task of the <em class="firstterm">planner/optimizer</em> is to
+ create an optimal execution plan. A given SQL query (and hence, a
+ query tree) can be actually executed in a wide variety of
+ different ways, each of which will produce the same set of
+ results. If it is computationally feasible, the query optimizer
+ will examine each of these possible execution plans, ultimately
+ selecting the execution plan that is expected to run the fastest.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In some situations, examining each possible way in which a query
+ can be executed would take an excessive amount of time and memory.
+ In particular, this occurs when executing queries
+ involving large numbers of join operations. In order to determine
+ a reasonable (not necessarily optimal) query plan in a reasonable amount
+ of time, <span class="productname">PostgreSQL</span> uses a <em class="firstterm">Genetic
+ Query Optimizer</em> (see <a class="xref" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Chapter 62</a>) when the number of joins
+ exceeds a threshold (see <a class="xref" href="runtime-config-query.html#GUC-GEQO-THRESHOLD">geqo_threshold</a>).
+ </p></div><p>
+ The planner's search procedure actually works with data structures
+ called <em class="firstterm">paths</em>, which are simply cut-down representations of
+ plans containing only as much information as the planner needs to make
+ its decisions. After the cheapest path is determined, a full-fledged
+ <em class="firstterm">plan tree</em> is built to pass to the executor. This represents
+ the desired execution plan in sufficient detail for the executor to run it.
+ In the rest of this section we'll ignore the distinction between paths
+ and plans.
+ </p><div class="sect2" id="id-1.10.3.8.5"><div class="titlepage"><div><div><h3 class="title">52.5.1. Generating Possible Plans</h3></div></div></div><p>
+ The planner/optimizer starts by generating plans for scanning each
+ individual relation (table) used in the query. The possible plans
+ are determined by the available indexes on each relation.
+ There is always the possibility of performing a
+ sequential scan on a relation, so a sequential scan plan is always
+ created. Assume an index is defined on a
+ relation (for example a B-tree index) and a query contains the
+ restriction
+ <code class="literal">relation.attribute OPR constant</code>. If
+ <code class="literal">relation.attribute</code> happens to match the key of the B-tree
+ index and <code class="literal">OPR</code> is one of the operators listed in
+ the index's <em class="firstterm">operator class</em>, another plan is created using
+ the B-tree index to scan the relation. If there are further indexes
+ present and the restrictions in the query happen to match a key of an
+ index, further plans will be considered. Index scan plans are also
+ generated for indexes that have a sort ordering that can match the
+ query's <code class="literal">ORDER BY</code> clause (if any), or a sort ordering that
+ might be useful for merge joining (see below).
+ </p><p>
+ If the query requires joining two or more relations,
+ plans for joining relations are considered
+ after all feasible plans have been found for scanning single relations.
+ The three available join strategies are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <em class="firstterm">nested loop join</em>: The right relation is scanned
+ once for every row found in the left relation. This strategy
+ is easy to implement but can be very time consuming. (However,
+ if the right relation can be scanned with an index scan, this can
+ be a good strategy. It is possible to use values from the current
+ row of the left relation as keys for the index scan of the right.)
+ </p></li><li class="listitem"><p>
+ <em class="firstterm">merge join</em>: Each relation is sorted on the join
+ attributes before the join starts. Then the two relations are
+ scanned in parallel, and matching rows are combined to form
+ join rows. This kind of join is
+ attractive because each relation has to be scanned only once.
+ The required sorting might be achieved either by an explicit sort
+ step, or by scanning the relation in the proper order using an
+ index on the join key.
+ </p></li><li class="listitem"><p>
+ <em class="firstterm">hash join</em>: the right relation is first scanned
+ and loaded into a hash table, using its join attributes as hash keys.
+ Next the left relation is scanned and the
+ appropriate values of every row found are used as hash keys to
+ locate the matching rows in the table.
+ </p></li></ul></div><p>
+ </p><p>
+ When the query involves more than two relations, the final result
+ must be built up by a tree of join steps, each with two inputs.
+ The planner examines different possible join sequences to find the
+ cheapest one.
+ </p><p>
+ If the query uses fewer than <a class="xref" href="runtime-config-query.html#GUC-GEQO-THRESHOLD">geqo_threshold</a>
+ 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 exists a corresponding join clause in the
+ <code class="literal">WHERE</code> qualification (i.e., for
+ which a restriction like <code class="literal">where rel1.attr1=rel2.attr2</code>
+ exists). Join pairs with no join clause are considered only when there
+ is no other choice, that is, a particular relation has no available
+ join clauses to any other relation. All possible plans are generated for
+ every join pair considered by the planner, and the one that is
+ (estimated to be) the cheapest is chosen.
+ </p><p>
+ When <code class="varname">geqo_threshold</code> is exceeded, the join
+ sequences considered are determined by heuristics, as described
+ in <a class="xref" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Chapter 62</a>. Otherwise the process is the same.
+ </p><p>
+ The finished plan tree consists of sequential or index scans of
+ the base relations, plus nested-loop, merge, or hash join nodes as
+ needed, plus any auxiliary steps needed, such as sort nodes or
+ aggregate-function calculation nodes. Most of these plan node
+ types have the additional ability to do <em class="firstterm">selection</em>
+ (discarding rows that do not meet a specified Boolean condition)
+ and <em class="firstterm">projection</em> (computation of a derived column set
+ based on given column values, that is, evaluation of scalar
+ expressions where needed). One of the responsibilities of the
+ planner is to attach selection conditions from the
+ <code class="literal">WHERE</code> clause and computation of required
+ output expressions to the most appropriate nodes of the plan
+ tree.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rule-system.html" title="52.4. The PostgreSQL Rule System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="executor.html" title="52.6. Executor">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.4. The <span class="productname">PostgreSQL</span> Rule System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.6. Executor</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/planner-stats-details.html b/doc/src/sgml/html/planner-stats-details.html
new file mode 100644
index 0000000..d6be293
--- /dev/null
+++ b/doc/src/sgml/html/planner-stats-details.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 75. How the Planner Uses Statistics</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki-example.html" title="74.6. BKI Example" /><link rel="next" href="row-estimation-examples.html" title="75.1. Row Estimation Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 75. How the Planner Uses Statistics</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki-example.html" title="74.6. BKI Example">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="row-estimation-examples.html" title="75.1. Row Estimation Examples">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLANNER-STATS-DETAILS"><div class="titlepage"><div><div><h2 class="title">Chapter 75. How the Planner Uses Statistics</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="row-estimation-examples.html">75.1. Row Estimation Examples</a></span></dt><dt><span class="sect1"><a href="multivariate-statistics-examples.html">75.2. Multivariate Statistics Examples</a></span></dt><dd><dl><dt><span class="sect2"><a href="multivariate-statistics-examples.html#FUNCTIONAL-DEPENDENCIES">75.2.1. Functional Dependencies</a></span></dt><dt><span class="sect2"><a href="multivariate-statistics-examples.html#MULTIVARIATE-NDISTINCT-COUNTS">75.2.2. Multivariate N-Distinct Counts</a></span></dt><dt><span class="sect2"><a href="multivariate-statistics-examples.html#MCV-LISTS">75.2.3. MCV Lists</a></span></dt></dl></dd><dt><span class="sect1"><a href="planner-stats-security.html">75.3. Planner Statistics and Security</a></span></dt></dl></div><p>
+ This chapter builds on the material covered in <a class="xref" href="using-explain.html" title="14.1. Using EXPLAIN">Section 14.1</a> and <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a> to show some
+ additional details about how the planner uses the
+ system statistics to estimate the number of rows each part of a query might
+ return. This is a significant part of the planning process,
+ providing much of the raw material for cost calculation.
+ </p><p>
+ The intent of this chapter is not to document the code in detail,
+ but to present an overview of how it works.
+ This will perhaps ease the learning curve for someone who subsequently
+ wishes to read the code.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki-example.html" title="74.6. BKI Example">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="row-estimation-examples.html" title="75.1. Row Estimation Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.6. BKI Example </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 75.1. Row Estimation Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/planner-stats-security.html b/doc/src/sgml/html/planner-stats-security.html
new file mode 100644
index 0000000..ce79081
--- /dev/null
+++ b/doc/src/sgml/html/planner-stats-security.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>75.3. Planner Statistics and Security</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples" /><link rel="next" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">75.3. Planner Statistics and Security</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><th width="60%" align="center">Chapter 75. How the Planner Uses Statistics</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLANNER-STATS-SECURITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">75.3. Planner Statistics and Security</h2></div></div></div><p>
+ Access to the table <code class="structname">pg_statistic</code> is restricted to
+ superusers, so that ordinary users cannot learn about the contents of the
+ tables of other users from it. Some selectivity estimation functions will
+ use a user-provided operator (either the operator appearing in the query or
+ a related operator) to analyze the stored statistics. For example, in order
+ to determine whether a stored most common value is applicable, the
+ selectivity estimator will have to run the appropriate <code class="literal">=</code>
+ operator to compare the constant in the query to the stored value.
+ Thus the data in <code class="structname">pg_statistic</code> is potentially
+ passed to user-defined operators. An appropriately crafted operator can
+ intentionally leak the passed operands (for example, by logging them
+ or writing them to a different table), or accidentally leak them by showing
+ their values in error messages, in either case possibly exposing data from
+ <code class="structname">pg_statistic</code> to a user who should not be able to
+ see it.
+ </p><p>
+ In order to prevent this, the following applies to all built-in selectivity
+ estimation functions. When planning a query, in order to be able to use
+ stored statistics, the current user must either
+ have <code class="literal">SELECT</code> privilege on the table or the involved
+ columns, or the operator used must be <code class="literal">LEAKPROOF</code> (more
+ accurately, the function that the operator is based on). If not, then the
+ selectivity estimator will behave as if no statistics are available, and
+ the planner will proceed with default or fall-back assumptions.
+ </p><p>
+ If a user does not have the required privilege on the table or columns,
+ then in many cases the query will ultimately receive a permission-denied
+ error, in which case this mechanism is invisible in practice. But if the
+ user is reading from a security-barrier view, then the planner might wish
+ to check the statistics of an underlying table that is otherwise
+ inaccessible to the user. In that case, the operator should be leak-proof
+ or the statistics will not be used. There is no direct feedback about
+ that, except that the plan might be suboptimal. If one suspects that this
+ is the case, one could try running the query as a more privileged user,
+ to see if a different plan results.
+ </p><p>
+ This restriction applies only to cases where the planner would need to
+ execute a user-defined operator on one or more values
+ from <code class="structname">pg_statistic</code>. Thus the planner is permitted
+ to use generic statistical information, such as the fraction of null values
+ or the number of distinct values in a column, regardless of access
+ privileges.
+ </p><p>
+ Selectivity estimation functions contained in third-party extensions that
+ potentially operate on statistics with user-defined operators should follow
+ the same security rules. Consult the PostgreSQL source code for guidance.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-manifest-format.html" title="Chapter 76. Backup Manifest Format">Next</a></td></tr><tr><td width="40%" align="left" valign="top">75.2. Multivariate Statistics Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 76. Backup Manifest Format</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/planner-stats.html b/doc/src/sgml/html/planner-stats.html
new file mode 100644
index 0000000..7cff365
--- /dev/null
+++ b/doc/src/sgml/html/planner-stats.html
@@ -0,0 +1,336 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>14.2. Statistics Used by the Planner</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="using-explain.html" title="14.1. Using EXPLAIN" /><link rel="next" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">14.2. Statistics Used by the Planner</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="using-explain.html" title="14.1. Using EXPLAIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><th width="60%" align="center">Chapter 14. Performance Tips</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLANNER-STATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">14.2. Statistics Used by the Planner</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="planner-stats.html#id-1.5.13.5.3">14.2.1. Single-Column Statistics</a></span></dt><dt><span class="sect2"><a href="planner-stats.html#PLANNER-STATS-EXTENDED">14.2.2. Extended Statistics</a></span></dt></dl></div><a id="id-1.5.13.5.2" class="indexterm"></a><div class="sect2" id="id-1.5.13.5.3"><div class="titlepage"><div><div><h3 class="title">14.2.1. Single-Column Statistics</h3></div></div></div><p>
+ As we saw in the previous section, the query planner needs to estimate
+ the number of rows retrieved by a query in order to make good choices
+ of query plans. This section provides a quick look at the statistics
+ that the system uses for these estimates.
+ </p><p>
+ One component of the statistics is the total number of entries in
+ each table and index, as well as the number of disk blocks occupied
+ by each table and index. This information is kept in the table
+ <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>,
+ in the columns <code class="structfield">reltuples</code> and
+ <code class="structfield">relpages</code>. We can look at it with
+ queries similar to this one:
+
+</p><pre class="screen">
+SELECT relname, relkind, reltuples, relpages
+FROM pg_class
+WHERE relname LIKE 'tenk1%';
+
+ relname | relkind | reltuples | relpages
+----------------------+---------+-----------+----------
+ tenk1 | r | 10000 | 358
+ tenk1_hundred | i | 10000 | 30
+ tenk1_thous_tenthous | i | 10000 | 30
+ tenk1_unique1 | i | 10000 | 30
+ tenk1_unique2 | i | 10000 | 30
+(5 rows)
+</pre><p>
+
+ Here we can see that <code class="structname">tenk1</code> contains 10000
+ rows, as do its indexes, but the indexes are (unsurprisingly) much
+ smaller than the table.
+ </p><p>
+ For efficiency reasons, <code class="structfield">reltuples</code>
+ and <code class="structfield">relpages</code> are not updated on-the-fly,
+ and so they usually contain somewhat out-of-date values.
+ They are updated by <code class="command">VACUUM</code>, <code class="command">ANALYZE</code>, and a
+ few DDL commands such as <code class="command">CREATE INDEX</code>. A <code class="command">VACUUM</code>
+ or <code class="command">ANALYZE</code> operation that does not scan the entire table
+ (which is commonly the case) will incrementally update the
+ <code class="structfield">reltuples</code> count on the basis of the part
+ of the table it did scan, resulting in an approximate value.
+ In any case, the planner
+ will scale the values it finds in <code class="structname">pg_class</code>
+ to match the current physical table size, thus obtaining a closer
+ approximation.
+ </p><a id="id-1.5.13.5.3.5" class="indexterm"></a><p>
+ Most queries retrieve only a fraction of the rows in a table, due
+ to <code class="literal">WHERE</code> clauses that restrict the rows to be
+ examined. The planner thus needs to make an estimate of the
+ <em class="firstterm">selectivity</em> of <code class="literal">WHERE</code> clauses, that is,
+ the fraction of rows that match each condition in the
+ <code class="literal">WHERE</code> clause. The information used for this task is
+ stored in the
+ <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>
+ system catalog. Entries in <code class="structname">pg_statistic</code>
+ are updated by the <code class="command">ANALYZE</code> and <code class="command">VACUUM
+ ANALYZE</code> commands, and are always approximate even when freshly
+ updated.
+ </p><a id="id-1.5.13.5.3.7" class="indexterm"></a><p>
+ Rather than look at <code class="structname">pg_statistic</code> directly,
+ it's better to look at its view
+ <a class="link" href="view-pg-stats.html" title="54.27. pg_stats"><code class="structname">pg_stats</code></a>
+ when examining the statistics manually. <code class="structname">pg_stats</code>
+ is designed to be more easily readable. Furthermore,
+ <code class="structname">pg_stats</code> is readable by all, whereas
+ <code class="structname">pg_statistic</code> is only readable by a superuser.
+ (This prevents unprivileged users from learning something about
+ the contents of other people's tables from the statistics. The
+ <code class="structname">pg_stats</code> view is restricted to show only
+ rows about tables that the current user can read.)
+ For example, we might do:
+
+</p><pre class="screen">
+SELECT attname, inherited, n_distinct,
+ array_to_string(most_common_vals, E'\n') as most_common_vals
+FROM pg_stats
+WHERE tablename = 'road';
+
+ attname | inherited | n_distinct | most_common_vals
+---------+-----------+------------+------------------------------------
+ name | f | -0.363388 | I- 580 Ramp+
+ | | | I- 880 Ramp+
+ | | | Sp Railroad +
+ | | | I- 580 +
+ | | | I- 680 Ramp
+ name | t | -0.284859 | I- 880 Ramp+
+ | | | I- 580 Ramp+
+ | | | I- 680 Ramp+
+ | | | I- 580 +
+ | | | State Hwy 13 Ramp
+(2 rows)
+</pre><p>
+
+ Note that two rows are displayed for the same column, one corresponding
+ to the complete inheritance hierarchy starting at the
+ <code class="literal">road</code> table (<code class="literal">inherited</code>=<code class="literal">t</code>),
+ and another one including only the <code class="literal">road</code> table itself
+ (<code class="literal">inherited</code>=<code class="literal">f</code>).
+ </p><p>
+ The amount of information stored in <code class="structname">pg_statistic</code>
+ by <code class="command">ANALYZE</code>, in particular the maximum number of entries in the
+ <code class="structfield">most_common_vals</code> and <code class="structfield">histogram_bounds</code>
+ arrays for each column, can be set on a
+ column-by-column basis using the <code class="command">ALTER TABLE SET STATISTICS</code>
+ command, or globally by setting the
+ <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> configuration variable.
+ The default limit is presently 100 entries. Raising the limit
+ might allow more accurate planner estimates to be made, particularly for
+ columns with irregular data distributions, at the price of consuming
+ more space in <code class="structname">pg_statistic</code> and slightly more
+ time to compute the estimates. Conversely, a lower limit might be
+ sufficient for columns with simple data distributions.
+ </p><p>
+ Further details about the planner's use of statistics can be found in
+ <a class="xref" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Chapter 75</a>.
+ </p></div><div class="sect2" id="PLANNER-STATS-EXTENDED"><div class="titlepage"><div><div><h3 class="title">14.2.2. Extended Statistics</h3></div></div></div><a id="id-1.5.13.5.4.2" class="indexterm"></a><a id="id-1.5.13.5.4.3" class="indexterm"></a><a id="id-1.5.13.5.4.4" class="indexterm"></a><a id="id-1.5.13.5.4.5" class="indexterm"></a><p>
+ It is common to see slow queries running bad execution plans because
+ multiple columns used in the query clauses are correlated.
+ The planner normally assumes that multiple conditions
+ are independent of each other,
+ an assumption that does not hold when column values are correlated.
+ Regular statistics, because of their per-individual-column nature,
+ cannot capture any knowledge about cross-column correlation.
+ However, <span class="productname">PostgreSQL</span> has the ability to compute
+ <em class="firstterm">multivariate statistics</em>, which can capture
+ such information.
+ </p><p>
+ Because the number of possible column combinations is very large,
+ it's impractical to compute multivariate statistics automatically.
+ Instead, <em class="firstterm">extended statistics objects</em>, more often
+ called just <em class="firstterm">statistics objects</em>, can be created to instruct
+ the server to obtain statistics across interesting sets of columns.
+ </p><p>
+ Statistics objects are created using the
+ <a class="link" href="sql-createstatistics.html" title="CREATE STATISTICS"><code class="command">CREATE STATISTICS</code></a> command.
+ Creation of such an object merely creates a catalog entry expressing
+ interest in the statistics. Actual data collection is performed
+ by <code class="command">ANALYZE</code> (either a manual command, or background
+ auto-analyze). The collected values can be examined in the
+ <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ catalog.
+ </p><p>
+ <code class="command">ANALYZE</code> computes extended statistics based on the same
+ sample of table rows that it takes for computing regular single-column
+ statistics. Since the sample size is increased by increasing the
+ statistics target for the table or any of its columns (as described in
+ the previous section), a larger statistics target will normally result in
+ more accurate extended statistics, as well as more time spent calculating
+ them.
+ </p><p>
+ The following subsections describe the kinds of extended statistics
+ that are currently supported.
+ </p><div class="sect3" id="id-1.5.13.5.4.11"><div class="titlepage"><div><div><h4 class="title">14.2.2.1. Functional Dependencies</h4></div></div></div><p>
+ The simplest kind of extended statistics tracks <em class="firstterm">functional
+ dependencies</em>, a concept used in definitions of database normal forms.
+ We say that column <code class="structfield">b</code> is functionally dependent on
+ column <code class="structfield">a</code> if knowledge of the value of
+ <code class="structfield">a</code> is sufficient to determine the value
+ of <code class="structfield">b</code>, that is there are no two rows having the same value
+ of <code class="structfield">a</code> but different values of <code class="structfield">b</code>.
+ In a fully normalized database, functional dependencies should exist
+ only on primary keys and superkeys. However, in practice many data sets
+ are not fully normalized for various reasons; intentional
+ denormalization for performance reasons is a common example.
+ Even in a fully normalized database, there may be partial correlation
+ between some columns, which can be expressed as partial functional
+ dependency.
+ </p><p>
+ The existence of functional dependencies directly affects the accuracy
+ of estimates in certain queries. If a query contains conditions on
+ both the independent and the dependent column(s), the
+ conditions on the dependent columns do not further reduce the result
+ size; but without knowledge of the functional dependency, the query
+ planner will assume that the conditions are independent, resulting
+ in underestimating the result size.
+ </p><p>
+ To inform the planner about functional dependencies, <code class="command">ANALYZE</code>
+ can collect measurements of cross-column dependency. Assessing the
+ degree of dependency between all sets of columns would be prohibitively
+ expensive, so data collection is limited to those groups of columns
+ appearing together in a statistics object defined with
+ the <code class="literal">dependencies</code> option. It is advisable to create
+ <code class="literal">dependencies</code> statistics only for column groups that are
+ strongly correlated, to avoid unnecessary overhead in both
+ <code class="command">ANALYZE</code> and later query planning.
+ </p><p>
+ Here is an example of collecting functional-dependency statistics:
+</p><pre class="programlisting">
+CREATE STATISTICS stts (dependencies) ON city, zip FROM zipcodes;
+
+ANALYZE zipcodes;
+
+SELECT stxname, stxkeys, stxddependencies
+ FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid)
+ WHERE stxname = 'stts';
+ stxname | stxkeys | stxddependencies
+---------+---------+------------------------------------------
+ stts | 1 5 | {"1 =&gt; 5": 1.000000, "5 =&gt; 1": 0.423130}
+(1 row)
+</pre><p>
+ Here it can be seen that column 1 (zip code) fully determines column
+ 5 (city) so the coefficient is 1.0, while city only determines zip code
+ about 42% of the time, meaning that there are many cities (58%) that are
+ represented by more than a single ZIP code.
+ </p><p>
+ When computing the selectivity for a query involving functionally
+ dependent columns, the planner adjusts the per-condition selectivity
+ estimates using the dependency coefficients so as not to produce
+ an underestimate.
+ </p><div class="sect4" id="id-1.5.13.5.4.11.7"><div class="titlepage"><div><div><h5 class="title">14.2.2.1.1. Limitations of Functional Dependencies</h5></div></div></div><p>
+ Functional dependencies are currently only applied when considering
+ simple equality conditions that compare columns to constant values,
+ and <code class="literal">IN</code> clauses with constant values.
+ They are not used to improve estimates for equality conditions
+ comparing two columns or comparing a column to an expression, nor for
+ range clauses, <code class="literal">LIKE</code> or any other type of condition.
+ </p><p>
+ When estimating with functional dependencies, the planner assumes that
+ conditions on the involved columns are compatible and hence redundant.
+ If they are incompatible, the correct estimate would be zero rows, but
+ that possibility is not considered. For example, given a query like
+</p><pre class="programlisting">
+SELECT * FROM zipcodes WHERE city = 'San Francisco' AND zip = '94105';
+</pre><p>
+ the planner will disregard the <code class="structfield">city</code> clause as not
+ changing the selectivity, which is correct. However, it will make
+ the same assumption about
+</p><pre class="programlisting">
+SELECT * FROM zipcodes WHERE city = 'San Francisco' AND zip = '90210';
+</pre><p>
+ even though there will really be zero rows satisfying this query.
+ Functional dependency statistics do not provide enough information
+ to conclude that, however.
+ </p><p>
+ In many practical situations, this assumption is usually satisfied;
+ for example, there might be a GUI in the application that only allows
+ selecting compatible city and ZIP code values to use in a query.
+ But if that's not the case, functional dependencies may not be a viable
+ option.
+ </p></div></div><div class="sect3" id="id-1.5.13.5.4.12"><div class="titlepage"><div><div><h4 class="title">14.2.2.2. Multivariate N-Distinct Counts</h4></div></div></div><p>
+ Single-column statistics store the number of distinct values in each
+ column. Estimates of the number of distinct values when combining more
+ than one column (for example, for <code class="literal">GROUP BY a, b</code>) are
+ frequently wrong when the planner only has single-column statistical
+ data, causing it to select bad plans.
+ </p><p>
+ To improve such estimates, <code class="command">ANALYZE</code> can collect n-distinct
+ statistics for groups of columns. As before, it's impractical to do
+ this for every possible column grouping, so data is collected only for
+ those groups of columns appearing together in a statistics object
+ defined with the <code class="literal">ndistinct</code> option. Data will be collected
+ for each possible combination of two or more columns from the set of
+ listed columns.
+ </p><p>
+ Continuing the previous example, the n-distinct counts in a
+ table of ZIP codes might look like the following:
+</p><pre class="programlisting">
+CREATE STATISTICS stts2 (ndistinct) ON city, state, zip FROM zipcodes;
+
+ANALYZE zipcodes;
+
+SELECT stxkeys AS k, stxdndistinct AS nd
+ FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid)
+ WHERE stxname = 'stts2';
+-[ RECORD 1 ]------------------------------------------------------​--
+k | 1 2 5
+nd | {"1, 2": 33178, "1, 5": 33178, "2, 5": 27435, "1, 2, 5": 33178}
+(1 row)
+</pre><p>
+ This indicates that there are three combinations of columns that
+ have 33178 distinct values: ZIP code and state; ZIP code and city;
+ and ZIP code, city and state (the fact that they are all equal is
+ expected given that ZIP code alone is unique in this table). On the
+ other hand, the combination of city and state has only 27435 distinct
+ values.
+ </p><p>
+ It's advisable to create <code class="literal">ndistinct</code> statistics objects only
+ on combinations of columns that are actually used for grouping, and
+ for which misestimation of the number of groups is resulting in bad
+ plans. Otherwise, the <code class="command">ANALYZE</code> cycles are just wasted.
+ </p></div><div class="sect3" id="id-1.5.13.5.4.13"><div class="titlepage"><div><div><h4 class="title">14.2.2.3. Multivariate MCV Lists</h4></div></div></div><p>
+ Another type of statistic stored for each column are most-common value
+ lists. This allows very accurate estimates for individual columns, but
+ may result in significant misestimates for queries with conditions on
+ multiple columns.
+ </p><p>
+ To improve such estimates, <code class="command">ANALYZE</code> can collect MCV
+ lists on combinations of columns. Similarly to functional dependencies
+ and n-distinct coefficients, it's impractical to do this for every
+ possible column grouping. Even more so in this case, as the MCV list
+ (unlike functional dependencies and n-distinct coefficients) does store
+ the common column values. So data is collected only for those groups
+ of columns appearing together in a statistics object defined with the
+ <code class="literal">mcv</code> option.
+ </p><p>
+ Continuing the previous example, the MCV list for a table of ZIP codes
+ might look like the following (unlike for simpler types of statistics,
+ a function is required for inspection of MCV contents):
+
+</p><pre class="programlisting">
+CREATE STATISTICS stts3 (mcv) ON city, state FROM zipcodes;
+
+ANALYZE zipcodes;
+
+SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
+ pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts3';
+
+ index | values | nulls | frequency | base_frequency
+-------+------------------------+-------+-----------+----------------
+ 0 | {Washington, DC} | {f,f} | 0.003467 | 2.7e-05
+ 1 | {Apo, AE} | {f,f} | 0.003067 | 1.9e-05
+ 2 | {Houston, TX} | {f,f} | 0.002167 | 0.000133
+ 3 | {El Paso, TX} | {f,f} | 0.002 | 0.000113
+ 4 | {New York, NY} | {f,f} | 0.001967 | 0.000114
+ 5 | {Atlanta, GA} | {f,f} | 0.001633 | 3.3e-05
+ 6 | {Sacramento, CA} | {f,f} | 0.001433 | 7.8e-05
+ 7 | {Miami, FL} | {f,f} | 0.0014 | 6e-05
+ 8 | {Dallas, TX} | {f,f} | 0.001367 | 8.8e-05
+ 9 | {Chicago, IL} | {f,f} | 0.001333 | 5.1e-05
+ ...
+(99 rows)
+</pre><p>
+ This indicates that the most common combination of city and state is
+ Washington in DC, with actual frequency (in the sample) about 0.35%.
+ The base frequency of the combination (as computed from the simple
+ per-column frequencies) is only 0.0027%, resulting in two orders of
+ magnitude under-estimates.
+ </p><p>
+ It's advisable to create <acronym class="acronym">MCV</acronym> statistics objects only
+ on combinations of columns that are actually used in conditions together,
+ and for which misestimation of the number of groups is resulting in bad
+ plans. Otherwise, the <code class="command">ANALYZE</code> and planning cycles
+ are just wasted.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using-explain.html" title="14.1. Using EXPLAIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.1. Using <code class="command">EXPLAIN</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plhandler.html b/doc/src/sgml/html/plhandler.html
new file mode 100644
index 0000000..8eaec1a
--- /dev/null
+++ b/doc/src/sgml/html/plhandler.html
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 58. Writing a Procedural Language Handler</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="nls-programmer.html" title="57.2. For the Programmer" /><link rel="next" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 58. Writing a Procedural Language Handler</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-programmer.html" title="57.2. For the Programmer">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLHANDLER"><div class="titlepage"><div><div><h2 class="title">Chapter 58. Writing a Procedural Language Handler</h2></div></div></div><a id="id-1.10.9.2" class="indexterm"></a><p>
+ All calls to functions that are written in a language other than
+ the current <span class="quote">“<span class="quote">version 1</span>”</span> interface for compiled
+ languages (this includes functions in user-defined procedural languages
+ and functions written in SQL) go through a <em class="firstterm">call handler</em>
+ function for the specific language. It is the responsibility of
+ the call handler to execute the function in a meaningful way, such
+ as by interpreting the supplied source text. This chapter outlines
+ how a new procedural language's call handler can be written.
+ </p><p>
+ The call handler for a procedural language is a
+ <span class="quote">“<span class="quote">normal</span>”</span> function that must be written in a compiled
+ language such as C, using the version-1 interface, and registered
+ with <span class="productname">PostgreSQL</span> as taking no arguments
+ and returning the type <code class="type">language_handler</code>. This
+ special pseudo-type identifies the function as a call handler and
+ prevents it from being called directly in SQL commands.
+ For more details on C language calling conventions and dynamic loading,
+ see <a class="xref" href="xfunc-c.html" title="38.10. C-Language Functions">Section 38.10</a>.
+ </p><p>
+ The call handler is called in the same way as any other function:
+ It receives a pointer to a
+ <code class="structname">FunctionCallInfoBaseData</code> <code class="type">struct</code> containing
+ argument values and information about the called function, and it
+ is expected to return a <code class="type">Datum</code> result (and possibly
+ set the <code class="structfield">isnull</code> field of the
+ <code class="structname">FunctionCallInfoBaseData</code> structure, if it wishes
+ to return an SQL null result). The difference between a call
+ handler and an ordinary callee function is that the
+ <code class="structfield">flinfo-&gt;fn_oid</code> field of the
+ <code class="structname">FunctionCallInfoBaseData</code> structure will contain
+ the OID of the actual function to be called, not of the call
+ handler itself. The call handler must use this field to determine
+ which function to execute. Also, the passed argument list has
+ been set up according to the declaration of the target function,
+ not of the call handler.
+ </p><p>
+ It's up to the call handler to fetch the entry of the function from the
+ <code class="classname">pg_proc</code> system catalog and to analyze the argument
+ and return types of the called function. The <code class="literal">AS</code> clause from the
+ <code class="command">CREATE FUNCTION</code> command for the function will be found
+ in the <code class="literal">prosrc</code> column of the
+ <code class="classname">pg_proc</code> row. This is commonly source
+ text in the procedural language, but in theory it could be something else,
+ such as a path name to a file, or anything else that tells the call handler
+ what to do in detail.
+ </p><p>
+ Often, the same function is called many times per SQL statement.
+ A call handler can avoid repeated lookups of information about the
+ called function by using the
+ <code class="structfield">flinfo-&gt;fn_extra</code> field. This will
+ initially be <code class="symbol">NULL</code>, but can be set by the call handler to point at
+ information about the called function. On subsequent calls, if
+ <code class="structfield">flinfo-&gt;fn_extra</code> is already non-<code class="symbol">NULL</code>
+ then it can be used and the information lookup step skipped. The
+ call handler must make sure that
+ <code class="structfield">flinfo-&gt;fn_extra</code> is made to point at
+ memory that will live at least until the end of the current query,
+ since an <code class="structname">FmgrInfo</code> data structure could be
+ kept that long. One way to do this is to allocate the extra data
+ in the memory context specified by
+ <code class="structfield">flinfo-&gt;fn_mcxt</code>; such data will
+ normally have the same lifespan as the
+ <code class="structname">FmgrInfo</code> itself. But the handler could
+ also choose to use a longer-lived memory context so that it can cache
+ function definition information across queries.
+ </p><p>
+ When a procedural-language function is invoked as a trigger, no arguments
+ are passed in the usual way, but the
+ <code class="structname">FunctionCallInfoBaseData</code>'s
+ <code class="structfield">context</code> field points at a
+ <code class="structname">TriggerData</code> structure, rather than being <code class="symbol">NULL</code>
+ as it is in a plain function call. A language handler should
+ provide mechanisms for procedural-language functions to get at the trigger
+ information.
+ </p><p>
+ A template for a procedural-language handler written as a C extension is
+ provided in <code class="literal">src/test/modules/plsample</code>. This is a
+ working sample demonstrating one way to create a procedural-language
+ handler, process parameters, and return a value.
+ </p><p>
+ Although providing a call handler is sufficient to create a minimal
+ procedural language, there are two other functions that can optionally
+ be provided to make the language more convenient to use. These
+ are a <em class="firstterm">validator</em> and an
+ <em class="firstterm">inline handler</em>. A validator can be provided
+ to allow language-specific checking to be done during
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>.
+ An inline handler can be provided to allow the language to support
+ anonymous code blocks executed via the <a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> command.
+ </p><p>
+ If a validator is provided by a procedural language, it
+ must be declared as a function taking a single parameter of type
+ <code class="type">oid</code>. The validator's result is ignored, so it is customarily
+ declared to return <code class="type">void</code>. The validator will be called at
+ the end of a <code class="command">CREATE FUNCTION</code> command that has created
+ or updated a function written in the procedural language.
+ The passed-in OID is the OID of the function's <code class="classname">pg_proc</code>
+ row. The validator must fetch this row in the usual way, and do
+ whatever checking is appropriate.
+ First, call <code class="function">CheckFunctionValidatorAccess()</code> to diagnose
+ explicit calls to the validator that the user could not achieve through
+ <code class="command">CREATE FUNCTION</code>. Typical checks then include verifying
+ that the function's argument and result types are supported by the
+ language, and that the function's body is syntactically correct
+ in the language. If the validator finds the function to be okay,
+ it should just return. If it finds an error, it should report that
+ via the normal <code class="function">ereport()</code> error reporting mechanism.
+ Throwing an error will force a transaction rollback and thus prevent
+ the incorrect function definition from being committed.
+ </p><p>
+ Validator functions should typically honor the <a class="xref" href="runtime-config-client.html#GUC-CHECK-FUNCTION-BODIES">check_function_bodies</a> parameter: if it is turned off then
+ any expensive or context-sensitive checking should be skipped. If the
+ language provides for code execution at compilation time, the validator
+ must suppress checks that would induce such execution. In particular,
+ this parameter is turned off by <span class="application">pg_dump</span> so that it can
+ load procedural language functions without worrying about side effects or
+ dependencies of the function bodies on other database objects.
+ (Because of this requirement, the call handler should avoid
+ assuming that the validator has fully checked the function. The point
+ of having a validator is not to let the call handler omit checks, but
+ to notify the user immediately if there are obvious errors in a
+ <code class="command">CREATE FUNCTION</code> command.)
+ While the choice of exactly what to check is mostly left to the
+ discretion of the validator function, note that the core
+ <code class="command">CREATE FUNCTION</code> code only executes <code class="literal">SET</code> clauses
+ attached to a function when <code class="varname">check_function_bodies</code> is on.
+ Therefore, checks whose results might be affected by GUC parameters
+ definitely should be skipped when <code class="varname">check_function_bodies</code> is
+ off, to avoid false failures when restoring a dump.
+ </p><p>
+ If an inline handler is provided by a procedural language, it
+ must be declared as a function taking a single parameter of type
+ <code class="type">internal</code>. The inline handler's result is ignored, so it is
+ customarily declared to return <code class="type">void</code>. The inline handler
+ will be called when a <code class="command">DO</code> statement is executed specifying
+ the procedural language. The parameter actually passed is a pointer
+ to an <code class="structname">InlineCodeBlock</code> struct, which contains information
+ about the <code class="command">DO</code> statement's parameters, in particular the
+ text of the anonymous code block to be executed. The inline handler
+ should execute this code and return.
+ </p><p>
+ It's recommended that you wrap all these function declarations,
+ as well as the <code class="command">CREATE LANGUAGE</code> command itself, into
+ an <em class="firstterm">extension</em> so that a simple <code class="command">CREATE EXTENSION</code>
+ command is sufficient to install the language. See
+ <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a> for information about writing
+ extensions.
+ </p><p>
+ The procedural languages included in the standard distribution
+ are good references when trying to write your own language handler.
+ Look into the <code class="filename">src/pl</code> subdirectory of the source tree.
+ The <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>
+ reference page also has some useful details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls-programmer.html" title="57.2. For the Programmer">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Next</a></td></tr><tr><td width="40%" align="left" valign="top">57.2. For the Programmer </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 59. Writing a Foreign Data Wrapper</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-builtins.html b/doc/src/sgml/html/plperl-builtins.html
new file mode 100644
index 0000000..5d7e60e
--- /dev/null
+++ b/doc/src/sgml/html/plperl-builtins.html
@@ -0,0 +1,360 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.3. Built-in Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-data.html" title="45.2. Data Values in PL/Perl" /><link rel="next" href="plperl-global.html" title="45.4. Global Values in PL/Perl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.3. Built-in Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-data.html" title="45.2. Data Values in PL/Perl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-global.html" title="45.4. Global Values in PL/Perl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-BUILTINS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.3. Built-in Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plperl-builtins.html#PLPERL-DATABASE">45.3.1. Database Access from PL/Perl</a></span></dt><dt><span class="sect2"><a href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">45.3.2. Utility Functions in PL/Perl</a></span></dt></dl></div><div class="sect2" id="PLPERL-DATABASE"><div class="titlepage"><div><div><h3 class="title">45.3.1. Database Access from PL/Perl</h3></div></div></div><p>
+ Access to the database itself from your Perl function can be done
+ via the following functions:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal"><code class="function">spi_exec_query</code>(<em class="replaceable"><code>query</code></em> [, <em class="replaceable"><code>limit</code></em>])</code>
+ <a id="id-1.8.10.11.2.3.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="function">spi_exec_query</code> executes an SQL command and
+returns the entire row set as a reference to an array of hash references.
+If <em class="replaceable"><code>limit</code></em> is specified and is greater than zero,
+then <code class="function">spi_exec_query</code> retrieves at
+most <em class="replaceable"><code>limit</code></em> rows, much as if the query included
+a <code class="literal">LIMIT</code> clause. Omitting <em class="replaceable"><code>limit</code></em>
+or specifying it as zero results in no row limit.
+ </p><p>
+<span class="emphasis"><em>You should only use this command when you know
+that the result set will be relatively small.</em></span> Here is an
+example of a query (<code class="command">SELECT</code> command) with the
+optional maximum number of rows:
+
+</p><pre class="programlisting">
+$rv = spi_exec_query('SELECT * FROM my_table', 5);
+</pre><p>
+ This returns up to 5 rows from the table
+ <code class="literal">my_table</code>. If <code class="literal">my_table</code>
+ has a column <code class="literal">my_column</code>, you can get that
+ value from row <code class="literal">$i</code> of the result like this:
+</p><pre class="programlisting">
+$foo = $rv-&gt;{rows}[$i]-&gt;{my_column};
+</pre><p>
+ The total number of rows returned from a <code class="command">SELECT</code>
+ query can be accessed like this:
+</p><pre class="programlisting">
+$nrows = $rv-&gt;{processed}
+</pre><p>
+ </p><p>
+ Here is an example using a different command type:
+</p><pre class="programlisting">
+$query = "INSERT INTO my_table VALUES (1, 'test')";
+$rv = spi_exec_query($query);
+</pre><p>
+ You can then access the command status (e.g.,
+ <code class="literal">SPI_OK_INSERT</code>) like this:
+</p><pre class="programlisting">
+$res = $rv-&gt;{status};
+</pre><p>
+ To get the number of rows affected, do:
+</p><pre class="programlisting">
+$nrows = $rv-&gt;{processed};
+</pre><p>
+ </p><p>
+ Here is a complete example:
+</p><pre class="programlisting">
+CREATE TABLE test (
+ i int,
+ v varchar
+);
+
+INSERT INTO test (i, v) VALUES (1, 'first line');
+INSERT INTO test (i, v) VALUES (2, 'second line');
+INSERT INTO test (i, v) VALUES (3, 'third line');
+INSERT INTO test (i, v) VALUES (4, 'immortal');
+
+CREATE OR REPLACE FUNCTION test_munge() RETURNS SETOF test AS $$
+ my $rv = spi_exec_query('select i, v from test;');
+ my $status = $rv-&gt;{status};
+ my $nrows = $rv-&gt;{processed};
+ foreach my $rn (0 .. $nrows - 1) {
+ my $row = $rv-&gt;{rows}[$rn];
+ $row-&gt;{i} += 200 if defined($row-&gt;{i});
+ $row-&gt;{v} =~ tr/A-Za-z/a-zA-Z/ if (defined($row-&gt;{v}));
+ return_next($row);
+ }
+ return undef;
+$$ LANGUAGE plperl;
+
+SELECT * FROM test_munge();
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">spi_query(<em class="replaceable"><code>command</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.2.1.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_fetchrow(<em class="replaceable"><code>cursor</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.2.2.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_cursor_close(<em class="replaceable"><code>cursor</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.2.3.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="literal">spi_query</code> and <code class="literal">spi_fetchrow</code>
+ work together as a pair for row sets which might be large, or for cases
+ where you wish to return rows as they arrive.
+ <code class="literal">spi_fetchrow</code> works <span class="emphasis"><em>only</em></span> with
+ <code class="literal">spi_query</code>. The following example illustrates how
+ you use them together:
+
+</p><pre class="programlisting">
+CREATE TYPE foo_type AS (the_num INTEGER, the_text TEXT);
+
+CREATE OR REPLACE FUNCTION lotsa_md5 (INTEGER) RETURNS SETOF foo_type AS $$
+ use Digest::MD5 qw(md5_hex);
+ my $file = '/usr/share/dict/words';
+ my $t = localtime;
+ elog(NOTICE, "opening file $file at $t" );
+ open my $fh, '&lt;', $file # ooh, it's a file access!
+ or elog(ERROR, "cannot open $file for reading: $!");
+ my @words = &lt;$fh&gt;;
+ close $fh;
+ $t = localtime;
+ elog(NOTICE, "closed file $file at $t");
+ chomp(@words);
+ my $row;
+ my $sth = spi_query("SELECT * FROM generate_series(1,$_[0]) AS b(a)");
+ while (defined ($row = spi_fetchrow($sth))) {
+ return_next({
+ the_num =&gt; $row-&gt;{a},
+ the_text =&gt; md5_hex($words[rand @words])
+ });
+ }
+ return;
+$$ LANGUAGE plperlu;
+
+SELECT * from lotsa_md5(500);
+</pre><p>
+ </p><p>
+ Normally, <code class="function">spi_fetchrow</code> should be repeated until it
+ returns <code class="literal">undef</code>, indicating that there are no more
+ rows to read. The cursor returned by <code class="literal">spi_query</code>
+ is automatically freed when
+ <code class="function">spi_fetchrow</code> returns <code class="literal">undef</code>.
+ If you do not wish to read all the rows, instead call
+ <code class="function">spi_cursor_close</code> to free the cursor.
+ Failure to do so will result in memory leaks.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">spi_prepare(<em class="replaceable"><code>command</code></em>, <em class="replaceable"><code>argument types</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.3.1.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_query_prepared(<em class="replaceable"><code>plan</code></em>, <em class="replaceable"><code>arguments</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.3.2.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_exec_prepared(<em class="replaceable"><code>plan</code></em> [, <em class="replaceable"><code>attributes</code></em>], <em class="replaceable"><code>arguments</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.3.3.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_freeplan(<em class="replaceable"><code>plan</code></em>)</code></code>
+ <a id="id-1.8.10.11.2.3.3.4.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="literal">spi_prepare</code>, <code class="literal">spi_query_prepared</code>, <code class="literal">spi_exec_prepared</code>,
+ and <code class="literal">spi_freeplan</code> implement the same functionality but for prepared queries.
+ <code class="literal">spi_prepare</code> accepts a query string with numbered argument placeholders ($1, $2, etc.)
+ and a string list of argument types:
+</p><pre class="programlisting">
+$plan = spi_prepare('SELECT * FROM test WHERE id &gt; $1 AND name = $2',
+ 'INTEGER', 'TEXT');
+</pre><p>
+ Once a query plan is prepared by a call to <code class="literal">spi_prepare</code>, the plan can be used instead
+ of the string query, either in <code class="literal">spi_exec_prepared</code>, where the result is the same as returned
+ by <code class="literal">spi_exec_query</code>, or in <code class="literal">spi_query_prepared</code> which returns a cursor
+ exactly as <code class="literal">spi_query</code> does, which can be later passed to <code class="literal">spi_fetchrow</code>.
+ The optional second parameter to <code class="literal">spi_exec_prepared</code> is a hash reference of attributes;
+ the only attribute currently supported is <code class="literal">limit</code>, which
+ sets the maximum number of rows returned from the query.
+ Omitting <code class="literal">limit</code> or specifying it as zero results in no
+ row limit.
+ </p><p>
+ The advantage of prepared queries is that is it possible to use one prepared plan for more
+ than one query execution. After the plan is not needed anymore, it can be freed with
+ <code class="literal">spi_freeplan</code>:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION init() RETURNS VOID AS $$
+ $_SHARED{my_plan} = spi_prepare('SELECT (now() + $1)::date AS now',
+ 'INTERVAL');
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION add_time( INTERVAL ) RETURNS TEXT AS $$
+ return spi_exec_prepared(
+ $_SHARED{my_plan},
+ $_[0]
+ )-&gt;{rows}-&gt;[0]-&gt;{now};
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION done() RETURNS VOID AS $$
+ spi_freeplan( $_SHARED{my_plan});
+ undef $_SHARED{my_plan};
+$$ LANGUAGE plperl;
+
+SELECT init();
+SELECT add_time('1 day'), add_time('2 days'), add_time('3 days');
+SELECT done();
+
+ add_time | add_time | add_time
+------------+------------+------------
+ 2005-12-10 | 2005-12-11 | 2005-12-12
+</pre><p>
+ Note that the parameter subscript in <code class="literal">spi_prepare</code> is defined via
+ $1, $2, $3, etc., so avoid declaring query strings in double quotes that might easily
+ lead to hard-to-catch bugs.
+ </p><p>
+ Another example illustrates usage of an optional parameter in <code class="literal">spi_exec_prepared</code>:
+</p><pre class="programlisting">
+CREATE TABLE hosts AS SELECT id, ('192.168.1.'||id)::inet AS address
+ FROM generate_series(1,3) AS id;
+
+CREATE OR REPLACE FUNCTION init_hosts_query() RETURNS VOID AS $$
+ $_SHARED{plan} = spi_prepare('SELECT * FROM hosts
+ WHERE address &lt;&lt; $1', 'inet');
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION query_hosts(inet) RETURNS SETOF hosts AS $$
+ return spi_exec_prepared(
+ $_SHARED{plan},
+ {limit =&gt; 2},
+ $_[0]
+ )-&gt;{rows};
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION release_hosts_query() RETURNS VOID AS $$
+ spi_freeplan($_SHARED{plan});
+ undef $_SHARED{plan};
+$$ LANGUAGE plperl;
+
+SELECT init_hosts_query();
+SELECT query_hosts('192.168.1.0/30');
+SELECT release_hosts_query();
+
+ query_hosts
+-----------------
+ (1,192.168.1.1)
+ (2,192.168.1.2)
+(2 rows)
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">spi_commit()</code></code>
+ <a id="id-1.8.10.11.2.3.4.1.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">spi_rollback()</code></code>
+ <a id="id-1.8.10.11.2.3.4.2.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Commit or roll back the current transaction. This can only be called
+ in a procedure or anonymous code block (<code class="command">DO</code> command)
+ called from the top level. (Note that it is not possible to run the
+ SQL commands <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code>
+ via <code class="function">spi_exec_query</code> or similar. It has to be done
+ using these functions.) After a transaction is ended, a new
+ transaction is automatically started, so there is no separate function
+ for that.
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+CREATE PROCEDURE transaction_test1()
+LANGUAGE plperl
+AS $$
+foreach my $i (0..9) {
+ spi_exec_query("INSERT INTO test1 (a) VALUES ($i)");
+ if ($i % 2 == 0) {
+ spi_commit();
+ } else {
+ spi_rollback();
+ }
+}
+$$;
+
+CALL transaction_test1();
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="PLPERL-UTILITY-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">45.3.2. Utility Functions in PL/Perl</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal"><code class="function">elog(<em class="replaceable"><code>level</code></em>, <em class="replaceable"><code>msg</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Emit a log or error message. Possible levels are
+ <code class="literal">DEBUG</code>, <code class="literal">LOG</code>, <code class="literal">INFO</code>,
+ <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>, and <code class="literal">ERROR</code>.
+ <code class="literal">ERROR</code>
+ raises an error condition; if this is not trapped by the surrounding
+ Perl code, the error propagates out to the calling query, causing
+ the current transaction or subtransaction to be aborted. This
+ is effectively the same as the Perl <code class="literal">die</code> command.
+ The other levels only generate messages of different
+ priority levels.
+ Whether messages of a particular priority are reported to the client,
+ written to the server log, or both is controlled by the
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
+ variables. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for more
+ information.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">quote_literal(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Return the given string suitably quoted to be used as a string literal in an SQL
+ statement string. Embedded single-quotes and backslashes are properly doubled.
+ Note that <code class="function">quote_literal</code> returns undef on undef input; if the argument
+ might be undef, <code class="function">quote_nullable</code> is often more suitable.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">quote_nullable(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Return the given string suitably quoted to be used as a string literal in an SQL
+ statement string; or, if the argument is undef, return the unquoted string "NULL".
+ Embedded single-quotes and backslashes are properly doubled.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">quote_ident(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Return the given string suitably quoted to be used as an identifier in
+ an SQL statement string. 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.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">decode_bytea(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Return the unescaped binary data represented by the contents of the given string,
+ which should be <code class="type">bytea</code> encoded.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">encode_bytea(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.6.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Return the <code class="type">bytea</code> encoded form of the binary data contents of the given string.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">encode_array_literal(<em class="replaceable"><code>array</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.7.1.2" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="literal"><code class="function">encode_array_literal(<em class="replaceable"><code>array</code></em>, <em class="replaceable"><code>delimiter</code></em>)</code></code>
+ </span></dt><dd><p>
+ Returns the contents of the referenced array as a string in array literal format
+ (see <a class="xref" href="arrays.html#ARRAYS-INPUT" title="8.15.2. Array Value Input">Section 8.15.2</a>).
+ Returns the argument value unaltered if it's not a reference to an array.
+ The delimiter used between elements of the array literal defaults to "<code class="literal">, </code>"
+ if a delimiter is not specified or is undef.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">encode_typed_literal(<em class="replaceable"><code>value</code></em>, <em class="replaceable"><code>typename</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.8.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Converts a Perl variable to the value of the data type passed as a
+ second argument and returns a string representation of this value.
+ Correctly handles nested arrays and values of composite types.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">encode_array_constructor(<em class="replaceable"><code>array</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.9.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the contents of the referenced array as a string in array constructor format
+ (see <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS" title="4.2.12. Array Constructors">Section 4.2.12</a>).
+ Individual values are quoted using <code class="function">quote_nullable</code>.
+ Returns the argument value, quoted using <code class="function">quote_nullable</code>,
+ if it's not a reference to an array.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">looks_like_number(<em class="replaceable"><code>string</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.10.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns a true value if the content of the given string looks like a
+ number, according to Perl, returns false otherwise.
+ Returns undef if the argument is undef. Leading and trailing space is
+ ignored. <code class="literal">Inf</code> and <code class="literal">Infinity</code> are regarded as numbers.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="function">is_array_ref(<em class="replaceable"><code>argument</code></em>)</code></code>
+ <a id="id-1.8.10.11.3.2.11.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns a true value if the given argument may be treated as an
+ array reference, that is, if ref of the argument is <code class="literal">ARRAY</code> or
+ <code class="literal">PostgreSQL::InServer::ARRAY</code>. Returns false otherwise.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-data.html" title="45.2. Data Values in PL/Perl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-global.html" title="45.4. Global Values in PL/Perl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.2. Data Values in PL/Perl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.4. Global Values in PL/Perl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-data.html b/doc/src/sgml/html/plperl-data.html
new file mode 100644
index 0000000..821eda1
--- /dev/null
+++ b/doc/src/sgml/html/plperl-data.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.2. Data Values in PL/Perl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments" /><link rel="next" href="plperl-builtins.html" title="45.3. Built-in Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.2. Data Values in PL/Perl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-builtins.html" title="45.3. Built-in Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.2. Data Values in PL/Perl</h2></div></div></div><p>
+ The argument values supplied to a PL/Perl function's code are
+ simply the input arguments converted to text form (just as if they
+ had been displayed by a <code class="command">SELECT</code> statement).
+ Conversely, the <code class="function">return</code> and <code class="function">return_next</code>
+ commands will accept any string that is acceptable input format
+ for the function's declared return type.
+ </p><p>
+ If this behavior is inconvenient for a particular case, it can be
+ improved by using a transform, as already illustrated
+ for <code class="type">bool</code> values. Several examples of transform modules
+ are included in the <span class="productname">PostgreSQL</span> distribution.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-builtins.html" title="45.3. Built-in Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.1. PL/Perl Functions and Arguments </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.3. Built-in Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-event-triggers.html b/doc/src/sgml/html/plperl-event-triggers.html
new file mode 100644
index 0000000..c9abe40
--- /dev/null
+++ b/doc/src/sgml/html/plperl-event-triggers.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.7. PL/Perl Event Triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-triggers.html" title="45.6. PL/Perl Triggers" /><link rel="next" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.7. PL/Perl Event Triggers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-triggers.html" title="45.6. PL/Perl Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-EVENT-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.7. PL/Perl Event Triggers</h2></div></div></div><p>
+ PL/Perl can be used to write event trigger functions. In an event trigger
+ function, the hash reference <code class="varname">$_TD</code> contains information
+ about the current trigger event. <code class="varname">$_TD</code> is a global variable,
+ which gets a separate local value for each invocation of the trigger. The
+ fields of the <code class="varname">$_TD</code> hash reference are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">$_TD-&gt;{event}</code></span></dt><dd><p>
+ The name of the event the trigger is fired for.
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{tag}</code></span></dt><dd><p>
+ The command tag for which the trigger is fired.
+ </p></dd></dl></div><p>
+ </p><p>
+ The return value of the trigger function is ignored.
+ </p><p>
+ Here is an example of an event trigger function, illustrating some of the
+ above:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION perlsnitch() RETURNS event_trigger AS $$
+ elog(NOTICE, "perlsnitch: " . $_TD-&gt;{event} . " " . $_TD-&gt;{tag} . " ");
+$$ LANGUAGE plperl;
+
+CREATE EVENT TRIGGER perl_a_snitch
+ ON ddl_command_start
+ EXECUTE FUNCTION perlsnitch();
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-triggers.html" title="45.6. PL/Perl Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.6. PL/Perl Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.8. PL/Perl Under the Hood</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-funcs.html b/doc/src/sgml/html/plperl-funcs.html
new file mode 100644
index 0000000..ce13b69
--- /dev/null
+++ b/doc/src/sgml/html/plperl-funcs.html
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.1. PL/Perl Functions and Arguments</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language" /><link rel="next" href="plperl-data.html" title="45.2. Data Values in PL/Perl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.1. PL/Perl Functions and Arguments</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-data.html" title="45.2. Data Values in PL/Perl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.1. PL/Perl Functions and Arguments</h2></div></div></div><p>
+ To create a function in the PL/Perl language, use the standard
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>
+ syntax:
+
+</p><pre class="programlisting">
+CREATE FUNCTION <em class="replaceable"><code>funcname</code></em> (<em class="replaceable"><code>argument-types</code></em>)
+RETURNS <em class="replaceable"><code>return-type</code></em>
+-- function attributes can go here
+AS $$
+ # PL/Perl function body goes here
+$$ LANGUAGE plperl;
+</pre><p>
+
+ The body of the function is ordinary Perl code. In fact, the PL/Perl
+ glue code wraps it inside a Perl subroutine. A PL/Perl function is
+ called in a scalar context, so it can't return a list. You can return
+ non-scalar values (arrays, records, and sets) by returning a reference,
+ as discussed below.
+ </p><p>
+ In a PL/Perl procedure, any return value from the Perl code is ignored.
+ </p><p>
+ PL/Perl also supports anonymous code blocks called with the
+ <a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> statement:
+
+</p><pre class="programlisting">
+DO $$
+ # PL/Perl code
+$$ LANGUAGE plperl;
+</pre><p>
+
+ An anonymous code block receives no arguments, and whatever value it
+ might return is discarded. Otherwise it behaves just like a function.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The use of named nested subroutines is dangerous in Perl, especially if
+ they refer to lexical variables in the enclosing scope. Because a PL/Perl
+ function is wrapped in a subroutine, any named subroutine you place inside
+ one will be nested. In general, it is far safer to create anonymous
+ subroutines which you call via a coderef. For more information, see the
+ entries for <code class="literal">Variable "%s" will not stay shared</code> and
+ <code class="literal">Variable "%s" is not available</code> in the
+ <span class="citerefentry"><span class="refentrytitle">perldiag</span></span> man page, or
+ search the Internet for <span class="quote">“<span class="quote">perl nested named subroutine</span>”</span>.
+ </p></div><p>
+ The syntax of the <code class="command">CREATE FUNCTION</code> command requires
+ the function body to be written as a string constant. It is usually
+ most convenient to use dollar quoting (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) for the string constant.
+ If you choose to use escape string syntax <code class="literal">E''</code>,
+ you must double any single quote marks (<code class="literal">'</code>) and backslashes
+ (<code class="literal">\</code>) used in the body of the function
+ (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>).
+ </p><p>
+ Arguments and results are handled as in any other Perl subroutine:
+ arguments are passed in <code class="varname">@_</code>, and a result value
+ is returned with <code class="literal">return</code> or as the last expression
+ evaluated in the function.
+ </p><p>
+ For example, a function returning the greater of two integer values
+ could be defined as:
+
+</p><pre class="programlisting">
+CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
+ if ($_[0] &gt; $_[1]) { return $_[0]; }
+ return $_[1];
+$$ LANGUAGE plperl;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Arguments will be converted from the database's encoding to UTF-8
+ for use inside PL/Perl, and then converted from UTF-8 back to the
+ database encoding upon return.
+ </p></div><p>
+ If an SQL null value<a id="id-1.8.10.9.10.1" class="indexterm"></a> is passed to a function,
+ the argument value will appear as <span class="quote">“<span class="quote">undefined</span>”</span> in Perl. The
+ above function definition will not behave very nicely with null
+ inputs (in fact, it will act as though they are zeroes). We could
+ add <code class="literal">STRICT</code> to the function definition to make
+ <span class="productname">PostgreSQL</span> do something more reasonable:
+ if a null value is passed, the function will not be called at all,
+ but will just return a null result automatically. Alternatively,
+ we could check for undefined inputs in the function body. For
+ example, suppose that we wanted <code class="function">perl_max</code> with
+ one null and one nonnull argument to return the nonnull argument,
+ rather than a null value:
+
+</p><pre class="programlisting">
+CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
+ my ($x, $y) = @_;
+ if (not defined $x) {
+ return undef if not defined $y;
+ return $y;
+ }
+ return $x if not defined $y;
+ return $x if $x &gt; $y;
+ return $y;
+$$ LANGUAGE plperl;
+</pre><p>
+ As shown above, to return an SQL null value from a PL/Perl
+ function, return an undefined value. This can be done whether the
+ function is strict or not.
+ </p><p>
+ Anything in a function argument that is not a reference is
+ a string, which is in the standard <span class="productname">PostgreSQL</span>
+ external text representation for the relevant data type. In the case of
+ ordinary numeric or text types, Perl will just do the right thing and
+ the programmer will normally not have to worry about it. However, in
+ other cases the argument will need to be converted into a form that is
+ more usable in Perl. For example, the <code class="function">decode_bytea</code>
+ function can be used to convert an argument of
+ type <code class="type">bytea</code> into unescaped binary.
+ </p><p>
+ Similarly, values passed back to <span class="productname">PostgreSQL</span>
+ must be in the external text representation format. For example, the
+ <code class="function">encode_bytea</code> function can be used to
+ escape binary data for a return value of type <code class="type">bytea</code>.
+ </p><p>
+ One case that is particularly important is boolean values. As just
+ stated, the default behavior for <code class="type">bool</code> values is that they
+ are passed to Perl as text, thus either <code class="literal">'t'</code>
+ or <code class="literal">'f'</code>. This is problematic, since Perl will not
+ treat <code class="literal">'f'</code> as false! It is possible to improve matters
+ by using a <span class="quote">“<span class="quote">transform</span>”</span> (see
+ <a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a>). Suitable transforms are provided
+ by the <code class="filename">bool_plperl</code> extension. To use it, install
+ the extension:
+</p><pre class="programlisting">
+CREATE EXTENSION bool_plperl; -- or bool_plperlu for PL/PerlU
+</pre><p>
+ Then use the <code class="literal">TRANSFORM</code> function attribute for a
+ PL/Perl function that takes or returns <code class="type">bool</code>, for example:
+</p><pre class="programlisting">
+CREATE FUNCTION perl_and(bool, bool) RETURNS bool
+TRANSFORM FOR TYPE bool
+AS $$
+ my ($a, $b) = @_;
+ return $a &amp;&amp; $b;
+$$ LANGUAGE plperl;
+</pre><p>
+ When this transform is applied, <code class="type">bool</code> arguments will be seen
+ by Perl as being <code class="literal">1</code> or empty, thus properly true or
+ false. If the function result is type <code class="type">bool</code>, it will be true
+ or false according to whether Perl would evaluate the returned value as
+ true.
+ Similar transformations are also performed for boolean query arguments
+ and results of SPI queries performed inside the function
+ (<a class="xref" href="plperl-builtins.html#PLPERL-DATABASE" title="45.3.1. Database Access from PL/Perl">Section 45.3.1</a>).
+ </p><p>
+ Perl can return <span class="productname">PostgreSQL</span> arrays as
+ references to Perl arrays. Here is an example:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE function returns_array()
+RETURNS text[][] AS $$
+ return [['a"b','c,d'],['e\\f','g']];
+$$ LANGUAGE plperl;
+
+select returns_array();
+</pre><p>
+ </p><p>
+ Perl passes <span class="productname">PostgreSQL</span> arrays as a blessed
+ <code class="type">PostgreSQL::InServer::ARRAY</code> object. This object may be treated as an array
+ reference or a string, allowing for backward compatibility with Perl
+ code written for <span class="productname">PostgreSQL</span> versions below 9.1 to
+ run. For example:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION concat_array_elements(text[]) RETURNS TEXT AS $$
+ my $arg = shift;
+ my $result = "";
+ return undef if (!defined $arg);
+
+ # as an array reference
+ for (@$arg) {
+ $result .= $_;
+ }
+
+ # also works as a string
+ $result .= $arg;
+
+ return $result;
+$$ LANGUAGE plperl;
+
+SELECT concat_array_elements(ARRAY['PL','/','Perl']);
+</pre><p>
+
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Multidimensional arrays are represented as references to
+ lower-dimensional arrays of references in a way common to every Perl
+ programmer.
+ </p></div><p>
+ </p><p>
+ Composite-type arguments are passed to the function as references
+ to hashes. The keys of the hash are the attribute names of the
+ composite type. Here is an example:
+
+</p><pre class="programlisting">
+CREATE TABLE employee (
+ name text,
+ basesalary integer,
+ bonus integer
+);
+
+CREATE FUNCTION empcomp(employee) RETURNS integer AS $$
+ my ($emp) = @_;
+ return $emp-&gt;{basesalary} + $emp-&gt;{bonus};
+$$ LANGUAGE plperl;
+
+SELECT name, empcomp(employee.*) FROM employee;
+</pre><p>
+ </p><p>
+ A PL/Perl function can return a composite-type result using the same
+ approach: return a reference to a hash that has the required attributes.
+ For example:
+
+</p><pre class="programlisting">
+CREATE TYPE testrowperl AS (f1 integer, f2 text, f3 text);
+
+CREATE OR REPLACE FUNCTION perl_row() RETURNS testrowperl AS $$
+ return {f2 =&gt; 'hello', f1 =&gt; 1, f3 =&gt; 'world'};
+$$ LANGUAGE plperl;
+
+SELECT * FROM perl_row();
+</pre><p>
+
+ Any columns in the declared result data type that are not present in the
+ hash will be returned as null values.
+ </p><p>
+ Similarly, output arguments of procedures can be returned as a hash
+ reference:
+
+</p><pre class="programlisting">
+CREATE PROCEDURE perl_triple(INOUT a integer, INOUT b integer) AS $$
+ my ($a, $b) = @_;
+ return {a =&gt; $a * 3, b =&gt; $b * 3};
+$$ LANGUAGE plperl;
+
+CALL perl_triple(5, 10);
+</pre><p>
+ </p><p>
+ PL/Perl functions can also return sets of either scalar or
+ composite types. Usually you'll want to return rows one at a
+ time, both to speed up startup time and to keep from queuing up
+ the entire result set in memory. You can do this with
+ <code class="function">return_next</code> as illustrated below. Note that
+ after the last <code class="function">return_next</code>, you must put
+ either <code class="literal">return</code> or (better) <code class="literal">return
+ undef</code>.
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION perl_set_int(int)
+RETURNS SETOF INTEGER AS $$
+ foreach (0..$_[0]) {
+ return_next($_);
+ }
+ return undef;
+$$ LANGUAGE plperl;
+
+SELECT * FROM perl_set_int(5);
+
+CREATE OR REPLACE FUNCTION perl_set()
+RETURNS SETOF testrowperl AS $$
+ return_next({ f1 =&gt; 1, f2 =&gt; 'Hello', f3 =&gt; 'World' });
+ return_next({ f1 =&gt; 2, f2 =&gt; 'Hello', f3 =&gt; 'PostgreSQL' });
+ return_next({ f1 =&gt; 3, f2 =&gt; 'Hello', f3 =&gt; 'PL/Perl' });
+ return undef;
+$$ LANGUAGE plperl;
+</pre><p>
+
+ For small result sets, you can return a reference to an array that
+ contains either scalars, references to arrays, or references to
+ hashes for simple types, array types, and composite types,
+ respectively. Here are some simple examples of returning the entire
+ result set as an array reference:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$
+ return [0..$_[0]];
+$$ LANGUAGE plperl;
+
+SELECT * FROM perl_set_int(5);
+
+CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testrowperl AS $$
+ return [
+ { f1 =&gt; 1, f2 =&gt; 'Hello', f3 =&gt; 'World' },
+ { f1 =&gt; 2, f2 =&gt; 'Hello', f3 =&gt; 'PostgreSQL' },
+ { f1 =&gt; 3, f2 =&gt; 'Hello', f3 =&gt; 'PL/Perl' }
+ ];
+$$ LANGUAGE plperl;
+
+SELECT * FROM perl_set();
+</pre><p>
+ </p><p>
+ If you wish to use the <code class="literal">strict</code> pragma with your code you
+ have a few options. For temporary global use you can <code class="command">SET</code>
+ <code class="literal">plperl.use_strict</code> to true.
+ This will affect subsequent compilations of <span class="application">PL/Perl</span>
+ functions, but not functions already compiled in the current session.
+ For permanent global use you can set <code class="literal">plperl.use_strict</code>
+ to true in the <code class="filename">postgresql.conf</code> file.
+ </p><p>
+ For permanent use in specific functions you can simply put:
+</p><pre class="programlisting">
+use strict;
+</pre><p>
+ at the top of the function body.
+ </p><p>
+ The <code class="literal">feature</code> pragma is also available to <code class="function">use</code> if your Perl is version 5.10.0 or higher.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-data.html" title="45.2. Data Values in PL/Perl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 45. PL/Perl — Perl Procedural Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.2. Data Values in PL/Perl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-global.html b/doc/src/sgml/html/plperl-global.html
new file mode 100644
index 0000000..da913c2
--- /dev/null
+++ b/doc/src/sgml/html/plperl-global.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.4. Global Values in PL/Perl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-builtins.html" title="45.3. Built-in Functions" /><link rel="next" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.4. Global Values in PL/Perl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-builtins.html" title="45.3. Built-in Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-GLOBAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.4. Global Values in PL/Perl</h2></div></div></div><p>
+ You can use the global hash <code class="varname">%_SHARED</code> to store
+ data, including code references, between function calls for the
+ lifetime of the current session.
+ </p><p>
+ Here is a simple example for shared data:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION set_var(name text, val text) RETURNS text AS $$
+ if ($_SHARED{$_[0]} = $_[1]) {
+ return 'ok';
+ } else {
+ return "cannot set shared variable $_[0] to $_[1]";
+ }
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION get_var(name text) RETURNS text AS $$
+ return $_SHARED{$_[0]};
+$$ LANGUAGE plperl;
+
+SELECT set_var('sample', 'Hello, PL/Perl! How''s tricks?');
+SELECT get_var('sample');
+</pre><p>
+ </p><p>
+ Here is a slightly more complicated example using a code reference:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION myfuncs() RETURNS void AS $$
+ $_SHARED{myquote} = sub {
+ my $arg = shift;
+ $arg =~ s/(['\\])/\\$1/g;
+ return "'$arg'";
+ };
+$$ LANGUAGE plperl;
+
+SELECT myfuncs(); /* initializes the function */
+
+/* Set up a function that uses the quote function */
+
+CREATE OR REPLACE FUNCTION use_quote(TEXT) RETURNS text AS $$
+ my $text_to_quote = shift;
+ my $qfunc = $_SHARED{myquote};
+ return &amp;$qfunc($text_to_quote);
+$$ LANGUAGE plperl;
+</pre><p>
+
+ (You could have replaced the above with the one-liner
+ <code class="literal">return $_SHARED{myquote}-&gt;($_[0]);</code>
+ at the expense of readability.)
+ </p><p>
+ For security reasons, PL/Perl executes functions called by any one SQL role
+ in a separate Perl interpreter for that role. This prevents accidental or
+ malicious interference by one user with the behavior of another user's
+ PL/Perl functions. Each such interpreter has its own value of the
+ <code class="varname">%_SHARED</code> variable and other global state. Thus, two
+ PL/Perl functions will share the same value of <code class="varname">%_SHARED</code>
+ if and only if they are executed by the same SQL role. In an application
+ wherein a single session executes code under multiple SQL roles (via
+ <code class="literal">SECURITY DEFINER</code> functions, use of <code class="command">SET ROLE</code>, etc.)
+ you may need to take explicit steps to ensure that PL/Perl functions can
+ share data via <code class="varname">%_SHARED</code>. To do that, make sure that
+ functions that should communicate are owned by the same user, and mark
+ them <code class="literal">SECURITY DEFINER</code>. You must of course take care that
+ such functions can't be used to do anything unintended.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-builtins.html" title="45.3. Built-in Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.3. Built-in Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.5. Trusted and Untrusted PL/Perl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-triggers.html b/doc/src/sgml/html/plperl-triggers.html
new file mode 100644
index 0000000..3043a8f
--- /dev/null
+++ b/doc/src/sgml/html/plperl-triggers.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.6. PL/Perl Triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl" /><link rel="next" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.6. PL/Perl Triggers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.6. PL/Perl Triggers</h2></div></div></div><p>
+ PL/Perl can be used to write trigger functions. In a trigger function,
+ the hash reference <code class="varname">$_TD</code> contains information about the
+ current trigger event. <code class="varname">$_TD</code> is a global variable,
+ which gets a separate local value for each invocation of the trigger.
+ The fields of the <code class="varname">$_TD</code> hash reference are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">$_TD-&gt;{new}{foo}</code></span></dt><dd><p>
+ <code class="literal">NEW</code> value of column <code class="literal">foo</code>
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{old}{foo}</code></span></dt><dd><p>
+ <code class="literal">OLD</code> value of column <code class="literal">foo</code>
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{name}</code></span></dt><dd><p>
+ Name of the trigger being called
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{event}</code></span></dt><dd><p>
+ Trigger event: <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, <code class="literal">TRUNCATE</code>, or <code class="literal">UNKNOWN</code>
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{when}</code></span></dt><dd><p>
+ When the trigger was called: <code class="literal">BEFORE</code>,
+ <code class="literal">AFTER</code>, <code class="literal">INSTEAD OF</code>, or
+ <code class="literal">UNKNOWN</code>
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{level}</code></span></dt><dd><p>
+ The trigger level: <code class="literal">ROW</code>, <code class="literal">STATEMENT</code>, or <code class="literal">UNKNOWN</code>
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{relid}</code></span></dt><dd><p>
+ OID of the table on which the trigger fired
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{table_name}</code></span></dt><dd><p>
+ Name of the table on which the trigger fired
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{relname}</code></span></dt><dd><p>
+ Name of the table on which the trigger fired. This has been deprecated,
+ and could be removed in a future release.
+ Please use $_TD-&gt;{table_name} instead.
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{table_schema}</code></span></dt><dd><p>
+ Name of the schema in which the table on which the trigger fired, is
+ </p></dd><dt><span class="term"><code class="literal">$_TD-&gt;{argc}</code></span></dt><dd><p>
+ Number of arguments of the trigger function
+ </p></dd><dt><span class="term"><code class="literal">@{$_TD-&gt;{args}}</code></span></dt><dd><p>
+ Arguments of the trigger function. Does not exist if <code class="literal">$_TD-&gt;{argc}</code> is 0.
+ </p></dd></dl></div><p>
+ </p><p>
+ Row-level triggers can return one of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">return;</code></span></dt><dd><p>
+ Execute the operation
+ </p></dd><dt><span class="term"><code class="literal">"SKIP"</code></span></dt><dd><p>
+ Don't execute the operation
+ </p></dd><dt><span class="term"><code class="literal">"MODIFY"</code></span></dt><dd><p>
+ Indicates that the <code class="literal">NEW</code> row was modified by
+ the trigger function
+ </p></dd></dl></div><p>
+ </p><p>
+ Here is an example of a trigger function, illustrating some of the
+ above:
+</p><pre class="programlisting">
+CREATE TABLE test (
+ i int,
+ v varchar
+);
+
+CREATE OR REPLACE FUNCTION valid_id() RETURNS trigger AS $$
+ if (($_TD-&gt;{new}{i} &gt;= 100) || ($_TD-&gt;{new}{i} &lt;= 0)) {
+ return "SKIP"; # skip INSERT/UPDATE command
+ } elsif ($_TD-&gt;{new}{v} ne "immortal") {
+ $_TD-&gt;{new}{v} .= "(modified by trigger)";
+ return "MODIFY"; # modify row and execute INSERT/UPDATE command
+ } else {
+ return; # execute INSERT/UPDATE command
+ }
+$$ LANGUAGE plperl;
+
+CREATE TRIGGER test_valid_id_trig
+ BEFORE INSERT OR UPDATE ON test
+ FOR EACH ROW EXECUTE FUNCTION valid_id();
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-trusted.html" title="45.5. Trusted and Untrusted PL/Perl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.5. Trusted and Untrusted PL/Perl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.7. PL/Perl Event Triggers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-trusted.html b/doc/src/sgml/html/plperl-trusted.html
new file mode 100644
index 0000000..1f90526
--- /dev/null
+++ b/doc/src/sgml/html/plperl-trusted.html
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.5. Trusted and Untrusted PL/Perl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-global.html" title="45.4. Global Values in PL/Perl" /><link rel="next" href="plperl-triggers.html" title="45.6. PL/Perl Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.5. Trusted and Untrusted PL/Perl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-global.html" title="45.4. Global Values in PL/Perl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-triggers.html" title="45.6. PL/Perl Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-TRUSTED"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.5. Trusted and Untrusted PL/Perl</h2></div></div></div><a id="id-1.8.10.13.2" class="indexterm"></a><p>
+ Normally, PL/Perl is installed as a <span class="quote">“<span class="quote">trusted</span>”</span> programming
+ language named <code class="literal">plperl</code>. In this setup, certain Perl
+ operations are disabled to preserve security. In general, the
+ operations that are restricted are those that interact with the
+ environment. This includes file handle operations,
+ <code class="literal">require</code>, and <code class="literal">use</code> (for
+ external modules). There is no way to access internals of the
+ database server process or to gain OS-level access with the
+ permissions of the server process,
+ as a C function can do. Thus, any unprivileged database user can
+ be permitted to use this language.
+ </p><p>
+ Here is an example of a function that will not work because file
+ system operations are not allowed for security reasons:
+</p><pre class="programlisting">
+CREATE FUNCTION badfunc() RETURNS integer AS $$
+ my $tmpfile = "/tmp/badfile";
+ open my $fh, '&gt;', $tmpfile
+ or elog(ERROR, qq{could not open the file "$tmpfile": $!});
+ print $fh "Testing writing to a file\n";
+ close $fh or elog(ERROR, qq{could not close the file "$tmpfile": $!});
+ return 1;
+$$ LANGUAGE plperl;
+</pre><p>
+ The creation of this function will fail as its use of a forbidden
+ operation will be caught by the validator.
+ </p><p>
+ Sometimes it is desirable to write Perl functions that are not
+ restricted. For example, one might want a Perl function that sends
+ mail. To handle these cases, PL/Perl can also be installed as an
+ <span class="quote">“<span class="quote">untrusted</span>”</span> language (usually called
+ <span class="application">PL/PerlU</span><a id="id-1.8.10.13.5.3" class="indexterm"></a>).
+ In this case the full Perl language is available. When installing the
+ language, the language name <code class="literal">plperlu</code> will select
+ the untrusted PL/Perl variant.
+ </p><p>
+ The writer of a <span class="application">PL/PerlU</span> function must take care that the function
+ cannot be used to do anything unwanted, since it will be able to do
+ anything that could be done by a user logged in as the database
+ administrator. Note that the database system allows only database
+ superusers to create functions in untrusted languages.
+ </p><p>
+ If the above function was created by a superuser using the language
+ <code class="literal">plperlu</code>, execution would succeed.
+ </p><p>
+ In the same way, anonymous code blocks written in Perl can use
+ restricted operations if the language is specified as
+ <code class="literal">plperlu</code> rather than <code class="literal">plperl</code>, but the caller
+ must be a superuser.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ While <span class="application">PL/Perl</span> functions run in a separate Perl
+ interpreter for each SQL role, all <span class="application">PL/PerlU</span> functions
+ executed in a given session run in a single Perl interpreter (which is
+ not any of the ones used for <span class="application">PL/Perl</span> functions).
+ This allows <span class="application">PL/PerlU</span> functions to share data freely,
+ but no communication can occur between <span class="application">PL/Perl</span> and
+ <span class="application">PL/PerlU</span> functions.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Perl cannot support multiple interpreters within one process unless
+ it was built with the appropriate flags, namely either
+ <code class="literal">usemultiplicity</code> or <code class="literal">useithreads</code>.
+ (<code class="literal">usemultiplicity</code> is preferred unless you actually need
+ to use threads. For more details, see the
+ <span class="citerefentry"><span class="refentrytitle">perlembed</span></span> man page.)
+ If <span class="application">PL/Perl</span> is used with a copy of Perl that was not built
+ this way, then it is only possible to have one Perl interpreter per
+ session, and so any one session can only execute either
+ <span class="application">PL/PerlU</span> functions, or <span class="application">PL/Perl</span> functions
+ that are all called by the same SQL role.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-global.html" title="45.4. Global Values in PL/Perl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-triggers.html" title="45.6. PL/Perl Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.4. Global Values in PL/Perl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.6. PL/Perl Triggers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl-under-the-hood.html b/doc/src/sgml/html/plperl-under-the-hood.html
new file mode 100644
index 0000000..0987d6b
--- /dev/null
+++ b/doc/src/sgml/html/plperl-under-the-hood.html
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>45.8. PL/Perl Under the Hood</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers" /><link rel="next" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">45.8. PL/Perl Under the Hood</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPERL-UNDER-THE-HOOD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">45.8. PL/Perl Under the Hood</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plperl-under-the-hood.html#PLPERL-CONFIG">45.8.1. Configuration</a></span></dt><dt><span class="sect2"><a href="plperl-under-the-hood.html#PLPERL-MISSING">45.8.2. Limitations and Missing Features</a></span></dt></dl></div><div class="sect2" id="PLPERL-CONFIG"><div class="titlepage"><div><div><h3 class="title">45.8.1. Configuration</h3></div></div></div><p>
+ This section lists configuration parameters that affect <span class="application">PL/Perl</span>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-PLPERL-ON-INIT"><span class="term">
+ <code class="varname">plperl.on_init</code> (<code class="type">string</code>)
+ <a id="id-1.8.10.16.2.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies Perl code to be executed when a Perl interpreter is first
+ initialized, before it is specialized for use by <code class="literal">plperl</code> or
+ <code class="literal">plperlu</code>.
+ The SPI functions are not available when this code is executed.
+ If the code fails with an error it will abort the initialization of
+ the interpreter and propagate out to the calling query, causing the
+ current transaction or subtransaction to be aborted.
+ </p><p>
+ The Perl code is limited to a single string. Longer code can be placed
+ into a module and loaded by the <code class="literal">on_init</code> string.
+ Examples:
+</p><pre class="programlisting">
+plperl.on_init = 'require "plperlinit.pl"'
+plperl.on_init = 'use lib "/my/app"; use MyApp::PgInit;'
+</pre><p>
+ </p><p>
+ Any modules loaded by <code class="literal">plperl.on_init</code>, either directly or
+ indirectly, will be available for use by <code class="literal">plperl</code>. This may
+ create a security risk. To see what modules have been loaded you can use:
+</p><pre class="programlisting">
+DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl;
+</pre><p>
+ </p><p>
+ Initialization will happen in the postmaster if the <code class="literal">plperl</code> library is
+ included in <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>, in which
+ case extra consideration should be given to the risk of destabilizing
+ the postmaster. The principal reason for making use of this feature
+ is that Perl modules loaded by <code class="literal">plperl.on_init</code> need be
+ loaded only at postmaster start, and will be instantly available
+ without loading overhead in individual database sessions. However,
+ keep in mind that the overhead is avoided only for the first Perl
+ interpreter used by a database session — either PL/PerlU, or
+ PL/Perl for the first SQL role that calls a PL/Perl function. Any
+ additional Perl interpreters created in a database session will have
+ to execute <code class="literal">plperl.on_init</code> afresh. Also, on Windows there
+ will be no savings whatsoever from preloading, since the Perl
+ interpreter created in the postmaster process does not propagate to
+ child processes.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-PLPERL-ON-PLPERL-INIT"><span class="term">
+ <code class="varname">plperl.on_plperl_init</code> (<code class="type">string</code>)
+ <a id="id-1.8.10.16.2.3.2.1.3" class="indexterm"></a>
+ <br /></span><span class="term">
+ <code class="varname">plperl.on_plperlu_init</code> (<code class="type">string</code>)
+ <a id="id-1.8.10.16.2.3.2.2.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ These parameters specify Perl code to be executed when a Perl
+ interpreter is specialized for <code class="literal">plperl</code> or
+ <code class="literal">plperlu</code> respectively. This will happen when a PL/Perl or
+ PL/PerlU function is first executed in a database session, or when
+ an additional interpreter has to be created because the other language
+ is called or a PL/Perl function is called by a new SQL role. This
+ follows any initialization done by <code class="literal">plperl.on_init</code>.
+ The SPI functions are not available when this code is executed.
+ The Perl code in <code class="literal">plperl.on_plperl_init</code> is executed after
+ <span class="quote">“<span class="quote">locking down</span>”</span> the interpreter, and thus it can only perform
+ trusted operations.
+ </p><p>
+ If the code fails with an error it will abort the initialization and
+ propagate out to the calling query, causing the current transaction or
+ subtransaction to be aborted. Any actions already done within Perl
+ won't be undone; however, that interpreter won't be used again.
+ If the language is used again the initialization will be attempted
+ again within a fresh Perl interpreter.
+ </p><p>
+ Only superusers can change these settings. Although these settings
+ can be changed within a session, such changes will not affect Perl
+ interpreters that have already been used to execute functions.
+ </p></dd><dt id="GUC-PLPERL-USE-STRICT"><span class="term">
+ <code class="varname">plperl.use_strict</code> (<code class="type">boolean</code>)
+ <a id="id-1.8.10.16.2.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set true subsequent compilations of PL/Perl functions will have
+ the <code class="literal">strict</code> pragma enabled. This parameter does not affect
+ functions already compiled in the current session.
+ </p></dd></dl></div></div><div class="sect2" id="PLPERL-MISSING"><div class="titlepage"><div><div><h3 class="title">45.8.2. Limitations and Missing Features</h3></div></div></div><p>
+ The following features are currently missing from PL/Perl, but they
+ would make welcome contributions.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ PL/Perl functions cannot call each other directly.
+ </p></li><li class="listitem"><p>
+ SPI is not yet fully implemented.
+ </p></li><li class="listitem"><p>
+ If you are fetching very large data sets using
+ <code class="literal">spi_exec_query</code>, you should be aware that
+ these will all go into memory. You can avoid this by using
+ <code class="literal">spi_query</code>/<code class="literal">spi_fetchrow</code> as
+ illustrated earlier.
+ </p><p>
+ A similar problem occurs if a set-returning function passes a
+ large set of rows back to PostgreSQL via <code class="literal">return</code>. You
+ can avoid this problem too by instead using
+ <code class="literal">return_next</code> for each row returned, as shown
+ previously.
+ </p></li><li class="listitem"><p>
+ When a session ends normally, not due to a fatal error, any
+ <code class="literal">END</code> blocks that have been defined are executed.
+ Currently no other actions are performed. Specifically,
+ file handles are not automatically flushed and objects are
+ not automatically destroyed.
+ </p></li></ul></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-event-triggers.html" title="45.7. PL/Perl Event Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.7. PL/Perl Event Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 46. PL/Python — Python Procedural Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plperl.html b/doc/src/sgml/html/plperl.html
new file mode 100644
index 0000000..47cf14d
--- /dev/null
+++ b/doc/src/sgml/html/plperl.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 45. PL/Perl — Perl Procedural Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names" /><link rel="next" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 45. PL/Perl — Perl Procedural Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLPERL"><div class="titlepage"><div><div><h2 class="title">Chapter 45. PL/Perl — Perl Procedural Language</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="plperl-funcs.html">45.1. PL/Perl Functions and Arguments</a></span></dt><dt><span class="sect1"><a href="plperl-data.html">45.2. Data Values in PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-builtins.html">45.3. Built-in Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="plperl-builtins.html#PLPERL-DATABASE">45.3.1. Database Access from PL/Perl</a></span></dt><dt><span class="sect2"><a href="plperl-builtins.html#PLPERL-UTILITY-FUNCTIONS">45.3.2. Utility Functions in PL/Perl</a></span></dt></dl></dd><dt><span class="sect1"><a href="plperl-global.html">45.4. Global Values in PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-trusted.html">45.5. Trusted and Untrusted PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-triggers.html">45.6. PL/Perl Triggers</a></span></dt><dt><span class="sect1"><a href="plperl-event-triggers.html">45.7. PL/Perl Event Triggers</a></span></dt><dt><span class="sect1"><a href="plperl-under-the-hood.html">45.8. PL/Perl Under the Hood</a></span></dt><dd><dl><dt><span class="sect2"><a href="plperl-under-the-hood.html#PLPERL-CONFIG">45.8.1. Configuration</a></span></dt><dt><span class="sect2"><a href="plperl-under-the-hood.html#PLPERL-MISSING">45.8.2. Limitations and Missing Features</a></span></dt></dl></dd></dl></div><a id="id-1.8.10.2" class="indexterm"></a><a id="id-1.8.10.3" class="indexterm"></a><p>
+ PL/Perl is a loadable procedural language that enables you to write
+ <span class="productname">PostgreSQL</span> functions and procedures in the
+ <a class="ulink" href="https://www.perl.org" target="_top">Perl programming language</a>.
+ </p><p>
+ The main advantage to using PL/Perl is that this allows use,
+ within stored functions and procedures, of the manyfold <span class="quote">“<span class="quote">string
+ munging</span>”</span> operators and functions available for Perl. Parsing
+ complex strings might be easier using Perl than it is with the
+ string functions and control structures provided in PL/pgSQL.
+ </p><p>
+ To install PL/Perl in a particular database, use
+ <code class="literal">CREATE EXTENSION plperl</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If a language is installed into <code class="literal">template1</code>, all subsequently
+ created databases will have the language installed automatically.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Users of source packages must specially enable the build of
+ PL/Perl during the installation process. (Refer to <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a> for more information.) Users of
+ binary packages might find PL/Perl in a separate subpackage.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl-funcs.html" title="45.1. PL/Perl Functions and Arguments">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.12. Tcl Procedure Names </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 45.1. PL/Perl Functions and Arguments</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-control-structures.html b/doc/src/sgml/html/plpgsql-control-structures.html
new file mode 100644
index 0000000..4fa998e
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-control-structures.html
@@ -0,0 +1,943 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.6. Control Structures</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-statements.html" title="43.5. Basic Statements" /><link rel="next" href="plpgsql-cursors.html" title="43.7. Cursors" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.6. Control Structures</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-statements.html" title="43.5. Basic Statements">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-cursors.html" title="43.7. Cursors">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-CONTROL-STRUCTURES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.6. Control Structures</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-RETURNING">43.6.1. Returning from a Function</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-RETURNING-PROCEDURE">43.6.2. Returning from a Procedure</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE">43.6.3. Calling a Procedure</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CONDITIONALS">43.6.4. Conditionals</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CONTROL-STRUCTURES-LOOPS">43.6.5. Simple Loops</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-RECORDS-ITERATING">43.6.6. Looping through Query Results</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-FOREACH-ARRAY">43.6.7. Looping through Arrays</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING">43.6.8. Trapping Errors</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CALL-STACK">43.6.9. Obtaining Execution Location Information</a></span></dt></dl></div><p>
+ Control structures are probably the most useful (and
+ important) part of <span class="application">PL/pgSQL</span>. With
+ <span class="application">PL/pgSQL</span>'s control structures,
+ you can manipulate <span class="productname">PostgreSQL</span> data in a very
+ flexible and powerful way.
+ </p><div class="sect2" id="PLPGSQL-STATEMENTS-RETURNING"><div class="titlepage"><div><div><h3 class="title">43.6.1. Returning from a Function</h3></div></div></div><p>
+ There are two commands available that allow you to return data
+ from a function: <code class="command">RETURN</code> and <code class="command">RETURN
+ NEXT</code>.
+ </p><div class="sect3" id="id-1.8.8.8.3.3"><div class="titlepage"><div><div><h4 class="title">43.6.1.1. <code class="command">RETURN</code></h4></div></div></div><pre class="synopsis">
+RETURN <em class="replaceable"><code>expression</code></em>;
+</pre><p>
+ <code class="command">RETURN</code> with an expression terminates the
+ function and returns the value of
+ <em class="replaceable"><code>expression</code></em> to the caller. This form
+ is used for <span class="application">PL/pgSQL</span> functions that do
+ not return a set.
+ </p><p>
+ In a function that returns a scalar type, the expression's result will
+ automatically be cast into the function's return type as described for
+ assignments. But to return a composite (row) value, you must write an
+ expression delivering exactly the requested column set. This may
+ require use of explicit casting.
+ </p><p>
+ If you declared the function with output parameters, write just
+ <code class="command">RETURN</code> with no expression. The current values
+ of the output parameter variables will be returned.
+ </p><p>
+ If you declared the function to return <code class="type">void</code>, a
+ <code class="command">RETURN</code> statement can be used to exit the function
+ early; but do not write an expression following
+ <code class="command">RETURN</code>.
+ </p><p>
+ The return value of a function cannot be left undefined. If
+ control reaches the end of the top-level block of the function
+ without hitting a <code class="command">RETURN</code> statement, a run-time
+ error will occur. This restriction does not apply to functions
+ with output parameters and functions returning <code class="type">void</code>,
+ however. In those cases a <code class="command">RETURN</code> statement is
+ automatically executed if the top-level block finishes.
+ </p><p>
+ Some examples:
+
+</p><pre class="programlisting">
+-- functions returning a scalar type
+RETURN 1 + 2;
+RETURN scalar_var;
+
+-- functions returning a composite type
+RETURN composite_type_var;
+RETURN (1, 2, 'three'::text); -- must cast columns to correct types
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.3.4"><div class="titlepage"><div><div><h4 class="title">43.6.1.2. <code class="command">RETURN NEXT</code> and <code class="command">RETURN QUERY</code></h4></div></div></div><a id="id-1.8.8.8.3.4.2" class="indexterm"></a><a id="id-1.8.8.8.3.4.3" class="indexterm"></a><pre class="synopsis">
+RETURN NEXT <em class="replaceable"><code>expression</code></em>;
+RETURN QUERY <em class="replaceable"><code>query</code></em>;
+RETURN QUERY EXECUTE <em class="replaceable"><code>command-string</code></em> [<span class="optional"> USING <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+</pre><p>
+ When a <span class="application">PL/pgSQL</span> function is declared to return
+ <code class="literal">SETOF <em class="replaceable"><code>sometype</code></em></code>, the procedure
+ to follow is slightly different. In that case, the individual
+ items to return are specified by a sequence of <code class="command">RETURN
+ NEXT</code> or <code class="command">RETURN QUERY</code> commands, and
+ then a final <code class="command">RETURN</code> command with no argument
+ is used to indicate that the function has finished executing.
+ <code class="command">RETURN NEXT</code> can be used with both scalar and
+ composite data types; with a composite result type, an entire
+ <span class="quote">“<span class="quote">table</span>”</span> of results will be returned.
+ <code class="command">RETURN QUERY</code> appends the results of executing
+ a query to the function's result set. <code class="command">RETURN
+ NEXT</code> and <code class="command">RETURN QUERY</code> can be freely
+ intermixed in a single set-returning function, in which case
+ their results will be concatenated.
+ </p><p>
+ <code class="command">RETURN NEXT</code> and <code class="command">RETURN
+ QUERY</code> do not actually return from the function —
+ they simply append zero or more rows to the function's result
+ set. Execution then continues with the next statement in the
+ <span class="application">PL/pgSQL</span> function. As successive
+ <code class="command">RETURN NEXT</code> or <code class="command">RETURN
+ QUERY</code> commands are executed, the result set is built
+ up. A final <code class="command">RETURN</code>, which should have no
+ argument, causes control to exit the function (or you can just
+ let control reach the end of the function).
+ </p><p>
+ <code class="command">RETURN QUERY</code> has a variant
+ <code class="command">RETURN QUERY EXECUTE</code>, which specifies the
+ query to be executed dynamically. Parameter expressions can
+ be inserted into the computed query string via <code class="literal">USING</code>,
+ in just the same way as in the <code class="command">EXECUTE</code> command.
+ </p><p>
+ If you declared the function with output parameters, write just
+ <code class="command">RETURN NEXT</code> with no expression. On each
+ execution, the current values of the output parameter
+ variable(s) will be saved for eventual return as a row of the
+ result. Note that you must declare the function as returning
+ <code class="literal">SETOF record</code> when there are multiple output
+ parameters, or <code class="literal">SETOF <em class="replaceable"><code>sometype</code></em></code>
+ when there is just one output parameter of type
+ <em class="replaceable"><code>sometype</code></em>, in order to create a set-returning
+ function with output parameters.
+ </p><p>
+ Here is an example of a function using <code class="command">RETURN
+ NEXT</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE foo (fooid INT, foosubid INT, fooname TEXT);
+INSERT INTO foo VALUES (1, 2, 'three');
+INSERT INTO foo VALUES (4, 5, 'six');
+
+CREATE OR REPLACE FUNCTION get_all_foo() RETURNS SETOF foo AS
+$BODY$
+DECLARE
+ r foo%rowtype;
+BEGIN
+ FOR r IN
+ SELECT * FROM foo WHERE fooid &gt; 0
+ LOOP
+ -- can do some processing here
+ RETURN NEXT r; -- return current row of SELECT
+ END LOOP;
+ RETURN;
+END;
+$BODY$
+LANGUAGE plpgsql;
+
+SELECT * FROM get_all_foo();
+</pre><p>
+ </p><p>
+ Here is an example of a function using <code class="command">RETURN
+ QUERY</code>:
+
+</p><pre class="programlisting">
+CREATE FUNCTION get_available_flightid(date) RETURNS SETOF integer AS
+$BODY$
+BEGIN
+ RETURN QUERY SELECT flightid
+ FROM flight
+ WHERE flightdate &gt;= $1
+ AND flightdate &lt; ($1 + 1);
+
+ -- Since execution is not finished, we can check whether rows were returned
+ -- and raise exception if not.
+ IF NOT FOUND THEN
+ RAISE EXCEPTION 'No flight at %.', $1;
+ END IF;
+
+ RETURN;
+ END;
+$BODY$
+LANGUAGE plpgsql;
+
+-- Returns available flights or raises exception if there are no
+-- available flights.
+SELECT * FROM get_available_flightid(CURRENT_DATE);
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The current implementation of <code class="command">RETURN NEXT</code>
+ and <code class="command">RETURN QUERY</code> stores the entire result set
+ before returning from the function, as discussed above. That
+ means that if a <span class="application">PL/pgSQL</span> function produces a
+ very large result set, performance might be poor: data will be
+ written to disk to avoid memory exhaustion, but the function
+ itself will not return until the entire result set has been
+ generated. A future version of <span class="application">PL/pgSQL</span> might
+ allow users to define set-returning functions
+ that do not have this limitation. Currently, the point at
+ which data begins being written to disk is controlled by the
+ <a class="xref" href="runtime-config-resource.html#GUC-WORK-MEM">work_mem</a>
+ configuration variable. Administrators who have sufficient
+ memory to store larger result sets in memory should consider
+ increasing this parameter.
+ </p></div></div></div><div class="sect2" id="PLPGSQL-STATEMENTS-RETURNING-PROCEDURE"><div class="titlepage"><div><div><h3 class="title">43.6.2. Returning from a Procedure</h3></div></div></div><p>
+ A procedure does not have a return value. A procedure can therefore end
+ without a <code class="command">RETURN</code> statement. If you wish to use
+ a <code class="command">RETURN</code> statement to exit the code early, write
+ just <code class="command">RETURN</code> with no expression.
+ </p><p>
+ If the procedure has output parameters, the final values of the output
+ parameter variables will be returned to the caller.
+ </p></div><div class="sect2" id="PLPGSQL-STATEMENTS-CALLING-PROCEDURE"><div class="titlepage"><div><div><h3 class="title">43.6.3. Calling a Procedure</h3></div></div></div><p>
+ A <span class="application">PL/pgSQL</span> function, procedure,
+ or <code class="command">DO</code> block can call a procedure
+ using <code class="command">CALL</code>. Output parameters are handled
+ differently from the way that <code class="command">CALL</code> works in plain
+ SQL. Each <code class="literal">OUT</code> or <code class="literal">INOUT</code>
+ parameter of the procedure must
+ correspond to a variable in the <code class="command">CALL</code> statement, and
+ whatever the procedure returns is assigned back to that variable after
+ it returns. For example:
+</p><pre class="programlisting">
+CREATE PROCEDURE triple(INOUT x int)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+ x := x * 3;
+END;
+$$;
+
+DO $$
+DECLARE myvar int := 5;
+BEGIN
+ CALL triple(myvar);
+ RAISE NOTICE 'myvar = %', myvar; -- prints 15
+END;
+$$;
+</pre><p>
+ The variable corresponding to an output parameter can be a simple
+ variable or a field of a composite-type variable. Currently,
+ it cannot be an element of an array.
+ </p></div><div class="sect2" id="PLPGSQL-CONDITIONALS"><div class="titlepage"><div><div><h3 class="title">43.6.4. Conditionals</h3></div></div></div><p>
+ <code class="command">IF</code> and <code class="command">CASE</code> statements let you execute
+ alternative commands based on certain conditions.
+ <span class="application">PL/pgSQL</span> has three forms of <code class="command">IF</code>:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">IF ... THEN ... END IF</code></p></li><li class="listitem"><p><code class="literal">IF ... THEN ... ELSE ... END IF</code></p></li><li class="listitem"><p><code class="literal">IF ... THEN ... ELSIF ... THEN ... ELSE ... END IF</code></p></li></ul></div><p>
+
+ and two forms of <code class="command">CASE</code>:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">CASE ... WHEN ... THEN ... ELSE ... END CASE</code></p></li><li class="listitem"><p><code class="literal">CASE WHEN ... THEN ... ELSE ... END CASE</code></p></li></ul></div><p>
+ </p><div class="sect3" id="id-1.8.8.8.6.3"><div class="titlepage"><div><div><h4 class="title">43.6.4.1. <code class="literal">IF-THEN</code></h4></div></div></div><pre class="synopsis">
+IF <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+END IF;
+</pre><p>
+ <code class="literal">IF-THEN</code> statements are the simplest form of
+ <code class="literal">IF</code>. The statements between
+ <code class="literal">THEN</code> and <code class="literal">END IF</code> will be
+ executed if the condition is true. Otherwise, they are
+ skipped.
+ </p><p>
+ Example:
+</p><pre class="programlisting">
+IF v_user_id &lt;&gt; 0 THEN
+ UPDATE users SET email = v_email WHERE user_id = v_user_id;
+END IF;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.6.4"><div class="titlepage"><div><div><h4 class="title">43.6.4.2. <code class="literal">IF-THEN-ELSE</code></h4></div></div></div><pre class="synopsis">
+IF <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+ELSE
+ <em class="replaceable"><code>statements</code></em>
+END IF;
+</pre><p>
+ <code class="literal">IF-THEN-ELSE</code> statements add to
+ <code class="literal">IF-THEN</code> by letting you specify an
+ alternative set of statements that should be executed if the
+ condition is not true. (Note this includes the case where the
+ condition evaluates to NULL.)
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+IF parentid IS NULL OR parentid = ''
+THEN
+ RETURN fullname;
+ELSE
+ RETURN hp_true_filename(parentid) || '/' || fullname;
+END IF;
+</pre><p>
+
+</p><pre class="programlisting">
+IF v_count &gt; 0 THEN
+ INSERT INTO users_count (count) VALUES (v_count);
+ RETURN 't';
+ELSE
+ RETURN 'f';
+END IF;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.6.5"><div class="titlepage"><div><div><h4 class="title">43.6.4.3. <code class="literal">IF-THEN-ELSIF</code></h4></div></div></div><pre class="synopsis">
+IF <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+[<span class="optional"> ELSIF <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+[<span class="optional"> ELSIF <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+ ...
+</span>]
+</span>]
+[<span class="optional"> ELSE
+ <em class="replaceable"><code>statements</code></em> </span>]
+END IF;
+</pre><p>
+ Sometimes there are more than just two alternatives.
+ <code class="literal">IF-THEN-ELSIF</code> provides a convenient
+ method of checking several alternatives in turn.
+ The <code class="literal">IF</code> conditions are tested successively
+ until the first one that is true is found. Then the
+ associated statement(s) are executed, after which control
+ passes to the next statement after <code class="literal">END IF</code>.
+ (Any subsequent <code class="literal">IF</code> conditions are <span class="emphasis"><em>not</em></span>
+ tested.) If none of the <code class="literal">IF</code> conditions is true,
+ then the <code class="literal">ELSE</code> block (if any) is executed.
+ </p><p>
+ Here is an example:
+
+</p><pre class="programlisting">
+IF number = 0 THEN
+ result := 'zero';
+ELSIF number &gt; 0 THEN
+ result := 'positive';
+ELSIF number &lt; 0 THEN
+ result := 'negative';
+ELSE
+ -- hmm, the only other possibility is that number is null
+ result := 'NULL';
+END IF;
+</pre><p>
+ </p><p>
+ The key word <code class="literal">ELSIF</code> can also be spelled
+ <code class="literal">ELSEIF</code>.
+ </p><p>
+ An alternative way of accomplishing the same task is to nest
+ <code class="literal">IF-THEN-ELSE</code> statements, as in the
+ following example:
+
+</p><pre class="programlisting">
+IF demo_row.sex = 'm' THEN
+ pretty_sex := 'man';
+ELSE
+ IF demo_row.sex = 'f' THEN
+ pretty_sex := 'woman';
+ END IF;
+END IF;
+</pre><p>
+ </p><p>
+ However, this method requires writing a matching <code class="literal">END IF</code>
+ for each <code class="literal">IF</code>, so it is much more cumbersome than
+ using <code class="literal">ELSIF</code> when there are many alternatives.
+ </p></div><div class="sect3" id="id-1.8.8.8.6.6"><div class="titlepage"><div><div><h4 class="title">43.6.4.4. Simple <code class="literal">CASE</code></h4></div></div></div><pre class="synopsis">
+CASE <em class="replaceable"><code>search-expression</code></em>
+ WHEN <em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> [<span class="optional"> ... </span>]</span>] THEN
+ <em class="replaceable"><code>statements</code></em>
+ [<span class="optional"> WHEN <em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> [<span class="optional"> ... </span>]</span>] THEN
+ <em class="replaceable"><code>statements</code></em>
+ ... </span>]
+ [<span class="optional"> ELSE
+ <em class="replaceable"><code>statements</code></em> </span>]
+END CASE;
+</pre><p>
+ The simple form of <code class="command">CASE</code> provides conditional execution
+ based on equality of operands. The <em class="replaceable"><code>search-expression</code></em>
+ is evaluated (once) and successively compared to each
+ <em class="replaceable"><code>expression</code></em> in the <code class="literal">WHEN</code> clauses.
+ If a match is found, then the corresponding
+ <em class="replaceable"><code>statements</code></em> are executed, and then control
+ passes to the next statement after <code class="literal">END CASE</code>. (Subsequent
+ <code class="literal">WHEN</code> expressions are not evaluated.) If no match is
+ found, the <code class="literal">ELSE</code> <em class="replaceable"><code>statements</code></em> are
+ executed; but if <code class="literal">ELSE</code> is not present, then a
+ <code class="literal">CASE_NOT_FOUND</code> exception is raised.
+ </p><p>
+ Here is a simple example:
+
+</p><pre class="programlisting">
+CASE x
+ WHEN 1, 2 THEN
+ msg := 'one or two';
+ ELSE
+ msg := 'other value than one or two';
+END CASE;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.6.7"><div class="titlepage"><div><div><h4 class="title">43.6.4.5. Searched <code class="literal">CASE</code></h4></div></div></div><pre class="synopsis">
+CASE
+ WHEN <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+ [<span class="optional"> WHEN <em class="replaceable"><code>boolean-expression</code></em> THEN
+ <em class="replaceable"><code>statements</code></em>
+ ... </span>]
+ [<span class="optional"> ELSE
+ <em class="replaceable"><code>statements</code></em> </span>]
+END CASE;
+</pre><p>
+ The searched form of <code class="command">CASE</code> provides conditional execution
+ based on truth of Boolean expressions. Each <code class="literal">WHEN</code> clause's
+ <em class="replaceable"><code>boolean-expression</code></em> is evaluated in turn,
+ until one is found that yields <code class="literal">true</code>. Then the
+ corresponding <em class="replaceable"><code>statements</code></em> are executed, and
+ then control passes to the next statement after <code class="literal">END CASE</code>.
+ (Subsequent <code class="literal">WHEN</code> expressions are not evaluated.)
+ If no true result is found, the <code class="literal">ELSE</code>
+ <em class="replaceable"><code>statements</code></em> are executed;
+ but if <code class="literal">ELSE</code> is not present, then a
+ <code class="literal">CASE_NOT_FOUND</code> exception is raised.
+ </p><p>
+ Here is an example:
+
+</p><pre class="programlisting">
+CASE
+ WHEN x BETWEEN 0 AND 10 THEN
+ msg := 'value is between zero and ten';
+ WHEN x BETWEEN 11 AND 20 THEN
+ msg := 'value is between eleven and twenty';
+END CASE;
+</pre><p>
+ </p><p>
+ This form of <code class="command">CASE</code> is entirely equivalent to
+ <code class="literal">IF-THEN-ELSIF</code>, except for the rule that reaching
+ an omitted <code class="literal">ELSE</code> clause results in an error rather
+ than doing nothing.
+ </p></div></div><div class="sect2" id="PLPGSQL-CONTROL-STRUCTURES-LOOPS"><div class="titlepage"><div><div><h3 class="title">43.6.5. Simple Loops</h3></div></div></div><a id="id-1.8.8.8.7.2" class="indexterm"></a><p>
+ With the <code class="literal">LOOP</code>, <code class="literal">EXIT</code>,
+ <code class="literal">CONTINUE</code>, <code class="literal">WHILE</code>, <code class="literal">FOR</code>,
+ and <code class="literal">FOREACH</code> statements, you can arrange for your
+ <span class="application">PL/pgSQL</span> function to repeat a series of commands.
+ </p><div class="sect3" id="id-1.8.8.8.7.4"><div class="titlepage"><div><div><h4 class="title">43.6.5.1. <code class="literal">LOOP</code></h4></div></div></div><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ <code class="literal">LOOP</code> defines an unconditional loop that is repeated
+ indefinitely until terminated by an <code class="literal">EXIT</code> or
+ <code class="command">RETURN</code> statement. The optional
+ <em class="replaceable"><code>label</code></em> can be used by <code class="literal">EXIT</code>
+ and <code class="literal">CONTINUE</code> statements within nested loops to
+ specify which loop those statements refer to.
+ </p></div><div class="sect3" id="id-1.8.8.8.7.5"><div class="titlepage"><div><div><h4 class="title">43.6.5.2. <code class="literal">EXIT</code></h4></div></div></div><a id="id-1.8.8.8.7.5.2" class="indexterm"></a><pre class="synopsis">
+EXIT [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>] [<span class="optional"> WHEN <em class="replaceable"><code>boolean-expression</code></em> </span>];
+</pre><p>
+ If no <em class="replaceable"><code>label</code></em> is given, the innermost
+ loop is terminated and the statement following <code class="literal">END
+ LOOP</code> is executed next. If <em class="replaceable"><code>label</code></em>
+ is given, it must be the label of the current or some outer
+ level of nested loop or block. Then the named loop or block is
+ terminated and control continues with the statement after the
+ loop's/block's corresponding <code class="literal">END</code>.
+ </p><p>
+ If <code class="literal">WHEN</code> is specified, the loop exit occurs only if
+ <em class="replaceable"><code>boolean-expression</code></em> is true. Otherwise, control passes
+ to the statement after <code class="literal">EXIT</code>.
+ </p><p>
+ <code class="literal">EXIT</code> can be used with all types of loops; it is
+ not limited to use with unconditional loops.
+ </p><p>
+ When used with a
+ <code class="literal">BEGIN</code> block, <code class="literal">EXIT</code> passes
+ control to the next statement after the end of the block.
+ Note that a label must be used for this purpose; an unlabeled
+ <code class="literal">EXIT</code> is never considered to match a
+ <code class="literal">BEGIN</code> block. (This is a change from
+ pre-8.4 releases of <span class="productname">PostgreSQL</span>, which
+ would allow an unlabeled <code class="literal">EXIT</code> to match
+ a <code class="literal">BEGIN</code> block.)
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+LOOP
+ -- some computations
+ IF count &gt; 0 THEN
+ EXIT; -- exit loop
+ END IF;
+END LOOP;
+
+LOOP
+ -- some computations
+ EXIT WHEN count &gt; 0; -- same result as previous example
+END LOOP;
+
+&lt;&lt;ablock&gt;&gt;
+BEGIN
+ -- some computations
+ IF stocks &gt; 100000 THEN
+ EXIT ablock; -- causes exit from the BEGIN block
+ END IF;
+ -- computations here will be skipped when stocks &gt; 100000
+END;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.7.6"><div class="titlepage"><div><div><h4 class="title">43.6.5.3. <code class="literal">CONTINUE</code></h4></div></div></div><a id="id-1.8.8.8.7.6.2" class="indexterm"></a><pre class="synopsis">
+CONTINUE [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>] [<span class="optional"> WHEN <em class="replaceable"><code>boolean-expression</code></em> </span>];
+</pre><p>
+ If no <em class="replaceable"><code>label</code></em> is given, the next iteration of
+ the innermost loop is begun. That is, all statements remaining
+ in the loop body are skipped, and control returns
+ to the loop control expression (if any) to determine whether
+ another loop iteration is needed.
+ If <em class="replaceable"><code>label</code></em> is present, it
+ specifies the label of the loop whose execution will be
+ continued.
+ </p><p>
+ If <code class="literal">WHEN</code> is specified, the next iteration of the
+ loop is begun only if <em class="replaceable"><code>boolean-expression</code></em> is
+ true. Otherwise, control passes to the statement after
+ <code class="literal">CONTINUE</code>.
+ </p><p>
+ <code class="literal">CONTINUE</code> can be used with all types of loops; it
+ is not limited to use with unconditional loops.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+LOOP
+ -- some computations
+ EXIT WHEN count &gt; 100;
+ CONTINUE WHEN count &lt; 50;
+ -- some computations for count IN [50 .. 100]
+END LOOP;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.8.7.7"><div class="titlepage"><div><div><h4 class="title">43.6.5.4. <code class="literal">WHILE</code></h4></div></div></div><a id="id-1.8.8.8.7.7.2" class="indexterm"></a><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+WHILE <em class="replaceable"><code>boolean-expression</code></em> LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ The <code class="literal">WHILE</code> statement repeats a
+ sequence of statements so long as the
+ <em class="replaceable"><code>boolean-expression</code></em>
+ evaluates to true. The expression is checked just before
+ each entry to the loop body.
+ </p><p>
+ For example:
+</p><pre class="programlisting">
+WHILE amount_owed &gt; 0 AND gift_certificate_balance &gt; 0 LOOP
+ -- some computations here
+END LOOP;
+
+WHILE NOT done LOOP
+ -- some computations here
+END LOOP;
+</pre><p>
+ </p></div><div class="sect3" id="PLPGSQL-INTEGER-FOR"><div class="titlepage"><div><div><h4 class="title">43.6.5.5. <code class="literal">FOR</code> (Integer Variant)</h4></div></div></div><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+FOR <em class="replaceable"><code>name</code></em> IN [<span class="optional"> REVERSE </span>] <em class="replaceable"><code>expression</code></em> .. <em class="replaceable"><code>expression</code></em> [<span class="optional"> BY <em class="replaceable"><code>expression</code></em> </span>] LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ This form of <code class="literal">FOR</code> creates a loop that iterates over a range
+ of integer values. The variable
+ <em class="replaceable"><code>name</code></em> is automatically defined as type
+ <code class="type">integer</code> and exists only inside the loop (any existing
+ definition of the variable name is ignored within the loop).
+ The two expressions giving
+ the lower and upper bound of the range are evaluated once when entering
+ the loop. If the <code class="literal">BY</code> clause isn't specified the iteration
+ step is 1, otherwise it's the value specified in the <code class="literal">BY</code>
+ clause, which again is evaluated once on loop entry.
+ If <code class="literal">REVERSE</code> is specified then the step value is
+ subtracted, rather than added, after each iteration.
+ </p><p>
+ Some examples of integer <code class="literal">FOR</code> loops:
+</p><pre class="programlisting">
+FOR i IN 1..10 LOOP
+ -- i will take on the values 1,2,3,4,5,6,7,8,9,10 within the loop
+END LOOP;
+
+FOR i IN REVERSE 10..1 LOOP
+ -- i will take on the values 10,9,8,7,6,5,4,3,2,1 within the loop
+END LOOP;
+
+FOR i IN REVERSE 10..1 BY 2 LOOP
+ -- i will take on the values 10,8,6,4,2 within the loop
+END LOOP;
+</pre><p>
+ </p><p>
+ If the lower bound is greater than the upper bound (or less than,
+ in the <code class="literal">REVERSE</code> case), the loop body is not
+ executed at all. No error is raised.
+ </p><p>
+ If a <em class="replaceable"><code>label</code></em> is attached to the
+ <code class="literal">FOR</code> loop then the integer loop variable can be
+ referenced with a qualified name, using that
+ <em class="replaceable"><code>label</code></em>.
+ </p></div></div><div class="sect2" id="PLPGSQL-RECORDS-ITERATING"><div class="titlepage"><div><div><h3 class="title">43.6.6. Looping through Query Results</h3></div></div></div><p>
+ Using a different type of <code class="literal">FOR</code> loop, you can iterate through
+ the results of a query and manipulate that data
+ accordingly. The syntax is:
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+FOR <em class="replaceable"><code>target</code></em> IN <em class="replaceable"><code>query</code></em> LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ The <em class="replaceable"><code>target</code></em> is a record variable, row variable,
+ or comma-separated list of scalar variables.
+ The <em class="replaceable"><code>target</code></em> is successively assigned each row
+ resulting from the <em class="replaceable"><code>query</code></em> and the loop body is
+ executed for each row. Here is an example:
+</p><pre class="programlisting">
+CREATE FUNCTION refresh_mviews() RETURNS integer AS $$
+DECLARE
+ mviews RECORD;
+BEGIN
+ RAISE NOTICE 'Refreshing all materialized views...';
+
+ FOR mviews IN
+ SELECT n.nspname AS mv_schema,
+ c.relname AS mv_name,
+ pg_catalog.pg_get_userbyid(c.relowner) AS owner
+ FROM pg_catalog.pg_class c
+ LEFT JOIN pg_catalog.pg_namespace n ON (n.oid = c.relnamespace)
+ WHERE c.relkind = 'm'
+ ORDER BY 1
+ LOOP
+
+ -- Now "mviews" has one record with information about the materialized view
+
+ RAISE NOTICE 'Refreshing materialized view %.% (owner: %)...',
+ quote_ident(mviews.mv_schema),
+ quote_ident(mviews.mv_name),
+ quote_ident(mviews.owner);
+ EXECUTE format('REFRESH MATERIALIZED VIEW %I.%I', mviews.mv_schema, mviews.mv_name);
+ END LOOP;
+
+ RAISE NOTICE 'Done refreshing materialized views.';
+ RETURN 1;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ If the loop is terminated by an <code class="literal">EXIT</code> statement, the last
+ assigned row value is still accessible after the loop.
+ </p><p>
+ The <em class="replaceable"><code>query</code></em> used in this type of <code class="literal">FOR</code>
+ statement can be any SQL command that returns rows to the caller:
+ <code class="command">SELECT</code> is the most common case,
+ but you can also use <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> with a <code class="literal">RETURNING</code> clause. Some utility
+ commands such as <code class="command">EXPLAIN</code> will work too.
+ </p><p>
+ <span class="application">PL/pgSQL</span> variables are replaced by query parameters,
+ and the query plan is cached for possible re-use, as discussed in
+ detail in <a class="xref" href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST" title="43.11.1. Variable Substitution">Section 43.11.1</a> and
+ <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="43.11.2. Plan Caching">Section 43.11.2</a>.
+ </p><p>
+ The <code class="literal">FOR-IN-EXECUTE</code> statement is another way to iterate over
+ rows:
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+FOR <em class="replaceable"><code>target</code></em> IN EXECUTE <em class="replaceable"><code>text_expression</code></em> [<span class="optional"> USING <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>] LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ This is like the previous form, except that the source query
+ is specified as a string expression, which is evaluated and replanned
+ on each entry to the <code class="literal">FOR</code> loop. This allows the programmer to
+ choose the speed of a preplanned query or the flexibility of a dynamic
+ query, just as with a plain <code class="command">EXECUTE</code> statement.
+ As with <code class="command">EXECUTE</code>, parameter values can be inserted
+ into the dynamic command via <code class="literal">USING</code>.
+ </p><p>
+ Another way to specify the query whose results should be iterated
+ through is to declare it as a cursor. This is described in
+ <a class="xref" href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP" title="43.7.4. Looping through a Cursor's Result">Section 43.7.4</a>.
+ </p></div><div class="sect2" id="PLPGSQL-FOREACH-ARRAY"><div class="titlepage"><div><div><h3 class="title">43.6.7. Looping through Arrays</h3></div></div></div><p>
+ The <code class="literal">FOREACH</code> loop is much like a <code class="literal">FOR</code> loop,
+ but instead of iterating through the rows returned by an SQL query,
+ it iterates through the elements of an array value.
+ (In general, <code class="literal">FOREACH</code> is meant for looping through
+ components of a composite-valued expression; variants for looping
+ through composites besides arrays may be added in future.)
+ The <code class="literal">FOREACH</code> statement to loop over an array is:
+
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+FOREACH <em class="replaceable"><code>target</code></em> [<span class="optional"> SLICE <em class="replaceable"><code>number</code></em> </span>] IN ARRAY <em class="replaceable"><code>expression</code></em> LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ </p><p>
+ Without <code class="literal">SLICE</code>, or if <code class="literal">SLICE 0</code> is specified,
+ the loop iterates through individual elements of the array produced
+ by evaluating the <em class="replaceable"><code>expression</code></em>.
+ The <em class="replaceable"><code>target</code></em> variable is assigned each
+ element value in sequence, and the loop body is executed for each element.
+ Here is an example of looping through the elements of an integer
+ array:
+
+</p><pre class="programlisting">
+CREATE FUNCTION sum(int[]) RETURNS int8 AS $$
+DECLARE
+ s int8 := 0;
+ x int;
+BEGIN
+ FOREACH x IN ARRAY $1
+ LOOP
+ s := s + x;
+ END LOOP;
+ RETURN s;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ The elements are visited in storage order, regardless of the number of
+ array dimensions. Although the <em class="replaceable"><code>target</code></em> is
+ usually just a single variable, it can be a list of variables when
+ looping through an array of composite values (records). In that case,
+ for each array element, the variables are assigned from successive
+ columns of the composite value.
+ </p><p>
+ With a positive <code class="literal">SLICE</code> value, <code class="literal">FOREACH</code>
+ iterates through slices of the array rather than single elements.
+ The <code class="literal">SLICE</code> value must be an integer constant not larger
+ than the number of dimensions of the array. The
+ <em class="replaceable"><code>target</code></em> variable must be an array,
+ and it receives successive slices of the array value, where each slice
+ is of the number of dimensions specified by <code class="literal">SLICE</code>.
+ Here is an example of iterating through one-dimensional slices:
+
+</p><pre class="programlisting">
+CREATE FUNCTION scan_rows(int[]) RETURNS void AS $$
+DECLARE
+ x int[];
+BEGIN
+ FOREACH x SLICE 1 IN ARRAY $1
+ LOOP
+ RAISE NOTICE 'row = %', x;
+ END LOOP;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT scan_rows(ARRAY[[1,2,3],[4,5,6],[7,8,9],[10,11,12]]);
+
+NOTICE: row = {1,2,3}
+NOTICE: row = {4,5,6}
+NOTICE: row = {7,8,9}
+NOTICE: row = {10,11,12}
+</pre><p>
+ </p></div><div class="sect2" id="PLPGSQL-ERROR-TRAPPING"><div class="titlepage"><div><div><h3 class="title">43.6.8. Trapping Errors</h3></div></div></div><a id="id-1.8.8.8.10.2" class="indexterm"></a><p>
+ By default, any error occurring in a <span class="application">PL/pgSQL</span>
+ function aborts execution of the function and the
+ surrounding transaction. You can trap errors and recover
+ from them by using a <code class="command">BEGIN</code> block with an
+ <code class="literal">EXCEPTION</code> clause. The syntax is an extension of the
+ normal syntax for a <code class="command">BEGIN</code> block:
+
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+[<span class="optional"> DECLARE
+ <em class="replaceable"><code>declarations</code></em> </span>]
+BEGIN
+ <em class="replaceable"><code>statements</code></em>
+EXCEPTION
+ WHEN <em class="replaceable"><code>condition</code></em> [<span class="optional"> OR <em class="replaceable"><code>condition</code></em> ... </span>] THEN
+ <em class="replaceable"><code>handler_statements</code></em>
+ [<span class="optional"> WHEN <em class="replaceable"><code>condition</code></em> [<span class="optional"> OR <em class="replaceable"><code>condition</code></em> ... </span>] THEN
+ <em class="replaceable"><code>handler_statements</code></em>
+ ... </span>]
+END;
+</pre><p>
+ </p><p>
+ If no error occurs, this form of block simply executes all the
+ <em class="replaceable"><code>statements</code></em>, and then control passes
+ to the next statement after <code class="literal">END</code>. But if an error
+ occurs within the <em class="replaceable"><code>statements</code></em>, further
+ processing of the <em class="replaceable"><code>statements</code></em> is
+ abandoned, and control passes to the <code class="literal">EXCEPTION</code> list.
+ The list is searched for the first <em class="replaceable"><code>condition</code></em>
+ matching the error that occurred. If a match is found, the
+ corresponding <em class="replaceable"><code>handler_statements</code></em> are
+ executed, and then control passes to the next statement after
+ <code class="literal">END</code>. If no match is found, the error propagates out
+ as though the <code class="literal">EXCEPTION</code> clause were not there at all:
+ the error can be caught by an enclosing block with
+ <code class="literal">EXCEPTION</code>, or if there is none it aborts processing
+ of the function.
+ </p><p>
+ The <em class="replaceable"><code>condition</code></em> names can be any of
+ those shown in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>. A category
+ name matches any error within its category. The special
+ condition name <code class="literal">OTHERS</code> matches every error type except
+ <code class="literal">QUERY_CANCELED</code> and <code class="literal">ASSERT_FAILURE</code>.
+ (It is possible, but often unwise, to trap those two error types
+ by name.) Condition names are
+ not case-sensitive. Also, an error condition can be specified
+ by <code class="literal">SQLSTATE</code> code; for example these are equivalent:
+</p><pre class="programlisting">
+WHEN division_by_zero THEN ...
+WHEN SQLSTATE '22012' THEN ...
+</pre><p>
+ </p><p>
+ If a new error occurs within the selected
+ <em class="replaceable"><code>handler_statements</code></em>, it cannot be caught
+ by this <code class="literal">EXCEPTION</code> clause, but is propagated out.
+ A surrounding <code class="literal">EXCEPTION</code> clause could catch it.
+ </p><p>
+ When an error is caught by an <code class="literal">EXCEPTION</code> clause,
+ the local variables of the <span class="application">PL/pgSQL</span> function
+ remain as they were when the error occurred, but all changes
+ to persistent database state within the block are rolled back.
+ As an example, consider this fragment:
+
+</p><pre class="programlisting">
+INSERT INTO mytab(firstname, lastname) VALUES('Tom', 'Jones');
+BEGIN
+ UPDATE mytab SET firstname = 'Joe' WHERE lastname = 'Jones';
+ x := x + 1;
+ y := x / 0;
+EXCEPTION
+ WHEN division_by_zero THEN
+ RAISE NOTICE 'caught division_by_zero';
+ RETURN x;
+END;
+</pre><p>
+
+ When control reaches the assignment to <code class="literal">y</code>, it will
+ fail with a <code class="literal">division_by_zero</code> error. This will be caught by
+ the <code class="literal">EXCEPTION</code> clause. The value returned in the
+ <code class="command">RETURN</code> statement will be the incremented value of
+ <code class="literal">x</code>, but the effects of the <code class="command">UPDATE</code> command will
+ have been rolled back. The <code class="command">INSERT</code> command preceding the
+ block is not rolled back, however, so the end result is that the database
+ contains <code class="literal">Tom Jones</code> not <code class="literal">Joe Jones</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ A block containing an <code class="literal">EXCEPTION</code> clause is significantly
+ more expensive to enter and exit than a block without one. Therefore,
+ don't use <code class="literal">EXCEPTION</code> without need.
+ </p></div><div class="example" id="PLPGSQL-UPSERT-EXAMPLE"><p class="title"><strong>Example 43.2. Exceptions with <code class="command">UPDATE</code>/<code class="command">INSERT</code></strong></p><div class="example-contents"><p>
+
+ This example uses exception handling to perform either
+ <code class="command">UPDATE</code> or <code class="command">INSERT</code>, as appropriate. It is
+ recommended that applications use <code class="command">INSERT</code> with
+ <code class="literal">ON CONFLICT DO UPDATE</code> rather than actually using
+ this pattern. This example serves primarily to illustrate use of
+ <span class="application">PL/pgSQL</span> control flow structures:
+
+</p><pre class="programlisting">
+CREATE TABLE db (a INT PRIMARY KEY, b TEXT);
+
+CREATE FUNCTION merge_db(key INT, data TEXT) RETURNS VOID AS
+$$
+BEGIN
+ LOOP
+ -- first try to update the key
+ UPDATE db SET b = data WHERE a = key;
+ IF found THEN
+ RETURN;
+ END IF;
+ -- not there, so try to insert the key
+ -- if someone else inserts the same key concurrently,
+ -- we could get a unique-key failure
+ BEGIN
+ INSERT INTO db(a,b) VALUES (key, data);
+ RETURN;
+ EXCEPTION WHEN unique_violation THEN
+ -- Do nothing, and loop to try the UPDATE again.
+ END;
+ END LOOP;
+END;
+$$
+LANGUAGE plpgsql;
+
+SELECT merge_db(1, 'david');
+SELECT merge_db(1, 'dennis');
+</pre><p>
+
+ This coding assumes the <code class="literal">unique_violation</code> error is caused by
+ the <code class="command">INSERT</code>, and not by, say, an <code class="command">INSERT</code> in a
+ trigger function on the table. It might also misbehave if there is
+ more than one unique index on the table, since it will retry the
+ operation regardless of which index caused the error.
+ More safety could be had by using the
+ features discussed next to check that the trapped error was the one
+ expected.
+ </p></div></div><br class="example-break" /><div class="sect3" id="PLPGSQL-EXCEPTION-DIAGNOSTICS"><div class="titlepage"><div><div><h4 class="title">43.6.8.1. Obtaining Information about an Error</h4></div></div></div><p>
+ Exception handlers frequently need to identify the specific error that
+ occurred. There are two ways to get information about the current
+ exception in <span class="application">PL/pgSQL</span>: special variables and the
+ <code class="command">GET STACKED DIAGNOSTICS</code> command.
+ </p><p>
+ Within an exception handler, the special variable
+ <code class="varname">SQLSTATE</code> contains the error code that corresponds to
+ the exception that was raised (refer to <a class="xref" href="errcodes-appendix.html#ERRCODES-TABLE" title="Table A.1. PostgreSQL Error Codes">Table A.1</a>
+ for a list of possible error codes). The special variable
+ <code class="varname">SQLERRM</code> contains the error message associated with the
+ exception. These variables are undefined outside exception handlers.
+ </p><p>
+ Within an exception handler, one may also retrieve
+ information about the current exception by using the
+ <code class="command">GET STACKED DIAGNOSTICS</code> command, which has the form:
+
+</p><pre class="synopsis">
+GET STACKED DIAGNOSTICS <em class="replaceable"><code>variable</code></em> { = | := } <em class="replaceable"><code>item</code></em> [<span class="optional"> , ... </span>];
+</pre><p>
+
+ Each <em class="replaceable"><code>item</code></em> is a key word identifying a status
+ value to be assigned to the specified <em class="replaceable"><code>variable</code></em>
+ (which should be of the right data type to receive it). The currently
+ available status items are shown
+ in <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-EXCEPTION-DIAGNOSTICS-VALUES" title="Table 43.2. Error Diagnostics Items">Table 43.2</a>.
+ </p><div class="table" id="PLPGSQL-EXCEPTION-DIAGNOSTICS-VALUES"><p class="title"><strong>Table 43.2. Error Diagnostics Items</strong></p><div class="table-contents"><table class="table" summary="Error Diagnostics Items" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">RETURNED_SQLSTATE</code></td><td><code class="type">text</code></td><td>the SQLSTATE error code of the exception</td></tr><tr><td><code class="literal">COLUMN_NAME</code></td><td><code class="type">text</code></td><td>the name of the column related to exception</td></tr><tr><td><code class="literal">CONSTRAINT_NAME</code></td><td><code class="type">text</code></td><td>the name of the constraint related to exception</td></tr><tr><td><code class="literal">PG_DATATYPE_NAME</code></td><td><code class="type">text</code></td><td>the name of the data type related to exception</td></tr><tr><td><code class="literal">MESSAGE_TEXT</code></td><td><code class="type">text</code></td><td>the text of the exception's primary message</td></tr><tr><td><code class="literal">TABLE_NAME</code></td><td><code class="type">text</code></td><td>the name of the table related to exception</td></tr><tr><td><code class="literal">SCHEMA_NAME</code></td><td><code class="type">text</code></td><td>the name of the schema related to exception</td></tr><tr><td><code class="literal">PG_EXCEPTION_DETAIL</code></td><td><code class="type">text</code></td><td>the text of the exception's detail message, if any</td></tr><tr><td><code class="literal">PG_EXCEPTION_HINT</code></td><td><code class="type">text</code></td><td>the text of the exception's hint message, if any</td></tr><tr><td><code class="literal">PG_EXCEPTION_CONTEXT</code></td><td><code class="type">text</code></td><td>line(s) of text describing the call stack at the time of the
+ exception (see <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-CALL-STACK" title="43.6.9. Obtaining Execution Location Information">Section 43.6.9</a>)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ If the exception did not set a value for an item, an empty string
+ will be returned.
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+DECLARE
+ text_var1 text;
+ text_var2 text;
+ text_var3 text;
+BEGIN
+ -- some processing which might cause an exception
+ ...
+EXCEPTION WHEN OTHERS THEN
+ GET STACKED DIAGNOSTICS text_var1 = MESSAGE_TEXT,
+ text_var2 = PG_EXCEPTION_DETAIL,
+ text_var3 = PG_EXCEPTION_HINT;
+END;
+</pre><p>
+ </p></div></div><div class="sect2" id="PLPGSQL-CALL-STACK"><div class="titlepage"><div><div><h3 class="title">43.6.9. Obtaining Execution Location Information</h3></div></div></div><p>
+ The <code class="command">GET DIAGNOSTICS</code> command, previously described
+ in <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS" title="43.5.5. Obtaining the Result Status">Section 43.5.5</a>, retrieves information
+ about current execution state (whereas the <code class="command">GET STACKED
+ DIAGNOSTICS</code> command discussed above reports information about
+ the execution state as of a previous error). Its <code class="literal">PG_CONTEXT</code>
+ status item is useful for identifying the current execution
+ location. <code class="literal">PG_CONTEXT</code> returns a text string with line(s)
+ of text describing the call stack. The first line refers to the current
+ function and currently executing <code class="command">GET DIAGNOSTICS</code>
+ command. The second and any subsequent lines refer to calling functions
+ further up the call stack. For example:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION outer_func() RETURNS integer AS $$
+BEGIN
+ RETURN inner_func();
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION inner_func() RETURNS integer AS $$
+DECLARE
+ stack text;
+BEGIN
+ GET DIAGNOSTICS stack = PG_CONTEXT;
+ RAISE NOTICE E'--- Call Stack ---\n%', stack;
+ RETURN 1;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT outer_func();
+
+NOTICE: --- Call Stack ---
+PL/pgSQL function inner_func() line 5 at GET DIAGNOSTICS
+PL/pgSQL function outer_func() line 3 at RETURN
+CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN
+ outer_func
+ ------------
+ 1
+(1 row)
+</pre><p>
+
+ </p><p>
+ <code class="literal">GET STACKED DIAGNOSTICS ... PG_EXCEPTION_CONTEXT</code>
+ returns the same sort of stack trace, but describing the location
+ at which an error was detected, rather than the current location.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-statements.html" title="43.5. Basic Statements">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-cursors.html" title="43.7. Cursors">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.5. Basic Statements </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.7. Cursors</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-cursors.html b/doc/src/sgml/html/plpgsql-cursors.html
new file mode 100644
index 0000000..9c5dfc0
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-cursors.html
@@ -0,0 +1,386 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.7. Cursors</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-control-structures.html" title="43.6. Control Structures" /><link rel="next" href="plpgsql-transactions.html" title="43.8. Transaction Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.7. Cursors</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-control-structures.html" title="43.6. Control Structures">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-transactions.html" title="43.8. Transaction Management">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-CURSORS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.7. Cursors</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-DECLARATIONS">43.7.1. Declaring Cursor Variables</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-OPENING">43.7.2. Opening Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-USING">43.7.3. Using Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP">43.7.4. Looping through a Cursor's Result</a></span></dt></dl></div><a id="id-1.8.8.9.2" class="indexterm"></a><p>
+ Rather than executing a whole query at once, it is possible to set
+ up a <em class="firstterm">cursor</em> that encapsulates the query, and then read
+ the query result a few rows at a time. One reason for doing this is
+ to avoid memory overrun when the result contains a large number of
+ rows. (However, <span class="application">PL/pgSQL</span> users do not normally need
+ to worry about that, since <code class="literal">FOR</code> loops automatically use a cursor
+ internally to avoid memory problems.) A more interesting usage is to
+ return a reference to a cursor that a function has created, allowing the
+ caller to read the rows. This provides an efficient way to return
+ large row sets from functions.
+ </p><div class="sect2" id="PLPGSQL-CURSOR-DECLARATIONS"><div class="titlepage"><div><div><h3 class="title">43.7.1. Declaring Cursor Variables</h3></div></div></div><p>
+ All access to cursors in <span class="application">PL/pgSQL</span> goes through
+ cursor variables, which are always of the special data type
+ <code class="type">refcursor</code>. One way to create a cursor variable
+ is just to declare it as a variable of type <code class="type">refcursor</code>.
+ Another way is to use the cursor declaration syntax,
+ which in general is:
+</p><pre class="synopsis">
+<em class="replaceable"><code>name</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] CURSOR [<span class="optional"> ( <em class="replaceable"><code>arguments</code></em> ) </span>] FOR <em class="replaceable"><code>query</code></em>;
+</pre><p>
+ (<code class="literal">FOR</code> can be replaced by <code class="literal">IS</code> for
+ <span class="productname">Oracle</span> compatibility.)
+ If <code class="literal">SCROLL</code> is specified, the cursor will be capable of
+ scrolling backward; if <code class="literal">NO SCROLL</code> is specified, backward
+ fetches will be rejected; if neither specification appears, it is
+ query-dependent whether backward fetches will be allowed.
+ <em class="replaceable"><code>arguments</code></em>, if specified, is a
+ comma-separated list of pairs <code class="literal"><em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>datatype</code></em></code> that define names to be
+ replaced by parameter values in the given query. The actual
+ values to substitute for these names will be specified later,
+ when the cursor is opened.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+DECLARE
+ curs1 refcursor;
+ curs2 CURSOR FOR SELECT * FROM tenk1;
+ curs3 CURSOR (key integer) FOR SELECT * FROM tenk1 WHERE unique1 = key;
+</pre><p>
+ All three of these variables have the data type <code class="type">refcursor</code>,
+ but the first can be used with any query, while the second has
+ a fully specified query already <em class="firstterm">bound</em> to it, and the last
+ has a parameterized query bound to it. (<code class="literal">key</code> will be
+ replaced by an integer parameter value when the cursor is opened.)
+ The variable <code class="literal">curs1</code>
+ is said to be <em class="firstterm">unbound</em> since it is not bound to
+ any particular query.
+ </p><p>
+ The <code class="literal">SCROLL</code> option cannot be used when the cursor's
+ query uses <code class="literal">FOR UPDATE/SHARE</code>. Also, it is
+ best to use <code class="literal">NO SCROLL</code> with a query that involves
+ volatile functions. The implementation of <code class="literal">SCROLL</code>
+ assumes that re-reading the query's output will give consistent
+ results, which a volatile function might not do.
+ </p></div><div class="sect2" id="PLPGSQL-CURSOR-OPENING"><div class="titlepage"><div><div><h3 class="title">43.7.2. Opening Cursors</h3></div></div></div><p>
+ Before a cursor can be used to retrieve rows, it must be
+ <em class="firstterm">opened</em>. (This is the equivalent action to the SQL
+ command <code class="command">DECLARE CURSOR</code>.) <span class="application">PL/pgSQL</span> has
+ three forms of the <code class="command">OPEN</code> statement, two of which use unbound
+ cursor variables while the third uses a bound cursor variable.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Bound cursor variables can also be used without explicitly opening the cursor,
+ via the <code class="command">FOR</code> statement described in
+ <a class="xref" href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP" title="43.7.4. Looping through a Cursor's Result">Section 43.7.4</a>.
+ </p></div><div class="sect3" id="id-1.8.8.9.5.4"><div class="titlepage"><div><div><h4 class="title">43.7.2.1. <code class="command">OPEN FOR</code> <em class="replaceable"><code>query</code></em></h4></div></div></div><pre class="synopsis">
+OPEN <em class="replaceable"><code>unbound_cursorvar</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] FOR <em class="replaceable"><code>query</code></em>;
+</pre><p>
+ The cursor variable is opened and given the specified query to
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor variable (that is, as a simple
+ <code class="type">refcursor</code> variable). The query must be a
+ <code class="command">SELECT</code>, or something else that returns rows
+ (such as <code class="command">EXPLAIN</code>). The query
+ is treated in the same way as other SQL commands in
+ <span class="application">PL/pgSQL</span>: <span class="application">PL/pgSQL</span>
+ variable names are substituted, and the query plan is cached for
+ possible reuse. When a <span class="application">PL/pgSQL</span>
+ variable is substituted into the cursor query, the value that is
+ substituted is the one it has at the time of the <code class="command">OPEN</code>;
+ subsequent changes to the variable will not affect the cursor's
+ behavior.
+ The <code class="literal">SCROLL</code> and <code class="literal">NO SCROLL</code>
+ options have the same meanings as for a bound cursor.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.9.5.5"><div class="titlepage"><div><div><h4 class="title">43.7.2.2. <code class="command">OPEN FOR EXECUTE</code></h4></div></div></div><pre class="synopsis">
+OPEN <em class="replaceable"><code>unbound_cursorvar</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] FOR EXECUTE <em class="replaceable"><code>query_string</code></em>
+ [<span class="optional"> USING <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+</pre><p>
+ The cursor variable is opened and given the specified query to
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor variable (that is, as a simple
+ <code class="type">refcursor</code> variable). The query is specified as a string
+ expression, in the same way as in the <code class="command">EXECUTE</code>
+ command. As usual, this gives flexibility so the query plan can vary
+ from one run to the next (see <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="43.11.2. Plan Caching">Section 43.11.2</a>),
+ and it also means that variable substitution is not done on the
+ command string. As with <code class="command">EXECUTE</code>, parameter values
+ can be inserted into the dynamic command via
+ <code class="literal">format()</code> and <code class="literal">USING</code>.
+ The <code class="literal">SCROLL</code> and
+ <code class="literal">NO SCROLL</code> options have the same meanings as for a bound
+ cursor.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING keyvalue;
+</pre><p>
+ In this example, the table name is inserted into the query via
+ <code class="function">format()</code>. The comparison value for <code class="literal">col1</code>
+ is inserted via a <code class="literal">USING</code> parameter, so it needs
+ no quoting.
+ </p></div><div class="sect3" id="PLPGSQL-OPEN-BOUND-CURSOR"><div class="titlepage"><div><div><h4 class="title">43.7.2.3. Opening a Bound Cursor</h4></div></div></div><pre class="synopsis">
+OPEN <em class="replaceable"><code>bound_cursorvar</code></em> [<span class="optional"> ( [<span class="optional"> <em class="replaceable"><code>argument_name</code></em> := </span>] <em class="replaceable"><code>argument_value</code></em> [<span class="optional">, ...</span>] ) </span>];
+</pre><p>
+ This form of <code class="command">OPEN</code> is used to open a cursor
+ variable whose query was bound to it when it was declared. The
+ cursor cannot be open already. A list of actual argument value
+ expressions must appear if and only if the cursor was declared to
+ take arguments. These values will be substituted in the query.
+ </p><p>
+ The query plan for a bound cursor is always considered cacheable;
+ there is no equivalent of <code class="command">EXECUTE</code> in this case.
+ Notice that <code class="literal">SCROLL</code> and <code class="literal">NO SCROLL</code> cannot be
+ specified in <code class="command">OPEN</code>, as the cursor's scrolling
+ behavior was already determined.
+ </p><p>
+ Argument values can be passed using either <em class="firstterm">positional</em>
+ or <em class="firstterm">named</em> notation. In positional
+ notation, all arguments are specified in order. In named notation,
+ each argument's name is specified using <code class="literal">:=</code> to
+ separate it from the argument expression. Similar to calling
+ functions, described in <a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a>, it
+ is also allowed to mix positional and named notation.
+ </p><p>
+ Examples (these use the cursor declaration examples above):
+</p><pre class="programlisting">
+OPEN curs2;
+OPEN curs3(42);
+OPEN curs3(key := 42);
+</pre><p>
+ </p><p>
+ Because variable substitution is done on a bound cursor's query,
+ there are really two ways to pass values into the cursor: either
+ with an explicit argument to <code class="command">OPEN</code>, or implicitly by
+ referencing a <span class="application">PL/pgSQL</span> variable in the query.
+ However, only variables declared before the bound cursor was
+ declared will be substituted into it. In either case the value to
+ be passed is determined at the time of the <code class="command">OPEN</code>.
+ For example, another way to get the same effect as the
+ <code class="literal">curs3</code> example above is
+</p><pre class="programlisting">
+DECLARE
+ key integer;
+ curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
+BEGIN
+ key := 42;
+ OPEN curs4;
+</pre><p>
+ </p></div></div><div class="sect2" id="PLPGSQL-CURSOR-USING"><div class="titlepage"><div><div><h3 class="title">43.7.3. Using Cursors</h3></div></div></div><p>
+ Once a cursor has been opened, it can be manipulated with the
+ statements described here.
+ </p><p>
+ These manipulations need not occur in the same function that
+ opened the cursor to begin with. You can return a <code class="type">refcursor</code>
+ value out of a function and let the caller operate on the cursor.
+ (Internally, a <code class="type">refcursor</code> value is simply the string name
+ of a so-called portal containing the active query for the cursor. This name
+ can be passed around, assigned to other <code class="type">refcursor</code> variables,
+ and so on, without disturbing the portal.)
+ </p><p>
+ All portals are implicitly closed at transaction end. Therefore
+ a <code class="type">refcursor</code> value is usable to reference an open cursor
+ only until the end of the transaction.
+ </p><div class="sect3" id="id-1.8.8.9.6.5"><div class="titlepage"><div><div><h4 class="title">43.7.3.1. <code class="literal">FETCH</code></h4></div></div></div><pre class="synopsis">
+FETCH [<span class="optional"> <em class="replaceable"><code>direction</code></em> { FROM | IN } </span>] <em class="replaceable"><code>cursor</code></em> INTO <em class="replaceable"><code>target</code></em>;
+</pre><p>
+ <code class="command">FETCH</code> retrieves the next row from the
+ cursor into a target, which might be a row variable, a record
+ variable, or a comma-separated list of simple variables, just like
+ <code class="command">SELECT INTO</code>. If there is no next row, the
+ target is set to NULL(s). As with <code class="command">SELECT
+ INTO</code>, the special variable <code class="literal">FOUND</code> can
+ be checked to see whether a row was obtained or not.
+ </p><p>
+ The <em class="replaceable"><code>direction</code></em> clause can be any of the
+ variants allowed in the SQL <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>
+ command except the ones that can fetch
+ more than one row; namely, it can be
+ <code class="literal">NEXT</code>,
+ <code class="literal">PRIOR</code>,
+ <code class="literal">FIRST</code>,
+ <code class="literal">LAST</code>,
+ <code class="literal">ABSOLUTE</code> <em class="replaceable"><code>count</code></em>,
+ <code class="literal">RELATIVE</code> <em class="replaceable"><code>count</code></em>,
+ <code class="literal">FORWARD</code>, or
+ <code class="literal">BACKWARD</code>.
+ Omitting <em class="replaceable"><code>direction</code></em> is the same
+ as specifying <code class="literal">NEXT</code>.
+ In the forms using a <em class="replaceable"><code>count</code></em>,
+ the <em class="replaceable"><code>count</code></em> can be any integer-valued
+ expression (unlike the SQL <code class="command">FETCH</code> command,
+ which only allows an integer constant).
+ <em class="replaceable"><code>direction</code></em> values that require moving
+ backward are likely to fail unless the cursor was declared or opened
+ with the <code class="literal">SCROLL</code> option.
+ </p><p>
+ <em class="replaceable"><code>cursor</code></em> must be the name of a <code class="type">refcursor</code>
+ variable that references an open cursor portal.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+FETCH curs1 INTO rowvar;
+FETCH curs2 INTO foo, bar, baz;
+FETCH LAST FROM curs3 INTO x, y;
+FETCH RELATIVE -2 FROM curs4 INTO x;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.9.6.6"><div class="titlepage"><div><div><h4 class="title">43.7.3.2. <code class="literal">MOVE</code></h4></div></div></div><pre class="synopsis">
+MOVE [<span class="optional"> <em class="replaceable"><code>direction</code></em> { FROM | IN } </span>] <em class="replaceable"><code>cursor</code></em>;
+</pre><p>
+ <code class="command">MOVE</code> repositions a cursor without retrieving
+ any data. <code class="command">MOVE</code> works exactly like the
+ <code class="command">FETCH</code> command, except it only repositions the
+ cursor and does not return the row moved to. As with <code class="command">SELECT
+ INTO</code>, the special variable <code class="literal">FOUND</code> can
+ be checked to see whether there was a next row to move to.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+MOVE curs1;
+MOVE LAST FROM curs3;
+MOVE RELATIVE -2 FROM curs4;
+MOVE FORWARD 2 FROM curs4;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.9.6.7"><div class="titlepage"><div><div><h4 class="title">43.7.3.3. <code class="literal">UPDATE/DELETE WHERE CURRENT OF</code></h4></div></div></div><pre class="synopsis">
+UPDATE <em class="replaceable"><code>table</code></em> SET ... WHERE CURRENT OF <em class="replaceable"><code>cursor</code></em>;
+DELETE FROM <em class="replaceable"><code>table</code></em> WHERE CURRENT OF <em class="replaceable"><code>cursor</code></em>;
+</pre><p>
+ When a cursor is positioned on a table row, that row can be updated
+ or deleted using the cursor to identify the row. There are
+ restrictions on what the cursor's query can be (in particular,
+ no grouping) and it's best to use <code class="literal">FOR UPDATE</code> in the
+ cursor. For more information see the
+ <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>
+ reference page.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.9.6.8"><div class="titlepage"><div><div><h4 class="title">43.7.3.4. <code class="literal">CLOSE</code></h4></div></div></div><pre class="synopsis">
+CLOSE <em class="replaceable"><code>cursor</code></em>;
+</pre><p>
+ <code class="command">CLOSE</code> closes the portal underlying an open
+ cursor. This can be used to release resources earlier than end of
+ transaction, or to free up the cursor variable to be opened again.
+ </p><p>
+ An example:
+</p><pre class="programlisting">
+CLOSE curs1;
+</pre><p>
+ </p></div><div class="sect3" id="id-1.8.8.9.6.9"><div class="titlepage"><div><div><h4 class="title">43.7.3.5. Returning Cursors</h4></div></div></div><p>
+ <span class="application">PL/pgSQL</span> functions can return cursors to the
+ caller. This is useful to return multiple rows or columns,
+ especially with very large result sets. To do this, the function
+ opens the cursor and returns the cursor name to the caller (or simply
+ opens the cursor using a portal name specified by or otherwise known
+ to the caller). The caller can then fetch rows from the cursor. The
+ cursor can be closed by the caller, or it will be closed automatically
+ when the transaction closes.
+ </p><p>
+ The portal name used for a cursor can be specified by the
+ programmer or automatically generated. To specify a portal name,
+ simply assign a string to the <code class="type">refcursor</code> variable before
+ opening it. The string value of the <code class="type">refcursor</code> variable
+ will be used by <code class="command">OPEN</code> as the name of the underlying portal.
+ However, if the <code class="type">refcursor</code> variable is null,
+ <code class="command">OPEN</code> automatically generates a name that does not
+ conflict with any existing portal, and assigns it to the
+ <code class="type">refcursor</code> variable.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A bound cursor variable is initialized to the string value
+ representing its name, so that the portal name is the same as
+ the cursor variable name, unless the programmer overrides it
+ by assignment before opening the cursor. But an unbound cursor
+ variable defaults to the null value initially, so it will receive
+ an automatically-generated unique name, unless overridden.
+ </p></div><p>
+ The following example shows one way a cursor name can be supplied by
+ the caller:
+
+</p><pre class="programlisting">
+CREATE TABLE test (col text);
+INSERT INTO test VALUES ('123');
+
+CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS '
+BEGIN
+ OPEN $1 FOR SELECT col FROM test;
+ RETURN $1;
+END;
+' LANGUAGE plpgsql;
+
+BEGIN;
+SELECT reffunc('funccursor');
+FETCH ALL IN funccursor;
+COMMIT;
+</pre><p>
+ </p><p>
+ The following example uses automatic cursor name generation:
+
+</p><pre class="programlisting">
+CREATE FUNCTION reffunc2() RETURNS refcursor AS '
+DECLARE
+ ref refcursor;
+BEGIN
+ OPEN ref FOR SELECT col FROM test;
+ RETURN ref;
+END;
+' LANGUAGE plpgsql;
+
+-- need to be in a transaction to use cursors.
+BEGIN;
+SELECT reffunc2();
+
+ reffunc2
+--------------------
+ &lt;unnamed cursor 1&gt;
+(1 row)
+
+FETCH ALL IN "&lt;unnamed cursor 1&gt;";
+COMMIT;
+</pre><p>
+ </p><p>
+ The following example shows one way to return multiple cursors
+ from a single function:
+
+</p><pre class="programlisting">
+CREATE FUNCTION myfunc(refcursor, refcursor) RETURNS SETOF refcursor AS $$
+BEGIN
+ OPEN $1 FOR SELECT * FROM table_1;
+ RETURN NEXT $1;
+ OPEN $2 FOR SELECT * FROM table_2;
+ RETURN NEXT $2;
+END;
+$$ LANGUAGE plpgsql;
+
+-- need to be in a transaction to use cursors.
+BEGIN;
+
+SELECT * FROM myfunc('a', 'b');
+
+FETCH ALL FROM a;
+FETCH ALL FROM b;
+COMMIT;
+</pre><p>
+ </p></div></div><div class="sect2" id="PLPGSQL-CURSOR-FOR-LOOP"><div class="titlepage"><div><div><h3 class="title">43.7.4. Looping through a Cursor's Result</h3></div></div></div><p>
+ There is a variant of the <code class="command">FOR</code> statement that allows
+ iterating through the rows returned by a cursor. The syntax is:
+
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+FOR <em class="replaceable"><code>recordvar</code></em> IN <em class="replaceable"><code>bound_cursorvar</code></em> [<span class="optional"> ( [<span class="optional"> <em class="replaceable"><code>argument_name</code></em> := </span>] <em class="replaceable"><code>argument_value</code></em> [<span class="optional">, ...</span>] ) </span>] LOOP
+ <em class="replaceable"><code>statements</code></em>
+END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+
+ The cursor variable must have been bound to some query when it was
+ declared, and it <span class="emphasis"><em>cannot</em></span> be open already. The
+ <code class="command">FOR</code> statement automatically opens the cursor, and it closes
+ the cursor again when the loop exits. A list of actual argument value
+ expressions must appear if and only if the cursor was declared to take
+ arguments. These values will be substituted in the query, in just
+ the same way as during an <code class="command">OPEN</code> (see <a class="xref" href="plpgsql-cursors.html#PLPGSQL-OPEN-BOUND-CURSOR" title="43.7.2.3. Opening a Bound Cursor">Section 43.7.2.3</a>).
+ </p><p>
+ The variable <em class="replaceable"><code>recordvar</code></em> is automatically
+ defined as type <code class="type">record</code> and exists only inside the loop (any
+ existing definition of the variable name is ignored within the loop).
+ Each row returned by the cursor is successively assigned to this
+ record variable and the loop body is executed.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-control-structures.html" title="43.6. Control Structures">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-transactions.html" title="43.8. Transaction Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.6. Control Structures </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.8. Transaction Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-declarations.html b/doc/src/sgml/html/plpgsql-declarations.html
new file mode 100644
index 0000000..6e208cf
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-declarations.html
@@ -0,0 +1,464 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.3. Declarations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL" /><link rel="next" href="plpgsql-expressions.html" title="43.4. Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.3. Declarations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-expressions.html" title="43.4. Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-DECLARATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.3. Declarations</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS">43.3.1. Declaring Function Parameters</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-ALIAS">43.3.2. <code class="literal">ALIAS</code></a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-TYPE">43.3.3. Copying Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-ROWTYPES">43.3.4. Row Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-RECORDS">43.3.5. Record Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-COLLATION">43.3.6. Collation of <span class="application">PL/pgSQL</span> Variables</a></span></dt></dl></div><p>
+ All variables used in a block must be declared in the
+ declarations section of the block.
+ (The only exceptions are that the loop variable of a <code class="literal">FOR</code> loop
+ iterating over a range of integer values is automatically declared as an
+ integer variable, and likewise the loop variable of a <code class="literal">FOR</code> loop
+ iterating over a cursor's result is automatically declared as a
+ record variable.)
+ </p><p>
+ <span class="application">PL/pgSQL</span> variables can have any SQL data type, such as
+ <code class="type">integer</code>, <code class="type">varchar</code>, and
+ <code class="type">char</code>.
+ </p><p>
+ Here are some examples of variable declarations:
+</p><pre class="programlisting">
+user_id integer;
+quantity numeric(5);
+url varchar;
+myrow tablename%ROWTYPE;
+myfield tablename.columnname%TYPE;
+arow RECORD;
+</pre><p>
+ </p><p>
+ The general syntax of a variable declaration is:
+</p><pre class="synopsis">
+<em class="replaceable"><code>name</code></em> [<span class="optional"> CONSTANT </span>] <em class="replaceable"><code>type</code></em> [<span class="optional"> COLLATE <em class="replaceable"><code>collation_name</code></em> </span>] [<span class="optional"> NOT NULL </span>] [<span class="optional"> { DEFAULT | := | = } <em class="replaceable"><code>expression</code></em> </span>];
+</pre><p>
+ The <code class="literal">DEFAULT</code> clause, if given, specifies the initial value assigned
+ to the variable when the block is entered. If the <code class="literal">DEFAULT</code> clause
+ is not given then the variable is initialized to the
+ <acronym class="acronym">SQL</acronym> null value.
+ The <code class="literal">CONSTANT</code> option prevents the variable from being
+ assigned to after initialization, so that its value will remain constant
+ for the duration of the block.
+ The <code class="literal">COLLATE</code> option specifies a collation to use for the
+ variable (see <a class="xref" href="plpgsql-declarations.html#PLPGSQL-DECLARATION-COLLATION" title="43.3.6. Collation of PL/pgSQL Variables">Section 43.3.6</a>).
+ If <code class="literal">NOT NULL</code>
+ is specified, an assignment of a null value results in a run-time
+ error. All variables declared as <code class="literal">NOT NULL</code>
+ must have a nonnull default value specified.
+ Equal (<code class="literal">=</code>) can be used instead of PL/SQL-compliant
+ <code class="literal">:=</code>.
+ </p><p>
+ A variable's default value is evaluated and assigned to the variable
+ each time the block is entered (not just once per function call).
+ So, for example, assigning <code class="literal">now()</code> to a variable of type
+ <code class="type">timestamp</code> causes the variable to have the
+ time of the current function call, not the time when the function was
+ precompiled.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+quantity integer DEFAULT 32;
+url varchar := 'http://mysite.com';
+transaction_time CONSTANT timestamp with time zone := now();
+</pre><p>
+ </p><p>
+ Once declared, a variable's value can be used in later initialization
+ expressions in the same block, for example:
+</p><pre class="programlisting">
+DECLARE
+ x integer := 1;
+ y integer := x + 1;
+</pre><p>
+ </p><div class="sect2" id="PLPGSQL-DECLARATION-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">43.3.1. Declaring Function Parameters</h3></div></div></div><p>
+ Parameters passed to functions are named with the identifiers
+ <code class="literal">$1</code>, <code class="literal">$2</code>,
+ etc. Optionally, aliases can be declared for
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code>
+ parameter names for increased readability. Either the alias or the
+ numeric identifier can then be used to refer to the parameter value.
+ </p><p>
+ There are two ways to create an alias. The preferred way is to give a
+ name to the parameter in the <code class="command">CREATE FUNCTION</code> command,
+ for example:
+</p><pre class="programlisting">
+CREATE FUNCTION sales_tax(subtotal real) RETURNS real AS $$
+BEGIN
+ RETURN subtotal * 0.06;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ The other way is to explicitly declare an alias, using the
+ declaration syntax
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>name</code></em> ALIAS FOR $<em class="replaceable"><code>n</code></em>;
+</pre><p>
+
+ The same example in this style looks like:
+</p><pre class="programlisting">
+CREATE FUNCTION sales_tax(real) RETURNS real AS $$
+DECLARE
+ subtotal ALIAS FOR $1;
+BEGIN
+ RETURN subtotal * 0.06;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ These two examples are not perfectly equivalent. In the first case,
+ <code class="literal">subtotal</code> could be referenced as
+ <code class="literal">sales_tax.subtotal</code>, but in the second case it could not.
+ (Had we attached a label to the inner block, <code class="literal">subtotal</code> could
+ be qualified with that label, instead.)
+ </p></div><p>
+ Some more examples:
+</p><pre class="programlisting">
+CREATE FUNCTION instr(varchar, integer) RETURNS integer AS $$
+DECLARE
+ v_string ALIAS FOR $1;
+ index ALIAS FOR $2;
+BEGIN
+ -- some computations using v_string and index here
+END;
+$$ LANGUAGE plpgsql;
+
+
+CREATE FUNCTION concat_selected_fields(in_t sometablename) RETURNS text AS $$
+BEGIN
+ RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ When a <span class="application">PL/pgSQL</span> function is declared
+ with output parameters, the output parameters are given
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code> names and optional
+ aliases in just the same way as the normal input parameters. An
+ output parameter is effectively a variable that starts out NULL;
+ it should be assigned to during the execution of the function.
+ The final value of the parameter is what is returned. For instance,
+ the sales-tax example could also be done this way:
+
+</p><pre class="programlisting">
+CREATE FUNCTION sales_tax(subtotal real, OUT tax real) AS $$
+BEGIN
+ tax := subtotal * 0.06;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ Notice that we omitted <code class="literal">RETURNS real</code> — we could have
+ included it, but it would be redundant.
+ </p><p>
+ To call a function with <code class="literal">OUT</code> parameters, omit the
+ output parameter(s) in the function call:
+</p><pre class="programlisting">
+SELECT sales_tax(100.00);
+</pre><p>
+ </p><p>
+ Output parameters are most useful when returning multiple values.
+ A trivial example is:
+
+</p><pre class="programlisting">
+CREATE FUNCTION sum_n_product(x int, y int, OUT sum int, OUT prod int) AS $$
+BEGIN
+ sum := x + y;
+ prod := x * y;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT * FROM sum_n_product(2, 4);
+ sum | prod
+-----+------
+ 6 | 8
+</pre><p>
+
+ As discussed in <a class="xref" href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS" title="38.5.4. SQL Functions with Output Parameters">Section 38.5.4</a>, this
+ effectively creates an anonymous record type for the function's
+ results. If a <code class="literal">RETURNS</code> clause is given, it must say
+ <code class="literal">RETURNS record</code>.
+ </p><p>
+ This also works with procedures, for example:
+
+</p><pre class="programlisting">
+CREATE PROCEDURE sum_n_product(x int, y int, OUT sum int, OUT prod int) AS $$
+BEGIN
+ sum := x + y;
+ prod := x * y;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ In a call to a procedure, all the parameters must be specified. For
+ output parameters, <code class="literal">NULL</code> may be specified when
+ calling the procedure from plain SQL:
+</p><pre class="programlisting">
+CALL sum_n_product(2, 4, NULL, NULL);
+ sum | prod
+-----+------
+ 6 | 8
+</pre><p>
+
+ However, when calling a procedure
+ from <span class="application">PL/pgSQL</span>, you should instead write a
+ variable for any output parameter; the variable will receive the result
+ of the call. See <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE" title="43.6.3. Calling a Procedure">Section 43.6.3</a>
+ for details.
+ </p><p>
+ Another way to declare a <span class="application">PL/pgSQL</span> function
+ is with <code class="literal">RETURNS TABLE</code>, for example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION extended_sales(p_itemno int)
+RETURNS TABLE(quantity int, total numeric) AS $$
+BEGIN
+ RETURN QUERY SELECT s.quantity, s.quantity * s.price FROM sales AS s
+ WHERE s.itemno = p_itemno;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ This is exactly equivalent to declaring one or more <code class="literal">OUT</code>
+ parameters and specifying <code class="literal">RETURNS SETOF
+ <em class="replaceable"><code>sometype</code></em></code>.
+ </p><p>
+ When the return type of a <span class="application">PL/pgSQL</span> function
+ is declared as a polymorphic type (see
+ <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>), a special
+ parameter <code class="literal">$0</code> is created. Its data type is the actual
+ return type of the function, as deduced from the actual input types.
+ This allows the function to access its actual return type
+ as shown in <a class="xref" href="plpgsql-declarations.html#PLPGSQL-DECLARATION-TYPE" title="43.3.3. Copying Types">Section 43.3.3</a>.
+ <code class="literal">$0</code> is initialized to null and can be modified by
+ the function, so it can be used to hold the return value if desired,
+ though that is not required. <code class="literal">$0</code> can also be
+ given an alias. For example, this function works on any data type
+ that has a <code class="literal">+</code> operator:
+
+</p><pre class="programlisting">
+CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement)
+RETURNS anyelement AS $$
+DECLARE
+ result ALIAS FOR $0;
+BEGIN
+ result := v1 + v2 + v3;
+ RETURN result;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ The same effect can be obtained by declaring one or more output parameters as
+ polymorphic types. In this case the
+ special <code class="literal">$0</code> parameter is not used; the output
+ parameters themselves serve the same purpose. For example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement,
+ OUT sum anyelement)
+AS $$
+BEGIN
+ sum := v1 + v2 + v3;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ In practice it might be more useful to declare a polymorphic function
+ using the <code class="type">anycompatible</code> family of types, so that automatic
+ promotion of the input arguments to a common type will occur.
+ For example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION add_three_values(v1 anycompatible, v2 anycompatible, v3 anycompatible)
+RETURNS anycompatible AS $$
+BEGIN
+ RETURN v1 + v2 + v3;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ With this example, a call such as
+
+</p><pre class="programlisting">
+SELECT add_three_values(1, 2, 4.7);
+</pre><p>
+
+ will work, automatically promoting the integer inputs to numeric.
+ The function using <code class="type">anyelement</code> would require you to
+ cast the three inputs to the same type manually.
+ </p></div><div class="sect2" id="PLPGSQL-DECLARATION-ALIAS"><div class="titlepage"><div><div><h3 class="title">43.3.2. <code class="literal">ALIAS</code></h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>newname</code></em> ALIAS FOR <em class="replaceable"><code>oldname</code></em>;
+</pre><p>
+ The <code class="literal">ALIAS</code> syntax is more general than is suggested in the
+ previous section: you can declare an alias for any variable, not just
+ function parameters. The main practical use for this is to assign
+ a different name for variables with predetermined names, such as
+ <code class="varname">NEW</code> or <code class="varname">OLD</code> within
+ a trigger function.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+DECLARE
+ prior ALIAS FOR old;
+ updated ALIAS FOR new;
+</pre><p>
+ </p><p>
+ Since <code class="literal">ALIAS</code> creates two different ways to name the same
+ object, unrestricted use can be confusing. It's best to use it only
+ for the purpose of overriding predetermined names.
+ </p></div><div class="sect2" id="PLPGSQL-DECLARATION-TYPE"><div class="titlepage"><div><div><h3 class="title">43.3.3. Copying Types</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>variable</code></em>%TYPE
+</pre><p>
+ <code class="literal">%TYPE</code> provides the data type of a variable or
+ table column. You can use this to declare variables that will hold
+ database values. For example, let's say you have a column named
+ <code class="literal">user_id</code> in your <code class="literal">users</code>
+ table. To declare a variable with the same data type as
+ <code class="literal">users.user_id</code> you write:
+</p><pre class="programlisting">
+user_id users.user_id%TYPE;
+</pre><p>
+ </p><p>
+ By using <code class="literal">%TYPE</code> you don't need to know the data
+ type of the structure you are referencing, and most importantly,
+ if the data type of the referenced item changes in the future (for
+ instance: you change the type of <code class="literal">user_id</code>
+ from <code class="type">integer</code> to <code class="type">real</code>), you might not need
+ to change your function definition.
+ </p><p>
+ <code class="literal">%TYPE</code> is particularly valuable in polymorphic
+ functions, since the data types needed for internal variables can
+ change from one call to the next. Appropriate variables can be
+ created by applying <code class="literal">%TYPE</code> to the function's
+ arguments or result placeholders.
+ </p></div><div class="sect2" id="PLPGSQL-DECLARATION-ROWTYPES"><div class="titlepage"><div><div><h3 class="title">43.3.4. Row Types</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>name</code></em> <em class="replaceable"><code>table_name</code></em><code class="literal">%ROWTYPE</code>;
+<em class="replaceable"><code>name</code></em> <em class="replaceable"><code>composite_type_name</code></em>;
+</pre><p>
+ A variable of a composite type is called a <em class="firstterm">row</em>
+ variable (or <em class="firstterm">row-type</em> variable). Such a variable
+ can hold a whole row of a <code class="command">SELECT</code> or <code class="command">FOR</code>
+ query result, so long as that query's column set matches the
+ declared type of the variable.
+ The individual fields of the row value
+ are accessed using the usual dot notation, for example
+ <code class="literal">rowvar.field</code>.
+ </p><p>
+ A row variable can be declared to have the same type as the rows of
+ an existing table or view, by using the
+ <em class="replaceable"><code>table_name</code></em><code class="literal">%ROWTYPE</code>
+ notation; or it can be declared by giving a composite type's name.
+ (Since every table has an associated composite type of the same name,
+ it actually does not matter in <span class="productname">PostgreSQL</span> whether you
+ write <code class="literal">%ROWTYPE</code> or not. But the form with
+ <code class="literal">%ROWTYPE</code> is more portable.)
+ </p><p>
+ Parameters to a function can be
+ composite types (complete table rows). In that case, the
+ corresponding identifier <code class="literal">$<em class="replaceable"><code>n</code></em></code> will be a row variable, and fields can
+ be selected from it, for example <code class="literal">$1.user_id</code>.
+ </p><p>
+ Here is an example of using composite types. <code class="structname">table1</code>
+ and <code class="structname">table2</code> are existing tables having at least the
+ mentioned fields:
+
+</p><pre class="programlisting">
+CREATE FUNCTION merge_fields(t_row table1) RETURNS text AS $$
+DECLARE
+ t2_row table2%ROWTYPE;
+BEGIN
+ SELECT * INTO t2_row FROM table2 WHERE ... ;
+ RETURN t_row.f1 || t2_row.f3 || t_row.f5 || t2_row.f7;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT merge_fields(t.*) FROM table1 t WHERE ... ;
+</pre><p>
+ </p></div><div class="sect2" id="PLPGSQL-DECLARATION-RECORDS"><div class="titlepage"><div><div><h3 class="title">43.3.5. Record Types</h3></div></div></div><pre class="synopsis">
+<em class="replaceable"><code>name</code></em> RECORD;
+</pre><p>
+ Record variables are similar to row-type variables, but they have no
+ predefined structure. They take on the actual row structure of the
+ row they are assigned during a <code class="command">SELECT</code> or <code class="command">FOR</code> command. The substructure
+ of a record variable can change each time it is assigned to.
+ A consequence of this is that until a record variable is first assigned
+ to, it has no substructure, and any attempt to access a
+ field in it will draw a run-time error.
+ </p><p>
+ Note that <code class="literal">RECORD</code> is not a true data type, only a placeholder.
+ One should also realize that when a <span class="application">PL/pgSQL</span>
+ function is declared to return type <code class="type">record</code>, this is not quite the
+ same concept as a record variable, even though such a function might
+ use a record variable to hold its result. In both cases the actual row
+ structure is unknown when the function is written, but for a function
+ returning <code class="type">record</code> the actual structure is determined when the
+ calling query is parsed, whereas a record variable can change its row
+ structure on-the-fly.
+ </p></div><div class="sect2" id="PLPGSQL-DECLARATION-COLLATION"><div class="titlepage"><div><div><h3 class="title">43.3.6. Collation of <span class="application">PL/pgSQL</span> Variables</h3></div></div></div><a id="id-1.8.8.5.14.2" class="indexterm"></a><p>
+ When a <span class="application">PL/pgSQL</span> function has one or more
+ parameters of collatable data types, a collation is identified for each
+ function call depending on the collations assigned to the actual
+ arguments, as described in <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>. If a collation is
+ successfully identified (i.e., there are no conflicts of implicit
+ collations among the arguments) then all the collatable parameters are
+ treated as having that collation implicitly. This will affect the
+ behavior of collation-sensitive operations within the function.
+ For example, consider
+
+</p><pre class="programlisting">
+CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
+BEGIN
+ RETURN a &lt; b;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT less_than(text_field_1, text_field_2) FROM table1;
+SELECT less_than(text_field_1, text_field_2 COLLATE "C") FROM table1;
+</pre><p>
+
+ The first use of <code class="function">less_than</code> will use the common collation
+ of <code class="structfield">text_field_1</code> and <code class="structfield">text_field_2</code> for
+ the comparison, while the second use will use <code class="literal">C</code> collation.
+ </p><p>
+ Furthermore, the identified collation is also assumed as the collation of
+ any local variables that are of collatable types. Thus this function
+ would not work any differently if it were written as
+
+</p><pre class="programlisting">
+CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
+DECLARE
+ local_a text := a;
+ local_b text := b;
+BEGIN
+ RETURN local_a &lt; local_b;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ If there are no parameters of collatable data types, or no common
+ collation can be identified for them, then parameters and local variables
+ use the default collation of their data type (which is usually the
+ database's default collation, but could be different for variables of
+ domain types).
+ </p><p>
+ A local variable of a collatable data type can have a different collation
+ associated with it by including the <code class="literal">COLLATE</code> option in its
+ declaration, for example
+
+</p><pre class="programlisting">
+DECLARE
+ local_a text COLLATE "en_US";
+</pre><p>
+
+ This option overrides the collation that would otherwise be
+ given to the variable according to the rules above.
+ </p><p>
+ Also, of course explicit <code class="literal">COLLATE</code> clauses can be written inside
+ a function if it is desired to force a particular collation to be used in
+ a particular operation. For example,
+
+</p><pre class="programlisting">
+CREATE FUNCTION less_than_c(a text, b text) RETURNS boolean AS $$
+BEGIN
+ RETURN a &lt; b COLLATE "C";
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ This overrides the collations associated with the table columns,
+ parameters, or local variables used in the expression, just as would
+ happen in a plain SQL command.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-expressions.html" title="43.4. Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.2. Structure of <span class="application">PL/pgSQL</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.4. Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-development-tips.html b/doc/src/sgml/html/plpgsql-development-tips.html
new file mode 100644
index 0000000..afadc4e
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-development-tips.html
@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.12. Tips for Developing in PL/pgSQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood" /><link rel="next" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.12. Tips for Developing in <span class="application">PL/pgSQL</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-DEVELOPMENT-TIPS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.12. Tips for Developing in <span class="application">PL/pgSQL</span></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-development-tips.html#PLPGSQL-QUOTE-TIPS">43.12.1. Handling of Quotation Marks</a></span></dt><dt><span class="sect2"><a href="plpgsql-development-tips.html#PLPGSQL-EXTRA-CHECKS">43.12.2. Additional Compile-Time and Run-Time Checks</a></span></dt></dl></div><p>
+ One good way to develop in
+ <span class="application">PL/pgSQL</span> is to use the text editor of your
+ choice to create your functions, and in another window, use
+ <span class="application">psql</span> to load and test those functions.
+ If you are doing it this way, it
+ is a good idea to write the function using <code class="command">CREATE OR
+ REPLACE FUNCTION</code>. That way you can just reload the file to update
+ the function definition. For example:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS $$
+ ....
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ While running <span class="application">psql</span>, you can load or reload such
+ a function definition file with:
+</p><pre class="programlisting">
+\i filename.sql
+</pre><p>
+ and then immediately issue SQL commands to test the function.
+ </p><p>
+ Another good way to develop in <span class="application">PL/pgSQL</span> is with a
+ GUI database access tool that facilitates development in a
+ procedural language. One example of such a tool is
+ <span class="application">pgAdmin</span>, although others exist. These tools often
+ provide convenient features such as escaping single quotes and
+ making it easier to recreate and debug functions.
+ </p><div class="sect2" id="PLPGSQL-QUOTE-TIPS"><div class="titlepage"><div><div><h3 class="title">43.12.1. Handling of Quotation Marks</h3></div></div></div><p>
+ The code of a <span class="application">PL/pgSQL</span> function is specified in
+ <code class="command">CREATE FUNCTION</code> as a string literal. If you
+ write the string literal in the ordinary way with surrounding
+ single quotes, then any single quotes inside the function body
+ must be doubled; likewise any backslashes must be doubled (assuming
+ escape string syntax is used).
+ Doubling quotes is at best tedious, and in more complicated cases
+ the code can become downright incomprehensible, because you can
+ easily find yourself needing half a dozen or more adjacent quote marks.
+ It's recommended that you instead write the function body as a
+ <span class="quote">“<span class="quote">dollar-quoted</span>”</span> string literal (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>). In the dollar-quoting
+ approach, you never double any quote marks, but instead take care to
+ choose a different dollar-quoting delimiter for each level of
+ nesting you need. For example, you might write the <code class="command">CREATE
+ FUNCTION</code> command as:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS $PROC$
+ ....
+$PROC$ LANGUAGE plpgsql;
+</pre><p>
+ Within this, you might use quote marks for simple literal strings in
+ SQL commands and <code class="literal">$$</code> to delimit fragments of SQL commands
+ that you are assembling as strings. If you need to quote text that
+ includes <code class="literal">$$</code>, you could use <code class="literal">$Q$</code>, and so on.
+ </p><p>
+ The following chart shows what you have to do when writing quote
+ marks without dollar quoting. It might be useful when translating
+ pre-dollar quoting code into something more comprehensible.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">1 quotation mark</span></dt><dd><p>
+ To begin and end the function body, for example:
+</p><pre class="programlisting">
+CREATE FUNCTION foo() RETURNS integer AS '
+ ....
+' LANGUAGE plpgsql;
+</pre><p>
+ Anywhere within a single-quoted function body, quote marks
+ <span class="emphasis"><em>must</em></span> appear in pairs.
+ </p></dd><dt><span class="term">2 quotation marks</span></dt><dd><p>
+ For string literals inside the function body, for example:
+</p><pre class="programlisting">
+a_output := ''Blah'';
+SELECT * FROM users WHERE f_name=''foobar'';
+</pre><p>
+ In the dollar-quoting approach, you'd just write:
+</p><pre class="programlisting">
+a_output := 'Blah';
+SELECT * FROM users WHERE f_name='foobar';
+</pre><p>
+ which is exactly what the <span class="application">PL/pgSQL</span> parser would see
+ in either case.
+ </p></dd><dt><span class="term">4 quotation marks</span></dt><dd><p>
+ When you need a single quotation mark in a string constant inside the
+ function body, for example:
+</p><pre class="programlisting">
+a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
+</pre><p>
+ The value actually appended to <code class="literal">a_output</code> would be:
+ <code class="literal"> AND name LIKE 'foobar' AND xyz</code>.
+ </p><p>
+ In the dollar-quoting approach, you'd write:
+</p><pre class="programlisting">
+a_output := a_output || $$ AND name LIKE 'foobar' AND xyz$$
+</pre><p>
+ being careful that any dollar-quote delimiters around this are not
+ just <code class="literal">$$</code>.
+ </p></dd><dt><span class="term">6 quotation marks</span></dt><dd><p>
+ When a single quotation mark in a string inside the function body is
+ adjacent to the end of that string constant, for example:
+</p><pre class="programlisting">
+a_output := a_output || '' AND name LIKE ''''foobar''''''
+</pre><p>
+ The value appended to <code class="literal">a_output</code> would then be:
+ <code class="literal"> AND name LIKE 'foobar'</code>.
+ </p><p>
+ In the dollar-quoting approach, this becomes:
+</p><pre class="programlisting">
+a_output := a_output || $$ AND name LIKE 'foobar'$$
+</pre><p>
+ </p></dd><dt><span class="term">10 quotation marks</span></dt><dd><p>
+ When you want two single quotation marks in a string constant (which
+ accounts for 8 quotation marks) and this is adjacent to the end of that
+ string constant (2 more). You will probably only need that if
+ you are writing a function that generates other functions, as in
+ <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-EX2" title="Example 43.10. Porting a Function that Creates Another Function from PL/SQL to PL/pgSQL">Example 43.10</a>.
+ For example:
+</p><pre class="programlisting">
+a_output := a_output || '' if v_'' ||
+ referrer_keys.kind || '' like ''''''''''
+ || referrer_keys.key_string || ''''''''''
+ then return '''''' || referrer_keys.referrer_type
+ || ''''''; end if;'';
+</pre><p>
+ The value of <code class="literal">a_output</code> would then be:
+</p><pre class="programlisting">
+if v_... like ''...'' then return ''...''; end if;
+</pre><p>
+ </p><p>
+ In the dollar-quoting approach, this becomes:
+</p><pre class="programlisting">
+a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$
+ || referrer_keys.key_string || $$'
+ then return '$$ || referrer_keys.referrer_type
+ || $$'; end if;$$;
+</pre><p>
+ where we assume we only need to put single quote marks into
+ <code class="literal">a_output</code>, because it will be re-quoted before use.
+ </p></dd></dl></div></div><div class="sect2" id="PLPGSQL-EXTRA-CHECKS"><div class="titlepage"><div><div><h3 class="title">43.12.2. Additional Compile-Time and Run-Time Checks</h3></div></div></div><p>
+ To aid the user in finding instances of simple but common problems before
+ they cause harm, <span class="application">PL/pgSQL</span> provides additional
+ <em class="replaceable"><code>checks</code></em>. When enabled, depending on the configuration, they
+ can be used to emit either a <code class="literal">WARNING</code> or an <code class="literal">ERROR</code>
+ during the compilation of a function. A function which has received
+ a <code class="literal">WARNING</code> can be executed without producing further messages,
+ so you are advised to test in a separate development environment.
+ </p><p>
+ Setting <code class="varname">plpgsql.extra_warnings</code>, or
+ <code class="varname">plpgsql.extra_errors</code>, as appropriate, to <code class="literal">"all"</code>
+ is encouraged in development and/or testing environments.
+ </p><p>
+ These additional checks are enabled through the configuration variables
+ <code class="varname">plpgsql.extra_warnings</code> for warnings and
+ <code class="varname">plpgsql.extra_errors</code> for errors. Both can be set either to
+ a comma-separated list of checks, <code class="literal">"none"</code> or
+ <code class="literal">"all"</code>. The default is <code class="literal">"none"</code>. Currently
+ the list of available checks includes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">shadowed_variables</code></span></dt><dd><p>
+ Checks if a declaration shadows a previously defined variable.
+ </p></dd><dt><span class="term"><code class="varname">strict_multi_assignment</code></span></dt><dd><p>
+ Some <span class="application">PL/PgSQL</span> commands allow assigning
+ values to more than one variable at a time, such as
+ <code class="command">SELECT INTO</code>. Typically, the number of target
+ variables and the number of source variables should match, though
+ <span class="application">PL/PgSQL</span> will use <code class="literal">NULL</code>
+ for missing values and extra variables are ignored. Enabling this
+ check will cause <span class="application">PL/PgSQL</span> to throw a
+ <code class="literal">WARNING</code> or <code class="literal">ERROR</code> whenever the
+ number of target variables and the number of source variables are
+ different.
+ </p></dd><dt><span class="term"><code class="varname">too_many_rows</code></span></dt><dd><p>
+ Enabling this check will cause <span class="application">PL/PgSQL</span> to
+ check if a given query returns more than one row when an
+ <code class="literal">INTO</code> clause is used. As an <code class="literal">INTO</code>
+ statement will only ever use one row, having a query return multiple
+ rows is generally either inefficient and/or nondeterministic and
+ therefore is likely an error.
+ </p></dd></dl></div><p>
+
+ The following example shows the effect of <code class="varname">plpgsql.extra_warnings</code>
+ set to <code class="varname">shadowed_variables</code>:
+</p><pre class="programlisting">
+SET plpgsql.extra_warnings TO 'shadowed_variables';
+
+CREATE FUNCTION foo(f1 int) RETURNS int AS $$
+DECLARE
+f1 int;
+BEGIN
+RETURN f1;
+END;
+$$ LANGUAGE plpgsql;
+WARNING: variable "f1" shadows a previously defined variable
+LINE 3: f1 int;
+ ^
+CREATE FUNCTION
+</pre><p>
+ The below example shows the effects of setting
+ <code class="varname">plpgsql.extra_warnings</code> to
+ <code class="varname">strict_multi_assignment</code>:
+</p><pre class="programlisting">
+SET plpgsql.extra_warnings TO 'strict_multi_assignment';
+
+CREATE OR REPLACE FUNCTION public.foo()
+ RETURNS void
+ LANGUAGE plpgsql
+AS $$
+DECLARE
+ x int;
+ y int;
+BEGIN
+ SELECT 1 INTO x, y;
+ SELECT 1, 2 INTO x, y;
+ SELECT 1, 2, 3 INTO x, y;
+END;
+$$;
+
+SELECT foo();
+WARNING: number of source and target fields in assignment does not match
+DETAIL: strict_multi_assignment check of extra_warnings is active.
+HINT: Make sure the query returns the exact list of columns.
+WARNING: number of source and target fields in assignment does not match
+DETAIL: strict_multi_assignment check of extra_warnings is active.
+HINT: Make sure the query returns the exact list of columns.
+
+ foo
+-----
+
+(1 row)
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.11. <span class="application">PL/pgSQL</span> under the Hood </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.13. Porting from <span class="productname">Oracle</span> PL/SQL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-errors-and-messages.html b/doc/src/sgml/html/plpgsql-errors-and-messages.html
new file mode 100644
index 0000000..57c7030
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-errors-and-messages.html
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.9. Errors and Messages</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-transactions.html" title="43.8. Transaction Management" /><link rel="next" href="plpgsql-trigger.html" title="43.10. Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.9. Errors and Messages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-transactions.html" title="43.8. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-trigger.html" title="43.10. Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-ERRORS-AND-MESSAGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.9. Errors and Messages</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE">43.9.1. Reporting Errors and Messages</a></span></dt><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">43.9.2. Checking Assertions</a></span></dt></dl></div><div class="sect2" id="PLPGSQL-STATEMENTS-RAISE"><div class="titlepage"><div><div><h3 class="title">43.9.1. Reporting Errors and Messages</h3></div></div></div><a id="id-1.8.8.11.2.2" class="indexterm"></a><a id="id-1.8.8.11.2.3" class="indexterm"></a><p>
+ Use the <code class="command">RAISE</code> statement to report messages and
+ raise errors.
+
+</p><pre class="synopsis">
+RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] '<em class="replaceable"><code>format</code></em>' [<span class="optional">, <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>]</span>] [<span class="optional"> USING <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] <em class="replaceable"><code>condition_name</code></em> [<span class="optional"> USING <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] SQLSTATE '<em class="replaceable"><code>sqlstate</code></em>' [<span class="optional"> USING <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+RAISE [<span class="optional"> <em class="replaceable"><code>level</code></em> </span>] USING <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>];
+RAISE ;
+</pre><p>
+
+ The <em class="replaceable"><code>level</code></em> option specifies
+ the error severity. Allowed levels are <code class="literal">DEBUG</code>,
+ <code class="literal">LOG</code>, <code class="literal">INFO</code>,
+ <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>,
+ and <code class="literal">EXCEPTION</code>, with <code class="literal">EXCEPTION</code>
+ being the default.
+ <code class="literal">EXCEPTION</code> raises an error (which normally aborts the
+ current transaction); the other levels only generate messages of different
+ priority levels.
+ Whether messages of a particular priority are reported to the client,
+ written to the server log, or both is controlled by the
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
+ variables. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for more
+ information.
+ </p><p>
+ After <em class="replaceable"><code>level</code></em> if any,
+ you can specify a <em class="replaceable"><code>format</code></em> string
+ (which must be a simple string literal, not an expression). The
+ format string specifies the error message text to be reported.
+ The format string can be followed
+ by optional argument expressions to be inserted into the message.
+ Inside the format string, <code class="literal">%</code> is replaced by the
+ string representation of the next optional argument's value. Write
+ <code class="literal">%%</code> to emit a literal <code class="literal">%</code>.
+ The number of arguments must match the number of <code class="literal">%</code>
+ placeholders in the format string, or an error is raised during
+ the compilation of the function.
+ </p><p>
+ In this example, the value of <code class="literal">v_job_id</code> will replace the
+ <code class="literal">%</code> in the string:
+</p><pre class="programlisting">
+RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
+</pre><p>
+ </p><p>
+ You can attach additional information to the error report by writing
+ <code class="literal">USING</code> followed by <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>expression</code></em> items. Each
+ <em class="replaceable"><code>expression</code></em> can be any
+ string-valued expression. The allowed <em class="replaceable"><code>option</code></em> key words are:
+
+ </p><div class="variablelist" id="RAISE-USING-OPTIONS"><dl class="variablelist"><dt><span class="term"><code class="literal">MESSAGE</code></span></dt><dd><p>Sets the error message text. This option can't be used in the
+ form of <code class="command">RAISE</code> that includes a format string
+ before <code class="literal">USING</code>.</p></dd><dt><span class="term"><code class="literal">DETAIL</code></span></dt><dd><p>Supplies an error detail message.</p></dd><dt><span class="term"><code class="literal">HINT</code></span></dt><dd><p>Supplies a hint message.</p></dd><dt><span class="term"><code class="literal">ERRCODE</code></span></dt><dd><p>Specifies the error code (SQLSTATE) to report, either by condition
+ name, as shown in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>, or directly as a
+ five-character SQLSTATE code.</p></dd><dt><span class="term"><code class="literal">COLUMN</code><br /></span><span class="term"><code class="literal">CONSTRAINT</code><br /></span><span class="term"><code class="literal">DATATYPE</code><br /></span><span class="term"><code class="literal">TABLE</code><br /></span><span class="term"><code class="literal">SCHEMA</code></span></dt><dd><p>Supplies the name of a related object.</p></dd></dl></div><p>
+ </p><p>
+ This example will abort the transaction with the given error message
+ and hint:
+</p><pre class="programlisting">
+RAISE EXCEPTION 'Nonexistent ID --&gt; %', user_id
+ USING HINT = 'Please check your user ID';
+</pre><p>
+ </p><p>
+ These two examples show equivalent ways of setting the SQLSTATE:
+</p><pre class="programlisting">
+RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
+RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
+</pre><p>
+ </p><p>
+ There is a second <code class="command">RAISE</code> syntax in which the main argument
+ is the condition name or SQLSTATE to be reported, for example:
+</p><pre class="programlisting">
+RAISE division_by_zero;
+RAISE SQLSTATE '22012';
+</pre><p>
+ In this syntax, <code class="literal">USING</code> can be used to supply a custom
+ error message, detail, or hint. Another way to do the earlier
+ example is
+</p><pre class="programlisting">
+RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
+</pre><p>
+ </p><p>
+ Still another variant is to write <code class="literal">RAISE USING</code> or <code class="literal">RAISE
+ <em class="replaceable"><code>level</code></em> USING</code> and put
+ everything else into the <code class="literal">USING</code> list.
+ </p><p>
+ The last variant of <code class="command">RAISE</code> has no parameters at all.
+ This form can only be used inside a <code class="literal">BEGIN</code> block's
+ <code class="literal">EXCEPTION</code> clause;
+ it causes the error currently being handled to be re-thrown.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 9.1, <code class="command">RAISE</code> without
+ parameters was interpreted as re-throwing the error from the block
+ containing the active exception handler. Thus an <code class="literal">EXCEPTION</code>
+ clause nested within that handler could not catch it, even if the
+ <code class="command">RAISE</code> was within the nested <code class="literal">EXCEPTION</code> clause's
+ block. This was deemed surprising as well as being incompatible with
+ Oracle's PL/SQL.
+ </p></div><p>
+ If no condition name nor SQLSTATE is specified in a
+ <code class="command">RAISE EXCEPTION</code> command, the default is to use
+ <code class="literal">raise_exception</code> (<code class="literal">P0001</code>).
+ If no message text is specified, the default is to use the condition
+ name or SQLSTATE as message text.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When specifying an error code by SQLSTATE code, you are not
+ limited to the predefined error codes, but can select any
+ error code consisting of five digits and/or upper-case ASCII
+ letters, other than <code class="literal">00000</code>. It is recommended that
+ you avoid throwing error codes that end in three zeroes, because
+ these are category codes and can only be trapped by trapping
+ the whole category.
+ </p></div></div><div class="sect2" id="PLPGSQL-STATEMENTS-ASSERT"><div class="titlepage"><div><div><h3 class="title">43.9.2. Checking Assertions</h3></div></div></div><a id="id-1.8.8.11.3.2" class="indexterm"></a><a id="id-1.8.8.11.3.3" class="indexterm"></a><a id="id-1.8.8.11.3.4" class="indexterm"></a><p>
+ The <code class="command">ASSERT</code> statement is a convenient shorthand for
+ inserting debugging checks into <span class="application">PL/pgSQL</span>
+ functions.
+
+</p><pre class="synopsis">
+ASSERT <em class="replaceable"><code>condition</code></em> [<span class="optional"> , <em class="replaceable"><code>message</code></em> </span>];
+</pre><p>
+
+ The <em class="replaceable"><code>condition</code></em> is a Boolean
+ expression that is expected to always evaluate to true; if it does,
+ the <code class="command">ASSERT</code> statement does nothing further. If the
+ result is false or null, then an <code class="literal">ASSERT_FAILURE</code> exception
+ is raised. (If an error occurs while evaluating
+ the <em class="replaceable"><code>condition</code></em>, it is
+ reported as a normal error.)
+ </p><p>
+ If the optional <em class="replaceable"><code>message</code></em> is
+ provided, it is an expression whose result (if not null) replaces the
+ default error message text <span class="quote">“<span class="quote">assertion failed</span>”</span>, should
+ the <em class="replaceable"><code>condition</code></em> fail.
+ The <em class="replaceable"><code>message</code></em> expression is
+ not evaluated in the normal case where the assertion succeeds.
+ </p><p>
+ Testing of assertions can be enabled or disabled via the configuration
+ parameter <code class="literal">plpgsql.check_asserts</code>, which takes a Boolean
+ value; the default is <code class="literal">on</code>. If this parameter
+ is <code class="literal">off</code> then <code class="command">ASSERT</code> statements do nothing.
+ </p><p>
+ Note that <code class="command">ASSERT</code> is meant for detecting program
+ bugs, not for reporting ordinary error conditions. Use
+ the <code class="command">RAISE</code> statement, described above, for that.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-transactions.html" title="43.8. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-trigger.html" title="43.10. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.8. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.10. Trigger Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-expressions.html b/doc/src/sgml/html/plpgsql-expressions.html
new file mode 100644
index 0000000..6d8e274
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-expressions.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.4. Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-declarations.html" title="43.3. Declarations" /><link rel="next" href="plpgsql-statements.html" title="43.5. Basic Statements" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.4. Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-declarations.html" title="43.3. Declarations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-statements.html" title="43.5. Basic Statements">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-EXPRESSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.4. Expressions</h2></div></div></div><p>
+ All expressions used in <span class="application">PL/pgSQL</span>
+ statements are processed using the server's main
+ <acronym class="acronym">SQL</acronym> executor. For example, when you write
+ a <span class="application">PL/pgSQL</span> statement like
+</p><pre class="synopsis">
+IF <em class="replaceable"><code>expression</code></em> THEN ...
+</pre><p>
+ <span class="application">PL/pgSQL</span> will evaluate the expression by
+ feeding a query like
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>expression</code></em>
+</pre><p>
+ to the main SQL engine. While forming the <code class="command">SELECT</code> command,
+ any occurrences of <span class="application">PL/pgSQL</span> variable names
+ are replaced by query parameters, as discussed in detail in
+ <a class="xref" href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST" title="43.11.1. Variable Substitution">Section 43.11.1</a>.
+ This allows the query plan for the <code class="command">SELECT</code> to
+ be prepared just once and then reused for subsequent
+ evaluations with different values of the variables. Thus, what
+ really happens on first use of an expression is essentially a
+ <code class="command">PREPARE</code> command. For example, if we have declared
+ two integer variables <code class="literal">x</code> and <code class="literal">y</code>, and we write
+</p><pre class="programlisting">
+IF x &lt; y THEN ...
+</pre><p>
+ what happens behind the scenes is equivalent to
+</p><pre class="programlisting">
+PREPARE <em class="replaceable"><code>statement_name</code></em>(integer, integer) AS SELECT $1 &lt; $2;
+</pre><p>
+ and then this prepared statement is <code class="command">EXECUTE</code>d for each
+ execution of the <code class="command">IF</code> statement, with the current values
+ of the <span class="application">PL/pgSQL</span> variables supplied as
+ parameter values. Normally these details are
+ not important to a <span class="application">PL/pgSQL</span> user, but
+ they are useful to know when trying to diagnose a problem.
+ More information appears in <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="43.11.2. Plan Caching">Section 43.11.2</a>.
+ </p><p>
+ Since an <em class="replaceable"><code>expression</code></em> is converted to a
+ <code class="literal">SELECT</code> command, it can contain the same clauses
+ that an ordinary <code class="literal">SELECT</code> would, except that it
+ cannot include a top-level <code class="literal">UNION</code>,
+ <code class="literal">INTERSECT</code>, or <code class="literal">EXCEPT</code> clause.
+ Thus for example one could test whether a table is non-empty with
+</p><pre class="programlisting">
+IF count(*) &gt; 0 FROM my_table THEN ...
+</pre><p>
+ since the <em class="replaceable"><code>expression</code></em>
+ between <code class="literal">IF</code> and <code class="literal">THEN</code> is parsed as
+ though it were <code class="literal">SELECT count(*) &gt; 0 FROM my_table</code>.
+ The <code class="literal">SELECT</code> must produce a single column, and not
+ more than one row. (If it produces no rows, the result is taken as
+ NULL.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-declarations.html" title="43.3. Declarations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-statements.html" title="43.5. Basic Statements">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.3. Declarations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.5. Basic Statements</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-implementation.html b/doc/src/sgml/html/plpgsql-implementation.html
new file mode 100644
index 0000000..3c7418a
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-implementation.html
@@ -0,0 +1,276 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.11. PL/pgSQL under the Hood</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-trigger.html" title="43.10. Trigger Functions" /><link rel="next" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.11. <span class="application">PL/pgSQL</span> under the Hood</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-trigger.html" title="43.10. Trigger Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.11. <span class="application">PL/pgSQL</span> under the Hood</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST">43.11.1. Variable Substitution</a></span></dt><dt><span class="sect2"><a href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING">43.11.2. Plan Caching</a></span></dt></dl></div><p>
+ This section discusses some implementation details that are
+ frequently important for <span class="application">PL/pgSQL</span> users to know.
+ </p><div class="sect2" id="PLPGSQL-VAR-SUBST"><div class="titlepage"><div><div><h3 class="title">43.11.1. Variable Substitution</h3></div></div></div><p>
+ SQL statements and expressions within a <span class="application">PL/pgSQL</span> function
+ can refer to variables and parameters of the function. Behind the scenes,
+ <span class="application">PL/pgSQL</span> substitutes query parameters for such references.
+ Query parameters will only be substituted in places where they are
+ syntactically permissible. As an extreme case, consider
+ this example of poor programming style:
+</p><pre class="programlisting">
+INSERT INTO foo (foo) VALUES (foo(foo));
+</pre><p>
+ The first occurrence of <code class="literal">foo</code> must syntactically be a table
+ name, so it will not be substituted, even if the function has a variable
+ named <code class="literal">foo</code>. The second occurrence must be the name of a
+ column of that table, so it will not be substituted either. Likewise
+ the third occurrence must be a function name, so it also will not be
+ substituted for. Only the last occurrence is a candidate to be a
+ reference to a variable of the <span class="application">PL/pgSQL</span>
+ function.
+ </p><p>
+ Another way to understand this is that variable substitution can only
+ insert data values into an SQL command; it cannot dynamically change which
+ database objects are referenced by the command. (If you want to do
+ that, you must build a command string dynamically, as explained in
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN" title="43.5.4. Executing Dynamic Commands">Section 43.5.4</a>.)
+ </p><p>
+ Since the names of variables are syntactically no different from the names
+ of table columns, there can be ambiguity in statements that also refer to
+ tables: is a given name meant to refer to a table column, or a variable?
+ Let's change the previous example to
+</p><pre class="programlisting">
+INSERT INTO dest (col) SELECT foo + bar FROM src;
+</pre><p>
+ Here, <code class="literal">dest</code> and <code class="literal">src</code> must be table names, and
+ <code class="literal">col</code> must be a column of <code class="literal">dest</code>, but <code class="literal">foo</code>
+ and <code class="literal">bar</code> might reasonably be either variables of the function
+ or columns of <code class="literal">src</code>.
+ </p><p>
+ By default, <span class="application">PL/pgSQL</span> will report an error if a name
+ in an SQL statement could refer to either a variable or a table column.
+ You can fix such a problem by renaming the variable or column,
+ or by qualifying the ambiguous reference, or by telling
+ <span class="application">PL/pgSQL</span> which interpretation to prefer.
+ </p><p>
+ The simplest solution is to rename the variable or column.
+ A common coding rule is to use a
+ different naming convention for <span class="application">PL/pgSQL</span>
+ variables than you use for column names. For example,
+ if you consistently name function variables
+ <code class="literal">v_<em class="replaceable"><code>something</code></em></code> while none of your
+ column names start with <code class="literal">v_</code>, no conflicts will occur.
+ </p><p>
+ Alternatively you can qualify ambiguous references to make them clear.
+ In the above example, <code class="literal">src.foo</code> would be an unambiguous reference
+ to the table column. To create an unambiguous reference to a variable,
+ declare it in a labeled block and use the block's label
+ (see <a class="xref" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL">Section 43.2</a>). For example,
+</p><pre class="programlisting">
+&lt;&lt;block&gt;&gt;
+DECLARE
+ foo int;
+BEGIN
+ foo := ...;
+ INSERT INTO dest (col) SELECT block.foo + bar FROM src;
+</pre><p>
+ Here <code class="literal">block.foo</code> means the variable even if there is a column
+ <code class="literal">foo</code> in <code class="literal">src</code>. Function parameters, as well as
+ special variables such as <code class="literal">FOUND</code>, can be qualified by the
+ function's name, because they are implicitly declared in an outer block
+ labeled with the function's name.
+ </p><p>
+ Sometimes it is impractical to fix all the ambiguous references in a
+ large body of <span class="application">PL/pgSQL</span> code. In such cases you can
+ specify that <span class="application">PL/pgSQL</span> should resolve ambiguous references
+ as the variable (which is compatible with <span class="application">PL/pgSQL</span>'s
+ behavior before <span class="productname">PostgreSQL</span> 9.0), or as the
+ table column (which is compatible with some other systems such as
+ <span class="productname">Oracle</span>).
+ </p><a id="id-1.8.8.13.3.9" class="indexterm"></a><p>
+ To change this behavior on a system-wide basis, set the configuration
+ parameter <code class="literal">plpgsql.variable_conflict</code> to one of
+ <code class="literal">error</code>, <code class="literal">use_variable</code>, or
+ <code class="literal">use_column</code> (where <code class="literal">error</code> is the factory default).
+ This parameter affects subsequent compilations
+ of statements in <span class="application">PL/pgSQL</span> functions, but not statements
+ already compiled in the current session.
+ Because changing this setting
+ can cause unexpected changes in the behavior of <span class="application">PL/pgSQL</span>
+ functions, it can only be changed by a superuser.
+ </p><p>
+ You can also set the behavior on a function-by-function basis, by
+ inserting one of these special commands at the start of the function
+ text:
+</p><pre class="programlisting">
+#variable_conflict error
+#variable_conflict use_variable
+#variable_conflict use_column
+</pre><p>
+ These commands affect only the function they are written in, and override
+ the setting of <code class="literal">plpgsql.variable_conflict</code>. An example is
+</p><pre class="programlisting">
+CREATE FUNCTION stamp_user(id int, comment text) RETURNS void AS $$
+ #variable_conflict use_variable
+ DECLARE
+ curtime timestamp := now();
+ BEGIN
+ UPDATE users SET last_modified = curtime, comment = comment
+ WHERE users.id = id;
+ END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ In the <code class="literal">UPDATE</code> command, <code class="literal">curtime</code>, <code class="literal">comment</code>,
+ and <code class="literal">id</code> will refer to the function's variable and parameters
+ whether or not <code class="literal">users</code> has columns of those names. Notice
+ that we had to qualify the reference to <code class="literal">users.id</code> in the
+ <code class="literal">WHERE</code> clause to make it refer to the table column.
+ But we did not have to qualify the reference to <code class="literal">comment</code>
+ as a target in the <code class="literal">UPDATE</code> list, because syntactically
+ that must be a column of <code class="literal">users</code>. We could write the same
+ function without depending on the <code class="literal">variable_conflict</code> setting
+ in this way:
+</p><pre class="programlisting">
+CREATE FUNCTION stamp_user(id int, comment text) RETURNS void AS $$
+ &lt;&lt;fn&gt;&gt;
+ DECLARE
+ curtime timestamp := now();
+ BEGIN
+ UPDATE users SET last_modified = fn.curtime, comment = stamp_user.comment
+ WHERE users.id = stamp_user.id;
+ END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ Variable substitution does not happen in a command string given
+ to <code class="command">EXECUTE</code> or one of its variants. If you need to
+ insert a varying value into such a command, do so as part of
+ constructing the string value, or use <code class="literal">USING</code>, as illustrated in
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN" title="43.5.4. Executing Dynamic Commands">Section 43.5.4</a>.
+ </p><p>
+ Variable substitution currently works only in <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, and commands containing one of
+ these (such as <code class="command">EXPLAIN</code> and <code class="command">CREATE TABLE
+ ... AS SELECT</code>),
+ because the main SQL engine allows query parameters only in these
+ commands. To use a non-constant name or value in other statement
+ types (generically called utility statements), you must construct
+ the utility statement as a string and <code class="command">EXECUTE</code> it.
+ </p></div><div class="sect2" id="PLPGSQL-PLAN-CACHING"><div class="titlepage"><div><div><h3 class="title">43.11.2. Plan Caching</h3></div></div></div><p>
+ The <span class="application">PL/pgSQL</span> interpreter parses the function's source
+ text and produces an internal binary instruction tree the first time the
+ function is called (within each session). The instruction tree
+ fully translates the
+ <span class="application">PL/pgSQL</span> statement structure, but individual
+ <acronym class="acronym">SQL</acronym> expressions and <acronym class="acronym">SQL</acronym> commands
+ used in the function are not translated immediately.
+ </p><p>
+ <a id="id-1.8.8.13.4.3.1" class="indexterm"></a>
+ As each expression and <acronym class="acronym">SQL</acronym> command is first
+ executed in the function, the <span class="application">PL/pgSQL</span> interpreter
+ parses and analyzes the command to create a prepared statement,
+ using the <acronym class="acronym">SPI</acronym> manager's
+ <code class="function">SPI_prepare</code> function.
+ Subsequent visits to that expression or command
+ reuse the prepared statement. Thus, a function with conditional code
+ paths that are seldom visited will never incur the overhead of
+ analyzing those commands that are never executed within the current
+ session. A disadvantage is that errors
+ in a specific expression or command cannot be detected until that
+ part of the function is reached in execution. (Trivial syntax
+ errors will be detected during the initial parsing pass, but
+ anything deeper will not be detected until execution.)
+ </p><p>
+ <span class="application">PL/pgSQL</span> (or more precisely, the SPI manager) can
+ furthermore attempt to cache the execution plan associated with any
+ particular prepared statement. If a cached plan is not used, then
+ a fresh execution plan is generated on each visit to the statement,
+ and the current parameter values (that is, <span class="application">PL/pgSQL</span>
+ variable values) can be used to optimize the selected plan. If the
+ statement has no parameters, or is executed many times, the SPI manager
+ will consider creating a <em class="firstterm">generic</em> plan that is not dependent
+ on specific parameter values, and caching that for re-use. Typically
+ this will happen only if the execution plan is not very sensitive to
+ the values of the <span class="application">PL/pgSQL</span> variables referenced in it.
+ If it is, generating a plan each time is a net win. See <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for more information about the behavior of
+ prepared statements.
+ </p><p>
+ Because <span class="application">PL/pgSQL</span> saves prepared statements
+ and sometimes execution plans in this way,
+ SQL commands that appear directly in a
+ <span class="application">PL/pgSQL</span> function must refer to the
+ same tables and columns on every execution; that is, you cannot use
+ a parameter as the name of a table or column in an SQL command. To get
+ around this restriction, you can construct dynamic commands using
+ the <span class="application">PL/pgSQL</span> <code class="command">EXECUTE</code>
+ statement — at the price of performing new parse analysis and
+ constructing a new execution plan on every execution.
+ </p><p>
+ The mutable nature of record variables presents another problem in this
+ connection. When fields of a record variable are used in
+ expressions or statements, the data types of the fields must not
+ change from one call of the function to the next, since each
+ expression will be analyzed using the data type that is present
+ when the expression is first reached. <code class="command">EXECUTE</code> can be
+ used to get around this problem when necessary.
+ </p><p>
+ If the same function is used as a trigger for more than one table,
+ <span class="application">PL/pgSQL</span> prepares and caches statements
+ independently for each such table — that is, there is a cache
+ for each trigger function and table combination, not just for each
+ function. This alleviates some of the problems with varying
+ data types; for instance, a trigger function will be able to work
+ successfully with a column named <code class="literal">key</code> even if it happens
+ to have different types in different tables.
+ </p><p>
+ Likewise, functions having polymorphic argument types have a separate
+ statement cache for each combination of actual argument types they have
+ been invoked for, so that data type differences do not cause unexpected
+ failures.
+ </p><p>
+ Statement caching can sometimes have surprising effects on the
+ interpretation of time-sensitive values. For example there
+ is a difference between what these two functions do:
+
+</p><pre class="programlisting">
+CREATE FUNCTION logfunc1(logtxt text) RETURNS void AS $$
+ BEGIN
+ INSERT INTO logtable VALUES (logtxt, 'now');
+ END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ and:
+
+</p><pre class="programlisting">
+CREATE FUNCTION logfunc2(logtxt text) RETURNS void AS $$
+ DECLARE
+ curtime timestamp;
+ BEGIN
+ curtime := 'now';
+ INSERT INTO logtable VALUES (logtxt, curtime);
+ END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ In the case of <code class="function">logfunc1</code>, the
+ <span class="productname">PostgreSQL</span> main parser knows when
+ analyzing the <code class="command">INSERT</code> that the
+ string <code class="literal">'now'</code> should be interpreted as
+ <code class="type">timestamp</code>, because the target column of
+ <code class="classname">logtable</code> is of that type. Thus,
+ <code class="literal">'now'</code> will be converted to a <code class="type">timestamp</code>
+ constant when the
+ <code class="command">INSERT</code> is analyzed, and then used in all
+ invocations of <code class="function">logfunc1</code> during the lifetime
+ of the session. Needless to say, this isn't what the programmer
+ wanted. A better idea is to use the <code class="literal">now()</code> or
+ <code class="literal">current_timestamp</code> function.
+ </p><p>
+ In the case of <code class="function">logfunc2</code>, the
+ <span class="productname">PostgreSQL</span> main parser does not know
+ what type <code class="literal">'now'</code> should become and therefore
+ it returns a data value of type <code class="type">text</code> containing the string
+ <code class="literal">now</code>. During the ensuing assignment
+ to the local variable <code class="varname">curtime</code>, the
+ <span class="application">PL/pgSQL</span> interpreter casts this
+ string to the <code class="type">timestamp</code> type by calling the
+ <code class="function">textout</code> and <code class="function">timestamp_in</code>
+ functions for the conversion. So, the computed time stamp is updated
+ on each execution as the programmer expects. Even though this
+ happens to work as expected, it's not terribly efficient, so
+ use of the <code class="literal">now()</code> function would still be a better idea.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-trigger.html" title="43.10. Trigger Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.10. Trigger Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.12. Tips for Developing in <span class="application">PL/pgSQL</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-overview.html b/doc/src/sgml/html/plpgsql-overview.html
new file mode 100644
index 0000000..80e9251
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-overview.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language" /><link rel="next" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.1. Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-overview.html#PLPGSQL-ADVANTAGES">43.1.1. Advantages of Using <span class="application">PL/pgSQL</span></a></span></dt><dt><span class="sect2"><a href="plpgsql-overview.html#PLPGSQL-ARGS-RESULTS">43.1.2. Supported Argument and Result Data Types</a></span></dt></dl></div><p>
+ <span class="application">PL/pgSQL</span> is a loadable procedural
+ language for the <span class="productname">PostgreSQL</span> database
+ system. The design goals of <span class="application">PL/pgSQL</span> were to create
+ a loadable procedural language that
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ can be used to create functions, procedures, and triggers,
+ </p></li><li class="listitem"><p>
+ adds control structures to the <acronym class="acronym">SQL</acronym> language,
+ </p></li><li class="listitem"><p>
+ can perform complex computations,
+ </p></li><li class="listitem"><p>
+ inherits all user-defined types, functions, procedures, and operators,
+ </p></li><li class="listitem"><p>
+ can be defined to be trusted by the server,
+ </p></li><li class="listitem"><p>
+ is easy to use.
+ </p></li></ul></div><p>
+ </p><p>
+ Functions created with <span class="application">PL/pgSQL</span> can be
+ used anywhere that built-in functions could be used.
+ For example, it is possible to
+ create complex conditional computation functions and later use
+ them to define operators or use them in index expressions.
+ </p><p>
+ In <span class="productname">PostgreSQL</span> 9.0 and later,
+ <span class="application">PL/pgSQL</span> is installed by default.
+ However it is still a loadable module, so especially security-conscious
+ administrators could choose to remove it.
+ </p><div class="sect2" id="PLPGSQL-ADVANTAGES"><div class="titlepage"><div><div><h3 class="title">43.1.1. Advantages of Using <span class="application">PL/pgSQL</span></h3></div></div></div><p>
+ <acronym class="acronym">SQL</acronym> is the language <span class="productname">PostgreSQL</span>
+ and most other relational databases use as query language. It's
+ portable and easy to learn. But every <acronym class="acronym">SQL</acronym>
+ statement must be executed individually by the database server.
+ </p><p>
+ That means that your client application must send each query to
+ the database server, wait for it to be processed, receive and
+ process the results, do some computation, then send further
+ queries to the server. All this incurs interprocess
+ communication and will also incur network overhead if your client
+ is on a different machine than the database server.
+ </p><p>
+ With <span class="application">PL/pgSQL</span> you can group a block of
+ computation and a series of queries <span class="emphasis"><em>inside</em></span>
+ the database server, thus having the power of a procedural
+ language and the ease of use of SQL, but with considerable
+ savings of client/server communication overhead.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Extra round trips between
+ client and server are eliminated </p></li><li class="listitem"><p> Intermediate results that the client does not
+ need do not have to be marshaled or transferred between server
+ and client </p></li><li class="listitem"><p> Multiple rounds of query
+ parsing can be avoided </p></li></ul></div><p> This can result in a considerable performance increase as
+ compared to an application that does not use stored functions.
+ </p><p>
+ Also, with <span class="application">PL/pgSQL</span> you can use all
+ the data types, operators and functions of SQL.
+ </p></div><div class="sect2" id="PLPGSQL-ARGS-RESULTS"><div class="titlepage"><div><div><h3 class="title">43.1.2. Supported Argument and Result Data Types</h3></div></div></div><p>
+ Functions written in <span class="application">PL/pgSQL</span> can accept
+ as arguments any scalar or array data type supported by the server,
+ and they can return a result of any of these types. They can also
+ accept or return any composite type (row type) specified by name.
+ It is also possible to declare a <span class="application">PL/pgSQL</span>
+ function as accepting <code class="type">record</code>, which means that any
+ composite type will do as input, or
+ as returning <code class="type">record</code>, which means that the result
+ is a row type whose columns are determined by specification in the
+ calling query, as discussed in <a class="xref" href="queries-table-expressions.html#QUERIES-TABLEFUNCTIONS" title="7.2.1.4. Table Functions">Section 7.2.1.4</a>.
+ </p><p>
+ <span class="application">PL/pgSQL</span> functions can be declared to accept a variable
+ number of arguments by using the <code class="literal">VARIADIC</code> marker. This
+ works exactly the same way as for SQL functions, as discussed in
+ <a class="xref" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS" title="38.5.6. SQL Functions with Variable Numbers of Arguments">Section 38.5.6</a>.
+ </p><p>
+ <span class="application">PL/pgSQL</span> functions can also be declared to
+ accept and return the polymorphic types described in
+ <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>, thus allowing the actual data
+ types handled by the function to vary from call to call.
+ Examples appear in <a class="xref" href="plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS" title="43.3.1. Declaring Function Parameters">Section 43.3.1</a>.
+ </p><p>
+ <span class="application">PL/pgSQL</span> functions can also be declared to return
+ a <span class="quote">“<span class="quote">set</span>”</span> (or table) of any data type that can be returned as
+ a single instance. Such a function generates its output by executing
+ <code class="command">RETURN NEXT</code> for each desired element of the result
+ set, or by using <code class="command">RETURN QUERY</code> to output the result of
+ evaluating a query.
+ </p><p>
+ Finally, a <span class="application">PL/pgSQL</span> function can be declared to return
+ <code class="type">void</code> if it has no useful return value. (Alternatively, it
+ could be written as a procedure in that case.)
+ </p><p>
+ <span class="application">PL/pgSQL</span> functions can also be declared with output
+ parameters in place of an explicit specification of the return type.
+ This does not add any fundamental capability to the language, but
+ it is often convenient, especially for returning multiple values.
+ The <code class="literal">RETURNS TABLE</code> notation can also be used in place
+ of <code class="literal">RETURNS SETOF</code>.
+ </p><p>
+ Specific examples appear in
+ <a class="xref" href="plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS" title="43.3.1. Declaring Function Parameters">Section 43.3.1</a> and
+ <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-RETURNING" title="43.6.1. Returning from a Function">Section 43.6.1</a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-structure.html" title="43.2. Structure of PL/pgSQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.2. Structure of <span class="application">PL/pgSQL</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-porting.html b/doc/src/sgml/html/plpgsql-porting.html
new file mode 100644
index 0000000..f6e09ee
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-porting.html
@@ -0,0 +1,560 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.13. Porting from Oracle PL/SQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL" /><link rel="next" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.13. Porting from <span class="productname">Oracle</span> PL/SQL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-PORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.13. Porting from <span class="productname">Oracle</span> PL/SQL</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-porting.html#id-1.8.8.15.6">43.13.1. Porting Examples</a></span></dt><dt><span class="sect2"><a href="plpgsql-porting.html#PLPGSQL-PORTING-OTHER">43.13.2. Other Things to Watch For</a></span></dt><dt><span class="sect2"><a href="plpgsql-porting.html#PLPGSQL-PORTING-APPENDIX">43.13.3. Appendix</a></span></dt></dl></div><a id="id-1.8.8.15.2" class="indexterm"></a><a id="id-1.8.8.15.3" class="indexterm"></a><p>
+ This section explains differences between
+ <span class="productname">PostgreSQL</span>'s <span class="application">PL/pgSQL</span>
+ language and Oracle's <span class="application">PL/SQL</span> language,
+ to help developers who port applications from
+ <span class="trademark">Oracle</span>® to <span class="productname">PostgreSQL</span>.
+ </p><p>
+ <span class="application">PL/pgSQL</span> is similar to PL/SQL in many
+ aspects. It is a block-structured, imperative language, and all
+ variables have to be declared. Assignments, loops, and conditionals
+ are similar. The main differences you should keep in mind when
+ porting from <span class="application">PL/SQL</span> to
+ <span class="application">PL/pgSQL</span> are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If a name used in an SQL command could be either a column name of a
+ table used in the command or a reference to a variable of the function,
+ <span class="application">PL/SQL</span> treats it as a column name.
+ By default, <span class="application">PL/pgSQL</span> will throw an error
+ complaining that the name is ambiguous. You can specify
+ <code class="literal">plpgsql.variable_conflict</code> = <code class="literal">use_column</code>
+ to change this behavior to match <span class="application">PL/SQL</span>,
+ as explained in <a class="xref" href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST" title="43.11.1. Variable Substitution">Section 43.11.1</a>.
+ It's often best to avoid such ambiguities in the first place,
+ but if you have to port a large amount of code that depends on
+ this behavior, setting <code class="literal">variable_conflict</code> may be the
+ best solution.
+ </p></li><li class="listitem"><p>
+ In <span class="productname">PostgreSQL</span> the function body must be written as
+ a string literal. Therefore you need to use dollar quoting or escape
+ single quotes in the function body. (See <a class="xref" href="plpgsql-development-tips.html#PLPGSQL-QUOTE-TIPS" title="43.12.1. Handling of Quotation Marks">Section 43.12.1</a>.)
+ </p></li><li class="listitem"><p>
+ Data type names often need translation. For example, in Oracle string
+ values are commonly declared as being of type <code class="type">varchar2</code>, which
+ is a non-SQL-standard type. In <span class="productname">PostgreSQL</span>,
+ use type <code class="type">varchar</code> or <code class="type">text</code> instead. Similarly, replace
+ type <code class="type">number</code> with <code class="type">numeric</code>, or use some other numeric
+ data type if there's a more appropriate one.
+ </p></li><li class="listitem"><p>
+ Instead of packages, use schemas to organize your functions
+ into groups.
+ </p></li><li class="listitem"><p>
+ Since there are no packages, there are no package-level variables
+ either. This is somewhat annoying. You can keep per-session state
+ in temporary tables instead.
+ </p></li><li class="listitem"><p>
+ Integer <code class="command">FOR</code> loops with <code class="literal">REVERSE</code> work
+ differently: <span class="application">PL/SQL</span> counts down from the second
+ number to the first, while <span class="application">PL/pgSQL</span> counts down
+ from the first number to the second, requiring the loop bounds
+ to be swapped when porting. This incompatibility is unfortunate
+ but is unlikely to be changed. (See <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-INTEGER-FOR" title="43.6.5.5. FOR (Integer Variant)">Section 43.6.5.5</a>.)
+ </p></li><li class="listitem"><p>
+ <code class="command">FOR</code> loops over queries (other than cursors) also work
+ differently: the target variable(s) must have been declared,
+ whereas <span class="application">PL/SQL</span> always declares them implicitly.
+ An advantage of this is that the variable values are still accessible
+ after the loop exits.
+ </p></li><li class="listitem"><p>
+ There are various notational differences for the use of cursor
+ variables.
+ </p></li></ul></div><p>
+ </p><div class="sect2" id="id-1.8.8.15.6"><div class="titlepage"><div><div><h3 class="title">43.13.1. Porting Examples</h3></div></div></div><p>
+ <a class="xref" href="plpgsql-porting.html#PGSQL-PORTING-EX1" title="Example 43.9. Porting a Simple Function from PL/SQL to PL/pgSQL">Example 43.9</a> shows how to port a simple
+ function from <span class="application">PL/SQL</span> to <span class="application">PL/pgSQL</span>.
+ </p><div class="example" id="PGSQL-PORTING-EX1"><p class="title"><strong>Example 43.9. Porting a Simple Function from <span class="application">PL/SQL</span> to <span class="application">PL/pgSQL</span></strong></p><div class="example-contents"><p>
+ Here is an <span class="productname">Oracle</span> <span class="application">PL/SQL</span> function:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name varchar2,
+ v_version varchar2)
+RETURN varchar2 IS
+BEGIN
+ IF v_version IS NULL THEN
+ RETURN v_name;
+ END IF;
+ RETURN v_name || '/' || v_version;
+END;
+/
+show errors;
+</pre><p>
+ </p><p>
+ Let's go through this function and see the differences compared to
+ <span class="application">PL/pgSQL</span>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The type name <code class="type">varchar2</code> has to be changed to <code class="type">varchar</code>
+ or <code class="type">text</code>. In the examples in this section, we'll
+ use <code class="type">varchar</code>, but <code class="type">text</code> is often a better choice if
+ you do not need specific string length limits.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">RETURN</code> key word in the function
+ prototype (not the function body) becomes
+ <code class="literal">RETURNS</code> in
+ <span class="productname">PostgreSQL</span>.
+ Also, <code class="literal">IS</code> becomes <code class="literal">AS</code>, and you need to
+ add a <code class="literal">LANGUAGE</code> clause because <span class="application">PL/pgSQL</span>
+ is not the only possible function language.
+ </p></li><li class="listitem"><p>
+ In <span class="productname">PostgreSQL</span>, the function body is considered
+ to be a string literal, so you need to use quote marks or dollar
+ quotes around it. This substitutes for the terminating <code class="literal">/</code>
+ in the Oracle approach.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">show errors</code> command does not exist in
+ <span class="productname">PostgreSQL</span>, and is not needed since errors are
+ reported automatically.
+ </p></li></ul></div><p>
+ </p><p>
+ This is how this function would look when ported to
+ <span class="productname">PostgreSQL</span>:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name varchar,
+ v_version varchar)
+RETURNS varchar AS $$
+BEGIN
+ IF v_version IS NULL THEN
+ RETURN v_name;
+ END IF;
+ RETURN v_name || '/' || v_version;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p></div></div><br class="example-break" /><p>
+ <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-EX2" title="Example 43.10. Porting a Function that Creates Another Function from PL/SQL to PL/pgSQL">Example 43.10</a> shows how to port a
+ function that creates another function and how to handle the
+ ensuing quoting problems.
+ </p><div class="example" id="PLPGSQL-PORTING-EX2"><p class="title"><strong>Example 43.10. Porting a Function that Creates Another Function from <span class="application">PL/SQL</span> to <span class="application">PL/pgSQL</span></strong></p><div class="example-contents"><p>
+ The following procedure grabs rows from a
+ <code class="command">SELECT</code> statement and builds a large function
+ with the results in <code class="literal">IF</code> statements, for the
+ sake of efficiency.
+ </p><p>
+ This is the Oracle version:
+</p><pre class="programlisting">
+CREATE OR REPLACE PROCEDURE cs_update_referrer_type_proc IS
+ CURSOR referrer_keys IS
+ SELECT * FROM cs_referrer_keys
+ ORDER BY try_order;
+ func_cmd VARCHAR(4000);
+BEGIN
+ func_cmd := 'CREATE OR REPLACE FUNCTION cs_find_referrer_type(v_host IN VARCHAR2,
+ v_domain IN VARCHAR2, v_url IN VARCHAR2) RETURN VARCHAR2 IS BEGIN';
+
+ FOR referrer_key IN referrer_keys LOOP
+ func_cmd := func_cmd ||
+ ' IF v_' || referrer_key.kind
+ || ' LIKE ''' || referrer_key.key_string
+ || ''' THEN RETURN ''' || referrer_key.referrer_type
+ || '''; END IF;';
+ END LOOP;
+
+ func_cmd := func_cmd || ' RETURN NULL; END;';
+
+ EXECUTE IMMEDIATE func_cmd;
+END;
+/
+show errors;
+</pre><p>
+ </p><p>
+ Here is how this function would end up in <span class="productname">PostgreSQL</span>:
+</p><pre class="programlisting">
+CREATE OR REPLACE PROCEDURE cs_update_referrer_type_proc() AS $func$
+DECLARE
+ referrer_keys CURSOR IS
+ SELECT * FROM cs_referrer_keys
+ ORDER BY try_order;
+ func_body text;
+ func_cmd text;
+BEGIN
+ func_body := 'BEGIN';
+
+ FOR referrer_key IN referrer_keys LOOP
+ func_body := func_body ||
+ ' IF v_' || referrer_key.kind
+ || ' LIKE ' || quote_literal(referrer_key.key_string)
+ || ' THEN RETURN ' || quote_literal(referrer_key.referrer_type)
+ || '; END IF;' ;
+ END LOOP;
+
+ func_body := func_body || ' RETURN NULL; END;';
+
+ func_cmd :=
+ 'CREATE OR REPLACE FUNCTION cs_find_referrer_type(v_host varchar,
+ v_domain varchar,
+ v_url varchar)
+ RETURNS varchar AS '
+ || quote_literal(func_body)
+ || ' LANGUAGE plpgsql;' ;
+
+ EXECUTE func_cmd;
+END;
+$func$ LANGUAGE plpgsql;
+</pre><p>
+ Notice how the body of the function is built separately and passed
+ through <code class="literal">quote_literal</code> to double any quote marks in it. This
+ technique is needed because we cannot safely use dollar quoting for
+ defining the new function: we do not know for sure what strings will
+ be interpolated from the <code class="structfield">referrer_key.key_string</code> field.
+ (We are assuming here that <code class="structfield">referrer_key.kind</code> can be
+ trusted to always be <code class="literal">host</code>, <code class="literal">domain</code>, or
+ <code class="literal">url</code>, but <code class="structfield">referrer_key.key_string</code> might be
+ anything, in particular it might contain dollar signs.) This function
+ is actually an improvement on the Oracle original, because it will
+ not generate broken code when <code class="structfield">referrer_key.key_string</code> or
+ <code class="structfield">referrer_key.referrer_type</code> contain quote marks.
+ </p></div></div><br class="example-break" /><p>
+ <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-EX3" title="Example 43.11. Porting a Procedure With String Manipulation and OUT Parameters from PL/SQL to PL/pgSQL">Example 43.11</a> shows how to port a function
+ with <code class="literal">OUT</code> parameters and string manipulation.
+ <span class="productname">PostgreSQL</span> does not have a built-in
+ <code class="function">instr</code> function, but you can create one
+ using a combination of other
+ functions. In <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-APPENDIX" title="43.13.3. Appendix">Section 43.13.3</a> there is a
+ <span class="application">PL/pgSQL</span> implementation of
+ <code class="function">instr</code> that you can use to make your porting
+ easier.
+ </p><div class="example" id="PLPGSQL-PORTING-EX3"><p class="title"><strong>Example 43.11. Porting a Procedure With String Manipulation and
+ <code class="literal">OUT</code> Parameters from <span class="application">PL/SQL</span> to
+ <span class="application">PL/pgSQL</span></strong></p><div class="example-contents"><p>
+ The following <span class="productname">Oracle</span> PL/SQL procedure is used
+ to parse a URL and return several elements (host, path, and query).
+ </p><p>
+ This is the Oracle version:
+</p><pre class="programlisting">
+CREATE OR REPLACE PROCEDURE cs_parse_url(
+ v_url IN VARCHAR2,
+ v_host OUT VARCHAR2, -- This will be passed back
+ v_path OUT VARCHAR2, -- This one too
+ v_query OUT VARCHAR2) -- And this one
+IS
+ a_pos1 INTEGER;
+ a_pos2 INTEGER;
+BEGIN
+ v_host := NULL;
+ v_path := NULL;
+ v_query := NULL;
+ a_pos1 := instr(v_url, '//');
+
+ IF a_pos1 = 0 THEN
+ RETURN;
+ END IF;
+ a_pos2 := instr(v_url, '/', a_pos1 + 2);
+ IF a_pos2 = 0 THEN
+ v_host := substr(v_url, a_pos1 + 2);
+ v_path := '/';
+ RETURN;
+ END IF;
+
+ v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
+ a_pos1 := instr(v_url, '?', a_pos2 + 1);
+
+ IF a_pos1 = 0 THEN
+ v_path := substr(v_url, a_pos2);
+ RETURN;
+ END IF;
+
+ v_path := substr(v_url, a_pos2, a_pos1 - a_pos2);
+ v_query := substr(v_url, a_pos1 + 1);
+END;
+/
+show errors;
+</pre><p>
+ </p><p>
+ Here is a possible translation into <span class="application">PL/pgSQL</span>:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION cs_parse_url(
+ v_url IN VARCHAR,
+ v_host OUT VARCHAR, -- This will be passed back
+ v_path OUT VARCHAR, -- This one too
+ v_query OUT VARCHAR) -- And this one
+AS $$
+DECLARE
+ a_pos1 INTEGER;
+ a_pos2 INTEGER;
+BEGIN
+ v_host := NULL;
+ v_path := NULL;
+ v_query := NULL;
+ a_pos1 := instr(v_url, '//');
+
+ IF a_pos1 = 0 THEN
+ RETURN;
+ END IF;
+ a_pos2 := instr(v_url, '/', a_pos1 + 2);
+ IF a_pos2 = 0 THEN
+ v_host := substr(v_url, a_pos1 + 2);
+ v_path := '/';
+ RETURN;
+ END IF;
+
+ v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
+ a_pos1 := instr(v_url, '?', a_pos2 + 1);
+
+ IF a_pos1 = 0 THEN
+ v_path := substr(v_url, a_pos2);
+ RETURN;
+ END IF;
+
+ v_path := substr(v_url, a_pos2, a_pos1 - a_pos2);
+ v_query := substr(v_url, a_pos1 + 1);
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ This function could be used like this:
+</p><pre class="programlisting">
+SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz');
+</pre><p>
+ </p></div></div><br class="example-break" /><p>
+ <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-EX4" title="Example 43.12. Porting a Procedure from PL/SQL to PL/pgSQL">Example 43.12</a> shows how to port a procedure
+ that uses numerous features that are specific to Oracle.
+ </p><div class="example" id="PLPGSQL-PORTING-EX4"><p class="title"><strong>Example 43.12. Porting a Procedure from <span class="application">PL/SQL</span> to <span class="application">PL/pgSQL</span></strong></p><div class="example-contents"><p>
+ The Oracle version:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS
+ a_running_job_count INTEGER;
+BEGIN
+ LOCK TABLE cs_jobs IN EXCLUSIVE MODE;
+
+ SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
+
+ IF a_running_job_count &gt; 0 THEN
+ COMMIT; -- free lock
+ raise_application_error(-20000,
+ 'Unable to create a new job: a job is currently running.');
+ END IF;
+
+ DELETE FROM cs_active_job;
+ INSERT INTO cs_active_job(job_id) VALUES (v_job_id);
+
+ BEGIN
+ INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
+ EXCEPTION
+ WHEN dup_val_on_index THEN NULL; -- don't worry if it already exists
+ END;
+ COMMIT;
+END;
+/
+show errors
+</pre><p>
+ </p><p>
+ This is how we could port this procedure to <span class="application">PL/pgSQL</span>:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id integer) AS $$
+DECLARE
+ a_running_job_count integer;
+BEGIN
+ LOCK TABLE cs_jobs IN EXCLUSIVE MODE;
+
+ SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
+
+ IF a_running_job_count &gt; 0 THEN
+ COMMIT; -- free lock
+ RAISE EXCEPTION 'Unable to create a new job: a job is currently running'; -- <span id="co.plpgsql-porting-raise"></span>(1)
+ END IF;
+
+ DELETE FROM cs_active_job;
+ INSERT INTO cs_active_job(job_id) VALUES (v_job_id);
+
+ BEGIN
+ INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
+ EXCEPTION
+ WHEN unique_violation THEN -- <span id="co.plpgsql-porting-exception"></span>(2)
+ -- don't worry if it already exists
+ END;
+ COMMIT;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+
+ </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co.plpgsql-porting-raise">(1)</a> </p></td><td valign="top" align="left"><p>
+ The syntax of <code class="literal">RAISE</code> is considerably different from
+ Oracle's statement, although the basic case <code class="literal">RAISE</code>
+ <em class="replaceable"><code>exception_name</code></em> works
+ similarly.
+ </p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#co.plpgsql-porting-exception">(2)</a> </p></td><td valign="top" align="left"><p>
+ The exception names supported by <span class="application">PL/pgSQL</span> are
+ different from Oracle's. The set of built-in exception names
+ is much larger (see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>). There
+ is not currently a way to declare user-defined exception names,
+ although you can throw user-chosen SQLSTATE values instead.
+ </p></td></tr></table></div><p>
+ </p></div></div><br class="example-break" /></div><div class="sect2" id="PLPGSQL-PORTING-OTHER"><div class="titlepage"><div><div><h3 class="title">43.13.2. Other Things to Watch For</h3></div></div></div><p>
+ This section explains a few other things to watch for when porting
+ Oracle <span class="application">PL/SQL</span> functions to
+ <span class="productname">PostgreSQL</span>.
+ </p><div class="sect3" id="PLPGSQL-PORTING-EXCEPTIONS"><div class="titlepage"><div><div><h4 class="title">43.13.2.1. Implicit Rollback after Exceptions</h4></div></div></div><p>
+ In <span class="application">PL/pgSQL</span>, when an exception is caught by an
+ <code class="literal">EXCEPTION</code> clause, all database changes since the block's
+ <code class="literal">BEGIN</code> are automatically rolled back. That is, the behavior
+ is equivalent to what you'd get in Oracle with:
+
+</p><pre class="programlisting">
+BEGIN
+ SAVEPOINT s1;
+ ... code here ...
+EXCEPTION
+ WHEN ... THEN
+ ROLLBACK TO s1;
+ ... code here ...
+ WHEN ... THEN
+ ROLLBACK TO s1;
+ ... code here ...
+END;
+</pre><p>
+
+ If you are translating an Oracle procedure that uses
+ <code class="command">SAVEPOINT</code> and <code class="command">ROLLBACK TO</code> in this style,
+ your task is easy: just omit the <code class="command">SAVEPOINT</code> and
+ <code class="command">ROLLBACK TO</code>. If you have a procedure that uses
+ <code class="command">SAVEPOINT</code> and <code class="command">ROLLBACK TO</code> in a different way
+ then some actual thought will be required.
+ </p></div><div class="sect3" id="id-1.8.8.15.7.4"><div class="titlepage"><div><div><h4 class="title">43.13.2.2. <code class="command">EXECUTE</code></h4></div></div></div><p>
+ The <span class="application">PL/pgSQL</span> version of
+ <code class="command">EXECUTE</code> works similarly to the
+ <span class="application">PL/SQL</span> version, but you have to remember to use
+ <code class="function">quote_literal</code> and
+ <code class="function">quote_ident</code> as described in <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN" title="43.5.4. Executing Dynamic Commands">Section 43.5.4</a>. Constructs of the
+ type <code class="literal">EXECUTE 'SELECT * FROM $1';</code> will not work
+ reliably unless you use these functions.
+ </p></div><div class="sect3" id="PLPGSQL-PORTING-OPTIMIZATION"><div class="titlepage"><div><div><h4 class="title">43.13.2.3. Optimizing <span class="application">PL/pgSQL</span> Functions</h4></div></div></div><p>
+ <span class="productname">PostgreSQL</span> gives you two function creation
+ modifiers to optimize execution: <span class="quote">“<span class="quote">volatility</span>”</span> (whether
+ the function always returns the same result when given the same
+ arguments) and <span class="quote">“<span class="quote">strictness</span>”</span> (whether the function
+ returns null if any argument is null). Consult the <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>
+ reference page for details.
+ </p><p>
+ When making use of these optimization attributes, your
+ <code class="command">CREATE FUNCTION</code> statement might look something
+ like this:
+
+</p><pre class="programlisting">
+CREATE FUNCTION foo(...) RETURNS integer AS $$
+...
+$$ LANGUAGE plpgsql STRICT IMMUTABLE;
+</pre><p>
+ </p></div></div><div class="sect2" id="PLPGSQL-PORTING-APPENDIX"><div class="titlepage"><div><div><h3 class="title">43.13.3. Appendix</h3></div></div></div><p>
+ This section contains the code for a set of Oracle-compatible
+ <code class="function">instr</code> functions that you can use to simplify
+ your porting efforts.
+ </p><a id="id-1.8.8.15.8.3" class="indexterm"></a><pre class="programlisting">
+--
+-- instr functions that mimic Oracle's counterpart
+-- Syntax: instr(string1, string2 [, n [, m]])
+-- where [] denotes optional parameters.
+--
+-- Search string1, beginning at the nth character, for the mth occurrence
+-- of string2. If n is negative, search backwards, starting at the abs(n)'th
+-- character from the end of string1.
+-- If n is not passed, assume 1 (search starts at first character).
+-- If m is not passed, assume 1 (find first occurrence).
+-- Returns starting index of string2 in string1, or 0 if string2 is not found.
+--
+
+CREATE FUNCTION instr(varchar, varchar) RETURNS integer AS $$
+BEGIN
+ RETURN instr($1, $2, 1);
+END;
+$$ LANGUAGE plpgsql STRICT IMMUTABLE;
+
+
+CREATE FUNCTION instr(string varchar, string_to_search_for varchar,
+ beg_index integer)
+RETURNS integer AS $$
+DECLARE
+ pos integer NOT NULL DEFAULT 0;
+ temp_str varchar;
+ beg integer;
+ length integer;
+ ss_length integer;
+BEGIN
+ IF beg_index &gt; 0 THEN
+ temp_str := substring(string FROM beg_index);
+ pos := position(string_to_search_for IN temp_str);
+
+ IF pos = 0 THEN
+ RETURN 0;
+ ELSE
+ RETURN pos + beg_index - 1;
+ END IF;
+ ELSIF beg_index &lt; 0 THEN
+ ss_length := char_length(string_to_search_for);
+ length := char_length(string);
+ beg := length + 1 + beg_index;
+
+ WHILE beg &gt; 0 LOOP
+ temp_str := substring(string FROM beg FOR ss_length);
+ IF string_to_search_for = temp_str THEN
+ RETURN beg;
+ END IF;
+
+ beg := beg - 1;
+ END LOOP;
+
+ RETURN 0;
+ ELSE
+ RETURN 0;
+ END IF;
+END;
+$$ LANGUAGE plpgsql STRICT IMMUTABLE;
+
+
+CREATE FUNCTION instr(string varchar, string_to_search_for varchar,
+ beg_index integer, occur_index integer)
+RETURNS integer AS $$
+DECLARE
+ pos integer NOT NULL DEFAULT 0;
+ occur_number integer NOT NULL DEFAULT 0;
+ temp_str varchar;
+ beg integer;
+ i integer;
+ length integer;
+ ss_length integer;
+BEGIN
+ IF occur_index &lt;= 0 THEN
+ RAISE 'argument ''%'' is out of range', occur_index
+ USING ERRCODE = '22003';
+ END IF;
+
+ IF beg_index &gt; 0 THEN
+ beg := beg_index - 1;
+ FOR i IN 1..occur_index LOOP
+ temp_str := substring(string FROM beg + 1);
+ pos := position(string_to_search_for IN temp_str);
+ IF pos = 0 THEN
+ RETURN 0;
+ END IF;
+ beg := beg + pos;
+ END LOOP;
+
+ RETURN beg;
+ ELSIF beg_index &lt; 0 THEN
+ ss_length := char_length(string_to_search_for);
+ length := char_length(string);
+ beg := length + 1 + beg_index;
+
+ WHILE beg &gt; 0 LOOP
+ temp_str := substring(string FROM beg FOR ss_length);
+ IF string_to_search_for = temp_str THEN
+ occur_number := occur_number + 1;
+ IF occur_number = occur_index THEN
+ RETURN beg;
+ END IF;
+ END IF;
+
+ beg := beg - 1;
+ END LOOP;
+
+ RETURN 0;
+ ELSE
+ RETURN 0;
+ END IF;
+END;
+$$ LANGUAGE plpgsql STRICT IMMUTABLE;
+
+</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-development-tips.html" title="43.12. Tips for Developing in PL/pgSQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.12. Tips for Developing in <span class="application">PL/pgSQL</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 44. PL/Tcl — Tcl Procedural Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-statements.html b/doc/src/sgml/html/plpgsql-statements.html
new file mode 100644
index 0000000..39dd1e1
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-statements.html
@@ -0,0 +1,598 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.5. Basic Statements</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-expressions.html" title="43.4. Expressions" /><link rel="next" href="plpgsql-control-structures.html" title="43.6. Control Structures" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.5. Basic Statements</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-expressions.html" title="43.4. Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-control-structures.html" title="43.6. Control Structures">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-STATEMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.5. Basic Statements</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-ASSIGNMENT">43.5.1. Assignment</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-GENERAL-SQL">43.5.2. Executing SQL Commands</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">43.5.3. Executing a Command with a Single-Row Result</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">43.5.4. Executing Dynamic Commands</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS">43.5.5. Obtaining the Result Status</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-NULL">43.5.6. Doing Nothing At All</a></span></dt></dl></div><p>
+ In this section and the following ones, we describe all the statement
+ types that are explicitly understood by
+ <span class="application">PL/pgSQL</span>.
+ Anything not recognized as one of these statement types is presumed
+ to be an SQL command and is sent to the main database engine to execute,
+ as described in <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-GENERAL-SQL" title="43.5.2. Executing SQL Commands">Section 43.5.2</a>.
+ </p><div class="sect2" id="PLPGSQL-STATEMENTS-ASSIGNMENT"><div class="titlepage"><div><div><h3 class="title">43.5.1. Assignment</h3></div></div></div><p>
+ An assignment of a value to a <span class="application">PL/pgSQL</span>
+ variable is written as:
+</p><pre class="synopsis">
+<em class="replaceable"><code>variable</code></em> { := | = } <em class="replaceable"><code>expression</code></em>;
+</pre><p>
+ As explained previously, the expression in such a statement is evaluated
+ by means of an SQL <code class="command">SELECT</code> command sent to the main
+ database engine. The expression must yield a single value (possibly
+ a row value, if the variable is a row or record variable). The target
+ variable can be a simple variable (optionally qualified with a block
+ name), a field of a row or record target, or an element or slice of
+ an array target. Equal (<code class="literal">=</code>) can be
+ used instead of PL/SQL-compliant <code class="literal">:=</code>.
+ </p><p>
+ If the expression's result data type doesn't match the variable's
+ data type, the value will be coerced as though by an assignment cast
+ (see <a class="xref" href="typeconv-query.html" title="10.4. Value Storage">Section 10.4</a>). If no assignment cast is known
+ for the pair of data types involved, the <span class="application">PL/pgSQL</span>
+ interpreter will attempt to convert the result value textually, that is
+ by applying the result type's output function followed by the variable
+ type's input function. Note that this could result in run-time errors
+ generated by the input function, if the string form of the result value
+ is not acceptable to the input function.
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+tax := subtotal * 0.06;
+my_record.user_id := 20;
+my_array[j] := 20;
+my_array[1:3] := array[1,2,3];
+complex_array[n].realpart = 12.3;
+</pre><p>
+ </p></div><div class="sect2" id="PLPGSQL-STATEMENTS-GENERAL-SQL"><div class="titlepage"><div><div><h3 class="title">43.5.2. Executing SQL Commands</h3></div></div></div><p>
+ In general, any SQL command that does not return rows can be executed
+ within a <span class="application">PL/pgSQL</span> function just by writing
+ the command. For example, you could create and fill a table by writing
+</p><pre class="programlisting">
+CREATE TABLE mytable (id int primary key, data text);
+INSERT INTO mytable VALUES (1,'one'), (2,'two');
+</pre><p>
+ </p><p>
+ If the command does return rows (for example <code class="command">SELECT</code>,
+ or <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>
+ with <code class="literal">RETURNING</code>), there are two ways to proceed.
+ When the command will return at most one row, or you only care about
+ the first row of output, write the command as usual but add
+ an <code class="literal">INTO</code> clause to capture the output, as described
+ in <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW" title="43.5.3. Executing a Command with a Single-Row Result">Section 43.5.3</a>.
+ To process all of the output rows, write the command as the data
+ source for a <code class="command">FOR</code> loop, as described in
+ <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-RECORDS-ITERATING" title="43.6.6. Looping through Query Results">Section 43.6.6</a>.
+ </p><p>
+ Usually it is not sufficient just to execute statically-defined SQL
+ commands. Typically you'll want a command to use varying data values,
+ or even to vary in more fundamental ways such as by using different
+ table names at different times. Again, there are two ways to proceed
+ depending on the situation.
+ </p><p>
+ <span class="application">PL/pgSQL</span> variable values can be
+ automatically inserted into optimizable SQL commands, which
+ are <code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">MERGE</code>, and certain
+ utility commands that incorporate one of these, such
+ as <code class="command">EXPLAIN</code> and <code class="command">CREATE TABLE ... AS
+ SELECT</code>. In these commands,
+ any <span class="application">PL/pgSQL</span> variable name appearing
+ in the command text is replaced by a query parameter, and then the
+ current value of the variable is provided as the parameter value
+ at run time. This is exactly like the processing described earlier
+ for expressions; for details see <a class="xref" href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST" title="43.11.1. Variable Substitution">Section 43.11.1</a>.
+ </p><p>
+ When executing an optimizable SQL command in this way,
+ <span class="application">PL/pgSQL</span> may cache and re-use the execution
+ plan for the command, as discussed in
+ <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="43.11.2. Plan Caching">Section 43.11.2</a>.
+ </p><p>
+ Non-optimizable SQL commands (also called utility commands) are not
+ capable of accepting query parameters. So automatic substitution
+ of <span class="application">PL/pgSQL</span> variables does not work in such
+ commands. To include non-constant text in a utility command executed
+ from <span class="application">PL/pgSQL</span>, you must build the utility
+ command as a string and then <code class="command">EXECUTE</code> it, as
+ discussed in <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN" title="43.5.4. Executing Dynamic Commands">Section 43.5.4</a>.
+ </p><p>
+ <code class="command">EXECUTE</code> must also be used if you want to modify
+ the command in some other way than supplying a data value, for example
+ by changing a table name.
+ </p><p>
+ Sometimes it is useful to evaluate an expression or <code class="command">SELECT</code>
+ query but discard the result, for example when calling a function
+ that has side-effects but no useful result value. To do
+ this in <span class="application">PL/pgSQL</span>, use the
+ <code class="command">PERFORM</code> statement:
+
+</p><pre class="synopsis">
+PERFORM <em class="replaceable"><code>query</code></em>;
+</pre><p>
+
+ This executes <em class="replaceable"><code>query</code></em> and discards the
+ result. Write the <em class="replaceable"><code>query</code></em> the same
+ way you would write an SQL <code class="command">SELECT</code> command, but replace the
+ initial keyword <code class="command">SELECT</code> with <code class="command">PERFORM</code>.
+ For <code class="command">WITH</code> queries, use <code class="command">PERFORM</code> and then
+ place the query in parentheses. (In this case, the query can only
+ return one row.)
+ <span class="application">PL/pgSQL</span> variables will be
+ substituted into the query just as described above,
+ and the plan is cached in the same way. Also, the special variable
+ <code class="literal">FOUND</code> is set to true if the query produced at
+ least one row, or false if it produced no rows (see
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS" title="43.5.5. Obtaining the Result Status">Section 43.5.5</a>).
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ One might expect that writing <code class="command">SELECT</code> directly
+ would accomplish this result, but at
+ present the only accepted way to do it is
+ <code class="command">PERFORM</code>. An SQL command that can return rows,
+ such as <code class="command">SELECT</code>, will be rejected as an error
+ unless it has an <code class="literal">INTO</code> clause as discussed in the
+ next section.
+ </p></div><p>
+ An example:
+</p><pre class="programlisting">
+PERFORM create_mv('cs_session_page_requests_mv', my_query);
+</pre><p>
+ </p></div><div class="sect2" id="PLPGSQL-STATEMENTS-SQL-ONEROW"><div class="titlepage"><div><div><h3 class="title">43.5.3. Executing a Command with a Single-Row Result</h3></div></div></div><a id="id-1.8.8.7.5.2" class="indexterm"></a><a id="id-1.8.8.7.5.3" class="indexterm"></a><p>
+ The result of an SQL command yielding a single row (possibly of multiple
+ columns) can be assigned to a record variable, row-type variable, or list
+ of scalar variables. This is done by writing the base SQL command and
+ adding an <code class="literal">INTO</code> clause. For example,
+
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_expressions</code></em> INTO [<span class="optional">STRICT</span>] <em class="replaceable"><code>target</code></em> FROM ...;
+INSERT ... RETURNING <em class="replaceable"><code>expressions</code></em> INTO [<span class="optional">STRICT</span>] <em class="replaceable"><code>target</code></em>;
+UPDATE ... RETURNING <em class="replaceable"><code>expressions</code></em> INTO [<span class="optional">STRICT</span>] <em class="replaceable"><code>target</code></em>;
+DELETE ... RETURNING <em class="replaceable"><code>expressions</code></em> INTO [<span class="optional">STRICT</span>] <em class="replaceable"><code>target</code></em>;
+</pre><p>
+
+ where <em class="replaceable"><code>target</code></em> can be a record variable, a row
+ variable, or a comma-separated list of simple variables and
+ record/row fields.
+ <span class="application">PL/pgSQL</span> variables will be
+ substituted into the rest of the command (that is, everything but the
+ <code class="literal">INTO</code> clause) just as described above,
+ and the plan is cached in the same way.
+ This works for <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code> with
+ <code class="literal">RETURNING</code>, and certain utility commands
+ that return row sets, such as <code class="command">EXPLAIN</code>.
+ Except for the <code class="literal">INTO</code> clause, the SQL command is the same
+ as it would be written outside <span class="application">PL/pgSQL</span>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Note that this interpretation of <code class="command">SELECT</code> with <code class="literal">INTO</code>
+ is quite different from <span class="productname">PostgreSQL</span>'s regular
+ <code class="command">SELECT INTO</code> command, wherein the <code class="literal">INTO</code>
+ target is a newly created table. If you want to create a table from a
+ <code class="command">SELECT</code> result inside a
+ <span class="application">PL/pgSQL</span> function, use the syntax
+ <code class="command">CREATE TABLE ... AS SELECT</code>.
+ </p></div><p>
+ If a row variable or a variable list is used as target,
+ the command's result columns
+ must exactly match the structure of the target as to number and data
+ types, or else a run-time error
+ occurs. When a record variable is the target, it automatically
+ configures itself to the row type of the command's result columns.
+ </p><p>
+ The <code class="literal">INTO</code> clause can appear almost anywhere in the SQL
+ command. Customarily it is written either just before or just after
+ the list of <em class="replaceable"><code>select_expressions</code></em> in a
+ <code class="command">SELECT</code> command, or at the end of the command for other
+ command types. It is recommended that you follow this convention
+ in case the <span class="application">PL/pgSQL</span> parser becomes
+ stricter in future versions.
+ </p><p>
+ If <code class="literal">STRICT</code> is not specified in the <code class="literal">INTO</code>
+ clause, then <em class="replaceable"><code>target</code></em> will be set to the first
+ row returned by the command, or to nulls if the command returned no rows.
+ (Note that <span class="quote">“<span class="quote">the first row</span>”</span> is not
+ well-defined unless you've used <code class="literal">ORDER BY</code>.) Any result rows
+ after the first row are discarded.
+ You can check the special <code class="literal">FOUND</code> variable (see
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS" title="43.5.5. Obtaining the Result Status">Section 43.5.5</a>) to
+ determine whether a row was returned:
+
+</p><pre class="programlisting">
+SELECT * INTO myrec FROM emp WHERE empname = myname;
+IF NOT FOUND THEN
+ RAISE EXCEPTION 'employee % not found', myname;
+END IF;
+</pre><p>
+
+ If the <code class="literal">STRICT</code> option is specified, the command must
+ return exactly one row or a run-time error will be reported, either
+ <code class="literal">NO_DATA_FOUND</code> (no rows) or <code class="literal">TOO_MANY_ROWS</code>
+ (more than one row). You can use an exception block if you wish
+ to catch the error, for example:
+
+</p><pre class="programlisting">
+BEGIN
+ SELECT * INTO STRICT myrec FROM emp WHERE empname = myname;
+ EXCEPTION
+ WHEN NO_DATA_FOUND THEN
+ RAISE EXCEPTION 'employee % not found', myname;
+ WHEN TOO_MANY_ROWS THEN
+ RAISE EXCEPTION 'employee % not unique', myname;
+END;
+</pre><p>
+ Successful execution of a command with <code class="literal">STRICT</code>
+ always sets <code class="literal">FOUND</code> to true.
+ </p><p>
+ For <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code> with
+ <code class="literal">RETURNING</code>, <span class="application">PL/pgSQL</span> reports
+ an error for more than one returned row, even when
+ <code class="literal">STRICT</code> is not specified. This is because there
+ is no option such as <code class="literal">ORDER BY</code> with which to determine
+ which affected row should be returned.
+ </p><p>
+ If <code class="literal">print_strict_params</code> is enabled for the function,
+ then when an error is thrown because the requirements
+ of <code class="literal">STRICT</code> are not met, the <code class="literal">DETAIL</code> part of
+ the error message will include information about the parameters
+ passed to the command.
+ You can change the <code class="literal">print_strict_params</code>
+ setting for all functions by setting
+ <code class="varname">plpgsql.print_strict_params</code>, though only subsequent
+ function compilations will be affected. You can also enable it
+ on a per-function basis by using a compiler option, for example:
+</p><pre class="programlisting">
+CREATE FUNCTION get_userid(username text) RETURNS int
+AS $$
+#print_strict_params on
+DECLARE
+userid int;
+BEGIN
+ SELECT users.userid INTO STRICT userid
+ FROM users WHERE users.username = get_userid.username;
+ RETURN userid;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ On failure, this function might produce an error message such as
+</p><pre class="programlisting">
+ERROR: query returned no rows
+DETAIL: parameters: $1 = 'nosuchuser'
+CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="literal">STRICT</code> option matches the behavior of
+ Oracle PL/SQL's <code class="command">SELECT INTO</code> and related statements.
+ </p></div></div><div class="sect2" id="PLPGSQL-STATEMENTS-EXECUTING-DYN"><div class="titlepage"><div><div><h3 class="title">43.5.4. Executing Dynamic Commands</h3></div></div></div><p>
+ Oftentimes you will want to generate dynamic commands inside your
+ <span class="application">PL/pgSQL</span> functions, that is, commands
+ that will involve different tables or different data types each
+ time they are executed. <span class="application">PL/pgSQL</span>'s
+ normal attempts to cache plans for commands (as discussed in
+ <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="43.11.2. Plan Caching">Section 43.11.2</a>) will not work in such
+ scenarios. To handle this sort of problem, the
+ <code class="command">EXECUTE</code> statement is provided:
+
+</p><pre class="synopsis">
+EXECUTE <em class="replaceable"><code>command-string</code></em> [<span class="optional"> INTO [<span class="optional">STRICT</span>] <em class="replaceable"><code>target</code></em> </span>] [<span class="optional"> USING <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
+</pre><p>
+
+ where <em class="replaceable"><code>command-string</code></em> is an expression
+ yielding a string (of type <code class="type">text</code>) containing the
+ command to be executed. The optional <em class="replaceable"><code>target</code></em>
+ is a record variable, a row variable, or a comma-separated list of
+ simple variables and record/row fields, into which the results of
+ the command will be stored. The optional <code class="literal">USING</code> expressions
+ supply values to be inserted into the command.
+ </p><p>
+ No substitution of <span class="application">PL/pgSQL</span> variables is done on the
+ computed command string. Any required variable values must be inserted
+ in the command string as it is constructed; or you can use parameters
+ as described below.
+ </p><p>
+ Also, there is no plan caching for commands executed via
+ <code class="command">EXECUTE</code>. Instead, the command is always planned
+ each time the statement is run. Thus the command
+ string can be dynamically created within the function to perform
+ actions on different tables and columns.
+ </p><p>
+ The <code class="literal">INTO</code> clause specifies where the results of
+ an SQL command returning rows should be assigned. If a row variable
+ or variable list is provided, it must exactly match the structure
+ of the command's results; if a
+ record variable is provided, it will configure itself to match the
+ result structure automatically. If multiple rows are returned,
+ only the first will be assigned to the <code class="literal">INTO</code>
+ variable(s). If no rows are returned, NULL is assigned to the
+ <code class="literal">INTO</code> variable(s). If no <code class="literal">INTO</code>
+ clause is specified, the command results are discarded.
+ </p><p>
+ If the <code class="literal">STRICT</code> option is given, an error is reported
+ unless the command produces exactly one row.
+ </p><p>
+ The command string can use parameter values, which are referenced
+ in the command as <code class="literal">$1</code>, <code class="literal">$2</code>, etc.
+ These symbols refer to values supplied in the <code class="literal">USING</code>
+ clause. This method is often preferable to inserting data values
+ into the command string as text: it avoids run-time overhead of
+ converting the values to text and back, and it is much less prone
+ to SQL-injection attacks since there is no need for quoting or escaping.
+ An example is:
+</p><pre class="programlisting">
+EXECUTE 'SELECT count(*) FROM mytable WHERE inserted_by = $1 AND inserted &lt;= $2'
+ INTO c
+ USING checked_user, checked_date;
+</pre><p>
+ </p><p>
+ Note that parameter symbols can only be used for data values
+ — if you want to use dynamically determined table or column
+ names, you must insert them into the command string textually.
+ For example, if the preceding query needed to be done against a
+ dynamically selected table, you could do this:
+</p><pre class="programlisting">
+EXECUTE 'SELECT count(*) FROM '
+ || quote_ident(tabname)
+ || ' WHERE inserted_by = $1 AND inserted &lt;= $2'
+ INTO c
+ USING checked_user, checked_date;
+</pre><p>
+ A cleaner approach is to use <code class="function">format()</code>'s <code class="literal">%I</code>
+ specification to insert table or column names with automatic quoting:
+</p><pre class="programlisting">
+EXECUTE format('SELECT count(*) FROM %I '
+ 'WHERE inserted_by = $1 AND inserted &lt;= $2', tabname)
+ INTO c
+ USING checked_user, checked_date;
+</pre><p>
+ (This example relies on the SQL rule that string literals separated by a
+ newline are implicitly concatenated.)
+ </p><p>
+ Another restriction on parameter symbols is that they only work in
+ optimizable SQL commands
+ (<code class="command">SELECT</code>, <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">MERGE</code>, and certain commands containing one of these).
+ In other statement
+ types (generically called utility statements), you must insert
+ values textually even if they are just data values.
+ </p><p>
+ An <code class="command">EXECUTE</code> with a simple constant command string and some
+ <code class="literal">USING</code> parameters, as in the first example above, is
+ functionally equivalent to just writing the command directly in
+ <span class="application">PL/pgSQL</span> and allowing replacement of
+ <span class="application">PL/pgSQL</span> variables to happen automatically.
+ The important difference is that <code class="command">EXECUTE</code> will re-plan
+ the command on each execution, generating a plan that is specific
+ to the current parameter values; whereas
+ <span class="application">PL/pgSQL</span> may otherwise create a generic plan
+ and cache it for re-use. In situations where the best plan depends
+ strongly on the parameter values, it can be helpful to use
+ <code class="command">EXECUTE</code> to positively ensure that a generic plan is not
+ selected.
+ </p><p>
+ <code class="command">SELECT INTO</code> is not currently supported within
+ <code class="command">EXECUTE</code>; instead, execute a plain <code class="command">SELECT</code>
+ command and specify <code class="literal">INTO</code> as part of the <code class="command">EXECUTE</code>
+ itself.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <span class="application">PL/pgSQL</span>
+ <code class="command">EXECUTE</code> statement is not related to the
+ <a class="link" href="sql-execute.html" title="EXECUTE"><code class="command">EXECUTE</code></a> SQL
+ statement supported by the
+ <span class="productname">PostgreSQL</span> server. The server's
+ <code class="command">EXECUTE</code> statement cannot be used directly within
+ <span class="application">PL/pgSQL</span> functions (and is not needed).
+ </p></div><div class="example" id="PLPGSQL-QUOTE-LITERAL-EXAMPLE"><p class="title"><strong>Example 43.1. Quoting Values in Dynamic Queries</strong></p><div class="example-contents"><a id="id-1.8.8.7.6.13.2" class="indexterm"></a><a id="id-1.8.8.7.6.13.3" class="indexterm"></a><a id="id-1.8.8.7.6.13.4" class="indexterm"></a><a id="id-1.8.8.7.6.13.5" class="indexterm"></a><p>
+ When working with dynamic commands you will often have to handle escaping
+ of single quotes. The recommended method for quoting fixed text in your
+ function body is dollar quoting. (If you have legacy code that does
+ not use dollar quoting, please refer to the
+ overview in <a class="xref" href="plpgsql-development-tips.html#PLPGSQL-QUOTE-TIPS" title="43.12.1. Handling of Quotation Marks">Section 43.12.1</a>, which can save you
+ some effort when translating said code to a more reasonable scheme.)
+ </p><p>
+ Dynamic values require careful handling since they might contain
+ quote characters.
+ An example using <code class="function">format()</code> (this assumes that you are
+ dollar quoting the function body so quote marks need not be doubled):
+</p><pre class="programlisting">
+EXECUTE format('UPDATE tbl SET %I = $1 '
+ 'WHERE key = $2', colname) USING newvalue, keyvalue;
+</pre><p>
+ It is also possible to call the quoting functions directly:
+</p><pre class="programlisting">
+EXECUTE 'UPDATE tbl SET '
+ || quote_ident(colname)
+ || ' = '
+ || quote_literal(newvalue)
+ || ' WHERE key = '
+ || quote_literal(keyvalue);
+</pre><p>
+ </p><p>
+ This example demonstrates the use of the
+ <code class="function">quote_ident</code> and
+ <code class="function">quote_literal</code> functions (see <a class="xref" href="functions-string.html" title="9.4. String Functions and Operators">Section 9.4</a>). For safety, expressions containing column
+ or table identifiers should be passed through
+ <code class="function">quote_ident</code> before insertion in a dynamic query.
+ Expressions containing values that should be literal strings in the
+ constructed command should be passed through <code class="function">quote_literal</code>.
+ These functions take the appropriate steps to return the input text
+ enclosed in double or single quotes respectively, with any embedded
+ special characters properly escaped.
+ </p><p>
+ Because <code class="function">quote_literal</code> is labeled
+ <code class="literal">STRICT</code>, it will always return null when called with a
+ null argument. In the above example, if <code class="literal">newvalue</code> or
+ <code class="literal">keyvalue</code> were null, the entire dynamic query string would
+ become null, leading to an error from <code class="command">EXECUTE</code>.
+ You can avoid this problem by using the <code class="function">quote_nullable</code>
+ function, which works the same as <code class="function">quote_literal</code> except that
+ when called with a null argument it returns the string <code class="literal">NULL</code>.
+ For example,
+</p><pre class="programlisting">
+EXECUTE 'UPDATE tbl SET '
+ || quote_ident(colname)
+ || ' = '
+ || quote_nullable(newvalue)
+ || ' WHERE key = '
+ || quote_nullable(keyvalue);
+</pre><p>
+ If you are dealing with values that might be null, you should usually
+ use <code class="function">quote_nullable</code> in place of <code class="function">quote_literal</code>.
+ </p><p>
+ As always, care must be taken to ensure that null values in a query do
+ not deliver unintended results. For example the <code class="literal">WHERE</code> clause
+</p><pre class="programlisting">
+'WHERE key = ' || quote_nullable(keyvalue)
+</pre><p>
+ will never succeed if <code class="literal">keyvalue</code> is null, because the
+ result of using the equality operator <code class="literal">=</code> with a null operand
+ is always null. If you wish null to work like an ordinary key value,
+ you would need to rewrite the above as
+</p><pre class="programlisting">
+'WHERE key IS NOT DISTINCT FROM ' || quote_nullable(keyvalue)
+</pre><p>
+ (At present, <code class="literal">IS NOT DISTINCT FROM</code> is handled much less
+ efficiently than <code class="literal">=</code>, so don't do this unless you must.
+ See <a class="xref" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Section 9.2</a> for
+ more information on nulls and <code class="literal">IS DISTINCT</code>.)
+ </p><p>
+ Note that dollar quoting is only useful for quoting fixed text.
+ It would be a very bad idea to try to write this example as:
+</p><pre class="programlisting">
+EXECUTE 'UPDATE tbl SET '
+ || quote_ident(colname)
+ || ' = $$'
+ || newvalue
+ || '$$ WHERE key = '
+ || quote_literal(keyvalue);
+</pre><p>
+ because it would break if the contents of <code class="literal">newvalue</code>
+ happened to contain <code class="literal">$$</code>. The same objection would
+ apply to any other dollar-quoting delimiter you might pick.
+ So, to safely quote text that is not known in advance, you
+ <span class="emphasis"><em>must</em></span> use <code class="function">quote_literal</code>,
+ <code class="function">quote_nullable</code>, or <code class="function">quote_ident</code>, as appropriate.
+ </p><p>
+ Dynamic SQL statements can also be safely constructed using the
+ <code class="function">format</code> function (see <a class="xref" href="functions-string.html#FUNCTIONS-STRING-FORMAT" title="9.4.1. format">Section 9.4.1</a>). For example:
+</p><pre class="programlisting">
+EXECUTE format('UPDATE tbl SET %I = %L '
+ 'WHERE key = %L', colname, newvalue, keyvalue);
+</pre><p>
+ <code class="literal">%I</code> is equivalent to <code class="function">quote_ident</code>, and
+ <code class="literal">%L</code> is equivalent to <code class="function">quote_nullable</code>.
+ The <code class="function">format</code> function can be used in conjunction with
+ the <code class="literal">USING</code> clause:
+</p><pre class="programlisting">
+EXECUTE format('UPDATE tbl SET %I = $1 WHERE key = $2', colname)
+ USING newvalue, keyvalue;
+</pre><p>
+ This form is better because the variables are handled in their native
+ data type format, rather than unconditionally converting them to
+ text and quoting them via <code class="literal">%L</code>. It is also more efficient.
+ </p></div></div><br class="example-break" /><p>
+ A much larger example of a dynamic command and
+ <code class="command">EXECUTE</code> can be seen in <a class="xref" href="plpgsql-porting.html#PLPGSQL-PORTING-EX2" title="Example 43.10. Porting a Function that Creates Another Function from PL/SQL to PL/pgSQL">Example 43.10</a>, which builds and executes a
+ <code class="command">CREATE FUNCTION</code> command to define a new function.
+ </p></div><div class="sect2" id="PLPGSQL-STATEMENTS-DIAGNOSTICS"><div class="titlepage"><div><div><h3 class="title">43.5.5. Obtaining the Result Status</h3></div></div></div><p>
+ There are several ways to determine the effect of a command. The
+ first method is to use the <code class="command">GET DIAGNOSTICS</code>
+ command, which has the form:
+
+</p><pre class="synopsis">
+GET [<span class="optional"> CURRENT </span>] DIAGNOSTICS <em class="replaceable"><code>variable</code></em> { = | := } <em class="replaceable"><code>item</code></em> [<span class="optional"> , ... </span>];
+</pre><p>
+
+ This command allows retrieval of system status indicators.
+ <code class="literal">CURRENT</code> is a noise word (but see also <code class="command">GET STACKED
+ DIAGNOSTICS</code> in <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-EXCEPTION-DIAGNOSTICS" title="43.6.8.1. Obtaining Information about an Error">Section 43.6.8.1</a>).
+ Each <em class="replaceable"><code>item</code></em> is a key word identifying a status
+ value to be assigned to the specified <em class="replaceable"><code>variable</code></em>
+ (which should be of the right data type to receive it). The currently
+ available status items are shown
+ in <a class="xref" href="plpgsql-statements.html#PLPGSQL-CURRENT-DIAGNOSTICS-VALUES" title="Table 43.1. Available Diagnostics Items">Table 43.1</a>. Colon-equal
+ (<code class="literal">:=</code>) can be used instead of the SQL-standard <code class="literal">=</code>
+ token. An example:
+</p><pre class="programlisting">
+GET DIAGNOSTICS integer_var = ROW_COUNT;
+</pre><p>
+ </p><div class="table" id="PLPGSQL-CURRENT-DIAGNOSTICS-VALUES"><p class="title"><strong>Table 43.1. Available Diagnostics Items</strong></p><div class="table-contents"><table class="table" summary="Available Diagnostics Items" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="varname">ROW_COUNT</code></td><td><code class="type">bigint</code></td><td>the number of rows processed by the most
+ recent <acronym class="acronym">SQL</acronym> command</td></tr><tr><td><code class="literal">PG_CONTEXT</code></td><td><code class="type">text</code></td><td>line(s) of text describing the current call stack
+ (see <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-CALL-STACK" title="43.6.9. Obtaining Execution Location Information">Section 43.6.9</a>)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The second method to determine the effects of a command is to check the
+ special variable named <code class="literal">FOUND</code>, which is of
+ type <code class="type">boolean</code>. <code class="literal">FOUND</code> starts out
+ false within each <span class="application">PL/pgSQL</span> function call.
+ It is set by each of the following types of statements:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A <code class="command">SELECT INTO</code> statement sets
+ <code class="literal">FOUND</code> true if a row is assigned, false if no
+ row is returned.
+ </p></li><li class="listitem"><p>
+ A <code class="command">PERFORM</code> statement sets <code class="literal">FOUND</code>
+ true if it produces (and discards) one or more rows, false if
+ no row is produced.
+ </p></li><li class="listitem"><p>
+ <code class="command">UPDATE</code>, <code class="command">INSERT</code>, <code class="command">DELETE</code>,
+ and <code class="command">MERGE</code>
+ statements set <code class="literal">FOUND</code> true if at least one
+ row is affected, false if no row is affected.
+ </p></li><li class="listitem"><p>
+ A <code class="command">FETCH</code> statement sets <code class="literal">FOUND</code>
+ true if it returns a row, false if no row is returned.
+ </p></li><li class="listitem"><p>
+ A <code class="command">MOVE</code> statement sets <code class="literal">FOUND</code>
+ true if it successfully repositions the cursor, false otherwise.
+ </p></li><li class="listitem"><p>
+ A <code class="command">FOR</code> or <code class="command">FOREACH</code> statement sets
+ <code class="literal">FOUND</code> true
+ if it iterates one or more times, else false.
+ <code class="literal">FOUND</code> is set this way when the
+ loop exits; inside the execution of the loop,
+ <code class="literal">FOUND</code> is not modified by the
+ loop statement, although it might be changed by the
+ execution of other statements within the loop body.
+ </p></li><li class="listitem"><p>
+ <code class="command">RETURN QUERY</code> and <code class="command">RETURN QUERY
+ EXECUTE</code> statements set <code class="literal">FOUND</code>
+ true if the query returns at least one row, false if no row
+ is returned.
+ </p></li></ul></div><p>
+
+ Other <span class="application">PL/pgSQL</span> statements do not change
+ the state of <code class="literal">FOUND</code>.
+ Note in particular that <code class="command">EXECUTE</code>
+ changes the output of <code class="command">GET DIAGNOSTICS</code>, but
+ does not change <code class="literal">FOUND</code>.
+ </p><p>
+ <code class="literal">FOUND</code> is a local variable within each
+ <span class="application">PL/pgSQL</span> function; any changes to it
+ affect only the current function.
+ </p></div><div class="sect2" id="PLPGSQL-STATEMENTS-NULL"><div class="titlepage"><div><div><h3 class="title">43.5.6. Doing Nothing At All</h3></div></div></div><p>
+ Sometimes a placeholder statement that does nothing is useful.
+ For example, it can indicate that one arm of an if/then/else
+ chain is deliberately empty. For this purpose, use the
+ <code class="command">NULL</code> statement:
+
+</p><pre class="synopsis">
+NULL;
+</pre><p>
+ </p><p>
+ For example, the following two fragments of code are equivalent:
+</p><pre class="programlisting">
+BEGIN
+ y := x / 0;
+EXCEPTION
+ WHEN division_by_zero THEN
+ NULL; -- ignore the error
+END;
+</pre><p>
+
+</p><pre class="programlisting">
+BEGIN
+ y := x / 0;
+EXCEPTION
+ WHEN division_by_zero THEN -- ignore the error
+END;
+</pre><p>
+ Which is preferable is a matter of taste.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In Oracle's PL/SQL, empty statement lists are not allowed, and so
+ <code class="command">NULL</code> statements are <span class="emphasis"><em>required</em></span> for situations
+ such as this. <span class="application">PL/pgSQL</span> allows you to
+ just write nothing, instead.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-expressions.html" title="43.4. Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-control-structures.html" title="43.6. Control Structures">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.4. Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.6. Control Structures</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-structure.html b/doc/src/sgml/html/plpgsql-structure.html
new file mode 100644
index 0000000..1a0fefb
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-structure.html
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.2. Structure of PL/pgSQL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-overview.html" title="43.1. Overview" /><link rel="next" href="plpgsql-declarations.html" title="43.3. Declarations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.2. Structure of <span class="application">PL/pgSQL</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-overview.html" title="43.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-declarations.html" title="43.3. Declarations">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-STRUCTURE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.2. Structure of <span class="application">PL/pgSQL</span></h2></div></div></div><p>
+ Functions written in <span class="application">PL/pgSQL</span> are defined
+ to the server by executing <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> commands.
+ Such a command would normally look like, say,
+</p><pre class="programlisting">
+CREATE FUNCTION somefunc(integer, text) RETURNS integer
+AS '<em class="replaceable"><code>function body text</code></em>'
+LANGUAGE plpgsql;
+</pre><p>
+ The function body is simply a string literal so far as <code class="command">CREATE
+ FUNCTION</code> is concerned. It is often helpful to use dollar quoting
+ (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) to write the function
+ body, rather than the normal single quote syntax. Without dollar quoting,
+ any single quotes or backslashes in the function body must be escaped by
+ doubling them. Almost all the examples in this chapter use dollar-quoted
+ literals for their function bodies.
+ </p><p>
+ <span class="application">PL/pgSQL</span> is a block-structured language.
+ The complete text of a function body must be a
+ <em class="firstterm">block</em>. A block is defined as:
+
+</p><pre class="synopsis">
+[<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
+[<span class="optional"> DECLARE
+ <em class="replaceable"><code>declarations</code></em> </span>]
+BEGIN
+ <em class="replaceable"><code>statements</code></em>
+END [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
+</pre><p>
+ </p><p>
+ Each declaration and each statement within a block is terminated
+ by a semicolon. A block that appears within another block must
+ have a semicolon after <code class="literal">END</code>, as shown above;
+ however the final <code class="literal">END</code> that
+ concludes a function body does not require a semicolon.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ A common mistake is to write a semicolon immediately after
+ <code class="literal">BEGIN</code>. This is incorrect and will result in a syntax error.
+ </p></div><p>
+ A <em class="replaceable"><code>label</code></em> is only needed if you want to
+ identify the block for use
+ in an <code class="literal">EXIT</code> statement, or to qualify the names of the
+ variables declared in the block. If a label is given after
+ <code class="literal">END</code>, it must match the label at the block's beginning.
+ </p><p>
+ All key words are case-insensitive.
+ Identifiers are implicitly converted to lower case
+ unless double-quoted, just as they are in ordinary SQL commands.
+ </p><p>
+ Comments work the same way in <span class="application">PL/pgSQL</span> code as in
+ ordinary SQL. A double dash (<code class="literal">--</code>) starts a comment
+ that extends to the end of the line. A <code class="literal">/*</code> starts a
+ block comment that extends to the matching occurrence of
+ <code class="literal">*/</code>. Block comments nest.
+ </p><p>
+ Any statement in the statement section of a block
+ can be a <em class="firstterm">subblock</em>. Subblocks can be used for
+ logical grouping or to localize variables to a small group
+ of statements. Variables declared in a subblock mask any
+ similarly-named variables of outer blocks for the duration
+ of the subblock; but you can access the outer variables anyway
+ if you qualify their names with their block's label. For example:
+</p><pre class="programlisting">
+CREATE FUNCTION somefunc() RETURNS integer AS $$
+&lt;&lt; outerblock &gt;&gt;
+DECLARE
+ quantity integer := 30;
+BEGIN
+ RAISE NOTICE 'Quantity here is %', quantity; -- Prints 30
+ quantity := 50;
+ --
+ -- Create a subblock
+ --
+ DECLARE
+ quantity integer := 80;
+ BEGIN
+ RAISE NOTICE 'Quantity here is %', quantity; -- Prints 80
+ RAISE NOTICE 'Outer quantity here is %', outerblock.quantity; -- Prints 50
+ END;
+
+ RAISE NOTICE 'Quantity here is %', quantity; -- Prints 50
+
+ RETURN quantity;
+END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ There is actually a hidden <span class="quote">“<span class="quote">outer block</span>”</span> surrounding the body
+ of any <span class="application">PL/pgSQL</span> function. This block provides the
+ declarations of the function's parameters (if any), as well as some
+ special variables such as <code class="literal">FOUND</code> (see
+ <a class="xref" href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS" title="43.5.5. Obtaining the Result Status">Section 43.5.5</a>). The outer block is
+ labeled with the function's name, meaning that parameters and special
+ variables can be qualified with the function's name.
+ </p></div><p>
+ It is important not to confuse the use of
+ <code class="command">BEGIN</code>/<code class="command">END</code> for grouping statements in
+ <span class="application">PL/pgSQL</span> with the similarly-named SQL commands
+ for transaction
+ control. <span class="application">PL/pgSQL</span>'s <code class="command">BEGIN</code>/<code class="command">END</code>
+ are only for grouping; they do not start or end a transaction.
+ See <a class="xref" href="plpgsql-transactions.html" title="43.8. Transaction Management">Section 43.8</a> for information on managing
+ transactions in <span class="application">PL/pgSQL</span>.
+ Also, a block containing an <code class="literal">EXCEPTION</code> clause effectively
+ forms a subtransaction that can be rolled back without affecting the
+ outer transaction. For more about that see <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING" title="43.6.8. Trapping Errors">Section 43.6.8</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-overview.html" title="43.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-declarations.html" title="43.3. Declarations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.3. Declarations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-transactions.html b/doc/src/sgml/html/plpgsql-transactions.html
new file mode 100644
index 0000000..33d3281
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-transactions.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.8. Transaction Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-cursors.html" title="43.7. Cursors" /><link rel="next" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.8. Transaction Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-cursors.html" title="43.7. Cursors">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-TRANSACTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.8. Transaction Management</h2></div></div></div><p>
+ In procedures invoked by the <code class="command">CALL</code> command
+ as well as in anonymous code blocks (<code class="command">DO</code> command),
+ it is possible to end transactions using the
+ commands <code class="command">COMMIT</code> and <code class="command">ROLLBACK</code>. A new
+ transaction is started automatically after a transaction is ended using
+ these commands, so there is no separate <code class="command">START
+ TRANSACTION</code> command. (Note that <code class="command">BEGIN</code> and
+ <code class="command">END</code> have different meanings in PL/pgSQL.)
+ </p><p>
+ Here is a simple example:
+</p><pre class="programlisting">
+CREATE PROCEDURE transaction_test1()
+LANGUAGE plpgsql
+AS $$
+BEGIN
+ FOR i IN 0..9 LOOP
+ INSERT INTO test1 (a) VALUES (i);
+ IF i % 2 = 0 THEN
+ COMMIT;
+ ELSE
+ ROLLBACK;
+ END IF;
+ END LOOP;
+END;
+$$;
+
+CALL transaction_test1();
+</pre><p>
+ </p><a id="id-1.8.8.10.4" class="indexterm"></a><p id="PLPGSQL-TRANSACTION-CHAIN">
+ A new transaction starts out with default transaction characteristics such
+ as transaction isolation level. In cases where transactions are committed
+ in a loop, it might be desirable to start new transactions automatically
+ with the same characteristics as the previous one. The commands
+ <code class="command">COMMIT AND CHAIN</code> and <code class="command">ROLLBACK AND
+ CHAIN</code> accomplish this.
+ </p><p>
+ Transaction control is only possible in <code class="command">CALL</code> or
+ <code class="command">DO</code> invocations from the top level or nested
+ <code class="command">CALL</code> or <code class="command">DO</code> invocations without any
+ other intervening command. For example, if the call stack is
+ <code class="command">CALL proc1()</code> → <code class="command">CALL proc2()</code>
+ → <code class="command">CALL proc3()</code>, then the second and third
+ procedures can perform transaction control actions. But if the call stack
+ is <code class="command">CALL proc1()</code> → <code class="command">SELECT
+ func2()</code> → <code class="command">CALL proc3()</code>, then the last
+ procedure cannot do transaction control, because of the
+ <code class="command">SELECT</code> in between.
+ </p><p>
+ Special considerations apply to cursor loops. Consider this example:
+</p><pre class="programlisting">
+CREATE PROCEDURE transaction_test2()
+LANGUAGE plpgsql
+AS $$
+DECLARE
+ r RECORD;
+BEGIN
+ FOR r IN SELECT * FROM test2 ORDER BY x LOOP
+ INSERT INTO test1 (a) VALUES (r.x);
+ COMMIT;
+ END LOOP;
+END;
+$$;
+
+CALL transaction_test2();
+</pre><p>
+ Normally, cursors are automatically closed at transaction commit.
+ However, a cursor created as part of a loop like this is automatically
+ converted to a holdable cursor by the first <code class="command">COMMIT</code> or
+ <code class="command">ROLLBACK</code>. That means that the cursor is fully
+ evaluated at the first <code class="command">COMMIT</code> or
+ <code class="command">ROLLBACK</code> rather than row by row. The cursor is still
+ removed automatically after the loop, so this is mostly invisible to the
+ user.
+ </p><p>
+ Transaction commands are not allowed in cursor loops driven by commands
+ that are not read-only (for example <code class="command">UPDATE
+ ... RETURNING</code>).
+ </p><p>
+ A transaction cannot be ended inside a block with exception handlers.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-cursors.html" title="43.7. Cursors">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.7. Cursors </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.9. Errors and Messages</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql-trigger.html b/doc/src/sgml/html/plpgsql-trigger.html
new file mode 100644
index 0000000..6a07fc1
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql-trigger.html
@@ -0,0 +1,516 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>43.10. Trigger Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages" /><link rel="next" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">43.10. Trigger Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">43.10. Trigger Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-trigger.html#PLPGSQL-DML-TRIGGER">43.10.1. Triggers on Data Changes</a></span></dt><dt><span class="sect2"><a href="plpgsql-trigger.html#PLPGSQL-EVENT-TRIGGER">43.10.2. Triggers on Events</a></span></dt></dl></div><a id="id-1.8.8.12.2" class="indexterm"></a><p>
+ <span class="application">PL/pgSQL</span> can be used to define trigger
+ functions on data changes or database events.
+ A trigger function is created with the <code class="command">CREATE FUNCTION</code>
+ command, declaring it as a function with no arguments and a return type of
+ <code class="type">trigger</code> (for data change triggers) or
+ <code class="type">event_trigger</code> (for database event triggers).
+ Special local variables named <code class="varname">TG_<em class="replaceable"><code>something</code></em></code> are
+ automatically defined to describe the condition that triggered the call.
+ </p><div class="sect2" id="PLPGSQL-DML-TRIGGER"><div class="titlepage"><div><div><h3 class="title">43.10.1. Triggers on Data Changes</h3></div></div></div><p>
+ A <a class="link" href="triggers.html" title="Chapter 39. Triggers">data change trigger</a> is declared as a
+ function with no arguments and a return type of <code class="type">trigger</code>.
+ Note that the function must be declared with no arguments even if it
+ expects to receive some arguments specified in <code class="command">CREATE TRIGGER</code>
+ — such arguments are passed via <code class="varname">TG_ARGV</code>, as described
+ below.
+ </p><p>
+ When a <span class="application">PL/pgSQL</span> function is called as a
+ trigger, several special variables are created automatically in the
+ top-level block. They are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">NEW</code></span></dt><dd><p>
+ Data type <code class="type">RECORD</code>; variable holding the new
+ database row for <code class="command">INSERT</code>/<code class="command">UPDATE</code> operations in row-level
+ triggers. This variable is null in statement-level triggers
+ and for <code class="command">DELETE</code> operations.
+ </p></dd><dt><span class="term"><code class="varname">OLD</code></span></dt><dd><p>
+ Data type <code class="type">RECORD</code>; variable holding the old
+ database row for <code class="command">UPDATE</code>/<code class="command">DELETE</code> operations in row-level
+ triggers. This variable is null in statement-level triggers
+ and for <code class="command">INSERT</code> operations.
+ </p></dd><dt><span class="term"><code class="varname">TG_NAME</code></span></dt><dd><p>
+ Data type <code class="type">name</code>; variable that contains the name of the trigger actually
+ fired.
+ </p></dd><dt><span class="term"><code class="varname">TG_WHEN</code></span></dt><dd><p>
+ Data type <code class="type">text</code>; a string of
+ <code class="literal">BEFORE</code>, <code class="literal">AFTER</code>, or
+ <code class="literal">INSTEAD OF</code>, depending on the trigger's definition.
+ </p></dd><dt><span class="term"><code class="varname">TG_LEVEL</code></span></dt><dd><p>
+ Data type <code class="type">text</code>; a string of either
+ <code class="literal">ROW</code> or <code class="literal">STATEMENT</code>
+ depending on the trigger's definition.
+ </p></dd><dt><span class="term"><code class="varname">TG_OP</code></span></dt><dd><p>
+ Data type <code class="type">text</code>; a string of
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code>
+ telling for which operation the trigger was fired.
+ </p></dd><dt><span class="term"><code class="varname">TG_RELID</code></span></dt><dd><p>
+ Data type <code class="type">oid</code>; the object ID of the table that caused the
+ trigger invocation.
+ </p></dd><dt><span class="term"><code class="varname">TG_RELNAME</code></span></dt><dd><p>
+ Data type <code class="type">name</code>; the name of the table that caused the trigger
+ invocation. This is now deprecated, and could disappear in a future
+ release. Use <code class="literal">TG_TABLE_NAME</code> instead.
+ </p></dd><dt><span class="term"><code class="varname">TG_TABLE_NAME</code></span></dt><dd><p>
+ Data type <code class="type">name</code>; the name of the table that
+ caused the trigger invocation.
+ </p></dd><dt><span class="term"><code class="varname">TG_TABLE_SCHEMA</code></span></dt><dd><p>
+ Data type <code class="type">name</code>; the name of the schema of the
+ table that caused the trigger invocation.
+ </p></dd><dt><span class="term"><code class="varname">TG_NARGS</code></span></dt><dd><p>
+ Data type <code class="type">integer</code>; the number of arguments given to the trigger
+ function in the <code class="command">CREATE TRIGGER</code> statement.
+ </p></dd><dt><span class="term"><code class="varname">TG_ARGV[]</code></span></dt><dd><p>
+ Data type array of <code class="type">text</code>; the arguments from
+ the <code class="command">CREATE TRIGGER</code> statement.
+ The index counts from 0. Invalid
+ indexes (less than 0 or greater than or equal to <code class="varname">tg_nargs</code>)
+ result in a null value.
+ </p></dd></dl></div><p>
+ </p><p>
+ A trigger function must return either <code class="symbol">NULL</code> or a
+ record/row value having exactly the structure of the table the
+ trigger was fired for.
+ </p><p>
+ Row-level triggers fired <code class="literal">BEFORE</code> can return null to signal the
+ trigger manager to skip the rest of the operation for this row
+ (i.e., subsequent triggers are not fired, and the
+ <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code> does not occur
+ for this row). If a nonnull
+ value is returned then the operation proceeds with that row value.
+ Returning a row value different from the original value
+ of <code class="varname">NEW</code> alters the row that will be inserted or
+ updated. Thus, if the trigger function wants the triggering
+ action to succeed normally without altering the row
+ value, <code class="varname">NEW</code> (or a value equal thereto) has to be
+ returned. To alter the row to be stored, it is possible to
+ replace single values directly in <code class="varname">NEW</code> and return the
+ modified <code class="varname">NEW</code>, or to build a complete new record/row to
+ return. In the case of a before-trigger
+ on <code class="command">DELETE</code>, the returned value has no direct
+ effect, but it has to be nonnull to allow the trigger action to
+ proceed. Note that <code class="varname">NEW</code> is null
+ in <code class="command">DELETE</code> triggers, so returning that is
+ usually not sensible. The usual idiom in <code class="command">DELETE</code>
+ triggers is to return <code class="varname">OLD</code>.
+ </p><p>
+ <code class="literal">INSTEAD OF</code> triggers (which are always row-level triggers,
+ and may only be used on views) can return null to signal that they did
+ not perform any updates, and that the rest of the operation for this
+ row should be skipped (i.e., subsequent triggers are not fired, and the
+ row is not counted in the rows-affected status for the surrounding
+ <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>).
+ Otherwise a nonnull value should be returned, to signal
+ that the trigger performed the requested operation. For
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> operations, the return value
+ should be <code class="varname">NEW</code>, which the trigger function may modify to
+ support <code class="command">INSERT RETURNING</code> and <code class="command">UPDATE RETURNING</code>
+ (this will also affect the row value passed to any subsequent triggers,
+ or passed to a special <code class="varname">EXCLUDED</code> alias reference within
+ an <code class="command">INSERT</code> statement with an <code class="literal">ON CONFLICT DO
+ UPDATE</code> clause). For <code class="command">DELETE</code> operations, the return
+ value should be <code class="varname">OLD</code>.
+ </p><p>
+ The return value of a row-level trigger
+ fired <code class="literal">AFTER</code> or a statement-level trigger
+ fired <code class="literal">BEFORE</code> or <code class="literal">AFTER</code> is
+ always ignored; it might as well be null. However, any of these types of
+ triggers might still abort the entire operation by raising an error.
+ </p><p>
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-TRIGGER-EXAMPLE" title="Example 43.3. A PL/pgSQL Trigger Function">Example 43.3</a> shows an example of a
+ trigger function in <span class="application">PL/pgSQL</span>.
+ </p><div class="example" id="PLPGSQL-TRIGGER-EXAMPLE"><p class="title"><strong>Example 43.3. A <span class="application">PL/pgSQL</span> Trigger Function</strong></p><div class="example-contents"><p>
+ This example trigger ensures that any time a row is inserted or updated
+ in the table, the current user name and time are stamped into the
+ row. And it checks that an employee's name is given and that the
+ salary is a positive value.
+ </p><pre class="programlisting">
+CREATE TABLE emp (
+ empname text,
+ salary integer,
+ last_date timestamp,
+ last_user text
+);
+
+CREATE FUNCTION emp_stamp() RETURNS trigger AS $emp_stamp$
+ BEGIN
+ -- Check that empname and salary are given
+ IF NEW.empname IS NULL THEN
+ RAISE EXCEPTION 'empname cannot be null';
+ END IF;
+ IF NEW.salary IS NULL THEN
+ RAISE EXCEPTION '% cannot have null salary', NEW.empname;
+ END IF;
+
+ -- Who works for us when they must pay for it?
+ IF NEW.salary &lt; 0 THEN
+ RAISE EXCEPTION '% cannot have a negative salary', NEW.empname;
+ END IF;
+
+ -- Remember who changed the payroll when
+ NEW.last_date := current_timestamp;
+ NEW.last_user := current_user;
+ RETURN NEW;
+ END;
+$emp_stamp$ LANGUAGE plpgsql;
+
+CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
+ FOR EACH ROW EXECUTE FUNCTION emp_stamp();
+</pre></div></div><br class="example-break" /><p>
+ Another way to log changes to a table involves creating a new table that
+ holds a row for each insert, update, or delete that occurs. This approach
+ can be thought of as auditing changes to a table.
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-TRIGGER-AUDIT-EXAMPLE" title="Example 43.4. A PL/pgSQL Trigger Function for Auditing">Example 43.4</a> shows an example of an
+ audit trigger function in <span class="application">PL/pgSQL</span>.
+ </p><div class="example" id="PLPGSQL-TRIGGER-AUDIT-EXAMPLE"><p class="title"><strong>Example 43.4. A <span class="application">PL/pgSQL</span> Trigger Function for Auditing</strong></p><div class="example-contents"><p>
+ This example trigger ensures that any insert, update or delete of a row
+ in the <code class="literal">emp</code> table is recorded (i.e., audited) in the <code class="literal">emp_audit</code> table.
+ The current time and user name are stamped into the row, together with
+ the type of operation performed on it.
+ </p><pre class="programlisting">
+CREATE TABLE emp (
+ empname text NOT NULL,
+ salary integer
+);
+
+CREATE TABLE emp_audit(
+ operation char(1) NOT NULL,
+ stamp timestamp NOT NULL,
+ userid text NOT NULL,
+ empname text NOT NULL,
+ salary integer
+);
+
+CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$
+ BEGIN
+ --
+ -- Create a row in emp_audit to reflect the operation performed on emp,
+ -- making use of the special variable TG_OP to work out the operation.
+ --
+ IF (TG_OP = 'DELETE') THEN
+ INSERT INTO emp_audit SELECT 'D', now(), current_user, OLD.*;
+ ELSIF (TG_OP = 'UPDATE') THEN
+ INSERT INTO emp_audit SELECT 'U', now(), current_user, NEW.*;
+ ELSIF (TG_OP = 'INSERT') THEN
+ INSERT INTO emp_audit SELECT 'I', now(), current_user, NEW.*;
+ END IF;
+ RETURN NULL; -- result is ignored since this is an AFTER trigger
+ END;
+$emp_audit$ LANGUAGE plpgsql;
+
+CREATE TRIGGER emp_audit
+AFTER INSERT OR UPDATE OR DELETE ON emp
+ FOR EACH ROW EXECUTE FUNCTION process_emp_audit();
+</pre></div></div><br class="example-break" /><p>
+ A variation of the previous example uses a view joining the main table
+ to the audit table, to show when each entry was last modified. This
+ approach still records the full audit trail of changes to the table,
+ but also presents a simplified view of the audit trail, showing just
+ the last modified timestamp derived from the audit trail for each entry.
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-VIEW-TRIGGER-AUDIT-EXAMPLE" title="Example 43.5. A PL/pgSQL View Trigger Function for Auditing">Example 43.5</a> shows an example
+ of an audit trigger on a view in <span class="application">PL/pgSQL</span>.
+ </p><div class="example" id="PLPGSQL-VIEW-TRIGGER-AUDIT-EXAMPLE"><p class="title"><strong>Example 43.5. A <span class="application">PL/pgSQL</span> View Trigger Function for Auditing</strong></p><div class="example-contents"><p>
+ This example uses a trigger on the view to make it updatable, and
+ ensure that any insert, update or delete of a row in the view is
+ recorded (i.e., audited) in the <code class="literal">emp_audit</code> table. The current time
+ and user name are recorded, together with the type of operation
+ performed, and the view displays the last modified time of each row.
+ </p><pre class="programlisting">
+CREATE TABLE emp (
+ empname text PRIMARY KEY,
+ salary integer
+);
+
+CREATE TABLE emp_audit(
+ operation char(1) NOT NULL,
+ userid text NOT NULL,
+ empname text NOT NULL,
+ salary integer,
+ stamp timestamp NOT NULL
+);
+
+CREATE VIEW emp_view AS
+ SELECT e.empname,
+ e.salary,
+ max(ea.stamp) AS last_updated
+ FROM emp e
+ LEFT JOIN emp_audit ea ON ea.empname = e.empname
+ GROUP BY 1, 2;
+
+CREATE OR REPLACE FUNCTION update_emp_view() RETURNS TRIGGER AS $$
+ BEGIN
+ --
+ -- Perform the required operation on emp, and create a row in emp_audit
+ -- to reflect the change made to emp.
+ --
+ IF (TG_OP = 'DELETE') THEN
+ DELETE FROM emp WHERE empname = OLD.empname;
+ IF NOT FOUND THEN RETURN NULL; END IF;
+
+ OLD.last_updated = now();
+ INSERT INTO emp_audit VALUES('D', current_user, OLD.*);
+ RETURN OLD;
+ ELSIF (TG_OP = 'UPDATE') THEN
+ UPDATE emp SET salary = NEW.salary WHERE empname = OLD.empname;
+ IF NOT FOUND THEN RETURN NULL; END IF;
+
+ NEW.last_updated = now();
+ INSERT INTO emp_audit VALUES('U', current_user, NEW.*);
+ RETURN NEW;
+ ELSIF (TG_OP = 'INSERT') THEN
+ INSERT INTO emp VALUES(NEW.empname, NEW.salary);
+
+ NEW.last_updated = now();
+ INSERT INTO emp_audit VALUES('I', current_user, NEW.*);
+ RETURN NEW;
+ END IF;
+ END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER emp_audit
+INSTEAD OF INSERT OR UPDATE OR DELETE ON emp_view
+ FOR EACH ROW EXECUTE FUNCTION update_emp_view();
+</pre></div></div><br class="example-break" /><p>
+ One use of triggers is to maintain a summary table
+ of another table. The resulting summary can be used in place of the
+ original table for certain queries — often with vastly reduced run
+ times.
+ This technique is commonly used in Data Warehousing, where the tables
+ of measured or observed data (called fact tables) might be extremely large.
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-TRIGGER-SUMMARY-EXAMPLE" title="Example 43.6. A PL/pgSQL Trigger Function for Maintaining a Summary Table">Example 43.6</a> shows an example of a
+ trigger function in <span class="application">PL/pgSQL</span> that maintains
+ a summary table for a fact table in a data warehouse.
+ </p><div class="example" id="PLPGSQL-TRIGGER-SUMMARY-EXAMPLE"><p class="title"><strong>Example 43.6. A <span class="application">PL/pgSQL</span> Trigger Function for Maintaining a Summary Table</strong></p><div class="example-contents"><p>
+ The schema detailed here is partly based on the <span class="emphasis"><em>Grocery Store
+ </em></span> example from <span class="emphasis"><em>The Data Warehouse Toolkit</em></span>
+ by Ralph Kimball.
+ </p><pre class="programlisting">
+--
+-- Main tables - time dimension and sales fact.
+--
+CREATE TABLE time_dimension (
+ time_key integer NOT NULL,
+ day_of_week integer NOT NULL,
+ day_of_month integer NOT NULL,
+ month integer NOT NULL,
+ quarter integer NOT NULL,
+ year integer NOT NULL
+);
+CREATE UNIQUE INDEX time_dimension_key ON time_dimension(time_key);
+
+CREATE TABLE sales_fact (
+ time_key integer NOT NULL,
+ product_key integer NOT NULL,
+ store_key integer NOT NULL,
+ amount_sold numeric(12,2) NOT NULL,
+ units_sold integer NOT NULL,
+ amount_cost numeric(12,2) NOT NULL
+);
+CREATE INDEX sales_fact_time ON sales_fact(time_key);
+
+--
+-- Summary table - sales by time.
+--
+CREATE TABLE sales_summary_bytime (
+ time_key integer NOT NULL,
+ amount_sold numeric(15,2) NOT NULL,
+ units_sold numeric(12) NOT NULL,
+ amount_cost numeric(15,2) NOT NULL
+);
+CREATE UNIQUE INDEX sales_summary_bytime_key ON sales_summary_bytime(time_key);
+
+--
+-- Function and trigger to amend summarized column(s) on UPDATE, INSERT, DELETE.
+--
+CREATE OR REPLACE FUNCTION maint_sales_summary_bytime() RETURNS TRIGGER
+AS $maint_sales_summary_bytime$
+ DECLARE
+ delta_time_key integer;
+ delta_amount_sold numeric(15,2);
+ delta_units_sold numeric(12);
+ delta_amount_cost numeric(15,2);
+ BEGIN
+
+ -- Work out the increment/decrement amount(s).
+ IF (TG_OP = 'DELETE') THEN
+
+ delta_time_key = OLD.time_key;
+ delta_amount_sold = -1 * OLD.amount_sold;
+ delta_units_sold = -1 * OLD.units_sold;
+ delta_amount_cost = -1 * OLD.amount_cost;
+
+ ELSIF (TG_OP = 'UPDATE') THEN
+
+ -- forbid updates that change the time_key -
+ -- (probably not too onerous, as DELETE + INSERT is how most
+ -- changes will be made).
+ IF ( OLD.time_key != NEW.time_key) THEN
+ RAISE EXCEPTION 'Update of time_key : % -&gt; % not allowed',
+ OLD.time_key, NEW.time_key;
+ END IF;
+
+ delta_time_key = OLD.time_key;
+ delta_amount_sold = NEW.amount_sold - OLD.amount_sold;
+ delta_units_sold = NEW.units_sold - OLD.units_sold;
+ delta_amount_cost = NEW.amount_cost - OLD.amount_cost;
+
+ ELSIF (TG_OP = 'INSERT') THEN
+
+ delta_time_key = NEW.time_key;
+ delta_amount_sold = NEW.amount_sold;
+ delta_units_sold = NEW.units_sold;
+ delta_amount_cost = NEW.amount_cost;
+
+ END IF;
+
+
+ -- Insert or update the summary row with the new values.
+ &lt;&lt;insert_update&gt;&gt;
+ LOOP
+ UPDATE sales_summary_bytime
+ SET amount_sold = amount_sold + delta_amount_sold,
+ units_sold = units_sold + delta_units_sold,
+ amount_cost = amount_cost + delta_amount_cost
+ WHERE time_key = delta_time_key;
+
+ EXIT insert_update WHEN found;
+
+ BEGIN
+ INSERT INTO sales_summary_bytime (
+ time_key,
+ amount_sold,
+ units_sold,
+ amount_cost)
+ VALUES (
+ delta_time_key,
+ delta_amount_sold,
+ delta_units_sold,
+ delta_amount_cost
+ );
+
+ EXIT insert_update;
+
+ EXCEPTION
+ WHEN UNIQUE_VIOLATION THEN
+ -- do nothing
+ END;
+ END LOOP insert_update;
+
+ RETURN NULL;
+
+ END;
+$maint_sales_summary_bytime$ LANGUAGE plpgsql;
+
+CREATE TRIGGER maint_sales_summary_bytime
+AFTER INSERT OR UPDATE OR DELETE ON sales_fact
+ FOR EACH ROW EXECUTE FUNCTION maint_sales_summary_bytime();
+
+INSERT INTO sales_fact VALUES(1,1,1,10,3,15);
+INSERT INTO sales_fact VALUES(1,2,1,20,5,35);
+INSERT INTO sales_fact VALUES(2,2,1,40,15,135);
+INSERT INTO sales_fact VALUES(2,3,1,10,1,13);
+SELECT * FROM sales_summary_bytime;
+DELETE FROM sales_fact WHERE product_key = 1;
+SELECT * FROM sales_summary_bytime;
+UPDATE sales_fact SET units_sold = units_sold * 2;
+SELECT * FROM sales_summary_bytime;
+</pre></div></div><br class="example-break" /><p>
+ <code class="literal">AFTER</code> triggers can also make use of <em class="firstterm">transition
+ tables</em> to inspect the entire set of rows changed by the triggering
+ statement. The <code class="command">CREATE TRIGGER</code> command assigns names to one
+ or both transition tables, and then the function can refer to those names
+ as though they were read-only temporary tables.
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-TRIGGER-AUDIT-TRANSITION-EXAMPLE" title="Example 43.7. Auditing with Transition Tables">Example 43.7</a> shows an example.
+ </p><div class="example" id="PLPGSQL-TRIGGER-AUDIT-TRANSITION-EXAMPLE"><p class="title"><strong>Example 43.7. Auditing with Transition Tables</strong></p><div class="example-contents"><p>
+ This example produces the same results as
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-TRIGGER-AUDIT-EXAMPLE" title="Example 43.4. A PL/pgSQL Trigger Function for Auditing">Example 43.4</a>, but instead of using a
+ trigger that fires for every row, it uses a trigger that fires once
+ per statement, after collecting the relevant information in a transition
+ table. This can be significantly faster than the row-trigger approach
+ when the invoking statement has modified many rows. Notice that we must
+ make a separate trigger declaration for each kind of event, since the
+ <code class="literal">REFERENCING</code> clauses must be different for each case. But
+ this does not stop us from using a single trigger function if we choose.
+ (In practice, it might be better to use three separate functions and
+ avoid the run-time tests on <code class="varname">TG_OP</code>.)
+ </p><pre class="programlisting">
+CREATE TABLE emp (
+ empname text NOT NULL,
+ salary integer
+);
+
+CREATE TABLE emp_audit(
+ operation char(1) NOT NULL,
+ stamp timestamp NOT NULL,
+ userid text NOT NULL,
+ empname text NOT NULL,
+ salary integer
+);
+
+CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$
+ BEGIN
+ --
+ -- Create rows in emp_audit to reflect the operations performed on emp,
+ -- making use of the special variable TG_OP to work out the operation.
+ --
+ IF (TG_OP = 'DELETE') THEN
+ INSERT INTO emp_audit
+ SELECT 'D', now(), current_user, o.* FROM old_table o;
+ ELSIF (TG_OP = 'UPDATE') THEN
+ INSERT INTO emp_audit
+ SELECT 'U', now(), current_user, n.* FROM new_table n;
+ ELSIF (TG_OP = 'INSERT') THEN
+ INSERT INTO emp_audit
+ SELECT 'I', now(), current_user, n.* FROM new_table n;
+ END IF;
+ RETURN NULL; -- result is ignored since this is an AFTER trigger
+ END;
+$emp_audit$ LANGUAGE plpgsql;
+
+CREATE TRIGGER emp_audit_ins
+ AFTER INSERT ON emp
+ REFERENCING NEW TABLE AS new_table
+ FOR EACH STATEMENT EXECUTE FUNCTION process_emp_audit();
+CREATE TRIGGER emp_audit_upd
+ AFTER UPDATE ON emp
+ REFERENCING OLD TABLE AS old_table NEW TABLE AS new_table
+ FOR EACH STATEMENT EXECUTE FUNCTION process_emp_audit();
+CREATE TRIGGER emp_audit_del
+ AFTER DELETE ON emp
+ REFERENCING OLD TABLE AS old_table
+ FOR EACH STATEMENT EXECUTE FUNCTION process_emp_audit();
+</pre></div></div><br class="example-break" /></div><div class="sect2" id="PLPGSQL-EVENT-TRIGGER"><div class="titlepage"><div><div><h3 class="title">43.10.2. Triggers on Events</h3></div></div></div><p>
+ <span class="application">PL/pgSQL</span> can be used to define
+ <a class="link" href="event-triggers.html" title="Chapter 40. Event Triggers">event triggers</a>.
+ <span class="productname">PostgreSQL</span> requires that a function that
+ is to be called as an event trigger must be declared as a function with
+ no arguments and a return type of <code class="literal">event_trigger</code>.
+ </p><p>
+ When a <span class="application">PL/pgSQL</span> function is called as an
+ event trigger, several special variables are created automatically
+ in the top-level block. They are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">TG_EVENT</code></span></dt><dd><p>
+ Data type <code class="type">text</code>; a string representing the event the
+ trigger is fired for.
+ </p></dd><dt><span class="term"><code class="varname">TG_TAG</code></span></dt><dd><p>
+ Data type <code class="type">text</code>; variable that contains the command tag
+ for which the trigger is fired.
+ </p></dd></dl></div><p>
+ </p><p>
+ <a class="xref" href="plpgsql-trigger.html#PLPGSQL-EVENT-TRIGGER-EXAMPLE" title="Example 43.8. A PL/pgSQL Event Trigger Function">Example 43.8</a> shows an example of an
+ event trigger function in <span class="application">PL/pgSQL</span>.
+ </p><div class="example" id="PLPGSQL-EVENT-TRIGGER-EXAMPLE"><p class="title"><strong>Example 43.8. A <span class="application">PL/pgSQL</span> Event Trigger Function</strong></p><div class="example-contents"><p>
+ This example trigger simply raises a <code class="literal">NOTICE</code> message
+ each time a supported command is executed.
+ </p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION snitch() RETURNS event_trigger AS $$
+BEGIN
+ RAISE NOTICE 'snitch: % %', tg_event, tg_tag;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE EVENT TRIGGER snitch ON ddl_command_start EXECUTE FUNCTION snitch();
+</pre></div></div><br class="example-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-errors-and-messages.html" title="43.9. Errors and Messages">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-implementation.html" title="43.11. PL/pgSQL under the Hood">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.9. Errors and Messages </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.11. <span class="application">PL/pgSQL</span> under the Hood</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpgsql.html b/doc/src/sgml/html/plpgsql.html
new file mode 100644
index 0000000..9372249
--- /dev/null
+++ b/doc/src/sgml/html/plpgsql.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 43. PL/pgSQL — SQL Procedural Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xplang-install.html" title="42.1. Installing Procedural Languages" /><link rel="next" href="plpgsql-overview.html" title="43.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xplang-install.html" title="42.1. Installing Procedural Languages">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-overview.html" title="43.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLPGSQL"><div class="titlepage"><div><div><h2 class="title">Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="plpgsql-overview.html">43.1. Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-overview.html#PLPGSQL-ADVANTAGES">43.1.1. Advantages of Using <span class="application">PL/pgSQL</span></a></span></dt><dt><span class="sect2"><a href="plpgsql-overview.html#PLPGSQL-ARGS-RESULTS">43.1.2. Supported Argument and Result Data Types</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-structure.html">43.2. Structure of <span class="application">PL/pgSQL</span></a></span></dt><dt><span class="sect1"><a href="plpgsql-declarations.html">43.3. Declarations</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS">43.3.1. Declaring Function Parameters</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-ALIAS">43.3.2. <code class="literal">ALIAS</code></a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-TYPE">43.3.3. Copying Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-ROWTYPES">43.3.4. Row Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-RECORDS">43.3.5. Record Types</a></span></dt><dt><span class="sect2"><a href="plpgsql-declarations.html#PLPGSQL-DECLARATION-COLLATION">43.3.6. Collation of <span class="application">PL/pgSQL</span> Variables</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-expressions.html">43.4. Expressions</a></span></dt><dt><span class="sect1"><a href="plpgsql-statements.html">43.5. Basic Statements</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-ASSIGNMENT">43.5.1. Assignment</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-GENERAL-SQL">43.5.2. Executing SQL Commands</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-SQL-ONEROW">43.5.3. Executing a Command with a Single-Row Result</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-EXECUTING-DYN">43.5.4. Executing Dynamic Commands</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS">43.5.5. Obtaining the Result Status</a></span></dt><dt><span class="sect2"><a href="plpgsql-statements.html#PLPGSQL-STATEMENTS-NULL">43.5.6. Doing Nothing At All</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-control-structures.html">43.6. Control Structures</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-RETURNING">43.6.1. Returning from a Function</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-RETURNING-PROCEDURE">43.6.2. Returning from a Procedure</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE">43.6.3. Calling a Procedure</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CONDITIONALS">43.6.4. Conditionals</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CONTROL-STRUCTURES-LOOPS">43.6.5. Simple Loops</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-RECORDS-ITERATING">43.6.6. Looping through Query Results</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-FOREACH-ARRAY">43.6.7. Looping through Arrays</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-ERROR-TRAPPING">43.6.8. Trapping Errors</a></span></dt><dt><span class="sect2"><a href="plpgsql-control-structures.html#PLPGSQL-CALL-STACK">43.6.9. Obtaining Execution Location Information</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-cursors.html">43.7. Cursors</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-DECLARATIONS">43.7.1. Declaring Cursor Variables</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-OPENING">43.7.2. Opening Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-USING">43.7.3. Using Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP">43.7.4. Looping through a Cursor's Result</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-transactions.html">43.8. Transaction Management</a></span></dt><dt><span class="sect1"><a href="plpgsql-errors-and-messages.html">43.9. Errors and Messages</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-RAISE">43.9.1. Reporting Errors and Messages</a></span></dt><dt><span class="sect2"><a href="plpgsql-errors-and-messages.html#PLPGSQL-STATEMENTS-ASSERT">43.9.2. Checking Assertions</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-trigger.html">43.10. Trigger Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-trigger.html#PLPGSQL-DML-TRIGGER">43.10.1. Triggers on Data Changes</a></span></dt><dt><span class="sect2"><a href="plpgsql-trigger.html#PLPGSQL-EVENT-TRIGGER">43.10.2. Triggers on Events</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-implementation.html">43.11. <span class="application">PL/pgSQL</span> under the Hood</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-implementation.html#PLPGSQL-VAR-SUBST">43.11.1. Variable Substitution</a></span></dt><dt><span class="sect2"><a href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING">43.11.2. Plan Caching</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-development-tips.html">43.12. Tips for Developing in <span class="application">PL/pgSQL</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-development-tips.html#PLPGSQL-QUOTE-TIPS">43.12.1. Handling of Quotation Marks</a></span></dt><dt><span class="sect2"><a href="plpgsql-development-tips.html#PLPGSQL-EXTRA-CHECKS">43.12.2. Additional Compile-Time and Run-Time Checks</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpgsql-porting.html">43.13. Porting from <span class="productname">Oracle</span> PL/SQL</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpgsql-porting.html#id-1.8.8.15.6">43.13.1. Porting Examples</a></span></dt><dt><span class="sect2"><a href="plpgsql-porting.html#PLPGSQL-PORTING-OTHER">43.13.2. Other Things to Watch For</a></span></dt><dt><span class="sect2"><a href="plpgsql-porting.html#PLPGSQL-PORTING-APPENDIX">43.13.3. Appendix</a></span></dt></dl></dd></dl></div><a id="id-1.8.8.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xplang-install.html" title="42.1. Installing Procedural Languages">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-overview.html" title="43.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">42.1. Installing Procedural Languages </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 43.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-data.html b/doc/src/sgml/html/plpython-data.html
new file mode 100644
index 0000000..5e31573
--- /dev/null
+++ b/doc/src/sgml/html/plpython-data.html
@@ -0,0 +1,343 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.2. Data Values</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-funcs.html" title="46.1. PL/Python Functions" /><link rel="next" href="plpython-sharing.html" title="46.3. Sharing Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.2. Data Values</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-funcs.html" title="46.1. PL/Python Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-sharing.html" title="46.3. Sharing Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.2. Data Values</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.3">46.2.1. Data Type Mapping</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.4">46.2.2. Null, None</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#PLPYTHON-ARRAYS">46.2.3. Arrays, Lists</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.6">46.2.4. Composite Types</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.7">46.2.5. Set-Returning Functions</a></span></dt></dl></div><p>
+ Generally speaking, the aim of PL/Python is to provide
+ a <span class="quote">“<span class="quote">natural</span>”</span> mapping between the PostgreSQL and the
+ Python worlds. This informs the data mapping rules described
+ below.
+ </p><div class="sect2" id="id-1.8.11.10.3"><div class="titlepage"><div><div><h3 class="title">46.2.1. Data Type Mapping</h3></div></div></div><p>
+ When a PL/Python function is called, its arguments are converted from
+ their PostgreSQL data type to a corresponding Python type:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ PostgreSQL <code class="type">boolean</code> is converted to Python <code class="type">bool</code>.
+ </p></li><li class="listitem"><p>
+ PostgreSQL <code class="type">smallint</code>, <code class="type">int</code>, <code class="type">bigint</code>
+ and <code class="type">oid</code> are converted to Python <code class="type">int</code>.
+ </p></li><li class="listitem"><p>
+ PostgreSQL <code class="type">real</code> and <code class="type">double</code> are converted to
+ Python <code class="type">float</code>.
+ </p></li><li class="listitem"><p>
+ PostgreSQL <code class="type">numeric</code> is converted to
+ Python <code class="type">Decimal</code>. This type is imported from
+ the <code class="literal">cdecimal</code> package if that is available.
+ Otherwise,
+ <code class="literal">decimal.Decimal</code> from the standard library will be
+ used. <code class="literal">cdecimal</code> is significantly faster
+ than <code class="literal">decimal</code>. In Python 3.3 and up,
+ however, <code class="literal">cdecimal</code> has been integrated into the
+ standard library under the name <code class="literal">decimal</code>, so there is
+ no longer any difference.
+ </p></li><li class="listitem"><p>
+ PostgreSQL <code class="type">bytea</code> is converted to Python <code class="type">bytes</code>.
+ </p></li><li class="listitem"><p>
+ All other data types, including the PostgreSQL character string types,
+ are converted to a Python <code class="type">str</code> (in Unicode like all Python
+ strings).
+ </p></li><li class="listitem"><p>
+ For nonscalar data types, see below.
+ </p></li></ul></div><p>
+ </p><p>
+ When a PL/Python function returns, its return value is converted to the
+ function's declared PostgreSQL return data type as follows:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ When the PostgreSQL return type is <code class="type">boolean</code>, the
+ return value will be evaluated for truth according to the
+ <span class="emphasis"><em>Python</em></span> rules. That is, 0 and empty string
+ are false, but notably <code class="literal">'f'</code> is true.
+ </p></li><li class="listitem"><p>
+ When the PostgreSQL return type is <code class="type">bytea</code>, the return value
+ will be converted to Python <code class="type">bytes</code> using the respective
+ Python built-ins, with the result being converted to
+ <code class="type">bytea</code>.
+ </p></li><li class="listitem"><p>
+ For all other PostgreSQL return types, the return value is converted
+ to a string using the Python built-in <code class="literal">str</code>, and the
+ result is passed to the input function of the PostgreSQL data type.
+ (If the Python value is a <code class="type">float</code>, it is converted using
+ the <code class="literal">repr</code> built-in instead of <code class="literal">str</code>, to
+ avoid loss of precision.)
+ </p><p>
+ Strings are automatically converted to the PostgreSQL server encoding
+ when they are passed to PostgreSQL.
+ </p></li><li class="listitem"><p>
+ For nonscalar data types, see below.
+ </p></li></ul></div><p>
+
+ Note that logical mismatches between the declared PostgreSQL
+ return type and the Python data type of the actual return object
+ are not flagged; the value will be converted in any case.
+ </p></div><div class="sect2" id="id-1.8.11.10.4"><div class="titlepage"><div><div><h3 class="title">46.2.2. Null, None</h3></div></div></div><p>
+ If an SQL null value<a id="id-1.8.11.10.4.2.1" class="indexterm"></a> is passed to a
+ function, the argument value will appear as <code class="symbol">None</code> in
+ Python. For example, the function definition of <code class="function">pymax</code>
+ shown in <a class="xref" href="plpython-funcs.html" title="46.1. PL/Python Functions">Section 46.1</a> will return the wrong answer for null
+ inputs. We could add <code class="literal">STRICT</code> to the function definition
+ to make <span class="productname">PostgreSQL</span> do something more reasonable:
+ if a null value is passed, the function will not be called at all,
+ but will just return a null result automatically. Alternatively,
+ we could check for null inputs in the function body:
+
+</p><pre class="programlisting">
+CREATE FUNCTION pymax (a integer, b integer)
+ RETURNS integer
+AS $$
+ if (a is None) or (b is None):
+ return None
+ if a &gt; b:
+ return a
+ return b
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ As shown above, to return an SQL null value from a PL/Python
+ function, return the value <code class="symbol">None</code>. This can be done whether the
+ function is strict or not.
+ </p></div><div class="sect2" id="PLPYTHON-ARRAYS"><div class="titlepage"><div><div><h3 class="title">46.2.3. Arrays, Lists</h3></div></div></div><p>
+ SQL array values are passed into PL/Python as a Python list. To
+ return an SQL array value out of a PL/Python function, return a
+ Python list:
+
+</p><pre class="programlisting">
+CREATE FUNCTION return_arr()
+ RETURNS int[]
+AS $$
+return [1, 2, 3, 4, 5]
+$$ LANGUAGE plpython3u;
+
+SELECT return_arr();
+ return_arr
+-------------
+ {1,2,3,4,5}
+(1 row)
+</pre><p>
+
+ Multidimensional arrays are passed into PL/Python as nested Python lists.
+ A 2-dimensional array is a list of lists, for example. When returning
+ a multi-dimensional SQL array out of a PL/Python function, the inner
+ lists at each level must all be of the same size. For example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION test_type_conversion_array_int4(x int4[]) RETURNS int4[] AS $$
+plpy.info(x, type(x))
+return x
+$$ LANGUAGE plpython3u;
+
+SELECT * FROM test_type_conversion_array_int4(ARRAY[[1,2,3],[4,5,6]]);
+INFO: ([[1, 2, 3], [4, 5, 6]], &lt;type 'list'&gt;)
+ test_type_conversion_array_int4
+---------------------------------
+ {{1,2,3},{4,5,6}}
+(1 row)
+</pre><p>
+
+ Other Python sequences, like tuples, are also accepted for
+ backwards-compatibility with PostgreSQL versions 9.6 and below, when
+ multi-dimensional arrays were not supported. However, they are always
+ treated as one-dimensional arrays, because they are ambiguous with
+ composite types. For the same reason, when a composite type is used in a
+ multi-dimensional array, it must be represented by a tuple, rather than a
+ list.
+ </p><p>
+ Note that in Python, strings are sequences, which can have
+ undesirable effects that might be familiar to Python programmers:
+
+</p><pre class="programlisting">
+CREATE FUNCTION return_str_arr()
+ RETURNS varchar[]
+AS $$
+return "hello"
+$$ LANGUAGE plpython3u;
+
+SELECT return_str_arr();
+ return_str_arr
+----------------
+ {h,e,l,l,o}
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.8.11.10.6"><div class="titlepage"><div><div><h3 class="title">46.2.4. Composite Types</h3></div></div></div><p>
+ Composite-type arguments are passed to the function as Python mappings. The
+ element names of the mapping are the attribute names of the composite type.
+ If an attribute in the passed row has the null value, it has the value
+ <code class="symbol">None</code> in the mapping. Here is an example:
+
+</p><pre class="programlisting">
+CREATE TABLE employee (
+ name text,
+ salary integer,
+ age integer
+);
+
+CREATE FUNCTION overpaid (e employee)
+ RETURNS boolean
+AS $$
+ if e["salary"] &gt; 200000:
+ return True
+ if (e["age"] &lt; 30) and (e["salary"] &gt; 100000):
+ return True
+ return False
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p><p>
+ There are multiple ways to return row or composite types from a Python
+ function. The following examples assume we have:
+
+</p><pre class="programlisting">
+CREATE TYPE named_value AS (
+ name text,
+ value integer
+);
+</pre><p>
+
+ A composite result can be returned as a:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Sequence type (a tuple or list, but not a set because
+ it is not indexable)</span></dt><dd><p>
+ Returned sequence objects must have the same number of items as the
+ composite result type has fields. The item with index 0 is assigned to
+ the first field of the composite type, 1 to the second and so on. For
+ example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION make_pair (name text, value integer)
+ RETURNS named_value
+AS $$
+ return ( name, value )
+ # or alternatively, as list: return [ name, value ]
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ To return an SQL null for any column, insert <code class="symbol">None</code> at
+ the corresponding position.
+ </p><p>
+ When an array of composite types is returned, it cannot be returned as a list,
+ because it is ambiguous whether the Python list represents a composite type,
+ or another array dimension.
+ </p></dd><dt><span class="term">Mapping (dictionary)</span></dt><dd><p>
+ The value for each result type column is retrieved from the mapping
+ with the column name as key. Example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION make_pair (name text, value integer)
+ RETURNS named_value
+AS $$
+ return { "name": name, "value": value }
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ Any extra dictionary key/value pairs are ignored. Missing keys are
+ treated as errors.
+ To return an SQL null value for any column, insert
+ <code class="symbol">None</code> with the corresponding column name as the key.
+ </p></dd><dt><span class="term">Object (any object providing method <code class="literal">__getattr__</code>)</span></dt><dd><p>
+ This works the same as a mapping.
+ Example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION make_pair (name text, value integer)
+ RETURNS named_value
+AS $$
+ class named_value:
+ def __init__ (self, n, v):
+ self.name = n
+ self.value = v
+ return named_value(name, value)
+
+ # or simply
+ class nv: pass
+ nv.name = name
+ nv.value = value
+ return nv
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ Functions with <code class="literal">OUT</code> parameters are also supported. For example:
+</p><pre class="programlisting">
+CREATE FUNCTION multiout_simple(OUT i integer, OUT j integer) AS $$
+return (1, 2)
+$$ LANGUAGE plpython3u;
+
+SELECT * FROM multiout_simple();
+</pre><p>
+ </p><p>
+ Output parameters of procedures are passed back the same way. For example:
+</p><pre class="programlisting">
+CREATE PROCEDURE python_triple(INOUT a integer, INOUT b integer) AS $$
+return (a * 3, b * 3)
+$$ LANGUAGE plpython3u;
+
+CALL python_triple(5, 10);
+</pre><p>
+ </p></div><div class="sect2" id="id-1.8.11.10.7"><div class="titlepage"><div><div><h3 class="title">46.2.5. Set-Returning Functions</h3></div></div></div><p>
+ A <span class="application">PL/Python</span> function can also return sets of
+ scalar or composite types. There are several ways to achieve this because
+ the returned object is internally turned into an iterator. The following
+ examples assume we have composite type:
+
+</p><pre class="programlisting">
+CREATE TYPE greeting AS (
+ how text,
+ who text
+);
+</pre><p>
+
+ A set result can be returned from a:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Sequence type (tuple, list, set)</span></dt><dd><p>
+</p><pre class="programlisting">
+CREATE FUNCTION greet (how text)
+ RETURNS SETOF greeting
+AS $$
+ # return tuple containing lists as composite types
+ # all other combinations work also
+ return ( [ how, "World" ], [ how, "PostgreSQL" ], [ how, "PL/Python" ] )
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p></dd><dt><span class="term">Iterator (any object providing <code class="symbol">__iter__</code> and
+ <code class="symbol">next</code> methods)</span></dt><dd><p>
+</p><pre class="programlisting">
+CREATE FUNCTION greet (how text)
+ RETURNS SETOF greeting
+AS $$
+ class producer:
+ def __init__ (self, how, who):
+ self.how = how
+ self.who = who
+ self.ndx = -1
+
+ def __iter__ (self):
+ return self
+
+ def next (self):
+ self.ndx += 1
+ if self.ndx == len(self.who):
+ raise StopIteration
+ return ( self.how, self.who[self.ndx] )
+
+ return producer(how, [ "World", "PostgreSQL", "PL/Python" ])
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p></dd><dt><span class="term">Generator (<code class="literal">yield</code>)</span></dt><dd><p>
+</p><pre class="programlisting">
+CREATE FUNCTION greet (how text)
+ RETURNS SETOF greeting
+AS $$
+ for who in [ "World", "PostgreSQL", "PL/Python" ]:
+ yield ( how, who )
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ </p></dd></dl></div><p>
+ </p><p>
+ Set-returning functions with <code class="literal">OUT</code> parameters
+ (using <code class="literal">RETURNS SETOF record</code>) are also
+ supported. For example:
+</p><pre class="programlisting">
+CREATE FUNCTION multiout_simple_setof(n integer, OUT integer, OUT integer) RETURNS SETOF record AS $$
+return [(1, 2)] * n
+$$ LANGUAGE plpython3u;
+
+SELECT * FROM multiout_simple_setof(3);
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-funcs.html" title="46.1. PL/Python Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-sharing.html" title="46.3. Sharing Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.1. PL/Python Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.3. Sharing Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-database.html b/doc/src/sgml/html/plpython-database.html
new file mode 100644
index 0000000..baa9dbf
--- /dev/null
+++ b/doc/src/sgml/html/plpython-database.html
@@ -0,0 +1,238 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.6. Database Access</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-trigger.html" title="46.5. Trigger Functions" /><link rel="next" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.6. Database Access</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-trigger.html" title="46.5. Trigger Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-DATABASE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.6. Database Access</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpython-database.html#id-1.8.11.14.3">46.6.1. Database Access Functions</a></span></dt><dt><span class="sect2"><a href="plpython-database.html#PLPYTHON-TRAPPING">46.6.2. Trapping Errors</a></span></dt></dl></div><p>
+ The PL/Python language module automatically imports a Python module
+ called <code class="literal">plpy</code>. The functions and constants in
+ this module are available to you in the Python code as
+ <code class="literal">plpy.<em class="replaceable"><code>foo</code></em></code>.
+ </p><div class="sect2" id="id-1.8.11.14.3"><div class="titlepage"><div><div><h3 class="title">46.6.1. Database Access Functions</h3></div></div></div><p>
+ The <code class="literal">plpy</code> module provides several functions to execute
+ database commands:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">plpy.<code class="function">execute</code>(<em class="replaceable"><code>query</code></em> [, <em class="replaceable"><code>limit</code></em>])</code></span></dt><dd><p>
+ Calling <code class="function">plpy.execute</code> with a query string and an
+ optional row limit argument causes that query to be run and the result to
+ be returned in a result object.
+ </p><p>
+ If <em class="replaceable"><code>limit</code></em> is specified and is greater than
+ zero, then <code class="function">plpy.execute</code> retrieves at
+ most <em class="replaceable"><code>limit</code></em> rows, much as if the query
+ included a <code class="literal">LIMIT</code>
+ clause. Omitting <em class="replaceable"><code>limit</code></em> or specifying it as
+ zero results in no row limit.
+ </p><p>
+ The result object emulates a list or dictionary object. The result
+ object can be accessed by row number and column name. For example:
+</p><pre class="programlisting">
+rv = plpy.execute("SELECT * FROM my_table", 5)
+</pre><p>
+ returns up to 5 rows from <code class="literal">my_table</code>. If
+ <code class="literal">my_table</code> has a column
+ <code class="literal">my_column</code>, it would be accessed as:
+</p><pre class="programlisting">
+foo = rv[i]["my_column"]
+</pre><p>
+ The number of rows returned can be obtained using the built-in
+ <code class="function">len</code> function.
+ </p><p>
+ The result object has these additional methods:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal"><code class="function">nrows</code>()</code></span></dt><dd><p>
+ Returns the number of rows processed by the command. Note that this
+ is not necessarily the same as the number of rows returned. For
+ example, an <code class="command">UPDATE</code> command will set this value but
+ won't return any rows (unless <code class="literal">RETURNING</code> is used).
+ </p></dd><dt><span class="term"><code class="literal"><code class="function">status</code>()</code></span></dt><dd><p>
+ The <code class="function">SPI_execute()</code> return value.
+ </p></dd><dt><span class="term"><code class="literal"><code class="function">colnames</code>()</code><br /></span><span class="term"><code class="literal"><code class="function">coltypes</code>()</code><br /></span><span class="term"><code class="literal"><code class="function">coltypmods</code>()</code></span></dt><dd><p>
+ Return a list of column names, list of column type OIDs, and list of
+ type-specific type modifiers for the columns, respectively.
+ </p><p>
+ These methods raise an exception when called on a result object from
+ a command that did not produce a result set, e.g.,
+ <code class="command">UPDATE</code> without <code class="literal">RETURNING</code>, or
+ <code class="command">DROP TABLE</code>. But it is OK to use these methods on
+ a result set containing zero rows.
+ </p></dd><dt><span class="term"><code class="literal"><code class="function">__str__</code>()</code></span></dt><dd><p>
+ The standard <code class="literal">__str__</code> method is defined so that it
+ is possible for example to debug query execution results
+ using <code class="literal">plpy.debug(rv)</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ The result object can be modified.
+ </p><p>
+ Note that calling <code class="literal">plpy.execute</code> will cause the entire
+ result set to be read into memory. Only use that function when you are
+ sure that the result set will be relatively small. If you don't want to
+ risk excessive memory usage when fetching large results,
+ use <code class="literal">plpy.cursor</code> rather
+ than <code class="literal">plpy.execute</code>.
+ </p></dd><dt><span class="term"><code class="literal">plpy.<code class="function">prepare</code>(<em class="replaceable"><code>query</code></em> [, <em class="replaceable"><code>argtypes</code></em>])</code><br /></span><span class="term"><code class="literal">plpy.<code class="function">execute</code>(<em class="replaceable"><code>plan</code></em> [, <em class="replaceable"><code>arguments</code></em> [, <em class="replaceable"><code>limit</code></em>]])</code></span></dt><dd><p>
+ <a id="id-1.8.11.14.3.3.2.3.1.1" class="indexterm"></a>
+ <code class="function">plpy.prepare</code> prepares the execution plan for a
+ query. It is called with a query string and a list of parameter types,
+ if you have parameter references in the query. For example:
+</p><pre class="programlisting">
+plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"])
+</pre><p>
+ <code class="literal">text</code> is the type of the variable you will be passing
+ for <code class="literal">$1</code>. The second argument is optional if you don't
+ want to pass any parameters to the query.
+ </p><p>
+ After preparing a statement, you use a variant of the
+ function <code class="function">plpy.execute</code> to run it:
+</p><pre class="programlisting">
+rv = plpy.execute(plan, ["name"], 5)
+</pre><p>
+ Pass the plan as the first argument (instead of the query string), and a
+ list of values to substitute into the query as the second argument. The
+ second argument is optional if the query does not expect any parameters.
+ The third argument is the optional row limit as before.
+ </p><p>
+ Alternatively, you can call the <code class="function">execute</code> method on
+ the plan object:
+</p><pre class="programlisting">
+rv = plan.execute(["name"], 5)
+</pre><p>
+ </p><p>
+ Query parameters and result row fields are converted between PostgreSQL
+ and Python data types as described in <a class="xref" href="plpython-data.html" title="46.2. Data Values">Section 46.2</a>.
+ </p><p>
+ When you prepare a plan using the PL/Python module it is automatically
+ saved. Read the SPI documentation (<a class="xref" href="spi.html" title="Chapter 47. Server Programming Interface">Chapter 47</a>) for a
+ description of what this means. In order to make effective use of this
+ across function calls one needs to use one of the persistent storage
+ dictionaries <code class="literal">SD</code> or <code class="literal">GD</code> (see
+ <a class="xref" href="plpython-sharing.html" title="46.3. Sharing Data">Section 46.3</a>). For example:
+</p><pre class="programlisting">
+CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
+ if "plan" in SD:
+ plan = SD["plan"]
+ else:
+ plan = plpy.prepare("SELECT 1")
+ SD["plan"] = plan
+ # rest of function
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">plpy.<code class="function">cursor</code>(<em class="replaceable"><code>query</code></em>)</code><br /></span><span class="term"><code class="literal">plpy.<code class="function">cursor</code>(<em class="replaceable"><code>plan</code></em> [, <em class="replaceable"><code>arguments</code></em>])</code></span></dt><dd><p>
+ The <code class="literal">plpy.cursor</code> function accepts the same arguments
+ as <code class="literal">plpy.execute</code> (except for the row limit) and returns
+ a cursor object, which allows you to process large result sets in smaller
+ chunks. As with <code class="literal">plpy.execute</code>, either a query string
+ or a plan object along with a list of arguments can be used, or
+ the <code class="function">cursor</code> function can be called as a method of
+ the plan object.
+ </p><p>
+ The cursor object provides a <code class="literal">fetch</code> method that accepts
+ an integer parameter and returns a result object. Each time you
+ call <code class="literal">fetch</code>, the returned object will contain the next
+ batch of rows, never larger than the parameter value. Once all rows are
+ exhausted, <code class="literal">fetch</code> starts returning an empty result
+ object. Cursor objects also provide an
+ <a class="ulink" href="https://docs.python.org/library/stdtypes.html#iterator-types" target="_top">iterator
+ interface</a>, yielding one row at a time until all rows are
+ exhausted. Data fetched that way is not returned as result objects, but
+ rather as dictionaries, each dictionary corresponding to a single result
+ row.
+ </p><p>
+ An example of two ways of processing data from a large table is:
+</p><pre class="programlisting">
+CREATE FUNCTION count_odd_iterator() RETURNS integer AS $$
+odd = 0
+for row in plpy.cursor("select num from largetable"):
+ if row['num'] % 2:
+ odd += 1
+return odd
+$$ LANGUAGE plpython3u;
+
+CREATE FUNCTION count_odd_fetch(batch_size integer) RETURNS integer AS $$
+odd = 0
+cursor = plpy.cursor("select num from largetable")
+while True:
+ rows = cursor.fetch(batch_size)
+ if not rows:
+ break
+ for row in rows:
+ if row['num'] % 2:
+ odd += 1
+return odd
+$$ LANGUAGE plpython3u;
+
+CREATE FUNCTION count_odd_prepared() RETURNS integer AS $$
+odd = 0
+plan = plpy.prepare("select num from largetable where num % $1 &lt;&gt; 0", ["integer"])
+rows = list(plpy.cursor(plan, [2])) # or: = list(plan.cursor([2]))
+
+return len(rows)
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p><p>
+ Cursors are automatically disposed of. But if you want to explicitly
+ release all resources held by a cursor, use the <code class="literal">close</code>
+ method. Once closed, a cursor cannot be fetched from anymore.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Do not confuse objects created by <code class="literal">plpy.cursor</code> with
+ DB-API cursors as defined by
+ the <a class="ulink" href="https://www.python.org/dev/peps/pep-0249/" target="_top">Python
+ Database API specification</a>. They don't have anything in common
+ except for the name.
+ </p></div></dd></dl></div></div><div class="sect2" id="PLPYTHON-TRAPPING"><div class="titlepage"><div><div><h3 class="title">46.6.2. Trapping Errors</h3></div></div></div><p>
+ Functions accessing the database might encounter errors, which
+ will cause them to abort and raise an exception. Both
+ <code class="function">plpy.execute</code> and
+ <code class="function">plpy.prepare</code> can raise an instance of a subclass of
+ <code class="literal">plpy.SPIError</code>, which by default will terminate
+ the function. This error can be handled just like any other
+ Python exception, by using the <code class="literal">try/except</code>
+ construct. For example:
+</p><pre class="programlisting">
+CREATE FUNCTION try_adding_joe() RETURNS text AS $$
+ try:
+ plpy.execute("INSERT INTO users(username) VALUES ('joe')")
+ except plpy.SPIError:
+ return "something went wrong"
+ else:
+ return "Joe added"
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p><p>
+ The actual class of the exception being raised corresponds to the
+ specific condition that caused the error. Refer
+ to <a class="xref" href="errcodes-appendix.html#ERRCODES-TABLE" title="Table A.1. PostgreSQL Error Codes">Table A.1</a> for a list of possible
+ conditions. The module
+ <code class="literal">plpy.spiexceptions</code> defines an exception class
+ for each <span class="productname">PostgreSQL</span> condition, deriving
+ their names from the condition name. For
+ instance, <code class="literal">division_by_zero</code>
+ becomes <code class="literal">DivisionByZero</code>, <code class="literal">unique_violation</code>
+ becomes <code class="literal">UniqueViolation</code>, <code class="literal">fdw_error</code>
+ becomes <code class="literal">FdwError</code>, and so on. Each of these
+ exception classes inherits from <code class="literal">SPIError</code>. This
+ separation makes it easier to handle specific errors, for
+ instance:
+</p><pre class="programlisting">
+CREATE FUNCTION insert_fraction(numerator int, denominator int) RETURNS text AS $$
+from plpy import spiexceptions
+try:
+ plan = plpy.prepare("INSERT INTO fractions (frac) VALUES ($1 / $2)", ["int", "int"])
+ plpy.execute(plan, [numerator, denominator])
+except spiexceptions.DivisionByZero:
+ return "denominator cannot equal zero"
+except spiexceptions.UniqueViolation:
+ return "already have that fraction"
+except plpy.SPIError as e:
+ return "other error, SQLSTATE %s" % e.sqlstate
+else:
+ return "fraction inserted"
+$$ LANGUAGE plpython3u;
+</pre><p>
+ Note that because all exceptions from
+ the <code class="literal">plpy.spiexceptions</code> module inherit
+ from <code class="literal">SPIError</code>, an <code class="literal">except</code>
+ clause handling it will catch any database access error.
+ </p><p>
+ As an alternative way of handling different error conditions, you
+ can catch the <code class="literal">SPIError</code> exception and determine
+ the specific error condition inside the <code class="literal">except</code>
+ block by looking at the <code class="literal">sqlstate</code> attribute of
+ the exception object. This attribute is a string value containing
+ the <span class="quote">“<span class="quote">SQLSTATE</span>”</span> error code. This approach provides
+ approximately the same functionality
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-trigger.html" title="46.5. Trigger Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.5. Trigger Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.7. Explicit Subtransactions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-do.html b/doc/src/sgml/html/plpython-do.html
new file mode 100644
index 0000000..dc8b4ae
--- /dev/null
+++ b/doc/src/sgml/html/plpython-do.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.4. Anonymous Code Blocks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-sharing.html" title="46.3. Sharing Data" /><link rel="next" href="plpython-trigger.html" title="46.5. Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.4. Anonymous Code Blocks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-sharing.html" title="46.3. Sharing Data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-trigger.html" title="46.5. Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-DO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.4. Anonymous Code Blocks</h2></div></div></div><p>
+ PL/Python also supports anonymous code blocks called with the
+ <a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> statement:
+
+</p><pre class="programlisting">
+DO $$
+ # PL/Python code
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ An anonymous code block receives no arguments, and whatever value it
+ might return is discarded. Otherwise it behaves just like a function.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-sharing.html" title="46.3. Sharing Data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-trigger.html" title="46.5. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.3. Sharing Data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.5. Trigger Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-envar.html b/doc/src/sgml/html/plpython-envar.html
new file mode 100644
index 0000000..fb5385c
--- /dev/null
+++ b/doc/src/sgml/html/plpython-envar.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.11. Environment Variables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3" /><link rel="next" href="spi.html" title="Chapter 47. Server Programming Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.11. Environment Variables</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi.html" title="Chapter 47. Server Programming Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-ENVAR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.11. Environment Variables</h2></div></div></div><p>
+ Some of the environment variables that are accepted by the Python
+ interpreter can also be used to affect PL/Python behavior. They
+ would need to be set in the environment of the main PostgreSQL
+ server process, for example in a start script. The available
+ environment variables depend on the version of Python; see the
+ Python documentation for details. At the time of this writing, the
+ following environment variables have an affect on PL/Python,
+ assuming an adequate Python version:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="envar">PYTHONHOME</code></p></li><li class="listitem"><p><code class="envar">PYTHONPATH</code></p></li><li class="listitem"><p><code class="envar">PYTHONY2K</code></p></li><li class="listitem"><p><code class="envar">PYTHONOPTIMIZE</code></p></li><li class="listitem"><p><code class="envar">PYTHONDEBUG</code></p></li><li class="listitem"><p><code class="envar">PYTHONVERBOSE</code></p></li><li class="listitem"><p><code class="envar">PYTHONCASEOK</code></p></li><li class="listitem"><p><code class="envar">PYTHONDONTWRITEBYTECODE</code></p></li><li class="listitem"><p><code class="envar">PYTHONIOENCODING</code></p></li><li class="listitem"><p><code class="envar">PYTHONUSERBASE</code></p></li><li class="listitem"><p><code class="envar">PYTHONHASHSEED</code></p></li></ul></div><p>
+
+ (It appears to be a Python implementation detail beyond the control
+ of PL/Python that some of the environment variables listed on
+ the <code class="command">python</code> man page are only effective in a
+ command-line interpreter and not an embedded Python interpreter.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi.html" title="Chapter 47. Server Programming Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.10. Python 2 vs. Python 3 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 47. Server Programming Interface</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-funcs.html b/doc/src/sgml/html/plpython-funcs.html
new file mode 100644
index 0000000..16fe9c3
--- /dev/null
+++ b/doc/src/sgml/html/plpython-funcs.html
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.1. PL/Python Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language" /><link rel="next" href="plpython-data.html" title="46.2. Data Values" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.1. PL/Python Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-data.html" title="46.2. Data Values">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.1. PL/Python Functions</h2></div></div></div><p>
+ Functions in PL/Python are declared via the
+ standard <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> syntax:
+
+</p><pre class="programlisting">
+CREATE FUNCTION <em class="replaceable"><code>funcname</code></em> (<em class="replaceable"><code>argument-list</code></em>)
+ RETURNS <em class="replaceable"><code>return-type</code></em>
+AS $$
+ # PL/Python function body
+$$ LANGUAGE plpython3u;
+</pre><p>
+ </p><p>
+ The body of a function is simply a Python script. When the function
+ is called, its arguments are passed as elements of the list
+ <code class="varname">args</code>; named arguments are also passed as
+ ordinary variables to the Python script. Use of named arguments is
+ usually more readable. The result is returned from the Python code
+ in the usual way, with <code class="literal">return</code> or
+ <code class="literal">yield</code> (in case of a result-set statement). If
+ you do not provide a return value, Python returns the default
+ <code class="symbol">None</code>. <span class="application">PL/Python</span> translates
+ Python's <code class="symbol">None</code> into the SQL null value. In a procedure,
+ the result from the Python code must be <code class="symbol">None</code> (typically
+ achieved by ending the procedure without a <code class="literal">return</code>
+ statement or by using a <code class="literal">return</code> statement without
+ argument); otherwise, an error will be raised.
+ </p><p>
+ For example, a function to return the greater of two integers can be
+ defined as:
+
+</p><pre class="programlisting">
+CREATE FUNCTION pymax (a integer, b integer)
+ RETURNS integer
+AS $$
+ if a &gt; b:
+ return a
+ return b
+$$ LANGUAGE plpython3u;
+</pre><p>
+
+ The Python code that is given as the body of the function definition
+ is transformed into a Python function. For example, the above results in:
+
+</p><pre class="programlisting">
+def __plpython_procedure_pymax_23456():
+ if a &gt; b:
+ return a
+ return b
+</pre><p>
+
+ assuming that 23456 is the OID assigned to the function by
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ The arguments are set as global variables. Because of the scoping
+ rules of Python, this has the subtle consequence that an argument
+ variable cannot be reassigned inside the function to the value of
+ an expression that involves the variable name itself, unless the
+ variable is redeclared as global in the block. For example, the
+ following won't work:
+</p><pre class="programlisting">
+CREATE FUNCTION pystrip(x text)
+ RETURNS text
+AS $$
+ x = x.strip() # error
+ return x
+$$ LANGUAGE plpython3u;
+</pre><p>
+ because assigning to <code class="varname">x</code>
+ makes <code class="varname">x</code> a local variable for the entire block,
+ and so the <code class="varname">x</code> on the right-hand side of the
+ assignment refers to a not-yet-assigned local
+ variable <code class="varname">x</code>, not the PL/Python function
+ parameter. Using the <code class="literal">global</code> statement, this can
+ be made to work:
+</p><pre class="programlisting">
+CREATE FUNCTION pystrip(x text)
+ RETURNS text
+AS $$
+ global x
+ x = x.strip() # ok now
+ return x
+$$ LANGUAGE plpython3u;
+</pre><p>
+ But it is advisable not to rely on this implementation detail of
+ PL/Python. It is better to treat the function parameters as
+ read-only.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-data.html" title="46.2. Data Values">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 46. PL/Python — Python Procedural Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.2. Data Values</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-python23.html b/doc/src/sgml/html/plpython-python23.html
new file mode 100644
index 0000000..9c9a970
--- /dev/null
+++ b/doc/src/sgml/html/plpython-python23.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.10. Python 2 vs. Python 3</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-util.html" title="46.9. Utility Functions" /><link rel="next" href="plpython-envar.html" title="46.11. Environment Variables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.10. Python 2 vs. Python 3</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-util.html" title="46.9. Utility Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-envar.html" title="46.11. Environment Variables">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-PYTHON23"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.10. Python 2 vs. Python 3</h2></div></div></div><p>
+ PL/Python supports only Python 3. Past versions of
+ <span class="productname">PostgreSQL</span> supported Python 2, using the
+ <code class="literal">plpythonu</code> and <code class="literal">plpython2u</code> language
+ names.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-util.html" title="46.9. Utility Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-envar.html" title="46.11. Environment Variables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.9. Utility Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.11. Environment Variables</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-sharing.html b/doc/src/sgml/html/plpython-sharing.html
new file mode 100644
index 0000000..f3841a5
--- /dev/null
+++ b/doc/src/sgml/html/plpython-sharing.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.3. Sharing Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-data.html" title="46.2. Data Values" /><link rel="next" href="plpython-do.html" title="46.4. Anonymous Code Blocks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.3. Sharing Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-data.html" title="46.2. Data Values">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-do.html" title="46.4. Anonymous Code Blocks">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-SHARING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.3. Sharing Data</h2></div></div></div><p>
+ The global dictionary <code class="varname">SD</code> is available to store
+ private data between repeated calls to the same function.
+ The global dictionary <code class="varname">GD</code> is public data,
+ that is available to all Python functions within a session; use with
+ care.<a id="id-1.8.11.11.2.3" class="indexterm"></a>
+ </p><p>
+ Each function gets its own execution environment in the
+ Python interpreter, so that global data and function arguments from
+ <code class="function">myfunc</code> are not available to
+ <code class="function">myfunc2</code>. The exception is the data in the
+ <code class="varname">GD</code> dictionary, as mentioned above.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-data.html" title="46.2. Data Values">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-do.html" title="46.4. Anonymous Code Blocks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.2. Data Values </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.4. Anonymous Code Blocks</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-subtransaction.html b/doc/src/sgml/html/plpython-subtransaction.html
new file mode 100644
index 0000000..5481342
--- /dev/null
+++ b/doc/src/sgml/html/plpython-subtransaction.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.7. Explicit Subtransactions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-database.html" title="46.6. Database Access" /><link rel="next" href="plpython-transactions.html" title="46.8. Transaction Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.7. Explicit Subtransactions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-database.html" title="46.6. Database Access">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-transactions.html" title="46.8. Transaction Management">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-SUBTRANSACTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.7. Explicit Subtransactions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpython-subtransaction.html#id-1.8.11.15.3">46.7.1. Subtransaction Context Managers</a></span></dt></dl></div><p>
+ Recovering from errors caused by database access as described in
+ <a class="xref" href="plpython-database.html#PLPYTHON-TRAPPING" title="46.6.2. Trapping Errors">Section 46.6.2</a> can lead to an undesirable
+ situation where some operations succeed before one of them fails,
+ and after recovering from that error the data is left in an
+ inconsistent state. PL/Python offers a solution to this problem in
+ the form of explicit subtransactions.
+ </p><div class="sect2" id="id-1.8.11.15.3"><div class="titlepage"><div><div><h3 class="title">46.7.1. Subtransaction Context Managers</h3></div></div></div><p>
+ Consider a function that implements a transfer between two
+ accounts:
+</p><pre class="programlisting">
+CREATE FUNCTION transfer_funds() RETURNS void AS $$
+try:
+ plpy.execute("UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'")
+ plpy.execute("UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'")
+except plpy.SPIError as e:
+ result = "error transferring funds: %s" % e.args
+else:
+ result = "funds transferred correctly"
+plan = plpy.prepare("INSERT INTO operations (result) VALUES ($1)", ["text"])
+plpy.execute(plan, [result])
+$$ LANGUAGE plpython3u;
+</pre><p>
+ If the second <code class="literal">UPDATE</code> statement results in an
+ exception being raised, this function will report the error, but
+ the result of the first <code class="literal">UPDATE</code> will
+ nevertheless be committed. In other words, the funds will be
+ withdrawn from Joe's account, but will not be transferred to
+ Mary's account.
+ </p><p>
+ To avoid such issues, you can wrap your
+ <code class="literal">plpy.execute</code> calls in an explicit
+ subtransaction. The <code class="literal">plpy</code> module provides a
+ helper object to manage explicit subtransactions that gets created
+ with the <code class="literal">plpy.subtransaction()</code> function.
+ Objects created by this function implement the
+ <a class="ulink" href="https://docs.python.org/library/stdtypes.html#context-manager-types" target="_top">
+ context manager interface</a>. Using explicit subtransactions
+ we can rewrite our function as:
+</p><pre class="programlisting">
+CREATE FUNCTION transfer_funds2() RETURNS void AS $$
+try:
+ with plpy.subtransaction():
+ plpy.execute("UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'")
+ plpy.execute("UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'")
+except plpy.SPIError as e:
+ result = "error transferring funds: %s" % e.args
+else:
+ result = "funds transferred correctly"
+plan = plpy.prepare("INSERT INTO operations (result) VALUES ($1)", ["text"])
+plpy.execute(plan, [result])
+$$ LANGUAGE plpython3u;
+</pre><p>
+ Note that the use of <code class="literal">try/catch</code> is still
+ required. Otherwise the exception would propagate to the top of
+ the Python stack and would cause the whole function to abort with
+ a <span class="productname">PostgreSQL</span> error, so that the
+ <code class="literal">operations</code> table would not have any row
+ inserted into it. The subtransaction context manager does not
+ trap errors, it only assures that all database operations executed
+ inside its scope will be atomically committed or rolled back. A
+ rollback of the subtransaction block occurs on any kind of
+ exception exit, not only ones caused by errors originating from
+ database access. A regular Python exception raised inside an
+ explicit subtransaction block would also cause the subtransaction
+ to be rolled back.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-database.html" title="46.6. Database Access">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-transactions.html" title="46.8. Transaction Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.6. Database Access </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.8. Transaction Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-transactions.html b/doc/src/sgml/html/plpython-transactions.html
new file mode 100644
index 0000000..df37548
--- /dev/null
+++ b/doc/src/sgml/html/plpython-transactions.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.8. Transaction Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions" /><link rel="next" href="plpython-util.html" title="46.9. Utility Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.8. Transaction Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-util.html" title="46.9. Utility Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-TRANSACTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.8. Transaction Management</h2></div></div></div><p>
+ In a procedure called from the top level or an anonymous code block
+ (<code class="command">DO</code> command) called from the top level it is possible to
+ control transactions. To commit the current transaction, call
+ <code class="literal">plpy.commit()</code>. To roll back the current transaction,
+ call <code class="literal">plpy.rollback()</code>. (Note that it is not possible to
+ run the SQL commands <code class="command">COMMIT</code> or
+ <code class="command">ROLLBACK</code> via <code class="function">plpy.execute</code> or
+ similar. It has to be done using these functions.) After a transaction is
+ ended, a new transaction is automatically started, so there is no separate
+ function for that.
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+CREATE PROCEDURE transaction_test1()
+LANGUAGE plpython3u
+AS $$
+for i in range(0, 10):
+ plpy.execute("INSERT INTO test1 (a) VALUES (%d)" % i)
+ if i % 2 == 0:
+ plpy.commit()
+ else:
+ plpy.rollback()
+$$;
+
+CALL transaction_test1();
+</pre><p>
+ </p><p>
+ Transactions cannot be ended when an explicit subtransaction is active.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-subtransaction.html" title="46.7. Explicit Subtransactions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-util.html" title="46.9. Utility Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.7. Explicit Subtransactions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.9. Utility Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-trigger.html b/doc/src/sgml/html/plpython-trigger.html
new file mode 100644
index 0000000..a291a9e
--- /dev/null
+++ b/doc/src/sgml/html/plpython-trigger.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.5. Trigger Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-do.html" title="46.4. Anonymous Code Blocks" /><link rel="next" href="plpython-database.html" title="46.6. Database Access" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.5. Trigger Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-do.html" title="46.4. Anonymous Code Blocks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-database.html" title="46.6. Database Access">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.5. Trigger Functions</h2></div></div></div><a id="id-1.8.11.13.2" class="indexterm"></a><p>
+ When a function is used as a trigger, the dictionary
+ <code class="literal">TD</code> contains trigger-related values:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TD["event"]</code></span></dt><dd><p>
+ contains the event as a string:
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code>.
+ </p></dd><dt><span class="term"><code class="literal">TD["when"]</code></span></dt><dd><p>
+ contains one of <code class="literal">BEFORE</code>, <code class="literal">AFTER</code>, or
+ <code class="literal">INSTEAD OF</code>.
+ </p></dd><dt><span class="term"><code class="literal">TD["level"]</code></span></dt><dd><p>
+ contains <code class="literal">ROW</code> or <code class="literal">STATEMENT</code>.
+ </p></dd><dt><span class="term"><code class="literal">TD["new"]</code><br /></span><span class="term"><code class="literal">TD["old"]</code></span></dt><dd><p>
+ For a row-level trigger, one or both of these fields contain
+ the respective trigger rows, depending on the trigger event.
+ </p></dd><dt><span class="term"><code class="literal">TD["name"]</code></span></dt><dd><p>
+ contains the trigger name.
+ </p></dd><dt><span class="term"><code class="literal">TD["table_name"]</code></span></dt><dd><p>
+ contains the name of the table on which the trigger occurred.
+ </p></dd><dt><span class="term"><code class="literal">TD["table_schema"]</code></span></dt><dd><p>
+ contains the schema of the table on which the trigger occurred.
+ </p></dd><dt><span class="term"><code class="literal">TD["relid"]</code></span></dt><dd><p>
+ contains the OID of the table on which the trigger occurred.
+ </p></dd><dt><span class="term"><code class="literal">TD["args"]</code></span></dt><dd><p>
+ If the <code class="command">CREATE TRIGGER</code> command
+ included arguments, they are available in <code class="literal">TD["args"][0]</code> to
+ <code class="literal">TD["args"][<em class="replaceable"><code>n</code></em>-1]</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ If <code class="literal">TD["when"]</code> is <code class="literal">BEFORE</code> or
+ <code class="literal">INSTEAD OF</code> and
+ <code class="literal">TD["level"]</code> is <code class="literal">ROW</code>, you can
+ return <code class="literal">None</code> or <code class="literal">"OK"</code> from the
+ Python function to indicate the row is unmodified,
+ <code class="literal">"SKIP"</code> to abort the event, or if <code class="literal">TD["event"]</code>
+ is <code class="command">INSERT</code> or <code class="command">UPDATE</code> you can return
+ <code class="literal">"MODIFY"</code> to indicate you've modified the new row.
+ Otherwise the return value is ignored.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-do.html" title="46.4. Anonymous Code Blocks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-database.html" title="46.6. Database Access">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.4. Anonymous Code Blocks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.6. Database Access</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython-util.html b/doc/src/sgml/html/plpython-util.html
new file mode 100644
index 0000000..0e3bc21
--- /dev/null
+++ b/doc/src/sgml/html/plpython-util.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.9. Utility Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-transactions.html" title="46.8. Transaction Management" /><link rel="next" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.9. Utility Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-transactions.html" title="46.8. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python — Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPYTHON-UTIL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.9. Utility Functions</h2></div></div></div><p>
+ The <code class="literal">plpy</code> module also provides the functions
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">plpy.debug(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.log(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.info(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.notice(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.warning(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.error(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.fatal(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr></table><p>
+ <a id="id-1.8.11.17.2.3" class="indexterm"></a>
+ <code class="function">plpy.error</code> and <code class="function">plpy.fatal</code>
+ actually raise a Python exception which, if uncaught, propagates out to
+ the calling query, causing the current transaction or subtransaction to
+ be aborted. <code class="literal">raise plpy.Error(<em class="replaceable"><code>msg</code></em>)</code> and
+ <code class="literal">raise plpy.Fatal(<em class="replaceable"><code>msg</code></em>)</code> are
+ equivalent to calling <code class="literal">plpy.error(<em class="replaceable"><code>msg</code></em>)</code> and
+ <code class="literal">plpy.fatal(<em class="replaceable"><code>msg</code></em>)</code>, respectively but
+ the <code class="literal">raise</code> form does not allow passing keyword arguments.
+ The other functions only generate messages of different priority levels.
+ Whether messages of a particular priority are reported to the client,
+ written to the server log, or both is controlled by the
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
+ variables. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for more information.
+ </p><p>
+ The <em class="replaceable"><code>msg</code></em> argument is given as a positional argument. For
+ backward compatibility, more than one positional argument can be given. In
+ that case, the string representation of the tuple of positional arguments
+ becomes the message reported to the client.
+ </p><p>
+ The following keyword-only arguments are accepted:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">detail</code></td></tr><tr><td><code class="literal">hint</code></td></tr><tr><td><code class="literal">sqlstate</code></td></tr><tr><td><code class="literal">schema_name</code></td></tr><tr><td><code class="literal">table_name</code></td></tr><tr><td><code class="literal">column_name</code></td></tr><tr><td><code class="literal">datatype_name</code></td></tr><tr><td><code class="literal">constraint_name</code></td></tr></table><p>
+ The string representation of the objects passed as keyword-only arguments
+ is used to enrich the messages reported to the client. For example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION raise_custom_exception() RETURNS void AS $$
+plpy.error("custom exception message",
+ detail="some info about exception",
+ hint="hint for users")
+$$ LANGUAGE plpython3u;
+
+=# SELECT raise_custom_exception();
+ERROR: plpy.Error: custom exception message
+DETAIL: some info about exception
+HINT: hint for users
+CONTEXT: Traceback (most recent call last):
+ PL/Python function "raise_custom_exception", line 4, in &lt;module&gt;
+ hint="hint for users")
+PL/Python function "raise_custom_exception"
+</pre><p>
+ </p><p>
+ Another set of utility functions are
+ <code class="literal">plpy.quote_literal(<em class="replaceable"><code>string</code></em>)</code>,
+ <code class="literal">plpy.quote_nullable(<em class="replaceable"><code>string</code></em>)</code>, and
+ <code class="literal">plpy.quote_ident(<em class="replaceable"><code>string</code></em>)</code>. They
+ are equivalent to the built-in quoting functions described in <a class="xref" href="functions-string.html" title="9.4. String Functions and Operators">Section 9.4</a>. They are useful when constructing
+ ad-hoc queries. A PL/Python equivalent of dynamic SQL from <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values in Dynamic Queries">Example 43.1</a> would be:
+</p><pre class="programlisting">
+plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
+ plpy.quote_ident(colname),
+ plpy.quote_nullable(newvalue),
+ plpy.quote_literal(keyvalue)))
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-transactions.html" title="46.8. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-python23.html" title="46.10. Python 2 vs. Python 3">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.8. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.10. Python 2 vs. Python 3</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/plpython.html b/doc/src/sgml/html/plpython.html
new file mode 100644
index 0000000..be8fc63
--- /dev/null
+++ b/doc/src/sgml/html/plpython.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 46. PL/Python — Python Procedural Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood" /><link rel="next" href="plpython-funcs.html" title="46.1. PL/Python Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 46. PL/Python — Python Procedural Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-funcs.html" title="46.1. PL/Python Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLPYTHON"><div class="titlepage"><div><div><h2 class="title">Chapter 46. PL/Python — Python Procedural Language</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="plpython-funcs.html">46.1. PL/Python Functions</a></span></dt><dt><span class="sect1"><a href="plpython-data.html">46.2. Data Values</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.3">46.2.1. Data Type Mapping</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.4">46.2.2. Null, None</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#PLPYTHON-ARRAYS">46.2.3. Arrays, Lists</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.6">46.2.4. Composite Types</a></span></dt><dt><span class="sect2"><a href="plpython-data.html#id-1.8.11.10.7">46.2.5. Set-Returning Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpython-sharing.html">46.3. Sharing Data</a></span></dt><dt><span class="sect1"><a href="plpython-do.html">46.4. Anonymous Code Blocks</a></span></dt><dt><span class="sect1"><a href="plpython-trigger.html">46.5. Trigger Functions</a></span></dt><dt><span class="sect1"><a href="plpython-database.html">46.6. Database Access</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpython-database.html#id-1.8.11.14.3">46.6.1. Database Access Functions</a></span></dt><dt><span class="sect2"><a href="plpython-database.html#PLPYTHON-TRAPPING">46.6.2. Trapping Errors</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpython-subtransaction.html">46.7. Explicit Subtransactions</a></span></dt><dd><dl><dt><span class="sect2"><a href="plpython-subtransaction.html#id-1.8.11.15.3">46.7.1. Subtransaction Context Managers</a></span></dt></dl></dd><dt><span class="sect1"><a href="plpython-transactions.html">46.8. Transaction Management</a></span></dt><dt><span class="sect1"><a href="plpython-util.html">46.9. Utility Functions</a></span></dt><dt><span class="sect1"><a href="plpython-python23.html">46.10. Python 2 vs. Python 3</a></span></dt><dt><span class="sect1"><a href="plpython-envar.html">46.11. Environment Variables</a></span></dt></dl></div><a id="id-1.8.11.2" class="indexterm"></a><a id="id-1.8.11.3" class="indexterm"></a><p>
+ The <span class="application">PL/Python</span> procedural language allows
+ <span class="productname">PostgreSQL</span> functions and procedures to be written in the
+ <a class="ulink" href="https://www.python.org" target="_top">Python language</a>.
+ </p><p>
+ To install PL/Python in a particular database, use
+ <code class="literal">CREATE EXTENSION plpython3u</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If a language is installed into <code class="literal">template1</code>, all subsequently
+ created databases will have the language installed automatically.
+ </p></div><p>
+ PL/Python is only available as an <span class="quote">“<span class="quote">untrusted</span>”</span> language, meaning
+ it does not offer any way of restricting what users can do in it and
+ is therefore named <code class="literal">plpython3u</code>. A trusted
+ variant <code class="literal">plpython</code> might become available in the future
+ if a secure execution mechanism is developed in Python. The
+ writer of a function in untrusted PL/Python must take care that the
+ function cannot be used to do anything unwanted, since it will be
+ able to do anything that could be done by a user logged in as the
+ database administrator. Only superusers can create functions in
+ untrusted languages such as <code class="literal">plpython3u</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Users of source packages must specially enable the build of
+ PL/Python during the installation process. (Refer to the
+ installation instructions for more information.) Users of binary
+ packages might find PL/Python in a separate subpackage.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plperl-under-the-hood.html" title="45.8. PL/Perl Under the Hood">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-funcs.html" title="46.1. PL/Python Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">45.8. PL/Perl Under the Hood </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 46.1. PL/Python Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-config.html b/doc/src/sgml/html/pltcl-config.html
new file mode 100644
index 0000000..656f505
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-config.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.11. PL/Tcl Configuration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-transactions.html" title="44.10. Transaction Management" /><link rel="next" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.11. PL/Tcl Configuration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-transactions.html" title="44.10. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.11. PL/Tcl Configuration</h2></div></div></div><p>
+ This section lists configuration parameters that
+ affect <span class="application">PL/Tcl</span>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-PLTCL-START-PROC"><span class="term">
+ <code class="varname">pltcl.start_proc</code> (<code class="type">string</code>)
+ <a id="id-1.8.9.15.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter, if set to a nonempty string, specifies the name
+ (possibly schema-qualified) of a parameterless PL/Tcl function that
+ is to be executed whenever a new Tcl interpreter is created for
+ PL/Tcl. Such a function can perform per-session initialization, such
+ as loading additional Tcl code. A new Tcl interpreter is created
+ when a PL/Tcl function is first executed in a database session, or
+ when an additional interpreter has to be created because a PL/Tcl
+ function is called by a new SQL role.
+ </p><p>
+ The referenced function must be written in the <code class="literal">pltcl</code>
+ language, and must not be marked <code class="literal">SECURITY DEFINER</code>.
+ (These restrictions ensure that it runs in the interpreter it's
+ supposed to initialize.) The current user must have permission to
+ call it, too.
+ </p><p>
+ If the function fails with an error it will abort the function call
+ that caused the new interpreter to be created and propagate out to
+ the calling query, causing the current transaction or subtransaction
+ to be aborted. Any actions already done within Tcl won't be undone;
+ however, that interpreter won't be used again. If the language is
+ used again the initialization will be attempted again within a fresh
+ Tcl interpreter.
+ </p><p>
+ Only superusers can change this setting. Although this setting
+ can be changed within a session, such changes will not affect Tcl
+ interpreters that have already been created.
+ </p></dd><dt id="GUC-PLTCLU-START-PROC"><span class="term">
+ <code class="varname">pltclu.start_proc</code> (<code class="type">string</code>)
+ <a id="id-1.8.9.15.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter is exactly like <code class="varname">pltcl.start_proc</code>,
+ except that it applies to PL/TclU. The referenced function must
+ be written in the <code class="literal">pltclu</code> language.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-transactions.html" title="44.10. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-procnames.html" title="44.12. Tcl Procedure Names">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.10. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.12. Tcl Procedure Names</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-data.html b/doc/src/sgml/html/pltcl-data.html
new file mode 100644
index 0000000..e6409bf
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-data.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.3. Data Values in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments" /><link rel="next" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.3. Data Values in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.3. Data Values in PL/Tcl</h2></div></div></div><p>
+ The argument values supplied to a PL/Tcl function's code are simply
+ the input arguments converted to text form (just as if they had been
+ displayed by a <code class="command">SELECT</code> statement). Conversely, the
+ <code class="literal">return</code> and <code class="literal">return_next</code> commands will accept
+ any string that is acceptable input format for the function's declared
+ result type, or for the specified column of a composite result type.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.2. PL/Tcl Functions and Arguments </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.4. Global Data in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-dbaccess.html b/doc/src/sgml/html/pltcl-dbaccess.html
new file mode 100644
index 0000000..025d849
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-dbaccess.html
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.5. Database Access from PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl" /><link rel="next" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.5. Database Access from PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-DBACCESS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.5. Database Access from PL/Tcl</h2></div></div></div><p>
+ In this section, we follow the usual Tcl convention of using question
+ marks, rather than brackets, to indicate an optional element in a
+ syntax synopsis. The following commands are available to access
+ the database from the body of a PL/Tcl function:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal"><code class="function">spi_exec</code> ?<span class="optional">-count <em class="replaceable"><code>n</code></em></span>? ?<span class="optional">-array <em class="replaceable"><code>name</code></em></span>? <em class="replaceable"><code>command</code></em> ?<span class="optional"><em class="replaceable"><code>loop-body</code></em></span>?</code></span></dt><dd><p>
+ Executes an SQL command given as a string. An error in the command
+ causes an error to be raised. Otherwise, the return value of <code class="function">spi_exec</code>
+ is the number of rows processed (selected, inserted, updated, or
+ deleted) by the command, or zero if the command is a utility
+ statement. In addition, if the command is a <code class="command">SELECT</code> statement, the
+ values of the selected columns are placed in Tcl variables as
+ described below.
+ </p><p>
+ The optional <code class="literal">-count</code> value tells
+ <code class="function">spi_exec</code> to stop
+ once <em class="replaceable"><code>n</code></em> rows have been retrieved,
+ much as if the query included a <code class="literal">LIMIT</code> clause.
+ If <em class="replaceable"><code>n</code></em> is zero, the query is run to
+ completion, the same as when <code class="literal">-count</code> is omitted.
+ </p><p>
+ If the command is a <code class="command">SELECT</code> statement, the values of the
+ result columns are placed into Tcl variables named after the columns.
+ If the <code class="literal">-array</code> option is given, the column values are
+ instead stored into elements of the named associative array, with the
+ column names used as array indexes. In addition, the current row
+ number within the result (counting from zero) is stored into the array
+ element named <span class="quote">“<span class="quote"><code class="literal">.tupno</code></span>”</span>, unless that name is
+ in use as a column name in the result.
+ </p><p>
+ If the command is a <code class="command">SELECT</code> statement and no <em class="replaceable"><code>loop-body</code></em>
+ script is given, then only the first row of results are stored into
+ Tcl variables or array elements; remaining rows, if any, are ignored.
+ No storing occurs if the query returns no rows. (This case can be
+ detected by checking the result of <code class="function">spi_exec</code>.)
+ For example:
+</p><pre class="programlisting">
+spi_exec "SELECT count(*) AS cnt FROM pg_proc"
+</pre><p>
+ will set the Tcl variable <code class="literal">$cnt</code> to the number of rows in
+ the <code class="structname">pg_proc</code> system catalog.
+ </p><p>
+ If the optional <em class="replaceable"><code>loop-body</code></em> argument is given, it is
+ a piece of Tcl script that is executed once for each row in the
+ query result. (<em class="replaceable"><code>loop-body</code></em> is ignored if the given
+ command is not a <code class="command">SELECT</code>.)
+ The values of the current row's columns
+ are stored into Tcl variables or array elements before each iteration.
+ For example:
+</p><pre class="programlisting">
+spi_exec -array C "SELECT * FROM pg_class" {
+ elog DEBUG "have table $C(relname)"
+}
+</pre><p>
+ will print a log message for every row of <code class="literal">pg_class</code>. This
+ feature works similarly to other Tcl looping constructs; in
+ particular <code class="literal">continue</code> and <code class="literal">break</code> work in the
+ usual way inside the loop body.
+ </p><p>
+ If a column of a query result is null, the target
+ variable for it is <span class="quote">“<span class="quote">unset</span>”</span> rather than being set.
+ </p></dd><dt><span class="term"><code class="function">spi_prepare</code> <em class="replaceable"><code>query</code></em> <em class="replaceable"><code>typelist</code></em></span></dt><dd><p>
+ Prepares and saves a query plan for later execution. The
+ saved plan will be retained for the life of the current
+ session.<a id="id-1.8.9.9.2.1.2.2.1.1" class="indexterm"></a>
+ </p><p>
+ The query can use parameters, that is, placeholders for
+ values to be supplied whenever the plan is actually executed.
+ In the query string, refer to parameters
+ by the symbols <code class="literal">$1</code> ... <code class="literal">$<em class="replaceable"><code>n</code></em></code>.
+ If the query uses parameters, the names of the parameter types
+ must be given as a Tcl list. (Write an empty list for
+ <em class="replaceable"><code>typelist</code></em> if no parameters are used.)
+ </p><p>
+ The return value from <code class="function">spi_prepare</code> is a query ID
+ to be used in subsequent calls to <code class="function">spi_execp</code>. See
+ <code class="function">spi_execp</code> for an example.
+ </p></dd><dt><span class="term"><code class="literal"><code class="function">spi_execp</code> ?<span class="optional">-count <em class="replaceable"><code>n</code></em></span>? ?<span class="optional">-array <em class="replaceable"><code>name</code></em></span>? ?<span class="optional">-nulls <em class="replaceable"><code>string</code></em></span>? <em class="replaceable"><code>queryid</code></em> ?<span class="optional"><em class="replaceable"><code>value-list</code></em></span>? ?<span class="optional"><em class="replaceable"><code>loop-body</code></em></span>?</code></span></dt><dd><p>
+ Executes a query previously prepared with <code class="function">spi_prepare</code>.
+ <em class="replaceable"><code>queryid</code></em> is the ID returned by
+ <code class="function">spi_prepare</code>. If the query references parameters,
+ a <em class="replaceable"><code>value-list</code></em> must be supplied. This
+ is a Tcl list of actual values for the parameters. The list must be
+ the same length as the parameter type list previously given to
+ <code class="function">spi_prepare</code>. Omit <em class="replaceable"><code>value-list</code></em>
+ if the query has no parameters.
+ </p><p>
+ The optional value for <code class="literal">-nulls</code> is a string of spaces and
+ <code class="literal">'n'</code> characters telling <code class="function">spi_execp</code>
+ which of the parameters are null values. If given, it must have exactly the
+ same length as the <em class="replaceable"><code>value-list</code></em>. If it
+ is not given, all the parameter values are nonnull.
+ </p><p>
+ Except for the way in which the query and its parameters are specified,
+ <code class="function">spi_execp</code> works just like <code class="function">spi_exec</code>.
+ The <code class="literal">-count</code>, <code class="literal">-array</code>, and
+ <em class="replaceable"><code>loop-body</code></em> options are the same,
+ and so is the result value.
+ </p><p>
+ Here's an example of a PL/Tcl function using a prepared plan:
+
+</p><pre class="programlisting">
+CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS $$
+ if {![ info exists GD(plan) ]} {
+ # prepare the saved plan on the first call
+ set GD(plan) [ spi_prepare \
+ "SELECT count(*) AS cnt FROM t1 WHERE num &gt;= \$1 AND num &lt;= \$2" \
+ [ list int4 int4 ] ]
+ }
+ spi_execp -count 1 $GD(plan) [ list $1 $2 ]
+ return $cnt
+$$ LANGUAGE pltcl;
+</pre><p>
+
+ We need backslashes inside the query string given to
+ <code class="function">spi_prepare</code> to ensure that the
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code> markers will be passed
+ through to <code class="function">spi_prepare</code> as-is, and not replaced by Tcl
+ variable substitution.
+
+ </p></dd><dt><span class="term"><code class="function">subtransaction</code> <em class="replaceable"><code>command</code></em></span></dt><dd><p>
+ The Tcl script contained in <em class="replaceable"><code>command</code></em> is
+ executed within an SQL subtransaction. If the script returns an
+ error, that entire subtransaction is rolled back before returning the
+ error out to the surrounding Tcl code.
+ See <a class="xref" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl">Section 44.9</a> for more details and an
+ example.
+ </p></dd><dt><span class="term"><code class="function">quote</code> <em class="replaceable"><code>string</code></em></span></dt><dd><p>
+ Doubles all occurrences of single quote and backslash characters
+ in the given string. This can be used to safely quote strings
+ that are to be inserted into SQL commands given
+ to <code class="function">spi_exec</code> or
+ <code class="function">spi_prepare</code>.
+ For example, think about an SQL command string like:
+
+</p><pre class="programlisting">
+"SELECT '$val' AS ret"
+</pre><p>
+
+ where the Tcl variable <code class="literal">val</code> actually contains
+ <code class="literal">doesn't</code>. This would result
+ in the final command string:
+
+</p><pre class="programlisting">
+SELECT 'doesn't' AS ret
+</pre><p>
+
+ which would cause a parse error during
+ <code class="function">spi_exec</code> or
+ <code class="function">spi_prepare</code>.
+ To work properly, the submitted command should contain:
+
+</p><pre class="programlisting">
+SELECT 'doesn''t' AS ret
+</pre><p>
+
+ which can be formed in PL/Tcl using:
+
+</p><pre class="programlisting">
+"SELECT '[ quote $val ]' AS ret"
+</pre><p>
+
+ One advantage of <code class="function">spi_execp</code> is that you don't
+ have to quote parameter values like this, since the parameters are never
+ parsed as part of an SQL command string.
+ </p></dd><dt><span class="term">
+ <code class="function">elog</code> <em class="replaceable"><code>level</code></em> <em class="replaceable"><code>msg</code></em>
+ <a id="id-1.8.9.9.2.1.6.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Emits a log or error message. Possible levels are
+ <code class="literal">DEBUG</code>, <code class="literal">LOG</code>, <code class="literal">INFO</code>,
+ <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>, <code class="literal">ERROR</code>, and
+ <code class="literal">FATAL</code>. <code class="literal">ERROR</code>
+ raises an error condition; if this is not trapped by the surrounding
+ Tcl code, the error propagates out to the calling query, causing
+ the current transaction or subtransaction to be aborted. This
+ is effectively the same as the Tcl <code class="literal">error</code> command.
+ <code class="literal">FATAL</code> aborts the transaction and causes the current
+ session to shut down. (There is probably no good reason to use
+ this error level in PL/Tcl functions, but it's provided for
+ completeness.) The other levels only generate messages of different
+ priority levels.
+ Whether messages of a particular priority are reported to the client,
+ written to the server log, or both is controlled by the
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
+ variables. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ and <a class="xref" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Section 44.8</a>
+ for more information.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-global.html" title="44.4. Global Data in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.4. Global Data in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.6. Trigger Functions in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-error-handling.html b/doc/src/sgml/html/pltcl-error-handling.html
new file mode 100644
index 0000000..1076c2c
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-error-handling.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.8. Error Handling in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl" /><link rel="next" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.8. Error Handling in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-ERROR-HANDLING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.8. Error Handling in PL/Tcl</h2></div></div></div><a id="id-1.8.9.12.2" class="indexterm"></a><p>
+ Tcl code within or called from a PL/Tcl function can raise an error,
+ either by executing some invalid operation or by generating an error
+ using the Tcl <code class="function">error</code> command or
+ PL/Tcl's <code class="function">elog</code> command. Such errors can be caught
+ within Tcl using the Tcl <code class="function">catch</code> command. If an
+ error is not caught but is allowed to propagate out to the top level of
+ execution of the PL/Tcl function, it is reported as an SQL error in the
+ function's calling query.
+ </p><p>
+ Conversely, SQL errors that occur within PL/Tcl's
+ <code class="function">spi_exec</code>, <code class="function">spi_prepare</code>,
+ and <code class="function">spi_execp</code> commands are reported as Tcl errors,
+ so they are catchable by Tcl's <code class="function">catch</code> command.
+ (Each of these PL/Tcl commands runs its SQL operation in a
+ subtransaction, which is rolled back on error, so that any
+ partially-completed operation is automatically cleaned up.)
+ Again, if an error propagates out to the top level without being caught,
+ it turns back into an SQL error.
+ </p><p>
+ Tcl provides an <code class="varname">errorCode</code> variable that can represent
+ additional information about an error in a form that is easy for Tcl
+ programs to interpret. The contents are in Tcl list format, and the
+ first word identifies the subsystem or library reporting the error;
+ beyond that the contents are left to the individual subsystem or
+ library. For database errors reported by PL/Tcl commands, the first
+ word is <code class="literal">POSTGRES</code>, the second word is the PostgreSQL
+ version number, and additional words are field name/value pairs
+ providing detailed information about the error.
+ Fields <code class="varname">SQLSTATE</code>, <code class="varname">condition</code>,
+ and <code class="varname">message</code> are always supplied
+ (the first two represent the error code and condition name as shown
+ in <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>).
+ Fields that may be present include
+ <code class="varname">detail</code>, <code class="varname">hint</code>, <code class="varname">context</code>,
+ <code class="varname">schema</code>, <code class="varname">table</code>, <code class="varname">column</code>,
+ <code class="varname">datatype</code>, <code class="varname">constraint</code>,
+ <code class="varname">statement</code>, <code class="varname">cursor_position</code>,
+ <code class="varname">filename</code>, <code class="varname">lineno</code>, and
+ <code class="varname">funcname</code>.
+ </p><p>
+ A convenient way to work with PL/Tcl's <code class="varname">errorCode</code>
+ information is to load it into an array, so that the field names become
+ array subscripts. Code for doing that might look like
+</p><pre class="programlisting">
+if {[catch { spi_exec $sql_command }]} {
+ if {[lindex $::errorCode 0] == "POSTGRES"} {
+ array set errorArray $::errorCode
+ if {$errorArray(condition) == "undefined_table"} {
+ # deal with missing table
+ } else {
+ # deal with some other type of SQL error
+ }
+ }
+}
+</pre><p>
+ (The double colons explicitly specify that <code class="varname">errorCode</code>
+ is a global variable.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.7. Event Trigger Functions in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.9. Explicit Subtransactions in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-event-trigger.html b/doc/src/sgml/html/pltcl-event-trigger.html
new file mode 100644
index 0000000..e821c66
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-event-trigger.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.7. Event Trigger Functions in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl" /><link rel="next" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.7. Event Trigger Functions in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-EVENT-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.7. Event Trigger Functions in PL/Tcl</h2></div></div></div><a id="id-1.8.9.11.2" class="indexterm"></a><p>
+ Event trigger functions can be written in PL/Tcl.
+ <span class="productname">PostgreSQL</span> requires that a function that is
+ to be called as an event trigger must be declared as a function with no
+ arguments and a return type of <code class="literal">event_trigger</code>.
+ </p><p>
+ The information from the trigger manager is passed to the function body
+ in the following variables:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">$TG_event</code></span></dt><dd><p>
+ The name of the event the trigger is fired for.
+ </p></dd><dt><span class="term"><code class="varname">$TG_tag</code></span></dt><dd><p>
+ The command tag for which the trigger is fired.
+ </p></dd></dl></div><p>
+ </p><p>
+ The return value of the trigger function is ignored.
+ </p><p>
+ Here's a little example event trigger function that simply raises
+ a <code class="literal">NOTICE</code> message each time a supported command is
+ executed:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION tclsnitch() RETURNS event_trigger AS $$
+ elog NOTICE "tclsnitch: $TG_event $TG_tag"
+$$ LANGUAGE pltcl;
+
+CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE FUNCTION tclsnitch();
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-trigger.html" title="44.6. Trigger Functions in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.6. Trigger Functions in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.8. Error Handling in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-functions.html b/doc/src/sgml/html/pltcl-functions.html
new file mode 100644
index 0000000..6e78564
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-functions.html
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.2. PL/Tcl Functions and Arguments</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-overview.html" title="44.1. Overview" /><link rel="next" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.2. PL/Tcl Functions and Arguments</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-overview.html" title="44.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.2. PL/Tcl Functions and Arguments</h2></div></div></div><p>
+ To create a function in the <span class="application">PL/Tcl</span> language, use
+ the standard <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> syntax:
+
+</p><pre class="programlisting">
+CREATE FUNCTION <em class="replaceable"><code>funcname</code></em> (<em class="replaceable"><code>argument-types</code></em>) RETURNS <em class="replaceable"><code>return-type</code></em> AS $$
+ # PL/Tcl function body
+$$ LANGUAGE pltcl;
+</pre><p>
+
+ <span class="application">PL/TclU</span> is the same, except that the language has to be specified as
+ <code class="literal">pltclu</code>.
+ </p><p>
+ The body of the function is simply a piece of Tcl script.
+ When the function is called, the argument values are passed to the
+ Tcl script as variables named <code class="literal">1</code>
+ ... <code class="literal"><em class="replaceable"><code>n</code></em></code>. The result is
+ returned from the Tcl code in the usual way, with
+ a <code class="literal">return</code> statement. In a procedure, the return value
+ from the Tcl code is ignored.
+ </p><p>
+ For example, a function
+ returning the greater of two integer values could be defined as:
+
+</p><pre class="programlisting">
+CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS $$
+ if {$1 &gt; $2} {return $1}
+ return $2
+$$ LANGUAGE pltcl STRICT;
+</pre><p>
+
+ Note the clause <code class="literal">STRICT</code>, which saves us from
+ having to think about null input values: if a null value is passed, the
+ function will not be called at all, but will just return a null
+ result automatically.
+ </p><p>
+ In a nonstrict function,
+ if the actual value of an argument is null, the corresponding
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code> variable will be set to an empty string.
+ To detect whether a particular argument is null, use the function
+ <code class="literal">argisnull</code>. For example, suppose that we wanted <code class="function">tcl_max</code>
+ with one null and one nonnull argument to return the nonnull
+ argument, rather than null:
+
+</p><pre class="programlisting">
+CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS $$
+ if {[argisnull 1]} {
+ if {[argisnull 2]} { return_null }
+ return $2
+ }
+ if {[argisnull 2]} { return $1 }
+ if {$1 &gt; $2} {return $1}
+ return $2
+$$ LANGUAGE pltcl;
+</pre><p>
+ </p><p>
+ As shown above,
+ to return a null value from a PL/Tcl function, execute
+ <code class="literal">return_null</code>. This can be done whether the
+ function is strict or not.
+ </p><p>
+ Composite-type arguments are passed to the function as Tcl
+ arrays. The element names of the array are the attribute names
+ of the composite type. If an attribute in the passed row has the
+ null value, it will not appear in the array. Here is an example:
+
+</p><pre class="programlisting">
+CREATE TABLE employee (
+ name text,
+ salary integer,
+ age integer
+);
+
+CREATE FUNCTION overpaid(employee) RETURNS boolean AS $$
+ if {200000.0 &lt; $1(salary)} {
+ return "t"
+ }
+ if {$1(age) &lt; 30 &amp;&amp; 100000.0 &lt; $1(salary)} {
+ return "t"
+ }
+ return "f"
+$$ LANGUAGE pltcl;
+</pre><p>
+ </p><p>
+ PL/Tcl functions can return composite-type results, too. To do this,
+ the Tcl code must return a list of column name/value pairs matching
+ the expected result type. Any column names omitted from the list
+ are returned as nulls, and an error is raised if there are unexpected
+ column names. Here is an example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION square_cube(in int, out squared int, out cubed int) AS $$
+ return [list squared [expr {$1 * $1}] cubed [expr {$1 * $1 * $1}]]
+$$ LANGUAGE pltcl;
+</pre><p>
+ </p><p>
+ Output arguments of procedures are returned in the same way, for example:
+
+</p><pre class="programlisting">
+CREATE PROCEDURE tcl_triple(INOUT a integer, INOUT b integer) AS $$
+ return [list a [expr {$1 * 3}] b [expr {$2 * 3}]]
+$$ LANGUAGE pltcl;
+
+CALL tcl_triple(5, 10);
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The result list can be made from an array representation of the
+ desired tuple with the <code class="literal">array get</code> Tcl command. For example:
+
+</p><pre class="programlisting">
+CREATE FUNCTION raise_pay(employee, delta int) RETURNS employee AS $$
+ set 1(salary) [expr {$1(salary) + $2}]
+ return [array get 1]
+$$ LANGUAGE pltcl;
+</pre><p>
+ </p></div><p>
+ PL/Tcl functions can return sets. To do this, the Tcl code should
+ call <code class="function">return_next</code> once per row to be returned,
+ passing either the appropriate value when returning a scalar type,
+ or a list of column name/value pairs when returning a composite type.
+ Here is an example returning a scalar type:
+
+</p><pre class="programlisting">
+CREATE FUNCTION sequence(int, int) RETURNS SETOF int AS $$
+ for {set i $1} {$i &lt; $2} {incr i} {
+ return_next $i
+ }
+$$ LANGUAGE pltcl;
+</pre><p>
+
+ and here is one returning a composite type:
+
+</p><pre class="programlisting">
+CREATE FUNCTION table_of_squares(int, int) RETURNS TABLE (x int, x2 int) AS $$
+ for {set i $1} {$i &lt; $2} {incr i} {
+ return_next [list x $i x2 [expr {$i * $i}]]
+ }
+$$ LANGUAGE pltcl;
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-overview.html" title="44.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.3. Data Values in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-global.html b/doc/src/sgml/html/pltcl-global.html
new file mode 100644
index 0000000..8a08a31
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-global.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.4. Global Data in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl" /><link rel="next" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.4. Global Data in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-GLOBAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.4. Global Data in PL/Tcl</h2></div></div></div><a id="id-1.8.9.8.2" class="indexterm"></a><p>
+ Sometimes it
+ is useful to have some global data that is held between two
+ calls to a function or is shared between different functions.
+ This is easily done in PL/Tcl, but there are some restrictions that
+ must be understood.
+ </p><p>
+ For security reasons, PL/Tcl executes functions called by any one SQL
+ role in a separate Tcl interpreter for that role. This prevents
+ accidental or malicious interference by one user with the behavior of
+ another user's PL/Tcl functions. Each such interpreter will have its own
+ values for any <span class="quote">“<span class="quote">global</span>”</span> Tcl variables. Thus, two PL/Tcl
+ functions will share the same global variables if and only if they are
+ executed by the same SQL role. In an application wherein a single
+ session executes code under multiple SQL roles (via <code class="literal">SECURITY
+ DEFINER</code> functions, use of <code class="command">SET ROLE</code>, etc.) you may need to
+ take explicit steps to ensure that PL/Tcl functions can share data. To
+ do that, make sure that functions that should communicate are owned by
+ the same user, and mark them <code class="literal">SECURITY DEFINER</code>. You must of
+ course take care that such functions can't be used to do anything
+ unintended.
+ </p><p>
+ All PL/TclU functions used in a session execute in the same Tcl
+ interpreter, which of course is distinct from the interpreter(s)
+ used for PL/Tcl functions. So global data is automatically shared
+ between PL/TclU functions. This is not considered a security risk
+ because all PL/TclU functions execute at the same trust level,
+ namely that of a database superuser.
+ </p><p>
+ To help protect PL/Tcl functions from unintentionally interfering
+ with each other, a global
+ array is made available to each function via the <code class="function">upvar</code>
+ command. The global name of this variable is the function's internal
+ name, and the local name is <code class="literal">GD</code>. It is recommended that
+ <code class="literal">GD</code> be used
+ for persistent private data of a function. Use regular Tcl global
+ variables only for values that you specifically intend to be shared among
+ multiple functions. (Note that the <code class="literal">GD</code> arrays are only
+ global within a particular interpreter, so they do not bypass the
+ security restrictions mentioned above.)
+ </p><p>
+ An example of using <code class="literal">GD</code> appears in the
+ <code class="function">spi_execp</code> example below.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-data.html" title="44.3. Data Values in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.3. Data Values in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.5. Database Access from PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-overview.html b/doc/src/sgml/html/pltcl-overview.html
new file mode 100644
index 0000000..0815851
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-overview.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language" /><link rel="next" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.1. Overview</h2></div></div></div><p>
+ PL/Tcl offers most of the capabilities a function writer has in
+ the C language, with a few restrictions, and with the addition of
+ the powerful string processing libraries that are available for
+ Tcl.
+ </p><p>
+ One compelling <span class="emphasis"><em>good</em></span> restriction is that
+ everything is executed from within the safety of the context of a
+ Tcl interpreter. In addition to the limited command set of safe
+ Tcl, only a few commands are available to access the database via
+ SPI and to raise messages via <code class="function">elog()</code>. PL/Tcl
+ provides no way to access internals of the database server or to
+ gain OS-level access under the permissions of the
+ <span class="productname">PostgreSQL</span> server process, as a C
+ function can do. Thus, unprivileged database users can be trusted
+ to use this language; it does not give them unlimited authority.
+ </p><p>
+ The other notable implementation restriction is that Tcl functions
+ cannot be used to create input/output functions for new data
+ types.
+ </p><p>
+ Sometimes it is desirable to write Tcl functions that are not restricted
+ to safe Tcl. For example, one might want a Tcl function that sends
+ email. To handle these cases, there is a variant of <span class="application">PL/Tcl</span> called <code class="literal">PL/TclU</code>
+ (for untrusted Tcl). This is exactly the same language except that a full
+ Tcl interpreter is used. <span class="emphasis"><em>If <span class="application">PL/TclU</span> is used, it must be
+ installed as an untrusted procedural language</em></span> so that only
+ database superusers can create functions in it. The writer of a <span class="application">PL/TclU</span>
+ function must take care that the function cannot be used to do anything
+ unwanted, since it will be able to do anything that could be done by
+ a user logged in as the database administrator.
+ </p><p>
+ The shared object code for the <span class="application">PL/Tcl</span> and
+ <span class="application">PL/TclU</span> call handlers is automatically built and
+ installed in the <span class="productname">PostgreSQL</span> library
+ directory if Tcl support is specified in the configuration step of
+ the installation procedure. To install <span class="application">PL/Tcl</span>
+ and/or <span class="application">PL/TclU</span> in a particular database, use the
+ <code class="command">CREATE EXTENSION</code> command, for example
+ <code class="literal">CREATE EXTENSION pltcl</code> or
+ <code class="literal">CREATE EXTENSION pltclu</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-functions.html" title="44.2. PL/Tcl Functions and Arguments">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 44. PL/Tcl — Tcl Procedural Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.2. PL/Tcl Functions and Arguments</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-procnames.html b/doc/src/sgml/html/pltcl-procnames.html
new file mode 100644
index 0000000..c39d052
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-procnames.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.12. Tcl Procedure Names</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-config.html" title="44.11. PL/Tcl Configuration" /><link rel="next" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.12. Tcl Procedure Names</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-config.html" title="44.11. PL/Tcl Configuration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-PROCNAMES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.12. Tcl Procedure Names</h2></div></div></div><p>
+ In <span class="productname">PostgreSQL</span>, the same function name can be used for
+ different function definitions as long as the number of arguments or their types
+ differ. Tcl, however, requires all procedure names to be distinct.
+ PL/Tcl deals with this by making the internal Tcl procedure names contain
+ the object
+ ID of the function from the system table <code class="structname">pg_proc</code> as part of their name. Thus,
+ <span class="productname">PostgreSQL</span> functions with the same name
+ and different argument types will be different Tcl procedures, too. This
+ is not normally a concern for a PL/Tcl programmer, but it might be visible
+ when debugging.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-config.html" title="44.11. PL/Tcl Configuration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.11. PL/Tcl Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 45. PL/Perl — Perl Procedural Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-subtransactions.html b/doc/src/sgml/html/pltcl-subtransactions.html
new file mode 100644
index 0000000..f2b9db1
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-subtransactions.html
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.9. Explicit Subtransactions in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl" /><link rel="next" href="pltcl-transactions.html" title="44.10. Transaction Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.9. Explicit Subtransactions in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-transactions.html" title="44.10. Transaction Management">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-SUBTRANSACTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.9. Explicit Subtransactions in PL/Tcl</h2></div></div></div><a id="id-1.8.9.13.2" class="indexterm"></a><p>
+ Recovering from errors caused by database access as described in
+ <a class="xref" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Section 44.8</a> can lead to an undesirable
+ situation where some operations succeed before one of them fails,
+ and after recovering from that error the data is left in an
+ inconsistent state. PL/Tcl offers a solution to this problem in
+ the form of explicit subtransactions.
+ </p><p>
+ Consider a function that implements a transfer between two accounts:
+</p><pre class="programlisting">
+CREATE FUNCTION transfer_funds() RETURNS void AS $$
+ if [catch {
+ spi_exec "UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'"
+ spi_exec "UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'"
+ } errormsg] {
+ set result [format "error transferring funds: %s" $errormsg]
+ } else {
+ set result "funds transferred successfully"
+ }
+ spi_exec "INSERT INTO operations (result) VALUES ('[quote $result]')"
+$$ LANGUAGE pltcl;
+</pre><p>
+ If the second <code class="command">UPDATE</code> statement results in an
+ exception being raised, this function will log the failure, but
+ the result of the first <code class="command">UPDATE</code> will
+ nevertheless be committed. In other words, the funds will be
+ withdrawn from Joe's account, but will not be transferred to
+ Mary's account. This happens because each <code class="function">spi_exec</code>
+ is a separate subtransaction, and only one of those subtransactions
+ got rolled back.
+ </p><p>
+ To handle such cases, you can wrap multiple database operations in an
+ explicit subtransaction, which will succeed or roll back as a whole.
+ PL/Tcl provides a <code class="function">subtransaction</code> command to manage
+ this. We can rewrite our function as:
+</p><pre class="programlisting">
+CREATE FUNCTION transfer_funds2() RETURNS void AS $$
+ if [catch {
+ subtransaction {
+ spi_exec "UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'"
+ spi_exec "UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'"
+ }
+ } errormsg] {
+ set result [format "error transferring funds: %s" $errormsg]
+ } else {
+ set result "funds transferred successfully"
+ }
+ spi_exec "INSERT INTO operations (result) VALUES ('[quote $result]')"
+$$ LANGUAGE pltcl;
+</pre><p>
+ Note that use of <code class="function">catch</code> is still required for this
+ purpose. Otherwise the error would propagate to the top level of the
+ function, preventing the desired insertion into
+ the <code class="structname">operations</code> table.
+ The <code class="function">subtransaction</code> command does not trap errors, it
+ only assures that all database operations executed inside its scope will
+ be rolled back together when an error is reported.
+ </p><p>
+ A rollback of an explicit subtransaction occurs on any error reported
+ by the contained Tcl code, not only errors originating from database
+ access. Thus a regular Tcl exception raised inside
+ a <code class="function">subtransaction</code> command will also cause the
+ subtransaction to be rolled back. However, non-error exits out of the
+ contained Tcl code (for instance, due to <code class="function">return</code>) do
+ not cause a rollback.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-error-handling.html" title="44.8. Error Handling in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-transactions.html" title="44.10. Transaction Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.8. Error Handling in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.10. Transaction Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-transactions.html b/doc/src/sgml/html/pltcl-transactions.html
new file mode 100644
index 0000000..7be56f6
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-transactions.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.10. Transaction Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl" /><link rel="next" href="pltcl-config.html" title="44.11. PL/Tcl Configuration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.10. Transaction Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-config.html" title="44.11. PL/Tcl Configuration">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-TRANSACTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.10. Transaction Management</h2></div></div></div><p>
+ In a procedure called from the top level or an anonymous code block
+ (<code class="command">DO</code> command) called from the top level it is possible
+ to control transactions. To commit the current transaction, call the
+ <code class="literal">commit</code> command. To roll back the current transaction,
+ call the <code class="literal">rollback</code> command. (Note that it is not
+ possible to run the SQL commands <code class="command">COMMIT</code> or
+ <code class="command">ROLLBACK</code> via <code class="function">spi_exec</code> or similar.
+ It has to be done using these functions.) After a transaction is ended,
+ a new transaction is automatically started, so there is no separate
+ command for that.
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+CREATE PROCEDURE transaction_test1()
+LANGUAGE pltcl
+AS $$
+for {set i 0} {$i &lt; 10} {incr i} {
+ spi_exec "INSERT INTO test1 (a) VALUES ($i)"
+ if {$i % 2 == 0} {
+ commit
+ } else {
+ rollback
+ }
+}
+$$;
+
+CALL transaction_test1();
+</pre><p>
+ </p><p>
+ Transactions cannot be ended when an explicit subtransaction is active.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-subtransactions.html" title="44.9. Explicit Subtransactions in PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-config.html" title="44.11. PL/Tcl Configuration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.9. Explicit Subtransactions in PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.11. PL/Tcl Configuration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl-trigger.html b/doc/src/sgml/html/pltcl-trigger.html
new file mode 100644
index 0000000..2845a81
--- /dev/null
+++ b/doc/src/sgml/html/pltcl-trigger.html
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>44.6. Trigger Functions in PL/Tcl</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl" /><link rel="next" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">44.6. Trigger Functions in PL/Tcl</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><th width="60%" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLTCL-TRIGGER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">44.6. Trigger Functions in PL/Tcl</h2></div></div></div><a id="id-1.8.9.10.2" class="indexterm"></a><p>
+ Trigger functions can be written in PL/Tcl.
+ <span class="productname">PostgreSQL</span> requires that a function that is to be called
+ as a trigger must be declared as a function with no arguments
+ and a return type of <code class="literal">trigger</code>.
+ </p><p>
+ The information from the trigger manager is passed to the function body
+ in the following variables:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">$TG_name</code></span></dt><dd><p>
+ The name of the trigger from the <code class="command">CREATE TRIGGER</code> statement.
+ </p></dd><dt><span class="term"><code class="varname">$TG_relid</code></span></dt><dd><p>
+ The object ID of the table that caused the trigger function
+ to be invoked.
+ </p></dd><dt><span class="term"><code class="varname">$TG_table_name</code></span></dt><dd><p>
+ The name of the table that caused the trigger function
+ to be invoked.
+ </p></dd><dt><span class="term"><code class="varname">$TG_table_schema</code></span></dt><dd><p>
+ The schema of the table that caused the trigger function
+ to be invoked.
+ </p></dd><dt><span class="term"><code class="varname">$TG_relatts</code></span></dt><dd><p>
+ A Tcl list of the table column names, prefixed with an empty list
+ element. So looking up a column name in the list with <span class="application">Tcl</span>'s
+ <code class="function">lsearch</code> command returns the element's number starting
+ with 1 for the first column, the same way the columns are customarily
+ numbered in <span class="productname">PostgreSQL</span>. (Empty list
+ elements also appear in the positions of columns that have been
+ dropped, so that the attribute numbering is correct for columns
+ to their right.)
+ </p></dd><dt><span class="term"><code class="varname">$TG_when</code></span></dt><dd><p>
+ The string <code class="literal">BEFORE</code>, <code class="literal">AFTER</code>, or
+ <code class="literal">INSTEAD OF</code>, depending on the type of trigger event.
+ </p></dd><dt><span class="term"><code class="varname">$TG_level</code></span></dt><dd><p>
+ The string <code class="literal">ROW</code> or <code class="literal">STATEMENT</code> depending on the
+ type of trigger event.
+ </p></dd><dt><span class="term"><code class="varname">$TG_op</code></span></dt><dd><p>
+ The string <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code> depending on the type of
+ trigger event.
+ </p></dd><dt><span class="term"><code class="varname">$NEW</code></span></dt><dd><p>
+ An associative array containing the values of the new table
+ row for <code class="command">INSERT</code> or <code class="command">UPDATE</code> actions, or
+ empty for <code class="command">DELETE</code>. The array is indexed by column
+ name. Columns that are null will not appear in the array.
+ This is not set for statement-level triggers.
+ </p></dd><dt><span class="term"><code class="varname">$OLD</code></span></dt><dd><p>
+ An associative array containing the values of the old table
+ row for <code class="command">UPDATE</code> or <code class="command">DELETE</code> actions, or
+ empty for <code class="command">INSERT</code>. The array is indexed by column
+ name. Columns that are null will not appear in the array.
+ This is not set for statement-level triggers.
+ </p></dd><dt><span class="term"><code class="varname">$args</code></span></dt><dd><p>
+ A Tcl list of the arguments to the function as given in the
+ <code class="command">CREATE TRIGGER</code> statement. These arguments are also accessible as
+ <code class="literal">$1</code> ... <code class="literal">$<em class="replaceable"><code>n</code></em></code> in the function body.
+ </p></dd></dl></div><p>
+ </p><p>
+ The return value from a trigger function can be one of the strings
+ <code class="literal">OK</code> or <code class="literal">SKIP</code>, or a list of column name/value pairs.
+ If the return value is <code class="literal">OK</code>,
+ the operation (<code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>)
+ that fired the trigger will proceed
+ normally. <code class="literal">SKIP</code> tells the trigger manager to silently suppress
+ the operation for this row. If a list is returned, it tells PL/Tcl to
+ return a modified row to the trigger manager; the contents of the
+ modified row are specified by the column names and values in the list.
+ Any columns not mentioned in the list are set to null.
+ Returning a modified row is only meaningful
+ for row-level <code class="literal">BEFORE</code> <code class="command">INSERT</code> or <code class="command">UPDATE</code>
+ triggers, for which the modified row will be inserted instead of the one
+ given in <code class="varname">$NEW</code>; or for row-level <code class="literal">INSTEAD OF</code>
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code> triggers where the returned row
+ is used as the source data for <code class="command">INSERT RETURNING</code> or
+ <code class="command">UPDATE RETURNING</code> clauses.
+ In row-level <code class="literal">BEFORE</code> <code class="command">DELETE</code> or <code class="literal">INSTEAD
+ OF</code> <code class="command">DELETE</code> triggers, returning a modified row has the same
+ effect as returning <code class="literal">OK</code>, that is the operation proceeds.
+ The trigger return value is ignored for all other types of triggers.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The result list can be made from an array representation of the
+ modified tuple with the <code class="literal">array get</code> Tcl command.
+ </p></div><p>
+ Here's a little example trigger function that forces an integer value
+ in a table to keep track of the number of updates that are performed on the
+ row. For new rows inserted, the value is initialized to 0 and then
+ incremented on every update operation.
+
+</p><pre class="programlisting">
+CREATE FUNCTION trigfunc_modcount() RETURNS trigger AS $$
+ switch $TG_op {
+ INSERT {
+ set NEW($1) 0
+ }
+ UPDATE {
+ set NEW($1) $OLD($1)
+ incr NEW($1)
+ }
+ default {
+ return OK
+ }
+ }
+ return [array get NEW]
+$$ LANGUAGE pltcl;
+
+CREATE TABLE mytab (num integer, description text, modcnt integer);
+
+CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
+ FOR EACH ROW EXECUTE FUNCTION trigfunc_modcount('modcnt');
+</pre><p>
+
+ Notice that the trigger function itself does not know the column
+ name; that's supplied from the trigger arguments. This lets the
+ trigger function be reused with different tables.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pltcl-dbaccess.html" title="44.5. Database Access from PL/Tcl">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-event-trigger.html" title="44.7. Event Trigger Functions in PL/Tcl">Next</a></td></tr><tr><td width="40%" align="left" valign="top">44.5. Database Access from PL/Tcl </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.7. Event Trigger Functions in PL/Tcl</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/pltcl.html b/doc/src/sgml/html/pltcl.html
new file mode 100644
index 0000000..53af887
--- /dev/null
+++ b/doc/src/sgml/html/pltcl.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 44. PL/Tcl — Tcl Procedural Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL" /><link rel="next" href="pltcl-overview.html" title="44.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 44. PL/Tcl — Tcl Procedural Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pltcl-overview.html" title="44.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLTCL"><div class="titlepage"><div><div><h2 class="title">Chapter 44. PL/Tcl — Tcl Procedural Language</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="pltcl-overview.html">44.1. Overview</a></span></dt><dt><span class="sect1"><a href="pltcl-functions.html">44.2. PL/Tcl Functions and Arguments</a></span></dt><dt><span class="sect1"><a href="pltcl-data.html">44.3. Data Values in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-global.html">44.4. Global Data in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-dbaccess.html">44.5. Database Access from PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-trigger.html">44.6. Trigger Functions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-event-trigger.html">44.7. Event Trigger Functions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-error-handling.html">44.8. Error Handling in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-subtransactions.html">44.9. Explicit Subtransactions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-transactions.html">44.10. Transaction Management</a></span></dt><dt><span class="sect1"><a href="pltcl-config.html">44.11. PL/Tcl Configuration</a></span></dt><dt><span class="sect1"><a href="pltcl-procnames.html">44.12. Tcl Procedure Names</a></span></dt></dl></div><a id="id-1.8.9.2" class="indexterm"></a><a id="id-1.8.9.3" class="indexterm"></a><p>
+ PL/Tcl is a loadable procedural language for the
+ <span class="productname">PostgreSQL</span> database system
+ that enables the <a class="ulink" href="https://www.tcl.tk/" target="_top">
+ Tcl language</a> to be used to write
+ <span class="productname">PostgreSQL</span> functions and procedures.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-porting.html" title="43.13. Porting from Oracle PL/SQL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pltcl-overview.html" title="44.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">43.13. Porting from <span class="productname">Oracle</span> PL/SQL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 44.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/populate.html b/doc/src/sgml/html/populate.html
new file mode 100644
index 0000000..35c379d
--- /dev/null
+++ b/doc/src/sgml/html/populate.html
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>14.4. Populating a Database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses" /><link rel="next" href="non-durability.html" title="14.5. Non-Durable Settings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">14.4. Populating a Database</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><th width="60%" align="center">Chapter 14. Performance Tips</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="non-durability.html" title="14.5. Non-Durable Settings">Next</a></td></tr></table><hr /></div><div class="sect1" id="POPULATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">14.4. Populating a Database</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="populate.html#DISABLE-AUTOCOMMIT">14.4.1. Disable Autocommit</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-COPY-FROM">14.4.2. Use <code class="command">COPY</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-RM-INDEXES">14.4.3. Remove Indexes</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-RM-FKEYS">14.4.4. Remove Foreign Key Constraints</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-WORK-MEM">14.4.5. Increase <code class="varname">maintenance_work_mem</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-MAX-WAL-SIZE">14.4.6. Increase <code class="varname">max_wal_size</code></a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-PITR">14.4.7. Disable WAL Archival and Streaming Replication</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-ANALYZE">14.4.8. Run <code class="command">ANALYZE</code> Afterwards</a></span></dt><dt><span class="sect2"><a href="populate.html#POPULATE-PG-DUMP">14.4.9. Some Notes about <span class="application">pg_dump</span></a></span></dt></dl></div><p>
+ One might need to insert a large amount of data when first populating
+ a database. This section contains some suggestions on how to make
+ this process as efficient as possible.
+ </p><div class="sect2" id="DISABLE-AUTOCOMMIT"><div class="titlepage"><div><div><h3 class="title">14.4.1. Disable Autocommit</h3></div></div></div><a id="id-1.5.13.7.3.2" class="indexterm"></a><p>
+ When using multiple <code class="command">INSERT</code>s, turn off autocommit and just do
+ one commit at the end. (In plain
+ SQL, this means issuing <code class="command">BEGIN</code> at the start and
+ <code class="command">COMMIT</code> at the end. Some client libraries might
+ do this behind your back, in which case you need to make sure the
+ library does it when you want it done.) If you allow each
+ insertion to be committed separately,
+ <span class="productname">PostgreSQL</span> is doing a lot of work for
+ each row that is added. An additional benefit of doing all
+ insertions in one transaction is that if the insertion of one row
+ were to fail then the insertion of all rows inserted up to that
+ point would be rolled back, so you won't be stuck with partially
+ loaded data.
+ </p></div><div class="sect2" id="POPULATE-COPY-FROM"><div class="titlepage"><div><div><h3 class="title">14.4.2. Use <code class="command">COPY</code></h3></div></div></div><p>
+ Use <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a> to load
+ all the rows in one command, instead of using a series of
+ <code class="command">INSERT</code> commands. The <code class="command">COPY</code>
+ command is optimized for loading large numbers of rows; it is less
+ flexible than <code class="command">INSERT</code>, but incurs significantly
+ less overhead for large data loads. Since <code class="command">COPY</code>
+ is a single command, there is no need to disable autocommit if you
+ use this method to populate a table.
+ </p><p>
+ If you cannot use <code class="command">COPY</code>, it might help to use <a class="link" href="sql-prepare.html" title="PREPARE"><code class="command">PREPARE</code></a> to create a
+ prepared <code class="command">INSERT</code> statement, and then use
+ <code class="command">EXECUTE</code> as many times as required. This avoids
+ some of the overhead of repeatedly parsing and planning
+ <code class="command">INSERT</code>. Different interfaces provide this facility
+ in different ways; look for <span class="quote">“<span class="quote">prepared statements</span>”</span> in the interface
+ documentation.
+ </p><p>
+ Note that loading a large number of rows using
+ <code class="command">COPY</code> is almost always faster than using
+ <code class="command">INSERT</code>, even if <code class="command">PREPARE</code> is used and
+ multiple insertions are batched into a single transaction.
+ </p><p>
+ <code class="command">COPY</code> is fastest when used within the same
+ transaction as an earlier <code class="command">CREATE TABLE</code> or
+ <code class="command">TRUNCATE</code> command. In such cases no WAL
+ needs to be written, because in case of an error, the files
+ containing the newly loaded data will be removed anyway.
+ However, this consideration only applies when
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> is <code class="literal">minimal</code>
+ as all commands must write WAL otherwise.
+ </p></div><div class="sect2" id="POPULATE-RM-INDEXES"><div class="titlepage"><div><div><h3 class="title">14.4.3. Remove Indexes</h3></div></div></div><p>
+ If you are loading a freshly created table, the fastest method is to
+ create the table, bulk load the table's data using
+ <code class="command">COPY</code>, then create any indexes needed for the
+ table. Creating an index on pre-existing data is quicker than
+ updating it incrementally as each row is loaded.
+ </p><p>
+ If you are adding large amounts of data to an existing table,
+ it might be a win to drop the indexes,
+ load the table, and then recreate the indexes. Of course, the
+ database performance for other users might suffer
+ during the time the indexes are missing. One should also think
+ twice before dropping a unique index, since the error checking
+ afforded by the unique constraint will be lost while the index is
+ missing.
+ </p></div><div class="sect2" id="POPULATE-RM-FKEYS"><div class="titlepage"><div><div><h3 class="title">14.4.4. Remove Foreign Key Constraints</h3></div></div></div><p>
+ Just as with indexes, a foreign key constraint can be checked
+ <span class="quote">“<span class="quote">in bulk</span>”</span> more efficiently than row-by-row. So it might be
+ useful to drop foreign key constraints, load data, and re-create
+ the constraints. Again, there is a trade-off between data load
+ speed and loss of error checking while the constraint is missing.
+ </p><p>
+ What's more, when you load data into a table with existing foreign key
+ constraints, each new row requires an entry in the server's list of
+ pending trigger events (since it is the firing of a trigger that checks
+ the row's foreign key constraint). Loading many millions of rows can
+ cause the trigger event queue to overflow available memory, leading to
+ intolerable swapping or even outright failure of the command. Therefore
+ it may be <span class="emphasis"><em>necessary</em></span>, not just desirable, to drop and re-apply
+ foreign keys when loading large amounts of data. If temporarily removing
+ the constraint isn't acceptable, the only other recourse may be to split
+ up the load operation into smaller transactions.
+ </p></div><div class="sect2" id="POPULATE-WORK-MEM"><div class="titlepage"><div><div><h3 class="title">14.4.5. Increase <code class="varname">maintenance_work_mem</code></h3></div></div></div><p>
+ Temporarily increasing the <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a>
+ configuration variable when loading large amounts of data can
+ lead to improved performance. This will help to speed up <code class="command">CREATE
+ INDEX</code> commands and <code class="command">ALTER TABLE ADD FOREIGN KEY</code> commands.
+ It won't do much for <code class="command">COPY</code> itself, so this advice is
+ only useful when you are using one or both of the above techniques.
+ </p></div><div class="sect2" id="POPULATE-MAX-WAL-SIZE"><div class="titlepage"><div><div><h3 class="title">14.4.6. Increase <code class="varname">max_wal_size</code></h3></div></div></div><p>
+ Temporarily increasing the <a class="xref" href="runtime-config-wal.html#GUC-MAX-WAL-SIZE">max_wal_size</a>
+ configuration variable can also
+ make large data loads faster. This is because loading a large
+ amount of data into <span class="productname">PostgreSQL</span> will
+ cause checkpoints to occur more often than the normal checkpoint
+ frequency (specified by the <code class="varname">checkpoint_timeout</code>
+ configuration variable). Whenever a checkpoint occurs, all dirty
+ pages must be flushed to disk. By increasing
+ <code class="varname">max_wal_size</code> temporarily during bulk
+ data loads, the number of checkpoints that are required can be
+ reduced.
+ </p></div><div class="sect2" id="POPULATE-PITR"><div class="titlepage"><div><div><h3 class="title">14.4.7. Disable WAL Archival and Streaming Replication</h3></div></div></div><p>
+ When loading large amounts of data into an installation that uses
+ WAL archiving or streaming replication, it might be faster to take a
+ new base backup after the load has completed than to process a large
+ amount of incremental WAL data. To prevent incremental WAL logging
+ while loading, disable archiving and streaming replication, by setting
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> to <code class="literal">minimal</code>,
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a> to <code class="literal">off</code>, and
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> to zero.
+ But note that changing these settings requires a server restart,
+ and makes any base backups taken before unavailable for archive
+ recovery and standby server, which may lead to data loss.
+ </p><p>
+ Aside from avoiding the time for the archiver or WAL sender to process the
+ WAL data, doing this will actually make certain commands faster, because
+ they do not to write WAL at all if <code class="varname">wal_level</code>
+ is <code class="literal">minimal</code> and the current subtransaction (or top-level
+ transaction) created or truncated the table or index they change. (They
+ can guarantee crash safety more cheaply by doing
+ an <code class="function">fsync</code> at the end than by writing WAL.)
+ </p></div><div class="sect2" id="POPULATE-ANALYZE"><div class="titlepage"><div><div><h3 class="title">14.4.8. Run <code class="command">ANALYZE</code> Afterwards</h3></div></div></div><p>
+ Whenever you have significantly altered the distribution of data
+ within a table, running <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> is strongly recommended. This
+ includes bulk loading large amounts of data into the table. Running
+ <code class="command">ANALYZE</code> (or <code class="command">VACUUM ANALYZE</code>)
+ ensures that the planner has up-to-date statistics about the
+ table. With no statistics or obsolete statistics, the planner might
+ make poor decisions during query planning, leading to poor
+ performance on any tables with inaccurate or nonexistent
+ statistics. Note that if the autovacuum daemon is enabled, it might
+ run <code class="command">ANALYZE</code> automatically; see
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>
+ and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ </p></div><div class="sect2" id="POPULATE-PG-DUMP"><div class="titlepage"><div><div><h3 class="title">14.4.9. Some Notes about <span class="application">pg_dump</span></h3></div></div></div><p>
+ Dump scripts generated by <span class="application">pg_dump</span> automatically apply
+ several, but not all, of the above guidelines. To restore a
+ <span class="application">pg_dump</span> dump as quickly as possible, you need to
+ do a few extra things manually. (Note that these points apply while
+ <span class="emphasis"><em>restoring</em></span> a dump, not while <span class="emphasis"><em>creating</em></span> it.
+ The same points apply whether loading a text dump with
+ <span class="application">psql</span> or using <span class="application">pg_restore</span> to load
+ from a <span class="application">pg_dump</span> archive file.)
+ </p><p>
+ By default, <span class="application">pg_dump</span> uses <code class="command">COPY</code>, and when
+ it is generating a complete schema-and-data dump, it is careful to
+ load data before creating indexes and foreign keys. So in this case
+ several guidelines are handled automatically. What is left
+ for you to do is to:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Set appropriate (i.e., larger than normal) values for
+ <code class="varname">maintenance_work_mem</code> and
+ <code class="varname">max_wal_size</code>.
+ </p></li><li class="listitem"><p>
+ If using WAL archiving or streaming replication, consider disabling
+ them during the restore. To do that, set <code class="varname">archive_mode</code>
+ to <code class="literal">off</code>,
+ <code class="varname">wal_level</code> to <code class="literal">minimal</code>, and
+ <code class="varname">max_wal_senders</code> to zero before loading the dump.
+ Afterwards, set them back to the right values and take a fresh
+ base backup.
+ </p></li><li class="listitem"><p>
+ Experiment with the parallel dump and restore modes of both
+ <span class="application">pg_dump</span> and <span class="application">pg_restore</span> and find the
+ optimal number of concurrent jobs to use. Dumping and restoring in
+ parallel by means of the <code class="option">-j</code> option should give you a
+ significantly higher performance over the serial mode.
+ </p></li><li class="listitem"><p>
+ Consider whether the whole dump should be restored as a single
+ transaction. To do that, pass the <code class="option">-1</code> or
+ <code class="option">--single-transaction</code> command-line option to
+ <span class="application">psql</span> or <span class="application">pg_restore</span>. When using this
+ mode, even the smallest of errors will rollback the entire restore,
+ possibly discarding many hours of processing. Depending on how
+ interrelated the data is, that might seem preferable to manual cleanup,
+ or not. <code class="command">COPY</code> commands will run fastest if you use a single
+ transaction and have WAL archiving turned off.
+ </p></li><li class="listitem"><p>
+ If multiple CPUs are available in the database server, consider using
+ <span class="application">pg_restore</span>'s <code class="option">--jobs</code> option. This
+ allows concurrent data loading and index creation.
+ </p></li><li class="listitem"><p>
+ Run <code class="command">ANALYZE</code> afterwards.
+ </p></li></ul></div><p>
+ </p><p>
+ A data-only dump will still use <code class="command">COPY</code>, but it does not
+ drop or recreate indexes, and it does not normally touch foreign
+ keys.
+
+ <a href="#ftn.id-1.5.13.7.11.4.2" class="footnote"><sup class="footnote" id="id-1.5.13.7.11.4.2">[14]</sup></a>
+
+ So when loading a data-only dump, it is up to you to drop and recreate
+ indexes and foreign keys if you wish to use those techniques.
+ It's still useful to increase <code class="varname">max_wal_size</code>
+ while loading the data, but don't bother increasing
+ <code class="varname">maintenance_work_mem</code>; rather, you'd do that while
+ manually recreating indexes and foreign keys afterwards.
+ And don't forget to <code class="command">ANALYZE</code> when you're done; see
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="25.1.3. Updating Planner Statistics">Section 25.1.3</a>
+ and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ </p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.13.7.11.4.2" class="footnote"><p><a href="#id-1.5.13.7.11.4.2" class="para"><sup class="para">[14] </sup></a>
+ You can get the effect of disabling foreign keys by using
+ the <code class="option">--disable-triggers</code> option — but realize that
+ that eliminates, rather than just postpones, foreign key
+ validation, and so it is possible to insert bad data if you use it.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="non-durability.html" title="14.5. Non-Durable Settings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 14.5. Non-Durable Settings</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/postgres-fdw.html b/doc/src/sgml/html/postgres-fdw.html
new file mode 100644
index 0000000..7f7b197
--- /dev/null
+++ b/doc/src/sgml/html/postgres-fdw.html
@@ -0,0 +1,677 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.38. postgres_fdw</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgwalinspect.html" title="F.37. pg_walinspect" /><link rel="next" href="seg.html" title="F.39. seg" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.38. postgres_fdw</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgwalinspect.html" title="F.37. pg_walinspect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="seg.html" title="F.39. seg">Next</a></td></tr></table><hr /></div><div class="sect1" id="POSTGRES-FDW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.38. postgres_fdw</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.11">F.38.1. FDW Options of postgres_fdw</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.12">F.38.2. Functions</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.13">F.38.3. Connection Management</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.14">F.38.4. Transaction Management</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.15">F.38.5. Remote Query Optimization</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.16">F.38.6. Remote Query Execution Environment</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.17">F.38.7. Cross-Version Compatibility</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.18">F.38.8. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.19">F.38.9. Examples</a></span></dt><dt><span class="sect2"><a href="postgres-fdw.html#id-1.11.7.47.20">F.38.10. Author</a></span></dt></dl></div><a id="id-1.11.7.47.2" class="indexterm"></a><p>
+ The <code class="filename">postgres_fdw</code> module provides the foreign-data wrapper
+ <code class="literal">postgres_fdw</code>, which can be used to access data
+ stored in external <span class="productname">PostgreSQL</span> servers.
+ </p><p>
+ The functionality provided by this module overlaps substantially
+ with the functionality of the older <a class="xref" href="dblink.html" title="F.12. dblink">dblink</a> module.
+ But <code class="filename">postgres_fdw</code> provides more transparent and
+ standards-compliant syntax for accessing remote tables, and can give
+ better performance in many cases.
+ </p><p>
+ To prepare for remote access using <code class="filename">postgres_fdw</code>:
+ </p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>
+ Install the <code class="filename">postgres_fdw</code> extension using <a class="xref" href="sql-createextension.html" title="CREATE EXTENSION"><span class="refentrytitle">CREATE EXTENSION</span></a>.
+ </p></li><li class="listitem"><p>
+ Create a foreign server object, using <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>,
+ to represent each remote database you want to connect to.
+ Specify connection information, except <code class="literal">user</code> and
+ <code class="literal">password</code>, as options of the server object.
+ </p></li><li class="listitem"><p>
+ Create a user mapping, using <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>, for
+ each database user you want to allow to access each foreign server.
+ Specify the remote user name and password to use as
+ <code class="literal">user</code> and <code class="literal">password</code> options of the
+ user mapping.
+ </p></li><li class="listitem"><p>
+ Create a foreign table, using <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>
+ or <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a>,
+ for each remote table you want to access. The columns of the foreign
+ table must match the referenced remote table. You can, however, use
+ table and/or column names different from the remote table's, if you
+ specify the correct remote names as options of the foreign table object.
+ </p></li></ol></div><p>
+ </p><p>
+ Now you need only <code class="command">SELECT</code> from a foreign table to access
+ the data stored in its underlying remote table. You can also modify
+ the remote table using <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">COPY</code>, or
+ <code class="command">TRUNCATE</code>.
+ (Of course, the remote user you have specified in your user mapping must
+ have privileges to do these things.)
+ </p><p>
+ Note that the <code class="literal">ONLY</code> option specified in
+ <code class="command">SELECT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code> or <code class="command">TRUNCATE</code>
+ has no effect when accessing or modifying the remote table.
+ </p><p>
+ Note that <code class="filename">postgres_fdw</code> currently lacks support for
+ <code class="command">INSERT</code> statements with an <code class="literal">ON CONFLICT DO
+ UPDATE</code> clause. However, the <code class="literal">ON CONFLICT DO NOTHING</code>
+ clause is supported, provided a unique index inference specification
+ is omitted.
+ Note also that <code class="filename">postgres_fdw</code> supports row movement
+ invoked by <code class="command">UPDATE</code> statements executed on partitioned
+ tables, but it currently does not handle the case where a remote partition
+ chosen to insert a moved row into is also an <code class="command">UPDATE</code>
+ target partition that will be updated elsewhere in the same command.
+ </p><p>
+ It is generally recommended that the columns of a foreign table be declared
+ with exactly the same data types, and collations if applicable, as the
+ referenced columns of the remote table. Although <code class="filename">postgres_fdw</code>
+ is currently rather forgiving about performing data type conversions at
+ need, surprising semantic anomalies may arise when types or collations do
+ not match, due to the remote server interpreting query conditions
+ differently from the local server.
+ </p><p>
+ Note that a foreign table can be declared with fewer columns, or with a
+ different column order, than its underlying remote table has. Matching
+ of columns to the remote table is by name, not position.
+ </p><div class="sect2" id="id-1.11.7.47.11"><div class="titlepage"><div><div><h3 class="title">F.38.1. FDW Options of postgres_fdw</h3></div></div></div><div class="sect3" id="id-1.11.7.47.11.2"><div class="titlepage"><div><div><h4 class="title">F.38.1.1. Connection Options</h4></div></div></div><p>
+ A foreign server using the <code class="filename">postgres_fdw</code> foreign data wrapper
+ can have the same options that <span class="application">libpq</span> accepts in
+ connection strings, as described in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>,
+ except that these options are not allowed or have special handling:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">user</code>, <code class="literal">password</code> and <code class="literal">sslpassword</code> (specify these
+ in a user mapping, instead, or use a service file)
+ </p></li><li class="listitem"><p>
+ <code class="literal">client_encoding</code> (this is automatically set from the local
+ server encoding)
+ </p></li><li class="listitem"><p>
+ <code class="literal">application_name</code> - this may appear in
+ <span class="emphasis"><em>either or both</em></span> a connection and
+ <a class="xref" href="postgres-fdw.html#GUC-PGFDW-APPLICATION-NAME">postgres_fdw.application_name</a>.
+ If both are present, <code class="varname">postgres_fdw.application_name</code>
+ overrides the connection setting.
+ Unlike <span class="application">libpq</span>,
+ <code class="filename">postgres_fdw</code> allows
+ <code class="varname">application_name</code> to include
+ <span class="quote">“<span class="quote">escape sequences</span>”</span>.
+ See <a class="xref" href="postgres-fdw.html#GUC-PGFDW-APPLICATION-NAME">postgres_fdw.application_name</a> for details.
+ </p></li><li class="listitem"><p>
+ <code class="literal">fallback_application_name</code> (always set to
+ <code class="literal">postgres_fdw</code>)
+ </p></li><li class="listitem"><p>
+ <code class="literal">sslkey</code> and <code class="literal">sslcert</code> - these may
+ appear in <span class="emphasis"><em>either or both</em></span> a connection and a user
+ mapping. If both are present, the user mapping setting overrides the
+ connection setting.
+ </p></li></ul></div><p>
+ </p><p>
+ Only superusers may create or modify user mappings with the
+ <code class="literal">sslcert</code> or <code class="literal">sslkey</code> settings.
+ </p><p>
+ Only superusers may connect to foreign servers without password
+ authentication, so always specify the <code class="literal">password</code> option
+ for user mappings belonging to non-superusers.
+ </p><p>
+ A superuser may override this check on a per-user-mapping basis by setting
+ the user mapping option <code class="literal">password_required 'false'</code>, e.g.,
+</p><pre class="programlisting">
+ALTER USER MAPPING FOR some_non_superuser SERVER loopback_nopw
+OPTIONS (ADD password_required 'false');
+</pre><p>
+ To prevent unprivileged users from exploiting the authentication rights
+ of the unix user the postgres server is running as to escalate to superuser
+ rights, only the superuser may set this option on a user mapping.
+ </p><p>
+ Care is required to ensure that this does not allow the mapped
+ user the ability to connect as superuser to the mapped database per
+ CVE-2007-3278 and CVE-2007-6601. Don't set
+ <code class="literal">password_required=false</code>
+ on the <code class="literal">public</code> role. Keep in mind that the mapped
+ user can potentially use any client certificates,
+ <code class="filename">.pgpass</code>,
+ <code class="filename">.pg_service.conf</code> etc. in the unix home directory of the
+ system user the postgres server runs as. They can also use any trust
+ relationship granted by authentication modes like <code class="literal">peer</code>
+ or <code class="literal">ident</code> authentication.
+ </p></div><div class="sect3" id="id-1.11.7.47.11.3"><div class="titlepage"><div><div><h4 class="title">F.38.1.2. Object Name Options</h4></div></div></div><p>
+ These options can be used to control the names used in SQL statements
+ sent to the remote <span class="productname">PostgreSQL</span> server. These
+ options are needed when a foreign table is created with names different
+ from the underlying remote table's names.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">schema_name</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This option, which can be specified for a foreign table, gives the
+ schema name to use for the foreign table on the remote server. If this
+ option is omitted, the name of the foreign table's schema is used.
+ </p></dd><dt><span class="term"><code class="literal">table_name</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This option, which can be specified for a foreign table, gives the
+ table name to use for the foreign table on the remote server. If this
+ option is omitted, the foreign table's name is used.
+ </p></dd><dt><span class="term"><code class="literal">column_name</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This option, which can be specified for a column of a foreign table,
+ gives the column name to use for the column on the remote server.
+ If this option is omitted, the column's name is used.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.4"><div class="titlepage"><div><div><h4 class="title">F.38.1.3. Cost Estimation Options</h4></div></div></div><p>
+ <code class="filename">postgres_fdw</code> retrieves remote data by executing queries
+ against remote servers, so ideally the estimated cost of scanning a
+ foreign table should be whatever it costs to be done on the remote
+ server, plus some overhead for communication. The most reliable way to
+ get such an estimate is to ask the remote server and then add something
+ for overhead — but for simple queries, it may not be worth the cost
+ of an additional remote query to get a cost estimate.
+ So <code class="filename">postgres_fdw</code> provides the following options to control
+ how cost estimation is done:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">use_remote_estimate</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option, which can be specified for a foreign table or a foreign
+ server, controls whether <code class="filename">postgres_fdw</code> issues remote
+ <code class="command">EXPLAIN</code> commands to obtain cost estimates.
+ A setting for a foreign table overrides any setting for its server,
+ but only for that table.
+ The default is <code class="literal">false</code>.
+ </p></dd><dt><span class="term"><code class="literal">fdw_startup_cost</code> (<code class="type">floating point</code>)</span></dt><dd><p>
+ This option, which can be specified for a foreign server, is a floating
+ point value that is added to the estimated startup cost of any
+ foreign-table scan on that server. This represents the additional
+ overhead of establishing a connection, parsing and planning the query on
+ the remote side, etc.
+ The default value is <code class="literal">100</code>.
+ </p></dd><dt><span class="term"><code class="literal">fdw_tuple_cost</code> (<code class="type">floating point</code>)</span></dt><dd><p>
+ This option, which can be specified for a foreign server, is a floating
+ point value that is used as extra cost per-tuple for foreign-table
+ scans on that server. This represents the additional overhead of
+ data transfer between servers. You might increase or decrease this
+ number to reflect higher or lower network delay to the remote server.
+ The default value is <code class="literal">0.01</code>.
+ </p></dd></dl></div><p>
+ When <code class="literal">use_remote_estimate</code> is true,
+ <code class="filename">postgres_fdw</code> obtains row count and cost estimates from the
+ remote server and then adds <code class="literal">fdw_startup_cost</code> and
+ <code class="literal">fdw_tuple_cost</code> to the cost estimates. When
+ <code class="literal">use_remote_estimate</code> is false,
+ <code class="filename">postgres_fdw</code> performs local row count and cost estimation
+ and then adds <code class="literal">fdw_startup_cost</code> and
+ <code class="literal">fdw_tuple_cost</code> to the cost estimates. This local
+ estimation is unlikely to be very accurate unless local copies of the
+ remote table's statistics are available. Running
+ <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a> on the foreign table is the way to update
+ the local statistics; this will perform a scan of the remote table and
+ then calculate and store statistics just as though the table were local.
+ Keeping local statistics can be a useful way to reduce per-query planning
+ overhead for a remote table — but if the remote table is
+ frequently updated, the local statistics will soon be obsolete.
+ </p></div><div class="sect3" id="id-1.11.7.47.11.5"><div class="titlepage"><div><div><h4 class="title">F.38.1.4. Remote Execution Options</h4></div></div></div><p>
+ By default, only <code class="literal">WHERE</code> clauses using built-in operators and
+ functions will be considered for execution on the remote server. Clauses
+ involving non-built-in functions are checked locally after rows are
+ fetched. If such functions are available on the remote server and can be
+ relied on to produce the same results as they do locally, performance can
+ be improved by sending such <code class="literal">WHERE</code> clauses for remote
+ execution. This behavior can be controlled using the following option:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">extensions</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This option is a comma-separated list of names
+ of <span class="productname">PostgreSQL</span> extensions that are installed, in
+ compatible versions, on both the local and remote servers. Functions
+ and operators that are immutable and belong to a listed extension will
+ be considered shippable to the remote server.
+ This option can only be specified for foreign servers, not per-table.
+ </p><p>
+ When using the <code class="literal">extensions</code> option, <span class="emphasis"><em>it is the
+ user's responsibility</em></span> that the listed extensions exist and behave
+ identically on both the local and remote servers. Otherwise, remote
+ queries may fail or behave unexpectedly.
+ </p></dd><dt><span class="term"><code class="literal">fetch_size</code> (<code class="type">integer</code>)</span></dt><dd><p>
+ This option specifies the number of rows <code class="filename">postgres_fdw</code>
+ should get in each fetch operation. It can be specified for a foreign
+ table or a foreign server. The option specified on a table overrides
+ an option specified for the server.
+ The default is <code class="literal">100</code>.
+ </p></dd><dt><span class="term"><code class="literal">batch_size</code> (<code class="type">integer</code>)</span></dt><dd><p>
+ This option specifies the number of rows <code class="filename">postgres_fdw</code>
+ should insert in each insert operation. It can be specified for a
+ foreign table or a foreign server. The option specified on a table
+ overrides an option specified for the server.
+ The default is <code class="literal">1</code>.
+ </p><p>
+ Note the actual number of rows <code class="filename">postgres_fdw</code> inserts at
+ once depends on the number of columns and the provided
+ <code class="literal">batch_size</code> value. The batch is executed as a single
+ query, and the libpq protocol (which <code class="filename">postgres_fdw</code>
+ uses to connect to a remote server) limits the number of parameters in a
+ single query to 65535. When the number of columns * <code class="literal">batch_size</code>
+ exceeds the limit, the <code class="literal">batch_size</code> will be adjusted to
+ avoid an error.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.6"><div class="titlepage"><div><div><h4 class="title">F.38.1.5. Asynchronous Execution Options</h4></div></div></div><p>
+ <code class="filename">postgres_fdw</code> supports asynchronous execution, which
+ runs multiple parts of an <code class="structname">Append</code> node
+ concurrently rather than serially to improve performance.
+ This execution can be controlled using the following option:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">async_capable</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether <code class="filename">postgres_fdw</code> allows
+ foreign tables to be scanned concurrently for asynchronous execution.
+ It can be specified for a foreign table or a foreign server.
+ A table-level option overrides a server-level option.
+ The default is <code class="literal">false</code>.
+ </p><p>
+ In order to ensure that the data being returned from a foreign server
+ is consistent, <code class="filename">postgres_fdw</code> will only open one
+ connection for a given foreign server and will run all queries against
+ that server sequentially even if there are multiple foreign tables
+ involved, unless those tables are subject to different user mappings.
+ In such a case, it may be more performant to disable this option to
+ eliminate the overhead associated with running queries asynchronously.
+ </p><p>
+ Asynchronous execution is applied even when an
+ <code class="structname">Append</code> node contains subplan(s) executed
+ synchronously as well as subplan(s) executed asynchronously.
+ In such a case, if the asynchronous subplans are ones processed using
+ <code class="filename">postgres_fdw</code>, tuples from the asynchronous
+ subplans are not returned until after at least one synchronous subplan
+ returns all tuples, as that subplan is executed while the asynchronous
+ subplans are waiting for the results of asynchronous queries sent to
+ foreign servers.
+ This behavior might change in a future release.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.7"><div class="titlepage"><div><div><h4 class="title">F.38.1.6. Transaction Management Options</h4></div></div></div><p>
+ As described in the Transaction Management section, in
+ <code class="filename">postgres_fdw</code> transactions are managed by creating
+ corresponding remote transactions, and subtransactions are managed by
+ creating corresponding remote subtransactions. When multiple remote
+ transactions are involved in the current local transaction, by default
+ <code class="filename">postgres_fdw</code> commits those remote transactions
+ serially when the local transaction is committed. When multiple remote
+ subtransactions are involved in the current local subtransaction, by
+ default <code class="filename">postgres_fdw</code> commits those remote
+ subtransactions serially when the local subtransaction is committed.
+ Performance can be improved with the following option:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">parallel_commit</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether <code class="filename">postgres_fdw</code> commits
+ in parallel remote transactions opened on a foreign server in a local
+ transaction when the local transaction is committed. This setting also
+ applies to remote and local subtransactions. This option can only be
+ specified for foreign servers, not per-table. The default is
+ <code class="literal">false</code>.
+ </p><p>
+ If multiple foreign servers with this option enabled are involved in a
+ local transaction, multiple remote transactions on those foreign
+ servers are committed in parallel across those foreign servers when
+ the local transaction is committed.
+ </p><p>
+ When this option is enabled, a foreign server with many remote
+ transactions may see a negative performance impact when the local
+ transaction is committed.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.8"><div class="titlepage"><div><div><h4 class="title">F.38.1.7. Updatability Options</h4></div></div></div><p>
+ By default all foreign tables using <code class="filename">postgres_fdw</code> are assumed
+ to be updatable. This may be overridden using the following option:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">updatable</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether <code class="filename">postgres_fdw</code> allows foreign
+ tables to be modified using <code class="command">INSERT</code>, <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code> commands. It can be specified for a foreign table
+ or a foreign server. A table-level option overrides a server-level
+ option.
+ The default is <code class="literal">true</code>.
+ </p><p>
+ Of course, if the remote table is not in fact updatable, an error
+ would occur anyway. Use of this option primarily allows the error to
+ be thrown locally without querying the remote server. Note however
+ that the <code class="literal">information_schema</code> views will report a
+ <code class="filename">postgres_fdw</code> foreign table to be updatable (or not)
+ according to the setting of this option, without any check of the
+ remote server.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.9"><div class="titlepage"><div><div><h4 class="title">F.38.1.8. Truncatability Options</h4></div></div></div><p>
+ By default all foreign tables using <code class="filename">postgres_fdw</code> are assumed
+ to be truncatable. This may be overridden using the following option:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">truncatable</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether <code class="filename">postgres_fdw</code> allows
+ foreign tables to be truncated using the <code class="command">TRUNCATE</code>
+ command. It can be specified for a foreign table or a foreign server.
+ A table-level option overrides a server-level option.
+ The default is <code class="literal">true</code>.
+ </p><p>
+ Of course, if the remote table is not in fact truncatable, an error
+ would occur anyway. Use of this option primarily allows the error to
+ be thrown locally without querying the remote server.
+ </p></dd></dl></div></div><div class="sect3" id="id-1.11.7.47.11.10"><div class="titlepage"><div><div><h4 class="title">F.38.1.9. Importing Options</h4></div></div></div><p>
+ <code class="filename">postgres_fdw</code> is able to import foreign table definitions
+ using <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a>. This command creates
+ foreign table definitions on the local server that match tables or
+ views present on the remote server. If the remote tables to be imported
+ have columns of user-defined data types, the local server must have
+ compatible types of the same names.
+ </p><p>
+ Importing behavior can be customized with the following options
+ (given in the <code class="command">IMPORT FOREIGN SCHEMA</code> command):
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">import_collate</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether column <code class="literal">COLLATE</code> options
+ are included in the definitions of foreign tables imported
+ from a foreign server. The default is <code class="literal">true</code>. You might
+ need to turn this off if the remote server has a different set of
+ collation names than the local server does, which is likely to be the
+ case if it's running on a different operating system.
+ If you do so, however, there is a very severe risk that the imported
+ table columns' collations will not match the underlying data, resulting
+ in anomalous query behavior.
+ </p><p>
+ Even when this parameter is set to <code class="literal">true</code>, importing
+ columns whose collation is the remote server's default can be risky.
+ They will be imported with <code class="literal">COLLATE "default"</code>, which
+ will select the local server's default collation, which could be
+ different.
+ </p></dd><dt><span class="term"><code class="literal">import_default</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether column <code class="literal">DEFAULT</code> expressions
+ are included in the definitions of foreign tables imported
+ from a foreign server. The default is <code class="literal">false</code>. If you
+ enable this option, be wary of defaults that might get computed
+ differently on the local server than they would be on the remote
+ server; <code class="function">nextval()</code> is a common source of problems.
+ The <code class="command">IMPORT</code> will fail altogether if an imported default
+ expression uses a function or operator that does not exist locally.
+ </p></dd><dt><span class="term"><code class="literal">import_generated</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether column <code class="literal">GENERATED</code> expressions
+ are included in the definitions of foreign tables imported
+ from a foreign server. The default is <code class="literal">true</code>.
+ The <code class="command">IMPORT</code> will fail altogether if an imported generated
+ expression uses a function or operator that does not exist locally.
+ </p></dd><dt><span class="term"><code class="literal">import_not_null</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether column <code class="literal">NOT NULL</code>
+ constraints are included in the definitions of foreign tables imported
+ from a foreign server. The default is <code class="literal">true</code>.
+ </p></dd></dl></div><p>
+ Note that constraints other than <code class="literal">NOT NULL</code> will never be
+ imported from the remote tables. Although <span class="productname">PostgreSQL</span>
+ does support check constraints on foreign tables, there is no
+ provision for importing them automatically, because of the risk that a
+ constraint expression could evaluate differently on the local and remote
+ servers. Any such inconsistency in the behavior of a check
+ constraint could lead to hard-to-detect errors in query optimization.
+ So if you wish to import check constraints, you must do so
+ manually, and you should verify the semantics of each one carefully.
+ For more detail about the treatment of check constraints on
+ foreign tables, see <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>.
+ </p><p>
+ Tables or foreign tables which are partitions of some other table are
+ imported only when they are explicitly specified in
+ <code class="literal">LIMIT TO</code> clause. Otherwise they are automatically
+ excluded from <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a>.
+ Since all data can be accessed through the partitioned table
+ which is the root of the partitioning hierarchy, importing only
+ partitioned tables should allow access to all the data without
+ creating extra objects.
+ </p></div><div class="sect3" id="id-1.11.7.47.11.11"><div class="titlepage"><div><div><h4 class="title">F.38.1.10. Connection Management Options</h4></div></div></div><p>
+ By default, all connections that <code class="filename">postgres_fdw</code>
+ establishes to foreign servers are kept open in the local session
+ for re-use.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">keep_connections</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option controls whether <code class="filename">postgres_fdw</code> keeps
+ the connections to the foreign server open so that subsequent
+ queries can re-use them. It can only be specified for a foreign server.
+ The default is <code class="literal">on</code>. If set to <code class="literal">off</code>,
+ all connections to this foreign server will be discarded at the end of
+ each transaction.
+ </p></dd></dl></div></div></div><div class="sect2" id="id-1.11.7.47.12"><div class="titlepage"><div><div><h3 class="title">F.38.2. Functions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">postgres_fdw_get_connections(OUT server_name text, OUT valid boolean) returns setof record</code></span></dt><dd><p>
+ This function returns the foreign server names of all the open
+ connections that <code class="filename">postgres_fdw</code> established from
+ the local session to the foreign servers. It also returns whether
+ each connection is valid or not. <code class="literal">false</code> is returned
+ if the foreign server connection is used in the current local
+ transaction but its foreign server or user mapping is changed or
+ dropped (Note that server name of an invalid connection will be
+ <code class="literal">NULL</code> if the server is dropped),
+ and then such invalid connection will be closed at
+ the end of that transaction. <code class="literal">true</code> is returned
+ otherwise. If there are no open connections, no record is returned.
+ Example usage of the function:
+</p><pre class="screen">
+postgres=# SELECT * FROM postgres_fdw_get_connections() ORDER BY 1;
+ server_name | valid
+-------------+-------
+ loopback1 | t
+ loopback2 | f
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">postgres_fdw_disconnect(server_name text) returns boolean</code></span></dt><dd><p>
+ This function discards the open connections that are established by
+ <code class="filename">postgres_fdw</code> from the local session to
+ the foreign server with the given name. Note that there can be
+ multiple connections to the given server using different user mappings.
+ If the connections are used in the current local transaction,
+ they are not disconnected and warning messages are reported.
+ This function returns <code class="literal">true</code> if it disconnects
+ at least one connection, otherwise <code class="literal">false</code>.
+ If no foreign server with the given name is found, an error is reported.
+ Example usage of the function:
+</p><pre class="screen">
+postgres=# SELECT postgres_fdw_disconnect('loopback1');
+ postgres_fdw_disconnect
+-------------------------
+ t
+</pre><p>
+ </p></dd><dt><span class="term"><code class="function">postgres_fdw_disconnect_all() returns boolean</code></span></dt><dd><p>
+ This function discards all the open connections that are established by
+ <code class="filename">postgres_fdw</code> from the local session to
+ foreign servers. If the connections are used in the current local
+ transaction, they are not disconnected and warning messages are reported.
+ This function returns <code class="literal">true</code> if it disconnects
+ at least one connection, otherwise <code class="literal">false</code>.
+ Example usage of the function:
+</p><pre class="screen">
+postgres=# SELECT postgres_fdw_disconnect_all();
+ postgres_fdw_disconnect_all
+-----------------------------
+ t
+</pre><p>
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.47.13"><div class="titlepage"><div><div><h3 class="title">F.38.3. Connection Management</h3></div></div></div><p>
+ <code class="filename">postgres_fdw</code> establishes a connection to a
+ foreign server during the first query that uses a foreign table
+ associated with the foreign server. By default this connection
+ is kept and re-used for subsequent queries in the same session.
+ This behavior can be controlled using
+ <code class="literal">keep_connections</code> option for a foreign server. If
+ multiple user identities (user mappings) are used to access the foreign
+ server, a connection is established for each user mapping.
+ </p><p>
+ When changing the definition of or removing a foreign server or
+ a user mapping, the associated connections are closed.
+ But note that if any connections are in use in the current local transaction,
+ they are kept until the end of the transaction.
+ Closed connections will be re-established when they are necessary
+ by future queries using a foreign table.
+ </p><p>
+ Once a connection to a foreign server has been established,
+ it's by default kept until the local or corresponding remote
+ session exits. To disconnect a connection explicitly,
+ <code class="literal">keep_connections</code> option for a foreign server
+ may be disabled, or
+ <code class="function">postgres_fdw_disconnect</code> and
+ <code class="function">postgres_fdw_disconnect_all</code> functions
+ may be used. For example, these are useful to close
+ connections that are no longer necessary, thereby releasing
+ connections on the foreign server.
+ </p></div><div class="sect2" id="id-1.11.7.47.14"><div class="titlepage"><div><div><h3 class="title">F.38.4. Transaction Management</h3></div></div></div><p>
+ During a query that references any remote tables on a foreign server,
+ <code class="filename">postgres_fdw</code> opens a transaction on the
+ remote server if one is not already open corresponding to the current
+ local transaction. The remote transaction is committed or aborted when
+ the local transaction commits or aborts. Savepoints are similarly
+ managed by creating corresponding remote savepoints.
+ </p><p>
+ The remote transaction uses <code class="literal">SERIALIZABLE</code>
+ isolation level when the local transaction has <code class="literal">SERIALIZABLE</code>
+ isolation level; otherwise it uses <code class="literal">REPEATABLE READ</code>
+ isolation level. This choice ensures that if a query performs multiple
+ table scans on the remote server, it will get snapshot-consistent results
+ for all the scans. A consequence is that successive queries within a
+ single transaction will see the same data from the remote server, even if
+ concurrent updates are occurring on the remote server due to other
+ activities. That behavior would be expected anyway if the local
+ transaction uses <code class="literal">SERIALIZABLE</code> or <code class="literal">REPEATABLE READ</code>
+ isolation level, but it might be surprising for a <code class="literal">READ
+ COMMITTED</code> local transaction. A future
+ <span class="productname">PostgreSQL</span> release might modify these rules.
+ </p><p>
+ Note that it is currently not supported by
+ <code class="filename">postgres_fdw</code> to prepare the remote transaction for
+ two-phase commit.
+ </p></div><div class="sect2" id="id-1.11.7.47.15"><div class="titlepage"><div><div><h3 class="title">F.38.5. Remote Query Optimization</h3></div></div></div><p>
+ <code class="filename">postgres_fdw</code> attempts to optimize remote queries to reduce
+ the amount of data transferred from foreign servers. This is done by
+ sending query <code class="literal">WHERE</code> clauses to the remote server for
+ execution, and by not retrieving table columns that are not needed for
+ the current query. To reduce the risk of misexecution of queries,
+ <code class="literal">WHERE</code> clauses are not sent to the remote server unless they use
+ only data types, operators, and functions that are built-in or belong to an
+ extension that's listed in the foreign server's <code class="literal">extensions</code>
+ option. Operators and functions in such clauses must
+ be <code class="literal">IMMUTABLE</code> as well.
+ For an <code class="command">UPDATE</code> or <code class="command">DELETE</code> query,
+ <code class="filename">postgres_fdw</code> attempts to optimize the query execution by
+ sending the whole query to the remote server if there are no query
+ <code class="literal">WHERE</code> clauses that cannot be sent to the remote server,
+ no local joins for the query, no row-level local <code class="literal">BEFORE</code> or
+ <code class="literal">AFTER</code> triggers or stored generated columns on the target
+ table, and no <code class="literal">CHECK OPTION</code> constraints from parent
+ views. In <code class="command">UPDATE</code>,
+ expressions to assign to target columns must use only built-in data types,
+ <code class="literal">IMMUTABLE</code> operators, or <code class="literal">IMMUTABLE</code> functions,
+ to reduce the risk of misexecution of the query.
+ </p><p>
+ When <code class="filename">postgres_fdw</code> encounters a join between foreign tables on
+ the same foreign server, it sends the entire join to the foreign server,
+ unless for some reason it believes that it will be more efficient to fetch
+ rows from each table individually, or unless the table references involved
+ are subject to different user mappings. While sending the <code class="literal">JOIN</code>
+ clauses, it takes the same precautions as mentioned above for the
+ <code class="literal">WHERE</code> clauses.
+ </p><p>
+ The query that is actually sent to the remote server for execution can
+ be examined using <code class="command">EXPLAIN VERBOSE</code>.
+ </p></div><div class="sect2" id="id-1.11.7.47.16"><div class="titlepage"><div><div><h3 class="title">F.38.6. Remote Query Execution Environment</h3></div></div></div><p>
+ In the remote sessions opened by <code class="filename">postgres_fdw</code>,
+ the <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> parameter is set to
+ just <code class="literal">pg_catalog</code>, so that only built-in objects are visible
+ without schema qualification. This is not an issue for queries
+ generated by <code class="filename">postgres_fdw</code> itself, because it always
+ supplies such qualification. However, this can pose a hazard for
+ functions that are executed on the remote server via triggers or rules
+ on remote tables. For example, if a remote table is actually a view,
+ any functions used in that view will be executed with the restricted
+ search path. It is recommended to schema-qualify all names in such
+ functions, or else attach <code class="literal">SET search_path</code> options
+ (see <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>) to such functions
+ to establish their expected search path environment.
+ </p><p>
+ <code class="filename">postgres_fdw</code> likewise establishes remote session settings
+ for various parameters:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> is set to <code class="literal">UTC</code>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a> is set to <code class="literal">ISO</code>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="runtime-config-client.html#GUC-INTERVALSTYLE">IntervalStyle</a> is set to <code class="literal">postgres</code>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS">extra_float_digits</a> is set to <code class="literal">3</code> for remote
+ servers 9.0 and newer and is set to <code class="literal">2</code> for older versions
+ </p></li></ul></div><p>
+ These are less likely to be problematic than <code class="varname">search_path</code>, but
+ can be handled with function <code class="literal">SET</code> options if the need arises.
+ </p><p>
+ It is <span class="emphasis"><em>not</em></span> recommended that you override this behavior by
+ changing the session-level settings of these parameters; that is likely
+ to cause <code class="filename">postgres_fdw</code> to malfunction.
+ </p></div><div class="sect2" id="id-1.11.7.47.17"><div class="titlepage"><div><div><h3 class="title">F.38.7. Cross-Version Compatibility</h3></div></div></div><p>
+ <code class="filename">postgres_fdw</code> can be used with remote servers dating back
+ to <span class="productname">PostgreSQL</span> 8.3. Read-only capability is available
+ back to 8.1. A limitation however is that <code class="filename">postgres_fdw</code>
+ generally assumes that immutable built-in functions and operators are
+ safe to send to the remote server for execution, if they appear in a
+ <code class="literal">WHERE</code> clause for a foreign table. Thus, a built-in
+ function that was added since the remote server's release might be sent
+ to it for execution, resulting in <span class="quote">“<span class="quote">function does not exist</span>”</span> or
+ a similar error. This type of failure can be worked around by
+ rewriting the query, for example by embedding the foreign table
+ reference in a sub-<code class="literal">SELECT</code> with <code class="literal">OFFSET 0</code> as an
+ optimization fence, and placing the problematic function or operator
+ outside the sub-<code class="literal">SELECT</code>.
+ </p></div><div class="sect2" id="id-1.11.7.47.18"><div class="titlepage"><div><div><h3 class="title">F.38.8. Configuration Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-PGFDW-APPLICATION-NAME"><span class="term">
+ <code class="varname">postgres_fdw.application_name</code> (<code class="type">string</code>)
+ <a id="id-1.11.7.47.18.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a value for <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>
+ configuration parameter used when <code class="filename">postgres_fdw</code>
+ establishes a connection to a foreign server. This overrides
+ <code class="varname">application_name</code> option of the server object.
+ Note that change of this parameter doesn't affect any existing
+ connections until they are re-established.
+ </p><p>
+ <code class="varname">postgres_fdw.application_name</code> can be any string
+ of any length and contain even non-ASCII characters. However when
+ it's passed to and used as <code class="varname">application_name</code>
+ in a foreign server, note that it will be truncated to less than
+ <code class="symbol">NAMEDATALEN</code> characters and anything other than
+ printable ASCII characters will be replaced with question
+ marks (<code class="literal">?</code>).
+ See <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> for details.
+ </p><p>
+ <code class="literal">%</code> characters begin <span class="quote">“<span class="quote">escape sequences</span>”</span>
+ that are replaced with status information as outlined below.
+ Unrecognized escapes are ignored. Other characters are copied straight
+ to the application name. Note that it's not allowed to specify a
+ plus/minus sign or a numeric literal after the <code class="literal">%</code>
+ and before the option, for alignment and padding.
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Escape</th><th>Effect</th></tr></thead><tbody><tr><td><code class="literal">%a</code></td><td>Application name on local server</td></tr><tr><td><code class="literal">%c</code></td><td>
+ Session ID on local server
+ (see <a class="xref" href="runtime-config-logging.html#GUC-LOG-LINE-PREFIX">log_line_prefix</a> for details)
+ </td></tr><tr><td><code class="literal">%C</code></td><td>
+ Cluster name on local server
+ (see <a class="xref" href="runtime-config-logging.html#GUC-CLUSTER-NAME">cluster_name</a> for details)
+ </td></tr><tr><td><code class="literal">%u</code></td><td>User name on local server</td></tr><tr><td><code class="literal">%d</code></td><td>Database name on local server</td></tr><tr><td><code class="literal">%p</code></td><td>Process ID of backend on local server</td></tr><tr><td><code class="literal">%%</code></td><td>Literal %</td></tr></tbody></table></div><p>
+ For example, suppose user <code class="literal">local_user</code> establishes
+ a connection from database <code class="literal">local_db</code> to
+ <code class="literal">foreign_db</code> as user <code class="literal">foreign_user</code>,
+ the setting <code class="literal">'db=%d, user=%u'</code> is replaced with
+ <code class="literal">'db=local_db, user=local_user'</code>.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.47.19"><div class="titlepage"><div><div><h3 class="title">F.38.9. Examples</h3></div></div></div><p>
+ Here is an example of creating a foreign table with
+ <code class="literal">postgres_fdw</code>. First install the extension:
+ </p><pre class="programlisting">
+CREATE EXTENSION postgres_fdw;
+</pre><p>
+ Then create a foreign server using <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>.
+ In this example we wish to connect to a <span class="productname">PostgreSQL</span> server
+ on host <code class="literal">192.83.123.89</code> listening on
+ port <code class="literal">5432</code>. The database to which the connection is made
+ is named <code class="literal">foreign_db</code> on the remote server:
+
+</p><pre class="programlisting">
+CREATE SERVER foreign_server
+ FOREIGN DATA WRAPPER postgres_fdw
+ OPTIONS (host '192.83.123.89', port '5432', dbname 'foreign_db');
+</pre><p>
+ </p><p>
+ A user mapping, defined with <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>, is
+ needed as well to identify the role that will be used on the remote
+ server:
+
+</p><pre class="programlisting">
+CREATE USER MAPPING FOR local_user
+ SERVER foreign_server
+ OPTIONS (user 'foreign_user', password 'password');
+</pre><p>
+ </p><p>
+ Now it is possible to create a foreign table with
+ <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>. In this example we
+ wish to access the table named <code class="structname">some_schema.some_table</code>
+ on the remote server. The local name for it will
+ be <code class="structname">foreign_table</code>:
+
+</p><pre class="programlisting">
+CREATE FOREIGN TABLE foreign_table (
+ id integer NOT NULL,
+ data text
+)
+ SERVER foreign_server
+ OPTIONS (schema_name 'some_schema', table_name 'some_table');
+</pre><p>
+
+ It's essential that the data types and other properties of the columns
+ declared in <code class="command">CREATE FOREIGN TABLE</code> match the actual remote table.
+ Column names must match as well, unless you attach <code class="literal">column_name</code>
+ options to the individual columns to show how they are named in the remote
+ table.
+ In many cases, use of <a class="link" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><code class="command">IMPORT FOREIGN SCHEMA</code></a> is
+ preferable to constructing foreign table definitions manually.
+ </p></div><div class="sect2" id="id-1.11.7.47.20"><div class="titlepage"><div><div><h3 class="title">F.38.10. Author</h3></div></div></div><p>
+ Shigeru Hanada <code class="email">&lt;<a class="email" href="mailto:shigeru.hanada@gmail.com">shigeru.hanada@gmail.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgwalinspect.html" title="F.37. pg_walinspect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="seg.html" title="F.39. seg">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.37. pg_walinspect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.39. seg</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/postgres-user.html b/doc/src/sgml/html/postgres-user.html
new file mode 100644
index 0000000..c2e1ec4
--- /dev/null
+++ b/doc/src/sgml/html/postgres-user.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.1. The PostgreSQL User Account</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime.html" title="Chapter 19. Server Setup and Operation" /><link rel="next" href="creating-cluster.html" title="19.2. Creating a Database Cluster" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.1. The <span class="productname">PostgreSQL</span> User Account</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime.html" title="Chapter 19. Server Setup and Operation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Next</a></td></tr></table><hr /></div><div class="sect1" id="POSTGRES-USER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.1. The <span class="productname">PostgreSQL</span> User Account</h2></div></div></div><a id="id-1.6.6.4.2" class="indexterm"></a><p>
+ As with any server daemon that is accessible to the outside world,
+ it is advisable to run <span class="productname">PostgreSQL</span> under a
+ separate user account. This user account should only own the data
+ that is managed by the server, and should not be shared with other
+ daemons. (For example, using the user <code class="literal">nobody</code> is a bad
+ idea.) In particular, it is advisable that this user account not own
+ the <span class="productname">PostgreSQL</span> executable files, to ensure
+ that a compromised server process could not modify those executables.
+ </p><p>
+ Pre-packaged versions of <span class="productname">PostgreSQL</span> will
+ typically create a suitable user account automatically during
+ package installation.
+ </p><p>
+ To add a Unix user account to your system, look for a command
+ <code class="command">useradd</code> or <code class="command">adduser</code>. The user
+ name <span class="systemitem">postgres</span> is often used, and is assumed
+ throughout this book, but you can use another name if you like.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime.html" title="Chapter 19. Server Setup and Operation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Server Setup and Operation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.2. Creating a Database Cluster</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/predefined-roles.html b/doc/src/sgml/html/predefined-roles.html
new file mode 100644
index 0000000..bb525bc
--- /dev/null
+++ b/doc/src/sgml/html/predefined-roles.html
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.5. Predefined Roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="role-removal.html" title="22.4. Dropping Roles" /><link rel="next" href="perm-functions.html" title="22.6. Function Security" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.5. Predefined Roles</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="role-removal.html" title="22.4. Dropping Roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="perm-functions.html" title="22.6. Function Security">Next</a></td></tr></table><hr /></div><div class="sect1" id="PREDEFINED-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.5. Predefined Roles</h2></div></div></div><a id="id-1.6.9.9.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides a set of predefined roles
+ that provide access to certain, commonly needed, privileged capabilities
+ and information. Administrators (including roles that have the
+ <code class="literal">CREATEROLE</code> privilege) can <code class="command">GRANT</code> these
+ roles to users and/or other roles in their environment, providing those
+ users with access to the specified capabilities and information.
+ </p><p>
+ The predefined roles are described in <a class="xref" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles">Table 22.1</a>.
+ Note that the specific permissions for each of the roles may change in
+ the future as additional capabilities are added. Administrators
+ should monitor the release notes for changes.
+ </p><div class="table" id="PREDEFINED-ROLES-TABLE"><p class="title"><strong>Table 22.1. Predefined Roles</strong></p><div class="table-contents"><table class="table" summary="Predefined Roles" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Role</th><th>Allowed Access</th></tr></thead><tbody><tr><td>pg_read_all_data</td><td>Read all data (tables, views, sequences), as if having
+ <code class="command">SELECT</code> rights on those objects, and USAGE rights on
+ all schemas, even without having it explicitly. This role does not have
+ the role attribute <code class="literal">BYPASSRLS</code> set. If RLS is being
+ used, an administrator may wish to set <code class="literal">BYPASSRLS</code> on
+ roles which this role is GRANTed to.</td></tr><tr><td>pg_write_all_data</td><td>Write all data (tables, views, sequences), as if having
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> rights on those objects, and USAGE rights on
+ all schemas, even without having it explicitly. This role does not have
+ the role attribute <code class="literal">BYPASSRLS</code> set. If RLS is being
+ used, an administrator may wish to set <code class="literal">BYPASSRLS</code> on
+ roles which this role is GRANTed to.</td></tr><tr><td>pg_read_all_settings</td><td>Read all configuration variables, even those normally visible only to
+ superusers.</td></tr><tr><td>pg_read_all_stats</td><td>Read all pg_stat_* views and use various statistics related extensions,
+ even those normally visible only to superusers.</td></tr><tr><td>pg_stat_scan_tables</td><td>Execute monitoring functions that may take <code class="literal">ACCESS SHARE</code> locks on tables,
+ potentially for a long time.</td></tr><tr><td>pg_monitor</td><td>Read/execute various monitoring views and functions.
+ This role is a member of <code class="literal">pg_read_all_settings</code>,
+ <code class="literal">pg_read_all_stats</code> and
+ <code class="literal">pg_stat_scan_tables</code>.</td></tr><tr><td>pg_database_owner</td><td>None. Membership consists, implicitly, of the current database owner.</td></tr><tr><td>pg_signal_backend</td><td>Signal another backend to cancel a query or terminate its session.</td></tr><tr><td>pg_read_server_files</td><td>Allow reading files from any location the database can access on the server with COPY and
+ other file-access functions.</td></tr><tr><td>pg_write_server_files</td><td>Allow writing to files in any location the database can access on the server with COPY and
+ other file-access functions.</td></tr><tr><td>pg_execute_server_program</td><td>Allow executing programs on the database server as the user the database runs as with
+ COPY and other functions which allow executing a server-side program.</td></tr><tr><td>pg_checkpoint</td><td>Allow executing
+ the <a class="link" href="sql-checkpoint.html" title="CHECKPOINT"><code class="command">CHECKPOINT</code></a>
+ command.</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="literal">pg_monitor</code>, <code class="literal">pg_read_all_settings</code>,
+ <code class="literal">pg_read_all_stats</code> and <code class="literal">pg_stat_scan_tables</code>
+ roles are intended to allow administrators to easily configure a role for the
+ purpose of monitoring the database server. They grant a set of common privileges
+ allowing the role to read various useful configuration settings, statistics and
+ other system information normally restricted to superusers.
+ </p><p>
+ The <code class="literal">pg_database_owner</code> role has one implicit,
+ situation-dependent member, namely the owner of the current database. Like
+ any role, it can own objects or receive grants of access privileges.
+ Consequently, once <code class="literal">pg_database_owner</code> has rights within a
+ template database, each owner of a database instantiated from that template
+ will exercise those rights. <code class="literal">pg_database_owner</code> cannot be
+ a member of any role, and it cannot have non-implicit members. Initially,
+ this role owns the <code class="literal">public</code> schema, so each database owner
+ governs local use of the schema.
+ </p><p>
+ The <code class="literal">pg_signal_backend</code> role is intended to allow
+ administrators to enable trusted, but non-superuser, roles to send signals
+ to other backends. Currently this role enables sending of signals for
+ canceling a query on another backend or terminating its session. A user
+ granted this role cannot however send signals to a backend owned by a
+ superuser. See <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL" title="9.27.2. Server Signaling Functions">Section 9.27.2</a>.
+ </p><p>
+ The <code class="literal">pg_read_server_files</code>, <code class="literal">pg_write_server_files</code> and
+ <code class="literal">pg_execute_server_program</code> roles are intended to allow administrators to have
+ trusted, but non-superuser, roles which are able to access files and run programs on the
+ database server as the user the database runs as. As these roles are able to access any file on
+ the server file system, they bypass all database-level permission checks when accessing files
+ directly and they could be used to gain superuser-level access, therefore
+ great care should be taken when granting these roles to users.
+ </p><p>
+ Care should be taken when granting these roles to ensure they are only used where
+ needed and with the understanding that these roles grant access to privileged
+ information.
+ </p><p>
+ Administrators can grant access to these roles to users using the
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> command, for example:
+
+</p><pre class="programlisting">
+GRANT pg_signal_backend TO admin_user;
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="role-removal.html" title="22.4. Dropping Roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="perm-functions.html" title="22.6. Function Security">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.4. Dropping Roles </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.6. Function Security</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/preface.html b/doc/src/sgml/html/preface.html
new file mode 100644
index 0000000..1c0da57
--- /dev/null
+++ b/doc/src/sgml/html/preface.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Preface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index.html" title="PostgreSQL 15.5 Documentation" /><link rel="next" href="intro-whatis.html" title="1.  What Is PostgreSQL?" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Preface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index.html" title="PostgreSQL 15.5 Documentation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="intro-whatis.html" title="1.  What Is PostgreSQL?">Next</a></td></tr></table><hr /></div><div class="preface" id="PREFACE"><div class="titlepage"><div><div><h1 class="title">Preface</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="intro-whatis.html">1. What Is <span class="productname">PostgreSQL</span>?</a></span></dt><dt><span class="sect1"><a href="history.html">2. A Brief History of <span class="productname">PostgreSQL</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="history.html#HISTORY-BERKELEY">2.1. The Berkeley <span class="productname">POSTGRES</span> Project</a></span></dt><dt><span class="sect2"><a href="history.html#HISTORY-POSTGRES95">2.2. <span class="productname">Postgres95</span></a></span></dt><dt><span class="sect2"><a href="history.html#id-1.3.5.6">2.3. <span class="productname">PostgreSQL</span></a></span></dt></dl></dd><dt><span class="sect1"><a href="notation.html">3. Conventions</a></span></dt><dt><span class="sect1"><a href="resources.html">4. Further Information</a></span></dt><dt><span class="sect1"><a href="bug-reporting.html">5. Bug Reporting Guidelines</a></span></dt><dd><dl><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.5">5.1. Identifying Bugs</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.6">5.2. What to Report</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.7">5.3. Where to Report Bugs</a></span></dt></dl></dd></dl></div><p>
+ This book is the official documentation of
+ <span class="productname">PostgreSQL</span>. It has been written by the
+ <span class="productname">PostgreSQL</span> developers and other
+ volunteers in parallel to the development of the
+ <span class="productname">PostgreSQL</span> software. It describes all
+ the functionality that the current version of
+ <span class="productname">PostgreSQL</span> officially supports.
+ </p><p>
+ To make the large amount of information about
+ <span class="productname">PostgreSQL</span> manageable, this book has been
+ organized in several parts. Each part is targeted at a different
+ class of users, or at users in different stages of their
+ <span class="productname">PostgreSQL</span> experience:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="xref" href="tutorial.html" title="Part I. Tutorial">Part I</a> is an informal introduction for new users.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="sql.html" title="Part II. The SQL Language">Part II</a> documents the <acronym class="acronym">SQL</acronym> query
+ language environment, including data types and functions, as well
+ as user-level performance tuning. Every
+ <span class="productname">PostgreSQL</span> user should read this.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="admin.html" title="Part III. Server Administration">Part III</a> describes the installation and
+ administration of the server. Everyone who runs a
+ <span class="productname">PostgreSQL</span> server, be it for private
+ use or for others, should read this part.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="client-interfaces.html" title="Part IV. Client Interfaces">Part IV</a> describes the programming
+ interfaces for <span class="productname">PostgreSQL</span> client
+ programs.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="server-programming.html" title="Part V. Server Programming">Part V</a> contains information for
+ advanced users about the extensibility capabilities of the
+ server. Topics include user-defined data types and
+ functions.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="reference.html" title="Part VI. Reference">Part VI</a> contains reference information about
+ SQL commands, client and server programs. This part supports
+ the other parts with structured information sorted by command or
+ program.
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="internals.html" title="Part VII. Internals">Part VII</a> contains assorted information that might be of
+ use to <span class="productname">PostgreSQL</span> developers.
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html" title="PostgreSQL 15.5 Documentation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="intro-whatis.html" title="1.  What Is PostgreSQL?">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostgreSQL 15.5 Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 1.  What Is <span class="productname">PostgreSQL</span>?</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/preventing-server-spoofing.html b/doc/src/sgml/html/preventing-server-spoofing.html
new file mode 100644
index 0000000..87dd039
--- /dev/null
+++ b/doc/src/sgml/html/preventing-server-spoofing.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.7. Preventing Server Spoofing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster" /><link rel="next" href="encryption-options.html" title="19.8. Encryption Options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.7. Preventing Server Spoofing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="encryption-options.html" title="19.8. Encryption Options">Next</a></td></tr></table><hr /></div><div class="sect1" id="PREVENTING-SERVER-SPOOFING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.7. Preventing Server Spoofing</h2></div></div></div><a id="id-1.6.6.10.2" class="indexterm"></a><p>
+ While the server is running, it is not possible for a malicious user
+ to take the place of the normal database server. However, when the
+ server is down, it is possible for a local user to spoof the normal
+ server by starting their own server. The spoof server could read
+ passwords and queries sent by clients, but could not return any data
+ because the <code class="varname">PGDATA</code> directory would still be secure because
+ of directory permissions. Spoofing is possible because any user can
+ start a database server; a client cannot identify an invalid server
+ unless it is specially configured.
+ </p><p>
+ One way to prevent spoofing of <code class="literal">local</code>
+ connections is to use a Unix domain socket directory (<a class="xref" href="runtime-config-connection.html#GUC-UNIX-SOCKET-DIRECTORIES">unix_socket_directories</a>) that has write permission only
+ for a trusted local user. This prevents a malicious user from creating
+ their own socket file in that directory. If you are concerned that
+ some applications might still reference <code class="filename">/tmp</code> for the
+ socket file and hence be vulnerable to spoofing, during operating system
+ startup create a symbolic link <code class="filename">/tmp/.s.PGSQL.5432</code> that points
+ to the relocated socket file. You also might need to modify your
+ <code class="filename">/tmp</code> cleanup script to prevent removal of the symbolic link.
+ </p><p>
+ Another option for <code class="literal">local</code> connections is for clients to use
+ <a class="link" href="libpq-connect.html#LIBPQ-CONNECT-REQUIREPEER"><code class="literal">requirepeer</code></a>
+ to specify the required owner of the server process connected to
+ the socket.
+ </p><p>
+ To prevent spoofing on TCP connections, either use
+ SSL certificates and make sure that clients check the server's certificate,
+ or use GSSAPI encryption (or both, if they're on separate connections).
+ </p><p>
+ To prevent spoofing with SSL, the server
+ must be configured to accept only <code class="literal">hostssl</code> connections (<a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a>) and have SSL key and certificate files
+ (<a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a>). The TCP client must connect using
+ <code class="literal">sslmode=verify-ca</code> or
+ <code class="literal">verify-full</code> and have the appropriate root certificate
+ file installed (<a class="xref" href="libpq-ssl.html#LIBQ-SSL-CERTIFICATES" title="34.19.1. Client Verification of Server Certificates">Section 34.19.1</a>).
+ </p><p>
+ To prevent spoofing with GSSAPI, the server must be configured to accept
+ only <code class="literal">hostgssenc</code> connections
+ (<a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a>) and use <code class="literal">gss</code>
+ authentication with them. The TCP client must connect
+ using <code class="literal">gssencmode=require</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="encryption-options.html" title="19.8. Encryption Options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.8. Encryption Options</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/progress-reporting.html b/doc/src/sgml/html/progress-reporting.html
new file mode 100644
index 0000000..7a88820
--- /dev/null
+++ b/doc/src/sgml/html/progress-reporting.html
@@ -0,0 +1,651 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>28.4. Progress Reporting</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="monitoring-locks.html" title="28.3. Viewing Locks" /><link rel="next" href="dynamic-trace.html" title="28.5. Dynamic Tracing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">28.4. Progress Reporting</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="monitoring-locks.html" title="28.3. Viewing Locks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROGRESS-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">28.4. Progress Reporting</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING">28.4.1. ANALYZE Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING">28.4.2. CREATE INDEX Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#VACUUM-PROGRESS-REPORTING">28.4.3. VACUUM Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING">28.4.4. CLUSTER Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#BASEBACKUP-PROGRESS-REPORTING">28.4.5. Base Backup Progress Reporting</a></span></dt><dt><span class="sect2"><a href="progress-reporting.html#COPY-PROGRESS-REPORTING">28.4.6. COPY Progress Reporting</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> has the ability to report the progress of
+ certain commands during command execution. Currently, the only commands
+ which support progress reporting are <code class="command">ANALYZE</code>,
+ <code class="command">CLUSTER</code>,
+ <code class="command">CREATE INDEX</code>, <code class="command">VACUUM</code>,
+ <code class="command">COPY</code>,
+ and <a class="xref" href="protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP">BASE_BACKUP</a> (i.e., replication
+ command that <a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a> issues to take
+ a base backup).
+ This may be expanded in the future.
+ </p><div class="sect2" id="ANALYZE-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.1. ANALYZE Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.3.2" class="indexterm"></a><p>
+ Whenever <code class="command">ANALYZE</code> is running, the
+ <code class="structname">pg_stat_progress_analyze</code> view will contain a
+ row for each backend that is currently running that command. The tables
+ below describe the information that will be reported and provide
+ information about how to interpret it.
+ </p><div class="table" id="PG-STAT-PROGRESS-ANALYZE-VIEW"><p class="title"><strong>Table 28.36. <code class="structname">pg_stat_progress_analyze</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_analyze View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of backend.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table being analyzed.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">phase</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current processing phase. See <a class="xref" href="progress-reporting.html#ANALYZE-PHASES" title="Table 28.37. ANALYZE Phases">Table 28.37</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sample_blks_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of heap blocks that will be sampled.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sample_blks_scanned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap blocks scanned.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ext_stats_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of extended statistics.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ext_stats_computed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of extended statistics computed. This counter only advances
+ when the phase is <code class="literal">computing extended statistics</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">child_tables_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of child tables.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">child_tables_done</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of child tables scanned. This counter only advances when the
+ phase is <code class="literal">acquiring inherited sample rows</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">current_child_table_relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the child table currently being scanned. This field is
+ only valid when the phase is
+ <code class="literal">acquiring inherited sample rows</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="ANALYZE-PHASES"><p class="title"><strong>Table 28.37. ANALYZE Phases</strong></p><div class="table-contents"><table class="table" summary="ANALYZE Phases" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Phase</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">initializing</code></td><td>
+ The command is preparing to begin scanning the heap. This phase is
+ expected to be very brief.
+ </td></tr><tr><td><code class="literal">acquiring sample rows</code></td><td>
+ The command is currently scanning the table given by
+ <code class="structfield">relid</code> to obtain sample rows.
+ </td></tr><tr><td><code class="literal">acquiring inherited sample rows</code></td><td>
+ The command is currently scanning child tables to obtain sample rows.
+ Columns <code class="structfield">child_tables_total</code>,
+ <code class="structfield">child_tables_done</code>, and
+ <code class="structfield">current_child_table_relid</code> contain the
+ progress information for this phase.
+ </td></tr><tr><td><code class="literal">computing statistics</code></td><td>
+ The command is computing statistics from the sample rows obtained
+ during the table scan.
+ </td></tr><tr><td><code class="literal">computing extended statistics</code></td><td>
+ The command is computing extended statistics from the sample rows
+ obtained during the table scan.
+ </td></tr><tr><td><code class="literal">finalizing analyze</code></td><td>
+ The command is updating <code class="structname">pg_class</code>. When this
+ phase is completed, <code class="command">ANALYZE</code> will end.
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ Note that when <code class="command">ANALYZE</code> is run on a partitioned table,
+ all of its partitions are also recursively analyzed.
+ In that case, <code class="command">ANALYZE</code>
+ progress is reported first for the parent table, whereby its inheritance
+ statistics are collected, followed by that for each partition.
+ </p></div></div><div class="sect2" id="CREATE-INDEX-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.2. CREATE INDEX Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.4.2" class="indexterm"></a><p>
+ Whenever <code class="command">CREATE INDEX</code> or <code class="command">REINDEX</code> is running, the
+ <code class="structname">pg_stat_progress_create_index</code> view will contain
+ one row for each backend that is currently creating indexes. The tables
+ below describe the information that will be reported and provide information
+ about how to interpret it.
+ </p><div class="table" id="PG-STAT-PROGRESS-CREATE-INDEX-VIEW"><p class="title"><strong>Table 28.38. <code class="structname">pg_stat_progress_create_index</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_create_index View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of backend.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table on which the index is being created.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">index_relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the index being created or reindexed. During a
+ non-concurrent <code class="command">CREATE INDEX</code>, this is 0.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">command</code> <code class="type">text</code>
+ </p>
+ <p>
+ The command that is running: <code class="literal">CREATE INDEX</code>,
+ <code class="literal">CREATE INDEX CONCURRENTLY</code>,
+ <code class="literal">REINDEX</code>, or <code class="literal">REINDEX CONCURRENTLY</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">phase</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current processing phase of index creation. See <a class="xref" href="progress-reporting.html#CREATE-INDEX-PHASES" title="Table 28.39. CREATE INDEX Phases">Table 28.39</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lockers_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of lockers to wait for, when applicable.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">lockers_done</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of lockers already waited for.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">current_locker_pid</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Process ID of the locker currently being waited for.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blocks_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of blocks to be processed in the current phase.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">blocks_done</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of blocks already processed in the current phase.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tuples_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of tuples to be processed in the current phase.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tuples_done</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of tuples already processed in the current phase.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partitions_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ When creating an index on a partitioned table, this column is set to
+ the total number of partitions on which the index is to be created.
+ This field is <code class="literal">0</code> during a <code class="literal">REINDEX</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">partitions_done</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ When creating an index on a partitioned table, this column is set to
+ the number of partitions on which the index has been created.
+ This field is <code class="literal">0</code> during a <code class="literal">REINDEX</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="CREATE-INDEX-PHASES"><p class="title"><strong>Table 28.39. CREATE INDEX Phases</strong></p><div class="table-contents"><table class="table" summary="CREATE INDEX Phases" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Phase</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">initializing</code></td><td>
+ <code class="command">CREATE INDEX</code> or <code class="command">REINDEX</code> is preparing to create the index. This
+ phase is expected to be very brief.
+ </td></tr><tr><td><code class="literal">waiting for writers before build</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> or <code class="command">REINDEX CONCURRENTLY</code> is waiting for transactions
+ with write locks that can potentially see the table to finish.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">lockers_total</code>, <code class="structname">lockers_done</code>
+ and <code class="structname">current_locker_pid</code> contain the progress
+ information for this phase.
+ </td></tr><tr><td><code class="literal">building index</code></td><td>
+ The index is being built by the access method-specific code. In this phase,
+ access methods that support progress reporting fill in their own progress data,
+ and the subphase is indicated in this column. Typically,
+ <code class="structname">blocks_total</code> and <code class="structname">blocks_done</code>
+ will contain progress data, as well as potentially
+ <code class="structname">tuples_total</code> and <code class="structname">tuples_done</code>.
+ </td></tr><tr><td><code class="literal">waiting for writers before validation</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> or <code class="command">REINDEX CONCURRENTLY</code> is waiting for transactions
+ with write locks that can potentially write into the table to finish.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">lockers_total</code>, <code class="structname">lockers_done</code>
+ and <code class="structname">current_locker_pid</code> contain the progress
+ information for this phase.
+ </td></tr><tr><td><code class="literal">index validation: scanning index</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> is scanning the index searching
+ for tuples that need to be validated.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">blocks_total</code> (set to the total size of the index)
+ and <code class="structname">blocks_done</code> contain the progress information for this phase.
+ </td></tr><tr><td><code class="literal">index validation: sorting tuples</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> is sorting the output of the
+ index scanning phase.
+ </td></tr><tr><td><code class="literal">index validation: scanning table</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> is scanning the table
+ to validate the index tuples collected in the previous two phases.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">blocks_total</code> (set to the total size of the table)
+ and <code class="structname">blocks_done</code> contain the progress information for this phase.
+ </td></tr><tr><td><code class="literal">waiting for old snapshots</code></td><td>
+ <code class="command">CREATE INDEX CONCURRENTLY</code> or <code class="command">REINDEX CONCURRENTLY</code> is waiting for transactions
+ that can potentially see the table to release their snapshots. This
+ phase is skipped when not in concurrent mode.
+ Columns <code class="structname">lockers_total</code>, <code class="structname">lockers_done</code>
+ and <code class="structname">current_locker_pid</code> contain the progress
+ information for this phase.
+ </td></tr><tr><td><code class="literal">waiting for readers before marking dead</code></td><td>
+ <code class="command">REINDEX CONCURRENTLY</code> is waiting for transactions
+ with read locks on the table to finish, before marking the old index dead.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">lockers_total</code>, <code class="structname">lockers_done</code>
+ and <code class="structname">current_locker_pid</code> contain the progress
+ information for this phase.
+ </td></tr><tr><td><code class="literal">waiting for readers before dropping</code></td><td>
+ <code class="command">REINDEX CONCURRENTLY</code> is waiting for transactions
+ with read locks on the table to finish, before dropping the old index.
+ This phase is skipped when not in concurrent mode.
+ Columns <code class="structname">lockers_total</code>, <code class="structname">lockers_done</code>
+ and <code class="structname">current_locker_pid</code> contain the progress
+ information for this phase.
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="VACUUM-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.3. VACUUM Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.5.2" class="indexterm"></a><p>
+ Whenever <code class="command">VACUUM</code> is running, the
+ <code class="structname">pg_stat_progress_vacuum</code> view will contain
+ one row for each backend (including autovacuum worker processes) that is
+ currently vacuuming. The tables below describe the information
+ that will be reported and provide information about how to interpret it.
+ Progress for <code class="command">VACUUM FULL</code> commands is reported via
+ <code class="structname">pg_stat_progress_cluster</code>
+ because both <code class="command">VACUUM FULL</code> and <code class="command">CLUSTER</code>
+ rewrite the table, while regular <code class="command">VACUUM</code> only modifies it
+ in place. See <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a>.
+ </p><div class="table" id="PG-STAT-PROGRESS-VACUUM-VIEW"><p class="title"><strong>Table 28.40. <code class="structname">pg_stat_progress_vacuum</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_vacuum View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of backend.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table being vacuumed.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">phase</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current processing phase of vacuum. See <a class="xref" href="progress-reporting.html#VACUUM-PHASES" title="Table 28.41. VACUUM Phases">Table 28.41</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of heap blocks in the table. This number is reported
+ as of the beginning of the scan; blocks added later will not be (and
+ need not be) visited by this <code class="command">VACUUM</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_scanned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap blocks scanned. Because the
+ <a class="link" href="storage-vm.html" title="73.4. Visibility Map">visibility map</a> is used to optimize scans,
+ some blocks will be skipped without inspection; skipped blocks are
+ included in this total, so that this number will eventually become
+ equal to <code class="structfield">heap_blks_total</code> when the vacuum is complete.
+ This counter only advances when the phase is <code class="literal">scanning heap</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_vacuumed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap blocks vacuumed. Unless the table has no indexes, this
+ counter only advances when the phase is <code class="literal">vacuuming heap</code>.
+ Blocks that contain no dead tuples are skipped, so the counter may
+ sometimes skip forward in large increments.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">index_vacuum_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of completed index vacuum cycles.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_dead_tuples</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of dead tuples that we can store before needing to perform
+ an index vacuum cycle, based on
+ <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">num_dead_tuples</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of dead tuples collected since the last index vacuum cycle.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="VACUUM-PHASES"><p class="title"><strong>Table 28.41. VACUUM Phases</strong></p><div class="table-contents"><table class="table" summary="VACUUM Phases" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Phase</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">initializing</code></td><td>
+ <code class="command">VACUUM</code> is preparing to begin scanning the heap. This
+ phase is expected to be very brief.
+ </td></tr><tr><td><code class="literal">scanning heap</code></td><td>
+ <code class="command">VACUUM</code> is currently scanning the heap. It will prune and
+ defragment each page if required, and possibly perform freezing
+ activity. The <code class="structfield">heap_blks_scanned</code> column can be used
+ to monitor the progress of the scan.
+ </td></tr><tr><td><code class="literal">vacuuming indexes</code></td><td>
+ <code class="command">VACUUM</code> is currently vacuuming the indexes. If a table has
+ any indexes, this will happen at least once per vacuum, after the heap
+ has been completely scanned. It may happen multiple times per vacuum
+ if <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a> (or, in the case of autovacuum,
+ <a class="xref" href="runtime-config-resource.html#GUC-AUTOVACUUM-WORK-MEM">autovacuum_work_mem</a> if set) is insufficient to store
+ the number of dead tuples found.
+ </td></tr><tr><td><code class="literal">vacuuming heap</code></td><td>
+ <code class="command">VACUUM</code> is currently vacuuming the heap. Vacuuming the heap
+ is distinct from scanning the heap, and occurs after each instance of
+ vacuuming indexes. If <code class="structfield">heap_blks_scanned</code> is less than
+ <code class="structfield">heap_blks_total</code>, the system will return to scanning
+ the heap after this phase is completed; otherwise, it will begin
+ cleaning up indexes after this phase is completed.
+ </td></tr><tr><td><code class="literal">cleaning up indexes</code></td><td>
+ <code class="command">VACUUM</code> is currently cleaning up indexes. This occurs after
+ the heap has been completely scanned and all vacuuming of the indexes
+ and the heap has been completed.
+ </td></tr><tr><td><code class="literal">truncating heap</code></td><td>
+ <code class="command">VACUUM</code> is currently truncating the heap so as to return
+ empty pages at the end of the relation to the operating system. This
+ occurs after cleaning up indexes.
+ </td></tr><tr><td><code class="literal">performing final cleanup</code></td><td>
+ <code class="command">VACUUM</code> is performing final cleanup. During this phase,
+ <code class="command">VACUUM</code> will vacuum the free space map, update statistics
+ in <code class="literal">pg_class</code>, and report statistics to the cumulative
+ statistics system. When this phase is completed, <code class="command">VACUUM</code> will end.
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="CLUSTER-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.4. CLUSTER Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.6.2" class="indexterm"></a><p>
+ Whenever <code class="command">CLUSTER</code> or <code class="command">VACUUM FULL</code> is
+ running, the <code class="structname">pg_stat_progress_cluster</code> view will
+ contain a row for each backend that is currently running either command.
+ The tables below describe the information that will be reported and
+ provide information about how to interpret it.
+ </p><div class="table" id="PG-STAT-PROGRESS-CLUSTER-VIEW"><p class="title"><strong>Table 28.42. <code class="structname">pg_stat_progress_cluster</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_cluster View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of backend.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table being clustered.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">command</code> <code class="type">text</code>
+ </p>
+ <p>
+ The command that is running. Either <code class="literal">CLUSTER</code> or <code class="literal">VACUUM FULL</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">phase</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current processing phase. See <a class="xref" href="progress-reporting.html#CLUSTER-PHASES" title="Table 28.43. CLUSTER and VACUUM FULL Phases">Table 28.43</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cluster_index_relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ If the table is being scanned using an index, this is the OID of the
+ index being used; otherwise, it is zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_tuples_scanned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap tuples scanned.
+ This counter only advances when the phase is
+ <code class="literal">seq scanning heap</code>,
+ <code class="literal">index scanning heap</code>
+ or <code class="literal">writing new heap</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_tuples_written</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap tuples written.
+ This counter only advances when the phase is
+ <code class="literal">seq scanning heap</code>,
+ <code class="literal">index scanning heap</code>
+ or <code class="literal">writing new heap</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of heap blocks in the table. This number is reported
+ as of the beginning of <code class="literal">seq scanning heap</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">heap_blks_scanned</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of heap blocks scanned. This counter only advances when the
+ phase is <code class="literal">seq scanning heap</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">index_rebuild_count</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of indexes rebuilt. This counter only advances when the phase
+ is <code class="literal">rebuilding index</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="CLUSTER-PHASES"><p class="title"><strong>Table 28.43. CLUSTER and VACUUM FULL Phases</strong></p><div class="table-contents"><table class="table" summary="CLUSTER and VACUUM FULL Phases" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Phase</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">initializing</code></td><td>
+ The command is preparing to begin scanning the heap. This phase is
+ expected to be very brief.
+ </td></tr><tr><td><code class="literal">seq scanning heap</code></td><td>
+ The command is currently scanning the table using a sequential scan.
+ </td></tr><tr><td><code class="literal">index scanning heap</code></td><td>
+ <code class="command">CLUSTER</code> is currently scanning the table using an index scan.
+ </td></tr><tr><td><code class="literal">sorting tuples</code></td><td>
+ <code class="command">CLUSTER</code> is currently sorting tuples.
+ </td></tr><tr><td><code class="literal">writing new heap</code></td><td>
+ <code class="command">CLUSTER</code> is currently writing the new heap.
+ </td></tr><tr><td><code class="literal">swapping relation files</code></td><td>
+ The command is currently swapping newly-built files into place.
+ </td></tr><tr><td><code class="literal">rebuilding index</code></td><td>
+ The command is currently rebuilding an index.
+ </td></tr><tr><td><code class="literal">performing final cleanup</code></td><td>
+ The command is performing final cleanup. When this phase is
+ completed, <code class="command">CLUSTER</code>
+ or <code class="command">VACUUM FULL</code> will end.
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="BASEBACKUP-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.5. Base Backup Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.7.2" class="indexterm"></a><p>
+ Whenever an application like <span class="application">pg_basebackup</span>
+ is taking a base backup, the
+ <code class="structname">pg_stat_progress_basebackup</code>
+ view will contain a row for each WAL sender process that is currently
+ running the <code class="command">BASE_BACKUP</code> replication command
+ and streaming the backup. The tables below describe the information
+ that will be reported and provide information about how to interpret it.
+ </p><div class="table" id="PG-STAT-PROGRESS-BASEBACKUP-VIEW"><p class="title"><strong>Table 28.44. <code class="structname">pg_stat_progress_basebackup</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_basebackup View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of a WAL sender process.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">phase</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current processing phase. See <a class="xref" href="progress-reporting.html#BASEBACKUP-PHASES" title="Table 28.45. Base Backup Phases">Table 28.45</a>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backup_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total amount of data that will be streamed. This is estimated and
+ reported as of the beginning of
+ <code class="literal">streaming database files</code> phase. Note that
+ this is only an approximation since the database
+ may change during <code class="literal">streaming database files</code> phase
+ and WAL log may be included in the backup later. This is always
+ the same value as <code class="structfield">backup_streamed</code>
+ once the amount of data streamed exceeds the estimated
+ total size. If the estimation is disabled in
+ <span class="application">pg_basebackup</span>
+ (i.e., <code class="literal">--no-estimate-size</code> option is specified),
+ this is <code class="literal">NULL</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">backup_streamed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Amount of data streamed. This counter only advances
+ when the phase is <code class="literal">streaming database files</code> or
+ <code class="literal">transferring wal files</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablespaces_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Total number of tablespaces that will be streamed.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablespaces_streamed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of tablespaces streamed. This counter only
+ advances when the phase is <code class="literal">streaming database files</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="BASEBACKUP-PHASES"><p class="title"><strong>Table 28.45. Base Backup Phases</strong></p><div class="table-contents"><table class="table" summary="Base Backup Phases" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Phase</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">initializing</code></td><td>
+ The WAL sender process is preparing to begin the backup.
+ This phase is expected to be very brief.
+ </td></tr><tr><td><code class="literal">waiting for checkpoint to finish</code></td><td>
+ The WAL sender process is currently performing
+ <code class="function">pg_backup_start</code> to prepare to
+ take a base backup, and waiting for the start-of-backup
+ checkpoint to finish.
+ </td></tr><tr><td><code class="literal">estimating backup size</code></td><td>
+ The WAL sender process is currently estimating the total amount
+ of database files that will be streamed as a base backup.
+ </td></tr><tr><td><code class="literal">streaming database files</code></td><td>
+ The WAL sender process is currently streaming database files
+ as a base backup.
+ </td></tr><tr><td><code class="literal">waiting for wal archiving to finish</code></td><td>
+ The WAL sender process is currently performing
+ <code class="function">pg_backup_stop</code> to finish the backup,
+ and waiting for all the WAL files required for the base backup
+ to be successfully archived.
+ If either <code class="literal">--wal-method=none</code> or
+ <code class="literal">--wal-method=stream</code> is specified in
+ <span class="application">pg_basebackup</span>, the backup will end
+ when this phase is completed.
+ </td></tr><tr><td><code class="literal">transferring wal files</code></td><td>
+ The WAL sender process is currently transferring all WAL logs
+ generated during the backup. This phase occurs after
+ <code class="literal">waiting for wal archiving to finish</code> phase if
+ <code class="literal">--wal-method=fetch</code> is specified in
+ <span class="application">pg_basebackup</span>. The backup will end
+ when this phase is completed.
+ </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="COPY-PROGRESS-REPORTING"><div class="titlepage"><div><div><h3 class="title">28.4.6. COPY Progress Reporting</h3></div></div></div><a id="id-1.6.15.9.8.2" class="indexterm"></a><p>
+ Whenever <code class="command">COPY</code> is running, the
+ <code class="structname">pg_stat_progress_copy</code> view will contain one row
+ for each backend that is currently running a <code class="command">COPY</code> command.
+ The table below describes the information that will be reported and provides
+ information about how to interpret it.
+ </p><div class="table" id="PG-STAT-PROGRESS-COPY-VIEW"><p class="title"><strong>Table 28.46. <code class="structname">pg_stat_progress_copy</code> View</strong></p><div class="table-contents"><table class="table" summary="pg_stat_progress_copy View" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">integer</code>
+ </p>
+ <p>
+ Process ID of backend.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the database to which this backend is connected.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ OID of the table on which the <code class="command">COPY</code> command is
+ executed. It is set to <code class="literal">0</code> if copying from a
+ <code class="command">SELECT</code> query.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">command</code> <code class="type">text</code>
+ </p>
+ <p>
+ The command that is running: <code class="literal">COPY FROM</code>, or
+ <code class="literal">COPY TO</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">type</code> <code class="type">text</code>
+ </p>
+ <p>
+ The io type that the data is read from or written to:
+ <code class="literal">FILE</code>, <code class="literal">PROGRAM</code>,
+ <code class="literal">PIPE</code> (for <code class="command">COPY FROM STDIN</code> and
+ <code class="command">COPY TO STDOUT</code>), or <code class="literal">CALLBACK</code>
+ (used for example during the initial table synchronization in
+ logical replication).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">bytes_processed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of bytes already processed by <code class="command">COPY</code> command.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">bytes_total</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Size of source file for <code class="command">COPY FROM</code> command in bytes.
+ It is set to <code class="literal">0</code> if not available.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tuples_processed</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of tuples already processed by <code class="command">COPY</code> command.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tuples_excluded</code> <code class="type">bigint</code>
+ </p>
+ <p>
+ Number of tuples not processed because they were excluded by the
+ <code class="command">WHERE</code> clause of the <code class="command">COPY</code> command.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="monitoring-locks.html" title="28.3. Viewing Locks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic-trace.html" title="28.5. Dynamic Tracing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.3. Viewing Locks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 28.5. Dynamic Tracing</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-changes.html b/doc/src/sgml/html/protocol-changes.html
new file mode 100644
index 0000000..ce309d1
--- /dev/null
+++ b/doc/src/sgml/html/protocol-changes.html
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.10. Summary of Changes since Protocol 2.0</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats" /><link rel="next" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.10. Summary of Changes since Protocol 2.0</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-CHANGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.10. Summary of Changes since Protocol 2.0</h2></div></div></div><p>
+ This section provides a quick checklist of changes, for the benefit of
+ developers trying to update existing client libraries to protocol 3.0.
+ </p><p>
+ The initial startup packet uses a flexible list-of-strings format
+ instead of a fixed format. Notice that session default values for run-time
+ parameters can now be specified directly in the startup packet. (Actually,
+ you could do that before using the <code class="literal">options</code> field, but given the
+ limited width of <code class="literal">options</code> and the lack of any way to quote
+ whitespace in the values, it wasn't a very safe technique.)
+ </p><p>
+ All messages now have a length count immediately following the message type
+ byte (except for startup packets, which have no type byte). Also note that
+ PasswordMessage now has a type byte.
+ </p><p>
+ ErrorResponse and NoticeResponse ('<code class="literal">E</code>' and '<code class="literal">N</code>')
+ messages now contain multiple fields, from which the client code can
+ assemble an error message of the desired level of verbosity. Note that
+ individual fields will typically not end with a newline, whereas the single
+ string sent in the older protocol always did.
+ </p><p>
+ The ReadyForQuery ('<code class="literal">Z</code>') message includes a transaction status
+ indicator.
+ </p><p>
+ The distinction between BinaryRow and DataRow message types is gone; the
+ single DataRow message type serves for returning data in all formats.
+ Note that the layout of DataRow has changed to make it easier to parse.
+ Also, the representation of binary values has changed: it is no longer
+ directly tied to the server's internal representation.
+ </p><p>
+ There is a new <span class="quote">“<span class="quote">extended query</span>”</span> sub-protocol, which adds the frontend
+ message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the
+ backend message types ParseComplete, BindComplete, PortalSuspended,
+ ParameterDescription, NoData, and CloseComplete. Existing clients do not
+ have to concern themselves with this sub-protocol, but making use of it
+ might allow improvements in performance or functionality.
+ </p><p>
+ <code class="command">COPY</code> data is now encapsulated into CopyData and CopyDone messages. There
+ is a well-defined way to recover from errors during <code class="command">COPY</code>. The special
+ <span class="quote">“<span class="quote"><code class="literal">\.</code></span>”</span> last line is not needed anymore, and is not sent
+ during <code class="command">COPY OUT</code>.
+ (It is still recognized as a terminator during <code class="command">COPY IN</code>, but its use is
+ deprecated and will eventually be removed.) Binary <code class="command">COPY</code> is supported.
+ The CopyInResponse and CopyOutResponse messages include fields indicating
+ the number of columns and the format of each column.
+ </p><p>
+ The layout of FunctionCall and FunctionCallResponse messages has changed.
+ FunctionCall can now support passing NULL arguments to functions. It also
+ can handle passing parameters and retrieving results in either text or
+ binary format. There is no longer any reason to consider FunctionCall a
+ potential security hole, since it does not offer direct access to internal
+ server data representations.
+ </p><p>
+ The backend sends ParameterStatus ('<code class="literal">S</code>') messages during connection
+ startup for all parameters it considers interesting to the client library.
+ Subsequently, a ParameterStatus message is sent whenever the active value
+ changes for any of these parameters.
+ </p><p>
+ The RowDescription ('<code class="literal">T</code>') message carries new table OID and column
+ number fields for each column of the described row. It also shows the format
+ code for each column.
+ </p><p>
+ The CursorResponse ('<code class="literal">P</code>') message is no longer generated by
+ the backend.
+ </p><p>
+ The NotificationResponse ('<code class="literal">A</code>') message has an additional string
+ field, which can carry a <span class="quote">“<span class="quote">payload</span>”</span> string passed
+ from the <code class="command">NOTIFY</code> event sender.
+ </p><p>
+ The EmptyQueryResponse ('<code class="literal">I</code>') message used to include an empty
+ string parameter; this has been removed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.9. Logical Replication Message Formats </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 56. PostgreSQL Coding Conventions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-error-fields.html b/doc/src/sgml/html/protocol-error-fields.html
new file mode 100644
index 0000000..ed9df3c
--- /dev/null
+++ b/doc/src/sgml/html/protocol-error-fields.html
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.8. Error and Notice Message Fields</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-message-formats.html" title="55.7. Message Formats" /><link rel="next" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.8. Error and Notice Message Fields</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-message-formats.html" title="55.7. Message Formats">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-ERROR-FIELDS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.8. Error and Notice Message Fields</h2></div></div></div><p>
+ This section describes the fields that can appear in ErrorResponse and
+ NoticeResponse messages. Each field type has a single-byte identification
+ token. Note that any given field type should appear at most once per
+ message.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">S</code></span></dt><dd><p>
+ Severity: the field contents are
+ <code class="literal">ERROR</code>, <code class="literal">FATAL</code>, or
+ <code class="literal">PANIC</code> (in an error message), or
+ <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,
+ <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message),
+ or a localized translation of one of these. Always present.
+ </p></dd><dt><span class="term"><code class="literal">V</code></span></dt><dd><p>
+ Severity: the field contents are
+ <code class="literal">ERROR</code>, <code class="literal">FATAL</code>, or
+ <code class="literal">PANIC</code> (in an error message), or
+ <code class="literal">WARNING</code>, <code class="literal">NOTICE</code>, <code class="literal">DEBUG</code>,
+ <code class="literal">INFO</code>, or <code class="literal">LOG</code> (in a notice message).
+ This is identical to the <code class="literal">S</code> field except
+ that the contents are never localized. This is present only in
+ messages generated by <span class="productname">PostgreSQL</span> versions 9.6
+ and later.
+ </p></dd><dt><span class="term"><code class="literal">C</code></span></dt><dd><p>
+ Code: the SQLSTATE code for the error (see <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>). Not localizable. Always present.
+ </p></dd><dt><span class="term"><code class="literal">M</code></span></dt><dd><p>
+ Message: the primary human-readable error message.
+ This should be accurate but terse (typically one line).
+ Always present.
+ </p></dd><dt><span class="term"><code class="literal">D</code></span></dt><dd><p>
+ Detail: an optional secondary error message carrying more
+ detail about the problem. Might run to multiple lines.
+ </p></dd><dt><span class="term"><code class="literal">H</code></span></dt><dd><p>
+ Hint: an optional suggestion what to do about the problem.
+ This is intended to differ from Detail in that it offers advice
+ (potentially inappropriate) rather than hard facts.
+ Might run to multiple lines.
+ </p></dd><dt><span class="term"><code class="literal">P</code></span></dt><dd><p>
+ Position: the field value is a decimal ASCII integer, indicating
+ an error cursor position as an index into the original query string.
+ The first character has index 1, and positions are measured in
+ characters not bytes.
+ </p></dd><dt><span class="term"><code class="literal">p</code></span></dt><dd><p>
+ Internal position: this is defined the same as the <code class="literal">P</code>
+ field, but it is used when the cursor position refers to an internally
+ generated command rather than the one submitted by the client.
+ The <code class="literal">q</code> field will always appear when this field appears.
+ </p></dd><dt><span class="term"><code class="literal">q</code></span></dt><dd><p>
+ Internal query: the text of a failed internally-generated command.
+ This could be, for example, an SQL query issued by a PL/pgSQL function.
+ </p></dd><dt><span class="term"><code class="literal">W</code></span></dt><dd><p>
+ Where: an indication of the context in which the error occurred.
+ Presently this includes a call stack traceback of active
+ procedural language functions and internally-generated queries.
+ The trace is one entry per line, most recent first.
+ </p></dd><dt><span class="term"><code class="literal">s</code></span></dt><dd><p>
+ Schema name: if the error was associated with a specific database
+ object, the name of the schema containing that object, if any.
+ </p></dd><dt><span class="term"><code class="literal">t</code></span></dt><dd><p>
+ Table name: if the error was associated with a specific table, the
+ name of the table. (Refer to the schema name field for the name of
+ the table's schema.)
+ </p></dd><dt><span class="term"><code class="literal">c</code></span></dt><dd><p>
+ Column name: if the error was associated with a specific table column,
+ the name of the column. (Refer to the schema and table name fields to
+ identify the table.)
+ </p></dd><dt><span class="term"><code class="literal">d</code></span></dt><dd><p>
+ Data type name: if the error was associated with a specific data type,
+ the name of the data type. (Refer to the schema name field for the
+ name of the data type's schema.)
+ </p></dd><dt><span class="term"><code class="literal">n</code></span></dt><dd><p>
+ Constraint name: if the error was associated with a specific
+ constraint, the name of the constraint. Refer to fields listed above
+ for the associated table or domain. (For this purpose, indexes are
+ treated as constraints, even if they weren't created with constraint
+ syntax.)
+ </p></dd><dt><span class="term"><code class="literal">F</code></span></dt><dd><p>
+ File: the file name of the source-code location where the error
+ was reported.
+ </p></dd><dt><span class="term"><code class="literal">L</code></span></dt><dd><p>
+ Line: the line number of the source-code location where the error
+ was reported.
+ </p></dd><dt><span class="term"><code class="literal">R</code></span></dt><dd><p>
+ Routine: the name of the source-code routine reporting the error.
+ </p></dd></dl></div><div class="note"><h3 class="title">Note</h3><p>
+ 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 <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>. Frontends should 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 ways. In the same
+ vein, clients should not assume that these fields denote contemporary
+ objects in the current database.
+ </p></div><p>
+ The client is responsible for formatting displayed information to meet its
+ needs; in particular it should break long lines as needed. Newline characters
+ appearing in the error message fields should be treated as paragraph breaks,
+ not line breaks.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-message-formats.html" title="55.7. Message Formats">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.7. Message Formats </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.9. Logical Replication Message Formats</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-flow.html b/doc/src/sgml/html/protocol-flow.html
new file mode 100644
index 0000000..ce94fe3
--- /dev/null
+++ b/doc/src/sgml/html/protocol-flow.html
@@ -0,0 +1,975 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.2. Message Flow</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-overview.html" title="55.1. Overview" /><link rel="next" href="sasl-authentication.html" title="55.3. SASL Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.2. Message Flow</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-overview.html" title="55.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sasl-authentication.html" title="55.3. SASL Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-FLOW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.2. Message Flow</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.3">55.2.1. Start-up</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.4">55.2.2. Simple Query</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY">55.2.3. Extended Query</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-FLOW-PIPELINING">55.2.4. Pipelining</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.7">55.2.5. Function Call</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-COPY">55.2.6. COPY Operations</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-ASYNC">55.2.7. Asynchronous Operations</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.10">55.2.8. Canceling Requests in Progress</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.11">55.2.9. Termination</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.12">55.2.10. <acronym class="acronym">SSL</acronym> Session Encryption</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.13">55.2.11. <acronym class="acronym">GSSAPI</acronym> Session Encryption</a></span></dt></dl></div><p>
+ This section describes the message flow and the semantics of each
+ message type. (Details of the exact representation of each message
+ appear in <a class="xref" href="protocol-message-formats.html" title="55.7. Message Formats">Section 55.7</a>.) There are
+ several different sub-protocols depending on the state of the
+ connection: start-up, query, function call,
+ <code class="command">COPY</code>, and termination. There are also special
+ provisions for asynchronous operations (including notification
+ responses and command cancellation), which can occur at any time
+ after the start-up phase.
+ </p><div class="sect2" id="id-1.10.6.7.3"><div class="titlepage"><div><div><h3 class="title">55.2.1. Start-up</h3></div></div></div><p>
+ To begin a session, a frontend opens a connection to the server and sends
+ a startup message. This message includes the names of the user and of the
+ database the user wants to connect to; it also identifies the particular
+ protocol version to be used. (Optionally, the startup message can include
+ additional settings for run-time parameters.)
+ The server then uses this information and
+ the contents of its configuration files (such as
+ <code class="filename">pg_hba.conf</code>) to determine
+ whether the connection is provisionally acceptable, and what additional
+ authentication is required (if any).
+ </p><p>
+ The server then sends an appropriate authentication request message,
+ to which the frontend must reply with an appropriate authentication
+ response message (such as a password).
+ For all authentication methods except GSSAPI, SSPI and SASL, there is at
+ most one request and one response. In some methods, no response
+ at all is needed from the frontend, and so no authentication request
+ occurs. For GSSAPI, SSPI and SASL, multiple exchanges of packets may be
+ needed to complete the authentication.
+ </p><p>
+ The authentication cycle ends with the server either rejecting the
+ connection attempt (ErrorResponse), or sending AuthenticationOk.
+ </p><p>
+ The possible messages from the server in this phase are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">ErrorResponse</span></dt><dd><p>
+ The connection attempt has been rejected.
+ The server then immediately closes the connection.
+ </p></dd><dt><span class="term">AuthenticationOk</span></dt><dd><p>
+ The authentication exchange is successfully completed.
+ </p></dd><dt><span class="term">AuthenticationKerberosV5</span></dt><dd><p>
+ The frontend must now take part in a Kerberos V5
+ authentication dialog (not described here, part of the
+ Kerberos specification) with the server. If this is
+ successful, the server responds with an AuthenticationOk,
+ otherwise it responds with an ErrorResponse. This is no
+ longer supported.
+ </p></dd><dt><span class="term">AuthenticationCleartextPassword</span></dt><dd><p>
+ The frontend must now send a PasswordMessage containing the
+ password in clear-text form. If
+ this is the correct password, the server responds with an
+ AuthenticationOk, otherwise it responds with an ErrorResponse.
+ </p></dd><dt><span class="term">AuthenticationMD5Password</span></dt><dd><p>
+ The frontend must now send a PasswordMessage containing the
+ password (with user name) encrypted via MD5, then encrypted
+ again using the 4-byte random salt specified in the
+ AuthenticationMD5Password message. If this is the correct
+ password, the server responds with an AuthenticationOk,
+ otherwise it responds with an ErrorResponse. The actual
+ PasswordMessage can be computed in SQL as <code class="literal">concat('md5',
+ md5(concat(md5(concat(password, username)), random-salt)))</code>.
+ (Keep in mind the <code class="function">md5()</code> function returns its
+ result as a hex string.)
+ </p></dd><dt><span class="term">AuthenticationSCMCredential</span></dt><dd><p>
+ This response is only possible for local Unix-domain connections
+ on platforms that support SCM credential messages. The frontend
+ must issue an SCM credential message and then send a single data
+ byte. (The contents of the data byte are uninteresting; it's
+ only used to ensure that the server waits long enough to receive
+ the credential message.) If the credential is acceptable,
+ the server responds with an
+ AuthenticationOk, otherwise it responds with an ErrorResponse.
+ (This message type is only issued by pre-9.1 servers. It may
+ eventually be removed from the protocol specification.)
+ </p></dd><dt><span class="term">AuthenticationGSS</span></dt><dd><p>
+ The frontend must now initiate a GSSAPI negotiation. The frontend
+ will send a GSSResponse message with the first part of the GSSAPI
+ data stream in response to this. If further messages are needed,
+ the server will respond with AuthenticationGSSContinue.
+ </p></dd><dt><span class="term">AuthenticationSSPI</span></dt><dd><p>
+ The frontend must now initiate an SSPI negotiation. The frontend
+ will send a GSSResponse with the first part of the SSPI
+ data stream in response to this. If further messages are needed,
+ the server will respond with AuthenticationGSSContinue.
+ </p></dd><dt><span class="term">AuthenticationGSSContinue</span></dt><dd><p>
+ This message contains the response data from the previous step
+ of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI
+ or a previous AuthenticationGSSContinue). If the GSSAPI
+ or SSPI data in this message
+ indicates more data is needed to complete the authentication,
+ the frontend must send that data as another GSSResponse message. If
+ GSSAPI or SSPI authentication is completed by this message, the server
+ will next send AuthenticationOk to indicate successful authentication
+ or ErrorResponse to indicate failure.
+ </p></dd><dt><span class="term">AuthenticationSASL</span></dt><dd><p>
+ The frontend must now initiate a SASL negotiation, using one of the
+ SASL mechanisms listed in the message. The frontend will send a
+ SASLInitialResponse with the name of the selected mechanism, and the
+ first part of the SASL data stream in response to this. If further
+ messages are needed, the server will respond with
+ AuthenticationSASLContinue. See <a class="xref" href="sasl-authentication.html" title="55.3. SASL Authentication">Section 55.3</a>
+ for details.
+ </p></dd><dt><span class="term">AuthenticationSASLContinue</span></dt><dd><p>
+ This message contains challenge data from the previous step of SASL
+ negotiation (AuthenticationSASL, or a previous
+ AuthenticationSASLContinue). The frontend must respond with a
+ SASLResponse message.
+ </p></dd><dt><span class="term">AuthenticationSASLFinal</span></dt><dd><p>
+ SASL authentication has completed with additional mechanism-specific
+ data for the client. The server will next send AuthenticationOk to
+ indicate successful authentication, or an ErrorResponse to indicate
+ failure. This message is sent only if the SASL mechanism specifies
+ additional data to be sent from server to client at completion.
+ </p></dd><dt><span class="term">NegotiateProtocolVersion</span></dt><dd><p>
+ The server does not support the minor protocol version requested
+ by the client, but does support an earlier version of the protocol;
+ this message indicates the highest supported minor version. This
+ message will also be sent if the client requested unsupported protocol
+ options (i.e., beginning with <code class="literal">_pq_.</code>) in the
+ startup packet. This message will be followed by an ErrorResponse or
+ a message indicating the success or failure of authentication.
+ </p></dd></dl></div><p>
+ </p><p>
+ If the frontend does not support the authentication method
+ requested by the server, then it should immediately close the
+ connection.
+ </p><p>
+ After having received AuthenticationOk, the frontend must wait
+ for further messages from the server. In this phase a backend process
+ is being started, and the frontend is just an interested bystander.
+ It is still possible for the startup attempt
+ to fail (ErrorResponse) or the server to decline support for the requested
+ minor protocol version (NegotiateProtocolVersion), but in the normal case
+ the backend will send some ParameterStatus messages, BackendKeyData, and
+ finally ReadyForQuery.
+ </p><p>
+ During this phase the backend will attempt to apply any additional
+ run-time parameter settings that were given in the startup message.
+ If successful, these values become session defaults. An error causes
+ ErrorResponse and exit.
+ </p><p>
+ The possible messages from the backend in this phase are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">BackendKeyData</span></dt><dd><p>
+ This message provides secret-key data that the frontend must
+ save if it wants to be able to issue cancel requests later.
+ The frontend should not respond to this message, but should
+ continue listening for a ReadyForQuery message.
+ </p></dd><dt><span class="term">ParameterStatus</span></dt><dd><p>
+ This message informs the frontend about the current (initial)
+ setting of backend parameters, such as <a class="xref" href="runtime-config-client.html#GUC-CLIENT-ENCODING">client_encoding</a> or <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a>.
+ The frontend can ignore this message, or record the settings
+ for its future use; see <a class="xref" href="protocol-flow.html#PROTOCOL-ASYNC" title="55.2.7. Asynchronous Operations">Section 55.2.7</a> for
+ more details. The frontend should not respond to this
+ message, but should continue listening for a ReadyForQuery
+ message.
+ </p></dd><dt><span class="term">ReadyForQuery</span></dt><dd><p>
+ Start-up is completed. The frontend can now issue commands.
+ </p></dd><dt><span class="term">ErrorResponse</span></dt><dd><p>
+ Start-up failed. The connection is closed after sending this
+ message.
+ </p></dd><dt><span class="term">NoticeResponse</span></dt><dd><p>
+ A warning message has been issued. The frontend should
+ display the message but continue listening for ReadyForQuery
+ or ErrorResponse.
+ </p></dd></dl></div><p>
+ </p><p>
+ The ReadyForQuery message is the same one that the backend will
+ issue after each command cycle. Depending on the coding needs of
+ the frontend, it is reasonable to consider ReadyForQuery as
+ starting a command cycle, or to consider ReadyForQuery as ending the
+ start-up phase and each subsequent command cycle.
+ </p></div><div class="sect2" id="id-1.10.6.7.4"><div class="titlepage"><div><div><h3 class="title">55.2.2. Simple Query</h3></div></div></div><p>
+ A simple query cycle is initiated by the frontend sending a Query message
+ to the backend. The message includes an SQL command (or commands)
+ expressed as a text string.
+ The backend then sends one or more response
+ messages depending on the contents of the query command string,
+ and finally a ReadyForQuery response message. ReadyForQuery
+ informs the frontend that it can safely send a new command.
+ (It is not actually necessary for the frontend to wait for
+ ReadyForQuery before issuing another command, but the frontend must
+ then take responsibility for figuring out what happens if the earlier
+ command fails and already-issued later commands succeed.)
+ </p><p>
+ The possible response messages from the backend are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">CommandComplete</span></dt><dd><p>
+ An SQL command completed normally.
+ </p></dd><dt><span class="term">CopyInResponse</span></dt><dd><p>
+ The backend is ready to copy data from the frontend to a
+ table; see <a class="xref" href="protocol-flow.html#PROTOCOL-COPY" title="55.2.6. COPY Operations">Section 55.2.6</a>.
+ </p></dd><dt><span class="term">CopyOutResponse</span></dt><dd><p>
+ The backend is ready to copy data from a table to the
+ frontend; see <a class="xref" href="protocol-flow.html#PROTOCOL-COPY" title="55.2.6. COPY Operations">Section 55.2.6</a>.
+ </p></dd><dt><span class="term">RowDescription</span></dt><dd><p>
+ Indicates that rows are about to be returned in response to
+ a <code class="command">SELECT</code>, <code class="command">FETCH</code>, etc. query.
+ The contents of this message describe the column layout of the rows.
+ This will be followed by a DataRow message for each row being returned
+ to the frontend.
+ </p></dd><dt><span class="term">DataRow</span></dt><dd><p>
+ One of the set of rows returned by
+ a <code class="command">SELECT</code>, <code class="command">FETCH</code>, etc. query.
+ </p></dd><dt><span class="term">EmptyQueryResponse</span></dt><dd><p>
+ An empty query string was recognized.
+ </p></dd><dt><span class="term">ErrorResponse</span></dt><dd><p>
+ An error has occurred.
+ </p></dd><dt><span class="term">ReadyForQuery</span></dt><dd><p>
+ Processing of the query string is complete. A separate
+ message is sent to indicate this because the query string might
+ contain multiple SQL commands. (CommandComplete marks the
+ end of processing one SQL command, not the whole string.)
+ ReadyForQuery will always be sent, whether processing
+ terminates successfully or with an error.
+ </p></dd><dt><span class="term">NoticeResponse</span></dt><dd><p>
+ A warning message has been issued in relation to the query.
+ Notices are in addition to other responses, i.e., the backend
+ will continue processing the command.
+ </p></dd></dl></div><p>
+ </p><p>
+ The response to a <code class="command">SELECT</code> query (or other queries that
+ return row sets, such as <code class="command">EXPLAIN</code> or <code class="command">SHOW</code>)
+ normally consists of RowDescription, zero or more
+ DataRow messages, and then CommandComplete.
+ <code class="command">COPY</code> to or from the frontend invokes special protocol
+ as described in <a class="xref" href="protocol-flow.html#PROTOCOL-COPY" title="55.2.6. COPY Operations">Section 55.2.6</a>.
+ All other query types normally produce only
+ a CommandComplete message.
+ </p><p>
+ Since a query string could contain several queries (separated by
+ semicolons), there might be several such response sequences before the
+ backend finishes processing the query string. ReadyForQuery is issued
+ when the entire string has been processed and the backend is ready to
+ accept a new query string.
+ </p><p>
+ If a completely empty (no contents other than whitespace) query string
+ is received, the response is EmptyQueryResponse followed by ReadyForQuery.
+ </p><p>
+ In the event of an error, ErrorResponse is issued followed by
+ ReadyForQuery. All further processing of the query string is aborted by
+ ErrorResponse (even if more queries remained in it). Note that this
+ might occur partway through the sequence of messages generated by an
+ individual query.
+ </p><p>
+ In simple Query mode, the format of retrieved values is always text,
+ except when the given command is a <code class="command">FETCH</code> from a cursor
+ declared with the <code class="literal">BINARY</code> option. In that case, the
+ retrieved values are in binary format. The format codes given in
+ the RowDescription message tell which format is being used.
+ </p><p>
+ A frontend must be prepared to accept ErrorResponse and
+ NoticeResponse messages whenever it is expecting any other type of
+ message. See also <a class="xref" href="protocol-flow.html#PROTOCOL-ASYNC" title="55.2.7. Asynchronous Operations">Section 55.2.7</a> concerning messages
+ that the backend might generate due to outside events.
+ </p><p>
+ Recommended practice is to code frontends in a state-machine style
+ that will accept any message type at any time that it could make sense,
+ rather than wiring in assumptions about the exact sequence of messages.
+ </p><div class="sect3" id="PROTOCOL-FLOW-MULTI-STATEMENT"><div class="titlepage"><div><div><h4 class="title">55.2.2.1. Multiple Statements in a Simple Query</h4></div></div></div><p>
+ When a simple Query message contains more than one SQL statement
+ (separated by semicolons), those statements are executed as a single
+ transaction, unless explicit transaction control commands are included
+ to force a different behavior. For example, if the message contains
+</p><pre class="programlisting">
+INSERT INTO mytable VALUES(1);
+SELECT 1/0;
+INSERT INTO mytable VALUES(2);
+</pre><p>
+ then the divide-by-zero failure in the <code class="command">SELECT</code> will force
+ rollback of the first <code class="command">INSERT</code>. Furthermore, because
+ execution of the message is abandoned at the first error, the second
+ <code class="command">INSERT</code> is never attempted at all.
+ </p><p>
+ If instead the message contains
+</p><pre class="programlisting">
+BEGIN;
+INSERT INTO mytable VALUES(1);
+COMMIT;
+INSERT INTO mytable VALUES(2);
+SELECT 1/0;
+</pre><p>
+ then the first <code class="command">INSERT</code> is committed by the
+ explicit <code class="command">COMMIT</code> command. The second <code class="command">INSERT</code>
+ and the <code class="command">SELECT</code> are still treated as a single transaction,
+ so that the divide-by-zero failure will roll back the
+ second <code class="command">INSERT</code>, but not the first one.
+ </p><p>
+ This behavior is implemented by running the statements in a
+ multi-statement Query message in an <em class="firstterm">implicit transaction
+ block</em> unless there is some explicit transaction block for them to
+ run in. The main difference between an implicit transaction block and
+ a regular one is that an implicit block is closed automatically at the
+ end of the Query message, either by an implicit commit if there was no
+ error, or an implicit rollback if there was an error. This is similar
+ to the implicit commit or rollback that happens for a statement
+ executed by itself (when not in a transaction block).
+ </p><p>
+ If the session is already in a transaction block, as a result of
+ a <code class="command">BEGIN</code> in some previous message, then the Query message
+ simply continues that transaction block, whether the message contains
+ one statement or several. However, if the Query message contains
+ a <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code> closing the existing
+ transaction block, then any following statements are executed in an
+ implicit transaction block.
+ Conversely, if a <code class="command">BEGIN</code> appears in a multi-statement Query
+ message, then it starts a regular transaction block that will only be
+ terminated by an explicit <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code>,
+ whether that appears in this Query message or a later one.
+ If the <code class="command">BEGIN</code> follows some statements that were executed as
+ an implicit transaction block, those statements are not immediately
+ committed; in effect, they are retroactively included into the new
+ regular transaction block.
+ </p><p>
+ A <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code> appearing in an implicit
+ transaction block is executed as normal, closing the implicit block;
+ however, a warning will be issued since a <code class="command">COMMIT</code>
+ or <code class="command">ROLLBACK</code> without a previous <code class="command">BEGIN</code> might
+ represent a mistake. If more statements follow, a new implicit
+ transaction block will be started for them.
+ </p><p>
+ Savepoints are not allowed in an implicit transaction block, since
+ they would conflict with the behavior of automatically closing the
+ block upon any error.
+ </p><p>
+ Remember that, regardless of any transaction control commands that may
+ be present, execution of the Query message stops at the first error.
+ Thus for example given
+</p><pre class="programlisting">
+BEGIN;
+SELECT 1/0;
+ROLLBACK;
+</pre><p>
+ in a single Query message, the session will be left inside a failed
+ regular transaction block, since the <code class="command">ROLLBACK</code> is not
+ reached after the divide-by-zero error. Another <code class="command">ROLLBACK</code>
+ will be needed to restore the session to a usable state.
+ </p><p>
+ Another behavior of note is that initial lexical and syntactic
+ analysis is done on the entire query string before any of it is
+ executed. Thus simple errors (such as a misspelled keyword) in later
+ statements can prevent execution of any of the statements. This
+ is normally invisible to users since the statements would all roll
+ back anyway when done as an implicit transaction block. However,
+ it can be visible when attempting to do multiple transactions within a
+ multi-statement Query. For instance, if a typo turned our previous
+ example into
+</p><pre class="programlisting">
+BEGIN;
+INSERT INTO mytable VALUES(1);
+COMMIT;
+INSERT INTO mytable VALUES(2);
+SELCT 1/0;
+</pre><p>
+ then none of the statements would get run, resulting in the visible
+ difference that the first <code class="command">INSERT</code> is not committed.
+ Errors detected at semantic analysis or later, such as a misspelled
+ table or column name, do not have this effect.
+ </p></div></div><div class="sect2" id="PROTOCOL-FLOW-EXT-QUERY"><div class="titlepage"><div><div><h3 class="title">55.2.3. Extended Query</h3></div></div></div><p>
+ The extended query protocol breaks down the above-described simple
+ query protocol into multiple steps. The results of preparatory
+ steps can be re-used multiple times for improved efficiency.
+ Furthermore, additional features are available, such as the possibility
+ of supplying data values as separate parameters instead of having to
+ insert them directly into a query string.
+ </p><p>
+ In the extended protocol, the frontend first sends a Parse message,
+ which contains a textual query string, optionally some information
+ about data types of parameter placeholders, and the
+ name of a destination prepared-statement object (an empty string
+ selects the unnamed prepared statement). The response is
+ either ParseComplete or ErrorResponse. Parameter data types can be
+ specified by OID; if not given, the parser attempts to infer the
+ data types in the same way as it would do for untyped literal string
+ constants.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A parameter data type can be left unspecified by setting it to zero,
+ or by making the array of parameter type OIDs shorter than the
+ number of parameter symbols (<code class="literal">$</code><em class="replaceable"><code>n</code></em>)
+ used in the query string. Another special case is that a parameter's
+ type can be specified as <code class="type">void</code> (that is, the OID of the
+ <code class="type">void</code> pseudo-type). This is meant to allow parameter symbols
+ to be used for function parameters that are actually OUT parameters.
+ Ordinarily there is no context in which a <code class="type">void</code> parameter
+ could be used, but if such a parameter symbol appears in a function's
+ parameter list, it is effectively ignored. For example, a function
+ call such as <code class="literal">foo($1,$2,$3,$4)</code> could match a function with
+ two IN and two OUT arguments, if <code class="literal">$3</code> and <code class="literal">$4</code>
+ are specified as having type <code class="type">void</code>.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ The query string contained in a Parse message cannot include more
+ than one SQL statement; else a syntax error is reported. This
+ restriction does not exist in the simple-query protocol, but it
+ does exist in the extended protocol, because allowing prepared
+ statements or portals to contain multiple commands would complicate
+ the protocol unduly.
+ </p></div><p>
+ If successfully created, a named prepared-statement object lasts till
+ the end of the current session, unless explicitly destroyed. An unnamed
+ prepared statement lasts only until the next Parse statement specifying
+ the unnamed statement as destination is issued. (Note that a simple
+ Query message also destroys the unnamed statement.) Named prepared
+ statements must be explicitly closed before they can be redefined by
+ another Parse message, but this is not required for the unnamed statement.
+ Named prepared statements can also be created and accessed at the SQL
+ command level, using <code class="command">PREPARE</code> and <code class="command">EXECUTE</code>.
+ </p><p>
+ Once a prepared statement exists, it can be readied for execution using a
+ Bind message. The Bind message gives the name of the source prepared
+ statement (empty string denotes the unnamed prepared statement), the name
+ of the destination portal (empty string denotes the unnamed portal), and
+ the values to use for any parameter placeholders present in the prepared
+ statement. The
+ supplied parameter set must match those needed by the prepared statement.
+ (If you declared any <code class="type">void</code> parameters in the Parse message,
+ pass NULL values for them in the Bind message.)
+ Bind also specifies the format to use for any data returned
+ by the query; the format can be specified overall, or per-column.
+ The response is either BindComplete or ErrorResponse.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The choice between text and binary output is determined by the format
+ codes given in Bind, regardless of the SQL command involved. The
+ <code class="literal">BINARY</code> attribute in cursor declarations is irrelevant when
+ using extended query protocol.
+ </p></div><p>
+ Query planning typically occurs when the Bind message is processed.
+ If the prepared statement has no parameters, or is executed repeatedly,
+ the server might save the created plan and re-use it during subsequent
+ Bind messages for the same prepared statement. However, it will do so
+ only if it finds that a generic plan can be created that is not much
+ less efficient than a plan that depends on the specific parameter values
+ supplied. This happens transparently so far as the protocol is concerned.
+ </p><p>
+ If successfully created, a named portal object lasts till the end of the
+ current transaction, unless explicitly destroyed. An unnamed portal is
+ destroyed at the end of the transaction, or as soon as the next Bind
+ statement specifying the unnamed portal as destination is issued. (Note
+ that a simple Query message also destroys the unnamed portal.) Named
+ portals must be explicitly closed before they can be redefined by another
+ Bind message, but this is not required for the unnamed portal.
+ Named portals can also be created and accessed at the SQL
+ command level, using <code class="command">DECLARE CURSOR</code> and <code class="command">FETCH</code>.
+ </p><p>
+ Once a portal exists, it can be executed using an Execute message.
+ The Execute message specifies the portal name (empty string denotes the
+ unnamed portal) and
+ a maximum result-row count (zero meaning <span class="quote">“<span class="quote">fetch all rows</span>”</span>).
+ The result-row count is only meaningful for portals
+ containing commands that return row sets; in other cases the command is
+ always executed to completion, and the row count is ignored.
+ The possible
+ responses to Execute are the same as those described above for queries
+ issued via simple query protocol, except that Execute doesn't cause
+ ReadyForQuery or RowDescription to be issued.
+ </p><p>
+ If Execute terminates before completing the execution of a portal
+ (due to reaching a nonzero result-row count), it will send a
+ PortalSuspended message; the appearance of this message tells the frontend
+ that another Execute should be issued against the same portal to
+ complete the operation. The CommandComplete message indicating
+ completion of the source SQL command is not sent until
+ the portal's execution is completed. Therefore, an Execute phase is
+ always terminated by the appearance of exactly one of these messages:
+ CommandComplete, EmptyQueryResponse (if the portal was created from
+ an empty query string), ErrorResponse, or PortalSuspended.
+ </p><p>
+ At completion of each series of extended-query messages, the frontend
+ should issue a Sync message. This parameterless message causes the
+ backend to close the current transaction if it's not inside a
+ <code class="command">BEGIN</code>/<code class="command">COMMIT</code> transaction block (<span class="quote">“<span class="quote">close</span>”</span>
+ meaning to commit if no error, or roll back if error). Then a
+ ReadyForQuery response is issued. The purpose of Sync is to provide
+ a resynchronization point for error recovery. When an error is detected
+ while processing any extended-query message, the backend issues
+ ErrorResponse, then reads and discards messages until a Sync is reached,
+ then issues ReadyForQuery and returns to normal message processing.
+ (But note that no skipping occurs if an error is detected
+ <span class="emphasis"><em>while</em></span> processing Sync — this ensures that there is one
+ and only one ReadyForQuery sent for each Sync.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Sync does not cause a transaction block opened with <code class="command">BEGIN</code>
+ to be closed. It is possible to detect this situation since the
+ ReadyForQuery message includes transaction status information.
+ </p></div><p>
+ In addition to these fundamental, required operations, there are several
+ optional operations that can be used with extended-query protocol.
+ </p><p>
+ The Describe message (portal variant) specifies the name of an existing
+ portal (or an empty string for the unnamed portal). The response is a
+ RowDescription message describing the rows that will be returned by
+ executing the portal; or a NoData message if the portal does not contain a
+ query that will return rows; or ErrorResponse if there is no such portal.
+ </p><p>
+ The Describe message (statement variant) specifies the name of an existing
+ prepared statement (or an empty string for the unnamed prepared
+ statement). The response is a ParameterDescription message describing the
+ parameters needed by the statement, followed by a RowDescription message
+ describing the rows that will be returned when the statement is eventually
+ executed (or a NoData message if the statement will not return rows).
+ ErrorResponse is issued if there is no such prepared statement. Note that
+ since Bind has not yet been issued, the formats to be used for returned
+ columns are not yet known to the backend; the format code fields in the
+ RowDescription message will be zeroes in this case.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ In most scenarios the frontend should issue one or the other variant
+ of Describe before issuing Execute, to ensure that it knows how to
+ interpret the results it will get back.
+ </p></div><p>
+ The Close message closes an existing prepared statement or portal
+ and releases resources. It is not an error to issue Close against
+ a nonexistent statement or portal name. The response is normally
+ CloseComplete, but could be ErrorResponse if some difficulty is
+ encountered while releasing resources. Note that closing a prepared
+ statement implicitly closes any open portals that were constructed
+ from that statement.
+ </p><p>
+ The Flush message does not cause any specific output to be generated,
+ but forces the backend to deliver any data pending in its output
+ buffers. A Flush must be sent after any extended-query command except
+ Sync, if the frontend wishes to examine the results of that command before
+ issuing more commands. Without Flush, messages returned by the backend
+ will be combined into the minimum possible number of packets to minimize
+ network overhead.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The simple Query message is approximately equivalent to the series Parse,
+ Bind, portal Describe, Execute, Close, Sync, using the unnamed prepared
+ statement and portal objects and no parameters. One difference is that
+ it will accept multiple SQL statements in the query string, automatically
+ performing the bind/describe/execute sequence for each one in succession.
+ Another difference is that it will not return ParseComplete, BindComplete,
+ CloseComplete, or NoData messages.
+ </p></div></div><div class="sect2" id="PROTOCOL-FLOW-PIPELINING"><div class="titlepage"><div><div><h3 class="title">55.2.4. Pipelining</h3></div></div></div><a id="id-1.10.6.7.6.2" class="indexterm"></a><p>
+ Use of the extended query protocol
+ allows <em class="firstterm">pipelining</em>, which means sending a series
+ of queries without waiting for earlier ones to complete. This reduces
+ the number of network round trips needed to complete a given series of
+ operations. However, the user must carefully consider the required
+ behavior if one of the steps fails, since later queries will already
+ be in flight to the server.
+ </p><p>
+ One way to deal with that is to make the whole query series be a
+ single transaction, that is wrap it in <code class="command">BEGIN</code> ...
+ <code class="command">COMMIT</code>. However, this does not help if one wishes
+ for some of the commands to commit independently of others.
+ </p><p>
+ The extended query protocol provides another way to manage this
+ concern, which is to omit sending Sync messages between steps that
+ are dependent. Since, after an error, the backend will skip command
+ messages until it finds Sync, this allows later commands in a pipeline
+ to be skipped automatically when an earlier one fails, without the
+ client having to manage that explicitly with <code class="command">BEGIN</code>
+ and <code class="command">COMMIT</code>. Independently-committable segments
+ of the pipeline can be separated by Sync messages.
+ </p><p>
+ If the client has not issued an explicit <code class="command">BEGIN</code>,
+ then each Sync ordinarily causes an implicit <code class="command">COMMIT</code>
+ if the preceding step(s) succeeded, or an
+ implicit <code class="command">ROLLBACK</code> if they failed. However, there
+ are a few DDL commands (such as <code class="command">CREATE DATABASE</code>)
+ that cannot be executed inside a transaction block. If one of
+ these is executed in a pipeline, it will fail unless it is the first
+ command in the pipeline. Furthermore, upon success it will force an
+ immediate commit to preserve database consistency. Thus a Sync
+ immediately following one of these commands has no effect except to
+ respond with ReadyForQuery.
+ </p><p>
+ When using this method, completion of the pipeline must be determined
+ by counting ReadyForQuery messages and waiting for that to reach the
+ number of Syncs sent. Counting command completion responses is
+ unreliable, since some of the commands may be skipped and thus not
+ produce a completion message.
+ </p></div><div class="sect2" id="id-1.10.6.7.7"><div class="titlepage"><div><div><h3 class="title">55.2.5. Function Call</h3></div></div></div><p>
+ The Function Call sub-protocol allows the client to request a direct
+ call of any function that exists in the database's
+ <code class="structname">pg_proc</code> system catalog. The client must have
+ execute permission for the function.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The Function Call sub-protocol is a legacy feature that is probably best
+ avoided in new code. Similar results can be accomplished by setting up
+ a prepared statement that does <code class="literal">SELECT function($1, ...)</code>.
+ The Function Call cycle can then be replaced with Bind/Execute.
+ </p></div><p>
+ A Function Call cycle is initiated by the frontend sending a
+ FunctionCall message to the backend. The backend then sends one
+ or more response messages depending on the results of the function
+ call, and finally a ReadyForQuery response message. ReadyForQuery
+ informs the frontend that it can safely send a new query or
+ function call.
+ </p><p>
+ The possible response messages from the backend are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">ErrorResponse</span></dt><dd><p>
+ An error has occurred.
+ </p></dd><dt><span class="term">FunctionCallResponse</span></dt><dd><p>
+ The function call was completed and returned the result given
+ in the message.
+ (Note that the Function Call protocol can only handle a single
+ scalar result, not a row type or set of results.)
+ </p></dd><dt><span class="term">ReadyForQuery</span></dt><dd><p>
+ Processing of the function call is complete. ReadyForQuery
+ will always be sent, whether processing terminates
+ successfully or with an error.
+ </p></dd><dt><span class="term">NoticeResponse</span></dt><dd><p>
+ A warning message has been issued in relation to the function
+ call. Notices are in addition to other responses, i.e., the
+ backend will continue processing the command.
+ </p></dd></dl></div><p>
+ </p></div><div class="sect2" id="PROTOCOL-COPY"><div class="titlepage"><div><div><h3 class="title">55.2.6. COPY Operations</h3></div></div></div><p>
+ The <code class="command">COPY</code> command allows high-speed bulk data transfer
+ to or from the server. Copy-in and copy-out operations each switch
+ the connection into a distinct sub-protocol, which lasts until the
+ operation is completed.
+ </p><p>
+ Copy-in mode (data transfer to the server) is initiated when the
+ backend executes a <code class="command">COPY FROM STDIN</code> SQL statement. The backend
+ sends a CopyInResponse message to the frontend. The frontend should
+ then send zero or more CopyData messages, forming a stream of input
+ data. (The message boundaries are not required to have anything to do
+ with row boundaries, although that is often a reasonable choice.)
+ The frontend can terminate the copy-in mode by sending either a CopyDone
+ message (allowing successful termination) or a CopyFail message (which
+ will cause the <code class="command">COPY</code> SQL statement to fail with an
+ error). The backend then reverts to the command-processing mode it was
+ in before the <code class="command">COPY</code> started, which will be either simple or
+ extended query protocol. It will next send either CommandComplete
+ (if successful) or ErrorResponse (if not).
+ </p><p>
+ In the event of a backend-detected error during copy-in mode (including
+ receipt of a CopyFail message), the backend will issue an ErrorResponse
+ message. If the <code class="command">COPY</code> command was issued via an extended-query
+ message, the backend will now discard frontend messages until a Sync
+ message is received, then it will issue ReadyForQuery and return to normal
+ processing. If the <code class="command">COPY</code> command was issued in a simple
+ Query message, the rest of that message is discarded and ReadyForQuery
+ is issued. In either case, any subsequent CopyData, CopyDone, or CopyFail
+ messages issued by the frontend will simply be dropped.
+ </p><p>
+ The backend will ignore Flush and Sync messages received during copy-in
+ mode. Receipt of any other non-copy message type constitutes an error
+ that will abort the copy-in state as described above. (The exception for
+ Flush and Sync is for the convenience of client libraries that always
+ send Flush or Sync after an Execute message, without checking whether
+ the command to be executed is a <code class="command">COPY FROM STDIN</code>.)
+ </p><p>
+ Copy-out mode (data transfer from the server) is initiated when the
+ backend executes a <code class="command">COPY TO STDOUT</code> SQL statement. The backend
+ sends a CopyOutResponse message to the frontend, followed by
+ zero or more CopyData messages (always one per row), followed by CopyDone.
+ The backend then reverts to the command-processing mode it was
+ in before the <code class="command">COPY</code> started, and sends CommandComplete.
+ The frontend cannot abort the transfer (except by closing the connection
+ or issuing a Cancel request),
+ but it can discard unwanted CopyData and CopyDone messages.
+ </p><p>
+ In the event of a backend-detected error during copy-out mode,
+ the backend will issue an ErrorResponse message and revert to normal
+ processing. The frontend should treat receipt of ErrorResponse as
+ terminating the copy-out mode.
+ </p><p>
+ It is possible for NoticeResponse and ParameterStatus messages to be
+ interspersed between CopyData messages; frontends must handle these cases,
+ and should be prepared for other asynchronous message types as well (see
+ <a class="xref" href="protocol-flow.html#PROTOCOL-ASYNC" title="55.2.7. Asynchronous Operations">Section 55.2.7</a>). Otherwise, any message type other than
+ CopyData or CopyDone may be treated as terminating copy-out mode.
+ </p><p>
+ There is another Copy-related mode called copy-both, which allows
+ high-speed bulk data transfer to <span class="emphasis"><em>and</em></span> from the server.
+ Copy-both mode is initiated when a backend in walsender mode
+ executes a <code class="command">START_REPLICATION</code> statement. The
+ backend sends a CopyBothResponse message to the frontend. Both
+ the backend and the frontend may then send CopyData messages
+ until either end sends a CopyDone message. After the client
+ sends a CopyDone message, the connection goes from copy-both mode to
+ copy-out mode, and the client may not send any more CopyData messages.
+ Similarly, when the server sends a CopyDone message, the connection
+ goes into copy-in mode, and the server may not send any more CopyData
+ messages. After both sides have sent a CopyDone message, the copy mode
+ is terminated, and the backend reverts to the command-processing mode.
+ In the event of a backend-detected error during copy-both mode,
+ the backend will issue an ErrorResponse message, discard frontend messages
+ until a Sync message is received, and then issue ReadyForQuery and return
+ to normal processing. The frontend should treat receipt of ErrorResponse
+ as terminating the copy in both directions; no CopyDone should be sent
+ in this case. See <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> for more
+ information on the subprotocol transmitted over copy-both mode.
+ </p><p>
+ The CopyInResponse, CopyOutResponse and CopyBothResponse messages
+ include fields that inform the frontend of the number of columns
+ per row and the format codes being used for each column. (As of
+ the present implementation, all columns in a given <code class="command">COPY</code>
+ operation will use the same format, but the message design does not
+ assume this.)
+ </p></div><div class="sect2" id="PROTOCOL-ASYNC"><div class="titlepage"><div><div><h3 class="title">55.2.7. Asynchronous Operations</h3></div></div></div><p>
+ There are several cases in which the backend will send messages that
+ are not specifically prompted by the frontend's command stream.
+ Frontends must be prepared to deal with these messages at any time,
+ even when not engaged in a query.
+ At minimum, one should check for these cases before beginning to
+ read a query response.
+ </p><p>
+ It is possible for NoticeResponse messages to be generated due to
+ outside activity; for example, if the database administrator commands
+ a <span class="quote">“<span class="quote">fast</span>”</span> database shutdown, the backend will send a NoticeResponse
+ indicating this fact before closing the connection. Accordingly,
+ frontends should always be prepared to accept and display NoticeResponse
+ messages, even when the connection is nominally idle.
+ </p><p>
+ ParameterStatus messages will be generated whenever the active
+ value changes for any of the parameters the backend believes the
+ frontend should know about. Most commonly this occurs in response
+ to a <code class="command">SET</code> SQL command executed by the frontend, and
+ this case is effectively synchronous — but it is also possible
+ for parameter status changes to occur because the administrator
+ changed a configuration file and then sent the
+ <span class="systemitem">SIGHUP</span> signal to the server. Also,
+ if a <code class="command">SET</code> command is rolled back, an appropriate
+ ParameterStatus message will be generated to report the current
+ effective value.
+ </p><p>
+ At present there is a hard-wired set of parameters for which
+ ParameterStatus will be generated: they are
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code>,
+ <code class="varname">client_encoding</code>,
+ <code class="varname">application_name</code>,
+ <code class="varname">default_transaction_read_only</code>,
+ <code class="varname">in_hot_standby</code>,
+ <code class="varname">is_superuser</code>,
+ <code class="varname">session_authorization</code>,
+ <code class="varname">DateStyle</code>,
+ <code class="varname">IntervalStyle</code>,
+ <code class="varname">TimeZone</code>,
+ <code class="varname">integer_datetimes</code>, and
+ <code class="varname">standard_conforming_strings</code>.
+ (<code class="varname">server_encoding</code>, <code class="varname">TimeZone</code>, and
+ <code class="varname">integer_datetimes</code> were not reported by releases before 8.0;
+ <code class="varname">standard_conforming_strings</code> was not reported by releases
+ before 8.1;
+ <code class="varname">IntervalStyle</code> was not reported by releases before 8.4;
+ <code class="varname">application_name</code> was not reported by releases before
+ 9.0;
+ <code class="varname">default_transaction_read_only</code> and
+ <code class="varname">in_hot_standby</code> were not reported by releases before
+ 14.)
+ Note that
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code> and
+ <code class="varname">integer_datetimes</code>
+ are pseudo-parameters that cannot change after startup.
+ This set might change in the future, or even become configurable.
+ Accordingly, a frontend should simply ignore ParameterStatus for
+ parameters that it does not understand or care about.
+ </p><p>
+ If a frontend issues a <code class="command">LISTEN</code> command, then the
+ backend will send a NotificationResponse message (not to be
+ confused with NoticeResponse!) whenever a
+ <code class="command">NOTIFY</code> command is executed for the same
+ channel name.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ At present, NotificationResponse can only be sent outside a
+ transaction, and thus it will not occur in the middle of a
+ command-response series, though it might occur just before ReadyForQuery.
+ It is unwise to design frontend logic that assumes that, however.
+ Good practice is to be able to accept NotificationResponse at any
+ point in the protocol.
+ </p></div></div><div class="sect2" id="id-1.10.6.7.10"><div class="titlepage"><div><div><h3 class="title">55.2.8. Canceling Requests in Progress</h3></div></div></div><p>
+ During the processing of a query, the frontend might request
+ cancellation of the query. The cancel request is not sent
+ directly on the open connection to the backend for reasons of
+ implementation efficiency: we don't want to have the backend
+ constantly checking for new input from the frontend during query
+ processing. Cancel requests should be relatively infrequent, so
+ we make them slightly cumbersome in order to avoid a penalty in
+ the normal case.
+ </p><p>
+ To issue a cancel request, the frontend opens a new connection to
+ the server and sends a CancelRequest message, rather than the
+ StartupMessage message that would ordinarily be sent across a new
+ connection. The server will process this request and then close
+ the connection. For security reasons, no direct reply is made to
+ the cancel request message.
+ </p><p>
+ A CancelRequest message will be ignored unless it contains the
+ same key data (PID and secret key) passed to the frontend during
+ connection start-up. If the request matches the PID and secret
+ key for a currently executing backend, the processing of the
+ current query is aborted. (In the existing implementation, this is
+ done by sending a special signal to the backend process that is
+ processing the query.)
+ </p><p>
+ The cancellation signal might or might not have any effect — for
+ example, if it arrives after the backend has finished processing
+ the query, then it will have no effect. If the cancellation is
+ effective, it results in the current command being terminated
+ early with an error message.
+ </p><p>
+ The upshot of all this is that for reasons of both security and
+ efficiency, the frontend has no direct way to tell whether a
+ cancel request has succeeded. It must continue to wait for the
+ backend to respond to the query. Issuing a cancel simply improves
+ the odds that the current query will finish soon, and improves the
+ odds that it will fail with an error message instead of
+ succeeding.
+ </p><p>
+ Since the cancel request is sent across a new connection to the
+ server and not across the regular frontend/backend communication
+ link, it is possible for the cancel request to be issued by any
+ process, not just the frontend whose query is to be canceled.
+ This might provide additional flexibility when building
+ multiple-process applications. It also introduces a security
+ risk, in that unauthorized persons might try to cancel queries.
+ The security risk is addressed by requiring a dynamically
+ generated secret key to be supplied in cancel requests.
+ </p></div><div class="sect2" id="id-1.10.6.7.11"><div class="titlepage"><div><div><h3 class="title">55.2.9. Termination</h3></div></div></div><p>
+ The normal, graceful termination procedure is that the frontend
+ sends a Terminate message and immediately closes the connection.
+ On receipt of this message, the backend closes the connection and
+ terminates.
+ </p><p>
+ In rare cases (such as an administrator-commanded database shutdown)
+ the backend might disconnect without any frontend request to do so.
+ In such cases the backend will attempt to send an error or notice message
+ giving the reason for the disconnection before it closes the connection.
+ </p><p>
+ Other termination scenarios arise from various failure cases, such as core
+ dump at one end or the other, loss of the communications link, loss of
+ message-boundary synchronization, etc. If either frontend or backend sees
+ an unexpected closure of the connection, it should clean
+ up and terminate. The frontend has the option of launching a new backend
+ by recontacting the server if it doesn't want to terminate itself.
+ Closing the connection is also advisable if an unrecognizable message type
+ is received, since this probably indicates loss of message-boundary sync.
+ </p><p>
+ For either normal or abnormal termination, any open transaction is
+ rolled back, not committed. One should note however that if a
+ frontend disconnects while a non-<code class="command">SELECT</code> query
+ is being processed, the backend will probably finish the query
+ before noticing the disconnection. If the query is outside any
+ transaction block (<code class="command">BEGIN</code> ... <code class="command">COMMIT</code>
+ sequence) then its results might be committed before the
+ disconnection is recognized.
+ </p></div><div class="sect2" id="id-1.10.6.7.12"><div class="titlepage"><div><div><h3 class="title">55.2.10. <acronym class="acronym">SSL</acronym> Session Encryption</h3></div></div></div><p>
+ If <span class="productname">PostgreSQL</span> was built with
+ <acronym class="acronym">SSL</acronym> support, frontend/backend communications
+ can be encrypted using <acronym class="acronym">SSL</acronym>. This provides
+ communication security in environments where attackers might be
+ able to capture the session traffic. For more information on
+ encrypting <span class="productname">PostgreSQL</span> sessions with
+ <acronym class="acronym">SSL</acronym>, see <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a>.
+ </p><p>
+ To initiate an <acronym class="acronym">SSL</acronym>-encrypted connection, the
+ frontend initially sends an SSLRequest message rather than a
+ StartupMessage. The server then responds with a single byte
+ containing <code class="literal">S</code> or <code class="literal">N</code>, indicating that it is
+ willing or unwilling to perform <acronym class="acronym">SSL</acronym>,
+ respectively. The frontend might close the connection at this point
+ if it is dissatisfied with the response. To continue after
+ <code class="literal">S</code>, perform an <acronym class="acronym">SSL</acronym> startup handshake
+ (not described here, part of the <acronym class="acronym">SSL</acronym>
+ specification) with the server. If this is successful, continue
+ with sending the usual StartupMessage. In this case the
+ StartupMessage and all subsequent data will be
+ <acronym class="acronym">SSL</acronym>-encrypted. To continue after
+ <code class="literal">N</code>, send the usual StartupMessage and proceed without
+ encryption.
+ (Alternatively, it is permissible to issue a GSSENCRequest message
+ after an <code class="literal">N</code> response to try to
+ use <acronym class="acronym">GSSAPI</acronym> encryption instead
+ of <acronym class="acronym">SSL</acronym>.)
+ </p><p>
+ The frontend should also be prepared to handle an ErrorMessage
+ response to SSLRequest from the server. This would only occur if
+ the server predates the addition of <acronym class="acronym">SSL</acronym> support
+ to <span class="productname">PostgreSQL</span>. (Such servers are now very ancient,
+ and likely do not exist in the wild anymore.)
+ In this case the connection must
+ be closed, but the frontend might choose to open a fresh connection
+ and proceed without requesting <acronym class="acronym">SSL</acronym>.
+ </p><p>
+ When <acronym class="acronym">SSL</acronym> encryption can be performed, the server
+ is expected to send only the single <code class="literal">S</code> byte and then
+ wait for the frontend to initiate an <acronym class="acronym">SSL</acronym> handshake.
+ If additional bytes are available to read at this point, it likely
+ means that a man-in-the-middle is attempting to perform a
+ buffer-stuffing attack
+ (<a class="ulink" href="https://www.postgresql.org/support/security/CVE-2021-23222/" target="_top">CVE-2021-23222</a>).
+ Frontends should be coded either to read exactly one byte from the
+ socket before turning the socket over to their SSL library, or to
+ treat it as a protocol violation if they find they have read additional
+ bytes.
+ </p><p>
+ An initial SSLRequest can also be used in a connection that is being
+ opened to send a CancelRequest message.
+ </p><p>
+ While the protocol itself does not provide a way for the server to
+ force <acronym class="acronym">SSL</acronym> encryption, the administrator can
+ configure the server to reject unencrypted sessions as a byproduct
+ of authentication checking.
+ </p></div><div class="sect2" id="id-1.10.6.7.13"><div class="titlepage"><div><div><h3 class="title">55.2.11. <acronym class="acronym">GSSAPI</acronym> Session Encryption</h3></div></div></div><p>
+ If <span class="productname">PostgreSQL</span> was built with
+ <acronym class="acronym">GSSAPI</acronym> support, frontend/backend communications
+ can be encrypted using <acronym class="acronym">GSSAPI</acronym>. This provides
+ communication security in environments where attackers might be
+ able to capture the session traffic. For more information on
+ encrypting <span class="productname">PostgreSQL</span> sessions with
+ <acronym class="acronym">GSSAPI</acronym>, see <a class="xref" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Section 19.10</a>.
+ </p><p>
+ To initiate a <acronym class="acronym">GSSAPI</acronym>-encrypted connection, the
+ frontend initially sends a GSSENCRequest message rather than a
+ StartupMessage. The server then responds with a single byte
+ containing <code class="literal">G</code> or <code class="literal">N</code>, indicating that it
+ is willing or unwilling to perform <acronym class="acronym">GSSAPI</acronym> encryption,
+ respectively. The frontend might close the connection at this point
+ if it is dissatisfied with the response. To continue after
+ <code class="literal">G</code>, using the GSSAPI C bindings as discussed in
+ <a class="ulink" href="https://tools.ietf.org/html/rfc2744" target="_top">RFC 2744</a>
+ or equivalent, perform a <acronym class="acronym">GSSAPI</acronym> initialization by
+ calling <code class="function">gss_init_sec_context()</code> in a loop and sending
+ the result to the server, starting with an empty input and then with each
+ result from the server, until it returns no output. When sending the
+ results of <code class="function">gss_init_sec_context()</code> to the server,
+ prepend the length of the message as a four byte integer in network byte
+ order.
+ To continue after
+ <code class="literal">N</code>, send the usual StartupMessage and proceed without
+ encryption.
+ (Alternatively, it is permissible to issue an SSLRequest message
+ after an <code class="literal">N</code> response to try to
+ use <acronym class="acronym">SSL</acronym> encryption instead
+ of <acronym class="acronym">GSSAPI</acronym>.)
+ </p><p>
+ The frontend should also be prepared to handle an ErrorMessage
+ response to GSSENCRequest from the server. This would only occur if
+ the server predates the addition of <acronym class="acronym">GSSAPI</acronym> encryption
+ support to <span class="productname">PostgreSQL</span>. In this case the
+ connection must be closed, but the frontend might choose to open a fresh
+ connection and proceed without requesting <acronym class="acronym">GSSAPI</acronym>
+ encryption.
+ </p><p>
+ When <acronym class="acronym">GSSAPI</acronym> encryption can be performed, the server
+ is expected to send only the single <code class="literal">G</code> byte and then
+ wait for the frontend to initiate a <acronym class="acronym">GSSAPI</acronym> handshake.
+ If additional bytes are available to read at this point, it likely
+ means that a man-in-the-middle is attempting to perform a
+ buffer-stuffing attack
+ (<a class="ulink" href="https://www.postgresql.org/support/security/CVE-2021-23222/" target="_top">CVE-2021-23222</a>).
+ Frontends should be coded either to read exactly one byte from the
+ socket before turning the socket over to their GSSAPI library, or to
+ treat it as a protocol violation if they find they have read additional
+ bytes.
+ </p><p>
+ An initial GSSENCRequest can also be used in a connection that is being
+ opened to send a CancelRequest message.
+ </p><p>
+ Once <acronym class="acronym">GSSAPI</acronym> encryption has been successfully
+ established, use <code class="function">gss_wrap()</code> to
+ encrypt the usual StartupMessage and all subsequent data, prepending the
+ length of the result from <code class="function">gss_wrap()</code> as a four byte
+ integer in network byte order to the actual encrypted payload. Note that
+ the server will only accept encrypted packets from the client which are less
+ than 16kB; <code class="function">gss_wrap_size_limit()</code> should be used by the
+ client to determine the size of the unencrypted message which will fit
+ within this limit and larger messages should be broken up into multiple
+ <code class="function">gss_wrap()</code> calls. Typical segments are 8kB of
+ unencrypted data, resulting in encrypted packets of slightly larger than 8kB
+ but well within the 16kB maximum. The server can be expected to not send
+ encrypted packets of larger than 16kB to the client.
+ </p><p>
+ While the protocol itself does not provide a way for the server to
+ force <acronym class="acronym">GSSAPI</acronym> encryption, the administrator can
+ configure the server to reject unencrypted sessions as a byproduct
+ of authentication checking.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-overview.html" title="55.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sasl-authentication.html" title="55.3. SASL Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.3. SASL Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-logical-replication.html b/doc/src/sgml/html/protocol-logical-replication.html
new file mode 100644
index 0000000..e8619da
--- /dev/null
+++ b/doc/src/sgml/html/protocol-logical-replication.html
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.5. Logical Streaming Replication Protocol</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-replication.html" title="55.4. Streaming Replication Protocol" /><link rel="next" href="protocol-message-types.html" title="55.6. Message Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.5. Logical Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-message-types.html" title="55.6. Message Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-LOGICAL-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.5. Logical Streaming Replication Protocol</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS">55.5.1. Logical Streaming Replication Parameters</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES">55.5.2. Logical Replication Protocol Messages</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES-FLOW">55.5.3. Logical Replication Protocol Message Flow</a></span></dt></dl></div><p>
+ This section describes the logical replication protocol, which is the message
+ flow started by the <code class="literal">START_REPLICATION</code>
+ <code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em>
+ <code class="literal">LOGICAL</code> replication command.
+ </p><p>
+ The logical streaming replication protocol builds on the primitives of
+ the physical streaming replication protocol.
+ </p><div class="sect2" id="PROTOCOL-LOGICAL-REPLICATION-PARAMS"><div class="titlepage"><div><div><h3 class="title">55.5.1. Logical Streaming Replication Parameters</h3></div></div></div><p>
+ The logical replication <code class="literal">START_REPLICATION</code> command
+ accepts following parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ proto_version
+ </span></dt><dd><p>
+ Protocol version. Currently versions <code class="literal">1</code>, <code class="literal">2</code>,
+ and <code class="literal">3</code> are supported.
+ </p><p>
+ Version <code class="literal">2</code> is supported only for server version 14
+ and above, and it allows streaming of large in-progress transactions.
+ </p><p>
+ Version <code class="literal">3</code> is supported only for server version 15
+ and above, and it allows streaming of two-phase commits.
+ </p></dd><dt><span class="term">
+ publication_names
+ </span></dt><dd><p>
+ Comma separated list of publication names for which to subscribe
+ (receive changes). The individual publication names are treated
+ as standard objects names and can be quoted the same as needed.
+ </p></dd></dl></div><p>
+
+ </p></div><div class="sect2" id="PROTOCOL-LOGICAL-MESSAGES"><div class="titlepage"><div><div><h3 class="title">55.5.2. Logical Replication Protocol Messages</h3></div></div></div><p>
+ The individual protocol messages are discussed in the following
+ subsections. Individual messages are described in
+ <a class="xref" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Section 55.9</a>.
+ </p><p>
+ All top-level protocol messages begin with a message type byte.
+ While represented in code as a character, this is a signed byte with no
+ associated encoding.
+ </p><p>
+ Since the streaming replication protocol supplies a message length there
+ is no need for top-level protocol messages to embed a length in their
+ header.
+ </p></div><div class="sect2" id="PROTOCOL-LOGICAL-MESSAGES-FLOW"><div class="titlepage"><div><div><h3 class="title">55.5.3. Logical Replication Protocol Message Flow</h3></div></div></div><p>
+ With the exception of the <code class="literal">START_REPLICATION</code> command and
+ the replay progress messages, all information flows only from the backend
+ to the frontend.
+ </p><p>
+ The logical replication protocol sends individual transactions one by one.
+ This means that all messages between a pair of Begin and Commit messages
+ belong to the same transaction. Similarly, all messages between a pair of
+ Begin Prepare and Prepare messages belong to the same transaction.
+ It also sends changes of large in-progress transactions between a pair of
+ Stream Start and Stream Stop messages. The last stream of such a transaction
+ contains a Stream Commit or Stream Abort message.
+ </p><p>
+ Every sent transaction contains zero or more DML messages (Insert,
+ Update, Delete). In case of a cascaded setup it can also contain Origin
+ messages. The origin message indicates that the transaction originated on
+ different replication node. Since a replication node in the scope of logical
+ replication protocol can be pretty much anything, the only identifier
+ is the origin name. It's downstream's responsibility to handle this as
+ needed (if needed). The Origin message is always sent before any DML
+ messages in the transaction.
+ </p><p>
+ Every DML message contains a relation OID, identifying the publisher's
+ relation that was acted on. Before the first DML message for a given
+ relation OID, a Relation message will be sent, describing the schema of
+ that relation. Subsequently, a new Relation message will be sent if
+ the relation's definition has changed since the last Relation message
+ was sent for it. (The protocol assumes that the client is capable of
+ remembering this metadata for as many relations as needed.)
+ </p><p>
+ Relation messages identify column types by their OIDs. In the case
+ of a built-in type, it is assumed that the client can look up that
+ type OID locally, so no additional data is needed. For a non-built-in
+ type OID, a Type message will be sent before the Relation message,
+ to provide the type name associated with that OID. Thus, a client that
+ needs to specifically identify the types of relation columns should
+ cache the contents of Type messages, and first consult that cache to
+ see if the type OID is defined there. If not, look up the type OID
+ locally.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-message-types.html" title="55.6. Message Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.4. Streaming Replication Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.6. Message Data Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-logicalrep-message-formats.html b/doc/src/sgml/html/protocol-logicalrep-message-formats.html
new file mode 100644
index 0000000..570ef9c
--- /dev/null
+++ b/doc/src/sgml/html/protocol-logicalrep-message-formats.html
@@ -0,0 +1,307 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.9. Logical Replication Message Formats</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields" /><link rel="next" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.9. Logical Replication Message Formats</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.9. Logical Replication Message Formats</h2></div></div></div><p>
+ This section describes the detailed format of each logical replication
+ message. These messages are either returned by the replication slot SQL
+ interface or are sent by a walsender. In the case of a walsender, they are
+ encapsulated inside replication protocol WAL messages as described in
+ <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>, and generally obey the same message
+ flow as physical replication.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-BEGIN"><span class="term">Begin</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('B')</span></dt><dd><p>
+ Identifies the message as a begin message.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The final LSN of the transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-MESSAGE"><span class="term">Message</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('M')</span></dt><dd><p>
+ Identifies the message as a logical decoding message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ Flags; Either 0 for no flags or 1 if the logical decoding
+ message is transactional.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the logical decoding message.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The prefix of the logical decoding message.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of the content.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The content of the logical decoding message.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-COMMIT"><span class="term">Commit</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('C')</span></dt><dd><p>
+ Identifies the message as a commit message.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the commit.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-ORIGIN"><span class="term">Origin</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('O')</span></dt><dd><p>
+ Identifies the message as an origin message.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the commit on the origin server.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Name of the origin.
+ </p></dd></dl></div><p>
+ Note that there can be multiple Origin messages inside a single transaction.
+ </p></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-RELATION"><span class="term">Relation</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as a relation message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the relation.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Namespace (empty string for <code class="literal">pg_catalog</code>).
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Relation name.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ Replica identity setting for the relation (same as
+ <code class="structfield">relreplident</code> in <code class="structname">pg_class</code>).
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ Number of columns.
+ </p></dd></dl></div><p>
+ Next, the following message part appears for each column included in
+ the publication (except generated columns):
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int8</span></dt><dd><p>
+ Flags for the column. Currently can be either 0 for no flags
+ or 1 which marks the column as part of the key.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Name of the column.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the column's data type.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Type modifier of the column (<code class="structfield">atttypmod</code>).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-TYPE"><span class="term">Type</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('Y')</span></dt><dd><p>
+ Identifies the message as a type message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the data type.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Namespace (empty string for <code class="literal">pg_catalog</code>).
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Name of the data type.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-INSERT"><span class="term">Insert</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('I')</span></dt><dd><p>
+ Identifies the message as an insert message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </p></dd><dt><span class="term">Byte1('N')</span></dt><dd><p>
+ Identifies the following TupleData message as a new tuple.
+ </p></dd><dt><span class="term">TupleData</span></dt><dd><p>
+ TupleData message part representing the contents of new tuple.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-UPDATE"><span class="term">Update</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('U')</span></dt><dd><p>
+ Identifies the message as an update message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </p></dd><dt><span class="term">Byte1('K')</span></dt><dd><p>
+ Identifies the following TupleData submessage as a key.
+ This field is optional and is only present if
+ the update changed data in any of the column(s) that are
+ part of the REPLICA IDENTITY index.
+ </p></dd><dt><span class="term">Byte1('O')</span></dt><dd><p>
+ Identifies the following TupleData submessage as an old tuple.
+ This field is optional and is only present if table in which
+ the update happened has REPLICA IDENTITY set to FULL.
+ </p></dd><dt><span class="term">TupleData</span></dt><dd><p>
+ TupleData message part representing the contents of the old tuple
+ or primary key. Only present if the previous 'O' or 'K' part
+ is present.
+ </p></dd><dt><span class="term">Byte1('N')</span></dt><dd><p>
+ Identifies the following TupleData message as a new tuple.
+ </p></dd><dt><span class="term">TupleData</span></dt><dd><p>
+ TupleData message part representing the contents of a new tuple.
+ </p></dd></dl></div><p>
+ The Update message may contain either a 'K' message part or an 'O' message part
+ or neither of them, but never both of them.
+ </p></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-DELETE"><span class="term">Delete</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('D')</span></dt><dd><p>
+ Identifies the message as a delete message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </p></dd><dt><span class="term">Byte1('K')</span></dt><dd><p>
+ Identifies the following TupleData submessage as a key.
+ This field is present if the table in which the delete has
+ happened uses an index as REPLICA IDENTITY.
+ </p></dd><dt><span class="term">Byte1('O')</span></dt><dd><p>
+ Identifies the following TupleData message as an old tuple.
+ This field is present if the table in which the delete
+ happened has REPLICA IDENTITY set to FULL.
+ </p></dd><dt><span class="term">TupleData</span></dt><dd><p>
+ TupleData message part representing the contents of the old tuple
+ or primary key, depending on the previous field.
+ </p></dd></dl></div><p>
+ The Delete message may contain either a 'K' message part or an 'O' message part,
+ but never both of them.
+ </p></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-TRUNCATE"><span class="term">Truncate</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('T')</span></dt><dd><p>
+ Identifies the message as a truncate message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Number of relations
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ Option bits for <code class="command">TRUNCATE</code>:
+ 1 for <code class="literal">CASCADE</code>, 2 for <code class="literal">RESTART IDENTITY</code>
+ </p></dd><dt><span class="term">Int32 (Oid)</span></dt><dd><p>
+ OID of the relation corresponding to the ID in the relation
+ message. This field is repeated for each relation.
+ </p></dd></dl></div></dd></dl></div><p>
+ The following messages (Stream Start, Stream Stop, Stream Commit, and
+ Stream Abort) are available since protocol version 2.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-STREAM-START"><span class="term">Stream Start</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('S')</span></dt><dd><p>
+ Identifies the message as a stream start message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ A value of 1 indicates this is the first stream segment for
+ this XID, 0 for any other stream segment.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-STREAM-STOP"><span class="term">Stream Stop</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('E')</span></dt><dd><p>
+ Identifies the message as a stream stop message.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-STREAM-COMMIT"><span class="term">Stream Commit</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('c')</span></dt><dd><p>
+ Identifies the message as a stream commit message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the commit.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-STREAM-ABORT"><span class="term">Stream Abort</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('A')</span></dt><dd><p>
+ Identifies the message as a stream abort message.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the subtransaction (will be same as xid of the transaction for top-level
+ transactions).
+ </p></dd></dl></div></dd></dl></div><p>
+ The following messages (Begin Prepare, Prepare, Commit Prepared, Rollback Prepared, Stream Prepare)
+ are available since protocol version 3.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-BEGIN-PREPARE"><span class="term">Begin Prepare</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('b')</span></dt><dd><p>
+ Identifies the message as the beginning of a prepared transaction message.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the prepare.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The user defined GID of the prepared transaction.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-PREPARE"><span class="term">Prepare</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('P')</span></dt><dd><p>
+ Identifies the message as a prepared transaction message.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the prepare.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The user defined GID of the prepared transaction.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-COMMIT-PREPARED"><span class="term">Commit Prepared</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('K')</span></dt><dd><p>
+ Identifies the message as the commit of a prepared transaction message.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the commit of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the commit of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The user defined GID of the prepared transaction.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-ROLLBACK-PREPARED"><span class="term">Rollback Prepared</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('r')</span></dt><dd><p>
+ Identifies the message as the rollback of a prepared transaction message.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the rollback of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Rollback timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The user defined GID of the prepared transaction.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-STREAM-PREPARE"><span class="term">Stream Prepare</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as a stream prepared transaction message.
+ </p></dd><dt><span class="term">Int8(0)</span></dt><dd><p>
+ Flags; currently unused.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The LSN of the prepare.
+ </p></dd><dt><span class="term">Int64 (XLogRecPtr)</span></dt><dd><p>
+ The end LSN of the prepared transaction.
+ </p></dd><dt><span class="term">Int64 (TimestampTz)</span></dt><dd><p>
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </p></dd><dt><span class="term">Int32 (TransactionId)</span></dt><dd><p>
+ Xid of the transaction.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The user defined GID of the prepared transaction.
+ </p></dd></dl></div></dd></dl></div><p>
+ The following message parts are shared by the above messages.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-LOGICALREP-MESSAGE-FORMATS-TUPLEDATA"><span class="term">TupleData</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int16</span></dt><dd><p>
+ Number of columns.
+ </p></dd></dl></div><p>
+ Next, one of the following submessages appears for each column (except generated columns):
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('n')</span></dt><dd><p>
+ Identifies the data as NULL value.
+ </p></dd></dl></div><p>
+ Or
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('u')</span></dt><dd><p>
+ Identifies unchanged TOASTed value (the actual value is not
+ sent).
+ </p></dd></dl></div><p>
+ Or
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('t')</span></dt><dd><p>
+ Identifies the data as text formatted value.
+ </p></dd></dl></div><p>
+ Or
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('b')</span></dt><dd><p>
+ Identifies the data as binary formatted value.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of the column value.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The value of the column, either in binary or in text format.
+ (As specified in the preceding format byte).
+ <em class="replaceable"><code>n</code></em> is the above length.
+ </p></dd></dl></div><p>
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.8. Error and Notice Message Fields </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.10. Summary of Changes since Protocol 2.0</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-message-formats.html b/doc/src/sgml/html/protocol-message-formats.html
new file mode 100644
index 0000000..6c01814
--- /dev/null
+++ b/doc/src/sgml/html/protocol-message-formats.html
@@ -0,0 +1,676 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.7. Message Formats</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-message-types.html" title="55.6. Message Data Types" /><link rel="next" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.7. Message Formats</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-message-types.html" title="55.6. Message Data Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-MESSAGE-FORMATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.7. Message Formats</h2></div></div></div><p>
+ This section describes the detailed format of each message. Each is marked to
+ indicate that it can be sent by a frontend (F), a backend (B), or both
+ (F &amp; B).
+ Notice that although each message includes a byte count at the beginning,
+ the message format is defined so that the message end can be found without
+ reference to the byte count. This aids validity checking. (The CopyData
+ message is an exception, because it forms part of a data stream; the contents
+ of any individual CopyData message cannot be interpretable on their own.)
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONOK"><span class="term">AuthenticationOk (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(0)</span></dt><dd><p>
+ Specifies that the authentication was successful.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONKERBEROSV5"><span class="term">AuthenticationKerberosV5 (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(2)</span></dt><dd><p>
+ Specifies that Kerberos V5 authentication is required.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONCLEARTEXTPASSWORD"><span class="term">AuthenticationCleartextPassword (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(3)</span></dt><dd><p>
+ Specifies that a clear-text password is required.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONMD5PASSWORD"><span class="term">AuthenticationMD5Password (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(12)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(5)</span></dt><dd><p>
+ Specifies that an MD5-encrypted password is required.
+ </p></dd><dt><span class="term">Byte4</span></dt><dd><p>
+ The salt to use when encrypting the password.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONSCMCREDENTIAL"><span class="term">AuthenticationSCMCredential (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(6)</span></dt><dd><p>
+ Specifies that an SCM credentials message is required.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONGSS"><span class="term">AuthenticationGSS (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(7)</span></dt><dd><p>
+ Specifies that GSSAPI authentication is required.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONGSSCONTINUE"><span class="term">AuthenticationGSSContinue (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Specifies that this message contains GSSAPI or SSPI data.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ GSSAPI or SSPI authentication data.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONSSPI"><span class="term">AuthenticationSSPI (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(9)</span></dt><dd><p>
+ Specifies that SSPI authentication is required.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONSASL"><span class="term">AuthenticationSASL (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(10)</span></dt><dd><p>
+ Specifies that SASL authentication is required.
+ </p></dd></dl></div><p>
+ The message body is a list of SASL authentication mechanisms, in the
+ server's order of preference. A zero byte is required as terminator after
+ the last authentication mechanism name. For each mechanism, there is the
+ following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String</span></dt><dd><p>
+ Name of a SASL authentication mechanism.
+ </p></dd></dl></div><p>
+ </p></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONSASLCONTINUE"><span class="term">AuthenticationSASLContinue (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(11)</span></dt><dd><p>
+ Specifies that this message contains a SASL challenge.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ SASL data, specific to the SASL mechanism being used.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-AUTHENTICATIONSASLFINAL"><span class="term">AuthenticationSASLFinal (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('R')</span></dt><dd><p>
+ Identifies the message as an authentication request.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(12)</span></dt><dd><p>
+ Specifies that SASL authentication has completed.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ SASL outcome "additional data", specific to the SASL mechanism
+ being used.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-BACKENDKEYDATA"><span class="term">BackendKeyData (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('K')</span></dt><dd><p>
+ Identifies the message as cancellation key data.
+ The frontend must save these values if it wishes to be
+ able to issue CancelRequest messages later.
+ </p></dd><dt><span class="term">Int32(12)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The process ID of this backend.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The secret key of this backend.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-BIND"><span class="term">Bind (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('B')</span></dt><dd><p>
+ Identifies the message as a Bind command.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the destination portal
+ (an empty string selects the unnamed portal).
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the source prepared statement
+ (an empty string selects the unnamed prepared statement).
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of parameter format codes that follow
+ (denoted <em class="replaceable"><code>C</code></em> below).
+ This can be zero to indicate that there are no parameters
+ or that the parameters all use the default format (text);
+ or one, in which case the specified format code is applied
+ to all parameters; or it can equal the actual number of
+ parameters.
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>C</code></em>]</span></dt><dd><p>
+ The parameter format codes. Each must presently be
+ zero (text) or one (binary).
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of parameter values that follow (possibly zero).
+ This must match the number of parameters needed by the query.
+ </p></dd></dl></div><p>
+ Next, the following pair of fields appear for each parameter:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ The length of the parameter value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL parameter value.
+ No value bytes follow in the NULL case.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The value of the parameter, in the format indicated by the
+ associated format code.
+ <em class="replaceable"><code>n</code></em> is the above length.
+ </p></dd></dl></div><p>
+ After the last parameter, the following fields appear:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int16</span></dt><dd><p>
+ The number of result-column format codes that follow
+ (denoted <em class="replaceable"><code>R</code></em> below).
+ This can be zero to indicate that there are no result columns
+ or that the result columns should all use the default format
+ (text);
+ or one, in which case the specified format code is applied
+ to all result columns (if any); or it can equal the actual
+ number of result columns of the query.
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>R</code></em>]</span></dt><dd><p>
+ The result-column format codes. Each must presently be
+ zero (text) or one (binary).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-BINDCOMPLETE"><span class="term">BindComplete (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('2')</span></dt><dd><p>
+ Identifies the message as a Bind-complete indicator.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-CANCELREQUEST"><span class="term">CancelRequest (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32(16)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(80877102)</span></dt><dd><p>
+ The cancel request code. The value is chosen to contain
+ <code class="literal">1234</code> in the most significant 16 bits, and <code class="literal">5678</code> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The process ID of the target backend.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The secret key for the target backend.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-CLOSE"><span class="term">Close (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('C')</span></dt><dd><p>
+ Identifies the message as a Close command.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
+ '<code class="literal">S</code>' to close a prepared statement; or
+ '<code class="literal">P</code>' to close a portal.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the prepared statement or portal to close
+ (an empty string selects the unnamed prepared statement
+ or portal).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-CLOSECOMPLETE"><span class="term">CloseComplete (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('3')</span></dt><dd><p>
+ Identifies the message as a Close-complete indicator.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COMMANDCOMPLETE"><span class="term">CommandComplete (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('C')</span></dt><dd><p>
+ Identifies the message as a command-completed response.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The command tag. This is usually a single
+ word that identifies which SQL command was completed.
+ </p><p>
+ For an <code class="command">INSERT</code> command, the tag is
+ <code class="literal">INSERT <em class="replaceable"><code>oid</code></em>
+ <em class="replaceable"><code>rows</code></em></code>, where
+ <em class="replaceable"><code>rows</code></em> is the number of rows
+ inserted. <em class="replaceable"><code>oid</code></em> used to be the object ID
+ of the inserted row if <em class="replaceable"><code>rows</code></em> was 1
+ and the target table had OIDs, but OIDs system columns are
+ not supported anymore; therefore <em class="replaceable"><code>oid</code></em>
+ is always 0.
+ </p><p>
+ For a <code class="command">DELETE</code> command, the tag is
+ <code class="literal">DELETE <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows deleted.
+ </p><p>
+ For an <code class="command">UPDATE</code> command, the tag is
+ <code class="literal">UPDATE <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows updated.
+ </p><p>
+ For a <code class="command">MERGE</code> command, the tag is
+ <code class="literal">MERGE <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows inserted,
+ updated, or deleted.
+ </p><p>
+ For a <code class="command">SELECT</code> or <code class="command">CREATE TABLE AS</code>
+ command, the tag is <code class="literal">SELECT <em class="replaceable"><code>rows</code></em></code>
+ where <em class="replaceable"><code>rows</code></em> is the number of rows retrieved.
+ </p><p>
+ For a <code class="command">MOVE</code> command, the tag is
+ <code class="literal">MOVE <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows the
+ cursor's position has been changed by.
+ </p><p>
+ For a <code class="command">FETCH</code> command, the tag is
+ <code class="literal">FETCH <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows that
+ have been retrieved from the cursor.
+ </p><p>
+ For a <code class="command">COPY</code> command, the tag is
+ <code class="literal">COPY <em class="replaceable"><code>rows</code></em></code> where
+ <em class="replaceable"><code>rows</code></em> is the number of rows copied.
+ (Note: the row count appears only in
+ <span class="productname">PostgreSQL</span> 8.2 and later.)
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYDATA"><span class="term">CopyData (F &amp; B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('d')</span></dt><dd><p>
+ Identifies the message as <code class="command">COPY</code> data.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ Data that forms part of a <code class="command">COPY</code> data stream. Messages sent
+ from the backend will always correspond to single data rows,
+ but messages sent by frontends might divide the data stream
+ arbitrarily.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYDONE"><span class="term">CopyDone (F &amp; B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('c')</span></dt><dd><p>
+ Identifies the message as a <code class="command">COPY</code>-complete indicator.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYFAIL"><span class="term">CopyFail (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('f')</span></dt><dd><p>
+ Identifies the message as a <code class="command">COPY</code>-failure indicator.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ An error message to report as the cause of failure.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYINRESPONSE"><span class="term">CopyInResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('G')</span></dt><dd><p>
+ Identifies the message as a Start Copy In response.
+ The frontend must now send copy-in data (if not
+ prepared to do so, send a CopyFail message).
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ 0 indicates the overall <code class="command">COPY</code> format is textual (rows
+ separated by newlines, columns separated by separator
+ characters, etc.).
+ 1 indicates the overall copy format is binary (similar
+ to DataRow format).
+ See <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a>
+ for more information.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of columns in the data to be copied
+ (denoted <em class="replaceable"><code>N</code></em> below).
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>N</code></em>]</span></dt><dd><p>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYOUTRESPONSE"><span class="term">CopyOutResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('H')</span></dt><dd><p>
+ Identifies the message as a Start Copy Out response.
+ This message will be followed by copy-out data.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ 0 indicates the overall <code class="command">COPY</code> format
+ is textual (rows separated by newlines, columns
+ separated by separator characters, etc.). 1 indicates
+ the overall copy format is binary (similar to DataRow
+ format). See <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for more information.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of columns in the data to be copied
+ (denoted <em class="replaceable"><code>N</code></em> below).
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>N</code></em>]</span></dt><dd><p>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-COPYBOTHRESPONSE"><span class="term">CopyBothResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('W')</span></dt><dd><p>
+ Identifies the message as a Start Copy Both response.
+ This message is used only for Streaming Replication.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int8</span></dt><dd><p>
+ 0 indicates the overall <code class="command">COPY</code> format
+ is textual (rows separated by newlines, columns
+ separated by separator characters, etc.). 1 indicates
+ the overall copy format is binary (similar to DataRow
+ format). See <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a> for more information.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of columns in the data to be copied
+ (denoted <em class="replaceable"><code>N</code></em> below).
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>N</code></em>]</span></dt><dd><p>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-DATAROW"><span class="term">DataRow (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('D')</span></dt><dd><p>
+ Identifies the message as a data row.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of column values that follow (possibly zero).
+ </p></dd></dl></div><p>
+ Next, the following pair of fields appear for each column:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ The length of the column value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL column value.
+ No value bytes follow in the NULL case.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The value of the column, in the format indicated by the
+ associated format code.
+ <em class="replaceable"><code>n</code></em> is the above length.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-DESCRIBE"><span class="term">Describe (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('D')</span></dt><dd><p>
+ Identifies the message as a Describe command.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
+ '<code class="literal">S</code>' to describe a prepared statement; or
+ '<code class="literal">P</code>' to describe a portal.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the prepared statement or portal to describe
+ (an empty string selects the unnamed prepared statement
+ or portal).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-EMPTYQUERYRESPONSE"><span class="term">EmptyQueryResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('I')</span></dt><dd><p>
+ Identifies the message as a response to an empty query string.
+ (This substitutes for CommandComplete.)
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-ERRORRESPONSE"><span class="term">ErrorResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('E')</span></dt><dd><p>
+ Identifies the message as an error.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div><p>
+ The message body consists of one or more identified fields,
+ followed by a zero byte as a terminator. Fields can appear in
+ any order. For each field there is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1</span></dt><dd><p>
+ A code identifying the field type; if zero, this is
+ the message terminator and no string follows.
+ The presently defined field types are listed in
+ <a class="xref" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Section 55.8</a>.
+ Since more field types might be added in future,
+ frontends should silently ignore fields of unrecognized
+ type.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The field value.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-EXECUTE"><span class="term">Execute (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('E')</span></dt><dd><p>
+ Identifies the message as an Execute command.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the portal to execute
+ (an empty string selects the unnamed portal).
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Maximum number of rows to return, if portal contains
+ a query that returns rows (ignored otherwise). Zero
+ denotes <span class="quote">“<span class="quote">no limit</span>”</span>.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-FLUSH"><span class="term">Flush (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('H')</span></dt><dd><p>
+ Identifies the message as a Flush command.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-FUNCTIONCALL"><span class="term">FunctionCall (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('F')</span></dt><dd><p>
+ Identifies the message as a function call.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Specifies the object ID of the function to call.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of argument format codes that follow
+ (denoted <em class="replaceable"><code>C</code></em> below).
+ This can be zero to indicate that there are no arguments
+ or that the arguments all use the default format (text);
+ or one, in which case the specified format code is applied
+ to all arguments; or it can equal the actual number of
+ arguments.
+ </p></dd><dt><span class="term">Int16[<em class="replaceable"><code>C</code></em>]</span></dt><dd><p>
+ The argument format codes. Each must presently be
+ zero (text) or one (binary).
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ Specifies the number of arguments being supplied to the
+ function.
+ </p></dd></dl></div><p>
+ Next, the following pair of fields appear for each argument:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ The length of the argument value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL argument value.
+ No value bytes follow in the NULL case.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The value of the argument, in the format indicated by the
+ associated format code.
+ <em class="replaceable"><code>n</code></em> is the above length.
+ </p></dd></dl></div><p>
+ After the last argument, the following field appears:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int16</span></dt><dd><p>
+ The format code for the function result. Must presently be
+ zero (text) or one (binary).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-FUNCTIONCALLRESPONSE"><span class="term">FunctionCallResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('V')</span></dt><dd><p>
+ Identifies the message as a function call result.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The length of the function result value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL function result.
+ No value bytes follow in the NULL case.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ The value of the function result, in the format indicated by
+ the associated format code.
+ <em class="replaceable"><code>n</code></em> is the above length.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-GSSENCREQUEST"><span class="term">GSSENCRequest (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(80877104)</span></dt><dd><p>
+ The <acronym class="acronym">GSSAPI</acronym> Encryption request code. The value is chosen to contain
+ <code class="literal">1234</code> in the most significant 16 bits, and <code class="literal">5680</code> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-GSSRESPONSE"><span class="term">GSSResponse (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as a GSSAPI or SSPI response. Note that
+ this is also used for SASL and password response messages.
+ The exact message type can be deduced from the context.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ GSSAPI/SSPI specific message data.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-NEGOTIATEPROTOCOLVERSION"><span class="term">NegotiateProtocolVersion (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('v')</span></dt><dd><p>
+ Identifies the message as a protocol version negotiation
+ message.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Newest minor protocol version supported by the server
+ for the major protocol version requested by the client.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Number of protocol options not recognized by the server.
+ </p></dd></dl></div><p>
+ Then, for protocol option not recognized by the server, there
+ is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String</span></dt><dd><p>
+ The option name.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-NODATA"><span class="term">NoData (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('n')</span></dt><dd><p>
+ Identifies the message as a no-data indicator.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-NOTICERESPONSE"><span class="term">NoticeResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('N')</span></dt><dd><p>
+ Identifies the message as a notice.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div><p>
+ The message body consists of one or more identified fields,
+ followed by a zero byte as a terminator. Fields can appear in
+ any order. For each field there is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1</span></dt><dd><p>
+ A code identifying the field type; if zero, this is
+ the message terminator and no string follows.
+ The presently defined field types are listed in
+ <a class="xref" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Section 55.8</a>.
+ Since more field types might be added in future,
+ frontends should silently ignore fields of unrecognized
+ type.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The field value.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-NOTIFICATIONRESPONSE"><span class="term">NotificationResponse (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('A')</span></dt><dd><p>
+ Identifies the message as a notification response.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The process ID of the notifying backend process.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the channel that the notify has been raised on.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The <span class="quote">“<span class="quote">payload</span>”</span> string passed from the notifying process.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PARAMETERDESCRIPTION"><span class="term">ParameterDescription (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('t')</span></dt><dd><p>
+ Identifies the message as a parameter description.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of parameters used by the statement
+ (can be zero).
+ </p></dd></dl></div><p>
+ Then, for each parameter, there is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ Specifies the object ID of the parameter data type.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PARAMETERSTATUS"><span class="term">ParameterStatus (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('S')</span></dt><dd><p>
+ Identifies the message as a run-time parameter status report.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the run-time parameter being reported.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The current value of the parameter.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PARSE"><span class="term">Parse (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('P')</span></dt><dd><p>
+ Identifies the message as a Parse command.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The name of the destination prepared statement
+ (an empty string selects the unnamed prepared statement).
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The query string to be parsed.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The number of parameter data types specified
+ (can be zero). Note that this is not an indication of
+ the number of parameters that might appear in the
+ query string, only the number that the frontend wants to
+ prespecify types for.
+ </p></dd></dl></div><p>
+ Then, for each parameter, there is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ Specifies the object ID of the parameter data type.
+ Placing a zero here is equivalent to leaving the type
+ unspecified.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PARSECOMPLETE"><span class="term">ParseComplete (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('1')</span></dt><dd><p>
+ Identifies the message as a Parse-complete indicator.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PASSWORDMESSAGE"><span class="term">PasswordMessage (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as a password response. Note that
+ this is also used for GSSAPI, SSPI and SASL response messages.
+ The exact message type can be deduced from the context.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The password (encrypted, if requested).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-PORTALSUSPENDED"><span class="term">PortalSuspended (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('s')</span></dt><dd><p>
+ Identifies the message as a portal-suspended indicator.
+ Note this only appears if an Execute message's row-count limit
+ was reached.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-QUERY"><span class="term">Query (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('Q')</span></dt><dd><p>
+ Identifies the message as a simple query.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The query string itself.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-READYFORQUERY"><span class="term">ReadyForQuery (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('Z')</span></dt><dd><p>
+ Identifies the message type. ReadyForQuery is sent
+ whenever the backend is ready for a new query cycle.
+ </p></dd><dt><span class="term">Int32(5)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
+ Current backend transaction status indicator.
+ Possible values are '<code class="literal">I</code>' if idle (not in
+ a transaction block); '<code class="literal">T</code>' if in a transaction
+ block; or '<code class="literal">E</code>' if in a failed transaction
+ block (queries will be rejected until block is ended).
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-ROWDESCRIPTION"><span class="term">RowDescription (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('T')</span></dt><dd><p>
+ Identifies the message as a row description.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ Specifies the number of fields in a row (can be zero).
+ </p></dd></dl></div><p>
+ Then, for each field, there is the following:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String</span></dt><dd><p>
+ The field name.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ If the field can be identified as a column of a specific
+ table, the object ID of the table; otherwise zero.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ If the field can be identified as a column of a specific
+ table, the attribute number of the column; otherwise zero.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The object ID of the field's data type.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The data type size (see <code class="varname">pg_type.typlen</code>).
+ Note that negative values denote variable-width types.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The type modifier (see <code class="varname">pg_attribute.atttypmod</code>).
+ The meaning of the modifier is type-specific.
+ </p></dd><dt><span class="term">Int16</span></dt><dd><p>
+ The format code being used for the field. Currently will
+ be zero (text) or one (binary). In a RowDescription
+ returned from the statement variant of Describe, the
+ format code is not yet known and will always be zero.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-SASLINITIALRESPONSE"><span class="term">SASLInitialResponse (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as an initial SASL response. Note that
+ this is also used for GSSAPI, SSPI and password response messages.
+ The exact message type is deduced from the context.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ Name of the SASL authentication mechanism that the client
+ selected.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of SASL mechanism specific "Initial Client Response" that
+ follows, or -1 if there is no Initial Response.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ SASL mechanism specific "Initial Response".
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-SASLRESPONSE"><span class="term">SASLResponse (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as a SASL response. Note that
+ this is also used for GSSAPI, SSPI and password response messages.
+ The exact message type can be deduced from the context.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ SASL mechanism specific message data.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-SSLREQUEST"><span class="term">SSLRequest (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32(8)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(80877103)</span></dt><dd><p>
+ The <acronym class="acronym">SSL</acronym> request code. The value is chosen to contain
+ <code class="literal">1234</code> in the most significant 16 bits, and <code class="literal">5679</code> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-STARTUPMESSAGE"><span class="term">StartupMessage (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int32</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd><dt><span class="term">Int32(196608)</span></dt><dd><p>
+ The protocol version number. The most significant 16 bits are
+ the major version number (3 for the protocol described here).
+ The least significant 16 bits are the minor version number
+ (0 for the protocol described here).
+ </p></dd></dl></div><p>
+ The protocol version number is followed by one or more pairs of
+ parameter name and value strings. A zero byte is required as a
+ terminator after the last name/value pair.
+ Parameters can appear in any
+ order. <code class="literal">user</code> is required, others are optional.
+ Each parameter is specified as:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">String</span></dt><dd><p>
+ The parameter name. Currently recognized names are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">user</code></span></dt><dd><p>
+ The database user name to connect as. Required;
+ there is no default.
+ </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>
+ The database to connect to. Defaults to the user name.
+ </p></dd><dt><span class="term"><code class="literal">options</code></span></dt><dd><p>
+ Command-line arguments for the backend. (This is
+ deprecated in favor of setting individual run-time
+ parameters.) Spaces within this string are
+ considered to separate arguments, unless escaped with
+ a backslash (<code class="literal">\</code>); write <code class="literal">\\</code> to
+ represent a literal backslash.
+ </p></dd><dt><span class="term"><code class="literal">replication</code></span></dt><dd><p>
+ Used to connect in streaming replication mode, where
+ a small set of replication commands can be issued
+ instead of SQL statements. Value can be
+ <code class="literal">true</code>, <code class="literal">false</code>, or
+ <code class="literal">database</code>, and the default is
+ <code class="literal">false</code>. See
+ <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> for details.
+ </p></dd></dl></div><p>
+
+ In addition to the above, other parameters may be listed.
+ Parameter names beginning with <code class="literal">_pq_.</code> are
+ reserved for use as protocol extensions, while others are
+ treated as run-time parameters to be set at backend start
+ time. Such settings will be applied during backend start
+ (after parsing the command-line arguments if any) and will
+ act as session defaults.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The parameter value.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-SYNC"><span class="term">Sync (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('S')</span></dt><dd><p>
+ Identifies the message as a Sync command.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-MESSAGE-FORMATS-TERMINATE"><span class="term">Terminate (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('X')</span></dt><dd><p>
+ Identifies the message as a termination.
+ </p></dd><dt><span class="term">Int32(4)</span></dt><dd><p>
+ Length of message contents in bytes, including self.
+ </p></dd></dl></div></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-message-types.html" title="55.6. Message Data Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-error-fields.html" title="55.8. Error and Notice Message Fields">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.6. Message Data Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.8. Error and Notice Message Fields</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-message-types.html b/doc/src/sgml/html/protocol-message-types.html
new file mode 100644
index 0000000..66da871
--- /dev/null
+++ b/doc/src/sgml/html/protocol-message-types.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.6. Message Data Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol" /><link rel="next" href="protocol-message-formats.html" title="55.7. Message Formats" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.6. Message Data Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-message-formats.html" title="55.7. Message Formats">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-MESSAGE-TYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.6. Message Data Types</h2></div></div></div><p>
+ This section describes the base data types used in messages.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Int<em class="replaceable"><code>n</code></em>(<em class="replaceable"><code>i</code></em>)</span></dt><dd><p>
+ An <em class="replaceable"><code>n</code></em>-bit integer in network byte
+ order (most significant byte first).
+ If <em class="replaceable"><code>i</code></em> is specified it
+ is the exact value that will appear, otherwise the value
+ is variable. Eg. Int16, Int32(42).
+ </p></dd><dt><span class="term">Int<em class="replaceable"><code>n</code></em>[<em class="replaceable"><code>k</code></em>]</span></dt><dd><p>
+ An array of <em class="replaceable"><code>k</code></em>
+ <em class="replaceable"><code>n</code></em>-bit integers, each in network
+ byte order. The array length <em class="replaceable"><code>k</code></em>
+ is always determined by an earlier field in the message.
+ Eg. Int16[M].
+ </p></dd><dt><span class="term">String(<em class="replaceable"><code>s</code></em>)</span></dt><dd><p>
+ A null-terminated string (C-style string). There is no
+ specific length limitation on strings.
+ If <em class="replaceable"><code>s</code></em> is specified it is the exact
+ value that will appear, otherwise the value is variable.
+ Eg. String, String("user").
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="emphasis"><em>There is no predefined limit</em></span> on the length of a string
+ that can be returned by the backend. Good coding strategy for a frontend
+ is to use an expandable buffer so that anything that fits in memory can be
+ accepted. If that's not feasible, read the full string and discard trailing
+ characters that don't fit into your fixed-size buffer.
+ </p></div></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em>(<em class="replaceable"><code>c</code></em>)</span></dt><dd><p>
+ Exactly <em class="replaceable"><code>n</code></em> bytes. If the field
+ width <em class="replaceable"><code>n</code></em> is not a constant, it is
+ always determinable from an earlier field in the message.
+ If <em class="replaceable"><code>c</code></em> is specified it is the exact
+ value. Eg. Byte2, Byte1('\n').
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-message-formats.html" title="55.7. Message Formats">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.5. Logical Streaming Replication Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.7. Message Formats</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-overview.html b/doc/src/sgml/html/protocol-overview.html
new file mode 100644
index 0000000..4c35fc3
--- /dev/null
+++ b/doc/src/sgml/html/protocol-overview.html
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol" /><link rel="next" href="protocol-flow.html" title="55.2. Message Flow" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-flow.html" title="55.2. Message Flow">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.1. Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-MESSAGE-CONCEPTS">55.1.1. Messaging Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-QUERY-CONCEPTS">55.1.2. Extended Query Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-FORMAT-CODES">55.1.3. Formats and Format Codes</a></span></dt></dl></div><p>
+ The protocol has separate phases for startup and normal operation.
+ In the startup phase, the frontend opens a connection to the server
+ and authenticates itself to the satisfaction of the server. (This might
+ involve a single message, or multiple messages depending on the
+ authentication method being used.) If all goes well, the server then sends
+ status information to the frontend, and finally enters normal operation.
+ Except for the initial startup-request message, this part of the
+ protocol is driven by the server.
+ </p><p>
+ During normal operation, the frontend sends queries and
+ other commands to the backend, and the backend sends back query results
+ and other responses. There are a few cases (such as <code class="command">NOTIFY</code>)
+ wherein the
+ backend will send unsolicited messages, but for the most part this portion
+ of a session is driven by frontend requests.
+ </p><p>
+ Termination of the session is normally by frontend choice, but can be
+ forced by the backend in certain cases. In any case, when the backend
+ closes the connection, it will roll back any open (incomplete) transaction
+ before exiting.
+ </p><p>
+ Within normal operation, SQL commands can be executed through either of
+ two sub-protocols. In the <span class="quote">“<span class="quote">simple query</span>”</span> protocol, the frontend
+ just sends a textual query string, which is parsed and immediately
+ executed by the backend. In the <span class="quote">“<span class="quote">extended query</span>”</span> protocol,
+ processing of queries is separated into multiple steps: parsing,
+ binding of parameter values, and execution. This offers flexibility
+ and performance benefits, at the cost of extra complexity.
+ </p><p>
+ Normal operation has additional sub-protocols for special operations
+ such as <code class="command">COPY</code>.
+ </p><div class="sect2" id="PROTOCOL-MESSAGE-CONCEPTS"><div class="titlepage"><div><div><h3 class="title">55.1.1. Messaging Overview</h3></div></div></div><p>
+ All communication is through a stream of messages. The first byte of a
+ message identifies the message type, and the next four bytes specify the
+ length of the rest of the message (this length count includes itself, but
+ not the message-type byte). The remaining contents of the message are
+ determined by the message type. For historical reasons, the very first
+ message sent by the client (the startup message) has no initial
+ message-type byte.
+ </p><p>
+ To avoid losing synchronization with the message stream, both servers and
+ clients typically read an entire message into a buffer (using the byte
+ count) before attempting to process its contents. This allows easy
+ recovery if an error is detected while processing the contents. In
+ extreme situations (such as not having enough memory to buffer the
+ message), the receiver can use the byte count to determine how much
+ input to skip before it resumes reading messages.
+ </p><p>
+ Conversely, both servers and clients must take care never to send an
+ incomplete message. This is commonly done by marshaling the entire message
+ in a buffer before beginning to send it. If a communications failure
+ occurs partway through sending or receiving a message, the only sensible
+ response is to abandon the connection, since there is little hope of
+ recovering message-boundary synchronization.
+ </p></div><div class="sect2" id="PROTOCOL-QUERY-CONCEPTS"><div class="titlepage"><div><div><h3 class="title">55.1.2. Extended Query Overview</h3></div></div></div><p>
+ In the extended-query protocol, execution of SQL commands is divided
+ into multiple steps. The state retained between steps is represented
+ by two types of objects: <em class="firstterm">prepared statements</em> and
+ <em class="firstterm">portals</em>. A prepared statement represents the result of
+ parsing and semantic analysis of a textual query string.
+ A prepared statement is not in itself ready to execute, because it might
+ lack specific values for <em class="firstterm">parameters</em>. A portal represents
+ a ready-to-execute or already-partially-executed statement, with any
+ missing parameter values filled in. (For <code class="command">SELECT</code> statements,
+ a portal is equivalent to an open cursor, but we choose to use a different
+ term since cursors don't handle non-<code class="command">SELECT</code> statements.)
+ </p><p>
+ The overall execution cycle consists of a <em class="firstterm">parse</em> step,
+ which creates a prepared statement from a textual query string; a
+ <em class="firstterm">bind</em> step, which creates a portal given a prepared
+ statement and values for any needed parameters; and an
+ <em class="firstterm">execute</em> step that runs a portal's query. In the case of
+ a query that returns rows (<code class="command">SELECT</code>, <code class="command">SHOW</code>, etc.),
+ the execute step can be told to fetch only
+ a limited number of rows, so that multiple execute steps might be needed
+ to complete the operation.
+ </p><p>
+ The backend can keep track of multiple prepared statements and portals
+ (but note that these exist only within a session, and are never shared
+ across sessions). Existing prepared statements and portals are
+ referenced by names assigned when they were created. In addition,
+ an <span class="quote">“<span class="quote">unnamed</span>”</span> prepared statement and portal exist. Although these
+ behave largely the same as named objects, operations on them are optimized
+ for the case of executing a query only once and then discarding it,
+ whereas operations on named objects are optimized on the expectation
+ of multiple uses.
+ </p></div><div class="sect2" id="PROTOCOL-FORMAT-CODES"><div class="titlepage"><div><div><h3 class="title">55.1.3. Formats and Format Codes</h3></div></div></div><p>
+ Data of a particular data type might be transmitted in any of several
+ different <em class="firstterm">formats</em>. As of <span class="productname">PostgreSQL</span> 7.4
+ the only supported formats are <span class="quote">“<span class="quote">text</span>”</span> and <span class="quote">“<span class="quote">binary</span>”</span>,
+ but the protocol makes provision for future extensions. The desired
+ format for any value is specified by a <em class="firstterm">format code</em>.
+ Clients can specify a format code for each transmitted parameter value
+ and for each column of a query result. Text has format code zero,
+ binary has format code one, and all other format codes are reserved
+ for future definition.
+ </p><p>
+ The text representation of values is whatever strings are produced
+ and accepted by the input/output conversion functions for the
+ particular data type. In the transmitted representation, there is
+ no trailing null character; the frontend must add one to received
+ values if it wants to process them as C strings.
+ (The text format does not allow embedded nulls, by the way.)
+ </p><p>
+ Binary representations for integers use network byte order (most
+ significant byte first). For other data types consult the documentation
+ or source code to learn about the binary representation. Keep in mind
+ that binary representations for complex data types might change across
+ server versions; the text format is usually the more portable choice.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-flow.html" title="55.2. Message Flow">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 55. Frontend/Backend Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.2. Message Flow</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol-replication.html b/doc/src/sgml/html/protocol-replication.html
new file mode 100644
index 0000000..6d4dfd4
--- /dev/null
+++ b/doc/src/sgml/html/protocol-replication.html
@@ -0,0 +1,529 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.4. Streaming Replication Protocol</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sasl-authentication.html" title="55.3. SASL Authentication" /><link rel="next" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.4. Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sasl-authentication.html" title="55.3. SASL Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.4. Streaming Replication Protocol</h2></div></div></div><p>
+ To initiate streaming replication, the frontend sends the
+ <code class="literal">replication</code> parameter in the startup message. A Boolean
+ value of <code class="literal">true</code> (or <code class="literal">on</code>,
+ <code class="literal">yes</code>, <code class="literal">1</code>) tells the backend to go into
+ physical replication walsender mode, wherein a small set of replication
+ commands, shown below, can be issued instead of SQL statements.
+ </p><p>
+ Passing <code class="literal">database</code> as the value for the
+ <code class="literal">replication</code> parameter instructs the backend to go into
+ logical replication walsender mode, connecting to the database specified in
+ the <code class="literal">dbname</code> parameter. In logical replication walsender
+ mode, the replication commands shown below as well as normal SQL commands can
+ be issued.
+ </p><p>
+ In either physical replication or logical replication walsender mode, only the
+ simple query protocol can be used.
+ </p><p>
+ For the purpose of testing replication commands, you can make a replication
+ connection via <span class="application">psql</span> or any other
+ <span class="application">libpq</span>-using tool with a connection string including
+ the <code class="literal">replication</code> option,
+ e.g.:
+</p><pre class="programlisting">
+psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
+</pre><p>
+ However, it is often more useful to use
+ <a class="xref" href="app-pgreceivewal.html" title="pg_receivewal"><span class="refentrytitle"><span class="application">pg_receivewal</span></span></a> (for physical replication) or
+ <a class="xref" href="app-pgrecvlogical.html" title="pg_recvlogical"><span class="refentrytitle"><span class="application">pg_recvlogical</span></span></a> (for logical replication).
+ </p><p>
+ Replication commands are logged in the server log when
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-REPLICATION-COMMANDS">log_replication_commands</a> is enabled.
+ </p><p>
+ The commands accepted in replication mode are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-IDENTIFY-SYSTEM"><span class="term"><code class="literal">IDENTIFY_SYSTEM</code>
+ <a id="id-1.10.6.9.7.1.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Requests the server to identify itself. Server replies with a result
+ set of a single row, containing four fields:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">systemid</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The unique system identifier identifying the cluster. This
+ can be used to check that the base backup used to initialize the
+ standby came from the same cluster.
+ </p></dd><dt><span class="term"><code class="literal">timeline</code> (<code class="type">int4</code>)</span></dt><dd><p>
+ Current timeline ID. Also useful to check that the standby is
+ consistent with the primary.
+ </p></dd><dt><span class="term"><code class="literal">xlogpos</code> (<code class="type">text</code>)</span></dt><dd><p>
+ Current WAL flush location. Useful to get a known location in the
+ write-ahead log where streaming can start.
+ </p></dd><dt><span class="term"><code class="literal">dbname</code> (<code class="type">text</code>)</span></dt><dd><p>
+ Database connected to or null.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-SHOW"><span class="term"><code class="literal">SHOW</code> <em class="replaceable"><code>name</code></em>
+ <a id="id-1.10.6.9.7.1.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Requests the server to send the current setting of a run-time parameter.
+ This is similar to the SQL command <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a run-time parameter. Available parameters are documented
+ in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-TIMELINE-HISTORY"><span class="term"><code class="literal">TIMELINE_HISTORY</code> <em class="replaceable"><code>tli</code></em>
+ <a id="id-1.10.6.9.7.1.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Requests the server to send over the timeline history file for timeline
+ <em class="replaceable"><code>tli</code></em>. Server replies with a
+ result set of a single row, containing two fields. While the fields
+ are labeled as <code class="type">text</code>, they effectively return raw bytes,
+ with no encoding conversion:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">filename</code> (<code class="type">text</code>)</span></dt><dd><p>
+ File name of the timeline history file, e.g., <code class="filename">00000002.history</code>.
+ </p></dd><dt><span class="term"><code class="literal">content</code> (<code class="type">text</code>)</span></dt><dd><p>
+ Contents of the timeline history file.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT"><span class="term"><code class="literal">CREATE_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [ <code class="literal">TEMPORARY</code> ] { <code class="literal">PHYSICAL</code> | <code class="literal">LOGICAL</code> <em class="replaceable"><code>output_plugin</code></em> } [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+ <a id="id-1.10.6.9.7.1.4.1.8" class="indexterm"></a>
+ </span></dt><dd><p>
+ Create a physical or logical replication
+ slot. See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a> for more about
+ replication slots.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
+ The name of the slot to create. Must be a valid replication slot
+ name (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS-MANIPULATION" title="27.2.6.1. Querying and Manipulating Replication Slots">Section 27.2.6.1</a>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_plugin</code></em></span></dt><dd><p>
+ The name of the output plugin used for logical decoding
+ (see <a class="xref" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Section 49.6</a>).
+ </p></dd><dt><span class="term"><code class="literal">TEMPORARY</code></span></dt><dd><p>
+ Specify that this replication slot is a temporary one. Temporary
+ slots are not saved to disk and are automatically dropped on error
+ or when the session has finished.
+ </p></dd></dl></div><p>The following options are supported:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TWO_PHASE [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If true, this logical replication slot supports decoding of two-phase
+ commit. With this option, commands related to two-phase commit such as
+ <code class="literal">PREPARE TRANSACTION</code>, <code class="literal">COMMIT PREPARED</code>
+ and <code class="literal">ROLLBACK PREPARED</code> are decoded and transmitted.
+ The transaction will be decoded and transmitted at
+ <code class="literal">PREPARE TRANSACTION</code> time.
+ The default is false.
+ </p></dd><dt><span class="term"><code class="literal">RESERVE_WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If true, this physical replication slot reserves <acronym class="acronym">WAL</acronym>
+ immediately. Otherwise, <acronym class="acronym">WAL</acronym> is only reserved upon
+ connection from a streaming replication client.
+ The default is false.
+ </p></dd><dt><span class="term"><code class="literal">SNAPSHOT { 'export' | 'use' | 'nothing' }</code></span></dt><dd><p>
+ Decides what to do with the snapshot created during logical slot
+ initialization. <code class="literal">'export'</code>, which is the default,
+ will export the snapshot for use in other sessions. This option can't
+ be used inside a transaction. <code class="literal">'use'</code> will use the
+ snapshot for the current transaction executing the command. This
+ option must be used in a transaction, and
+ <code class="literal">CREATE_REPLICATION_SLOT</code> must be the first command
+ run in that transaction. Finally, <code class="literal">'nothing'</code> will
+ just use the snapshot for logical decoding as normal but won't do
+ anything else with it.
+ </p></dd></dl></div><p>
+ In response to this command, the server will send a one-row result set
+ containing the following fields:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">slot_name</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The name of the newly-created replication slot.
+ </p></dd><dt><span class="term"><code class="literal">consistent_point</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The WAL location at which the slot became consistent. This is the
+ earliest location from which streaming can start on this replication
+ slot.
+ </p></dd><dt><span class="term"><code class="literal">snapshot_name</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The identifier of the snapshot exported by the command. The
+ snapshot is valid until a new command is executed on this connection
+ or the replication connection is closed. Null if the created slot
+ is physical.
+ </p></dd><dt><span class="term"><code class="literal">output_plugin</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The name of the output plugin used by the newly-created replication
+ slot. Null if the created slot is physical.
+ </p></dd></dl></div><p>
+ </p></dd><dt id="PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT-LEGACY"><span class="term"><code class="literal">CREATE_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [ <code class="literal">TEMPORARY</code> ] { <code class="literal">PHYSICAL</code> [ <code class="literal">RESERVE_WAL</code> ] | <code class="literal">LOGICAL</code> <em class="replaceable"><code>output_plugin</code></em> [ <code class="literal">EXPORT_SNAPSHOT</code> | <code class="literal">NOEXPORT_SNAPSHOT</code> | <code class="literal">USE_SNAPSHOT</code> | <code class="literal">TWO_PHASE</code> ] }
+ </span></dt><dd><p>
+ For compatibility with older releases, this alternative syntax for
+ the <code class="literal">CREATE_REPLICATION_SLOT</code> command is still supported.
+ </p></dd><dt id="PROTOCOL-REPLICATION-READ-REPLICATION-SLOT"><span class="term"><code class="literal">READ_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em>
+ <a id="id-1.10.6.9.7.1.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Read some information associated with a replication slot. Returns a tuple
+ with <code class="literal">NULL</code> values if the replication slot does not
+ exist. This command is currently only supported for physical replication
+ slots.
+ </p><p>
+ In response to this command, the server will return a one-row result set,
+ containing the following fields:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">slot_type</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The replication slot's type, either <code class="literal">physical</code> or
+ <code class="literal">NULL</code>.
+ </p></dd><dt><span class="term"><code class="literal">restart_lsn</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The replication slot's <code class="literal">restart_lsn</code>.
+ </p></dd><dt><span class="term"><code class="literal">restart_tli</code> (<code class="type">int8</code>)</span></dt><dd><p>
+ The timeline ID associated with <code class="literal">restart_lsn</code>,
+ following the current timeline history.
+ </p></dd></dl></div><p>
+ </p></dd><dt id="PROTOCOL-REPLICATION-START-REPLICATION"><span class="term"><code class="literal">START_REPLICATION</code> [ <code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em> ] [ <code class="literal">PHYSICAL</code> ] <em class="replaceable"><code>XXX/XXX</code></em> [ <code class="literal">TIMELINE</code> <em class="replaceable"><code>tli</code></em> ]
+ <a id="id-1.10.6.9.7.1.7.1.8" class="indexterm"></a>
+ </span></dt><dd><p>
+ Instructs server to start streaming WAL, starting at
+ WAL location <em class="replaceable"><code>XXX/XXX</code></em>.
+ If <code class="literal">TIMELINE</code> option is specified,
+ streaming starts on timeline <em class="replaceable"><code>tli</code></em>;
+ otherwise, the server's current timeline is selected. The server can
+ reply with an error, for example if the requested section of WAL has already
+ been recycled. On success, the server responds with a CopyBothResponse
+ message, and then starts to stream WAL to the frontend.
+ </p><p>
+ If a slot's name is provided
+ via <em class="replaceable"><code>slot_name</code></em>, it will be updated
+ as replication progresses so that the server knows which WAL segments,
+ and if <code class="varname">hot_standby_feedback</code> is on which transactions,
+ are still needed by the standby.
+ </p><p>
+ If the client requests a timeline that's not the latest but is part of
+ the history of the server, the server will stream all the WAL on that
+ timeline starting from the requested start point up to the point where
+ the server switched to another timeline. If the client requests
+ streaming at exactly the end of an old timeline, the server skips COPY
+ mode entirely.
+ </p><p>
+ After streaming all the WAL on a timeline that is not the latest one,
+ the server will end streaming by exiting the COPY mode. When the client
+ acknowledges this by also exiting COPY mode, the server sends a result
+ set with one row and two columns, indicating the next timeline in this
+ server's history. The first column is the next timeline's ID (type <code class="type">int8</code>), and the
+ second column is the WAL location where the switch happened (type <code class="type">text</code>). Usually,
+ the switch position is the end of the WAL that was streamed, but there
+ are corner cases where the server can send some WAL from the old
+ timeline that it has not itself replayed before promoting. Finally, the
+ server sends two CommandComplete messages (one that ends the CopyData
+ and the other ends the <code class="literal">START_REPLICATION</code> itself), and
+ is ready to accept a new command.
+ </p><p>
+ WAL data is sent as a series of CopyData messages. (This allows
+ other information to be intermixed; in particular the server can send
+ an ErrorResponse message if it encounters a failure after beginning
+ to stream.) The payload of each CopyData message from server to the
+ client contains a message of one of the following formats:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-XLOGDATA"><span class="term">XLogData (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('w')</span></dt><dd><p>
+ Identifies the message as WAL data.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The starting point of the WAL data in this message.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The current end of WAL on the server.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The server's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ A section of the WAL data stream.
+ </p><p>
+ A single WAL record is never split across two XLogData messages.
+ When a WAL record crosses a WAL page boundary, and is therefore
+ already split using continuation records, it can be split at the page
+ boundary. In other words, the first main WAL record and its
+ continuation records can be sent in different XLogData messages.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-PRIMARY-KEEPALIVE-MESSAGE"><span class="term">Primary keepalive message (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('k')</span></dt><dd><p>
+ Identifies the message as a sender keepalive.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The current end of WAL on the server.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The server's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
+ 1 means that the client should reply to this message as soon as
+ possible, to avoid a timeout disconnect. 0 otherwise.
+ </p></dd></dl></div></dd></dl></div><p>
+ The receiving process can send replies back to the sender at any time,
+ using one of the following message formats (also in the payload of a
+ CopyData message):
+ </p><div class="variablelist"><dl class="variablelist"><dt id="PROTOCOL-REPLICATION-STANDBY-STATUS-UPDATE"><span class="term">Standby status update (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('r')</span></dt><dd><p>
+ Identifies the message as a receiver status update.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The location of the last WAL byte + 1 received and written to disk
+ in the standby.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The location of the last WAL byte + 1 flushed to disk in
+ the standby.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The location of the last WAL byte + 1 applied in the standby.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The client's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </p></dd><dt><span class="term">Byte1</span></dt><dd><p>
+ If 1, the client requests the server to reply to this message
+ immediately. This can be used to ping the server, to test if
+ the connection is still healthy.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-HOT-STANDBY-FEEDBACK-MESSAGE"><span class="term">Hot standby feedback message (F)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('h')</span></dt><dd><p>
+ Identifies the message as a hot standby feedback message.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The client's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The standby's current global xmin, excluding the catalog_xmin from any
+ replication slots. If both this value and the following
+ catalog_xmin are 0 this is treated as a notification that hot standby
+ feedback will no longer be sent on this connection. Later non-zero
+ messages may reinitiate the feedback mechanism.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The epoch of the global xmin xid on the standby.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The lowest catalog_xmin of any replication slots on the standby. Set to 0
+ if no catalog_xmin exists on the standby or if hot standby feedback is being
+ disabled.
+ </p></dd><dt><span class="term">Int32</span></dt><dd><p>
+ The epoch of the catalog_xmin xid on the standby.
+ </p></dd></dl></div></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-START-REPLICATION-SLOT-LOGICAL"><span class="term"><code class="literal">START_REPLICATION</code> <code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em> <code class="literal">LOGICAL</code> <em class="replaceable"><code>XXX/XXX</code></em> [ ( <em class="replaceable"><code>option_name</code></em> [ <em class="replaceable"><code>option_value</code></em> ] [, ...] ) ]</span></dt><dd><p>
+ Instructs server to start streaming WAL for logical replication,
+ starting at either WAL location <em class="replaceable"><code>XXX/XXX</code></em> or the slot's
+ <code class="literal">confirmed_flush_lsn</code> (see <a class="xref" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Section 54.19</a>), whichever is greater. This
+ behavior makes it easier for clients to avoid updating their local LSN
+ status when there is no data to process. However, starting at a
+ different LSN than requested might not catch certain kinds of client
+ errors; so the client may wish to check that
+ <code class="literal">confirmed_flush_lsn</code> matches its expectations before
+ issuing <code class="literal">START_REPLICATION</code>.
+ </p><p>
+ The server can reply with an error, for example if the
+ slot does not exist. On success, the server responds with a CopyBothResponse
+ message, and then starts to stream WAL to the frontend.
+ </p><p>
+ The messages inside the CopyBothResponse messages are of the same format
+ documented for <code class="literal">START_REPLICATION ... PHYSICAL</code>, including
+ two CommandComplete messages.
+ </p><p>
+ The output plugin associated with the selected slot is used
+ to process the output for streaming.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
+ The name of the slot to stream changes from. This parameter is required,
+ and must correspond to an existing logical replication slot created
+ with <code class="literal">CREATE_REPLICATION_SLOT</code> in
+ <code class="literal">LOGICAL</code> mode.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>XXX/XXX</code></em></span></dt><dd><p>
+ The WAL location to begin streaming at.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>option_name</code></em></span></dt><dd><p>
+ The name of an option passed to the slot's logical decoding plugin.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>option_value</code></em></span></dt><dd><p>
+ Optional value, in the form of a string constant, associated with the
+ specified option.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-DROP-REPLICATION-SLOT"><span class="term">
+ <code class="literal">DROP_REPLICATION_SLOT</code> <em class="replaceable"><code>slot_name</code></em> [<span class="optional"> <code class="literal">WAIT</code> </span>]
+ <a id="id-1.10.6.9.7.1.9.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Drops a replication slot, freeing any reserved server-side resources.
+ If the slot is a logical slot that was created in a database other than
+ the database the walsender is connected to, this command fails.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>slot_name</code></em></span></dt><dd><p>
+ The name of the slot to drop.
+ </p></dd><dt><span class="term"><code class="literal">WAIT</code></span></dt><dd><p>
+ This option causes the command to wait if the slot is active until
+ it becomes inactive, instead of the default behavior of raising an
+ error.
+ </p></dd></dl></div></dd><dt id="PROTOCOL-REPLICATION-BASE-BACKUP"><span class="term"><code class="literal">BASE_BACKUP</code> [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+ <a id="id-1.10.6.9.7.1.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Instructs the server to start streaming a base backup.
+ The system will automatically be put in backup mode before the backup
+ is started, and taken out of it when the backup is complete. The
+ following options are accepted:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">LABEL</code> <em class="replaceable"><code>'label'</code></em></span></dt><dd><p>
+ Sets the label of the backup. If none is specified, a backup label
+ of <code class="literal">base backup</code> will be used. The quoting rules
+ for the label are the same as a standard SQL string with
+ <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> turned on.
+ </p></dd><dt><span class="term"><code class="literal">TARGET</code> <em class="replaceable"><code>'target'</code></em></span></dt><dd><p>
+ Tells the server where to send the backup. If the target is
+ <code class="literal">client</code>, which is the default, the backup data is
+ sent to the client. If it is <code class="literal">server</code>, the backup
+ data is written to the server at the pathname specified by the
+ <code class="literal">TARGET_DETAIL</code> option. If it is
+ <code class="literal">blackhole</code>, the backup data is not sent
+ anywhere; it is simply discarded.
+ </p><p>
+ The <code class="literal">server</code> target requires superuser privilege or
+ being granted the <code class="literal">pg_write_server_files</code> role.
+ </p></dd><dt><span class="term"><code class="literal">TARGET_DETAIL</code> <em class="replaceable"><code>'detail'</code></em></span></dt><dd><p>
+ Provides additional information about the backup target.
+ </p><p>
+ Currently, this option can only be used when the backup target is
+ <code class="literal">server</code>. It specifies the server directory
+ to which the backup should be written.
+ </p></dd><dt><span class="term"><code class="literal">PROGRESS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If set to true, request information required to generate a progress
+ report. This will send back an approximate size in the header of each
+ tablespace, which can be used to calculate how far along the stream
+ is done. This is calculated by enumerating all the file sizes once
+ before the transfer is even started, and might as such have a
+ negative impact on the performance. In particular, it might take
+ longer before the first data
+ is streamed. Since the database files can change during the backup,
+ the size is only approximate and might both grow and shrink between
+ the time of approximation and the sending of the actual files.
+ The default is false.
+ </p></dd><dt><span class="term"><code class="literal">CHECKPOINT { 'fast' | 'spread' }</code></span></dt><dd><p>
+ Sets the type of checkpoint to be performed at the beginning of the
+ base backup. The default is <code class="literal">spread</code>.
+ </p></dd><dt><span class="term"><code class="literal">WAL [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If set to true, include the necessary WAL segments in the backup.
+ This will include all the files between start and stop backup in the
+ <code class="filename">pg_wal</code> directory of the base directory tar
+ file. The default is false.
+ </p></dd><dt><span class="term"><code class="literal">WAIT [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If set to true, the backup will wait until the last required WAL
+ segment has been archived, or emit a warning if log archiving is
+ not enabled. If false, the backup will neither wait nor warn,
+ leaving the client responsible for ensuring the required log is
+ available. The default is true.
+ </p></dd><dt><span class="term"><code class="literal">COMPRESSION</code> <em class="replaceable"><code>'method'</code></em></span></dt><dd><p>
+ Instructs the server to compress the backup using the specified
+ method. Currently, the supported methods are <code class="literal">gzip</code>,
+ <code class="literal">lz4</code>, and <code class="literal">zstd</code>.
+ </p></dd><dt><span class="term"><code class="literal">COMPRESSION_DETAIL</code> <em class="replaceable"><code>detail</code></em></span></dt><dd><p>
+ Specifies details for the chosen compression method. This should only
+ be used in conjunction with the <code class="literal">COMPRESSION</code>
+ option. If the value is an integer, it specifies the compression
+ level. Otherwise, it should be a comma-separated list of items,
+ each of the form <em class="replaceable"><code>keyword</code></em> or
+ <em class="replaceable"><code>keyword=value</code></em>. Currently, the supported
+ keywords are <code class="literal">level</code> and <code class="literal">workers</code>.
+ </p><p>
+ The <code class="literal">level</code> keyword sets the compression level.
+ For <code class="literal">gzip</code> the compression level should be an
+ integer between <code class="literal">1</code> and <code class="literal">9</code>
+ (default <code class="literal">Z_DEFAULT_COMPRESSION</code> or
+ <code class="literal">-1</code>), for <code class="literal">lz4</code> an integer
+ between 1 and 12 (default <code class="literal">0</code> for fast compression
+ mode), and for <code class="literal">zstd</code> an integer between
+ <code class="literal">ZSTD_minCLevel()</code> (usually <code class="literal">-131072</code>)
+ and <code class="literal">ZSTD_maxCLevel()</code> (usually <code class="literal">22</code>),
+ (default <code class="literal">ZSTD_CLEVEL_DEFAULT</code> or
+ <code class="literal">3</code>).
+ </p><p>
+ The <code class="literal">workers</code> keyword sets the number of threads
+ that should be used for parallel compression. Parallel compression
+ is supported only for <code class="literal">zstd</code>.
+ </p></dd><dt><span class="term"><code class="literal">MAX_RATE</code> <em class="replaceable"><code>rate</code></em></span></dt><dd><p>
+ Limit (throttle) the maximum amount of data transferred from server
+ to client per unit of time. The expected unit is kilobytes per second.
+ If this option is specified, the value must either be equal to zero
+ or it must fall within the range from 32 kB through 1 GB (inclusive).
+ If zero is passed or the option is not specified, no restriction is
+ imposed on the transfer.
+ </p></dd><dt><span class="term"><code class="literal">TABLESPACE_MAP [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If true, include information about symbolic links present in the
+ directory <code class="filename">pg_tblspc</code> in a file named
+ <code class="filename">tablespace_map</code>. The tablespace map file includes
+ each symbolic link name as it exists in the directory
+ <code class="filename">pg_tblspc/</code> and the full path of that symbolic link.
+ The default is false.
+ </p></dd><dt><span class="term"><code class="literal">VERIFY_CHECKSUMS [ <em class="replaceable"><code>boolean</code></em> ]</code></span></dt><dd><p>
+ If true, checksums are verified during a base backup if they are
+ enabled. If false, this is skipped. The default is true.
+ </p></dd><dt><span class="term"><code class="literal">MANIFEST</code> <em class="replaceable"><code>manifest_option</code></em></span></dt><dd><p>
+ When this option is specified with a value of <code class="literal">yes</code>
+ or <code class="literal">force-encode</code>, a backup manifest is created
+ and sent along with the backup. The manifest is a list of every
+ file present in the backup with the exception of any WAL files that
+ may be included. It also stores the size, last modification time, and
+ optionally a checksum for each file.
+ A value of <code class="literal">force-encode</code> forces all filenames
+ to be hex-encoded; otherwise, this type of encoding is performed only
+ for files whose names are non-UTF8 octet sequences.
+ <code class="literal">force-encode</code> is intended primarily for testing
+ purposes, to be sure that clients which read the backup manifest
+ can handle this case. For compatibility with previous releases,
+ the default is <code class="literal">MANIFEST 'no'</code>.
+ </p></dd><dt><span class="term"><code class="literal">MANIFEST_CHECKSUMS</code> <em class="replaceable"><code>checksum_algorithm</code></em></span></dt><dd><p>
+ Specifies the checksum algorithm that should be applied to each file included
+ in the backup manifest. Currently, the available
+ algorithms are <code class="literal">NONE</code>, <code class="literal">CRC32C</code>,
+ <code class="literal">SHA224</code>, <code class="literal">SHA256</code>,
+ <code class="literal">SHA384</code>, and <code class="literal">SHA512</code>.
+ The default is <code class="literal">CRC32C</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ When the backup is started, the server will first send two
+ ordinary result sets, followed by one or more CopyOutResponse
+ results.
+ </p><p>
+ The first ordinary result set contains the starting position of the
+ backup, in a single row with two columns. The first column contains
+ the start position given in XLogRecPtr format, and the second column
+ contains the corresponding timeline ID.
+ </p><p>
+ The second ordinary result set has one row for each tablespace.
+ The fields in this row are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">spcoid</code> (<code class="type">oid</code>)</span></dt><dd><p>
+ The OID of the tablespace, or null if it's the base
+ directory.
+ </p></dd><dt><span class="term"><code class="literal">spclocation</code> (<code class="type">text</code>)</span></dt><dd><p>
+ The full path of the tablespace directory, or null
+ if it's the base directory.
+ </p></dd><dt><span class="term"><code class="literal">size</code> (<code class="type">int8</code>)</span></dt><dd><p>
+ The approximate size of the tablespace, in kilobytes (1024 bytes),
+ if progress report has been requested; otherwise it's null.
+ </p></dd></dl></div><p>
+ </p><p>
+ After the second regular result set, a CopyOutResponse will be sent.
+ The payload of each CopyData message will contain a message in one of
+ the following formats:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">new archive (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('n')</span></dt><dd><p>
+ Identifies the message as indicating the start of a new archive.
+ There will be one archive for the main data directory and one
+ for each additional tablespace; each will use tar format
+ (following the <span class="quote">“<span class="quote">ustar interchange format</span>”</span> specified
+ in the POSIX 1003.1-2008 standard).
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ The file name for this archive.
+ </p></dd><dt><span class="term">String</span></dt><dd><p>
+ For the main data directory, an empty string. For other
+ tablespaces, the full path to the directory from which this
+ archive was created.
+ </p></dd></dl></div></dd><dt><span class="term">manifest (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('m')</span></dt><dd><p>
+ Identifies the message as indicating the start of the backup
+ manifest.
+ </p></dd></dl></div></dd><dt><span class="term">archive or manifest data (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('d')</span></dt><dd><p>
+ Identifies the message as containing archive or manifest data.
+ </p></dd><dt><span class="term">Byte<em class="replaceable"><code>n</code></em></span></dt><dd><p>
+ Data bytes.
+ </p></dd></dl></div></dd><dt><span class="term">progress report (B)</span></dt><dd><div class="variablelist"><dl class="variablelist"><dt><span class="term">Byte1('p')</span></dt><dd><p>
+ Identifies the message as a progress report.
+ </p></dd><dt><span class="term">Int64</span></dt><dd><p>
+ The number of bytes from the current tablespace for which
+ processing has been completed.
+ </p></dd></dl></div></dd></dl></div><p>
+ After the CopyOutResponse, or all such responses, have been sent, a
+ final ordinary result set will be sent, containing the WAL end position
+ of the backup, in the same format as the start position.
+ </p><p>
+ The tar archive for the data directory and each tablespace will contain
+ all files in the directories, regardless of whether they are
+ <span class="productname">PostgreSQL</span> files or other files added to the same
+ directory. The only excluded files are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <code class="filename">postmaster.pid</code>
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="filename">postmaster.opts</code>
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="filename">pg_internal.init</code> (found in multiple directories)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Various temporary files and directories created during the operation
+ of the PostgreSQL server, such as any file or directory beginning
+ with <code class="filename">pgsql_tmp</code> and temporary relations.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Unlogged relations, except for the init fork which is required to
+ recreate the (empty) unlogged relation on recovery.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="filename">pg_wal</code>, including subdirectories. If the backup is run
+ with WAL files included, a synthesized version of <code class="filename">pg_wal</code> will be
+ included, but it will only contain the files necessary for the
+ backup to work, not the rest of the contents.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="filename">pg_dynshmem</code>, <code class="filename">pg_notify</code>,
+ <code class="filename">pg_replslot</code>, <code class="filename">pg_serial</code>,
+ <code class="filename">pg_snapshots</code>, <code class="filename">pg_stat_tmp</code>, and
+ <code class="filename">pg_subtrans</code> are copied as empty directories (even if
+ they are symbolic links).
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Files other than regular files and directories, such as symbolic
+ links (other than for the directories listed above) and special
+ device files, are skipped. (Symbolic links
+ in <code class="filename">pg_tblspc</code> are maintained.)
+ </p></li></ul></div><p>
+ Owner, group, and file mode are set if the underlying file system on
+ the server supports it.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sasl-authentication.html" title="55.3. SASL Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-logical-replication.html" title="55.5. Logical Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.3. SASL Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.5. Logical Streaming Replication Protocol</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/protocol.html b/doc/src/sgml/html/protocol.html
new file mode 100644
index 0000000..0dd9eb4
--- /dev/null
+++ b/doc/src/sgml/html/protocol.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 55. Frontend/Backend Protocol</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-views.html" title="54.35. pg_views" /><link rel="next" href="protocol-overview.html" title="55.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 55. Frontend/Backend Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-views.html" title="54.35. pg_views">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-overview.html" title="55.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="PROTOCOL"><div class="titlepage"><div><div><h2 class="title">Chapter 55. Frontend/Backend Protocol</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="protocol-overview.html">55.1. Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-MESSAGE-CONCEPTS">55.1.1. Messaging Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-QUERY-CONCEPTS">55.1.2. Extended Query Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-FORMAT-CODES">55.1.3. Formats and Format Codes</a></span></dt></dl></dd><dt><span class="sect1"><a href="protocol-flow.html">55.2. Message Flow</a></span></dt><dd><dl><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.3">55.2.1. Start-up</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.4">55.2.2. Simple Query</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY">55.2.3. Extended Query</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-FLOW-PIPELINING">55.2.4. Pipelining</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.7">55.2.5. Function Call</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-COPY">55.2.6. COPY Operations</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#PROTOCOL-ASYNC">55.2.7. Asynchronous Operations</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.10">55.2.8. Canceling Requests in Progress</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.11">55.2.9. Termination</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.12">55.2.10. <acronym class="acronym">SSL</acronym> Session Encryption</a></span></dt><dt><span class="sect2"><a href="protocol-flow.html#id-1.10.6.7.13">55.2.11. <acronym class="acronym">GSSAPI</acronym> Session Encryption</a></span></dt></dl></dd><dt><span class="sect1"><a href="sasl-authentication.html">55.3. SASL Authentication</a></span></dt><dd><dl><dt><span class="sect2"><a href="sasl-authentication.html#SASL-SCRAM-SHA-256">55.3.1. SCRAM-SHA-256 Authentication</a></span></dt></dl></dd><dt><span class="sect1"><a href="protocol-replication.html">55.4. Streaming Replication Protocol</a></span></dt><dt><span class="sect1"><a href="protocol-logical-replication.html">55.5. Logical Streaming Replication Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS">55.5.1. Logical Streaming Replication Parameters</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES">55.5.2. Logical Replication Protocol Messages</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES-FLOW">55.5.3. Logical Replication Protocol Message Flow</a></span></dt></dl></dd><dt><span class="sect1"><a href="protocol-message-types.html">55.6. Message Data Types</a></span></dt><dt><span class="sect1"><a href="protocol-message-formats.html">55.7. Message Formats</a></span></dt><dt><span class="sect1"><a href="protocol-error-fields.html">55.8. Error and Notice Message Fields</a></span></dt><dt><span class="sect1"><a href="protocol-logicalrep-message-formats.html">55.9. Logical Replication Message Formats</a></span></dt><dt><span class="sect1"><a href="protocol-changes.html">55.10. Summary of Changes since Protocol 2.0</a></span></dt></dl></div><a id="id-1.10.6.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> uses a message-based protocol
+ for communication between frontends and backends (clients and servers).
+ The protocol is supported over <acronym class="acronym">TCP/IP</acronym> and also over
+ Unix-domain sockets. Port number 5432 has been registered with IANA as
+ the customary TCP port number for servers supporting this protocol, but
+ in practice any non-privileged port number can be used.
+ </p><p>
+ This document describes version 3.0 of the protocol, implemented in
+ <span class="productname">PostgreSQL</span> 7.4 and later. For descriptions
+ of the earlier protocol versions, see previous releases of the
+ <span class="productname">PostgreSQL</span> documentation. A single server
+ can support multiple protocol versions. The initial startup-request
+ message tells the server which protocol version the client is attempting to
+ use. If the major version requested by the client is not supported by
+ the server, the connection will be rejected (for example, this would occur
+ if the client requested protocol version 4.0, which does not exist as of
+ this writing). If the minor version requested by the client is not
+ supported by the server (e.g., the client requests version 3.1, but the
+ server supports only 3.0), the server may either reject the connection or
+ may respond with a NegotiateProtocolVersion message containing the highest
+ minor protocol version which it supports. The client may then choose either
+ to continue with the connection using the specified protocol version or
+ to abort the connection.
+ </p><p>
+ In order to serve multiple clients efficiently, the server launches
+ a new <span class="quote">“<span class="quote">backend</span>”</span> process for each client.
+ In the current implementation, a new child
+ process is created immediately after an incoming connection is detected.
+ This is transparent to the protocol, however. For purposes of the
+ protocol, the terms <span class="quote">“<span class="quote">backend</span>”</span> and <span class="quote">“<span class="quote">server</span>”</span> are
+ interchangeable; likewise <span class="quote">“<span class="quote">frontend</span>”</span> and <span class="quote">“<span class="quote">client</span>”</span>
+ are interchangeable.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-views.html" title="54.35. pg_views">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-overview.html" title="55.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.35. <code class="structname">pg_views</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-limit.html b/doc/src/sgml/html/queries-limit.html
new file mode 100644
index 0000000..d2880bd
--- /dev/null
+++ b/doc/src/sgml/html/queries-limit.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.6. LIMIT and OFFSET</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)" /><link rel="next" href="queries-values.html" title="7.7. VALUES Lists" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-values.html" title="7.7. VALUES Lists">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-LIMIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></h2></div></div></div><a id="id-1.5.6.10.2" class="indexterm"></a><a id="id-1.5.6.10.3" class="indexterm"></a><p>
+ <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code> allow you to retrieve just
+ a portion of the rows that are generated by the rest of the query:
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_list</code></em>
+ FROM <em class="replaceable"><code>table_expression</code></em>
+ [<span class="optional"> ORDER BY ... </span>]
+ [<span class="optional"> LIMIT { <em class="replaceable"><code>number</code></em> | ALL } </span>] [<span class="optional"> OFFSET <em class="replaceable"><code>number</code></em> </span>]
+</pre><p>
+ </p><p>
+ If a limit count is given, no more than that many rows will be
+ returned (but possibly fewer, if the query itself yields fewer rows).
+ <code class="literal">LIMIT ALL</code> is the same as omitting the <code class="literal">LIMIT</code>
+ clause, as is <code class="literal">LIMIT</code> with a NULL argument.
+ </p><p>
+ <code class="literal">OFFSET</code> says to skip that many rows before beginning to
+ return rows. <code class="literal">OFFSET 0</code> is the same as omitting the
+ <code class="literal">OFFSET</code> clause, as is <code class="literal">OFFSET</code> with a NULL argument.
+ </p><p>
+ If both <code class="literal">OFFSET</code>
+ and <code class="literal">LIMIT</code> appear, then <code class="literal">OFFSET</code> rows are
+ skipped before starting to count the <code class="literal">LIMIT</code> rows that
+ are returned.
+ </p><p>
+ When using <code class="literal">LIMIT</code>, it is important to use an
+ <code class="literal">ORDER BY</code> clause that constrains the result rows into a
+ unique order. Otherwise you will get an unpredictable subset of
+ the query's rows. You might be asking for the tenth through
+ twentieth rows, but tenth through twentieth in what ordering? The
+ ordering is unknown, unless you specified <code class="literal">ORDER BY</code>.
+ </p><p>
+ The query optimizer takes <code class="literal">LIMIT</code> into account when
+ generating query plans, so you are very likely to get different
+ plans (yielding different row orders) depending on what you give
+ for <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code>. Thus, using
+ different <code class="literal">LIMIT</code>/<code class="literal">OFFSET</code> values to select
+ different subsets of a query result <span class="emphasis"><em>will give
+ inconsistent results</em></span> unless you enforce a predictable
+ result ordering with <code class="literal">ORDER BY</code>. This is not a bug; it
+ is an inherent consequence of the fact that SQL does not promise to
+ deliver the results of a query in any particular order unless
+ <code class="literal">ORDER BY</code> is used to constrain the order.
+ </p><p>
+ The rows skipped by an <code class="literal">OFFSET</code> clause still have to be
+ computed inside the server; therefore a large <code class="literal">OFFSET</code>
+ might be inefficient.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-values.html" title="7.7. VALUES Lists">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.5. Sorting Rows (<code class="literal">ORDER BY</code>) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.7. <code class="literal">VALUES</code> Lists</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-order.html b/doc/src/sgml/html/queries-order.html
new file mode 100644
index 0000000..8823e99
--- /dev/null
+++ b/doc/src/sgml/html/queries-order.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.5. Sorting Rows (ORDER BY)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)" /><link rel="next" href="queries-limit.html" title="7.6. LIMIT and OFFSET" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.5. Sorting Rows (<code class="literal">ORDER BY</code>)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-limit.html" title="7.6. LIMIT and OFFSET">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-ORDER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.5. Sorting Rows (<code class="literal">ORDER BY</code>)</h2></div></div></div><a id="id-1.5.6.9.2" class="indexterm"></a><a id="id-1.5.6.9.3" class="indexterm"></a><p>
+ After a query has produced an output table (after the select list
+ has been processed) it can optionally be sorted. If sorting is not
+ chosen, the rows will be returned in an unspecified order. The actual
+ order in that case will depend on the scan and join plan types and
+ the order on disk, but it must not be relied on. A particular
+ output ordering can only be guaranteed if the sort step is explicitly
+ chosen.
+ </p><p>
+ The <code class="literal">ORDER BY</code> clause specifies the sort order:
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_list</code></em>
+ FROM <em class="replaceable"><code>table_expression</code></em>
+ ORDER BY <em class="replaceable"><code>sort_expression1</code></em> [<span class="optional">ASC | DESC</span>] [<span class="optional">NULLS { FIRST | LAST }</span>]
+ [<span class="optional">, <em class="replaceable"><code>sort_expression2</code></em> [<span class="optional">ASC | DESC</span>] [<span class="optional">NULLS { FIRST | LAST }</span>] ...</span>]
+</pre><p>
+ The sort expression(s) can be any expression that would be valid in the
+ query's select list. An example is:
+</p><pre class="programlisting">
+SELECT a, b FROM table1 ORDER BY a + b, c;
+</pre><p>
+ When more than one expression is specified,
+ the later values are used to sort rows that are equal according to the
+ earlier values. Each expression can be followed by an optional
+ <code class="literal">ASC</code> or <code class="literal">DESC</code> keyword to set the sort direction to
+ ascending or descending. <code class="literal">ASC</code> order is the default.
+ Ascending order puts smaller values first, where
+ <span class="quote">“<span class="quote">smaller</span>”</span> is defined in terms of the
+ <code class="literal">&lt;</code> operator. Similarly, descending order is
+ determined with the <code class="literal">&gt;</code> operator.
+ <a href="#ftn.id-1.5.6.9.5.10" class="footnote"><sup class="footnote" id="id-1.5.6.9.5.10">[6]</sup></a>
+ </p><p>
+ The <code class="literal">NULLS FIRST</code> and <code class="literal">NULLS LAST</code> options can be
+ used to determine whether nulls appear before or after non-null values
+ in the sort ordering. By default, null values sort as if larger than any
+ non-null value; that is, <code class="literal">NULLS FIRST</code> is the default for
+ <code class="literal">DESC</code> order, and <code class="literal">NULLS LAST</code> otherwise.
+ </p><p>
+ Note that the ordering options are considered independently for each
+ sort column. For example <code class="literal">ORDER BY x, y DESC</code> means
+ <code class="literal">ORDER BY x ASC, y DESC</code>, which is not the same as
+ <code class="literal">ORDER BY x DESC, y DESC</code>.
+ </p><p>
+ A <em class="replaceable"><code>sort_expression</code></em> can also be the column label or number
+ of an output column, as in:
+</p><pre class="programlisting">
+SELECT a + b AS sum, c FROM table1 ORDER BY sum;
+SELECT a, max(b) FROM table1 GROUP BY a ORDER BY 1;
+</pre><p>
+ both of which sort by the first output column. Note that an output
+ column name has to stand alone, that is, it cannot be used in an expression
+ — for example, this is <span class="emphasis"><em>not</em></span> correct:
+</p><pre class="programlisting">
+SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong
+</pre><p>
+ This restriction is made to reduce ambiguity. There is still
+ ambiguity if an <code class="literal">ORDER BY</code> item is a simple name that
+ could match either an output column name or a column from the table
+ expression. The output column is used in such cases. This would
+ only cause confusion if you use <code class="literal">AS</code> to rename an output
+ column to match some other table column's name.
+ </p><p>
+ <code class="literal">ORDER BY</code> can be applied to the result of a
+ <code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, or <code class="literal">EXCEPT</code>
+ combination, but in this case it is only permitted to sort by
+ output column names or numbers, not by expressions.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.6.9.5.10" class="footnote"><p><a href="#id-1.5.6.9.5.10" class="para"><sup class="para">[6] </sup></a>
+ Actually, <span class="productname">PostgreSQL</span> uses the <em class="firstterm">default B-tree
+ operator class</em> for the expression's data type to determine the sort
+ ordering for <code class="literal">ASC</code> and <code class="literal">DESC</code>. Conventionally,
+ data types will be set up so that the <code class="literal">&lt;</code> and
+ <code class="literal">&gt;</code> operators correspond to this sort ordering,
+ but a user-defined data type's designer could choose to do something
+ different.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-limit.html" title="7.6. LIMIT and OFFSET">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-overview.html b/doc/src/sgml/html/queries-overview.html
new file mode 100644
index 0000000..e52ccd0
--- /dev/null
+++ b/doc/src/sgml/html/queries-overview.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries.html" title="Chapter 7. Queries" /><link rel="next" href="queries-table-expressions.html" title="7.2. Table Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries.html" title="Chapter 7. Queries">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-table-expressions.html" title="7.2. Table Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.1. Overview</h2></div></div></div><p>
+ The process of retrieving or the command to retrieve data from a
+ database is called a <em class="firstterm">query</em>. In SQL the
+ <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a> command is
+ used to specify queries. The general syntax of the
+ <code class="command">SELECT</code> command is
+</p><pre class="synopsis">
+[<span class="optional">WITH <em class="replaceable"><code>with_queries</code></em></span>] SELECT <em class="replaceable"><code>select_list</code></em> FROM <em class="replaceable"><code>table_expression</code></em> [<span class="optional"><em class="replaceable"><code>sort_specification</code></em></span>]
+</pre><p>
+ The following sections describe the details of the select list, the
+ table expression, and the sort specification. <code class="literal">WITH</code>
+ queries are treated last since they are an advanced feature.
+ </p><p>
+ A simple kind of query has the form:
+</p><pre class="programlisting">
+SELECT * FROM table1;
+</pre><p>
+ Assuming that there is a table called <code class="literal">table1</code>,
+ this command would retrieve all rows and all user-defined columns from
+ <code class="literal">table1</code>. (The method of retrieval depends on the
+ client application. For example, the
+ <span class="application">psql</span> program will display an ASCII-art
+ table on the screen, while client libraries will offer functions to
+ extract individual values from the query result.) The select list
+ specification <code class="literal">*</code> means all columns that the table
+ expression happens to provide. A select list can also select a
+ subset of the available columns or make calculations using the
+ columns. For example, if
+ <code class="literal">table1</code> has columns named <code class="literal">a</code>,
+ <code class="literal">b</code>, and <code class="literal">c</code> (and perhaps others) you can make
+ the following query:
+</p><pre class="programlisting">
+SELECT a, b + c FROM table1;
+</pre><p>
+ (assuming that <code class="literal">b</code> and <code class="literal">c</code> are of a numerical
+ data type).
+ See <a class="xref" href="queries-select-lists.html" title="7.3. Select Lists">Section 7.3</a> for more details.
+ </p><p>
+ <code class="literal">FROM table1</code> is a simple kind of
+ table expression: it reads just one table. In general, table
+ expressions can be complex constructs of base tables, joins, and
+ subqueries. But you can also omit the table expression entirely and
+ use the <code class="command">SELECT</code> command as a calculator:
+</p><pre class="programlisting">
+SELECT 3 * 4;
+</pre><p>
+ This is more useful if the expressions in the select list return
+ varying results. For example, you could call a function this way:
+</p><pre class="programlisting">
+SELECT random();
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries.html" title="Chapter 7. Queries">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-table-expressions.html" title="7.2. Table Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Queries </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.2. Table Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-select-lists.html b/doc/src/sgml/html/queries-select-lists.html
new file mode 100644
index 0000000..f3ece84
--- /dev/null
+++ b/doc/src/sgml/html/queries-select-lists.html
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.3. Select Lists</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-table-expressions.html" title="7.2. Table Expressions" /><link rel="next" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.3. Select Lists</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-table-expressions.html" title="7.2. Table Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-SELECT-LISTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.3. Select Lists</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-SELECT-LIST-ITEMS">7.3.1. Select-List Items</a></span></dt><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-COLUMN-LABELS">7.3.2. Column Labels</a></span></dt><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-DISTINCT">7.3.3. <code class="literal">DISTINCT</code></a></span></dt></dl></div><a id="id-1.5.6.7.2" class="indexterm"></a><p>
+ As shown in the previous section,
+ the table expression in the <code class="command">SELECT</code> command
+ constructs an intermediate virtual table by possibly combining
+ tables, views, eliminating rows, grouping, etc. This table is
+ finally passed on to processing by the <em class="firstterm">select list</em>. The select
+ list determines which <span class="emphasis"><em>columns</em></span> of the
+ intermediate table are actually output.
+ </p><div class="sect2" id="QUERIES-SELECT-LIST-ITEMS"><div class="titlepage"><div><div><h3 class="title">7.3.1. Select-List Items</h3></div></div></div><a id="id-1.5.6.7.4.2" class="indexterm"></a><p>
+ The simplest kind of select list is <code class="literal">*</code> which
+ emits all columns that the table expression produces. Otherwise,
+ a select list is a comma-separated list of value expressions (as
+ defined in <a class="xref" href="sql-expressions.html" title="4.2. Value Expressions">Section 4.2</a>). For instance, it
+ could be a list of column names:
+</p><pre class="programlisting">
+SELECT a, b, c FROM ...
+</pre><p>
+ The columns names <code class="literal">a</code>, <code class="literal">b</code>, and <code class="literal">c</code>
+ are either the actual names of the columns of tables referenced
+ in the <code class="literal">FROM</code> clause, or the aliases given to them as
+ explained in <a class="xref" href="queries-table-expressions.html#QUERIES-TABLE-ALIASES" title="7.2.1.2. Table and Column Aliases">Section 7.2.1.2</a>. The name
+ space available in the select list is the same as in the
+ <code class="literal">WHERE</code> clause, unless grouping is used, in which case
+ it is the same as in the <code class="literal">HAVING</code> clause.
+ </p><p>
+ If more than one table has a column of the same name, the table
+ name must also be given, as in:
+</p><pre class="programlisting">
+SELECT tbl1.a, tbl2.a, tbl1.b FROM ...
+</pre><p>
+ When working with multiple tables, it can also be useful to ask for
+ all the columns of a particular table:
+</p><pre class="programlisting">
+SELECT tbl1.*, tbl2.a FROM ...
+</pre><p>
+ See <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a> for more about
+ the <em class="replaceable"><code>table_name</code></em><code class="literal">.*</code> notation.
+ </p><p>
+ If an arbitrary value expression is used in the select list, it
+ conceptually adds a new virtual column to the returned table. The
+ value expression is evaluated once for each result row, with
+ the row's values substituted for any column references. But the
+ expressions in the select list do not have to reference any
+ columns in the table expression of the <code class="literal">FROM</code> clause;
+ they can be constant arithmetic expressions, for instance.
+ </p></div><div class="sect2" id="QUERIES-COLUMN-LABELS"><div class="titlepage"><div><div><h3 class="title">7.3.2. Column Labels</h3></div></div></div><a id="id-1.5.6.7.5.2" class="indexterm"></a><p>
+ The entries in the select list can be assigned names for subsequent
+ processing, such as for use in an <code class="literal">ORDER BY</code> clause
+ or for display by the client application. For example:
+</p><pre class="programlisting">
+SELECT a AS value, b + c AS sum FROM ...
+</pre><p>
+ </p><p>
+ If no output column name is specified using <code class="literal">AS</code>,
+ the system assigns a default column name. For simple column references,
+ this is the name of the referenced column. For function
+ calls, this is the name of the function. For complex expressions,
+ the system will generate a generic name.
+ </p><p>
+ The <code class="literal">AS</code> key word is usually optional, but in some
+ cases where the desired column name matches a
+ <span class="productname">PostgreSQL</span> key word, you must write
+ <code class="literal">AS</code> or double-quote the column name in order to
+ avoid ambiguity.
+ (<a class="xref" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Appendix C</a> shows which key words
+ require <code class="literal">AS</code> to be used as a column label.)
+ For example, <code class="literal">FROM</code> is one such key word, so this
+ does not work:
+</p><pre class="programlisting">
+SELECT a from, b + c AS sum FROM ...
+</pre><p>
+ but either of these do:
+</p><pre class="programlisting">
+SELECT a AS from, b + c AS sum FROM ...
+SELECT a "from", b + c AS sum FROM ...
+</pre><p>
+ For greatest safety against possible
+ future key word additions, it is recommended that you always either
+ write <code class="literal">AS</code> or double-quote the output column name.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The naming of output columns here is different from that done in
+ the <code class="literal">FROM</code> clause (see <a class="xref" href="queries-table-expressions.html#QUERIES-TABLE-ALIASES" title="7.2.1.2. Table and Column Aliases">Section 7.2.1.2</a>). It is possible
+ to rename the same column twice, but the name assigned in
+ the select list is the one that will be passed on.
+ </p></div></div><div class="sect2" id="QUERIES-DISTINCT"><div class="titlepage"><div><div><h3 class="title">7.3.3. <code class="literal">DISTINCT</code></h3></div></div></div><a id="id-1.5.6.7.6.2" class="indexterm"></a><a id="id-1.5.6.7.6.3" class="indexterm"></a><a id="id-1.5.6.7.6.4" class="indexterm"></a><p>
+ After the select list has been processed, the result table can
+ optionally be subject to the elimination of duplicate rows. The
+ <code class="literal">DISTINCT</code> key word is written directly after
+ <code class="literal">SELECT</code> to specify this:
+</p><pre class="synopsis">
+SELECT DISTINCT <em class="replaceable"><code>select_list</code></em> ...
+</pre><p>
+ (Instead of <code class="literal">DISTINCT</code> the key word <code class="literal">ALL</code>
+ can be used to specify the default behavior of retaining all rows.)
+ </p><a id="id-1.5.6.7.6.6" class="indexterm"></a><p>
+ Obviously, two rows are considered distinct if they differ in at
+ least one column value. Null values are considered equal in this
+ comparison.
+ </p><p>
+ Alternatively, an arbitrary expression can determine what rows are
+ to be considered distinct:
+</p><pre class="synopsis">
+SELECT DISTINCT ON (<em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> ...</span>]) <em class="replaceable"><code>select_list</code></em> ...
+</pre><p>
+ Here <em class="replaceable"><code>expression</code></em> is an arbitrary value
+ expression that is evaluated for all rows. A set of rows for
+ which all the expressions are equal are considered duplicates, and
+ only the first row of the set is kept in the output. Note that
+ the <span class="quote">“<span class="quote">first row</span>”</span> of a set is unpredictable unless the
+ query is sorted on enough columns to guarantee a unique ordering
+ of the rows arriving at the <code class="literal">DISTINCT</code> filter.
+ (<code class="literal">DISTINCT ON</code> processing occurs after <code class="literal">ORDER
+ BY</code> sorting.)
+ </p><p>
+ The <code class="literal">DISTINCT ON</code> clause is not part of the SQL standard
+ and is sometimes considered bad style because of the potentially
+ indeterminate nature of its results. With judicious use of
+ <code class="literal">GROUP BY</code> and subqueries in <code class="literal">FROM</code>, this
+ construct can be avoided, but it is often the most convenient
+ alternative.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-table-expressions.html" title="7.2. Table Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-union.html" title="7.4. Combining Queries (UNION, INTERSECT, EXCEPT)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.2. Table Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-table-expressions.html b/doc/src/sgml/html/queries-table-expressions.html
new file mode 100644
index 0000000..7ef400f
--- /dev/null
+++ b/doc/src/sgml/html/queries-table-expressions.html
@@ -0,0 +1,1030 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.2. Table Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-overview.html" title="7.1. Overview" /><link rel="next" href="queries-select-lists.html" title="7.3. Select Lists" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.2. Table Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-overview.html" title="7.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-select-lists.html" title="7.3. Select Lists">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-TABLE-EXPRESSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.2. Table Expressions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-FROM">7.2.1. The <code class="literal">FROM</code> Clause</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-WHERE">7.2.2. The <code class="literal">WHERE</code> Clause</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-GROUP">7.2.3. The <code class="literal">GROUP BY</code> and <code class="literal">HAVING</code> Clauses</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-GROUPING-SETS">7.2.4. <code class="literal">GROUPING SETS</code>, <code class="literal">CUBE</code>, and <code class="literal">ROLLUP</code></a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-WINDOW">7.2.5. Window Function Processing</a></span></dt></dl></div><a id="id-1.5.6.6.2" class="indexterm"></a><p>
+ A <em class="firstterm">table expression</em> computes a table. The
+ table expression contains a <code class="literal">FROM</code> clause that is
+ optionally followed by <code class="literal">WHERE</code>, <code class="literal">GROUP BY</code>, and
+ <code class="literal">HAVING</code> clauses. Trivial table expressions simply refer
+ to a table on disk, a so-called base table, but more complex
+ expressions can be used to modify or combine base tables in various
+ ways.
+ </p><p>
+ The optional <code class="literal">WHERE</code>, <code class="literal">GROUP BY</code>, and
+ <code class="literal">HAVING</code> clauses in the table expression specify a
+ pipeline of successive transformations performed on the table
+ derived in the <code class="literal">FROM</code> clause. All these transformations
+ produce a virtual table that provides the rows that are passed to
+ the select list to compute the output rows of the query.
+ </p><div class="sect2" id="QUERIES-FROM"><div class="titlepage"><div><div><h3 class="title">7.2.1. The <code class="literal">FROM</code> Clause</h3></div></div></div><p>
+ The <a class="link" href="sql-select.html#SQL-FROM" title="FROM Clause"><code class="literal">FROM</code></a> clause derives a
+ table from one or more other tables given in a comma-separated
+ table reference list.
+</p><pre class="synopsis">
+FROM <em class="replaceable"><code>table_reference</code></em> [<span class="optional">, <em class="replaceable"><code>table_reference</code></em> [<span class="optional">, ...</span>]</span>]
+</pre><p>
+
+ A table reference can be a table name (possibly schema-qualified),
+ or a derived table such as a subquery, a <code class="literal">JOIN</code> construct, or
+ complex combinations of these. If more than one table reference is
+ listed in the <code class="literal">FROM</code> clause, the tables are cross-joined
+ (that is, the Cartesian product of their rows is formed; see below).
+ The result of the <code class="literal">FROM</code> list is an intermediate virtual
+ table that can then be subject to
+ transformations by the <code class="literal">WHERE</code>, <code class="literal">GROUP BY</code>,
+ and <code class="literal">HAVING</code> clauses and is finally the result of the
+ overall table expression.
+ </p><a id="id-1.5.6.6.5.3" class="indexterm"></a><p>
+ When a table reference names a table that is the parent of a
+ table inheritance hierarchy, the table reference produces rows of
+ not only that table but all of its descendant tables, unless the
+ key word <code class="literal">ONLY</code> precedes the table name. However, the
+ reference produces only the columns that appear in the named table
+ — any columns added in subtables are ignored.
+ </p><p>
+ Instead of writing <code class="literal">ONLY</code> before the table name, you can write
+ <code class="literal">*</code> after the table name to explicitly specify that descendant
+ tables are included. There is no real reason to use this syntax any more,
+ because searching descendant tables is now always the default behavior.
+ However, it is supported for compatibility with older releases.
+ </p><div class="sect3" id="QUERIES-JOIN"><div class="titlepage"><div><div><h4 class="title">7.2.1.1. Joined Tables</h4></div></div></div><a id="id-1.5.6.6.5.6.2" class="indexterm"></a><p>
+ A joined table is a table derived from two other (real or
+ derived) tables according to the rules of the particular join
+ type. Inner, outer, and cross-joins are available.
+ The general syntax of a joined table is
+</p><pre class="synopsis">
+<em class="replaceable"><code>T1</code></em> <em class="replaceable"><code>join_type</code></em> <em class="replaceable"><code>T2</code></em> [<span class="optional"> <em class="replaceable"><code>join_condition</code></em> </span>]
+</pre><p>
+ Joins of all types can be chained together, or nested: either or
+ both <em class="replaceable"><code>T1</code></em> and
+ <em class="replaceable"><code>T2</code></em> can be joined tables. Parentheses
+ can be used around <code class="literal">JOIN</code> clauses to control the join
+ order. In the absence of parentheses, <code class="literal">JOIN</code> clauses
+ nest left-to-right.
+ </p><div class="variablelist"><p class="title"><strong>Join Types</strong></p><dl class="variablelist"><dt><span class="term">Cross join
+ <a id="id-1.5.6.6.5.6.4.2.1.1" class="indexterm"></a>
+
+ <a id="id-1.5.6.6.5.6.4.2.1.2" class="indexterm"></a>
+ </span></dt><dd><pre class="synopsis">
+<em class="replaceable"><code>T1</code></em> CROSS JOIN <em class="replaceable"><code>T2</code></em>
+</pre><p>
+ For every possible combination of rows from
+ <em class="replaceable"><code>T1</code></em> and
+ <em class="replaceable"><code>T2</code></em> (i.e., a Cartesian product),
+ the joined table will contain a
+ row consisting of all columns in <em class="replaceable"><code>T1</code></em>
+ followed by all columns in <em class="replaceable"><code>T2</code></em>. If
+ the tables have N and M rows respectively, the joined
+ table will have N * M rows.
+ </p><p>
+ <code class="literal">FROM <em class="replaceable"><code>T1</code></em> CROSS JOIN
+ <em class="replaceable"><code>T2</code></em></code> is equivalent to
+ <code class="literal">FROM <em class="replaceable"><code>T1</code></em> INNER JOIN
+ <em class="replaceable"><code>T2</code></em> ON TRUE</code> (see below).
+ It is also equivalent to
+ <code class="literal">FROM <em class="replaceable"><code>T1</code></em>,
+ <em class="replaceable"><code>T2</code></em></code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This latter equivalence does not hold exactly when more than two
+ tables appear, because <code class="literal">JOIN</code> binds more tightly than
+ comma. For example
+ <code class="literal">FROM <em class="replaceable"><code>T1</code></em> CROSS JOIN
+ <em class="replaceable"><code>T2</code></em> INNER JOIN <em class="replaceable"><code>T3</code></em>
+ ON <em class="replaceable"><code>condition</code></em></code>
+ is not the same as
+ <code class="literal">FROM <em class="replaceable"><code>T1</code></em>,
+ <em class="replaceable"><code>T2</code></em> INNER JOIN <em class="replaceable"><code>T3</code></em>
+ ON <em class="replaceable"><code>condition</code></em></code>
+ because the <em class="replaceable"><code>condition</code></em> can
+ reference <em class="replaceable"><code>T1</code></em> in the first case but not
+ the second.
+ </p></div><p>
+ </p></dd><dt><span class="term">Qualified joins
+ <a id="id-1.5.6.6.5.6.4.3.1.1" class="indexterm"></a>
+
+ <a id="id-1.5.6.6.5.6.4.3.1.2" class="indexterm"></a>
+ </span></dt><dd><pre class="synopsis">
+<em class="replaceable"><code>T1</code></em> { [<span class="optional">INNER</span>] | { LEFT | RIGHT | FULL } [<span class="optional">OUTER</span>] } JOIN <em class="replaceable"><code>T2</code></em> ON <em class="replaceable"><code>boolean_expression</code></em>
+<em class="replaceable"><code>T1</code></em> { [<span class="optional">INNER</span>] | { LEFT | RIGHT | FULL } [<span class="optional">OUTER</span>] } JOIN <em class="replaceable"><code>T2</code></em> USING ( <em class="replaceable"><code>join column list</code></em> )
+<em class="replaceable"><code>T1</code></em> NATURAL { [<span class="optional">INNER</span>] | { LEFT | RIGHT | FULL } [<span class="optional">OUTER</span>] } JOIN <em class="replaceable"><code>T2</code></em>
+</pre><p>
+ The words <code class="literal">INNER</code> and
+ <code class="literal">OUTER</code> are optional in all forms.
+ <code class="literal">INNER</code> is the default;
+ <code class="literal">LEFT</code>, <code class="literal">RIGHT</code>, and
+ <code class="literal">FULL</code> imply an outer join.
+ </p><p>
+ The <em class="firstterm">join condition</em> is specified in the
+ <code class="literal">ON</code> or <code class="literal">USING</code> clause, or implicitly by
+ the word <code class="literal">NATURAL</code>. The join condition determines
+ which rows from the two source tables are considered to
+ <span class="quote">“<span class="quote">match</span>”</span>, as explained in detail below.
+ </p><p>
+ The possible types of qualified join are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">INNER JOIN</code></span></dt><dd><p>
+ For each row R1 of T1, the joined table has a row for each
+ row in T2 that satisfies the join condition with R1.
+ </p></dd><dt><span class="term"><code class="literal">LEFT OUTER JOIN</code>
+ <a id="id-1.5.6.6.5.6.4.3.2.4.1.2.1.2" class="indexterm"></a>
+
+ <a id="id-1.5.6.6.5.6.4.3.2.4.1.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ First, an inner join is performed. Then, for each row in
+ T1 that does not satisfy the join condition with any row in
+ T2, a joined row is added with null values in columns of
+ T2. Thus, the joined table always has at least
+ one row for each row in T1.
+ </p></dd><dt><span class="term"><code class="literal">RIGHT OUTER JOIN</code>
+ <a id="id-1.5.6.6.5.6.4.3.2.4.1.3.1.2" class="indexterm"></a>
+
+ <a id="id-1.5.6.6.5.6.4.3.2.4.1.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ First, an inner join is performed. Then, for each row in
+ T2 that does not satisfy the join condition with any row in
+ T1, a joined row is added with null values in columns of
+ T1. This is the converse of a left join: the result table
+ will always have a row for each row in T2.
+ </p></dd><dt><span class="term"><code class="literal">FULL OUTER JOIN</code></span></dt><dd><p>
+ First, an inner join is performed. Then, for each row in
+ T1 that does not satisfy the join condition with any row in
+ T2, a joined row is added with null values in columns of
+ T2. Also, for each row of T2 that does not satisfy the
+ join condition with any row in T1, a joined row with null
+ values in the columns of T1 is added.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="literal">ON</code> clause is the most general kind of join
+ condition: it takes a Boolean value expression of the same
+ kind as is used in a <code class="literal">WHERE</code> clause. A pair of rows
+ from <em class="replaceable"><code>T1</code></em> and <em class="replaceable"><code>T2</code></em> match if the
+ <code class="literal">ON</code> expression evaluates to true.
+ </p><p>
+ The <code class="literal">USING</code> clause is a shorthand that allows you to take
+ advantage of the specific situation where both sides of the join use
+ the same name for the joining column(s). It takes a
+ comma-separated list of the shared column names
+ and forms a join condition that includes an equality comparison
+ for each one. For example, joining <em class="replaceable"><code>T1</code></em>
+ and <em class="replaceable"><code>T2</code></em> with <code class="literal">USING (a, b)</code> produces
+ the join condition <code class="literal">ON <em class="replaceable"><code>T1</code></em>.a
+ = <em class="replaceable"><code>T2</code></em>.a AND <em class="replaceable"><code>T1</code></em>.b
+ = <em class="replaceable"><code>T2</code></em>.b</code>.
+ </p><p>
+ Furthermore, the output of <code class="literal">JOIN USING</code> suppresses
+ redundant columns: there is no need to print both of the matched
+ columns, since they must have equal values. While <code class="literal">JOIN
+ ON</code> produces all columns from <em class="replaceable"><code>T1</code></em> followed by all
+ columns from <em class="replaceable"><code>T2</code></em>, <code class="literal">JOIN USING</code> produces one
+ output column for each of the listed column pairs (in the listed
+ order), followed by any remaining columns from <em class="replaceable"><code>T1</code></em>,
+ followed by any remaining columns from <em class="replaceable"><code>T2</code></em>.
+ </p><p>
+ <a id="id-1.5.6.6.5.6.4.3.2.8.1" class="indexterm"></a>
+ <a id="id-1.5.6.6.5.6.4.3.2.8.2" class="indexterm"></a>
+ Finally, <code class="literal">NATURAL</code> is a shorthand form of
+ <code class="literal">USING</code>: it forms a <code class="literal">USING</code> list
+ consisting of all column names that appear in both
+ input tables. As with <code class="literal">USING</code>, these columns appear
+ only once in the output table. If there are no common
+ column names, <code class="literal">NATURAL JOIN</code> behaves like
+ <code class="literal">JOIN ... ON TRUE</code>, producing a cross-product join.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">USING</code> is reasonably safe from column changes
+ in the joined relations since only the listed columns
+ are combined. <code class="literal">NATURAL</code> is considerably more risky since
+ any schema changes to either relation that cause a new matching
+ column name to be present will cause the join to combine that new
+ column as well.
+ </p></div></dd></dl></div><p>
+ To put this together, assume we have tables <code class="literal">t1</code>:
+</p><pre class="programlisting">
+ num | name
+-----+------
+ 1 | a
+ 2 | b
+ 3 | c
+</pre><p>
+ and <code class="literal">t2</code>:
+</p><pre class="programlisting">
+ num | value
+-----+-------
+ 1 | xxx
+ 3 | yyy
+ 5 | zzz
+</pre><p>
+ then we get the following results for the various joins:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 CROSS JOIN t2;</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 1 | a | 3 | yyy
+ 1 | a | 5 | zzz
+ 2 | b | 1 | xxx
+ 2 | b | 3 | yyy
+ 2 | b | 5 | zzz
+ 3 | c | 1 | xxx
+ 3 | c | 3 | yyy
+ 3 | c | 5 | zzz
+(9 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 INNER JOIN t2 ON t1.num = t2.num;</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 3 | c | 3 | yyy
+(2 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 INNER JOIN t2 USING (num);</code></strong>
+ num | name | value
+-----+------+-------
+ 1 | a | xxx
+ 3 | c | yyy
+(2 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 NATURAL INNER JOIN t2;</code></strong>
+ num | name | value
+-----+------+-------
+ 1 | a | xxx
+ 3 | c | yyy
+(2 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 LEFT JOIN t2 ON t1.num = t2.num;</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 2 | b | |
+ 3 | c | 3 | yyy
+(3 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 LEFT JOIN t2 USING (num);</code></strong>
+ num | name | value
+-----+------+-------
+ 1 | a | xxx
+ 2 | b |
+ 3 | c | yyy
+(3 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 RIGHT JOIN t2 ON t1.num = t2.num;</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 3 | c | 3 | yyy
+ | | 5 | zzz
+(3 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 FULL JOIN t2 ON t1.num = t2.num;</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 2 | b | |
+ 3 | c | 3 | yyy
+ | | 5 | zzz
+(4 rows)
+</pre><p>
+ </p><p>
+ The join condition specified with <code class="literal">ON</code> can also contain
+ conditions that do not relate directly to the join. This can
+ prove useful for some queries but needs to be thought out
+ carefully. For example:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 LEFT JOIN t2 ON t1.num = t2.num AND t2.value = 'xxx';</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+ 2 | b | |
+ 3 | c | |
+(3 rows)
+</pre><p>
+ Notice that placing the restriction in the <code class="literal">WHERE</code> clause
+ produces a different result:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM t1 LEFT JOIN t2 ON t1.num = t2.num WHERE t2.value = 'xxx';</code></strong>
+ num | name | num | value
+-----+------+-----+-------
+ 1 | a | 1 | xxx
+(1 row)
+</pre><p>
+ This is because a restriction placed in the <code class="literal">ON</code>
+ clause is processed <span class="emphasis"><em>before</em></span> the join, while
+ a restriction placed in the <code class="literal">WHERE</code> clause is processed
+ <span class="emphasis"><em>after</em></span> the join.
+ That does not matter with inner joins, but it matters a lot with outer
+ joins.
+ </p></div><div class="sect3" id="QUERIES-TABLE-ALIASES"><div class="titlepage"><div><div><h4 class="title">7.2.1.2. Table and Column Aliases</h4></div></div></div><a id="id-1.5.6.6.5.7.2" class="indexterm"></a><a id="id-1.5.6.6.5.7.3" class="indexterm"></a><p>
+ A temporary name can be given to tables and complex table
+ references to be used for references to the derived table in
+ the rest of the query. This is called a <em class="firstterm">table
+ alias</em>.
+ </p><p>
+ To create a table alias, write
+</p><pre class="synopsis">
+FROM <em class="replaceable"><code>table_reference</code></em> AS <em class="replaceable"><code>alias</code></em>
+</pre><p>
+ or
+</p><pre class="synopsis">
+FROM <em class="replaceable"><code>table_reference</code></em> <em class="replaceable"><code>alias</code></em>
+</pre><p>
+ The <code class="literal">AS</code> key word is optional noise.
+ <em class="replaceable"><code>alias</code></em> can be any identifier.
+ </p><p>
+ A typical application of table aliases is to assign short
+ identifiers to long table names to keep the join clauses
+ readable. For example:
+</p><pre class="programlisting">
+SELECT * FROM some_very_long_table_name s JOIN another_fairly_long_name a ON s.id = a.num;
+</pre><p>
+ </p><p>
+ The alias becomes the new name of the table reference so far as the
+ current query is concerned — it is not allowed to refer to the
+ table by the original name elsewhere in the query. Thus, this is not
+ valid:
+</p><pre class="programlisting">
+SELECT * FROM my_table AS m WHERE my_table.a &gt; 5; -- wrong
+</pre><p>
+ </p><p>
+ Table aliases are mainly for notational convenience, but it is
+ necessary to use them when joining a table to itself, e.g.:
+</p><pre class="programlisting">
+SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id;
+</pre><p>
+ Additionally, an alias is required if the table reference is a
+ subquery (see <a class="xref" href="queries-table-expressions.html#QUERIES-SUBQUERIES" title="7.2.1.3. Subqueries">Section 7.2.1.3</a>).
+ </p><p>
+ Parentheses are used to resolve ambiguities. In the following example,
+ the first statement assigns the alias <code class="literal">b</code> to the second
+ instance of <code class="literal">my_table</code>, but the second statement assigns the
+ alias to the result of the join:
+</p><pre class="programlisting">
+SELECT * FROM my_table AS a CROSS JOIN my_table AS b ...
+SELECT * FROM (my_table AS a CROSS JOIN my_table) AS b ...
+</pre><p>
+ </p><p>
+ Another form of table aliasing gives temporary names to the columns of
+ the table, as well as the table itself:
+</p><pre class="synopsis">
+FROM <em class="replaceable"><code>table_reference</code></em> [<span class="optional">AS</span>] <em class="replaceable"><code>alias</code></em> ( <em class="replaceable"><code>column1</code></em> [<span class="optional">, <em class="replaceable"><code>column2</code></em> [<span class="optional">, ...</span>]</span>] )
+</pre><p>
+ If fewer column aliases are specified than the actual table has
+ columns, the remaining columns are not renamed. This syntax is
+ especially useful for self-joins or subqueries.
+ </p><p>
+ When an alias is applied to the output of a <code class="literal">JOIN</code>
+ clause, the alias hides the original
+ name(s) within the <code class="literal">JOIN</code>. For example:
+</p><pre class="programlisting">
+SELECT a.* FROM my_table AS a JOIN your_table AS b ON ...
+</pre><p>
+ is valid SQL, but:
+</p><pre class="programlisting">
+SELECT a.* FROM (my_table AS a JOIN your_table AS b ON ...) AS c
+</pre><p>
+ is not valid; the table alias <code class="literal">a</code> is not visible
+ outside the alias <code class="literal">c</code>.
+ </p></div><div class="sect3" id="QUERIES-SUBQUERIES"><div class="titlepage"><div><div><h4 class="title">7.2.1.3. Subqueries</h4></div></div></div><a id="id-1.5.6.6.5.8.2" class="indexterm"></a><p>
+ Subqueries specifying a derived table must be enclosed in
+ parentheses and <span class="emphasis"><em>must</em></span> be assigned a table
+ alias name (as in <a class="xref" href="queries-table-expressions.html#QUERIES-TABLE-ALIASES" title="7.2.1.2. Table and Column Aliases">Section 7.2.1.2</a>). For
+ example:
+</p><pre class="programlisting">
+FROM (SELECT * FROM table1) AS alias_name
+</pre><p>
+ </p><p>
+ This example is equivalent to <code class="literal">FROM table1 AS
+ alias_name</code>. More interesting cases, which cannot be
+ reduced to a plain join, arise when the subquery involves
+ grouping or aggregation.
+ </p><p>
+ A subquery can also be a <code class="command">VALUES</code> list:
+</p><pre class="programlisting">
+FROM (VALUES ('anne', 'smith'), ('bob', 'jones'), ('joe', 'blow'))
+ AS names(first, last)
+</pre><p>
+ Again, a table alias is required. Assigning alias names to the columns
+ of the <code class="command">VALUES</code> list is optional, but is good practice.
+ For more information see <a class="xref" href="queries-values.html" title="7.7. VALUES Lists">Section 7.7</a>.
+ </p></div><div class="sect3" id="QUERIES-TABLEFUNCTIONS"><div class="titlepage"><div><div><h4 class="title">7.2.1.4. Table Functions</h4></div></div></div><a id="id-1.5.6.6.5.9.2" class="indexterm"></a><a id="id-1.5.6.6.5.9.3" class="indexterm"></a><p>
+ Table functions are functions that produce a set of rows, made up
+ of either base data types (scalar types) or composite data types
+ (table rows). They are used like a table, view, or subquery in
+ the <code class="literal">FROM</code> clause of a query. Columns returned by table
+ functions can be included in <code class="literal">SELECT</code>,
+ <code class="literal">JOIN</code>, or <code class="literal">WHERE</code> clauses in the same manner
+ as columns of a table, view, or subquery.
+ </p><p>
+ Table functions may also be combined using the <code class="literal">ROWS FROM</code>
+ syntax, with the results returned in parallel columns; the number of
+ result rows in this case is that of the largest function result, with
+ smaller results padded with null values to match.
+ </p><pre class="synopsis">
+<em class="replaceable"><code>function_call</code></em> [<span class="optional">WITH ORDINALITY</span>] [<span class="optional">[<span class="optional">AS</span>] <em class="replaceable"><code>table_alias</code></em> [<span class="optional">(<em class="replaceable"><code>column_alias</code></em> [<span class="optional">, ... </span>])</span>]</span>]
+ROWS FROM( <em class="replaceable"><code>function_call</code></em> [<span class="optional">, ... </span>] ) [<span class="optional">WITH ORDINALITY</span>] [<span class="optional">[<span class="optional">AS</span>] <em class="replaceable"><code>table_alias</code></em> [<span class="optional">(<em class="replaceable"><code>column_alias</code></em> [<span class="optional">, ... </span>])</span>]</span>]
+</pre><p>
+ If the <code class="literal">WITH ORDINALITY</code> clause is specified, an
+ additional column of type <code class="type">bigint</code> will be added to the
+ function result columns. This column numbers the rows of the function
+ result set, starting from 1. (This is a generalization of the
+ SQL-standard syntax for <code class="literal">UNNEST ... WITH ORDINALITY</code>.)
+ By default, the ordinal column is called <code class="literal">ordinality</code>, but
+ a different column name can be assigned to it using
+ an <code class="literal">AS</code> clause.
+ </p><p>
+ The special table function <code class="literal">UNNEST</code> may be called with
+ any number of array parameters, and it returns a corresponding number of
+ columns, as if <code class="literal">UNNEST</code>
+ (<a class="xref" href="functions-array.html" title="9.19. Array Functions and Operators">Section 9.19</a>) had been called on each parameter
+ separately and combined using the <code class="literal">ROWS FROM</code> construct.
+ </p><pre class="synopsis">
+UNNEST( <em class="replaceable"><code>array_expression</code></em> [<span class="optional">, ... </span>] ) [<span class="optional">WITH ORDINALITY</span>] [<span class="optional">[<span class="optional">AS</span>] <em class="replaceable"><code>table_alias</code></em> [<span class="optional">(<em class="replaceable"><code>column_alias</code></em> [<span class="optional">, ... </span>])</span>]</span>]
+</pre><p>
+ If no <em class="replaceable"><code>table_alias</code></em> is specified, the function
+ name is used as the table name; in the case of a <code class="literal">ROWS FROM()</code>
+ construct, the first function's name is used.
+ </p><p>
+ If column aliases are not supplied, then for a function returning a base
+ data type, the column name is also the same as the function name. For a
+ function returning a composite type, the result columns get the names
+ of the individual attributes of the type.
+ </p><p>
+ Some examples:
+</p><pre class="programlisting">
+CREATE TABLE foo (fooid int, foosubid int, fooname text);
+
+CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS $$
+ SELECT * FROM foo WHERE fooid = $1;
+$$ LANGUAGE SQL;
+
+SELECT * FROM getfoo(1) AS t1;
+
+SELECT * FROM foo
+ WHERE foosubid IN (
+ SELECT foosubid
+ FROM getfoo(foo.fooid) z
+ WHERE z.fooid = foo.fooid
+ );
+
+CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1);
+
+SELECT * FROM vw_getfoo;
+</pre><p>
+ </p><p>
+ In some cases it is useful to define table functions that can
+ return different column sets depending on how they are invoked.
+ To support this, the table function can be declared as returning
+ the pseudo-type <code class="type">record</code> with no <code class="literal">OUT</code>
+ parameters. When such a function is used in
+ a query, the expected row structure must be specified in the
+ query itself, so that the system can know how to parse and plan
+ the query. This syntax looks like:
+ </p><pre class="synopsis">
+<em class="replaceable"><code>function_call</code></em> [<span class="optional">AS</span>] <em class="replaceable"><code>alias</code></em> (<em class="replaceable"><code>column_definition</code></em> [<span class="optional">, ... </span>])
+<em class="replaceable"><code>function_call</code></em> AS [<span class="optional"><em class="replaceable"><code>alias</code></em></span>] (<em class="replaceable"><code>column_definition</code></em> [<span class="optional">, ... </span>])
+ROWS FROM( ... <em class="replaceable"><code>function_call</code></em> AS (<em class="replaceable"><code>column_definition</code></em> [<span class="optional">, ... </span>]) [<span class="optional">, ... </span>] )
+</pre><p>
+ When not using the <code class="literal">ROWS FROM()</code> syntax,
+ the <em class="replaceable"><code>column_definition</code></em> list replaces the column
+ alias list that could otherwise be attached to the <code class="literal">FROM</code>
+ item; the names in the column definitions serve as column aliases.
+ When using the <code class="literal">ROWS FROM()</code> syntax,
+ a <em class="replaceable"><code>column_definition</code></em> list can be attached to
+ each member function separately; or if there is only one member function
+ and no <code class="literal">WITH ORDINALITY</code> clause,
+ a <em class="replaceable"><code>column_definition</code></em> list can be written in
+ place of a column alias list following <code class="literal">ROWS FROM()</code>.
+ </p><p>
+ Consider this example:
+</p><pre class="programlisting">
+SELECT *
+ FROM dblink('dbname=mydb', 'SELECT proname, prosrc FROM pg_proc')
+ AS t1(proname name, prosrc text)
+ WHERE proname LIKE 'bytea%';
+</pre><p>
+ The <a class="xref" href="contrib-dblink-function.html" title="dblink"><span class="refentrytitle">dblink</span></a> function
+ (part of the <a class="xref" href="dblink.html" title="F.12. dblink">dblink</a> module) executes
+ a remote query. It is declared to return
+ <code class="type">record</code> since it might be used for any kind of query.
+ The actual column set must be specified in the calling query so
+ that the parser knows, for example, what <code class="literal">*</code> should
+ expand to.
+ </p><p>
+ This example uses <code class="literal">ROWS FROM</code>:
+</p><pre class="programlisting">
+SELECT *
+FROM ROWS FROM
+ (
+ json_to_recordset('[{"a":40,"b":"foo"},{"a":"100","b":"bar"}]')
+ AS (a INTEGER, b TEXT),
+ generate_series(1, 3)
+ ) AS x (p, q, s)
+ORDER BY p;
+
+ p | q | s
+-----+-----+---
+ 40 | foo | 1
+ 100 | bar | 2
+ | | 3
+</pre><p>
+ It joins two functions into a single <code class="literal">FROM</code>
+ target. <code class="function">json_to_recordset()</code> is instructed
+ to return two columns, the first <code class="type">integer</code>
+ and the second <code class="type">text</code>. The result of
+ <code class="function">generate_series()</code> is used directly.
+ The <code class="literal">ORDER BY</code> clause sorts the column values
+ as integers.
+ </p></div><div class="sect3" id="QUERIES-LATERAL"><div class="titlepage"><div><div><h4 class="title">7.2.1.5. <code class="literal">LATERAL</code> Subqueries</h4></div></div></div><a id="id-1.5.6.6.5.10.2" class="indexterm"></a><p>
+ Subqueries appearing in <code class="literal">FROM</code> can be
+ preceded by the key word <code class="literal">LATERAL</code>. This allows them to
+ reference columns provided by preceding <code class="literal">FROM</code> items.
+ (Without <code class="literal">LATERAL</code>, each subquery is
+ evaluated independently and so cannot cross-reference any other
+ <code class="literal">FROM</code> item.)
+ </p><p>
+ Table functions appearing in <code class="literal">FROM</code> can also be
+ preceded by the key word <code class="literal">LATERAL</code>, but for functions the
+ key word is optional; the function's arguments can contain references
+ to columns provided by preceding <code class="literal">FROM</code> items in any case.
+ </p><p>
+ A <code class="literal">LATERAL</code> item can appear at the top level in the
+ <code class="literal">FROM</code> list, or within a <code class="literal">JOIN</code> tree. In the latter
+ case it can also refer to any items that are on the left-hand side of a
+ <code class="literal">JOIN</code> that it is on the right-hand side of.
+ </p><p>
+ When a <code class="literal">FROM</code> item contains <code class="literal">LATERAL</code>
+ cross-references, evaluation proceeds as follows: for each row of the
+ <code class="literal">FROM</code> item providing the cross-referenced column(s), or
+ set of rows of multiple <code class="literal">FROM</code> items providing the
+ columns, the <code class="literal">LATERAL</code> item is evaluated using that
+ row or row set's values of the columns. The resulting row(s) are
+ joined as usual with the rows they were computed from. This is
+ repeated for each row or set of rows from the column source table(s).
+ </p><p>
+ A trivial example of <code class="literal">LATERAL</code> is
+</p><pre class="programlisting">
+SELECT * FROM foo, LATERAL (SELECT * FROM bar WHERE bar.id = foo.bar_id) ss;
+</pre><p>
+ This is not especially useful since it has exactly the same result as
+ the more conventional
+</p><pre class="programlisting">
+SELECT * FROM foo, bar WHERE bar.id = foo.bar_id;
+</pre><p>
+ <code class="literal">LATERAL</code> is primarily useful when the cross-referenced
+ column is necessary for computing the row(s) to be joined. A common
+ application is providing an argument value for a set-returning function.
+ For example, supposing that <code class="function">vertices(polygon)</code> returns the
+ set of vertices of a polygon, we could identify close-together vertices
+ of polygons stored in a table with:
+</p><pre class="programlisting">
+SELECT p1.id, p2.id, v1, v2
+FROM polygons p1, polygons p2,
+ LATERAL vertices(p1.poly) v1,
+ LATERAL vertices(p2.poly) v2
+WHERE (v1 &lt;-&gt; v2) &lt; 10 AND p1.id != p2.id;
+</pre><p>
+ This query could also be written
+</p><pre class="programlisting">
+SELECT p1.id, p2.id, v1, v2
+FROM polygons p1 CROSS JOIN LATERAL vertices(p1.poly) v1,
+ polygons p2 CROSS JOIN LATERAL vertices(p2.poly) v2
+WHERE (v1 &lt;-&gt; v2) &lt; 10 AND p1.id != p2.id;
+</pre><p>
+ or in several other equivalent formulations. (As already mentioned,
+ the <code class="literal">LATERAL</code> key word is unnecessary in this example, but
+ we use it for clarity.)
+ </p><p>
+ It is often particularly handy to <code class="literal">LEFT JOIN</code> to a
+ <code class="literal">LATERAL</code> subquery, so that source rows will appear in
+ the result even if the <code class="literal">LATERAL</code> subquery produces no
+ rows for them. For example, if <code class="function">get_product_names()</code> returns
+ the names of products made by a manufacturer, but some manufacturers in
+ our table currently produce no products, we could find out which ones
+ those are like this:
+</p><pre class="programlisting">
+SELECT m.name
+FROM manufacturers m LEFT JOIN LATERAL get_product_names(m.id) pname ON true
+WHERE pname IS NULL;
+</pre><p>
+ </p></div></div><div class="sect2" id="QUERIES-WHERE"><div class="titlepage"><div><div><h3 class="title">7.2.2. The <code class="literal">WHERE</code> Clause</h3></div></div></div><a id="id-1.5.6.6.6.2" class="indexterm"></a><p>
+ The syntax of the <a class="link" href="sql-select.html#SQL-WHERE" title="WHERE Clause"><code class="literal">WHERE</code></a>
+ clause is
+</p><pre class="synopsis">
+WHERE <em class="replaceable"><code>search_condition</code></em>
+</pre><p>
+ where <em class="replaceable"><code>search_condition</code></em> is any value
+ expression (see <a class="xref" href="sql-expressions.html" title="4.2. Value Expressions">Section 4.2</a>) that
+ returns a value of type <code class="type">boolean</code>.
+ </p><p>
+ After the processing of the <code class="literal">FROM</code> clause is done, each
+ row of the derived virtual table is checked against the search
+ condition. If the result of the condition is true, the row is
+ kept in the output table, otherwise (i.e., if the result is
+ false or null) it is discarded. The search condition typically
+ references at least one column of the table generated in the
+ <code class="literal">FROM</code> clause; this is not required, but otherwise the
+ <code class="literal">WHERE</code> clause will be fairly useless.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The join condition of an inner join can be written either in
+ the <code class="literal">WHERE</code> clause or in the <code class="literal">JOIN</code> clause.
+ For example, these table expressions are equivalent:
+</p><pre class="programlisting">
+FROM a, b WHERE a.id = b.id AND b.val &gt; 5
+</pre><p>
+ and:
+</p><pre class="programlisting">
+FROM a INNER JOIN b ON (a.id = b.id) WHERE b.val &gt; 5
+</pre><p>
+ or perhaps even:
+</p><pre class="programlisting">
+FROM a NATURAL JOIN b WHERE b.val &gt; 5
+</pre><p>
+ Which one of these you use is mainly a matter of style. The
+ <code class="literal">JOIN</code> syntax in the <code class="literal">FROM</code> clause is
+ probably not as portable to other SQL database management systems,
+ even though it is in the SQL standard. For
+ outer joins there is no choice: they must be done in
+ the <code class="literal">FROM</code> clause. The <code class="literal">ON</code> or <code class="literal">USING</code>
+ clause of an outer join is <span class="emphasis"><em>not</em></span> equivalent to a
+ <code class="literal">WHERE</code> condition, because it results in the addition
+ of rows (for unmatched input rows) as well as the removal of rows
+ in the final result.
+ </p></div><p>
+ Here are some examples of <code class="literal">WHERE</code> clauses:
+</p><pre class="programlisting">
+SELECT ... FROM fdt WHERE c1 &gt; 5
+
+SELECT ... FROM fdt WHERE c1 IN (1, 2, 3)
+
+SELECT ... FROM fdt WHERE c1 IN (SELECT c1 FROM t2)
+
+SELECT ... FROM fdt WHERE c1 IN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10)
+
+SELECT ... FROM fdt WHERE c1 BETWEEN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10) AND 100
+
+SELECT ... FROM fdt WHERE EXISTS (SELECT c1 FROM t2 WHERE c2 &gt; fdt.c1)
+</pre><p>
+ <code class="literal">fdt</code> is the table derived in the
+ <code class="literal">FROM</code> clause. Rows that do not meet the search
+ condition of the <code class="literal">WHERE</code> clause are eliminated from
+ <code class="literal">fdt</code>. Notice the use of scalar subqueries as
+ value expressions. Just like any other query, the subqueries can
+ employ complex table expressions. Notice also how
+ <code class="literal">fdt</code> is referenced in the subqueries.
+ Qualifying <code class="literal">c1</code> as <code class="literal">fdt.c1</code> is only necessary
+ if <code class="literal">c1</code> is also the name of a column in the derived
+ input table of the subquery. But qualifying the column name adds
+ clarity even when it is not needed. This example shows how the column
+ naming scope of an outer query extends into its inner queries.
+ </p></div><div class="sect2" id="QUERIES-GROUP"><div class="titlepage"><div><div><h3 class="title">7.2.3. The <code class="literal">GROUP BY</code> and <code class="literal">HAVING</code> Clauses</h3></div></div></div><a id="id-1.5.6.6.7.2" class="indexterm"></a><a id="id-1.5.6.6.7.3" class="indexterm"></a><p>
+ After passing the <code class="literal">WHERE</code> filter, the derived input
+ table might be subject to grouping, using the <code class="literal">GROUP BY</code>
+ clause, and elimination of group rows using the <code class="literal">HAVING</code>
+ clause.
+ </p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_list</code></em>
+ FROM ...
+ [<span class="optional">WHERE ...</span>]
+ GROUP BY <em class="replaceable"><code>grouping_column_reference</code></em> [<span class="optional">, <em class="replaceable"><code>grouping_column_reference</code></em></span>]...
+</pre><p>
+ The <a class="link" href="sql-select.html#SQL-GROUPBY" title="GROUP BY Clause"><code class="literal">GROUP BY</code></a> clause is
+ used to group together those rows in a table that have the same
+ values in all the columns listed. The order in which the columns
+ are listed does not matter. The effect is to combine each set
+ of rows having common values into one group row that
+ represents all rows in the group. This is done to
+ eliminate redundancy in the output and/or compute aggregates that
+ apply to these groups. For instance:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM test1;</code></strong>
+ x | y
+---+---
+ a | 3
+ c | 2
+ b | 5
+ a | 1
+(4 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT x FROM test1 GROUP BY x;</code></strong>
+ x
+---
+ a
+ b
+ c
+(3 rows)
+</pre><p>
+ </p><p>
+ In the second query, we could not have written <code class="literal">SELECT *
+ FROM test1 GROUP BY x</code>, because there is no single value
+ for the column <code class="literal">y</code> that could be associated with each
+ group. The grouped-by columns can be referenced in the select list since
+ they have a single value in each group.
+ </p><p>
+ In general, if a table is grouped, columns that are not
+ listed in <code class="literal">GROUP BY</code> cannot be referenced except in aggregate
+ expressions. An example with aggregate expressions is:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT x, sum(y) FROM test1 GROUP BY x;</code></strong>
+ x | sum
+---+-----
+ a | 4
+ b | 5
+ c | 2
+(3 rows)
+</pre><p>
+ Here <code class="literal">sum</code> is an aggregate function that
+ computes a single value over the entire group. More information
+ about the available aggregate functions can be found in <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Grouping without aggregate expressions effectively calculates the
+ set of distinct values in a column. This can also be achieved
+ using the <code class="literal">DISTINCT</code> clause (see <a class="xref" href="queries-select-lists.html#QUERIES-DISTINCT" title="7.3.3. DISTINCT">Section 7.3.3</a>).
+ </p></div><p>
+ Here is another example: it calculates the total sales for each
+ product (rather than the total sales of all products):
+</p><pre class="programlisting">
+SELECT product_id, p.name, (sum(s.units) * p.price) AS sales
+ FROM products p LEFT JOIN sales s USING (product_id)
+ GROUP BY product_id, p.name, p.price;
+</pre><p>
+ In this example, the columns <code class="literal">product_id</code>,
+ <code class="literal">p.name</code>, and <code class="literal">p.price</code> must be
+ in the <code class="literal">GROUP BY</code> clause since they are referenced in
+ the query select list (but see below). The column
+ <code class="literal">s.units</code> does not have to be in the <code class="literal">GROUP
+ BY</code> list since it is only used in an aggregate expression
+ (<code class="literal">sum(...)</code>), which represents the sales
+ of a product. For each product, the query returns a summary row about
+ all sales of the product.
+ </p><a id="id-1.5.6.6.7.11" class="indexterm"></a><p>
+ If the products table is set up so that, say,
+ <code class="literal">product_id</code> is the primary key, then it would be
+ enough to group by <code class="literal">product_id</code> in the above example,
+ since name and price would be <em class="firstterm">functionally
+ dependent</em> on the product ID, and so there would be no
+ ambiguity about which name and price value to return for each product
+ ID group.
+ </p><p>
+ In strict SQL, <code class="literal">GROUP BY</code> can only group by columns of
+ the source table but <span class="productname">PostgreSQL</span> extends
+ this to also allow <code class="literal">GROUP BY</code> to group by columns in the
+ select list. Grouping by value expressions instead of simple
+ column names is also allowed.
+ </p><a id="id-1.5.6.6.7.14" class="indexterm"></a><p>
+ If a table has been grouped using <code class="literal">GROUP BY</code>,
+ but only certain groups are of interest, the
+ <code class="literal">HAVING</code> clause can be used, much like a
+ <code class="literal">WHERE</code> clause, to eliminate groups from the result.
+ The syntax is:
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_list</code></em> FROM ... [<span class="optional">WHERE ...</span>] GROUP BY ... HAVING <em class="replaceable"><code>boolean_expression</code></em>
+</pre><p>
+ Expressions in the <code class="literal">HAVING</code> clause can refer both to
+ grouped expressions and to ungrouped expressions (which necessarily
+ involve an aggregate function).
+ </p><p>
+ Example:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT x, sum(y) FROM test1 GROUP BY x HAVING sum(y) &gt; 3;</code></strong>
+ x | sum
+---+-----
+ a | 4
+ b | 5
+(2 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT x, sum(y) FROM test1 GROUP BY x HAVING x &lt; 'c';</code></strong>
+ x | sum
+---+-----
+ a | 4
+ b | 5
+(2 rows)
+</pre><p>
+ </p><p>
+ Again, a more realistic example:
+</p><pre class="programlisting">
+SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit
+ FROM products p LEFT JOIN sales s USING (product_id)
+ WHERE s.date &gt; CURRENT_DATE - INTERVAL '4 weeks'
+ GROUP BY product_id, p.name, p.price, p.cost
+ HAVING sum(p.price * s.units) &gt; 5000;
+</pre><p>
+ In the example above, the <code class="literal">WHERE</code> clause is selecting
+ rows by a column that is not grouped (the expression is only true for
+ sales during the last four weeks), while the <code class="literal">HAVING</code>
+ clause restricts the output to groups with total gross sales over
+ 5000. Note that the aggregate expressions do not necessarily need
+ to be the same in all parts of the query.
+ </p><p>
+ If a query contains aggregate function calls, but no <code class="literal">GROUP BY</code>
+ clause, grouping still occurs: the result is a single group row (or
+ perhaps no rows at all, if the single row is then eliminated by
+ <code class="literal">HAVING</code>).
+ The same is true if it contains a <code class="literal">HAVING</code> clause, even
+ without any aggregate function calls or <code class="literal">GROUP BY</code> clause.
+ </p></div><div class="sect2" id="QUERIES-GROUPING-SETS"><div class="titlepage"><div><div><h3 class="title">7.2.4. <code class="literal">GROUPING SETS</code>, <code class="literal">CUBE</code>, and <code class="literal">ROLLUP</code></h3></div></div></div><a id="id-1.5.6.6.8.2" class="indexterm"></a><a id="id-1.5.6.6.8.3" class="indexterm"></a><a id="id-1.5.6.6.8.4" class="indexterm"></a><p>
+ More complex grouping operations than those described above are possible
+ using the concept of <em class="firstterm">grouping sets</em>. The data selected by
+ the <code class="literal">FROM</code> and <code class="literal">WHERE</code> clauses is grouped separately
+ by each specified grouping set, aggregates computed for each group just as
+ for simple <code class="literal">GROUP BY</code> clauses, and then the results returned.
+ For example:
+</p><pre class="screen">
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT * FROM items_sold;</code></strong>
+ brand | size | sales
+-------+------+-------
+ Foo | L | 10
+ Foo | M | 20
+ Bar | M | 15
+ Bar | L | 5
+(4 rows)
+
+<code class="prompt">=&gt;</code> <strong class="userinput"><code>SELECT brand, size, sum(sales) FROM items_sold GROUP BY GROUPING SETS ((brand), (size), ());</code></strong>
+ brand | size | sum
+-------+------+-----
+ Foo | | 30
+ Bar | | 20
+ | L | 15
+ | M | 35
+ | | 50
+(5 rows)
+</pre><p>
+ </p><p>
+ Each sublist of <code class="literal">GROUPING SETS</code> may specify zero or more columns
+ or expressions and is interpreted the same way as though it were directly
+ in the <code class="literal">GROUP BY</code> clause. An empty grouping set means that all
+ rows are aggregated down to a single group (which is output even if no
+ input rows were present), as described above for the case of aggregate
+ functions with no <code class="literal">GROUP BY</code> clause.
+ </p><p>
+ References to the grouping columns or expressions are replaced
+ by null values in result rows for grouping sets in which those
+ columns do not appear. To distinguish which grouping a particular output
+ row resulted from, see <a class="xref" href="functions-aggregate.html#FUNCTIONS-GROUPING-TABLE" title="Table 9.62. Grouping Operations">Table 9.62</a>.
+ </p><p>
+ A shorthand notation is provided for specifying two common types of grouping set.
+ A clause of the form
+</p><pre class="programlisting">
+ROLLUP ( <em class="replaceable"><code>e1</code></em>, <em class="replaceable"><code>e2</code></em>, <em class="replaceable"><code>e3</code></em>, ... )
+</pre><p>
+ represents the given list of expressions and all prefixes of the list including
+ the empty list; thus it is equivalent to
+</p><pre class="programlisting">
+GROUPING SETS (
+ ( <em class="replaceable"><code>e1</code></em>, <em class="replaceable"><code>e2</code></em>, <em class="replaceable"><code>e3</code></em>, ... ),
+ ...
+ ( <em class="replaceable"><code>e1</code></em>, <em class="replaceable"><code>e2</code></em> ),
+ ( <em class="replaceable"><code>e1</code></em> ),
+ ( )
+)
+</pre><p>
+ This is commonly used for analysis over hierarchical data; e.g., total
+ salary by department, division, and company-wide total.
+ </p><p>
+ A clause of the form
+</p><pre class="programlisting">
+CUBE ( <em class="replaceable"><code>e1</code></em>, <em class="replaceable"><code>e2</code></em>, ... )
+</pre><p>
+ represents the given list and all of its possible subsets (i.e., the power
+ set). Thus
+</p><pre class="programlisting">
+CUBE ( a, b, c )
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUPING SETS (
+ ( a, b, c ),
+ ( a, b ),
+ ( a, c ),
+ ( a ),
+ ( b, c ),
+ ( b ),
+ ( c ),
+ ( )
+)
+</pre><p>
+ </p><p>
+ The individual elements of a <code class="literal">CUBE</code> or <code class="literal">ROLLUP</code>
+ clause may be either individual expressions, or sublists of elements in
+ parentheses. In the latter case, the sublists are treated as single
+ units for the purposes of generating the individual grouping sets.
+ For example:
+</p><pre class="programlisting">
+CUBE ( (a, b), (c, d) )
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUPING SETS (
+ ( a, b, c, d ),
+ ( a, b ),
+ ( c, d ),
+ ( )
+)
+</pre><p>
+ and
+</p><pre class="programlisting">
+ROLLUP ( a, (b, c), d )
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUPING SETS (
+ ( a, b, c, d ),
+ ( a, b, c ),
+ ( a ),
+ ( )
+)
+</pre><p>
+ </p><p>
+ The <code class="literal">CUBE</code> and <code class="literal">ROLLUP</code> constructs can be used either
+ directly in the <code class="literal">GROUP BY</code> clause, or nested inside a
+ <code class="literal">GROUPING SETS</code> clause. If one <code class="literal">GROUPING SETS</code> clause
+ is nested inside another, the effect is the same as if all the elements of
+ the inner clause had been written directly in the outer clause.
+ </p><p>
+ If multiple grouping items are specified in a single <code class="literal">GROUP BY</code>
+ clause, then the final list of grouping sets is the cross product of the
+ individual items. For example:
+</p><pre class="programlisting">
+GROUP BY a, CUBE (b, c), GROUPING SETS ((d), (e))
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUP BY GROUPING SETS (
+ (a, b, c, d), (a, b, c, e),
+ (a, b, d), (a, b, e),
+ (a, c, d), (a, c, e),
+ (a, d), (a, e)
+)
+</pre><p>
+ </p><p>
+ <a id="id-1.5.6.6.8.13.1" class="indexterm"></a>
+ <a id="id-1.5.6.6.8.13.2" class="indexterm"></a>
+ When specifying multiple grouping items together, the final set of grouping
+ sets might contain duplicates. For example:
+</p><pre class="programlisting">
+GROUP BY ROLLUP (a, b), ROLLUP (a, c)
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUP BY GROUPING SETS (
+ (a, b, c),
+ (a, b),
+ (a, b),
+ (a, c),
+ (a),
+ (a),
+ (a, c),
+ (a),
+ ()
+)
+</pre><p>
+ If these duplicates are undesirable, they can be removed using the
+ <code class="literal">DISTINCT</code> clause directly on the <code class="literal">GROUP BY</code>.
+ Therefore:
+</p><pre class="programlisting">
+GROUP BY <span class="emphasis"><strong>DISTINCT</strong></span> ROLLUP (a, b), ROLLUP (a, c)
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+GROUP BY GROUPING SETS (
+ (a, b, c),
+ (a, b),
+ (a, c),
+ (a),
+ ()
+)
+</pre><p>
+ This is not the same as using <code class="literal">SELECT DISTINCT</code> because the output
+ rows may still contain duplicates. If any of the ungrouped columns contains NULL,
+ it will be indistinguishable from the NULL used when that same column is grouped.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The construct <code class="literal">(a, b)</code> is normally recognized in expressions as
+ a <a class="link" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">row constructor</a>.
+ Within the <code class="literal">GROUP BY</code> clause, this does not apply at the top
+ levels of expressions, and <code class="literal">(a, b)</code> is parsed as a list of
+ expressions as described above. If for some reason you <span class="emphasis"><em>need</em></span>
+ a row constructor in a grouping expression, use <code class="literal">ROW(a, b)</code>.
+ </p></div></div><div class="sect2" id="QUERIES-WINDOW"><div class="titlepage"><div><div><h3 class="title">7.2.5. Window Function Processing</h3></div></div></div><a id="id-1.5.6.6.9.2" class="indexterm"></a><p>
+ If the query contains any window functions (see
+ <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a>,
+ <a class="xref" href="functions-window.html" title="9.22. Window Functions">Section 9.22</a> and
+ <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a>), these functions are evaluated
+ after any grouping, aggregation, and <code class="literal">HAVING</code> filtering is
+ performed. That is, if the query uses any aggregates, <code class="literal">GROUP
+ BY</code>, or <code class="literal">HAVING</code>, then the rows seen by the window functions
+ are the group rows instead of the original table rows from
+ <code class="literal">FROM</code>/<code class="literal">WHERE</code>.
+ </p><p>
+ When multiple window functions are used, all the window functions having
+ syntactically equivalent <code class="literal">PARTITION BY</code> and <code class="literal">ORDER BY</code>
+ clauses in their window definitions are guaranteed to be evaluated in a
+ single pass over the data. Therefore they will see the same sort ordering,
+ even if the <code class="literal">ORDER BY</code> does not uniquely determine an ordering.
+ However, no guarantees are made about the evaluation of functions having
+ different <code class="literal">PARTITION BY</code> or <code class="literal">ORDER BY</code> specifications.
+ (In such cases a sort step is typically required between the passes of
+ window function evaluations, and the sort is not guaranteed to preserve
+ ordering of rows that its <code class="literal">ORDER BY</code> sees as equivalent.)
+ </p><p>
+ Currently, window functions always require presorted data, and so the
+ query output will be ordered according to one or another of the window
+ functions' <code class="literal">PARTITION BY</code>/<code class="literal">ORDER BY</code> clauses.
+ It is not recommended to rely on this, however. Use an explicit
+ top-level <code class="literal">ORDER BY</code> clause if you want to be sure the
+ results are sorted in a particular way.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-overview.html" title="7.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-select-lists.html" title="7.3. Select Lists">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.3. Select Lists</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-union.html b/doc/src/sgml/html/queries-union.html
new file mode 100644
index 0000000..24f26ba
--- /dev/null
+++ b/doc/src/sgml/html/queries-union.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.4. Combining Queries (UNION, INTERSECT, EXCEPT)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-select-lists.html" title="7.3. Select Lists" /><link rel="next" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-select-lists.html" title="7.3. Select Lists">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-UNION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>)</h2></div></div></div><a id="id-1.5.6.8.2" class="indexterm"></a><a id="id-1.5.6.8.3" class="indexterm"></a><a id="id-1.5.6.8.4" class="indexterm"></a><a id="id-1.5.6.8.5" class="indexterm"></a><a id="id-1.5.6.8.6" class="indexterm"></a><a id="id-1.5.6.8.7" class="indexterm"></a><a id="id-1.5.6.8.8" class="indexterm"></a><p>
+ The results of two queries can be combined using the set operations
+ union, intersection, and difference. The syntax is
+</p><pre class="synopsis">
+<em class="replaceable"><code>query1</code></em> UNION [<span class="optional">ALL</span>] <em class="replaceable"><code>query2</code></em>
+<em class="replaceable"><code>query1</code></em> INTERSECT [<span class="optional">ALL</span>] <em class="replaceable"><code>query2</code></em>
+<em class="replaceable"><code>query1</code></em> EXCEPT [<span class="optional">ALL</span>] <em class="replaceable"><code>query2</code></em>
+</pre><p>
+ where <em class="replaceable"><code>query1</code></em> and
+ <em class="replaceable"><code>query2</code></em> are queries that can use any of
+ the features discussed up to this point.
+ </p><p>
+ <code class="literal">UNION</code> effectively appends the result of
+ <em class="replaceable"><code>query2</code></em> to the result of
+ <em class="replaceable"><code>query1</code></em> (although there is no guarantee
+ that this is the order in which the rows are actually returned).
+ Furthermore, it eliminates duplicate rows from its result, in the same
+ way as <code class="literal">DISTINCT</code>, unless <code class="literal">UNION ALL</code> is used.
+ </p><p>
+ <code class="literal">INTERSECT</code> returns all rows that are both in the result
+ of <em class="replaceable"><code>query1</code></em> and in the result of
+ <em class="replaceable"><code>query2</code></em>. Duplicate rows are eliminated
+ unless <code class="literal">INTERSECT ALL</code> is used.
+ </p><p>
+ <code class="literal">EXCEPT</code> returns all rows that are in the result of
+ <em class="replaceable"><code>query1</code></em> but not in the result of
+ <em class="replaceable"><code>query2</code></em>. (This is sometimes called the
+ <em class="firstterm">difference</em> between two queries.) Again, duplicates
+ are eliminated unless <code class="literal">EXCEPT ALL</code> is used.
+ </p><p>
+ In order to calculate the union, intersection, or difference of two
+ queries, the two queries must be <span class="quote">“<span class="quote">union compatible</span>”</span>,
+ which means that they return the same number of columns and
+ the corresponding columns have compatible data types, as
+ described in <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>.
+ </p><p>
+ Set operations can be combined, for example
+</p><pre class="synopsis">
+<em class="replaceable"><code>query1</code></em> UNION <em class="replaceable"><code>query2</code></em> EXCEPT <em class="replaceable"><code>query3</code></em>
+</pre><p>
+ which is equivalent to
+</p><pre class="synopsis">
+(<em class="replaceable"><code>query1</code></em> UNION <em class="replaceable"><code>query2</code></em>) EXCEPT <em class="replaceable"><code>query3</code></em>
+</pre><p>
+ As shown here, you can use parentheses to control the order of
+ evaluation. Without parentheses, <code class="literal">UNION</code>
+ and <code class="literal">EXCEPT</code> associate left-to-right,
+ but <code class="literal">INTERSECT</code> binds more tightly than those two
+ operators. Thus
+</p><pre class="synopsis">
+<em class="replaceable"><code>query1</code></em> UNION <em class="replaceable"><code>query2</code></em> INTERSECT <em class="replaceable"><code>query3</code></em>
+</pre><p>
+ means
+</p><pre class="synopsis">
+<em class="replaceable"><code>query1</code></em> UNION (<em class="replaceable"><code>query2</code></em> INTERSECT <em class="replaceable"><code>query3</code></em>)
+</pre><p>
+ You can also surround an individual <em class="replaceable"><code>query</code></em>
+ with parentheses. This is important if
+ the <em class="replaceable"><code>query</code></em> needs to use any of the clauses
+ discussed in following sections, such as <code class="literal">LIMIT</code>.
+ Without parentheses, you'll get a syntax error, or else the clause will
+ be understood as applying to the output of the set operation rather
+ than one of its inputs. For example,
+</p><pre class="synopsis">
+SELECT a FROM b UNION SELECT x FROM y LIMIT 10
+</pre><p>
+ is accepted, but it means
+</p><pre class="synopsis">
+(SELECT a FROM b UNION SELECT x FROM y) LIMIT 10
+</pre><p>
+ not
+</p><pre class="synopsis">
+SELECT a FROM b UNION (SELECT x FROM y LIMIT 10)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-select-lists.html" title="7.3. Select Lists">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.3. Select Lists </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.5. Sorting Rows (<code class="literal">ORDER BY</code>)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-values.html b/doc/src/sgml/html/queries-values.html
new file mode 100644
index 0000000..fc90277
--- /dev/null
+++ b/doc/src/sgml/html/queries-values.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.7. VALUES Lists</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-limit.html" title="7.6. LIMIT and OFFSET" /><link rel="next" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.7. <code class="literal">VALUES</code> Lists</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-limit.html" title="7.6. LIMIT and OFFSET">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-VALUES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.7. <code class="literal">VALUES</code> Lists</h2></div></div></div><a id="id-1.5.6.11.2" class="indexterm"></a><p>
+ <code class="literal">VALUES</code> provides a way to generate a <span class="quote">“<span class="quote">constant table</span>”</span>
+ that can be used in a query without having to actually create and populate
+ a table on-disk. The syntax is
+</p><pre class="synopsis">
+VALUES ( <em class="replaceable"><code>expression</code></em> [, ...] ) [, ...]
+</pre><p>
+ Each parenthesized list of expressions generates a row in the table.
+ The lists must all have the same number of elements (i.e., the number
+ of columns in the table), and corresponding entries in each list must
+ have compatible data types. The actual data type assigned to each column
+ of the result is determined using the same rules as for <code class="literal">UNION</code>
+ (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
+ </p><p>
+ As an example:
+</p><pre class="programlisting">
+VALUES (1, 'one'), (2, 'two'), (3, 'three');
+</pre><p>
+
+ will return a table of two columns and three rows. It's effectively
+ equivalent to:
+</p><pre class="programlisting">
+SELECT 1 AS column1, 'one' AS column2
+UNION ALL
+SELECT 2, 'two'
+UNION ALL
+SELECT 3, 'three';
+</pre><p>
+
+ By default, <span class="productname">PostgreSQL</span> assigns the names
+ <code class="literal">column1</code>, <code class="literal">column2</code>, etc. to the columns of a
+ <code class="literal">VALUES</code> table. The column names are not specified by the
+ SQL standard and different database systems do it differently, so
+ it's usually better to override the default names with a table alias
+ list, like this:
+</p><pre class="programlisting">
+=&gt; SELECT * FROM (VALUES (1, 'one'), (2, 'two'), (3, 'three')) AS t (num,letter);
+ num | letter
+-----+--------
+ 1 | one
+ 2 | two
+ 3 | three
+(3 rows)
+</pre><p>
+ </p><p>
+ Syntactically, <code class="literal">VALUES</code> followed by expression lists is
+ treated as equivalent to:
+</p><pre class="synopsis">
+SELECT <em class="replaceable"><code>select_list</code></em> FROM <em class="replaceable"><code>table_expression</code></em>
+</pre><p>
+ and can appear anywhere a <code class="literal">SELECT</code> can. For example, you can
+ use it as part of a <code class="literal">UNION</code>, or attach a
+ <em class="replaceable"><code>sort_specification</code></em> (<code class="literal">ORDER BY</code>,
+ <code class="literal">LIMIT</code>, and/or <code class="literal">OFFSET</code>) to it. <code class="literal">VALUES</code>
+ is most commonly used as the data source in an <code class="command">INSERT</code> command,
+ and next most commonly as a subquery.
+ </p><p>
+ For more information see <a class="xref" href="sql-values.html" title="VALUES"><span class="refentrytitle">VALUES</span></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-limit.html" title="7.6. LIMIT and OFFSET">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.8. <code class="literal">WITH</code> Queries (Common Table Expressions)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries-with.html b/doc/src/sgml/html/queries-with.html
new file mode 100644
index 0000000..799b40d
--- /dev/null
+++ b/doc/src/sgml/html/queries-with.html
@@ -0,0 +1,564 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>7.8. WITH Queries (Common Table Expressions)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="queries-values.html" title="7.7. VALUES Lists" /><link rel="next" href="datatype.html" title="Chapter 8. Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">7.8. <code class="literal">WITH</code> Queries (Common Table Expressions)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="queries-values.html" title="7.7. VALUES Lists">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><th width="60%" align="center">Chapter 7. Queries</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype.html" title="Chapter 8. Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERIES-WITH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.8. <code class="literal">WITH</code> Queries (Common Table Expressions)</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-SELECT">7.8.1. <code class="command">SELECT</code> in <code class="literal">WITH</code></a></span></dt><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-RECURSIVE">7.8.2. Recursive Queries</a></span></dt><dt><span class="sect2"><a href="queries-with.html#id-1.5.6.12.7">7.8.3. Common Table Expression Materialization</a></span></dt><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-MODIFYING">7.8.4. Data-Modifying Statements in <code class="literal">WITH</code></a></span></dt></dl></div><a id="id-1.5.6.12.2" class="indexterm"></a><a id="id-1.5.6.12.3" class="indexterm"></a><p>
+ <code class="literal">WITH</code> provides a way to write auxiliary statements for use in a
+ larger query. These statements, which are often referred to as Common
+ Table Expressions or <acronym class="acronym">CTE</acronym>s, can be thought of as defining
+ temporary tables that exist just for one query. Each auxiliary statement
+ in a <code class="literal">WITH</code> clause can be a <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code>; and the
+ <code class="literal">WITH</code> clause itself is attached to a primary statement that can
+ be a <code class="command">SELECT</code>, <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, or <code class="command">MERGE</code>.
+ </p><div class="sect2" id="QUERIES-WITH-SELECT"><div class="titlepage"><div><div><h3 class="title">7.8.1. <code class="command">SELECT</code> in <code class="literal">WITH</code></h3></div></div></div><p>
+ The basic value of <code class="command">SELECT</code> in <code class="literal">WITH</code> is to
+ break down complicated queries into simpler parts. An example is:
+
+</p><pre class="programlisting">
+WITH regional_sales AS (
+ SELECT region, SUM(amount) AS total_sales
+ FROM orders
+ GROUP BY region
+), top_regions AS (
+ SELECT region
+ FROM regional_sales
+ WHERE total_sales &gt; (SELECT SUM(total_sales)/10 FROM regional_sales)
+)
+SELECT region,
+ product,
+ SUM(quantity) AS product_units,
+ SUM(amount) AS product_sales
+FROM orders
+WHERE region IN (SELECT region FROM top_regions)
+GROUP BY region, product;
+</pre><p>
+
+ which displays per-product sales totals in only the top sales regions.
+ The <code class="literal">WITH</code> clause defines two auxiliary statements named
+ <code class="structname">regional_sales</code> and <code class="structname">top_regions</code>,
+ where the output of <code class="structname">regional_sales</code> is used in
+ <code class="structname">top_regions</code> and the output of <code class="structname">top_regions</code>
+ is used in the primary <code class="command">SELECT</code> query.
+ This example could have been written without <code class="literal">WITH</code>,
+ but we'd have needed two levels of nested sub-<code class="command">SELECT</code>s. It's a bit
+ easier to follow this way.
+ </p></div><div class="sect2" id="QUERIES-WITH-RECURSIVE"><div class="titlepage"><div><div><h3 class="title">7.8.2. Recursive Queries</h3></div></div></div><p>
+ <a id="id-1.5.6.12.6.2.1" class="indexterm"></a>
+ The optional <code class="literal">RECURSIVE</code> modifier changes <code class="literal">WITH</code>
+ from a mere syntactic convenience into a feature that accomplishes
+ things not otherwise possible in standard SQL. Using
+ <code class="literal">RECURSIVE</code>, a <code class="literal">WITH</code> query can refer to its own
+ output. A very simple example is this query to sum the integers from 1
+ through 100:
+
+</p><pre class="programlisting">
+WITH RECURSIVE t(n) AS (
+ VALUES (1)
+ UNION ALL
+ SELECT n+1 FROM t WHERE n &lt; 100
+)
+SELECT sum(n) FROM t;
+</pre><p>
+
+ The general form of a recursive <code class="literal">WITH</code> query is always a
+ <em class="firstterm">non-recursive term</em>, then <code class="literal">UNION</code> (or
+ <code class="literal">UNION ALL</code>), then a
+ <em class="firstterm">recursive term</em>, where only the recursive term can contain
+ a reference to the query's own output. Such a query is executed as
+ follows:
+ </p><div class="procedure" id="id-1.5.6.12.6.3"><p class="title"><strong>Recursive Query Evaluation</strong></p><ol class="procedure" type="1"><li class="step"><p>
+ Evaluate the non-recursive term. For <code class="literal">UNION</code> (but not
+ <code class="literal">UNION ALL</code>), discard duplicate rows. Include all remaining
+ rows in the result of the recursive query, and also place them in a
+ temporary <em class="firstterm">working table</em>.
+ </p></li><li class="step"><p>
+ So long as the working table is not empty, repeat these steps:
+ </p><ol type="a" class="substeps"><li class="step"><p>
+ Evaluate the recursive term, substituting the current contents of
+ the working table for the recursive self-reference.
+ For <code class="literal">UNION</code> (but not <code class="literal">UNION ALL</code>), discard
+ duplicate rows and rows that duplicate any previous result row.
+ Include all remaining rows in the result of the recursive query, and
+ also place them in a temporary <em class="firstterm">intermediate table</em>.
+ </p></li><li class="step"><p>
+ Replace the contents of the working table with the contents of the
+ intermediate table, then empty the intermediate table.
+ </p></li></ol></li></ol></div><div class="note"><h3 class="title">Note</h3><p>
+ While <code class="literal">RECURSIVE</code> allows queries to be specified
+ recursively, internally such queries are evaluated iteratively.
+ </p></div><p>
+ In the example above, the working table has just a single row in each step,
+ and it takes on the values from 1 through 100 in successive steps. In
+ the 100th step, there is no output because of the <code class="literal">WHERE</code>
+ clause, and so the query terminates.
+ </p><p>
+ Recursive queries are typically used to deal with hierarchical or
+ tree-structured data. A useful example is this query to find all the
+ direct and indirect sub-parts of a product, given only a table that
+ shows immediate inclusions:
+
+</p><pre class="programlisting">
+WITH RECURSIVE included_parts(sub_part, part, quantity) AS (
+ SELECT sub_part, part, quantity FROM parts WHERE part = 'our_product'
+ UNION ALL
+ SELECT p.sub_part, p.part, p.quantity * pr.quantity
+ FROM included_parts pr, parts p
+ WHERE p.part = pr.sub_part
+)
+SELECT sub_part, SUM(quantity) as total_quantity
+FROM included_parts
+GROUP BY sub_part
+</pre><p>
+ </p><div class="sect3" id="QUERIES-WITH-SEARCH"><div class="titlepage"><div><div><h4 class="title">7.8.2.1. Search Order</h4></div></div></div><p>
+ When computing a tree traversal using a recursive query, you might want to
+ order the results in either depth-first or breadth-first order. This can
+ be done by computing an ordering column alongside the other data columns
+ and using that to sort the results at the end. Note that this does not
+ actually control in which order the query evaluation visits the rows; that
+ is as always in SQL implementation-dependent. This approach merely
+ provides a convenient way to order the results afterwards.
+ </p><p>
+ To create a depth-first order, we compute for each result row an array of
+ rows that we have visited so far. For example, consider the following
+ query that searches a table <code class="structname">tree</code> using a
+ <code class="structfield">link</code> field:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_tree(id, link, data) AS (
+ SELECT t.id, t.link, t.data
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+)
+SELECT * FROM search_tree;
+</pre><p>
+
+ To add depth-first ordering information, you can write this:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_tree(id, link, data, <span class="emphasis"><strong>path</strong></span>) AS (
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>ARRAY[t.id]</strong></span>
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>path || t.id</strong></span>
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+)
+SELECT * FROM search_tree <span class="emphasis"><strong>ORDER BY path</strong></span>;
+</pre><p>
+ </p><p>
+ In the general case where more than one field needs to be used to identify
+ a row, use an array of rows. For example, if we needed to track fields
+ <code class="structfield">f1</code> and <code class="structfield">f2</code>:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_tree(id, link, data, <span class="emphasis"><strong>path</strong></span>) AS (
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>ARRAY[ROW(t.f1, t.f2)]</strong></span>
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>path || ROW(t.f1, t.f2)</strong></span>
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+)
+SELECT * FROM search_tree <span class="emphasis"><strong>ORDER BY path</strong></span>;
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Omit the <code class="literal">ROW()</code> syntax in the common case where only one
+ field needs to be tracked. This allows a simple array rather than a
+ composite-type array to be used, gaining efficiency.
+ </p></div><p>
+ To create a breadth-first order, you can add a column that tracks the depth
+ of the search, for example:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_tree(id, link, data, <span class="emphasis"><strong>depth</strong></span>) AS (
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>0</strong></span>
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data, <span class="emphasis"><strong>depth + 1</strong></span>
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+)
+SELECT * FROM search_tree <span class="emphasis"><strong>ORDER BY depth</strong></span>;
+</pre><p>
+
+ To get a stable sort, add data columns as secondary sorting columns.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The recursive query evaluation algorithm produces its output in
+ breadth-first search order. However, this is an implementation detail and
+ it is perhaps unsound to rely on it. The order of the rows within each
+ level is certainly undefined, so some explicit ordering might be desired
+ in any case.
+ </p></div><p>
+ There is built-in syntax to compute a depth- or breadth-first sort column.
+ For example:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_tree(id, link, data) AS (
+ SELECT t.id, t.link, t.data
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+) <span class="emphasis"><strong>SEARCH DEPTH FIRST BY id SET ordercol</strong></span>
+SELECT * FROM search_tree ORDER BY ordercol;
+
+WITH RECURSIVE search_tree(id, link, data) AS (
+ SELECT t.id, t.link, t.data
+ FROM tree t
+ UNION ALL
+ SELECT t.id, t.link, t.data
+ FROM tree t, search_tree st
+ WHERE t.id = st.link
+) <span class="emphasis"><strong>SEARCH BREADTH FIRST BY id SET ordercol</strong></span>
+SELECT * FROM search_tree ORDER BY ordercol;
+</pre><p>
+ This syntax is internally expanded to something similar to the above
+ hand-written forms. The <code class="literal">SEARCH</code> clause specifies whether
+ depth- or breadth first search is wanted, the list of columns to track for
+ sorting, and a column name that will contain the result data that can be
+ used for sorting. That column will implicitly be added to the output rows
+ of the CTE.
+ </p></div><div class="sect3" id="QUERIES-WITH-CYCLE"><div class="titlepage"><div><div><h4 class="title">7.8.2.2. Cycle Detection</h4></div></div></div><p>
+ When working with recursive queries it is important to be sure that
+ the recursive part of the query will eventually return no tuples,
+ or else the query will loop indefinitely. Sometimes, using
+ <code class="literal">UNION</code> instead of <code class="literal">UNION ALL</code> can accomplish this
+ by discarding rows that duplicate previous output rows. However, often a
+ cycle does not involve output rows that are completely duplicate: it may be
+ necessary to check just one or a few fields to see if the same point has
+ been reached before. The standard method for handling such situations is
+ to compute an array of the already-visited values. For example, consider again
+ the following query that searches a table <code class="structname">graph</code> using a
+ <code class="structfield">link</code> field:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_graph(id, link, data, depth) AS (
+ SELECT g.id, g.link, g.data, 0
+ FROM graph g
+ UNION ALL
+ SELECT g.id, g.link, g.data, sg.depth + 1
+ FROM graph g, search_graph sg
+ WHERE g.id = sg.link
+)
+SELECT * FROM search_graph;
+</pre><p>
+
+ This query will loop if the <code class="structfield">link</code> relationships contain
+ cycles. Because we require a <span class="quote">“<span class="quote">depth</span>”</span> output, just changing
+ <code class="literal">UNION ALL</code> to <code class="literal">UNION</code> would not eliminate the looping.
+ Instead we need to recognize whether we have reached the same row again
+ while following a particular path of links. We add two columns
+ <code class="structfield">is_cycle</code> and <code class="structfield">path</code> to the loop-prone query:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_graph(id, link, data, depth, <span class="emphasis"><strong>is_cycle, path</strong></span>) AS (
+ SELECT g.id, g.link, g.data, 0,
+ <span class="emphasis"><strong>false,
+ ARRAY[g.id]</strong></span>
+ FROM graph g
+ UNION ALL
+ SELECT g.id, g.link, g.data, sg.depth + 1,
+ <span class="emphasis"><strong>g.id = ANY(path),
+ path || g.id</strong></span>
+ FROM graph g, search_graph sg
+ WHERE g.id = sg.link <span class="emphasis"><strong>AND NOT is_cycle</strong></span>
+)
+SELECT * FROM search_graph;
+</pre><p>
+
+ Aside from preventing cycles, the array value is often useful in its own
+ right as representing the <span class="quote">“<span class="quote">path</span>”</span> taken to reach any particular row.
+ </p><p>
+ In the general case where more than one field needs to be checked to
+ recognize a cycle, use an array of rows. For example, if we needed to
+ compare fields <code class="structfield">f1</code> and <code class="structfield">f2</code>:
+
+</p><pre class="programlisting">
+WITH RECURSIVE search_graph(id, link, data, depth, <span class="emphasis"><strong>is_cycle, path</strong></span>) AS (
+ SELECT g.id, g.link, g.data, 0,
+ <span class="emphasis"><strong>false,
+ ARRAY[ROW(g.f1, g.f2)]</strong></span>
+ FROM graph g
+ UNION ALL
+ SELECT g.id, g.link, g.data, sg.depth + 1,
+ <span class="emphasis"><strong>ROW(g.f1, g.f2) = ANY(path),
+ path || ROW(g.f1, g.f2)</strong></span>
+ FROM graph g, search_graph sg
+ WHERE g.id = sg.link <span class="emphasis"><strong>AND NOT is_cycle</strong></span>
+)
+SELECT * FROM search_graph;
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Omit the <code class="literal">ROW()</code> syntax in the common case where only one field
+ needs to be checked to recognize a cycle. This allows a simple array
+ rather than a composite-type array to be used, gaining efficiency.
+ </p></div><p>
+ There is built-in syntax to simplify cycle detection. The above query can
+ also be written like this:
+</p><pre class="programlisting">
+WITH RECURSIVE search_graph(id, link, data, depth) AS (
+ SELECT g.id, g.link, g.data, 1
+ FROM graph g
+ UNION ALL
+ SELECT g.id, g.link, g.data, sg.depth + 1
+ FROM graph g, search_graph sg
+ WHERE g.id = sg.link
+) <span class="emphasis"><strong>CYCLE id SET is_cycle USING path</strong></span>
+SELECT * FROM search_graph;
+</pre><p>
+ and it will be internally rewritten to the above form. The
+ <code class="literal">CYCLE</code> clause specifies first the list of columns to
+ track for cycle detection, then a column name that will show whether a
+ cycle has been detected, and finally the name of another column that will track the
+ path. The cycle and path columns will implicitly be added to the output
+ rows of the CTE.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The cycle path column is computed in the same way as the depth-first
+ ordering column show in the previous section. A query can have both a
+ <code class="literal">SEARCH</code> and a <code class="literal">CYCLE</code> clause, but a
+ depth-first search specification and a cycle detection specification would
+ create redundant computations, so it's more efficient to just use the
+ <code class="literal">CYCLE</code> clause and order by the path column. If
+ breadth-first ordering is wanted, then specifying both
+ <code class="literal">SEARCH</code> and <code class="literal">CYCLE</code> can be useful.
+ </p></div><p>
+ A helpful trick for testing queries
+ when you are not certain if they might loop is to place a <code class="literal">LIMIT</code>
+ in the parent query. For example, this query would loop forever without
+ the <code class="literal">LIMIT</code>:
+
+</p><pre class="programlisting">
+WITH RECURSIVE t(n) AS (
+ SELECT 1
+ UNION ALL
+ SELECT n+1 FROM t
+)
+SELECT n FROM t <span class="emphasis"><strong>LIMIT 100</strong></span>;
+</pre><p>
+
+ This works because <span class="productname">PostgreSQL</span>'s implementation
+ evaluates only as many rows of a <code class="literal">WITH</code> query as are actually
+ fetched by the parent query. Using this trick in production is not
+ recommended, because other systems might work differently. Also, it
+ usually won't work if you make the outer query sort the recursive query's
+ results or join them to some other table, because in such cases the
+ outer query will usually try to fetch all of the <code class="literal">WITH</code> query's
+ output anyway.
+ </p></div></div><div class="sect2" id="id-1.5.6.12.7"><div class="titlepage"><div><div><h3 class="title">7.8.3. Common Table Expression Materialization</h3></div></div></div><p>
+ A useful property of <code class="literal">WITH</code> queries is that they are
+ normally evaluated only once per execution of the parent query, even if
+ they are referred to more than once by the parent query or
+ sibling <code class="literal">WITH</code> queries.
+ Thus, expensive calculations that are needed in multiple places can be
+ placed within a <code class="literal">WITH</code> query to avoid redundant work. Another
+ possible application is to prevent unwanted multiple evaluations of
+ functions with side-effects.
+ However, the other side of this coin is that the optimizer is not able to
+ push restrictions from the parent query down into a multiply-referenced
+ <code class="literal">WITH</code> query, since that might affect all uses of the
+ <code class="literal">WITH</code> query's output when it should affect only one.
+ The multiply-referenced <code class="literal">WITH</code> query will be
+ evaluated as written, without suppression of rows that the parent query
+ might discard afterwards. (But, as mentioned above, evaluation might stop
+ early if the reference(s) to the query demand only a limited number of
+ rows.)
+ </p><p>
+ However, if a <code class="literal">WITH</code> query is non-recursive and
+ side-effect-free (that is, it is a <code class="literal">SELECT</code> containing
+ no volatile functions) then it can be folded into the parent query,
+ allowing joint optimization of the two query levels. By default, this
+ happens if the parent query references the <code class="literal">WITH</code> query
+ just once, but not if it references the <code class="literal">WITH</code> query
+ more than once. You can override that decision by
+ specifying <code class="literal">MATERIALIZED</code> to force separate calculation
+ of the <code class="literal">WITH</code> query, or by specifying <code class="literal">NOT
+ MATERIALIZED</code> to force it to be merged into the parent query.
+ The latter choice risks duplicate computation of
+ the <code class="literal">WITH</code> query, but it can still give a net savings if
+ each usage of the <code class="literal">WITH</code> query needs only a small part
+ of the <code class="literal">WITH</code> query's full output.
+ </p><p>
+ A simple example of these rules is
+</p><pre class="programlisting">
+WITH w AS (
+ SELECT * FROM big_table
+)
+SELECT * FROM w WHERE key = 123;
+</pre><p>
+ This <code class="literal">WITH</code> query will be folded, producing the same
+ execution plan as
+</p><pre class="programlisting">
+SELECT * FROM big_table WHERE key = 123;
+</pre><p>
+ In particular, if there's an index on <code class="structfield">key</code>,
+ it will probably be used to fetch just the rows having <code class="literal">key =
+ 123</code>. On the other hand, in
+</p><pre class="programlisting">
+WITH w AS (
+ SELECT * FROM big_table
+)
+SELECT * FROM w AS w1 JOIN w AS w2 ON w1.key = w2.ref
+WHERE w2.key = 123;
+</pre><p>
+ the <code class="literal">WITH</code> query will be materialized, producing a
+ temporary copy of <code class="structname">big_table</code> that is then
+ joined with itself — without benefit of any index. This query
+ will be executed much more efficiently if written as
+</p><pre class="programlisting">
+WITH w AS NOT MATERIALIZED (
+ SELECT * FROM big_table
+)
+SELECT * FROM w AS w1 JOIN w AS w2 ON w1.key = w2.ref
+WHERE w2.key = 123;
+</pre><p>
+ so that the parent query's restrictions can be applied directly
+ to scans of <code class="structname">big_table</code>.
+ </p><p>
+ An example where <code class="literal">NOT MATERIALIZED</code> could be
+ undesirable is
+</p><pre class="programlisting">
+WITH w AS (
+ SELECT key, very_expensive_function(val) as f FROM some_table
+)
+SELECT * FROM w AS w1 JOIN w AS w2 ON w1.f = w2.f;
+</pre><p>
+ Here, materialization of the <code class="literal">WITH</code> query ensures
+ that <code class="function">very_expensive_function</code> is evaluated only
+ once per table row, not twice.
+ </p><p>
+ The examples above only show <code class="literal">WITH</code> being used with
+ <code class="command">SELECT</code>, but it can be attached in the same way to
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, or <code class="command">MERGE</code>.
+ In each case it effectively provides temporary table(s) that can
+ be referred to in the main command.
+ </p></div><div class="sect2" id="QUERIES-WITH-MODIFYING"><div class="titlepage"><div><div><h3 class="title">7.8.4. Data-Modifying Statements in <code class="literal">WITH</code></h3></div></div></div><p>
+ You can use most data-modifying statements (<code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, or <code class="command">DELETE</code>, but not
+ <code class="command">MERGE</code>) in <code class="literal">WITH</code>. This
+ allows you to perform several different operations in the same query.
+ An example is:
+
+</p><pre class="programlisting">
+WITH moved_rows AS (
+ DELETE FROM products
+ WHERE
+ "date" &gt;= '2010-10-01' AND
+ "date" &lt; '2010-11-01'
+ RETURNING *
+)
+INSERT INTO products_log
+SELECT * FROM moved_rows;
+</pre><p>
+
+ This query effectively moves rows from <code class="structname">products</code> to
+ <code class="structname">products_log</code>. The <code class="command">DELETE</code> in <code class="literal">WITH</code>
+ deletes the specified rows from <code class="structname">products</code>, returning their
+ contents by means of its <code class="literal">RETURNING</code> clause; and then the
+ primary query reads that output and inserts it into
+ <code class="structname">products_log</code>.
+ </p><p>
+ A fine point of the above example is that the <code class="literal">WITH</code> clause is
+ attached to the <code class="command">INSERT</code>, not the sub-<code class="command">SELECT</code> within
+ the <code class="command">INSERT</code>. This is necessary because data-modifying
+ statements are only allowed in <code class="literal">WITH</code> clauses that are attached
+ to the top-level statement. However, normal <code class="literal">WITH</code> visibility
+ rules apply, so it is possible to refer to the <code class="literal">WITH</code>
+ statement's output from the sub-<code class="command">SELECT</code>.
+ </p><p>
+ Data-modifying statements in <code class="literal">WITH</code> usually have
+ <code class="literal">RETURNING</code> clauses (see <a class="xref" href="dml-returning.html" title="6.4. Returning Data from Modified Rows">Section 6.4</a>),
+ as shown in the example above.
+ It is the output of the <code class="literal">RETURNING</code> clause, <span class="emphasis"><em>not</em></span> the
+ target table of the data-modifying statement, that forms the temporary
+ table that can be referred to by the rest of the query. If a
+ data-modifying statement in <code class="literal">WITH</code> lacks a <code class="literal">RETURNING</code>
+ clause, then it forms no temporary table and cannot be referred to in
+ the rest of the query. Such a statement will be executed nonetheless.
+ A not-particularly-useful example is:
+
+</p><pre class="programlisting">
+WITH t AS (
+ DELETE FROM foo
+)
+DELETE FROM bar;
+</pre><p>
+
+ This example would remove all rows from tables <code class="structname">foo</code> and
+ <code class="structname">bar</code>. The number of affected rows reported to the client
+ would only include rows removed from <code class="structname">bar</code>.
+ </p><p>
+ Recursive self-references in data-modifying statements are not
+ allowed. In some cases it is possible to work around this limitation by
+ referring to the output of a recursive <code class="literal">WITH</code>, for example:
+
+</p><pre class="programlisting">
+WITH RECURSIVE included_parts(sub_part, part) AS (
+ SELECT sub_part, part FROM parts WHERE part = 'our_product'
+ UNION ALL
+ SELECT p.sub_part, p.part
+ FROM included_parts pr, parts p
+ WHERE p.part = pr.sub_part
+)
+DELETE FROM parts
+ WHERE part IN (SELECT part FROM included_parts);
+</pre><p>
+
+ This query would remove all direct and indirect subparts of a product.
+ </p><p>
+ Data-modifying statements in <code class="literal">WITH</code> are executed exactly once,
+ and always to completion, independently of whether the primary query
+ reads all (or indeed any) of their output. Notice that this is different
+ from the rule for <code class="command">SELECT</code> in <code class="literal">WITH</code>: as stated in the
+ previous section, execution of a <code class="command">SELECT</code> is carried only as far
+ as the primary query demands its output.
+ </p><p>
+ The sub-statements in <code class="literal">WITH</code> are executed concurrently with
+ each other and with the main query. Therefore, when using data-modifying
+ statements in <code class="literal">WITH</code>, the order in which the specified updates
+ actually happen is unpredictable. All the statements are executed with
+ the same <em class="firstterm">snapshot</em> (see <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>), so they
+ cannot <span class="quote">“<span class="quote">see</span>”</span> one another's effects on the target tables. This
+ alleviates the effects of the unpredictability of the actual order of row
+ updates, and means that <code class="literal">RETURNING</code> data is the only way to
+ communicate changes between different <code class="literal">WITH</code> sub-statements and
+ the main query. An example of this is that in
+
+</p><pre class="programlisting">
+WITH t AS (
+ UPDATE products SET price = price * 1.05
+ RETURNING *
+)
+SELECT * FROM products;
+</pre><p>
+
+ the outer <code class="command">SELECT</code> would return the original prices before the
+ action of the <code class="command">UPDATE</code>, while in
+
+</p><pre class="programlisting">
+WITH t AS (
+ UPDATE products SET price = price * 1.05
+ RETURNING *
+)
+SELECT * FROM t;
+</pre><p>
+
+ the outer <code class="command">SELECT</code> would return the updated data.
+ </p><p>
+ Trying to update the same row twice in a single statement is not
+ supported. Only one of the modifications takes place, but it is not easy
+ (and sometimes not possible) to reliably predict which one. This also
+ applies to deleting a row that was already updated in the same statement:
+ only the update is performed. Therefore you should generally avoid trying
+ to modify a single row twice in a single statement. In particular avoid
+ writing <code class="literal">WITH</code> sub-statements that could affect the same rows
+ changed by the main statement or a sibling sub-statement. The effects
+ of such a statement will not be predictable.
+ </p><p>
+ At present, any table used as the target of a data-modifying statement in
+ <code class="literal">WITH</code> must not have a conditional rule, nor an <code class="literal">ALSO</code>
+ rule, nor an <code class="literal">INSTEAD</code> rule that expands to multiple statements.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="queries-values.html" title="7.7. VALUES Lists">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="queries.html" title="Chapter 7. Queries">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype.html" title="Chapter 8. Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.7. <code class="literal">VALUES</code> Lists </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Data Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/queries.html b/doc/src/sgml/html/queries.html
new file mode 100644
index 0000000..efc5136
--- /dev/null
+++ b/doc/src/sgml/html/queries.html
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7. Queries</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="dml-returning.html" title="6.4. Returning Data from Modified Rows" /><link rel="next" href="queries-overview.html" title="7.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 7. Queries</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="dml-returning.html" title="6.4. Returning Data from Modified Rows">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="queries-overview.html" title="7.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="QUERIES"><div class="titlepage"><div><div><h2 class="title">Chapter 7. Queries</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="queries-overview.html">7.1. Overview</a></span></dt><dt><span class="sect1"><a href="queries-table-expressions.html">7.2. Table Expressions</a></span></dt><dd><dl><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-FROM">7.2.1. The <code class="literal">FROM</code> Clause</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-WHERE">7.2.2. The <code class="literal">WHERE</code> Clause</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-GROUP">7.2.3. The <code class="literal">GROUP BY</code> and <code class="literal">HAVING</code> Clauses</a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-GROUPING-SETS">7.2.4. <code class="literal">GROUPING SETS</code>, <code class="literal">CUBE</code>, and <code class="literal">ROLLUP</code></a></span></dt><dt><span class="sect2"><a href="queries-table-expressions.html#QUERIES-WINDOW">7.2.5. Window Function Processing</a></span></dt></dl></dd><dt><span class="sect1"><a href="queries-select-lists.html">7.3. Select Lists</a></span></dt><dd><dl><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-SELECT-LIST-ITEMS">7.3.1. Select-List Items</a></span></dt><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-COLUMN-LABELS">7.3.2. Column Labels</a></span></dt><dt><span class="sect2"><a href="queries-select-lists.html#QUERIES-DISTINCT">7.3.3. <code class="literal">DISTINCT</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="queries-union.html">7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>)</a></span></dt><dt><span class="sect1"><a href="queries-order.html">7.5. Sorting Rows (<code class="literal">ORDER BY</code>)</a></span></dt><dt><span class="sect1"><a href="queries-limit.html">7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></a></span></dt><dt><span class="sect1"><a href="queries-values.html">7.7. <code class="literal">VALUES</code> Lists</a></span></dt><dt><span class="sect1"><a href="queries-with.html">7.8. <code class="literal">WITH</code> Queries (Common Table Expressions)</a></span></dt><dd><dl><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-SELECT">7.8.1. <code class="command">SELECT</code> in <code class="literal">WITH</code></a></span></dt><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-RECURSIVE">7.8.2. Recursive Queries</a></span></dt><dt><span class="sect2"><a href="queries-with.html#id-1.5.6.12.7">7.8.3. Common Table Expression Materialization</a></span></dt><dt><span class="sect2"><a href="queries-with.html#QUERIES-WITH-MODIFYING">7.8.4. Data-Modifying Statements in <code class="literal">WITH</code></a></span></dt></dl></dd></dl></div><a id="id-1.5.6.2" class="indexterm"></a><a id="id-1.5.6.3" class="indexterm"></a><p>
+ The previous chapters explained how to create tables, how to fill
+ them with data, and how to manipulate that data. Now we finally
+ discuss how to retrieve the data from the database.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dml-returning.html" title="6.4. Returning Data from Modified Rows">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="queries-overview.html" title="7.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.4. Returning Data from Modified Rows </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 7.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/query-path.html b/doc/src/sgml/html/query-path.html
new file mode 100644
index 0000000..e8efce7
--- /dev/null
+++ b/doc/src/sgml/html/query-path.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.1. The Path of a Query</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals" /><link rel="next" href="connect-estab.html" title="52.2. How Connections Are Established" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.1. The Path of a Query</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="connect-estab.html" title="52.2. How Connections Are Established">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERY-PATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.1. The Path of a Query</h2></div></div></div><p>
+ Here we give a short overview of the stages a query has to pass
+ to obtain a result.
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ A connection from an application program to the <span class="productname">PostgreSQL</span>
+ server has to be established. The application program transmits a
+ query to the server and waits to receive the results sent back by the
+ server.
+ </p></li><li class="step"><p>
+ The <em class="firstterm">parser stage</em> checks the query
+ transmitted by the application
+ program for correct syntax and creates
+ a <em class="firstterm">query tree</em>.
+ </p></li><li class="step"><p>
+ The <em class="firstterm">rewrite system</em> takes
+ the query tree created by the parser stage and looks for
+ any <em class="firstterm">rules</em> (stored in the
+ <em class="firstterm">system catalogs</em>) to apply to
+ the query tree. It performs the
+ transformations given in the <em class="firstterm">rule bodies</em>.
+ </p><p>
+ One application of the rewrite system is in the realization of
+ <em class="firstterm">views</em>.
+ Whenever a query against a view
+ (i.e., a <em class="firstterm">virtual table</em>) is made,
+ the rewrite system rewrites the user's query to
+ a query that accesses the <em class="firstterm">base tables</em> given in
+ the <em class="firstterm">view definition</em> instead.
+ </p></li><li class="step"><p>
+ The <em class="firstterm">planner/optimizer</em> takes
+ the (rewritten) query tree and creates a
+ <em class="firstterm">query plan</em> that will be the input to the
+ <em class="firstterm">executor</em>.
+ </p><p>
+ It does so by first creating all possible <em class="firstterm">paths</em>
+ leading to the same result. For example if there is an index on a
+ relation to be scanned, there are two paths for the
+ scan. One possibility is a simple sequential scan and the other
+ possibility is to use the index. Next the cost for the execution of
+ each path is estimated and the cheapest path is chosen. The cheapest
+ path is expanded into a complete plan that the executor can use.
+ </p></li><li class="step"><p>
+ The executor recursively steps through
+ the <em class="firstterm">plan tree</em> and
+ retrieves rows in the way represented by the plan.
+ The executor makes use of the
+ <em class="firstterm">storage system</em> while scanning
+ relations, performs <em class="firstterm">sorts</em> and <em class="firstterm">joins</em>,
+ evaluates <em class="firstterm">qualifications</em> and finally hands back the rows derived.
+ </p></li></ol></div><p>
+ In the following sections we will cover each of the above listed items
+ in more detail to give a better understanding of <span class="productname">PostgreSQL</span>'s internal
+ control and data structures.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="connect-estab.html" title="52.2. How Connections Are Established">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 52. Overview of PostgreSQL Internals </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.2. How Connections Are Established</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/querytree.html b/doc/src/sgml/html/querytree.html
new file mode 100644
index 0000000..4f51320
--- /dev/null
+++ b/doc/src/sgml/html/querytree.html
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.1. The Query Tree</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules.html" title="Chapter 41. The Rule System" /><link rel="next" href="rules-views.html" title="41.2. Views and the Rule System" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.1. The Query Tree</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules.html" title="Chapter 41. The Rule System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-views.html" title="41.2. Views and the Rule System">Next</a></td></tr></table><hr /></div><div class="sect1" id="QUERYTREE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.1. The Query Tree</h2></div></div></div><a id="id-1.8.6.6.2" class="indexterm"></a><p>
+ To understand how the rule system works it is necessary to know
+ when it is invoked and what its input and results are.
+</p><p>
+ The rule system is located between the parser and the planner.
+ It takes the output of the parser, one query tree, and the user-defined
+ rewrite rules, which are also
+ query trees with some extra information, and creates zero or more
+ query trees as result. So its input and output are always things
+ the parser itself could have produced and thus, anything it sees
+ is basically representable as an <acronym class="acronym">SQL</acronym> statement.
+</p><p>
+ Now what is a query tree? It is an internal representation of an
+ <acronym class="acronym">SQL</acronym> statement where the single parts that it is
+ built from are stored separately. These query trees can be shown
+ in the server log if you set the configuration parameters
+ <code class="varname">debug_print_parse</code>,
+ <code class="varname">debug_print_rewritten</code>, or
+ <code class="varname">debug_print_plan</code>. The rule actions are also
+ stored as query trees, in the system catalog
+ <code class="structname">pg_rewrite</code>. They are not formatted like
+ the log output, but they contain exactly the same information.
+</p><p>
+ Reading a raw query tree requires some experience. But since
+ <acronym class="acronym">SQL</acronym> representations of query trees are
+ sufficient to understand the rule system, this chapter will not
+ teach how to read them.
+</p><p>
+ When reading the <acronym class="acronym">SQL</acronym> representations of the
+ query trees in this chapter it is necessary to be able to identify
+ the parts the statement is broken into when it is in the query tree
+ structure. The parts of a query tree are
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ the command type
+ </span></dt><dd><p>
+ This is a simple value telling which command
+ (<code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>) produced
+ the query tree.
+ </p></dd><dt><span class="term">
+ the range table
+ <a id="id-1.8.6.6.7.2.2.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ The range table is a list of relations that are used in the query.
+ In a <code class="command">SELECT</code> statement these are the relations given after
+ the <code class="literal">FROM</code> key word.
+ </p><p>
+ Every range table entry identifies a table or view and tells
+ by which name it is called in the other parts of the query.
+ In the query tree, the range table entries are referenced by
+ number rather than by name, so here it doesn't matter if there
+ are duplicate names as it would in an <acronym class="acronym">SQL</acronym>
+ statement. This can happen after the range tables of rules
+ have been merged in. The examples in this chapter will not have
+ this situation.
+ </p></dd><dt><span class="term">
+ the result relation
+ </span></dt><dd><p>
+ This is an index into the range table that identifies the
+ relation where the results of the query go.
+ </p><p>
+ <code class="command">SELECT</code> queries don't have a result
+ relation. (The special case of <code class="command">SELECT INTO</code> is
+ mostly identical to <code class="command">CREATE TABLE</code> followed by
+ <code class="literal">INSERT ... SELECT</code>, and is not discussed
+ separately here.)
+ </p><p>
+ For <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> commands, the result relation is the table
+ (or view!) where the changes are to take effect.
+ </p></dd><dt><span class="term">
+ the target list
+ <a id="id-1.8.6.6.7.2.4.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ The target list is a list of expressions that define the
+ result of the query. In the case of a
+ <code class="command">SELECT</code>, these expressions are the ones that
+ build the final output of the query. They correspond to the
+ expressions between the key words <code class="command">SELECT</code>
+ and <code class="command">FROM</code>. (<code class="literal">*</code> is just an
+ abbreviation for all the column names of a relation. It is
+ expanded by the parser into the individual columns, so the
+ rule system never sees it.)
+ </p><p>
+ <code class="command">DELETE</code> commands don't need a normal target list
+ because they don't produce any result. Instead, the planner
+ adds a special <acronym class="acronym">CTID</acronym> entry to the empty target list,
+ to allow the executor to find the row to be deleted.
+ (<acronym class="acronym">CTID</acronym> is added when the result relation is an ordinary
+ table. If it is a view, a whole-row variable is added instead, by
+ the rule system, as described in <a class="xref" href="rules-views.html#RULES-VIEWS-UPDATE" title="41.2.4. Updating a View">Section 41.2.4</a>.)
+ </p><p>
+ For <code class="command">INSERT</code> commands, the target list describes
+ the new rows that should go into the result relation. It consists of the
+ expressions in the <code class="literal">VALUES</code> clause or the ones from the
+ <code class="command">SELECT</code> clause in <code class="literal">INSERT
+ ... SELECT</code>. The first step of the rewrite process adds
+ target list entries for any columns that were not assigned to by
+ the original command but have defaults. Any remaining columns (with
+ neither a given value nor a default) will be filled in by the
+ planner with a constant null expression.
+ </p><p>
+ For <code class="command">UPDATE</code> commands, the target list
+ describes the new rows that should replace the old ones. In the
+ rule system, it contains just the expressions from the <code class="literal">SET
+ column = expression</code> part of the command. The planner will
+ handle missing columns by inserting expressions that copy the values
+ from the old row into the new one. Just as for <code class="command">DELETE</code>,
+ a <acronym class="acronym">CTID</acronym> or whole-row variable is added so that
+ the executor can identify the old row to be updated.
+ </p><p>
+ Every entry in the target list contains an expression that can
+ be a constant value, a variable pointing to a column of one
+ of the relations in the range table, a parameter, or an expression
+ tree made of function calls, constants, variables, operators, etc.
+ </p></dd><dt><span class="term">
+ the qualification
+ </span></dt><dd><p>
+ The query's qualification is an expression much like one of
+ those contained in the target list entries. The result value of
+ this expression is a Boolean that tells whether the operation
+ (<code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, or <code class="command">SELECT</code>) for the
+ final result row should be executed or not. It corresponds to the <code class="literal">WHERE</code> clause
+ of an <acronym class="acronym">SQL</acronym> statement.
+ </p></dd><dt><span class="term">
+ the join tree
+ </span></dt><dd><p>
+ The query's join tree shows the structure of the <code class="literal">FROM</code> clause.
+ For a simple query like <code class="literal">SELECT ... FROM a, b, c</code>, the join tree is just
+ a list of the <code class="literal">FROM</code> items, because we are allowed to join them in
+ any order. But when <code class="literal">JOIN</code> expressions, particularly outer joins,
+ are used, we have to join in the order shown by the joins.
+ In that case, the join tree shows the structure of the <code class="literal">JOIN</code> expressions. The
+ restrictions associated with particular <code class="literal">JOIN</code> clauses (from <code class="literal">ON</code> or
+ <code class="literal">USING</code> expressions) are stored as qualification expressions attached
+ to those join-tree nodes. It turns out to be convenient to store
+ the top-level <code class="literal">WHERE</code> expression as a qualification attached to the
+ top-level join-tree item, too. So really the join tree represents
+ both the <code class="literal">FROM</code> and <code class="literal">WHERE</code> clauses of a <code class="command">SELECT</code>.
+ </p></dd><dt><span class="term">
+ the others
+ </span></dt><dd><p>
+ The other parts of the query tree like the <code class="literal">ORDER BY</code>
+ clause aren't of interest here. The rule system
+ substitutes some entries there while applying rules, but that
+ doesn't have much to do with the fundamentals of the rule
+ system.
+ </p></dd></dl></div><p>
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules.html" title="Chapter 41. The Rule System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-views.html" title="41.2. Views and the Rule System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 41. The Rule System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.2. Views and the Rule System</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rangetypes.html b/doc/src/sgml/html/rangetypes.html
new file mode 100644
index 0000000..0ad4a55
--- /dev/null
+++ b/doc/src/sgml/html/rangetypes.html
@@ -0,0 +1,435 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.17. Range Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rowtypes.html" title="8.16. Composite Types" /><link rel="next" href="domains.html" title="8.18. Domain Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.17. Range Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rowtypes.html" title="8.16. Composite Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="domains.html" title="8.18. Domain Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="RANGETYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.17. Range Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-BUILTIN">8.17.1. Built-in Range and Multirange Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-EXAMPLES">8.17.2. Examples</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INCLUSIVITY">8.17.3. Inclusive and Exclusive Bounds</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INFINITE">8.17.4. Infinite (Unbounded) Ranges</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-IO">8.17.5. Range Input/Output</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-CONSTRUCT">8.17.6. Constructing Ranges and Multiranges</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-DISCRETE">8.17.7. Discrete Range Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-DEFINING">8.17.8. Defining New Range Types</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-INDEXING">8.17.9. Indexing</a></span></dt><dt><span class="sect2"><a href="rangetypes.html#RANGETYPES-CONSTRAINT">8.17.10. Constraints on Ranges</a></span></dt></dl></div><a id="id-1.5.7.25.2" class="indexterm"></a><a id="id-1.5.7.25.3" class="indexterm"></a><p>
+ Range types are data types representing a range of values of some
+ element type (called the range's <em class="firstterm">subtype</em>).
+ For instance, ranges
+ of <code class="type">timestamp</code> might be used to represent the ranges of
+ time that a meeting room is reserved. In this case the data type
+ is <code class="type">tsrange</code> (short for <span class="quote">“<span class="quote">timestamp range</span>”</span>),
+ and <code class="type">timestamp</code> is the subtype. The subtype must have
+ a total order so that it is well-defined whether element values are
+ within, before, or after a range of values.
+ </p><p>
+ Range types are useful because they represent many element values in a
+ single range value, and because concepts such as overlapping ranges can
+ be expressed clearly. The use of time and date ranges for scheduling
+ purposes is the clearest example; but price ranges, measurement
+ ranges from an instrument, and so forth can also be useful.
+ </p><p>
+ Every range type has a corresponding multirange type. A multirange is
+ an ordered list of non-contiguous, non-empty, non-null ranges. Most
+ range operators also work on multiranges, and they have a few functions
+ of their own.
+ </p><div class="sect2" id="RANGETYPES-BUILTIN"><div class="titlepage"><div><div><h3 class="title">8.17.1. Built-in Range and Multirange Types</h3></div></div></div><p>
+ PostgreSQL comes with the following built-in range types:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="type">int4range</code> — Range of <code class="type">integer</code>,
+ <code class="type">int4multirange</code> — corresponding Multirange
+ </p></li><li class="listitem"><p>
+ <code class="type">int8range</code> — Range of <code class="type">bigint</code>,
+ <code class="type">int8multirange</code> — corresponding Multirange
+ </p></li><li class="listitem"><p>
+ <code class="type">numrange</code> — Range of <code class="type">numeric</code>,
+ <code class="type">nummultirange</code> — corresponding Multirange
+ </p></li><li class="listitem"><p>
+ <code class="type">tsrange</code> — Range of <code class="type">timestamp without time zone</code>,
+ <code class="type">tsmultirange</code> — corresponding Multirange
+ </p></li><li class="listitem"><p>
+ <code class="type">tstzrange</code> — Range of <code class="type">timestamp with time zone</code>,
+ <code class="type">tstzmultirange</code> — corresponding Multirange
+ </p></li><li class="listitem"><p>
+ <code class="type">daterange</code> — Range of <code class="type">date</code>,
+ <code class="type">datemultirange</code> — corresponding Multirange
+ </p></li></ul></div><p>
+ In addition, you can define your own range types;
+ see <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> for more information.
+ </p></div><div class="sect2" id="RANGETYPES-EXAMPLES"><div class="titlepage"><div><div><h3 class="title">8.17.2. Examples</h3></div></div></div><p>
+</p><pre class="programlisting">
+CREATE TABLE reservation (room int, during tsrange);
+INSERT INTO reservation VALUES
+ (1108, '[2010-01-01 14:30, 2010-01-01 15:30)');
+
+-- Containment
+SELECT int4range(10, 20) @&gt; 3;
+
+-- Overlaps
+SELECT numrange(11.1, 22.2) &amp;&amp; numrange(20.0, 30.0);
+
+-- Extract the upper bound
+SELECT upper(int8range(15, 25));
+
+-- Compute the intersection
+SELECT int4range(10, 20) * int4range(15, 25);
+
+-- Is the range empty?
+SELECT isempty(numrange(1, 5));
+</pre><p>
+
+ See <a class="xref" href="functions-range.html#RANGE-OPERATORS-TABLE" title="Table 9.54. Range Operators">Table 9.54</a>
+ and <a class="xref" href="functions-range.html#RANGE-FUNCTIONS-TABLE" title="Table 9.56. Range Functions">Table 9.56</a> for complete lists of
+ operators and functions on range types.
+ </p></div><div class="sect2" id="RANGETYPES-INCLUSIVITY"><div class="titlepage"><div><div><h3 class="title">8.17.3. Inclusive and Exclusive Bounds</h3></div></div></div><p>
+ Every non-empty range has two bounds, the lower bound and the upper
+ bound. All points between these values are included in the range. An
+ inclusive bound means that the boundary point itself is included in
+ the range as well, while an exclusive bound means that the boundary
+ point is not included in the range.
+ </p><p>
+ In the text form of a range, an inclusive lower bound is represented by
+ <span class="quote">“<span class="quote"><code class="literal">[</code></span>”</span> while an exclusive lower bound is
+ represented by <span class="quote">“<span class="quote"><code class="literal">(</code></span>”</span>. Likewise, an inclusive upper bound is represented by
+ <span class="quote">“<span class="quote"><code class="literal">]</code></span>”</span>, while an exclusive upper bound is
+ represented by <span class="quote">“<span class="quote"><code class="literal">)</code></span>”</span>.
+ (See <a class="xref" href="rangetypes.html#RANGETYPES-IO" title="8.17.5. Range Input/Output">Section 8.17.5</a> for more details.)
+ </p><p>
+ The functions <code class="literal">lower_inc</code>
+ and <code class="literal">upper_inc</code> test the inclusivity of the lower
+ and upper bounds of a range value, respectively.
+ </p></div><div class="sect2" id="RANGETYPES-INFINITE"><div class="titlepage"><div><div><h3 class="title">8.17.4. Infinite (Unbounded) Ranges</h3></div></div></div><p>
+ The lower bound of a range can be omitted, meaning that all
+ values less than the upper bound are included in the range, e.g.,
+ <code class="literal">(,3]</code>. Likewise, if the upper bound of the range
+ is omitted, then all values greater than the lower bound are included
+ in the range. If both lower and upper bounds are omitted, all values
+ of the element type are considered to be in the range. Specifying a
+ missing bound as inclusive is automatically converted to exclusive,
+ e.g., <code class="literal">[,]</code> is converted to <code class="literal">(,)</code>.
+ You can think of these missing values as +/-infinity, but they are
+ special range type values and are considered to be beyond any range
+ element type's +/-infinity values.
+ </p><p>
+ Element types that have the notion of <span class="quote">“<span class="quote">infinity</span>”</span> can
+ use them as explicit bound values. For example, with timestamp
+ ranges, <code class="literal">[today,infinity)</code> excludes the special
+ <code class="type">timestamp</code> value <code class="literal">infinity</code>,
+ while <code class="literal">[today,infinity]</code> include it, as does
+ <code class="literal">[today,)</code> and <code class="literal">[today,]</code>.
+ </p><p>
+ The functions <code class="literal">lower_inf</code>
+ and <code class="literal">upper_inf</code> test for infinite lower
+ and upper bounds of a range, respectively.
+ </p></div><div class="sect2" id="RANGETYPES-IO"><div class="titlepage"><div><div><h3 class="title">8.17.5. Range Input/Output</h3></div></div></div><p>
+ The input for a range value must follow one of the following patterns:
+</p><pre class="synopsis">
+(<em class="replaceable"><code>lower-bound</code></em>,<em class="replaceable"><code>upper-bound</code></em>)
+(<em class="replaceable"><code>lower-bound</code></em>,<em class="replaceable"><code>upper-bound</code></em>]
+[<em class="replaceable"><code>lower-bound</code></em>,<em class="replaceable"><code>upper-bound</code></em>)
+[<em class="replaceable"><code>lower-bound</code></em>,<em class="replaceable"><code>upper-bound</code></em>]
+empty
+</pre><p>
+ The parentheses or brackets indicate whether the lower and upper bounds
+ are exclusive or inclusive, as described previously.
+ Notice that the final pattern is <code class="literal">empty</code>, which
+ represents an empty range (a range that contains no points).
+ </p><p>
+ The <em class="replaceable"><code>lower-bound</code></em> may be either a string
+ that is valid input for the subtype, or empty to indicate no
+ lower bound. Likewise, <em class="replaceable"><code>upper-bound</code></em> may be
+ either a string that is valid input for the subtype, or empty to
+ indicate no upper bound.
+ </p><p>
+ Each bound value can be quoted using <code class="literal">"</code> (double quote)
+ characters. This is necessary if the bound value contains parentheses,
+ brackets, commas, double quotes, or backslashes, since these characters
+ would otherwise be taken as part of the range syntax. To put a double
+ quote or backslash in a quoted bound value, precede it with a
+ backslash. (Also, a pair of double quotes within a double-quoted bound
+ value is taken to represent a double quote character, analogously to the
+ rules for single quotes in SQL literal strings.) Alternatively, you can
+ avoid quoting and use backslash-escaping to protect all data characters
+ that would otherwise be taken as range syntax. Also, to write a bound
+ value that is an empty string, write <code class="literal">""</code>, since writing
+ nothing means an infinite bound.
+ </p><p>
+ Whitespace is allowed before and after the range value, but any whitespace
+ between the parentheses or brackets is taken as part of the lower or upper
+ bound value. (Depending on the element type, it might or might not be
+ significant.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ These rules are very similar to those for writing field values in
+ composite-type literals. See <a class="xref" href="rowtypes.html#ROWTYPES-IO-SYNTAX" title="8.16.6. Composite Type Input and Output Syntax">Section 8.16.6</a> for
+ additional commentary.
+ </p></div><p>
+ Examples:
+</p><pre class="programlisting">
+-- includes 3, does not include 7, and does include all points in between
+SELECT '[3,7)'::int4range;
+
+-- does not include either 3 or 7, but includes all points in between
+SELECT '(3,7)'::int4range;
+
+-- includes only the single point 4
+SELECT '[4,4]'::int4range;
+
+-- includes no points (and will be normalized to 'empty')
+SELECT '[4,4)'::int4range;
+</pre><p>
+ </p><p>
+ The input for a multirange is curly brackets (<code class="literal">{</code> and
+ <code class="literal">}</code>) containing zero or more valid ranges,
+ separated by commas. Whitespace is permitted around the brackets and
+ commas. This is intended to be reminiscent of array syntax, although
+ multiranges are much simpler: they have just one dimension and there is
+ no need to quote their contents. (The bounds of their ranges may be
+ quoted as above however.)
+ </p><p>
+ Examples:
+</p><pre class="programlisting">
+SELECT '{}'::int4multirange;
+SELECT '{[3,7)}'::int4multirange;
+SELECT '{[3,7), [8,9)}'::int4multirange;
+</pre><p>
+ </p></div><div class="sect2" id="RANGETYPES-CONSTRUCT"><div class="titlepage"><div><div><h3 class="title">8.17.6. Constructing Ranges and Multiranges</h3></div></div></div><p>
+ Each range type has a constructor function with the same name as the range
+ type. Using the constructor function is frequently more convenient than
+ writing a range literal constant, since it avoids the need for extra
+ quoting of the bound values. The constructor function
+ accepts two or three arguments. The two-argument form constructs a range
+ in standard form (lower bound inclusive, upper bound exclusive), while
+ the three-argument form constructs a range with bounds of the form
+ specified by the third argument.
+ The third argument must be one of the strings
+ <span class="quote">“<span class="quote"><code class="literal">()</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">(]</code></span>”</span>,
+ <span class="quote">“<span class="quote"><code class="literal">[)</code></span>”</span>, or
+ <span class="quote">“<span class="quote"><code class="literal">[]</code></span>”</span>.
+ For example:
+
+</p><pre class="programlisting">
+-- The full form is: lower bound, upper bound, and text argument indicating
+-- inclusivity/exclusivity of bounds.
+SELECT numrange(1.0, 14.0, '(]');
+
+-- If the third argument is omitted, '[)' is assumed.
+SELECT numrange(1.0, 14.0);
+
+-- Although '(]' is specified here, on display the value will be converted to
+-- canonical form, since int8range is a discrete range type (see below).
+SELECT int8range(1, 14, '(]');
+
+-- Using NULL for either bound causes the range to be unbounded on that side.
+SELECT numrange(NULL, 2.2);
+</pre><p>
+ </p><p>
+ Each range type also has a multirange constructor with the same name as the
+ multirange type. The constructor function takes zero or more arguments
+ which are all ranges of the appropriate type.
+ For example:
+
+</p><pre class="programlisting">
+SELECT nummultirange();
+SELECT nummultirange(numrange(1.0, 14.0));
+SELECT nummultirange(numrange(1.0, 14.0), numrange(20.0, 25.0));
+</pre><p>
+ </p></div><div class="sect2" id="RANGETYPES-DISCRETE"><div class="titlepage"><div><div><h3 class="title">8.17.7. Discrete Range Types</h3></div></div></div><p>
+ A discrete range is one whose element type has a well-defined
+ <span class="quote">“<span class="quote">step</span>”</span>, such as <code class="type">integer</code> or <code class="type">date</code>.
+ In these types two elements can be said to be adjacent, when there are
+ no valid values between them. This contrasts with continuous ranges,
+ where it's always (or almost always) possible to identify other element
+ values between two given values. For example, a range over the
+ <code class="type">numeric</code> type is continuous, as is a range over <code class="type">timestamp</code>.
+ (Even though <code class="type">timestamp</code> has limited precision, and so could
+ theoretically be treated as discrete, it's better to consider it continuous
+ since the step size is normally not of interest.)
+ </p><p>
+ Another way to think about a discrete range type is that there is a clear
+ idea of a <span class="quote">“<span class="quote">next</span>”</span> or <span class="quote">“<span class="quote">previous</span>”</span> value for each element value.
+ Knowing that, it is possible to convert between inclusive and exclusive
+ representations of a range's bounds, by choosing the next or previous
+ element value instead of the one originally given.
+ For example, in an integer range type <code class="literal">[4,8]</code> and
+ <code class="literal">(3,9)</code> denote the same set of values; but this would not be so
+ for a range over numeric.
+ </p><p>
+ A discrete range type should have a <em class="firstterm">canonicalization</em>
+ function that is aware of the desired step size for the element type.
+ The canonicalization function is charged with converting equivalent values
+ of the range type to have identical representations, in particular
+ consistently inclusive or exclusive bounds.
+ If a canonicalization function is not specified, then ranges with different
+ formatting will always be treated as unequal, even though they might
+ represent the same set of values in reality.
+ </p><p>
+ The built-in range types <code class="type">int4range</code>, <code class="type">int8range</code>,
+ and <code class="type">daterange</code> all use a canonical form that includes
+ the lower bound and excludes the upper bound; that is,
+ <code class="literal">[)</code>. User-defined range types can use other conventions,
+ however.
+ </p></div><div class="sect2" id="RANGETYPES-DEFINING"><div class="titlepage"><div><div><h3 class="title">8.17.8. Defining New Range Types</h3></div></div></div><p>
+ Users can define their own range types. The most common reason to do
+ this is to use ranges over subtypes not provided among the built-in
+ range types.
+ For example, to define a new range type of subtype <code class="type">float8</code>:
+
+</p><pre class="programlisting">
+CREATE TYPE floatrange AS RANGE (
+ subtype = float8,
+ subtype_diff = float8mi
+);
+
+SELECT '[1.234, 5.678]'::floatrange;
+</pre><p>
+
+ Because <code class="type">float8</code> has no meaningful
+ <span class="quote">“<span class="quote">step</span>”</span>, we do not define a canonicalization
+ function in this example.
+ </p><p>
+ When you define your own range you automatically get a corresponding
+ multirange type.
+ </p><p>
+ Defining your own range type also allows you to specify a different
+ subtype B-tree operator class or collation to use, so as to change the sort
+ ordering that determines which values fall into a given range.
+ </p><p>
+ If the subtype is considered to have discrete rather than continuous
+ values, the <code class="command">CREATE TYPE</code> command should specify a
+ <code class="literal">canonical</code> function.
+ The canonicalization function takes an input range value, and must return
+ an equivalent range value that may have different bounds and formatting.
+ The canonical output for two ranges that represent the same set of values,
+ for example the integer ranges <code class="literal">[1, 7]</code> and <code class="literal">[1,
+ 8)</code>, must be identical. It doesn't matter which representation
+ you choose to be the canonical one, so long as two equivalent values with
+ different formattings are always mapped to the same value with the same
+ formatting. In addition to adjusting the inclusive/exclusive bounds
+ format, a canonicalization function might round off boundary values, in
+ case the desired step size is larger than what the subtype is capable of
+ storing. For instance, a range type over <code class="type">timestamp</code> could be
+ defined to have a step size of an hour, in which case the canonicalization
+ function would need to round off bounds that weren't a multiple of an hour,
+ or perhaps throw an error instead.
+ </p><p>
+ In addition, any range type that is meant to be used with GiST or SP-GiST
+ indexes should define a subtype difference, or <code class="literal">subtype_diff</code>,
+ function. (The index will still work without <code class="literal">subtype_diff</code>,
+ but it is likely to be considerably less efficient than if a difference
+ function is provided.) The subtype difference function takes two input
+ values of the subtype, and returns their difference
+ (i.e., <em class="replaceable"><code>X</code></em> minus <em class="replaceable"><code>Y</code></em>) represented as
+ a <code class="type">float8</code> value. In our example above, the
+ function <code class="function">float8mi</code> that underlies the regular <code class="type">float8</code>
+ minus operator can be used; but for any other subtype, some type
+ conversion would be necessary. Some creative thought about how to
+ represent differences as numbers might be needed, too. To the greatest
+ extent possible, the <code class="literal">subtype_diff</code> function should agree with
+ the sort ordering implied by the selected operator class and collation;
+ that is, its result should be positive whenever its first argument is
+ greater than its second according to the sort ordering.
+ </p><p>
+ A less-oversimplified example of a <code class="literal">subtype_diff</code> function is:
+ </p><pre class="programlisting">
+CREATE FUNCTION time_subtype_diff(x time, y time) RETURNS float8 AS
+'SELECT EXTRACT(EPOCH FROM (x - y))' LANGUAGE sql STRICT IMMUTABLE;
+
+CREATE TYPE timerange AS RANGE (
+ subtype = time,
+ subtype_diff = time_subtype_diff
+);
+
+SELECT '[11:10, 23:00]'::timerange;
+</pre><p>
+ See <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> for more information about creating
+ range types.
+ </p></div><div class="sect2" id="RANGETYPES-INDEXING"><div class="titlepage"><div><div><h3 class="title">8.17.9. Indexing</h3></div></div></div><a id="id-1.5.7.25.15.2" class="indexterm"></a><p>
+ GiST and SP-GiST indexes can be created for table columns of range types.
+ GiST indexes can be also created for table columns of multirange types.
+ For instance, to create a GiST index:
+</p><pre class="programlisting">
+CREATE INDEX reservation_idx ON reservation USING GIST (during);
+</pre><p>
+ A GiST or SP-GiST index on ranges can accelerate queries involving these
+ range operators:
+ <code class="literal">=</code>,
+ <code class="literal">&amp;&amp;</code>,
+ <code class="literal">&lt;@</code>,
+ <code class="literal">@&gt;</code>,
+ <code class="literal">&lt;&lt;</code>,
+ <code class="literal">&gt;&gt;</code>,
+ <code class="literal">-|-</code>,
+ <code class="literal">&amp;&lt;</code>, and
+ <code class="literal">&amp;&gt;</code>.
+ A GiST index on multiranges can accelerate queries involving the same
+ set of multirange operators.
+ A GiST index on ranges and GiST index on multiranges can also accelerate
+ queries involving these cross-type range to multirange and multirange to
+ range operators correspondingly:
+ <code class="literal">&amp;&amp;</code>,
+ <code class="literal">&lt;@</code>,
+ <code class="literal">@&gt;</code>,
+ <code class="literal">&lt;&lt;</code>,
+ <code class="literal">&gt;&gt;</code>,
+ <code class="literal">-|-</code>,
+ <code class="literal">&amp;&lt;</code>, and
+ <code class="literal">&amp;&gt;</code>.
+ See <a class="xref" href="functions-range.html#RANGE-OPERATORS-TABLE" title="Table 9.54. Range Operators">Table 9.54</a> for more information.
+ </p><p>
+ In addition, B-tree and hash indexes can be created for table columns of
+ range types. For these index types, basically the only useful range
+ operation is equality. There is a B-tree sort ordering defined for range
+ values, with corresponding <code class="literal">&lt;</code> and <code class="literal">&gt;</code> operators,
+ but the ordering is rather arbitrary and not usually useful in the real
+ world. Range types' B-tree and hash support is primarily meant to
+ allow sorting and hashing internally in queries, rather than creation of
+ actual indexes.
+ </p></div><div class="sect2" id="RANGETYPES-CONSTRAINT"><div class="titlepage"><div><div><h3 class="title">8.17.10. Constraints on Ranges</h3></div></div></div><a id="id-1.5.7.25.16.2" class="indexterm"></a><p>
+ While <code class="literal">UNIQUE</code> is a natural constraint for scalar
+ values, it is usually unsuitable for range types. Instead, an
+ exclusion constraint is often more appropriate
+ (see <a class="link" href="sql-createtable.html#SQL-CREATETABLE-EXCLUDE">CREATE TABLE
+ ... CONSTRAINT ... EXCLUDE</a>). Exclusion constraints allow the
+ specification of constraints such as <span class="quote">“<span class="quote">non-overlapping</span>”</span> on a
+ range type. For example:
+
+</p><pre class="programlisting">
+CREATE TABLE reservation (
+ during tsrange,
+ EXCLUDE USING GIST (during WITH &amp;&amp;)
+);
+</pre><p>
+
+ That constraint will prevent any overlapping values from existing
+ in the table at the same time:
+
+</p><pre class="programlisting">
+INSERT INTO reservation VALUES
+ ('[2010-01-01 11:30, 2010-01-01 15:00)');
+INSERT 0 1
+
+INSERT INTO reservation VALUES
+ ('[2010-01-01 14:45, 2010-01-01 15:45)');
+ERROR: conflicting key value violates exclusion constraint "reservation_during_excl"
+DETAIL: Key (during)=(["2010-01-01 14:45:00","2010-01-01 15:45:00")) conflicts
+with existing key (during)=(["2010-01-01 11:30:00","2010-01-01 15:00:00")).
+</pre><p>
+ </p><p>
+ You can use the <a class="link" href="btree-gist.html" title="F.9. btree_gist"><code class="literal">btree_gist</code></a>
+ extension to define exclusion constraints on plain scalar data types, which
+ can then be combined with range exclusions for maximum flexibility. For
+ example, after <code class="literal">btree_gist</code> is installed, the following
+ constraint will reject overlapping ranges only if the meeting room numbers
+ are equal:
+
+</p><pre class="programlisting">
+CREATE EXTENSION btree_gist;
+CREATE TABLE room_reservation (
+ room text,
+ during tsrange,
+ EXCLUDE USING GIST (room WITH =, during WITH &amp;&amp;)
+);
+
+INSERT INTO room_reservation VALUES
+ ('123A', '[2010-01-01 14:00, 2010-01-01 15:00)');
+INSERT 0 1
+
+INSERT INTO room_reservation VALUES
+ ('123A', '[2010-01-01 14:30, 2010-01-01 15:30)');
+ERROR: conflicting key value violates exclusion constraint "room_reservation_room_during_excl"
+DETAIL: Key (room, during)=(123A, ["2010-01-01 14:30:00","2010-01-01 15:30:00")) conflicts
+with existing key (room, during)=(123A, ["2010-01-01 14:00:00","2010-01-01 15:00:00")).
+
+INSERT INTO room_reservation VALUES
+ ('123B', '[2010-01-01 14:30, 2010-01-01 15:30)');
+INSERT 0 1
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rowtypes.html" title="8.16. Composite Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="domains.html" title="8.18. Domain Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.16. Composite Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.18. Domain Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/recovery-config.html b/doc/src/sgml/html/recovery-config.html
new file mode 100644
index 0000000..4f3c4d6
--- /dev/null
+++ b/doc/src/sgml/html/recovery-config.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>O.1. recovery.conf file merged into postgresql.conf</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features" /><link rel="next" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><th width="60%" align="center">Appendix O. Obsolete or Renamed Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="RECOVERY-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">O.1. <code class="filename">recovery.conf</code> file merged into <code class="filename">postgresql.conf</code></h2></div></div></div><a id="id-1.11.16.3.2" class="indexterm"></a><p>
+ PostgreSQL 11 and below used a configuration file named
+ <code class="filename">recovery.conf</code>
+ <a id="id-1.11.16.3.3.2" class="indexterm"></a>
+ to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See
+ <a class="link" href="release-prior.html" title="E.7. Prior Releases">the release notes for PostgreSQL 12</a> for details
+ on this change.
+ </p><p>
+ On PostgreSQL 12 and above,
+ <a class="link" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">archive recovery, streaming replication, and PITR</a>
+ are configured using
+ <a class="link" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY" title="20.6.3. Standby Servers">normal server configuration parameters</a>.
+ These are set in <code class="filename">postgresql.conf</code> or via
+ <a class="link" href="sql-altersystem.html" title="ALTER SYSTEM">ALTER SYSTEM</a>
+ like any other parameter.
+ </p><p>
+ The server will not start if a <code class="filename">recovery.conf</code> exists.
+ </p><p>
+ The
+ <code class="literal">trigger_file</code>
+ <a id="id-1.11.16.3.6.2" class="indexterm"></a>
+ setting has been renamed to
+ <a class="xref" href="runtime-config-replication.html#GUC-PROMOTE-TRIGGER-FILE">promote_trigger_file</a>.
+ </p><p>
+ The
+ <code class="literal">standby_mode</code>
+ <a id="id-1.11.16.3.7.2" class="indexterm"></a>
+ setting has been removed. A <code class="filename">standby.signal</code> file in the data directory
+ is used instead. See <a class="xref" href="warm-standby.html#STANDBY-SERVER-OPERATION" title="27.2.2. Standby Server Operation">Standby Server Operation</a> for details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix-obsolete.html" title="Appendix O. Obsolete or Renamed Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="default-roles.html" title="O.2. Default Roles Renamed to Predefined Roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix O. Obsolete or Renamed Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> O.2. Default Roles Renamed to Predefined Roles</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/reference-client.html b/doc/src/sgml/html/reference-client.html
new file mode 100644
index 0000000..56bd649
--- /dev/null
+++ b/doc/src/sgml/html/reference-client.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PostgreSQL Client Applications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-values.html" title="VALUES" /><link rel="next" href="app-clusterdb.html" title="clusterdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PostgreSQL Client Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-values.html" title="VALUES">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><th width="60%" align="center">Part VI. Reference</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-clusterdb.html" title="clusterdb">Next</a></td></tr></table><hr /></div><div class="reference" id="REFERENCE-CLIENT"><div class="titlepage"><div><div><h1 class="title">PostgreSQL Client Applications</h1></div></div><hr /></div><div class="partintro" id="id-1.9.4.2"><div></div><p>
+ This part contains reference information for
+ <span class="productname">PostgreSQL</span> client applications and
+ utilities. Not all of these commands are of general utility; some
+ might require special privileges. The common feature of these
+ applications is that they can be run on any host, independent of
+ where the database server resides.
+ </p><p>
+ When specified on the command line, user and database names have
+ their case preserved — the presence of spaces or special
+ characters might require quoting. Table names and other identifiers
+ do not have their case preserved, except where documented, and
+ might require quoting.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="refentrytitle"><a href="app-clusterdb.html"><span class="application">clusterdb</span></a></span><span class="refpurpose"> — cluster a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-createdb.html"><span class="application">createdb</span></a></span><span class="refpurpose"> — create a new <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-createuser.html"><span class="application">createuser</span></a></span><span class="refpurpose"> — define a new <span class="productname">PostgreSQL</span> user account</span></dt><dt><span class="refentrytitle"><a href="app-dropdb.html"><span class="application">dropdb</span></a></span><span class="refpurpose"> — remove a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-dropuser.html"><span class="application">dropuser</span></a></span><span class="refpurpose"> — remove a <span class="productname">PostgreSQL</span> user account</span></dt><dt><span class="refentrytitle"><a href="app-ecpg.html"><span class="application">ecpg</span></a></span><span class="refpurpose"> — embedded SQL C preprocessor</span></dt><dt><span class="refentrytitle"><a href="app-pgamcheck.html"><span class="application">pg_amcheck</span></a></span><span class="refpurpose"> — checks for corruption in one or more
+ <span class="productname">PostgreSQL</span> databases</span></dt><dt><span class="refentrytitle"><a href="app-pgbasebackup.html"><span class="application">pg_basebackup</span></a></span><span class="refpurpose"> — take a base backup of a <span class="productname">PostgreSQL</span> cluster</span></dt><dt><span class="refentrytitle"><a href="pgbench.html"><span class="application">pgbench</span></a></span><span class="refpurpose"> — run a benchmark test on <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="app-pgconfig.html"><span class="application">pg_config</span></a></span><span class="refpurpose"> — retrieve information about the installed version of <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="app-pgdump.html"><span class="application">pg_dump</span></a></span><span class="refpurpose"> —
+ extract a <span class="productname">PostgreSQL</span> database into a script file or other archive file
+ </span></dt><dt><span class="refentrytitle"><a href="app-pg-dumpall.html"><span class="application">pg_dumpall</span></a></span><span class="refpurpose"> — extract a <span class="productname">PostgreSQL</span> database cluster into a script file</span></dt><dt><span class="refentrytitle"><a href="app-pg-isready.html"><span class="application">pg_isready</span></a></span><span class="refpurpose"> — check the connection status of a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgreceivewal.html"><span class="application">pg_receivewal</span></a></span><span class="refpurpose"> — stream write-ahead logs from a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgrecvlogical.html"><span class="application">pg_recvlogical</span></a></span><span class="refpurpose"> — control <span class="productname">PostgreSQL</span> logical decoding streams</span></dt><dt><span class="refentrytitle"><a href="app-pgrestore.html"><span class="application">pg_restore</span></a></span><span class="refpurpose"> —
+ restore a <span class="productname">PostgreSQL</span> database from an
+ archive file created by <span class="application">pg_dump</span>
+ </span></dt><dt><span class="refentrytitle"><a href="app-pgverifybackup.html"><span class="application">pg_verifybackup</span></a></span><span class="refpurpose"> — verify the integrity of a base backup of a
+ <span class="productname">PostgreSQL</span> cluster</span></dt><dt><span class="refentrytitle"><a href="app-psql.html"><span class="application">psql</span></a></span><span class="refpurpose"> —
+ <span class="productname">PostgreSQL</span> interactive terminal
+ </span></dt><dt><span class="refentrytitle"><a href="app-reindexdb.html"><span class="application">reindexdb</span></a></span><span class="refpurpose"> — reindex a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-vacuumdb.html"><span class="application">vacuumdb</span></a></span><span class="refpurpose"> — garbage-collect and analyze a <span class="productname">PostgreSQL</span> database</span></dt></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-values.html" title="VALUES">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-clusterdb.html" title="clusterdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top">VALUES </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">clusterdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/reference-server.html b/doc/src/sgml/html/reference-server.html
new file mode 100644
index 0000000..8f556e3
--- /dev/null
+++ b/doc/src/sgml/html/reference-server.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PostgreSQL Server Applications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-vacuumdb.html" title="vacuumdb" /><link rel="next" href="app-initdb.html" title="initdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PostgreSQL Server Applications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-vacuumdb.html" title="vacuumdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><th width="60%" align="center">Part VI. Reference</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-initdb.html" title="initdb">Next</a></td></tr></table><hr /></div><div class="reference" id="REFERENCE-SERVER"><div class="titlepage"><div><div><h1 class="title">PostgreSQL Server Applications</h1></div></div><hr /></div><div class="partintro" id="id-1.9.5.2"><div></div><p>
+ This part contains reference information for
+ <span class="productname">PostgreSQL</span> server applications and
+ support utilities. These commands can only be run usefully on the
+ host where the database server resides. Other utility programs
+ are listed in <a class="xref" href="reference-client.html" title="PostgreSQL Client Applications">PostgreSQL Client Applications</a>.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="refentrytitle"><a href="app-initdb.html"><span class="application">initdb</span></a></span><span class="refpurpose"> — create a new <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="pgarchivecleanup.html"><span class="application">pg_archivecleanup</span></a></span><span class="refpurpose"> — clean up <span class="productname">PostgreSQL</span> WAL archive files</span></dt><dt><span class="refentrytitle"><a href="app-pgchecksums.html"><span class="application">pg_checksums</span></a></span><span class="refpurpose"> — enable, disable or check data checksums in a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pgcontroldata.html"><span class="application">pg_controldata</span></a></span><span class="refpurpose"> — display control information of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pg-ctl.html"><span class="application">pg_ctl</span></a></span><span class="refpurpose"> — initialize, start, stop, or control a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgresetwal.html"><span class="application">pg_resetwal</span></a></span><span class="refpurpose"> — reset the write-ahead log and other control information of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pgrewind.html"><span class="application">pg_rewind</span></a></span><span class="refpurpose"> — synchronize a <span class="productname">PostgreSQL</span> data directory with another data directory that was forked from it</span></dt><dt><span class="refentrytitle"><a href="pgtestfsync.html"><span class="application">pg_test_fsync</span></a></span><span class="refpurpose"> — determine fastest <code class="varname">wal_sync_method</code> for <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="pgtesttiming.html"><span class="application">pg_test_timing</span></a></span><span class="refpurpose"> — measure timing overhead</span></dt><dt><span class="refentrytitle"><a href="pgupgrade.html"><span class="application">pg_upgrade</span></a></span><span class="refpurpose"> — upgrade a <span class="productname">PostgreSQL</span> server instance</span></dt><dt><span class="refentrytitle"><a href="pgwaldump.html"><span class="application">pg_waldump</span></a></span><span class="refpurpose"> — display a human-readable rendering of the write-ahead log of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-postgres.html"><span class="application">postgres</span></a></span><span class="refpurpose"> — <span class="productname">PostgreSQL</span> database server</span></dt><dt><span class="refentrytitle"><a href="app-postmaster.html"><span class="application">postmaster</span></a></span><span class="refpurpose"> — <span class="productname">PostgreSQL</span> database server</span></dt></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-vacuumdb.html" title="vacuumdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-initdb.html" title="initdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">vacuumdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">initdb</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/reference.html b/doc/src/sgml/html/reference.html
new file mode 100644
index 0000000..f24d745
--- /dev/null
+++ b/doc/src/sgml/html/reference.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part VI. Reference</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks" /><link rel="next" href="sql-commands.html" title="SQL Commands" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part VI. Reference</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-commands.html" title="SQL Commands">Next</a></td></tr></table><hr /></div><div class="part" id="REFERENCE"><div class="titlepage"><div><div><h1 class="title">Part VI. Reference</h1></div></div></div><div class="partintro" id="id-1.9.2"><div></div><p>
+ The entries in this Reference are meant to provide in reasonable
+ length an authoritative, complete, and formal summary about their
+ respective subjects. More information about the use of
+ <span class="productname">PostgreSQL</span>, in narrative, tutorial, or
+ example form, can be found in other parts of this book. See the
+ cross-references listed on each reference page.
+ </p><p>
+ The reference entries are also available as traditional
+ <span class="quote">“<span class="quote">man</span>”</span> pages.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="reference"><a href="sql-commands.html">I. SQL Commands</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="sql-abort.html">ABORT</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-alteraggregate.html">ALTER AGGREGATE</a></span><span class="refpurpose"> — change the definition of an aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-altercollation.html">ALTER COLLATION</a></span><span class="refpurpose"> — change the definition of a collation</span></dt><dt><span class="refentrytitle"><a href="sql-alterconversion.html">ALTER CONVERSION</a></span><span class="refpurpose"> — change the definition of a conversion</span></dt><dt><span class="refentrytitle"><a href="sql-alterdatabase.html">ALTER DATABASE</a></span><span class="refpurpose"> — change a database</span></dt><dt><span class="refentrytitle"><a href="sql-alterdefaultprivileges.html">ALTER DEFAULT PRIVILEGES</a></span><span class="refpurpose"> — define default access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-alterdomain.html">ALTER DOMAIN</a></span><span class="refpurpose"> —
+ change the definition of a domain
+ </span></dt><dt><span class="refentrytitle"><a href="sql-altereventtrigger.html">ALTER EVENT TRIGGER</a></span><span class="refpurpose"> — change the definition of an event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-alterextension.html">ALTER EXTENSION</a></span><span class="refpurpose"> —
+ change the definition of an extension
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alterforeigndatawrapper.html">ALTER FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — change the definition of a foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-alterforeigntable.html">ALTER FOREIGN TABLE</a></span><span class="refpurpose"> — change the definition of a foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-alterfunction.html">ALTER FUNCTION</a></span><span class="refpurpose"> — change the definition of a function</span></dt><dt><span class="refentrytitle"><a href="sql-altergroup.html">ALTER GROUP</a></span><span class="refpurpose"> — change role name or membership</span></dt><dt><span class="refentrytitle"><a href="sql-alterindex.html">ALTER INDEX</a></span><span class="refpurpose"> — change the definition of an index</span></dt><dt><span class="refentrytitle"><a href="sql-alterlanguage.html">ALTER LANGUAGE</a></span><span class="refpurpose"> — change the definition of a procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-alterlargeobject.html">ALTER LARGE OBJECT</a></span><span class="refpurpose"> — change the definition of a large object</span></dt><dt><span class="refentrytitle"><a href="sql-altermaterializedview.html">ALTER MATERIALIZED VIEW</a></span><span class="refpurpose"> — change the definition of a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-alteroperator.html">ALTER OPERATOR</a></span><span class="refpurpose"> — change the definition of an operator</span></dt><dt><span class="refentrytitle"><a href="sql-alteropclass.html">ALTER OPERATOR CLASS</a></span><span class="refpurpose"> — change the definition of an operator class</span></dt><dt><span class="refentrytitle"><a href="sql-alteropfamily.html">ALTER OPERATOR FAMILY</a></span><span class="refpurpose"> — change the definition of an operator family</span></dt><dt><span class="refentrytitle"><a href="sql-alterpolicy.html">ALTER POLICY</a></span><span class="refpurpose"> — change the definition of a row-level security policy</span></dt><dt><span class="refentrytitle"><a href="sql-alterprocedure.html">ALTER PROCEDURE</a></span><span class="refpurpose"> — change the definition of a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-alterpublication.html">ALTER PUBLICATION</a></span><span class="refpurpose"> — change the definition of a publication</span></dt><dt><span class="refentrytitle"><a href="sql-alterrole.html">ALTER ROLE</a></span><span class="refpurpose"> — change a database role</span></dt><dt><span class="refentrytitle"><a href="sql-alterroutine.html">ALTER ROUTINE</a></span><span class="refpurpose"> — change the definition of a routine</span></dt><dt><span class="refentrytitle"><a href="sql-alterrule.html">ALTER RULE</a></span><span class="refpurpose"> — change the definition of a rule</span></dt><dt><span class="refentrytitle"><a href="sql-alterschema.html">ALTER SCHEMA</a></span><span class="refpurpose"> — change the definition of a schema</span></dt><dt><span class="refentrytitle"><a href="sql-altersequence.html">ALTER SEQUENCE</a></span><span class="refpurpose"> —
+ change the definition of a sequence generator
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alterserver.html">ALTER SERVER</a></span><span class="refpurpose"> — change the definition of a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-alterstatistics.html">ALTER STATISTICS</a></span><span class="refpurpose"> —
+ change the definition of an extended statistics object
+ </span></dt><dt><span class="refentrytitle"><a href="sql-altersubscription.html">ALTER SUBSCRIPTION</a></span><span class="refpurpose"> — change the definition of a subscription</span></dt><dt><span class="refentrytitle"><a href="sql-altersystem.html">ALTER SYSTEM</a></span><span class="refpurpose"> — change a server configuration parameter</span></dt><dt><span class="refentrytitle"><a href="sql-altertable.html">ALTER TABLE</a></span><span class="refpurpose"> — change the definition of a table</span></dt><dt><span class="refentrytitle"><a href="sql-altertablespace.html">ALTER TABLESPACE</a></span><span class="refpurpose"> — change the definition of a tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-altertsconfig.html">ALTER TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — change the definition of a text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-altertsdictionary.html">ALTER TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — change the definition of a text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-altertsparser.html">ALTER TEXT SEARCH PARSER</a></span><span class="refpurpose"> — change the definition of a text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-altertstemplate.html">ALTER TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — change the definition of a text search template</span></dt><dt><span class="refentrytitle"><a href="sql-altertrigger.html">ALTER TRIGGER</a></span><span class="refpurpose"> — change the definition of a trigger</span></dt><dt><span class="refentrytitle"><a href="sql-altertype.html">ALTER TYPE</a></span><span class="refpurpose"> —
+ change the definition of a type
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alteruser.html">ALTER USER</a></span><span class="refpurpose"> — change a database role</span></dt><dt><span class="refentrytitle"><a href="sql-alterusermapping.html">ALTER USER MAPPING</a></span><span class="refpurpose"> — change the definition of a user mapping</span></dt><dt><span class="refentrytitle"><a href="sql-alterview.html">ALTER VIEW</a></span><span class="refpurpose"> — change the definition of a view</span></dt><dt><span class="refentrytitle"><a href="sql-analyze.html">ANALYZE</a></span><span class="refpurpose"> — collect statistics about a database</span></dt><dt><span class="refentrytitle"><a href="sql-begin.html">BEGIN</a></span><span class="refpurpose"> — start a transaction block</span></dt><dt><span class="refentrytitle"><a href="sql-call.html">CALL</a></span><span class="refpurpose"> — invoke a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-checkpoint.html">CHECKPOINT</a></span><span class="refpurpose"> — force a write-ahead log checkpoint</span></dt><dt><span class="refentrytitle"><a href="sql-close.html">CLOSE</a></span><span class="refpurpose"> — close a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-cluster.html">CLUSTER</a></span><span class="refpurpose"> — cluster a table according to an index</span></dt><dt><span class="refentrytitle"><a href="sql-comment.html">COMMENT</a></span><span class="refpurpose"> — define or change the comment of an object</span></dt><dt><span class="refentrytitle"><a href="sql-commit.html">COMMIT</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-commit-prepared.html">COMMIT PREPARED</a></span><span class="refpurpose"> — commit a transaction that was earlier prepared for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-copy.html">COPY</a></span><span class="refpurpose"> — copy data between a file and a table</span></dt><dt><span class="refentrytitle"><a href="sql-create-access-method.html">CREATE ACCESS METHOD</a></span><span class="refpurpose"> — define a new access method</span></dt><dt><span class="refentrytitle"><a href="sql-createaggregate.html">CREATE AGGREGATE</a></span><span class="refpurpose"> — define a new aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-createcast.html">CREATE CAST</a></span><span class="refpurpose"> — define a new cast</span></dt><dt><span class="refentrytitle"><a href="sql-createcollation.html">CREATE COLLATION</a></span><span class="refpurpose"> — define a new collation</span></dt><dt><span class="refentrytitle"><a href="sql-createconversion.html">CREATE CONVERSION</a></span><span class="refpurpose"> — define a new encoding conversion</span></dt><dt><span class="refentrytitle"><a href="sql-createdatabase.html">CREATE DATABASE</a></span><span class="refpurpose"> — create a new database</span></dt><dt><span class="refentrytitle"><a href="sql-createdomain.html">CREATE DOMAIN</a></span><span class="refpurpose"> — define a new domain</span></dt><dt><span class="refentrytitle"><a href="sql-createeventtrigger.html">CREATE EVENT TRIGGER</a></span><span class="refpurpose"> — define a new event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-createextension.html">CREATE EXTENSION</a></span><span class="refpurpose"> — install an extension</span></dt><dt><span class="refentrytitle"><a href="sql-createforeigndatawrapper.html">CREATE FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — define a new foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-createforeigntable.html">CREATE FOREIGN TABLE</a></span><span class="refpurpose"> — define a new foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-createfunction.html">CREATE FUNCTION</a></span><span class="refpurpose"> — define a new function</span></dt><dt><span class="refentrytitle"><a href="sql-creategroup.html">CREATE GROUP</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createindex.html">CREATE INDEX</a></span><span class="refpurpose"> — define a new index</span></dt><dt><span class="refentrytitle"><a href="sql-createlanguage.html">CREATE LANGUAGE</a></span><span class="refpurpose"> — define a new procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-creatematerializedview.html">CREATE MATERIALIZED VIEW</a></span><span class="refpurpose"> — define a new materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-createoperator.html">CREATE OPERATOR</a></span><span class="refpurpose"> — define a new operator</span></dt><dt><span class="refentrytitle"><a href="sql-createopclass.html">CREATE OPERATOR CLASS</a></span><span class="refpurpose"> — define a new operator class</span></dt><dt><span class="refentrytitle"><a href="sql-createopfamily.html">CREATE OPERATOR FAMILY</a></span><span class="refpurpose"> — define a new operator family</span></dt><dt><span class="refentrytitle"><a href="sql-createpolicy.html">CREATE POLICY</a></span><span class="refpurpose"> — define a new row-level security policy for a table</span></dt><dt><span class="refentrytitle"><a href="sql-createprocedure.html">CREATE PROCEDURE</a></span><span class="refpurpose"> — define a new procedure</span></dt><dt><span class="refentrytitle"><a href="sql-createpublication.html">CREATE PUBLICATION</a></span><span class="refpurpose"> — define a new publication</span></dt><dt><span class="refentrytitle"><a href="sql-createrole.html">CREATE ROLE</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createrule.html">CREATE RULE</a></span><span class="refpurpose"> — define a new rewrite rule</span></dt><dt><span class="refentrytitle"><a href="sql-createschema.html">CREATE SCHEMA</a></span><span class="refpurpose"> — define a new schema</span></dt><dt><span class="refentrytitle"><a href="sql-createsequence.html">CREATE SEQUENCE</a></span><span class="refpurpose"> — define a new sequence generator</span></dt><dt><span class="refentrytitle"><a href="sql-createserver.html">CREATE SERVER</a></span><span class="refpurpose"> — define a new foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-createstatistics.html">CREATE STATISTICS</a></span><span class="refpurpose"> — define extended statistics</span></dt><dt><span class="refentrytitle"><a href="sql-createsubscription.html">CREATE SUBSCRIPTION</a></span><span class="refpurpose"> — define a new subscription</span></dt><dt><span class="refentrytitle"><a href="sql-createtable.html">CREATE TABLE</a></span><span class="refpurpose"> — define a new table</span></dt><dt><span class="refentrytitle"><a href="sql-createtableas.html">CREATE TABLE AS</a></span><span class="refpurpose"> — define a new table from the results of a query</span></dt><dt><span class="refentrytitle"><a href="sql-createtablespace.html">CREATE TABLESPACE</a></span><span class="refpurpose"> — define a new tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-createtsconfig.html">CREATE TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — define a new text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-createtsdictionary.html">CREATE TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — define a new text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-createtsparser.html">CREATE TEXT SEARCH PARSER</a></span><span class="refpurpose"> — define a new text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-createtstemplate.html">CREATE TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — define a new text search template</span></dt><dt><span class="refentrytitle"><a href="sql-createtransform.html">CREATE TRANSFORM</a></span><span class="refpurpose"> — define a new transform</span></dt><dt><span class="refentrytitle"><a href="sql-createtrigger.html">CREATE TRIGGER</a></span><span class="refpurpose"> — define a new trigger</span></dt><dt><span class="refentrytitle"><a href="sql-createtype.html">CREATE TYPE</a></span><span class="refpurpose"> — define a new data type</span></dt><dt><span class="refentrytitle"><a href="sql-createuser.html">CREATE USER</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createusermapping.html">CREATE USER MAPPING</a></span><span class="refpurpose"> — define a new mapping of a user to a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-createview.html">CREATE VIEW</a></span><span class="refpurpose"> — define a new view</span></dt><dt><span class="refentrytitle"><a href="sql-deallocate.html">DEALLOCATE</a></span><span class="refpurpose"> — deallocate a prepared statement</span></dt><dt><span class="refentrytitle"><a href="sql-declare.html">DECLARE</a></span><span class="refpurpose"> — define a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-delete.html">DELETE</a></span><span class="refpurpose"> — delete rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-discard.html">DISCARD</a></span><span class="refpurpose"> — discard session state</span></dt><dt><span class="refentrytitle"><a href="sql-do.html">DO</a></span><span class="refpurpose"> — execute an anonymous code block</span></dt><dt><span class="refentrytitle"><a href="sql-drop-access-method.html">DROP ACCESS METHOD</a></span><span class="refpurpose"> — remove an access method</span></dt><dt><span class="refentrytitle"><a href="sql-dropaggregate.html">DROP AGGREGATE</a></span><span class="refpurpose"> — remove an aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-dropcast.html">DROP CAST</a></span><span class="refpurpose"> — remove a cast</span></dt><dt><span class="refentrytitle"><a href="sql-dropcollation.html">DROP COLLATION</a></span><span class="refpurpose"> — remove a collation</span></dt><dt><span class="refentrytitle"><a href="sql-dropconversion.html">DROP CONVERSION</a></span><span class="refpurpose"> — remove a conversion</span></dt><dt><span class="refentrytitle"><a href="sql-dropdatabase.html">DROP DATABASE</a></span><span class="refpurpose"> — remove a database</span></dt><dt><span class="refentrytitle"><a href="sql-dropdomain.html">DROP DOMAIN</a></span><span class="refpurpose"> — remove a domain</span></dt><dt><span class="refentrytitle"><a href="sql-dropeventtrigger.html">DROP EVENT TRIGGER</a></span><span class="refpurpose"> — remove an event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-dropextension.html">DROP EXTENSION</a></span><span class="refpurpose"> — remove an extension</span></dt><dt><span class="refentrytitle"><a href="sql-dropforeigndatawrapper.html">DROP FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — remove a foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-dropforeigntable.html">DROP FOREIGN TABLE</a></span><span class="refpurpose"> — remove a foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-dropfunction.html">DROP FUNCTION</a></span><span class="refpurpose"> — remove a function</span></dt><dt><span class="refentrytitle"><a href="sql-dropgroup.html">DROP GROUP</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-dropindex.html">DROP INDEX</a></span><span class="refpurpose"> — remove an index</span></dt><dt><span class="refentrytitle"><a href="sql-droplanguage.html">DROP LANGUAGE</a></span><span class="refpurpose"> — remove a procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-dropmaterializedview.html">DROP MATERIALIZED VIEW</a></span><span class="refpurpose"> — remove a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-dropoperator.html">DROP OPERATOR</a></span><span class="refpurpose"> — remove an operator</span></dt><dt><span class="refentrytitle"><a href="sql-dropopclass.html">DROP OPERATOR CLASS</a></span><span class="refpurpose"> — remove an operator class</span></dt><dt><span class="refentrytitle"><a href="sql-dropopfamily.html">DROP OPERATOR FAMILY</a></span><span class="refpurpose"> — remove an operator family</span></dt><dt><span class="refentrytitle"><a href="sql-drop-owned.html">DROP OWNED</a></span><span class="refpurpose"> — remove database objects owned by a database role</span></dt><dt><span class="refentrytitle"><a href="sql-droppolicy.html">DROP POLICY</a></span><span class="refpurpose"> — remove a row-level security policy from a table</span></dt><dt><span class="refentrytitle"><a href="sql-dropprocedure.html">DROP PROCEDURE</a></span><span class="refpurpose"> — remove a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-droppublication.html">DROP PUBLICATION</a></span><span class="refpurpose"> — remove a publication</span></dt><dt><span class="refentrytitle"><a href="sql-droprole.html">DROP ROLE</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-droproutine.html">DROP ROUTINE</a></span><span class="refpurpose"> — remove a routine</span></dt><dt><span class="refentrytitle"><a href="sql-droprule.html">DROP RULE</a></span><span class="refpurpose"> — remove a rewrite rule</span></dt><dt><span class="refentrytitle"><a href="sql-dropschema.html">DROP SCHEMA</a></span><span class="refpurpose"> — remove a schema</span></dt><dt><span class="refentrytitle"><a href="sql-dropsequence.html">DROP SEQUENCE</a></span><span class="refpurpose"> — remove a sequence</span></dt><dt><span class="refentrytitle"><a href="sql-dropserver.html">DROP SERVER</a></span><span class="refpurpose"> — remove a foreign server descriptor</span></dt><dt><span class="refentrytitle"><a href="sql-dropstatistics.html">DROP STATISTICS</a></span><span class="refpurpose"> — remove extended statistics</span></dt><dt><span class="refentrytitle"><a href="sql-dropsubscription.html">DROP SUBSCRIPTION</a></span><span class="refpurpose"> — remove a subscription</span></dt><dt><span class="refentrytitle"><a href="sql-droptable.html">DROP TABLE</a></span><span class="refpurpose"> — remove a table</span></dt><dt><span class="refentrytitle"><a href="sql-droptablespace.html">DROP TABLESPACE</a></span><span class="refpurpose"> — remove a tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-droptsconfig.html">DROP TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — remove a text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-droptsdictionary.html">DROP TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — remove a text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-droptsparser.html">DROP TEXT SEARCH PARSER</a></span><span class="refpurpose"> — remove a text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-droptstemplate.html">DROP TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — remove a text search template</span></dt><dt><span class="refentrytitle"><a href="sql-droptransform.html">DROP TRANSFORM</a></span><span class="refpurpose"> — remove a transform</span></dt><dt><span class="refentrytitle"><a href="sql-droptrigger.html">DROP TRIGGER</a></span><span class="refpurpose"> — remove a trigger</span></dt><dt><span class="refentrytitle"><a href="sql-droptype.html">DROP TYPE</a></span><span class="refpurpose"> — remove a data type</span></dt><dt><span class="refentrytitle"><a href="sql-dropuser.html">DROP USER</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-dropusermapping.html">DROP USER MAPPING</a></span><span class="refpurpose"> — remove a user mapping for a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-dropview.html">DROP VIEW</a></span><span class="refpurpose"> — remove a view</span></dt><dt><span class="refentrytitle"><a href="sql-end.html">END</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-execute.html">EXECUTE</a></span><span class="refpurpose"> — execute a prepared statement</span></dt><dt><span class="refentrytitle"><a href="sql-explain.html">EXPLAIN</a></span><span class="refpurpose"> — show the execution plan of a statement</span></dt><dt><span class="refentrytitle"><a href="sql-fetch.html">FETCH</a></span><span class="refpurpose"> — retrieve rows from a query using a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-grant.html">GRANT</a></span><span class="refpurpose"> — define access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-importforeignschema.html">IMPORT FOREIGN SCHEMA</a></span><span class="refpurpose"> — import table definitions from a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-insert.html">INSERT</a></span><span class="refpurpose"> — create new rows in a table</span></dt><dt><span class="refentrytitle"><a href="sql-listen.html">LISTEN</a></span><span class="refpurpose"> — listen for a notification</span></dt><dt><span class="refentrytitle"><a href="sql-load.html">LOAD</a></span><span class="refpurpose"> — load a shared library file</span></dt><dt><span class="refentrytitle"><a href="sql-lock.html">LOCK</a></span><span class="refpurpose"> — lock a table</span></dt><dt><span class="refentrytitle"><a href="sql-merge.html">MERGE</a></span><span class="refpurpose"> — conditionally insert, update, or delete rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-move.html">MOVE</a></span><span class="refpurpose"> — position a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-notify.html">NOTIFY</a></span><span class="refpurpose"> — generate a notification</span></dt><dt><span class="refentrytitle"><a href="sql-prepare.html">PREPARE</a></span><span class="refpurpose"> — prepare a statement for execution</span></dt><dt><span class="refentrytitle"><a href="sql-prepare-transaction.html">PREPARE TRANSACTION</a></span><span class="refpurpose"> — prepare the current transaction for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-reassign-owned.html">REASSIGN OWNED</a></span><span class="refpurpose"> — change the ownership of database objects owned by a database role</span></dt><dt><span class="refentrytitle"><a href="sql-refreshmaterializedview.html">REFRESH MATERIALIZED VIEW</a></span><span class="refpurpose"> — replace the contents of a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-reindex.html">REINDEX</a></span><span class="refpurpose"> — rebuild indexes</span></dt><dt><span class="refentrytitle"><a href="sql-release-savepoint.html">RELEASE SAVEPOINT</a></span><span class="refpurpose"> — destroy a previously defined savepoint</span></dt><dt><span class="refentrytitle"><a href="sql-reset.html">RESET</a></span><span class="refpurpose"> — restore the value of a run-time parameter to the default value</span></dt><dt><span class="refentrytitle"><a href="sql-revoke.html">REVOKE</a></span><span class="refpurpose"> — remove access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-rollback.html">ROLLBACK</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-rollback-prepared.html">ROLLBACK PREPARED</a></span><span class="refpurpose"> — cancel a transaction that was earlier prepared for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-rollback-to.html">ROLLBACK TO SAVEPOINT</a></span><span class="refpurpose"> — roll back to a savepoint</span></dt><dt><span class="refentrytitle"><a href="sql-savepoint.html">SAVEPOINT</a></span><span class="refpurpose"> — define a new savepoint within the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-security-label.html">SECURITY LABEL</a></span><span class="refpurpose"> — define or change a security label applied to an object</span></dt><dt><span class="refentrytitle"><a href="sql-select.html">SELECT</a></span><span class="refpurpose"> — retrieve rows from a table or view</span></dt><dt><span class="refentrytitle"><a href="sql-selectinto.html">SELECT INTO</a></span><span class="refpurpose"> — define a new table from the results of a query</span></dt><dt><span class="refentrytitle"><a href="sql-set.html">SET</a></span><span class="refpurpose"> — change a run-time parameter</span></dt><dt><span class="refentrytitle"><a href="sql-set-constraints.html">SET CONSTRAINTS</a></span><span class="refpurpose"> — set constraint check timing for the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-set-role.html">SET ROLE</a></span><span class="refpurpose"> — set the current user identifier of the current session</span></dt><dt><span class="refentrytitle"><a href="sql-set-session-authorization.html">SET SESSION AUTHORIZATION</a></span><span class="refpurpose"> — set the session user identifier and the current user identifier of the current session</span></dt><dt><span class="refentrytitle"><a href="sql-set-transaction.html">SET TRANSACTION</a></span><span class="refpurpose"> — set the characteristics of the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-show.html">SHOW</a></span><span class="refpurpose"> — show the value of a run-time parameter</span></dt><dt><span class="refentrytitle"><a href="sql-start-transaction.html">START TRANSACTION</a></span><span class="refpurpose"> — start a transaction block</span></dt><dt><span class="refentrytitle"><a href="sql-truncate.html">TRUNCATE</a></span><span class="refpurpose"> — empty a table or set of tables</span></dt><dt><span class="refentrytitle"><a href="sql-unlisten.html">UNLISTEN</a></span><span class="refpurpose"> — stop listening for a notification</span></dt><dt><span class="refentrytitle"><a href="sql-update.html">UPDATE</a></span><span class="refpurpose"> — update rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-vacuum.html">VACUUM</a></span><span class="refpurpose"> — garbage-collect and optionally analyze a database</span></dt><dt><span class="refentrytitle"><a href="sql-values.html">VALUES</a></span><span class="refpurpose"> — compute a set of rows</span></dt></dl></dd><dt><span class="reference"><a href="reference-client.html">II. PostgreSQL Client Applications</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="app-clusterdb.html"><span class="application">clusterdb</span></a></span><span class="refpurpose"> — cluster a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-createdb.html"><span class="application">createdb</span></a></span><span class="refpurpose"> — create a new <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-createuser.html"><span class="application">createuser</span></a></span><span class="refpurpose"> — define a new <span class="productname">PostgreSQL</span> user account</span></dt><dt><span class="refentrytitle"><a href="app-dropdb.html"><span class="application">dropdb</span></a></span><span class="refpurpose"> — remove a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-dropuser.html"><span class="application">dropuser</span></a></span><span class="refpurpose"> — remove a <span class="productname">PostgreSQL</span> user account</span></dt><dt><span class="refentrytitle"><a href="app-ecpg.html"><span class="application">ecpg</span></a></span><span class="refpurpose"> — embedded SQL C preprocessor</span></dt><dt><span class="refentrytitle"><a href="app-pgamcheck.html"><span class="application">pg_amcheck</span></a></span><span class="refpurpose"> — checks for corruption in one or more
+ <span class="productname">PostgreSQL</span> databases</span></dt><dt><span class="refentrytitle"><a href="app-pgbasebackup.html"><span class="application">pg_basebackup</span></a></span><span class="refpurpose"> — take a base backup of a <span class="productname">PostgreSQL</span> cluster</span></dt><dt><span class="refentrytitle"><a href="pgbench.html"><span class="application">pgbench</span></a></span><span class="refpurpose"> — run a benchmark test on <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="app-pgconfig.html"><span class="application">pg_config</span></a></span><span class="refpurpose"> — retrieve information about the installed version of <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="app-pgdump.html"><span class="application">pg_dump</span></a></span><span class="refpurpose"> —
+ extract a <span class="productname">PostgreSQL</span> database into a script file or other archive file
+ </span></dt><dt><span class="refentrytitle"><a href="app-pg-dumpall.html"><span class="application">pg_dumpall</span></a></span><span class="refpurpose"> — extract a <span class="productname">PostgreSQL</span> database cluster into a script file</span></dt><dt><span class="refentrytitle"><a href="app-pg-isready.html"><span class="application">pg_isready</span></a></span><span class="refpurpose"> — check the connection status of a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgreceivewal.html"><span class="application">pg_receivewal</span></a></span><span class="refpurpose"> — stream write-ahead logs from a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgrecvlogical.html"><span class="application">pg_recvlogical</span></a></span><span class="refpurpose"> — control <span class="productname">PostgreSQL</span> logical decoding streams</span></dt><dt><span class="refentrytitle"><a href="app-pgrestore.html"><span class="application">pg_restore</span></a></span><span class="refpurpose"> —
+ restore a <span class="productname">PostgreSQL</span> database from an
+ archive file created by <span class="application">pg_dump</span>
+ </span></dt><dt><span class="refentrytitle"><a href="app-pgverifybackup.html"><span class="application">pg_verifybackup</span></a></span><span class="refpurpose"> — verify the integrity of a base backup of a
+ <span class="productname">PostgreSQL</span> cluster</span></dt><dt><span class="refentrytitle"><a href="app-psql.html"><span class="application">psql</span></a></span><span class="refpurpose"> —
+ <span class="productname">PostgreSQL</span> interactive terminal
+ </span></dt><dt><span class="refentrytitle"><a href="app-reindexdb.html"><span class="application">reindexdb</span></a></span><span class="refpurpose"> — reindex a <span class="productname">PostgreSQL</span> database</span></dt><dt><span class="refentrytitle"><a href="app-vacuumdb.html"><span class="application">vacuumdb</span></a></span><span class="refpurpose"> — garbage-collect and analyze a <span class="productname">PostgreSQL</span> database</span></dt></dl></dd><dt><span class="reference"><a href="reference-server.html">III. PostgreSQL Server Applications</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="app-initdb.html"><span class="application">initdb</span></a></span><span class="refpurpose"> — create a new <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="pgarchivecleanup.html"><span class="application">pg_archivecleanup</span></a></span><span class="refpurpose"> — clean up <span class="productname">PostgreSQL</span> WAL archive files</span></dt><dt><span class="refentrytitle"><a href="app-pgchecksums.html"><span class="application">pg_checksums</span></a></span><span class="refpurpose"> — enable, disable or check data checksums in a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pgcontroldata.html"><span class="application">pg_controldata</span></a></span><span class="refpurpose"> — display control information of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pg-ctl.html"><span class="application">pg_ctl</span></a></span><span class="refpurpose"> — initialize, start, stop, or control a <span class="productname">PostgreSQL</span> server</span></dt><dt><span class="refentrytitle"><a href="app-pgresetwal.html"><span class="application">pg_resetwal</span></a></span><span class="refpurpose"> — reset the write-ahead log and other control information of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-pgrewind.html"><span class="application">pg_rewind</span></a></span><span class="refpurpose"> — synchronize a <span class="productname">PostgreSQL</span> data directory with another data directory that was forked from it</span></dt><dt><span class="refentrytitle"><a href="pgtestfsync.html"><span class="application">pg_test_fsync</span></a></span><span class="refpurpose"> — determine fastest <code class="varname">wal_sync_method</code> for <span class="productname">PostgreSQL</span></span></dt><dt><span class="refentrytitle"><a href="pgtesttiming.html"><span class="application">pg_test_timing</span></a></span><span class="refpurpose"> — measure timing overhead</span></dt><dt><span class="refentrytitle"><a href="pgupgrade.html"><span class="application">pg_upgrade</span></a></span><span class="refpurpose"> — upgrade a <span class="productname">PostgreSQL</span> server instance</span></dt><dt><span class="refentrytitle"><a href="pgwaldump.html"><span class="application">pg_waldump</span></a></span><span class="refpurpose"> — display a human-readable rendering of the write-ahead log of a <span class="productname">PostgreSQL</span> database cluster</span></dt><dt><span class="refentrytitle"><a href="app-postgres.html"><span class="application">postgres</span></a></span><span class="refpurpose"> — <span class="productname">PostgreSQL</span> database server</span></dt><dt><span class="refentrytitle"><a href="app-postmaster.html"><span class="application">postmaster</span></a></span><span class="refpurpose"> — <span class="productname">PostgreSQL</span> database server</span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="archive-module-callbacks.html" title="51.2. Archive Module Callbacks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-commands.html" title="SQL Commands">Next</a></td></tr><tr><td width="40%" align="left" valign="top">51.2. Archive Module Callbacks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SQL Commands</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress-coverage.html b/doc/src/sgml/html/regress-coverage.html
new file mode 100644
index 0000000..c89f070
--- /dev/null
+++ b/doc/src/sgml/html/regress-coverage.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.5. Test Coverage Examination</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress-tap.html" title="33.4. TAP Tests" /><link rel="next" href="client-interfaces.html" title="Part IV. Client Interfaces" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.5. Test Coverage Examination</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress-tap.html" title="33.4. TAP Tests">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><th width="60%" align="center">Chapter 33. Regression Tests</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="client-interfaces.html" title="Part IV. Client Interfaces">Next</a></td></tr></table><hr /></div><div class="sect1" id="REGRESS-COVERAGE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.5. Test Coverage Examination</h2></div></div></div><p>
+ The PostgreSQL source code can be compiled with coverage testing
+ instrumentation, so that it becomes possible to examine which
+ parts of the code are covered by the regression tests or any other
+ test suite that is run with the code. This is currently supported
+ when compiling with GCC, and it requires the <code class="command">gcov</code>
+ and <code class="command">lcov</code> programs.
+ </p><p>
+ A typical workflow looks like this:
+</p><pre class="screen">
+./configure --enable-coverage ... OTHER OPTIONS ...
+make
+make check # or other test suite
+make coverage-html
+</pre><p>
+ Then point your HTML browser
+ to <code class="filename">coverage/index.html</code>.
+ </p><p>
+ If you don't have <code class="command">lcov</code> or prefer text output over an
+ HTML report, you can run
+</p><pre class="screen">
+make coverage
+</pre><p>
+ instead of <code class="literal">make coverage-html</code>, which will
+ produce <code class="filename">.gcov</code> output files for each source file
+ relevant to the test. (<code class="literal">make coverage</code> and <code class="literal">make
+ coverage-html</code> will overwrite each other's files, so mixing them
+ might be confusing.)
+ </p><p>
+ You can run several different tests before making the coverage report;
+ the execution counts will accumulate. If you want
+ to reset the execution counts between test runs, run:
+</p><pre class="screen">
+make coverage-clean
+</pre><p>
+ </p><p>
+ You can run the <code class="literal">make coverage-html</code> or <code class="literal">make
+ coverage</code> command in a subdirectory if you want a coverage
+ report for only a portion of the code tree.
+ </p><p>
+ Use <code class="literal">make distclean</code> to clean up when done.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress-tap.html" title="33.4. TAP Tests">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="client-interfaces.html" title="Part IV. Client Interfaces">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.4. TAP Tests </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part IV. Client Interfaces</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress-evaluation.html b/doc/src/sgml/html/regress-evaluation.html
new file mode 100644
index 0000000..13fc3df
--- /dev/null
+++ b/doc/src/sgml/html/regress-evaluation.html
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.2. Test Evaluation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress-run.html" title="33.1. Running the Tests" /><link rel="next" href="regress-variant.html" title="33.3. Variant Comparison Files" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.2. Test Evaluation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress-run.html" title="33.1. Running the Tests">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><th width="60%" align="center">Chapter 33. Regression Tests</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress-variant.html" title="33.3. Variant Comparison Files">Next</a></td></tr></table><hr /></div><div class="sect1" id="REGRESS-EVALUATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.2. Test Evaluation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.6">33.2.1. Error Message Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.7">33.2.2. Locale Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.8">33.2.3. Date and Time Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.9">33.2.4. Floating-Point Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.10">33.2.5. Row Ordering Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.11">33.2.6. Insufficient Stack Depth</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.12">33.2.7. The <span class="quote">“<span class="quote">random</span>”</span> Test</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.13">33.2.8. Configuration Parameters</a></span></dt></dl></div><p>
+ Some properly installed and fully functional
+ <span class="productname">PostgreSQL</span> installations can
+ <span class="quote">“<span class="quote">fail</span>”</span> some of these regression tests due to
+ platform-specific artifacts such as varying floating-point representation
+ and message wording. The tests are currently evaluated using a simple
+ <code class="command">diff</code> comparison against the outputs
+ generated on a reference system, so the results are sensitive to
+ small system differences. When a test is reported as
+ <span class="quote">“<span class="quote">failed</span>”</span>, always examine the differences between
+ expected and actual results; you might find that the
+ differences are not significant. Nonetheless, we still strive to
+ maintain accurate reference files across all supported platforms,
+ so it can be expected that all tests pass.
+ </p><p>
+ The actual outputs of the regression tests are in files in the
+ <code class="filename">src/test/regress/results</code> directory. The test
+ script uses <code class="command">diff</code> to compare each output
+ file against the reference outputs stored in the
+ <code class="filename">src/test/regress/expected</code> directory. Any
+ differences are saved for your inspection in
+ <code class="filename">src/test/regress/regression.diffs</code>.
+ (When running a test suite other than the core tests, these files
+ of course appear in the relevant subdirectory,
+ not <code class="filename">src/test/regress</code>.)
+ </p><p>
+ If you don't
+ like the <code class="command">diff</code> options that are used by default, set the
+ environment variable <code class="envar">PG_REGRESS_DIFF_OPTS</code>, for
+ instance <code class="literal">PG_REGRESS_DIFF_OPTS='-c'</code>. (Or you
+ can run <code class="command">diff</code> yourself, if you prefer.)
+ </p><p>
+ If for some reason a particular platform generates a <span class="quote">“<span class="quote">failure</span>”</span>
+ for a given test, but inspection of the output convinces you that
+ the result is valid, you can add a new comparison file to silence
+ the failure report in future test runs. See
+ <a class="xref" href="regress-variant.html" title="33.3. Variant Comparison Files">Section 33.3</a> for details.
+ </p><div class="sect2" id="id-1.6.20.6.6"><div class="titlepage"><div><div><h3 class="title">33.2.1. Error Message Differences</h3></div></div></div><p>
+ Some of the regression tests involve intentional invalid input
+ values. Error messages can come from either the
+ <span class="productname">PostgreSQL</span> code or from the host
+ platform system routines. In the latter case, the messages can
+ vary between platforms, but should reflect similar
+ information. These differences in messages will result in a
+ <span class="quote">“<span class="quote">failed</span>”</span> regression test that can be validated by
+ inspection.
+ </p></div><div class="sect2" id="id-1.6.20.6.7"><div class="titlepage"><div><div><h3 class="title">33.2.2. Locale Differences</h3></div></div></div><p>
+ If you run the tests against a server that was
+ initialized with a collation-order locale other than C, then
+ there might be differences due to sort order and subsequent
+ failures. The regression test suite is set up to handle this
+ problem by providing alternate result files that together are
+ known to handle a large number of locales.
+ </p><p>
+ To run the tests in a different locale when using the
+ temporary-installation method, pass the appropriate
+ locale-related environment variables on
+ the <code class="command">make</code> command line, for example:
+</p><pre class="programlisting">
+make check LANG=de_DE.utf8
+</pre><p>
+ (The regression test driver unsets <code class="envar">LC_ALL</code>, so it
+ does not work to choose the locale using that variable.) To use
+ no locale, either unset all locale-related environment variables
+ (or set them to <code class="literal">C</code>) or use the following
+ special invocation:
+</p><pre class="programlisting">
+make check NO_LOCALE=1
+</pre><p>
+ When running the tests against an existing installation, the
+ locale setup is determined by the existing installation. To
+ change it, initialize the database cluster with a different
+ locale by passing the appropriate options
+ to <code class="command">initdb</code>.
+ </p><p>
+ In general, it is advisable to try to run the
+ regression tests in the locale setup that is wanted for
+ production use, as this will exercise the locale- and
+ encoding-related code portions that will actually be used in
+ production. Depending on the operating system environment, you
+ might get failures, but then you will at least know what
+ locale-specific behaviors to expect when running real
+ applications.
+ </p></div><div class="sect2" id="id-1.6.20.6.8"><div class="titlepage"><div><div><h3 class="title">33.2.3. Date and Time Differences</h3></div></div></div><p>
+ Most of the date and time results are dependent on the time zone
+ environment. The reference files are generated for time zone
+ <code class="literal">PST8PDT</code> (Berkeley, California), and there will be
+ apparent failures if the tests are not run with that time zone setting.
+ The regression test driver sets environment variable
+ <code class="envar">PGTZ</code> to <code class="literal">PST8PDT</code>, which normally
+ ensures proper results.
+ </p></div><div class="sect2" id="id-1.6.20.6.9"><div class="titlepage"><div><div><h3 class="title">33.2.4. Floating-Point Differences</h3></div></div></div><p>
+ Some of the tests involve computing 64-bit floating-point numbers (<code class="type">double
+ precision</code>) from table columns. Differences in
+ results involving mathematical functions of <code class="type">double
+ precision</code> columns have been observed. The <code class="literal">float8</code> and
+ <code class="literal">geometry</code> tests are particularly prone to small differences
+ across platforms, or even with different compiler optimization settings.
+ Human eyeball comparison is needed to determine the real
+ significance of these differences which are usually 10 places to
+ the right of the decimal point.
+ </p><p>
+ Some systems display minus zero as <code class="literal">-0</code>, while others
+ just show <code class="literal">0</code>.
+ </p><p>
+ Some systems signal errors from <code class="function">pow()</code> and
+ <code class="function">exp()</code> differently from the mechanism
+ expected by the current <span class="productname">PostgreSQL</span>
+ code.
+ </p></div><div class="sect2" id="id-1.6.20.6.10"><div class="titlepage"><div><div><h3 class="title">33.2.5. Row Ordering Differences</h3></div></div></div><p>
+You might see differences in which the same rows are output in a
+different order than what appears in the expected file. In most cases
+this is not, strictly speaking, a bug. Most of the regression test
+scripts are not so pedantic as to use an <code class="literal">ORDER BY</code> for every single
+<code class="literal">SELECT</code>, and so their result row orderings are not well-defined
+according to the SQL specification. In practice, since we are
+looking at the same queries being executed on the same data by the same
+software, we usually get the same result ordering on all platforms,
+so the lack of <code class="literal">ORDER BY</code> is not a problem. Some queries do exhibit
+cross-platform ordering differences, however. When testing against an
+already-installed server, ordering differences can also be caused by
+non-C locale settings or non-default parameter settings, such as custom values
+of <code class="varname">work_mem</code> or the planner cost parameters.
+ </p><p>
+Therefore, if you see an ordering difference, it's not something to
+worry about, unless the query does have an <code class="literal">ORDER BY</code> that your
+result is violating. However, please report it anyway, so that we can add an
+<code class="literal">ORDER BY</code> to that particular query to eliminate the bogus
+<span class="quote">“<span class="quote">failure</span>”</span> in future releases.
+ </p><p>
+You might wonder why we don't order all the regression test queries explicitly
+to get rid of this issue once and for all. The reason is that that would
+make the regression tests less useful, not more, since they'd tend
+to exercise query plan types that produce ordered results to the
+exclusion of those that don't.
+ </p></div><div class="sect2" id="id-1.6.20.6.11"><div class="titlepage"><div><div><h3 class="title">33.2.6. Insufficient Stack Depth</h3></div></div></div><p>
+ If the <code class="literal">errors</code> test results in a server crash
+ at the <code class="literal">select infinite_recurse()</code> command, it means that
+ the platform's limit on process stack size is smaller than the
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-STACK-DEPTH">max_stack_depth</a> parameter indicates. This
+ can be fixed by running the server under a higher stack
+ size limit (4MB is recommended with the default value of
+ <code class="varname">max_stack_depth</code>). If you are unable to do that, an
+ alternative is to reduce the value of <code class="varname">max_stack_depth</code>.
+ </p><p>
+ On platforms supporting <code class="function">getrlimit()</code>, the server should
+ automatically choose a safe value of <code class="varname">max_stack_depth</code>;
+ so unless you've manually overridden this setting, a failure of this
+ kind is a reportable bug.
+ </p></div><div class="sect2" id="id-1.6.20.6.12"><div class="titlepage"><div><div><h3 class="title">33.2.7. The <span class="quote">“<span class="quote">random</span>”</span> Test</h3></div></div></div><p>
+ The <code class="literal">random</code> test script is intended to produce
+ random results. In very rare cases, this causes that regression
+ test to fail. Typing:
+</p><pre class="programlisting">
+diff results/random.out expected/random.out
+</pre><p>
+ should produce only one or a few lines of differences. You need
+ not worry unless the random test fails repeatedly.
+ </p></div><div class="sect2" id="id-1.6.20.6.13"><div class="titlepage"><div><div><h3 class="title">33.2.8. Configuration Parameters</h3></div></div></div><p>
+ When running the tests against an existing installation, some non-default
+ parameter settings could cause the tests to fail. For example, changing
+ parameters such as <code class="varname">enable_seqscan</code> or
+ <code class="varname">enable_indexscan</code> could cause plan changes that would
+ affect the results of tests that use <code class="command">EXPLAIN</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress-run.html" title="33.1. Running the Tests">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress-variant.html" title="33.3. Variant Comparison Files">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.1. Running the Tests </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.3. Variant Comparison Files</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress-run.html b/doc/src/sgml/html/regress-run.html
new file mode 100644
index 0000000..44543f3
--- /dev/null
+++ b/doc/src/sgml/html/regress-run.html
@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.1. Running the Tests</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress.html" title="Chapter 33. Regression Tests" /><link rel="next" href="regress-evaluation.html" title="33.2. Test Evaluation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.1. Running the Tests</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress.html" title="Chapter 33. Regression Tests">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><th width="60%" align="center">Chapter 33. Regression Tests</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress-evaluation.html" title="33.2. Test Evaluation">Next</a></td></tr></table><hr /></div><div class="sect1" id="REGRESS-RUN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.1. Running the Tests</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.3">33.1.1. Running the Tests Against a Temporary Installation</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.4">33.1.2. Running the Tests Against an Existing Installation</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.5">33.1.3. Additional Test Suites</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.6">33.1.4. Locale and Encoding</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.7">33.1.5. Custom Server Settings</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.8">33.1.6. Extra Tests</a></span></dt></dl></div><p>
+ The regression tests can be run against an already installed and
+ running server, or using a temporary installation within the build
+ tree. Furthermore, there is a <span class="quote">“<span class="quote">parallel</span>”</span> and a
+ <span class="quote">“<span class="quote">sequential</span>”</span> mode for running the tests. The
+ sequential method runs each test script alone, while the
+ parallel method starts up multiple server processes to run groups
+ of tests in parallel. Parallel testing adds confidence that
+ interprocess communication and locking are working correctly.
+ </p><div class="sect2" id="id-1.6.20.5.3"><div class="titlepage"><div><div><h3 class="title">33.1.1. Running the Tests Against a Temporary Installation</h3></div></div></div><p>
+ To run the parallel regression tests after building but before installation,
+ type:
+</p><pre class="screen">
+make check
+</pre><p>
+ in the top-level directory. (Or you can change to
+ <code class="filename">src/test/regress</code> and run the command there.)
+ At the end you should see something like:
+</p><pre class="screen">
+<code class="computeroutput">
+=======================
+ All 193 tests passed.
+=======================
+</code>
+</pre><p>
+ or otherwise a note about which tests failed. See <a class="xref" href="regress-evaluation.html" title="33.2. Test Evaluation">Section 33.2</a> below before assuming that a
+ <span class="quote">“<span class="quote">failure</span>”</span> represents a serious problem.
+ </p><p>
+ Because this test method runs a temporary server, it will not work
+ if you did the build as the root user, since the server will not start as
+ root. Recommended procedure is not to do the build as root, or else to
+ perform testing after completing the installation.
+ </p><p>
+ If you have configured <span class="productname">PostgreSQL</span> to install
+ into a location where an older <span class="productname">PostgreSQL</span>
+ installation already exists, and you perform <code class="literal">make check</code>
+ before installing the new version, you might find that the tests fail
+ because the new programs try to use the already-installed shared
+ libraries. (Typical symptoms are complaints about undefined symbols.)
+ If you wish to run the tests before overwriting the old installation,
+ you'll need to build with <code class="literal">configure --disable-rpath</code>.
+ It is not recommended that you use this option for the final installation,
+ however.
+ </p><p>
+ The parallel regression test starts quite a few processes under your
+ user ID. Presently, the maximum concurrency is twenty parallel test
+ scripts, which means forty processes: there's a server process and a
+ <span class="application">psql</span> process for each test script.
+ So if your system enforces a per-user limit on the number of processes,
+ make sure this limit is at least fifty or so, else you might get
+ random-seeming failures in the parallel test. If you are not in
+ a position to raise the limit, you can cut down the degree of parallelism
+ by setting the <code class="literal">MAX_CONNECTIONS</code> parameter. For example:
+</p><pre class="screen">
+make MAX_CONNECTIONS=10 check
+</pre><p>
+ runs no more than ten tests concurrently.
+ </p></div><div class="sect2" id="id-1.6.20.5.4"><div class="titlepage"><div><div><h3 class="title">33.1.2. Running the Tests Against an Existing Installation</h3></div></div></div><p>
+ To run the tests after installation (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>),
+ initialize a data directory and start the
+ server as explained in <a class="xref" href="runtime.html" title="Chapter 19. Server Setup and Operation">Chapter 19</a>, then type:
+</p><pre class="screen">
+make installcheck
+</pre><p>
+or for a parallel test:
+</p><pre class="screen">
+make installcheck-parallel
+</pre><p>
+ The tests will expect to contact the server at the local host and the
+ default port number, unless directed otherwise by <code class="envar">PGHOST</code> and
+ <code class="envar">PGPORT</code> environment variables. The tests will be run in a
+ database named <code class="literal">regression</code>; any existing database by this name
+ will be dropped.
+ </p><p>
+ The tests will also transiently create some cluster-wide objects, such as
+ roles, tablespaces, and subscriptions. These objects will have names
+ beginning with <code class="literal">regress_</code>. Beware of
+ using <code class="literal">installcheck</code> mode with an installation that has
+ any actual global objects named that way.
+ </p></div><div class="sect2" id="id-1.6.20.5.5"><div class="titlepage"><div><div><h3 class="title">33.1.3. Additional Test Suites</h3></div></div></div><p>
+ The <code class="literal">make check</code> and <code class="literal">make installcheck</code> commands
+ run only the <span class="quote">“<span class="quote">core</span>”</span> regression tests, which test built-in
+ functionality of the <span class="productname">PostgreSQL</span> server. The source
+ distribution contains many additional test suites, most of them having
+ to do with add-on functionality such as optional procedural languages.
+ </p><p>
+ To run all test suites applicable to the modules that have been selected
+ to be built, including the core tests, type one of these commands at the
+ top of the build tree:
+</p><pre class="screen">
+make check-world
+make installcheck-world
+</pre><p>
+ These commands run the tests using temporary servers or an
+ already-installed server, respectively, just as previously explained
+ for <code class="literal">make check</code> and <code class="literal">make installcheck</code>. Other
+ considerations are the same as previously explained for each method.
+ Note that <code class="literal">make check-world</code> builds a separate instance
+ (temporary data directory) for each tested module, so it requires more
+ time and disk space than <code class="literal">make installcheck-world</code>.
+ </p><p>
+ On a modern machine with multiple CPU cores and no tight operating-system
+ limits, you can make things go substantially faster with parallelism.
+ The recipe that most PostgreSQL developers actually use for running all
+ tests is something like
+</p><pre class="screen">
+make check-world -j8 &gt;/dev/null
+</pre><p>
+ with a <code class="option">-j</code> limit near to or a bit more than the number
+ of available cores. Discarding <span class="systemitem">stdout</span>
+ eliminates chatter that's not interesting when you just want to verify
+ success. (In case of failure, the <span class="systemitem">stderr</span>
+ messages are usually enough to determine where to look closer.)
+ </p><p>
+ Alternatively, you can run individual test suites by typing
+ <code class="literal">make check</code> or <code class="literal">make installcheck</code> in the appropriate
+ subdirectory of the build tree. Keep in mind that <code class="literal">make
+ installcheck</code> assumes you've installed the relevant module(s), not
+ only the core server.
+ </p><p>
+ The additional tests that can be invoked this way include:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Regression tests for optional procedural languages.
+ These are located under <code class="filename">src/pl</code>.
+ </p></li><li class="listitem"><p>
+ Regression tests for <code class="filename">contrib</code> modules,
+ located under <code class="filename">contrib</code>.
+ Not all <code class="filename">contrib</code> modules have tests.
+ </p></li><li class="listitem"><p>
+ Regression tests for the interface libraries,
+ located in <code class="filename">src/interfaces/libpq/test</code> and
+ <code class="filename">src/interfaces/ecpg/test</code>.
+ </p></li><li class="listitem"><p>
+ Tests for core-supported authentication methods,
+ located in <code class="filename">src/test/authentication</code>.
+ (See below for additional authentication-related tests.)
+ </p></li><li class="listitem"><p>
+ Tests stressing behavior of concurrent sessions,
+ located in <code class="filename">src/test/isolation</code>.
+ </p></li><li class="listitem"><p>
+ Tests for crash recovery and physical replication,
+ located in <code class="filename">src/test/recovery</code>.
+ </p></li><li class="listitem"><p>
+ Tests for logical replication,
+ located in <code class="filename">src/test/subscription</code>.
+ </p></li><li class="listitem"><p>
+ Tests of client programs, located under <code class="filename">src/bin</code>.
+ </p></li></ul></div><p>
+ When using <code class="literal">installcheck</code> mode, these tests will create
+ and destroy test databases whose names
+ include <code class="literal">regression</code>, for
+ example <code class="literal">pl_regression</code>
+ or <code class="literal">contrib_regression</code>. Beware of
+ using <code class="literal">installcheck</code> mode with an installation that has
+ any non-test databases named that way.
+ </p><p>
+ Some of these auxiliary test suites use the TAP infrastructure explained
+ in <a class="xref" href="regress-tap.html" title="33.4. TAP Tests">Section 33.4</a>.
+ The TAP-based tests are run only when PostgreSQL was configured with the
+ option <code class="option">--enable-tap-tests</code>. This is recommended for
+ development, but can be omitted if there is no suitable Perl installation.
+ </p><p>
+ Some test suites are not run by default, either because they are not secure
+ to run on a multiuser system, because they require special software or
+ because they are resource intensive. You can decide which test suites to
+ run additionally by setting the <code class="command">make</code> or environment
+ variable <code class="varname">PG_TEST_EXTRA</code> to a whitespace-separated list,
+ for example:
+</p><pre class="programlisting">
+make check-world PG_TEST_EXTRA='kerberos ldap ssl'
+</pre><p>
+ The following values are currently supported:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">kerberos</code></span></dt><dd><p>
+ Runs the test suite under <code class="filename">src/test/kerberos</code>. This
+ requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ </p></dd><dt><span class="term"><code class="literal">ldap</code></span></dt><dd><p>
+ Runs the test suite under <code class="filename">src/test/ldap</code>. This
+ requires an <span class="productname">OpenLDAP</span> installation and opens
+ TCP/IP listen sockets.
+ </p></dd><dt><span class="term"><code class="literal">ssl</code></span></dt><dd><p>
+ Runs the test suite under <code class="filename">src/test/ssl</code>. This opens TCP/IP listen sockets.
+ </p></dd><dt><span class="term"><code class="literal">wal_consistency_checking</code></span></dt><dd><p>
+ Uses <code class="literal">wal_consistency_checking=all</code> while running
+ certain tests under <code class="filename">src/test/recovery</code>. Not
+ enabled by default because it is resource intensive.
+ </p></dd></dl></div><p>
+
+ Tests for features that are not supported by the current build
+ configuration are not run even if they are mentioned in
+ <code class="varname">PG_TEST_EXTRA</code>.
+ </p><p>
+ In addition, there are tests in <code class="filename">src/test/modules</code>
+ which will be run by <code class="literal">make check-world</code> but not
+ by <code class="literal">make installcheck-world</code>. This is because they
+ install non-production extensions or have other side-effects that are
+ considered undesirable for a production installation. You can
+ use <code class="literal">make install</code> and <code class="literal">make
+ installcheck</code> in one of those subdirectories if you wish,
+ but it's not recommended to do so with a non-test server.
+ </p></div><div class="sect2" id="id-1.6.20.5.6"><div class="titlepage"><div><div><h3 class="title">33.1.4. Locale and Encoding</h3></div></div></div><p>
+ By default, tests using a temporary installation use the
+ locale defined in the current environment and the corresponding
+ database encoding as determined by <code class="command">initdb</code>. It
+ can be useful to test different locales by setting the appropriate
+ environment variables, for example:
+</p><pre class="screen">
+make check LANG=C
+make check LC_COLLATE=en_US.utf8 LC_CTYPE=fr_CA.utf8
+</pre><p>
+ For implementation reasons, setting <code class="envar">LC_ALL</code> does not
+ work for this purpose; all the other locale-related environment
+ variables do work.
+ </p><p>
+ When testing against an existing installation, the locale is
+ determined by the existing database cluster and cannot be set
+ separately for the test run.
+ </p><p>
+ You can also choose the database encoding explicitly by setting
+ the variable <code class="envar">ENCODING</code>, for example:
+</p><pre class="screen">
+make check LANG=C ENCODING=EUC_JP
+</pre><p>
+ Setting the database encoding this way typically only makes sense
+ if the locale is C; otherwise the encoding is chosen automatically
+ from the locale, and specifying an encoding that does not match
+ the locale will result in an error.
+ </p><p>
+ The database encoding can be set for tests against either a temporary or
+ an existing installation, though in the latter case it must be
+ compatible with the installation's locale.
+ </p></div><div class="sect2" id="id-1.6.20.5.7"><div class="titlepage"><div><div><h3 class="title">33.1.5. Custom Server Settings</h3></div></div></div><p>
+ Custom server settings to use when running a regression test suite can be
+ set in the <code class="varname">PGOPTIONS</code> environment variable (for settings
+ that allow this):
+</p><pre class="screen">
+make check PGOPTIONS="-c force_parallel_mode=regress -c work_mem=50MB"
+</pre><p>
+ When running against a temporary installation, custom settings can also be
+ set by supplying a pre-written <code class="filename">postgresql.conf</code>:
+</p><pre class="screen">
+echo 'log_checkpoints = on' &gt; test_postgresql.conf
+echo 'work_mem = 50MB' &gt;&gt; test_postgresql.conf
+make check EXTRA_REGRESS_OPTS="--temp-config=test_postgresql.conf"
+</pre><p>
+ </p><p>
+ This can be useful to enable additional logging, adjust resource limits,
+ or enable extra run-time checks such as <a class="xref" href="runtime-config-developer.html#GUC-DEBUG-DISCARD-CACHES">debug_discard_caches</a>.
+ </p></div><div class="sect2" id="id-1.6.20.5.8"><div class="titlepage"><div><div><h3 class="title">33.1.6. Extra Tests</h3></div></div></div><p>
+ The core regression test suite contains a few test files that are not
+ run by default, because they might be platform-dependent or take a
+ very long time to run. You can run these or other extra test
+ files by setting the variable <code class="envar">EXTRA_TESTS</code>. For
+ example, to run the <code class="literal">numeric_big</code> test:
+</p><pre class="screen">
+make check EXTRA_TESTS=numeric_big
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress.html" title="Chapter 33. Regression Tests">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress-evaluation.html" title="33.2. Test Evaluation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 33. Regression Tests </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.2. Test Evaluation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress-tap.html b/doc/src/sgml/html/regress-tap.html
new file mode 100644
index 0000000..4640c5f
--- /dev/null
+++ b/doc/src/sgml/html/regress-tap.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.4. TAP Tests</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress-variant.html" title="33.3. Variant Comparison Files" /><link rel="next" href="regress-coverage.html" title="33.5. Test Coverage Examination" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.4. TAP Tests</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress-variant.html" title="33.3. Variant Comparison Files">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><th width="60%" align="center">Chapter 33. Regression Tests</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress-coverage.html" title="33.5. Test Coverage Examination">Next</a></td></tr></table><hr /></div><div class="sect1" id="REGRESS-TAP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.4. TAP Tests</h2></div></div></div><p>
+ Various tests, particularly the client program tests
+ under <code class="filename">src/bin</code>, use the Perl TAP tools and are run
+ using the Perl testing program <code class="command">prove</code>. You can pass
+ command-line options to <code class="command">prove</code> by setting
+ the <code class="command">make</code> variable <code class="varname">PROVE_FLAGS</code>, for example:
+</p><pre class="programlisting">
+make -C src/bin check PROVE_FLAGS='--timer'
+</pre><p>
+ See the manual page of <code class="command">prove</code> for more information.
+ </p><p>
+ The <code class="command">make</code> variable <code class="varname">PROVE_TESTS</code>
+ can be used to define a whitespace-separated list of paths relative
+ to the <code class="filename">Makefile</code> invoking <code class="command">prove</code>
+ to run the specified subset of tests instead of the default
+ <code class="filename">t/*.pl</code>. For example:
+</p><pre class="programlisting">
+make check PROVE_TESTS='t/001_test1.pl t/003_test3.pl'
+</pre><p>
+ </p><p>
+ The TAP tests require the Perl module <code class="literal">IPC::Run</code>.
+ This module is available from CPAN or an operating system package.
+ They also require <span class="productname">PostgreSQL</span> to be
+ configured with the option <code class="option">--enable-tap-tests</code>.
+ </p><p>
+ Generically speaking, the TAP tests will test the executables in a
+ previously-installed installation tree if you say <code class="literal">make
+ installcheck</code>, or will build a new local installation tree from
+ current sources if you say <code class="literal">make check</code>. In either
+ case they will initialize a local instance (data directory) and
+ transiently run a server in it. Some of these tests run more than one
+ server. Thus, these tests can be fairly resource-intensive.
+ </p><p>
+ It's important to realize that the TAP tests will start test server(s)
+ even when you say <code class="literal">make installcheck</code>; this is unlike
+ the traditional non-TAP testing infrastructure, which expects to use an
+ already-running test server in that case. Some PostgreSQL
+ subdirectories contain both traditional-style and TAP-style tests,
+ meaning that <code class="literal">make installcheck</code> will produce a mix of
+ results from temporary servers and the already-running test server.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress-variant.html" title="33.3. Variant Comparison Files">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress-coverage.html" title="33.5. Test Coverage Examination">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.3. Variant Comparison Files </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.5. Test Coverage Examination</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress-variant.html b/doc/src/sgml/html/regress-variant.html
new file mode 100644
index 0000000..6326d82
--- /dev/null
+++ b/doc/src/sgml/html/regress-variant.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.3. Variant Comparison Files</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="regress-evaluation.html" title="33.2. Test Evaluation" /><link rel="next" href="regress-tap.html" title="33.4. TAP Tests" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.3. Variant Comparison Files</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="regress-evaluation.html" title="33.2. Test Evaluation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><th width="60%" align="center">Chapter 33. Regression Tests</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress-tap.html" title="33.4. TAP Tests">Next</a></td></tr></table><hr /></div><div class="sect1" id="REGRESS-VARIANT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.3. Variant Comparison Files</h2></div></div></div><p>
+ Since some of the tests inherently produce environment-dependent
+ results, we have provided ways to specify alternate <span class="quote">“<span class="quote">expected</span>”</span>
+ result files. Each regression test can have several comparison files
+ showing possible results on different platforms. There are two
+ independent mechanisms for determining which comparison file is used
+ for each test.
+ </p><p>
+ The first mechanism allows comparison files to be selected for
+ specific platforms. There is a mapping file,
+ <code class="filename">src/test/regress/resultmap</code>, that defines
+ which comparison file to use for each platform.
+ To eliminate bogus test <span class="quote">“<span class="quote">failures</span>”</span> for a particular platform,
+ you first choose or make a variant result file, and then add a line to the
+ <code class="filename">resultmap</code> file.
+ </p><p>
+ Each line in the mapping file is of the form
+</p><pre class="synopsis">
+testname:output:platformpattern=comparisonfilename
+</pre><p>
+ The test name is just the name of the particular regression test
+ module. The output value indicates which output file to check. For the
+ standard regression tests, this is always <code class="literal">out</code>. The
+ value corresponds to the file extension of the output file.
+ The platform pattern is a pattern in the style of the Unix
+ tool <code class="command">expr</code> (that is, a regular expression with an implicit
+ <code class="literal">^</code> anchor at the start). It is matched against the
+ platform name as printed by <code class="command">config.guess</code>.
+ The comparison file name is the base name of the substitute result
+ comparison file.
+ </p><p>
+ For example: some systems lack a working <code class="literal">strtof</code> function,
+ for which our workaround causes rounding errors in the
+ <code class="filename">float4</code> regression test.
+ Therefore, we provide a variant comparison file,
+ <code class="filename">float4-misrounded-input.out</code>, which includes
+ the results to be expected on these systems. To silence the bogus
+ <span class="quote">“<span class="quote">failure</span>”</span> message on <span class="systemitem">HP-UX 10</span>
+ platforms, <code class="filename">resultmap</code> includes:
+</p><pre class="programlisting">
+float4:out:hppa.*-hp-hpux10.*=float4-misrounded-input.out
+</pre><p>
+ which will trigger on any machine where the output of
+ <code class="command">config.guess</code> matches <code class="literal">hppa.*-hp-hpux10.*</code>.
+ Other lines in <code class="filename">resultmap</code> select the variant comparison
+ file for other platforms where it's appropriate.
+ </p><p>
+ The second selection mechanism for variant comparison files is
+ much more automatic: it simply uses the <span class="quote">“<span class="quote">best match</span>”</span> among
+ several supplied comparison files. The regression test driver
+ script considers both the standard comparison file for a test,
+ <code class="literal"><em class="replaceable"><code>testname</code></em>.out</code>, and variant files named
+ <code class="literal"><em class="replaceable"><code>testname</code></em>_<em class="replaceable"><code>digit</code></em>.out</code>
+ (where the <em class="replaceable"><code>digit</code></em> is any single digit
+ <code class="literal">0</code>-<code class="literal">9</code>). If any such file is an exact match,
+ the test is considered to pass; otherwise, the one that generates
+ the shortest diff is used to create the failure report. (If
+ <code class="filename">resultmap</code> includes an entry for the particular
+ test, then the base <em class="replaceable"><code>testname</code></em> is the substitute
+ name given in <code class="filename">resultmap</code>.)
+ </p><p>
+ For example, for the <code class="literal">char</code> test, the comparison file
+ <code class="filename">char.out</code> contains results that are expected
+ in the <code class="literal">C</code> and <code class="literal">POSIX</code> locales, while
+ the file <code class="filename">char_1.out</code> contains results sorted as
+ they appear in many other locales.
+ </p><p>
+ The best-match mechanism was devised to cope with locale-dependent
+ results, but it can be used in any situation where the test results
+ cannot be predicted easily from the platform name alone. A limitation of
+ this mechanism is that the test driver cannot tell which variant is
+ actually <span class="quote">“<span class="quote">correct</span>”</span> for the current environment; it will just pick
+ the variant that seems to work best. Therefore it is safest to use this
+ mechanism only for variant results that you are willing to consider
+ equally valid in all contexts.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="regress-evaluation.html" title="33.2. Test Evaluation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="regress.html" title="Chapter 33. Regression Tests">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress-tap.html" title="33.4. TAP Tests">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.2. Test Evaluation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.4. TAP Tests</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/regress.html b/doc/src/sgml/html/regress.html
new file mode 100644
index 0000000..46292d6
--- /dev/null
+++ b/doc/src/sgml/html/regress.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 33. Regression Tests</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="jit-extensibility.html" title="32.4. Extensibility" /><link rel="next" href="regress-run.html" title="33.1. Running the Tests" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 33. Regression Tests</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="jit-extensibility.html" title="32.4. Extensibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="regress-run.html" title="33.1. Running the Tests">Next</a></td></tr></table><hr /></div><div class="chapter" id="REGRESS"><div class="titlepage"><div><div><h2 class="title">Chapter 33. Regression Tests</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="regress-run.html">33.1. Running the Tests</a></span></dt><dd><dl><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.3">33.1.1. Running the Tests Against a Temporary Installation</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.4">33.1.2. Running the Tests Against an Existing Installation</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.5">33.1.3. Additional Test Suites</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.6">33.1.4. Locale and Encoding</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.7">33.1.5. Custom Server Settings</a></span></dt><dt><span class="sect2"><a href="regress-run.html#id-1.6.20.5.8">33.1.6. Extra Tests</a></span></dt></dl></dd><dt><span class="sect1"><a href="regress-evaluation.html">33.2. Test Evaluation</a></span></dt><dd><dl><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.6">33.2.1. Error Message Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.7">33.2.2. Locale Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.8">33.2.3. Date and Time Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.9">33.2.4. Floating-Point Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.10">33.2.5. Row Ordering Differences</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.11">33.2.6. Insufficient Stack Depth</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.12">33.2.7. The <span class="quote">“<span class="quote">random</span>”</span> Test</a></span></dt><dt><span class="sect2"><a href="regress-evaluation.html#id-1.6.20.6.13">33.2.8. Configuration Parameters</a></span></dt></dl></dd><dt><span class="sect1"><a href="regress-variant.html">33.3. Variant Comparison Files</a></span></dt><dt><span class="sect1"><a href="regress-tap.html">33.4. TAP Tests</a></span></dt><dt><span class="sect1"><a href="regress-coverage.html">33.5. Test Coverage Examination</a></span></dt></dl></div><a id="id-1.6.20.2" class="indexterm"></a><a id="id-1.6.20.3" class="indexterm"></a><p>
+ The regression tests are a comprehensive set of tests for the SQL
+ implementation in <span class="productname">PostgreSQL</span>. They test
+ standard SQL operations as well as the extended capabilities of
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jit-extensibility.html" title="32.4. Extensibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="regress-run.html" title="33.1. Running the Tests">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.4. Extensibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.1. Running the Tests</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15-1.html b/doc/src/sgml/html/release-15-1.html
new file mode 100644
index 0000000..48c6ab2
--- /dev/null
+++ b/doc/src/sgml/html/release-15-1.html
@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.5. Release 15.1</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15-2.html" title="E.4. Release 15.2" /><link rel="next" href="release-15.html" title="E.6. Release 15" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.5. Release 15.1</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15-2.html" title="E.4. Release 15.2">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15.html" title="E.6. Release 15">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15-1"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.5. Release 15.1</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15-1.html#id-1.11.6.9.4">E.5.1. Migration to Version 15.1</a></span></dt><dt><span class="sect2"><a href="release-15-1.html#id-1.11.6.9.5">E.5.2. Changes</a></span></dt></dl></div><p><strong>Release date: </strong>2022-11-10</p><p>
+ This release contains a variety of fixes from 15.0.
+ For information about new features in major release 15, see
+ <a class="xref" href="release-15.html" title="E.6. Release 15">Section E.6</a>.
+ </p><div class="sect2" id="id-1.11.6.9.4"><div class="titlepage"><div><div><h3 class="title">E.5.1. Migration to Version 15.1</h3></div></div></div><p>
+ A dump/restore is not required for those running 15.X.
+ </p><p>
+ However, if you regularly create and drop tables exceeding 1GB,
+ see the first changelog entry below.
+ </p></div><div class="sect2" id="id-1.11.6.9.5"><div class="titlepage"><div><div><h3 class="title">E.5.2. Changes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Fix failure to remove non-first segments of large tables
+ (Tom Lane)
+ </p><p>
+ <span class="productname">PostgreSQL</span> splits large tables into
+ multiple files (normally with 1GB per file). The logic for dropping
+ a table was broken and would miss removing all but the first such
+ file, in two cases: drops of temporary tables and WAL replay of
+ drops of regular tables. Applications that routinely create
+ multi-gigabyte temporary tables could suffer significant disk space
+ leakage.
+ </p><p>
+ Orphaned temporary-table files are removed during postmaster start,
+ so the mere act of updating to 15.1 is sufficient to clear any
+ leaked temporary-table storage. However, if you suffered any
+ database crashes while using 15.0, and there might have been
+ large tables dropped just before such crashes, it's advisable
+ to check the database directories for files named according to the
+ pattern
+ <code class="literal"><em class="replaceable"><code>NNNN</code></em>.<em class="replaceable"><code>NN</code></em></code>.
+ If there is no matching file named
+ just <code class="literal"><em class="replaceable"><code>NNNN</code></em></code> (without
+ the <code class="literal">.<em class="replaceable"><code>NN</code></em></code> suffix), these
+ files should be removed manually.
+ </p></li><li class="listitem"><p>
+ Fix handling of <code class="literal">DEFAULT</code> tokens that appear
+ in a multi-row <code class="literal">VALUES</code> clause of an
+ <code class="command">INSERT</code> on an updatable view (Tom Lane)
+ </p><p>
+ This oversight could lead to <span class="quote">“<span class="quote">cache lookup failed for
+ type</span>”</span> errors, or in older branches even to crashes.
+ </p></li><li class="listitem"><p>
+ Disallow rules named <code class="literal">_RETURN</code> that are
+ not <code class="literal">ON SELECT</code> (Tom Lane)
+ </p><p>
+ This avoids confusion between a view's <code class="literal">ON SELECT</code>
+ rule and any other rules it may have.
+ </p></li><li class="listitem"><p>
+ Avoid failure in <code class="command">EXPLAIN VERBOSE</code> for a query
+ using <code class="literal">SEARCH BREADTH FIRST</code> with constant
+ initial values (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Prevent use of <code class="command">MERGE</code> on a partitioned table with
+ foreign-table partitions (Álvaro Herrera)
+ </p><p>
+ The case isn't supported, and previously threw an incomprehensible
+ error.
+ </p></li><li class="listitem"><p>
+ Fix construction of per-partition foreign key constraints while
+ doing <code class="command">ALTER TABLE ATTACH PARTITION</code>
+ (Jehan-Guillaume de Rorthais, Álvaro Herrera)
+ </p><p>
+ Previously, incorrect or duplicate constraints could be constructed
+ for the newly-added partition.
+ </p></li><li class="listitem"><p>
+ Fix planner failure with extended statistics on partitioned or
+ inherited tables (Richard Guo, Justin Pryzby)
+ </p><p>
+ Some cases failed with <span class="quote">“<span class="quote">cache lookup failed for statistics
+ object</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Fix mis-ordering of WAL operations in fast insert path for GIN
+ indexes (Matthias van de Meent, Zhang Mingli)
+ </p><p>
+ This mistake is not known to have any negative consequences within
+ core <span class="productname">PostgreSQL</span>, but it did cause issues
+ for some extensions.
+ </p></li><li class="listitem"><p>
+ Fix bugs in logical decoding when replay starts from a point
+ between the beginning of a transaction and the beginning of its
+ subtransaction (Masahiko Sawada, Kuroda Hayato)
+ </p><p>
+ These errors could lead to assertion failures in debug builds, and
+ otherwise to memory leaks.
+ </p></li><li class="listitem"><p>
+ Accept interrupts in more places during logical decoding (Amit
+ Kapila, Masahiko Sawada)
+ </p><p>
+ This ameliorates problems with slow shutdown of replication workers.
+ </p></li><li class="listitem"><p>
+ Prevent attempts to replicate into a foreign-table partition in
+ replication workers (Shi Yu, Tom Lane)
+ </p><p>
+ Although partitioned tables can have foreign tables as partitions,
+ replicating into such a partition isn't currently supported.
+ The logical replication worker process would crash if it was
+ attempted. Now, an error is thrown.
+ </p></li><li class="listitem"><p>
+ Avoid crash after function syntax error in replication workers
+ (Maxim Orlov, Anton Melnikov, Masahiko Sawada, Tom Lane)
+ </p><p>
+ If a syntax error occurred in a SQL-language or PL/pgSQL-language
+ <code class="command">CREATE FUNCTION</code> or <code class="command">DO</code> command
+ executed in a logical replication worker, the worker process would
+ crash with a null pointer dereference or assertion failure.
+ </p></li><li class="listitem"><p>
+ Avoid double call of the shutdown callback of an archiver module
+ (Nathan Bossart, Bharath Rupireddy)
+ </p></li><li class="listitem"><p>
+ Add plan-time check for attempted access to a table that has no
+ table access method (Tom Lane)
+ </p><p>
+ This prevents a crash in some catalog-corruption scenarios, for
+ example use of a view whose <code class="literal">ON SELECT</code> rule is
+ missing.
+ </p></li><li class="listitem"><p>
+ Prevent postmaster crash when shared-memory state is corrupted
+ (Tom Lane)
+ </p><p>
+ The postmaster process is supposed to survive and initiate a
+ database restart if shared memory becomes corrupted, but one
+ bit of code was being insufficiently cautious about that.
+ </p></li><li class="listitem"><p>
+ In <span class="application">libpq</span>, handle single-row mode
+ correctly when pipelining (Denis Laxalde)
+ </p><p>
+ The single-row flag was not reset at the correct time if pipeline
+ mode was also active.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">psql</span>'s exit status when a
+ command-line query is canceled (Peter Eisentraut)
+ </p><p>
+ <code class="literal">psql -c <em class="replaceable"><code>query</code></em></code> would
+ exit successfully if the query was canceled. Fix it to exit with
+ nonzero status, as in other error cases.
+ </p></li><li class="listitem"><p>
+ Allow cross-platform tablespace relocation
+ in <span class="application">pg_basebackup</span> (Robert Haas)
+ </p><p>
+ Allow the remote path in <code class="option">--tablespace-mapping</code> to be
+ either a Unix-style or Windows-style absolute path, since the source
+ server could be on a different OS than the local system.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pg_dump</span>'s failure to dump comments
+ attached to some <code class="literal">CHECK</code> constraints (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">CREATE DATABASE</code> to allow
+ its <code class="literal">oid</code> parameter to exceed
+ 2<sup>31</sup> (Tom Lane)
+ </p><p>
+ This oversight prevented <span class="application">pg_upgrade</span> from
+ succeeding when the source installation contained databases with
+ OIDs larger than that.
+ </p></li><li class="listitem"><p>
+ In <span class="application">pg_stat_statements</span>, fix access to
+ already-freed memory (zhaoqigui)
+ </p><p>
+ This occurred if <span class="application">pg_stat_statements</span>
+ tracked a <code class="command">ROLLBACK</code> command issued via extended
+ query protocol. In debug builds it consistently led to an assertion
+ failure. In production builds there would often be no visible ill
+ effect; but if the freed memory had already been reused, the likely
+ result would be to store garbage for the query string.
+ </p></li><li class="listitem"><p>
+ Fix incompatibilities with LLVM 15 (Thomas Munro, Andres Freund)
+ </p></li><li class="listitem"><p>
+ Allow use of <code class="function">__sync_lock_test_and_set()</code> for
+ spinlocks on any machine (Tom Lane)
+ </p><p>
+ This eases porting to new machine architectures, at least if you're
+ using a compiler that supports this GCC builtin function.
+ </p></li><li class="listitem"><p>
+ Rename symbol <code class="literal">REF</code> to <code class="literal">REF_P</code> to
+ avoid compile failure on recent macOS (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Avoid using <code class="function">sprintf</code>, to avoid compile-time
+ deprecation warnings (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Update time zone data files to <span class="application">tzdata</span>
+ release 2022f for DST law changes in Chile, Fiji, Iran, Jordan,
+ Mexico, Palestine, and Syria, plus historical corrections for Chile,
+ Crimea, Iran, and Mexico.
+ </p><p>
+ Also, the Europe/Kiev zone has been renamed to Europe/Kyiv.
+ Also, the following zones have been merged into nearby,
+ more-populous zones whose clocks have agreed with them since 1970:
+ Antarctica/Vostok, Asia/Brunei,
+ Asia/Kuala_Lumpur, Atlantic/Reykjavik, Europe/Amsterdam,
+ Europe/Copenhagen, Europe/Luxembourg, Europe/Monaco, Europe/Oslo,
+ Europe/Stockholm, Indian/Christmas, Indian/Cocos, Indian/Kerguelen,
+ Indian/Mahe, Indian/Reunion, Pacific/Chuuk, Pacific/Funafuti,
+ Pacific/Majuro, Pacific/Pohnpei, Pacific/Wake and Pacific/Wallis.
+ (This indirectly affects zones that were already links to one of
+ these: Arctic/Longyearbyen, Atlantic/Jan_Mayen, Iceland,
+ Pacific/Ponape, Pacific/Truk, and Pacific/Yap.) America/Nipigon,
+ America/Rainy_River, America/Thunder_Bay, Europe/Uzhgorod, and
+ Europe/Zaporozhye were also merged into nearby zones after
+ discovering that their claimed post-1970 differences from those
+ zones seem to have been errors.
+ In all these cases, the previous zone name remains as an alias;
+ but the actual data is that of the zone that was merged into.
+ </p><p>
+ These zone mergers result in loss of pre-1970 timezone history for
+ the merged zones, which may be troublesome for applications
+ expecting consistency of <code class="type">timestamptz</code> display. As an
+ example, the stored value <code class="literal">1944-06-01 12:00 UTC</code>
+ would previously display as <code class="literal">1944-06-01
+ 13:00:00+01</code> if the Europe/Stockholm zone is selected, but
+ now it will read out as <code class="literal">1944-06-01 14:00:00+02</code>.
+ </p><p>
+ It is possible to build the time zone data files with options that
+ will restore the older zone data, but that choice also inserts a lot
+ of other old (and typically poorly-attested) zone data, resulting in
+ more total changes from the previous release than accepting these
+ upstream changes does. <span class="productname">PostgreSQL</span> has
+ chosen to ship the <span class="productname">tzdb</span> data
+ as-recommended, and so far as we are aware most major operating
+ system distributions are doing likewise. However, if these changes
+ cause significant problems for your application, a possible solution
+ is to install a local build of the time zone data files using
+ <span class="productname">tzdb</span>'s backwards-compatibility options
+ (see their <code class="literal">PACKRATDATA</code>
+ and <code class="literal">PACKRATLIST</code> options).
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15-2.html" title="E.4. Release 15.2">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15.html" title="E.6. Release 15">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.4. Release 15.2 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.6. Release 15</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15-2.html b/doc/src/sgml/html/release-15-2.html
new file mode 100644
index 0000000..4d61e7e
--- /dev/null
+++ b/doc/src/sgml/html/release-15-2.html
@@ -0,0 +1,433 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.4. Release 15.2</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15-3.html" title="E.3. Release 15.3" /><link rel="next" href="release-15-1.html" title="E.5. Release 15.1" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.4. Release 15.2</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15-3.html" title="E.3. Release 15.3">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15-1.html" title="E.5. Release 15.1">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15-2"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.4. Release 15.2</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15-2.html#id-1.11.6.8.4">E.4.1. Migration to Version 15.2</a></span></dt><dt><span class="sect2"><a href="release-15-2.html#id-1.11.6.8.5">E.4.2. Changes</a></span></dt></dl></div><p><strong>Release date: </strong>2023-02-09</p><p>
+ This release contains a variety of fixes from 15.1.
+ For information about new features in major release 15, see
+ <a class="xref" href="release-15.html" title="E.6. Release 15">Section E.6</a>.
+ </p><div class="sect2" id="id-1.11.6.8.4"><div class="titlepage"><div><div><h3 class="title">E.4.1. Migration to Version 15.2</h3></div></div></div><p>
+ A dump/restore is not required for those running 15.X.
+ </p><p>
+ However, if you are upgrading from a version earlier than 15.1,
+ see <a class="xref" href="release-15-1.html" title="E.5. Release 15.1">Section E.5</a>.
+ </p></div><div class="sect2" id="id-1.11.6.8.5"><div class="titlepage"><div><div><h3 class="title">E.4.2. Changes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <span class="application">libpq</span> can leak memory contents after
+ GSSAPI transport encryption initiation fails (Jacob Champion)
+ </p><p>
+ A modified server, or an unauthenticated man-in-the-middle, can
+ send a not-zero-terminated error message during setup of GSSAPI
+ (Kerberos) transport encryption. <span class="application">libpq</span>
+ will then copy that string, as well as following bytes in
+ application memory up to the next zero byte, to its error report.
+ Depending on what the calling application does with the error
+ report, this could result in disclosure of application memory
+ contents. There is also a small probability of a crash due to
+ reading beyond the end of memory. Fix by properly zero-terminating
+ the server message.
+ (CVE-2022-41862)
+ </p></li><li class="listitem"><p>
+ Fix calculation of which <code class="literal">GENERATED</code> columns need
+ to be updated in child tables during an <code class="command">UPDATE</code> on
+ a partitioned table or inheritance tree (Amit Langote, Tom Lane)
+ </p><p>
+ This fixes failure to update <code class="literal">GENERATED</code> columns
+ that do not exist in the parent table, or that have different
+ dependencies than are in the parent column's generation expression.
+ </p></li><li class="listitem"><p>
+ Fix possible failure of <code class="command">MERGE</code> to compute
+ <code class="literal">GENERATED</code> columns (Dean Rasheed)
+ </p><p>
+ When the first row-level action of the <code class="command">MERGE</code> was
+ an <code class="literal">UPDATE</code>, any
+ subsequent <code class="literal">INSERT</code> actions would fail to
+ compute <code class="literal">GENERATED</code> columns that were deemed
+ unnecessary to compute for the <code class="literal">UPDATE</code> action
+ (due to not depending on any of the <code class="literal">UPDATE</code> target
+ columns).
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">MERGE</code>'s check for
+ unreachable <code class="literal">WHEN</code> clauses (Dean Rasheed)
+ </p><p>
+ A <code class="literal">WHEN</code> clause following an
+ unconditional <code class="literal">WHEN</code> clause should be rejected as
+ unreachable, but this case was not always detected.
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">MERGE</code>'s rule-detection test (Dean Rasheed)
+ </p><p>
+ <code class="command">MERGE</code> is not supported on tables with rules;
+ but it also failed on tables that once had rules but no longer do.
+ </p></li><li class="listitem"><p>
+ In <code class="command">MERGE</code>, don't count a <code class="literal">DO
+ NOTHING</code> action as a processed tuple (Álvaro Herrera)
+ </p><p>
+ This makes the code's behavior match the documentation.
+ </p></li><li class="listitem"><p>
+ Allow a <code class="literal">WITH RECURSIVE ... CYCLE</code> CTE
+ to access its output column (Tom Lane)
+ </p><p>
+ A reference to the <code class="literal">SET</code> column from within the CTE
+ would fail with <span class="quote">“<span class="quote">cache lookup failed for type 0</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Fix handling of pending inserts when doing a bulk insertion to a
+ foreign table (Etsuro Fujita)
+ </p><p>
+ In some cases pending insertions were not flushed to the FDW soon
+ enough, leading to logical inconsistencies, for
+ example <code class="literal">BEFORE ROW</code> triggers not seeing rows they
+ should be able to see.
+ </p></li><li class="listitem"><p>
+ Allow <code class="literal">REPLICA IDENTITY</code>
+ to be set on an index that's not (yet) valid (Tom Lane)
+ </p><p>
+ When <span class="application">pg_dump</span> dumps a partitioned index
+ that's marked <code class="literal">REPLICA IDENTITY</code>, it generates a
+ command sequence that applies <code class="literal">REPLICA IDENTITY</code>
+ before the partitioned index has been marked valid, causing restore
+ to fail. There seems no very good reason to prohibit doing it in
+ that order, so allow it. The marking will have no effect anyway
+ until the index becomes valid.
+ </p></li><li class="listitem"><p>
+ Fix handling of <code class="literal">DEFAULT</code> markers in rules that
+ perform an <code class="command">INSERT</code> from a
+ multi-row <code class="literal">VALUES</code> list (Dean Rasheed)
+ </p><p>
+ In some cases a <code class="literal">DEFAULT</code> marker would not get
+ replaced with the proper default-value expression, leading to
+ an <span class="quote">“<span class="quote">unrecognized node type</span>”</span> error.
+ </p></li><li class="listitem"><p>
+ Reject uses of undefined variables in <code class="type">jsonpath</code>
+ existence checks (Alexander Korotkov, David G. Johnston)
+ </p><p>
+ While <code class="type">jsonpath</code> match operators threw an error for an
+ undefined variable in the path pattern, the existence operators
+ silently treated it as a match.
+ </p></li><li class="listitem"><p>
+ Fix <code class="type">jsonb</code> subscripting to cope with toasted subscript
+ values (Tom Lane, David G. Johnston)
+ </p><p>
+ Using a text value fetched directly from a table as
+ a <code class="type">jsonb</code> subscript was likely to fail.
+ Fetches would usually not find any matching element.
+ Assignments could store the value with a garbage key,
+ although keys long enough to cause that problem are probably rare in
+ the field.
+ </p></li><li class="listitem"><p>
+ Fix edge-case data corruption in parallel hash joins (Dmitry Astapov)
+ </p><p>
+ If the final chunk of a large tuple being written out to a temporary
+ file was exactly 32760 bytes, it would be corrupted due to a
+ fencepost bug. The query would typically fail later with
+ corrupted-data symptoms.
+ </p></li><li class="listitem"><p>
+ Honor non-default settings
+ of <code class="varname">checkpoint_completion_target</code>
+ (Bharath Rupireddy)
+ </p><p>
+ Internal state was not updated after a change
+ in <code class="varname">checkpoint_completion_target</code>, possibly
+ resulting in performing checkpoint I/O faster or slower than
+ desired, especially if that setting was changed on-the-fly.
+ </p></li><li class="listitem"><p>
+ Log the correct ending timestamp
+ in <code class="varname">recovery_target_xid</code> mode (Tom Lane)
+ </p><p>
+ When ending recovery based on the <code class="varname">recovery_target_xid</code>
+ setting with <code class="varname">recovery_target_inclusive</code>
+ = <code class="literal">off</code>, we printed an incorrect timestamp (always
+ 2000-01-01) in the <span class="quote">“<span class="quote">recovery stopping before
+ ... transaction</span>”</span> log message.
+ </p></li><li class="listitem"><p>
+ Improve error reporting for some buffered file read failures
+ (Peter Eisentraut)
+ </p><p>
+ Correctly report a short read, giving the numbers of bytes desired
+ and actually read, instead of reporting an irrelevant error code.
+ Most places got this right already, but some recently-written
+ replication logic did not.
+ </p></li><li class="listitem"><p>
+ Remove arbitrary limit on number of elements
+ in <code class="type">int2vector</code> and <code class="type">oidvector</code> (Tom Lane)
+ </p><p>
+ The input functions for these types previously rejected more than
+ 100 elements. With the introduction of the logical replication
+ column list feature, it's necessary to
+ accept <code class="type">int2vector</code>s having up to 1600 columns,
+ otherwise long column lists cause logical-replication failures.
+ </p></li><li class="listitem"><p>
+ In extended query protocol, avoid an immediate commit
+ after <code class="command">ANALYZE</code> if we're running a pipeline
+ (Tom Lane)
+ </p><p>
+ If there's not been an explicit <code class="command">BEGIN
+ TRANSACTION</code>, <code class="command">ANALYZE</code> would take it on
+ itself to commit, which should not happen within a pipelined series
+ of commands.
+ </p></li><li class="listitem"><p>
+ Reject cancel request packets having the wrong length
+ (Andrey Borodin)
+ </p><p>
+ The server would process a cancel request even if its length word
+ was too small. This led to reading beyond the end of the allocated
+ buffer. In theory that could cause a segfault, but it seems quite
+ unlikely to happen in practice, since the buffer would have to be
+ very close to the end of memory. The more likely outcome was a bogus
+ log message about wrong backend PID or cancel code. Complain about
+ the wrong length, instead.
+ </p></li><li class="listitem"><p>
+ Fix planner preprocessing oversights for window function run-condition
+ expressions (Richard Guo, David Rowley)
+ </p><p>
+ This could lead to planner errors such as <span class="quote">“<span class="quote">WindowFunc not
+ found in subplan target lists</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Fix possible dangling-pointer access during execution of window
+ function run-condition expressions (David Rowley)
+ </p><p>
+ In practice, because the run-condition optimization is only applied
+ to certain window functions that happen to all
+ return <code class="type">int8</code>, this only manifested as a problem on
+ 32-bit builds.
+ </p></li><li class="listitem"><p>
+ Add recursion and looping defenses in subquery pullup (Tom Lane)
+ </p><p>
+ A contrived query can result in deep recursion and unreasonable
+ amounts of time spent trying to flatten subqueries. A proper fix
+ for that seems unduly invasive for a back-patch, but we can at least
+ add stack depth checks and an interrupt check to allow the query to
+ be cancelled.
+ </p></li><li class="listitem"><p>
+ Fix planner issues when combining Memoize nodes with partitionwise
+ joins or parameterized nestloops (Richard Guo)
+ </p><p>
+ These errors could lead to not using Memoize in contexts where it
+ would be useful, or possibly to wrong query plans.
+ </p></li><li class="listitem"><p>
+ Fix partitionwise-join code to tolerate failure to produce a plan for
+ each partition (Tom Lane)
+ </p><p>
+ This could result in <span class="quote">“<span class="quote">could not devise a query plan for the
+ given query</span>”</span> errors.
+ </p></li><li class="listitem"><p>
+ Limit the amount of cleanup work done
+ by <code class="function">get_actual_variable_range</code> (Simon Riggs)
+ </p><p>
+ Planner runs occurring just after deletion of a large number of
+ tuples appearing at the end of an index could expend significant
+ amounts of work setting the <span class="quote">“<span class="quote">killed</span>”</span> bits for those
+ index entries. Limit the amount of work done in any one query by
+ giving up on this process after examining 100 heap pages. All the
+ cleanup will still happen eventually, but without so large a
+ performance hiccup.
+ </p></li><li class="listitem"><p>
+ Prevent the statistics machinery from getting confused when a
+ relation's relkind changes (Andres Freund)
+ </p><p>
+ Converting a table to a view could lead to crashes or assertion
+ failures.
+ </p></li><li class="listitem"><p>
+ Fix under-parenthesized display of <code class="literal">AT TIME ZONE</code>
+ constructs (Tom Lane)
+ </p><p>
+ This could result in dump/restore failures for rules or views in
+ which an argument of <code class="literal">AT TIME ZONE</code> is itself an
+ expression.
+ </p></li><li class="listitem"><p>
+ Prevent clobbering of cached parsetrees for utility statements in
+ SQL functions (Tom Lane, Daniel Gustafsson)
+ </p><p>
+ If a SQL-language function executes the same utility command more
+ than once within a single calling query, it could crash or report
+ strange errors such as <span class="quote">“<span class="quote">unrecognized node type</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Ensure that execution of full-text-search queries can be cancelled
+ while they are performing phrase matches (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix memory leak in hashing strings with nondeterministic collations
+ (Jeff Davis)
+ </p></li><li class="listitem"><p>
+ Fix deadlock between <code class="command">DROP DATABASE</code> and logical
+ replication worker process (Hou Zhijie)
+ </p><p>
+ This was caused by an ill-advised choice to block interrupts while
+ creating a logical replication slot in the worker. In version 15
+ that could lead to an undetected deadlock. In version 14, no
+ deadlock has been observed, but it's still a bad idea to block
+ interrupts while waiting for network I/O.
+ </p></li><li class="listitem"><p>
+ Clean up the <span class="application">libpq</span> connection object
+ after a failed replication connection attempt (Andres Freund)
+ </p><p>
+ The previous coding leaked the connection object. In background
+ code paths that's pretty harmless because the calling process will
+ give up and exit. But in commands such as <code class="command">CREATE
+ SUBSCRIPTION</code>, such a failure resulted in a small
+ session-lifespan memory leak.
+ </p></li><li class="listitem"><p>
+ In hot-standby servers, reduce processing effort for tracking XIDs
+ known to be active on the primary (Simon Riggs, Michail Nikolaev)
+ </p><p>
+ Insufficiently-aggressive cleanup of the KnownAssignedXids array
+ could lead to poor performance, particularly
+ when <code class="varname">max_connections</code> is set to a large value on
+ the standby.
+ </p></li><li class="listitem"><p>
+ Ignore invalidated logical-replication slots while determining
+ oldest catalog xmin (Sirisha Chamarthi)
+ </p><p>
+ A replication slot could prevent cleanup of dead tuples in the
+ system catalogs even after it becomes invalidated due to
+ exceeding <code class="varname">max_slot_wal_keep_size</code>. Thus, failure
+ of a replication consumer could lead to indefinitely-large catalog
+ bloat.
+ </p></li><li class="listitem"><p>
+ In logical decoding, notify the remote node when a transaction is
+ detected to have crashed (Hou Zhijie)
+ </p><p>
+ After a server restart, we'll re-stream the changes for transactions
+ occurring shortly before the restart. Some of these transactions
+ probably never completed; when we realize that one didn't we throw
+ away the relevant decoding state locally, but we neglected to tell
+ the subscriber about it. That led to the subscriber keeping useless
+ streaming files until it's next restarted.
+ </p></li><li class="listitem"><p>
+ Fix uninitialized-memory usage in logical decoding (Masahiko Sawada)
+ </p><p>
+ In certain cases, resumption of logical decoding could try to re-use
+ XID data that had already been freed, leading to unpredictable
+ behavior.
+ </p></li><li class="listitem"><p>
+ Acquire spinlock while updating shared state during logical decoding
+ context creation (Masahiko Sawada)
+ </p><p>
+ We neglected to acquire the appropriate lock while updating data
+ about two-phase transactions, potentially allowing other processes
+ to see inconsistent data.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pgoutput</span> replication plug-in to not
+ send columns not listed in a table's replication column list
+ (Hou Zhijie)
+ </p><p>
+ <code class="literal">UPDATE</code> and <code class="literal">DELETE</code> events did
+ not pay attention to the configured column list, thus sending more
+ data than expected. This did not cause a problem when the receiver
+ is our built-in logical replication code, but it might confuse other
+ receivers, and in any case it wasted network bandwidth.
+ </p></li><li class="listitem"><p>
+ Avoid rare <span class="quote">“<span class="quote">failed to acquire cleanup lock</span>”</span> panic
+ during WAL replay of hash-index page split operations (Robert Haas)
+ </p></li><li class="listitem"><p>
+ Advance a heap page's LSN when setting its all-visible bit during
+ WAL replay (Jeff Davis)
+ </p><p>
+ Failure to do this left the page possibly different on standby
+ servers than the primary, and violated some other expectations about
+ when the LSN changes. This seems only a theoretical hazard so
+ far as <span class="productname">PostgreSQL</span> itself is concerned,
+ but it could upset third-party tools.
+ </p></li><li class="listitem"><p>
+ Fix <code class="function">int64_div_fast_to_numeric()</code> to work for a
+ wider range of inputs (Dean Rasheed)
+ </p><p>
+ This function misbehaved with some values of its second argument.
+ No such usages exist in core <span class="productname">PostgreSQL</span>,
+ but it's clearly a hazard for external modules, so repair.
+ </p></li><li class="listitem"><p>
+ Fix latent buffer-overrun problem in <code class="literal">WaitEventSet</code>
+ logic (Thomas Munro)
+ </p><p>
+ The <code class="function">epoll</code>-based
+ and <code class="function">kqueue</code>-based implementations could ask the
+ kernel for too many events if the size of their internal buffer was
+ different from the size of the caller's output buffer. That case is
+ not known to occur in released <span class="productname">PostgreSQL</span>
+ versions, but this error is a hazard for external modules and future
+ bug fixes.
+ </p></li><li class="listitem"><p>
+ Avoid nominally-undefined behavior when accessing shared memory in
+ 32-bit builds (Andres Freund)
+ </p><p>
+ clang's undefined-behavior sanitizer complained about use of a
+ pointer that was less aligned than it should be. It's very unlikely
+ that this would cause a problem in non-debug builds, but it's worth
+ fixing for testing purposes.
+ </p></li><li class="listitem"><p>
+ Fix assertion failure in BRIN minmax-multi opclasses (Tomas Vondra)
+ </p><p>
+ The assertion was overly strict, so this mistake was harmless in
+ non-assert builds.
+ </p></li><li class="listitem"><p>
+ Remove faulty assertion in useless-RESULT-RTE optimization logic
+ (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix copy-and-paste errors in cache-lookup-failure messages for ACL
+ checks (Justin Pryzby)
+ </p><p>
+ In principle these errors should never be reached. But if they are,
+ some of them reported the wrong type of object.
+ </p></li><li class="listitem"><p>
+ Fix possible corruption of very large tablespace map files
+ in <span class="application">pg_basebackup</span> (Antonin Houska)
+ </p></li><li class="listitem"><p>
+ Avoid harmless warning from <span class="application">pg_dump</span>
+ in <code class="option">--if-exists</code> mode (Tom Lane)
+ </p><p>
+ If the <code class="literal">public</code> schema has a non-default owner then
+ use of <span class="application">pg_dump</span>'s <code class="option">--if-exists</code>
+ option resulted in a warning message <span class="quote">“<span class="quote">warning: could not find
+ where to insert IF EXISTS in statement "-- *not* dropping schema,
+ since initdb creates it"</span>”</span>. The dump output was okay, though.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">psql</span>'s <code class="literal">\sf</code>
+ and <code class="literal">\ef</code> commands to handle SQL-language functions
+ that have <acronym class="acronym">SQL</acronym>-standard function bodies (Tom Lane)
+ </p><p>
+ These commands misidentified the start of the function body when it
+ used new-style syntax.
+ </p></li><li class="listitem"><p>
+ Fix tab completion of <code class="command">ALTER
+ FUNCTION/PROCEDURE/ROUTINE</code> ... <code class="command">SET
+ SCHEMA</code> (Dean Rasheed)
+ </p></li><li class="listitem"><p>
+ Update <code class="filename">contrib/pageinspect</code> to mark its
+ disk-accessing functions as <code class="literal">PARALLEL RESTRICTED</code>
+ (Tom Lane)
+ </p><p>
+ This avoids possible failure if one of these functions is used to
+ examine a temporary table, since a session's temporary tables are not
+ accessible from parallel workers.
+ </p></li><li class="listitem"><p>
+ Fix <code class="filename">contrib/seg</code> to not crash or print garbage
+ if an input number has more than 127 digits (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix build on Microsoft Visual Studio 2013 (Tom Lane)
+ </p><p>
+ A previous patch supposed that all platforms of interest
+ have <code class="function">snprintf()</code>, but MSVC 2013 isn't quite
+ there yet. Revert to using <code class="function">sprintf()</code> on that
+ platform.
+ </p></li><li class="listitem"><p>
+ Fix compile failure in building PL/Perl with MSVC when using
+ Strawberry Perl (Andrew Dunstan)
+ </p></li><li class="listitem"><p>
+ Fix mismatch of PL/Perl built with MSVC versus a Perl library built
+ with gcc (Andrew Dunstan)
+ </p><p>
+ Such combinations could previously fail with <span class="quote">“<span class="quote">loadable library
+ and perl binaries are mismatched</span>”</span> errors.
+ </p></li><li class="listitem"><p>
+ Suppress compiler warnings from Perl's header files (Andres Freund)
+ </p><p>
+ Our preferred compiler options provoke warnings about constructs
+ appearing in recent versions of Perl's header files. When using
+ <span class="application">gcc</span>, we can suppress these warnings with
+ a pragma.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pg_waldump</span> to build on compilers that
+ don't discard unused static-inline functions (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Update time zone data files to <span class="application">tzdata</span>
+ release 2022g for DST law changes in Greenland and Mexico,
+ plus historical corrections for northern Canada, Colombia, and
+ Singapore.
+ </p><p>
+ Notably, a new timezone America/Ciudad_Juarez has been split off
+ from America/Ojinaga.
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15-3.html" title="E.3. Release 15.3">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15-1.html" title="E.5. Release 15.1">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.3. Release 15.3 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.5. Release 15.1</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15-3.html b/doc/src/sgml/html/release-15-3.html
new file mode 100644
index 0000000..ee11279
--- /dev/null
+++ b/doc/src/sgml/html/release-15-3.html
@@ -0,0 +1,603 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.3. Release 15.3</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15-4.html" title="E.2. Release 15.4" /><link rel="next" href="release-15-2.html" title="E.4. Release 15.2" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.3. Release 15.3</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15-4.html" title="E.2. Release 15.4">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15-2.html" title="E.4. Release 15.2">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15-3"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.3. Release 15.3</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15-3.html#id-1.11.6.7.4">E.3.1. Migration to Version 15.3</a></span></dt><dt><span class="sect2"><a href="release-15-3.html#id-1.11.6.7.5">E.3.2. Changes</a></span></dt></dl></div><p><strong>Release date: </strong>2023-05-11</p><p>
+ This release contains a variety of fixes from 15.2.
+ For information about new features in major release 15, see
+ <a class="xref" href="release-15.html" title="E.6. Release 15">Section E.6</a>.
+ </p><div class="sect2" id="id-1.11.6.7.4"><div class="titlepage"><div><div><h3 class="title">E.3.1. Migration to Version 15.3</h3></div></div></div><p>
+ A dump/restore is not required for those running 15.X.
+ </p><p>
+ However, if you are upgrading from a version earlier than 15.1,
+ see <a class="xref" href="release-15-1.html" title="E.5. Release 15.1">Section E.5</a>.
+ </p></div><div class="sect2" id="id-1.11.6.7.5"><div class="titlepage"><div><div><h3 class="title">E.3.2. Changes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Prevent <code class="command">CREATE SCHEMA</code> from defeating changes
+ in <code class="varname">search_path</code> (Alexander Lakhin)
+ </p><p>
+ Within a <code class="command">CREATE SCHEMA</code> command, objects in the
+ prevailing <code class="varname">search_path</code>, as well as those in the
+ newly-created schema, would be visible even within a called
+ function or script that attempted to set a
+ secure <code class="varname">search_path</code>. This could allow any user
+ having permission to create a schema to hijack the privileges of a
+ security definer function or extension script.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks
+ Alexander Lakhin for reporting this problem.
+ (CVE-2023-2454)
+ </p></li><li class="listitem"><p>
+ Enforce row-level security policies correctly after inlining a
+ set-returning function (Stephen Frost, Tom Lane)
+ </p><p>
+ If a set-returning SQL-language function refers to a table having
+ row-level security policies, and it can be inlined into a calling
+ query, those RLS policies would not get enforced properly in some
+ cases involving re-using a cached plan under a different role.
+ This could allow a user to see or modify rows that should have been
+ invisible.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks
+ Wolfgang Walther for reporting this problem.
+ (CVE-2023-2455)
+ </p></li><li class="listitem"><p>
+ Fix potential corruption of the template (source) database after
+ <code class="command">CREATE DATABASE</code> with the <code class="literal">STRATEGY
+ WAL_LOG</code> option (Nathan Bossart, Ryo Matsumura)
+ </p><p>
+ Improper buffer handling created a risk that any later modification
+ of the template's <code class="structname">pg_class</code> catalog would be
+ lost.
+ </p></li><li class="listitem"><p>
+ Fix memory leakage and unnecessary disk reads
+ during <code class="command">CREATE DATABASE</code> with the <code class="literal">STRATEGY
+ WAL_LOG</code> option (Andres Freund)
+ </p></li><li class="listitem"><p>
+ Avoid crash when the new schema name is omitted
+ in <code class="command">CREATE SCHEMA</code> (Michael Paquier)
+ </p><p>
+ The SQL standard allows writing <code class="literal">CREATE SCHEMA AUTHORIZATION
+ <em class="replaceable"><code>owner_name</code></em></code>, with the schema
+ name defaulting to <em class="replaceable"><code>owner_name</code></em>. However
+ some code paths expected the schema name to be present and would
+ fail.
+ </p></li><li class="listitem"><p>
+ Fix various planner failures with <code class="command">MERGE</code>
+ commands (Tom Lane)
+ </p><p>
+ Planning could fail with errors like <span class="quote">“<span class="quote">variable not found in
+ subplan target list</span>”</span> or <span class="quote">“<span class="quote">PlaceHolderVar found where not
+ expected</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Fix the row count reported by <code class="command">MERGE</code> for some
+ corner cases (Dean Rasheed)
+ </p><p>
+ The row count reported in the command tag counted rows that actually
+ hadn't been modified due to a <code class="literal">BEFORE ROW</code> trigger
+ returning NULL. This is inconsistent with what happens in
+ plain <code class="command">UPDATE</code> or <code class="command">DELETE</code>, so
+ change it to not count such rows. Also, avoid counting a row twice
+ when <code class="command">MERGE</code> moves it into a different partition of
+ a partitioned table.
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">MERGE</code> problems with concurrent updates
+ (Dean Rasheed, Álvaro Herrera)
+ </p><p>
+ Some cases misbehaved if a row to be updated or deleted
+ by <code class="command">MERGE</code> had just been updated by a concurrent
+ transaction. This could lead to a crash, or the wrong merge action
+ being executed, or no action at all.
+ </p></li><li class="listitem"><p>
+ Add support for decompiling <code class="command">MERGE</code>
+ commands (Álvaro Herrera)
+ </p><p>
+ This was overlooked when <code class="command">MERGE</code> was added, but
+ it's essential support for <code class="command">MERGE</code> in new-style SQL
+ functions.
+ </p></li><li class="listitem"><p>
+ Fix enabling/disabling of foreign-key triggers in partitioned tables
+ (Tom Lane)
+ </p><p>
+ <code class="command">ALTER TABLE ... ENABLE/DISABLE TRIGGER</code> failed if
+ applied to a partitioned table's foreign-key enforcement triggers,
+ because it tried to locate the clone triggers for the partitions by
+ name, and they do not have the same name. Locate them by
+ parent-trigger OID instead.
+ </p></li><li class="listitem"><p>
+ Disallow altering composite types that are stored in indexes
+ (Tom Lane)
+ </p><p>
+ <code class="command">ALTER TYPE</code> disallows non-binary-compatible
+ modifications of composite types if they are stored in any table
+ columns. (Perhaps that will be allowed someday, but it hasn't
+ happened yet; the locking implications of rewriting many tables are
+ daunting.) We overlooked the possibility that an index might
+ contain a composite type that doesn't also appear in its table.
+ </p></li><li class="listitem"><p>
+ Disallow system columns as elements of foreign keys (Tom Lane)
+ </p><p>
+ Since the removal of OID as a system column, there is no plausible
+ use-case for this, and various bits of code no longer support it.
+ Disallow it rather than trying to fix all the cases.
+ </p></li><li class="listitem"><p>
+ Ensure that <code class="command">COPY TO</code> from an RLS-enabled parent
+ table does not copy any rows from child tables (Antonin Houska)
+ </p><p>
+ The documentation is quite clear that <code class="command">COPY TO</code>
+ copies rows from only the named table, not any inheritance children
+ it may have. However, if row-level security was enabled on the table
+ then this stopped being true.
+ </p></li><li class="listitem"><p>
+ Avoid possible crash when <code class="function">array_position()</code>
+ or <code class="function">array_positions()</code> is passed an empty array
+ (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix possible out-of-bounds fetch in <code class="function">to_char()</code>
+ (Tom Lane)
+ </p><p>
+ With bad luck this could have resulted in a server crash.
+ </p></li><li class="listitem"><p>
+ Avoid buffer overread in <code class="function">translate()</code> function
+ (Daniil Anisimov)
+ </p><p>
+ When using the deletion feature, the function might fetch the byte
+ just after the input string, creating a small risk of crash.
+ </p></li><li class="listitem"><p>
+ Adjust text-search-related character classification logic to
+ correctly detect whether the prevailing locale
+ is <code class="literal">C</code> (Jeff Davis)
+ </p><p>
+ This code got confused if the database's default collation uses ICU.
+ </p></li><li class="listitem"><p>
+ Avoid possible crash on empty input for type <code class="type">interval</code>
+ (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Re-allow exponential notation in ISO-8601 interval fields
+ (Tom Lane)
+ </p><p>
+ Interval input like <code class="literal">P0.1e10D</code> isn't officially
+ sanctioned by ISO-8601, but we accepted it for a long time before
+ version 15, so re-allow it.
+ </p></li><li class="listitem"><p>
+ Fix error cursor setting for parse errors in JSON string literals
+ (Tom Lane)
+ </p><p>
+ Most cases in which a syntax error is detected in a string literal
+ within a JSON value failed to set the error cursor appropriately.
+ This led at least to an unhelpful error message (pointing to the
+ token before the string, rather than the actual trouble spot), and
+ could even result in a crash in v14 and later.
+ </p></li><li class="listitem"><p>
+ Fix data corruption due to <code class="varname">vacuum_defer_cleanup_age</code>
+ being larger than the current 64-bit xid (Andres Freund)
+ </p><p>
+ In v14 and later with non-default settings
+ of <code class="varname">vacuum_defer_cleanup_age</code>, it was possible to
+ compute a very large vacuum cleanup horizon xid, leading to vacuum
+ removing rows that are still live. v12 and v13 have a lesser form
+ of the same problem affecting only GiST indexes, which could lead to
+ index pages getting recycled too early.
+ </p></li><li class="listitem"><p>
+ Fix parser's failure to detect some cases of improperly-nested
+ aggregates (Tom Lane)
+ </p><p>
+ This oversight could lead to executor failures for queries that
+ should have been rejected as invalid.
+ </p></li><li class="listitem"><p>
+ Fix data structure corruption during parsing of
+ serial <code class="literal">SEQUENCE NAME</code> options (David Rowley)
+ </p><p>
+ This can lead to trouble if an event trigger captures the corrupted
+ parse tree.
+ </p></li><li class="listitem"><p>
+ Correctly update plan nodes' parallel-safety markings when moving
+ initplans from one node to another (Tom Lane)
+ </p><p>
+ This planner oversight could lead to <span class="quote">“<span class="quote">subplan was not
+ initialized</span>”</span> errors at runtime.
+ </p></li><li class="listitem"><p>
+ Avoid failure with PlaceHolderVars in extended-statistics code
+ (Tom Lane)
+ </p><p>
+ Use of dependency-type extended statistics could fail with
+ <span class="quote">“<span class="quote">PlaceHolderVar found where not expected</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Fix incorrect tests for whether a qual clause applied to a subquery
+ can be transformed into a window aggregate <span class="quote">“<span class="quote">run
+ condition</span>”</span> within the subquery (David Rowley)
+ </p><p>
+ A SubPlan within such a clause would cause assertion failures or
+ incorrect answers, as would some other unusual cases.
+ </p></li><li class="listitem"><p>
+ Disable the inverse-transition optimization for window aggregates
+ when the call contains sub-SELECTs (David Rowley)
+ </p><p>
+ This optimization requires that the aggregate's argument expressions
+ have repeatable results, which might not hold for a sub-SELECT.
+ </p></li><li class="listitem"><p>
+ Fix oversights in execution of nested <code class="literal">ARRAY[]</code>
+ constructs (Alexander Lakhin, Tom Lane)
+ </p><p>
+ Correctly detect overflow of the total space needed for the result
+ array, avoiding a possible crash due to undersized output
+ allocation. Also ensure that any trailing padding space in the
+ result array is zeroed; while leaving garbage there is harmless for
+ most purposes, it can result in odd behavior later.
+ </p></li><li class="listitem"><p>
+ Prevent crash when updating a field within an
+ array-of-domain-over-composite-type column (Dmitry Dolgov)
+ </p></li><li class="listitem"><p>
+ Fix partition pruning logic for partitioning on boolean columns
+ (David Rowley)
+ </p><p>
+ Pruning with a condition like <code class="literal">boolcol IS NOT TRUE</code>
+ was done incorrectly, leading to possibly not returning rows in
+ which <code class="literal">boolcol</code> is NULL. Also, the rather unlikely
+ case of partitioning on <code class="literal">NOT boolcol</code> was handled
+ incorrectly.
+ </p></li><li class="listitem"><p>
+ Fix race condition in per-batch cleanup during parallel hash join
+ (Thomas Munro, Melanie Plageman)
+ </p><p>
+ A crash was possible given unlucky timing and
+ <code class="varname">parallel_leader_participation</code>
+ = <code class="literal">off</code> (which is not the default).
+ </p></li><li class="listitem"><p>
+ Recalculate <code class="literal">GENERATED</code> columns after an
+ EvalPlanQual check (Tom Lane)
+ </p><p>
+ In <code class="literal">READ COMMITTED</code> isolation mode, the effects of
+ a row update might need to get reapplied to a newer version of the
+ row than the query found originally. If so, we need to recompute
+ any <code class="literal">GENERATED</code> columns, in case they depend on
+ columns that were changed by the concurrent update.
+ </p></li><li class="listitem"><p>
+ Fix memory leak in Memoize plan execution (David Rowley)
+ </p></li><li class="listitem"><p>
+ Fix buffer refcount leak when using batched inserts for a foreign
+ table included in a partitioned tree (Alexander Pyhalov)
+ </p></li><li class="listitem"><p>
+ Restore support for
+ sub-millisecond <code class="varname">vacuum_cost_delay</code> settings
+ (Thomas Munro)
+ </p></li><li class="listitem"><p>
+ Don't balance vacuum cost delay when a table has a
+ per-relation <code class="varname">vacuum_cost_delay</code> setting of zero
+ (Masahiko Sawada)
+ </p><p>
+ Delay balancing is supposed to be disabled whenever autovacuum is
+ processing a table with a
+ per-relation <code class="varname">vacuum_cost_delay</code> setting, but this
+ was done only for positive settings, not zero.
+ </p></li><li class="listitem"><p>
+ Fix corner-case crashes when columns have been added to the end of a
+ view (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Repair rare failure of MULTIEXPR_SUBLINK subplans in partitioned
+ updates (Andres Freund, Tom Lane)
+ </p><p>
+ Use of the syntax <code class="literal">INSERT ... ON CONFLICT DO UPDATE SET (c1,
+ ...) = (SELECT ...)</code> with a partitioned target table could
+ result in failure if any child table is dissimilar from the parent
+ (for example, different physical column order).
+ This typically manifested as failure of consistency checks in the
+ executor; but a crash or incorrect data updates are also possible.
+ </p></li><li class="listitem"><p>
+ Fix handling of <code class="literal">DEFAULT</code> markers within a
+ multi-row <code class="literal">INSERT ... VALUES</code> query on a view that
+ has a <code class="literal">DO ALSO INSERT ... SELECT</code> rule (Dean
+ Rasheed)
+ </p><p>
+ Such cases typically failed with <span class="quote">“<span class="quote">unrecognized node
+ type</span>”</span> errors or assertion failures.
+ </p></li><li class="listitem"><p>
+ Support references to <code class="literal">OLD</code>
+ and <code class="literal">NEW</code> within subqueries in rule actions
+ (Dean Rasheed, Tom Lane)
+ </p><p>
+ Such references are really lateral references, but the server could
+ crash if the subquery wasn't explicitly marked
+ with <code class="literal">LATERAL</code>. Arrange to do that implicitly when
+ necessary.
+ </p></li><li class="listitem"><p>
+ When decompiling a rule or SQL function body
+ containing <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>
+ within <code class="command">WITH</code>, take care to print the correct alias
+ for the target table (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix glitches in <code class="literal">SERIALIZABLE READ ONLY</code>
+ optimization (Thomas Munro)
+ </p><p>
+ Transactions already marked as <span class="quote">“<span class="quote">doomed</span>”</span> confused the
+ safe-snapshot optimization for <code class="literal">SERIALIZABLE READ
+ ONLY</code> transactions. The optimization was unnecessarily
+ skipped in some cases. In other cases an assertion failure occurred
+ (but there was no problem in non-assert builds).
+ </p></li><li class="listitem"><p>
+ Avoid leaking cache callback slots in
+ the <code class="literal">pgoutput</code> logical decoding plugin (Shi Yu)
+ </p><p>
+ Multiple cycles of starting up and shutting down the plugin within a
+ single session would eventually lead to an <span class="quote">“<span class="quote">out of
+ relcache_callback_list slots</span>”</span> error.
+ </p></li><li class="listitem"><p>
+ Avoid unnecessary calls to custom validators for index operator
+ class options (Alexander Korotkov)
+ </p><p>
+ This change fixes some cases where an unexpected error was thrown.
+ </p></li><li class="listitem"><p>
+ Avoid useless work while scanning a multi-column BRIN index with
+ multiple scan keys (Tomas Vondra)
+ </p><p>
+ The existing code effectively considered only the last scan key
+ while deciding whether a range matched, thus usually scanning more
+ of the index than it needed to.
+ </p></li><li class="listitem"><p>
+ Fix netmask handling in BRIN inet_minmax_multi_ops opclass
+ (Tomas Vondra)
+ </p><p>
+ This error triggered an assertion failure in assert-enabled builds,
+ but is mostly harmless in production builds.
+ </p></li><li class="listitem"><p>
+ Fix dereference of dangling pointer during buffering build of a GiST
+ index (Alexander Lakhin)
+ </p><p>
+ This error seems to usually be harmless in production builds, as the
+ fetched value is noncritical; but in principle it could cause a
+ server crash.
+ </p></li><li class="listitem"><p>
+ Ignore dropped columns and generated columns during logical
+ replication of an update or delete action (Onder Kalaci, Shi Yu)
+ </p><p>
+ Replication with the <code class="literal">REPLICA IDENTITY FULL</code> option
+ failed if the table contained such columns.
+ </p></li><li class="listitem"><p>
+ Correct the name of the wait event for SLRU buffer I/O for commit
+ timestamps (Alexander Lakhin)
+ </p><p>
+ This wait event is named <code class="literal">CommitTsBuffer</code> according
+ to the documentation, but the code had it
+ as <code class="literal">CommitTSBuffer</code>. Change the code to match the
+ documentation, as that way is more consistent with the naming of
+ related wait events.
+ </p></li><li class="listitem"><p>
+ Re-activate reporting of wait event <code class="literal">SLRUFlushSync</code>
+ (Thomas Munro)
+ </p><p>
+ Reporting of this type of wait was accidentally removed in code
+ refactoring.
+ </p></li><li class="listitem"><p>
+ Avoid possible underflow when calculating how many WAL segments to
+ keep (Kyotaro Horiguchi)
+ </p><p>
+ This could result in not honoring <code class="varname">wal_keep_size</code>
+ accurately.
+ </p></li><li class="listitem"><p>
+ Disable startup progress reporting overhead in standby mode
+ (Bharath Rupireddy)
+ </p><p>
+ In standby mode, we don't actually report progress of recovery,
+ but we were doing work to track it anyway.
+ </p></li><li class="listitem"><p>
+ Support RSA-PSS certificates with SCRAM-SHA-256 channel binding
+ (Jacob Champion, Heikki Linnakangas)
+ </p><p>
+ This feature requires building with OpenSSL 1.1.1 or newer. Both
+ the server and <span class="application">libpq</span> are affected.
+ </p></li><li class="listitem"><p>
+ Avoid race condition with process ID tracking on Windows (Thomas Munro)
+ </p><p>
+ The operating system could recycle a PID before the postmaster
+ observed that that child process was gone. This could lead to
+ tracking more than one child with the same PID, resulting in
+ confusion.
+ </p></li><li class="listitem"><p>
+ Fix <code class="function">list_copy_head()</code> to work correctly on an
+ empty List (David Rowley)
+ </p><p>
+ This case is not known to be reached by any
+ core <span class="productname">PostgreSQL</span> code, but extensions
+ might rely on it working.
+ </p></li><li class="listitem"><p>
+ Add missing cases to <code class="function">SPI_result_code_string()</code>
+ (Dean Rasheed)
+ </p></li><li class="listitem"><p>
+ Fix erroneous Valgrind markings
+ in <code class="function">AllocSetRealloc()</code> (Karina Litskevich)
+ </p><p>
+ In the unusual case where the size of a large (&gt;8kB) palloc chunk
+ is decreased, a Valgrind-aware build would mismark the defined-ness
+ state of the memory released from the chunk, possibly causing
+ incorrect results during Valgrind testing.
+ </p></li><li class="listitem"><p>
+ Fix assertion failure for <code class="command">MERGE</code> into a
+ partitioned table with row-level security enabled (Dean Rasheed)
+ </p></li><li class="listitem"><p>
+ Avoid assertion failure when decoding a transactional logical
+ replication message (Tomas Vondra)
+ </p></li><li class="listitem"><p>
+ Avoid locale sensitivity when processing regular expression escapes
+ (Jeff Davis)
+ </p><p>
+ A backslash followed by a non-ASCII character could sometimes cause
+ an assertion failure, depending on the prevailing locale.
+ </p></li><li class="listitem"><p>
+ Avoid trying to write an empty WAL record
+ in <code class="function">log_newpage_range()</code> when the last few pages
+ in the specified range are empty (Matthias van de Meent)
+ </p><p>
+ It is not entirely clear whether this case is reachable in released
+ branches, but if it is then an assertion failure could occur.
+ </p></li><li class="listitem"><p>
+ Fix session-lifespan memory leakage in <span class="application">plpgsql</span>
+ <code class="literal">DO</code> blocks that use cast expressions
+ (Ajit Awekar, Tom Lane)
+ </p></li><li class="listitem"><p>
+ Tighten array dimensionality checks when converting Perl
+ list structures to multi-dimensional SQL arrays (Tom Lane)
+ </p><p>
+ <span class="application">plperl</span> could misbehave when the nesting
+ of sub-lists is inconsistent so that the data does not represent a
+ rectangular array of values. Such cases now produce errors, but
+ previously they could result in a crash or garbage output.
+ </p></li><li class="listitem"><p>
+ Tighten array dimensionality checks when converting Python
+ list structures to multi-dimensional SQL arrays (Tom Lane)
+ </p><p>
+ <span class="application">plpython</span> could misbehave when dealing
+ with empty sub-lists, or when the nesting of sub-lists is
+ inconsistent so that the data does not represent a rectangular array
+ of values. The former should result in an empty output array, and
+ the latter in an error. But some cases resulted in a crash, and
+ others in unexpected output.
+ </p></li><li class="listitem"><p>
+ Fix unwinding of exception stack
+ in <span class="application">plpython</span> (Xing Guo)
+ </p><p>
+ Some rare failure cases could return without cleaning up the PG_TRY
+ exception stack, risking a crash if another error was raised before
+ the next stack level was unwound.
+ </p></li><li class="listitem"><p>
+ Fix inconsistent GSS-encryption error handling
+ in <span class="application">libpq</span>'s
+ <code class="function">PQconnectPoll()</code>
+ (Michael Paquier)
+ </p><p>
+ With <code class="option">gssencmode</code> set to <code class="literal">require</code>,
+ the connection was not marked dead after a GSS initialization
+ failure. Make it fail immediately, as the equivalent case for TLS
+ encryption has long done.
+ </p></li><li class="listitem"><p>
+ Fix possible data corruption in <span class="application">ecpg</span>
+ programs built with the <code class="option">-C ORACLE</code> option
+ (Kyotaro Horiguchi)
+ </p><p>
+ When <code class="function">ecpg_get_data()</code> is called
+ with <code class="varname">varcharsize</code> set to zero, it could write a
+ terminating zero character into the last byte of the preceding
+ field, truncating the data in that field.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pg_dump</span> so that partitioned tables
+ that are hash-partitioned on an enum-type column can be restored
+ successfully (Tom Lane)
+ </p><p>
+ Since the hash codes for enum values depend on the OIDs assigned to
+ the enum, they are typically different after a dump and restore,
+ meaning that rows often need to go into a different partition than
+ they were in originally. Users can work around that by specifying
+ the <code class="option">--load-via-partition-root</code> option; but since
+ there is very little chance of success without that,
+ teach <span class="application">pg_dump</span> to apply it automatically
+ to such tables.
+ </p><p>
+ Also, fix <span class="application">pg_restore</span> to not try
+ to <code class="command">TRUNCATE</code> target tables before restoring into
+ them when <code class="option">--load-via-partition-root</code> mode is used.
+ This avoids a hazard of deadlocks and lost data.
+ </p></li><li class="listitem"><p>
+ Correctly detect non-seekable files on Windows
+ (Juan José Santamaría Flecha, Michael Paquier, Daniel Watzinger)
+ </p><p>
+ This bug led to misbehavior when <span class="application">pg_dump</span>
+ writes to a pipe or <span class="application">pg_restore</span> reads from
+ one.
+ </p></li><li class="listitem"><p>
+ In <span class="application">pgbench</span>'s <span class="quote">“<span class="quote">prepared</span>”</span>
+ mode, prepare all the commands in a pipeline before starting the
+ pipeline (Álvaro Herrera)
+ </p><p>
+ This avoids a failure when a pgbench script tries to
+ start a serializable transaction inside a pipeline.
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/amcheck</code>'s heap checking code, deal
+ correctly with tuples having zero xmin or xmax (Robert Haas)
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/amcheck</code>, deal sanely with xids that
+ appear to be before epoch zero (Andres Freund)
+ </p><p>
+ In cases of corruption we might see a wrapped-around 32-bit xid that
+ appears to be before the first xid epoch. Promoting such a value to
+ 64-bit form produced a value far in the future, resulting in wrong
+ reports. Return FirstNormalFullTransactionId in such cases so that
+ things work reasonably sanely.
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/basebackup_to_shell</code>, properly detect
+ failure to open a pipe (Robert Haas)
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/hstore_plpython</code>, avoid crashing if
+ the Python value to be transformed isn't a mapping (Dmitry Dolgov,
+ Tom Lane)
+ </p><p>
+ This should give an error, but Python 3 changed some APIs in a way
+ that caused the check to misbehave, allowing a crash to ensue.
+ </p></li><li class="listitem"><p>
+ Require the <code class="literal">siglen</code> option of a GiST index on
+ an <code class="type">ltree</code> column, if specified, to be a multiple of 4
+ (Alexander Korotkov)
+ </p><p>
+ Other values result in misaligned accesses to index content, which
+ is harmless on Intel-compatible hardware but can cause a crash on
+ some other architectures.
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/pageinspect</code>, add defenses against
+ incorrect input for the <code class="function">gist_page_items()</code> function
+ (Dmitry Koval)
+ </p></li><li class="listitem"><p>
+ Fix misbehavior in <code class="filename">contrib/pg_trgm</code> with an
+ unsatisfiable regular expression (Tom Lane)
+ </p><p>
+ A regex such as <code class="literal">$foo</code> is legal but unsatisfiable;
+ the regex compiler recognizes that and produces an empty NFA graph.
+ Attempting to optimize such a graph into a pg_trgm GIN or GiST index
+ qualification resulted in accessing off the end of a work array,
+ possibly leading to crashes.
+ </p></li><li class="listitem"><p>
+ Fix handling of escape sequences
+ in <code class="filename">contrib/postgres_fdw</code>'s
+ <code class="varname">application_name</code> parameter (Kyotaro Horiguchi,
+ Michael Paquier)
+ </p><p>
+ The code to expand these could fail if executed in a background
+ process, as for example during auto-analyze of a foreign table.
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/pg_walinspect</code>, limit memory usage
+ of <code class="function">pg_get_wal_records_info()</code> (Bharath Rupireddy)
+ </p></li><li class="listitem"><p>
+ Use the <code class="option">--strip-unneeded</code> option when stripping
+ static libraries with
+ GNU-compatible <span class="application">strip</span> (Tom Lane)
+ </p><p>
+ Previously, <code class="literal">make install-strip</code> used
+ the <code class="option">-x</code> option in this case. This change avoids
+ misbehavior of <span class="application">llvm-strip</span>, and gives
+ slightly smaller output as well.
+ </p></li><li class="listitem"><p>
+ Stop recommending auto-download of DTD files for building the
+ documentation, and indeed disable it (Aleksander Alekseev, Peter
+ Eisentraut, Tom Lane)
+ </p><p>
+ It appears no longer possible to build the SGML documentation
+ without a local installation of the DocBook DTD files.
+ Formerly <span class="application">xsltproc</span> could download those
+ files on-the-fly from sourceforge.net; but sourceforge.net now
+ permits only HTTPS access, and no common version
+ of <span class="application">xsltproc</span> supports that. Hence, remove
+ the bits of our documentation suggesting that that's possible or
+ useful, and instead
+ add <span class="application">xsltproc</span>'s <code class="option">--nonet</code>
+ option to the build recipes.
+ </p></li><li class="listitem"><p>
+ When running TAP tests in PGXS builds, use a saner location for the
+ temporary <code class="filename">portlock</code> directory (Peter Eisentraut)
+ </p><p>
+ Place it under <code class="filename">tmp_check</code> in the build
+ directory. With the previous coding, a PGXS build would try to place
+ it in the installation directory, which is not necessarily writable.
+ </p></li><li class="listitem"><p>
+ Update time zone data files to <span class="application">tzdata</span>
+ release 2023c for DST law changes in Egypt, Greenland, Morocco, and
+ Palestine.
+ </p><p>
+ When observing Moscow time, Europe/Kirov and Europe/Volgograd now
+ use the abbreviations MSK/MSD instead of numeric abbreviations,
+ for consistency with other timezones observing Moscow time.
+ Also, America/Yellowknife is no longer distinct from America/Edmonton;
+ this affects some pre-1948 timestamps in that area.
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15-4.html" title="E.2. Release 15.4">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15-2.html" title="E.4. Release 15.2">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.2. Release 15.4 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.4. Release 15.2</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15-4.html b/doc/src/sgml/html/release-15-4.html
new file mode 100644
index 0000000..67f56e0
--- /dev/null
+++ b/doc/src/sgml/html/release-15-4.html
@@ -0,0 +1,351 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.2. Release 15.4</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15-5.html" title="E.1. Release 15.5" /><link rel="next" href="release-15-3.html" title="E.3. Release 15.3" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.2. Release 15.4</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15-5.html" title="E.1. Release 15.5">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15-3.html" title="E.3. Release 15.3">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15-4"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.2. Release 15.4</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15-4.html#id-1.11.6.6.4">E.2.1. Migration to Version 15.4</a></span></dt><dt><span class="sect2"><a href="release-15-4.html#id-1.11.6.6.5">E.2.2. Changes</a></span></dt></dl></div><p><strong>Release date: </strong>2023-08-10</p><p>
+ This release contains a variety of fixes from 15.3.
+ For information about new features in major release 15, see
+ <a class="xref" href="release-15.html" title="E.6. Release 15">Section E.6</a>.
+ </p><div class="sect2" id="id-1.11.6.6.4"><div class="titlepage"><div><div><h3 class="title">E.2.1. Migration to Version 15.4</h3></div></div></div><p>
+ A dump/restore is not required for those running 15.X.
+ </p><p>
+ However, if you use BRIN indexes, it may be advisable to reindex them;
+ see the third changelog entry below.
+ </p><p>
+ Also, if you are upgrading from a version earlier than 15.1,
+ see <a class="xref" href="release-15-1.html" title="E.5. Release 15.1">Section E.5</a>.
+ </p></div><div class="sect2" id="id-1.11.6.6.5"><div class="titlepage"><div><div><h3 class="title">E.2.2. Changes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Disallow substituting a schema or owner name into an extension script
+ if the name contains a quote, backslash, or dollar sign (Noah Misch)
+ </p><p>
+ This restriction guards against SQL-injection hazards for trusted
+ extensions.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks Micah Gate,
+ Valerie Woolard, Tim Carey-Smith, and Christoph Berg for reporting
+ this problem.
+ (CVE-2023-39417)
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">MERGE</code> to enforce row security policies
+ properly (Dean Rasheed)
+ </p><p>
+ When <code class="command">MERGE</code> performs an <code class="literal">UPDATE</code>
+ action, it should enforce any <code class="literal">UPDATE</code> or
+ <code class="literal">SELECT</code> RLS policies defined on the target table,
+ to be consistent with the way that a plain <code class="command">UPDATE</code>
+ with a <code class="literal">WHERE</code> clause works. Instead it was
+ enforcing <code class="literal">INSERT</code> RLS policies for both
+ <code class="literal">INSERT</code> and <code class="literal">UPDATE</code> actions.
+ </p><p>
+ In addition, when <code class="command">MERGE</code> performs a <code class="literal">DO
+ NOTHING</code> action, it applied the target table's
+ <code class="literal">DELETE</code> RLS policies to existing rows, even though
+ those rows are not being deleted. While it's not a security
+ problem, this could result in unwanted errors.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks
+ Dean Rasheed for reporting this problem.
+ (CVE-2023-39418)
+ </p></li><li class="listitem"><p>
+ Fix confusion between empty (no rows) ranges and all-NULL ranges in
+ BRIN indexes, as well as incorrect merging of all-NULL summaries
+ (Tomas Vondra)
+ </p><p>
+ Each of these oversights could result in forgetting that a BRIN
+ index range contains any NULL values, potentially allowing
+ subsequent queries that should return NULL values to miss doing so.
+ </p><p>
+ This fix will not in itself correct faulty BRIN entries.
+ It's recommended to <code class="command">REINDEX</code> any BRIN indexes that
+ may be used to search for nulls.
+ </p></li><li class="listitem"><p>
+ Avoid leaving a corrupted database behind when <code class="command">DROP
+ DATABASE</code> is interrupted (Andres Freund)
+ </p><p>
+ If <code class="command">DROP DATABASE</code> was interrupted after it had
+ already begun taking irreversible steps, the target database
+ remained accessible (because the removal of
+ its <code class="structname">pg_database</code> row would roll back),
+ but it would have corrupt contents. Fix by marking the database
+ as inaccessible before we begin to perform irreversible operations.
+ A failure after that will leave the database still partially
+ present, but nothing can be done with it except to issue
+ another <code class="command">DROP DATABASE</code>.
+ </p></li><li class="listitem"><p>
+ Ensure that partitioned indexes are correctly marked as valid or not
+ at creation (Michael Paquier)
+ </p><p>
+ If a new partitioned index matches an existing but invalid index on
+ one of the partitions, the partitioned index could end up being
+ marked valid prematurely. This could lead to misbehavior or
+ assertion failures in subsequent queries on the partitioned table.
+ </p></li><li class="listitem"><p>
+ Ignore invalid child indexes when matching partitioned indexes to
+ child indexes during <code class="command">ALTER TABLE ATTACH PARTITION</code>
+ (Michael Paquier)
+ </p><p>
+ Such an index will now be ignored, and a new child index created
+ instead.
+ </p></li><li class="listitem"><p>
+ Fix possible failure when marking a partitioned index valid after
+ all of its partitions have been attached (Michael Paquier)
+ </p><p>
+ The update of the index's <code class="structname">pg_index</code> entry
+ could use stale data for other columns. One reported symptom is
+ an <span class="quote">“<span class="quote">attempted to update invisible tuple</span>”</span> error.
+ </p></li><li class="listitem"><p>
+ Fix <code class="command">ALTER EXTENSION SET SCHEMA</code> to complain if the
+ extension contains any objects outside the extension's schema
+ (Michael Paquier, Heikki Linnakangas)
+ </p><p>
+ Erroring out if the extension contains objects in multiple schemas
+ was always intended; but the check was mis-coded so that it would
+ fail to detect some cases, leading to surprising behavior.
+ </p></li><li class="listitem"><p>
+ Fix tracking of tables' access method dependencies (Michael Paquier)
+ </p><p>
+ <code class="command">ALTER TABLE ... SET ACCESS METHOD</code> failed to
+ update relevant <code class="structname">pg_depend</code> entries when
+ changing a table's access method. When using non-built-in access
+ methods, this creates a risk that an access method could be dropped
+ even though tables still depend on it. This fix corrects the logic
+ in <code class="command">ALTER TABLE</code>, but it will not adjust any
+ already-missing <code class="structname">pg_depend</code> entries.
+ </p></li><li class="listitem"><p>
+ Don't use partial unique indexes for uniqueness proofs in the
+ planner (David Rowley)
+ </p><p>
+ This could give rise to incorrect plans, since the presumed
+ uniqueness of rows read from a table might not hold if the index in
+ question isn't used to scan the table.
+ </p></li><li class="listitem"><p>
+ Don't Memoize lateral joins with volatile join conditions
+ (Richard Guo)
+ </p><p>
+ Applying Memoize to a sub-plan that contains volatile filter
+ conditions is likely to lead to wrong answers. The check to avoid
+ doing this missed some cases that can arise when
+ using <code class="literal">LATERAL</code>.
+ </p></li><li class="listitem"><p>
+ Avoid producing incorrect plans for foreign joins with
+ pseudoconstant join clauses (Etsuro Fujita)
+ </p><p>
+ The planner currently lacks support for attaching pseudoconstant
+ join clauses to a pushed-down remote join, so disable generation
+ of remote joins in such cases. (A better solution will require
+ ABI-breaking changes of planner data structures, so it will have to
+ wait for a future major release.)
+ </p></li><li class="listitem"><p>
+ Correctly handle sub-SELECTs in RLS policy expressions and
+ security-barrier views when expanding rule actions (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix race conditions in conflict detection
+ for <code class="literal">SERIALIZABLE</code> isolation mode
+ (Thomas Munro)
+ </p><p>
+ Conflicts could be missed when using bitmap heap scans, when using
+ GIN indexes, and when examining an initially-empty btree index.
+ All these cases could lead to serializability failures due to
+ improperly allowing conflicting transactions to commit.
+ </p></li><li class="listitem"><p>
+ Fix misbehavior of EvalPlanQual checks with inherited or partitioned
+ target tables (Tom Lane)
+ </p><p>
+ This oversight could lead to update or delete actions
+ in <code class="literal">READ COMMITTED</code> isolation mode getting
+ performed when they should have been skipped because of a
+ conflicting concurrent update.
+ </p></li><li class="listitem"><p>
+ Fix hash join with an inner-side hash key that contains Params
+ coming from an outer nested loop (Tom Lane)
+ </p><p>
+ When rescanning the join after the values of such Params have
+ changed, we must rebuild the hash table, but neglected to do so.
+ This could result in missing join output rows.
+ </p></li><li class="listitem"><p>
+ Fix intermittent failures when trying to update a field of a
+ composite column (Tom Lane)
+ </p><p>
+ If the overall value of the composite column is wide enough to
+ require out-of-line toasting, then an unluckily-timed cache flush
+ could cause errors or server crashes.
+ </p></li><li class="listitem"><p>
+ Prevent query-lifespan memory leaks in some <code class="command">UPDATE</code>
+ queries with triggers (Tomas Vondra)
+ </p></li><li class="listitem"><p>
+ Prevent query-lifespan memory leaks when an Incremental Sort plan
+ node is rescanned (James Coleman, Laurenz Albe, Tom Lane)
+ </p></li><li class="listitem"><p>
+ Accept fractional seconds in the input to <code class="type">jsonpath</code>'s
+ <code class="function">datetime()</code> method (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Prevent stack-overflow crashes with very complex text search
+ patterns (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Allow tokens up to 10240 bytes long
+ in <code class="filename">pg_hba.conf</code>
+ and <code class="filename">pg_ident.conf</code> (Tom Lane)
+ </p><p>
+ The previous limit of 256 bytes has been found insufficient for some
+ use-cases.
+ </p></li><li class="listitem"><p>
+ Ensure that all existing placeholders are checked for matches when
+ an extension declares its GUC prefix to be reserved (Karina
+ Litskevich, Ekaterina Sokolova)
+ </p><p>
+ Faulty loop logic could cause some entries to be skipped.
+ </p></li><li class="listitem"><p>
+ Fix mishandling of C++ out-of-memory conditions (Heikki Linnakangas)
+ </p><p>
+ If JIT is in use, running out of memory in a
+ C++ <code class="function">new</code> call would lead to
+ a <span class="productname">PostgreSQL</span> FATAL error, instead of the
+ expected C++ exception.
+ </p></li><li class="listitem"><p>
+ Fix rare null-pointer crash in <code class="filename">plancache.c</code>
+ (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Avoid leaking a stats entry for a subscription when it is dropped
+ (Masahiko Sawada)
+ </p></li><li class="listitem"><p>
+ Avoid losing track of possibly-useful shared memory segments when a
+ page free results in coalescing ranges of free space (Dongming Liu)
+ </p><p>
+ Ensure that the segment is moved into the
+ appropriate <span class="quote">“<span class="quote">bin</span>”</span> for its new amount of free space, so
+ that it will be found by subsequent searches.
+ </p></li><li class="listitem"><p>
+ Allow <code class="command">VACUUM</code> to continue after detecting certain
+ types of b-tree index corruption (Peter Geoghegan)
+ </p><p>
+ If an invalid sibling-page link is detected, log the issue and press
+ on, rather than throwing an error as before. Nothing short
+ of <code class="command">REINDEX</code> will fix the broken index, but
+ preventing <code class="command">VACUUM</code> from completing until that is
+ done risks making matters far worse.
+ </p></li><li class="listitem"><p>
+ Ensure that <code class="varname">WrapLimitsVacuumLock</code> is released
+ after <code class="command">VACUUM</code> detects invalid data
+ in <code class="structname">pg_database</code>.<code class="structfield">datfrozenxid</code>
+ or <code class="structname">pg_database</code>.<code class="structfield">datminmxid</code>
+ (Andres Freund)
+ </p><p>
+ Failure to release this lock could lead to a deadlock later,
+ although the lock would be cleaned up if the session exits or
+ encounters some other error.
+ </p></li><li class="listitem"><p>
+ Avoid double replay of prepared transactions during crash
+ recovery (suyu.cmj, Michael Paquier)
+ </p><p>
+ After a crash partway through a checkpoint with some two-phase
+ transaction state data already flushed to disk by this checkpoint,
+ crash recovery could attempt to replay the prepared transaction(s)
+ twice, leading to a fatal error such as <span class="quote">“<span class="quote">lock is already
+ held</span>”</span> in the startup process.
+ </p></li><li class="listitem"><p>
+ Ensure that a newly created, but still empty table
+ is <code class="function">fsync</code>'ed at the next checkpoint (Heikki
+ Linnakangas)
+ </p><p>
+ Without this, if there is an operating system crash causing the
+ empty file to disappear, subsequent operations on the table might
+ fail with <span class="quote">“<span class="quote">could not open file</span>”</span> errors.
+ </p></li><li class="listitem"><p>
+ Ensure that creation of the init fork of an unlogged index is
+ WAL-logged (Heikki Linnakangas)
+ </p><p>
+ While an unlogged index's main data fork is not WAL-logged, its init
+ fork should be, to ensure that we have a consistent state to restore
+ the index to after a crash. This step was missed if the init fork
+ contains no data, which is a case not used by any standard index AM;
+ but perhaps some extension behaves that way.
+ </p></li><li class="listitem"><p>
+ Silence bogus <span class="quote">“<span class="quote">missing contrecord</span>”</span> errors (Thomas Munro)
+ </p><p>
+ Treat this case as plain end-of-WAL to avoid logging inaccurate
+ complaints from <span class="application">pg_waldump</span>
+ and <span class="application">walsender</span>.
+ </p></li><li class="listitem"><p>
+ Fix overly strict assertion in <code class="type">jsonpath</code> code
+ (David Rowley)
+ </p><p>
+ This assertion failed if a query applied
+ the <code class="literal">.type()</code> operator to
+ a <code class="literal">like_regex</code> result.
+ There was no bug in non-assert builds.
+ </p></li><li class="listitem"><p>
+ Avoid assertion failure when processing an empty statement via the
+ extended query protocol in an already-aborted transaction (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Avoid assertion failure when
+ the <code class="varname">stats_fetch_consistency</code> setting is changed
+ intra-transaction (Kyotaro Horiguchi)
+ </p></li><li class="listitem"><p>
+ Fix <code class="filename">contrib/fuzzystrmatch</code>'s
+ Soundex <code class="function">difference()</code> function to handle empty
+ input sanely (Alexander Lakhin, Tom Lane)
+ </p><p>
+ An input string containing no alphabetic characters resulted in
+ unpredictable output.
+ </p></li><li class="listitem"><p>
+ Tighten whitespace checks in <code class="filename">contrib/hstore</code>
+ input (Evan Jones)
+ </p><p>
+ In some cases, characters would be falsely recognized as whitespace
+ and hence discarded.
+ </p></li><li class="listitem"><p>
+ Disallow oversize input arrays
+ with <code class="filename">contrib/intarray</code>'s
+ <code class="literal">gist__int_ops</code> index opclass (Ankit Kumar Pandey,
+ Alexander Lakhin)
+ </p><p>
+ Previously this code would report a <code class="literal">NOTICE</code> but
+ press on anyway, creating an invalid index entry that presents a
+ risk of crashes when the index is read.
+ </p></li><li class="listitem"><p>
+ Avoid useless double decompression of GiST index entries
+ in <code class="filename">contrib/intarray</code> (Konstantin Knizhnik,
+ Matthias van de Meent, Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix <code class="filename">contrib/pageinspect</code>'s
+ <code class="function">gist_page_items()</code> function to work when there
+ are included index columns (Alexander Lakhin, Michael Paquier)
+ </p><p>
+ Previously, if the index has included
+ columns, <code class="function">gist_page_items()</code> would fail to
+ display those values on index leaf pages, or crash outright on
+ non-leaf pages.
+ </p></li><li class="listitem"><p>
+ In <span class="application">psql</span>, ignore
+ the <code class="envar">PSQL_WATCH_PAGER</code> environment variable when
+ stdin/stdout are not a terminal (Tom Lane)
+ </p><p>
+ This corresponds to the treatment of <code class="envar">PSQL_PAGER</code> in
+ commands besides <code class="command">\watch</code>.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pg_dump</span> to correctly handle new-style
+ SQL-language functions whose bodies require parse-time dependencies
+ on unique indexes (Tom Lane)
+ </p><p>
+ Such cases can arise from <code class="literal">GROUP BY</code>
+ and <code class="literal">ON CONFLICT</code> clauses, for example. The
+ function must then be postponed until after the unique index in the
+ dump output, but <span class="application">pg_dump</span> did not do that
+ and instead printed a warning about <span class="quote">“<span class="quote">could not resolve
+ dependency loop</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Improve <span class="application">pg_dump</span>'s display of details
+ about dependency-loop problems (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Avoid crash in <span class="application">pgbench</span> with an empty
+ pipeline and prepared mode (Álvaro Herrera)
+ </p></li><li class="listitem"><p>
+ Ensure
+ that <code class="structname">pg_index</code>.<code class="structfield">indisreplident</code>
+ is kept up-to-date in relation cache entries (Shruthi Gowda)
+ </p><p>
+ This value could be stale in some cases. There is no core code that
+ relies on the relation cache's copy, so this is only a latent bug as
+ far as Postgres itself is concerned; but there may be extensions for
+ which it is a live bug.
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">make_etags</span> script to work with
+ non-Exuberant <span class="application">ctags</span> (Masahiko Sawada)
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15-5.html" title="E.1. Release 15.5">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15-3.html" title="E.3. Release 15.3">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.1. Release 15.5 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.3. Release 15.3</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15-5.html b/doc/src/sgml/html/release-15-5.html
new file mode 100644
index 0000000..2f887fd
--- /dev/null
+++ b/doc/src/sgml/html/release-15-5.html
@@ -0,0 +1,468 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.1. Release 15.5</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release.html" title="Appendix E. Release Notes" /><link rel="next" href="release-15-4.html" title="E.2. Release 15.4" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.1. Release 15.5</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release.html" title="Appendix E. Release Notes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15-4.html" title="E.2. Release 15.4">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15-5"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.1. Release 15.5</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15-5.html#id-1.11.6.5.4">E.1.1. Migration to Version 15.5</a></span></dt><dt><span class="sect2"><a href="release-15-5.html#id-1.11.6.5.5">E.1.2. Changes</a></span></dt></dl></div><p><strong>Release date: </strong>2023-11-09</p><p>
+ This release contains a variety of fixes from 15.4.
+ For information about new features in major release 15, see
+ <a class="xref" href="release-15.html" title="E.6. Release 15">Section E.6</a>.
+ </p><div class="sect2" id="id-1.11.6.5.4"><div class="titlepage"><div><div><h3 class="title">E.1.1. Migration to Version 15.5</h3></div></div></div><p>
+ A dump/restore is not required for those running 15.X.
+ </p><p>
+ However, several mistakes have been discovered that could lead to
+ certain types of indexes yielding wrong search results or being
+ unnecessarily inefficient. It is advisable
+ to <code class="command">REINDEX</code> potentially-affected indexes after
+ installing this update. See the fourth through seventh changelog
+ entries below.
+ </p><p>
+ Also, if you are upgrading from a version earlier than 15.4,
+ see <a class="xref" href="release-15-4.html" title="E.2. Release 15.4">Section E.2</a>.
+ </p></div><div class="sect2" id="id-1.11.6.5.5"><div class="titlepage"><div><div><h3 class="title">E.1.2. Changes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Fix handling of unknown-type arguments
+ in <code class="literal">DISTINCT</code> <code class="type">"any"</code> aggregate
+ functions (Tom Lane)
+ </p><p>
+ This error led to a <code class="type">text</code>-type value being interpreted
+ as an <code class="type">unknown</code>-type value (that is, a zero-terminated
+ string) at runtime. This could result in disclosure of server
+ memory following the <code class="type">text</code> value.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks Jingzhou Fu
+ for reporting this problem.
+ (CVE-2023-5868)
+ </p></li><li class="listitem"><p>
+ Detect integer overflow while computing new array dimensions
+ (Tom Lane)
+ </p><p>
+ When assigning new elements to array subscripts that are outside the
+ current array bounds, an undetected integer overflow could occur in
+ edge cases. Memory stomps that are potentially exploitable for
+ arbitrary code execution are possible, and so is disclosure of
+ server memory.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks Pedro
+ Gallegos for reporting this problem.
+ (CVE-2023-5869)
+ </p></li><li class="listitem"><p>
+ Prevent the <code class="literal">pg_signal_backend</code> role from
+ signalling background workers and autovacuum processes
+ (Noah Misch, Jelte Fennema-Nio)
+ </p><p>
+ The documentation says that <code class="literal">pg_signal_backend</code>
+ cannot issue signals to superuser-owned processes. It was able to
+ signal these background processes, though, because they advertise a
+ role OID of zero. Treat that as indicating superuser ownership.
+ The security implications of cancelling one of these process types
+ are fairly small so far as the core code goes (we'll just start
+ another one), but extensions might add background workers that are
+ more vulnerable.
+ </p><p>
+ Also ensure that the <code class="varname">is_superuser</code> parameter is
+ set correctly in such processes. No specific security consequences
+ are known for that oversight, but it might be significant for some
+ extensions.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> Project thanks
+ Hemanth Sandrana and Mahendrakar Srinivasarao
+ for reporting this problem.
+ (CVE-2023-5870)
+ </p></li><li class="listitem"><p>
+ Fix misbehavior during recursive page split in GiST index build
+ (Heikki Linnakangas)
+ </p><p>
+ Fix a case where the location of a page downlink was incorrectly
+ tracked, and introduce some logic to allow recovering from such
+ situations rather than silently doing the wrong thing. This error
+ could result in incorrect answers from subsequent index searches.
+ It may be advisable to reindex all GiST indexes after installing
+ this update.
+ </p></li><li class="listitem"><p>
+ Prevent de-duplication of btree index entries
+ for <code class="type">interval</code> columns (Noah Misch)
+ </p><p>
+ There are <code class="type">interval</code> values that are distinguishable but
+ compare equal, for example <code class="literal">24:00:00</code>
+ and <code class="literal">1 day</code>. This breaks assumptions made by btree
+ de-duplication, so <code class="type">interval</code> columns need to be excluded
+ from de-duplication. This oversight can cause incorrect results
+ from index-only scans. Moreover, after
+ updating <span class="application">amcheck</span> will report an error for
+ almost all such indexes. Users should reindex any btree indexes
+ on <code class="type">interval</code> columns.
+ </p></li><li class="listitem"><p>
+ Process <code class="type">date</code> values more sanely in
+ BRIN <code class="literal">datetime_minmax_multi_ops</code> indexes
+ (Tomas Vondra)
+ </p><p>
+ The distance calculation for dates was backward, causing poor
+ decisions about which entries to merge. The index still produces
+ correct results, but is much less efficient than it should be.
+ Reindexing BRIN <code class="literal">minmax_multi</code> indexes
+ on <code class="type">date</code> columns is advisable.
+ </p></li><li class="listitem"><p>
+ Process large <code class="type">timestamp</code> and <code class="type">timestamptz</code>
+ values more sanely in
+ BRIN <code class="literal">datetime_minmax_multi_ops</code> indexes
+ (Tomas Vondra)
+ </p><p>
+ Infinities were mistakenly treated as having distance zero rather
+ than a large distance from other values, causing poor decisions
+ about which entries to merge. Also, finite-but-very-large values
+ (near the endpoints of the representable timestamp range) could
+ result in internal overflows, again causing poor decisions. The
+ index still produces correct results, but is much less efficient
+ than it should be. Reindexing BRIN <code class="literal">minmax_multi</code>
+ indexes on <code class="type">timestamp</code> and <code class="type">timestamptz</code>
+ columns is advisable if the column contains, or has contained,
+ infinities or large finite values.
+ </p></li><li class="listitem"><p>
+ Avoid calculation overflows in
+ BRIN <code class="literal">interval_minmax_multi_ops</code> indexes with
+ extreme interval values (Tomas Vondra)
+ </p><p>
+ This bug might have caused unexpected failures while trying to
+ insert large interval values into such an index.
+ </p></li><li class="listitem"><p>
+ Fix partition step generation and runtime partition pruning for
+ hash-partitioned tables with multiple partition keys (David Rowley)
+ </p><p>
+ Some cases involving an <code class="literal">IS NULL</code> condition on one
+ of the partition keys could result in a crash.
+ </p></li><li class="listitem"><p>
+ Fix inconsistent rechecking of concurrently-updated rows
+ during <code class="command">MERGE</code> (Dean Rasheed)
+ </p><p>
+ In <code class="literal">READ COMMITTED</code> mode, an update that finds that
+ its target row was just updated by a concurrent transaction will
+ recheck the query's <code class="literal">WHERE</code> conditions on the
+ updated row. <code class="command">MERGE</code> failed to ensure that the
+ proper rows of other joined tables were used during this recheck,
+ possibly resulting in incorrect decisions about whether the
+ newly-updated row should be updated again
+ by <code class="command">MERGE</code>.
+ </p></li><li class="listitem"><p>
+ Correctly identify the target table in an
+ inherited <code class="command">UPDATE</code>/<code class="command">DELETE</code>/<code class="command">MERGE</code>
+ even when the parent table is excluded by constraints (Amit Langote,
+ Tom Lane)
+ </p><p>
+ If the initially-named table is excluded by constraints, but not all
+ its inheritance descendants are, the first non-excluded descendant
+ was identified as the primary target table. This would lead to
+ firing statement-level triggers associated with that table, rather
+ than the initially-named table as should happen. In v16, the same
+ oversight could also lead to <span class="quote">“<span class="quote">invalid perminfoindex 0 in RTE
+ with relid NNNN</span>”</span> errors.
+ </p></li><li class="listitem"><p>
+ Fix edge case in btree mark/restore processing of ScalarArrayOpExpr
+ clauses (Peter Geoghegan)
+ </p><p>
+ When restoring an indexscan to a previously marked position, the
+ code could miss required setup steps if the scan had advanced
+ exactly to the end of the matches for a ScalarArrayOpExpr (that is,
+ an <code class="literal">indexcol = ANY(ARRAY[])</code>) clause. This could
+ result in missing some rows that should have been fetched.
+ </p></li><li class="listitem"><p>
+ Fix intra-query memory leak in Memoize execution
+ (Orlov Aleksej, David Rowley)
+ </p></li><li class="listitem"><p>
+ Fix intra-query memory leak when a set-returning function repeatedly
+ returns zero rows (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Don't crash if <code class="function">cursor_to_xmlschema()</code> is applied
+ to a non-data-returning Portal (Boyu Yang)
+ </p></li><li class="listitem"><p>
+ Throw the intended error if <code class="function">pgrowlocks()</code> is
+ applied to a partitioned table (David Rowley)
+ </p><p>
+ Previously, a not-on-point complaint <span class="quote">“<span class="quote">only heap AM is
+ supported</span>”</span> would be raised.
+ </p></li><li class="listitem"><p>
+ Handle invalid indexes more cleanly in assorted SQL functions
+ (Noah Misch)
+ </p><p>
+ Report an error if <code class="function">pgstatindex()</code>,
+ <code class="function">pgstatginindex()</code>,
+ <code class="function">pgstathashindex()</code>,
+ or <code class="function">pgstattuple()</code> is applied to an invalid
+ index. If <code class="function">brin_desummarize_range()</code>,
+ <code class="function">brin_summarize_new_values()</code>,
+ <code class="function">brin_summarize_range()</code>,
+ or <code class="function">gin_clean_pending_list()</code> is applied to an
+ invalid index, do nothing except to report a debug-level message.
+ Formerly these functions attempted to process the index, and might
+ fail in strange ways depending on what the failed <code class="command">CREATE
+ INDEX</code> had left behind.
+ </p></li><li class="listitem"><p>
+ Fix <code class="function">pg_stat_reset_single_table_counters()</code> to do
+ the right thing for a shared catalog (Masahiro Ikeda)
+ </p><p>
+ Previously the reset would be ineffective.
+ </p></li><li class="listitem"><p>
+ Avoid premature memory allocation failure with long inputs
+ to <code class="function">to_tsvector()</code> (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Fix over-allocation of the constructed <code class="type">tsvector</code>
+ in <code class="function">tsvectorrecv()</code> (Denis Erokhin)
+ </p><p>
+ If the incoming vector includes position data, the binary receive
+ function left wasted space (roughly equal to the size of the
+ position data) in the finished <code class="type">tsvector</code>. In extreme
+ cases this could lead to <span class="quote">“<span class="quote">maximum total lexeme length
+ exceeded</span>”</span> failures for vectors that were under the length
+ limit when emitted. In any case it could lead to wasted space
+ on-disk.
+ </p></li><li class="listitem"><p>
+ Fix incorrect coding in <code class="function">gtsvector_picksplit()</code>
+ (Alexander Lakhin)
+ </p><p>
+ This could lead to poor page-split decisions in GiST indexes
+ on <code class="type">tsvector</code> columns.
+ </p></li><li class="listitem"><p>
+ Improve checks for corrupt PGLZ compressed data (Flavien Guedez)
+ </p></li><li class="listitem"><p>
+ In <code class="command">COPY FROM</code>, fail cleanly when an unsupported
+ encoding conversion is needed (Tom Lane)
+ </p><p>
+ Recent refactoring accidentally removed the intended error check for
+ this, such that it ended in <span class="quote">“<span class="quote">cache lookup failed for function
+ 0</span>”</span> instead of a useful error message.
+ </p></li><li class="listitem"><p>
+ Avoid crash in <code class="command">EXPLAIN</code> if a parameter marked to
+ be displayed by <code class="command">EXPLAIN</code> has a NULL boot-time
+ value (Xing Guo, Aleksander Alekseev, Tom Lane)
+ </p><p>
+ No built-in parameter fits this description, but an extension could
+ define such a parameter.
+ </p></li><li class="listitem"><p>
+ Ensure we have a snapshot while dropping <code class="literal">ON COMMIT
+ DROP</code> temp tables (Tom Lane)
+ </p><p>
+ This prevents possible misbehavior if any catalog entries for the
+ temp tables have fields wide enough to require toasting (such as a
+ very complex <code class="literal">CHECK</code> condition).
+ </p></li><li class="listitem"><p>
+ Avoid improper response to shutdown signals in child processes
+ just forked by <code class="function">system()</code> (Nathan Bossart)
+ </p><p>
+ This fix avoids a race condition in which a child process that has
+ been forked off by <code class="function">system()</code>, but hasn't yet
+ exec'd the intended child program, might receive and act on a signal
+ intended for the parent server process. That would lead to
+ duplicate cleanup actions being performed, which will not end well.
+ </p></li><li class="listitem"><p>
+ Cope with torn reads of <code class="filename">pg_control</code> in frontend
+ programs (Thomas Munro)
+ </p><p>
+ On some file systems, reading <code class="filename">pg_control</code> may
+ not be an atomic action when the server concurrently writes that
+ file. This is detectable via a bad CRC. Retry a few times to see
+ if the file becomes valid before we report error.
+ </p></li><li class="listitem"><p>
+ Avoid torn reads of <code class="filename">pg_control</code> in relevant SQL
+ functions (Thomas Munro)
+ </p><p>
+ Acquire the appropriate lock before
+ reading <code class="filename">pg_control</code>, to ensure we get a
+ consistent view of that file.
+ </p></li><li class="listitem"><p>
+ Avoid integer overflow when computing size of backend activity
+ string array (Jakub Wartak)
+ </p><p>
+ On 64-bit machines we will allow values
+ of <code class="varname">track_activity_query_size</code> large enough to
+ cause 32-bit overflow when multiplied by the allowed number of
+ connections. The code actually allocating the per-backend local
+ array was careless about this though, and allocated the array
+ incorrectly.
+ </p></li><li class="listitem"><p>
+ Fix briefly showing inconsistent progress statistics
+ for <code class="command">ANALYZE</code> on inherited tables
+ (Heikki Linnakangas)
+ </p><p>
+ The block-level counters should be reset to zero at the same time we
+ update the current-relation field.
+ </p></li><li class="listitem"><p>
+ Fix the background writer to report any WAL writes it makes to the
+ statistics counters (Nazir Bilal Yavuz)
+ </p></li><li class="listitem"><p>
+ Fix confusion about forced-flush behavior
+ in <code class="function">pgstat_report_wal()</code>
+ (Ryoga Yoshida, Michael Paquier)
+ </p><p>
+ This could result in some statistics about WAL I/O being forgotten
+ in a shutdown.
+ </p></li><li class="listitem"><p>
+ Track the dependencies of cached <code class="command">CALL</code> statements,
+ and re-plan them when needed (Tom Lane)
+ </p><p>
+ DDL commands, such as replacement of a function that has been
+ inlined into a <code class="command">CALL</code> argument, can create the need
+ to re-plan a <code class="command">CALL</code> that has been cached by
+ PL/pgSQL. That was not happening, leading to misbehavior or strange
+ errors such as <span class="quote">“<span class="quote">cache lookup failed</span>”</span>.
+ </p></li><li class="listitem"><p>
+ Avoid a possible pfree-a-NULL-pointer crash after an error in
+ OpenSSL connection setup (Sergey Shinderuk)
+ </p></li><li class="listitem"><p>
+ Track nesting depth correctly when
+ inspecting <code class="type">RECORD</code>-type Vars from outer query levels
+ (Richard Guo)
+ </p><p>
+ This oversight could lead to assertion failures, core dumps,
+ or <span class="quote">“<span class="quote">bogus varno</span>”</span> errors.
+ </p></li><li class="listitem"><p>
+ Track hash function and negator function dependencies of
+ ScalarArrayOpExpr plan nodes (David Rowley)
+ </p><p>
+ In most cases this oversight was harmless, since these functions
+ would be unlikely to disappear while the node's original operator
+ remains present.
+ </p></li><li class="listitem"><p>
+ Fix error-handling bug in <code class="type">RECORD</code> type cache management
+ (Thomas Munro)
+ </p><p>
+ An out-of-memory error occurring at just the wrong point could leave
+ behind inconsistent state that would lead to an infinite loop.
+ </p></li><li class="listitem"><p>
+ Fix assertion failure when logical decoding is retried in the same
+ session after an error (Hou Zhijie)
+ </p></li><li class="listitem"><p>
+ Treat out-of-memory failures as fatal while reading WAL
+ (Michael Paquier)
+ </p><p>
+ Previously this would be treated as a bogus-data condition, leading
+ to the conclusion that we'd reached the end of WAL, which is
+ incorrect and could lead to inconsistent WAL replay.
+ </p></li><li class="listitem"><p>
+ Fix possible recovery failure due to trying to allocate memory based
+ on a bogus WAL record length field (Thomas Munro, Michael Paquier)
+ </p></li><li class="listitem"><p>
+ Fix race condition in database dropping that could lead to the
+ autovacuum launcher getting stuck (Andres Freund, Will Mortensen,
+ Jacob Speidel)
+ </p><p>
+ The race could lead to a statistics entry for the removed database
+ remaining present, confusing the launcher's selection of which
+ database to process.
+ </p></li><li class="listitem"><p>
+ Fix datatype size confusion in logical tape management
+ (Ranier Vilela)
+ </p><p>
+ Integer overflow was possible on platforms where long is wider than
+ int, although it would take a multiple-terabyte temporary file to
+ cause a problem.
+ </p></li><li class="listitem"><p>
+ Avoid unintended close of syslogger process's stdin
+ (Heikki Linnakangas)
+ </p></li><li class="listitem"><p>
+ Avoid doing plan cache revalidation of utility statements
+ that do not receive interesting processing during parse analysis
+ (Tom Lane)
+ </p><p>
+ Aside from saving a few cycles, this prevents failure after a cache
+ invalidation for statements that must not set a snapshot, such
+ as <code class="command">SET TRANSACTION ISOLATION LEVEL</code>.
+ </p></li><li class="listitem"><p>
+ Keep by-reference <code class="structfield">attmissingval</code> values in
+ a long-lived context while they are being used (Andrew Dunstan)
+ </p><p>
+ This avoids possible use of dangling pointers when a tuple slot
+ outlives the tuple descriptor with which its value was constructed.
+ </p></li><li class="listitem"><p>
+ Recalculate the effective value of <code class="varname">search_path</code>
+ after <code class="command">ALTER ROLE</code> (Jeff Davis)
+ </p><p>
+ This ensures that after renaming a role, the meaning of the special
+ string <code class="literal">$user</code> is re-determined.
+ </p></li><li class="listitem"><p>
+ Fix <span class="quote">“<span class="quote">could not duplicate handle</span>”</span> error occurring on
+ Windows when <code class="varname">min_dynamic_shared_memory</code> is set
+ above zero (Thomas Munro)
+ </p></li><li class="listitem"><p>
+ Fix order of operations in <code class="function">GenericXLogFinish</code>
+ (Jeff Davis)
+ </p><p>
+ This code violated the conditions required for crash safety by
+ writing WAL before marking changed buffers dirty. No core code uses
+ this function, but extensions do (<code class="filename">contrib/bloom</code>
+ does, for example).
+ </p></li><li class="listitem"><p>
+ Remove incorrect assertion in PL/Python exception handling
+ (Alexander Lakhin)
+ </p></li><li class="listitem"><p>
+ Fix assertion failure in <span class="application">pg_dump</span> when
+ it's asked to dump the <code class="literal">pg_catalog</code> schema (Peter
+ Eisentraut)
+ </p></li><li class="listitem"><p>
+ Fix <span class="application">pg_restore</span> so that selective restores
+ will include both table-level and column-level ACLs for selected
+ tables (Euler Taveira, Tom Lane)
+ </p><p>
+ Formerly, only the table-level ACL would get restored if both types
+ were present.
+ </p></li><li class="listitem"><p>
+ Add logic to <span class="application">pg_upgrade</span> to check for use
+ of <code class="type">abstime</code>, <code class="type">reltime</code>,
+ and <code class="type">tinterval</code> data types (Álvaro Herrera)
+ </p><p>
+ These obsolete data types were removed
+ in <span class="productname">PostgreSQL</span> version 12, so check to
+ make sure they aren't present in an older database before claiming
+ it can be upgraded.
+ </p></li><li class="listitem"><p>
+ Avoid generating invalid temporary slot names
+ in <span class="application">pg_basebackup</span> (Jelte Fennema)
+ </p><p>
+ This has only been seen to occur when the server connection runs
+ through <span class="application">pgbouncer</span>.
+ </p></li><li class="listitem"><p>
+ Avoid false <span class="quote">“<span class="quote">too many client connections</span>”</span> errors
+ in <span class="application">pgbench</span> on Windows (Noah Misch)
+ </p></li><li class="listitem"><p>
+ In <code class="filename">contrib/amcheck</code>, do not report interrupted
+ page deletion as corruption (Noah Misch)
+ </p><p>
+ This fix prevents false-positive reports of <span class="quote">“<span class="quote">the first child
+ of leftmost target page is not leftmost of its
+ level</span>”</span>, <span class="quote">“<span class="quote">block NNNN is not leftmost</span>”</span>
+ or <span class="quote">“<span class="quote">left link/right link pair in index XXXX not in
+ agreement</span>”</span>. They appeared
+ if <span class="application">amcheck</span> ran after an unfinished btree
+ index page deletion and before <code class="command">VACUUM</code> had cleaned
+ things up.
+ </p></li><li class="listitem"><p>
+ Fix failure of <code class="filename">contrib/btree_gin</code> indexes
+ on <code class="type">interval</code> columns,
+ when an indexscan using the <code class="literal">&lt;</code>
+ or <code class="literal">&lt;=</code> operator is performed (Dean Rasheed)
+ </p><p>
+ Such an indexscan failed to return all the entries it should.
+ </p></li><li class="listitem"><p>
+ Add support for LLVM 16 and 17 (Thomas Munro, Dmitry Dolgov)
+ </p></li><li class="listitem"><p>
+ Suppress assorted build-time warnings on
+ recent <span class="productname">macOS</span> (Tom Lane)
+ </p><p>
+ <span class="productname">Xcode 15</span> (released
+ with <span class="productname">macOS Sonoma</span>) changed the linker's
+ behavior in a way that causes many duplicate-library warnings while
+ building <span class="productname">PostgreSQL</span>. These were
+ harmless, but they're annoying so avoid citing the same libraries
+ twice. Also remove use of the <code class="option">-multiply_defined
+ suppress</code> linker switch, which apparently has been a no-op
+ for a long time, and is now actively complained of.
+ </p></li><li class="listitem"><p>
+ When building <code class="filename">contrib/unaccent</code>'s rules file,
+ fall back to using <code class="literal">python</code>
+ if <code class="literal">--with-python</code> was not given and make
+ variable <code class="literal">PYTHON</code> was not set (Japin Li)
+ </p></li><li class="listitem"><p>
+ Remove <code class="literal">PHOT</code> (Phoenix Islands Time) from the
+ default timezone abbreviations list (Tom Lane)
+ </p><p>
+ Presence of this abbreviation in the default list can cause failures
+ on recent Debian and Ubuntu releases, as they no longer install the
+ underlying tzdb entry by default. Since this is a made-up
+ abbreviation for a zone with a total human population of about two
+ dozen, it seems unlikely that anyone will miss it. If someone does,
+ they can put it back via a custom abbreviations file.
+ </p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release.html" title="Appendix E. Release Notes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15-4.html" title="E.2. Release 15.4">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix E. Release Notes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.2. Release 15.4</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-15.html b/doc/src/sgml/html/release-15.html
new file mode 100644
index 0000000..c2e72f8
--- /dev/null
+++ b/doc/src/sgml/html/release-15.html
@@ -0,0 +1,1113 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.6. Release 15</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15-1.html" title="E.5. Release 15.1" /><link rel="next" href="release-prior.html" title="E.7. Prior Releases" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.6. Release 15</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15-1.html" title="E.5. Release 15.1">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-prior.html" title="E.7. Prior Releases">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-15"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.6. Release 15</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.3">E.6.1. Overview</a></span></dt><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.4">E.6.2. Migration to Version 15</a></span></dt><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.5">E.6.3. Changes</a></span></dt><dt><span class="sect2"><a href="release-15.html#RELEASE-15-ACKNOWLEDGEMENTS">E.6.4. Acknowledgments</a></span></dt></dl></div><p><strong>Release date: </strong>2022-10-13</p><div class="sect2" id="id-1.11.6.10.3"><div class="titlepage"><div><div><h3 class="title">E.6.1. Overview</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> 15 contains many new features
+ and enhancements, including:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Support for the <acronym class="acronym">SQL</acronym>
+ <a class="link" href="sql-merge.html" title="MERGE"><code class="command">MERGE</code></a> command.
+ </p></li><li class="listitem"><p>
+ Selective publication of tables' contents within
+ <a class="link" href="logical-replication.html" title="Chapter 31. Logical Replication">logical replication</a>
+ publications, through the ability to specify column lists and
+ row filter conditions.
+ </p></li><li class="listitem"><p>
+ More options for compression, including support for Zstandard (zstd)
+ compression. This includes support for performing compression on
+ the server side during
+ <a class="link" href="app-pgbasebackup.html" title="pg_basebackup"><span class="application">pg_basebackup</span></a>.
+ </p></li><li class="listitem"><p>
+ Support for structured <a class="link" href="runtime-config-logging.html#GUC-LOG-DESTINATION">server
+ log output</a> using the <acronym class="acronym">JSON</acronym> format.
+ </p></li><li class="listitem"><p>
+ Performance improvements, particularly for in-memory and on-disk
+ sorting.
+ </p></li></ul></div><p>
+ The above items and other new features of
+ <span class="productname">PostgreSQL</span> 15 are explained in more detail
+ in the sections below.
+ </p></div><div class="sect2" id="id-1.11.6.10.4"><div class="titlepage"><div><div><h3 class="title">E.6.2. Migration to Version 15</h3></div></div></div><p>
+ A dump/restore using <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a> or use of
+ <a class="xref" href="pgupgrade.html" title="pg_upgrade"><span class="refentrytitle"><span class="application">pg_upgrade</span></span></a> or logical replication is required for
+ those wishing to migrate data from any previous release. See <a class="xref" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Section 19.6</a> for general information on migrating to new
+ major releases.
+ </p><p>
+ Version 15 contains a number of changes that may affect compatibility
+ with previous releases. Observe the following incompatibilities:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Remove <code class="literal">PUBLIC</code> creation permission on the <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PUBLIC" title="5.9.2. The Public Schema"><code class="literal">public</code> schema</a>
+ (Noah Misch)
+ </p><p>
+ The new default is one of the secure schema usage patterns that <a class="xref" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">Section 5.9.6</a> has recommended since the security
+ release for CVE-2018-1058. The change applies to new database
+ clusters and to newly-created databases in existing clusters.
+ Upgrading a cluster or restoring a database dump will preserve
+ <code class="literal">public</code>'s existing permissions.
+ </p><p>
+ For existing databases, especially those having multiple users,
+ consider revoking <code class="literal">CREATE</code> permission on
+ the <code class="literal">public</code> schema to adopt this new default.
+ For new databases having no need to defend against insider threats,
+ granting <code class="literal">CREATE</code> permission will yield the behavior
+ of prior releases.
+ </p></li><li class="listitem"><p>
+ Change the owner of the <code class="literal">public</code> schema to be the
+ new <code class="literal">pg_database_owner</code> role (Noah Misch)
+ </p><p>
+ This allows each database's owner to have ownership privileges on
+ the <code class="literal">public</code> schema within their database.
+ Previously it was owned by the bootstrap superuser, so that
+ non-superuser database owners could not do anything with it.
+ </p><p>
+ This change applies to new database clusters and to newly-created
+ databases in existing clusters.
+ Upgrading a cluster or restoring a database dump will preserve
+ <code class="literal">public</code>'s existing ownership specification.
+ </p></li><li class="listitem"><p>
+ Remove long-deprecated <a class="link" href="continuous-archiving.html#BACKUP-BASE-BACKUP" title="26.3.2. Making a Base Backup">exclusive
+ backup mode</a> (David Steele, Nathan Bossart)
+ </p><p>
+ If the database server stops abruptly while in this mode, the
+ server could fail to start. The non-exclusive backup mode is
+ considered superior for all purposes. Functions
+ <code class="function">pg_start_backup()</code>/<code class="function">pg_stop_backup()</code>
+ have been renamed to
+ <code class="function">pg_backup_start()</code>/<code class="function">pg_backup_stop()</code>,
+ and the functions <code class="function">pg_backup_start_time()</code>
+ and <code class="function">pg_is_in_backup()</code> have been removed.
+ </p></li><li class="listitem"><p>
+ Increase <a class="link" href="runtime-config-resource.html#GUC-HASH-MEM-MULTIPLIER"><code class="varname">hash_mem_multiplier</code></a>
+ default to 2.0 (Peter Geoghegan)
+ </p><p>
+ This allows query hash operations to use more
+ <a class="link" href="runtime-config-resource.html#GUC-WORK-MEM"><code class="varname">work_mem</code></a>
+ memory than other operations.
+ </p></li><li class="listitem"><p>
+ Remove server-side language <a class="link" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language"><code class="literal">plpython2u</code></a> and generic
+ Python language <code class="literal">plpythonu</code> (Andres Freund)
+ </p><p>
+ Python 2.x is no longer supported. While the original intent of
+ <code class="literal">plpythonu</code> was that it could eventually refer
+ to <code class="literal">plpython3u</code>, changing it now seems more likely
+ to cause problems than solve them, so it's just been removed.
+ </p></li><li class="listitem"><p>
+ Generate an error if <a class="link" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-TABLE" title="Table 9.43. Text Search Functions"><code class="function">array_to_tsvector()</code></a>
+ is passed an empty-string array element (Jean-Christophe Arnu)
+ </p><p>
+ This is prohibited because lexemes should never be empty. Users of
+ previous Postgres releases should verify that no empty lexemes
+ are stored because they can lead to dump/restore failures and
+ inconsistent results.
+ </p></li><li class="listitem"><p>
+ Generate an error when <a class="link" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators"><code class="function">chr()</code></a>
+ is supplied with a negative argument (Peter Eisentraut)
+ </p></li><li class="listitem"><p>
+ Prevent <a class="link" href="sql-createview.html" title="CREATE VIEW"><code class="command">CREATE OR REPLACE
+ VIEW</code></a> from changing the collation of an output column
+ (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Disallow zero-length <a class="link" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS" title="4.1.1. Identifiers and Key Words">Unicode identifiers</a>,
+ e.g., <code class="literal">U&amp;""</code>
+ (Peter Eisentraut)
+ </p><p>
+ Non-Unicode zero-length identifiers were already disallowed.
+ </p></li><li class="listitem"><p>
+ Prevent <a class="link" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-NUMERIC" title="4.1.2.6. Numeric Constants">numeric
+ literals</a> from having non-numeric trailing characters (Peter
+ Eisentraut)
+ </p><p>
+ Previously, query text like <code class="literal">123abc</code> would be
+ interpreted as <code class="literal">123</code> followed
+ by a separate token <code class="literal">abc</code>.
+ </p></li><li class="listitem"><p>
+ Adjust <a class="link" href="datatype-json.html" title="8.14. JSON Types"><acronym class="acronym">JSON</acronym></a>
+ numeric literal processing to match the
+ <acronym class="acronym">SQL</acronym>/<acronym class="acronym">JSON</acronym>-standard (Peter
+ Eisentraut)
+ </p><p>
+ This accepts numeric formats like <code class="literal">.1</code> and
+ <code class="literal">1.</code>, and disallows trailing junk after numeric
+ literals, like <code class="literal">1.type()</code>.
+ </p></li><li class="listitem"><p>
+ When <a class="link" href="datatype-datetime.html" title="8.5. Date/Time Types"><code class="type">interval</code></a>
+ input provides a fractional value for a unit greater than months,
+ round to the nearest month (Bruce Momjian)
+ </p><p>
+ For example, convert <code class="literal">1.99 years</code> to <code class="literal">2
+ years</code>, not <code class="literal">1 year 11 months</code> as before.
+ </p></li><li class="listitem"><p>
+ Improve consistency of <code class="type">interval</code> parsing with trailing
+ periods (Tom Lane)
+ </p><p>
+ Numbers with trailing periods were rejected on some platforms.
+ </p></li><li class="listitem"><p>
+ Mark the <code class="type">interval</code> output
+ function as stable, not immutable, since it depends on <a class="link" href="runtime-config-client.html#GUC-INTERVALSTYLE"><code class="varname">IntervalStyle</code></a>
+ (Tom Lane)
+ </p><p>
+ This will, for example, cause creation of indexes relying on the
+ text output of <code class="type">interval</code> values to fail.
+ </p></li><li class="listitem"><p>
+ Detect integer overflow in <a class="link" href="functions-datetime.html#FUNCTIONS-DATETIME-TABLE" title="Table 9.33. Date/Time Functions">interval justification
+ functions</a> (Joe Koshakow)
+ </p><p>
+ The affected functions are <code class="function">justify_interval()</code>,
+ <code class="function">justify_hours()</code>, and
+ <code class="function">justify_days()</code>.
+ </p></li><li class="listitem"><p>
+ Change the I/O format of type <code class="type">"char"</code> for non-ASCII
+ characters (Tom Lane)
+ </p><p>
+ Bytes with the high bit set are now output as a backslash and three
+ octal digits, to avoid encoding issues.
+ </p></li><li class="listitem"><p>
+ Remove the default <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="literal">ADMIN
+ OPTION</code></a> privilege a login role has on its own role
+ membership (Robert Haas)
+ </p><p>
+ Previously, a login role could add/remove members of its own role,
+ even without <code class="literal">ADMIN OPTION</code> privilege.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="logical-replication.html" title="Chapter 31. Logical Replication">logical replication</a>
+ to run as the owner of the subscription (Mark Dilger)
+ </p><p>
+ Because row-level security policies are not checked, only superusers,
+ roles with <code class="literal">bypassrls</code>, and table owners can
+ replicate into tables with row-level security policies.
+ </p></li><li class="listitem"><p>
+ Prevent <code class="command">UPDATE</code> and <code class="command">DELETE</code>
+ <a class="link" href="logical-replication.html" title="Chapter 31. Logical Replication">logical replication</a>
+ operations on tables where the subscription owner does not have
+ <code class="command">SELECT</code> permission on the table (Jeff Davis)
+ </p><p>
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code> commands
+ typically involve reading the table as well, so require the
+ subscription owner to have table <code class="command">SELECT</code>
+ permission.
+ </p></li><li class="listitem"><p>
+ When <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN</code></a>
+ references the session's temporary object schema, refer to it as
+ <code class="literal">pg_temp</code> (Amul Sul)
+ </p><p>
+ Previously the actual schema name was reported, leading to
+ inconsistencies across sessions.
+ </p></li><li class="listitem"><p>
+ Fix <a class="link" href="monitoring-stats.html#MONITORING-PG-STATIO-ALL-TABLES-VIEW" title="28.2.19. pg_statio_all_tables"><code class="structname">pg_statio_all_tables</code></a>
+ to sum values for the rare case of <acronym class="acronym">TOAST</acronym> tables
+ with multiple indexes (Andrei Zubkov)
+ </p><p>
+ Previously such cases would show one row for each index.
+ </p></li><li class="listitem"><p>
+ Disallow setting <a class="link" href="runtime-config-custom.html" title="20.16. Customized Options">custom
+ options</a> that match the name of an installed extension, but
+ are not one of the extension's declared variables
+ (Florin Irion, Tom Lane)
+ </p><p>
+ This change causes any such pre-existing variables to be deleted
+ during extension load, and then prevents new ones from being created
+ later in the session. The intent is to prevent confusion about
+ whether a variable is associated with an extension or not.
+ </p></li><li class="listitem"><p>
+ Remove obsolete server variable
+ <code class="varname">stats_temp_directory</code> (Andres Freund, Kyotaro
+ Horiguchi)
+ </p></li><li class="listitem"><p>
+ Improve the algorithm used to compute <a class="link" href="functions-math.html#FUNCTIONS-MATH-RANDOM-TABLE" title="Table 9.6. Random Functions"><code class="function">random()</code></a>
+ (Fabien Coelho)
+ </p><p>
+ This will cause <code class="function">random()</code>'s results to differ
+ from what was emitted by prior versions, even for the same seed
+ value.
+ </p></li><li class="listitem"><p>
+ <span class="application">libpq</span>'s <a class="link" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery()</code></a>
+ function is no longer supported in pipeline mode (Álvaro Herrera)
+ </p><p>
+ Applications that are using that combination will need to be
+ modified to use <code class="function">PQsendQueryParams()</code> instead.
+ </p></li><li class="listitem"><p>
+ On non-Windows platforms, consult the <code class="envar">HOME</code> environment
+ variable to find the user's home directory (Anders Kaseorg)
+ </p><p>
+ If <code class="envar">HOME</code> is empty or unset, fall back to the previous
+ method of checking the <code class="literal">&lt;pwd.h&gt;</code> database.
+ This change affects <span class="application">libpq</span> (for example,
+ while looking up <code class="filename">~/.pgpass</code>) as well as various
+ client application programs.
+ </p></li><li class="listitem"><p>
+ Remove <a class="link" href="app-pgdump.html" title="pg_dump"><span class="application">pg_dump</span></a>'s
+ <code class="option">--no-synchronized-snapshots</code> option (Tom Lane)
+ </p><p>
+ All still-supported server versions support synchronized snapshots,
+ so there's no longer a need for this option.
+ </p></li><li class="listitem"><p>
+ After an error is detected in <a class="link" href="app-psql.html" title="psql"><span class="application">psql</span></a>'s
+ <code class="option">--single-transaction</code> mode, change the
+ final <code class="command">COMMIT</code> command
+ to <code class="command">ROLLBACK</code> only
+ if <code class="varname">ON_ERROR_STOP</code> is set (Michael Paquier)
+ </p></li><li class="listitem"><p>
+ Avoid unnecessary casting of constants in queries sent by <a class="link" href="postgres-fdw.html" title="F.38. postgres_fdw">postgres_fdw</a> (Dian Fay)
+ </p><p>
+ When column types are intentionally different between local and
+ remote databases, such casts could cause errors.
+ </p></li><li class="listitem"><p>
+ Remove <a class="link" href="xml2.html" title="F.50. xml2">xml2</a>'s
+ <code class="function">xml_is_well_formed()</code> function (Tom Lane)
+ </p><p>
+ This function has been implemented in the core backend since
+ Postgres 9.1.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">custom scan providers</a>
+ to indicate if they support projections (Sven Klemm)
+ </p><p>
+ The default is now that custom scan providers are assumed to not
+ support projections; those that do will need to be updated for
+ this release.
+ </p></li></ul></div></div><div class="sect2" id="id-1.11.6.10.5"><div class="titlepage"><div><div><h3 class="title">E.6.3. Changes</h3></div></div></div><p>
+ Below you will find a detailed account of the changes between
+ <span class="productname">PostgreSQL</span> 15 and the previous major
+ release.
+ </p><div class="sect3" id="id-1.11.6.10.5.3"><div class="titlepage"><div><div><h4 class="title">E.6.3.1. Server</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Record and check the collation version of each <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE">database</a> (Peter Eisentraut)
+ </p><p>
+ This feature is designed to detect collation version
+ changes to avoid index corruption. Function
+ <code class="function">pg_database_collation_actual_version()</code>
+ reports the underlying operating system collation version, and
+ <code class="command">ALTER DATABASE ... REFRESH</code> sets the recorded
+ database collation version to match the operating system collation
+ version.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="locale.html" title="24.1. Locale Support"><acronym class="acronym">ICU</acronym></a>
+ collations to be set as the default for clusters and databases
+ (Peter Eisentraut)
+ </p><p>
+ Previously, only <span class="application">libc</span>-based
+ collations could be selected at the cluster and database levels.
+ <acronym class="acronym">ICU</acronym> collations could only be used via explicit
+ <code class="literal">COLLATE</code> clauses.
+ </p></li><li class="listitem"><p>
+ Add system view <a class="link" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings"><code class="structname">pg_ident_file_mappings</code></a>
+ to report <code class="filename">pg_ident.conf</code> information (Julien
+ Rouhaud)
+ </p></li></ul></div><div class="sect4" id="id-1.11.6.10.5.3.3"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.1. <a class="link" href="ddl-partitioning.html" title="5.11. Table Partitioning">Partitioning</a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Improve planning time for queries referencing partitioned tables
+ (David Rowley)
+ </p><p>
+ This change helps when only a few of many partitions are relevant.
+ </p></li><li class="listitem"><p>
+ Allow ordered scans of partitions to avoid sorting in more cases
+ (David Rowley)
+ </p><p>
+ Previously, a partitioned table with a <code class="literal">DEFAULT</code>
+ partition or a <code class="literal">LIST</code> partition containing
+ multiple values could not be used for ordered partition scans.
+ Now they can be used if such partitions are pruned during planning.
+ </p></li><li class="listitem"><p>
+ Improve foreign key behavior of updates on partitioned tables
+ that move rows between partitions (Amit Langote)
+ </p><p>
+ Previously, such updates ran a delete action on the source
+ partition and an insert action on the target partition.
+ <span class="productname">PostgreSQL</span> will now run an update action
+ on the partition root, providing cleaner semantics.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="sql-cluster.html" title="CLUSTER"><code class="command">CLUSTER</code></a>
+ on partitioned tables (Justin Pryzby)
+ </p></li><li class="listitem"><p>
+ Fix <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TRIGGER
+ RENAME</code></a> on partitioned tables to properly rename
+ triggers on all partitions (Arne Roland, Álvaro Herrera)
+ </p><p>
+ Also prohibit cloned triggers from being renamed.
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.4"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.2. Indexes</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow btree indexes on system and <a class="link" href="storage-toast.html" title="73.2. TOAST"><acronym class="acronym">TOAST</acronym></a>
+ tables to efficiently store duplicates (Peter Geoghegan)
+ </p><p>
+ Previously de-duplication was disabled for these types of indexes.
+ </p></li><li class="listitem"><p>
+ Improve lookup performance
+ of <a class="link" href="gist.html" title="Chapter 68. GiST Indexes"><acronym class="acronym">GiST</acronym></a> indexes
+ that were built using sorting (Aliaksandr Kalenik, Sergei
+ Shoulbakov, Andrey Borodin)
+ </p></li><li class="listitem"><p>
+ Allow unique constraints and indexes to treat
+ <code class="literal">NULL</code> values as not distinct (Peter Eisentraut)
+ </p><p>
+ Previously <code class="literal">NULL</code> entries were always treated
+ as distinct values, but this can now be changed by creating
+ constraints and indexes using <code class="literal">UNIQUE NULLS NOT
+ DISTINCT</code>.
+ </p></li><li class="listitem"><p>
+ Allow the <a class="link" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators"><code class="literal">^@</code></a>
+ starts-with operator and the <code class="function">starts_with()</code>
+ function to use btree indexes if using the C collation (Tom Lane)
+ </p><p>
+ Previously these could only use <a class="link" href="spgist.html" title="Chapter 69. SP-GiST Indexes"><acronym class="acronym">SP-GiST</acronym></a> indexes.
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.5"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.3. Optimizer</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <a class="link" href="sql-createstatistics.html" title="CREATE STATISTICS">extended
+ statistics</a> to record statistics for a parent with all its
+ children (Tomas Vondra, Justin Pryzby)
+ </p><p>
+ Regular statistics already tracked parent and
+ parent-plus-all-children statistics separately.
+ </p></li><li class="listitem"><p>
+ Add server variable <a class="link" href="runtime-config-query.html#GUC-RECURSIVE-WORKTABLE-FACTOR"><code class="varname">recursive_worktable_factor</code></a>
+ to allow the user to specify the expected size of the working
+ table of a <a class="link" href="queries-with.html#QUERIES-WITH-RECURSIVE" title="7.8.2. Recursive Queries">recursive
+ query</a> (Simon Riggs)
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.6"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.4. General Performance</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow hash lookup for <a class="link" href="functions-subquery.html#FUNCTIONS-SUBQUERY-NOTIN" title="9.23.3. NOT IN"><code class="literal">NOT IN</code></a>
+ clauses with many constants (David Rowley, James Coleman)
+ </p><p>
+ Previously the code always sequentially scanned the list of values.
+ </p></li><li class="listitem"><p>
+ Allow <code class="command">SELECT DISTINCT</code> to be parallelized
+ (David Rowley)
+ </p></li><li class="listitem"><p>
+ Speed up encoding validation of <acronym class="acronym">UTF</acronym>-8 text
+ by processing 16 bytes at a time
+ (John Naylor, Heikki Linnakangas)
+ </p><p>
+ This will improve text-heavy operations like <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY FROM</code></a>.
+ </p></li><li class="listitem"><p>
+ Improve performance for sorts that exceed <a class="link" href="runtime-config-resource.html#GUC-WORK-MEM"><code class="varname">work_mem</code></a>
+ (Heikki Linnakangas)
+ </p><p>
+ When the sort data no longer fits in <code class="varname">work_mem</code>,
+ switch to a batch sorting algorithm that uses more output streams
+ than before.
+ </p></li><li class="listitem"><p>
+ Improve performance and reduce memory consumption of in-memory
+ sorts (Ronan Dunklau, David Rowley, Thomas Munro, John Naylor)
+ </p></li><li class="listitem"><p>
+ Allow <acronym class="acronym">WAL</acronym> <a class="link" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full page writes</a> to use
+ LZ4 and Zstandard compression (Andrey Borodin, Justin Pryzby)
+ </p><p>
+ This is controlled by the <a class="link" href="runtime-config-wal.html#GUC-WAL-COMPRESSION"><code class="varname">wal_compression</code></a>
+ server setting.
+ </p></li><li class="listitem"><p>
+ Add support for writing <acronym class="acronym">WAL</acronym>
+ using <a class="link" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">direct I/O</a> on
+ macOS (Thomas Munro)
+ </p><p>
+ This only works if <code class="literal">max_wal_senders = 0</code>
+ and <code class="literal">wal_level = minimal</code>.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">vacuum</a> to be more
+ aggressive in setting the oldest frozen and multi transaction id
+ (Peter Geoghegan)
+ </p></li><li class="listitem"><p>
+ Allow a query referencing multiple <a class="link" href="ddl-foreign-data.html" title="5.12. Foreign Data">foreign tables</a> to perform
+ parallel foreign table scans in more cases (Andrey Lepikhov,
+ Etsuro Fujita)
+ </p></li><li class="listitem"><p>
+ Improve the performance of <a class="link" href="functions-window.html" title="9.22. Window Functions">window
+ functions</a> that use <code class="function">row_number()</code>,
+ <code class="function">rank()</code>, <code class="function">dense_rank()</code> and
+ <code class="function">count()</code>
+ (David Rowley)
+ </p></li><li class="listitem"><p>
+ Improve the performance of spinlocks on high-core-count ARM64
+ systems (Geoffrey Blake)
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.7"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.5. Monitoring</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Enable default logging of checkpoints and slow autovacuum
+ operations (Bharath Rupireddy)
+ </p><p>
+ This changes the default of <a class="link" href="runtime-config-logging.html#GUC-LOG-CHECKPOINTS"><code class="varname">log_checkpoints</code></a>
+ to <code class="literal">on</code> and that of <a class="link" href="runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION"><code class="varname">log_autovacuum_min_duration</code></a>
+ to 10 minutes. This will cause even an idle server to generate
+ some log output, which might cause problems on
+ resource-constrained servers without log file rotation. These
+ defaults should be changed in such cases.
+ </p></li><li class="listitem"><p>
+ Generate progress messages in the server log during slow server
+ starts (Nitin Jadhav, Robert Haas)
+ </p><p>
+ The messages report the cause of the delay. The time interval for
+ notification is controlled by the new server variable <a class="link" href="runtime-config-logging.html#GUC-LOG-STARTUP-PROGRESS-INTERVAL"><code class="varname">log_startup_progress_interval</code></a>.
+ </p></li><li class="listitem"><p>
+ Store <a class="link" href="monitoring-stats.html" title="28.2. The Cumulative Statistics System">cumulative statistics
+ system</a> data in shared memory (Kyotaro Horiguchi, Andres
+ Freund, Melanie Plageman)
+ </p><p>
+ Previously this data was sent to a statistics collector process
+ via <acronym class="acronym">UDP</acronym> packets, and could only be read by
+ sessions after transferring it via the file system. There is no
+ longer a separate statistics collector process.
+ </p></li><li class="listitem"><p>
+ Add additional information to <code class="command">VACUUM VERBOSE</code>
+ and autovacuum logging messages (Peter Geoghegan)
+ </p></li><li class="listitem"><p>
+ Add <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN
+ (BUFFERS)</code></a> output for temporary file block I/O
+ (Masahiko Sawada)
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="runtime-config-logging.html#GUC-LOG-DESTINATION">log output</a> in
+ <acronym class="acronym">JSON</acronym> format (Sehrope Sarkuni, Michael Paquier)
+ </p><p>
+ The new setting is <code class="literal">log_destination = jsonlog</code>.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="monitoring-stats.html#MONITORING-STATS-FUNCS-TABLE" title="Table 28.34. Additional Statistics Functions"><code class="function">pg_stat_reset_single_table_counters()</code></a>
+ to reset the counters of relations shared across all databases
+ (Sadhuprasad Patro)
+ </p></li><li class="listitem"><p>
+ Add <a class="link" href="monitoring-stats.html#WAIT-EVENT-TABLE" title="Table 28.4. Wait Event Types">wait events</a> for local
+ shell commands (Fujii Masao)
+ </p><p>
+ The new wait events are used when calling
+ <code class="varname">archive_command</code>,
+ <code class="varname">archive_cleanup_command</code>,
+ <code class="varname">restore_command</code> and
+ <code class="varname">recovery_end_command</code>.
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.8"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.6. Privileges</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow table accesses done by
+ a <a class="link" href="sql-createview.html" title="CREATE VIEW">view</a> to optionally be
+ controlled by privileges of the view's caller (Christoph Heiss)
+ </p><p>
+ Previously, view accesses were always treated as being done by the
+ view's owner. That's still the default.
+ </p></li><li class="listitem"><p>
+ Allow members of the <a class="link" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles"><code class="literal">pg_write_server_files</code></a>
+ predefined role to perform server-side base backups (Dagfinn
+ Ilmari Mannsåker)
+ </p><p>
+ Previously only superusers could perform such backups.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a>
+ to grant permissions to change individual server variables via
+ <code class="command">SET</code> and <code class="command">ALTER SYSTEM</code>
+ (Mark Dilger)
+ </p><p>
+ The new function <code class="function">has_parameter_privilege()</code>
+ reports on this privilege.
+ </p></li><li class="listitem"><p>
+ Add predefined role <a class="link" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles"><code class="literal">pg_checkpoint</code></a>
+ that allows members to run <code class="command">CHECKPOINT</code>
+ (Jeff Davis)
+ </p><p>
+ Previously checkpoints could only be run by superusers.
+ </p></li><li class="listitem"><p>
+ Allow members of the <a class="link" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles"><code class="literal">pg_read_all_stats</code></a>
+ predefined role to access the views <a class="link" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts"><code class="structname">pg_backend_memory_contexts</code></a>
+ and <a class="link" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations"><code class="structname">pg_shmem_allocations</code></a>
+ (Bharath Rupireddy)
+ </p><p>
+ Previously these views could only be accessed by superusers.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a>
+ to grant permissions on <a class="link" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL" title="9.27.2. Server Signaling Functions"><code class="function">pg_log_backend_memory_contexts()</code></a>
+ (Jeff Davis)
+ </p><p>
+ Previously this function could only be run by superusers.
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.3.9"><div class="titlepage"><div><div><h5 class="title">E.6.3.1.7. Server Configuration</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add server variable <a class="link" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE"><code class="varname">shared_memory_size</code></a>
+ to report the size of allocated shared memory (Nathan Bossart)
+ </p></li><li class="listitem"><p>
+ Add server variable <a class="link" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE-IN-HUGE-PAGES"><code class="varname">shared_memory_size_in_huge_pages</code></a>
+ to report the number of huge memory pages required (Nathan Bossart)
+ </p><p>
+ This is only supported on Linux.
+ </p></li><li class="listitem"><p>
+ Honor server variable <a class="link" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES"><code class="varname">shared_preload_libraries</code></a>
+ in single-user mode (Jeff Davis)
+ </p><p>
+ This change supports use
+ of <code class="varname">shared_preload_libraries</code> to load custom
+ access methods and WAL resource managers, which would be essential
+ for database access even in single-user mode.
+ </p></li><li class="listitem"><p>
+ On Solaris, make the default setting of <a class="link" href="runtime-config-resource.html#GUC-DYNAMIC-SHARED-MEMORY-TYPE"><code class="varname">dynamic_shared_memory_type</code></a>
+ be <code class="literal">sysv</code> (Thomas Munro)
+ </p><p>
+ The previous default choice, <code class="literal">posix</code>, can result
+ in spurious failures on this platform.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="app-postgres.html" title="postgres"><code class="command">postgres
+ -C</code></a> to properly report runtime-computed values
+ (Nathan Bossart)
+ </p><p>
+ Previously runtime-computed values <a class="link" href="runtime-config-preset.html#GUC-DATA-CHECKSUMS"><code class="varname">data_checksums</code></a>,
+ <a class="link" href="runtime-config-preset.html#GUC-WAL-SEGMENT-SIZE"><code class="varname">wal_segment_size</code></a>,
+ and <a class="link" href="runtime-config-preset.html#GUC-DATA-DIRECTORY-MODE"><code class="varname">data_directory_mode</code></a>
+ would report values that would not be accurate on the running
+ server. However, this does not work on a running server.
+ </p></li></ul></div></div></div><div class="sect3" id="id-1.11.6.10.5.4"><div class="titlepage"><div><div><h4 class="title">E.6.3.2. Streaming Replication and Recovery</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add support for LZ4 and Zstandard compression of server-side <a class="link" href="continuous-archiving.html#BACKUP-BASE-BACKUP" title="26.3.2. Making a Base Backup">base backups</a> (Jeevan Ladhe,
+ Robert Haas)
+ </p></li><li class="listitem"><p>
+ Run the checkpointer and bgwriter processes during crash recovery
+ (Thomas Munro)
+ </p><p>
+ This helps to speed up long crash recoveries.
+ </p></li><li class="listitem"><p>
+ Allow <acronym class="acronym">WAL</acronym> processing to pre-fetch needed file
+ contents (Thomas Munro)
+ </p><p>
+ This is controlled by the server variable <a class="link" href="runtime-config-wal.html#GUC-RECOVERY-PREFETCH"><code class="varname">recovery_prefetch</code></a>.
+ </p></li><li class="listitem"><p>
+ Allow archiving via loadable modules (Nathan Bossart)
+ </p><p>
+ Previously, archiving was only done by calling shell commands.
+ The new server variable <a class="link" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY"><code class="varname">archive_library</code></a>
+ can be set to specify a library to be called for archiving.
+ </p></li><li class="listitem"><p>
+ No longer require <a class="link" href="protocol-replication.html" title="55.4. Streaming Replication Protocol"><code class="literal">IDENTIFY_SYSTEM</code></a>
+ to be run before <code class="literal">START_REPLICATION</code> (Jeff Davis)
+ </p></li></ul></div><div class="sect4" id="id-1.11.6.10.5.4.3"><div class="titlepage"><div><div><h5 class="title">E.6.3.2.1. <a class="link" href="logical-replication.html" title="Chapter 31. Logical Replication">Logical Replication</a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <a class="link" href="sql-createpublication.html" title="CREATE PUBLICATION">publication</a> of
+ all tables in a schema (Vignesh C, Hou Zhijie, Amit Kapila)
+ </p><p>
+ For example, this syntax is now supported: <code class="literal">CREATE
+ PUBLICATION pub1 FOR TABLES IN SCHEMA s1,s2</code>.
+ <code class="command">ALTER PUBLICATION</code> supports a similar syntax.
+ Tables added later to the listed schemas will also be replicated.
+ </p></li><li class="listitem"><p>
+ Allow publication content to be filtered using a
+ <code class="literal">WHERE</code> clause (Hou Zhijie, Euler Taveira,
+ Peter Smith, Ajin Cherian, Tomas Vondra, Amit Kapila)
+ </p><p>
+ Rows not satisfying the <code class="literal">WHERE</code> clause are not
+ published.
+ </p></li><li class="listitem"><p>
+ Allow publication content to
+ be restricted to specific columns (Tomas Vondra, Álvaro Herrera,
+ Rahila Syed)
+ </p></li><li class="listitem"><p>
+ Allow skipping of transactions on a subscriber using <a class="link" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><code class="command">ALTER SUBSCRIPTION
+ ... SKIP</code></a> (Masahiko Sawada)
+ </p></li><li class="listitem"><p>
+ Add support for prepared (two-phase) transactions to logical
+ replication (Peter Smith, Ajin Cherian, Amit Kapila, Nikhil
+ Sontakke, Stas Kelvich)
+ </p><p>
+ The new <a class="link" href="protocol-replication.html" title="55.4. Streaming Replication Protocol"><code class="literal">CREATE_REPLICATION_SLOT</code></a>
+ option is called <code class="literal">TWO_PHASE</code>.
+ <span class="application">pg_recvlogical</span> now supports a new
+ <code class="option">--two-phase</code> option during slot creation.
+ </p></li><li class="listitem"><p>
+ Prevent logical replication of empty transactions (Ajin Cherian,
+ Hou Zhijie, Euler Taveira)
+ </p><p>
+ Previously, publishers would send empty transactions to
+ subscribers if subscribed tables were not modified.
+ </p></li><li class="listitem"><p>
+ Add <acronym class="acronym">SQL</acronym> functions to monitor the directory
+ contents of logical replication slots (Bharath Rupireddy)
+ </p><p>
+ The new functions are <a class="link" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE-TABLE" title="Table 9.99. Generic File Access Functions"><code class="function">pg_ls_logicalsnapdir()</code></a>,
+ <code class="function">pg_ls_logicalmapdir()</code>, and
+ <code class="function">pg_ls_replslotdir()</code>. They can be run by
+ members of the predefined <code class="literal">pg_monitor</code> role.
+ </p></li><li class="listitem"><p>
+ Allow subscribers to stop the application of logical replication changes on error
+ (Osumi Takamichi, Mark Dilger)
+ </p><p>
+ This is enabled with the subscriber option <a class="link" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><code class="literal">disable_on_error</code></a>
+ and avoids possible infinite error loops during stream application.
+ </p></li><li class="listitem"><p>
+ Adjust subscriber server variables to match the publisher so
+ datetime and float8 values are interpreted consistently (Japin Li)
+ </p><p>
+ Some publishers might be relying on inconsistent behavior.
+ </p></li><li class="listitem"><p>
+ Add system view <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SUBSCRIPTION-STATS" title="28.2.9. pg_stat_subscription_stats"><code class="structname">pg_stat_subscription_stats</code></a>
+ to report on subscriber activity (Masahiko Sawada)
+ </p><p>
+ The new function <a class="link" href="monitoring-stats.html#MONITORING-STATS-FUNCTIONS" title="28.2.24. Statistics Functions"><code class="function">pg_stat_reset_subscription_stats()</code></a>
+ allows resetting these statistics counters.
+ </p></li><li class="listitem"><p>
+ Suppress duplicate entries in the <a class="link" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables"><code class="structname">pg_publication_tables</code></a>
+ system view (Hou Zhijie)
+ </p><p>
+ In some cases a partition could appear more than once.
+ </p></li></ul></div></div></div><div class="sect3" id="id-1.11.6.10.5.5"><div class="titlepage"><div><div><h4 class="title">E.6.3.3. Utility Commands</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add <acronym class="acronym">SQL</acronym> <a class="link" href="sql-merge.html" title="MERGE"><code class="command">MERGE</code></a>
+ command to adjust one table to match another (Simon Riggs, Pavan
+ Deolasee, Álvaro Herrera, Amit Langote)
+ </p><p>
+ This is similar to <code class="command">INSERT ... ON CONFLICT</code>
+ but more batch-oriented.
+ </p></li><li class="listitem"><p>
+ Add support for <code class="literal">HEADER</code> option in <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a> text format
+ (Rémi Lapeyre)
+ </p><p>
+ The new option causes the column names to be output, and optionally
+ verified on input.
+ </p></li><li class="listitem"><p>
+ Add new <acronym class="acronym">WAL</acronym>-logged method for <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE">database creation</a> (Dilip Kumar)
+ </p><p>
+ This is the new default method for copying the template database,
+ as it avoids the need for checkpoints during database creation.
+ However, it might be slow if the template database is large, so
+ the old method is still available.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE
+ DATABASE</code></a> to set the database <acronym class="acronym">OID</acronym>
+ (Shruthi Gowda, Antonin Houska)
+ </p></li><li class="listitem"><p>
+ Prevent <a class="link" href="sql-dropdatabase.html" title="DROP DATABASE"><code class="command">DROP
+ DATABASE</code></a>, <a class="link" href="sql-droptablespace.html" title="DROP TABLESPACE"><code class="command">DROP
+ TABLESPACE</code></a>, and <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE SET
+ TABLESPACE</code></a> from occasionally failing during
+ concurrent use on Windows (Thomas Munro)
+ </p></li><li class="listitem"><p>
+ Allow foreign key <a class="link" href="ddl-constraints.html#DDL-CONSTRAINTS-FK" title="5.4.5. Foreign Keys"><code class="literal">ON
+ DELETE SET</code></a> actions to affect only specified columns
+ (Paul Martinez)
+ </p><p>
+ Previously, all of the columns in the foreign key were always
+ affected.
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER
+ TABLE</code></a> to modify a table's <code class="literal">ACCESS
+ METHOD</code> (Justin Pryzby, Jeff Davis)
+ </p></li><li class="listitem"><p>
+ Properly call object access hooks when <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ causes table rewrites (Michael Paquier)
+ </p></li><li class="listitem"><p>
+ Allow creation of unlogged <a class="link" href="sql-createsequence.html" title="CREATE SEQUENCE">sequences</a> (Peter Eisentraut)
+ </p></li><li class="listitem"><p>
+ Track dependencies on individual columns in the results of
+ functions returning composite types (Tom Lane)
+ </p><p>
+ Previously, if a view or rule contained a reference to a specific
+ column within the result of a composite-returning function, that
+ was not noted as a dependency; the view or rule was only considered
+ to depend on the composite type as a whole. This meant that
+ dropping the individual column would be allowed, causing problems
+ in later use of the view or rule. The column-level dependency is
+ now also noted, so that dropping such a column will be rejected
+ unless the view is changed or dropped.
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.6"><div class="titlepage"><div><div><h4 class="title">E.6.3.4. Data Types</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow the scale of
+ a <a class="link" href="datatype-numeric.html" title="8.1. Numeric Types"><code class="type">numeric</code></a>
+ value to be negative, or greater than its precision (Dean Rasheed,
+ Tom Lane)
+ </p><p>
+ This allows rounding of values to the left of the decimal point,
+ e.g., <code class="literal">'1234'::numeric(4, -2)</code> returns 1200.
+ </p></li><li class="listitem"><p>
+ Improve overflow detection when casting values to <a class="link" href="datatype-datetime.html" title="8.5. Date/Time Types">interval</a> (Joe Koshakow)
+ </p></li><li class="listitem"><p>
+ Change the I/O format of type <code class="type">"char"</code> for non-ASCII
+ characters (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Update the display width information of modern Unicode characters,
+ like emojis (Jacob Champion)
+ </p><p>
+ Also update from Unicode 5.0 to 14.0.0. There is now an automated
+ way to keep Postgres updated with Unicode releases.
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.7"><div class="titlepage"><div><div><h4 class="title">E.6.3.5. Functions</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add multirange input to <a class="link" href="functions-aggregate.html#FUNCTIONS-AGGREGATE-TABLE" title="Table 9.58. General-Purpose Aggregate Functions"><code class="function">range_agg()</code></a>
+ (Paul Jungwirth)
+ </p></li><li class="listitem"><p>
+ Add <a class="link" href="tutorial-agg.html" title="2.7. Aggregate Functions"><code class="function">MIN()</code></a>
+ and <code class="function">MAX()</code> aggregates for the <a class="link" href="datatype-numeric.html#DATATYPE-INT" title="8.1.1. Integer Types"><code class="type">xid8</code></a> data type (Ken Kato)
+ </p></li><li class="listitem"><p>
+ Add regular expression functions for compatibility with other
+ relational systems (Gilles Darold, Tom Lane)
+ </p><p>
+ The new functions are <a class="link" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators"><code class="function">regexp_count()</code></a>,
+ <code class="function">regexp_instr()</code>,
+ <code class="function">regexp_like()</code>, and
+ <code class="function">regexp_substr()</code>. Some new optional arguments
+ were also added to <code class="function">regexp_replace()</code>.
+ </p></li><li class="listitem"><p>
+ Add the ability to compute the distance between <a class="link" href="datatype-geometric.html#DATATYPE-POLYGON" title="8.8.6. Polygons"><code class="type">polygons</code></a> (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Add <a class="link" href="functions-formatting.html#FUNCTIONS-FORMATTING-TABLE" title="Table 9.26. Formatting Functions"><code class="function">to_char()</code></a>
+ format codes <code class="literal">of</code>, <code class="literal">tzh</code>, and
+ <code class="literal">tzm</code> (Nitin Jadhav)
+ </p><p>
+ The upper-case equivalents of these were already supported.
+ </p></li><li class="listitem"><p>
+ When applying <a class="link" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT" title="9.9.4. AT TIME ZONE"><code class="literal">AT
+ TIME ZONE</code></a> to a <code class="type">time with time zone</code>
+ value, use the transaction start time rather than wall clock time
+ to determine whether DST applies (Aleksander Alekseev, Tom Lane)
+ </p><p>
+ This allows the conversion to be considered stable rather than
+ volatile, and it saves a kernel call per invocation.
+ </p></li><li class="listitem"><p>
+ Ignore NULL array elements in <a class="link" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-TABLE" title="Table 9.43. Text Search Functions"><code class="function">ts_delete()</code></a> and
+ <code class="function">setweight()</code> functions with array arguments
+ (Jean-Christophe Arnu)
+ </p><p>
+ These functions effectively ignore empty-string array elements
+ (since those could never match a valid lexeme). It seems
+ consistent to let them ignore NULL elements too, instead of
+ failing.
+ </p></li><li class="listitem"><p>
+ Add support for petabyte units to <a class="link" href="functions-admin.html#FUNCTIONS-ADMIN-DBSIZE" title="Table 9.94. Database Object Size Functions"><code class="function">pg_size_pretty()</code></a>
+ and <code class="function">pg_size_bytes()</code> (David Christensen)
+ </p></li><li class="listitem"><p>
+ Change <a class="link" href="functions-event-triggers.html#PG-EVENT-TRIGGER-DDL-COMMAND-END-FUNCTIONS" title="9.29.1. Capturing Changes at Command End"><code class="function">pg_event_trigger_ddl_commands()</code></a>
+ to output references to other sessions' temporary schemas using the
+ actual schema name (Tom Lane)
+ </p><p>
+ Previously this function reported all temporary schemas as
+ <code class="literal">pg_temp</code>, but it's misleading to use that for any
+ but the current session's temporary schema.
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.8"><div class="titlepage"><div><div><h4 class="title">E.6.3.6. <a class="link" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">PL/pgSQL</a></h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Fix enforcement of PL/pgSQL variable <code class="literal">CONSTANT</code>
+ markings (Tom Lane)
+ </p><p>
+ Previously, a variable could be used as a <a class="link" href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE" title="43.6.3. Calling a Procedure"><code class="command">CALL</code></a>
+ output parameter or refcursor <code class="command">OPEN</code> variable
+ despite being marked <code class="literal">CONSTANT</code>.
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.9"><div class="titlepage"><div><div><h4 class="title">E.6.3.7. <a class="link" href="libpq.html" title="Chapter 34. libpq — C Library">libpq</a></h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <acronym class="acronym">IP</acronym> address matching against a server
+ certificate's Subject Alternative Name (Jacob Champion)
+ </p></li><li class="listitem"><p>
+ Allow <code class="function">PQsslAttribute()</code> to report the
+ <acronym class="acronym">SSL</acronym> library type without requiring a libpq
+ connection (Jacob Champion)
+ </p></li><li class="listitem"><p>
+ Change query cancellations sent by the client to use the same
+ <acronym class="acronym">TCP</acronym> settings as normal client connections
+ (Jelte Fennema)
+ </p><p>
+ This allows configured <acronym class="acronym">TCP</acronym> timeouts to apply
+ to query cancel connections.
+ </p></li><li class="listitem"><p>
+ Prevent libpq event callback failures from forcing an error result
+ (Tom Lane)
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.10"><div class="titlepage"><div><div><h4 class="title">E.6.3.8. Client Applications</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <a class="link" href="pgbench.html" title="pgbench"><span class="application">pgbench</span></a> to
+ retry after serialization and deadlock failures (Yugo Nagata,
+ Marina Polyakova)
+ </p></li></ul></div><div class="sect4" id="id-1.11.6.10.5.10.3"><div class="titlepage"><div><div><h5 class="title">E.6.3.8.1. <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Improve performance
+ of <span class="application">psql</span>'s <code class="command">\copy</code>
+ command, by sending data in larger chunks (Heikki Linnakangas)
+ </p></li><li class="listitem"><p>
+ Add <code class="command">\dconfig</code> command to report server variables
+ (Mark Dilger, Tom Lane)
+ </p><p>
+ This is similar to the server-side <code class="command">SHOW</code>
+ command, but it can process patterns to show multiple variables
+ conveniently.
+ </p></li><li class="listitem"><p>
+ Add <code class="command">\getenv</code> command
+ to assign the value of an environment variable to a
+ <span class="application">psql</span> variable (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Add <code class="literal">+</code> option to the
+ <code class="literal">\lo_list</code> and <code class="literal">\dl</code> commands to
+ show large-object privileges (Pavel Luzanov)
+ </p></li><li class="listitem"><p>
+ Add a pager option for the <code class="command">\watch</code>
+ command (Pavel Stehule, Thomas Munro)
+ </p><p>
+ This is only supported on Unix and is controlled by the
+ <code class="envar">PSQL_WATCH_PAGER</code> environment variable.
+ </p></li><li class="listitem"><p>
+ Make <span class="application">psql</span> include intra-query double-hyphen
+ comments in queries sent to the server (Tom Lane, Greg Nancarrow)
+ </p><p>
+ Previously such comments were removed from the query
+ before being sent. Double-hyphen comments that are before any
+ query text are not sent, and are not recorded as separate
+ <span class="application">psql</span> history entries.
+ </p></li><li class="listitem"><p>
+ Adjust <span class="application">psql</span> so
+ that <span class="application">Readline</span>'s
+ meta-<code class="literal">#</code> command will insert a double-hyphen
+ comment marker (Tom Lane)
+ </p><p>
+ Previously a pound marker was inserted, unless the user had taken
+ the trouble to configure a non-default comment marker.
+ </p></li><li class="listitem"><p>
+ Make <span class="application">psql</span> output all results when multiple
+ queries are passed to the server at once (Fabien Coelho)
+ </p><p>
+ Previously, only the last query result was displayed. The old
+ behavior can be restored by setting
+ the <code class="literal">SHOW_ALL_RESULTS</code> <span class="application">psql</span>
+ variable to <code class="literal">off</code>.
+ </p></li><li class="listitem"><p>
+ After an error is detected
+ in <code class="option">--single-transaction</code> mode, change the
+ final <code class="command">COMMIT</code> command
+ to <code class="command">ROLLBACK</code> only
+ if <code class="varname">ON_ERROR_STOP</code> is set (Michael Paquier)
+ </p><p>
+ Previously, detection of an error in a <code class="option">-c</code> command
+ or <code class="option">-f</code> script file would lead to
+ issuing <code class="command">ROLLBACK</code> at the end, regardless of the
+ value of <code class="varname">ON_ERROR_STOP</code>.
+ </p></li><li class="listitem"><p>
+ Improve <span class="application">psql</span>'s tab completion (Shinya
+ Kato, Dagfinn Ilmari Mannsåker, Peter Smith, Koyu Tanigawa,
+ Ken Kato, David Fetter, Haiying Tang, Peter Eisentraut, Álvaro
+ Herrera, Tom Lane, Masahiko Sawada)
+ </p></li><li class="listitem"><p>
+ Limit support of <span class="application">psql</span>'s backslash
+ commands to servers running <span class="productname">PostgreSQL</span>
+ 9.2 or later (Tom Lane)
+ </p><p>
+ Remove code that was only used when running with an older server.
+ Commands that do not require any version-specific adjustments
+ compared to 9.2 will still work.
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.10.4"><div class="titlepage"><div><div><h5 class="title">E.6.3.8.2. <a class="link" href="app-pgdump.html" title="pg_dump"><span class="application">pg_dump</span></a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Make <span class="application">pg_dump</span> dump
+ <code class="literal">public</code> schema ownership changes and security
+ labels (Noah Misch)
+ </p></li><li class="listitem"><p>
+ Improve performance of dumping databases with many objects
+ (Tom Lane)
+ </p><p>
+ This will also improve the performance of <a class="link" href="pgupgrade.html" title="pg_upgrade"><span class="application">pg_upgrade</span></a>.
+ </p></li><li class="listitem"><p>
+ Improve parallel <span class="application">pg_dump</span>'s performance
+ for tables with large <acronym class="acronym">TOAST</acronym> tables (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Add dump/restore option <code class="option">--no-table-access-method</code>
+ to force restore to only use the default table access method
+ (Justin Pryzby)
+ </p></li><li class="listitem"><p>
+ Limit support of <span class="application">pg_dump</span> and <a class="link" href="app-pg-dumpall.html" title="pg_dumpall"><span class="application">pg_dumpall</span></a>
+ to servers running <span class="productname">PostgreSQL</span> 9.2 or
+ later (Tom Lane)
+ </p></li></ul></div></div></div><div class="sect3" id="id-1.11.6.10.5.11"><div class="titlepage"><div><div><h4 class="title">E.6.3.9. Server Applications</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add new <a class="link" href="app-pgbasebackup.html" title="pg_basebackup"><span class="application">pg_basebackup</span></a>
+ option <code class="option">--target</code> to control the base backup location
+ (Robert Haas)
+ </p><p>
+ The new options are <code class="literal">server</code> to write the
+ backup locally and <code class="literal">blackhole</code> to discard the
+ backup (for testing).
+ </p></li><li class="listitem"><p>
+ Allow <span class="application">pg_basebackup</span> to do server-side
+ gzip, LZ4, and Zstandard compression and client-side LZ4 and
+ Zstandard compression of base backup files (Dipesh Pandit,
+ Jeevan Ladhe)
+ </p><p>
+ Client-side <code class="literal">gzip</code> compression was already
+ supported.
+ </p></li><li class="listitem"><p>
+ Allow <span class="application">pg_basebackup</span> to compress on
+ the server side and decompress on the client side before storage
+ (Dipesh Pandit)
+ </p><p>
+ This is accomplished by specifying compression on the server side
+ and plain output format.
+ </p></li><li class="listitem"><p>
+ Allow <span class="application">pg_basebackup</span>'s
+ <code class="option">--compress</code> option to control the compression
+ location (server or client), compression method, and compression
+ options (Michael Paquier, Robert Haas)
+ </p></li><li class="listitem"><p>
+ Add the LZ4 compression method to <a class="link" href="app-pgreceivewal.html" title="pg_receivewal"><span class="application">pg_receivewal</span></a>
+ (Georgios Kokolatos)
+ </p><p>
+ This is enabled via <code class="literal">--compress=lz4</code> and requires
+ binaries to be built using <code class="option">--with-lz4</code>.
+ </p></li><li class="listitem"><p>
+ Add additional capabilities to
+ <span class="application">pg_receivewal</span>'s
+ <code class="option">--compress</code> option (Georgios Kokolatos)
+ </p></li><li class="listitem"><p>
+ Improve <span class="application">pg_receivewal</span>'s ability to
+ restart at the proper <acronym class="acronym">WAL</acronym> location (Ronan
+ Dunklau)
+ </p><p>
+ Previously, <span class="application">pg_receivewal</span> would start
+ based on the <acronym class="acronym">WAL</acronym> file stored in the local archive
+ directory, or at the sending server's current <acronym class="acronym">WAL</acronym>
+ flush location. With this change, if the sending server is running
+ Postgres 15 or later, the local archive directory is empty, and
+ a replication slot is specified, the replication slot's restart
+ point will be used.
+ </p></li><li class="listitem"><p>
+ Add <a class="link" href="app-pgrewind.html" title="pg_rewind"><span class="application">pg_rewind</span></a>
+ option <code class="option">--config-file</code> to simplify use when server
+ configuration files are stored outside the data directory (Gunnar
+ Bluth)
+ </p></li></ul></div><div class="sect4" id="id-1.11.6.10.5.11.3"><div class="titlepage"><div><div><h5 class="title">E.6.3.9.1. <a class="link" href="pgupgrade.html" title="pg_upgrade"><span class="application">pg_upgrade</span></a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Store <span class="application">pg_upgrade</span>'s log and
+ temporary files in a subdirectory of the new cluster called
+ <code class="filename">pg_upgrade_output.d</code> (Justin Pryzby)
+ </p><p>
+ Previously such files were left in the current directory,
+ requiring manual cleanup. Now they are automatically removed on
+ successful completion of <span class="application">pg_upgrade</span>.
+ </p></li><li class="listitem"><p>
+ Disable default status reporting during
+ <span class="application">pg_upgrade</span> operation if the output is
+ not a terminal (Andres Freund)
+ </p><p>
+ The status reporting output can be enabled for non-tty usage by
+ using <code class="option">--verbose</code>.
+ </p></li><li class="listitem"><p>
+ Make <span class="application">pg_upgrade</span> report all databases
+ with invalid connection settings (Jeevan Ladhe)
+ </p><p>
+ Previously only the first database with an invalid connection
+ setting was reported.
+ </p></li><li class="listitem"><p>
+ Make <span class="application">pg_upgrade</span> preserve tablespace
+ and database OIDs, as well as relation relfilenode numbers
+ (Shruthi Gowda, Antonin Houska)
+ </p></li><li class="listitem"><p>
+ Add a <code class="option">--no-sync</code> option to
+ <span class="application">pg_upgrade</span> (Michael Paquier)
+ </p><p>
+ This is recommended only for testing.
+ </p></li><li class="listitem"><p>
+ Limit support of <span class="application">pg_upgrade</span> to old
+ servers running <span class="productname">PostgreSQL</span> 9.2 or later
+ (Tom Lane)
+ </p></li></ul></div></div><div class="sect4" id="id-1.11.6.10.5.11.4"><div class="titlepage"><div><div><h5 class="title">E.6.3.9.2. <a class="link" href="pgwaldump.html" title="pg_waldump"><span class="application">pg_waldump</span></a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <span class="application">pg_waldump</span> output to be filtered by
+ relation file node, block number, fork number, and full page images
+ (David Christensen, Thomas Munro)
+ </p></li><li class="listitem"><p>
+ Make <span class="application">pg_waldump</span> report statistics
+ before an interrupted exit (Bharath Rupireddy)
+ </p><p>
+ For example, issuing a control-C in a terminal running
+ <code class="command">pg_waldump --stats --follow</code> will report the
+ current statistics before exiting. This does not work on Windows.
+ </p></li><li class="listitem"><p>
+ Improve descriptions of some transaction <acronym class="acronym">WAL</acronym>
+ records reported by <span class="application">pg_waldump</span>
+ (Masahiko Sawada, Michael Paquier)
+ </p></li><li class="listitem"><p>
+ Allow <span class="application">pg_waldump</span> to dump information
+ about multiple resource managers (Heikki Linnakangas)
+ </p><p>
+ This is enabled by specifying the <code class="option">--rmgr</code> option
+ multiple times.
+ </p></li></ul></div></div></div><div class="sect3" id="id-1.11.6.10.5.12"><div class="titlepage"><div><div><h4 class="title">E.6.3.10. Documentation</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add documentation for <a class="link" href="functions-info.html#FUNCTIONS-INFO-CATALOG-TABLE" title="Table 9.71. System Catalog Information Functions"><code class="function">pg_encoding_to_char()</code></a>
+ and <code class="function">pg_char_to_encoding()</code> (Ian Lawrence
+ Barwick)
+ </p></li><li class="listitem"><p>
+ Document the <a class="link" href="functions-string.html#FUNCTIONS-STRING-OTHER" title="Table 9.10. Other String Functions and Operators"><code class="literal">^@</code></a>
+ starts-with operator (Tom Lane)
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.13"><div class="titlepage"><div><div><h4 class="title">E.6.3.11. Source Code</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Add support for continuous integration testing using cirrus-ci
+ (Andres Freund, Thomas Munro, Melanie Plageman)
+ </p></li><li class="listitem"><p>
+ Add configure option <a class="link" href="install-procedure.html#CONFIGURE-OPTIONS-FEATURES" title="17.4.1.2. PostgreSQL Features"><code class="option">--with-zstd</code></a>
+ to enable Zstandard builds (Jeevan Ladhe, Robert Haas, Michael
+ Paquier)
+ </p></li><li class="listitem"><p>
+ Add an ABI identifier field to the magic block in loadable
+ libraries, allowing
+ non-community <span class="productname">PostgreSQL</span> distributions
+ to identify libraries that are not compatible with other builds
+ (Peter Eisentraut)
+ </p><p>
+ An ABI field mismatch will generate an error at load time.
+ </p></li><li class="listitem"><p>
+ Create a new <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structfield">pg_type.typcategory</code></a>
+ value for <code class="type">"char"</code> (Tom Lane)
+ </p><p>
+ Some other internal-use-only types have also been assigned to this
+ category.
+ </p></li><li class="listitem"><p>
+ Add new protocol message <a class="link" href="protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP"><code class="literal">TARGET</code></a>
+ to specify a new <code class="command">COPY</code> method to be used for base
+ backups (Robert Haas)
+ </p><p>
+ <a class="link" href="app-pgbasebackup.html" title="pg_basebackup"><span class="application">pg_basebackup</span></a>
+ now uses this method.
+ </p></li><li class="listitem"><p>
+ Add new protocol message <a class="link" href="protocol-replication.html#PROTOCOL-REPLICATION-BASE-BACKUP"><code class="literal">COMPRESSION</code></a>
+ and <code class="literal">COMPRESSION_DETAIL</code> to specify the compression
+ method and options (Robert Haas)
+ </p></li><li class="listitem"><p>
+ Remove server support for old <code class="literal">BASE_BACKUP</code>
+ command syntax and base backup protocol (Robert Haas)
+ </p></li><li class="listitem"><p>
+ Add support for extensions to set custom backup targets (Robert
+ Haas)
+ </p></li><li class="listitem"><p>
+ Allow extensions to define custom <acronym class="acronym">WAL</acronym>
+ resource managers (Jeff Davis)
+ </p></li><li class="listitem"><p>
+ Add function <a class="link" href="functions-info.html#FUNCTIONS-INFO-CATALOG-TABLE" title="Table 9.71. System Catalog Information Functions"><code class="function">pg_settings_get_flags()</code></a>
+ to get the flags of server variables (Justin Pryzby)
+ </p></li><li class="listitem"><p>
+ On Windows, export all the server's global variables using
+ <code class="literal">PGDLLIMPORT</code> markers (Robert Haas)
+ </p><p>
+ Previously, only specific variables were accessible to extensions
+ on Windows.
+ </p></li><li class="listitem"><p>
+ Require GNU <span class="application">make</span> version 3.81 or later
+ to build <span class="productname">PostgreSQL</span> (Tom Lane)
+ </p></li><li class="listitem"><p>
+ Require OpenSSL to build the <a class="link" href="pgcrypto.html" title="F.28. pgcrypto"><span class="application">pgcrypto</span></a>
+ extension (Peter Eisentraut)
+ </p></li><li class="listitem"><p>
+ Require <span class="application">Perl</span>
+ version 5.8.3 or later (Dagfinn Ilmari Mannsåker)
+ </p></li><li class="listitem"><p>
+ Require <span class="application">Python</span>
+ version 3.2 or later (Andres Freund)
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.6.10.5.14"><div class="titlepage"><div><div><h4 class="title">E.6.3.12. Additional Modules</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow <a class="link" href="amcheck.html" title="F.2. amcheck"><span class="application">amcheck</span></a> to
+ check sequences (Mark Dilger)
+ </p></li><li class="listitem"><p>
+ Improve <span class="application">amcheck</span> sanity checks for
+ <acronym class="acronym">TOAST</acronym> tables (Mark Dilger)
+ </p></li><li class="listitem"><p>
+ Add new module <span class="application"><a class="link" href="basebackup-to-shell.html" title="F.5. basebackup_to_shell">basebackup_to_shell</a></span>
+ as an example of a custom backup target (Robert Haas)
+ </p></li><li class="listitem"><p>
+ Add new module <a class="link" href="basic-archive.html" title="F.6. basic_archive"><span class="application">basic_archive</span></a>
+ as an example of performing archiving via a library (Nathan Bossart)
+ </p></li><li class="listitem"><p>
+ Allow <a class="link" href="btree-gist.html" title="F.9. btree_gist"><span class="application">btree_gist</span></a>
+ indexes on boolean columns (Emre Hasegeli)
+ </p><p>
+ These can be used for exclusion constraints.
+ </p></li><li class="listitem"><p>
+ Fix <a class="link" href="pageinspect.html" title="F.25. pageinspect"><span class="application">pageinspect</span></a>'s
+ <code class="function">page_header()</code> to handle 32-kilobyte page sizes
+ (Quan Zongliang)
+ </p><p>
+ Previously, improper negative values could be returned in certain
+ cases.
+ </p></li><li class="listitem"><p>
+ Add counters for temporary file block I/O to <a class="link" href="pgstatstatements.html" title="F.32. pg_stat_statements"><span class="application">pg_stat_statements</span></a>
+ (Masahiko Sawada)
+ </p></li><li class="listitem"><p>
+ Add <acronym class="acronym">JIT</acronym> counters to pg_stat_statements (Magnus
+ Hagander)
+ </p></li><li class="listitem"><p>
+ Add new module <a class="link" href="pgwalinspect.html" title="F.37. pg_walinspect"><span class="application">pg_walinspect</span></a>
+ (Bharath Rupireddy)
+ </p><p>
+ This gives <acronym class="acronym">SQL</acronym>-level output similar to <a class="link" href="pgwaldump.html" title="pg_waldump"><span class="application">pg_waldump</span></a>.
+ </p></li><li class="listitem"><p>
+ Indicate the permissive/enforcing state in <a class="link" href="sepgsql.html" title="F.40. sepgsql"><span class="application">sepgsql</span></a> log
+ messages (Dave Page)
+ </p></li></ul></div><div class="sect4" id="id-1.11.6.10.5.14.3"><div class="titlepage"><div><div><h5 class="title">E.6.3.12.1. <a class="link" href="postgres-fdw.html" title="F.38. postgres_fdw"><span class="application">postgres_fdw</span></a></h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Allow postgres_fdw to push down <code class="literal">CASE</code> expressions
+ (Alexander Pyhalov)
+ </p></li><li class="listitem"><p>
+ Add server variable
+ <code class="varname">postgres_fdw.application_name</code> to control the
+ application name of postgres_fdw connections (Hayato Kuroda)
+ </p><p>
+ Previously the remote session's <a class="link" href="runtime-config-logging.html#GUC-APPLICATION-NAME"><code class="varname">application_name</code></a>
+ could only be set on the remote server or via a
+ <span class="application">postgres_fdw</span> connection specification.
+ <code class="varname">postgres_fdw.application_name</code> supports some
+ escape sequences for customization, making it easier to tell such
+ connections apart on the remote server.
+ </p></li><li class="listitem"><p>
+ Allow parallel commit on <span class="application">postgres_fdw</span>
+ servers (Etsuro Fujita)
+ </p><p>
+ This is enabled with the <code class="literal">CREATE SERVER</code> option
+ <code class="literal">parallel_commit</code>.
+ </p></li></ul></div></div></div></div><div class="sect2" id="RELEASE-15-ACKNOWLEDGEMENTS"><div class="titlepage"><div><div><h3 class="title">E.6.4. Acknowledgments</h3></div></div></div><p>
+ The following individuals (in alphabetical order) have contributed
+ to this release as patch authors, committers, reviewers, testers,
+ or reporters of issues.
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td>Abhijit Menon-Sen</td></tr><tr><td>Adam Brusselback</td></tr><tr><td>Adam Mackler</td></tr><tr><td>Adrian Ho</td></tr><tr><td>Ahsan Hadi</td></tr><tr><td>Ajin Cherian</td></tr><tr><td>Alastair McKinley</td></tr><tr><td>Aleksander Alekseev</td></tr><tr><td>Ales Zeleny</td></tr><tr><td>Alex Kingsborough</td></tr><tr><td>Alex Kozhemyakin</td></tr><tr><td>Alexander Korotkov</td></tr><tr><td>Alexander Kukushkin</td></tr><tr><td>Alexander Lakhin</td></tr><tr><td>Alexander Nawratil</td></tr><tr><td>Alexander Pyhalov</td></tr><tr><td>Alexey Borzov</td></tr><tr><td>Alexey Ermakov</td></tr><tr><td>Aliaksandr Kalenik</td></tr><tr><td>Álvaro Herrera</td></tr><tr><td>Amit Kapila</td></tr><tr><td>Amit Khandekar</td></tr><tr><td>Amit Langote</td></tr><tr><td>Amul Sul</td></tr><tr><td>Anastasia Lubennikova</td></tr><tr><td>Anders Kaseorg</td></tr><tr><td>Andreas Dijkman</td></tr><tr><td>Andreas Grob</td></tr><tr><td>Andreas Seltenreich</td></tr><tr><td>Andrei Zubkov</td></tr><tr><td>Andres Freund</td></tr><tr><td>Andrew Alsup</td></tr><tr><td>Andrew Bille</td></tr><tr><td>Andrew Dunstan</td></tr><tr><td>Andrew Gierth</td></tr><tr><td>Andrew Kesper</td></tr><tr><td>Andrey Borodin</td></tr><tr><td>Andrey Lepikhov</td></tr><tr><td>Andrey Sokolov</td></tr><tr><td>Andy Fan</td></tr><tr><td>Anton Melnikov</td></tr><tr><td>Anton Voloshin</td></tr><tr><td>Antonin Houska</td></tr><tr><td>Arjan van de Ven</td></tr><tr><td>Arne Roland</td></tr><tr><td>Arthur Zakirov</td></tr><tr><td>Ashutosh Bapat</td></tr><tr><td>Ashutosh Sharma</td></tr><tr><td>Ashwin Agrawal</td></tr><tr><td>Asif Rehman</td></tr><tr><td>Asim Praveen</td></tr><tr><td>Atsushi Torikoshi</td></tr><tr><td>Aya Iwata</td></tr><tr><td>Bauyrzhan Sakhariyev</td></tr><tr><td>Benoit Lobréau</td></tr><tr><td>Bernd Dorn</td></tr><tr><td>Bertrand Drouvot</td></tr><tr><td>Bharath Rupireddy</td></tr><tr><td>Björn Harrtell</td></tr><tr><td>Boris Kolpackov</td></tr><tr><td>Boris Korzun</td></tr><tr><td>Brad Nicholson</td></tr><tr><td>Brar Piening</td></tr><tr><td>Bruce Momjian</td></tr><tr><td>Bruno da Silva</td></tr><tr><td>Bryn Llewellyn</td></tr><tr><td>Carl Sopchak</td></tr><tr><td>Cary Huang</td></tr><tr><td>Chapman Flack</td></tr><tr><td>Chen Jiaoqian</td></tr><tr><td>Chris Bandy</td></tr><tr><td>Chris Lowder</td></tr><tr><td>Christian Quest</td></tr><tr><td>Christoph Berg</td></tr><tr><td>Christoph Heiss</td></tr><tr><td>Christophe Pettus</td></tr><tr><td>Christopher Painter-Wakefield</td></tr><tr><td>Claudio Freire</td></tr><tr><td>Clemens Zeidler</td></tr><tr><td>Corey Huinker</td></tr><tr><td>Dag Lem</td></tr><tr><td>Dagfinn Ilmari Mannsåker</td></tr><tr><td>Dan Kubb</td></tr><tr><td>Daniel Cherniy</td></tr><tr><td>Daniel Gustafsson</td></tr><tr><td>Daniel Polski</td></tr><tr><td>Daniel Vérité</td></tr><tr><td>Daniel Westermann</td></tr><tr><td>Daniele Varrazzo</td></tr><tr><td>Daniil Anisimov</td></tr><tr><td>Danny Shemesh</td></tr><tr><td>Darafei Praliaskouski</td></tr><tr><td>Daria Lepikhova</td></tr><tr><td>Dave Cramer</td></tr><tr><td>Dave Page</td></tr><tr><td>David Christensen</td></tr><tr><td>David Fetter</td></tr><tr><td>David G. Johnston</td></tr><tr><td>David Rowley</td></tr><tr><td>David Steele</td></tr><tr><td>David Zhang</td></tr><tr><td>Dean Rasheed</td></tr><tr><td>Dian Fay</td></tr><tr><td>Dilip Kumar</td></tr><tr><td>Dipesh Pandit</td></tr><tr><td>Dmitry Dolgov</td></tr><tr><td>Dmitry Koval</td></tr><tr><td>Dmitry Marakasov</td></tr><tr><td>Dominique Devienne</td></tr><tr><td>Dong Wook</td></tr><tr><td>Drew DeVault</td></tr><tr><td>Eduard Català</td></tr><tr><td>Egor Chindyaskin</td></tr><tr><td>Egor Rogov</td></tr><tr><td>Ekaterina Kiryanova</td></tr><tr><td>Elena Indrupskaya</td></tr><tr><td>Elvis Pranskevichus</td></tr><tr><td>Emmanuel Quincerot</td></tr><tr><td>Emre Hasegeli</td></tr><tr><td>Eric Mutta</td></tr><tr><td>Erica Zhang</td></tr><tr><td>Erik Rijkers</td></tr><tr><td>Erki Eessaar</td></tr><tr><td>Etsuro Fujita</td></tr><tr><td>Euler Taveira</td></tr><tr><td>Fabien Coelho</td></tr><tr><td>Fabrice Chapuis</td></tr><tr><td>Fabrice Fontaine</td></tr><tr><td>Fabrízio de Royes Mello</td></tr><tr><td>Feike Steenbergen</td></tr><tr><td>Filip Gospodinov</td></tr><tr><td>Florin Irion</td></tr><tr><td>Floris Van Nee</td></tr><tr><td>Frédéric Yhuel</td></tr><tr><td>Gabriela Serventi</td></tr><tr><td>Gaurab Dey</td></tr><tr><td>Geoff Winkless</td></tr><tr><td>Geoffrey Blake</td></tr><tr><td>Georgios Kokolatos</td></tr><tr><td>Gilles Darold</td></tr><tr><td>Greg Nancarrow</td></tr><tr><td>Greg Rychlewski</td></tr><tr><td>Greg Sabino Mullane</td></tr><tr><td>Greg Stark</td></tr><tr><td>Gregory Smith</td></tr><tr><td>Guillaume Lelarge</td></tr><tr><td>Gunnar Bluth</td></tr><tr><td>Gurjeet Singh</td></tr><tr><td>Haiyang Wang</td></tr><tr><td>Haiying Tang</td></tr><tr><td>Hannu Krosing</td></tr><tr><td>Hans Buschmann</td></tr><tr><td>Hayato Kuroda</td></tr><tr><td>Heath Lord</td></tr><tr><td>Heikki Linnakangas</td></tr><tr><td>Herwig Goemans</td></tr><tr><td>Himanshu Upadhyaya</td></tr><tr><td>Holly Roberts</td></tr><tr><td>Hou Zhijie</td></tr><tr><td>Hubert Lubaczewski</td></tr><tr><td>Ian Barwick</td></tr><tr><td>Ian Campbell</td></tr><tr><td>Ibrar Ahmed</td></tr><tr><td>Ildus Kurbangaliev</td></tr><tr><td>Ilya Anfimov</td></tr><tr><td>Itamar Gafni</td></tr><tr><td>Jacob Champion</td></tr><tr><td>Jaime Casanova</td></tr><tr><td>Jakub Wartak</td></tr><tr><td>James Coleman</td></tr><tr><td>James Hilliard</td></tr><tr><td>James Inform</td></tr><tr><td>Jan Piotrowski</td></tr><tr><td>Japin Li</td></tr><tr><td>Jason Harvey</td></tr><tr><td>Jason Kim</td></tr><tr><td>Jean-Christophe Arnu</td></tr><tr><td>Jeevan Ladhe</td></tr><tr><td>Jeff Davis</td></tr><tr><td>Jeff Janes</td></tr><tr><td>Jehan-Guillaume de Rorthais</td></tr><tr><td>Jelte Fennema</td></tr><tr><td>Jeremy Evans</td></tr><tr><td>Jeremy Schneider</td></tr><tr><td>Jian Guo</td></tr><tr><td>Jian He</td></tr><tr><td>Jimmy Yih</td></tr><tr><td>Jiri Fejfar</td></tr><tr><td>Jitka Plesníková</td></tr><tr><td>Joe Conway</td></tr><tr><td>Joe Wildish</td></tr><tr><td>Joel Jacobson</td></tr><tr><td>Joey Bodoia</td></tr><tr><td>John Naylor</td></tr><tr><td>Jonathan Katz</td></tr><tr><td>Josef Simanek</td></tr><tr><td>Joseph Koshakow</td></tr><tr><td>Josh Soref</td></tr><tr><td>Joshua Brindle</td></tr><tr><td>Juan José Santamaría Flecha</td></tr><tr><td>Julien Rouhaud</td></tr><tr><td>Julien Roze</td></tr><tr><td>Junwang Zhao</td></tr><tr><td>Jürgen Purtz</td></tr><tr><td>Justin Pryzby</td></tr><tr><td>Ken Kato</td></tr><tr><td>Kevin Burke</td></tr><tr><td>Kevin Grittner</td></tr><tr><td>Kevin Humphreys</td></tr><tr><td>Kevin McKibbin</td></tr><tr><td>Kevin Sweet</td></tr><tr><td>Kevin Zheng</td></tr><tr><td>Klaudie Willis</td></tr><tr><td>Konstantin Knizhnik</td></tr><tr><td>Konstantina Skovola</td></tr><tr><td>Kosei Masumura</td></tr><tr><td>Kotaro Kawamoto</td></tr><tr><td>Koyu Tanigawa</td></tr><tr><td>Kuntal Ghosh</td></tr><tr><td>Kyotaro Horiguchi</td></tr><tr><td>Lars Kanis</td></tr><tr><td>Lauren Fliksteen</td></tr><tr><td>Laurent Hasson</td></tr><tr><td>Laurenz Albe</td></tr><tr><td>Leslie Lemaire</td></tr><tr><td>Liam Bowen</td></tr><tr><td>Lingjie Qiang</td></tr><tr><td>Liu Huailing</td></tr><tr><td>Louis Jachiet</td></tr><tr><td>Lukas Fittl</td></tr><tr><td>Ma Liangzhu</td></tr><tr><td>Maciek Sakrejda</td></tr><tr><td>Magnus Hagander</td></tr><tr><td>Mahendra Singh Thalor</td></tr><tr><td>Maksim Milyutin</td></tr><tr><td>Marc Bachmann</td></tr><tr><td>Marcin Krupowicz</td></tr><tr><td>Marcus Gartner</td></tr><tr><td>Marek Szuba</td></tr><tr><td>Marina Polyakova</td></tr><tr><td>Mario Emmenlauer</td></tr><tr><td>Mark Dilger</td></tr><tr><td>Mark Murawski</td></tr><tr><td>Mark Wong</td></tr><tr><td>Markus Wanner</td></tr><tr><td>Markus Winand</td></tr><tr><td>Martijn van Oosterhout</td></tr><tr><td>Martin Jurca</td></tr><tr><td>Martin Kalcher</td></tr><tr><td>Martín Marqués</td></tr><tr><td>Masahiko Sawada</td></tr><tr><td>Masahiro Ikeda</td></tr><tr><td>Masao Fujii</td></tr><tr><td>Masaya Kawamoto</td></tr><tr><td>Masayuki Hirose</td></tr><tr><td>Matthias van de Meent</td></tr><tr><td>Matthijs van der Vleuten</td></tr><tr><td>Maxim Orlov</td></tr><tr><td>Maxim Yablokov</td></tr><tr><td>Melanie Plageman</td></tr><tr><td>Michael Banck</td></tr><tr><td>Michael Harris</td></tr><tr><td>Michael J. Sullivan</td></tr><tr><td>Michael Meskes</td></tr><tr><td>Michael Mühlbeyer</td></tr><tr><td>Michael Paquier</td></tr><tr><td>Michael Powers</td></tr><tr><td>Mike Fiedler</td></tr><tr><td>Mike Oh</td></tr><tr><td>Mikhail Kulagin</td></tr><tr><td>Miles Delahunty</td></tr><tr><td>Naoki Okano</td></tr><tr><td>Nathan Bossart</td></tr><tr><td>Nathan Long</td></tr><tr><td>Nazir Bilal Yavuz</td></tr><tr><td>Neha Sharma</td></tr><tr><td>Neil Chen</td></tr><tr><td>Nicola Contu</td></tr><tr><td>Nicolas Lutic</td></tr><tr><td>Nikhil Benesch</td></tr><tr><td>Nikhil Shetty</td></tr><tr><td>Nikhil Sontakke</td></tr><tr><td>Nikita Glukhov</td></tr><tr><td>Nikolai Berkoff</td></tr><tr><td>Nikolay Samokhvalov</td></tr><tr><td>Nikolay Shaplov</td></tr><tr><td>Nitin Jadhav</td></tr><tr><td>Noah Misch</td></tr><tr><td>Noboru Saito</td></tr><tr><td>Noriyoshi Shinoda</td></tr><tr><td>Olaf Bohlen</td></tr><tr><td>Olly Betts</td></tr><tr><td>Onder Kalaci</td></tr><tr><td>Oskar Stenberg</td></tr><tr><td>Otto Kekalainen</td></tr><tr><td>Paul Guo</td></tr><tr><td>Paul Jungwirth</td></tr><tr><td>Paul Martinez</td></tr><tr><td>Pavan Deolasee</td></tr><tr><td>Pavel Borisov</td></tr><tr><td>Pavel Luzanov</td></tr><tr><td>Pavel Stehule</td></tr><tr><td>Peter Eisentraut</td></tr><tr><td>Peter Geoghegan</td></tr><tr><td>Peter Slavov</td></tr><tr><td>Peter Smith</td></tr><tr><td>Petr Jelínek</td></tr><tr><td>Phil Florent</td></tr><tr><td>Phil Krylov</td></tr><tr><td>Pierre-Aurélien Georges</td></tr><tr><td>Prabhat Sahu</td></tr><tr><td>Quan Zongliang</td></tr><tr><td>Rachel Heaton</td></tr><tr><td>Rahila Syed</td></tr><tr><td>Rajakavitha Kodhandapani</td></tr><tr><td>Rajkumar Raghuwanshi</td></tr><tr><td>Ranier Vilela</td></tr><tr><td>Rei Kamigishi</td></tr><tr><td>Reid Thompson</td></tr><tr><td>Rémi Lapeyre</td></tr><tr><td>Renan Soares Lopes</td></tr><tr><td>Richard Guo</td></tr><tr><td>Richard Wesley</td></tr><tr><td>RKN Sai Krishna</td></tr><tr><td>Robert Haas</td></tr><tr><td>Robert Treat</td></tr><tr><td>Roberto Mello</td></tr><tr><td>Robins Tharakan</td></tr><tr><td>Roger Mason</td></tr><tr><td>Roman Zharkov</td></tr><tr><td>Ronan Dunklau</td></tr><tr><td>Rui Zhao</td></tr><tr><td>Ryan Kelly</td></tr><tr><td>Ryo Matsumura</td></tr><tr><td>Ryohei Takahashi</td></tr><tr><td>Sadhuprasad Patro</td></tr><tr><td>Sait Talha Nisanci</td></tr><tr><td>Sami Imseih</td></tr><tr><td>Sandeep Thakkar</td></tr><tr><td>Sebastian Kemper</td></tr><tr><td>Sehrope Sarkuni</td></tr><tr><td>Sergei Kornilov</td></tr><tr><td>Sergei Shoulbakov</td></tr><tr><td>Sergey Shinderuk</td></tr><tr><td>Shay Rojansky</td></tr><tr><td>Shenhao Wang</td></tr><tr><td>Shi Yu</td></tr><tr><td>Shinya Kato</td></tr><tr><td>Shruthi Gowda</td></tr><tr><td>Simon Perepelitsa</td></tr><tr><td>Simon Riggs</td></tr><tr><td>Sirisha Chamarthi</td></tr><tr><td>Soumyadeep Chakraborty</td></tr><tr><td>Stan Hu</td></tr><tr><td>Stas Kelvich</td></tr><tr><td>Stefen Hillman</td></tr><tr><td>Stephen Frost</td></tr><tr><td>Steve Chavez</td></tr><tr><td>Sumanta Mukherjee</td></tr><tr><td>Suraj Khamkar</td></tr><tr><td>Suraj Kharage</td></tr><tr><td>Sven Klemm</td></tr><tr><td>Takamichi Osumi</td></tr><tr><td>Takayuki Tsunakawa</td></tr><tr><td>Takeshi Ideriha</td></tr><tr><td>Tatsuhiro Nakamori</td></tr><tr><td>Tatsuhito Kasahara</td></tr><tr><td>Tatsuo Ishii</td></tr><tr><td>Tatsuro Yamada</td></tr><tr><td>Teja Mupparti</td></tr><tr><td>Teodor Sigaev</td></tr><tr><td>Thibaud Walkowiak</td></tr><tr><td>Thom Brown</td></tr><tr><td>Thomas McKay</td></tr><tr><td>Thomas Munro</td></tr><tr><td>Tim McNamara</td></tr><tr><td>Timo Stolz</td></tr><tr><td>Timur Khanjanov</td></tr><tr><td>Tom Lane</td></tr><tr><td>Tomas Barton</td></tr><tr><td>Tomas Vondra</td></tr><tr><td>Tony Reix</td></tr><tr><td>Troy Frericks</td></tr><tr><td>Tushar Ahuja</td></tr><tr><td>Victor Wagner</td></tr><tr><td>Victor Yegorov</td></tr><tr><td>Vignesh C</td></tr><tr><td>Vik Fearing</td></tr><tr><td>Vincas Dargis</td></tr><tr><td>Vitaly Burovoy</td></tr><tr><td>Vitaly Voronov</td></tr><tr><td>Vladimir Sitnikov</td></tr><tr><td>Wang Ke</td></tr><tr><td>Wei Sun</td></tr><tr><td>Wei Wang</td></tr><tr><td>Whale Song</td></tr><tr><td>Will Mortensen</td></tr><tr><td>Wolfgang Walther</td></tr><tr><td>Yanliang Lei</td></tr><tr><td>Yaoguang Chen</td></tr><tr><td>Yogendra Suralkar</td></tr><tr><td>YoungHwan Joo</td></tr><tr><td>Yugo Nagata</td></tr><tr><td>Yukun Wang</td></tr><tr><td>Yura Sokolov</td></tr><tr><td>Yusuke Egashira</td></tr><tr><td>Yuzuko Hosoya</td></tr><tr><td>Zhang Mingli</td></tr><tr><td>Zhang Wenjie</td></tr><tr><td>Zhihong Yu</td></tr><tr><td>Zhiyong Wu</td></tr></table></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15-1.html" title="E.5. Release 15.1">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-prior.html" title="E.7. Prior Releases">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.5. Release 15.1 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.7. Prior Releases</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release-prior.html b/doc/src/sgml/html/release-prior.html
new file mode 100644
index 0000000..327a972
--- /dev/null
+++ b/doc/src/sgml/html/release-prior.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>E.7. Prior Releases</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="release-15.html" title="E.6. Release 15" /><link rel="next" href="contrib.html" title="Appendix F. Additional Supplied Modules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">E.7. Prior Releases</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="release-15.html" title="E.6. Release 15">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><th width="60%" align="center">Appendix E. Release Notes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib.html" title="Appendix F. Additional Supplied Modules">Next</a></td></tr></table><hr /></div><div class="sect1" id="RELEASE-PRIOR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">E.7. Prior Releases</h2></div></div></div><p>
+ Release notes for prior release branches can be found at
+ <a class="ulink" href="https://www.postgresql.org/docs/release/" target="_top"><code class="literal">https://www.postgresql.org/docs/release/</code></a>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-15.html" title="E.6. Release 15">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="release.html" title="Appendix E. Release Notes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib.html" title="Appendix F. Additional Supplied Modules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E.6. Release 15 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix F. Additional Supplied Modules</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/release.html b/doc/src/sgml/html/release.html
new file mode 100644
index 0000000..943ee30
--- /dev/null
+++ b/doc/src/sgml/html/release.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. Release Notes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML" /><link rel="next" href="release-15-5.html" title="E.1. Release 15.5" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix E. Release Notes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release-15-5.html" title="E.1. Release 15.5">Next</a></td></tr></table><hr /></div><div class="appendix" id="RELEASE"><div class="titlepage"><div><div><h2 class="title">Appendix E. Release Notes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="release-15-5.html">E.1. Release 15.5</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15-5.html#id-1.11.6.5.4">E.1.1. Migration to Version 15.5</a></span></dt><dt><span class="sect2"><a href="release-15-5.html#id-1.11.6.5.5">E.1.2. Changes</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-15-4.html">E.2. Release 15.4</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15-4.html#id-1.11.6.6.4">E.2.1. Migration to Version 15.4</a></span></dt><dt><span class="sect2"><a href="release-15-4.html#id-1.11.6.6.5">E.2.2. Changes</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-15-3.html">E.3. Release 15.3</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15-3.html#id-1.11.6.7.4">E.3.1. Migration to Version 15.3</a></span></dt><dt><span class="sect2"><a href="release-15-3.html#id-1.11.6.7.5">E.3.2. Changes</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-15-2.html">E.4. Release 15.2</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15-2.html#id-1.11.6.8.4">E.4.1. Migration to Version 15.2</a></span></dt><dt><span class="sect2"><a href="release-15-2.html#id-1.11.6.8.5">E.4.2. Changes</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-15-1.html">E.5. Release 15.1</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15-1.html#id-1.11.6.9.4">E.5.1. Migration to Version 15.1</a></span></dt><dt><span class="sect2"><a href="release-15-1.html#id-1.11.6.9.5">E.5.2. Changes</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-15.html">E.6. Release 15</a></span></dt><dd><dl><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.3">E.6.1. Overview</a></span></dt><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.4">E.6.2. Migration to Version 15</a></span></dt><dt><span class="sect2"><a href="release-15.html#id-1.11.6.10.5">E.6.3. Changes</a></span></dt><dt><span class="sect2"><a href="release-15.html#RELEASE-15-ACKNOWLEDGEMENTS">E.6.4. Acknowledgments</a></span></dt></dl></dd><dt><span class="sect1"><a href="release-prior.html">E.7. Prior Releases</a></span></dt></dl></div><p>
+ The release notes contain the significant changes in each
+ <span class="productname">PostgreSQL</span> release, with major features and migration
+ issues listed at the top. The release notes do not contain changes
+ that affect only a few users or changes that are internal and therefore not
+ user-visible. For example, the optimizer is improved in almost every
+ release, but the improvements are usually observed by users as simply
+ faster queries.
+ </p><p>
+ A complete list of changes for each release can be obtained by
+ viewing the <a class="link" href="git.html" title="I.1. Getting the Source via Git">Git</a> logs for each release.
+ The <a class="ulink" href="https://www.postgresql.org/list/pgsql-committers/" target="_top"><code class="literal">pgsql-committers</code>
+ email list</a> records all source code changes as well. There is also
+ a <a class="ulink" href="https://git.postgresql.org/gitweb/?p=postgresql.git;a=summary" target="_top">web
+ interface</a> that shows changes to specific files.
+ </p><p>
+ The name appearing next to each item represents the major developer for
+ that item. Of course all changes involve community discussion and patch
+ review, so each item is truly a community effort.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release-15-5.html" title="E.1. Release 15.5">Next</a></td></tr><tr><td width="40%" align="left" valign="top">D.3. XML Limits and Conformance to SQL/XML </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> E.1. Release 15.5</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/replication-origins.html b/doc/src/sgml/html/replication-origins.html
new file mode 100644
index 0000000..ab687ef
--- /dev/null
+++ b/doc/src/sgml/html/replication-origins.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 50. Replication Progress Tracking</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding" /><link rel="next" href="archive-modules.html" title="Chapter 51. Archive Modules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 50. Replication Progress Tracking</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="archive-modules.html" title="Chapter 51. Archive Modules">Next</a></td></tr></table><hr /></div><div class="chapter" id="REPLICATION-ORIGINS"><div class="titlepage"><div><div><h2 class="title">Chapter 50. Replication Progress Tracking</h2></div></div></div><a id="id-1.8.15.2" class="indexterm"></a><a id="id-1.8.15.3" class="indexterm"></a><p>
+ Replication origins are intended to make it easier to implement
+ logical replication solutions on top
+ of <a class="link" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">logical decoding</a>.
+ They provide a solution to two common problems:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>How to safely keep track of replication progress</p></li><li class="listitem"><p>How to change replication behavior based on the
+ origin of a row; for example, to prevent loops in bi-directional
+ replication setups</p></li></ul></div><p>
+ </p><p>
+ Replication origins have just two properties, a name and an ID. The name,
+ which is what should be used to refer to the origin across systems, is
+ free-form <code class="type">text</code>. It should be used in a way that makes conflicts
+ between replication origins created by different replication solutions
+ unlikely; e.g., by prefixing the replication solution's name to it.
+ The ID is used only to avoid having to store the long version
+ in situations where space efficiency is important. It should never be shared
+ across systems.
+ </p><p>
+ Replication origins can be created using the function
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-CREATE"><code class="function">pg_replication_origin_create()</code></a>;
+ dropped using
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-DROP"><code class="function">pg_replication_origin_drop()</code></a>;
+ and seen in the
+ <a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin"><code class="structname">pg_replication_origin</code></a>
+ system catalog.
+ </p><p>
+ One nontrivial part of building a replication solution is to keep track of
+ replay progress in a safe manner. When the applying process, or the whole
+ cluster, dies, it needs to be possible to find out up to where data has
+ successfully been replicated. Naive solutions to this, such as updating a
+ row in a table for every replayed transaction, have problems like run-time
+ overhead and database bloat.
+ </p><p>
+ Using the replication origin infrastructure a session can be
+ marked as replaying from a remote node (using the
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-SESSION-SETUP"><code class="function">pg_replication_origin_session_setup()</code></a>
+ function). Additionally the <acronym class="acronym">LSN</acronym> and commit
+ time stamp of every source transaction can be configured on a per
+ transaction basis using
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-XACT-SETUP"><code class="function">pg_replication_origin_xact_setup()</code></a>.
+ If that's done replication progress will persist in a crash safe
+ manner. Replay progress for all replication origins can be seen in the
+ <a class="link" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">
+ <code class="structname">pg_replication_origin_status</code>
+ </a> view. An individual origin's progress, e.g., when resuming
+ replication, can be acquired using
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-PROGRESS"><code class="function">pg_replication_origin_progress()</code></a>
+ for any origin or
+ <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-SESSION-PROGRESS"><code class="function">pg_replication_origin_session_progress()</code></a>
+ for the origin configured in the current session.
+ </p><p>
+ In replication topologies more complex than replication from exactly one
+ system to one other system, another problem can be that it is hard to avoid
+ replicating replayed rows again. That can lead both to cycles in the
+ replication and inefficiencies. Replication origins provide an optional
+ mechanism to recognize and prevent that. When configured using the functions
+ referenced in the previous paragraph, every change and transaction passed to
+ output plugin callbacks (see <a class="xref" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Section 49.6</a>)
+ generated by the session is tagged with the replication origin of the
+ generating session. This allows treating them differently in the output
+ plugin, e.g., ignoring all but locally-originating rows. Additionally
+ the <a class="link" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN" title="49.6.4.7. Origin Filter Callback">
+ <code class="function">filter_by_origin_cb</code></a> callback can be used
+ to filter the logical decoding change stream based on the
+ source. While less flexible, filtering via that callback is
+ considerably more efficient than doing it in the output plugin.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="archive-modules.html" title="Chapter 51. Archive Modules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.10. Two-phase Commit Support for Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 51. Archive Modules</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/resources.html b/doc/src/sgml/html/resources.html
new file mode 100644
index 0000000..32397d6
--- /dev/null
+++ b/doc/src/sgml/html/resources.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4. Further Information</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="notation.html" title="3. Conventions" /><link rel="next" href="bug-reporting.html" title="5. Bug Reporting Guidelines" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">4. Further Information</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="notation.html" title="3. Conventions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bug-reporting.html" title="5. Bug Reporting Guidelines">Next</a></td></tr></table><hr /></div><div class="sect1" id="RESOURCES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">4. Further Information</h2></div></div></div><p>
+ Besides the documentation, that is, this book, there are other
+ resources about <span class="productname">PostgreSQL</span>:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Wiki</span></dt><dd><p>
+ The <span class="productname">PostgreSQL</span> <a class="ulink" href="https://wiki.postgresql.org" target="_top">wiki</a> contains the project's <a class="ulink" href="https://wiki.postgresql.org/wiki/Frequently_Asked_Questions" target="_top">FAQ</a>
+ (Frequently Asked Questions) list, <a class="ulink" href="https://wiki.postgresql.org/wiki/Todo" target="_top">TODO</a> list, and
+ detailed information about many more topics.
+ </p></dd><dt><span class="term">Web Site</span></dt><dd><p>
+ The <span class="productname">PostgreSQL</span>
+ <a class="ulink" href="https://www.postgresql.org" target="_top">web site</a>
+ carries details on the latest release and other
+ information to make your work or play with
+ <span class="productname">PostgreSQL</span> more productive.
+ </p></dd><dt><span class="term">Mailing Lists</span></dt><dd><p>
+ The mailing lists are a good place to have your questions
+ answered, to share experiences with other users, and to contact
+ the developers. Consult the <span class="productname">PostgreSQL</span> web site
+ for details.
+ </p></dd><dt><span class="term">Yourself!</span></dt><dd><p>
+ <span class="productname">PostgreSQL</span> is an open-source project.
+ As such, it depends on the user community for ongoing support.
+ As you begin to use <span class="productname">PostgreSQL</span>, you
+ will rely on others for help, either through the documentation
+ or through the mailing lists. Consider contributing your
+ knowledge back. Read the mailing lists and answer questions. If
+ you learn something which is not in the documentation, write it
+ up and contribute it. If you add features to the code,
+ contribute them.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="notation.html" title="3. Conventions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bug-reporting.html" title="5. Bug Reporting Guidelines">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Conventions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 5. Bug Reporting Guidelines</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/role-attributes.html b/doc/src/sgml/html/role-attributes.html
new file mode 100644
index 0000000..8db141c
--- /dev/null
+++ b/doc/src/sgml/html/role-attributes.html
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.2. Role Attributes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="database-roles.html" title="22.1. Database Roles" /><link rel="next" href="role-membership.html" title="22.3. Role Membership" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.2. Role Attributes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="database-roles.html" title="22.1. Database Roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="role-membership.html" title="22.3. Role Membership">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROLE-ATTRIBUTES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.2. Role Attributes</h2></div></div></div><p>
+ A database role can have a number of attributes that define its
+ privileges and interact with the client authentication system.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">login privilege<a id="id-1.6.9.6.2.1.1.1.1" class="indexterm"></a></span></dt><dd><p>
+ Only roles that have the <code class="literal">LOGIN</code> attribute can be used
+ as the initial role name for a database connection. A role with
+ the <code class="literal">LOGIN</code> attribute can be considered the same
+ as a <span class="quote">“<span class="quote">database user</span>”</span>. To create a role with login privilege,
+ use either:
+</p><pre class="programlisting">
+CREATE ROLE <em class="replaceable"><code>name</code></em> LOGIN;
+CREATE USER <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ (<code class="command">CREATE USER</code> is equivalent to <code class="command">CREATE ROLE</code>
+ except that <code class="command">CREATE USER</code> includes <code class="literal">LOGIN</code> by
+ default, while <code class="command">CREATE ROLE</code> does not.)
+ </p></dd><dt><span class="term">superuser status<a id="id-1.6.9.6.2.1.2.1.1" class="indexterm"></a></span></dt><dd><p>
+ A database superuser bypasses all permission checks, except the right
+ to log in. This is a dangerous privilege and should not be used
+ carelessly; it is best to do most of your work as a role that is not a
+ superuser. To create a new database superuser, use <code class="literal">CREATE
+ ROLE <em class="replaceable"><code>name</code></em> SUPERUSER</code>. You must do
+ this as a role that is already a superuser.
+ </p></dd><dt><span class="term">database creation<a id="id-1.6.9.6.2.1.3.1.1" class="indexterm"></a></span></dt><dd><p>
+ A role must be explicitly given permission to create databases
+ (except for superusers, since those bypass all permission
+ checks). To create such a role, use <code class="literal">CREATE ROLE
+ <em class="replaceable"><code>name</code></em> CREATEDB</code>.
+ </p></dd><dt><span class="term" id="ROLE-CREATION">role creation<a id="id-1.6.9.6.2.1.4.1.1" class="indexterm"></a></span></dt><dd><p>
+ A role must be explicitly given permission to create more roles
+ (except for superusers, since those bypass all permission
+ checks). To create such a role, use <code class="literal">CREATE ROLE
+ <em class="replaceable"><code>name</code></em> CREATEROLE</code>.
+ A role with <code class="literal">CREATEROLE</code> privilege can alter and drop
+ other roles, too, as well as grant or revoke membership in them.
+ Altering a role includes most changes that can be made using
+ <code class="literal">ALTER ROLE</code>, including, for example, changing
+ passwords. It also includes modifications to a role that can
+ be made using the <code class="literal">COMMENT</code> and
+ <code class="literal">SECURITY LABEL</code> commands.
+ </p><p>
+ However, <code class="literal">CREATEROLE</code> does not convey the ability to
+ create <code class="literal">SUPERUSER</code> roles, nor does it convey any
+ power over <code class="literal">SUPERUSER</code> roles that already exist.
+ Furthermore, <code class="literal">CREATEROLE</code> does not convey the power
+ to create <code class="literal">REPLICATION</code> users, nor the ability to
+ grant or revoke the <code class="literal">REPLICATION</code> privilege, nor the
+ ability to modify the role properties of such users. However, it does
+ allow <code class="literal">ALTER ROLE ... SET</code> and
+ <code class="literal">ALTER ROLE ... RENAME</code> to be used on
+ <code class="literal">REPLICATION</code> roles, as well as the use of
+ <code class="literal">COMMENT ON ROLE</code>,
+ <code class="literal">SECURITY LABEL ON ROLE</code>,
+ and <code class="literal">DROP ROLE</code>.
+ Finally, <code class="literal">CREATEROLE</code> does not
+ confer the ability to grant or revoke the <code class="literal">BYPASSRLS</code>
+ privilege.
+ </p><p>
+ Because the <code class="literal">CREATEROLE</code> privilege allows a user
+ to grant or revoke membership even in roles to which it does not (yet)
+ have any access, a <code class="literal">CREATEROLE</code> user can obtain access
+ to the capabilities of every predefined role in the system, including
+ highly privileged roles such as
+ <code class="literal">pg_execute_server_program</code> and
+ <code class="literal">pg_write_server_files</code>.
+ </p></dd><dt><span class="term">initiating replication<a id="id-1.6.9.6.2.1.5.1.1" class="indexterm"></a></span></dt><dd><p>
+ A role must explicitly be given permission to initiate streaming
+ replication (except for superusers, since those bypass all permission
+ checks). A role used for streaming replication must
+ have <code class="literal">LOGIN</code> permission as well. To create such a role, use
+ <code class="literal">CREATE ROLE <em class="replaceable"><code>name</code></em> REPLICATION
+ LOGIN</code>.
+ </p></dd><dt><span class="term">password<a id="id-1.6.9.6.2.1.6.1.1" class="indexterm"></a></span></dt><dd><p>
+ A password is only significant if the client authentication
+ method requires the user to supply a password when connecting
+ to the database. The <code class="option">password</code> and
+ <code class="option">md5</code> authentication methods
+ make use of passwords. Database passwords are separate from
+ operating system passwords. Specify a password upon role
+ creation with <code class="literal">CREATE ROLE
+ <em class="replaceable"><code>name</code></em> PASSWORD '<em class="replaceable"><code>string</code></em>'</code>.
+ </p></dd><dt><span class="term">inheritance of privileges<a id="id-1.6.9.6.2.1.7.1.1" class="indexterm"></a></span></dt><dd><p>
+ A role is given permission to inherit the privileges of roles it is a
+ member of, by default. However, to create a role without the permission,
+ use <code class="literal">CREATE ROLE <em class="replaceable"><code>name</code></em> NOINHERIT</code>.
+ </p></dd><dt><span class="term">bypassing row-level security<a id="id-1.6.9.6.2.1.8.1.1" class="indexterm"></a></span></dt><dd><p>
+ A role must be explicitly given permission to bypass every row-level security (RLS) policy
+ (except for superusers, since those bypass all permission checks).
+ To create such a role, use <code class="literal">CREATE ROLE <em class="replaceable"><code>name</code></em> BYPASSRLS</code> as a superuser.
+ </p></dd><dt><span class="term">connection limit<a id="id-1.6.9.6.2.1.9.1.1" class="indexterm"></a></span></dt><dd><p>
+ Connection limit can specify how many concurrent connections a role can make.
+ -1 (the default) means no limit. Specify connection limit upon role creation with
+ <code class="literal">CREATE ROLE <em class="replaceable"><code>name</code></em> CONNECTION LIMIT '<em class="replaceable"><code>integer</code></em>'</code>.
+ </p></dd></dl></div><p>
+
+ A role's attributes can be modified after creation with
+ <code class="command">ALTER ROLE</code>.<a id="id-1.6.9.6.2.3" class="indexterm"></a>
+ See the reference pages for the <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>
+ and <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a> commands for details.
+ </p><p>
+ A role can also have role-specific defaults for many of the run-time
+ configuration settings described in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>. For example, if for some reason you
+ want to disable index scans (hint: not a good idea) anytime you
+ connect, you can use:
+</p><pre class="programlisting">
+ALTER ROLE myname SET enable_indexscan TO off;
+</pre><p>
+ This will save the setting (but not set it immediately). In
+ subsequent connections by this role it will appear as though
+ <code class="literal">SET enable_indexscan TO off</code> had been executed
+ just before the session started.
+ You can still alter this setting during the session; it will only
+ be the default. To remove a role-specific default setting, use
+ <code class="literal">ALTER ROLE <em class="replaceable"><code>rolename</code></em> RESET <em class="replaceable"><code>varname</code></em></code>.
+ Note that role-specific defaults attached to roles without
+ <code class="literal">LOGIN</code> privilege are fairly useless, since they will never
+ be invoked.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="database-roles.html" title="22.1. Database Roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="role-membership.html" title="22.3. Role Membership">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.1. Database Roles </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.3. Role Membership</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/role-membership.html b/doc/src/sgml/html/role-membership.html
new file mode 100644
index 0000000..3f2150a
--- /dev/null
+++ b/doc/src/sgml/html/role-membership.html
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.3. Role Membership</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="role-attributes.html" title="22.2. Role Attributes" /><link rel="next" href="role-removal.html" title="22.4. Dropping Roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.3. Role Membership</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="role-attributes.html" title="22.2. Role Attributes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="role-removal.html" title="22.4. Dropping Roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROLE-MEMBERSHIP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.3. Role Membership</h2></div></div></div><a id="id-1.6.9.7.2" class="indexterm"></a><p>
+ It is frequently convenient to group users together to ease
+ management of privileges: that way, privileges can be granted to, or
+ revoked from, a group as a whole. In <span class="productname">PostgreSQL</span>
+ this is done by creating a role that represents the group, and then
+ granting <em class="firstterm">membership</em> in the group role to individual user
+ roles.
+ </p><p>
+ To set up a group role, first create the role:
+</p><pre class="synopsis">
+CREATE ROLE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ Typically a role being used as a group would not have the <code class="literal">LOGIN</code>
+ attribute, though you can set it if you wish.
+ </p><p>
+ Once the group role exists, you can add and remove members using the
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a> commands:
+</p><pre class="synopsis">
+GRANT <em class="replaceable"><code>group_role</code></em> TO <em class="replaceable"><code>role1</code></em>, ... ;
+REVOKE <em class="replaceable"><code>group_role</code></em> FROM <em class="replaceable"><code>role1</code></em>, ... ;
+</pre><p>
+ You can grant membership to other group roles, too (since there isn't
+ really any distinction between group roles and non-group roles). The
+ database will not let you set up circular membership loops. Also,
+ it is not permitted to grant membership in a role to
+ <code class="literal">PUBLIC</code>.
+ </p><p>
+ The members of a group role can use the privileges of the role in two
+ ways. First, every member of a group can explicitly do
+ <a class="link" href="sql-set-role.html" title="SET ROLE"><code class="command">SET ROLE</code></a> to
+ temporarily <span class="quote">“<span class="quote">become</span>”</span> the group role. In this state, the
+ database session has access to the privileges of the group role rather
+ than the original login role, and any database objects created are
+ considered owned by the group role not the login role. Second, member
+ roles that have the <code class="literal">INHERIT</code> attribute automatically have use
+ of the privileges of roles of which they are members, including any
+ privileges inherited by those roles.
+ As an example, suppose we have done:
+</p><pre class="programlisting">
+CREATE ROLE joe LOGIN INHERIT;
+CREATE ROLE admin NOINHERIT;
+CREATE ROLE wheel NOINHERIT;
+GRANT admin TO joe;
+GRANT wheel TO admin;
+</pre><p>
+ Immediately after connecting as role <code class="literal">joe</code>, a database
+ session will have use of privileges granted directly to <code class="literal">joe</code>
+ plus any privileges granted to <code class="literal">admin</code>, because <code class="literal">joe</code>
+ <span class="quote">“<span class="quote">inherits</span>”</span> <code class="literal">admin</code>'s privileges. However, privileges
+ granted to <code class="literal">wheel</code> are not available, because even though
+ <code class="literal">joe</code> is indirectly a member of <code class="literal">wheel</code>, the
+ membership is via <code class="literal">admin</code> which has the <code class="literal">NOINHERIT</code>
+ attribute. After:
+</p><pre class="programlisting">
+SET ROLE admin;
+</pre><p>
+ the session would have use of only those privileges granted to
+ <code class="literal">admin</code>, and not those granted to <code class="literal">joe</code>. After:
+</p><pre class="programlisting">
+SET ROLE wheel;
+</pre><p>
+ the session would have use of only those privileges granted to
+ <code class="literal">wheel</code>, and not those granted to either <code class="literal">joe</code>
+ or <code class="literal">admin</code>. The original privilege state can be restored
+ with any of:
+</p><pre class="programlisting">
+SET ROLE joe;
+SET ROLE NONE;
+RESET ROLE;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="command">SET ROLE</code> command always allows selecting any role
+ that the original login role is directly or indirectly a member of.
+ Thus, in the above example, it is not necessary to become
+ <code class="literal">admin</code> before becoming <code class="literal">wheel</code>.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ In the SQL standard, there is a clear distinction between users and roles,
+ and users do not automatically inherit privileges while roles do. This
+ behavior can be obtained in <span class="productname">PostgreSQL</span> by giving
+ roles being used as SQL roles the <code class="literal">INHERIT</code> attribute, while
+ giving roles being used as SQL users the <code class="literal">NOINHERIT</code> attribute.
+ However, <span class="productname">PostgreSQL</span> defaults to giving all roles
+ the <code class="literal">INHERIT</code> attribute, for backward compatibility with pre-8.1
+ releases in which users always had use of permissions granted to groups
+ they were members of.
+ </p></div><p>
+ The role attributes <code class="literal">LOGIN</code>, <code class="literal">SUPERUSER</code>,
+ <code class="literal">CREATEDB</code>, and <code class="literal">CREATEROLE</code> can be thought of as
+ special privileges, but they are never inherited as ordinary privileges
+ on database objects are. You must actually <code class="command">SET ROLE</code> to a
+ specific role having one of these attributes in order to make use of
+ the attribute. Continuing the above example, we might choose to
+ grant <code class="literal">CREATEDB</code> and <code class="literal">CREATEROLE</code> to the
+ <code class="literal">admin</code> role. Then a session connecting as role <code class="literal">joe</code>
+ would not have these privileges immediately, only after doing
+ <code class="command">SET ROLE admin</code>.
+ </p><p>
+ </p><p>
+ To destroy a group role, use <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>:
+</p><pre class="synopsis">
+DROP ROLE <em class="replaceable"><code>name</code></em>;
+</pre><p>
+ Any memberships in the group role are automatically revoked (but the
+ member roles are not otherwise affected).
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="role-attributes.html" title="22.2. Role Attributes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="role-removal.html" title="22.4. Dropping Roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.2. Role Attributes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.4. Dropping Roles</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/role-removal.html b/doc/src/sgml/html/role-removal.html
new file mode 100644
index 0000000..d444827
--- /dev/null
+++ b/doc/src/sgml/html/role-removal.html
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>22.4. Dropping Roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="role-membership.html" title="22.3. Role Membership" /><link rel="next" href="predefined-roles.html" title="22.5. Predefined Roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">22.4. Dropping Roles</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="role-membership.html" title="22.3. Role Membership">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><th width="60%" align="center">Chapter 22. Database Roles</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="predefined-roles.html" title="22.5. Predefined Roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROLE-REMOVAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">22.4. Dropping Roles</h2></div></div></div><p>
+ Because roles can own database objects and can hold privileges
+ to access other objects, dropping a role is often not just a matter of a
+ quick <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>. Any objects owned by the role must
+ first be dropped or reassigned to other owners; and any permissions
+ granted to the role must be revoked.
+ </p><p>
+ Ownership of objects can be transferred one at a time
+ using <code class="command">ALTER</code> commands, for example:
+</p><pre class="programlisting">
+ALTER TABLE bobs_table OWNER TO alice;
+</pre><p>
+ Alternatively, the <a class="link" href="sql-reassign-owned.html" title="REASSIGN OWNED"><code class="command">REASSIGN OWNED</code></a> command can be
+ used to reassign ownership of all objects owned by the role-to-be-dropped
+ to a single other role. Because <code class="command">REASSIGN OWNED</code> cannot access
+ objects in other databases, it is necessary to run it in each database
+ that contains objects owned by the role. (Note that the first
+ such <code class="command">REASSIGN OWNED</code> will change the ownership of any
+ shared-across-databases objects, that is databases or tablespaces, that
+ are owned by the role-to-be-dropped.)
+ </p><p>
+ Once any valuable objects have been transferred to new owners, any
+ remaining objects owned by the role-to-be-dropped can be dropped with
+ the <a class="link" href="sql-drop-owned.html" title="DROP OWNED"><code class="command">DROP OWNED</code></a> command. Again, this command cannot
+ access objects in other databases, so it is necessary to run it in each
+ database that contains objects owned by the role. Also, <code class="command">DROP
+ OWNED</code> will not drop entire databases or tablespaces, so it is
+ necessary to do that manually if the role owns any databases or
+ tablespaces that have not been transferred to new owners.
+ </p><p>
+ <code class="command">DROP OWNED</code> also takes care of removing any privileges granted
+ to the target role for objects that do not belong to it.
+ Because <code class="command">REASSIGN OWNED</code> does not touch such objects, it's
+ typically necessary to run both <code class="command">REASSIGN OWNED</code>
+ and <code class="command">DROP OWNED</code> (in that order!) to fully remove the
+ dependencies of a role to be dropped.
+ </p><p>
+ In short then, the most general recipe for removing a role that has been
+ used to own objects is:
+ </p><pre class="programlisting">
+REASSIGN OWNED BY doomed_role TO successor_role;
+DROP OWNED BY doomed_role;
+-- repeat the above commands in each database of the cluster
+DROP ROLE doomed_role;
+</pre><p>
+ When not all owned objects are to be transferred to the same successor
+ owner, it's best to handle the exceptions manually and then perform
+ the above steps to mop up.
+ </p><p>
+ If <code class="command">DROP ROLE</code> is attempted while dependent objects still
+ remain, it will issue messages identifying which objects need to be
+ reassigned or dropped.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="role-membership.html" title="22.3. Role Membership">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-manag.html" title="Chapter 22. Database Roles">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="predefined-roles.html" title="22.5. Predefined Roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">22.3. Role Membership </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.5. Predefined Roles</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/routine-reindex.html b/doc/src/sgml/html/routine-reindex.html
new file mode 100644
index 0000000..e6195e0
--- /dev/null
+++ b/doc/src/sgml/html/routine-reindex.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>25.2. Routine Reindexing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="routine-vacuuming.html" title="25.1. Routine Vacuuming" /><link rel="next" href="logfile-maintenance.html" title="25.3. Log File Maintenance" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">25.2. Routine Reindexing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><th width="60%" align="center">Chapter 25. Routine Database Maintenance Tasks</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROUTINE-REINDEX"><div class="titlepage"><div><div><h2 class="title" style="clear: both">25.2. Routine Reindexing</h2></div></div></div><a id="id-1.6.12.11.2" class="indexterm"></a><p>
+ In some situations it is worthwhile to rebuild indexes periodically
+ with the <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a> command or a series of individual
+ rebuilding steps.
+
+ </p><p>
+ B-tree index pages that have become completely empty are reclaimed for
+ re-use. However, there is still a possibility
+ of inefficient use of space: if all but a few index keys on a page have
+ been deleted, the page remains allocated. Therefore, a usage
+ pattern in which most, but not all, keys in each range are eventually
+ deleted will see poor use of space. For such usage patterns,
+ periodic reindexing is recommended.
+ </p><p>
+ The potential for bloat in non-B-tree indexes has not been well
+ researched. It is a good idea to periodically monitor the index's physical
+ size when using any non-B-tree index type.
+ </p><p>
+ Also, for B-tree indexes, a freshly-constructed index is slightly faster to
+ access than one that has been updated many times because logically
+ adjacent pages are usually also physically adjacent in a newly built index.
+ (This consideration does not apply to non-B-tree indexes.) It
+ might be worthwhile to reindex periodically just to improve access speed.
+ </p><p>
+ <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a> can be used safely and easily in all cases.
+ This command requires an <code class="literal">ACCESS EXCLUSIVE</code> lock by
+ default, hence it is often preferable to execute it with its
+ <code class="literal">CONCURRENTLY</code> option, which requires only a
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Next</a></td></tr><tr><td width="40%" align="left" valign="top">25.1. Routine Vacuuming </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 25.3. Log File Maintenance</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/routine-vacuuming.html b/doc/src/sgml/html/routine-vacuuming.html
new file mode 100644
index 0000000..88ca08b
--- /dev/null
+++ b/doc/src/sgml/html/routine-vacuuming.html
@@ -0,0 +1,695 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>25.1. Routine Vacuuming</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks" /><link rel="next" href="routine-reindex.html" title="25.2. Routine Reindexing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">25.1. Routine Vacuuming</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><th width="60%" align="center">Chapter 25. Routine Database Maintenance Tasks</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="routine-reindex.html" title="25.2. Routine Reindexing">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROUTINE-VACUUMING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">25.1. Routine Vacuuming</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-BASICS">25.1.1. Vacuuming Basics</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-SPACE-RECOVERY">25.1.2. Recovering Disk Space</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-STATISTICS">25.1.3. Updating Planner Statistics</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-VISIBILITY-MAP">25.1.4. Updating the Visibility Map</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND">25.1.5. Preventing Transaction ID Wraparound Failures</a></span></dt><dt><span class="sect2"><a href="routine-vacuuming.html#AUTOVACUUM">25.1.6. The Autovacuum Daemon</a></span></dt></dl></div><a id="id-1.6.12.10.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> databases require periodic
+ maintenance known as <em class="firstterm">vacuuming</em>. For many installations, it
+ is sufficient to let vacuuming be performed by the <em class="firstterm">autovacuum
+ daemon</em>, which is described in <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>. You might
+ need to adjust the autovacuuming parameters described there to obtain best
+ results for your situation. Some database administrators will want to
+ supplement or replace the daemon's activities with manually-managed
+ <code class="command">VACUUM</code> commands, which typically are executed according to a
+ schedule by <span class="application">cron</span> or <span class="application">Task
+ Scheduler</span> scripts. To set up manually-managed vacuuming properly,
+ it is essential to understand the issues discussed in the next few
+ subsections. Administrators who rely on autovacuuming may still wish
+ to skim this material to help them understand and adjust autovacuuming.
+ </p><div class="sect2" id="VACUUM-BASICS"><div class="titlepage"><div><div><h3 class="title">25.1.1. Vacuuming Basics</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span>'s
+ <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a> command has to
+ process each table on a regular basis for several reasons:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">To recover or reuse disk space occupied by updated or deleted
+ rows.</li><li class="listitem">To update data statistics used by the
+ <span class="productname">PostgreSQL</span> query planner.</li><li class="listitem">To update the visibility map, which speeds
+ up <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">index-only
+ scans</a>.</li><li class="listitem">To protect against loss of very old data due to
+ <em class="firstterm">transaction ID wraparound</em> or
+ <em class="firstterm">multixact ID wraparound</em>.</li></ol></div><p>
+
+ Each of these reasons dictates performing <code class="command">VACUUM</code> operations
+ of varying frequency and scope, as explained in the following subsections.
+ </p><p>
+ There are two variants of <code class="command">VACUUM</code>: standard <code class="command">VACUUM</code>
+ and <code class="command">VACUUM FULL</code>. <code class="command">VACUUM FULL</code> can reclaim more
+ disk space but runs much more slowly. Also,
+ the standard form of <code class="command">VACUUM</code> can run in parallel with production
+ database operations. (Commands such as <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> will continue to function normally, though you
+ will not be able to modify the definition of a table with commands such as
+ <code class="command">ALTER TABLE</code> while it is being vacuumed.)
+ <code class="command">VACUUM FULL</code> requires an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the table it is
+ working on, and therefore cannot be done in parallel with other use
+ of the table. Generally, therefore,
+ administrators should strive to use standard <code class="command">VACUUM</code> and
+ avoid <code class="command">VACUUM FULL</code>.
+ </p><p>
+ <code class="command">VACUUM</code> creates a substantial amount of I/O
+ traffic, which can cause poor performance for other active sessions.
+ There are configuration parameters that can be adjusted to reduce the
+ performance impact of background vacuuming — see
+ <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST" title="20.4.4. Cost-based Vacuum Delay">Section 20.4.4</a>.
+ </p></div><div class="sect2" id="VACUUM-FOR-SPACE-RECOVERY"><div class="titlepage"><div><div><h3 class="title">25.1.2. Recovering Disk Space</h3></div></div></div><a id="id-1.6.12.10.5.2" class="indexterm"></a><p>
+ In <span class="productname">PostgreSQL</span>, an
+ <code class="command">UPDATE</code> or <code class="command">DELETE</code> of a row does not
+ immediately remove the old version of the row.
+ This approach is necessary to gain the benefits of multiversion
+ concurrency control (<acronym class="acronym">MVCC</acronym>, see <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>): the row version
+ must not be deleted while it is still potentially visible to other
+ transactions. But eventually, an outdated or deleted row version is no
+ longer of interest to any transaction. The space it occupies must then be
+ reclaimed for reuse by new rows, to avoid unbounded growth of disk
+ space requirements. This is done by running <code class="command">VACUUM</code>.
+ </p><p>
+ The standard form of <code class="command">VACUUM</code> removes dead row
+ versions in tables and indexes and marks the space available for
+ future reuse. However, it will not return the space to the operating
+ system, except in the special case where one or more pages at the
+ end of a table become entirely free and an exclusive table lock can be
+ easily obtained. In contrast, <code class="command">VACUUM FULL</code> actively compacts
+ tables by writing a complete new version of the table file with no dead
+ space. This minimizes the size of the table, but can take a long time.
+ It also requires extra disk space for the new copy of the table, until
+ the operation completes.
+ </p><p>
+ The usual goal of routine vacuuming is to do standard <code class="command">VACUUM</code>s
+ often enough to avoid needing <code class="command">VACUUM FULL</code>. The
+ autovacuum daemon attempts to work this way, and in fact will
+ never issue <code class="command">VACUUM FULL</code>. In this approach, the idea
+ is not to keep tables at their minimum size, but to maintain steady-state
+ usage of disk space: each table occupies space equivalent to its
+ minimum size plus however much space gets used up between vacuum runs.
+ Although <code class="command">VACUUM FULL</code> can be used to shrink a table back
+ to its minimum size and return the disk space to the operating system,
+ there is not much point in this if the table will just grow again in the
+ future. Thus, moderately-frequent standard <code class="command">VACUUM</code> runs are a
+ better approach than infrequent <code class="command">VACUUM FULL</code> runs for
+ maintaining heavily-updated tables.
+ </p><p>
+ Some administrators prefer to schedule vacuuming themselves, for example
+ doing all the work at night when load is low.
+ The difficulty with doing vacuuming according to a fixed schedule
+ is that if a table has an unexpected spike in update activity, it may
+ get bloated to the point that <code class="command">VACUUM FULL</code> is really necessary
+ to reclaim space. Using the autovacuum daemon alleviates this problem,
+ since the daemon schedules vacuuming dynamically in response to update
+ activity. It is unwise to disable the daemon completely unless you
+ have an extremely predictable workload. One possible compromise is
+ to set the daemon's parameters so that it will only react to unusually
+ heavy update activity, thus keeping things from getting out of hand,
+ while scheduled <code class="command">VACUUM</code>s are expected to do the bulk of the
+ work when the load is typical.
+ </p><p>
+ For those not using autovacuum, a typical approach is to schedule a
+ database-wide <code class="command">VACUUM</code> once a day during a low-usage period,
+ supplemented by more frequent vacuuming of heavily-updated tables as
+ necessary. (Some installations with extremely high update rates vacuum
+ their busiest tables as often as once every few minutes.) If you have
+ multiple databases in a cluster, don't forget to
+ <code class="command">VACUUM</code> each one; the program <a class="xref" href="app-vacuumdb.html" title="vacuumdb"><span class="refentrytitle"><span class="application">vacuumdb</span></span></a> might be helpful.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Plain <code class="command">VACUUM</code> may not be satisfactory when
+ a table contains large numbers of dead row versions as a result of
+ massive update or delete activity. If you have such a table and
+ you need to reclaim the excess disk space it occupies, you will need
+ to use <code class="command">VACUUM FULL</code>, or alternatively
+ <a class="link" href="sql-cluster.html" title="CLUSTER"><code class="command">CLUSTER</code></a>
+ or one of the table-rewriting variants of
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>.
+ These commands rewrite an entire new copy of the table and build
+ new indexes for it. All these options require an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock. Note that
+ they also temporarily use extra disk space approximately equal to the size
+ of the table, since the old copies of the table and indexes can't be
+ released until the new ones are complete.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ If you have a table whose entire contents are deleted on a periodic
+ basis, consider doing it with
+ <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a> rather
+ than using <code class="command">DELETE</code> followed by
+ <code class="command">VACUUM</code>. <code class="command">TRUNCATE</code> removes the
+ entire content of the table immediately, without requiring a
+ subsequent <code class="command">VACUUM</code> or <code class="command">VACUUM
+ FULL</code> to reclaim the now-unused disk space.
+ The disadvantage is that strict MVCC semantics are violated.
+ </p></div></div><div class="sect2" id="VACUUM-FOR-STATISTICS"><div class="titlepage"><div><div><h3 class="title">25.1.3. Updating Planner Statistics</h3></div></div></div><a id="id-1.6.12.10.6.2" class="indexterm"></a><a id="id-1.6.12.10.6.3" class="indexterm"></a><p>
+ The <span class="productname">PostgreSQL</span> query planner relies on
+ statistical information about the contents of tables in order to
+ generate good plans for queries. These statistics are gathered by
+ the <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> command,
+ which can be invoked by itself or
+ as an optional step in <code class="command">VACUUM</code>. It is important to have
+ reasonably accurate statistics, otherwise poor choices of plans might
+ degrade database performance.
+ </p><p>
+ The autovacuum daemon, if enabled, will automatically issue
+ <code class="command">ANALYZE</code> commands whenever the content of a table has
+ changed sufficiently. However, administrators might prefer to rely
+ on manually-scheduled <code class="command">ANALYZE</code> operations, particularly
+ if it is known that update activity on a table will not affect the
+ statistics of <span class="quote">“<span class="quote">interesting</span>”</span> columns. The daemon schedules
+ <code class="command">ANALYZE</code> strictly as a function of the number of rows
+ inserted or updated; it has no knowledge of whether that will lead
+ to meaningful statistical changes.
+ </p><p>
+ Tuples changed in partitions and inheritance children do not trigger
+ analyze on the parent table. If the parent table is empty or rarely
+ changed, it may never be processed by autovacuum, and the statistics for
+ the inheritance tree as a whole won't be collected. It is necessary to
+ run <code class="command">ANALYZE</code> on the parent table manually in order to
+ keep the statistics up to date.
+ </p><p>
+ As with vacuuming for space recovery, frequent updates of statistics
+ are more useful for heavily-updated tables than for seldom-updated
+ ones. But even for a heavily-updated table, there might be no need for
+ statistics updates if the statistical distribution of the data is
+ not changing much. A simple rule of thumb is to think about how much
+ the minimum and maximum values of the columns in the table change.
+ For example, a <code class="type">timestamp</code> column that contains the time
+ of row update will have a constantly-increasing maximum value as
+ rows are added and updated; such a column will probably need more
+ frequent statistics updates than, say, a column containing URLs for
+ pages accessed on a website. The URL column might receive changes just
+ as often, but the statistical distribution of its values probably
+ changes relatively slowly.
+ </p><p>
+ It is possible to run <code class="command">ANALYZE</code> on specific tables and even
+ just specific columns of a table, so the flexibility exists to update some
+ statistics more frequently than others if your application requires it.
+ In practice, however, it is usually best to just analyze the entire
+ database, because it is a fast operation. <code class="command">ANALYZE</code> uses a
+ statistically random sampling of the rows of a table rather than reading
+ every single row.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Although per-column tweaking of <code class="command">ANALYZE</code> frequency might not be
+ very productive, you might find it worthwhile to do per-column
+ adjustment of the level of detail of the statistics collected by
+ <code class="command">ANALYZE</code>. Columns that are heavily used in <code class="literal">WHERE</code>
+ clauses and have highly irregular data distributions might require a
+ finer-grain data histogram than other columns. See <code class="command">ALTER TABLE
+ SET STATISTICS</code>, or change the database-wide default using the <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> configuration parameter.
+ </p><p>
+ Also, by default there is limited information available about
+ the selectivity of functions. However, if you create a statistics
+ object or an expression
+ index that uses a function call, useful statistics will be
+ gathered about the function, which can greatly improve query
+ plans that use the expression index.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ The autovacuum daemon does not issue <code class="command">ANALYZE</code> commands for
+ foreign tables, since it has no means of determining how often that
+ might be useful. If your queries require statistics on foreign tables
+ for proper planning, it's a good idea to run manually-managed
+ <code class="command">ANALYZE</code> commands on those tables on a suitable schedule.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ The autovacuum daemon does not issue <code class="command">ANALYZE</code> commands
+ for partitioned tables. Inheritance parents will only be analyzed if the
+ parent itself is changed - changes to child tables do not trigger
+ autoanalyze on the parent table. If your queries require statistics on
+ parent tables for proper planning, it is necessary to periodically run
+ a manual <code class="command">ANALYZE</code> on those tables to keep the statistics
+ up to date.
+ </p></div></div><div class="sect2" id="VACUUM-FOR-VISIBILITY-MAP"><div class="titlepage"><div><div><h3 class="title">25.1.4. Updating the Visibility Map</h3></div></div></div><p>
+ Vacuum maintains a <a class="link" href="storage-vm.html" title="73.4. Visibility Map">visibility map</a> for each
+ table to keep track of which pages contain only tuples that are known to be
+ visible to all active transactions (and all future transactions, until the
+ page is again modified). This has two purposes. First, vacuum
+ itself can skip such pages on the next run, since there is nothing to
+ clean up.
+ </p><p>
+ Second, it allows <span class="productname">PostgreSQL</span> to answer some
+ queries using only the index, without reference to the underlying table.
+ Since <span class="productname">PostgreSQL</span> indexes don't contain tuple
+ visibility information, a normal index scan fetches the heap tuple for each
+ matching index entry, to check whether it should be seen by the current
+ transaction.
+ An <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes"><em class="firstterm">index-only
+ scan</em></a>, on the other hand, checks the visibility map first.
+ If it's known that all tuples on the page are
+ visible, the heap fetch can be skipped. This is most useful on
+ large data sets where the visibility map can prevent disk accesses.
+ The visibility map is vastly smaller than the heap, so it can easily be
+ cached even when the heap is very large.
+ </p></div><div class="sect2" id="VACUUM-FOR-WRAPAROUND"><div class="titlepage"><div><div><h3 class="title">25.1.5. Preventing Transaction ID Wraparound Failures</h3></div></div></div><a id="id-1.6.12.10.8.2" class="indexterm"></a><a id="id-1.6.12.10.8.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span>'s
+ <a class="link" href="mvcc-intro.html" title="13.1. Introduction">MVCC</a> transaction semantics
+ depend on being able to compare transaction ID (<acronym class="acronym">XID</acronym>)
+ numbers: a row version with an insertion XID greater than the current
+ transaction's XID is <span class="quote">“<span class="quote">in the future</span>”</span> and should not be visible
+ to the current transaction. But since transaction IDs have limited size
+ (32 bits) a cluster that runs for a long time (more
+ than 4 billion transactions) would suffer <em class="firstterm">transaction ID
+ wraparound</em>: the XID counter wraps around to zero, and all of a sudden
+ transactions that were in the past appear to be in the future — which
+ means their output become invisible. In short, catastrophic data loss.
+ (Actually the data is still there, but that's cold comfort if you cannot
+ get at it.) To avoid this, it is necessary to vacuum every table
+ in every database at least once every two billion transactions.
+ </p><p>
+ The reason that periodic vacuuming solves the problem is that
+ <code class="command">VACUUM</code> will mark rows as <span class="emphasis"><em>frozen</em></span>, indicating that
+ they were inserted by a transaction that committed sufficiently far in
+ the past that the effects of the inserting transaction are certain to be
+ visible to all current and future transactions.
+ Normal XIDs are
+ compared using modulo-2<sup>32</sup> arithmetic. This means
+ that for every normal XID, there are two billion XIDs that are
+ <span class="quote">“<span class="quote">older</span>”</span> and two billion that are <span class="quote">“<span class="quote">newer</span>”</span>; another
+ way to say it is that the normal XID space is circular with no
+ endpoint. Therefore, once a row version has been created with a particular
+ normal XID, the row version will appear to be <span class="quote">“<span class="quote">in the past</span>”</span> for
+ the next two billion transactions, no matter which normal XID we are
+ talking about. If the row version still exists after more than two billion
+ transactions, it will suddenly appear to be in the future. To
+ prevent this, <span class="productname">PostgreSQL</span> reserves a special XID,
+ <code class="literal">FrozenTransactionId</code>, which does not follow the normal XID
+ comparison rules and is always considered older
+ than every normal XID.
+ Frozen row versions are treated as if the inserting XID were
+ <code class="literal">FrozenTransactionId</code>, so that they will appear to be
+ <span class="quote">“<span class="quote">in the past</span>”</span> to all normal transactions regardless of wraparound
+ issues, and so such row versions will be valid until deleted, no matter
+ how long that is.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In <span class="productname">PostgreSQL</span> versions before 9.4, freezing was
+ implemented by actually replacing a row's insertion XID
+ with <code class="literal">FrozenTransactionId</code>, which was visible in the
+ row's <code class="structname">xmin</code> system column. Newer versions just set a flag
+ bit, preserving the row's original <code class="structname">xmin</code> for possible
+ forensic use. However, rows with <code class="structname">xmin</code> equal
+ to <code class="literal">FrozenTransactionId</code> (2) may still be found
+ in databases <span class="application">pg_upgrade</span>'d from pre-9.4 versions.
+ </p><p>
+ Also, system catalogs may contain rows with <code class="structname">xmin</code> equal
+ to <code class="literal">BootstrapTransactionId</code> (1), indicating that they were
+ inserted during the first phase of <span class="application">initdb</span>.
+ Like <code class="literal">FrozenTransactionId</code>, this special XID is treated as
+ older than every normal XID.
+ </p></div><p>
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-MIN-AGE">vacuum_freeze_min_age</a>
+ controls how old an XID value has to be before rows bearing that XID will be
+ frozen. Increasing this setting may avoid unnecessary work if the
+ rows that would otherwise be frozen will soon be modified again,
+ but decreasing this setting increases
+ the number of transactions that can elapse before the table must be
+ vacuumed again.
+ </p><p>
+ <code class="command">VACUUM</code> uses the <a class="link" href="storage-vm.html" title="73.4. Visibility Map">visibility map</a>
+ to determine which pages of a table must be scanned. Normally, it
+ will skip pages that don't have any dead row versions even if those pages
+ might still have row versions with old XID values. Therefore, normal
+ <code class="command">VACUUM</code>s won't always freeze every old row version in the table.
+ When that happens, <code class="command">VACUUM</code> will eventually need to perform an
+ <em class="firstterm">aggressive vacuum</em>, which will freeze all eligible unfrozen
+ XID and MXID values, including those from all-visible but not all-frozen pages.
+ In practice most tables require periodic aggressive vacuuming.
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-TABLE-AGE">vacuum_freeze_table_age</a>
+ controls when <code class="command">VACUUM</code> does that: all-visible but not all-frozen
+ pages are scanned if the number of transactions that have passed since the
+ last such scan is greater than <code class="varname">vacuum_freeze_table_age</code> minus
+ <code class="varname">vacuum_freeze_min_age</code>. Setting
+ <code class="varname">vacuum_freeze_table_age</code> to 0 forces <code class="command">VACUUM</code> to
+ always use its aggressive strategy.
+ </p><p>
+ The maximum time that a table can go unvacuumed is two billion
+ transactions minus the <code class="varname">vacuum_freeze_min_age</code> value at
+ the time of the last aggressive vacuum. If it were to go
+ unvacuumed for longer than
+ that, data loss could result. To ensure that this does not happen,
+ autovacuum is invoked on any table that might contain unfrozen rows with
+ XIDs older than the age specified by the configuration parameter <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a>. (This will happen even if
+ autovacuum is disabled.)
+ </p><p>
+ This implies that if a table is not otherwise vacuumed,
+ autovacuum will be invoked on it approximately once every
+ <code class="varname">autovacuum_freeze_max_age</code> minus
+ <code class="varname">vacuum_freeze_min_age</code> transactions.
+ For tables that are regularly vacuumed for space reclamation purposes,
+ this is of little importance. However, for static tables
+ (including tables that receive inserts, but no updates or deletes),
+ there is no need to vacuum for space reclamation, so it can
+ be useful to try to maximize the interval between forced autovacuums
+ on very large static tables. Obviously one can do this either by
+ increasing <code class="varname">autovacuum_freeze_max_age</code> or decreasing
+ <code class="varname">vacuum_freeze_min_age</code>.
+ </p><p>
+ The effective maximum for <code class="varname">vacuum_freeze_table_age</code> is 0.95 *
+ <code class="varname">autovacuum_freeze_max_age</code>; a setting higher than that will be
+ capped to the maximum. A value higher than
+ <code class="varname">autovacuum_freeze_max_age</code> wouldn't make sense because an
+ anti-wraparound autovacuum would be triggered at that point anyway, and
+ the 0.95 multiplier leaves some breathing room to run a manual
+ <code class="command">VACUUM</code> before that happens. As a rule of thumb,
+ <code class="command">vacuum_freeze_table_age</code> should be set to a value somewhat
+ below <code class="varname">autovacuum_freeze_max_age</code>, leaving enough gap so that
+ a regularly scheduled <code class="command">VACUUM</code> or an autovacuum triggered by
+ normal delete and update activity is run in that window. Setting it too
+ close could lead to anti-wraparound autovacuums, even though the table
+ was recently vacuumed to reclaim space, whereas lower values lead to more
+ frequent aggressive vacuuming.
+ </p><p>
+ The sole disadvantage of increasing <code class="varname">autovacuum_freeze_max_age</code>
+ (and <code class="varname">vacuum_freeze_table_age</code> along with it) is that
+ the <code class="filename">pg_xact</code> and <code class="filename">pg_commit_ts</code>
+ subdirectories of the database cluster will take more space, because it
+ must store the commit status and (if <code class="varname">track_commit_timestamp</code> is
+ enabled) timestamp of all transactions back to
+ the <code class="varname">autovacuum_freeze_max_age</code> horizon. The commit status uses
+ two bits per transaction, so if
+ <code class="varname">autovacuum_freeze_max_age</code> is set to its maximum allowed value
+ of two billion, <code class="filename">pg_xact</code> can be expected to grow to about half
+ a gigabyte and <code class="filename">pg_commit_ts</code> to about 20GB. If this
+ is trivial compared to your total database size,
+ setting <code class="varname">autovacuum_freeze_max_age</code> to its maximum allowed value
+ is recommended. Otherwise, set it depending on what you are willing to
+ allow for <code class="filename">pg_xact</code> and <code class="filename">pg_commit_ts</code> storage.
+ (The default, 200 million transactions, translates to about 50MB
+ of <code class="filename">pg_xact</code> storage and about 2GB of <code class="filename">pg_commit_ts</code>
+ storage.)
+ </p><p>
+ One disadvantage of decreasing <code class="varname">vacuum_freeze_min_age</code> is that
+ it might cause <code class="command">VACUUM</code> to do useless work: freezing a row
+ version is a waste of time if the row is modified
+ soon thereafter (causing it to acquire a new XID). So the setting should
+ be large enough that rows are not frozen until they are unlikely to change
+ any more.
+ </p><p>
+ To track the age of the oldest unfrozen XIDs in a database,
+ <code class="command">VACUUM</code> stores XID
+ statistics in the system tables <code class="structname">pg_class</code> and
+ <code class="structname">pg_database</code>. In particular,
+ the <code class="structfield">relfrozenxid</code> column of a table's
+ <code class="structname">pg_class</code> row contains the oldest remaining unfrozen
+ XID at the end of the most recent <code class="command">VACUUM</code> that successfully
+ advanced <code class="structfield">relfrozenxid</code> (typically the most recent
+ aggressive VACUUM). Similarly, the
+ <code class="structfield">datfrozenxid</code> column of a database's
+ <code class="structname">pg_database</code> row is a lower bound on the unfrozen XIDs
+ appearing in that database — it is just the minimum of the
+ per-table <code class="structfield">relfrozenxid</code> values within the database.
+ A convenient way to
+ examine this information is to execute queries such as:
+
+</p><pre class="programlisting">
+SELECT c.oid::regclass as table_name,
+ greatest(age(c.relfrozenxid),age(t.relfrozenxid)) as age
+FROM pg_class c
+LEFT JOIN pg_class t ON c.reltoastrelid = t.oid
+WHERE c.relkind IN ('r', 'm');
+
+SELECT datname, age(datfrozenxid) FROM pg_database;
+</pre><p>
+
+ The <code class="literal">age</code> column measures the number of transactions from the
+ cutoff XID to the current transaction's XID.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ When the <code class="command">VACUUM</code> command's <code class="literal">VERBOSE</code>
+ parameter is specified, <code class="command">VACUUM</code> prints various
+ statistics about the table. This includes information about how
+ <code class="structfield">relfrozenxid</code> and
+ <code class="structfield">relminmxid</code> advanced. The same details appear
+ in the server log when autovacuum logging (controlled by <a class="xref" href="runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION">log_autovacuum_min_duration</a>) reports on a
+ <code class="command">VACUUM</code> operation executed by autovacuum.
+ </p></div><p>
+ <code class="command">VACUUM</code> normally only scans pages that have been modified
+ since the last vacuum, but <code class="structfield">relfrozenxid</code> can only be
+ advanced when every page of the table
+ that might contain unfrozen XIDs is scanned. This happens when
+ <code class="structfield">relfrozenxid</code> is more than
+ <code class="varname">vacuum_freeze_table_age</code> transactions old, when
+ <code class="command">VACUUM</code>'s <code class="literal">FREEZE</code> option is used, or when all
+ pages that are not already all-frozen happen to
+ require vacuuming to remove dead row versions. When <code class="command">VACUUM</code>
+ scans every page in the table that is not already all-frozen, it should
+ set <code class="literal">age(relfrozenxid)</code> to a value just a little more than the
+ <code class="varname">vacuum_freeze_min_age</code> setting
+ that was used (more by the number of transactions started since the
+ <code class="command">VACUUM</code> started). <code class="command">VACUUM</code>
+ will set <code class="structfield">relfrozenxid</code> to the oldest XID
+ that remains in the table, so it's possible that the final value
+ will be much more recent than strictly required.
+ If no <code class="structfield">relfrozenxid</code>-advancing
+ <code class="command">VACUUM</code> is issued on the table until
+ <code class="varname">autovacuum_freeze_max_age</code> is reached, an autovacuum will soon
+ be forced for the table.
+ </p><p>
+ If for some reason autovacuum fails to clear old XIDs from a table, the
+ system will begin to emit warning messages like this when the database's
+ oldest XIDs reach forty million transactions from the wraparound point:
+
+</p><pre class="programlisting">
+WARNING: database "mydb" must be vacuumed within 39985967 transactions
+HINT: To avoid a database shutdown, execute a database-wide VACUUM in that database.
+</pre><p>
+
+ (A manual <code class="command">VACUUM</code> should fix the problem, as suggested by the
+ hint; but note that the <code class="command">VACUUM</code> should be performed by a
+ superuser, else it will fail to process system catalogs, which prevent it from
+ being able to advance the database's <code class="structfield">datfrozenxid</code>.)
+ If these warnings are ignored, the system will refuse to assign new XIDs once
+ there are fewer than three million transactions left until wraparound:
+
+</p><pre class="programlisting">
+ERROR: database is not accepting commands to avoid wraparound data loss in database "mydb"
+HINT: Stop the postmaster and vacuum that database in single-user mode.
+</pre><p>
+
+ In this condition any transactions already in progress can continue,
+ but only read-only transactions can be started. Operations that
+ modify database records or truncate relations will fail.
+ The <code class="command">VACUUM</code> command can still be run normally.
+ Contrary to what the hint states, it is not necessary or desirable to stop the
+ postmaster or enter single user-mode in order to restore normal operation.
+ Instead, follow these steps:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Resolve old prepared transactions. You can find these by checking
+ <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts">pg_prepared_xacts</a> for rows where
+ <code class="literal">age(transactionid)</code> is large. Such transactions should be
+ committed or rolled back.</li><li class="listitem">End long-running open transactions. You can find these by checking
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">pg_stat_activity</a> for rows where
+ <code class="literal">age(backend_xid)</code> or <code class="literal">age(backend_xmin)</code> is
+ large. Such transactions should be committed or rolled back, or the session
+ can be terminated using <code class="literal">pg_terminate_backend</code>.</li><li class="listitem">Drop any old replication slots. Use
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication">pg_stat_replication</a> to
+ find slots where <code class="literal">age(xmin)</code> or <code class="literal">age(catalog_xmin)</code>
+ is large. In many cases, such slots were created for replication to servers that no
+ longer exist, or that have been down for a long time. If you drop a slot for a server
+ that still exists and might still try to connect to that slot, that replica may
+ need to be rebuilt.</li><li class="listitem">Execute <code class="command">VACUUM</code> in the target database. A database-wide
+ <code class="literal">VACUUM</code> is simplest; to reduce the time required, it as also possible
+ to issue manual <code class="command">VACUUM</code> commands on the tables where
+ <code class="structfield">relminxid</code> is oldest. Do not use <code class="literal">VACUUM FULL</code>
+ in this scenario, because it requires an XID and will therefore fail, except in super-user
+ mode, where it will instead consume an XID and thus increase the risk of transaction ID
+ wraparound. Do not use <code class="literal">VACUUM FREEZE</code> either, because it will do
+ more than the minimum amount of work required to restore normal operation.</li><li class="listitem">Once normal operation is restored, ensure that autovacuum is properly configured
+ in the target database in order to avoid future problems.</li></ol></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In earlier versions, it was sometimes necessary to stop the postmaster and
+ <code class="command">VACUUM</code> the database in a single-user mode. In typical scenarios, this
+ is no longer necessary, and should be avoided whenever possible, since it involves taking
+ the system down. It is also riskier, since it disables transaction ID wraparound safeguards
+ that are designed to prevent data loss. The only reason to use single-user mode in this
+ scenario is if you wish to <code class="command">TRUNCATE</code> or <code class="command">DROP</code> unneeded
+ tables to avoid needing to <code class="command">VACUUM</code> them. The three-million-transaction
+ safety margin exists to let the administrator do this. See the
+ <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference page for details about using single-user mode.
+ </p></div><div class="sect3" id="VACUUM-FOR-MULTIXACT-WRAPAROUND"><div class="titlepage"><div><div><h4 class="title">25.1.5.1. Multixacts and Wraparound</h4></div></div></div><a id="id-1.6.12.10.8.19.2" class="indexterm"></a><a id="id-1.6.12.10.8.19.3" class="indexterm"></a><p>
+ <em class="firstterm">Multixact IDs</em> are used to support row locking by
+ multiple transactions. Since there is only limited space in a tuple
+ header to store lock information, that information is encoded as
+ a <span class="quote">“<span class="quote">multiple transaction ID</span>”</span>, or multixact ID for short,
+ whenever there is more than one transaction concurrently locking a
+ row. Information about which transaction IDs are included in any
+ particular multixact ID is stored separately in
+ the <code class="filename">pg_multixact</code> subdirectory, and only the multixact ID
+ appears in the <code class="structfield">xmax</code> field in the tuple header.
+ Like transaction IDs, multixact IDs are implemented as a
+ 32-bit counter and corresponding storage, all of which requires
+ careful aging management, storage cleanup, and wraparound handling.
+ There is a separate storage area which holds the list of members in
+ each multixact, which also uses a 32-bit counter and which must also
+ be managed.
+ </p><p>
+ Whenever <code class="command">VACUUM</code> scans any part of a table, it will replace
+ any multixact ID it encounters which is older than
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-MULTIXACT-FREEZE-MIN-AGE">vacuum_multixact_freeze_min_age</a>
+ by a different value, which can be the zero value, a single
+ transaction ID, or a newer multixact ID. For each table,
+ <code class="structname">pg_class</code>.<code class="structfield">relminmxid</code> stores the oldest
+ possible multixact ID still appearing in any tuple of that table.
+ If this value is older than
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-MULTIXACT-FREEZE-TABLE-AGE">vacuum_multixact_freeze_table_age</a>, an aggressive
+ vacuum is forced. As discussed in the previous section, an aggressive
+ vacuum means that only those pages which are known to be all-frozen will
+ be skipped. <code class="function">mxid_age()</code> can be used on
+ <code class="structname">pg_class</code>.<code class="structfield">relminmxid</code> to find its age.
+ </p><p>
+ Aggressive <code class="command">VACUUM</code>s, regardless of what causes
+ them, are <span class="emphasis"><em>guaranteed</em></span> to be able to advance
+ the table's <code class="structfield">relminmxid</code>.
+ Eventually, as all tables in all databases are scanned and their
+ oldest multixact values are advanced, on-disk storage for older
+ multixacts can be removed.
+ </p><p>
+ As a safety device, an aggressive vacuum scan will
+ occur for any table whose multixact-age is greater than <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a>. Also, if the
+ storage occupied by multixacts members exceeds 2GB, aggressive vacuum
+ scans will occur more often for all tables, starting with those that
+ have the oldest multixact-age. Both of these kinds of aggressive
+ scans will occur even if autovacuum is nominally disabled.
+ </p><p>
+ Similar to the XID case, if autovacuum fails to clear old MXIDs from a table, the
+ system will begin to emit warning messages when the database's oldest MXIDs reach forty
+ million transactions from the wraparound point. And, just as an the XID case, if these
+ warnings are ignored, the system will refuse to generate new MXIDs once there are fewer
+ than three million left until wraparound.
+ </p><p>
+ Normal operation when MXIDs are exhausted can be restored in much the same way as
+ when XIDs are exhausted. Follow the same steps in the previous section, but with the
+ following differences:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Running transactions and prepared transactions can be ignored if there
+ is no chance that they might appear in a multixact.</li><li class="listitem">MXID information is not directly visible in system views such as
+ <code class="literal">pg_stat_activity</code>; however, looking for old XIDs is still a good
+ way of determining which transactions are causing MXID wraparound problems.</li><li class="listitem">XID exhaustion will block all write transactions, but MXID exhaustion will
+ only block a subset of write transactions, specifically those that involve
+ row locks that require an MXID.</li></ol></div><p>
+ </p></div></div><div class="sect2" id="AUTOVACUUM"><div class="titlepage"><div><div><h3 class="title">25.1.6. The Autovacuum Daemon</h3></div></div></div><a id="id-1.6.12.10.9.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> has an optional but highly
+ recommended feature called <em class="firstterm">autovacuum</em>,
+ whose purpose is to automate the execution of
+ <code class="command">VACUUM</code> and <code class="command">ANALYZE</code> commands.
+ When enabled, autovacuum checks for
+ tables that have had a large number of inserted, updated or deleted
+ tuples. These checks use the statistics collection facility;
+ therefore, autovacuum cannot be used unless <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-COUNTS">track_counts</a> is set to <code class="literal">true</code>.
+ In the default configuration, autovacuuming is enabled and the related
+ configuration parameters are appropriately set.
+ </p><p>
+ The <span class="quote">“<span class="quote">autovacuum daemon</span>”</span> actually consists of multiple processes.
+ There is a persistent daemon process, called the
+ <em class="firstterm">autovacuum launcher</em>, which is in charge of starting
+ <em class="firstterm">autovacuum worker</em> processes for all databases. The
+ launcher will distribute the work across time, attempting to start one
+ worker within each database every <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-NAPTIME">autovacuum_naptime</a>
+ seconds. (Therefore, if the installation has <em class="replaceable"><code>N</code></em> databases,
+ a new worker will be launched every
+ <code class="varname">autovacuum_naptime</code>/<em class="replaceable"><code>N</code></em> seconds.)
+ A maximum of <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MAX-WORKERS">autovacuum_max_workers</a> worker processes
+ are allowed to run at the same time. If there are more than
+ <code class="varname">autovacuum_max_workers</code> databases to be processed,
+ the next database will be processed as soon as the first worker finishes.
+ Each worker process will check each table within its database and
+ execute <code class="command">VACUUM</code> and/or <code class="command">ANALYZE</code> as needed.
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION">log_autovacuum_min_duration</a> can be set to monitor
+ autovacuum workers' activity.
+ </p><p>
+ If several large tables all become eligible for vacuuming in a short
+ amount of time, all autovacuum workers might become occupied with
+ vacuuming those tables for a long period. This would result
+ in other tables and databases not being vacuumed until a worker becomes
+ available. There is no limit on how many workers might be in a
+ single database, but workers do try to avoid repeating work that has
+ already been done by other workers. Note that the number of running
+ workers does not count towards <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> or
+ <a class="xref" href="runtime-config-connection.html#GUC-SUPERUSER-RESERVED-CONNECTIONS">superuser_reserved_connections</a> limits.
+ </p><p>
+ Tables whose <code class="structfield">relfrozenxid</code> value is more than
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a> transactions old are always
+ vacuumed (this also applies to those tables whose freeze max age has
+ been modified via storage parameters; see below). Otherwise, if the
+ number of tuples obsoleted since the last
+ <code class="command">VACUUM</code> exceeds the <span class="quote">“<span class="quote">vacuum threshold</span>”</span>, the
+ table is vacuumed. The vacuum threshold is defined as:
+</p><pre class="programlisting">
+vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuples
+</pre><p>
+ where the vacuum base threshold is
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-THRESHOLD">autovacuum_vacuum_threshold</a>,
+ the vacuum scale factor is
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-SCALE-FACTOR">autovacuum_vacuum_scale_factor</a>,
+ and the number of tuples is
+ <code class="structname">pg_class</code>.<code class="structfield">reltuples</code>.
+ </p><p>
+ The table is also vacuumed if the number of tuples inserted since the last
+ vacuum has exceeded the defined insert threshold, which is defined as:
+</p><pre class="programlisting">
+vacuum insert threshold = vacuum base insert threshold + vacuum insert scale factor * number of tuples
+</pre><p>
+ where the vacuum insert base threshold is
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-INSERT-THRESHOLD">autovacuum_vacuum_insert_threshold</a>,
+ and vacuum insert scale factor is
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-INSERT-SCALE-FACTOR">autovacuum_vacuum_insert_scale_factor</a>.
+ Such vacuums may allow portions of the table to be marked as
+ <em class="firstterm">all visible</em> and also allow tuples to be frozen, which
+ can reduce the work required in subsequent vacuums.
+ For tables which receive <code class="command">INSERT</code> operations but no or
+ almost no <code class="command">UPDATE</code>/<code class="command">DELETE</code> operations,
+ it may be beneficial to lower the table's
+ <a class="xref" href="sql-createtable.html#RELOPTION-AUTOVACUUM-FREEZE-MIN-AGE">autovacuum_freeze_min_age</a> as this may allow
+ tuples to be frozen by earlier vacuums. The number of obsolete tuples and
+ the number of inserted tuples are obtained from the cumulative statistics system;
+ it is a semi-accurate count updated by each <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code> and <code class="command">INSERT</code> operation. (It is
+ only semi-accurate because some information might be lost under heavy
+ load.) If the <code class="structfield">relfrozenxid</code> value of the table
+ is more than <code class="varname">vacuum_freeze_table_age</code> transactions old,
+ an aggressive vacuum is performed to freeze old tuples and advance
+ <code class="structfield">relfrozenxid</code>; otherwise, only pages that have been modified
+ since the last vacuum are scanned.
+ </p><p>
+ For analyze, a similar condition is used: the threshold, defined as:
+</p><pre class="programlisting">
+analyze threshold = analyze base threshold + analyze scale factor * number of tuples
+</pre><p>
+ is compared to the total number of tuples inserted, updated, or deleted
+ since the last <code class="command">ANALYZE</code>.
+ </p><p>
+ Partitioned tables do not directly store tuples and consequently
+ are not processed by autovacuum. (Autovacuum does process table
+ partitions just like other tables.) Unfortunately, this means that
+ autovacuum does not run <code class="command">ANALYZE</code> on partitioned
+ tables, and this can cause suboptimal plans for queries that reference
+ partitioned table statistics. You can work around this problem by
+ manually running <code class="command">ANALYZE</code> on partitioned tables
+ when they are first populated, and again whenever the distribution
+ of data in their partitions changes significantly.
+ </p><p>
+ Temporary tables cannot be accessed by autovacuum. Therefore,
+ appropriate vacuum and analyze operations should be performed via
+ session SQL commands.
+ </p><p>
+ The default thresholds and scale factors are taken from
+ <code class="filename">postgresql.conf</code>, but it is possible to override them
+ (and many other autovacuum control parameters) on a per-table basis; see
+ <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a> for more information.
+ If a setting has been changed via a table's storage parameters, that value
+ is used when processing that table; otherwise the global settings are
+ used. See <a class="xref" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming">Section 20.10</a> for more details on
+ the global settings.
+ </p><p>
+ When multiple workers are running, the autovacuum cost delay parameters
+ (see <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST" title="20.4.4. Cost-based Vacuum Delay">Section 20.4.4</a>) are
+ <span class="quote">“<span class="quote">balanced</span>”</span> among all the running workers, so that the
+ total I/O impact on the system is the same regardless of the number
+ of workers actually running. However, any workers processing tables whose
+ per-table <code class="literal">autovacuum_vacuum_cost_delay</code> or
+ <code class="literal">autovacuum_vacuum_cost_limit</code> storage parameters have been set
+ are not considered in the balancing algorithm.
+ </p><p>
+ Autovacuum workers generally don't block other commands. If a process
+ attempts to acquire a lock that conflicts with the
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock held by autovacuum, lock
+ acquisition will interrupt the autovacuum. For conflicting lock modes,
+ see <a class="xref" href="explicit-locking.html#TABLE-LOCK-COMPATIBILITY" title="Table 13.2. Conflicting Lock Modes">Table 13.2</a>. However, if the autovacuum
+ is running to prevent transaction ID wraparound (i.e., the autovacuum query
+ name in the <code class="structname">pg_stat_activity</code> view ends with
+ <code class="literal">(to prevent wraparound)</code>), the autovacuum is not
+ automatically interrupted.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ Regularly running commands that acquire locks conflicting with a
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock (e.g., ANALYZE) can
+ effectively prevent autovacuums from ever completing.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="routine-reindex.html" title="25.2. Routine Reindexing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 25. Routine Database Maintenance Tasks </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 25.2. Routine Reindexing</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/row-estimation-examples.html b/doc/src/sgml/html/row-estimation-examples.html
new file mode 100644
index 0000000..641970f
--- /dev/null
+++ b/doc/src/sgml/html/row-estimation-examples.html
@@ -0,0 +1,399 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>75.1. Row Estimation Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics" /><link rel="next" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">75.1. Row Estimation Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><th width="60%" align="center">Chapter 75. How the Planner Uses Statistics</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROW-ESTIMATION-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">75.1. Row Estimation Examples</h2></div></div></div><a id="id-1.10.26.4.2" class="indexterm"></a><p>
+ The examples shown below use tables in the <span class="productname">PostgreSQL</span>
+ regression test database.
+ The outputs shown are taken from version 8.3.
+ The behavior of earlier (or later) versions might vary.
+ Note also that since <code class="command">ANALYZE</code> uses random sampling
+ while producing statistics, the results will change slightly after
+ any new <code class="command">ANALYZE</code>.
+ </p><p>
+ Let's start with a very simple query:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1;
+
+ QUERY PLAN
+-------------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..458.00 rows=10000 width=244)
+</pre><p>
+
+ How the planner determines the cardinality of <code class="structname">tenk1</code>
+ is covered in <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>, but is repeated here for
+ completeness. The number of pages and rows is looked up in
+ <code class="structname">pg_class</code>:
+
+</p><pre class="programlisting">
+SELECT relpages, reltuples FROM pg_class WHERE relname = 'tenk1';
+
+ relpages | reltuples
+----------+-----------
+ 358 | 10000
+</pre><p>
+
+ These numbers are current as of the last <code class="command">VACUUM</code> or
+ <code class="command">ANALYZE</code> on the table. The planner then fetches the
+ actual current number of pages in the table (this is a cheap operation,
+ not requiring a table scan). If that is different from
+ <code class="structfield">relpages</code> then
+ <code class="structfield">reltuples</code> is scaled accordingly to
+ arrive at a current number-of-rows estimate. In the example above, the value of
+ <code class="structfield">relpages</code> is up-to-date so the rows estimate is
+ the same as <code class="structfield">reltuples</code>.
+ </p><p>
+ Let's move on to an example with a range condition in its
+ <code class="literal">WHERE</code> clause:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 1000;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------
+ Bitmap Heap Scan on tenk1 (cost=24.06..394.64 rows=1007 width=244)
+ Recheck Cond: (unique1 &lt; 1000)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..23.80 rows=1007 width=0)
+ Index Cond: (unique1 &lt; 1000)
+</pre><p>
+
+ The planner examines the <code class="literal">WHERE</code> clause condition
+ and looks up the selectivity function for the operator
+ <code class="literal">&lt;</code> in <code class="structname">pg_operator</code>.
+ This is held in the column <code class="structfield">oprrest</code>,
+ and the entry in this case is <code class="function">scalarltsel</code>.
+ The <code class="function">scalarltsel</code> function retrieves the histogram for
+ <code class="structfield">unique1</code> from
+ <code class="structname">pg_statistic</code>. For manual queries it is more
+ convenient to look in the simpler <code class="structname">pg_stats</code>
+ view:
+
+</p><pre class="programlisting">
+SELECT histogram_bounds FROM pg_stats
+WHERE tablename='tenk1' AND attname='unique1';
+
+ histogram_bounds
+------------------------------------------------------
+ {0,993,1997,3050,4040,5036,5957,7057,8029,9016,9995}
+</pre><p>
+
+ Next the fraction of the histogram occupied by <span class="quote">“<span class="quote">&lt; 1000</span>”</span>
+ is worked out. This is the selectivity. The histogram divides the range
+ into equal frequency buckets, so all we have to do is locate the bucket
+ that our value is in and count <span class="emphasis"><em>part</em></span> of it and
+ <span class="emphasis"><em>all</em></span> of the ones before. The value 1000 is clearly in
+ the second bucket (993–1997). Assuming a linear distribution of
+ values inside each bucket, we can calculate the selectivity as:
+
+</p><pre class="programlisting">
+selectivity = (1 + (1000 - bucket[2].min)/(bucket[2].max - bucket[2].min))/num_buckets
+ = (1 + (1000 - 993)/(1997 - 993))/10
+ = 0.100697
+</pre><p>
+
+ that is, one whole bucket plus a linear fraction of the second, divided by
+ the number of buckets. The estimated number of rows can now be calculated as
+ the product of the selectivity and the cardinality of
+ <code class="structname">tenk1</code>:
+
+</p><pre class="programlisting">
+rows = rel_cardinality * selectivity
+ = 10000 * 0.100697
+ = 1007 (rounding off)
+</pre><p>
+ </p><p>
+ Next let's consider an example with an equality condition in its
+ <code class="literal">WHERE</code> clause:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 WHERE stringu1 = 'CRAAAA';
+
+ QUERY PLAN
+----------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..483.00 rows=30 width=244)
+ Filter: (stringu1 = 'CRAAAA'::name)
+</pre><p>
+
+ Again the planner examines the <code class="literal">WHERE</code> clause condition
+ and looks up the selectivity function for <code class="literal">=</code>, which is
+ <code class="function">eqsel</code>. For equality estimation the histogram is
+ not useful; instead the list of <em class="firstterm">most
+ common values</em> (<acronym class="acronym">MCV</acronym>s) is used to determine the
+ selectivity. Let's have a look at the MCVs, with some additional columns
+ that will be useful later:
+
+</p><pre class="programlisting">
+SELECT null_frac, n_distinct, most_common_vals, most_common_freqs FROM pg_stats
+WHERE tablename='tenk1' AND attname='stringu1';
+
+null_frac | 0
+n_distinct | 676
+most_common_vals | {EJAAAA,BBAAAA,CRAAAA,FCAAAA,FEAAAA,GSAAAA,​JOAAAA,MCAAAA,NAAAAA,WGAAAA}
+most_common_freqs | {0.00333333,0.003,0.003,0.003,0.003,0.003,​0.003,0.003,0.003,0.003}
+
+</pre><p>
+
+ Since <code class="literal">CRAAAA</code> appears in the list of MCVs, the selectivity is
+ merely the corresponding entry in the list of most common frequencies
+ (<acronym class="acronym">MCF</acronym>s):
+
+</p><pre class="programlisting">
+selectivity = mcf[3]
+ = 0.003
+</pre><p>
+
+ As before, the estimated number of rows is just the product of this with the
+ cardinality of <code class="structname">tenk1</code>:
+
+</p><pre class="programlisting">
+rows = 10000 * 0.003
+ = 30
+</pre><p>
+ </p><p>
+ Now consider the same query, but with a constant that is not in the
+ <acronym class="acronym">MCV</acronym> list:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 WHERE stringu1 = 'xxx';
+
+ QUERY PLAN
+----------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..483.00 rows=15 width=244)
+ Filter: (stringu1 = 'xxx'::name)
+</pre><p>
+
+ This is quite a different problem: how to estimate the selectivity when the
+ value is <span class="emphasis"><em>not</em></span> in the <acronym class="acronym">MCV</acronym> list.
+ The approach is to use the fact that the value is not in the list,
+ combined with the knowledge of the frequencies for all of the
+ <acronym class="acronym">MCV</acronym>s:
+
+</p><pre class="programlisting">
+selectivity = (1 - sum(mvf))/(num_distinct - num_mcv)
+ = (1 - (0.00333333 + 0.003 + 0.003 + 0.003 + 0.003 + 0.003 +
+ 0.003 + 0.003 + 0.003 + 0.003))/(676 - 10)
+ = 0.0014559
+</pre><p>
+
+ That is, add up all the frequencies for the <acronym class="acronym">MCV</acronym>s and
+ subtract them from one, then
+ divide by the number of <span class="emphasis"><em>other</em></span> distinct values.
+ This amounts to assuming that the fraction of the column that is not any
+ of the MCVs is evenly distributed among all the other distinct values.
+ Notice that there are no null values so we don't have to worry about those
+ (otherwise we'd subtract the null fraction from the numerator as well).
+ The estimated number of rows is then calculated as usual:
+
+</p><pre class="programlisting">
+rows = 10000 * 0.0014559
+ = 15 (rounding off)
+</pre><p>
+ </p><p>
+ The previous example with <code class="literal">unique1 &lt; 1000</code> was an
+ oversimplification of what <code class="function">scalarltsel</code> really does;
+ now that we have seen an example of the use of MCVs, we can fill in some
+ more detail. The example was correct as far as it went, because since
+ <code class="structfield">unique1</code> is a unique column it has no MCVs (obviously, no
+ value is any more common than any other value). For a non-unique
+ column, there will normally be both a histogram and an MCV list, and
+ <span class="emphasis"><em>the histogram does not include the portion of the column
+ population represented by the MCVs</em></span>. We do things this way because
+ it allows more precise estimation. In this situation
+ <code class="function">scalarltsel</code> directly applies the condition (e.g.,
+ <span class="quote">“<span class="quote">&lt; 1000</span>”</span>) to each value of the MCV list, and adds up the
+ frequencies of the MCVs for which the condition is true. This gives
+ an exact estimate of the selectivity within the portion of the table
+ that is MCVs. The histogram is then used in the same way as above
+ to estimate the selectivity in the portion of the table that is not
+ MCVs, and then the two numbers are combined to estimate the overall
+ selectivity. For example, consider
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 WHERE stringu1 &lt; 'IAAAAA';
+
+ QUERY PLAN
+------------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..483.00 rows=3077 width=244)
+ Filter: (stringu1 &lt; 'IAAAAA'::name)
+</pre><p>
+
+ We already saw the MCV information for <code class="structfield">stringu1</code>,
+ and here is its histogram:
+
+</p><pre class="programlisting">
+SELECT histogram_bounds FROM pg_stats
+WHERE tablename='tenk1' AND attname='stringu1';
+
+ histogram_bounds
+-------------------------------------------------------------------​-------------
+ {AAAAAA,CQAAAA,FRAAAA,IBAAAA,KRAAAA,NFAAAA,PSAAAA,SGAAAA,VAAAAA,​XLAAAA,ZZAAAA}
+</pre><p>
+
+ Checking the MCV list, we find that the condition <code class="literal">stringu1 &lt;
+ 'IAAAAA'</code> is satisfied by the first six entries and not the last four,
+ so the selectivity within the MCV part of the population is
+
+</p><pre class="programlisting">
+selectivity = sum(relevant mvfs)
+ = 0.00333333 + 0.003 + 0.003 + 0.003 + 0.003 + 0.003
+ = 0.01833333
+</pre><p>
+
+ Summing all the MCFs also tells us that the total fraction of the
+ population represented by MCVs is 0.03033333, and therefore the
+ fraction represented by the histogram is 0.96966667 (again, there
+ are no nulls, else we'd have to exclude them here). We can see
+ that the value <code class="literal">IAAAAA</code> falls nearly at the end of the
+ third histogram bucket. Using some rather cheesy assumptions
+ about the frequency of different characters, the planner arrives
+ at the estimate 0.298387 for the portion of the histogram population
+ that is less than <code class="literal">IAAAAA</code>. We then combine the estimates
+ for the MCV and non-MCV populations:
+
+</p><pre class="programlisting">
+selectivity = mcv_selectivity + histogram_selectivity * histogram_fraction
+ = 0.01833333 + 0.298387 * 0.96966667
+ = 0.307669
+
+rows = 10000 * 0.307669
+ = 3077 (rounding off)
+</pre><p>
+
+ In this particular example, the correction from the MCV list is fairly
+ small, because the column distribution is actually quite flat (the
+ statistics showing these particular values as being more common than
+ others are mostly due to sampling error). In a more typical case where
+ some values are significantly more common than others, this complicated
+ process gives a useful improvement in accuracy because the selectivity
+ for the most common values is found exactly.
+ </p><p>
+ Now let's consider a case with more than one
+ condition in the <code class="literal">WHERE</code> clause:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 1000 AND stringu1 = 'xxx';
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------
+ Bitmap Heap Scan on tenk1 (cost=23.80..396.91 rows=1 width=244)
+ Recheck Cond: (unique1 &lt; 1000)
+ Filter: (stringu1 = 'xxx'::name)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..23.80 rows=1007 width=0)
+ Index Cond: (unique1 &lt; 1000)
+</pre><p>
+
+ The planner assumes that the two conditions are independent, so that
+ the individual selectivities of the clauses can be multiplied together:
+
+</p><pre class="programlisting">
+selectivity = selectivity(unique1 &lt; 1000) * selectivity(stringu1 = 'xxx')
+ = 0.100697 * 0.0014559
+ = 0.0001466
+
+rows = 10000 * 0.0001466
+ = 1 (rounding off)
+</pre><p>
+
+ Notice that the number of rows estimated to be returned from the bitmap
+ index scan reflects only the condition used with the index; this is
+ important since it affects the cost estimate for the subsequent heap
+ fetches.
+ </p><p>
+ Finally we will examine a query that involves a join:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 50 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------
+ Nested Loop (cost=4.64..456.23 rows=50 width=488)
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=4.64..142.17 rows=50 width=244)
+ Recheck Cond: (unique1 &lt; 50)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.63 rows=50 width=0)
+ Index Cond: (unique1 &lt; 50)
+ -&gt; Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.00..6.27 rows=1 width=244)
+ Index Cond: (unique2 = t1.unique2)
+</pre><p>
+
+ The restriction on <code class="structname">tenk1</code>,
+ <code class="literal">unique1 &lt; 50</code>,
+ is evaluated before the nested-loop join.
+ This is handled analogously to the previous range example. This time the
+ value 50 falls into the first bucket of the
+ <code class="structfield">unique1</code> histogram:
+
+</p><pre class="programlisting">
+selectivity = (0 + (50 - bucket[1].min)/(bucket[1].max - bucket[1].min))/num_buckets
+ = (0 + (50 - 0)/(993 - 0))/10
+ = 0.005035
+
+rows = 10000 * 0.005035
+ = 50 (rounding off)
+</pre><p>
+
+ The restriction for the join is <code class="literal">t2.unique2 = t1.unique2</code>.
+ The operator is just
+ our familiar <code class="literal">=</code>, however the selectivity function is
+ obtained from the <code class="structfield">oprjoin</code> column of
+ <code class="structname">pg_operator</code>, and is <code class="function">eqjoinsel</code>.
+ <code class="function">eqjoinsel</code> looks up the statistical information for both
+ <code class="structname">tenk2</code> and <code class="structname">tenk1</code>:
+
+</p><pre class="programlisting">
+SELECT tablename, null_frac,n_distinct, most_common_vals FROM pg_stats
+WHERE tablename IN ('tenk1', 'tenk2') AND attname='unique2';
+
+tablename | null_frac | n_distinct | most_common_vals
+-----------+-----------+------------+------------------
+ tenk1 | 0 | -1 |
+ tenk2 | 0 | -1 |
+</pre><p>
+
+ In this case there is no <acronym class="acronym">MCV</acronym> information for
+ <code class="structfield">unique2</code> because all the values appear to be
+ unique, so we use an algorithm that relies only on the number of
+ distinct values for both relations together with their null fractions:
+
+</p><pre class="programlisting">
+selectivity = (1 - null_frac1) * (1 - null_frac2) * min(1/num_distinct1, 1/num_distinct2)
+ = (1 - 0) * (1 - 0) / max(10000, 10000)
+ = 0.0001
+</pre><p>
+
+ This is, subtract the null fraction from one for each of the relations,
+ and divide by the maximum of the numbers of distinct values.
+ The number of rows
+ that the join is likely to emit is calculated as the cardinality of the
+ Cartesian product of the two inputs, multiplied by the
+ selectivity:
+
+</p><pre class="programlisting">
+rows = (outer_cardinality * inner_cardinality) * selectivity
+ = (50 * 10000) * 0.0001
+ = 50
+</pre><p>
+ </p><p>
+ Had there been MCV lists for the two columns,
+ <code class="function">eqjoinsel</code> would have used direct comparison of the MCV
+ lists to determine the join selectivity within the part of the column
+ populations represented by the MCVs. The estimate for the remainder of the
+ populations follows the same approach shown here.
+ </p><p>
+ Notice that we showed <code class="literal">inner_cardinality</code> as 10000, that is,
+ the unmodified size of <code class="structname">tenk2</code>. It might appear from
+ inspection of the <code class="command">EXPLAIN</code> output that the estimate of
+ join rows comes from 50 * 1, that is, the number of outer rows times
+ the estimated number of rows obtained by each inner index scan on
+ <code class="structname">tenk2</code>. But this is not the case: the join relation size
+ is estimated before any particular join plan has been considered. If
+ everything is working well then the two ways of estimating the join
+ size will produce about the same answer, but due to round-off error and
+ other factors they sometimes diverge significantly.
+ </p><p>
+ For those interested in further details, estimation of the size of
+ a table (before any <code class="literal">WHERE</code> clauses) is done in
+ <code class="filename">src/backend/optimizer/util/plancat.c</code>. The generic
+ logic for clause selectivities is in
+ <code class="filename">src/backend/optimizer/path/clausesel.c</code>. The
+ operator-specific selectivity functions are mostly found
+ in <code class="filename">src/backend/utils/adt/selfuncs.c</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="planner-stats-details.html" title="Chapter 75. How the Planner Uses Statistics">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 75. How the Planner Uses Statistics </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 75.2. Multivariate Statistics Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rowtypes.html b/doc/src/sgml/html/rowtypes.html
new file mode 100644
index 0000000..a904f0f
--- /dev/null
+++ b/doc/src/sgml/html/rowtypes.html
@@ -0,0 +1,424 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.16. Composite Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="arrays.html" title="8.15. Arrays" /><link rel="next" href="rangetypes.html" title="8.17. Range Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.16. Composite Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="arrays.html" title="8.15. Arrays">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rangetypes.html" title="8.17. Range Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="ROWTYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.16. Composite Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-DECLARING">8.16.1. Declaration of Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#id-1.5.7.24.6">8.16.2. Constructing Composite Values</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-ACCESSING">8.16.3. Accessing Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#id-1.5.7.24.8">8.16.4. Modifying Composite Types</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-USAGE">8.16.5. Using Composite Types in Queries</a></span></dt><dt><span class="sect2"><a href="rowtypes.html#ROWTYPES-IO-SYNTAX">8.16.6. Composite Type Input and Output Syntax</a></span></dt></dl></div><a id="id-1.5.7.24.2" class="indexterm"></a><a id="id-1.5.7.24.3" class="indexterm"></a><p>
+ A <em class="firstterm">composite type</em> represents the structure of a row or record;
+ it is essentially just a list of field names and their data types.
+ <span class="productname">PostgreSQL</span> allows composite types to be
+ used in many of the same ways that simple types can be used. For example, a
+ column of a table can be declared to be of a composite type.
+ </p><div class="sect2" id="ROWTYPES-DECLARING"><div class="titlepage"><div><div><h3 class="title">8.16.1. Declaration of Composite Types</h3></div></div></div><p>
+ Here are two simple examples of defining composite types:
+</p><pre class="programlisting">
+CREATE TYPE complex AS (
+ r double precision,
+ i double precision
+);
+
+CREATE TYPE inventory_item AS (
+ name text,
+ supplier_id integer,
+ price numeric
+);
+</pre><p>
+ The syntax is comparable to <code class="command">CREATE TABLE</code>, except that only
+ field names and types can be specified; no constraints (such as <code class="literal">NOT
+ NULL</code>) can presently be included. Note that the <code class="literal">AS</code> keyword
+ is essential; without it, the system will think a different kind
+ of <code class="command">CREATE TYPE</code> command is meant, and you will get odd syntax
+ errors.
+ </p><p>
+ Having defined the types, we can use them to create tables:
+
+</p><pre class="programlisting">
+CREATE TABLE on_hand (
+ item inventory_item,
+ count integer
+);
+
+INSERT INTO on_hand VALUES (ROW('fuzzy dice', 42, 1.99), 1000);
+</pre><p>
+
+ or functions:
+
+</p><pre class="programlisting">
+CREATE FUNCTION price_extension(inventory_item, integer) RETURNS numeric
+AS 'SELECT $1.price * $2' LANGUAGE SQL;
+
+SELECT price_extension(item, 10) FROM on_hand;
+</pre><p>
+
+ </p><p>
+ Whenever you create a table, a composite type is also automatically
+ created, with the same name as the table, to represent the table's
+ row type. For example, had we said:
+</p><pre class="programlisting">
+CREATE TABLE inventory_item (
+ name text,
+ supplier_id integer REFERENCES suppliers,
+ price numeric CHECK (price &gt; 0)
+);
+</pre><p>
+ then the same <code class="literal">inventory_item</code> composite type shown above would
+ come into being as a
+ byproduct, and could be used just as above. Note however an important
+ restriction of the current implementation: since no constraints are
+ associated with a composite type, the constraints shown in the table
+ definition <span class="emphasis"><em>do not apply</em></span> to values of the composite type
+ outside the table. (To work around this, create a
+ <a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN"><em class="glossterm"><a class="glossterm" href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain</a></em></a> over the composite
+ type, and apply the desired constraints as <code class="literal">CHECK</code>
+ constraints of the domain.)
+ </p></div><div class="sect2" id="id-1.5.7.24.6"><div class="titlepage"><div><div><h3 class="title">8.16.2. Constructing Composite Values</h3></div></div></div><a id="id-1.5.7.24.6.2" class="indexterm"></a><p>
+ To write a composite value as a literal constant, enclose the field
+ values within parentheses and separate them by commas. You can put double
+ quotes around any field value, and must do so if it contains commas or
+ parentheses. (More details appear <a class="link" href="rowtypes.html#ROWTYPES-IO-SYNTAX" title="8.16.6. Composite Type Input and Output Syntax">below</a>.) Thus, the general format of
+ a composite constant is the following:
+</p><pre class="synopsis">
+'( <em class="replaceable"><code>val1</code></em> , <em class="replaceable"><code>val2</code></em> , ... )'
+</pre><p>
+ An example is:
+</p><pre class="programlisting">
+'("fuzzy dice",42,1.99)'
+</pre><p>
+ which would be a valid value of the <code class="literal">inventory_item</code> type
+ defined above. To make a field be NULL, write no characters at all
+ in its position in the list. For example, this constant specifies
+ a NULL third field:
+</p><pre class="programlisting">
+'("fuzzy dice",42,)'
+</pre><p>
+ If you want an empty string rather than NULL, write double quotes:
+</p><pre class="programlisting">
+'("",42,)'
+</pre><p>
+ Here the first field is a non-NULL empty string, the third is NULL.
+ </p><p>
+ (These constants are actually only a special case of
+ the generic type constants discussed in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC" title="4.1.2.7. Constants of Other Types">Section 4.1.2.7</a>. The constant is initially
+ treated as a string and passed to the composite-type input conversion
+ routine. An explicit type specification might be necessary to tell
+ which type to convert the constant to.)
+ </p><p>
+ The <code class="literal">ROW</code> expression syntax can also be used to
+ construct composite values. In most cases this is considerably
+ simpler to use than the string-literal syntax since you don't have
+ to worry about multiple layers of quoting. We already used this
+ method above:
+</p><pre class="programlisting">
+ROW('fuzzy dice', 42, 1.99)
+ROW('', 42, NULL)
+</pre><p>
+ The ROW keyword is actually optional as long as you have more than one
+ field in the expression, so these can be simplified to:
+</p><pre class="programlisting">
+('fuzzy dice', 42, 1.99)
+('', 42, NULL)
+</pre><p>
+ The <code class="literal">ROW</code> expression syntax is discussed in more detail in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">Section 4.2.13</a>.
+ </p></div><div class="sect2" id="ROWTYPES-ACCESSING"><div class="titlepage"><div><div><h3 class="title">8.16.3. Accessing Composite Types</h3></div></div></div><p>
+ To access a field of a composite column, one writes a dot and the field
+ name, much like selecting a field from a table name. In fact, it's so
+ much like selecting from a table name that you often have to use parentheses
+ to keep from confusing the parser. For example, you might try to select
+ some subfields from our <code class="literal">on_hand</code> example table with something
+ like:
+
+</p><pre class="programlisting">
+SELECT item.name FROM on_hand WHERE item.price &gt; 9.99;
+</pre><p>
+
+ This will not work since the name <code class="literal">item</code> is taken to be a table
+ name, not a column name of <code class="literal">on_hand</code>, per SQL syntax rules.
+ You must write it like this:
+
+</p><pre class="programlisting">
+SELECT (item).name FROM on_hand WHERE (item).price &gt; 9.99;
+</pre><p>
+
+ or if you need to use the table name as well (for instance in a multitable
+ query), like this:
+
+</p><pre class="programlisting">
+SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price &gt; 9.99;
+</pre><p>
+
+ Now the parenthesized object is correctly interpreted as a reference to
+ the <code class="literal">item</code> column, and then the subfield can be selected from it.
+ </p><p>
+ Similar syntactic issues apply whenever you select a field from a composite
+ value. For instance, to select just one field from the result of a function
+ that returns a composite value, you'd need to write something like:
+
+</p><pre class="programlisting">
+SELECT (my_func(...)).field FROM ...
+</pre><p>
+
+ Without the extra parentheses, this will generate a syntax error.
+ </p><p>
+ The special field name <code class="literal">*</code> means <span class="quote">“<span class="quote">all fields</span>”</span>, as
+ further explained in <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a>.
+ </p></div><div class="sect2" id="id-1.5.7.24.8"><div class="titlepage"><div><div><h3 class="title">8.16.4. Modifying Composite Types</h3></div></div></div><p>
+ Here are some examples of the proper syntax for inserting and updating
+ composite columns.
+ First, inserting or updating a whole column:
+
+</p><pre class="programlisting">
+INSERT INTO mytab (complex_col) VALUES((1.1,2.2));
+
+UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...;
+</pre><p>
+
+ The first example omits <code class="literal">ROW</code>, the second uses it; we
+ could have done it either way.
+ </p><p>
+ We can update an individual subfield of a composite column:
+
+</p><pre class="programlisting">
+UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...;
+</pre><p>
+
+ Notice here that we don't need to (and indeed cannot)
+ put parentheses around the column name appearing just after
+ <code class="literal">SET</code>, but we do need parentheses when referencing the same
+ column in the expression to the right of the equal sign.
+ </p><p>
+ And we can specify subfields as targets for <code class="command">INSERT</code>, too:
+
+</p><pre class="programlisting">
+INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
+</pre><p>
+
+ Had we not supplied values for all the subfields of the column, the
+ remaining subfields would have been filled with null values.
+ </p></div><div class="sect2" id="ROWTYPES-USAGE"><div class="titlepage"><div><div><h3 class="title">8.16.5. Using Composite Types in Queries</h3></div></div></div><p>
+ There are various special syntax rules and behaviors associated with
+ composite types in queries. These rules provide useful shortcuts,
+ but can be confusing if you don't know the logic behind them.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, a reference to a table name (or alias)
+ in a query is effectively a reference to the composite value of the
+ table's current row. For example, if we had a table
+ <code class="structname">inventory_item</code> as shown
+ <a class="link" href="rowtypes.html#ROWTYPES-DECLARING" title="8.16.1. Declaration of Composite Types">above</a>, we could write:
+</p><pre class="programlisting">
+SELECT c FROM inventory_item c;
+</pre><p>
+ This query produces a single composite-valued column, so we might get
+ output like:
+</p><pre class="programlisting">
+ c
+------------------------
+ ("fuzzy dice",42,1.99)
+(1 row)
+</pre><p>
+ Note however that simple names are matched to column names before table
+ names, so this example works only because there is no column
+ named <code class="structfield">c</code> in the query's tables.
+ </p><p>
+ The ordinary qualified-column-name
+ syntax <em class="replaceable"><code>table_name</code></em><code class="literal">.</code><em class="replaceable"><code>column_name</code></em>
+ can be understood as applying <a class="link" href="sql-expressions.html#FIELD-SELECTION" title="4.2.4. Field Selection">field
+ selection</a> to the composite value of the table's current row.
+ (For efficiency reasons, it's not actually implemented that way.)
+ </p><p>
+ When we write
+</p><pre class="programlisting">
+SELECT c.* FROM inventory_item c;
+</pre><p>
+ then, according to the SQL standard, we should get the contents of the
+ table expanded into separate columns:
+</p><pre class="programlisting">
+ name | supplier_id | price
+------------+-------------+-------
+ fuzzy dice | 42 | 1.99
+(1 row)
+</pre><p>
+ as if the query were
+</p><pre class="programlisting">
+SELECT c.name, c.supplier_id, c.price FROM inventory_item c;
+</pre><p>
+ <span class="productname">PostgreSQL</span> will apply this expansion behavior to
+ any composite-valued expression, although as shown <a class="link" href="rowtypes.html#ROWTYPES-ACCESSING" title="8.16.3. Accessing Composite Types">above</a>, you need to write parentheses
+ around the value that <code class="literal">.*</code> is applied to whenever it's not a
+ simple table name. For example, if <code class="function">myfunc()</code> is a function
+ returning a composite type with columns <code class="structfield">a</code>,
+ <code class="structfield">b</code>, and <code class="structfield">c</code>, then these two queries have the
+ same result:
+</p><pre class="programlisting">
+SELECT (myfunc(x)).* FROM some_table;
+SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table;
+</pre><p>
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <span class="productname">PostgreSQL</span> handles column expansion by
+ actually transforming the first form into the second. So, in this
+ example, <code class="function">myfunc()</code> would get invoked three times per row
+ with either syntax. If it's an expensive function you may wish to
+ avoid that, which you can do with a query like:
+</p><pre class="programlisting">
+SELECT m.* FROM some_table, LATERAL myfunc(x) AS m;
+</pre><p>
+ Placing the function in
+ a <code class="literal">LATERAL</code> <code class="literal">FROM</code> item keeps it from
+ being invoked more than once per row. <code class="literal">m.*</code> is still
+ expanded into <code class="literal">m.a, m.b, m.c</code>, but now those variables
+ are just references to the output of the <code class="literal">FROM</code> item.
+ (The <code class="literal">LATERAL</code> keyword is optional here, but we show it
+ to clarify that the function is getting <code class="structfield">x</code>
+ from <code class="structname">some_table</code>.)
+ </p></div><p>
+ The <em class="replaceable"><code>composite_value</code></em><code class="literal">.*</code> syntax results in
+ column expansion of this kind when it appears at the top level of
+ a <a class="link" href="queries-select-lists.html" title="7.3. Select Lists"><code class="command">SELECT</code> output
+ list</a>, a <a class="link" href="dml-returning.html" title="6.4. Returning Data from Modified Rows"><code class="literal">RETURNING</code>
+ list</a> in <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code>,
+ a <a class="link" href="queries-values.html" title="7.7. VALUES Lists"><code class="literal">VALUES</code> clause</a>, or
+ a <a class="link" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">row constructor</a>.
+ In all other contexts (including when nested inside one of those
+ constructs), attaching <code class="literal">.*</code> to a composite value does not
+ change the value, since it means <span class="quote">“<span class="quote">all columns</span>”</span> and so the
+ same composite value is produced again. For example,
+ if <code class="function">somefunc()</code> accepts a composite-valued argument,
+ these queries are the same:
+
+</p><pre class="programlisting">
+SELECT somefunc(c.*) FROM inventory_item c;
+SELECT somefunc(c) FROM inventory_item c;
+</pre><p>
+
+ In both cases, the current row of <code class="structname">inventory_item</code> is
+ passed to the function as a single composite-valued argument.
+ Even though <code class="literal">.*</code> does nothing in such cases, using it is good
+ style, since it makes clear that a composite value is intended. In
+ particular, the parser will consider <code class="literal">c</code> in <code class="literal">c.*</code> to
+ refer to a table name or alias, not to a column name, so that there is
+ no ambiguity; whereas without <code class="literal">.*</code>, it is not clear
+ whether <code class="literal">c</code> means a table name or a column name, and in fact
+ the column-name interpretation will be preferred if there is a column
+ named <code class="literal">c</code>.
+ </p><p>
+ Another example demonstrating these concepts is that all these queries
+ mean the same thing:
+</p><pre class="programlisting">
+SELECT * FROM inventory_item c ORDER BY c;
+SELECT * FROM inventory_item c ORDER BY c.*;
+SELECT * FROM inventory_item c ORDER BY ROW(c.*);
+</pre><p>
+ All of these <code class="literal">ORDER BY</code> clauses specify the row's composite
+ value, resulting in sorting the rows according to the rules described
+ in <a class="xref" href="functions-comparisons.html#COMPOSITE-TYPE-COMPARISON" title="9.24.6. Composite Type Comparison">Section 9.24.6</a>. However,
+ if <code class="structname">inventory_item</code> contained a column
+ named <code class="structfield">c</code>, the first case would be different from the
+ others, as it would mean to sort by that column only. Given the column
+ names previously shown, these queries are also equivalent to those above:
+</p><pre class="programlisting">
+SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price);
+SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price);
+</pre><p>
+ (The last case uses a row constructor with the key word <code class="literal">ROW</code>
+ omitted.)
+ </p><p>
+ Another special syntactical behavior associated with composite values is
+ that we can use <em class="firstterm">functional notation</em> for extracting a field
+ of a composite value. The simple way to explain this is that
+ the notations <code class="literal"><em class="replaceable"><code>field</code></em>(<em class="replaceable"><code>table</code></em>)</code>
+ and <code class="literal"><em class="replaceable"><code>table</code></em>.<em class="replaceable"><code>field</code></em></code>
+ are interchangeable. For example, these queries are equivalent:
+
+</p><pre class="programlisting">
+SELECT c.name FROM inventory_item c WHERE c.price &gt; 1000;
+SELECT name(c) FROM inventory_item c WHERE price(c) &gt; 1000;
+</pre><p>
+
+ Moreover, if we have a function that accepts a single argument of a
+ composite type, we can call it with either notation. These queries are
+ all equivalent:
+
+</p><pre class="programlisting">
+SELECT somefunc(c) FROM inventory_item c;
+SELECT somefunc(c.*) FROM inventory_item c;
+SELECT c.somefunc FROM inventory_item c;
+</pre><p>
+ </p><p>
+ This equivalence between functional notation and field notation
+ makes it possible to use functions on composite types to implement
+ <span class="quote">“<span class="quote">computed fields</span>”</span>.
+ <a id="id-1.5.7.24.9.10.2" class="indexterm"></a>
+ <a id="id-1.5.7.24.9.10.3" class="indexterm"></a>
+ An application using the last query above wouldn't need to be directly
+ aware that <code class="literal">somefunc</code> isn't a real column of the table.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Because of this behavior, it's unwise to give a function that takes a
+ single composite-type argument the same name as any of the fields of
+ that composite type. If there is ambiguity, the field-name
+ interpretation will be chosen if field-name syntax is used, while the
+ function will be chosen if function-call syntax is used. However,
+ <span class="productname">PostgreSQL</span> versions before 11 always chose the
+ field-name interpretation, unless the syntax of the call required it to
+ be a function call. One way to force the function interpretation in
+ older versions is to schema-qualify the function name, that is, write
+ <code class="literal"><em class="replaceable"><code>schema</code></em>.<em class="replaceable"><code>func</code></em>(<em class="replaceable"><code>compositevalue</code></em>)</code>.
+ </p></div></div><div class="sect2" id="ROWTYPES-IO-SYNTAX"><div class="titlepage"><div><div><h3 class="title">8.16.6. Composite Type Input and Output Syntax</h3></div></div></div><p>
+ The external text representation of a composite value consists of items that
+ are interpreted according to the I/O conversion rules for the individual
+ field types, plus decoration that indicates the composite structure.
+ The decoration consists of parentheses (<code class="literal">(</code> and <code class="literal">)</code>)
+ around the whole value, plus commas (<code class="literal">,</code>) between adjacent
+ items. Whitespace outside the parentheses is ignored, but within the
+ parentheses it is considered part of the field value, and might or might not be
+ significant depending on the input conversion rules for the field data type.
+ For example, in:
+</p><pre class="programlisting">
+'( 42)'
+</pre><p>
+ the whitespace will be ignored if the field type is integer, but not if
+ it is text.
+ </p><p>
+ As shown previously, when writing a composite value you can write double
+ quotes around any individual field value.
+ You <span class="emphasis"><em>must</em></span> do so if the field value would otherwise
+ confuse the composite-value parser. In particular, fields containing
+ parentheses, commas, double quotes, or backslashes must be double-quoted.
+ To put a double quote or backslash in a quoted composite field value,
+ precede it with a backslash. (Also, a pair of double quotes within a
+ double-quoted field value is taken to represent a double quote character,
+ analogously to the rules for single quotes in SQL literal strings.)
+ Alternatively, you can avoid quoting and use backslash-escaping to
+ protect all data characters
+ that would otherwise be taken as composite syntax.
+ </p><p>
+ A completely empty field value (no characters at all between the commas
+ or parentheses) represents a NULL. To write a value that is an empty
+ string rather than NULL, write <code class="literal">""</code>.
+ </p><p>
+ The composite output routine will put double quotes around field values
+ if they are empty strings or contain parentheses, commas,
+ double quotes, backslashes, or white space. (Doing so for white space
+ is not essential, but aids legibility.) Double quotes and backslashes
+ embedded in field values will be doubled.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Remember that what you write in an SQL command will first be interpreted
+ as a string literal, and then as a composite. This doubles the number of
+ backslashes you need (assuming escape string syntax is used).
+ For example, to insert a <code class="type">text</code> field
+ containing a double quote and a backslash in a composite
+ value, you'd need to write:
+</p><pre class="programlisting">
+INSERT ... VALUES ('("\"\\")');
+</pre><p>
+ The string-literal processor removes one level of backslashes, so that
+ what arrives at the composite-value parser looks like
+ <code class="literal">("\"\\")</code>. In turn, the string
+ fed to the <code class="type">text</code> data type's input routine
+ becomes <code class="literal">"\</code>. (If we were working
+ with a data type whose input routine also treated backslashes specially,
+ <code class="type">bytea</code> for example, we might need as many as eight backslashes
+ in the command to get one backslash into the stored composite field.)
+ Dollar quoting (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) can be
+ used to avoid the need to double backslashes.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ The <code class="literal">ROW</code> constructor syntax is usually easier to work with
+ than the composite-literal syntax when writing composite values in SQL
+ commands.
+ In <code class="literal">ROW</code>, individual field values are written the same way
+ they would be written when not members of a composite.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="arrays.html" title="8.15. Arrays">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rangetypes.html" title="8.17. Range Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.15. Arrays </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.17. Range Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rule-system.html b/doc/src/sgml/html/rule-system.html
new file mode 100644
index 0000000..7d4f062
--- /dev/null
+++ b/doc/src/sgml/html/rule-system.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.4. The PostgreSQL Rule System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="parser-stage.html" title="52.3. The Parser Stage" /><link rel="next" href="planner-optimizer.html" title="52.5. Planner/Optimizer" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.4. The <span class="productname">PostgreSQL</span> Rule System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="parser-stage.html" title="52.3. The Parser Stage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><th width="60%" align="center">Chapter 52. Overview of PostgreSQL Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="planner-optimizer.html" title="52.5. Planner/Optimizer">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULE-SYSTEM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.4. The <span class="productname">PostgreSQL</span> Rule System</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> supports a powerful
+ <em class="firstterm">rule system</em> for the specification
+ of <em class="firstterm">views</em> and ambiguous <em class="firstterm">view updates</em>.
+ Originally the <span class="productname">PostgreSQL</span>
+ rule system consisted of two implementations:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The first one worked using <em class="firstterm">row level</em> processing and was
+ implemented deep in the <em class="firstterm">executor</em>. The rule system was
+ called whenever an individual row had been accessed. This
+ implementation was removed in 1995 when the last official release
+ of the <span class="productname">Berkeley Postgres</span> project was
+ transformed into <span class="productname">Postgres95</span>.
+ </p></li><li class="listitem"><p>
+ The second implementation of the rule system is a technique
+ called <em class="firstterm">query rewriting</em>.
+ The <em class="firstterm">rewrite system</em> is a module
+ that exists between the <em class="firstterm">parser stage</em> and the
+ <em class="firstterm">planner/optimizer</em>. This technique is still implemented.
+ </p></li></ul></div><p>
+ </p><p>
+ The query rewriter is discussed in some detail in
+ <a class="xref" href="rules.html" title="Chapter 41. The Rule System">Chapter 41</a>, 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
+ can be thought of as a form of macro expansion.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parser-stage.html" title="52.3. The Parser Stage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="overview.html" title="Chapter 52. Overview of PostgreSQL Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="planner-optimizer.html" title="52.5. Planner/Optimizer">Next</a></td></tr><tr><td width="40%" align="left" valign="top">52.3. The Parser Stage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 52.5. Planner/Optimizer</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-materializedviews.html b/doc/src/sgml/html/rules-materializedviews.html
new file mode 100644
index 0000000..899c987
--- /dev/null
+++ b/doc/src/sgml/html/rules-materializedviews.html
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.3. Materialized Views</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-views.html" title="41.2. Views and the Rule System" /><link rel="next" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.3. Materialized Views</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-views.html" title="41.2. Views and the Rule System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-MATERIALIZEDVIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.3. Materialized Views</h2></div></div></div><a id="id-1.8.6.8.2" class="indexterm"></a><a id="id-1.8.6.8.3" class="indexterm"></a><a id="id-1.8.6.8.4" class="indexterm"></a><p>
+ Materialized views in <span class="productname">PostgreSQL</span> use the
+ rule system like views do, but persist the results in a table-like form.
+ The main differences between:
+
+</p><pre class="programlisting">
+CREATE MATERIALIZED VIEW mymatview AS SELECT * FROM mytab;
+</pre><p>
+
+ and:
+
+</p><pre class="programlisting">
+CREATE TABLE mymatview AS SELECT * FROM mytab;
+</pre><p>
+
+ are that the materialized view cannot subsequently be directly updated
+ and that the query used to create the materialized view is stored in
+ exactly the same way that a view's query is stored, so that fresh data
+ can be generated for the materialized view with:
+
+</p><pre class="programlisting">
+REFRESH MATERIALIZED VIEW mymatview;
+</pre><p>
+
+ The information about a materialized view in the
+ <span class="productname">PostgreSQL</span> system catalogs is exactly
+ the same as it is for a table or view. So for the parser, a
+ materialized view is a relation, just like a table or a view. When
+ a materialized view is referenced in a query, the data is returned
+ directly from the materialized view, like from a table; the rule is
+ only used for populating the materialized view.
+</p><p>
+ While access to the data stored in a materialized view is often much
+ faster than accessing the underlying tables directly or through a view,
+ the data is not always current; yet sometimes current data is not needed.
+ Consider a table which records sales:
+
+</p><pre class="programlisting">
+CREATE TABLE invoice (
+ invoice_no integer PRIMARY KEY,
+ seller_no integer, -- ID of salesperson
+ invoice_date date, -- date of sale
+ invoice_amt numeric(13,2) -- amount of sale
+);
+</pre><p>
+
+ If people want to be able to quickly graph historical sales data, they
+ might want to summarize, and they may not care about the incomplete data
+ for the current date:
+
+</p><pre class="programlisting">
+CREATE MATERIALIZED VIEW sales_summary AS
+ SELECT
+ seller_no,
+ invoice_date,
+ sum(invoice_amt)::numeric(13,2) as sales_amt
+ FROM invoice
+ WHERE invoice_date &lt; CURRENT_DATE
+ GROUP BY
+ seller_no,
+ invoice_date;
+
+CREATE UNIQUE INDEX sales_summary_seller
+ ON sales_summary (seller_no, invoice_date);
+</pre><p>
+
+ This materialized view might be useful for displaying a graph in the
+ dashboard created for salespeople. A job could be scheduled to update
+ the statistics each night using this SQL statement:
+
+</p><pre class="programlisting">
+REFRESH MATERIALIZED VIEW sales_summary;
+</pre><p>
+</p><p>
+ Another use for a materialized view is to allow faster access to data
+ brought across from a remote system through a foreign data wrapper.
+ A simple example using <code class="literal">file_fdw</code> is below, with timings,
+ but since this is using cache on the local system the performance
+ difference compared to access to a remote system would usually be greater
+ than shown here. Notice we are also exploiting the ability to put an
+ index on the materialized view, whereas <code class="literal">file_fdw</code> does
+ not support indexes; this advantage might not apply for other sorts of
+ foreign data access.
+</p><p>
+ Setup:
+
+</p><pre class="programlisting">
+CREATE EXTENSION file_fdw;
+CREATE SERVER local_file FOREIGN DATA WRAPPER file_fdw;
+CREATE FOREIGN TABLE words (word text NOT NULL)
+ SERVER local_file
+ OPTIONS (filename '/usr/share/dict/words');
+CREATE MATERIALIZED VIEW wrd AS SELECT * FROM words;
+CREATE UNIQUE INDEX wrd_word ON wrd (word);
+CREATE EXTENSION pg_trgm;
+CREATE INDEX wrd_trgm ON wrd USING gist (word gist_trgm_ops);
+VACUUM ANALYZE wrd;
+</pre><p>
+
+ Now let's spell-check a word. Using <code class="literal">file_fdw</code> directly:
+
+</p><pre class="programlisting">
+SELECT count(*) FROM words WHERE word = 'caterpiler';
+
+ count
+-------
+ 0
+(1 row)
+</pre><p>
+
+ With <code class="command">EXPLAIN ANALYZE</code>, we see:
+
+</p><pre class="programlisting">
+ Aggregate (cost=21763.99..21764.00 rows=1 width=0) (actual time=188.180..188.181 rows=1 loops=1)
+ -&gt; Foreign Scan on words (cost=0.00..21761.41 rows=1032 width=0) (actual time=188.177..188.177 rows=0 loops=1)
+ Filter: (word = 'caterpiler'::text)
+ Rows Removed by Filter: 479829
+ Foreign File: /usr/share/dict/words
+ Foreign File Size: 4953699
+ Planning time: 0.118 ms
+ Execution time: 188.273 ms
+</pre><p>
+
+ If the materialized view is used instead, the query is much faster:
+
+</p><pre class="programlisting">
+ Aggregate (cost=4.44..4.45 rows=1 width=0) (actual time=0.042..0.042 rows=1 loops=1)
+ -&gt; Index Only Scan using wrd_word on wrd (cost=0.42..4.44 rows=1 width=0) (actual time=0.039..0.039 rows=0 loops=1)
+ Index Cond: (word = 'caterpiler'::text)
+ Heap Fetches: 0
+ Planning time: 0.164 ms
+ Execution time: 0.117 ms
+</pre><p>
+
+ Either way, the word is spelled wrong, so let's look for what we might
+ have wanted. Again using <code class="literal">file_fdw</code> and
+ <code class="literal">pg_trgm</code>:
+
+</p><pre class="programlisting">
+SELECT word FROM words ORDER BY word &lt;-&gt; 'caterpiler' LIMIT 10;
+
+ word
+---------------
+ cater
+ caterpillar
+ Caterpillar
+ caterpillars
+ caterpillar's
+ Caterpillar's
+ caterer
+ caterer's
+ caters
+ catered
+(10 rows)
+</pre><p>
+
+</p><pre class="programlisting">
+ Limit (cost=11583.61..11583.64 rows=10 width=32) (actual time=1431.591..1431.594 rows=10 loops=1)
+ -&gt; Sort (cost=11583.61..11804.76 rows=88459 width=32) (actual time=1431.589..1431.591 rows=10 loops=1)
+ Sort Key: ((word &lt;-&gt; 'caterpiler'::text))
+ Sort Method: top-N heapsort Memory: 25kB
+ -&gt; Foreign Scan on words (cost=0.00..9672.05 rows=88459 width=32) (actual time=0.057..1286.455 rows=479829 loops=1)
+ Foreign File: /usr/share/dict/words
+ Foreign File Size: 4953699
+ Planning time: 0.128 ms
+ Execution time: 1431.679 ms
+</pre><p>
+
+ Using the materialized view:
+
+</p><pre class="programlisting">
+ Limit (cost=0.29..1.06 rows=10 width=10) (actual time=187.222..188.257 rows=10 loops=1)
+ -&gt; Index Scan using wrd_trgm on wrd (cost=0.29..37020.87 rows=479829 width=10) (actual time=187.219..188.252 rows=10 loops=1)
+ Order By: (word &lt;-&gt; 'caterpiler'::text)
+ Planning time: 0.196 ms
+ Execution time: 198.640 ms
+</pre><p>
+
+ If you can tolerate periodic update of the remote data to the local
+ database, the performance benefit can be substantial.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-views.html" title="41.2. Views and the Rule System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.2. Views and the Rule System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-privileges.html b/doc/src/sgml/html/rules-privileges.html
new file mode 100644
index 0000000..ddf23e4
--- /dev/null
+++ b/doc/src/sgml/html/rules-privileges.html
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.5. Rules and Privileges</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE" /><link rel="next" href="rules-status.html" title="41.6. Rules and Command Status" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.5. Rules and Privileges</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-status.html" title="41.6. Rules and Command Status">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-PRIVILEGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.5. Rules and Privileges</h2></div></div></div><a id="id-1.8.6.10.2" class="indexterm"></a><a id="id-1.8.6.10.3" class="indexterm"></a><p>
+ Due to rewriting of queries by the <span class="productname">PostgreSQL</span>
+ rule system, other tables/views than those used in the original
+ query get accessed. When update rules are used, this can include write access
+ to tables.
+</p><p>
+ Rewrite rules don't have a separate owner. The owner of
+ a relation (table or view) is automatically the owner of the
+ rewrite rules that are defined for it.
+ The <span class="productname">PostgreSQL</span> rule system changes the
+ behavior of the default access control system. With the exception of
+ <code class="literal">SELECT</code> rules associated with security invoker views
+ (see <a class="link" href="sql-createview.html" title="CREATE VIEW"><code class="command">CREATE VIEW</code></a>),
+ all relations that are used due to rules get checked against the
+ privileges of the rule owner, not the user invoking the rule.
+ This means that, except for security invoker views, users only need the
+ required privileges for the tables/views that are explicitly named in
+ their queries.
+</p><p>
+ For example: A user has a list of phone numbers where some of
+ them are private, the others are of interest for the assistant of the office.
+ The user can construct the following:
+
+</p><pre class="programlisting">
+CREATE TABLE phone_data (person text, phone text, private boolean);
+CREATE VIEW phone_number AS
+ SELECT person, CASE WHEN NOT private THEN phone END AS phone
+ FROM phone_data;
+GRANT SELECT ON phone_number TO assistant;
+</pre><p>
+
+ Nobody except that user (and the database superusers) can access the
+ <code class="literal">phone_data</code> table. But because of the <code class="command">GRANT</code>,
+ the assistant can run a <code class="command">SELECT</code> on the
+ <code class="literal">phone_number</code> view. The rule system will rewrite the
+ <code class="command">SELECT</code> from <code class="literal">phone_number</code> into a
+ <code class="command">SELECT</code> from <code class="literal">phone_data</code>.
+ Since the user is the owner of
+ <code class="literal">phone_number</code> and therefore the owner of the rule, the
+ read access to <code class="literal">phone_data</code> is now checked against the user's
+ privileges and the query is permitted. The check for accessing
+ <code class="literal">phone_number</code> is also performed, but this is done
+ against the invoking user, so nobody but the user and the
+ assistant can use it.
+</p><p>
+ The privileges are checked rule by rule. So the assistant is for now the
+ only one who can see the public phone numbers. But the assistant can set up
+ another view and grant access to that to the public. Then, anyone
+ can see the <code class="literal">phone_number</code> data through the assistant's view.
+ What the assistant cannot do is to create a view that directly
+ accesses <code class="literal">phone_data</code>. (Actually the assistant can, but it will not work since
+ every access will be denied during the permission checks.)
+ And as soon as the user notices that the assistant opened
+ their <code class="literal">phone_number</code> view, the user can revoke the assistant's access. Immediately, any
+ access to the assistant's view would fail.
+</p><p>
+ One might think that this rule-by-rule checking is a security
+ hole, but in fact it isn't. But if it did not work this way, the assistant
+ could set up a table with the same columns as <code class="literal">phone_number</code> and
+ copy the data to there once per day. Then it's the assistant's own data and
+ the assistant can grant access to everyone they want. A
+ <code class="command">GRANT</code> command means, <span class="quote">“<span class="quote">I trust you</span>”</span>.
+ If someone you trust does the thing above, it's time to
+ think it over and then use <code class="command">REVOKE</code>.
+</p><p>
+ Note that while views can be used to hide the contents of certain
+ columns using the technique shown above, they cannot be used to reliably
+ conceal the data in unseen rows unless the
+ <code class="literal">security_barrier</code> flag has been set. For example,
+ the following view is insecure:
+</p><pre class="programlisting">
+CREATE VIEW phone_number AS
+ SELECT person, phone FROM phone_data WHERE phone NOT LIKE '412%';
+</pre><p>
+ This view might seem secure, since the rule system will rewrite any
+ <code class="command">SELECT</code> from <code class="literal">phone_number</code> into a
+ <code class="command">SELECT</code> from <code class="literal">phone_data</code> and add the
+ qualification that only entries where <code class="literal">phone</code> does not begin
+ with 412 are wanted. But if the user can create their own functions,
+ it is not difficult to convince the planner to execute the user-defined
+ function prior to the <code class="function">NOT LIKE</code> expression.
+ For example:
+</p><pre class="programlisting">
+CREATE FUNCTION tricky(text, text) RETURNS bool AS $$
+BEGIN
+ RAISE NOTICE '% =&gt; %', $1, $2;
+ RETURN true;
+END;
+$$ LANGUAGE plpgsql COST 0.0000000000000000000001;
+
+SELECT * FROM phone_number WHERE tricky(person, phone);
+</pre><p>
+ Every person and phone number in the <code class="literal">phone_data</code> table will be
+ printed as a <code class="literal">NOTICE</code>, because the planner will choose to
+ execute the inexpensive <code class="function">tricky</code> function before the
+ more expensive <code class="function">NOT LIKE</code>. Even if the user is
+ prevented from defining new functions, built-in functions can be used in
+ similar attacks. (For example, most casting functions include their
+ input values in the error messages they produce.)
+</p><p>
+ Similar considerations apply to update rules. In the examples of
+ the previous section, the owner of the tables in the example
+ database could grant the privileges <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, and <code class="literal">DELETE</code> on
+ the <code class="literal">shoelace</code> view to someone else, but only
+ <code class="literal">SELECT</code> on <code class="literal">shoelace_log</code>. The rule action to
+ write log entries will still be executed successfully, and that
+ other user could see the log entries. But they could not create fake
+ entries, nor could they manipulate or remove existing ones. In this
+ case, there is no possibility of subverting the rules by convincing
+ the planner to alter the order of operations, because the only rule
+ which references <code class="literal">shoelace_log</code> is an unqualified
+ <code class="literal">INSERT</code>. This might not be true in more complex scenarios.
+</p><p>
+ When it is necessary for a view to provide row-level security, the
+ <code class="literal">security_barrier</code> attribute should be applied to
+ the view. This prevents maliciously-chosen functions and operators from
+ being passed values from rows until after the view has done its work. For
+ example, if the view shown above had been created like this, it would
+ be secure:
+</p><pre class="programlisting">
+CREATE VIEW phone_number WITH (security_barrier) AS
+ SELECT person, phone FROM phone_data WHERE phone NOT LIKE '412%';
+</pre><p>
+ Views created with the <code class="literal">security_barrier</code> may perform
+ far worse than views created without this option. In general, there is
+ no way to avoid this: the fastest possible plan must be rejected
+ if it may compromise security. For this reason, this option is not
+ enabled by default.
+</p><p>
+ The query planner has more flexibility when dealing with functions that
+ have no side effects. Such functions are referred to as <code class="literal">LEAKPROOF</code>, and
+ include many simple, commonly used operators, such as many equality
+ operators. The query planner can safely allow such functions to be evaluated
+ at any point in the query execution process, since invoking them on rows
+ invisible to the user will not leak any information about the unseen rows.
+ Further, functions which do not take arguments or which are not passed any
+ arguments from the security barrier view do not have to be marked as
+ <code class="literal">LEAKPROOF</code> to be pushed down, as they never receive data
+ from the view. In contrast, a function that might throw an error depending
+ on the values received as arguments (such as one that throws an error in the
+ event of overflow or division by zero) is not leak-proof, and could provide
+ significant information about the unseen rows if applied before the security
+ view's row filters.
+</p><p>
+ It is important to understand that even a view created with the
+ <code class="literal">security_barrier</code> option is intended to be secure only
+ in the limited sense that the contents of the invisible tuples will not be
+ passed to possibly-insecure functions. The user may well have other means
+ of making inferences about the unseen data; for example, they can see the
+ query plan using <code class="command">EXPLAIN</code>, or measure the run time of
+ queries against the view. A malicious attacker might be able to infer
+ something about the amount of unseen data, or even gain some information
+ about the data distribution or most common values (since these things may
+ affect the run time of the plan; or even, since they are also reflected in
+ the optimizer statistics, the choice of plan). If these types of "covert
+ channel" attacks are of concern, it is probably unwise to grant any access
+ to the data at all.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-status.html" title="41.6. Rules and Command Status">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.6. Rules and Command Status</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-status.html b/doc/src/sgml/html/rules-status.html
new file mode 100644
index 0000000..81ce991
--- /dev/null
+++ b/doc/src/sgml/html/rules-status.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.6. Rules and Command Status</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-privileges.html" title="41.5. Rules and Privileges" /><link rel="next" href="rules-triggers.html" title="41.7. Rules Versus Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.6. Rules and Command Status</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-privileges.html" title="41.5. Rules and Privileges">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-triggers.html" title="41.7. Rules Versus Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-STATUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.6. Rules and Command Status</h2></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> server returns a command
+ status string, such as <code class="literal">INSERT 149592 1</code>, for each
+ command it receives. This is simple enough when there are no rules
+ involved, but what happens when the query is rewritten by rules?
+</p><p>
+ Rules affect the command status as follows:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ If there is no unconditional <code class="literal">INSTEAD</code> rule for the query, then
+ the originally given query will be executed, and its command
+ status will be returned as usual. (But note that if there were
+ any conditional <code class="literal">INSTEAD</code> rules, the negation of their qualifications
+ will have been added to the original query. This might reduce the
+ number of rows it processes, and if so the reported status will
+ be affected.)
+ </p></li><li class="listitem"><p>
+ If there is any unconditional <code class="literal">INSTEAD</code> rule for the query, then
+ the original query will not be executed at all. In this case,
+ the server will return the command status for the last query
+ that was inserted by an <code class="literal">INSTEAD</code> rule (conditional or
+ unconditional) and is of the same command type
+ (<code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code>) as the original query. If no query
+ meeting those requirements is added by any rule, then the
+ returned command status shows the original query type and
+ zeroes for the row-count and OID fields.
+ </p></li></ul></div><p>
+</p><p>
+ The programmer can ensure that any desired <code class="literal">INSTEAD</code> rule is the one
+ that sets the command status in the second case, by giving it the
+ alphabetically last rule name among the active rules, so that it
+ gets applied last.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-privileges.html" title="41.5. Rules and Privileges">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-triggers.html" title="41.7. Rules Versus Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.5. Rules and Privileges </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.7. Rules Versus Triggers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-triggers.html b/doc/src/sgml/html/rules-triggers.html
new file mode 100644
index 0000000..f46f65f
--- /dev/null
+++ b/doc/src/sgml/html/rules-triggers.html
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.7. Rules Versus Triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-status.html" title="41.6. Rules and Command Status" /><link rel="next" href="xplang.html" title="Chapter 42. Procedural Languages" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.7. Rules Versus Triggers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-status.html" title="41.6. Rules and Command Status">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xplang.html" title="Chapter 42. Procedural Languages">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-TRIGGERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.7. Rules Versus Triggers</h2></div></div></div><a id="id-1.8.6.12.2" class="indexterm"></a><a id="id-1.8.6.12.3" class="indexterm"></a><p>
+ Many things that can be done using triggers can also be
+ implemented using the <span class="productname">PostgreSQL</span>
+ rule system. One of the things that cannot be implemented by
+ rules are some kinds of constraints, especially foreign keys. It is possible
+ to place a qualified rule that rewrites a command to <code class="literal">NOTHING</code>
+ if the value of a column does not appear in another table.
+ But then the data is silently thrown away and that's
+ not a good idea. If checks for valid values are required,
+ and in the case of an invalid value an error message should
+ be generated, it must be done by a trigger.
+</p><p>
+ In this chapter, we focused on using rules to update views. All of
+ the update rule examples in this chapter can also be implemented
+ using <code class="literal">INSTEAD OF</code> triggers on the views. Writing such
+ triggers is often easier than writing rules, particularly if complex
+ logic is required to perform the update.
+</p><p>
+ For the things that can be implemented by both, which is best
+ depends on the usage of the database.
+ A trigger is fired once for each affected row. A rule modifies
+ the query or generates an additional query. So if many
+ rows are affected in one statement, a rule issuing one extra
+ command is likely to be faster than a trigger that is
+ called for every single row and must re-determine what to do
+ many times. However, the trigger approach is conceptually far
+ simpler than the rule approach, and is easier for novices to get right.
+</p><p>
+ Here we show an example of how the choice of rules versus triggers
+ plays out in one situation. There are two tables:
+
+</p><pre class="programlisting">
+CREATE TABLE computer (
+ hostname text, -- indexed
+ manufacturer text -- indexed
+);
+
+CREATE TABLE software (
+ software text, -- indexed
+ hostname text -- indexed
+);
+</pre><p>
+
+ Both tables have many thousands of rows and the indexes on
+ <code class="structfield">hostname</code> are unique. The rule or trigger should
+ implement a constraint that deletes rows from <code class="literal">software</code>
+ that reference a deleted computer. The trigger would use this command:
+
+</p><pre class="programlisting">
+DELETE FROM software WHERE hostname = $1;
+</pre><p>
+
+ Since the trigger is called for each individual row deleted from
+ <code class="literal">computer</code>, it can prepare and save the plan for this
+ command and pass the <code class="structfield">hostname</code> value in the
+ parameter. The rule would be written as:
+
+</p><pre class="programlisting">
+CREATE RULE computer_del AS ON DELETE TO computer
+ DO DELETE FROM software WHERE hostname = OLD.hostname;
+</pre><p>
+ </p><p>
+ Now we look at different types of deletes. In the case of a:
+
+</p><pre class="programlisting">
+DELETE FROM computer WHERE hostname = 'mypc.local.net';
+</pre><p>
+
+ the table <code class="literal">computer</code> is scanned by index (fast), and the
+ command issued by the trigger would also use an index scan (also fast).
+ The extra command from the rule would be:
+
+</p><pre class="programlisting">
+DELETE FROM software WHERE computer.hostname = 'mypc.local.net'
+ AND software.hostname = computer.hostname;
+</pre><p>
+
+ Since there are appropriate indexes set up, the planner
+ will create a plan of
+
+</p><pre class="literallayout">
+Nestloop
+ -&gt; Index Scan using comp_hostidx on computer
+ -&gt; Index Scan using soft_hostidx on software
+</pre><p>
+
+ So there would be not that much difference in speed between
+ the trigger and the rule implementation.
+ </p><p>
+ With the next delete we want to get rid of all the 2000 computers
+ where the <code class="structfield">hostname</code> starts with
+ <code class="literal">old</code>. There are two possible commands to do that. One
+ is:
+
+</p><pre class="programlisting">
+DELETE FROM computer WHERE hostname &gt;= 'old'
+ AND hostname &lt; 'ole'
+</pre><p>
+
+ The command added by the rule will be:
+
+</p><pre class="programlisting">
+DELETE FROM software WHERE computer.hostname &gt;= 'old' AND computer.hostname &lt; 'ole'
+ AND software.hostname = computer.hostname;
+</pre><p>
+
+ with the plan
+
+</p><pre class="literallayout">
+Hash Join
+ -&gt; Seq Scan on software
+ -&gt; Hash
+ -&gt; Index Scan using comp_hostidx on computer
+</pre><p>
+
+ The other possible command is:
+
+</p><pre class="programlisting">
+DELETE FROM computer WHERE hostname ~ '^old';
+</pre><p>
+
+ which results in the following executing plan for the command
+ added by the rule:
+
+</p><pre class="literallayout">
+Nestloop
+ -&gt; Index Scan using comp_hostidx on computer
+ -&gt; Index Scan using soft_hostidx on software
+</pre><p>
+
+ This shows, that the planner does not realize that the
+ qualification for <code class="structfield">hostname</code> in
+ <code class="literal">computer</code> could also be used for an index scan on
+ <code class="literal">software</code> when there are multiple qualification
+ expressions combined with <code class="literal">AND</code>, which is what it does
+ in the regular-expression version of the command. The trigger will
+ get invoked once for each of the 2000 old computers that have to be
+ deleted, and that will result in one index scan over
+ <code class="literal">computer</code> and 2000 index scans over
+ <code class="literal">software</code>. The rule implementation will do it with two
+ commands that use indexes. And it depends on the overall size of
+ the table <code class="literal">software</code> whether the rule will still be faster in the
+ sequential scan situation. 2000 command executions from the trigger over the SPI
+ manager take some time, even if all the index blocks will soon be in the cache.
+</p><p>
+ The last command we look at is:
+
+</p><pre class="programlisting">
+DELETE FROM computer WHERE manufacturer = 'bim';
+</pre><p>
+
+ Again this could result in many rows to be deleted from
+ <code class="literal">computer</code>. So the trigger will again run many commands
+ through the executor. The command generated by the rule will be:
+
+</p><pre class="programlisting">
+DELETE FROM software WHERE computer.manufacturer = 'bim'
+ AND software.hostname = computer.hostname;
+</pre><p>
+
+ The plan for that command will again be the nested loop over two
+ index scans, only using a different index on <code class="literal">computer</code>:
+
+</p><pre class="programlisting">
+Nestloop
+ -&gt; Index Scan using comp_manufidx on computer
+ -&gt; Index Scan using soft_hostidx on software
+</pre><p>
+
+ In any of these cases, the extra commands from the rule system
+ will be more or less independent from the number of affected rows
+ in a command.
+</p><p>
+ The summary is, rules will only be significantly slower than
+ triggers if their actions result in large and badly qualified
+ joins, a situation where the planner fails.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-status.html" title="41.6. Rules and Command Status">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xplang.html" title="Chapter 42. Procedural Languages">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.6. Rules and Command Status </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 42. Procedural Languages</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-update.html b/doc/src/sgml/html/rules-update.html
new file mode 100644
index 0000000..27d60c8
--- /dev/null
+++ b/doc/src/sgml/html/rules-update.html
@@ -0,0 +1,750 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.4. Rules on INSERT, UPDATE, and DELETE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-materializedviews.html" title="41.3. Materialized Views" /><link rel="next" href="rules-privileges.html" title="41.5. Rules and Privileges" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-materializedviews.html" title="41.3. Materialized Views">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-privileges.html" title="41.5. Rules and Privileges">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-UPDATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="rules-update.html#id-1.8.6.9.7">41.4.1. How Update Rules Work</a></span></dt><dt><span class="sect2"><a href="rules-update.html#RULES-UPDATE-VIEWS">41.4.2. Cooperation with Views</a></span></dt></dl></div><a id="id-1.8.6.9.2" class="indexterm"></a><a id="id-1.8.6.9.3" class="indexterm"></a><a id="id-1.8.6.9.4" class="indexterm"></a><p>
+ Rules that are defined on <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ and <code class="command">DELETE</code> are significantly different from the view rules
+ described in the previous section. First, their <code class="command">CREATE
+ RULE</code> command allows more:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ They are allowed to have no action.
+ </p></li><li class="listitem"><p>
+ They can have multiple actions.
+ </p></li><li class="listitem"><p>
+ They can be <code class="literal">INSTEAD</code> or <code class="literal">ALSO</code> (the default).
+ </p></li><li class="listitem"><p>
+ The pseudorelations <code class="literal">NEW</code> and <code class="literal">OLD</code> become useful.
+ </p></li><li class="listitem"><p>
+ They can have rule qualifications.
+ </p></li></ul></div><p>
+
+ Second, they don't modify the query tree in place. Instead they
+ create zero or more new query trees and can throw away the
+ original one.
+</p><div class="caution"><h3 class="title">Caution</h3><p>
+ In many cases, tasks that could be performed by rules
+ on <code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code> are better done
+ with triggers. Triggers are notationally a bit more complicated, but their
+ semantics are much simpler to understand. Rules tend to have surprising
+ results when the original query contains volatile functions: volatile
+ functions may get executed more times than expected in the process of
+ carrying out the rules.
+ </p><p>
+ Also, there are some cases that are not supported by these types of rules at
+ all, notably including <code class="literal">WITH</code> clauses in the original query and
+ multiple-assignment sub-<code class="literal">SELECT</code>s in the <code class="literal">SET</code> list
+ of <code class="command">UPDATE</code> queries. This is because copying these constructs
+ into a rule query would result in multiple evaluations of the sub-query,
+ contrary to the express intent of the query's author.
+ </p></div><div class="sect2" id="id-1.8.6.9.7"><div class="titlepage"><div><div><h3 class="title">41.4.1. How Update Rules Work</h3></div></div></div><p>
+ Keep the syntax:
+
+</p><pre class="programlisting">
+CREATE [ OR REPLACE ] RULE <em class="replaceable"><code>name</code></em> AS ON <em class="replaceable"><code>event</code></em>
+ TO <em class="replaceable"><code>table</code></em> [ WHERE <em class="replaceable"><code>condition</code></em> ]
+ DO [ ALSO | INSTEAD ] { NOTHING | <em class="replaceable"><code>command</code></em> | ( <em class="replaceable"><code>command</code></em> ; <em class="replaceable"><code>command</code></em> ... ) }
+</pre><p>
+
+ in mind.
+ In the following, <em class="firstterm">update rules</em> means rules that are defined
+ on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code>.
+</p><p>
+ Update rules get applied by the rule system when the result
+ relation and the command type of a query tree are equal to the
+ object and event given in the <code class="command">CREATE RULE</code> command.
+ For update rules, the rule system creates a list of query trees.
+ Initially the query-tree list is empty.
+ There can be zero (<code class="literal">NOTHING</code> key word), one, or multiple actions.
+ To simplify, we will look at a rule with one action. This rule
+ can have a qualification or not and it can be <code class="literal">INSTEAD</code> or
+ <code class="literal">ALSO</code> (the default).
+</p><p>
+ What is a rule qualification? It is a restriction that tells
+ when the actions of the rule should be done and when not. This
+ qualification can only reference the pseudorelations <code class="literal">NEW</code> and/or <code class="literal">OLD</code>,
+ which basically represent the relation that was given as object (but with a
+ special meaning).
+</p><p>
+ So we have three cases that produce the following query trees for
+ a one-action rule.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">No qualification, with either <code class="literal">ALSO</code> or
+ <code class="literal">INSTEAD</code></span></dt><dd><p>
+ the query tree from the rule action with the original query
+ tree's qualification added
+ </p></dd><dt><span class="term">Qualification given and <code class="literal">ALSO</code></span></dt><dd><p>
+ the query tree from the rule action with the rule
+ qualification and the original query tree's qualification
+ added
+ </p></dd><dt><span class="term">Qualification given and <code class="literal">INSTEAD</code></span></dt><dd><p>
+ the query tree from the rule action with the rule
+ qualification and the original query tree's qualification; and
+ the original query tree with the negated rule qualification
+ added
+ </p></dd></dl></div><p>
+
+ Finally, if the rule is <code class="literal">ALSO</code>, the unchanged original query tree is
+ added to the list. Since only qualified <code class="literal">INSTEAD</code> rules already add the
+ original query tree, we end up with either one or two output query trees
+ for a rule with one action.
+</p><p>
+ For <code class="literal">ON INSERT</code> rules, the original query (if not suppressed by <code class="literal">INSTEAD</code>)
+ is done before any actions added by rules. This allows the actions to
+ see the inserted row(s). But for <code class="literal">ON UPDATE</code> and <code class="literal">ON
+ DELETE</code> rules, the original query is done after the actions added by rules.
+ This ensures that the actions can see the to-be-updated or to-be-deleted
+ rows; otherwise, the actions might do nothing because they find no rows
+ matching their qualifications.
+</p><p>
+ The query trees generated from rule actions are thrown into the
+ rewrite system again, and maybe more rules get applied resulting
+ in additional or fewer query trees.
+ So a rule's actions must have either a different
+ command type or a different result relation than the rule itself is
+ on, otherwise this recursive process will end up in an infinite loop.
+ (Recursive expansion of a rule will be detected and reported as an
+ error.)
+</p><p>
+ The query trees found in the actions of the
+ <code class="structname">pg_rewrite</code> system catalog are only
+ templates. Since they can reference the range-table entries for
+ <code class="literal">NEW</code> and <code class="literal">OLD</code>, some substitutions have to be made before they can be
+ used. For any reference to <code class="literal">NEW</code>, the target list of the original
+ query is searched for a corresponding entry. If found, that
+ entry's expression replaces the reference. Otherwise, <code class="literal">NEW</code> means the
+ same as <code class="literal">OLD</code> (for an <code class="command">UPDATE</code>) or is replaced by
+ a null value (for an <code class="command">INSERT</code>). Any reference to <code class="literal">OLD</code> is
+ replaced by a reference to the range-table entry that is the
+ result relation.
+</p><p>
+ After the system is done applying update rules, it applies view rules to the
+ produced query tree(s). Views cannot insert new update actions so
+ there is no need to apply update rules to the output of view rewriting.
+</p><div class="sect3" id="id-1.8.6.9.7.10"><div class="titlepage"><div><div><h4 class="title">41.4.1.1. A First Rule Step by Step</h4></div></div></div><p>
+ Say we want to trace changes to the <code class="literal">sl_avail</code> column in the
+ <code class="literal">shoelace_data</code> relation. So we set up a log table
+ and a rule that conditionally writes a log entry when an
+ <code class="command">UPDATE</code> is performed on
+ <code class="literal">shoelace_data</code>.
+
+</p><pre class="programlisting">
+CREATE TABLE shoelace_log (
+ sl_name text, -- shoelace changed
+ sl_avail integer, -- new available value
+ log_who text, -- who did it
+ log_when timestamp -- when
+);
+
+CREATE RULE log_shoelace AS ON UPDATE TO shoelace_data
+ WHERE NEW.sl_avail &lt;&gt; OLD.sl_avail
+ DO INSERT INTO shoelace_log VALUES (
+ NEW.sl_name,
+ NEW.sl_avail,
+ current_user,
+ current_timestamp
+ );
+</pre><p>
+</p><p>
+ Now someone does:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data SET sl_avail = 6 WHERE sl_name = 'sl7';
+</pre><p>
+
+ and we look at the log table:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace_log;
+
+ sl_name | sl_avail | log_who | log_when
+---------+----------+---------+----------------------------------
+ sl7 | 6 | Al | Tue Oct 20 16:14:45 1998 MET DST
+(1 row)
+</pre><p>
+ </p><p>
+ That's what we expected. What happened in the background is the following.
+ The parser created the query tree:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data SET sl_avail = 6
+ FROM shoelace_data shoelace_data
+ WHERE shoelace_data.sl_name = 'sl7';
+</pre><p>
+
+ There is a rule <code class="literal">log_shoelace</code> that is <code class="literal">ON UPDATE</code> with the rule
+ qualification expression:
+
+</p><pre class="programlisting">
+NEW.sl_avail &lt;&gt; OLD.sl_avail
+</pre><p>
+
+ and the action:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ new.sl_name, new.sl_avail,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old;
+</pre><p>
+
+ (This looks a little strange since you cannot normally write
+ <code class="literal">INSERT ... VALUES ... FROM</code>. The <code class="literal">FROM</code>
+ clause here is just to indicate that there are range-table entries
+ in the query tree for <code class="literal">new</code> and <code class="literal">old</code>.
+ These are needed so that they can be referenced by variables in
+ the <code class="command">INSERT</code> command's query tree.)
+</p><p>
+ The rule is a qualified <code class="literal">ALSO</code> rule, so the rule system
+ has to return two query trees: the modified rule action and the original
+ query tree. In step 1, the range table of the original query is
+ incorporated into the rule's action query tree. This results in:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ new.sl_name, new.sl_avail,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old,
+ <span class="emphasis"><strong>shoelace_data shoelace_data</strong></span>;
+</pre><p>
+
+ In step 2, the rule qualification is added to it, so the result set
+ is restricted to rows where <code class="literal">sl_avail</code> changes:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ new.sl_name, new.sl_avail,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old,
+ shoelace_data shoelace_data
+ <span class="emphasis"><strong>WHERE new.sl_avail &lt;&gt; old.sl_avail</strong></span>;
+</pre><p>
+
+ (This looks even stranger, since <code class="literal">INSERT ... VALUES</code> doesn't have
+ a <code class="literal">WHERE</code> clause either, but the planner and executor will have no
+ difficulty with it. They need to support this same functionality
+ anyway for <code class="literal">INSERT ... SELECT</code>.)
+ </p><p>
+ In step 3, the original query tree's qualification is added,
+ restricting the result set further to only the rows that would have been touched
+ by the original query:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ new.sl_name, new.sl_avail,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old,
+ shoelace_data shoelace_data
+ WHERE new.sl_avail &lt;&gt; old.sl_avail
+ <span class="emphasis"><strong>AND shoelace_data.sl_name = 'sl7'</strong></span>;
+</pre><p>
+ </p><p>
+ Step 4 replaces references to <code class="literal">NEW</code> by the target list entries from the
+ original query tree or by the matching variable references
+ from the result relation:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ <span class="emphasis"><strong>shoelace_data.sl_name</strong></span>, <span class="emphasis"><strong>6</strong></span>,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old,
+ shoelace_data shoelace_data
+ WHERE <span class="emphasis"><strong>6</strong></span> &lt;&gt; old.sl_avail
+ AND shoelace_data.sl_name = 'sl7';
+</pre><p>
+
+ </p><p>
+ Step 5 changes <code class="literal">OLD</code> references into result relation references:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ shoelace_data.sl_name, 6,
+ current_user, current_timestamp )
+ FROM shoelace_data new, shoelace_data old,
+ shoelace_data shoelace_data
+ WHERE 6 &lt;&gt; <span class="emphasis"><strong>shoelace_data.sl_avail</strong></span>
+ AND shoelace_data.sl_name = 'sl7';
+</pre><p>
+ </p><p>
+ That's it. Since the rule is <code class="literal">ALSO</code>, we also output the
+ original query tree. In short, the output from the rule system
+ is a list of two query trees that correspond to these statements:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ shoelace_data.sl_name, 6,
+ current_user, current_timestamp )
+ FROM shoelace_data
+ WHERE 6 &lt;&gt; shoelace_data.sl_avail
+ AND shoelace_data.sl_name = 'sl7';
+
+UPDATE shoelace_data SET sl_avail = 6
+ WHERE sl_name = 'sl7';
+</pre><p>
+
+ These are executed in this order, and that is exactly what
+ the rule was meant to do.
+ </p><p>
+ The substitutions and the added qualifications
+ ensure that, if the original query would be, say:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data SET sl_color = 'green'
+ WHERE sl_name = 'sl7';
+</pre><p>
+
+ no log entry would get written. In that case, the original query
+ tree does not contain a target list entry for
+ <code class="literal">sl_avail</code>, so <code class="literal">NEW.sl_avail</code> will get
+ replaced by <code class="literal">shoelace_data.sl_avail</code>. Thus, the extra
+ command generated by the rule is:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log VALUES (
+ shoelace_data.sl_name, <span class="emphasis"><strong>shoelace_data.sl_avail</strong></span>,
+ current_user, current_timestamp )
+ FROM shoelace_data
+ WHERE <span class="emphasis"><strong>shoelace_data.sl_avail</strong></span> &lt;&gt; shoelace_data.sl_avail
+ AND shoelace_data.sl_name = 'sl7';
+</pre><p>
+
+ and that qualification will never be true.
+ </p><p>
+ It will also work if the original query modifies multiple rows. So
+ if someone issued the command:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data SET sl_avail = 0
+ WHERE sl_color = 'black';
+</pre><p>
+
+ four rows in fact get updated (<code class="literal">sl1</code>, <code class="literal">sl2</code>, <code class="literal">sl3</code>, and <code class="literal">sl4</code>).
+ But <code class="literal">sl3</code> already has <code class="literal">sl_avail = 0</code>. In this case, the original
+ query trees qualification is different and that results
+ in the extra query tree:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log
+SELECT shoelace_data.sl_name, 0,
+ current_user, current_timestamp
+ FROM shoelace_data
+ WHERE 0 &lt;&gt; shoelace_data.sl_avail
+ AND <span class="emphasis"><strong>shoelace_data.sl_color = 'black'</strong></span>;
+</pre><p>
+
+ being generated by the rule. This query tree will surely insert
+ three new log entries. And that's absolutely correct.
+</p><p>
+ Here we can see why it is important that the original query tree
+ is executed last. If the <code class="command">UPDATE</code> had been
+ executed first, all the rows would have already been set to zero, so the
+ logging <code class="command">INSERT</code> would not find any row where
+ <code class="literal">0 &lt;&gt; shoelace_data.sl_avail</code>.
+</p></div></div><div class="sect2" id="RULES-UPDATE-VIEWS"><div class="titlepage"><div><div><h3 class="title">41.4.2. Cooperation with Views</h3></div></div></div><a id="id-1.8.6.9.8.2" class="indexterm"></a><p>
+ A simple way to protect view relations from the mentioned
+ possibility that someone can try to run <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, or <code class="command">DELETE</code> on them is
+ to let those query trees get thrown away. So we could create the rules:
+
+</p><pre class="programlisting">
+CREATE RULE shoe_ins_protect AS ON INSERT TO shoe
+ DO INSTEAD NOTHING;
+CREATE RULE shoe_upd_protect AS ON UPDATE TO shoe
+ DO INSTEAD NOTHING;
+CREATE RULE shoe_del_protect AS ON DELETE TO shoe
+ DO INSTEAD NOTHING;
+</pre><p>
+
+ If someone now tries to do any of these operations on the view
+ relation <code class="literal">shoe</code>, the rule system will
+ apply these rules. Since the rules have
+ no actions and are <code class="literal">INSTEAD</code>, the resulting list of
+ query trees will be empty and the whole query will become
+ nothing because there is nothing left to be optimized or
+ executed after the rule system is done with it.
+</p><p>
+ A more sophisticated way to use the rule system is to
+ create rules that rewrite the query tree into one that
+ does the right operation on the real tables. To do that
+ on the <code class="literal">shoelace</code> view, we create
+ the following rules:
+
+</p><pre class="programlisting">
+CREATE RULE shoelace_ins AS ON INSERT TO shoelace
+ DO INSTEAD
+ INSERT INTO shoelace_data VALUES (
+ NEW.sl_name,
+ NEW.sl_avail,
+ NEW.sl_color,
+ NEW.sl_len,
+ NEW.sl_unit
+ );
+
+CREATE RULE shoelace_upd AS ON UPDATE TO shoelace
+ DO INSTEAD
+ UPDATE shoelace_data
+ SET sl_name = NEW.sl_name,
+ sl_avail = NEW.sl_avail,
+ sl_color = NEW.sl_color,
+ sl_len = NEW.sl_len,
+ sl_unit = NEW.sl_unit
+ WHERE sl_name = OLD.sl_name;
+
+CREATE RULE shoelace_del AS ON DELETE TO shoelace
+ DO INSTEAD
+ DELETE FROM shoelace_data
+ WHERE sl_name = OLD.sl_name;
+</pre><p>
+ </p><p>
+ If you want to support <code class="literal">RETURNING</code> queries on the view,
+ you need to make the rules include <code class="literal">RETURNING</code> clauses that
+ compute the view rows. This is usually pretty trivial for views on a
+ single table, but it's a bit tedious for join views such as
+ <code class="literal">shoelace</code>. An example for the insert case is:
+
+</p><pre class="programlisting">
+CREATE RULE shoelace_ins AS ON INSERT TO shoelace
+ DO INSTEAD
+ INSERT INTO shoelace_data VALUES (
+ NEW.sl_name,
+ NEW.sl_avail,
+ NEW.sl_color,
+ NEW.sl_len,
+ NEW.sl_unit
+ )
+ RETURNING
+ shoelace_data.*,
+ (SELECT shoelace_data.sl_len * u.un_fact
+ FROM unit u WHERE shoelace_data.sl_unit = u.un_name);
+</pre><p>
+
+ Note that this one rule supports both <code class="command">INSERT</code> and
+ <code class="command">INSERT RETURNING</code> queries on the view — the
+ <code class="literal">RETURNING</code> clause is simply ignored for <code class="command">INSERT</code>.
+ </p><p>
+ Now assume that once in a while, a pack of shoelaces arrives at
+ the shop and a big parts list along with it. But you don't want
+ to manually update the <code class="literal">shoelace</code> view every
+ time. Instead we set up two little tables: one where you can
+ insert the items from the part list, and one with a special
+ trick. The creation commands for these are:
+
+</p><pre class="programlisting">
+CREATE TABLE shoelace_arrive (
+ arr_name text,
+ arr_quant integer
+);
+
+CREATE TABLE shoelace_ok (
+ ok_name text,
+ ok_quant integer
+);
+
+CREATE RULE shoelace_ok_ins AS ON INSERT TO shoelace_ok
+ DO INSTEAD
+ UPDATE shoelace
+ SET sl_avail = sl_avail + NEW.ok_quant
+ WHERE sl_name = NEW.ok_name;
+</pre><p>
+
+ Now you can fill the table <code class="literal">shoelace_arrive</code> with
+ the data from the parts list:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace_arrive;
+
+ arr_name | arr_quant
+----------+-----------
+ sl3 | 10
+ sl6 | 20
+ sl8 | 20
+(3 rows)
+</pre><p>
+
+ Take a quick look at the current data:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace;
+
+ sl_name | sl_avail | sl_color | sl_len | sl_unit | sl_len_cm
+----------+----------+----------+--------+---------+-----------
+ sl1 | 5 | black | 80 | cm | 80
+ sl2 | 6 | black | 100 | cm | 100
+ sl7 | 6 | brown | 60 | cm | 60
+ sl3 | 0 | black | 35 | inch | 88.9
+ sl4 | 8 | black | 40 | inch | 101.6
+ sl8 | 1 | brown | 40 | inch | 101.6
+ sl5 | 4 | brown | 1 | m | 100
+ sl6 | 0 | brown | 0.9 | m | 90
+(8 rows)
+</pre><p>
+
+ Now move the arrived shoelaces in:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_ok SELECT * FROM shoelace_arrive;
+</pre><p>
+
+ and check the results:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace ORDER BY sl_name;
+
+ sl_name | sl_avail | sl_color | sl_len | sl_unit | sl_len_cm
+----------+----------+----------+--------+---------+-----------
+ sl1 | 5 | black | 80 | cm | 80
+ sl2 | 6 | black | 100 | cm | 100
+ sl7 | 6 | brown | 60 | cm | 60
+ sl4 | 8 | black | 40 | inch | 101.6
+ sl3 | 10 | black | 35 | inch | 88.9
+ sl8 | 21 | brown | 40 | inch | 101.6
+ sl5 | 4 | brown | 1 | m | 100
+ sl6 | 20 | brown | 0.9 | m | 90
+(8 rows)
+
+SELECT * FROM shoelace_log;
+
+ sl_name | sl_avail | log_who| log_when
+---------+----------+--------+----------------------------------
+ sl7 | 6 | Al | Tue Oct 20 19:14:45 1998 MET DST
+ sl3 | 10 | Al | Tue Oct 20 19:25:16 1998 MET DST
+ sl6 | 20 | Al | Tue Oct 20 19:25:16 1998 MET DST
+ sl8 | 21 | Al | Tue Oct 20 19:25:16 1998 MET DST
+(4 rows)
+</pre><p>
+ </p><p>
+ It's a long way from the one <code class="literal">INSERT ... SELECT</code>
+ to these results. And the description of the query-tree
+ transformation will be the last in this chapter. First, there is
+ the parser's output:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_ok
+SELECT shoelace_arrive.arr_name, shoelace_arrive.arr_quant
+ FROM shoelace_arrive shoelace_arrive, shoelace_ok shoelace_ok;
+</pre><p>
+
+ Now the first rule <code class="literal">shoelace_ok_ins</code> is applied and turns this
+ into:
+
+</p><pre class="programlisting">
+UPDATE shoelace
+ SET sl_avail = shoelace.sl_avail + shoelace_arrive.arr_quant
+ FROM shoelace_arrive shoelace_arrive, shoelace_ok shoelace_ok,
+ shoelace_ok old, shoelace_ok new,
+ shoelace shoelace
+ WHERE shoelace.sl_name = shoelace_arrive.arr_name;
+</pre><p>
+
+ and throws away the original <code class="command">INSERT</code> on
+ <code class="literal">shoelace_ok</code>. This rewritten query is passed to
+ the rule system again, and the second applied rule
+ <code class="literal">shoelace_upd</code> produces:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data
+ SET sl_name = shoelace.sl_name,
+ sl_avail = shoelace.sl_avail + shoelace_arrive.arr_quant,
+ sl_color = shoelace.sl_color,
+ sl_len = shoelace.sl_len,
+ sl_unit = shoelace.sl_unit
+ FROM shoelace_arrive shoelace_arrive, shoelace_ok shoelace_ok,
+ shoelace_ok old, shoelace_ok new,
+ shoelace shoelace, shoelace old,
+ shoelace new, shoelace_data shoelace_data
+ WHERE shoelace.sl_name = shoelace_arrive.arr_name
+ AND shoelace_data.sl_name = shoelace.sl_name;
+</pre><p>
+
+ Again it's an <code class="literal">INSTEAD</code> rule and the previous query tree is trashed.
+ Note that this query still uses the view <code class="literal">shoelace</code>.
+ But the rule system isn't finished with this step, so it continues
+ and applies the <code class="literal">_RETURN</code> rule on it, and we get:
+
+</p><pre class="programlisting">
+UPDATE shoelace_data
+ SET sl_name = s.sl_name,
+ sl_avail = s.sl_avail + shoelace_arrive.arr_quant,
+ sl_color = s.sl_color,
+ sl_len = s.sl_len,
+ sl_unit = s.sl_unit
+ FROM shoelace_arrive shoelace_arrive, shoelace_ok shoelace_ok,
+ shoelace_ok old, shoelace_ok new,
+ shoelace shoelace, shoelace old,
+ shoelace new, shoelace_data shoelace_data,
+ shoelace old, shoelace new,
+ shoelace_data s, unit u
+ WHERE s.sl_name = shoelace_arrive.arr_name
+ AND shoelace_data.sl_name = s.sl_name;
+</pre><p>
+
+ Finally, the rule <code class="literal">log_shoelace</code> gets applied,
+ producing the extra query tree:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log
+SELECT s.sl_name,
+ s.sl_avail + shoelace_arrive.arr_quant,
+ current_user,
+ current_timestamp
+ FROM shoelace_arrive shoelace_arrive, shoelace_ok shoelace_ok,
+ shoelace_ok old, shoelace_ok new,
+ shoelace shoelace, shoelace old,
+ shoelace new, shoelace_data shoelace_data,
+ shoelace old, shoelace new,
+ shoelace_data s, unit u,
+ shoelace_data old, shoelace_data new
+ shoelace_log shoelace_log
+ WHERE s.sl_name = shoelace_arrive.arr_name
+ AND shoelace_data.sl_name = s.sl_name
+ AND (s.sl_avail + shoelace_arrive.arr_quant) &lt;&gt; s.sl_avail;
+</pre><p>
+
+ After that the rule system runs out of rules and returns the
+ generated query trees.
+ </p><p>
+ So we end up with two final query trees that are equivalent to the
+ <acronym class="acronym">SQL</acronym> statements:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace_log
+SELECT s.sl_name,
+ s.sl_avail + shoelace_arrive.arr_quant,
+ current_user,
+ current_timestamp
+ FROM shoelace_arrive shoelace_arrive, shoelace_data shoelace_data,
+ shoelace_data s
+ WHERE s.sl_name = shoelace_arrive.arr_name
+ AND shoelace_data.sl_name = s.sl_name
+ AND s.sl_avail + shoelace_arrive.arr_quant &lt;&gt; s.sl_avail;
+
+UPDATE shoelace_data
+ SET sl_avail = shoelace_data.sl_avail + shoelace_arrive.arr_quant
+ FROM shoelace_arrive shoelace_arrive,
+ shoelace_data shoelace_data,
+ shoelace_data s
+ WHERE s.sl_name = shoelace_arrive.sl_name
+ AND shoelace_data.sl_name = s.sl_name;
+</pre><p>
+
+ The result is that data coming from one relation inserted into another,
+ changed into updates on a third, changed into updating
+ a fourth plus logging that final update in a fifth
+ gets reduced into two queries.
+</p><p>
+ There is a little detail that's a bit ugly. Looking at the two
+ queries, it turns out that the <code class="literal">shoelace_data</code>
+ relation appears twice in the range table where it could
+ definitely be reduced to one. The planner does not handle it and
+ so the execution plan for the rule systems output of the
+ <code class="command">INSERT</code> will be
+
+</p><pre class="literallayout">
+Nested Loop
+ -&gt; Merge Join
+ -&gt; Seq Scan
+ -&gt; Sort
+ -&gt; Seq Scan on s
+ -&gt; Seq Scan
+ -&gt; Sort
+ -&gt; Seq Scan on shoelace_arrive
+ -&gt; Seq Scan on shoelace_data
+</pre><p>
+
+ while omitting the extra range table entry would result in a
+
+</p><pre class="literallayout">
+Merge Join
+ -&gt; Seq Scan
+ -&gt; Sort
+ -&gt; Seq Scan on s
+ -&gt; Seq Scan
+ -&gt; Sort
+ -&gt; Seq Scan on shoelace_arrive
+</pre><p>
+
+ which produces exactly the same entries in the log table. Thus,
+ the rule system caused one extra scan on the table
+ <code class="literal">shoelace_data</code> that is absolutely not
+ necessary. And the same redundant scan is done once more in the
+ <code class="command">UPDATE</code>. But it was a really hard job to make
+ that all possible at all.
+</p><p>
+ Now we make a final demonstration of the
+ <span class="productname">PostgreSQL</span> rule system and its power.
+ Say you add some shoelaces with extraordinary colors to your
+ database:
+
+</p><pre class="programlisting">
+INSERT INTO shoelace VALUES ('sl9', 0, 'pink', 35.0, 'inch', 0.0);
+INSERT INTO shoelace VALUES ('sl10', 1000, 'magenta', 40.0, 'inch', 0.0);
+</pre><p>
+
+ We would like to make a view to check which
+ <code class="literal">shoelace</code> entries do not fit any shoe in color.
+ The view for this is:
+
+</p><pre class="programlisting">
+CREATE VIEW shoelace_mismatch AS
+ SELECT * FROM shoelace WHERE NOT EXISTS
+ (SELECT shoename FROM shoe WHERE slcolor = sl_color);
+</pre><p>
+
+ Its output is:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace_mismatch;
+
+ sl_name | sl_avail | sl_color | sl_len | sl_unit | sl_len_cm
+---------+----------+----------+--------+---------+-----------
+ sl9 | 0 | pink | 35 | inch | 88.9
+ sl10 | 1000 | magenta | 40 | inch | 101.6
+</pre><p>
+ </p><p>
+ Now we want to set it up so that mismatching shoelaces that are
+ not in stock are deleted from the database.
+ To make it a little harder for <span class="productname">PostgreSQL</span>,
+ we don't delete it directly. Instead we create one more view:
+
+</p><pre class="programlisting">
+CREATE VIEW shoelace_can_delete AS
+ SELECT * FROM shoelace_mismatch WHERE sl_avail = 0;
+</pre><p>
+
+ and do it this way:
+
+</p><pre class="programlisting">
+DELETE FROM shoelace WHERE EXISTS
+ (SELECT * FROM shoelace_can_delete
+ WHERE sl_name = shoelace.sl_name);
+</pre><p>
+
+ The results are:
+
+</p><pre class="programlisting">
+SELECT * FROM shoelace;
+
+ sl_name | sl_avail | sl_color | sl_len | sl_unit | sl_len_cm
+---------+----------+----------+--------+---------+-----------
+ sl1 | 5 | black | 80 | cm | 80
+ sl2 | 6 | black | 100 | cm | 100
+ sl7 | 6 | brown | 60 | cm | 60
+ sl4 | 8 | black | 40 | inch | 101.6
+ sl3 | 10 | black | 35 | inch | 88.9
+ sl8 | 21 | brown | 40 | inch | 101.6
+ sl10 | 1000 | magenta | 40 | inch | 101.6
+ sl5 | 4 | brown | 1 | m | 100
+ sl6 | 20 | brown | 0.9 | m | 90
+(9 rows)
+</pre><p>
+ </p><p>
+ A <code class="command">DELETE</code> on a view, with a subquery qualification that
+ in total uses 4 nesting/joined views, where one of them
+ itself has a subquery qualification containing a view
+ and where calculated view columns are used,
+ gets rewritten into
+ one single query tree that deletes the requested data
+ from a real table.
+</p><p>
+ There are probably only a few situations out in the real world
+ where such a construct is necessary. But it makes you feel
+ comfortable that it works.
+</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-materializedviews.html" title="41.3. Materialized Views">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-privileges.html" title="41.5. Rules and Privileges">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.3. Materialized Views </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.5. Rules and Privileges</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules-views.html b/doc/src/sgml/html/rules-views.html
new file mode 100644
index 0000000..41bb926
--- /dev/null
+++ b/doc/src/sgml/html/rules-views.html
@@ -0,0 +1,506 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.2. Views and the Rule System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="querytree.html" title="41.1. The Query Tree" /><link rel="next" href="rules-materializedviews.html" title="41.3. Materialized Views" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.2. Views and the Rule System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="querytree.html" title="41.1. The Query Tree">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><th width="60%" align="center">Chapter 41. The Rule System</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="rules-materializedviews.html" title="41.3. Materialized Views">Next</a></td></tr></table><hr /></div><div class="sect1" id="RULES-VIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.2. Views and the Rule System</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="rules-views.html#RULES-SELECT">41.2.1. How <code class="command">SELECT</code> Rules Work</a></span></dt><dt><span class="sect2"><a href="rules-views.html#id-1.8.6.7.6">41.2.2. View Rules in Non-<code class="command">SELECT</code> Statements</a></span></dt><dt><span class="sect2"><a href="rules-views.html#id-1.8.6.7.7">41.2.3. The Power of Views in <span class="productname">PostgreSQL</span></a></span></dt><dt><span class="sect2"><a href="rules-views.html#RULES-VIEWS-UPDATE">41.2.4. Updating a View</a></span></dt></dl></div><a id="id-1.8.6.7.2" class="indexterm"></a><a id="id-1.8.6.7.3" class="indexterm"></a><p>
+ Views in <span class="productname">PostgreSQL</span> are implemented
+ using the rule system. In fact, there is essentially no difference
+ between:
+
+</p><pre class="programlisting">
+CREATE VIEW myview AS SELECT * FROM mytab;
+</pre><p>
+
+ compared against the two commands:
+
+</p><pre class="programlisting">
+CREATE TABLE myview (<em class="replaceable"><code>same column list as mytab</code></em>);
+CREATE RULE "_RETURN" AS ON SELECT TO myview DO INSTEAD
+ SELECT * FROM mytab;
+</pre><p>
+
+ because this is exactly what the <code class="command">CREATE VIEW</code>
+ command does internally. This has some side effects. One of them
+ is that the information about a view in the
+ <span class="productname">PostgreSQL</span> system catalogs is exactly
+ the same as it is for a table. So for the parser, there is
+ absolutely no difference between a table and a view. They are the
+ same thing: relations.
+</p><div class="sect2" id="RULES-SELECT"><div class="titlepage"><div><div><h3 class="title">41.2.1. How <code class="command">SELECT</code> Rules Work</h3></div></div></div><a id="id-1.8.6.7.5.2" class="indexterm"></a><p>
+ Rules <code class="literal">ON SELECT</code> are applied to all queries as the last step, even
+ if the command given is an <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code> or <code class="command">DELETE</code>. And they
+ have different semantics from rules on the other command types in that they modify the
+ query tree in place instead of creating a new one. So
+ <code class="command">SELECT</code> rules are described first.
+</p><p>
+ Currently, there can be only one action in an <code class="literal">ON SELECT</code> rule, and it must
+ be an unconditional <code class="command">SELECT</code> action that is <code class="literal">INSTEAD</code>. This restriction was
+ required to make rules safe enough to open them for ordinary users, and
+ it restricts <code class="literal">ON SELECT</code> rules to act like views.
+</p><p>
+ The examples for this chapter are two join views that do some
+ calculations and some more views using them in turn. One of the
+ two first views is customized later by adding rules for
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> operations so that the final result will
+ be a view that behaves like a real table with some magic
+ functionality. This is not such a simple example to start from and
+ this makes things harder to get into. But it's better to have one
+ example that covers all the points discussed step by step rather
+ than having many different ones that might mix up in mind.
+</p><p>
+ The real tables we need in the first two rule system descriptions
+ are these:
+
+</p><pre class="programlisting">
+CREATE TABLE shoe_data (
+ shoename text, -- primary key
+ sh_avail integer, -- available number of pairs
+ slcolor text, -- preferred shoelace color
+ slminlen real, -- minimum shoelace length
+ slmaxlen real, -- maximum shoelace length
+ slunit text -- length unit
+);
+
+CREATE TABLE shoelace_data (
+ sl_name text, -- primary key
+ sl_avail integer, -- available number of pairs
+ sl_color text, -- shoelace color
+ sl_len real, -- shoelace length
+ sl_unit text -- length unit
+);
+
+CREATE TABLE unit (
+ un_name text, -- primary key
+ un_fact real -- factor to transform to cm
+);
+</pre><p>
+
+ As you can see, they represent shoe-store data.
+</p><p>
+ The views are created as:
+
+</p><pre class="programlisting">
+CREATE VIEW shoe AS
+ SELECT sh.shoename,
+ sh.sh_avail,
+ sh.slcolor,
+ sh.slminlen,
+ sh.slminlen * un.un_fact AS slminlen_cm,
+ sh.slmaxlen,
+ sh.slmaxlen * un.un_fact AS slmaxlen_cm,
+ sh.slunit
+ FROM shoe_data sh, unit un
+ WHERE sh.slunit = un.un_name;
+
+CREATE VIEW shoelace AS
+ SELECT s.sl_name,
+ s.sl_avail,
+ s.sl_color,
+ s.sl_len,
+ s.sl_unit,
+ s.sl_len * u.un_fact AS sl_len_cm
+ FROM shoelace_data s, unit u
+ WHERE s.sl_unit = u.un_name;
+
+CREATE VIEW shoe_ready AS
+ SELECT rsh.shoename,
+ rsh.sh_avail,
+ rsl.sl_name,
+ rsl.sl_avail,
+ least(rsh.sh_avail, rsl.sl_avail) AS total_avail
+ FROM shoe rsh, shoelace rsl
+ WHERE rsl.sl_color = rsh.slcolor
+ AND rsl.sl_len_cm &gt;= rsh.slminlen_cm
+ AND rsl.sl_len_cm &lt;= rsh.slmaxlen_cm;
+</pre><p>
+
+ The <code class="command">CREATE VIEW</code> command for the
+ <code class="literal">shoelace</code> view (which is the simplest one we
+ have) will create a relation <code class="literal">shoelace</code> and an entry in
+ <code class="structname">pg_rewrite</code> that tells that there is a
+ rewrite rule that must be applied whenever the relation <code class="literal">shoelace</code>
+ is referenced in a query's range table. The rule has no rule
+ qualification (discussed later, with the non-<code class="command">SELECT</code> rules, since
+ <code class="command">SELECT</code> rules currently cannot have them) and it is <code class="literal">INSTEAD</code>. Note
+ that rule qualifications are not the same as query qualifications.
+ The action of our rule has a query qualification.
+ The action of the rule is one query tree that is a copy of the
+ <code class="command">SELECT</code> statement in the view creation command.
+</p><div class="note"><h3 class="title">Note</h3><p>
+ The two extra range
+ table entries for <code class="literal">NEW</code> and <code class="literal">OLD</code> that you can see in
+ the <code class="structname">pg_rewrite</code> entry aren't of interest
+ for <code class="command">SELECT</code> rules.
+ </p></div><p>
+ Now we populate <code class="literal">unit</code>, <code class="literal">shoe_data</code>
+ and <code class="literal">shoelace_data</code> and run a simple query on a view:
+
+</p><pre class="programlisting">
+INSERT INTO unit VALUES ('cm', 1.0);
+INSERT INTO unit VALUES ('m', 100.0);
+INSERT INTO unit VALUES ('inch', 2.54);
+
+INSERT INTO shoe_data VALUES ('sh1', 2, 'black', 70.0, 90.0, 'cm');
+INSERT INTO shoe_data VALUES ('sh2', 0, 'black', 30.0, 40.0, 'inch');
+INSERT INTO shoe_data VALUES ('sh3', 4, 'brown', 50.0, 65.0, 'cm');
+INSERT INTO shoe_data VALUES ('sh4', 3, 'brown', 40.0, 50.0, 'inch');
+
+INSERT INTO shoelace_data VALUES ('sl1', 5, 'black', 80.0, 'cm');
+INSERT INTO shoelace_data VALUES ('sl2', 6, 'black', 100.0, 'cm');
+INSERT INTO shoelace_data VALUES ('sl3', 0, 'black', 35.0 , 'inch');
+INSERT INTO shoelace_data VALUES ('sl4', 8, 'black', 40.0 , 'inch');
+INSERT INTO shoelace_data VALUES ('sl5', 4, 'brown', 1.0 , 'm');
+INSERT INTO shoelace_data VALUES ('sl6', 0, 'brown', 0.9 , 'm');
+INSERT INTO shoelace_data VALUES ('sl7', 7, 'brown', 60 , 'cm');
+INSERT INTO shoelace_data VALUES ('sl8', 1, 'brown', 40 , 'inch');
+
+SELECT * FROM shoelace;
+
+ sl_name | sl_avail | sl_color | sl_len | sl_unit | sl_len_cm
+-----------+----------+----------+--------+---------+-----------
+ sl1 | 5 | black | 80 | cm | 80
+ sl2 | 6 | black | 100 | cm | 100
+ sl7 | 7 | brown | 60 | cm | 60
+ sl3 | 0 | black | 35 | inch | 88.9
+ sl4 | 8 | black | 40 | inch | 101.6
+ sl8 | 1 | brown | 40 | inch | 101.6
+ sl5 | 4 | brown | 1 | m | 100
+ sl6 | 0 | brown | 0.9 | m | 90
+(8 rows)
+</pre><p>
+ </p><p>
+ This is the simplest <code class="command">SELECT</code> you can do on our
+ views, so we take this opportunity to explain the basics of view
+ rules. The <code class="literal">SELECT * FROM shoelace</code> was
+ interpreted by the parser and produced the query tree:
+
+</p><pre class="programlisting">
+SELECT shoelace.sl_name, shoelace.sl_avail,
+ shoelace.sl_color, shoelace.sl_len,
+ shoelace.sl_unit, shoelace.sl_len_cm
+ FROM shoelace shoelace;
+</pre><p>
+
+ and this is given to the rule system. The rule system walks through the
+ range table and checks if there are rules
+ for any relation. When processing the range table entry for
+ <code class="literal">shoelace</code> (the only one up to now) it finds the
+ <code class="literal">_RETURN</code> rule with the query tree:
+
+</p><pre class="programlisting">
+SELECT s.sl_name, s.sl_avail,
+ s.sl_color, s.sl_len, s.sl_unit,
+ s.sl_len * u.un_fact AS sl_len_cm
+ FROM shoelace old, shoelace new,
+ shoelace_data s, unit u
+ WHERE s.sl_unit = u.un_name;
+</pre><p>
+</p><p>
+ To expand the view, the rewriter simply creates a subquery range-table
+ entry containing the rule's action query tree, and substitutes this
+ range table entry for the original one that referenced the view. The
+ resulting rewritten query tree is almost the same as if you had typed:
+
+</p><pre class="programlisting">
+SELECT shoelace.sl_name, shoelace.sl_avail,
+ shoelace.sl_color, shoelace.sl_len,
+ shoelace.sl_unit, shoelace.sl_len_cm
+ FROM (SELECT s.sl_name,
+ s.sl_avail,
+ s.sl_color,
+ s.sl_len,
+ s.sl_unit,
+ s.sl_len * u.un_fact AS sl_len_cm
+ FROM shoelace_data s, unit u
+ WHERE s.sl_unit = u.un_name) shoelace;
+</pre><p>
+
+ There is one difference however: the subquery's range table has two
+ extra entries <code class="literal">shoelace old</code> and <code class="literal">shoelace new</code>. These entries don't
+ participate directly in the query, since they aren't referenced by
+ the subquery's join tree or target list. The rewriter uses them
+ to store the access privilege check information that was originally present
+ in the range-table entry that referenced the view. In this way, the
+ executor will still check that the user has proper privileges to access
+ the view, even though there's no direct use of the view in the rewritten
+ query.
+</p><p>
+ That was the first rule applied. The rule system will continue checking
+ the remaining range-table entries in the top query (in this example there
+ are no more), and it will recursively check the range-table entries in
+ the added subquery to see if any of them reference views. (But it
+ won't expand <code class="literal">old</code> or <code class="literal">new</code> — otherwise we'd have infinite recursion!)
+ In this example, there are no rewrite rules for <code class="literal">shoelace_data</code> or <code class="literal">unit</code>,
+ so rewriting is complete and the above is the final result given to
+ the planner.
+</p><p>
+ Now we want to write a query that finds out for which shoes currently in the store
+ we have the matching shoelaces (color and length) and where the
+ total number of exactly matching pairs is greater than or equal to two.
+
+</p><pre class="programlisting">
+SELECT * FROM shoe_ready WHERE total_avail &gt;= 2;
+
+ shoename | sh_avail | sl_name | sl_avail | total_avail
+----------+----------+---------+----------+-------------
+ sh1 | 2 | sl1 | 5 | 2
+ sh3 | 4 | sl7 | 7 | 4
+(2 rows)
+</pre><p>
+</p><p>
+ The output of the parser this time is the query tree:
+
+</p><pre class="programlisting">
+SELECT shoe_ready.shoename, shoe_ready.sh_avail,
+ shoe_ready.sl_name, shoe_ready.sl_avail,
+ shoe_ready.total_avail
+ FROM shoe_ready shoe_ready
+ WHERE shoe_ready.total_avail &gt;= 2;
+</pre><p>
+
+ The first rule applied will be the one for the
+ <code class="literal">shoe_ready</code> view and it results in the
+ query tree:
+
+</p><pre class="programlisting">
+SELECT shoe_ready.shoename, shoe_ready.sh_avail,
+ shoe_ready.sl_name, shoe_ready.sl_avail,
+ shoe_ready.total_avail
+ FROM (SELECT rsh.shoename,
+ rsh.sh_avail,
+ rsl.sl_name,
+ rsl.sl_avail,
+ least(rsh.sh_avail, rsl.sl_avail) AS total_avail
+ FROM shoe rsh, shoelace rsl
+ WHERE rsl.sl_color = rsh.slcolor
+ AND rsl.sl_len_cm &gt;= rsh.slminlen_cm
+ AND rsl.sl_len_cm &lt;= rsh.slmaxlen_cm) shoe_ready
+ WHERE shoe_ready.total_avail &gt;= 2;
+</pre><p>
+
+ Similarly, the rules for <code class="literal">shoe</code> and
+ <code class="literal">shoelace</code> are substituted into the range table of
+ the subquery, leading to a three-level final query tree:
+
+</p><pre class="programlisting">
+SELECT shoe_ready.shoename, shoe_ready.sh_avail,
+ shoe_ready.sl_name, shoe_ready.sl_avail,
+ shoe_ready.total_avail
+ FROM (SELECT rsh.shoename,
+ rsh.sh_avail,
+ rsl.sl_name,
+ rsl.sl_avail,
+ least(rsh.sh_avail, rsl.sl_avail) AS total_avail
+ FROM (SELECT sh.shoename,
+ sh.sh_avail,
+ sh.slcolor,
+ sh.slminlen,
+ sh.slminlen * un.un_fact AS slminlen_cm,
+ sh.slmaxlen,
+ sh.slmaxlen * un.un_fact AS slmaxlen_cm,
+ sh.slunit
+ FROM shoe_data sh, unit un
+ WHERE sh.slunit = un.un_name) rsh,
+ (SELECT s.sl_name,
+ s.sl_avail,
+ s.sl_color,
+ s.sl_len,
+ s.sl_unit,
+ s.sl_len * u.un_fact AS sl_len_cm
+ FROM shoelace_data s, unit u
+ WHERE s.sl_unit = u.un_name) rsl
+ WHERE rsl.sl_color = rsh.slcolor
+ AND rsl.sl_len_cm &gt;= rsh.slminlen_cm
+ AND rsl.sl_len_cm &lt;= rsh.slmaxlen_cm) shoe_ready
+ WHERE shoe_ready.total_avail &gt; 2;
+</pre><p>
+ </p><p>
+ This might look inefficient, but the planner will collapse this into a
+ single-level query tree by <span class="quote">“<span class="quote">pulling up</span>”</span> the subqueries,
+ and then it will plan the joins just as if we'd written them out
+ manually. So collapsing the query tree is an optimization that the
+ rewrite system doesn't have to concern itself with.
+ </p></div><div class="sect2" id="id-1.8.6.7.6"><div class="titlepage"><div><div><h3 class="title">41.2.2. View Rules in Non-<code class="command">SELECT</code> Statements</h3></div></div></div><p>
+ Two details of the query tree aren't touched in the description of
+ view rules above. These are the command type and the result relation.
+ In fact, the command type is not needed by view rules, but the result
+ relation may affect the way in which the query rewriter works, because
+ special care needs to be taken if the result relation is a view.
+</p><p>
+ There are only a few differences between a query tree for a
+ <code class="command">SELECT</code> and one for any other
+ command. Obviously, they have a different command type and for a
+ command other than a <code class="command">SELECT</code>, the result
+ relation points to the range-table entry where the result should
+ go. Everything else is absolutely the same. So having two tables
+ <code class="literal">t1</code> and <code class="literal">t2</code> with columns <code class="literal">a</code> and
+ <code class="literal">b</code>, the query trees for the two statements:
+
+</p><pre class="programlisting">
+SELECT t2.b FROM t1, t2 WHERE t1.a = t2.a;
+
+UPDATE t1 SET b = t2.b FROM t2 WHERE t1.a = t2.a;
+</pre><p>
+
+ are nearly identical. In particular:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The range tables contain entries for the tables <code class="literal">t1</code> and <code class="literal">t2</code>.
+ </p></li><li class="listitem"><p>
+ The target lists contain one variable that points to column
+ <code class="literal">b</code> of the range table entry for table <code class="literal">t2</code>.
+ </p></li><li class="listitem"><p>
+ The qualification expressions compare the columns <code class="literal">a</code> of both
+ range-table entries for equality.
+ </p></li><li class="listitem"><p>
+ The join trees show a simple join between <code class="literal">t1</code> and <code class="literal">t2</code>.
+ </p></li></ul></div><p>
+ </p><p>
+ The consequence is, that both query trees result in similar
+ execution plans: They are both joins over the two tables. For the
+ <code class="command">UPDATE</code> the missing columns from <code class="literal">t1</code> are added to
+ the target list by the planner and the final query tree will read
+ as:
+
+</p><pre class="programlisting">
+UPDATE t1 SET a = t1.a, b = t2.b FROM t2 WHERE t1.a = t2.a;
+</pre><p>
+
+ and thus the executor run over the join will produce exactly the
+ same result set as:
+
+</p><pre class="programlisting">
+SELECT t1.a, t2.b FROM t1, t2 WHERE t1.a = t2.a;
+</pre><p>
+
+ But there is a little problem in
+ <code class="command">UPDATE</code>: the part of the executor plan that does
+ the join does not care what the results from the join are
+ meant for. It just produces a result set of rows. The fact that
+ one is a <code class="command">SELECT</code> command and the other is an
+ <code class="command">UPDATE</code> is handled higher up in the executor, where
+ it knows that this is an <code class="command">UPDATE</code>, and it knows that
+ this result should go into table <code class="literal">t1</code>. But which of the rows
+ that are there has to be replaced by the new row?
+</p><p>
+ To resolve this problem, another entry is added to the target list
+ in <code class="command">UPDATE</code> (and also in
+ <code class="command">DELETE</code>) statements: the current tuple ID
+ (<acronym class="acronym">CTID</acronym>).<a id="id-1.8.6.7.6.5.4" class="indexterm"></a>
+ This is a system column containing the
+ file block number and position in the block for the row. Knowing
+ the table, the <acronym class="acronym">CTID</acronym> can be used to retrieve the
+ original row of <code class="literal">t1</code> to be updated. After adding the
+ <acronym class="acronym">CTID</acronym> to the target list, the query actually looks like:
+
+</p><pre class="programlisting">
+SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a;
+</pre><p>
+
+ Now another detail of <span class="productname">PostgreSQL</span> enters
+ the stage. Old table rows aren't overwritten, and this
+ is why <code class="command">ROLLBACK</code> is fast. In an <code class="command">UPDATE</code>,
+ the new result row is inserted into the table (after stripping the
+ <acronym class="acronym">CTID</acronym>) and in the row header of the old row, which the
+ <acronym class="acronym">CTID</acronym> pointed to, the <code class="literal">cmax</code> and
+ <code class="literal">xmax</code> entries are set to the current command counter
+ and current transaction ID. Thus the old row is hidden, and after
+ the transaction commits the vacuum cleaner can eventually remove
+ the dead row.
+</p><p>
+ Knowing all that, we can simply apply view rules in absolutely
+ the same way to any command. There is no difference.
+</p></div><div class="sect2" id="id-1.8.6.7.7"><div class="titlepage"><div><div><h3 class="title">41.2.3. The Power of Views in <span class="productname">PostgreSQL</span></h3></div></div></div><p>
+ The above demonstrates how the rule system incorporates view
+ definitions into the original query tree. In the second example, a
+ simple <code class="command">SELECT</code> from one view created a final
+ query tree that is a join of 4 tables (<code class="literal">unit</code> was used twice with
+ different names).
+</p><p>
+ The benefit of implementing views with the rule system is
+ that the planner has all
+ the information about which tables have to be scanned plus the
+ relationships between these tables plus the restrictive
+ qualifications from the views plus the qualifications from
+ the original query
+ in one single query tree. And this is still the situation
+ when the original query is already a join over views.
+ The planner has to decide which is
+ the best path to execute the query, and the more information
+ the planner has, the better this decision can be. And
+ the rule system as implemented in <span class="productname">PostgreSQL</span>
+ ensures that this is all information available about the query
+ up to that point.
+</p></div><div class="sect2" id="RULES-VIEWS-UPDATE"><div class="titlepage"><div><div><h3 class="title">41.2.4. Updating a View</h3></div></div></div><p>
+ What happens if a view is named as the target relation for an
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code>? Doing the substitutions
+ described above would give a query tree in which the result
+ relation points at a subquery range-table entry, which will not
+ work. There are several ways in which <span class="productname">PostgreSQL</span>
+ can support the appearance of updating a view, however.
+ In order of user-experienced complexity those are: automatically substitute
+ in the underlying table for the view, execute a user-defined trigger,
+ or rewrite the query per a user-defined rule.
+ These options are discussed below.
+</p><p>
+ If the subquery selects from a single base relation and is simple
+ enough, the rewriter can automatically replace the subquery with the
+ underlying base relation so that the <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, or <code class="command">DELETE</code> is applied to
+ the base relation in the appropriate way. Views that are
+ <span class="quote">“<span class="quote">simple enough</span>”</span> for this are called <em class="firstterm">automatically
+ updatable</em>. For detailed information on the kinds of view that can
+ be automatically updated, see <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a>.
+</p><p>
+ Alternatively, the operation may be handled by a user-provided
+ <code class="literal">INSTEAD OF</code> trigger on the view
+ (see <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>).
+ Rewriting works slightly differently
+ in this case. For <code class="command">INSERT</code>, the rewriter does
+ nothing at all with the view, leaving it as the result relation
+ for the query. For <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code>, it's still necessary to expand the
+ view query to produce the <span class="quote">“<span class="quote">old</span>”</span> rows that the command will
+ attempt to update or delete. So the view is expanded as normal,
+ but another unexpanded range-table entry is added to the query
+ to represent the view in its capacity as the result relation.
+</p><p>
+ The problem that now arises is how to identify the rows to be
+ updated in the view. Recall that when the result relation
+ is a table, a special <acronym class="acronym">CTID</acronym> entry is added to the target
+ list to identify the physical locations of the rows to be updated.
+ This does not work if the result relation is a view, because a view
+ does not have any <acronym class="acronym">CTID</acronym>, since its rows do not have
+ actual physical locations. Instead, for an <code class="command">UPDATE</code>
+ or <code class="command">DELETE</code> operation, a special <code class="literal">wholerow</code>
+ entry is added to the target list, which expands to include all
+ columns from the view. The executor uses this value to supply the
+ <span class="quote">“<span class="quote">old</span>”</span> row to the <code class="literal">INSTEAD OF</code> trigger. It is
+ up to the trigger to work out what to update based on the old and
+ new row values.
+</p><p>
+ Another possibility is for the user to define <code class="literal">INSTEAD</code>
+ rules that specify substitute actions for <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, and <code class="command">DELETE</code> commands on
+ a view. These rules will rewrite the command, typically into a command
+ that updates one or more tables, rather than views. That is the topic
+ of <a class="xref" href="rules-update.html" title="41.4. Rules on INSERT, UPDATE, and DELETE">Section 41.4</a>.
+</p><p>
+ Note that rules are evaluated first, rewriting the original query
+ before it is planned and executed. Therefore, if a view has
+ <code class="literal">INSTEAD OF</code> triggers as well as rules on <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, or <code class="command">DELETE</code>, then the rules will be
+ evaluated first, and depending on the result, the triggers may not be
+ used at all.
+</p><p>
+ Automatic rewriting of an <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, or <code class="command">DELETE</code> query on a
+ simple view is always tried last. Therefore, if a view has rules or
+ triggers, they will override the default behavior of automatically
+ updatable views.
+</p><p>
+ If there are no <code class="literal">INSTEAD</code> rules or <code class="literal">INSTEAD OF</code>
+ triggers for the view, and the rewriter cannot automatically rewrite
+ the query as an update on the underlying base relation, an error will
+ be thrown because the executor cannot update a view as such.
+</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="querytree.html" title="41.1. The Query Tree">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="rules.html" title="Chapter 41. The Rule System">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="rules-materializedviews.html" title="41.3. Materialized Views">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.1. The Query Tree </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.3. Materialized Views</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/rules.html b/doc/src/sgml/html/rules.html
new file mode 100644
index 0000000..44bd352
--- /dev/null
+++ b/doc/src/sgml/html/rules.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 41. The Rule System</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example" /><link rel="next" href="querytree.html" title="41.1. The Query Tree" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 41. The Rule System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="querytree.html" title="41.1. The Query Tree">Next</a></td></tr></table><hr /></div><div class="chapter" id="RULES"><div class="titlepage"><div><div><h2 class="title">Chapter 41. The Rule System</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="querytree.html">41.1. The Query Tree</a></span></dt><dt><span class="sect1"><a href="rules-views.html">41.2. Views and the Rule System</a></span></dt><dd><dl><dt><span class="sect2"><a href="rules-views.html#RULES-SELECT">41.2.1. How <code class="command">SELECT</code> Rules Work</a></span></dt><dt><span class="sect2"><a href="rules-views.html#id-1.8.6.7.6">41.2.2. View Rules in Non-<code class="command">SELECT</code> Statements</a></span></dt><dt><span class="sect2"><a href="rules-views.html#id-1.8.6.7.7">41.2.3. The Power of Views in <span class="productname">PostgreSQL</span></a></span></dt><dt><span class="sect2"><a href="rules-views.html#RULES-VIEWS-UPDATE">41.2.4. Updating a View</a></span></dt></dl></dd><dt><span class="sect1"><a href="rules-materializedviews.html">41.3. Materialized Views</a></span></dt><dt><span class="sect1"><a href="rules-update.html">41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code></a></span></dt><dd><dl><dt><span class="sect2"><a href="rules-update.html#id-1.8.6.9.7">41.4.1. How Update Rules Work</a></span></dt><dt><span class="sect2"><a href="rules-update.html#RULES-UPDATE-VIEWS">41.4.2. Cooperation with Views</a></span></dt></dl></dd><dt><span class="sect1"><a href="rules-privileges.html">41.5. Rules and Privileges</a></span></dt><dt><span class="sect1"><a href="rules-status.html">41.6. Rules and Command Status</a></span></dt><dt><span class="sect1"><a href="rules-triggers.html">41.7. Rules Versus Triggers</a></span></dt></dl></div><a id="id-1.8.6.2" class="indexterm"></a><p>
+ This chapter discusses the rule system in
+ <span class="productname">PostgreSQL</span>. Production rule systems
+ are conceptually simple, but there are many subtle points
+ involved in actually using them.
+</p><p>
+ Some other database systems define active database rules, which
+ are usually stored procedures and triggers. In
+ <span class="productname">PostgreSQL</span>, these can be implemented
+ using functions and triggers as well.
+</p><p>
+ The rule system (more precisely speaking, the query rewrite rule
+ system) is totally different from stored procedures and triggers.
+ It modifies queries to take rules into consideration, and then
+ passes the modified query to the query planner for planning and
+ execution. It is very powerful, and can be used for many things
+ such as query language procedures, views, and versions. The
+ theoretical foundations and the power of this rule system are
+ also discussed in <a class="xref" href="biblio.html#STON90B">[ston90b]</a> and <a class="xref" href="biblio.html#ONG90">[ong90]</a>.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-trigger-table-rewrite-example.html" title="40.5. A Table Rewrite Event Trigger Example">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="querytree.html" title="41.1. The Query Tree">Next</a></td></tr><tr><td width="40%" align="left" valign="top">40.5. A Table Rewrite Event Trigger Example </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.1. The Query Tree</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-autovacuum.html b/doc/src/sgml/html/runtime-config-autovacuum.html
new file mode 100644
index 0000000..91718f9
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-autovacuum.html
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.10. Automatic Vacuuming</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-statistics.html" title="20.9. Run-time Statistics" /><link rel="next" href="runtime-config-client.html" title="20.11. Client Connection Defaults" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.10. Automatic Vacuuming</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-statistics.html" title="20.9. Run-time Statistics">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-client.html" title="20.11. Client Connection Defaults">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-AUTOVACUUM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.10. Automatic Vacuuming</h2></div></div></div><a id="id-1.6.7.13.2" class="indexterm"></a><p>
+ These settings control the behavior of the <em class="firstterm">autovacuum</em>
+ feature. Refer to <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a> for more information.
+ Note that many of these settings can be overridden on a per-table
+ basis; see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-AUTOVACUUM"><span class="term"><code class="varname">autovacuum</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.13.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls whether the server should run the
+ autovacuum launcher daemon. This is on by default; however,
+ <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-COUNTS">track_counts</a> must also be enabled for
+ autovacuum to work.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line; however, autovacuuming can be
+ disabled for individual tables by changing table storage parameters.
+ </p><p>
+ Note that even when this parameter is disabled, the system
+ will launch autovacuum processes if necessary to
+ prevent transaction ID wraparound. See <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a> for more information.
+ </p></dd><dt id="GUC-AUTOVACUUM-MAX-WORKERS"><span class="term"><code class="varname">autovacuum_max_workers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum number of autovacuum processes (other than the
+ autovacuum launcher) that may be running at any one time. The default
+ is three. This parameter can only be set at server start.
+ </p></dd><dt id="GUC-AUTOVACUUM-NAPTIME"><span class="term"><code class="varname">autovacuum_naptime</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the minimum delay between autovacuum runs on any given
+ database. In each round the daemon examines the
+ database and issues <code class="command">VACUUM</code> and <code class="command">ANALYZE</code> commands
+ as needed for tables in that database.
+ If this value is specified without units, it is taken as seconds.
+ The default is one minute (<code class="literal">1min</code>).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-THRESHOLD"><span class="term"><code class="varname">autovacuum_vacuum_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the minimum number of updated or deleted tuples needed
+ to trigger a <code class="command">VACUUM</code> in any one table.
+ The default is 50 tuples.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-INSERT-THRESHOLD"><span class="term"><code class="varname">autovacuum_vacuum_insert_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the number of inserted tuples needed to trigger a
+ <code class="command">VACUUM</code> in any one table.
+ The default is 1000 tuples. If -1 is specified, autovacuum will not
+ trigger a <code class="command">VACUUM</code> operation on any tables based on
+ the number of inserts.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-ANALYZE-THRESHOLD"><span class="term"><code class="varname">autovacuum_analyze_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the minimum number of inserted, updated or deleted tuples
+ needed to trigger an <code class="command">ANALYZE</code> in any one table.
+ The default is 50 tuples.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-SCALE-FACTOR"><span class="term"><code class="varname">autovacuum_vacuum_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.13.4.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a fraction of the table size to add to
+ <code class="varname">autovacuum_vacuum_threshold</code>
+ when deciding whether to trigger a <code class="command">VACUUM</code>.
+ The default is 0.2 (20% of table size).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-INSERT-SCALE-FACTOR"><span class="term"><code class="varname">autovacuum_vacuum_insert_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.13.4.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a fraction of the table size to add to
+ <code class="varname">autovacuum_vacuum_insert_threshold</code>
+ when deciding whether to trigger a <code class="command">VACUUM</code>.
+ The default is 0.2 (20% of table size).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-ANALYZE-SCALE-FACTOR"><span class="term"><code class="varname">autovacuum_analyze_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.13.4.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a fraction of the table size to add to
+ <code class="varname">autovacuum_analyze_threshold</code>
+ when deciding whether to trigger an <code class="command">ANALYZE</code>.
+ The default is 0.1 (10% of table size).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-FREEZE-MAX-AGE"><span class="term"><code class="varname">autovacuum_freeze_max_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum age (in transactions) that a table's
+ <code class="structname">pg_class</code>.<code class="structfield">relfrozenxid</code> field can
+ attain before a <code class="command">VACUUM</code> operation is forced
+ to prevent transaction ID wraparound within the table.
+ Note that the system will launch autovacuum processes to
+ prevent wraparound even when autovacuum is otherwise disabled.
+ </p><p>
+ Vacuum also allows removal of old files from the
+ <code class="filename">pg_xact</code> subdirectory, which is why the default
+ is a relatively low 200 million transactions.
+ This parameter can only be set at server start, but the setting
+ can be reduced for individual tables by
+ changing table storage parameters.
+ For more information see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>.
+ </p></dd><dt id="GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE"><span class="term"><code class="varname">autovacuum_multixact_freeze_max_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum age (in multixacts) that a table's
+ <code class="structname">pg_class</code>.<code class="structfield">relminmxid</code> field can
+ attain before a <code class="command">VACUUM</code> operation is forced to
+ prevent multixact ID wraparound within the table.
+ Note that the system will launch autovacuum processes to
+ prevent wraparound even when autovacuum is otherwise disabled.
+ </p><p>
+ Vacuuming multixacts also allows removal of old files from the
+ <code class="filename">pg_multixact/members</code> and <code class="filename">pg_multixact/offsets</code>
+ subdirectories, which is why the default is a relatively low
+ 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 <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND" title="25.1.5.1. Multixacts and Wraparound">Section 25.1.5.1</a>.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-COST-DELAY"><span class="term"><code class="varname">autovacuum_vacuum_cost_delay</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.13.4.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the cost delay value that will be used in automatic
+ <code class="command">VACUUM</code> operations. If -1 is specified, the regular
+ <a class="xref" href="runtime-config-resource.html#GUC-VACUUM-COST-DELAY">vacuum_cost_delay</a> value will be used.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 2 milliseconds.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd><dt id="GUC-AUTOVACUUM-VACUUM-COST-LIMIT"><span class="term"><code class="varname">autovacuum_vacuum_cost_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.13.4.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the cost limit value that will be used in automatic
+ <code class="command">VACUUM</code> operations. If -1 is specified (which is the
+ default), the regular
+ <a class="xref" href="runtime-config-resource.html#GUC-VACUUM-COST-LIMIT">vacuum_cost_limit</a> 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.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-statistics.html" title="20.9. Run-time Statistics">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-client.html" title="20.11. Client Connection Defaults">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.9. Run-time Statistics </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.11. Client Connection Defaults</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-client.html b/doc/src/sgml/html/runtime-config-client.html
new file mode 100644
index 0000000..7e65f65
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-client.html
@@ -0,0 +1,854 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.11. Client Connection Defaults</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming" /><link rel="next" href="runtime-config-locks.html" title="20.12. Lock Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.11. Client Connection Defaults</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-locks.html" title="20.12. Lock Management">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-CLIENT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.11. Client Connection Defaults</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">20.11.1. Statement Behavior</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">20.11.2. Locale and Formatting</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">20.11.3. Shared Library Preloading</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER">20.11.4. Other Defaults</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-CLIENT-STATEMENT"><div class="titlepage"><div><div><h3 class="title">20.11.1. Statement Behavior</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-CLIENT-MIN-MESSAGES"><span class="term"><code class="varname">client_min_messages</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls which
+ <a class="link" href="runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS" title="Table 20.2. Message Severity Levels">message levels</a>
+ are sent to the client.
+ Valid values are <code class="literal">DEBUG5</code>,
+ <code class="literal">DEBUG4</code>, <code class="literal">DEBUG3</code>, <code class="literal">DEBUG2</code>,
+ <code class="literal">DEBUG1</code>, <code class="literal">LOG</code>, <code class="literal">NOTICE</code>,
+ <code class="literal">WARNING</code>, and <code class="literal">ERROR</code>.
+ Each level includes all the levels that follow it. The later the level,
+ the fewer messages are sent. The default is
+ <code class="literal">NOTICE</code>. Note that <code class="literal">LOG</code> has a different
+ rank here than in <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a>.
+ </p><p>
+ <code class="literal">INFO</code> level messages are always sent to the client.
+ </p></dd><dt id="GUC-SEARCH-PATH"><span class="term"><code class="varname">search_path</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.2.2.2.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.2.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable specifies the order in which schemas are searched
+ when an object (table, data type, function, etc.) is referenced by a
+ simple name with no schema specified. When there are objects of
+ identical names in different schemas, the one found first
+ in the search path is used. An object that is not in any of the
+ schemas in the search path can only be referenced by specifying
+ its containing schema with a qualified (dotted) name.
+ </p><p>
+ The value for <code class="varname">search_path</code> must be a comma-separated
+ list of schema names. Any name that is not an existing schema, or is
+ a schema for which the user does not have <code class="literal">USAGE</code>
+ permission, is silently ignored.
+ </p><p>
+ If one of the list items is the special name
+ <code class="literal">$user</code>, then the schema having the name returned by
+ <code class="function">CURRENT_USER</code> is substituted, if there is such a schema
+ and the user has <code class="literal">USAGE</code> permission for it.
+ (If not, <code class="literal">$user</code> is ignored.)
+ </p><p>
+ The system catalog schema, <code class="literal">pg_catalog</code>, is always
+ searched, whether it is mentioned in the path or not. If it is
+ mentioned in the path then it will be searched in the specified
+ order. If <code class="literal">pg_catalog</code> is not in the path then it will
+ be searched <span class="emphasis"><em>before</em></span> searching any of the path items.
+ </p><p>
+ Likewise, the current session's temporary-table schema,
+ <code class="literal">pg_temp_<em class="replaceable"><code>nnn</code></em></code>, is always searched if it
+ exists. It can be explicitly listed in the path by using the
+ alias <code class="literal">pg_temp</code><a id="id-1.6.7.14.2.2.2.2.5.3" class="indexterm"></a>. If it is not listed in the path then
+ it is searched first (even before <code class="literal">pg_catalog</code>). However,
+ the temporary schema is only searched for relation (table, view,
+ sequence, etc.) and data type names. It is never searched for
+ function or operator names.
+ </p><p>
+ When objects are created without specifying a particular target
+ schema, they will be placed in the first valid schema named in
+ <code class="varname">search_path</code>. An error is reported if the search
+ path is empty.
+ </p><p>
+ The default value for this parameter is
+ <code class="literal">"$user", public</code>.
+ This setting supports shared use of a database (where no users
+ have private schemas, and all share use of <code class="literal">public</code>),
+ private per-user schemas, and combinations of these. Other
+ effects can be obtained by altering the default search path
+ setting, either globally or per-user.
+ </p><p>
+ For more information on schema handling, see
+ <a class="xref" href="ddl-schemas.html" title="5.9. Schemas">Section 5.9</a>. In particular, the default
+ configuration is suitable only when the database has a single user or
+ a few mutually-trusting users.
+ </p><p>
+ The current effective value of the search path can be examined
+ via the <acronym class="acronym">SQL</acronym> function
+ <code class="function">current_schemas</code>
+ (see <a class="xref" href="functions-info.html" title="9.26. System Information Functions and Operators">Section 9.26</a>).
+ This is not quite the same as
+ examining the value of <code class="varname">search_path</code>, since
+ <code class="function">current_schemas</code> shows how the items
+ appearing in <code class="varname">search_path</code> were resolved.
+ </p></dd><dt id="GUC-ROW-SECURITY"><span class="term"><code class="varname">row_security</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable controls whether to raise an error in lieu of applying a
+ row security policy. When set to <code class="literal">on</code>, policies apply
+ normally. When set to <code class="literal">off</code>, queries fail which would
+ otherwise apply at least one policy. The default is <code class="literal">on</code>.
+ Change to <code class="literal">off</code> where limited row visibility could cause
+ incorrect results; for example, <span class="application">pg_dump</span> makes that
+ change by default. This variable has no effect on roles which bypass
+ every row security policy, to wit, superusers and roles with
+ the <code class="literal">BYPASSRLS</code> attribute.
+ </p><p>
+ For more information on row security policies,
+ see <a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a>.
+ </p></dd><dt id="GUC-DEFAULT-TABLE-ACCESS-METHOD"><span class="term"><code class="varname">default_table_access_method</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.2.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies the default table access method to use when
+ creating tables or materialized views if the <code class="command">CREATE</code>
+ command does not explicitly specify an access method, or when
+ <code class="command">SELECT ... INTO</code> is used, which does not allow
+ specifying a table access method. The default is <code class="literal">heap</code>.
+ </p></dd><dt id="GUC-DEFAULT-TABLESPACE"><span class="term"><code class="varname">default_tablespace</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.2.2.5.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.5.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable specifies the default tablespace in which to create
+ objects (tables and indexes) when a <code class="command">CREATE</code> command does
+ not explicitly specify a tablespace.
+ </p><p>
+ The value is either the name of a tablespace, or an empty string
+ to specify using the default tablespace of the current database.
+ If the value does not match the name of any existing tablespace,
+ <span class="productname">PostgreSQL</span> will automatically use the default
+ tablespace of the current database. If a nondefault tablespace
+ is specified, the user must have <code class="literal">CREATE</code> privilege
+ for it, or creation attempts will fail.
+ </p><p>
+ This variable is not used for temporary tables; for them,
+ <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> is consulted instead.
+ </p><p>
+ This variable is also not used when creating databases.
+ By default, a new database inherits its tablespace setting from
+ the template database it is copied from.
+ </p><p>
+ If this parameter is set to a value other than the empty string
+ when a partitioned table is created, the partitioned table's
+ tablespace will be set to that value, which will be used as
+ the default tablespace for partitions created in the future,
+ even if <code class="varname">default_tablespace</code> has changed since then.
+ </p><p>
+ For more information on tablespaces,
+ see <a class="xref" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Section 23.6</a>.
+ </p></dd><dt id="GUC-DEFAULT-TOAST-COMPRESSION"><span class="term"><code class="varname">default_toast_compression</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable sets the default
+ <a class="link" href="storage-toast.html" title="73.2. TOAST">TOAST</a>
+ compression method for values of compressible columns.
+ (This can be overridden for individual columns by setting
+ the <code class="literal">COMPRESSION</code> column option in
+ <code class="command">CREATE TABLE</code> or
+ <code class="command">ALTER TABLE</code>.)
+ The supported compression methods are <code class="literal">pglz</code> and
+ (if <span class="productname">PostgreSQL</span> was compiled with
+ <code class="option">--with-lz4</code>) <code class="literal">lz4</code>.
+ The default is <code class="literal">pglz</code>.
+ </p></dd><dt id="GUC-TEMP-TABLESPACES"><span class="term"><code class="varname">temp_tablespaces</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.2.2.7.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.7.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable specifies tablespaces in which to create temporary
+ objects (temp tables and indexes on temp tables) when a
+ <code class="command">CREATE</code> command does not explicitly specify a tablespace.
+ Temporary files for purposes such as sorting large data sets
+ are also created in these tablespaces.
+ </p><p>
+ The value is a list of names of tablespaces. When there is more than
+ one name in the list, <span class="productname">PostgreSQL</span> chooses a random
+ member of the list each time a temporary object is to be created;
+ except that within a transaction, successively created temporary
+ objects are placed in successive tablespaces from the list.
+ If the selected element of the list is an empty string,
+ <span class="productname">PostgreSQL</span> will automatically use the default
+ tablespace of the current database instead.
+ </p><p>
+ When <code class="varname">temp_tablespaces</code> is set interactively, specifying a
+ nonexistent tablespace is an error, as is specifying a tablespace for
+ which the user does not have <code class="literal">CREATE</code> privilege. However,
+ when using a previously set value, nonexistent tablespaces are
+ ignored, as are tablespaces for which the user lacks
+ <code class="literal">CREATE</code> privilege. In particular, this rule applies when
+ using a value set in <code class="filename">postgresql.conf</code>.
+ </p><p>
+ The default value is an empty string, which results in all temporary
+ objects being created in the default tablespace of the current
+ database.
+ </p><p>
+ See also <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a>.
+ </p></dd><dt id="GUC-CHECK-FUNCTION-BODIES"><span class="term"><code class="varname">check_function_bodies</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter is normally on. When set to <code class="literal">off</code>, it
+ disables validation of the routine body string during <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> and <a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a>. Disabling validation avoids side
+ effects of the validation process, in particular preventing false
+ positives due to problems such as forward references.
+ Set this parameter
+ to <code class="literal">off</code> before loading functions on behalf of other
+ users; <span class="application">pg_dump</span> does so automatically.
+ </p></dd><dt id="GUC-DEFAULT-TRANSACTION-ISOLATION"><span class="term"><code class="varname">default_transaction_isolation</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.9.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.9.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Each SQL transaction has an isolation level, which can be
+ either <span class="quote">“<span class="quote">read uncommitted</span>”</span>, <span class="quote">“<span class="quote">read
+ committed</span>”</span>, <span class="quote">“<span class="quote">repeatable read</span>”</span>, or
+ <span class="quote">“<span class="quote">serializable</span>”</span>. This parameter controls the
+ default isolation level of each new transaction. The default
+ is <span class="quote">“<span class="quote">read committed</span>”</span>.
+ </p><p>
+ Consult <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a> and <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for more information.
+ </p></dd><dt id="GUC-DEFAULT-TRANSACTION-READ-ONLY"><span class="term"><code class="varname">default_transaction_read_only</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.10.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.10.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ A read-only SQL transaction cannot alter non-temporary tables.
+ This parameter controls the default read-only status of each new
+ transaction. The default is <code class="literal">off</code> (read/write).
+ </p><p>
+ Consult <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for more information.
+ </p></dd><dt id="GUC-DEFAULT-TRANSACTION-DEFERRABLE"><span class="term"><code class="varname">default_transaction_deferrable</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.11.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.11.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ When running at the <code class="literal">serializable</code> isolation level,
+ a deferrable read-only SQL transaction may be delayed before
+ it is allowed to proceed. However, once it begins executing
+ it does not incur any of the overhead required to ensure
+ serializability; so serialization code will have no reason to
+ force it to abort because of concurrent updates, making this
+ option suitable for long-running read-only transactions.
+ </p><p>
+ This parameter controls the default deferrable status of each
+ new transaction. It currently has no effect on read-write
+ transactions or those operating at isolation levels lower
+ than <code class="literal">serializable</code>. The default is <code class="literal">off</code>.
+ </p><p>
+ Consult <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for more information.
+ </p></dd><dt id="GUC-TRANSACTION-ISOLATION"><span class="term"><code class="varname">transaction_isolation</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.12.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.12.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter reflects the current transaction's isolation level.
+ At the beginning of each transaction, it is set to the current value
+ of <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION">default_transaction_isolation</a>.
+ Any subsequent attempt to change it is equivalent to a <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> command.
+ </p></dd><dt id="GUC-TRANSACTION-READ-ONLY"><span class="term"><code class="varname">transaction_read_only</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.13.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.13.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter reflects the current transaction's read-only status.
+ At the beginning of each transaction, it is set to the current value
+ of <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY">default_transaction_read_only</a>.
+ Any subsequent attempt to change it is equivalent to a <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> command.
+ </p></dd><dt id="GUC-TRANSACTION-DEFERRABLE"><span class="term"><code class="varname">transaction_deferrable</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.14.2.2.14.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.14.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter reflects the current transaction's deferrability status.
+ At the beginning of each transaction, it is set to the current value
+ of <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE">default_transaction_deferrable</a>.
+ Any subsequent attempt to change it is equivalent to a <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> command.
+ </p></dd><dt id="GUC-SESSION-REPLICATION-ROLE"><span class="term"><code class="varname">session_replication_role</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls firing of replication-related triggers and rules for the
+ current session.
+ Possible values are <code class="literal">origin</code> (the default),
+ <code class="literal">replica</code> and <code class="literal">local</code>.
+ Setting this parameter results in discarding any previously cached
+ query plans.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ The intended use of this setting is that logical replication systems
+ set it to <code class="literal">replica</code> when they are applying replicated
+ changes. The effect of that will be that triggers and rules (that
+ have not been altered from their default configuration) will not fire
+ on the replica. See the <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> clauses
+ <code class="literal">ENABLE TRIGGER</code> and <code class="literal">ENABLE RULE</code>
+ for more information.
+ </p><p>
+ PostgreSQL treats the settings <code class="literal">origin</code> and
+ <code class="literal">local</code> the same internally. Third-party replication
+ systems may use these two values for their internal purposes, for
+ example using <code class="literal">local</code> to designate a session whose
+ changes should not be replicated.
+ </p><p>
+ Since foreign keys are implemented as triggers, setting this parameter
+ to <code class="literal">replica</code> also disables all foreign key checks,
+ which can leave data in an inconsistent state if improperly used.
+ </p></dd><dt id="GUC-STATEMENT-TIMEOUT"><span class="term"><code class="varname">statement_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.16.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Abort any statement that takes more than the specified amount of time.
+ If <code class="varname">log_min_error_statement</code> is set
+ to <code class="literal">ERROR</code> or lower, the statement that timed out
+ will also be logged.
+ If this value is specified without units, it is taken as milliseconds.
+ A value of zero (the default) disables the timeout.
+ </p><p>
+ The timeout is measured from the time a command arrives at the
+ server until it is completed by the server. If multiple SQL
+ statements appear in a single simple-Query message, the timeout
+ is applied to each statement separately.
+ (<span class="productname">PostgreSQL</span> versions before 13 usually
+ treated the timeout as applying to the whole query string.)
+ In extended query protocol, the timeout starts running when any
+ query-related message (Parse, Bind, Execute, Describe) arrives, and
+ it is canceled by completion of an Execute or Sync message.
+ </p><p>
+ Setting <code class="varname">statement_timeout</code> in
+ <code class="filename">postgresql.conf</code> is not recommended because it would
+ affect all sessions.
+ </p></dd><dt id="GUC-LOCK-TIMEOUT"><span class="term"><code class="varname">lock_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.17.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Abort any statement that waits longer than the specified amount of
+ time while attempting to acquire a lock on a table, index,
+ row, or other database object. The time limit applies separately to
+ each lock acquisition attempt. The limit applies both to explicit
+ locking requests (such as <code class="command">LOCK TABLE</code>, or <code class="command">SELECT
+ FOR UPDATE</code> without <code class="literal">NOWAIT</code>) and to implicitly-acquired
+ locks.
+ If this value is specified without units, it is taken as milliseconds.
+ A value of zero (the default) disables the timeout.
+ </p><p>
+ Unlike <code class="varname">statement_timeout</code>, this timeout can only occur
+ while waiting for locks. Note that if <code class="varname">statement_timeout</code>
+ is nonzero, it is rather pointless to set <code class="varname">lock_timeout</code> to
+ the same or larger value, since the statement timeout would always
+ trigger first. If <code class="varname">log_min_error_statement</code> is set to
+ <code class="literal">ERROR</code> or lower, the statement that timed out will be
+ logged.
+ </p><p>
+ Setting <code class="varname">lock_timeout</code> in
+ <code class="filename">postgresql.conf</code> is not recommended because it would
+ affect all sessions.
+ </p></dd><dt id="GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT"><span class="term"><code class="varname">idle_in_transaction_session_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.18.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Terminate any session that has been idle (that is, waiting for a
+ client query) within an open transaction for longer than the
+ specified amount of time.
+ If this value is specified without units, it is taken as milliseconds.
+ A value of zero (the default) disables the timeout.
+ </p><p>
+ This option can be used to ensure that idle sessions do not hold
+ locks for an unreasonable amount of time. Even when no significant
+ locks are held, an open transaction prevents vacuuming away
+ recently-dead tuples that may be visible only to this transaction;
+ so remaining idle for a long time can contribute to table bloat.
+ See <a class="xref" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Section 25.1</a> for more details.
+ </p></dd><dt id="GUC-IDLE-SESSION-TIMEOUT"><span class="term"><code class="varname">idle_session_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.19.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Terminate any session that has been idle (that is, waiting for a
+ client query), but not within an open transaction, for longer than
+ the specified amount of time.
+ If this value is specified without units, it is taken as milliseconds.
+ A value of zero (the default) disables the timeout.
+ </p><p>
+ Unlike the case with an open transaction, an idle session without a
+ transaction imposes no large costs on the server, so there is less
+ need to enable this timeout
+ than <code class="varname">idle_in_transaction_session_timeout</code>.
+ </p><p>
+ Be wary of enforcing this timeout on connections made through
+ connection-pooling software or other middleware, as such a layer
+ may not react well to unexpected connection closure. It may be
+ helpful to enable this timeout only for interactive sessions,
+ perhaps by applying it only to particular users.
+ </p></dd><dt id="GUC-VACUUM-FREEZE-TABLE-AGE"><span class="term"><code class="varname">vacuum_freeze_table_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.20.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="command">VACUUM</code> performs an aggressive scan if the table's
+ <code class="structname">pg_class</code>.<code class="structfield">relfrozenxid</code> field has reached
+ the age specified by this setting. An aggressive scan differs from
+ a regular <code class="command">VACUUM</code> in that it visits every page that might
+ contain unfrozen XIDs or MXIDs, not just those that might contain dead
+ tuples. The default is 150 million transactions. Although users can
+ set this value anywhere from zero to two billion, <code class="command">VACUUM</code>
+ will silently limit the effective value to 95% of
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a>, so that a
+ periodic manual <code class="command">VACUUM</code> has a chance to run before an
+ anti-wraparound autovacuum is launched for the table. For more
+ information see
+ <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>.
+ </p></dd><dt id="GUC-VACUUM-FREEZE-MIN-AGE"><span class="term"><code class="varname">vacuum_freeze_min_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.21.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the cutoff age (in transactions) that <code class="command">VACUUM</code>
+ should use to decide whether to freeze row versions
+ while scanning a table.
+ The default is 50 million transactions. Although
+ users can set this value anywhere from zero to one billion,
+ <code class="command">VACUUM</code> will silently limit the effective value to half
+ the value of <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a>, so
+ that there is not an unreasonably short time between forced
+ autovacuums. For more information see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>.
+ </p></dd><dt id="GUC-VACUUM-FAILSAFE-AGE"><span class="term"><code class="varname">vacuum_failsafe_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.22.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum age (in transactions) that a table's
+ <code class="structname">pg_class</code>.<code class="structfield">relfrozenxid</code>
+ field can attain before <code class="command">VACUUM</code> takes
+ extraordinary measures to avoid system-wide transaction ID
+ wraparound failure. This is <code class="command">VACUUM</code>'s
+ strategy of last resort. The failsafe typically triggers
+ when an autovacuum to prevent transaction ID wraparound has
+ already been running for some time, though it's possible for
+ the failsafe to trigger during any <code class="command">VACUUM</code>.
+ </p><p>
+ When the failsafe is triggered, any cost-based delay that is
+ in effect will no longer be applied, and further non-essential
+ maintenance tasks (such as index vacuuming) are bypassed.
+ </p><p>
+ The default is 1.6 billion transactions. Although users can
+ set this value anywhere from zero to 2.1 billion,
+ <code class="command">VACUUM</code> will silently adjust the effective
+ value to no less than 105% of <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a>.
+ </p></dd><dt id="GUC-VACUUM-MULTIXACT-FREEZE-TABLE-AGE"><span class="term"><code class="varname">vacuum_multixact_freeze_table_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.23.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="command">VACUUM</code> performs an aggressive scan if the table's
+ <code class="structname">pg_class</code>.<code class="structfield">relminmxid</code> field has reached
+ the age specified by this setting. An aggressive scan differs from
+ a regular <code class="command">VACUUM</code> in that it visits every page that might
+ contain unfrozen XIDs or MXIDs, not just those that might contain dead
+ tuples. The default is 150 million multixacts.
+ Although users can set this value anywhere from zero to two billion,
+ <code class="command">VACUUM</code> will silently limit the effective value to 95% of
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a>, so that a
+ periodic manual <code class="command">VACUUM</code> has a chance to run before an
+ anti-wraparound is launched for the table.
+ For more information see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND" title="25.1.5.1. Multixacts and Wraparound">Section 25.1.5.1</a>.
+ </p></dd><dt id="GUC-VACUUM-MULTIXACT-FREEZE-MIN-AGE"><span class="term"><code class="varname">vacuum_multixact_freeze_min_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.24.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the cutoff age (in multixacts) that <code class="command">VACUUM</code>
+ should use to decide whether to replace multixact IDs with a newer
+ transaction ID or multixact ID while scanning a table. The default
+ is 5 million multixacts.
+ Although users can set this value anywhere from zero to one billion,
+ <code class="command">VACUUM</code> will silently limit the effective value to half
+ the value of <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a>,
+ so that there is not an unreasonably short time between forced
+ autovacuums.
+ For more information see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND" title="25.1.5.1. Multixacts and Wraparound">Section 25.1.5.1</a>.
+ </p></dd><dt id="GUC-VACUUM-MULTIXACT-FAILSAFE-AGE"><span class="term"><code class="varname">vacuum_multixact_failsafe_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.25.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum age (in multixacts) that a table's
+ <code class="structname">pg_class</code>.<code class="structfield">relminmxid</code>
+ field can attain before <code class="command">VACUUM</code> takes
+ extraordinary measures to avoid system-wide multixact ID
+ wraparound failure. This is <code class="command">VACUUM</code>'s
+ strategy of last resort. The failsafe typically triggers when
+ an autovacuum to prevent transaction ID wraparound has already
+ been running for some time, though it's possible for the
+ failsafe to trigger during any <code class="command">VACUUM</code>.
+ </p><p>
+ When the failsafe is triggered, any cost-based delay that is
+ in effect will no longer be applied, and further non-essential
+ maintenance tasks (such as index vacuuming) are bypassed.
+ </p><p>
+ The default is 1.6 billion multixacts. Although users can set
+ this value anywhere from zero to 2.1 billion,
+ <code class="command">VACUUM</code> will silently adjust the effective
+ value to no less than 105% of <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a>.
+ </p></dd><dt id="GUC-BYTEA-OUTPUT"><span class="term"><code class="varname">bytea_output</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.26.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the output format for values of type <code class="type">bytea</code>.
+ Valid values are <code class="literal">hex</code> (the default)
+ and <code class="literal">escape</code> (the traditional PostgreSQL
+ format). See <a class="xref" href="datatype-binary.html" title="8.4. Binary Data Types">Section 8.4</a> for more
+ information. The <code class="type">bytea</code> type always
+ accepts both formats on input, regardless of this setting.
+ </p></dd><dt id="GUC-XMLBINARY"><span class="term"><code class="varname">xmlbinary</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.27.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets how binary values are to be encoded in XML. This applies
+ for example when <code class="type">bytea</code> values are converted to
+ XML by the functions <code class="function">xmlelement</code> or
+ <code class="function">xmlforest</code>. Possible values are
+ <code class="literal">base64</code> and <code class="literal">hex</code>, which
+ are both defined in the XML Schema standard. The default is
+ <code class="literal">base64</code>. For further information about
+ XML-related functions, see <a class="xref" href="functions-xml.html" title="9.15. XML Functions">Section 9.15</a>.
+ </p><p>
+ The actual choice here is mostly a matter of taste,
+ constrained only by possible restrictions in client
+ applications. Both methods support all possible values,
+ although the hex encoding will be somewhat larger than the
+ base64 encoding.
+ </p></dd><dt id="GUC-XMLOPTION"><span class="term"><code class="varname">xmloption</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.2.2.28.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.28.1.4" class="indexterm"></a>
+ <a id="id-1.6.7.14.2.2.28.1.5" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets whether <code class="literal">DOCUMENT</code> or
+ <code class="literal">CONTENT</code> is implicit when converting between
+ XML and character string values. See <a class="xref" href="datatype-xml.html" title="8.13. XML Type">Section 8.13</a> for a description of this. Valid
+ values are <code class="literal">DOCUMENT</code> and
+ <code class="literal">CONTENT</code>. The default is
+ <code class="literal">CONTENT</code>.
+ </p><p>
+ According to the SQL standard, the command to set this option is
+</p><pre class="synopsis">
+SET XML OPTION { DOCUMENT | CONTENT };
+</pre><p>
+ This syntax is also available in PostgreSQL.
+ </p></dd><dt id="GUC-GIN-PENDING-LIST-LIMIT"><span class="term"><code class="varname">gin_pending_list_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.2.2.29.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum size of a GIN index's pending list, which is used
+ when <code class="literal">fastupdate</code> is enabled. If the list grows
+ larger than this maximum size, it is cleaned up by moving
+ the entries in it to the index's main GIN data structure in bulk.
+ If this value is specified without units, it is taken as kilobytes.
+ The default is four megabytes (<code class="literal">4MB</code>). This setting
+ can be overridden for individual GIN indexes by changing
+ index storage parameters.
+ See <a class="xref" href="gin-implementation.html#GIN-FAST-UPDATE" title="70.4.1. GIN Fast Update Technique">Section 70.4.1</a> and <a class="xref" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Section 70.5</a>
+ for more information.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CLIENT-FORMAT"><div class="titlepage"><div><div><h3 class="title">20.11.2. Locale and Formatting</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-DATESTYLE"><span class="term"><code class="varname">DateStyle</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the display format for date and time values, as well as the
+ rules for interpreting ambiguous date input values. For
+ historical reasons, this variable contains two independent
+ components: the output format specification (<code class="literal">ISO</code>,
+ <code class="literal">Postgres</code>, <code class="literal">SQL</code>, or <code class="literal">German</code>)
+ and the input/output specification for year/month/day ordering
+ (<code class="literal">DMY</code>, <code class="literal">MDY</code>, or <code class="literal">YMD</code>). These
+ can be set separately or together. The keywords <code class="literal">Euro</code>
+ and <code class="literal">European</code> are synonyms for <code class="literal">DMY</code>; the
+ keywords <code class="literal">US</code>, <code class="literal">NonEuro</code>, and
+ <code class="literal">NonEuropean</code> are synonyms for <code class="literal">MDY</code>. See
+ <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a> for more information. The
+ built-in default is <code class="literal">ISO, MDY</code>, but
+ <span class="application">initdb</span> will initialize the
+ configuration file with a setting that corresponds to the
+ behavior of the chosen <code class="varname">lc_time</code> locale.
+ </p></dd><dt id="GUC-INTERVALSTYLE"><span class="term"><code class="varname">IntervalStyle</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.14.3.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the display format for interval values.
+ The value <code class="literal">sql_standard</code> will produce
+ output matching <acronym class="acronym">SQL</acronym> standard interval literals.
+ The value <code class="literal">postgres</code> (which is the default) will produce
+ output matching <span class="productname">PostgreSQL</span> releases prior to 8.4
+ when the <a class="xref" href="runtime-config-client.html#GUC-DATESTYLE">DateStyle</a>
+ parameter was set to <code class="literal">ISO</code>.
+ The value <code class="literal">postgres_verbose</code> will produce output
+ matching <span class="productname">PostgreSQL</span> releases prior to 8.4
+ when the <code class="varname">DateStyle</code>
+ parameter was set to non-<code class="literal">ISO</code> output.
+ The value <code class="literal">iso_8601</code> will produce output matching the time
+ interval <span class="quote">“<span class="quote">format with designators</span>”</span> defined in section
+ 4.4.3.2 of ISO 8601.
+ </p><p>
+ The <code class="varname">IntervalStyle</code> parameter also affects the
+ interpretation of ambiguous interval input. See
+ <a class="xref" href="datatype-datetime.html#DATATYPE-INTERVAL-INPUT" title="8.5.4. Interval Input">Section 8.5.4</a> for more information.
+ </p></dd><dt id="GUC-TIMEZONE"><span class="term"><code class="varname">TimeZone</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.3.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.3.2.3.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the time zone for displaying and interpreting time stamps.
+ The built-in default is <code class="literal">GMT</code>, but that is typically
+ overridden in <code class="filename">postgresql.conf</code>; <span class="application">initdb</span>
+ will install a setting there corresponding to its system environment.
+ See <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a> for more information.
+ </p></dd><dt id="GUC-TIMEZONE-ABBREVIATIONS"><span class="term"><code class="varname">timezone_abbreviations</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.4.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.3.2.4.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the collection of time zone abbreviations that will be accepted
+ by the server for datetime input. The default is <code class="literal">'Default'</code>,
+ which is a collection that works in most of the world; there are
+ also <code class="literal">'Australia'</code> and <code class="literal">'India'</code>,
+ and other collections can be defined for a particular installation.
+ See <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a> for more information.
+ </p></dd><dt id="GUC-EXTRA-FLOAT-DIGITS"><span class="term"><code class="varname">extra_float_digits</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.3.2.5.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.3.2.5.1.4" class="indexterm"></a>
+ <a id="id-1.6.7.14.3.2.5.1.5" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter adjusts the number of digits used for textual output of
+ floating-point values, including <code class="type">float4</code>, <code class="type">float8</code>,
+ and geometric data types.
+ </p><p>
+ If the value is 1 (the default) or above, float values are output in
+ shortest-precise format; see <a class="xref" href="datatype-numeric.html#DATATYPE-FLOAT" title="8.1.3. Floating-Point Types">Section 8.1.3</a>. The
+ actual number of digits generated depends only on the value being
+ output, not on the value of this parameter. At most 17 digits are
+ required for <code class="type">float8</code> values, and 9 for <code class="type">float4</code>
+ values. This format is both fast and precise, preserving the original
+ binary float value exactly when correctly read. For historical
+ compatibility, values up to 3 are permitted.
+ </p><p>
+ If the value is zero or negative, then the output is rounded to a
+ given decimal precision. The precision used is the standard number of
+ digits for the type (<code class="literal">FLT_DIG</code>
+ or <code class="literal">DBL_DIG</code> as appropriate) reduced according to the
+ value of this parameter. (For example, specifying -1 will cause
+ <code class="type">float4</code> values to be output rounded to 5 significant
+ digits, and <code class="type">float8</code> values
+ rounded to 14 digits.) This format is slower and does not preserve all
+ the bits of the binary float value, but may be more human-readable.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The meaning of this parameter, and its default value, changed
+ in <span class="productname">PostgreSQL</span> 12;
+ see <a class="xref" href="datatype-numeric.html#DATATYPE-FLOAT" title="8.1.3. Floating-Point Types">Section 8.1.3</a> for further discussion.
+ </p></div></dd><dt id="GUC-CLIENT-ENCODING"><span class="term"><code class="varname">client_encoding</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.6.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.3.2.6.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the client-side encoding (character set).
+ The default is to use the database encoding.
+ The character sets supported by the <span class="productname">PostgreSQL</span>
+ server are described in <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
+ </p></dd><dt id="GUC-LC-MESSAGES"><span class="term"><code class="varname">lc_messages</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the language in which messages are displayed. Acceptable
+ values are system-dependent; see <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> 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.
+ </p><p>
+ On some systems, this locale category does not exist. Setting
+ this variable will still work, but there will be no effect.
+ Also, there is a chance that no translated messages for the
+ desired language exist. In that case you will continue to see
+ the English messages.
+ </p><p>
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LC-MONETARY"><span class="term"><code class="varname">lc_monetary</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the locale to use for formatting monetary amounts, for
+ example with the <code class="function">to_char</code> family of
+ functions. Acceptable values are system-dependent; see <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> 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.
+ </p></dd><dt id="GUC-LC-NUMERIC"><span class="term"><code class="varname">lc_numeric</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the locale to use for formatting numbers, for example
+ with the <code class="function">to_char</code> family of
+ functions. Acceptable values are system-dependent; see <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> 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.
+ </p></dd><dt id="GUC-LC-TIME"><span class="term"><code class="varname">lc_time</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the locale to use for formatting dates and times, for example
+ with the <code class="function">to_char</code> family of
+ functions. Acceptable values are system-dependent; see <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> 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.
+ </p></dd><dt id="GUC-DEFAULT-TEXT-SEARCH-CONFIG"><span class="term"><code class="varname">default_text_search_config</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.3.2.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ 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 <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for further information.
+ The built-in default is <code class="literal">pg_catalog.simple</code>, but
+ <span class="application">initdb</span> will initialize the
+ configuration file with a setting that corresponds to the
+ chosen <code class="varname">lc_ctype</code> locale, if a configuration
+ matching that locale can be identified.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CLIENT-PRELOAD"><div class="titlepage"><div><div><h3 class="title">20.11.3. Shared Library Preloading</h3></div></div></div><p>
+ Several settings are available for preloading shared libraries into the
+ server, in order to load additional functionality or achieve performance
+ benefits. For example, a setting of
+ <code class="literal">'$libdir/mylib'</code> would cause
+ <code class="literal">mylib.so</code> (or on some platforms,
+ <code class="literal">mylib.sl</code>) to be preloaded from the installation's standard
+ library directory. The differences between the settings are when they
+ take effect and what privileges are required to change them.
+ </p><p>
+ <span class="productname">PostgreSQL</span> procedural language libraries can
+ be preloaded in this way, typically by using the
+ syntax <code class="literal">'$libdir/plXXX'</code> where
+ <code class="literal">XXX</code> is <code class="literal">pgsql</code>, <code class="literal">perl</code>,
+ <code class="literal">tcl</code>, or <code class="literal">python</code>.
+ </p><p>
+ Only shared libraries specifically intended to be used with PostgreSQL
+ can be loaded this way. Every PostgreSQL-supported library has
+ a <span class="quote">“<span class="quote">magic block</span>”</span> that is checked to guarantee compatibility. For
+ this reason, non-PostgreSQL libraries cannot be loaded in this way. You
+ might be able to use operating-system facilities such
+ as <code class="envar">LD_PRELOAD</code> for that.
+ </p><p>
+ In general, refer to the documentation of a specific module for the
+ recommended way to load that module.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-LOCAL-PRELOAD-LIBRARIES"><span class="term"><code class="varname">local_preload_libraries</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.4.6.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.4.6.1.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ 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 <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> 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.
+ Subsequent changes have no effect. If a specified library is not
+ found, the connection attempt will fail.
+ </p><p>
+ This option can be set by any user. Because of that, the libraries
+ that can be loaded are restricted to those appearing in the
+ <code class="filename">plugins</code> subdirectory of the installation's
+ standard library directory. (It is the database administrator's
+ responsibility to ensure that only <span class="quote">“<span class="quote">safe</span>”</span> libraries
+ are installed there.) Entries in <code class="varname">local_preload_libraries</code>
+ can specify this directory explicitly, for example
+ <code class="literal">$libdir/plugins/mylib</code>, or just specify
+ the library name — <code class="literal">mylib</code> would have
+ the same effect as <code class="literal">$libdir/plugins/mylib</code>.
+ </p><p>
+ The intent of this feature is to allow unprivileged users to load
+ debugging or performance-measurement libraries into specific sessions
+ without requiring an explicit <code class="command">LOAD</code> command. To that end,
+ it would be typical to set this parameter using
+ the <code class="envar">PGOPTIONS</code> environment variable on the client or by
+ using
+ <code class="command">ALTER ROLE SET</code>.
+ </p><p>
+ 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 <a class="xref" href="runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES">session_preload_libraries</a> instead.
+ </p></dd><dt id="GUC-SESSION-PRELOAD-LIBRARIES"><span class="term"><code class="varname">session_preload_libraries</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.4.6.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ 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 <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> 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.
+ Subsequent changes have no effect. If a specified library is not
+ found, the connection attempt will fail.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ The intent of this feature is to allow debugging or
+ performance-measurement libraries to be loaded into specific sessions
+ without an explicit
+ <code class="command">LOAD</code> command being given. For
+ example, <a class="xref" href="auto-explain.html" title="F.4. auto_explain">auto_explain</a> could be enabled for all
+ sessions under a given user name by setting this parameter
+ with <code class="command">ALTER ROLE SET</code>. Also, this parameter can be changed
+ without restarting the server (but changes only take effect when a new
+ session is started), so it is easier to add new modules this way, even
+ if they should apply to all sessions.
+ </p><p>
+ Unlike <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>, 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.
+ </p></dd><dt id="GUC-SHARED-PRELOAD-LIBRARIES"><span class="term"><code class="varname">shared_preload_libraries</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.4.6.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ 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 <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> 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
+ library is not found, the server will fail to start.
+ </p><p>
+ Some libraries need to perform certain operations that can only take
+ place at postmaster start, such as allocating shared memory, reserving
+ light-weight locks, or starting background workers. Those libraries
+ must be loaded at server start through this parameter. See the
+ documentation of each library for details.
+ </p><p>
+ Other libraries can also be preloaded. By preloading a shared library,
+ the library startup time is avoided when the library is first used.
+ However, the time to start each new server process might increase
+ slightly, even if that process never uses the library. So this
+ 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 <a class="xref" href="runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES">session_preload_libraries</a> for that
+ instead.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On Windows hosts, preloading a library at server start will not reduce
+ the time required to start each new server process; each server process
+ will re-load all preload libraries. However, <code class="varname">shared_preload_libraries
+ </code> is still useful on Windows hosts for libraries that need to
+ perform operations at postmaster start time.
+ </p></div></dd><dt id="GUC-JIT-PROVIDER"><span class="term"><code class="varname">jit_provider</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.4.6.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This variable is the name of the JIT provider library to be used
+ (see <a class="xref" href="jit-extensibility.html#JIT-PLUGGABLE" title="32.4.2. Pluggable JIT Providers">Section 32.4.2</a>).
+ The default is <code class="literal">llvmjit</code>.
+ This parameter can only be set at server start.
+ </p><p>
+ If set to a non-existent library, <acronym class="acronym">JIT</acronym> will not be
+ available, but no error will be raised. This allows JIT support to be
+ installed separately from the main
+ <span class="productname">PostgreSQL</span> package.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CLIENT-OTHER"><div class="titlepage"><div><div><h3 class="title">20.11.4. Other Defaults</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-DYNAMIC-LIBRARY-PATH"><span class="term"><code class="varname">dynamic_library_path</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.14.5.2.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.14.5.2.1.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ If a dynamically loadable module needs to be opened and the
+ file name specified in the <code class="command">CREATE FUNCTION</code> or
+ <code class="command">LOAD</code> command
+ does not have a directory component (i.e., the
+ name does not contain a slash), the system will search this
+ path for the required file.
+ </p><p>
+ The value for <code class="varname">dynamic_library_path</code> must be a
+ list of absolute directory paths separated by colons (or semi-colons
+ on Windows). If a list element starts
+ with the special string <code class="literal">$libdir</code>, the
+ compiled-in <span class="productname">PostgreSQL</span> package
+ library directory is substituted for <code class="literal">$libdir</code>; this
+ is where the modules provided by the standard
+ <span class="productname">PostgreSQL</span> distribution are installed.
+ (Use <code class="literal">pg_config --pkglibdir</code> to find out the name of
+ this directory.) For example:
+</p><pre class="programlisting">
+dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
+</pre><p>
+ or, in a Windows environment:
+</p><pre class="programlisting">
+dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+</pre><p>
+ </p><p>
+ The default value for this parameter is
+ <code class="literal">'$libdir'</code>. If the value is set to an empty
+ string, the automatic path search is turned off.
+ </p><p>
+ This parameter can be changed at run time by superusers and users
+ with the appropriate <code class="literal">SET</code> privilege, but a
+ setting done that way will only persist until the end of the
+ client connection, so this method should be reserved for
+ development purposes. The recommended way to set this parameter
+ is in the <code class="filename">postgresql.conf</code> configuration
+ file.
+ </p></dd><dt id="GUC-GIN-FUZZY-SEARCH-LIMIT"><span class="term"><code class="varname">gin_fuzzy_search_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.14.5.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Soft upper limit of the size of the set returned by GIN index scans. For more
+ information see <a class="xref" href="gin-tips.html" title="70.5. GIN Tips and Tricks">Section 70.5</a>.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-locks.html" title="20.12. Lock Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.10. Automatic Vacuuming </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.12. Lock Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-compatible.html b/doc/src/sgml/html/runtime-config-compatible.html
new file mode 100644
index 0000000..b285411
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-compatible.html
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.13. Version and Platform Compatibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-locks.html" title="20.12. Lock Management" /><link rel="next" href="runtime-config-error-handling.html" title="20.14. Error Handling" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.13. Version and Platform Compatibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-locks.html" title="20.12. Lock Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-error-handling.html" title="20.14. Error Handling">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-COMPATIBLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.13. Version and Platform Compatibility</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">20.13.1. Previous PostgreSQL Versions</a></span></dt><dt><span class="sect2"><a href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-CLIENTS">20.13.2. Platform and Client Compatibility</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-COMPATIBLE-VERSION"><div class="titlepage"><div><div><h3 class="title">20.13.1. Previous PostgreSQL Versions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-ARRAY-NULLS"><span class="term"><code class="varname">array_nulls</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This controls whether the array input parser recognizes
+ unquoted <code class="literal">NULL</code> as specifying a null array element.
+ By default, this is <code class="literal">on</code>, allowing array values containing
+ null values to be entered. However, <span class="productname">PostgreSQL</span> versions
+ before 8.2 did not support null values in arrays, and therefore would
+ treat <code class="literal">NULL</code> as specifying a normal array element with
+ the string value <span class="quote">“<span class="quote">NULL</span>”</span>. For backward compatibility with
+ applications that require the old behavior, this variable can be
+ turned <code class="literal">off</code>.
+ </p><p>
+ Note that it is possible to create array values containing null values
+ even when this variable is <code class="literal">off</code>.
+ </p></dd><dt id="GUC-BACKSLASH-QUOTE"><span class="term"><code class="varname">backslash_quote</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.16.2.2.2.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.16.2.2.2.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This controls whether a quote mark can be represented by
+ <code class="literal">\'</code> in a string literal. The preferred, SQL-standard way
+ to represent a quote mark is by doubling it (<code class="literal">''</code>) but
+ <span class="productname">PostgreSQL</span> has historically also accepted
+ <code class="literal">\'</code>. However, use of <code class="literal">\'</code> creates security risks
+ because in some client character set encodings, there are multibyte
+ characters in which the last byte is numerically equivalent to ASCII
+ <code class="literal">\</code>. If client-side code does escaping incorrectly then an
+ SQL-injection attack is possible. This risk can be prevented by
+ making the server reject queries in which a quote mark appears to be
+ escaped by a backslash.
+ The allowed values of <code class="varname">backslash_quote</code> are
+ <code class="literal">on</code> (allow <code class="literal">\'</code> always),
+ <code class="literal">off</code> (reject always), and
+ <code class="literal">safe_encoding</code> (allow only if client encoding does not
+ allow ASCII <code class="literal">\</code> within a multibyte character).
+ <code class="literal">safe_encoding</code> is the default setting.
+ </p><p>
+ Note that in a standard-conforming string literal, <code class="literal">\</code> just
+ means <code class="literal">\</code> anyway. This parameter only affects the handling of
+ non-standard-conforming literals, including
+ escape string syntax (<code class="literal">E'...'</code>).
+ </p></dd><dt id="GUC-ESCAPE-STRING-WARNING"><span class="term"><code class="varname">escape_string_warning</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.3.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.16.2.2.3.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ When on, a warning is issued if a backslash (<code class="literal">\</code>)
+ appears in an ordinary string literal (<code class="literal">'...'</code>
+ syntax) and <code class="varname">standard_conforming_strings</code> is off.
+ The default is <code class="literal">on</code>.
+ </p><p>
+ Applications that wish to use backslash as escape should be
+ modified to use escape string syntax (<code class="literal">E'...'</code>),
+ because the default behavior of ordinary strings is now to treat
+ backslash as an ordinary character, per SQL standard. This variable
+ can be enabled to help locate code that needs to be changed.
+ </p></dd><dt id="GUC-LO-COMPAT-PRIVILEGES"><span class="term"><code class="varname">lo_compat_privileges</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ In <span class="productname">PostgreSQL</span> releases prior to 9.0, large objects
+ did not have access privileges and were, therefore, always readable
+ and writable by all users. Setting this variable to <code class="literal">on</code>
+ disables the new privilege checks, for compatibility with prior
+ releases. The default is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ Setting this variable does not disable all security checks related to
+ large objects — only those for which the default behavior has
+ changed in <span class="productname">PostgreSQL</span> 9.0.
+ </p></dd><dt id="GUC-QUOTE-ALL-IDENTIFIERS"><span class="term"><code class="varname">quote_all_identifiers</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When the database generates SQL, force all identifiers to be quoted,
+ even if they are not (currently) keywords. This will affect the
+ output of <code class="command">EXPLAIN</code> as well as the results of functions
+ like <code class="function">pg_get_viewdef</code>. See also the
+ <code class="option">--quote-all-identifiers</code> option of
+ <a class="xref" href="app-pgdump.html" title="pg_dump"><span class="refentrytitle"><span class="application">pg_dump</span></span></a> and <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>.
+ </p></dd><dt id="GUC-STANDARD-CONFORMING-STRINGS"><span class="term"><code class="varname">standard_conforming_strings</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.6.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.16.2.2.6.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ This controls whether ordinary string literals
+ (<code class="literal">'...'</code>) treat backslashes literally, as specified in
+ the SQL standard.
+ Beginning in <span class="productname">PostgreSQL</span> 9.1, the default is
+ <code class="literal">on</code> (prior releases defaulted to <code class="literal">off</code>).
+ Applications can check this
+ 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 (<code class="literal">E'...'</code>) is supported.
+ Escape string syntax (<a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE" title="4.1.2.2. String Constants with C-Style Escapes">Section 4.1.2.2</a>)
+ should be used if an application desires
+ backslashes to be treated as escape characters.
+ </p></dd><dt id="GUC-SYNCHRONIZE-SEQSCANS"><span class="term"><code class="varname">synchronize_seqscans</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.2.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This allows sequential scans of large tables to synchronize with each
+ other, so that concurrent scans read the same block at about the
+ same time and hence share the I/O workload. When this is enabled,
+ a scan might start in the middle of the table and then <span class="quote">“<span class="quote">wrap
+ around</span>”</span> the end to cover all rows, so as to synchronize with the
+ activity of scans already in progress. This can result in
+ unpredictable changes in the row ordering returned by queries that
+ have no <code class="literal">ORDER BY</code> clause. Setting this parameter to
+ <code class="literal">off</code> ensures the pre-8.3 behavior in which a sequential
+ scan always starts from the beginning of the table. The default
+ is <code class="literal">on</code>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-COMPATIBLE-CLIENTS"><div class="titlepage"><div><div><h3 class="title">20.13.2. Platform and Client Compatibility</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-TRANSFORM-NULL-EQUALS"><span class="term"><code class="varname">transform_null_equals</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.16.3.2.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.16.3.2.1.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ When on, expressions of the form <code class="literal"><em class="replaceable"><code>expr</code></em> =
+ NULL</code> (or <code class="literal">NULL =
+ <em class="replaceable"><code>expr</code></em></code>) are treated as
+ <code class="literal"><em class="replaceable"><code>expr</code></em> IS NULL</code>, that is, they
+ return true if <em class="replaceable"><code>expr</code></em> evaluates to the null value,
+ and false otherwise. The correct SQL-spec-compliant behavior of
+ <code class="literal"><em class="replaceable"><code>expr</code></em> = NULL</code> is to always
+ return null (unknown). Therefore this parameter defaults to
+ <code class="literal">off</code>.
+ </p><p>
+ However, filtered forms in <span class="productname">Microsoft
+ Access</span> generate queries that appear to use
+ <code class="literal"><em class="replaceable"><code>expr</code></em> = NULL</code> to test for
+ null values, so if you use that interface to access the database you
+ might want to turn this option on. Since expressions of the
+ form <code class="literal"><em class="replaceable"><code>expr</code></em> = NULL</code> always
+ return the null value (using the SQL standard interpretation), they are not
+ very useful and do not appear often in normal applications so
+ this option does little harm in practice. But new users are
+ frequently confused about the semantics of expressions
+ involving null values, so this option is off by default.
+ </p><p>
+ Note that this option only affects the exact form <code class="literal">= NULL</code>,
+ not other comparison operators or other expressions
+ that are computationally equivalent to some expression
+ involving the equals operator (such as <code class="literal">IN</code>).
+ Thus, this option is not a general fix for bad programming.
+ </p><p>
+ Refer to <a class="xref" href="functions-comparison.html" title="9.2. Comparison Functions and Operators">Section 9.2</a> for related information.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-locks.html" title="20.12. Lock Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-error-handling.html" title="20.14. Error Handling">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.12. Lock Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.14. Error Handling</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-connection.html b/doc/src/sgml/html/runtime-config-connection.html
new file mode 100644
index 0000000..3faa9b4
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-connection.html
@@ -0,0 +1,546 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.3. Connections and Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-file-locations.html" title="20.2. File Locations" /><link rel="next" href="runtime-config-resource.html" title="20.4. Resource Consumption" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.3. Connections and Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-file-locations.html" title="20.2. File Locations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-resource.html" title="20.4. Resource Consumption">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-CONNECTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.3. Connections and Authentication</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">20.3.1. Connection Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">20.3.2. Authentication</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">20.3.3. SSL</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-SETTINGS"><div class="titlepage"><div><div><h3 class="title">20.3.1. Connection Settings</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-LISTEN-ADDRESSES"><span class="term"><code class="varname">listen_addresses</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.2.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the TCP/IP address(es) on which the server is
+ to listen for connections from client applications.
+ The value takes the form of a comma-separated list of host names
+ and/or numeric IP addresses. The special entry <code class="literal">*</code>
+ corresponds to all available IP interfaces. The entry
+ <code class="literal">0.0.0.0</code> allows listening for all IPv4 addresses and
+ <code class="literal">::</code> allows listening for all IPv6 addresses.
+ If the list is empty, the server does not listen on any IP interface
+ at all, in which case only Unix-domain sockets can be used to connect
+ to it. If the list is not empty, the server will start if it
+ can listen on at least one TCP/IP address. A warning will be
+ emitted for any TCP/IP address which cannot be opened.
+ The default value is <span class="systemitem">localhost</span>,
+ which allows only local TCP/IP <span class="quote">“<span class="quote">loopback</span>”</span> connections to be
+ made.
+ </p><p>
+ While client authentication (<a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>) allows fine-grained control
+ over who can access the server, <code class="varname">listen_addresses</code>
+ controls which interfaces accept connection attempts, which
+ can help prevent repeated malicious connection requests on
+ insecure network interfaces. This parameter can only be set
+ at server start.
+ </p></dd><dt id="GUC-PORT"><span class="term"><code class="varname">port</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The TCP port the server listens on; 5432 by default. Note that the
+ same port number is used for all IP addresses the server listens on.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-MAX-CONNECTIONS"><span class="term"><code class="varname">max_connections</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines the maximum number of concurrent connections to the
+ database server. The default is typically 100 connections, but
+ might be less if your kernel settings will not support it (as
+ determined during <span class="application">initdb</span>). This parameter can
+ only be set at server start.
+ </p><p>
+ When running a standby server, you must set this parameter to the
+ same or higher value than on the primary server. Otherwise, queries
+ will not be allowed in the standby server.
+ </p></dd><dt id="GUC-SUPERUSER-RESERVED-CONNECTIONS"><span class="term"><code class="varname">superuser_reserved_connections</code>
+ (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines the number of connection <span class="quote">“<span class="quote">slots</span>”</span> that
+ are reserved for connections by <span class="productname">PostgreSQL</span>
+ superusers. At most <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>
+ connections can ever be active simultaneously. Whenever the
+ number of active concurrent connections is at least
+ <code class="varname">max_connections</code> minus
+ <code class="varname">superuser_reserved_connections</code>, new
+ connections will be accepted only for superusers, and no
+ new replication connections will be accepted.
+ </p><p>
+ The default value is three connections. The value must be less
+ than <code class="varname">max_connections</code>.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-UNIX-SOCKET-DIRECTORIES"><span class="term"><code class="varname">unix_socket_directories</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.2.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the directory of the Unix-domain socket(s) on which the
+ server is to listen for connections from client applications.
+ Multiple sockets can be created by listing multiple directories
+ separated by commas. Whitespace between entries is
+ ignored; surround a directory name with double quotes if you need
+ to include whitespace or commas in the name.
+ An empty value
+ specifies not listening on any Unix-domain sockets, in which case
+ only TCP/IP sockets can be used to connect to the server.
+ </p><p>
+ A value that starts with <code class="literal">@</code> specifies that a
+ Unix-domain socket in the abstract namespace should be created
+ (currently supported on Linux only). In that case, this value
+ does not specify a <span class="quote">“<span class="quote">directory</span>”</span> but a prefix from which
+ the actual socket name is computed in the same manner as for the
+ file-system namespace. While the abstract socket name prefix can be
+ chosen freely, since it is not a file-system location, the convention
+ is to nonetheless use file-system-like values such as
+ <code class="literal">@/tmp</code>.
+ </p><p>
+ The default value is normally
+ <code class="filename">/tmp</code>, but that can be changed at build time.
+ On Windows, the default is empty, which means no Unix-domain socket is
+ created by default.
+ This parameter can only be set at server start.
+ </p><p>
+ In addition to the socket file itself, which is named
+ <code class="literal">.s.PGSQL.<em class="replaceable"><code>nnnn</code></em></code> where
+ <em class="replaceable"><code>nnnn</code></em> is the server's port number, an ordinary file
+ named <code class="literal">.s.PGSQL.<em class="replaceable"><code>nnnn</code></em>.lock</code> will be
+ created in each of the <code class="varname">unix_socket_directories</code> directories.
+ Neither file should ever be removed manually.
+ For sockets in the abstract namespace, no lock file is created.
+ </p></dd><dt id="GUC-UNIX-SOCKET-GROUP"><span class="term"><code class="varname">unix_socket_group</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.2.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the owning group of the Unix-domain socket(s). (The owning
+ user of the sockets is always the user that starts the
+ server.) In combination with the parameter
+ <code class="varname">unix_socket_permissions</code> this can be used as
+ an additional access control mechanism for Unix-domain connections.
+ By default this is the empty string, which uses the default
+ group of the server user. This parameter can only be set at
+ server start.
+ </p><p>
+ This parameter is not supported on Windows. Any setting will be
+ ignored. Also, sockets in the abstract namespace have no file owner,
+ so this setting is also ignored in that case.
+ </p></dd><dt id="GUC-UNIX-SOCKET-PERMISSIONS"><span class="term"><code class="varname">unix_socket_permissions</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the access permissions of the Unix-domain socket(s). Unix-domain
+ sockets use the usual Unix file system permission set.
+ The parameter value is expected to be a numeric mode
+ specified in the format accepted by the
+ <code class="function">chmod</code> and <code class="function">umask</code>
+ system calls. (To use the customary octal format the number
+ must start with a <code class="literal">0</code> (zero).)
+ </p><p>
+ The default permissions are <code class="literal">0777</code>, meaning
+ anyone can connect. Reasonable alternatives are
+ <code class="literal">0770</code> (only user and group, see also
+ <code class="varname">unix_socket_group</code>) and <code class="literal">0700</code>
+ (only user). (Note that for a Unix-domain socket, only write
+ permission matters, so there is no point in setting or revoking
+ read or execute permissions.)
+ </p><p>
+ This access control mechanism is independent of the one
+ described in <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>.
+ </p><p>
+ This parameter can only be set at server start.
+ </p><p>
+ This parameter is irrelevant on systems, notably Solaris as of Solaris
+ 10, that ignore socket permissions entirely. There, one can achieve a
+ similar effect by pointing <code class="varname">unix_socket_directories</code> to a
+ directory having search permission limited to the desired audience.
+ </p><p>
+ Sockets in the abstract namespace have no file permissions, so this
+ setting is also ignored in that case.
+ </p></dd><dt id="GUC-BONJOUR"><span class="term"><code class="varname">bonjour</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.2.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables advertising the server's existence via
+ <span class="productname">Bonjour</span>. The default is off.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-BONJOUR-NAME"><span class="term"><code class="varname">bonjour_name</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.2.2.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the <span class="productname">Bonjour</span> service
+ name. The computer name is used if this parameter is set to the
+ empty string <code class="literal">''</code> (which is the default). This parameter is
+ ignored if the server was not compiled with
+ <span class="productname">Bonjour</span> support.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-TCP-KEEPALIVES-IDLE"><span class="term"><code class="varname">tcp_keepalives_idle</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the amount of time with no network activity after which
+ the operating system should send a TCP keepalive message to the client.
+ If this value is specified without units, it is taken as seconds.
+ A value of 0 (the default) selects the operating system's default.
+ This parameter is supported only on systems that support
+ <code class="symbol">TCP_KEEPIDLE</code> or an equivalent socket option, and on
+ Windows; on other systems, it must be zero.
+ In sessions connected via a Unix-domain socket, this parameter is
+ ignored and always reads as zero.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On Windows, setting a value of 0 will set this parameter to 2 hours,
+ since Windows does not provide a way to read the system default value.
+ </p></div></dd><dt id="GUC-TCP-KEEPALIVES-INTERVAL"><span class="term"><code class="varname">tcp_keepalives_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the amount of time after which a TCP keepalive message
+ that has not been acknowledged by the client should be retransmitted.
+ If this value is specified without units, it is taken as seconds.
+ A value of 0 (the default) selects the operating system's default.
+ This parameter is supported only on systems that support
+ <code class="symbol">TCP_KEEPINTVL</code> or an equivalent socket option, and on
+ Windows; on other systems, it must be zero.
+ In sessions connected via a Unix-domain socket, this parameter is
+ ignored and always reads as zero.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On Windows, setting a value of 0 will set this parameter to 1 second,
+ since Windows does not provide a way to read the system default value.
+ </p></div></dd><dt id="GUC-TCP-KEEPALIVES-COUNT"><span class="term"><code class="varname">tcp_keepalives_count</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the number of TCP keepalive messages that can be lost before
+ the server's connection to the client is considered dead.
+ A value of 0 (the default) selects the operating system's default.
+ This parameter is supported only on systems that support
+ <code class="symbol">TCP_KEEPCNT</code> or an equivalent socket option;
+ on other systems, it must be zero.
+ In sessions connected via a Unix-domain socket, this parameter is
+ ignored and always reads as zero.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This parameter is not supported on Windows, and must be zero.
+ </p></div></dd><dt id="GUC-TCP-USER-TIMEOUT"><span class="term"><code class="varname">tcp_user_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the amount of time that transmitted data may
+ remain unacknowledged before the TCP connection is forcibly closed.
+ If this value is specified without units, it is taken as milliseconds.
+ A value of 0 (the default) selects the operating system's default.
+ This parameter is supported only on systems that support
+ <code class="symbol">TCP_USER_TIMEOUT</code>; on other systems, it must be zero.
+ In sessions connected via a Unix-domain socket, this parameter is
+ ignored and always reads as zero.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This parameter is not supported on Windows, and must be zero.
+ </p></div></dd><dt id="GUC-CLIENT-CONNECTION-CHECK-INTERVAL"><span class="term"><code class="varname">client_connection_check_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.2.2.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the time interval between optional checks that the client is still
+ connected, while running queries. The check is performed by polling
+ the socket, and allows long running queries to be aborted sooner if
+ the kernel reports that the connection is closed.
+ </p><p>
+ This option relies on kernel events exposed by Linux, macOS, illumos
+ and the BSD family of operating systems, and is not currently available
+ on other systems.
+ </p><p>
+ If the value is specified without units, it is taken as milliseconds.
+ The default value is <code class="literal">0</code>, which disables connection
+ checks. Without connection checks, the server will detect the loss of
+ the connection only at the next interaction with the socket, when it
+ waits for, receives or sends data.
+ </p><p>
+ For the kernel itself to detect lost TCP connections reliably and within
+ a known timeframe in all scenarios including network failure, it may
+ also be necessary to adjust the TCP keepalive settings of the operating
+ system, or the <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-IDLE">tcp_keepalives_idle</a>,
+ <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-INTERVAL">tcp_keepalives_interval</a> and
+ <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-COUNT">tcp_keepalives_count</a> settings of
+ <span class="productname">PostgreSQL</span>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-AUTHENTICATION"><div class="titlepage"><div><div><h3 class="title">20.3.2. Authentication</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-AUTHENTICATION-TIMEOUT"><span class="term"><code class="varname">authentication_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.6.3.2.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.6.3.2.1.1.4" class="indexterm"></a>
+ <a id="id-1.6.7.6.3.2.1.1.5" class="indexterm"></a>
+ </span></dt><dd><p>
+ Maximum amount of time allowed to complete client authentication. If a
+ would-be client has not completed the authentication protocol in
+ this much time, the server closes the connection. This prevents
+ hung clients from occupying a connection indefinitely.
+ If this value is specified without units, it is taken as seconds.
+ The default is one minute (<code class="literal">1m</code>).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-PASSWORD-ENCRYPTION"><span class="term"><code class="varname">password_encryption</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.6.3.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When a password is specified in <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a> or
+ <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>, this parameter determines the
+ algorithm to use to encrypt the password. Possible values are
+ <code class="literal">scram-sha-256</code>, which will encrypt the password with
+ SCRAM-SHA-256, and <code class="literal">md5</code>, which stores the password
+ as an MD5 hash. The default is <code class="literal">scram-sha-256</code>.
+ </p><p>
+ Note that older clients might lack support for the SCRAM authentication
+ mechanism, and hence not work with passwords encrypted with
+ SCRAM-SHA-256. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for more details.
+ </p></dd><dt id="GUC-KRB-SERVER-KEYFILE"><span class="term"><code class="varname">krb_server_keyfile</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.3.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the location of the server's Kerberos key file. The default is
+ <code class="filename">FILE:/usr/local/pgsql/etc/krb5.keytab</code>
+ (where the directory part is whatever was specified
+ as <code class="varname">sysconfdir</code> at build time; use
+ <code class="literal">pg_config --sysconfdir</code> to determine that).
+ If this parameter is set to an empty string, it is ignored and a
+ system-dependent default is used.
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ See <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a> for more information.
+ </p></dd><dt id="GUC-KRB-CASEINS-USERS"><span class="term"><code class="varname">krb_caseins_users</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.3.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets whether GSSAPI user names should be treated
+ case-insensitively.
+ The default is <code class="literal">off</code> (case sensitive). This parameter can only be
+ set in the <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-DB-USER-NAMESPACE"><span class="term"><code class="varname">db_user_namespace</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.3.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter enables per-database user names. It is off by default.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ If this is on, you should create users as <em class="replaceable"><code>username@dbname</code></em>.
+ When <em class="replaceable"><code>username</code></em> is passed by a connecting client,
+ <code class="literal">@</code> and the database name are appended to the user
+ name and that database-specific user name is looked up by the
+ server. Note that when you create users with names containing
+ <code class="literal">@</code> within the SQL environment, you will need to
+ quote the user name.
+ </p><p>
+ With this parameter enabled, you can still create ordinary global
+ users. Simply append <code class="literal">@</code> when specifying the user
+ name in the client, e.g., <code class="literal">joe@</code>. The <code class="literal">@</code>
+ will be stripped off before the user name is looked up by the
+ server.
+ </p><p>
+ <code class="varname">db_user_namespace</code> causes the client's and
+ server's user name representation to differ.
+ Authentication checks are always done with the server's user name
+ so authentication methods must be configured for the
+ server's user name, not the client's. Because
+ <code class="literal">md5</code> uses the user name as salt on both the
+ client and server, <code class="literal">md5</code> cannot be used with
+ <code class="varname">db_user_namespace</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This feature is intended as a temporary measure until a
+ complete solution is found. At that time, this option will
+ be removed.
+ </p></div></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-SSL"><div class="titlepage"><div><div><h3 class="title">20.3.3. SSL</h3></div></div></div><p>
+ See <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for more information about setting up
+ <acronym class="acronym">SSL</acronym>. The configuration parameters for controlling
+ transfer encryption using <acronym class="acronym">TLS</acronym> protocols are named
+ <code class="literal">ssl</code> for historic reasons, even though support for
+ the <acronym class="acronym">SSL</acronym> protocol has been deprecated.
+ <acronym class="acronym">SSL</acronym> is in this context used interchangeably with
+ <acronym class="acronym">TLS</acronym>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-SSL"><span class="term"><code class="varname">ssl</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.4.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables <acronym class="acronym">SSL</acronym> connections.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="literal">off</code>.
+ </p></dd><dt id="GUC-SSL-CA-FILE"><span class="term"><code class="varname">ssl_ca_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the file containing the SSL server certificate
+ authority (CA).
+ Relative paths are relative to the data directory.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is empty, meaning no CA file is loaded,
+ and client certificate verification is not performed.
+ </p></dd><dt id="GUC-SSL-CERT-FILE"><span class="term"><code class="varname">ssl_cert_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the file containing the SSL server certificate.
+ Relative paths are relative to the data directory.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="filename">server.crt</code>.
+ </p></dd><dt id="GUC-SSL-CRL-FILE"><span class="term"><code class="varname">ssl_crl_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the file containing the SSL client certificate
+ revocation list (CRL).
+ Relative paths are relative to the data directory.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is empty, meaning no CRL file is loaded (unless
+ <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-DIR">ssl_crl_dir</a> is set).
+ </p></dd><dt id="GUC-SSL-CRL-DIR"><span class="term"><code class="varname">ssl_crl_dir</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the directory containing the SSL client
+ certificate revocation list (CRL). Relative paths are relative to the
+ data directory. This parameter can only be set in
+ the <code class="filename">postgresql.conf</code> file or on the server command
+ line. The default is empty, meaning no CRLs are used (unless
+ <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> is set).
+ </p><p>
+ The directory needs to be prepared with the
+ <span class="productname">OpenSSL</span> command
+ <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See
+ its documentation for details.
+ </p><p>
+ When using this setting, CRLs in the specified directory are loaded
+ on-demand at connection time. New CRLs can be added to the directory
+ and will be used immediately. This is unlike <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a>, which causes the CRL in the file to be
+ loaded at server start time or when the configuration is reloaded.
+ Both settings can be used together.
+ </p></dd><dt id="GUC-SSL-KEY-FILE"><span class="term"><code class="varname">ssl_key_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the file containing the SSL server private key.
+ Relative paths are relative to the data directory.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="filename">server.key</code>.
+ </p></dd><dt id="GUC-SSL-CIPHERS"><span class="term"><code class="varname">ssl_ciphers</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a list of <acronym class="acronym">SSL</acronym> cipher suites that are
+ allowed to be used by SSL connections. See the
+ <span class="citerefentry"><span class="refentrytitle">ciphers</span></span>
+ manual page in the <span class="productname">OpenSSL</span> package for the
+ syntax of this setting and a list of supported values. Only
+ connections using TLS version 1.2 and lower are affected. There is
+ currently no setting that controls the cipher choices used by TLS
+ version 1.3 connections. The default value is
+ <code class="literal">HIGH:MEDIUM:+3DES:!aNULL</code>. The default is usually a
+ reasonable choice unless you have specific security requirements.
+ </p><p>
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command
+ line.
+ </p><p>
+ Explanation of the default value:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HIGH</code></span></dt><dd><p>
+ Cipher suites that use ciphers from <code class="literal">HIGH</code> group (e.g.,
+ AES, Camellia, 3DES)
+ </p></dd><dt><span class="term"><code class="literal">MEDIUM</code></span></dt><dd><p>
+ Cipher suites that use ciphers from <code class="literal">MEDIUM</code> group
+ (e.g., RC4, SEED)
+ </p></dd><dt><span class="term"><code class="literal">+3DES</code></span></dt><dd><p>
+ The <span class="productname">OpenSSL</span> default order for
+ <code class="literal">HIGH</code> is problematic because it orders 3DES
+ higher than AES128. This is wrong because 3DES offers less
+ security than AES128, and it is also much slower.
+ <code class="literal">+3DES</code> reorders it after all other
+ <code class="literal">HIGH</code> and <code class="literal">MEDIUM</code> ciphers.
+ </p></dd><dt><span class="term"><code class="literal">!aNULL</code></span></dt><dd><p>
+ Disables anonymous cipher suites that do no authentication. Such
+ cipher suites are vulnerable to <acronym class="acronym">MITM</acronym> attacks and
+ therefore should not be used.
+ </p></dd></dl></div><p>
+ </p><p>
+ Available cipher suite details will vary across
+ <span class="productname">OpenSSL</span> versions. Use the command
+ <code class="literal">openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'</code> to
+ see actual details for the currently installed
+ <span class="productname">OpenSSL</span> version. Note that this list is
+ filtered at run time based on the server key type.
+ </p></dd><dt id="GUC-SSL-PREFER-SERVER-CIPHERS"><span class="term"><code class="varname">ssl_prefer_server_ciphers</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.4.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies whether to use the server's SSL cipher preferences, rather
+ than the client's.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="literal">on</code>.
+ </p><p>
+ Older PostgreSQL versions do not have this setting and always use the
+ client's preferences. This setting is mainly for backward
+ compatibility with those versions. Using the server's preferences is
+ usually better because it is more likely that the server is appropriately
+ configured.
+ </p></dd><dt id="GUC-SSL-ECDH-CURVE"><span class="term"><code class="varname">ssl_ecdh_curve</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the curve to use in <acronym class="acronym">ECDH</acronym> key
+ exchange. It needs to be supported by all clients that connect.
+ It does not need to be the same curve used by the server's Elliptic
+ Curve key.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="literal">prime256v1</code>.
+ </p><p>
+ <span class="productname">OpenSSL</span> names for the most common curves
+ are:
+ <code class="literal">prime256v1</code> (NIST P-256),
+ <code class="literal">secp384r1</code> (NIST P-384),
+ <code class="literal">secp521r1</code> (NIST P-521).
+ The full list of available curves can be shown with the command
+ <code class="command">openssl ecparam -list_curves</code>. Not all of them
+ are usable in <acronym class="acronym">TLS</acronym> though.
+ </p></dd><dt id="GUC-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="varname">ssl_min_protocol_version</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.6.4.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the minimum SSL/TLS protocol version to use. Valid values are
+ currently: <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>,
+ <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. Older
+ versions of the <span class="productname">OpenSSL</span> library do not
+ support all values; an error will be raised if an unsupported setting
+ is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and
+ 3, are always disabled.
+ </p><p>
+ The default is <code class="literal">TLSv1.2</code>, which satisfies industry
+ best practices as of this writing.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="varname">ssl_max_protocol_version</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.6.4.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum SSL/TLS protocol version to use. Valid values are as
+ for <a class="xref" href="runtime-config-connection.html#GUC-SSL-MIN-PROTOCOL-VERSION">ssl_min_protocol_version</a>, with addition of
+ an empty string, which allows any protocol version. The default is to
+ allow any version. Setting the maximum protocol version is mainly
+ useful for testing or if some component has issues working with a
+ newer protocol.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SSL-DH-PARAMS-FILE"><span class="term"><code class="varname">ssl_dh_params_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of the file containing Diffie-Hellman parameters
+ used for so-called ephemeral DH family of SSL ciphers. The default is
+ empty, in which case compiled-in default DH parameters used. Using
+ custom DH parameters reduces the exposure if an attacker manages to
+ crack the well-known compiled-in DH parameters. You can create your own
+ DH parameters file with the command
+ <code class="command">openssl dhparam -out dhparams.pem 2048</code>.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SSL-PASSPHRASE-COMMAND"><span class="term"><code class="varname">ssl_passphrase_command</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.6.4.3.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets an external command to be invoked when a passphrase for
+ decrypting an SSL file such as a private key needs to be obtained. By
+ default, this parameter is empty, which means the built-in prompting
+ mechanism is used.
+ </p><p>
+ The command must print the passphrase to the standard output and exit
+ with code 0. In the parameter value, <code class="literal">%p</code> is
+ replaced by a prompt string. (Write <code class="literal">%%</code> for a
+ literal <code class="literal">%</code>.) Note that the prompt string will
+ probably contain whitespace, so be sure to quote adequately. A single
+ newline is stripped from the end of the output if present.
+ </p><p>
+ The command does not actually have to prompt the user for a
+ passphrase. It can read it from a file, obtain it from a keychain
+ facility, or similar. It is up to the user to make sure the chosen
+ mechanism is adequately secure.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SSL-PASSPHRASE-COMMAND-SUPPORTS-RELOAD"><span class="term"><code class="varname">ssl_passphrase_command_supports_reload</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.6.4.3.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter determines whether the passphrase command set by
+ <code class="varname">ssl_passphrase_command</code> will also be called during a
+ configuration reload if a key file needs a passphrase. If this
+ parameter is off (the default), then
+ <code class="varname">ssl_passphrase_command</code> will be ignored during a
+ reload and the SSL configuration will not be reloaded if a passphrase
+ is needed. That setting is appropriate for a command that requires a
+ TTY for prompting, which might not be available when the server is
+ running. Setting this parameter to on might be appropriate if the
+ passphrase is obtained from a file, for example.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-file-locations.html" title="20.2. File Locations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-resource.html" title="20.4. Resource Consumption">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.2. File Locations </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.4. Resource Consumption</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-custom.html b/doc/src/sgml/html/runtime-config-custom.html
new file mode 100644
index 0000000..ef35e38
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-custom.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.16. Customized Options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-preset.html" title="20.15. Preset Options" /><link rel="next" href="runtime-config-developer.html" title="20.17. Developer Options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.16. Customized Options</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-preset.html" title="20.15. Preset Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-developer.html" title="20.17. Developer Options">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-CUSTOM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.16. Customized Options</h2></div></div></div><p>
+ This feature was designed to allow parameters not normally known to
+ <span class="productname">PostgreSQL</span> to be added by add-on modules
+ (such as procedural languages). This allows extension modules to be
+ configured in the standard ways.
+ </p><p>
+ Custom options have two-part names: an extension name, then a dot, then
+ the parameter name proper, much like qualified names in SQL. An example
+ is <code class="literal">plpgsql.variable_conflict</code>.
+ </p><p>
+ Because custom options may need to be set in processes that have not
+ loaded the relevant extension module, <span class="productname">PostgreSQL</span>
+ will accept a setting for any two-part parameter name. Such variables
+ are treated as placeholders and have no function until the module that
+ defines them is loaded. When an extension module is loaded, it will add
+ its variable definitions and convert any placeholder values according to
+ those definitions. If there are any unrecognized placeholders
+ that begin with its extension name, warnings are issued and those
+ placeholders are removed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-preset.html" title="20.15. Preset Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-developer.html" title="20.17. Developer Options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.15. Preset Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.17. Developer Options</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-developer.html b/doc/src/sgml/html/runtime-config-developer.html
new file mode 100644
index 0000000..f7fa53c
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-developer.html
@@ -0,0 +1,377 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.17. Developer Options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-custom.html" title="20.16. Customized Options" /><link rel="next" href="runtime-config-short.html" title="20.18. Short Options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.17. Developer Options</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-custom.html" title="20.16. Customized Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-short.html" title="20.18. Short Options">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-DEVELOPER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.17. Developer Options</h2></div></div></div><p>
+ The following parameters are intended for developer testing, and
+ should never be used on a production database. However, some of
+ them can be used to assist with the recovery of severely damaged
+ databases. As such, they have been excluded from the sample
+ <code class="filename">postgresql.conf</code> file. Note that many of these
+ parameters require special source compilation flags to work at all.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-ALLOW-IN-PLACE-TABLESPACES"><span class="term"><code class="varname">allow_in_place_tablespaces</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Allows tablespaces to be created as directories inside
+ <code class="filename">pg_tblspc</code>, when an empty location string
+ is provided to the <code class="command">CREATE TABLESPACE</code> command. This
+ is intended to allow testing replication scenarios where primary and
+ standby servers are running on the same machine. Such directories
+ are likely to confuse backup tools that expect to find only symbolic
+ links in that location.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-ALLOW-SYSTEM-TABLE-MODS"><span class="term"><code class="varname">allow_system_table_mods</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Allows modification of the structure of system tables as well as
+ certain other risky actions on system tables. This is otherwise not
+ allowed even for superusers. Ill-advised use of this setting can
+ cause irretrievable data loss or seriously corrupt the database
+ system.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-BACKTRACE-FUNCTIONS"><span class="term"><code class="varname">backtrace_functions</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.20.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter contains a comma-separated list of C function names.
+ If an error is raised and the name of the internal C function where
+ the error happens matches a value in the list, then a backtrace is
+ written to the server log together with the error message. This can
+ be used to debug specific areas of the source code.
+ </p><p>
+ Backtrace support is not available on all platforms, and the quality
+ of the backtraces depends on compilation options.
+ </p><p>
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-DEBUG-DISCARD-CACHES"><span class="term"><code class="varname">debug_discard_caches</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.20.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to <code class="literal">1</code>, each system catalog cache entry is
+ invalidated at the first possible opportunity, whether or not
+ anything that would render it invalid really occurred. Caching of
+ system catalogs is effectively disabled as a result, so the server
+ will run extremely slowly. Higher values run the cache invalidation
+ recursively, which is even slower and only useful for testing
+ the caching logic itself. The default value of <code class="literal">0</code>
+ selects normal catalog caching behavior.
+ </p><p>
+ This parameter can be very helpful when trying to trigger
+ hard-to-reproduce bugs involving concurrent catalog changes, but it
+ is otherwise rarely needed. See the source code files
+ <code class="filename">inval.c</code> and
+ <code class="filename">pg_config_manual.h</code> for details.
+ </p><p>
+ This parameter is supported when
+ <code class="symbol">DISCARD_CACHES_ENABLED</code> was defined at compile time
+ (which happens automatically when using the
+ <span class="application">configure</span> option
+ <code class="option">--enable-cassert</code>). In production builds, its value
+ will always be <code class="literal">0</code> and attempts to set it to another
+ value will raise an error.
+ </p></dd><dt id="GUC-FORCE-PARALLEL-MODE"><span class="term"><code class="varname">force_parallel_mode</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.20.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Allows the use of parallel queries for testing purposes even in cases
+ where no performance benefit is expected.
+ The allowed values of <code class="varname">force_parallel_mode</code> are
+ <code class="literal">off</code> (use parallel mode only when it is expected to improve
+ performance), <code class="literal">on</code> (force parallel query for all queries
+ for which it is thought to be safe), and <code class="literal">regress</code> (like
+ <code class="literal">on</code>, but with additional behavior changes as explained
+ below).
+ </p><p>
+ More specifically, setting this value to <code class="literal">on</code> will add
+ a <code class="literal">Gather</code> node to the top of any query plan for which this
+ appears to be safe, so that the query runs inside of a parallel worker.
+ Even when a parallel worker is not available or cannot be used,
+ operations such as starting a subtransaction that would be prohibited
+ in a parallel query context will be prohibited unless the planner
+ believes that this will cause the query to fail. If failures or
+ unexpected results occur when this option is set, some functions used
+ by the query may need to be marked <code class="literal">PARALLEL UNSAFE</code>
+ (or, possibly, <code class="literal">PARALLEL RESTRICTED</code>).
+ </p><p>
+ Setting this value to <code class="literal">regress</code> has all of the same effects
+ as setting it to <code class="literal">on</code> plus some additional effects that are
+ intended to facilitate automated regression testing. Normally,
+ messages from a parallel worker include a context line indicating that,
+ but a setting of <code class="literal">regress</code> suppresses this line so that the
+ output is the same as in non-parallel execution. Also,
+ the <code class="literal">Gather</code> nodes added to plans by this setting are hidden
+ in <code class="literal">EXPLAIN</code> output so that the output matches what
+ would be obtained if this setting were turned <code class="literal">off</code>.
+ </p></dd><dt id="GUC-IGNORE-SYSTEM-INDEXES"><span class="term"><code class="varname">ignore_system_indexes</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Ignore system indexes when reading system tables (but still
+ update the indexes when modifying the tables). This is useful
+ when recovering from damaged system indexes.
+ This parameter cannot be changed after session start.
+ </p></dd><dt id="GUC-POST-AUTH-DELAY"><span class="term"><code class="varname">post_auth_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.20.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The amount of time to delay when a new
+ server process is started, after it conducts the
+ authentication procedure. This is intended to give developers an
+ opportunity to attach to the server process with a debugger.
+ If this value is specified without units, it is taken as seconds.
+ A value of zero (the default) disables the delay.
+ This parameter cannot be changed after session start.
+ </p></dd><dt id="GUC-PRE-AUTH-DELAY"><span class="term"><code class="varname">pre_auth_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.20.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The amount of time to delay just after a
+ new server process is forked, before it conducts the
+ authentication procedure. This is intended to give developers an
+ opportunity to attach to the server process with a debugger to
+ trace down misbehavior in authentication.
+ If this value is specified without units, it is taken as seconds.
+ A value of zero (the default) disables the delay.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-TRACE-NOTIFY"><span class="term"><code class="varname">trace_notify</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Generates a great amount of debugging output for the
+ <code class="command">LISTEN</code> and <code class="command">NOTIFY</code>
+ commands. <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> or
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> must be
+ <code class="literal">DEBUG1</code> or lower to send this output to the
+ client or server logs, respectively.
+ </p></dd><dt id="GUC-TRACE-RECOVERY-MESSAGES"><span class="term"><code class="varname">trace_recovery_messages</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.20.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables logging of recovery-related debugging output that otherwise
+ would not be logged. This parameter allows the user to override the
+ normal setting of <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a>, but only for
+ specific messages. This is intended for use in debugging hot standby.
+ Valid values are <code class="literal">DEBUG5</code>, <code class="literal">DEBUG4</code>,
+ <code class="literal">DEBUG3</code>, <code class="literal">DEBUG2</code>, <code class="literal">DEBUG1</code>, and
+ <code class="literal">LOG</code>. The default, <code class="literal">LOG</code>, does not affect
+ logging decisions at all. The other values cause recovery-related
+ debug messages of that priority or higher to be logged as though they
+ had <code class="literal">LOG</code> priority; for common settings of
+ <code class="varname">log_min_messages</code> this results in unconditionally sending
+ them to the server log.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-TRACE-SORT"><span class="term"><code class="varname">trace_sort</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, emit information about resource usage during sort operations.
+ This parameter is only available if the <code class="symbol">TRACE_SORT</code> macro
+ was defined when <span class="productname">PostgreSQL</span> was compiled.
+ (However, <code class="symbol">TRACE_SORT</code> is currently defined by default.)
+ </p></dd><dt id="GUC-TRACE-LOCKS"><span class="term"><code class="varname">trace_locks</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, emit information about lock usage. Information dumped
+ includes the type of lock operation, the type of lock and the unique
+ identifier of the object being locked or unlocked. Also included
+ are bit masks for the lock types already granted on this object as
+ well as for the lock types awaited on this object. For each lock
+ type a count of the number of granted locks and waiting locks is
+ also dumped as well as the totals. An example of the log file output
+ is shown here:
+</p><pre class="screen">
+LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1)
+ grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
+ wait(0) type(AccessShareLock)
+LOG: GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1)
+ grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1
+ wait(0) type(AccessShareLock)
+LOG: UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1)
+ grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
+ wait(0) type(AccessShareLock)
+LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
+ grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
+ wait(0) type(INVALID)
+</pre><p>
+ Details of the structure being dumped may be found in
+ <code class="filename">src/include/storage/lock.h</code>.
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-TRACE-LWLOCKS"><span class="term"><code class="varname">trace_lwlocks</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, emit information about lightweight lock usage. Lightweight
+ locks are intended primarily to provide mutual exclusion of access
+ to shared-memory data structures.
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-TRACE-USERLOCKS"><span class="term"><code class="varname">trace_userlocks</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, emit information about user lock usage. Output is the same
+ as for <code class="symbol">trace_locks</code>, only for advisory locks.
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-TRACE-LOCK-OIDMIN"><span class="term"><code class="varname">trace_lock_oidmin</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.20.3.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set, do not trace locks for tables below this OID (used to avoid
+ output on system tables).
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-TRACE-LOCK-TABLE"><span class="term"><code class="varname">trace_lock_table</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.20.3.16.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Unconditionally trace locks on this table (OID).
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-DEBUG-DEADLOCKS"><span class="term"><code class="varname">debug_deadlocks</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.17.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set, dumps information about all current locks when a
+ deadlock timeout occurs.
+ </p><p>
+ This parameter is only available if the <code class="symbol">LOCK_DEBUG</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-LOG-BTREE-BUILD-STATS"><span class="term"><code class="varname">log_btree_build_stats</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.18.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set, logs system resource usage statistics (memory and CPU) on
+ various B-tree operations.
+ </p><p>
+ This parameter is only available if the <code class="symbol">BTREE_BUILD_STATS</code>
+ macro was defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-WAL-CONSISTENCY-CHECKING"><span class="term"><code class="varname">wal_consistency_checking</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.20.3.19.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter is intended to be used to check for bugs in the WAL
+ redo routines. When enabled, full-page images of any buffers modified
+ in conjunction with the WAL record are added to the record.
+ If the record is subsequently replayed, the system will first apply
+ each record and then test whether the buffers modified by the record
+ match the stored images. In certain cases (such as hint bits), minor
+ variations are acceptable, and will be ignored. Any unexpected
+ differences will result in a fatal error, terminating recovery.
+ </p><p>
+ The default value of this setting is the empty string, which disables
+ the feature. It can be set to <code class="literal">all</code> to check all
+ records, or to a comma-separated list of resource managers to check
+ only records originating from those resource managers. Currently,
+ the supported resource managers are <code class="literal">heap</code>,
+ <code class="literal">heap2</code>, <code class="literal">btree</code>, <code class="literal">hash</code>,
+ <code class="literal">gin</code>, <code class="literal">gist</code>, <code class="literal">sequence</code>,
+ <code class="literal">spgist</code>, <code class="literal">brin</code>, and <code class="literal">generic</code>.
+ Extensions may define additional resource managers. Only superusers and users with
+ the appropriate <code class="literal">SET</code> privilege can change this setting.
+ </p></dd><dt id="GUC-WAL-DEBUG"><span class="term"><code class="varname">wal_debug</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.20.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, emit WAL-related debugging output. This parameter is
+ only available if the <code class="symbol">WAL_DEBUG</code> macro was
+ defined when <span class="productname">PostgreSQL</span> was
+ compiled.
+ </p></dd><dt id="GUC-IGNORE-CHECKSUM-FAILURE"><span class="term"><code class="varname">ignore_checksum_failure</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.21.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Only has effect if <a class="xref" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS">data checksums</a> are enabled.
+ </p><p>
+ Detection of a checksum failure during a read normally causes
+ <span class="productname">PostgreSQL</span> to report an error, aborting the current
+ transaction. Setting <code class="varname">ignore_checksum_failure</code> to on causes
+ the system to ignore the failure (but still report a warning), and
+ continue processing. This behavior may <span class="emphasis"><em>cause crashes, propagate
+ or hide corruption, or other serious problems</em></span>. However, it may allow
+ you to get past the error and retrieve undamaged tuples that might still be
+ present in the table if the block header is still sane. If the header is
+ corrupt an error will be reported even if this option is enabled. The
+ default setting is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-ZERO-DAMAGED-PAGES"><span class="term"><code class="varname">zero_damaged_pages</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.22.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Detection of a damaged page header normally causes
+ <span class="productname">PostgreSQL</span> to report an error, aborting the current
+ transaction. Setting <code class="varname">zero_damaged_pages</code> to on causes
+ the system to instead report a warning, zero out the damaged
+ page in memory, and continue processing. This behavior <span class="emphasis"><em>will destroy data</em></span>,
+ namely all the rows on the damaged page. However, it does allow you to get
+ past the error and retrieve rows from any undamaged pages that might
+ be present in the table. It is useful for recovering data if
+ corruption has occurred due to a hardware or software error. You should
+ generally not set this on until you have given up hope of recovering
+ data from the damaged pages of a table. Zeroed-out pages are not
+ forced to disk so it is recommended to recreate the table or
+ the index before turning this parameter off again. The
+ default setting is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-IGNORE-INVALID-PAGES"><span class="term"><code class="varname">ignore_invalid_pages</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.23.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set to <code class="literal">off</code> (the default), detection of
+ WAL records having references to invalid pages during
+ recovery causes <span class="productname">PostgreSQL</span> to
+ raise a PANIC-level error, aborting the recovery. Setting
+ <code class="varname">ignore_invalid_pages</code> to <code class="literal">on</code>
+ causes the system to ignore invalid page references in WAL records
+ (but still report a warning), and continue the recovery.
+ This behavior may <span class="emphasis"><em>cause crashes, data loss,
+ propagate or hide corruption, or other serious problems</em></span>.
+ However, it may allow you to get past the PANIC-level error,
+ to finish the recovery, and to cause the server to start up.
+ The parameter can only be set at server start. It only has effect
+ during recovery or in standby mode.
+ </p></dd><dt id="GUC-JIT-DEBUGGING-SUPPORT"><span class="term"><code class="varname">jit_debugging_support</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.24.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If LLVM has the required functionality, register generated functions
+ with <span class="productname">GDB</span>. This makes debugging easier.
+ The default setting is <code class="literal">off</code>.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-JIT-DUMP-BITCODE"><span class="term"><code class="varname">jit_dump_bitcode</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.25.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Writes the generated <span class="productname">LLVM</span> IR out to the
+ file system, inside <a class="xref" href="runtime-config-file-locations.html#GUC-DATA-DIRECTORY">data_directory</a>. This is only
+ useful for working on the internals of the JIT implementation.
+ The default setting is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-JIT-EXPRESSIONS"><span class="term"><code class="varname">jit_expressions</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.26.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines whether expressions are JIT compiled, when JIT compilation
+ is activated (see <a class="xref" href="jit-decision.html" title="32.2. When to JIT?">Section 32.2</a>). The default is
+ <code class="literal">on</code>.
+ </p></dd><dt id="GUC-JIT-PROFILING-SUPPORT"><span class="term"><code class="varname">jit_profiling_support</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.27.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If LLVM has the required functionality, emit the data needed to allow
+ <span class="productname">perf</span> to profile functions generated by JIT.
+ This writes out files to <code class="filename">~/.debug/jit/</code>; the
+ user is responsible for performing cleanup when desired.
+ The default setting is <code class="literal">off</code>.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-JIT-TUPLE-DEFORMING"><span class="term"><code class="varname">jit_tuple_deforming</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.28.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines whether tuple deforming is JIT compiled, when JIT
+ compilation is activated (see <a class="xref" href="jit-decision.html" title="32.2. When to JIT?">Section 32.2</a>).
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-REMOVE-TEMP-FILES-AFTER-CRASH"><span class="term"><code class="varname">remove_temp_files_after_crash</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.20.3.29.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to <code class="literal">on</code>, which is the default,
+ <span class="productname">PostgreSQL</span> will automatically remove
+ temporary files after a backend crash. If disabled, the files will be
+ retained and may be used for debugging, for example. Repeated crashes
+ may however result in accumulation of useless files. This parameter
+ can only be set in the <code class="filename">postgresql.conf</code> file or on
+ the server command line.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-custom.html" title="20.16. Customized Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-short.html" title="20.18. Short Options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.16. Customized Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.18. Short Options</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-error-handling.html b/doc/src/sgml/html/runtime-config-error-handling.html
new file mode 100644
index 0000000..b6db726
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-error-handling.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.14. Error Handling</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility" /><link rel="next" href="runtime-config-preset.html" title="20.15. Preset Options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.14. Error Handling</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-preset.html" title="20.15. Preset Options">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-ERROR-HANDLING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.14. Error Handling</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-EXIT-ON-ERROR"><span class="term"><code class="varname">exit_on_error</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.17.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If on, any error will terminate the current session. By default,
+ this is set to off, so that only FATAL errors will terminate the
+ session.
+ </p></dd><dt id="GUC-RESTART-AFTER-CRASH"><span class="term"><code class="varname">restart_after_crash</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.17.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to on, which is the default, <span class="productname">PostgreSQL</span>
+ will automatically reinitialize after a backend crash. Leaving this
+ value set to on is normally the best way to maximize the availability
+ of the database. However, in some circumstances, such as when
+ <span class="productname">PostgreSQL</span> is being invoked by clusterware, it may be
+ useful to disable the restart so that the clusterware can gain
+ control and take any actions it deems appropriate.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-DATA-SYNC-RETRY"><span class="term"><code class="varname">data_sync_retry</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.17.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to off, which is the default, <span class="productname">PostgreSQL</span>
+ will raise a PANIC-level error on failure to flush modified data files
+ to the file system. This causes the database server to crash. This
+ parameter can only be set at server start.
+ </p><p>
+ On some operating systems, the status of data in the kernel's page
+ cache is unknown after a write-back failure. In some cases it might
+ have been entirely forgotten, making it unsafe to retry; the second
+ attempt may be reported as successful, when in fact the data has been
+ lost. In these circumstances, the only way to avoid data loss is to
+ recover from the WAL after any failure is reported, preferably
+ after investigating the root cause of the failure and replacing any
+ faulty hardware.
+ </p><p>
+ If set to on, <span class="productname">PostgreSQL</span> will instead
+ report an error but continue to run so that the data flushing
+ operation can be retried in a later checkpoint. Only set it to on
+ after investigating the operating system's treatment of buffered data
+ in case of write-back failure.
+ </p></dd><dt id="GUC-RECOVERY-INIT-SYNC-METHOD"><span class="term"><code class="varname">recovery_init_sync_method</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.17.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set to <code class="literal">fsync</code>, which is the default,
+ <span class="productname">PostgreSQL</span> will recursively open and
+ synchronize all files in the data directory before crash recovery
+ begins. The search for files will follow symbolic links for the WAL
+ directory and each configured tablespace (but not any other symbolic
+ links). This is intended to make sure that all WAL and data files are
+ durably stored on disk before replaying changes. This applies whenever
+ starting a database cluster that did not shut down cleanly, including
+ copies created with <span class="application">pg_basebackup</span>.
+ </p><p>
+ On Linux, <code class="literal">syncfs</code> may be used instead, to ask the
+ operating system to synchronize the whole file systems that contain the
+ data directory, the WAL files and each tablespace (but not any other
+ file systems that may be reachable through symbolic links). This may
+ be a lot faster than the <code class="literal">fsync</code> setting, because it
+ doesn't need to open each file one by one. On the other hand, it may
+ be slower if a file system is shared by other applications that
+ modify a lot of files, since those files will also be written to disk.
+ Furthermore, on versions of Linux before 5.8, I/O errors encountered
+ while writing data to disk may not be reported to
+ <span class="productname">PostgreSQL</span>, and relevant error messages may
+ appear only in kernel logs.
+ </p><p>
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-preset.html" title="20.15. Preset Options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.13. Version and Platform Compatibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.15. Preset Options</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-file-locations.html b/doc/src/sgml/html/runtime-config-file-locations.html
new file mode 100644
index 0000000..67a2e84
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-file-locations.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.2. File Locations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="config-setting.html" title="20.1. Setting Parameters" /><link rel="next" href="runtime-config-connection.html" title="20.3. Connections and Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.2. File Locations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="config-setting.html" title="20.1. Setting Parameters">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-FILE-LOCATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.2. File Locations</h2></div></div></div><p>
+ In addition to the <code class="filename">postgresql.conf</code> file
+ already mentioned, <span class="productname">PostgreSQL</span> uses
+ two other manually-edited configuration files, which control
+ client authentication (their use is discussed in <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>). 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
+ administration. In particular it is often easier to ensure that
+ the configuration files are properly backed-up when they are
+ kept separate.)
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-DATA-DIRECTORY"><span class="term"><code class="varname">data_directory</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.5.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the directory to use for data storage.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-CONFIG-FILE"><span class="term"><code class="varname">config_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.5.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the main server configuration file
+ (customarily called <code class="filename">postgresql.conf</code>).
+ This parameter can only be set on the <code class="command">postgres</code> command line.
+ </p></dd><dt id="GUC-HBA-FILE"><span class="term"><code class="varname">hba_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.5.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the configuration file for host-based authentication
+ (customarily called <code class="filename">pg_hba.conf</code>).
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-IDENT-FILE"><span class="term"><code class="varname">ident_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.5.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the configuration file for user name mapping
+ (customarily called <code class="filename">pg_ident.conf</code>).
+ This parameter can only be set at server start.
+ See also <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a>.
+ </p></dd><dt id="GUC-EXTERNAL-PID-FILE"><span class="term"><code class="varname">external_pid_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.5.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the name of an additional process-ID (PID) file that the
+ server should create for use by server administration programs.
+ This parameter can only be set at server start.
+ </p></dd></dl></div><p>
+ In a default installation, none of the above parameters are set
+ explicitly. Instead, the
+ data directory is specified by the <code class="option">-D</code> command-line
+ option or the <code class="envar">PGDATA</code> environment variable, and the
+ configuration files are all found within the data directory.
+ </p><p>
+ If you wish to keep the configuration files elsewhere than the
+ data directory, the <code class="command">postgres</code> <code class="option">-D</code>
+ command-line option or <code class="envar">PGDATA</code> environment variable
+ must point to the directory containing the configuration files,
+ and the <code class="varname">data_directory</code> parameter must be set in
+ <code class="filename">postgresql.conf</code> (or on the command line) to show
+ where the data directory is actually located. Notice that
+ <code class="varname">data_directory</code> overrides <code class="option">-D</code> and
+ <code class="envar">PGDATA</code> for the location
+ of the data directory, but not for the location of the configuration
+ files.
+ </p><p>
+ If you wish, you can specify the configuration file names and locations
+ individually using the parameters <code class="varname">config_file</code>,
+ <code class="varname">hba_file</code> and/or <code class="varname">ident_file</code>.
+ <code class="varname">config_file</code> can only be specified on the
+ <code class="command">postgres</code> command line, but the others can be
+ set within the main configuration file. If all three parameters plus
+ <code class="varname">data_directory</code> are explicitly set, then it is not necessary
+ to specify <code class="option">-D</code> or <code class="envar">PGDATA</code>.
+ </p><p>
+ When setting any of these parameters, a relative path will be interpreted
+ with respect to the directory in which <code class="command">postgres</code>
+ is started.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="config-setting.html" title="20.1. Setting Parameters">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.1. Setting Parameters </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.3. Connections and Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-locks.html b/doc/src/sgml/html/runtime-config-locks.html
new file mode 100644
index 0000000..c17c875
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-locks.html
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.12. Lock Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-client.html" title="20.11. Client Connection Defaults" /><link rel="next" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.12. Lock Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-client.html" title="20.11. Client Connection Defaults">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-LOCKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.12. Lock Management</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-DEADLOCK-TIMEOUT"><span class="term"><code class="varname">deadlock_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.15.2.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.15.2.1.1.4" class="indexterm"></a>
+ <a id="id-1.6.7.15.2.1.1.5" class="indexterm"></a>
+ </span></dt><dd><p>
+ This is the amount of time to wait on a lock
+ before checking to see if there is a deadlock condition. The
+ check for deadlock is relatively expensive, so the server doesn't run
+ it every time it waits for a lock. We optimistically assume
+ that deadlocks are not common in production applications and
+ just wait on the lock for a while before checking for a
+ deadlock. Increasing this value reduces the amount of time
+ wasted in needless deadlock checks, but slows down reporting of
+ real deadlock errors.
+ If this value is specified without units, it is taken as milliseconds.
+ The default is one second (<code class="literal">1s</code>),
+ which is probably about the smallest value you would want in
+ practice. On a heavily loaded server you might want to raise it.
+ Ideally the setting should exceed your typical transaction time,
+ so as to improve the odds that a lock will be released before
+ the waiter decides to check for deadlock.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ When <a class="xref" href="runtime-config-logging.html#GUC-LOG-LOCK-WAITS">log_lock_waits</a> is set,
+ this parameter also determines the amount 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
+ normal <code class="varname">deadlock_timeout</code>.
+ </p></dd><dt id="GUC-MAX-LOCKS-PER-TRANSACTION"><span class="term"><code class="varname">max_locks_per_transaction</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.15.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The shared lock table tracks locks on
+ <code class="varname">max_locks_per_transaction</code> * (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> + <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a>) 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
+ can lock more objects as long as the locks of all transactions
+ fit in the lock table. This is <span class="emphasis"><em>not</em></span> the number of
+ rows that can be locked; that value is unlimited. The default,
+ 64, has historically proven sufficient, but you might need to
+ raise this value if you have queries that touch many different
+ tables in a single transaction, e.g., query of a parent table with
+ many children. This parameter can only be set at server start.
+ </p><p>
+ When running a standby server, you must set this parameter to the
+ same or higher value than on the primary server. Otherwise, queries
+ will not be allowed in the standby server.
+ </p></dd><dt id="GUC-MAX-PRED-LOCKS-PER-TRANSACTION"><span class="term"><code class="varname">max_pred_locks_per_transaction</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.15.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The shared predicate lock table tracks locks on
+ <code class="varname">max_pred_locks_per_transaction</code> * (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> + <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a>) 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
+ can lock more objects as long as the locks of all transactions
+ fit in the lock table. This is <span class="emphasis"><em>not</em></span> the number of
+ rows that can be locked; that value is unlimited. The default,
+ 64, has generally been sufficient in testing, but you might need to
+ raise this value if you have clients that touch many different
+ tables in a single serializable transaction. This parameter can
+ only be set at server start.
+ </p></dd><dt id="GUC-MAX-PRED-LOCKS-PER-RELATION"><span class="term"><code class="varname">max_pred_locks_per_relation</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.15.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This controls how many pages or tuples of a single relation can be
+ predicate-locked before the lock is promoted to covering the whole
+ relation. Values greater than or equal to zero mean an absolute
+ limit, while negative values
+ mean <a class="xref" href="runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-TRANSACTION">max_pred_locks_per_transaction</a> divided by
+ the absolute value of this setting. The default is -2, which keeps
+ the behavior from previous versions of <span class="productname">PostgreSQL</span>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-MAX-PRED-LOCKS-PER-PAGE"><span class="term"><code class="varname">max_pred_locks_per_page</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.15.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This controls how many rows on a single page can be predicate-locked
+ before the lock is promoted to covering the whole page. The default
+ is 2. This parameter can only be set in
+ the <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-client.html" title="20.11. Client Connection Defaults">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-compatible.html" title="20.13. Version and Platform Compatibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.11. Client Connection Defaults </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.13. Version and Platform Compatibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-logging.html b/doc/src/sgml/html/runtime-config-logging.html
new file mode 100644
index 0000000..e84abaa
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-logging.html
@@ -0,0 +1,938 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.8. Error Reporting and Logging</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-query.html" title="20.7. Query Planning" /><link rel="next" href="runtime-config-statistics.html" title="20.9. Run-time Statistics" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.8. Error Reporting and Logging</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-query.html" title="20.7. Query Planning">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-statistics.html" title="20.9. Run-time Statistics">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-LOGGING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.8. Error Reporting and Logging</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">20.8.1. Where to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">20.8.2. When to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">20.8.3. What to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG">20.8.4. Using CSV-Format Log Output</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-JSONLOG">20.8.5. Using JSON-Format Log Output</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#id-1.6.7.11.8">20.8.6. Process Title</a></span></dt></dl></div><a id="id-1.6.7.11.2" class="indexterm"></a><div class="sect2" id="RUNTIME-CONFIG-LOGGING-WHERE"><div class="titlepage"><div><div><h3 class="title">20.8.1. Where to Log</h3></div></div></div><a id="id-1.6.7.11.3.2" class="indexterm"></a><a id="id-1.6.7.11.3.3" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt id="GUC-LOG-DESTINATION"><span class="term"><code class="varname">log_destination</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.3.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <span class="productname">PostgreSQL</span> supports several methods
+ for logging server messages, including
+ <span class="systemitem">stderr</span>, <span class="systemitem">csvlog</span>,
+ <span class="systemitem">jsonlog</span>, and
+ <span class="systemitem">syslog</span>. On Windows,
+ <span class="systemitem">eventlog</span> is also supported. Set this
+ parameter to a list of desired log destinations separated by
+ commas. The default is to log to <span class="systemitem">stderr</span>
+ only.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ If <span class="systemitem">csvlog</span> is included in <code class="varname">log_destination</code>,
+ log entries are output in <span class="quote">“<span class="quote">comma separated
+ value</span>”</span> (<acronym class="acronym">CSV</acronym>) format, which is convenient for
+ loading logs into programs.
+ See <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG" title="20.8.4. Using CSV-Format Log Output">Section 20.8.4</a> for details.
+ <a class="xref" href="runtime-config-logging.html#GUC-LOGGING-COLLECTOR">logging_collector</a> must be enabled to generate
+ CSV-format log output.
+ </p><p>
+ If <span class="systemitem">jsonlog</span> is included in
+ <code class="varname">log_destination</code>, log entries are output in
+ <acronym class="acronym">JSON</acronym> format, which is convenient for loading logs
+ into programs.
+ See <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-JSONLOG" title="20.8.5. Using JSON-Format Log Output">Section 20.8.5</a> for details.
+ <a class="xref" href="runtime-config-logging.html#GUC-LOGGING-COLLECTOR">logging_collector</a> must be enabled to generate
+ JSON-format log output.
+ </p><p>
+ When either <span class="systemitem">stderr</span>,
+ <span class="systemitem">csvlog</span> or <span class="systemitem">jsonlog</span> are
+ included, the file <code class="filename">current_logfiles</code> is created to
+ record the location of the log file(s) currently in use by the logging
+ collector and the associated logging destination. This provides a
+ convenient way to find the logs currently in use by the instance. Here
+ is an example of this file's content:
+</p><pre class="programlisting">
+stderr log/postgresql.log
+csvlog log/postgresql.csv
+jsonlog log/postgresql.json
+</pre><p>
+
+ <code class="filename">current_logfiles</code> is recreated when a new log file
+ is created as an effect of rotation, and
+ when <code class="varname">log_destination</code> is reloaded. It is removed when
+ none of <span class="systemitem">stderr</span>,
+ <span class="systemitem">csvlog</span> or <span class="systemitem">jsonlog</span> are
+ included in <code class="varname">log_destination</code>, and when the logging
+ collector is disabled.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ On most Unix systems, you will need to alter the configuration of
+ your system's <span class="application">syslog</span> daemon in order
+ to make use of the <span class="systemitem">syslog</span> option for
+ <code class="varname">log_destination</code>. <span class="productname">PostgreSQL</span>
+ can log to <span class="application">syslog</span> facilities
+ <code class="literal">LOCAL0</code> through <code class="literal">LOCAL7</code> (see <a class="xref" href="runtime-config-logging.html#GUC-SYSLOG-FACILITY">syslog_facility</a>), but the default
+ <span class="application">syslog</span> configuration on most platforms
+ will discard all such messages. You will need to add something like:
+</p><pre class="programlisting">
+local0.* /var/log/postgresql
+</pre><p>
+ to the <span class="application">syslog</span> daemon's configuration file
+ to make it work.
+ </p><p>
+ On Windows, when you use the <code class="literal">eventlog</code>
+ option for <code class="varname">log_destination</code>, you should
+ register an event source and its library with the operating
+ system so that the Windows Event Viewer can display event
+ log messages cleanly.
+ See <a class="xref" href="event-log-registration.html" title="19.12. Registering Event Log on Windows">Section 19.12</a> for details.
+ </p></div></dd><dt id="GUC-LOGGING-COLLECTOR"><span class="term"><code class="varname">logging_collector</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.3.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter enables the <em class="firstterm">logging collector</em>, which
+ is a background process that captures log messages
+ sent to <span class="systemitem">stderr</span> and redirects them into log files.
+ This approach is often more useful than
+ logging to <span class="application">syslog</span>, since some types of messages
+ might not appear in <span class="application">syslog</span> output. (One common
+ example is dynamic-linker failure messages; another is error messages
+ produced by scripts such as <code class="varname">archive_command</code>.)
+ This parameter can only be set at server start.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ It is possible to log to <span class="systemitem">stderr</span> without using the
+ logging collector; the log messages will just go to wherever the
+ server's <span class="systemitem">stderr</span> is directed. However, that method is
+ only suitable for low log volumes, since it provides no convenient
+ way to rotate log files. Also, on some platforms not using the
+ logging collector can result in lost or garbled log output, because
+ multiple processes writing concurrently to the same log file can
+ overwrite each other's output.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ The logging collector is designed to never lose messages. This means
+ that in case of extremely high load, server processes could be
+ blocked while trying to send additional log messages when the
+ collector has fallen behind. In contrast, <span class="application">syslog</span>
+ prefers to drop messages if it cannot write them, which means it
+ may fail to log some messages in such cases but it will not block
+ the rest of the system.
+ </p></div></dd><dt id="GUC-LOG-DIRECTORY"><span class="term"><code class="varname">log_directory</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.3.4.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">logging_collector</code> is enabled,
+ this parameter determines the directory in which log files will be created.
+ It can be specified as an absolute path, or relative to the
+ cluster data directory.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="literal">log</code>.
+ </p></dd><dt id="GUC-LOG-FILENAME"><span class="term"><code class="varname">log_filename</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.3.4.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">logging_collector</code> is enabled,
+ this parameter sets the file names of the created log files. The value
+ is treated as a <code class="function">strftime</code> pattern,
+ so <code class="literal">%</code>-escapes can be used to specify time-varying
+ file names. (Note that if there are
+ any time-zone-dependent <code class="literal">%</code>-escapes, the computation
+ is done in the zone specified
+ by <a class="xref" href="runtime-config-logging.html#GUC-LOG-TIMEZONE">log_timezone</a>.)
+ The supported <code class="literal">%</code>-escapes are similar to those
+ listed in the Open Group's <a class="ulink" href="https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html" target="_top">strftime
+ </a> specification.
+ Note that the system's <code class="function">strftime</code> is not used
+ directly, so platform-specific (nonstandard) extensions do not work.
+ The default is <code class="literal">postgresql-%Y-%m-%d_%H%M%S.log</code>.
+ </p><p>
+ If you specify a file name without escapes, you should plan to
+ use a log rotation utility to avoid eventually filling the
+ entire disk. In releases prior to 8.4, if
+ no <code class="literal">%</code> escapes were
+ present, <span class="productname">PostgreSQL</span> would append
+ the epoch of the new log file's creation time, but this is no
+ longer the case.
+ </p><p>
+ If CSV-format output is enabled in <code class="varname">log_destination</code>,
+ <code class="literal">.csv</code> will be appended to the timestamped
+ log file name to create the file name for CSV-format output.
+ (If <code class="varname">log_filename</code> ends in <code class="literal">.log</code>, the suffix is
+ replaced instead.)
+ </p><p>
+ If JSON-format output is enabled in <code class="varname">log_destination</code>,
+ <code class="literal">.json</code> will be appended to the timestamped
+ log file name to create the file name for JSON-format output.
+ (If <code class="varname">log_filename</code> ends in <code class="literal">.log</code>, the suffix is
+ replaced instead.)
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-LOG-FILE-MODE"><span class="term"><code class="varname">log_file_mode</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.3.4.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ On Unix systems this parameter sets the permissions for log files
+ when <code class="varname">logging_collector</code> is enabled. (On Microsoft
+ Windows this parameter is ignored.)
+ The parameter value is expected to be a numeric mode
+ specified in the format accepted by the
+ <code class="function">chmod</code> and <code class="function">umask</code>
+ system calls. (To use the customary octal format the number
+ must start with a <code class="literal">0</code> (zero).)
+ </p><p>
+ The default permissions are <code class="literal">0600</code>, meaning only the
+ server owner can read or write the log files. The other commonly
+ useful setting is <code class="literal">0640</code>, 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 <a class="xref" href="runtime-config-logging.html#GUC-LOG-DIRECTORY">log_directory</a> 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.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-LOG-ROTATION-AGE"><span class="term"><code class="varname">log_rotation_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.3.4.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">logging_collector</code> is enabled,
+ this parameter determines the maximum amount of time to use an
+ individual log file, after which a new log file will be created.
+ If this value is specified without units, it is taken as minutes.
+ The default is 24 hours.
+ Set to zero to disable time-based creation of new log files.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-LOG-ROTATION-SIZE"><span class="term"><code class="varname">log_rotation_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.3.4.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">logging_collector</code> is enabled,
+ this parameter determines the maximum size of an individual log file.
+ After this amount of data has been emitted into a log file,
+ a new log file will be created.
+ If this value is specified without units, it is taken as kilobytes.
+ The default is 10 megabytes.
+ Set to zero to disable size-based creation of new log files.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-LOG-TRUNCATE-ON-ROTATION"><span class="term"><code class="varname">log_truncate_on_rotation</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.3.4.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">logging_collector</code> is enabled,
+ this parameter will cause <span class="productname">PostgreSQL</span> to truncate (overwrite),
+ rather than append to, any existing log file of the same name.
+ However, truncation will occur only when a new file is being opened
+ due to time-based rotation, not during server startup or size-based
+ rotation. When off, pre-existing files will be appended to in
+ all cases. For example, using this setting in combination with
+ a <code class="varname">log_filename</code> like <code class="literal">postgresql-%H.log</code>
+ would result in generating twenty-four hourly log files and then
+ cyclically overwriting them.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ Example: To keep 7 days of logs, one log file per day named
+ <code class="literal">server_log.Mon</code>, <code class="literal">server_log.Tue</code>,
+ etc., and automatically overwrite last week's log with this week's log,
+ set <code class="varname">log_filename</code> to <code class="literal">server_log.%a</code>,
+ <code class="varname">log_truncate_on_rotation</code> to <code class="literal">on</code>, and
+ <code class="varname">log_rotation_age</code> to <code class="literal">1440</code>.
+ </p><p>
+ Example: To keep 24 hours of logs, one log file per hour, but
+ also rotate sooner if the log file size exceeds 1GB, set
+ <code class="varname">log_filename</code> to <code class="literal">server_log.%H%M</code>,
+ <code class="varname">log_truncate_on_rotation</code> to <code class="literal">on</code>,
+ <code class="varname">log_rotation_age</code> to <code class="literal">60</code>, and
+ <code class="varname">log_rotation_size</code> to <code class="literal">1000000</code>.
+ Including <code class="literal">%M</code> in <code class="varname">log_filename</code> allows
+ any size-driven rotations that might occur to select a file name
+ different from the hour's initial file name.
+ </p></dd><dt id="GUC-SYSLOG-FACILITY"><span class="term"><code class="varname">syslog_facility</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.11.3.4.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When logging to <span class="application">syslog</span> is enabled, this parameter
+ determines the <span class="application">syslog</span>
+ <span class="quote">“<span class="quote">facility</span>”</span> to be used. You can choose
+ from <code class="literal">LOCAL0</code>, <code class="literal">LOCAL1</code>,
+ <code class="literal">LOCAL2</code>, <code class="literal">LOCAL3</code>, <code class="literal">LOCAL4</code>,
+ <code class="literal">LOCAL5</code>, <code class="literal">LOCAL6</code>, <code class="literal">LOCAL7</code>;
+ the default is <code class="literal">LOCAL0</code>. See also the
+ documentation of your system's
+ <span class="application">syslog</span> daemon.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SYSLOG-IDENT"><span class="term"><code class="varname">syslog_ident</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.3.4.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When logging to <span class="application">syslog</span> is enabled, this parameter
+ determines the program name used to identify
+ <span class="productname">PostgreSQL</span> messages in
+ <span class="application">syslog</span> logs. The default is
+ <code class="literal">postgres</code>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SYSLOG-SEQUENCE-NUMBERS"><span class="term"><code class="varname">syslog_sequence_numbers</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.3.4.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When logging to <span class="application">syslog</span> and this is on (the
+ default), then each message will be prefixed by an increasing
+ sequence number (such as <code class="literal">[2]</code>). This circumvents
+ the <span class="quote">“<span class="quote">--- last message repeated N times ---</span>”</span> suppression
+ that many syslog implementations perform by default. In more modern
+ syslog implementations, repeated message suppression can be configured
+ (for example, <code class="literal">$RepeatedMsgReduction</code>
+ in <span class="productname">rsyslog</span>), so this might not be
+ necessary. Also, you could turn this off if you actually want to
+ suppress repeated messages.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-SYSLOG-SPLIT-MESSAGES"><span class="term"><code class="varname">syslog_split_messages</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.3.4.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When logging to <span class="application">syslog</span> is enabled, this parameter
+ determines how messages are delivered to syslog. When on (the
+ default), messages are split by lines, and long lines are split so
+ that they will fit into 1024 bytes, which is a typical size limit for
+ traditional syslog implementations. When off, PostgreSQL server log
+ messages are delivered to the syslog service as is, and it is up to
+ the syslog service to cope with the potentially bulky messages.
+ </p><p>
+ If syslog is ultimately logging to a text file, then the effect will
+ be the same either way, and it is best to leave the setting on, since
+ most syslog implementations either cannot handle large messages or
+ would need to be specially configured to handle them. But if syslog
+ is ultimately writing into some other medium, it might be necessary or
+ more useful to keep messages logically together.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-EVENT-SOURCE"><span class="term"><code class="varname">event_source</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.3.4.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When logging to <span class="application">event log</span> is enabled, this parameter
+ determines the program name used to identify
+ <span class="productname">PostgreSQL</span> messages in
+ the log. The default is <code class="literal">PostgreSQL</code>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-LOGGING-WHEN"><div class="titlepage"><div><div><h3 class="title">20.8.2. When to Log</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-LOG-MIN-MESSAGES"><span class="term"><code class="varname">log_min_messages</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.11.4.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls which <a class="link" href="runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS" title="Table 20.2. Message Severity Levels">message
+ levels</a> are written to the server log.
+ Valid values are <code class="literal">DEBUG5</code>, <code class="literal">DEBUG4</code>,
+ <code class="literal">DEBUG3</code>, <code class="literal">DEBUG2</code>, <code class="literal">DEBUG1</code>,
+ <code class="literal">INFO</code>, <code class="literal">NOTICE</code>, <code class="literal">WARNING</code>,
+ <code class="literal">ERROR</code>, <code class="literal">LOG</code>, <code class="literal">FATAL</code>, and
+ <code class="literal">PANIC</code>. Each level includes all the levels that
+ follow it. The later the level, the fewer messages are sent
+ to the log. The default is <code class="literal">WARNING</code>. Note that
+ <code class="literal">LOG</code> has a different rank here than in
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-MIN-ERROR-STATEMENT"><span class="term"><code class="varname">log_min_error_statement</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.11.4.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls which SQL statements that cause an error
+ condition are recorded in the server log. The current
+ SQL statement is included in the log entry for any message of
+ the specified
+ <a class="link" href="runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS" title="Table 20.2. Message Severity Levels">severity</a>
+ or higher.
+ Valid values are <code class="literal">DEBUG5</code>,
+ <code class="literal">DEBUG4</code>, <code class="literal">DEBUG3</code>,
+ <code class="literal">DEBUG2</code>, <code class="literal">DEBUG1</code>,
+ <code class="literal">INFO</code>, <code class="literal">NOTICE</code>,
+ <code class="literal">WARNING</code>, <code class="literal">ERROR</code>,
+ <code class="literal">LOG</code>,
+ <code class="literal">FATAL</code>, and <code class="literal">PANIC</code>.
+ The default is <code class="literal">ERROR</code>, which means statements
+ causing errors, log messages, fatal errors, or panics will be logged.
+ To effectively turn off logging of failing statements,
+ set this parameter to <code class="literal">PANIC</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-MIN-DURATION-STATEMENT"><span class="term"><code class="varname">log_min_duration_statement</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.4.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes the duration of each completed statement to be logged
+ if the statement ran for at least the specified amount of time.
+ For example, if you set it to <code class="literal">250ms</code>
+ then all SQL statements that run 250ms or longer will be
+ logged. Enabling this parameter can be helpful in tracking down
+ unoptimized queries in your applications.
+ If this value is specified without units, it is taken as milliseconds.
+ Setting this to zero prints all statement durations.
+ <code class="literal">-1</code> (the default) disables logging statement
+ durations.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ This overrides <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-DURATION-SAMPLE">log_min_duration_sample</a>,
+ meaning that queries with duration exceeding this setting are not
+ subject to sampling and are always logged.
+ </p><p>
+ For clients using extended query protocol, durations of the Parse,
+ Bind, and Execute steps are logged independently.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When using this option together with
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-STATEMENT">log_statement</a>,
+ the text of statements that are logged because of
+ <code class="varname">log_statement</code> will not be repeated in the
+ duration log message.
+ If you are not using <span class="application">syslog</span>, it is recommended
+ that you log the PID or session ID using
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-LINE-PREFIX">log_line_prefix</a>
+ so that you can link the statement message to the later
+ duration message using the process ID or session ID.
+ </p></div></dd><dt id="GUC-LOG-MIN-DURATION-SAMPLE"><span class="term"><code class="varname">log_min_duration_sample</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.4.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Allows sampling the duration of completed statements that ran for
+ at least the specified amount of time. This produces the same
+ kind of log entries as
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-DURATION-STATEMENT">log_min_duration_statement</a>, but only for a
+ subset of the executed statements, with sample rate controlled by
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-STATEMENT-SAMPLE-RATE">log_statement_sample_rate</a>.
+ For example, if you set it to <code class="literal">100ms</code> then all
+ SQL statements that run 100ms or longer will be considered for
+ sampling. Enabling this parameter can be helpful when the
+ traffic is too high to log all queries.
+ If this value is specified without units, it is taken as milliseconds.
+ Setting this to zero samples all statement durations.
+ <code class="literal">-1</code> (the default) disables sampling statement
+ durations.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ This setting has lower priority
+ than <code class="varname">log_min_duration_statement</code>, meaning that
+ statements with durations
+ exceeding <code class="varname">log_min_duration_statement</code> are not
+ subject to sampling and are always logged.
+ </p><p>
+ Other notes for <code class="varname">log_min_duration_statement</code>
+ apply also to this setting.
+ </p></dd><dt id="GUC-LOG-STATEMENT-SAMPLE-RATE"><span class="term"><code class="varname">log_statement_sample_rate</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.11.4.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines the fraction of statements with duration exceeding
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-DURATION-SAMPLE">log_min_duration_sample</a> that will be logged.
+ Sampling is stochastic, for example <code class="literal">0.5</code> means
+ there is statistically one chance in two that any given statement
+ will be logged.
+ The default is <code class="literal">1.0</code>, meaning to log all sampled
+ statements.
+ Setting this to zero disables sampled statement-duration logging,
+ the same as setting
+ <code class="varname">log_min_duration_sample</code> to
+ <code class="literal">-1</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-TRANSACTION-SAMPLE-RATE"><span class="term"><code class="varname">log_transaction_sample_rate</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.11.4.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the fraction of transactions whose statements are all logged,
+ in addition to statements logged for other reasons. It applies to
+ each new transaction regardless of its statements' durations.
+ Sampling is stochastic, for example <code class="literal">0.1</code> means
+ there is statistically one chance in ten that any given transaction
+ will be logged.
+ <code class="varname">log_transaction_sample_rate</code> can be helpful to
+ construct a sample of transactions.
+ The default is <code class="literal">0</code>, meaning not to log
+ statements from any additional transactions. Setting this
+ to <code class="literal">1</code> logs all statements of all transactions.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Like all statement-logging options, this option can add significant
+ overhead.
+ </p></div></dd><dt id="GUC-LOG-STARTUP-PROGRESS-INTERVAL"><span class="term"><code class="varname">log_startup_progress_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.4.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the amount of time after which the startup process will log
+ a message about a long-running operation that is still in progress,
+ as well as the interval between further progress messages for that
+ operation. The default is 10 seconds. A setting of <code class="literal">0</code>
+ disables the feature. If this value is specified without units,
+ it is taken as milliseconds. This setting is applied separately to
+ each operation.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ For example, if syncing the data directory takes 25 seconds and
+ thereafter resetting unlogged relations takes 8 seconds, and if this
+ setting has the default value of 10 seconds, then a messages will be
+ logged for syncing the data directory after it has been in progress
+ for 10 seconds and again after it has been in progress for 20 seconds,
+ but nothing will be logged for resetting unlogged relations.
+ </p></dd></dl></div><p>
+ <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS" title="Table 20.2. Message Severity Levels">Table 20.2</a> explains the message
+ severity levels used by <span class="productname">PostgreSQL</span>. If logging output
+ is sent to <span class="systemitem">syslog</span> or Windows'
+ <span class="systemitem">eventlog</span>, the severity levels are translated
+ as shown in the table.
+ </p><div class="table" id="RUNTIME-CONFIG-SEVERITY-LEVELS"><p class="title"><strong>Table 20.2. Message Severity Levels</strong></p><div class="table-contents"><table class="table" summary="Message Severity Levels" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Severity</th><th>Usage</th><th><span class="systemitem">syslog</span></th><th><span class="systemitem">eventlog</span></th></tr></thead><tbody><tr><td><code class="literal">DEBUG1 .. DEBUG5</code></td><td>Provides successively-more-detailed information for use by
+ developers.</td><td><code class="literal">DEBUG</code></td><td><code class="literal">INFORMATION</code></td></tr><tr><td><code class="literal">INFO</code></td><td>Provides information implicitly requested by the user,
+ e.g., output from <code class="command">VACUUM VERBOSE</code>.</td><td><code class="literal">INFO</code></td><td><code class="literal">INFORMATION</code></td></tr><tr><td><code class="literal">NOTICE</code></td><td>Provides information that might be helpful to users, e.g.,
+ notice of truncation of long identifiers.</td><td><code class="literal">NOTICE</code></td><td><code class="literal">INFORMATION</code></td></tr><tr><td><code class="literal">WARNING</code></td><td>Provides warnings of likely problems, e.g., <code class="command">COMMIT</code>
+ outside a transaction block.</td><td><code class="literal">NOTICE</code></td><td><code class="literal">WARNING</code></td></tr><tr><td><code class="literal">ERROR</code></td><td>Reports an error that caused the current command to
+ abort.</td><td><code class="literal">WARNING</code></td><td><code class="literal">ERROR</code></td></tr><tr><td><code class="literal">LOG</code></td><td>Reports information of interest to administrators, e.g.,
+ checkpoint activity.</td><td><code class="literal">INFO</code></td><td><code class="literal">INFORMATION</code></td></tr><tr><td><code class="literal">FATAL</code></td><td>Reports an error that caused the current session to
+ abort.</td><td><code class="literal">ERR</code></td><td><code class="literal">ERROR</code></td></tr><tr><td><code class="literal">PANIC</code></td><td>Reports an error that caused all database sessions to abort.</td><td><code class="literal">CRIT</code></td><td><code class="literal">ERROR</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="RUNTIME-CONFIG-LOGGING-WHAT"><div class="titlepage"><div><div><h3 class="title">20.8.3. What to Log</h3></div></div></div><div class="note"><h3 class="title">Note</h3><p>
+ What you choose to log can have security implications; see
+ <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a>.
+ </p></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-APPLICATION-NAME"><span class="term"><code class="varname">application_name</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.5.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The <code class="varname">application_name</code> can be any string of less than
+ <code class="symbol">NAMEDATALEN</code> characters (64 characters in a standard build).
+ It is typically set by an application upon connection to the server.
+ The name will be displayed in the <code class="structname">pg_stat_activity</code> view
+ and included in CSV log entries. It can also be included in regular
+ log entries via the <a class="xref" href="runtime-config-logging.html#GUC-LOG-LINE-PREFIX">log_line_prefix</a> parameter.
+ Only printable ASCII characters may be used in the
+ <code class="varname">application_name</code> value. Other characters will be
+ replaced with question marks (<code class="literal">?</code>).
+ </p></dd><dt><span class="term"><code class="varname">debug_print_parse</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.2.1.3" class="indexterm"></a>
+ <br /></span><span class="term"><code class="varname">debug_print_rewritten</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.2.2.3" class="indexterm"></a>
+ <br /></span><span class="term"><code class="varname">debug_print_plan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.2.3.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ These parameters enable various debugging output to be emitted.
+ When set, they print the resulting parse tree, the query rewriter
+ output, or the execution plan for each executed query.
+ These messages are emitted at <code class="literal">LOG</code> 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
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> and/or
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a>.
+ These parameters are off by default.
+ </p></dd><dt><span class="term"><code class="varname">debug_pretty_print</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When set, <code class="varname">debug_pretty_print</code> indents the messages
+ produced by <code class="varname">debug_print_parse</code>,
+ <code class="varname">debug_print_rewritten</code>, or
+ <code class="varname">debug_print_plan</code>. This results in more readable
+ but much longer output than the <span class="quote">“<span class="quote">compact</span>”</span> format used when
+ it is off. It is on by default.
+ </p></dd><dt id="GUC-LOG-AUTOVACUUM-MIN-DURATION"><span class="term"><code class="varname">log_autovacuum_min_duration</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.5.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes each action executed by autovacuum to be logged if it ran for at
+ least the specified amount of time. Setting this to zero logs
+ all autovacuum actions. <code class="literal">-1</code> disables logging autovacuum
+ actions. If this value is specified without units, it is taken as milliseconds.
+ For example, if you set this to
+ <code class="literal">250ms</code> then all automatic vacuums and analyzes that run
+ 250ms or longer will be logged. In addition, when this parameter is
+ set to any value other than <code class="literal">-1</code>, a message will be
+ logged if an autovacuum action is skipped due to a conflicting lock or a
+ concurrently dropped relation. The default is <code class="literal">10min</code>.
+ Enabling this parameter can be helpful in tracking autovacuum activity.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line; but the setting can be overridden for
+ individual tables by changing table storage parameters.
+ </p></dd><dt id="GUC-LOG-CHECKPOINTS"><span class="term"><code class="varname">log_checkpoints</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes checkpoints and restartpoints to be logged in the server log.
+ Some statistics are included in the log messages, including the number
+ of buffers written and the time spent writing them.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line. The default is on.
+ </p></dd><dt id="GUC-LOG-CONNECTIONS"><span class="term"><code class="varname">log_connections</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes each attempted connection to the server to be logged,
+ as well as successful completion of both client authentication (if
+ necessary) and authorization.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this parameter at session start,
+ and it cannot be changed at all within a session.
+ The default is <code class="literal">off</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Some client programs, like <span class="application">psql</span>, attempt
+ to connect twice while determining if a password is required, so
+ duplicate <span class="quote">“<span class="quote">connection received</span>”</span> messages do not
+ necessarily indicate a problem.
+ </p></div></dd><dt id="GUC-LOG-DISCONNECTIONS"><span class="term"><code class="varname">log_disconnections</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes session terminations to be logged. The log output
+ provides information similar to <code class="varname">log_connections</code>,
+ plus the duration of the session.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this parameter at session start,
+ and it cannot be changed at all within a session.
+ The default is <code class="literal">off</code>.
+ </p></dd><dt id="GUC-LOG-DURATION"><span class="term"><code class="varname">log_duration</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes the duration of every completed statement to be logged.
+ The default is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ For clients using extended query protocol, durations of the Parse,
+ Bind, and Execute steps are logged independently.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The difference between enabling <code class="varname">log_duration</code> and setting
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-DURATION-STATEMENT">log_min_duration_statement</a> to zero is that
+ exceeding <code class="varname">log_min_duration_statement</code> forces the text of
+ the query to be logged, but this option doesn't. Thus, if
+ <code class="varname">log_duration</code> is <code class="literal">on</code> and
+ <code class="varname">log_min_duration_statement</code> has a positive value, all
+ durations are logged but the query text is included only for
+ statements exceeding the threshold. This behavior can be useful for
+ gathering statistics in high-load installations.
+ </p></div></dd><dt id="GUC-LOG-ERROR-VERBOSITY"><span class="term"><code class="varname">log_error_verbosity</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.11.5.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the amount of detail written in the server log for each
+ message that is logged. Valid values are <code class="literal">TERSE</code>,
+ <code class="literal">DEFAULT</code>, and <code class="literal">VERBOSE</code>, each adding more
+ fields to displayed messages. <code class="literal">TERSE</code> excludes
+ the logging of <code class="literal">DETAIL</code>, <code class="literal">HINT</code>,
+ <code class="literal">QUERY</code>, and <code class="literal">CONTEXT</code> error information.
+ <code class="literal">VERBOSE</code> output includes the <code class="symbol">SQLSTATE</code> error
+ code (see also <a class="xref" href="errcodes-appendix.html" title="Appendix A. PostgreSQL Error Codes">Appendix A</a>) and the source code file name, function name,
+ and line number that generated the error.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-HOSTNAME"><span class="term"><code class="varname">log_hostname</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ By default, connection log messages only show the IP address of the
+ connecting host. Turning this parameter on causes logging of the
+ host name as well. Note that depending on your host name resolution
+ setup this might impose a non-negligible performance penalty.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-LOG-LINE-PREFIX"><span class="term"><code class="varname">log_line_prefix</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.5.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This is a <code class="function">printf</code>-style string that is output at the
+ beginning of each log line.
+ <code class="literal">%</code> characters begin <span class="quote">“<span class="quote">escape sequences</span>”</span>
+ that are replaced with status information as outlined below.
+ Unrecognized escapes are ignored. Other
+ characters are copied straight to the log line. Some escapes are
+ only recognized by session processes, and will be treated as empty by
+ background processes such as the main server process. Status
+ information may be aligned either left or right by specifying a
+ numeric literal after the % and before the option. A negative
+ value will cause the status information to be padded on the
+ right with spaces to give it a minimum width, whereas a positive
+ value will pad on the left. Padding can be useful to aid human
+ readability in log files.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line. The default is
+ <code class="literal">'%m [%p] '</code> which logs a time stamp and the process ID.
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Escape</th><th>Effect</th><th>Session only</th></tr></thead><tbody><tr><td><code class="literal">%a</code></td><td>Application name</td><td>yes</td></tr><tr><td><code class="literal">%u</code></td><td>User name</td><td>yes</td></tr><tr><td><code class="literal">%d</code></td><td>Database name</td><td>yes</td></tr><tr><td><code class="literal">%r</code></td><td>Remote host name or IP address, and remote port</td><td>yes</td></tr><tr><td><code class="literal">%h</code></td><td>Remote host name or IP address</td><td>yes</td></tr><tr><td><code class="literal">%b</code></td><td>Backend type</td><td>no</td></tr><tr><td><code class="literal">%p</code></td><td>Process ID</td><td>no</td></tr><tr><td><code class="literal">%P</code></td><td>Process ID of the parallel group leader, if this process
+ is a parallel query worker</td><td>no</td></tr><tr><td><code class="literal">%t</code></td><td>Time stamp without milliseconds</td><td>no</td></tr><tr><td><code class="literal">%m</code></td><td>Time stamp with milliseconds</td><td>no</td></tr><tr><td><code class="literal">%n</code></td><td>Time stamp with milliseconds (as a Unix epoch)</td><td>no</td></tr><tr><td><code class="literal">%i</code></td><td>Command tag: type of session's current command</td><td>yes</td></tr><tr><td><code class="literal">%e</code></td><td>SQLSTATE error code</td><td>no</td></tr><tr><td><code class="literal">%c</code></td><td>Session ID: see below</td><td>no</td></tr><tr><td><code class="literal">%l</code></td><td>Number of the log line for each session or process, starting at 1</td><td>no</td></tr><tr><td><code class="literal">%s</code></td><td>Process start time stamp</td><td>no</td></tr><tr><td><code class="literal">%v</code></td><td>Virtual transaction ID (backendID/localXID)</td><td>no</td></tr><tr><td><code class="literal">%x</code></td><td>Transaction ID (0 if none is assigned)</td><td>no</td></tr><tr><td><code class="literal">%q</code></td><td>Produces no output, but tells non-session
+ processes to stop at this point in the string; ignored by
+ session processes</td><td>no</td></tr><tr><td><code class="literal">%Q</code></td><td>Query identifier of the current query. Query
+ identifiers are not computed by default, so this field
+ will be zero unless <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a>
+ parameter is enabled or a third-party module that computes
+ query identifiers is configured.</td><td>yes</td></tr><tr><td><code class="literal">%%</code></td><td>Literal <code class="literal">%</code></td><td>no</td></tr></tbody></table></div><p>
+ The backend type corresponds to the column
+ <code class="structfield">backend_type</code> in the view
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">
+ <code class="structname">pg_stat_activity</code></a>,
+ but additional types can appear
+ in the log that don't show in that view.
+ </p><p>
+ The <code class="literal">%c</code> escape prints a quasi-unique session identifier,
+ consisting of two 4-byte hexadecimal numbers (without leading zeros)
+ separated by a dot. The numbers are the process start time and the
+ process ID, so <code class="literal">%c</code> can also be used as a space saving way
+ of printing those items. For example, to generate the session
+ identifier from <code class="literal">pg_stat_activity</code>, use this query:
+</p><pre class="programlisting">
+SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' ||
+ to_hex(pid)
+FROM pg_stat_activity;
+</pre><p>
+
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ If you set a nonempty value for <code class="varname">log_line_prefix</code>,
+ you should usually make its last character be a space, to provide
+ visual separation from the rest of the log line. A punctuation
+ character can be used too.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ <span class="application">Syslog</span> produces its own
+ time stamp and process ID information, so you probably do not want to
+ include those escapes if you are logging to <span class="application">syslog</span>.
+ </p></div><div class="tip"><h3 class="title">Tip</h3><p>
+ The <code class="literal">%q</code> escape is useful when including information that is
+ only available in session (backend) context like user or database
+ name. For example:
+</p><pre class="programlisting">
+log_line_prefix = '%m [%p] %q%u@%d/%a '
+</pre><p>
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="literal">%Q</code> escape always reports a zero identifier
+ for lines output by <a class="xref" href="runtime-config-logging.html#GUC-LOG-STATEMENT">log_statement</a> because
+ <code class="varname">log_statement</code> generates output before an
+ identifier can be calculated, including invalid statements for
+ which an identifier cannot be calculated.
+ </p></div></dd><dt id="GUC-LOG-LOCK-WAITS"><span class="term"><code class="varname">log_lock_waits</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls whether a log message is produced when a session waits
+ longer than <a class="xref" href="runtime-config-locks.html#GUC-DEADLOCK-TIMEOUT">deadlock_timeout</a> to acquire a
+ lock. This is useful in determining if lock waits are causing
+ poor performance. The default is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-RECOVERY-CONFLICT-WAITS"><span class="term"><code class="varname">log_recovery_conflict_waits</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls whether a log message is produced when the startup process
+ waits longer than <code class="varname">deadlock_timeout</code>
+ for recovery conflicts. This is useful in determining if recovery
+ conflicts prevent the recovery from applying WAL.
+ </p><p>
+ The default is <code class="literal">off</code>. This parameter can only be set
+ in the <code class="filename">postgresql.conf</code> file or on the server
+ command line.
+ </p></dd><dt id="GUC-LOG-PARAMETER-MAX-LENGTH"><span class="term"><code class="varname">log_parameter_max_length</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.5.3.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If greater than zero, each bind parameter value logged with a
+ non-error statement-logging message is trimmed to this many bytes.
+ Zero disables logging of bind parameters for non-error statement logs.
+ <code class="literal">-1</code> (the default) allows bind parameters to be
+ logged in full.
+ If this value is specified without units, it is taken as bytes.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ This setting only affects log messages printed as a result of
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-STATEMENT">log_statement</a>,
+ <a class="xref" href="runtime-config-logging.html#GUC-LOG-DURATION">log_duration</a>, and related settings. Non-zero
+ values of this setting add some overhead, particularly if parameters
+ are sent in binary form, since then conversion to text is required.
+ </p></dd><dt id="GUC-LOG-PARAMETER-MAX-LENGTH-ON-ERROR"><span class="term"><code class="varname">log_parameter_max_length_on_error</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.5.3.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If greater than zero, each bind parameter value reported in error
+ messages is trimmed to this many bytes.
+ Zero (the default) disables including bind parameters in error
+ messages.
+ <code class="literal">-1</code> allows bind parameters to be printed in full.
+ If this value is specified without units, it is taken as bytes.
+ </p><p>
+ Non-zero values of this setting add overhead, as
+ <span class="productname">PostgreSQL</span> will need to store textual
+ representations of parameter values in memory at the start of each
+ statement, whether or not an error eventually occurs. The overhead
+ is greater when bind parameters are sent in binary form than when
+ they are sent as text, since the former case requires data
+ conversion while the latter only requires copying the string.
+ </p></dd><dt id="GUC-LOG-STATEMENT"><span class="term"><code class="varname">log_statement</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.11.5.3.16.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls which SQL statements are logged. Valid values are
+ <code class="literal">none</code> (off), <code class="literal">ddl</code>, <code class="literal">mod</code>, and
+ <code class="literal">all</code> (all statements). <code class="literal">ddl</code> logs all data definition
+ statements, such as <code class="command">CREATE</code>, <code class="command">ALTER</code>, and
+ <code class="command">DROP</code> statements. <code class="literal">mod</code> logs all
+ <code class="literal">ddl</code> statements, plus data-modifying statements
+ such as <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, <code class="command">TRUNCATE</code>,
+ and <code class="command">COPY FROM</code>.
+ <code class="command">PREPARE</code>, <code class="command">EXECUTE</code>, and
+ <code class="command">EXPLAIN ANALYZE</code> statements are also logged if their
+ contained command is of an appropriate type. For clients using
+ extended query protocol, logging occurs when an Execute message
+ is received, and values of the Bind parameters are included
+ (with any embedded single-quote marks doubled).
+ </p><p>
+ The default is <code class="literal">none</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Statements that contain simple syntax errors are not logged
+ even by the <code class="varname">log_statement</code> = <code class="literal">all</code> setting,
+ because the log message is emitted only after basic parsing has
+ been done to determine the statement type. In the case of extended
+ query protocol, this setting likewise does not log statements that
+ fail before the Execute phase (i.e., during parse analysis or
+ planning). Set <code class="varname">log_min_error_statement</code> to
+ <code class="literal">ERROR</code> (or lower) to log such statements.
+ </p><p>
+ Logged statements might reveal sensitive data and even contain
+ plaintext passwords.
+ </p></div></dd><dt id="GUC-LOG-REPLICATION-COMMANDS"><span class="term"><code class="varname">log_replication_commands</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.5.3.17.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Causes each replication command to be logged in the server log.
+ See <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a> for more information about
+ replication command. The default value is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-TEMP-FILES"><span class="term"><code class="varname">log_temp_files</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.11.5.3.18.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls logging of temporary file names and sizes.
+ Temporary files can be
+ created for sorts, hashes, and temporary query results.
+ If enabled by this setting, a log entry is emitted for each
+ temporary file when it is deleted.
+ A value of zero logs all temporary file information, while positive
+ values log only files whose size is greater than or equal to
+ the specified amount of data.
+ If this value is specified without units, it is taken as kilobytes.
+ The default setting is -1, which disables such logging.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-LOG-TIMEZONE"><span class="term"><code class="varname">log_timezone</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.5.3.19.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the time zone used for timestamps written in the server log.
+ Unlike <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a>, this value is cluster-wide,
+ so that all sessions will report timestamps consistently.
+ The built-in default is <code class="literal">GMT</code>, but that is typically
+ overridden in <code class="filename">postgresql.conf</code>; <span class="application">initdb</span>
+ will install a setting there corresponding to its system environment.
+ See <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a> for more information.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-LOGGING-CSVLOG"><div class="titlepage"><div><div><h3 class="title">20.8.4. Using CSV-Format Log Output</h3></div></div></div><p>
+ Including <code class="literal">csvlog</code> in the <code class="varname">log_destination</code> list
+ provides a convenient way to import log files into a database table.
+ This option emits log lines in comma-separated-values
+ (<acronym class="acronym">CSV</acronym>) format,
+ with these columns:
+ time stamp with milliseconds,
+ user name,
+ database name,
+ process ID,
+ client host:port number,
+ session ID,
+ per-session line number,
+ command tag,
+ session start time,
+ virtual transaction ID,
+ regular transaction ID,
+ error severity,
+ SQLSTATE code,
+ error message,
+ error message detail,
+ hint,
+ internal query that led to the error (if any),
+ character count of the error position therein,
+ error context,
+ user query that led to the error (if any and enabled by
+ <code class="varname">log_min_error_statement</code>),
+ character count of the error position therein,
+ location of the error in the PostgreSQL source code
+ (if <code class="varname">log_error_verbosity</code> is set to <code class="literal">verbose</code>),
+ application name, backend type, process ID of parallel group leader,
+ and query id.
+ Here is a sample table definition for storing CSV-format log output:
+
+</p><pre class="programlisting">
+CREATE TABLE postgres_log
+(
+ log_time timestamp(3) with time zone,
+ user_name text,
+ database_name text,
+ process_id integer,
+ connection_from text,
+ session_id text,
+ session_line_num bigint,
+ command_tag text,
+ session_start_time timestamp with time zone,
+ virtual_transaction_id text,
+ transaction_id bigint,
+ error_severity text,
+ sql_state_code text,
+ message text,
+ detail text,
+ hint text,
+ internal_query text,
+ internal_query_pos integer,
+ context text,
+ query text,
+ query_pos integer,
+ location text,
+ application_name text,
+ backend_type text,
+ leader_pid integer,
+ query_id bigint,
+ PRIMARY KEY (session_id, session_line_num)
+);
+</pre><p>
+ </p><p>
+ To import a log file into this table, use the <code class="command">COPY FROM</code>
+ command:
+
+</p><pre class="programlisting">
+COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
+</pre><p>
+ It is also possible to access the file as a foreign table, using
+ the supplied <a class="xref" href="file-fdw.html" title="F.16. file_fdw">file_fdw</a> module.
+ </p><p>
+ There are a few things you need to do to simplify importing CSV log
+ files:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Set <code class="varname">log_filename</code> and
+ <code class="varname">log_rotation_age</code> to provide a consistent,
+ predictable naming scheme for your log files. This lets you
+ predict what the file name will be and know when an individual log
+ file is complete and therefore ready to be imported.
+ </p></li><li class="listitem"><p>
+ Set <code class="varname">log_rotation_size</code> to 0 to disable
+ size-based log rotation, as it makes the log file name difficult
+ to predict.
+ </p></li><li class="listitem"><p>
+ Set <code class="varname">log_truncate_on_rotation</code> to <code class="literal">on</code> so
+ that old log data isn't mixed with the new in the same file.
+ </p></li><li class="listitem"><p>
+ The table definition above includes a primary key specification.
+ This is useful to protect against accidentally importing the same
+ information twice. The <code class="command">COPY</code> command commits all of the
+ data it imports at one time, so any error will cause the entire
+ import to fail. If you import a partial log file and later import
+ the file again when it is complete, the primary key violation will
+ cause the import to fail. Wait until the log is complete and
+ closed before importing. This procedure will also protect against
+ accidentally importing a partial line that hasn't been completely
+ written, which would also cause <code class="command">COPY</code> to fail.
+ </p></li></ol></div><p>
+ </p></div><div class="sect2" id="RUNTIME-CONFIG-LOGGING-JSONLOG"><div class="titlepage"><div><div><h3 class="title">20.8.5. Using JSON-Format Log Output</h3></div></div></div><p>
+ Including <code class="literal">jsonlog</code> in the
+ <code class="varname">log_destination</code> list provides a convenient way to
+ import log files into many different programs. This option emits log
+ lines in <acronym class="acronym">JSON</acronym> format.
+ </p><p>
+ String fields with null values are excluded from output.
+ Additional fields may be added in the future. User applications that
+ process <code class="literal">jsonlog</code> output should ignore unknown fields.
+ </p><p>
+ Each log line is serialized as a JSON object with the set of keys and
+ their associated values shown in <a class="xref" href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-JSONLOG-KEYS-VALUES" title="Table 20.3. Keys and Values of JSON Log Entries">Table 20.3</a>.
+ </p><div class="table" id="RUNTIME-CONFIG-LOGGING-JSONLOG-KEYS-VALUES"><p class="title"><strong>Table 20.3. Keys and Values of JSON Log Entries</strong></p><div class="table-contents"><table class="table" summary="Keys and Values of JSON Log Entries" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Key name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">timestamp</code></td><td>string</td><td>Time stamp with milliseconds</td></tr><tr><td><code class="literal">user</code></td><td>string</td><td>User name</td></tr><tr><td><code class="literal">dbname</code></td><td>string</td><td>Database name</td></tr><tr><td><code class="literal">pid</code></td><td>number</td><td>Process ID</td></tr><tr><td><code class="literal">remote_host</code></td><td>string</td><td>Client host</td></tr><tr><td><code class="literal">remote_port</code></td><td>number</td><td>Client port</td></tr><tr><td><code class="literal">session_id</code></td><td>string</td><td>Session ID</td></tr><tr><td><code class="literal">line_num</code></td><td>number</td><td>Per-session line number</td></tr><tr><td><code class="literal">ps</code></td><td>string</td><td>Current ps display</td></tr><tr><td><code class="literal">session_start</code></td><td>string</td><td>Session start time</td></tr><tr><td><code class="literal">vxid</code></td><td>string</td><td>Virtual transaction ID</td></tr><tr><td><code class="literal">txid</code></td><td>string</td><td>Regular transaction ID</td></tr><tr><td><code class="literal">error_severity</code></td><td>string</td><td>Error severity</td></tr><tr><td><code class="literal">state_code</code></td><td>string</td><td>SQLSTATE code</td></tr><tr><td><code class="literal">message</code></td><td>string</td><td>Error message</td></tr><tr><td><code class="literal">detail</code></td><td>string</td><td>Error message detail</td></tr><tr><td><code class="literal">hint</code></td><td>string</td><td>Error message hint</td></tr><tr><td><code class="literal">internal_query</code></td><td>string</td><td>Internal query that led to the error</td></tr><tr><td><code class="literal">internal_position</code></td><td>number</td><td>Cursor index into internal query</td></tr><tr><td><code class="literal">context</code></td><td>string</td><td>Error context</td></tr><tr><td><code class="literal">statement</code></td><td>string</td><td>Client-supplied query string</td></tr><tr><td><code class="literal">cursor_position</code></td><td>number</td><td>Cursor index into query string</td></tr><tr><td><code class="literal">func_name</code></td><td>string</td><td>Error location function name</td></tr><tr><td><code class="literal">file_name</code></td><td>string</td><td>File name of error location</td></tr><tr><td><code class="literal">file_line_num</code></td><td>number</td><td>File line number of the error location</td></tr><tr><td><code class="literal">application_name</code></td><td>string</td><td>Client application name</td></tr><tr><td><code class="literal">backend_type</code></td><td>string</td><td>Type of backend</td></tr><tr><td><code class="literal">leader_pid</code></td><td>number</td><td>Process ID of leader for active parallel workers</td></tr><tr><td><code class="literal">query_id</code></td><td>number</td><td>Query ID</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.6.7.11.8"><div class="titlepage"><div><div><h3 class="title">20.8.6. Process Title</h3></div></div></div><p>
+ These settings control how process titles of server processes are
+ modified. Process titles are typically viewed using programs like
+ <span class="application">ps</span> or, on Windows, <span class="application">Process Explorer</span>.
+ See <a class="xref" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Section 28.1</a> for details.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-CLUSTER-NAME"><span class="term"><code class="varname">cluster_name</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.11.8.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets a name that identifies this database cluster (instance) for
+ various purposes. The cluster name appears in the process title for
+ all server processes in this cluster. Moreover, it is the default
+ application name for a standby connection (see <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a>.)
+ </p><p>
+ The name can be any string of less
+ than <code class="symbol">NAMEDATALEN</code> characters (64 characters in a standard
+ build). Only printable ASCII characters may be used in the
+ <code class="varname">cluster_name</code> value. Other characters will be
+ replaced with question marks (<code class="literal">?</code>). No name is shown
+ if this parameter is set to the empty string <code class="literal">''</code> (which is
+ the default). This parameter can only be set at server start.
+ </p></dd><dt id="GUC-UPDATE-PROCESS-TITLE"><span class="term"><code class="varname">update_process_title</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.11.8.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables updating of the process title every time a new SQL command
+ is received by the server.
+ This setting defaults to <code class="literal">on</code> on most platforms, but it
+ defaults to <code class="literal">off</code> on Windows due to that platform's larger
+ overhead for updating the process title.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-query.html" title="20.7. Query Planning">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-statistics.html" title="20.9. Run-time Statistics">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.7. Query Planning </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.9. Run-time Statistics</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-preset.html b/doc/src/sgml/html/runtime-config-preset.html
new file mode 100644
index 0000000..ae4d3da
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-preset.html
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.15. Preset Options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-error-handling.html" title="20.14. Error Handling" /><link rel="next" href="runtime-config-custom.html" title="20.16. Customized Options" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.15. Preset Options</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-error-handling.html" title="20.14. Error Handling">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-custom.html" title="20.16. Customized Options">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-PRESET"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.15. Preset Options</h2></div></div></div><p>
+ The following <span class="quote">“<span class="quote">parameters</span>”</span> are read-only.
+ As such, they have been excluded from the sample
+ <code class="filename">postgresql.conf</code> file. These options report
+ various aspects of <span class="productname">PostgreSQL</span> behavior
+ that might be of interest to certain applications, particularly
+ administrative front-ends.
+ Most of them are determined when <span class="productname">PostgreSQL</span>
+ is compiled or when it is installed.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-BLOCK-SIZE"><span class="term"><code class="varname">block_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the size of a disk block. It is determined by the value
+ of <code class="literal">BLCKSZ</code> when building the server. The default
+ value is 8192 bytes. The meaning of some configuration
+ variables (such as <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>) is
+ influenced by <code class="varname">block_size</code>. See <a class="xref" href="runtime-config-resource.html" title="20.4. Resource Consumption">Section 20.4</a> for information.
+ </p></dd><dt id="GUC-DATA-CHECKSUMS"><span class="term"><code class="varname">data_checksums</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.18.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports whether data checksums are enabled for this cluster.
+ See <a class="xref" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS">data checksums</a> for more information.
+ </p></dd><dt id="GUC-DATA-DIRECTORY-MODE"><span class="term"><code class="varname">data_directory_mode</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ On Unix systems this parameter reports the permissions the data
+ directory (defined by <a class="xref" href="runtime-config-file-locations.html#GUC-DATA-DIRECTORY">data_directory</a>)
+ had at server startup.
+ (On Microsoft Windows this parameter will always display
+ <code class="literal">0700</code>.) See
+ <a class="xref" href="app-initdb.html#APP-INITDB-ALLOW-GROUP-ACCESS">group access</a> for more information.
+ </p></dd><dt id="GUC-DEBUG-ASSERTIONS"><span class="term"><code class="varname">debug_assertions</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.18.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports whether <span class="productname">PostgreSQL</span> has been built
+ with assertions enabled. That is the case if the
+ macro <code class="symbol">USE_ASSERT_CHECKING</code> is defined
+ when <span class="productname">PostgreSQL</span> is built (accomplished
+ e.g., by the <code class="command">configure</code> option
+ <code class="option">--enable-cassert</code>). By
+ default <span class="productname">PostgreSQL</span> is built without
+ assertions.
+ </p></dd><dt id="GUC-INTEGER-DATETIMES"><span class="term"><code class="varname">integer_datetimes</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.18.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports whether <span class="productname">PostgreSQL</span> was built with support for
+ 64-bit-integer dates and times. As of <span class="productname">PostgreSQL</span> 10,
+ this is always <code class="literal">on</code>.
+ </p></dd><dt id="GUC-IN-HOT-STANDBY"><span class="term"><code class="varname">in_hot_standby</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.18.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports whether the server is currently in hot standby mode. When
+ this is <code class="literal">on</code>, all transactions are forced to be
+ read-only. Within a session, this can change only if the server is
+ promoted to be primary. See <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a> for more
+ information.
+ </p></dd><dt id="GUC-LC-COLLATE"><span class="term"><code class="varname">lc_collate</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.18.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the locale in which sorting of textual data is done.
+ See <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> for more information.
+ This value is determined when a database is created.
+ </p></dd><dt id="GUC-LC-CTYPE"><span class="term"><code class="varname">lc_ctype</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.18.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the locale that determines character classifications.
+ See <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a> for more information.
+ This value is determined when a database is created.
+ Ordinarily this will be the same as <code class="varname">lc_collate</code>,
+ but for special applications it might be set differently.
+ </p></dd><dt id="GUC-MAX-FUNCTION-ARGS"><span class="term"><code class="varname">max_function_args</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the maximum number of function arguments. It is determined by
+ the value of <code class="literal">FUNC_MAX_ARGS</code> when building the server. The
+ default value is 100 arguments.
+ </p></dd><dt id="GUC-MAX-IDENTIFIER-LENGTH"><span class="term"><code class="varname">max_identifier_length</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the maximum identifier length. It is determined as one
+ less than the value of <code class="literal">NAMEDATALEN</code> when building
+ the server. The default value of <code class="literal">NAMEDATALEN</code> is
+ 64; therefore the default
+ <code class="varname">max_identifier_length</code> is 63 bytes, which
+ can be less than 63 characters when using multibyte encodings.
+ </p></dd><dt id="GUC-MAX-INDEX-KEYS"><span class="term"><code class="varname">max_index_keys</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the maximum number of index keys. It is determined by
+ the value of <code class="literal">INDEX_MAX_KEYS</code> when building the server. The
+ default value is 32 keys.
+ </p></dd><dt id="GUC-SEGMENT-SIZE"><span class="term"><code class="varname">segment_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the number of blocks (pages) that can be stored within a file
+ segment. It is determined by the value of <code class="literal">RELSEG_SIZE</code>
+ when building the server. The maximum size of a segment file in bytes
+ is equal to <code class="varname">segment_size</code> multiplied by
+ <code class="varname">block_size</code>; by default this is 1GB.
+ </p></dd><dt id="GUC-SERVER-ENCODING"><span class="term"><code class="varname">server_encoding</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.18.3.13.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.18.3.13.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the database encoding (character set).
+ It is determined when the database is created. Ordinarily,
+ clients need only be concerned with the value of <a class="xref" href="runtime-config-client.html#GUC-CLIENT-ENCODING">client_encoding</a>.
+ </p></dd><dt id="GUC-SERVER-VERSION"><span class="term"><code class="varname">server_version</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.18.3.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the version number of the server. It is determined by the
+ value of <code class="literal">PG_VERSION</code> when building the server.
+ </p></dd><dt id="GUC-SERVER-VERSION-NUM"><span class="term"><code class="varname">server_version_num</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the version number of the server as an integer. It is determined
+ by the value of <code class="literal">PG_VERSION_NUM</code> when building the server.
+ </p></dd><dt id="GUC-SHARED-MEMORY-SIZE"><span class="term"><code class="varname">shared_memory_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.16.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the size of the main shared memory area, rounded up to the
+ nearest megabyte.
+ </p></dd><dt id="GUC-SHARED-MEMORY-SIZE-IN-HUGE-PAGES"><span class="term"><code class="varname">shared_memory_size_in_huge_pages</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.17.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the number of huge pages that are needed for the main shared
+ memory area based on the specified <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGE-SIZE">huge_page_size</a>.
+ If huge pages are not supported, this will be <code class="literal">-1</code>.
+ </p><p>
+ This setting is supported only on <span class="productname">Linux</span>. It
+ is always set to <code class="literal">-1</code> on other platforms. For more
+ details about using huge pages on <span class="productname">Linux</span>, see
+ <a class="xref" href="kernel-resources.html#LINUX-HUGE-PAGES" title="19.4.5. Linux Huge Pages">Section 19.4.5</a>.
+ </p></dd><dt id="GUC-SSL-LIBRARY"><span class="term"><code class="varname">ssl_library</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.18.3.18.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the name of the SSL library that this
+ <span class="productname">PostgreSQL</span> server was built with (even if
+ SSL is not currently configured or in use on this instance), for
+ example <code class="literal">OpenSSL</code>, or an empty string if none.
+ </p></dd><dt id="GUC-WAL-BLOCK-SIZE"><span class="term"><code class="varname">wal_block_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.19.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the size of a WAL disk block. It is determined by the value
+ of <code class="literal">XLOG_BLCKSZ</code> when building the server. The default value
+ is 8192 bytes.
+ </p></dd><dt id="GUC-WAL-SEGMENT-SIZE"><span class="term"><code class="varname">wal_segment_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.18.3.20.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Reports the size of write ahead log segments. The default value is
+ 16MB. See <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a> for more information.
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-error-handling.html" title="20.14. Error Handling">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-custom.html" title="20.16. Customized Options">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.14. Error Handling </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.16. Customized Options</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-query.html b/doc/src/sgml/html/runtime-config-query.html
new file mode 100644
index 0000000..71b2ccd
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-query.html
@@ -0,0 +1,544 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.7. Query Planning</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-replication.html" title="20.6. Replication" /><link rel="next" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.7. Query Planning</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-replication.html" title="20.6. Replication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-QUERY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.7. Query Planning</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">20.7.1. Planner Method Configuration</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">20.7.2. Planner Cost Constants</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">20.7.3. Genetic Query Optimizer</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">20.7.4. Other Planner Options</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-QUERY-ENABLE"><div class="titlepage"><div><div><h3 class="title">20.7.1. Planner Method Configuration</h3></div></div></div><p>
+ These configuration parameters provide a crude method of
+ influencing the query plans chosen by the query optimizer. If
+ the default plan chosen by the optimizer for a particular query
+ is not optimal, a <span class="emphasis"><em>temporary</em></span> solution is to use one
+ of these configuration parameters to force the optimizer to
+ choose a different plan.
+ Better ways to improve the quality of the
+ plans chosen by the optimizer include adjusting the planner cost
+ constants (see <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS" title="20.7.2. Planner Cost Constants">Section 20.7.2</a>),
+ running <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> manually, increasing
+ the value of the <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> configuration parameter,
+ and increasing the amount of statistics collected for
+ specific columns using <code class="command">ALTER TABLE SET
+ STATISTICS</code>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-ENABLE-ASYNC-APPEND"><span class="term"><code class="varname">enable_async_append</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of async-aware
+ append plan types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-BITMAPSCAN"><span class="term"><code class="varname">enable_bitmapscan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.2.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.10.2.3.2.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of bitmap-scan plan
+ types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-GATHERMERGE"><span class="term"><code class="varname">enable_gathermerge</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of gather
+ merge plan types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-HASHAGG"><span class="term"><code class="varname">enable_hashagg</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of hashed
+ aggregation plan types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-HASHJOIN"><span class="term"><code class="varname">enable_hashjoin</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of hash-join plan
+ types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-INCREMENTAL-SORT"><span class="term"><code class="varname">enable_incremental_sort</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of incremental sort steps.
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-INDEXSCAN"><span class="term"><code class="varname">enable_indexscan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.7.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.10.2.3.7.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of index-scan plan
+ types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-INDEXONLYSCAN"><span class="term"><code class="varname">enable_indexonlyscan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of index-only-scan plan
+ types (see <a class="xref" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">Section 11.9</a>).
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-MATERIAL"><span class="term"><code class="varname">enable_material</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of materialization.
+ It is impossible to suppress materialization entirely,
+ but turning this variable off prevents the planner from inserting
+ materialize nodes except in cases where it is required for correctness.
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-MEMOIZE"><span class="term"><code class="varname">enable_memoize</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of memoize plans for
+ caching results from parameterized scans inside nested-loop joins.
+ This plan type allows scans to the underlying plans to be skipped when
+ the results for the current parameters are already in the cache. Less
+ commonly looked up results may be evicted from the cache when more
+ space is required for new entries. The default is
+ <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-MERGEJOIN"><span class="term"><code class="varname">enable_mergejoin</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of merge-join plan
+ types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-NESTLOOP"><span class="term"><code class="varname">enable_nestloop</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of nested-loop join
+ plans. It is impossible to suppress nested-loop joins entirely,
+ but turning this variable off discourages the planner from using
+ one if there are other methods available. The default is
+ <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-PARALLEL-APPEND"><span class="term"><code class="varname">enable_parallel_append</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of parallel-aware
+ append plan types. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-PARALLEL-HASH"><span class="term"><code class="varname">enable_parallel_hash</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of hash-join plan
+ types with parallel hash. Has no effect if hash-join plans are not
+ also enabled. The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-PARTITION-PRUNING"><span class="term"><code class="varname">enable_partition_pruning</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's ability to eliminate a
+ partitioned table's partitions from query plans. This also controls
+ the planner's ability to generate query plans which allow the query
+ executor to remove (ignore) partitions during query execution. The
+ default is <code class="literal">on</code>.
+ See <a class="xref" href="ddl-partitioning.html#DDL-PARTITION-PRUNING" title="5.11.4. Partition Pruning">Section 5.11.4</a> for details.
+ </p></dd><dt id="GUC-ENABLE-PARTITIONWISE-JOIN"><span class="term"><code class="varname">enable_partitionwise_join</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.16.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of partitionwise join,
+ which allows a join between partitioned tables to be performed by
+ joining the matching partitions. Partitionwise join currently applies
+ only when the join conditions include all the partition keys, which
+ must be of the same data type and have one-to-one matching sets of
+ child partitions. Because partitionwise join planning can use
+ significantly more CPU time and memory during planning, the default is
+ <code class="literal">off</code>.
+ </p></dd><dt id="GUC-ENABLE-PARTITIONWISE-AGGREGATE"><span class="term"><code class="varname">enable_partitionwise_aggregate</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.17.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of partitionwise grouping
+ or aggregation, which allows grouping or aggregation on partitioned
+ tables to be performed separately for each partition. If the
+ <code class="literal">GROUP BY</code> clause does not include the partition
+ keys, only partial aggregation can be performed on a per-partition
+ basis, and finalization must be performed later. Because
+ partitionwise grouping or aggregation can use significantly more CPU
+ time and memory during planning, the default is
+ <code class="literal">off</code>.
+ </p></dd><dt id="GUC-ENABLE-SEQSCAN"><span class="term"><code class="varname">enable_seqscan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.18.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.10.2.3.18.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of sequential scan
+ plan types. It is impossible to suppress sequential scans
+ entirely, but turning this variable off discourages the planner
+ from using one if there are other methods available. The
+ default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-SORT"><span class="term"><code class="varname">enable_sort</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.19.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of explicit sort
+ steps. It is impossible to suppress explicit sorts entirely,
+ but turning this variable off discourages the planner from
+ using one if there are other methods available. The default
+ is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-ENABLE-TIDSCAN"><span class="term"><code class="varname">enable_tidscan</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.2.3.20.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the query planner's use of <acronym class="acronym">TID</acronym>
+ scan plan types. The default is <code class="literal">on</code>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-QUERY-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">20.7.2. Planner Cost Constants</h3></div></div></div><p>
+ The <em class="firstterm">cost</em> variables described in this section are measured
+ on an arbitrary scale. Only their relative values matter, hence
+ scaling them all up or down by the same factor will result in no change
+ in the planner's choices. By default, these cost variables are based on
+ the cost of sequential page fetches; that is,
+ <code class="varname">seq_page_cost</code> is conventionally set to <code class="literal">1.0</code>
+ and the other cost variables are set with reference to that. But
+ you can use a different scale if you prefer, such as actual execution
+ times in milliseconds on a particular machine.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Unfortunately, there is no well-defined method for determining ideal
+ values for the cost variables. They are best treated as averages over
+ the entire mix of queries that a particular installation will receive. This
+ means that changing them on the basis of just a few experiments is very
+ risky.
+ </p></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-SEQ-PAGE-COST"><span class="term"><code class="varname">seq_page_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of a disk page fetch
+ that is part of a series of sequential fetches. The default is 1.0.
+ This value can be overridden for tables and indexes in a particular
+ tablespace by setting the tablespace parameter of the same name
+ (see <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a>).
+ </p></dd><dt id="GUC-RANDOM-PAGE-COST"><span class="term"><code class="varname">random_page_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of a
+ non-sequentially-fetched disk page. The default is 4.0.
+ This value can be overridden for tables and indexes in a particular
+ tablespace by setting the tablespace parameter of the same name
+ (see <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a>).
+ </p><p>
+ Reducing this value relative to <code class="varname">seq_page_cost</code>
+ will cause the system to prefer index scans; raising it will
+ make index scans look relatively more expensive. You can raise
+ or lower both values together to change the importance of disk I/O
+ costs relative to CPU costs, which are described by the following
+ parameters.
+ </p><p>
+ Random access to mechanical disk storage is normally much more expensive
+ than four times sequential access. However, a lower default is used
+ (4.0) because the majority of random accesses to disk, such as indexed
+ reads, are assumed to be in cache. The default value can be thought of
+ as modeling random access as 40 times slower than sequential, while
+ expecting 90% of random reads to be cached.
+ </p><p>
+ If you believe a 90% cache rate is an incorrect assumption
+ for your workload, you can increase random_page_cost to better
+ reflect the true cost of random storage reads. Correspondingly,
+ if your data is likely to be completely in cache, such as when
+ the database is smaller than the total server memory, decreasing
+ random_page_cost can be appropriate. Storage that has a low random
+ read cost relative to sequential, e.g., solid-state drives, might
+ also be better modeled with a lower value for random_page_cost,
+ e.g., <code class="literal">1.1</code>.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Although the system will let you set <code class="varname">random_page_cost</code> to
+ less than <code class="varname">seq_page_cost</code>, it is not physically sensible
+ to do so. However, setting them equal makes sense if the database
+ is entirely cached in RAM, since in that case there is no penalty
+ for touching pages out of sequence. Also, in a heavily-cached
+ database you should lower both values relative to the CPU parameters,
+ since the cost of fetching a page already in RAM is much smaller
+ than it would normally be.
+ </p></div></dd><dt id="GUC-CPU-TUPLE-COST"><span class="term"><code class="varname">cpu_tuple_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of processing
+ each row during a query.
+ The default is 0.01.
+ </p></dd><dt id="GUC-CPU-INDEX-TUPLE-COST"><span class="term"><code class="varname">cpu_index_tuple_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of processing
+ each index entry during an index scan.
+ The default is 0.005.
+ </p></dd><dt id="GUC-CPU-OPERATOR-COST"><span class="term"><code class="varname">cpu_operator_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of processing each
+ operator or function executed during a query.
+ The default is 0.0025.
+ </p></dd><dt id="GUC-PARALLEL-SETUP-COST"><span class="term"><code class="varname">parallel_setup_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of launching parallel worker
+ processes.
+ The default is 1000.
+ </p></dd><dt id="GUC-PARALLEL-TUPLE-COST"><span class="term"><code class="varname">parallel_tuple_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the cost of transferring one tuple
+ from a parallel worker process to another process.
+ The default is 0.1.
+ </p></dd><dt id="GUC-MIN-PARALLEL-TABLE-SCAN-SIZE"><span class="term"><code class="varname">min_parallel_table_scan_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.3.4.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the minimum amount of table data that must be scanned in order
+ for a parallel scan to be considered. For a parallel sequential scan,
+ the amount of table data scanned is always equal to the size of the
+ table, but when indexes are used the amount of table data
+ scanned will normally be less.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The default is 8 megabytes (<code class="literal">8MB</code>).
+ </p></dd><dt id="GUC-MIN-PARALLEL-INDEX-SCAN-SIZE"><span class="term"><code class="varname">min_parallel_index_scan_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.3.4.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the minimum amount of index data that must be scanned in order
+ for a parallel scan to be considered. Note that a parallel index scan
+ typically won't touch the entire index; it is the number of pages
+ which the planner believes will actually be touched by the scan which
+ is relevant. This parameter is also used to decide whether a
+ particular index can participate in a parallel vacuum. See
+ <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a>.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The default is 512 kilobytes (<code class="literal">512kB</code>).
+ </p></dd><dt id="GUC-EFFECTIVE-CACHE-SIZE"><span class="term"><code class="varname">effective_cache_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.3.4.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's assumption about the effective size of the
+ disk cache that is available to a single query. This is
+ factored into estimates of the cost of using an index; a
+ higher value makes it more likely index scans will be used, a
+ lower value makes it more likely sequential scans will be
+ used. When setting this parameter you should consider both
+ <span class="productname">PostgreSQL</span>'s shared buffers and the
+ portion of the kernel's disk cache that will be used for
+ <span class="productname">PostgreSQL</span> data files, though some
+ data might exist in both places. Also, take
+ into account the expected number of concurrent queries on different
+ tables, since they will have to share the available
+ space. This parameter has no effect on the size of shared
+ memory allocated by <span class="productname">PostgreSQL</span>, nor
+ does it reserve kernel disk cache; it is used only for estimation
+ purposes. The system also does not assume data remains in
+ the disk cache between queries.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The default is 4 gigabytes (<code class="literal">4GB</code>).
+ (If <code class="symbol">BLCKSZ</code> is not 8kB, the default value scales
+ proportionally to it.)
+ </p></dd><dt id="GUC-JIT-ABOVE-COST"><span class="term"><code class="varname">jit_above_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the query cost above which JIT compilation is activated, if
+ enabled (see <a class="xref" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Chapter 32</a>).
+ Performing <acronym class="acronym">JIT</acronym> costs planning time but can
+ accelerate query execution.
+ Setting this to <code class="literal">-1</code> disables JIT compilation.
+ The default is <code class="literal">100000</code>.
+ </p></dd><dt id="GUC-JIT-INLINE-ABOVE-COST"><span class="term"><code class="varname">jit_inline_above_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the query cost above which JIT compilation attempts to inline
+ functions and operators. Inlining adds planning time, but can
+ improve execution speed. It is not meaningful to set this to less
+ than <code class="varname">jit_above_cost</code>.
+ Setting this to <code class="literal">-1</code> disables inlining.
+ The default is <code class="literal">500000</code>.
+ </p></dd><dt id="GUC-JIT-OPTIMIZE-ABOVE-COST"><span class="term"><code class="varname">jit_optimize_above_cost</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.3.4.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the query cost above which JIT compilation applies expensive
+ optimizations. Such optimization adds planning time, but can improve
+ execution speed. It is not meaningful to set this to less
+ than <code class="varname">jit_above_cost</code>, and it is unlikely to be
+ beneficial to set it to more
+ than <code class="varname">jit_inline_above_cost</code>.
+ Setting this to <code class="literal">-1</code> disables expensive optimizations.
+ The default is <code class="literal">500000</code>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-QUERY-GEQO"><div class="titlepage"><div><div><h3 class="title">20.7.3. Genetic Query Optimizer</h3></div></div></div><p>
+ The genetic query optimizer (GEQO) is an algorithm that does query
+ planning using heuristic searching. This reduces planning time for
+ complex queries (those joining many relations), at the cost of producing
+ plans that are sometimes inferior to those found by the normal
+ exhaustive-search algorithm.
+ For more information see <a class="xref" href="geqo.html" title="Chapter 62. Genetic Query Optimizer">Chapter 62</a>.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-GEQO"><span class="term"><code class="varname">geqo</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.4.3.1.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.10.4.3.1.1.4" class="indexterm"></a>
+ <a id="id-1.6.7.10.4.3.1.1.5" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables genetic query optimization.
+ This is on by default. It is usually best not to turn it off in
+ production; the <code class="varname">geqo_threshold</code> variable provides
+ more granular control of GEQO.
+ </p></dd><dt id="GUC-GEQO-THRESHOLD"><span class="term"><code class="varname">geqo_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.4.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Use genetic query optimization to plan queries with at least
+ this many <code class="literal">FROM</code> items involved. (Note that a
+ <code class="literal">FULL OUTER JOIN</code> construct counts as only one <code class="literal">FROM</code>
+ item.) The default is 12. For simpler queries it is usually best
+ to use the regular, exhaustive-search planner, but for queries with
+ many tables the exhaustive search takes too long, often
+ longer than the penalty of executing a suboptimal plan. Thus,
+ a threshold on the size of the query is a convenient way to manage
+ use of GEQO.
+ </p></dd><dt id="GUC-GEQO-EFFORT"><span class="term"><code class="varname">geqo_effort</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.4.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the trade-off between planning time and query plan
+ quality in GEQO. This variable must be an integer in the
+ range from 1 to 10. The default value is five. Larger values
+ increase the time spent doing query planning, but also
+ increase the likelihood that an efficient query plan will be
+ chosen.
+ </p><p>
+ <code class="varname">geqo_effort</code> doesn't actually do anything
+ directly; it is only used to compute the default values for
+ the other variables that influence GEQO behavior (described
+ below). If you prefer, you can set the other parameters by
+ hand instead.
+ </p></dd><dt id="GUC-GEQO-POOL-SIZE"><span class="term"><code class="varname">geqo_pool_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.4.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the pool size used by GEQO, that is the
+ number of individuals in the genetic population. It must be
+ at least two, and useful values are typically 100 to 1000. If
+ it is set to zero (the default setting) then a suitable
+ value is chosen based on <code class="varname">geqo_effort</code> and
+ the number of tables in the query.
+ </p></dd><dt id="GUC-GEQO-GENERATIONS"><span class="term"><code class="varname">geqo_generations</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.4.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the number of generations used by GEQO, that is
+ the number of iterations of the algorithm. It must
+ be at least one, and useful values are in the same range as
+ the pool size. If it is set to zero (the default setting)
+ then a suitable value is chosen based on
+ <code class="varname">geqo_pool_size</code>.
+ </p></dd><dt id="GUC-GEQO-SELECTION-BIAS"><span class="term"><code class="varname">geqo_selection_bias</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.4.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the selection bias used by GEQO. The selection bias
+ is the selective pressure within the population. Values can be
+ from 1.50 to 2.00; the latter is the default.
+ </p></dd><dt id="GUC-GEQO-SEED"><span class="term"><code class="varname">geqo_seed</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.4.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the initial value of the random number generator used
+ by GEQO to select random paths through the join order search space.
+ The value can range from zero (the default) to one. Varying the
+ value changes the set of join paths explored, and may result in a
+ better or worse best path being found.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-QUERY-OTHER"><div class="titlepage"><div><div><h3 class="title">20.7.4. Other Planner Options</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-DEFAULT-STATISTICS-TARGET"><span class="term"><code class="varname">default_statistics_target</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the default statistics target for table columns without
+ a column-specific target set via <code class="command">ALTER TABLE
+ SET STATISTICS</code>. Larger values increase the time needed to
+ do <code class="command">ANALYZE</code>, but might improve the quality of the
+ planner's estimates. The default is 100. For more information
+ on the use of statistics by the <span class="productname">PostgreSQL</span>
+ query planner, refer to <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>.
+ </p></dd><dt id="GUC-CONSTRAINT-EXCLUSION"><span class="term"><code class="varname">constraint_exclusion</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.10.5.2.2.1.3" class="indexterm"></a>
+ <a id="id-1.6.7.10.5.2.2.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the query planner's use of table constraints to
+ optimize queries.
+ The allowed values of <code class="varname">constraint_exclusion</code> are
+ <code class="literal">on</code> (examine constraints for all tables),
+ <code class="literal">off</code> (never examine constraints), and
+ <code class="literal">partition</code> (examine constraints only for inheritance
+ child tables and <code class="literal">UNION ALL</code> subqueries).
+ <code class="literal">partition</code> is the default setting.
+ It is often used with traditional inheritance trees to improve
+ performance.
+ </p><p>
+ When this parameter allows it for a particular table, the planner
+ compares query conditions with the table's <code class="literal">CHECK</code>
+ constraints, and omits scanning tables for which the conditions
+ contradict the constraints. For example:
+
+</p><pre class="programlisting">
+CREATE TABLE parent(key integer, ...);
+CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent);
+CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent);
+...
+SELECT * FROM parent WHERE key = 2400;
+</pre><p>
+
+ With constraint exclusion enabled, this <code class="command">SELECT</code>
+ will not scan <code class="structname">child1000</code> at all, improving performance.
+ </p><p>
+ Currently, constraint exclusion is enabled by default
+ only for cases that are often used to implement table partitioning via
+ inheritance trees. Turning it on for all tables imposes extra
+ planning overhead that is quite noticeable on simple queries, and most
+ often will yield no benefit for simple queries. If you have no
+ tables that are partitioned using traditional inheritance, you might
+ prefer to turn it off entirely. (Note that the equivalent feature for
+ partitioned tables is controlled by a separate parameter,
+ <a class="xref" href="runtime-config-query.html#GUC-ENABLE-PARTITION-PRUNING">enable_partition_pruning</a>.)
+ </p><p>
+ Refer to <a class="xref" href="ddl-partitioning.html#DDL-PARTITIONING-CONSTRAINT-EXCLUSION" title="5.11.5. Partitioning and Constraint Exclusion">Section 5.11.5</a> for
+ more information on using constraint exclusion to implement
+ partitioning.
+ </p></dd><dt id="GUC-CURSOR-TUPLE-FRACTION"><span class="term"><code class="varname">cursor_tuple_fraction</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.5.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the fraction of a cursor's rows that
+ will be retrieved. The default is 0.1. Smaller values of this
+ setting bias the planner towards using <span class="quote">“<span class="quote">fast start</span>”</span> plans
+ for cursors, which will retrieve the first few rows quickly while
+ perhaps taking a long time to fetch all rows. Larger values
+ put more emphasis on the total estimated time. At the maximum
+ setting of 1.0, cursors are planned exactly like regular queries,
+ considering only the total estimated time and not how soon the
+ first rows might be delivered.
+ </p></dd><dt id="GUC-FROM-COLLAPSE-LIMIT"><span class="term"><code class="varname">from_collapse_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.5.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The planner will merge sub-queries into upper queries if the
+ resulting <code class="literal">FROM</code> 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 <a class="xref" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Section 14.3</a>.
+ </p><p>
+ Setting this value to <a class="xref" href="runtime-config-query.html#GUC-GEQO-THRESHOLD">geqo_threshold</a> or more
+ may trigger use of the GEQO planner, resulting in non-optimal
+ plans. See <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO" title="20.7.3. Genetic Query Optimizer">Section 20.7.3</a>.
+ </p></dd><dt id="GUC-JIT"><span class="term"><code class="varname">jit</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.10.5.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines whether <acronym class="acronym">JIT</acronym> compilation may be used by
+ <span class="productname">PostgreSQL</span>, if available (see <a class="xref" href="jit.html" title="Chapter 32. Just-in-Time Compilation (JIT)">Chapter 32</a>).
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-JOIN-COLLAPSE-LIMIT"><span class="term"><code class="varname">join_collapse_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.10.5.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The planner will rewrite explicit <code class="literal">JOIN</code>
+ constructs (except <code class="literal">FULL JOIN</code>s) into lists of
+ <code class="literal">FROM</code> items whenever a list of no more than this many items
+ would result. Smaller values reduce planning time but might
+ yield inferior query plans.
+ </p><p>
+ By default, this variable is set the same as
+ <code class="varname">from_collapse_limit</code>, which is appropriate
+ for most uses. Setting it to 1 prevents any reordering of
+ explicit <code class="literal">JOIN</code>s. Thus, the explicit join order
+ specified in the query will be the actual order in which the
+ relations are joined. Because the query planner does not always choose
+ 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 <a class="xref" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Section 14.3</a>.
+ </p><p>
+ Setting this value to <a class="xref" href="runtime-config-query.html#GUC-GEQO-THRESHOLD">geqo_threshold</a> or more
+ may trigger use of the GEQO planner, resulting in non-optimal
+ plans. See <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO" title="20.7.3. Genetic Query Optimizer">Section 20.7.3</a>.
+ </p></dd><dt id="GUC-PLAN-CACHE_MODE"><span class="term"><code class="varname">plan_cache_mode</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.10.5.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Prepared statements (either explicitly prepared or implicitly
+ generated, for example by PL/pgSQL) can be executed using custom or
+ generic plans. Custom plans are made afresh for each execution
+ using its specific set of parameter values, while generic plans do
+ not rely on the parameter values and can be re-used across
+ executions. Thus, use of a generic plan saves planning time, but if
+ the ideal plan depends strongly on the parameter values then a
+ generic plan may be inefficient. The choice between these options
+ is normally made automatically, but it can be overridden
+ with <code class="varname">plan_cache_mode</code>.
+ The allowed values are <code class="literal">auto</code> (the default),
+ <code class="literal">force_custom_plan</code> and
+ <code class="literal">force_generic_plan</code>.
+ This setting is considered when a cached plan is to be executed,
+ not when it is prepared.
+ For more information see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>.
+ </p></dd><dt id="GUC-RECURSIVE-WORKTABLE-FACTOR"><span class="term"><code class="varname">recursive_worktable_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.10.5.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the planner's estimate of the average size of the working
+ table of a <a class="link" href="queries-with.html#QUERIES-WITH-RECURSIVE" title="7.8.2. Recursive Queries">recursive
+ query</a>, as a multiple of the estimated size of the initial
+ non-recursive term of the query. This helps the planner choose
+ the most appropriate method for joining the working table to the
+ query's other tables.
+ The default value is <code class="literal">10.0</code>. A smaller value
+ such as <code class="literal">1.0</code> can be helpful when the recursion
+ has low <span class="quote">“<span class="quote">fan-out</span>”</span> from one step to the next, as for
+ example in shortest-path queries. Graph analytics queries may
+ benefit from larger-than-default values.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-replication.html" title="20.6. Replication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.6. Replication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.8. Error Reporting and Logging</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-replication.html b/doc/src/sgml/html/runtime-config-replication.html
new file mode 100644
index 0000000..85c2656
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-replication.html
@@ -0,0 +1,562 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.6. Replication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-wal.html" title="20.5. Write Ahead Log" /><link rel="next" href="runtime-config-query.html" title="20.7. Query Planning" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.6. Replication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-wal.html" title="20.5. Write Ahead Log">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-query.html" title="20.7. Query Planning">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.6. Replication</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">20.6.1. Sending Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY">20.6.2. Primary Server</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">20.6.3. Standby Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SUBSCRIBER">20.6.4. Subscribers</a></span></dt></dl></div><p>
+ These settings control the behavior of the built-in
+ <em class="firstterm">streaming replication</em> feature (see
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>). Servers will be either a
+ primary or a standby server. Primaries can send data, while standbys
+ are always receivers of replicated data. When cascading replication
+ (see <a class="xref" href="warm-standby.html#CASCADING-REPLICATION" title="27.2.7. Cascading Replication">Section 27.2.7</a>) is used, standby servers
+ can also be senders, as well as receivers.
+ Parameters are mainly for sending and standby servers, though some
+ parameters have meaning only on the primary server. Settings may vary
+ across the cluster without problems if that is required.
+ </p><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-SENDER"><div class="titlepage"><div><div><h3 class="title">20.6.1. Sending Servers</h3></div></div></div><p>
+ These parameters can be set on any server that is
+ to send replication data to one or more standby servers.
+ The primary is always a sending server, so these parameters must
+ always be set on the primary.
+ The role and meaning of these parameters does not change after a
+ standby becomes the primary.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-MAX-WAL-SENDERS"><span class="term"><code class="varname">max_wal_senders</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.3.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum number of concurrent connections from standby
+ servers or streaming base backup clients (i.e., the maximum number of
+ simultaneously running WAL sender processes). The default is
+ <code class="literal">10</code>. The value <code class="literal">0</code> means
+ replication is disabled. Abrupt disconnection of a streaming client might
+ leave an orphaned connection slot behind until a timeout is reached,
+ so this parameter should be set slightly higher than the maximum
+ number of expected clients so disconnected clients can immediately
+ reconnect. This parameter can only be set at server start. Also,
+ <code class="varname">wal_level</code> must be set to
+ <code class="literal">replica</code> or higher to allow connections from standby
+ servers.
+ </p><p>
+ When running a standby server, you must set this parameter to the
+ same or higher value than on the primary server. Otherwise, queries
+ will not be allowed in the standby server.
+ </p></dd><dt id="GUC-MAX-REPLICATION-SLOTS"><span class="term"><code class="varname">max_replication_slots</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.3.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum number of replication slots
+ (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>) that the server
+ can support. The default is 10. This parameter can only be set at
+ server start.
+ Setting it to a lower value than the number of currently
+ existing replication slots will prevent the server from starting.
+ Also, <code class="varname">wal_level</code> must be set
+ to <code class="literal">replica</code> or higher to allow replication slots to
+ be used.
+ </p><p>
+ On the subscriber side, specifies how many replication origins (see
+ <a class="xref" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Chapter 50</a>) can be tracked simultaneously,
+ effectively limiting how many logical replication subscriptions can
+ be created on the server. Setting it to a lower value than the current
+ number of tracked replication origins (reflected in
+ <a class="link" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">pg_replication_origin_status</a>,
+ not <a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin">pg_replication_origin</a>)
+ will prevent the server from starting.
+ </p></dd><dt id="GUC-WAL-KEEP-SIZE"><span class="term"><code class="varname">wal_keep_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.3.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the minimum size of past log file segments kept in the
+ <code class="filename">pg_wal</code>
+ directory, in case a standby server needs to fetch them for streaming
+ replication. If a standby
+ server connected to the sending server falls behind by more than
+ <code class="varname">wal_keep_size</code> megabytes, the sending server might
+ remove a WAL segment still needed by the standby, in which case the
+ replication connection will be terminated. Downstream connections
+ will also eventually fail as a result. (However, the standby
+ server can recover by fetching the segment from archive, if WAL
+ archiving is in use.)
+ </p><p>
+ This sets only the minimum size of segments retained in
+ <code class="filename">pg_wal</code>; the system might need to retain more segments
+ for WAL archival or to recover from a checkpoint. If
+ <code class="varname">wal_keep_size</code> is zero (the default), the system
+ doesn't keep any extra segments for standby purposes, so the number
+ of old WAL segments available to standby servers is a function of
+ the location of the previous checkpoint and status of WAL
+ archiving.
+ If this value is specified without units, it is taken as megabytes.
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-MAX-SLOT-WAL-KEEP-SIZE"><span class="term"><code class="varname">max_slot_wal_keep_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.3.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specify the maximum size of WAL files
+ that <a class="link" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">replication
+ slots</a> are allowed to retain in the <code class="filename">pg_wal</code>
+ directory at checkpoint time.
+ If <code class="varname">max_slot_wal_keep_size</code> is -1 (the default),
+ replication slots may retain an unlimited amount of WAL files. Otherwise, if
+ restart_lsn of a replication slot falls behind the current LSN by more
+ than the given size, the standby using the slot may no longer be able
+ to continue replication due to removal of required WAL files. You
+ can see the WAL availability of replication slots
+ in <a class="link" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">pg_replication_slots</a>.
+ If this value is specified without units, it is taken as megabytes.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-WAL-SENDER-TIMEOUT"><span class="term"><code class="varname">wal_sender_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.3.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Terminate replication connections that are inactive for longer
+ than this amount of time. This is useful for
+ the sending server to detect a standby crash or network outage.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 60 seconds.
+ A value of zero disables the timeout mechanism.
+ </p><p>
+ With a cluster distributed across multiple geographic
+ locations, using different values per location brings more flexibility
+ in the cluster management. A smaller value is useful for faster
+ failure detection with a standby having a low-latency network
+ connection, and a larger value helps in judging better the health
+ of a standby if located on a remote location, with a high-latency
+ network connection.
+ </p></dd><dt id="GUC-TRACK-COMMIT-TIMESTAMP"><span class="term"><code class="varname">track_commit_timestamp</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.9.3.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Record commit time of transactions. This parameter
+ can only be set in <code class="filename">postgresql.conf</code> file or on the server
+ command line. The default value is <code class="literal">off</code>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-PRIMARY"><div class="titlepage"><div><div><h3 class="title">20.6.2. Primary Server</h3></div></div></div><p>
+ These parameters can be set on the primary server that is
+ to send replication data to one or more standby servers.
+ Note that in addition to these parameters,
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> must be set appropriately on the primary
+ server, and optionally WAL archiving can be enabled as
+ well (see <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING" title="20.5.3. Archiving">Section 20.5.3</a>).
+ 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 primary.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-SYNCHRONOUS-STANDBY-NAMES"><span class="term"><code class="varname">synchronous_standby_names</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.9.4.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a list of standby servers that can support
+ <em class="firstterm">synchronous replication</em>, as described in
+ <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">Section 27.2.8</a>.
+ 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.
+ The synchronous standbys will be those whose names appear
+ in this list, and
+ that are both currently connected and streaming data in real-time
+ (as shown by a state of <code class="literal">streaming</code> in the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication">
+ <code class="structname">pg_stat_replication</code></a> view).
+ Specifying more than one synchronous standby can allow for very high
+ availability and protection against data loss.
+ </p><p>
+ The name of a standby server for this purpose is the
+ <code class="varname">application_name</code> setting of the standby, as set in the
+ standby's connection information. In case of a physical replication
+ standby, this should be set in the <code class="varname">primary_conninfo</code>
+ setting; the default is the setting of <a class="xref" href="runtime-config-logging.html#GUC-CLUSTER-NAME">cluster_name</a>
+ if set, else <code class="literal">walreceiver</code>.
+ For logical replication, this can be set in the connection
+ information of the subscription, and it defaults to the
+ subscription name. For other replication stream consumers,
+ consult their documentation.
+ </p><p>
+ This parameter specifies a list of standby servers using
+ either of the following syntaxes:
+</p><pre class="synopsis">
+[FIRST] <em class="replaceable"><code>num_sync</code></em> ( <em class="replaceable"><code>standby_name</code></em> [, ...] )
+ANY <em class="replaceable"><code>num_sync</code></em> ( <em class="replaceable"><code>standby_name</code></em> [, ...] )
+<em class="replaceable"><code>standby_name</code></em> [, ...]
+</pre><p>
+ where <em class="replaceable"><code>num_sync</code></em> is
+ the number of synchronous standbys that transactions need to
+ wait for replies from,
+ and <em class="replaceable"><code>standby_name</code></em>
+ is the name of a standby server.
+ <code class="literal">FIRST</code> and <code class="literal">ANY</code> specify the method to choose
+ synchronous standbys from the listed servers.
+ </p><p>
+ The keyword <code class="literal">FIRST</code>, coupled with
+ <em class="replaceable"><code>num_sync</code></em>, specifies a
+ priority-based synchronous replication and makes transaction commits
+ wait until their WAL records are replicated to
+ <em class="replaceable"><code>num_sync</code></em> synchronous
+ standbys chosen based on their priorities. For example, a setting of
+ <code class="literal">FIRST 3 (s1, s2, s3, s4)</code> will cause each commit to wait for
+ replies from three higher-priority standbys chosen from standby servers
+ <code class="literal">s1</code>, <code class="literal">s2</code>, <code class="literal">s3</code> and <code class="literal">s4</code>.
+ The standbys whose names appear earlier in the list are given higher
+ priority and will be considered as synchronous. Other standby servers
+ appearing later in this list represent potential synchronous standbys.
+ If any of the current synchronous standbys disconnects for whatever
+ reason, it will be replaced immediately with the next-highest-priority
+ standby. The keyword <code class="literal">FIRST</code> is optional.
+ </p><p>
+ The keyword <code class="literal">ANY</code>, coupled with
+ <em class="replaceable"><code>num_sync</code></em>, specifies a
+ quorum-based synchronous replication and makes transaction commits
+ wait until their WAL records are replicated to <span class="emphasis"><em>at least</em></span>
+ <em class="replaceable"><code>num_sync</code></em> listed standbys.
+ For example, a setting of <code class="literal">ANY 3 (s1, s2, s3, s4)</code> will cause
+ each commit to proceed as soon as at least any three standbys of
+ <code class="literal">s1</code>, <code class="literal">s2</code>, <code class="literal">s3</code> and <code class="literal">s4</code>
+ reply.
+ </p><p>
+ <code class="literal">FIRST</code> and <code class="literal">ANY</code> are case-insensitive. If these
+ keywords are used as the name of a standby server,
+ its <em class="replaceable"><code>standby_name</code></em> must
+ be double-quoted.
+ </p><p>
+ The third syntax was used before <span class="productname">PostgreSQL</span>
+ version 9.6 and is still supported. It's the same as the first syntax
+ with <code class="literal">FIRST</code> and
+ <em class="replaceable"><code>num_sync</code></em> equal to 1.
+ For example, <code class="literal">FIRST 1 (s1, s2)</code> and <code class="literal">s1, s2</code> have
+ the same meaning: either <code class="literal">s1</code> or <code class="literal">s2</code> is chosen
+ as a synchronous standby.
+ </p><p>
+ The special entry <code class="literal">*</code> matches any standby name.
+ </p><p>
+ There is no mechanism to enforce uniqueness of standby names. In case
+ of duplicates one of the matching standbys will be considered as
+ higher priority, though exactly which one is indeterminate.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Each <em class="replaceable"><code>standby_name</code></em>
+ should have the form of a valid SQL identifier, unless it
+ is <code class="literal">*</code>. You can use double-quoting if necessary. But note
+ that <em class="replaceable"><code>standby_name</code></em>s are
+ compared to standby application names case-insensitively, whether
+ double-quoted or not.
+ </p></div><p>
+ If no synchronous standby names are specified here, then synchronous
+ replication is not enabled and transaction commits will not wait for
+ replication. This is the default configuration. Even when
+ synchronous replication is enabled, individual transactions can be
+ configured not to wait for replication by setting the
+ <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> parameter to
+ <code class="literal">local</code> or <code class="literal">off</code>.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-VACUUM-DEFER-CLEANUP-AGE"><span class="term"><code class="varname">vacuum_defer_cleanup_age</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.4.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the number of transactions by which <code class="command">VACUUM</code> and
+ <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)"><acronym class="acronym">HOT</acronym> updates</a>
+ will defer cleanup of dead row versions. The
+ default is zero transactions, meaning that dead row versions can be
+ removed as soon as possible, that is, as soon as they are no longer
+ visible to any open transaction. You may wish to set this to a
+ non-zero value on a primary server that is supporting hot standby
+ servers, as described in <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a>. 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
+ primary server, it is difficult to predict just how much additional
+ grace time will be made available to standby queries.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ You should also consider setting <code class="varname">hot_standby_feedback</code>
+ on standby server(s) as an alternative to using this parameter.
+ </p><p>
+ This does not prevent cleanup of dead rows which have reached the age
+ specified by <code class="varname">old_snapshot_threshold</code>.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-STANDBY"><div class="titlepage"><div><div><h3 class="title">20.6.3. Standby Servers</h3></div></div></div><p>
+ These settings control the behavior of a
+ <a class="link" href="warm-standby.html#STANDBY-SERVER-OPERATION" title="27.2.2. Standby Server Operation">standby server</a>
+ that is
+ to receive replication data. Their values on the primary server
+ are irrelevant.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-PRIMARY-CONNINFO"><span class="term"><code class="varname">primary_conninfo</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.9.5.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a connection string to be used for the standby server
+ to connect with a sending server. This string is in the format
+ described in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>. If any option is
+ unspecified in this string, then the corresponding environment
+ variable (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>) is checked. If the
+ environment variable is not set either, then
+ defaults are used.
+ </p><p>
+ The connection string should specify the host name (or address)
+ of the sending server, as well as the port number if it is not
+ the same as the standby server's default.
+ Also specify a user name corresponding to a suitably-privileged role
+ on the sending server (see
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-AUTHENTICATION" title="27.2.5.1. Authentication">Section 27.2.5.1</a>).
+ A password needs to be provided too, if the sender demands password
+ authentication. It can be provided in the
+ <code class="varname">primary_conninfo</code> string, or in a separate
+ <code class="filename">~/.pgpass</code> file on the standby server (use
+ <code class="literal">replication</code> as the database name).
+ Do not specify a database name in the
+ <code class="varname">primary_conninfo</code> string.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ If this parameter is changed while the WAL receiver process is
+ running, that process is signaled to shut down and expected to
+ restart with the new setting (except if <code class="varname">primary_conninfo</code>
+ is an empty string).
+ This setting has no effect if the server is not in standby mode.
+ </p></dd><dt id="GUC-PRIMARY-SLOT-NAME"><span class="term"><code class="varname">primary_slot_name</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.9.5.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Optionally specifies an existing replication slot to be used when
+ connecting to the sending server via streaming replication to control
+ resource removal on the upstream node
+ (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>).
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ If this parameter is changed while the WAL receiver process is running,
+ that process is signaled to shut down and expected to restart with the
+ new setting.
+ This setting has no effect if <code class="varname">primary_conninfo</code> is not
+ set or the server is not in standby mode.
+ </p></dd><dt id="GUC-PROMOTE-TRIGGER-FILE"><span class="term"><code class="varname">promote_trigger_file</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.9.5.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies a trigger file whose presence ends recovery in the
+ standby. Even if this value is not set, you can still promote
+ the standby using <code class="command">pg_ctl promote</code> or calling
+ <code class="function">pg_promote()</code>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-HOT-STANDBY"><span class="term"><code class="varname">hot_standby</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.9.5.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies whether or not you can connect and run queries during
+ recovery, as described in <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a>.
+ The default value is <code class="literal">on</code>.
+ This parameter can only be set at server start. It only has effect
+ during archive recovery or in standby mode.
+ </p></dd><dt id="GUC-MAX-STANDBY-ARCHIVE-DELAY"><span class="term"><code class="varname">max_standby_archive_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When hot standby is active, this parameter determines how long the
+ standby server should wait before canceling standby queries that
+ conflict with about-to-be-applied WAL entries, as described in
+ <a class="xref" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="27.4.2. Handling Query Conflicts">Section 27.4.2</a>.
+ <code class="varname">max_standby_archive_delay</code> applies when WAL data is
+ being read from WAL archive (and is therefore not current).
+ If this value is specified without units, it is taken as milliseconds.
+ The default is 30 seconds.
+ A value of -1 allows the standby to wait forever for conflicting
+ queries to complete.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ Note that <code class="varname">max_standby_archive_delay</code> is not the same as the
+ maximum length of time a query can run before cancellation; rather it
+ is the maximum total time allowed to apply any one WAL segment's data.
+ Thus, if one query has resulted in significant delay earlier in the
+ WAL segment, subsequent conflicting queries will have much less grace
+ time.
+ </p></dd><dt id="GUC-MAX-STANDBY-STREAMING-DELAY"><span class="term"><code class="varname">max_standby_streaming_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When hot standby is active, this parameter determines how long the
+ standby server should wait before canceling standby queries that
+ conflict with about-to-be-applied WAL entries, as described in
+ <a class="xref" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="27.4.2. Handling Query Conflicts">Section 27.4.2</a>.
+ <code class="varname">max_standby_streaming_delay</code> applies when WAL data is
+ being received via streaming replication.
+ If this value is specified without units, it is taken as milliseconds.
+ The default is 30 seconds.
+ A value of -1 allows the standby to wait forever for conflicting
+ queries to complete.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ Note that <code class="varname">max_standby_streaming_delay</code> is not the same as
+ the maximum length of time a query can run before cancellation; rather
+ it is the maximum total time allowed to apply WAL data once it has
+ been received from the primary server. Thus, if one query has
+ resulted in significant delay, subsequent conflicting queries will
+ have much less grace time until the standby server has caught up
+ again.
+ </p></dd><dt id="GUC-WAL-RECEIVER-CREATE-TEMP-SLOT"><span class="term"><code class="varname">wal_receiver_create_temp_slot</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.9.5.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies whether the WAL receiver process should create a temporary replication
+ slot on the remote instance when no permanent replication slot to use
+ has been configured (using <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">primary_slot_name</a>).
+ The default is off. This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ If this parameter is changed while the WAL receiver process is running,
+ that process is signaled to shut down and expected to restart with
+ the new setting.
+ </p></dd><dt id="GUC-WAL-RECEIVER-STATUS-INTERVAL"><span class="term"><code class="varname">wal_receiver_status_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the minimum frequency for the WAL receiver
+ process on the standby to send information about replication progress
+ to the primary or upstream standby, where it can be seen using the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication">
+ <code class="structname">pg_stat_replication</code></a>
+ view. The standby will report
+ the last write-ahead log location it has written, the last position it
+ has flushed to disk, and the last position it has applied.
+ This parameter's value is the maximum amount of time between reports.
+ Updates are sent each time the write or flush positions change, or as
+ often as specified by this parameter if set to a non-zero value.
+ There are additional cases where updates are sent while ignoring this
+ parameter; for example, when processing of the existing WAL completes
+ or when <code class="varname">synchronous_commit</code> is set to
+ <code class="literal">remote_apply</code>.
+ Thus, the apply position may lag slightly behind the true position.
+ If this value is specified without units, it is taken as seconds.
+ The default value is 10 seconds. This parameter can only be set in
+ the <code class="filename">postgresql.conf</code> file or on the server
+ command line.
+ </p></dd><dt id="GUC-HOT-STANDBY-FEEDBACK"><span class="term"><code class="varname">hot_standby_feedback</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.9.5.3.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies whether or not a hot standby will send feedback to the primary
+ or upstream standby
+ about queries currently executing on the standby. This parameter can
+ be used to eliminate query cancels caused by cleanup records, but
+ can cause database bloat on the primary for some workloads.
+ Feedback messages will not be sent more frequently than once per
+ <code class="varname">wal_receiver_status_interval</code>. The default value is
+ <code class="literal">off</code>. This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p><p>
+ If cascaded replication is in use the feedback is passed upstream
+ until it eventually reaches the primary. Standbys make no other use
+ of feedback they receive other than to pass upstream.
+ </p><p>
+ This setting does not override the behavior of
+ <code class="varname">old_snapshot_threshold</code> on the primary; a snapshot on the
+ standby which exceeds the primary's age threshold can become invalid,
+ resulting in cancellation of transactions on the standby. This is
+ because <code class="varname">old_snapshot_threshold</code> is intended to provide an
+ absolute limit on the time which dead rows can contribute to bloat,
+ which would otherwise be violated because of the configuration of a
+ standby.
+ </p></dd><dt id="GUC-WAL-RECEIVER-TIMEOUT"><span class="term"><code class="varname">wal_receiver_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Terminate replication connections that are inactive for longer
+ than this amount of time. This is useful for
+ the receiving standby server to detect a primary node crash or network
+ outage.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 60 seconds.
+ A value of zero disables the timeout mechanism.
+ This parameter can only be set in
+ the <code class="filename">postgresql.conf</code> file or on the server
+ command line.
+ </p></dd><dt id="GUC-WAL-RETRIEVE-RETRY-INTERVAL"><span class="term"><code class="varname">wal_retrieve_retry_interval</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies how long the standby server should wait when WAL data is not
+ available from any sources (streaming replication,
+ local <code class="filename">pg_wal</code> or WAL archive) before trying
+ again to retrieve WAL data.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 5 seconds.
+ This parameter can only be set in
+ the <code class="filename">postgresql.conf</code> file or on the server
+ command line.
+ </p><p>
+ This parameter is useful in configurations where a node in recovery
+ needs to control the amount of time to wait for new WAL data to be
+ available. For example, in archive recovery, it is possible to
+ make the recovery more responsive in the detection of a new WAL
+ log file by reducing the value of this parameter. On a system with
+ low WAL activity, increasing it reduces the amount of requests necessary
+ to access WAL archives, something useful for example in cloud
+ environments where the number of times an infrastructure is accessed
+ is taken into account.
+ </p></dd><dt id="GUC-RECOVERY-MIN-APPLY-DELAY"><span class="term"><code class="varname">recovery_min_apply_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.5.3.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ By default, a standby server restores WAL records from the
+ sending server as soon as possible. It may be useful to have a time-delayed
+ copy of the data, offering opportunities to correct data loss errors.
+ This parameter allows you to delay recovery by a specified amount
+ of time. For example, if
+ you set this parameter to <code class="literal">5min</code>, the standby will
+ replay each transaction commit only when the system time on the standby
+ is at least five minutes past the commit time reported by the primary.
+ If this value is specified without units, it is taken as milliseconds.
+ The default is zero, adding no delay.
+ </p><p>
+ It is possible that the replication delay between servers exceeds the
+ value of this parameter, in which case no delay is added.
+ Note that the delay is calculated between the WAL time stamp as written
+ on primary and the current time on the standby. Delays in transfer
+ because of network lag or cascading replication configurations
+ may reduce the actual wait time significantly. If the system
+ clocks on primary and standby are not synchronized, this may lead to
+ recovery applying records earlier than expected; but that is not a
+ major issue because useful settings of this parameter are much larger
+ than typical time deviations between servers.
+ </p><p>
+ The delay occurs only on WAL records for transaction commits.
+ Other records are replayed as quickly as possible, which
+ is not a problem because MVCC visibility rules ensure their effects
+ are not visible until the corresponding commit record is applied.
+ </p><p>
+ The delay occurs once the database in recovery has reached a consistent
+ state, until the standby is promoted or triggered. After that the standby
+ will end recovery without further waiting.
+ </p><p>
+ WAL records must be kept on the standby until they are ready to be
+ applied. Therefore, longer delays will result in a greater accumulation
+ of WAL files, increasing disk space requirements for the standby's
+ <code class="filename">pg_wal</code> directory.
+ </p><p>
+ This parameter is intended for use with streaming replication deployments;
+ however, if the parameter is specified it will be honored in all cases
+ except crash recovery.
+
+ <code class="varname">hot_standby_feedback</code> will be delayed by use of this feature
+ which could lead to bloat on the primary; use both together with care.
+
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ Synchronous replication is affected by this setting when <code class="varname">synchronous_commit</code>
+ is set to <code class="literal">remote_apply</code>; every <code class="literal">COMMIT</code>
+ will need to wait to be applied.
+ </p></div><p>
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-SUBSCRIBER"><div class="titlepage"><div><div><h3 class="title">20.6.4. Subscribers</h3></div></div></div><p>
+ These settings control the behavior of a logical replication subscriber.
+ Their values on the publisher are irrelevant.
+ </p><p>
+ Note that <code class="varname">wal_receiver_timeout</code>,
+ <code class="varname">wal_receiver_status_interval</code> and
+ <code class="varname">wal_retrieve_retry_interval</code> configuration parameters
+ affect the logical replication workers as well.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-MAX-LOGICAL-REPLICATION-WORKERS"><span class="term"><code class="varname">max_logical_replication_workers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.6.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies maximum number of logical replication workers. This includes
+ both apply workers and table synchronization workers.
+ </p><p>
+ Logical replication workers are taken from the pool defined by
+ <code class="varname">max_worker_processes</code>.
+ </p><p>
+ The default value is 4. This parameter can only be set at server
+ start.
+ </p></dd><dt id="GUC-MAX-SYNC-WORKERS-PER-SUBSCRIPTION"><span class="term"><code class="varname">max_sync_workers_per_subscription</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.9.6.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Maximum number of synchronization workers per subscription. This
+ parameter controls the amount of parallelism of the initial data copy
+ during the subscription initialization or when new tables are added.
+ </p><p>
+ Currently, there can be only one synchronization worker per table.
+ </p><p>
+ The synchronization workers are taken from the pool defined by
+ <code class="varname">max_logical_replication_workers</code>.
+ </p><p>
+ The default value is 2. This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command
+ line.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-wal.html" title="20.5. Write Ahead Log">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-query.html" title="20.7. Query Planning">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.5. Write Ahead Log </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.7. Query Planning</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-resource.html b/doc/src/sgml/html/runtime-config-resource.html
new file mode 100644
index 0000000..f184318
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-resource.html
@@ -0,0 +1,714 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.4. Resource Consumption</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-connection.html" title="20.3. Connections and Authentication" /><link rel="next" href="runtime-config-wal.html" title="20.5. Write Ahead Log" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.4. Resource Consumption</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-wal.html" title="20.5. Write Ahead Log">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-RESOURCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.4. Resource Consumption</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">20.4.1. Memory</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-DISK">20.4.2. Disk</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-KERNEL">20.4.3. Kernel Resource Usage</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">20.4.4. Cost-based Vacuum Delay</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">20.4.5. Background Writer</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">20.4.6. Asynchronous Behavior</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-MEMORY"><div class="titlepage"><div><div><h3 class="title">20.4.1. Memory</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-SHARED-BUFFERS"><span class="term"><code class="varname">shared_buffers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the amount of memory the database server uses for shared
+ memory buffers. The default is typically 128 megabytes
+ (<code class="literal">128MB</code>), but might be less if your kernel settings will
+ not support it (as determined during <span class="application">initdb</span>).
+ This setting must be at least 128 kilobytes. However,
+ settings significantly higher than the minimum are usually needed
+ for good performance.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ (Non-default values of <code class="symbol">BLCKSZ</code> change the minimum
+ value.)
+ This parameter can only be set at server start.
+ </p><p>
+ If you have a dedicated database server with 1GB or more of RAM, a
+ reasonable starting value for <code class="varname">shared_buffers</code> is 25%
+ of the memory in your system. There are some workloads where even
+ larger settings for <code class="varname">shared_buffers</code> are effective, but
+ because <span class="productname">PostgreSQL</span> also relies on the
+ operating system cache, it is unlikely that an allocation of more than
+ 40% of RAM to <code class="varname">shared_buffers</code> will work better than a
+ smaller amount. Larger settings for <code class="varname">shared_buffers</code>
+ usually require a corresponding increase in
+ <code class="varname">max_wal_size</code>, in order to spread out the
+ process of writing large quantities of new or changed data over a
+ longer period of time.
+ </p><p>
+ On systems with less than 1GB of RAM, a smaller percentage of RAM is
+ appropriate, so as to leave adequate space for the operating system.
+ </p></dd><dt id="GUC-HUGE-PAGES"><span class="term"><code class="varname">huge_pages</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.7.2.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls whether huge pages are requested for the main shared memory
+ area. Valid values are <code class="literal">try</code> (the default),
+ <code class="literal">on</code>, and <code class="literal">off</code>. With
+ <code class="varname">huge_pages</code> set to <code class="literal">try</code>, the
+ server will try to request huge pages, but fall back to the default if
+ that fails. With <code class="literal">on</code>, failure to request huge pages
+ will prevent the server from starting up. With <code class="literal">off</code>,
+ huge pages will not be requested.
+ </p><p>
+ At present, this setting is supported only on Linux and Windows. The
+ setting is ignored on other systems when set to
+ <code class="literal">try</code>. On Linux, it is only supported when
+ <code class="varname">shared_memory_type</code> is set to <code class="literal">mmap</code>
+ (the default).
+ </p><p>
+ The use of huge pages results in smaller page tables and less CPU time
+ spent on memory management, increasing performance. For more details about
+ using huge pages on Linux, see <a class="xref" href="kernel-resources.html#LINUX-HUGE-PAGES" title="19.4.5. Linux Huge Pages">Section 19.4.5</a>.
+ </p><p>
+ Huge pages are known as large pages on Windows. To use them, you need to
+ assign the user right <span class="quote">“<span class="quote">Lock pages in memory</span>”</span> to the Windows user account
+ that runs <span class="productname">PostgreSQL</span>.
+ You can use Windows Group Policy tool (gpedit.msc) to assign the user right
+ <span class="quote">“<span class="quote">Lock pages in memory</span>”</span>.
+ To start the database server on the command prompt as a standalone process,
+ not as a Windows service, the command prompt must be run as an administrator or
+ User Access Control (UAC) must be disabled. When the UAC is enabled, the normal
+ command prompt revokes the user right <span class="quote">“<span class="quote">Lock pages in memory</span>”</span> when started.
+ </p><p>
+ Note that this setting only affects the main shared memory area.
+ Operating systems such as Linux, FreeBSD, and Illumos can also use
+ huge pages (also known as <span class="quote">“<span class="quote">super</span>”</span> pages or
+ <span class="quote">“<span class="quote">large</span>”</span> pages) automatically for normal memory
+ allocation, without an explicit request from
+ <span class="productname">PostgreSQL</span>. On Linux, this is called
+ <span class="quote">“<span class="quote">transparent huge pages</span>”</span><a id="id-1.6.7.7.2.2.2.2.5.5" class="indexterm"></a> (THP). That feature has been known to
+ cause performance degradation with
+ <span class="productname">PostgreSQL</span> for some users on some Linux
+ versions, so its use is currently discouraged (unlike explicit use of
+ <code class="varname">huge_pages</code>).
+ </p></dd><dt id="GUC-HUGE-PAGE-SIZE"><span class="term"><code class="varname">huge_page_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls the size of huge pages, when they are enabled with
+ <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGES">huge_pages</a>.
+ The default is zero (<code class="literal">0</code>).
+ When set to <code class="literal">0</code>, the default huge page size on the
+ system will be used. This parameter can only be set at server start.
+ </p><p>
+ Some commonly available page sizes on modern 64 bit server architectures include:
+ <code class="literal">2MB</code> and <code class="literal">1GB</code> (Intel and AMD), <code class="literal">16MB</code> and
+ <code class="literal">16GB</code> (IBM POWER), and <code class="literal">64kB</code>, <code class="literal">2MB</code>,
+ <code class="literal">32MB</code> and <code class="literal">1GB</code> (ARM). For more information
+ about usage and support, see <a class="xref" href="kernel-resources.html#LINUX-HUGE-PAGES" title="19.4.5. Linux Huge Pages">Section 19.4.5</a>.
+ </p><p>
+ Non-default settings are currently supported only on Linux.
+ </p></dd><dt id="GUC-TEMP-BUFFERS"><span class="term"><code class="varname">temp_buffers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum amount of memory used for temporary buffers within
+ each database session. These are session-local buffers used only
+ for access to temporary tables.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The default is eight megabytes (<code class="literal">8MB</code>).
+ (If <code class="symbol">BLCKSZ</code> is not 8kB, the default value scales
+ proportionally to it.)
+ This setting can be changed within individual
+ sessions, but only before the first use of temporary tables
+ within the session; subsequent attempts to change the value will
+ have no effect on that session.
+ </p><p>
+ A session will allocate temporary buffers as needed up to the limit
+ given by <code class="varname">temp_buffers</code>. The cost of setting a large
+ value in sessions that do not actually need many temporary
+ buffers is only a buffer descriptor, or about 64 bytes, per
+ increment in <code class="varname">temp_buffers</code>. However if a buffer is
+ actually used an additional 8192 bytes will be consumed for it
+ (or in general, <code class="symbol">BLCKSZ</code> bytes).
+ </p></dd><dt id="GUC-MAX-PREPARED-TRANSACTIONS"><span class="term"><code class="varname">max_prepared_transactions</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of transactions that can be in the
+ <span class="quote">“<span class="quote">prepared</span>”</span> state simultaneously (see <a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>).
+ Setting this parameter to zero (which is the default)
+ disables the prepared-transaction feature.
+ This parameter can only be set at server start.
+ </p><p>
+ If you are not planning to use prepared transactions, this parameter
+ should be set to zero to prevent accidental creation of prepared
+ transactions. If you are using prepared transactions, you will
+ probably want <code class="varname">max_prepared_transactions</code> to be at
+ least as large as <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>, so that every
+ session can have a prepared transaction pending.
+ </p><p>
+ When running a standby server, you must set this parameter to the
+ same or higher value than on the primary server. Otherwise, queries
+ will not be allowed in the standby server.
+ </p></dd><dt id="GUC-WORK-MEM"><span class="term"><code class="varname">work_mem</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the base maximum amount of memory to be used by a query operation
+ (such as a sort or hash table) before writing to temporary disk files.
+ If this value is specified without units, it is taken as kilobytes.
+ The default value is four megabytes (<code class="literal">4MB</code>).
+ Note that a complex query might perform several sort and hash
+ operations at the same time, with each operation generally being
+ allowed to use as much memory as this value specifies before
+ it starts
+ to write data into temporary files. Also, several running
+ sessions could be doing such operations concurrently.
+ Therefore, the total memory used could be many times the value
+ of <code class="varname">work_mem</code>; it is necessary to keep this
+ fact in mind when choosing the value. Sort operations are used
+ for <code class="literal">ORDER BY</code>, <code class="literal">DISTINCT</code>,
+ and merge joins.
+ Hash tables are used in hash joins, hash-based aggregation, memoize
+ nodes and hash-based processing of <code class="literal">IN</code> subqueries.
+ </p><p>
+ Hash-based operations are generally more sensitive to memory
+ availability than equivalent sort-based operations. The
+ memory limit for a hash table is computed by multiplying
+ <code class="varname">work_mem</code> by
+ <code class="varname">hash_mem_multiplier</code>. This makes it
+ possible for hash-based operations to use an amount of memory
+ that exceeds the usual <code class="varname">work_mem</code> base
+ amount.
+ </p></dd><dt id="GUC-HASH-MEM-MULTIPLIER"><span class="term"><code class="varname">hash_mem_multiplier</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.7.2.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Used to compute the maximum amount of memory that hash-based
+ operations can use. The final limit is determined by
+ multiplying <code class="varname">work_mem</code> by
+ <code class="varname">hash_mem_multiplier</code>. The default value is
+ 2.0, which makes hash-based operations use twice the usual
+ <code class="varname">work_mem</code> base amount.
+ </p><p>
+ Consider increasing <code class="varname">hash_mem_multiplier</code> in
+ environments where spilling by query operations is a regular
+ occurrence, especially when simply increasing
+ <code class="varname">work_mem</code> results in memory pressure (memory
+ pressure typically takes the form of intermittent out of
+ memory errors). The default setting of 2.0 is often effective with
+ mixed workloads. Higher settings in the range of 2.0 - 8.0 or
+ more may be effective in environments where
+ <code class="varname">work_mem</code> has already been increased to 40MB
+ or more.
+ </p></dd><dt id="GUC-MAINTENANCE-WORK-MEM"><span class="term"><code class="varname">maintenance_work_mem</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum amount of memory to be used by maintenance
+ operations, such as <code class="command">VACUUM</code>, <code class="command">CREATE
+ INDEX</code>, and <code class="command">ALTER TABLE ADD FOREIGN KEY</code>.
+ If this value is specified without units, it is taken as kilobytes.
+ It defaults
+ to 64 megabytes (<code class="literal">64MB</code>). Since only one of these
+ operations can be executed at a time by a database session, and
+ an installation normally doesn't have many of them running
+ concurrently, it's safe to set this value significantly larger
+ than <code class="varname">work_mem</code>. Larger settings might improve
+ performance for vacuuming and for restoring database dumps.
+ </p><p>
+ Note that when autovacuum runs, up to
+ <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MAX-WORKERS">autovacuum_max_workers</a> 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 <a class="xref" href="runtime-config-resource.html#GUC-AUTOVACUUM-WORK-MEM">autovacuum_work_mem</a>.
+ </p><p>
+ Note that for the collection of dead tuple identifiers,
+ <code class="command">VACUUM</code> is only able to utilize up to a maximum of
+ <code class="literal">1GB</code> of memory.
+ </p></dd><dt id="GUC-AUTOVACUUM-WORK-MEM"><span class="term"><code class="varname">autovacuum_work_mem</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum amount of memory to be used by each
+ autovacuum worker process.
+ If this value is specified without units, it is taken as kilobytes.
+ It defaults to -1, indicating that
+ the value of <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a> should
+ be used instead. The setting has no effect on the behavior of
+ <code class="command">VACUUM</code> when run in other contexts.
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command
+ line.
+ </p><p>
+ For the collection of dead tuple identifiers, autovacuum is only able
+ to utilize up to a maximum of <code class="literal">1GB</code> of memory, so
+ setting <code class="varname">autovacuum_work_mem</code> to a value higher than
+ that has no effect on the number of dead tuples that autovacuum can
+ collect while scanning a table.
+ </p></dd><dt id="GUC-LOGICAL-DECODING-WORK-MEM"><span class="term"><code class="varname">logical_decoding_work_mem</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum amount of memory to be used by logical decoding,
+ before some of the decoded changes are written to local disk. This
+ limits the amount of memory used by logical streaming replication
+ connections. It defaults to 64 megabytes (<code class="literal">64MB</code>).
+ Since each replication connection only uses a single buffer of this size,
+ and an installation normally doesn't have many such connections
+ concurrently (as limited by <code class="varname">max_wal_senders</code>), it's
+ safe to set this value significantly higher than <code class="varname">work_mem</code>,
+ reducing the amount of decoded changes written to disk.
+ </p></dd><dt id="GUC-MAX-STACK-DEPTH"><span class="term"><code class="varname">max_stack_depth</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum safe depth of the server's execution stack.
+ The ideal setting for this parameter is the actual stack size limit
+ enforced by the kernel (as set by <code class="literal">ulimit -s</code> or local
+ equivalent), less a safety margin of a megabyte or so. The safety
+ margin is needed because the stack depth is not checked in every
+ routine in the server, but only in key potentially-recursive routines.
+ If this value is specified without units, it is taken as kilobytes.
+ The default setting is two megabytes (<code class="literal">2MB</code>), which
+ is conservatively small and unlikely to risk crashes. However,
+ it might be too small to allow execution of complex functions.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ Setting <code class="varname">max_stack_depth</code> higher than
+ the actual kernel limit will mean that a runaway recursive function
+ can crash an individual backend process. On platforms where
+ <span class="productname">PostgreSQL</span> can determine the kernel limit,
+ the server will not allow this variable to be set to an unsafe
+ value. However, not all platforms provide the information,
+ so caution is recommended in selecting a value.
+ </p></dd><dt id="GUC-SHARED-MEMORY-TYPE"><span class="term"><code class="varname">shared_memory_type</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.7.2.2.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the shared memory implementation that the server
+ should use for the main shared memory region that holds
+ <span class="productname">PostgreSQL</span>'s shared buffers and other
+ shared data. Possible values are <code class="literal">mmap</code> (for
+ anonymous shared memory allocated using <code class="function">mmap</code>),
+ <code class="literal">sysv</code> (for System V shared memory allocated via
+ <code class="function">shmget</code>) and <code class="literal">windows</code> (for Windows
+ shared memory). Not all values are supported on all platforms; the
+ first supported option is the default for that platform. The use of
+ the <code class="literal">sysv</code> option, which is not the default on any
+ platform, is generally discouraged because it typically requires
+ non-default kernel settings to allow for large allocations (see <a class="xref" href="kernel-resources.html#SYSVIPC" title="19.4.1. Shared Memory and Semaphores">Section 19.4.1</a>).
+ </p></dd><dt id="GUC-DYNAMIC-SHARED-MEMORY-TYPE"><span class="term"><code class="varname">dynamic_shared_memory_type</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.7.2.2.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the dynamic shared memory implementation that the server
+ should use. Possible values are <code class="literal">posix</code> (for POSIX shared
+ memory allocated using <code class="literal">shm_open</code>), <code class="literal">sysv</code>
+ (for System V shared memory allocated via <code class="literal">shmget</code>),
+ <code class="literal">windows</code> (for Windows shared memory),
+ and <code class="literal">mmap</code> (to simulate shared memory using
+ memory-mapped files stored in the data directory).
+ Not all values are supported on all platforms; the first supported
+ option is usually the default for that platform. The use of the
+ <code class="literal">mmap</code> option, which is not the default on any platform,
+ is generally discouraged because the operating system may write
+ modified pages back to disk repeatedly, increasing system I/O load;
+ however, it may be useful for debugging, when the
+ <code class="literal">pg_dynshmem</code> directory is stored on a RAM disk, or when
+ other shared memory facilities are not available.
+ </p></dd><dt id="GUC-MIN-DYNAMIC-SHARED-MEMORY"><span class="term"><code class="varname">min_dynamic_shared_memory</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.2.2.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the amount of memory that should be allocated at server
+ startup for use by parallel queries. When this memory region is
+ insufficient or exhausted by concurrent queries, new parallel queries
+ try to allocate extra shared memory temporarily from the operating
+ system using the method configured with
+ <code class="varname">dynamic_shared_memory_type</code>, which may be slower due
+ to memory management overheads. Memory that is allocated at startup
+ with <code class="varname">min_dynamic_shared_memory</code> is affected by
+ the <code class="varname">huge_pages</code> setting on operating systems where
+ that is supported, and may be more likely to benefit from larger pages
+ on operating systems where that is managed automatically.
+ The default value is <code class="literal">0</code> (none). This parameter can
+ only be set at server start.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-DISK"><div class="titlepage"><div><div><h3 class="title">20.4.2. Disk</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-TEMP-FILE-LIMIT"><span class="term"><code class="varname">temp_file_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.3.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the maximum amount of disk space that a process can use
+ for temporary files, such as sort and hash temporary files, or the
+ storage file for a held cursor. A transaction attempting to exceed
+ this limit will be canceled.
+ If this value is specified without units, it is taken as kilobytes.
+ <code class="literal">-1</code> (the default) means no limit.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ This setting constrains the total space used at any instant by all
+ temporary files used by a given <span class="productname">PostgreSQL</span> process.
+ It should be noted that disk space used for explicit temporary
+ tables, as opposed to temporary files used behind-the-scenes in query
+ execution, does <span class="emphasis"><em>not</em></span> count against this limit.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-KERNEL"><div class="titlepage"><div><div><h3 class="title">20.4.3. Kernel Resource Usage</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-MAX-FILES-PER-PROCESS"><span class="term"><code class="varname">max_files_per_process</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.4.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of simultaneously open files allowed to each
+ server subprocess. The default is one thousand files. If the kernel is enforcing
+ a safe per-process limit, you don't need to worry about this setting.
+ But on some platforms (notably, most BSD systems), the kernel will
+ allow individual processes to open many more files than the system
+ can actually support if many processes all try to open
+ that many files. If you find yourself seeing <span class="quote">“<span class="quote">Too many open
+ files</span>”</span> failures, try reducing this setting.
+ This parameter can only be set at server start.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-VACUUM-COST"><div class="titlepage"><div><div><h3 class="title">20.4.4. Cost-based Vacuum Delay</h3></div></div></div><p>
+ During the execution of <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a>
+ and <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>
+ 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
+ cost reaches a limit (specified by
+ <code class="varname">vacuum_cost_limit</code>), the process performing
+ the operation will sleep for a short period of time, as specified by
+ <code class="varname">vacuum_cost_delay</code>. Then it will reset the
+ counter and continue execution.
+ </p><p>
+ The intent of this feature is to allow administrators to reduce
+ the I/O impact of these commands on concurrent database
+ activity. There are many situations where it is not
+ important that maintenance commands like
+ <code class="command">VACUUM</code> and <code class="command">ANALYZE</code> finish
+ quickly; however, it is usually very important that these
+ commands do not significantly interfere with the ability of the
+ system to perform other database operations. Cost-based vacuum
+ delay provides a way for administrators to achieve this.
+ </p><p>
+ This feature is disabled by default for manually issued
+ <code class="command">VACUUM</code> commands. To enable it, set the
+ <code class="varname">vacuum_cost_delay</code> variable to a nonzero
+ value.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-VACUUM-COST-DELAY"><span class="term"><code class="varname">vacuum_cost_delay</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.7.5.5.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The amount of time that the process will sleep
+ when the cost limit has been exceeded.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is zero, which disables the cost-based vacuum
+ delay feature. Positive values enable cost-based vacuuming.
+ </p><p>
+ When using cost-based vacuuming, appropriate values for
+ <code class="varname">vacuum_cost_delay</code> are usually quite small, perhaps
+ less than 1 millisecond. While <code class="varname">vacuum_cost_delay</code>
+ can be set to fractional-millisecond values, such delays may not be
+ measured accurately on older platforms. On such platforms,
+ increasing <code class="command">VACUUM</code>'s throttled resource consumption
+ above what you get at 1ms will require changing the other vacuum cost
+ parameters. You should, nonetheless,
+ keep <code class="varname">vacuum_cost_delay</code> as small as your platform
+ will consistently measure; large delays are not helpful.
+ </p></dd><dt id="GUC-VACUUM-COST-PAGE-HIT"><span class="term"><code class="varname">vacuum_cost_page_hit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.5.5.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The estimated cost for vacuuming a buffer found in the shared buffer
+ cache. It represents the cost to lock the buffer pool, lookup
+ the shared hash table and scan the content of the page. The
+ default value is one.
+ </p></dd><dt id="GUC-VACUUM-COST-PAGE-MISS"><span class="term"><code class="varname">vacuum_cost_page_miss</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.5.5.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The estimated cost for vacuuming a buffer that has to be read from
+ disk. This represents the effort to lock the buffer pool,
+ lookup the shared hash table, read the desired block in from
+ the disk and scan its content. The default value is 2.
+ </p></dd><dt id="GUC-VACUUM-COST-PAGE-DIRTY"><span class="term"><code class="varname">vacuum_cost_page_dirty</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.5.5.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The estimated cost charged when vacuum modifies a block that was
+ previously clean. It represents the extra I/O required to
+ flush the dirty block out to disk again. The default value is
+ 20.
+ </p></dd><dt id="GUC-VACUUM-COST-LIMIT"><span class="term"><code class="varname">vacuum_cost_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.5.5.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The accumulated cost that will cause the vacuuming process to sleep.
+ The default value is 200.
+ </p></dd></dl></div><div class="note"><h3 class="title">Note</h3><p>
+ There are certain operations that hold critical locks and should
+ therefore complete as quickly as possible. Cost-based vacuum
+ delays do not occur during such operations. Therefore it is
+ possible that the cost accumulates far higher than the specified
+ limit. To avoid uselessly long delays in such cases, the actual
+ delay is calculated as <code class="varname">vacuum_cost_delay</code> *
+ <code class="varname">accumulated_balance</code> /
+ <code class="varname">vacuum_cost_limit</code> with a maximum of
+ <code class="varname">vacuum_cost_delay</code> * 4.
+ </p></div></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER"><div class="titlepage"><div><div><h3 class="title">20.4.5. Background Writer</h3></div></div></div><p>
+ There is a separate server
+ process called the <em class="firstterm">background writer</em>, whose function
+ is to issue writes of <span class="quote">“<span class="quote">dirty</span>”</span> (new or modified) shared
+ buffers. When the number of clean shared buffers appears to be
+ insufficient, the background writer writes some dirty buffers to the
+ file system and marks them as clean. This reduces the likelihood
+ that server processes handling user queries will be unable to find
+ clean buffers and have to write dirty buffers themselves.
+ However, the background writer does cause a net overall
+ increase in I/O load, because while a repeatedly-dirtied page might
+ otherwise be written only once per checkpoint interval, the
+ background writer might write it several times as it is dirtied
+ in the same interval. The parameters discussed in this subsection
+ can be used to tune the behavior for local needs.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-BGWRITER-DELAY"><span class="term"><code class="varname">bgwriter_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.6.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the delay between activity rounds for the
+ background writer. In each round the writer issues writes
+ for some number of dirty buffers (controllable by the
+ following parameters). It then sleeps for
+ the length of <code class="varname">bgwriter_delay</code>, and repeats.
+ When there are no dirty buffers in the
+ buffer pool, though, it goes into a longer sleep regardless of
+ <code class="varname">bgwriter_delay</code>.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 200
+ milliseconds (<code class="literal">200ms</code>). Note that on many systems, the
+ effective resolution of sleep delays is 10 milliseconds; setting
+ <code class="varname">bgwriter_delay</code> to a value that is not a multiple of 10
+ might have the same results as setting it to the next higher multiple
+ of 10. This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-BGWRITER-LRU-MAXPAGES"><span class="term"><code class="varname">bgwriter_lru_maxpages</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.6.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ In each round, no more than this many buffers will be written
+ by the background writer. Setting this to zero disables
+ background writing. (Note that checkpoints, which are managed by
+ a separate, dedicated auxiliary process, are unaffected.)
+ The default value is 100 buffers.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-BGWRITER-LRU-MULTIPLIER"><span class="term"><code class="varname">bgwriter_lru_multiplier</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.7.6.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The number of dirty buffers written in each round is based on the
+ number of new buffers that have been needed by server processes
+ during recent rounds. The average recent need is multiplied by
+ <code class="varname">bgwriter_lru_multiplier</code> to arrive at an estimate of the
+ number of buffers that will be needed during the next round. Dirty
+ buffers are written until there are that many clean, reusable buffers
+ available. (However, no more than <code class="varname">bgwriter_lru_maxpages</code>
+ buffers will be written per round.)
+ Thus, a setting of 1.0 represents a <span class="quote">“<span class="quote">just in time</span>”</span> policy
+ of writing exactly the number of buffers predicted to be needed.
+ Larger values provide some cushion against spikes in demand,
+ while smaller values intentionally leave writes to be done by
+ server processes.
+ The default is 2.0.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-BGWRITER-FLUSH-AFTER"><span class="term"><code class="varname">bgwriter_flush_after</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.6.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Whenever more than this amount of data has
+ been written by the background writer, attempt to force the OS to issue these
+ writes to the underlying storage. Doing so will limit the amount of
+ dirty data in the kernel's page cache, reducing the likelihood of
+ stalls when an <code class="function">fsync</code> is issued at the end of a 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
+ <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but smaller than the OS's page
+ cache, where performance might degrade. This setting may have no
+ effect on some platforms.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The valid range is between
+ <code class="literal">0</code>, which disables forced writeback, and
+ <code class="literal">2MB</code>. The default is <code class="literal">512kB</code> on Linux,
+ <code class="literal">0</code> elsewhere. (If <code class="symbol">BLCKSZ</code> is not 8kB,
+ the default and maximum values scale proportionally to it.)
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div><p>
+ Smaller values of <code class="varname">bgwriter_lru_maxpages</code> and
+ <code class="varname">bgwriter_lru_multiplier</code> reduce the extra I/O load
+ caused by the background writer, but make it more likely that server
+ processes will have to issue writes for themselves, delaying interactive
+ queries.
+ </p></div><div class="sect2" id="RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR"><div class="titlepage"><div><div><h3 class="title">20.4.6. Asynchronous Behavior</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-BACKEND-FLUSH-AFTER"><span class="term"><code class="varname">backend_flush_after</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Whenever more than this amount of data has
+ been written by a single backend, attempt to force the OS to issue
+ these writes to the underlying storage. Doing so will limit the
+ amount of dirty data in the kernel's page cache, reducing the
+ likelihood of stalls when an <code class="function">fsync</code> is issued at the end of a
+ 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 <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but smaller
+ than the OS's page cache, where performance might degrade. This
+ setting may have no effect on some platforms.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The valid range is
+ between <code class="literal">0</code>, which disables forced writeback,
+ and <code class="literal">2MB</code>. The default is <code class="literal">0</code>, i.e., no
+ forced writeback. (If <code class="symbol">BLCKSZ</code> is not 8kB,
+ the maximum value scales proportionally to it.)
+ </p></dd><dt id="GUC-EFFECTIVE-IO-CONCURRENCY"><span class="term"><code class="varname">effective_io_concurrency</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the number of concurrent disk I/O operations that
+ <span class="productname">PostgreSQL</span> expects can be executed
+ simultaneously. Raising this value will increase the number of I/O
+ operations that any individual <span class="productname">PostgreSQL</span> session
+ attempts to initiate in parallel. The allowed range is 1 to 1000,
+ or zero to disable issuance of asynchronous I/O requests. Currently,
+ this setting only affects bitmap heap scans.
+ </p><p>
+ For magnetic drives, a good starting point for this setting is the
+ number of separate
+ drives comprising a RAID 0 stripe or RAID 1 mirror being used for the
+ database. (For RAID 5 the parity drive should not be counted.)
+ However, if the database is often busy with multiple queries issued in
+ concurrent sessions, lower values may be sufficient to keep the disk
+ array busy. A value higher than needed to keep the disks busy will
+ only result in extra CPU overhead.
+ SSDs and other memory-based storage can often process many
+ concurrent requests, so the best value might be in the hundreds.
+ </p><p>
+ Asynchronous I/O depends on an effective <code class="function">posix_fadvise</code>
+ function, which some operating systems lack. If the function is not
+ present then setting this parameter to anything but zero will result
+ in an error. On some operating systems (e.g., Solaris), the function
+ is present but does not actually do anything.
+ </p><p>
+ 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
+ <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a>).
+ </p></dd><dt id="GUC-MAINTENANCE-IO-CONCURRENCY"><span class="term"><code class="varname">maintenance_io_concurrency</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Similar to <code class="varname">effective_io_concurrency</code>, but used
+ for maintenance work that is done on behalf of many client sessions.
+ </p><p>
+ The default is 10 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
+ <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a>).
+ </p></dd><dt id="GUC-MAX-WORKER-PROCESSES"><span class="term"><code class="varname">max_worker_processes</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of background processes that the system
+ can support. This parameter can only be set at server start. The
+ default is 8.
+ </p><p>
+ When running a standby server, you must set this parameter to the
+ same or higher value than on the primary server. Otherwise, queries
+ will not be allowed in the standby server.
+ </p><p>
+ When changing this value, consider also adjusting
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>,
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS">max_parallel_maintenance_workers</a>, and
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a>.
+ </p></dd><dt id="GUC-MAX-PARALLEL-WORKERS-PER-GATHER"><span class="term"><code class="varname">max_parallel_workers_per_gather</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of workers that can be started by a single
+ <code class="literal">Gather</code> or <code class="literal">Gather Merge</code> node.
+ Parallel workers are taken from the pool of processes established by
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>, limited by
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>. 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
+ disables parallel query execution.
+ </p><p>
+ Note that parallel queries may consume very substantially more
+ resources than non-parallel queries, because each worker process is
+ a completely separate process which has roughly the same impact on the
+ 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 <a class="xref" href="runtime-config-resource.html#GUC-WORK-MEM">work_mem</a>. Resource limits such as
+ <code class="varname">work_mem</code> 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.
+ For example, a parallel query using 4 workers may use up to 5 times
+ as much CPU time, memory, I/O bandwidth, and so forth as a query which
+ uses no workers at all.
+ </p><p>
+ For more information on parallel query, see
+ <a class="xref" href="parallel-query.html" title="Chapter 15. Parallel Query">Chapter 15</a>.
+ </p></dd><dt id="GUC-MAX-PARALLEL-MAINTENANCE-WORKERS"><span class="term"><code class="varname">max_parallel_maintenance_workers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of parallel workers that can be
+ started by a single utility command. Currently, the parallel
+ utility commands that support the use of parallel workers are
+ <code class="command">CREATE INDEX</code> only when building a B-tree index,
+ and <code class="command">VACUUM</code> without <code class="literal">FULL</code>
+ option. Parallel workers are taken from the pool of processes
+ established by <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>, limited
+ by <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>. Note that the requested
+ number of workers may not actually be available at run time.
+ If this occurs, the utility operation will run with fewer
+ workers than expected. The default value is 2. Setting this
+ value to 0 disables the use of parallel workers by utility
+ commands.
+ </p><p>
+ Note that parallel utility commands should not consume
+ substantially more memory than equivalent non-parallel
+ operations. This strategy differs from that of parallel
+ query, where resource limits generally apply per worker
+ process. Parallel utility commands treat the resource limit
+ <code class="varname">maintenance_work_mem</code> as a limit to be applied to
+ the entire utility command, regardless of the number of
+ parallel worker processes. However, parallel utility
+ commands may still consume substantially more CPU resources
+ and I/O bandwidth.
+ </p></dd><dt id="GUC-MAX-PARALLEL-WORKERS"><span class="term"><code class="varname">max_parallel_workers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the maximum number of workers that the system can support for
+ parallel operations. The default value is 8. When increasing or
+ decreasing this value, consider also adjusting
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS">max_parallel_maintenance_workers</a> and
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a>.
+ Also, note that a setting for this value which is higher than
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a> will have no effect,
+ since parallel workers are taken from the pool of worker processes
+ established by that setting.
+ </p></dd><dt id="GUC-PARALLEL-LEADER-PARTICIPATION"><span class="term">
+ <code class="varname">parallel_leader_participation</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.7.7.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Allows the leader process to execute the query plan under
+ <code class="literal">Gather</code> and <code class="literal">Gather Merge</code> nodes
+ instead of waiting for worker processes. The default is
+ <code class="literal">on</code>. Setting this value to <code class="literal">off</code>
+ reduces the likelihood that workers will become blocked because the
+ leader is not reading tuples fast enough, but requires the leader
+ process to wait for worker processes to start up before the first
+ tuples can be produced. The degree to which the leader can help or
+ hinder performance depends on the plan type, number of workers and
+ query duration.
+ </p></dd><dt id="GUC-OLD-SNAPSHOT-THRESHOLD"><span class="term"><code class="varname">old_snapshot_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.7.7.2.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Sets the minimum amount of time that a query snapshot can be used
+ without risk of a <span class="quote">“<span class="quote">snapshot too old</span>”</span> error occurring
+ when using the snapshot. Data that has been dead for longer than
+ this threshold is allowed to be vacuumed away. This can help
+ prevent bloat in the face of snapshots which remain in use for a
+ long time. To prevent incorrect results due to cleanup of data which
+ would otherwise be visible to the snapshot, an error is generated
+ when the snapshot is older than this threshold and the snapshot is
+ used to read a page which has been modified since the snapshot was
+ built.
+ </p><p>
+ If this value is specified without units, it is taken as minutes.
+ A value of <code class="literal">-1</code> (the default) disables this feature,
+ effectively setting the snapshot age limit to infinity.
+ This parameter can only be set at server start.
+ </p><p>
+ Useful values for production work probably range from a small number
+ of hours to a few days. Small values (such as <code class="literal">0</code> or
+ <code class="literal">1min</code>) are only allowed because they may sometimes be
+ useful for testing. While a setting as high as <code class="literal">60d</code> is
+ allowed, please note that in many workloads extreme bloat or
+ transaction ID wraparound may occur in much shorter time frames.
+ </p><p>
+ When this feature is enabled, freed space at the end of a relation
+ cannot be released to the operating system, since that could remove
+ information needed to detect the <span class="quote">“<span class="quote">snapshot too old</span>”</span>
+ condition. All space allocated to a relation remains associated with
+ that relation for reuse only within that relation unless explicitly
+ freed (for example, with <code class="command">VACUUM FULL</code>).
+ </p><p>
+ This setting does not attempt to guarantee that an error will be
+ generated under any particular circumstances. In fact, if the
+ correct results can be generated from (for example) a cursor which
+ has materialized a result set, no error will be generated even if the
+ underlying rows in the referenced table have been vacuumed away.
+ Some tables cannot safely be vacuumed early, and so will not be
+ affected by this setting, such as system catalogs. For such tables
+ this setting will neither reduce bloat nor create a possibility
+ of a <span class="quote">“<span class="quote">snapshot too old</span>”</span> error on scanning.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-connection.html" title="20.3. Connections and Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-wal.html" title="20.5. Write Ahead Log">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.3. Connections and Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.5. Write Ahead Log</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-short.html b/doc/src/sgml/html/runtime-config-short.html
new file mode 100644
index 0000000..e48cf46
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-short.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.18. Short Options</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-developer.html" title="20.17. Developer Options" /><link rel="next" href="client-authentication.html" title="Chapter 21. Client Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.18. Short Options</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-developer.html" title="20.17. Developer Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="client-authentication.html" title="Chapter 21. Client Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-SHORT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.18. Short Options</h2></div></div></div><p>
+ For convenience there are also single letter command-line option
+ switches available for some parameters. They are described in
+ <a class="xref" href="runtime-config-short.html#RUNTIME-CONFIG-SHORT-TABLE" title="Table 20.4. Short Option Key">Table 20.4</a>. 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.
+ </p><div class="table" id="RUNTIME-CONFIG-SHORT-TABLE"><p class="title"><strong>Table 20.4. Short Option Key</strong></p><div class="table-contents"><table class="table" summary="Short Option Key" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Short Option</th><th>Equivalent</th></tr></thead><tbody><tr><td><code class="option">-B <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">shared_buffers = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-d <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">log_min_messages = DEBUG<em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-e</code></td><td><code class="literal">datestyle = euro</code></td></tr><tr><td>
+ <code class="option">-fb</code>, <code class="option">-fh</code>, <code class="option">-fi</code>,
+ <code class="option">-fm</code>, <code class="option">-fn</code>, <code class="option">-fo</code>,
+ <code class="option">-fs</code>, <code class="option">-ft</code>
+ </td><td>
+ <code class="literal">enable_bitmapscan = off</code>,
+ <code class="literal">enable_hashjoin = off</code>,
+ <code class="literal">enable_indexscan = off</code>,
+ <code class="literal">enable_mergejoin = off</code>,
+ <code class="literal">enable_nestloop = off</code>,
+ <code class="literal">enable_indexonlyscan = off</code>,
+ <code class="literal">enable_seqscan = off</code>,
+ <code class="literal">enable_tidscan = off</code>
+ </td></tr><tr><td><code class="option">-F</code></td><td><code class="literal">fsync = off</code></td></tr><tr><td><code class="option">-h <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">listen_addresses = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-i</code></td><td><code class="literal">listen_addresses = '*'</code></td></tr><tr><td><code class="option">-k <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">unix_socket_directories = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-l</code></td><td><code class="literal">ssl = on</code></td></tr><tr><td><code class="option">-N <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">max_connections = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-O</code></td><td><code class="literal">allow_system_table_mods = on</code></td></tr><tr><td><code class="option">-p <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">port = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-P</code></td><td><code class="literal">ignore_system_indexes = on</code></td></tr><tr><td><code class="option">-s</code></td><td><code class="literal">log_statement_stats = on</code></td></tr><tr><td><code class="option">-S <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">work_mem = <em class="replaceable"><code>x</code></em></code></td></tr><tr><td><code class="option">-tpa</code>, <code class="option">-tpl</code>, <code class="option">-te</code></td><td><code class="literal">log_parser_stats = on</code>,
+ <code class="literal">log_planner_stats = on</code>,
+ <code class="literal">log_executor_stats = on</code></td></tr><tr><td><code class="option">-W <em class="replaceable"><code>x</code></em></code></td><td><code class="literal">post_auth_delay = <em class="replaceable"><code>x</code></em></code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-developer.html" title="20.17. Developer Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="client-authentication.html" title="Chapter 21. Client Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.17. Developer Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 21. Client Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-statistics.html b/doc/src/sgml/html/runtime-config-statistics.html
new file mode 100644
index 0000000..e9f9279
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-statistics.html
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.9. Run-time Statistics</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging" /><link rel="next" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.9. Run-time Statistics</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-STATISTICS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.9. Run-time Statistics</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">20.9.1. Cumulative Query and Index Statistics</a></span></dt><dt><span class="sect2"><a href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">20.9.2. Statistics Monitoring</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-CUMULATIVE-STATISTICS"><div class="titlepage"><div><div><h3 class="title">20.9.1. Cumulative Query and Index Statistics</h3></div></div></div><p>
+ These parameters control the server-wide cumulative statistics system.
+ When enabled, the data that is collected can be accessed via the
+ <code class="structname">pg_stat</code> and <code class="structname">pg_statio</code>
+ family of system views. Refer to <a class="xref" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Chapter 28</a> for more
+ information.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-TRACK-ACTIVITIES"><span class="term"><code class="varname">track_activities</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.2.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables the collection of information on the currently
+ executing command of each session, along with its identifier and the
+ time when that command began execution. This parameter is on by
+ default. Note that even when enabled, this information is only
+ visible to superusers, roles with privileges of the
+ <code class="literal">pg_read_all_stats</code> role and the user owning the
+ sessions being reported on (including sessions belonging to a role they
+ have the privileges of), so it should not represent a security risk.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-TRACK-ACTIVITY-QUERY-SIZE"><span class="term"><code class="varname">track_activity_query_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.12.2.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the amount of memory reserved to store the text of the
+ currently executing command for each active session, for the
+ <code class="structname">pg_stat_activity</code>.<code class="structfield">query</code> field.
+ If this value is specified without units, it is taken as bytes.
+ The default value is 1024 bytes.
+ This parameter can only be set at server start.
+ </p></dd><dt id="GUC-TRACK-COUNTS"><span class="term"><code class="varname">track_counts</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.2.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables collection of statistics on database activity.
+ This parameter is on by default, because the autovacuum
+ daemon needs the collected information.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-TRACK-IO-TIMING"><span class="term"><code class="varname">track_io_timing</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.2.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables timing of database I/O calls. This parameter is off by
+ default, as it will repeatedly query the operating system for
+ the current time, which may cause significant overhead on some
+ platforms. You can use the <a class="xref" href="pgtesttiming.html" title="pg_test_timing"><span class="refentrytitle"><span class="application">pg_test_timing</span></span></a> tool to
+ measure the overhead of timing on your system.
+ I/O timing information is
+ displayed in <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW" title="28.2.15. pg_stat_database">
+ <code class="structname">pg_stat_database</code></a>, in the output of
+ <a class="xref" href="sql-explain.html" title="EXPLAIN"><span class="refentrytitle">EXPLAIN</span></a> when the <code class="literal">BUFFERS</code> option
+ is used, in the output of <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a> when
+ the <code class="literal">VERBOSE</code> option is used, by autovacuum
+ for auto-vacuums and auto-analyzes, when <a class="xref" href="runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION">log_autovacuum_min_duration</a> is set and by
+ <a class="xref" href="pgstatstatements.html" title="F.32. pg_stat_statements">pg_stat_statements</a>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-TRACK-WAL-IO-TIMING"><span class="term"><code class="varname">track_wal_io_timing</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.2.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables timing of WAL I/O calls. This parameter is off by default,
+ as it will repeatedly query the operating system for the current time,
+ which may cause significant overhead on some platforms.
+ You can use the <span class="application">pg_test_timing</span> tool to
+ measure the overhead of timing on your system.
+ I/O timing information is
+ displayed in <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-VIEW" title="28.2.14. pg_stat_wal">
+ <code class="structname">pg_stat_wal</code></a>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p></dd><dt id="GUC-TRACK-FUNCTIONS"><span class="term"><code class="varname">track_functions</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.12.2.3.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables tracking of function call counts and time used. Specify
+ <code class="literal">pl</code> to track only procedural-language functions,
+ <code class="literal">all</code> to also track SQL and C language functions.
+ The default is <code class="literal">none</code>, which disables function
+ statistics tracking.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ SQL-language functions that are simple enough to be <span class="quote">“<span class="quote">inlined</span>”</span>
+ into the calling query will not be tracked, regardless of this
+ setting.
+ </p></div></dd><dt id="GUC-STATS-FETCH-CONSISTENCY"><span class="term"><code class="varname">stats_fetch_consistency</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.12.2.3.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines the behavior when cumulative statistics are accessed
+ multiple times within a transaction. When set to
+ <code class="literal">none</code>, each access re-fetches counters from shared
+ memory. When set to <code class="literal">cache</code>, the first access to
+ statistics for an object caches those statistics until the end of the
+ transaction unless <code class="function">pg_stat_clear_snapshot()</code> is
+ called. When set to <code class="literal">snapshot</code>, the first statistics
+ access caches all statistics accessible in the current database, until
+ the end of the transaction unless
+ <code class="function">pg_stat_clear_snapshot()</code> is called. Changing this
+ parameter in a transaction discards the statistics snapshot.
+ The default is <code class="literal">cache</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="literal">none</code> is most suitable for monitoring systems. If
+ values are only accessed once, it is the most
+ efficient. <code class="literal">cache</code> ensures repeat accesses yield the
+ same values, which is important for queries involving
+ e.g. self-joins. <code class="literal">snapshot</code> can be useful when
+ interactively inspecting statistics, but has higher overhead,
+ particularly if many database objects exist.
+ </p></div></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-STATISTICS-MONITOR"><div class="titlepage"><div><div><h3 class="title">20.9.2. Statistics Monitoring</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-COMPUTE-QUERY-ID"><span class="term"><code class="varname">compute_query_id</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.12.3.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables in-core computation of a query identifier.
+ Query identifiers can be displayed in the <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity"><code class="structname">pg_stat_activity</code></a>
+ view, using <code class="command">EXPLAIN</code>, or emitted in the log if
+ configured via the <a class="xref" href="runtime-config-logging.html#GUC-LOG-LINE-PREFIX">log_line_prefix</a> parameter.
+ The <a class="xref" href="pgstatstatements.html" title="F.32. pg_stat_statements">pg_stat_statements</a> extension also requires a query
+ identifier to be computed. Note that an external module can
+ alternatively be used if the in-core query identifier computation
+ method is not acceptable. In this case, in-core computation
+ must be always disabled.
+ Valid values are <code class="literal">off</code> (always disabled),
+ <code class="literal">on</code> (always enabled), <code class="literal">auto</code>,
+ which lets modules such as <a class="xref" href="pgstatstatements.html" title="F.32. pg_stat_statements">pg_stat_statements</a>
+ automatically enable it, and <code class="literal">regress</code> which
+ has the same effect as <code class="literal">auto</code>, except that the
+ query identifier is not shown in the <code class="literal">EXPLAIN</code> output
+ in order to facilitate automated regression testing.
+ The default is <code class="literal">auto</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ To ensure that only one query identifier is calculated and
+ displayed, extensions that calculate query identifiers should
+ throw an error if a query identifier has already been computed.
+ </p></div></dd><dt><span class="term"><code class="varname">log_statement_stats</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.3.2.2.1.3" class="indexterm"></a>
+ <br /></span><span class="term"><code class="varname">log_parser_stats</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.3.2.2.2.3" class="indexterm"></a>
+ <br /></span><span class="term"><code class="varname">log_planner_stats</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.3.2.2.3.3" class="indexterm"></a>
+ <br /></span><span class="term"><code class="varname">log_executor_stats</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.12.3.2.2.4.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ For each query, output performance statistics of the respective
+ module to the server log. This is a crude profiling
+ instrument, similar to the Unix <code class="function">getrusage()</code> operating
+ system facility. <code class="varname">log_statement_stats</code> reports total
+ statement statistics, while the others report per-module statistics.
+ <code class="varname">log_statement_stats</code> cannot be enabled together with
+ any of the per-module options. All of these options are disabled by
+ default.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change these settings.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-logging.html" title="20.8. Error Reporting and Logging">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-autovacuum.html" title="20.10. Automatic Vacuuming">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.8. Error Reporting and Logging </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.10. Automatic Vacuuming</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config-wal.html b/doc/src/sgml/html/runtime-config-wal.html
new file mode 100644
index 0000000..5103255
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config-wal.html
@@ -0,0 +1,830 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.5. Write Ahead Log</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-resource.html" title="20.4. Resource Consumption" /><link rel="next" href="runtime-config-replication.html" title="20.6. Replication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.5. Write Ahead Log</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-resource.html" title="20.4. Resource Consumption">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-replication.html" title="20.6. Replication">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-WAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.5. Write Ahead Log</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">20.5.1. Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">20.5.2. Checkpoints</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">20.5.3. Archiving</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">20.5.4. Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">20.5.5. Archive Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">20.5.6. Recovery Target</a></span></dt></dl></div><p>
+ For additional information on tuning these settings,
+ see <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a>.
+ </p><div class="sect2" id="RUNTIME-CONFIG-WAL-SETTINGS"><div class="titlepage"><div><div><h3 class="title">20.5.1. Settings</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-WAL-LEVEL"><span class="term"><code class="varname">wal_level</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.3.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ <code class="varname">wal_level</code> determines how much information is written to
+ the WAL. The default value is <code class="literal">replica</code>, which writes enough
+ data to support WAL archiving and replication, including running
+ read-only queries on a standby server. <code class="literal">minimal</code> removes all
+ logging except the information required to recover from a crash or
+ immediate shutdown. Finally,
+ <code class="literal">logical</code> adds information necessary to support logical
+ decoding. Each level includes the information logged at all lower
+ levels. This parameter can only be set at server start.
+ </p><p>
+ The <code class="literal">minimal</code> level generates the least WAL
+ volume. It logs no row information for permanent relations
+ in transactions that create or
+ rewrite them. This can make operations much faster (see
+ <a class="xref" href="populate.html#POPULATE-PITR" title="14.4.7. Disable WAL Archival and Streaming Replication">Section 14.4.7</a>). Operations that initiate this
+ optimization include:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="command">ALTER ... SET TABLESPACE</code></td></tr><tr><td><code class="command">CLUSTER</code></td></tr><tr><td><code class="command">CREATE TABLE</code></td></tr><tr><td><code class="command">REFRESH MATERIALIZED VIEW</code>
+ (without <code class="option">CONCURRENTLY</code>)</td></tr><tr><td><code class="command">REINDEX</code></td></tr><tr><td><code class="command">TRUNCATE</code></td></tr></table><p>
+ However, minimal WAL does not contain sufficient information for
+ point-in-time recovery, so <code class="literal">replica</code> or
+ higher must be used to enable continuous archiving
+ (<a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a>) and streaming binary replication.
+ In fact, the server will not even start in this mode if
+ <code class="varname">max_wal_senders</code> is non-zero.
+ Note that changing <code class="varname">wal_level</code> to
+ <code class="literal">minimal</code> makes previous base backups unusable
+ for point-in-time recovery and standby servers.
+ </p><p>
+ In <code class="literal">logical</code> level, the same information is logged as
+ with <code class="literal">replica</code>, plus information needed to
+ extract logical change sets from the WAL. Using a level of
+ <code class="literal">logical</code> will increase the WAL volume, particularly if many
+ tables are configured for <code class="literal">REPLICA IDENTITY FULL</code> and
+ many <code class="command">UPDATE</code> and <code class="command">DELETE</code> statements are
+ executed.
+ </p><p>
+ In releases prior to 9.6, this parameter also allowed the
+ values <code class="literal">archive</code> and <code class="literal">hot_standby</code>.
+ These are still accepted but mapped to <code class="literal">replica</code>.
+ </p></dd><dt id="GUC-FSYNC"><span class="term"><code class="varname">fsync</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.3.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If this parameter is on, the <span class="productname">PostgreSQL</span> server
+ will try to make sure that updates are physically written to
+ disk, by issuing <code class="function">fsync()</code> system calls or various
+ equivalent methods (see <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a>).
+ This ensures that the database cluster can recover to a
+ consistent state after an operating system or hardware crash.
+ </p><p>
+ While turning off <code class="varname">fsync</code> is often a performance
+ benefit, this can result in unrecoverable data corruption in
+ the event of a power failure or system crash. Thus it
+ is only advisable to turn off <code class="varname">fsync</code> if
+ you can easily recreate your entire database from external
+ data.
+ </p><p>
+ Examples of safe circumstances for turning off
+ <code class="varname">fsync</code> include the initial loading of a new
+ database cluster from a backup file, using a database cluster
+ for processing a batch of data after which the database
+ will be thrown away and recreated,
+ or for a read-only database clone which
+ gets recreated frequently and is not used for failover. High
+ quality hardware alone is not a sufficient justification for
+ turning off <code class="varname">fsync</code>.
+ </p><p>
+ For reliable recovery when changing <code class="varname">fsync</code>
+ off to on, it is necessary to force all modified buffers in the
+ kernel to durable storage. This can be done while the cluster
+ is shutdown or while <code class="varname">fsync</code> is on by running <code class="command">initdb
+ --sync-only</code>, running <code class="command">sync</code>, unmounting the
+ file system, or rebooting the server.
+ </p><p>
+ In many situations, turning off <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a>
+ for noncritical transactions can provide much of the potential
+ performance benefit of turning off <code class="varname">fsync</code>, without
+ the attendant risks of data corruption.
+ </p><p>
+ <code class="varname">fsync</code> can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ If you turn this parameter off, also consider turning off
+ <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a>.
+ </p></dd><dt id="GUC-SYNCHRONOUS-COMMIT"><span class="term"><code class="varname">synchronous_commit</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.3.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies how much WAL processing must complete before
+ the database server returns a <span class="quote">“<span class="quote">success</span>”</span>
+ indication to the client. Valid values are
+ <code class="literal">remote_apply</code>, <code class="literal">on</code>
+ (the default), <code class="literal">remote_write</code>,
+ <code class="literal">local</code>, and <code class="literal">off</code>.
+ </p><p>
+ If <code class="varname">synchronous_standby_names</code> is empty,
+ the only meaningful settings are <code class="literal">on</code> and
+ <code class="literal">off</code>; <code class="literal">remote_apply</code>,
+ <code class="literal">remote_write</code> and <code class="literal">local</code>
+ all provide the same local synchronization level
+ as <code class="literal">on</code>. The local behavior of all
+ non-<code class="literal">off</code> modes is to wait for local flush of WAL
+ to disk. In <code class="literal">off</code> mode, there is no waiting,
+ so there can be a delay between when success is reported to the
+ client and when the transaction is later guaranteed to be safe
+ against a server crash. (The maximum
+ delay is three times <a class="xref" href="runtime-config-wal.html#GUC-WAL-WRITER-DELAY">wal_writer_delay</a>.) Unlike
+ <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a>, setting this parameter to <code class="literal">off</code>
+ 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
+ the database state will be just the same as if those transactions had
+ been aborted cleanly. So, turning <code class="varname">synchronous_commit</code> off
+ can be a useful alternative when performance is more important than
+ exact certainty about the durability of a transaction. For more
+ discussion see <a class="xref" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Section 30.4</a>.
+ </p><p>
+ If <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a> is non-empty,
+ <code class="varname">synchronous_commit</code> also controls whether
+ transaction commits will wait for their WAL records to be
+ processed on the standby server(s).
+ </p><p>
+ When set to <code class="literal">remote_apply</code>, commits will wait
+ until replies from the current synchronous standby(s) indicate they
+ have received the commit record of the transaction and applied
+ it, so that it has become visible to queries on the standby(s),
+ and also written to durable storage on the standbys. This will
+ cause much larger commit delays than previous settings since
+ it waits for WAL replay. When set to <code class="literal">on</code>,
+ commits wait until replies
+ from the current synchronous standby(s) indicate they have received
+ the commit record of the transaction and flushed it to durable storage. This
+ ensures the transaction will not be lost unless both the primary and
+ all synchronous standbys suffer corruption of their database storage.
+ When set to <code class="literal">remote_write</code>, commits will wait until replies
+ from the current synchronous standby(s) indicate they have
+ received the commit record of the transaction and written it to
+ their file systems. This setting ensures data preservation if a standby instance of
+ <span class="productname">PostgreSQL</span> crashes, but not if the standby
+ suffers an operating-system-level crash because the data has not
+ necessarily reached durable storage on the standby.
+ The setting <code class="literal">local</code> causes commits to wait for
+ local flush to disk, but not for replication. This is usually not
+ desirable when synchronous replication is in use, but is provided for
+ completeness.
+ </p><p>
+ This parameter can be changed at any time; the behavior for any
+ one transaction is determined by the setting in effect when it
+ commits. It is therefore possible, and useful, to have some
+ transactions commit synchronously and others asynchronously.
+ For example, to make a single multistatement transaction commit
+ asynchronously when the default is the opposite, issue <code class="command">SET
+ LOCAL synchronous_commit TO OFF</code> within the transaction.
+ </p><p>
+ <a class="xref" href="runtime-config-wal.html#SYNCHRONOUS-COMMIT-MATRIX" title="Table 20.1. synchronous_commit Modes">Table 20.1</a> summarizes the
+ capabilities of the <code class="varname">synchronous_commit</code> settings.
+ </p><div class="table" id="SYNCHRONOUS-COMMIT-MATRIX"><p class="title"><strong>Table 20.1. synchronous_commit Modes</strong></p><div class="table-contents"><table class="table" summary="synchronous_commit Modes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>synchronous_commit setting</th><th>local durable commit</th><th>standby durable commit after PG crash</th><th>standby durable commit after OS crash</th><th>standby query consistency</th></tr></thead><tbody><tr><td>remote_apply</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td></tr><tr><td>on</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center"> </td></tr><tr><td>remote_write</td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center"> </td></tr><tr><td>local</td><td align="center">•</td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td>off</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="GUC-WAL-SYNC-METHOD"><span class="term"><code class="varname">wal_sync_method</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.3.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Method used for forcing WAL updates out to disk.
+ If <code class="varname">fsync</code> is off then this setting is irrelevant,
+ since WAL file updates will not be forced out at all.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">open_datasync</code> (write WAL files with <code class="function">open()</code> option <code class="symbol">O_DSYNC</code>)
+ </p></li><li class="listitem"><p>
+ <code class="literal">fdatasync</code> (call <code class="function">fdatasync()</code> at each commit)
+ </p></li><li class="listitem"><p>
+ <code class="literal">fsync</code> (call <code class="function">fsync()</code> at each commit)
+ </p></li><li class="listitem"><p>
+ <code class="literal">fsync_writethrough</code> (call <code class="function">fsync()</code> at each commit, forcing write-through of any disk write cache)
+ </p></li><li class="listitem"><p>
+ <code class="literal">open_sync</code> (write WAL files with <code class="function">open()</code> option <code class="symbol">O_SYNC</code>)
+ </p></li></ul></div><p>
+ The <code class="literal">open_</code>* options also use <code class="literal">O_DIRECT</code> if available.
+ Not all of these choices are available on all platforms.
+ The default is the first method in the above list that is supported
+ by the platform, except that <code class="literal">fdatasync</code> is the default on
+ Linux and FreeBSD. The default is not necessarily ideal; it might be
+ 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 <a class="xref" href="wal-reliability.html" title="30.1. Reliability">Section 30.1</a>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-FULL-PAGE-WRITES"><span class="term"><code class="varname">full_page_writes</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.3.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When this parameter is on, the <span class="productname">PostgreSQL</span> server
+ writes the entire content of each disk page to WAL during the
+ first modification of that page after a checkpoint.
+ This is needed because
+ a page write that is in process during an operating system crash might
+ be only partially completed, leading to an on-disk page
+ that contains a mix of old and new data. The row-level change data
+ normally stored in WAL will not be enough to completely restore
+ such a page during post-crash recovery. Storing the full page image
+ guarantees that the page can be correctly restored, but at the price
+ of increasing the amount of data that must be written to WAL.
+ (Because WAL replay always starts from a checkpoint, it is sufficient
+ to do this during the first change of each page after a checkpoint.
+ Therefore, one way to reduce the cost of full-page writes is to
+ increase the checkpoint interval parameters.)
+ </p><p>
+ Turning this parameter off speeds normal operation, but
+ might lead to either unrecoverable data corruption, or silent
+ data corruption, after a system failure. The risks are similar to turning off
+ <code class="varname">fsync</code>, though smaller, and it should be turned off
+ only based on the same circumstances recommended for that parameter.
+ </p><p>
+ Turning off this parameter does not affect use of
+ WAL archiving for point-in-time recovery (PITR)
+ (see <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>).
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ The default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-WAL-LOG-HINTS"><span class="term"><code class="varname">wal_log_hints</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.3.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When this parameter is <code class="literal">on</code>, the <span class="productname">PostgreSQL</span>
+ server writes the entire content of each disk page to WAL during the
+ first modification of that page after a checkpoint, even for
+ non-critical modifications of so-called hint bits.
+ </p><p>
+ If data checksums are enabled, hint bit updates are always WAL-logged
+ and this setting is ignored. You can use this setting to test how much
+ extra WAL-logging would occur if your database had data checksums
+ enabled.
+ </p><p>
+ This parameter can only be set at server start. The default value is <code class="literal">off</code>.
+ </p></dd><dt id="GUC-WAL-COMPRESSION"><span class="term"><code class="varname">wal_compression</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.3.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter enables compression of WAL using the specified
+ compression method.
+ When enabled, the <span class="productname">PostgreSQL</span>
+ server compresses full page images written to WAL when
+ <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> is on or during a base backup.
+ A compressed page image will be decompressed during WAL replay.
+ The supported methods are <code class="literal">pglz</code>,
+ <code class="literal">lz4</code> (if <span class="productname">PostgreSQL</span>
+ was compiled with <code class="option">--with-lz4</code>) and
+ <code class="literal">zstd</code> (if <span class="productname">PostgreSQL</span>
+ was compiled with <code class="option">--with-zstd</code>).
+ The default value is <code class="literal">off</code>.
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ Enabling compression can reduce the WAL volume without
+ increasing the risk of unrecoverable data corruption,
+ but at the cost of some extra CPU spent on the compression during
+ WAL logging and on the decompression during WAL replay.
+ </p></dd><dt id="GUC-WAL-INIT-ZERO"><span class="term"><code class="varname">wal_init_zero</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.3.2.8.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set to <code class="literal">on</code> (the default), this option causes new
+ WAL files to be filled with zeroes. On some file systems, this ensures
+ that space is allocated before we need to write WAL records. However,
+ <em class="firstterm">Copy-On-Write</em> (COW) file systems may not benefit
+ from this technique, so the option is given to skip the unnecessary
+ work. If set to <code class="literal">off</code>, only the final byte is written
+ when the file is created so that it has the expected size.
+ </p></dd><dt id="GUC-WAL-RECYCLE"><span class="term"><code class="varname">wal_recycle</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.3.2.9.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ If set to <code class="literal">on</code> (the default), this option causes WAL
+ files to be recycled by renaming them, avoiding the need to create new
+ ones. On COW file systems, it may be faster to create new ones, so the
+ option is given to disable this behavior.
+ </p></dd><dt id="GUC-WAL-BUFFERS"><span class="term"><code class="varname">wal_buffers</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.10.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ 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 <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but not less
+ than <code class="literal">64kB</code> nor more than the size of one WAL
+ segment, typically <code class="literal">16MB</code>. This value can be set
+ manually if the automatic choice is too large or too small,
+ but any positive value less than <code class="literal">32kB</code> will be
+ treated as <code class="literal">32kB</code>.
+ If this value is specified without units, it is taken as WAL blocks,
+ that is <code class="symbol">XLOG_BLCKSZ</code> bytes, typically 8kB.
+ This parameter can only be set at server start.
+ </p><p>
+ The contents of the WAL buffers are written out to disk at every
+ transaction commit, so extremely large values are unlikely to
+ provide a significant benefit. However, setting this value to at
+ least a few megabytes can improve write performance on a busy
+ server where many clients are committing at once. The auto-tuning
+ selected by the default setting of -1 should give reasonable
+ results in most cases.
+ </p></dd><dt id="GUC-WAL-WRITER-DELAY"><span class="term"><code class="varname">wal_writer_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies how often the WAL writer flushes WAL, in time terms.
+ After flushing WAL the writer sleeps for the length of time given
+ by <code class="varname">wal_writer_delay</code>, unless woken up sooner
+ by an asynchronously committing transaction. If the last flush
+ happened less than <code class="varname">wal_writer_delay</code> ago and less
+ than <code class="varname">wal_writer_flush_after</code> worth of WAL has been
+ produced since, then WAL is only written to the operating system, not
+ flushed to disk.
+ If this value is specified without units, it is taken as milliseconds.
+ The default value is 200 milliseconds (<code class="literal">200ms</code>). Note that
+ on many systems, the effective resolution of sleep delays is 10
+ milliseconds; setting <code class="varname">wal_writer_delay</code> to a value that is
+ not a multiple of 10 might have the same results as setting it to the
+ next higher multiple of 10. This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-WAL-WRITER-FLUSH-AFTER"><span class="term"><code class="varname">wal_writer_flush_after</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies how often the WAL writer flushes WAL, in volume terms.
+ If the last flush happened less
+ than <code class="varname">wal_writer_delay</code> ago and less
+ than <code class="varname">wal_writer_flush_after</code> worth of WAL has been
+ produced since, then WAL is only written to the operating system, not
+ flushed to disk. If <code class="varname">wal_writer_flush_after</code> is set
+ to <code class="literal">0</code> then WAL data is always flushed immediately.
+ If this value is specified without units, it is taken as WAL blocks,
+ that is <code class="symbol">XLOG_BLCKSZ</code> bytes, typically 8kB.
+ The default is <code class="literal">1MB</code>.
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-WAL-SKIP-THRESHOLD"><span class="term"><code class="varname">wal_skip_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.13.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">wal_level</code> is <code class="literal">minimal</code> and a
+ transaction commits after creating or rewriting a permanent relation,
+ this setting determines how to persist the new data. If the data is
+ smaller than this setting, write it to the WAL log; otherwise, use an
+ fsync of affected files. Depending on the properties of your storage,
+ raising or lowering this value might help if such commits are slowing
+ concurrent transactions. If this value is specified without units, it
+ is taken as kilobytes. The default is two megabytes
+ (<code class="literal">2MB</code>).
+ </p></dd><dt id="GUC-COMMIT-DELAY"><span class="term"><code class="varname">commit_delay</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.14.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Setting <code class="varname">commit_delay</code> adds a time delay
+ before a WAL flush is initiated. This can improve
+ group commit throughput by allowing a larger number of transactions
+ to commit via a single WAL flush, if system load is high enough
+ that additional transactions become ready to commit within the
+ given interval. However, it also increases latency by up to the
+ <code class="varname">commit_delay</code> for each WAL
+ flush. Because the delay is just wasted if no other transactions
+ become ready to commit, a delay is only performed if at least
+ <code class="varname">commit_siblings</code> other transactions are active
+ when a flush is about to be initiated. Also, no delays are
+ performed if <code class="varname">fsync</code> is disabled.
+ If this value is specified without units, it is taken as microseconds.
+ The default <code class="varname">commit_delay</code> is zero (no delay).
+ Only superusers and users with the appropriate <code class="literal">SET</code>
+ privilege can change this setting.
+ </p><p>
+ In <span class="productname">PostgreSQL</span> releases prior to 9.3,
+ <code class="varname">commit_delay</code> behaved differently and was much
+ less effective: it affected only commits, rather than all WAL flushes,
+ and waited for the entire configured delay even if the WAL flush
+ was completed sooner. Beginning in <span class="productname">PostgreSQL</span> 9.3,
+ the first process that becomes ready to flush waits for the configured
+ interval, while subsequent processes wait only until the leader
+ completes the flush operation.
+ </p></dd><dt id="GUC-COMMIT-SIBLINGS"><span class="term"><code class="varname">commit_siblings</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.3.2.15.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Minimum number of concurrent open transactions to require
+ before performing the <code class="varname">commit_delay</code> delay. A larger
+ value makes it more probable that at least one other
+ transaction will become ready to commit during the delay
+ interval. The default is five transactions.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-CHECKPOINTS"><div class="titlepage"><div><div><h3 class="title">20.5.2. Checkpoints</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-CHECKPOINT-TIMEOUT"><span class="term"><code class="varname">checkpoint_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.4.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Maximum time between automatic WAL checkpoints.
+ If this value is specified without units, it is taken as seconds.
+ The valid range is between 30 seconds and one day.
+ The default is five minutes (<code class="literal">5min</code>).
+ Increasing this parameter can increase the amount of time needed
+ for crash recovery.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-CHECKPOINT-COMPLETION-TARGET"><span class="term"><code class="varname">checkpoint_completion_target</code> (<code class="type">floating point</code>)
+ <a id="id-1.6.7.8.4.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies the target of checkpoint completion, as a fraction of
+ total time between checkpoints. The default is 0.9, which spreads the
+ checkpoint across almost all of the available interval, providing fairly
+ consistent I/O load while also leaving some time for checkpoint
+ completion overhead. Reducing this parameter is not recommended because
+ it causes the checkpoint to complete faster. This results in a higher
+ rate of I/O during the checkpoint followed by a period of less I/O between
+ the checkpoint completion and the next scheduled checkpoint. This
+ parameter can only be set in the <code class="filename">postgresql.conf</code> file
+ or on the server command line.
+ </p></dd><dt id="GUC-CHECKPOINT-FLUSH-AFTER"><span class="term"><code class="varname">checkpoint_flush_after</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.4.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Whenever more than this amount of data has been
+ written while performing a checkpoint, attempt to force the
+ OS to issue these writes to the underlying storage. Doing so will
+ limit the amount of dirty data in the kernel's page cache, reducing
+ the likelihood of stalls when an <code class="function">fsync</code> is issued at the end of the
+ 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 <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but smaller
+ than the OS's page cache, where performance might degrade. This
+ setting may have no effect on some platforms.
+ If this value is specified without units, it is taken as blocks,
+ that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
+ The valid range is
+ between <code class="literal">0</code>, which disables forced writeback,
+ and <code class="literal">2MB</code>. The default is <code class="literal">256kB</code> on
+ Linux, <code class="literal">0</code> elsewhere. (If <code class="symbol">BLCKSZ</code> is not
+ 8kB, the default and maximum values scale proportionally to it.)
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-CHECKPOINT-WARNING"><span class="term"><code class="varname">checkpoint_warning</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.4.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Write a message to the server log if checkpoints caused by
+ the filling of WAL segment files happen closer together
+ than this amount of time (which suggests that
+ <code class="varname">max_wal_size</code> ought to be raised).
+ If this value is specified without units, it is taken as seconds.
+ The default is 30 seconds (<code class="literal">30s</code>).
+ Zero disables the warning.
+ No warnings will be generated if <code class="varname">checkpoint_timeout</code>
+ is less than <code class="varname">checkpoint_warning</code>.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-MAX-WAL-SIZE"><span class="term"><code class="varname">max_wal_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.4.2.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Maximum size to let the WAL grow during automatic
+ checkpoints. This is a soft limit; WAL size can exceed
+ <code class="varname">max_wal_size</code> under special circumstances, such as
+ heavy load, a failing <code class="varname">archive_command</code> or <code class="varname">archive_library</code>, or a high
+ <code class="varname">wal_keep_size</code> setting.
+ If this value is specified without units, it is taken as megabytes.
+ The default is 1 GB.
+ Increasing this parameter can increase the amount of time needed for
+ crash recovery.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-MIN-WAL-SIZE"><span class="term"><code class="varname">min_wal_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.4.2.6.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ As long as WAL disk usage stays below this setting, old WAL files are
+ always recycled for future use at a checkpoint, rather than removed.
+ This can be used to ensure that enough WAL space is reserved to
+ handle spikes in WAL usage, for example when running large batch
+ jobs.
+ If this value is specified without units, it is taken as megabytes.
+ The default is 80 MB.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-ARCHIVING"><div class="titlepage"><div><div><h3 class="title">20.5.3. Archiving</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-ARCHIVE-MODE"><span class="term"><code class="varname">archive_mode</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.5.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ When <code class="varname">archive_mode</code> is enabled, completed WAL segments
+ are sent to archive storage by setting
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a>. In addition to <code class="literal">off</code>,
+ to disable, there are two modes: <code class="literal">on</code>, and
+ <code class="literal">always</code>. During normal operation, there is no
+ difference between the two modes, but when set to <code class="literal">always</code>
+ the WAL archiver is enabled also during archive recovery or standby
+ mode. In <code class="literal">always</code> mode, all files restored from the archive
+ or streamed with streaming replication will be archived (again). See
+ <a class="xref" href="warm-standby.html#CONTINUOUS-ARCHIVING-IN-STANDBY" title="27.2.9. Continuous Archiving in Standby">Section 27.2.9</a> for details.
+ </p><p>
+ <code class="varname">archive_mode</code> is a separate setting from
+ <code class="varname">archive_command</code> and
+ <code class="varname">archive_library</code> so that
+ <code class="varname">archive_command</code> and
+ <code class="varname">archive_library</code> can be changed without leaving
+ archiving mode.
+ This parameter can only be set at server start.
+ <code class="varname">archive_mode</code> cannot be enabled when
+ <code class="varname">wal_level</code> is set to <code class="literal">minimal</code>.
+ </p></dd><dt id="GUC-ARCHIVE-COMMAND"><span class="term"><code class="varname">archive_command</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.5.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The local shell command to execute to archive a completed WAL file
+ segment. Any <code class="literal">%p</code> in the string is
+ replaced by the path name of the file to archive, and any
+ <code class="literal">%f</code> is replaced by only the file name.
+ (The path name is relative to the working directory of the server,
+ i.e., the cluster's data directory.)
+ Use <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character in the
+ command. It is important for the command to return a zero
+ exit status only if it succeeds. For more information see
+ <a class="xref" href="continuous-archiving.html#BACKUP-ARCHIVING-WAL" title="26.3.1. Setting Up WAL Archiving">Section 26.3.1</a>.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line. It is ignored unless
+ <code class="varname">archive_mode</code> was enabled at server start and
+ <code class="varname">archive_library</code> is set to an empty string.
+ If <code class="varname">archive_command</code> is an empty string (the default) while
+ <code class="varname">archive_mode</code> is enabled (and <code class="varname">archive_library</code>
+ is set to an empty string), WAL archiving is temporarily
+ disabled, but the server continues to accumulate WAL segment files in
+ the expectation that a command will soon be provided. Setting
+ <code class="varname">archive_command</code> to a command that does nothing but
+ return true, e.g., <code class="literal">/bin/true</code> (<code class="literal">REM</code> on
+ Windows), effectively disables
+ archiving, but also breaks the chain of WAL files needed for
+ archive recovery, so it should only be used in unusual circumstances.
+ </p></dd><dt id="GUC-ARCHIVE-LIBRARY"><span class="term"><code class="varname">archive_library</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.5.2.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The library to use for archiving completed WAL file segments. If set to
+ an empty string (the default), archiving via shell is enabled, and
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> is used. Otherwise, the specified
+ shared library is used for archiving. The WAL archiver process is
+ restarted by the postmaster when this parameter changes. For more
+ information, see <a class="xref" href="continuous-archiving.html#BACKUP-ARCHIVING-WAL" title="26.3.1. Setting Up WAL Archiving">Section 26.3.1</a> and
+ <a class="xref" href="archive-modules.html" title="Chapter 51. Archive Modules">Chapter 51</a>.
+ </p><p>
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd><dt id="GUC-ARCHIVE-TIMEOUT"><span class="term"><code class="varname">archive_timeout</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.5.2.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> 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
+ recording in archive storage. To limit how old unarchived
+ data can be, you can set <code class="varname">archive_timeout</code> to force the
+ server to switch to a new WAL segment file periodically. When this
+ parameter is greater than zero, the server will switch to a new
+ segment file whenever this amount of time has elapsed since the last
+ segment file switch, and there has been any database activity,
+ including a single checkpoint (checkpoints are skipped if there is
+ no database activity). Note that archived files that are closed
+ early due to a forced switch are still the same length as completely
+ full files. Therefore, it is unwise to use a very short
+ <code class="varname">archive_timeout</code> — it will bloat your archive
+ storage. <code class="varname">archive_timeout</code> settings of a minute or so are
+ usually reasonable. You should consider using streaming replication,
+ instead of archiving, if you want data to be copied off the primary
+ server more quickly than that.
+ If this value is specified without units, it is taken as seconds.
+ This parameter can only be set in the
+ <code class="filename">postgresql.conf</code> file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-RECOVERY"><div class="titlepage"><div><div><h3 class="title">20.5.4. Recovery</h3></div></div></div><a id="id-1.6.7.8.6.2" class="indexterm"></a><p>
+ This section describes the settings that apply to recovery in general,
+ affecting crash recovery, streaming replication and archive-based
+ replication.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-PREFETCH"><span class="term"><code class="varname">recovery_prefetch</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.6.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Whether to try to prefetch blocks that are referenced in the WAL that
+ are not yet in the buffer pool, during recovery. Valid values are
+ <code class="literal">off</code>, <code class="literal">on</code> and
+ <code class="literal">try</code> (the default). The setting
+ <code class="literal">try</code> enables
+ prefetching only if the operating system provides the
+ <code class="function">posix_fadvise</code> function, which is currently used
+ to implement prefetching. Note that some operating systems provide the
+ function, but it doesn't do anything.
+ </p><p>
+ Prefetching blocks that will soon be needed can reduce I/O wait times
+ during recovery with some workloads.
+ See also the <a class="xref" href="runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE">wal_decode_buffer_size</a> and
+ <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY">maintenance_io_concurrency</a> settings, which limit
+ prefetching activity.
+ </p></dd><dt id="GUC-WAL-DECODE-BUFFER-SIZE"><span class="term"><code class="varname">wal_decode_buffer_size</code> (<code class="type">integer</code>)
+ <a id="id-1.6.7.8.6.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ A limit on how far ahead the server can look in the WAL, to find
+ blocks to prefetch. If this value is specified without units, it is
+ taken as bytes.
+ The default is 512kB.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY"><div class="titlepage"><div><div><h3 class="title">20.5.5. Archive Recovery</h3></div></div></div><a id="id-1.6.7.8.7.2" class="indexterm"></a><p>
+ This section describes the settings that apply only for the duration of
+ the recovery. They must be reset for any subsequent recovery you wish to
+ perform.
+ </p><p>
+ <span class="quote">“<span class="quote">Recovery</span>”</span> covers using the server as a standby or for
+ executing a targeted recovery. Typically, standby mode would be used to
+ provide high availability and/or read scalability, whereas a targeted
+ recovery is used to recover from data loss.
+ </p><p>
+ To start the server in standby mode, create a file called
+ <code class="filename">standby.signal</code><a id="id-1.6.7.8.7.5.2" class="indexterm"></a>
+ in the data directory. The server will enter recovery and will not stop
+ recovery when the end of archived WAL is reached, but will keep trying to
+ continue recovery by connecting to the sending server as specified by the
+ <code class="varname">primary_conninfo</code> setting and/or by fetching new WAL
+ segments using <code class="varname">restore_command</code>. For this mode, the
+ parameters from this section and <a class="xref" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY" title="20.6.3. Standby Servers">Section 20.6.3</a> are of interest.
+ Parameters from <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="20.5.6. Recovery Target">Section 20.5.6</a> will
+ also be applied but are typically not useful in this mode.
+ </p><p>
+ To start the server in targeted recovery mode, create a file called
+ <code class="filename">recovery.signal</code><a id="id-1.6.7.8.7.6.2" class="indexterm"></a>
+ in the data directory. If both <code class="filename">standby.signal</code> and
+ <code class="filename">recovery.signal</code> files are created, standby mode
+ takes precedence. Targeted recovery mode ends when the archived WAL is
+ fully replayed, or when <code class="varname">recovery_target</code> is reached.
+ In this mode, the parameters from both this section and <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="20.5.6. Recovery Target">Section 20.5.6</a> will be used.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RESTORE-COMMAND"><span class="term"><code class="varname">restore_command</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.7.7.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The local shell command to execute to retrieve an archived segment of
+ the WAL file series. This parameter is required for archive recovery,
+ but optional for streaming replication.
+ Any <code class="literal">%f</code> in the string is
+ replaced by the name of the file to retrieve from the archive,
+ and any <code class="literal">%p</code> is replaced by the copy destination path name
+ on the server.
+ (The path name is relative to the current working directory,
+ i.e., the cluster's data directory.)
+ Any <code class="literal">%r</code> is replaced by the name of the file containing the
+ last valid restart point. That is the earliest file that must be kept
+ to allow a restore to be restartable, so this information can be used
+ to truncate the archive to just the minimum required to support
+ restarting from the current restore. <code class="literal">%r</code> is typically only
+ used by warm-standby configurations
+ (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
+ Write <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character.
+ </p><p>
+ It is important for the command to return a zero exit status
+ only if it succeeds. The command <span class="emphasis"><em>will</em></span> be asked for file
+ names that are not present in the archive; it must return nonzero
+ when so asked. Examples:
+</p><pre class="programlisting">
+restore_command = 'cp /mnt/server/archivedir/%f "%p"'
+restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
+</pre><p>
+ An exception is that if the command was terminated by a signal (other
+ than <span class="systemitem">SIGTERM</span>, which is used as part of a
+ database server shutdown) or an error by the shell (such as command
+ not found), then recovery will abort and the server will not start up.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-ARCHIVE-CLEANUP-COMMAND"><span class="term"><code class="varname">archive_cleanup_command</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.7.7.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This optional parameter specifies a shell command that will be executed
+ at every restartpoint. The purpose of
+ <code class="varname">archive_cleanup_command</code> is to provide a mechanism for
+ cleaning up old archived WAL files that are no longer needed by the
+ standby server.
+ Any <code class="literal">%r</code> is replaced by the name of the file containing the
+ last valid restart point.
+ That is the earliest file that must be <span class="emphasis"><em>kept</em></span> to allow a
+ restore to be restartable, and so all files earlier than <code class="literal">%r</code>
+ may be safely removed.
+ This information can be used to truncate the archive to just the
+ minimum required to support restart from the current restore.
+ The <a class="xref" href="pgarchivecleanup.html" title="pg_archivecleanup"><span class="refentrytitle"><span class="application">pg_archivecleanup</span></span></a> module
+ is often used in <code class="varname">archive_cleanup_command</code> for
+ single-standby configurations, for example:
+</p><pre class="programlisting">archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</pre><p>
+ Note however that if multiple standby servers are restoring from the
+ same archive directory, you will need to ensure that you do not delete
+ WAL files until they are no longer needed by any of the servers.
+ <code class="varname">archive_cleanup_command</code> would typically be used in a
+ warm-standby configuration (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
+ Write <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character in the
+ command.
+ </p><p>
+ If the command returns a nonzero exit status then a warning log
+ message will be written. An exception is that if the command was
+ terminated by a signal or an error by the shell (such as command not
+ found), a fatal error will be raised.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd><dt id="GUC-RECOVERY-END-COMMAND"><span class="term"><code class="varname">recovery_end_command</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.7.7.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies a shell command that will be executed once only
+ at the end of recovery. This parameter is optional. The purpose of the
+ <code class="varname">recovery_end_command</code> is to provide a mechanism for cleanup
+ following replication or recovery.
+ Any <code class="literal">%r</code> is replaced by the name of the file containing the
+ last valid restart point, like in <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-COMMAND">archive_cleanup_command</a>.
+ </p><p>
+ If the command returns a nonzero exit status then a warning log
+ message will be written and the database will proceed to start up
+ anyway. An exception is that if the command was terminated by a
+ signal or an error by the shell (such as command not found), the
+ database will not proceed with startup.
+ </p><p>
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-RECOVERY-TARGET"><div class="titlepage"><div><div><h3 class="title">20.5.6. Recovery Target</h3></div></div></div><p>
+ By default, recovery will recover to the end of the WAL log. The
+ following parameters can be used to specify an earlier stopping point.
+ At most one of <code class="varname">recovery_target</code>,
+ <code class="varname">recovery_target_lsn</code>, <code class="varname">recovery_target_name</code>,
+ <code class="varname">recovery_target_time</code>, or <code class="varname">recovery_target_xid</code>
+ can be used; if more than one of these is specified in the configuration
+ file, an error will be raised.
+ These parameters can only be set at server start.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-TARGET"><span class="term"><code class="varname">recovery_target</code><code class="literal"> = 'immediate'</code>
+ <a id="id-1.6.7.8.8.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies that recovery should end as soon as a
+ consistent state is reached, i.e., as early as possible. When restoring
+ from an online backup, this means the point where taking the backup
+ ended.
+ </p><p>
+ Technically, this is a string parameter, but <code class="literal">'immediate'</code>
+ is currently the only allowed value.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-NAME"><span class="term"><code class="varname">recovery_target_name</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.8.3.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies the named restore point (created with
+ <code class="function">pg_create_restore_point()</code>) to which recovery will proceed.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-TIME"><span class="term"><code class="varname">recovery_target_time</code> (<code class="type">timestamp</code>)
+ <a id="id-1.6.7.8.8.3.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies the time stamp up to which recovery
+ will proceed.
+ The precise stopping point is also influenced by
+ <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>.
+ </p><p>
+ The value of this parameter is a time stamp in the same format
+ accepted by the <code class="type">timestamp with time zone</code> data type,
+ except that you cannot use a time zone abbreviation (unless the
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE-ABBREVIATIONS">timezone_abbreviations</a> variable has been set
+ earlier in the configuration file). Preferred style is to use a
+ numeric offset from UTC, or you can write a full time zone name,
+ e.g., <code class="literal">Europe/Helsinki</code> not <code class="literal">EEST</code>.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-XID"><span class="term"><code class="varname">recovery_target_xid</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.8.3.4.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies the transaction ID up to which recovery
+ will proceed. Keep in mind
+ that while transaction IDs are assigned sequentially at transaction
+ start, transactions can complete in a different numeric order.
+ The transactions that will be recovered are those that committed
+ before (and optionally including) the specified one.
+ The precise stopping point is also influenced by
+ <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-LSN"><span class="term"><code class="varname">recovery_target_lsn</code> (<code class="type">pg_lsn</code>)
+ <a id="id-1.6.7.8.8.3.5.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter specifies the LSN of the write-ahead log location up
+ to which recovery will proceed. The precise stopping point is also
+ influenced by <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>. This
+ parameter is parsed using the system data type
+ <a class="link" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type"><code class="type">pg_lsn</code></a>.
+ </p></dd></dl></div><p>
+ The following options further specify the recovery target, and affect
+ what happens when the target is reached:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-TARGET-INCLUSIVE"><span class="term"><code class="varname">recovery_target_inclusive</code> (<code class="type">boolean</code>)
+ <a id="id-1.6.7.8.8.5.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies whether to stop just after the specified recovery target
+ (<code class="literal">on</code>), or just before the recovery target
+ (<code class="literal">off</code>).
+ Applies when <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-LSN">recovery_target_lsn</a>,
+ <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-TIME">recovery_target_time</a>, or
+ <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-XID">recovery_target_xid</a> is specified.
+ This setting controls whether transactions
+ having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will
+ be included in the recovery. Default is <code class="literal">on</code>.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-TIMELINE"><span class="term"><code class="varname">recovery_target_timeline</code> (<code class="type">string</code>)
+ <a id="id-1.6.7.8.8.5.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies recovering into a particular timeline. The value can be a
+ numeric timeline ID or a special value. The value
+ <code class="literal">current</code> recovers along the same timeline that was
+ current when the base backup was taken. The
+ value <code class="literal">latest</code> recovers
+ to the latest timeline found in the archive, which is useful in
+ a standby server. <code class="literal">latest</code> is the default.
+ </p><p>
+ You usually only need to set this parameter
+ in complex re-recovery situations, where you need to return to
+ a state that itself was reached after a point-in-time recovery.
+ See <a class="xref" href="continuous-archiving.html#BACKUP-TIMELINES" title="26.3.5. Timelines">Section 26.3.5</a> for discussion.
+ </p></dd><dt id="GUC-RECOVERY-TARGET-ACTION"><span class="term"><code class="varname">recovery_target_action</code> (<code class="type">enum</code>)
+ <a id="id-1.6.7.8.8.5.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Specifies what action the server should take once the recovery target is
+ reached. The default is <code class="literal">pause</code>, which means recovery will
+ be paused. <code class="literal">promote</code> means the recovery process will finish
+ and the server will start to accept connections.
+ Finally <code class="literal">shutdown</code> will stop the server after reaching the
+ recovery target.
+ </p><p>
+ The intended use of the <code class="literal">pause</code> setting is to allow queries
+ to be executed against the database to check if this recovery target
+ is the most desirable point for recovery.
+ The paused state can be resumed by
+ using <code class="function">pg_wal_replay_resume()</code> (see
+ <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE" title="Table 9.91. Recovery Control Functions">Table 9.91</a>), which then
+ causes recovery to end. If this recovery target is not the
+ desired stopping point, then shut down the server, change the
+ recovery target settings to a later target and restart to
+ continue recovery.
+ </p><p>
+ The <code class="literal">shutdown</code> setting is useful to have the instance ready
+ at the exact replay point desired. The instance will still be able to
+ replay more WAL records (and in fact will have to replay WAL records
+ since the last checkpoint next time it is started).
+ </p><p>
+ Note that because <code class="filename">recovery.signal</code> will not be
+ removed when <code class="varname">recovery_target_action</code> is set to <code class="literal">shutdown</code>,
+ any subsequent start will end with immediate shutdown unless the
+ configuration is changed or the <code class="filename">recovery.signal</code>
+ file is removed manually.
+ </p><p>
+ This setting has no effect if no recovery target is set.
+ If <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a> is not enabled, a setting of
+ <code class="literal">pause</code> will act the same as <code class="literal">shutdown</code>.
+ If the recovery target is reached while a promotion is ongoing,
+ a setting of <code class="literal">pause</code> will act the same as
+ <code class="literal">promote</code>.
+ </p><p>
+ In any case, if a recovery target is configured but the archive
+ recovery ends before the target is reached, the server will shut down
+ with a fatal error.
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-resource.html" title="20.4. Resource Consumption">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-replication.html" title="20.6. Replication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.4. Resource Consumption </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.6. Replication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime-config.html b/doc/src/sgml/html/runtime-config.html
new file mode 100644
index 0000000..b3781f6
--- /dev/null
+++ b/doc/src/sgml/html/runtime-config.html
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 20. Server Configuration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="event-log-registration.html" title="19.12. Registering Event Log on Windows" /><link rel="next" href="config-setting.html" title="20.1. Setting Parameters" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 20. Server Configuration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="event-log-registration.html" title="19.12. Registering Event Log on Windows">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="config-setting.html" title="20.1. Setting Parameters">Next</a></td></tr></table><hr /></div><div class="chapter" id="RUNTIME-CONFIG"><div class="titlepage"><div><div><h2 class="title">Chapter 20. Server Configuration</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="config-setting.html">20.1. Setting Parameters</a></span></dt><dd><dl><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-NAMES-VALUES">20.1.1. Parameter Names and Values</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE">20.1.2. Parameter Interaction via the Configuration File</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-SETTING-SQL-COMMAND-INTERACTION">20.1.3. Parameter Interaction via SQL</a></span></dt><dt><span class="sect2"><a href="config-setting.html#id-1.6.7.4.5">20.1.4. Parameter Interaction via the Shell</a></span></dt><dt><span class="sect2"><a href="config-setting.html#CONFIG-INCLUDES">20.1.5. Managing Configuration File Contents</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-file-locations.html">20.2. File Locations</a></span></dt><dt><span class="sect1"><a href="runtime-config-connection.html">20.3. Connections and Authentication</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">20.3.1. Connection Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">20.3.2. Authentication</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">20.3.3. SSL</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-resource.html">20.4. Resource Consumption</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY">20.4.1. Memory</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-DISK">20.4.2. Disk</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-KERNEL">20.4.3. Kernel Resource Usage</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST">20.4.4. Cost-based Vacuum Delay</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-BACKGROUND-WRITER">20.4.5. Background Writer</a></span></dt><dt><span class="sect2"><a href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-ASYNC-BEHAVIOR">20.4.6. Asynchronous Behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-wal.html">20.5. Write Ahead Log</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">20.5.1. Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">20.5.2. Checkpoints</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">20.5.3. Archiving</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">20.5.4. Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">20.5.5. Archive Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">20.5.6. Recovery Target</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-replication.html">20.6. Replication</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">20.6.1. Sending Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY">20.6.2. Primary Server</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">20.6.3. Standby Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SUBSCRIBER">20.6.4. Subscribers</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-query.html">20.7. Query Planning</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE">20.7.1. Planner Method Configuration</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">20.7.2. Planner Cost Constants</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO">20.7.3. Genetic Query Optimizer</a></span></dt><dt><span class="sect2"><a href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-OTHER">20.7.4. Other Planner Options</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-logging.html">20.8. Error Reporting and Logging</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHERE">20.8.1. Where to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHEN">20.8.2. When to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-WHAT">20.8.3. What to Log</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG">20.8.4. Using CSV-Format Log Output</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-JSONLOG">20.8.5. Using JSON-Format Log Output</a></span></dt><dt><span class="sect2"><a href="runtime-config-logging.html#id-1.6.7.11.8">20.8.6. Process Title</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-statistics.html">20.9. Run-time Statistics</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-statistics.html#RUNTIME-CONFIG-CUMULATIVE-STATISTICS">20.9.1. Cumulative Query and Index Statistics</a></span></dt><dt><span class="sect2"><a href="runtime-config-statistics.html#RUNTIME-CONFIG-STATISTICS-MONITOR">20.9.2. Statistics Monitoring</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-autovacuum.html">20.10. Automatic Vacuuming</a></span></dt><dt><span class="sect1"><a href="runtime-config-client.html">20.11. Client Connection Defaults</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-STATEMENT">20.11.1. Statement Behavior</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-FORMAT">20.11.2. Locale and Formatting</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD">20.11.3. Shared Library Preloading</a></span></dt><dt><span class="sect2"><a href="runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER">20.11.4. Other Defaults</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-locks.html">20.12. Lock Management</a></span></dt><dt><span class="sect1"><a href="runtime-config-compatible.html">20.13. Version and Platform Compatibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-VERSION">20.13.1. Previous PostgreSQL Versions</a></span></dt><dt><span class="sect2"><a href="runtime-config-compatible.html#RUNTIME-CONFIG-COMPATIBLE-CLIENTS">20.13.2. Platform and Client Compatibility</a></span></dt></dl></dd><dt><span class="sect1"><a href="runtime-config-error-handling.html">20.14. Error Handling</a></span></dt><dt><span class="sect1"><a href="runtime-config-preset.html">20.15. Preset Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-custom.html">20.16. Customized Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-developer.html">20.17. Developer Options</a></span></dt><dt><span class="sect1"><a href="runtime-config-short.html">20.18. Short Options</a></span></dt></dl></div><a id="id-1.6.7.2" class="indexterm"></a><p>
+ There are many configuration parameters that affect the behavior of
+ the database system. In the first section of this chapter we
+ describe how to interact with configuration parameters. The subsequent sections
+ discuss each parameter in detail.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="event-log-registration.html" title="19.12. Registering Event Log on Windows">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="config-setting.html" title="20.1. Setting Parameters">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.1. Setting Parameters</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/runtime.html b/doc/src/sgml/html/runtime.html
new file mode 100644
index 0000000..a892217
--- /dev/null
+++ b/doc/src/sgml/html/runtime.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 19. Server Setup and Operation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-windows-full.html" title="18.1. Building with Visual C++ or the Microsoft Windows SDK" /><link rel="next" href="postgres-user.html" title="19.1. The PostgreSQL User Account" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 19. Server Setup and Operation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-windows-full.html" title="18.1. Building with Visual C++ or the&#10; Microsoft Windows SDK">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Next</a></td></tr></table><hr /></div><div class="chapter" id="RUNTIME"><div class="titlepage"><div><div><h2 class="title">Chapter 19. Server Setup and Operation</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="postgres-user.html">19.1. The <span class="productname">PostgreSQL</span> User Account</a></span></dt><dt><span class="sect1"><a href="creating-cluster.html">19.2. Creating a Database Cluster</a></span></dt><dd><dl><dt><span class="sect2"><a href="creating-cluster.html#CREATING-CLUSTER-MOUNT-POINTS">19.2.1. Use of Secondary File Systems</a></span></dt><dt><span class="sect2"><a href="creating-cluster.html#CREATING-CLUSTER-FILESYSTEM">19.2.2. File Systems</a></span></dt></dl></dd><dt><span class="sect1"><a href="server-start.html">19.3. Starting the Database Server</a></span></dt><dd><dl><dt><span class="sect2"><a href="server-start.html#SERVER-START-FAILURES">19.3.1. Server Start-up Failures</a></span></dt><dt><span class="sect2"><a href="server-start.html#CLIENT-CONNECTION-PROBLEMS">19.3.2. Client Connection Problems</a></span></dt></dl></dd><dt><span class="sect1"><a href="kernel-resources.html">19.4. Managing Kernel Resources</a></span></dt><dd><dl><dt><span class="sect2"><a href="kernel-resources.html#SYSVIPC">19.4.1. Shared Memory and Semaphores</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#SYSTEMD-REMOVEIPC">19.4.2. systemd RemoveIPC</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#id-1.6.6.7.5">19.4.3. Resource Limits</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">19.4.4. Linux Memory Overcommit</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-HUGE-PAGES">19.4.5. Linux Huge Pages</a></span></dt></dl></dd><dt><span class="sect1"><a href="server-shutdown.html">19.5. Shutting Down the Server</a></span></dt><dt><span class="sect1"><a href="upgrading.html">19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</a></span></dt><dd><dl><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PGDUMPALL">19.6.1. Upgrading Data via <span class="application">pg_dumpall</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PG-UPGRADE">19.6.2. Upgrading Data via <span class="application">pg_upgrade</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-REPLICATION">19.6.3. Upgrading Data via Replication</a></span></dt></dl></dd><dt><span class="sect1"><a href="preventing-server-spoofing.html">19.7. Preventing Server Spoofing</a></span></dt><dt><span class="sect1"><a href="encryption-options.html">19.8. Encryption Options</a></span></dt><dt><span class="sect1"><a href="ssl-tcp.html">19.9. Secure TCP/IP Connections with SSL</a></span></dt><dd><dl><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SETUP">19.9.1. Basic Setup</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-OPENSSL-CONFIG">19.9.2. OpenSSL Configuration</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CLIENT-CERTIFICATES">19.9.3. Using Client Certificates</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SERVER-FILES">19.9.4. SSL Server File Usage</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CERTIFICATE-CREATION">19.9.5. Creating Certificates</a></span></dt></dl></dd><dt><span class="sect1"><a href="gssapi-enc.html">19.10. Secure TCP/IP Connections with GSSAPI Encryption</a></span></dt><dd><dl><dt><span class="sect2"><a href="gssapi-enc.html#GSSAPI-SETUP">19.10.1. Basic Setup</a></span></dt></dl></dd><dt><span class="sect1"><a href="ssh-tunnels.html">19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</a></span></dt><dt><span class="sect1"><a href="event-log-registration.html">19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span></a></span></dt></dl></div><p>
+ This chapter discusses how to set up and run the database server,
+ and its interactions with the operating system.
+ </p><p>
+ The directions in this chapter assume that you are working with
+ plain <span class="productname">PostgreSQL</span> without any additional
+ infrastructure, for example a copy that you built from source
+ according to the directions in the preceding chapters.
+ If you are working with a pre-packaged or vendor-supplied
+ version of <span class="productname">PostgreSQL</span>, it is likely that
+ the packager has made special provisions for installing and starting
+ the database server according to your system's conventions.
+ Consult the package-level documentation for details.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-windows-full.html" title="18.1. Building with Visual C++ or the&#10; Microsoft Windows SDK">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres-user.html" title="19.1. The PostgreSQL User Account">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.1. Building with <span class="productname">Visual C++</span> or the
+ <span class="productname">Microsoft Windows SDK</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.1. The <span class="productname">PostgreSQL</span> User Account</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sasl-authentication.html b/doc/src/sgml/html/sasl-authentication.html
new file mode 100644
index 0000000..aa8d232
--- /dev/null
+++ b/doc/src/sgml/html/sasl-authentication.html
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.3. SASL Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-flow.html" title="55.2. Message Flow" /><link rel="next" href="protocol-replication.html" title="55.4. Streaming Replication Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.3. SASL Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-flow.html" title="55.2. Message Flow">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="SASL-AUTHENTICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.3. SASL Authentication</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sasl-authentication.html#SASL-SCRAM-SHA-256">55.3.1. SCRAM-SHA-256 Authentication</a></span></dt></dl></div><p>
+ <em class="firstterm">SASL</em> is a framework for authentication in connection-oriented
+ protocols. At the moment, <span class="productname">PostgreSQL</span> implements two SASL
+ authentication mechanisms, SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. More
+ might be added in the future. The below steps illustrate how SASL
+ authentication is performed in general, while the next subsection gives
+ more details on SCRAM-SHA-256 and SCRAM-SHA-256-PLUS.
+ </p><div class="procedure" id="id-1.10.6.8.3"><p class="title"><strong>SASL Authentication Message Flow</strong></p><ol class="procedure" type="1"><li class="step" id="SASL-AUTH-BEGIN"><p>
+ To begin a SASL authentication exchange, the server sends an
+ AuthenticationSASL message. It includes a list of SASL authentication
+ mechanisms that the server can accept, in the server's preferred order.
+ </p></li><li class="step" id="SASL-AUTH-INITIAL-RESPONSE"><p>
+ The client selects one of the supported mechanisms from the list, and sends
+ a SASLInitialResponse message to the server. The message includes the name
+ of the selected mechanism, and an optional Initial Client Response, if the
+ selected mechanism uses that.
+ </p></li><li class="step" id="SASL-AUTH-CONTINUE"><p>
+ One or more server-challenge and client-response message will follow. Each
+ server-challenge is sent in an AuthenticationSASLContinue message, followed
+ by a response from client in a SASLResponse message. The particulars of
+ the messages are mechanism specific.
+ </p></li><li class="step" id="SASL-AUTH-END"><p>
+ Finally, when the authentication exchange is completed successfully, the
+ server sends an AuthenticationSASLFinal message, followed
+ immediately by an AuthenticationOk message. The AuthenticationSASLFinal
+ contains additional server-to-client data, whose content is particular to the
+ selected authentication mechanism. If the authentication mechanism doesn't
+ use additional data that's sent at completion, the AuthenticationSASLFinal
+ message is not sent.
+ </p></li></ol></div><p>
+ On error, the server can abort the authentication at any stage, and send an
+ ErrorMessage.
+ </p><div class="sect2" id="SASL-SCRAM-SHA-256"><div class="titlepage"><div><div><h3 class="title">55.3.1. SCRAM-SHA-256 Authentication</h3></div></div></div><p>
+ The implemented SASL mechanisms at the moment
+ are <code class="literal">SCRAM-SHA-256</code> and its variant with channel
+ binding <code class="literal">SCRAM-SHA-256-PLUS</code>. They are described in
+ detail in <a class="ulink" href="https://tools.ietf.org/html/rfc7677" target="_top">RFC 7677</a>
+ and <a class="ulink" href="https://tools.ietf.org/html/rfc5802" target="_top">RFC 5802</a>.
+ </p><p>
+ When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name
+ that the client sends in the <code class="structname">client-first-message</code>. The user name
+ that was already sent in the startup message is used instead.
+ <span class="productname">PostgreSQL</span> supports multiple character encodings, while SCRAM
+ dictates UTF-8 to be used for the user name, so it might be impossible to
+ represent the PostgreSQL user name in UTF-8.
+ </p><p>
+ The SCRAM specification dictates that the password is also in UTF-8, and is
+ processed with the <em class="firstterm">SASLprep</em> algorithm.
+ <span class="productname">PostgreSQL</span>, however, does not require UTF-8 to be used for
+ the password. When a user's password is set, it is processed with SASLprep
+ as if it was in UTF-8, regardless of the actual encoding used. However, if
+ it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences
+ that are prohibited by the SASLprep algorithm, the raw password will be used
+ without SASLprep processing, instead of throwing an error. This allows the
+ password to be normalized when it is in UTF-8, but still allows a non-UTF-8
+ password to be used, and doesn't require the system to know which encoding
+ the password is in.
+ </p><p>
+ <em class="firstterm">Channel binding</em> is supported in PostgreSQL builds with
+ SSL support. The SASL mechanism name for SCRAM with channel binding is
+ <code class="literal">SCRAM-SHA-256-PLUS</code>. The channel binding type used by
+ PostgreSQL is <code class="literal">tls-server-end-point</code>.
+ </p><p>
+ In <acronym class="acronym">SCRAM</acronym> without channel binding, the server chooses
+ a random number that is transmitted to the client to be mixed with the
+ user-supplied password in the transmitted password hash. While this
+ prevents the password hash from being successfully retransmitted in
+ a later session, it does not prevent a fake server between the real
+ server and client from passing through the server's random value
+ and successfully authenticating.
+ </p><p>
+ <acronym class="acronym">SCRAM</acronym> with channel binding prevents such
+ man-in-the-middle attacks by mixing the signature of the server's
+ certificate into the transmitted password hash. While a fake server can
+ retransmit the real server's certificate, it doesn't have access to the
+ private key matching that certificate, and therefore cannot prove it is
+ the owner, causing SSL connection failure.
+ </p><div class="procedure" id="id-1.10.6.8.5.8"><p class="title"><strong>Example</strong></p><ol class="procedure" type="1"><li class="step" id="SCRAM-BEGIN"><p>
+ The server sends an AuthenticationSASL message. It includes a list of
+ SASL authentication mechanisms that the server can accept.
+ This will be <code class="literal">SCRAM-SHA-256-PLUS</code>
+ and <code class="literal">SCRAM-SHA-256</code> if the server is built with SSL
+ support, or else just the latter.
+ </p></li><li class="step" id="SCRAM-CLIENT-FIRST"><p>
+ The client responds by sending a SASLInitialResponse message, which
+ indicates the chosen mechanism, <code class="literal">SCRAM-SHA-256</code> or
+ <code class="literal">SCRAM-SHA-256-PLUS</code>. (A client is free to choose either
+ mechanism, but for better security it should choose the channel-binding
+ variant if it can support it.) In the Initial Client response field, the
+ message contains the SCRAM <code class="structname">client-first-message</code>.
+ The <code class="structname">client-first-message</code> also contains the channel
+ binding type chosen by the client.
+ </p></li><li class="step" id="SCRAM-SERVER-FIRST"><p>
+ Server sends an AuthenticationSASLContinue message, with a SCRAM
+ <code class="structname">server-first-message</code> as the content.
+ </p></li><li class="step" id="SCRAM-CLIENT-FINAL"><p>
+ Client sends a SASLResponse message, with SCRAM
+ <code class="structname">client-final-message</code> as the content.
+ </p></li><li class="step" id="SCRAM-SERVER-FINAL"><p>
+ Server sends an AuthenticationSASLFinal message, with the SCRAM
+ <code class="structname">server-final-message</code>, followed immediately by
+ an AuthenticationOk message.
+ </p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-flow.html" title="55.2. Message Flow">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.2. Message Flow </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.4. Streaming Replication Protocol</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/seg.html b/doc/src/sgml/html/seg.html
new file mode 100644
index 0000000..e6e1b4b
--- /dev/null
+++ b/doc/src/sgml/html/seg.html
@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.39. seg</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="postgres-fdw.html" title="F.38. postgres_fdw" /><link rel="next" href="sepgsql.html" title="F.40. sepgsql" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.39. seg</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="postgres-fdw.html" title="F.38. postgres_fdw">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sepgsql.html" title="F.40. sepgsql">Next</a></td></tr></table><hr /></div><div class="sect1" id="SEG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.39. seg</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.5">F.39.1. Rationale</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.6">F.39.2. Syntax</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.7">F.39.3. Precision</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.8">F.39.4. Usage</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.9">F.39.5. Notes</a></span></dt><dt><span class="sect2"><a href="seg.html#id-1.11.7.48.10">F.39.6. Credits</a></span></dt></dl></div><a id="id-1.11.7.48.2" class="indexterm"></a><p>
+ This module implements a data type <code class="type">seg</code> for
+ representing line segments, or floating point intervals.
+ <code class="type">seg</code> can represent uncertainty in the interval endpoints,
+ making it especially useful for representing laboratory measurements.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.48.5"><div class="titlepage"><div><div><h3 class="title">F.39.1. Rationale</h3></div></div></div><p>
+ The geometry of measurements is usually more complex than that of a
+ point in a numeric continuum. A measurement is usually a segment of
+ that continuum with somewhat fuzzy limits. The measurements come out
+ as intervals because of uncertainty and randomness, as well as because
+ the value being measured may naturally be an interval indicating some
+ condition, such as the temperature range of stability of a protein.
+ </p><p>
+ Using just common sense, it appears more convenient to store such data
+ as intervals, rather than pairs of numbers. In practice, it even turns
+ out more efficient in most applications.
+ </p><p>
+ Further along the line of common sense, the fuzziness of the limits
+ suggests that the use of traditional numeric data types leads to a
+ certain loss of information. Consider this: your instrument reads
+ 6.50, and you input this reading into the database. What do you get
+ when you fetch it? Watch:
+
+</p><pre class="screen">
+test=&gt; select 6.50 :: float8 as "pH";
+ pH
+---
+6.5
+(1 row)
+</pre><p>
+
+ In the world of measurements, 6.50 is not the same as 6.5. It may
+ sometimes be critically different. The experimenters usually write
+ down (and publish) the digits they trust. 6.50 is actually a fuzzy
+ interval contained within a bigger and even fuzzier interval, 6.5,
+ with their center points being (probably) the only common feature they
+ share. We definitely do not want such different data items to appear the
+ same.
+ </p><p>
+ Conclusion? It is nice to have a special data type that can record the
+ limits of an interval with arbitrarily variable precision. Variable in
+ the sense that each data element records its own precision.
+ </p><p>
+ Check this out:
+
+</p><pre class="screen">
+test=&gt; select '6.25 .. 6.50'::seg as "pH";
+ pH
+------------
+6.25 .. 6.50
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.48.6"><div class="titlepage"><div><div><h3 class="title">F.39.2. Syntax</h3></div></div></div><p>
+ The external representation of an interval is formed using one or two
+ floating-point numbers joined by the range operator (<code class="literal">..</code>
+ or <code class="literal">...</code>). Alternatively, it can be specified as a
+ center point plus or minus a deviation.
+ Optional certainty indicators (<code class="literal">&lt;</code>,
+ <code class="literal">&gt;</code> or <code class="literal">~</code>) can be stored as well.
+ (Certainty indicators are ignored by all the built-in operators, however.)
+ <a class="xref" href="seg.html#SEG-REPR-TABLE" title="Table F.26. seg External Representations">Table F.26</a> gives an overview of allowed
+ representations; <a class="xref" href="seg.html#SEG-INPUT-EXAMPLES" title="Table F.27. Examples of Valid seg Input">Table F.27</a> shows some
+ examples.
+ </p><p>
+ In <a class="xref" href="seg.html#SEG-REPR-TABLE" title="Table F.26. seg External Representations">Table F.26</a>, <em class="replaceable"><code>x</code></em>, <em class="replaceable"><code>y</code></em>, and
+ <em class="replaceable"><code>delta</code></em> denote
+ floating-point numbers. <em class="replaceable"><code>x</code></em> and <em class="replaceable"><code>y</code></em>, but
+ not <em class="replaceable"><code>delta</code></em>, can be preceded by a certainty indicator.
+ </p><div class="table" id="SEG-REPR-TABLE"><p class="title"><strong>Table F.26. <code class="type">seg</code> External Representations</strong></p><div class="table-contents"><table class="table" summary="seg External Representations" border="1"><colgroup><col /><col /></colgroup><tbody><tr><td><code class="literal"><em class="replaceable"><code>x</code></em></code></td><td>Single value (zero-length interval)
+ </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> .. <em class="replaceable"><code>y</code></em></code></td><td>Interval from <em class="replaceable"><code>x</code></em> to <em class="replaceable"><code>y</code></em>
+ </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> (+-) <em class="replaceable"><code>delta</code></em></code></td><td>Interval from <em class="replaceable"><code>x</code></em> - <em class="replaceable"><code>delta</code></em> to
+ <em class="replaceable"><code>x</code></em> + <em class="replaceable"><code>delta</code></em>
+ </td></tr><tr><td><code class="literal"><em class="replaceable"><code>x</code></em> ..</code></td><td>Open interval with lower bound <em class="replaceable"><code>x</code></em>
+ </td></tr><tr><td><code class="literal">.. <em class="replaceable"><code>x</code></em></code></td><td>Open interval with upper bound <em class="replaceable"><code>x</code></em>
+ </td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="SEG-INPUT-EXAMPLES"><p class="title"><strong>Table F.27. Examples of Valid <code class="type">seg</code> Input</strong></p><div class="table-contents"><table class="table" summary="Examples of Valid seg Input" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><tbody><tr><td><code class="literal">5.0</code></td><td>
+ Creates a zero-length segment (a point, if you will)
+ </td></tr><tr><td><code class="literal">~5.0</code></td><td>
+ Creates a zero-length segment and records
+ <code class="literal">~</code> in the data. <code class="literal">~</code> is ignored
+ by <code class="type">seg</code> operations, but
+ is preserved as a comment.
+ </td></tr><tr><td><code class="literal">&lt;5.0</code></td><td>
+ Creates a point at 5.0. <code class="literal">&lt;</code> is ignored but
+ is preserved as a comment.
+ </td></tr><tr><td><code class="literal">&gt;5.0</code></td><td>
+ Creates a point at 5.0. <code class="literal">&gt;</code> is ignored but
+ is preserved as a comment.
+ </td></tr><tr><td><code class="literal">5(+-)0.3</code></td><td>
+ Creates an interval <code class="literal">4.7 .. 5.3</code>.
+ Note that the <code class="literal">(+-)</code> notation isn't preserved.
+ </td></tr><tr><td><code class="literal">50 .. </code></td><td>Everything that is greater than or equal to 50</td></tr><tr><td><code class="literal">.. 0</code></td><td>Everything that is less than or equal to 0</td></tr><tr><td><code class="literal">1.5e-2 .. 2E-2 </code></td><td>Creates an interval <code class="literal">0.015 .. 0.02</code></td></tr><tr><td><code class="literal">1 ... 2</code></td><td>
+ The same as <code class="literal">1...2</code>, or <code class="literal">1 .. 2</code>,
+ or <code class="literal">1..2</code>
+ (spaces around the range operator are ignored)
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Because the <code class="literal">...</code> operator is widely used in data sources, it is allowed
+ as an alternative spelling of the <code class="literal">..</code> operator. Unfortunately, this
+ creates a parsing ambiguity: it is not clear whether the upper bound
+ in <code class="literal">0...23</code> is meant to be <code class="literal">23</code> or <code class="literal">0.23</code>.
+ This is resolved by requiring at least one digit before the decimal
+ point in all numbers in <code class="type">seg</code> input.
+ </p><p>
+ As a sanity check, <code class="type">seg</code> rejects intervals with the lower bound
+ greater than the upper, for example <code class="literal">5 .. 2</code>.
+ </p></div><div class="sect2" id="id-1.11.7.48.7"><div class="titlepage"><div><div><h3 class="title">F.39.3. Precision</h3></div></div></div><p>
+ <code class="type">seg</code> values are stored internally as pairs of 32-bit floating point
+ numbers. This means that numbers with more than 7 significant digits
+ will be truncated.
+ </p><p>
+ Numbers with 7 or fewer significant digits retain their
+ original precision. That is, if your query returns 0.00, you will be
+ sure that the trailing zeroes are not the artifacts of formatting: they
+ reflect the precision of the original data. The number of leading
+ zeroes does not affect precision: the value 0.0067 is considered to
+ have just 2 significant digits.
+ </p></div><div class="sect2" id="id-1.11.7.48.8"><div class="titlepage"><div><div><h3 class="title">F.39.4. Usage</h3></div></div></div><p>
+ The <code class="filename">seg</code> module includes a GiST index operator class for
+ <code class="type">seg</code> values.
+ The operators supported by the GiST operator class are shown in <a class="xref" href="seg.html#SEG-GIST-OPERATORS" title="Table F.28. Seg GiST Operators">Table F.28</a>.
+ </p><div class="table" id="SEG-GIST-OPERATORS"><p class="title"><strong>Table F.28. Seg GiST Operators</strong></p><div class="table-contents"><table class="table" summary="Seg GiST Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Operator
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&lt;&lt;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first <code class="type">seg</code> entirely to the left of the second?
+ [a, b] &lt;&lt; [c, d] is true if b &lt; c.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&gt;&gt;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first <code class="type">seg</code> entirely to the right of the second?
+ [a, b] &gt;&gt; [c, d] is true if a &gt; d.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&amp;&lt;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first <code class="type">seg</code> not extend to the right of the
+ second?
+ [a, b] &amp;&lt; [c, d] is true if b &lt;= d.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&amp;&gt;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first <code class="type">seg</code> not extend to the left of the
+ second?
+ [a, b] &amp;&gt; [c, d] is true if a &gt;= c.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">=</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Are the two <code class="type">seg</code>s equal?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&amp;&amp;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Do the two <code class="type">seg</code>s overlap?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">@&gt;</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Does the first <code class="type">seg</code> contain the second?
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="type">seg</code> <code class="literal">&lt;@</code> <code class="type">seg</code>
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Is the first <code class="type">seg</code> contained in the second?
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In addition to the above operators, the usual comparison
+ operators shown in <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are
+ available for type <code class="type">seg</code>. These operators
+ first compare (a) to (c),
+ and if these are equal, compare (b) to (d). That results in
+ reasonably good sorting in most cases, which is useful if
+ you want to use ORDER BY with this type.
+ </p></div><div class="sect2" id="id-1.11.7.48.9"><div class="titlepage"><div><div><h3 class="title">F.39.5. Notes</h3></div></div></div><p>
+ For examples of usage, see the regression test <code class="filename">sql/seg.sql</code>.
+ </p><p>
+ The mechanism that converts <code class="literal">(+-)</code> to regular ranges
+ isn't completely accurate in determining the number of significant digits
+ for the boundaries. For example, it adds an extra digit to the lower
+ boundary if the resulting interval includes a power of ten:
+
+</p><pre class="screen">
+postgres=&gt; select '10(+-)1'::seg as seg;
+ seg
+---------
+9.0 .. 11 -- should be: 9 .. 11
+</pre><p>
+ </p><p>
+ The performance of an R-tree index can largely depend on the initial
+ order of input values. It may be very helpful to sort the input table
+ on the <code class="type">seg</code> column; see the script <code class="filename">sort-segments.pl</code>
+ for an example.
+ </p></div><div class="sect2" id="id-1.11.7.48.10"><div class="titlepage"><div><div><h3 class="title">F.39.6. Credits</h3></div></div></div><p>
+ Original author: Gene Selkov, Jr. <code class="email">&lt;<a class="email" href="mailto:selkovjr@mcs.anl.gov">selkovjr@mcs.anl.gov</a>&gt;</code>,
+ Mathematics and Computer Science Division, Argonne National Laboratory.
+ </p><p>
+ My thanks are primarily to Prof. Joe Hellerstein
+ (<a class="ulink" href="https://dsf.berkeley.edu/jmh/" target="_top">https://dsf.berkeley.edu/jmh/</a>) for elucidating the
+ gist of the GiST (<a class="ulink" href="http://gist.cs.berkeley.edu/" target="_top">http://gist.cs.berkeley.edu/</a>). I am
+ also grateful to all Postgres developers, present and past, for enabling
+ myself to create my own world and live undisturbed in it. And I would like
+ to acknowledge my gratitude to Argonne Lab and to the U.S. Department of
+ Energy for the years of faithful support of my database research.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres-fdw.html" title="F.38. postgres_fdw">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sepgsql.html" title="F.40. sepgsql">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.38. postgres_fdw </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.40. sepgsql</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sepgsql.html b/doc/src/sgml/html/sepgsql.html
new file mode 100644
index 0000000..94488fd
--- /dev/null
+++ b/doc/src/sgml/html/sepgsql.html
@@ -0,0 +1,520 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.40. sepgsql</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="seg.html" title="F.39. seg" /><link rel="next" href="contrib-spi.html" title="F.41. spi" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.40. sepgsql</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="seg.html" title="F.39. seg">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-spi.html" title="F.41. spi">Next</a></td></tr></table><hr /></div><div class="sect1" id="SEPGSQL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.40. sepgsql</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-OVERVIEW">F.40.1. Overview</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-INSTALLATION">F.40.2. Installation</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-REGRESSION">F.40.3. Regression Tests</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-PARAMETERS">F.40.4. GUC Parameters</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-FEATURES">F.40.5. Features</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-FUNCTIONS">F.40.6. Sepgsql Functions</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-LIMITATIONS">F.40.7. Limitations</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-RESOURCES">F.40.8. External Resources</a></span></dt><dt><span class="sect2"><a href="sepgsql.html#SEPGSQL-AUTHOR">F.40.9. Author</a></span></dt></dl></div><a id="id-1.11.7.49.2" class="indexterm"></a><p>
+ <code class="filename">sepgsql</code> is a loadable module that supports label-based
+ mandatory access control (MAC) based on <span class="productname">SELinux</span> security
+ policy.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ The current implementation has significant limitations, and does not
+ enforce mandatory access control for all actions. See
+ <a class="xref" href="sepgsql.html#SEPGSQL-LIMITATIONS" title="F.40.7. Limitations">Section F.40.7</a>.
+ </p></div><div class="sect2" id="SEPGSQL-OVERVIEW"><div class="titlepage"><div><div><h3 class="title">F.40.1. Overview</h3></div></div></div><p>
+ This module integrates with <span class="productname">SELinux</span> to provide an
+ additional layer of security checking above and beyond what is normally
+ provided by <span class="productname">PostgreSQL</span>. From the perspective of
+ <span class="productname">SELinux</span>, this module allows
+ <span class="productname">PostgreSQL</span> to function as a user-space object
+ manager. Each table or function access initiated by a DML query will be
+ checked against the system security policy. This check is in addition to
+ the usual SQL permissions checking performed by
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ <span class="productname">SELinux</span> access control decisions are made using
+ security labels, which are represented by strings such as
+ <code class="literal">system_u:object_r:sepgsql_table_t:s0</code>. Each access control
+ decision involves two labels: the label of the subject attempting to
+ perform the action, and the label of the object on which the operation is
+ to be performed. Since these labels can be applied to any sort of object,
+ access control decisions for objects stored within the database can be
+ (and, with this module, are) subjected to the same general criteria used
+ for objects of any other type, such as files. This design is intended to
+ allow a centralized security policy to protect information assets
+ independent of the particulars of how those assets are stored.
+ </p><p>
+ The <a class="link" href="sql-security-label.html" title="SECURITY LABEL"><code class="command">SECURITY LABEL</code></a> statement allows assignment of
+ a security label to a database object.
+ </p></div><div class="sect2" id="SEPGSQL-INSTALLATION"><div class="titlepage"><div><div><h3 class="title">F.40.2. Installation</h3></div></div></div><p>
+ <code class="filename">sepgsql</code> can only be used on <span class="productname">Linux</span>
+ 2.6.28 or higher with <span class="productname">SELinux</span> enabled.
+ It is not available on any other platform. You will also need
+ <span class="productname">libselinux</span> 2.1.10 or higher and
+ <span class="productname">selinux-policy</span> 3.9.13 or higher (although some
+ distributions may backport the necessary rules into older policy
+ versions).
+ </p><p>
+ The <code class="command">sestatus</code> command allows you to check the status of
+ <span class="productname">SELinux</span>. A typical display is:
+</p><pre class="screen">
+$ sestatus
+SELinux status: enabled
+SELinuxfs mount: /selinux
+Current mode: enforcing
+Mode from config file: enforcing
+Policy version: 24
+Policy from config file: targeted
+</pre><p>
+ If <span class="productname">SELinux</span> is disabled or not installed, you must set
+ that product up first before installing this module.
+ </p><p>
+ To build this module, include the option <code class="literal">--with-selinux</code> in
+ your PostgreSQL <code class="literal">configure</code> command. Be sure that the
+ <code class="filename">libselinux-devel</code> RPM is installed at build time.
+ </p><p>
+ To use this module, you must include <code class="literal">sepgsql</code>
+ in the <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a> parameter in
+ <code class="filename">postgresql.conf</code>. The module will not function correctly
+ if loaded in any other manner. Once the module is loaded, you
+ should execute <code class="filename">sepgsql.sql</code> in each database.
+ This will install functions needed for security label management, and
+ assign initial security labels.
+ </p><p>
+ Here is an example showing how to initialize a fresh database cluster
+ with <code class="filename">sepgsql</code> functions and security labels installed.
+ Adjust the paths shown as appropriate for your installation:
+ </p><pre class="screen">
+$ export PGDATA=/path/to/data/directory
+$ initdb
+$ vi $PGDATA/postgresql.conf
+ change
+ #shared_preload_libraries = '' # (change requires restart)
+ to
+ shared_preload_libraries = 'sepgsql' # (change requires restart)
+$ for DBNAME in template0 template1 postgres; do
+ postgres --single -F -c exit_on_error=true $DBNAME \
+ &lt;/usr/local/pgsql/share/contrib/sepgsql.sql &gt;/dev/null
+ done
+</pre><p>
+ Please note that you may see some or all of the following notifications
+ depending on the particular versions you have of
+ <span class="productname">libselinux</span> and <span class="productname">selinux-policy</span>:
+</p><pre class="screen">
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 33 has invalid object type db_blobs
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 36 has invalid object type db_language
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 37 has invalid object type db_language
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 38 has invalid object type db_language
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 39 has invalid object type db_language
+/etc/selinux/targeted/contexts/sepgsql_contexts: line 40 has invalid object type db_language
+</pre><p>
+ These messages are harmless and should be ignored.
+ </p><p>
+ If the installation process completes without error, you can now start the
+ server normally.
+ </p></div><div class="sect2" id="SEPGSQL-REGRESSION"><div class="titlepage"><div><div><h3 class="title">F.40.3. Regression Tests</h3></div></div></div><p>
+ Due to the nature of <span class="productname">SELinux</span>, running the
+ regression tests for <code class="filename">sepgsql</code> requires several extra
+ configuration steps, some of which must be done as root.
+ The regression tests will not be run by an ordinary
+ <code class="literal">make check</code> or <code class="literal">make installcheck</code> command; you must
+ set up the configuration and then invoke the test script manually.
+ The tests must be run in the <code class="filename">contrib/sepgsql</code> directory
+ of a configured PostgreSQL build tree. Although they require a build tree,
+ the tests are designed to be executed against an installed server,
+ that is they are comparable to <code class="literal">make installcheck</code> not
+ <code class="literal">make check</code>.
+ </p><p>
+ First, set up <code class="filename">sepgsql</code> in a working database
+ according to the instructions in <a class="xref" href="sepgsql.html#SEPGSQL-INSTALLATION" title="F.40.2. Installation">Section F.40.2</a>.
+ Note that the current operating system user must be able to connect to the
+ database as superuser without password authentication.
+ </p><p>
+ Second, build and install the policy package for the regression test.
+ The <code class="filename">sepgsql-regtest</code> policy is a special purpose policy package
+ which provides a set of rules to be allowed during the regression tests.
+ It should be built from the policy source file
+ <code class="filename">sepgsql-regtest.te</code>, which is done using
+ <code class="command">make</code> with a Makefile supplied by SELinux.
+ You will need to locate the appropriate
+ Makefile on your system; the path shown below is only an example.
+ (This Makefile is usually supplied by the
+ <code class="filename">selinux-policy-devel</code> or
+ <code class="filename">selinux-policy</code> RPM.)
+ Once built, install this policy package using the
+ <code class="command">semodule</code> command, which loads supplied policy packages
+ into the kernel. If the package is correctly installed,
+ <code class="literal"><code class="command">semodule</code> -l</code> should list <code class="literal">sepgsql-regtest</code> as an
+ available policy package:
+ </p><pre class="screen">
+$ cd .../contrib/sepgsql
+$ make -f /usr/share/selinux/devel/Makefile
+$ sudo semodule -u sepgsql-regtest.pp
+$ sudo semodule -l | grep sepgsql
+sepgsql-regtest 1.07
+</pre><p>
+ Third, turn on <code class="literal">sepgsql_regression_test_mode</code>.
+ For security reasons, the rules in <code class="filename">sepgsql-regtest</code>
+ are not enabled by default;
+ the <code class="literal">sepgsql_regression_test_mode</code> parameter enables
+ the rules needed to launch the regression tests.
+ It can be turned on using the <code class="command">setsebool</code> command:
+ </p><pre class="screen">
+$ sudo setsebool sepgsql_regression_test_mode on
+$ getsebool sepgsql_regression_test_mode
+sepgsql_regression_test_mode --&gt; on
+</pre><p>
+ Fourth, verify your shell is operating in the <code class="literal">unconfined_t</code>
+ domain:
+ </p><pre class="screen">
+$ id -Z
+unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
+</pre><p>
+ See <a class="xref" href="sepgsql.html#SEPGSQL-RESOURCES" title="F.40.8. External Resources">Section F.40.8</a> for details on adjusting your
+ working domain, if necessary.
+ </p><p>
+ Finally, run the regression test script:
+ </p><pre class="screen">
+$ ./test_sepgsql
+</pre><p>
+ This script will attempt to verify that you have done all the configuration
+ steps correctly, and then it will run the regression tests for the
+ <code class="filename">sepgsql</code> module.
+ </p><p>
+ After completing the tests, it's recommended you disable
+ the <code class="literal">sepgsql_regression_test_mode</code> parameter:
+ </p><pre class="screen">
+$ sudo setsebool sepgsql_regression_test_mode off
+</pre><p>
+ You might prefer to remove the <code class="filename">sepgsql-regtest</code> policy
+ entirely:
+ </p><pre class="screen">
+$ sudo semodule -r sepgsql-regtest
+</pre></div><div class="sect2" id="SEPGSQL-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">F.40.4. GUC Parameters</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-SEPGSQL-PERMISSIVE"><span class="term">
+ <code class="varname">sepgsql.permissive</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.49.8.2.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter enables <code class="filename">sepgsql</code> to function
+ in permissive mode, regardless of the system setting.
+ The default is off.
+ This parameter can only be set in the <code class="filename">postgresql.conf</code>
+ file or on the server command line.
+ </p><p>
+ When this parameter is on, <code class="filename">sepgsql</code> functions
+ in permissive mode, even if SELinux in general is working in enforcing
+ mode. This parameter is primarily useful for testing purposes.
+ </p></dd><dt id="GUC-SEPGSQL-DEBUG-AUDIT"><span class="term">
+ <code class="varname">sepgsql.debug_audit</code> (<code class="type">boolean</code>)
+ <a id="id-1.11.7.49.8.2.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This parameter enables the printing of audit messages regardless of
+ the system policy settings.
+ The default is off, which means that messages will be printed according
+ to the system settings.
+ </p><p>
+ The security policy of <span class="productname">SELinux</span> also has rules to
+ control whether or not particular accesses are logged.
+ By default, access violations are logged, but allowed
+ accesses are not.
+ </p><p>
+ This parameter forces all possible logging to be turned on, regardless
+ of the system policy.
+ </p></dd></dl></div></div><div class="sect2" id="SEPGSQL-FEATURES"><div class="titlepage"><div><div><h3 class="title">F.40.5. Features</h3></div></div></div><div class="sect3" id="id-1.11.7.49.9.2"><div class="titlepage"><div><div><h4 class="title">F.40.5.1. Controlled Object Classes</h4></div></div></div><p>
+ The security model of <span class="productname">SELinux</span> describes all the access
+ control rules as relationships between a subject entity (typically,
+ a client of the database) and an object entity (such as a database
+ object), each of which is
+ identified by a security label. If access to an unlabeled object is
+ attempted, the object is treated as if it were assigned the label
+ <code class="literal">unlabeled_t</code>.
+ </p><p>
+ Currently, <code class="filename">sepgsql</code> allows security labels to be
+ assigned to schemas, tables, columns, sequences, views, and functions.
+ When <code class="filename">sepgsql</code> is in use, security labels are
+ automatically assigned to supported database objects at creation time.
+ This label is called a default security label, and is decided according
+ to the system security policy, which takes as input the creator's label,
+ the label assigned to the new object's parent object and optionally name
+ of the constructed object.
+ </p><p>
+ A new database object basically inherits the security label of the parent
+ object, except when the security policy has special rules known as
+ type-transition rules, in which case a different label may be applied.
+ For schemas, the parent object is the current database; for tables,
+ sequences, views, and functions, it is the containing schema; for columns,
+ it is the containing table.
+ </p></div><div class="sect3" id="id-1.11.7.49.9.3"><div class="titlepage"><div><div><h4 class="title">F.40.5.2. DML Permissions</h4></div></div></div><p>
+ For tables, <code class="literal">db_table:select</code>, <code class="literal">db_table:insert</code>,
+ <code class="literal">db_table:update</code> or <code class="literal">db_table:delete</code> are
+ checked for all the referenced target tables depending on the kind of
+ statement; in addition, <code class="literal">db_table:select</code> is also checked for
+ all the tables that contain columns referenced in the
+ <code class="literal">WHERE</code> or <code class="literal">RETURNING</code> clause, as a data source
+ for <code class="literal">UPDATE</code>, and so on.
+ </p><p>
+ Column-level permissions will also be checked for each referenced column.
+ <code class="literal">db_column:select</code> is checked on not only the columns being
+ read using <code class="literal">SELECT</code>, but those being referenced in other DML
+ statements; <code class="literal">db_column:update</code> or <code class="literal">db_column:insert</code>
+ will also be checked for columns being modified by <code class="literal">UPDATE</code> or
+ <code class="literal">INSERT</code>.
+ </p><p>
+ For example, consider:
+</p><pre class="synopsis">
+UPDATE t1 SET x = 2, y = func1(y) WHERE z = 100;
+</pre><p>
+
+ Here, <code class="literal">db_column:update</code> will be checked for
+ <code class="literal">t1.x</code>, since it is being updated,
+ <code class="literal">db_column:{select update}</code> will be checked for
+ <code class="literal">t1.y</code>, since it is both updated and referenced, and
+ <code class="literal">db_column:select</code> will be checked for <code class="literal">t1.z</code>, since
+ it is only referenced.
+ <code class="literal">db_table:{select update}</code> will also be checked
+ at the table level.
+ </p><p>
+ For sequences, <code class="literal">db_sequence:get_value</code> is checked when we
+ reference a sequence object using <code class="literal">SELECT</code>; however, note that we
+ do not currently check permissions on execution of corresponding functions
+ such as <code class="literal">lastval()</code>.
+ </p><p>
+ For views, <code class="literal">db_view:expand</code> will be checked, then any other
+ required permissions will be checked on the objects being
+ expanded from the view, individually.
+ </p><p>
+ For functions, <code class="literal">db_procedure:{execute}</code> will be checked when
+ user tries to execute a function as a part of query, or using fast-path
+ invocation. If this function is a trusted procedure, it also checks
+ <code class="literal">db_procedure:{entrypoint}</code> permission to check whether it
+ can perform as entry point of trusted procedure.
+ </p><p>
+ In order to access any schema object, <code class="literal">db_schema:search</code>
+ permission is required on the containing schema. When an object is
+ referenced without schema qualification, schemas on which this
+ permission is not present will not be searched (just as if the user did
+ not have <code class="literal">USAGE</code> privilege on the schema). If an explicit schema
+ qualification is present, an error will occur if the user does not have
+ the requisite permission on the named schema.
+ </p><p>
+ The client must be allowed to access all referenced tables and
+ columns, even if they originated from views which were then expanded,
+ so that we apply consistent access control rules independent of the manner
+ in which the table contents are referenced.
+ </p><p>
+ The default database privilege system allows database superusers to
+ modify system catalogs using DML commands, and reference or modify
+ toast tables. These operations are prohibited when
+ <code class="filename">sepgsql</code> is enabled.
+ </p></div><div class="sect3" id="id-1.11.7.49.9.4"><div class="titlepage"><div><div><h4 class="title">F.40.5.3. DDL Permissions</h4></div></div></div><p>
+ <span class="productname">SELinux</span> defines several permissions to control common
+ operations for each object type; such as creation, alter, drop and
+ relabel of security label. In addition, several object types have
+ special permissions to control their characteristic operations; such as
+ addition or deletion of name entries within a particular schema.
+ </p><p>
+ Creating a new database object requires <code class="literal">create</code> permission.
+ <span class="productname">SELinux</span> will grant or deny this permission based on the
+ client's security label and the proposed security label for the new
+ object. In some cases, additional privileges are required:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a> additionally requires
+ <code class="literal">getattr</code> permission for the source or template database.
+ </p></li><li class="listitem"><p>
+ Creating a schema object additionally requires <code class="literal">add_name</code>
+ permission on the parent schema.
+ </p></li><li class="listitem"><p>
+ Creating a table additionally requires permission to create each
+ individual table column, just as if each table column were a
+ separate top-level object.
+ </p></li><li class="listitem"><p>
+ Creating a function marked as <code class="literal">LEAKPROOF</code> additionally
+ requires <code class="literal">install</code> permission. (This permission is also
+ checked when <code class="literal">LEAKPROOF</code> is set for an existing function.)
+ </p></li></ul></div><p>
+ When <code class="literal">DROP</code> command is executed, <code class="literal">drop</code> will be
+ checked on the object being removed. Permissions will be also checked for
+ objects dropped indirectly via <code class="literal">CASCADE</code>. Deletion of objects
+ contained within a particular schema (tables, views, sequences and
+ procedures) additionally requires <code class="literal">remove_name</code> on the schema.
+ </p><p>
+ When <code class="literal">ALTER</code> command is executed, <code class="literal">setattr</code> will be
+ checked on the object being modified for each object types, except for
+ subsidiary objects such as the indexes or triggers of a table, where
+ permissions are instead checked on the parent object. In some cases,
+ additional permissions are required:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Moving an object to a new schema additionally requires
+ <code class="literal">remove_name</code> permission on the old schema and
+ <code class="literal">add_name</code> permission on the new one.
+ </p></li><li class="listitem"><p>
+ Setting the <code class="literal">LEAKPROOF</code> attribute on a function requires
+ <code class="literal">install</code> permission.
+ </p></li><li class="listitem"><p>
+ Using <a class="link" href="sql-security-label.html" title="SECURITY LABEL"><code class="command">SECURITY LABEL</code></a> on an object additionally
+ requires <code class="literal">relabelfrom</code> permission for the object in
+ conjunction with its old security label and <code class="literal">relabelto</code>
+ permission for the object in conjunction with its new security label.
+ (In cases where multiple label providers are installed and the user
+ tries to set a security label, but it is not managed by
+ <span class="productname">SELinux</span>, only <code class="literal">setattr</code> should be checked here.
+ This is currently not done due to implementation restrictions.)
+ </p></li></ul></div></div><div class="sect3" id="id-1.11.7.49.9.5"><div class="titlepage"><div><div><h4 class="title">F.40.5.4. Trusted Procedures</h4></div></div></div><p>
+ Trusted procedures are similar to security definer functions or setuid
+ commands. <span class="productname">SELinux</span> provides a feature to allow trusted
+ code to run using a security label different from that of the client,
+ generally for the purpose of providing highly controlled access to
+ sensitive data (e.g., rows might be omitted, or the precision of stored
+ values might be reduced). Whether or not a function acts as a trusted
+ procedure is controlled by its security label and the operating system
+ security policy. For example:
+ </p><pre class="screen">
+postgres=# CREATE TABLE customer (
+ cid int primary key,
+ cname text,
+ credit text
+ );
+CREATE TABLE
+postgres=# SECURITY LABEL ON COLUMN customer.credit
+ IS 'system_u:object_r:sepgsql_secret_table_t:s0';
+SECURITY LABEL
+postgres=# CREATE FUNCTION show_credit(int) RETURNS text
+ AS 'SELECT regexp_replace(credit, ''-[0-9]+$'', ''-xxxx'', ''g'')
+ FROM customer WHERE cid = $1'
+ LANGUAGE sql;
+CREATE FUNCTION
+postgres=# SECURITY LABEL ON FUNCTION show_credit(int)
+ IS 'system_u:object_r:sepgsql_trusted_proc_exec_t:s0';
+SECURITY LABEL
+</pre><p>
+ The above operations should be performed by an administrative user.
+ </p><pre class="screen">
+postgres=# SELECT * FROM customer;
+ERROR: SELinux: security policy violation
+postgres=# SELECT cid, cname, show_credit(cid) FROM customer;
+ cid | cname | show_credit
+-----+--------+---------------------
+ 1 | taro | 1111-2222-3333-xxxx
+ 2 | hanako | 5555-6666-7777-xxxx
+(2 rows)
+</pre><p>
+ In this case, a regular user cannot reference <code class="literal">customer.credit</code>
+ directly, but a trusted procedure <code class="literal">show_credit</code> allows the user
+ to print the credit card numbers of customers with some of the digits
+ masked out.
+ </p></div><div class="sect3" id="id-1.11.7.49.9.6"><div class="titlepage"><div><div><h4 class="title">F.40.5.5. Dynamic Domain Transitions</h4></div></div></div><p>
+ It is possible to use SELinux's dynamic domain transition feature
+ to switch the security label of the client process, the client domain,
+ to a new context, if that is allowed by the security policy.
+ The client domain needs the <code class="literal">setcurrent</code> permission and also
+ <code class="literal">dyntransition</code> from the old to the new domain.
+ </p><p>
+ Dynamic domain transitions should be considered carefully, because they
+ allow users to switch their label, and therefore their privileges,
+ at their option, rather than (as in the case of a trusted procedure)
+ as mandated by the system.
+ Thus, the <code class="literal">dyntransition</code> permission is only considered
+ safe when used to switch to a domain with a smaller set of privileges than
+ the original one. For example:
+ </p><pre class="screen">
+regression=# select sepgsql_getcon();
+ sepgsql_getcon
+-------------------------------------------------------
+ unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
+(1 row)
+
+regression=# SELECT sepgsql_setcon('unconfined_u:unconfined_r:unconfined_t:s0-s0:c1.c4');
+ sepgsql_setcon
+----------------
+ t
+(1 row)
+
+regression=# SELECT sepgsql_setcon('unconfined_u:unconfined_r:unconfined_t:s0-s0:c1.c1023');
+ERROR: SELinux: security policy violation
+</pre><p>
+ In this example above we were allowed to switch from the larger MCS
+ range <code class="literal">c1.c1023</code> to the smaller range <code class="literal">c1.c4</code>, but
+ switching back was denied.
+ </p><p>
+ A combination of dynamic domain transition and trusted procedure
+ enables an interesting use case that fits the typical process life-cycle
+ of connection pooling software.
+ Even if your connection pooling software is not allowed to run most
+ of SQL commands, you can allow it to switch the security label
+ of the client using the <code class="literal">sepgsql_setcon()</code> function
+ from within a trusted procedure; that should take some
+ credential to authorize the request to switch the client label.
+ After that, this session will have the privileges of the target user,
+ rather than the connection pooler.
+ The connection pooler can later revert the security label change by
+ again using <code class="literal">sepgsql_setcon()</code> with
+ <code class="literal">NULL</code> argument, again invoked from within a trusted
+ procedure with appropriate permissions checks.
+ The point here is that only the trusted procedure actually has permission
+ to change the effective security label, and only does so when given proper
+ credentials. Of course, for secure operation, the credential store
+ (table, procedure definition, or whatever) must be protected from
+ unauthorized access.
+ </p></div><div class="sect3" id="id-1.11.7.49.9.7"><div class="titlepage"><div><div><h4 class="title">F.40.5.6. Miscellaneous</h4></div></div></div><p>
+ We reject the <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> command across the board, because
+ any module loaded could easily circumvent security policy enforcement.
+ </p></div></div><div class="sect2" id="SEPGSQL-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">F.40.6. Sepgsql Functions</h3></div></div></div><p>
+ <a class="xref" href="sepgsql.html#SEPGSQL-FUNCTIONS-TABLE" title="Table F.29. Sepgsql Functions">Table F.29</a> shows the available functions.
+ </p><div class="table" id="SEPGSQL-FUNCTIONS-TABLE"><p class="title"><strong>Table F.29. Sepgsql Functions</strong></p><div class="table-contents"><table class="table" summary="Sepgsql Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sepgsql_getcon</code> ()
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Returns the client domain, the current security label of the client.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sepgsql_setcon</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Switches the client domain of the current session to the new domain,
+ if allowed by the security policy.
+ It also accepts <code class="literal">NULL</code> input as a request to transition
+ to the client's original domain.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sepgsql_mcstrans_in</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Translates the given qualified MLS/MCS range into raw format if
+ the mcstrans daemon is running.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sepgsql_mcstrans_out</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Translates the given raw MLS/MCS range into qualified format if
+ the mcstrans daemon is running.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">sepgsql_restorecon</code> ( <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Sets up initial security labels for all objects within the
+ current database. The argument may be <code class="literal">NULL</code>, or the
+ name of a specfile to be used as alternative of the system default.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="SEPGSQL-LIMITATIONS"><div class="titlepage"><div><div><h3 class="title">F.40.7. Limitations</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Data Definition Language (DDL) Permissions</span></dt><dd><p>
+ Due to implementation restrictions, some DDL operations do not
+ check permissions.
+ </p></dd><dt><span class="term">Data Control Language (DCL) Permissions</span></dt><dd><p>
+ Due to implementation restrictions, DCL operations do not check
+ permissions.
+ </p></dd><dt><span class="term">Row-level access control</span></dt><dd><p>
+ <span class="productname">PostgreSQL</span> supports row-level access, but
+ <code class="filename">sepgsql</code> does not.
+ </p></dd><dt><span class="term">Covert channels</span></dt><dd><p>
+ <code class="filename">sepgsql</code> does not try to hide the existence of
+ a certain object, even if the user is not allowed to reference it.
+ For example, we can infer the existence of an invisible object as
+ a result of primary key conflicts, foreign key violations, and so on,
+ even if we cannot obtain the contents of the object. The existence
+ of a top secret table cannot be hidden; we only hope to conceal its
+ contents.
+ </p></dd></dl></div></div><div class="sect2" id="SEPGSQL-RESOURCES"><div class="titlepage"><div><div><h3 class="title">F.40.8. External Resources</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="ulink" href="https://wiki.postgresql.org/wiki/SEPostgreSQL" target="_top">SE-PostgreSQL Introduction</a></span></dt><dd><p>
+ This wiki page provides a brief overview, security design, architecture,
+ administration and upcoming features.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index" target="_top">SELinux User's and Administrator's Guide</a></span></dt><dd><p>
+ This document provides a wide spectrum of knowledge to administer
+ <span class="productname">SELinux</span> on your systems.
+ It focuses primarily on Red Hat operating systems, but is not limited to them.
+ </p></dd><dt><span class="term"><a class="ulink" href="https://fedoraproject.org/wiki/SELinux_FAQ" target="_top">Fedora SELinux FAQ</a></span></dt><dd><p>
+ This document answers frequently asked questions about
+ <span class="productname">SELinux</span>.
+ It focuses primarily on Fedora, but is not limited to Fedora.
+ </p></dd></dl></div></div><div class="sect2" id="SEPGSQL-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.40.9. Author</h3></div></div></div><p>
+ KaiGai Kohei <code class="email">&lt;<a class="email" href="mailto:kaigai@ak.jp.nec.com">kaigai@ak.jp.nec.com</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="seg.html" title="F.39. seg">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-spi.html" title="F.41. spi">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.39. seg </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.41. spi</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/server-programming.html b/doc/src/sgml/html/server-programming.html
new file mode 100644
index 0000000..5c180b8
--- /dev/null
+++ b/doc/src/sgml/html/server-programming.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part V. Server Programming</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="infoschema-views.html" title="37.66. views" /><link rel="next" href="extend.html" title="Chapter 38. Extending SQL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part V. Server Programming</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="infoschema-views.html" title="37.66. views">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="extend.html" title="Chapter 38. Extending SQL">Next</a></td></tr></table><hr /></div><div class="part" id="SERVER-PROGRAMMING"><div class="titlepage"><div><div><h1 class="title">Part V. Server Programming</h1></div></div></div><div class="partintro" id="id-1.8.2"><div></div><p>
+ This part is about extending the server functionality with
+ user-defined functions, data types, triggers, etc. These are
+ advanced topics which should probably be approached only after all
+ the other user documentation about <span class="productname">PostgreSQL</span> has
+ been understood. Later chapters in this part describe the server-side
+ programming languages available in the
+ <span class="productname">PostgreSQL</span> distribution as well as
+ general issues concerning server-side programming languages. It
+ is essential to read at least the earlier sections of <a class="xref" href="extend.html" title="Chapter 38. Extending SQL">Chapter 38</a> (covering functions) before diving into the
+ material about server-side programming languages.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="extend.html">38. Extending <acronym class="acronym">SQL</acronym></a></span></dt><dd><dl><dt><span class="sect1"><a href="extend-how.html">38.1. How Extensibility Works</a></span></dt><dt><span class="sect1"><a href="extend-type-system.html">38.2. The <span class="productname">PostgreSQL</span> Type System</a></span></dt><dt><span class="sect1"><a href="xfunc.html">38.3. User-Defined Functions</a></span></dt><dt><span class="sect1"><a href="xproc.html">38.4. User-Defined Procedures</a></span></dt><dt><span class="sect1"><a href="xfunc-sql.html">38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-overload.html">38.6. Function Overloading</a></span></dt><dt><span class="sect1"><a href="xfunc-volatility.html">38.7. Function Volatility Categories</a></span></dt><dt><span class="sect1"><a href="xfunc-pl.html">38.8. Procedural Language Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-internal.html">38.9. Internal Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-c.html">38.10. C-Language Functions</a></span></dt><dt><span class="sect1"><a href="xfunc-optimization.html">38.11. Function Optimization Information</a></span></dt><dt><span class="sect1"><a href="xaggr.html">38.12. User-Defined Aggregates</a></span></dt><dt><span class="sect1"><a href="xtypes.html">38.13. User-Defined Types</a></span></dt><dt><span class="sect1"><a href="xoper.html">38.14. User-Defined Operators</a></span></dt><dt><span class="sect1"><a href="xoper-optimization.html">38.15. Operator Optimization Information</a></span></dt><dt><span class="sect1"><a href="xindex.html">38.16. Interfacing Extensions to Indexes</a></span></dt><dt><span class="sect1"><a href="extend-extensions.html">38.17. Packaging Related Objects into an Extension</a></span></dt><dt><span class="sect1"><a href="extend-pgxs.html">38.18. Extension Building Infrastructure</a></span></dt></dl></dd><dt><span class="chapter"><a href="triggers.html">39. Triggers</a></span></dt><dd><dl><dt><span class="sect1"><a href="trigger-definition.html">39.1. Overview of Trigger Behavior</a></span></dt><dt><span class="sect1"><a href="trigger-datachanges.html">39.2. Visibility of Data Changes</a></span></dt><dt><span class="sect1"><a href="trigger-interface.html">39.3. Writing Trigger Functions in C</a></span></dt><dt><span class="sect1"><a href="trigger-example.html">39.4. A Complete Trigger Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="event-triggers.html">40. Event Triggers</a></span></dt><dd><dl><dt><span class="sect1"><a href="event-trigger-definition.html">40.1. Overview of Event Trigger Behavior</a></span></dt><dt><span class="sect1"><a href="event-trigger-matrix.html">40.2. Event Trigger Firing Matrix</a></span></dt><dt><span class="sect1"><a href="event-trigger-interface.html">40.3. Writing Event Trigger Functions in C</a></span></dt><dt><span class="sect1"><a href="event-trigger-example.html">40.4. A Complete Event Trigger Example</a></span></dt><dt><span class="sect1"><a href="event-trigger-table-rewrite-example.html">40.5. A Table Rewrite Event Trigger Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="rules.html">41. The Rule System</a></span></dt><dd><dl><dt><span class="sect1"><a href="querytree.html">41.1. The Query Tree</a></span></dt><dt><span class="sect1"><a href="rules-views.html">41.2. Views and the Rule System</a></span></dt><dt><span class="sect1"><a href="rules-materializedviews.html">41.3. Materialized Views</a></span></dt><dt><span class="sect1"><a href="rules-update.html">41.4. Rules on <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and <code class="command">DELETE</code></a></span></dt><dt><span class="sect1"><a href="rules-privileges.html">41.5. Rules and Privileges</a></span></dt><dt><span class="sect1"><a href="rules-status.html">41.6. Rules and Command Status</a></span></dt><dt><span class="sect1"><a href="rules-triggers.html">41.7. Rules Versus Triggers</a></span></dt></dl></dd><dt><span class="chapter"><a href="xplang.html">42. Procedural Languages</a></span></dt><dd><dl><dt><span class="sect1"><a href="xplang-install.html">42.1. Installing Procedural Languages</a></span></dt></dl></dd><dt><span class="chapter"><a href="plpgsql.html">43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</a></span></dt><dd><dl><dt><span class="sect1"><a href="plpgsql-overview.html">43.1. Overview</a></span></dt><dt><span class="sect1"><a href="plpgsql-structure.html">43.2. Structure of <span class="application">PL/pgSQL</span></a></span></dt><dt><span class="sect1"><a href="plpgsql-declarations.html">43.3. Declarations</a></span></dt><dt><span class="sect1"><a href="plpgsql-expressions.html">43.4. Expressions</a></span></dt><dt><span class="sect1"><a href="plpgsql-statements.html">43.5. Basic Statements</a></span></dt><dt><span class="sect1"><a href="plpgsql-control-structures.html">43.6. Control Structures</a></span></dt><dt><span class="sect1"><a href="plpgsql-cursors.html">43.7. Cursors</a></span></dt><dt><span class="sect1"><a href="plpgsql-transactions.html">43.8. Transaction Management</a></span></dt><dt><span class="sect1"><a href="plpgsql-errors-and-messages.html">43.9. Errors and Messages</a></span></dt><dt><span class="sect1"><a href="plpgsql-trigger.html">43.10. Trigger Functions</a></span></dt><dt><span class="sect1"><a href="plpgsql-implementation.html">43.11. <span class="application">PL/pgSQL</span> under the Hood</a></span></dt><dt><span class="sect1"><a href="plpgsql-development-tips.html">43.12. Tips for Developing in <span class="application">PL/pgSQL</span></a></span></dt><dt><span class="sect1"><a href="plpgsql-porting.html">43.13. Porting from <span class="productname">Oracle</span> PL/SQL</a></span></dt></dl></dd><dt><span class="chapter"><a href="pltcl.html">44. PL/Tcl — Tcl Procedural Language</a></span></dt><dd><dl><dt><span class="sect1"><a href="pltcl-overview.html">44.1. Overview</a></span></dt><dt><span class="sect1"><a href="pltcl-functions.html">44.2. PL/Tcl Functions and Arguments</a></span></dt><dt><span class="sect1"><a href="pltcl-data.html">44.3. Data Values in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-global.html">44.4. Global Data in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-dbaccess.html">44.5. Database Access from PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-trigger.html">44.6. Trigger Functions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-event-trigger.html">44.7. Event Trigger Functions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-error-handling.html">44.8. Error Handling in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-subtransactions.html">44.9. Explicit Subtransactions in PL/Tcl</a></span></dt><dt><span class="sect1"><a href="pltcl-transactions.html">44.10. Transaction Management</a></span></dt><dt><span class="sect1"><a href="pltcl-config.html">44.11. PL/Tcl Configuration</a></span></dt><dt><span class="sect1"><a href="pltcl-procnames.html">44.12. Tcl Procedure Names</a></span></dt></dl></dd><dt><span class="chapter"><a href="plperl.html">45. PL/Perl — Perl Procedural Language</a></span></dt><dd><dl><dt><span class="sect1"><a href="plperl-funcs.html">45.1. PL/Perl Functions and Arguments</a></span></dt><dt><span class="sect1"><a href="plperl-data.html">45.2. Data Values in PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-builtins.html">45.3. Built-in Functions</a></span></dt><dt><span class="sect1"><a href="plperl-global.html">45.4. Global Values in PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-trusted.html">45.5. Trusted and Untrusted PL/Perl</a></span></dt><dt><span class="sect1"><a href="plperl-triggers.html">45.6. PL/Perl Triggers</a></span></dt><dt><span class="sect1"><a href="plperl-event-triggers.html">45.7. PL/Perl Event Triggers</a></span></dt><dt><span class="sect1"><a href="plperl-under-the-hood.html">45.8. PL/Perl Under the Hood</a></span></dt></dl></dd><dt><span class="chapter"><a href="plpython.html">46. PL/Python — Python Procedural Language</a></span></dt><dd><dl><dt><span class="sect1"><a href="plpython-funcs.html">46.1. PL/Python Functions</a></span></dt><dt><span class="sect1"><a href="plpython-data.html">46.2. Data Values</a></span></dt><dt><span class="sect1"><a href="plpython-sharing.html">46.3. Sharing Data</a></span></dt><dt><span class="sect1"><a href="plpython-do.html">46.4. Anonymous Code Blocks</a></span></dt><dt><span class="sect1"><a href="plpython-trigger.html">46.5. Trigger Functions</a></span></dt><dt><span class="sect1"><a href="plpython-database.html">46.6. Database Access</a></span></dt><dt><span class="sect1"><a href="plpython-subtransaction.html">46.7. Explicit Subtransactions</a></span></dt><dt><span class="sect1"><a href="plpython-transactions.html">46.8. Transaction Management</a></span></dt><dt><span class="sect1"><a href="plpython-util.html">46.9. Utility Functions</a></span></dt><dt><span class="sect1"><a href="plpython-python23.html">46.10. Python 2 vs. Python 3</a></span></dt><dt><span class="sect1"><a href="plpython-envar.html">46.11. Environment Variables</a></span></dt></dl></dd><dt><span class="chapter"><a href="spi.html">47. Server Programming Interface</a></span></dt><dd><dl><dt><span class="sect1"><a href="spi-interface.html">47.1. Interface Functions</a></span></dt><dt><span class="sect1"><a href="spi-interface-support.html">47.2. Interface Support Functions</a></span></dt><dt><span class="sect1"><a href="spi-memory.html">47.3. Memory Management</a></span></dt><dt><span class="sect1"><a href="spi-transaction.html">47.4. Transaction Management</a></span></dt><dt><span class="sect1"><a href="spi-visibility.html">47.5. Visibility of Data Changes</a></span></dt><dt><span class="sect1"><a href="spi-examples.html">47.6. Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="bgworker.html">48. Background Worker Processes</a></span></dt><dt><span class="chapter"><a href="logicaldecoding.html">49. Logical Decoding</a></span></dt><dd><dl><dt><span class="sect1"><a href="logicaldecoding-example.html">49.1. Logical Decoding Examples</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-explanation.html">49.2. Logical Decoding Concepts</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-walsender.html">49.3. Streaming Replication Protocol Interface</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-sql.html">49.4. Logical Decoding <acronym class="acronym">SQL</acronym> Interface</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-catalogs.html">49.5. System Catalogs Related to Logical Decoding</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-output-plugin.html">49.6. Logical Decoding Output Plugins</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-writer.html">49.7. Logical Decoding Output Writers</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-synchronous.html">49.8. Synchronous Replication Support for Logical Decoding</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-streaming.html">49.9. Streaming of Large Transactions for Logical Decoding</a></span></dt><dt><span class="sect1"><a href="logicaldecoding-two-phase-commits.html">49.10. Two-phase Commit Support for Logical Decoding</a></span></dt></dl></dd><dt><span class="chapter"><a href="replication-origins.html">50. Replication Progress Tracking</a></span></dt><dt><span class="chapter"><a href="archive-modules.html">51. Archive Modules</a></span></dt><dd><dl><dt><span class="sect1"><a href="archive-module-init.html">51.1. Initialization Functions</a></span></dt><dt><span class="sect1"><a href="archive-module-callbacks.html">51.2. Archive Module Callbacks</a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="infoschema-views.html" title="37.66. views">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extend.html" title="Chapter 38. Extending SQL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.66. <code class="literal">views</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Extending <acronym class="acronym">SQL</acronym></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/server-shutdown.html b/doc/src/sgml/html/server-shutdown.html
new file mode 100644
index 0000000..61b0827
--- /dev/null
+++ b/doc/src/sgml/html/server-shutdown.html
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.5. Shutting Down the Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="kernel-resources.html" title="19.4. Managing Kernel Resources" /><link rel="next" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.5. Shutting Down the Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Next</a></td></tr></table><hr /></div><div class="sect1" id="SERVER-SHUTDOWN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.5. Shutting Down the Server</h2></div></div></div><a id="id-1.6.6.8.2" class="indexterm"></a><p>
+ There are several ways to shut down the database server.
+ Under the hood, they all reduce to sending a signal to the supervisor
+ <code class="command">postgres</code> process.
+ </p><p>
+ If you are using a pre-packaged version
+ of <span class="productname">PostgreSQL</span>, and you used its provisions
+ for starting the server, then you should also use its provisions for
+ stopping the server. Consult the package-level documentation for
+ details.
+ </p><p>
+ When managing the server directly, you can control the type of shutdown
+ by sending different signals to the <code class="command">postgres</code>
+ process:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="systemitem">SIGTERM</span><a id="id-1.6.6.8.5.2.1.1.2" class="indexterm"></a></span></dt><dd><p>
+ This is the <em class="firstterm">Smart Shutdown</em> mode.
+ After receiving <span class="systemitem">SIGTERM</span>, the server
+ disallows new connections, but lets existing sessions end their
+ work normally. It shuts down only after all of the sessions terminate.
+ If the server is in recovery when a smart
+ shutdown is requested, recovery and streaming replication will be
+ stopped only after all regular sessions have terminated.
+ </p></dd><dt><span class="term"><span class="systemitem">SIGINT</span><a id="id-1.6.6.8.5.2.2.1.2" class="indexterm"></a></span></dt><dd><p>
+ This is the <em class="firstterm">Fast Shutdown</em> mode.
+ The server disallows new connections and sends all existing
+ server processes <span class="systemitem">SIGTERM</span>, which will cause them
+ to abort their current transactions and exit promptly. It then
+ waits for all server processes to exit and finally shuts down.
+ </p></dd><dt><span class="term"><span class="systemitem">SIGQUIT</span><a id="id-1.6.6.8.5.2.3.1.2" class="indexterm"></a></span></dt><dd><p>
+ This is the <em class="firstterm">Immediate Shutdown</em> mode.
+ The server will send <span class="systemitem">SIGQUIT</span> to all child
+ processes and wait for them to terminate. If any do not terminate
+ within 5 seconds, they will be sent <span class="systemitem">SIGKILL</span>.
+ The supervisor server process exits as soon as all child processes have
+ exited, without doing normal database shutdown processing.
+ This will lead to recovery (by
+ replaying the WAL log) upon next start-up. This is recommended
+ only in emergencies.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a> program provides a convenient
+ interface for sending these signals to shut down the server.
+ Alternatively, you can send the signal directly using <code class="command">kill</code>
+ on non-Windows systems.
+ The <acronym class="acronym">PID</acronym> of the <code class="command">postgres</code> process can be
+ found using the <code class="command">ps</code> program, or from the file
+ <code class="filename">postmaster.pid</code> in the data directory. For
+ example, to do a fast shutdown:
+</p><pre class="screen">
+$ <strong class="userinput"><code>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</code></strong>
+</pre><p>
+ </p><div class="important"><h3 class="title">Important</h3><p>
+ It is best not to use <span class="systemitem">SIGKILL</span> to shut down the
+ server. Doing so will prevent the server from releasing shared memory and
+ semaphores. Furthermore, <span class="systemitem">SIGKILL</span> kills
+ the <code class="command">postgres</code> process without letting it relay the
+ signal to its subprocesses, so it might be necessary to kill the
+ individual subprocesses by hand as well.
+ </p></div><p>
+ To terminate an individual session while allowing other sessions to
+ continue, use <code class="function">pg_terminate_backend()</code> (see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL-TABLE" title="Table 9.88. Server Signaling Functions">Table 9.88</a>) or send a
+ <span class="systemitem">SIGTERM</span> signal to the child process associated with
+ the session.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrading.html" title="19.6. Upgrading a PostgreSQL Cluster">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.4. Managing Kernel Resources </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/server-start.html b/doc/src/sgml/html/server-start.html
new file mode 100644
index 0000000..ca959a9
--- /dev/null
+++ b/doc/src/sgml/html/server-start.html
@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.3. Starting the Database Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="creating-cluster.html" title="19.2. Creating a Database Cluster" /><link rel="next" href="kernel-resources.html" title="19.4. Managing Kernel Resources" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.3. Starting the Database Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Next</a></td></tr></table><hr /></div><div class="sect1" id="SERVER-START"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.3. Starting the Database Server</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="server-start.html#SERVER-START-FAILURES">19.3.1. Server Start-up Failures</a></span></dt><dt><span class="sect2"><a href="server-start.html#CLIENT-CONNECTION-PROBLEMS">19.3.2. Client Connection Problems</a></span></dt></dl></div><p>
+ Before anyone can access the database, you must start the database
+ server. The database server program is called
+ <code class="command">postgres</code>.<a id="id-1.6.6.6.2.2" class="indexterm"></a>
+ </p><p>
+ If you are using a pre-packaged version
+ of <span class="productname">PostgreSQL</span>, it almost certainly includes
+ provisions for running the server as a background task according to the
+ conventions of your operating system. Using the package's
+ infrastructure to start the server will be much less work than figuring
+ out how to do this yourself. Consult the package-level documentation
+ for details.
+ </p><p>
+ The bare-bones way to start the server manually is just to invoke
+ <code class="command">postgres</code> directly, specifying the location of the
+ data directory with the <code class="option">-D</code> option, for example:
+</p><pre class="screen">
+$ <strong class="userinput"><code>postgres -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ which will leave the server running in the foreground. This must be
+ done while logged into the <span class="productname">PostgreSQL</span> user
+ account. Without <code class="option">-D</code>, the server will try to use
+ the data directory named by the environment variable <code class="envar">PGDATA</code>.
+ If that variable is not provided either, it will fail.
+ </p><p>
+ Normally it is better to start <code class="command">postgres</code> in the
+ background. For this, use the usual Unix shell syntax:
+</p><pre class="screen">
+$ <strong class="userinput"><code>postgres -D /usr/local/pgsql/data &gt;logfile 2&gt;&amp;1 &amp;</code></strong>
+</pre><p>
+ It is important to store the server's <span class="systemitem">stdout</span> and
+ <span class="systemitem">stderr</span> output somewhere, as shown above. It will help
+ for auditing purposes and to diagnose problems. (See <a class="xref" href="logfile-maintenance.html" title="25.3. Log File Maintenance">Section 25.3</a> for a more thorough discussion of log
+ file handling.)
+ </p><p>
+ The <code class="command">postgres</code> program also takes a number of other
+ command-line options. For more information, see the
+ <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference page
+ and <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> below.
+ </p><p>
+ This shell syntax can get tedious quickly. Therefore the wrapper
+ program
+ <a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a><a id="id-1.6.6.6.7.2" class="indexterm"></a>
+ is provided to simplify some tasks. For example:
+</p><pre class="programlisting">
+pg_ctl start -l logfile
+</pre><p>
+ will start the server in the background and put the output into the
+ named log file. The <code class="option">-D</code> option has the same meaning
+ here as for <code class="command">postgres</code>. <code class="command">pg_ctl</code>
+ is also capable of stopping the server.
+ </p><p>
+ Normally, you will want to start the database server when the
+ computer boots.<a id="id-1.6.6.6.8.1" class="indexterm"></a>
+ Autostart scripts are operating-system-specific.
+ There are a few example scripts distributed with
+ <span class="productname">PostgreSQL</span> in the
+ <code class="filename">contrib/start-scripts</code> directory. Installing one will require
+ root privileges.
+ </p><p>
+ Different systems have different conventions for starting up daemons
+ at boot time. Many systems have a file
+ <code class="filename">/etc/rc.local</code> or
+ <code class="filename">/etc/rc.d/rc.local</code>. Others use <code class="filename">init.d</code> or
+ <code class="filename">rc.d</code> directories. Whatever you do, the server must be
+ run by the <span class="productname">PostgreSQL</span> user account
+ <span class="emphasis"><em>and not by root</em></span> or any other user. Therefore you
+ probably should form your commands using
+ <code class="literal">su postgres -c '...'</code>. For example:
+</p><pre class="programlisting">
+su postgres -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog'
+</pre><p>
+ </p><p>
+ Here are a few more operating-system-specific suggestions. (In each
+ case be sure to use the proper installation directory and user
+ name where we show generic values.)
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ For <span class="productname">FreeBSD</span>, look at the file
+ <code class="filename">contrib/start-scripts/freebsd</code> in the
+ <span class="productname">PostgreSQL</span> source distribution.
+ <a id="id-1.6.6.6.10.1.1.1.4" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ On <span class="productname">OpenBSD</span>, add the following lines
+ to the file <code class="filename">/etc/rc.local</code>:
+ <a id="id-1.6.6.6.10.1.2.1.3" class="indexterm"></a>
+</p><pre class="programlisting">
+if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
+ su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data'
+ echo -n ' postgresql'
+fi
+</pre><p>
+ </p></li><li class="listitem"><p>
+ On <span class="productname">Linux</span> systems either add
+ <a id="id-1.6.6.6.10.1.3.1.2" class="indexterm"></a>
+</p><pre class="programlisting">
+/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
+</pre><p>
+ to <code class="filename">/etc/rc.d/rc.local</code>
+ or <code class="filename">/etc/rc.local</code> or look at the file
+ <code class="filename">contrib/start-scripts/linux</code> in the
+ <span class="productname">PostgreSQL</span> source distribution.
+ </p><p>
+ When using <span class="application">systemd</span>, you can use the following
+ service unit file (e.g.,
+ at <code class="filename">/etc/systemd/system/postgresql.service</code>):<a id="id-1.6.6.6.10.1.3.2.3" class="indexterm"></a>
+</p><pre class="programlisting">
+[Unit]
+Description=PostgreSQL database server
+Documentation=man:postgres(1)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=notify
+User=postgres
+ExecStart=/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
+ExecReload=/bin/kill -HUP $MAINPID
+KillMode=mixed
+KillSignal=SIGINT
+TimeoutSec=infinity
+
+[Install]
+WantedBy=multi-user.target
+</pre><p>
+ Using <code class="literal">Type=notify</code> requires that the server binary was
+ built with <code class="literal">configure --with-systemd</code>.
+ </p><p>
+ Consider carefully the timeout
+ setting. <span class="application">systemd</span> has a default timeout of 90
+ seconds as of this writing and will kill a process that does not report
+ readiness within that time. But a <span class="productname">PostgreSQL</span>
+ server that might have to perform crash recovery at startup could take
+ much longer to become ready. The suggested value
+ of <code class="literal">infinity</code> disables the timeout logic.
+ </p></li><li class="listitem"><p>
+ On <span class="productname">NetBSD</span>, use either the
+ <span class="productname">FreeBSD</span> or
+ <span class="productname">Linux</span> start scripts, depending on
+ preference.
+ <a id="id-1.6.6.6.10.1.4.1.4" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ On <span class="productname">Solaris</span>, create a file called
+ <code class="filename">/etc/init.d/postgresql</code> that contains
+ the following line:
+ <a id="id-1.6.6.6.10.1.5.1.3" class="indexterm"></a>
+</p><pre class="programlisting">
+su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"
+</pre><p>
+ Then, create a symbolic link to it in <code class="filename">/etc/rc3.d</code> as
+ <code class="filename">S99postgresql</code>.
+ </p></li></ul></div><p>
+
+ </p><p>
+ While the server is running, its
+ <acronym class="acronym">PID</acronym> is stored in the file
+ <code class="filename">postmaster.pid</code> in the data directory. This is
+ used to prevent multiple server instances from
+ running in the same data directory and can also be used for
+ shutting down the server.
+ </p><div class="sect2" id="SERVER-START-FAILURES"><div class="titlepage"><div><div><h3 class="title">19.3.1. Server Start-up Failures</h3></div></div></div><p>
+ There are several common reasons the server might fail to
+ start. Check the server's log file, or start it by hand (without
+ redirecting standard output or standard error) and see what error
+ messages appear. Below we explain some of the most common error
+ messages in more detail.
+ </p><p>
+</p><pre class="screen">
+LOG: could not bind IPv4 address "127.0.0.1": Address already in use
+HINT: Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
+FATAL: could not create any TCP/IP sockets
+</pre><p>
+ This usually means just what it suggests: you tried to start
+ another server on the same port where one is already running.
+ However, if the kernel error message is not <code class="computeroutput">Address
+ already in use</code> or some variant of that, there might
+ be a different problem. For example, trying to start a server
+ on a reserved port number might draw something like:
+</p><pre class="screen">
+$ <strong class="userinput"><code>postgres -p 666</code></strong>
+LOG: could not bind IPv4 address "127.0.0.1": Permission denied
+HINT: Is another postmaster already running on port 666? If not, wait a few seconds and retry.
+FATAL: could not create any TCP/IP sockets
+</pre><p>
+ </p><p>
+ A message like:
+</p><pre class="screen">
+FATAL: could not create shared memory segment: Invalid argument
+DETAIL: Failed system call was shmget(key=5440001, size=4011376640, 03600).
+</pre><p>
+ probably means your kernel's limit on the size of shared memory is
+ smaller than the work area <span class="productname">PostgreSQL</span>
+ is trying to create (4011376640 bytes in this example).
+ This is only likely to happen if you have set <code class="literal">shared_memory_type</code>
+ to <code class="literal">sysv</code>. In that case, you
+ can try starting the server with a smaller-than-normal number of
+ buffers (<a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>), or
+ reconfigure your kernel to increase the allowed shared memory
+ size. You might also see this message when trying to start multiple
+ servers on the same machine, if their total space requested
+ exceeds the kernel limit.
+ </p><p>
+ An error like:
+</p><pre class="screen">
+FATAL: could not create semaphores: No space left on device
+DETAIL: Failed system call was semget(5440126, 17, 03600).
+</pre><p>
+ does <span class="emphasis"><em>not</em></span> mean you've run out of disk
+ space. It means your kernel's limit on the number of <span class="systemitem">System V</span> semaphores is smaller than the number
+ <span class="productname">PostgreSQL</span> wants to create. As above,
+ you might be able to work around the problem by starting the
+ server with a reduced number of allowed connections
+ (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), but you'll eventually want to
+ increase the kernel limit.
+ </p><p>
+ Details about configuring <span class="systemitem">System V</span>
+ <acronym class="acronym">IPC</acronym> facilities are given in <a class="xref" href="kernel-resources.html#SYSVIPC" title="19.4.1. Shared Memory and Semaphores">Section 19.4.1</a>.
+ </p></div><div class="sect2" id="CLIENT-CONNECTION-PROBLEMS"><div class="titlepage"><div><div><h3 class="title">19.3.2. Client Connection Problems</h3></div></div></div><p>
+ Although the error conditions possible on the client side are quite
+ varied and application-dependent, a few of them might be directly
+ related to how the server was started. Conditions other than
+ those shown below should be documented with the respective client
+ application.
+ </p><p>
+</p><pre class="screen">
+psql: error: connection to server at "server.joe.com" (123.123.123.123), port 5432 failed: Connection refused
+ Is the server running on that host and accepting TCP/IP connections?
+</pre><p>
+ This is the generic <span class="quote">“<span class="quote">I couldn't find a server to talk
+ to</span>”</span> failure. It looks like the above when TCP/IP
+ communication is attempted. A common mistake is to forget to
+ configure the server to allow TCP/IP connections.
+ </p><p>
+ Alternatively, you might get this when attempting Unix-domain socket
+ communication to a local server:
+</p><pre class="screen">
+psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
+ Is the server running locally and accepting connections on that socket?
+</pre><p>
+ If the server is indeed running, check that the client's idea of the
+ socket path (here <code class="literal">/tmp</code>) agrees with the server's
+ <a class="xref" href="runtime-config-connection.html#GUC-UNIX-SOCKET-DIRECTORIES">unix_socket_directories</a> setting.
+ </p><p>
+ A connection failure message always shows the server address or socket
+ path name, which is useful in verifying that the client is trying to
+ connect to the right place. If there is in fact no server
+ listening there, the kernel error message will typically be either
+ <code class="computeroutput">Connection refused</code> or
+ <code class="computeroutput">No such file or directory</code>, as
+ illustrated. (It is important to realize that
+ <code class="computeroutput">Connection refused</code> in this context
+ does <span class="emphasis"><em>not</em></span> mean that the server got your
+ connection request and rejected it. That case will produce a
+ different message, as shown in <a class="xref" href="client-authentication-problems.html" title="21.15. Authentication Problems">Section 21.15</a>.) Other error messages
+ such as <code class="computeroutput">Connection timed out</code> might
+ indicate more fundamental problems, like lack of network
+ connectivity, or a firewall blocking the connection.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-resources.html" title="19.4. Managing Kernel Resources">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.2. Creating a Database Cluster </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.4. Managing Kernel Resources</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/source-conventions.html b/doc/src/sgml/html/source-conventions.html
new file mode 100644
index 0000000..6e4d362
--- /dev/null
+++ b/doc/src/sgml/html/source-conventions.html
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.4. Miscellaneous Coding Conventions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="error-style-guide.html" title="56.3. Error Message Style Guide" /><link rel="next" href="nls.html" title="Chapter 57. Native Language Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.4. Miscellaneous Coding Conventions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="error-style-guide.html" title="56.3. Error Message Style Guide">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 57. Native Language Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="SOURCE-CONVENTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.4. Miscellaneous Coding Conventions</h2></div></div></div><div class="simplesect" id="id-1.10.7.5.2"><div class="titlepage"><div><div><h3 class="title">C Standard</h3></div></div></div><p>
+ Code in <span class="productname">PostgreSQL</span> should only rely on language
+ features available in the C99 standard. That means a conforming
+ C99 compiler has to be able to compile postgres, at least aside
+ from a few platform dependent pieces.
+ </p><p>
+ A few features included in the C99 standard are, at this time, not
+ permitted to be used in core <span class="productname">PostgreSQL</span>
+ code. This currently includes variable length arrays, intermingled
+ declarations and code, <code class="literal">//</code> comments, universal
+ character names. Reasons for that include portability and historical
+ practices.
+ </p><p>
+ Features from later revisions of the C standard or compiler specific
+ features can be used, if a fallback is provided.
+ </p><p>
+ For example <code class="literal">_Static_assert()</code> and
+ <code class="literal">__builtin_constant_p</code> are currently used, even though
+ they are from newer revisions of the C standard and a
+ <span class="productname">GCC</span> extension respectively. If not available
+ we respectively fall back to using a C99 compatible replacement that
+ performs the same checks, but emits rather cryptic messages and do not
+ use <code class="literal">__builtin_constant_p</code>.
+ </p></div><div class="simplesect" id="id-1.10.7.5.3"><div class="titlepage"><div><div><h3 class="title">Function-Like Macros and Inline Functions</h3></div></div></div><p>
+ Both macros with arguments and <code class="literal">static inline</code>
+ functions may be used. The latter are preferable if there are
+ multiple-evaluation hazards when written as a macro, as e.g., the
+ case with
+</p><pre class="programlisting">
+#define Max(x, y) ((x) &gt; (y) ? (x) : (y))
+</pre><p>
+ or when the macro would be very long. In other cases it's only
+ possible to use macros, or at least easier. For example because
+ expressions of various types need to be passed to the macro.
+ </p><p>
+ When the definition of an inline function references symbols
+ (i.e., variables, functions) that are only available as part of the
+ backend, the function may not be visible when included from frontend
+ code.
+</p><pre class="programlisting">
+#ifndef FRONTEND
+static inline MemoryContext
+MemoryContextSwitchTo(MemoryContext context)
+{
+ MemoryContext old = CurrentMemoryContext;
+
+ CurrentMemoryContext = context;
+ return old;
+}
+#endif /* FRONTEND */
+</pre><p>
+ In this example <code class="literal">CurrentMemoryContext</code>, which is only
+ available in the backend, is referenced and the function thus
+ hidden with a <code class="literal">#ifndef FRONTEND</code>. This rule
+ exists because some compilers emit references to symbols
+ contained in inline functions even if the function is not used.
+ </p></div><div class="simplesect" id="id-1.10.7.5.4"><div class="titlepage"><div><div><h3 class="title">Writing Signal Handlers</h3></div></div></div><p>
+ To be suitable to run inside a signal handler code has to be
+ written very carefully. The fundamental problem is that, unless
+ blocked, a signal handler can interrupt code at any time. If code
+ inside the signal handler uses the same state as code outside
+ chaos may ensue. As an example consider what happens if a signal
+ handler tries to acquire a lock that's already held in the
+ interrupted code.
+ </p><p>
+ Barring special arrangements code in signal handlers may only
+ call async-signal safe functions (as defined in POSIX) and access
+ variables of type <code class="literal">volatile sig_atomic_t</code>. A few
+ functions in <code class="command">postgres</code> are also deemed signal safe, importantly
+ <code class="function">SetLatch()</code>.
+ </p><p>
+ In most cases signal handlers should do nothing more than note
+ that a signal has arrived, and wake up code running outside of
+ the handler using a latch. An example of such a handler is the
+ following:
+</p><pre class="programlisting">
+static void
+handle_sighup(SIGNAL_ARGS)
+{
+ int save_errno = errno;
+
+ got_SIGHUP = true;
+ SetLatch(MyLatch);
+
+ errno = save_errno;
+}
+</pre><p>
+ <code class="varname">errno</code> is saved and restored because
+ <code class="function">SetLatch()</code> might change it. If that were not done
+ interrupted code that's currently inspecting <code class="varname">errno</code> might see the wrong
+ value.
+ </p></div><div class="simplesect" id="id-1.10.7.5.5"><div class="titlepage"><div><div><h3 class="title">Calling Function Pointers</h3></div></div></div><p>
+ For clarity, it is preferred to explicitly dereference a function pointer
+ when calling the pointed-to function if the pointer is a simple variable,
+ for example:
+</p><pre class="programlisting">
+(*emit_log_hook) (edata);
+</pre><p>
+ (even though <code class="literal">emit_log_hook(edata)</code> would also work).
+ When the function pointer is part of a structure, then the extra
+ punctuation can and usually should be omitted, for example:
+</p><pre class="programlisting">
+paramInfo-&gt;paramFetch(paramInfo, paramId);
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="error-style-guide.html" title="56.3. Error Message Style Guide">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="nls.html" title="Chapter 57. Native Language Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.3. Error Message Style Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 57. Native Language Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/source-format.html b/doc/src/sgml/html/source-format.html
new file mode 100644
index 0000000..19adbb1
--- /dev/null
+++ b/doc/src/sgml/html/source-format.html
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.1. Formatting</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions" /><link rel="next" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.1. Formatting</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Next</a></td></tr></table><hr /></div><div class="sect1" id="SOURCE-FORMAT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.1. Formatting</h2></div></div></div><p>
+ Source code formatting uses 4 column tab spacing, with
+ tabs preserved (i.e., tabs are not expanded to spaces).
+ Each logical indentation level is one additional tab stop.
+ </p><p>
+ Layout rules (brace positioning, etc.) follow BSD conventions. In
+ particular, curly braces for the controlled blocks of <code class="literal">if</code>,
+ <code class="literal">while</code>, <code class="literal">switch</code>, etc. go on their own lines.
+ </p><p>
+ Limit line lengths so that the code is readable in an 80-column window.
+ (This doesn't mean that you must never go past 80 columns. For instance,
+ breaking a long error message string in arbitrary places just to keep the
+ code within 80 columns is probably not a net gain in readability.)
+ </p><p>
+ To maintain a consistent coding style, do not use C++ style comments
+ (<code class="literal">//</code> comments). <span class="application">pgindent</span>
+ will replace them with <code class="literal">/* ... */</code>.
+ </p><p>
+ The preferred style for multi-line comment blocks is
+</p><pre class="programlisting">
+/*
+ * comment text begins here
+ * and continues here
+ */
+</pre><p>
+ Note that comment blocks that begin in column 1 will be preserved as-is
+ by <span class="application">pgindent</span>, but it will re-flow indented comment blocks
+ as though they were plain text. If you want to preserve the line breaks
+ in an indented block, add dashes like this:
+</p><pre class="programlisting">
+ /*----------
+ * comment text begins here
+ * and continues here
+ *----------
+ */
+</pre><p>
+ </p><p>
+ While submitted patches do not absolutely have to follow these formatting
+ rules, it's a good idea to do so. Your code will get run through
+ <span class="application">pgindent</span> before the next release, so there's no point in
+ making it look nice under some other set of formatting conventions.
+ A good rule of thumb for patches is <span class="quote">“<span class="quote">make the new code look like
+ the existing code around it</span>”</span>.
+ </p><p>
+ The <code class="filename">src/tools/editors</code> directory contains sample settings
+ files that can be used with the <span class="productname">Emacs</span>,
+ <span class="productname">xemacs</span> or <span class="productname">vim</span>
+ editors to help ensure that they format code according to these
+ conventions.
+ </p><p>
+ If you'd like to run <span class="application">pgindent</span> locally
+ to help make your code match project style, see
+ the <code class="filename">src/tools/pgindent</code> directory.
+ </p><p>
+ The text browsing tools <span class="application">more</span> and
+ <span class="application">less</span> can be invoked as:
+</p><pre class="programlisting">
+more -x4
+less -x4
+</pre><p>
+ to make them show tabs appropriately.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="error-message-reporting.html" title="56.2. Reporting Errors Within the Server">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 56. PostgreSQL Coding Conventions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.2. Reporting Errors Within the Server</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/source.html b/doc/src/sgml/html/source.html
new file mode 100644
index 0000000..9e6c58d
--- /dev/null
+++ b/doc/src/sgml/html/source.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 56. PostgreSQL Coding Conventions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0" /><link rel="next" href="source-format.html" title="56.1. Formatting" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 56. PostgreSQL Coding Conventions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="source-format.html" title="56.1. Formatting">Next</a></td></tr></table><hr /></div><div class="chapter" id="SOURCE"><div class="titlepage"><div><div><h2 class="title">Chapter 56. PostgreSQL Coding Conventions</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="source-format.html">56.1. Formatting</a></span></dt><dt><span class="sect1"><a href="error-message-reporting.html">56.2. Reporting Errors Within the Server</a></span></dt><dt><span class="sect1"><a href="error-style-guide.html">56.3. Error Message Style Guide</a></span></dt><dt><span class="sect1"><a href="source-conventions.html">56.4. Miscellaneous Coding Conventions</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-changes.html" title="55.10. Summary of Changes since Protocol 2.0">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source-format.html" title="56.1. Formatting">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.10. Summary of Changes since Protocol 2.0 </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.1. Formatting</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sourcerepo.html b/doc/src/sgml/html/sourcerepo.html
new file mode 100644
index 0000000..61aa752
--- /dev/null
+++ b/doc/src/sgml/html/sourcerepo.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix I. The Source Code Repository</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="external-extensions.html" title="H.4. Extensions" /><link rel="next" href="git.html" title="I.1. Getting the Source via Git" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix I. The Source Code Repository</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="external-extensions.html" title="H.4. Extensions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="git.html" title="I.1. Getting the Source via Git">Next</a></td></tr></table><hr /></div><div class="appendix" id="SOURCEREPO"><div class="titlepage"><div><div><h2 class="title">Appendix I. The Source Code Repository</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="git.html">I.1. Getting the Source via <span class="productname">Git</span></a></span></dt></dl></div><p>
+ The <span class="productname">PostgreSQL</span> source code is stored and managed
+ using the <span class="productname">Git</span> version control system. A public
+ mirror of the master repository is available; it is updated within a minute
+ of any change to the master repository.
+ </p><p>
+ Our wiki, <a class="ulink" href="https://wiki.postgresql.org/wiki/Working_with_Git" target="_top">https://wiki.postgresql.org/wiki/Working_with_Git</a>,
+ has some discussion on working with Git.
+ </p><p>
+ Note that building <span class="productname">PostgreSQL</span> from the source
+ repository requires reasonably up-to-date versions of <span class="application">bison</span>,
+ <span class="application">flex</span>, and <span class="application">Perl</span>. These tools are not needed
+ to build from a distribution tarball, because the files that these tools
+ are used to build are included in the tarball. Other tool requirements
+ are the same as shown in <a class="xref" href="install-requirements.html" title="17.2. Requirements">Section 17.2</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="external-extensions.html" title="H.4. Extensions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="git.html" title="I.1. Getting the Source via Git">Next</a></td></tr><tr><td width="40%" align="left" valign="top">H.4. Extensions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> I.1. Getting the Source via <span class="productname">Git</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist-builtin-opclasses.html b/doc/src/sgml/html/spgist-builtin-opclasses.html
new file mode 100644
index 0000000..c1430a9
--- /dev/null
+++ b/doc/src/sgml/html/spgist-builtin-opclasses.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>69.2. Built-in Operator Classes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist-intro.html" title="69.1. Introduction" /><link rel="next" href="spgist-extensibility.html" title="69.3. Extensibility" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">69.2. Built-in Operator Classes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist-intro.html" title="69.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 69. SP-GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist-extensibility.html" title="69.3. Extensibility">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPGIST-BUILTIN-OPCLASSES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">69.2. Built-in Operator Classes</h2></div></div></div><p>
+ The core <span class="productname">PostgreSQL</span> distribution
+ includes the <acronym class="acronym">SP-GiST</acronym> operator classes shown in
+ <a class="xref" href="spgist-builtin-opclasses.html#SPGIST-BUILTIN-OPCLASSES-TABLE" title="Table 69.1. Built-in SP-GiST Operator Classes">Table 69.1</a>.
+ </p><div class="table" id="SPGIST-BUILTIN-OPCLASSES-TABLE"><p class="title"><strong>Table 69.1. Built-in <acronym class="acronym">SP-GiST</acronym> Operator Classes</strong></p><div class="table-contents"><table class="table" summary="Built-in SP-GiST Operator Classes" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Indexable Operators</th><th>Ordering Operators</th></tr></thead><tbody><tr><td rowspan="12" valign="middle"><code class="literal">box_ops</code></td><td><code class="literal">&lt;&lt; (box,box)</code></td><td rowspan="12" valign="middle"><code class="literal">&lt;-&gt; (box,point)</code></td></tr><tr><td><code class="literal">&amp;&lt; (box,box)</code></td></tr><tr><td><code class="literal">&amp;&gt; (box,box)</code></td></tr><tr><td><code class="literal">&gt;&gt; (box,box)</code></td></tr><tr><td><code class="literal">&lt;@ (box,box)</code></td></tr><tr><td><code class="literal">@&gt; (box,box)</code></td></tr><tr><td><code class="literal">~= (box,box)</code></td></tr><tr><td><code class="literal">&amp;&amp; (box,box)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (box,box)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (box,box)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (box,box)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (box,box)</code></td></tr><tr><td rowspan="11" valign="middle"><code class="literal">inet_ops</code></td><td><code class="literal">&lt;&lt; (inet,inet)</code></td><td rowspan="11" valign="middle"> </td></tr><tr><td><code class="literal">&lt;&lt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;&gt;= (inet,inet)</code></td></tr><tr><td><code class="literal">= (inet,inet)</code></td></tr><tr><td><code class="literal">&lt;&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&lt; (inet,inet)</code></td></tr><tr><td><code class="literal">&lt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&gt; (inet,inet)</code></td></tr><tr><td><code class="literal">&gt;= (inet,inet)</code></td></tr><tr><td><code class="literal">&amp;&amp; (inet,inet)</code></td></tr><tr><td rowspan="6" valign="middle"><code class="literal">kd_point_ops</code></td><td><code class="literal">|&gt;&gt; (point,point)</code></td><td rowspan="6" valign="middle"><code class="literal">&lt;-&gt; (point,point)</code></td></tr><tr><td><code class="literal">&lt;&lt; (point,point)</code></td></tr><tr><td><code class="literal">&gt;&gt; (point,point)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (point,point)</code></td></tr><tr><td><code class="literal">~= (point,point)</code></td></tr><tr><td><code class="literal">&lt;@ (point,box)</code></td></tr><tr><td rowspan="12" valign="middle"><code class="literal">poly_ops</code></td><td><code class="literal">&lt;&lt; (polygon,polygon)</code></td><td rowspan="12" valign="middle"><code class="literal">&lt;-&gt; (polygon,point)</code></td></tr><tr><td><code class="literal">&amp;&lt; (polygon,polygon)</code></td></tr><tr><td><code class="literal">&amp;&gt; (polygon,polygon)</code></td></tr><tr><td><code class="literal">&gt;&gt; (polygon,polygon)</code></td></tr><tr><td><code class="literal">&lt;@ (polygon,polygon)</code></td></tr><tr><td><code class="literal">@&gt; (polygon,polygon)</code></td></tr><tr><td><code class="literal">~= (polygon,polygon)</code></td></tr><tr><td><code class="literal">&amp;&amp; (polygon,polygon)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (polygon,polygon)</code></td></tr><tr><td><code class="literal">&amp;&lt;| (polygon,polygon)</code></td></tr><tr><td><code class="literal">|&gt;&gt; (polygon,polygon)</code></td></tr><tr><td><code class="literal">|&amp;&gt; (polygon,polygon)</code></td></tr><tr><td rowspan="6" valign="middle"><code class="literal">quad_point_ops</code></td><td><code class="literal">|&gt;&gt; (point,point)</code></td><td rowspan="6" valign="middle"><code class="literal">&lt;-&gt; (point,point)</code></td></tr><tr><td><code class="literal">&lt;&lt; (point,point)</code></td></tr><tr><td><code class="literal">&gt;&gt; (point,point)</code></td></tr><tr><td><code class="literal">&lt;&lt;| (point,point)</code></td></tr><tr><td><code class="literal">~= (point,point)</code></td></tr><tr><td><code class="literal">&lt;@ (point,box)</code></td></tr><tr><td rowspan="10" valign="middle"><code class="literal">range_ops</code></td><td><code class="literal">= (anyrange,anyrange)</code></td><td rowspan="10" valign="middle"> </td></tr><tr><td><code class="literal">&amp;&amp; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange,anyelement)</code></td></tr><tr><td><code class="literal">@&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt;@ (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&lt;&lt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&gt;&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&amp;&lt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">&amp;&gt; (anyrange,anyrange)</code></td></tr><tr><td><code class="literal">-|- (anyrange,anyrange)</code></td></tr><tr><td rowspan="10" valign="middle"><code class="literal">text_ops</code></td><td><code class="literal">= (text,text)</code></td><td rowspan="10" valign="middle"> </td></tr><tr><td><code class="literal">&lt; (text,text)</code></td></tr><tr><td><code class="literal">&lt;= (text,text)</code></td></tr><tr><td><code class="literal">&gt; (text,text)</code></td></tr><tr><td><code class="literal">&gt;= (text,text)</code></td></tr><tr><td><code class="literal">~&lt;~ (text,text)</code></td></tr><tr><td><code class="literal">~&lt;=~ (text,text)</code></td></tr><tr><td><code class="literal">~&gt;=~ (text,text)</code></td></tr><tr><td><code class="literal">~&gt;~ (text,text)</code></td></tr><tr><td><code class="literal">^@ (text,text)</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Of the two operator classes for type <code class="type">point</code>,
+ <code class="literal">quad_point_ops</code> is the default. <code class="literal">kd_point_ops</code>
+ supports the same operators but uses a different index data structure that
+ may offer better performance in some applications.
+ </p><p>
+ The <code class="literal">quad_point_ops</code>, <code class="literal">kd_point_ops</code> and
+ <code class="literal">poly_ops</code> operator classes support the <code class="literal">&lt;-&gt;</code>
+ ordering operator, which enables the k-nearest neighbor (<code class="literal">k-NN</code>)
+ search over indexed point or polygon data sets.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist-intro.html" title="69.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist-extensibility.html" title="69.3. Extensibility">Next</a></td></tr><tr><td width="40%" align="left" valign="top">69.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 69.3. Extensibility</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist-examples.html b/doc/src/sgml/html/spgist-examples.html
new file mode 100644
index 0000000..65f6e16
--- /dev/null
+++ b/doc/src/sgml/html/spgist-examples.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>69.5. Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist-implementation.html" title="69.4. Implementation" /><link rel="next" href="gin.html" title="Chapter 70. GIN Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">69.5. Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist-implementation.html" title="69.4. Implementation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 69. SP-GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gin.html" title="Chapter 70. GIN Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPGIST-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">69.5. Examples</h2></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> source distribution includes
+ several examples of index operator classes for <acronym class="acronym">SP-GiST</acronym>,
+ as described in <a class="xref" href="spgist-builtin-opclasses.html#SPGIST-BUILTIN-OPCLASSES-TABLE" title="Table 69.1. Built-in SP-GiST Operator Classes">Table 69.1</a>. Look
+ into <code class="filename">src/backend/access/spgist/</code>
+ and <code class="filename">src/backend/utils/adt/</code> to see the code.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist-implementation.html" title="69.4. Implementation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gin.html" title="Chapter 70. GIN Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">69.4. Implementation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 70. GIN Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist-extensibility.html b/doc/src/sgml/html/spgist-extensibility.html
new file mode 100644
index 0000000..177cb3d
--- /dev/null
+++ b/doc/src/sgml/html/spgist-extensibility.html
@@ -0,0 +1,621 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>69.3. Extensibility</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes" /><link rel="next" href="spgist-implementation.html" title="69.4. Implementation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">69.3. Extensibility</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 69. SP-GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist-implementation.html" title="69.4. Implementation">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPGIST-EXTENSIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">69.3. Extensibility</h2></div></div></div><p>
+ <acronym class="acronym">SP-GiST</acronym> offers an interface with a high level of
+ abstraction, requiring the access method developer to implement only
+ methods specific to a given data type. The <acronym class="acronym">SP-GiST</acronym> core
+ is responsible for efficient disk mapping and searching the tree structure.
+ It also takes care of concurrency and logging considerations.
+ </p><p>
+ Leaf tuples of an <acronym class="acronym">SP-GiST</acronym> tree usually contain values
+ of the same data type as the indexed column, although it is also possible
+ for them to contain lossy representations of the indexed column.
+ Leaf tuples stored at the root level will directly represent
+ the original indexed data value, but leaf tuples at lower
+ levels might contain only a partial value, such as a suffix.
+ In that case the operator class support functions must be able to
+ reconstruct the original value using information accumulated from the
+ inner tuples that are passed through to reach the leaf level.
+ </p><p>
+ When an <acronym class="acronym">SP-GiST</acronym> index is created with
+ <code class="literal">INCLUDE</code> columns, the values of those columns are also
+ stored in leaf tuples. The <code class="literal">INCLUDE</code> columns are of no
+ concern to the <acronym class="acronym">SP-GiST</acronym> operator class, so they are
+ not discussed further here.
+ </p><p>
+ Inner tuples are more complex, since they are branching points in the
+ search tree. Each inner tuple contains a set of one or more
+ <em class="firstterm">nodes</em>, which represent groups of similar leaf values.
+ A node contains a downlink that leads either to another, lower-level inner
+ tuple, or to a short list of leaf tuples that all lie on the same index page.
+ Each node normally has a <em class="firstterm">label</em> that describes it; for example,
+ in a radix tree the node label could be the next character of the string
+ value. (Alternatively, an operator class can omit the node labels, if it
+ works with a fixed set of nodes for all inner tuples;
+ see <a class="xref" href="spgist-implementation.html#SPGIST-NULL-LABELS" title="69.4.2. SP-GiST Without Node Labels">Section 69.4.2</a>.)
+ Optionally, an inner tuple can have a <em class="firstterm">prefix</em> value
+ that describes all its members. In a radix tree this could be the common
+ prefix of the represented strings. The prefix value is not necessarily
+ really a prefix, but can be any data needed by the operator class;
+ for example, in a quad-tree it can store the central point that the four
+ quadrants are measured with respect to. A quad-tree inner tuple would
+ then also contain four nodes corresponding to the quadrants around this
+ central point.
+ </p><p>
+ Some tree algorithms require knowledge of level (or depth) of the current
+ tuple, so the <acronym class="acronym">SP-GiST</acronym> core provides the possibility for
+ operator classes to manage level counting while descending the tree.
+ There is also support for incrementally reconstructing the represented
+ value when that is needed, and for passing down additional data (called
+ <em class="firstterm">traverse values</em>) during a tree descent.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <acronym class="acronym">SP-GiST</acronym> core code takes care of null entries.
+ Although <acronym class="acronym">SP-GiST</acronym> indexes do store entries for nulls
+ in indexed columns, this is hidden from the index operator class code:
+ no null index entries or search conditions will ever be passed to the
+ operator class methods. (It is assumed that <acronym class="acronym">SP-GiST</acronym>
+ operators are strict and so cannot succeed for null values.) Null values
+ are therefore not discussed further here.
+ </p></div><p>
+ There are five user-defined methods that an index operator class for
+ <acronym class="acronym">SP-GiST</acronym> must provide, and two are optional. All five
+ mandatory methods follow the convention of accepting two <code class="type">internal</code>
+ arguments, the first of which is a pointer to a C struct containing input
+ values for the support method, while the second argument is a pointer to a
+ C struct where output values must be placed. Four of the mandatory methods just
+ return <code class="type">void</code>, since all their results appear in the output struct; but
+ <code class="function">leaf_consistent</code> returns a <code class="type">boolean</code> result.
+ The methods must not modify any fields of their input structs. In all
+ cases, the output struct is initialized to zeroes before calling the
+ user-defined method. The optional sixth method <code class="function">compress</code>
+ accepts a <code class="type">datum</code> to be indexed as the only argument and returns a value suitable
+ for physical storage in a leaf tuple. The optional seventh method
+ <code class="function">options</code> accepts an <code class="type">internal</code> pointer to a C struct, where
+ opclass-specific parameters should be placed, and returns <code class="type">void</code>.
+ </p><p>
+ The five mandatory user-defined methods are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">config</code></span></dt><dd><p>
+ Returns static information about the index implementation, including
+ the data type OIDs of the prefix and node label data types.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+</p><pre class="programlisting">
+CREATE FUNCTION my_config(internal, internal) RETURNS void ...
+</pre><p>
+ The first argument is a pointer to a <code class="structname">spgConfigIn</code>
+ C struct, containing input data for the function.
+ The second argument is a pointer to a <code class="structname">spgConfigOut</code>
+ C struct, which the function must fill with result data.
+</p><pre class="programlisting">
+typedef struct spgConfigIn
+{
+ Oid attType; /* Data type to be indexed */
+} spgConfigIn;
+
+typedef struct spgConfigOut
+{
+ Oid prefixType; /* Data type of inner-tuple prefixes */
+ Oid labelType; /* Data type of inner-tuple node labels */
+ Oid leafType; /* Data type of leaf-tuple values */
+ bool canReturnData; /* Opclass can reconstruct original data */
+ bool longValuesOK; /* Opclass can cope with values &gt; 1 page */
+} spgConfigOut;
+</pre><p>
+
+ <code class="structfield">attType</code> is passed in order to support polymorphic
+ index operator classes; for ordinary fixed-data-type operator classes, it
+ will always have the same value and so can be ignored.
+ </p><p>
+ For operator classes that do not use prefixes,
+ <code class="structfield">prefixType</code> can be set to <code class="literal">VOIDOID</code>.
+ Likewise, for operator classes that do not use node labels,
+ <code class="structfield">labelType</code> can be set to <code class="literal">VOIDOID</code>.
+ <code class="structfield">canReturnData</code> should be set true if the operator class
+ is capable of reconstructing the originally-supplied index value.
+ <code class="structfield">longValuesOK</code> should be set true only when the
+ <code class="structfield">attType</code> is of variable length and the operator
+ class is capable of segmenting long values by repeated suffixing
+ (see <a class="xref" href="spgist-implementation.html#SPGIST-LIMITS" title="69.4.1. SP-GiST Limits">Section 69.4.1</a>).
+ </p><p>
+ <code class="structfield">leafType</code> should match the index storage type
+ defined by the operator class's <code class="structfield">opckeytype</code>
+ catalog entry.
+ (Note that <code class="structfield">opckeytype</code> can be zero,
+ implying the storage type is the same as the operator class's input
+ type, which is the most common situation.)
+ For reasons of backward compatibility, the <code class="function">config</code>
+ method can set <code class="structfield">leafType</code> to some other value,
+ and that value will be used; but this is deprecated since the index
+ contents are then incorrectly identified in the catalogs.
+ Also, it's permissible to
+ leave <code class="structfield">leafType</code> uninitialized (zero);
+ that is interpreted as meaning the index storage type derived from
+ <code class="structfield">opckeytype</code>.
+ </p><p>
+ When <code class="structfield">attType</code>
+ and <code class="structfield">leafType</code> are different, the optional
+ method <code class="function">compress</code> must be provided.
+ Method <code class="function">compress</code> is responsible
+ for transformation of datums to be indexed from <code class="structfield">attType</code>
+ to <code class="structfield">leafType</code>.
+ </p></dd><dt><span class="term"><code class="function">choose</code></span></dt><dd><p>
+ Chooses a method for inserting a new value into an inner tuple.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+</p><pre class="programlisting">
+CREATE FUNCTION my_choose(internal, internal) RETURNS void ...
+</pre><p>
+ The first argument is a pointer to a <code class="structname">spgChooseIn</code>
+ C struct, containing input data for the function.
+ The second argument is a pointer to a <code class="structname">spgChooseOut</code>
+ C struct, which the function must fill with result data.
+</p><pre class="programlisting">
+typedef struct spgChooseIn
+{
+ Datum datum; /* original datum to be indexed */
+ Datum leafDatum; /* current datum to be stored at leaf */
+ int level; /* current level (counting from zero) */
+
+ /* Data from current inner tuple */
+ bool allTheSame; /* tuple is marked all-the-same? */
+ bool hasPrefix; /* tuple has a prefix? */
+ Datum prefixDatum; /* if so, the prefix value */
+ int nNodes; /* number of nodes in the inner tuple */
+ Datum *nodeLabels; /* node label values (NULL if none) */
+} spgChooseIn;
+
+typedef enum spgChooseResultType
+{
+ spgMatchNode = 1, /* descend into existing node */
+ spgAddNode, /* add a node to the inner tuple */
+ spgSplitTuple /* split inner tuple (change its prefix) */
+} spgChooseResultType;
+
+typedef struct spgChooseOut
+{
+ spgChooseResultType resultType; /* action code, see above */
+ union
+ {
+ struct /* results for spgMatchNode */
+ {
+ int nodeN; /* descend to this node (index from 0) */
+ int levelAdd; /* increment level by this much */
+ Datum restDatum; /* new leaf datum */
+ } matchNode;
+ struct /* results for spgAddNode */
+ {
+ Datum nodeLabel; /* new node's label */
+ int nodeN; /* where to insert it (index from 0) */
+ } addNode;
+ struct /* results for spgSplitTuple */
+ {
+ /* Info to form new upper-level inner tuple with one child tuple */
+ bool prefixHasPrefix; /* tuple should have a prefix? */
+ Datum prefixPrefixDatum; /* if so, its value */
+ int prefixNNodes; /* number of nodes */
+ Datum *prefixNodeLabels; /* their labels (or NULL for
+ * no labels) */
+ int childNodeN; /* which node gets child tuple */
+
+ /* Info to form new lower-level inner tuple with all old nodes */
+ bool postfixHasPrefix; /* tuple should have a prefix? */
+ Datum postfixPrefixDatum; /* if so, its value */
+ } splitTuple;
+ } result;
+} spgChooseOut;
+</pre><p>
+
+ <code class="structfield">datum</code> is the original datum of
+ <code class="structname">spgConfigIn</code>.<code class="structfield">attType</code>
+ type that was to be inserted into the index.
+ <code class="structfield">leafDatum</code> is a value of
+ <code class="structname">spgConfigOut</code>.<code class="structfield">leafType</code>
+ type, which is initially a result of method
+ <code class="function">compress</code> applied to <code class="structfield">datum</code>
+ when method <code class="function">compress</code> is provided, or the same value as
+ <code class="structfield">datum</code> otherwise.
+ <code class="structfield">leafDatum</code> can change at lower levels of the tree
+ if the <code class="function">choose</code> or <code class="function">picksplit</code>
+ methods change it. When the insertion search reaches a leaf page,
+ the current value of <code class="structfield">leafDatum</code> is what will be stored
+ in the newly created leaf tuple.
+ <code class="structfield">level</code> is the current inner tuple's level, starting at
+ zero for the root level.
+ <code class="structfield">allTheSame</code> is true if the current inner tuple is
+ marked as containing multiple equivalent nodes
+ (see <a class="xref" href="spgist-implementation.html#SPGIST-ALL-THE-SAME" title="69.4.3. “All-the-Same” Inner Tuples">Section 69.4.3</a>).
+ <code class="structfield">hasPrefix</code> is true if the current inner tuple contains
+ a prefix; if so,
+ <code class="structfield">prefixDatum</code> is its value.
+ <code class="structfield">nNodes</code> is the number of child nodes contained in the
+ inner tuple, and
+ <code class="structfield">nodeLabels</code> is an array of their label values, or
+ NULL if there are no labels.
+ </p><p>
+ The <code class="function">choose</code> function can determine either that
+ the new value matches one of the existing child nodes, or that a new
+ child node must be added, or that the new value is inconsistent with
+ the tuple prefix and so the inner tuple must be split to create a
+ less restrictive prefix.
+ </p><p>
+ If the new value matches one of the existing child nodes,
+ set <code class="structfield">resultType</code> to <code class="literal">spgMatchNode</code>.
+ Set <code class="structfield">nodeN</code> to the index (from zero) of that node in
+ the node array.
+ Set <code class="structfield">levelAdd</code> to the increment in
+ <code class="structfield">level</code> caused by descending through that node,
+ or leave it as zero if the operator class does not use levels.
+ Set <code class="structfield">restDatum</code> to equal <code class="structfield">leafDatum</code>
+ if the operator class does not modify datums from one level to the
+ next, or otherwise set it to the modified value to be used as
+ <code class="structfield">leafDatum</code> at the next level.
+ </p><p>
+ If a new child node must be added,
+ set <code class="structfield">resultType</code> to <code class="literal">spgAddNode</code>.
+ Set <code class="structfield">nodeLabel</code> to the label to be used for the new
+ node, and set <code class="structfield">nodeN</code> to the index (from zero) at which
+ to insert the node in the node array.
+ After the node has been added, the <code class="function">choose</code>
+ function will be called again with the modified inner tuple;
+ that call should result in an <code class="literal">spgMatchNode</code> result.
+ </p><p>
+ If the new value is inconsistent with the tuple prefix,
+ set <code class="structfield">resultType</code> to <code class="literal">spgSplitTuple</code>.
+ This action moves all the existing nodes into a new lower-level
+ inner tuple, and replaces the existing inner tuple with a tuple
+ having a single downlink pointing to the new lower-level inner tuple.
+ Set <code class="structfield">prefixHasPrefix</code> to indicate whether the new
+ upper tuple should have a prefix, and if so set
+ <code class="structfield">prefixPrefixDatum</code> to the prefix value. This new
+ prefix value must be sufficiently less restrictive than the original
+ to accept the new value to be indexed.
+ Set <code class="structfield">prefixNNodes</code> to the number of nodes needed in the
+ new tuple, and set <code class="structfield">prefixNodeLabels</code> to a palloc'd array
+ holding their labels, or to NULL if node labels are not required.
+ Note that the total size of the new upper tuple must be no more
+ than the total size of the tuple it is replacing; this constrains
+ the lengths of the new prefix and new labels.
+ Set <code class="structfield">childNodeN</code> to the index (from zero) of the node
+ that will downlink to the new lower-level inner tuple.
+ Set <code class="structfield">postfixHasPrefix</code> to indicate whether the new
+ lower-level inner tuple should have a prefix, and if so set
+ <code class="structfield">postfixPrefixDatum</code> to the prefix value. The
+ combination of these two prefixes and the downlink node's label
+ (if any) must have the same meaning as the original prefix, because
+ there is no opportunity to alter the node labels that are moved to
+ the new lower-level tuple, nor to change any child index entries.
+ After the node has been split, the <code class="function">choose</code>
+ function will be called again with the replacement inner tuple.
+ That call may return an <code class="literal">spgAddNode</code> result, if no suitable
+ node was created by the <code class="literal">spgSplitTuple</code> action. Eventually
+ <code class="function">choose</code> must return <code class="literal">spgMatchNode</code> to
+ allow the insertion to descend to the next level.
+ </p></dd><dt><span class="term"><code class="function">picksplit</code></span></dt><dd><p>
+ Decides how to create a new inner tuple over a set of leaf tuples.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+</p><pre class="programlisting">
+CREATE FUNCTION my_picksplit(internal, internal) RETURNS void ...
+</pre><p>
+ The first argument is a pointer to a <code class="structname">spgPickSplitIn</code>
+ C struct, containing input data for the function.
+ The second argument is a pointer to a <code class="structname">spgPickSplitOut</code>
+ C struct, which the function must fill with result data.
+</p><pre class="programlisting">
+typedef struct spgPickSplitIn
+{
+ int nTuples; /* number of leaf tuples */
+ Datum *datums; /* their datums (array of length nTuples) */
+ int level; /* current level (counting from zero) */
+} spgPickSplitIn;
+
+typedef struct spgPickSplitOut
+{
+ bool hasPrefix; /* new inner tuple should have a prefix? */
+ Datum prefixDatum; /* if so, its value */
+
+ int nNodes; /* number of nodes for new inner tuple */
+ Datum *nodeLabels; /* their labels (or NULL for no labels) */
+
+ int *mapTuplesToNodes; /* node index for each leaf tuple */
+ Datum *leafTupleDatums; /* datum to store in each new leaf tuple */
+} spgPickSplitOut;
+</pre><p>
+
+ <code class="structfield">nTuples</code> is the number of leaf tuples provided.
+ <code class="structfield">datums</code> is an array of their datum values of
+ <code class="structname">spgConfigOut</code>.<code class="structfield">leafType</code>
+ type.
+ <code class="structfield">level</code> is the current level that all the leaf tuples
+ share, which will become the level of the new inner tuple.
+ </p><p>
+ Set <code class="structfield">hasPrefix</code> to indicate whether the new inner
+ tuple should have a prefix, and if so set
+ <code class="structfield">prefixDatum</code> to the prefix value.
+ Set <code class="structfield">nNodes</code> to indicate the number of nodes that
+ the new inner tuple will contain, and
+ set <code class="structfield">nodeLabels</code> to an array of their label values,
+ or to NULL if node labels are not required.
+ Set <code class="structfield">mapTuplesToNodes</code> to an array that gives the index
+ (from zero) of the node that each leaf tuple should be assigned to.
+ Set <code class="structfield">leafTupleDatums</code> to an array of the values to
+ be stored in the new leaf tuples (these will be the same as the
+ input <code class="structfield">datums</code> if the operator class does not modify
+ datums from one level to the next).
+ Note that the <code class="function">picksplit</code> function is
+ responsible for palloc'ing the
+ <code class="structfield">nodeLabels</code>, <code class="structfield">mapTuplesToNodes</code> and
+ <code class="structfield">leafTupleDatums</code> arrays.
+ </p><p>
+ If more than one leaf tuple is supplied, it is expected that the
+ <code class="function">picksplit</code> function will classify them into more than
+ one node; otherwise it is not possible to split the leaf tuples
+ across multiple pages, which is the ultimate purpose of this
+ operation. Therefore, if the <code class="function">picksplit</code> function
+ ends up placing all the leaf tuples in the same node, the core
+ SP-GiST code will override that decision and generate an inner
+ tuple in which the leaf tuples are assigned at random to several
+ identically-labeled nodes. Such a tuple is marked
+ <code class="literal">allTheSame</code> to signify that this has happened. The
+ <code class="function">choose</code> and <code class="function">inner_consistent</code> functions
+ must take suitable care with such inner tuples.
+ See <a class="xref" href="spgist-implementation.html#SPGIST-ALL-THE-SAME" title="69.4.3. “All-the-Same” Inner Tuples">Section 69.4.3</a> for more information.
+ </p><p>
+ <code class="function">picksplit</code> can be applied to a single leaf tuple only
+ in the case that the <code class="function">config</code> function set
+ <code class="structfield">longValuesOK</code> to true and a larger-than-a-page input
+ value has been supplied. In this case the point of the operation is
+ to strip off a prefix and produce a new, shorter leaf datum value.
+ The call will be repeated until a leaf datum short enough to fit on
+ a page has been produced. See <a class="xref" href="spgist-implementation.html#SPGIST-LIMITS" title="69.4.1. SP-GiST Limits">Section 69.4.1</a> for
+ more information.
+ </p></dd><dt><span class="term"><code class="function">inner_consistent</code></span></dt><dd><p>
+ Returns set of nodes (branches) to follow during tree search.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+</p><pre class="programlisting">
+CREATE FUNCTION my_inner_consistent(internal, internal) RETURNS void ...
+</pre><p>
+ The first argument is a pointer to a <code class="structname">spgInnerConsistentIn</code>
+ C struct, containing input data for the function.
+ The second argument is a pointer to a <code class="structname">spgInnerConsistentOut</code>
+ C struct, which the function must fill with result data.
+
+</p><pre class="programlisting">
+typedef struct spgInnerConsistentIn
+{
+ ScanKey scankeys; /* array of operators and comparison values */
+ ScanKey orderbys; /* array of ordering operators and comparison
+ * values */
+ int nkeys; /* length of scankeys array */
+ int norderbys; /* length of orderbys array */
+
+ Datum reconstructedValue; /* value reconstructed at parent */
+ void *traversalValue; /* opclass-specific traverse value */
+ MemoryContext traversalMemoryContext; /* put new traverse values here */
+ int level; /* current level (counting from zero) */
+ bool returnData; /* original data must be returned? */
+
+ /* Data from current inner tuple */
+ bool allTheSame; /* tuple is marked all-the-same? */
+ bool hasPrefix; /* tuple has a prefix? */
+ Datum prefixDatum; /* if so, the prefix value */
+ int nNodes; /* number of nodes in the inner tuple */
+ Datum *nodeLabels; /* node label values (NULL if none) */
+} spgInnerConsistentIn;
+
+typedef struct spgInnerConsistentOut
+{
+ int nNodes; /* number of child nodes to be visited */
+ int *nodeNumbers; /* their indexes in the node array */
+ int *levelAdds; /* increment level by this much for each */
+ Datum *reconstructedValues; /* associated reconstructed values */
+ void **traversalValues; /* opclass-specific traverse values */
+ double **distances; /* associated distances */
+} spgInnerConsistentOut;
+</pre><p>
+
+ The array <code class="structfield">scankeys</code>, of length <code class="structfield">nkeys</code>,
+ describes the index search condition(s). These conditions are
+ combined with AND — only index entries that satisfy all of
+ them are interesting. (Note that <code class="structfield">nkeys</code> = 0 implies
+ that all index entries satisfy the query.) Usually the consistent
+ function only cares about the <code class="structfield">sk_strategy</code> and
+ <code class="structfield">sk_argument</code> fields of each array entry, which
+ respectively give the indexable operator and comparison value.
+ In particular it is not necessary to check <code class="structfield">sk_flags</code> to
+ see if the comparison value is NULL, because the SP-GiST core code
+ will filter out such conditions.
+ The array <code class="structfield">orderbys</code>, of length <code class="structfield">norderbys</code>,
+ describes ordering operators (if any) in the same manner.
+ <code class="structfield">reconstructedValue</code> is the value reconstructed for the
+ parent tuple; it is <code class="literal">(Datum) 0</code> at the root level or if the
+ <code class="function">inner_consistent</code> function did not provide a value at the
+ parent level.
+ <code class="structfield">traversalValue</code> is a pointer to any traverse data
+ passed down from the previous call of <code class="function">inner_consistent</code>
+ on the parent index tuple, or NULL at the root level.
+ <code class="structfield">traversalMemoryContext</code> is the memory context in which
+ to store output traverse values (see below).
+ <code class="structfield">level</code> is the current inner tuple's level, starting at
+ zero for the root level.
+ <code class="structfield">returnData</code> is <code class="literal">true</code> if reconstructed data is
+ required for this query; this will only be so if the
+ <code class="function">config</code> function asserted <code class="structfield">canReturnData</code>.
+ <code class="structfield">allTheSame</code> is true if the current inner tuple is
+ marked <span class="quote">“<span class="quote">all-the-same</span>”</span>; in this case all the nodes have the
+ same label (if any) and so either all or none of them match the query
+ (see <a class="xref" href="spgist-implementation.html#SPGIST-ALL-THE-SAME" title="69.4.3. “All-the-Same” Inner Tuples">Section 69.4.3</a>).
+ <code class="structfield">hasPrefix</code> is true if the current inner tuple contains
+ a prefix; if so,
+ <code class="structfield">prefixDatum</code> is its value.
+ <code class="structfield">nNodes</code> is the number of child nodes contained in the
+ inner tuple, and
+ <code class="structfield">nodeLabels</code> is an array of their label values, or
+ NULL if the nodes do not have labels.
+ </p><p>
+ <code class="structfield">nNodes</code> must be set to the number of child nodes that
+ need to be visited by the search, and
+ <code class="structfield">nodeNumbers</code> must be set to an array of their indexes.
+ If the operator class keeps track of levels, set
+ <code class="structfield">levelAdds</code> to an array of the level increments
+ required when descending to each node to be visited. (Often these
+ increments will be the same for all the nodes, but that's not
+ necessarily so, so an array is used.)
+ If value reconstruction is needed, set
+ <code class="structfield">reconstructedValues</code> to an array of the values
+ reconstructed for each child node to be visited; otherwise, leave
+ <code class="structfield">reconstructedValues</code> as NULL.
+ The reconstructed values are assumed to be of type
+ <code class="structname">spgConfigOut</code>.<code class="structfield">leafType</code>.
+ (However, since the core system will do nothing with them except
+ possibly copy them, it is sufficient for them to have the
+ same <code class="literal">typlen</code> and <code class="literal">typbyval</code>
+ properties as <code class="structfield">leafType</code>.)
+ If ordered search is performed, set <code class="structfield">distances</code>
+ to an array of distance values according to <code class="structfield">orderbys</code>
+ array (nodes with lowest distances will be processed first). Leave it
+ NULL otherwise.
+ If it is desired to pass down additional out-of-band information
+ (<span class="quote">“<span class="quote">traverse values</span>”</span>) to lower levels of the tree search,
+ set <code class="structfield">traversalValues</code> to an array of the appropriate
+ traverse values, one for each child node to be visited; otherwise,
+ leave <code class="structfield">traversalValues</code> as NULL.
+ Note that the <code class="function">inner_consistent</code> function is
+ responsible for palloc'ing the
+ <code class="structfield">nodeNumbers</code>, <code class="structfield">levelAdds</code>,
+ <code class="structfield">distances</code>,
+ <code class="structfield">reconstructedValues</code>, and
+ <code class="structfield">traversalValues</code> arrays in the current memory context.
+ However, any output traverse values pointed to by
+ the <code class="structfield">traversalValues</code> array should be allocated
+ in <code class="structfield">traversalMemoryContext</code>.
+ Each traverse value must be a single palloc'd chunk.
+ </p></dd><dt><span class="term"><code class="function">leaf_consistent</code></span></dt><dd><p>
+ Returns true if a leaf tuple satisfies a query.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+</p><pre class="programlisting">
+CREATE FUNCTION my_leaf_consistent(internal, internal) RETURNS bool ...
+</pre><p>
+ The first argument is a pointer to a <code class="structname">spgLeafConsistentIn</code>
+ C struct, containing input data for the function.
+ The second argument is a pointer to a <code class="structname">spgLeafConsistentOut</code>
+ C struct, which the function must fill with result data.
+</p><pre class="programlisting">
+typedef struct spgLeafConsistentIn
+{
+ ScanKey scankeys; /* array of operators and comparison values */
+ ScanKey orderbys; /* array of ordering operators and comparison
+ * values */
+ int nkeys; /* length of scankeys array */
+ int norderbys; /* length of orderbys array */
+
+ Datum reconstructedValue; /* value reconstructed at parent */
+ void *traversalValue; /* opclass-specific traverse value */
+ int level; /* current level (counting from zero) */
+ bool returnData; /* original data must be returned? */
+
+ Datum leafDatum; /* datum in leaf tuple */
+} spgLeafConsistentIn;
+
+typedef struct spgLeafConsistentOut
+{
+ Datum leafValue; /* reconstructed original data, if any */
+ bool recheck; /* set true if operator must be rechecked */
+ bool recheckDistances; /* set true if distances must be rechecked */
+ double *distances; /* associated distances */
+} spgLeafConsistentOut;
+</pre><p>
+
+ The array <code class="structfield">scankeys</code>, of length <code class="structfield">nkeys</code>,
+ describes the index search condition(s). These conditions are
+ combined with AND — only index entries that satisfy all of
+ them satisfy the query. (Note that <code class="structfield">nkeys</code> = 0 implies
+ that all index entries satisfy the query.) Usually the consistent
+ function only cares about the <code class="structfield">sk_strategy</code> and
+ <code class="structfield">sk_argument</code> fields of each array entry, which
+ respectively give the indexable operator and comparison value.
+ In particular it is not necessary to check <code class="structfield">sk_flags</code> to
+ see if the comparison value is NULL, because the SP-GiST core code
+ will filter out such conditions.
+ The array <code class="structfield">orderbys</code>, of length <code class="structfield">norderbys</code>,
+ describes the ordering operators in the same manner.
+ <code class="structfield">reconstructedValue</code> is the value reconstructed for the
+ parent tuple; it is <code class="literal">(Datum) 0</code> at the root level or if the
+ <code class="function">inner_consistent</code> function did not provide a value at the
+ parent level.
+ <code class="structfield">traversalValue</code> is a pointer to any traverse data
+ passed down from the previous call of <code class="function">inner_consistent</code>
+ on the parent index tuple, or NULL at the root level.
+ <code class="structfield">level</code> is the current leaf tuple's level, starting at
+ zero for the root level.
+ <code class="structfield">returnData</code> is <code class="literal">true</code> if reconstructed data is
+ required for this query; this will only be so if the
+ <code class="function">config</code> function asserted <code class="structfield">canReturnData</code>.
+ <code class="structfield">leafDatum</code> is the key value of
+ <code class="structname">spgConfigOut</code>.<code class="structfield">leafType</code>
+ stored in the current leaf tuple.
+ </p><p>
+ The function must return <code class="literal">true</code> if the leaf tuple matches the
+ query, or <code class="literal">false</code> if not. In the <code class="literal">true</code> case,
+ if <code class="structfield">returnData</code> is <code class="literal">true</code> then
+ <code class="structfield">leafValue</code> must be set to the value (of type
+ <code class="structname">spgConfigIn</code>.<code class="structfield">attType</code>)
+ originally supplied to be indexed for this leaf tuple. Also,
+ <code class="structfield">recheck</code> may be set to <code class="literal">true</code> if the match
+ is uncertain and so the operator(s) must be re-applied to the actual
+ heap tuple to verify the match.
+ If ordered search is performed, set <code class="structfield">distances</code>
+ to an array of distance values according to <code class="structfield">orderbys</code>
+ array. Leave it NULL otherwise. If at least one of returned distances
+ is not exact, set <code class="structfield">recheckDistances</code> to true.
+ In this case, the executor will calculate the exact distances after
+ fetching the tuple from the heap, and will reorder the tuples if needed.
+ </p></dd></dl></div><p>
+ The optional user-defined methods are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">Datum compress(Datum in)</code></span></dt><dd><p>
+ Converts a data item into a format suitable for physical storage in
+ a leaf tuple of the index. It accepts a value of type
+ <code class="structname">spgConfigIn</code>.<code class="structfield">attType</code>
+ and returns a value of type
+ <code class="structname">spgConfigOut</code>.<code class="structfield">leafType</code>.
+ The output value must not contain an out-of-line TOAST pointer.
+ </p><p>
+ Note: the <code class="function">compress</code> method is only applied to
+ values to be stored. The consistent methods receive query
+ <code class="structfield">scankeys</code> unchanged, without transformation
+ using <code class="function">compress</code>.
+ </p></dd><dt><span class="term"><code class="function">options</code></span></dt><dd><p>
+ Defines a set of user-visible parameters that control operator class
+ behavior.
+ </p><p>
+ The <acronym class="acronym">SQL</acronym> declaration of the function must look like this:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION my_options(internal)
+RETURNS void
+AS 'MODULE_PATHNAME'
+LANGUAGE C STRICT;
+</pre><p>
+ </p><p>
+ The function is passed a pointer to a <code class="structname">local_relopts</code>
+ struct, which needs to be filled with a set of operator class
+ specific options. The options can be accessed from other support
+ functions using the <code class="literal">PG_HAS_OPCLASS_OPTIONS()</code> and
+ <code class="literal">PG_GET_OPCLASS_OPTIONS()</code> macros.
+ </p><p>
+ Since the representation of the key in <acronym class="acronym">SP-GiST</acronym> is
+ flexible, it may depend on user-specified parameters.
+ </p></dd></dl></div><p>
+ All the SP-GiST support methods are normally called in a short-lived
+ memory context; that is, <code class="varname">CurrentMemoryContext</code> will be reset
+ after processing of each tuple. It is therefore not very important to
+ worry about pfree'ing everything you palloc. (The <code class="function">config</code>
+ method is an exception: it should try to avoid leaking memory. But
+ usually the <code class="function">config</code> method need do nothing but assign
+ constants into the passed parameter struct.)
+ </p><p>
+ If the indexed column is of a collatable data type, the index collation
+ will be passed to all the support methods, using the standard
+ <code class="function">PG_GET_COLLATION()</code> mechanism.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist-implementation.html" title="69.4. Implementation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">69.2. Built-in Operator Classes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 69.4. Implementation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist-implementation.html b/doc/src/sgml/html/spgist-implementation.html
new file mode 100644
index 0000000..fb96869
--- /dev/null
+++ b/doc/src/sgml/html/spgist-implementation.html
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>69.4. Implementation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist-extensibility.html" title="69.3. Extensibility" /><link rel="next" href="spgist-examples.html" title="69.5. Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">69.4. Implementation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist-extensibility.html" title="69.3. Extensibility">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 69. SP-GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist-examples.html" title="69.5. Examples">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPGIST-IMPLEMENTATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">69.4. Implementation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-LIMITS">69.4.1. SP-GiST Limits</a></span></dt><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-NULL-LABELS">69.4.2. SP-GiST Without Node Labels</a></span></dt><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-ALL-THE-SAME">69.4.3. <span class="quote">“<span class="quote">All-the-Same</span>”</span> Inner Tuples</a></span></dt></dl></div><p>
+ This section covers implementation details and other tricks that are
+ useful for implementers of <acronym class="acronym">SP-GiST</acronym> operator classes to
+ know.
+ </p><div class="sect2" id="SPGIST-LIMITS"><div class="titlepage"><div><div><h3 class="title">69.4.1. SP-GiST Limits</h3></div></div></div><p>
+ Individual leaf tuples and inner tuples must fit on a single index page
+ (8kB by default). Therefore, when indexing values of variable-length
+ data types, long values can only be supported by methods such as radix
+ trees, in which each level of the tree includes a prefix that is short
+ enough to fit on a page, and the final leaf level includes a suffix also
+ short enough to fit on a page. The operator class should set
+ <code class="structfield">longValuesOK</code> to true only if it is prepared to arrange for
+ this to happen. Otherwise, the <acronym class="acronym">SP-GiST</acronym> core will
+ reject any request to index a value that is too large to fit
+ on an index page.
+ </p><p>
+ Likewise, it is the operator class's responsibility that inner tuples
+ do not grow too large to fit on an index page; this limits the number
+ of child nodes that can be used in one inner tuple, as well as the
+ maximum size of a prefix value.
+ </p><p>
+ Another limitation is that when an inner tuple's node points to a set
+ of leaf tuples, those tuples must all be in the same index page.
+ (This is a design decision to reduce seeking and save space in the
+ links that chain such tuples together.) If the set of leaf tuples
+ grows too large for a page, a split is performed and an intermediate
+ inner tuple is inserted. For this to fix the problem, the new inner
+ tuple <span class="emphasis"><em>must</em></span> divide the set of leaf values into more than one
+ node group. If the operator class's <code class="function">picksplit</code> function
+ fails to do that, the <acronym class="acronym">SP-GiST</acronym> core resorts to
+ extraordinary measures described in <a class="xref" href="spgist-implementation.html#SPGIST-ALL-THE-SAME" title="69.4.3. “All-the-Same” Inner Tuples">Section 69.4.3</a>.
+ </p><p>
+ When <code class="structfield">longValuesOK</code> is true, it is expected
+ that successive levels of the <acronym class="acronym">SP-GiST</acronym> tree will
+ absorb more and more information into the prefixes and node labels of
+ the inner tuples, making the required leaf datum smaller and smaller,
+ so that eventually it will fit on a page.
+ To prevent bugs in operator classes from causing infinite insertion
+ loops, the <acronym class="acronym">SP-GiST</acronym> core will raise an error if the
+ leaf datum does not become any smaller within ten cycles
+ of <code class="function">choose</code> method calls.
+ </p></div><div class="sect2" id="SPGIST-NULL-LABELS"><div class="titlepage"><div><div><h3 class="title">69.4.2. SP-GiST Without Node Labels</h3></div></div></div><p>
+ Some tree algorithms use a fixed set of nodes for each inner tuple;
+ for example, in a quad-tree there are always exactly four nodes
+ corresponding to the four quadrants around the inner tuple's centroid
+ point. In such a case the code typically works with the nodes by
+ number, and there is no need for explicit node labels. To suppress
+ node labels (and thereby save some space), the <code class="function">picksplit</code>
+ function can return NULL for the <code class="structfield">nodeLabels</code> array,
+ and likewise the <code class="function">choose</code> function can return NULL for
+ the <code class="structfield">prefixNodeLabels</code> array during
+ a <code class="literal">spgSplitTuple</code> action.
+ This will in turn result in <code class="structfield">nodeLabels</code> being NULL during
+ subsequent calls to <code class="function">choose</code> and <code class="function">inner_consistent</code>.
+ In principle, node labels could be used for some inner tuples and omitted
+ for others in the same index.
+ </p><p>
+ When working with an inner tuple having unlabeled nodes, it is an error
+ for <code class="function">choose</code> to return <code class="literal">spgAddNode</code>, since the set
+ of nodes is supposed to be fixed in such cases.
+ </p></div><div class="sect2" id="SPGIST-ALL-THE-SAME"><div class="titlepage"><div><div><h3 class="title">69.4.3. <span class="quote">“<span class="quote">All-the-Same</span>”</span> Inner Tuples</h3></div></div></div><p>
+ The <acronym class="acronym">SP-GiST</acronym> core can override the results of the
+ operator class's <code class="function">picksplit</code> function when
+ <code class="function">picksplit</code> fails to divide the supplied leaf values into
+ at least two node categories. When this happens, the new inner tuple
+ is created with multiple nodes that each have the same label (if any)
+ that <code class="function">picksplit</code> gave to the one node it did use, and the
+ leaf values are divided at random among these equivalent nodes.
+ The <code class="literal">allTheSame</code> flag is set on the inner tuple to warn the
+ <code class="function">choose</code> and <code class="function">inner_consistent</code> functions that the
+ tuple does not have the node set that they might otherwise expect.
+ </p><p>
+ When dealing with an <code class="literal">allTheSame</code> tuple, a <code class="function">choose</code>
+ result of <code class="literal">spgMatchNode</code> is interpreted to mean that the new
+ value can be assigned to any of the equivalent nodes; the core code will
+ ignore the supplied <code class="structfield">nodeN</code> value and descend into one
+ of the nodes at random (so as to keep the tree balanced). It is an
+ error for <code class="function">choose</code> to return <code class="literal">spgAddNode</code>, since
+ that would make the nodes not all equivalent; the
+ <code class="literal">spgSplitTuple</code> action must be used if the value to be inserted
+ doesn't match the existing nodes.
+ </p><p>
+ When dealing with an <code class="literal">allTheSame</code> tuple, the
+ <code class="function">inner_consistent</code> function should return either all or none
+ of the nodes as targets for continuing the index search, since they are
+ all equivalent. This may or may not require any special-case code,
+ depending on how much the <code class="function">inner_consistent</code> function normally
+ assumes about the meaning of the nodes.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist-extensibility.html" title="69.3. Extensibility">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist-examples.html" title="69.5. Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">69.3. Extensibility </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 69.5. Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist-intro.html b/doc/src/sgml/html/spgist-intro.html
new file mode 100644
index 0000000..b676795
--- /dev/null
+++ b/doc/src/sgml/html/spgist-intro.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>69.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spgist.html" title="Chapter 69. SP-GiST Indexes" /><link rel="next" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">69.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><th width="60%" align="center">Chapter 69. SP-GiST Indexes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPGIST-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">69.1. Introduction</h2></div></div></div><p>
+ <acronym class="acronym">SP-GiST</acronym> is an abbreviation for space-partitioned
+ <acronym class="acronym">GiST</acronym>. <acronym class="acronym">SP-GiST</acronym> supports partitioned
+ search trees, which facilitate development of a wide range of different
+ non-balanced data structures, such as quad-trees, k-d trees, and radix
+ trees (tries). The common feature of these structures is that they
+ repeatedly divide the search space into partitions that need not be
+ of equal size. Searches that are well matched to the partitioning rule
+ can be very fast.
+ </p><p>
+ These popular data structures were originally developed for in-memory
+ usage. In main memory, they are usually designed as a set of dynamically
+ allocated nodes linked by pointers. This is not suitable for direct
+ storing on disk, since these chains of pointers can be rather long which
+ would require too many disk accesses. In contrast, disk-based data
+ structures should have a high fanout to minimize I/O. The challenge
+ addressed by <acronym class="acronym">SP-GiST</acronym> is to map search tree nodes to
+ disk pages in such a way that a search need access only a few disk pages,
+ even if it traverses many nodes.
+ </p><p>
+ Like <acronym class="acronym">GiST</acronym>, <acronym class="acronym">SP-GiST</acronym> is meant to allow
+ the development of custom data types with the appropriate access methods,
+ by an expert in the domain of the data type, rather than a database expert.
+ </p><p>
+ Some of the information here is derived from Purdue University's
+ SP-GiST Indexing Project
+ <a class="ulink" href="https://www.cs.purdue.edu/spgist/" target="_top">web site</a>.
+ The <acronym class="acronym">SP-GiST</acronym> implementation in
+ <span class="productname">PostgreSQL</span> is primarily maintained by Teodor
+ Sigaev and Oleg Bartunov, and there is more information on their
+
+ <a class="ulink" href="http://www.sai.msu.su/~megera/wiki/spgist_dev" target="_top">web site</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist-builtin-opclasses.html" title="69.2. Built-in Operator Classes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 69. SP-GiST Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 69.2. Built-in Operator Classes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spgist.html b/doc/src/sgml/html/spgist.html
new file mode 100644
index 0000000..f504e43
--- /dev/null
+++ b/doc/src/sgml/html/spgist.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 69. SP-GiST Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gist-examples.html" title="68.5. Examples" /><link rel="next" href="spgist-intro.html" title="69.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 69. SP-GiST Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gist-examples.html" title="68.5. Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spgist-intro.html" title="69.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="SPGIST"><div class="titlepage"><div><div><h2 class="title">Chapter 69. SP-GiST Indexes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="spgist-intro.html">69.1. Introduction</a></span></dt><dt><span class="sect1"><a href="spgist-builtin-opclasses.html">69.2. Built-in Operator Classes</a></span></dt><dt><span class="sect1"><a href="spgist-extensibility.html">69.3. Extensibility</a></span></dt><dt><span class="sect1"><a href="spgist-implementation.html">69.4. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-LIMITS">69.4.1. SP-GiST Limits</a></span></dt><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-NULL-LABELS">69.4.2. SP-GiST Without Node Labels</a></span></dt><dt><span class="sect2"><a href="spgist-implementation.html#SPGIST-ALL-THE-SAME">69.4.3. <span class="quote">“<span class="quote">All-the-Same</span>”</span> Inner Tuples</a></span></dt></dl></dd><dt><span class="sect1"><a href="spgist-examples.html">69.5. Examples</a></span></dt></dl></div><a id="id-1.10.20.2" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gist-examples.html" title="68.5. Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spgist-intro.html" title="69.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">68.5. Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 69.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-examples.html b/doc/src/sgml/html/spi-examples.html
new file mode 100644
index 0000000..5f8e6aa
--- /dev/null
+++ b/doc/src/sgml/html/spi-examples.html
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.6. Examples</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-visibility.html" title="47.5. Visibility of Data Changes" /><link rel="next" href="bgworker.html" title="Chapter 48. Background Worker Processes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.6. Examples</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-visibility.html" title="47.5. Visibility of Data Changes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bgworker.html" title="Chapter 48. Background Worker Processes">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-EXAMPLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.6. Examples</h2></div></div></div><p>
+ This section contains a very simple example of SPI usage. The
+ C function <code class="function">execq</code> takes an SQL command as its
+ first argument and a row count as its second, executes the command
+ using <code class="function">SPI_exec</code> and returns the number of rows
+ that were processed by the command. You can find more complex
+ examples for SPI in the source tree in
+ <code class="filename">src/test/regress/regress.c</code> and in the
+ <a class="xref" href="contrib-spi.html" title="F.41. spi">spi</a> module.
+ </p><pre class="programlisting">
+#include "postgres.h"
+
+#include "executor/spi.h"
+#include "utils/builtins.h"
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(execq);
+
+Datum
+execq(PG_FUNCTION_ARGS)
+{
+ char *command;
+ int cnt;
+ int ret;
+ uint64 proc;
+
+ /* Convert given text object to a C string */
+ command = text_to_cstring(PG_GETARG_TEXT_PP(0));
+ cnt = PG_GETARG_INT32(1);
+
+ SPI_connect();
+
+ ret = SPI_exec(command, cnt);
+
+ proc = SPI_processed;
+
+ /*
+ * If some rows were fetched, print them via elog(INFO).
+ */
+ if (ret &gt; 0 &amp;&amp; SPI_tuptable != NULL)
+ {
+ SPITupleTable *tuptable = SPI_tuptable;
+ TupleDesc tupdesc = tuptable-&gt;tupdesc;
+ char buf[8192];
+ uint64 j;
+
+ for (j = 0; j &lt; tuptable-&gt;numvals; j++)
+ {
+ HeapTuple tuple = tuptable-&gt;vals[j];
+ int i;
+
+ for (i = 1, buf[0] = 0; i &lt;= tupdesc-&gt;natts; i++)
+ snprintf(buf + strlen(buf), sizeof(buf) - strlen(buf), " %s%s",
+ SPI_getvalue(tuple, tupdesc, i),
+ (i == tupdesc-&gt;natts) ? " " : " |");
+ elog(INFO, "EXECQ: %s", buf);
+ }
+ }
+
+ SPI_finish();
+ pfree(command);
+
+ PG_RETURN_INT64(proc);
+}
+</pre><p>
+ This is how you declare the function after having compiled it into
+ a shared library (details are in <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a>.):
+
+</p><pre class="programlisting">
+CREATE FUNCTION execq(text, integer) RETURNS int8
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C STRICT;
+</pre><p>
+ </p><p>
+ Here is a sample session:
+
+</p><pre class="programlisting">
+=&gt; SELECT execq('CREATE TABLE a (x integer)', 0);
+ execq
+-------
+ 0
+(1 row)
+
+=&gt; INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
+INSERT 0 1
+=&gt; SELECT execq('SELECT * FROM a', 0);
+INFO: EXECQ: 0 <em class="lineannotation"><span class="lineannotation">-- inserted by execq</span></em>
+INFO: EXECQ: 1 <em class="lineannotation"><span class="lineannotation">-- returned by execq and inserted by upper INSERT</span></em>
+
+ execq
+-------
+ 2
+(1 row)
+
+=&gt; SELECT execq('INSERT INTO a SELECT x + 2 FROM a RETURNING *', 1);
+INFO: EXECQ: 2 <em class="lineannotation"><span class="lineannotation">-- 0 + 2, then execution was stopped by count</span></em>
+ execq
+-------
+ 1
+(1 row)
+
+=&gt; SELECT execq('SELECT * FROM a', 10);
+INFO: EXECQ: 0
+INFO: EXECQ: 1
+INFO: EXECQ: 2
+
+ execq
+-------
+ 3 <em class="lineannotation"><span class="lineannotation">-- 10 is the max value only, 3 is the real number of rows</span></em>
+(1 row)
+
+=&gt; SELECT execq('INSERT INTO a SELECT x + 10 FROM a', 1);
+ execq
+-------
+ 3 <em class="lineannotation"><span class="lineannotation">-- all rows processed; count does not stop it, because nothing is returned</span></em>
+(1 row)
+
+=&gt; SELECT * FROM a;
+ x
+----
+ 0
+ 1
+ 2
+ 10
+ 11
+ 12
+(6 rows)
+
+=&gt; DELETE FROM a;
+DELETE 6
+=&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
+INSERT 0 1
+=&gt; SELECT * FROM a;
+ x
+---
+ 1 <em class="lineannotation"><span class="lineannotation">-- 0 (no rows in a) + 1</span></em>
+(1 row)
+
+=&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
+INFO: EXECQ: 1
+INSERT 0 1
+=&gt; SELECT * FROM a;
+ x
+---
+ 1
+ 2 <em class="lineannotation"><span class="lineannotation">-- 1 (there was one row in a) + 1</span></em>
+(2 rows)
+
+<em class="lineannotation"><span class="lineannotation">-- This demonstrates the data changes visibility rule.</span></em>
+<em class="lineannotation"><span class="lineannotation">-- execq is called twice and sees different numbers of rows each time:</span></em>
+
+=&gt; INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
+INFO: EXECQ: 1 <em class="lineannotation"><span class="lineannotation">-- results from first execq</span></em>
+INFO: EXECQ: 2
+INFO: EXECQ: 1 <em class="lineannotation"><span class="lineannotation">-- results from second execq</span></em>
+INFO: EXECQ: 2
+INFO: EXECQ: 2
+INSERT 0 2
+=&gt; SELECT * FROM a;
+ x
+---
+ 1
+ 2
+ 2 <em class="lineannotation"><span class="lineannotation">-- 2 rows * 1 (x in first row)</span></em>
+ 6 <em class="lineannotation"><span class="lineannotation">-- 3 rows (2 + 1 just inserted) * 2 (x in second row)</span></em>
+(4 rows)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-visibility.html" title="47.5. Visibility of Data Changes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bgworker.html" title="Chapter 48. Background Worker Processes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.5. Visibility of Data Changes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 48. Background Worker Processes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-interface-support.html b/doc/src/sgml/html/spi-interface-support.html
new file mode 100644
index 0000000..57d0af8
--- /dev/null
+++ b/doc/src/sgml/html/spi-interface-support.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.2. Interface Support Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data" /><link rel="next" href="spi-spi-fname.html" title="SPI_fname" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.2. Interface Support Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-fname.html" title="SPI_fname">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-INTERFACE-SUPPORT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.2. Interface Support Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="spi-spi-fname.html">SPI_fname</a></span><span class="refpurpose"> — determine the column name for the specified column number</span></dt><dt><span class="refentrytitle"><a href="spi-spi-fnumber.html">SPI_fnumber</a></span><span class="refpurpose"> — determine the column number for the specified column name</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getvalue.html">SPI_getvalue</a></span><span class="refpurpose"> — return the string value of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getbinval.html">SPI_getbinval</a></span><span class="refpurpose"> — return the binary value of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-gettype.html">SPI_gettype</a></span><span class="refpurpose"> — return the data type name of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-gettypeid.html">SPI_gettypeid</a></span><span class="refpurpose"> — return the data type <acronym class="acronym">OID</acronym> of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getrelname.html">SPI_getrelname</a></span><span class="refpurpose"> — return the name of the specified relation</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getnspname.html">SPI_getnspname</a></span><span class="refpurpose"> — return the namespace of the specified relation</span></dt><dt><span class="refentrytitle"><a href="spi-spi-result-code-string.html">SPI_result_code_string</a></span><span class="refpurpose"> — return error code as string</span></dt></dl></div><p>
+ The functions described here provide an interface for extracting
+ information from result sets returned by <code class="function">SPI_execute</code> and
+ other SPI functions.
+ </p><p>
+ All functions described in this section can be used by both
+ connected and unconnected C functions.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-fname.html" title="SPI_fname">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_register_trigger_data </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_fname</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-interface.html b/doc/src/sgml/html/spi-interface.html
new file mode 100644
index 0000000..4dc6b67
--- /dev/null
+++ b/doc/src/sgml/html/spi-interface.html
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.1. Interface Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi.html" title="Chapter 47. Server Programming Interface" /><link rel="next" href="spi-spi-connect.html" title="SPI_connect" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.1. Interface Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi.html" title="Chapter 47. Server Programming Interface">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-connect.html" title="SPI_connect">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-INTERFACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.1. Interface Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="spi-spi-connect.html">SPI_connect</a></span><span class="refpurpose"> — connect a C function to the SPI manager</span></dt><dt><span class="refentrytitle"><a href="spi-spi-finish.html">SPI_finish</a></span><span class="refpurpose"> — disconnect a C function from the SPI manager</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute.html">SPI_execute</a></span><span class="refpurpose"> — execute a command</span></dt><dt><span class="refentrytitle"><a href="spi-spi-exec.html">SPI_exec</a></span><span class="refpurpose"> — execute a read/write command</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-extended.html">SPI_execute_extended</a></span><span class="refpurpose"> — execute a command with out-of-line parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-with-args.html">SPI_execute_with_args</a></span><span class="refpurpose"> — execute a command with out-of-line parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare.html">SPI_prepare</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-cursor.html">SPI_prepare_cursor</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-extended.html">SPI_prepare_extended</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-params.html">SPI_prepare_params</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getargcount.html">SPI_getargcount</a></span><span class="refpurpose"> — return the number of arguments needed by a statement
+ prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-getargtypeid.html">SPI_getargtypeid</a></span><span class="refpurpose"> — return the data type OID for an argument of
+ a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-is-cursor-plan.html">SPI_is_cursor_plan</a></span><span class="refpurpose"> — return <code class="symbol">true</code> if a statement
+ prepared by <code class="function">SPI_prepare</code> can be used with
+ <code class="function">SPI_cursor_open</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan.html">SPI_execute_plan</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan-extended.html">SPI_execute_plan_extended</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan-with-paramlist.html">SPI_execute_plan_with_paramlist</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execp.html">SPI_execp</a></span><span class="refpurpose"> — execute a statement in read/write mode</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open.html">SPI_cursor_open</a></span><span class="refpurpose"> — set up a cursor using a statement created with <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open-with-args.html">SPI_cursor_open_with_args</a></span><span class="refpurpose"> — set up a cursor using a query and parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open-with-paramlist.html">SPI_cursor_open_with_paramlist</a></span><span class="refpurpose"> — set up a cursor using parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-parse-open.html">SPI_cursor_parse_open</a></span><span class="refpurpose"> — set up a cursor using a query string and parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-find.html">SPI_cursor_find</a></span><span class="refpurpose"> — find an existing cursor by name</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-fetch.html">SPI_cursor_fetch</a></span><span class="refpurpose"> — fetch some rows from a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-move.html">SPI_cursor_move</a></span><span class="refpurpose"> — move a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-scroll-cursor-fetch.html">SPI_scroll_cursor_fetch</a></span><span class="refpurpose"> — fetch some rows from a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-scroll-cursor-move.html">SPI_scroll_cursor_move</a></span><span class="refpurpose"> — move a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-close.html">SPI_cursor_close</a></span><span class="refpurpose"> — close a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-keepplan.html">SPI_keepplan</a></span><span class="refpurpose"> — save a prepared statement</span></dt><dt><span class="refentrytitle"><a href="spi-spi-saveplan.html">SPI_saveplan</a></span><span class="refpurpose"> — save a prepared statement</span></dt><dt><span class="refentrytitle"><a href="spi-spi-register-relation.html">SPI_register_relation</a></span><span class="refpurpose"> — make an ephemeral named relation available by name in SPI queries</span></dt><dt><span class="refentrytitle"><a href="spi-spi-unregister-relation.html">SPI_unregister_relation</a></span><span class="refpurpose"> — remove an ephemeral named relation from the registry</span></dt><dt><span class="refentrytitle"><a href="spi-spi-register-trigger-data.html">SPI_register_trigger_data</a></span><span class="refpurpose"> — make ephemeral trigger data available in SPI queries</span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi.html" title="Chapter 47. Server Programming Interface">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-connect.html" title="SPI_connect">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 47. Server Programming Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_connect</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-memory.html b/doc/src/sgml/html/spi-memory.html
new file mode 100644
index 0000000..4081783
--- /dev/null
+++ b/doc/src/sgml/html/spi-memory.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.3. Memory Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-result-code-string.html" title="SPI_result_code_string" /><link rel="next" href="spi-spi-palloc.html" title="SPI_palloc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.3. Memory Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-result-code-string.html" title="SPI_result_code_string">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-palloc.html" title="SPI_palloc">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-MEMORY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.3. Memory Management</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="spi-spi-palloc.html">SPI_palloc</a></span><span class="refpurpose"> — allocate memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-realloc.html">SPI_repalloc</a></span><span class="refpurpose"> — reallocate memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-pfree.html">SPI_pfree</a></span><span class="refpurpose"> — free memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-copytuple.html">SPI_copytuple</a></span><span class="refpurpose"> — make a copy of a row in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-returntuple.html">SPI_returntuple</a></span><span class="refpurpose"> — prepare to return a tuple as a Datum</span></dt><dt><span class="refentrytitle"><a href="spi-spi-modifytuple.html">SPI_modifytuple</a></span><span class="refpurpose"> — create a row by replacing selected fields of a given row</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freetuple.html">SPI_freetuple</a></span><span class="refpurpose"> — free a row allocated in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freetupletable.html">SPI_freetuptable</a></span><span class="refpurpose"> — free a row set created by <code class="function">SPI_execute</code> or a similar
+ function</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freeplan.html">SPI_freeplan</a></span><span class="refpurpose"> — free a previously saved prepared statement</span></dt></dl></div><p>
+ <a id="id-1.8.12.10.2.1" class="indexterm"></a>
+ <span class="productname">PostgreSQL</span> allocates memory within
+ <em class="firstterm">memory contexts</em>, which provide a convenient method of
+ managing allocations made in many different places that need to
+ live for differing amounts of time. Destroying a context releases
+ all the memory that was allocated in it. Thus, it is not necessary
+ to keep track of individual objects to avoid memory leaks; instead
+ only a relatively small number of contexts have to be managed.
+ <code class="function">palloc</code> and related functions allocate memory
+ from the <span class="quote">“<span class="quote">current</span>”</span> context.
+ </p><p>
+ <code class="function">SPI_connect</code> creates a new memory context and
+ makes it current. <code class="function">SPI_finish</code> restores the
+ previous current memory context and destroys the context created by
+ <code class="function">SPI_connect</code>. These actions ensure that
+ transient memory allocations made inside your C function are
+ reclaimed at C function exit, avoiding memory leakage.
+ </p><p>
+ However, if your C function needs to return an object in allocated
+ memory (such as a value of a pass-by-reference data type), you
+ cannot allocate that memory using <code class="function">palloc</code>, at
+ least not while you are connected to SPI. If you try, the object
+ will be deallocated by <code class="function">SPI_finish</code>, and your
+ C function will not work reliably. To solve this problem, use
+ <code class="function">SPI_palloc</code> to allocate memory for your return
+ object. <code class="function">SPI_palloc</code> allocates memory in the
+ <span class="quote">“<span class="quote">upper executor context</span>”</span>, that is, the memory context
+ that was current when <code class="function">SPI_connect</code> was called,
+ which is precisely the right context for a value returned from your
+ C function. Several of the other utility functions described in
+ this section also return objects created in the upper executor context.
+ </p><p>
+ When <code class="function">SPI_connect</code> is called, the private
+ context of the C function, which is created by
+ <code class="function">SPI_connect</code>, is made the current context. All
+ allocations made by <code class="function">palloc</code>,
+ <code class="function">repalloc</code>, or SPI utility functions (except as
+ described in this section) are made in this context. When a
+ C function disconnects from the SPI manager (via
+ <code class="function">SPI_finish</code>) the current context is restored to
+ the upper executor context, and all allocations made in the
+ C function memory context are freed and cannot be used any more.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-result-code-string.html" title="SPI_result_code_string">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-palloc.html" title="SPI_palloc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_result_code_string </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_palloc</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-realloc.html b/doc/src/sgml/html/spi-realloc.html
new file mode 100644
index 0000000..530ea69
--- /dev/null
+++ b/doc/src/sgml/html/spi-realloc.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_repalloc</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-palloc.html" title="SPI_palloc" /><link rel="next" href="spi-spi-pfree.html" title="SPI_pfree" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_repalloc</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-palloc.html" title="SPI_palloc">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-pfree.html" title="SPI_pfree">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-REALLOC"><div class="titlepage"></div><a id="id-1.8.12.10.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_repalloc</span></h2><p>SPI_repalloc — reallocate memory in the upper executor context</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void * SPI_repalloc(void * <em class="parameter"><code>pointer</code></em>, Size <em class="parameter"><code>size</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.7.5"><h2>Description</h2><p>
+ <code class="function">SPI_repalloc</code> changes the size of a memory
+ segment previously allocated using <code class="function">SPI_palloc</code>.
+ </p><p>
+ This function is no longer different from plain
+ <code class="function">repalloc</code>. It's kept just for backward
+ compatibility of existing code.
+ </p></div><div class="refsect1" id="id-1.8.12.10.7.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">void * <em class="parameter"><code>pointer</code></em></code></span></dt><dd><p>
+ pointer to existing storage to change
+ </p></dd><dt><span class="term"><code class="literal">Size <em class="parameter"><code>size</code></em></code></span></dt><dd><p>
+ size in bytes of storage to allocate
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.7.7"><h2>Return Value</h2><p>
+ pointer to new storage space of specified size with the contents
+ copied from the existing area
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-palloc.html" title="SPI_palloc">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-pfree.html" title="SPI_pfree">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_palloc </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_pfree</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-commit.html b/doc/src/sgml/html/spi-spi-commit.html
new file mode 100644
index 0000000..b857555
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-commit.html
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_commit</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-transaction.html" title="47.4. Transaction Management" /><link rel="next" href="spi-spi-rollback.html" title="SPI_rollback" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_commit</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-transaction.html" title="47.4. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><th width="60%" align="center">47.4. Transaction Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-rollback.html" title="SPI_rollback">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-COMMIT"><div class="titlepage"></div><a id="id-1.8.12.11.4.1" class="indexterm"></a><a id="id-1.8.12.11.4.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_commit</span></h2><p>SPI_commit, SPI_commit_and_chain — commit the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_commit(void)
+</pre><pre class="synopsis">
+void SPI_commit_and_chain(void)
+</pre></div><div class="refsect1" id="id-1.8.12.11.4.6"><h2>Description</h2><p>
+ <code class="function">SPI_commit</code> commits the current transaction. It is
+ approximately equivalent to running the SQL
+ command <code class="command">COMMIT</code>. After the transaction is committed, a
+ new transaction is automatically started using default transaction
+ characteristics, so that the caller can continue using SPI facilities.
+ If there is a failure during commit, the current transaction is instead
+ rolled back and a new transaction is started, after which the error is
+ thrown in the usual way.
+ </p><p>
+ <code class="function">SPI_commit_and_chain</code> is the same, but the new
+ transaction is started with the same transaction
+ characteristics as the just finished one, like with the SQL command
+ <code class="command">COMMIT AND CHAIN</code>.
+ </p><p>
+ These functions can only be executed if the SPI connection has been set as
+ nonatomic in the call to <code class="function">SPI_connect_ext</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-transaction.html" title="47.4. Transaction Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-rollback.html" title="SPI_rollback">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.4. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_rollback</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-connect.html b/doc/src/sgml/html/spi-spi-connect.html
new file mode 100644
index 0000000..f657819
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-connect.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_connect</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-interface.html" title="47.1. Interface Functions" /><link rel="next" href="spi-spi-finish.html" title="SPI_finish" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_connect</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-interface.html" title="47.1. Interface Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-finish.html" title="SPI_finish">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CONNECT"><div class="titlepage"></div><a id="id-1.8.12.8.2.1" class="indexterm"></a><a id="id-1.8.12.8.2.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_connect</span></h2><p>SPI_connect, SPI_connect_ext — connect a C function to the SPI manager</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_connect(void)
+</pre><pre class="synopsis">
+int SPI_connect_ext(int <em class="parameter"><code>options</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.2.6"><h2>Description</h2><p>
+ <code class="function">SPI_connect</code> opens a connection from a
+ C function invocation to the SPI manager. You must call this
+ function if you want to execute commands through SPI. Some utility
+ SPI functions can be called from unconnected C functions.
+ </p><p>
+ <code class="function">SPI_connect_ext</code> does the same but has an argument that
+ allows passing option flags. Currently, the following option values are
+ available:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OPT_NONATOMIC</code></span></dt><dd><p>
+ Sets the SPI connection to be <em class="firstterm">nonatomic</em>, which
+ means that transaction control calls (<code class="function">SPI_commit</code>,
+ <code class="function">SPI_rollback</code>) are allowed. Otherwise,
+ calling those functions will result in an immediate error.
+ </p></dd></dl></div><p>
+ </p><p>
+ <code class="literal">SPI_connect()</code> is equivalent to
+ <code class="literal">SPI_connect_ext(0)</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.2.7"><h2>Return Value</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_CONNECT</code></span></dt><dd><p>
+ on success
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_CONNECT</code></span></dt><dd><p>
+ on error
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-interface.html" title="47.1. Interface Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-finish.html" title="SPI_finish">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.1. Interface Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_finish</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-copytuple.html b/doc/src/sgml/html/spi-spi-copytuple.html
new file mode 100644
index 0000000..2ebb159
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-copytuple.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_copytuple</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-pfree.html" title="SPI_pfree" /><link rel="next" href="spi-spi-returntuple.html" title="SPI_returntuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_copytuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-pfree.html" title="SPI_pfree">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-returntuple.html" title="SPI_returntuple">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-COPYTUPLE"><div class="titlepage"></div><a id="id-1.8.12.10.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_copytuple</span></h2><p>SPI_copytuple — make a copy of a row in the upper executor context</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+HeapTuple SPI_copytuple(HeapTuple <em class="parameter"><code>row</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.9.5"><h2>Description</h2><p>
+ <code class="function">SPI_copytuple</code> makes a copy of a row in the
+ upper executor context. This is normally used to return a modified
+ row from a trigger. In a function declared to return a composite
+ type, use <code class="function">SPI_returntuple</code> instead.
+ </p><p>
+ This function can only be used while connected to SPI.
+ Otherwise, it returns NULL and sets <code class="varname">SPI_result</code> to
+ <code class="symbol">SPI_ERROR_UNCONNECTED</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.10.9.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ row to be copied
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.9.7"><h2>Return Value</h2><p>
+ the copied row, or <code class="symbol">NULL</code> on error
+ (see <code class="varname">SPI_result</code> for an error indication)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-pfree.html" title="SPI_pfree">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-returntuple.html" title="SPI_returntuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_pfree </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_returntuple</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-close.html b/doc/src/sgml/html/spi-spi-cursor-close.html
new file mode 100644
index 0000000..14c6fd2
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-close.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_close</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move" /><link rel="next" href="spi-spi-keepplan.html" title="SPI_keepplan" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_close</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-keepplan.html" title="SPI_keepplan">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-CLOSE"><div class="titlepage"></div><a id="id-1.8.12.8.28.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_close</span></h2><p>SPI_cursor_close — close a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_cursor_close(Portal <em class="parameter"><code>portal</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.28.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_close</code> closes a previously created
+ cursor and releases its portal storage.
+ </p><p>
+ All open cursors are closed automatically at the end of a
+ transaction. <code class="function">SPI_cursor_close</code> need only be
+ invoked if it is desirable to release resources sooner.
+ </p></div><div class="refsect1" id="id-1.8.12.8.28.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Portal <em class="parameter"><code>portal</code></em></code></span></dt><dd><p>
+ portal containing the cursor
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-keepplan.html" title="SPI_keepplan">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_scroll_cursor_move </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_keepplan</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-fetch.html b/doc/src/sgml/html/spi-spi-cursor-fetch.html
new file mode 100644
index 0000000..a47f8a4
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-fetch.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_fetch</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-find.html" title="SPI_cursor_find" /><link rel="next" href="spi-spi-cursor-move.html" title="SPI_cursor_move" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_fetch</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-move.html" title="SPI_cursor_move">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-FETCH"><div class="titlepage"></div><a id="id-1.8.12.8.24.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_fetch</span></h2><p>SPI_cursor_fetch — fetch some rows from a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_cursor_fetch(Portal <em class="parameter"><code>portal</code></em>, bool <em class="parameter"><code>forward</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.24.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_fetch</code> fetches some rows from a
+ cursor. This is equivalent to a subset of the SQL command
+ <code class="command">FETCH</code> (see <code class="function">SPI_scroll_cursor_fetch</code>
+ for more functionality).
+ </p></div><div class="refsect1" id="id-1.8.12.8.24.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Portal <em class="parameter"><code>portal</code></em></code></span></dt><dd><p>
+ portal containing the cursor
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>forward</code></em></code></span></dt><dd><p>
+ true for fetch forward, false for fetch backward
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to fetch
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.24.7"><h2>Return Value</h2><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code> if successful.
+ </p></div><div class="refsect1" id="id-1.8.12.8.24.8"><h2>Notes</h2><p>
+ Fetching backward may fail if the cursor's plan was not created
+ with the <code class="symbol">CURSOR_OPT_SCROLL</code> option.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-move.html" title="SPI_cursor_move">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_find </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_move</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-find.html b/doc/src/sgml/html/spi-spi-cursor-find.html
new file mode 100644
index 0000000..d3a19f3
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-find.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_find</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open" /><link rel="next" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_find</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-FIND"><div class="titlepage"></div><a id="id-1.8.12.8.23.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_find</span></h2><p>SPI_cursor_find — find an existing cursor by name</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Portal SPI_cursor_find(const char * <em class="parameter"><code>name</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.23.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_find</code> finds an existing portal by
+ name. This is primarily useful to resolve a cursor name returned
+ as text by some other function.
+ </p></div><div class="refsect1" id="id-1.8.12.8.23.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ name of the portal
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.23.7"><h2>Return Value</h2><p>
+ pointer to the portal with the specified name, or
+ <code class="symbol">NULL</code> if none was found
+ </p></div><div class="refsect1" id="id-1.8.12.8.23.8"><h2>Notes</h2><p>
+ Beware that this function can return a <code class="type">Portal</code> object
+ that does not have cursor-like properties; for example it might not
+ return tuples. If you simply pass the <code class="type">Portal</code> pointer
+ to other SPI functions, they can defend themselves against such
+ cases, but caution is appropriate when directly inspecting
+ the <code class="type">Portal</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_parse_open </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_fetch</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-move.html b/doc/src/sgml/html/spi-spi-cursor-move.html
new file mode 100644
index 0000000..6d6f419
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-move.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_move</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch" /><link rel="next" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_move</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-MOVE"><div class="titlepage"></div><a id="id-1.8.12.8.25.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_move</span></h2><p>SPI_cursor_move — move a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_cursor_move(Portal <em class="parameter"><code>portal</code></em>, bool <em class="parameter"><code>forward</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.25.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_move</code> skips over some number of rows
+ in a cursor. This is equivalent to a subset of the SQL command
+ <code class="command">MOVE</code> (see <code class="function">SPI_scroll_cursor_move</code>
+ for more functionality).
+ </p></div><div class="refsect1" id="id-1.8.12.8.25.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Portal <em class="parameter"><code>portal</code></em></code></span></dt><dd><p>
+ portal containing the cursor
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>forward</code></em></code></span></dt><dd><p>
+ true for move forward, false for move backward
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to move
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.25.7"><h2>Notes</h2><p>
+ Moving backward may fail if the cursor's plan was not created
+ with the <code class="symbol">CURSOR_OPT_SCROLL</code> option.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-fetch.html" title="SPI_cursor_fetch">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_fetch </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_scroll_cursor_fetch</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-open-with-args.html b/doc/src/sgml/html/spi-spi-cursor-open-with-args.html
new file mode 100644
index 0000000..e02a37d
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-open-with-args.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_open_with_args</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-open.html" title="SPI_cursor_open" /><link rel="next" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_open_with_args</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-open.html" title="SPI_cursor_open">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-OPEN-WITH-ARGS"><div class="titlepage"></div><a id="id-1.8.12.8.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_open_with_args</span></h2><p>SPI_cursor_open_with_args — set up a cursor using a query and parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Portal SPI_cursor_open_with_args(const char *<em class="parameter"><code>name</code></em>,
+ const char *<em class="parameter"><code>command</code></em>,
+ int <em class="parameter"><code>nargs</code></em>, Oid *<em class="parameter"><code>argtypes</code></em>,
+ Datum *<em class="parameter"><code>values</code></em>, const char *<em class="parameter"><code>nulls</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>, int <em class="parameter"><code>cursorOptions</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.20.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_open_with_args</code> sets up a cursor
+ (internally, a portal) that will execute the specified query.
+ Most of the parameters have the same meanings as the corresponding
+ parameters to <code class="function">SPI_prepare_cursor</code>
+ and <code class="function">SPI_cursor_open</code>.
+ </p><p>
+ For one-time query execution, this function should be preferred
+ over <code class="function">SPI_prepare_cursor</code> followed by
+ <code class="function">SPI_cursor_open</code>.
+ If the same command is to be executed with many different parameters,
+ either method might be faster, depending on the cost of re-planning
+ versus the benefit of custom plans.
+ </p><p>
+ The passed-in parameter data will be copied into the cursor's portal, so it
+ can be freed while the cursor still exists.
+ </p><p>
+ This function is now deprecated in favor
+ of <code class="function">SPI_cursor_parse_open</code>, which provides equivalent
+ functionality using a more modern API for handling query parameters.
+ </p></div><div class="refsect1" id="id-1.8.12.8.20.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ name for portal, or <code class="symbol">NULL</code> to let the system
+ select a name
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>nargs</code></em></code></span></dt><dd><p>
+ number of input parameters (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.)
+ </p></dd><dt><span class="term"><code class="literal">Oid * <em class="parameter"><code>argtypes</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, containing the
+ <acronym class="acronym">OID</acronym>s of the data types of the parameters
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, containing the actual
+ parameter values
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, describing which
+ parameters are null
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_cursor_open_with_args</code> assumes that no parameters
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding parameter
+ value is non-null, or <code class="literal">'n'</code> if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding <em class="parameter"><code>values</code></em> entry doesn't matter.) Note
+ that <em class="parameter"><code>nulls</code></em> is not a text string, just an array:
+ it does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
+ integer bit mask of cursor options; zero produces default behavior
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.20.7"><h2>Return Value</h2><p>
+ Pointer to portal containing the cursor. Note there is no error
+ return convention; any error will be reported via <code class="function">elog</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-open.html" title="SPI_cursor_open">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_open </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_open_with_paramlist</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-open-with-paramlist.html b/doc/src/sgml/html/spi-spi-cursor-open-with-paramlist.html
new file mode 100644
index 0000000..1fb599a
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-open-with-paramlist.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_open_with_paramlist</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args" /><link rel="next" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_open_with_paramlist</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-OPEN-WITH-PARAMLIST"><div class="titlepage"></div><a id="id-1.8.12.8.21.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_open_with_paramlist</span></h2><p>SPI_cursor_open_with_paramlist — set up a cursor using parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Portal SPI_cursor_open_with_paramlist(const char *<em class="parameter"><code>name</code></em>,
+ SPIPlanPtr <em class="parameter"><code>plan</code></em>,
+ ParamListInfo <em class="parameter"><code>params</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.21.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_open_with_paramlist</code> sets up a cursor
+ (internally, a portal) that will execute a statement prepared by
+ <code class="function">SPI_prepare</code>.
+ This function is equivalent to <code class="function">SPI_cursor_open</code>
+ except that information about the parameter values to be passed to the
+ query is presented differently. The <code class="literal">ParamListInfo</code>
+ representation can be convenient for passing down values that are
+ already available in that format. It also supports use of dynamic
+ parameter sets via hook functions specified in <code class="literal">ParamListInfo</code>.
+ </p><p>
+ The passed-in parameter data will be copied into the cursor's portal, so it
+ can be freed while the cursor still exists.
+ </p></div><div class="refsect1" id="id-1.8.12.8.21.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ name for portal, or <code class="symbol">NULL</code> to let the system
+ select a name
+ </p></dd><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
+ data structure containing parameter types and values; NULL if none
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.21.7"><h2>Return Value</h2><p>
+ Pointer to portal containing the cursor. Note there is no error
+ return convention; any error will be reported via <code class="function">elog</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-parse-open.html" title="SPI_cursor_parse_open">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_open_with_args </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_parse_open</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-open.html b/doc/src/sgml/html/spi-spi-cursor-open.html
new file mode 100644
index 0000000..ec028a9
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-open.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_open</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execp.html" title="SPI_execp" /><link rel="next" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_open</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execp.html" title="SPI_execp">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-OPEN"><div class="titlepage"></div><a id="id-1.8.12.8.19.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_open</span></h2><p>SPI_cursor_open — set up a cursor using a statement created with <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Portal SPI_cursor_open(const char * <em class="parameter"><code>name</code></em>, SPIPlanPtr <em class="parameter"><code>plan</code></em>,
+ Datum * <em class="parameter"><code>values</code></em>, const char * <em class="parameter"><code>nulls</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.19.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_open</code> sets up a cursor (internally,
+ a portal) that will execute a statement prepared by
+ <code class="function">SPI_prepare</code>. The parameters have the same
+ meanings as the corresponding parameters to
+ <code class="function">SPI_execute_plan</code>.
+ </p><p>
+ Using a cursor instead of executing the statement directly has two
+ benefits. First, the result rows can be retrieved a few at a time,
+ avoiding memory overrun for queries that return many rows. Second,
+ a portal can outlive the current C function (it can, in fact, live
+ to the end of the current transaction). Returning the portal name
+ to the C function's caller provides a way of returning a row set as
+ result.
+ </p><p>
+ The passed-in parameter data will be copied into the cursor's portal, so it
+ can be freed while the cursor still exists.
+ </p></div><div class="refsect1" id="id-1.8.12.8.19.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ name for portal, or <code class="symbol">NULL</code> to let the system
+ select a name
+ </p></dd><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ An array of actual parameter values. Must have same length as the
+ statement's number of arguments.
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ An array describing which parameters are null. Must have same length as
+ the statement's number of arguments.
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_cursor_open</code> assumes that no parameters
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding parameter
+ value is non-null, or <code class="literal">'n'</code> if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding <em class="parameter"><code>values</code></em> entry doesn't matter.) Note
+ that <em class="parameter"><code>nulls</code></em> is not a text string, just an array:
+ it does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.19.7"><h2>Return Value</h2><p>
+ Pointer to portal containing the cursor. Note there is no error
+ return convention; any error will be reported via <code class="function">elog</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execp.html" title="SPI_execp">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-open-with-args.html" title="SPI_cursor_open_with_args">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execp </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_open_with_args</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-cursor-parse-open.html b/doc/src/sgml/html/spi-spi-cursor-parse-open.html
new file mode 100644
index 0000000..2cdad11
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-cursor-parse-open.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_cursor_parse_open</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist" /><link rel="next" href="spi-spi-cursor-find.html" title="SPI_cursor_find" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_parse_open</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-PARSE-OPEN"><div class="titlepage"></div><a id="id-1.8.12.8.22.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_parse_open</span></h2><p>SPI_cursor_parse_open — set up a cursor using a query string and parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Portal SPI_cursor_parse_open(const char *<em class="parameter"><code>name</code></em>,
+ const char *<em class="parameter"><code>command</code></em>,
+ const SPIParseOpenOptions * <em class="parameter"><code>options</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.22.5"><h2>Description</h2><p>
+ <code class="function">SPI_cursor_parse_open</code> sets up a cursor
+ (internally, a portal) that will execute the specified query string.
+ This is comparable to <code class="function">SPI_prepare_cursor</code> followed
+ by <code class="function">SPI_cursor_open_with_paramlist</code>, except that
+ parameter references within the query string are handled entirely by
+ supplying a <code class="literal">ParamListInfo</code> object.
+ </p><p>
+ For one-time query execution, this function should be preferred
+ over <code class="function">SPI_prepare_cursor</code> followed by
+ <code class="function">SPI_cursor_open_with_paramlist</code>.
+ If the same command is to be executed with many different parameters,
+ either method might be faster, depending on the cost of re-planning
+ versus the benefit of custom plans.
+ </p><p>
+ The <em class="parameter"><code>options-&gt;params</code></em> object should normally
+ mark each parameter with the <code class="literal">PARAM_FLAG_CONST</code> flag,
+ since a one-shot plan is always used for the query.
+ </p><p>
+ The passed-in parameter data will be copied into the cursor's portal, so it
+ can be freed while the cursor still exists.
+ </p></div><div class="refsect1" id="id-1.8.12.8.22.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ name for portal, or <code class="symbol">NULL</code> to let the system
+ select a name
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">const SPIParseOpenOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
+ struct containing optional arguments
+ </p></dd></dl></div><p>
+ Callers should always zero out the entire <em class="parameter"><code>options</code></em>
+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available <em class="parameter"><code>options</code></em> fields are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
+ data structure containing query parameter types and values; NULL if none
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
+ integer bit mask of cursor options; zero produces default behavior
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.22.7"><h2>Return Value</h2><p>
+ Pointer to portal containing the cursor. Note there is no error
+ return convention; any error will be reported via <code class="function">elog</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_open_with_paramlist </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_find</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-exec.html b/doc/src/sgml/html/spi-spi-exec.html
new file mode 100644
index 0000000..ae5ad01
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-exec.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_exec</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute.html" title="SPI_execute" /><link rel="next" href="spi-spi-execute-extended.html" title="SPI_execute_extended" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_exec</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute.html" title="SPI_execute">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-extended.html" title="SPI_execute_extended">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXEC"><div class="titlepage"></div><a id="id-1.8.12.8.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_exec</span></h2><p>SPI_exec — execute a read/write command</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_exec(const char * <em class="parameter"><code>command</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.5.5"><h2>Description</h2><p>
+ <code class="function">SPI_exec</code> is the same as
+ <code class="function">SPI_execute</code>, with the latter's
+ <em class="parameter"><code>read_only</code></em> parameter always taken as
+ <code class="literal">false</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.5.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ string containing command to execute
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.5.7"><h2>Return Value</h2><p>
+ See <code class="function">SPI_execute</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute.html" title="SPI_execute">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-extended.html" title="SPI_execute_extended">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_extended</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execp.html b/doc/src/sgml/html/spi-spi-execp.html
new file mode 100644
index 0000000..23faf7b
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execp.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execp</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist" /><link rel="next" href="spi-spi-cursor-open.html" title="SPI_cursor_open" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execp</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-open.html" title="SPI_cursor_open">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECP"><div class="titlepage"></div><a id="id-1.8.12.8.18.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execp</span></h2><p>SPI_execp — execute a statement in read/write mode</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execp(SPIPlanPtr <em class="parameter"><code>plan</code></em>, Datum * <em class="parameter"><code>values</code></em>, const char * <em class="parameter"><code>nulls</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.18.5"><h2>Description</h2><p>
+ <code class="function">SPI_execp</code> is the same as
+ <code class="function">SPI_execute_plan</code>, with the latter's
+ <em class="parameter"><code>read_only</code></em> parameter always taken as
+ <code class="literal">false</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.18.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ An array of actual parameter values. Must have same length as the
+ statement's number of arguments.
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ An array describing which parameters are null. Must have same length as
+ the statement's number of arguments.
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_execp</code> assumes that no parameters
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding parameter
+ value is non-null, or <code class="literal">'n'</code> if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding <em class="parameter"><code>values</code></em> entry doesn't matter.) Note
+ that <em class="parameter"><code>nulls</code></em> is not a text string, just an array:
+ it does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.18.7"><h2>Return Value</h2><p>
+ See <code class="function">SPI_execute_plan</code>.
+ </p><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code> if successful.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-open.html" title="SPI_cursor_open">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_plan_with_paramlist </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_open</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute-extended.html b/doc/src/sgml/html/spi-spi-execute-extended.html
new file mode 100644
index 0000000..3f59e37
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute-extended.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_extended</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-exec.html" title="SPI_exec" /><link rel="next" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_extended</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-exec.html" title="SPI_exec">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-EXTENDED"><div class="titlepage"></div><a id="id-1.8.12.8.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_extended</span></h2><p>SPI_execute_extended — execute a command with out-of-line parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute_extended(const char *<em class="parameter"><code>command</code></em>,
+ const SPIExecuteOptions * <em class="parameter"><code>options</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.6.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute_extended</code> executes a command that might
+ include references to externally supplied parameters. The command text
+ refers to a parameter as <code class="literal">$<em class="replaceable"><code>n</code></em></code>,
+ and the <em class="parameter"><code>options-&gt;params</code></em> object (if supplied)
+ provides values and type information for each such symbol.
+ Various execution options can be specified
+ in the <em class="parameter"><code>options</code></em> struct, too.
+ </p><p>
+ The <em class="parameter"><code>options-&gt;params</code></em> object should normally
+ mark each parameter with the <code class="literal">PARAM_FLAG_CONST</code> flag,
+ since a one-shot plan is always used for the query.
+ </p><p>
+ If <em class="parameter"><code>options-&gt;dest</code></em> is not NULL, then result
+ tuples are passed to that object as they are generated by the executor,
+ instead of being accumulated in <code class="varname">SPI_tuptable</code>. Using
+ a caller-supplied <code class="literal">DestReceiver</code> object is particularly
+ helpful for queries that might generate many tuples, since the data can
+ be processed on-the-fly instead of being accumulated in memory.
+ </p></div><div class="refsect1" id="id-1.8.12.8.6.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">const SPIExecuteOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
+ struct containing optional arguments
+ </p></dd></dl></div><p>
+ Callers should always zero out the entire <em class="parameter"><code>options</code></em>
+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available <em class="parameter"><code>options</code></em> fields are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
+ data structure containing query parameter types and values; NULL if none
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>allow_nonatomic</code></em></code></span></dt><dd><p>
+ <code class="literal">true</code> allows non-atomic execution of CALL and DO
+ statements
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>must_return_tuples</code></em></code></span></dt><dd><p>
+ if <code class="literal">true</code>, raise error if the query is not of a kind
+ that returns tuples (this does not forbid the case where it happens to
+ return zero tuples)
+ </p></dd><dt><span class="term"><code class="literal">uint64 <em class="parameter"><code>tcount</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd><dt><span class="term"><code class="literal">DestReceiver * <em class="parameter"><code>dest</code></em></code></span></dt><dd><p>
+ <code class="literal">DestReceiver</code> object that will receive any tuples
+ emitted by the query; if NULL, result tuples are accumulated into
+ a <code class="varname">SPI_tuptable</code> structure, as
+ in <code class="function">SPI_execute</code>
+ </p></dd><dt><span class="term"><code class="literal">ResourceOwner <em class="parameter"><code>owner</code></em></code></span></dt><dd><p>
+ This field is present for consistency
+ with <code class="function">SPI_execute_plan_extended</code>, but it is
+ ignored, since the plan used
+ by <code class="function">SPI_execute_extended</code> is never saved.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.6.7"><h2>Return Value</h2><p>
+ The return value is the same as for <code class="function">SPI_execute</code>.
+ </p><p>
+ When <em class="parameter"><code>options-&gt;dest</code></em> is NULL,
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code>.
+ When <em class="parameter"><code>options-&gt;dest</code></em> is not NULL,
+ <code class="varname">SPI_processed</code> is set to zero and
+ <code class="varname">SPI_tuptable</code> is set to NULL. If a tuple count
+ is required, the caller's <code class="literal">DestReceiver</code> object must
+ calculate it.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-exec.html" title="SPI_exec">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_exec </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_with_args</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute-plan-extended.html b/doc/src/sgml/html/spi-spi-execute-plan-extended.html
new file mode 100644
index 0000000..05a2463
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute-plan-extended.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_plan_extended</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-plan.html" title="SPI_execute_plan" /><link rel="next" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_plan_extended</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-PLAN-EXTENDED"><div class="titlepage"></div><a id="id-1.8.12.8.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_plan_extended</span></h2><p>SPI_execute_plan_extended — execute a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute_plan_extended(SPIPlanPtr <em class="parameter"><code>plan</code></em>,
+ const SPIExecuteOptions * <em class="parameter"><code>options</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.16.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute_plan_extended</code> executes a statement
+ prepared by <code class="function">SPI_prepare</code> or one of its siblings.
+ This function is equivalent to <code class="function">SPI_execute_plan</code>,
+ except that information about the parameter values to be passed to the
+ query is presented differently, and additional execution-controlling
+ options can be passed.
+ </p><p>
+ Query parameter values are represented by
+ a <code class="literal">ParamListInfo</code> struct, which is convenient for passing
+ down values that are already available in that format. Dynamic parameter
+ sets can also be used, via hook functions specified
+ in <code class="literal">ParamListInfo</code>.
+ </p><p>
+ Also, instead of always accumulating the result tuples into a
+ <code class="varname">SPI_tuptable</code> structure, tuples can be passed to a
+ caller-supplied <code class="literal">DestReceiver</code> object as they are
+ generated by the executor. This is particularly helpful for queries
+ that might generate many tuples, since the data can be processed
+ on-the-fly instead of being accumulated in memory.
+ </p></div><div class="refsect1" id="id-1.8.12.8.16.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">const SPIExecuteOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
+ struct containing optional arguments
+ </p></dd></dl></div><p>
+ Callers should always zero out the entire <em class="parameter"><code>options</code></em>
+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available <em class="parameter"><code>options</code></em> fields are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
+ data structure containing query parameter types and values; NULL if none
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>allow_nonatomic</code></em></code></span></dt><dd><p>
+ <code class="literal">true</code> allows non-atomic execution of CALL and DO
+ statements
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>must_return_tuples</code></em></code></span></dt><dd><p>
+ if <code class="literal">true</code>, raise error if the query is not of a kind
+ that returns tuples (this does not forbid the case where it happens to
+ return zero tuples)
+ </p></dd><dt><span class="term"><code class="literal">uint64 <em class="parameter"><code>tcount</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd><dt><span class="term"><code class="literal">DestReceiver * <em class="parameter"><code>dest</code></em></code></span></dt><dd><p>
+ <code class="literal">DestReceiver</code> object that will receive any tuples
+ emitted by the query; if NULL, result tuples are accumulated into
+ a <code class="varname">SPI_tuptable</code> structure, as
+ in <code class="function">SPI_execute_plan</code>
+ </p></dd><dt><span class="term"><code class="literal">ResourceOwner <em class="parameter"><code>owner</code></em></code></span></dt><dd><p>
+ The resource owner that will hold a reference count on the plan while
+ it is executed. If NULL, CurrentResourceOwner is used. Ignored for
+ non-saved plans, as SPI does not acquire reference counts on those.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.16.7"><h2>Return Value</h2><p>
+ The return value is the same as for <code class="function">SPI_execute_plan</code>.
+ </p><p>
+ When <em class="parameter"><code>options-&gt;dest</code></em> is NULL,
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute_plan</code>.
+ When <em class="parameter"><code>options-&gt;dest</code></em> is not NULL,
+ <code class="varname">SPI_processed</code> is set to zero and
+ <code class="varname">SPI_tuptable</code> is set to NULL. If a tuple count
+ is required, the caller's <code class="literal">DestReceiver</code> object must
+ calculate it.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_plan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_plan_with_paramlist</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute-plan-with-paramlist.html b/doc/src/sgml/html/spi-spi-execute-plan-with-paramlist.html
new file mode 100644
index 0000000..6c8a625
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute-plan-with-paramlist.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_plan_with_paramlist</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended" /><link rel="next" href="spi-spi-execp.html" title="SPI_execp" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_plan_with_paramlist</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execp.html" title="SPI_execp">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-PLAN-WITH-PARAMLIST"><div class="titlepage"></div><a id="id-1.8.12.8.17.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_plan_with_paramlist</span></h2><p>SPI_execute_plan_with_paramlist — execute a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute_plan_with_paramlist(SPIPlanPtr <em class="parameter"><code>plan</code></em>,
+ ParamListInfo <em class="parameter"><code>params</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>,
+ long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.17.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute_plan_with_paramlist</code> executes a statement
+ prepared by <code class="function">SPI_prepare</code>.
+ This function is equivalent to <code class="function">SPI_execute_plan</code>
+ except that information about the parameter values to be passed to the
+ query is presented differently. The <code class="literal">ParamListInfo</code>
+ representation can be convenient for passing down values that are
+ already available in that format. It also supports use of dynamic
+ parameter sets via hook functions specified in <code class="literal">ParamListInfo</code>.
+ </p><p>
+ This function is now deprecated in favor
+ of <code class="function">SPI_execute_plan_extended</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.17.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
+ data structure containing parameter types and values; NULL if none
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.17.7"><h2>Return Value</h2><p>
+ The return value is the same as for <code class="function">SPI_execute_plan</code>.
+ </p><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute_plan</code> if successful.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execp.html" title="SPI_execp">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_plan_extended </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execp</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute-plan.html b/doc/src/sgml/html/spi-spi-execute-plan.html
new file mode 100644
index 0000000..05b4a45
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute-plan.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_plan</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan" /><link rel="next" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_plan</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-PLAN"><div class="titlepage"></div><a id="id-1.8.12.8.15.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_plan</span></h2><p>SPI_execute_plan — execute a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute_plan(SPIPlanPtr <em class="parameter"><code>plan</code></em>, Datum * <em class="parameter"><code>values</code></em>, const char * <em class="parameter"><code>nulls</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.15.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute_plan</code> executes a statement prepared by
+ <code class="function">SPI_prepare</code> or one of its siblings.
+ <em class="parameter"><code>read_only</code></em> and
+ <em class="parameter"><code>count</code></em> have the same interpretation as in
+ <code class="function">SPI_execute</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.15.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ An array of actual parameter values. Must have same length as the
+ statement's number of arguments.
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ An array describing which parameters are null. Must have same length as
+ the statement's number of arguments.
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_execute_plan</code> assumes that no parameters
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding parameter
+ value is non-null, or <code class="literal">'n'</code> if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding <em class="parameter"><code>values</code></em> entry doesn't matter.) Note
+ that <em class="parameter"><code>nulls</code></em> is not a text string, just an array:
+ it does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.15.7"><h2>Return Value</h2><p>
+ The return value is the same as for <code class="function">SPI_execute</code>,
+ with the following additional possible error (negative) results:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>plan</code></em> is <code class="symbol">NULL</code> or invalid,
+ or <em class="parameter"><code>count</code></em> is less than 0
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_PARAM</code></span></dt><dd><p>
+ if <em class="parameter"><code>values</code></em> is <code class="symbol">NULL</code> and
+ <em class="parameter"><code>plan</code></em> was prepared with some parameters
+ </p></dd></dl></div><p>
+ </p><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code> if successful.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-extended.html" title="SPI_execute_plan_extended">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_is_cursor_plan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_plan_extended</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute-with-args.html b/doc/src/sgml/html/spi-spi-execute-with-args.html
new file mode 100644
index 0000000..cdae2f2
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute-with-args.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_with_args</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-extended.html" title="SPI_execute_extended" /><link rel="next" href="spi-spi-prepare.html" title="SPI_prepare" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_with_args</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-extended.html" title="SPI_execute_extended">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-prepare.html" title="SPI_prepare">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-WITH-ARGS"><div class="titlepage"></div><a id="id-1.8.12.8.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_with_args</span></h2><p>SPI_execute_with_args — execute a command with out-of-line parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute_with_args(const char *<em class="parameter"><code>command</code></em>,
+ int <em class="parameter"><code>nargs</code></em>, Oid *<em class="parameter"><code>argtypes</code></em>,
+ Datum *<em class="parameter"><code>values</code></em>, const char *<em class="parameter"><code>nulls</code></em>,
+ bool <em class="parameter"><code>read_only</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.7.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute_with_args</code> executes a command that might
+ include references to externally supplied parameters. The command text
+ refers to a parameter as <code class="literal">$<em class="replaceable"><code>n</code></em></code>, and
+ the call specifies data types and values for each such symbol.
+ <em class="parameter"><code>read_only</code></em> and <em class="parameter"><code>count</code></em> have
+ the same interpretation as in <code class="function">SPI_execute</code>.
+ </p><p>
+ The main advantage of this routine compared to
+ <code class="function">SPI_execute</code> is that data values can be inserted
+ into the command without tedious quoting/escaping, and thus with much
+ less risk of SQL-injection attacks.
+ </p><p>
+ Similar results can be achieved with <code class="function">SPI_prepare</code> followed by
+ <code class="function">SPI_execute_plan</code>; however, when using this function
+ the query plan is always customized to the specific parameter values
+ provided.
+ For one-time query execution, this function should be preferred.
+ If the same command is to be executed with many different parameters,
+ either method might be faster, depending on the cost of re-planning
+ versus the benefit of custom plans.
+ </p></div><div class="refsect1" id="id-1.8.12.8.7.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>nargs</code></em></code></span></dt><dd><p>
+ number of input parameters (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.)
+ </p></dd><dt><span class="term"><code class="literal">Oid * <em class="parameter"><code>argtypes</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, containing the
+ <acronym class="acronym">OID</acronym>s of the data types of the parameters
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, containing the actual
+ parameter values
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>nargs</code></em>, describing which
+ parameters are null
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_execute_with_args</code> assumes that no parameters
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding parameter
+ value is non-null, or <code class="literal">'n'</code> if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding <em class="parameter"><code>values</code></em> entry doesn't matter.) Note
+ that <em class="parameter"><code>nulls</code></em> is not a text string, just an array:
+ it does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.7.7"><h2>Return Value</h2><p>
+ The return value is the same as for <code class="function">SPI_execute</code>.
+ </p><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code> if successful.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-extended.html" title="SPI_execute_extended">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-prepare.html" title="SPI_prepare">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_extended </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_prepare</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-execute.html b/doc/src/sgml/html/spi-spi-execute.html
new file mode 100644
index 0000000..bd93b62
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-execute.html
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-finish.html" title="SPI_finish" /><link rel="next" href="spi-spi-exec.html" title="SPI_exec" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-finish.html" title="SPI_finish">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-exec.html" title="SPI_exec">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE"><div class="titlepage"></div><a id="id-1.8.12.8.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute</span></h2><p>SPI_execute — execute a command</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_execute(const char * <em class="parameter"><code>command</code></em>, bool <em class="parameter"><code>read_only</code></em>, long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.4.5"><h2>Description</h2><p>
+ <code class="function">SPI_execute</code> executes the specified SQL command
+ for <em class="parameter"><code>count</code></em> rows. If <em class="parameter"><code>read_only</code></em>
+ is <code class="literal">true</code>, the command must be read-only, and execution overhead
+ is somewhat reduced.
+ </p><p>
+ This function can only be called from a connected C function.
+ </p><p>
+ If <em class="parameter"><code>count</code></em> is zero then the command is executed
+ for all rows that it applies to. If <em class="parameter"><code>count</code></em>
+ is greater than zero, then no more than <em class="parameter"><code>count</code></em> rows
+ will be retrieved; execution stops when the count is reached, much like
+ adding a <code class="literal">LIMIT</code> clause to the query. For example,
+</p><pre class="programlisting">
+SPI_execute("SELECT * FROM foo", true, 5);
+</pre><p>
+ will retrieve at most 5 rows from the table. Note that such a limit
+ is only effective when the command actually returns rows. For example,
+</p><pre class="programlisting">
+SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
+</pre><p>
+ inserts all rows from <code class="structname">bar</code>, ignoring the
+ <em class="parameter"><code>count</code></em> parameter. However, with
+</p><pre class="programlisting">
+SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
+</pre><p>
+ at most 5 rows would be inserted, since execution would stop after the
+ fifth <code class="literal">RETURNING</code> result row is retrieved.
+ </p><p>
+ You can pass multiple commands in one string;
+ <code class="function">SPI_execute</code> returns the
+ result for the command executed last. The <em class="parameter"><code>count</code></em>
+ limit applies to each command separately (even though only the last
+ result will actually be returned). The limit is not applied to any
+ hidden commands generated by rules.
+ </p><p>
+ When <em class="parameter"><code>read_only</code></em> is <code class="literal">false</code>,
+ <code class="function">SPI_execute</code> increments the command
+ counter and computes a new <em class="firstterm">snapshot</em> before executing each
+ command in the string. The snapshot does not actually change if the
+ current transaction isolation level is <code class="literal">SERIALIZABLE</code> or <code class="literal">REPEATABLE READ</code>, but in
+ <code class="literal">READ COMMITTED</code> mode the snapshot update allows each command to
+ see the results of newly committed transactions from other sessions.
+ This is essential for consistent behavior when the commands are modifying
+ the database.
+ </p><p>
+ When <em class="parameter"><code>read_only</code></em> is <code class="literal">true</code>,
+ <code class="function">SPI_execute</code> does not update either the snapshot
+ or the command counter, and it allows only plain <code class="command">SELECT</code>
+ commands to appear in the command string. The commands are executed
+ using the snapshot previously established for the surrounding query.
+ This execution mode is somewhat faster than the read/write mode due
+ to eliminating per-command overhead. It also allows genuinely
+ <em class="firstterm">stable</em> functions to be built: since successive executions
+ will all use the same snapshot, there will be no change in the results.
+ </p><p>
+ It is generally unwise to mix read-only and read-write commands within
+ a single function using SPI; that could result in very confusing behavior,
+ since the read-only queries would not see the results of any database
+ updates done by the read-write queries.
+ </p><p>
+ The actual number of rows for which the (last) command was executed
+ is returned in the global variable <code class="varname">SPI_processed</code>.
+ If the return value of the function is <code class="symbol">SPI_OK_SELECT</code>,
+ <code class="symbol">SPI_OK_INSERT_RETURNING</code>,
+ <code class="symbol">SPI_OK_DELETE_RETURNING</code>, or
+ <code class="symbol">SPI_OK_UPDATE_RETURNING</code>,
+ then you can use the
+ global pointer <code class="literal">SPITupleTable *SPI_tuptable</code> to
+ access the result rows. Some utility commands (such as
+ <code class="command">EXPLAIN</code>) also return row sets, and <code class="literal">SPI_tuptable</code>
+ will contain the result in these cases too. Some utility commands
+ (<code class="command">COPY</code>, <code class="command">CREATE TABLE AS</code>) don't return a row set, so
+ <code class="literal">SPI_tuptable</code> is NULL, but they still return the number of
+ rows processed in <code class="varname">SPI_processed</code>.
+ </p><p>
+ The structure <code class="structname">SPITupleTable</code> is defined
+ thus:
+</p><pre class="programlisting">
+typedef struct SPITupleTable
+{
+ /* Public members */
+ TupleDesc tupdesc; /* tuple descriptor */
+ HeapTuple *vals; /* array of tuples */
+ uint64 numvals; /* number of valid tuples */
+
+ /* Private members, not intended for external callers */
+ uint64 alloced; /* allocated length of vals array */
+ MemoryContext tuptabcxt; /* memory context of result table */
+ slist_node next; /* link for internal bookkeeping */
+ SubTransactionId subid; /* subxact in which tuptable was created */
+} SPITupleTable;
+</pre><p>
+ The fields <code class="structfield">tupdesc</code>,
+ <code class="structfield">vals</code>, and
+ <code class="structfield">numvals</code>
+ can be used by SPI callers; the remaining fields are internal.
+ <code class="structfield">vals</code> is an array of pointers to rows.
+ The number of rows is given by <code class="structfield">numvals</code>
+ (for somewhat historical reasons, this count is also returned
+ in <code class="varname">SPI_processed</code>).
+ <code class="structfield">tupdesc</code> is a row descriptor which you can pass to
+ SPI functions dealing with rows.
+ </p><p>
+ <code class="function">SPI_finish</code> frees all
+ <code class="structname">SPITupleTable</code>s allocated during the current
+ C function. You can free a particular result table earlier, if you
+ are done with it, by calling <code class="function">SPI_freetuptable</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.4.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ string containing command to execute
+ </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ maximum number of rows to return,
+ or <code class="literal">0</code> for no limit
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.4.7"><h2>Return Value</h2><p>
+ If the execution of the command was successful then one of the
+ following (nonnegative) values will be returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_SELECT</code></span></dt><dd><p>
+ if a <code class="command">SELECT</code> (but not <code class="command">SELECT
+ INTO</code>) was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_SELINTO</code></span></dt><dd><p>
+ if a <code class="command">SELECT INTO</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_INSERT</code></span></dt><dd><p>
+ if an <code class="command">INSERT</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_DELETE</code></span></dt><dd><p>
+ if a <code class="command">DELETE</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UPDATE</code></span></dt><dd><p>
+ if an <code class="command">UPDATE</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_MERGE</code></span></dt><dd><p>
+ if a <code class="command">MERGE</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_INSERT_RETURNING</code></span></dt><dd><p>
+ if an <code class="command">INSERT RETURNING</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_DELETE_RETURNING</code></span></dt><dd><p>
+ if a <code class="command">DELETE RETURNING</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UPDATE_RETURNING</code></span></dt><dd><p>
+ if an <code class="command">UPDATE RETURNING</code> was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UTILITY</code></span></dt><dd><p>
+ if a utility command (e.g., <code class="command">CREATE TABLE</code>)
+ was executed
+ </p></dd><dt><span class="term"><code class="symbol">SPI_OK_REWRITTEN</code></span></dt><dd><p>
+ if the command was rewritten into another kind of command (e.g.,
+ <code class="command">UPDATE</code> became an <code class="command">INSERT</code>) by a <a class="link" href="rules.html" title="Chapter 41. The Rule System">rule</a>.
+ </p></dd></dl></div><p>
+ </p><p>
+ On error, one of the following negative values is returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>command</code></em> is <code class="symbol">NULL</code> or
+ <em class="parameter"><code>count</code></em> is less than 0
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_COPY</code></span></dt><dd><p>
+ if <code class="command">COPY TO stdout</code> or <code class="command">COPY FROM stdin</code>
+ was attempted
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_TRANSACTION</code></span></dt><dd><p>
+ if a transaction manipulation command was attempted
+ (<code class="command">BEGIN</code>,
+ <code class="command">COMMIT</code>,
+ <code class="command">ROLLBACK</code>,
+ <code class="command">SAVEPOINT</code>,
+ <code class="command">PREPARE TRANSACTION</code>,
+ <code class="command">COMMIT PREPARED</code>,
+ <code class="command">ROLLBACK PREPARED</code>,
+ or any variant thereof)
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_OPUNKNOWN</code></span></dt><dd><p>
+ if the command type is unknown (shouldn't happen)
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.8.12.8.4.8"><h2>Notes</h2><p>
+ All SPI query-execution functions set both
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> (just the pointer, not the contents
+ of the structure). Save these two global variables into local
+ C function variables if you need to access the result table of
+ <code class="function">SPI_execute</code> or another query-execution function
+ across later calls.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-finish.html" title="SPI_finish">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-exec.html" title="SPI_exec">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_finish </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_exec</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-finish.html b/doc/src/sgml/html/spi-spi-finish.html
new file mode 100644
index 0000000..c56c351
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-finish.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_finish</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-connect.html" title="SPI_connect" /><link rel="next" href="spi-spi-execute.html" title="SPI_execute" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_finish</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-connect.html" title="SPI_connect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute.html" title="SPI_execute">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FINISH"><div class="titlepage"></div><a id="id-1.8.12.8.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_finish</span></h2><p>SPI_finish — disconnect a C function from the SPI manager</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_finish(void)
+</pre></div><div class="refsect1" id="id-1.8.12.8.3.5"><h2>Description</h2><p>
+ <code class="function">SPI_finish</code> closes an existing connection to
+ the SPI manager. You must call this function after completing the
+ SPI operations needed during your C function's current invocation.
+ You do not need to worry about making this happen, however, if you
+ abort the transaction via <code class="literal">elog(ERROR)</code>. In that
+ case SPI will clean itself up automatically.
+ </p></div><div class="refsect1" id="id-1.8.12.8.3.6"><h2>Return Value</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_FINISH</code></span></dt><dd><p>
+ if properly disconnected
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-connect.html" title="SPI_connect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute.html" title="SPI_execute">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_connect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-fname.html b/doc/src/sgml/html/spi-spi-fname.html
new file mode 100644
index 0000000..3ee00fd
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-fname.html
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_fname</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-interface-support.html" title="47.2. Interface Support Functions" /><link rel="next" href="spi-spi-fnumber.html" title="SPI_fnumber" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_fname</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-interface-support.html" title="47.2. Interface Support Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-fnumber.html" title="SPI_fnumber">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FNAME"><div class="titlepage"></div><a id="id-1.8.12.9.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_fname</span></h2><p>SPI_fname — determine the column name for the specified column number</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+char * SPI_fname(TupleDesc <em class="parameter"><code>rowdesc</code></em>, int <em class="parameter"><code>colnumber</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.4.5"><h2>Description</h2><p>
+ <code class="function">SPI_fname</code> returns a copy of the column name of the
+ specified column. (You can use <code class="function">pfree</code> to
+ release the copy of the name when you don't need it anymore.)
+ </p></div><div class="refsect1" id="id-1.8.12.9.4.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>colnumber</code></em></code></span></dt><dd><p>
+ column number (count starts at 1)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.4.7"><h2>Return Value</h2><p>
+ The column name; <code class="symbol">NULL</code> if
+ <em class="parameter"><code>colnumber</code></em> is out of range.
+ <code class="varname">SPI_result</code> set to
+ <code class="symbol">SPI_ERROR_NOATTRIBUTE</code> on error.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-interface-support.html" title="47.2. Interface Support Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-fnumber.html" title="SPI_fnumber">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.2. Interface Support Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_fnumber</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-fnumber.html b/doc/src/sgml/html/spi-spi-fnumber.html
new file mode 100644
index 0000000..b4e2a65
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-fnumber.html
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_fnumber</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-fname.html" title="SPI_fname" /><link rel="next" href="spi-spi-getvalue.html" title="SPI_getvalue" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_fnumber</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-fname.html" title="SPI_fname">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getvalue.html" title="SPI_getvalue">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FNUMBER"><div class="titlepage"></div><a id="id-1.8.12.9.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_fnumber</span></h2><p>SPI_fnumber — determine the column number for the specified column name</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_fnumber(TupleDesc <em class="parameter"><code>rowdesc</code></em>, const char * <em class="parameter"><code>colname</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.5.5"><h2>Description</h2><p>
+ <code class="function">SPI_fnumber</code> returns the column number for the
+ column with the specified name.
+ </p><p>
+ If <em class="parameter"><code>colname</code></em> refers to a system column (e.g.,
+ <code class="literal">ctid</code>) then the appropriate negative column number will
+ be returned. The caller should be careful to test the return value
+ for exact equality to <code class="symbol">SPI_ERROR_NOATTRIBUTE</code> to
+ detect an error; testing the result for less than or equal to 0 is
+ not correct unless system columns should be rejected.
+ </p></div><div class="refsect1" id="id-1.8.12.9.5.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>colname</code></em></code></span></dt><dd><p>
+ column name
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.5.7"><h2>Return Value</h2><p>
+ Column number (count starts at 1 for user-defined columns), or
+ <code class="symbol">SPI_ERROR_NOATTRIBUTE</code> if the named column was not
+ found.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-fname.html" title="SPI_fname">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getvalue.html" title="SPI_getvalue">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_fname </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getvalue</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-freeplan.html b/doc/src/sgml/html/spi-spi-freeplan.html
new file mode 100644
index 0000000..6482eaa
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-freeplan.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_freeplan</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-freetupletable.html" title="SPI_freetuptable" /><link rel="next" href="spi-transaction.html" title="47.4. Transaction Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_freeplan</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-freetupletable.html" title="SPI_freetuptable">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-transaction.html" title="47.4. Transaction Management">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FREEPLAN"><div class="titlepage"></div><a id="id-1.8.12.10.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_freeplan</span></h2><p>SPI_freeplan — free a previously saved prepared statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_freeplan(SPIPlanPtr <em class="parameter"><code>plan</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.14.5"><h2>Description</h2><p>
+ <code class="function">SPI_freeplan</code> releases a prepared statement
+ previously returned by <code class="function">SPI_prepare</code> or saved by
+ <code class="function">SPI_keepplan</code> or <code class="function">SPI_saveplan</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.10.14.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ pointer to statement to free
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.14.7"><h2>Return Value</h2><p>
+ 0 on success;
+ <code class="symbol">SPI_ERROR_ARGUMENT</code> if <em class="parameter"><code>plan</code></em>
+ is <code class="symbol">NULL</code> or invalid
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-freetupletable.html" title="SPI_freetuptable">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-transaction.html" title="47.4. Transaction Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_freetuptable </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.4. Transaction Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-freetuple.html b/doc/src/sgml/html/spi-spi-freetuple.html
new file mode 100644
index 0000000..3f99549
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-freetuple.html
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_freetuple</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-modifytuple.html" title="SPI_modifytuple" /><link rel="next" href="spi-spi-freetupletable.html" title="SPI_freetuptable" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_freetuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-modifytuple.html" title="SPI_modifytuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-freetupletable.html" title="SPI_freetuptable">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FREETUPLE"><div class="titlepage"></div><a id="id-1.8.12.10.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_freetuple</span></h2><p>SPI_freetuple — free a row allocated in the upper executor context</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_freetuple(HeapTuple <em class="parameter"><code>row</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.12.5"><h2>Description</h2><p>
+ <code class="function">SPI_freetuple</code> frees a row previously allocated
+ in the upper executor context.
+ </p><p>
+ This function is no longer different from plain
+ <code class="function">heap_freetuple</code>. It's kept just for backward
+ compatibility of existing code.
+ </p></div><div class="refsect1" id="id-1.8.12.10.12.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ row to free
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-modifytuple.html" title="SPI_modifytuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-freetupletable.html" title="SPI_freetuptable">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_modifytuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_freetuptable</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-freetupletable.html b/doc/src/sgml/html/spi-spi-freetupletable.html
new file mode 100644
index 0000000..fde1df8
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-freetupletable.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_freetuptable</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-freetuple.html" title="SPI_freetuple" /><link rel="next" href="spi-spi-freeplan.html" title="SPI_freeplan" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_freetuptable</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-freetuple.html" title="SPI_freetuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-freeplan.html" title="SPI_freeplan">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-FREETUPLETABLE"><div class="titlepage"></div><a id="id-1.8.12.10.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_freetuptable</span></h2><p>SPI_freetuptable — free a row set created by <code class="function">SPI_execute</code> or a similar
+ function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_freetuptable(SPITupleTable * <em class="parameter"><code>tuptable</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.13.5"><h2>Description</h2><p>
+ <code class="function">SPI_freetuptable</code> frees a row set created by a
+ prior SPI command execution function, such as
+ <code class="function">SPI_execute</code>. Therefore, this function is often called
+ with the global variable <code class="varname">SPI_tuptable</code> as
+ argument.
+ </p><p>
+ This function is useful if an SPI-using C function needs to execute
+ multiple commands and does not want to keep the results of earlier
+ commands around until it ends. Note that any unfreed row sets will
+ be freed anyway at <code class="function">SPI_finish</code>.
+ Also, if a subtransaction is started and then aborted within execution
+ of an SPI-using C function, SPI automatically frees any row sets created while
+ the subtransaction was running.
+ </p><p>
+ Beginning in <span class="productname">PostgreSQL</span> 9.3,
+ <code class="function">SPI_freetuptable</code> contains guard logic to protect
+ against duplicate deletion requests for the same row set. In previous
+ releases, duplicate deletions would lead to crashes.
+ </p></div><div class="refsect1" id="id-1.8.12.10.13.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPITupleTable * <em class="parameter"><code>tuptable</code></em></code></span></dt><dd><p>
+ pointer to row set to free, or NULL to do nothing
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-freetuple.html" title="SPI_freetuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-freeplan.html" title="SPI_freeplan">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_freetuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_freeplan</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getargcount.html b/doc/src/sgml/html/spi-spi-getargcount.html
new file mode 100644
index 0000000..95792cd
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getargcount.html
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getargcount</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-prepare-params.html" title="SPI_prepare_params" /><link rel="next" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getargcount</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-prepare-params.html" title="SPI_prepare_params">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETARGCOUNT"><div class="titlepage"></div><a id="id-1.8.12.8.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getargcount</span></h2><p>SPI_getargcount — return the number of arguments needed by a statement
+ prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_getargcount(SPIPlanPtr <em class="parameter"><code>plan</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.12.5"><h2>Description</h2><p>
+ <code class="function">SPI_getargcount</code> returns the number of arguments needed
+ to execute a statement prepared by <code class="function">SPI_prepare</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.12.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.12.7"><h2>Return Value</h2><p>
+ The count of expected arguments for the <em class="parameter"><code>plan</code></em>.
+ If the <em class="parameter"><code>plan</code></em> is <code class="symbol">NULL</code> or invalid,
+ <code class="varname">SPI_result</code> is set to <code class="symbol">SPI_ERROR_ARGUMENT</code>
+ and -1 is returned.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-prepare-params.html" title="SPI_prepare_params">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_prepare_params </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getargtypeid</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getargtypeid.html b/doc/src/sgml/html/spi-spi-getargtypeid.html
new file mode 100644
index 0000000..4cf8c64
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getargtypeid.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getargtypeid</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getargcount.html" title="SPI_getargcount" /><link rel="next" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getargtypeid</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getargcount.html" title="SPI_getargcount">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETARGTYPEID"><div class="titlepage"></div><a id="id-1.8.12.8.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getargtypeid</span></h2><p>SPI_getargtypeid — return the data type OID for an argument of
+ a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Oid SPI_getargtypeid(SPIPlanPtr <em class="parameter"><code>plan</code></em>, int <em class="parameter"><code>argIndex</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.13.5"><h2>Description</h2><p>
+ <code class="function">SPI_getargtypeid</code> returns the OID representing the type
+ for the <em class="parameter"><code>argIndex</code></em>'th argument of a statement prepared by
+ <code class="function">SPI_prepare</code>. First argument is at index zero.
+ </p></div><div class="refsect1" id="id-1.8.12.8.13.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>argIndex</code></em></code></span></dt><dd><p>
+ zero based index of the argument
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.13.7"><h2>Return Value</h2><p>
+ The type OID of the argument at the given index.
+ If the <em class="parameter"><code>plan</code></em> is <code class="symbol">NULL</code> or invalid,
+ or <em class="parameter"><code>argIndex</code></em> is less than 0 or
+ not less than the number of arguments declared for the
+ <em class="parameter"><code>plan</code></em>,
+ <code class="varname">SPI_result</code> is set to <code class="symbol">SPI_ERROR_ARGUMENT</code>
+ and <code class="symbol">InvalidOid</code> is returned.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getargcount.html" title="SPI_getargcount">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-is-cursor-plan.html" title="SPI_is_cursor_plan">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getargcount </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_is_cursor_plan</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getbinval.html b/doc/src/sgml/html/spi-spi-getbinval.html
new file mode 100644
index 0000000..282e3b3
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getbinval.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getbinval</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getvalue.html" title="SPI_getvalue" /><link rel="next" href="spi-spi-gettype.html" title="SPI_gettype" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getbinval</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getvalue.html" title="SPI_getvalue">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-gettype.html" title="SPI_gettype">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETBINVAL"><div class="titlepage"></div><a id="id-1.8.12.9.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getbinval</span></h2><p>SPI_getbinval — return the binary value of the specified column</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Datum SPI_getbinval(HeapTuple <em class="parameter"><code>row</code></em>, TupleDesc <em class="parameter"><code>rowdesc</code></em>, int <em class="parameter"><code>colnumber</code></em>,
+ bool * <em class="parameter"><code>isnull</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.7.5"><h2>Description</h2><p>
+ <code class="function">SPI_getbinval</code> returns the value of the
+ specified column in the internal form (as type <code class="type">Datum</code>).
+ </p><p>
+ This function does not allocate new space for the datum. In the
+ case of a pass-by-reference data type, the return value will be a
+ pointer into the passed row.
+ </p></div><div class="refsect1" id="id-1.8.12.9.7.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ input row to be examined
+ </p></dd><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>colnumber</code></em></code></span></dt><dd><p>
+ column number (count starts at 1)
+ </p></dd><dt><span class="term"><code class="literal">bool * <em class="parameter"><code>isnull</code></em></code></span></dt><dd><p>
+ flag for a null value in the column
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.7.7"><h2>Return Value</h2><p>
+ The binary value of the column is returned. The variable pointed
+ to by <em class="parameter"><code>isnull</code></em> is set to true if the column is
+ null, else to false.
+ </p><p>
+ <code class="varname">SPI_result</code> is set to
+ <code class="symbol">SPI_ERROR_NOATTRIBUTE</code> on error.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getvalue.html" title="SPI_getvalue">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-gettype.html" title="SPI_gettype">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getvalue </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_gettype</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getnspname.html b/doc/src/sgml/html/spi-spi-getnspname.html
new file mode 100644
index 0000000..2cf3e72
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getnspname.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getnspname</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getrelname.html" title="SPI_getrelname" /><link rel="next" href="spi-spi-result-code-string.html" title="SPI_result_code_string" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getnspname</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getrelname.html" title="SPI_getrelname">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-result-code-string.html" title="SPI_result_code_string">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETNSPNAME"><div class="titlepage"></div><a id="id-1.8.12.9.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getnspname</span></h2><p>SPI_getnspname — return the namespace of the specified relation</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+char * SPI_getnspname(Relation <em class="parameter"><code>rel</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.11.5"><h2>Description</h2><p>
+ <code class="function">SPI_getnspname</code> returns a copy of the name of
+ the namespace that the specified <code class="structname">Relation</code>
+ belongs to. This is equivalent to the relation's schema. You should
+ <code class="function">pfree</code> the return value of this function when
+ you are finished with it.
+ </p></div><div class="refsect1" id="id-1.8.12.9.11.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Relation <em class="parameter"><code>rel</code></em></code></span></dt><dd><p>
+ input relation
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.11.7"><h2>Return Value</h2><p>
+ The name of the specified relation's namespace.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getrelname.html" title="SPI_getrelname">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-result-code-string.html" title="SPI_result_code_string">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getrelname </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_result_code_string</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getrelname.html b/doc/src/sgml/html/spi-spi-getrelname.html
new file mode 100644
index 0000000..c970e83
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getrelname.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getrelname</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-gettypeid.html" title="SPI_gettypeid" /><link rel="next" href="spi-spi-getnspname.html" title="SPI_getnspname" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getrelname</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-gettypeid.html" title="SPI_gettypeid">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getnspname.html" title="SPI_getnspname">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETRELNAME"><div class="titlepage"></div><a id="id-1.8.12.9.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getrelname</span></h2><p>SPI_getrelname — return the name of the specified relation</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+char * SPI_getrelname(Relation <em class="parameter"><code>rel</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.10.5"><h2>Description</h2><p>
+ <code class="function">SPI_getrelname</code> returns a copy of the name of the
+ specified relation. (You can use <code class="function">pfree</code> to
+ release the copy of the name when you don't need it anymore.)
+ </p></div><div class="refsect1" id="id-1.8.12.9.10.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Relation <em class="parameter"><code>rel</code></em></code></span></dt><dd><p>
+ input relation
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.10.7"><h2>Return Value</h2><p>
+ The name of the specified relation.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-gettypeid.html" title="SPI_gettypeid">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getnspname.html" title="SPI_getnspname">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_gettypeid </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getnspname</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-gettype.html b/doc/src/sgml/html/spi-spi-gettype.html
new file mode 100644
index 0000000..4b5bff1
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-gettype.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_gettype</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getbinval.html" title="SPI_getbinval" /><link rel="next" href="spi-spi-gettypeid.html" title="SPI_gettypeid" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_gettype</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getbinval.html" title="SPI_getbinval">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-gettypeid.html" title="SPI_gettypeid">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETTYPE"><div class="titlepage"></div><a id="id-1.8.12.9.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_gettype</span></h2><p>SPI_gettype — return the data type name of the specified column</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+char * SPI_gettype(TupleDesc <em class="parameter"><code>rowdesc</code></em>, int <em class="parameter"><code>colnumber</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.8.5"><h2>Description</h2><p>
+ <code class="function">SPI_gettype</code> returns a copy of the data type name of the
+ specified column. (You can use <code class="function">pfree</code> to
+ release the copy of the name when you don't need it anymore.)
+ </p></div><div class="refsect1" id="id-1.8.12.9.8.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>colnumber</code></em></code></span></dt><dd><p>
+ column number (count starts at 1)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.8.7"><h2>Return Value</h2><p>
+ The data type name of the specified column, or
+ <code class="symbol">NULL</code> on error. <code class="varname">SPI_result</code> is
+ set to <code class="symbol">SPI_ERROR_NOATTRIBUTE</code> on error.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getbinval.html" title="SPI_getbinval">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-gettypeid.html" title="SPI_gettypeid">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getbinval </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_gettypeid</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-gettypeid.html b/doc/src/sgml/html/spi-spi-gettypeid.html
new file mode 100644
index 0000000..004598f
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-gettypeid.html
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_gettypeid</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-gettype.html" title="SPI_gettype" /><link rel="next" href="spi-spi-getrelname.html" title="SPI_getrelname" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_gettypeid</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-gettype.html" title="SPI_gettype">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getrelname.html" title="SPI_getrelname">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETTYPEID"><div class="titlepage"></div><a id="id-1.8.12.9.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_gettypeid</span></h2><p>SPI_gettypeid — return the data type <acronym class="acronym">OID</acronym> of the specified column</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+Oid SPI_gettypeid(TupleDesc <em class="parameter"><code>rowdesc</code></em>, int <em class="parameter"><code>colnumber</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.9.5"><h2>Description</h2><p>
+ <code class="function">SPI_gettypeid</code> returns the
+ <acronym class="acronym">OID</acronym> of the data type of the specified column.
+ </p></div><div class="refsect1" id="id-1.8.12.9.9.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>colnumber</code></em></code></span></dt><dd><p>
+ column number (count starts at 1)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.9.7"><h2>Return Value</h2><p>
+ The <acronym class="acronym">OID</acronym> of the data type of the specified column
+ or <code class="symbol">InvalidOid</code> on error. On error,
+ <code class="varname">SPI_result</code> is set to
+ <code class="symbol">SPI_ERROR_NOATTRIBUTE</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-gettype.html" title="SPI_gettype">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getrelname.html" title="SPI_getrelname">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_gettype </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getrelname</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-getvalue.html b/doc/src/sgml/html/spi-spi-getvalue.html
new file mode 100644
index 0000000..182d1c6
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-getvalue.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_getvalue</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-fnumber.html" title="SPI_fnumber" /><link rel="next" href="spi-spi-getbinval.html" title="SPI_getbinval" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_getvalue</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-fnumber.html" title="SPI_fnumber">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getbinval.html" title="SPI_getbinval">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-GETVALUE"><div class="titlepage"></div><a id="id-1.8.12.9.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_getvalue</span></h2><p>SPI_getvalue — return the string value of the specified column</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+char * SPI_getvalue(HeapTuple <em class="parameter"><code>row</code></em>, TupleDesc <em class="parameter"><code>rowdesc</code></em>, int <em class="parameter"><code>colnumber</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.9.6.5"><h2>Description</h2><p>
+ <code class="function">SPI_getvalue</code> returns the string representation
+ of the value of the specified column.
+ </p><p>
+ The result is returned in memory allocated using
+ <code class="function">palloc</code>. (You can use
+ <code class="function">pfree</code> to release the memory when you don't
+ need it anymore.)
+ </p></div><div class="refsect1" id="id-1.8.12.9.6.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ input row to be examined
+ </p></dd><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ input row description
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>colnumber</code></em></code></span></dt><dd><p>
+ column number (count starts at 1)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.6.7"><h2>Return Value</h2><p>
+ Column value, or <code class="symbol">NULL</code> if the column is null,
+ <em class="parameter"><code>colnumber</code></em> is out of range
+ (<code class="varname">SPI_result</code> is set to
+ <code class="symbol">SPI_ERROR_NOATTRIBUTE</code>), or no output function is
+ available (<code class="varname">SPI_result</code> is set to
+ <code class="symbol">SPI_ERROR_NOOUTFUNC</code>).
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-fnumber.html" title="SPI_fnumber">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getbinval.html" title="SPI_getbinval">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_fnumber </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getbinval</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-is-cursor-plan.html b/doc/src/sgml/html/spi-spi-is-cursor-plan.html
new file mode 100644
index 0000000..51a0f3b
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-is-cursor-plan.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_is_cursor_plan</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid" /><link rel="next" href="spi-spi-execute-plan.html" title="SPI_execute_plan" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_is_cursor_plan</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-IS-CURSOR-PLAN"><div class="titlepage"></div><a id="id-1.8.12.8.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_is_cursor_plan</span></h2><p>SPI_is_cursor_plan — return <code class="symbol">true</code> if a statement
+ prepared by <code class="function">SPI_prepare</code> can be used with
+ <code class="function">SPI_cursor_open</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+bool SPI_is_cursor_plan(SPIPlanPtr <em class="parameter"><code>plan</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.14.5"><h2>Description</h2><p>
+ <code class="function">SPI_is_cursor_plan</code> returns <code class="symbol">true</code>
+ if a statement prepared by <code class="function">SPI_prepare</code> can be passed
+ as an argument to <code class="function">SPI_cursor_open</code>, or
+ <code class="symbol">false</code> if that is not the case. The criteria are that the
+ <em class="parameter"><code>plan</code></em> represents one single command and that this
+ command returns tuples to the caller; for example, <code class="command">SELECT</code>
+ is allowed unless it contains an <code class="literal">INTO</code> clause, and
+ <code class="command">UPDATE</code> is allowed only if it contains a <code class="literal">RETURNING</code>
+ clause.
+ </p></div><div class="refsect1" id="id-1.8.12.8.14.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ prepared statement (returned by <code class="function">SPI_prepare</code>)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.14.7"><h2>Return Value</h2><p>
+ <code class="symbol">true</code> or <code class="symbol">false</code> to indicate if the
+ <em class="parameter"><code>plan</code></em> can produce a cursor or not, with
+ <code class="varname">SPI_result</code> set to zero.
+ If it is not possible to determine the answer (for example,
+ if the <em class="parameter"><code>plan</code></em> is <code class="symbol">NULL</code> or invalid,
+ or if called when not connected to SPI), then
+ <code class="varname">SPI_result</code> is set to a suitable error code
+ and <code class="symbol">false</code> is returned.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getargtypeid.html" title="SPI_getargtypeid">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getargtypeid </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_plan</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-keepplan.html b/doc/src/sgml/html/spi-spi-keepplan.html
new file mode 100644
index 0000000..804f22c
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-keepplan.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_keepplan</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-close.html" title="SPI_cursor_close" /><link rel="next" href="spi-spi-saveplan.html" title="SPI_saveplan" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_keepplan</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-close.html" title="SPI_cursor_close">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-saveplan.html" title="SPI_saveplan">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-KEEPPLAN"><div class="titlepage"></div><a id="id-1.8.12.8.29.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_keepplan</span></h2><p>SPI_keepplan — save a prepared statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_keepplan(SPIPlanPtr <em class="parameter"><code>plan</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.29.5"><h2>Description</h2><p>
+ <code class="function">SPI_keepplan</code> saves a passed statement (prepared by
+ <code class="function">SPI_prepare</code>) so that it will not be freed
+ by <code class="function">SPI_finish</code> nor by the transaction manager.
+ This gives you the ability to reuse prepared statements in the subsequent
+ invocations of your C function in the current session.
+ </p></div><div class="refsect1" id="id-1.8.12.8.29.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ the prepared statement to be saved
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.29.7"><h2>Return Value</h2><p>
+ 0 on success;
+ <code class="symbol">SPI_ERROR_ARGUMENT</code> if <em class="parameter"><code>plan</code></em>
+ is <code class="symbol">NULL</code> or invalid
+ </p></div><div class="refsect1" id="id-1.8.12.8.29.8"><h2>Notes</h2><p>
+ The passed-in statement is relocated to permanent storage by means
+ of pointer adjustment (no data copying is required). If you later
+ wish to delete it, use <code class="function">SPI_freeplan</code> on it.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-close.html" title="SPI_cursor_close">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-saveplan.html" title="SPI_saveplan">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_close </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_saveplan</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-modifytuple.html b/doc/src/sgml/html/spi-spi-modifytuple.html
new file mode 100644
index 0000000..96bc78d
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-modifytuple.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_modifytuple</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-returntuple.html" title="SPI_returntuple" /><link rel="next" href="spi-spi-freetuple.html" title="SPI_freetuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_modifytuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-returntuple.html" title="SPI_returntuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-freetuple.html" title="SPI_freetuple">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-MODIFYTUPLE"><div class="titlepage"></div><a id="id-1.8.12.10.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_modifytuple</span></h2><p>SPI_modifytuple — create a row by replacing selected fields of a given row</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+HeapTuple SPI_modifytuple(Relation <em class="parameter"><code>rel</code></em>, HeapTuple <em class="parameter"><code>row</code></em>, int <em class="parameter"><code>ncols</code></em>,
+ int * <em class="parameter"><code>colnum</code></em>, Datum * <em class="parameter"><code>values</code></em>, const char * <em class="parameter"><code>nulls</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.11.5"><h2>Description</h2><p>
+ <code class="function">SPI_modifytuple</code> creates a new row by
+ substituting new values for selected columns, copying the original
+ row's columns at other positions. The input row is not modified.
+ The new row is returned in the upper executor context.
+ </p><p>
+ This function can only be used while connected to SPI.
+ Otherwise, it returns NULL and sets <code class="varname">SPI_result</code> to
+ <code class="symbol">SPI_ERROR_UNCONNECTED</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.10.11.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Relation <em class="parameter"><code>rel</code></em></code></span></dt><dd><p>
+ Used only as the source of the row descriptor for the row.
+ (Passing a relation rather than a row descriptor is a
+ misfeature.)
+ </p></dd><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ row to be modified
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>ncols</code></em></code></span></dt><dd><p>
+ number of columns to be changed
+ </p></dd><dt><span class="term"><code class="literal">int * <em class="parameter"><code>colnum</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>ncols</code></em>, containing the numbers
+ of the columns that are to be changed (column numbers start at 1)
+ </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>ncols</code></em>, containing the
+ new values for the specified columns
+ </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>
+ an array of length <em class="parameter"><code>ncols</code></em>, describing which
+ new values are null
+ </p><p>
+ If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then
+ <code class="function">SPI_modifytuple</code> assumes that no new values
+ are null. Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>
+ array should be <code class="literal">' '</code> if the corresponding new value is
+ non-null, or <code class="literal">'n'</code> if the corresponding new value is
+ null. (In the latter case, the actual value in the corresponding
+ <em class="parameter"><code>values</code></em> entry doesn't matter.) Note that
+ <em class="parameter"><code>nulls</code></em> is not a text string, just an array: it
+ does not need a <code class="literal">'\0'</code> terminator.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.11.7"><h2>Return Value</h2><p>
+ new row with modifications, allocated in the upper executor
+ context, or <code class="symbol">NULL</code> on error
+ (see <code class="varname">SPI_result</code> for an error indication)
+ </p><p>
+ On error, <code class="varname">SPI_result</code> is set as follows:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>rel</code></em> is <code class="symbol">NULL</code>, or if
+ <em class="parameter"><code>row</code></em> is <code class="symbol">NULL</code>, or if <em class="parameter"><code>ncols</code></em>
+ is less than or equal to 0, or if <em class="parameter"><code>colnum</code></em> is
+ <code class="symbol">NULL</code>, or if <em class="parameter"><code>values</code></em> is <code class="symbol">NULL</code>.
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_NOATTRIBUTE</code></span></dt><dd><p>
+ if <em class="parameter"><code>colnum</code></em> contains an invalid column number (less
+ than or equal to 0 or greater than the number of columns in
+ <em class="parameter"><code>row</code></em>)
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if SPI is not active
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-returntuple.html" title="SPI_returntuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-freetuple.html" title="SPI_freetuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_returntuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_freetuple</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-palloc.html b/doc/src/sgml/html/spi-spi-palloc.html
new file mode 100644
index 0000000..298c605
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-palloc.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_palloc</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-memory.html" title="47.3. Memory Management" /><link rel="next" href="spi-realloc.html" title="SPI_repalloc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_palloc</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-memory.html" title="47.3. Memory Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-realloc.html" title="SPI_repalloc">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PALLOC"><div class="titlepage"></div><a id="id-1.8.12.10.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_palloc</span></h2><p>SPI_palloc — allocate memory in the upper executor context</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void * SPI_palloc(Size <em class="parameter"><code>size</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.6.5"><h2>Description</h2><p>
+ <code class="function">SPI_palloc</code> allocates memory in the upper
+ executor context.
+ </p><p>
+ This function can only be used while connected to SPI.
+ Otherwise, it throws an error.
+ </p></div><div class="refsect1" id="id-1.8.12.10.6.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Size <em class="parameter"><code>size</code></em></code></span></dt><dd><p>
+ size in bytes of storage to allocate
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.6.7"><h2>Return Value</h2><p>
+ pointer to new storage space of the specified size
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-memory.html" title="47.3. Memory Management">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-realloc.html" title="SPI_repalloc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.3. Memory Management </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_repalloc</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-pfree.html b/doc/src/sgml/html/spi-spi-pfree.html
new file mode 100644
index 0000000..3120281
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-pfree.html
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_pfree</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-realloc.html" title="SPI_repalloc" /><link rel="next" href="spi-spi-copytuple.html" title="SPI_copytuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_pfree</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-realloc.html" title="SPI_repalloc">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-copytuple.html" title="SPI_copytuple">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PFREE"><div class="titlepage"></div><a id="id-1.8.12.10.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_pfree</span></h2><p>SPI_pfree — free memory in the upper executor context</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_pfree(void * <em class="parameter"><code>pointer</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.8.5"><h2>Description</h2><p>
+ <code class="function">SPI_pfree</code> frees memory previously allocated
+ using <code class="function">SPI_palloc</code> or
+ <code class="function">SPI_repalloc</code>.
+ </p><p>
+ This function is no longer different from plain
+ <code class="function">pfree</code>. It's kept just for backward
+ compatibility of existing code.
+ </p></div><div class="refsect1" id="id-1.8.12.10.8.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">void * <em class="parameter"><code>pointer</code></em></code></span></dt><dd><p>
+ pointer to existing storage to free
+ </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-realloc.html" title="SPI_repalloc">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-copytuple.html" title="SPI_copytuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_repalloc </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_copytuple</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-prepare-cursor.html b/doc/src/sgml/html/spi-spi-prepare-cursor.html
new file mode 100644
index 0000000..9975f88
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-prepare-cursor.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_prepare_cursor</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-prepare.html" title="SPI_prepare" /><link rel="next" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_prepare_cursor</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-prepare.html" title="SPI_prepare">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PREPARE-CURSOR"><div class="titlepage"></div><a id="id-1.8.12.8.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_prepare_cursor</span></h2><p>SPI_prepare_cursor — prepare a statement, without executing it yet</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_prepare_cursor(const char * <em class="parameter"><code>command</code></em>, int <em class="parameter"><code>nargs</code></em>,
+ Oid * <em class="parameter"><code>argtypes</code></em>, int <em class="parameter"><code>cursorOptions</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.9.5"><h2>Description</h2><p>
+ <code class="function">SPI_prepare_cursor</code> is identical to
+ <code class="function">SPI_prepare</code>, except that it also allows specification
+ of the planner's <span class="quote">“<span class="quote">cursor options</span>”</span> parameter. This is a bit mask
+ having the values shown in <code class="filename">nodes/parsenodes.h</code>
+ for the <code class="structfield">options</code> field of <code class="structname">DeclareCursorStmt</code>.
+ <code class="function">SPI_prepare</code> always takes the cursor options as zero.
+ </p><p>
+ This function is now deprecated in favor
+ of <code class="function">SPI_prepare_extended</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.9.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>nargs</code></em></code></span></dt><dd><p>
+ number of input parameters (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.)
+ </p></dd><dt><span class="term"><code class="literal">Oid * <em class="parameter"><code>argtypes</code></em></code></span></dt><dd><p>
+ pointer to an array containing the <acronym class="acronym">OID</acronym>s of
+ the data types of the parameters
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
+ integer bit mask of cursor options; zero produces default behavior
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.9.7"><h2>Return Value</h2><p>
+ <code class="function">SPI_prepare_cursor</code> has the same return conventions as
+ <code class="function">SPI_prepare</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.9.8"><h2>Notes</h2><p>
+ Useful bits to set in <em class="parameter"><code>cursorOptions</code></em> include
+ <code class="symbol">CURSOR_OPT_SCROLL</code>,
+ <code class="symbol">CURSOR_OPT_NO_SCROLL</code>,
+ <code class="symbol">CURSOR_OPT_FAST_PLAN</code>,
+ <code class="symbol">CURSOR_OPT_GENERIC_PLAN</code>, and
+ <code class="symbol">CURSOR_OPT_CUSTOM_PLAN</code>. Note in particular that
+ <code class="symbol">CURSOR_OPT_HOLD</code> is ignored.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-prepare.html" title="SPI_prepare">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_prepare </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_prepare_extended</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-prepare-extended.html b/doc/src/sgml/html/spi-spi-prepare-extended.html
new file mode 100644
index 0000000..c517aa2
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-prepare-extended.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_prepare_extended</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor" /><link rel="next" href="spi-spi-prepare-params.html" title="SPI_prepare_params" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_prepare_extended</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-prepare-params.html" title="SPI_prepare_params">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PREPARE-EXTENDED"><div class="titlepage"></div><a id="id-1.8.12.8.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_prepare_extended</span></h2><p>SPI_prepare_extended — prepare a statement, without executing it yet</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_prepare_extended(const char * <em class="parameter"><code>command</code></em>,
+ const SPIPrepareOptions * <em class="parameter"><code>options</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.10.5"><h2>Description</h2><p>
+ <code class="function">SPI_prepare_extended</code> creates and returns a prepared
+ statement for the specified command, but doesn't execute the command.
+ This function is equivalent to <code class="function">SPI_prepare</code>,
+ with the addition that the caller can specify options to control
+ the parsing of external parameter references, as well as other facets
+ of query parsing and planning.
+ </p></div><div class="refsect1" id="id-1.8.12.8.10.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">const SPIPrepareOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
+ struct containing optional arguments
+ </p></dd></dl></div><p>
+ Callers should always zero out the entire <em class="parameter"><code>options</code></em>
+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available <em class="parameter"><code>options</code></em> fields are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParserSetupHook <em class="parameter"><code>parserSetup</code></em></code></span></dt><dd><p>
+ Parser hook setup function
+ </p></dd><dt><span class="term"><code class="literal">void * <em class="parameter"><code>parserSetupArg</code></em></code></span></dt><dd><p>
+ pass-through argument for <em class="parameter"><code>parserSetup</code></em>
+ </p></dd><dt><span class="term"><code class="literal">RawParseMode <em class="parameter"><code>parseMode</code></em></code></span></dt><dd><p>
+ mode for raw parsing; <code class="literal">RAW_PARSE_DEFAULT</code> (zero)
+ produces default behavior
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
+ integer bit mask of cursor options; zero produces default behavior
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.10.7"><h2>Return Value</h2><p>
+ <code class="function">SPI_prepare_extended</code> has the same return conventions as
+ <code class="function">SPI_prepare</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-prepare-params.html" title="SPI_prepare_params">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_prepare_cursor </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_prepare_params</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-prepare-params.html b/doc/src/sgml/html/spi-spi-prepare-params.html
new file mode 100644
index 0000000..c367fd8
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-prepare-params.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_prepare_params</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended" /><link rel="next" href="spi-spi-getargcount.html" title="SPI_getargcount" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_prepare_params</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-getargcount.html" title="SPI_getargcount">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PREPARE-PARAMS"><div class="titlepage"></div><a id="id-1.8.12.8.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_prepare_params</span></h2><p>SPI_prepare_params — prepare a statement, without executing it yet</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_prepare_params(const char * <em class="parameter"><code>command</code></em>,
+ ParserSetupHook <em class="parameter"><code>parserSetup</code></em>,
+ void * <em class="parameter"><code>parserSetupArg</code></em>,
+ int <em class="parameter"><code>cursorOptions</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.11.5"><h2>Description</h2><p>
+ <code class="function">SPI_prepare_params</code> creates and returns a prepared
+ statement for the specified command, but doesn't execute the command.
+ This function is equivalent to <code class="function">SPI_prepare_cursor</code>,
+ with the addition that the caller can specify parser hook functions
+ to control the parsing of external parameter references.
+ </p><p>
+ This function is now deprecated in favor
+ of <code class="function">SPI_prepare_extended</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.11.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">ParserSetupHook <em class="parameter"><code>parserSetup</code></em></code></span></dt><dd><p>
+ Parser hook setup function
+ </p></dd><dt><span class="term"><code class="literal">void * <em class="parameter"><code>parserSetupArg</code></em></code></span></dt><dd><p>
+ pass-through argument for <em class="parameter"><code>parserSetup</code></em>
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
+ integer bit mask of cursor options; zero produces default behavior
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.11.7"><h2>Return Value</h2><p>
+ <code class="function">SPI_prepare_params</code> has the same return conventions as
+ <code class="function">SPI_prepare</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-prepare-extended.html" title="SPI_prepare_extended">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-getargcount.html" title="SPI_getargcount">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_prepare_extended </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_getargcount</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-prepare.html b/doc/src/sgml/html/spi-spi-prepare.html
new file mode 100644
index 0000000..1183414
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-prepare.html
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_prepare</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args" /><link rel="next" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_prepare</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-PREPARE"><div class="titlepage"></div><a id="id-1.8.12.8.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_prepare</span></h2><p>SPI_prepare — prepare a statement, without executing it yet</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_prepare(const char * <em class="parameter"><code>command</code></em>, int <em class="parameter"><code>nargs</code></em>, Oid * <em class="parameter"><code>argtypes</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.8.5"><h2>Description</h2><p>
+ <code class="function">SPI_prepare</code> creates and returns a prepared
+ statement for the specified command, but doesn't execute the command.
+ The prepared statement can later be executed repeatedly using
+ <code class="function">SPI_execute_plan</code>.
+ </p><p>
+ When the same or a similar command is to be executed repeatedly, it
+ is generally advantageous to perform parse analysis only once, and
+ might furthermore be advantageous to re-use an execution plan for the
+ command.
+ <code class="function">SPI_prepare</code> converts a command string into a
+ prepared statement that encapsulates the results of parse analysis.
+ The prepared statement also provides a place for caching an execution plan
+ if it is found that generating a custom plan for each execution is not
+ helpful.
+ </p><p>
+ A prepared command can be generalized by writing parameters
+ (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.) in place of what would be
+ constants in a normal command. The actual values of the parameters
+ are then specified when <code class="function">SPI_execute_plan</code> is called.
+ This allows the prepared command to be used over a wider range of
+ situations than would be possible without parameters.
+ </p><p>
+ The statement returned by <code class="function">SPI_prepare</code> can be used
+ only in the current invocation of the C function, since
+ <code class="function">SPI_finish</code> frees memory allocated for such a
+ statement. But the statement can be saved for longer using the functions
+ <code class="function">SPI_keepplan</code> or <code class="function">SPI_saveplan</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.8.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
+ command string
+ </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>nargs</code></em></code></span></dt><dd><p>
+ number of input parameters (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.)
+ </p></dd><dt><span class="term"><code class="literal">Oid * <em class="parameter"><code>argtypes</code></em></code></span></dt><dd><p>
+ pointer to an array containing the <acronym class="acronym">OID</acronym>s of
+ the data types of the parameters
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.8.7"><h2>Return Value</h2><p>
+ <code class="function">SPI_prepare</code> returns a non-null pointer to an
+ <code class="type">SPIPlan</code>, which is an opaque struct representing a prepared
+ statement. On error, <code class="symbol">NULL</code> will be returned,
+ and <code class="varname">SPI_result</code> will be set to one of the same
+ error codes used by <code class="function">SPI_execute</code>, except that
+ it is set to <code class="symbol">SPI_ERROR_ARGUMENT</code> if
+ <em class="parameter"><code>command</code></em> is <code class="symbol">NULL</code>, or if
+ <em class="parameter"><code>nargs</code></em> is less than 0, or if <em class="parameter"><code>nargs</code></em> is
+ greater than 0 and <em class="parameter"><code>argtypes</code></em> is <code class="symbol">NULL</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.8.8"><h2>Notes</h2><p>
+ If no parameters are defined, a generic plan will be created at the
+ first use of <code class="function">SPI_execute_plan</code>, and used for all
+ subsequent executions as well. If there are parameters, the first few uses
+ of <code class="function">SPI_execute_plan</code> will generate custom plans
+ that are specific to the supplied parameter values. After enough uses
+ of the same prepared statement, <code class="function">SPI_execute_plan</code> will
+ build a generic plan, and if that is not too much more expensive than the
+ custom plans, it will start using the generic plan instead of re-planning
+ each time. If this default behavior is unsuitable, you can alter it by
+ passing the <code class="literal">CURSOR_OPT_GENERIC_PLAN</code> or
+ <code class="literal">CURSOR_OPT_CUSTOM_PLAN</code> flag to
+ <code class="function">SPI_prepare_cursor</code>, to force use of generic or custom
+ plans respectively.
+ </p><p>
+ Although the main point of a prepared statement is to avoid repeated parse
+ analysis and planning of the statement, <span class="productname">PostgreSQL</span> will
+ force re-analysis and re-planning of the statement before using it
+ whenever database objects used in the statement have undergone
+ definitional (DDL) changes since the previous use of the prepared
+ statement. Also, if the value of <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> changes
+ from one use to the next, the statement will be re-parsed using the new
+ <code class="varname">search_path</code>. (This latter behavior is new as of
+ <span class="productname">PostgreSQL</span> 9.3.) See <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for more information about the behavior of prepared
+ statements.
+ </p><p>
+ This function should only be called from a connected C function.
+ </p><p>
+ <code class="type">SPIPlanPtr</code> is declared as a pointer to an opaque struct type in
+ <code class="filename">spi.h</code>. It is unwise to try to access its contents
+ directly, as that makes your code much more likely to break in
+ future revisions of <span class="productname">PostgreSQL</span>.
+ </p><p>
+ The name <code class="type">SPIPlanPtr</code> is somewhat historical, since the data
+ structure no longer necessarily contains an execution plan.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_with_args </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_prepare_cursor</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-register-relation.html b/doc/src/sgml/html/spi-spi-register-relation.html
new file mode 100644
index 0000000..3466d37
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-register-relation.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_register_relation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-saveplan.html" title="SPI_saveplan" /><link rel="next" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_register_relation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-saveplan.html" title="SPI_saveplan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-REGISTER-RELATION"><div class="titlepage"></div><a id="id-1.8.12.8.31.1" class="indexterm"></a><a id="id-1.8.12.8.31.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_register_relation</span></h2><p>SPI_register_relation — make an ephemeral named relation available by name in SPI queries</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_register_relation(EphemeralNamedRelation <em class="parameter"><code>enr</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.31.6"><h2>Description</h2><p>
+ <code class="function">SPI_register_relation</code> makes an ephemeral named
+ relation, with associated information, available to queries planned and
+ executed through the current SPI connection.
+ </p></div><div class="refsect1" id="id-1.8.12.8.31.7"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">EphemeralNamedRelation <em class="parameter"><code>enr</code></em></code></span></dt><dd><p>
+ the ephemeral named relation registry entry
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.31.8"><h2>Return Value</h2><p>
+ If the execution of the command was successful then the following
+ (nonnegative) value will be returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_REL_REGISTER</code></span></dt><dd><p>
+ if the relation has been successfully registered by name
+ </p></dd></dl></div><p>
+ </p><p>
+ On error, one of the following negative values is returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>enr</code></em> is <code class="symbol">NULL</code> or its
+ <code class="varname">name</code> field is <code class="symbol">NULL</code>
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_REL_DUPLICATE</code></span></dt><dd><p>
+ if the name specified in the <code class="varname">name</code> field of
+ <em class="parameter"><code>enr</code></em> is already registered for this connection
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-saveplan.html" title="SPI_saveplan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_saveplan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_unregister_relation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-register-trigger-data.html b/doc/src/sgml/html/spi-spi-register-trigger-data.html
new file mode 100644
index 0000000..7693763
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-register-trigger-data.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_register_trigger_data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation" /><link rel="next" href="spi-interface-support.html" title="47.2. Interface Support Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_register_trigger_data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-interface-support.html" title="47.2. Interface Support Functions">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-REGISTER-TRIGGER-DATA"><div class="titlepage"></div><a id="id-1.8.12.8.33.1" class="indexterm"></a><a id="id-1.8.12.8.33.2" class="indexterm"></a><a id="id-1.8.12.8.33.3" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_register_trigger_data</span></h2><p>SPI_register_trigger_data — make ephemeral trigger data available in SPI queries</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_register_trigger_data(TriggerData *<em class="parameter"><code>tdata</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.33.7"><h2>Description</h2><p>
+ <code class="function">SPI_register_trigger_data</code> makes any ephemeral
+ relations captured by a trigger available to queries planned and executed
+ through the current SPI connection. Currently, this means the transition
+ tables captured by an <code class="literal">AFTER</code> trigger defined with a
+ <code class="literal">REFERENCING OLD/NEW TABLE AS</code> ... clause. This function
+ should be called by a PL trigger handler function after connecting.
+ </p></div><div class="refsect1" id="id-1.8.12.8.33.8"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TriggerData *<em class="parameter"><code>tdata</code></em></code></span></dt><dd><p>
+ the <code class="structname">TriggerData</code> object passed to a trigger
+ handler function as <code class="literal">fcinfo-&gt;context</code>
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.33.9"><h2>Return Value</h2><p>
+ If the execution of the command was successful then the following
+ (nonnegative) value will be returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_TD_REGISTER</code></span></dt><dd><p>
+ if the captured trigger data (if any) has been successfully registered
+ </p></dd></dl></div><p>
+ </p><p>
+ On error, one of the following negative values is returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>tdata</code></em> is <code class="symbol">NULL</code>
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_REL_DUPLICATE</code></span></dt><dd><p>
+ if the name of any trigger data transient relation is already
+ registered for this connection
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-unregister-relation.html" title="SPI_unregister_relation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-interface-support.html" title="47.2. Interface Support Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_unregister_relation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.2. Interface Support Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-result-code-string.html b/doc/src/sgml/html/spi-spi-result-code-string.html
new file mode 100644
index 0000000..67988cb
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-result-code-string.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_result_code_string</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-getnspname.html" title="SPI_getnspname" /><link rel="next" href="spi-memory.html" title="47.3. Memory Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_result_code_string</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-getnspname.html" title="SPI_getnspname">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><th width="60%" align="center">47.2. Interface Support Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-memory.html" title="47.3. Memory Management">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-RESULT-CODE-STRING"><div class="titlepage"></div><a id="id-1.8.12.9.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_result_code_string</span></h2><p>SPI_result_code_string — return error code as string</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+const char * SPI_result_code_string(int <em class="parameter"><code>code</code></em>);
+</pre></div><div class="refsect1" id="id-1.8.12.9.12.5"><h2>Description</h2><p>
+ <code class="function">SPI_result_code_string</code> returns a string representation
+ of the result code returned by various SPI functions or stored
+ in <code class="varname">SPI_result</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.9.12.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">int <em class="parameter"><code>code</code></em></code></span></dt><dd><p>
+ result code
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.9.12.7"><h2>Return Value</h2><p>
+ A string representation of the result code.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-getnspname.html" title="SPI_getnspname">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface-support.html" title="47.2. Interface Support Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-memory.html" title="47.3. Memory Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_getnspname </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.3. Memory Management</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-returntuple.html b/doc/src/sgml/html/spi-spi-returntuple.html
new file mode 100644
index 0000000..026070b
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-returntuple.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_returntuple</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-copytuple.html" title="SPI_copytuple" /><link rel="next" href="spi-spi-modifytuple.html" title="SPI_modifytuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_returntuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-copytuple.html" title="SPI_copytuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-modifytuple.html" title="SPI_modifytuple">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-RETURNTUPLE"><div class="titlepage"></div><a id="id-1.8.12.10.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_returntuple</span></h2><p>SPI_returntuple — prepare to return a tuple as a Datum</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+HeapTupleHeader SPI_returntuple(HeapTuple <em class="parameter"><code>row</code></em>, TupleDesc <em class="parameter"><code>rowdesc</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.10.10.5"><h2>Description</h2><p>
+ <code class="function">SPI_returntuple</code> makes a copy of a row in
+ the upper executor context, returning it in the form of a row type <code class="type">Datum</code>.
+ The returned pointer need only be converted to <code class="type">Datum</code> via <code class="function">PointerGetDatum</code>
+ before returning.
+ </p><p>
+ This function can only be used while connected to SPI.
+ Otherwise, it returns NULL and sets <code class="varname">SPI_result</code> to
+ <code class="symbol">SPI_ERROR_UNCONNECTED</code>.
+ </p><p>
+ Note that this should be used for functions that are declared to return
+ composite types. It is not used for triggers; use
+ <code class="function">SPI_copytuple</code> for returning a modified row in a trigger.
+ </p></div><div class="refsect1" id="id-1.8.12.10.10.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>
+ row to be copied
+ </p></dd><dt><span class="term"><code class="literal">TupleDesc <em class="parameter"><code>rowdesc</code></em></code></span></dt><dd><p>
+ descriptor for row (pass the same descriptor each time for most
+ effective caching)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.10.7"><h2>Return Value</h2><p>
+ <code class="type">HeapTupleHeader</code> pointing to copied row,
+ or <code class="symbol">NULL</code> on error
+ (see <code class="varname">SPI_result</code> for an error indication)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-copytuple.html" title="SPI_copytuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-modifytuple.html" title="SPI_modifytuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_copytuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_modifytuple</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-rollback.html b/doc/src/sgml/html/spi-spi-rollback.html
new file mode 100644
index 0000000..91ae900
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-rollback.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_rollback</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-commit.html" title="SPI_commit" /><link rel="next" href="spi-spi-start-transaction.html" title="SPI_start_transaction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_rollback</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-commit.html" title="SPI_commit">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><th width="60%" align="center">47.4. Transaction Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-ROLLBACK"><div class="titlepage"></div><a id="id-1.8.12.11.5.1" class="indexterm"></a><a id="id-1.8.12.11.5.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_rollback</span></h2><p>SPI_rollback, SPI_rollback_and_chain — abort the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_rollback(void)
+</pre><pre class="synopsis">
+void SPI_rollback_and_chain(void)
+</pre></div><div class="refsect1" id="id-1.8.12.11.5.6"><h2>Description</h2><p>
+ <code class="function">SPI_rollback</code> rolls back the current transaction. It
+ is approximately equivalent to running the SQL
+ command <code class="command">ROLLBACK</code>. After the transaction is rolled back,
+ a new transaction is automatically started using default transaction
+ characteristics, so that the caller can continue using SPI facilities.
+ </p><p>
+ <code class="function">SPI_rollback_and_chain</code> is the same, but the new
+ transaction is started with the same transaction
+ characteristics as the just finished one, like with the SQL command
+ <code class="command">ROLLBACK AND CHAIN</code>.
+ </p><p>
+ These functions can only be executed if the SPI connection has been set as
+ nonatomic in the call to <code class="function">SPI_connect_ext</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-commit.html" title="SPI_commit">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_commit </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_start_transaction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-saveplan.html b/doc/src/sgml/html/spi-spi-saveplan.html
new file mode 100644
index 0000000..e3a825d
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-saveplan.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_saveplan</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-keepplan.html" title="SPI_keepplan" /><link rel="next" href="spi-spi-register-relation.html" title="SPI_register_relation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_saveplan</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-keepplan.html" title="SPI_keepplan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-register-relation.html" title="SPI_register_relation">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-SAVEPLAN"><div class="titlepage"></div><a id="id-1.8.12.8.30.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_saveplan</span></h2><p>SPI_saveplan — save a prepared statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_saveplan(SPIPlanPtr <em class="parameter"><code>plan</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.30.5"><h2>Description</h2><p>
+ <code class="function">SPI_saveplan</code> copies a passed statement (prepared by
+ <code class="function">SPI_prepare</code>) into memory that will not be freed
+ by <code class="function">SPI_finish</code> nor by the transaction manager,
+ and returns a pointer to the copied statement. This gives you the
+ ability to reuse prepared statements in the subsequent invocations of
+ your C function in the current session.
+ </p></div><div class="refsect1" id="id-1.8.12.8.30.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
+ the prepared statement to be saved
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.30.7"><h2>Return Value</h2><p>
+ Pointer to the copied statement; or <code class="symbol">NULL</code> if unsuccessful.
+ On error, <code class="varname">SPI_result</code> is set thus:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>plan</code></em> is <code class="symbol">NULL</code> or invalid
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.8.12.8.30.8"><h2>Notes</h2><p>
+ The originally passed-in statement is not freed, so you might wish to do
+ <code class="function">SPI_freeplan</code> on it to avoid leaking memory
+ until <code class="function">SPI_finish</code>.
+ </p><p>
+ In most cases, <code class="function">SPI_keepplan</code> is preferred to this
+ function, since it accomplishes largely the same result without needing
+ to physically copy the prepared statement's data structures.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-keepplan.html" title="SPI_keepplan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-register-relation.html" title="SPI_register_relation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_keepplan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_register_relation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-scroll-cursor-fetch.html b/doc/src/sgml/html/spi-spi-scroll-cursor-fetch.html
new file mode 100644
index 0000000..ddd25b3
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-scroll-cursor-fetch.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_scroll_cursor_fetch</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-cursor-move.html" title="SPI_cursor_move" /><link rel="next" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_scroll_cursor_fetch</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-move.html" title="SPI_cursor_move">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-SCROLL-CURSOR-FETCH"><div class="titlepage"></div><a id="id-1.8.12.8.26.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_scroll_cursor_fetch</span></h2><p>SPI_scroll_cursor_fetch — fetch some rows from a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_scroll_cursor_fetch(Portal <em class="parameter"><code>portal</code></em>, FetchDirection <em class="parameter"><code>direction</code></em>,
+ long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.26.5"><h2>Description</h2><p>
+ <code class="function">SPI_scroll_cursor_fetch</code> fetches some rows from a
+ cursor. This is equivalent to the SQL command <code class="command">FETCH</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.26.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Portal <em class="parameter"><code>portal</code></em></code></span></dt><dd><p>
+ portal containing the cursor
+ </p></dd><dt><span class="term"><code class="literal">FetchDirection <em class="parameter"><code>direction</code></em></code></span></dt><dd><p>
+ one of <code class="symbol">FETCH_FORWARD</code>,
+ <code class="symbol">FETCH_BACKWARD</code>,
+ <code class="symbol">FETCH_ABSOLUTE</code> or
+ <code class="symbol">FETCH_RELATIVE</code>
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ number of rows to fetch for
+ <code class="symbol">FETCH_FORWARD</code> or
+ <code class="symbol">FETCH_BACKWARD</code>; absolute row number to fetch for
+ <code class="symbol">FETCH_ABSOLUTE</code>; or relative row number to fetch for
+ <code class="symbol">FETCH_RELATIVE</code>
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.26.7"><h2>Return Value</h2><p>
+ <code class="varname">SPI_processed</code> and
+ <code class="varname">SPI_tuptable</code> are set as in
+ <code class="function">SPI_execute</code> if successful.
+ </p></div><div class="refsect1" id="id-1.8.12.8.26.8"><h2>Notes</h2><p>
+ See the SQL <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a> command
+ for details of the interpretation of the
+ <em class="parameter"><code>direction</code></em> and
+ <em class="parameter"><code>count</code></em> parameters.
+ </p><p>
+ Direction values other than <code class="symbol">FETCH_FORWARD</code>
+ may fail if the cursor's plan was not created
+ with the <code class="symbol">CURSOR_OPT_SCROLL</code> option.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-move.html" title="SPI_cursor_move">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-scroll-cursor-move.html" title="SPI_scroll_cursor_move">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_move </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_scroll_cursor_move</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-scroll-cursor-move.html b/doc/src/sgml/html/spi-spi-scroll-cursor-move.html
new file mode 100644
index 0000000..ed37da8
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-scroll-cursor-move.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_scroll_cursor_move</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch" /><link rel="next" href="spi-spi-cursor-close.html" title="SPI_cursor_close" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_scroll_cursor_move</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-close.html" title="SPI_cursor_close">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-SCROLL-CURSOR-MOVE"><div class="titlepage"></div><a id="id-1.8.12.8.27.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_scroll_cursor_move</span></h2><p>SPI_scroll_cursor_move — move a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_scroll_cursor_move(Portal <em class="parameter"><code>portal</code></em>, FetchDirection <em class="parameter"><code>direction</code></em>,
+ long <em class="parameter"><code>count</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.27.5"><h2>Description</h2><p>
+ <code class="function">SPI_scroll_cursor_move</code> skips over some number of rows
+ in a cursor. This is equivalent to the SQL command
+ <code class="command">MOVE</code>.
+ </p></div><div class="refsect1" id="id-1.8.12.8.27.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Portal <em class="parameter"><code>portal</code></em></code></span></dt><dd><p>
+ portal containing the cursor
+ </p></dd><dt><span class="term"><code class="literal">FetchDirection <em class="parameter"><code>direction</code></em></code></span></dt><dd><p>
+ one of <code class="symbol">FETCH_FORWARD</code>,
+ <code class="symbol">FETCH_BACKWARD</code>,
+ <code class="symbol">FETCH_ABSOLUTE</code> or
+ <code class="symbol">FETCH_RELATIVE</code>
+ </p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
+ number of rows to move for
+ <code class="symbol">FETCH_FORWARD</code> or
+ <code class="symbol">FETCH_BACKWARD</code>; absolute row number to move to for
+ <code class="symbol">FETCH_ABSOLUTE</code>; or relative row number to move to for
+ <code class="symbol">FETCH_RELATIVE</code>
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.27.7"><h2>Return Value</h2><p>
+ <code class="varname">SPI_processed</code> is set as in
+ <code class="function">SPI_execute</code> if successful.
+ <code class="varname">SPI_tuptable</code> is set to <code class="symbol">NULL</code>, since
+ no rows are returned by this function.
+ </p></div><div class="refsect1" id="id-1.8.12.8.27.8"><h2>Notes</h2><p>
+ See the SQL <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a> command
+ for details of the interpretation of the
+ <em class="parameter"><code>direction</code></em> and
+ <em class="parameter"><code>count</code></em> parameters.
+ </p><p>
+ Direction values other than <code class="symbol">FETCH_FORWARD</code>
+ may fail if the cursor's plan was not created
+ with the <code class="symbol">CURSOR_OPT_SCROLL</code> option.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-scroll-cursor-fetch.html" title="SPI_scroll_cursor_fetch">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-close.html" title="SPI_cursor_close">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_scroll_cursor_fetch </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_close</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-start-transaction.html b/doc/src/sgml/html/spi-spi-start-transaction.html
new file mode 100644
index 0000000..7367fbf
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-start-transaction.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_start_transaction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-rollback.html" title="SPI_rollback" /><link rel="next" href="spi-visibility.html" title="47.5. Visibility of Data Changes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_start_transaction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-rollback.html" title="SPI_rollback">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><th width="60%" align="center">47.4. Transaction Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-visibility.html" title="47.5. Visibility of Data Changes">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-START-TRANSACTION"><div class="titlepage"></div><a id="id-1.8.12.11.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_start_transaction</span></h2><p>SPI_start_transaction — obsolete function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+void SPI_start_transaction(void)
+</pre></div><div class="refsect1" id="id-1.8.12.11.6.5"><h2>Description</h2><p>
+ <code class="function">SPI_start_transaction</code> does nothing, and exists
+ only for code compatibility with
+ earlier <span class="productname">PostgreSQL</span> releases. It used to
+ be required after calling <code class="function">SPI_commit</code>
+ or <code class="function">SPI_rollback</code>, but now those functions start
+ a new transaction automatically.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-rollback.html" title="SPI_rollback">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-transaction.html" title="47.4. Transaction Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-visibility.html" title="47.5. Visibility of Data Changes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_rollback </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.5. Visibility of Data Changes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-spi-unregister-relation.html b/doc/src/sgml/html/spi-spi-unregister-relation.html
new file mode 100644
index 0000000..453d69a
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-unregister-relation.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_unregister_relation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-register-relation.html" title="SPI_register_relation" /><link rel="next" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_unregister_relation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-register-relation.html" title="SPI_register_relation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-UNREGISTER-RELATION"><div class="titlepage"></div><a id="id-1.8.12.8.32.1" class="indexterm"></a><a id="id-1.8.12.8.32.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_unregister_relation</span></h2><p>SPI_unregister_relation — remove an ephemeral named relation from the registry</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+int SPI_unregister_relation(const char * <em class="parameter"><code>name</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.32.6"><h2>Description</h2><p>
+ <code class="function">SPI_unregister_relation</code> removes an ephemeral named
+ relation from the registry for the current connection.
+ </p></div><div class="refsect1" id="id-1.8.12.8.32.7"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
+ the relation registry entry name
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.32.8"><h2>Return Value</h2><p>
+ If the execution of the command was successful then the following
+ (nonnegative) value will be returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_REL_UNREGISTER</code></span></dt><dd><p>
+ if the tuplestore has been successfully removed from the registry
+ </p></dd></dl></div><p>
+ </p><p>
+ On error, one of the following negative values is returned:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
+ if <em class="parameter"><code>name</code></em> is <code class="symbol">NULL</code>
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
+ if called from an unconnected C function
+ </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_REL_NOT_FOUND</code></span></dt><dd><p>
+ if <em class="parameter"><code>name</code></em> is not found in the registry for the
+ current connection
+ </p></dd></dl></div><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-register-relation.html" title="SPI_register_relation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_register_relation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_register_trigger_data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-transaction.html b/doc/src/sgml/html/spi-transaction.html
new file mode 100644
index 0000000..2c2eab5
--- /dev/null
+++ b/doc/src/sgml/html/spi-transaction.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.4. Transaction Management</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-freeplan.html" title="SPI_freeplan" /><link rel="next" href="spi-spi-commit.html" title="SPI_commit" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.4. Transaction Management</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-freeplan.html" title="SPI_freeplan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-commit.html" title="SPI_commit">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-TRANSACTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.4. Transaction Management</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="spi-spi-commit.html">SPI_commit</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="spi-spi-rollback.html">SPI_rollback</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="spi-spi-start-transaction.html">SPI_start_transaction</a></span><span class="refpurpose"> — obsolete function</span></dt></dl></div><p>
+ It is not possible to run transaction control commands such
+ as <code class="command">COMMIT</code> and <code class="command">ROLLBACK</code> through SPI
+ functions such as <code class="function">SPI_execute</code>. There are, however,
+ separate interface functions that allow transaction control through SPI.
+ </p><p>
+ It is not generally safe and sensible to start and end transactions in
+ arbitrary user-defined SQL-callable functions without taking into account
+ the context in which they are called. For example, a transaction boundary
+ in the middle of a function that is part of a complex SQL expression that
+ is part of some SQL command will probably result in obscure internal errors
+ or crashes. The interface functions presented here are primarily intended
+ to be used by procedural language implementations to support transaction
+ management in SQL-level procedures that are invoked by the <code class="command">CALL</code>
+ command, taking the context of the <code class="command">CALL</code> invocation into
+ account. SPI-using procedures implemented in C can implement the same logic, but
+ the details of that are beyond the scope of this documentation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-freeplan.html" title="SPI_freeplan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-commit.html" title="SPI_commit">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_freeplan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_commit</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi-visibility.html b/doc/src/sgml/html/spi-visibility.html
new file mode 100644
index 0000000..101334d
--- /dev/null
+++ b/doc/src/sgml/html/spi-visibility.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>47.5. Visibility of Data Changes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-start-transaction.html" title="SPI_start_transaction" /><link rel="next" href="spi-examples.html" title="47.6. Examples" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.5. Visibility of Data Changes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><th width="60%" align="center">Chapter 47. Server Programming Interface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-examples.html" title="47.6. Examples">Next</a></td></tr></table><hr /></div><div class="sect1" id="SPI-VISIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.5. Visibility of Data Changes</h2></div></div></div><p>
+ The following rules govern the visibility of data changes in
+ functions that use SPI (or any other C function):
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ During the execution of an SQL command, any data changes made by
+ the command are invisible to the command itself. For
+ example, in:
+</p><pre class="programlisting">
+INSERT INTO a SELECT * FROM a;
+</pre><p>
+ the inserted rows are invisible to the <code class="command">SELECT</code>
+ part.
+ </p></li><li class="listitem"><p>
+ Changes made by a command C are visible to all commands that are
+ started after C, no matter whether they are started inside C
+ (during the execution of C) or after C is done.
+ </p></li><li class="listitem"><p>
+ Commands executed via SPI inside a function called by an SQL command
+ (either an ordinary function or a trigger) follow one or the
+ other of the above rules depending on the read/write flag passed
+ to SPI. Commands executed in read-only mode follow the first
+ rule: they cannot see changes of the calling command. Commands executed
+ in read-write mode follow the second rule: they can see all changes made
+ so far.
+ </p></li><li class="listitem"><p>
+ All standard procedural languages set the SPI read-write mode
+ depending on the volatility attribute of the function. Commands of
+ <code class="literal">STABLE</code> and <code class="literal">IMMUTABLE</code> functions are done in
+ read-only mode, while commands of <code class="literal">VOLATILE</code> functions are
+ done in read-write mode. While authors of C functions are able to
+ violate this convention, it's unlikely to be a good idea to do so.
+ </p></li></ul></div><p>
+ </p><p>
+ The next section contains an example that illustrates the
+ application of these rules.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-start-transaction.html" title="SPI_start_transaction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi.html" title="Chapter 47. Server Programming Interface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-examples.html" title="47.6. Examples">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_start_transaction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.6. Examples</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/spi.html b/doc/src/sgml/html/spi.html
new file mode 100644
index 0000000..e681931
--- /dev/null
+++ b/doc/src/sgml/html/spi.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 47. Server Programming Interface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-envar.html" title="46.11. Environment Variables" /><link rel="next" href="spi-interface.html" title="47.1. Interface Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 47. Server Programming Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-envar.html" title="46.11. Environment Variables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-interface.html" title="47.1. Interface Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="SPI"><div class="titlepage"><div><div><h2 class="title">Chapter 47. Server Programming Interface</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="spi-interface.html">47.1. Interface Functions</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="spi-spi-connect.html">SPI_connect</a></span><span class="refpurpose"> — connect a C function to the SPI manager</span></dt><dt><span class="refentrytitle"><a href="spi-spi-finish.html">SPI_finish</a></span><span class="refpurpose"> — disconnect a C function from the SPI manager</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute.html">SPI_execute</a></span><span class="refpurpose"> — execute a command</span></dt><dt><span class="refentrytitle"><a href="spi-spi-exec.html">SPI_exec</a></span><span class="refpurpose"> — execute a read/write command</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-extended.html">SPI_execute_extended</a></span><span class="refpurpose"> — execute a command with out-of-line parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-with-args.html">SPI_execute_with_args</a></span><span class="refpurpose"> — execute a command with out-of-line parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare.html">SPI_prepare</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-cursor.html">SPI_prepare_cursor</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-extended.html">SPI_prepare_extended</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-prepare-params.html">SPI_prepare_params</a></span><span class="refpurpose"> — prepare a statement, without executing it yet</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getargcount.html">SPI_getargcount</a></span><span class="refpurpose"> — return the number of arguments needed by a statement
+ prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-getargtypeid.html">SPI_getargtypeid</a></span><span class="refpurpose"> — return the data type OID for an argument of
+ a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-is-cursor-plan.html">SPI_is_cursor_plan</a></span><span class="refpurpose"> — return <code class="symbol">true</code> if a statement
+ prepared by <code class="function">SPI_prepare</code> can be used with
+ <code class="function">SPI_cursor_open</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan.html">SPI_execute_plan</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan-extended.html">SPI_execute_plan_extended</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execute-plan-with-paramlist.html">SPI_execute_plan_with_paramlist</a></span><span class="refpurpose"> — execute a statement prepared by <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-execp.html">SPI_execp</a></span><span class="refpurpose"> — execute a statement in read/write mode</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open.html">SPI_cursor_open</a></span><span class="refpurpose"> — set up a cursor using a statement created with <code class="function">SPI_prepare</code></span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open-with-args.html">SPI_cursor_open_with_args</a></span><span class="refpurpose"> — set up a cursor using a query and parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-open-with-paramlist.html">SPI_cursor_open_with_paramlist</a></span><span class="refpurpose"> — set up a cursor using parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-parse-open.html">SPI_cursor_parse_open</a></span><span class="refpurpose"> — set up a cursor using a query string and parameters</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-find.html">SPI_cursor_find</a></span><span class="refpurpose"> — find an existing cursor by name</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-fetch.html">SPI_cursor_fetch</a></span><span class="refpurpose"> — fetch some rows from a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-move.html">SPI_cursor_move</a></span><span class="refpurpose"> — move a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-scroll-cursor-fetch.html">SPI_scroll_cursor_fetch</a></span><span class="refpurpose"> — fetch some rows from a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-scroll-cursor-move.html">SPI_scroll_cursor_move</a></span><span class="refpurpose"> — move a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-cursor-close.html">SPI_cursor_close</a></span><span class="refpurpose"> — close a cursor</span></dt><dt><span class="refentrytitle"><a href="spi-spi-keepplan.html">SPI_keepplan</a></span><span class="refpurpose"> — save a prepared statement</span></dt><dt><span class="refentrytitle"><a href="spi-spi-saveplan.html">SPI_saveplan</a></span><span class="refpurpose"> — save a prepared statement</span></dt><dt><span class="refentrytitle"><a href="spi-spi-register-relation.html">SPI_register_relation</a></span><span class="refpurpose"> — make an ephemeral named relation available by name in SPI queries</span></dt><dt><span class="refentrytitle"><a href="spi-spi-unregister-relation.html">SPI_unregister_relation</a></span><span class="refpurpose"> — remove an ephemeral named relation from the registry</span></dt><dt><span class="refentrytitle"><a href="spi-spi-register-trigger-data.html">SPI_register_trigger_data</a></span><span class="refpurpose"> — make ephemeral trigger data available in SPI queries</span></dt></dl></dd><dt><span class="sect1"><a href="spi-interface-support.html">47.2. Interface Support Functions</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="spi-spi-fname.html">SPI_fname</a></span><span class="refpurpose"> — determine the column name for the specified column number</span></dt><dt><span class="refentrytitle"><a href="spi-spi-fnumber.html">SPI_fnumber</a></span><span class="refpurpose"> — determine the column number for the specified column name</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getvalue.html">SPI_getvalue</a></span><span class="refpurpose"> — return the string value of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getbinval.html">SPI_getbinval</a></span><span class="refpurpose"> — return the binary value of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-gettype.html">SPI_gettype</a></span><span class="refpurpose"> — return the data type name of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-gettypeid.html">SPI_gettypeid</a></span><span class="refpurpose"> — return the data type <acronym class="acronym">OID</acronym> of the specified column</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getrelname.html">SPI_getrelname</a></span><span class="refpurpose"> — return the name of the specified relation</span></dt><dt><span class="refentrytitle"><a href="spi-spi-getnspname.html">SPI_getnspname</a></span><span class="refpurpose"> — return the namespace of the specified relation</span></dt><dt><span class="refentrytitle"><a href="spi-spi-result-code-string.html">SPI_result_code_string</a></span><span class="refpurpose"> — return error code as string</span></dt></dl></dd><dt><span class="sect1"><a href="spi-memory.html">47.3. Memory Management</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="spi-spi-palloc.html">SPI_palloc</a></span><span class="refpurpose"> — allocate memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-realloc.html">SPI_repalloc</a></span><span class="refpurpose"> — reallocate memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-pfree.html">SPI_pfree</a></span><span class="refpurpose"> — free memory in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-copytuple.html">SPI_copytuple</a></span><span class="refpurpose"> — make a copy of a row in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-returntuple.html">SPI_returntuple</a></span><span class="refpurpose"> — prepare to return a tuple as a Datum</span></dt><dt><span class="refentrytitle"><a href="spi-spi-modifytuple.html">SPI_modifytuple</a></span><span class="refpurpose"> — create a row by replacing selected fields of a given row</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freetuple.html">SPI_freetuple</a></span><span class="refpurpose"> — free a row allocated in the upper executor context</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freetupletable.html">SPI_freetuptable</a></span><span class="refpurpose"> — free a row set created by <code class="function">SPI_execute</code> or a similar
+ function</span></dt><dt><span class="refentrytitle"><a href="spi-spi-freeplan.html">SPI_freeplan</a></span><span class="refpurpose"> — free a previously saved prepared statement</span></dt></dl></dd><dt><span class="sect1"><a href="spi-transaction.html">47.4. Transaction Management</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="spi-spi-commit.html">SPI_commit</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="spi-spi-rollback.html">SPI_rollback</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="spi-spi-start-transaction.html">SPI_start_transaction</a></span><span class="refpurpose"> — obsolete function</span></dt></dl></dd><dt><span class="sect1"><a href="spi-visibility.html">47.5. Visibility of Data Changes</a></span></dt><dt><span class="sect1"><a href="spi-examples.html">47.6. Examples</a></span></dt></dl></div><a id="id-1.8.12.2" class="indexterm"></a><p>
+ The <em class="firstterm">Server Programming Interface</em>
+ (<acronym class="acronym">SPI</acronym>) gives writers of user-defined
+ <acronym class="acronym">C</acronym> functions the ability to run
+ <acronym class="acronym">SQL</acronym> commands inside their functions or procedures.
+ <acronym class="acronym">SPI</acronym> is a set of
+ interface functions to simplify access to the parser, planner,
+ and executor. <acronym class="acronym">SPI</acronym> also does some
+ memory management.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The available procedural languages provide various means to
+ execute SQL commands from functions. Most of these facilities are
+ based on SPI, so this documentation might be of use for users
+ of those languages as well.
+ </p></div><p>
+ Note that if a command invoked via SPI fails, then control will not be
+ returned to your C function. Rather, the
+ transaction or subtransaction in which your C function executes will be
+ rolled back. (This might seem surprising given that the SPI functions mostly
+ have documented error-return conventions. Those conventions only apply
+ for errors detected within the SPI functions themselves, however.)
+ It is possible to recover control after an error by establishing your own
+ subtransaction surrounding SPI calls that might fail.
+ </p><p>
+ <acronym class="acronym">SPI</acronym> functions return a nonnegative result on
+ success (either via a returned integer value or in the global
+ variable <code class="varname">SPI_result</code>, as described below). On
+ error, a negative result or <code class="symbol">NULL</code> will be returned.
+ </p><p>
+ Source code files that use SPI must include the header file
+ <code class="filename">executor/spi.h</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-envar.html" title="46.11. Environment Variables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-interface.html" title="47.1. Interface Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.11. Environment Variables </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 47.1. Interface Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-abort.html b/doc/src/sgml/html/sql-abort.html
new file mode 100644
index 0000000..f85a92d
--- /dev/null
+++ b/doc/src/sgml/html/sql-abort.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ABORT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-commands.html" title="SQL Commands" /><link rel="next" href="sql-alteraggregate.html" title="ALTER AGGREGATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ABORT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-commands.html" title="SQL Commands">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteraggregate.html" title="ALTER AGGREGATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ABORT"><div class="titlepage"></div><a id="id-1.9.3.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ABORT</span></h2><p>ABORT — abort the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ABORT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
+</pre></div><div class="refsect1" id="id-1.9.3.3.5"><h2>Description</h2><p>
+ <code class="command">ABORT</code> rolls back the current transaction and causes
+ all the updates made by the transaction to be discarded.
+ This command is identical
+ in behavior to the standard <acronym class="acronym">SQL</acronym> command
+ <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a>,
+ and is present only for historical reasons.
+ </p></div><div class="refsect1" id="id-1.9.3.3.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">WORK</code><br /></span><span class="term"><code class="literal">TRANSACTION</code></span></dt><dd><p>
+ Optional key words. They have no effect.
+ </p></dd><dt><span class="term"><code class="literal">AND CHAIN</code></span></dt><dd><p>
+ If <code class="literal">AND CHAIN</code> is specified, a new transaction is
+ immediately started with the same transaction characteristics (see <a class="link" href="sql-set-transaction.html" title="SET TRANSACTION"><code class="command">SET TRANSACTION</code></a>) as the just finished one. Otherwise,
+ no new transaction is started.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.3.7"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a> to
+ successfully terminate a transaction.
+ </p><p>
+ Issuing <code class="command">ABORT</code> outside of a transaction block
+ emits a warning and otherwise has no effect.
+ </p></div><div class="refsect1" id="id-1.9.3.3.8"><h2>Examples</h2><p>
+ To abort all changes:
+</p><pre class="programlisting">
+ABORT;
+</pre></div><div class="refsect1" id="id-1.9.3.3.9"><h2>Compatibility</h2><p>
+ This command is a <span class="productname">PostgreSQL</span> extension
+ present for historical reasons. <code class="command">ROLLBACK</code> is the
+ equivalent standard SQL command.
+ </p></div><div class="refsect1" id="id-1.9.3.3.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-commands.html" title="SQL Commands">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteraggregate.html" title="ALTER AGGREGATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SQL Commands </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER AGGREGATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alteraggregate.html b/doc/src/sgml/html/sql-alteraggregate.html
new file mode 100644
index 0000000..fb1de03
--- /dev/null
+++ b/doc/src/sgml/html/sql-alteraggregate.html
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER AGGREGATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-abort.html" title="ABORT" /><link rel="next" href="sql-altercollation.html" title="ALTER COLLATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER AGGREGATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-abort.html" title="ABORT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altercollation.html" title="ALTER COLLATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERAGGREGATE"><div class="titlepage"></div><a id="id-1.9.3.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER AGGREGATE</span></h2><p>ALTER AGGREGATE — change the definition of an aggregate function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER AGGREGATE <em class="replaceable"><code>name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER AGGREGATE <em class="replaceable"><code>name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> )
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER AGGREGATE <em class="replaceable"><code>name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
+
+* |
+[ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
+[ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.4.5"><h2>Description</h2><p>
+ <code class="command">ALTER AGGREGATE</code> changes the definition of an
+ aggregate function.
+ </p><p>
+ You must own the aggregate function to use <code class="command">ALTER AGGREGATE</code>.
+ To change the schema of an aggregate function, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the aggregate function's schema. (These restrictions enforce that altering
+ the owner doesn't do anything you couldn't do by dropping and recreating
+ the aggregate function. However, a superuser can alter ownership of any
+ aggregate function anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.4.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing aggregate function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code> or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">ALTER AGGREGATE</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the aggregate function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ An input data type on which the aggregate function operates.
+ To reference a zero-argument aggregate function, write <code class="literal">*</code>
+ in place of the list of argument specifications.
+ To reference an ordered-set aggregate function, write
+ <code class="literal">ORDER BY</code> between the direct and aggregated argument
+ specifications.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the aggregate function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the aggregate function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the aggregate function.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.4.7"><h2>Notes</h2><p>
+ The recommended syntax for referencing an ordered-set aggregate
+ is to write <code class="literal">ORDER BY</code> between the direct and aggregated
+ argument specifications, in the same style as in
+ <a class="link" href="sql-createaggregate.html" title="CREATE AGGREGATE"><code class="command">CREATE AGGREGATE</code></a>. However, it will also work to
+ omit <code class="literal">ORDER BY</code> and just run the direct and aggregated
+ argument specifications into a single list. In this abbreviated form,
+ if <code class="literal">VARIADIC "any"</code> was used in both the direct and
+ aggregated argument lists, write <code class="literal">VARIADIC "any"</code> only once.
+ </p></div><div class="refsect1" id="id-1.9.3.4.8"><h2>Examples</h2><p>
+ To rename the aggregate function <code class="literal">myavg</code> for type
+ <code class="type">integer</code> to <code class="literal">my_average</code>:
+</p><pre class="programlisting">
+ALTER AGGREGATE myavg(integer) RENAME TO my_average;
+</pre><p>
+ </p><p>
+ To change the owner of the aggregate function <code class="literal">myavg</code> for type
+ <code class="type">integer</code> to <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER AGGREGATE myavg(integer) OWNER TO joe;
+</pre><p>
+ </p><p>
+ To move the ordered-set aggregate <code class="literal">mypercentile</code> with
+ direct argument of type <code class="type">float8</code> and aggregated argument
+ of type <code class="type">integer</code> into schema <code class="literal">myschema</code>:
+</p><pre class="programlisting">
+ALTER AGGREGATE mypercentile(float8 ORDER BY integer) SET SCHEMA myschema;
+</pre><p>
+ This will work too:
+</p><pre class="programlisting">
+ALTER AGGREGATE mypercentile(float8, integer) SET SCHEMA myschema;
+</pre></div><div class="refsect1" id="id-1.9.3.4.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER AGGREGATE</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.4.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a>, <a class="xref" href="sql-dropaggregate.html" title="DROP AGGREGATE"><span class="refentrytitle">DROP AGGREGATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-abort.html" title="ABORT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altercollation.html" title="ALTER COLLATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ABORT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER COLLATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altercollation.html b/doc/src/sgml/html/sql-altercollation.html
new file mode 100644
index 0000000..1293dce
--- /dev/null
+++ b/doc/src/sgml/html/sql-altercollation.html
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER COLLATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alteraggregate.html" title="ALTER AGGREGATE" /><link rel="next" href="sql-alterconversion.html" title="ALTER CONVERSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER COLLATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alteraggregate.html" title="ALTER AGGREGATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterconversion.html" title="ALTER CONVERSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERCOLLATION"><div class="titlepage"></div><a id="id-1.9.3.5.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER COLLATION</span></h2><p>ALTER COLLATION — change the definition of a collation</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER COLLATION <em class="replaceable"><code>name</code></em> REFRESH VERSION
+
+ALTER COLLATION <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER COLLATION <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER COLLATION <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.5.5"><h2>Description</h2><p>
+ <code class="command">ALTER COLLATION</code> changes the definition of a
+ collation.
+ </p><p>
+ You must own the collation to use <code class="command">ALTER COLLATION</code>.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the collation's schema. (These restrictions enforce that altering the
+ owner doesn't do anything you couldn't do by dropping and recreating the
+ collation. However, a superuser can alter ownership of any collation
+ anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.5.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing collation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the collation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the collation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the collation.
+ </p></dd><dt><span class="term"><code class="literal">REFRESH VERSION</code></span></dt><dd><p>
+ Update the collation's version.
+ See <a class="xref" href="sql-altercollation.html#SQL-ALTERCOLLATION-NOTES" title="Notes">Notes</a> below.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-ALTERCOLLATION-NOTES"><h2>Notes</h2><p>
+ When a collation object is created, the provider-specific version of the
+ collation is recorded in the system catalog. When the collation is used,
+ the current version is
+ checked against the recorded version, and a warning is issued when there is
+ a mismatch, for example:
+</p><pre class="screen">
+WARNING: collation "xx-x-icu" has version mismatch
+DETAIL: The collation in the database was created using version 1.2.3.4, but the operating system provides version 2.3.4.5.
+HINT: Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog."xx-x-icu" REFRESH VERSION, or build PostgreSQL with the right library version.
+</pre><p>
+ A change in collation definitions can lead to corrupt indexes and other
+ problems because the database system relies on stored objects having a
+ certain sort order. Generally, this should be avoided, but it can happen
+ in legitimate circumstances, such as when upgrading the operating system
+ to a new major version or when
+ using <code class="command">pg_upgrade</code> to upgrade to server binaries linked
+ with a newer version of ICU. When this happens, all objects depending on
+ the collation should be rebuilt, for example,
+ using <code class="command">REINDEX</code>. When that is done, the collation version
+ can be refreshed using the command <code class="literal">ALTER COLLATION ... REFRESH
+ VERSION</code>. This will update the system catalog to record the
+ current collation version and will make the warning go away. Note that this
+ does not actually check whether all affected objects have been rebuilt
+ correctly.
+ </p><p>
+ When using collations provided by <code class="literal">libc</code>, version
+ information is recorded on systems using the GNU C library (most Linux
+ systems), FreeBSD and Windows. When using collations provided by ICU, the
+ version information is provided by the ICU library and is available on all
+ platforms.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When using the GNU C library for collations, the C library's version
+ is used as a proxy for the collation version. Many Linux distributions
+ change collation definitions only when upgrading the C library, but this
+ approach is imperfect as maintainers are free to back-port newer
+ collation definitions to older C library releases.
+ </p><p>
+ When using Windows for collations, version information is only available
+ for collations defined with BCP 47 language tags such as
+ <code class="literal">en-US</code>.
+ </p></div><p>
+ For the database default collation, there is an analogous command
+ <code class="literal">ALTER DATABASE ... REFRESH COLLATION VERSION</code>.
+ </p><p>
+ The following query can be used to identify all collations in the current
+ database that need to be refreshed and the objects that depend on them:
+</p><pre class="programlisting">
+SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation",
+ pg_describe_object(classid, objid, objsubid) AS "Object"
+ FROM pg_depend d JOIN pg_collation c
+ ON refclassid = 'pg_collation'::regclass AND refobjid = c.oid
+ WHERE c.collversion &lt;&gt; pg_collation_actual_version(c.oid)
+ ORDER BY 1, 2;
+</pre></div><div class="refsect1" id="id-1.9.3.5.8"><h2>Examples</h2><p>
+ To rename the collation <code class="literal">de_DE</code> to
+ <code class="literal">german</code>:
+</p><pre class="programlisting">
+ALTER COLLATION "de_DE" RENAME TO german;
+</pre><p>
+ </p><p>
+ To change the owner of the collation <code class="literal">en_US</code> to
+ <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER COLLATION "en_US" OWNER TO joe;
+</pre></div><div class="refsect1" id="id-1.9.3.5.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER COLLATION</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.5.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createcollation.html" title="CREATE COLLATION"><span class="refentrytitle">CREATE COLLATION</span></a>, <a class="xref" href="sql-dropcollation.html" title="DROP COLLATION"><span class="refentrytitle">DROP COLLATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alteraggregate.html" title="ALTER AGGREGATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterconversion.html" title="ALTER CONVERSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER AGGREGATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER CONVERSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterconversion.html b/doc/src/sgml/html/sql-alterconversion.html
new file mode 100644
index 0000000..7f840f2
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterconversion.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER CONVERSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altercollation.html" title="ALTER COLLATION" /><link rel="next" href="sql-alterdatabase.html" title="ALTER DATABASE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER CONVERSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altercollation.html" title="ALTER COLLATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterdatabase.html" title="ALTER DATABASE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERCONVERSION"><div class="titlepage"></div><a id="id-1.9.3.6.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER CONVERSION</span></h2><p>ALTER CONVERSION — change the definition of a conversion</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER CONVERSION <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER CONVERSION <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER CONVERSION <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.6.5"><h2>Description</h2><p>
+ <code class="command">ALTER CONVERSION</code> changes the definition of a
+ conversion.
+ </p><p>
+ You must own the conversion to use <code class="command">ALTER CONVERSION</code>.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the conversion's schema. (These restrictions enforce that altering the
+ owner doesn't do anything you couldn't do by dropping and recreating the
+ conversion. However, a superuser can alter ownership of any conversion
+ anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.6.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing conversion.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the conversion.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the conversion.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the conversion.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.6.7"><h2>Examples</h2><p>
+ To rename the conversion <code class="literal">iso_8859_1_to_utf8</code> to
+ <code class="literal">latin1_to_unicode</code>:
+</p><pre class="programlisting">
+ALTER CONVERSION iso_8859_1_to_utf8 RENAME TO latin1_to_unicode;
+</pre><p>
+ </p><p>
+ To change the owner of the conversion <code class="literal">iso_8859_1_to_utf8</code> to
+ <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe;
+</pre></div><div class="refsect1" id="id-1.9.3.6.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER CONVERSION</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.6.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createconversion.html" title="CREATE CONVERSION"><span class="refentrytitle">CREATE CONVERSION</span></a>, <a class="xref" href="sql-dropconversion.html" title="DROP CONVERSION"><span class="refentrytitle">DROP CONVERSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altercollation.html" title="ALTER COLLATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterdatabase.html" title="ALTER DATABASE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER COLLATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER DATABASE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterdatabase.html b/doc/src/sgml/html/sql-alterdatabase.html
new file mode 100644
index 0000000..94ef74b
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterdatabase.html
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER DATABASE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterconversion.html" title="ALTER CONVERSION" /><link rel="next" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER DATABASE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterconversion.html" title="ALTER CONVERSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERDATABASE"><div class="titlepage"></div><a id="id-1.9.3.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER DATABASE</span></h2><p>ALTER DATABASE — change a database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER DATABASE <em class="replaceable"><code>name</code></em> [ [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ ALLOW_CONNECTIONS <em class="replaceable"><code>allowconn</code></em>
+ CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ IS_TEMPLATE <em class="replaceable"><code>istemplate</code></em>
+
+ALTER DATABASE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER DATABASE <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+
+ALTER DATABASE <em class="replaceable"><code>name</code></em> SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em>
+
+ALTER DATABASE <em class="replaceable"><code>name</code></em> REFRESH COLLATION VERSION
+
+ALTER DATABASE <em class="replaceable"><code>name</code></em> SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ALTER DATABASE <em class="replaceable"><code>name</code></em> SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ALTER DATABASE <em class="replaceable"><code>name</code></em> RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ALTER DATABASE <em class="replaceable"><code>name</code></em> RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.7.5"><h2>Description</h2><p>
+ <code class="command">ALTER DATABASE</code> changes the attributes
+ of a database.
+ </p><p>
+ The first form changes certain per-database settings. (See below for
+ details.) Only the database owner or a superuser can change these settings.
+ </p><p>
+ The second form changes the name of the database. Only the database
+ owner or a superuser can rename a database; non-superuser owners must
+ also have the
+ <code class="literal">CREATEDB</code> privilege. The current database cannot
+ be renamed. (Connect to a different database if you need to do
+ that.)
+ </p><p>
+ The third form changes the owner of the database.
+ To alter the owner, you must own the database and also be a direct or
+ indirect member of the new owning role, and you must have the
+ <code class="literal">CREATEDB</code> privilege.
+ (Note that superusers have all these privileges automatically.)
+ </p><p>
+ The fourth form changes the default tablespace of the database.
+ Only the database owner or a superuser can do this; you must also have
+ create privilege for the new tablespace.
+ This command physically moves any tables or indexes in the database's old
+ default tablespace to the new tablespace. The new default tablespace
+ must be empty for this database, and no one can be connected to
+ the database. Tables and indexes in non-default tablespaces are
+ unaffected.
+ </p><p>
+ The remaining forms change the session default for a run-time
+ configuration variable for a <span class="productname">PostgreSQL</span>
+ database. Whenever a new session is subsequently started in that
+ database, the specified value becomes the session default value.
+ The database-specific default overrides whatever setting is present
+ in <code class="filename">postgresql.conf</code> or has been received from the
+ <code class="command">postgres</code> command line. Only the database
+ owner or a superuser can change the session defaults for a
+ database. Certain variables cannot be set this way, or can only be
+ set by a superuser.
+ </p></div><div class="refsect1" id="id-1.9.3.7.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the database whose attributes are to be altered.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>allowconn</code></em></span></dt><dd><p>
+ If false then no one can connect to this database.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>connlimit</code></em></span></dt><dd><p>
+ How many concurrent connections can be made
+ to this database. -1 means no limit.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>istemplate</code></em></span></dt><dd><p>
+ If true, then this database can be cloned by any user with <code class="literal">CREATEDB</code>
+ privileges; if false, then only superusers or the owner of the
+ database can clone it.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the database.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the database.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_tablespace</code></em></span></dt><dd><p>
+ The new default tablespace of the database.
+ </p><p>
+ This form of the command cannot be executed inside a transaction block.
+ </p></dd><dt><span class="term"><code class="literal">REFRESH COLLATION VERSION</code></span></dt><dd><p>
+ Update the database collation version. See <a class="xref" href="sql-altercollation.html#SQL-ALTERCOLLATION-NOTES" title="Notes">Notes</a> for background.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ Set this database's session default for the specified configuration
+ parameter to the given value. If
+ <em class="replaceable"><code>value</code></em> is <code class="literal">DEFAULT</code>
+ or, equivalently, <code class="literal">RESET</code> is used, the
+ database-specific setting is removed, so the system-wide default
+ setting will be inherited in new sessions. Use <code class="literal">RESET
+ ALL</code> to clear all database-specific settings.
+ <code class="literal">SET FROM CURRENT</code> saves the session's current value of
+ the parameter as the database-specific value.
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information about allowed parameter names
+ and values.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.7.7"><h2>Notes</h2><p>
+ It is also possible to tie a session default to a specific role
+ rather than to a database; see
+ <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>.
+ Role-specific settings override database-specific
+ ones if there is a conflict.
+ </p></div><div class="refsect1" id="id-1.9.3.7.8"><h2>Examples</h2><p>
+ To disable index scans by default in the database
+ <code class="literal">test</code>:
+
+</p><pre class="programlisting">
+ALTER DATABASE test SET enable_indexscan TO off;
+</pre></div><div class="refsect1" id="id-1.9.3.7.9"><h2>Compatibility</h2><p>
+ The <code class="command">ALTER DATABASE</code> statement is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.7.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>, <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a>, <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>, <a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterconversion.html" title="ALTER CONVERSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER CONVERSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER DEFAULT PRIVILEGES</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterdefaultprivileges.html b/doc/src/sgml/html/sql-alterdefaultprivileges.html
new file mode 100644
index 0000000..ce7f496
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterdefaultprivileges.html
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER DEFAULT PRIVILEGES</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterdatabase.html" title="ALTER DATABASE" /><link rel="next" href="sql-alterdomain.html" title="ALTER DOMAIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER DEFAULT PRIVILEGES</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterdatabase.html" title="ALTER DATABASE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterdomain.html" title="ALTER DOMAIN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERDEFAULTPRIVILEGES"><div class="titlepage"></div><a id="id-1.9.3.8.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER DEFAULT PRIVILEGES</span></h2><p>ALTER DEFAULT PRIVILEGES — define default access privileges</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER DEFAULT PRIVILEGES
+ [ FOR { ROLE | USER } <em class="replaceable"><code>target_role</code></em> [, ...] ]
+ [ IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] ]
+ <em class="replaceable"><code>abbreviated_grant_or_revoke</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>abbreviated_grant_or_revoke</code></em> is one of:</span>
+
+GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON TABLES
+ TO { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { { USAGE | SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON SEQUENCES
+ TO { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { EXECUTE | ALL [ PRIVILEGES ] }
+ ON { FUNCTIONS | ROUTINES }
+ TO { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON TYPES
+ TO { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { USAGE | CREATE | ALL [ PRIVILEGES ] }
+ ON SCHEMAS
+ TO { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON TABLES
+ FROM { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { USAGE | SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON SEQUENCES
+ FROM { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { EXECUTE | ALL [ PRIVILEGES ] }
+ ON { FUNCTIONS | ROUTINES }
+ FROM { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON TYPES
+ FROM { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | CREATE | ALL [ PRIVILEGES ] }
+ ON SCHEMAS
+ FROM { [ GROUP ] <em class="replaceable"><code>role_name</code></em> | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="SQL-ALTERDEFAULTPRIVILEGES-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">ALTER DEFAULT PRIVILEGES</code> allows you to set the privileges
+ that will be applied to objects created in the future. (It does not
+ affect privileges assigned to already-existing objects.) Currently,
+ only the privileges for schemas, tables (including views and foreign
+ tables), sequences, functions, and types (including domains) can be
+ altered. For this command, functions include aggregates and procedures.
+ The words <code class="literal">FUNCTIONS</code> and <code class="literal">ROUTINES</code> are
+ equivalent in this command. (<code class="literal">ROUTINES</code> is preferred
+ going forward as the standard term for functions and procedures taken
+ together. In earlier PostgreSQL releases, only the
+ word <code class="literal">FUNCTIONS</code> was allowed. It is not possible to set
+ default privileges for functions and procedures separately.)
+ </p><p>
+ You can change default privileges only for objects that will be created by
+ yourself or by roles that you are a member of. The privileges can be set
+ globally (i.e., for all objects created in the current database),
+ or just for objects created in specified schemas.
+ </p><p>
+ As explained in <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>,
+ the default privileges for any object type normally grant all grantable
+ permissions to the object owner, and may grant some privileges to
+ <code class="literal">PUBLIC</code> as well. However, this behavior can be changed by
+ altering the global default privileges with
+ <code class="command">ALTER DEFAULT PRIVILEGES</code>.
+ </p><p>
+ Default privileges that are specified per-schema are added to whatever
+ the global default privileges are for the particular object type.
+ This means you cannot revoke privileges per-schema if they are granted
+ globally (either by default, or according to a previous <code class="command">ALTER
+ DEFAULT PRIVILEGES</code> command that did not specify a schema).
+ Per-schema <code class="literal">REVOKE</code> is only useful to reverse the
+ effects of a previous per-schema <code class="literal">GRANT</code>.
+ </p><div class="refsect2" id="id-1.9.3.8.5.6"><h3>Parameters</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>target_role</code></em></span></dt><dd><p>
+ The name of an existing role of which the current role is a member.
+ Default access privileges are not inherited, so member roles
+ must use <code class="command">SET ROLE</code> to access these privileges,
+ or <code class="command">ALTER DEFAULT PRIVILEGES</code> must be run for
+ each member role. If <code class="literal">FOR ROLE</code> is omitted,
+ the current role is assumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>schema_name</code></em></span></dt><dd><p>
+ The name of an existing schema. If specified, the default privileges
+ are altered for objects later created in that schema.
+ If <code class="literal">IN SCHEMA</code> is omitted, the global default privileges
+ are altered.
+ <code class="literal">IN SCHEMA</code> is not allowed when setting privileges
+ for schemas, since schemas can't be nested.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The name of an existing role to grant or revoke privileges for.
+ This parameter, and all the other parameters in
+ <em class="replaceable"><code>abbreviated_grant_or_revoke</code></em>,
+ act as described under
+ <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> or
+ <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>,
+ except that one is setting permissions for a whole class of objects
+ rather than specific named objects.
+ </p></dd></dl></div></div></div><div class="refsect1" id="SQL-ALTERDEFAULTPRIVILEGES-NOTES"><h2>Notes</h2><p>
+ Use <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>'s <code class="command">\ddp</code> command
+ to obtain information about existing assignments of default privileges.
+ The meaning of the privilege display is the same as explained for
+ <code class="command">\dp</code> in <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.
+ </p><p>
+ If you wish to drop a role for which the default privileges have been
+ altered, it is necessary to reverse the changes in its default privileges
+ or use <code class="command">DROP OWNED BY</code> to get rid of the default privileges entry
+ for the role.
+ </p></div><div class="refsect1" id="SQL-ALTERDEFAULTPRIVILEGES-EXAMPLES"><h2>Examples</h2><p>
+ Grant SELECT privilege to everyone for all tables (and views) you
+ subsequently create in schema <code class="literal">myschema</code>, and allow
+ role <code class="literal">webuser</code> to INSERT into them too:
+
+</p><pre class="programlisting">
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLES TO PUBLIC;
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT INSERT ON TABLES TO webuser;
+</pre><p>
+ </p><p>
+ Undo the above, so that subsequently-created tables won't have any
+ more permissions than normal:
+
+</p><pre class="programlisting">
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE SELECT ON TABLES FROM PUBLIC;
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser;
+</pre><p>
+ </p><p>
+ Remove the public EXECUTE permission that is normally granted on functions,
+ for all functions subsequently created by role <code class="literal">admin</code>:
+</p><pre class="programlisting">
+ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
+</pre><p>
+ Note however that you <span class="emphasis"><em>cannot</em></span> accomplish that effect
+ with a command limited to a single schema. This command has no effect,
+ unless it is undoing a matching <code class="literal">GRANT</code>:
+</p><pre class="programlisting">
+ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
+</pre><p>
+ That's because per-schema default privileges can only add privileges to
+ the global setting, not remove privileges granted by it.
+ </p></div><div class="refsect1" id="id-1.9.3.8.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER DEFAULT PRIVILEGES</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.8.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterdatabase.html" title="ALTER DATABASE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterdomain.html" title="ALTER DOMAIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER DATABASE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER DOMAIN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterdomain.html b/doc/src/sgml/html/sql-alterdomain.html
new file mode 100644
index 0000000..d8bcb6e
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterdomain.html
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER DOMAIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES" /><link rel="next" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER DOMAIN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERDOMAIN"><div class="titlepage"></div><a id="id-1.9.3.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER DOMAIN</span></h2><p>ALTER DOMAIN —
+ change the definition of a domain
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ { SET DEFAULT <em class="replaceable"><code>expression</code></em> | DROP DEFAULT }
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ { SET | DROP } NOT NULL
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ ADD <em class="replaceable"><code>domain_constraint</code></em> [ NOT VALID ]
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ DROP CONSTRAINT [ IF EXISTS ] <em class="replaceable"><code>constraint_name</code></em> [ RESTRICT | CASCADE ]
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ RENAME CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> TO <em class="replaceable"><code>new_constraint_name</code></em>
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ VALIDATE CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER DOMAIN <em class="replaceable"><code>name</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.9.5"><h2>Description</h2><p>
+ <code class="command">ALTER DOMAIN</code> changes the definition of an existing domain.
+ There are several sub-forms:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP DEFAULT</code></span></dt><dd><p>
+ These forms set or remove the default value for a domain. Note
+ that defaults only apply to subsequent <code class="command">INSERT</code>
+ commands; they do not affect rows already in a table using the domain.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP NOT NULL</code></span></dt><dd><p>
+ These forms change whether a domain is marked to allow NULL
+ values or to reject NULL values. You can only <code class="literal">SET NOT NULL</code>
+ when the columns using the domain contain no null values.
+ </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>domain_constraint</code></em> [ NOT VALID ]</code></span></dt><dd><p>
+ This form adds a new constraint to a domain using the same syntax as
+ <a class="link" href="sql-createdomain.html" title="CREATE DOMAIN"><code class="command">CREATE DOMAIN</code></a>.
+ When a new constraint is added to a domain, all columns using that
+ domain will be checked against the newly added constraint. These
+ checks can be suppressed by adding the new constraint using the
+ <code class="literal">NOT VALID</code> option; the constraint can later be made
+ valid using <code class="command">ALTER DOMAIN ... VALIDATE CONSTRAINT</code>.
+ Newly inserted or updated rows are always checked against all
+ constraints, even those marked <code class="literal">NOT VALID</code>.
+ <code class="literal">NOT VALID</code> is only accepted for <code class="literal">CHECK</code> constraints.
+ </p></dd><dt><span class="term"><code class="literal">DROP CONSTRAINT [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops constraints on a domain.
+ If <code class="literal">IF EXISTS</code> is specified and the constraint
+ does not exist, no error is thrown. In this case a notice is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">RENAME CONSTRAINT</code></span></dt><dd><p>
+ This form changes the name of a constraint on a domain.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATE CONSTRAINT</code></span></dt><dd><p>
+ This form validates a constraint previously added as
+ <code class="literal">NOT VALID</code>, that is, it verifies that all values in
+ table columns of the domain type satisfy the specified constraint.
+ </p></dd><dt><span class="term"><code class="literal">OWNER</code></span></dt><dd><p>
+ This form changes the owner of the domain to the specified user.
+ </p></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
+ This form changes the name of the domain.
+ </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
+ This form changes the schema of the domain. Any constraints
+ associated with the domain are moved into the new schema as well.
+ </p></dd></dl></div><p>
+ You must own the domain to use <code class="command">ALTER DOMAIN</code>.
+ To change the schema of a domain, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the domain's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the domain.
+ However, a superuser can alter ownership of any domain anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.9.6"><h2>Parameters</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of an existing domain to
+ alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>domain_constraint</code></em></span></dt><dd><p>
+ New domain constraint for the domain.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>
+ Name of an existing constraint to drop or rename.
+ </p></dd><dt><span class="term"><code class="literal">NOT VALID</code></span></dt><dd><p>
+ Do not verify existing stored data for constraint validity.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the constraint,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the constraint if there are any dependent
+ objects. This is the default behavior.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the domain.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_constraint_name</code></em></span></dt><dd><p>
+ The new name for the constraint.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the domain.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the domain.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.9.7"><h2>Notes</h2><p>
+ Although <code class="command">ALTER DOMAIN ADD CONSTRAINT</code> attempts to verify
+ that existing stored data satisfies the new constraint, this check is not
+ bulletproof, because the command cannot <span class="quote">“<span class="quote">see</span>”</span> table rows that
+ are newly inserted or updated and not yet committed. If there is a hazard
+ that concurrent operations might insert bad data, the way to proceed is to
+ add the constraint using the <code class="literal">NOT VALID</code> option, commit
+ that command, wait until all transactions started before that commit have
+ finished, and then issue <code class="command">ALTER DOMAIN VALIDATE
+ CONSTRAINT</code> to search for data violating the constraint. This
+ method is reliable because once the constraint is committed, all new
+ transactions are guaranteed to enforce it against new values of the domain
+ type.
+ </p><p>
+ Currently, <code class="command">ALTER DOMAIN ADD CONSTRAINT</code>, <code class="command">ALTER
+ DOMAIN VALIDATE CONSTRAINT</code>, and <code class="command">ALTER DOMAIN SET NOT
+ NULL</code> will fail if the named domain or any derived domain is used
+ within a container-type column (a composite, array, or range column) in
+ any table in the database. They should eventually be improved to be able
+ to verify the new constraint for such nested values.
+ </p></div><div class="refsect1" id="id-1.9.3.9.8"><h2>Examples</h2><p>
+ To add a <code class="literal">NOT NULL</code> constraint to a domain:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode SET NOT NULL;
+</pre><p>
+ To remove a <code class="literal">NOT NULL</code> constraint from a domain:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode DROP NOT NULL;
+</pre><p>
+ </p><p>
+ To add a check constraint to a domain:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
+</pre><p>
+ </p><p>
+ To remove a check constraint from a domain:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
+</pre><p>
+ </p><p>
+ To rename a check constraint on a domain:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode RENAME CONSTRAINT zipchk TO zip_check;
+</pre><p>
+ </p><p>
+ To move the domain into a different schema:
+</p><pre class="programlisting">
+ALTER DOMAIN zipcode SET SCHEMA customers;
+</pre></div><div class="refsect1" id="SQL-ALTERDOMAIN-COMPATIBILITY"><h2>Compatibility</h2><p>
+ <code class="command">ALTER DOMAIN</code> conforms to the <acronym class="acronym">SQL</acronym>
+ standard, except for the <code class="literal">OWNER</code>, <code class="literal">RENAME</code>, <code class="literal">SET SCHEMA</code>, and
+ <code class="literal">VALIDATE CONSTRAINT</code> variants, which are
+ <span class="productname">PostgreSQL</span> extensions. The <code class="literal">NOT VALID</code>
+ clause of the <code class="literal">ADD CONSTRAINT</code> variant is also a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="SQL-ALTERDOMAIN-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>, <a class="xref" href="sql-dropdomain.html" title="DROP DOMAIN"><span class="refentrytitle">DROP DOMAIN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER DEFAULT PRIVILEGES </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER EVENT TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altereventtrigger.html b/doc/src/sgml/html/sql-altereventtrigger.html
new file mode 100644
index 0000000..c580e0b
--- /dev/null
+++ b/doc/src/sgml/html/sql-altereventtrigger.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER EVENT TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterdomain.html" title="ALTER DOMAIN" /><link rel="next" href="sql-alterextension.html" title="ALTER EXTENSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER EVENT TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterdomain.html" title="ALTER DOMAIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterextension.html" title="ALTER EXTENSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTEREVENTTRIGGER"><div class="titlepage"></div><a id="id-1.9.3.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER EVENT TRIGGER</span></h2><p>ALTER EVENT TRIGGER — change the definition of an event trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER EVENT TRIGGER <em class="replaceable"><code>name</code></em> DISABLE
+ALTER EVENT TRIGGER <em class="replaceable"><code>name</code></em> ENABLE [ REPLICA | ALWAYS ]
+ALTER EVENT TRIGGER <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER EVENT TRIGGER <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.10.5"><h2>Description</h2><p>
+ <code class="command">ALTER EVENT TRIGGER</code> changes properties of an
+ existing event trigger.
+ </p><p>
+ You must be superuser to alter an event trigger.
+ </p></div><div class="refsect1" id="id-1.9.3.10.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing trigger to alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the event trigger.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the event trigger.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE [ REPLICA | ALWAYS ] TRIGGER</code></span></dt><dd><p>
+ These forms configure the firing of event triggers. A disabled trigger
+ is still known to the system, but is not executed when its triggering
+ event occurs. See also <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a>.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-ALTERVENTTRIGGER-COMPATIBILITY"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER EVENT TRIGGER</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.10.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER"><span class="refentrytitle">CREATE EVENT TRIGGER</span></a>, <a class="xref" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER"><span class="refentrytitle">DROP EVENT TRIGGER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterdomain.html" title="ALTER DOMAIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterextension.html" title="ALTER EXTENSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER DOMAIN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER EXTENSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterextension.html b/doc/src/sgml/html/sql-alterextension.html
new file mode 100644
index 0000000..3f709d4
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterextension.html
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER EXTENSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER" /><link rel="next" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER EXTENSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTEREXTENSION"><div class="titlepage"></div><a id="id-1.9.3.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER EXTENSION</span></h2><p>ALTER EXTENSION —
+ change the definition of an extension
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER EXTENSION <em class="replaceable"><code>name</code></em> UPDATE [ TO <em class="replaceable"><code>new_version</code></em> ]
+ALTER EXTENSION <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER EXTENSION <em class="replaceable"><code>name</code></em> ADD <em class="replaceable"><code>member_object</code></em>
+ALTER EXTENSION <em class="replaceable"><code>name</code></em> DROP <em class="replaceable"><code>member_object</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>member_object</code></em> is:</span>
+
+ ACCESS METHOD <em class="replaceable"><code>object_name</code></em> |
+ AGGREGATE <em class="replaceable"><code>aggregate_name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) |
+ CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>) |
+ COLLATION <em class="replaceable"><code>object_name</code></em> |
+ CONVERSION <em class="replaceable"><code>object_name</code></em> |
+ DOMAIN <em class="replaceable"><code>object_name</code></em> |
+ EVENT TRIGGER <em class="replaceable"><code>object_name</code></em> |
+ FOREIGN DATA WRAPPER <em class="replaceable"><code>object_name</code></em> |
+ FOREIGN TABLE <em class="replaceable"><code>object_name</code></em> |
+ FUNCTION <em class="replaceable"><code>function_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ MATERIALIZED VIEW <em class="replaceable"><code>object_name</code></em> |
+ OPERATOR <em class="replaceable"><code>operator_name</code></em> (<em class="replaceable"><code>left_type</code></em>, <em class="replaceable"><code>right_type</code></em>) |
+ OPERATOR CLASS <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
+ OPERATOR FAMILY <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
+ [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>object_name</code></em> |
+ PROCEDURE <em class="replaceable"><code>procedure_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ ROUTINE <em class="replaceable"><code>routine_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ SCHEMA <em class="replaceable"><code>object_name</code></em> |
+ SEQUENCE <em class="replaceable"><code>object_name</code></em> |
+ SERVER <em class="replaceable"><code>object_name</code></em> |
+ TABLE <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH CONFIGURATION <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH DICTIONARY <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH PARSER <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH TEMPLATE <em class="replaceable"><code>object_name</code></em> |
+ TRANSFORM FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> |
+ TYPE <em class="replaceable"><code>object_name</code></em> |
+ VIEW <em class="replaceable"><code>object_name</code></em>
+
+<span class="phrase">and <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
+
+* |
+[ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
+[ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.11.5"><h2>Description</h2><p>
+ <code class="command">ALTER EXTENSION</code> changes the definition of an installed
+ extension. There are several subforms:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">UPDATE</code></span></dt><dd><p>
+ This form updates the extension to a newer version. The extension
+ must supply a suitable update script (or series of scripts) that can
+ modify the currently-installed version into the requested version.
+ </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
+ This form moves the extension's objects into another schema. The
+ extension has to be <em class="firstterm">relocatable</em> for this command to
+ succeed.
+ </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>member_object</code></em></code></span></dt><dd><p>
+ This form adds an existing object to the extension. This is mainly
+ useful in extension update scripts. The object will subsequently
+ be treated as a member of the extension; notably, it can only be
+ dropped by dropping the extension.
+ </p></dd><dt><span class="term"><code class="literal">DROP <em class="replaceable"><code>member_object</code></em></code></span></dt><dd><p>
+ This form removes a member object from the extension. This is mainly
+ useful in extension update scripts. The object is not dropped, only
+ disassociated from the extension.
+ </p></dd></dl></div><p>
+
+ See <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a> for more information about these
+ operations.
+ </p><p>
+ You must own the extension to use <code class="command">ALTER EXTENSION</code>.
+ The <code class="literal">ADD</code>/<code class="literal">DROP</code> forms require ownership of the
+ added/dropped object as well.
+ </p></div><div class="refsect1" id="id-1.9.3.11.6"><h2>Parameters</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an installed extension.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_version</code></em></span></dt><dd><p>
+ The desired new version of the extension. This can be written as
+ either an identifier or a string literal. If not specified,
+ <code class="command">ALTER EXTENSION UPDATE</code> attempts to update to whatever is
+ shown as the default version in the extension's control file.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the extension.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>object_name</code></em><br /></span><span class="term"><em class="replaceable"><code>aggregate_name</code></em><br /></span><span class="term"><em class="replaceable"><code>function_name</code></em><br /></span><span class="term"><em class="replaceable"><code>operator_name</code></em><br /></span><span class="term"><em class="replaceable"><code>procedure_name</code></em><br /></span><span class="term"><em class="replaceable"><code>routine_name</code></em></span></dt><dd><p>
+ The name of an object to be added to or removed from the extension.
+ Names of tables,
+ aggregates, domains, foreign tables, functions, operators,
+ operator classes, operator families, procedures, routines, sequences, text search objects,
+ types, and views can be schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_type</code></em></span></dt><dd><p>
+ The name of the source data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>target_type</code></em></span></dt><dd><p>
+ The name of the target data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of a function, procedure, or aggregate
+ argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Note that <code class="command">ALTER EXTENSION</code> does not actually pay
+ any attention to <code class="literal">OUT</code> arguments, since only the input
+ arguments are needed to determine the function's identity.
+ So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
+ and <code class="literal">VARIADIC</code> arguments.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of a function, procedure, or aggregate argument.
+ Note that <code class="command">ALTER EXTENSION</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type of a function, procedure, or aggregate argument.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em><br /></span><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
+ The data type(s) of the operator's arguments (optionally
+ schema-qualified). Write <code class="literal">NONE</code> for the missing argument
+ of a prefix operator.
+ </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p>
+ This is a noise word.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
+ The name of the data type of the transform.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language of the transform.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.11.7"><h2>Examples</h2><p>
+ To update the <code class="literal">hstore</code> extension to version 2.0:
+</p><pre class="programlisting">
+ALTER EXTENSION hstore UPDATE TO '2.0';
+</pre><p>
+ </p><p>
+ To change the schema of the <code class="literal">hstore</code> extension
+ to <code class="literal">utils</code>:
+</p><pre class="programlisting">
+ALTER EXTENSION hstore SET SCHEMA utils;
+</pre><p>
+ </p><p>
+ To add an existing function to the <code class="literal">hstore</code> extension:
+</p><pre class="programlisting">
+ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore);
+</pre></div><div class="refsect1" id="id-1.9.3.11.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER EXTENSION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="SQL-ALTEREXTENSION-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createextension.html" title="CREATE EXTENSION"><span class="refentrytitle">CREATE EXTENSION</span></a>, <a class="xref" href="sql-dropextension.html" title="DROP EXTENSION"><span class="refentrytitle">DROP EXTENSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER EVENT TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER FOREIGN DATA WRAPPER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterforeigndatawrapper.html b/doc/src/sgml/html/sql-alterforeigndatawrapper.html
new file mode 100644
index 0000000..843019d
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterforeigndatawrapper.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER FOREIGN DATA WRAPPER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterextension.html" title="ALTER EXTENSION" /><link rel="next" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER FOREIGN DATA WRAPPER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterextension.html" title="ALTER EXTENSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERFOREIGNDATAWRAPPER"><div class="titlepage"></div><a id="id-1.9.3.12.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER FOREIGN DATA WRAPPER</span></h2><p>ALTER FOREIGN DATA WRAPPER — change the definition of a foreign-data wrapper</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER FOREIGN DATA WRAPPER <em class="replaceable"><code>name</code></em>
+ [ HANDLER <em class="replaceable"><code>handler_function</code></em> | NO HANDLER ]
+ [ VALIDATOR <em class="replaceable"><code>validator_function</code></em> | NO VALIDATOR ]
+ [ OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ]) ]
+ALTER FOREIGN DATA WRAPPER <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER FOREIGN DATA WRAPPER <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.12.5"><h2>Description</h2><p>
+ <code class="command">ALTER FOREIGN DATA WRAPPER</code> changes the
+ definition of a foreign-data wrapper. The first form of the
+ command changes the support functions or the generic options of the
+ foreign-data wrapper (at least one clause is required). The second
+ form changes the owner of the foreign-data wrapper.
+ </p><p>
+ Only superusers can alter foreign-data wrappers. Additionally,
+ only superusers can own foreign-data wrappers.
+ </p></div><div class="refsect1" id="id-1.9.3.12.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing foreign-data wrapper.
+ </p></dd><dt><span class="term"><code class="literal">HANDLER <em class="replaceable"><code>handler_function</code></em></code></span></dt><dd><p>
+ Specifies a new handler function for the foreign-data wrapper.
+ </p></dd><dt><span class="term"><code class="literal">NO HANDLER</code></span></dt><dd><p>
+ This is used to specify that the foreign-data wrapper should no
+ longer have a handler function.
+ </p><p>
+ Note that foreign tables that use a foreign-data wrapper with no
+ handler cannot be accessed.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATOR <em class="replaceable"><code>validator_function</code></em></code></span></dt><dd><p>
+ Specifies a new validator function for the foreign-data wrapper.
+ </p><p>
+ Note that it is possible that pre-existing options of the foreign-data
+ wrapper, or of dependent servers, user mappings, or foreign tables, are
+ invalid according to the new validator. <span class="productname">PostgreSQL</span> does
+ not check for this. It is up to the user to make sure that these
+ options are correct before using the modified foreign-data wrapper.
+ However, any options specified in this <code class="command">ALTER FOREIGN DATA
+ WRAPPER</code> command will be checked using the new validator.
+ </p></dd><dt><span class="term"><code class="literal">NO VALIDATOR</code></span></dt><dd><p>
+ This is used to specify that the foreign-data wrapper should no
+ longer have a validator function.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )</code></span></dt><dd><p>
+ Change options for the foreign-data
+ wrapper. <code class="literal">ADD</code>, <code class="literal">SET</code>, and <code class="literal">DROP</code>
+ specify the action to be performed. <code class="literal">ADD</code> is assumed
+ if no operation is explicitly specified. Option names must be
+ unique; names and values are also validated using the foreign
+ data wrapper's validator function, if any.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the foreign-data wrapper.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the foreign-data wrapper.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.12.7"><h2>Examples</h2><p>
+ Change a foreign-data wrapper <code class="literal">dbi</code>, add
+ option <code class="literal">foo</code>, drop <code class="literal">bar</code>:
+</p><pre class="programlisting">
+ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP 'bar');
+</pre><p>
+ </p><p>
+ Change the foreign-data wrapper <code class="literal">dbi</code> validator
+ to <code class="literal">bob.myvalidator</code>:
+</p><pre class="programlisting">
+ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator;
+</pre></div><div class="refsect1" id="id-1.9.3.12.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER FOREIGN DATA WRAPPER</code> conforms to ISO/IEC
+ 9075-9 (SQL/MED), except that the <code class="literal">HANDLER</code>,
+ <code class="literal">VALIDATOR</code>, <code class="literal">OWNER TO</code>, and <code class="literal">RENAME</code>
+ clauses are extensions.
+ </p></div><div class="refsect1" id="id-1.9.3.12.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER"><span class="refentrytitle">DROP FOREIGN DATA WRAPPER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterextension.html" title="ALTER EXTENSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER EXTENSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER FOREIGN TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterforeigntable.html b/doc/src/sgml/html/sql-alterforeigntable.html
new file mode 100644
index 0000000..f49de80
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterforeigntable.html
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER FOREIGN TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER" /><link rel="next" href="sql-alterfunction.html" title="ALTER FUNCTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER FOREIGN TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterfunction.html" title="ALTER FUNCTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERFOREIGNTABLE"><div class="titlepage"></div><a id="id-1.9.3.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER FOREIGN TABLE</span></h2><p>ALTER FOREIGN TABLE — change the definition of a foreign table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
+ <em class="replaceable"><code>action</code></em> [, ... ]
+ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
+ RENAME [ COLUMN ] <em class="replaceable"><code>column_name</code></em> TO <em class="replaceable"><code>new_column_name</code></em>
+ALTER FOREIGN TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER FOREIGN TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ ADD [ COLUMN ] <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ DROP [ COLUMN ] [ IF EXISTS ] <em class="replaceable"><code>column_name</code></em> [ RESTRICT | CASCADE ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> [ SET DATA ] TYPE <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET DEFAULT <em class="replaceable"><code>expression</code></em>
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP DEFAULT
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> { SET | DROP } NOT NULL
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STATISTICS <em class="replaceable"><code>integer</code></em>
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ])
+ ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]
+ VALIDATE CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>
+ DROP CONSTRAINT [ IF EXISTS ] <em class="replaceable"><code>constraint_name</code></em> [ RESTRICT | CASCADE ]
+ DISABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
+ ENABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
+ ENABLE REPLICA TRIGGER <em class="replaceable"><code>trigger_name</code></em>
+ ENABLE ALWAYS TRIGGER <em class="replaceable"><code>trigger_name</code></em>
+ SET WITHOUT OIDS
+ INHERIT <em class="replaceable"><code>parent_table</code></em>
+ NO INHERIT <em class="replaceable"><code>parent_table</code></em>
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ])
+</pre></div><div class="refsect1" id="id-1.9.3.13.5"><h2>Description</h2><p>
+ <code class="command">ALTER FOREIGN TABLE</code> changes the definition of an
+ existing foreign table. There are several subforms:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ADD COLUMN</code></span></dt><dd><p>
+ This form adds a new column to the foreign table, using the same syntax as
+ <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.
+ Unlike the case when adding a column to a regular table, nothing happens
+ to the underlying storage: this action simply declares that
+ some new column is now accessible through the foreign table.
+ </p></dd><dt><span class="term"><code class="literal">DROP COLUMN [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops a column from a foreign table.
+ You will need to say <code class="literal">CASCADE</code> if
+ anything outside the table depends on the column; for example,
+ views.
+ If <code class="literal">IF EXISTS</code> is specified and the column
+ does not exist, no error is thrown. In this case a notice
+ is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">SET DATA TYPE</code></span></dt><dd><p>
+ This form changes the type of a column of a foreign table.
+ Again, this has no effect on any underlying storage: this action simply
+ changes the type that <span class="productname">PostgreSQL</span> believes the column to
+ have.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP DEFAULT</code></span></dt><dd><p>
+ These forms set or remove the default value for a column.
+ Default values only apply in subsequent <code class="command">INSERT</code>
+ or <code class="command">UPDATE</code> commands; they do not cause rows already in the
+ table to change.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP NOT NULL</code></span></dt><dd><p>
+ Mark a column as allowing, or not allowing, null values.
+ </p></dd><dt><span class="term"><code class="literal">SET STATISTICS</code></span></dt><dd><p>
+ This form
+ sets the per-column statistics-gathering target for subsequent
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> operations.
+ See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ for more details.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )</code><br /></span><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )</code></span></dt><dd><p>
+ This form sets or resets per-attribute options.
+ See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ for more details.
+ </p></dd><dt><span class="term">
+ <code class="literal">SET STORAGE</code>
+ </span></dt><dd><p>
+ This form sets the storage mode for a column.
+ See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ for more details.
+ Note that the storage mode has no effect unless the table's
+ foreign-data wrapper chooses to pay attention to it.
+ </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]</code></span></dt><dd><p>
+ This form adds a new constraint to a foreign table, using the same
+ syntax as <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.
+ Currently only <code class="literal">CHECK</code> constraints are supported.
+ </p><p>
+ Unlike the case when adding a constraint to a regular table, nothing is
+ done to verify the constraint is correct; rather, this action simply
+ declares that some new condition should be assumed to hold for all rows
+ in the foreign table. (See the discussion
+ in <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.)
+ If the constraint is marked <code class="literal">NOT VALID</code>, then it isn't
+ assumed to hold, but is only recorded for possible future use.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATE CONSTRAINT</code></span></dt><dd><p>
+ This form marks as valid a constraint that was previously marked
+ as <code class="literal">NOT VALID</code>. No action is taken to verify the
+ constraint, but future queries will assume that it holds.
+ </p></dd><dt><span class="term"><code class="literal">DROP CONSTRAINT [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops the specified constraint on a foreign table.
+ If <code class="literal">IF EXISTS</code> is specified and the constraint
+ does not exist, no error is thrown.
+ In this case a notice is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE [ REPLICA | ALWAYS ] TRIGGER</code></span></dt><dd><p>
+ These forms configure the firing of trigger(s) belonging to the foreign
+ table. See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> for more
+ details.
+ </p></dd><dt><span class="term"><code class="literal">SET WITHOUT OIDS</code></span></dt><dd><p>
+ Backward compatibility syntax for removing the <code class="literal">oid</code>
+ system column. As <code class="literal">oid</code> system columns cannot be added
+ anymore, this never has an effect.
+ </p></dd><dt><span class="term"><code class="literal">INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
+ This form adds the target foreign table as a new child of the specified
+ parent table.
+ See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ for more details.
+ </p></dd><dt><span class="term"><code class="literal">NO INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
+ This form removes the target foreign table from the list of children of
+ the specified parent table.
+ </p></dd><dt><span class="term"><code class="literal">OWNER</code></span></dt><dd><p>
+ This form changes the owner of the foreign table to the
+ specified user.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )</code></span></dt><dd><p>
+ Change options for the foreign table or one of its columns.
+ <code class="literal">ADD</code>, <code class="literal">SET</code>, and <code class="literal">DROP</code>
+ specify the action to be performed. <code class="literal">ADD</code> is assumed
+ if no operation is explicitly specified. Duplicate option names are not
+ allowed (although it's OK for a table option and a column option to have
+ the same name). Option names and values are also validated using the
+ foreign data wrapper library.
+ </p></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
+ The <code class="literal">RENAME</code> forms change the name of a foreign table
+ or the name of an individual column in a foreign table.
+ </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
+ This form moves the foreign table into another schema.
+ </p></dd></dl></div><p>
+ </p><p>
+ All the actions except <code class="literal">RENAME</code> and <code class="literal">SET SCHEMA</code>
+ can be combined into
+ a list of multiple alterations to apply in parallel. For example, it
+ is possible to add several columns and/or alter the type of several
+ columns in a single command.
+ </p><p>
+ If the command is written as <code class="literal">ALTER FOREIGN TABLE IF EXISTS ...</code>
+ and the foreign table does not exist, no error is thrown. A notice is
+ issued in this case.
+ </p><p>
+ You must own the table to use <code class="command">ALTER FOREIGN TABLE</code>.
+ To change the schema of a foreign table, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the table's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the table.
+ However, a superuser can alter ownership of any table anyway.)
+ To add a column or alter a column type, you must also
+ have <code class="literal">USAGE</code> privilege on the data type.
+ </p></div><div class="refsect1" id="id-1.9.3.13.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of an existing foreign table to
+ alter. If <code class="literal">ONLY</code> is specified before the table name, only
+ that table is altered. If <code class="literal">ONLY</code> is not specified, the table
+ and all its descendant tables (if any) are altered. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ Name of a new or existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_column_name</code></em></span></dt><dd><p>
+ New name for an existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ New name for the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ Data type of the new column, or new data type for an existing
+ column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_constraint</code></em></span></dt><dd><p>
+ New table constraint for the foreign table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>
+ Name of an existing constraint to drop.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the dropped column
+ or constraint (for example, views referencing the column),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the column or constraint if there are any dependent
+ objects. This is the default behavior.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>trigger_name</code></em></span></dt><dd><p>
+ Name of a single trigger to disable or enable.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Disable or enable all triggers belonging to the foreign table. (This
+ requires superuser privilege if any of the triggers are internally
+ generated triggers. The core system does not add such triggers to
+ foreign tables, but add-on code could do so.)
+ </p></dd><dt><span class="term"><code class="literal">USER</code></span></dt><dd><p>
+ Disable or enable all triggers belonging to the foreign table except
+ for internally generated triggers.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>parent_table</code></em></span></dt><dd><p>
+ A parent table to associate or de-associate with this foreign table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The name of the schema to which the table will be moved.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.13.7"><h2>Notes</h2><p>
+ The key word <code class="literal">COLUMN</code> is noise and can be omitted.
+ </p><p>
+ Consistency with the foreign server is not checked when a column is added
+ or removed with <code class="literal">ADD COLUMN</code> or
+ <code class="literal">DROP COLUMN</code>, a <code class="literal">NOT NULL</code>
+ or <code class="literal">CHECK</code> constraint is added, or a column type is changed
+ with <code class="literal">SET DATA TYPE</code>. It is the user's responsibility to ensure
+ that the table definition matches the remote side.
+ </p><p>
+ Refer to <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a> for a further description of valid
+ parameters.
+ </p></div><div class="refsect1" id="id-1.9.3.13.8"><h2>Examples</h2><p>
+ To mark a column as not-null:
+</p><pre class="programlisting">
+ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
+</pre><p>
+ </p><p>
+ To change options of a foreign table:
+</p><pre class="programlisting">
+ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3);
+</pre></div><div class="refsect1" id="id-1.9.3.13.9"><h2>Compatibility</h2><p>
+ The forms <code class="literal">ADD</code>, <code class="literal">DROP</code>,
+ and <code class="literal">SET DATA TYPE</code>
+ conform with the SQL standard. The other forms are
+ <span class="productname">PostgreSQL</span> extensions of the SQL standard.
+ Also, the ability to specify more than one manipulation in a single
+ <code class="command">ALTER FOREIGN TABLE</code> command is an extension.
+ </p><p>
+ <code class="command">ALTER FOREIGN TABLE DROP COLUMN</code> can be used to drop the only
+ column of a foreign table, leaving a zero-column table. This is an
+ extension of SQL, which disallows zero-column foreign tables.
+ </p></div><div class="refsect1" id="id-1.9.3.13.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>, <a class="xref" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE"><span class="refentrytitle">DROP FOREIGN TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterfunction.html" title="ALTER FUNCTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER FOREIGN DATA WRAPPER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER FUNCTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterfunction.html b/doc/src/sgml/html/sql-alterfunction.html
new file mode 100644
index 0000000..54944e3
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterfunction.html
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER FUNCTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE" /><link rel="next" href="sql-altergroup.html" title="ALTER GROUP" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER FUNCTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altergroup.html" title="ALTER GROUP">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERFUNCTION"><div class="titlepage"></div><a id="id-1.9.3.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER FUNCTION</span></h2><p>ALTER FUNCTION — change the definition of a function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER FUNCTION <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ <em class="replaceable"><code>action</code></em> [ ... ] [ RESTRICT ]
+ALTER FUNCTION <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER FUNCTION <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER FUNCTION <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER FUNCTION <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
+ IMMUTABLE | STABLE | VOLATILE
+ [ NOT ] LEAKPROOF
+ [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
+ PARALLEL { UNSAFE | RESTRICTED | SAFE }
+ COST <em class="replaceable"><code>execution_cost</code></em>
+ ROWS <em class="replaceable"><code>result_rows</code></em>
+ SUPPORT <em class="replaceable"><code>support_function</code></em>
+ SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.14.5"><h2>Description</h2><p>
+ <code class="command">ALTER FUNCTION</code> changes the definition of a
+ function.
+ </p><p>
+ You must own the function to use <code class="command">ALTER FUNCTION</code>.
+ To change a function's schema, you must also have <code class="literal">CREATE</code>
+ privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the function's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the function.
+ However, a superuser can alter ownership of any function anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.14.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing function. If no
+ argument list is specified, the name must be unique in its schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Note that <code class="command">ALTER FUNCTION</code> does not actually pay
+ any attention to <code class="literal">OUT</code> arguments, since only the input
+ arguments are needed to determine the function's identity.
+ So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
+ and <code class="literal">VARIADIC</code> arguments.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">ALTER FUNCTION</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the function's arguments (optionally
+ schema-qualified), if any.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the function. Note that if the function is
+ marked <code class="literal">SECURITY DEFINER</code>, it will subsequently
+ execute as the new owner.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the function.
+ </p></dd><dt><span class="term"><code class="literal">DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em></code><br /></span><span class="term"><code class="literal">NO DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em></code></span></dt><dd><p>
+ This form marks the function as dependent on the extension, or no longer
+ dependent on that extension if <code class="literal">NO</code> is specified.
+ A function that's marked as dependent on an extension is dropped when the
+ extension is dropped, even if <code class="literal">CASCADE</code> is not specified.
+ A function can depend upon multiple extensions, and will be dropped when
+ any one of those extensions is dropped.
+ </p></dd><dt><span class="term"><code class="literal">CALLED ON NULL INPUT</code><br /></span><span class="term"><code class="literal">RETURNS NULL ON NULL INPUT</code><br /></span><span class="term"><code class="literal">STRICT</code></span></dt><dd><p><code class="literal">CALLED ON NULL INPUT</code> changes the function so
+ that it will be invoked when some or all of its arguments are
+ null. <code class="literal">RETURNS NULL ON NULL INPUT</code> or
+ <code class="literal">STRICT</code> changes the function so that it is not
+ invoked if any of its arguments are null; instead, a null result
+ is assumed automatically. See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>
+ for more information.
+ </p></dd><dt><span class="term"><code class="literal">IMMUTABLE</code><br /></span><span class="term"><code class="literal">STABLE</code><br /></span><span class="term"><code class="literal">VOLATILE</code></span></dt><dd><p>
+ Change the volatility of the function to the specified setting.
+ See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">[<span class="optional"> EXTERNAL </span>] SECURITY INVOKER</code><br /></span><span class="term"><code class="literal">[<span class="optional"> EXTERNAL </span>] SECURITY DEFINER</code></span></dt><dd><p>
+ Change whether the function is a security definer or not. The
+ key word <code class="literal">EXTERNAL</code> is ignored for SQL
+ conformance. See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for more information about
+ this capability.
+ </p></dd><dt><span class="term"><code class="literal">PARALLEL</code></span></dt><dd><p>
+ Change whether the function is deemed safe for parallelism.
+ See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">LEAKPROOF</code></span></dt><dd><p>
+ Change whether the function is considered leakproof or not.
+ See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for more information about
+ this capability.
+ </p></dd><dt><span class="term"><code class="literal">COST</code> <em class="replaceable"><code>execution_cost</code></em></span></dt><dd><p>
+ Change the estimated execution cost of the function.
+ See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">ROWS</code> <em class="replaceable"><code>result_rows</code></em></span></dt><dd><p>
+ Change the estimated number of rows returned by a set-returning
+ function. See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">SUPPORT</code> <em class="replaceable"><code>support_function</code></em></span></dt><dd><p>
+ Set or change the planner support function to use for this function.
+ See <a class="xref" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Section 38.11</a> for details. You must be
+ superuser to use this option.
+ </p><p>
+ This option cannot be used to remove the support function altogether,
+ since it must name a new support function. Use <code class="command">CREATE OR
+ REPLACE FUNCTION</code> if you need to do that.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ Add or change the assignment to be made to a configuration parameter
+ when the function is called. If
+ <em class="replaceable"><code>value</code></em> is <code class="literal">DEFAULT</code>
+ or, equivalently, <code class="literal">RESET</code> is used, the function-local
+ setting is removed, so that the function executes with the value
+ present in its environment. Use <code class="literal">RESET
+ ALL</code> to clear all function-local settings.
+ <code class="literal">SET FROM CURRENT</code> saves the value of the parameter that
+ is current when <code class="command">ALTER FUNCTION</code> is executed as the value
+ to be applied when the function is entered.
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and
+ <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information about allowed parameter names and values.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Ignored for conformance with the SQL standard.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.14.7"><h2>Examples</h2><p>
+ To rename the function <code class="literal">sqrt</code> for type
+ <code class="type">integer</code> to <code class="literal">square_root</code>:
+</p><pre class="programlisting">
+ALTER FUNCTION sqrt(integer) RENAME TO square_root;
+</pre><p>
+ </p><p>
+ To change the owner of the function <code class="literal">sqrt</code> for type
+ <code class="type">integer</code> to <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER FUNCTION sqrt(integer) OWNER TO joe;
+</pre><p>
+ </p><p>
+ To change the schema of the function <code class="literal">sqrt</code> for type
+ <code class="type">integer</code> to <code class="literal">maths</code>:
+</p><pre class="programlisting">
+ALTER FUNCTION sqrt(integer) SET SCHEMA maths;
+</pre><p>
+ </p><p>
+ To mark the function <code class="literal">sqrt</code> for type
+ <code class="type">integer</code> as being dependent on the extension
+ <code class="literal">mathlib</code>:
+</p><pre class="programlisting">
+ALTER FUNCTION sqrt(integer) DEPENDS ON EXTENSION mathlib;
+</pre><p>
+ </p><p>
+ To adjust the search path that is automatically set for a function:
+</p><pre class="programlisting">
+ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp;
+</pre><p>
+ </p><p>
+ To disable automatic setting of <code class="varname">search_path</code> for a function:
+</p><pre class="programlisting">
+ALTER FUNCTION check_password(text) RESET search_path;
+</pre><p>
+ The function will now execute with whatever search path is used by its
+ caller.
+ </p></div><div class="refsect1" id="id-1.9.3.14.8"><h2>Compatibility</h2><p>
+ This statement is partially compatible with the <code class="command">ALTER
+ FUNCTION</code> statement in the SQL standard. The standard allows more
+ properties of a function to be modified, but does not provide the
+ ability to rename a function, make a function a security definer,
+ attach configuration parameter values to a function,
+ or change the owner, schema, or volatility of a function. The standard also
+ requires the <code class="literal">RESTRICT</code> key word, which is optional in
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect1" id="id-1.9.3.14.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-dropfunction.html" title="DROP FUNCTION"><span class="refentrytitle">DROP FUNCTION</span></a>, <a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a>, <a class="xref" href="sql-alterroutine.html" title="ALTER ROUTINE"><span class="refentrytitle">ALTER ROUTINE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altergroup.html" title="ALTER GROUP">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER FOREIGN TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER GROUP</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altergroup.html b/doc/src/sgml/html/sql-altergroup.html
new file mode 100644
index 0000000..50c0ed7
--- /dev/null
+++ b/doc/src/sgml/html/sql-altergroup.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER GROUP</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterfunction.html" title="ALTER FUNCTION" /><link rel="next" href="sql-alterindex.html" title="ALTER INDEX" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER GROUP</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterfunction.html" title="ALTER FUNCTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterindex.html" title="ALTER INDEX">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERGROUP"><div class="titlepage"></div><a id="id-1.9.3.15.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER GROUP</span></h2><p>ALTER GROUP — change role name or membership</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER GROUP <em class="replaceable"><code>role_specification</code></em> ADD USER <em class="replaceable"><code>user_name</code></em> [, ... ]
+ALTER GROUP <em class="replaceable"><code>role_specification</code></em> DROP USER <em class="replaceable"><code>user_name</code></em> [, ... ]
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ <em class="replaceable"><code>role_name</code></em>
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+
+ALTER GROUP <em class="replaceable"><code>group_name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.15.5"><h2>Description</h2><p>
+ <code class="command">ALTER GROUP</code> changes the attributes of a user group.
+ This is an obsolete command, though still accepted for backwards
+ compatibility, because groups (and users too) have been superseded by the
+ more general concept of roles.
+ </p><p>
+ The first two variants add users to a group or remove them from a group.
+ (Any role can play the part of either a <span class="quote">“<span class="quote">user</span>”</span> or a
+ <span class="quote">“<span class="quote">group</span>”</span> for this purpose.) These variants are effectively
+ equivalent to granting or revoking membership in the role named as the
+ <span class="quote">“<span class="quote">group</span>”</span>; so the preferred way to do this is to use
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> or
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a>.
+ </p><p>
+ The third variant changes the name of the group. This is exactly
+ equivalent to renaming the role with
+ <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.15.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>group_name</code></em></span></dt><dd><p>
+ The name of the group (role) to modify.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ Users (roles) that are to be added to or removed from the group.
+ The users must already exist; <code class="command">ALTER GROUP</code> does not
+ create or drop users.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the group.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.15.7"><h2>Examples</h2><p>
+ Add users to a group:
+
+</p><pre class="programlisting">
+ALTER GROUP staff ADD USER karl, john;
+</pre><p>
+
+ Remove a user from a group:
+
+</p><pre class="programlisting">
+ALTER GROUP workers DROP USER beth;
+</pre></div><div class="refsect1" id="id-1.9.3.15.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER GROUP</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.15.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>, <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterfunction.html" title="ALTER FUNCTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterindex.html" title="ALTER INDEX">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER FUNCTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER INDEX</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterindex.html b/doc/src/sgml/html/sql-alterindex.html
new file mode 100644
index 0000000..fb1d3ef
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterindex.html
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER INDEX</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altergroup.html" title="ALTER GROUP" /><link rel="next" href="sql-alterlanguage.html" title="ALTER LANGUAGE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER INDEX</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altergroup.html" title="ALTER GROUP">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterlanguage.html" title="ALTER LANGUAGE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERINDEX"><div class="titlepage"></div><a id="id-1.9.3.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER INDEX</span></h2><p>ALTER INDEX — change the definition of an index</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER INDEX [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER INDEX [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET TABLESPACE <em class="replaceable"><code>tablespace_name</code></em>
+ALTER INDEX <em class="replaceable"><code>name</code></em> ATTACH PARTITION <em class="replaceable"><code>index_name</code></em>
+ALTER INDEX <em class="replaceable"><code>name</code></em> [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+ALTER INDEX [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )
+ALTER INDEX [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RESET ( <em class="replaceable"><code>storage_parameter</code></em> [, ... ] )
+ALTER INDEX [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ALTER [ COLUMN ] <em class="replaceable"><code>column_number</code></em>
+ SET STATISTICS <em class="replaceable"><code>integer</code></em>
+ALTER INDEX ALL IN TABLESPACE <em class="replaceable"><code>name</code></em> [ OWNED BY <em class="replaceable"><code>role_name</code></em> [, ... ] ]
+ SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em> [ NOWAIT ]
+</pre></div><div class="refsect1" id="id-1.9.3.16.5"><h2>Description</h2><p>
+ <code class="command">ALTER INDEX</code> changes the definition of an existing index.
+ There are several subforms described below. Note that the lock level required
+ may differ for each subform. An <code class="literal">ACCESS EXCLUSIVE</code> lock is held
+ unless explicitly noted. When multiple subcommands are listed, the lock
+ held will be the strictest one required from any subcommand.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
+ The <code class="literal">RENAME</code> form changes the name of the index.
+ If the index is associated with a table constraint (either
+ <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>,
+ or <code class="literal">EXCLUDE</code>), the constraint is renamed as well.
+ There is no effect on the stored data.
+ </p><p>
+ Renaming an index acquires a <code class="literal">SHARE UPDATE EXCLUSIVE</code>
+ lock.
+ </p></dd><dt><span class="term"><code class="literal">SET TABLESPACE</code></span></dt><dd><p>
+ This form changes the index's tablespace to the specified tablespace and
+ moves the data file(s) associated with the index to the new tablespace.
+ To change the tablespace of an index, you must own the index and have
+ <code class="literal">CREATE</code> privilege on the new tablespace.
+ All indexes in the current database in a tablespace can be moved by using
+ the <code class="literal">ALL IN TABLESPACE</code> form, which will lock all
+ indexes to be moved and then move each one. This form also supports
+ <code class="literal">OWNED BY</code>, which will only move indexes owned by the
+ roles specified. If the <code class="literal">NOWAIT</code> option is specified
+ then the command will fail if it is unable to acquire all of the locks
+ required immediately. Note that system catalogs will not be moved by
+ this command, use <code class="command">ALTER DATABASE</code> or explicit
+ <code class="command">ALTER INDEX</code> invocations instead if desired.
+ See also
+ <a class="link" href="sql-createtablespace.html" title="CREATE TABLESPACE"><code class="command">CREATE TABLESPACE</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">ATTACH PARTITION</code></span></dt><dd><p>
+ Causes the named index to become attached to the altered index.
+ The named index must be on a partition of the table containing the
+ index being altered, and have an equivalent definition. An attached
+ index cannot be dropped by itself, and will automatically be dropped
+ if its parent index is dropped.
+ </p></dd><dt><span class="term"><code class="literal">DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em></code><br /></span><span class="term"><code class="literal">NO DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em></code></span></dt><dd><p>
+ This form marks the index as dependent on the extension, or no longer
+ dependent on that extension if <code class="literal">NO</code> is specified.
+ An index that's marked as dependent on an extension is automatically
+ dropped when the extension is dropped.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This form changes one or more index-method-specific storage parameters
+ for the index. See
+ <a class="link" href="sql-createindex.html" title="CREATE INDEX"><code class="command">CREATE INDEX</code></a>
+ for details on the available parameters. Note that the index contents
+ will not be modified immediately by this command; depending on the
+ parameter you might need to rebuild the index with
+ <a class="link" href="sql-reindex.html" title="REINDEX"><code class="command">REINDEX</code></a>
+ to get the desired effects.
+ </p></dd><dt><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>storage_parameter</code></em> [, ... ] )</code></span></dt><dd><p>
+ This form resets one or more index-method-specific storage parameters to
+ their defaults. As with <code class="literal">SET</code>, a <code class="literal">REINDEX</code>
+ might be needed to update the index entirely.
+ </p></dd><dt><span class="term"><code class="literal">ALTER [ COLUMN ] <em class="replaceable"><code>column_number</code></em> SET STATISTICS <em class="replaceable"><code>integer</code></em></code></span></dt><dd><p>
+ This form sets the per-column statistics-gathering target for
+ subsequent <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> operations, though can
+ be used only on index columns that are defined as an expression.
+ Since expressions lack a unique name, we refer to them using the
+ ordinal number of the index column.
+ The target can be set in the range 0 to 10000; alternatively, set it
+ to -1 to revert to using the system default statistics
+ target (<a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a>).
+ For more information on the use of statistics by the
+ <span class="productname">PostgreSQL</span> query planner, refer to
+ <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.16.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the index does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_number</code></em></span></dt><dd><p>
+ The ordinal number refers to the ordinal (left-to-right) position
+ of the index column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of an existing index to
+ alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the index.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>tablespace_name</code></em></span></dt><dd><p>
+ The tablespace to which the index will be moved.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p>
+ The name of the extension that the index is to depend on.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>storage_parameter</code></em></span></dt><dd><p>
+ The name of an index-method-specific storage parameter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The new value for an index-method-specific storage parameter.
+ This might be a number or a word depending on the parameter.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.16.7"><h2>Notes</h2><p>
+ These operations are also possible using
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>.
+ <code class="command">ALTER INDEX</code> is in fact just an alias for the forms
+ of <code class="command">ALTER TABLE</code> that apply to indexes.
+ </p><p>
+ There was formerly an <code class="command">ALTER INDEX OWNER</code> variant, but
+ this is now ignored (with a warning). An index cannot have an owner
+ different from its table's owner. Changing the table's owner
+ automatically changes the index as well.
+ </p><p>
+ Changing any part of a system catalog index is not permitted.
+ </p></div><div class="refsect1" id="id-1.9.3.16.8"><h2>Examples</h2><p>
+ To rename an existing index:
+</p><pre class="programlisting">
+ALTER INDEX distributors RENAME TO suppliers;
+</pre><p>
+ </p><p>
+ To move an index to a different tablespace:
+</p><pre class="programlisting">
+ALTER INDEX distributors SET TABLESPACE fasttablespace;
+</pre><p>
+ </p><p>
+ To change an index's fill factor (assuming that the index method
+ supports it):
+</p><pre class="programlisting">
+ALTER INDEX distributors SET (fillfactor = 75);
+REINDEX INDEX distributors;
+</pre><p>
+ Set the statistics-gathering target for an expression index:
+</p><pre class="programlisting">
+CREATE INDEX coord_idx ON measured (x, y, (z + t));
+ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000;
+</pre></div><div class="refsect1" id="id-1.9.3.16.9"><h2>Compatibility</h2><p>
+ <code class="command">ALTER INDEX</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.16.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>, <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altergroup.html" title="ALTER GROUP">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterlanguage.html" title="ALTER LANGUAGE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER GROUP </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER LANGUAGE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterlanguage.html b/doc/src/sgml/html/sql-alterlanguage.html
new file mode 100644
index 0000000..bbd6ead
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterlanguage.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER LANGUAGE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterindex.html" title="ALTER INDEX" /><link rel="next" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER LANGUAGE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterindex.html" title="ALTER INDEX">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERLANGUAGE"><div class="titlepage"></div><a id="id-1.9.3.17.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER LANGUAGE</span></h2><p>ALTER LANGUAGE — change the definition of a procedural language</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+</pre></div><div class="refsect1" id="id-1.9.3.17.5"><h2>Description</h2><p>
+ <code class="command">ALTER LANGUAGE</code> changes the definition of a
+ procedural language. The only functionality is to rename the language or
+ assign a new owner. You must be superuser or owner of the language to
+ use <code class="command">ALTER LANGUAGE</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.17.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ Name of a language
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the language
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the language
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.17.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER LANGUAGE</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.17.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>, <a class="xref" href="sql-droplanguage.html" title="DROP LANGUAGE"><span class="refentrytitle">DROP LANGUAGE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterindex.html" title="ALTER INDEX">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER INDEX </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER LARGE OBJECT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterlargeobject.html b/doc/src/sgml/html/sql-alterlargeobject.html
new file mode 100644
index 0000000..75d442a
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterlargeobject.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER LARGE OBJECT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterlanguage.html" title="ALTER LANGUAGE" /><link rel="next" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER LARGE OBJECT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterlanguage.html" title="ALTER LANGUAGE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERLARGEOBJECT"><div class="titlepage"></div><a id="id-1.9.3.18.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER LARGE OBJECT</span></h2><p>ALTER LARGE OBJECT — change the definition of a large object</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER LARGE OBJECT <em class="replaceable"><code>large_object_oid</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+</pre></div><div class="refsect1" id="id-1.9.3.18.5"><h2>Description</h2><p>
+ <code class="command">ALTER LARGE OBJECT</code> changes the definition of a
+ large object.
+ </p><p>
+ You must own the large object to use <code class="command">ALTER LARGE OBJECT</code>.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role. (However, a superuser can alter any large object anyway.)
+ Currently, the only functionality is to assign a new owner, so both
+ restrictions always apply.
+ </p></div><div class="refsect1" id="id-1.9.3.18.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>large_object_oid</code></em></span></dt><dd><p>
+ OID of the large object to be altered
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the large object
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.18.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER LARGE OBJECT</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.18.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="largeobjects.html" title="Chapter 35. Large Objects">Chapter 35</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterlanguage.html" title="ALTER LANGUAGE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER LANGUAGE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER MATERIALIZED VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altermaterializedview.html b/doc/src/sgml/html/sql-altermaterializedview.html
new file mode 100644
index 0000000..97abf62
--- /dev/null
+++ b/doc/src/sgml/html/sql-altermaterializedview.html
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER MATERIALIZED VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT" /><link rel="next" href="sql-alteroperator.html" title="ALTER OPERATOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER MATERIALIZED VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteroperator.html" title="ALTER OPERATOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERMATERIALIZEDVIEW"><div class="titlepage"></div><a id="id-1.9.3.19.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER MATERIALIZED VIEW</span></h2><p>ALTER MATERIALIZED VIEW — change the definition of a materialized view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER MATERIALIZED VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>action</code></em> [, ... ]
+ALTER MATERIALIZED VIEW <em class="replaceable"><code>name</code></em>
+ [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+ALTER MATERIALIZED VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ RENAME [ COLUMN ] <em class="replaceable"><code>column_name</code></em> TO <em class="replaceable"><code>new_column_name</code></em>
+ALTER MATERIALIZED VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER MATERIALIZED VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER MATERIALIZED VIEW ALL IN TABLESPACE <em class="replaceable"><code>name</code></em> [ OWNED BY <em class="replaceable"><code>role_name</code></em> [, ... ] ]
+ SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em> [ NOWAIT ]
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STATISTICS <em class="replaceable"><code>integer</code></em>
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET COMPRESSION <em class="replaceable"><code>compression_method</code></em>
+ CLUSTER ON <em class="replaceable"><code>index_name</code></em>
+ SET WITHOUT CLUSTER
+ SET ACCESS METHOD <em class="replaceable"><code>new_access_method</code></em>
+ SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em>
+ SET ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )
+ RESET ( <em class="replaceable"><code>storage_parameter</code></em> [, ... ] )
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+</pre></div><div class="refsect1" id="id-1.9.3.19.5"><h2>Description</h2><p>
+ <code class="command">ALTER MATERIALIZED VIEW</code> changes various auxiliary
+ properties of an existing materialized view.
+ </p><p>
+ You must own the materialized view to use <code class="command">ALTER MATERIALIZED
+ VIEW</code>. To change a materialized view's schema, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the materialized view's schema. (These restrictions enforce that altering
+ the owner doesn't do anything you couldn't do by dropping and recreating the
+ materialized view. However, a superuser can alter ownership of any view
+ anyway.)
+ </p><p>
+ The statement subforms and actions available for
+ <code class="command">ALTER MATERIALIZED VIEW</code> are a subset of those available
+ for <code class="command">ALTER TABLE</code>, and have the same meaning when used for
+ materialized views. See the descriptions for
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
+ for details.
+ </p></div><div class="refsect1" id="id-1.9.3.19.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing materialized view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ Name of a new or existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p>
+ The name of the extension that the materialized view is to depend on (or no longer
+ dependent on, if <code class="literal">NO</code> is specified). A materialized view
+ that's marked as dependent on an extension is automatically dropped when
+ the extension is dropped.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_column_name</code></em></span></dt><dd><p>
+ New name for an existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the materialized view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the materialized view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the materialized view.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.19.7"><h2>Examples</h2><p>
+ To rename the materialized view <code class="literal">foo</code> to
+ <code class="literal">bar</code>:
+</p><pre class="programlisting">
+ALTER MATERIALIZED VIEW foo RENAME TO bar;
+</pre></div><div class="refsect1" id="id-1.9.3.19.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER MATERIALIZED VIEW</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.19.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW"><span class="refentrytitle">DROP MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW"><span class="refentrytitle">REFRESH MATERIALIZED VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterlargeobject.html" title="ALTER LARGE OBJECT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteroperator.html" title="ALTER OPERATOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER LARGE OBJECT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER OPERATOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alteropclass.html b/doc/src/sgml/html/sql-alteropclass.html
new file mode 100644
index 0000000..f063ab7
--- /dev/null
+++ b/doc/src/sgml/html/sql-alteropclass.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER OPERATOR CLASS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alteroperator.html" title="ALTER OPERATOR" /><link rel="next" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER OPERATOR CLASS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alteroperator.html" title="ALTER OPERATOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTEROPCLASS"><div class="titlepage"></div><a id="id-1.9.3.21.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER OPERATOR CLASS</span></h2><p>ALTER OPERATOR CLASS — change the definition of an operator class</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER OPERATOR CLASS <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER OPERATOR CLASS <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+
+ALTER OPERATOR CLASS <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.21.5"><h2>Description</h2><p>
+ <code class="command">ALTER OPERATOR CLASS</code> changes the definition of
+ an operator class.
+ </p><p>
+ You must own the operator class to use <code class="command">ALTER OPERATOR CLASS</code>.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the operator class's schema. (These restrictions enforce that altering the
+ owner doesn't do anything you couldn't do by dropping and recreating the
+ operator class. However, a superuser can alter ownership of any operator
+ class anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.21.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator
+ class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index method this operator class is for.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the operator class.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.21.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER OPERATOR CLASS</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.21.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopclass.html" title="DROP OPERATOR CLASS"><span class="refentrytitle">DROP OPERATOR CLASS</span></a>, <a class="xref" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY"><span class="refentrytitle">ALTER OPERATOR FAMILY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alteroperator.html" title="ALTER OPERATOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER OPERATOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER OPERATOR FAMILY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alteroperator.html b/doc/src/sgml/html/sql-alteroperator.html
new file mode 100644
index 0000000..efb5eaa
--- /dev/null
+++ b/doc/src/sgml/html/sql-alteroperator.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER OPERATOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW" /><link rel="next" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER OPERATOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTEROPERATOR"><div class="titlepage"></div><a id="id-1.9.3.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER OPERATOR</span></h2><p>ALTER OPERATOR — change the definition of an operator</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER OPERATOR <em class="replaceable"><code>name</code></em> ( { <em class="replaceable"><code>left_type</code></em> | NONE } , <em class="replaceable"><code>right_type</code></em> )
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+
+ALTER OPERATOR <em class="replaceable"><code>name</code></em> ( { <em class="replaceable"><code>left_type</code></em> | NONE } , <em class="replaceable"><code>right_type</code></em> )
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+
+ALTER OPERATOR <em class="replaceable"><code>name</code></em> ( { <em class="replaceable"><code>left_type</code></em> | NONE } , <em class="replaceable"><code>right_type</code></em> )
+ SET ( { RESTRICT = { <em class="replaceable"><code>res_proc</code></em> | NONE }
+ | JOIN = { <em class="replaceable"><code>join_proc</code></em> | NONE }
+ } [, ... ] )
+</pre></div><div class="refsect1" id="id-1.9.3.20.5"><h2>Description</h2><p>
+ <code class="command">ALTER OPERATOR</code> changes the definition of
+ an operator.
+ </p><p>
+ You must own the operator to use <code class="command">ALTER OPERATOR</code>.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the operator's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the operator.
+ However, a superuser can alter ownership of any operator anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.20.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em></span></dt><dd><p>
+ The data type of the operator's left operand; write
+ <code class="literal">NONE</code> if the operator has no left operand.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
+ The data type of the operator's right operand.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>res_proc</code></em></span></dt><dd><p>
+ The restriction selectivity estimator function for this operator; write NONE to remove existing selectivity estimator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>join_proc</code></em></span></dt><dd><p>
+ The join selectivity estimator function for this operator; write NONE to remove existing selectivity estimator.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.20.7"><h2>Examples</h2><p>
+ Change the owner of a custom operator <code class="literal">a @@ b</code> for type <code class="type">text</code>:
+</p><pre class="programlisting">
+ALTER OPERATOR @@ (text, text) OWNER TO joe;
+</pre><p>
+ Change the restriction and join selectivity estimator functions of a custom operator <code class="literal">a &amp;&amp; b</code> for type <code class="type">int[]</code>:
+</p><pre class="programlisting">
+ALTER OPERATOR &amp;&amp; (_int4, _int4) SET (RESTRICT = _int_contsel, JOIN = _int_contjoinsel);
+</pre></div><div class="refsect1" id="id-1.9.3.20.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER OPERATOR</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.20.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createoperator.html" title="CREATE OPERATOR"><span class="refentrytitle">CREATE OPERATOR</span></a>, <a class="xref" href="sql-dropoperator.html" title="DROP OPERATOR"><span class="refentrytitle">DROP OPERATOR</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER MATERIALIZED VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER OPERATOR CLASS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alteropfamily.html b/doc/src/sgml/html/sql-alteropfamily.html
new file mode 100644
index 0000000..fc0e6b2
--- /dev/null
+++ b/doc/src/sgml/html/sql-alteropfamily.html
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER OPERATOR FAMILY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS" /><link rel="next" href="sql-alterpolicy.html" title="ALTER POLICY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER OPERATOR FAMILY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterpolicy.html" title="ALTER POLICY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTEROPFAMILY"><div class="titlepage"></div><a id="id-1.9.3.22.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER OPERATOR FAMILY</span></h2><p>ALTER OPERATOR FAMILY — change the definition of an operator family</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em> ADD
+ { OPERATOR <em class="replaceable"><code>strategy_number</code></em> <em class="replaceable"><code>operator_name</code></em> ( <em class="replaceable"><code>op_type</code></em>, <em class="replaceable"><code>op_type</code></em> )
+ [ FOR SEARCH | FOR ORDER BY <em class="replaceable"><code>sort_family_name</code></em> ]
+ | FUNCTION <em class="replaceable"><code>support_number</code></em> [ ( <em class="replaceable"><code>op_type</code></em> [ , <em class="replaceable"><code>op_type</code></em> ] ) ]
+ <em class="replaceable"><code>function_name</code></em> [ ( <em class="replaceable"><code>argument_type</code></em> [, ...] ) ]
+ } [, ... ]
+
+ALTER OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em> DROP
+ { OPERATOR <em class="replaceable"><code>strategy_number</code></em> ( <em class="replaceable"><code>op_type</code></em> [ , <em class="replaceable"><code>op_type</code></em> ] )
+ | FUNCTION <em class="replaceable"><code>support_number</code></em> ( <em class="replaceable"><code>op_type</code></em> [ , <em class="replaceable"><code>op_type</code></em> ] )
+ } [, ... ]
+
+ALTER OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+
+ALTER OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.22.5"><h2>Description</h2><p>
+ <code class="command">ALTER OPERATOR FAMILY</code> changes the definition of
+ an operator family. You can add operators and support functions
+ to the family, remove them from the family,
+ or change the family's name or owner.
+ </p><p>
+ When operators and support functions are added to a family with
+ <code class="command">ALTER OPERATOR FAMILY</code>, they are not part of any
+ specific operator class within the family, but are just <span class="quote">“<span class="quote">loose</span>”</span>
+ within the family. This indicates that these operators and functions
+ are compatible with the family's semantics, but are not required for
+ correct functioning of any specific index. (Operators and functions
+ that are so required should be declared as part of an operator class,
+ instead; see <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>.)
+ <span class="productname">PostgreSQL</span> will allow loose members of a
+ family to be dropped from the family at any time, but members of an
+ operator class cannot be dropped without dropping the whole class and
+ any indexes that depend on it.
+ Typically, single-data-type operators
+ and functions are part of operator classes because they are needed to
+ support an index on that specific data type, while cross-data-type
+ operators and functions are made loose members of the family.
+ </p><p>
+ You must be a superuser to use <code class="command">ALTER OPERATOR FAMILY</code>.
+ (This restriction is made because an erroneous operator family definition
+ could confuse or even crash the server.)
+ </p><p>
+ <code class="command">ALTER OPERATOR FAMILY</code> does not presently check
+ whether the operator family definition includes all the operators and
+ functions required by the index method, nor whether the operators and
+ functions form a self-consistent set. It is the user's
+ responsibility to define a valid operator family.
+ </p><p>
+ Refer to <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.22.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator
+ family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index method this operator family is for.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>strategy_number</code></em></span></dt><dd><p>
+ The index method's strategy number for an operator
+ associated with the operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>operator_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an operator associated
+ with the operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>op_type</code></em></span></dt><dd><p>
+ In an <code class="literal">OPERATOR</code> clause,
+ the operand data type(s) of the operator, or <code class="literal">NONE</code> to
+ signify a prefix operator. Unlike the comparable
+ syntax in <code class="command">CREATE OPERATOR CLASS</code>, the operand data types
+ must always be specified.
+ </p><p>
+ In an <code class="literal">ADD FUNCTION</code> clause, the operand data type(s) the
+ function is intended to support, if different from
+ the input data type(s) of the function. For B-tree comparison functions
+ and hash functions it is not necessary to specify <em class="replaceable"><code>op_type</code></em> since the function's input
+ data type(s) are always the correct ones to use. For B-tree sort
+ support functions, B-Tree equal image functions, and all
+ functions in GiST, SP-GiST and GIN operator classes, it is
+ necessary to specify the operand data type(s) the function is to
+ be used with.
+ </p><p>
+ In a <code class="literal">DROP FUNCTION</code> clause, the operand data type(s) the
+ function is intended to support must be specified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sort_family_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing <code class="literal">btree</code> operator
+ family that describes the sort ordering associated with an ordering
+ operator.
+ </p><p>
+ If neither <code class="literal">FOR SEARCH</code> nor <code class="literal">FOR ORDER BY</code> is
+ specified, <code class="literal">FOR SEARCH</code> is the default.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>support_number</code></em></span></dt><dd><p>
+ The index method's support function number for a
+ function associated with the operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a function that is an index
+ method support function for the operator family. If no argument list
+ is specified, the name must be unique in its schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argument_type</code></em></span></dt><dd><p>
+ The parameter data type(s) of the function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the operator family.
+ </p></dd></dl></div><p>
+ The <code class="literal">OPERATOR</code> and <code class="literal">FUNCTION</code>
+ clauses can appear in any order.
+ </p></div><div class="refsect1" id="id-1.9.3.22.7"><h2>Notes</h2><p>
+ Notice that the <code class="literal">DROP</code> syntax only specifies the <span class="quote">“<span class="quote">slot</span>”</span>
+ in the operator family, by strategy or support number and input data
+ type(s). The name of the operator or function occupying the slot is not
+ mentioned. Also, for <code class="literal">DROP FUNCTION</code> the type(s) to specify
+ are the input data type(s) the function is intended to support; for
+ GiST, SP-GiST and GIN indexes this might have nothing to do with the actual
+ input argument types of the function.
+ </p><p>
+ Because the index machinery does not check access permissions on functions
+ before using them, including a function or operator in an operator family
+ is tantamount to granting public execute permission on it. This is usually
+ not an issue for the sorts of functions that are useful in an operator
+ family.
+ </p><p>
+ The operators should not be defined by SQL functions. An SQL function
+ is likely to be inlined into the calling query, which will prevent
+ the optimizer from recognizing that the query matches an index.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> 8.4, the <code class="literal">OPERATOR</code>
+ clause could include a <code class="literal">RECHECK</code> option. This is no longer
+ supported because whether an index operator is <span class="quote">“<span class="quote">lossy</span>”</span> is now
+ determined on-the-fly at run time. This allows efficient handling of
+ cases where an operator might or might not be lossy.
+ </p></div><div class="refsect1" id="id-1.9.3.22.8"><h2>Examples</h2><p>
+ The following example command adds cross-data-type operators and
+ support functions to an operator family that already contains B-tree
+ operator classes for data types <code class="type">int4</code> and <code class="type">int2</code>.
+ </p><pre class="programlisting">
+ALTER OPERATOR FAMILY integer_ops USING btree ADD
+
+ -- int4 vs int2
+ OPERATOR 1 &lt; (int4, int2) ,
+ OPERATOR 2 &lt;= (int4, int2) ,
+ OPERATOR 3 = (int4, int2) ,
+ OPERATOR 4 &gt;= (int4, int2) ,
+ OPERATOR 5 &gt; (int4, int2) ,
+ FUNCTION 1 btint42cmp(int4, int2) ,
+
+ -- int2 vs int4
+ OPERATOR 1 &lt; (int2, int4) ,
+ OPERATOR 2 &lt;= (int2, int4) ,
+ OPERATOR 3 = (int2, int4) ,
+ OPERATOR 4 &gt;= (int2, int4) ,
+ OPERATOR 5 &gt; (int2, int4) ,
+ FUNCTION 1 btint24cmp(int2, int4) ;
+</pre><p>
+ To remove these entries again:
+ </p><pre class="programlisting">
+ALTER OPERATOR FAMILY integer_ops USING btree DROP
+
+ -- int4 vs int2
+ OPERATOR 1 (int4, int2) ,
+ OPERATOR 2 (int4, int2) ,
+ OPERATOR 3 (int4, int2) ,
+ OPERATOR 4 (int4, int2) ,
+ OPERATOR 5 (int4, int2) ,
+ FUNCTION 1 (int4, int2) ,
+
+ -- int2 vs int4
+ OPERATOR 1 (int2, int4) ,
+ OPERATOR 2 (int2, int4) ,
+ OPERATOR 3 (int2, int4) ,
+ OPERATOR 4 (int2, int4) ,
+ OPERATOR 5 (int2, int4) ,
+ FUNCTION 1 (int2, int4) ;
+</pre></div><div class="refsect1" id="id-1.9.3.22.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER OPERATOR FAMILY</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.22.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY"><span class="refentrytitle">CREATE OPERATOR FAMILY</span></a>, <a class="xref" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY"><span class="refentrytitle">DROP OPERATOR FAMILY</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS"><span class="refentrytitle">ALTER OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopclass.html" title="DROP OPERATOR CLASS"><span class="refentrytitle">DROP OPERATOR CLASS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterpolicy.html" title="ALTER POLICY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER OPERATOR CLASS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER POLICY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterpolicy.html b/doc/src/sgml/html/sql-alterpolicy.html
new file mode 100644
index 0000000..03557d5
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterpolicy.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER POLICY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY" /><link rel="next" href="sql-alterprocedure.html" title="ALTER PROCEDURE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER POLICY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterprocedure.html" title="ALTER PROCEDURE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERPOLICY"><div class="titlepage"></div><a id="id-1.9.3.23.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER POLICY</span></h2><p>ALTER POLICY — change the definition of a row-level security policy</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER POLICY <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER POLICY <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em>
+ [ TO { <em class="replaceable"><code>role_name</code></em> | PUBLIC | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, ...] ]
+ [ USING ( <em class="replaceable"><code>using_expression</code></em> ) ]
+ [ WITH CHECK ( <em class="replaceable"><code>check_expression</code></em> ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.23.5"><h2>Description</h2><p>
+ <code class="command">ALTER POLICY</code> changes the definition of an existing
+ row-level security policy. Note that <code class="command">ALTER POLICY</code>
+ only allows the set of roles to which the policy applies and the
+ <code class="literal">USING</code> and <code class="literal">WITH CHECK</code> expressions to
+ be modified. To change other properties of a policy, such as the command
+ to which it applies or whether it is permissive or restrictive, the policy
+ must be dropped and recreated.
+ </p><p>
+ To use <code class="command">ALTER POLICY</code>, you must own the table that
+ the policy applies to.
+ </p><p>
+ In the second form of <code class="command">ALTER POLICY</code>, the role list,
+ <em class="replaceable"><code>using_expression</code></em>, and
+ <em class="replaceable"><code>check_expression</code></em> are replaced
+ independently if specified. When one of those clauses is omitted, the
+ corresponding part of the policy is unchanged.
+ </p></div><div class="refsect1" id="id-1.9.3.23.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing policy to alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table that the
+ policy is on.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the policy.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The role(s) to which the policy applies. Multiple roles can be
+ specified at one time. To apply the policy to all roles,
+ use <code class="literal">PUBLIC</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>using_expression</code></em></span></dt><dd><p>
+ The <code class="literal">USING</code> expression for the policy.
+ See <a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a> for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>check_expression</code></em></span></dt><dd><p>
+ The <code class="literal">WITH CHECK</code> expression for the policy.
+ See <a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a> for details.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.23.7"><h2>Compatibility</h2><p>
+ <code class="command">ALTER POLICY</code> is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.23.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a>, <a class="xref" href="sql-droppolicy.html" title="DROP POLICY"><span class="refentrytitle">DROP POLICY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterprocedure.html" title="ALTER PROCEDURE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER OPERATOR FAMILY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER PROCEDURE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterprocedure.html b/doc/src/sgml/html/sql-alterprocedure.html
new file mode 100644
index 0000000..80cffd1
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterprocedure.html
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER PROCEDURE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterpolicy.html" title="ALTER POLICY" /><link rel="next" href="sql-alterpublication.html" title="ALTER PUBLICATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER PROCEDURE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterpolicy.html" title="ALTER POLICY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterpublication.html" title="ALTER PUBLICATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERPROCEDURE"><div class="titlepage"></div><a id="id-1.9.3.24.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER PROCEDURE</span></h2><p>ALTER PROCEDURE — change the definition of a procedure</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER PROCEDURE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ <em class="replaceable"><code>action</code></em> [ ... ] [ RESTRICT ]
+ALTER PROCEDURE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER PROCEDURE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER PROCEDURE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER PROCEDURE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
+ SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.24.5"><h2>Description</h2><p>
+ <code class="command">ALTER PROCEDURE</code> changes the definition of a
+ procedure.
+ </p><p>
+ You must own the procedure to use <code class="command">ALTER PROCEDURE</code>.
+ To change a procedure's schema, you must also have <code class="literal">CREATE</code>
+ privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the procedure's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the procedure.
+ However, a superuser can alter ownership of any procedure anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.24.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing procedure. If no
+ argument list is specified, the name must be unique in its schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>. If omitted,
+ the default is <code class="literal">IN</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">ALTER PROCEDURE</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are used to determine the procedure's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the procedure's arguments (optionally
+ schema-qualified), if any.
+ See <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a> for the details of how
+ the procedure is looked up using the argument data type(s).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the procedure.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the procedure. Note that if the procedure is
+ marked <code class="literal">SECURITY DEFINER</code>, it will subsequently
+ execute as the new owner.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the procedure.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p>
+ This form marks the procedure as dependent on the extension, or no longer
+ dependent on the extension if <code class="literal">NO</code> is specified.
+ A procedure that's marked as dependent on an extension is dropped when the
+ extension is dropped, even if cascade is not specified.
+ A procedure can depend upon multiple extensions, and will be dropped when
+ any one of those extensions is dropped.
+ </p></dd><dt><span class="term"><code class="literal">[<span class="optional"> EXTERNAL </span>] SECURITY INVOKER</code><br /></span><span class="term"><code class="literal">[<span class="optional"> EXTERNAL </span>] SECURITY DEFINER</code></span></dt><dd><p>
+ Change whether the procedure is a security definer or not. The
+ key word <code class="literal">EXTERNAL</code> is ignored for SQL
+ conformance. See <a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a> for more information about
+ this capability.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ Add or change the assignment to be made to a configuration parameter
+ when the procedure is called. If
+ <em class="replaceable"><code>value</code></em> is <code class="literal">DEFAULT</code>
+ or, equivalently, <code class="literal">RESET</code> is used, the procedure-local
+ setting is removed, so that the procedure executes with the value
+ present in its environment. Use <code class="literal">RESET
+ ALL</code> to clear all procedure-local settings.
+ <code class="literal">SET FROM CURRENT</code> saves the value of the parameter that
+ is current when <code class="command">ALTER PROCEDURE</code> is executed as the value
+ to be applied when the procedure is entered.
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and
+ <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information about allowed parameter names and values.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Ignored for conformance with the SQL standard.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.24.7"><h2>Examples</h2><p>
+ To rename the procedure <code class="literal">insert_data</code> with two arguments
+ of type <code class="type">integer</code> to <code class="literal">insert_record</code>:
+</p><pre class="programlisting">
+ALTER PROCEDURE insert_data(integer, integer) RENAME TO insert_record;
+</pre><p>
+ </p><p>
+ To change the owner of the procedure <code class="literal">insert_data</code> with
+ two arguments of type <code class="type">integer</code> to <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER PROCEDURE insert_data(integer, integer) OWNER TO joe;
+</pre><p>
+ </p><p>
+ To change the schema of the procedure <code class="literal">insert_data</code> with
+ two arguments of type <code class="type">integer</code>
+ to <code class="literal">accounting</code>:
+</p><pre class="programlisting">
+ALTER PROCEDURE insert_data(integer, integer) SET SCHEMA accounting;
+</pre><p>
+ </p><p>
+ To mark the procedure <code class="literal">insert_data(integer, integer)</code> as
+ being dependent on the extension <code class="literal">myext</code>:
+</p><pre class="programlisting">
+ALTER PROCEDURE insert_data(integer, integer) DEPENDS ON EXTENSION myext;
+</pre><p>
+ </p><p>
+ To adjust the search path that is automatically set for a procedure:
+</p><pre class="programlisting">
+ALTER PROCEDURE check_password(text) SET search_path = admin, pg_temp;
+</pre><p>
+ </p><p>
+ To disable automatic setting of <code class="varname">search_path</code> for a procedure:
+</p><pre class="programlisting">
+ALTER PROCEDURE check_password(text) RESET search_path;
+</pre><p>
+ The procedure will now execute with whatever search path is used by its
+ caller.
+ </p></div><div class="refsect1" id="id-1.9.3.24.8"><h2>Compatibility</h2><p>
+ This statement is partially compatible with the <code class="command">ALTER
+ PROCEDURE</code> statement in the SQL standard. The standard allows more
+ properties of a procedure to be modified, but does not provide the
+ ability to rename a procedure, make a procedure a security definer,
+ attach configuration parameter values to a procedure,
+ or change the owner, schema, or volatility of a procedure. The standard also
+ requires the <code class="literal">RESTRICT</code> key word, which is optional in
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect1" id="id-1.9.3.24.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a>, <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a>, <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, <a class="xref" href="sql-alterroutine.html" title="ALTER ROUTINE"><span class="refentrytitle">ALTER ROUTINE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterpolicy.html" title="ALTER POLICY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterpublication.html" title="ALTER PUBLICATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER POLICY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER PUBLICATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterpublication.html b/doc/src/sgml/html/sql-alterpublication.html
new file mode 100644
index 0000000..2b83701
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterpublication.html
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER PUBLICATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterprocedure.html" title="ALTER PROCEDURE" /><link rel="next" href="sql-alterrole.html" title="ALTER ROLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER PUBLICATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterprocedure.html" title="ALTER PROCEDURE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterrole.html" title="ALTER ROLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERPUBLICATION"><div class="titlepage"></div><a id="id-1.9.3.25.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER PUBLICATION</span></h2><p>ALTER PUBLICATION — change the definition of a publication</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> ADD <em class="replaceable"><code>publication_object</code></em> [, ...]
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> SET <em class="replaceable"><code>publication_object</code></em> [, ...]
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> DROP <em class="replaceable"><code>publication_object</code></em> [, ...]
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER PUBLICATION <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>publication_object</code></em> is one of:</span>
+
+ TABLE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] [ WHERE ( <em class="replaceable"><code>expression</code></em> ) ] [, ... ]
+ TABLES IN SCHEMA { <em class="replaceable"><code>schema_name</code></em> | CURRENT_SCHEMA } [, ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.25.5"><h2>Description</h2><p>
+ The command <code class="command">ALTER PUBLICATION</code> can change the attributes
+ of a publication.
+ </p><p>
+ The first three variants change which tables/schemas are part of the
+ publication. The <code class="literal">SET</code> clause will replace the list of
+ tables/schemas in the publication with the specified list; the existing
+ tables/schemas that were present in the publication will be removed. The
+ <code class="literal">ADD</code> and <code class="literal">DROP</code> clauses will add and
+ remove one or more tables/schemas from the publication. Note that adding
+ tables/schemas to a publication that is already subscribed to will require an
+ <code class="literal">ALTER SUBSCRIPTION ... REFRESH PUBLICATION</code> action on the
+ subscribing side in order to become effective. Note also that
+ <code class="literal">DROP TABLES IN SCHEMA</code> will not drop any schema tables
+ that were specified using <code class="literal">FOR TABLE</code>/
+ <code class="literal">ADD TABLE</code>, and the combination of <code class="literal">DROP</code>
+ with a <code class="literal">WHERE</code> clause is not allowed.
+ </p><p>
+ The fourth variant of this command listed in the synopsis can change
+ all of the publication properties specified in
+ <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>. Properties not mentioned in the
+ command retain their previous settings.
+ </p><p>
+ The remaining variants change the owner and the name of the publication.
+ </p><p>
+ You must own the publication to use <code class="command">ALTER PUBLICATION</code>.
+ Adding a table to a publication additionally requires owning that table.
+ The <code class="literal">ADD TABLES IN SCHEMA</code> and
+ <code class="literal">SET TABLES IN SCHEMA</code> to a publication requires the
+ invoking user to be a superuser. To alter the owner, you must also be a
+ direct or indirect member of the new owning role. The new owner must have
+ <code class="literal">CREATE</code> privilege on the database. Also, the new owner
+ of a <code class="literal">FOR ALL TABLES</code> or <code class="literal">FOR TABLES IN SCHEMA</code>
+ publication must be a superuser. However, a superuser can
+ change the ownership of a publication regardless of these restrictions.
+ </p><p>
+ Adding/Setting any schema when the publication also publishes a table with a
+ column list, and vice versa is not supported.
+ </p></div><div class="refsect1" id="id-1.9.3.25.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing publication whose definition is to be altered.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ Name of an existing table. If <code class="literal">ONLY</code> is specified before the
+ table name, only that table is affected. If <code class="literal">ONLY</code> is not
+ specified, the table and all its descendant tables (if any) are
+ affected. Optionally, <code class="literal">*</code> can be specified after the table
+ name to explicitly indicate that descendant tables are included.
+ </p><p>
+ Optionally, a column list can be specified. See <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a> for details. Note that a subscription
+ having several publications in which the same table has been published
+ with different column lists is not supported. See
+ <a class="xref" href="logical-replication-col-lists.html#LOGICAL-REPLICATION-COL-LIST-COMBINING" title="Warning: Combining Column Lists from Multiple Publications">Warning: Combining Column Lists from Multiple Publications</a> for details of
+ potential problems when altering column lists.
+ </p><p>
+ If the optional <code class="literal">WHERE</code> clause is specified, rows for
+ which the <em class="replaceable"><code>expression</code></em>
+ evaluates to false or null will not be published. Note that parentheses
+ are required around the expression. The
+ <em class="replaceable"><code>expression</code></em> is evaluated with
+ the role used for the replication connection.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>schema_name</code></em></span></dt><dd><p>
+ Name of an existing schema.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause alters publication parameters originally set by
+ <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>. See there for more information.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the publication.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the publication.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.25.7"><h2>Examples</h2><p>
+ Change the publication to publish only deletes and updates:
+</p><pre class="programlisting">
+ALTER PUBLICATION noinsert SET (publish = 'update, delete');
+</pre><p>
+ </p><p>
+ Add some tables to the publication:
+</p><pre class="programlisting">
+ALTER PUBLICATION mypublication ADD TABLE users (user_id, firstname), departments;
+</pre><p>
+ Change the set of columns published for a table:
+</p><pre class="programlisting">
+ALTER PUBLICATION mypublication SET TABLE users (user_id, firstname, lastname), TABLE departments;
+</pre><p>
+ Add schemas <code class="structname">marketing</code> and
+ <code class="structname">sales</code> to the publication
+ <code class="structname">sales_publication</code>:
+</p><pre class="programlisting">
+ALTER PUBLICATION sales_publication ADD TABLES IN SCHEMA marketing, sales;
+</pre><p>
+ </p><p>
+ Add tables <code class="structname">users</code>,
+ <code class="structname">departments</code> and schema
+ <code class="structname">production</code> to the publication
+ <code class="structname">production_publication</code>:
+</p><pre class="programlisting">
+ALTER PUBLICATION production_publication ADD TABLE users, departments, TABLES IN SCHEMA production;
+</pre></div><div class="refsect1" id="id-1.9.3.25.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER PUBLICATION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.25.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>, <a class="xref" href="sql-droppublication.html" title="DROP PUBLICATION"><span class="refentrytitle">DROP PUBLICATION</span></a>, <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>, <a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterprocedure.html" title="ALTER PROCEDURE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterrole.html" title="ALTER ROLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER PROCEDURE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER ROLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterrole.html b/doc/src/sgml/html/sql-alterrole.html
new file mode 100644
index 0000000..42d0e56
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterrole.html
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER ROLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterpublication.html" title="ALTER PUBLICATION" /><link rel="next" href="sql-alterroutine.html" title="ALTER ROUTINE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER ROLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterpublication.html" title="ALTER PUBLICATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterroutine.html" title="ALTER ROUTINE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERROLE"><div class="titlepage"></div><a id="id-1.9.3.26.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER ROLE</span></h2><p>ALTER ROLE — change a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER ROLE <em class="replaceable"><code>role_specification</code></em> [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ SUPERUSER | NOSUPERUSER
+ | CREATEDB | NOCREATEDB
+ | CREATEROLE | NOCREATEROLE
+ | INHERIT | NOINHERIT
+ | LOGIN | NOLOGIN
+ | REPLICATION | NOREPLICATION
+ | BYPASSRLS | NOBYPASSRLS
+ | CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ | [ ENCRYPTED ] PASSWORD '<em class="replaceable"><code>password</code></em>' | PASSWORD NULL
+ | VALID UNTIL '<em class="replaceable"><code>timestamp</code></em>'
+
+ALTER ROLE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER ROLE { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ALTER ROLE { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ALTER ROLE { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ALTER ROLE { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] RESET ALL
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ <em class="replaceable"><code>role_name</code></em>
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+</pre></div><div class="refsect1" id="id-1.9.3.26.5"><h2>Description</h2><p>
+ <code class="command">ALTER ROLE</code> changes the attributes of a
+ <span class="productname">PostgreSQL</span> role.
+ </p><p>
+ The first variant of this command listed in the synopsis can change
+ many of the role attributes that can be specified in
+ <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a>.
+ (All the possible attributes are covered,
+ except that there are no options for adding or removing memberships; use
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a> for that.)
+ Attributes not mentioned in the command retain their previous settings.
+ Database superusers can change any of these settings for any role.
+ Roles having <code class="literal">CREATEROLE</code> privilege can change any of these
+ settings except <code class="literal">SUPERUSER</code>, <code class="literal">REPLICATION</code>,
+ and <code class="literal">BYPASSRLS</code>; but only for non-superuser and
+ non-replication roles.
+ Ordinary roles can only change their own password.
+ </p><p>
+ The second variant changes the name of the role.
+ Database superusers can rename any role.
+ Roles having <code class="literal">CREATEROLE</code> privilege can rename non-superuser
+ roles.
+ The current session user cannot be renamed.
+ (Connect as a different user if you need to do that.)
+ Because <code class="literal">MD5</code>-encrypted passwords use the role name as
+ cryptographic salt, renaming a role clears its password if the
+ password is <code class="literal">MD5</code>-encrypted.
+ </p><p>
+ The remaining variants change a role's session default for a configuration
+ variable, either for all databases or, when the <code class="literal">IN
+ DATABASE</code> clause is specified, only for sessions in the named
+ database. If <code class="literal">ALL</code> is specified instead of a role name,
+ this changes the setting for all roles. Using <code class="literal">ALL</code>
+ with <code class="literal">IN DATABASE</code> is effectively the same as using the
+ command <code class="literal">ALTER DATABASE ... SET ...</code>.
+ </p><p>
+ Whenever the role subsequently
+ starts a new session, the specified value becomes the session
+ default, overriding whatever setting is present in
+ <code class="filename">postgresql.conf</code> or has been received from the <code class="command">postgres</code>
+ command line. This only happens at login time; executing
+ <a class="link" href="sql-set-role.html" title="SET ROLE"><code class="command">SET ROLE</code></a> or
+ <a class="link" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION"><code class="command">SET SESSION AUTHORIZATION</code></a> does not cause new
+ configuration values to be set.
+ Settings set for all databases are overridden by database-specific settings
+ attached to a role. Settings for specific databases or specific roles override
+ settings for all roles.
+ </p><p>
+ Superusers can change anyone's session defaults. Roles having
+ <code class="literal">CREATEROLE</code> privilege can change defaults for non-superuser
+ roles. Ordinary roles can only set defaults for themselves.
+ Certain configuration variables cannot be set this way, or can only be
+ set if a superuser issues the command. Only superusers can change a setting
+ for all roles in all databases.
+ </p></div><div class="refsect1" id="id-1.9.3.26.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the role whose attributes are to be altered.
+ </p></dd><dt><span class="term"><code class="literal">CURRENT_ROLE</code><br /></span><span class="term"><code class="literal">CURRENT_USER</code></span></dt><dd><p>
+ Alter the current user instead of an explicitly identified role.
+ </p></dd><dt><span class="term"><code class="literal">SESSION_USER</code></span></dt><dd><p>
+ Alter the current session user instead of an explicitly identified
+ role.
+ </p></dd><dt><span class="term"><code class="literal">SUPERUSER</code><br /></span><span class="term"><code class="literal">NOSUPERUSER</code><br /></span><span class="term"><code class="literal">CREATEDB</code><br /></span><span class="term"><code class="literal">NOCREATEDB</code><br /></span><span class="term"><code class="literal">CREATEROLE</code><br /></span><span class="term"><code class="literal">NOCREATEROLE</code><br /></span><span class="term"><code class="literal">INHERIT</code><br /></span><span class="term"><code class="literal">NOINHERIT</code><br /></span><span class="term"><code class="literal">LOGIN</code><br /></span><span class="term"><code class="literal">NOLOGIN</code><br /></span><span class="term"><code class="literal">REPLICATION</code><br /></span><span class="term"><code class="literal">NOREPLICATION</code><br /></span><span class="term"><code class="literal">BYPASSRLS</code><br /></span><span class="term"><code class="literal">NOBYPASSRLS</code><br /></span><span class="term"><code class="literal">CONNECTION LIMIT</code> <em class="replaceable"><code>connlimit</code></em><br /></span><span class="term">[ <code class="literal">ENCRYPTED</code> ] <code class="literal">PASSWORD</code> '<em class="replaceable"><code>password</code></em>'<br /></span><span class="term"><code class="literal">PASSWORD NULL</code><br /></span><span class="term"><code class="literal">VALID UNTIL</code> '<em class="replaceable"><code>timestamp</code></em>'</span></dt><dd><p>
+ These clauses alter attributes originally set by
+ <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a>. For more information, see the
+ <code class="command">CREATE ROLE</code> reference page.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the role.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>database_name</code></em></span></dt><dd><p>
+ The name of the database the configuration variable should be set in.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ Set this role's session default for the specified configuration
+ parameter to the given value. If
+ <em class="replaceable"><code>value</code></em> is <code class="literal">DEFAULT</code>
+ or, equivalently, <code class="literal">RESET</code> is used, the
+ role-specific variable setting is removed, so the role will
+ inherit the system-wide default setting in new sessions. Use
+ <code class="literal">RESET ALL</code> to clear all role-specific settings.
+ <code class="literal">SET FROM CURRENT</code> saves the session's current value of
+ the parameter as the role-specific value.
+ If <code class="literal">IN DATABASE</code> is specified, the configuration
+ parameter is set or removed for the given role and database only.
+ </p><p>
+ Role-specific variable settings take effect only at login;
+ <a class="link" href="sql-set-role.html" title="SET ROLE"><code class="command">SET ROLE</code></a> and
+ <a class="link" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION"><code class="command">SET SESSION AUTHORIZATION</code></a>
+ do not process role-specific variable settings.
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for more information about allowed
+ parameter names and values.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.26.7"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a>
+ to add new roles, and <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a> to remove a role.
+ </p><p>
+ <code class="command">ALTER ROLE</code> cannot change a role's memberships.
+ Use <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a>
+ to do that.
+ </p><p>
+ Caution must be exercised when specifying an unencrypted password
+ with this command. The password will be transmitted to the server
+ in cleartext, and it might also be logged in the client's command
+ history or the server log. <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>
+ contains a command
+ <code class="command">\password</code> that can be used to change a
+ role's password without exposing the cleartext password.
+ </p><p>
+ It is also possible to tie a
+ session default to a specific database rather than to a role; see
+ <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>.
+ If there is a conflict, database-role-specific settings override role-specific
+ ones, which in turn override database-specific ones.
+ </p></div><div class="refsect1" id="id-1.9.3.26.8"><h2>Examples</h2><p>
+ Change a role's password:
+
+</p><pre class="programlisting">
+ALTER ROLE davide WITH PASSWORD 'hu8jmn3';
+</pre><p>
+ </p><p>
+ Remove a role's password:
+
+</p><pre class="programlisting">
+ALTER ROLE davide WITH PASSWORD NULL;
+</pre><p>
+ </p><p>
+ Change a password expiration date, specifying that the password
+ should expire at midday on 4th May 2015 using
+ the time zone which is one hour ahead of <acronym class="acronym">UTC</acronym>:
+</p><pre class="programlisting">
+ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1';
+</pre><p>
+ </p><p>
+ Make a password valid forever:
+</p><pre class="programlisting">
+ALTER ROLE fred VALID UNTIL 'infinity';
+</pre><p>
+ </p><p>
+ Give a role the ability to manage other roles and create new databases:
+
+</p><pre class="programlisting">
+ALTER ROLE miriam CREATEROLE CREATEDB;
+</pre><p>
+ </p><p>
+ Give a role a non-default setting of the
+ <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a> parameter:
+
+</p><pre class="programlisting">
+ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
+</pre><p>
+ </p><p>
+ Give a role a non-default, database-specific setting of the
+ <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> parameter:
+
+</p><pre class="programlisting">
+ALTER ROLE fred IN DATABASE devel SET client_min_messages = DEBUG;
+</pre></div><div class="refsect1" id="id-1.9.3.26.9"><h2>Compatibility</h2><p>
+ The <code class="command">ALTER ROLE</code> statement is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.26.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>, <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a>, <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>, <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterpublication.html" title="ALTER PUBLICATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterroutine.html" title="ALTER ROUTINE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER PUBLICATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER ROUTINE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterroutine.html b/doc/src/sgml/html/sql-alterroutine.html
new file mode 100644
index 0000000..d28c780
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterroutine.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER ROUTINE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterrole.html" title="ALTER ROLE" /><link rel="next" href="sql-alterrule.html" title="ALTER RULE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER ROUTINE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterrole.html" title="ALTER ROLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterrule.html" title="ALTER RULE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERROUTINE"><div class="titlepage"></div><a id="id-1.9.3.27.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER ROUTINE</span></h2><p>ALTER ROUTINE — change the definition of a routine</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER ROUTINE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ <em class="replaceable"><code>action</code></em> [ ... ] [ RESTRICT ]
+ALTER ROUTINE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER ROUTINE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER ROUTINE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER ROUTINE <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ]
+ [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ IMMUTABLE | STABLE | VOLATILE
+ [ NOT ] LEAKPROOF
+ [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
+ PARALLEL { UNSAFE | RESTRICTED | SAFE }
+ COST <em class="replaceable"><code>execution_cost</code></em>
+ ROWS <em class="replaceable"><code>result_rows</code></em>
+ SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.27.5"><h2>Description</h2><p>
+ <code class="command">ALTER ROUTINE</code> changes the definition of a routine, which
+ can be an aggregate function, a normal function, or a procedure. See
+ under <a class="xref" href="sql-alteraggregate.html" title="ALTER AGGREGATE"><span class="refentrytitle">ALTER AGGREGATE</span></a>, <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>,
+ and <a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a> for the description of the
+ parameters, more examples, and further details.
+ </p></div><div class="refsect1" id="id-1.9.3.27.6"><h2>Examples</h2><p>
+ To rename the routine <code class="literal">foo</code> for type
+ <code class="type">integer</code> to <code class="literal">foobar</code>:
+</p><pre class="programlisting">
+ALTER ROUTINE foo(integer) RENAME TO foobar;
+</pre><p>
+ This command will work independent of whether <code class="literal">foo</code> is an
+ aggregate, function, or procedure.
+ </p></div><div class="refsect1" id="id-1.9.3.27.7"><h2>Compatibility</h2><p>
+ This statement is partially compatible with the <code class="command">ALTER
+ ROUTINE</code> statement in the SQL standard. See
+ under <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>
+ and <a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a> for more details. Allowing
+ routine names to refer to aggregate functions is
+ a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.27.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteraggregate.html" title="ALTER AGGREGATE"><span class="refentrytitle">ALTER AGGREGATE</span></a>, <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, <a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a>, <a class="xref" href="sql-droproutine.html" title="DROP ROUTINE"><span class="refentrytitle">DROP ROUTINE</span></a></span><p>
+ Note that there is no <code class="literal">CREATE ROUTINE</code> command.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterrole.html" title="ALTER ROLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterrule.html" title="ALTER RULE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER ROLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER RULE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterrule.html b/doc/src/sgml/html/sql-alterrule.html
new file mode 100644
index 0000000..8c56d6e
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterrule.html
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER RULE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterroutine.html" title="ALTER ROUTINE" /><link rel="next" href="sql-alterschema.html" title="ALTER SCHEMA" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER RULE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterroutine.html" title="ALTER ROUTINE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterschema.html" title="ALTER SCHEMA">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERRULE"><div class="titlepage"></div><a id="id-1.9.3.28.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER RULE</span></h2><p>ALTER RULE — change the definition of a rule</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER RULE <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.28.5"><h2>Description</h2><p>
+ <code class="command">ALTER RULE</code> changes properties of an existing
+ rule. Currently, the only available action is to change the rule's name.
+ </p><p>
+ To use <code class="command">ALTER RULE</code>, you must own the table or view that
+ the rule applies to.
+ </p></div><div class="refsect1" id="id-1.9.3.28.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing rule to alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table or view that the
+ rule applies to.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the rule.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.28.7"><h2>Examples</h2><p>
+ To rename an existing rule:
+</p><pre class="programlisting">
+ALTER RULE notify_all ON emp RENAME TO notify_me;
+</pre></div><div class="refsect1" id="id-1.9.3.28.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER RULE</code> is a
+ <span class="productname">PostgreSQL</span> language extension, as is the
+ entire query rewrite system.
+ </p></div><div class="refsect1" id="id-1.9.3.28.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrule.html" title="CREATE RULE"><span class="refentrytitle">CREATE RULE</span></a>, <a class="xref" href="sql-droprule.html" title="DROP RULE"><span class="refentrytitle">DROP RULE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterroutine.html" title="ALTER ROUTINE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterschema.html" title="ALTER SCHEMA">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER ROUTINE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER SCHEMA</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterschema.html b/doc/src/sgml/html/sql-alterschema.html
new file mode 100644
index 0000000..9593f50
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterschema.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER SCHEMA</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterrule.html" title="ALTER RULE" /><link rel="next" href="sql-altersequence.html" title="ALTER SEQUENCE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER SCHEMA</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterrule.html" title="ALTER RULE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altersequence.html" title="ALTER SEQUENCE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSCHEMA"><div class="titlepage"></div><a id="id-1.9.3.29.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER SCHEMA</span></h2><p>ALTER SCHEMA — change the definition of a schema</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER SCHEMA <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER SCHEMA <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+</pre></div><div class="refsect1" id="id-1.9.3.29.5"><h2>Description</h2><p>
+ <code class="command">ALTER SCHEMA</code> changes the definition of a schema.
+ </p><p>
+ You must own the schema to use <code class="command">ALTER SCHEMA</code>.
+ To rename a schema you must also have the
+ <code class="literal">CREATE</code> privilege for the database.
+ To alter the owner, you must also be a direct or
+ indirect member of the new owning role, and you must have the
+ <code class="literal">CREATE</code> privilege for the database.
+ (Note that superusers have all these privileges automatically.)
+ </p></div><div class="refsect1" id="id-1.9.3.29.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the schema. The new name cannot
+ begin with <code class="literal">pg_</code>, as such names
+ are reserved for system schemas.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the schema.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.29.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER SCHEMA</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.29.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createschema.html" title="CREATE SCHEMA"><span class="refentrytitle">CREATE SCHEMA</span></a>, <a class="xref" href="sql-dropschema.html" title="DROP SCHEMA"><span class="refentrytitle">DROP SCHEMA</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterrule.html" title="ALTER RULE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altersequence.html" title="ALTER SEQUENCE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER RULE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER SEQUENCE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altersequence.html b/doc/src/sgml/html/sql-altersequence.html
new file mode 100644
index 0000000..7bed788
--- /dev/null
+++ b/doc/src/sgml/html/sql-altersequence.html
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER SEQUENCE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterschema.html" title="ALTER SCHEMA" /><link rel="next" href="sql-alterserver.html" title="ALTER SERVER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER SEQUENCE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterschema.html" title="ALTER SCHEMA">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterserver.html" title="ALTER SERVER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSEQUENCE"><div class="titlepage"></div><a id="id-1.9.3.30.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER SEQUENCE</span></h2><p>ALTER SEQUENCE —
+ change the definition of a sequence generator
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ [ AS <em class="replaceable"><code>data_type</code></em> ]
+ [ INCREMENT [ BY ] <em class="replaceable"><code>increment</code></em> ]
+ [ MINVALUE <em class="replaceable"><code>minvalue</code></em> | NO MINVALUE ] [ MAXVALUE <em class="replaceable"><code>maxvalue</code></em> | NO MAXVALUE ]
+ [ START [ WITH ] <em class="replaceable"><code>start</code></em> ]
+ [ RESTART [ [ WITH ] <em class="replaceable"><code>restart</code></em> ] ]
+ [ CACHE <em class="replaceable"><code>cache</code></em> ] [ [ NO ] CYCLE ]
+ [ OWNED BY { <em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em> | NONE } ]
+ALTER SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET { LOGGED | UNLOGGED }
+ALTER SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.30.5"><h2>Description</h2><p>
+ <code class="command">ALTER SEQUENCE</code> changes the parameters of an existing
+ sequence generator. Any parameters not specifically set in the
+ <code class="command">ALTER SEQUENCE</code> command retain their prior settings.
+ </p><p>
+ You must own the sequence to use <code class="command">ALTER SEQUENCE</code>.
+ To change a sequence's schema, you must also have <code class="literal">CREATE</code>
+ privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the sequence's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the sequence.
+ However, a superuser can alter ownership of any sequence anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.30.6"><h2>Parameters</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a sequence to be altered.
+ </p></dd><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the sequence does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The optional
+ clause <code class="literal">AS <em class="replaceable"><code>data_type</code></em></code>
+ changes the data type of the sequence. Valid types are
+ <code class="literal">smallint</code>, <code class="literal">integer</code>,
+ and <code class="literal">bigint</code>.
+ </p><p>
+ Changing the data type automatically changes the minimum and maximum
+ values of the sequence if and only if the previous minimum and maximum
+ values were the minimum or maximum value of the old data type (in
+ other words, if the sequence had been created using <code class="literal">NO
+ MINVALUE</code> or <code class="literal">NO MAXVALUE</code>, implicitly or
+ explicitly). Otherwise, the minimum and maximum values are preserved,
+ unless new values are given as part of the same command. If the
+ minimum and maximum values do not fit into the new data type, an error
+ will be generated.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>increment</code></em></span></dt><dd><p>
+ The clause <code class="literal">INCREMENT BY <em class="replaceable"><code>increment</code></em></code> is
+ optional. A positive value will make an ascending sequence, a
+ negative one a descending sequence. If unspecified, the old
+ increment value will be maintained.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>minvalue</code></em><br /></span><span class="term"><code class="literal">NO MINVALUE</code></span></dt><dd><p>
+ The optional clause <code class="literal">MINVALUE <em class="replaceable"><code>minvalue</code></em></code> determines
+ the minimum value a sequence can generate. If <code class="literal">NO
+ MINVALUE</code> is specified, the defaults of 1 and
+ the minimum value of the data type for ascending and descending sequences,
+ respectively, will be used. If neither option is specified,
+ the current minimum value will be maintained.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>maxvalue</code></em><br /></span><span class="term"><code class="literal">NO MAXVALUE</code></span></dt><dd><p>
+ The optional clause <code class="literal">MAXVALUE <em class="replaceable"><code>maxvalue</code></em></code> determines
+ the maximum value for the sequence. If <code class="literal">NO
+ MAXVALUE</code> is specified, the defaults of
+ the maximum value of the data type and -1 for ascending and descending
+ sequences, respectively, will be used. If neither option is
+ specified, the current maximum value will be maintained.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>start</code></em></span></dt><dd><p>
+ The optional clause <code class="literal">START WITH <em class="replaceable"><code>start</code></em></code> changes the
+ recorded start value of the sequence. This has no effect on the
+ <span class="emphasis"><em>current</em></span> sequence value; it simply sets the value
+ that future <code class="command">ALTER SEQUENCE RESTART</code> commands will use.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>restart</code></em></span></dt><dd><p>
+ The optional clause <code class="literal">RESTART [ WITH <em class="replaceable"><code>restart</code></em> ]</code> changes the
+ current value of the sequence. This is similar to calling the
+ <code class="function">setval</code> function with <code class="literal">is_called</code> =
+ <code class="literal">false</code>: the specified value will be returned by the
+ <span class="emphasis"><em>next</em></span> call of <code class="function">nextval</code>.
+ Writing <code class="literal">RESTART</code> with no <em class="replaceable"><code>restart</code></em> value is equivalent to supplying
+ the start value that was recorded by <code class="command">CREATE SEQUENCE</code>
+ or last set by <code class="command">ALTER SEQUENCE START WITH</code>.
+ </p><p>
+ In contrast to a <code class="function">setval</code> call,
+ a <code class="literal">RESTART</code> operation on a sequence is transactional
+ and blocks concurrent transactions from obtaining numbers from the
+ same sequence. If that's not the desired mode of
+ operation, <code class="function">setval</code> should be used.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cache</code></em></span></dt><dd><p>
+ The clause <code class="literal">CACHE <em class="replaceable"><code>cache</code></em></code> enables
+ sequence numbers to be preallocated and stored in memory for
+ faster access. The minimum value is 1 (only one value can be
+ generated at a time, i.e., no cache). If unspecified, the old
+ cache value will be maintained.
+ </p></dd><dt><span class="term"><code class="literal">CYCLE</code></span></dt><dd><p>
+ The optional <code class="literal">CYCLE</code> key word can be used to enable
+ the sequence to wrap around when the
+ <em class="replaceable"><code>maxvalue</code></em> or
+ <em class="replaceable"><code>minvalue</code></em> has been
+ reached by
+ an ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the
+ <em class="replaceable"><code>minvalue</code></em> or
+ <em class="replaceable"><code>maxvalue</code></em>,
+ respectively.
+ </p></dd><dt><span class="term"><code class="literal">NO CYCLE</code></span></dt><dd><p>
+ If the optional <code class="literal">NO CYCLE</code> key word is
+ specified, any calls to <code class="function">nextval</code> after the
+ sequence has reached its maximum value will return an error.
+ If neither <code class="literal">CYCLE</code> or <code class="literal">NO
+ CYCLE</code> are specified, the old cycle behavior will be
+ maintained.
+ </p></dd><dt><span class="term"><code class="literal">SET { LOGGED | UNLOGGED }</code></span></dt><dd><p>
+ This form changes the sequence from unlogged to logged or vice-versa
+ (see <a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a>). It cannot be applied to a
+ temporary sequence.
+ </p></dd><dt><span class="term"><code class="literal">OWNED BY</code> <em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em><br /></span><span class="term"><code class="literal">OWNED BY NONE</code></span></dt><dd><p>
+ The <code class="literal">OWNED BY</code> option causes the sequence to be
+ associated with a specific table column, such that if that column
+ (or its whole table) is dropped, the sequence will be automatically
+ dropped as well. If specified, this association replaces any
+ previously specified association for the sequence. The specified
+ table must have the same owner and be in the same schema as the
+ sequence.
+ Specifying <code class="literal">OWNED BY NONE</code> removes any existing
+ association, making the sequence <span class="quote">“<span class="quote">free-standing</span>”</span>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the sequence.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the sequence.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the sequence.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.30.7"><h2>Notes</h2><p>
+ <code class="command">ALTER SEQUENCE</code> will not immediately affect
+ <code class="function">nextval</code> results in backends,
+ other than the current one, that have preallocated (cached) sequence
+ values. They will use up all cached values prior to noticing the changed
+ sequence generation parameters. The current backend will be affected
+ immediately.
+ </p><p>
+ <code class="command">ALTER SEQUENCE</code> does not affect the <code class="function">currval</code>
+ status for the sequence. (Before <span class="productname">PostgreSQL</span>
+ 8.3, it sometimes did.)
+ </p><p>
+ <code class="command">ALTER SEQUENCE</code> blocks
+ concurrent <code class="function">nextval</code>, <code class="function">currval</code>,
+ <code class="function">lastval</code>, and <code class="command">setval</code> calls.
+ </p><p>
+ For historical reasons, <code class="command">ALTER TABLE</code> can be used with
+ sequences too; but the only variants of <code class="command">ALTER TABLE</code>
+ that are allowed with sequences are equivalent to the forms shown above.
+ </p></div><div class="refsect1" id="id-1.9.3.30.8"><h2>Examples</h2><p>
+ Restart a sequence called <code class="literal">serial</code>, at 105:
+</p><pre class="programlisting">
+ALTER SEQUENCE serial RESTART WITH 105;
+</pre></div><div class="refsect1" id="id-1.9.3.30.9"><h2>Compatibility</h2><p>
+ <code class="command">ALTER SEQUENCE</code> conforms to the <acronym class="acronym">SQL</acronym>
+ standard, except for the <code class="literal">AS</code>, <code class="literal">START WITH</code>,
+ <code class="literal">OWNED BY</code>, <code class="literal">OWNER TO</code>, <code class="literal">RENAME TO</code>, and
+ <code class="literal">SET SCHEMA</code> clauses, which are
+ <span class="productname">PostgreSQL</span> extensions.
+ </p></div><div class="refsect1" id="id-1.9.3.30.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a>, <a class="xref" href="sql-dropsequence.html" title="DROP SEQUENCE"><span class="refentrytitle">DROP SEQUENCE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterschema.html" title="ALTER SCHEMA">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterserver.html" title="ALTER SERVER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER SCHEMA </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER SERVER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterserver.html b/doc/src/sgml/html/sql-alterserver.html
new file mode 100644
index 0000000..619b20c
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterserver.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER SERVER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altersequence.html" title="ALTER SEQUENCE" /><link rel="next" href="sql-alterstatistics.html" title="ALTER STATISTICS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER SERVER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altersequence.html" title="ALTER SEQUENCE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterstatistics.html" title="ALTER STATISTICS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSERVER"><div class="titlepage"></div><a id="id-1.9.3.31.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER SERVER</span></h2><p>ALTER SERVER — change the definition of a foreign server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER SERVER <em class="replaceable"><code>name</code></em> [ VERSION '<em class="replaceable"><code>new_version</code></em>' ]
+ [ OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] ) ]
+ALTER SERVER <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER SERVER <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.31.5"><h2>Description</h2><p>
+ <code class="command">ALTER SERVER</code> changes the definition of a foreign
+ server. The first form changes the server version string or the
+ generic options of the server (at least one clause is required).
+ The second form changes the owner of the server.
+ </p><p>
+ To alter the server you must be the owner of the server.
+ Additionally to alter the owner, you must own the server and also
+ be a direct or indirect member of the new owning role, and you must
+ have <code class="literal">USAGE</code> privilege on the server's foreign-data
+ wrapper. (Note that superusers satisfy all these criteria
+ automatically.)
+ </p></div><div class="refsect1" id="id-1.9.3.31.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing server.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_version</code></em></span></dt><dd><p>
+ New server version.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )</code></span></dt><dd><p>
+ Change options for the
+ server. <code class="literal">ADD</code>, <code class="literal">SET</code>, and <code class="literal">DROP</code>
+ specify the action to be performed. <code class="literal">ADD</code> is assumed
+ if no operation is explicitly specified. Option names must be
+ unique; names and values are also validated using the server's
+ foreign-data wrapper library.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the foreign server.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the foreign server.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.31.7"><h2>Examples</h2><p>
+ Alter server <code class="literal">foo</code>, add connection options:
+</p><pre class="programlisting">
+ALTER SERVER foo OPTIONS (host 'foo', dbname 'foodb');
+</pre><p>
+ </p><p>
+ Alter server <code class="literal">foo</code>, change version,
+ change <code class="literal">host</code> option:
+</p><pre class="programlisting">
+ALTER SERVER foo VERSION '8.4' OPTIONS (SET host 'baz');
+</pre></div><div class="refsect1" id="id-1.9.3.31.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER SERVER</code> conforms to ISO/IEC 9075-9 (SQL/MED).
+ The <code class="literal">OWNER TO</code> and <code class="literal">RENAME</code> forms are
+ PostgreSQL extensions.
+ </p></div><div class="refsect1" id="id-1.9.3.31.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>, <a class="xref" href="sql-dropserver.html" title="DROP SERVER"><span class="refentrytitle">DROP SERVER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altersequence.html" title="ALTER SEQUENCE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterstatistics.html" title="ALTER STATISTICS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER SEQUENCE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER STATISTICS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterstatistics.html b/doc/src/sgml/html/sql-alterstatistics.html
new file mode 100644
index 0000000..8f9a3e8
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterstatistics.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER STATISTICS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterserver.html" title="ALTER SERVER" /><link rel="next" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER STATISTICS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterserver.html" title="ALTER SERVER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSTATISTICS"><div class="titlepage"></div><a id="id-1.9.3.32.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER STATISTICS</span></h2><p>ALTER STATISTICS —
+ change the definition of an extended statistics object
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER STATISTICS <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER STATISTICS <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER STATISTICS <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER STATISTICS <em class="replaceable"><code>name</code></em> SET STATISTICS <em class="replaceable"><code>new_target</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.32.5"><h2>Description</h2><p>
+ <code class="command">ALTER STATISTICS</code> changes the parameters of an existing
+ extended statistics object. Any parameters not specifically set in the
+ <code class="command">ALTER STATISTICS</code> command retain their prior settings.
+ </p><p>
+ You must own the statistics object to use <code class="command">ALTER STATISTICS</code>.
+ To change a statistics object's schema, you must also
+ have <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the statistics object's schema. (These restrictions enforce that altering
+ the owner doesn't do anything you couldn't do by dropping and recreating
+ the statistics object. However, a superuser can alter ownership of any
+ statistics object anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.32.6"><h2>Parameters</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the statistics object to be
+ altered.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the statistics object.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the statistics object.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the statistics object.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_target</code></em></span></dt><dd><p>
+ The statistic-gathering target for this statistics object for subsequent
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> operations.
+ The target can be set in the range 0 to 10000; alternatively, set it
+ to -1 to revert to using the maximum of the statistics target of the
+ referenced columns, if set, or the system default statistics
+ target (<a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a>).
+ For more information on the use of statistics by the
+ <span class="productname">PostgreSQL</span> query planner, refer to
+ <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.32.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER STATISTICS</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.32.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createstatistics.html" title="CREATE STATISTICS"><span class="refentrytitle">CREATE STATISTICS</span></a>, <a class="xref" href="sql-dropstatistics.html" title="DROP STATISTICS"><span class="refentrytitle">DROP STATISTICS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterserver.html" title="ALTER SERVER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER SERVER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER SUBSCRIPTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altersubscription.html b/doc/src/sgml/html/sql-altersubscription.html
new file mode 100644
index 0000000..a412cd7
--- /dev/null
+++ b/doc/src/sgml/html/sql-altersubscription.html
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER SUBSCRIPTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterstatistics.html" title="ALTER STATISTICS" /><link rel="next" href="sql-altersystem.html" title="ALTER SYSTEM" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER SUBSCRIPTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterstatistics.html" title="ALTER STATISTICS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altersystem.html" title="ALTER SYSTEM">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSUBSCRIPTION"><div class="titlepage"></div><a id="id-1.9.3.33.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER SUBSCRIPTION</span></h2><p>ALTER SUBSCRIPTION — change the definition of a subscription</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> CONNECTION '<em class="replaceable"><code>conninfo</code></em>'
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> SET PUBLICATION <em class="replaceable"><code>publication_name</code></em> [, ...] [ WITH ( <em class="replaceable"><code>publication_option</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> ADD PUBLICATION <em class="replaceable"><code>publication_name</code></em> [, ...] [ WITH ( <em class="replaceable"><code>publication_option</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> DROP PUBLICATION <em class="replaceable"><code>publication_name</code></em> [, ...] [ WITH ( <em class="replaceable"><code>publication_option</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> REFRESH PUBLICATION [ WITH ( <em class="replaceable"><code>refresh_option</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> ENABLE
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> DISABLE
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>subscription_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> SKIP ( <em class="replaceable"><code>skip_option</code></em> = <em class="replaceable"><code>value</code></em> )
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER SUBSCRIPTION <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.33.5"><h2>Description</h2><p>
+ <code class="command">ALTER SUBSCRIPTION</code> can change most of the subscription
+ properties that can be specified
+ in <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>.
+ </p><p>
+ You must own the subscription to use <code class="command">ALTER SUBSCRIPTION</code>.
+ To alter the owner, you must also be a direct or indirect member of the
+ new owning role. The new owner has to be a superuser.
+ (Currently, all subscription owners must be superusers, so the owner checks
+ will be bypassed in practice. But this might change in the future.)
+ </p><p>
+ When refreshing a publication we remove the relations that are no longer
+ part of the publication and we also remove the table synchronization slots
+ if there are any. It is necessary to remove these slots so that the resources
+ allocated for the subscription on the remote host are released. If due to
+ network breakdown or some other error, <span class="productname">PostgreSQL</span>
+ is unable to remove the slots, an error will be reported. To proceed in this
+ situation, the user either needs to retry the operation or disassociate the
+ slot from the subscription and drop the subscription as explained in
+ <a class="xref" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION"><span class="refentrytitle">DROP SUBSCRIPTION</span></a>.
+ </p><p>
+ Commands <code class="command">ALTER SUBSCRIPTION ... REFRESH PUBLICATION</code> and
+ <code class="command">ALTER SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ...</code>
+ with <code class="literal">refresh</code> option as <code class="literal">true</code> cannot be
+ executed inside a transaction block.
+
+ These commands also cannot be executed when the subscription has
+ <code class="literal">two_phase</code> commit enabled,
+ unless <code class="literal">copy_data</code> is <code class="literal">false</code>.
+ See column <code class="structfield">subtwophasestate</code> of
+ <a class="link" href="catalog-pg-subscription.html" title="53.54. pg_subscription"><code class="structname">pg_subscription</code></a>
+ to know the actual two-phase state.
+ </p></div><div class="refsect1" id="id-1.9.3.33.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a subscription whose properties are to be altered.
+ </p></dd><dt><span class="term"><code class="literal">CONNECTION '<em class="replaceable"><code>conninfo</code></em>'</code></span></dt><dd><p>
+ This clause replaces the connection string originally set by
+ <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>. See there for more
+ information.
+ </p></dd><dt><span class="term"><code class="literal">SET PUBLICATION <em class="replaceable"><code>publication_name</code></em></code><br /></span><span class="term"><code class="literal">ADD PUBLICATION <em class="replaceable"><code>publication_name</code></em></code><br /></span><span class="term"><code class="literal">DROP PUBLICATION <em class="replaceable"><code>publication_name</code></em></code></span></dt><dd><p>
+ These forms change the list of subscribed publications.
+ <code class="literal">SET</code>
+ replaces the entire list of publications with a new list,
+ <code class="literal">ADD</code> adds additional publications to the list of
+ publications, and <code class="literal">DROP</code> removes the publications from
+ the list of publications. We allow non-existent publications to be
+ specified in <code class="literal">ADD</code> and <code class="literal">SET</code> variants
+ so that users can add those later. See <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>
+ for more information. By default, this command will also act like
+ <code class="literal">REFRESH PUBLICATION</code>.
+ </p><p>
+ <em class="replaceable"><code>publication_option</code></em> specifies additional
+ options for this operation. The supported options are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">refresh</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ When false, the command will not try to refresh table information.
+ <code class="literal">REFRESH PUBLICATION</code> should then be executed separately.
+ The default is <code class="literal">true</code>.
+ </p></dd></dl></div><p>
+
+ Additionally, the options described under
+ <code class="literal">REFRESH PUBLICATION</code> may be specified, to control the
+ implicit refresh operation.
+ </p></dd><dt><span class="term"><code class="literal">REFRESH PUBLICATION</code></span></dt><dd><p>
+ Fetch missing table information from publisher. This will start
+ replication of tables that were added to the subscribed-to publications
+ since <code class="command">CREATE SUBSCRIPTION</code> or
+ the last invocation of <code class="command">REFRESH PUBLICATION</code>.
+ </p><p>
+ <em class="replaceable"><code>refresh_option</code></em> specifies additional options for the
+ refresh operation. The supported options are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">copy_data</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether to copy pre-existing data in the publications
+ that are being subscribed to when the replication starts.
+ The default is <code class="literal">true</code>.
+ </p><p>
+ Previously subscribed tables are not copied, even if a table's row
+ filter <code class="literal">WHERE</code> clause has since been modified.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="literal">ENABLE</code></span></dt><dd><p>
+ Enables a previously disabled subscription, starting the logical
+ replication worker at the end of the transaction.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code></span></dt><dd><p>
+ Disables a running subscription, stopping the logical replication
+ worker at the end of the transaction.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>subscription_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause alters parameters originally set by
+ <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>. See there for more
+ information. The parameters that can be altered
+ are <code class="literal">slot_name</code>,
+ <code class="literal">synchronous_commit</code>,
+ <code class="literal">binary</code>, <code class="literal">streaming</code>, and
+ <code class="literal">disable_on_error</code>.
+ </p></dd><dt><span class="term"><code class="literal">SKIP ( <em class="replaceable"><code>skip_option</code></em> = <em class="replaceable"><code>value</code></em> )</code></span></dt><dd><p>
+ Skips applying all changes of the remote transaction. If incoming data
+ violates any constraints, logical replication will stop until it is
+ resolved. By using the <code class="command">ALTER SUBSCRIPTION ... SKIP</code> command,
+ the logical replication worker skips all data modification changes within
+ the transaction. This option has no effect on the transactions that are
+ already prepared by enabling <code class="literal">two_phase</code> on
+ subscriber.
+ After the logical replication worker successfully skips the transaction or
+ finishes a transaction, the LSN (stored in
+ <code class="structname">pg_subscription</code>.<code class="structfield">subskiplsn</code>)
+ is cleared. See <a class="xref" href="logical-replication-conflicts.html" title="31.5. Conflicts">Section 31.5</a> for
+ the details of logical replication conflicts. Using this command requires
+ superuser privilege.
+ </p><p>
+ <em class="replaceable"><code>skip_option</code></em> specifies options for this operation.
+ The supported option is:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">lsn</code> (<code class="type">pg_lsn</code>)</span></dt><dd><p>
+ Specifies the finish LSN of the remote transaction whose changes
+ are to be skipped by the logical replication worker. The finish LSN
+ is the LSN at which the transaction is either committed or prepared.
+ Skipping individual subtransactions is not supported. Setting
+ <code class="literal">NONE</code> resets the LSN.
+ </p></dd></dl></div></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the subscription.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the subscription.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.33.7"><h2>Examples</h2><p>
+ Change the publication subscribed by a subscription to
+ <code class="literal">insert_only</code>:
+</p><pre class="programlisting">
+ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
+</pre><p>
+ </p><p>
+ Disable (stop) the subscription:
+</p><pre class="programlisting">
+ALTER SUBSCRIPTION mysub DISABLE;
+</pre></div><div class="refsect1" id="id-1.9.3.33.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER SUBSCRIPTION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.33.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>, <a class="xref" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION"><span class="refentrytitle">DROP SUBSCRIPTION</span></a>, <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>, <a class="xref" href="sql-alterpublication.html" title="ALTER PUBLICATION"><span class="refentrytitle">ALTER PUBLICATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterstatistics.html" title="ALTER STATISTICS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altersystem.html" title="ALTER SYSTEM">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER STATISTICS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER SYSTEM</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altersystem.html b/doc/src/sgml/html/sql-altersystem.html
new file mode 100644
index 0000000..b0b072e
--- /dev/null
+++ b/doc/src/sgml/html/sql-altersystem.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER SYSTEM</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION" /><link rel="next" href="sql-altertable.html" title="ALTER TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER SYSTEM</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertable.html" title="ALTER TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERSYSTEM"><div class="titlepage"></div><a id="id-1.9.3.34.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER SYSTEM</span></h2><p>ALTER SYSTEM — change a server configuration parameter</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER SYSTEM SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> [, ...] | DEFAULT }
+
+ALTER SYSTEM RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ALTER SYSTEM RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.34.5"><h2>Description</h2><p>
+ <code class="command">ALTER SYSTEM</code> is used for changing server configuration
+ parameters across the entire database cluster. It can be more convenient
+ than the traditional method of manually editing
+ the <code class="filename">postgresql.conf</code> file.
+ <code class="command">ALTER SYSTEM</code> writes the given parameter setting to
+ the <code class="filename">postgresql.auto.conf</code> file, which is read in
+ addition to <code class="filename">postgresql.conf</code>.
+ Setting a parameter to <code class="literal">DEFAULT</code>, or using the
+ <code class="command">RESET</code> variant, removes that configuration entry from the
+ <code class="filename">postgresql.auto.conf</code> file. Use <code class="literal">RESET
+ ALL</code> to remove all such configuration entries.
+ </p><p>
+ Values set with <code class="command">ALTER SYSTEM</code> will be effective after
+ the next server configuration reload, or after the next server restart
+ in the case of parameters that can only be changed at server start.
+ A server configuration reload can be commanded by calling the SQL
+ function <code class="function">pg_reload_conf()</code>, running <code class="literal">pg_ctl reload</code>,
+ or sending a <span class="systemitem">SIGHUP</span> signal to the main server process.
+ </p><p>
+ Only superusers and users granted <code class="literal">ALTER SYSTEM</code> privilege
+ on a parameter can change it using <code class="command">ALTER SYSTEM</code>. Also, since
+ this command acts directly on the file system and cannot be rolled back,
+ it is not allowed inside a transaction block or function.
+ </p></div><div class="refsect1" id="id-1.9.3.34.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em></span></dt><dd><p>
+ Name of a settable configuration parameter. Available parameters are
+ documented in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ New value of the parameter. Values can be specified as string
+ constants, identifiers, numbers, or comma-separated lists of
+ these, as appropriate for the particular parameter.
+ Values that are neither numbers nor valid identifiers must be quoted.
+ <code class="literal">DEFAULT</code> can be written to specify removing the
+ parameter and its value from <code class="filename">postgresql.auto.conf</code>.
+ </p><p>
+ For some list-accepting parameters, quoted values will produce
+ double-quoted output to preserve whitespace and commas; for others,
+ double-quotes must be used inside single-quoted strings to get
+ this effect.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.34.7"><h2>Notes</h2><p>
+ This command can't be used to set <a class="xref" href="runtime-config-file-locations.html#GUC-DATA-DIRECTORY">data_directory</a>,
+ nor parameters that are not allowed in <code class="filename">postgresql.conf</code>
+ (e.g., <a class="link" href="runtime-config-preset.html" title="20.15. Preset Options">preset options</a>).
+ </p><p>
+ See <a class="xref" href="config-setting.html" title="20.1. Setting Parameters">Section 20.1</a> for other ways to set the parameters.
+ </p></div><div class="refsect1" id="id-1.9.3.34.8"><h2>Examples</h2><p>
+ Set the <code class="literal">wal_level</code>:
+</p><pre class="programlisting">
+ALTER SYSTEM SET wal_level = replica;
+</pre><p>
+ </p><p>
+ Undo that, restoring whatever setting was effective
+ in <code class="filename">postgresql.conf</code>:
+</p><pre class="programlisting">
+ALTER SYSTEM RESET wal_level;
+</pre></div><div class="refsect1" id="id-1.9.3.34.9"><h2>Compatibility</h2><p>
+ The <code class="command">ALTER SYSTEM</code> statement is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.34.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>, <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertable.html" title="ALTER TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER SUBSCRIPTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertable.html b/doc/src/sgml/html/sql-altertable.html
new file mode 100644
index 0000000..ed859ce
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertable.html
@@ -0,0 +1,1094 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altersystem.html" title="ALTER SYSTEM" /><link rel="next" href="sql-altertablespace.html" title="ALTER TABLESPACE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altersystem.html" title="ALTER SYSTEM">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertablespace.html" title="ALTER TABLESPACE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTABLE"><div class="titlepage"></div><a id="id-1.9.3.35.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TABLE</span></h2><p>ALTER TABLE — change the definition of a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
+ <em class="replaceable"><code>action</code></em> [, ... ]
+ALTER TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
+ RENAME [ COLUMN ] <em class="replaceable"><code>column_name</code></em> TO <em class="replaceable"><code>new_column_name</code></em>
+ALTER TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
+ RENAME CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> TO <em class="replaceable"><code>new_constraint_name</code></em>
+ALTER TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER TABLE ALL IN TABLESPACE <em class="replaceable"><code>name</code></em> [ OWNED BY <em class="replaceable"><code>role_name</code></em> [, ... ] ]
+ SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em> [ NOWAIT ]
+ALTER TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ ATTACH PARTITION <em class="replaceable"><code>partition_name</code></em> { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }
+ALTER TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+ DETACH PARTITION <em class="replaceable"><code>partition_name</code></em> [ CONCURRENTLY | FINALIZE ]
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ ADD [ COLUMN ] [ IF NOT EXISTS ] <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ DROP [ COLUMN ] [ IF EXISTS ] <em class="replaceable"><code>column_name</code></em> [ RESTRICT | CASCADE ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> [ SET DATA ] TYPE <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ USING <em class="replaceable"><code>expression</code></em> ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET DEFAULT <em class="replaceable"><code>expression</code></em>
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP DEFAULT
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> { SET | DROP } NOT NULL
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP EXPRESSION [ IF EXISTS ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <em class="replaceable"><code>sequence_options</code></em> ) ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> { SET GENERATED { ALWAYS | BY DEFAULT } | SET <em class="replaceable"><code>sequence_option</code></em> | RESTART [ [ WITH ] <em class="replaceable"><code>restart</code></em> ] } [...]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP IDENTITY [ IF EXISTS ]
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STATISTICS <em class="replaceable"><code>integer</code></em>
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
+ ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET COMPRESSION <em class="replaceable"><code>compression_method</code></em>
+ ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]
+ ADD <em class="replaceable"><code>table_constraint_using_index</code></em>
+ ALTER CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+ VALIDATE CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>
+ DROP CONSTRAINT [ IF EXISTS ] <em class="replaceable"><code>constraint_name</code></em> [ RESTRICT | CASCADE ]
+ DISABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
+ ENABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
+ ENABLE REPLICA TRIGGER <em class="replaceable"><code>trigger_name</code></em>
+ ENABLE ALWAYS TRIGGER <em class="replaceable"><code>trigger_name</code></em>
+ DISABLE RULE <em class="replaceable"><code>rewrite_rule_name</code></em>
+ ENABLE RULE <em class="replaceable"><code>rewrite_rule_name</code></em>
+ ENABLE REPLICA RULE <em class="replaceable"><code>rewrite_rule_name</code></em>
+ ENABLE ALWAYS RULE <em class="replaceable"><code>rewrite_rule_name</code></em>
+ DISABLE ROW LEVEL SECURITY
+ ENABLE ROW LEVEL SECURITY
+ FORCE ROW LEVEL SECURITY
+ NO FORCE ROW LEVEL SECURITY
+ CLUSTER ON <em class="replaceable"><code>index_name</code></em>
+ SET WITHOUT CLUSTER
+ SET WITHOUT OIDS
+ SET ACCESS METHOD <em class="replaceable"><code>new_access_method</code></em>
+ SET TABLESPACE <em class="replaceable"><code>new_tablespace</code></em>
+ SET { LOGGED | UNLOGGED }
+ SET ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )
+ RESET ( <em class="replaceable"><code>storage_parameter</code></em> [, ... ] )
+ INHERIT <em class="replaceable"><code>parent_table</code></em>
+ NO INHERIT <em class="replaceable"><code>parent_table</code></em>
+ OF <em class="replaceable"><code>type_name</code></em>
+ NOT OF
+ OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ REPLICA IDENTITY { DEFAULT | USING INDEX <em class="replaceable"><code>index_name</code></em> | FULL | NOTHING }
+
+<span class="phrase">and <em class="replaceable"><code>partition_bound_spec</code></em> is:</span>
+
+IN ( <em class="replaceable"><code>partition_bound_expr</code></em> [, ...] ) |
+FROM ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] )
+ TO ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] ) |
+WITH ( MODULUS <em class="replaceable"><code>numeric_literal</code></em>, REMAINDER <em class="replaceable"><code>numeric_literal</code></em> )
+
+<span class="phrase">and <em class="replaceable"><code>column_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ NOT NULL |
+ NULL |
+ CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
+ DEFAULT <em class="replaceable"><code>default_expr</code></em> |
+ GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) STORED |
+ GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <em class="replaceable"><code>sequence_options</code></em> ) ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] <em class="replaceable"><code>index_parameters</code></em> |
+ PRIMARY KEY <em class="replaceable"><code>index_parameters</code></em> |
+ REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
+ [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ] [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ] }
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+
+<span class="phrase">and <em class="replaceable"><code>table_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> |
+ PRIMARY KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> |
+ EXCLUDE [ USING <em class="replaceable"><code>index_method</code></em> ] ( <em class="replaceable"><code>exclude_element</code></em> WITH <em class="replaceable"><code>operator</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> [ WHERE ( <em class="replaceable"><code>predicate</code></em> ) ] |
+ FOREIGN KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> [, ... ] ) ]
+ [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ] [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ] }
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+
+<span class="phrase">and <em class="replaceable"><code>table_constraint_using_index</code></em> is:</span>
+
+ [ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+ { UNIQUE | PRIMARY KEY } USING INDEX <em class="replaceable"><code>index_name</code></em>
+ [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+
+<span class="phrase"><em class="replaceable"><code>index_parameters</code></em> in <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>, and <code class="literal">EXCLUDE</code> constraints are:</span>
+
+[ INCLUDE ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ]
+[ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+[ USING INDEX TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+
+<span class="phrase"><em class="replaceable"><code>exclude_element</code></em> in an <code class="literal">EXCLUDE</code> constraint is:</span>
+
+{ <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ <em class="replaceable"><code>opclass</code></em> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
+
+<span class="phrase"><em class="replaceable"><code>referential_action</code></em> in a <code class="literal">FOREIGN KEY</code>/<code class="literal">REFERENCES</code> constraint is:</span>
+
+{ NO ACTION | RESTRICT | CASCADE | SET NULL [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] | SET DEFAULT [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] }
+</pre></div><div class="refsect1" id="id-1.9.3.35.5"><h2>Description</h2><p>
+ <code class="command">ALTER TABLE</code> changes the definition of an existing table.
+ There are several subforms described below. Note that the lock level required
+ may differ for each subform. An <code class="literal">ACCESS EXCLUSIVE</code> lock is
+ acquired unless explicitly noted. When multiple subcommands are given, the
+ lock acquired will be the strictest one required by any subcommand.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ADD COLUMN [ IF NOT EXISTS ]</code></span></dt><dd><p>
+ This form adds a new column to the table, using the same syntax as
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>. If <code class="literal">IF NOT EXISTS</code>
+ is specified and a column already exists with this name,
+ no error is thrown.
+ </p></dd><dt><span class="term"><code class="literal">DROP COLUMN [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops a column from a table. Indexes and
+ table constraints involving the column will be automatically
+ dropped as well.
+ Multivariate statistics referencing the dropped column will also be
+ removed if the removal of the column would cause the statistics to
+ contain data for only a single column.
+ You will need to say <code class="literal">CASCADE</code> if anything outside the table
+ depends on the column, for example, foreign key references or views.
+ If <code class="literal">IF EXISTS</code> is specified and the column
+ does not exist, no error is thrown. In this case a notice
+ is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">SET DATA TYPE</code></span></dt><dd><p>
+ This form changes the type of a column of a table. Indexes and
+ simple table constraints involving the column will be automatically
+ converted to use the new column type by reparsing the originally
+ supplied expression.
+ The optional <code class="literal">COLLATE</code> clause specifies a collation
+ for the new column; if omitted, the collation is the default for the
+ new column type.
+ The optional <code class="literal">USING</code>
+ clause specifies how to compute the new column value from the old;
+ if omitted, the default conversion is the same as an assignment
+ cast from old data type to new. A <code class="literal">USING</code>
+ clause must be provided if there is no implicit or assignment
+ cast from old to new type.
+ </p><p>
+ When this form is used, the column's statistics are removed,
+ so running <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
+ on the table afterwards is recommended.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP DEFAULT</code></span></dt><dd><p>
+ These forms set or remove the default value for a column (where
+ removal is equivalent to setting the default value to NULL). The new
+ default value will only apply in subsequent <code class="command">INSERT</code>
+ or <code class="command">UPDATE</code> commands; it does not cause rows already
+ in the table to change.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP NOT NULL</code></span></dt><dd><p>
+ These forms change whether a column is marked to allow null
+ values or to reject null values.
+ </p><p>
+ <code class="literal">SET NOT NULL</code> may only be applied to a column
+ provided none of the records in the table contain a
+ <code class="literal">NULL</code> value for the column. Ordinarily this is
+ checked during the <code class="literal">ALTER TABLE</code> by scanning the
+ entire table; however, if a valid <code class="literal">CHECK</code> constraint is
+ found which proves no <code class="literal">NULL</code> can exist, then the
+ table scan is skipped.
+ </p><p>
+ If this table is a partition, one cannot perform <code class="literal">DROP NOT NULL</code>
+ on a column if it is marked <code class="literal">NOT NULL</code> in the parent
+ table. To drop the <code class="literal">NOT NULL</code> constraint from all the
+ partitions, perform <code class="literal">DROP NOT NULL</code> on the parent
+ table. Even if there is no <code class="literal">NOT NULL</code> constraint on the
+ parent, such a constraint can still be added to individual partitions,
+ if desired; that is, the children can disallow nulls even if the parent
+ allows them, but not the other way around.
+ </p></dd><dt><span class="term"><code class="literal">DROP EXPRESSION [ IF EXISTS ]</code></span></dt><dd><p>
+ This form turns a stored generated column into a normal base column.
+ Existing data in the columns is retained, but future changes will no
+ longer apply the generation expression.
+ </p><p>
+ If <code class="literal">DROP EXPRESSION IF EXISTS</code> is specified and the
+ column is not a stored generated column, no error is thrown. In this
+ case a notice is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY</code><br /></span><span class="term"><code class="literal">SET GENERATED { ALWAYS | BY DEFAULT }</code><br /></span><span class="term"><code class="literal">DROP IDENTITY [ IF EXISTS ]</code></span></dt><dd><p>
+ These forms change whether a column is an identity column or change the
+ generation attribute of an existing identity column.
+ See <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> for details.
+ Like <code class="literal">SET DEFAULT</code>, these forms only affect the
+ behavior of subsequent <code class="command">INSERT</code>
+ and <code class="command">UPDATE</code> commands; they do not cause rows
+ already in the table to change.
+ </p><p>
+ If <code class="literal">DROP IDENTITY IF EXISTS</code> is specified and the
+ column is not an identity column, no error is thrown. In this case a
+ notice is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">SET <em class="replaceable"><code>sequence_option</code></em></code><br /></span><span class="term"><code class="literal">RESTART</code></span></dt><dd><p>
+ These forms alter the sequence that underlies an existing identity
+ column. <em class="replaceable"><code>sequence_option</code></em> is an option
+ supported by <a class="link" href="sql-altersequence.html" title="ALTER SEQUENCE"><code class="command">ALTER SEQUENCE</code></a> such
+ as <code class="literal">INCREMENT BY</code>.
+ </p></dd><dt><span class="term"><code class="literal">SET STATISTICS</code></span></dt><dd><p>
+ This form
+ sets the per-column statistics-gathering target for subsequent
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> operations.
+ The target can be set in the range 0 to 10000; alternatively, set it
+ to -1 to revert to using the system default statistics
+ target (<a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a>).
+ For more information on the use of statistics by the
+ <span class="productname">PostgreSQL</span> query planner, refer to
+ <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>.
+ </p><p>
+ <code class="literal">SET STATISTICS</code> acquires a
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )</code><br /></span><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )</code></span></dt><dd><p>
+ This form sets or resets per-attribute options. Currently, the only
+ defined per-attribute options are <code class="literal">n_distinct</code> and
+ <code class="literal">n_distinct_inherited</code>, which override the
+ number-of-distinct-values estimates made by subsequent
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
+ operations. <code class="literal">n_distinct</code> affects the statistics for the table
+ itself, while <code class="literal">n_distinct_inherited</code> affects the statistics
+ gathered for the table plus its inheritance children. When set to a
+ positive value, <code class="command">ANALYZE</code> will assume that the column contains
+ exactly the specified number of distinct nonnull values. When set to a
+ negative value, which must be greater
+ than or equal to -1, <code class="command">ANALYZE</code> will assume that the number of
+ distinct nonnull values in the column is linear in the size of the
+ table; the exact count is to be computed by multiplying the estimated
+ table size by the absolute value of the given number. For example,
+ a value of -1 implies that all values in the column are distinct, while
+ a value of -0.5 implies that each value appears twice on the average.
+ This can be useful when the size of the table changes over time, since
+ the multiplication by the number of rows in the table is not performed
+ until query planning time. Specify a value of 0 to revert to estimating
+ the number of distinct values normally. For more information on the use
+ of statistics by the <span class="productname">PostgreSQL</span> query
+ planner, refer to <a class="xref" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Section 14.2</a>.
+ </p><p>
+ Changing per-attribute options acquires a
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term">
+ <code class="literal">SET STORAGE</code>
+ <a id="id-1.9.3.35.5.2.3.11.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ This form sets the storage mode for a column. This controls whether this
+ column is held inline or in a secondary <acronym class="acronym">TOAST</acronym> table, and
+ whether the data
+ should be compressed or not. <code class="literal">PLAIN</code> must be used
+ for fixed-length values such as <code class="type">integer</code> and is
+ inline, uncompressed. <code class="literal">MAIN</code> is for inline,
+ compressible data. <code class="literal">EXTERNAL</code> is for external,
+ uncompressed data, and <code class="literal">EXTENDED</code> is for external,
+ compressed data. <code class="literal">EXTENDED</code> is the default for most
+ data types that support non-<code class="literal">PLAIN</code> storage.
+ Use of <code class="literal">EXTERNAL</code> will make substring operations on
+ very large <code class="type">text</code> and <code class="type">bytea</code> values run faster,
+ at the penalty of increased storage space. Note that
+ <code class="literal">SET STORAGE</code> doesn't itself change anything in the table,
+ it just sets the strategy to be pursued during future table updates.
+ See <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a> for more information.
+ </p></dd><dt><span class="term">
+ <code class="literal">SET COMPRESSION <em class="replaceable"><code>compression_method</code></em></code>
+ </span></dt><dd><p>
+ This form sets the compression method for a column, determining how
+ values inserted in future will be compressed (if the storage mode
+ permits compression at all).
+ This does not cause the table to be rewritten, so existing data may still
+ be compressed with other compression methods. If the table is restored
+ with <span class="application">pg_restore</span>, then all values are rewritten
+ with the configured compression method.
+ However, when data is inserted from another relation (for example,
+ by <code class="command">INSERT ... SELECT</code>), values from the source table are
+ not necessarily detoasted, so any previously compressed data may retain
+ its existing compression method, rather than being recompressed with the
+ compression method of the target column.
+ The supported compression
+ methods are <code class="literal">pglz</code> and <code class="literal">lz4</code>.
+ (<code class="literal">lz4</code> is available only if <code class="option">--with-lz4</code>
+ was used when building <span class="productname">PostgreSQL</span>.) In
+ addition, <em class="replaceable"><code>compression_method</code></em>
+ can be <code class="literal">default</code>, which selects the default behavior of
+ consulting the <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TOAST-COMPRESSION">default_toast_compression</a> setting
+ at the time of data insertion to determine the method to use.
+ </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]</code></span></dt><dd><p>
+ This form adds a new constraint to a table using the same constraint
+ syntax as <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>, plus the option <code class="literal">NOT
+ VALID</code>, which is currently only allowed for foreign key
+ and CHECK constraints.
+ </p><p>
+ Normally, this form will cause a scan of the table to verify that all
+ existing rows in the table satisfy the new constraint. But if
+ the <code class="literal">NOT VALID</code> option is used, this
+ potentially-lengthy scan is skipped. The constraint will still be
+ enforced against subsequent inserts or updates (that is, they'll fail
+ unless there is a matching row in the referenced table, in the case
+ of foreign keys, or they'll fail unless the new row matches the
+ specified check condition). But the
+ database will not assume that the constraint holds for all rows in
+ the table, until it is validated by using the <code class="literal">VALIDATE
+ CONSTRAINT</code> option.
+ See <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-NOTES" title="Notes">Notes</a> below for more information
+ about using the <code class="literal">NOT VALID</code> option.
+ </p><p>
+ Although most forms of <code class="literal">ADD
+ <em class="replaceable"><code>table_constraint</code></em></code>
+ require an <code class="literal">ACCESS EXCLUSIVE</code> lock, <code class="literal">ADD
+ FOREIGN KEY</code> requires only a <code class="literal">SHARE ROW
+ EXCLUSIVE</code> lock. Note that <code class="literal">ADD FOREIGN KEY</code>
+ also acquires a <code class="literal">SHARE ROW EXCLUSIVE</code> lock on the
+ referenced table, in addition to the lock on the table on which the
+ constraint is declared.
+ </p><p>
+ Additional restrictions apply when unique or primary key constraints
+ are added to partitioned tables; see <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>.
+ Also, foreign key constraints on partitioned
+ tables may not be declared <code class="literal">NOT VALID</code> at present.
+ </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>table_constraint_using_index</code></em></code></span></dt><dd><p>
+ This form adds a new <code class="literal">PRIMARY KEY</code> or <code class="literal">UNIQUE</code>
+ constraint to a table based on an existing unique index. All the
+ columns of the index will be included in the constraint.
+ </p><p>
+ The index cannot have expression columns nor be a partial index.
+ Also, it must be a b-tree index with default sort ordering. These
+ restrictions ensure that the index is equivalent to one that would be
+ built by a regular <code class="literal">ADD PRIMARY KEY</code> or <code class="literal">ADD UNIQUE</code>
+ command.
+ </p><p>
+ If <code class="literal">PRIMARY KEY</code> is specified, and the index's columns are not
+ already marked <code class="literal">NOT NULL</code>, then this command will attempt to
+ do <code class="literal">ALTER COLUMN SET NOT NULL</code> against each such column.
+ That requires a full table scan to verify the column(s) contain no
+ nulls. In all other cases, this is a fast operation.
+ </p><p>
+ If a constraint name is provided then the index will be renamed to match
+ the constraint name. Otherwise the constraint will be named the same as
+ the index.
+ </p><p>
+ After this command is executed, the index is <span class="quote">“<span class="quote">owned</span>”</span> by the
+ constraint, in the same way as if the index had been built by
+ a regular <code class="literal">ADD PRIMARY KEY</code> or <code class="literal">ADD UNIQUE</code>
+ command. In particular, dropping the constraint will make the index
+ disappear too.
+ </p><p>
+ This form is not currently supported on partitioned tables.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Adding a constraint using an existing index can be helpful in
+ situations where a new constraint needs to be added without blocking
+ table updates for a long time. To do that, create the index using
+ <code class="command">CREATE INDEX CONCURRENTLY</code>, and then install it as an
+ official constraint using this syntax. See the example below.
+ </p></div></dd><dt><span class="term"><code class="literal">ALTER CONSTRAINT</code></span></dt><dd><p>
+ This form alters the attributes of a constraint that was previously
+ created. Currently only foreign key constraints may be altered.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATE CONSTRAINT</code></span></dt><dd><p>
+ This form validates a foreign key or check constraint that was
+ previously created as <code class="literal">NOT VALID</code>, by scanning the
+ table to ensure there are no rows for which the constraint is not
+ satisfied. Nothing happens if the constraint is already marked valid.
+ (See <a class="xref" href="sql-altertable.html#SQL-ALTERTABLE-NOTES" title="Notes">Notes</a> below for an explanation
+ of the usefulness of this command.)
+ </p><p>
+ This command acquires a <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term"><code class="literal">DROP CONSTRAINT [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops the specified constraint on a table, along with
+ any index underlying the constraint.
+ If <code class="literal">IF EXISTS</code> is specified and the constraint
+ does not exist, no error is thrown. In this case a notice is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE [ REPLICA | ALWAYS ] TRIGGER</code></span></dt><dd><p>
+ These forms configure the firing of trigger(s) belonging to the table.
+ A disabled trigger is still known to the system, but is not executed
+ when its triggering event occurs. (For a deferred trigger, the enable
+ status is checked when the event occurs, not when the trigger function
+ is actually executed.) One can disable or enable a single
+ trigger specified by name, or all triggers on the table, or only
+ user triggers (this option excludes internally generated constraint
+ triggers, such as those that are used to implement foreign key
+ constraints or deferrable uniqueness and exclusion constraints).
+ Disabling or enabling internally generated constraint triggers
+ requires superuser privileges; it should be done with caution since
+ of course the integrity of the constraint cannot be guaranteed if the
+ triggers are not executed.
+ </p><p>
+ The trigger firing mechanism is also affected by the configuration
+ variable <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a>. Simply enabled
+ triggers (the default) will fire when the replication role is <span class="quote">“<span class="quote">origin</span>”</span>
+ (the default) or <span class="quote">“<span class="quote">local</span>”</span>. Triggers configured as <code class="literal">ENABLE
+ REPLICA</code> will only fire if the session is in <span class="quote">“<span class="quote">replica</span>”</span>
+ mode, and triggers configured as <code class="literal">ENABLE ALWAYS</code> will
+ fire regardless of the current replication role.
+ </p><p>
+ The effect of this mechanism is that in the default configuration,
+ triggers do not fire on replicas. This is useful because if a trigger
+ is used on the origin to propagate data between tables, then the
+ replication system will also replicate the propagated data; so the
+ trigger should not fire a second time on the replica, because that would
+ lead to duplication. However, if a trigger is used for another purpose
+ such as creating external alerts, then it might be appropriate to set it
+ to <code class="literal">ENABLE ALWAYS</code> so that it is also fired on
+ replicas.
+ </p><p>
+ When this command is applied to a partitioned table, the states of
+ corresponding clone triggers in the partitions are updated too,
+ unless <code class="literal">ONLY</code> is specified.
+ </p><p>
+ This command acquires a <code class="literal">SHARE ROW EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE [ REPLICA | ALWAYS ] RULE</code></span></dt><dd><p>
+ These forms configure the firing of rewrite rules belonging to the table.
+ A disabled rule is still known to the system, but is not applied
+ during query rewriting. The semantics are as for disabled/enabled
+ triggers. This configuration is ignored for <code class="literal">ON SELECT</code> rules, which
+ are always applied in order to keep views working even if the current
+ session is in a non-default replication role.
+ </p><p>
+ The rule firing mechanism is also affected by the configuration variable
+ <a class="xref" href="runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE">session_replication_role</a>, analogous to triggers as
+ described above.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE ROW LEVEL SECURITY</code></span></dt><dd><p>
+ These forms control the application of row security policies belonging
+ to the table. If enabled and no policies exist for the table, then a
+ default-deny policy is applied. Note that policies can exist for a table
+ even if row-level security is disabled. In this case, the policies will
+ <span class="emphasis"><em>not</em></span> be applied and the policies will be ignored.
+ See also
+ <a class="link" href="sql-createpolicy.html" title="CREATE POLICY"><code class="command">CREATE POLICY</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">NO FORCE</code>/<code class="literal">FORCE ROW LEVEL SECURITY</code></span></dt><dd><p>
+ These forms control the application of row security policies belonging
+ to the table when the user is the table owner. If enabled, row-level
+ security policies will be applied when the user is the table owner. If
+ disabled (the default) then row-level security will not be applied when
+ the user is the table owner.
+ See also
+ <a class="link" href="sql-createpolicy.html" title="CREATE POLICY"><code class="command">CREATE POLICY</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">CLUSTER ON</code></span></dt><dd><p>
+ This form selects the default index for future
+ <a class="link" href="sql-cluster.html" title="CLUSTER"><code class="command">CLUSTER</code></a>
+ operations. It does not actually re-cluster the table.
+ </p><p>
+ Changing cluster options acquires a <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term"><code class="literal">SET WITHOUT CLUSTER</code></span></dt><dd><p>
+ This form removes the most recently used
+ <a class="link" href="sql-cluster.html" title="CLUSTER"><code class="command">CLUSTER</code></a>
+ index specification from the table. This affects
+ future cluster operations that don't specify an index.
+ </p><p>
+ Changing cluster options acquires a <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock.
+ </p></dd><dt><span class="term"><code class="literal">SET WITHOUT OIDS</code></span></dt><dd><p>
+ Backward-compatible syntax for removing the <code class="literal">oid</code>
+ system column. As <code class="literal">oid</code> system columns cannot be
+ added anymore, this never has an effect.
+ </p></dd><dt><span class="term"><code class="literal">SET ACCESS METHOD</code></span></dt><dd><p>
+ This form changes the access method of the table by rewriting it. See
+ <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">SET TABLESPACE</code></span></dt><dd><p>
+ This form changes the table's tablespace to the specified tablespace and
+ moves the data file(s) associated with the table to the new tablespace.
+ Indexes on the table, if any, are not moved; but they can be moved
+ separately with additional <code class="literal">SET TABLESPACE</code> commands.
+ When applied to a partitioned table, nothing is moved, but any
+ partitions created afterwards with
+ <code class="command">CREATE TABLE PARTITION OF</code> will use that tablespace,
+ unless overridden by a <code class="literal">TABLESPACE</code> clause.
+ </p><p>
+ All tables in the current database in a tablespace can be moved by using
+ the <code class="literal">ALL IN TABLESPACE</code> form, which will lock all tables
+ to be moved first and then move each one. This form also supports
+ <code class="literal">OWNED BY</code>, which will only move tables owned by the
+ roles specified. If the <code class="literal">NOWAIT</code> option is specified
+ then the command will fail if it is unable to acquire all of the locks
+ required immediately. Note that system catalogs are not moved by this
+ command; use <code class="command">ALTER DATABASE</code> or explicit
+ <code class="command">ALTER TABLE</code> invocations instead if desired. The
+ <code class="literal">information_schema</code> relations are not considered part
+ of the system catalogs and will be moved.
+ See also
+ <a class="link" href="sql-createtablespace.html" title="CREATE TABLESPACE"><code class="command">CREATE TABLESPACE</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">SET { LOGGED | UNLOGGED }</code></span></dt><dd><p>
+ This form changes the table from unlogged to logged or vice-versa
+ (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-UNLOGGED"><code class="literal">UNLOGGED</code></a>). It cannot be applied
+ to a temporary table.
+ </p><p>
+ This also changes the persistence of any sequences linked to the table
+ (for identity or serial columns). However, it is also possible to
+ change the persistence of such sequences separately.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This form changes one or more storage parameters for the table. See
+ <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a> in the
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> documentation
+ for details on the available parameters. Note that the table contents
+ will not be modified immediately by this command; depending on the
+ parameter you might need to rewrite the table to get the desired effects.
+ That can be done with <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM
+ FULL</code></a>, <a class="link" href="sql-cluster.html" title="CLUSTER"><code class="command">CLUSTER</code></a> or one of the forms
+ of <code class="command">ALTER TABLE</code> that forces a table rewrite.
+ For planner related parameters, changes will take effect from the next
+ time the table is locked so currently executing queries will not be
+ affected.
+ </p><p>
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock will be taken for
+ fillfactor, toast and autovacuum storage parameters, as well as the
+ planner parameter <code class="varname">parallel_workers</code>.
+ </p></dd><dt><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>storage_parameter</code></em> [, ... ] )</code></span></dt><dd><p>
+ This form resets one or more storage parameters to their
+ defaults. As with <code class="literal">SET</code>, a table rewrite might be
+ needed to update the table entirely.
+ </p></dd><dt><span class="term"><code class="literal">INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
+ This form adds the target table as a new child of the specified parent
+ table. Subsequently, queries against the parent will include records
+ of the target table. To be added as a child, the target table must
+ already contain all the same columns as the parent (it could have
+ additional columns, too). The columns must have matching data types,
+ and if they have <code class="literal">NOT NULL</code> constraints in the parent
+ then they must also have <code class="literal">NOT NULL</code> constraints in the
+ child.
+ </p><p>
+ There must also be matching child-table constraints for all
+ <code class="literal">CHECK</code> constraints of the parent, except those
+ marked non-inheritable (that is, created with <code class="literal">ALTER TABLE ... ADD CONSTRAINT ... NO INHERIT</code>)
+ in the parent, which are ignored; all child-table constraints matched
+ must not be marked non-inheritable.
+ Currently
+ <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>, and
+ <code class="literal">FOREIGN KEY</code> constraints are not considered, but
+ this might change in the future.
+ </p></dd><dt><span class="term"><code class="literal">NO INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
+ This form removes the target table from the list of children of the
+ specified parent table.
+ Queries against the parent table will no longer include records drawn
+ from the target table.
+ </p></dd><dt><span class="term"><code class="literal">OF <em class="replaceable"><code>type_name</code></em></code></span></dt><dd><p>
+ This form links the table to a composite type as though <code class="command">CREATE
+ TABLE OF</code> had formed it. The table's list of column names and types
+ must precisely match that of the composite type. The table must
+ not inherit from any other table. These restrictions ensure
+ that <code class="command">CREATE TABLE OF</code> would permit an equivalent table
+ definition.
+ </p></dd><dt><span class="term"><code class="literal">NOT OF</code></span></dt><dd><p>
+ This form dissociates a typed table from its type.
+ </p></dd><dt><span class="term"><code class="literal">OWNER TO</code></span></dt><dd><p>
+ This form changes the owner of the table, sequence, view, materialized view,
+ or foreign table to the specified user.
+ </p></dd><dt id="SQL-ALTERTABLE-REPLICA-IDENTITY"><span class="term"><code class="literal">REPLICA IDENTITY</code></span></dt><dd><p>
+ This form changes the information which is written to the write-ahead log
+ to identify rows which are updated or deleted.
+ In most cases, the old value of each column is only logged if it differs
+ from the new value; however, if the old value is stored externally, it is
+ always logged regardless of whether it changed.
+ This option has no effect except when logical replication is in use.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ Records the old values of the columns of the primary key, if any.
+ This is the default for non-system tables.
+ </p></dd><dt><span class="term"><code class="literal">USING INDEX <em class="replaceable"><code>index_name</code></em></code></span></dt><dd><p>
+ Records the old values of the columns covered by the named index,
+ that must be unique, not partial, not deferrable, and include only
+ columns marked <code class="literal">NOT NULL</code>. If this index is
+ dropped, the behavior is the same as <code class="literal">NOTHING</code>.
+ </p></dd><dt><span class="term"><code class="literal">FULL</code></span></dt><dd><p>
+ Records the old values of all columns in the row.
+ </p></dd><dt><span class="term"><code class="literal">NOTHING</code></span></dt><dd><p>
+ Records no information about the old row. This is the default for
+ system tables.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
+ The <code class="literal">RENAME</code> forms change the name of a table
+ (or an index, sequence, view, materialized view, or foreign table), the
+ name of an individual column in a table, or the name of a constraint of
+ the table. When renaming a constraint that has an underlying index,
+ the index is renamed as well.
+ There is no effect on the stored data.
+ </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
+ This form moves the table into another schema. Associated indexes,
+ constraints, and sequences owned by table columns are moved as well.
+ </p></dd><dt id="SQL-ALTERTABLE-ATTACH-PARTITION"><span class="term"><code class="literal">ATTACH PARTITION <em class="replaceable"><code>partition_name</code></em> { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }</code></span></dt><dd><p>
+ This form attaches an existing table (which might itself be partitioned)
+ as a partition of the target table. The table can be attached
+ as a partition for specific values using <code class="literal">FOR VALUES</code>
+ or as a default partition by using <code class="literal">DEFAULT</code>.
+ For each index in the target table, a corresponding
+ one will be created in the attached table; or, if an equivalent
+ index already exists, it will be attached to the target table's index,
+ as if <code class="command">ALTER INDEX ATTACH PARTITION</code> had been executed.
+ Note that if the existing table is a foreign table, it is currently not
+ allowed to attach the table as a partition of the target table if there
+ are <code class="literal">UNIQUE</code> indexes on the target table. (See also
+ <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>.) For each user-defined
+ row-level trigger that exists in the target table, a corresponding one
+ is created in the attached table.
+ </p><p>
+ A partition using <code class="literal">FOR VALUES</code> uses same syntax for
+ <em class="replaceable"><code>partition_bound_spec</code></em> as
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>. The partition bound specification
+ must correspond to the partitioning strategy and partition key of the
+ target table. The table to be attached must have all the same columns
+ as the target table and no more; moreover, the column types must also
+ match. Also, it must have all the <code class="literal">NOT NULL</code> and
+ <code class="literal">CHECK</code> constraints of the target table. Currently
+ <code class="literal">FOREIGN KEY</code> constraints are not considered.
+ <code class="literal">UNIQUE</code> and <code class="literal">PRIMARY KEY</code> constraints
+ from the parent table will be created in the partition, if they don't
+ already exist.
+ If any of the <code class="literal">CHECK</code> constraints of the table being
+ attached are marked <code class="literal">NO INHERIT</code>, the command will fail;
+ such constraints must be recreated without the
+ <code class="literal">NO INHERIT</code> clause.
+ </p><p>
+ If the new partition is a regular table, a full table scan is performed
+ to check that existing rows in the table do not violate the partition
+ constraint. It is possible to avoid this scan by adding a valid
+ <code class="literal">CHECK</code> constraint to the table that allows only
+ rows satisfying the desired partition constraint before running this
+ command. The <code class="literal">CHECK</code> constraint will be used to
+ determine that the table need not be scanned to validate the partition
+ constraint. This does not work, however, if any of the partition keys
+ is an expression and the partition does not accept
+ <code class="literal">NULL</code> values. If attaching a list partition that will
+ not accept <code class="literal">NULL</code> values, also add a
+ <code class="literal">NOT NULL</code> constraint to the partition key column,
+ unless it's an expression.
+ </p><p>
+ If the new partition is a foreign table, nothing is done to verify
+ that all the rows in the foreign table obey the partition constraint.
+ (See the discussion in <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a> about
+ constraints on the foreign table.)
+ </p><p>
+ When a table has a default partition, defining a new partition changes
+ the partition constraint for the default partition. The default
+ partition can't contain any rows that would need to be moved to the new
+ partition, and will be scanned to verify that none are present. This
+ scan, like the scan of the new partition, can be avoided if an
+ appropriate <code class="literal">CHECK</code> constraint is present. Also like
+ the scan of the new partition, it is always skipped when the default
+ partition is a foreign table.
+ </p><p>
+ Attaching a partition acquires a
+ <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock on the parent table,
+ in addition to the <code class="literal">ACCESS EXCLUSIVE</code> locks on the table
+ being attached and on the default partition (if any).
+ </p><p>
+ Further locks must also be held on all sub-partitions if the table being
+ attached is itself a partitioned table. Likewise if the default
+ partition is itself a partitioned table. The locking of the
+ sub-partitions can be avoided by adding a <code class="literal">CHECK</code>
+ constraint as described in
+ <a class="xref" href="ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE-MAINTENANCE" title="5.11.2.2. Partition Maintenance">Section 5.11.2.2</a>.
+ </p></dd><dt id="SQL-ALTERTABLE-DETACH-PARTITION"><span class="term"><code class="literal">DETACH PARTITION <em class="replaceable"><code>partition_name</code></em> [ CONCURRENTLY | FINALIZE ]</code></span></dt><dd><p>
+ This form detaches the specified partition of the target table. The detached
+ partition continues to exist as a standalone table, but no longer has any
+ ties to the table from which it was detached. Any indexes that were
+ attached to the target table's indexes are detached. Any triggers that
+ were created as clones of those in the target table are removed.
+ <code class="literal">SHARE</code> lock is obtained on any tables that reference
+ this partitioned table in foreign key constraints.
+ </p><p>
+ If <code class="literal">CONCURRENTLY</code> is specified, it runs using a reduced
+ lock level to avoid blocking other sessions that might be accessing the
+ partitioned table. In this mode, two transactions are used internally.
+ During the first transaction, a <code class="literal">SHARE UPDATE EXCLUSIVE</code>
+ lock is taken on both parent table and partition, and the partition is
+ marked as undergoing detach; at that point, the transaction is committed
+ and all other transactions using the partitioned table are waited for.
+ Once all those transactions have completed, the second transaction
+ acquires <code class="literal">SHARE UPDATE EXCLUSIVE</code> on the partitioned
+ table and <code class="literal">ACCESS EXCLUSIVE</code> on the partition,
+ and the detach process completes. A <code class="literal">CHECK</code> constraint
+ that duplicates the partition constraint is added to the partition.
+ <code class="literal">CONCURRENTLY</code> cannot be run in a transaction block and
+ is not allowed if the partitioned table contains a default partition.
+ </p><p>
+ If <code class="literal">FINALIZE</code> is specified, a previous
+ <code class="literal">DETACH CONCURRENTLY</code> invocation that was canceled or
+ interrupted is completed.
+ At most one partition in a partitioned table can be pending detach at
+ a time.
+ </p></dd></dl></div><p>
+ </p><p>
+ All the forms of ALTER TABLE that act on a single table, except
+ <code class="literal">RENAME</code>, <code class="literal">SET SCHEMA</code>,
+ <code class="literal">ATTACH PARTITION</code>, and
+ <code class="literal">DETACH PARTITION</code> can be combined into
+ a list of multiple alterations to be applied together. For example, it
+ is possible to add several columns and/or alter the type of several
+ columns in a single command. This is particularly useful with large
+ tables, since only one pass over the table need be made.
+ </p><p>
+ You must own the table to use <code class="command">ALTER TABLE</code>.
+ To change the schema or tablespace of a table, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema or tablespace.
+ To add the table as a new child of a parent table, you must own the parent
+ table as well. Also, to attach a table as a new partition of the table,
+ you must own the table being attached.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the table's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the table.
+ However, a superuser can alter ownership of any table anyway.)
+ To add a column or alter a column type or use the <code class="literal">OF</code>
+ clause, you must also have <code class="literal">USAGE</code> privilege on the data
+ type.
+ </p></div><div class="refsect1" id="id-1.9.3.35.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the table does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing table to
+ alter. If <code class="literal">ONLY</code> is specified before the table name, only
+ that table is altered. If <code class="literal">ONLY</code> is not specified, the table
+ and all its descendant tables (if any) are altered. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ Name of a new or existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_column_name</code></em></span></dt><dd><p>
+ New name for an existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ New name for the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ Data type of the new column, or new data type for an existing
+ column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_constraint</code></em></span></dt><dd><p>
+ New table constraint for the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>
+ Name of a new or existing constraint.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the dropped column
+ or constraint (for example, views referencing the column),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the column or constraint if there are any dependent
+ objects. This is the default behavior.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>trigger_name</code></em></span></dt><dd><p>
+ Name of a single trigger to disable or enable.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Disable or enable all triggers belonging to the table.
+ (This requires superuser privilege if any of the triggers are
+ internally generated constraint triggers, such as those that are used
+ to implement foreign key constraints or deferrable uniqueness and
+ exclusion constraints.)
+ </p></dd><dt><span class="term"><code class="literal">USER</code></span></dt><dd><p>
+ Disable or enable all triggers belonging to the table except for
+ internally generated constraint triggers, such as those that are used
+ to implement foreign key constraints or deferrable uniqueness and
+ exclusion constraints.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_name</code></em></span></dt><dd><p>
+ The name of an existing index.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>storage_parameter</code></em></span></dt><dd><p>
+ The name of a table storage parameter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The new value for a table storage parameter.
+ This might be a number or a word depending on the parameter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>parent_table</code></em></span></dt><dd><p>
+ A parent table to associate or de-associate with this table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_access_method</code></em></span></dt><dd><p>
+ The name of the access method to which the table will be converted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_tablespace</code></em></span></dt><dd><p>
+ The name of the tablespace to which the table will be moved.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The name of the schema to which the table will be moved.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>partition_name</code></em></span></dt><dd><p>
+ The name of the table to attach as a new partition or to detach from this table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>partition_bound_spec</code></em></span></dt><dd><p>
+ The partition bound specification for a new partition. Refer to
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for more details on the syntax of the same.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-ALTERTABLE-NOTES"><h2>Notes</h2><p>
+ The key word <code class="literal">COLUMN</code> is noise and can be omitted.
+ </p><p>
+ When a column is added with <code class="literal">ADD COLUMN</code> and a
+ non-volatile <code class="literal">DEFAULT</code> is specified, the default is
+ evaluated at the time of the statement and the result stored in the
+ table's metadata. That value will be used for the column for all existing
+ rows. If no <code class="literal">DEFAULT</code> is specified, NULL is used. In
+ neither case is a rewrite of the table required.
+ </p><p>
+ Adding a column with a volatile <code class="literal">DEFAULT</code> or
+ changing the type of an existing column will require the entire table and
+ its indexes to be rewritten. As an exception, when changing the type of an
+ existing column, if the <code class="literal">USING</code> clause does not change
+ the column contents and the old type is either binary coercible to the new
+ type or an unconstrained domain over the new type, a table rewrite is not
+ needed. However, indexes must always be rebuilt unless the system can
+ verify that the new index would be logically equivalent to the existing
+ one. For example, if the collation for a column has been changed, an index
+ rebuild is always required because the new sort order might be different.
+ However, in the absence of a collation change, a column can be changed
+ from <code class="type">text</code> to <code class="type">varchar</code> (or vice versa) without
+ rebuilding the indexes because these data types sort identically.
+ Table and/or index rebuilds may take a
+ significant amount of time for a large table; and will temporarily require
+ as much as double the disk space.
+ </p><p>
+ Adding a <code class="literal">CHECK</code> or <code class="literal">NOT NULL</code> constraint requires
+ scanning the table to verify that existing rows meet the constraint,
+ but does not require a table rewrite.
+ </p><p>
+ Similarly, when attaching a new partition it may be scanned to verify that
+ existing rows meet the partition constraint.
+ </p><p>
+ The main reason for providing the option to specify multiple changes
+ in a single <code class="command">ALTER TABLE</code> is that multiple table scans or
+ rewrites can thereby be combined into a single pass over the table.
+ </p><p>
+ Scanning a large table to verify a new foreign key or check constraint
+ can take a long time, and other updates to the table are locked out
+ until the <code class="command">ALTER TABLE ADD CONSTRAINT</code> command is
+ committed. The main purpose of the <code class="literal">NOT VALID</code>
+ constraint option is to reduce the impact of adding a constraint on
+ concurrent updates. With <code class="literal">NOT VALID</code>,
+ the <code class="command">ADD CONSTRAINT</code> command does not scan the table
+ and can be committed immediately. After that, a <code class="literal">VALIDATE
+ CONSTRAINT</code> command can be issued to verify that existing rows
+ satisfy the constraint. The validation step does not need to lock out
+ concurrent updates, since it knows that other transactions will be
+ enforcing the constraint for rows that they insert or update; only
+ pre-existing rows need to be checked. Hence, validation acquires only
+ a <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock on the table being
+ altered. (If the constraint is a foreign key then a <code class="literal">ROW
+ SHARE</code> lock is also required on the table referenced by the
+ constraint.) In addition to improving concurrency, it can be useful to
+ use <code class="literal">NOT VALID</code> and <code class="literal">VALIDATE
+ CONSTRAINT</code> in cases where the table is known to contain
+ pre-existing violations. Once the constraint is in place, no new
+ violations can be inserted, and the existing problems can be corrected
+ at leisure until <code class="literal">VALIDATE CONSTRAINT</code> finally
+ succeeds.
+ </p><p>
+ The <code class="literal">DROP COLUMN</code> form does not physically remove
+ the column, but simply makes it invisible to SQL operations. Subsequent
+ insert and update operations in the table will store a null value for the
+ column. Thus, dropping a column is quick but it will not immediately
+ reduce the on-disk size of your table, as the space occupied
+ by the dropped column is not reclaimed. The space will be
+ reclaimed over time as existing rows are updated.
+ </p><p>
+ To force immediate reclamation of space occupied by a dropped column,
+ you can execute one of the forms of <code class="command">ALTER TABLE</code> that
+ performs a rewrite of the whole table. This results in reconstructing
+ each row with the dropped column replaced by a null value.
+ </p><p>
+ The rewriting forms of <code class="command">ALTER TABLE</code> are not MVCC-safe.
+ After a table rewrite, the table will appear empty to concurrent
+ transactions, if they are using a snapshot taken before the rewrite
+ occurred. See <a class="xref" href="mvcc-caveats.html" title="13.6. Caveats">Section 13.6</a> for more details.
+ </p><p>
+ The <code class="literal">USING</code> option of <code class="literal">SET DATA TYPE</code> can actually
+ specify any expression involving the old values of the row; that is, it
+ can refer to other columns as well as the one being converted. This allows
+ very general conversions to be done with the <code class="literal">SET DATA TYPE</code>
+ syntax. Because of this flexibility, the <code class="literal">USING</code>
+ expression is not applied to the column's default value (if any); the
+ result might not be a constant expression as required for a default.
+ This means that when there is no implicit or assignment cast from old to
+ new type, <code class="literal">SET DATA TYPE</code> might fail to convert the default even
+ though a <code class="literal">USING</code> clause is supplied. In such cases,
+ drop the default with <code class="literal">DROP DEFAULT</code>, perform the <code class="literal">ALTER
+ TYPE</code>, and then use <code class="literal">SET DEFAULT</code> to add a suitable new
+ default. Similar considerations apply to indexes and constraints involving
+ the column.
+ </p><p>
+ If a table has any descendant tables, it is not permitted to add,
+ rename, or change the type of a column in the parent table without doing
+ the same to the descendants. This ensures that the descendants always
+ have columns matching the parent. Similarly, a <code class="literal">CHECK</code>
+ constraint cannot be renamed in the parent without also renaming it in
+ all descendants, so that <code class="literal">CHECK</code> constraints also match
+ between the parent and its descendants. (That restriction does not apply
+ to index-based constraints, however.)
+ Also, because selecting from the parent also selects from its descendants,
+ a constraint on the parent cannot be marked valid unless it is also marked
+ valid for those descendants. In all of these cases, <code class="command">ALTER TABLE
+ ONLY</code> will be rejected.
+ </p><p>
+ A recursive <code class="literal">DROP COLUMN</code> operation will remove a
+ descendant table's column only if the descendant does not inherit
+ that column from any other parents and never had an independent
+ definition of the column. A nonrecursive <code class="literal">DROP
+ COLUMN</code> (i.e., <code class="command">ALTER TABLE ONLY ... DROP
+ COLUMN</code>) never removes any descendant columns, but
+ instead marks them as independently defined rather than inherited.
+ A nonrecursive <code class="literal">DROP COLUMN</code> command will fail for a
+ partitioned table, because all partitions of a table must have the same
+ columns as the partitioning root.
+ </p><p>
+ The actions for identity columns (<code class="literal">ADD
+ GENERATED</code>, <code class="literal">SET</code> etc., <code class="literal">DROP
+ IDENTITY</code>), as well as the actions
+ <code class="literal">CLUSTER</code>, <code class="literal">OWNER</code>,
+ and <code class="literal">TABLESPACE</code> never recurse to descendant tables;
+ that is, they always act as though <code class="literal">ONLY</code> were specified.
+ Actions affecting trigger states recurse to partitions of partitioned
+ tables (unless <code class="literal">ONLY</code> is specified), but never to
+ traditional-inheritance descendants.
+ Adding a constraint recurses only for <code class="literal">CHECK</code> constraints
+ that are not marked <code class="literal">NO INHERIT</code>.
+ </p><p>
+ Changing any part of a system catalog table is not permitted.
+ </p><p>
+ Refer to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for a further description of valid
+ parameters. <a class="xref" href="ddl.html" title="Chapter 5. Data Definition">Chapter 5</a> has further information on
+ inheritance.
+ </p></div><div class="refsect1" id="id-1.9.3.35.8"><h2>Examples</h2><p>
+ To add a column of type <code class="type">varchar</code> to a table:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD COLUMN address varchar(30);
+</pre><p>
+ That will cause all existing rows in the table to be filled with null
+ values for the new column.
+ </p><p>
+ To add a column with a non-null default:
+</p><pre class="programlisting">
+ALTER TABLE measurements
+ ADD COLUMN mtime timestamp with time zone DEFAULT now();
+</pre><p>
+ Existing rows will be filled with the current time as the value of the
+ new column, and then new rows will receive the time of their insertion.
+ </p><p>
+ To add a column and fill it with a value different from the default to
+ be used later:
+</p><pre class="programlisting">
+ALTER TABLE transactions
+ ADD COLUMN status varchar(30) DEFAULT 'old',
+ ALTER COLUMN status SET default 'current';
+</pre><p>
+ Existing rows will be filled with <code class="literal">old</code>, but then
+ the default for subsequent commands will be <code class="literal">current</code>.
+ The effects are the same as if the two sub-commands had been issued
+ in separate <code class="command">ALTER TABLE</code> commands.
+ </p><p>
+ To drop a column from a table:
+</p><pre class="programlisting">
+ALTER TABLE distributors DROP COLUMN address RESTRICT;
+</pre><p>
+ </p><p>
+ To change the types of two existing columns in one operation:
+</p><pre class="programlisting">
+ALTER TABLE distributors
+ ALTER COLUMN address TYPE varchar(80),
+ ALTER COLUMN name TYPE varchar(100);
+</pre><p>
+ </p><p>
+ To change an integer column containing Unix timestamps to <code class="type">timestamp
+ with time zone</code> via a <code class="literal">USING</code> clause:
+</p><pre class="programlisting">
+ALTER TABLE foo
+ ALTER COLUMN foo_timestamp SET DATA TYPE timestamp with time zone
+ USING
+ timestamp with time zone 'epoch' + foo_timestamp * interval '1 second';
+</pre><p>
+ </p><p>
+ The same, when the column has a default expression that won't automatically
+ cast to the new data type:
+</p><pre class="programlisting">
+ALTER TABLE foo
+ ALTER COLUMN foo_timestamp DROP DEFAULT,
+ ALTER COLUMN foo_timestamp TYPE timestamp with time zone
+ USING
+ timestamp with time zone 'epoch' + foo_timestamp * interval '1 second',
+ ALTER COLUMN foo_timestamp SET DEFAULT now();
+</pre><p>
+ </p><p>
+ To rename an existing column:
+</p><pre class="programlisting">
+ALTER TABLE distributors RENAME COLUMN address TO city;
+</pre><p>
+ </p><p>
+ To rename an existing table:
+</p><pre class="programlisting">
+ALTER TABLE distributors RENAME TO suppliers;
+</pre><p>
+ </p><p>
+ To rename an existing constraint:
+</p><pre class="programlisting">
+ALTER TABLE distributors RENAME CONSTRAINT zipchk TO zip_check;
+</pre><p>
+ </p><p>
+ To add a not-null constraint to a column:
+</p><pre class="programlisting">
+ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
+</pre><p>
+ To remove a not-null constraint from a column:
+</p><pre class="programlisting">
+ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
+</pre><p>
+ </p><p>
+ To add a check constraint to a table and all its children:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
+</pre><p>
+ </p><p>
+ To add a check constraint only to a table and not to its children:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5) NO INHERIT;
+</pre><p>
+ (The check constraint will not be inherited by future children, either.)
+ </p><p>
+ To remove a check constraint from a table and all its children:
+</p><pre class="programlisting">
+ALTER TABLE distributors DROP CONSTRAINT zipchk;
+</pre><p>
+ </p><p>
+ To remove a check constraint from one table only:
+</p><pre class="programlisting">
+ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
+</pre><p>
+ (The check constraint remains in place for any child tables.)
+ </p><p>
+ To add a foreign key constraint to a table:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address);
+</pre><p>
+ </p><p>
+ To add a foreign key constraint to a table with the least impact on other work:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) NOT VALID;
+ALTER TABLE distributors VALIDATE CONSTRAINT distfk;
+</pre><p>
+ </p><p>
+ To add a (multicolumn) unique constraint to a table:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
+</pre><p>
+ </p><p>
+ To add an automatically named primary key constraint to a table, noting
+ that a table can only ever have one primary key:
+</p><pre class="programlisting">
+ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
+</pre><p>
+ </p><p>
+ To move a table to a different tablespace:
+</p><pre class="programlisting">
+ALTER TABLE distributors SET TABLESPACE fasttablespace;
+</pre><p>
+ </p><p>
+ To move a table to a different schema:
+</p><pre class="programlisting">
+ALTER TABLE myschema.distributors SET SCHEMA yourschema;
+</pre><p>
+ </p><p>
+ To recreate a primary key constraint, without blocking updates while the
+ index is rebuilt:
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX CONCURRENTLY dist_id_temp_idx ON distributors (dist_id);
+ALTER TABLE distributors DROP CONSTRAINT distributors_pkey,
+ ADD CONSTRAINT distributors_pkey PRIMARY KEY USING INDEX dist_id_temp_idx;
+</pre><p>
+ To attach a partition to a range-partitioned table:
+</p><pre class="programlisting">
+ALTER TABLE measurement
+ ATTACH PARTITION measurement_y2016m07 FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
+</pre><p>
+ To attach a partition to a list-partitioned table:
+</p><pre class="programlisting">
+ALTER TABLE cities
+ ATTACH PARTITION cities_ab FOR VALUES IN ('a', 'b');
+</pre><p>
+ To attach a partition to a hash-partitioned table:
+</p><pre class="programlisting">
+ALTER TABLE orders
+ ATTACH PARTITION orders_p4 FOR VALUES WITH (MODULUS 4, REMAINDER 3);
+</pre><p>
+ To attach a default partition to a partitioned table:
+</p><pre class="programlisting">
+ALTER TABLE cities
+ ATTACH PARTITION cities_partdef DEFAULT;
+</pre><p>
+ To detach a partition from a partitioned table:
+</p><pre class="programlisting">
+ALTER TABLE measurement
+ DETACH PARTITION measurement_y2015m12;
+</pre></div><div class="refsect1" id="id-1.9.3.35.9"><h2>Compatibility</h2><p>
+ The forms <code class="literal">ADD</code> (without <code class="literal">USING INDEX</code>),
+ <code class="literal">DROP [COLUMN]</code>, <code class="literal">DROP IDENTITY</code>, <code class="literal">RESTART</code>,
+ <code class="literal">SET DEFAULT</code>, <code class="literal">SET DATA TYPE</code> (without <code class="literal">USING</code>),
+ <code class="literal">SET GENERATED</code>, and <code class="literal">SET <em class="replaceable"><code>sequence_option</code></em></code>
+ conform with the SQL standard. The other forms are
+ <span class="productname">PostgreSQL</span> extensions of the SQL standard.
+ Also, the ability to specify more than one manipulation in a single
+ <code class="command">ALTER TABLE</code> command is an extension.
+ </p><p>
+ <code class="command">ALTER TABLE DROP COLUMN</code> can be used to drop the only
+ column of a table, leaving a zero-column table. This is an
+ extension of SQL, which disallows zero-column tables.
+ </p></div><div class="refsect1" id="id-1.9.3.35.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altersystem.html" title="ALTER SYSTEM">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertablespace.html" title="ALTER TABLESPACE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER SYSTEM </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TABLESPACE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertablespace.html b/doc/src/sgml/html/sql-altertablespace.html
new file mode 100644
index 0000000..08ba942
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertablespace.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TABLESPACE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertable.html" title="ALTER TABLE" /><link rel="next" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TABLESPACE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertable.html" title="ALTER TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTABLESPACE"><div class="titlepage"></div><a id="id-1.9.3.36.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TABLESPACE</span></h2><p>ALTER TABLESPACE — change the definition of a tablespace</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TABLESPACE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TABLESPACE <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER TABLESPACE <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>tablespace_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
+ALTER TABLESPACE <em class="replaceable"><code>name</code></em> RESET ( <em class="replaceable"><code>tablespace_option</code></em> [, ... ] )
+</pre></div><div class="refsect1" id="id-1.9.3.36.5"><h2>Description</h2><p>
+ <code class="command">ALTER TABLESPACE</code> can be used to change the definition of
+ a tablespace.
+ </p><p>
+ You must own the tablespace to change the definition of a tablespace.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role.
+ (Note that superusers have these privileges automatically.)
+ </p></div><div class="refsect1" id="id-1.9.3.36.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing tablespace.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the tablespace. The new name cannot
+ begin with <code class="literal">pg_</code>, as such names
+ are reserved for system tablespaces.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the tablespace.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>tablespace_option</code></em></span></dt><dd><p>
+ A tablespace parameter to be set or reset. Currently, the only
+ available parameters are <code class="varname">seq_page_cost</code>,
+ <code class="varname">random_page_cost</code>, <code class="varname">effective_io_concurrency</code>
+ and <code class="varname">maintenance_io_concurrency</code>.
+ Setting these values for a particular tablespace will override the
+ planner's usual estimate of the cost of reading pages from tables in
+ that tablespace, and the executor's prefetching behavior, as established
+ by the configuration parameters of the
+ same name (see <a class="xref" href="runtime-config-query.html#GUC-SEQ-PAGE-COST">seq_page_cost</a>,
+ <a class="xref" href="runtime-config-query.html#GUC-RANDOM-PAGE-COST">random_page_cost</a>,
+ <a class="xref" href="runtime-config-resource.html#GUC-EFFECTIVE-IO-CONCURRENCY">effective_io_concurrency</a>,
+ <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY">maintenance_io_concurrency</a>). This may be useful if
+ one tablespace is located on a disk which is faster or slower than the
+ remainder of the I/O subsystem.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.36.7"><h2>Examples</h2><p>
+ Rename tablespace <code class="literal">index_space</code> to <code class="literal">fast_raid</code>:
+</p><pre class="programlisting">
+ALTER TABLESPACE index_space RENAME TO fast_raid;
+</pre><p>
+ </p><p>
+ Change the owner of tablespace <code class="literal">index_space</code>:
+</p><pre class="programlisting">
+ALTER TABLESPACE index_space OWNER TO mary;
+</pre></div><div class="refsect1" id="id-1.9.3.36.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER TABLESPACE</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.36.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>, <a class="xref" href="sql-droptablespace.html" title="DROP TABLESPACE"><span class="refentrytitle">DROP TABLESPACE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertable.html" title="ALTER TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TEXT SEARCH CONFIGURATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertrigger.html b/doc/src/sgml/html/sql-altertrigger.html
new file mode 100644
index 0000000..51e2836
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertrigger.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE" /><link rel="next" href="sql-altertype.html" title="ALTER TYPE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertype.html" title="ALTER TYPE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTRIGGER"><div class="titlepage"></div><a id="id-1.9.3.41.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TRIGGER</span></h2><p>ALTER TRIGGER — change the definition of a trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TRIGGER <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TRIGGER <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> [ NO ] DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.41.5"><h2>Description</h2><p>
+ <code class="command">ALTER TRIGGER</code> changes properties of an existing
+ trigger.
+ </p><p>
+ The <code class="literal">RENAME</code> clause changes the name of
+ the given trigger without otherwise changing the trigger
+ definition.
+ If the table that the trigger is on is a partitioned table,
+ then corresponding clone triggers in the partitions are
+ renamed too.
+ </p><p>
+ The <code class="literal">DEPENDS ON EXTENSION</code> clause marks
+ the trigger as dependent on an extension, such that if the extension is
+ dropped, the trigger will automatically be dropped as well.
+ </p><p>
+ You must own the table on which the trigger acts to be allowed to change its properties.
+ </p></div><div class="refsect1" id="id-1.9.3.41.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing trigger to alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name of the table on which this trigger acts.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the trigger.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p>
+ The name of the extension that the trigger is to depend on (or no longer
+ dependent on, if <code class="literal">NO</code> is specified). A trigger
+ that's marked as dependent on an extension is automatically dropped when
+ the extension is dropped.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.41.7"><h2>Notes</h2><p>
+ The ability to temporarily enable or disable a trigger is provided by
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>, not by
+ <code class="command">ALTER TRIGGER</code>, because <code class="command">ALTER TRIGGER</code> has no
+ convenient way to express the option of enabling or disabling all of
+ a table's triggers at once.
+ </p></div><div class="refsect1" id="id-1.9.3.41.8"><h2>Examples</h2><p>
+ To rename an existing trigger:
+</p><pre class="programlisting">
+ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;
+</pre><p>
+ To mark a trigger as being dependent on an extension:
+</p><pre class="programlisting">
+ALTER TRIGGER emp_stamp ON emp DEPENDS ON EXTENSION emplib;
+</pre></div><div class="refsect1" id="id-1.9.3.41.9"><h2>Compatibility</h2><p>
+ <code class="command">ALTER TRIGGER</code> is a <span class="productname">PostgreSQL</span>
+ extension of the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.41.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertype.html" title="ALTER TYPE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TEXT SEARCH TEMPLATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TYPE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertsconfig.html b/doc/src/sgml/html/sql-altertsconfig.html
new file mode 100644
index 0000000..52a7a04
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertsconfig.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TEXT SEARCH CONFIGURATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertablespace.html" title="ALTER TABLESPACE" /><link rel="next" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TEXT SEARCH CONFIGURATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertablespace.html" title="ALTER TABLESPACE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTSCONFIG"><div class="titlepage"></div><a id="id-1.9.3.37.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TEXT SEARCH CONFIGURATION</span></h2><p>ALTER TEXT SEARCH CONFIGURATION — change the definition of a text search configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em>
+ ADD MAPPING FOR <em class="replaceable"><code>token_type</code></em> [, ... ] WITH <em class="replaceable"><code>dictionary_name</code></em> [, ... ]
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em>
+ ALTER MAPPING FOR <em class="replaceable"><code>token_type</code></em> [, ... ] WITH <em class="replaceable"><code>dictionary_name</code></em> [, ... ]
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em>
+ ALTER MAPPING REPLACE <em class="replaceable"><code>old_dictionary</code></em> WITH <em class="replaceable"><code>new_dictionary</code></em>
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em>
+ ALTER MAPPING FOR <em class="replaceable"><code>token_type</code></em> [, ... ] REPLACE <em class="replaceable"><code>old_dictionary</code></em> WITH <em class="replaceable"><code>new_dictionary</code></em>
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em>
+ DROP MAPPING [ IF EXISTS ] FOR <em class="replaceable"><code>token_type</code></em> [, ... ]
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.37.5"><h2>Description</h2><p>
+ <code class="command">ALTER TEXT SEARCH CONFIGURATION</code> changes the definition of
+ a text search configuration. You can modify
+ its mappings from token types to dictionaries,
+ or change the configuration's name or owner.
+ </p><p>
+ You must be the owner of the configuration to use
+ <code class="command">ALTER TEXT SEARCH CONFIGURATION</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.37.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search
+ configuration.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>token_type</code></em></span></dt><dd><p>
+ The name of a token type that is emitted by the configuration's
+ parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>dictionary_name</code></em></span></dt><dd><p>
+ The name of a text search dictionary to be consulted for the
+ specified token type(s). If multiple dictionaries are listed,
+ they are consulted in the specified order.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>old_dictionary</code></em></span></dt><dd><p>
+ The name of a text search dictionary to be replaced in the mapping.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_dictionary</code></em></span></dt><dd><p>
+ The name of a text search dictionary to be substituted for
+ <em class="replaceable"><code>old_dictionary</code></em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the text search configuration.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the text search configuration.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the text search configuration.
+ </p></dd></dl></div><p>
+ The <code class="literal">ADD MAPPING FOR</code> form installs a list of dictionaries to be
+ consulted for the specified token type(s); it is an error if there is
+ already a mapping for any of the token types.
+ The <code class="literal">ALTER MAPPING FOR</code> form does the same, but first removing
+ any existing mapping for those token types.
+ The <code class="literal">ALTER MAPPING REPLACE</code> forms substitute <em class="replaceable"><code>new_dictionary</code></em> for <em class="replaceable"><code>old_dictionary</code></em> anywhere the latter appears.
+ This is done for only the specified token types when <code class="literal">FOR</code>
+ appears, or for all mappings of the configuration when it doesn't.
+ The <code class="literal">DROP MAPPING</code> form removes all dictionaries for the
+ specified token type(s), causing tokens of those types to be ignored
+ by the text search configuration. It is an error if there is no mapping
+ for the token types, unless <code class="literal">IF EXISTS</code> appears.
+ </p></div><div class="refsect1" id="id-1.9.3.37.7"><h2>Examples</h2><p>
+ The following example replaces the <code class="literal">english</code> dictionary
+ with the <code class="literal">swedish</code> dictionary anywhere that <code class="literal">english</code>
+ is used within <code class="literal">my_config</code>.
+ </p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION my_config
+ ALTER MAPPING REPLACE english WITH swedish;
+</pre></div><div class="refsect1" id="id-1.9.3.37.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER TEXT SEARCH CONFIGURATION</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.37.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION"><span class="refentrytitle">CREATE TEXT SEARCH CONFIGURATION</span></a>, <a class="xref" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION"><span class="refentrytitle">DROP TEXT SEARCH CONFIGURATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertablespace.html" title="ALTER TABLESPACE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TABLESPACE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TEXT SEARCH DICTIONARY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertsdictionary.html b/doc/src/sgml/html/sql-altertsdictionary.html
new file mode 100644
index 0000000..70dc36b
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertsdictionary.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TEXT SEARCH DICTIONARY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION" /><link rel="next" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TEXT SEARCH DICTIONARY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTSDICTIONARY"><div class="titlepage"></div><a id="id-1.9.3.38.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TEXT SEARCH DICTIONARY</span></h2><p>ALTER TEXT SEARCH DICTIONARY — change the definition of a text search dictionary</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TEXT SEARCH DICTIONARY <em class="replaceable"><code>name</code></em> (
+ <em class="replaceable"><code>option</code></em> [ = <em class="replaceable"><code>value</code></em> ] [, ... ]
+)
+ALTER TEXT SEARCH DICTIONARY <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TEXT SEARCH DICTIONARY <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER TEXT SEARCH DICTIONARY <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.38.5"><h2>Description</h2><p>
+ <code class="command">ALTER TEXT SEARCH DICTIONARY</code> changes the definition of
+ a text search dictionary. You can change the dictionary's
+ template-specific options, or change the dictionary's name or owner.
+ </p><p>
+ You must be the owner of the dictionary to use
+ <code class="command">ALTER TEXT SEARCH DICTIONARY</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.38.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search
+ dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>option</code></em></span></dt><dd><p>
+ The name of a template-specific option to be set for this dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The new value to use for a template-specific option.
+ If the equal sign and value are omitted, then any previous
+ setting for the option is removed from the dictionary,
+ allowing the default to be used.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the text search dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The new owner of the text search dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the text search dictionary.
+ </p></dd></dl></div><p>
+ Template-specific options can appear in any order.
+ </p></div><div class="refsect1" id="id-1.9.3.38.7"><h2>Examples</h2><p>
+ The following example command changes the stopword list
+ for a Snowball-based dictionary. Other parameters remain unchanged.
+ </p><pre class="programlisting">
+ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian );
+</pre><p>
+ The following example command changes the language option to <code class="literal">dutch</code>,
+ and removes the stopword option entirely.
+ </p><pre class="programlisting">
+ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords );
+</pre><p>
+ The following example command <span class="quote">“<span class="quote">updates</span>”</span> the dictionary's
+ definition without actually changing anything.
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH DICTIONARY my_dict ( dummy );
+</pre><p>
+
+ (The reason this works is that the option removal code doesn't complain
+ if there is no such option.) This trick is useful when changing
+ configuration files for the dictionary: the <code class="command">ALTER</code> will
+ force existing database sessions to re-read the configuration files,
+ which otherwise they would never do if they had read them earlier.
+ </p></div><div class="refsect1" id="id-1.9.3.38.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER TEXT SEARCH DICTIONARY</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.38.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY"><span class="refentrytitle">CREATE TEXT SEARCH DICTIONARY</span></a>, <a class="xref" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY"><span class="refentrytitle">DROP TEXT SEARCH DICTIONARY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TEXT SEARCH CONFIGURATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TEXT SEARCH PARSER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertsparser.html b/doc/src/sgml/html/sql-altertsparser.html
new file mode 100644
index 0000000..63a109a
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertsparser.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TEXT SEARCH PARSER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY" /><link rel="next" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TEXT SEARCH PARSER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTSPARSER"><div class="titlepage"></div><a id="id-1.9.3.39.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TEXT SEARCH PARSER</span></h2><p>ALTER TEXT SEARCH PARSER — change the definition of a text search parser</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TEXT SEARCH PARSER <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TEXT SEARCH PARSER <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.39.5"><h2>Description</h2><p>
+ <code class="command">ALTER TEXT SEARCH PARSER</code> changes the definition of
+ a text search parser. Currently, the only supported functionality
+ is to change the parser's name.
+ </p><p>
+ You must be a superuser to use <code class="command">ALTER TEXT SEARCH PARSER</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.39.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the text search parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the text search parser.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.39.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER TEXT SEARCH PARSER</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.39.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER"><span class="refentrytitle">CREATE TEXT SEARCH PARSER</span></a>, <a class="xref" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER"><span class="refentrytitle">DROP TEXT SEARCH PARSER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TEXT SEARCH DICTIONARY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TEXT SEARCH TEMPLATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertstemplate.html b/doc/src/sgml/html/sql-altertstemplate.html
new file mode 100644
index 0000000..671adbe
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertstemplate.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TEXT SEARCH TEMPLATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER" /><link rel="next" href="sql-altertrigger.html" title="ALTER TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TEXT SEARCH TEMPLATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-altertrigger.html" title="ALTER TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTSTEMPLATE"><div class="titlepage"></div><a id="id-1.9.3.40.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TEXT SEARCH TEMPLATE</span></h2><p>ALTER TEXT SEARCH TEMPLATE — change the definition of a text search template</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TEXT SEARCH TEMPLATE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TEXT SEARCH TEMPLATE <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.40.5"><h2>Description</h2><p>
+ <code class="command">ALTER TEXT SEARCH TEMPLATE</code> changes the definition of
+ a text search template. Currently, the only supported functionality
+ is to change the template's name.
+ </p><p>
+ You must be a superuser to use <code class="command">ALTER TEXT SEARCH TEMPLATE</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.40.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search template.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name of the text search template.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the text search template.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.40.7"><h2>Compatibility</h2><p>
+ There is no <code class="command">ALTER TEXT SEARCH TEMPLATE</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.40.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE"><span class="refentrytitle">CREATE TEXT SEARCH TEMPLATE</span></a>, <a class="xref" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE"><span class="refentrytitle">DROP TEXT SEARCH TEMPLATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-altertrigger.html" title="ALTER TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TEXT SEARCH PARSER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-altertype.html b/doc/src/sgml/html/sql-altertype.html
new file mode 100644
index 0000000..3068ee1
--- /dev/null
+++ b/doc/src/sgml/html/sql-altertype.html
@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TYPE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertrigger.html" title="ALTER TRIGGER" /><link rel="next" href="sql-alteruser.html" title="ALTER USER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TYPE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertrigger.html" title="ALTER TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteruser.html" title="ALTER USER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTYPE"><div class="titlepage"></div><a id="id-1.9.3.42.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TYPE</span></h2><p>ALTER TYPE —
+ change the definition of a type
+ </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER TYPE <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER TYPE <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> TO <em class="replaceable"><code>new_attribute_name</code></em> [ CASCADE | RESTRICT ]
+ALTER TYPE <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>action</code></em> [, ... ]
+ALTER TYPE <em class="replaceable"><code>name</code></em> ADD VALUE [ IF NOT EXISTS ] <em class="replaceable"><code>new_enum_value</code></em> [ { BEFORE | AFTER } <em class="replaceable"><code>neighbor_enum_value</code></em> ]
+ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME VALUE <em class="replaceable"><code>existing_enum_value</code></em> TO <em class="replaceable"><code>new_enum_value</code></em>
+ALTER TYPE <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>property</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
+
+<span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
+
+ ADD ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ CASCADE | RESTRICT ]
+ DROP ATTRIBUTE [ IF EXISTS ] <em class="replaceable"><code>attribute_name</code></em> [ CASCADE | RESTRICT ]
+ ALTER ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> [ SET DATA ] TYPE <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.42.5"><h2>Description</h2><p>
+ <code class="command">ALTER TYPE</code> changes the definition of an existing type.
+ There are several subforms:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">OWNER</code></span></dt><dd><p>
+ This form changes the owner of the type.
+ </p></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
+ This form changes the name of the type.
+ </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
+ This form moves the type into another schema.
+ </p></dd><dt><span class="term"><code class="literal">RENAME ATTRIBUTE</code></span></dt><dd><p>
+ This form is only usable with composite types.
+ It changes the name of an individual attribute of the type.
+ </p></dd><dt><span class="term"><code class="literal">ADD ATTRIBUTE</code></span></dt><dd><p>
+ This form adds a new attribute to a composite type, using the same syntax as
+ <a class="link" href="sql-createtype.html" title="CREATE TYPE"><code class="command">CREATE TYPE</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">DROP ATTRIBUTE [ IF EXISTS ]</code></span></dt><dd><p>
+ This form drops an attribute from a composite type.
+ If <code class="literal">IF EXISTS</code> is specified and the attribute
+ does not exist, no error is thrown. In this case a notice
+ is issued instead.
+ </p></dd><dt><span class="term"><code class="literal">ALTER ATTRIBUTE ... SET DATA TYPE</code></span></dt><dd><p>
+ This form changes the type of an attribute of a composite type.
+ </p></dd><dt><span class="term"><code class="literal">ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ]</code></span></dt><dd><p>
+ This form adds a new value to an enum type. The new value's place in
+ the enum's ordering can be specified as being <code class="literal">BEFORE</code>
+ or <code class="literal">AFTER</code> one of the existing values. Otherwise,
+ the new item is added at the end of the list of values.
+ </p><p>
+ If <code class="literal">IF NOT EXISTS</code> is specified, it is not an error if
+ the type already contains the new value: a notice is issued but no other
+ action is taken. Otherwise, an error will occur if the new value is
+ already present.
+ </p></dd><dt><span class="term"><code class="literal">RENAME VALUE</code></span></dt><dd><p>
+ This form renames a value of an enum type.
+ The value's place in the enum's ordering is not affected.
+ An error will occur if the specified value is not present or the new
+ name is already present.
+ </p></dd><dt><span class="term">
+ <code class="literal">SET ( <em class="replaceable"><code>property</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )</code>
+ </span></dt><dd><p>
+ This form is only applicable to base types. It allows adjustment of a
+ subset of the base-type properties that can be set in <code class="command">CREATE
+ TYPE</code>. Specifically, these properties can be changed:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">RECEIVE</code> can be set to the name of a binary input
+ function, or <code class="literal">NONE</code> to remove the type's binary
+ input function. Using this option requires superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">SEND</code> can be set to the name of a binary output
+ function, or <code class="literal">NONE</code> to remove the type's binary
+ output function. Using this option requires superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">TYPMOD_IN</code> can be set to the name of a type
+ modifier input function, or <code class="literal">NONE</code> to remove the
+ type's type modifier input function. Using this option requires
+ superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">TYPMOD_OUT</code> can be set to the name of a type
+ modifier output function, or <code class="literal">NONE</code> to remove the
+ type's type modifier output function. Using this option requires
+ superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">ANALYZE</code> can be set to the name of a type-specific
+ statistics collection function, or <code class="literal">NONE</code> to remove
+ the type's statistics collection function. Using this option
+ requires superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">SUBSCRIPT</code> can be set to the name of a type-specific
+ subscripting handler function, or <code class="literal">NONE</code> to remove
+ the type's subscripting handler function. Using this option
+ requires superuser privilege.
+ </p></li><li class="listitem"><p>
+ <code class="literal">STORAGE</code><a id="id-1.9.3.42.5.2.2.10.2.1.2.7.1.2" class="indexterm"></a>
+ can be set to <code class="literal">plain</code>,
+ <code class="literal">extended</code>, <code class="literal">external</code>,
+ or <code class="literal">main</code> (see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a> for
+ more information about what these mean). However, changing
+ from <code class="literal">plain</code> to another setting requires superuser
+ privilege (because it requires that the type's C functions all be
+ TOAST-ready), and changing to <code class="literal">plain</code> from another
+ setting is not allowed at all (since the type may already have
+ TOASTed values present in the database). Note that changing this
+ option doesn't by itself change any stored data, it just sets the
+ default TOAST strategy to be used for table columns created in the
+ future. See <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a> to change the TOAST
+ strategy for existing table columns.
+ </p></li></ul></div><p>
+ See <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> for more details about these
+ type properties. Note that where appropriate, a change in these
+ properties for a base type will be propagated automatically to domains
+ based on that type.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="literal">ADD ATTRIBUTE</code>, <code class="literal">DROP
+ ATTRIBUTE</code>, and <code class="literal">ALTER ATTRIBUTE</code> actions
+ can be combined into a list of multiple alterations to apply in
+ parallel. For example, it is possible to add several attributes
+ and/or alter the type of several attributes in a single command.
+ </p><p>
+ You must own the type to use <code class="command">ALTER TYPE</code>.
+ To change the schema of a type, you must also have
+ <code class="literal">CREATE</code> privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the type's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the type.
+ However, a superuser can alter ownership of any type anyway.)
+ To add an attribute or alter an attribute type, you must also
+ have <code class="literal">USAGE</code> privilege on the attribute's data type.
+ </p></div><div class="refsect1" id="id-1.9.3.42.6"><h2>Parameters</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of an existing type to
+ alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>attribute_name</code></em></span></dt><dd><p>
+ The name of the attribute to add, alter, or drop.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_attribute_name</code></em></span></dt><dd><p>
+ The new name of the attribute to be renamed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The data type of the attribute to add, or the new type of the
+ attribute to alter.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_enum_value</code></em></span></dt><dd><p>
+ The new value to be added to an enum type's list of values,
+ or the new name to be given to an existing value.
+ Like all enum literals, it needs to be quoted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>neighbor_enum_value</code></em></span></dt><dd><p>
+ The existing enum value that the new value should be added immediately
+ before or after in the enum type's sort ordering.
+ Like all enum literals, it needs to be quoted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>existing_enum_value</code></em></span></dt><dd><p>
+ The existing enum value that should be renamed.
+ Like all enum literals, it needs to be quoted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>property</code></em></span></dt><dd><p>
+ The name of a base-type property to be modified; see above for
+ possible values.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically propagate the operation to typed tables of the
+ type being altered, and their descendants.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse the operation if the type being altered is the type of a
+ typed table. This is the default.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.42.7"><h2>Notes</h2><p>
+ If <code class="command">ALTER TYPE ... ADD VALUE</code> (the form that adds a new
+ value to an enum type) is executed inside a transaction block, the new
+ value cannot be used until after the transaction has been committed.
+ </p><p>
+ Comparisons involving an added enum value will sometimes be slower than
+ comparisons involving only original members of the enum type. This will
+ usually only occur if <code class="literal">BEFORE</code> or <code class="literal">AFTER</code>
+ is used to set the new value's sort position somewhere other than at the
+ end of the list. However, sometimes it will happen even though the new
+ value is added at the end (this occurs if the OID counter <span class="quote">“<span class="quote">wrapped
+ around</span>”</span> since the original creation of the enum type). The slowdown is
+ usually insignificant; but if it matters, optimal performance can be
+ regained by dropping and recreating the enum type, or by dumping and
+ restoring the database.
+ </p></div><div class="refsect1" id="id-1.9.3.42.8"><h2>Examples</h2><p>
+ To rename a data type:
+</p><pre class="programlisting">
+ALTER TYPE electronic_mail RENAME TO email;
+</pre><p>
+ </p><p>
+ To change the owner of the type <code class="literal">email</code>
+ to <code class="literal">joe</code>:
+</p><pre class="programlisting">
+ALTER TYPE email OWNER TO joe;
+</pre><p>
+ </p><p>
+ To change the schema of the type <code class="literal">email</code>
+ to <code class="literal">customers</code>:
+</p><pre class="programlisting">
+ALTER TYPE email SET SCHEMA customers;
+</pre><p>
+ </p><p>
+ To add a new attribute to a composite type:
+</p><pre class="programlisting">
+ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
+</pre><p>
+ </p><p>
+ To add a new value to an enum type in a particular sort position:
+</p><pre class="programlisting">
+ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';
+</pre><p>
+ </p><p>
+ To rename an enum value:
+</p><pre class="programlisting">
+ALTER TYPE colors RENAME VALUE 'purple' TO 'mauve';
+</pre><p>
+ </p><p>
+ To create binary I/O functions for an existing base type:
+</p><pre class="programlisting">
+CREATE FUNCTION mytypesend(mytype) RETURNS bytea ...;
+CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype ...;
+ALTER TYPE mytype SET (
+ SEND = mytypesend,
+ RECEIVE = mytyperecv
+);
+</pre></div><div class="refsect1" id="id-1.9.3.42.9"><h2>Compatibility</h2><p>
+ The variants to add and drop attributes are part of the SQL
+ standard; the other variants are PostgreSQL extensions.
+ </p></div><div class="refsect1" id="SQL-ALTERTYPE-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a>, <a class="xref" href="sql-droptype.html" title="DROP TYPE"><span class="refentrytitle">DROP TYPE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertrigger.html" title="ALTER TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteruser.html" title="ALTER USER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER USER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alteruser.html b/doc/src/sgml/html/sql-alteruser.html
new file mode 100644
index 0000000..b84b8f3
--- /dev/null
+++ b/doc/src/sgml/html/sql-alteruser.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER USER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertype.html" title="ALTER TYPE" /><link rel="next" href="sql-alterusermapping.html" title="ALTER USER MAPPING" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER USER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertype.html" title="ALTER TYPE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterusermapping.html" title="ALTER USER MAPPING">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERUSER"><div class="titlepage"></div><a id="id-1.9.3.43.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER USER</span></h2><p>ALTER USER — change a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER USER <em class="replaceable"><code>role_specification</code></em> [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ SUPERUSER | NOSUPERUSER
+ | CREATEDB | NOCREATEDB
+ | CREATEROLE | NOCREATEROLE
+ | INHERIT | NOINHERIT
+ | LOGIN | NOLOGIN
+ | REPLICATION | NOREPLICATION
+ | BYPASSRLS | NOBYPASSRLS
+ | CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ | [ ENCRYPTED ] PASSWORD '<em class="replaceable"><code>password</code></em>' | PASSWORD NULL
+ | VALID UNTIL '<em class="replaceable"><code>timestamp</code></em>'
+
+ALTER USER <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+
+ALTER USER { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] SET <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | DEFAULT }
+ALTER USER { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] SET <em class="replaceable"><code>configuration_parameter</code></em> FROM CURRENT
+ALTER USER { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] RESET <em class="replaceable"><code>configuration_parameter</code></em>
+ALTER USER { <em class="replaceable"><code>role_specification</code></em> | ALL } [ IN DATABASE <em class="replaceable"><code>database_name</code></em> ] RESET ALL
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ <em class="replaceable"><code>role_name</code></em>
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+</pre></div><div class="refsect1" id="id-1.9.3.43.5"><h2>Description</h2><p>
+ <code class="command">ALTER USER</code> is now an alias for
+ <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.43.6"><h2>Compatibility</h2><p>
+ The <code class="command">ALTER USER</code> statement is a
+ <span class="productname">PostgreSQL</span> extension. The SQL standard
+ leaves the definition of users to the implementation.
+ </p></div><div class="refsect1" id="id-1.9.3.43.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertype.html" title="ALTER TYPE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterusermapping.html" title="ALTER USER MAPPING">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TYPE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER USER MAPPING</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterusermapping.html b/doc/src/sgml/html/sql-alterusermapping.html
new file mode 100644
index 0000000..d7d5a07
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterusermapping.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER USER MAPPING</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alteruser.html" title="ALTER USER" /><link rel="next" href="sql-alterview.html" title="ALTER VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER USER MAPPING</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alteruser.html" title="ALTER USER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterview.html" title="ALTER VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERUSERMAPPING"><div class="titlepage"></div><a id="id-1.9.3.44.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER USER MAPPING</span></h2><p>ALTER USER MAPPING — change the definition of a user mapping</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER USER MAPPING FOR { <em class="replaceable"><code>user_name</code></em> | USER | CURRENT_ROLE | CURRENT_USER | SESSION_USER | PUBLIC }
+ SERVER <em class="replaceable"><code>server_name</code></em>
+ OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )
+</pre></div><div class="refsect1" id="id-1.9.3.44.5"><h2>Description</h2><p>
+ <code class="command">ALTER USER MAPPING</code> changes the definition of a
+ user mapping.
+ </p><p>
+ The owner of a foreign server can alter user mappings for that
+ server for any user. Also, a user can alter a user mapping for
+ their own user name if <code class="literal">USAGE</code> privilege on the server has
+ been granted to the user.
+ </p></div><div class="refsect1" id="id-1.9.3.44.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ User name of the mapping. <code class="literal">CURRENT_ROLE</code>, <code class="literal">CURRENT_USER</code>,
+ and <code class="literal">USER</code> match the name of the current
+ user. <code class="literal">PUBLIC</code> is used to match all present and future
+ user names in the system.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ Server name of the user mapping.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )</code></span></dt><dd><p>
+ Change options for the user mapping. The new options override
+ any previously specified
+ options. <code class="literal">ADD</code>, <code class="literal">SET</code>, and <code class="literal">DROP</code>
+ specify the action to be performed. <code class="literal">ADD</code> is assumed
+ if no operation is explicitly specified. Option names must be
+ unique; options are also validated by the server's foreign-data
+ wrapper.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.44.7"><h2>Examples</h2><p>
+ Change the password for user mapping <code class="literal">bob</code>, server <code class="literal">foo</code>:
+</p><pre class="programlisting">
+ALTER USER MAPPING FOR bob SERVER foo OPTIONS (SET password 'public');
+</pre></div><div class="refsect1" id="id-1.9.3.44.8"><h2>Compatibility</h2><p>
+ <code class="command">ALTER USER MAPPING</code> conforms to ISO/IEC 9075-9
+ (SQL/MED). There is a subtle syntax issue: The standard omits
+ the <code class="literal">FOR</code> key word. Since both <code class="literal">CREATE
+ USER MAPPING</code> and <code class="literal">DROP USER MAPPING</code> use
+ <code class="literal">FOR</code> in analogous positions, and IBM DB2 (being
+ the other major SQL/MED implementation) also requires it
+ for <code class="literal">ALTER USER MAPPING</code>, PostgreSQL diverges from
+ the standard here in the interest of consistency and
+ interoperability.
+ </p></div><div class="refsect1" id="id-1.9.3.44.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>, <a class="xref" href="sql-dropusermapping.html" title="DROP USER MAPPING"><span class="refentrytitle">DROP USER MAPPING</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alteruser.html" title="ALTER USER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterview.html" title="ALTER VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER USER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-alterview.html b/doc/src/sgml/html/sql-alterview.html
new file mode 100644
index 0000000..89f10fb
--- /dev/null
+++ b/doc/src/sgml/html/sql-alterview.html
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterusermapping.html" title="ALTER USER MAPPING" /><link rel="next" href="sql-analyze.html" title="ANALYZE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterusermapping.html" title="ALTER USER MAPPING">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-analyze.html" title="ANALYZE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERVIEW"><div class="titlepage"></div><a id="id-1.9.3.45.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER VIEW</span></h2><p>ALTER VIEW — change the definition of a view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET DEFAULT <em class="replaceable"><code>expression</code></em>
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP DEFAULT
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RENAME [ COLUMN ] <em class="replaceable"><code>column_name</code></em> TO <em class="replaceable"><code>new_column_name</code></em>
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>view_option_name</code></em> [= <em class="replaceable"><code>view_option_value</code></em>] [, ... ] )
+ALTER VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> RESET ( <em class="replaceable"><code>view_option_name</code></em> [, ... ] )
+</pre></div><div class="refsect1" id="id-1.9.3.45.5"><h2>Description</h2><p>
+ <code class="command">ALTER VIEW</code> changes various auxiliary properties
+ of a view. (If you want to modify the view's defining query,
+ use <code class="command">CREATE OR REPLACE VIEW</code>.)
+ </p><p>
+ You must own the view to use <code class="command">ALTER VIEW</code>.
+ To change a view's schema, you must also have <code class="literal">CREATE</code>
+ privilege on the new schema.
+ To alter the owner, you must also be a direct or indirect member of the new
+ owning role, and that role must have <code class="literal">CREATE</code> privilege on
+ the view's schema. (These restrictions enforce that altering the owner
+ doesn't do anything you couldn't do by dropping and recreating the view.
+ However, a superuser can alter ownership of any view anyway.)
+ </p></div><div class="refsect1" id="id-1.9.3.45.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ Name of an existing column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_column_name</code></em></span></dt><dd><p>
+ New name for an existing column.
+ </p></dd><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the view does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP DEFAULT</code></span></dt><dd><p>
+ These forms set or remove the default value for a column.
+ A view column's default value is substituted into any
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code> command whose target is the
+ view, before applying any rules or triggers for the view. The view's
+ default will therefore take precedence over any default values from
+ underlying relations.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
+ The user name of the new owner of the view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
+ The new name for the view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
+ The new schema for the view.
+ </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>view_option_name</code></em> [= <em class="replaceable"><code>view_option_value</code></em>] [, ... ] )</code><br /></span><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>view_option_name</code></em> [, ... ] )</code></span></dt><dd><p>
+ Sets or resets a view option. Currently supported options are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">check_option</code> (<code class="type">enum</code>)</span></dt><dd><p>
+ Changes the check option of the view. The value must
+ be <code class="literal">local</code> or <code class="literal">cascaded</code>.
+ </p></dd><dt><span class="term"><code class="literal">security_barrier</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Changes the security-barrier property of the view. The value must
+ be a Boolean value, such as <code class="literal">true</code>
+ or <code class="literal">false</code>.
+ </p></dd><dt><span class="term"><code class="literal">security_invoker</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Changes the security-invoker property of the view. The value must
+ be a Boolean value, such as <code class="literal">true</code>
+ or <code class="literal">false</code>.
+ </p></dd></dl></div></dd></dl></div></div><div class="refsect1" id="id-1.9.3.45.7"><h2>Notes</h2><p>
+ For historical reasons, <code class="command">ALTER TABLE</code> can be used with
+ views too; but the only variants of <code class="command">ALTER TABLE</code>
+ that are allowed with views are equivalent to the ones shown above.
+ </p></div><div class="refsect1" id="id-1.9.3.45.8"><h2>Examples</h2><p>
+ To rename the view <code class="literal">foo</code> to
+ <code class="literal">bar</code>:
+</p><pre class="programlisting">
+ALTER VIEW foo RENAME TO bar;
+</pre><p>
+ </p><p>
+ To attach a default column value to an updatable view:
+</p><pre class="programlisting">
+CREATE TABLE base_table (id int, ts timestamptz);
+CREATE VIEW a_view AS SELECT * FROM base_table;
+ALTER VIEW a_view ALTER COLUMN ts SET DEFAULT now();
+INSERT INTO base_table(id) VALUES(1); -- ts will receive a NULL
+INSERT INTO a_view(id) VALUES(2); -- ts will receive the current time
+</pre></div><div class="refsect1" id="id-1.9.3.45.9"><h2>Compatibility</h2><p>
+ <code class="command">ALTER VIEW</code> is a <span class="productname">PostgreSQL</span>
+ extension of the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.45.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a>, <a class="xref" href="sql-dropview.html" title="DROP VIEW"><span class="refentrytitle">DROP VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterusermapping.html" title="ALTER USER MAPPING">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-analyze.html" title="ANALYZE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER USER MAPPING </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ANALYZE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-analyze.html b/doc/src/sgml/html/sql-analyze.html
new file mode 100644
index 0000000..745addb
--- /dev/null
+++ b/doc/src/sgml/html/sql-analyze.html
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ANALYZE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterview.html" title="ALTER VIEW" /><link rel="next" href="sql-begin.html" title="BEGIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ANALYZE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterview.html" title="ALTER VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-begin.html" title="BEGIN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ANALYZE"><div class="titlepage"></div><a id="id-1.9.3.46.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ANALYZE</span></h2><p>ANALYZE — collect statistics about a database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ANALYZE [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ] [ <em class="replaceable"><code>table_and_columns</code></em> [, ...] ]
+ANALYZE [ VERBOSE ] [ <em class="replaceable"><code>table_and_columns</code></em> [, ...] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
+ SKIP_LOCKED [ <em class="replaceable"><code>boolean</code></em> ]
+
+<span class="phrase">and <em class="replaceable"><code>table_and_columns</code></em> is:</span>
+
+ <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.46.5"><h2>Description</h2><p>
+ <code class="command">ANALYZE</code> collects statistics about the contents
+ of tables in the database, and stores the results in the <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>
+ system catalog. Subsequently, the query planner uses these
+ statistics to help determine the most efficient execution plans for
+ queries.
+ </p><p>
+ Without a <em class="replaceable"><code>table_and_columns</code></em>
+ list, <code class="command">ANALYZE</code> processes every table and materialized view
+ in the current database that the current user has permission to analyze.
+ With a list, <code class="command">ANALYZE</code> processes only those table(s).
+ It is further possible to give a list of column names for a table,
+ in which case only the statistics for those columns are collected.
+ </p><p>
+ When the option list is surrounded by parentheses, the options can be
+ written in any order. The parenthesized syntax was added in
+ <span class="productname">PostgreSQL</span> 11; the unparenthesized syntax
+ is deprecated.
+ </p></div><div class="refsect1" id="id-1.9.3.46.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
+ Enables display of progress messages.
+ </p></dd><dt><span class="term"><code class="literal">SKIP_LOCKED</code></span></dt><dd><p>
+ Specifies that <code class="command">ANALYZE</code> should not wait for any
+ conflicting locks to be released when beginning work on a relation:
+ if a relation cannot be locked immediately without waiting, the relation
+ is skipped. Note that even with this option, <code class="command">ANALYZE</code>
+ may still block when opening the relation's indexes or when acquiring
+ sample rows from partitions, table inheritance children, and some
+ types of foreign tables. Also, while <code class="command">ANALYZE</code>
+ ordinarily processes all partitions of specified partitioned tables,
+ this option will cause <code class="command">ANALYZE</code> to skip all
+ partitions if there is a conflicting lock on the partitioned table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of a specific table to
+ analyze. If omitted, all regular tables, partitioned tables, and
+ materialized views in the current database are analyzed (but not
+ foreign tables). If the specified table is a partitioned table, both the
+ inheritance statistics of the partitioned table as a whole and
+ statistics of the individual partitions are updated.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a specific column to analyze. Defaults to all columns.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.46.7"><h2>Outputs</h2><p>
+ When <code class="literal">VERBOSE</code> is specified, <code class="command">ANALYZE</code> emits
+ progress messages to indicate which table is currently being
+ processed. Various statistics about the tables are printed as well.
+ </p></div><div class="refsect1" id="id-1.9.3.46.8"><h2>Notes</h2><p>
+ To analyze a table, one must ordinarily be the table's owner or a
+ superuser. However, database owners are allowed to
+ analyze all tables in their databases, except shared catalogs.
+ (The restriction for shared catalogs means that a true database-wide
+ <code class="command">ANALYZE</code> can only be performed by a superuser.)
+ <code class="command">ANALYZE</code> will skip over any tables that the calling user
+ does not have permission to analyze.
+ </p><p>
+ Foreign tables are analyzed only when explicitly selected. Not all
+ foreign data wrappers support <code class="command">ANALYZE</code>. If the table's
+ wrapper does not support <code class="command">ANALYZE</code>, the command prints a
+ warning and does nothing.
+ </p><p>
+ In the default <span class="productname">PostgreSQL</span> configuration,
+ the autovacuum daemon (see <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>)
+ takes care of automatic analyzing of tables when they are first loaded
+ with data, and as they change throughout regular operation.
+ When autovacuum is disabled,
+ it is a good idea to run <code class="command">ANALYZE</code> periodically, or
+ just after making major changes in the contents of a table. Accurate
+ statistics will help the planner to choose the most appropriate query
+ plan, and thereby improve the speed of query processing. A common
+ strategy for read-mostly databases is to run <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>
+ and <code class="command">ANALYZE</code> once a day during a low-usage time of day.
+ (This will not be sufficient if there is heavy update activity.)
+ </p><p>
+ <code class="command">ANALYZE</code>
+ requires only a read lock on the target table, so it can run in
+ parallel with other activity on the table.
+ </p><p>
+ The statistics collected by <code class="command">ANALYZE</code> usually
+ include a list of some of the most common values in each column and
+ a histogram showing the approximate data distribution in each
+ column. One or both of these can be omitted if
+ <code class="command">ANALYZE</code> deems them uninteresting (for example,
+ in a unique-key column, there are no common values) or if the
+ column data type does not support the appropriate operators. There
+ is more information about the statistics in <a class="xref" href="maintenance.html" title="Chapter 25. Routine Database Maintenance Tasks">Chapter 25</a>.
+ </p><p>
+ For large tables, <code class="command">ANALYZE</code> takes a random sample
+ of the table contents, rather than examining every row. This
+ allows even very large tables to be analyzed in a small amount of
+ time. Note, however, that the statistics are only approximate, and
+ will change slightly each time <code class="command">ANALYZE</code> is run,
+ even if the actual table contents did not change. This might result
+ in small changes in the planner's estimated costs shown by
+ <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN</code></a>.
+ In rare situations, this non-determinism will cause the planner's
+ choices of query plans to change after <code class="command">ANALYZE</code> is run.
+ To avoid this, raise the amount of statistics collected by
+ <code class="command">ANALYZE</code>, as described below.
+ </p><p>
+ The extent of analysis can be controlled by adjusting the
+ <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> configuration variable, or
+ on a column-by-column basis by setting the per-column statistics
+ target with <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ... ALTER COLUMN ... SET
+ STATISTICS</code></a>.
+ The target value sets the
+ maximum number of entries in the most-common-value list and the
+ maximum number of bins in the histogram. The default target value
+ is 100, but this can be adjusted up or down to trade off accuracy of
+ planner estimates against the time taken for
+ <code class="command">ANALYZE</code> and the amount of space occupied in
+ <code class="literal">pg_statistic</code>. In particular, setting the
+ statistics target to zero disables collection of statistics for
+ that column. It might be useful to do that for columns that are
+ never used as part of the <code class="literal">WHERE</code>, <code class="literal">GROUP BY</code>,
+ or <code class="literal">ORDER BY</code> clauses of queries, since the planner will
+ have no use for statistics on such columns.
+ </p><p>
+ The largest statistics target among the columns being analyzed determines
+ the number of table rows sampled to prepare the statistics. Increasing
+ the target causes a proportional increase in the time and space needed
+ to do <code class="command">ANALYZE</code>.
+ </p><p>
+ One of the values estimated by <code class="command">ANALYZE</code> is the number of
+ distinct values that appear in each column. Because only a subset of the
+ rows are examined, this estimate can sometimes be quite inaccurate, even
+ with the largest possible statistics target. If this inaccuracy leads to
+ bad query plans, a more accurate value can be determined manually and then
+ installed with
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</code></a>.
+ </p><p>
+ If the table being analyzed has inheritance children,
+ <code class="command">ANALYZE</code> gathers two sets of statistics: one on the rows
+ of the parent table only, and a second including rows of both the parent
+ table and all of its children. This second set of statistics is needed when
+ planning queries that process the inheritance tree as a whole. The child
+ tables themselves are not individually analyzed in this case.
+ The autovacuum daemon, however, will only consider inserts or
+ updates on the parent table itself when deciding whether to trigger an
+ automatic analyze for that table. If that table is rarely inserted into
+ or updated, the inheritance statistics will not be up to date unless you
+ run <code class="command">ANALYZE</code> manually.
+ </p><p>
+ For partitioned tables, <code class="command">ANALYZE</code> gathers statistics by
+ sampling rows from all partitions; in addition, it will recurse into each
+ partition and update its statistics. Each leaf partition is analyzed only
+ once, even with multi-level partitioning. No statistics are collected for
+ only the parent table (without data from its partitions), because with
+ partitioning it's guaranteed to be empty.
+ </p><p>
+ The autovacuum daemon does not process partitioned tables, nor does it
+ process inheritance parents if only the children are ever modified.
+ It is usually necessary to periodically run a manual
+ <code class="command">ANALYZE</code> to keep the statistics of the table hierarchy
+ up to date.
+ </p><p>
+ If any child tables or partitions are foreign tables whose foreign
+ data wrappers do not support <code class="command">ANALYZE</code>, those tables are
+ ignored while gathering inheritance statistics.
+ </p><p>
+ If the table being analyzed is completely empty, <code class="command">ANALYZE</code>
+ will not record new statistics for that table. Any existing statistics
+ will be retained.
+ </p><p>
+ Each backend running <code class="command">ANALYZE</code> will report its progress
+ in the <code class="structname">pg_stat_progress_analyze</code> view. See
+ <a class="xref" href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING" title="28.4.1. ANALYZE Progress Reporting">Section 28.4.1</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.46.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">ANALYZE</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.46.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a>, <a class="xref" href="app-vacuumdb.html" title="vacuumdb"><span class="refentrytitle"><span class="application">vacuumdb</span></span></a>, <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST" title="20.4.4. Cost-based Vacuum Delay">Section 20.4.4</a>, <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>, <a class="xref" href="progress-reporting.html#ANALYZE-PROGRESS-REPORTING" title="28.4.1. ANALYZE Progress Reporting">Section 28.4.1</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterview.html" title="ALTER VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-begin.html" title="BEGIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> BEGIN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-begin.html b/doc/src/sgml/html/sql-begin.html
new file mode 100644
index 0000000..a773c15
--- /dev/null
+++ b/doc/src/sgml/html/sql-begin.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>BEGIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-analyze.html" title="ANALYZE" /><link rel="next" href="sql-call.html" title="CALL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">BEGIN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-analyze.html" title="ANALYZE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-call.html" title="CALL">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-BEGIN"><div class="titlepage"></div><a id="id-1.9.3.47.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">BEGIN</span></h2><p>BEGIN — start a transaction block</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+BEGIN [ WORK | TRANSACTION ] [ <em class="replaceable"><code>transaction_mode</code></em> [, ...] ]
+
+<span class="phrase">where <em class="replaceable"><code>transaction_mode</code></em> is one of:</span>
+
+ ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
+ READ WRITE | READ ONLY
+ [ NOT ] DEFERRABLE
+</pre></div><div class="refsect1" id="id-1.9.3.47.5"><h2>Description</h2><p>
+ <code class="command">BEGIN</code> initiates a transaction block, that is,
+ all statements after a <code class="command">BEGIN</code> command will be
+ executed in a single transaction until an explicit <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a> or <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a> is given.
+ By default (without <code class="command">BEGIN</code>),
+ <span class="productname">PostgreSQL</span> executes
+ transactions in <span class="quote">“<span class="quote">autocommit</span>”</span> mode, that is, each
+ statement is executed in its own transaction and a commit is
+ implicitly performed at the end of the statement (if execution was
+ successful, otherwise a rollback is done).
+ </p><p>
+ Statements are executed more quickly in a transaction block, because
+ transaction start/commit requires significant CPU and disk
+ activity. Execution of multiple statements inside a transaction is
+ also useful to ensure consistency when making several related changes:
+ other sessions will be unable to see the intermediate states
+ wherein not all the related updates have been done.
+ </p><p>
+ If the isolation level, read/write mode, or deferrable mode is specified, the new
+ transaction has those characteristics, as if
+ <a class="link" href="sql-set-transaction.html" title="SET TRANSACTION"><code class="command">SET TRANSACTION</code></a>
+ was executed.
+ </p></div><div class="refsect1" id="id-1.9.3.47.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">WORK</code><br /></span><span class="term"><code class="literal">TRANSACTION</code></span></dt><dd><p>
+ Optional key words. They have no effect.
+ </p></dd></dl></div><p>
+ Refer to <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for information on the meaning
+ of the other parameters to this statement.
+ </p></div><div class="refsect1" id="id-1.9.3.47.7"><h2>Notes</h2><p>
+ <a class="link" href="sql-start-transaction.html" title="START TRANSACTION"><code class="command">START TRANSACTION</code></a> has the same functionality
+ as <code class="command">BEGIN</code>.
+ </p><p>
+ Use <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a> or
+ <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a>
+ to terminate a transaction block.
+ </p><p>
+ Issuing <code class="command">BEGIN</code> when already inside a transaction block will
+ provoke a warning message. The state of the transaction is not affected.
+ To nest transactions within a transaction block, use savepoints
+ (see <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a>).
+ </p><p>
+ For reasons of backwards compatibility, the commas between successive
+ <em class="replaceable"><code>transaction_modes</code></em> can be
+ omitted.
+ </p></div><div class="refsect1" id="id-1.9.3.47.8"><h2>Examples</h2><p>
+ To begin a transaction block:
+
+</p><pre class="programlisting">
+BEGIN;
+</pre></div><div class="refsect1" id="id-1.9.3.47.9"><h2>Compatibility</h2><p>
+ <code class="command">BEGIN</code> is a <span class="productname">PostgreSQL</span>
+ language extension. It is equivalent to the SQL-standard command
+ <a class="link" href="sql-start-transaction.html" title="START TRANSACTION"><code class="command">START TRANSACTION</code></a>, whose reference page
+ contains additional compatibility information.
+ </p><p>
+ The <code class="literal">DEFERRABLE</code>
+ <em class="replaceable"><code>transaction_mode</code></em>
+ is a <span class="productname">PostgreSQL</span> language extension.
+ </p><p>
+ Incidentally, the <code class="literal">BEGIN</code> key word is used for a
+ different purpose in embedded SQL. You are advised to be careful
+ about the transaction semantics when porting database applications.
+ </p></div><div class="refsect1" id="id-1.9.3.47.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>, <a class="xref" href="sql-start-transaction.html" title="START TRANSACTION"><span class="refentrytitle">START TRANSACTION</span></a>, <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-analyze.html" title="ANALYZE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-call.html" title="CALL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ANALYZE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CALL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-call.html b/doc/src/sgml/html/sql-call.html
new file mode 100644
index 0000000..dcc87f7
--- /dev/null
+++ b/doc/src/sgml/html/sql-call.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CALL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-begin.html" title="BEGIN" /><link rel="next" href="sql-checkpoint.html" title="CHECKPOINT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CALL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-begin.html" title="BEGIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-checkpoint.html" title="CHECKPOINT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CALL"><div class="titlepage"></div><a id="id-1.9.3.48.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CALL</span></h2><p>CALL — invoke a procedure</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CALL <em class="replaceable"><code>name</code></em> ( [ <em class="replaceable"><code>argument</code></em> ] [, ...] )
+</pre></div><div class="refsect1" id="id-1.9.3.48.5"><h2>Description</h2><p>
+ <code class="command">CALL</code> executes a procedure.
+ </p><p>
+ If the procedure has any output parameters, then a result row will be
+ returned, containing the values of those parameters.
+ </p></div><div class="refsect1" id="id-1.9.3.48.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the procedure.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argument</code></em></span></dt><dd><p>
+ An argument expression for the procedure call.
+ </p><p>
+ Arguments can include parameter names, using the syntax
+ <code class="literal"><em class="replaceable"><code>name</code></em> =&gt; <em class="replaceable"><code>value</code></em></code>.
+ This works the same as in ordinary function calls; see
+ <a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a> for details.
+ </p><p>
+ Arguments must be supplied for all procedure parameters that lack
+ defaults, including <code class="literal">OUT</code> parameters. However,
+ arguments matching <code class="literal">OUT</code> parameters are not evaluated,
+ so it's customary to just write <code class="literal">NULL</code> for them.
+ (Writing something else for an <code class="literal">OUT</code> parameter
+ might cause compatibility problems with
+ future <span class="productname">PostgreSQL</span> versions.)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.48.7"><h2>Notes</h2><p>
+ The user must have <code class="literal">EXECUTE</code> privilege on the procedure in
+ order to be allowed to invoke it.
+ </p><p>
+ To call a function (not a procedure), use <code class="command">SELECT</code> instead.
+ </p><p>
+ If <code class="command">CALL</code> is executed in a transaction block, then the
+ called procedure cannot execute transaction control statements.
+ Transaction control statements are only allowed if <code class="command">CALL</code>
+ is executed in its own transaction.
+ </p><p>
+ <span class="application">PL/pgSQL</span> handles output parameters
+ in <code class="command">CALL</code> commands differently;
+ see <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE" title="43.6.3. Calling a Procedure">Section 43.6.3</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.48.8"><h2>Examples</h2><pre class="programlisting">
+CALL do_db_maintenance();
+</pre></div><div class="refsect1" id="id-1.9.3.48.9"><h2>Compatibility</h2><p>
+ <code class="command">CALL</code> conforms to the SQL standard,
+ except for the handling of output parameters. The standard
+ says that users should write variables to receive the values
+ of output parameters.
+ </p></div><div class="refsect1" id="id-1.9.3.48.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-begin.html" title="BEGIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-checkpoint.html" title="CHECKPOINT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">BEGIN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CHECKPOINT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-checkpoint.html b/doc/src/sgml/html/sql-checkpoint.html
new file mode 100644
index 0000000..3eec682
--- /dev/null
+++ b/doc/src/sgml/html/sql-checkpoint.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CHECKPOINT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-call.html" title="CALL" /><link rel="next" href="sql-close.html" title="CLOSE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CHECKPOINT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-call.html" title="CALL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-close.html" title="CLOSE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CHECKPOINT"><div class="titlepage"></div><a id="id-1.9.3.49.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CHECKPOINT</span></h2><p>CHECKPOINT — force a write-ahead log checkpoint</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CHECKPOINT
+</pre></div><div class="refsect1" id="id-1.9.3.49.5"><h2>Description</h2><p>
+ A checkpoint is a point in the write-ahead log sequence at which
+ all data files have been updated to reflect the information in the
+ log. All data files will be flushed to disk. Refer to
+ <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a> for more details about what happens
+ during a checkpoint.
+ </p><p>
+ The <code class="command">CHECKPOINT</code> command forces an immediate
+ checkpoint when the command is issued, without waiting for a
+ regular checkpoint scheduled by the system (controlled by the settings in
+ <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS" title="20.5.2. Checkpoints">Section 20.5.2</a>).
+ <code class="command">CHECKPOINT</code> is not intended for use during normal
+ operation.
+ </p><p>
+ If executed during recovery, the <code class="command">CHECKPOINT</code> command
+ will force a restartpoint (see <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a>)
+ rather than writing a new checkpoint.
+ </p><p>
+ Only superusers or users with the privileges of
+ the <a class="link" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles"><code class="literal">pg_checkpoint</code></a>
+ role can call <code class="command">CHECKPOINT</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.49.6"><h2>Compatibility</h2><p>
+ The <code class="command">CHECKPOINT</code> command is a
+ <span class="productname">PostgreSQL</span> language extension.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-call.html" title="CALL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-close.html" title="CLOSE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CALL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CLOSE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-close.html b/doc/src/sgml/html/sql-close.html
new file mode 100644
index 0000000..291862c
--- /dev/null
+++ b/doc/src/sgml/html/sql-close.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CLOSE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-checkpoint.html" title="CHECKPOINT" /><link rel="next" href="sql-cluster.html" title="CLUSTER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CLOSE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-checkpoint.html" title="CHECKPOINT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-cluster.html" title="CLUSTER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CLOSE"><div class="titlepage"></div><a id="id-1.9.3.50.1" class="indexterm"></a><a id="id-1.9.3.50.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CLOSE</span></h2><p>CLOSE — close a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CLOSE { <em class="replaceable"><code>name</code></em> | ALL }
+</pre></div><div class="refsect1" id="id-1.9.3.50.6"><h2>Description</h2><p>
+ <code class="command">CLOSE</code> frees the resources associated with an open cursor.
+ After the cursor is closed, no subsequent operations
+ are allowed on it. A cursor should be closed when it is
+ no longer needed.
+ </p><p>
+ Every non-holdable open cursor is implicitly closed when a
+ transaction is terminated by <code class="command">COMMIT</code> or
+ <code class="command">ROLLBACK</code>. A holdable cursor is implicitly
+ closed if the transaction that created it aborts via
+ <code class="command">ROLLBACK</code>. If the creating transaction
+ successfully commits, the holdable cursor remains open until an
+ explicit <code class="command">CLOSE</code> is executed, or the client
+ disconnects.
+ </p></div><div class="refsect1" id="id-1.9.3.50.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an open cursor to close.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Close all open cursors.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.50.8"><h2>Notes</h2><p>
+ <span class="productname">PostgreSQL</span> does not have an explicit
+ <code class="command">OPEN</code> cursor statement; a cursor is considered
+ open when it is declared. Use the
+ <a class="link" href="sql-declare.html" title="DECLARE"><code class="command">DECLARE</code></a>
+ statement to declare a cursor.
+ </p><p>
+ You can see all available cursors by querying the <a class="link" href="view-pg-cursors.html" title="54.6. pg_cursors"><code class="structname">pg_cursors</code></a> system view.
+ </p><p>
+ If a cursor is closed after a savepoint which is later rolled back,
+ the <code class="command">CLOSE</code> is not rolled back; that is, the cursor
+ remains closed.
+ </p></div><div class="refsect1" id="id-1.9.3.50.9"><h2>Examples</h2><p>
+ Close the cursor <code class="literal">liahona</code>:
+</p><pre class="programlisting">
+CLOSE liahona;
+</pre></div><div class="refsect1" id="id-1.9.3.50.10"><h2>Compatibility</h2><p>
+ <code class="command">CLOSE</code> is fully conforming with the SQL
+ standard. <code class="command">CLOSE ALL</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.50.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>, <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>, <a class="xref" href="sql-move.html" title="MOVE"><span class="refentrytitle">MOVE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-checkpoint.html" title="CHECKPOINT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-cluster.html" title="CLUSTER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CHECKPOINT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CLUSTER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-cluster.html b/doc/src/sgml/html/sql-cluster.html
new file mode 100644
index 0000000..0d9de20
--- /dev/null
+++ b/doc/src/sgml/html/sql-cluster.html
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CLUSTER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-close.html" title="CLOSE" /><link rel="next" href="sql-comment.html" title="COMMENT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CLUSTER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-close.html" title="CLOSE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-comment.html" title="COMMENT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CLUSTER"><div class="titlepage"></div><a id="id-1.9.3.51.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CLUSTER</span></h2><p>CLUSTER — cluster a table according to an index</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CLUSTER [VERBOSE] <em class="replaceable"><code>table_name</code></em> [ USING <em class="replaceable"><code>index_name</code></em> ]
+CLUSTER ( <em class="replaceable"><code>option</code></em> [, ...] ) <em class="replaceable"><code>table_name</code></em> [ USING <em class="replaceable"><code>index_name</code></em> ]
+CLUSTER [VERBOSE]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.51.5"><h2>Description</h2><p>
+ <code class="command">CLUSTER</code> instructs <span class="productname">PostgreSQL</span>
+ to cluster the table specified
+ by <em class="replaceable"><code>table_name</code></em>
+ based on the index specified by
+ <em class="replaceable"><code>index_name</code></em>. The index must
+ already have been defined on
+ <em class="replaceable"><code>table_name</code></em>.
+ </p><p>
+ When a table is clustered, it is physically reordered
+ based on the index information. Clustering is a one-time operation:
+ when the table is subsequently updated, the changes are
+ not clustered. That is, no attempt is made to store new or
+ updated rows according to their index order. (If one wishes, one can
+ periodically recluster by issuing the command again. Also, setting
+ the table's <code class="literal">fillfactor</code> storage parameter to less than
+ 100% can aid in preserving cluster ordering during updates, since updated
+ rows are kept on the same page if enough space is available there.)
+ </p><p>
+ When a table is clustered, <span class="productname">PostgreSQL</span>
+ remembers which index it was clustered by. The form
+ <code class="command">CLUSTER <em class="replaceable"><code>table_name</code></em></code>
+ reclusters the table using the same index as before. You can also
+ use the <code class="literal">CLUSTER</code> or <code class="literal">SET WITHOUT CLUSTER</code>
+ forms of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> to set the index to be used for
+ future cluster operations, or to clear any previous setting.
+ </p><p>
+ <code class="command">CLUSTER</code> without any parameter reclusters all the
+ previously-clustered tables in the current database that the calling user
+ owns, or all such tables if called by a superuser. This
+ form of <code class="command">CLUSTER</code> cannot be executed inside a transaction
+ block.
+ </p><p>
+ When a table is being clustered, an <code class="literal">ACCESS
+ EXCLUSIVE</code> lock is acquired on it. This prevents any other
+ database operations (both reads and writes) from operating on the
+ table until the <code class="command">CLUSTER</code> is finished.
+ </p></div><div class="refsect1" id="id-1.9.3.51.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of a table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_name</code></em></span></dt><dd><p>
+ The name of an index.
+ </p></dd><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
+ Prints a progress report as each table is clustered.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.51.7"><h2>Notes</h2><p>
+ In cases where you are accessing single rows randomly
+ within a table, the actual order of the data in the
+ table is unimportant. However, if you tend to access some
+ data more than others, and there is an index that groups
+ them together, you will benefit from using <code class="command">CLUSTER</code>.
+ If you are requesting a range of indexed values from a table, or a
+ single indexed value that has multiple rows that match,
+ <code class="command">CLUSTER</code> will help because once the index identifies the
+ table page for the first row that matches, all other rows
+ that match are probably already on the same table page,
+ and so you save disk accesses and speed up the query.
+ </p><p>
+ <code class="command">CLUSTER</code> can re-sort the table using either an index scan
+ on the specified index, or (if the index is a b-tree) a sequential
+ scan followed by sorting. It will attempt to choose the method that
+ will be faster, based on planner cost parameters and available statistical
+ information.
+ </p><p>
+ When an index scan is used, a temporary copy of the table is created that
+ contains the table data in the index order. Temporary copies of each
+ index on the table are created as well. Therefore, you need free space on
+ disk at least equal to the sum of the table size and the index sizes.
+ </p><p>
+ When a sequential scan and sort is used, a temporary sort file is
+ also created, so that the peak temporary space requirement is as much
+ as double the table size, plus the index sizes. This method is often
+ faster than the index scan method, but if the disk space requirement is
+ intolerable, you can disable this choice by temporarily setting <a class="xref" href="runtime-config-query.html#GUC-ENABLE-SORT">enable_sort</a> to <code class="literal">off</code>.
+ </p><p>
+ It is advisable to set <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a> to
+ a reasonably large value (but not more than the amount of RAM you can
+ dedicate to the <code class="command">CLUSTER</code> operation) before clustering.
+ </p><p>
+ Because the planner records statistics about the ordering of
+ tables, it is advisable to run <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>
+ on the newly clustered table.
+ Otherwise, the planner might make poor choices of query plans.
+ </p><p>
+ Because <code class="command">CLUSTER</code> remembers which indexes are clustered,
+ one can cluster the tables one wants clustered manually the first time,
+ then set up a periodic maintenance script that executes
+ <code class="command">CLUSTER</code> without any parameters, so that the desired tables
+ are periodically reclustered.
+ </p><p>
+ Each backend running <code class="command">CLUSTER</code> will report its progress
+ in the <code class="structname">pg_stat_progress_cluster</code> view. See
+ <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a> for details.
+ </p><p>
+ Clustering a partitioned table clusters each of its partitions using the
+ partition of the specified partitioned index. When clustering a partitioned
+ table, the index may not be omitted.
+ </p></div><div class="refsect1" id="id-1.9.3.51.8"><h2>Examples</h2><p>
+ Cluster the table <code class="literal">employees</code> on the basis of
+ its index <code class="literal">employees_ind</code>:
+</p><pre class="programlisting">
+CLUSTER employees USING employees_ind;
+</pre><p>
+ </p><p>
+ Cluster the <code class="literal">employees</code> table using the same
+ index that was used before:
+</p><pre class="programlisting">
+CLUSTER employees;
+</pre><p>
+ </p><p>
+ Cluster all tables in the database that have previously been clustered:
+</p><pre class="programlisting">
+CLUSTER;
+</pre></div><div class="refsect1" id="id-1.9.3.51.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">CLUSTER</code> statement in the SQL standard.
+ </p><p>
+ The syntax
+</p><pre class="synopsis">
+CLUSTER <em class="replaceable"><code>index_name</code></em> ON <em class="replaceable"><code>table_name</code></em>
+</pre><p>
+ is also supported for compatibility with pre-8.3 <span class="productname">PostgreSQL</span>
+ versions.
+ </p></div><div class="refsect1" id="id-1.9.3.51.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-clusterdb.html" title="clusterdb"><span class="refentrytitle"><span class="application">clusterdb</span></span></a>, <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-close.html" title="CLOSE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-comment.html" title="COMMENT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CLOSE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMENT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-commands.html b/doc/src/sgml/html/sql-commands.html
new file mode 100644
index 0000000..b3266c1
--- /dev/null
+++ b/doc/src/sgml/html/sql-commands.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SQL Commands</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="reference.html" title="Part VI. Reference" /><link rel="next" href="sql-abort.html" title="ABORT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SQL Commands</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="reference.html" title="Part VI. Reference">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><th width="60%" align="center">Part VI. Reference</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-abort.html" title="ABORT">Next</a></td></tr></table><hr /></div><div class="reference" id="SQL-COMMANDS"><div class="titlepage"><div><div><h1 class="title">SQL Commands</h1></div></div><hr /></div><div class="partintro" id="id-1.9.3.2"><div></div><p>
+ This part contains reference information for the
+ <acronym class="acronym">SQL</acronym> commands supported by
+ <span class="productname">PostgreSQL</span>. By <span class="quote">“<span class="quote">SQL</span>”</span> the
+ language in general is meant; information about the standards
+ conformance and compatibility of each command can be found on the
+ respective reference page.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="refentrytitle"><a href="sql-abort.html">ABORT</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-alteraggregate.html">ALTER AGGREGATE</a></span><span class="refpurpose"> — change the definition of an aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-altercollation.html">ALTER COLLATION</a></span><span class="refpurpose"> — change the definition of a collation</span></dt><dt><span class="refentrytitle"><a href="sql-alterconversion.html">ALTER CONVERSION</a></span><span class="refpurpose"> — change the definition of a conversion</span></dt><dt><span class="refentrytitle"><a href="sql-alterdatabase.html">ALTER DATABASE</a></span><span class="refpurpose"> — change a database</span></dt><dt><span class="refentrytitle"><a href="sql-alterdefaultprivileges.html">ALTER DEFAULT PRIVILEGES</a></span><span class="refpurpose"> — define default access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-alterdomain.html">ALTER DOMAIN</a></span><span class="refpurpose"> —
+ change the definition of a domain
+ </span></dt><dt><span class="refentrytitle"><a href="sql-altereventtrigger.html">ALTER EVENT TRIGGER</a></span><span class="refpurpose"> — change the definition of an event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-alterextension.html">ALTER EXTENSION</a></span><span class="refpurpose"> —
+ change the definition of an extension
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alterforeigndatawrapper.html">ALTER FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — change the definition of a foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-alterforeigntable.html">ALTER FOREIGN TABLE</a></span><span class="refpurpose"> — change the definition of a foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-alterfunction.html">ALTER FUNCTION</a></span><span class="refpurpose"> — change the definition of a function</span></dt><dt><span class="refentrytitle"><a href="sql-altergroup.html">ALTER GROUP</a></span><span class="refpurpose"> — change role name or membership</span></dt><dt><span class="refentrytitle"><a href="sql-alterindex.html">ALTER INDEX</a></span><span class="refpurpose"> — change the definition of an index</span></dt><dt><span class="refentrytitle"><a href="sql-alterlanguage.html">ALTER LANGUAGE</a></span><span class="refpurpose"> — change the definition of a procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-alterlargeobject.html">ALTER LARGE OBJECT</a></span><span class="refpurpose"> — change the definition of a large object</span></dt><dt><span class="refentrytitle"><a href="sql-altermaterializedview.html">ALTER MATERIALIZED VIEW</a></span><span class="refpurpose"> — change the definition of a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-alteroperator.html">ALTER OPERATOR</a></span><span class="refpurpose"> — change the definition of an operator</span></dt><dt><span class="refentrytitle"><a href="sql-alteropclass.html">ALTER OPERATOR CLASS</a></span><span class="refpurpose"> — change the definition of an operator class</span></dt><dt><span class="refentrytitle"><a href="sql-alteropfamily.html">ALTER OPERATOR FAMILY</a></span><span class="refpurpose"> — change the definition of an operator family</span></dt><dt><span class="refentrytitle"><a href="sql-alterpolicy.html">ALTER POLICY</a></span><span class="refpurpose"> — change the definition of a row-level security policy</span></dt><dt><span class="refentrytitle"><a href="sql-alterprocedure.html">ALTER PROCEDURE</a></span><span class="refpurpose"> — change the definition of a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-alterpublication.html">ALTER PUBLICATION</a></span><span class="refpurpose"> — change the definition of a publication</span></dt><dt><span class="refentrytitle"><a href="sql-alterrole.html">ALTER ROLE</a></span><span class="refpurpose"> — change a database role</span></dt><dt><span class="refentrytitle"><a href="sql-alterroutine.html">ALTER ROUTINE</a></span><span class="refpurpose"> — change the definition of a routine</span></dt><dt><span class="refentrytitle"><a href="sql-alterrule.html">ALTER RULE</a></span><span class="refpurpose"> — change the definition of a rule</span></dt><dt><span class="refentrytitle"><a href="sql-alterschema.html">ALTER SCHEMA</a></span><span class="refpurpose"> — change the definition of a schema</span></dt><dt><span class="refentrytitle"><a href="sql-altersequence.html">ALTER SEQUENCE</a></span><span class="refpurpose"> —
+ change the definition of a sequence generator
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alterserver.html">ALTER SERVER</a></span><span class="refpurpose"> — change the definition of a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-alterstatistics.html">ALTER STATISTICS</a></span><span class="refpurpose"> —
+ change the definition of an extended statistics object
+ </span></dt><dt><span class="refentrytitle"><a href="sql-altersubscription.html">ALTER SUBSCRIPTION</a></span><span class="refpurpose"> — change the definition of a subscription</span></dt><dt><span class="refentrytitle"><a href="sql-altersystem.html">ALTER SYSTEM</a></span><span class="refpurpose"> — change a server configuration parameter</span></dt><dt><span class="refentrytitle"><a href="sql-altertable.html">ALTER TABLE</a></span><span class="refpurpose"> — change the definition of a table</span></dt><dt><span class="refentrytitle"><a href="sql-altertablespace.html">ALTER TABLESPACE</a></span><span class="refpurpose"> — change the definition of a tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-altertsconfig.html">ALTER TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — change the definition of a text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-altertsdictionary.html">ALTER TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — change the definition of a text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-altertsparser.html">ALTER TEXT SEARCH PARSER</a></span><span class="refpurpose"> — change the definition of a text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-altertstemplate.html">ALTER TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — change the definition of a text search template</span></dt><dt><span class="refentrytitle"><a href="sql-altertrigger.html">ALTER TRIGGER</a></span><span class="refpurpose"> — change the definition of a trigger</span></dt><dt><span class="refentrytitle"><a href="sql-altertype.html">ALTER TYPE</a></span><span class="refpurpose"> —
+ change the definition of a type
+ </span></dt><dt><span class="refentrytitle"><a href="sql-alteruser.html">ALTER USER</a></span><span class="refpurpose"> — change a database role</span></dt><dt><span class="refentrytitle"><a href="sql-alterusermapping.html">ALTER USER MAPPING</a></span><span class="refpurpose"> — change the definition of a user mapping</span></dt><dt><span class="refentrytitle"><a href="sql-alterview.html">ALTER VIEW</a></span><span class="refpurpose"> — change the definition of a view</span></dt><dt><span class="refentrytitle"><a href="sql-analyze.html">ANALYZE</a></span><span class="refpurpose"> — collect statistics about a database</span></dt><dt><span class="refentrytitle"><a href="sql-begin.html">BEGIN</a></span><span class="refpurpose"> — start a transaction block</span></dt><dt><span class="refentrytitle"><a href="sql-call.html">CALL</a></span><span class="refpurpose"> — invoke a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-checkpoint.html">CHECKPOINT</a></span><span class="refpurpose"> — force a write-ahead log checkpoint</span></dt><dt><span class="refentrytitle"><a href="sql-close.html">CLOSE</a></span><span class="refpurpose"> — close a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-cluster.html">CLUSTER</a></span><span class="refpurpose"> — cluster a table according to an index</span></dt><dt><span class="refentrytitle"><a href="sql-comment.html">COMMENT</a></span><span class="refpurpose"> — define or change the comment of an object</span></dt><dt><span class="refentrytitle"><a href="sql-commit.html">COMMIT</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-commit-prepared.html">COMMIT PREPARED</a></span><span class="refpurpose"> — commit a transaction that was earlier prepared for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-copy.html">COPY</a></span><span class="refpurpose"> — copy data between a file and a table</span></dt><dt><span class="refentrytitle"><a href="sql-create-access-method.html">CREATE ACCESS METHOD</a></span><span class="refpurpose"> — define a new access method</span></dt><dt><span class="refentrytitle"><a href="sql-createaggregate.html">CREATE AGGREGATE</a></span><span class="refpurpose"> — define a new aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-createcast.html">CREATE CAST</a></span><span class="refpurpose"> — define a new cast</span></dt><dt><span class="refentrytitle"><a href="sql-createcollation.html">CREATE COLLATION</a></span><span class="refpurpose"> — define a new collation</span></dt><dt><span class="refentrytitle"><a href="sql-createconversion.html">CREATE CONVERSION</a></span><span class="refpurpose"> — define a new encoding conversion</span></dt><dt><span class="refentrytitle"><a href="sql-createdatabase.html">CREATE DATABASE</a></span><span class="refpurpose"> — create a new database</span></dt><dt><span class="refentrytitle"><a href="sql-createdomain.html">CREATE DOMAIN</a></span><span class="refpurpose"> — define a new domain</span></dt><dt><span class="refentrytitle"><a href="sql-createeventtrigger.html">CREATE EVENT TRIGGER</a></span><span class="refpurpose"> — define a new event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-createextension.html">CREATE EXTENSION</a></span><span class="refpurpose"> — install an extension</span></dt><dt><span class="refentrytitle"><a href="sql-createforeigndatawrapper.html">CREATE FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — define a new foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-createforeigntable.html">CREATE FOREIGN TABLE</a></span><span class="refpurpose"> — define a new foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-createfunction.html">CREATE FUNCTION</a></span><span class="refpurpose"> — define a new function</span></dt><dt><span class="refentrytitle"><a href="sql-creategroup.html">CREATE GROUP</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createindex.html">CREATE INDEX</a></span><span class="refpurpose"> — define a new index</span></dt><dt><span class="refentrytitle"><a href="sql-createlanguage.html">CREATE LANGUAGE</a></span><span class="refpurpose"> — define a new procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-creatematerializedview.html">CREATE MATERIALIZED VIEW</a></span><span class="refpurpose"> — define a new materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-createoperator.html">CREATE OPERATOR</a></span><span class="refpurpose"> — define a new operator</span></dt><dt><span class="refentrytitle"><a href="sql-createopclass.html">CREATE OPERATOR CLASS</a></span><span class="refpurpose"> — define a new operator class</span></dt><dt><span class="refentrytitle"><a href="sql-createopfamily.html">CREATE OPERATOR FAMILY</a></span><span class="refpurpose"> — define a new operator family</span></dt><dt><span class="refentrytitle"><a href="sql-createpolicy.html">CREATE POLICY</a></span><span class="refpurpose"> — define a new row-level security policy for a table</span></dt><dt><span class="refentrytitle"><a href="sql-createprocedure.html">CREATE PROCEDURE</a></span><span class="refpurpose"> — define a new procedure</span></dt><dt><span class="refentrytitle"><a href="sql-createpublication.html">CREATE PUBLICATION</a></span><span class="refpurpose"> — define a new publication</span></dt><dt><span class="refentrytitle"><a href="sql-createrole.html">CREATE ROLE</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createrule.html">CREATE RULE</a></span><span class="refpurpose"> — define a new rewrite rule</span></dt><dt><span class="refentrytitle"><a href="sql-createschema.html">CREATE SCHEMA</a></span><span class="refpurpose"> — define a new schema</span></dt><dt><span class="refentrytitle"><a href="sql-createsequence.html">CREATE SEQUENCE</a></span><span class="refpurpose"> — define a new sequence generator</span></dt><dt><span class="refentrytitle"><a href="sql-createserver.html">CREATE SERVER</a></span><span class="refpurpose"> — define a new foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-createstatistics.html">CREATE STATISTICS</a></span><span class="refpurpose"> — define extended statistics</span></dt><dt><span class="refentrytitle"><a href="sql-createsubscription.html">CREATE SUBSCRIPTION</a></span><span class="refpurpose"> — define a new subscription</span></dt><dt><span class="refentrytitle"><a href="sql-createtable.html">CREATE TABLE</a></span><span class="refpurpose"> — define a new table</span></dt><dt><span class="refentrytitle"><a href="sql-createtableas.html">CREATE TABLE AS</a></span><span class="refpurpose"> — define a new table from the results of a query</span></dt><dt><span class="refentrytitle"><a href="sql-createtablespace.html">CREATE TABLESPACE</a></span><span class="refpurpose"> — define a new tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-createtsconfig.html">CREATE TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — define a new text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-createtsdictionary.html">CREATE TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — define a new text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-createtsparser.html">CREATE TEXT SEARCH PARSER</a></span><span class="refpurpose"> — define a new text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-createtstemplate.html">CREATE TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — define a new text search template</span></dt><dt><span class="refentrytitle"><a href="sql-createtransform.html">CREATE TRANSFORM</a></span><span class="refpurpose"> — define a new transform</span></dt><dt><span class="refentrytitle"><a href="sql-createtrigger.html">CREATE TRIGGER</a></span><span class="refpurpose"> — define a new trigger</span></dt><dt><span class="refentrytitle"><a href="sql-createtype.html">CREATE TYPE</a></span><span class="refpurpose"> — define a new data type</span></dt><dt><span class="refentrytitle"><a href="sql-createuser.html">CREATE USER</a></span><span class="refpurpose"> — define a new database role</span></dt><dt><span class="refentrytitle"><a href="sql-createusermapping.html">CREATE USER MAPPING</a></span><span class="refpurpose"> — define a new mapping of a user to a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-createview.html">CREATE VIEW</a></span><span class="refpurpose"> — define a new view</span></dt><dt><span class="refentrytitle"><a href="sql-deallocate.html">DEALLOCATE</a></span><span class="refpurpose"> — deallocate a prepared statement</span></dt><dt><span class="refentrytitle"><a href="sql-declare.html">DECLARE</a></span><span class="refpurpose"> — define a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-delete.html">DELETE</a></span><span class="refpurpose"> — delete rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-discard.html">DISCARD</a></span><span class="refpurpose"> — discard session state</span></dt><dt><span class="refentrytitle"><a href="sql-do.html">DO</a></span><span class="refpurpose"> — execute an anonymous code block</span></dt><dt><span class="refentrytitle"><a href="sql-drop-access-method.html">DROP ACCESS METHOD</a></span><span class="refpurpose"> — remove an access method</span></dt><dt><span class="refentrytitle"><a href="sql-dropaggregate.html">DROP AGGREGATE</a></span><span class="refpurpose"> — remove an aggregate function</span></dt><dt><span class="refentrytitle"><a href="sql-dropcast.html">DROP CAST</a></span><span class="refpurpose"> — remove a cast</span></dt><dt><span class="refentrytitle"><a href="sql-dropcollation.html">DROP COLLATION</a></span><span class="refpurpose"> — remove a collation</span></dt><dt><span class="refentrytitle"><a href="sql-dropconversion.html">DROP CONVERSION</a></span><span class="refpurpose"> — remove a conversion</span></dt><dt><span class="refentrytitle"><a href="sql-dropdatabase.html">DROP DATABASE</a></span><span class="refpurpose"> — remove a database</span></dt><dt><span class="refentrytitle"><a href="sql-dropdomain.html">DROP DOMAIN</a></span><span class="refpurpose"> — remove a domain</span></dt><dt><span class="refentrytitle"><a href="sql-dropeventtrigger.html">DROP EVENT TRIGGER</a></span><span class="refpurpose"> — remove an event trigger</span></dt><dt><span class="refentrytitle"><a href="sql-dropextension.html">DROP EXTENSION</a></span><span class="refpurpose"> — remove an extension</span></dt><dt><span class="refentrytitle"><a href="sql-dropforeigndatawrapper.html">DROP FOREIGN DATA WRAPPER</a></span><span class="refpurpose"> — remove a foreign-data wrapper</span></dt><dt><span class="refentrytitle"><a href="sql-dropforeigntable.html">DROP FOREIGN TABLE</a></span><span class="refpurpose"> — remove a foreign table</span></dt><dt><span class="refentrytitle"><a href="sql-dropfunction.html">DROP FUNCTION</a></span><span class="refpurpose"> — remove a function</span></dt><dt><span class="refentrytitle"><a href="sql-dropgroup.html">DROP GROUP</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-dropindex.html">DROP INDEX</a></span><span class="refpurpose"> — remove an index</span></dt><dt><span class="refentrytitle"><a href="sql-droplanguage.html">DROP LANGUAGE</a></span><span class="refpurpose"> — remove a procedural language</span></dt><dt><span class="refentrytitle"><a href="sql-dropmaterializedview.html">DROP MATERIALIZED VIEW</a></span><span class="refpurpose"> — remove a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-dropoperator.html">DROP OPERATOR</a></span><span class="refpurpose"> — remove an operator</span></dt><dt><span class="refentrytitle"><a href="sql-dropopclass.html">DROP OPERATOR CLASS</a></span><span class="refpurpose"> — remove an operator class</span></dt><dt><span class="refentrytitle"><a href="sql-dropopfamily.html">DROP OPERATOR FAMILY</a></span><span class="refpurpose"> — remove an operator family</span></dt><dt><span class="refentrytitle"><a href="sql-drop-owned.html">DROP OWNED</a></span><span class="refpurpose"> — remove database objects owned by a database role</span></dt><dt><span class="refentrytitle"><a href="sql-droppolicy.html">DROP POLICY</a></span><span class="refpurpose"> — remove a row-level security policy from a table</span></dt><dt><span class="refentrytitle"><a href="sql-dropprocedure.html">DROP PROCEDURE</a></span><span class="refpurpose"> — remove a procedure</span></dt><dt><span class="refentrytitle"><a href="sql-droppublication.html">DROP PUBLICATION</a></span><span class="refpurpose"> — remove a publication</span></dt><dt><span class="refentrytitle"><a href="sql-droprole.html">DROP ROLE</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-droproutine.html">DROP ROUTINE</a></span><span class="refpurpose"> — remove a routine</span></dt><dt><span class="refentrytitle"><a href="sql-droprule.html">DROP RULE</a></span><span class="refpurpose"> — remove a rewrite rule</span></dt><dt><span class="refentrytitle"><a href="sql-dropschema.html">DROP SCHEMA</a></span><span class="refpurpose"> — remove a schema</span></dt><dt><span class="refentrytitle"><a href="sql-dropsequence.html">DROP SEQUENCE</a></span><span class="refpurpose"> — remove a sequence</span></dt><dt><span class="refentrytitle"><a href="sql-dropserver.html">DROP SERVER</a></span><span class="refpurpose"> — remove a foreign server descriptor</span></dt><dt><span class="refentrytitle"><a href="sql-dropstatistics.html">DROP STATISTICS</a></span><span class="refpurpose"> — remove extended statistics</span></dt><dt><span class="refentrytitle"><a href="sql-dropsubscription.html">DROP SUBSCRIPTION</a></span><span class="refpurpose"> — remove a subscription</span></dt><dt><span class="refentrytitle"><a href="sql-droptable.html">DROP TABLE</a></span><span class="refpurpose"> — remove a table</span></dt><dt><span class="refentrytitle"><a href="sql-droptablespace.html">DROP TABLESPACE</a></span><span class="refpurpose"> — remove a tablespace</span></dt><dt><span class="refentrytitle"><a href="sql-droptsconfig.html">DROP TEXT SEARCH CONFIGURATION</a></span><span class="refpurpose"> — remove a text search configuration</span></dt><dt><span class="refentrytitle"><a href="sql-droptsdictionary.html">DROP TEXT SEARCH DICTIONARY</a></span><span class="refpurpose"> — remove a text search dictionary</span></dt><dt><span class="refentrytitle"><a href="sql-droptsparser.html">DROP TEXT SEARCH PARSER</a></span><span class="refpurpose"> — remove a text search parser</span></dt><dt><span class="refentrytitle"><a href="sql-droptstemplate.html">DROP TEXT SEARCH TEMPLATE</a></span><span class="refpurpose"> — remove a text search template</span></dt><dt><span class="refentrytitle"><a href="sql-droptransform.html">DROP TRANSFORM</a></span><span class="refpurpose"> — remove a transform</span></dt><dt><span class="refentrytitle"><a href="sql-droptrigger.html">DROP TRIGGER</a></span><span class="refpurpose"> — remove a trigger</span></dt><dt><span class="refentrytitle"><a href="sql-droptype.html">DROP TYPE</a></span><span class="refpurpose"> — remove a data type</span></dt><dt><span class="refentrytitle"><a href="sql-dropuser.html">DROP USER</a></span><span class="refpurpose"> — remove a database role</span></dt><dt><span class="refentrytitle"><a href="sql-dropusermapping.html">DROP USER MAPPING</a></span><span class="refpurpose"> — remove a user mapping for a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-dropview.html">DROP VIEW</a></span><span class="refpurpose"> — remove a view</span></dt><dt><span class="refentrytitle"><a href="sql-end.html">END</a></span><span class="refpurpose"> — commit the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-execute.html">EXECUTE</a></span><span class="refpurpose"> — execute a prepared statement</span></dt><dt><span class="refentrytitle"><a href="sql-explain.html">EXPLAIN</a></span><span class="refpurpose"> — show the execution plan of a statement</span></dt><dt><span class="refentrytitle"><a href="sql-fetch.html">FETCH</a></span><span class="refpurpose"> — retrieve rows from a query using a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-grant.html">GRANT</a></span><span class="refpurpose"> — define access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-importforeignschema.html">IMPORT FOREIGN SCHEMA</a></span><span class="refpurpose"> — import table definitions from a foreign server</span></dt><dt><span class="refentrytitle"><a href="sql-insert.html">INSERT</a></span><span class="refpurpose"> — create new rows in a table</span></dt><dt><span class="refentrytitle"><a href="sql-listen.html">LISTEN</a></span><span class="refpurpose"> — listen for a notification</span></dt><dt><span class="refentrytitle"><a href="sql-load.html">LOAD</a></span><span class="refpurpose"> — load a shared library file</span></dt><dt><span class="refentrytitle"><a href="sql-lock.html">LOCK</a></span><span class="refpurpose"> — lock a table</span></dt><dt><span class="refentrytitle"><a href="sql-merge.html">MERGE</a></span><span class="refpurpose"> — conditionally insert, update, or delete rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-move.html">MOVE</a></span><span class="refpurpose"> — position a cursor</span></dt><dt><span class="refentrytitle"><a href="sql-notify.html">NOTIFY</a></span><span class="refpurpose"> — generate a notification</span></dt><dt><span class="refentrytitle"><a href="sql-prepare.html">PREPARE</a></span><span class="refpurpose"> — prepare a statement for execution</span></dt><dt><span class="refentrytitle"><a href="sql-prepare-transaction.html">PREPARE TRANSACTION</a></span><span class="refpurpose"> — prepare the current transaction for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-reassign-owned.html">REASSIGN OWNED</a></span><span class="refpurpose"> — change the ownership of database objects owned by a database role</span></dt><dt><span class="refentrytitle"><a href="sql-refreshmaterializedview.html">REFRESH MATERIALIZED VIEW</a></span><span class="refpurpose"> — replace the contents of a materialized view</span></dt><dt><span class="refentrytitle"><a href="sql-reindex.html">REINDEX</a></span><span class="refpurpose"> — rebuild indexes</span></dt><dt><span class="refentrytitle"><a href="sql-release-savepoint.html">RELEASE SAVEPOINT</a></span><span class="refpurpose"> — destroy a previously defined savepoint</span></dt><dt><span class="refentrytitle"><a href="sql-reset.html">RESET</a></span><span class="refpurpose"> — restore the value of a run-time parameter to the default value</span></dt><dt><span class="refentrytitle"><a href="sql-revoke.html">REVOKE</a></span><span class="refpurpose"> — remove access privileges</span></dt><dt><span class="refentrytitle"><a href="sql-rollback.html">ROLLBACK</a></span><span class="refpurpose"> — abort the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-rollback-prepared.html">ROLLBACK PREPARED</a></span><span class="refpurpose"> — cancel a transaction that was earlier prepared for two-phase commit</span></dt><dt><span class="refentrytitle"><a href="sql-rollback-to.html">ROLLBACK TO SAVEPOINT</a></span><span class="refpurpose"> — roll back to a savepoint</span></dt><dt><span class="refentrytitle"><a href="sql-savepoint.html">SAVEPOINT</a></span><span class="refpurpose"> — define a new savepoint within the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-security-label.html">SECURITY LABEL</a></span><span class="refpurpose"> — define or change a security label applied to an object</span></dt><dt><span class="refentrytitle"><a href="sql-select.html">SELECT</a></span><span class="refpurpose"> — retrieve rows from a table or view</span></dt><dt><span class="refentrytitle"><a href="sql-selectinto.html">SELECT INTO</a></span><span class="refpurpose"> — define a new table from the results of a query</span></dt><dt><span class="refentrytitle"><a href="sql-set.html">SET</a></span><span class="refpurpose"> — change a run-time parameter</span></dt><dt><span class="refentrytitle"><a href="sql-set-constraints.html">SET CONSTRAINTS</a></span><span class="refpurpose"> — set constraint check timing for the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-set-role.html">SET ROLE</a></span><span class="refpurpose"> — set the current user identifier of the current session</span></dt><dt><span class="refentrytitle"><a href="sql-set-session-authorization.html">SET SESSION AUTHORIZATION</a></span><span class="refpurpose"> — set the session user identifier and the current user identifier of the current session</span></dt><dt><span class="refentrytitle"><a href="sql-set-transaction.html">SET TRANSACTION</a></span><span class="refpurpose"> — set the characteristics of the current transaction</span></dt><dt><span class="refentrytitle"><a href="sql-show.html">SHOW</a></span><span class="refpurpose"> — show the value of a run-time parameter</span></dt><dt><span class="refentrytitle"><a href="sql-start-transaction.html">START TRANSACTION</a></span><span class="refpurpose"> — start a transaction block</span></dt><dt><span class="refentrytitle"><a href="sql-truncate.html">TRUNCATE</a></span><span class="refpurpose"> — empty a table or set of tables</span></dt><dt><span class="refentrytitle"><a href="sql-unlisten.html">UNLISTEN</a></span><span class="refpurpose"> — stop listening for a notification</span></dt><dt><span class="refentrytitle"><a href="sql-update.html">UPDATE</a></span><span class="refpurpose"> — update rows of a table</span></dt><dt><span class="refentrytitle"><a href="sql-vacuum.html">VACUUM</a></span><span class="refpurpose"> — garbage-collect and optionally analyze a database</span></dt><dt><span class="refentrytitle"><a href="sql-values.html">VALUES</a></span><span class="refpurpose"> — compute a set of rows</span></dt></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reference.html" title="Part VI. Reference">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html" title="Part VI. Reference">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-abort.html" title="ABORT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VI. Reference </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ABORT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-comment.html b/doc/src/sgml/html/sql-comment.html
new file mode 100644
index 0000000..172a4dc
--- /dev/null
+++ b/doc/src/sgml/html/sql-comment.html
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COMMENT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-cluster.html" title="CLUSTER" /><link rel="next" href="sql-commit.html" title="COMMIT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COMMENT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-cluster.html" title="CLUSTER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-commit.html" title="COMMIT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-COMMENT"><div class="titlepage"></div><a id="id-1.9.3.52.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COMMENT</span></h2><p>COMMENT — define or change the comment of an object</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+COMMENT ON
+{
+ ACCESS METHOD <em class="replaceable"><code>object_name</code></em> |
+ AGGREGATE <em class="replaceable"><code>aggregate_name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) |
+ CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>) |
+ COLLATION <em class="replaceable"><code>object_name</code></em> |
+ COLUMN <em class="replaceable"><code>relation_name</code></em>.<em class="replaceable"><code>column_name</code></em> |
+ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
+ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ON DOMAIN <em class="replaceable"><code>domain_name</code></em> |
+ CONVERSION <em class="replaceable"><code>object_name</code></em> |
+ DATABASE <em class="replaceable"><code>object_name</code></em> |
+ DOMAIN <em class="replaceable"><code>object_name</code></em> |
+ EXTENSION <em class="replaceable"><code>object_name</code></em> |
+ EVENT TRIGGER <em class="replaceable"><code>object_name</code></em> |
+ FOREIGN DATA WRAPPER <em class="replaceable"><code>object_name</code></em> |
+ FOREIGN TABLE <em class="replaceable"><code>object_name</code></em> |
+ FUNCTION <em class="replaceable"><code>function_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ INDEX <em class="replaceable"><code>object_name</code></em> |
+ LARGE OBJECT <em class="replaceable"><code>large_object_oid</code></em> |
+ MATERIALIZED VIEW <em class="replaceable"><code>object_name</code></em> |
+ OPERATOR <em class="replaceable"><code>operator_name</code></em> (<em class="replaceable"><code>left_type</code></em>, <em class="replaceable"><code>right_type</code></em>) |
+ OPERATOR CLASS <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
+ OPERATOR FAMILY <em class="replaceable"><code>object_name</code></em> USING <em class="replaceable"><code>index_method</code></em> |
+ POLICY <em class="replaceable"><code>policy_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
+ [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>object_name</code></em> |
+ PROCEDURE <em class="replaceable"><code>procedure_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ PUBLICATION <em class="replaceable"><code>object_name</code></em> |
+ ROLE <em class="replaceable"><code>object_name</code></em> |
+ ROUTINE <em class="replaceable"><code>routine_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ RULE <em class="replaceable"><code>rule_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
+ SCHEMA <em class="replaceable"><code>object_name</code></em> |
+ SEQUENCE <em class="replaceable"><code>object_name</code></em> |
+ SERVER <em class="replaceable"><code>object_name</code></em> |
+ STATISTICS <em class="replaceable"><code>object_name</code></em> |
+ SUBSCRIPTION <em class="replaceable"><code>object_name</code></em> |
+ TABLE <em class="replaceable"><code>object_name</code></em> |
+ TABLESPACE <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH CONFIGURATION <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH DICTIONARY <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH PARSER <em class="replaceable"><code>object_name</code></em> |
+ TEXT SEARCH TEMPLATE <em class="replaceable"><code>object_name</code></em> |
+ TRANSFORM FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> |
+ TRIGGER <em class="replaceable"><code>trigger_name</code></em> ON <em class="replaceable"><code>table_name</code></em> |
+ TYPE <em class="replaceable"><code>object_name</code></em> |
+ VIEW <em class="replaceable"><code>object_name</code></em>
+} IS { <em class="replaceable"><code>string_literal</code></em> | NULL }
+
+<span class="phrase">where <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
+
+* |
+[ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
+[ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.52.5"><h2>Description</h2><p>
+ <code class="command">COMMENT</code> stores a comment about a database object.
+ </p><p>
+ Only one comment string is stored for each object, so to modify a comment,
+ issue a new <code class="command">COMMENT</code> command for the same object. To remove a
+ comment, write <code class="literal">NULL</code> in place of the text string.
+ Comments are automatically dropped when their object is dropped.
+ </p><p>
+ A <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock is acquired on the
+ object to be commented.
+ </p><p>
+ For most kinds of object, only the object's owner can set the comment.
+ Roles don't have owners, so the rule for <code class="literal">COMMENT ON ROLE</code> is
+ that you must be superuser to comment on a superuser role, or have the
+ <code class="literal">CREATEROLE</code> privilege to comment on non-superuser roles.
+ Likewise, access methods don't have owners either; you must be superuser
+ to comment on an access method.
+ Of course, a superuser can comment on anything.
+ </p><p>
+ Comments can be viewed using <span class="application">psql</span>'s
+ <code class="command">\d</code> family of commands.
+ Other user interfaces to retrieve comments can be built atop
+ the same built-in functions that <span class="application">psql</span> uses, namely
+ <code class="function">obj_description</code>, <code class="function">col_description</code>,
+ and <code class="function">shobj_description</code>
+ (see <a class="xref" href="functions-info.html#FUNCTIONS-INFO-COMMENT-TABLE" title="Table 9.77. Comment Information Functions">Table 9.77</a>).
+ </p></div><div class="refsect1" id="id-1.9.3.52.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>object_name</code></em><br /></span><span class="term"><em class="replaceable"><code>relation_name</code></em>.<em class="replaceable"><code>column_name</code></em><br /></span><span class="term"><em class="replaceable"><code>aggregate_name</code></em><br /></span><span class="term"><em class="replaceable"><code>constraint_name</code></em><br /></span><span class="term"><em class="replaceable"><code>function_name</code></em><br /></span><span class="term"><em class="replaceable"><code>operator_name</code></em><br /></span><span class="term"><em class="replaceable"><code>policy_name</code></em><br /></span><span class="term"><em class="replaceable"><code>procedure_name</code></em><br /></span><span class="term"><em class="replaceable"><code>routine_name</code></em><br /></span><span class="term"><em class="replaceable"><code>rule_name</code></em><br /></span><span class="term"><em class="replaceable"><code>trigger_name</code></em></span></dt><dd><p>
+ The name of the object to be commented. Names of objects that reside in
+ schemas (tables, functions, etc.) can be
+ schema-qualified. When commenting on a column,
+ <em class="replaceable"><code>relation_name</code></em> must refer
+ to a table, view, composite type, or foreign table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em><br /></span><span class="term"><em class="replaceable"><code>domain_name</code></em></span></dt><dd><p>
+ When creating a comment on a constraint, a trigger, a rule or
+ a policy these parameters specify the name of the table or domain on
+ which that object is defined.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_type</code></em></span></dt><dd><p>
+ The name of the source data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>target_type</code></em></span></dt><dd><p>
+ The name of the target data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of a function, procedure, or aggregate
+ argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Note that <code class="command">COMMENT</code> does not actually pay
+ any attention to <code class="literal">OUT</code> arguments, since only the input
+ arguments are needed to determine the function's identity.
+ So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
+ and <code class="literal">VARIADIC</code> arguments.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of a function, procedure, or aggregate argument.
+ Note that <code class="command">COMMENT</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type of a function, procedure, or aggregate argument.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>large_object_oid</code></em></span></dt><dd><p>
+ The OID of the large object.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em><br /></span><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
+ The data type(s) of the operator's arguments (optionally
+ schema-qualified). Write <code class="literal">NONE</code> for the missing argument
+ of a prefix operator.
+ </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p>
+ This is a noise word.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
+ The name of the data type of the transform.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language of the transform.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>string_literal</code></em></span></dt><dd><p>
+ The new comment contents, written as a string literal.
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ Write <code class="literal">NULL</code> to drop the comment.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.52.7"><h2>Notes</h2><p>
+ There is presently no security mechanism for viewing comments: any user
+ connected to a database can see all the comments for objects in
+ that database. For shared objects such as
+ databases, roles, and tablespaces, comments are stored globally so any
+ user connected to any database in the cluster can see all the comments
+ for shared objects. Therefore, don't put security-critical
+ information in comments.
+ </p></div><div class="refsect1" id="id-1.9.3.52.8"><h2>Examples</h2><p>
+ Attach a comment to the table <code class="literal">mytable</code>:
+
+</p><pre class="programlisting">
+COMMENT ON TABLE mytable IS 'This is my table.';
+</pre><p>
+
+ Remove it again:
+
+</p><pre class="programlisting">
+COMMENT ON TABLE mytable IS NULL;
+</pre><p>
+ </p><p>
+ Some more examples:
+
+</p><pre class="programlisting">
+COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
+COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
+COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
+COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
+COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
+COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
+COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
+COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';
+COMMENT ON DATABASE my_database IS 'Development Database';
+COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
+COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
+COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
+COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
+COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
+COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
+COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
+COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
+COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
+COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
+COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
+COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
+COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
+COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
+COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
+COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
+COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
+COMMENT ON ROLE my_role IS 'Administration group for finance tables';
+COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';
+COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
+COMMENT ON SCHEMA my_schema IS 'Departmental data';
+COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
+COMMENT ON SERVER myserver IS 'my foreign server';
+COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
+COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';
+COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
+COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
+COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
+COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';
+COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
+COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
+COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';
+COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
+COMMENT ON TYPE complex IS 'Complex number data type';
+COMMENT ON VIEW my_view IS 'View of departmental costs';
+</pre></div><div class="refsect1" id="id-1.9.3.52.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">COMMENT</code> command in the SQL standard.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-cluster.html" title="CLUSTER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-commit.html" title="COMMIT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CLUSTER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMIT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-commit-prepared.html b/doc/src/sgml/html/sql-commit-prepared.html
new file mode 100644
index 0000000..eb81c31
--- /dev/null
+++ b/doc/src/sgml/html/sql-commit-prepared.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COMMIT PREPARED</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-commit.html" title="COMMIT" /><link rel="next" href="sql-copy.html" title="COPY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COMMIT PREPARED</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-commit.html" title="COMMIT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-copy.html" title="COPY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-COMMIT-PREPARED"><div class="titlepage"></div><a id="id-1.9.3.54.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COMMIT PREPARED</span></h2><p>COMMIT PREPARED — commit a transaction that was earlier prepared for two-phase commit</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+COMMIT PREPARED <em class="replaceable"><code>transaction_id</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.54.5"><h2>Description</h2><p>
+ <code class="command">COMMIT PREPARED</code> commits a transaction that is in
+ prepared state.
+ </p></div><div class="refsect1" id="id-1.9.3.54.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ The transaction identifier of the transaction that is to be
+ committed.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.54.7"><h2>Notes</h2><p>
+ To commit a prepared transaction, you must be either the same user that
+ executed the transaction originally, or a superuser. But you do not
+ have to be in the same session that executed the transaction.
+ </p><p>
+ This command cannot be executed inside a transaction block. The prepared
+ transaction is committed immediately.
+ </p><p>
+ All currently available prepared transactions are listed in the
+ <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a>
+ system view.
+ </p></div><div class="refsect1" id="SQL-COMMIT-PREPARED-EXAMPLES"><h2>Examples</h2><p>
+ Commit the transaction identified by the transaction
+ identifier <code class="literal">foobar</code>:
+
+</p><pre class="programlisting">
+COMMIT PREPARED 'foobar';
+</pre></div><div class="refsect1" id="id-1.9.3.54.9"><h2>Compatibility</h2><p>
+ <code class="command">COMMIT PREPARED</code> is a
+ <span class="productname">PostgreSQL</span> extension. It is intended for use by
+ external transaction management systems, some of which are covered by
+ standards (such as X/Open XA), but the SQL side of those systems is not
+ standardized.
+ </p></div><div class="refsect1" id="id-1.9.3.54.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>, <a class="xref" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED"><span class="refentrytitle">ROLLBACK PREPARED</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-commit.html" title="COMMIT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-copy.html" title="COPY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">COMMIT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COPY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-commit.html b/doc/src/sgml/html/sql-commit.html
new file mode 100644
index 0000000..05952cc
--- /dev/null
+++ b/doc/src/sgml/html/sql-commit.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COMMIT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-comment.html" title="COMMENT" /><link rel="next" href="sql-commit-prepared.html" title="COMMIT PREPARED" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COMMIT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-comment.html" title="COMMENT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-commit-prepared.html" title="COMMIT PREPARED">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-COMMIT"><div class="titlepage"></div><a id="id-1.9.3.53.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COMMIT</span></h2><p>COMMIT — commit the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
+</pre></div><div class="refsect1" id="id-1.9.3.53.5"><h2>Description</h2><p>
+ <code class="command">COMMIT</code> commits the current transaction. All
+ changes made by the transaction become visible to others
+ and are guaranteed to be durable if a crash occurs.
+ </p></div><div class="refsect1" id="id-1.9.3.53.6"><h2>Parameters</h2><a id="id-1.9.3.53.6.2" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">WORK</code><br /></span><span class="term"><code class="literal">TRANSACTION</code></span></dt><dd><p>
+ Optional key words. They have no effect.
+ </p></dd><dt id="SQL-COMMIT-CHAIN"><span class="term"><code class="literal">AND CHAIN</code></span></dt><dd><p>
+ If <code class="literal">AND CHAIN</code> is specified, a new transaction is
+ immediately started with the same transaction characteristics (see <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a>) as the just finished one. Otherwise,
+ no new transaction is started.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.53.7"><h2>Notes</h2><p>
+ Use <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a> to
+ abort a transaction.
+ </p><p>
+ Issuing <code class="command">COMMIT</code> when not inside a transaction does
+ no harm, but it will provoke a warning message. <code class="command">COMMIT AND
+ CHAIN</code> when not inside a transaction is an error.
+ </p></div><div class="refsect1" id="id-1.9.3.53.8"><h2>Examples</h2><p>
+ To commit the current transaction and make all changes permanent:
+</p><pre class="programlisting">
+COMMIT;
+</pre></div><div class="refsect1" id="id-1.9.3.53.9"><h2>Compatibility</h2><p>
+ The command <code class="command">COMMIT</code> conforms to the SQL standard. The
+ form <code class="literal">COMMIT TRANSACTION</code> is a PostgreSQL extension.
+ </p></div><div class="refsect1" id="id-1.9.3.53.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-comment.html" title="COMMENT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-commit-prepared.html" title="COMMIT PREPARED">Next</a></td></tr><tr><td width="40%" align="left" valign="top">COMMENT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> COMMIT PREPARED</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-copy.html b/doc/src/sgml/html/sql-copy.html
new file mode 100644
index 0000000..b3dca10
--- /dev/null
+++ b/doc/src/sgml/html/sql-copy.html
@@ -0,0 +1,641 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COPY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-commit-prepared.html" title="COMMIT PREPARED" /><link rel="next" href="sql-create-access-method.html" title="CREATE ACCESS METHOD" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COPY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-commit-prepared.html" title="COMMIT PREPARED">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-COPY"><div class="titlepage"></div><a id="id-1.9.3.55.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COPY</span></h2><p>COPY — copy data between a file and a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+COPY <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ FROM { '<em class="replaceable"><code>filename</code></em>' | PROGRAM '<em class="replaceable"><code>command</code></em>' | STDIN }
+ [ [ WITH ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+ [ WHERE <em class="replaceable"><code>condition</code></em> ]
+
+COPY { <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ] | ( <em class="replaceable"><code>query</code></em> ) }
+ TO { '<em class="replaceable"><code>filename</code></em>' | PROGRAM '<em class="replaceable"><code>command</code></em>' | STDOUT }
+ [ [ WITH ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ FORMAT <em class="replaceable"><code>format_name</code></em>
+ FREEZE [ <em class="replaceable"><code>boolean</code></em> ]
+ DELIMITER '<em class="replaceable"><code>delimiter_character</code></em>'
+ NULL '<em class="replaceable"><code>null_string</code></em>'
+ HEADER [ <em class="replaceable"><code>boolean</code></em> | MATCH ]
+ QUOTE '<em class="replaceable"><code>quote_character</code></em>'
+ ESCAPE '<em class="replaceable"><code>escape_character</code></em>'
+ FORCE_QUOTE { ( <em class="replaceable"><code>column_name</code></em> [, ...] ) | * }
+ FORCE_NOT_NULL ( <em class="replaceable"><code>column_name</code></em> [, ...] )
+ FORCE_NULL ( <em class="replaceable"><code>column_name</code></em> [, ...] )
+ ENCODING '<em class="replaceable"><code>encoding_name</code></em>'
+</pre></div><div class="refsect1" id="id-1.9.3.55.5"><h2>Description</h2><p>
+ <code class="command">COPY</code> moves data between
+ <span class="productname">PostgreSQL</span> tables and standard file-system
+ files. <code class="command">COPY TO</code> copies the contents of a table
+ <span class="emphasis"><em>to</em></span> a file, while <code class="command">COPY FROM</code> copies
+ data <span class="emphasis"><em>from</em></span> a file to a table (appending the data to
+ whatever is in the table already). <code class="command">COPY TO</code>
+ can also copy the results of a <code class="command">SELECT</code> query.
+ </p><p>
+ If a column list is specified, <code class="command">COPY TO</code> copies only
+ the data in the specified columns to the file. For <code class="command">COPY
+ FROM</code>, each field in the file is inserted, in order, into the
+ specified column. Table columns not specified in the <code class="command">COPY
+ FROM</code> column list will receive their default values.
+ </p><p>
+ <code class="command">COPY</code> with a file name instructs the
+ <span class="productname">PostgreSQL</span> server to directly read from
+ or write to a file. The file must be accessible by the
+ <span class="productname">PostgreSQL</span> user (the user ID the server
+ runs as) and the name must be specified from the viewpoint of the
+ server. When <code class="literal">PROGRAM</code> is specified, the server
+ executes the given command and reads from the standard output of the
+ program, or writes to the standard input of the program. The command
+ must be specified from the viewpoint of the server, and be executable
+ by the <span class="productname">PostgreSQL</span> user. When
+ <code class="literal">STDIN</code> or <code class="literal">STDOUT</code> is
+ specified, data is transmitted via the connection between the
+ client and the server.
+ </p><p>
+ Each backend running <code class="command">COPY</code> will report its progress
+ in the <code class="structname">pg_stat_progress_copy</code> view. See
+ <a class="xref" href="progress-reporting.html#COPY-PROGRESS-REPORTING" title="28.4.6. COPY Progress Reporting">Section 28.4.6</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.55.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ An optional list of columns to be copied. If no column list is
+ specified, all columns of the table except generated columns will be
+ copied.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a>,
+ <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a>,
+ <a class="link" href="sql-insert.html" title="INSERT"><code class="command">INSERT</code></a>,
+ <a class="link" href="sql-update.html" title="UPDATE"><code class="command">UPDATE</code></a>, or
+ <a class="link" href="sql-delete.html" title="DELETE"><code class="command">DELETE</code></a> command whose results are to be
+ copied. Note that parentheses are required around the query.
+ </p><p>
+ For <code class="command">INSERT</code>, <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code> queries a RETURNING clause must be provided,
+ and the target relation must not have a conditional rule, nor
+ an <code class="literal">ALSO</code> rule, nor an <code class="literal">INSTEAD</code> rule
+ that expands to multiple statements.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>filename</code></em></span></dt><dd><p>
+ The path name of the input or output file. An input file name can be
+ an absolute or relative path, but an output file name must be an absolute
+ path. Windows users might need to use an <code class="literal">E''</code> string and
+ double any backslashes used in the path name.
+ </p></dd><dt><span class="term"><code class="literal">PROGRAM</code></span></dt><dd><p>
+ A command to execute. In <code class="command">COPY FROM</code>, the input is
+ read from standard output of the command, and in <code class="command">COPY TO</code>,
+ the output is written to the standard input of the command.
+ </p><p>
+ Note that the command is invoked by the shell, so if you need to pass
+ any arguments to shell command that come from an untrusted source, you
+ must be careful to strip or escape any special characters that might
+ have a special meaning for the shell. For security reasons, it is best
+ to use a fixed command string, or at least avoid passing any user input
+ in it.
+ </p></dd><dt><span class="term"><code class="literal">STDIN</code></span></dt><dd><p>
+ Specifies that input comes from the client application.
+ </p></dd><dt><span class="term"><code class="literal">STDOUT</code></span></dt><dd><p>
+ Specifies that output goes to the client application.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd><dt><span class="term"><code class="literal">FORMAT</code></span></dt><dd><p>
+ Selects the data format to be read or written:
+ <code class="literal">text</code>,
+ <code class="literal">csv</code> (Comma Separated Values),
+ or <code class="literal">binary</code>.
+ The default is <code class="literal">text</code>.
+ </p></dd><dt><span class="term"><code class="literal">FREEZE</code></span></dt><dd><p>
+ Requests copying the data with rows already frozen, just as they
+ would be after running the <code class="command">VACUUM FREEZE</code> command.
+ This is intended as a performance option for initial data loading.
+ Rows will be frozen only if the table being loaded has been created
+ or truncated in the current subtransaction, there are no cursors
+ open and there are no older snapshots held by this transaction. It is
+ currently not possible to perform a <code class="command">COPY FREEZE</code> on
+ a partitioned table.
+ </p><p>
+ Note that all other sessions will immediately be able to see the data
+ once it has been successfully loaded. This violates the normal rules
+ of MVCC visibility and users specifying should be aware of the
+ potential problems this might cause.
+ </p></dd><dt><span class="term"><code class="literal">DELIMITER</code></span></dt><dd><p>
+ Specifies the character that separates columns within each row
+ (line) of the file. The default is a tab character in text format,
+ a comma in <code class="literal">CSV</code> format.
+ This must be a single one-byte character.
+ This option is not allowed when using <code class="literal">binary</code> format.
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ Specifies the string that represents a null value. The default is
+ <code class="literal">\N</code> (backslash-N) in text format, and an unquoted empty
+ string in <code class="literal">CSV</code> format. You might prefer an
+ empty string even in text format for cases where you don't want to
+ distinguish nulls from empty strings.
+ This option is not allowed when using <code class="literal">binary</code> format.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When using <code class="command">COPY FROM</code>, any data item that matches
+ this string will be stored as a null value, so you should make
+ sure that you use the same string as you used with
+ <code class="command">COPY TO</code>.
+ </p></div></dd><dt><span class="term"><code class="literal">HEADER</code></span></dt><dd><p>
+ Specifies that the file contains a header line with the names of each
+ column in the file. On output, the first line contains the column
+ names from the table. On input, the first line is discarded when this
+ option is set to <code class="literal">true</code> (or equivalent Boolean value).
+ If this option is set to <code class="literal">MATCH</code>, the number and names
+ of the columns in the header line must match the actual column names of
+ the table, in order; otherwise an error is raised.
+ This option is not allowed when using <code class="literal">binary</code> format.
+ The <code class="literal">MATCH</code> option is only valid for <code class="command">COPY
+ FROM</code> commands.
+ </p></dd><dt><span class="term"><code class="literal">QUOTE</code></span></dt><dd><p>
+ Specifies the quoting character to be used when a data value is quoted.
+ The default is double-quote.
+ This must be a single one-byte character.
+ This option is allowed only when using <code class="literal">CSV</code> format.
+ </p></dd><dt><span class="term"><code class="literal">ESCAPE</code></span></dt><dd><p>
+ Specifies the character that should appear before a
+ data character that matches the <code class="literal">QUOTE</code> value.
+ The default is the same as the <code class="literal">QUOTE</code> value (so that
+ the quoting character is doubled if it appears in the data).
+ This must be a single one-byte character.
+ This option is allowed only when using <code class="literal">CSV</code> format.
+ </p></dd><dt><span class="term"><code class="literal">FORCE_QUOTE</code></span></dt><dd><p>
+ Forces quoting to be
+ used for all non-<code class="literal">NULL</code> values in each specified column.
+ <code class="literal">NULL</code> output is never quoted. If <code class="literal">*</code> is specified,
+ non-<code class="literal">NULL</code> values will be quoted in all columns.
+ This option is allowed only in <code class="command">COPY TO</code>, and only when
+ using <code class="literal">CSV</code> format.
+ </p></dd><dt><span class="term"><code class="literal">FORCE_NOT_NULL</code></span></dt><dd><p>
+ Do not match the specified columns' values against the null string.
+ In the default case where the null string is empty, this means that
+ empty values will be read as zero-length strings rather than nulls,
+ even when they are not quoted.
+ This option is allowed only in <code class="command">COPY FROM</code>, and only when
+ using <code class="literal">CSV</code> format.
+ </p></dd><dt><span class="term"><code class="literal">FORCE_NULL</code></span></dt><dd><p>
+ Match the specified columns' values against the null string, even
+ if it has been quoted, and if a match is found set the value to
+ <code class="literal">NULL</code>. In the default case where the null string is empty,
+ this converts a quoted empty string into NULL.
+ This option is allowed only in <code class="command">COPY FROM</code>, and only when
+ using <code class="literal">CSV</code> format.
+ </p></dd><dt><span class="term"><code class="literal">ENCODING</code></span></dt><dd><p>
+ Specifies that the file is encoded in the <em class="replaceable"><code>encoding_name</code></em>. If this option is
+ omitted, the current client encoding is used. See the Notes below
+ for more details.
+ </p></dd><dt><span class="term"><code class="literal">WHERE</code></span></dt><dd><p>
+ The optional <code class="literal">WHERE</code> clause has the general form
+</p><pre class="synopsis">
+WHERE <em class="replaceable"><code>condition</code></em>
+</pre><p>
+ where <em class="replaceable"><code>condition</code></em> is
+ any expression that evaluates to a result of type
+ <code class="type">boolean</code>. Any row that does not satisfy this
+ condition will not be inserted to the table. A row satisfies the
+ condition if it returns true when the actual row values are
+ substituted for any variable references.
+ </p><p>
+ Currently, subqueries are not allowed in <code class="literal">WHERE</code>
+ expressions, and the evaluation does not see any changes made by the
+ <code class="command">COPY</code> itself (this matters when the expression
+ contains calls to <code class="literal">VOLATILE</code> functions).
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.55.7"><h2>Outputs</h2><p>
+ On successful completion, a <code class="command">COPY</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+COPY <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number
+ of rows copied.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="application">psql</span> will print this command tag only if the command
+ was not <code class="literal">COPY ... TO STDOUT</code>, or the
+ equivalent <span class="application">psql</span> meta-command
+ <code class="literal">\copy ... to stdout</code>. This is to prevent confusing the
+ command tag with the data that was just printed.
+ </p></div></div><div class="refsect1" id="id-1.9.3.55.8"><h2>Notes</h2><p>
+ <code class="command">COPY TO</code> can be used only with plain
+ tables, not views, and does not copy rows from child tables
+ or child partitions. For example, <code class="literal">COPY <em class="replaceable"><code>table</code></em> TO</code> copies
+ the same rows as <code class="literal">SELECT * FROM ONLY <em class="replaceable"><code>table</code></em></code>.
+ The syntax <code class="literal">COPY (SELECT * FROM <em class="replaceable"><code>table</code></em>) TO ...</code> can be used to
+ dump all of the rows in an inheritance hierarchy, partitioned table,
+ or view.
+ </p><p>
+ <code class="command">COPY FROM</code> can be used with plain, foreign, or
+ partitioned tables or with views that have
+ <code class="literal">INSTEAD OF INSERT</code> triggers.
+ </p><p>
+ You must have select privilege on the table
+ whose values are read by <code class="command">COPY TO</code>, and
+ insert privilege on the table into which values
+ are inserted by <code class="command">COPY FROM</code>. It is sufficient
+ to have column privileges on the column(s) listed in the command.
+ </p><p>
+ If row-level security is enabled for the table, the relevant
+ <code class="command">SELECT</code> policies will apply to <code class="literal">COPY
+ <em class="replaceable"><code>table</code></em> TO</code> statements.
+ Currently, <code class="command">COPY FROM</code> is not supported for tables
+ with row-level security. Use equivalent <code class="command">INSERT</code>
+ statements instead.
+ </p><p>
+ Files named in a <code class="command">COPY</code> command are read or written
+ directly by the server, not by the client application. Therefore,
+ they must reside on or be accessible to the database server machine,
+ not the client. They must be accessible to and readable or writable
+ by the <span class="productname">PostgreSQL</span> user (the user ID the
+ server runs as), not the client. Similarly,
+ the command specified with <code class="literal">PROGRAM</code> is executed directly
+ by the server, not by the client application, must be executable by the
+ <span class="productname">PostgreSQL</span> user.
+ <code class="command">COPY</code> naming a file or command is only allowed to
+ database superusers or users who are granted one of the roles
+ <code class="literal">pg_read_server_files</code>,
+ <code class="literal">pg_write_server_files</code>,
+ or <code class="literal">pg_execute_server_program</code>, since it allows reading
+ or writing any file or running a program that the server has privileges to
+ access.
+ </p><p>
+ Do not confuse <code class="command">COPY</code> with the
+ <span class="application">psql</span> instruction
+ <code class="command"><a class="link" href="app-psql.html#APP-PSQL-META-COMMANDS-COPY">\copy</a></code>. <code class="command">\copy</code> invokes
+ <code class="command">COPY FROM STDIN</code> or <code class="command">COPY TO
+ STDOUT</code>, and then fetches/stores the data in a file
+ accessible to the <span class="application">psql</span> client. Thus,
+ file accessibility and access rights depend on the client rather
+ than the server when <code class="command">\copy</code> is used.
+ </p><p>
+ It is recommended that the file name used in <code class="command">COPY</code>
+ always be specified as an absolute path. This is enforced by the
+ server in the case of <code class="command">COPY TO</code>, but for
+ <code class="command">COPY FROM</code> you do have the option of reading from
+ a file specified by a relative path. The path will be interpreted
+ relative to the working directory of the server process (normally
+ the cluster's data directory), not the client's working directory.
+ </p><p>
+ Executing a command with <code class="literal">PROGRAM</code> might be restricted
+ by the operating system's access control mechanisms, such as SELinux.
+ </p><p>
+ <code class="command">COPY FROM</code> will invoke any triggers and check
+ constraints on the destination table. However, it will not invoke rules.
+ </p><p>
+ For identity columns, the <code class="command">COPY FROM</code> command will always
+ write the column values provided in the input data, like
+ the <code class="command">INSERT</code> option <code class="literal">OVERRIDING SYSTEM
+ VALUE</code>.
+ </p><p>
+ <code class="command">COPY</code> input and output is affected by
+ <code class="varname">DateStyle</code>. To ensure portability to other
+ <span class="productname">PostgreSQL</span> installations that might use
+ non-default <code class="varname">DateStyle</code> settings,
+ <code class="varname">DateStyle</code> should be set to <code class="literal">ISO</code> before
+ using <code class="command">COPY TO</code>. It is also a good idea to avoid dumping
+ data with <code class="varname">IntervalStyle</code> set to
+ <code class="literal">sql_standard</code>, because negative interval values might be
+ misinterpreted by a server that has a different setting for
+ <code class="varname">IntervalStyle</code>.
+ </p><p>
+ Input data is interpreted according to <code class="literal">ENCODING</code>
+ option or the current client encoding, and output data is encoded
+ in <code class="literal">ENCODING</code> or the current client encoding, even
+ if the data does not pass through the client but is read from or
+ written to a file directly by the server.
+ </p><p>
+ <code class="command">COPY</code> stops operation at the first error. This
+ should not lead to problems in the event of a <code class="command">COPY
+ TO</code>, but the target table will already have received
+ earlier rows in a <code class="command">COPY FROM</code>. These rows will not
+ be visible or accessible, but they still occupy disk space. This might
+ amount to a considerable amount of wasted disk space if the failure
+ happened well into a large copy operation. You might wish to invoke
+ <code class="command">VACUUM</code> to recover the wasted space.
+ </p><p>
+ <code class="literal">FORCE_NULL</code> and <code class="literal">FORCE_NOT_NULL</code> can be used
+ simultaneously on the same column. This results in converting quoted
+ null strings to null values and unquoted null strings to empty strings.
+ </p></div><div class="refsect1" id="id-1.9.3.55.9"><h2>File Formats</h2><div class="refsect2" id="id-1.9.3.55.9.2"><h3>Text Format</h3><p>
+ When the <code class="literal">text</code> format is used,
+ the data read or written is a text file with one line per table row.
+ Columns in a row are separated by the delimiter character.
+ The column values themselves are strings generated by the
+ output function, or acceptable to the input function, of each
+ attribute's data type. The specified null string is used in
+ place of columns that are null.
+ <code class="command">COPY FROM</code> will raise an error if any line of the
+ input file contains more or fewer columns than are expected.
+ </p><p>
+ End of data can be represented by a single line containing just
+ backslash-period (<code class="literal">\.</code>). An end-of-data marker is
+ not necessary when reading from a file, since the end of file
+ serves perfectly well; it is needed only when copying data to or from
+ client applications using pre-3.0 client protocol.
+ </p><p>
+ Backslash characters (<code class="literal">\</code>) can be used in the
+ <code class="command">COPY</code> data to quote data characters that might
+ otherwise be taken as row or column delimiters. In particular, the
+ following characters <span class="emphasis"><em>must</em></span> be preceded by a backslash if
+ they appear as part of a column value: backslash itself,
+ newline, carriage return, and the current delimiter character.
+ </p><p>
+ The specified null string is sent by <code class="command">COPY TO</code> without
+ adding any backslashes; conversely, <code class="command">COPY FROM</code> matches
+ the input against the null string before removing backslashes. Therefore,
+ a null string such as <code class="literal">\N</code> cannot be confused with
+ the actual data value <code class="literal">\N</code> (which would be represented
+ as <code class="literal">\\N</code>).
+ </p><p>
+ The following special backslash sequences are recognized by
+ <code class="command">COPY FROM</code>:
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Sequence</th><th>Represents</th></tr></thead><tbody><tr><td><code class="literal">\b</code></td><td>Backspace (ASCII 8)</td></tr><tr><td><code class="literal">\f</code></td><td>Form feed (ASCII 12)</td></tr><tr><td><code class="literal">\n</code></td><td>Newline (ASCII 10)</td></tr><tr><td><code class="literal">\r</code></td><td>Carriage return (ASCII 13)</td></tr><tr><td><code class="literal">\t</code></td><td>Tab (ASCII 9)</td></tr><tr><td><code class="literal">\v</code></td><td>Vertical tab (ASCII 11)</td></tr><tr><td><code class="literal">\</code><em class="replaceable"><code>digits</code></em></td><td>Backslash followed by one to three octal digits specifies
+ the byte with that numeric code</td></tr><tr><td><code class="literal">\x</code><em class="replaceable"><code>digits</code></em></td><td>Backslash <code class="literal">x</code> followed by one or two hex digits specifies
+ the byte with that numeric code</td></tr></tbody></table></div><p>
+
+ Presently, <code class="command">COPY TO</code> will never emit an octal or
+ hex-digits backslash sequence, but it does use the other sequences
+ listed above for those control characters.
+ </p><p>
+ Any other backslashed character that is not mentioned in the above table
+ will be taken to represent itself. However, beware of adding backslashes
+ unnecessarily, since that might accidentally produce a string matching the
+ end-of-data marker (<code class="literal">\.</code>) or the null string (<code class="literal">\N</code> by
+ default). These strings will be recognized before any other backslash
+ processing is done.
+ </p><p>
+ It is strongly recommended that applications generating <code class="command">COPY</code> data convert
+ data newlines and carriage returns to the <code class="literal">\n</code> and
+ <code class="literal">\r</code> sequences respectively. At present it is
+ possible to represent a data carriage return by a backslash and carriage
+ return, and to represent a data newline by a backslash and newline.
+ However, these representations might not be accepted in future releases.
+ They are also highly vulnerable to corruption if the <code class="command">COPY</code> file is
+ transferred across different machines (for example, from Unix to Windows
+ or vice versa).
+ </p><p>
+ All backslash sequences are interpreted after encoding conversion.
+ The bytes specified with the octal and hex-digit backslash sequences must
+ form valid characters in the database encoding.
+ </p><p>
+ <code class="command">COPY TO</code> will terminate each row with a Unix-style
+ newline (<span class="quote">“<span class="quote"><code class="literal">\n</code></span>”</span>). Servers running on Microsoft Windows instead
+ output carriage return/newline (<span class="quote">“<span class="quote"><code class="literal">\r\n</code></span>”</span>), but only for
+ <code class="command">COPY</code> to a server file; for consistency across platforms,
+ <code class="command">COPY TO STDOUT</code> always sends <span class="quote">“<span class="quote"><code class="literal">\n</code></span>”</span>
+ regardless of server platform.
+ <code class="command">COPY FROM</code> can handle lines ending with newlines,
+ carriage returns, or carriage return/newlines. To reduce the risk of
+ error due to un-backslashed newlines or carriage returns that were
+ meant as data, <code class="command">COPY FROM</code> will complain if the line
+ endings in the input are not all alike.
+ </p></div><div class="refsect2" id="id-1.9.3.55.9.3"><h3>CSV Format</h3><p>
+ This format option is used for importing and exporting the Comma
+ Separated Value (<code class="literal">CSV</code>) file format used by many other
+ programs, such as spreadsheets. Instead of the escaping rules used by
+ <span class="productname">PostgreSQL</span>'s standard text format, it
+ produces and recognizes the common CSV escaping mechanism.
+ </p><p>
+ The values in each record are separated by the <code class="literal">DELIMITER</code>
+ character. If the value contains the delimiter character, the
+ <code class="literal">QUOTE</code> character, the <code class="literal">NULL</code> string, a carriage
+ return, or line feed character, then the whole value is prefixed and
+ suffixed by the <code class="literal">QUOTE</code> character, and any occurrence
+ within the value of a <code class="literal">QUOTE</code> character or the
+ <code class="literal">ESCAPE</code> character is preceded by the escape character.
+ You can also use <code class="literal">FORCE_QUOTE</code> to force quotes when outputting
+ non-<code class="literal">NULL</code> values in specific columns.
+ </p><p>
+ The <code class="literal">CSV</code> format has no standard way to distinguish a
+ <code class="literal">NULL</code> value from an empty string.
+ <span class="productname">PostgreSQL</span>'s <code class="command">COPY</code> handles this by quoting.
+ A <code class="literal">NULL</code> is output as the <code class="literal">NULL</code> parameter string
+ and is not quoted, while a non-<code class="literal">NULL</code> value matching the
+ <code class="literal">NULL</code> parameter string is quoted. For example, with the
+ default settings, a <code class="literal">NULL</code> is written as an unquoted empty
+ string, while an empty string data value is written with double quotes
+ (<code class="literal">""</code>). Reading values follows similar rules. You can
+ use <code class="literal">FORCE_NOT_NULL</code> to prevent <code class="literal">NULL</code> input
+ comparisons for specific columns. You can also use
+ <code class="literal">FORCE_NULL</code> to convert quoted null string data values to
+ <code class="literal">NULL</code>.
+ </p><p>
+ Because backslash is not a special character in the <code class="literal">CSV</code>
+ format, <code class="literal">\.</code>, the end-of-data marker, could also appear
+ as a data value. To avoid any misinterpretation, a <code class="literal">\.</code>
+ data value appearing as a lone entry on a line is automatically
+ quoted on output, and on input, if quoted, is not interpreted as the
+ end-of-data marker. If you are loading a file created by another
+ application that has a single unquoted column and might have a
+ value of <code class="literal">\.</code>, you might need to quote that value in the
+ input file.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In <code class="literal">CSV</code> format, all characters are significant. A quoted value
+ surrounded by white space, or any characters other than
+ <code class="literal">DELIMITER</code>, will include those characters. This can cause
+ errors if you import data from a system that pads <code class="literal">CSV</code>
+ lines with white space out to some fixed width. If such a situation
+ arises you might need to preprocess the <code class="literal">CSV</code> file to remove
+ the trailing white space, before importing the data into
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ CSV format will both recognize and produce CSV files with quoted
+ values containing embedded carriage returns and line feeds. Thus
+ the files are not strictly one line per table row like text-format
+ files.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Many programs produce strange and occasionally perverse CSV files,
+ so the file format is more a convention than a standard. Thus you
+ might encounter some files that cannot be imported using this
+ mechanism, and <code class="command">COPY</code> might produce files that other
+ programs cannot process.
+ </p></div></div><div class="refsect2" id="id-1.9.3.55.9.4"><h3>Binary Format</h3><p>
+ The <code class="literal">binary</code> format option causes all data to be
+ stored/read as binary format rather than as text. It is
+ somewhat faster than the text and <code class="literal">CSV</code> formats,
+ but a binary-format file is less portable across machine architectures and
+ <span class="productname">PostgreSQL</span> versions.
+ Also, the binary format is very data type specific; for example
+ it will not work to output binary data from a <code class="type">smallint</code> column
+ and read it into an <code class="type">integer</code> column, even though that would work
+ fine in text format.
+ </p><p>
+ The <code class="literal">binary</code> file format consists
+ of a file header, zero or more tuples containing the row data, and
+ a file trailer. Headers and data are in network byte order.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> releases before 7.4 used a
+ different binary file format.
+ </p></div><div class="refsect3" id="id-1.9.3.55.9.4.5"><h4>File Header</h4><p>
+ The file header consists of 15 bytes of fixed fields, followed
+ by a variable-length header extension area. The fixed fields are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Signature</span></dt><dd><p>
+11-byte sequence <code class="literal">PGCOPY\n\377\r\n\0</code> — note that the zero byte
+is a required part of the signature. (The signature is designed to allow
+easy identification of files that have been munged by a non-8-bit-clean
+transfer. This signature will be changed by end-of-line-translation
+filters, dropped zero bytes, dropped high bits, or parity changes.)
+ </p></dd><dt><span class="term">Flags field</span></dt><dd><p>
+32-bit integer bit mask to denote important aspects of the file format. Bits
+are numbered from 0 (<acronym class="acronym">LSB</acronym>) to 31 (<acronym class="acronym">MSB</acronym>). Note that
+this field is stored in network byte order (most significant byte first),
+as are all the integer fields used in the file format. Bits
+16–31 are reserved to denote critical file format issues; a reader
+should abort if it finds an unexpected bit set in this range. Bits 0–15
+are reserved to signal backwards-compatible format issues; a reader
+should simply ignore any unexpected bits set in this range. Currently
+only one flag bit is defined, and the rest must be zero:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Bit 16</span></dt><dd><p>
+ If 1, OIDs are included in the data; if 0, not. Oid system columns
+ are not supported in <span class="productname">PostgreSQL</span>
+ anymore, but the format still contains the indicator.
+ </p></dd></dl></div></dd><dt><span class="term">Header extension area length</span></dt><dd><p>
+32-bit integer, length in bytes of remainder of header, not including self.
+Currently, this is zero, and the first tuple follows
+immediately. Future changes to the format might allow additional data
+to be present in the header. A reader should silently skip over any header
+extension data it does not know what to do with.
+ </p></dd></dl></div><p>
+ </p><p>
+The header extension area is envisioned to contain a sequence of
+self-identifying chunks. The flags field is not intended to tell readers
+what is in the extension area. Specific design of header extension contents
+is left for a later release.
+ </p><p>
+ This design allows for both backwards-compatible header additions (add
+ header extension chunks, or set low-order flag bits) and
+ non-backwards-compatible changes (set high-order flag bits to signal such
+ changes, and add supporting data to the extension area if needed).
+ </p></div><div class="refsect3" id="id-1.9.3.55.9.4.6"><h4>Tuples</h4><p>
+Each tuple begins with a 16-bit integer count of the number of fields in the
+tuple. (Presently, all tuples in a table will have the same count, but that
+might not always be true.) Then, repeated for each field in the tuple, there
+is a 32-bit length word followed by that many bytes of field data. (The
+length word does not include itself, and can be zero.) As a special case,
+-1 indicates a NULL field value. No value bytes follow in the NULL case.
+ </p><p>
+There is no alignment padding or any other extra data between fields.
+ </p><p>
+Presently, all data values in a binary-format file are
+assumed to be in binary format (format code one). It is anticipated that a
+future extension might add a header field that allows per-column format codes
+to be specified.
+ </p><p>
+To determine the appropriate binary format for the actual tuple data you
+should consult the <span class="productname">PostgreSQL</span> source, in
+particular the <code class="function">*send</code> and <code class="function">*recv</code> functions for
+each column's data type (typically these functions are found in the
+<code class="filename">src/backend/utils/adt/</code> directory of the source
+distribution).
+ </p><p>
+If OIDs are included in the file, the OID field immediately follows the
+field-count word. It is a normal field except that it's not included in the
+field-count. Note that oid system columns are not supported in current
+versions of <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect3" id="id-1.9.3.55.9.4.7"><h4>File Trailer</h4><p>
+ The file trailer consists of a 16-bit integer word containing -1. This
+ is easily distinguished from a tuple's field-count word.
+ </p><p>
+ A reader should report an error if a field-count word is neither -1
+ nor the expected number of columns. This provides an extra
+ check against somehow getting out of sync with the data.
+ </p></div></div></div><div class="refsect1" id="id-1.9.3.55.10"><h2>Examples</h2><p>
+ The following example copies a table to the client
+ using the vertical bar (<code class="literal">|</code>) as the field delimiter:
+</p><pre class="programlisting">
+COPY country TO STDOUT (DELIMITER '|');
+</pre><p>
+ </p><p>
+ To copy data from a file into the <code class="literal">country</code> table:
+</p><pre class="programlisting">
+COPY country FROM '/usr1/proj/bray/sql/country_data';
+</pre><p>
+ </p><p>
+ To copy into a file just the countries whose names start with 'A':
+</p><pre class="programlisting">
+COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';
+</pre><p>
+ </p><p>
+ To copy into a compressed file, you can pipe the output through an external
+ compression program:
+</p><pre class="programlisting">
+COPY country TO PROGRAM 'gzip &gt; /usr1/proj/bray/sql/country_data.gz';
+</pre><p>
+ </p><p>
+ Here is a sample of data suitable for copying into a table from
+ <code class="literal">STDIN</code>:
+</p><pre class="programlisting">
+AF AFGHANISTAN
+AL ALBANIA
+DZ ALGERIA
+ZM ZAMBIA
+ZW ZIMBABWE
+</pre><p>
+ Note that the white space on each line is actually a tab character.
+ </p><p>
+ The following is the same data, output in binary format.
+ The data is shown after filtering through the
+ Unix utility <code class="command">od -c</code>. The table has three columns;
+ the first has type <code class="type">char(2)</code>, the second has type <code class="type">text</code>,
+ and the third has type <code class="type">integer</code>. All the rows have a null value
+ in the third column.
+</p><pre class="programlisting">
+0000000 P G C O P Y \n 377 \r \n \0 \0 \0 \0 \0 \0
+0000020 \0 \0 \0 \0 003 \0 \0 \0 002 A F \0 \0 \0 013 A
+0000040 F G H A N I S T A N 377 377 377 377 \0 003
+0000060 \0 \0 \0 002 A L \0 \0 \0 007 A L B A N I
+0000100 A 377 377 377 377 \0 003 \0 \0 \0 002 D Z \0 \0 \0
+0000120 007 A L G E R I A 377 377 377 377 \0 003 \0 \0
+0000140 \0 002 Z M \0 \0 \0 006 Z A M B I A 377 377
+0000160 377 377 \0 003 \0 \0 \0 002 Z W \0 \0 \0 \b Z I
+0000200 M B A B W E 377 377 377 377 377 377
+</pre></div><div class="refsect1" id="id-1.9.3.55.11"><h2>Compatibility</h2><p>
+ There is no <code class="command">COPY</code> statement in the SQL standard.
+ </p><p>
+ The following syntax was used before <span class="productname">PostgreSQL</span>
+ version 9.0 and is still supported:
+
+</p><pre class="synopsis">
+COPY <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ FROM { '<em class="replaceable"><code>filename</code></em>' | STDIN }
+ [ [ WITH ]
+ [ BINARY ]
+ [ DELIMITER [ AS ] '<em class="replaceable"><code>delimiter_character</code></em>' ]
+ [ NULL [ AS ] '<em class="replaceable"><code>null_string</code></em>' ]
+ [ CSV [ HEADER ]
+ [ QUOTE [ AS ] '<em class="replaceable"><code>quote_character</code></em>' ]
+ [ ESCAPE [ AS ] '<em class="replaceable"><code>escape_character</code></em>' ]
+ [ FORCE NOT NULL <em class="replaceable"><code>column_name</code></em> [, ...] ] ] ]
+
+COPY { <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ] | ( <em class="replaceable"><code>query</code></em> ) }
+ TO { '<em class="replaceable"><code>filename</code></em>' | STDOUT }
+ [ [ WITH ]
+ [ BINARY ]
+ [ DELIMITER [ AS ] '<em class="replaceable"><code>delimiter_character</code></em>' ]
+ [ NULL [ AS ] '<em class="replaceable"><code>null_string</code></em>' ]
+ [ CSV [ HEADER ]
+ [ QUOTE [ AS ] '<em class="replaceable"><code>quote_character</code></em>' ]
+ [ ESCAPE [ AS ] '<em class="replaceable"><code>escape_character</code></em>' ]
+ [ FORCE QUOTE { <em class="replaceable"><code>column_name</code></em> [, ...] | * } ] ] ]
+</pre><p>
+
+ Note that in this syntax, <code class="literal">BINARY</code> and <code class="literal">CSV</code> are
+ treated as independent keywords, not as arguments of a <code class="literal">FORMAT</code>
+ option.
+ </p><p>
+ The following syntax was used before <span class="productname">PostgreSQL</span>
+ version 7.3 and is still supported:
+
+</p><pre class="synopsis">
+COPY [ BINARY ] <em class="replaceable"><code>table_name</code></em>
+ FROM { '<em class="replaceable"><code>filename</code></em>' | STDIN }
+ [ [USING] DELIMITERS '<em class="replaceable"><code>delimiter_character</code></em>' ]
+ [ WITH NULL AS '<em class="replaceable"><code>null_string</code></em>' ]
+
+COPY [ BINARY ] <em class="replaceable"><code>table_name</code></em>
+ TO { '<em class="replaceable"><code>filename</code></em>' | STDOUT }
+ [ [USING] DELIMITERS '<em class="replaceable"><code>delimiter_character</code></em>' ]
+ [ WITH NULL AS '<em class="replaceable"><code>null_string</code></em>' ]
+</pre></div><div class="refsect1" id="id-1.9.3.55.12"><h2>See Also</h2><span class="simplelist"><a class="xref" href="progress-reporting.html#COPY-PROGRESS-REPORTING" title="28.4.6. COPY Progress Reporting">Section 28.4.6</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-commit-prepared.html" title="COMMIT PREPARED">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">Next</a></td></tr><tr><td width="40%" align="left" valign="top">COMMIT PREPARED </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE ACCESS METHOD</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-create-access-method.html b/doc/src/sgml/html/sql-create-access-method.html
new file mode 100644
index 0000000..18f82b5
--- /dev/null
+++ b/doc/src/sgml/html/sql-create-access-method.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE ACCESS METHOD</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-copy.html" title="COPY" /><link rel="next" href="sql-createaggregate.html" title="CREATE AGGREGATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE ACCESS METHOD</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-copy.html" title="COPY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createaggregate.html" title="CREATE AGGREGATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATE-ACCESS-METHOD"><div class="titlepage"></div><a id="id-1.9.3.56.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE ACCESS METHOD</span></h2><p>CREATE ACCESS METHOD — define a new access method</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE ACCESS METHOD <em class="replaceable"><code>name</code></em>
+ TYPE <em class="replaceable"><code>access_method_type</code></em>
+ HANDLER <em class="replaceable"><code>handler_function</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.56.5"><h2>Description</h2><p>
+ <code class="command">CREATE ACCESS METHOD</code> creates a new access method.
+ </p><p>
+ The access method name must be unique within the database.
+ </p><p>
+ Only superusers can define new access methods.
+ </p></div><div class="refsect1" id="id-1.9.3.56.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the access method to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>access_method_type</code></em></span></dt><dd><p>
+ This clause specifies the type of access method to define.
+ Only <code class="literal">TABLE</code> and <code class="literal">INDEX</code>
+ are supported at present.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>handler_function</code></em></span></dt><dd><p>
+ <em class="replaceable"><code>handler_function</code></em> is the
+ name (possibly schema-qualified) of a previously registered function
+ that represents the access method. The handler function must be
+ declared to take a single argument of type <code class="type">internal</code>,
+ and its return type depends on the type of access method;
+ for <code class="literal">TABLE</code> access methods, it must
+ be <code class="type">table_am_handler</code> and for <code class="literal">INDEX</code>
+ access methods, it must be <code class="type">index_am_handler</code>.
+ The C-level API that the handler function must implement varies
+ depending on the type of access method. The table access method API
+ is described in <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> and the index access method
+ API is described in <a class="xref" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Chapter 64</a>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.56.7"><h2>Examples</h2><p>
+ Create an index access method <code class="literal">heptree</code> with
+ handler function <code class="literal">heptree_handler</code>:
+</p><pre class="programlisting">
+CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler;
+</pre></div><div class="refsect1" id="id-1.9.3.56.8"><h2>Compatibility</h2><p>
+ <code class="command">CREATE ACCESS METHOD</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.56.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY"><span class="refentrytitle">CREATE OPERATOR FAMILY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-copy.html" title="COPY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createaggregate.html" title="CREATE AGGREGATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">COPY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE AGGREGATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createaggregate.html b/doc/src/sgml/html/sql-createaggregate.html
new file mode 100644
index 0000000..f691383
--- /dev/null
+++ b/doc/src/sgml/html/sql-createaggregate.html
@@ -0,0 +1,510 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE AGGREGATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-create-access-method.html" title="CREATE ACCESS METHOD" /><link rel="next" href="sql-createcast.html" title="CREATE CAST" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE AGGREGATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createcast.html" title="CREATE CAST">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEAGGREGATE"><div class="titlepage"></div><a id="id-1.9.3.57.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE AGGREGATE</span></h2><p>CREATE AGGREGATE — define a new aggregate function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] AGGREGATE <em class="replaceable"><code>name</code></em> ( [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>arg_data_type</code></em> [ , ... ] ) (
+ SFUNC = <em class="replaceable"><code>sfunc</code></em>,
+ STYPE = <em class="replaceable"><code>state_data_type</code></em>
+ [ , SSPACE = <em class="replaceable"><code>state_data_size</code></em> ]
+ [ , FINALFUNC = <em class="replaceable"><code>ffunc</code></em> ]
+ [ , FINALFUNC_EXTRA ]
+ [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ]
+ [ , COMBINEFUNC = <em class="replaceable"><code>combinefunc</code></em> ]
+ [ , SERIALFUNC = <em class="replaceable"><code>serialfunc</code></em> ]
+ [ , DESERIALFUNC = <em class="replaceable"><code>deserialfunc</code></em> ]
+ [ , INITCOND = <em class="replaceable"><code>initial_condition</code></em> ]
+ [ , MSFUNC = <em class="replaceable"><code>msfunc</code></em> ]
+ [ , MINVFUNC = <em class="replaceable"><code>minvfunc</code></em> ]
+ [ , MSTYPE = <em class="replaceable"><code>mstate_data_type</code></em> ]
+ [ , MSSPACE = <em class="replaceable"><code>mstate_data_size</code></em> ]
+ [ , MFINALFUNC = <em class="replaceable"><code>mffunc</code></em> ]
+ [ , MFINALFUNC_EXTRA ]
+ [ , MFINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ]
+ [ , MINITCOND = <em class="replaceable"><code>minitial_condition</code></em> ]
+ [ , SORTOP = <em class="replaceable"><code>sort_operator</code></em> ]
+ [ , PARALLEL = { SAFE | RESTRICTED | UNSAFE } ]
+)
+
+CREATE [ OR REPLACE ] AGGREGATE <em class="replaceable"><code>name</code></em> ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>arg_data_type</code></em> [ , ... ] ]
+ ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>arg_data_type</code></em> [ , ... ] ) (
+ SFUNC = <em class="replaceable"><code>sfunc</code></em>,
+ STYPE = <em class="replaceable"><code>state_data_type</code></em>
+ [ , SSPACE = <em class="replaceable"><code>state_data_size</code></em> ]
+ [ , FINALFUNC = <em class="replaceable"><code>ffunc</code></em> ]
+ [ , FINALFUNC_EXTRA ]
+ [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ]
+ [ , INITCOND = <em class="replaceable"><code>initial_condition</code></em> ]
+ [ , PARALLEL = { SAFE | RESTRICTED | UNSAFE } ]
+ [ , HYPOTHETICAL ]
+)
+
+<span class="phrase">or the old syntax</span>
+
+CREATE [ OR REPLACE ] AGGREGATE <em class="replaceable"><code>name</code></em> (
+ BASETYPE = <em class="replaceable"><code>base_type</code></em>,
+ SFUNC = <em class="replaceable"><code>sfunc</code></em>,
+ STYPE = <em class="replaceable"><code>state_data_type</code></em>
+ [ , SSPACE = <em class="replaceable"><code>state_data_size</code></em> ]
+ [ , FINALFUNC = <em class="replaceable"><code>ffunc</code></em> ]
+ [ , FINALFUNC_EXTRA ]
+ [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ]
+ [ , COMBINEFUNC = <em class="replaceable"><code>combinefunc</code></em> ]
+ [ , SERIALFUNC = <em class="replaceable"><code>serialfunc</code></em> ]
+ [ , DESERIALFUNC = <em class="replaceable"><code>deserialfunc</code></em> ]
+ [ , INITCOND = <em class="replaceable"><code>initial_condition</code></em> ]
+ [ , MSFUNC = <em class="replaceable"><code>msfunc</code></em> ]
+ [ , MINVFUNC = <em class="replaceable"><code>minvfunc</code></em> ]
+ [ , MSTYPE = <em class="replaceable"><code>mstate_data_type</code></em> ]
+ [ , MSSPACE = <em class="replaceable"><code>mstate_data_size</code></em> ]
+ [ , MFINALFUNC = <em class="replaceable"><code>mffunc</code></em> ]
+ [ , MFINALFUNC_EXTRA ]
+ [ , MFINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ]
+ [ , MINITCOND = <em class="replaceable"><code>minitial_condition</code></em> ]
+ [ , SORTOP = <em class="replaceable"><code>sort_operator</code></em> ]
+)
+</pre></div><div class="refsect1" id="id-1.9.3.57.5"><h2>Description</h2><p>
+ <code class="command">CREATE AGGREGATE</code> defines a new aggregate function.
+ <code class="command">CREATE OR REPLACE AGGREGATE</code> will either define a new
+ aggregate function or replace an existing definition. Some basic and
+ commonly-used aggregate functions are included with the distribution; they
+ are documented in <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a>. If one defines new
+ types or needs an aggregate function not already provided, then
+ <code class="command">CREATE AGGREGATE</code> can be used to provide the desired
+ features.
+ </p><p>
+ When replacing an existing definition, the argument types, result type,
+ and number of direct arguments may not be changed. Also, the new definition
+ must be of the same kind (ordinary aggregate, ordered-set aggregate, or
+ hypothetical-set aggregate) as the old one.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE AGGREGATE
+ myschema.myagg ...</code>) then the aggregate function is created in the
+ specified schema. Otherwise it is created in the current schema.
+ </p><p>
+ An aggregate function is identified by its name and input data type(s).
+ Two aggregates in the same schema can have the same name if they operate on
+ different input types. The
+ name and input data type(s) of an aggregate must also be distinct from
+ the name and input data type(s) of every ordinary function in the same
+ schema.
+ This behavior is identical to overloading of ordinary function names
+ (see <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>).
+ </p><p>
+ A simple aggregate function is made from one or two ordinary
+ functions:
+ a state transition function
+ <em class="replaceable"><code>sfunc</code></em>,
+ and an optional final calculation function
+ <em class="replaceable"><code>ffunc</code></em>.
+ These are used as follows:
+</p><pre class="programlisting">
+<em class="replaceable"><code>sfunc</code></em>( internal-state, next-data-values ) ---&gt; next-internal-state
+<em class="replaceable"><code>ffunc</code></em>( internal-state ) ---&gt; aggregate-value
+</pre><p>
+ </p><p>
+ <span class="productname">PostgreSQL</span> creates a temporary variable
+ of data type <em class="replaceable"><code>stype</code></em>
+ to hold the current internal state of the aggregate. At each input row,
+ the aggregate argument value(s) are calculated and
+ the state transition function is invoked with the current state value
+ and the new argument value(s) to calculate a new
+ internal state value. After all the rows have been processed,
+ the final function is invoked once to calculate the aggregate's return
+ value. If there is no final function then the ending state value
+ is returned as-is.
+ </p><p>
+ An aggregate function can provide an initial condition,
+ that is, an initial value for the internal state value.
+ This is specified and stored in the database as a value of type
+ <code class="type">text</code>, but it must be a valid external representation
+ of a constant of the state value data type. If it is not supplied
+ then the state value starts out null.
+ </p><p>
+ If the state transition function is declared <span class="quote">“<span class="quote">strict</span>”</span>,
+ then it cannot be called with null inputs. With such a transition
+ function, aggregate execution behaves as follows. Rows with any null input
+ values are ignored (the function is not called and the previous state value
+ is retained). If the initial state value is null, then at the first row
+ with all-nonnull input values, the first argument value replaces the state
+ value, and the transition function is invoked at each subsequent row with
+ all-nonnull input values.
+ This is handy for implementing aggregates like <code class="function">max</code>.
+ Note that this behavior is only available when
+ <em class="replaceable"><code>state_data_type</code></em>
+ is the same as the first
+ <em class="replaceable"><code>arg_data_type</code></em>.
+ When these types are different, you must supply a nonnull initial
+ condition or use a nonstrict transition function.
+ </p><p>
+ If the state transition function is not strict, then it will be called
+ unconditionally at each input row, and must deal with null inputs
+ and null state values for itself. This allows the aggregate
+ author to have full control over the aggregate's handling of null values.
+ </p><p>
+ If the final function is declared <span class="quote">“<span class="quote">strict</span>”</span>, then it will not
+ be called when the ending state value is null; instead a null result
+ will be returned automatically. (Of course this is just the normal
+ behavior of strict functions.) In any case the final function has
+ the option of returning a null value. For example, the final function for
+ <code class="function">avg</code> returns null when it sees there were zero
+ input rows.
+ </p><p>
+ Sometimes it is useful to declare the final function as taking not just
+ the state value, but extra parameters corresponding to the aggregate's
+ input values. The main reason for doing this is if the final function
+ is polymorphic and the state value's data type would be inadequate to
+ pin down the result type. These extra parameters are always passed as
+ NULL (and so the final function must not be strict when
+ the <code class="literal">FINALFUNC_EXTRA</code> option is used), but nonetheless they
+ are valid parameters. The final function could for example make use
+ of <code class="function">get_fn_expr_argtype</code> to identify the actual argument type
+ in the current call.
+ </p><p>
+ An aggregate can optionally support <em class="firstterm">moving-aggregate mode</em>,
+ as described in <a class="xref" href="xaggr.html#XAGGR-MOVING-AGGREGATES" title="38.12.1. Moving-Aggregate Mode">Section 38.12.1</a>. This requires
+ specifying the <code class="literal">MSFUNC</code>, <code class="literal">MINVFUNC</code>,
+ and <code class="literal">MSTYPE</code> parameters, and optionally
+ the <code class="literal">MSSPACE</code>, <code class="literal">MFINALFUNC</code>,
+ <code class="literal">MFINALFUNC_EXTRA</code>, <code class="literal">MFINALFUNC_MODIFY</code>,
+ and <code class="literal">MINITCOND</code> parameters. Except for <code class="literal">MINVFUNC</code>,
+ these parameters work like the corresponding simple-aggregate parameters
+ without <code class="literal">M</code>; they define a separate implementation of the
+ aggregate that includes an inverse transition function.
+ </p><p>
+ The syntax with <code class="literal">ORDER BY</code> in the parameter list creates
+ a special type of aggregate called an <em class="firstterm">ordered-set
+ aggregate</em>; or if <code class="literal">HYPOTHETICAL</code> is specified, then
+ a <em class="firstterm">hypothetical-set aggregate</em> is created. These
+ aggregates operate over groups of sorted values in order-dependent ways,
+ so that specification of an input sort order is an essential part of a
+ call. Also, they can have <em class="firstterm">direct</em> arguments, which are
+ arguments that are evaluated only once per aggregation rather than once
+ per input row. Hypothetical-set aggregates are a subclass of ordered-set
+ aggregates in which some of the direct arguments are required to match,
+ in number and data types, the aggregated argument columns. This allows
+ the values of those direct arguments to be added to the collection of
+ aggregate-input rows as an additional <span class="quote">“<span class="quote">hypothetical</span>”</span> row.
+ </p><p>
+ An aggregate can optionally support <em class="firstterm">partial aggregation</em>,
+ as described in <a class="xref" href="xaggr.html#XAGGR-PARTIAL-AGGREGATES" title="38.12.4. Partial Aggregation">Section 38.12.4</a>.
+ This requires specifying the <code class="literal">COMBINEFUNC</code> parameter.
+ If the <em class="replaceable"><code>state_data_type</code></em>
+ is <code class="type">internal</code>, it's usually also appropriate to provide the
+ <code class="literal">SERIALFUNC</code> and <code class="literal">DESERIALFUNC</code> parameters so that
+ parallel aggregation is possible. Note that the aggregate must also be
+ marked <code class="literal">PARALLEL SAFE</code> to enable parallel aggregation.
+ </p><p>
+ Aggregates that behave like <code class="function">MIN</code> or <code class="function">MAX</code> can
+ sometimes be optimized by looking into an index instead of scanning every
+ input row. If this aggregate can be so optimized, indicate it by
+ specifying a <em class="firstterm">sort operator</em>. The basic requirement is that
+ the aggregate must yield the first element in the sort ordering induced by
+ the operator; in other words:
+</p><pre class="programlisting">
+SELECT agg(col) FROM tab;
+</pre><p>
+ must be equivalent to:
+</p><pre class="programlisting">
+SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
+</pre><p>
+ Further assumptions are that the aggregate ignores null inputs, and that
+ it delivers a null result if and only if there were no non-null inputs.
+ Ordinarily, a data type's <code class="literal">&lt;</code> operator is the proper sort
+ operator for <code class="function">MIN</code>, and <code class="literal">&gt;</code> is the proper sort
+ operator for <code class="function">MAX</code>. Note that the optimization will never
+ actually take effect unless the specified operator is the <span class="quote">“<span class="quote">less
+ than</span>”</span> or <span class="quote">“<span class="quote">greater than</span>”</span> strategy member of a B-tree
+ index operator class.
+ </p><p>
+ To be able to create an aggregate function, you must
+ have <code class="literal">USAGE</code> privilege on the argument types, the state
+ type(s), and the return type, as well as <code class="literal">EXECUTE</code>
+ privilege on the supporting functions.
+ </p></div><div class="refsect1" id="id-1.9.3.57.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the aggregate function
+ to create.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code> or <code class="literal">VARIADIC</code>.
+ (Aggregate functions do not support <code class="literal">OUT</code> arguments.)
+ If omitted, the default is <code class="literal">IN</code>. Only the last argument
+ can be marked <code class="literal">VARIADIC</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument. This is currently only useful for
+ documentation purposes. If omitted, the argument has no name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>arg_data_type</code></em></span></dt><dd><p>
+ An input data type on which this aggregate function operates.
+ To create a zero-argument aggregate function, write <code class="literal">*</code>
+ in place of the list of argument specifications. (An example of such an
+ aggregate is <code class="function">count(*)</code>.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>base_type</code></em></span></dt><dd><p>
+ In the old syntax for <code class="command">CREATE AGGREGATE</code>, the input data type
+ is specified by a <code class="literal">basetype</code> parameter rather than being
+ written next to the aggregate name. Note that this syntax allows
+ only one input parameter. To define a zero-argument aggregate function
+ with this syntax, specify the <code class="literal">basetype</code> as
+ <code class="literal">"ANY"</code> (not <code class="literal">*</code>).
+ Ordered-set aggregates cannot be defined with the old syntax.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sfunc</code></em></span></dt><dd><p>
+ The name of the state transition function to be called for each
+ input row. For a normal <em class="replaceable"><code>N</code></em>-argument
+ aggregate function, the <em class="replaceable"><code>sfunc</code></em>
+ must take <em class="replaceable"><code>N</code></em>+1 arguments,
+ the first being of type <em class="replaceable"><code>state_data_type</code></em> and the rest
+ matching the declared input data type(s) of the aggregate.
+ The function must return a value of type <em class="replaceable"><code>state_data_type</code></em>. This function
+ takes the current state value and the current input data value(s),
+ and returns the next state value.
+ </p><p>
+ For ordered-set (including hypothetical-set) aggregates, the state
+ transition function receives only the current state value and the
+ aggregated arguments, not the direct arguments. Otherwise it is the
+ same.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>state_data_type</code></em></span></dt><dd><p>
+ The data type for the aggregate's state value.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>state_data_size</code></em></span></dt><dd><p>
+ The approximate average size (in bytes) of the aggregate's state value.
+ If this parameter is omitted or is zero, a default estimate is used
+ based on the <em class="replaceable"><code>state_data_type</code></em>.
+ The planner uses this value to estimate the memory required for a
+ grouped aggregate query.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>ffunc</code></em></span></dt><dd><p>
+ The name of the final function called to compute the aggregate's
+ result after all input rows have been traversed.
+ For a normal aggregate, this function
+ must take a single argument of type <em class="replaceable"><code>state_data_type</code></em>. The return
+ data type of the aggregate is defined as the return type of this
+ function. If <em class="replaceable"><code>ffunc</code></em>
+ is not specified, then the ending state value is used as the
+ aggregate's result, and the return type is <em class="replaceable"><code>state_data_type</code></em>.
+ </p><p>
+ For ordered-set (including hypothetical-set) aggregates, the
+ final function receives not only the final state value,
+ but also the values of all the direct arguments.
+ </p><p>
+ If <code class="literal">FINALFUNC_EXTRA</code> is specified, then in addition to the
+ final state value and any direct arguments, the final function
+ receives extra NULL values corresponding to the aggregate's regular
+ (aggregated) arguments. This is mainly useful to allow correct
+ resolution of the aggregate result type when a polymorphic aggregate
+ is being defined.
+ </p></dd><dt><span class="term"><code class="literal">FINALFUNC_MODIFY</code> = { <code class="literal">READ_ONLY</code> | <code class="literal">SHAREABLE</code> | <code class="literal">READ_WRITE</code> }</span></dt><dd><p>
+ This option specifies whether the final function is a pure function
+ that does not modify its arguments. <code class="literal">READ_ONLY</code> indicates
+ it does not; the other two values indicate that it may change the
+ transition state value. See <a class="xref" href="sql-createaggregate.html#SQL-CREATEAGGREGATE-NOTES" title="Notes">Notes</a>
+ below for more detail. The
+ default is <code class="literal">READ_ONLY</code>, except for ordered-set aggregates,
+ for which the default is <code class="literal">READ_WRITE</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>combinefunc</code></em></span></dt><dd><p>
+ The <em class="replaceable"><code>combinefunc</code></em> function
+ may optionally be specified to allow the aggregate function to support
+ partial aggregation. If provided,
+ the <em class="replaceable"><code>combinefunc</code></em> must
+ combine two <em class="replaceable"><code>state_data_type</code></em>
+ values, each containing the result of aggregation over some subset of
+ the input values, to produce a
+ new <em class="replaceable"><code>state_data_type</code></em> that
+ represents the result of aggregating over both sets of inputs. This
+ function can be thought of as
+ an <em class="replaceable"><code>sfunc</code></em>, where instead of
+ acting upon an individual input row and adding it to the running
+ aggregate state, it adds another aggregate state to the running state.
+ </p><p>
+ The <em class="replaceable"><code>combinefunc</code></em> must be
+ declared as taking two arguments of
+ the <em class="replaceable"><code>state_data_type</code></em> and
+ returning a value of
+ the <em class="replaceable"><code>state_data_type</code></em>.
+ Optionally this function may be <span class="quote">“<span class="quote">strict</span>”</span>. In this case the
+ function will not be called when either of the input states are null;
+ the other state will be taken as the correct result.
+ </p><p>
+ For aggregate functions
+ whose <em class="replaceable"><code>state_data_type</code></em>
+ is <code class="type">internal</code>,
+ the <em class="replaceable"><code>combinefunc</code></em> must not
+ be strict. In this case
+ the <em class="replaceable"><code>combinefunc</code></em> must
+ ensure that null states are handled correctly and that the state being
+ returned is properly stored in the aggregate memory context.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>serialfunc</code></em></span></dt><dd><p>
+ An aggregate function
+ whose <em class="replaceable"><code>state_data_type</code></em>
+ is <code class="type">internal</code> can participate in parallel aggregation only if it
+ has a <em class="replaceable"><code>serialfunc</code></em> function,
+ which must serialize the aggregate state into a <code class="type">bytea</code> value for
+ transmission to another process. This function must take a single
+ argument of type <code class="type">internal</code> and return type <code class="type">bytea</code>. A
+ corresponding <em class="replaceable"><code>deserialfunc</code></em>
+ is also required.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>deserialfunc</code></em></span></dt><dd><p>
+ Deserialize a previously serialized aggregate state back into
+ <em class="replaceable"><code>state_data_type</code></em>. This
+ function must take two arguments of types <code class="type">bytea</code>
+ and <code class="type">internal</code>, and produce a result of type <code class="type">internal</code>.
+ (Note: the second, <code class="type">internal</code> argument is unused, but is required
+ for type safety reasons.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>initial_condition</code></em></span></dt><dd><p>
+ The initial setting for the state value. This must be a string
+ constant in the form accepted for the data type <em class="replaceable"><code>state_data_type</code></em>. If not
+ specified, the state value starts out null.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>msfunc</code></em></span></dt><dd><p>
+ The name of the forward state transition function to be called for each
+ input row in moving-aggregate mode. This is exactly like the regular
+ transition function, except that its first argument and result are of
+ type <em class="replaceable"><code>mstate_data_type</code></em>, which might be different
+ from <em class="replaceable"><code>state_data_type</code></em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>minvfunc</code></em></span></dt><dd><p>
+ The name of the inverse state transition function to be used in
+ moving-aggregate mode. This function has the same argument and
+ result types as <em class="replaceable"><code>msfunc</code></em>, but it is used to remove
+ a value from the current aggregate state, rather than add a value to
+ it. The inverse transition function must have the same strictness
+ attribute as the forward state transition function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>mstate_data_type</code></em></span></dt><dd><p>
+ The data type for the aggregate's state value, when using
+ moving-aggregate mode.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>mstate_data_size</code></em></span></dt><dd><p>
+ The approximate average size (in bytes) of the aggregate's state
+ value, when using moving-aggregate mode. This works the same as
+ <em class="replaceable"><code>state_data_size</code></em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>mffunc</code></em></span></dt><dd><p>
+ The name of the final function called to compute the aggregate's
+ result after all input rows have been traversed, when using
+ moving-aggregate mode. This works the same as <em class="replaceable"><code>ffunc</code></em>,
+ except that its first argument's type
+ is <em class="replaceable"><code>mstate_data_type</code></em> and extra dummy arguments are
+ specified by writing <code class="literal">MFINALFUNC_EXTRA</code>.
+ The aggregate result type determined by <em class="replaceable"><code>mffunc</code></em>
+ or <em class="replaceable"><code>mstate_data_type</code></em> must match that determined by the
+ aggregate's regular implementation.
+ </p></dd><dt><span class="term"><code class="literal">MFINALFUNC_MODIFY</code> = { <code class="literal">READ_ONLY</code> | <code class="literal">SHAREABLE</code> | <code class="literal">READ_WRITE</code> }</span></dt><dd><p>
+ This option is like <code class="literal">FINALFUNC_MODIFY</code>, but it describes
+ the behavior of the moving-aggregate final function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>minitial_condition</code></em></span></dt><dd><p>
+ The initial setting for the state value, when using moving-aggregate
+ mode. This works the same as <em class="replaceable"><code>initial_condition</code></em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sort_operator</code></em></span></dt><dd><p>
+ The associated sort operator for a <code class="function">MIN</code>- or
+ <code class="function">MAX</code>-like aggregate.
+ This is just an operator name (possibly schema-qualified).
+ The operator is assumed to have the same input data types as
+ the aggregate (which must be a single-argument normal aggregate).
+ </p></dd><dt><span class="term"><code class="literal">PARALLEL =</code> { <code class="literal">SAFE</code> | <code class="literal">RESTRICTED</code> | <code class="literal">UNSAFE</code> }</span></dt><dd><p>
+ The meanings of <code class="literal">PARALLEL SAFE</code>, <code class="literal">PARALLEL
+ RESTRICTED</code>, and <code class="literal">PARALLEL UNSAFE</code> are the same as
+ in <a class="link" href="sql-createfunction.html" title="CREATE FUNCTION"><code class="command">CREATE FUNCTION</code></a>. An aggregate will not be
+ considered for parallelization if it is marked <code class="literal">PARALLEL
+ UNSAFE</code> (which is the default!) or <code class="literal">PARALLEL RESTRICTED</code>.
+ Note that the parallel-safety markings of the aggregate's support
+ functions are not consulted by the planner, only the marking of the
+ aggregate itself.
+ </p></dd><dt><span class="term"><code class="literal">HYPOTHETICAL</code></span></dt><dd><p>
+ For ordered-set aggregates only, this flag specifies that the aggregate
+ arguments are to be processed according to the requirements for
+ hypothetical-set aggregates: that is, the last few direct arguments must
+ match the data types of the aggregated (<code class="literal">WITHIN GROUP</code>)
+ arguments. The <code class="literal">HYPOTHETICAL</code> flag has no effect on
+ run-time behavior, only on parse-time resolution of the data types and
+ collations of the aggregate's arguments.
+ </p></dd></dl></div><p>
+ The parameters of <code class="command">CREATE AGGREGATE</code> can be
+ written in any order, not just the order illustrated above.
+ </p></div><div class="refsect1" id="SQL-CREATEAGGREGATE-NOTES"><h2>Notes</h2><p>
+ In parameters that specify support function names, you can write
+ a schema name if needed, for example <code class="literal">SFUNC = public.sum</code>.
+ Do not write argument types there, however — the argument types
+ of the support functions are determined from other parameters.
+ </p><p>
+ Ordinarily, PostgreSQL functions are expected to be true functions that
+ do not modify their input values. However, an aggregate transition
+ function, <span class="emphasis"><em>when used in the context of an aggregate</em></span>,
+ is allowed to cheat and modify its transition-state argument in place.
+ This can provide substantial performance benefits compared to making
+ a fresh copy of the transition state each time.
+ </p><p>
+ Likewise, while an aggregate final function is normally expected not to
+ modify its input values, sometimes it is impractical to avoid modifying
+ the transition-state argument. Such behavior must be declared using
+ the <code class="literal">FINALFUNC_MODIFY</code> parameter.
+ The <code class="literal">READ_WRITE</code>
+ value indicates that the final function modifies the transition state in
+ unspecified ways. This value prevents use of the aggregate as a window
+ function, and it also prevents merging of transition states for aggregate
+ calls that share the same input values and transition functions.
+ The <code class="literal">SHAREABLE</code> value indicates that the transition function
+ cannot be applied after the final function, but multiple final-function
+ calls can be performed on the ending transition state value. This value
+ prevents use of the aggregate as a window function, but it allows merging
+ of transition states. (That is, the optimization of interest here is not
+ applying the same final function repeatedly, but applying different final
+ functions to the same ending transition state value. This is allowed as
+ long as none of the final functions are marked <code class="literal">READ_WRITE</code>.)
+ </p><p>
+ If an aggregate supports moving-aggregate mode, it will improve
+ calculation efficiency when the aggregate is used as a window function
+ for a window with moving frame start (that is, a frame start mode other
+ than <code class="literal">UNBOUNDED PRECEDING</code>). Conceptually, the forward
+ transition function adds input values to the aggregate's state when
+ they enter the window frame from the bottom, and the inverse transition
+ function removes them again when they leave the frame at the top. So,
+ when values are removed, they are always removed in the same order they
+ were added. Whenever the inverse transition function is invoked, it will
+ thus receive the earliest added but not yet removed argument value(s).
+ The inverse transition function can assume that at least one row will
+ remain in the current state after it removes the oldest row. (When this
+ would not be the case, the window function mechanism simply starts a
+ fresh aggregation, rather than using the inverse transition function.)
+ </p><p>
+ The forward transition function for moving-aggregate mode is not
+ allowed to return NULL as the new state value. If the inverse
+ transition function returns NULL, this is taken as an indication that
+ the inverse function cannot reverse the state calculation for this
+ particular input, and so the aggregate calculation will be redone from
+ scratch for the current frame starting position. This convention
+ allows moving-aggregate mode to be used in situations where there are
+ some infrequent cases that are impractical to reverse out of the
+ running state value.
+ </p><p>
+ If no moving-aggregate implementation is supplied,
+ the aggregate can still be used with moving frames,
+ but <span class="productname">PostgreSQL</span> will recompute the whole
+ aggregation whenever the start of the frame moves.
+ Note that whether or not the aggregate supports moving-aggregate
+ mode, <span class="productname">PostgreSQL</span> can handle a moving frame
+ end without recalculation; this is done by continuing to add new values
+ to the aggregate's state. This is why use of an aggregate as a window
+ function requires that the final function be read-only: it must
+ not damage the aggregate's state value, so that the aggregation can be
+ continued even after an aggregate result value has been obtained for
+ one set of frame boundaries.
+ </p><p>
+ The syntax for ordered-set aggregates allows <code class="literal">VARIADIC</code>
+ to be specified for both the last direct parameter and the last
+ aggregated (<code class="literal">WITHIN GROUP</code>) parameter. However, the
+ current implementation restricts use of <code class="literal">VARIADIC</code>
+ in two ways. First, ordered-set aggregates can only use
+ <code class="literal">VARIADIC "any"</code>, not other variadic array types.
+ Second, if the last direct parameter is <code class="literal">VARIADIC "any"</code>,
+ then there can be only one aggregated parameter and it must also
+ be <code class="literal">VARIADIC "any"</code>. (In the representation used in the
+ system catalogs, these two parameters are merged into a single
+ <code class="literal">VARIADIC "any"</code> item, since <code class="structname">pg_proc</code> cannot
+ represent functions with more than one <code class="literal">VARIADIC</code> parameter.)
+ If the aggregate is a hypothetical-set aggregate, the direct arguments
+ that match the <code class="literal">VARIADIC "any"</code> parameter are the hypothetical
+ ones; any preceding parameters represent additional direct arguments
+ that are not constrained to match the aggregated arguments.
+ </p><p>
+ Currently, ordered-set aggregates do not need to support
+ moving-aggregate mode, since they cannot be used as window functions.
+ </p><p>
+ Partial (including parallel) aggregation is currently not supported for
+ ordered-set aggregates. Also, it will never be used for aggregate calls
+ that include <code class="literal">DISTINCT</code> or <code class="literal">ORDER BY</code> clauses, since
+ those semantics cannot be supported during partial aggregation.
+ </p></div><div class="refsect1" id="id-1.9.3.57.8"><h2>Examples</h2><p>
+ See <a class="xref" href="xaggr.html" title="38.12. User-Defined Aggregates">Section 38.12</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.57.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE AGGREGATE</code> is a
+ <span class="productname">PostgreSQL</span> language extension. The SQL
+ standard does not provide for user-defined aggregate functions.
+ </p></div><div class="refsect1" id="id-1.9.3.57.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteraggregate.html" title="ALTER AGGREGATE"><span class="refentrytitle">ALTER AGGREGATE</span></a>, <a class="xref" href="sql-dropaggregate.html" title="DROP AGGREGATE"><span class="refentrytitle">DROP AGGREGATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createcast.html" title="CREATE CAST">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE ACCESS METHOD </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE CAST</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createcast.html b/doc/src/sgml/html/sql-createcast.html
new file mode 100644
index 0000000..cc91355
--- /dev/null
+++ b/doc/src/sgml/html/sql-createcast.html
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE CAST</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createaggregate.html" title="CREATE AGGREGATE" /><link rel="next" href="sql-createcollation.html" title="CREATE COLLATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE CAST</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createaggregate.html" title="CREATE AGGREGATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createcollation.html" title="CREATE COLLATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATECAST"><div class="titlepage"></div><a id="id-1.9.3.58.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE CAST</span></h2><p>CREATE CAST — define a new cast</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>)
+ WITH FUNCTION <em class="replaceable"><code>function_name</code></em> [ (<em class="replaceable"><code>argument_type</code></em> [, ...]) ]
+ [ AS ASSIGNMENT | AS IMPLICIT ]
+
+CREATE CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>)
+ WITHOUT FUNCTION
+ [ AS ASSIGNMENT | AS IMPLICIT ]
+
+CREATE CAST (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>)
+ WITH INOUT
+ [ AS ASSIGNMENT | AS IMPLICIT ]
+</pre></div><div class="refsect1" id="SQL-CREATECAST-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE CAST</code> defines a new cast. A cast
+ specifies how to perform a conversion between
+ two data types. For example,
+</p><pre class="programlisting">
+SELECT CAST(42 AS float8);
+</pre><p>
+ converts the integer constant 42 to type <code class="type">float8</code> by
+ invoking a previously specified function, in this case
+ <code class="literal">float8(int4)</code>. (If no suitable cast has been defined, the
+ conversion fails.)
+ </p><p>
+ Two types can be <em class="firstterm">binary coercible</em>, which
+ means that the conversion can be performed <span class="quote">“<span class="quote">for free</span>”</span>
+ without invoking any function. This requires that corresponding
+ values use the same internal representation. For instance, the
+ types <code class="type">text</code> and <code class="type">varchar</code> are binary
+ coercible both ways. Binary coercibility is not necessarily a
+ symmetric relationship. For example, the cast
+ from <code class="type">xml</code> to <code class="type">text</code> can be performed for
+ free in the present implementation, but the reverse direction
+ requires a function that performs at least a syntax check. (Two
+ types that are binary coercible both ways are also referred to as
+ binary compatible.)
+ </p><p>
+ You can define a cast as an <em class="firstterm">I/O conversion cast</em> by using
+ the <code class="literal">WITH INOUT</code> syntax. An I/O conversion cast is
+ performed by invoking the output function of the source data type, and
+ passing the resulting string to the input function of the target data type.
+ In many common cases, this feature avoids the need to write a separate
+ cast function for conversion. An I/O conversion cast acts the same as
+ a regular function-based cast; only the implementation is different.
+ </p><p>
+ By default, a cast can be invoked only by an explicit cast request,
+ that is an explicit <code class="literal">CAST(<em class="replaceable"><code>x</code></em> AS
+ <em class="replaceable"><code>typename</code></em>)</code> or
+ <em class="replaceable"><code>x</code></em><code class="literal">::</code><em class="replaceable"><code>typename</code></em>
+ construct.
+ </p><p>
+ If the cast is marked <code class="literal">AS ASSIGNMENT</code> then it can be invoked
+ implicitly when assigning a value to a column of the target data type.
+ For example, supposing that <code class="literal">foo.f1</code> is a column of
+ type <code class="type">text</code>, then:
+</p><pre class="programlisting">
+INSERT INTO foo (f1) VALUES (42);
+</pre><p>
+ will be allowed if the cast from type <code class="type">integer</code> to type
+ <code class="type">text</code> is marked <code class="literal">AS ASSIGNMENT</code>, otherwise not.
+ (We generally use the term <em class="firstterm">assignment
+ cast</em> to describe this kind of cast.)
+ </p><p>
+ If the cast is marked <code class="literal">AS IMPLICIT</code> then it can be invoked
+ implicitly in any context, whether assignment or internally in an
+ expression. (We generally use the term <em class="firstterm">implicit
+ cast</em> to describe this kind of cast.)
+ For example, consider this query:
+</p><pre class="programlisting">
+SELECT 2 + 4.0;
+</pre><p>
+ The parser initially marks the constants as being of type <code class="type">integer</code>
+ and <code class="type">numeric</code> respectively. There is no <code class="type">integer</code>
+ <code class="literal">+</code> <code class="type">numeric</code> operator in the system catalogs,
+ but there is a <code class="type">numeric</code> <code class="literal">+</code> <code class="type">numeric</code> operator.
+ The query will therefore succeed if a cast from <code class="type">integer</code> to
+ <code class="type">numeric</code> is available and is marked <code class="literal">AS IMPLICIT</code> —
+ which in fact it is. The parser will apply the implicit cast and resolve
+ the query as if it had been written
+</p><pre class="programlisting">
+SELECT CAST ( 2 AS numeric ) + 4.0;
+</pre><p>
+ </p><p>
+ Now, the catalogs also provide a cast from <code class="type">numeric</code> to
+ <code class="type">integer</code>. If that cast were marked <code class="literal">AS IMPLICIT</code> —
+ which it is not — then the parser would be faced with choosing
+ between the above interpretation and the alternative of casting the
+ <code class="type">numeric</code> constant to <code class="type">integer</code> and applying the
+ <code class="type">integer</code> <code class="literal">+</code> <code class="type">integer</code> operator. Lacking any
+ knowledge of which choice to prefer, it would give up and declare the
+ query ambiguous. The fact that only one of the two casts is
+ implicit is the way in which we teach the parser to prefer resolution
+ of a mixed <code class="type">numeric</code>-and-<code class="type">integer</code> expression as
+ <code class="type">numeric</code>; there is no built-in knowledge about that.
+ </p><p>
+ It is wise to be conservative about marking casts as implicit. An
+ overabundance of implicit casting paths can cause
+ <span class="productname">PostgreSQL</span> to choose surprising
+ interpretations of commands, or to be unable to resolve commands at
+ all because there are multiple possible interpretations. A good
+ rule of thumb is to make a cast implicitly invokable only for
+ information-preserving transformations between types in the same
+ general type category. For example, the cast from <code class="type">int2</code> to
+ <code class="type">int4</code> can reasonably be implicit, but the cast from
+ <code class="type">float8</code> to <code class="type">int4</code> should probably be
+ assignment-only. Cross-type-category casts, such as <code class="type">text</code>
+ to <code class="type">int4</code>, are best made explicit-only.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Sometimes it is necessary for usability or standards-compliance reasons
+ to provide multiple implicit casts among a set of types, resulting in
+ ambiguity that cannot be avoided as above. The parser has a fallback
+ heuristic based on <em class="firstterm">type categories</em> and <em class="firstterm">preferred
+ types</em> that can help to provide desired behavior in such cases. See
+ <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> for
+ more information.
+ </p></div><p>
+ To be able to create a cast, you must own the source or the target data type
+ and have <code class="literal">USAGE</code> privilege on the other type. To create a
+ binary-coercible cast, you must be superuser. (This restriction is made
+ because an erroneous binary-coercible cast conversion can easily crash the
+ server.)
+ </p></div><div class="refsect1" id="id-1.9.3.58.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>source_type</code></em></span></dt><dd><p>
+ The name of the source data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>target_type</code></em></span></dt><dd><p>
+ The name of the target data type of the cast.
+ </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>function_name</code></em>[(<em class="replaceable"><code>argument_type</code></em> [, ...])]</code></span></dt><dd><p>
+ The function used to perform the cast. The function name can
+ be schema-qualified. If it is not, the function will be looked
+ up in the schema search path. The function's result data type must
+ match the target type of the cast. Its arguments are discussed below.
+ If no argument list is specified, the function name must be unique in
+ its schema.
+ </p></dd><dt><span class="term"><code class="literal">WITHOUT FUNCTION</code></span></dt><dd><p>
+ Indicates that the source type is binary-coercible to the target type,
+ so no function is required to perform the cast.
+ </p></dd><dt><span class="term"><code class="literal">WITH INOUT</code></span></dt><dd><p>
+ Indicates that the cast is an I/O conversion cast, performed by
+ invoking the output function of the source data type, and passing the
+ resulting string to the input function of the target data type.
+ </p></dd><dt><span class="term"><code class="literal">AS ASSIGNMENT</code></span></dt><dd><p>
+ Indicates that the cast can be invoked implicitly in assignment
+ contexts.
+ </p></dd><dt><span class="term"><code class="literal">AS IMPLICIT</code></span></dt><dd><p>
+ Indicates that the cast can be invoked implicitly in any context.
+ </p></dd></dl></div><p>
+ Cast implementation functions can have one to three arguments.
+ The first argument type must be identical to or binary-coercible from
+ the cast's source type. The second argument,
+ if present, must be type <code class="type">integer</code>; it receives the type
+ modifier associated with the destination type, or <code class="literal">-1</code>
+ if there is none. The third argument,
+ if present, must be type <code class="type">boolean</code>; it receives <code class="literal">true</code>
+ if the cast is an explicit cast, <code class="literal">false</code> otherwise.
+ (Bizarrely, the SQL standard demands different behaviors for explicit and
+ implicit casts in some cases. This argument is supplied for functions
+ that must implement such casts. It is not recommended that you design
+ your own data types so that this matters.)
+ </p><p>
+ The return type of a cast function must be identical to or
+ binary-coercible to the cast's target type.
+ </p><p>
+ Ordinarily a cast must have different source and target data types.
+ However, it is allowed to declare a cast with identical source and
+ target types if it has a cast implementation function with more than one
+ argument. This is used to represent type-specific length coercion
+ functions in the system catalogs. The named function is used to
+ coerce a value of the type to the type modifier value given by its
+ second argument.
+ </p><p>
+ When a cast has different source and
+ target types and a function that takes more than one argument, it
+ supports converting from one type to another and applying a length
+ coercion in a single step. When no such entry is available, coercion
+ to a type that uses a type modifier involves two cast steps, one to
+ convert between data types and a second to apply the modifier.
+ </p><p>
+ A cast to or from a domain type currently has no effect. Casting
+ to or from a domain uses the casts associated with its underlying type.
+ </p></div><div class="refsect1" id="SQL-CREATECAST-NOTES"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-dropcast.html" title="DROP CAST"><code class="command">DROP CAST</code></a> to remove user-defined casts.
+ </p><p>
+ Remember that if you want to be able to convert types both ways you
+ need to declare casts both ways explicitly.
+ </p><a id="id-1.9.3.58.7.4" class="indexterm"></a><p>
+ It is normally not necessary to create casts between user-defined types
+ and the standard string types (<code class="type">text</code>, <code class="type">varchar</code>, and
+ <code class="type">char(<em class="replaceable"><code>n</code></em>)</code>, as well as user-defined types that
+ are defined to be in the string category). <span class="productname">PostgreSQL</span>
+ provides automatic I/O conversion casts for that. The automatic casts to
+ string types are treated as assignment casts, while the automatic casts
+ from string types are
+ explicit-only. You can override this behavior by declaring your own
+ cast to replace an automatic cast, but usually the only reason to
+ do so is if you want the conversion to be more easily invokable than the
+ standard assignment-only or explicit-only setting. Another possible
+ reason is that you want the conversion to behave differently from the
+ type's I/O function; but that is sufficiently surprising that you
+ should think twice about whether it's a good idea. (A small number of
+ the built-in types do indeed have different behaviors for conversions,
+ mostly because of requirements of the SQL standard.)
+ </p><p>
+ While not required, it is recommended that you continue to follow this old
+ convention of naming cast implementation functions after the target data
+ type. Many users are used to being able to cast data types using a
+ function-style notation, that is
+ <em class="replaceable"><code>typename</code></em>(<em class="replaceable"><code>x</code></em>). This notation is in fact
+ nothing more nor less than a call of the cast implementation function; it
+ is not specially treated as a cast. If your conversion functions are not
+ named to support this convention then you will have surprised users.
+ Since <span class="productname">PostgreSQL</span> allows overloading of the same function
+ name with different argument types, there is no difficulty in having
+ multiple conversion functions from different types that all use the
+ target type's name.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Actually the preceding paragraph is an oversimplification: there are
+ two cases in which a function-call construct will be treated as a cast
+ request without having matched it to an actual function.
+ If a function call <em class="replaceable"><code>name</code></em>(<em class="replaceable"><code>x</code></em>) does not
+ exactly match any existing function, but <em class="replaceable"><code>name</code></em> is the name
+ of a data type and <code class="structname">pg_cast</code> provides a binary-coercible cast
+ to this type from the type of <em class="replaceable"><code>x</code></em>, then the call will be
+ construed as a binary-coercible cast. This exception is made so that
+ binary-coercible casts can be invoked using functional syntax, even
+ though they lack any function. Likewise, if there is no
+ <code class="structname">pg_cast</code> entry but the cast would be to or from a string
+ type, the call will be construed as an I/O conversion cast. This
+ exception allows I/O conversion casts to be invoked using functional
+ syntax.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ There is also an exception to the exception: I/O conversion casts from
+ composite types to string types cannot be invoked using functional
+ syntax, but must be written in explicit cast syntax (either
+ <code class="literal">CAST</code> or <code class="literal">::</code> notation). This exception was added
+ because after the introduction of automatically-provided I/O conversion
+ casts, it was found too easy to accidentally invoke such a cast when
+ a function or column reference was intended.
+ </p></div></div><div class="refsect1" id="SQL-CREATECAST-EXAMPLES"><h2>Examples</h2><p>
+ To create an assignment cast from type <code class="type">bigint</code> to type
+ <code class="type">int4</code> using the function <code class="literal">int4(bigint)</code>:
+</p><pre class="programlisting">
+CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT;
+</pre><p>
+ (This cast is already predefined in the system.)
+ </p></div><div class="refsect1" id="SQL-CREATECAST-COMPAT"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE CAST</code> command conforms to the
+ <acronym class="acronym">SQL</acronym> standard,
+ except that SQL does not make provisions for binary-coercible
+ types or extra arguments to implementation functions.
+ <code class="literal">AS IMPLICIT</code> is a <span class="productname">PostgreSQL</span>
+ extension, too.
+ </p></div><div class="refsect1" id="SQL-CREATECAST-SEEALSO"><h2>See Also</h2><p>
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>,
+ <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a>,
+ <a class="xref" href="sql-dropcast.html" title="DROP CAST"><span class="refentrytitle">DROP CAST</span></a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createaggregate.html" title="CREATE AGGREGATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createcollation.html" title="CREATE COLLATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE AGGREGATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE COLLATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createcollation.html b/doc/src/sgml/html/sql-createcollation.html
new file mode 100644
index 0000000..7e7b4dc
--- /dev/null
+++ b/doc/src/sgml/html/sql-createcollation.html
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE COLLATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createcast.html" title="CREATE CAST" /><link rel="next" href="sql-createconversion.html" title="CREATE CONVERSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE COLLATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createcast.html" title="CREATE CAST">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createconversion.html" title="CREATE CONVERSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATECOLLATION"><div class="titlepage"></div><a id="id-1.9.3.59.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE COLLATION</span></h2><p>CREATE COLLATION — define a new collation</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE COLLATION [ IF NOT EXISTS ] <em class="replaceable"><code>name</code></em> (
+ [ LOCALE = <em class="replaceable"><code>locale</code></em>, ]
+ [ LC_COLLATE = <em class="replaceable"><code>lc_collate</code></em>, ]
+ [ LC_CTYPE = <em class="replaceable"><code>lc_ctype</code></em>, ]
+ [ PROVIDER = <em class="replaceable"><code>provider</code></em>, ]
+ [ DETERMINISTIC = <em class="replaceable"><code>boolean</code></em>, ]
+ [ VERSION = <em class="replaceable"><code>version</code></em> ]
+)
+CREATE COLLATION [ IF NOT EXISTS ] <em class="replaceable"><code>name</code></em> FROM <em class="replaceable"><code>existing_collation</code></em>
+</pre></div><div class="refsect1" id="SQL-CREATECOLLATION-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE COLLATION</code> defines a new collation using
+ the specified operating system locale settings,
+ or by copying an existing collation.
+ </p><p>
+ To be able to create a collation, you must
+ have <code class="literal">CREATE</code> privilege on the destination schema.
+ </p></div><div class="refsect1" id="id-1.9.3.59.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a collation with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing collation is anything like the one that would have been created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the collation. The collation name can be
+ schema-qualified. If it is not, the collation is defined in the
+ current schema. The collation name must be unique within that
+ schema. (The system catalogs can contain collations with the
+ same name for other encodings, but these are ignored if the
+ database encoding does not match.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>locale</code></em></span></dt><dd><p>
+ This is a shortcut for setting <code class="symbol">LC_COLLATE</code>
+ and <code class="symbol">LC_CTYPE</code> at once. If you specify this,
+ you cannot specify either of those parameters.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lc_collate</code></em></span></dt><dd><p>
+ Use the specified operating system locale for
+ the <code class="symbol">LC_COLLATE</code> locale category.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lc_ctype</code></em></span></dt><dd><p>
+ Use the specified operating system locale for
+ the <code class="symbol">LC_CTYPE</code> locale category.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>provider</code></em></span></dt><dd><p>
+ Specifies the provider to use for locale services associated with this
+ collation. Possible values
+ are: <code class="literal">icu</code>,<a id="id-1.9.3.59.6.2.6.2.1.2" class="indexterm"></a>
+ <code class="literal">libc</code>.
+ <code class="literal">libc</code> is the default.
+ The available choices depend on the operating system and build options.
+ </p></dd><dt><span class="term"><code class="literal">DETERMINISTIC</code></span></dt><dd><p>
+ Specifies whether the collation should use deterministic comparisons.
+ The default is true. A deterministic comparison considers strings that
+ are not byte-wise equal to be unequal even if they are considered
+ logically equal by the comparison. PostgreSQL breaks ties using a
+ byte-wise comparison. Comparison that is not deterministic can make the
+ collation be, say, case- or accent-insensitive. For that, you need to
+ choose an appropriate <code class="literal">LC_COLLATE</code> setting
+ <span class="emphasis"><em>and</em></span> set the collation to not deterministic here.
+ </p><p>
+ Nondeterministic collations are only supported with the ICU provider.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>version</code></em></span></dt><dd><p>
+ Specifies the version string to store with the collation. Normally,
+ this should be omitted, which will cause the version to be computed
+ from the actual version of the collation as provided by the operating
+ system. This option is intended to be used
+ by <code class="command">pg_upgrade</code> for copying the version from an
+ existing installation.
+ </p><p>
+ See also <a class="xref" href="sql-altercollation.html" title="ALTER COLLATION"><span class="refentrytitle">ALTER COLLATION</span></a> for how to handle
+ collation version mismatches.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>existing_collation</code></em></span></dt><dd><p>
+ The name of an existing collation to copy. The new collation
+ will have the same properties as the existing one, but it
+ will be an independent object.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATECOLLATION-NOTES"><h2>Notes</h2><p>
+ <code class="command">CREATE COLLATION</code> takes a <code class="literal">SHARE ROW
+ EXCLUSIVE</code> lock, which is self-conflicting, on the
+ <code class="structname">pg_collation</code> system catalog, so only one
+ <code class="command">CREATE COLLATION</code> command can run at a time.
+ </p><p>
+ Use <code class="command">DROP COLLATION</code> to remove user-defined collations.
+ </p><p>
+ See <a class="xref" href="collation.html#COLLATION-CREATE" title="24.2.2.3. Creating New Collation Objects">Section 24.2.2.3</a> for more information on how to create collations.
+ </p><p>
+ When using the <code class="literal">libc</code> collation provider, the locale must
+ be applicable to the current database encoding.
+ See <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a> for the precise rules.
+ </p></div><div class="refsect1" id="SQL-CREATECOLLATION-EXAMPLES"><h2>Examples</h2><p>
+ To create a collation from the operating system locale
+ <code class="literal">fr_FR.utf8</code>
+ (assuming the current database encoding is <code class="literal">UTF8</code>):
+</p><pre class="programlisting">
+CREATE COLLATION french (locale = 'fr_FR.utf8');
+</pre><p>
+ </p><p>
+ To create a collation using the ICU provider using German phone book sort order:
+</p><pre class="programlisting">
+CREATE COLLATION german_phonebook (provider = icu, locale = 'de-u-co-phonebk');
+</pre><p>
+ </p><p>
+ To create a collation from an existing collation:
+</p><pre class="programlisting">
+CREATE COLLATION german FROM "de_DE";
+</pre><p>
+ This can be convenient to be able to use operating-system-independent
+ collation names in applications.
+ </p></div><div class="refsect1" id="SQL-CREATECOLLATION-COMPAT"><h2>Compatibility</h2><p>
+ There is a <code class="command">CREATE COLLATION</code> statement in the SQL
+ standard, but it is limited to copying an existing collation. The
+ syntax to create a new collation is
+ a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="SQL-CREATECOLLATION-SEEALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altercollation.html" title="ALTER COLLATION"><span class="refentrytitle">ALTER COLLATION</span></a>, <a class="xref" href="sql-dropcollation.html" title="DROP COLLATION"><span class="refentrytitle">DROP COLLATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createcast.html" title="CREATE CAST">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createconversion.html" title="CREATE CONVERSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE CAST </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE CONVERSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createconversion.html b/doc/src/sgml/html/sql-createconversion.html
new file mode 100644
index 0000000..9dae318
--- /dev/null
+++ b/doc/src/sgml/html/sql-createconversion.html
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE CONVERSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createcollation.html" title="CREATE COLLATION" /><link rel="next" href="sql-createdatabase.html" title="CREATE DATABASE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE CONVERSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createcollation.html" title="CREATE COLLATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createdatabase.html" title="CREATE DATABASE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATECONVERSION"><div class="titlepage"></div><a id="id-1.9.3.60.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE CONVERSION</span></h2><p>CREATE CONVERSION — define a new encoding conversion</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ DEFAULT ] CONVERSION <em class="replaceable"><code>name</code></em>
+ FOR <em class="replaceable"><code>source_encoding</code></em> TO <em class="replaceable"><code>dest_encoding</code></em> FROM <em class="replaceable"><code>function_name</code></em>
+</pre></div><div class="refsect1" id="SQL-CREATECONVERSION-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE CONVERSION</code> defines a new conversion between
+ two character set encodings.
+ </p><p>
+ Conversions that are marked <code class="literal">DEFAULT</code> can be used for
+ automatic encoding conversion between client and server. To support that
+ usage, two conversions, from encoding A to B <span class="emphasis"><em>and</em></span>
+ from encoding B to A, must be defined.
+ </p><p>
+ To be able to create a conversion, you must have <code class="literal">EXECUTE</code> privilege
+ on the function and <code class="literal">CREATE</code> privilege on the destination schema.
+ </p></div><div class="refsect1" id="id-1.9.3.60.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ The <code class="literal">DEFAULT</code> clause indicates that this conversion
+ is the default for this particular source to destination
+ encoding. There should be only one default encoding in a schema
+ for the encoding pair.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the conversion. The conversion name can be
+ schema-qualified. If it is not, the conversion is defined in the
+ current schema. The conversion name must be unique within a
+ schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_encoding</code></em></span></dt><dd><p>
+ The source encoding name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>dest_encoding</code></em></span></dt><dd><p>
+ The destination encoding name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ The function used to perform the conversion. The function name can
+ be schema-qualified. If it is not, the function will be looked
+ up in the path.
+ </p><p>
+ The function must have the following signature:
+
+</p><pre class="programlisting">
+conv_proc(
+ integer, -- source encoding ID
+ integer, -- destination encoding ID
+ cstring, -- source string (null terminated C string)
+ internal, -- destination (fill with a null terminated C string)
+ integer, -- source string length
+ boolean -- if true, don't throw an error if conversion fails
+) RETURNS integer;
+</pre><p>
+ The return value is the number of source bytes that were successfully
+ converted. If the last argument is false, the function must throw an
+ error on invalid input, and the return value is always equal to the
+ source string length.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATECONVERSION-NOTES"><h2>Notes</h2><p>
+ Neither the source nor the destination encoding can
+ be <code class="literal">SQL_ASCII</code>, as the server's behavior for cases
+ involving the <code class="literal">SQL_ASCII</code> <span class="quote">“<span class="quote">encoding</span>”</span> is
+ hard-wired.
+ </p><p>
+ Use <code class="command">DROP CONVERSION</code> to remove user-defined conversions.
+ </p><p>
+ The privileges required to create a conversion might be changed in a future
+ release.
+ </p></div><div class="refsect1" id="SQL-CREATECONVERSION-EXAMPLES"><h2>Examples</h2><p>
+ To create a conversion from encoding <code class="literal">UTF8</code> to
+ <code class="literal">LATIN1</code> using <code class="function">myfunc</code>:
+</p><pre class="programlisting">
+CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;
+</pre></div><div class="refsect1" id="SQL-CREATECONVERSION-COMPAT"><h2>Compatibility</h2><p>
+ <code class="command">CREATE CONVERSION</code>
+ is a <span class="productname">PostgreSQL</span> extension.
+ There is no <code class="command">CREATE CONVERSION</code>
+ statement in the SQL standard, but a <code class="command">CREATE TRANSLATION</code>
+ statement that is very similar in purpose and syntax.
+ </p></div><div class="refsect1" id="SQL-CREATECONVERSION-SEEALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterconversion.html" title="ALTER CONVERSION"><span class="refentrytitle">ALTER CONVERSION</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-dropconversion.html" title="DROP CONVERSION"><span class="refentrytitle">DROP CONVERSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createcollation.html" title="CREATE COLLATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createdatabase.html" title="CREATE DATABASE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE COLLATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DATABASE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createdatabase.html b/doc/src/sgml/html/sql-createdatabase.html
new file mode 100644
index 0000000..0f04e76
--- /dev/null
+++ b/doc/src/sgml/html/sql-createdatabase.html
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE DATABASE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createconversion.html" title="CREATE CONVERSION" /><link rel="next" href="sql-createdomain.html" title="CREATE DOMAIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE DATABASE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createconversion.html" title="CREATE CONVERSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createdomain.html" title="CREATE DOMAIN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEDATABASE"><div class="titlepage"></div><a id="id-1.9.3.61.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE DATABASE</span></h2><p>CREATE DATABASE — create a new database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE DATABASE <em class="replaceable"><code>name</code></em>
+ [ WITH ] [ OWNER [=] <em class="replaceable"><code>user_name</code></em> ]
+ [ TEMPLATE [=] <em class="replaceable"><code>template</code></em> ]
+ [ ENCODING [=] <em class="replaceable"><code>encoding</code></em> ]
+ [ STRATEGY [=] <em class="replaceable"><code>strategy</code></em> ] ]
+ [ LOCALE [=] <em class="replaceable"><code>locale</code></em> ]
+ [ LC_COLLATE [=] <em class="replaceable"><code>lc_collate</code></em> ]
+ [ LC_CTYPE [=] <em class="replaceable"><code>lc_ctype</code></em> ]
+ [ ICU_LOCALE [=] <em class="replaceable"><code>icu_locale</code></em> ]
+ [ LOCALE_PROVIDER [=] <em class="replaceable"><code>locale_provider</code></em> ]
+ [ COLLATION_VERSION = <em class="replaceable"><code>collation_version</code></em> ]
+ [ TABLESPACE [=] <em class="replaceable"><code>tablespace_name</code></em> ]
+ [ ALLOW_CONNECTIONS [=] <em class="replaceable"><code>allowconn</code></em> ]
+ [ CONNECTION LIMIT [=] <em class="replaceable"><code>connlimit</code></em> ]
+ [ IS_TEMPLATE [=] <em class="replaceable"><code>istemplate</code></em> ]
+ [ OID [=] <em class="replaceable"><code>oid</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.61.5"><h2>Description</h2><p>
+ <code class="command">CREATE DATABASE</code> creates a new
+ <span class="productname">PostgreSQL</span> database.
+ </p><p>
+ To create a database, you must be a superuser or have the special
+ <code class="literal">CREATEDB</code> privilege.
+ See <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>.
+ </p><p>
+ By default, the new database will be created by cloning the standard
+ system database <code class="literal">template1</code>. A different template can be
+ specified by writing <code class="literal">TEMPLATE
+ <em class="replaceable"><code>name</code></em></code>. In particular,
+ by writing <code class="literal">TEMPLATE template0</code>, you can create a pristine
+ database (one where no user-defined objects exist and where the system
+ objects have not been altered)
+ containing only the standard objects predefined by your
+ version of <span class="productname">PostgreSQL</span>. This is useful
+ if you wish to avoid copying
+ any installation-local objects that might have been added to
+ <code class="literal">template1</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.61.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a database to create.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ The role name of the user who will own the new database,
+ or <code class="literal">DEFAULT</code> to use the default (namely, the
+ user executing the command). To create a database owned by another
+ role, you must be a direct or indirect member of that role,
+ or be a superuser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>template</code></em></span></dt><dd><p>
+ The name of the template from which to create the new database,
+ or <code class="literal">DEFAULT</code> to use the default template
+ (<code class="literal">template1</code>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>encoding</code></em></span></dt><dd><p>
+ Character set encoding to use in the new database. Specify
+ a string constant (e.g., <code class="literal">'SQL_ASCII'</code>),
+ or an integer encoding number, or <code class="literal">DEFAULT</code>
+ to use the default encoding (namely, the encoding of the
+ template database). The character sets supported by the
+ <span class="productname">PostgreSQL</span> server are described in
+ <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>. See below for
+ additional restrictions.
+ </p></dd><dt id="CREATE-DATABASE-STRATEGY"><span class="term"><em class="replaceable"><code>strategy</code></em></span></dt><dd><p>
+ Strategy to be used in creating the new database. If
+ the <code class="literal">WAL_LOG</code> strategy is used, the database will be
+ copied block by block and each block will be separately written
+ to the write-ahead log. This is the most efficient strategy in
+ cases where the template database is small, and therefore it is the
+ default. The older <code class="literal">FILE_COPY</code> strategy is also
+ available. This strategy writes a small record to the write-ahead log
+ for each tablespace used by the target database. Each such record
+ represents copying an entire directory to a new location at the
+ filesystem level. While this does reduce the write-ahead
+ log volume substantially, especially if the template database is large,
+ it also forces the system to perform a checkpoint both before and
+ after the creation of the new database. In some situations, this may
+ have a noticeable negative impact on overall system performance.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>locale</code></em></span></dt><dd><p>
+ This is a shortcut for setting <code class="symbol">LC_COLLATE</code>
+ and <code class="symbol">LC_CTYPE</code> at once.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ The other locale settings <a class="xref" href="runtime-config-client.html#GUC-LC-MESSAGES">lc_messages</a>, <a class="xref" href="runtime-config-client.html#GUC-LC-MONETARY">lc_monetary</a>, <a class="xref" href="runtime-config-client.html#GUC-LC-NUMERIC">lc_numeric</a>, and
+ <a class="xref" href="runtime-config-client.html#GUC-LC-TIME">lc_time</a> are not fixed per database and are not
+ set by this command. If you want to make them the default for a
+ specific database, you can use <code class="literal">ALTER DATABASE
+ ... SET</code>.
+ </p></div></dd><dt><span class="term"><em class="replaceable"><code>lc_collate</code></em></span></dt><dd><p>
+ Collation order (<code class="literal">LC_COLLATE</code>) to use in the new database.
+ This affects the sort order applied to strings, e.g., in queries with
+ ORDER BY, as well as the order used in indexes on text columns.
+ The default is to use the collation order of the template database.
+ See below for additional restrictions.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lc_ctype</code></em></span></dt><dd><p>
+ Character classification (<code class="literal">LC_CTYPE</code>) to use in the new
+ database. This affects the categorization of characters, e.g., lower,
+ upper and digit. The default is to use the character classification of
+ the template database. See below for additional restrictions.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>icu_locale</code></em></span></dt><dd><p>
+ Specifies the ICU locale ID if the ICU locale provider is used.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>locale_provider</code></em></span></dt><dd><p>
+ Specifies the provider to use for the default collation in this
+ database. Possible values are:
+ <code class="literal">icu</code>,<a id="id-1.9.3.61.6.2.10.2.1.2" class="indexterm"></a>
+ <code class="literal">libc</code>. <code class="literal">libc</code> is the default. The
+ available choices depend on the operating system and build options.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collation_version</code></em></span></dt><dd><p>
+ Specifies the collation version string to store with the database.
+ Normally, this should be omitted, which will cause the version to be
+ computed from the actual version of the database collation as provided
+ by the operating system. This option is intended to be used by
+ <code class="command">pg_upgrade</code> for copying the version from an existing
+ installation.
+ </p><p>
+ See also <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a> for how to handle
+ database collation version mismatches.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>tablespace_name</code></em></span></dt><dd><p>
+ The name of the tablespace that will be associated with the
+ new database, or <code class="literal">DEFAULT</code> to use the
+ template database's tablespace. This
+ tablespace will be the default tablespace used for objects
+ created in this database. See
+ <a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>
+ for more information.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>allowconn</code></em></span></dt><dd><p>
+ If false then no one can connect to this database. The default is
+ true, allowing connections (except as restricted by other mechanisms,
+ such as <code class="literal">GRANT</code>/<code class="literal">REVOKE CONNECT</code>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>connlimit</code></em></span></dt><dd><p>
+ How many concurrent connections can be made
+ to this database. -1 (the default) means no limit.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>istemplate</code></em></span></dt><dd><p>
+ If true, then this database can be cloned by any user with <code class="literal">CREATEDB</code>
+ privileges; if false (the default), then only superusers or the owner
+ of the database can clone it.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>oid</code></em></span></dt><dd><p>
+ The object identifier to be used for the new database. If this
+ parameter is not specified, <span class="productname">PostgreSQL</span>
+ will choose a suitable OID automatically. This parameter is primarily
+ intended for internal use by <span class="application">pg_upgrade</span>,
+ and only <span class="application">pg_upgrade</span> can specify a value
+ less than 16384.
+ </p></dd></dl></div><p>
+ Optional parameters can be written in any order, not only the order
+ illustrated above.
+ </p></div><div class="refsect1" id="id-1.9.3.61.7"><h2>Notes</h2><p>
+ <code class="command">CREATE DATABASE</code> cannot be executed inside a transaction
+ block.
+ </p><p>
+ Errors along the line of <span class="quote">“<span class="quote">could not initialize database directory</span>”</span>
+ are most likely related to insufficient permissions on the data
+ directory, a full disk, or other file system problems.
+ </p><p>
+ Use <a class="link" href="sql-dropdatabase.html" title="DROP DATABASE"><code class="command">DROP DATABASE</code></a> to remove a database.
+ </p><p>
+ The program <a class="xref" href="app-createdb.html" title="createdb"><span class="refentrytitle"><span class="application">createdb</span></span></a> is a
+ wrapper program around this command, provided for convenience.
+ </p><p>
+ Database-level configuration parameters (set via <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE</code></a>) and database-level permissions (set via
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a>) are not copied from the template database.
+ </p><p>
+ Although it is possible to copy a database other than <code class="literal">template1</code>
+ by specifying its name as the template, this is not (yet) intended as
+ a general-purpose <span class="quote">“<span class="quote"><code class="command">COPY DATABASE</code></span>”</span> facility.
+ The principal limitation is that no other sessions can be connected to
+ the template database while it is being copied. <code class="command">CREATE
+ DATABASE</code> will fail if any other connection exists when it starts;
+ otherwise, new connections to the template database are locked out
+ until <code class="command">CREATE DATABASE</code> completes.
+ See <a class="xref" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Section 23.3</a> for more information.
+ </p><p>
+ The character set encoding specified for the new database must be
+ compatible with the chosen locale settings (<code class="literal">LC_COLLATE</code> and
+ <code class="literal">LC_CTYPE</code>). If the locale is <code class="literal">C</code> (or equivalently
+ <code class="literal">POSIX</code>), then all encodings are allowed, but for other
+ locale settings there is only one encoding that will work properly.
+ (On Windows, however, UTF-8 encoding can be used with any locale.)
+ <code class="command">CREATE DATABASE</code> will allow superusers to specify
+ <code class="literal">SQL_ASCII</code> encoding regardless of the locale settings,
+ but this choice is deprecated and may result in misbehavior of
+ character-string functions if data that is not encoding-compatible
+ with the locale is stored in the database.
+ </p><p>
+ The encoding and locale settings must match those of the template database,
+ except when <code class="literal">template0</code> is used as template. This is because
+ other databases might contain data that does not match the specified
+ encoding, or might contain indexes whose sort ordering is affected by
+ <code class="literal">LC_COLLATE</code> and <code class="literal">LC_CTYPE</code>. Copying such data would
+ result in a database that is corrupt according to the new settings.
+ <code class="literal">template0</code>, however, is known to not contain any data or
+ indexes that would be affected.
+ </p><p>
+ There is currently no option to use a database locale with nondeterministic
+ comparisons (see <a class="link" href="sql-createcollation.html" title="CREATE COLLATION"><code class="command">CREATE
+ COLLATION</code></a> for an explanation). If this is needed, then
+ per-column collations would need to be used.
+ </p><p>
+ The <code class="literal">CONNECTION LIMIT</code> option is only enforced approximately;
+ if two new sessions start at about the same time when just one
+ connection <span class="quote">“<span class="quote">slot</span>”</span> remains for the database, it is possible that
+ both will fail. Also, the limit is not enforced against superusers or
+ background worker processes.
+ </p></div><div class="refsect1" id="id-1.9.3.61.8"><h2>Examples</h2><p>
+ To create a new database:
+
+</p><pre class="programlisting">
+CREATE DATABASE lusiadas;
+</pre><p>
+ </p><p>
+ To create a database <code class="literal">sales</code> owned by user <code class="literal">salesapp</code>
+ with a default tablespace of <code class="literal">salesspace</code>:
+
+</p><pre class="programlisting">
+CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
+</pre><p>
+ </p><p>
+ To create a database <code class="literal">music</code> with a different locale:
+</p><pre class="programlisting">
+CREATE DATABASE music
+ LOCALE 'sv_SE.utf8'
+ TEMPLATE template0;
+</pre><p>
+ In this example, the <code class="literal">TEMPLATE template0</code> clause is required if
+ the specified locale is different from the one in <code class="literal">template1</code>.
+ (If it is not, then specifying the locale explicitly is redundant.)
+ </p><p>
+ To create a database <code class="literal">music2</code> with a different locale and a
+ different character set encoding:
+</p><pre class="programlisting">
+CREATE DATABASE music2
+ LOCALE 'sv_SE.iso885915'
+ ENCODING LATIN9
+ TEMPLATE template0;
+</pre><p>
+ The specified locale and encoding settings must match, or an error will be
+ reported.
+ </p><p>
+ Note that locale names are specific to the operating system, so that the
+ above commands might not work in the same way everywhere.
+ </p></div><div class="refsect1" id="id-1.9.3.61.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE DATABASE</code> statement in the SQL
+ standard. Databases are equivalent to catalogs, whose creation is
+ implementation-defined.
+ </p></div><div class="refsect1" id="id-1.9.3.61.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>, <a class="xref" href="sql-dropdatabase.html" title="DROP DATABASE"><span class="refentrytitle">DROP DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createconversion.html" title="CREATE CONVERSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createdomain.html" title="CREATE DOMAIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE CONVERSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE DOMAIN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createdomain.html b/doc/src/sgml/html/sql-createdomain.html
new file mode 100644
index 0000000..a1cac63
--- /dev/null
+++ b/doc/src/sgml/html/sql-createdomain.html
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE DOMAIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createdatabase.html" title="CREATE DATABASE" /><link rel="next" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE DOMAIN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createdatabase.html" title="CREATE DATABASE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEDOMAIN"><div class="titlepage"></div><a id="id-1.9.3.62.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE DOMAIN</span></h2><p>CREATE DOMAIN — define a new domain</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE DOMAIN <em class="replaceable"><code>name</code></em> [ AS ] <em class="replaceable"><code>data_type</code></em>
+ [ COLLATE <em class="replaceable"><code>collation</code></em> ]
+ [ DEFAULT <em class="replaceable"><code>expression</code></em> ]
+ [ <em class="replaceable"><code>constraint</code></em> [ ... ] ]
+
+<span class="phrase">where <em class="replaceable"><code>constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ NOT NULL | NULL | CHECK (<em class="replaceable"><code>expression</code></em>) }
+</pre></div><div class="refsect1" id="id-1.9.3.62.5"><h2>Description</h2><p>
+ <code class="command">CREATE DOMAIN</code> creates a new domain. A domain is
+ essentially a data type with optional constraints (restrictions on
+ the allowed set of values).
+ The user who defines a domain becomes its owner.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE DOMAIN
+ myschema.mydomain ...</code>) then the domain is created in the
+ specified schema. Otherwise it is created in the current schema.
+ The domain name must be unique among the types and domains existing
+ in its schema.
+ </p><p>
+ Domains are useful for abstracting common constraints on fields into
+ a single location for maintenance. For example, several tables might
+ contain email address columns, all requiring the same CHECK constraint
+ to verify the address syntax.
+ Define a domain rather than setting up each table's constraint
+ individually.
+ </p><p>
+ To be able to create a domain, you must have <code class="literal">USAGE</code>
+ privilege on the underlying type.
+ </p></div><div class="refsect1" id="id-1.9.3.62.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a domain to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The underlying data type of the domain. This can include array
+ specifiers.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collation</code></em></span></dt><dd><p>
+ An optional collation for the domain. If no collation is
+ specified, the domain has the same collation behavior as its
+ underlying data type.
+ The underlying type must be collatable if <code class="literal">COLLATE</code>
+ is specified.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT <em class="replaceable"><code>expression</code></em></code></span></dt><dd><p>
+ The <code class="literal">DEFAULT</code> clause specifies a default value for
+ columns of the domain data type. The value is any
+ variable-free expression (but subqueries are not allowed).
+ The data type of the default expression must match the data
+ type of the domain. If no default value is specified, then
+ the default value is the null value.
+ </p><p>
+ The default expression will be used in any insert operation
+ that does not specify a value for the column. If a default
+ value is defined for a particular column, it overrides any
+ default associated with the domain. In turn, the domain
+ default overrides any default value associated with the
+ underlying data type.
+ </p></dd><dt><span class="term"><code class="literal">CONSTRAINT <em class="replaceable"><code>constraint_name</code></em></code></span></dt><dd><p>
+ An optional name for a constraint. If not specified,
+ the system generates a name.
+ </p></dd><dt><span class="term"><code class="literal">NOT NULL</code></span></dt><dd><p>
+ Values of this domain are prevented from being null
+ (but see notes below).
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ Values of this domain are allowed to be null. This is the default.
+ </p><p>
+ This clause is only intended for compatibility with
+ nonstandard SQL databases. Its use is discouraged in new
+ applications.
+ </p></dd><dt><span class="term"><code class="literal">CHECK (<em class="replaceable"><code>expression</code></em>)</code></span></dt><dd><p><code class="literal">CHECK</code> clauses specify integrity constraints or tests
+ which values of the domain must satisfy.
+ Each constraint must be an expression
+ producing a Boolean result. It should use the key word <code class="literal">VALUE</code>
+ to refer to the value being tested. Expressions evaluating
+ to TRUE or UNKNOWN succeed. If the expression produces a FALSE result,
+ an error is reported and the value is not allowed to be converted
+ to the domain type.
+ </p><p>
+ Currently, <code class="literal">CHECK</code> expressions cannot contain
+ subqueries nor refer to variables other than <code class="literal">VALUE</code>.
+ </p><p>
+ When a domain has multiple <code class="literal">CHECK</code> constraints,
+ they will be tested in alphabetical order by name.
+ (<span class="productname">PostgreSQL</span> versions before 9.5 did not honor any
+ particular firing order for <code class="literal">CHECK</code> constraints.)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.62.7"><h2>Notes</h2><p>
+ Domain constraints, particularly <code class="literal">NOT NULL</code>, are checked when
+ converting a value to the domain type. It is possible for a column that
+ is nominally of the domain type to read as null despite there being such
+ a constraint. For example, this can happen in an outer-join query, if
+ the domain column is on the nullable side of the outer join. A more
+ subtle example is
+</p><pre class="programlisting">
+INSERT INTO tab (domcol) VALUES ((SELECT domcol FROM tab WHERE false));
+</pre><p>
+ The empty scalar sub-SELECT will produce a null value that is considered
+ to be of the domain type, so no further constraint checking is applied
+ to it, and the insertion will succeed.
+ </p><p>
+ It is very difficult to avoid such problems, because of SQL's general
+ assumption that a null value is a valid value of every data type. Best practice
+ therefore is to design a domain's constraints so that a null value is allowed,
+ and then to apply column <code class="literal">NOT NULL</code> constraints to columns of
+ the domain type as needed, rather than directly to the domain type.
+ </p><p>
+ <span class="productname">PostgreSQL</span> assumes that
+ <code class="literal">CHECK</code> constraints' conditions are immutable, that is,
+ they will always give the same result for the same input value. This
+ assumption is what justifies examining <code class="literal">CHECK</code>
+ constraints only when a value is first converted to be of a domain type,
+ and not at other times. (This is essentially the same as the treatment
+ of table <code class="literal">CHECK</code> constraints, as described in
+ <a class="xref" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS" title="5.4.1. Check Constraints">Section 5.4.1</a>.)
+ </p><p>
+ An example of a common way to break this assumption is to reference a
+ user-defined function in a <code class="literal">CHECK</code> expression, and then
+ change the behavior of that
+ function. <span class="productname">PostgreSQL</span> does not disallow that,
+ but it will not notice if there are stored values of the domain type that
+ now violate the <code class="literal">CHECK</code> constraint. That would cause a
+ subsequent database dump and restore to fail. The recommended way to
+ handle such a change is to drop the constraint (using <code class="command">ALTER
+ DOMAIN</code>), adjust the function definition, and re-add the
+ constraint, thereby rechecking it against stored data.
+ </p></div><div class="refsect1" id="id-1.9.3.62.8"><h2>Examples</h2><p>
+ This example creates the <code class="type">us_postal_code</code> data type and
+ then uses the type in a table definition. A regular expression test
+ is used to verify that the value looks like a valid US postal code:
+
+</p><pre class="programlisting">
+CREATE DOMAIN us_postal_code AS TEXT
+CHECK(
+ VALUE ~ '^\d{5}$'
+OR VALUE ~ '^\d{5}-\d{4}$'
+);
+
+CREATE TABLE us_snail_addy (
+ address_id SERIAL PRIMARY KEY,
+ street1 TEXT NOT NULL,
+ street2 TEXT,
+ street3 TEXT,
+ city TEXT NOT NULL,
+ postal us_postal_code NOT NULL
+);
+</pre></div><div class="refsect1" id="SQL-CREATEDOMAIN-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The command <code class="command">CREATE DOMAIN</code> conforms to the SQL
+ standard.
+ </p></div><div class="refsect1" id="SQL-CREATEDOMAIN-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterdomain.html" title="ALTER DOMAIN"><span class="refentrytitle">ALTER DOMAIN</span></a>, <a class="xref" href="sql-dropdomain.html" title="DROP DOMAIN"><span class="refentrytitle">DROP DOMAIN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createdatabase.html" title="CREATE DATABASE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE DATABASE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE EVENT TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createeventtrigger.html b/doc/src/sgml/html/sql-createeventtrigger.html
new file mode 100644
index 0000000..1c3acd5
--- /dev/null
+++ b/doc/src/sgml/html/sql-createeventtrigger.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE EVENT TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createdomain.html" title="CREATE DOMAIN" /><link rel="next" href="sql-createextension.html" title="CREATE EXTENSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE EVENT TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createdomain.html" title="CREATE DOMAIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createextension.html" title="CREATE EXTENSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEEVENTTRIGGER"><div class="titlepage"></div><a id="id-1.9.3.63.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE EVENT TRIGGER</span></h2><p>CREATE EVENT TRIGGER — define a new event trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE EVENT TRIGGER <em class="replaceable"><code>name</code></em>
+ ON <em class="replaceable"><code>event</code></em>
+ [ WHEN <em class="replaceable"><code>filter_variable</code></em> IN (<em class="replaceable"><code>filter_value</code></em> [, ... ]) [ AND ... ] ]
+ EXECUTE { FUNCTION | PROCEDURE } <em class="replaceable"><code>function_name</code></em>()
+</pre></div><div class="refsect1" id="id-1.9.3.63.5"><h2>Description</h2><p>
+ <code class="command">CREATE EVENT TRIGGER</code> creates a new event trigger.
+ Whenever the designated event occurs and the <code class="literal">WHEN</code> condition
+ associated with the trigger, if any, is satisfied, the trigger function
+ will be executed. For a general introduction to event triggers, see
+ <a class="xref" href="event-triggers.html" title="Chapter 40. Event Triggers">Chapter 40</a>. The user who creates an event trigger
+ becomes its owner.
+ </p></div><div class="refsect1" id="id-1.9.3.63.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name to give the new trigger. This name must be unique within
+ the database.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>event</code></em></span></dt><dd><p>
+ The name of the event that triggers a call to the given function.
+ See <a class="xref" href="event-trigger-definition.html" title="40.1. Overview of Event Trigger Behavior">Section 40.1</a> for more information
+ on event names.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>filter_variable</code></em></span></dt><dd><p>
+ The name of a variable used to filter events. This makes it possible
+ to restrict the firing of the trigger to a subset of the cases in which
+ it is supported. Currently the only supported
+ <em class="replaceable"><code>filter_variable</code></em>
+ is <code class="literal">TAG</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>filter_value</code></em></span></dt><dd><p>
+ A list of values for the
+ associated <em class="replaceable"><code>filter_variable</code></em>
+ for which the trigger should fire. For <code class="literal">TAG</code>, this means a
+ list of command tags (e.g., <code class="literal">'DROP FUNCTION'</code>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ A user-supplied function that is declared as taking no argument and
+ returning type <code class="literal">event_trigger</code>.
+ </p><p>
+ In the syntax of <code class="literal">CREATE EVENT TRIGGER</code>, the keywords
+ <code class="literal">FUNCTION</code> and <code class="literal">PROCEDURE</code> are
+ equivalent, but the referenced function must in any case be a function,
+ not a procedure. The use of the keyword <code class="literal">PROCEDURE</code>
+ here is historical and deprecated.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATEEVENTTRIGGER-NOTES"><h2>Notes</h2><p>
+ Only superusers can create event triggers.
+ </p><p>
+ Event triggers are disabled in single-user mode (see <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>). If an erroneous event trigger disables the
+ database so much that you can't even drop the trigger, restart in
+ single-user mode and you'll be able to do that.
+ </p></div><div class="refsect1" id="SQL-CREATEEVENTTRIGGER-EXAMPLES"><h2>Examples</h2><p>
+ Forbid the execution of any <a class="link" href="ddl.html" title="Chapter 5. Data Definition">DDL</a> command:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION abort_any_command()
+ RETURNS event_trigger
+ LANGUAGE plpgsql
+ AS $$
+BEGIN
+ RAISE EXCEPTION 'command % is disabled', tg_tag;
+END;
+$$;
+
+CREATE EVENT TRIGGER abort_ddl ON ddl_command_start
+ EXECUTE FUNCTION abort_any_command();
+</pre></div><div class="refsect1" id="SQL-CREATEEVENTTRIGGER-COMPATIBILITY"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE EVENT TRIGGER</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.63.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER"><span class="refentrytitle">ALTER EVENT TRIGGER</span></a>, <a class="xref" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER"><span class="refentrytitle">DROP EVENT TRIGGER</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createdomain.html" title="CREATE DOMAIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createextension.html" title="CREATE EXTENSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE DOMAIN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE EXTENSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createextension.html b/doc/src/sgml/html/sql-createextension.html
new file mode 100644
index 0000000..ff9b4b3
--- /dev/null
+++ b/doc/src/sgml/html/sql-createextension.html
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE EXTENSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER" /><link rel="next" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE EXTENSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEEXTENSION"><div class="titlepage"></div><a id="id-1.9.3.64.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE EXTENSION</span></h2><p>CREATE EXTENSION — install an extension</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE EXTENSION [ IF NOT EXISTS ] <em class="replaceable"><code>extension_name</code></em>
+ [ WITH ] [ SCHEMA <em class="replaceable"><code>schema_name</code></em> ]
+ [ VERSION <em class="replaceable"><code>version</code></em> ]
+ [ CASCADE ]
+</pre></div><div class="refsect1" id="id-1.9.3.64.5"><h2>Description</h2><p>
+ <code class="command">CREATE EXTENSION</code> loads a new extension into the current
+ database. There must not be an extension of the same name already loaded.
+ </p><p>
+ Loading an extension essentially amounts to running the extension's script
+ file. The script will typically create new <acronym class="acronym">SQL</acronym> objects such as
+ functions, data types, operators and index support methods.
+ <code class="command">CREATE EXTENSION</code> additionally records the identities
+ of all the created objects, so that they can be dropped again if
+ <code class="command">DROP EXTENSION</code> is issued.
+ </p><p>
+ The user who runs <code class="command">CREATE EXTENSION</code> becomes the
+ owner of the extension for purposes of later privilege checks, and
+ normally also becomes the owner of any objects created by the
+ extension's script.
+ </p><p>
+ Loading an extension ordinarily requires the same privileges that would
+ be required to create its component objects. For many extensions this
+ means superuser privileges are needed.
+ However, if the extension is marked <em class="firstterm">trusted</em> in
+ its control file, then it can be installed by any user who has
+ <code class="literal">CREATE</code> privilege on the current database.
+ In this case the extension object itself will be owned by the calling
+ user, but the contained objects will be owned by the bootstrap superuser
+ (unless the extension's script explicitly assigns them to the calling
+ user). This configuration gives the calling user the right to drop the
+ extension, but not to modify individual objects within it.
+ </p></div><div class="refsect1" id="id-1.9.3.64.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if an extension with the same name already
+ exists. A notice is issued in this case. Note that there is no
+ guarantee that the existing extension is anything like the one that
+ would have been created from the currently-available script file.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p>
+ The name of the extension to be
+ installed. <span class="productname">PostgreSQL</span> will create the
+ extension using details from the file
+ <code class="literal">SHAREDIR/extension/</code><em class="replaceable"><code>extension_name</code></em><code class="literal">.control</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>schema_name</code></em></span></dt><dd><p>
+ The name of the schema in which to install the extension's
+ objects, given that the extension allows its contents to be
+ relocated. The named schema must already exist.
+ If not specified, and the extension's control file does not specify a
+ schema either, the current default object creation schema is used.
+ </p><p>
+ If the extension specifies a <code class="literal">schema</code> parameter in its
+ control file, then that schema cannot be overridden with
+ a <code class="literal">SCHEMA</code> clause. Normally, an error will be raised if
+ a <code class="literal">SCHEMA</code> clause is given and it conflicts with the
+ extension's <code class="literal">schema</code> parameter. However, if
+ the <code class="literal">CASCADE</code> clause is also given,
+ then <em class="replaceable"><code>schema_name</code></em> is
+ ignored when it conflicts. The
+ given <em class="replaceable"><code>schema_name</code></em> will be
+ used for installation of any needed extensions that do not
+ specify <code class="literal">schema</code> in their control files.
+ </p><p>
+ Remember that the extension itself is not considered to be within any
+ schema: extensions have unqualified names that must be unique
+ database-wide. But objects belonging to the extension can be within
+ schemas.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>version</code></em></span></dt><dd><p>
+ The version of the extension to install. This can be written as
+ either an identifier or a string literal. The default version is
+ whatever is specified in the extension's control file.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically install any extensions that this extension depends on
+ that are not already installed. Their dependencies are likewise
+ automatically installed, recursively. The <code class="literal">SCHEMA</code> clause,
+ if given, applies to all extensions that get installed this way.
+ Other options of the statement are not applied to
+ automatically-installed extensions; in particular, their default
+ versions are always selected.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.64.7"><h2>Notes</h2><p>
+ Before you can use <code class="command">CREATE EXTENSION</code> to load an extension
+ into a database, the extension's supporting files must be installed.
+ Information about installing the extensions supplied with
+ <span class="productname">PostgreSQL</span> can be found in
+ <a class="link" href="contrib.html" title="Appendix F. Additional Supplied Modules">Additional Supplied Modules</a>.
+ </p><p>
+ The extensions currently available for loading can be identified from the
+ <a class="link" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions"><code class="structname">pg_available_extensions</code></a>
+ or
+ <a class="link" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions"><code class="structname">pg_available_extension_versions</code></a>
+ system views.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Installing an extension as superuser requires trusting that the
+ extension's author wrote the extension installation script in a secure
+ fashion. It is not terribly difficult for a malicious user to create
+ trojan-horse objects that will compromise later execution of a
+ carelessly-written extension script, allowing that user to acquire
+ superuser privileges. However, trojan-horse objects are only hazardous
+ if they are in the <code class="varname">search_path</code> during script
+ execution, meaning that they are in the extension's installation target
+ schema or in the schema of some extension it depends on. Therefore, a
+ good rule of thumb when dealing with extensions whose scripts have not
+ been carefully vetted is to install them only into schemas for which
+ CREATE privilege has not been and will not be granted to any untrusted
+ users. Likewise for any extensions they depend on.
+ </p><p>
+ The extensions supplied with <span class="productname">PostgreSQL</span> are
+ believed to be secure against installation-time attacks of this sort,
+ except for a few that depend on other extensions. As stated in the
+ documentation for those extensions, they should be installed into secure
+ schemas, or installed into the same schemas as the extensions they
+ depend on, or both.
+ </p></div><p>
+ For information about writing new extensions, see
+ <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.64.8"><h2>Examples</h2><p>
+ Install the <a class="link" href="hstore.html" title="F.18. hstore">hstore</a> extension into the
+ current database, placing its objects in schema <code class="literal">addons</code>:
+</p><pre class="programlisting">
+CREATE EXTENSION hstore SCHEMA addons;
+</pre><p>
+ Another way to accomplish the same thing:
+</p><pre class="programlisting">
+SET search_path = addons;
+CREATE EXTENSION hstore;
+</pre></div><div class="refsect1" id="id-1.9.3.64.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE EXTENSION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.64.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterextension.html" title="ALTER EXTENSION"><span class="refentrytitle">ALTER EXTENSION</span></a>, <a class="xref" href="sql-dropextension.html" title="DROP EXTENSION"><span class="refentrytitle">DROP EXTENSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE EVENT TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE FOREIGN DATA WRAPPER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createforeigndatawrapper.html b/doc/src/sgml/html/sql-createforeigndatawrapper.html
new file mode 100644
index 0000000..1942f19
--- /dev/null
+++ b/doc/src/sgml/html/sql-createforeigndatawrapper.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE FOREIGN DATA WRAPPER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createextension.html" title="CREATE EXTENSION" /><link rel="next" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE FOREIGN DATA WRAPPER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createextension.html" title="CREATE EXTENSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEFOREIGNDATAWRAPPER"><div class="titlepage"></div><a id="id-1.9.3.65.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></h2><p>CREATE FOREIGN DATA WRAPPER — define a new foreign-data wrapper</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE FOREIGN DATA WRAPPER <em class="replaceable"><code>name</code></em>
+ [ HANDLER <em class="replaceable"><code>handler_function</code></em> | NO HANDLER ]
+ [ VALIDATOR <em class="replaceable"><code>validator_function</code></em> | NO VALIDATOR ]
+ [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.65.5"><h2>Description</h2><p>
+ <code class="command">CREATE FOREIGN DATA WRAPPER</code> creates a new
+ foreign-data wrapper. The user who defines a foreign-data wrapper
+ becomes its owner.
+ </p><p>
+ The foreign-data wrapper name must be unique within the database.
+ </p><p>
+ Only superusers can create foreign-data wrappers.
+ </p></div><div class="refsect1" id="id-1.9.3.65.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the foreign-data wrapper to be created.
+ </p></dd><dt><span class="term"><code class="literal">HANDLER <em class="replaceable"><code>handler_function</code></em></code></span></dt><dd><p><em class="replaceable"><code>handler_function</code></em> is the
+ name of a previously registered function that will be called to
+ retrieve the execution functions for foreign tables.
+ The handler function must take no arguments, and
+ its return type must be <code class="type">fdw_handler</code>.
+ </p><p>
+ It is possible to create a foreign-data wrapper with no handler
+ function, but foreign tables using such a wrapper can only be declared,
+ not accessed.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATOR <em class="replaceable"><code>validator_function</code></em></code></span></dt><dd><p><em class="replaceable"><code>validator_function</code></em>
+ is the name of a previously registered function that will be called to
+ check the generic options given to the foreign-data wrapper, as
+ well as options for foreign servers, user mappings and foreign tables
+ using the foreign-data wrapper. If no validator function or <code class="literal">NO
+ VALIDATOR</code> is specified, then options will not be
+ checked at creation time. (Foreign-data wrappers will possibly
+ ignore or reject invalid option specifications at run time,
+ depending on the implementation.) The validator function must
+ take two arguments: one of type <code class="type">text[]</code>, which will
+ contain the array of options as stored in the system catalogs,
+ and one of type <code class="type">oid</code>, which will be the OID of the
+ system catalog containing the options. The return type is ignored;
+ the function should report invalid options using the
+ <code class="function">ereport(ERROR)</code> function.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] )</code></span></dt><dd><p>
+ This clause specifies options for the new foreign-data wrapper.
+ The allowed option names and values are specific to each foreign
+ data wrapper and are validated using the foreign-data wrapper's
+ validator function. Option names must be unique.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.65.7"><h2>Notes</h2><p>
+ <span class="productname">PostgreSQL</span>'s foreign-data functionality is still under
+ active development. Optimization of queries is primitive (and mostly left
+ to the wrapper, too). Thus, there is considerable room for future
+ performance improvements.
+ </p></div><div class="refsect1" id="id-1.9.3.65.8"><h2>Examples</h2><p>
+ Create a useless foreign-data wrapper <code class="literal">dummy</code>:
+</p><pre class="programlisting">
+CREATE FOREIGN DATA WRAPPER dummy;
+</pre><p>
+ </p><p>
+ Create a foreign-data wrapper <code class="literal">file</code> with
+ handler function <code class="literal">file_fdw_handler</code>:
+</p><pre class="programlisting">
+CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
+</pre><p>
+ </p><p>
+ Create a foreign-data wrapper <code class="literal">mywrapper</code> with some
+ options:
+</p><pre class="programlisting">
+CREATE FOREIGN DATA WRAPPER mywrapper
+ OPTIONS (debug 'true');
+</pre></div><div class="refsect1" id="id-1.9.3.65.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE FOREIGN DATA WRAPPER</code> conforms to ISO/IEC
+ 9075-9 (SQL/MED), with the exception that the <code class="literal">HANDLER</code>
+ and <code class="literal">VALIDATOR</code> clauses are extensions and the standard
+ clauses <code class="literal">LIBRARY</code> and <code class="literal">LANGUAGE</code>
+ are not implemented in <span class="productname">PostgreSQL</span>.
+ </p><p>
+ Note, however, that the SQL/MED functionality as a whole is not yet
+ conforming.
+ </p></div><div class="refsect1" id="id-1.9.3.65.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER"><span class="refentrytitle">ALTER FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER"><span class="refentrytitle">DROP FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>, <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>, <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createextension.html" title="CREATE EXTENSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE EXTENSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE FOREIGN TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createforeigntable.html b/doc/src/sgml/html/sql-createforeigntable.html
new file mode 100644
index 0000000..1572f71
--- /dev/null
+++ b/doc/src/sgml/html/sql-createforeigntable.html
@@ -0,0 +1,244 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE FOREIGN TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER" /><link rel="next" href="sql-createfunction.html" title="CREATE FUNCTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE FOREIGN TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createfunction.html" title="CREATE FUNCTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEFOREIGNTABLE"><div class="titlepage"></div><a id="id-1.9.3.66.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE FOREIGN TABLE</span></h2><p>CREATE FOREIGN TABLE — define a new foreign table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE FOREIGN TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em> ( [
+ { <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ] [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ | <em class="replaceable"><code>table_constraint</code></em> }
+ [, ... ]
+] )
+[ INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] ) ]
+ SERVER <em class="replaceable"><code>server_name</code></em>
+[ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
+
+CREATE FOREIGN TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
+ PARTITION OF <em class="replaceable"><code>parent_table</code></em> [ (
+ { <em class="replaceable"><code>column_name</code></em> [ WITH OPTIONS ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ | <em class="replaceable"><code>table_constraint</code></em> }
+ [, ... ]
+) ]
+{ FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }
+ SERVER <em class="replaceable"><code>server_name</code></em>
+[ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
+
+<span class="phrase">where <em class="replaceable"><code>column_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ NOT NULL |
+ NULL |
+ CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
+ DEFAULT <em class="replaceable"><code>default_expr</code></em> |
+ GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) STORED }
+
+<span class="phrase">and <em class="replaceable"><code>table_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ]
+
+<span class="phrase">and <em class="replaceable"><code>partition_bound_spec</code></em> is:</span>
+
+IN ( <em class="replaceable"><code>partition_bound_expr</code></em> [, ...] ) |
+FROM ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] )
+ TO ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] ) |
+WITH ( MODULUS <em class="replaceable"><code>numeric_literal</code></em>, REMAINDER <em class="replaceable"><code>numeric_literal</code></em> )
+</pre></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE FOREIGN TABLE</code> creates a new foreign table
+ in the current database. The table will be owned by the user issuing the
+ command.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE FOREIGN TABLE
+ myschema.mytable ...</code>) then the table is created in the specified
+ schema. Otherwise it is created in the current schema.
+ The name of the foreign table must be
+ distinct from the name of any other relation (table, sequence, index, view,
+ materialized view, or foreign table) in the same schema.
+ </p><p>
+ <code class="command">CREATE FOREIGN TABLE</code> also automatically creates a data
+ type that represents the composite type corresponding to one row of
+ the foreign table. Therefore, foreign tables cannot have the same
+ name as any existing data type in the same schema.
+ </p><p>
+ If <code class="literal">PARTITION OF</code> clause is specified then the table is
+ created as a partition of <code class="literal">parent_table</code> with specified
+ bounds.
+ </p><p>
+ To be able to create a foreign table, you must have <code class="literal">USAGE</code>
+ privilege on the foreign server, as well as <code class="literal">USAGE</code>
+ privilege on all column types used in the table.
+ </p></div><div class="refsect1" id="id-1.9.3.66.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a relation with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing relation is anything like the one that would have been
+ created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column to be created in the new table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The data type of the column. This can include array
+ specifiers. For more information on the data types supported by
+ <span class="productname">PostgreSQL</span>, refer to <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>.
+ </p></dd><dt><span class="term"><code class="literal">COLLATE <em class="replaceable"><code>collation</code></em></code></span></dt><dd><p>
+ The <code class="literal">COLLATE</code> clause assigns a collation to
+ the column (which must be of a collatable data type).
+ If not specified, the column data type's default collation is used.
+ </p></dd><dt><span class="term"><code class="literal">INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] )</code></span></dt><dd><p>
+ The optional <code class="literal">INHERITS</code> clause specifies a list of
+ tables from which the new foreign table automatically inherits
+ all columns. Parent tables can be plain tables or foreign tables.
+ See the similar form of
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> for more details.
+ </p></dd><dt><span class="term"><code class="literal">PARTITION OF <em class="replaceable"><code>parent_table</code></em> { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }</code></span></dt><dd><p>
+ This form can be used to create the foreign table as partition of
+ the given parent table with specified partition bound values.
+ See the similar form of
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> for more details.
+ Note that it is currently not allowed to create the foreign table as a
+ partition of the parent table if there are <code class="literal">UNIQUE</code>
+ indexes on the parent table. (See also
+ <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ATTACH PARTITION</code></a>.)
+ </p></dd><dt><span class="term"><code class="literal">CONSTRAINT <em class="replaceable"><code>constraint_name</code></em></code></span></dt><dd><p>
+ An optional name for a column or table constraint. If the
+ constraint is violated, the constraint name is present in error messages,
+ so constraint names like <code class="literal">col must be positive</code> can be used
+ to communicate helpful constraint information to client applications.
+ (Double-quotes are needed to specify constraint names that contain spaces.)
+ If a constraint name is not specified, the system generates a name.
+ </p></dd><dt><span class="term"><code class="literal">NOT NULL</code></span></dt><dd><p>
+ The column is not allowed to contain null values.
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ The column is allowed to contain null values. This is the default.
+ </p><p>
+ This clause is only provided for compatibility with
+ non-standard SQL databases. Its use is discouraged in new
+ applications.
+ </p></dd><dt><span class="term"><code class="literal">CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] </code></span></dt><dd><p>
+ The <code class="literal">CHECK</code> clause specifies an expression producing a
+ Boolean result which each row in the foreign table is expected
+ to satisfy; that is, the expression should produce TRUE or UNKNOWN,
+ never FALSE, for all rows in the foreign table.
+ A check constraint specified as a column constraint should
+ reference that column's value only, while an expression
+ appearing in a table constraint can reference multiple columns.
+ </p><p>
+ Currently, <code class="literal">CHECK</code> expressions cannot contain
+ subqueries nor refer to variables other than columns of the
+ current row. The system column <code class="literal">tableoid</code>
+ may be referenced, but not any other system column.
+ </p><p>
+ A constraint marked with <code class="literal">NO INHERIT</code> will not propagate to
+ child tables.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT
+ <em class="replaceable"><code>default_expr</code></em></code></span></dt><dd><p>
+ The <code class="literal">DEFAULT</code> clause assigns a default data value for
+ the column whose column definition it appears within. The value
+ is any variable-free expression (subqueries and cross-references
+ to other columns in the current table are not allowed). The
+ data type of the default expression must match the data type of the
+ column.
+ </p><p>
+ The default expression will be used in any insert operation that
+ does not specify a value for the column. If there is no default
+ for a column, then the default is null.
+ </p></dd><dt><span class="term"><code class="literal">GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) STORED</code><a id="id-1.9.3.66.6.2.13.1.2" class="indexterm"></a></span></dt><dd><p>
+ This clause creates the column as a <em class="firstterm">generated
+ column</em>. The column cannot be written to, and when read the
+ result of the specified expression will be returned.
+ </p><p>
+ The keyword <code class="literal">STORED</code> is required to signify that the
+ column will be computed on write. (The computed value will be presented
+ to the foreign-data wrapper for storage and must be returned on
+ reading.)
+ </p><p>
+ The generation expression can refer to other columns in the table, but
+ not other generated columns. Any functions and operators used must be
+ immutable. References to other tables are not allowed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ The name of an existing foreign server to use for the foreign table.
+ For details on defining a server, see <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ...] )</code></span></dt><dd><p>
+ Options to be associated with the new foreign table or one of its
+ columns.
+ The allowed option names and values are specific to each foreign
+ data wrapper and are validated using the foreign-data wrapper's
+ validator function. Duplicate option names are not allowed (although
+ it's OK for a table option and a column option to have the same name).
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.66.7"><h2>Notes</h2><p>
+ Constraints on foreign tables (such as <code class="literal">CHECK</code>
+ or <code class="literal">NOT NULL</code> clauses) are not enforced by the
+ core <span class="productname">PostgreSQL</span> system, and most foreign data wrappers
+ do not attempt to enforce them either; that is, the constraint is
+ simply assumed to hold true. There would be little point in such
+ enforcement since it would only apply to rows inserted or updated via
+ the foreign table, and not to rows modified by other means, such as
+ directly on the remote server. Instead, a constraint attached to a
+ foreign table should represent a constraint that is being enforced by
+ the remote server.
+ </p><p>
+ Some special-purpose foreign data wrappers might be the only access
+ mechanism for the data they access, and in that case it might be
+ appropriate for the foreign data wrapper itself to perform constraint
+ enforcement. But you should not assume that a wrapper does that
+ unless its documentation says so.
+ </p><p>
+ Although <span class="productname">PostgreSQL</span> does not attempt to enforce
+ constraints on foreign tables, it does assume that they are correct
+ for purposes of query optimization. If there are rows visible in the
+ foreign table that do not satisfy a declared constraint, queries on
+ the table might produce errors or incorrect answers. It is the user's
+ responsibility to ensure that the constraint definition matches
+ reality.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ When a foreign table is used as a partition of a partitioned table,
+ there is an implicit constraint that its contents must satisfy the
+ partitioning rule. Again, it is the user's responsibility to ensure
+ that that is true, which is best done by installing a matching
+ constraint on the remote server.
+ </p></div><p>
+ Within a partitioned table containing foreign-table partitions,
+ an <code class="command">UPDATE</code> that changes the partition key value can
+ cause a row to be moved from a local partition to a foreign-table
+ partition, provided the foreign data wrapper supports tuple routing.
+ However, it is not currently possible to move a row from a
+ foreign-table partition to another partition.
+ An <code class="command">UPDATE</code> that would require doing that will fail
+ due to the partitioning constraint, assuming that that is properly
+ enforced by the remote server.
+ </p><p>
+ Similar considerations apply to generated columns. Stored generated
+ columns are computed on insert or update on the local
+ <span class="productname">PostgreSQL</span> server and handed to the
+ foreign-data wrapper for writing out to the foreign data store, but it is
+ not enforced that a query of the foreign table returns values for stored
+ generated columns that are consistent with the generation expression.
+ Again, this might result in incorrect query results.
+ </p></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-EXAMPLES"><h2>Examples</h2><p>
+ Create foreign table <code class="structname">films</code>, which will be accessed through
+ the server <code class="structname">film_server</code>:
+
+</p><pre class="programlisting">
+CREATE FOREIGN TABLE films (
+ code char(5) NOT NULL,
+ title varchar(40) NOT NULL,
+ did integer NOT NULL,
+ date_prod date,
+ kind varchar(10),
+ len interval hour to minute
+)
+SERVER film_server;
+</pre><p>
+ Create foreign table <code class="structname">measurement_y2016m07</code>, which will be
+ accessed through the server <code class="structname">server_07</code>, as a partition
+ of the range partitioned table <code class="structname">measurement</code>:
+
+</p><pre class="programlisting">
+CREATE FOREIGN TABLE measurement_y2016m07
+ PARTITION OF measurement FOR VALUES FROM ('2016-07-01') TO ('2016-08-01')
+ SERVER server_07;
+</pre></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE FOREIGN TABLE</code> command largely conforms to the
+ <acronym class="acronym">SQL</acronym> standard; however, much as with
+ <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>,
+ <code class="literal">NULL</code> constraints and zero-column foreign tables are permitted.
+ The ability to specify column default values is also
+ a <span class="productname">PostgreSQL</span> extension. Table inheritance, in the form
+ defined by <span class="productname">PostgreSQL</span>, is nonstandard.
+ </p></div><div class="refsect1" id="id-1.9.3.66.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE"><span class="refentrytitle">ALTER FOREIGN TABLE</span></a>, <a class="xref" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE"><span class="refentrytitle">DROP FOREIGN TABLE</span></a>, <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>, <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>, <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createfunction.html" title="CREATE FUNCTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE FOREIGN DATA WRAPPER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE FUNCTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createfunction.html b/doc/src/sgml/html/sql-createfunction.html
new file mode 100644
index 0000000..db7a676
--- /dev/null
+++ b/doc/src/sgml/html/sql-createfunction.html
@@ -0,0 +1,554 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE FUNCTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE" /><link rel="next" href="sql-creategroup.html" title="CREATE GROUP" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE FUNCTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-creategroup.html" title="CREATE GROUP">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEFUNCTION"><div class="titlepage"></div><a id="id-1.9.3.67.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE FUNCTION</span></h2><p>CREATE FUNCTION — define a new function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] FUNCTION
+ <em class="replaceable"><code>name</code></em> ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ { DEFAULT | = } <em class="replaceable"><code>default_expr</code></em> ] [, ...] ] )
+ [ RETURNS <em class="replaceable"><code>rettype</code></em>
+ | RETURNS TABLE ( <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>column_type</code></em> [, ...] ) ]
+ { LANGUAGE <em class="replaceable"><code>lang_name</code></em>
+ | TRANSFORM { FOR TYPE <em class="replaceable"><code>type_name</code></em> } [, ... ]
+ | WINDOW
+ | { IMMUTABLE | STABLE | VOLATILE }
+ | [ NOT ] LEAKPROOF
+ | { CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT }
+ | { [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER }
+ | PARALLEL { UNSAFE | RESTRICTED | SAFE }
+ | COST <em class="replaceable"><code>execution_cost</code></em>
+ | ROWS <em class="replaceable"><code>result_rows</code></em>
+ | SUPPORT <em class="replaceable"><code>support_function</code></em>
+ | SET <em class="replaceable"><code>configuration_parameter</code></em> { TO <em class="replaceable"><code>value</code></em> | = <em class="replaceable"><code>value</code></em> | FROM CURRENT }
+ | AS '<em class="replaceable"><code>definition</code></em>'
+ | AS '<em class="replaceable"><code>obj_file</code></em>', '<em class="replaceable"><code>link_symbol</code></em>'
+ | <em class="replaceable"><code>sql_body</code></em>
+ } ...
+</pre></div><div class="refsect1" id="SQL-CREATEFUNCTION-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE FUNCTION</code> defines a new function.
+ <code class="command">CREATE OR REPLACE FUNCTION</code> will either create a
+ new function, or replace an existing definition.
+ To be able to define a function, the user must have the
+ <code class="literal">USAGE</code> privilege on the language.
+ </p><p>
+ If a schema name is included, then the function is created in the
+ specified schema. Otherwise it is created in the current schema.
+ The name of the new function must not match any existing function or procedure
+ with the same input argument types in the same schema. However,
+ functions and procedures of different argument types can share a name (this is
+ called <em class="firstterm">overloading</em>).
+ </p><p>
+ To replace the current definition of an existing function, use
+ <code class="command">CREATE OR REPLACE FUNCTION</code>. It is not possible
+ to change the name or argument types of a function this way (if you
+ tried, you would actually be creating a new, distinct function).
+ Also, <code class="command">CREATE OR REPLACE FUNCTION</code> will not let
+ you change the return type of an existing function. To do that,
+ you must drop and recreate the function. (When using <code class="literal">OUT</code>
+ parameters, that means you cannot change the types of any
+ <code class="literal">OUT</code> parameters except by dropping the function.)
+ </p><p>
+ When <code class="command">CREATE OR REPLACE FUNCTION</code> is used to replace an
+ existing function, the ownership and permissions of the function
+ do not change. All other function properties are assigned the
+ values specified or implied in the command. You must own the function
+ to replace it (this includes being a member of the owning role).
+ </p><p>
+ If you drop and then recreate a function, the new function is not
+ the same entity as the old; you will have to drop existing rules, views,
+ triggers, etc. that refer to the old function. Use
+ <code class="command">CREATE OR REPLACE FUNCTION</code> to change a function
+ definition without breaking objects that refer to the function.
+ Also, <code class="command">ALTER FUNCTION</code> can be used to change most of the
+ auxiliary properties of an existing function.
+ </p><p>
+ The user that creates the function becomes the owner of the function.
+ </p><p>
+ To be able to create a function, you must have <code class="literal">USAGE</code>
+ privilege on the argument types and the return type.
+ </p><p>
+ Refer to <a class="xref" href="xfunc.html" title="38.3. User-Defined Functions">Section 38.3</a> for further information on writing
+ functions.
+ </p></div><div class="refsect1" id="id-1.9.3.67.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the function to create.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Only <code class="literal">OUT</code> arguments can follow a <code class="literal">VARIADIC</code> one.
+ Also, <code class="literal">OUT</code> and <code class="literal">INOUT</code> arguments cannot be used
+ together with the <code class="literal">RETURNS TABLE</code> notation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument. Some languages (including SQL and PL/pgSQL)
+ let you use the name in the function body. For other languages the
+ name of an input argument is just extra documentation, so far as
+ the function itself is concerned; but you can use input argument names
+ when calling a function to improve readability (see <a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a>). In any case, the name
+ of an output argument is significant, because it defines the column
+ name in the result row type. (If you omit the name for an output
+ argument, the system will choose a default column name.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the function's arguments (optionally
+ schema-qualified), if any. The argument types can be base, composite,
+ or domain types, or can reference the type of a table column.
+ </p><p>
+ Depending on the implementation language it might also be allowed
+ to specify <span class="quote">“<span class="quote">pseudo-types</span>”</span> such as <code class="type">cstring</code>.
+ Pseudo-types indicate that the actual argument type is either
+ incompletely specified, or outside the set of ordinary SQL data types.
+ </p><p>
+ The type of a column is referenced by writing
+ <code class="literal"><em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em>%TYPE</code>.
+ Using this feature can sometimes help make a function independent of
+ changes to the definition of a table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>default_expr</code></em></span></dt><dd><p>
+ An expression to be used as default value if the parameter is
+ not specified. The expression has to be coercible to the
+ argument type of the parameter.
+ Only input (including <code class="literal">INOUT</code>) parameters can have a default
+ value. All input parameters following a
+ parameter with a default value must have default values as well.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>rettype</code></em></span></dt><dd><p>
+ The return data type (optionally schema-qualified). The return type
+ can be a base, composite, or domain type,
+ or can reference the type of a table column.
+ Depending on the implementation language it might also be allowed
+ to specify <span class="quote">“<span class="quote">pseudo-types</span>”</span> such as <code class="type">cstring</code>.
+ If the function is not supposed to return a value, specify
+ <code class="type">void</code> as the return type.
+ </p><p>
+ When there are <code class="literal">OUT</code> or <code class="literal">INOUT</code> parameters,
+ the <code class="literal">RETURNS</code> clause can be omitted. If present, it
+ must agree with the result type implied by the output parameters:
+ <code class="literal">RECORD</code> if there are multiple output parameters, or
+ the same type as the single output parameter.
+ </p><p>
+ The <code class="literal">SETOF</code>
+ modifier indicates that the function will return a set of
+ items, rather than a single item.
+ </p><p>
+ The type of a column is referenced by writing
+ <code class="literal"><em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em>%TYPE</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of an output column in the <code class="literal">RETURNS TABLE</code>
+ syntax. This is effectively another way of declaring a named
+ <code class="literal">OUT</code> parameter, except that <code class="literal">RETURNS TABLE</code>
+ also implies <code class="literal">RETURNS SETOF</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_type</code></em></span></dt><dd><p>
+ The data type of an output column in the <code class="literal">RETURNS TABLE</code>
+ syntax.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language that the function is implemented in.
+ It can be <code class="literal">sql</code>, <code class="literal">c</code>,
+ <code class="literal">internal</code>, or the name of a user-defined
+ procedural language, e.g., <code class="literal">plpgsql</code>. The default is
+ <code class="literal">sql</code> if <em class="replaceable"><code>sql_body</code></em> is specified. Enclosing the
+ name in single quotes is deprecated and requires matching case.
+ </p></dd><dt><span class="term"><code class="literal">TRANSFORM { FOR TYPE <em class="replaceable"><code>type_name</code></em> } [, ... ] }</code></span></dt><dd><p>
+ Lists which transforms a call to the function should apply. Transforms
+ convert between SQL types and language-specific data types;
+ see <a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a>. Procedural language
+ implementations usually have hardcoded knowledge of the built-in types,
+ so those don't need to be listed here. If a procedural language
+ implementation does not know how to handle a type and no transform is
+ supplied, it will fall back to a default behavior for converting data
+ types, but this depends on the implementation.
+ </p></dd><dt><span class="term"><code class="literal">WINDOW</code></span></dt><dd><p><code class="literal">WINDOW</code> indicates that the function is a
+ <em class="firstterm">window function</em> rather than a plain function.
+ This is currently only useful for functions written in C.
+ The <code class="literal">WINDOW</code> attribute cannot be changed when
+ replacing an existing function definition.
+ </p></dd><dt><span class="term"><code class="literal">IMMUTABLE</code><br /></span><span class="term"><code class="literal">STABLE</code><br /></span><span class="term"><code class="literal">VOLATILE</code></span></dt><dd><p>
+ These attributes inform the query optimizer about the behavior
+ of the function. At most one choice
+ can be specified. If none of these appear,
+ <code class="literal">VOLATILE</code> is the default assumption.
+ </p><p><code class="literal">IMMUTABLE</code> indicates that the function
+ cannot modify the database and always
+ returns the same result when given the same argument values; that
+ is, it does not do database lookups or otherwise use information not
+ directly present in its argument list. If this option is given,
+ any call of the function with all-constant arguments can be
+ immediately replaced with the function value.
+ </p><p><code class="literal">STABLE</code> indicates that the function
+ cannot modify the database,
+ and that within a single table scan it will consistently
+ return the same result for the same argument values, but that its
+ result could change across SQL statements. This is the appropriate
+ selection for functions whose results depend on database lookups,
+ parameter variables (such as the current time zone), etc. (It is
+ inappropriate for <code class="literal">AFTER</code> triggers that wish to
+ query rows modified by the current command.) Also note
+ that the <code class="function">current_timestamp</code> family of functions qualify
+ as stable, since their values do not change within a transaction.
+ </p><p><code class="literal">VOLATILE</code> indicates that the function value can
+ change even within a single table scan, so no optimizations can be
+ made. Relatively few database functions are volatile in this sense;
+ some examples are <code class="literal">random()</code>, <code class="literal">currval()</code>,
+ <code class="literal">timeofday()</code>. But note that any function that has
+ side-effects must be classified volatile, even if its result is quite
+ predictable, to prevent calls from being optimized away; an example is
+ <code class="literal">setval()</code>.
+ </p><p>
+ For additional details see <a class="xref" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Section 38.7</a>.
+ </p></dd><dt><span class="term"><code class="literal">LEAKPROOF</code></span></dt><dd><p>
+ <code class="literal">LEAKPROOF</code> indicates that the function has no side
+ effects. It reveals no information about its arguments other than by
+ its return value. For example, a function which throws an error message
+ for some argument values but not others, or which includes the argument
+ values in any error message, is not leakproof. This affects how the
+ system executes queries against views created with the
+ <code class="literal">security_barrier</code> option or tables with row level
+ security enabled. The system will enforce conditions from security
+ policies and security barrier views before any user-supplied conditions
+ from the query itself that contain non-leakproof functions, in order to
+ prevent the inadvertent exposure of data. Functions and operators
+ marked as leakproof are assumed to be trustworthy, and may be executed
+ before conditions from security policies and security barrier views.
+ In addition, functions which do not take arguments or which are not
+ passed any arguments from the security barrier view or table do not have
+ to be marked as leakproof to be executed before security conditions. See
+ <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a> and <a class="xref" href="rules-privileges.html" title="41.5. Rules and Privileges">Section 41.5</a>.
+ This option can only be set by the superuser.
+ </p></dd><dt><span class="term"><code class="literal">CALLED ON NULL INPUT</code><br /></span><span class="term"><code class="literal">RETURNS NULL ON NULL INPUT</code><br /></span><span class="term"><code class="literal">STRICT</code></span></dt><dd><p><code class="literal">CALLED ON NULL INPUT</code> (the default) indicates
+ that the function will be called normally when some of its
+ arguments are null. It is then the function author's
+ responsibility to check for null values if necessary and respond
+ appropriately.
+ </p><p><code class="literal">RETURNS NULL ON NULL INPUT</code> or
+ <code class="literal">STRICT</code> indicates that the function always
+ returns null whenever any of its arguments are null. If this
+ parameter is specified, the function is not executed when there
+ are null arguments; instead a null result is assumed
+ automatically.
+ </p></dd><dt><span class="term"><code class="literal">[<span class="optional">EXTERNAL</span>] SECURITY INVOKER</code><br /></span><span class="term"><code class="literal">[<span class="optional">EXTERNAL</span>] SECURITY DEFINER</code></span></dt><dd><p><code class="literal">SECURITY INVOKER</code> indicates that the function
+ is to be executed with the privileges of the user that calls it.
+ That is the default. <code class="literal">SECURITY DEFINER</code>
+ specifies that the function is to be executed with the
+ privileges of the user that owns it.
+ </p><p>
+ The key word <code class="literal">EXTERNAL</code> is allowed for SQL
+ conformance, but it is optional since, unlike in SQL, this feature
+ applies to all functions not only external ones.
+ </p></dd><dt><span class="term"><code class="literal">PARALLEL</code></span></dt><dd><p><code class="literal">PARALLEL UNSAFE</code> indicates that the function
+ can't be executed in parallel mode and the presence of such a
+ function in an SQL statement forces a serial execution plan. This is
+ the default. <code class="literal">PARALLEL RESTRICTED</code> indicates that
+ the function can be executed in parallel mode, but the execution is
+ restricted to parallel group leader. <code class="literal">PARALLEL SAFE</code>
+ indicates that the function is safe to run in parallel mode without
+ restriction.
+ </p><p>
+ Functions should be labeled parallel unsafe if they modify any database
+ state, or if they make changes to the transaction such as using
+ sub-transactions, or if they access sequences or attempt to make
+ persistent changes to settings (e.g., <code class="literal">setval</code>). They should
+ be labeled as parallel restricted if they access temporary tables,
+ client connection state, cursors, prepared statements, or miscellaneous
+ backend-local state which the system cannot synchronize in parallel mode
+ (e.g., <code class="literal">setseed</code> cannot be executed other than by the group
+ leader because a change made by another process would not be reflected
+ in the leader). In general, if a function is labeled as being safe when
+ it is restricted or unsafe, or if it is labeled as being restricted when
+ it is in fact unsafe, it may throw errors or produce wrong answers
+ when used in a parallel query. C-language functions could in theory
+ exhibit totally undefined behavior if mislabeled, since there is no way
+ for the system to protect itself against arbitrary C code, but in most
+ likely cases the result will be no worse than for any other function.
+ If in doubt, functions should be labeled as <code class="literal">UNSAFE</code>, which is
+ the default.
+ </p></dd><dt><span class="term"><code class="literal">COST</code> <em class="replaceable"><code>execution_cost</code></em></span></dt><dd><p>
+ A positive number giving the estimated execution cost for the function,
+ in units of <a class="xref" href="runtime-config-query.html#GUC-CPU-OPERATOR-COST">cpu_operator_cost</a>. If the function
+ returns a set, this is the cost per returned row. If the cost is
+ not specified, 1 unit is assumed for C-language and internal functions,
+ and 100 units for functions in all other languages. Larger values
+ cause the planner to try to avoid evaluating the function more often
+ than necessary.
+ </p></dd><dt><span class="term"><code class="literal">ROWS</code> <em class="replaceable"><code>result_rows</code></em></span></dt><dd><p>
+ A positive number giving the estimated number of rows that the planner
+ should expect the function to return. This is only allowed when the
+ function is declared to return a set. The default assumption is
+ 1000 rows.
+ </p></dd><dt><span class="term"><code class="literal">SUPPORT</code> <em class="replaceable"><code>support_function</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a <em class="firstterm">planner support
+ function</em> to use for this function. See
+ <a class="xref" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Section 38.11</a> for details.
+ You must be superuser to use this option.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The <code class="literal">SET</code> clause causes the specified configuration
+ parameter to be set to the specified value when the function is
+ entered, and then restored to its prior value when the function exits.
+ <code class="literal">SET FROM CURRENT</code> saves the value of the parameter that
+ is current when <code class="command">CREATE FUNCTION</code> is executed as the value
+ to be applied when the function is entered.
+ </p><p>
+ If a <code class="literal">SET</code> clause is attached to a function, then
+ the effects of a <code class="command">SET LOCAL</code> command executed inside the
+ function for the same variable are restricted to the function: the
+ configuration parameter's prior value is still restored at function exit.
+ However, an ordinary
+ <code class="command">SET</code> command (without <code class="literal">LOCAL</code>) overrides the
+ <code class="literal">SET</code> clause, much as it would do for a previous <code class="command">SET
+ LOCAL</code> command: the effects of such a command will persist after
+ function exit, unless the current transaction is rolled back.
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and
+ <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information about allowed parameter names and values.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>definition</code></em></span></dt><dd><p>
+ A string constant defining the function; the meaning depends on the
+ language. It can be an internal function name, the path to an
+ object file, an SQL command, or text in a procedural language.
+ </p><p>
+ It is often helpful to use dollar quoting (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) to write the function definition
+ string, rather than the normal single quote syntax. Without dollar
+ quoting, any single quotes or backslashes in the function definition must
+ be escaped by doubling them.
+ </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>obj_file</code></em>, <em class="replaceable"><code>link_symbol</code></em></code></span></dt><dd><p>
+ This form of the <code class="literal">AS</code> clause is used for
+ dynamically loadable C language functions when the function name
+ in the C language source code is not the same as the name of
+ the SQL function. The string <em class="replaceable"><code>obj_file</code></em> is the name of the shared
+ library file containing the compiled C function, and is interpreted
+ as for the <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> command. The string
+ <em class="replaceable"><code>link_symbol</code></em> is the
+ function's link symbol, that is, the name of the function in the C
+ language source code. If the link symbol is omitted, it is assumed to
+ be the same as the name of the SQL function being defined. The C names
+ of all functions must be different, so you must give overloaded C
+ functions different C names (for example, use the argument types as
+ part of the C names).
+ </p><p>
+ When repeated <code class="command">CREATE FUNCTION</code> calls refer to
+ the same object file, the file is only loaded once per session.
+ To unload and
+ reload the file (perhaps during development), start a new session.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sql_body</code></em></span></dt><dd><p>
+ The body of a <code class="literal">LANGUAGE SQL</code> function. This can
+ either be a single statement
+</p><pre class="programlisting">
+RETURN <em class="replaceable"><code>expression</code></em>
+</pre><p>
+ or a block
+</p><pre class="programlisting">
+BEGIN ATOMIC
+ <em class="replaceable"><code>statement</code></em>;
+ <em class="replaceable"><code>statement</code></em>;
+ ...
+ <em class="replaceable"><code>statement</code></em>;
+END
+</pre><p>
+ </p><p>
+ This is similar to writing the text of the function body as a string
+ constant (see <em class="replaceable"><code>definition</code></em> above), but there
+ are some differences: This form only works for <code class="literal">LANGUAGE
+ SQL</code>, the string constant form works for all languages. This
+ form is parsed at function definition time, the string constant form is
+ parsed at execution time; therefore this form cannot support
+ polymorphic argument types and other constructs that are not resolvable
+ at function definition time. This form tracks dependencies between the
+ function and objects used in the function body, so <code class="literal">DROP
+ ... CASCADE</code> will work correctly, whereas the form using
+ string literals may leave dangling functions. Finally, this form is
+ more compatible with the SQL standard and other SQL implementations.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATEFUNCTION-OVERLOADING"><h2>Overloading</h2><p>
+ <span class="productname">PostgreSQL</span> allows function
+ <em class="firstterm">overloading</em>; that is, the same name can be
+ used for several different functions so long as they have distinct
+ input argument types. Whether or not you use it, this capability entails
+ security precautions when calling functions in databases where some users
+ mistrust other users; see <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>.
+ </p><p>
+ Two functions are considered the same if they have the same names and
+ <span class="emphasis"><em>input</em></span> argument types, ignoring any <code class="literal">OUT</code>
+ parameters. Thus for example these declarations conflict:
+</p><pre class="programlisting">
+CREATE FUNCTION foo(int) ...
+CREATE FUNCTION foo(int, out text) ...
+</pre><p>
+ </p><p>
+ Functions that have different argument type lists will not be considered
+ to conflict at creation time, but if defaults are provided they might
+ conflict in use. For example, consider
+</p><pre class="programlisting">
+CREATE FUNCTION foo(int) ...
+CREATE FUNCTION foo(int, int default 42) ...
+</pre><p>
+ A call <code class="literal">foo(10)</code> will fail due to the ambiguity about which
+ function should be called.
+ </p></div><div class="refsect1" id="SQL-CREATEFUNCTION-NOTES"><h2>Notes</h2><p>
+ The full <acronym class="acronym">SQL</acronym> type syntax is allowed for
+ declaring a function's arguments and return value. However,
+ parenthesized type modifiers (e.g., the precision field for
+ type <code class="type">numeric</code>) are discarded by <code class="command">CREATE FUNCTION</code>.
+ Thus for example
+ <code class="literal">CREATE FUNCTION foo (varchar(10)) ...</code>
+ is exactly the same as
+ <code class="literal">CREATE FUNCTION foo (varchar) ...</code>.
+ </p><p>
+ When replacing an existing function with <code class="command">CREATE OR REPLACE
+ FUNCTION</code>, there are restrictions on changing parameter names.
+ You cannot change the name already assigned to any input parameter
+ (although you can add names to parameters that had none before).
+ If there is more than one output parameter, you cannot change the
+ names of the output parameters, because that would change the
+ column names of the anonymous composite type that describes the
+ function's result. These restrictions are made to ensure that
+ existing calls of the function do not stop working when it is replaced.
+ </p><p>
+ If a function is declared <code class="literal">STRICT</code> with a <code class="literal">VARIADIC</code>
+ argument, the strictness check tests that the variadic array <span class="emphasis"><em>as
+ a whole</em></span> is non-null. The function will still be called if the
+ array has null elements.
+ </p></div><div class="refsect1" id="SQL-CREATEFUNCTION-EXAMPLES"><h2>Examples</h2><p>
+ Add two integers using an SQL function:
+</p><pre class="programlisting">
+CREATE FUNCTION add(integer, integer) RETURNS integer
+ AS 'select $1 + $2;'
+ LANGUAGE SQL
+ IMMUTABLE
+ RETURNS NULL ON NULL INPUT;
+</pre><p>
+ The same function written in a more SQL-conforming style, using argument
+ names and an unquoted body:
+</p><pre class="programlisting">
+CREATE FUNCTION add(a integer, b integer) RETURNS integer
+ LANGUAGE SQL
+ IMMUTABLE
+ RETURNS NULL ON NULL INPUT
+ RETURN a + b;
+</pre><p>
+ </p><p>
+ Increment an integer, making use of an argument name, in
+ <span class="application">PL/pgSQL</span>:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
+ BEGIN
+ RETURN i + 1;
+ END;
+$$ LANGUAGE plpgsql;
+</pre><p>
+ </p><p>
+ Return a record containing multiple output parameters:
+</p><pre class="programlisting">
+CREATE FUNCTION dup(in int, out f1 int, out f2 text)
+ AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
+ LANGUAGE SQL;
+
+SELECT * FROM dup(42);
+</pre><p>
+ You can do the same thing more verbosely with an explicitly named
+ composite type:
+</p><pre class="programlisting">
+CREATE TYPE dup_result AS (f1 int, f2 text);
+
+CREATE FUNCTION dup(int) RETURNS dup_result
+ AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
+ LANGUAGE SQL;
+
+SELECT * FROM dup(42);
+</pre><p>
+ Another way to return multiple columns is to use a <code class="literal">TABLE</code>
+ function:
+</p><pre class="programlisting">
+CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text)
+ AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
+ LANGUAGE SQL;
+
+SELECT * FROM dup(42);
+</pre><p>
+ However, a <code class="literal">TABLE</code> function is different from the
+ preceding examples, because it actually returns a <span class="emphasis"><em>set</em></span>
+ of records, not just one record.
+ </p></div><div class="refsect1" id="SQL-CREATEFUNCTION-SECURITY"><h2>Writing <code class="literal">SECURITY DEFINER</code> Functions Safely</h2><a id="id-1.9.3.67.10.2" class="indexterm"></a><p>
+ Because a <code class="literal">SECURITY DEFINER</code> function is executed
+ with the privileges of the user that owns it, care is needed to
+ ensure that the function cannot be misused. For security,
+ <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> should be set to exclude any schemas
+ writable by untrusted users. This prevents
+ malicious users from creating objects (e.g., tables, functions, and
+ operators) that mask objects intended to be used by the function.
+ Particularly important in this regard is the
+ temporary-table schema, which is searched first by default, and
+ is normally writable by anyone. A secure arrangement can be obtained
+ by forcing the temporary schema to be searched last. To do this,
+ write <code class="literal">pg_temp</code><a id="id-1.9.3.67.10.3.4" class="indexterm"></a> as the last entry in <code class="varname">search_path</code>.
+ This function illustrates safe usage:
+
+</p><pre class="programlisting">
+CREATE FUNCTION check_password(uname TEXT, pass TEXT)
+RETURNS BOOLEAN AS $$
+DECLARE passed BOOLEAN;
+BEGIN
+ SELECT (pwd = $2) INTO passed
+ FROM pwds
+ WHERE username = $1;
+
+ RETURN passed;
+END;
+$$ LANGUAGE plpgsql
+ SECURITY DEFINER
+ -- Set a secure search_path: trusted schema(s), then 'pg_temp'.
+ SET search_path = admin, pg_temp;
+</pre><p>
+
+ This function's intention is to access a table <code class="literal">admin.pwds</code>.
+ But without the <code class="literal">SET</code> clause, or with a <code class="literal">SET</code> clause
+ mentioning only <code class="literal">admin</code>, the function could be subverted by
+ creating a temporary table named <code class="literal">pwds</code>.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> version 8.3, the
+ <code class="literal">SET</code> clause was not available, and so older functions may
+ contain rather complicated logic to save, set, and restore
+ <code class="varname">search_path</code>. The <code class="literal">SET</code> clause is far easier
+ to use for this purpose.
+ </p><p>
+ Another point to keep in mind is that by default, execute privilege
+ is granted to <code class="literal">PUBLIC</code> for newly created functions
+ (see <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for more
+ information). Frequently you will wish to restrict use of a security
+ definer function to only some users. To do that, you must revoke
+ the default <code class="literal">PUBLIC</code> privileges and then grant execute
+ privilege selectively. To avoid having a window where the new function
+ is accessible to all, create it and set the privileges within a single
+ transaction. For example:
+ </p><pre class="programlisting">
+BEGIN;
+CREATE FUNCTION check_password(uname TEXT, pass TEXT) ... SECURITY DEFINER;
+REVOKE ALL ON FUNCTION check_password(uname TEXT, pass TEXT) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION check_password(uname TEXT, pass TEXT) TO admins;
+COMMIT;
+</pre></div><div class="refsect1" id="SQL-CREATEFUNCTION-COMPAT"><h2>Compatibility</h2><p>
+ A <code class="command">CREATE FUNCTION</code> command is defined in the SQL
+ standard. The <span class="productname">PostgreSQL</span> implementation can be
+ used in a compatible way but has many extensions. Conversely, the SQL
+ standard specifies a number of optional features that are not implemented
+ in <span class="productname">PostgreSQL</span>.
+ </p><p>
+ The following are important compatibility issues:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">OR REPLACE</code> is a PostgreSQL extension.
+ </p></li><li class="listitem"><p>
+ For compatibility with some other database systems, <em class="replaceable"><code>argmode</code></em> can be written either before or
+ after <em class="replaceable"><code>argname</code></em>. But only
+ the first way is standard-compliant.
+ </p></li><li class="listitem"><p>
+ For parameter defaults, the SQL standard specifies only the syntax with
+ the <code class="literal">DEFAULT</code> key word. The syntax with
+ <code class="literal">=</code> is used in T-SQL and Firebird.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">SETOF</code> modifier is a PostgreSQL extension.
+ </p></li><li class="listitem"><p>
+ Only <code class="literal">SQL</code> is standardized as a language.
+ </p></li><li class="listitem"><p>
+ All other attributes except <code class="literal">CALLED ON NULL INPUT</code> and
+ <code class="literal">RETURNS NULL ON NULL INPUT</code> are not standardized.
+ </p></li><li class="listitem"><p>
+ For the body of <code class="literal">LANGUAGE SQL</code> functions, the SQL
+ standard only specifies the <em class="replaceable"><code>sql_body</code></em> form.
+ </p></li></ul></div><p>
+ </p><p>
+ Simple <code class="literal">LANGUAGE SQL</code> functions can be written in a way
+ that is both standard-conforming and portable to other implementations.
+ More complex functions using advanced features, optimization attributes, or
+ other languages will necessarily be specific to PostgreSQL in a significant
+ way.
+ </p></div><div class="refsect1" id="id-1.9.3.67.12"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, <a class="xref" href="sql-dropfunction.html" title="DROP FUNCTION"><span class="refentrytitle">DROP FUNCTION</span></a>, <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-load.html" title="LOAD"><span class="refentrytitle">LOAD</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-creategroup.html" title="CREATE GROUP">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE FOREIGN TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE GROUP</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-creategroup.html b/doc/src/sgml/html/sql-creategroup.html
new file mode 100644
index 0000000..de56202
--- /dev/null
+++ b/doc/src/sgml/html/sql-creategroup.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE GROUP</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createfunction.html" title="CREATE FUNCTION" /><link rel="next" href="sql-createindex.html" title="CREATE INDEX" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE GROUP</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createfunction.html" title="CREATE FUNCTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createindex.html" title="CREATE INDEX">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEGROUP"><div class="titlepage"></div><a id="id-1.9.3.68.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE GROUP</span></h2><p>CREATE GROUP — define a new database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE GROUP <em class="replaceable"><code>name</code></em> [ [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ SUPERUSER | NOSUPERUSER
+ | CREATEDB | NOCREATEDB
+ | CREATEROLE | NOCREATEROLE
+ | INHERIT | NOINHERIT
+ | LOGIN | NOLOGIN
+ | REPLICATION | NOREPLICATION
+ | BYPASSRLS | NOBYPASSRLS
+ | CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ | [ ENCRYPTED ] PASSWORD '<em class="replaceable"><code>password</code></em>' | PASSWORD NULL
+ | VALID UNTIL '<em class="replaceable"><code>timestamp</code></em>'
+ | IN ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | IN GROUP <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ADMIN <em class="replaceable"><code>role_name</code></em> [, ...]
+ | USER <em class="replaceable"><code>role_name</code></em> [, ...]
+ | SYSID <em class="replaceable"><code>uid</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.68.5"><h2>Description</h2><p>
+ <code class="command">CREATE GROUP</code> is now an alias for
+ <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.68.6"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE GROUP</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.68.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createfunction.html" title="CREATE FUNCTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createindex.html" title="CREATE INDEX">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE FUNCTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE INDEX</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createindex.html b/doc/src/sgml/html/sql-createindex.html
new file mode 100644
index 0000000..2c9a051
--- /dev/null
+++ b/doc/src/sgml/html/sql-createindex.html
@@ -0,0 +1,580 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE INDEX</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-creategroup.html" title="CREATE GROUP" /><link rel="next" href="sql-createlanguage.html" title="CREATE LANGUAGE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE INDEX</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-creategroup.html" title="CREATE GROUP">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createlanguage.html" title="CREATE LANGUAGE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEINDEX"><div class="titlepage"></div><a id="id-1.9.3.69.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE INDEX</span></h2><p>CREATE INDEX — define a new index</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <em class="replaceable"><code>name</code></em> ] ON [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ USING <em class="replaceable"><code>method</code></em> ]
+ ( { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> [ ( <em class="replaceable"><code>opclass_parameter</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] ) ] ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] )
+ [ INCLUDE ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ [ NULLS [ NOT ] DISTINCT ]
+ [ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ [ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+ [ WHERE <em class="replaceable"><code>predicate</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.69.5"><h2>Description</h2><p>
+ <code class="command">CREATE INDEX</code> constructs an index on the specified column(s)
+ of the specified relation, which can be a table or a materialized view.
+ Indexes are primarily used to enhance database performance (though
+ inappropriate use can result in slower performance).
+ </p><p>
+ The key field(s) for the index are specified as column names,
+ or alternatively as expressions written in parentheses.
+ Multiple fields can be specified if the index method supports
+ multicolumn indexes.
+ </p><p>
+ An index field can be an expression computed from the values of
+ one or more columns of the table row. This feature can be used
+ to obtain fast access to data based on some transformation of
+ the basic data. For example, an index computed on
+ <code class="literal">upper(col)</code> would allow the clause
+ <code class="literal">WHERE upper(col) = 'JIM'</code> to use an index.
+ </p><p>
+ <span class="productname">PostgreSQL</span> provides the index methods
+ B-tree, hash, GiST, SP-GiST, GIN, and BRIN. Users can also define their own
+ index methods, but that is fairly complicated.
+ </p><p>
+ When the <code class="literal">WHERE</code> clause is present, a
+ <em class="firstterm">partial index</em> is created.
+ A partial index is an index that contains entries for only a portion of
+ a table, usually a portion that is more useful for indexing than the
+ rest of the table. For example, if you have a table that contains both
+ billed and unbilled orders where the unbilled orders take up a small
+ fraction of the total table and yet that is an often used section, you
+ can improve performance by creating an index on just that portion.
+ Another possible application is to use <code class="literal">WHERE</code> with
+ <code class="literal">UNIQUE</code> to enforce uniqueness over a subset of a
+ table. See <a class="xref" href="indexes-partial.html" title="11.8. Partial Indexes">Section 11.8</a> for more discussion.
+ </p><p>
+ The expression used in the <code class="literal">WHERE</code> clause can refer
+ only to columns of the underlying table, but it can use all columns,
+ not just the ones being indexed. Presently, subqueries and
+ aggregate expressions are also forbidden in <code class="literal">WHERE</code>.
+ The same restrictions apply to index fields that are expressions.
+ </p><p>
+ All functions and operators used in an index definition must be
+ <span class="quote">“<span class="quote">immutable</span>”</span>, that is, their results must depend only on
+ their arguments and never on any outside influence (such as
+ the contents of another table or the current time). This restriction
+ ensures that the behavior of the index is well-defined. To use a
+ user-defined function in an index expression or <code class="literal">WHERE</code>
+ clause, remember to mark the function immutable when you create it.
+ </p></div><div class="refsect1" id="id-1.9.3.69.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">UNIQUE</code></span></dt><dd><p>
+ Causes the system to check for
+ duplicate values in the table when the index is created (if data
+ already exist) and each time data is added. Attempts to
+ insert or update data which would result in duplicate entries
+ will generate an error.
+ </p><p>
+ Additional restrictions apply when unique indexes are applied to
+ partitioned tables; see <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>.
+ </p></dd><dt><span class="term"><code class="literal">CONCURRENTLY</code></span></dt><dd><p>
+ When this option is used, <span class="productname">PostgreSQL</span> will build the
+ index without taking any locks that prevent concurrent inserts,
+ updates, or deletes on the table; whereas a standard index build
+ locks out writes (but not reads) on the table until it's done.
+ There are several caveats to be aware of when using this option
+ — see <a class="xref" href="sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY" title="Building Indexes Concurrently">Building Indexes Concurrently</a> below.
+ </p><p>
+ For temporary tables, <code class="command">CREATE INDEX</code> is always
+ non-concurrent, as no other session can access them, and
+ non-concurrent index creation is cheaper.
+ </p></dd><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a relation with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing index is anything like the one that would have been created.
+ Index name is required when <code class="literal">IF NOT EXISTS</code> is specified.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDE</code></span></dt><dd><p>
+ The optional <code class="literal">INCLUDE</code> clause specifies a
+ list of columns which will be included in the index
+ as <em class="firstterm">non-key</em> columns. A non-key column cannot
+ be used in an index scan search qualification, and it is disregarded
+ for purposes of any uniqueness or exclusion constraint enforced by
+ the index. However, an index-only scan can return the contents of
+ non-key columns without having to visit the index's table, since
+ they are available directly from the index entry. Thus, addition of
+ non-key columns allows index-only scans to be used for queries that
+ otherwise could not use them.
+ </p><p>
+ It's wise to be conservative about adding non-key columns to an
+ index, especially wide columns. If an index tuple exceeds the
+ maximum size allowed for the index type, data insertion will fail.
+ In any case, non-key columns duplicate data from the index's table
+ and bloat the size of the index, thus potentially slowing searches.
+ Furthermore, B-tree deduplication is never used with indexes
+ that have a non-key column.
+ </p><p>
+ Columns listed in the <code class="literal">INCLUDE</code> clause don't need
+ appropriate operator classes; the clause can include
+ columns whose data types don't have operator classes defined for
+ a given access method.
+ </p><p>
+ Expressions are not supported as included columns since they cannot be
+ used in index-only scans.
+ </p><p>
+ Currently, the B-tree, GiST and SP-GiST index access methods support
+ this feature. In these indexes, the values of columns listed
+ in the <code class="literal">INCLUDE</code> clause are included in leaf tuples
+ which correspond to heap tuples, but are not included in upper-level
+ index entries used for tree navigation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the index to be created. No schema name can be included
+ here; the index is always created in the same schema as its parent
+ table. The name of the index must be distinct from the name of any
+ other relation (table, sequence, index, view, materialized view, or
+ foreign table) in that schema.
+ If the name is omitted, <span class="productname">PostgreSQL</span> chooses a
+ suitable name based on the parent table's name and the indexed column
+ name(s).
+ </p></dd><dt><span class="term"><code class="literal">ONLY</code></span></dt><dd><p>
+ Indicates not to recurse creating indexes on partitions, if the
+ table is partitioned. The default is to recurse.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (possibly schema-qualified) of the table to be indexed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>method</code></em></span></dt><dd><p>
+ The name of the index method to be used. Choices are
+ <code class="literal">btree</code>, <code class="literal">hash</code>,
+ <code class="literal">gist</code>, <code class="literal">spgist</code>, <code class="literal">gin</code>,
+ <code class="literal">brin</code>, or user-installed access methods like
+ <a class="link" href="bloom.html" title="F.7. bloom">bloom</a>.
+ The default method is <code class="literal">btree</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column of the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ An expression based on one or more columns of the table. The
+ expression usually must be written with surrounding parentheses,
+ as shown in the syntax. However, the parentheses can be omitted
+ if the expression has the form of a function call.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collation</code></em></span></dt><dd><p>
+ The name of the collation to use for the index. By default,
+ the index uses the collation declared for the column to be
+ indexed or the result collation of the expression to be
+ indexed. Indexes with non-default collations can be useful for
+ queries that involve expressions using non-default collations.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>opclass</code></em></span></dt><dd><p>
+ The name of an operator class. See below for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>opclass_parameter</code></em></span></dt><dd><p>
+ The name of an operator class parameter. See below for details.
+ </p></dd><dt><span class="term"><code class="literal">ASC</code></span></dt><dd><p>
+ Specifies ascending sort order (which is the default).
+ </p></dd><dt><span class="term"><code class="literal">DESC</code></span></dt><dd><p>
+ Specifies descending sort order.
+ </p></dd><dt><span class="term"><code class="literal">NULLS FIRST</code></span></dt><dd><p>
+ Specifies that nulls sort before non-nulls. This is the default
+ when <code class="literal">DESC</code> is specified.
+ </p></dd><dt><span class="term"><code class="literal">NULLS LAST</code></span></dt><dd><p>
+ Specifies that nulls sort after non-nulls. This is the default
+ when <code class="literal">DESC</code> is not specified.
+ </p></dd><dt><span class="term"><code class="literal">NULLS DISTINCT</code><br /></span><span class="term"><code class="literal">NULLS NOT DISTINCT</code></span></dt><dd><p>
+ Specifies whether for a unique index, null values should be considered
+ distinct (not equal). The default is that they are distinct, so that
+ a unique index could contain multiple null values in a column.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>storage_parameter</code></em></span></dt><dd><p>
+ The name of an index-method-specific storage parameter. See
+ <a class="xref" href="sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS" title="Index Storage Parameters">Index Storage Parameters</a> below
+ for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>tablespace_name</code></em></span></dt><dd><p>
+ The tablespace in which to create the index. If not specified,
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> is consulted, or
+ <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> for indexes on temporary
+ tables.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>predicate</code></em></span></dt><dd><p>
+ The constraint expression for a partial index.
+ </p></dd></dl></div><div class="refsect2" id="SQL-CREATEINDEX-STORAGE-PARAMETERS"><h3>Index Storage Parameters</h3><p>
+ The optional <code class="literal">WITH</code> clause specifies <em class="firstterm">storage
+ parameters</em> for the index. Each index method has its own set of allowed
+ storage parameters. The B-tree, hash, GiST and SP-GiST index methods all
+ accept this parameter:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-FILLFACTOR"><span class="term"><code class="literal">fillfactor</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.69.6.3.3.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The fillfactor for an index is a percentage that determines how full
+ the index method will try to pack index pages. For B-trees, leaf pages
+ are filled to this percentage during initial index builds, and also
+ when extending the index at the right (adding new largest key values).
+ If pages
+ subsequently become completely full, they will be split, leading to
+ fragmentation of the on-disk index structure. B-trees use a default
+ fillfactor of 90, but any integer value from 10 to 100 can be selected.
+ </p><p>
+ B-tree indexes on tables where many inserts and/or updates are
+ anticipated can benefit from lower fillfactor settings at
+ <code class="command">CREATE INDEX</code> time (following bulk loading into the
+ table). Values in the range of 50 - 90 can usefully <span class="quote">“<span class="quote">smooth
+ out</span>”</span> the <span class="emphasis"><em>rate</em></span> of page splits during the
+ early life of the B-tree index (lowering fillfactor like this may even
+ lower the absolute number of page splits, though this effect is highly
+ workload dependent). The B-tree bottom-up index deletion technique
+ described in <a class="xref" href="btree-implementation.html#BTREE-DELETION" title="67.4.2. Bottom-up Index Deletion">Section 67.4.2</a> is dependent on having
+ some <span class="quote">“<span class="quote">extra</span>”</span> space on pages to store <span class="quote">“<span class="quote">extra</span>”</span>
+ tuple versions, and so can be affected by fillfactor (though the effect
+ is usually not significant).
+ </p><p>
+ In other specific cases it might be useful to increase fillfactor to
+ 100 at <code class="command">CREATE INDEX</code> time as a way of maximizing
+ space utilization. You should only consider this when you are
+ completely sure that the table is static (i.e. that it will never be
+ affected by either inserts or updates). A fillfactor setting of 100
+ otherwise risks <span class="emphasis"><em>harming</em></span> performance: even a few
+ updates or inserts will cause a sudden flood of page splits.
+ </p><p>
+ The other index methods use fillfactor in different but roughly
+ analogous ways; the default fillfactor varies between methods.
+ </p></dd></dl></div><p>
+ B-tree indexes additionally accept this parameter:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-DEDUPLICATE-ITEMS"><span class="term"><code class="literal">deduplicate_items</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.69.6.3.5.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Controls usage of the B-tree deduplication technique described
+ in <a class="xref" href="btree-implementation.html#BTREE-DEDUPLICATION" title="67.4.3. Deduplication">Section 67.4.3</a>. Set to
+ <code class="literal">ON</code> or <code class="literal">OFF</code> to enable or
+ disable the optimization. (Alternative spellings of
+ <code class="literal">ON</code> and <code class="literal">OFF</code> are allowed as
+ described in <a class="xref" href="config-setting.html" title="20.1. Setting Parameters">Section 20.1</a>.) The default is
+ <code class="literal">ON</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Turning <code class="literal">deduplicate_items</code> off via
+ <code class="command">ALTER INDEX</code> prevents future insertions from
+ triggering deduplication, but does not in itself make existing
+ posting list tuples use the standard tuple representation.
+ </p></div></dd></dl></div><p>
+ GiST indexes additionally accept this parameter:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-BUFFERING"><span class="term"><code class="literal">buffering</code> (<code class="type">enum</code>)
+ <a id="id-1.9.3.69.6.3.7.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Determines whether the buffered build technique described in
+ <a class="xref" href="gist-implementation.html#GIST-BUFFERING-BUILD" title="68.4.1. GiST Index Build Methods">Section 68.4.1</a> is used to build the index. With
+ <code class="literal">OFF</code> buffering is disabled, with <code class="literal">ON</code>
+ it is enabled, and with <code class="literal">AUTO</code> it is initially disabled,
+ but is turned on on-the-fly once the index size reaches
+ <a class="xref" href="runtime-config-query.html#GUC-EFFECTIVE-CACHE-SIZE">effective_cache_size</a>. The default
+ is <code class="literal">AUTO</code>.
+ Note that if sorted build is possible, it will be used instead of
+ buffered build unless <code class="literal">buffering=ON</code> is specified.
+ </p></dd></dl></div><p>
+ GIN indexes accept different parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-FASTUPDATE"><span class="term"><code class="literal">fastupdate</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.69.6.3.9.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This setting controls usage of the fast update technique described in
+ <a class="xref" href="gin-implementation.html#GIN-FAST-UPDATE" title="70.4.1. GIN Fast Update Technique">Section 70.4.1</a>. It is a Boolean parameter:
+ <code class="literal">ON</code> enables fast update, <code class="literal">OFF</code> disables it.
+ The default is <code class="literal">ON</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Turning <code class="literal">fastupdate</code> off via <code class="command">ALTER INDEX</code> prevents
+ future insertions from going into the list of pending index entries,
+ but does not in itself flush previous entries. You might want to
+ <code class="command">VACUUM</code> the table or call <code class="function">gin_clean_pending_list</code>
+ function afterward to ensure the pending list is emptied.
+ </p></div></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-GIN-PENDING-LIST-LIMIT"><span class="term"><code class="literal">gin_pending_list_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.69.6.3.10.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Custom <a class="xref" href="runtime-config-client.html#GUC-GIN-PENDING-LIST-LIMIT">gin_pending_list_limit</a> parameter.
+ This value is specified in kilobytes.
+ </p></dd></dl></div><p>
+ <acronym class="acronym">BRIN</acronym> indexes accept different parameters:
+ </p><div class="variablelist"><dl class="variablelist"><dt id="INDEX-RELOPTION-PAGES-PER-RANGE"><span class="term"><code class="literal">pages_per_range</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.69.6.3.12.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Defines the number of table blocks that make up one block range for
+ each entry of a <acronym class="acronym">BRIN</acronym> index (see <a class="xref" href="brin-intro.html" title="71.1. Introduction">Section 71.1</a>
+ for more details). The default is <code class="literal">128</code>.
+ </p></dd><dt id="INDEX-RELOPTION-AUTOSUMMARIZE"><span class="term"><code class="literal">autosummarize</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.69.6.3.12.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Defines whether a summarization run is queued for the previous page
+ range whenever an insertion is detected on the next one.
+ See <a class="xref" href="brin-intro.html#BRIN-OPERATION" title="71.1.1. Index Maintenance">Section 71.1.1</a> for more details.
+ The default is <code class="literal">off</code>.
+ </p></dd></dl></div></div><div class="refsect2" id="SQL-CREATEINDEX-CONCURRENTLY"><h3>Building Indexes Concurrently</h3><a id="id-1.9.3.69.6.4.2" class="indexterm"></a><p>
+ Creating an index can interfere with regular operation of a database.
+ Normally <span class="productname">PostgreSQL</span> locks the table to be indexed against
+ writes and performs the entire index build with a single scan of the
+ table. Other transactions can still read the table, but if they try to
+ insert, update, or delete rows in the table they will block until the
+ index build is finished. This could have a severe effect if the system is
+ a live production database. Very large tables can take many hours to be
+ indexed, and even for smaller tables, an index build can lock out writers
+ for periods that are unacceptably long for a production system.
+ </p><p>
+ <span class="productname">PostgreSQL</span> supports building indexes without locking
+ out writes. This method is invoked by specifying the
+ <code class="literal">CONCURRENTLY</code> option of <code class="command">CREATE INDEX</code>.
+ When this option is used,
+ <span class="productname">PostgreSQL</span> must perform two scans of the table, and in
+ addition it must wait for all existing transactions that could potentially
+ modify or use the index to terminate. Thus
+ this method requires more total work than a standard index build and takes
+ significantly longer to complete. However, since it allows normal
+ operations to continue while the index is built, this method is useful for
+ adding new indexes in a production environment. Of course, the extra CPU
+ and I/O load imposed by the index creation might slow other operations.
+ </p><p>
+ In a concurrent index build, the index is actually entered as an
+ <span class="quote">“<span class="quote">invalid</span>”</span> index into
+ the system catalogs in one transaction, then two table scans occur in
+ two more transactions. Before each table scan, the index build must
+ wait for existing transactions that have modified the table to terminate.
+ After the second scan, the index build must wait for any transactions
+ that have a snapshot (see <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>) predating the second
+ scan to terminate, including transactions used by any phase of concurrent
+ index builds on other tables, if the indexes involved are partial or have
+ columns that are not simple column references.
+ Then finally the index can be marked <span class="quote">“<span class="quote">valid</span>”</span> and ready for use,
+ and the <code class="command">CREATE INDEX</code> command terminates.
+ Even then, however, the index may not be immediately usable for queries:
+ in the worst case, it cannot be used as long as transactions exist that
+ predate the start of the index build.
+ </p><p>
+ If a problem arises while scanning the table, such as a deadlock or a
+ uniqueness violation in a unique index, the <code class="command">CREATE INDEX</code>
+ command will fail but leave behind an <span class="quote">“<span class="quote">invalid</span>”</span> index. This index
+ will be ignored for querying purposes because it might be incomplete;
+ however it will still consume update overhead. The <span class="application">psql</span>
+ <code class="command">\d</code> command will report such an index as <code class="literal">INVALID</code>:
+
+</p><pre class="programlisting">
+postgres=# \d tab
+ Table "public.tab"
+ Column | Type | Collation | Nullable | Default
+--------+---------+-----------+----------+---------
+ col | integer | | |
+Indexes:
+ "idx" btree (col) INVALID
+</pre><p>
+
+ The recommended recovery
+ method in such cases is to drop the index and try again to perform
+ <code class="command">CREATE INDEX CONCURRENTLY</code>. (Another possibility is
+ to rebuild the index with <code class="command">REINDEX INDEX CONCURRENTLY</code>).
+ </p><p>
+ Another caveat when building a unique index concurrently is that the
+ uniqueness constraint is already being enforced against other transactions
+ when the second table scan begins. This means that constraint violations
+ could be reported in other queries prior to the index becoming available
+ for use, or even in cases where the index build eventually fails. Also,
+ if a failure does occur in the second scan, the <span class="quote">“<span class="quote">invalid</span>”</span> index
+ continues to enforce its uniqueness constraint afterwards.
+ </p><p>
+ Concurrent builds of expression indexes and partial indexes are supported.
+ Errors occurring in the evaluation of these expressions could cause
+ behavior similar to that described above for unique constraint violations.
+ </p><p>
+ Regular index builds permit other regular index builds on the
+ same table to occur simultaneously, but only one concurrent index build
+ can occur on a table at a time. In either case, schema modification of the
+ table is not allowed while the index is being built. Another difference is
+ that a regular <code class="command">CREATE INDEX</code> command can be performed
+ within a transaction block, but <code class="command">CREATE INDEX CONCURRENTLY</code>
+ cannot.
+ </p><p>
+ Concurrent builds for indexes on partitioned tables are currently not
+ supported. However, you may concurrently build the index on each
+ partition individually and then finally create the partitioned index
+ non-concurrently in order to reduce the time where writes to the
+ partitioned table will be locked out. In this case, building the
+ partitioned index is a metadata only operation.
+ </p></div></div><div class="refsect1" id="id-1.9.3.69.7"><h2>Notes</h2><p>
+ See <a class="xref" href="indexes.html" title="Chapter 11. Indexes">Chapter 11</a> for information about when indexes can
+ be used, when they are not used, and in which particular situations
+ they can be useful.
+ </p><p>
+ Currently, only the B-tree, GiST, GIN, and BRIN index methods support
+ multiple-key-column indexes. Whether there can be multiple key
+ columns is independent of whether <code class="literal">INCLUDE</code> columns
+ can be added to the index. Indexes can have up to 32 columns,
+ including <code class="literal">INCLUDE</code> columns.
+ (This limit can be altered when building
+ <span class="productname">PostgreSQL</span>.) Only B-tree currently
+ supports unique indexes.
+ </p><p>
+ An <em class="firstterm">operator class</em> with optional parameters
+ can be specified for each column of an index.
+ The operator class identifies the operators to be
+ used by the index for that column. For example, a B-tree index on
+ four-byte integers would use the <code class="literal">int4_ops</code> class;
+ this operator class includes comparison functions for four-byte
+ integers. In practice the default operator class for the column's data
+ type is usually sufficient. The main point of having operator classes
+ is that for some data types, there could be more than one meaningful
+ ordering. For example, we might want to sort a complex-number data
+ type either by absolute value or by real part. We could do this by
+ defining two operator classes for the data type and then selecting
+ the proper class when creating an index. More information about
+ operator classes is in <a class="xref" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Section 11.10</a> and in <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>.
+ </p><p>
+ When <code class="literal">CREATE INDEX</code> is invoked on a partitioned
+ table, the default behavior is to recurse to all partitions to ensure
+ they all have matching indexes.
+ Each partition is first checked to determine whether an equivalent
+ index already exists, and if so, that index will become attached as a
+ partition index to the index being created, which will become its
+ parent index.
+ If no matching index exists, a new index will be created and
+ automatically attached; the name of the new index in each partition
+ will be determined as if no index name had been specified in the
+ command.
+ If the <code class="literal">ONLY</code> option is specified, no recursion
+ is done, and the index is marked invalid.
+ (<code class="command">ALTER INDEX ... ATTACH PARTITION</code> marks the index
+ valid, once all partitions acquire matching indexes.) Note, however,
+ that any partition that is created in the future using
+ <code class="command">CREATE TABLE ... PARTITION OF</code> will automatically
+ have a matching index, regardless of whether <code class="literal">ONLY</code> is
+ specified.
+ </p><p>
+ For index methods that support ordered scans (currently, only B-tree),
+ the optional clauses <code class="literal">ASC</code>, <code class="literal">DESC</code>, <code class="literal">NULLS
+ FIRST</code>, and/or <code class="literal">NULLS LAST</code> can be specified to modify
+ the sort ordering of the index. Since an ordered index can be
+ scanned either forward or backward, it is not normally useful to create a
+ single-column <code class="literal">DESC</code> index — that sort ordering is already
+ available with a regular index. The value of these options is that
+ multicolumn indexes can be created that match the sort ordering requested
+ by a mixed-ordering query, such as <code class="literal">SELECT ... ORDER BY x ASC, y
+ DESC</code>. The <code class="literal">NULLS</code> options are useful if you need to support
+ <span class="quote">“<span class="quote">nulls sort low</span>”</span> behavior, rather than the default <span class="quote">“<span class="quote">nulls
+ sort high</span>”</span>, in queries that depend on indexes to avoid sorting steps.
+ </p><p>
+ The system regularly collects statistics on all of a table's
+ columns. Newly-created non-expression indexes can immediately
+ use these statistics to determine an index's usefulness.
+ For new expression indexes, it is necessary to run <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> or wait for
+ the <a class="link" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">autovacuum daemon</a> to analyze
+ the table to generate statistics for these indexes.
+ </p><p>
+ For most index methods, the speed of creating an index is
+ dependent on the setting of <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a>.
+ Larger values will reduce the time needed for index creation, so long
+ as you don't make it larger than the amount of memory really available,
+ which would drive the machine into swapping.
+ </p><p>
+ <span class="productname">PostgreSQL</span> can build indexes while
+ leveraging multiple CPUs in order to process the table rows faster.
+ This feature is known as <em class="firstterm">parallel index
+ build</em>. For index methods that support building indexes
+ in parallel (currently, only B-tree),
+ <code class="varname">maintenance_work_mem</code> specifies the maximum
+ amount of memory that can be used by each index build operation as
+ a whole, regardless of how many worker processes were started.
+ Generally, a cost model automatically determines how many worker
+ processes should be requested, if any.
+ </p><p>
+ Parallel index builds may benefit from increasing
+ <code class="varname">maintenance_work_mem</code> where an equivalent serial
+ index build will see little or no benefit. Note that
+ <code class="varname">maintenance_work_mem</code> may influence the number of
+ worker processes requested, since parallel workers must have at
+ least a <code class="literal">32MB</code> share of the total
+ <code class="varname">maintenance_work_mem</code> budget. There must also be
+ a remaining <code class="literal">32MB</code> share for the leader process.
+ Increasing <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS">max_parallel_maintenance_workers</a>
+ may allow more workers to be used, which will reduce the time
+ needed for index creation, so long as the index build is not
+ already I/O bound. Of course, there should also be sufficient
+ CPU capacity that would otherwise lie idle.
+ </p><p>
+ Setting a value for <code class="literal">parallel_workers</code> via <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> directly controls how many parallel
+ worker processes will be requested by a <code class="command">CREATE
+ INDEX</code> against the table. This bypasses the cost model
+ completely, and prevents <code class="varname">maintenance_work_mem</code>
+ from affecting how many parallel workers are requested. Setting
+ <code class="literal">parallel_workers</code> to 0 via <code class="command">ALTER
+ TABLE</code> will disable parallel index builds on the table in
+ all cases.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ You might want to reset <code class="literal">parallel_workers</code> after
+ setting it as part of tuning an index build. This avoids
+ inadvertent changes to query plans, since
+ <code class="literal">parallel_workers</code> affects
+ <span class="emphasis"><em>all</em></span> parallel table scans.
+ </p></div><p>
+ While <code class="command">CREATE INDEX</code> with the
+ <code class="literal">CONCURRENTLY</code> option supports parallel builds
+ without special restrictions, only the first table scan is actually
+ performed in parallel.
+ </p><p>
+ Use <a class="link" href="sql-dropindex.html" title="DROP INDEX"><code class="command">DROP INDEX</code></a>
+ to remove an index.
+ </p><p>
+ Like any long-running transaction, <code class="command">CREATE INDEX</code> on a
+ table can affect which tuples can be removed by concurrent
+ <code class="command">VACUUM</code> on any other table.
+ </p><p>
+ Prior releases of <span class="productname">PostgreSQL</span> also had an
+ R-tree index method. This method has been removed because
+ it had no significant advantages over the GiST method.
+ If <code class="literal">USING rtree</code> is specified, <code class="command">CREATE INDEX</code>
+ will interpret it as <code class="literal">USING gist</code>, to simplify conversion
+ of old databases to GiST.
+ </p><p>
+ Each backend running <code class="command">CREATE INDEX</code> will report its
+ progress in the <code class="structname">pg_stat_progress_create_index</code>
+ view. See <a class="xref" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING" title="28.4.2. CREATE INDEX Progress Reporting">Section 28.4.2</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.69.8"><h2>Examples</h2><p>
+ To create a unique B-tree index on the column <code class="literal">title</code> in
+ the table <code class="literal">films</code>:
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX title_idx ON films (title);
+</pre><p>
+ </p><p>
+ To create a unique B-tree index on the column <code class="literal">title</code>
+ with included columns <code class="literal">director</code>
+ and <code class="literal">rating</code> in the table <code class="literal">films</code>:
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX title_idx ON films (title) INCLUDE (director, rating);
+</pre><p>
+ </p><p>
+ To create a B-Tree index with deduplication disabled:
+</p><pre class="programlisting">
+CREATE INDEX title_idx ON films (title) WITH (deduplicate_items = off);
+</pre><p>
+ </p><p>
+ To create an index on the expression <code class="literal">lower(title)</code>,
+ allowing efficient case-insensitive searches:
+</p><pre class="programlisting">
+CREATE INDEX ON films ((lower(title)));
+</pre><p>
+ (In this example we have chosen to omit the index name, so the system
+ will choose a name, typically <code class="literal">films_lower_idx</code>.)
+ </p><p>
+ To create an index with non-default collation:
+</p><pre class="programlisting">
+CREATE INDEX title_idx_german ON films (title COLLATE "de_DE");
+</pre><p>
+ </p><p>
+ To create an index with non-default sort ordering of nulls:
+</p><pre class="programlisting">
+CREATE INDEX title_idx_nulls_low ON films (title NULLS FIRST);
+</pre><p>
+ </p><p>
+ To create an index with non-default fill factor:
+</p><pre class="programlisting">
+CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70);
+</pre><p>
+ </p><p>
+ To create a <acronym class="acronym">GIN</acronym> index with fast updates disabled:
+</p><pre class="programlisting">
+CREATE INDEX gin_idx ON documents_table USING GIN (locations) WITH (fastupdate = off);
+</pre><p>
+ </p><p>
+ To create an index on the column <code class="literal">code</code> in the table
+ <code class="literal">films</code> and have the index reside in the tablespace
+ <code class="literal">indexspace</code>:
+</p><pre class="programlisting">
+CREATE INDEX code_idx ON films (code) TABLESPACE indexspace;
+</pre><p>
+ </p><p>
+ To create a GiST index on a point attribute so that we
+ can efficiently use box operators on the result of the
+ conversion function:
+</p><pre class="programlisting">
+CREATE INDEX pointloc
+ ON points USING gist (box(location,location));
+SELECT * FROM points
+ WHERE box(location,location) &amp;&amp; '(0,0),(1,1)'::box;
+</pre><p>
+ </p><p>
+ To create an index without locking out writes to the table:
+</p><pre class="programlisting">
+CREATE INDEX CONCURRENTLY sales_quantity_index ON sales_table (quantity);
+</pre></div><div class="refsect1" id="id-1.9.3.69.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE INDEX</code> is a
+ <span class="productname">PostgreSQL</span> language extension. There
+ are no provisions for indexes in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.69.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterindex.html" title="ALTER INDEX"><span class="refentrytitle">ALTER INDEX</span></a>, <a class="xref" href="sql-dropindex.html" title="DROP INDEX"><span class="refentrytitle">DROP INDEX</span></a>, <a class="xref" href="sql-reindex.html" title="REINDEX"><span class="refentrytitle">REINDEX</span></a>, <a class="xref" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING" title="28.4.2. CREATE INDEX Progress Reporting">Section 28.4.2</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-creategroup.html" title="CREATE GROUP">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createlanguage.html" title="CREATE LANGUAGE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE GROUP </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE LANGUAGE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createlanguage.html b/doc/src/sgml/html/sql-createlanguage.html
new file mode 100644
index 0000000..b67a640
--- /dev/null
+++ b/doc/src/sgml/html/sql-createlanguage.html
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE LANGUAGE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createindex.html" title="CREATE INDEX" /><link rel="next" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE LANGUAGE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createindex.html" title="CREATE INDEX">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATELANGUAGE"><div class="titlepage"></div><a id="id-1.9.3.70.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE LANGUAGE</span></h2><p>CREATE LANGUAGE — define a new procedural language</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em>
+ HANDLER <em class="replaceable"><code>call_handler</code></em> [ INLINE <em class="replaceable"><code>inline_handler</code></em> ] [ VALIDATOR <em class="replaceable"><code>valfunction</code></em> ]
+CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em>
+</pre></div><div class="refsect1" id="SQL-CREATELANGUAGE-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE LANGUAGE</code> registers a new
+ procedural language with a <span class="productname">PostgreSQL</span>
+ database. Subsequently, functions and procedures can be
+ defined in this new language.
+ </p><p>
+ <code class="command">CREATE LANGUAGE</code> effectively associates the
+ language name with handler function(s) that are responsible for executing
+ functions written in the language. Refer to <a class="xref" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Chapter 58</a>
+ for more information about language handlers.
+ </p><p>
+ <code class="command">CREATE OR REPLACE LANGUAGE</code> will either create a
+ new language, or replace an existing definition. If the language
+ already exists, its parameters are updated according to the command,
+ but the language's ownership and permissions settings do not change,
+ and any existing functions written in the language are assumed to still
+ be valid.
+ </p><p>
+ One must have the
+ <span class="productname">PostgreSQL</span> superuser privilege to
+ register a new language or change an existing language's parameters.
+ However, once the language is created it is valid to assign ownership of
+ it to a non-superuser, who may then drop it, change its permissions,
+ rename it, or assign it to a new owner. (Do not, however, assign
+ ownership of the underlying C functions to a non-superuser; that would
+ create a privilege escalation path for that user.)
+ </p><p>
+ The form of <code class="command">CREATE LANGUAGE</code> that does not supply
+ any handler function is obsolete. For backwards compatibility with
+ old dump files, it is interpreted as <code class="command">CREATE EXTENSION</code>.
+ That will work if the language has been packaged into an extension of
+ the same name, which is the conventional way to set up procedural
+ languages.
+ </p></div><div class="refsect1" id="SQL-CREATELANGUAGE-PARAMETERS"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TRUSTED</code></span></dt><dd><p><code class="literal">TRUSTED</code> specifies that the language does
+ not grant access to data that the user would not otherwise
+ have. If this key word is omitted
+ when registering the language, only users with the
+ <span class="productname">PostgreSQL</span> superuser privilege can
+ use this language to create new functions.
+ </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p>
+ This is a noise word.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the new procedural language.
+ The name must be unique among the languages in the database.
+ </p></dd><dt><span class="term"><code class="literal">HANDLER</code> <em class="replaceable"><code>call_handler</code></em></span></dt><dd><p><em class="replaceable"><code>call_handler</code></em> is
+ the name of a previously registered function that will be
+ called to execute the procedural language's functions. The call
+ handler for a procedural language must be written in a compiled
+ language such as C with version 1 call convention and
+ registered with <span class="productname">PostgreSQL</span> as a
+ function taking no arguments and returning the
+ <code class="type">language_handler</code> type, a placeholder type that is
+ simply used to identify the function as a call handler.
+ </p></dd><dt><span class="term"><code class="literal">INLINE</code> <em class="replaceable"><code>inline_handler</code></em></span></dt><dd><p><em class="replaceable"><code>inline_handler</code></em> is the
+ name of a previously registered function that will be called
+ to execute an anonymous code block
+ (<a class="link" href="sql-do.html" title="DO"><code class="command">DO</code></a> command)
+ in this language.
+ If no <em class="replaceable"><code>inline_handler</code></em>
+ function is specified, the language does not support anonymous code
+ blocks.
+ The handler function must take one argument of
+ type <code class="type">internal</code>, which will be the <code class="command">DO</code> command's
+ internal representation, and it will typically return
+ <code class="type">void</code>. The return value of the handler is ignored.
+ </p></dd><dt><span class="term"><code class="literal">VALIDATOR</code> <em class="replaceable"><code>valfunction</code></em></span></dt><dd><p><em class="replaceable"><code>valfunction</code></em> is the
+ name of a previously registered function that will be called
+ when a new function in the language is created, to validate the
+ new function.
+ If no
+ validator function is specified, then a new function will not
+ be checked when it is created.
+ The validator function must take one argument of
+ type <code class="type">oid</code>, which will be the OID of the
+ to-be-created function, and will typically return <code class="type">void</code>.
+ </p><p>
+ A validator function would typically inspect the function body
+ for syntactical correctness, but it can also look at other
+ properties of the function, for example if the language cannot
+ handle certain argument types. To signal an error, the
+ validator function should use the <code class="function">ereport()</code>
+ function. The return value of the function is ignored.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATELANGUAGE-NOTES"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-droplanguage.html" title="DROP LANGUAGE"><code class="command">DROP LANGUAGE</code></a> to drop procedural languages.
+ </p><p>
+ The system catalog <code class="classname">pg_language</code> (see <a class="xref" href="catalog-pg-language.html" title="53.29. pg_language">Section 53.29</a>) records information about the
+ currently installed languages. Also, the <span class="application">psql</span>
+ command <code class="command">\dL</code> lists the installed languages.
+ </p><p>
+ To create functions in a procedural language, a user must have the
+ <code class="literal">USAGE</code> privilege for the language. By default,
+ <code class="literal">USAGE</code> is granted to <code class="literal">PUBLIC</code> (i.e., everyone)
+ for trusted languages. This can be revoked if desired.
+ </p><p>
+ Procedural languages are local to individual databases.
+ However, a language can be installed into the <code class="literal">template1</code>
+ database, which will cause it to be available automatically in
+ all subsequently-created databases.
+ </p></div><div class="refsect1" id="SQL-CREATELANGUAGE-EXAMPLES"><h2>Examples</h2><p>
+ A minimal sequence for creating a new procedural language is:
+</p><pre class="programlisting">
+CREATE FUNCTION plsample_call_handler() RETURNS language_handler
+ AS '$libdir/plsample'
+ LANGUAGE C;
+CREATE LANGUAGE plsample
+ HANDLER plsample_call_handler;
+</pre><p>
+ Typically that would be written in an extension's creation script,
+ and users would do this to install the extension:
+</p><pre class="programlisting">
+CREATE EXTENSION plsample;
+</pre></div><div class="refsect1" id="SQL-CREATELANGUAGE-COMPAT"><h2>Compatibility</h2><p>
+ <code class="command">CREATE LANGUAGE</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.70.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterlanguage.html" title="ALTER LANGUAGE"><span class="refentrytitle">ALTER LANGUAGE</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-droplanguage.html" title="DROP LANGUAGE"><span class="refentrytitle">DROP LANGUAGE</span></a>, <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createindex.html" title="CREATE INDEX">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE INDEX </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE MATERIALIZED VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-creatematerializedview.html b/doc/src/sgml/html/sql-creatematerializedview.html
new file mode 100644
index 0000000..f3a842b
--- /dev/null
+++ b/doc/src/sgml/html/sql-creatematerializedview.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE MATERIALIZED VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createlanguage.html" title="CREATE LANGUAGE" /><link rel="next" href="sql-createoperator.html" title="CREATE OPERATOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE MATERIALIZED VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createlanguage.html" title="CREATE LANGUAGE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createoperator.html" title="CREATE OPERATOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEMATERIALIZEDVIEW"><div class="titlepage"></div><a id="id-1.9.3.71.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></h2><p>CREATE MATERIALIZED VIEW — define a new materialized view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
+ [ (<em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ [ USING <em class="replaceable"><code>method</code></em> ]
+ [ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+ [ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+ AS <em class="replaceable"><code>query</code></em>
+ [ WITH [ NO ] DATA ]
+</pre></div><div class="refsect1" id="id-1.9.3.71.5"><h2>Description</h2><p>
+ <code class="command">CREATE MATERIALIZED VIEW</code> defines a materialized view of
+ a query. The query is executed and used to populate the view at the time
+ the command is issued (unless <code class="command">WITH NO DATA</code> is used) and may be
+ refreshed later using <code class="command">REFRESH MATERIALIZED VIEW</code>.
+ </p><p>
+ <code class="command">CREATE MATERIALIZED VIEW</code> is similar to
+ <code class="command">CREATE TABLE AS</code>, except that it also remembers the query used
+ to initialize the view, so that it can be refreshed later upon demand.
+ A materialized view has many of the same properties as a table, but there
+ is no support for temporary materialized views.
+ </p><p>
+ <code class="command">CREATE MATERIALIZED VIEW</code> requires
+ <code class="literal">CREATE</code> privilege on the schema used for the materialized
+ view.
+ </p></div><div class="refsect1" id="id-1.9.3.71.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a materialized view with the same name already
+ exists. A notice is issued in this case. Note that there is no guarantee
+ that the existing materialized view is anything like the one that would
+ have been created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the materialized view to be
+ created. The name must be distinct from the name of any other relation
+ (table, sequence, index, view, materialized view, or foreign table) in
+ the same schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column in the new materialized view. If column names are
+ not provided, they are taken from the output column names of the query.
+ </p></dd><dt><span class="term"><code class="literal">USING <em class="replaceable"><code>method</code></em></code></span></dt><dd><p>
+ This optional clause specifies the table access method to use to store
+ the contents for the new materialized view; the method needs be an
+ access method of type <code class="literal">TABLE</code>. See <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> for more information. If this option is not
+ specified, the default table access method is chosen for the new
+ materialized view. See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLE-ACCESS-METHOD">default_table_access_method</a>
+ for more information.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional storage parameters for the new
+ materialized view; see
+ <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a> in the
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> documentation for more
+ information. All parameters supported for <code class="literal">CREATE
+ TABLE</code> are also supported for <code class="literal">CREATE MATERIALIZED
+ VIEW</code>.
+ See <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">TABLESPACE <em class="replaceable"><code>tablespace_name</code></em></code></span></dt><dd><p>
+ The <em class="replaceable"><code>tablespace_name</code></em> is the name
+ of the tablespace in which the new materialized view is to be created.
+ If not specified, <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> is consulted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a>, <a class="link" href="sql-select.html#SQL-TABLE" title="TABLE Command"><code class="command">TABLE</code></a>,
+ or <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a> command. This query will run within a
+ security-restricted operation; in particular, calls to functions that
+ themselves create temporary tables will fail.
+ </p></dd><dt><span class="term"><code class="literal">WITH [ NO ] DATA</code></span></dt><dd><p>
+ This clause specifies whether or not the materialized view should be
+ populated at creation time. If not, the materialized view will be
+ flagged as unscannable and cannot be queried until <code class="command">REFRESH
+ MATERIALIZED VIEW</code> is used.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.71.7"><h2>Compatibility</h2><p>
+ <code class="command">CREATE MATERIALIZED VIEW</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.71.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW"><span class="refentrytitle">ALTER MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-createtableas.html" title="CREATE TABLE AS"><span class="refentrytitle">CREATE TABLE AS</span></a>, <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a>, <a class="xref" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW"><span class="refentrytitle">DROP MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW"><span class="refentrytitle">REFRESH MATERIALIZED VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createlanguage.html" title="CREATE LANGUAGE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createoperator.html" title="CREATE OPERATOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE LANGUAGE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE OPERATOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createopclass.html b/doc/src/sgml/html/sql-createopclass.html
new file mode 100644
index 0000000..f42dd6f
--- /dev/null
+++ b/doc/src/sgml/html/sql-createopclass.html
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE OPERATOR CLASS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createoperator.html" title="CREATE OPERATOR" /><link rel="next" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE OPERATOR CLASS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createoperator.html" title="CREATE OPERATOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEOPCLASS"><div class="titlepage"></div><a id="id-1.9.3.73.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE OPERATOR CLASS</span></h2><p>CREATE OPERATOR CLASS — define a new operator class</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE OPERATOR CLASS <em class="replaceable"><code>name</code></em> [ DEFAULT ] FOR TYPE <em class="replaceable"><code>data_type</code></em>
+ USING <em class="replaceable"><code>index_method</code></em> [ FAMILY <em class="replaceable"><code>family_name</code></em> ] AS
+ { OPERATOR <em class="replaceable"><code>strategy_number</code></em> <em class="replaceable"><code>operator_name</code></em> [ ( <em class="replaceable"><code>op_type</code></em>, <em class="replaceable"><code>op_type</code></em> ) ] [ FOR SEARCH | FOR ORDER BY <em class="replaceable"><code>sort_family_name</code></em> ]
+ | FUNCTION <em class="replaceable"><code>support_number</code></em> [ ( <em class="replaceable"><code>op_type</code></em> [ , <em class="replaceable"><code>op_type</code></em> ] ) ] <em class="replaceable"><code>function_name</code></em> ( <em class="replaceable"><code>argument_type</code></em> [, ...] )
+ | STORAGE <em class="replaceable"><code>storage_type</code></em>
+ } [, ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.73.5"><h2>Description</h2><p>
+ <code class="command">CREATE OPERATOR CLASS</code> creates a new operator class.
+ An operator class defines how a particular data type can be used with
+ an index. The operator class specifies that certain operators will fill
+ particular roles or <span class="quote">“<span class="quote">strategies</span>”</span> for this data type and this
+ index method. The operator class also specifies the support functions to
+ be used by
+ the index method when the operator class is selected for an
+ index column. All the operators and functions used by an operator
+ class must be defined before the operator class can be created.
+ </p><p>
+ If a schema name is given then the operator class is created in the
+ specified schema. Otherwise it is created in the current schema.
+ Two operator classes in the same schema can have the same name only if they
+ are for different index methods.
+ </p><p>
+ The user who defines an operator class becomes its owner. Presently,
+ the creating user must be a superuser. (This restriction is made because
+ an erroneous operator class definition could confuse or even crash the
+ server.)
+ </p><p>
+ <code class="command">CREATE OPERATOR CLASS</code> does not presently check
+ whether the operator class definition includes all the operators and
+ functions required by the index method, nor whether the operators and
+ functions form a self-consistent set. It is the user's
+ responsibility to define a valid operator class.
+ </p><p>
+ Related operator classes can be grouped into <em class="firstterm">operator
+ families</em>. To add a new operator class to an existing family,
+ specify the <code class="literal">FAMILY</code> option in <code class="command">CREATE OPERATOR
+ CLASS</code>. Without this option, the new class is placed into
+ a family named the same as the new class (creating that family if
+ it doesn't already exist).
+ </p><p>
+ Refer to <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.73.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the operator class to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ If present, the operator class will become the default
+ operator class for its data type. At most one operator class
+ can be the default for a specific data type and index method.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The column data type that this operator class is for.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index method this operator class is for.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>family_name</code></em></span></dt><dd><p>
+ The name of the existing operator family to add this operator class to.
+ If not specified, a family named the same as the operator class is
+ used (creating it, if it doesn't already exist).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>strategy_number</code></em></span></dt><dd><p>
+ The index method's strategy number for an operator
+ associated with the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>operator_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an operator associated
+ with the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>op_type</code></em></span></dt><dd><p>
+ In an <code class="literal">OPERATOR</code> clause,
+ the operand data type(s) of the operator, or <code class="literal">NONE</code> to
+ signify a prefix operator. The operand data
+ types can be omitted in the normal case where they are the same
+ as the operator class's data type.
+ </p><p>
+ In a <code class="literal">FUNCTION</code> clause, the operand data type(s) the
+ function is intended to support, if different from
+ the input data type(s) of the function (for B-tree comparison functions
+ and hash functions)
+ or the class's data type (for B-tree sort support functions,
+ B-tree equal image functions, and all functions in GiST,
+ SP-GiST, GIN and BRIN operator classes). These defaults are
+ correct, and so <em class="replaceable"><code>op_type</code></em> need not be specified
+ in <code class="literal">FUNCTION</code> clauses, except for the case of a
+ B-tree sort support function that is meant to support
+ cross-data-type comparisons.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sort_family_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing <code class="literal">btree</code> operator
+ family that describes the sort ordering associated with an ordering
+ operator.
+ </p><p>
+ If neither <code class="literal">FOR SEARCH</code> nor <code class="literal">FOR ORDER BY</code> is
+ specified, <code class="literal">FOR SEARCH</code> is the default.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>support_number</code></em></span></dt><dd><p>
+ The index method's support function number for a
+ function associated with the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a function that is an
+ index method support function for the operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argument_type</code></em></span></dt><dd><p>
+ The parameter data type(s) of the function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>storage_type</code></em></span></dt><dd><p>
+ The data type actually stored in the index. Normally this is
+ the same as the column data type, but some index methods
+ (currently GiST, GIN, SP-GiST and BRIN) allow it to be different. The
+ <code class="literal">STORAGE</code> clause must be omitted unless the index
+ method allows a different type to be used.
+ If the column <em class="replaceable"><code>data_type</code></em> is specified
+ as <code class="type">anyarray</code>, the <em class="replaceable"><code>storage_type</code></em>
+ can be declared as <code class="type">anyelement</code> to indicate that the index
+ entries are members of the element type belonging to the actual array
+ type that each particular index is created for.
+ </p></dd></dl></div><p>
+ The <code class="literal">OPERATOR</code>, <code class="literal">FUNCTION</code>, and <code class="literal">STORAGE</code>
+ clauses can appear in any order.
+ </p></div><div class="refsect1" id="id-1.9.3.73.7"><h2>Notes</h2><p>
+ Because the index machinery does not check access permissions on functions
+ before using them, including a function or operator in an operator class
+ is tantamount to granting public execute permission on it. This is usually
+ not an issue for the sorts of functions that are useful in an operator
+ class.
+ </p><p>
+ The operators should not be defined by SQL functions. An SQL function
+ is likely to be inlined into the calling query, which will prevent
+ the optimizer from recognizing that the query matches an index.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> 8.4, the <code class="literal">OPERATOR</code>
+ clause could include a <code class="literal">RECHECK</code> option. This is no longer
+ supported because whether an index operator is <span class="quote">“<span class="quote">lossy</span>”</span> is now
+ determined on-the-fly at run time. This allows efficient handling of
+ cases where an operator might or might not be lossy.
+ </p></div><div class="refsect1" id="id-1.9.3.73.8"><h2>Examples</h2><p>
+ The following example command defines a GiST index operator class
+ for the data type <code class="literal">_int4</code> (array of <code class="type">int4</code>). See the
+ <a class="xref" href="intarray.html" title="F.20. intarray">intarray</a> module for the complete example.
+ </p><pre class="programlisting">
+CREATE OPERATOR CLASS gist__int_ops
+ DEFAULT FOR TYPE _int4 USING gist AS
+ OPERATOR 3 &amp;&amp;,
+ OPERATOR 6 = (anyarray, anyarray),
+ OPERATOR 7 @&gt;,
+ OPERATOR 8 &lt;@,
+ OPERATOR 20 @@ (_int4, query_int),
+ FUNCTION 1 g_int_consistent (internal, _int4, smallint, oid, internal),
+ FUNCTION 2 g_int_union (internal, internal),
+ FUNCTION 3 g_int_compress (internal),
+ FUNCTION 4 g_int_decompress (internal),
+ FUNCTION 5 g_int_penalty (internal, internal, internal),
+ FUNCTION 6 g_int_picksplit (internal, internal),
+ FUNCTION 7 g_int_same (_int4, _int4, internal);
+</pre></div><div class="refsect1" id="id-1.9.3.73.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE OPERATOR CLASS</code> is a
+ <span class="productname">PostgreSQL</span> extension. There is no
+ <code class="command">CREATE OPERATOR CLASS</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.73.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS"><span class="refentrytitle">ALTER OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopclass.html" title="DROP OPERATOR CLASS"><span class="refentrytitle">DROP OPERATOR CLASS</span></a>, <a class="xref" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY"><span class="refentrytitle">CREATE OPERATOR FAMILY</span></a>, <a class="xref" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY"><span class="refentrytitle">ALTER OPERATOR FAMILY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createoperator.html" title="CREATE OPERATOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE OPERATOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE OPERATOR FAMILY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createoperator.html b/doc/src/sgml/html/sql-createoperator.html
new file mode 100644
index 0000000..994a234
--- /dev/null
+++ b/doc/src/sgml/html/sql-createoperator.html
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE OPERATOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW" /><link rel="next" href="sql-createopclass.html" title="CREATE OPERATOR CLASS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE OPERATOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createopclass.html" title="CREATE OPERATOR CLASS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEOPERATOR"><div class="titlepage"></div><a id="id-1.9.3.72.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE OPERATOR</span></h2><p>CREATE OPERATOR — define a new operator</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE OPERATOR <em class="replaceable"><code>name</code></em> (
+ {FUNCTION|PROCEDURE} = <em class="replaceable"><code>function_name</code></em>
+ [, LEFTARG = <em class="replaceable"><code>left_type</code></em> ] [, RIGHTARG = <em class="replaceable"><code>right_type</code></em> ]
+ [, COMMUTATOR = <em class="replaceable"><code>com_op</code></em> ] [, NEGATOR = <em class="replaceable"><code>neg_op</code></em> ]
+ [, RESTRICT = <em class="replaceable"><code>res_proc</code></em> ] [, JOIN = <em class="replaceable"><code>join_proc</code></em> ]
+ [, HASHES ] [, MERGES ]
+)
+</pre></div><div class="refsect1" id="id-1.9.3.72.5"><h2>Description</h2><p>
+ <code class="command">CREATE OPERATOR</code> defines a new operator,
+ <em class="replaceable"><code>name</code></em>. The user who
+ defines an operator becomes its owner. If a schema name is given
+ then the operator is created in the specified schema. Otherwise it
+ is created in the current schema.
+ </p><p>
+ The operator name is a sequence of up to <code class="symbol">NAMEDATALEN</code>-1
+ (63 by default) characters from the following list:
+</p><div class="literallayout"><p><br />
++ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?<br />
+</p></div><p>
+
+ There are a few restrictions on your choice of name:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">--</code> and <code class="literal">/*</code> cannot appear anywhere in an operator name,
+ since they will be taken as the start of a comment.
+ </p></li><li class="listitem"><p>
+ A multicharacter operator name cannot end in <code class="literal">+</code> or
+ <code class="literal">-</code>,
+ unless the name also contains at least one of these characters:
+</p><div class="literallayout"><p><br />
+~ ! @ # % ^ &amp; | ` ?<br />
+</p></div><p>
+ For example, <code class="literal">@-</code> is an allowed operator name,
+ but <code class="literal">*-</code> is not.
+ This restriction allows <span class="productname">PostgreSQL</span> to
+ parse SQL-compliant commands without requiring spaces between tokens.
+ </p></li><li class="listitem"><p>
+ The symbol <code class="literal">=&gt;</code> is reserved by the SQL grammar,
+ so it cannot be used as an operator name.
+ </p></li></ul></div><p>
+ </p><p>
+ The operator <code class="literal">!=</code> is mapped to
+ <code class="literal">&lt;&gt;</code> on input, so these two names are always
+ equivalent.
+ </p><p>
+ For binary operators, both <code class="literal">LEFTARG</code> and
+ <code class="literal">RIGHTARG</code> must be defined. For prefix operators only
+ <code class="literal">RIGHTARG</code> should be defined.
+ The <em class="replaceable"><code>function_name</code></em>
+ function must have been previously defined using <code class="command">CREATE
+ FUNCTION</code> and must be defined to accept the correct number
+ of arguments (either one or two) of the indicated types.
+ </p><p>
+ In the syntax of <code class="literal">CREATE OPERATOR</code>, the keywords
+ <code class="literal">FUNCTION</code> and <code class="literal">PROCEDURE</code> are
+ equivalent, but the referenced function must in any case be a function, not
+ a procedure. The use of the keyword <code class="literal">PROCEDURE</code> here is
+ historical and deprecated.
+ </p><p>
+ The other clauses specify optional operator optimization clauses.
+ Their meaning is detailed in <a class="xref" href="xoper-optimization.html" title="38.15. Operator Optimization Information">Section 38.15</a>.
+ </p><p>
+ To be able to create an operator, you must have <code class="literal">USAGE</code>
+ privilege on the argument types and the return type, as well
+ as <code class="literal">EXECUTE</code> privilege on the underlying function. If a
+ commutator or negator operator is specified, you must own these operators.
+ </p></div><div class="refsect1" id="id-1.9.3.72.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the operator to be defined. See above for allowable
+ characters. The name can be schema-qualified, for example
+ <code class="literal">CREATE OPERATOR myschema.+ (...)</code>. If not, then
+ the operator is created in the current schema. Two operators
+ in the same schema can have the same name if they operate on
+ different data types. This is called
+ <em class="firstterm">overloading</em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ The function used to implement this operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em></span></dt><dd><p>
+ The data type of the operator's left operand, if any.
+ This option would be omitted for a prefix operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
+ The data type of the operator's right operand.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>com_op</code></em></span></dt><dd><p>
+ The commutator of this operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>neg_op</code></em></span></dt><dd><p>
+ The negator of this operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>res_proc</code></em></span></dt><dd><p>
+ The restriction selectivity estimator function for this operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>join_proc</code></em></span></dt><dd><p>
+ The join selectivity estimator function for this operator.
+ </p></dd><dt><span class="term"><code class="literal">HASHES</code></span></dt><dd><p>
+ Indicates this operator can support a hash join.
+ </p></dd><dt><span class="term"><code class="literal">MERGES</code></span></dt><dd><p>
+ Indicates this operator can support a merge join.
+ </p></dd></dl></div><p>
+ To give a schema-qualified operator name in <em class="replaceable"><code>com_op</code></em> or the other optional
+ arguments, use the <code class="literal">OPERATOR()</code> syntax, for example:
+</p><pre class="programlisting">
+COMMUTATOR = OPERATOR(myschema.===) ,
+</pre></div><div class="refsect1" id="id-1.9.3.72.7"><h2>Notes</h2><p>
+ Refer to <a class="xref" href="xoper.html" title="38.14. User-Defined Operators">Section 38.14</a> for further information.
+ </p><p>
+ It is not possible to specify an operator's lexical precedence in
+ <code class="command">CREATE OPERATOR</code>, because the parser's precedence behavior
+ is hard-wired. See <a class="xref" href="sql-syntax-lexical.html#SQL-PRECEDENCE" title="4.1.6. Operator Precedence">Section 4.1.6</a> for precedence details.
+ </p><p>
+ The obsolete options <code class="literal">SORT1</code>, <code class="literal">SORT2</code>,
+ <code class="literal">LTCMP</code>, and <code class="literal">GTCMP</code> were formerly used to
+ specify the names of sort operators associated with a merge-joinable
+ operator. This is no longer necessary, since information about
+ associated operators is found by looking at B-tree operator families
+ instead. If one of these options is given, it is ignored except
+ for implicitly setting <code class="literal">MERGES</code> true.
+ </p><p>
+ Use <a class="link" href="sql-dropoperator.html" title="DROP OPERATOR"><code class="command">DROP OPERATOR</code></a> to delete user-defined operators
+ from a database. Use <a class="link" href="sql-alteroperator.html" title="ALTER OPERATOR"><code class="command">ALTER OPERATOR</code></a> to modify operators in a
+ database.
+ </p></div><div class="refsect1" id="id-1.9.3.72.8"><h2>Examples</h2><p>
+ The following command defines a new operator, area-equality, for
+ the data type <code class="type">box</code>:
+</p><pre class="programlisting">
+CREATE OPERATOR === (
+ LEFTARG = box,
+ RIGHTARG = box,
+ FUNCTION = area_equal_function,
+ COMMUTATOR = ===,
+ NEGATOR = !==,
+ RESTRICT = area_restriction_function,
+ JOIN = area_join_function,
+ HASHES, MERGES
+);
+</pre></div><div class="refsect1" id="id-1.9.3.72.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE OPERATOR</code> is a
+ <span class="productname">PostgreSQL</span> extension. There are no
+ provisions for user-defined operators in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.72.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteroperator.html" title="ALTER OPERATOR"><span class="refentrytitle">ALTER OPERATOR</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropoperator.html" title="DROP OPERATOR"><span class="refentrytitle">DROP OPERATOR</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createopclass.html" title="CREATE OPERATOR CLASS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE MATERIALIZED VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE OPERATOR CLASS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createopfamily.html b/doc/src/sgml/html/sql-createopfamily.html
new file mode 100644
index 0000000..48e1e0c
--- /dev/null
+++ b/doc/src/sgml/html/sql-createopfamily.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE OPERATOR FAMILY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createopclass.html" title="CREATE OPERATOR CLASS" /><link rel="next" href="sql-createpolicy.html" title="CREATE POLICY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE OPERATOR FAMILY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createopclass.html" title="CREATE OPERATOR CLASS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createpolicy.html" title="CREATE POLICY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEOPFAMILY"><div class="titlepage"></div><a id="id-1.9.3.74.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE OPERATOR FAMILY</span></h2><p>CREATE OPERATOR FAMILY — define a new operator family</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE OPERATOR FAMILY <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.74.5"><h2>Description</h2><p>
+ <code class="command">CREATE OPERATOR FAMILY</code> creates a new operator family.
+ An operator family defines a collection of related operator classes,
+ and perhaps some additional operators and support functions that are
+ compatible with these operator classes but not essential for the
+ functioning of any individual index. (Operators and functions that
+ are essential to indexes should be grouped within the relevant operator
+ class, rather than being <span class="quote">“<span class="quote">loose</span>”</span> in the operator family.
+ Typically, single-data-type operators are bound to operator classes,
+ while cross-data-type operators can be loose in an operator family
+ containing operator classes for both data types.)
+ </p><p>
+ The new operator family is initially empty. It should be populated
+ by issuing subsequent <code class="command">CREATE OPERATOR CLASS</code> commands
+ to add contained operator classes, and optionally
+ <code class="command">ALTER OPERATOR FAMILY</code> commands to add <span class="quote">“<span class="quote">loose</span>”</span>
+ operators and their corresponding support functions.
+ </p><p>
+ If a schema name is given then the operator family is created in the
+ specified schema. Otherwise it is created in the current schema.
+ Two operator families in the same schema can have the same name only if they
+ are for different index methods.
+ </p><p>
+ The user who defines an operator family becomes its owner. Presently,
+ the creating user must be a superuser. (This restriction is made because
+ an erroneous operator family definition could confuse or even crash the
+ server.)
+ </p><p>
+ Refer to <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.74.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the operator family to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index method this operator family is for.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.74.7"><h2>Compatibility</h2><p>
+ <code class="command">CREATE OPERATOR FAMILY</code> is a
+ <span class="productname">PostgreSQL</span> extension. There is no
+ <code class="command">CREATE OPERATOR FAMILY</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.74.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY"><span class="refentrytitle">ALTER OPERATOR FAMILY</span></a>, <a class="xref" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY"><span class="refentrytitle">DROP OPERATOR FAMILY</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS"><span class="refentrytitle">ALTER OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopclass.html" title="DROP OPERATOR CLASS"><span class="refentrytitle">DROP OPERATOR CLASS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createopclass.html" title="CREATE OPERATOR CLASS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createpolicy.html" title="CREATE POLICY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE OPERATOR CLASS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE POLICY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createpolicy.html b/doc/src/sgml/html/sql-createpolicy.html
new file mode 100644
index 0000000..3465759
--- /dev/null
+++ b/doc/src/sgml/html/sql-createpolicy.html
@@ -0,0 +1,361 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE POLICY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY" /><link rel="next" href="sql-createprocedure.html" title="CREATE PROCEDURE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE POLICY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createprocedure.html" title="CREATE PROCEDURE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEPOLICY"><div class="titlepage"></div><a id="id-1.9.3.75.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE POLICY</span></h2><p>CREATE POLICY — define a new row-level security policy for a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE POLICY <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em>
+ [ AS { PERMISSIVE | RESTRICTIVE } ]
+ [ FOR { ALL | SELECT | INSERT | UPDATE | DELETE } ]
+ [ TO { <em class="replaceable"><code>role_name</code></em> | PUBLIC | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, ...] ]
+ [ USING ( <em class="replaceable"><code>using_expression</code></em> ) ]
+ [ WITH CHECK ( <em class="replaceable"><code>check_expression</code></em> ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.75.5"><h2>Description</h2><p>
+ The <code class="command">CREATE POLICY</code> command defines a new row-level
+ security policy for a table. Note that row-level security must be
+ enabled on the table (using <code class="command">ALTER TABLE ... ENABLE ROW LEVEL
+ SECURITY</code>) in order for created policies to be applied.
+ </p><p>
+ A policy grants the permission to select, insert, update, or delete rows
+ that match the relevant policy expression. Existing table rows are
+ checked against the expression specified in <code class="literal">USING</code>,
+ while new rows that would be created via <code class="literal">INSERT</code>
+ or <code class="literal">UPDATE</code> are checked against the expression specified
+ in <code class="literal">WITH CHECK</code>. When a <code class="literal">USING</code>
+ expression returns true for a given row then that row is visible to the
+ user, while if false or null is returned then the row is not visible.
+ When a <code class="literal">WITH CHECK</code> expression returns true for a row
+ then that row is inserted or updated, while if false or null is returned
+ then an error occurs.
+ </p><p>
+ For <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">MERGE</code> statements,
+ <code class="literal">WITH CHECK</code> expressions are enforced after
+ <code class="literal">BEFORE</code> triggers are fired, and before any actual data
+ modifications are made. Thus a <code class="literal">BEFORE ROW</code> trigger may
+ modify the data to be inserted, affecting the result of the security
+ policy check. <code class="literal">WITH CHECK</code> expressions are enforced
+ before any other constraints.
+ </p><p>
+ Policy names are per-table. Therefore, one policy name can be used for many
+ different tables and have a definition for each table which is appropriate to
+ that table.
+ </p><p>
+ Policies can be applied for specific commands or for specific roles. The
+ default for newly created policies is that they apply for all commands and
+ roles, unless otherwise specified. Multiple policies may apply to a single
+ command; see below for more details.
+ <a class="xref" href="sql-createpolicy.html#SQL-CREATEPOLICY-SUMMARY" title="Table 287. Policies Applied by Command Type">Table 287</a> summarizes how the different types
+ of policy apply to specific commands.
+ </p><p>
+ For policies that can have both <code class="literal">USING</code>
+ and <code class="literal">WITH CHECK</code> expressions (<code class="literal">ALL</code>
+ and <code class="literal">UPDATE</code>), if no <code class="literal">WITH CHECK</code>
+ expression is defined, then the <code class="literal">USING</code> expression will be
+ used both to determine which rows are visible (normal
+ <code class="literal">USING</code> case) and which new rows will be allowed to be
+ added (<code class="literal">WITH CHECK</code> case).
+ </p><p>
+ If row-level security is enabled for a table, but no applicable policies
+ exist, a <span class="quote">“<span class="quote">default deny</span>”</span> policy is assumed, so that no rows will
+ be visible or updatable.
+ </p></div><div class="refsect1" id="id-1.9.3.75.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the policy to be created. This must be distinct from the
+ name of any other policy for the table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table the
+ policy applies to.
+ </p></dd><dt><span class="term"><code class="literal">PERMISSIVE</code></span></dt><dd><p>
+ Specify that the policy is to be created as a permissive policy.
+ All permissive policies which are applicable to a given query will
+ be combined together using the Boolean <span class="quote">“<span class="quote">OR</span>”</span> operator. By creating
+ permissive policies, administrators can add to the set of records
+ which can be accessed. Policies are permissive by default.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICTIVE</code></span></dt><dd><p>
+ Specify that the policy is to be created as a restrictive policy.
+ All restrictive policies which are applicable to a given query will
+ be combined together using the Boolean <span class="quote">“<span class="quote">AND</span>”</span> operator. By creating
+ restrictive policies, administrators can reduce the set of records
+ which can be accessed as all restrictive policies must be passed for
+ each record.
+ </p><p>
+ Note that there needs to be at least one permissive policy to grant
+ access to records before restrictive policies can be usefully used to
+ reduce that access. If only restrictive policies exist, then no records
+ will be accessible. When a mix of permissive and restrictive policies
+ are present, a record is only accessible if at least one of the
+ permissive policies passes, in addition to all the restrictive
+ policies.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>command</code></em></span></dt><dd><p>
+ The command to which the policy applies. Valid options are
+ <code class="command">ALL</code>, <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ and <code class="command">DELETE</code>.
+ <code class="command">ALL</code> is the default.
+ See below for specifics regarding how these are applied.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The role(s) to which the policy is to be applied. The default is
+ <code class="literal">PUBLIC</code>, which will apply the policy to all roles.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>using_expression</code></em></span></dt><dd><p>
+ Any <acronym class="acronym">SQL</acronym> conditional expression (returning
+ <code class="type">boolean</code>). The conditional expression cannot contain
+ any aggregate or window functions. This expression will be added
+ to queries that refer to the table if row-level security is enabled.
+ Rows for which the expression returns true will be visible. Any
+ rows for which the expression returns false or null will not be
+ visible to the user (in a <code class="command">SELECT</code>), and will not be
+ available for modification (in an <code class="command">UPDATE</code>
+ or <code class="command">DELETE</code>). Such rows are silently suppressed; no error
+ is reported.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>check_expression</code></em></span></dt><dd><p>
+ Any <acronym class="acronym">SQL</acronym> conditional expression (returning
+ <code class="type">boolean</code>). The conditional expression cannot contain
+ any aggregate or window functions. This expression will be used in
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> queries against
+ the table if row-level security is enabled. Only rows for which the
+ expression evaluates to true will be allowed. An error will be thrown
+ if the expression evaluates to false or null for any of the records
+ inserted or any of the records that result from the update. Note that
+ the <em class="replaceable"><code>check_expression</code></em> is
+ evaluated against the proposed new contents of the row, not the
+ original contents.
+ </p></dd></dl></div><div class="refsect2" id="id-1.9.3.75.6.3"><h3>Per-Command Policies</h3><div class="variablelist"><dl class="variablelist"><dt id="SQL-CREATEPOLICY-ALL"><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Using <code class="literal">ALL</code> for a policy means that it will apply
+ to all commands, regardless of the type of command. If an
+ <code class="literal">ALL</code> policy exists and more specific policies
+ exist, then both the <code class="literal">ALL</code> policy and the more
+ specific policy (or policies) will be applied.
+ Additionally, <code class="literal">ALL</code> policies will be applied to
+ both the selection side of a query and the modification side, using
+ the <code class="literal">USING</code> expression for both cases if only
+ a <code class="literal">USING</code> expression has been defined.
+ </p><p>
+ As an example, if an <code class="literal">UPDATE</code> is issued, then the
+ <code class="literal">ALL</code> policy will be applicable both to what the
+ <code class="literal">UPDATE</code> will be able to select as rows to be
+ updated (applying the <code class="literal">USING</code> expression),
+ and to the resulting updated rows, to check if they are permitted
+ to be added to the table (applying the <code class="literal">WITH CHECK</code>
+ expression, if defined, and the <code class="literal">USING</code> expression
+ otherwise). If an <code class="command">INSERT</code>
+ or <code class="command">UPDATE</code> command attempts to add rows to the
+ table that do not pass the <code class="literal">ALL</code>
+ policy's <code class="literal">WITH CHECK</code> expression, the entire
+ command will be aborted.
+ </p></dd><dt id="SQL-CREATEPOLICY-SELECT"><span class="term"><code class="literal">SELECT</code></span></dt><dd><p>
+ Using <code class="literal">SELECT</code> for a policy means that it will apply
+ to <code class="literal">SELECT</code> queries and whenever
+ <code class="literal">SELECT</code> permissions are required on the relation the
+ policy is defined for. The result is that only those records from the
+ relation that pass the <code class="literal">SELECT</code> policy will be
+ returned during a <code class="literal">SELECT</code> query, and that queries
+ that require <code class="literal">SELECT</code> permissions, such as
+ <code class="literal">UPDATE</code>, will also only see those records
+ that are allowed by the <code class="literal">SELECT</code> policy.
+ A <code class="literal">SELECT</code> policy cannot have a <code class="literal">WITH
+ CHECK</code> expression, as it only applies in cases where
+ records are being retrieved from the relation.
+ </p></dd><dt id="SQL-CREATEPOLICY-INSERT"><span class="term"><code class="literal">INSERT</code></span></dt><dd><p>
+ Using <code class="literal">INSERT</code> for a policy means that it will apply
+ to <code class="literal">INSERT</code> commands and <code class="literal">MERGE</code>
+ commands that contain <code class="literal">INSERT</code> actions.
+ Rows being inserted that do
+ not pass this policy will result in a policy violation error, and the
+ entire <code class="literal">INSERT</code> command will be aborted.
+ An <code class="literal">INSERT</code> policy cannot have
+ a <code class="literal">USING</code> expression, as it only applies in cases
+ where records are being added to the relation.
+ </p><p>
+ Note that <code class="literal">INSERT</code> with <code class="literal">ON CONFLICT DO
+ UPDATE</code> checks <code class="literal">INSERT</code> policies'
+ <code class="literal">WITH CHECK</code> expressions only for rows appended
+ to the relation by the <code class="literal">INSERT</code> path.
+ </p></dd><dt id="SQL-CREATEPOLICY-UPDATE"><span class="term"><code class="literal">UPDATE</code></span></dt><dd><p>
+ Using <code class="literal">UPDATE</code> for a policy means that it will apply
+ to <code class="literal">UPDATE</code>, <code class="literal">SELECT FOR UPDATE</code>
+ and <code class="literal">SELECT FOR SHARE</code> commands, as well as
+ auxiliary <code class="literal">ON CONFLICT DO UPDATE</code> clauses of
+ <code class="literal">INSERT</code> commands.
+ <code class="literal">MERGE</code> commands containing <code class="literal">UPDATE</code>
+ actions are affected as well. Since <code class="literal">UPDATE</code>
+ involves pulling an existing record and replacing it with a new
+ modified record, <code class="literal">UPDATE</code>
+ policies accept both a <code class="literal">USING</code> expression and
+ a <code class="literal">WITH CHECK</code> expression.
+ The <code class="literal">USING</code> expression determines which records
+ the <code class="literal">UPDATE</code> command will see to operate against,
+ while the <code class="literal">WITH CHECK</code> expression defines which
+ modified rows are allowed to be stored back into the relation.
+ </p><p>
+ Any rows whose updated values do not pass the
+ <code class="literal">WITH CHECK</code> expression will cause an error, and the
+ entire command will be aborted. If only a <code class="literal">USING</code>
+ clause is specified, then that clause will be used for both
+ <code class="literal">USING</code> and <code class="literal">WITH CHECK</code> cases.
+ </p><p>
+ Typically an <code class="literal">UPDATE</code> command also needs to read
+ data from columns in the relation being updated (e.g., in a
+ <code class="literal">WHERE</code> clause or a <code class="literal">RETURNING</code>
+ clause, or in an expression on the right hand side of the
+ <code class="literal">SET</code> clause). In this case,
+ <code class="literal">SELECT</code> rights are also required on the relation
+ being updated, and the appropriate <code class="literal">SELECT</code> or
+ <code class="literal">ALL</code> policies will be applied in addition to
+ the <code class="literal">UPDATE</code> policies. Thus the user must have
+ access to the row(s) being updated through a <code class="literal">SELECT</code>
+ or <code class="literal">ALL</code> policy in addition to being granted
+ permission to update the row(s) via an <code class="literal">UPDATE</code>
+ or <code class="literal">ALL</code> policy.
+ </p><p>
+ When an <code class="literal">INSERT</code> command has an auxiliary
+ <code class="literal">ON CONFLICT DO UPDATE</code> clause, if the
+ <code class="literal">UPDATE</code> path is taken, the row to be updated is
+ first checked against the <code class="literal">USING</code> expressions of
+ any <code class="literal">UPDATE</code> policies, and then the new updated row
+ is checked against the <code class="literal">WITH CHECK</code> expressions.
+ Note, however, that unlike a standalone <code class="literal">UPDATE</code>
+ command, if the existing row does not pass the
+ <code class="literal">USING</code> expressions, an error will be thrown (the
+ <code class="literal">UPDATE</code> path will <span class="emphasis"><em>never</em></span> be silently
+ avoided).
+ </p></dd><dt id="SQL-CREATEPOLICY-DELETE"><span class="term"><code class="literal">DELETE</code></span></dt><dd><p>
+ Using <code class="literal">DELETE</code> for a policy means that it will apply
+ to <code class="literal">DELETE</code> commands. Only rows that pass this
+ policy will be seen by a <code class="literal">DELETE</code> command. There can
+ be rows that are visible through a <code class="literal">SELECT</code> that are
+ not available for deletion, if they do not pass the
+ <code class="literal">USING</code> expression for
+ the <code class="literal">DELETE</code> policy.
+ </p><p>
+ In most cases a <code class="literal">DELETE</code> command also needs to read
+ data from columns in the relation that it is deleting from (e.g.,
+ in a <code class="literal">WHERE</code> clause or a
+ <code class="literal">RETURNING</code> clause). In this case,
+ <code class="literal">SELECT</code> rights are also required on the relation,
+ and the appropriate <code class="literal">SELECT</code> or
+ <code class="literal">ALL</code> policies will be applied in addition to
+ the <code class="literal">DELETE</code> policies. Thus the user must have
+ access to the row(s) being deleted through a <code class="literal">SELECT</code>
+ or <code class="literal">ALL</code> policy in addition to being granted
+ permission to delete the row(s) via a <code class="literal">DELETE</code> or
+ <code class="literal">ALL</code> policy.
+ </p><p>
+ A <code class="literal">DELETE</code> policy cannot have a <code class="literal">WITH
+ CHECK</code> expression, as it only applies in cases where
+ records are being deleted from the relation, so that there is no
+ new row to check.
+ </p></dd></dl></div><div class="table" id="SQL-CREATEPOLICY-SUMMARY"><p class="title"><strong>Table 287. Policies Applied by Command Type</strong></p><div class="table-contents"><table class="table" summary="Policies Applied by Command Type" border="1"><colgroup><col /><col /><col /><col class="update-using" /><col class="update-check" /><col /></colgroup><thead><tr><th rowspan="2">Command</th><th><code class="literal">SELECT/ALL policy</code></th><th><code class="literal">INSERT/ALL policy</code></th><th colspan="2"><code class="literal">UPDATE/ALL policy</code></th><th><code class="literal">DELETE/ALL policy</code></th></tr><tr><th><code class="literal">USING expression</code></th><th><code class="literal">WITH CHECK expression</code></th><th><code class="literal">USING expression</code></th><th><code class="literal">WITH CHECK expression</code></th><th><code class="literal">USING expression</code></th></tr></thead><tbody><tr><td><code class="command">SELECT</code></td><td>Existing row</td><td>—</td><td>—</td><td>—</td><td>—</td></tr><tr><td><code class="command">SELECT FOR UPDATE/SHARE</code></td><td>Existing row</td><td>—</td><td>Existing row</td><td>—</td><td>—</td></tr><tr><td><code class="command">INSERT</code> / <code class="command">MERGE ... THEN INSERT</code></td><td>—</td><td>New row</td><td>—</td><td>—</td><td>—</td></tr><tr><td><code class="command">INSERT ... RETURNING</code></td><td>
+ New row <a href="#ftn.RLS-SELECT-PRIV" class="footnote"><sup class="footnote" id="RLS-SELECT-PRIV">[a]</sup></a>
+ </td><td>New row</td><td>—</td><td>—</td><td>—</td></tr><tr><td><code class="command">UPDATE</code> / <code class="command">MERGE ... THEN UPDATE</code></td><td>
+ Existing &amp; new rows <a href="sql-createpolicy.html#ftn.RLS-SELECT-PRIV" class="footnoteref"><sup class="footnoteref">[a]</sup></a>
+ </td><td>—</td><td>Existing row</td><td>New row</td><td>—</td></tr><tr><td><code class="command">DELETE</code></td><td>
+ Existing row <a href="sql-createpolicy.html#ftn.RLS-SELECT-PRIV" class="footnoteref"><sup class="footnoteref">[a]</sup></a>
+ </td><td>—</td><td>—</td><td>—</td><td>Existing row</td></tr><tr><td><code class="command">ON CONFLICT DO UPDATE</code></td><td>Existing &amp; new rows</td><td>—</td><td>Existing row</td><td>New row</td><td>—</td></tr></tbody><tbody class="footnotes"><tr><td colspan="6"><div id="ftn.RLS-SELECT-PRIV" class="footnote"><p><a href="#RLS-SELECT-PRIV" class="para"><sup class="para">[a] </sup></a>
+ If read access is required to the existing or new row (for example,
+ a <code class="literal">WHERE</code> or <code class="literal">RETURNING</code> clause
+ that refers to columns from the relation).
+ </p></div></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="refsect2" id="id-1.9.3.75.6.4"><h3>Application of Multiple Policies</h3><p>
+ When multiple policies of different command types apply to the same command
+ (for example, <code class="literal">SELECT</code> and <code class="literal">UPDATE</code>
+ policies applied to an <code class="literal">UPDATE</code> command), then the user
+ must have both types of permissions (for example, permission to select rows
+ from the relation as well as permission to update them). Thus the
+ expressions for one type of policy are combined with the expressions for
+ the other type of policy using the <code class="literal">AND</code> operator.
+ </p><p>
+ When multiple policies of the same command type apply to the same command,
+ then there must be at least one <code class="literal">PERMISSIVE</code> policy
+ granting access to the relation, and all of the
+ <code class="literal">RESTRICTIVE</code> policies must pass. Thus all the
+ <code class="literal">PERMISSIVE</code> policy expressions are combined using
+ <code class="literal">OR</code>, all the <code class="literal">RESTRICTIVE</code> policy
+ expressions are combined using <code class="literal">AND</code>, and the results are
+ combined using <code class="literal">AND</code>. If there are no
+ <code class="literal">PERMISSIVE</code> policies, then access is denied.
+ </p><p>
+ Note that, for the purposes of combining multiple policies,
+ <code class="literal">ALL</code> policies are treated as having the same type as
+ whichever other type of policy is being applied.
+ </p><p>
+ For example, in an <code class="literal">UPDATE</code> command requiring both
+ <code class="literal">SELECT</code> and <code class="literal">UPDATE</code> permissions, if
+ there are multiple applicable policies of each type, they will be combined
+ as follows:
+
+</p><pre class="programlisting">
+<em class="replaceable"><code>expression</code></em> from RESTRICTIVE SELECT/ALL policy 1
+AND
+<em class="replaceable"><code>expression</code></em> from RESTRICTIVE SELECT/ALL policy 2
+AND
+...
+AND
+(
+ <em class="replaceable"><code>expression</code></em> from PERMISSIVE SELECT/ALL policy 1
+ OR
+ <em class="replaceable"><code>expression</code></em> from PERMISSIVE SELECT/ALL policy 2
+ OR
+ ...
+)
+AND
+<em class="replaceable"><code>expression</code></em> from RESTRICTIVE UPDATE/ALL policy 1
+AND
+<em class="replaceable"><code>expression</code></em> from RESTRICTIVE UPDATE/ALL policy 2
+AND
+...
+AND
+(
+ <em class="replaceable"><code>expression</code></em> from PERMISSIVE UPDATE/ALL policy 1
+ OR
+ <em class="replaceable"><code>expression</code></em> from PERMISSIVE UPDATE/ALL policy 2
+ OR
+ ...
+)
+</pre></div></div><div class="refsect1" id="id-1.9.3.75.7"><h2>Notes</h2><p>
+ You must be the owner of a table to create or change policies for it.
+ </p><p>
+ While policies will be applied for explicit queries against tables
+ in the database, they are not applied when the system is performing internal
+ referential integrity checks or validating constraints. This means there are
+ indirect ways to determine that a given value exists. An example of this is
+ attempting to insert a duplicate value into a column that is a primary key
+ or has a unique constraint. If the insert fails then the user can infer that
+ the value already exists. (This example assumes that the user is permitted by
+ policy to insert records which they are not allowed to see.) Another example
+ is where a user is allowed to insert into a table which references another,
+ otherwise hidden table. Existence can be determined by the user inserting
+ values into the referencing table, where success would indicate that the
+ value exists in the referenced table. These issues can be addressed by
+ carefully crafting policies to prevent users from being able to insert,
+ delete, or update records at all which might possibly indicate a value they
+ are not otherwise able to see, or by using generated values (e.g., surrogate
+ keys) instead of keys with external meanings.
+ </p><p>
+ Generally, the system will enforce filter conditions imposed using
+ security policies prior to qualifications that appear in user queries,
+ in order to prevent inadvertent exposure of the protected data to
+ user-defined functions which might not be trustworthy. However,
+ functions and operators marked by the system (or the system
+ administrator) as <code class="literal">LEAKPROOF</code> may be evaluated before
+ policy expressions, as they are assumed to be trustworthy.
+ </p><p>
+ Since policy expressions
+ are added to the user's query directly, they will be run with the rights of
+ the user running the overall query. Therefore, users who are using a given
+ policy must be able to access any tables or functions referenced in the
+ expression or they will simply receive a permission denied error when
+ attempting to query the table that has row-level security enabled.
+ This does not change how views
+ work, however. As with normal queries and views, permission checks and
+ policies for the tables which are referenced by a view will use the view
+ owner's rights and any policies which apply to the view owner, except if
+ the view is defined using the <code class="literal">security_invoker</code> option
+ (see <a class="link" href="sql-createview.html" title="CREATE VIEW"><code class="command">CREATE VIEW</code></a>).
+ </p><p>
+ No separate policy exists for <code class="command">MERGE</code>. Instead, the policies
+ defined for <code class="command">SELECT</code>, <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, and <code class="command">DELETE</code> are applied
+ while executing <code class="command">MERGE</code>, depending on the actions that are
+ performed.
+ </p><p>
+ Additional discussion and practical examples can be found
+ in <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.75.8"><h2>Compatibility</h2><p>
+ <code class="command">CREATE POLICY</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.75.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterpolicy.html" title="ALTER POLICY"><span class="refentrytitle">ALTER POLICY</span></a>, <a class="xref" href="sql-droppolicy.html" title="DROP POLICY"><span class="refentrytitle">DROP POLICY</span></a>, <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createprocedure.html" title="CREATE PROCEDURE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE OPERATOR FAMILY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE PROCEDURE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createprocedure.html b/doc/src/sgml/html/sql-createprocedure.html
new file mode 100644
index 0000000..d819963
--- /dev/null
+++ b/doc/src/sgml/html/sql-createprocedure.html
@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE PROCEDURE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createpolicy.html" title="CREATE POLICY" /><link rel="next" href="sql-createpublication.html" title="CREATE PUBLICATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE PROCEDURE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createpolicy.html" title="CREATE POLICY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createpublication.html" title="CREATE PUBLICATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEPROCEDURE"><div class="titlepage"></div><a id="id-1.9.3.76.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE PROCEDURE</span></h2><p>CREATE PROCEDURE — define a new procedure</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] PROCEDURE
+ <em class="replaceable"><code>name</code></em> ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ { DEFAULT | = } <em class="replaceable"><code>default_expr</code></em> ] [, ...] ] )
+ { LANGUAGE <em class="replaceable"><code>lang_name</code></em>
+ | TRANSFORM { FOR TYPE <em class="replaceable"><code>type_name</code></em> } [, ... ]
+ | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
+ | SET <em class="replaceable"><code>configuration_parameter</code></em> { TO <em class="replaceable"><code>value</code></em> | = <em class="replaceable"><code>value</code></em> | FROM CURRENT }
+ | AS '<em class="replaceable"><code>definition</code></em>'
+ | AS '<em class="replaceable"><code>obj_file</code></em>', '<em class="replaceable"><code>link_symbol</code></em>'
+ | <em class="replaceable"><code>sql_body</code></em>
+ } ...
+</pre></div><div class="refsect1" id="SQL-CREATEPROCEDURE-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE PROCEDURE</code> defines a new procedure.
+ <code class="command">CREATE OR REPLACE PROCEDURE</code> will either create a
+ new procedure, or replace an existing definition.
+ To be able to define a procedure, the user must have the
+ <code class="literal">USAGE</code> privilege on the language.
+ </p><p>
+ If a schema name is included, then the procedure is created in the
+ specified schema. Otherwise it is created in the current schema.
+ The name of the new procedure must not match any existing procedure or function
+ with the same input argument types in the same schema. However,
+ procedures and functions of different argument types can share a name (this is
+ called <em class="firstterm">overloading</em>).
+ </p><p>
+ To replace the current definition of an existing procedure, use
+ <code class="command">CREATE OR REPLACE PROCEDURE</code>. It is not possible
+ to change the name or argument types of a procedure this way (if you
+ tried, you would actually be creating a new, distinct procedure).
+ </p><p>
+ When <code class="command">CREATE OR REPLACE PROCEDURE</code> is used to replace an
+ existing procedure, the ownership and permissions of the procedure
+ do not change. All other procedure properties are assigned the
+ values specified or implied in the command. You must own the procedure
+ to replace it (this includes being a member of the owning role).
+ </p><p>
+ The user that creates the procedure becomes the owner of the procedure.
+ </p><p>
+ To be able to create a procedure, you must have <code class="literal">USAGE</code>
+ privilege on the argument types.
+ </p><p>
+ Refer to <a class="xref" href="xproc.html" title="38.4. User-Defined Procedures">Section 38.4</a> for further information on writing
+ procedures.
+ </p></div><div class="refsect1" id="id-1.9.3.76.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the procedure to create.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>. If omitted,
+ the default is <code class="literal">IN</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the procedure's arguments (optionally
+ schema-qualified), if any. The argument types can be base, composite,
+ or domain types, or can reference the type of a table column.
+ </p><p>
+ Depending on the implementation language it might also be allowed
+ to specify <span class="quote">“<span class="quote">pseudo-types</span>”</span> such as <code class="type">cstring</code>.
+ Pseudo-types indicate that the actual argument type is either
+ incompletely specified, or outside the set of ordinary SQL data types.
+ </p><p>
+ The type of a column is referenced by writing
+ <code class="literal"><em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em>%TYPE</code>.
+ Using this feature can sometimes help make a procedure independent of
+ changes to the definition of a table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>default_expr</code></em></span></dt><dd><p>
+ An expression to be used as default value if the parameter is
+ not specified. The expression has to be coercible to the
+ argument type of the parameter.
+ All input parameters following a
+ parameter with a default value must have default values as well.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language that the procedure is implemented in.
+ It can be <code class="literal">sql</code>, <code class="literal">c</code>,
+ <code class="literal">internal</code>, or the name of a user-defined
+ procedural language, e.g., <code class="literal">plpgsql</code>. The default is
+ <code class="literal">sql</code> if <em class="replaceable"><code>sql_body</code></em> is specified. Enclosing the
+ name in single quotes is deprecated and requires matching case.
+ </p></dd><dt><span class="term"><code class="literal">TRANSFORM { FOR TYPE <em class="replaceable"><code>type_name</code></em> } [, ... ] }</code></span></dt><dd><p>
+ Lists which transforms a call to the procedure should apply. Transforms
+ convert between SQL types and language-specific data types;
+ see <a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a>. Procedural language
+ implementations usually have hardcoded knowledge of the built-in types,
+ so those don't need to be listed here. If a procedural language
+ implementation does not know how to handle a type and no transform is
+ supplied, it will fall back to a default behavior for converting data
+ types, but this depends on the implementation.
+ </p></dd><dt><span class="term"><code class="literal">[<span class="optional">EXTERNAL</span>] SECURITY INVOKER</code><br /></span><span class="term"><code class="literal">[<span class="optional">EXTERNAL</span>] SECURITY DEFINER</code></span></dt><dd><p><code class="literal">SECURITY INVOKER</code> indicates that the procedure
+ is to be executed with the privileges of the user that calls it.
+ That is the default. <code class="literal">SECURITY DEFINER</code>
+ specifies that the procedure is to be executed with the
+ privileges of the user that owns it.
+ </p><p>
+ The key word <code class="literal">EXTERNAL</code> is allowed for SQL
+ conformance, but it is optional since, unlike in SQL, this feature
+ applies to all procedures not only external ones.
+ </p><p>
+ A <code class="literal">SECURITY DEFINER</code> procedure cannot execute
+ transaction control statements (for example, <code class="command">COMMIT</code>
+ and <code class="command">ROLLBACK</code>, depending on the language).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em><br /></span><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The <code class="literal">SET</code> clause causes the specified configuration
+ parameter to be set to the specified value when the procedure is
+ entered, and then restored to its prior value when the procedure exits.
+ <code class="literal">SET FROM CURRENT</code> saves the value of the parameter that
+ is current when <code class="command">CREATE PROCEDURE</code> is executed as the value
+ to be applied when the procedure is entered.
+ </p><p>
+ If a <code class="literal">SET</code> clause is attached to a procedure, then
+ the effects of a <code class="command">SET LOCAL</code> command executed inside the
+ procedure for the same variable are restricted to the procedure: the
+ configuration parameter's prior value is still restored at procedure exit.
+ However, an ordinary
+ <code class="command">SET</code> command (without <code class="literal">LOCAL</code>) overrides the
+ <code class="literal">SET</code> clause, much as it would do for a previous <code class="command">SET
+ LOCAL</code> command: the effects of such a command will persist after
+ procedure exit, unless the current transaction is rolled back.
+ </p><p>
+ If a <code class="literal">SET</code> clause is attached to a procedure, then
+ that procedure cannot execute transaction control statements (for
+ example, <code class="command">COMMIT</code> and <code class="command">ROLLBACK</code>,
+ depending on the language).
+ </p><p>
+ See <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> and
+ <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information about allowed parameter names and values.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>definition</code></em></span></dt><dd><p>
+ A string constant defining the procedure; the meaning depends on the
+ language. It can be an internal procedure name, the path to an
+ object file, an SQL command, or text in a procedural language.
+ </p><p>
+ It is often helpful to use dollar quoting (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) to write the procedure definition
+ string, rather than the normal single quote syntax. Without dollar
+ quoting, any single quotes or backslashes in the procedure definition must
+ be escaped by doubling them.
+ </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>obj_file</code></em>, <em class="replaceable"><code>link_symbol</code></em></code></span></dt><dd><p>
+ This form of the <code class="literal">AS</code> clause is used for
+ dynamically loadable C language procedures when the procedure name
+ in the C language source code is not the same as the name of
+ the SQL procedure. The string <em class="replaceable"><code>obj_file</code></em> is the name of the shared
+ library file containing the compiled C procedure, and is interpreted
+ as for the <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> command. The string
+ <em class="replaceable"><code>link_symbol</code></em> is the
+ procedure's link symbol, that is, the name of the procedure in the C
+ language source code. If the link symbol is omitted, it is assumed
+ to be the same as the name of the SQL procedure being defined.
+ </p><p>
+ When repeated <code class="command">CREATE PROCEDURE</code> calls refer to
+ the same object file, the file is only loaded once per session.
+ To unload and
+ reload the file (perhaps during development), start a new session.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sql_body</code></em></span></dt><dd><p>
+ The body of a <code class="literal">LANGUAGE SQL</code> procedure. This should
+ be a block
+</p><pre class="programlisting">
+BEGIN ATOMIC
+ <em class="replaceable"><code>statement</code></em>;
+ <em class="replaceable"><code>statement</code></em>;
+ ...
+ <em class="replaceable"><code>statement</code></em>;
+END
+</pre><p>
+ </p><p>
+ This is similar to writing the text of the procedure body as a string
+ constant (see <em class="replaceable"><code>definition</code></em> above), but there
+ are some differences: This form only works for <code class="literal">LANGUAGE
+ SQL</code>, the string constant form works for all languages. This
+ form is parsed at procedure definition time, the string constant form is
+ parsed at execution time; therefore this form cannot support
+ polymorphic argument types and other constructs that are not resolvable
+ at procedure definition time. This form tracks dependencies between the
+ procedure and objects used in the procedure body, so <code class="literal">DROP
+ ... CASCADE</code> will work correctly, whereas the form using
+ string literals may leave dangling procedures. Finally, this form is
+ more compatible with the SQL standard and other SQL implementations.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATEPROCEDURE-NOTES"><h2>Notes</h2><p>
+ See <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> for more details on function
+ creation that also apply to procedures.
+ </p><p>
+ Use <a class="xref" href="sql-call.html" title="CALL"><span class="refentrytitle">CALL</span></a> to execute a procedure.
+ </p></div><div class="refsect1" id="SQL-CREATEPROCEDURE-EXAMPLES"><h2>Examples</h2><p>
+</p><pre class="programlisting">
+CREATE PROCEDURE insert_data(a integer, b integer)
+LANGUAGE SQL
+AS $$
+INSERT INTO tbl VALUES (a);
+INSERT INTO tbl VALUES (b);
+$$;
+</pre><p>
+ or
+</p><pre class="programlisting">
+CREATE PROCEDURE insert_data(a integer, b integer)
+LANGUAGE SQL
+BEGIN ATOMIC
+ INSERT INTO tbl VALUES (a);
+ INSERT INTO tbl VALUES (b);
+END;
+</pre><p>
+ and call like this:
+</p><pre class="programlisting">
+CALL insert_data(1, 2);
+</pre></div><div class="refsect1" id="SQL-CREATEPROCEDURE-COMPAT"><h2>Compatibility</h2><p>
+ A <code class="command">CREATE PROCEDURE</code> command is defined in the SQL
+ standard. The <span class="productname">PostgreSQL</span> implementation can be
+ used in a compatible way but has many extensions. For details see also
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.76.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a>, <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a>, <a class="xref" href="sql-call.html" title="CALL"><span class="refentrytitle">CALL</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createpolicy.html" title="CREATE POLICY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createpublication.html" title="CREATE PUBLICATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE POLICY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE PUBLICATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createpublication.html b/doc/src/sgml/html/sql-createpublication.html
new file mode 100644
index 0000000..01650b4
--- /dev/null
+++ b/doc/src/sgml/html/sql-createpublication.html
@@ -0,0 +1,232 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE PUBLICATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createprocedure.html" title="CREATE PROCEDURE" /><link rel="next" href="sql-createrole.html" title="CREATE ROLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE PUBLICATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createprocedure.html" title="CREATE PROCEDURE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createrole.html" title="CREATE ROLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEPUBLICATION"><div class="titlepage"></div><a id="id-1.9.3.77.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE PUBLICATION</span></h2><p>CREATE PUBLICATION — define a new publication</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE PUBLICATION <em class="replaceable"><code>name</code></em>
+ [ FOR ALL TABLES
+ | FOR <em class="replaceable"><code>publication_object</code></em> [, ... ] ]
+ [ WITH ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+
+<span class="phrase">where <em class="replaceable"><code>publication_object</code></em> is one of:</span>
+
+ TABLE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] [ WHERE ( <em class="replaceable"><code>expression</code></em> ) ] [, ... ]
+ TABLES IN SCHEMA { <em class="replaceable"><code>schema_name</code></em> | CURRENT_SCHEMA } [, ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.77.5"><h2>Description</h2><p>
+ <code class="command">CREATE PUBLICATION</code> adds a new publication
+ into the current database. The publication name must be distinct from
+ the name of any existing publication in the current database.
+ </p><p>
+ A publication is essentially a group of tables whose data changes are
+ intended to be replicated through logical replication. See
+ <a class="xref" href="logical-replication-publication.html" title="31.1. Publication">Section 31.1</a> for details about how
+ publications fit into the logical replication setup.
+ </p></div><div class="refsect1" id="id-1.9.3.77.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the new publication.
+ </p></dd><dt><span class="term"><code class="literal">FOR TABLE</code></span></dt><dd><p>
+ Specifies a list of tables to add to the publication. If
+ <code class="literal">ONLY</code> is specified before the table name, only
+ that table is added to the publication. If <code class="literal">ONLY</code> is not
+ specified, the table and all its descendant tables (if any) are added.
+ Optionally, <code class="literal">*</code> can be specified after the table name to
+ explicitly indicate that descendant tables are included.
+ This does not apply to a partitioned table, however. The partitions of
+ a partitioned table are always implicitly considered part of the
+ publication, so they are never explicitly added to the publication.
+ </p><p>
+ If the optional <code class="literal">WHERE</code> clause is specified, it defines a
+ <em class="firstterm">row filter</em> expression. Rows for
+ which the <em class="replaceable"><code>expression</code></em>
+ evaluates to false or null will not be published. Note that parentheses
+ are required around the expression. It has no effect on
+ <code class="literal">TRUNCATE</code> commands.
+ </p><p>
+ When a column list is specified, only the named columns are replicated.
+ If no column list is specified, all columns of the table are replicated
+ through this publication, including any columns added later. It has no
+ effect on <code class="literal">TRUNCATE</code> commands. See
+ <a class="xref" href="logical-replication-col-lists.html" title="31.4. Column Lists">Section 31.4</a> for details about column
+ lists.
+ </p><p>
+ Only persistent base tables and partitioned tables can be part of a
+ publication. Temporary tables, unlogged tables, foreign tables,
+ materialized views, and regular views cannot be part of a publication.
+ </p><p>
+ Specifying a column list when the publication also publishes
+ <code class="literal">FOR TABLES IN SCHEMA</code> is not supported.
+ </p><p>
+ When a partitioned table is added to a publication, all of its existing
+ and future partitions are implicitly considered to be part of the
+ publication. So, even operations that are performed directly on a
+ partition are also published via publications that its ancestors are
+ part of.
+ </p></dd><dt><span class="term"><code class="literal">FOR ALL TABLES</code></span></dt><dd><p>
+ Marks the publication as one that replicates changes for all tables in
+ the database, including tables created in the future.
+ </p></dd><dt><span class="term"><code class="literal">FOR TABLES IN SCHEMA</code></span></dt><dd><p>
+ Marks the publication as one that replicates changes for all tables in
+ the specified list of schemas, including tables created in the future.
+ </p><p>
+ Specifying a schema when the publication also publishes a table with a
+ column list is not supported.
+ </p><p>
+ Only persistent base tables and partitioned tables present in the schema
+ will be included as part of the publication. Temporary tables, unlogged
+ tables, foreign tables, materialized views, and regular views from the
+ schema will not be part of the publication.
+ </p><p>
+ When a partitioned table is published via schema level publication, all
+ of its existing and future partitions are implicitly considered to be part of the
+ publication, regardless of whether they are from the publication schema or not.
+ So, even operations that are performed directly on a
+ partition are also published via publications that its ancestors are
+ part of.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>publication_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional parameters for a publication. The
+ following parameters are supported:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">publish</code> (<code class="type">string</code>)</span></dt><dd><p>
+ This parameter determines which DML operations will be published by
+ the new publication to the subscribers. The value is
+ comma-separated list of operations. The allowed operations are
+ <code class="literal">insert</code>, <code class="literal">update</code>,
+ <code class="literal">delete</code>, and <code class="literal">truncate</code>.
+ The default is to publish all actions,
+ and so the default value for this option is
+ <code class="literal">'insert, update, delete, truncate'</code>.
+ </p><p>
+ This parameter only affects DML operations. In particular, the initial
+ data synchronization (see <a class="xref" href="logical-replication-architecture.html#LOGICAL-REPLICATION-SNAPSHOT" title="31.7.1. Initial Snapshot">Section 31.7.1</a>)
+ for logical replication does not take this parameter into account when
+ copying existing table data.
+ </p></dd><dt><span class="term"><code class="literal">publish_via_partition_root</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This parameter determines whether changes in a partitioned table (or
+ on its partitions) contained in the publication will be published
+ using the identity and schema of the partitioned table rather than
+ that of the individual partitions that are actually changed; the
+ latter is the default. Enabling this allows the changes to be
+ replicated into a non-partitioned table or a partitioned table
+ consisting of a different set of partitions.
+ </p><p>
+ This parameter also affects how row filters and column lists are
+ chosen for partitions; see below for details.
+ </p><p>
+ If this is enabled, <code class="literal">TRUNCATE</code> operations performed
+ directly on partitions are not replicated.
+ </p></dd></dl></div></dd></dl></div></div><div class="refsect1" id="id-1.9.3.77.7"><h2>Notes</h2><p>
+ If <code class="literal">FOR TABLE</code>, <code class="literal">FOR ALL TABLES</code> or
+ <code class="literal">FOR TABLES IN SCHEMA</code> are not specified, then the
+ publication starts out with an empty set of tables. That is useful if
+ tables or schemas are to be added later.
+ </p><p>
+ The creation of a publication does not start replication. It only defines
+ a grouping and filtering logic for future subscribers.
+ </p><p>
+ To create a publication, the invoking user must have the
+ <code class="literal">CREATE</code> privilege for the current database.
+ (Of course, superusers bypass this check.)
+ </p><p>
+ To add a table to a publication, the invoking user must have ownership
+ rights on the table. The <code class="command">FOR ALL TABLES</code> and
+ <code class="command">FOR TABLES IN SCHEMA</code> clauses require the invoking
+ user to be a superuser.
+ </p><p>
+ The tables added to a publication that publishes <code class="command">UPDATE</code>
+ and/or <code class="command">DELETE</code> operations must have
+ <code class="literal">REPLICA IDENTITY</code> defined. Otherwise those operations will be
+ disallowed on those tables.
+ </p><p>
+ Any column list must include the <code class="literal">REPLICA IDENTITY</code> columns
+ in order for <code class="command">UPDATE</code> or <code class="command">DELETE</code>
+ operations to be published. There are no column list restrictions if the
+ publication publishes only <code class="command">INSERT</code> operations.
+ </p><p>
+ A row filter expression (i.e., the <code class="literal">WHERE</code> clause) must contain only
+ columns that are covered by the <code class="literal">REPLICA IDENTITY</code>, in
+ order for <code class="command">UPDATE</code> and <code class="command">DELETE</code> operations
+ to be published. For publication of <code class="command">INSERT</code> operations,
+ any column may be used in the <code class="literal">WHERE</code> expression. The
+ row filter allows simple expressions that don't have
+ user-defined functions, user-defined operators, user-defined types,
+ user-defined collations, non-immutable built-in functions, or references to
+ system columns.
+ </p><p>
+ The row filter on a table becomes redundant if
+ <code class="literal">FOR TABLES IN SCHEMA</code> is specified and the table
+ belongs to the referred schema.
+ </p><p>
+ For published partitioned tables, the row filter for each
+ partition is taken from the published partitioned table if the
+ publication parameter <code class="literal">publish_via_partition_root</code> is true,
+ or from the partition itself if it is false (the default).
+ See <a class="xref" href="logical-replication-row-filter.html" title="31.3. Row Filters">Section 31.3</a> for details about row
+ filters.
+ Similarly, for published partitioned tables, the column list for each
+ partition is taken from the published partitioned table if the
+ publication parameter <code class="literal">publish_via_partition_root</code> is true,
+ or from the partition itself if it is false.
+ </p><p>
+ For an <code class="command">INSERT ... ON CONFLICT</code> command, the publication will
+ publish the operation that results from the command. Depending
+ on the outcome, it may be published as either <code class="command">INSERT</code> or
+ <code class="command">UPDATE</code>, or it may not be published at all.
+ </p><p>
+ For a <code class="command">MERGE</code> command, the publication will publish an
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code>
+ for each row inserted, updated, or deleted.
+ </p><p>
+ <code class="command">ATTACH</code>ing a table into a partition tree whose root is
+ published using a publication with <code class="literal">publish_via_partition_root</code>
+ set to <code class="literal">true</code> does not result in the table's existing contents
+ being replicated.
+ </p><p>
+ <code class="command">COPY ... FROM</code> commands are published
+ as <code class="command">INSERT</code> operations.
+ </p><p>
+ <acronym class="acronym">DDL</acronym> operations are not published.
+ </p><p>
+ The <code class="literal">WHERE</code> clause expression is executed with the role used
+ for the replication connection.
+ </p></div><div class="refsect1" id="id-1.9.3.77.8"><h2>Examples</h2><p>
+ Create a publication that publishes all changes in two tables:
+</p><pre class="programlisting">
+CREATE PUBLICATION mypublication FOR TABLE users, departments;
+</pre><p>
+ </p><p>
+ Create a publication that publishes all changes from active departments:
+</p><pre class="programlisting">
+CREATE PUBLICATION active_departments FOR TABLE departments WHERE (active IS TRUE);
+</pre><p>
+ </p><p>
+ Create a publication that publishes all changes in all tables:
+</p><pre class="programlisting">
+CREATE PUBLICATION alltables FOR ALL TABLES;
+</pre><p>
+ </p><p>
+ Create a publication that only publishes <code class="command">INSERT</code>
+ operations in one table:
+</p><pre class="programlisting">
+CREATE PUBLICATION insert_only FOR TABLE mydata
+ WITH (publish = 'insert');
+</pre><p>
+ </p><p>
+ Create a publication that publishes all changes for tables
+ <code class="structname">users</code>, <code class="structname">departments</code> and
+ all changes for all the tables present in the schema
+ <code class="structname">production</code>:
+</p><pre class="programlisting">
+CREATE PUBLICATION production_publication FOR TABLE users, departments, TABLES IN SCHEMA production;
+</pre><p>
+ </p><p>
+ Create a publication that publishes all changes for all the tables present in
+ the schemas <code class="structname">marketing</code> and
+ <code class="structname">sales</code>:
+</p><pre class="programlisting">
+CREATE PUBLICATION sales_publication FOR TABLES IN SCHEMA marketing, sales;
+</pre><p>
+ Create a publication that publishes all changes for table <code class="structname">users</code>,
+ but replicates only columns <code class="structname">user_id</code> and
+ <code class="structname">firstname</code>:
+</p><pre class="programlisting">
+CREATE PUBLICATION users_filtered FOR TABLE users (user_id, firstname);
+</pre></div><div class="refsect1" id="id-1.9.3.77.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE PUBLICATION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.77.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterpublication.html" title="ALTER PUBLICATION"><span class="refentrytitle">ALTER PUBLICATION</span></a>, <a class="xref" href="sql-droppublication.html" title="DROP PUBLICATION"><span class="refentrytitle">DROP PUBLICATION</span></a>, <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>, <a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createprocedure.html" title="CREATE PROCEDURE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createrole.html" title="CREATE ROLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE PROCEDURE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE ROLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createrole.html b/doc/src/sgml/html/sql-createrole.html
new file mode 100644
index 0000000..bdabf68
--- /dev/null
+++ b/doc/src/sgml/html/sql-createrole.html
@@ -0,0 +1,269 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE ROLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createpublication.html" title="CREATE PUBLICATION" /><link rel="next" href="sql-createrule.html" title="CREATE RULE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE ROLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createpublication.html" title="CREATE PUBLICATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createrule.html" title="CREATE RULE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEROLE"><div class="titlepage"></div><a id="id-1.9.3.78.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE ROLE</span></h2><p>CREATE ROLE — define a new database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE ROLE <em class="replaceable"><code>name</code></em> [ [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ SUPERUSER | NOSUPERUSER
+ | CREATEDB | NOCREATEDB
+ | CREATEROLE | NOCREATEROLE
+ | INHERIT | NOINHERIT
+ | LOGIN | NOLOGIN
+ | REPLICATION | NOREPLICATION
+ | BYPASSRLS | NOBYPASSRLS
+ | CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ | [ ENCRYPTED ] PASSWORD '<em class="replaceable"><code>password</code></em>' | PASSWORD NULL
+ | VALID UNTIL '<em class="replaceable"><code>timestamp</code></em>'
+ | IN ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | IN GROUP <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ADMIN <em class="replaceable"><code>role_name</code></em> [, ...]
+ | USER <em class="replaceable"><code>role_name</code></em> [, ...]
+ | SYSID <em class="replaceable"><code>uid</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.78.5"><h2>Description</h2><p>
+ <code class="command">CREATE ROLE</code> adds a new role to a
+ <span class="productname">PostgreSQL</span> database cluster. A role is
+ an entity that can own database objects and have database privileges;
+ a role can be considered a <span class="quote">“<span class="quote">user</span>”</span>, a <span class="quote">“<span class="quote">group</span>”</span>, or both
+ depending on how it is used. Refer to
+ <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a> and <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> for information about managing
+ users and authentication. You must have <code class="literal">CREATEROLE</code>
+ privilege or be a database superuser to use this command.
+ </p><p>
+ Note that roles are defined at the database cluster
+ level, and so are valid in all databases in the cluster.
+ </p></div><div class="refsect1" id="id-1.9.3.78.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the new role.
+ </p></dd><dt><span class="term"><code class="literal">SUPERUSER</code><br /></span><span class="term"><code class="literal">NOSUPERUSER</code></span></dt><dd><p>
+ These clauses determine whether the new role is a <span class="quote">“<span class="quote">superuser</span>”</span>,
+ who can override all access restrictions within the database.
+ Superuser status is dangerous and should be used only when really
+ needed. You must yourself be a superuser to create a new superuser.
+ If not specified,
+ <code class="literal">NOSUPERUSER</code> is the default.
+ </p></dd><dt><span class="term"><code class="literal">CREATEDB</code><br /></span><span class="term"><code class="literal">NOCREATEDB</code></span></dt><dd><p>
+ These clauses define a role's ability to create databases. If
+ <code class="literal">CREATEDB</code> is specified, the role being
+ defined will be allowed to create new databases. Specifying
+ <code class="literal">NOCREATEDB</code> will deny a role the ability to
+ create databases. If not specified,
+ <code class="literal">NOCREATEDB</code> is the default.
+ </p></dd><dt><span class="term"><code class="literal">CREATEROLE</code><br /></span><span class="term"><code class="literal">NOCREATEROLE</code></span></dt><dd><p>
+ These clauses determine whether a role will be permitted to
+ create, alter, drop, comment on, change the security label for,
+ and grant or revoke membership in other roles.
+ See <a class="xref" href="role-attributes.html#ROLE-CREATION">role creation</a> for more details about what
+ capabilities are conferred by this privilege.
+ If not specified, <code class="literal">NOCREATEROLE</code> is the default.
+ </p></dd><dt><span class="term"><code class="literal">INHERIT</code><br /></span><span class="term"><code class="literal">NOINHERIT</code></span></dt><dd><p>
+ These clauses determine whether a role <span class="quote">“<span class="quote">inherits</span>”</span> the
+ privileges of roles it is a member of.
+ A role with the <code class="literal">INHERIT</code> attribute can automatically
+ use whatever database privileges have been granted to all roles
+ it is directly or indirectly a member of.
+ Without <code class="literal">INHERIT</code>, membership in another role
+ only grants the ability to <code class="command">SET ROLE</code> to that other role;
+ the privileges of the other role are only available after having
+ done so.
+ If not specified,
+ <code class="literal">INHERIT</code> is the default.
+ </p></dd><dt><span class="term"><code class="literal">LOGIN</code><br /></span><span class="term"><code class="literal">NOLOGIN</code></span></dt><dd><p>
+ These clauses determine whether a role is allowed to log in;
+ that is, whether the role can be given as the initial session
+ authorization name during client connection. A role having
+ the <code class="literal">LOGIN</code> attribute can be thought of as a user.
+ Roles without this attribute are useful for managing database
+ privileges, but are not users in the usual sense of the word.
+ If not specified,
+ <code class="literal">NOLOGIN</code> is the default, except when
+ <code class="command">CREATE ROLE</code> is invoked through its alternative spelling
+ <a class="link" href="sql-createuser.html" title="CREATE USER"><code class="command">CREATE USER</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">REPLICATION</code><br /></span><span class="term"><code class="literal">NOREPLICATION</code></span></dt><dd><p>
+ These clauses determine whether a role is a replication role. A role
+ must have this attribute (or be a superuser) in order to be able to
+ connect to the server in replication mode (physical or logical
+ replication) and in order to be able to create or drop replication
+ slots.
+ A role having the <code class="literal">REPLICATION</code> attribute is a very
+ highly privileged role, and should only be used on roles actually
+ used for replication. If not specified,
+ <code class="literal">NOREPLICATION</code> is the default.
+ You must be a superuser to create a new role having the
+ <code class="literal">REPLICATION</code> attribute.
+ </p></dd><dt><span class="term"><code class="literal">BYPASSRLS</code><br /></span><span class="term"><code class="literal">NOBYPASSRLS</code></span></dt><dd><p>
+ These clauses determine whether a role bypasses every row-level
+ security (RLS) policy. <code class="literal">NOBYPASSRLS</code> is the default.
+ You must be a superuser to create a new role having
+ the <code class="literal">BYPASSRLS</code> attribute.
+ </p><p>
+ Note that pg_dump will set <code class="literal">row_security</code> to
+ <code class="literal">OFF</code> by default, to ensure all contents of a table are
+ dumped out. If the user running pg_dump does not have appropriate
+ permissions, an error will be returned. However, superusers and the
+ owner of the table being dumped always bypass RLS.
+ </p></dd><dt><span class="term"><code class="literal">CONNECTION LIMIT</code> <em class="replaceable"><code>connlimit</code></em></span></dt><dd><p>
+ If role can log in, this specifies how many concurrent connections
+ the role can make. -1 (the default) means no limit. Note that only
+ normal connections are counted towards this limit. Neither prepared
+ transactions nor background worker connections are counted towards
+ this limit.
+ </p></dd><dt><span class="term">[ <code class="literal">ENCRYPTED</code> ] <code class="literal">PASSWORD</code> '<em class="replaceable"><code>password</code></em>'<br /></span><span class="term"><code class="literal">PASSWORD NULL</code></span></dt><dd><p>
+ Sets the role's password. (A password is only of use for
+ roles having the <code class="literal">LOGIN</code> attribute, but you
+ can nonetheless define one for roles without it.) If you do
+ not plan to use password authentication you can omit this
+ option. If no password is specified, the password will be set
+ to null and password authentication will always fail for that
+ user. A null password can optionally be written explicitly as
+ <code class="literal">PASSWORD NULL</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Specifying an empty string will also set the password to null,
+ but that was not the case before <span class="productname">PostgreSQL</span>
+ version 10. In earlier versions, an empty string could be used,
+ or not, depending on the authentication method and the exact
+ version, and libpq would refuse to use it in any case.
+ To avoid the ambiguity, specifying an empty string should be
+ avoided.
+ </p></div><p>
+ The password is always stored encrypted in the system catalogs. The
+ <code class="literal">ENCRYPTED</code> keyword has no effect, but is accepted for
+ backwards compatibility. The method of encryption is determined
+ by the configuration parameter <a class="xref" href="runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION">password_encryption</a>.
+ If the presented password string is already in MD5-encrypted or
+ SCRAM-encrypted format, then it is stored as-is regardless of
+ <code class="varname">password_encryption</code> (since the system cannot decrypt
+ the specified encrypted password string, to encrypt it in a
+ different format). This allows reloading of encrypted passwords
+ during dump/restore.
+ </p></dd><dt><span class="term"><code class="literal">VALID UNTIL</code> '<em class="replaceable"><code>timestamp</code></em>'</span></dt><dd><p>
+ The <code class="literal">VALID UNTIL</code> clause sets a date and
+ time after which the role's password is no longer valid. If
+ this clause is omitted the password will be valid for all time.
+ </p></dd><dt><span class="term"><code class="literal">IN ROLE</code> <em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The <code class="literal">IN ROLE</code> clause lists one or more existing
+ roles to which the new role will be immediately added as a new
+ member. (Note that there is no option to add the new role as an
+ administrator; use a separate <code class="command">GRANT</code> command to do that.)
+ </p></dd><dt><span class="term"><code class="literal">IN GROUP</code> <em class="replaceable"><code>role_name</code></em></span></dt><dd><p><code class="literal">IN GROUP</code> is an obsolete spelling of
+ <code class="literal">IN ROLE</code>.
+ </p></dd><dt><span class="term"><code class="literal">ROLE</code> <em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The <code class="literal">ROLE</code> clause lists one or more existing
+ roles which are automatically added as members of the new role.
+ (This in effect makes the new role a <span class="quote">“<span class="quote">group</span>”</span>.)
+ </p></dd><dt><span class="term"><code class="literal">ADMIN</code> <em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The <code class="literal">ADMIN</code> clause is like <code class="literal">ROLE</code>,
+ but the named roles are added to the new role <code class="literal">WITH ADMIN
+ OPTION</code>, giving them the right to grant membership in this role
+ to others.
+ </p></dd><dt><span class="term"><code class="literal">USER</code> <em class="replaceable"><code>role_name</code></em></span></dt><dd><p>
+ The <code class="literal">USER</code> clause is an obsolete spelling of
+ the <code class="literal">ROLE</code> clause.
+ </p></dd><dt><span class="term"><code class="literal">SYSID</code> <em class="replaceable"><code>uid</code></em></span></dt><dd><p>
+ The <code class="literal">SYSID</code> clause is ignored, but is accepted
+ for backwards compatibility.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.78.7"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a> to
+ change the attributes of a role, and <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>
+ to remove a role. All the attributes
+ specified by <code class="command">CREATE ROLE</code> can be modified by later
+ <code class="command">ALTER ROLE</code> commands.
+ </p><p>
+ The preferred way to add and remove members of roles that are being
+ used as groups is to use
+ <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and
+ <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a>.
+ </p><p>
+ The <code class="literal">VALID UNTIL</code> clause defines an expiration time for a
+ password only, not for the role per se. In
+ particular, the expiration time is not enforced when logging in using
+ a non-password-based authentication method.
+ </p><p>
+ The <code class="literal">INHERIT</code> attribute governs inheritance of grantable
+ privileges (that is, access privileges for database objects and role
+ memberships). It does not apply to the special role attributes set by
+ <code class="command">CREATE ROLE</code> and <code class="command">ALTER ROLE</code>. For example, being
+ a member of a role with <code class="literal">CREATEDB</code> privilege does not immediately
+ grant the ability to create databases, even if <code class="literal">INHERIT</code> is set;
+ it would be necessary to become that role via
+ <a class="link" href="sql-set-role.html" title="SET ROLE"><code class="command">SET ROLE</code></a> before
+ creating a database.
+ </p><p>
+ The <code class="literal">INHERIT</code> attribute is the default for reasons of backwards
+ compatibility: in prior releases of <span class="productname">PostgreSQL</span>,
+ users always had access to all privileges of groups they were members of.
+ However, <code class="literal">NOINHERIT</code> provides a closer match to the semantics
+ specified in the SQL standard.
+ </p><p>
+ Be careful with the <code class="literal">CREATEROLE</code> privilege. There is no concept of
+ inheritance for the privileges of a <code class="literal">CREATEROLE</code>-role. That
+ means that even if a role does not have a certain privilege but is allowed
+ to create other roles, it can easily create another role with different
+ privileges than its own (except for creating roles with superuser
+ privileges). For example, if the role <span class="quote">“<span class="quote">user</span>”</span> has the
+ <code class="literal">CREATEROLE</code> privilege but not the <code class="literal">CREATEDB</code> privilege,
+ nonetheless it can create a new role with the <code class="literal">CREATEDB</code>
+ privilege. Therefore, regard roles that have the <code class="literal">CREATEROLE</code>
+ privilege as almost-superuser-roles.
+ </p><p>
+ <span class="productname">PostgreSQL</span> includes a program <a class="xref" href="app-createuser.html" title="createuser"><span class="refentrytitle"><span class="application">createuser</span></span></a> that has
+ the same functionality as <code class="command">CREATE ROLE</code> (in fact,
+ it calls this command) but can be run from the command shell.
+ </p><p>
+ The <code class="literal">CONNECTION LIMIT</code> option is only enforced approximately;
+ if two new sessions start at about the same time when just one
+ connection <span class="quote">“<span class="quote">slot</span>”</span> remains for the role, it is possible that
+ both will fail. Also, the limit is never enforced for superusers.
+ </p><p>
+ Caution must be exercised when specifying an unencrypted password
+ with this command. The password will be transmitted to the server
+ in cleartext, and it might also be logged in the client's command
+ history or the server log. The command <a class="xref" href="app-createuser.html" title="createuser"><span class="refentrytitle"><span class="application">createuser</span></span></a>, however, transmits
+ the password encrypted. Also, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>
+ contains a command
+ <code class="command">\password</code> that can be used to safely change the
+ password later.
+ </p></div><div class="refsect1" id="id-1.9.3.78.8"><h2>Examples</h2><p>
+ Create a role that can log in, but don't give it a password:
+</p><pre class="programlisting">
+CREATE ROLE jonathan LOGIN;
+</pre><p>
+ </p><p>
+ Create a role with a password:
+</p><pre class="programlisting">
+CREATE USER davide WITH PASSWORD 'jw8s0F4';
+</pre><p>
+ (<code class="command">CREATE USER</code> is the same as <code class="command">CREATE ROLE</code> except
+ that it implies <code class="literal">LOGIN</code>.)
+ </p><p>
+ Create a role with a password that is valid until the end of 2004.
+ After one second has ticked in 2005, the password is no longer
+ valid.
+
+</p><pre class="programlisting">
+CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
+</pre><p>
+ </p><p>
+ Create a role that can create databases and manage roles:
+</p><pre class="programlisting">
+CREATE ROLE admin WITH CREATEDB CREATEROLE;
+</pre></div><div class="refsect1" id="id-1.9.3.78.9"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE ROLE</code> statement is in the SQL standard,
+ but the standard only requires the syntax
+</p><pre class="synopsis">
+CREATE ROLE <em class="replaceable"><code>name</code></em> [ WITH ADMIN <em class="replaceable"><code>role_name</code></em> ]
+</pre><p>
+ Multiple initial administrators, and all the other options of
+ <code class="command">CREATE ROLE</code>, are
+ <span class="productname">PostgreSQL</span> extensions.
+ </p><p>
+ The SQL standard defines the concepts of users and roles, but it
+ regards them as distinct concepts and leaves all commands defining
+ users to be specified by each database implementation. In
+ <span class="productname">PostgreSQL</span> we have chosen to unify
+ users and roles into a single kind of entity. Roles therefore
+ have many more optional attributes than they do in the standard.
+ </p><p>
+ The behavior specified by the SQL standard is most closely approximated
+ by giving users the <code class="literal">NOINHERIT</code> attribute, while roles are
+ given the <code class="literal">INHERIT</code> attribute.
+ </p></div><div class="refsect1" id="id-1.9.3.78.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set-role.html" title="SET ROLE"><span class="refentrytitle">SET ROLE</span></a>, <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>, <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a>, <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>, <a class="xref" href="app-createuser.html" title="createuser"><span class="refentrytitle"><span class="application">createuser</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createpublication.html" title="CREATE PUBLICATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createrule.html" title="CREATE RULE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE PUBLICATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE RULE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createrule.html b/doc/src/sgml/html/sql-createrule.html
new file mode 100644
index 0000000..e90a8f9
--- /dev/null
+++ b/doc/src/sgml/html/sql-createrule.html
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE RULE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createrole.html" title="CREATE ROLE" /><link rel="next" href="sql-createschema.html" title="CREATE SCHEMA" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE RULE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createrole.html" title="CREATE ROLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createschema.html" title="CREATE SCHEMA">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATERULE"><div class="titlepage"></div><a id="id-1.9.3.79.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE RULE</span></h2><p>CREATE RULE — define a new rewrite rule</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] RULE <em class="replaceable"><code>name</code></em> AS ON <em class="replaceable"><code>event</code></em>
+ TO <em class="replaceable"><code>table_name</code></em> [ WHERE <em class="replaceable"><code>condition</code></em> ]
+ DO [ ALSO | INSTEAD ] { NOTHING | <em class="replaceable"><code>command</code></em> | ( <em class="replaceable"><code>command</code></em> ; <em class="replaceable"><code>command</code></em> ... ) }
+
+<span class="phrase">where <em class="replaceable"><code>event</code></em> can be one of:</span>
+
+ SELECT | INSERT | UPDATE | DELETE
+</pre></div><div class="refsect1" id="id-1.9.3.79.5"><h2>Description</h2><p>
+ <code class="command">CREATE RULE</code> defines a new rule applying to a specified
+ table or view.
+ <code class="command">CREATE OR REPLACE RULE</code> will either create a
+ new rule, or replace an existing rule of the same name for the same
+ table.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> rule system allows one to
+ define an alternative action to be performed on insertions, updates,
+ or deletions in database tables. Roughly speaking, a rule causes
+ additional commands to be executed when a given command on a given
+ table is executed. Alternatively, an <code class="literal">INSTEAD</code>
+ rule can replace a given command by another, or cause a command
+ not to be executed at all. Rules are used to implement SQL
+ views as well. It is important to realize that a rule is really
+ a command transformation mechanism, or command macro. The
+ transformation happens before the execution of the command starts.
+ If you actually want an operation that fires independently for each
+ physical row, you probably want to use a trigger, not a rule.
+ More information about the rules system is in <a class="xref" href="rules.html" title="Chapter 41. The Rule System">Chapter 41</a>.
+ </p><p>
+ Presently, <code class="literal">ON SELECT</code> rules can only be attached
+ to views. (Attaching one to a table converts the table into a view.)
+ Such a rule must be named <code class="literal">"_RETURN"</code>,
+ must be an unconditional <code class="literal">INSTEAD</code> rule, and must have
+ an action that consists of a single <code class="command">SELECT</code> command.
+ This command defines the visible contents of the view. (The view
+ itself is basically a dummy table with no storage.) It's best to
+ regard such a rule as an implementation detail. While a view can be
+ redefined via <code class="literal">CREATE OR REPLACE RULE "_RETURN" AS
+ ...</code>, it's better style to use <code class="literal">CREATE OR REPLACE
+ VIEW</code>.
+ </p><p>
+ You can create the illusion of an updatable view by defining
+ <code class="literal">ON INSERT</code>, <code class="literal">ON UPDATE</code>, and
+ <code class="literal">ON DELETE</code> rules (or any subset of those that's
+ sufficient for your purposes) to replace update actions on the view
+ with appropriate updates on other tables. If you want to support
+ <code class="command">INSERT RETURNING</code> and so on, then be sure to put a suitable
+ <code class="literal">RETURNING</code> clause into each of these rules.
+ </p><p>
+ There is a catch if you try to use conditional rules for complex view
+ updates: there <span class="emphasis"><em>must</em></span> be an unconditional
+ <code class="literal">INSTEAD</code> rule for each action you wish to allow
+ on the view. If the rule is conditional, or is not
+ <code class="literal">INSTEAD</code>, then the system will still reject
+ attempts to perform the update action, because it thinks it might
+ end up trying to perform the action on the dummy table of the view
+ in some cases. If you want to handle all the useful cases in
+ conditional rules, add an unconditional <code class="literal">DO
+ INSTEAD NOTHING</code> rule to ensure that the system
+ understands it will never be called on to update the dummy table.
+ Then make the conditional rules non-<code class="literal">INSTEAD</code>; in
+ the cases where they are applied, they add to the default
+ <code class="literal">INSTEAD NOTHING</code> action. (This method does not
+ currently work to support <code class="literal">RETURNING</code> queries, however.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A view that is simple enough to be automatically updatable (see <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a>) does not require a user-created rule in
+ order to be updatable. While you can create an explicit rule anyway,
+ the automatic update transformation will generally outperform an
+ explicit rule.
+ </p><p>
+ Another alternative worth considering is to use <code class="literal">INSTEAD OF</code>
+ triggers (see <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>) in place of rules.
+ </p></div></div><div class="refsect1" id="id-1.9.3.79.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a rule to create. This must be distinct from the
+ name of any other rule for the same table. Multiple rules on
+ the same table and same event type are applied in alphabetical
+ name order.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>event</code></em></span></dt><dd><p>
+ The event is one of <code class="literal">SELECT</code>,
+ <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or
+ <code class="literal">DELETE</code>. Note that an
+ <code class="command">INSERT</code> containing an <code class="literal">ON
+ CONFLICT</code> clause cannot be used on tables that have
+ either <code class="literal">INSERT</code> or <code class="literal">UPDATE</code>
+ rules. Consider using an updatable view instead.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table or view the
+ rule applies to.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ Any <acronym class="acronym">SQL</acronym> conditional expression (returning
+ <code class="type">boolean</code>). The condition expression cannot refer
+ to any tables except <code class="literal">NEW</code> and <code class="literal">OLD</code>, and
+ cannot contain aggregate functions.
+ </p></dd><dt><span class="term"><code class="option">INSTEAD</code></span></dt><dd><p><code class="literal">INSTEAD</code> indicates that the commands should be
+ executed <span class="emphasis"><em>instead of</em></span> the original command.
+ </p></dd><dt><span class="term"><code class="option">ALSO</code></span></dt><dd><p><code class="literal">ALSO</code> indicates that the commands should be
+ executed <span class="emphasis"><em>in addition to</em></span> the original
+ command.
+ </p><p>
+ If neither <code class="literal">ALSO</code> nor
+ <code class="literal">INSTEAD</code> is specified, <code class="literal">ALSO</code>
+ is the default.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>command</code></em></span></dt><dd><p>
+ The command or commands that make up the rule action. Valid
+ commands are <code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, or <code class="command">NOTIFY</code>.
+ </p></dd></dl></div><p>
+ Within <em class="replaceable"><code>condition</code></em> and
+ <em class="replaceable"><code>command</code></em>, the special
+ table names <code class="literal">NEW</code> and <code class="literal">OLD</code> can
+ be used to refer to values in the referenced table.
+ <code class="literal">NEW</code> is valid in <code class="literal">ON INSERT</code> and
+ <code class="literal">ON UPDATE</code> rules to refer to the new row being
+ inserted or updated. <code class="literal">OLD</code> is valid in
+ <code class="literal">ON UPDATE</code> and <code class="literal">ON DELETE</code> rules
+ to refer to the existing row being updated or deleted.
+ </p></div><div class="refsect1" id="id-1.9.3.79.7"><h2>Notes</h2><p>
+ You must be the owner of a table to create or change rules for it.
+ </p><p>
+ In a rule for <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or
+ <code class="literal">DELETE</code> on a view, you can add a <code class="literal">RETURNING</code>
+ clause that emits the view's columns. This clause will be used to compute
+ the outputs if the rule is triggered by an <code class="command">INSERT RETURNING</code>,
+ <code class="command">UPDATE RETURNING</code>, or <code class="command">DELETE RETURNING</code> command
+ respectively. When the rule is triggered by a command without
+ <code class="literal">RETURNING</code>, the rule's <code class="literal">RETURNING</code> clause will be
+ ignored. The current implementation allows only unconditional
+ <code class="literal">INSTEAD</code> rules to contain <code class="literal">RETURNING</code>; furthermore
+ there can be at most one <code class="literal">RETURNING</code> clause among all the rules
+ for the same event. (This ensures that there is only one candidate
+ <code class="literal">RETURNING</code> clause to be used to compute the results.)
+ <code class="literal">RETURNING</code> queries on the view will be rejected if
+ there is no <code class="literal">RETURNING</code> clause in any available rule.
+ </p><p>
+ It is very important to take care to avoid circular rules. For
+ example, though each of the following two rule definitions are
+ accepted by <span class="productname">PostgreSQL</span>, the
+ <code class="command">SELECT</code> command would cause
+ <span class="productname">PostgreSQL</span> to report an error because
+ of recursive expansion of a rule:
+
+</p><pre class="programlisting">
+CREATE RULE "_RETURN" AS
+ ON SELECT TO t1
+ DO INSTEAD
+ SELECT * FROM t2;
+
+CREATE RULE "_RETURN" AS
+ ON SELECT TO t2
+ DO INSTEAD
+ SELECT * FROM t1;
+
+SELECT * FROM t1;
+</pre><p>
+ </p><p>
+ Presently, if a rule action contains a <code class="command">NOTIFY</code>
+ command, the <code class="command">NOTIFY</code> command will be executed
+ unconditionally, that is, the <code class="command">NOTIFY</code> will be
+ issued even if there are not any rows that the rule should apply
+ to. For example, in:
+</p><pre class="programlisting">
+CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable;
+
+UPDATE mytable SET name = 'foo' WHERE id = 42;
+</pre><p>
+ one <code class="command">NOTIFY</code> event will be sent during the
+ <code class="command">UPDATE</code>, whether or not there are any rows that
+ match the condition <code class="literal">id = 42</code>. This is an
+ implementation restriction that might be fixed in future releases.
+ </p></div><div class="refsect1" id="id-1.9.3.79.8"><h2>Compatibility</h2><p>
+ <code class="command">CREATE RULE</code> is a
+ <span class="productname">PostgreSQL</span> language extension, as is the
+ entire query rewrite system.
+ </p></div><div class="refsect1" id="id-1.9.3.79.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterrule.html" title="ALTER RULE"><span class="refentrytitle">ALTER RULE</span></a>, <a class="xref" href="sql-droprule.html" title="DROP RULE"><span class="refentrytitle">DROP RULE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createrole.html" title="CREATE ROLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createschema.html" title="CREATE SCHEMA">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE ROLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE SCHEMA</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createschema.html b/doc/src/sgml/html/sql-createschema.html
new file mode 100644
index 0000000..70be55b
--- /dev/null
+++ b/doc/src/sgml/html/sql-createschema.html
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE SCHEMA</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createrule.html" title="CREATE RULE" /><link rel="next" href="sql-createsequence.html" title="CREATE SEQUENCE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE SCHEMA</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createrule.html" title="CREATE RULE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createsequence.html" title="CREATE SEQUENCE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATESCHEMA"><div class="titlepage"></div><a id="id-1.9.3.80.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE SCHEMA</span></h2><p>CREATE SCHEMA — define a new schema</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE SCHEMA <em class="replaceable"><code>schema_name</code></em> [ AUTHORIZATION <em class="replaceable"><code>role_specification</code></em> ] [ <em class="replaceable"><code>schema_element</code></em> [ ... ] ]
+CREATE SCHEMA AUTHORIZATION <em class="replaceable"><code>role_specification</code></em> [ <em class="replaceable"><code>schema_element</code></em> [ ... ] ]
+CREATE SCHEMA IF NOT EXISTS <em class="replaceable"><code>schema_name</code></em> [ AUTHORIZATION <em class="replaceable"><code>role_specification</code></em> ]
+CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <em class="replaceable"><code>role_specification</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ <em class="replaceable"><code>user_name</code></em>
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+</pre></div><div class="refsect1" id="id-1.9.3.80.5"><h2>Description</h2><p>
+ <code class="command">CREATE SCHEMA</code> enters a new schema
+ into the current database.
+ The schema name must be distinct from the name of any existing schema
+ in the current database.
+ </p><p>
+ A schema is essentially a namespace:
+ it contains named objects (tables, data types, functions, and operators)
+ whose names can duplicate those of other objects existing in other
+ schemas. Named objects are accessed either by <span class="quote">“<span class="quote">qualifying</span>”</span>
+ their names with the schema name as a prefix, or by setting a search
+ path that includes the desired schema(s). A <code class="literal">CREATE</code> command
+ specifying an unqualified object name creates the object
+ in the current schema (the one at the front of the search path,
+ which can be determined with the function <code class="function">current_schema</code>).
+ </p><p>
+ Optionally, <code class="command">CREATE SCHEMA</code> can include subcommands
+ to create objects within the new schema. The subcommands are treated
+ essentially the same as separate commands issued after creating the
+ schema, except that if the <code class="literal">AUTHORIZATION</code> clause is used,
+ all the created objects will be owned by that user.
+ </p></div><div class="refsect1" id="id-1.9.3.80.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>schema_name</code></em></span></dt><dd><p>
+ The name of a schema to be created. If this is omitted, the
+ <em class="replaceable"><code>user_name</code></em>
+ is used as the schema name. The name cannot
+ begin with <code class="literal">pg_</code>, as such names
+ are reserved for system schemas.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ The role name of the user who will own the new schema. If omitted,
+ defaults to the user executing the command. To create a schema
+ owned by another role, you must be a direct or indirect member of
+ that role, or be a superuser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>schema_element</code></em></span></dt><dd><p>
+ An SQL statement defining an object to be created within the
+ schema. Currently, only <code class="command">CREATE
+ TABLE</code>, <code class="command">CREATE VIEW</code>, <code class="command">CREATE
+ INDEX</code>, <code class="command">CREATE SEQUENCE</code>, <code class="command">CREATE
+ TRIGGER</code> and <code class="command">GRANT</code> are accepted as clauses
+ within <code class="command">CREATE SCHEMA</code>. Other kinds of objects may
+ be created in separate commands after the schema is created.
+ </p></dd><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do nothing (except issuing a notice) if a schema with the same name
+ already exists. <em class="replaceable"><code>schema_element</code></em>
+ subcommands cannot be included when this option is used.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.80.7"><h2>Notes</h2><p>
+ To create a schema, the invoking user must have the
+ <code class="literal">CREATE</code> privilege for the current database.
+ (Of course, superusers bypass this check.)
+ </p></div><div class="refsect1" id="id-1.9.3.80.8"><h2>Examples</h2><p>
+ Create a schema:
+</p><pre class="programlisting">
+CREATE SCHEMA myschema;
+</pre><p>
+ </p><p>
+ Create a schema for user <code class="literal">joe</code>; the schema will also be
+ named <code class="literal">joe</code>:
+</p><pre class="programlisting">
+CREATE SCHEMA AUTHORIZATION joe;
+</pre><p>
+ </p><p>
+ Create a schema named <code class="literal">test</code> that will be owned by user
+ <code class="literal">joe</code>, unless there already is a schema named <code class="literal">test</code>.
+ (It does not matter whether <code class="literal">joe</code> owns the pre-existing schema.)
+</p><pre class="programlisting">
+CREATE SCHEMA IF NOT EXISTS test AUTHORIZATION joe;
+</pre><p>
+ </p><p>
+ Create a schema and create a table and view within it:
+</p><pre class="programlisting">
+CREATE SCHEMA hollywood
+ CREATE TABLE films (title text, release date, awards text[])
+ CREATE VIEW winners AS
+ SELECT title, release FROM films WHERE awards IS NOT NULL;
+</pre><p>
+ Notice that the individual subcommands do not end with semicolons.
+ </p><p>
+ The following is an equivalent way of accomplishing the same result:
+</p><pre class="programlisting">
+CREATE SCHEMA hollywood;
+CREATE TABLE hollywood.films (title text, release date, awards text[]);
+CREATE VIEW hollywood.winners AS
+ SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
+</pre></div><div class="refsect1" id="id-1.9.3.80.9"><h2>Compatibility</h2><p>
+ The SQL standard allows a <code class="literal">DEFAULT CHARACTER SET</code> clause
+ in <code class="command">CREATE SCHEMA</code>, as well as more subcommand
+ types than are presently accepted by
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ The SQL standard specifies that the subcommands in <code class="command">CREATE
+ SCHEMA</code> can appear in any order. The present
+ <span class="productname">PostgreSQL</span> implementation does not
+ handle all cases of forward references in subcommands; it might
+ sometimes be necessary to reorder the subcommands in order to avoid
+ forward references.
+ </p><p>
+ According to the SQL standard, the owner of a schema always owns
+ all objects within it. <span class="productname">PostgreSQL</span>
+ allows schemas to contain objects owned by users other than the
+ schema owner. This can happen only if the schema owner grants the
+ <code class="literal">CREATE</code> privilege on their schema to someone else, or a
+ superuser chooses to create objects in it.
+ </p><p>
+ The <code class="literal">IF NOT EXISTS</code> option is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.80.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterschema.html" title="ALTER SCHEMA"><span class="refentrytitle">ALTER SCHEMA</span></a>, <a class="xref" href="sql-dropschema.html" title="DROP SCHEMA"><span class="refentrytitle">DROP SCHEMA</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createrule.html" title="CREATE RULE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createsequence.html" title="CREATE SEQUENCE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE RULE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE SEQUENCE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createsequence.html b/doc/src/sgml/html/sql-createsequence.html
new file mode 100644
index 0000000..5205ed0
--- /dev/null
+++ b/doc/src/sgml/html/sql-createsequence.html
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE SEQUENCE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createschema.html" title="CREATE SCHEMA" /><link rel="next" href="sql-createserver.html" title="CREATE SERVER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE SEQUENCE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createschema.html" title="CREATE SCHEMA">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createserver.html" title="CREATE SERVER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATESEQUENCE"><div class="titlepage"></div><a id="id-1.9.3.81.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE SEQUENCE</span></h2><p>CREATE SEQUENCE — define a new sequence generator</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] <em class="replaceable"><code>name</code></em>
+ [ AS <em class="replaceable"><code>data_type</code></em> ]
+ [ INCREMENT [ BY ] <em class="replaceable"><code>increment</code></em> ]
+ [ MINVALUE <em class="replaceable"><code>minvalue</code></em> | NO MINVALUE ] [ MAXVALUE <em class="replaceable"><code>maxvalue</code></em> | NO MAXVALUE ]
+ [ START [ WITH ] <em class="replaceable"><code>start</code></em> ] [ CACHE <em class="replaceable"><code>cache</code></em> ] [ [ NO ] CYCLE ]
+ [ OWNED BY { <em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em> | NONE } ]
+</pre></div><div class="refsect1" id="id-1.9.3.81.5"><h2>Description</h2><p>
+ <code class="command">CREATE SEQUENCE</code> creates a new sequence number
+ generator. This involves creating and initializing a new special
+ single-row table with the name <em class="replaceable"><code>name</code></em>. The generator will be
+ owned by the user issuing the command.
+ </p><p>
+ If a schema name is given then the sequence is created in the
+ specified schema. Otherwise it is created in the current schema.
+ Temporary sequences exist in a special schema, so a schema name cannot be
+ given when creating a temporary sequence.
+ The sequence name must be distinct from the name of any other relation
+ (table, sequence, index, view, materialized view, or foreign table) in
+ the same schema.
+ </p><p>
+ After a sequence is created, you use the functions
+ <code class="function">nextval</code>,
+ <code class="function">currval</code>, and
+ <code class="function">setval</code>
+ to operate on the sequence. These functions are documented in
+ <a class="xref" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Section 9.17</a>.
+ </p><p>
+ Although you cannot update a sequence directly, you can use a query like:
+
+</p><pre class="programlisting">
+SELECT * FROM <em class="replaceable"><code>name</code></em>;
+</pre><p>
+
+ to examine the parameters and current state of a sequence. In particular,
+ the <code class="literal">last_value</code> field of the sequence shows the last value
+ allocated by any session. (Of course, this value might be obsolete
+ by the time it's printed, if other sessions are actively doing
+ <code class="function">nextval</code> calls.)
+ </p></div><div class="refsect1" id="id-1.9.3.81.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ If specified, the sequence object is created only for this
+ session, and is automatically dropped on session exit. Existing
+ permanent sequences with the same name are not visible (in this
+ session) while the temporary sequence exists, unless they are
+ referenced with schema-qualified names.
+ </p></dd><dt><span class="term"><code class="literal">UNLOGGED</code></span></dt><dd><p>
+ If specified, the sequence is created as an unlogged sequence. Changes
+ to unlogged sequences are not written to the write-ahead log. They are
+ not crash-safe: an unlogged sequence is automatically reset to its
+ initial state after a crash or unclean shutdown. Unlogged sequences are
+ also not replicated to standby servers.
+ </p><p>
+ Unlike unlogged tables, unlogged sequences do not offer a significant
+ performance advantage. This option is mainly intended for sequences
+ associated with unlogged tables via identity columns or serial columns.
+ In those cases, it usually wouldn't make sense to have the sequence
+ WAL-logged and replicated but not its associated table.
+ </p></dd><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a relation with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing relation is anything like the sequence that would have
+ been created — it might not even be a sequence.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the sequence to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The optional
+ clause <code class="literal">AS <em class="replaceable"><code>data_type</code></em></code>
+ specifies the data type of the sequence. Valid types are
+ <code class="literal">smallint</code>, <code class="literal">integer</code>,
+ and <code class="literal">bigint</code>. <code class="literal">bigint</code> is the
+ default. The data type determines the default minimum and maximum
+ values of the sequence.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>increment</code></em></span></dt><dd><p>
+ The optional clause <code class="literal">INCREMENT BY <em class="replaceable"><code>increment</code></em></code> specifies
+ which value is added to the current sequence value to create a
+ new value. A positive value will make an ascending sequence, a
+ negative one a descending sequence. The default value is 1.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>minvalue</code></em><br /></span><span class="term"><code class="literal">NO MINVALUE</code></span></dt><dd><p>
+ The optional clause <code class="literal">MINVALUE <em class="replaceable"><code>minvalue</code></em></code> determines
+ the minimum value a sequence can generate. If this clause is not
+ supplied or <code class="option">NO MINVALUE</code> is specified, then
+ defaults will be used. The default for an ascending sequence is 1. The
+ default for a descending sequence is the minimum value of the data type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>maxvalue</code></em><br /></span><span class="term"><code class="literal">NO MAXVALUE</code></span></dt><dd><p>
+ The optional clause <code class="literal">MAXVALUE <em class="replaceable"><code>maxvalue</code></em></code> determines
+ the maximum value for the sequence. If this clause is not
+ supplied or <code class="option">NO MAXVALUE</code> is specified, then
+ default values will be used. The default for an ascending sequence is
+ the maximum value of the data type. The default for a descending
+ sequence is -1.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>start</code></em></span></dt><dd><p>
+ The optional clause <code class="literal">START WITH <em class="replaceable"><code>start</code></em> </code> allows the
+ sequence to begin anywhere. The default starting value is
+ <em class="replaceable"><code>minvalue</code></em> for
+ ascending sequences and <em class="replaceable"><code>maxvalue</code></em> for descending ones.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cache</code></em></span></dt><dd><p>
+ The optional clause <code class="literal">CACHE <em class="replaceable"><code>cache</code></em></code> specifies how
+ many sequence numbers are to be preallocated and stored in
+ memory for faster access. The minimum value is 1 (only one value
+ can be generated at a time, i.e., no cache), and this is also the
+ default.
+ </p></dd><dt><span class="term"><code class="literal">CYCLE</code><br /></span><span class="term"><code class="literal">NO CYCLE</code></span></dt><dd><p>
+ The <code class="literal">CYCLE</code> option allows the sequence to wrap
+ around when the <em class="replaceable"><code>maxvalue</code></em> or <em class="replaceable"><code>minvalue</code></em> has been reached by an
+ ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the <em class="replaceable"><code>minvalue</code></em> or <em class="replaceable"><code>maxvalue</code></em>, respectively.
+ </p><p>
+ If <code class="literal">NO CYCLE</code> is specified, any calls to
+ <code class="function">nextval</code> after the sequence has reached its
+ maximum value will return an error. If neither
+ <code class="literal">CYCLE</code> or <code class="literal">NO CYCLE</code> are
+ specified, <code class="literal">NO CYCLE</code> is the default.
+ </p></dd><dt><span class="term"><code class="literal">OWNED BY</code> <em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em><br /></span><span class="term"><code class="literal">OWNED BY NONE</code></span></dt><dd><p>
+ The <code class="literal">OWNED BY</code> option causes the sequence to be
+ associated with a specific table column, such that if that column
+ (or its whole table) is dropped, the sequence will be automatically
+ dropped as well. The specified table must have the same owner and be in
+ the same schema as the sequence.
+ <code class="literal">OWNED BY NONE</code>, the default, specifies that there
+ is no such association.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.81.7"><h2>Notes</h2><p>
+ Use <code class="command">DROP SEQUENCE</code> to remove a sequence.
+ </p><p>
+ Sequences are based on <code class="type">bigint</code> arithmetic, so the range
+ cannot exceed the range of an eight-byte integer
+ (-9223372036854775808 to 9223372036854775807).
+ </p><p>
+ Because <code class="function">nextval</code> and <code class="function">setval</code> calls are never
+ rolled back, sequence objects cannot be used if <span class="quote">“<span class="quote">gapless</span>”</span>
+ assignment of sequence numbers is needed. It is possible to build
+ gapless assignment by using exclusive locking of a table containing a
+ counter; but this solution is much more expensive than sequence
+ objects, especially if many transactions need sequence numbers
+ concurrently.
+ </p><p>
+ Unexpected results might be obtained if a <em class="replaceable"><code>cache</code></em> setting greater than one is
+ used for a sequence object that will be used concurrently by
+ multiple sessions. Each session will allocate and cache successive
+ sequence values during one access to the sequence object and
+ increase the sequence object's <code class="literal">last_value</code> accordingly.
+ Then, the next <em class="replaceable"><code>cache</code></em>-1
+ uses of <code class="function">nextval</code> within that session simply return the
+ preallocated values without touching the sequence object. So, any
+ numbers allocated but not used within a session will be lost when
+ that session ends, resulting in <span class="quote">“<span class="quote">holes</span>”</span> in the
+ sequence.
+ </p><p>
+ Furthermore, although multiple sessions are guaranteed to allocate
+ distinct sequence values, the values might be generated out of
+ sequence when all the sessions are considered. For example, with
+ a <em class="replaceable"><code>cache</code></em> setting of 10,
+ session A might reserve values 1..10 and return
+ <code class="function">nextval</code>=1, then session B might reserve values
+ 11..20 and return <code class="function">nextval</code>=11 before session A
+ has generated <code class="function">nextval</code>=2. Thus, with a
+ <em class="replaceable"><code>cache</code></em> setting of one
+ it is safe to assume that <code class="function">nextval</code> values are generated
+ sequentially; with a <em class="replaceable"><code>cache</code></em> setting greater than one you
+ should only assume that the <code class="function">nextval</code> values are all
+ distinct, not that they are generated purely sequentially. Also,
+ <code class="literal">last_value</code> will reflect the latest value reserved by
+ any session, whether or not it has yet been returned by
+ <code class="function">nextval</code>.
+ </p><p>
+ Another consideration is that a <code class="function">setval</code> executed on
+ such a sequence will not be noticed by other sessions until they
+ have used up any preallocated values they have cached.
+ </p></div><div class="refsect1" id="id-1.9.3.81.8"><h2>Examples</h2><p>
+ Create an ascending sequence called <code class="literal">serial</code>, starting at 101:
+</p><pre class="programlisting">
+CREATE SEQUENCE serial START 101;
+</pre><p>
+ </p><p>
+ Select the next number from this sequence:
+</p><pre class="programlisting">
+SELECT nextval('serial');
+
+ nextval
+---------
+ 101
+</pre><p>
+ </p><p>
+ Select the next number from this sequence:
+</p><pre class="programlisting">
+SELECT nextval('serial');
+
+ nextval
+---------
+ 102
+</pre><p>
+ </p><p>
+ Use this sequence in an <code class="command">INSERT</code> command:
+</p><pre class="programlisting">
+INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
+</pre><p>
+ </p><p>
+ Update the sequence value after a <code class="command">COPY FROM</code>:
+</p><pre class="programlisting">
+BEGIN;
+COPY distributors FROM 'input_file';
+SELECT setval('serial', max(id)) FROM distributors;
+END;
+</pre></div><div class="refsect1" id="id-1.9.3.81.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE SEQUENCE</code> conforms to the <acronym class="acronym">SQL</acronym>
+ standard, with the following exceptions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Obtaining the next value is done using the <code class="function">nextval()</code>
+ function instead of the standard's <code class="command">NEXT VALUE FOR</code>
+ expression.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">OWNED BY</code> clause is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></li></ul></div></div><div class="refsect1" id="id-1.9.3.81.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altersequence.html" title="ALTER SEQUENCE"><span class="refentrytitle">ALTER SEQUENCE</span></a>, <a class="xref" href="sql-dropsequence.html" title="DROP SEQUENCE"><span class="refentrytitle">DROP SEQUENCE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createschema.html" title="CREATE SCHEMA">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createserver.html" title="CREATE SERVER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE SCHEMA </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE SERVER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createserver.html b/doc/src/sgml/html/sql-createserver.html
new file mode 100644
index 0000000..b92f23d
--- /dev/null
+++ b/doc/src/sgml/html/sql-createserver.html
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE SERVER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createsequence.html" title="CREATE SEQUENCE" /><link rel="next" href="sql-createstatistics.html" title="CREATE STATISTICS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE SERVER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createsequence.html" title="CREATE SEQUENCE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createstatistics.html" title="CREATE STATISTICS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATESERVER"><div class="titlepage"></div><a id="id-1.9.3.82.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE SERVER</span></h2><p>CREATE SERVER — define a new foreign server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE SERVER [ IF NOT EXISTS ] <em class="replaceable"><code>server_name</code></em> [ TYPE '<em class="replaceable"><code>server_type</code></em>' ] [ VERSION '<em class="replaceable"><code>server_version</code></em>' ]
+ FOREIGN DATA WRAPPER <em class="replaceable"><code>fdw_name</code></em>
+ [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.82.5"><h2>Description</h2><p>
+ <code class="command">CREATE SERVER</code> defines a new foreign server. The
+ user who defines the server becomes its owner.
+ </p><p>
+ A foreign server typically encapsulates connection information that
+ a foreign-data wrapper uses to access an external data resource.
+ Additional user-specific connection information may be specified by
+ means of user mappings.
+ </p><p>
+ The server name must be unique within the database.
+ </p><p>
+ Creating a server requires <code class="literal">USAGE</code> privilege on the
+ foreign-data wrapper being used.
+ </p></div><div class="refsect1" id="id-1.9.3.82.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a server with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing server is anything like the one that would have been
+ created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ The name of the foreign server to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_type</code></em></span></dt><dd><p>
+ Optional server type, potentially useful to foreign-data wrappers.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_version</code></em></span></dt><dd><p>
+ Optional server version, potentially useful to foreign-data wrappers.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>fdw_name</code></em></span></dt><dd><p>
+ The name of the foreign-data wrapper that manages the server.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] )</code></span></dt><dd><p>
+ This clause specifies the options for the server. The options
+ typically define the connection details of the server, but the
+ actual names and values are dependent on the server's
+ foreign-data wrapper.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.82.7"><h2>Notes</h2><p>
+ When using the <a class="xref" href="dblink.html" title="F.12. dblink">dblink</a> module,
+ a foreign server's name can be used
+ as an argument of the <a class="xref" href="contrib-dblink-connect.html" title="dblink_connect"><span class="refentrytitle">dblink_connect</span></a>
+ function to indicate the connection parameters. It is necessary to have
+ the <code class="literal">USAGE</code> privilege on the foreign server to be
+ able to use it in this way.
+ </p><p>
+ If the foreign server supports sort pushdown, it is necessary for it
+ to have the same sort ordering as the local server.
+ </p></div><div class="refsect1" id="id-1.9.3.82.8"><h2>Examples</h2><p>
+ Create a server <code class="literal">myserver</code> that uses the
+ foreign-data wrapper <code class="literal">postgres_fdw</code>:
+</p><pre class="programlisting">
+CREATE SERVER myserver FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host 'foo', dbname 'foodb', port '5432');
+</pre><p>
+ See <a class="xref" href="postgres-fdw.html" title="F.38. postgres_fdw">postgres_fdw</a> for more details.
+ </p></div><div class="refsect1" id="id-1.9.3.82.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE SERVER</code> conforms to ISO/IEC 9075-9 (SQL/MED).
+ </p></div><div class="refsect1" id="id-1.9.3.82.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterserver.html" title="ALTER SERVER"><span class="refentrytitle">ALTER SERVER</span></a>, <a class="xref" href="sql-dropserver.html" title="DROP SERVER"><span class="refentrytitle">DROP SERVER</span></a>, <a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>, <a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createsequence.html" title="CREATE SEQUENCE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createstatistics.html" title="CREATE STATISTICS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE SEQUENCE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE STATISTICS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createstatistics.html b/doc/src/sgml/html/sql-createstatistics.html
new file mode 100644
index 0000000..c5d23c2
--- /dev/null
+++ b/doc/src/sgml/html/sql-createstatistics.html
@@ -0,0 +1,210 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE STATISTICS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createserver.html" title="CREATE SERVER" /><link rel="next" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE STATISTICS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createserver.html" title="CREATE SERVER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATESTATISTICS"><div class="titlepage"></div><a id="id-1.9.3.83.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE STATISTICS</span></h2><p>CREATE STATISTICS — define extended statistics</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE STATISTICS [ IF NOT EXISTS ] <em class="replaceable"><code>statistics_name</code></em>
+ ON ( <em class="replaceable"><code>expression</code></em> )
+ FROM <em class="replaceable"><code>table_name</code></em>
+
+CREATE STATISTICS [ IF NOT EXISTS ] <em class="replaceable"><code>statistics_name</code></em>
+ [ ( <em class="replaceable"><code>statistics_kind</code></em> [, ... ] ) ]
+ ON { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) }, { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [, ...]
+ FROM <em class="replaceable"><code>table_name</code></em>
+</pre></div><div class="refsect1" id="SQL-CREATESTATISTICS-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE STATISTICS</code> will create a new extended statistics
+ object tracking data about the specified table, foreign table or
+ materialized view. The statistics object will be created in the current
+ database and will be owned by the user issuing the command.
+ </p><p>
+ The <code class="command">CREATE STATISTICS</code> command has two basic forms. The
+ first form allows univariate statistics for a single expression to be
+ collected, providing benefits similar to an expression index without the
+ overhead of index maintenance. This form does not allow the statistics
+ kind to be specified, since the various statistics kinds refer only to
+ multivariate statistics. The second form of the command allows
+ multivariate statistics on multiple columns and/or expressions to be
+ collected, optionally specifying which statistics kinds to include. This
+ form will also automatically cause univariate statistics to be collected on
+ any expressions included in the list.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE STATISTICS
+ myschema.mystat ...</code>) then the statistics object is created in the
+ specified schema. Otherwise it is created in the current schema.
+ The name of the statistics object must be distinct from the name of any
+ other statistics object in the same schema.
+ </p></div><div class="refsect1" id="id-1.9.3.83.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a statistics object with the same name already
+ exists. A notice is issued in this case. Note that only the name of
+ the statistics object is considered here, not the details of its
+ definition.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>statistics_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the statistics object to be
+ created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>statistics_kind</code></em></span></dt><dd><p>
+ A multivariate statistics kind to be computed in this statistics object.
+ Currently supported kinds are
+ <code class="literal">ndistinct</code>, which enables n-distinct statistics,
+ <code class="literal">dependencies</code>, which enables functional
+ dependency statistics, and <code class="literal">mcv</code> which enables
+ most-common values lists.
+ If this clause is omitted, all supported statistics kinds are
+ included in the statistics object. Univariate expression statistics are
+ built automatically if the statistics definition includes any complex
+ expressions rather than just simple column references.
+ For more information, see <a class="xref" href="planner-stats.html#PLANNER-STATS-EXTENDED" title="14.2.2. Extended Statistics">Section 14.2.2</a>
+ and <a class="xref" href="multivariate-statistics-examples.html" title="75.2. Multivariate Statistics Examples">Section 75.2</a>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a table column to be covered by the computed statistics.
+ This is only allowed when building multivariate statistics. At least
+ two column names or expressions must be specified, and their order is
+ not significant.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ An expression to be covered by the computed statistics. This may be
+ used to build univariate statistics on a single expression, or as part
+ of a list of multiple column names and/or expressions to build
+ multivariate statistics. In the latter case, separate univariate
+ statistics are built automatically for each expression in the list.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table containing the
+ column(s) the statistics are computed on; see <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a> for an explanation of the handling of
+ inheritance and partitions.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.83.7"><h2>Notes</h2><p>
+ You must be the owner of a table to create a statistics object
+ reading it. Once created, however, the ownership of the statistics
+ object is independent of the underlying table(s).
+ </p><p>
+ Expression statistics are per-expression and are similar to creating an
+ index on the expression, except that they avoid the overhead of index
+ maintenance. Expression statistics are built automatically for each
+ expression in the statistics object definition.
+ </p><p>
+ Extended statistics are not currently used by the planner for selectivity
+ estimations made for table joins. This limitation will likely be removed
+ in a future version of <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect1" id="SQL-CREATESTATISTICS-EXAMPLES"><h2>Examples</h2><p>
+ Create table <code class="structname">t1</code> with two functionally dependent columns, i.e.,
+ knowledge of a value in the first column is sufficient for determining the
+ value in the other column. Then functional dependency statistics are built
+ on those columns:
+
+</p><pre class="programlisting">
+CREATE TABLE t1 (
+ a int,
+ b int
+);
+
+INSERT INTO t1 SELECT i/100, i/500
+ FROM generate_series(1,1000000) s(i);
+
+ANALYZE t1;
+
+-- the number of matching rows will be drastically underestimated:
+EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0);
+
+CREATE STATISTICS s1 (dependencies) ON a, b FROM t1;
+
+ANALYZE t1;
+
+-- now the row count estimate is more accurate:
+EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0);
+</pre><p>
+
+ Without functional-dependency statistics, the planner would assume
+ that the two <code class="literal">WHERE</code> conditions are independent, and would
+ multiply their selectivities together to arrive at a much-too-small
+ row count estimate.
+ With such statistics, the planner recognizes that the <code class="literal">WHERE</code>
+ conditions are redundant and does not underestimate the row count.
+ </p><p>
+ Create table <code class="structname">t2</code> with two perfectly correlated columns
+ (containing identical data), and an MCV list on those columns:
+
+</p><pre class="programlisting">
+CREATE TABLE t2 (
+ a int,
+ b int
+);
+
+INSERT INTO t2 SELECT mod(i,100), mod(i,100)
+ FROM generate_series(1,1000000) s(i);
+
+CREATE STATISTICS s2 (mcv) ON a, b FROM t2;
+
+ANALYZE t2;
+
+-- valid combination (found in MCV)
+EXPLAIN ANALYZE SELECT * FROM t2 WHERE (a = 1) AND (b = 1);
+
+-- invalid combination (not found in MCV)
+EXPLAIN ANALYZE SELECT * FROM t2 WHERE (a = 1) AND (b = 2);
+</pre><p>
+
+ The MCV list gives the planner more detailed information about the
+ specific values that commonly appear in the table, as well as an upper
+ bound on the selectivities of combinations of values that do not appear
+ in the table, allowing it to generate better estimates in both cases.
+ </p><p>
+ Create table <code class="structname">t3</code> with a single timestamp column,
+ and run queries using expressions on that column. Without extended
+ statistics, the planner has no information about the data distribution for
+ the expressions, and uses default estimates. The planner also does not
+ realize that the value of the date truncated to the month is fully
+ determined by the value of the date truncated to the day. Then expression
+ and ndistinct statistics are built on those two expressions:
+
+</p><pre class="programlisting">
+CREATE TABLE t3 (
+ a timestamp
+);
+
+INSERT INTO t3 SELECT i FROM generate_series('2020-01-01'::timestamp,
+ '2020-12-31'::timestamp,
+ '1 minute'::interval) s(i);
+
+ANALYZE t3;
+
+-- the number of matching rows will be drastically underestimated:
+EXPLAIN ANALYZE SELECT * FROM t3
+ WHERE date_trunc('month', a) = '2020-01-01'::timestamp;
+
+EXPLAIN ANALYZE SELECT * FROM t3
+ WHERE date_trunc('day', a) BETWEEN '2020-01-01'::timestamp
+ AND '2020-06-30'::timestamp;
+
+EXPLAIN ANALYZE SELECT date_trunc('month', a), date_trunc('day', a)
+ FROM t3 GROUP BY 1, 2;
+
+-- build ndistinct statistics on the pair of expressions (per-expression
+-- statistics are built automatically)
+CREATE STATISTICS s3 (ndistinct) ON date_trunc('month', a), date_trunc('day', a) FROM t3;
+
+ANALYZE t3;
+
+-- now the row count estimates are more accurate:
+EXPLAIN ANALYZE SELECT * FROM t3
+ WHERE date_trunc('month', a) = '2020-01-01'::timestamp;
+
+EXPLAIN ANALYZE SELECT * FROM t3
+ WHERE date_trunc('day', a) BETWEEN '2020-01-01'::timestamp
+ AND '2020-06-30'::timestamp;
+
+EXPLAIN ANALYZE SELECT date_trunc('month', a), date_trunc('day', a)
+ FROM t3 GROUP BY 1, 2;
+</pre><p>
+
+ Without expression and ndistinct statistics, the planner has no information
+ about the number of distinct values for the expressions, and has to rely
+ on default estimates. The equality and range conditions are assumed to have
+ 0.5% selectivity, and the number of distinct values in the expression is
+ assumed to be the same as for the column (i.e. unique). This results in a
+ significant underestimate of the row count in the first two queries. Moreover,
+ the planner has no information about the relationship between the expressions,
+ so it assumes the two <code class="literal">WHERE</code> and <code class="literal">GROUP BY</code>
+ conditions are independent, and multiplies their selectivities together to
+ arrive at a severe overestimate of the group count in the aggregate query.
+ This is further exacerbated by the lack of accurate statistics for the
+ expressions, forcing the planner to use a default ndistinct estimate for the
+ expression derived from ndistinct for the column. With such statistics, the
+ planner recognizes that the conditions are correlated, and arrives at much
+ more accurate estimates.
+ </p></div><div class="refsect1" id="id-1.9.3.83.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE STATISTICS</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.83.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterstatistics.html" title="ALTER STATISTICS"><span class="refentrytitle">ALTER STATISTICS</span></a>, <a class="xref" href="sql-dropstatistics.html" title="DROP STATISTICS"><span class="refentrytitle">DROP STATISTICS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createserver.html" title="CREATE SERVER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE SERVER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE SUBSCRIPTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createsubscription.html b/doc/src/sgml/html/sql-createsubscription.html
new file mode 100644
index 0000000..66ff222
--- /dev/null
+++ b/doc/src/sgml/html/sql-createsubscription.html
@@ -0,0 +1,217 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE SUBSCRIPTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createstatistics.html" title="CREATE STATISTICS" /><link rel="next" href="sql-createtable.html" title="CREATE TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE SUBSCRIPTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createstatistics.html" title="CREATE STATISTICS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtable.html" title="CREATE TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATESUBSCRIPTION"><div class="titlepage"></div><a id="id-1.9.3.84.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE SUBSCRIPTION</span></h2><p>CREATE SUBSCRIPTION — define a new subscription</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE SUBSCRIPTION <em class="replaceable"><code>subscription_name</code></em>
+ CONNECTION '<em class="replaceable"><code>conninfo</code></em>'
+ PUBLICATION <em class="replaceable"><code>publication_name</code></em> [, ...]
+ [ WITH ( <em class="replaceable"><code>subscription_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.84.5"><h2>Description</h2><p>
+ <code class="command">CREATE SUBSCRIPTION</code> adds a new logical-replication
+ subscription. The subscription name must be distinct from the name of
+ any existing subscription in the current database.
+ </p><p>
+ A subscription represents a replication connection to the publisher.
+ Hence, in addition to adding definitions in the local catalogs, this
+ command normally creates a replication slot on the publisher.
+ </p><p>
+ A logical replication worker will be started to replicate data for the new
+ subscription at the commit of the transaction where this command is run,
+ unless the subscription is initially disabled.
+ </p><p>
+ Additional information about subscriptions and logical replication as a
+ whole is available at <a class="xref" href="logical-replication-subscription.html" title="31.2. Subscription">Section 31.2</a> and
+ <a class="xref" href="logical-replication.html" title="Chapter 31. Logical Replication">Chapter 31</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.84.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>subscription_name</code></em></span></dt><dd><p>
+ The name of the new subscription.
+ </p></dd><dt><span class="term"><code class="literal">CONNECTION '<em class="replaceable"><code>conninfo</code></em>'</code></span></dt><dd><p>
+ The <span class="application">libpq</span> connection string defining how
+ to connect to the publisher database. For details see
+ <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.
+ </p></dd><dt><span class="term"><code class="literal">PUBLICATION <em class="replaceable"><code>publication_name</code></em> [, ...]</code></span></dt><dd><p>
+ Names of the publications on the publisher to subscribe to.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>subscription_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional parameters for a subscription.
+ </p><p>
+ The following parameters control what happens during subscription creation:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">connect</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether the <code class="command">CREATE SUBSCRIPTION</code>
+ command should connect to the publisher at all. The default
+ is <code class="literal">true</code>. Setting this to
+ <code class="literal">false</code> will force the values of
+ <code class="literal">create_slot</code>, <code class="literal">enabled</code> and
+ <code class="literal">copy_data</code> to <code class="literal">false</code>.
+ (You cannot combine setting <code class="literal">connect</code>
+ to <code class="literal">false</code> with
+ setting <code class="literal">create_slot</code>, <code class="literal">enabled</code>,
+ or <code class="literal">copy_data</code> to <code class="literal">true</code>.)
+ </p><p>
+ Since no connection is made when this option is
+ <code class="literal">false</code>, no tables are subscribed, and so
+ after you enable the subscription nothing will be replicated.
+ You will need to then run
+ <code class="literal">ALTER SUBSCRIPTION ... REFRESH PUBLICATION</code>
+ for tables to be subscribed.
+ </p></dd><dt><span class="term"><code class="literal">create_slot</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether the command should create the replication slot on
+ the publisher. The default is <code class="literal">true</code>.
+ If set to <code class="literal">false</code>, you are responsible for
+ creating the publisher's slot in some other way.
+ </p></dd><dt><span class="term"><code class="literal">enabled</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether the subscription should be actively replicating
+ or whether it should just be set up but not started yet. The default
+ is <code class="literal">true</code>.
+ </p></dd><dt><span class="term"><code class="literal">slot_name</code> (<code class="type">string</code>)</span></dt><dd><p>
+ Name of the publisher's replication slot to use. The default is
+ to use the name of the subscription for the slot name.
+ </p><p>
+ Setting <code class="literal">slot_name</code> to <code class="literal">NONE</code>
+ means there will be no replication slot
+ associated with the subscription. Use this when you will be
+ creating the replication slot later manually. Such
+ subscriptions must also have both <code class="literal">enabled</code> and
+ <code class="literal">create_slot</code> set to <code class="literal">false</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following parameters control the subscription's replication
+ behavior after it has been created:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">binary</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether the subscription will request the publisher to
+ send the data in binary format (as opposed to text).
+ The default is <code class="literal">false</code>.
+ Even when this option is enabled, only data types having
+ binary send and receive functions will be transferred in binary.
+ </p><p>
+ When doing cross-version replication, it could be that the
+ publisher has a binary send function for some data type, but the
+ subscriber lacks a binary receive function for that type. In
+ such a case, data transfer will fail, and
+ the <code class="literal">binary</code> option cannot be used.
+ </p></dd><dt><span class="term"><code class="literal">copy_data</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether to copy pre-existing data in the publications
+ that are being subscribed to when the replication starts.
+ The default is <code class="literal">true</code>.
+ </p><p>
+ If the publications contain <code class="literal">WHERE</code> clauses, it
+ will affect what data is copied. Refer to the
+ <a class="xref" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-NOTES" title="Notes">Notes</a> for details.
+ </p></dd><dt><span class="term"><code class="literal">streaming</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether to enable streaming of in-progress transactions
+ for this subscription. By default, all transactions
+ are fully decoded on the publisher and only then sent to the
+ subscriber as a whole.
+ </p></dd><dt><span class="term"><code class="literal">synchronous_commit</code> (<code class="type">enum</code>)</span></dt><dd><p>
+ The value of this parameter overrides the
+ <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> setting within this
+ subscription's apply worker processes. The default value
+ is <code class="literal">off</code>.
+ </p><p>
+ It is safe to use <code class="literal">off</code> for logical replication:
+ If the subscriber loses transactions because of missing
+ synchronization, the data will be sent again from the publisher.
+ </p><p>
+ A different setting might be appropriate when doing synchronous
+ logical replication. The logical replication workers report the
+ positions of writes and flushes to the publisher, and when using
+ synchronous replication, the publisher will wait for the actual
+ flush. This means that setting
+ <code class="literal">synchronous_commit</code> for the subscriber to
+ <code class="literal">off</code> when the subscription is used for
+ synchronous replication might increase the latency for
+ <code class="command">COMMIT</code> on the publisher. In this scenario, it
+ can be advantageous to set <code class="literal">synchronous_commit</code>
+ to <code class="literal">local</code> or higher.
+ </p></dd><dt><span class="term"><code class="literal">two_phase</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether two-phase commit is enabled for this subscription.
+ The default is <code class="literal">false</code>.
+ </p><p>
+ When two-phase commit is enabled, prepared transactions are sent
+ to the subscriber at the time of <code class="command">PREPARE
+ TRANSACTION</code>, and are processed as two-phase
+ transactions on the subscriber too. Otherwise, prepared
+ transactions are sent to the subscriber only when committed, and
+ are then processed immediately by the subscriber.
+ </p><p>
+ The implementation of two-phase commit requires that replication
+ has successfully finished the initial table synchronization
+ phase. So even when <code class="literal">two_phase</code> is enabled for a
+ subscription, the internal two-phase state remains
+ temporarily <span class="quote">“<span class="quote">pending</span>”</span> until the initialization phase
+ completes. See column <code class="structfield">subtwophasestate</code>
+ of <a class="link" href="catalog-pg-subscription.html" title="53.54. pg_subscription"><code class="structname">pg_subscription</code></a>
+ to know the actual two-phase state.
+ </p></dd><dt><span class="term"><code class="literal">disable_on_error</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ Specifies whether the subscription should be automatically disabled
+ if any errors are detected by subscription workers during data
+ replication from the publisher. The default is
+ <code class="literal">false</code>.
+ </p></dd></dl></div></dd></dl></div></div><div class="refsect1" id="SQL-CREATESUBSCRIPTION-NOTES"><h2>Notes</h2><p>
+ See <a class="xref" href="logical-replication-security.html" title="31.9. Security">Section 31.9</a> for details on
+ how to configure access control between the subscription and the
+ publication instance.
+ </p><p>
+ When creating a replication slot (the default behavior), <code class="command">CREATE
+ SUBSCRIPTION</code> cannot be executed inside a transaction block.
+ </p><p>
+ Creating a subscription that connects to the same database cluster (for
+ example, to replicate between databases in the same cluster or to replicate
+ within the same database) will only succeed if the replication slot is not
+ created as part of the same command. Otherwise, the <code class="command">CREATE
+ SUBSCRIPTION</code> call will hang. To make this work, create the
+ replication slot separately (using the
+ function <code class="function">pg_create_logical_replication_slot</code> with the
+ plugin name <code class="literal">pgoutput</code>) and create the subscription using
+ the parameter <code class="literal">create_slot = false</code>. This is an
+ implementation restriction that might be lifted in a future release.
+ </p><p>
+ If any table in the publication has a <code class="literal">WHERE</code> clause, rows
+ for which the <em class="replaceable"><code>expression</code></em>
+ evaluates to false or null will not be published. If the subscription has
+ several publications in which the same table has been published with
+ different <code class="literal">WHERE</code> clauses, a row will be published if any
+ of the expressions (referring to that publish operation) are satisfied. In
+ the case of different <code class="literal">WHERE</code> clauses, if one of the
+ publications has no <code class="literal">WHERE</code> clause (referring to that
+ publish operation) or the publication is declared as
+ <code class="literal">FOR ALL TABLES</code> or
+ <code class="literal">FOR TABLES IN SCHEMA</code>, rows are always published
+ regardless of the definition of the other expressions.
+ If the subscriber is a <span class="productname">PostgreSQL</span> version before
+ 15, then any row filtering is ignored during the initial data synchronization
+ phase. For this case, the user might want to consider deleting any initially
+ copied data that would be incompatible with subsequent filtering.
+ Because initial data synchronization does not take into account the publication
+ <code class="literal">publish</code> parameter when copying existing table data, some rows
+ may be copied that would not be replicated using DML. See
+ <a class="xref" href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-EXAMPLES" title="31.2.2. Examples">Section 31.2.2</a> for examples.
+ </p><p>
+ Subscriptions having several publications in which the same table has been
+ published with different column lists are not supported.
+ </p><p>
+ We allow non-existent publications to be specified so that users can add
+ those later. This means
+ <a class="link" href="catalog-pg-subscription.html" title="53.54. pg_subscription"><code class="structname">pg_subscription</code></a>
+ can have non-existent publications.
+ </p></div><div class="refsect1" id="id-1.9.3.84.8"><h2>Examples</h2><p>
+ Create a subscription to a remote server that replicates tables in
+ the publications <code class="literal">mypublication</code> and
+ <code class="literal">insert_only</code> and starts replicating immediately on
+ commit:
+</p><pre class="programlisting">
+CREATE SUBSCRIPTION mysub
+ CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
+ PUBLICATION mypublication, insert_only;
+</pre><p>
+ </p><p>
+ Create a subscription to a remote server that replicates tables in
+ the <code class="literal">insert_only</code> publication and does not start replicating
+ until enabled at a later time.
+</p><pre class="programlisting">
+CREATE SUBSCRIPTION mysub
+ CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
+ PUBLICATION insert_only
+ WITH (enabled = false);
+</pre></div><div class="refsect1" id="id-1.9.3.84.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE SUBSCRIPTION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.84.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a>, <a class="xref" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION"><span class="refentrytitle">DROP SUBSCRIPTION</span></a>, <a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>, <a class="xref" href="sql-alterpublication.html" title="ALTER PUBLICATION"><span class="refentrytitle">ALTER PUBLICATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createstatistics.html" title="CREATE STATISTICS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtable.html" title="CREATE TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE STATISTICS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtable.html b/doc/src/sgml/html/sql-createtable.html
new file mode 100644
index 0000000..473703b
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtable.html
@@ -0,0 +1,1470 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION" /><link rel="next" href="sql-createtableas.html" title="CREATE TABLE AS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtableas.html" title="CREATE TABLE AS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETABLE"><div class="titlepage"></div><a id="id-1.9.3.85.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TABLE</span></h2><p>CREATE TABLE — define a new table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em> ( [
+ { <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COMPRESSION <em class="replaceable"><code>compression_method</code></em> ] [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ | <em class="replaceable"><code>table_constraint</code></em>
+ | LIKE <em class="replaceable"><code>source_table</code></em> [ <em class="replaceable"><code>like_option</code></em> ... ] }
+ [, ... ]
+] )
+[ INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] ) ]
+[ PARTITION BY { RANGE | LIST | HASH } ( { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> ] [, ... ] ) ]
+[ USING <em class="replaceable"><code>method</code></em> ]
+[ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) | WITHOUT OIDS ]
+[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
+[ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
+ OF <em class="replaceable"><code>type_name</code></em> [ (
+ { <em class="replaceable"><code>column_name</code></em> [ WITH OPTIONS ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ | <em class="replaceable"><code>table_constraint</code></em> }
+ [, ... ]
+) ]
+[ PARTITION BY { RANGE | LIST | HASH } ( { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> ] [, ... ] ) ]
+[ USING <em class="replaceable"><code>method</code></em> ]
+[ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) | WITHOUT OIDS ]
+[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
+[ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
+ PARTITION OF <em class="replaceable"><code>parent_table</code></em> [ (
+ { <em class="replaceable"><code>column_name</code></em> [ WITH OPTIONS ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
+ | <em class="replaceable"><code>table_constraint</code></em> }
+ [, ... ]
+) ] { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }
+[ PARTITION BY { RANGE | LIST | HASH } ( { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> ] [, ... ] ) ]
+[ USING <em class="replaceable"><code>method</code></em> ]
+[ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) | WITHOUT OIDS ]
+[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
+[ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+
+<span class="phrase">where <em class="replaceable"><code>column_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ NOT NULL |
+ NULL |
+ CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
+ DEFAULT <em class="replaceable"><code>default_expr</code></em> |
+ GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) STORED |
+ GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <em class="replaceable"><code>sequence_options</code></em> ) ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] <em class="replaceable"><code>index_parameters</code></em> |
+ PRIMARY KEY <em class="replaceable"><code>index_parameters</code></em> |
+ REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
+ [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ] [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ] }
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+
+<span class="phrase">and <em class="replaceable"><code>table_constraint</code></em> is:</span>
+
+[ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
+{ CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> |
+ PRIMARY KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> |
+ EXCLUDE [ USING <em class="replaceable"><code>index_method</code></em> ] ( <em class="replaceable"><code>exclude_element</code></em> WITH <em class="replaceable"><code>operator</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> [ WHERE ( <em class="replaceable"><code>predicate</code></em> ) ] |
+ FOREIGN KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> [, ... ] ) ]
+ [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ] [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ] }
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+
+<span class="phrase">and <em class="replaceable"><code>like_option</code></em> is:</span>
+
+{ INCLUDING | EXCLUDING } { COMMENTS | COMPRESSION | CONSTRAINTS | DEFAULTS | GENERATED | IDENTITY | INDEXES | STATISTICS | STORAGE | ALL }
+
+<span class="phrase">and <em class="replaceable"><code>partition_bound_spec</code></em> is:</span>
+
+IN ( <em class="replaceable"><code>partition_bound_expr</code></em> [, ...] ) |
+FROM ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] )
+ TO ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] ) |
+WITH ( MODULUS <em class="replaceable"><code>numeric_literal</code></em>, REMAINDER <em class="replaceable"><code>numeric_literal</code></em> )
+
+<span class="phrase"><em class="replaceable"><code>index_parameters</code></em> in <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>, and <code class="literal">EXCLUDE</code> constraints are:</span>
+
+[ INCLUDE ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ]
+[ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) ]
+[ USING INDEX TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+
+<span class="phrase"><em class="replaceable"><code>exclude_element</code></em> in an <code class="literal">EXCLUDE</code> constraint is:</span>
+
+{ <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ <em class="replaceable"><code>opclass</code></em> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
+
+<span class="phrase"><em class="replaceable"><code>referential_action</code></em> in a <code class="literal">FOREIGN KEY</code>/<code class="literal">REFERENCES</code> constraint is:</span>
+
+{ NO ACTION | RESTRICT | CASCADE | SET NULL [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] | SET DEFAULT [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ] }
+</pre></div><div class="refsect1" id="SQL-CREATETABLE-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE TABLE</code> will create a new, initially empty table
+ in the current database. The table will be owned by the user issuing the
+ command.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE TABLE
+ myschema.mytable ...</code>) then the table is created in the specified
+ schema. Otherwise it is created in the current schema. Temporary
+ tables exist in a special schema, so a schema name cannot be given
+ when creating a temporary table. The name of the table must be
+ distinct from the name of any other relation (table, sequence, index, view,
+ materialized view, or foreign table) in the same schema.
+ </p><p>
+ <code class="command">CREATE TABLE</code> also automatically creates a data
+ type that represents the composite type corresponding
+ to one row of the table. Therefore, tables cannot have the same
+ name as any existing data type in the same schema.
+ </p><p>
+ The optional constraint clauses specify constraints (tests) that
+ new or updated rows must satisfy for an insert or update operation
+ to succeed. A constraint is an SQL object that helps define the
+ set of valid values in the table in various ways.
+ </p><p>
+ There are two ways to define constraints: table constraints and
+ column constraints. A column constraint is defined as part of a
+ column definition. A table constraint definition is not tied to a
+ particular column, and it can encompass more than one column.
+ Every column constraint can also be written as a table constraint;
+ a column constraint is only a notational convenience for use when the
+ constraint only affects one column.
+ </p><p>
+ To be able to create a table, you must have <code class="literal">USAGE</code>
+ privilege on all column types or the type in the <code class="literal">OF</code>
+ clause, respectively.
+ </p></div><div class="refsect1" id="id-1.9.3.85.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt id="SQL-CREATETABLE-TEMPORARY"><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ If specified, the table is created as a temporary table.
+ Temporary tables are automatically dropped at the end of a
+ session, or optionally at the end of the current transaction
+ (see <code class="literal">ON COMMIT</code> below). The default
+ search_path includes the temporary schema first and so identically
+ named existing permanent tables are not chosen for new plans
+ while the temporary table exists, unless they are referenced
+ with schema-qualified names. Any indexes created on a temporary
+ table are automatically temporary as well.
+ </p><p>
+ The <a class="link" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">autovacuum daemon</a> cannot
+ access and therefore cannot vacuum or analyze temporary tables.
+ For this reason, appropriate vacuum and analyze operations should be
+ performed via session SQL commands. For example, if a temporary
+ table is going to be used in complex queries, it is wise to run
+ <code class="command">ANALYZE</code> on the temporary table after it is populated.
+ </p><p>
+ Optionally, <code class="literal">GLOBAL</code> or <code class="literal">LOCAL</code>
+ can be written before <code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code>.
+ This presently makes no difference in <span class="productname">PostgreSQL</span>
+ and is deprecated; see
+ <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-COMPATIBILITY" title="Compatibility">Compatibility</a> below.
+ </p></dd><dt id="SQL-CREATETABLE-UNLOGGED"><span class="term"><code class="literal">UNLOGGED</code></span></dt><dd><p>
+ If specified, the table is created as an unlogged table. Data written
+ to unlogged tables is not written to the write-ahead log (see <a class="xref" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Chapter 30</a>), which makes them considerably faster than ordinary
+ tables. However, they are not crash-safe: an unlogged table is
+ automatically truncated after a crash or unclean shutdown. The contents
+ of an unlogged table are also not replicated to standby servers.
+ Any indexes created on an unlogged table are automatically unlogged as
+ well.
+ </p><p>
+ If this is specified, any sequences created together with the unlogged
+ table (for identity or serial columns) are also created as unlogged.
+ </p></dd><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a relation with the same name already exists.
+ A notice is issued in this case. Note that there is no guarantee that
+ the existing relation is anything like the one that would have been
+ created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to be created.
+ </p></dd><dt><span class="term"><code class="literal">OF <em class="replaceable"><code>type_name</code></em></code></span></dt><dd><p>
+ Creates a <em class="firstterm">typed table</em>, which takes its
+ structure from the specified composite type (name optionally
+ schema-qualified). A typed table is tied to its type; for
+ example the table will be dropped if the type is dropped
+ (with <code class="literal">DROP TYPE ... CASCADE</code>).
+ </p><p>
+ When a typed table is created, then the data types of the
+ columns are determined by the underlying composite type and are
+ not specified by the <code class="literal">CREATE TABLE</code> command.
+ But the <code class="literal">CREATE TABLE</code> command can add defaults
+ and constraints to the table and can specify storage parameters.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column to be created in the new table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The data type of the column. This can include array
+ specifiers. For more information on the data types supported by
+ <span class="productname">PostgreSQL</span>, refer to <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>.
+ </p></dd><dt><span class="term"><code class="literal">COLLATE <em class="replaceable"><code>collation</code></em></code></span></dt><dd><p>
+ The <code class="literal">COLLATE</code> clause assigns a collation to
+ the column (which must be of a collatable data type).
+ If not specified, the column data type's default collation is used.
+ </p></dd><dt><span class="term"><code class="literal">COMPRESSION <em class="replaceable"><code>compression_method</code></em></code></span></dt><dd><p>
+ The <code class="literal">COMPRESSION</code> clause sets the compression method
+ for the column. Compression is supported only for variable-width data
+ types, and is used only when the column's storage mode
+ is <code class="literal">main</code> or <code class="literal">extended</code>.
+ (See <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a> for information on
+ column storage modes.) Setting this property for a partitioned table
+ has no direct effect, because such tables have no storage of their own,
+ but the configured value will be inherited by newly-created partitions.
+ The supported compression methods are <code class="literal">pglz</code> and
+ <code class="literal">lz4</code>. (<code class="literal">lz4</code> is available only if
+ <code class="option">--with-lz4</code> was used when building
+ <span class="productname">PostgreSQL</span>.) In addition,
+ <em class="replaceable"><code>compression_method</code></em>
+ can be <code class="literal">default</code> to explicitly specify the default
+ behavior, which is to consult the
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TOAST-COMPRESSION">default_toast_compression</a> setting at the time of
+ data insertion to determine the method to use.
+ </p></dd><dt><span class="term"><code class="literal">INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] )</code></span></dt><dd><p>
+ The optional <code class="literal">INHERITS</code> clause specifies a list of
+ tables from which the new table automatically inherits all
+ columns. Parent tables can be plain tables or foreign tables.
+ </p><p>
+ Use of <code class="literal">INHERITS</code> creates a persistent relationship
+ between the new child table and its parent table(s). Schema
+ modifications to the parent(s) normally propagate to children
+ as well, and by default the data of the child table is included in
+ scans of the parent(s).
+ </p><p>
+ If the same column name exists in more than one parent
+ table, an error is reported unless the data types of the columns
+ match in each of the parent tables. If there is no conflict,
+ then the duplicate columns are merged to form a single column in
+ the new table. If the column name list of the new table
+ contains a column name that is also inherited, the data type must
+ likewise match the inherited column(s), and the column
+ definitions are merged into one. If the
+ new table explicitly specifies a default value for the column,
+ this default overrides any defaults from inherited declarations
+ of the column. Otherwise, any parents that specify default
+ values for the column must all specify the same default, or an
+ error will be reported.
+ </p><p>
+ <code class="literal">CHECK</code> constraints are merged in essentially the same way as
+ columns: if multiple parent tables and/or the new table definition
+ contain identically-named <code class="literal">CHECK</code> constraints, these
+ constraints must all have the same check expression, or an error will be
+ reported. Constraints having the same name and expression will
+ be merged into one copy. A constraint marked <code class="literal">NO INHERIT</code> in a
+ parent will not be considered. Notice that an unnamed <code class="literal">CHECK</code>
+ constraint in the new table will never be merged, since a unique name
+ will always be chosen for it.
+ </p><p>
+ Column <code class="literal">STORAGE</code> settings are also copied from parent tables.
+ </p><p>
+ If a column in the parent table is an identity column, that property is
+ not inherited. A column in the child table can be declared identity
+ column if desired.
+ </p></dd><dt><span class="term"><code class="literal">PARTITION BY { RANGE | LIST | HASH } ( { <em class="replaceable"><code>column_name</code></em> | ( <em class="replaceable"><code>expression</code></em> ) } [ <em class="replaceable"><code>opclass</code></em> ] [, ...] ) </code></span></dt><dd><p>
+ The optional <code class="literal">PARTITION BY</code> clause specifies a strategy
+ of partitioning the table. The table thus created is called a
+ <em class="firstterm">partitioned</em> table. The parenthesized list of
+ columns or expressions forms the <em class="firstterm">partition key</em>
+ for the table. When using range or hash partitioning, the partition key
+ can include multiple columns or expressions (up to 32, but this limit can
+ be altered when building <span class="productname">PostgreSQL</span>), but for
+ list partitioning, the partition key must consist of a single column or
+ expression.
+ </p><p>
+ Range and list partitioning require a btree operator class, while hash
+ partitioning requires a hash operator class. If no operator class is
+ specified explicitly, the default operator class of the appropriate
+ type will be used; if no default operator class exists, an error will
+ be raised. When hash partitioning is used, the operator class used
+ must implement support function 2 (see <a class="xref" href="xindex.html#XINDEX-SUPPORT" title="38.16.3. Index Method Support Routines">Section 38.16.3</a>
+ for details).
+ </p><p>
+ A partitioned table is divided into sub-tables (called partitions),
+ which are created using separate <code class="literal">CREATE TABLE</code> commands.
+ The partitioned table is itself empty. A data row inserted into the
+ table is routed to a partition based on the value of columns or
+ expressions in the partition key. If no existing partition matches
+ the values in the new row, an error will be reported.
+ </p><p>
+ Partitioned tables do not support <code class="literal">EXCLUDE</code> constraints;
+ however, you can define these constraints on individual partitions.
+ </p><p>
+ See <a class="xref" href="ddl-partitioning.html" title="5.11. Table Partitioning">Section 5.11</a> for more discussion on table
+ partitioning.
+ </p></dd><dt id="SQL-CREATETABLE-PARTITION"><span class="term"><code class="literal">PARTITION OF <em class="replaceable"><code>parent_table</code></em> { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }</code></span></dt><dd><p>
+ Creates the table as a <em class="firstterm">partition</em> of the specified
+ parent table. The table can be created either as a partition for specific
+ values using <code class="literal">FOR VALUES</code> or as a default partition
+ using <code class="literal">DEFAULT</code>. Any indexes, constraints and
+ user-defined row-level triggers that exist in the parent table are cloned
+ on the new partition.
+ </p><p>
+ The <em class="replaceable"><code>partition_bound_spec</code></em>
+ must correspond to the partitioning method and partition key of the
+ parent table, and must not overlap with any existing partition of that
+ parent. The form with <code class="literal">IN</code> is used for list partitioning,
+ the form with <code class="literal">FROM</code> and <code class="literal">TO</code> is used
+ for range partitioning, and the form with <code class="literal">WITH</code> is used
+ for hash partitioning.
+ </p><p>
+ <em class="replaceable"><code>partition_bound_expr</code></em> is
+ any variable-free expression (subqueries, window functions, aggregate
+ functions, and set-returning functions are not allowed). Its data type
+ must match the data type of the corresponding partition key column.
+ The expression is evaluated once at table creation time, so it can
+ even contain volatile expressions such as
+ <code class="literal"><code class="function">CURRENT_TIMESTAMP</code></code>.
+ </p><p>
+ When creating a list partition, <code class="literal">NULL</code> can be
+ specified to signify that the partition allows the partition key
+ column to be null. However, there cannot be more than one such
+ list partition for a given parent table. <code class="literal">NULL</code>
+ cannot be specified for range partitions.
+ </p><p>
+ When creating a range partition, the lower bound specified with
+ <code class="literal">FROM</code> is an inclusive bound, whereas the upper
+ bound specified with <code class="literal">TO</code> is an exclusive bound.
+ That is, the values specified in the <code class="literal">FROM</code> list
+ are valid values of the corresponding partition key columns for this
+ partition, whereas those in the <code class="literal">TO</code> list are
+ not. Note that this statement must be understood according to the
+ rules of row-wise comparison (<a class="xref" href="functions-comparisons.html#ROW-WISE-COMPARISON" title="9.24.5. Row Constructor Comparison">Section 9.24.5</a>).
+ For example, given <code class="literal">PARTITION BY RANGE (x,y)</code>, a partition
+ bound <code class="literal">FROM (1, 2) TO (3, 4)</code>
+ allows <code class="literal">x=1</code> with any <code class="literal">y&gt;=2</code>,
+ <code class="literal">x=2</code> with any non-null <code class="literal">y</code>,
+ and <code class="literal">x=3</code> with any <code class="literal">y&lt;4</code>.
+ </p><p>
+ The special values <code class="literal">MINVALUE</code> and <code class="literal">MAXVALUE</code>
+ may be used when creating a range partition to indicate that there
+ is no lower or upper bound on the column's value. For example, a
+ partition defined using <code class="literal">FROM (MINVALUE) TO (10)</code> allows
+ any values less than 10, and a partition defined using
+ <code class="literal">FROM (10) TO (MAXVALUE)</code> allows any values greater than
+ or equal to 10.
+ </p><p>
+ When creating a range partition involving more than one column, it
+ can also make sense to use <code class="literal">MAXVALUE</code> as part of the lower
+ bound, and <code class="literal">MINVALUE</code> as part of the upper bound. For
+ example, a partition defined using
+ <code class="literal">FROM (0, MAXVALUE) TO (10, MAXVALUE)</code> allows any rows
+ where the first partition key column is greater than 0 and less than
+ or equal to 10. Similarly, a partition defined using
+ <code class="literal">FROM ('a', MINVALUE) TO ('b', MINVALUE)</code> allows any rows
+ where the first partition key column starts with "a".
+ </p><p>
+ Note that if <code class="literal">MINVALUE</code> or <code class="literal">MAXVALUE</code> is used for
+ one column of a partitioning bound, the same value must be used for all
+ subsequent columns. For example, <code class="literal">(10, MINVALUE, 0)</code> is not
+ a valid bound; you should write <code class="literal">(10, MINVALUE, MINVALUE)</code>.
+ </p><p>
+ Also note that some element types, such as <code class="literal">timestamp</code>,
+ have a notion of "infinity", which is just another value that can
+ be stored. This is different from <code class="literal">MINVALUE</code> and
+ <code class="literal">MAXVALUE</code>, which are not real values that can be stored,
+ but rather they are ways of saying that the value is unbounded.
+ <code class="literal">MAXVALUE</code> can be thought of as being greater than any
+ other value, including "infinity" and <code class="literal">MINVALUE</code> as being
+ less than any other value, including "minus infinity". Thus the range
+ <code class="literal">FROM ('infinity') TO (MAXVALUE)</code> is not an empty range; it
+ allows precisely one value to be stored — "infinity".
+ </p><p>
+ If <code class="literal">DEFAULT</code> is specified, the table will be
+ created as the default partition of the parent table. This option
+ is not available for hash-partitioned tables. A partition key value
+ not fitting into any other partition of the given parent will be
+ routed to the default partition.
+ </p><p>
+ When a table has an existing <code class="literal">DEFAULT</code> partition and
+ a new partition is added to it, the default partition must
+ be scanned to verify that it does not contain any rows which properly
+ belong in the new partition. If the default partition contains a
+ large number of rows, this may be slow. The scan will be skipped if
+ the default partition is a foreign table or if it has a constraint which
+ proves that it cannot contain rows which should be placed in the new
+ partition.
+ </p><p>
+ When creating a hash partition, a modulus and remainder must be specified.
+ The modulus must be a positive integer, and the remainder must be a
+ non-negative integer less than the modulus. Typically, when initially
+ setting up a hash-partitioned table, you should choose a modulus equal to
+ the number of partitions and assign every table the same modulus and a
+ different remainder (see examples, below). However, it is not required
+ that every partition have the same modulus, only that every modulus which
+ occurs among the partitions of a hash-partitioned table is a factor of the
+ next larger modulus. This allows the number of partitions to be increased
+ incrementally without needing to move all the data at once. For example,
+ suppose you have a hash-partitioned table with 8 partitions, each of which
+ has modulus 8, but find it necessary to increase the number of partitions
+ to 16. You can detach one of the modulus-8 partitions, create two new
+ modulus-16 partitions covering the same portion of the key space (one with
+ a remainder equal to the remainder of the detached partition, and the
+ other with a remainder equal to that value plus 8), and repopulate them
+ with data. You can then repeat this -- perhaps at a later time -- for
+ each modulus-8 partition until none remain. While this may still involve
+ a large amount of data movement at each step, it is still better than
+ having to create a whole new table and move all the data at once.
+ </p><p>
+ A partition must have the same column names and types as the partitioned
+ table to which it belongs. Modifications to the column names or types of
+ a partitioned table will automatically propagate to all partitions.
+ <code class="literal">CHECK</code> constraints will be inherited automatically by
+ every partition, but an individual partition may specify additional
+ <code class="literal">CHECK</code> constraints; additional constraints with the
+ same name and condition as in the parent will be merged with the parent
+ constraint. Defaults may be specified separately for each partition.
+ But note that a partition's default value is not applied when inserting
+ a tuple through a partitioned table.
+ </p><p>
+ Rows inserted into a partitioned table will be automatically routed to
+ the correct partition. If no suitable partition exists, an error will
+ occur.
+ </p><p>
+ Operations such as <code class="command">TRUNCATE</code>
+ which normally affect a table and all of its
+ inheritance children will cascade to all partitions, but may also be
+ performed on an individual partition.
+ </p><p>
+ Note that creating a partition using <code class="literal">PARTITION OF</code>
+ requires taking an <code class="literal">ACCESS EXCLUSIVE</code> lock on the
+ parent partitioned table. Likewise, dropping a partition
+ with <code class="command">DROP TABLE</code> requires taking
+ an <code class="literal">ACCESS EXCLUSIVE</code> lock on the parent table.
+ It is possible to use <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER
+ TABLE ATTACH/DETACH PARTITION</code></a> to perform these
+ operations with a weaker lock, thus reducing interference with
+ concurrent operations on the partitioned table.
+ </p></dd><dt><span class="term"><code class="literal">LIKE <em class="replaceable"><code>source_table</code></em> [ <em class="replaceable"><code>like_option</code></em> ... ]</code></span></dt><dd><p>
+ The <code class="literal">LIKE</code> clause specifies a table from which
+ the new table automatically copies all column names, their data types,
+ and their not-null constraints.
+ </p><p>
+ Unlike <code class="literal">INHERITS</code>, the new table and original table
+ are completely decoupled after creation is complete. Changes to the
+ original table will not be applied to the new table, and it is not
+ possible to include data of the new table in scans of the original
+ table.
+ </p><p>
+ Also unlike <code class="literal">INHERITS</code>, columns and
+ constraints copied by <code class="literal">LIKE</code> are not merged with similarly
+ named columns and constraints.
+ If the same name is specified explicitly or in another
+ <code class="literal">LIKE</code> clause, an error is signaled.
+ </p><p>
+ The optional <em class="replaceable"><code>like_option</code></em> clauses specify
+ which additional properties of the original table to copy. Specifying
+ <code class="literal">INCLUDING</code> copies the property, specifying
+ <code class="literal">EXCLUDING</code> omits the property.
+ <code class="literal">EXCLUDING</code> is the default. If multiple specifications
+ are made for the same kind of object, the last one is used. The
+ available options are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">INCLUDING COMMENTS</code></span></dt><dd><p>
+ Comments for the copied columns, constraints, and indexes will be
+ copied. The default behavior is to exclude comments, resulting in
+ the copied columns and constraints in the new table having no
+ comments.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING COMPRESSION</code></span></dt><dd><p>
+ Compression method of the columns will be copied. The default
+ behavior is to exclude compression methods, resulting in columns
+ having the default compression method.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING CONSTRAINTS</code></span></dt><dd><p>
+ <code class="literal">CHECK</code> constraints will be copied. No distinction
+ is made between column constraints and table constraints. Not-null
+ constraints are always copied to the new table.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING DEFAULTS</code></span></dt><dd><p>
+ Default expressions for the copied column definitions will be
+ copied. Otherwise, default expressions are not copied, resulting in
+ the copied columns in the new table having null defaults. Note that
+ copying defaults that call database-modification functions, such as
+ <code class="function">nextval</code>, may create a functional linkage
+ between the original and new tables.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING GENERATED</code></span></dt><dd><p>
+ Any generation expressions of copied column definitions will be
+ copied. By default, new columns will be regular base columns.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING IDENTITY</code></span></dt><dd><p>
+ Any identity specifications of copied column definitions will be
+ copied. A new sequence is created for each identity column of the
+ new table, separate from the sequences associated with the old
+ table.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING INDEXES</code></span></dt><dd><p>
+ Indexes, <code class="literal">PRIMARY KEY</code>, <code class="literal">UNIQUE</code>,
+ and <code class="literal">EXCLUDE</code> constraints on the original table
+ will be created on the new table. Names for the new indexes and
+ constraints are chosen according to the default rules, regardless of
+ how the originals were named. (This behavior avoids possible
+ duplicate-name failures for the new indexes.)
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING STATISTICS</code></span></dt><dd><p>
+ Extended statistics are copied to the new table.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING STORAGE</code></span></dt><dd><p>
+ <code class="literal">STORAGE</code> settings for the copied column
+ definitions will be copied. The default behavior is to exclude
+ <code class="literal">STORAGE</code> settings, resulting in the copied columns
+ in the new table having type-specific default settings. For more on
+ <code class="literal">STORAGE</code> settings, see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>.
+ </p></dd><dt><span class="term"><code class="literal">INCLUDING ALL</code></span></dt><dd><p>
+ <code class="literal">INCLUDING ALL</code> is an abbreviated form selecting
+ all the available individual options. (It could be useful to write
+ individual <code class="literal">EXCLUDING</code> clauses after
+ <code class="literal">INCLUDING ALL</code> to select all but some specific
+ options.)
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="literal">LIKE</code> clause can also be used to copy column
+ definitions from views, foreign tables, or composite types.
+ Inapplicable options (e.g., <code class="literal">INCLUDING INDEXES</code> from
+ a view) are ignored.
+ </p></dd><dt><span class="term"><code class="literal">CONSTRAINT <em class="replaceable"><code>constraint_name</code></em></code></span></dt><dd><p>
+ An optional name for a column or table constraint. If the
+ constraint is violated, the constraint name is present in error messages,
+ so constraint names like <code class="literal">col must be positive</code> can be used
+ to communicate helpful constraint information to client applications.
+ (Double-quotes are needed to specify constraint names that contain spaces.)
+ If a constraint name is not specified, the system generates a name.
+ </p></dd><dt><span class="term"><code class="literal">NOT NULL</code></span></dt><dd><p>
+ The column is not allowed to contain null values.
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ The column is allowed to contain null values. This is the default.
+ </p><p>
+ This clause is only provided for compatibility with
+ non-standard SQL databases. Its use is discouraged in new
+ applications.
+ </p></dd><dt><span class="term"><code class="literal">CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] </code></span></dt><dd><p>
+ The <code class="literal">CHECK</code> clause specifies an expression producing a
+ Boolean result which new or updated rows must satisfy for an
+ insert or update operation to succeed. Expressions evaluating
+ to TRUE or UNKNOWN succeed. Should any row of an insert or
+ update operation produce a FALSE result, an error exception is
+ raised and the insert or update does not alter the database. A
+ check constraint specified as a column constraint should
+ reference that column's value only, while an expression
+ appearing in a table constraint can reference multiple columns.
+ </p><p>
+ Currently, <code class="literal">CHECK</code> expressions cannot contain
+ subqueries nor refer to variables other than columns of the
+ current row (see <a class="xref" href="ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS" title="5.4.1. Check Constraints">Section 5.4.1</a>).
+ The system column <code class="literal">tableoid</code>
+ may be referenced, but not any other system column.
+ </p><p>
+ A constraint marked with <code class="literal">NO INHERIT</code> will not propagate to
+ child tables.
+ </p><p>
+ When a table has multiple <code class="literal">CHECK</code> constraints,
+ they will be tested for each row in alphabetical order by name,
+ after checking <code class="literal">NOT NULL</code> constraints.
+ (<span class="productname">PostgreSQL</span> versions before 9.5 did not honor any
+ particular firing order for <code class="literal">CHECK</code> constraints.)
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT
+ <em class="replaceable"><code>default_expr</code></em></code></span></dt><dd><p>
+ The <code class="literal">DEFAULT</code> clause assigns a default data value for
+ the column whose column definition it appears within. The value
+ is any variable-free expression (in particular, cross-references
+ to other columns in the current table are not allowed). Subqueries
+ are not allowed either. The data type of the default expression must
+ match the data type of the column.
+ </p><p>
+ The default expression will be used in any insert operation that
+ does not specify a value for the column. If there is no default
+ for a column, then the default is null.
+ </p></dd><dt><span class="term"><code class="literal">GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) STORED</code><a id="id-1.9.3.85.6.2.19.1.2" class="indexterm"></a></span></dt><dd><p>
+ This clause creates the column as a <em class="firstterm">generated
+ column</em>. The column cannot be written to, and when read the
+ result of the specified expression will be returned.
+ </p><p>
+ The keyword <code class="literal">STORED</code> is required to signify that the
+ column will be computed on write and will be stored on disk.
+ </p><p>
+ The generation expression can refer to other columns in the table, but
+ not other generated columns. Any functions and operators used must be
+ immutable. References to other tables are not allowed.
+ </p></dd><dt><span class="term"><code class="literal">GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <em class="replaceable"><code>sequence_options</code></em> ) ]</code></span></dt><dd><p>
+ This clause creates the column as an <em class="firstterm">identity
+ column</em>. It will have an implicit sequence attached to it
+ and the column in new rows will automatically have values from the
+ sequence assigned to it.
+ Such a column is implicitly <code class="literal">NOT NULL</code>.
+ </p><p>
+ The clauses <code class="literal">ALWAYS</code> and <code class="literal">BY DEFAULT</code>
+ determine how explicitly user-specified values are handled in
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> commands.
+ </p><p>
+ In an <code class="command">INSERT</code> command, if <code class="literal">ALWAYS</code> is
+ selected, a user-specified value is only accepted if the
+ <code class="command">INSERT</code> statement specifies <code class="literal">OVERRIDING SYSTEM
+ VALUE</code>. If <code class="literal">BY DEFAULT</code> is selected, then the
+ user-specified value takes precedence. See <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>
+ for details. (In the <code class="command">COPY</code> command, user-specified
+ values are always used regardless of this setting.)
+ </p><p>
+ In an <code class="command">UPDATE</code> command, if <code class="literal">ALWAYS</code> is
+ selected, any update of the column to any value other than
+ <code class="literal">DEFAULT</code> will be rejected. If <code class="literal">BY
+ DEFAULT</code> is selected, the column can be updated normally.
+ (There is no <code class="literal">OVERRIDING</code> clause for the
+ <code class="command">UPDATE</code> command.)
+ </p><p>
+ The optional <em class="replaceable"><code>sequence_options</code></em> clause can be
+ used to override the options of the sequence.
+ See <a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">UNIQUE [ NULLS [ NOT ] DISTINCT ]</code> (column constraint)<br /></span><span class="term"><code class="literal">UNIQUE [ NULLS [ NOT ] DISTINCT ] ( <em class="replaceable"><code>column_name</code></em> [, ... ] )</code>
+ [<span class="optional"> <code class="literal">INCLUDE ( <em class="replaceable"><code>column_name</code></em> [, ...])</code> </span>] (table constraint)</span></dt><dd><p>
+ The <code class="literal">UNIQUE</code> constraint specifies that a
+ group of one or more columns of a table can contain
+ only unique values. The behavior of a unique table constraint
+ is the same as that of a unique column constraint, with the
+ additional capability to span multiple columns. The constraint
+ therefore enforces that any two rows must differ in at least one
+ of these columns.
+ </p><p>
+ For the purpose of a unique constraint, null values are not
+ considered equal, unless <code class="literal">NULLS NOT DISTINCT</code> is
+ specified.
+ </p><p>
+ Each unique constraint should name a set of columns that is
+ different from the set of columns named by any other unique or
+ primary key constraint defined for the table. (Otherwise, redundant
+ unique constraints will be discarded.)
+ </p><p>
+ When establishing a unique constraint for a multi-level partition
+ hierarchy, all the columns in the partition key of the target
+ partitioned table, as well as those of all its descendant partitioned
+ tables, must be included in the constraint definition.
+ </p><p>
+ Adding a unique constraint will automatically create a unique btree
+ index on the column or group of columns used in the constraint.
+ </p><p>
+ The optional <code class="literal">INCLUDE</code> clause adds to that index
+ one or more columns that are simply <span class="quote">“<span class="quote">payload</span>”</span>: uniqueness
+ is not enforced on them, and the index cannot be searched on the basis
+ of those columns. However they can be retrieved by an index-only scan.
+ Note that although the constraint is not enforced on included columns,
+ it still depends on them. Consequently, some operations on such columns
+ (e.g., <code class="literal">DROP COLUMN</code>) can cause cascaded constraint and
+ index deletion.
+ </p></dd><dt><span class="term"><code class="literal">PRIMARY KEY</code> (column constraint)<br /></span><span class="term"><code class="literal">PRIMARY KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] )</code>
+ [<span class="optional"> <code class="literal">INCLUDE ( <em class="replaceable"><code>column_name</code></em> [, ...])</code> </span>] (table constraint)</span></dt><dd><p>
+ The <code class="literal">PRIMARY KEY</code> constraint specifies that a column or
+ columns of a table can contain only unique (non-duplicate), nonnull
+ values. Only one primary key can be specified for a table, whether as a
+ column constraint or a table constraint.
+ </p><p>
+ The primary key constraint should name a set of columns that is
+ different from the set of columns named by any unique
+ constraint defined for the same table. (Otherwise, the unique
+ constraint is redundant and will be discarded.)
+ </p><p>
+ <code class="literal">PRIMARY KEY</code> enforces the same data constraints as
+ a combination of <code class="literal">UNIQUE</code> and <code class="literal">NOT
+ NULL</code>. However,
+ identifying a set of columns as the primary key also provides metadata
+ about the design of the schema, since a primary key implies that other
+ tables can rely on this set of columns as a unique identifier for rows.
+ </p><p>
+ When placed on a partitioned table, <code class="literal">PRIMARY KEY</code>
+ constraints share the restrictions previously described
+ for <code class="literal">UNIQUE</code> constraints.
+ </p><p>
+ Adding a <code class="literal">PRIMARY KEY</code> constraint will automatically
+ create a unique btree index on the column or group of columns used in the
+ constraint.
+ </p><p>
+ The optional <code class="literal">INCLUDE</code> clause adds to that index
+ one or more columns that are simply <span class="quote">“<span class="quote">payload</span>”</span>: uniqueness
+ is not enforced on them, and the index cannot be searched on the basis
+ of those columns. However they can be retrieved by an index-only scan.
+ Note that although the constraint is not enforced on included columns,
+ it still depends on them. Consequently, some operations on such columns
+ (e.g., <code class="literal">DROP COLUMN</code>) can cause cascaded constraint and
+ index deletion.
+ </p></dd><dt id="SQL-CREATETABLE-EXCLUDE"><span class="term"><code class="literal">EXCLUDE [ USING <em class="replaceable"><code>index_method</code></em> ] ( <em class="replaceable"><code>exclude_element</code></em> WITH <em class="replaceable"><code>operator</code></em> [, ... ] ) <em class="replaceable"><code>index_parameters</code></em> [ WHERE ( <em class="replaceable"><code>predicate</code></em> ) ]</code></span></dt><dd><p>
+ The <code class="literal">EXCLUDE</code> clause defines an exclusion
+ constraint, which guarantees that if
+ any two rows are compared on the specified column(s) or
+ expression(s) using the specified operator(s), not all of these
+ comparisons will return <code class="literal">TRUE</code>. If all of the
+ specified operators test for equality, this is equivalent to a
+ <code class="literal">UNIQUE</code> constraint, although an ordinary unique constraint
+ will be faster. However, exclusion constraints can specify
+ constraints that are more general than simple equality.
+ For example, you can specify a constraint that
+ no two rows in the table contain overlapping circles
+ (see <a class="xref" href="datatype-geometric.html" title="8.8. Geometric Types">Section 8.8</a>) by using the
+ <code class="literal">&amp;&amp;</code> operator.
+ </p><p>
+ Exclusion constraints are implemented using
+ an index, so each specified operator must be associated with an
+ appropriate operator class
+ (see <a class="xref" href="indexes-opclass.html" title="11.10. Operator Classes and Operator Families">Section 11.10</a>) for the index access
+ method <em class="replaceable"><code>index_method</code></em>.
+ The operators are required to be commutative.
+ Each <em class="replaceable"><code>exclude_element</code></em>
+ can optionally specify an operator class and/or ordering options;
+ these are described fully under
+ <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>.
+ </p><p>
+ The access method must support <code class="literal">amgettuple</code> (see <a class="xref" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Chapter 64</a>); at present this means <acronym class="acronym">GIN</acronym>
+ cannot be used. Although it's allowed, there is little point in using
+ B-tree or hash indexes with an exclusion constraint, because this
+ does nothing that an ordinary unique constraint doesn't do better.
+ So in practice the access method will always be <acronym class="acronym">GiST</acronym> or
+ <acronym class="acronym">SP-GiST</acronym>.
+ </p><p>
+ The <em class="replaceable"><code>predicate</code></em> allows you to specify an
+ exclusion constraint on a subset of the table; internally this creates a
+ partial index. Note that parentheses are required around the predicate.
+ </p></dd><dt><span class="term"><code class="literal">REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> ) ] [ MATCH <em class="replaceable"><code>matchtype</code></em> ] [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ] [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ]</code> (column constraint)<br /></span><span class="term"><code class="literal">FOREIGN KEY ( <em class="replaceable"><code>column_name</code></em> [, ... ] )
+ REFERENCES <em class="replaceable"><code>reftable</code></em> [ ( <em class="replaceable"><code>refcolumn</code></em> [, ... ] ) ]
+ [ MATCH <em class="replaceable"><code>matchtype</code></em> ]
+ [ ON DELETE <em class="replaceable"><code>referential_action</code></em> ]
+ [ ON UPDATE <em class="replaceable"><code>referential_action</code></em> ]</code>
+ (table constraint)</span></dt><dd><p>
+ These clauses specify a foreign key constraint, which requires
+ that a group of one or more columns of the new table must only
+ contain values that match values in the referenced
+ column(s) of some row of the referenced table. If the <em class="replaceable"><code>refcolumn</code></em> list is omitted, the
+ primary key of the <em class="replaceable"><code>reftable</code></em>
+ is used. The referenced columns must be the columns of a non-deferrable
+ unique or primary key constraint in the referenced table. The user
+ must have <code class="literal">REFERENCES</code> permission on the referenced table
+ (either the whole table, or the specific referenced columns). The
+ addition of a foreign key constraint requires a
+ <code class="literal">SHARE ROW EXCLUSIVE</code> lock on the referenced table.
+ Note that foreign key constraints cannot be defined between temporary
+ tables and permanent tables.
+ </p><p>
+ A value inserted into the referencing column(s) is matched against the
+ values of the referenced table and referenced columns using the
+ given match type. There are three match types: <code class="literal">MATCH
+ FULL</code>, <code class="literal">MATCH PARTIAL</code>, and <code class="literal">MATCH
+ SIMPLE</code> (which is the default). <code class="literal">MATCH
+ FULL</code> will not allow one column of a multicolumn foreign key
+ to be null unless all foreign key columns are null; if they are all
+ null, the row is not required to have a match in the referenced table.
+ <code class="literal">MATCH SIMPLE</code> allows any of the foreign key columns
+ to be null; if any of them are null, the row is not required to have a
+ match in the referenced table.
+ <code class="literal">MATCH PARTIAL</code> is not yet implemented.
+ (Of course, <code class="literal">NOT NULL</code> constraints can be applied to the
+ referencing column(s) to prevent these cases from arising.)
+ </p><p>
+ In addition, when the data in the referenced columns is changed,
+ certain actions are performed on the data in this table's
+ columns. The <code class="literal">ON DELETE</code> clause specifies the
+ action to perform when a referenced row in the referenced table is
+ being deleted. Likewise, the <code class="literal">ON UPDATE</code>
+ clause specifies the action to perform when a referenced column
+ in the referenced table is being updated to a new value. If the
+ row is updated, but the referenced column is not actually
+ changed, no action is done. Referential actions other than the
+ <code class="literal">NO ACTION</code> check cannot be deferred, even if
+ the constraint is declared deferrable. There are the following possible
+ actions for each clause:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">NO ACTION</code></span></dt><dd><p>
+ Produce an error indicating that the deletion or update
+ would create a foreign key constraint violation.
+ If the constraint is deferred, this
+ error will be produced at constraint check time if there still
+ exist any referencing rows. This is the default action.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Produce an error indicating that the deletion or update
+ would create a foreign key constraint violation.
+ This is the same as <code class="literal">NO ACTION</code> except that
+ the check is not deferrable.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Delete any rows referencing the deleted row, or update the
+ values of the referencing column(s) to the new values of the
+ referenced columns, respectively.
+ </p></dd><dt><span class="term"><code class="literal">SET NULL [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ]</code></span></dt><dd><p>
+ Set all of the referencing columns, or a specified subset of the
+ referencing columns, to null. A subset of columns can only be
+ specified for <code class="literal">ON DELETE</code> actions.
+ </p></dd><dt><span class="term"><code class="literal">SET DEFAULT [ ( <em class="replaceable"><code>column_name</code></em> [, ... ] ) ]</code></span></dt><dd><p>
+ Set all of the referencing columns, or a specified subset of the
+ referencing columns, to their default values. A subset of columns
+ can only be specified for <code class="literal">ON DELETE</code> actions.
+ (There must be a row in the referenced table matching the default
+ values, if they are not null, or the operation will fail.)
+ </p></dd></dl></div><p>
+ </p><p>
+ If the referenced column(s) are changed frequently, it might be wise to
+ add an index to the referencing column(s) so that referential actions
+ associated with the foreign key constraint can be performed more
+ efficiently.
+ </p></dd><dt><span class="term"><code class="literal">DEFERRABLE</code><br /></span><span class="term"><code class="literal">NOT DEFERRABLE</code></span></dt><dd><p>
+ This controls whether the constraint can be deferred. A
+ constraint that is not deferrable will be checked immediately
+ after every command. Checking of constraints that are
+ deferrable can be postponed until the end of the transaction
+ (using the <a class="link" href="sql-set-constraints.html" title="SET CONSTRAINTS"><code class="command">SET CONSTRAINTS</code></a> command).
+ <code class="literal">NOT DEFERRABLE</code> is the default.
+ Currently, only <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>,
+ <code class="literal">EXCLUDE</code>, and
+ <code class="literal">REFERENCES</code> (foreign key) constraints accept this
+ clause. <code class="literal">NOT NULL</code> and <code class="literal">CHECK</code> constraints are not
+ deferrable. Note that deferrable constraints cannot be used as
+ conflict arbitrators in an <code class="command">INSERT</code> statement that
+ includes an <code class="literal">ON CONFLICT DO UPDATE</code> clause.
+ </p></dd><dt><span class="term"><code class="literal">INITIALLY IMMEDIATE</code><br /></span><span class="term"><code class="literal">INITIALLY DEFERRED</code></span></dt><dd><p>
+ If a constraint is deferrable, this clause specifies the default
+ time to check the constraint. If the constraint is
+ <code class="literal">INITIALLY IMMEDIATE</code>, it is checked after each
+ statement. This is the default. If the constraint is
+ <code class="literal">INITIALLY DEFERRED</code>, it is checked only at the
+ end of the transaction. The constraint check time can be
+ altered with the <a class="link" href="sql-set-constraints.html" title="SET CONSTRAINTS"><code class="command">SET CONSTRAINTS</code></a> command.
+ </p></dd><dt id="SQL-CREATETABLE-METHOD"><span class="term"><code class="literal">USING <em class="replaceable"><code>method</code></em></code></span></dt><dd><p>
+ This optional clause specifies the table access method to use to store
+ the contents for the new table; the method needs be an access method of
+ type <code class="literal">TABLE</code>. See <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> for more
+ information. If this option is not specified, the default table access
+ method is chosen for the new table. See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLE-ACCESS-METHOD">default_table_access_method</a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional storage parameters for a table or index;
+ see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a> below for more
+ information. For backward-compatibility the <code class="literal">WITH</code>
+ clause for a table can also include <code class="literal">OIDS=FALSE</code> to
+ specify that rows of the new table should not contain OIDs (object
+ identifiers), <code class="literal">OIDS=TRUE</code> is not supported anymore.
+ </p></dd><dt><span class="term"><code class="literal">WITHOUT OIDS</code></span></dt><dd><p>
+ This is backward-compatible syntax for declaring a table
+ <code class="literal">WITHOUT OIDS</code>, creating a table <code class="literal">WITH
+ OIDS</code> is not supported anymore.
+ </p></dd><dt><span class="term"><code class="literal">ON COMMIT</code></span></dt><dd><p>
+ The behavior of temporary tables at the end of a transaction
+ block can be controlled using <code class="literal">ON COMMIT</code>.
+ The three options are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PRESERVE ROWS</code></span></dt><dd><p>
+ No special action is taken at the ends of transactions.
+ This is the default behavior.
+ </p></dd><dt><span class="term"><code class="literal">DELETE ROWS</code></span></dt><dd><p>
+ All rows in the temporary table will be deleted at the end
+ of each transaction block. Essentially, an automatic <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a> is done
+ at each commit. When used on a partitioned table, this
+ is not cascaded to its partitions.
+ </p></dd><dt><span class="term"><code class="literal">DROP</code></span></dt><dd><p>
+ The temporary table will be dropped at the end of the current
+ transaction block. When used on a partitioned table, this action
+ drops its partitions and when used on tables with inheritance
+ children, it drops the dependent children.
+ </p></dd></dl></div></dd><dt id="SQL-CREATETABLE-TABLESPACE"><span class="term"><code class="literal">TABLESPACE <em class="replaceable"><code>tablespace_name</code></em></code></span></dt><dd><p>
+ The <em class="replaceable"><code>tablespace_name</code></em> is the name
+ of the tablespace in which the new table is to be created.
+ If not specified,
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> is consulted, or
+ <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> if the table is temporary. For
+ partitioned tables, since no storage is required for the table itself,
+ the tablespace specified overrides <code class="literal">default_tablespace</code>
+ as the default tablespace to use for any newly created partitions when no
+ other tablespace is explicitly specified.
+ </p></dd><dt><span class="term"><code class="literal">USING INDEX TABLESPACE <em class="replaceable"><code>tablespace_name</code></em></code></span></dt><dd><p>
+ This clause allows selection of the tablespace in which the index
+ associated with a <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY
+ KEY</code>, or <code class="literal">EXCLUDE</code> constraint will be created.
+ If not specified,
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> is consulted, or
+ <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> if the table is temporary.
+ </p></dd></dl></div><div class="refsect2" id="SQL-CREATETABLE-STORAGE-PARAMETERS"><h3>Storage Parameters</h3><a id="id-1.9.3.85.6.3.2" class="indexterm"></a><p>
+ The <code class="literal">WITH</code> clause can specify <em class="firstterm">storage parameters</em>
+ for tables, and for indexes associated with a <code class="literal">UNIQUE</code>,
+ <code class="literal">PRIMARY KEY</code>, or <code class="literal">EXCLUDE</code> constraint.
+ Storage parameters for
+ indexes are documented in <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>.
+ The storage parameters currently
+ available for tables are listed below. For many of these parameters, as
+ shown, there is an additional parameter with the same name prefixed with
+ <code class="literal">toast.</code>, which controls the behavior of the
+ table's secondary <acronym class="acronym">TOAST</acronym> table, if any
+ (see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a> for more information about TOAST).
+ If a table parameter value is set and the
+ equivalent <code class="literal">toast.</code> parameter is not, the TOAST table
+ will use the table's parameter value.
+ Specifying these parameters for partitioned tables is not supported,
+ but you may specify them for individual leaf partitions.
+ </p><div class="variablelist"><dl class="variablelist"><dt id="RELOPTION-FILLFACTOR"><span class="term"><code class="varname">fillfactor</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.1.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The fillfactor for a table is a percentage between 10 and 100.
+ 100 (complete packing) is the default. When a smaller fillfactor
+ is specified, <code class="command">INSERT</code> operations pack table pages only
+ to the indicated percentage; the remaining space on each page is
+ reserved for updating rows on that page. This gives <code class="command">UPDATE</code>
+ a chance to place the updated copy of a row on the same page as the
+ original, which is more efficient than placing it on a different
+ page, and makes <a class="link" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">heap-only tuple
+ updates</a> more likely.
+ For a table whose entries are never updated, complete packing is the
+ best choice, but in heavily updated tables smaller fillfactors are
+ appropriate. This parameter cannot be set for TOAST tables.
+ </p></dd><dt id="RELOPTION-TOAST-TUPLE-TARGET"><span class="term"><code class="literal">toast_tuple_target</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.2.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ The toast_tuple_target specifies the minimum tuple length required before
+ we try to compress and/or move long column values into TOAST tables, and
+ is also the target length we try to reduce the length below once toasting
+ begins. This affects columns marked as External (for move),
+ Main (for compression), or Extended (for both) and applies only to new
+ tuples. There is no effect on existing rows.
+ By default this parameter is set to allow at least 4 tuples per block,
+ which with the default block size will be 2040 bytes. Valid values are
+ between 128 bytes and the (block size - header), by default 8160 bytes.
+ Changing this value may not be useful for very short or very long rows.
+ Note that the default setting is often close to optimal, and
+ it is possible that setting this parameter could have negative
+ effects in some cases.
+ This parameter cannot be set for TOAST tables.
+ </p></dd><dt id="RELOPTION-PARALLEL-WORKERS"><span class="term"><code class="literal">parallel_workers</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.3.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This sets the number of workers that should be used to assist a parallel
+ scan of this table. If not set, the system will determine a value based
+ on the relation size. The actual number of workers chosen by the planner
+ or by utility statements that use parallel scans may be less, for example
+ due to the setting of <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-ENABLED"><span class="term"><code class="literal">autovacuum_enabled</code>, <code class="literal">toast.autovacuum_enabled</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.85.6.3.4.4.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables the autovacuum daemon for a particular table.
+ If true, the autovacuum daemon will perform automatic <code class="command">VACUUM</code>
+ and/or <code class="command">ANALYZE</code> operations on this table following the rules
+ discussed in <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>.
+ If false, this table will not be autovacuumed, except to prevent
+ transaction ID wraparound. See <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a> for
+ more about wraparound prevention.
+ Note that the autovacuum daemon does not run at all (except to prevent
+ transaction ID wraparound) if the <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM">autovacuum</a>
+ parameter is false; setting individual tables' storage parameters does
+ not override that. Therefore there is seldom much point in explicitly
+ setting this storage parameter to <code class="literal">true</code>, only
+ to <code class="literal">false</code>.
+ </p></dd><dt id="RELOPTION-VACUUM-INDEX-CLEANUP"><span class="term"><code class="literal">vacuum_index_cleanup</code>, <code class="literal">toast.vacuum_index_cleanup</code> (<code class="type">enum</code>)
+ <a id="id-1.9.3.85.6.3.4.5.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Forces or disables index cleanup when <code class="command">VACUUM</code>
+ is run on this table. The default value is
+ <code class="literal">AUTO</code>. With <code class="literal">OFF</code>, index
+ cleanup is disabled, with <code class="literal">ON</code> it is enabled,
+ and with <code class="literal">AUTO</code> a decision is made dynamically,
+ each time <code class="command">VACUUM</code> runs. The dynamic behavior
+ allows <code class="command">VACUUM</code> to avoid needlessly scanning
+ indexes to remove very few dead tuples. Forcibly disabling all
+ index cleanup can speed up <code class="command">VACUUM</code> very
+ significantly, but may also lead to severely bloated indexes if
+ table modifications are frequent. The
+ <code class="literal">INDEX_CLEANUP</code> parameter of <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>, if
+ specified, overrides the value of this option.
+ </p></dd><dt id="RELOPTION-VACUUM-TRUNCATE"><span class="term"><code class="literal">vacuum_truncate</code>, <code class="literal">toast.vacuum_truncate</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.85.6.3.4.6.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Enables or disables vacuum to try to truncate off any empty pages
+ at the end of this table. The default value is <code class="literal">true</code>.
+ If <code class="literal">true</code>, <code class="command">VACUUM</code> and
+ autovacuum do the truncation and the disk space for
+ the truncated pages is returned to the operating system.
+ Note that the truncation requires <code class="literal">ACCESS EXCLUSIVE</code>
+ lock on the table. The <code class="literal">TRUNCATE</code> parameter
+ of <a class="link" href="sql-vacuum.html" title="VACUUM"><code class="command">VACUUM</code></a>, if specified, overrides the value
+ of this option.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-THRESHOLD"><span class="term"><code class="literal">autovacuum_vacuum_threshold</code>, <code class="literal">toast.autovacuum_vacuum_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.7.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-THRESHOLD">autovacuum_vacuum_threshold</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-SCALE-FACTOR"><span class="term"><code class="literal">autovacuum_vacuum_scale_factor</code>, <code class="literal">toast.autovacuum_vacuum_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.9.3.85.6.3.4.8.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-SCALE-FACTOR">autovacuum_vacuum_scale_factor</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-INSERT-THRESHOLD"><span class="term"><code class="literal">autovacuum_vacuum_insert_threshold</code>, <code class="literal">toast.autovacuum_vacuum_insert_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.9.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-INSERT-THRESHOLD">autovacuum_vacuum_insert_threshold</a>
+ parameter. The special value of -1 may be used to disable insert vacuums on the table.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-INSERT-SCALE-FACTOR"><span class="term"><code class="literal">autovacuum_vacuum_insert_scale_factor</code>, <code class="literal">toast.autovacuum_vacuum_insert_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.9.3.85.6.3.4.10.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-INSERT-SCALE-FACTOR">autovacuum_vacuum_insert_scale_factor</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-ANALYZE-THRESHOLD"><span class="term"><code class="literal">autovacuum_analyze_threshold</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.11.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-ANALYZE-THRESHOLD">autovacuum_analyze_threshold</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-ANALYZE-SCALE-FACTOR"><span class="term"><code class="literal">autovacuum_analyze_scale_factor</code> (<code class="type">floating point</code>)
+ <a id="id-1.9.3.85.6.3.4.12.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-ANALYZE-SCALE-FACTOR">autovacuum_analyze_scale_factor</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-COST-DELAY"><span class="term"><code class="literal">autovacuum_vacuum_cost_delay</code>, <code class="literal">toast.autovacuum_vacuum_cost_delay</code> (<code class="type">floating point</code>)
+ <a id="id-1.9.3.85.6.3.4.13.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-COST-DELAY">autovacuum_vacuum_cost_delay</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-VACUUM-COST-LIMIT"><span class="term"><code class="literal">autovacuum_vacuum_cost_limit</code>, <code class="literal">toast.autovacuum_vacuum_cost_limit</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.14.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-VACUUM-COST-LIMIT">autovacuum_vacuum_cost_limit</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-FREEZE-MIN-AGE"><span class="term"><code class="literal">autovacuum_freeze_min_age</code>, <code class="literal">toast.autovacuum_freeze_min_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.15.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-MIN-AGE">vacuum_freeze_min_age</a>
+ parameter. Note that autovacuum will ignore
+ per-table <code class="literal">autovacuum_freeze_min_age</code> parameters that are
+ larger than half the
+ system-wide <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a> setting.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-FREEZE-MAX-AGE"><span class="term"><code class="literal">autovacuum_freeze_max_age</code>, <code class="literal">toast.autovacuum_freeze_max_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.16.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-FREEZE-MAX-AGE">autovacuum_freeze_max_age</a>
+ parameter. Note that autovacuum will ignore
+ per-table <code class="literal">autovacuum_freeze_max_age</code> parameters that are
+ larger than the system-wide setting (it can only be set smaller).
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-FREEZE-TABLE-AGE"><span class="term"><code class="literal">autovacuum_freeze_table_age</code>, <code class="literal">toast.autovacuum_freeze_table_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.17.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-TABLE-AGE">vacuum_freeze_table_age</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-MULTIXACT-FREEZE-MIN-AGE"><span class="term"><code class="literal">autovacuum_multixact_freeze_min_age</code>, <code class="literal">toast.autovacuum_multixact_freeze_min_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.18.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-client.html#GUC-VACUUM-MULTIXACT-FREEZE-MIN-AGE">vacuum_multixact_freeze_min_age</a>
+ parameter. Note that autovacuum will ignore
+ per-table <code class="literal">autovacuum_multixact_freeze_min_age</code> parameters
+ that are larger than half the
+ system-wide <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a>
+ setting.
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE"><span class="term"><code class="literal">autovacuum_multixact_freeze_max_age</code>, <code class="literal">toast.autovacuum_multixact_freeze_max_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.19.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value
+ for <a class="xref" href="runtime-config-autovacuum.html#GUC-AUTOVACUUM-MULTIXACT-FREEZE-MAX-AGE">autovacuum_multixact_freeze_max_age</a> parameter.
+ Note that autovacuum will ignore
+ per-table <code class="literal">autovacuum_multixact_freeze_max_age</code> parameters
+ that are larger than the system-wide setting (it can only be set
+ smaller).
+ </p></dd><dt id="RELOPTION-AUTOVACUUM-MULTIXACT-FREEZE-TABLE-AGE"><span class="term"><code class="literal">autovacuum_multixact_freeze_table_age</code>, <code class="literal">toast.autovacuum_multixact_freeze_table_age</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.20.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value
+ for <a class="xref" href="runtime-config-client.html#GUC-VACUUM-MULTIXACT-FREEZE-TABLE-AGE">vacuum_multixact_freeze_table_age</a> parameter.
+ </p></dd><dt id="RELOPTION-LOG-AUTOVACUUM-MIN-DURATION"><span class="term"><code class="literal">log_autovacuum_min_duration</code>, <code class="literal">toast.log_autovacuum_min_duration</code> (<code class="type">integer</code>)
+ <a id="id-1.9.3.85.6.3.4.21.1.4" class="indexterm"></a>
+ </span></dt><dd><p>
+ Per-table value for <a class="xref" href="runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION">log_autovacuum_min_duration</a>
+ parameter.
+ </p></dd><dt id="RELOPTION-USER-CATALOG-TABLE"><span class="term"><code class="literal">user_catalog_table</code> (<code class="type">boolean</code>)
+ <a id="id-1.9.3.85.6.3.4.22.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ Declare the table as an additional catalog table for purposes of
+ logical replication. See
+ <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES" title="49.6.2. Capabilities">Section 49.6.2</a> for details.
+ This parameter cannot be set for TOAST tables.
+ </p></dd></dl></div></div></div><div class="refsect1" id="SQL-CREATETABLE-NOTES"><h2>Notes</h2><p>
+ <span class="productname">PostgreSQL</span> automatically creates an
+ index for each unique constraint and primary key constraint to
+ enforce uniqueness. Thus, it is not necessary to create an
+ index explicitly for primary key columns. (See <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a> for more information.)
+ </p><p>
+ Unique constraints and primary keys are not inherited in the
+ current implementation. This makes the combination of
+ inheritance and unique constraints rather dysfunctional.
+ </p><p>
+ A table cannot have more than 1600 columns. (In practice, the
+ effective limit is usually lower because of tuple-length constraints.)
+ </p></div><div class="refsect1" id="SQL-CREATETABLE-EXAMPLES"><h2>Examples</h2><p>
+ Create table <code class="structname">films</code> and table
+ <code class="structname">distributors</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE films (
+ code char(5) CONSTRAINT firstkey PRIMARY KEY,
+ title varchar(40) NOT NULL,
+ did integer NOT NULL,
+ date_prod date,
+ kind varchar(10),
+ len interval hour to minute
+);
+
+CREATE TABLE distributors (
+ did integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
+ name varchar(40) NOT NULL CHECK (name &lt;&gt; '')
+);
+</pre><p>
+ </p><p>
+ Create a table with a 2-dimensional array:
+
+</p><pre class="programlisting">
+CREATE TABLE array_int (
+ vector int[][]
+);
+</pre><p>
+ </p><p>
+ Define a unique table constraint for the table
+ <code class="literal">films</code>. Unique table constraints can be defined
+ on one or more columns of the table:
+
+</p><pre class="programlisting">
+CREATE TABLE films (
+ code char(5),
+ title varchar(40),
+ did integer,
+ date_prod date,
+ kind varchar(10),
+ len interval hour to minute,
+ CONSTRAINT production UNIQUE(date_prod)
+);
+</pre><p>
+ </p><p>
+ Define a check column constraint:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer CHECK (did &gt; 100),
+ name varchar(40)
+);
+</pre><p>
+ </p><p>
+ Define a check table constraint:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer,
+ name varchar(40),
+ CONSTRAINT con1 CHECK (did &gt; 100 AND name &lt;&gt; '')
+);
+</pre><p>
+ </p><p>
+ Define a primary key table constraint for the table
+ <code class="structname">films</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE films (
+ code char(5),
+ title varchar(40),
+ did integer,
+ date_prod date,
+ kind varchar(10),
+ len interval hour to minute,
+ CONSTRAINT code_title PRIMARY KEY(code,title)
+);
+</pre><p>
+ </p><p>
+ Define a primary key constraint for table
+ <code class="structname">distributors</code>. The following two examples are
+ equivalent, the first using the table constraint syntax, the second
+ the column constraint syntax:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer,
+ name varchar(40),
+ PRIMARY KEY(did)
+);
+
+CREATE TABLE distributors (
+ did integer PRIMARY KEY,
+ name varchar(40)
+);
+</pre><p>
+ </p><p>
+ Assign a literal constant default value for the column
+ <code class="literal">name</code>, arrange for the default value of column
+ <code class="literal">did</code> to be generated by selecting the next value
+ of a sequence object, and make the default value of
+ <code class="literal">modtime</code> be the time at which the row is
+ inserted:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ name varchar(40) DEFAULT 'Luso Films',
+ did integer DEFAULT nextval('distributors_serial'),
+ modtime timestamp DEFAULT current_timestamp
+);
+</pre><p>
+ </p><p>
+ Define two <code class="literal">NOT NULL</code> column constraints on the table
+ <code class="classname">distributors</code>, one of which is explicitly
+ given a name:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer CONSTRAINT no_null NOT NULL,
+ name varchar(40) NOT NULL
+);
+</pre><p>
+ </p><p>
+ Define a unique constraint for the <code class="literal">name</code> column:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer,
+ name varchar(40) UNIQUE
+);
+</pre><p>
+
+ The same, specified as a table constraint:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer,
+ name varchar(40),
+ UNIQUE(name)
+);
+</pre><p>
+ </p><p>
+ Create the same table, specifying 70% fill factor for both the table
+ and its unique index:
+
+</p><pre class="programlisting">
+CREATE TABLE distributors (
+ did integer,
+ name varchar(40),
+ UNIQUE(name) WITH (fillfactor=70)
+)
+WITH (fillfactor=70);
+</pre><p>
+ </p><p>
+ Create table <code class="structname">circles</code> with an exclusion
+ constraint that prevents any two circles from overlapping:
+
+</p><pre class="programlisting">
+CREATE TABLE circles (
+ c circle,
+ EXCLUDE USING gist (c WITH &amp;&amp;)
+);
+</pre><p>
+ </p><p>
+ Create table <code class="structname">cinemas</code> in tablespace <code class="structname">diskvol1</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE cinemas (
+ id serial,
+ name text,
+ location text
+) TABLESPACE diskvol1;
+</pre><p>
+ </p><p>
+ Create a composite type and a typed table:
+</p><pre class="programlisting">
+CREATE TYPE employee_type AS (name text, salary numeric);
+
+CREATE TABLE employees OF employee_type (
+ PRIMARY KEY (name),
+ salary WITH OPTIONS DEFAULT 1000
+);
+</pre><p>
+ Create a range partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE measurement (
+ logdate date not null,
+ peaktemp int,
+ unitsales int
+) PARTITION BY RANGE (logdate);
+</pre><p>
+ Create a range partitioned table with multiple columns in the partition key:
+</p><pre class="programlisting">
+CREATE TABLE measurement_year_month (
+ logdate date not null,
+ peaktemp int,
+ unitsales int
+) PARTITION BY RANGE (EXTRACT(YEAR FROM logdate), EXTRACT(MONTH FROM logdate));
+</pre><p>
+ Create a list partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE cities (
+ city_id bigserial not null,
+ name text not null,
+ population bigint
+) PARTITION BY LIST (left(lower(name), 1));
+</pre><p>
+ Create a hash partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE orders (
+ order_id bigint not null,
+ cust_id bigint not null,
+ status text
+) PARTITION BY HASH (order_id);
+</pre><p>
+ Create partition of a range partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE measurement_y2016m07
+ PARTITION OF measurement (
+ unitsales DEFAULT 0
+) FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
+</pre><p>
+ Create a few partitions of a range partitioned table with multiple
+ columns in the partition key:
+</p><pre class="programlisting">
+CREATE TABLE measurement_ym_older
+ PARTITION OF measurement_year_month
+ FOR VALUES FROM (MINVALUE, MINVALUE) TO (2016, 11);
+
+CREATE TABLE measurement_ym_y2016m11
+ PARTITION OF measurement_year_month
+ FOR VALUES FROM (2016, 11) TO (2016, 12);
+
+CREATE TABLE measurement_ym_y2016m12
+ PARTITION OF measurement_year_month
+ FOR VALUES FROM (2016, 12) TO (2017, 01);
+
+CREATE TABLE measurement_ym_y2017m01
+ PARTITION OF measurement_year_month
+ FOR VALUES FROM (2017, 01) TO (2017, 02);
+</pre><p>
+ Create partition of a list partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE cities_ab
+ PARTITION OF cities (
+ CONSTRAINT city_id_nonzero CHECK (city_id != 0)
+) FOR VALUES IN ('a', 'b');
+</pre><p>
+ Create partition of a list partitioned table that is itself further
+ partitioned and then add a partition to it:
+</p><pre class="programlisting">
+CREATE TABLE cities_ab
+ PARTITION OF cities (
+ CONSTRAINT city_id_nonzero CHECK (city_id != 0)
+) FOR VALUES IN ('a', 'b') PARTITION BY RANGE (population);
+
+CREATE TABLE cities_ab_10000_to_100000
+ PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000);
+</pre><p>
+ Create partitions of a hash partitioned table:
+</p><pre class="programlisting">
+CREATE TABLE orders_p1 PARTITION OF orders
+ FOR VALUES WITH (MODULUS 4, REMAINDER 0);
+CREATE TABLE orders_p2 PARTITION OF orders
+ FOR VALUES WITH (MODULUS 4, REMAINDER 1);
+CREATE TABLE orders_p3 PARTITION OF orders
+ FOR VALUES WITH (MODULUS 4, REMAINDER 2);
+CREATE TABLE orders_p4 PARTITION OF orders
+ FOR VALUES WITH (MODULUS 4, REMAINDER 3);
+</pre><p>
+ Create a default partition:
+</p><pre class="programlisting">
+CREATE TABLE cities_partdef
+ PARTITION OF cities DEFAULT;
+</pre></div><div class="refsect1" id="SQL-CREATETABLE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE TABLE</code> command conforms to the
+ <acronym class="acronym">SQL</acronym> standard, with exceptions listed below.
+ </p><div class="refsect2" id="id-1.9.3.85.9.3"><h3>Temporary Tables</h3><p>
+ Although the syntax of <code class="literal">CREATE TEMPORARY TABLE</code>
+ resembles that of the SQL standard, the effect is not the same. In the
+ standard,
+ temporary tables are defined just once and automatically exist (starting
+ with empty contents) in every session that needs them.
+ <span class="productname">PostgreSQL</span> instead
+ requires each session to issue its own <code class="literal">CREATE TEMPORARY
+ TABLE</code> command for each temporary table to be used. This allows
+ different sessions to use the same temporary table name for different
+ purposes, whereas the standard's approach constrains all instances of a
+ given temporary table name to have the same table structure.
+ </p><p>
+ The standard's definition of the behavior of temporary tables is
+ widely ignored. <span class="productname">PostgreSQL</span>'s behavior
+ on this point is similar to that of several other SQL databases.
+ </p><p>
+ The SQL standard also distinguishes between global and local temporary
+ tables, where a local temporary table has a separate set of contents for
+ each SQL module within each session, though its definition is still shared
+ across sessions. Since <span class="productname">PostgreSQL</span> does not
+ support SQL modules, this distinction is not relevant in
+ <span class="productname">PostgreSQL</span>.
+ </p><p>
+ For compatibility's sake, <span class="productname">PostgreSQL</span> will
+ accept the <code class="literal">GLOBAL</code> and <code class="literal">LOCAL</code> keywords
+ in a temporary table declaration, but they currently have no effect.
+ Use of these keywords is discouraged, since future versions of
+ <span class="productname">PostgreSQL</span> might adopt a more
+ standard-compliant interpretation of their meaning.
+ </p><p>
+ The <code class="literal">ON COMMIT</code> clause for temporary tables
+ also resembles the SQL standard, but has some differences.
+ If the <code class="literal">ON COMMIT</code> clause is omitted, SQL specifies that the
+ default behavior is <code class="literal">ON COMMIT DELETE ROWS</code>. However, the
+ default behavior in <span class="productname">PostgreSQL</span> is
+ <code class="literal">ON COMMIT PRESERVE ROWS</code>. The <code class="literal">ON COMMIT
+ DROP</code> option does not exist in SQL.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.4"><h3>Non-Deferred Uniqueness Constraints</h3><p>
+ When a <code class="literal">UNIQUE</code> or <code class="literal">PRIMARY KEY</code> constraint is
+ not deferrable, <span class="productname">PostgreSQL</span> checks for
+ uniqueness immediately whenever a row is inserted or modified.
+ The SQL standard says that uniqueness should be enforced only at
+ the end of the statement; this makes a difference when, for example,
+ a single command updates multiple key values. To obtain
+ standard-compliant behavior, declare the constraint as
+ <code class="literal">DEFERRABLE</code> but not deferred (i.e., <code class="literal">INITIALLY
+ IMMEDIATE</code>). Be aware that this can be significantly slower than
+ immediate uniqueness checking.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.5"><h3>Column Check Constraints</h3><p>
+ The SQL standard says that <code class="literal">CHECK</code> column constraints
+ can only refer to the column they apply to; only <code class="literal">CHECK</code>
+ table constraints can refer to multiple columns.
+ <span class="productname">PostgreSQL</span> does not enforce this
+ restriction; it treats column and table check constraints alike.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.6"><h3><code class="literal">EXCLUDE</code> Constraint</h3><p>
+ The <code class="literal">EXCLUDE</code> constraint type is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.7"><h3>Foreign-Key Constraint Actions</h3><p>
+ The ability to specify column lists in the foreign-key actions
+ <code class="literal">SET DEFAULT</code> and <code class="literal">SET NULL</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.8"><h3><code class="literal">NULL</code> <span class="quote">“<span class="quote">Constraint</span>”</span></h3><p>
+ The <code class="literal">NULL</code> <span class="quote">“<span class="quote">constraint</span>”</span> (actually a
+ non-constraint) is a <span class="productname">PostgreSQL</span>
+ extension to the SQL standard that is included for compatibility with some
+ other database systems (and for symmetry with the <code class="literal">NOT
+ NULL</code> constraint). Since it is the default for any
+ column, its presence is simply noise.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.9"><h3>Constraint Naming</h3><p>
+ The SQL standard says that table and domain constraints must have names
+ that are unique across the schema containing the table or domain.
+ <span class="productname">PostgreSQL</span> is laxer: it only requires
+ constraint names to be unique across the constraints attached to a
+ particular table or domain. However, this extra freedom does not exist
+ for index-based constraints (<code class="literal">UNIQUE</code>,
+ <code class="literal">PRIMARY KEY</code>, and <code class="literal">EXCLUDE</code>
+ constraints), because the associated index is named the same as the
+ constraint, and index names must be unique across all relations within
+ the same schema.
+ </p><p>
+ Currently, <span class="productname">PostgreSQL</span> does not record names
+ for <code class="literal">NOT NULL</code> constraints at all, so they are not
+ subject to the uniqueness restriction. This might change in a future
+ release.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.10"><h3>Inheritance</h3><p>
+ Multiple inheritance via the <code class="literal">INHERITS</code> clause is
+ a <span class="productname">PostgreSQL</span> language extension.
+ SQL:1999 and later define single inheritance using a
+ different syntax and different semantics. SQL:1999-style
+ inheritance is not yet supported by
+ <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.11"><h3>Zero-Column Tables</h3><p>
+ <span class="productname">PostgreSQL</span> allows a table of no columns
+ to be created (for example, <code class="literal">CREATE TABLE foo();</code>). This
+ is an extension from the SQL standard, which does not allow zero-column
+ tables. Zero-column tables are not in themselves very useful, but
+ disallowing them creates odd special cases for <code class="command">ALTER TABLE
+ DROP COLUMN</code>, so it seems cleaner to ignore this spec restriction.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.12"><h3>Multiple Identity Columns</h3><p>
+ <span class="productname">PostgreSQL</span> allows a table to have more than one
+ identity column. The standard specifies that a table can have at most one
+ identity column. This is relaxed mainly to give more flexibility for
+ doing schema changes or migrations. Note that
+ the <code class="command">INSERT</code> command supports only one override clause
+ that applies to the entire statement, so having multiple identity columns
+ with different behaviors is not well supported.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.13"><h3>Generated Columns</h3><p>
+ The option <code class="literal">STORED</code> is not standard but is also used by
+ other SQL implementations. The SQL standard does not specify the storage
+ of generated columns.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.14"><h3><code class="literal">LIKE</code> Clause</h3><p>
+ While a <code class="literal">LIKE</code> clause exists in the SQL standard, many of the
+ options that <span class="productname">PostgreSQL</span> accepts for it are not
+ in the standard, and some of the standard's options are not implemented
+ by <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.15"><h3><code class="literal">WITH</code> Clause</h3><p>
+ The <code class="literal">WITH</code> clause is a <span class="productname">PostgreSQL</span>
+ extension; storage parameters are not in the standard.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.16"><h3>Tablespaces</h3><p>
+ The <span class="productname">PostgreSQL</span> concept of tablespaces is not
+ part of the standard. Hence, the clauses <code class="literal">TABLESPACE</code>
+ and <code class="literal">USING INDEX TABLESPACE</code> are extensions.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.17"><h3>Typed Tables</h3><p>
+ Typed tables implement a subset of the SQL standard. According to
+ the standard, a typed table has columns corresponding to the
+ underlying composite type as well as one other column that is
+ the <span class="quote">“<span class="quote">self-referencing column</span>”</span>.
+ <span class="productname">PostgreSQL</span> does not support self-referencing
+ columns explicitly.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.18"><h3><code class="literal">PARTITION BY</code> Clause</h3><p>
+ The <code class="literal">PARTITION BY</code> clause is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect2" id="id-1.9.3.85.9.19"><h3><code class="literal">PARTITION OF</code> Clause</h3><p>
+ The <code class="literal">PARTITION OF</code> clause is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div></div><div class="refsect1" id="id-1.9.3.85.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>, <a class="xref" href="sql-droptable.html" title="DROP TABLE"><span class="refentrytitle">DROP TABLE</span></a>, <a class="xref" href="sql-createtableas.html" title="CREATE TABLE AS"><span class="refentrytitle">CREATE TABLE AS</span></a>, <a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>, <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtableas.html" title="CREATE TABLE AS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE SUBSCRIPTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TABLE AS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtableas.html b/doc/src/sgml/html/sql-createtableas.html
new file mode 100644
index 0000000..ccd08bd
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtableas.html
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TABLE AS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtable.html" title="CREATE TABLE" /><link rel="next" href="sql-createtablespace.html" title="CREATE TABLESPACE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TABLE AS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtable.html" title="CREATE TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtablespace.html" title="CREATE TABLESPACE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETABLEAS"><div class="titlepage"></div><a id="id-1.9.3.86.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TABLE AS</span></h2><p>CREATE TABLE AS — define a new table from the results of a query</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
+ [ (<em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ [ USING <em class="replaceable"><code>method</code></em> ]
+ [ WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] ) | WITHOUT OIDS ]
+ [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
+ [ TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> ]
+ AS <em class="replaceable"><code>query</code></em>
+ [ WITH [ NO ] DATA ]
+</pre></div><div class="refsect1" id="id-1.9.3.86.5"><h2>Description</h2><p>
+ <code class="command">CREATE TABLE AS</code> creates a table and fills it
+ with data computed by a <code class="command">SELECT</code> command.
+ The table columns have the
+ names and data types associated with the output columns of the
+ <code class="command">SELECT</code> (except that you can override the column
+ names by giving an explicit list of new column names).
+ </p><p>
+ <code class="command">CREATE TABLE AS</code> bears some resemblance to
+ creating a view, but it is really quite different: it creates a new
+ table and evaluates the query just once to fill the new table
+ initially. The new table will not track subsequent changes to the
+ source tables of the query. In contrast, a view re-evaluates its
+ defining <code class="command">SELECT</code> statement whenever it is
+ queried.
+ </p><p>
+ <code class="command">CREATE TABLE AS</code> requires <code class="literal">CREATE</code>
+ privilege on the schema used for the table.
+ </p></div><div class="refsect1" id="id-1.9.3.86.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">GLOBAL</code> or <code class="literal">LOCAL</code></span></dt><dd><p>
+ Ignored for compatibility. Use of these keywords is deprecated;
+ refer to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for details.
+ </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ If specified, the table is created as a temporary table.
+ Refer to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">UNLOGGED</code></span></dt><dd><p>
+ If specified, the table is created as an unlogged table.
+ Refer to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a relation with the same name already
+ exists; simply issue a notice and leave the table unmodified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column in the new table. If column names are not
+ provided, they are taken from the output column names of the query.
+ </p></dd><dt><span class="term"><code class="literal">USING <em class="replaceable"><code>method</code></em></code></span></dt><dd><p>
+ This optional clause specifies the table access method to use to store
+ the contents for the new table; the method needs be an access method of
+ type <code class="literal">TABLE</code>. See <a class="xref" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">Chapter 63</a> for more
+ information. If this option is not specified, the default table access
+ method is chosen for the new table. See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLE-ACCESS-METHOD">default_table_access_method</a> for more information.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>storage_parameter</code></em> [= <em class="replaceable"><code>value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional storage parameters for the new table;
+ see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS" title="Storage Parameters">Storage Parameters</a> in the
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> documentation for more
+ information. For backward-compatibility the <code class="literal">WITH</code>
+ clause for a table can also include <code class="literal">OIDS=FALSE</code> to
+ specify that rows of the new table should contain no OIDs (object
+ identifiers), <code class="literal">OIDS=TRUE</code> is not supported anymore.
+ </p></dd><dt><span class="term"><code class="literal">WITHOUT OIDS</code></span></dt><dd><p>
+ This is backward-compatible syntax for declaring a table
+ <code class="literal">WITHOUT OIDS</code>, creating a table <code class="literal">WITH
+ OIDS</code> is not supported anymore.
+ </p></dd><dt><span class="term"><code class="literal">ON COMMIT</code></span></dt><dd><p>
+ The behavior of temporary tables at the end of a transaction
+ block can be controlled using <code class="literal">ON COMMIT</code>.
+ The three options are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PRESERVE ROWS</code></span></dt><dd><p>
+ No special action is taken at the ends of transactions.
+ This is the default behavior.
+ </p></dd><dt><span class="term"><code class="literal">DELETE ROWS</code></span></dt><dd><p>
+ All rows in the temporary table will be deleted at the end
+ of each transaction block. Essentially, an automatic <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a> is done
+ at each commit.
+ </p></dd><dt><span class="term"><code class="literal">DROP</code></span></dt><dd><p>
+ The temporary table will be dropped at the end of the current
+ transaction block.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="literal">TABLESPACE <em class="replaceable"><code>tablespace_name</code></em></code></span></dt><dd><p>
+ The <em class="replaceable"><code>tablespace_name</code></em> is the name
+ of the tablespace in which the new table is to be created.
+ If not specified,
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLESPACE">default_tablespace</a> is consulted, or
+ <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> if the table is temporary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a>, <a class="link" href="sql-select.html#SQL-TABLE" title="TABLE Command"><code class="command">TABLE</code></a>, or <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a>
+ command, or an <a class="link" href="sql-execute.html" title="EXECUTE"><code class="command">EXECUTE</code></a> command that runs a
+ prepared <code class="command">SELECT</code>, <code class="command">TABLE</code>, or
+ <code class="command">VALUES</code> query.
+ </p></dd><dt><span class="term"><code class="literal">WITH [ NO ] DATA</code></span></dt><dd><p>
+ This clause specifies whether or not the data produced by the query
+ should be copied into the new table. If not, only the table structure
+ is copied. The default is to copy the data.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.86.7"><h2>Notes</h2><p>
+ This command is functionally similar to <a class="xref" href="sql-selectinto.html" title="SELECT INTO"><span class="refentrytitle">SELECT INTO</span></a>, but it is
+ preferred since it is less likely to be confused with other uses of
+ the <code class="command">SELECT INTO</code> syntax. Furthermore, <code class="command">CREATE
+ TABLE AS</code> offers a superset of the functionality offered
+ by <code class="command">SELECT INTO</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.86.8"><h2>Examples</h2><p>
+ Create a new table <code class="literal">films_recent</code> consisting of only
+ recent entries from the table <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+CREATE TABLE films_recent AS
+ SELECT * FROM films WHERE date_prod &gt;= '2002-01-01';
+</pre><p>
+ </p><p>
+ To copy a table completely, the short form using
+ the <code class="literal">TABLE</code> command can also be used:
+
+</p><pre class="programlisting">
+CREATE TABLE films2 AS
+ TABLE films;
+</pre><p>
+ </p><p>
+ Create a new temporary table <code class="literal">films_recent</code>, consisting of
+ only recent entries from the table <code class="literal">films</code>, using a
+ prepared statement. The new table will be dropped at commit:
+
+</p><pre class="programlisting">
+PREPARE recentfilms(date) AS
+ SELECT * FROM films WHERE date_prod &gt; $1;
+CREATE TEMP TABLE films_recent ON COMMIT DROP AS
+ EXECUTE recentfilms('2002-01-01');
+</pre></div><div class="refsect1" id="id-1.9.3.86.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE TABLE AS</code> conforms to the <acronym class="acronym">SQL</acronym>
+ standard. The following are nonstandard extensions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
+ The standard requires parentheses around the subquery clause; in
+ <span class="productname">PostgreSQL</span>, these parentheses are
+ optional.
+ </p></li><li class="listitem"><p>
+ In the standard, the <code class="literal">WITH [ NO ] DATA</code> clause
+ is required; in PostgreSQL it is optional.
+ </p></li><li class="listitem"><p><span class="productname">PostgreSQL</span> handles temporary tables in a way
+ rather different from the standard; see
+ <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>
+ for details.
+ </p></li><li class="listitem"><p>
+ The <code class="literal">WITH</code> clause is a <span class="productname">PostgreSQL</span>
+ extension; storage parameters are not in the standard.
+ </p></li><li class="listitem"><p>
+ The <span class="productname">PostgreSQL</span> concept of tablespaces is not
+ part of the standard. Hence, the clause <code class="literal">TABLESPACE</code>
+ is an extension.
+ </p></li></ul></div></div><div class="refsect1" id="id-1.9.3.86.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>, <a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a>, <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>, <a class="xref" href="sql-selectinto.html" title="SELECT INTO"><span class="refentrytitle">SELECT INTO</span></a>, <a class="xref" href="sql-values.html" title="VALUES"><span class="refentrytitle">VALUES</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtable.html" title="CREATE TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtablespace.html" title="CREATE TABLESPACE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TABLESPACE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtablespace.html b/doc/src/sgml/html/sql-createtablespace.html
new file mode 100644
index 0000000..df16fbf
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtablespace.html
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TABLESPACE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtableas.html" title="CREATE TABLE AS" /><link rel="next" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TABLESPACE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtableas.html" title="CREATE TABLE AS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETABLESPACE"><div class="titlepage"></div><a id="id-1.9.3.87.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TABLESPACE</span></h2><p>CREATE TABLESPACE — define a new tablespace</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TABLESPACE <em class="replaceable"><code>tablespace_name</code></em>
+ [ OWNER { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ]
+ LOCATION '<em class="replaceable"><code>directory</code></em>'
+ [ WITH ( <em class="replaceable"><code>tablespace_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.87.5"><h2>Description</h2><p>
+ <code class="command">CREATE TABLESPACE</code> registers a new cluster-wide
+ tablespace. The tablespace name must be distinct from the name of any
+ existing tablespace in the database cluster.
+ </p><p>
+ A tablespace allows superusers to define an alternative location on
+ the file system where the data files containing database objects
+ (such as tables and indexes) can reside.
+ </p><p>
+ A user with appropriate privileges can pass
+ <em class="replaceable"><code>tablespace_name</code></em> to
+ <code class="command">CREATE DATABASE</code>, <code class="command">CREATE TABLE</code>,
+ <code class="command">CREATE INDEX</code> or <code class="command">ADD CONSTRAINT</code> to have the data
+ files for these objects stored within the specified tablespace.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ A tablespace cannot be used independently of the cluster in which it
+ is defined; see <a class="xref" href="manage-ag-tablespaces.html" title="23.6. Tablespaces">Section 23.6</a>.
+ </p></div></div><div class="refsect1" id="id-1.9.3.87.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>tablespace_name</code></em></span></dt><dd><p>
+ The name of a tablespace to be created. The name cannot
+ begin with <code class="literal">pg_</code>, as such names
+ are reserved for system tablespaces.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ The name of the user who will own the tablespace. If omitted,
+ defaults to the user executing the command. Only superusers
+ can create tablespaces, but they can assign ownership of tablespaces
+ to non-superusers.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>directory</code></em></span></dt><dd><p>
+ The directory that will be used for the tablespace. The directory
+ must exist (<code class="command">CREATE TABLESPACE</code> will not create it),
+ should be empty, and must be owned by the
+ <span class="productname">PostgreSQL</span> system user. The directory must be
+ specified by an absolute path name.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>tablespace_option</code></em></span></dt><dd><p>
+ A tablespace parameter to be set or reset. Currently, the only
+ available parameters are <code class="varname">seq_page_cost</code>,
+ <code class="varname">random_page_cost</code>, <code class="varname">effective_io_concurrency</code>
+ and <code class="varname">maintenance_io_concurrency</code>.
+ Setting these values for a particular tablespace will override the
+ planner's usual estimate of the cost of reading pages from tables in
+ that tablespace, and the executor's prefetching behavior, as established
+ by the configuration parameters of the
+ same name (see <a class="xref" href="runtime-config-query.html#GUC-SEQ-PAGE-COST">seq_page_cost</a>,
+ <a class="xref" href="runtime-config-query.html#GUC-RANDOM-PAGE-COST">random_page_cost</a>,
+ <a class="xref" href="runtime-config-resource.html#GUC-EFFECTIVE-IO-CONCURRENCY">effective_io_concurrency</a>,
+ <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY">maintenance_io_concurrency</a>). This may be useful if
+ one tablespace is located on a disk which is faster or slower than the
+ remainder of the I/O subsystem.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.87.7"><h2>Notes</h2><p>
+ Tablespaces are only supported on systems that support symbolic links.
+ </p><p>
+ <code class="command">CREATE TABLESPACE</code> cannot be executed inside a transaction
+ block.
+ </p></div><div class="refsect1" id="id-1.9.3.87.8"><h2>Examples</h2><p>
+ To create a tablespace <code class="literal">dbspace</code> at file system location
+ <code class="literal">/data/dbs</code>, first create the directory using operating
+ system facilities and set the correct ownership:
+</p><pre class="programlisting">
+mkdir /data/dbs
+chown postgres:postgres /data/dbs
+</pre><p>
+ Then issue the tablespace creation command inside
+ <span class="productname">PostgreSQL</span>:
+</p><pre class="programlisting">
+CREATE TABLESPACE dbspace LOCATION '/data/dbs';
+</pre><p>
+ </p><p>
+ To create a tablespace owned by a different database user, use a command
+ like this:
+</p><pre class="programlisting">
+CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes';
+</pre></div><div class="refsect1" id="id-1.9.3.87.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE TABLESPACE</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.87.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>, <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>, <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>, <a class="xref" href="sql-droptablespace.html" title="DROP TABLESPACE"><span class="refentrytitle">DROP TABLESPACE</span></a>, <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtableas.html" title="CREATE TABLE AS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TABLE AS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TEXT SEARCH CONFIGURATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtransform.html b/doc/src/sgml/html/sql-createtransform.html
new file mode 100644
index 0000000..a237ad0
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtransform.html
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TRANSFORM</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE" /><link rel="next" href="sql-createtrigger.html" title="CREATE TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TRANSFORM</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtrigger.html" title="CREATE TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETRANSFORM"><div class="titlepage"></div><a id="id-1.9.3.92.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TRANSFORM</span></h2><p>CREATE TRANSFORM — define a new transform</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] TRANSFORM FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> (
+ FROM SQL WITH FUNCTION <em class="replaceable"><code>from_sql_function_name</code></em> [ (<em class="replaceable"><code>argument_type</code></em> [, ...]) ],
+ TO SQL WITH FUNCTION <em class="replaceable"><code>to_sql_function_name</code></em> [ (<em class="replaceable"><code>argument_type</code></em> [, ...]) ]
+);
+</pre></div><div class="refsect1" id="SQL-CREATETRANSFORM-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">CREATE TRANSFORM</code> defines a new transform.
+ <code class="command">CREATE OR REPLACE TRANSFORM</code> will either create a new
+ transform, or replace an existing definition.
+ </p><p>
+ A transform specifies how to adapt a data type to a procedural language.
+ For example, when writing a function in PL/Python using
+ the <code class="type">hstore</code> type, PL/Python has no prior knowledge how to
+ present <code class="type">hstore</code> values in the Python environment. Language
+ implementations usually default to using the text representation, but that
+ is inconvenient when, for example, an associative array or a list would be
+ more appropriate.
+ </p><p>
+ A transform specifies two functions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A <span class="quote">“<span class="quote">from SQL</span>”</span> function that converts the type from the SQL
+ environment to the language. This function will be invoked on the
+ arguments of a function written in the language.
+ </p></li><li class="listitem"><p>
+ A <span class="quote">“<span class="quote">to SQL</span>”</span> function that converts the type from the
+ language to the SQL environment. This function will be invoked on the
+ return value of a function written in the language.
+ </p></li></ul></div><p>
+ It is not necessary to provide both of these functions. If one is not
+ specified, the language-specific default behavior will be used if
+ necessary. (To prevent a transformation in a certain direction from
+ happening at all, you could also write a transform function that always
+ errors out.)
+ </p><p>
+ To be able to create a transform, you must own and
+ have <code class="literal">USAGE</code> privilege on the type, have
+ <code class="literal">USAGE</code> privilege on the language, and own and
+ have <code class="literal">EXECUTE</code> privilege on the from-SQL and to-SQL
+ functions, if specified.
+ </p></div><div class="refsect1" id="id-1.9.3.92.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
+ The name of the data type of the transform.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language of the transform.
+ </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>from_sql_function_name</code></em>[(<em class="replaceable"><code>argument_type</code></em> [, ...])]</code></span></dt><dd><p>
+ The name of the function for converting the type from the SQL
+ environment to the language. It must take one argument of
+ type <code class="type">internal</code> and return type <code class="type">internal</code>. The
+ actual argument will be of the type for the transform, and the function
+ should be coded as if it were. (But it is not allowed to declare an
+ SQL-level function returning <code class="type">internal</code> without at
+ least one argument of type <code class="type">internal</code>.) The actual return
+ value will be something specific to the language implementation.
+ If no argument list is specified, the function name must be unique in
+ its schema.
+ </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>to_sql_function_name</code></em>[(<em class="replaceable"><code>argument_type</code></em> [, ...])]</code></span></dt><dd><p>
+ The name of the function for converting the type from the language to
+ the SQL environment. It must take one argument of type
+ <code class="type">internal</code> and return the type that is the type for the
+ transform. The actual argument value will be something specific to the
+ language implementation.
+ If no argument list is specified, the function name must be unique in
+ its schema.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATETRANSFORM-NOTES"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-droptransform.html" title="DROP TRANSFORM"><code class="command">DROP TRANSFORM</code></a> to remove transforms.
+ </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-EXAMPLES"><h2>Examples</h2><p>
+ To create a transform for type <code class="type">hstore</code> and language
+ <code class="literal">plpython3u</code>, first set up the type and the language:
+</p><pre class="programlisting">
+CREATE TYPE hstore ...;
+
+CREATE EXTENSION plpython3u;
+</pre><p>
+ Then create the necessary functions:
+</p><pre class="programlisting">
+CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
+LANGUAGE C STRICT IMMUTABLE
+AS ...;
+
+CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
+LANGUAGE C STRICT IMMUTABLE
+AS ...;
+</pre><p>
+ And finally create the transform to connect them all together:
+</p><pre class="programlisting">
+CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
+ FROM SQL WITH FUNCTION hstore_to_plpython(internal),
+ TO SQL WITH FUNCTION plpython_to_hstore(internal)
+);
+</pre><p>
+ In practice, these commands would be wrapped up in an extension.
+ </p><p>
+ The <code class="filename">contrib</code> section contains a number of extensions
+ that provide transforms, which can serve as real-world examples.
+ </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-COMPAT"><h2>Compatibility</h2><p>
+ This form of <code class="command">CREATE TRANSFORM</code> is a
+ <span class="productname">PostgreSQL</span> extension. There is a <code class="command">CREATE
+ TRANSFORM</code> command in the <acronym class="acronym">SQL</acronym> standard, but it
+ is for adapting data types to client languages. That usage is not supported
+ by <span class="productname">PostgreSQL</span>.
+ </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-SEEALSO"><h2>See Also</h2><p>
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>,
+ <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>,
+ <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a>,
+ <a class="xref" href="sql-droptransform.html" title="DROP TRANSFORM"><span class="refentrytitle">DROP TRANSFORM</span></a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtrigger.html" title="CREATE TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TEXT SEARCH TEMPLATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtrigger.html b/doc/src/sgml/html/sql-createtrigger.html
new file mode 100644
index 0000000..66d5fee
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtrigger.html
@@ -0,0 +1,461 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtransform.html" title="CREATE TRANSFORM" /><link rel="next" href="sql-createtype.html" title="CREATE TYPE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtransform.html" title="CREATE TRANSFORM">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtype.html" title="CREATE TYPE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETRIGGER"><div class="titlepage"></div><a id="id-1.9.3.93.1" class="indexterm"></a><a id="id-1.9.3.93.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TRIGGER</span></h2><p>CREATE TRIGGER — define a new trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER <em class="replaceable"><code>name</code></em> { BEFORE | AFTER | INSTEAD OF } { <em class="replaceable"><code>event</code></em> [ OR ... ] }
+ ON <em class="replaceable"><code>table_name</code></em>
+ [ FROM <em class="replaceable"><code>referenced_table_name</code></em> ]
+ [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ]
+ [ REFERENCING { { OLD | NEW } TABLE [ AS ] <em class="replaceable"><code>transition_relation_name</code></em> } [ ... ] ]
+ [ FOR [ EACH ] { ROW | STATEMENT } ]
+ [ WHEN ( <em class="replaceable"><code>condition</code></em> ) ]
+ EXECUTE { FUNCTION | PROCEDURE } <em class="replaceable"><code>function_name</code></em> ( <em class="replaceable"><code>arguments</code></em> )
+
+<span class="phrase">where <em class="replaceable"><code>event</code></em> can be one of:</span>
+
+ INSERT
+ UPDATE [ OF <em class="replaceable"><code>column_name</code></em> [, ... ] ]
+ DELETE
+ TRUNCATE
+</pre></div><div class="refsect1" id="id-1.9.3.93.6"><h2>Description</h2><p>
+ <code class="command">CREATE TRIGGER</code> creates a new trigger.
+ <code class="command">CREATE OR REPLACE TRIGGER</code> will either create a
+ new trigger, or replace an existing trigger. The
+ trigger will be associated with the specified table, view, or foreign table
+ and will execute the specified
+ function <em class="replaceable"><code>function_name</code></em> when
+ certain operations are performed on that table.
+ </p><p>
+ To replace the current definition of an existing trigger, use
+ <code class="command">CREATE OR REPLACE TRIGGER</code>, specifying the existing
+ trigger's name and parent table. All other properties are replaced.
+ </p><p>
+ The trigger can be specified to fire before the
+ operation is attempted on a row (before constraints are checked and
+ the <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> is attempted); or after the operation has
+ completed (after constraints are checked and the
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> has completed); or instead of the operation
+ (in the case of inserts, updates or deletes on a view).
+ If the trigger fires before or instead of the event, the trigger can skip
+ the operation for the current row, or change the row being inserted (for
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> operations
+ only). If the trigger fires after the event, all changes, including
+ the effects of other triggers, are <span class="quote">“<span class="quote">visible</span>”</span>
+ to the trigger.
+ </p><p>
+ A trigger that is marked <code class="literal">FOR EACH ROW</code> is called
+ once for every row that the operation modifies. For example, a
+ <code class="command">DELETE</code> that affects 10 rows will cause any
+ <code class="literal">ON DELETE</code> triggers on the target relation to be
+ called 10 separate times, once for each deleted row. In contrast, a
+ trigger that is marked <code class="literal">FOR EACH STATEMENT</code> only
+ executes once for any given operation, regardless of how many rows
+ it modifies (in particular, an operation that modifies zero rows
+ will still result in the execution of any applicable <code class="literal">FOR
+ EACH STATEMENT</code> triggers).
+ </p><p>
+ Triggers that are specified to fire <code class="literal">INSTEAD OF</code> the trigger
+ event must be marked <code class="literal">FOR EACH ROW</code>, and can only be defined
+ on views. <code class="literal">BEFORE</code> and <code class="literal">AFTER</code> triggers on a view
+ must be marked as <code class="literal">FOR EACH STATEMENT</code>.
+ </p><p>
+ In addition, triggers may be defined to fire for
+ <code class="command">TRUNCATE</code>, though only
+ <code class="literal">FOR EACH STATEMENT</code>.
+ </p><p>
+ The following table summarizes which types of triggers may be used on
+ tables, views, and foreign tables:
+ </p><div class="informaltable" id="SUPPORTED-TRIGGER-TYPES"><table class="informaltable" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>When</th><th>Event</th><th>Row-level</th><th>Statement-level</th></tr></thead><tbody><tr><td rowspan="2" align="center"><code class="literal">BEFORE</code></td><td align="center"><code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code></td><td align="center">Tables and foreign tables</td><td align="center">Tables, views, and foreign tables</td></tr><tr><td align="center"><code class="command">TRUNCATE</code></td><td align="center">—</td><td align="center">Tables</td></tr><tr><td rowspan="2" align="center"><code class="literal">AFTER</code></td><td align="center"><code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code></td><td align="center">Tables and foreign tables</td><td align="center">Tables, views, and foreign tables</td></tr><tr><td align="center"><code class="command">TRUNCATE</code></td><td align="center">—</td><td align="center">Tables</td></tr><tr><td rowspan="2" align="center"><code class="literal">INSTEAD OF</code></td><td align="center"><code class="command">INSERT</code>/<code class="command">UPDATE</code>/<code class="command">DELETE</code></td><td align="center">Views</td><td align="center">—</td></tr><tr><td align="center"><code class="command">TRUNCATE</code></td><td align="center">—</td><td align="center">—</td></tr></tbody></table></div><p>
+ Also, a trigger definition can specify a Boolean <code class="literal">WHEN</code>
+ condition, which will be tested to see whether the trigger should
+ be fired. In row-level triggers the <code class="literal">WHEN</code> condition can
+ examine the old and/or new values of columns of the row. Statement-level
+ triggers can also have <code class="literal">WHEN</code> conditions, although the feature
+ is not so useful for them since the condition cannot refer to any values
+ in the table.
+ </p><p>
+ If multiple triggers of the same kind are defined for the same event,
+ they will be fired in alphabetical order by name.
+ </p><p>
+ When the <code class="literal">CONSTRAINT</code> option is specified, this command creates a
+ <em class="firstterm">constraint trigger</em>.<a id="id-1.9.3.93.6.12.3" class="indexterm"></a>
+ This is the same as a regular trigger
+ except that the timing of the trigger firing can be adjusted using
+ <a class="link" href="sql-set-constraints.html" title="SET CONSTRAINTS"><code class="command">SET CONSTRAINTS</code></a>.
+ Constraint triggers must be <code class="literal">AFTER ROW</code> triggers on plain
+ tables (not foreign tables). They
+ can be fired either at the end of the statement causing the triggering
+ event, or at the end of the containing transaction; in the latter case they
+ are said to be <em class="firstterm">deferred</em>. A pending deferred-trigger firing
+ can also be forced to happen immediately by using <code class="command">SET
+ CONSTRAINTS</code>. Constraint triggers are expected to raise an exception
+ when the constraints they implement are violated.
+ </p><p>
+ The <code class="literal">REFERENCING</code> option enables collection
+ of <em class="firstterm">transition relations</em>, which are row sets that include all
+ of the rows inserted, deleted, or modified by the current SQL statement.
+ This feature lets the trigger see a global view of what the statement did,
+ not just one row at a time. This option is only allowed for
+ an <code class="literal">AFTER</code> trigger that is not a constraint trigger; also, if
+ the trigger is an <code class="literal">UPDATE</code> trigger, it must not specify
+ a <em class="replaceable"><code>column_name</code></em> list.
+ <code class="literal">OLD TABLE</code> may only be specified once, and only for a trigger
+ that can fire on <code class="literal">UPDATE</code> or <code class="literal">DELETE</code>; it creates a
+ transition relation containing the <em class="firstterm">before-images</em> of all rows
+ updated or deleted by the statement.
+ Similarly, <code class="literal">NEW TABLE</code> may only be specified once, and only for
+ a trigger that can fire on <code class="literal">UPDATE</code> or <code class="literal">INSERT</code>;
+ it creates a transition relation containing the <em class="firstterm">after-images</em>
+ of all rows updated or inserted by the statement.
+ </p><p>
+ <code class="command">SELECT</code> does not modify any rows so you cannot
+ create <code class="command">SELECT</code> triggers. Rules and views may provide
+ workable solutions to problems that seem to need <code class="command">SELECT</code>
+ triggers.
+ </p><p>
+ Refer to <a class="xref" href="triggers.html" title="Chapter 39. Triggers">Chapter 39</a> for more information about triggers.
+ </p></div><div class="refsect1" id="id-1.9.3.93.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name to give the new trigger. This must be distinct from
+ the name of any other trigger for the same table.
+ The name cannot be schema-qualified — the trigger inherits the
+ schema of its table. For a constraint trigger, this is also the name to
+ use when modifying the trigger's behavior using
+ <code class="command">SET CONSTRAINTS</code>.
+ </p></dd><dt><span class="term"><code class="literal">BEFORE</code><br /></span><span class="term"><code class="literal">AFTER</code><br /></span><span class="term"><code class="literal">INSTEAD OF</code></span></dt><dd><p>
+ Determines whether the function is called before, after, or instead of
+ the event. A constraint trigger can only be specified as
+ <code class="literal">AFTER</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>event</code></em></span></dt><dd><p>
+ One of <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
+ <code class="literal">DELETE</code>, or <code class="literal">TRUNCATE</code>;
+ this specifies the event that will fire the trigger. Multiple
+ events can be specified using <code class="literal">OR</code>, except when
+ transition relations are requested.
+ </p><p>
+ For <code class="literal">UPDATE</code> events, it is possible to
+ specify a list of columns using this syntax:
+</p><pre class="synopsis">
+UPDATE OF <em class="replaceable"><code>column_name1</code></em> [, <em class="replaceable"><code>column_name2</code></em> ... ]
+</pre><p>
+ The trigger will only fire if at least one of the listed columns
+ is mentioned as a target of the <code class="command">UPDATE</code> command
+ or if one of the listed columns is a generated column that depends on a
+ column that is the target of the <code class="command">UPDATE</code>.
+ </p><p>
+ <code class="literal">INSTEAD OF UPDATE</code> events do not allow a list of columns.
+ A column list cannot be specified when requesting transition relations,
+ either.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table, view, or foreign
+ table the trigger is for.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>referenced_table_name</code></em></span></dt><dd><p>
+ The (possibly schema-qualified) name of another table referenced by the
+ constraint. This option is used for foreign-key constraints and is not
+ recommended for general use. This can only be specified for
+ constraint triggers.
+ </p></dd><dt><span class="term"><code class="literal">DEFERRABLE</code><br /></span><span class="term"><code class="literal">NOT DEFERRABLE</code><br /></span><span class="term"><code class="literal">INITIALLY IMMEDIATE</code><br /></span><span class="term"><code class="literal">INITIALLY DEFERRED</code></span></dt><dd><p>
+ The default timing of the trigger.
+ See the <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> documentation for details of
+ these constraint options. This can only be specified for constraint
+ triggers.
+ </p></dd><dt><span class="term"><code class="literal">REFERENCING</code></span></dt><dd><p>
+ This keyword immediately precedes the declaration of one or two
+ relation names that provide access to the transition relations of the
+ triggering statement.
+ </p></dd><dt><span class="term"><code class="literal">OLD TABLE</code><br /></span><span class="term"><code class="literal">NEW TABLE</code></span></dt><dd><p>
+ This clause indicates whether the following relation name is for the
+ before-image transition relation or the after-image transition
+ relation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>transition_relation_name</code></em></span></dt><dd><p>
+ The (unqualified) name to be used within the trigger for this
+ transition relation.
+ </p></dd><dt><span class="term"><code class="literal">FOR EACH ROW</code><br /></span><span class="term"><code class="literal">FOR EACH STATEMENT</code></span></dt><dd><p>
+ This specifies whether the trigger function should be fired
+ once for every row affected by the trigger event, or just once
+ per SQL statement. If neither is specified, <code class="literal">FOR EACH
+ STATEMENT</code> is the default. Constraint triggers can only
+ be specified <code class="literal">FOR EACH ROW</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ A Boolean expression that determines whether the trigger function
+ will actually be executed. If <code class="literal">WHEN</code> is specified, the
+ function will only be called if the <em class="replaceable"><code>condition</code></em> returns <code class="literal">true</code>.
+ In <code class="literal">FOR EACH ROW</code> triggers, the <code class="literal">WHEN</code>
+ condition can refer to columns of the old and/or new row values
+ by writing <code class="literal">OLD.<em class="replaceable"><code>column_name</code></em></code> or
+ <code class="literal">NEW.<em class="replaceable"><code>column_name</code></em></code> respectively.
+ Of course, <code class="literal">INSERT</code> triggers cannot refer to <code class="literal">OLD</code>
+ and <code class="literal">DELETE</code> triggers cannot refer to <code class="literal">NEW</code>.
+ </p><p><code class="literal">INSTEAD OF</code> triggers do not support <code class="literal">WHEN</code>
+ conditions.
+ </p><p>
+ Currently, <code class="literal">WHEN</code> expressions cannot contain
+ subqueries.
+ </p><p>
+ Note that for constraint triggers, evaluation of the <code class="literal">WHEN</code>
+ condition is not deferred, but occurs immediately after the row update
+ operation is performed. If the condition does not evaluate to true then
+ the trigger is not queued for deferred execution.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ A user-supplied function that is declared as taking no arguments
+ and returning type <code class="literal">trigger</code>, which is executed when
+ the trigger fires.
+ </p><p>
+ In the syntax of <code class="literal">CREATE TRIGGER</code>, the keywords
+ <code class="literal">FUNCTION</code> and <code class="literal">PROCEDURE</code> are
+ equivalent, but the referenced function must in any case be a function,
+ not a procedure. The use of the keyword <code class="literal">PROCEDURE</code>
+ here is historical and deprecated.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>arguments</code></em></span></dt><dd><p>
+ An optional comma-separated list of arguments to be provided to
+ the function when the trigger is executed. The arguments are
+ literal string constants. Simple names and numeric constants
+ can be written here, too, but they will all be converted to
+ strings. Please check the description of the implementation
+ language of the trigger function to find out how these arguments
+ can be accessed within the function; it might be different from
+ normal function arguments.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATETRIGGER-NOTES"><h2>Notes</h2><p>
+ To create or replace a trigger on a table, the user must have the
+ <code class="literal">TRIGGER</code> privilege on the table. The user must
+ also have <code class="literal">EXECUTE</code> privilege on the trigger function.
+ </p><p>
+ Use <a class="link" href="sql-droptrigger.html" title="DROP TRIGGER"><code class="command">DROP TRIGGER</code></a> to remove a trigger.
+ </p><p>
+ Creating a row-level trigger on a partitioned table will cause an
+ identical <span class="quote">“<span class="quote">clone</span>”</span> trigger to be created on each of its
+ existing partitions; and any partitions created or attached later will have
+ an identical trigger, too. If there is a conflictingly-named trigger on a
+ child partition already, an error occurs unless <code class="command">CREATE OR REPLACE
+ TRIGGER</code> is used, in which case that trigger is replaced with a
+ clone trigger. When a partition is detached from its parent, its clone
+ triggers are removed.
+ </p><p>
+ A column-specific trigger (one defined using the <code class="literal">UPDATE OF
+ <em class="replaceable"><code>column_name</code></em></code> syntax) will fire when any
+ of its columns are listed as targets in the <code class="command">UPDATE</code>
+ command's <code class="literal">SET</code> list. It is possible for a column's value
+ to change even when the trigger is not fired, because changes made to the
+ row's contents by <code class="literal">BEFORE UPDATE</code> triggers are not considered.
+ Conversely, a command such as <code class="literal">UPDATE ... SET x = x ...</code>
+ will fire a trigger on column <code class="literal">x</code>, even though the column's
+ value did not change.
+ </p><p>
+ In a <code class="literal">BEFORE</code> trigger, the <code class="literal">WHEN</code> condition is
+ evaluated just before the function is or would be executed, so using
+ <code class="literal">WHEN</code> is not materially different from testing the same
+ condition at the beginning of the trigger function. Note in particular
+ that the <code class="literal">NEW</code> row seen by the condition is the current value,
+ as possibly modified by earlier triggers. Also, a <code class="literal">BEFORE</code>
+ trigger's <code class="literal">WHEN</code> condition is not allowed to examine the
+ system columns of the <code class="literal">NEW</code> row (such as <code class="literal">ctid</code>),
+ because those won't have been set yet.
+ </p><p>
+ In an <code class="literal">AFTER</code> trigger, the <code class="literal">WHEN</code> condition is
+ evaluated just after the row update occurs, and it determines whether an
+ event is queued to fire the trigger at the end of statement. So when an
+ <code class="literal">AFTER</code> trigger's <code class="literal">WHEN</code> condition does not return
+ true, it is not necessary to queue an event nor to re-fetch the row at end
+ of statement. This can result in significant speedups in statements that
+ modify many rows, if the trigger only needs to be fired for a few of the
+ rows.
+ </p><p>
+ In some cases it is possible for a single SQL command to fire more than
+ one kind of trigger. For instance an <code class="command">INSERT</code> with
+ an <code class="literal">ON CONFLICT DO UPDATE</code> clause may cause both insert and
+ update operations, so it will fire both kinds of triggers as needed.
+ The transition relations supplied to triggers are
+ specific to their event type; thus an <code class="command">INSERT</code> trigger
+ will see only the inserted rows, while an <code class="command">UPDATE</code>
+ trigger will see only the updated rows.
+ </p><p>
+ Row updates or deletions caused by foreign-key enforcement actions, such
+ as <code class="literal">ON UPDATE CASCADE</code> or <code class="literal">ON DELETE SET NULL</code>, are
+ treated as part of the SQL command that caused them (note that such
+ actions are never deferred). Relevant triggers on the affected table will
+ be fired, so that this provides another way in which an SQL command might
+ fire triggers not directly matching its type. In simple cases, triggers
+ that request transition relations will see all changes caused in their
+ table by a single original SQL command as a single transition relation.
+ However, there are cases in which the presence of an <code class="literal">AFTER ROW</code>
+ trigger that requests transition relations will cause the foreign-key
+ enforcement actions triggered by a single SQL command to be split into
+ multiple steps, each with its own transition relation(s). In such cases,
+ any statement-level triggers that are present will be fired once per
+ creation of a transition relation set, ensuring that the triggers see
+ each affected row in a transition relation once and only once.
+ </p><p>
+ Statement-level triggers on a view are fired only if the action on the
+ view is handled by a row-level <code class="literal">INSTEAD OF</code> trigger.
+ If the action is handled by an <code class="literal">INSTEAD</code> rule, then
+ whatever statements are emitted by the rule are executed in place of the
+ original statement naming the view, so that the triggers that will be
+ fired are those on tables named in the replacement statements.
+ Similarly, if the view is automatically updatable, then the action is
+ handled by automatically rewriting the statement into an action on the
+ view's base table, so that the base table's statement-level triggers are
+ the ones that are fired.
+ </p><p>
+ Modifying a partitioned table or a table with inheritance children fires
+ statement-level triggers attached to the explicitly named table, but not
+ statement-level triggers for its partitions or child tables. In contrast,
+ row-level triggers are fired on the rows in affected partitions or
+ child tables, even if they are not explicitly named in the query.
+ If a statement-level trigger has been defined with transition relations
+ named by a <code class="literal">REFERENCING</code> clause, then before and after
+ images of rows are visible from all affected partitions or child tables.
+ In the case of inheritance children, the row images include only columns
+ that are present in the table that the trigger is attached to.
+ </p><p>
+ Currently, row-level triggers with transition relations cannot be defined
+ on partitions or inheritance child tables. Also, triggers on partitioned
+ tables may not be <code class="literal">INSTEAD OF</code>.
+ </p><p>
+ Currently, the <code class="literal">OR REPLACE</code> option is not supported for
+ constraint triggers.
+ </p><p>
+ Replacing an existing trigger within a transaction that has already
+ performed updating actions on the trigger's table is not recommended.
+ Trigger firing decisions, or portions of firing decisions, that have
+ already been made will not be reconsidered, so the effects could be
+ surprising.
+ </p><p>
+ There are a few built-in trigger functions that can be used to
+ solve common problems without having to write your own trigger code;
+ see <a class="xref" href="functions-trigger.html" title="9.28. Trigger Functions">Section 9.28</a>.
+ </p></div><div class="refsect1" id="SQL-CREATETRIGGER-EXAMPLES"><h2>Examples</h2><p>
+ Execute the function <code class="function">check_account_update</code> whenever
+ a row of the table <code class="literal">accounts</code> is about to be updated:
+
+</p><pre class="programlisting">
+CREATE TRIGGER check_update
+ BEFORE UPDATE ON accounts
+ FOR EACH ROW
+ EXECUTE FUNCTION check_account_update();
+</pre><p>
+
+ Modify that trigger definition to only execute the function if
+ column <code class="literal">balance</code> is specified as a target in
+ the <code class="command">UPDATE</code> command:
+
+</p><pre class="programlisting">
+CREATE OR REPLACE TRIGGER check_update
+ BEFORE UPDATE OF balance ON accounts
+ FOR EACH ROW
+ EXECUTE FUNCTION check_account_update();
+</pre><p>
+
+ This form only executes the function if column <code class="literal">balance</code>
+ has in fact changed value:
+
+</p><pre class="programlisting">
+CREATE TRIGGER check_update
+ BEFORE UPDATE ON accounts
+ FOR EACH ROW
+ WHEN (OLD.balance IS DISTINCT FROM NEW.balance)
+ EXECUTE FUNCTION check_account_update();
+</pre><p>
+
+ Call a function to log updates of <code class="literal">accounts</code>, but only if
+ something changed:
+
+</p><pre class="programlisting">
+CREATE TRIGGER log_update
+ AFTER UPDATE ON accounts
+ FOR EACH ROW
+ WHEN (OLD.* IS DISTINCT FROM NEW.*)
+ EXECUTE FUNCTION log_account_update();
+</pre><p>
+
+ Execute the function <code class="function">view_insert_row</code> for each row to insert
+ rows into the tables underlying a view:
+
+</p><pre class="programlisting">
+CREATE TRIGGER view_insert
+ INSTEAD OF INSERT ON my_view
+ FOR EACH ROW
+ EXECUTE FUNCTION view_insert_row();
+</pre><p>
+
+ Execute the function <code class="function">check_transfer_balances_to_zero</code> for each
+ statement to confirm that the <code class="literal">transfer</code> rows offset to a net of
+ zero:
+
+</p><pre class="programlisting">
+CREATE TRIGGER transfer_insert
+ AFTER INSERT ON transfer
+ REFERENCING NEW TABLE AS inserted
+ FOR EACH STATEMENT
+ EXECUTE FUNCTION check_transfer_balances_to_zero();
+</pre><p>
+
+ Execute the function <code class="function">check_matching_pairs</code> for each row to
+ confirm that changes are made to matching pairs at the same time (by the
+ same statement):
+
+</p><pre class="programlisting">
+CREATE TRIGGER paired_items_update
+ AFTER UPDATE ON paired_items
+ REFERENCING NEW TABLE AS newtab OLD TABLE AS oldtab
+ FOR EACH ROW
+ EXECUTE FUNCTION check_matching_pairs();
+</pre><p>
+ </p><p>
+ <a class="xref" href="trigger-example.html" title="39.4. A Complete Trigger Example">Section 39.4</a> contains a complete example of a trigger
+ function written in C.
+ </p></div><div class="refsect1" id="SQL-CREATETRIGGER-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE TRIGGER</code> statement in
+ <span class="productname">PostgreSQL</span> implements a subset of the
+ <acronym class="acronym">SQL</acronym> standard. The following functionalities are currently
+ missing:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ While transition table names for <code class="literal">AFTER</code> triggers are
+ specified using the <code class="literal">REFERENCING</code> clause in the standard way,
+ the row variables used in <code class="literal">FOR EACH ROW</code> triggers may not be
+ specified in a <code class="literal">REFERENCING</code> clause. They are available in a
+ manner that is dependent on the language in which the trigger function
+ is written, but is fixed for any one language. Some languages
+ effectively behave as though there is a <code class="literal">REFERENCING</code> clause
+ containing <code class="literal">OLD ROW AS OLD NEW ROW AS NEW</code>.
+ </p></li><li class="listitem"><p>
+ The standard allows transition tables to be used with
+ column-specific <code class="literal">UPDATE</code> triggers, but then the set of rows
+ that should be visible in the transition tables depends on the
+ trigger's column list. This is not currently implemented by
+ <span class="productname">PostgreSQL</span>.
+ </p></li><li class="listitem"><p>
+ <span class="productname">PostgreSQL</span> only allows the execution
+ of a user-defined function for the triggered action. The standard
+ allows the execution of a number of other SQL commands, such as
+ <code class="command">CREATE TABLE</code>, as the triggered action. This
+ limitation is not hard to work around by creating a user-defined
+ function that executes the desired commands.
+ </p></li></ul></div><p>
+ </p><p>
+ SQL specifies that multiple triggers should be fired in
+ time-of-creation order. <span class="productname">PostgreSQL</span> uses
+ name order, which was judged to be more convenient.
+ </p><p>
+ SQL specifies that <code class="literal">BEFORE DELETE</code> triggers on cascaded
+ deletes fire <span class="emphasis"><em>after</em></span> the cascaded <code class="literal">DELETE</code> completes.
+ The <span class="productname">PostgreSQL</span> behavior is for <code class="literal">BEFORE
+ DELETE</code> to always fire before the delete action, even a cascading
+ one. This is considered more consistent. There is also nonstandard
+ behavior if <code class="literal">BEFORE</code> triggers modify rows or prevent
+ updates during an update that is caused by a referential action. This can
+ lead to constraint violations or stored data that does not honor the
+ referential constraint.
+ </p><p>
+ The ability to specify multiple actions for a single trigger using
+ <code class="literal">OR</code> is a <span class="productname">PostgreSQL</span> extension of
+ the SQL standard.
+ </p><p>
+ The ability to fire triggers for <code class="command">TRUNCATE</code> is a
+ <span class="productname">PostgreSQL</span> extension of the SQL standard, as is the
+ ability to define statement-level triggers on views.
+ </p><p>
+ <code class="command">CREATE CONSTRAINT TRIGGER</code> is a
+ <span class="productname">PostgreSQL</span> extension of the <acronym class="acronym">SQL</acronym>
+ standard.
+ So is the <code class="literal">OR REPLACE</code> option.
+ </p></div><div class="refsect1" id="id-1.9.3.93.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertrigger.html" title="ALTER TRIGGER"><span class="refentrytitle">ALTER TRIGGER</span></a>, <a class="xref" href="sql-droptrigger.html" title="DROP TRIGGER"><span class="refentrytitle">DROP TRIGGER</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-set-constraints.html" title="SET CONSTRAINTS"><span class="refentrytitle">SET CONSTRAINTS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtransform.html" title="CREATE TRANSFORM">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtype.html" title="CREATE TYPE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TRANSFORM </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TYPE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtsconfig.html b/doc/src/sgml/html/sql-createtsconfig.html
new file mode 100644
index 0000000..da7e8bd
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtsconfig.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TEXT SEARCH CONFIGURATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtablespace.html" title="CREATE TABLESPACE" /><link rel="next" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TEXT SEARCH CONFIGURATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtablespace.html" title="CREATE TABLESPACE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETSCONFIG"><div class="titlepage"></div><a id="id-1.9.3.88.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TEXT SEARCH CONFIGURATION</span></h2><p>CREATE TEXT SEARCH CONFIGURATION — define a new text search configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TEXT SEARCH CONFIGURATION <em class="replaceable"><code>name</code></em> (
+ PARSER = <em class="replaceable"><code>parser_name</code></em> |
+ COPY = <em class="replaceable"><code>source_config</code></em>
+)
+</pre></div><div class="refsect1" id="id-1.9.3.88.5"><h2>Description</h2><p>
+ <code class="command">CREATE TEXT SEARCH CONFIGURATION</code> creates a new text
+ search configuration. A text search configuration specifies a text
+ search parser that can divide a string into tokens, plus dictionaries
+ that can be used to determine which tokens are of interest for searching.
+ </p><p>
+ If only the parser is specified, then the new text search configuration
+ initially has no mappings from token types to dictionaries, and therefore
+ will ignore all words. Subsequent <code class="command">ALTER TEXT SEARCH
+ CONFIGURATION</code> commands must be used to create mappings to
+ make the configuration useful. Alternatively, an existing text search
+ configuration can be copied.
+ </p><p>
+ If a schema name is given then the text search configuration is created in
+ the specified schema. Otherwise it is created in the current schema.
+ </p><p>
+ The user who defines a text search configuration becomes its owner.
+ </p><p>
+ Refer to <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.88.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the text search configuration to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>parser_name</code></em></span></dt><dd><p>
+ The name of the text search parser to use for this configuration.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_config</code></em></span></dt><dd><p>
+ The name of an existing text search configuration to copy.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.88.7"><h2>Notes</h2><p>
+ The <code class="literal">PARSER</code> and <code class="literal">COPY</code> options are mutually
+ exclusive, because when an existing configuration is copied, its
+ parser selection is copied too.
+ </p></div><div class="refsect1" id="id-1.9.3.88.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE TEXT SEARCH CONFIGURATION</code> statement
+ in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.88.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION"><span class="refentrytitle">ALTER TEXT SEARCH CONFIGURATION</span></a>, <a class="xref" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION"><span class="refentrytitle">DROP TEXT SEARCH CONFIGURATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtablespace.html" title="CREATE TABLESPACE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TABLESPACE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TEXT SEARCH DICTIONARY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtsdictionary.html b/doc/src/sgml/html/sql-createtsdictionary.html
new file mode 100644
index 0000000..3d84e39
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtsdictionary.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TEXT SEARCH DICTIONARY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION" /><link rel="next" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TEXT SEARCH DICTIONARY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETSDICTIONARY"><div class="titlepage"></div><a id="id-1.9.3.89.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TEXT SEARCH DICTIONARY</span></h2><p>CREATE TEXT SEARCH DICTIONARY — define a new text search dictionary</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TEXT SEARCH DICTIONARY <em class="replaceable"><code>name</code></em> (
+ TEMPLATE = <em class="replaceable"><code>template</code></em>
+ [, <em class="replaceable"><code>option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ]]
+)
+</pre></div><div class="refsect1" id="id-1.9.3.89.5"><h2>Description</h2><p>
+ <code class="command">CREATE TEXT SEARCH DICTIONARY</code> creates a new text search
+ dictionary. A text search dictionary specifies a way of recognizing
+ interesting or uninteresting words for searching. A dictionary depends
+ on a text search template, which specifies the functions that actually
+ perform the work. Typically the dictionary provides some options that
+ control the detailed behavior of the template's functions.
+ </p><p>
+ If a schema name is given then the text search dictionary is created in the
+ specified schema. Otherwise it is created in the current schema.
+ </p><p>
+ The user who defines a text search dictionary becomes its owner.
+ </p><p>
+ Refer to <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.89.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the text search dictionary to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>template</code></em></span></dt><dd><p>
+ The name of the text search template that will define the basic
+ behavior of this dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>option</code></em></span></dt><dd><p>
+ The name of a template-specific option to be set for this dictionary.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ The value to use for a template-specific option. If the value
+ is not a simple identifier or number, it must be quoted (but you can
+ always quote it, if you wish).
+ </p></dd></dl></div><p>
+ The options can appear in any order.
+ </p></div><div class="refsect1" id="id-1.9.3.89.7"><h2>Examples</h2><p>
+ The following example command creates a Snowball-based dictionary
+ with a nonstandard list of stop words.
+ </p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY my_russian (
+ template = snowball,
+ language = russian,
+ stopwords = myrussian
+);
+</pre></div><div class="refsect1" id="id-1.9.3.89.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">CREATE TEXT SEARCH DICTIONARY</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.89.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY"><span class="refentrytitle">ALTER TEXT SEARCH DICTIONARY</span></a>, <a class="xref" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY"><span class="refentrytitle">DROP TEXT SEARCH DICTIONARY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TEXT SEARCH CONFIGURATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TEXT SEARCH PARSER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtsparser.html b/doc/src/sgml/html/sql-createtsparser.html
new file mode 100644
index 0000000..bb3bf12
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtsparser.html
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TEXT SEARCH PARSER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY" /><link rel="next" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TEXT SEARCH PARSER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETSPARSER"><div class="titlepage"></div><a id="id-1.9.3.90.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TEXT SEARCH PARSER</span></h2><p>CREATE TEXT SEARCH PARSER — define a new text search parser</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TEXT SEARCH PARSER <em class="replaceable"><code>name</code></em> (
+ START = <em class="replaceable"><code>start_function</code></em> ,
+ GETTOKEN = <em class="replaceable"><code>gettoken_function</code></em> ,
+ END = <em class="replaceable"><code>end_function</code></em> ,
+ LEXTYPES = <em class="replaceable"><code>lextypes_function</code></em>
+ [, HEADLINE = <em class="replaceable"><code>headline_function</code></em> ]
+)
+</pre></div><div class="refsect1" id="id-1.9.3.90.5"><h2>Description</h2><p>
+ <code class="command">CREATE TEXT SEARCH PARSER</code> creates a new text search
+ parser. A text search parser defines a method for splitting a text
+ string into tokens and assigning types (categories) to the tokens.
+ A parser is not particularly useful by itself, but must be bound into a
+ text search configuration along with some text search dictionaries
+ to be used for searching.
+ </p><p>
+ If a schema name is given then the text search parser is created in the
+ specified schema. Otherwise it is created in the current schema.
+ </p><p>
+ You must be a superuser to use <code class="command">CREATE TEXT SEARCH PARSER</code>.
+ (This restriction is made because an erroneous text search parser
+ definition could confuse or even crash the server.)
+ </p><p>
+ Refer to <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.90.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the text search parser to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>start_function</code></em></span></dt><dd><p>
+ The name of the start function for the parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>gettoken_function</code></em></span></dt><dd><p>
+ The name of the get-next-token function for the parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>end_function</code></em></span></dt><dd><p>
+ The name of the end function for the parser.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lextypes_function</code></em></span></dt><dd><p>
+ The name of the lextypes function for the parser (a function that
+ returns information about the set of token types it produces).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>headline_function</code></em></span></dt><dd><p>
+ The name of the headline function for the parser (a function that
+ summarizes a set of tokens).
+ </p></dd></dl></div><p>
+ The function names can be schema-qualified if necessary. Argument types
+ are not given, since the argument list for each type of function is
+ predetermined. All except the headline function are required.
+ </p><p>
+ The arguments can appear in any order, not only the one shown above.
+ </p></div><div class="refsect1" id="id-1.9.3.90.7"><h2>Compatibility</h2><p>
+ There is no
+ <code class="command">CREATE TEXT SEARCH PARSER</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.90.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER"><span class="refentrytitle">ALTER TEXT SEARCH PARSER</span></a>, <a class="xref" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER"><span class="refentrytitle">DROP TEXT SEARCH PARSER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TEXT SEARCH DICTIONARY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TEXT SEARCH TEMPLATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtstemplate.html b/doc/src/sgml/html/sql-createtstemplate.html
new file mode 100644
index 0000000..a9beb76
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtstemplate.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TEXT SEARCH TEMPLATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER" /><link rel="next" href="sql-createtransform.html" title="CREATE TRANSFORM" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TEXT SEARCH TEMPLATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtransform.html" title="CREATE TRANSFORM">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETSTEMPLATE"><div class="titlepage"></div><a id="id-1.9.3.91.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TEXT SEARCH TEMPLATE</span></h2><p>CREATE TEXT SEARCH TEMPLATE — define a new text search template</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TEXT SEARCH TEMPLATE <em class="replaceable"><code>name</code></em> (
+ [ INIT = <em class="replaceable"><code>init_function</code></em> , ]
+ LEXIZE = <em class="replaceable"><code>lexize_function</code></em>
+)
+</pre></div><div class="refsect1" id="id-1.9.3.91.5"><h2>Description</h2><p>
+ <code class="command">CREATE TEXT SEARCH TEMPLATE</code> creates a new text search
+ template. Text search templates define the functions that implement
+ text search dictionaries. A template is not useful by itself, but must
+ be instantiated as a dictionary to be used. The dictionary typically
+ specifies parameters to be given to the template functions.
+ </p><p>
+ If a schema name is given then the text search template is created in the
+ specified schema. Otherwise it is created in the current schema.
+ </p><p>
+ You must be a superuser to use <code class="command">CREATE TEXT SEARCH
+ TEMPLATE</code>. This restriction is made because an erroneous text
+ search template definition could confuse or even crash the server.
+ The reason for separating templates from dictionaries is that a template
+ encapsulates the <span class="quote">“<span class="quote">unsafe</span>”</span> aspects of defining a dictionary.
+ The parameters that can be set when defining a dictionary are safe for
+ unprivileged users to set, and so creating a dictionary need not be a
+ privileged operation.
+ </p><p>
+ Refer to <a class="xref" href="textsearch.html" title="Chapter 12. Full Text Search">Chapter 12</a> for further information.
+ </p></div><div class="refsect1" id="id-1.9.3.91.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the text search template to be created. The name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>init_function</code></em></span></dt><dd><p>
+ The name of the init function for the template.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lexize_function</code></em></span></dt><dd><p>
+ The name of the lexize function for the template.
+ </p></dd></dl></div><p>
+ The function names can be schema-qualified if necessary. Argument types
+ are not given, since the argument list for each type of function is
+ predetermined. The lexize function is required, but the init function
+ is optional.
+ </p><p>
+ The arguments can appear in any order, not only the one shown above.
+ </p></div><div class="refsect1" id="id-1.9.3.91.7"><h2>Compatibility</h2><p>
+ There is no
+ <code class="command">CREATE TEXT SEARCH TEMPLATE</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.91.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE"><span class="refentrytitle">ALTER TEXT SEARCH TEMPLATE</span></a>, <a class="xref" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE"><span class="refentrytitle">DROP TEXT SEARCH TEMPLATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtransform.html" title="CREATE TRANSFORM">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TEXT SEARCH PARSER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TRANSFORM</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createtype.html b/doc/src/sgml/html/sql-createtype.html
new file mode 100644
index 0000000..207459e
--- /dev/null
+++ b/doc/src/sgml/html/sql-createtype.html
@@ -0,0 +1,655 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TYPE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtrigger.html" title="CREATE TRIGGER" /><link rel="next" href="sql-createuser.html" title="CREATE USER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TYPE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtrigger.html" title="CREATE TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createuser.html" title="CREATE USER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETYPE"><div class="titlepage"></div><a id="id-1.9.3.94.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TYPE</span></h2><p>CREATE TYPE — define a new data type</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE TYPE <em class="replaceable"><code>name</code></em> AS
+ ( [ <em class="replaceable"><code>attribute_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [, ... ] ] )
+
+CREATE TYPE <em class="replaceable"><code>name</code></em> AS ENUM
+ ( [ '<em class="replaceable"><code>label</code></em>' [, ... ] ] )
+
+CREATE TYPE <em class="replaceable"><code>name</code></em> AS RANGE (
+ SUBTYPE = <em class="replaceable"><code>subtype</code></em>
+ [ , SUBTYPE_OPCLASS = <em class="replaceable"><code>subtype_operator_class</code></em> ]
+ [ , COLLATION = <em class="replaceable"><code>collation</code></em> ]
+ [ , CANONICAL = <em class="replaceable"><code>canonical_function</code></em> ]
+ [ , SUBTYPE_DIFF = <em class="replaceable"><code>subtype_diff_function</code></em> ]
+ [ , MULTIRANGE_TYPE_NAME = <em class="replaceable"><code>multirange_type_name</code></em> ]
+)
+
+CREATE TYPE <em class="replaceable"><code>name</code></em> (
+ INPUT = <em class="replaceable"><code>input_function</code></em>,
+ OUTPUT = <em class="replaceable"><code>output_function</code></em>
+ [ , RECEIVE = <em class="replaceable"><code>receive_function</code></em> ]
+ [ , SEND = <em class="replaceable"><code>send_function</code></em> ]
+ [ , TYPMOD_IN = <em class="replaceable"><code>type_modifier_input_function</code></em> ]
+ [ , TYPMOD_OUT = <em class="replaceable"><code>type_modifier_output_function</code></em> ]
+ [ , ANALYZE = <em class="replaceable"><code>analyze_function</code></em> ]
+ [ , SUBSCRIPT = <em class="replaceable"><code>subscript_function</code></em> ]
+ [ , INTERNALLENGTH = { <em class="replaceable"><code>internallength</code></em> | VARIABLE } ]
+ [ , PASSEDBYVALUE ]
+ [ , ALIGNMENT = <em class="replaceable"><code>alignment</code></em> ]
+ [ , STORAGE = <em class="replaceable"><code>storage</code></em> ]
+ [ , LIKE = <em class="replaceable"><code>like_type</code></em> ]
+ [ , CATEGORY = <em class="replaceable"><code>category</code></em> ]
+ [ , PREFERRED = <em class="replaceable"><code>preferred</code></em> ]
+ [ , DEFAULT = <em class="replaceable"><code>default</code></em> ]
+ [ , ELEMENT = <em class="replaceable"><code>element</code></em> ]
+ [ , DELIMITER = <em class="replaceable"><code>delimiter</code></em> ]
+ [ , COLLATABLE = <em class="replaceable"><code>collatable</code></em> ]
+)
+
+CREATE TYPE <em class="replaceable"><code>name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.94.5"><h2>Description</h2><p>
+ <code class="command">CREATE TYPE</code> registers a new data type for use in
+ the current database. The user who defines a type becomes its
+ owner.
+ </p><p>
+ If a schema name is given then the type is created in the specified
+ schema. Otherwise it is created in the current schema. The type
+ name must be distinct from the name of any existing type or domain
+ in the same schema. (Because tables have associated data types,
+ the type name must also be distinct from the name of any existing
+ table in the same schema.)
+ </p><p>
+ There are five forms of <code class="command">CREATE TYPE</code>, as shown in the
+ syntax synopsis above. They respectively create a <em class="firstterm">composite
+ type</em>, an <em class="firstterm">enum type</em>, a <em class="firstterm">range type</em>, a
+ <em class="firstterm">base type</em>, or a <em class="firstterm">shell type</em>. The first four
+ of these are discussed in turn below. A shell type is simply a placeholder
+ for a type to be defined later; it is created by issuing <code class="command">CREATE
+ TYPE</code> with no parameters except for the type name. Shell types
+ are needed as forward references when creating range types and base types,
+ as discussed in those sections.
+ </p><div class="refsect2" id="id-1.9.3.94.5.5"><h3>Composite Types</h3><p>
+ The first form of <code class="command">CREATE TYPE</code>
+ creates a composite type.
+ The composite type is specified by a list of attribute names and data types.
+ An attribute's collation can be specified too, if its data type is
+ collatable. A composite type is essentially the same as the row type
+ of a table, but using <code class="command">CREATE TYPE</code> avoids the need to
+ create an actual table when all that is wanted is to define a type.
+ A stand-alone composite type is useful, for example, as the argument or
+ return type of a function.
+ </p><p>
+ To be able to create a composite type, you must
+ have <code class="literal">USAGE</code> privilege on all attribute types.
+ </p></div><div class="refsect2" id="SQL-CREATETYPE-ENUM"><h3>Enumerated Types</h3><p>
+ The second form of <code class="command">CREATE TYPE</code> creates an enumerated
+ (enum) type, as described in <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a>.
+ Enum types take a list of quoted labels, each of which
+ must be less than <code class="symbol">NAMEDATALEN</code> bytes long (64 bytes in a
+ standard <span class="productname">PostgreSQL</span> build). (It is possible to
+ create an enumerated type with zero labels, but such a type cannot be used
+ to hold values before at least one label is added using <a class="link" href="sql-altertype.html" title="ALTER TYPE"><code class="command">ALTER TYPE</code></a>.)
+ </p></div><div class="refsect2" id="SQL-CREATETYPE-RANGE"><h3>Range Types</h3><p>
+ The third form of <code class="command">CREATE TYPE</code> creates a new
+ range type, as described in <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>.
+ </p><p>
+ The range type's <em class="replaceable"><code>subtype</code></em> can
+ be any type with an associated b-tree operator class (to determine the
+ ordering of values for the range type). Normally the subtype's default
+ b-tree operator class is used to determine ordering; to use a non-default
+ operator class, specify its name with <em class="replaceable"><code>subtype_opclass</code></em>. If the subtype is
+ collatable, and you want to use a non-default collation in the range's
+ ordering, specify the desired collation with the <em class="replaceable"><code>collation</code></em> option.
+ </p><p>
+ The optional <em class="replaceable"><code>canonical</code></em>
+ function must take one argument of the range type being defined, and
+ return a value of the same type. This is used to convert range values
+ to a canonical form, when applicable. See <a class="xref" href="rangetypes.html#RANGETYPES-DEFINING" title="8.17.8. Defining New Range Types">Section 8.17.8</a> for more information. Creating a
+ <em class="replaceable"><code>canonical</code></em> function
+ is a bit tricky, since it must be defined before the range type can be
+ declared. To do this, you must first create a shell type, which is a
+ placeholder type that has no properties except a name and an
+ owner. This is done by issuing the command <code class="literal">CREATE TYPE
+ <em class="replaceable"><code>name</code></em></code>, with no additional parameters. Then
+ the function can be declared using the shell type as argument and result,
+ and finally the range type can be declared using the same name. This
+ automatically replaces the shell type entry with a valid range type.
+ </p><p>
+ The optional <em class="replaceable"><code>subtype_diff</code></em>
+ function must take two values of the
+ <em class="replaceable"><code>subtype</code></em> type as argument,
+ and return a <code class="type">double precision</code> value representing the
+ difference between the two given values. While this is optional,
+ providing it allows much greater efficiency of GiST indexes on columns of
+ the range type. See <a class="xref" href="rangetypes.html#RANGETYPES-DEFINING" title="8.17.8. Defining New Range Types">Section 8.17.8</a> for more
+ information.
+ </p><p>
+ The optional <em class="replaceable"><code>multirange_type_name</code></em>
+ parameter specifies the name of the corresponding multirange type. If not
+ specified, this name is chosen automatically as follows.
+ If the range type name contains the substring <code class="literal">range</code>, then
+ the multirange type name is formed by replacement of the <code class="literal">range</code>
+ substring with <code class="literal">multirange</code> in the range
+ type name. Otherwise, the multirange type name is formed by appending a
+ <code class="literal">_multirange</code> suffix to the range type name.
+ </p></div><div class="refsect2" id="id-1.9.3.94.5.8"><h3>Base Types</h3><p>
+ The fourth form of <code class="command">CREATE TYPE</code> creates a new base type
+ (scalar type). To create a new base type, you must be a superuser.
+ (This restriction is made because an erroneous type definition could
+ confuse or even crash the server.)
+ </p><p>
+ The parameters can appear in any order, not only that
+ illustrated above, and most are optional. You must register
+ two or more functions (using <code class="command">CREATE FUNCTION</code>) before
+ defining the type. The support functions
+ <em class="replaceable"><code>input_function</code></em> and
+ <em class="replaceable"><code>output_function</code></em>
+ are required, while the functions
+ <em class="replaceable"><code>receive_function</code></em>,
+ <em class="replaceable"><code>send_function</code></em>,
+ <em class="replaceable"><code>type_modifier_input_function</code></em>,
+ <em class="replaceable"><code>type_modifier_output_function</code></em>,
+ <em class="replaceable"><code>analyze_function</code></em>, and
+ <em class="replaceable"><code>subscript_function</code></em>
+ are optional. Generally these functions have to be coded in C
+ or another low-level language.
+ </p><p>
+ The <em class="replaceable"><code>input_function</code></em>
+ converts the type's external textual representation to the internal
+ representation used by the operators and functions defined for the type.
+ <em class="replaceable"><code>output_function</code></em>
+ performs the reverse transformation. The input function can be
+ declared as taking one argument of type <code class="type">cstring</code>,
+ or as taking three arguments of types
+ <code class="type">cstring</code>, <code class="type">oid</code>, <code class="type">integer</code>.
+ The first argument is the input text as a C string, the second
+ argument is the type's own OID (except for array types, which instead
+ receive their element type's OID),
+ and the third is the <code class="literal">typmod</code> of the destination column, if known
+ (-1 will be passed if not).
+ The input function must return a value of the data type itself.
+ Usually, an input function should be declared STRICT; if it is not,
+ it will be called with a NULL first parameter when reading a NULL
+ input value. The function must still return NULL in this case, unless
+ it raises an error.
+ (This case is mainly meant to support domain input functions, which
+ might need to reject NULL inputs.)
+ The output function must be
+ declared as taking one argument of the new data type.
+ The output function must return type <code class="type">cstring</code>.
+ Output functions are not invoked for NULL values.
+ </p><p>
+ The optional <em class="replaceable"><code>receive_function</code></em>
+ converts the type's external binary representation to the internal
+ representation. If this function is not supplied, the type cannot
+ participate in binary input. The binary representation should be
+ chosen to be cheap to convert to internal form, while being reasonably
+ portable. (For example, the standard integer data types use network
+ byte order as the external binary representation, while the internal
+ representation is in the machine's native byte order.) The receive
+ function should perform adequate checking to ensure that the value is
+ valid.
+ The receive function can be declared as taking one argument of type
+ <code class="type">internal</code>, or as taking three arguments of types
+ <code class="type">internal</code>, <code class="type">oid</code>, <code class="type">integer</code>.
+ The first argument is a pointer to a <code class="type">StringInfo</code> buffer
+ holding the received byte string; the optional arguments are the
+ same as for the text input function.
+ The receive function must return a value of the data type itself.
+ Usually, a receive function should be declared STRICT; if it is not,
+ it will be called with a NULL first parameter when reading a NULL
+ input value. The function must still return NULL in this case, unless
+ it raises an error.
+ (This case is mainly meant to support domain receive functions, which
+ might need to reject NULL inputs.)
+ Similarly, the optional
+ <em class="replaceable"><code>send_function</code></em> converts
+ from the internal representation to the external binary representation.
+ If this function is not supplied, the type cannot participate in binary
+ output. The send function must be
+ declared as taking one argument of the new data type.
+ The send function must return type <code class="type">bytea</code>.
+ Send functions are not invoked for NULL values.
+ </p><p>
+ You should at this point be wondering how the input and output functions
+ can be declared to have results or arguments of the new type, when they
+ have to be created before the new type can be created. The answer is that
+ the type should first be defined as a <em class="firstterm">shell type</em>, which is a
+ placeholder type that has no properties except a name and an owner. This
+ is done by issuing the command <code class="literal">CREATE TYPE
+ <em class="replaceable"><code>name</code></em></code>, with no additional parameters. Then the
+ C I/O functions can be defined referencing the shell type. Finally,
+ <code class="command">CREATE TYPE</code> with a full definition replaces the shell entry
+ with a complete, valid type definition, after which the new type can be
+ used normally.
+ </p><p>
+ The optional
+ <em class="replaceable"><code>type_modifier_input_function</code></em>
+ and <em class="replaceable"><code>type_modifier_output_function</code></em>
+ are needed if the type supports modifiers, that is optional constraints
+ attached to a type declaration, such as <code class="literal">char(5)</code> or
+ <code class="literal">numeric(30,2)</code>. <span class="productname">PostgreSQL</span> allows
+ user-defined types to take one or more simple constants or identifiers as
+ modifiers. However, this information must be capable of being packed into a
+ single non-negative integer value for storage in the system catalogs. The
+ <em class="replaceable"><code>type_modifier_input_function</code></em>
+ is passed the declared modifier(s) in the form of a <code class="type">cstring</code>
+ array. It must check the values for validity (throwing an error if they
+ are wrong), and if they are correct, return a single non-negative
+ <code class="type">integer</code> value that will be stored as the column <span class="quote">“<span class="quote">typmod</span>”</span>.
+ Type modifiers will be rejected if the type does not have a
+ <em class="replaceable"><code>type_modifier_input_function</code></em>.
+ The <em class="replaceable"><code>type_modifier_output_function</code></em>
+ converts the internal integer typmod value back to the correct form for
+ user display. It must return a <code class="type">cstring</code> value that is the exact
+ string to append to the type name; for example <code class="type">numeric</code>'s
+ function might return <code class="literal">(30,2)</code>.
+ It is allowed to omit the
+ <em class="replaceable"><code>type_modifier_output_function</code></em>,
+ in which case the default display format is just the stored typmod integer
+ value enclosed in parentheses.
+ </p><p>
+ The optional <em class="replaceable"><code>analyze_function</code></em>
+ performs type-specific statistics collection for columns of the data type.
+ By default, <code class="command">ANALYZE</code> will attempt to gather statistics using
+ the type's <span class="quote">“<span class="quote">equals</span>”</span> and <span class="quote">“<span class="quote">less-than</span>”</span> operators, if there
+ is a default b-tree operator class for the type. For non-scalar types
+ this behavior is likely to be unsuitable, so it can be overridden by
+ specifying a custom analysis function. The analysis function must be
+ declared to take a single argument of type <code class="type">internal</code>, and return
+ a <code class="type">boolean</code> result. The detailed API for analysis functions appears
+ in <code class="filename">src/include/commands/vacuum.h</code>.
+ </p><p>
+ The optional <em class="replaceable"><code>subscript_function</code></em>
+ allows the data type to be subscripted in SQL commands. Specifying this
+ function does not cause the type to be considered a <span class="quote">“<span class="quote">true</span>”</span>
+ array type; for example, it will not be a candidate for the result type
+ of <code class="literal">ARRAY[]</code> constructs. But if subscripting a value
+ of the type is a natural notation for extracting data from it, then
+ a <em class="replaceable"><code>subscript_function</code></em> can
+ be written to define what that means. The subscript function must be
+ declared to take a single argument of type <code class="type">internal</code>, and
+ return an <code class="type">internal</code> result, which is a pointer to a struct
+ of methods (functions) that implement subscripting.
+ The detailed API for subscript functions appears
+ in <code class="filename">src/include/nodes/subscripting.h</code>.
+ It may also be useful to read the array implementation
+ in <code class="filename">src/backend/utils/adt/arraysubs.c</code>,
+ or the simpler code
+ in <code class="filename">contrib/hstore/hstore_subs.c</code>.
+ Additional information appears in
+ <a class="xref" href="sql-createtype.html#SQL-CREATETYPE-ARRAY" title="Array Types">Array Types</a> below.
+ </p><p>
+ While the details of the new type's internal representation are only
+ known to the I/O functions and other functions you create to work with
+ the type, there are several properties of the internal representation
+ that must be declared to <span class="productname">PostgreSQL</span>.
+ Foremost of these is
+ <em class="replaceable"><code>internallength</code></em>.
+ Base data types can be fixed-length, in which case
+ <em class="replaceable"><code>internallength</code></em> is a
+ positive integer, or variable-length, indicated by setting
+ <em class="replaceable"><code>internallength</code></em>
+ to <code class="literal">VARIABLE</code>. (Internally, this is represented
+ by setting <code class="literal">typlen</code> to -1.) The internal representation of all
+ variable-length types must start with a 4-byte integer giving the total
+ length of this value of the type. (Note that the length field is often
+ encoded, as described in <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>; it's unwise
+ to access it directly.)
+ </p><p>
+ The optional flag <code class="literal">PASSEDBYVALUE</code> indicates that
+ values of this data type are passed by value, rather than by
+ reference. Types passed by value must be fixed-length, and their internal
+ representation cannot be larger than the size of the <code class="type">Datum</code> type
+ (4 bytes on some machines, 8 bytes on others).
+ </p><p>
+ The <em class="replaceable"><code>alignment</code></em> parameter
+ specifies the storage alignment required for the data type. The
+ allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
+ Note that variable-length types must have an alignment of at least
+ 4, since they necessarily contain an <code class="type">int4</code> as their first component.
+ </p><p>
+ The <em class="replaceable"><code>storage</code></em> parameter
+ allows selection of storage strategies for variable-length data
+ types. (Only <code class="literal">plain</code> is allowed for fixed-length
+ types.) <code class="literal">plain</code> specifies that data of the type
+ will always be stored in-line and not compressed.
+ <code class="literal">extended</code> specifies that the system will first
+ try to compress a long data value, and will move the value out of
+ the main table row if it's still too long.
+ <code class="literal">external</code> allows the value to be moved out of the
+ main table, but the system will not try to compress it.
+ <code class="literal">main</code> allows compression, but discourages moving
+ the value out of the main table. (Data items with this storage
+ strategy might still be moved out of the main table if there is no
+ other way to make a row fit, but they will be kept in the main
+ table preferentially over <code class="literal">extended</code> and
+ <code class="literal">external</code> items.)
+ </p><p>
+ All <em class="replaceable"><code>storage</code></em> values other
+ than <code class="literal">plain</code> imply that the functions of the data type
+ can handle values that have been <em class="firstterm">toasted</em>, as described
+ in <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a> and <a class="xref" href="xtypes.html#XTYPES-TOAST" title="38.13.1. TOAST Considerations">Section 38.13.1</a>.
+ The specific other value given merely determines the default TOAST
+ storage strategy for columns of a toastable data type; users can pick
+ other strategies for individual columns using <code class="literal">ALTER TABLE
+ SET STORAGE</code>.
+ </p><p>
+ The <em class="replaceable"><code>like_type</code></em> parameter
+ provides an alternative method for specifying the basic representation
+ properties of a data type: copy them from some existing type. The values of
+ <em class="replaceable"><code>internallength</code></em>,
+ <em class="replaceable"><code>passedbyvalue</code></em>,
+ <em class="replaceable"><code>alignment</code></em>, and
+ <em class="replaceable"><code>storage</code></em> are copied from the
+ named type. (It is possible, though usually undesirable, to override
+ some of these values by specifying them along with the <code class="literal">LIKE</code>
+ clause.) Specifying representation this way is especially useful when
+ the low-level implementation of the new type <span class="quote">“<span class="quote">piggybacks</span>”</span> on an
+ existing type in some fashion.
+ </p><p>
+ The <em class="replaceable"><code>category</code></em> and
+ <em class="replaceable"><code>preferred</code></em> parameters can be
+ used to help control which implicit cast will be applied in ambiguous
+ situations. Each data type belongs to a category named by a single ASCII
+ character, and each type is either <span class="quote">“<span class="quote">preferred</span>”</span> or not within its
+ category. The parser will prefer casting to preferred types (but only from
+ other types within the same category) when this rule is helpful in
+ resolving overloaded functions or operators. For more details see <a class="xref" href="typeconv.html" title="Chapter 10. Type Conversion">Chapter 10</a>. For types that have no implicit casts to or from any
+ other types, it is sufficient to leave these settings at the defaults.
+ However, for a group of related types that have implicit casts, it is often
+ helpful to mark them all as belonging to a category and select one or two
+ of the <span class="quote">“<span class="quote">most general</span>”</span> types as being preferred within the category.
+ The <em class="replaceable"><code>category</code></em> parameter is
+ especially useful when adding a user-defined type to an existing built-in
+ category, such as the numeric or string types. However, it is also
+ possible to create new entirely-user-defined type categories. Select any
+ ASCII character other than an upper-case letter to name such a category.
+ </p><p>
+ A default value can be specified, in case a user wants columns of the
+ data type to default to something other than the null value.
+ Specify the default with the <code class="literal">DEFAULT</code> key word.
+ (Such a default can be overridden by an explicit <code class="literal">DEFAULT</code>
+ clause attached to a particular column.)
+ </p><p>
+ To indicate that a type is a fixed-length array type,
+ specify the type of the array
+ elements using the <code class="literal">ELEMENT</code> key word. For example, to
+ define an array of 4-byte integers (<code class="type">int4</code>), specify
+ <code class="literal">ELEMENT = int4</code>. For more details,
+ see <a class="xref" href="sql-createtype.html#SQL-CREATETYPE-ARRAY" title="Array Types">Array Types</a> below.
+ </p><p>
+ To indicate the delimiter to be used between values in the external
+ representation of arrays of this type, <em class="replaceable"><code>delimiter</code></em> can be
+ set to a specific character. The default delimiter is the comma
+ (<code class="literal">,</code>). Note that the delimiter is associated
+ with the array element type, not the array type itself.
+ </p><p>
+ If the optional Boolean
+ parameter <em class="replaceable"><code>collatable</code></em>
+ is true, column definitions and expressions of the type may carry
+ collation information through use of
+ the <code class="literal">COLLATE</code> clause. It is up to the
+ implementations of the functions operating on the type to actually
+ make use of the collation information; this does not happen
+ automatically merely by marking the type collatable.
+ </p></div><div class="refsect2" id="SQL-CREATETYPE-ARRAY"><h3>Array Types</h3><p>
+ Whenever a user-defined type is created,
+ <span class="productname">PostgreSQL</span> automatically creates an
+ associated array type, whose name consists of the element type's
+ name prepended with an underscore, and truncated if necessary to keep
+ it less than <code class="symbol">NAMEDATALEN</code> bytes long. (If the name
+ so generated collides with an existing type name, the process is
+ repeated until a non-colliding name is found.)
+ This implicitly-created array type is variable length and uses the
+ built-in input and output functions <code class="literal">array_in</code> and
+ <code class="literal">array_out</code>. Furthermore, this type is what the system
+ uses for constructs such as <code class="literal">ARRAY[]</code> over the
+ user-defined type. The array type tracks any changes in its
+ element type's owner or schema, and is dropped if the element type is.
+ </p><p>
+ You might reasonably ask why there is an <code class="option">ELEMENT</code>
+ option, if the system makes the correct array type automatically.
+ The main case where it's useful to use <code class="option">ELEMENT</code> is when you are
+ making a fixed-length type that happens to be internally an array of a number of
+ identical things, and you want to allow these things to be accessed
+ directly by subscripting, in addition to whatever operations you plan
+ to provide for the type as a whole. For example, type <code class="type">point</code>
+ is represented as just two floating-point numbers, which can be accessed
+ using <code class="literal">point[0]</code> and <code class="literal">point[1]</code>.
+ Note that
+ this facility only works for fixed-length types whose internal form
+ is exactly a sequence of identical fixed-length fields.
+ For historical reasons (i.e., this is clearly wrong but it's far too
+ late to change it), subscripting of fixed-length array types starts from
+ zero, rather than from one as for variable-length arrays.
+ </p><p>
+ Specifying the <code class="option">SUBSCRIPT</code> option allows a data type to
+ be subscripted, even though the system does not otherwise regard it as
+ an array type. The behavior just described for fixed-length arrays is
+ actually implemented by the <code class="option">SUBSCRIPT</code> handler
+ function <code class="function">raw_array_subscript_handler</code>, which is
+ used automatically if you specify <code class="option">ELEMENT</code> for a
+ fixed-length type without also writing <code class="option">SUBSCRIPT</code>.
+ </p><p>
+ When specifying a custom <code class="option">SUBSCRIPT</code> function, it is
+ not necessary to specify <code class="option">ELEMENT</code> unless
+ the <code class="option">SUBSCRIPT</code> handler function needs to
+ consult <code class="structfield">typelem</code> to find out what to return.
+ Be aware that specifying <code class="option">ELEMENT</code> causes the system to
+ assume that the new type contains, or is somehow physically dependent on,
+ the element type; thus for example changing properties of the element
+ type won't be allowed if there are any columns of the dependent type.
+ </p></div></div><div class="refsect1" id="id-1.9.3.94.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a type to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>attribute_name</code></em></span></dt><dd><p>
+ The name of an attribute (column) for the composite type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The name of an existing data type to become a column of the
+ composite type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collation</code></em></span></dt><dd><p>
+ The name of an existing collation to be associated with a column of
+ a composite type, or with a range type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>label</code></em></span></dt><dd><p>
+ A string literal representing the textual label associated with
+ one value of an enum type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>subtype</code></em></span></dt><dd><p>
+ The name of the element type that the range type will represent ranges
+ of.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>subtype_operator_class</code></em></span></dt><dd><p>
+ The name of a b-tree operator class for the subtype.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>canonical_function</code></em></span></dt><dd><p>
+ The name of the canonicalization function for the range type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>subtype_diff_function</code></em></span></dt><dd><p>
+ The name of a difference function for the subtype.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>multirange_type_name</code></em></span></dt><dd><p>
+ The name of the corresponding multirange type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>input_function</code></em></span></dt><dd><p>
+ The name of a function that converts data from the type's
+ external textual form to its internal form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_function</code></em></span></dt><dd><p>
+ The name of a function that converts data from the type's
+ internal form to its external textual form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>receive_function</code></em></span></dt><dd><p>
+ The name of a function that converts data from the type's
+ external binary form to its internal form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>send_function</code></em></span></dt><dd><p>
+ The name of a function that converts data from the type's
+ internal form to its external binary form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>type_modifier_input_function</code></em></span></dt><dd><p>
+ The name of a function that converts an array of modifier(s) for the type
+ into internal form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>type_modifier_output_function</code></em></span></dt><dd><p>
+ The name of a function that converts the internal form of the type's
+ modifier(s) to external textual form.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>analyze_function</code></em></span></dt><dd><p>
+ The name of a function that performs statistical analysis for the
+ data type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>subscript_function</code></em></span></dt><dd><p>
+ The name of a function that defines what subscripting a value of the
+ data type does.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>internallength</code></em></span></dt><dd><p>
+ A numeric constant that specifies the length in bytes of the new
+ type's internal representation. The default assumption is that
+ it is variable-length.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>alignment</code></em></span></dt><dd><p>
+ The storage alignment requirement of the data type. If specified,
+ it must be <code class="literal">char</code>, <code class="literal">int2</code>,
+ <code class="literal">int4</code>, or <code class="literal">double</code>; the
+ default is <code class="literal">int4</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>storage</code></em></span></dt><dd><p>
+ The storage strategy for the data type. If specified, must be
+ <code class="literal">plain</code>, <code class="literal">external</code>,
+ <code class="literal">extended</code>, or <code class="literal">main</code>; the
+ default is <code class="literal">plain</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>like_type</code></em></span></dt><dd><p>
+ The name of an existing data type that the new type will have the
+ same representation as. The values of
+ <em class="replaceable"><code>internallength</code></em>,
+ <em class="replaceable"><code>passedbyvalue</code></em>,
+ <em class="replaceable"><code>alignment</code></em>, and
+ <em class="replaceable"><code>storage</code></em>
+ are copied from that type, unless overridden by explicit
+ specification elsewhere in this <code class="command">CREATE TYPE</code> command.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>category</code></em></span></dt><dd><p>
+ The category code (a single ASCII character) for this type.
+ The default is <code class="literal">'U'</code> for <span class="quote">“<span class="quote">user-defined type</span>”</span>.
+ Other standard category codes can be found in
+ <a class="xref" href="catalog-pg-type.html#CATALOG-TYPCATEGORY-TABLE" title="Table 53.65. typcategory Codes">Table 53.65</a>. You may also choose
+ other ASCII characters in order to create custom categories.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>preferred</code></em></span></dt><dd><p>
+ True if this type is a preferred type within its type category,
+ else false. The default is false. Be very careful about creating
+ a new preferred type within an existing type category, as this
+ could cause surprising changes in behavior.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>default</code></em></span></dt><dd><p>
+ The default value for the data type. If this is omitted, the
+ default is null.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>element</code></em></span></dt><dd><p>
+ The type being created is an array; this specifies the type of
+ the array elements.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>delimiter</code></em></span></dt><dd><p>
+ The delimiter character to be used between values in arrays made
+ of this type.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collatable</code></em></span></dt><dd><p>
+ True if this type's operations can use collation information.
+ The default is false.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATETYPE-NOTES"><h2>Notes</h2><p>
+ Because there are no restrictions on use of a data type once it's been
+ created, creating a base type or range type is tantamount to granting
+ public execute permission on the functions mentioned in the type definition.
+ This is usually
+ not an issue for the sorts of functions that are useful in a type
+ definition. But you might want to think twice before designing a type
+ in a way that would require <span class="quote">“<span class="quote">secret</span>”</span> information to be used
+ while converting it to or from external form.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> version 8.3, the name of
+ a generated array type was always exactly the element type's name with one
+ underscore character (<code class="literal">_</code>) prepended. (Type names were
+ therefore restricted in length to one fewer character than other names.)
+ While this is still usually the case, the array type name may vary from
+ this in case of maximum-length names or collisions with user type names
+ that begin with underscore. Writing code that depends on this convention
+ is therefore deprecated. Instead, use
+ <code class="structname">pg_type</code>.<code class="structfield">typarray</code> to locate the array type
+ associated with a given type.
+ </p><p>
+ It may be advisable to avoid using type and table names that begin with
+ underscore. While the server will change generated array type names to
+ avoid collisions with user-given names, there is still risk of confusion,
+ particularly with old client software that may assume that type names
+ beginning with underscores always represent arrays.
+ </p><p>
+ Before <span class="productname">PostgreSQL</span> version 8.2, the shell-type
+ creation syntax
+ <code class="literal">CREATE TYPE <em class="replaceable"><code>name</code></em></code> did not exist.
+ The way to create a new base type was to create its input function first.
+ In this approach, <span class="productname">PostgreSQL</span> will first see
+ the name of the new data type as the return type of the input function.
+ The shell type is implicitly created in this situation, and then it
+ can be referenced in the definitions of the remaining I/O functions.
+ This approach still works, but is deprecated and might be disallowed in
+ some future release. Also, to avoid accidentally cluttering
+ the catalogs with shell types as a result of simple typos in function
+ definitions, a shell type will only be made this way when the input
+ function is written in C.
+ </p></div><div class="refsect1" id="id-1.9.3.94.8"><h2>Examples</h2><p>
+ This example creates a composite type and uses it in
+ a function definition:
+</p><pre class="programlisting">
+CREATE TYPE compfoo AS (f1 int, f2 text);
+
+CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$
+ SELECT fooid, fooname FROM foo
+$$ LANGUAGE SQL;
+</pre><p>
+ </p><p>
+ This example creates an enumerated type and uses it in
+ a table definition:
+</p><pre class="programlisting">
+CREATE TYPE bug_status AS ENUM ('new', 'open', 'closed');
+
+CREATE TABLE bug (
+ id serial,
+ description text,
+ status bug_status
+);
+</pre><p>
+ </p><p>
+ This example creates a range type:
+</p><pre class="programlisting">
+CREATE TYPE float8_range AS RANGE (subtype = float8, subtype_diff = float8mi);
+</pre><p>
+ </p><p>
+ This example creates the base data type <code class="type">box</code> and then uses the
+ type in a table definition:
+</p><pre class="programlisting">
+CREATE TYPE box;
+
+CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS ... ;
+CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS ... ;
+
+CREATE TYPE box (
+ INTERNALLENGTH = 16,
+ INPUT = my_box_in_function,
+ OUTPUT = my_box_out_function
+);
+
+CREATE TABLE myboxes (
+ id integer,
+ description box
+);
+</pre><p>
+ </p><p>
+ If the internal structure of <code class="type">box</code> were an array of four
+ <code class="type">float4</code> elements, we might instead use:
+</p><pre class="programlisting">
+CREATE TYPE box (
+ INTERNALLENGTH = 16,
+ INPUT = my_box_in_function,
+ OUTPUT = my_box_out_function,
+ ELEMENT = float4
+);
+</pre><p>
+ which would allow a box value's component numbers to be accessed
+ by subscripting. Otherwise the type behaves the same as before.
+ </p><p>
+ This example creates a large object type and uses it in
+ a table definition:
+</p><pre class="programlisting">
+CREATE TYPE bigobj (
+ INPUT = lo_filein, OUTPUT = lo_fileout,
+ INTERNALLENGTH = VARIABLE
+);
+CREATE TABLE big_objs (
+ id integer,
+ obj bigobj
+);
+</pre><p>
+ </p><p>
+ More examples, including suitable input and output functions, are
+ in <a class="xref" href="xtypes.html" title="38.13. User-Defined Types">Section 38.13</a>.
+ </p></div><div class="refsect1" id="SQL-CREATETYPE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The first form of the <code class="command">CREATE TYPE</code> command, which
+ creates a composite type, conforms to the <acronym class="acronym">SQL</acronym> standard.
+ The other forms are <span class="productname">PostgreSQL</span>
+ extensions. The <code class="command">CREATE TYPE</code> statement in
+ the <acronym class="acronym">SQL</acronym> standard also defines other forms that are not
+ implemented in <span class="productname">PostgreSQL</span>.
+ </p><p>
+ The ability to create a composite type with zero attributes is
+ a <span class="productname">PostgreSQL</span>-specific deviation from the
+ standard (analogous to the same case in <code class="command">CREATE TABLE</code>).
+ </p></div><div class="refsect1" id="SQL-CREATETYPE-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertype.html" title="ALTER TYPE"><span class="refentrytitle">ALTER TYPE</span></a>, <a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-droptype.html" title="DROP TYPE"><span class="refentrytitle">DROP TYPE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtrigger.html" title="CREATE TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createuser.html" title="CREATE USER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE USER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createuser.html b/doc/src/sgml/html/sql-createuser.html
new file mode 100644
index 0000000..90839be
--- /dev/null
+++ b/doc/src/sgml/html/sql-createuser.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE USER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtype.html" title="CREATE TYPE" /><link rel="next" href="sql-createusermapping.html" title="CREATE USER MAPPING" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE USER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtype.html" title="CREATE TYPE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createusermapping.html" title="CREATE USER MAPPING">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEUSER"><div class="titlepage"></div><a id="id-1.9.3.95.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE USER</span></h2><p>CREATE USER — define a new database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE USER <em class="replaceable"><code>name</code></em> [ [ WITH ] <em class="replaceable"><code>option</code></em> [ ... ] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ SUPERUSER | NOSUPERUSER
+ | CREATEDB | NOCREATEDB
+ | CREATEROLE | NOCREATEROLE
+ | INHERIT | NOINHERIT
+ | LOGIN | NOLOGIN
+ | REPLICATION | NOREPLICATION
+ | BYPASSRLS | NOBYPASSRLS
+ | CONNECTION LIMIT <em class="replaceable"><code>connlimit</code></em>
+ | [ ENCRYPTED ] PASSWORD '<em class="replaceable"><code>password</code></em>' | PASSWORD NULL
+ | VALID UNTIL '<em class="replaceable"><code>timestamp</code></em>'
+ | IN ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | IN GROUP <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ROLE <em class="replaceable"><code>role_name</code></em> [, ...]
+ | ADMIN <em class="replaceable"><code>role_name</code></em> [, ...]
+ | USER <em class="replaceable"><code>role_name</code></em> [, ...]
+ | SYSID <em class="replaceable"><code>uid</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.95.5"><h2>Description</h2><p>
+ <code class="command">CREATE USER</code> is now an alias for
+ <a class="link" href="sql-createrole.html" title="CREATE ROLE"><code class="command">CREATE ROLE</code></a>.
+ The only difference is that when the command is spelled
+ <code class="command">CREATE USER</code>, <code class="literal">LOGIN</code> is assumed
+ by default, whereas <code class="literal">NOLOGIN</code> is assumed when
+ the command is spelled
+ <code class="command">CREATE ROLE</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.95.6"><h2>Compatibility</h2><p>
+ The <code class="command">CREATE USER</code> statement is a
+ <span class="productname">PostgreSQL</span> extension. The SQL standard
+ leaves the definition of users to the implementation.
+ </p></div><div class="refsect1" id="id-1.9.3.95.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtype.html" title="CREATE TYPE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createusermapping.html" title="CREATE USER MAPPING">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TYPE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE USER MAPPING</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createusermapping.html b/doc/src/sgml/html/sql-createusermapping.html
new file mode 100644
index 0000000..fd621d3
--- /dev/null
+++ b/doc/src/sgml/html/sql-createusermapping.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE USER MAPPING</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createuser.html" title="CREATE USER" /><link rel="next" href="sql-createview.html" title="CREATE VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE USER MAPPING</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createuser.html" title="CREATE USER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createview.html" title="CREATE VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEUSERMAPPING"><div class="titlepage"></div><a id="id-1.9.3.96.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE USER MAPPING</span></h2><p>CREATE USER MAPPING — define a new mapping of a user to a foreign server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE USER MAPPING [ IF NOT EXISTS ] FOR { <em class="replaceable"><code>user_name</code></em> | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC }
+ SERVER <em class="replaceable"><code>server_name</code></em>
+ [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [ , ... ] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.96.5"><h2>Description</h2><p>
+ <code class="command">CREATE USER MAPPING</code> defines a mapping of a user
+ to a foreign server. A user mapping typically encapsulates
+ connection information that a foreign-data wrapper uses together
+ with the information encapsulated by a foreign server to access an
+ external data resource.
+ </p><p>
+ The owner of a foreign server can create user mappings for that
+ server for any user. Also, a user can create a user mapping for
+ their own user name if <code class="literal">USAGE</code> privilege on the server has
+ been granted to the user.
+ </p></div><div class="refsect1" id="id-1.9.3.96.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
+ Do not throw an error if a mapping of the given user to the given foreign
+ server already exists. A notice is issued in this case. Note that there
+ is no guarantee that the existing user mapping is anything like the one
+ that would have been created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ The name of an existing user that is mapped to foreign server.
+ <code class="literal">CURRENT_ROLE</code>, <code class="literal">CURRENT_USER</code>, and <code class="literal">USER</code> match the name of
+ the current user. When <code class="literal">PUBLIC</code> is specified, a
+ so-called public mapping is created that is used when no
+ user-specific mapping is applicable.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ The name of an existing server for which the user mapping is
+ to be created.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] )</code></span></dt><dd><p>
+ This clause specifies the options of the user mapping. The
+ options typically define the actual user name and password of
+ the mapping. Option names must be unique. The allowed option
+ names and values are specific to the server's foreign-data wrapper.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.96.7"><h2>Examples</h2><p>
+ Create a user mapping for user <code class="literal">bob</code>, server <code class="literal">foo</code>:
+</p><pre class="programlisting">
+CREATE USER MAPPING FOR bob SERVER foo OPTIONS (user 'bob', password 'secret');
+</pre></div><div class="refsect1" id="id-1.9.3.96.8"><h2>Compatibility</h2><p>
+ <code class="command">CREATE USER MAPPING</code> conforms to ISO/IEC 9075-9 (SQL/MED).
+ </p></div><div class="refsect1" id="id-1.9.3.96.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterusermapping.html" title="ALTER USER MAPPING"><span class="refentrytitle">ALTER USER MAPPING</span></a>, <a class="xref" href="sql-dropusermapping.html" title="DROP USER MAPPING"><span class="refentrytitle">DROP USER MAPPING</span></a>, <a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createuser.html" title="CREATE USER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createview.html" title="CREATE VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE USER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-createview.html b/doc/src/sgml/html/sql-createview.html
new file mode 100644
index 0000000..9cb89b9
--- /dev/null
+++ b/doc/src/sgml/html/sql-createview.html
@@ -0,0 +1,346 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createusermapping.html" title="CREATE USER MAPPING" /><link rel="next" href="sql-deallocate.html" title="DEALLOCATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createusermapping.html" title="CREATE USER MAPPING">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-deallocate.html" title="DEALLOCATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEVIEW"><div class="titlepage"></div><a id="id-1.9.3.97.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE VIEW</span></h2><p>CREATE VIEW — define a new view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <em class="replaceable"><code>name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ [ WITH ( <em class="replaceable"><code>view_option_name</code></em> [= <em class="replaceable"><code>view_option_value</code></em>] [, ... ] ) ]
+ AS <em class="replaceable"><code>query</code></em>
+ [ WITH [ CASCADED | LOCAL ] CHECK OPTION ]
+</pre></div><div class="refsect1" id="id-1.9.3.97.5"><h2>Description</h2><p>
+ <code class="command">CREATE VIEW</code> defines a view of a query. The view
+ is not physically materialized. Instead, the query is run every time
+ the view is referenced in a query.
+ </p><p>
+ <code class="command">CREATE OR REPLACE VIEW</code> is similar, but if a view
+ of the same name already exists, it is replaced. The new query must
+ generate the same columns that were generated by the existing view query
+ (that is, the same column names in the same order and with the same data
+ types), but it may add additional columns to the end of the list. The
+ calculations giving rise to the output columns may be completely different.
+ </p><p>
+ If a schema name is given (for example, <code class="literal">CREATE VIEW
+ myschema.myview ...</code>) then the view is created in the specified
+ schema. Otherwise it is created in the current schema. Temporary
+ views exist in a special schema, so a schema name cannot be given
+ when creating a temporary view. The name of the view must be
+ distinct from the name of any other relation (table, sequence, index, view,
+ materialized view, or foreign table) in the same schema.
+ </p></div><div class="refsect1" id="id-1.9.3.97.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ If specified, the view is created as a temporary view.
+ Temporary views are automatically dropped at the end of the
+ current session. Existing
+ permanent relations with the same name are not visible to the
+ current session while the temporary view exists, unless they are
+ referenced with schema-qualified names.
+ </p><p>
+ If any of the tables referenced by the view are temporary,
+ the view is created as a temporary view (whether
+ <code class="literal">TEMPORARY</code> is specified or not).
+ </p></dd><dt><span class="term"><code class="literal">RECURSIVE</code>
+ <a id="id-1.9.3.97.6.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Creates a recursive view. The syntax
+</p><pre class="synopsis">
+CREATE RECURSIVE VIEW [ <em class="replaceable"><code>schema</code></em> . ] <em class="replaceable"><code>view_name</code></em> (<em class="replaceable"><code>column_names</code></em>) AS SELECT <em class="replaceable"><code>...</code></em>;
+</pre><p>
+ is equivalent to
+</p><pre class="synopsis">
+CREATE VIEW [ <em class="replaceable"><code>schema</code></em> . ] <em class="replaceable"><code>view_name</code></em> AS WITH RECURSIVE <em class="replaceable"><code>view_name</code></em> (<em class="replaceable"><code>column_names</code></em>) AS (SELECT <em class="replaceable"><code>...</code></em>) SELECT <em class="replaceable"><code>column_names</code></em> FROM <em class="replaceable"><code>view_name</code></em>;
+</pre><p>
+ A view column name list must be specified for a recursive view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a view to be created.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ An optional list of names to be used for columns of the view.
+ If not given, the column names are deduced from the query.
+ </p></dd><dt><span class="term"><code class="literal">WITH ( <em class="replaceable"><code>view_option_name</code></em> [= <em class="replaceable"><code>view_option_value</code></em>] [, ... ] )</code></span></dt><dd><p>
+ This clause specifies optional parameters for a view; the following
+ parameters are supported:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">check_option</code> (<code class="type">enum</code>)</span></dt><dd><p>
+ This parameter may be either <code class="literal">local</code> or
+ <code class="literal">cascaded</code>, and is equivalent to specifying
+ <code class="literal">WITH [ CASCADED | LOCAL ] CHECK OPTION</code> (see below).
+ </p></dd><dt><span class="term"><code class="literal">security_barrier</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This should be used if the view is intended to provide row-level
+ security. See <a class="xref" href="rules-privileges.html" title="41.5. Rules and Privileges">Section 41.5</a> for full details.
+ </p></dd><dt><span class="term"><code class="literal">security_invoker</code> (<code class="type">boolean</code>)</span></dt><dd><p>
+ This option causes the underlying base relations to be checked
+ against the privileges of the user of the view rather than the view
+ owner. See the notes below for full details.
+ </p></dd></dl></div><p>
+
+ All of the above options can be changed on existing views using <a class="link" href="sql-alterview.html" title="ALTER VIEW"><code class="command">ALTER VIEW</code></a>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a> or
+ <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a> command
+ which will provide the columns and rows of the view.
+ </p></dd><dt><span class="term"><code class="literal">WITH [ CASCADED | LOCAL ] CHECK OPTION</code>
+ <a id="id-1.9.3.97.6.2.7.1.2" class="indexterm"></a>
+ <a id="id-1.9.3.97.6.2.7.1.3" class="indexterm"></a>
+ </span></dt><dd><p>
+ This option controls the behavior of automatically updatable views. When
+ this option is specified, <code class="command">INSERT</code> and <code class="command">UPDATE</code>
+ commands on the view will be checked to ensure that new rows satisfy the
+ view-defining condition (that is, the new rows are checked to ensure that
+ they are visible through the view). If they are not, the update will be
+ rejected. If the <code class="literal">CHECK OPTION</code> is not specified,
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> commands on the view are
+ allowed to create rows that are not visible through the view. The
+ following check options are supported:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">LOCAL</code></span></dt><dd><p>
+ New rows are only checked against the conditions defined directly in
+ the view itself. Any conditions defined on underlying base views are
+ not checked (unless they also specify the <code class="literal">CHECK OPTION</code>).
+ </p></dd><dt><span class="term"><code class="literal">CASCADED</code></span></dt><dd><p>
+ New rows are checked against the conditions of the view and all
+ underlying base views. If the <code class="literal">CHECK OPTION</code> is specified,
+ and neither <code class="literal">LOCAL</code> nor <code class="literal">CASCADED</code> is specified,
+ then <code class="literal">CASCADED</code> is assumed.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="literal">CHECK OPTION</code> may not be used with <code class="literal">RECURSIVE</code>
+ views.
+ </p><p>
+ Note that the <code class="literal">CHECK OPTION</code> is only supported on views that
+ are automatically updatable, and do not have <code class="literal">INSTEAD OF</code>
+ triggers or <code class="literal">INSTEAD</code> rules. If an automatically updatable
+ view is defined on top of a base view that has <code class="literal">INSTEAD OF</code>
+ triggers, then the <code class="literal">LOCAL CHECK OPTION</code> may be used to check
+ the conditions on the automatically updatable view, but the conditions
+ on the base view with <code class="literal">INSTEAD OF</code> triggers will not be
+ checked (a cascaded check option will not cascade down to a
+ trigger-updatable view, and any check options defined directly on a
+ trigger-updatable view will be ignored). If the view or any of its base
+ relations has an <code class="literal">INSTEAD</code> rule that causes the
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code> command to be rewritten, then
+ all check options will be ignored in the rewritten query, including any
+ checks from automatically updatable views defined on top of the relation
+ with the <code class="literal">INSTEAD</code> rule.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.97.7"><h2>Notes</h2><p>
+ Use the <a class="link" href="sql-dropview.html" title="DROP VIEW"><code class="command">DROP VIEW</code></a>
+ statement to drop views.
+ </p><p>
+ Be careful that the names and types of the view's columns will be
+ assigned the way you want. For example:
+</p><pre class="programlisting">
+CREATE VIEW vista AS SELECT 'Hello World';
+</pre><p>
+ is bad form because the column name defaults to <code class="literal">?column?</code>;
+ also, the column data type defaults to <code class="type">text</code>, which might not
+ be what you wanted. Better style for a string literal in a view's
+ result is something like:
+</p><pre class="programlisting">
+CREATE VIEW vista AS SELECT text 'Hello World' AS hello;
+</pre><p>
+ </p><p>
+ By default, access to the underlying base relations referenced in the view
+ is determined by the permissions of the view owner. In some cases, this
+ can be used to provide secure but restricted access to the underlying
+ tables. However, not all views are secure against tampering; see <a class="xref" href="rules-privileges.html" title="41.5. Rules and Privileges">Section 41.5</a> for details.
+ </p><p>
+ If the view has the <code class="literal">security_invoker</code> property set to
+ <code class="literal">true</code>, access to the underlying base relations is
+ determined by the permissions of the user executing the query, rather than
+ the view owner. Thus, the user of a security invoker view must have the
+ relevant permissions on the view and its underlying base relations.
+ </p><p>
+ If any of the underlying base relations is a security invoker view, it
+ will be treated as if it had been accessed directly from the original
+ query. Thus, a security invoker view will always check its underlying
+ base relations using the permissions of the current user, even if it is
+ accessed from a view without the <code class="literal">security_invoker</code>
+ property.
+ </p><p>
+ If any of the underlying base relations has
+ <a class="link" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">row-level security</a> enabled, then
+ by default, the row-level security policies of the view owner are applied,
+ and access to any additional relations referred to by those policies is
+ determined by the permissions of the view owner. However, if the view has
+ <code class="literal">security_invoker</code> set to <code class="literal">true</code>, then
+ the policies and permissions of the invoking user are used instead, as if
+ the base relations had been referenced directly from the query using the
+ view.
+ </p><p>
+ Functions called in the view are treated the same as if they had been
+ called directly from the query using the view. Therefore, the user of
+ a view must have permissions to call all functions used by the view.
+ Functions in the view are executed with the privileges of the user
+ executing the query or the function owner, depending on whether the
+ functions are defined as <code class="literal">SECURITY INVOKER</code> or
+ <code class="literal">SECURITY DEFINER</code>. Thus, for example, calling
+ <code class="literal">CURRENT_USER</code> directly in a view will always return the
+ invoking user, not the view owner. This is not affected by the view's
+ <code class="literal">security_invoker</code> setting, and so a view with
+ <code class="literal">security_invoker</code> set to <code class="literal">false</code> is
+ <span class="emphasis"><em>not</em></span> equivalent to a
+ <code class="literal">SECURITY DEFINER</code> function and those concepts should not
+ be confused.
+ </p><p>
+ The user creating or replacing a view must have <code class="literal">USAGE</code>
+ privileges on any schemas referred to in the view query, in order to look
+ up the referenced objects in those schemas. Note, however, that this
+ lookup only happens when the view is created or replaced. Therefore, the
+ user of the view only requires the <code class="literal">USAGE</code> privilege on
+ the schema containing the view, not on the schemas referred to in the view
+ query, even for a security invoker view.
+ </p><p>
+ When <code class="command">CREATE OR REPLACE VIEW</code> is used on an existing
+ view, only the view's defining SELECT rule, plus any
+ <code class="literal">WITH ( ... )</code> parameters and its
+ <code class="literal">CHECK OPTION</code> are changed.
+ Other view properties, including ownership, permissions, and non-SELECT
+ rules, remain unchanged. You must own the view
+ to replace it (this includes being a member of the owning role).
+ </p><div class="refsect2" id="SQL-CREATEVIEW-UPDATABLE-VIEWS"><h3>Updatable Views</h3><a id="id-1.9.3.97.7.11.2" class="indexterm"></a><p>
+ Simple views are automatically updatable: the system will allow
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code> and <code class="command">DELETE</code> statements
+ to be used on the view in the same way as on a regular table. A view is
+ automatically updatable if it satisfies all of the following conditions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The view must have exactly one entry in its <code class="literal">FROM</code> list,
+ which must be a table or another updatable view.
+ </p></li><li class="listitem"><p>
+ The view definition must not contain <code class="literal">WITH</code>,
+ <code class="literal">DISTINCT</code>, <code class="literal">GROUP BY</code>, <code class="literal">HAVING</code>,
+ <code class="literal">LIMIT</code>, or <code class="literal">OFFSET</code> clauses at the top level.
+ </p></li><li class="listitem"><p>
+ The view definition must not contain set operations (<code class="literal">UNION</code>,
+ <code class="literal">INTERSECT</code> or <code class="literal">EXCEPT</code>) at the top level.
+ </p></li><li class="listitem"><p>
+ The view's select list must not contain any aggregates, window functions
+ or set-returning functions.
+ </p></li></ul></div><p>
+ </p><p>
+ An automatically updatable view may contain a mix of updatable and
+ non-updatable columns. A column is updatable if it is a simple reference
+ to an updatable column of the underlying base relation; otherwise the
+ column is read-only, and an error will be raised if an <code class="command">INSERT</code>
+ or <code class="command">UPDATE</code> statement attempts to assign a value to it.
+ </p><p>
+ If the view is automatically updatable the system will convert any
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code> or <code class="command">DELETE</code> statement
+ on the view into the corresponding statement on the underlying base
+ relation. <code class="command">INSERT</code> statements that have an <code class="literal">ON
+ CONFLICT UPDATE</code> clause are fully supported.
+ </p><p>
+ If an automatically updatable view contains a <code class="literal">WHERE</code>
+ condition, the condition restricts which rows of the base relation are
+ available to be modified by <code class="command">UPDATE</code> and <code class="command">DELETE</code>
+ statements on the view. However, an <code class="command">UPDATE</code> is allowed to
+ change a row so that it no longer satisfies the <code class="literal">WHERE</code>
+ condition, and thus is no longer visible through the view. Similarly,
+ an <code class="command">INSERT</code> command can potentially insert base-relation rows
+ that do not satisfy the <code class="literal">WHERE</code> condition and thus are not
+ visible through the view (<code class="literal">ON CONFLICT UPDATE</code> may
+ similarly affect an existing row not visible through the view).
+ The <code class="literal">CHECK OPTION</code> may be used to prevent
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> commands from creating
+ such rows that are not visible through the view.
+ </p><p>
+ If an automatically updatable view is marked with the
+ <code class="literal">security_barrier</code> property then all the view's <code class="literal">WHERE</code>
+ conditions (and any conditions using operators which are marked as <code class="literal">LEAKPROOF</code>)
+ will always be evaluated before any conditions that a user of the view has
+ added. See <a class="xref" href="rules-privileges.html" title="41.5. Rules and Privileges">Section 41.5</a> for full details. Note that,
+ due to this, rows which are not ultimately returned (because they do not
+ pass the user's <code class="literal">WHERE</code> conditions) may still end up being locked.
+ <code class="command">EXPLAIN</code> can be used to see which conditions are
+ applied at the relation level (and therefore do not lock rows) and which are
+ not.
+ </p><p>
+ A more complex view that does not satisfy all these conditions is
+ read-only by default: the system will not allow an insert, update, or
+ delete on the view. You can get the effect of an updatable view by
+ creating <code class="literal">INSTEAD OF</code> triggers on the view, which must
+ convert attempted inserts, etc. on the view into appropriate actions
+ on other tables. For more information see <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>. Another possibility is to create rules
+ (see <a class="xref" href="sql-createrule.html" title="CREATE RULE"><span class="refentrytitle">CREATE RULE</span></a>), but in practice triggers are
+ easier to understand and use correctly.
+ </p><p>
+ Note that the user performing the insert, update or delete on the view
+ must have the corresponding insert, update or delete privilege on the
+ view. In addition, by default, the view's owner must have the relevant
+ privileges on the underlying base relations, whereas the user performing
+ the update does not need any permissions on the underlying base relations
+ (see <a class="xref" href="rules-privileges.html" title="41.5. Rules and Privileges">Section 41.5</a>). However, if the view has
+ <code class="literal">security_invoker</code> set to <code class="literal">true</code>, the
+ user performing the update, rather than the view owner, must have the
+ relevant privileges on the underlying base relations.
+ </p></div></div><div class="refsect1" id="id-1.9.3.97.8"><h2>Examples</h2><p>
+ Create a view consisting of all comedy films:
+
+</p><pre class="programlisting">
+CREATE VIEW comedies AS
+ SELECT *
+ FROM films
+ WHERE kind = 'Comedy';
+</pre><p>
+ This will create a view containing the columns that are in the
+ <code class="literal">film</code> table at the time of view creation. Though
+ <code class="literal">*</code> was used to create the view, columns added later to
+ the table will not be part of the view.
+ </p><p>
+ Create a view with <code class="literal">LOCAL CHECK OPTION</code>:
+
+</p><pre class="programlisting">
+CREATE VIEW universal_comedies AS
+ SELECT *
+ FROM comedies
+ WHERE classification = 'U'
+ WITH LOCAL CHECK OPTION;
+</pre><p>
+ This will create a view based on the <code class="literal">comedies</code> view, showing
+ only films with <code class="literal">kind = 'Comedy'</code> and
+ <code class="literal">classification = 'U'</code>. Any attempt to <code class="command">INSERT</code> or
+ <code class="command">UPDATE</code> a row in the view will be rejected if the new row
+ doesn't have <code class="literal">classification = 'U'</code>, but the film
+ <code class="literal">kind</code> will not be checked.
+ </p><p>
+ Create a view with <code class="literal">CASCADED CHECK OPTION</code>:
+
+</p><pre class="programlisting">
+CREATE VIEW pg_comedies AS
+ SELECT *
+ FROM comedies
+ WHERE classification = 'PG'
+ WITH CASCADED CHECK OPTION;
+</pre><p>
+ This will create a view that checks both the <code class="literal">kind</code> and
+ <code class="literal">classification</code> of new rows.
+ </p><p>
+ Create a view with a mix of updatable and non-updatable columns:
+
+</p><pre class="programlisting">
+CREATE VIEW comedies AS
+ SELECT f.*,
+ country_code_to_name(f.country_code) AS country,
+ (SELECT avg(r.rating)
+ FROM user_ratings r
+ WHERE r.film_id = f.id) AS avg_rating
+ FROM films f
+ WHERE f.kind = 'Comedy';
+</pre><p>
+ This view will support <code class="command">INSERT</code>, <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code>. All the columns from the <code class="literal">films</code> table will
+ be updatable, whereas the computed columns <code class="literal">country</code> and
+ <code class="literal">avg_rating</code> will be read-only.
+ </p><p>
+ Create a recursive view consisting of the numbers from 1 to 100:
+</p><pre class="programlisting">
+CREATE RECURSIVE VIEW public.nums_1_100 (n) AS
+ VALUES (1)
+UNION ALL
+ SELECT n+1 FROM nums_1_100 WHERE n &lt; 100;
+</pre><p>
+ Notice that although the recursive view's name is schema-qualified in this
+ <code class="command">CREATE</code>, its internal self-reference is not schema-qualified.
+ This is because the implicitly-created CTE's name cannot be
+ schema-qualified.
+ </p></div><div class="refsect1" id="id-1.9.3.97.9"><h2>Compatibility</h2><p>
+ <code class="command">CREATE OR REPLACE VIEW</code> is a
+ <span class="productname">PostgreSQL</span> language extension.
+ So is the concept of a temporary view.
+ The <code class="literal">WITH ( ... )</code> clause is an extension as well, as are
+ security barrier views and security invoker views.
+ </p></div><div class="refsect1" id="id-1.9.3.97.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterview.html" title="ALTER VIEW"><span class="refentrytitle">ALTER VIEW</span></a>, <a class="xref" href="sql-dropview.html" title="DROP VIEW"><span class="refentrytitle">DROP VIEW</span></a>, <a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createusermapping.html" title="CREATE USER MAPPING">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-deallocate.html" title="DEALLOCATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE USER MAPPING </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DEALLOCATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-deallocate.html b/doc/src/sgml/html/sql-deallocate.html
new file mode 100644
index 0000000..231ad9c
--- /dev/null
+++ b/doc/src/sgml/html/sql-deallocate.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DEALLOCATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createview.html" title="CREATE VIEW" /><link rel="next" href="sql-declare.html" title="DECLARE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DEALLOCATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createview.html" title="CREATE VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-declare.html" title="DECLARE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DEALLOCATE"><div class="titlepage"></div><a id="id-1.9.3.98.1" class="indexterm"></a><a id="id-1.9.3.98.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DEALLOCATE</span></h2><p>DEALLOCATE — deallocate a prepared statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DEALLOCATE [ PREPARE ] { <em class="replaceable"><code>name</code></em> | ALL }
+</pre></div><div class="refsect1" id="id-1.9.3.98.6"><h2>Description</h2><p>
+ <code class="command">DEALLOCATE</code> is used to deallocate a previously
+ prepared SQL statement. If you do not explicitly deallocate a
+ prepared statement, it is deallocated when the session ends.
+ </p><p>
+ For more information on prepared statements, see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.98.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PREPARE</code></span></dt><dd><p>
+ This key word is ignored.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the prepared statement to deallocate.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Deallocate all prepared statements.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.98.8"><h2>Compatibility</h2><p>
+ The SQL standard includes a <code class="command">DEALLOCATE</code>
+ statement, but it is only for use in embedded SQL.
+ </p></div><div class="refsect1" id="id-1.9.3.98.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a>, <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createview.html" title="CREATE VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-declare.html" title="DECLARE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DECLARE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-declare.html b/doc/src/sgml/html/sql-declare.html
new file mode 100644
index 0000000..b5f393a
--- /dev/null
+++ b/doc/src/sgml/html/sql-declare.html
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DECLARE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-deallocate.html" title="DEALLOCATE" /><link rel="next" href="sql-delete.html" title="DELETE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DECLARE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-deallocate.html" title="DEALLOCATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-delete.html" title="DELETE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DECLARE"><div class="titlepage"></div><a id="id-1.9.3.99.1" class="indexterm"></a><a id="id-1.9.3.99.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DECLARE</span></h2><p>DECLARE — define a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DECLARE <em class="replaceable"><code>name</code></em> [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ]
+ CURSOR [ { WITH | WITHOUT } HOLD ] FOR <em class="replaceable"><code>query</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.99.6"><h2>Description</h2><p>
+ <code class="command">DECLARE</code> allows a user to create cursors, which
+ can be used to retrieve
+ a small number of rows at a time out of a larger query.
+ After the cursor is created, rows are fetched from it using
+ <a class="link" href="sql-fetch.html" title="FETCH"><code class="command">FETCH</code></a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This page describes usage of cursors at the SQL command level.
+ If you are trying to use cursors inside a <span class="application">PL/pgSQL</span>
+ function, the rules are different —
+ see <a class="xref" href="plpgsql-cursors.html" title="43.7. Cursors">Section 43.7</a>.
+ </p></div></div><div class="refsect1" id="id-1.9.3.99.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the cursor to be created.
+ </p></dd><dt><span class="term"><code class="literal">BINARY</code></span></dt><dd><p>
+ Causes the cursor to return data in binary rather than in text format.
+ </p></dd><dt><span class="term"><code class="literal">ASENSITIVE</code><br /></span><span class="term"><code class="literal">INSENSITIVE</code></span></dt><dd><p>
+ Cursor sensitivity determines whether changes to the data underlying the
+ cursor, done in the same transaction, after the cursor has been
+ declared, are visible in the cursor. <code class="literal">INSENSITIVE</code>
+ means they are not visible, <code class="literal">ASENSITIVE</code> means the
+ behavior is implementation-dependent. A third behavior,
+ <code class="literal">SENSITIVE</code>, meaning that such changes are visible in
+ the cursor, is not available in <span class="productname">PostgreSQL</span>.
+ In <span class="productname">PostgreSQL</span>, all cursors are insensitive;
+ so these key words have no effect and are only accepted for
+ compatibility with the SQL standard.
+ </p><p>
+ Specifying <code class="literal">INSENSITIVE</code> together with <code class="literal">FOR
+ UPDATE</code> or <code class="literal">FOR SHARE</code> is an error.
+ </p></dd><dt><span class="term"><code class="literal">SCROLL</code><br /></span><span class="term"><code class="literal">NO SCROLL</code></span></dt><dd><p><code class="literal">SCROLL</code> specifies that the cursor can be used
+ to retrieve rows in a nonsequential fashion (e.g.,
+ backward). Depending upon the complexity of the query's
+ execution plan, specifying <code class="literal">SCROLL</code> might impose
+ a performance penalty on the query's execution time.
+ <code class="literal">NO SCROLL</code> specifies that the cursor cannot be
+ used to retrieve rows in a nonsequential fashion. The default is to
+ allow scrolling in some cases; this is not the same as specifying
+ <code class="literal">SCROLL</code>. See <a class="xref" href="sql-declare.html#SQL-DECLARE-NOTES" title="Notes">Notes</a>
+ below for details.
+ </p></dd><dt><span class="term"><code class="literal">WITH HOLD</code><br /></span><span class="term"><code class="literal">WITHOUT HOLD</code></span></dt><dd><p><code class="literal">WITH HOLD</code> specifies that the cursor can
+ continue to be used after the transaction that created it
+ successfully commits. <code class="literal">WITHOUT HOLD</code> specifies
+ that the cursor cannot be used outside of the transaction that
+ created it. If neither <code class="literal">WITHOUT HOLD</code> nor
+ <code class="literal">WITH HOLD</code> is specified, <code class="literal">WITHOUT
+ HOLD</code> is the default.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a> or
+ <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a> command
+ which will provide the rows to be returned by the cursor.
+ </p></dd></dl></div><p>
+ The key words <code class="literal">ASENSITIVE</code>, <code class="literal">BINARY</code>,
+ <code class="literal">INSENSITIVE</code>, and <code class="literal">SCROLL</code> can
+ appear in any order.
+ </p></div><div class="refsect1" id="SQL-DECLARE-NOTES"><h2>Notes</h2><p>
+ Normal cursors return data in text format, the same as a
+ <code class="command">SELECT</code> would produce. The <code class="literal">BINARY</code> option
+ specifies that the cursor should return data in binary format.
+ This reduces conversion effort for both the server and client,
+ at the cost of more programmer effort to deal with platform-dependent
+ binary data formats.
+ As an example, if a query returns a value of one from an integer column,
+ you would get a string of <code class="literal">1</code> with a default cursor,
+ whereas with a binary cursor you would get
+ a 4-byte field containing the internal representation of the value
+ (in big-endian byte order).
+ </p><p>
+ Binary cursors should be used carefully. Many applications,
+ including <span class="application">psql</span>, are not prepared to
+ handle binary cursors and expect data to come back in the text
+ format.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ When the client application uses the <span class="quote">“<span class="quote">extended query</span>”</span> protocol
+ to issue a <code class="command">FETCH</code> command, the Bind protocol message
+ specifies whether data is to be retrieved in text or binary format.
+ This choice overrides the way that the cursor is defined. The concept
+ of a binary cursor as such is thus obsolete when using extended query
+ protocol — any cursor can be treated as either text or binary.
+ </p></div><p>
+ Unless <code class="literal">WITH HOLD</code> is specified, the cursor
+ created by this command can only be used within the current
+ transaction. Thus, <code class="command">DECLARE</code> without <code class="literal">WITH
+ HOLD</code> is useless outside a transaction block: the cursor would
+ survive only to the completion of the statement. Therefore
+ <span class="productname">PostgreSQL</span> reports an error if such a
+ command is used outside a transaction block.
+ Use
+ <a class="link" href="sql-begin.html" title="BEGIN"><code class="command">BEGIN</code></a> and
+ <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a>
+ (or <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a>)
+ to define a transaction block.
+ </p><p>
+ If <code class="literal">WITH HOLD</code> is specified and the transaction
+ that created the cursor successfully commits, the cursor can
+ continue to be accessed by subsequent transactions in the same
+ session. (But if the creating transaction is aborted, the cursor
+ is removed.) A cursor created with <code class="literal">WITH HOLD</code>
+ is closed when an explicit <code class="command">CLOSE</code> command is
+ issued on it, or the session ends. In the current implementation,
+ the rows represented by a held cursor are copied into a temporary
+ file or memory area so that they remain available for subsequent
+ transactions.
+ </p><p>
+ <code class="literal">WITH HOLD</code> may not be specified when the query
+ includes <code class="literal">FOR UPDATE</code> or <code class="literal">FOR SHARE</code>.
+ </p><p>
+ The <code class="literal">SCROLL</code> option should be specified when defining a
+ cursor that will be used to fetch backwards. This is required by
+ the SQL standard. However, for compatibility with earlier
+ versions, <span class="productname">PostgreSQL</span> will allow
+ backward fetches without <code class="literal">SCROLL</code>, if the cursor's query
+ plan is simple enough that no extra overhead is needed to support
+ it. However, application developers are advised not to rely on
+ using backward fetches from a cursor that has not been created
+ with <code class="literal">SCROLL</code>. If <code class="literal">NO SCROLL</code> is
+ specified, then backward fetches are disallowed in any case.
+ </p><p>
+ Backward fetches are also disallowed when the query
+ includes <code class="literal">FOR UPDATE</code> or <code class="literal">FOR SHARE</code>; therefore
+ <code class="literal">SCROLL</code> may not be specified in this case.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Scrollable cursors may give unexpected
+ results if they invoke any volatile functions (see <a class="xref" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Section 38.7</a>). When a previously fetched row is
+ re-fetched, the functions might be re-executed, perhaps leading to
+ results different from the first time. It's best to
+ specify <code class="literal">NO SCROLL</code> for a query involving volatile
+ functions. If that is not practical, one workaround
+ is to declare the cursor <code class="literal">SCROLL WITH HOLD</code> and commit the
+ transaction before reading any rows from it. This will force the
+ entire output of the cursor to be materialized in temporary storage,
+ so that volatile functions are executed exactly once for each row.
+ </p></div><p>
+ If the cursor's query includes <code class="literal">FOR UPDATE</code> or <code class="literal">FOR
+ SHARE</code>, then returned rows are locked at the time they are first
+ fetched, in the same way as for a regular
+ <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a> command with
+ these options.
+ In addition, the returned rows will be the most up-to-date versions.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is generally recommended to use <code class="literal">FOR UPDATE</code> if the cursor
+ is intended to be used with <code class="command">UPDATE ... WHERE CURRENT OF</code> or
+ <code class="command">DELETE ... WHERE CURRENT OF</code>. Using <code class="literal">FOR UPDATE</code>
+ prevents other sessions from changing the rows between the time they are
+ fetched and the time they are updated. Without <code class="literal">FOR UPDATE</code>,
+ a subsequent <code class="literal">WHERE CURRENT OF</code> command will have no effect if
+ the row was changed since the cursor was created.
+ </p><p>
+ Another reason to use <code class="literal">FOR UPDATE</code> is that without it, a
+ subsequent <code class="literal">WHERE CURRENT OF</code> might fail if the cursor query
+ does not meet the SQL standard's rules for being <span class="quote">“<span class="quote">simply
+ updatable</span>”</span> (in particular, the cursor must reference just one table
+ and not use grouping or <code class="literal">ORDER BY</code>). Cursors
+ that are not simply updatable might work, or might not, depending on plan
+ choice details; so in the worst case, an application might work in testing
+ and then fail in production. If <code class="literal">FOR UPDATE</code> is
+ specified, the cursor is guaranteed to be updatable.
+ </p><p>
+ The main reason not to use <code class="literal">FOR UPDATE</code> with <code class="literal">WHERE
+ CURRENT OF</code> is if you need the cursor to be scrollable, or to be
+ isolated from concurrent updates (that is, continue to show the old
+ data). If this is a requirement, pay close heed to the caveats shown
+ above.
+ </p></div><p>
+ The SQL standard only makes provisions for cursors in embedded
+ <acronym class="acronym">SQL</acronym>. The <span class="productname">PostgreSQL</span>
+ server does not implement an <code class="command">OPEN</code> statement for
+ cursors; a cursor is considered to be open when it is declared.
+ However, <span class="application">ECPG</span>, the embedded SQL
+ preprocessor for <span class="productname">PostgreSQL</span>, supports
+ the standard SQL cursor conventions, including those involving
+ <code class="command">DECLARE</code> and <code class="command">OPEN</code> statements.
+ </p><p>
+ You can see all available cursors by querying the <a class="link" href="view-pg-cursors.html" title="54.6. pg_cursors"><code class="structname">pg_cursors</code></a>
+ system view.
+ </p></div><div class="refsect1" id="id-1.9.3.99.9"><h2>Examples</h2><p>
+ To declare a cursor:
+</p><pre class="programlisting">
+DECLARE liahona CURSOR FOR SELECT * FROM films;
+</pre><p>
+ See <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a> for more
+ examples of cursor usage.
+ </p></div><div class="refsect1" id="id-1.9.3.99.10"><h2>Compatibility</h2><p>
+ The SQL standard allows cursors only in embedded
+ <acronym class="acronym">SQL</acronym> and in modules. <span class="productname">PostgreSQL</span>
+ permits cursors to be used interactively.
+ </p><p>
+ According to the SQL standard, changes made to insensitive cursors by
+ <code class="literal">UPDATE ... WHERE CURRENT OF</code> and <code class="literal">DELETE
+ ... WHERE CURRENT OF</code> statements are visible in that same
+ cursor. <span class="productname">PostgreSQL</span> treats these statements like
+ all other data changing statements in that they are not visible in
+ insensitive cursors.
+ </p><p>
+ Binary cursors are a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.99.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-close.html" title="CLOSE"><span class="refentrytitle">CLOSE</span></a>, <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>, <a class="xref" href="sql-move.html" title="MOVE"><span class="refentrytitle">MOVE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-deallocate.html" title="DEALLOCATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-delete.html" title="DELETE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DEALLOCATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DELETE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-delete.html b/doc/src/sgml/html/sql-delete.html
new file mode 100644
index 0000000..abb8449
--- /dev/null
+++ b/doc/src/sgml/html/sql-delete.html
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DELETE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-declare.html" title="DECLARE" /><link rel="next" href="sql-discard.html" title="DISCARD" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DELETE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-declare.html" title="DECLARE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-discard.html" title="DISCARD">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DELETE"><div class="titlepage"></div><a id="id-1.9.3.100.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DELETE</span></h2><p>DELETE — delete rows of a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+DELETE FROM [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ [ AS ] <em class="replaceable"><code>alias</code></em> ]
+ [ USING <em class="replaceable"><code>from_item</code></em> [, ...] ]
+ [ WHERE <em class="replaceable"><code>condition</code></em> | WHERE CURRENT OF <em class="replaceable"><code>cursor_name</code></em> ]
+ [ RETURNING * | <em class="replaceable"><code>output_expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]
+</pre></div><div class="refsect1" id="id-1.9.3.100.5"><h2>Description</h2><p>
+ <code class="command">DELETE</code> deletes rows that satisfy the
+ <code class="literal">WHERE</code> clause from the specified table. If the
+ <code class="literal">WHERE</code> clause is absent, the effect is to delete
+ all rows in the table. The result is a valid, but empty table.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a> provides a
+ faster mechanism to remove all rows from a table.
+ </p></div><p>
+ There are two ways to delete rows in a table using information
+ contained in other tables in the database: using sub-selects, or
+ specifying additional tables in the <code class="literal">USING</code> clause.
+ Which technique is more appropriate depends on the specific
+ circumstances.
+ </p><p>
+ The optional <code class="literal">RETURNING</code> clause causes <code class="command">DELETE</code>
+ to compute and return value(s) based on each row actually deleted.
+ Any expression using the table's columns, and/or columns of other
+ tables mentioned in <code class="literal">USING</code>, can be computed.
+ The syntax of the <code class="literal">RETURNING</code> list is identical to that of the
+ output list of <code class="command">SELECT</code>.
+ </p><p>
+ You must have the <code class="literal">DELETE</code> privilege on the table
+ to delete from it, as well as the <code class="literal">SELECT</code>
+ privilege for any table in the <code class="literal">USING</code> clause or
+ whose values are read in the <em class="replaceable"><code>condition</code></em>.
+ </p></div><div class="refsect1" id="id-1.9.3.100.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>
+ The <code class="literal">WITH</code> clause allows you to specify one or more
+ subqueries that can be referenced by name in the <code class="command">DELETE</code>
+ query. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> and <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to delete rows
+ from. If <code class="literal">ONLY</code> is specified before the table name,
+ matching rows are deleted from the named table only. If
+ <code class="literal">ONLY</code> is not specified, matching rows are also deleted
+ from any tables inheriting from the named table. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>
+ A substitute name for the target table. When an alias is
+ provided, it completely hides the actual name of the table. For
+ example, given <code class="literal">DELETE FROM foo AS f</code>, the remainder
+ of the <code class="command">DELETE</code> statement must refer to this
+ table as <code class="literal">f</code> not <code class="literal">foo</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>from_item</code></em></span></dt><dd><p>
+ A table expression allowing columns from other tables to appear
+ in the <code class="literal">WHERE</code> condition. This uses the same
+ syntax as the <a class="link" href="sql-select.html#SQL-FROM" title="FROM Clause"><code class="literal">FROM</code></a>
+ clause of a <code class="command">SELECT</code> statement; for example, an alias
+ for the table name can be specified. Do not repeat the target
+ table as a <em class="replaceable"><code>from_item</code></em>
+ unless you wish to set up a self-join (in which case it must appear
+ with an alias in the <em class="replaceable"><code>from_item</code></em>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ An expression that returns a value of type <code class="type">boolean</code>.
+ Only rows for which this expression returns <code class="literal">true</code>
+ will be deleted.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+ The name of the cursor to use in a <code class="literal">WHERE CURRENT OF</code>
+ condition. The row to be deleted is the one most recently fetched
+ from this cursor. The cursor must be a non-grouping
+ query on the <code class="command">DELETE</code>'s target table.
+ Note that <code class="literal">WHERE CURRENT OF</code> cannot be
+ specified together with a Boolean condition. See
+ <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>
+ for more information about using cursors with
+ <code class="literal">WHERE CURRENT OF</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_expression</code></em></span></dt><dd><p>
+ An expression to be computed and returned by the <code class="command">DELETE</code>
+ command after each row is deleted. The expression can use any
+ column names of the table named by <em class="replaceable"><code>table_name</code></em>
+ or table(s) listed in <code class="literal">USING</code>.
+ Write <code class="literal">*</code> to return all columns.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_name</code></em></span></dt><dd><p>
+ A name to use for a returned column.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.100.7"><h2>Outputs</h2><p>
+ On successful completion, a <code class="command">DELETE</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+DELETE <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number
+ of rows deleted. Note that the number may be less than the number of
+ rows that matched the <em class="replaceable"><code>condition</code></em> when deletes were
+ suppressed by a <code class="literal">BEFORE DELETE</code> trigger. If <em class="replaceable"><code>count</code></em> is 0, no rows were deleted by
+ the query (this is not considered an error).
+ </p><p>
+ If the <code class="command">DELETE</code> command contains a <code class="literal">RETURNING</code>
+ clause, the result will be similar to that of a <code class="command">SELECT</code>
+ statement containing the columns and values defined in the
+ <code class="literal">RETURNING</code> list, computed over the row(s) deleted by the
+ command.
+ </p></div><div class="refsect1" id="id-1.9.3.100.8"><h2>Notes</h2><p>
+ <span class="productname">PostgreSQL</span> lets you reference columns of
+ other tables in the <code class="literal">WHERE</code> condition by specifying the
+ other tables in the <code class="literal">USING</code> clause. For example,
+ to delete all films produced by a given producer, one can do:
+</p><pre class="programlisting">
+DELETE FROM films USING producers
+ WHERE producer_id = producers.id AND producers.name = 'foo';
+</pre><p>
+ What is essentially happening here is a join between <code class="structname">films</code>
+ and <code class="structname">producers</code>, with all successfully joined
+ <code class="structname">films</code> rows being marked for deletion.
+ This syntax is not standard. A more standard way to do it is:
+</p><pre class="programlisting">
+DELETE FROM films
+ WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');
+</pre><p>
+ In some cases the join style is easier to write or faster to
+ execute than the sub-select style.
+ </p></div><div class="refsect1" id="id-1.9.3.100.9"><h2>Examples</h2><p>
+ Delete all films but musicals:
+</p><pre class="programlisting">
+DELETE FROM films WHERE kind &lt;&gt; 'Musical';
+</pre><p>
+ </p><p>
+ Clear the table <code class="literal">films</code>:
+</p><pre class="programlisting">
+DELETE FROM films;
+</pre><p>
+ </p><p>
+ Delete completed tasks, returning full details of the deleted rows:
+</p><pre class="programlisting">
+DELETE FROM tasks WHERE status = 'DONE' RETURNING *;
+</pre><p>
+ </p><p>
+ Delete the row of <code class="structname">tasks</code> on which the cursor
+ <code class="literal">c_tasks</code> is currently positioned:
+</p><pre class="programlisting">
+DELETE FROM tasks WHERE CURRENT OF c_tasks;
+</pre></div><div class="refsect1" id="id-1.9.3.100.10"><h2>Compatibility</h2><p>
+ This command conforms to the <acronym class="acronym">SQL</acronym> standard, except
+ that the <code class="literal">USING</code> and <code class="literal">RETURNING</code> clauses
+ are <span class="productname">PostgreSQL</span> extensions, as is the ability
+ to use <code class="literal">WITH</code> with <code class="command">DELETE</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.100.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-declare.html" title="DECLARE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-discard.html" title="DISCARD">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DECLARE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DISCARD</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-discard.html b/doc/src/sgml/html/sql-discard.html
new file mode 100644
index 0000000..8496252
--- /dev/null
+++ b/doc/src/sgml/html/sql-discard.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DISCARD</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-delete.html" title="DELETE" /><link rel="next" href="sql-do.html" title="DO" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DISCARD</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-delete.html" title="DELETE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-do.html" title="DO">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DISCARD"><div class="titlepage"></div><a id="id-1.9.3.101.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DISCARD</span></h2><p>DISCARD — discard session state</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
+</pre></div><div class="refsect1" id="id-1.9.3.101.5"><h2>Description</h2><p>
+ <code class="command">DISCARD</code> releases internal resources associated with a
+ database session. This command is useful for partially or fully
+ resetting the session's state. There are several subcommands to
+ release different types of resources; the <code class="command">DISCARD ALL</code>
+ variant subsumes all the others, and also resets additional state.
+ </p></div><div class="refsect1" id="id-1.9.3.101.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">PLANS</code></span></dt><dd><p>
+ Releases all cached query plans, forcing re-planning to occur
+ the next time the associated prepared statement is used.
+ </p></dd><dt><span class="term"><code class="literal">SEQUENCES</code></span></dt><dd><p>
+ Discards all cached sequence-related state,
+ including <code class="function">currval()</code>/<code class="function">lastval()</code>
+ information and any preallocated sequence values that have not
+ yet been returned by <code class="function">nextval()</code>.
+ (See <a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a> for a description of
+ preallocated sequence values.)
+ </p></dd><dt><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ Drops all temporary tables created in the current session.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Releases all temporary resources associated with the current
+ session and resets the session to its initial state.
+ Currently, this has the same effect as executing the following sequence
+ of statements:
+</p><pre class="programlisting">
+CLOSE ALL;
+SET SESSION AUTHORIZATION DEFAULT;
+RESET ALL;
+DEALLOCATE ALL;
+UNLISTEN *;
+SELECT pg_advisory_unlock_all();
+DISCARD PLANS;
+DISCARD TEMP;
+DISCARD SEQUENCES;
+</pre></dd></dl></div></div><div class="refsect1" id="id-1.9.3.101.7"><h2>Notes</h2><p>
+ <code class="command">DISCARD ALL</code> cannot be executed inside a transaction block.
+ </p></div><div class="refsect1" id="id-1.9.3.101.8"><h2>Compatibility</h2><p>
+ <code class="command">DISCARD</code> is a <span class="productname">PostgreSQL</span> extension.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-delete.html" title="DELETE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-do.html" title="DO">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DELETE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DO</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-do.html b/doc/src/sgml/html/sql-do.html
new file mode 100644
index 0000000..f6c6de7
--- /dev/null
+++ b/doc/src/sgml/html/sql-do.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DO</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-discard.html" title="DISCARD" /><link rel="next" href="sql-drop-access-method.html" title="DROP ACCESS METHOD" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DO</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-discard.html" title="DISCARD">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-drop-access-method.html" title="DROP ACCESS METHOD">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DO"><div class="titlepage"></div><a id="id-1.9.3.102.1" class="indexterm"></a><a id="id-1.9.3.102.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DO</span></h2><p>DO — execute an anonymous code block</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DO [ LANGUAGE <em class="replaceable"><code>lang_name</code></em> ] <em class="replaceable"><code>code</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.102.6"><h2>Description</h2><p>
+ <code class="command">DO</code> executes an anonymous code block, or in other
+ words a transient anonymous function in a procedural language.
+ </p><p>
+ The code block is treated as though it were the body of a function
+ with no parameters, returning <code class="type">void</code>. It is parsed and
+ executed a single time.
+ </p><p>
+ The optional <code class="literal">LANGUAGE</code> clause can be written either
+ before or after the code block.
+ </p></div><div class="refsect1" id="id-1.9.3.102.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>code</code></em></span></dt><dd><p>
+ The procedural language code to be executed. This must be specified
+ as a string literal, just as in <code class="command">CREATE FUNCTION</code>.
+ Use of a dollar-quoted literal is recommended.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the procedural language the code is written in.
+ If omitted, the default is <code class="literal">plpgsql</code>.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.102.8"><h2>Notes</h2><p>
+ The procedural language to be used must already have been installed
+ into the current database by means of <code class="command">CREATE EXTENSION</code>.
+ <code class="literal">plpgsql</code> is installed by default, but other languages are not.
+ </p><p>
+ The user must have <code class="literal">USAGE</code> privilege for the procedural
+ language, or must be a superuser if the language is untrusted.
+ This is the same privilege requirement as for creating a function
+ in the language.
+ </p><p>
+ If <code class="command">DO</code> is executed in a transaction block, then the
+ procedure code cannot execute transaction control statements. Transaction
+ control statements are only allowed if <code class="command">DO</code> is executed in
+ its own transaction.
+ </p></div><div class="refsect1" id="SQL-DO-EXAMPLES"><h2>Examples</h2><p>
+ Grant all privileges on all views in schema <code class="literal">public</code> to
+ role <code class="literal">webuser</code>:
+</p><pre class="programlisting">
+DO $$DECLARE r record;
+BEGIN
+ FOR r IN SELECT table_schema, table_name FROM information_schema.tables
+ WHERE table_type = 'VIEW' AND table_schema = 'public'
+ LOOP
+ EXECUTE 'GRANT ALL ON ' || quote_ident(r.table_schema) || '.' || quote_ident(r.table_name) || ' TO webuser';
+ END LOOP;
+END$$;
+</pre></div><div class="refsect1" id="id-1.9.3.102.10"><h2>Compatibility</h2><p>
+ There is no <code class="command">DO</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.102.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-discard.html" title="DISCARD">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-drop-access-method.html" title="DROP ACCESS METHOD">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DISCARD </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP ACCESS METHOD</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-drop-access-method.html b/doc/src/sgml/html/sql-drop-access-method.html
new file mode 100644
index 0000000..e896988
--- /dev/null
+++ b/doc/src/sgml/html/sql-drop-access-method.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP ACCESS METHOD</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-do.html" title="DO" /><link rel="next" href="sql-dropaggregate.html" title="DROP AGGREGATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP ACCESS METHOD</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-do.html" title="DO">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropaggregate.html" title="DROP AGGREGATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROP-ACCESS-METHOD"><div class="titlepage"></div><a id="id-1.9.3.103.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP ACCESS METHOD</span></h2><p>DROP ACCESS METHOD — remove an access method</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP ACCESS METHOD [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.103.5"><h2>Description</h2><p>
+ <code class="command">DROP ACCESS METHOD</code> removes an existing access method.
+ Only superusers can drop access methods.
+ </p></div><div class="refsect1" id="id-1.9.3.103.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the access method does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing access method.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the access method
+ (such as operator classes, operator families, and indexes),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the access method if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.103.7"><h2>Examples</h2><p>
+ Drop the access method <code class="literal">heptree</code>:
+</p><pre class="programlisting">
+DROP ACCESS METHOD heptree;
+</pre></div><div class="refsect1" id="id-1.9.3.103.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP ACCESS METHOD</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.103.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-do.html" title="DO">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropaggregate.html" title="DROP AGGREGATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DO </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP AGGREGATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-drop-owned.html b/doc/src/sgml/html/sql-drop-owned.html
new file mode 100644
index 0000000..5eb5a00
--- /dev/null
+++ b/doc/src/sgml/html/sql-drop-owned.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP OWNED</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY" /><link rel="next" href="sql-droppolicy.html" title="DROP POLICY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP OWNED</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droppolicy.html" title="DROP POLICY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROP-OWNED"><div class="titlepage"></div><a id="id-1.9.3.122.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP OWNED</span></h2><p>DROP OWNED — remove database objects owned by a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP OWNED BY { <em class="replaceable"><code>name</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.122.5"><h2>Description</h2><p>
+ <code class="command">DROP OWNED</code> drops all the objects within the current
+ database that are owned by one of the specified roles. Any
+ privileges granted to the given roles on objects in the current
+ database or on shared objects (databases, tablespaces, configuration
+ parameters) will also be revoked.
+ </p></div><div class="refsect1" id="id-1.9.3.122.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a role whose objects will be dropped, and whose
+ privileges will be revoked.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the affected objects,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the objects owned by a role if any other database
+ objects depend on one of the affected objects. This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.122.7"><h2>Notes</h2><p>
+ <code class="command">DROP OWNED</code> is often used to prepare for the
+ removal of one or more roles. Because <code class="command">DROP OWNED</code>
+ only affects the objects in the current database, it is usually
+ necessary to execute this command in each database that contains
+ objects owned by a role that is to be removed.
+ </p><p>
+ Using the <code class="literal">CASCADE</code> option might make the command
+ recurse to objects owned by other users.
+ </p><p>
+ The <a class="link" href="sql-reassign-owned.html" title="REASSIGN OWNED"><code class="command">REASSIGN OWNED</code></a> command is an alternative that
+ reassigns the ownership of all the database objects owned by one or
+ more roles. However, <code class="command">REASSIGN OWNED</code> does not deal with
+ privileges for other objects.
+ </p><p>
+ Databases and tablespaces owned by the role(s) will not be removed.
+ </p><p>
+ See <a class="xref" href="role-removal.html" title="22.4. Dropping Roles">Section 22.4</a> for more discussion.
+ </p></div><div class="refsect1" id="id-1.9.3.122.8"><h2>Compatibility</h2><p>
+ The <code class="command">DROP OWNED</code> command is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.122.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-reassign-owned.html" title="REASSIGN OWNED"><span class="refentrytitle">REASSIGN OWNED</span></a>, <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droppolicy.html" title="DROP POLICY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP OPERATOR FAMILY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP POLICY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropaggregate.html b/doc/src/sgml/html/sql-dropaggregate.html
new file mode 100644
index 0000000..e598e9c
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropaggregate.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP AGGREGATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-drop-access-method.html" title="DROP ACCESS METHOD" /><link rel="next" href="sql-dropcast.html" title="DROP CAST" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP AGGREGATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-drop-access-method.html" title="DROP ACCESS METHOD">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropcast.html" title="DROP CAST">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPAGGREGATE"><div class="titlepage"></div><a id="id-1.9.3.104.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP AGGREGATE</span></h2><p>DROP AGGREGATE — remove an aggregate function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP AGGREGATE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) [, ...] [ CASCADE | RESTRICT ]
+
+<span class="phrase">where <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
+
+* |
+[ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
+[ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.104.5"><h2>Description</h2><p>
+ <code class="command">DROP AGGREGATE</code> removes an existing
+ aggregate function. To execute this command the current
+ user must be the owner of the aggregate function.
+ </p></div><div class="refsect1" id="id-1.9.3.104.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the aggregate does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing aggregate function.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code> or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">DROP AGGREGATE</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the aggregate function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ An input data type on which the aggregate function operates.
+ To reference a zero-argument aggregate function, write <code class="literal">*</code>
+ in place of the list of argument specifications.
+ To reference an ordered-set aggregate function, write
+ <code class="literal">ORDER BY</code> between the direct and aggregated argument
+ specifications.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the aggregate function
+ (such as views using it),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the aggregate function if any objects depend on
+ it. This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.104.7"><h2>Notes</h2><p>
+ Alternative syntaxes for referencing ordered-set aggregates
+ are described under <a class="xref" href="sql-alteraggregate.html" title="ALTER AGGREGATE"><span class="refentrytitle">ALTER AGGREGATE</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.104.8"><h2>Examples</h2><p>
+ To remove the aggregate function <code class="literal">myavg</code> for type
+ <code class="type">integer</code>:
+</p><pre class="programlisting">
+DROP AGGREGATE myavg(integer);
+</pre><p>
+ </p><p>
+ To remove the hypothetical-set aggregate function <code class="literal">myrank</code>,
+ which takes an arbitrary list of ordering columns and a matching list
+ of direct arguments:
+</p><pre class="programlisting">
+DROP AGGREGATE myrank(VARIADIC "any" ORDER BY VARIADIC "any");
+</pre><p>
+ </p><p>
+ To remove multiple aggregate functions in one command:
+</p><pre class="programlisting">
+DROP AGGREGATE myavg(integer), myavg(bigint);
+</pre></div><div class="refsect1" id="id-1.9.3.104.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP AGGREGATE</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.104.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteraggregate.html" title="ALTER AGGREGATE"><span class="refentrytitle">ALTER AGGREGATE</span></a>, <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-drop-access-method.html" title="DROP ACCESS METHOD">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropcast.html" title="DROP CAST">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP ACCESS METHOD </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP CAST</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropcast.html b/doc/src/sgml/html/sql-dropcast.html
new file mode 100644
index 0000000..675e77b
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropcast.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP CAST</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropaggregate.html" title="DROP AGGREGATE" /><link rel="next" href="sql-dropcollation.html" title="DROP COLLATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP CAST</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropaggregate.html" title="DROP AGGREGATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropcollation.html" title="DROP COLLATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPCAST"><div class="titlepage"></div><a id="id-1.9.3.105.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP CAST</span></h2><p>DROP CAST — remove a cast</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP CAST [ IF EXISTS ] (<em class="replaceable"><code>source_type</code></em> AS <em class="replaceable"><code>target_type</code></em>) [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="SQL-DROPCAST-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">DROP CAST</code> removes a previously defined cast.
+ </p><p>
+ To be able to drop a cast, you must own the source or the target
+ data type. These are the same privileges that are required to
+ create a cast.
+ </p></div><div class="refsect1" id="id-1.9.3.105.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the cast does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_type</code></em></span></dt><dd><p>
+ The name of the source data type of the cast.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>target_type</code></em></span></dt><dd><p>
+ The name of the target data type of the cast.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no
+ dependencies on casts.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPCAST-EXAMPLES"><h2>Examples</h2><p>
+ To drop the cast from type <code class="type">text</code> to type <code class="type">int</code>:
+</p><pre class="programlisting">
+DROP CAST (text AS int);
+</pre></div><div class="refsect1" id="SQL-DROPCAST-COMPAT"><h2>Compatibility</h2><p>
+ The <code class="command">DROP CAST</code> command conforms to the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.105.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropaggregate.html" title="DROP AGGREGATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropcollation.html" title="DROP COLLATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP AGGREGATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP COLLATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropcollation.html b/doc/src/sgml/html/sql-dropcollation.html
new file mode 100644
index 0000000..747a8b6
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropcollation.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP COLLATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropcast.html" title="DROP CAST" /><link rel="next" href="sql-dropconversion.html" title="DROP CONVERSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP COLLATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropcast.html" title="DROP CAST">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropconversion.html" title="DROP CONVERSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPCOLLATION"><div class="titlepage"></div><a id="id-1.9.3.106.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP COLLATION</span></h2><p>DROP COLLATION — remove a collation</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP COLLATION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="SQL-DROPCOLLATION-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">DROP COLLATION</code> removes a previously defined collation.
+ To be able to drop a collation, you must own the collation.
+ </p></div><div class="refsect1" id="id-1.9.3.106.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the collation does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the collation. The collation name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the collation,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the collation if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPCOLLATION-EXAMPLES"><h2>Examples</h2><p>
+ To drop the collation named <code class="literal">german</code>:
+</p><pre class="programlisting">
+DROP COLLATION german;
+</pre></div><div class="refsect1" id="SQL-DROPCOLLATION-COMPAT"><h2>Compatibility</h2><p>
+ The <code class="command">DROP COLLATION</code> command conforms to the
+ <acronym class="acronym">SQL</acronym> standard, apart from the <code class="literal">IF
+ EXISTS</code> option, which is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.106.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altercollation.html" title="ALTER COLLATION"><span class="refentrytitle">ALTER COLLATION</span></a>, <a class="xref" href="sql-createcollation.html" title="CREATE COLLATION"><span class="refentrytitle">CREATE COLLATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropcast.html" title="DROP CAST">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropconversion.html" title="DROP CONVERSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP CAST </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP CONVERSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropconversion.html b/doc/src/sgml/html/sql-dropconversion.html
new file mode 100644
index 0000000..2b9a7e2
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropconversion.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP CONVERSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropcollation.html" title="DROP COLLATION" /><link rel="next" href="sql-dropdatabase.html" title="DROP DATABASE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP CONVERSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropcollation.html" title="DROP COLLATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropdatabase.html" title="DROP DATABASE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPCONVERSION"><div class="titlepage"></div><a id="id-1.9.3.107.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP CONVERSION</span></h2><p>DROP CONVERSION — remove a conversion</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP CONVERSION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="SQL-DROPCONVERSION-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">DROP CONVERSION</code> removes a previously defined conversion.
+ To be able to drop a conversion, you must own the conversion.
+ </p></div><div class="refsect1" id="id-1.9.3.107.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the conversion does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the conversion. The conversion name can be
+ schema-qualified.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no
+ dependencies on conversions.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPCONVERSION-EXAMPLES"><h2>Examples</h2><p>
+ To drop the conversion named <code class="literal">myname</code>:
+</p><pre class="programlisting">
+DROP CONVERSION myname;
+</pre></div><div class="refsect1" id="SQL-DROPCONVERSION-COMPAT"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP CONVERSION</code> statement in the SQL
+ standard, but a <code class="command">DROP TRANSLATION</code> statement that
+ goes along with the <code class="command">CREATE TRANSLATION</code> statement
+ that is similar to the <code class="command">CREATE CONVERSION</code>
+ statement in PostgreSQL.
+ </p></div><div class="refsect1" id="id-1.9.3.107.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterconversion.html" title="ALTER CONVERSION"><span class="refentrytitle">ALTER CONVERSION</span></a>, <a class="xref" href="sql-createconversion.html" title="CREATE CONVERSION"><span class="refentrytitle">CREATE CONVERSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropcollation.html" title="DROP COLLATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropdatabase.html" title="DROP DATABASE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP COLLATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP DATABASE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropdatabase.html b/doc/src/sgml/html/sql-dropdatabase.html
new file mode 100644
index 0000000..20f74d7
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropdatabase.html
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP DATABASE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropconversion.html" title="DROP CONVERSION" /><link rel="next" href="sql-dropdomain.html" title="DROP DOMAIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP DATABASE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropconversion.html" title="DROP CONVERSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropdomain.html" title="DROP DOMAIN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPDATABASE"><div class="titlepage"></div><a id="id-1.9.3.108.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP DATABASE</span></h2><p>DROP DATABASE — remove a database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP DATABASE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ [ WITH ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be:</span>
+
+ FORCE
+</pre></div><div class="refsect1" id="id-1.9.3.108.5"><h2>Description</h2><p>
+ <code class="command">DROP DATABASE</code> drops a database. It removes the
+ catalog entries for the database and deletes the directory
+ containing the data. It can only be executed by the database owner.
+ It cannot be executed while you are connected to the target database.
+ (Connect to <code class="literal">postgres</code> or any other database to issue this
+ command.)
+ Also, if anyone else is connected to the target database, this command will
+ fail unless you use the <code class="literal">FORCE</code> option described below.
+ </p><p>
+ <code class="command">DROP DATABASE</code> cannot be undone. Use it with care!
+ </p></div><div class="refsect1" id="id-1.9.3.108.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the database does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the database to remove.
+ </p></dd><dt><span class="term"><code class="literal">FORCE</code></span></dt><dd><p>
+ Attempt to terminate all existing connections to the target database.
+ It doesn't terminate if prepared transactions, active logical replication
+ slots or subscriptions are present in the target database.
+ </p><p>
+ This will fail if the current user has no permissions to terminate other
+ connections. Required permissions are the same as with
+ <code class="literal">pg_terminate_backend</code>, described in
+ <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL" title="9.27.2. Server Signaling Functions">Section 9.27.2</a>. This will also fail if we
+ are not able to terminate connections.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.108.7"><h2>Notes</h2><p>
+ <code class="command">DROP DATABASE</code> cannot be executed inside a transaction
+ block.
+ </p><p>
+ This command cannot be executed while connected to the target
+ database. Thus, it might be more convenient to use the program
+ <a class="xref" href="app-dropdb.html" title="dropdb"><span class="refentrytitle"><span class="application">dropdb</span></span></a> instead,
+ which is a wrapper around this command.
+ </p></div><div class="refsect1" id="id-1.9.3.108.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP DATABASE</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.108.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropconversion.html" title="DROP CONVERSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropdomain.html" title="DROP DOMAIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP CONVERSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP DOMAIN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropdomain.html b/doc/src/sgml/html/sql-dropdomain.html
new file mode 100644
index 0000000..c0410a1
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropdomain.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP DOMAIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropdatabase.html" title="DROP DATABASE" /><link rel="next" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP DOMAIN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropdatabase.html" title="DROP DATABASE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPDOMAIN"><div class="titlepage"></div><a id="id-1.9.3.109.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP DOMAIN</span></h2><p>DROP DOMAIN — remove a domain</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP DOMAIN [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.109.5"><h2>Description</h2><p>
+ <code class="command">DROP DOMAIN</code> removes a domain. Only the owner of
+ a domain can remove it.
+ </p></div><div class="refsect1" id="id-1.9.3.109.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the domain does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing domain.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the domain (such as
+ table columns),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the domain if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPDOMAIN-EXAMPLES"><h2>Examples</h2><p>
+ To remove the domain <code class="type">box</code>:
+
+</p><pre class="programlisting">
+DROP DOMAIN box;
+</pre></div><div class="refsect1" id="SQL-DROPDOMAIN-COMPATIBILITY"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, except for the
+ <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="SQL-DROPDOMAIN-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>, <a class="xref" href="sql-alterdomain.html" title="ALTER DOMAIN"><span class="refentrytitle">ALTER DOMAIN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropdatabase.html" title="DROP DATABASE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP DATABASE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP EVENT TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropeventtrigger.html b/doc/src/sgml/html/sql-dropeventtrigger.html
new file mode 100644
index 0000000..9137035
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropeventtrigger.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP EVENT TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropdomain.html" title="DROP DOMAIN" /><link rel="next" href="sql-dropextension.html" title="DROP EXTENSION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP EVENT TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropdomain.html" title="DROP DOMAIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropextension.html" title="DROP EXTENSION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPEVENTTRIGGER"><div class="titlepage"></div><a id="id-1.9.3.110.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP EVENT TRIGGER</span></h2><p>DROP EVENT TRIGGER — remove an event trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP EVENT TRIGGER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.110.5"><h2>Description</h2><p>
+ <code class="command">DROP EVENT TRIGGER</code> removes an existing event trigger.
+ To execute this command, the current user must be the owner of the event
+ trigger.
+ </p></div><div class="refsect1" id="id-1.9.3.110.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the event trigger does not exist. A notice
+ is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the event trigger to remove.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the trigger,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the trigger if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPEVENTTRIGGER-EXAMPLES"><h2>Examples</h2><p>
+ Destroy the trigger <code class="literal">snitch</code>:
+
+</p><pre class="programlisting">
+DROP EVENT TRIGGER snitch;
+</pre></div><div class="refsect1" id="SQL-DROPEVENTTRIGGER-COMPATIBILITY"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP EVENT TRIGGER</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.110.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER"><span class="refentrytitle">CREATE EVENT TRIGGER</span></a>, <a class="xref" href="sql-altereventtrigger.html" title="ALTER EVENT TRIGGER"><span class="refentrytitle">ALTER EVENT TRIGGER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropdomain.html" title="DROP DOMAIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropextension.html" title="DROP EXTENSION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP DOMAIN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP EXTENSION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropextension.html b/doc/src/sgml/html/sql-dropextension.html
new file mode 100644
index 0000000..25e3b11
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropextension.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP EXTENSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER" /><link rel="next" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP EXTENSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPEXTENSION"><div class="titlepage"></div><a id="id-1.9.3.111.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP EXTENSION</span></h2><p>DROP EXTENSION — remove an extension</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP EXTENSION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.111.5"><h2>Description</h2><p>
+ <code class="command">DROP EXTENSION</code> removes extensions from the database.
+ Dropping an extension causes its member objects, and other explicitly
+ dependent routines (see <a class="xref" href="sql-alterroutine.html" title="ALTER ROUTINE"><span class="refentrytitle">ALTER ROUTINE</span></a>,
+ the <code class="literal">DEPENDS ON EXTENSION <em class="replaceable"><code>extension_name</code></em>
+ </code> action), to be dropped as well.
+ </p><p>
+ You must own the extension to use <code class="command">DROP EXTENSION</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.111.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the extension does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an installed extension.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the extension,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ This option prevents the specified extensions from being dropped if
+ other objects, besides these extensions, their members, and their
+ explicitly dependent routines, depend on them.  This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.111.7"><h2>Examples</h2><p>
+ To remove the extension <code class="literal">hstore</code> from the current
+ database:
+</p><pre class="programlisting">
+DROP EXTENSION hstore;
+</pre><p>
+ This command will fail if any of <code class="literal">hstore</code>'s objects
+ are in use in the database, for example if any tables have columns
+ of the <code class="type">hstore</code> type. Add the <code class="literal">CASCADE</code> option to
+ forcibly remove those dependent objects as well.
+ </p></div><div class="refsect1" id="id-1.9.3.111.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP EXTENSION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.111.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createextension.html" title="CREATE EXTENSION"><span class="refentrytitle">CREATE EXTENSION</span></a>, <a class="xref" href="sql-alterextension.html" title="ALTER EXTENSION"><span class="refentrytitle">ALTER EXTENSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropeventtrigger.html" title="DROP EVENT TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP EVENT TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP FOREIGN DATA WRAPPER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropforeigndatawrapper.html b/doc/src/sgml/html/sql-dropforeigndatawrapper.html
new file mode 100644
index 0000000..36f8816
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropforeigndatawrapper.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP FOREIGN DATA WRAPPER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropextension.html" title="DROP EXTENSION" /><link rel="next" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP FOREIGN DATA WRAPPER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropextension.html" title="DROP EXTENSION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPFOREIGNDATAWRAPPER"><div class="titlepage"></div><a id="id-1.9.3.112.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP FOREIGN DATA WRAPPER</span></h2><p>DROP FOREIGN DATA WRAPPER — remove a foreign-data wrapper</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.112.5"><h2>Description</h2><p>
+ <code class="command">DROP FOREIGN DATA WRAPPER</code> removes an existing
+ foreign-data wrapper. To execute this command, the current user
+ must be the owner of the foreign-data wrapper.
+ </p></div><div class="refsect1" id="id-1.9.3.112.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the foreign-data wrapper does not
+ exist. A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing foreign-data wrapper.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the foreign-data
+ wrapper (such as foreign tables and servers),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the foreign-data wrapper if any objects depend
+ on it. This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.112.7"><h2>Examples</h2><p>
+ Drop the foreign-data wrapper <code class="literal">dbi</code>:
+</p><pre class="programlisting">
+DROP FOREIGN DATA WRAPPER dbi;
+</pre></div><div class="refsect1" id="id-1.9.3.112.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP FOREIGN DATA WRAPPER</code> conforms to ISO/IEC
+ 9075-9 (SQL/MED). The <code class="literal">IF EXISTS</code> clause is
+ a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.112.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER"><span class="refentrytitle">CREATE FOREIGN DATA WRAPPER</span></a>, <a class="xref" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER"><span class="refentrytitle">ALTER FOREIGN DATA WRAPPER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropextension.html" title="DROP EXTENSION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP EXTENSION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP FOREIGN TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropforeigntable.html b/doc/src/sgml/html/sql-dropforeigntable.html
new file mode 100644
index 0000000..15613fd
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropforeigntable.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP FOREIGN TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER" /><link rel="next" href="sql-dropfunction.html" title="DROP FUNCTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP FOREIGN TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropfunction.html" title="DROP FUNCTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPFOREIGNTABLE"><div class="titlepage"></div><a id="id-1.9.3.113.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP FOREIGN TABLE</span></h2><p>DROP FOREIGN TABLE — remove a foreign table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP FOREIGN TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.113.5"><h2>Description</h2><p>
+ <code class="command">DROP FOREIGN TABLE</code> removes a foreign table.
+ Only the owner of a foreign table can remove it.
+ </p></div><div class="refsect1" id="id-1.9.3.113.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the foreign table does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the foreign table to drop.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the foreign table (such as
+ views), and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the foreign table if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.113.7"><h2>Examples</h2><p>
+ To destroy two foreign tables, <code class="literal">films</code> and
+ <code class="literal">distributors</code>:
+
+</p><pre class="programlisting">
+DROP FOREIGN TABLE films, distributors;
+</pre></div><div class="refsect1" id="id-1.9.3.113.8"><h2>Compatibility</h2><p>
+ This command conforms to ISO/IEC 9075-9 (SQL/MED), except that the
+ standard only allows one foreign table to be dropped per command, and apart
+ from the <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.113.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE"><span class="refentrytitle">ALTER FOREIGN TABLE</span></a>, <a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropforeigndatawrapper.html" title="DROP FOREIGN DATA WRAPPER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropfunction.html" title="DROP FUNCTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP FOREIGN DATA WRAPPER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP FUNCTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropfunction.html b/doc/src/sgml/html/sql-dropfunction.html
new file mode 100644
index 0000000..619cb77
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropfunction.html
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP FUNCTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE" /><link rel="next" href="sql-dropgroup.html" title="DROP GROUP" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP FUNCTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropgroup.html" title="DROP GROUP">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPFUNCTION"><div class="titlepage"></div><a id="id-1.9.3.114.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP FUNCTION</span></h2><p>DROP FUNCTION — remove a function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP FUNCTION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] [, ...]
+ [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.114.5"><h2>Description</h2><p>
+ <code class="command">DROP FUNCTION</code> removes the definition of an existing
+ function. To execute this command the user must be the
+ owner of the function. The argument types to the
+ function must be specified, since several different functions
+ can exist with the same name and different argument lists.
+ </p></div><div class="refsect1" id="id-1.9.3.114.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the function does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing function. If no
+ argument list is specified, the name must be unique in its schema.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Note that <code class="command">DROP FUNCTION</code> does not actually pay
+ any attention to <code class="literal">OUT</code> arguments, since only the input
+ arguments are needed to determine the function's identity.
+ So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
+ and <code class="literal">VARIADIC</code> arguments.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">DROP FUNCTION</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are needed to determine the function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the function's arguments (optionally
+ schema-qualified), if any.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the function (such as
+ operators or triggers),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the function if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPFUNCTION-EXAMPLES"><h2>Examples</h2><p>
+ This command removes the square root function:
+
+</p><pre class="programlisting">
+DROP FUNCTION sqrt(integer);
+</pre><p>
+ Drop multiple functions in one command:
+</p><pre class="programlisting">
+DROP FUNCTION sqrt(integer), sqrt(bigint);
+</pre><p>
+ If the function name is unique in its schema, it can be referred to without
+ an argument list:
+</p><pre class="programlisting">
+DROP FUNCTION update_employee_salaries;
+</pre><p>
+ Note that this is different from
+</p><pre class="programlisting">
+DROP FUNCTION update_employee_salaries();
+</pre><p>
+ which refers to a function with zero arguments, whereas the first variant
+ can refer to a function with any number of arguments, including zero, as
+ long as the name is unique.
+ </p></div><div class="refsect1" id="SQL-DROPFUNCTION-COMPATIBILITY"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, with
+ these <span class="productname">PostgreSQL</span> extensions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The standard only allows one function to be dropped per command.</p></li><li class="listitem"><p>The <code class="literal">IF EXISTS</code> option</p></li><li class="listitem"><p>The ability to specify argument modes and names</p></li></ul></div></div><div class="refsect1" id="id-1.9.3.114.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a>, <a class="xref" href="sql-droproutine.html" title="DROP ROUTINE"><span class="refentrytitle">DROP ROUTINE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropgroup.html" title="DROP GROUP">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP FOREIGN TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP GROUP</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropgroup.html b/doc/src/sgml/html/sql-dropgroup.html
new file mode 100644
index 0000000..91dbe76
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropgroup.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP GROUP</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropfunction.html" title="DROP FUNCTION" /><link rel="next" href="sql-dropindex.html" title="DROP INDEX" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP GROUP</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropfunction.html" title="DROP FUNCTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropindex.html" title="DROP INDEX">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPGROUP"><div class="titlepage"></div><a id="id-1.9.3.115.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP GROUP</span></h2><p>DROP GROUP — remove a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP GROUP [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...]
+</pre></div><div class="refsect1" id="id-1.9.3.115.5"><h2>Description</h2><p>
+ <code class="command">DROP GROUP</code> is now an alias for
+ <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.115.6"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP GROUP</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.115.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropfunction.html" title="DROP FUNCTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropindex.html" title="DROP INDEX">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP FUNCTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP INDEX</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropindex.html b/doc/src/sgml/html/sql-dropindex.html
new file mode 100644
index 0000000..dd4d8d3
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropindex.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP INDEX</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropgroup.html" title="DROP GROUP" /><link rel="next" href="sql-droplanguage.html" title="DROP LANGUAGE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP INDEX</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropgroup.html" title="DROP GROUP">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droplanguage.html" title="DROP LANGUAGE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPINDEX"><div class="titlepage"></div><a id="id-1.9.3.116.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP INDEX</span></h2><p>DROP INDEX — remove an index</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.116.5"><h2>Description</h2><p>
+ <code class="command">DROP INDEX</code> drops an existing index from the database
+ system. To execute this command you must be the owner of
+ the index.
+ </p></div><div class="refsect1" id="id-1.9.3.116.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CONCURRENTLY</code></span></dt><dd><p>
+ Drop the index without locking out concurrent selects, inserts, updates,
+ and deletes on the index's table. A normal <code class="command">DROP INDEX</code>
+ acquires an <code class="literal">ACCESS EXCLUSIVE</code> lock on the table,
+ blocking other accesses until the index drop can be completed. With
+ this option, the command instead waits until conflicting transactions
+ have completed.
+ </p><p>
+ There are several caveats to be aware of when using this option.
+ Only one index name can be specified, and the <code class="literal">CASCADE</code> option
+ is not supported. (Thus, an index that supports a <code class="literal">UNIQUE</code> or
+ <code class="literal">PRIMARY KEY</code> constraint cannot be dropped this way.)
+ Also, regular <code class="command">DROP INDEX</code> commands can be
+ performed within a transaction block, but
+ <code class="command">DROP INDEX CONCURRENTLY</code> cannot.
+ Lastly, indexes on partitioned tables cannot be dropped using this
+ option.
+ </p><p>
+ For temporary tables, <code class="command">DROP INDEX</code> is always
+ non-concurrent, as no other session can access them, and
+ non-concurrent index drop is cheaper.
+ </p></dd><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the index does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an index to remove.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the index,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the index if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.116.7"><h2>Examples</h2><p>
+ This command will remove the index <code class="literal">title_idx</code>:
+
+</p><pre class="programlisting">
+DROP INDEX title_idx;
+</pre></div><div class="refsect1" id="id-1.9.3.116.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP INDEX</code> is a
+ <span class="productname">PostgreSQL</span> language extension. There
+ are no provisions for indexes in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.116.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropgroup.html" title="DROP GROUP">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droplanguage.html" title="DROP LANGUAGE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP GROUP </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP LANGUAGE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droplanguage.html b/doc/src/sgml/html/sql-droplanguage.html
new file mode 100644
index 0000000..b45c987
--- /dev/null
+++ b/doc/src/sgml/html/sql-droplanguage.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP LANGUAGE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropindex.html" title="DROP INDEX" /><link rel="next" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP LANGUAGE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropindex.html" title="DROP INDEX">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPLANGUAGE"><div class="titlepage"></div><a id="id-1.9.3.117.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP LANGUAGE</span></h2><p>DROP LANGUAGE — remove a procedural language</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.117.5"><h2>Description</h2><p>
+ <code class="command">DROP LANGUAGE</code> removes the definition of a
+ previously registered procedural language. You must be a superuser
+ or the owner of the language to use <code class="command">DROP LANGUAGE</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ As of <span class="productname">PostgreSQL</span> 9.1, most procedural
+ languages have been made into <span class="quote">“<span class="quote">extensions</span>”</span>, and should
+ therefore be removed with <a class="link" href="sql-dropextension.html" title="DROP EXTENSION"><code class="command">DROP EXTENSION</code></a>
+ not <code class="command">DROP LANGUAGE</code>.
+ </p></div></div><div class="refsect1" id="id-1.9.3.117.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the language does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing procedural language.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the language (such as
+ functions in the language),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the language if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.117.7"><h2>Examples</h2><p>
+ This command removes the procedural language
+ <code class="literal">plsample</code>:
+
+</p><pre class="programlisting">
+DROP LANGUAGE plsample;
+</pre></div><div class="refsect1" id="id-1.9.3.117.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP LANGUAGE</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.117.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterlanguage.html" title="ALTER LANGUAGE"><span class="refentrytitle">ALTER LANGUAGE</span></a>, <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropindex.html" title="DROP INDEX">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP INDEX </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP MATERIALIZED VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropmaterializedview.html b/doc/src/sgml/html/sql-dropmaterializedview.html
new file mode 100644
index 0000000..b9a2bbf
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropmaterializedview.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP MATERIALIZED VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droplanguage.html" title="DROP LANGUAGE" /><link rel="next" href="sql-dropoperator.html" title="DROP OPERATOR" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP MATERIALIZED VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droplanguage.html" title="DROP LANGUAGE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropoperator.html" title="DROP OPERATOR">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPMATERIALIZEDVIEW"><div class="titlepage"></div><a id="id-1.9.3.118.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP MATERIALIZED VIEW</span></h2><p>DROP MATERIALIZED VIEW — remove a materialized view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP MATERIALIZED VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.118.5"><h2>Description</h2><p>
+ <code class="command">DROP MATERIALIZED VIEW</code> drops an existing materialized
+ view. To execute this command you must be the owner of the materialized
+ view.
+ </p></div><div class="refsect1" id="id-1.9.3.118.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the materialized view does not exist. A notice
+ is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the materialized view to
+ remove.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the materialized view (such as
+ other materialized views, or regular views),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the materialized view if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.118.7"><h2>Examples</h2><p>
+ This command will remove the materialized view called
+ <code class="literal">order_summary</code>:
+</p><pre class="programlisting">
+DROP MATERIALIZED VIEW order_summary;
+</pre></div><div class="refsect1" id="id-1.9.3.118.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP MATERIALIZED VIEW</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.118.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW"><span class="refentrytitle">ALTER MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW"><span class="refentrytitle">REFRESH MATERIALIZED VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droplanguage.html" title="DROP LANGUAGE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropoperator.html" title="DROP OPERATOR">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP LANGUAGE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP OPERATOR</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropopclass.html b/doc/src/sgml/html/sql-dropopclass.html
new file mode 100644
index 0000000..c74596b
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropopclass.html
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP OPERATOR CLASS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropoperator.html" title="DROP OPERATOR" /><link rel="next" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP OPERATOR CLASS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropoperator.html" title="DROP OPERATOR">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPOPCLASS"><div class="titlepage"></div><a id="id-1.9.3.120.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP OPERATOR CLASS</span></h2><p>DROP OPERATOR CLASS — remove an operator class</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP OPERATOR CLASS [ IF EXISTS ] <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.120.5"><h2>Description</h2><p>
+ <code class="command">DROP OPERATOR CLASS</code> drops an existing operator class.
+ To execute this command you must be the owner of the operator class.
+ </p><p>
+ <code class="command">DROP OPERATOR CLASS</code> does not drop any of the operators
+ or functions referenced by the class. If there are any indexes depending
+ on the operator class, you will need to specify
+ <code class="literal">CASCADE</code> for the drop to complete.
+ </p></div><div class="refsect1" id="id-1.9.3.120.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the operator class does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator class.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index access method the operator class is for.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the operator class (such as
+ indexes), and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the operator class if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.120.7"><h2>Notes</h2><p>
+ <code class="command">DROP OPERATOR CLASS</code> will not drop the operator family
+ containing the class, even if there is nothing else left in the
+ family (in particular, in the case where the family was implicitly
+ created by <code class="command">CREATE OPERATOR CLASS</code>). An empty operator
+ family is harmless, but for the sake of tidiness you might wish to
+ remove the family with <code class="command">DROP OPERATOR FAMILY</code>; or perhaps
+ better, use <code class="command">DROP OPERATOR FAMILY</code> in the first place.
+ </p></div><div class="refsect1" id="id-1.9.3.120.8"><h2>Examples</h2><p>
+ Remove the B-tree operator class <code class="literal">widget_ops</code>:
+
+</p><pre class="programlisting">
+DROP OPERATOR CLASS widget_ops USING btree;
+</pre><p>
+
+ This command will not succeed if there are any existing indexes
+ that use the operator class. Add <code class="literal">CASCADE</code> to drop
+ such indexes along with the operator class.
+ </p></div><div class="refsect1" id="id-1.9.3.120.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP OPERATOR CLASS</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.120.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS"><span class="refentrytitle">ALTER OPERATOR CLASS</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY"><span class="refentrytitle">DROP OPERATOR FAMILY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropoperator.html" title="DROP OPERATOR">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropopfamily.html" title="DROP OPERATOR FAMILY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP OPERATOR </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP OPERATOR FAMILY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropoperator.html b/doc/src/sgml/html/sql-dropoperator.html
new file mode 100644
index 0000000..e8dc11e
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropoperator.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP OPERATOR</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW" /><link rel="next" href="sql-dropopclass.html" title="DROP OPERATOR CLASS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP OPERATOR</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropopclass.html" title="DROP OPERATOR CLASS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPOPERATOR"><div class="titlepage"></div><a id="id-1.9.3.119.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP OPERATOR</span></h2><p>DROP OPERATOR — remove an operator</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP OPERATOR [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ( { <em class="replaceable"><code>left_type</code></em> | NONE } , <em class="replaceable"><code>right_type</code></em> ) [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.119.5"><h2>Description</h2><p>
+ <code class="command">DROP OPERATOR</code> drops an existing operator from
+ the database system. To execute this command you must be the owner
+ of the operator.
+ </p></div><div class="refsect1" id="id-1.9.3.119.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the operator does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>left_type</code></em></span></dt><dd><p>
+ The data type of the operator's left operand; write
+ <code class="literal">NONE</code> if the operator has no left operand.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>right_type</code></em></span></dt><dd><p>
+ The data type of the operator's right operand.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the operator (such as views
+ using it), and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the operator if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.119.7"><h2>Examples</h2><p>
+ Remove the power operator <code class="literal">a^b</code> for type <code class="type">integer</code>:
+</p><pre class="programlisting">
+DROP OPERATOR ^ (integer, integer);
+</pre><p>
+ </p><p>
+ Remove the bitwise-complement prefix operator
+ <code class="literal">~b</code> for type <code class="type">bit</code>:
+</p><pre class="programlisting">
+DROP OPERATOR ~ (none, bit);
+</pre><p>
+ </p><p>
+ Remove multiple operators in one command:
+</p><pre class="programlisting">
+DROP OPERATOR ~ (none, bit), ^ (integer, integer);
+</pre></div><div class="refsect1" id="id-1.9.3.119.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP OPERATOR</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.119.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createoperator.html" title="CREATE OPERATOR"><span class="refentrytitle">CREATE OPERATOR</span></a>, <a class="xref" href="sql-alteroperator.html" title="ALTER OPERATOR"><span class="refentrytitle">ALTER OPERATOR</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropopclass.html" title="DROP OPERATOR CLASS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP MATERIALIZED VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP OPERATOR CLASS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropopfamily.html b/doc/src/sgml/html/sql-dropopfamily.html
new file mode 100644
index 0000000..5b57537
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropopfamily.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP OPERATOR FAMILY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropopclass.html" title="DROP OPERATOR CLASS" /><link rel="next" href="sql-drop-owned.html" title="DROP OWNED" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP OPERATOR FAMILY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropopclass.html" title="DROP OPERATOR CLASS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-drop-owned.html" title="DROP OWNED">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPOPFAMILY"><div class="titlepage"></div><a id="id-1.9.3.121.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP OPERATOR FAMILY</span></h2><p>DROP OPERATOR FAMILY — remove an operator family</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP OPERATOR FAMILY [ IF EXISTS ] <em class="replaceable"><code>name</code></em> USING <em class="replaceable"><code>index_method</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.121.5"><h2>Description</h2><p>
+ <code class="command">DROP OPERATOR FAMILY</code> drops an existing operator family.
+ To execute this command you must be the owner of the operator family.
+ </p><p>
+ <code class="command">DROP OPERATOR FAMILY</code> includes dropping any operator
+ classes contained in the family, but it does not drop any of the operators
+ or functions referenced by the family. If there are any indexes depending
+ on operator classes within the family, you will need to specify
+ <code class="literal">CASCADE</code> for the drop to complete.
+ </p></div><div class="refsect1" id="id-1.9.3.121.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the operator family does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing operator family.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_method</code></em></span></dt><dd><p>
+ The name of the index access method the operator family is for.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the operator family,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the operator family if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.121.7"><h2>Examples</h2><p>
+ Remove the B-tree operator family <code class="literal">float_ops</code>:
+
+</p><pre class="programlisting">
+DROP OPERATOR FAMILY float_ops USING btree;
+</pre><p>
+
+ This command will not succeed if there are any existing indexes
+ that use operator classes within the family. Add <code class="literal">CASCADE</code> to
+ drop such indexes along with the operator family.
+ </p></div><div class="refsect1" id="id-1.9.3.121.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP OPERATOR FAMILY</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.121.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alteropfamily.html" title="ALTER OPERATOR FAMILY"><span class="refentrytitle">ALTER OPERATOR FAMILY</span></a>, <a class="xref" href="sql-createopfamily.html" title="CREATE OPERATOR FAMILY"><span class="refentrytitle">CREATE OPERATOR FAMILY</span></a>, <a class="xref" href="sql-alteropclass.html" title="ALTER OPERATOR CLASS"><span class="refentrytitle">ALTER OPERATOR CLASS</span></a>, <a class="xref" href="sql-createopclass.html" title="CREATE OPERATOR CLASS"><span class="refentrytitle">CREATE OPERATOR CLASS</span></a>, <a class="xref" href="sql-dropopclass.html" title="DROP OPERATOR CLASS"><span class="refentrytitle">DROP OPERATOR CLASS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropopclass.html" title="DROP OPERATOR CLASS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-drop-owned.html" title="DROP OWNED">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP OPERATOR CLASS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP OWNED</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droppolicy.html b/doc/src/sgml/html/sql-droppolicy.html
new file mode 100644
index 0000000..4ca62fd
--- /dev/null
+++ b/doc/src/sgml/html/sql-droppolicy.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP POLICY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-drop-owned.html" title="DROP OWNED" /><link rel="next" href="sql-dropprocedure.html" title="DROP PROCEDURE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP POLICY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-drop-owned.html" title="DROP OWNED">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropprocedure.html" title="DROP PROCEDURE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPPOLICY"><div class="titlepage"></div><a id="id-1.9.3.123.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP POLICY</span></h2><p>DROP POLICY — remove a row-level security policy from a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP POLICY [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.123.5"><h2>Description</h2><p>
+ <code class="command">DROP POLICY</code> removes the specified policy from the table.
+ Note that if the last policy is removed for a table and the table still has
+ row-level security enabled via <code class="command">ALTER TABLE</code>, then the
+ default-deny policy will be used. <code class="literal">ALTER TABLE ... DISABLE ROW
+ LEVEL SECURITY</code> can be used to disable row-level security for a
+ table, whether policies for the table exist or not.
+ </p></div><div class="refsect1" id="id-1.9.3.123.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the policy does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the policy to drop.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table that
+ the policy is on.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no
+ dependencies on policies.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.123.7"><h2>Examples</h2><p>
+ To drop the policy called <code class="literal">p1</code> on the table named
+ <code class="literal">my_table</code>:
+
+</p><pre class="programlisting">
+DROP POLICY p1 ON my_table;
+</pre></div><div class="refsect1" id="id-1.9.3.123.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP POLICY</code> is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.123.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createpolicy.html" title="CREATE POLICY"><span class="refentrytitle">CREATE POLICY</span></a>, <a class="xref" href="sql-alterpolicy.html" title="ALTER POLICY"><span class="refentrytitle">ALTER POLICY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-drop-owned.html" title="DROP OWNED">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropprocedure.html" title="DROP PROCEDURE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP OWNED </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP PROCEDURE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropprocedure.html b/doc/src/sgml/html/sql-dropprocedure.html
new file mode 100644
index 0000000..e2e0b11
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropprocedure.html
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP PROCEDURE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droppolicy.html" title="DROP POLICY" /><link rel="next" href="sql-droppublication.html" title="DROP PUBLICATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP PROCEDURE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droppolicy.html" title="DROP POLICY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droppublication.html" title="DROP PUBLICATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPPROCEDURE"><div class="titlepage"></div><a id="id-1.9.3.124.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP PROCEDURE</span></h2><p>DROP PROCEDURE — remove a procedure</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP PROCEDURE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] [, ...]
+ [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.124.5"><h2>Description</h2><p>
+ <code class="command">DROP PROCEDURE</code> removes the definition of one or more
+ existing procedures. To execute this command the user must be the
+ owner of the procedure(s). The argument types to the
+ procedure(s) usually must be specified, since several different procedures
+ can exist with the same name and different argument lists.
+ </p></div><div class="refsect1" id="id-1.9.3.124.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the procedure does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing procedure.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of an argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>. If omitted,
+ the default is <code class="literal">IN</code> (but see below).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of an argument.
+ Note that <code class="command">DROP PROCEDURE</code> does not actually pay
+ any attention to argument names, since only the argument data
+ types are used to determine the procedure's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type(s) of the procedure's arguments (optionally
+ schema-qualified), if any.
+ See below for details.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the procedure,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the procedure if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPPROCEDURE-NOTES"><h2>Notes</h2><p>
+ If there is only one procedure of the given name, the argument list
+ can be omitted. Omit the parentheses too in this case.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, it's sufficient to list the
+ input (including <code class="literal">INOUT</code>) arguments,
+ because no two routines of the same name are allowed to share the same
+ input-argument list. Moreover, the <code class="command">DROP</code> command
+ will not actually check that you wrote the types
+ of <code class="literal">OUT</code> arguments correctly; so any arguments that
+ are explicitly marked <code class="literal">OUT</code> are just noise. But
+ writing them is recommendable for consistency with the
+ corresponding <code class="command">CREATE</code> command.
+ </p><p>
+ For compatibility with the SQL standard, it is also allowed to write
+ all the argument data types (including those of <code class="literal">OUT</code>
+ arguments) without
+ any <em class="replaceable"><code>argmode</code></em> markers.
+ When this is done, the types of the procedure's <code class="literal">OUT</code>
+ argument(s) <span class="emphasis"><em>will</em></span> be verified against the command.
+ This provision creates an ambiguity, in that when the argument list
+ contains no <em class="replaceable"><code>argmode</code></em>
+ markers, it's unclear which rule is intended.
+ The <code class="command">DROP</code> command will attempt the lookup both ways,
+ and will throw an error if two different procedures are found.
+ To avoid the risk of such ambiguity, it's recommendable to
+ write <code class="literal">IN</code> markers explicitly rather than letting them
+ be defaulted, thus forcing the
+ traditional <span class="productname">PostgreSQL</span> interpretation to be
+ used.
+ </p><p>
+ The lookup rules just explained are also used by other commands that
+ act on existing procedures, such as <code class="command">ALTER PROCEDURE</code>
+ and <code class="command">COMMENT ON PROCEDURE</code>.
+ </p></div><div class="refsect1" id="SQL-DROPPROCEDURE-EXAMPLES"><h2>Examples</h2><p>
+ If there is only one procedure <code class="literal">do_db_maintenance</code>,
+ this command is sufficient to drop it:
+</p><pre class="programlisting">
+DROP PROCEDURE do_db_maintenance;
+</pre><p>
+ </p><p>
+ Given this procedure definition:
+</p><pre class="programlisting">
+CREATE PROCEDURE do_db_maintenance(IN target_schema text, OUT results text) ...
+</pre><p>
+ any one of these commands would work to drop it:
+</p><pre class="programlisting">
+DROP PROCEDURE do_db_maintenance(IN target_schema text, OUT results text);
+DROP PROCEDURE do_db_maintenance(IN text, OUT text);
+DROP PROCEDURE do_db_maintenance(IN text);
+DROP PROCEDURE do_db_maintenance(text);
+DROP PROCEDURE do_db_maintenance(text, text); -- potentially ambiguous
+</pre><p>
+ However, the last example would be ambiguous if there is also, say,
+</p><pre class="programlisting">
+CREATE PROCEDURE do_db_maintenance(IN target_schema text, IN options text) ...
+</pre></div><div class="refsect1" id="SQL-DROPPROCEDURE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, with
+ these <span class="productname">PostgreSQL</span> extensions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The standard only allows one procedure to be dropped per command.</p></li><li class="listitem"><p>The <code class="literal">IF EXISTS</code> option is an extension.</p></li><li class="listitem"><p>The ability to specify argument modes and names is an
+ extension, and the lookup rules differ when modes are given.</p></li></ul></div></div><div class="refsect1" id="id-1.9.3.124.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createprocedure.html" title="CREATE PROCEDURE"><span class="refentrytitle">CREATE PROCEDURE</span></a>, <a class="xref" href="sql-alterprocedure.html" title="ALTER PROCEDURE"><span class="refentrytitle">ALTER PROCEDURE</span></a>, <a class="xref" href="sql-dropfunction.html" title="DROP FUNCTION"><span class="refentrytitle">DROP FUNCTION</span></a>, <a class="xref" href="sql-droproutine.html" title="DROP ROUTINE"><span class="refentrytitle">DROP ROUTINE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droppolicy.html" title="DROP POLICY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droppublication.html" title="DROP PUBLICATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP POLICY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP PUBLICATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droppublication.html b/doc/src/sgml/html/sql-droppublication.html
new file mode 100644
index 0000000..53ca984
--- /dev/null
+++ b/doc/src/sgml/html/sql-droppublication.html
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP PUBLICATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropprocedure.html" title="DROP PROCEDURE" /><link rel="next" href="sql-droprole.html" title="DROP ROLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP PUBLICATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropprocedure.html" title="DROP PROCEDURE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droprole.html" title="DROP ROLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPPUBLICATION"><div class="titlepage"></div><a id="id-1.9.3.125.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP PUBLICATION</span></h2><p>DROP PUBLICATION — remove a publication</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP PUBLICATION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.125.5"><h2>Description</h2><p>
+ <code class="command">DROP PUBLICATION</code> removes an existing publication from
+ the database.
+ </p><p>
+ A publication can only be dropped by its owner or a superuser.
+ </p></div><div class="refsect1" id="id-1.9.3.125.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the publication does not exist. A notice is
+ issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing publication.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no dependencies
+ on publications.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.125.7"><h2>Examples</h2><p>
+ Drop a publication:
+</p><pre class="programlisting">
+DROP PUBLICATION mypublication;
+</pre></div><div class="refsect1" id="id-1.9.3.125.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP PUBLICATION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.125.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createpublication.html" title="CREATE PUBLICATION"><span class="refentrytitle">CREATE PUBLICATION</span></a>, <a class="xref" href="sql-alterpublication.html" title="ALTER PUBLICATION"><span class="refentrytitle">ALTER PUBLICATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropprocedure.html" title="DROP PROCEDURE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droprole.html" title="DROP ROLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP PROCEDURE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP ROLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droprole.html b/doc/src/sgml/html/sql-droprole.html
new file mode 100644
index 0000000..1c78c64
--- /dev/null
+++ b/doc/src/sgml/html/sql-droprole.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP ROLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droppublication.html" title="DROP PUBLICATION" /><link rel="next" href="sql-droproutine.html" title="DROP ROUTINE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP ROLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droppublication.html" title="DROP PUBLICATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droproutine.html" title="DROP ROUTINE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPROLE"><div class="titlepage"></div><a id="id-1.9.3.126.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP ROLE</span></h2><p>DROP ROLE — remove a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP ROLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...]
+</pre></div><div class="refsect1" id="id-1.9.3.126.5"><h2>Description</h2><p>
+ <code class="command">DROP ROLE</code> removes the specified role(s).
+ To drop a superuser role, you must be a superuser yourself;
+ to drop non-superuser roles, you must have <code class="literal">CREATEROLE</code>
+ privilege.
+ </p><p>
+ A role cannot be removed if it is still referenced in any database
+ of the cluster; an error will be raised if so. Before dropping the role,
+ you must drop all the objects it owns (or reassign their ownership)
+ and revoke any privileges the role has been granted on other objects.
+ The <a class="link" href="sql-reassign-owned.html" title="REASSIGN OWNED"><code class="command">REASSIGN
+ OWNED</code></a> and <a class="link" href="sql-drop-owned.html" title="DROP OWNED"><code class="command">DROP
+ OWNED</code></a>
+ commands can be useful for this purpose; see <a class="xref" href="role-removal.html" title="22.4. Dropping Roles">Section 22.4</a>
+ for more discussion.
+ </p><p>
+ However, it is not necessary to remove role memberships involving
+ the role; <code class="command">DROP ROLE</code> automatically revokes any memberships
+ of the target role in other roles, and of other roles in the target role.
+ The other roles are not dropped nor otherwise affected.
+ </p></div><div class="refsect1" id="id-1.9.3.126.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the role does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the role to remove.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.126.7"><h2>Notes</h2><p>
+ <span class="productname">PostgreSQL</span> includes a program <a class="xref" href="app-dropuser.html" title="dropuser"><span class="refentrytitle"><span class="application">dropuser</span></span></a> that has the
+ same functionality as this command (in fact, it calls this command)
+ but can be run from the command shell.
+ </p></div><div class="refsect1" id="id-1.9.3.126.8"><h2>Examples</h2><p>
+ To drop a role:
+</p><pre class="programlisting">
+DROP ROLE jonathan;
+</pre></div><div class="refsect1" id="id-1.9.3.126.9"><h2>Compatibility</h2><p>
+ The SQL standard defines <code class="command">DROP ROLE</code>, but it allows
+ only one role to be dropped at a time, and it specifies different
+ privilege requirements than <span class="productname">PostgreSQL</span> uses.
+ </p></div><div class="refsect1" id="id-1.9.3.126.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a>, <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>, <a class="xref" href="sql-set-role.html" title="SET ROLE"><span class="refentrytitle">SET ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droppublication.html" title="DROP PUBLICATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droproutine.html" title="DROP ROUTINE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP PUBLICATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP ROUTINE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droproutine.html b/doc/src/sgml/html/sql-droproutine.html
new file mode 100644
index 0000000..e007c77
--- /dev/null
+++ b/doc/src/sgml/html/sql-droproutine.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP ROUTINE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droprole.html" title="DROP ROLE" /><link rel="next" href="sql-droprule.html" title="DROP RULE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP ROUTINE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droprole.html" title="DROP ROLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droprule.html" title="DROP RULE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPROUTINE"><div class="titlepage"></div><a id="id-1.9.3.127.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP ROUTINE</span></h2><p>DROP ROUTINE — remove a routine</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP ROUTINE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] [, ...]
+ [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.127.5"><h2>Description</h2><p>
+ <code class="command">DROP ROUTINE</code> removes the definition of one or more
+ existing routines. The term <span class="quote">“<span class="quote">routine</span>”</span> includes
+ aggregate functions, normal functions, and procedures. See
+ under <a class="xref" href="sql-dropaggregate.html" title="DROP AGGREGATE"><span class="refentrytitle">DROP AGGREGATE</span></a>, <a class="xref" href="sql-dropfunction.html" title="DROP FUNCTION"><span class="refentrytitle">DROP FUNCTION</span></a>,
+ and <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a> for the description of the
+ parameters, more examples, and further details.
+ </p></div><div class="refsect1" id="SQL-DROPROUTINE-NOTES"><h2>Notes</h2><p>
+ The lookup rules used by <code class="command">DROP ROUTINE</code> are
+ fundamentally the same as for <code class="command">DROP PROCEDURE</code>; in
+ particular, <code class="command">DROP ROUTINE</code> shares that command's
+ behavior of considering an argument list that has
+ no <em class="replaceable"><code>argmode</code></em> markers to be
+ possibly using the SQL standard's definition that <code class="literal">OUT</code>
+ arguments are included in the list. (<code class="command">DROP AGGREGATE</code>
+ and <code class="command">DROP FUNCTION</code> do not do that.)
+ </p><p>
+ In some cases where the same name is shared by routines of different
+ kinds, it is possible for <code class="command">DROP ROUTINE</code> to fail with
+ an ambiguity error when a more specific command (<code class="command">DROP
+ FUNCTION</code>, etc.) would work. Specifying the argument type
+ list more carefully will also resolve such problems.
+ </p><p>
+ These lookup rules are also used by other commands that
+ act on existing routines, such as <code class="command">ALTER ROUTINE</code>
+ and <code class="command">COMMENT ON ROUTINE</code>.
+ </p></div><div class="refsect1" id="SQL-DROPROUTINE-EXAMPLES"><h2>Examples</h2><p>
+ To drop the routine <code class="literal">foo</code> for type
+ <code class="type">integer</code>:
+</p><pre class="programlisting">
+DROP ROUTINE foo(integer);
+</pre><p>
+ This command will work independent of whether <code class="literal">foo</code> is an
+ aggregate, function, or procedure.
+ </p></div><div class="refsect1" id="SQL-DROPROUTINE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, with
+ these <span class="productname">PostgreSQL</span> extensions:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The standard only allows one routine to be dropped per command.</p></li><li class="listitem"><p>The <code class="literal">IF EXISTS</code> option is an extension.</p></li><li class="listitem"><p>The ability to specify argument modes and names is an
+ extension, and the lookup rules differ when modes are given.</p></li><li class="listitem"><p>User-definable aggregate functions are an extension.</p></li></ul></div></div><div class="refsect1" id="id-1.9.3.127.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-dropaggregate.html" title="DROP AGGREGATE"><span class="refentrytitle">DROP AGGREGATE</span></a>, <a class="xref" href="sql-dropfunction.html" title="DROP FUNCTION"><span class="refentrytitle">DROP FUNCTION</span></a>, <a class="xref" href="sql-dropprocedure.html" title="DROP PROCEDURE"><span class="refentrytitle">DROP PROCEDURE</span></a>, <a class="xref" href="sql-alterroutine.html" title="ALTER ROUTINE"><span class="refentrytitle">ALTER ROUTINE</span></a></span><p>
+ Note that there is no <code class="literal">CREATE ROUTINE</code> command.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droprole.html" title="DROP ROLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droprule.html" title="DROP RULE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP ROLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP RULE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droprule.html b/doc/src/sgml/html/sql-droprule.html
new file mode 100644
index 0000000..b09cbbd
--- /dev/null
+++ b/doc/src/sgml/html/sql-droprule.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP RULE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droproutine.html" title="DROP ROUTINE" /><link rel="next" href="sql-dropschema.html" title="DROP SCHEMA" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP RULE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droproutine.html" title="DROP ROUTINE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropschema.html" title="DROP SCHEMA">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPRULE"><div class="titlepage"></div><a id="id-1.9.3.128.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP RULE</span></h2><p>DROP RULE — remove a rewrite rule</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP RULE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.128.5"><h2>Description</h2><p>
+ <code class="command">DROP RULE</code> drops a rewrite rule.
+ </p></div><div class="refsect1" id="id-1.9.3.128.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the rule does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the rule to drop.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table or view that
+ the rule applies to.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the rule,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the rule if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.128.7"><h2>Examples</h2><p>
+ To drop the rewrite rule <code class="literal">newrule</code>:
+
+</p><pre class="programlisting">
+DROP RULE newrule ON mytable;
+</pre></div><div class="refsect1" id="id-1.9.3.128.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP RULE</code> is a
+ <span class="productname">PostgreSQL</span> language extension, as is the
+ entire query rewrite system.
+ </p></div><div class="refsect1" id="id-1.9.3.128.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createrule.html" title="CREATE RULE"><span class="refentrytitle">CREATE RULE</span></a>, <a class="xref" href="sql-alterrule.html" title="ALTER RULE"><span class="refentrytitle">ALTER RULE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droproutine.html" title="DROP ROUTINE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropschema.html" title="DROP SCHEMA">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP ROUTINE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP SCHEMA</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropschema.html b/doc/src/sgml/html/sql-dropschema.html
new file mode 100644
index 0000000..01ca42e
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropschema.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP SCHEMA</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droprule.html" title="DROP RULE" /><link rel="next" href="sql-dropsequence.html" title="DROP SEQUENCE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP SCHEMA</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droprule.html" title="DROP RULE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropsequence.html" title="DROP SEQUENCE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPSCHEMA"><div class="titlepage"></div><a id="id-1.9.3.129.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP SCHEMA</span></h2><p>DROP SCHEMA — remove a schema</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP SCHEMA [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.129.5"><h2>Description</h2><p>
+ <code class="command">DROP SCHEMA</code> removes schemas from the database.
+ </p><p>
+ A schema can only be dropped by its owner or a superuser. Note that
+ the owner can drop the schema (and thereby all contained objects)
+ even if they do not own some of the objects within the schema.
+ </p></div><div class="refsect1" id="id-1.9.3.129.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the schema does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a schema.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects (tables, functions, etc.) that are
+ contained in the schema,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the schema if it contains any objects. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.129.7"><h2>Notes</h2><p>
+ Using the <code class="literal">CASCADE</code> option might make the command
+ remove objects in other schemas besides the one(s) named.
+ </p></div><div class="refsect1" id="id-1.9.3.129.8"><h2>Examples</h2><p>
+ To remove schema <code class="literal">mystuff</code> from the database,
+ along with everything it contains:
+
+</p><pre class="programlisting">
+DROP SCHEMA mystuff CASCADE;
+</pre></div><div class="refsect1" id="id-1.9.3.129.9"><h2>Compatibility</h2><p>
+ <code class="command">DROP SCHEMA</code> is fully conforming with the SQL
+ standard, except that the standard only allows one schema to be
+ dropped per command, and apart from the
+ <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.129.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterschema.html" title="ALTER SCHEMA"><span class="refentrytitle">ALTER SCHEMA</span></a>, <a class="xref" href="sql-createschema.html" title="CREATE SCHEMA"><span class="refentrytitle">CREATE SCHEMA</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droprule.html" title="DROP RULE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropsequence.html" title="DROP SEQUENCE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP RULE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP SEQUENCE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropsequence.html b/doc/src/sgml/html/sql-dropsequence.html
new file mode 100644
index 0000000..332304d
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropsequence.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP SEQUENCE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropschema.html" title="DROP SCHEMA" /><link rel="next" href="sql-dropserver.html" title="DROP SERVER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP SEQUENCE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropschema.html" title="DROP SCHEMA">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropserver.html" title="DROP SERVER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPSEQUENCE"><div class="titlepage"></div><a id="id-1.9.3.130.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP SEQUENCE</span></h2><p>DROP SEQUENCE — remove a sequence</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP SEQUENCE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.130.5"><h2>Description</h2><p>
+ <code class="command">DROP SEQUENCE</code> removes sequence number
+ generators. A sequence can only be dropped by its owner or a superuser.
+ </p></div><div class="refsect1" id="id-1.9.3.130.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the sequence does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a sequence.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the sequence,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the sequence if any objects depend on it. This
+ is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.130.7"><h2>Examples</h2><p>
+ To remove the sequence <code class="literal">serial</code>:
+
+</p><pre class="programlisting">
+DROP SEQUENCE serial;
+</pre></div><div class="refsect1" id="id-1.9.3.130.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP SEQUENCE</code> conforms to the <acronym class="acronym">SQL</acronym>
+ standard, except that the standard only allows one
+ sequence to be dropped per command, and apart from the
+ <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.130.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createsequence.html" title="CREATE SEQUENCE"><span class="refentrytitle">CREATE SEQUENCE</span></a>, <a class="xref" href="sql-altersequence.html" title="ALTER SEQUENCE"><span class="refentrytitle">ALTER SEQUENCE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropschema.html" title="DROP SCHEMA">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropserver.html" title="DROP SERVER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP SCHEMA </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP SERVER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropserver.html b/doc/src/sgml/html/sql-dropserver.html
new file mode 100644
index 0000000..b94b68c
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropserver.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP SERVER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropsequence.html" title="DROP SEQUENCE" /><link rel="next" href="sql-dropstatistics.html" title="DROP STATISTICS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP SERVER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropsequence.html" title="DROP SEQUENCE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropstatistics.html" title="DROP STATISTICS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPSERVER"><div class="titlepage"></div><a id="id-1.9.3.131.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP SERVER</span></h2><p>DROP SERVER — remove a foreign server descriptor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP SERVER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.131.5"><h2>Description</h2><p>
+ <code class="command">DROP SERVER</code> removes an existing foreign server
+ descriptor. To execute this command, the current user must be the
+ owner of the server.
+ </p></div><div class="refsect1" id="id-1.9.3.131.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the server does not exist. A notice is
+ issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of an existing server.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the server (such as
+ user mappings),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the server if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.131.7"><h2>Examples</h2><p>
+ Drop a server <code class="literal">foo</code> if it exists:
+</p><pre class="programlisting">
+DROP SERVER IF EXISTS foo;
+</pre></div><div class="refsect1" id="id-1.9.3.131.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP SERVER</code> conforms to ISO/IEC 9075-9
+ (SQL/MED). The <code class="literal">IF EXISTS</code> clause is
+ a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.131.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>, <a class="xref" href="sql-alterserver.html" title="ALTER SERVER"><span class="refentrytitle">ALTER SERVER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropsequence.html" title="DROP SEQUENCE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropstatistics.html" title="DROP STATISTICS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP SEQUENCE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP STATISTICS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropstatistics.html b/doc/src/sgml/html/sql-dropstatistics.html
new file mode 100644
index 0000000..f3cd4f0
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropstatistics.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP STATISTICS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropserver.html" title="DROP SERVER" /><link rel="next" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP STATISTICS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropserver.html" title="DROP SERVER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPSTATISTICS"><div class="titlepage"></div><a id="id-1.9.3.132.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP STATISTICS</span></h2><p>DROP STATISTICS — remove extended statistics</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP STATISTICS [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.132.5"><h2>Description</h2><p>
+ <code class="command">DROP STATISTICS</code> removes statistics object(s) from the
+ database. Only the statistics object's owner, the schema owner, or a
+ superuser can drop a statistics object.
+ </p></div><div class="refsect1" id="id-1.9.3.132.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the statistics object does not exist. A notice
+ is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the statistics object to drop.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no dependencies
+ on statistics.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.132.7"><h2>Examples</h2><p>
+ To destroy two statistics objects in different schemas, without failing
+ if they don't exist:
+
+</p><pre class="programlisting">
+DROP STATISTICS IF EXISTS
+ accounting.users_uid_creation,
+ public.grants_user_role;
+</pre></div><div class="refsect1" id="id-1.9.3.132.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP STATISTICS</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.132.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterstatistics.html" title="ALTER STATISTICS"><span class="refentrytitle">ALTER STATISTICS</span></a>, <a class="xref" href="sql-createstatistics.html" title="CREATE STATISTICS"><span class="refentrytitle">CREATE STATISTICS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropserver.html" title="DROP SERVER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP SERVER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP SUBSCRIPTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropsubscription.html b/doc/src/sgml/html/sql-dropsubscription.html
new file mode 100644
index 0000000..c41dfb3
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropsubscription.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP SUBSCRIPTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropstatistics.html" title="DROP STATISTICS" /><link rel="next" href="sql-droptable.html" title="DROP TABLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP SUBSCRIPTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropstatistics.html" title="DROP STATISTICS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptable.html" title="DROP TABLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPSUBSCRIPTION"><div class="titlepage"></div><a id="id-1.9.3.133.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP SUBSCRIPTION</span></h2><p>DROP SUBSCRIPTION — remove a subscription</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP SUBSCRIPTION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.133.5"><h2>Description</h2><p>
+ <code class="command">DROP SUBSCRIPTION</code> removes a subscription from the
+ database cluster.
+ </p><p>
+ A subscription can only be dropped by a superuser.
+ </p><p>
+ <code class="command">DROP SUBSCRIPTION</code> cannot be executed inside a
+ transaction block if the subscription is associated with a replication
+ slot. (You can use <code class="command">ALTER SUBSCRIPTION</code> to unset the
+ slot.)
+ </p></div><div class="refsect1" id="id-1.9.3.133.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a subscription to be dropped.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code><br /></span><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ These key words do not have any effect, since there are no dependencies
+ on subscriptions.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.133.7"><h2>Notes</h2><p>
+ When dropping a subscription that is associated with a replication slot on
+ the remote host (the normal state), <code class="command">DROP SUBSCRIPTION</code>
+ will connect to the remote host and try to drop the replication slot (and
+ any remaining table synchronization slots) as
+ part of its operation. This is necessary so that the resources allocated
+ for the subscription on the remote host are released. If this fails,
+ either because the remote host is not reachable or because the remote
+ replication slot cannot be dropped or does not exist or never existed,
+ the <code class="command">DROP SUBSCRIPTION</code> command will fail. To proceed
+ in this situation, first disable the subscription by executing
+ <code class="literal">ALTER SUBSCRIPTION ... DISABLE</code>, and then disassociate
+ it from the replication slot by executing
+ <code class="literal">ALTER SUBSCRIPTION ... SET (slot_name = NONE)</code>.
+ After that, <code class="command">DROP SUBSCRIPTION</code> will no longer attempt any
+ actions on a remote host. Note that if the remote replication slot still
+ exists, it (and any related table synchronization slots) should then be
+ dropped manually; otherwise it/they will continue to
+ reserve WAL and might eventually cause the disk to fill up. See
+ also <a class="xref" href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-SLOT" title="31.2.1. Replication Slot Management">Section 31.2.1</a>.
+ </p><p>
+ If a subscription is associated with a replication slot, then <code class="command">DROP
+ SUBSCRIPTION</code> cannot be executed inside a transaction block.
+ </p></div><div class="refsect1" id="id-1.9.3.133.8"><h2>Examples</h2><p>
+ Drop a subscription:
+</p><pre class="programlisting">
+DROP SUBSCRIPTION mysub;
+</pre></div><div class="refsect1" id="id-1.9.3.133.9"><h2>Compatibility</h2><p>
+ <code class="command">DROP SUBSCRIPTION</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.133.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a>, <a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropstatistics.html" title="DROP STATISTICS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptable.html" title="DROP TABLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP STATISTICS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TABLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptable.html b/doc/src/sgml/html/sql-droptable.html
new file mode 100644
index 0000000..6c8c47e
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptable.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION" /><link rel="next" href="sql-droptablespace.html" title="DROP TABLESPACE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptablespace.html" title="DROP TABLESPACE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTABLE"><div class="titlepage"></div><a id="id-1.9.3.134.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TABLE</span></h2><p>DROP TABLE — remove a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.134.5"><h2>Description</h2><p>
+ <code class="command">DROP TABLE</code> removes tables from the database.
+ Only the table owner, the schema owner, and superuser can drop a
+ table. To empty a table of rows
+ without destroying the table, use <a class="link" href="sql-delete.html" title="DELETE"><code class="command">DELETE</code></a>
+ or <a class="link" href="sql-truncate.html" title="TRUNCATE"><code class="command">TRUNCATE</code></a>.
+ </p><p>
+ <code class="command">DROP TABLE</code> always removes any indexes, rules,
+ triggers, and constraints that exist for the target table.
+ However, to drop a table that is referenced by a view or a foreign-key
+ constraint of another table, <code class="literal">CASCADE</code> must be
+ specified. (<code class="literal">CASCADE</code> will remove a dependent view entirely,
+ but in the foreign-key case it will only remove the foreign-key
+ constraint, not the other table entirely.)
+ </p></div><div class="refsect1" id="id-1.9.3.134.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the table does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to drop.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the table (such as
+ views),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the table if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.134.7"><h2>Examples</h2><p>
+ To destroy two tables, <code class="literal">films</code> and
+ <code class="literal">distributors</code>:
+
+</p><pre class="programlisting">
+DROP TABLE films, distributors;
+</pre></div><div class="refsect1" id="id-1.9.3.134.8"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, except that the standard only
+ allows one table to be dropped per command, and apart from the
+ <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.134.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a>, <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptablespace.html" title="DROP TABLESPACE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP SUBSCRIPTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TABLESPACE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptablespace.html b/doc/src/sgml/html/sql-droptablespace.html
new file mode 100644
index 0000000..2e58cc2
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptablespace.html
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TABLESPACE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptable.html" title="DROP TABLE" /><link rel="next" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TABLESPACE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptable.html" title="DROP TABLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTABLESPACE"><div class="titlepage"></div><a id="id-1.9.3.135.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TABLESPACE</span></h2><p>DROP TABLESPACE — remove a tablespace</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TABLESPACE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.135.5"><h2>Description</h2><p>
+ <code class="command">DROP TABLESPACE</code> removes a tablespace from the system.
+ </p><p>
+ A tablespace can only be dropped by its owner or a superuser.
+ The tablespace must be empty of all database objects before it can be
+ dropped. It is possible that objects in other databases might still reside
+ in the tablespace even if no objects in the current database are using
+ the tablespace. Also, if the tablespace is listed in the <a class="xref" href="runtime-config-client.html#GUC-TEMP-TABLESPACES">temp_tablespaces</a> setting of any active session, the
+ <code class="command">DROP</code> might fail due to temporary files residing in the
+ tablespace.
+ </p></div><div class="refsect1" id="id-1.9.3.135.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the tablespace does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a tablespace.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.135.7"><h2>Notes</h2><p>
+ <code class="command">DROP TABLESPACE</code> cannot be executed inside a transaction block.
+ </p></div><div class="refsect1" id="id-1.9.3.135.8"><h2>Examples</h2><p>
+ To remove tablespace <code class="literal">mystuff</code> from the system:
+</p><pre class="programlisting">
+DROP TABLESPACE mystuff;
+</pre></div><div class="refsect1" id="id-1.9.3.135.9"><h2>Compatibility</h2><p>
+ <code class="command">DROP TABLESPACE</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.135.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>, <a class="xref" href="sql-altertablespace.html" title="ALTER TABLESPACE"><span class="refentrytitle">ALTER TABLESPACE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptable.html" title="DROP TABLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TABLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TEXT SEARCH CONFIGURATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptransform.html b/doc/src/sgml/html/sql-droptransform.html
new file mode 100644
index 0000000..301f568
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptransform.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TRANSFORM</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE" /><link rel="next" href="sql-droptrigger.html" title="DROP TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TRANSFORM</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptrigger.html" title="DROP TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTRANSFORM"><div class="titlepage"></div><a id="id-1.9.3.140.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TRANSFORM</span></h2><p>DROP TRANSFORM — remove a transform</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TRANSFORM [ IF EXISTS ] FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="SQL-DROPTRANSFORM-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">DROP TRANSFORM</code> removes a previously defined transform.
+ </p><p>
+ To be able to drop a transform, you must own the type and the language.
+ These are the same privileges that are required to create a transform.
+ </p></div><div class="refsect1" id="id-1.9.3.140.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the transform does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
+ The name of the data type of the transform.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
+ The name of the language of the transform.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the transform,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the transform if any objects depend on it. This is the
+ default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPTRANSFORM-EXAMPLES"><h2>Examples</h2><p>
+ To drop the transform for type <code class="type">hstore</code> and language
+ <code class="literal">plpython3u</code>:
+</p><pre class="programlisting">
+DROP TRANSFORM FOR hstore LANGUAGE plpython3u;
+</pre></div><div class="refsect1" id="SQL-DROPTRANSFORM-COMPAT"><h2>Compatibility</h2><p>
+ This form of <code class="command">DROP TRANSFORM</code> is a
+ <span class="productname">PostgreSQL</span> extension. See <a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.140.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtransform.html" title="CREATE TRANSFORM"><span class="refentrytitle">CREATE TRANSFORM</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptrigger.html" title="DROP TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TEXT SEARCH TEMPLATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TRIGGER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptrigger.html b/doc/src/sgml/html/sql-droptrigger.html
new file mode 100644
index 0000000..1899fbd
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptrigger.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TRIGGER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptransform.html" title="DROP TRANSFORM" /><link rel="next" href="sql-droptype.html" title="DROP TYPE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TRIGGER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptransform.html" title="DROP TRANSFORM">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptype.html" title="DROP TYPE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTRIGGER"><div class="titlepage"></div><a id="id-1.9.3.141.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TRIGGER</span></h2><p>DROP TRIGGER — remove a trigger</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TRIGGER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table_name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.141.5"><h2>Description</h2><p>
+ <code class="command">DROP TRIGGER</code> removes an existing
+ trigger definition. To execute this command, the current
+ user must be the owner of the table for which the trigger is defined.
+ </p></div><div class="refsect1" id="id-1.9.3.141.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the trigger does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the trigger to remove.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table for which
+ the trigger is defined.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the trigger,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the trigger if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPTRIGGER-EXAMPLES"><h2>Examples</h2><p>
+ Destroy the trigger <code class="literal">if_dist_exists</code> on the table
+ <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+DROP TRIGGER if_dist_exists ON films;
+</pre></div><div class="refsect1" id="SQL-DROPTRIGGER-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The <code class="command">DROP TRIGGER</code> statement in
+ <span class="productname">PostgreSQL</span> is incompatible with the SQL
+ standard. In the SQL standard, trigger names are not local to
+ tables, so the command is simply <code class="literal">DROP TRIGGER
+ <em class="replaceable"><code>name</code></em></code>.
+ </p></div><div class="refsect1" id="id-1.9.3.141.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptransform.html" title="DROP TRANSFORM">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptype.html" title="DROP TYPE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TRANSFORM </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TYPE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptsconfig.html b/doc/src/sgml/html/sql-droptsconfig.html
new file mode 100644
index 0000000..17a49d3
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptsconfig.html
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TEXT SEARCH CONFIGURATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptablespace.html" title="DROP TABLESPACE" /><link rel="next" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TEXT SEARCH CONFIGURATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptablespace.html" title="DROP TABLESPACE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTSCONFIG"><div class="titlepage"></div><a id="id-1.9.3.136.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TEXT SEARCH CONFIGURATION</span></h2><p>DROP TEXT SEARCH CONFIGURATION — remove a text search configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.136.5"><h2>Description</h2><p>
+ <code class="command">DROP TEXT SEARCH CONFIGURATION</code> drops an existing text
+ search configuration. To execute this command you must be the owner of the
+ configuration.
+ </p></div><div class="refsect1" id="id-1.9.3.136.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the text search configuration does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search
+ configuration.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the text search configuration,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the text search configuration if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.136.7"><h2>Examples</h2><p>
+ Remove the text search configuration <code class="literal">my_english</code>:
+
+</p><pre class="programlisting">
+DROP TEXT SEARCH CONFIGURATION my_english;
+</pre><p>
+
+ This command will not succeed if there are any existing indexes
+ that reference the configuration in <code class="function">to_tsvector</code> calls.
+ Add <code class="literal">CASCADE</code> to
+ drop such indexes along with the text search configuration.
+ </p></div><div class="refsect1" id="id-1.9.3.136.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP TEXT SEARCH CONFIGURATION</code> statement in
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.136.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsconfig.html" title="ALTER TEXT SEARCH CONFIGURATION"><span class="refentrytitle">ALTER TEXT SEARCH CONFIGURATION</span></a>, <a class="xref" href="sql-createtsconfig.html" title="CREATE TEXT SEARCH CONFIGURATION"><span class="refentrytitle">CREATE TEXT SEARCH CONFIGURATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptablespace.html" title="DROP TABLESPACE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TABLESPACE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TEXT SEARCH DICTIONARY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptsdictionary.html b/doc/src/sgml/html/sql-droptsdictionary.html
new file mode 100644
index 0000000..6c1b2ee
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptsdictionary.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TEXT SEARCH DICTIONARY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION" /><link rel="next" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TEXT SEARCH DICTIONARY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTSDICTIONARY"><div class="titlepage"></div><a id="id-1.9.3.137.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TEXT SEARCH DICTIONARY</span></h2><p>DROP TEXT SEARCH DICTIONARY — remove a text search dictionary</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.137.5"><h2>Description</h2><p>
+ <code class="command">DROP TEXT SEARCH DICTIONARY</code> drops an existing text
+ search dictionary. To execute this command you must be the owner of the
+ dictionary.
+ </p></div><div class="refsect1" id="id-1.9.3.137.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the text search dictionary does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search
+ dictionary.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the text search dictionary,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the text search dictionary if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.137.7"><h2>Examples</h2><p>
+ Remove the text search dictionary <code class="literal">english</code>:
+
+</p><pre class="programlisting">
+DROP TEXT SEARCH DICTIONARY english;
+</pre><p>
+
+ This command will not succeed if there are any existing text search
+ configurations that use the dictionary. Add <code class="literal">CASCADE</code> to
+ drop such configurations along with the dictionary.
+ </p></div><div class="refsect1" id="id-1.9.3.137.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP TEXT SEARCH DICTIONARY</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.137.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsdictionary.html" title="ALTER TEXT SEARCH DICTIONARY"><span class="refentrytitle">ALTER TEXT SEARCH DICTIONARY</span></a>, <a class="xref" href="sql-createtsdictionary.html" title="CREATE TEXT SEARCH DICTIONARY"><span class="refentrytitle">CREATE TEXT SEARCH DICTIONARY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptsconfig.html" title="DROP TEXT SEARCH CONFIGURATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TEXT SEARCH CONFIGURATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TEXT SEARCH PARSER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptsparser.html b/doc/src/sgml/html/sql-droptsparser.html
new file mode 100644
index 0000000..fd492d1
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptsparser.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TEXT SEARCH PARSER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY" /><link rel="next" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TEXT SEARCH PARSER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTSPARSER"><div class="titlepage"></div><a id="id-1.9.3.138.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TEXT SEARCH PARSER</span></h2><p>DROP TEXT SEARCH PARSER — remove a text search parser</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TEXT SEARCH PARSER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.138.5"><h2>Description</h2><p>
+ <code class="command">DROP TEXT SEARCH PARSER</code> drops an existing text search
+ parser. You must be a superuser to use this command.
+ </p></div><div class="refsect1" id="id-1.9.3.138.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the text search parser does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search parser.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the text search parser,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the text search parser if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.138.7"><h2>Examples</h2><p>
+ Remove the text search parser <code class="literal">my_parser</code>:
+
+</p><pre class="programlisting">
+DROP TEXT SEARCH PARSER my_parser;
+</pre><p>
+
+ This command will not succeed if there are any existing text search
+ configurations that use the parser. Add <code class="literal">CASCADE</code> to
+ drop such configurations along with the parser.
+ </p></div><div class="refsect1" id="id-1.9.3.138.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP TEXT SEARCH PARSER</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.138.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertsparser.html" title="ALTER TEXT SEARCH PARSER"><span class="refentrytitle">ALTER TEXT SEARCH PARSER</span></a>, <a class="xref" href="sql-createtsparser.html" title="CREATE TEXT SEARCH PARSER"><span class="refentrytitle">CREATE TEXT SEARCH PARSER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptsdictionary.html" title="DROP TEXT SEARCH DICTIONARY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptstemplate.html" title="DROP TEXT SEARCH TEMPLATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TEXT SEARCH DICTIONARY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TEXT SEARCH TEMPLATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptstemplate.html b/doc/src/sgml/html/sql-droptstemplate.html
new file mode 100644
index 0000000..0c0edae
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptstemplate.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TEXT SEARCH TEMPLATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER" /><link rel="next" href="sql-droptransform.html" title="DROP TRANSFORM" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TEXT SEARCH TEMPLATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-droptransform.html" title="DROP TRANSFORM">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTSTEMPLATE"><div class="titlepage"></div><a id="id-1.9.3.139.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TEXT SEARCH TEMPLATE</span></h2><p>DROP TEXT SEARCH TEMPLATE — remove a text search template</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.139.5"><h2>Description</h2><p>
+ <code class="command">DROP TEXT SEARCH TEMPLATE</code> drops an existing text search
+ template. You must be a superuser to use this command.
+ </p></div><div class="refsect1" id="id-1.9.3.139.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the text search template does not exist.
+ A notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing text search
+ template.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the text search template,
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the text search template if any objects depend on it.
+ This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.139.7"><h2>Examples</h2><p>
+ Remove the text search template <code class="literal">thesaurus</code>:
+
+</p><pre class="programlisting">
+DROP TEXT SEARCH TEMPLATE thesaurus;
+</pre><p>
+
+ This command will not succeed if there are any existing text search
+ dictionaries that use the template. Add <code class="literal">CASCADE</code> to
+ drop such dictionaries along with the template.
+ </p></div><div class="refsect1" id="id-1.9.3.139.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">DROP TEXT SEARCH TEMPLATE</code> statement in the
+ SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.139.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertstemplate.html" title="ALTER TEXT SEARCH TEMPLATE"><span class="refentrytitle">ALTER TEXT SEARCH TEMPLATE</span></a>, <a class="xref" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE"><span class="refentrytitle">CREATE TEXT SEARCH TEMPLATE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptsparser.html" title="DROP TEXT SEARCH PARSER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-droptransform.html" title="DROP TRANSFORM">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TEXT SEARCH PARSER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP TRANSFORM</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-droptype.html b/doc/src/sgml/html/sql-droptype.html
new file mode 100644
index 0000000..8d68fb0
--- /dev/null
+++ b/doc/src/sgml/html/sql-droptype.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP TYPE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptrigger.html" title="DROP TRIGGER" /><link rel="next" href="sql-dropuser.html" title="DROP USER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP TYPE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptrigger.html" title="DROP TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropuser.html" title="DROP USER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPTYPE"><div class="titlepage"></div><a id="id-1.9.3.142.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP TYPE</span></h2><p>DROP TYPE — remove a data type</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP TYPE [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.142.5"><h2>Description</h2><p>
+ <code class="command">DROP TYPE</code> removes a user-defined data type.
+ Only the owner of a type can remove it.
+ </p></div><div class="refsect1" id="id-1.9.3.142.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the type does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the data type to remove.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the type (such as
+ table columns, functions, and operators),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the type if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-DROPTYPE-EXAMPLES"><h2>Examples</h2><p>
+ To remove the data type <code class="type">box</code>:
+</p><pre class="programlisting">
+DROP TYPE box;
+</pre></div><div class="refsect1" id="SQL-DROPTYPE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ This command is similar to the corresponding command in the SQL
+ standard, apart from the <code class="literal">IF EXISTS</code>
+ option, which is a <span class="productname">PostgreSQL</span> extension.
+ But note that much of the <code class="command">CREATE TYPE</code> command
+ and the data type extension mechanisms in
+ <span class="productname">PostgreSQL</span> differ from the SQL standard.
+ </p></div><div class="refsect1" id="SQL-DROPTYPE-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-altertype.html" title="ALTER TYPE"><span class="refentrytitle">ALTER TYPE</span></a>, <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptrigger.html" title="DROP TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropuser.html" title="DROP USER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP USER</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropuser.html b/doc/src/sgml/html/sql-dropuser.html
new file mode 100644
index 0000000..a8317a2
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropuser.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP USER</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-droptype.html" title="DROP TYPE" /><link rel="next" href="sql-dropusermapping.html" title="DROP USER MAPPING" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP USER</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-droptype.html" title="DROP TYPE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropusermapping.html" title="DROP USER MAPPING">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPUSER"><div class="titlepage"></div><a id="id-1.9.3.143.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP USER</span></h2><p>DROP USER — remove a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP USER [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...]
+</pre></div><div class="refsect1" id="id-1.9.3.143.5"><h2>Description</h2><p>
+ <code class="command">DROP USER</code> is simply an alternate spelling of
+ <a class="link" href="sql-droprole.html" title="DROP ROLE"><code class="command">DROP ROLE</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.143.6"><h2>Compatibility</h2><p>
+ The <code class="command">DROP USER</code> statement is a
+ <span class="productname">PostgreSQL</span> extension. The SQL standard
+ leaves the definition of users to the implementation.
+ </p></div><div class="refsect1" id="id-1.9.3.143.7"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-droptype.html" title="DROP TYPE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropusermapping.html" title="DROP USER MAPPING">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP TYPE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP USER MAPPING</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropusermapping.html b/doc/src/sgml/html/sql-dropusermapping.html
new file mode 100644
index 0000000..187051a
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropusermapping.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP USER MAPPING</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropuser.html" title="DROP USER" /><link rel="next" href="sql-dropview.html" title="DROP VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP USER MAPPING</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropuser.html" title="DROP USER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-dropview.html" title="DROP VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPUSERMAPPING"><div class="titlepage"></div><a id="id-1.9.3.144.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP USER MAPPING</span></h2><p>DROP USER MAPPING — remove a user mapping for a foreign server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP USER MAPPING [ IF EXISTS ] FOR { <em class="replaceable"><code>user_name</code></em> | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC } SERVER <em class="replaceable"><code>server_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.144.5"><h2>Description</h2><p>
+ <code class="command">DROP USER MAPPING</code> removes an existing user
+ mapping from foreign server.
+ </p><p>
+ The owner of a foreign server can drop user mappings for that server
+ for any user. Also, a user can drop a user mapping for their own
+ user name if <code class="literal">USAGE</code> privilege on the server has been
+ granted to the user.
+ </p></div><div class="refsect1" id="id-1.9.3.144.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the user mapping does not exist. A
+ notice is issued in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>user_name</code></em></span></dt><dd><p>
+ User name of the mapping. <code class="literal">CURRENT_ROLE</code>, <code class="literal">CURRENT_USER</code>,
+ and <code class="literal">USER</code> match the name of the current
+ user. <code class="literal">PUBLIC</code> is used to match all present and
+ future user names in the system.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ Server name of the user mapping.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.144.7"><h2>Examples</h2><p>
+ Drop a user mapping <code class="literal">bob</code>, server <code class="literal">foo</code> if it exists:
+</p><pre class="programlisting">
+DROP USER MAPPING IF EXISTS FOR bob SERVER foo;
+</pre></div><div class="refsect1" id="id-1.9.3.144.8"><h2>Compatibility</h2><p>
+ <code class="command">DROP USER MAPPING</code> conforms to ISO/IEC 9075-9
+ (SQL/MED). The <code class="literal">IF EXISTS</code> clause is
+ a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.144.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createusermapping.html" title="CREATE USER MAPPING"><span class="refentrytitle">CREATE USER MAPPING</span></a>, <a class="xref" href="sql-alterusermapping.html" title="ALTER USER MAPPING"><span class="refentrytitle">ALTER USER MAPPING</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropuser.html" title="DROP USER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-dropview.html" title="DROP VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP USER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> DROP VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-dropview.html b/doc/src/sgml/html/sql-dropview.html
new file mode 100644
index 0000000..7316310
--- /dev/null
+++ b/doc/src/sgml/html/sql-dropview.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DROP VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropusermapping.html" title="DROP USER MAPPING" /><link rel="next" href="sql-end.html" title="END" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">DROP VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropusermapping.html" title="DROP USER MAPPING">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-end.html" title="END">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-DROPVIEW"><div class="titlepage"></div><a id="id-1.9.3.145.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">DROP VIEW</span></h2><p>DROP VIEW — remove a view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+DROP VIEW [ IF EXISTS ] <em class="replaceable"><code>name</code></em> [, ...] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.145.5"><h2>Description</h2><p>
+ <code class="command">DROP VIEW</code> drops an existing view. To execute
+ this command you must be the owner of the view.
+ </p></div><div class="refsect1" id="id-1.9.3.145.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF EXISTS</code></span></dt><dd><p>
+ Do not throw an error if the view does not exist. A notice is issued
+ in this case.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the view to remove.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically drop objects that depend on the view (such as
+ other views),
+ and in turn all objects that depend on those objects
+ (see <a class="xref" href="ddl-depend.html" title="5.14. Dependency Tracking">Section 5.14</a>).
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to drop the view if any objects depend on it. This is
+ the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.145.7"><h2>Examples</h2><p>
+ This command will remove the view called <code class="literal">kinds</code>:
+</p><pre class="programlisting">
+DROP VIEW kinds;
+</pre></div><div class="refsect1" id="id-1.9.3.145.8"><h2>Compatibility</h2><p>
+ This command conforms to the SQL standard, except that the standard only
+ allows one view to be dropped per command, and apart from the
+ <code class="literal">IF EXISTS</code> option, which is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.145.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterview.html" title="ALTER VIEW"><span class="refentrytitle">ALTER VIEW</span></a>, <a class="xref" href="sql-createview.html" title="CREATE VIEW"><span class="refentrytitle">CREATE VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropusermapping.html" title="DROP USER MAPPING">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-end.html" title="END">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP USER MAPPING </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> END</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-end.html b/doc/src/sgml/html/sql-end.html
new file mode 100644
index 0000000..8ab9840
--- /dev/null
+++ b/doc/src/sgml/html/sql-end.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>END</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-dropview.html" title="DROP VIEW" /><link rel="next" href="sql-execute.html" title="EXECUTE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">END</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-dropview.html" title="DROP VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-execute.html" title="EXECUTE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-END"><div class="titlepage"></div><a id="id-1.9.3.146.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">END</span></h2><p>END — commit the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+END [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
+</pre></div><div class="refsect1" id="id-1.9.3.146.5"><h2>Description</h2><p>
+ <code class="command">END</code> commits the current transaction. All changes
+ made by the transaction become visible to others and are guaranteed
+ to be durable if a crash occurs. This command is a
+ <span class="productname">PostgreSQL</span> extension
+ that is equivalent to <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.146.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">WORK</code><br /></span><span class="term"><code class="literal">TRANSACTION</code></span></dt><dd><p>
+ Optional key words. They have no effect.
+ </p></dd><dt><span class="term"><code class="literal">AND CHAIN</code></span></dt><dd><p>
+ If <code class="literal">AND CHAIN</code> is specified, a new transaction is
+ immediately started with the same transaction characteristics (see <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a>) as the just finished one. Otherwise,
+ no new transaction is started.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.146.7"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a> to
+ abort a transaction.
+ </p><p>
+ Issuing <code class="command">END</code> when not inside a transaction does
+ no harm, but it will provoke a warning message.
+ </p></div><div class="refsect1" id="id-1.9.3.146.8"><h2>Examples</h2><p>
+ To commit the current transaction and make all changes permanent:
+</p><pre class="programlisting">
+END;
+</pre></div><div class="refsect1" id="id-1.9.3.146.9"><h2>Compatibility</h2><p>
+ <code class="command">END</code> is a <span class="productname">PostgreSQL</span>
+ extension that provides functionality equivalent to <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a>, which is
+ specified in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.146.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-dropview.html" title="DROP VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-execute.html" title="EXECUTE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DROP VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> EXECUTE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-execute.html b/doc/src/sgml/html/sql-execute.html
new file mode 100644
index 0000000..8ef612f
--- /dev/null
+++ b/doc/src/sgml/html/sql-execute.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>EXECUTE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-end.html" title="END" /><link rel="next" href="sql-explain.html" title="EXPLAIN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">EXECUTE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-end.html" title="END">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-explain.html" title="EXPLAIN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-EXECUTE"><div class="titlepage"></div><a id="id-1.9.3.147.1" class="indexterm"></a><a id="id-1.9.3.147.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">EXECUTE</span></h2><p>EXECUTE — execute a prepared statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+EXECUTE <em class="replaceable"><code>name</code></em> [ ( <em class="replaceable"><code>parameter</code></em> [, ...] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.147.6"><h2>Description</h2><p>
+ <code class="command">EXECUTE</code> is used to execute a previously prepared
+ statement. Since prepared statements only exist for the duration of a
+ session, the prepared statement must have been created by a
+ <code class="command">PREPARE</code> statement executed earlier in the
+ current session.
+ </p><p>
+ If the <code class="command">PREPARE</code> statement that created the statement
+ specified some parameters, a compatible set of parameters must be
+ passed to the <code class="command">EXECUTE</code> statement, or else an
+ error is raised. Note that (unlike functions) prepared statements are
+ not overloaded based on the type or number of their parameters; the
+ name of a prepared statement must be unique within a database session.
+ </p><p>
+ For more information on the creation and usage of prepared statements,
+ see <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.147.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the prepared statement to execute.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>parameter</code></em></span></dt><dd><p>
+ The actual value of a parameter to the prepared statement. This
+ must be an expression yielding a value that is compatible with
+ the data type of this parameter, as was determined when the
+ prepared statement was created.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.147.8"><h2>Outputs</h2><p>
+ The command tag returned by <code class="command">EXECUTE</code>
+ is that of the prepared statement, and not <code class="literal">EXECUTE</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.147.9"><h2>Examples</h2><p>
+ Examples are given in <a class="xref" href="sql-prepare.html#SQL-PREPARE-EXAMPLES" title="Examples">Examples</a>
+ in the <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> documentation.
+ </p></div><div class="refsect1" id="id-1.9.3.147.10"><h2>Compatibility</h2><p>
+ The SQL standard includes an <code class="command">EXECUTE</code> statement,
+ but it is only for use in embedded SQL. This version of the
+ <code class="command">EXECUTE</code> statement also uses a somewhat different
+ syntax.
+ </p></div><div class="refsect1" id="id-1.9.3.147.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-deallocate.html" title="DEALLOCATE"><span class="refentrytitle">DEALLOCATE</span></a>, <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-end.html" title="END">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-explain.html" title="EXPLAIN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">END </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> EXPLAIN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-explain.html b/doc/src/sgml/html/sql-explain.html
new file mode 100644
index 0000000..fb29950
--- /dev/null
+++ b/doc/src/sgml/html/sql-explain.html
@@ -0,0 +1,306 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>EXPLAIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-execute.html" title="EXECUTE" /><link rel="next" href="sql-fetch.html" title="FETCH" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">EXPLAIN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-execute.html" title="EXECUTE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-fetch.html" title="FETCH">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-EXPLAIN"><div class="titlepage"></div><a id="id-1.9.3.148.1" class="indexterm"></a><a id="id-1.9.3.148.2" class="indexterm"></a><a id="id-1.9.3.148.3" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">EXPLAIN</span></h2><p>EXPLAIN — show the execution plan of a statement</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+EXPLAIN [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ] <em class="replaceable"><code>statement</code></em>
+EXPLAIN [ ANALYZE ] [ VERBOSE ] <em class="replaceable"><code>statement</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ ANALYZE [ <em class="replaceable"><code>boolean</code></em> ]
+ VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
+ COSTS [ <em class="replaceable"><code>boolean</code></em> ]
+ SETTINGS [ <em class="replaceable"><code>boolean</code></em> ]
+ BUFFERS [ <em class="replaceable"><code>boolean</code></em> ]
+ WAL [ <em class="replaceable"><code>boolean</code></em> ]
+ TIMING [ <em class="replaceable"><code>boolean</code></em> ]
+ SUMMARY [ <em class="replaceable"><code>boolean</code></em> ]
+ FORMAT { TEXT | XML | JSON | YAML }
+</pre></div><div class="refsect1" id="id-1.9.3.148.7"><h2>Description</h2><p>
+ This command displays the execution plan that the
+ <span class="productname">PostgreSQL</span> planner generates for the
+ supplied statement. The execution plan shows how the table(s)
+ referenced by the statement will be scanned — by plain sequential scan,
+ index scan, etc. — and if multiple tables are referenced, what join
+ algorithms will be used to bring together the required rows from
+ each input table.
+ </p><p>
+ The most critical part of the display is the estimated statement execution
+ cost, which is the planner's guess at how long it will take to run the
+ statement (measured in cost units that are arbitrary, but conventionally
+ mean disk page fetches). Actually two numbers
+ are shown: the start-up cost before the first row can be returned, and
+ the total cost to return all the rows. For most queries the total cost
+ is what matters, but in contexts such as a subquery in <code class="literal">EXISTS</code>, the planner
+ will choose the smallest start-up cost instead of the smallest total cost
+ (since the executor will stop after getting one row, anyway).
+ Also, if you limit the number of rows to return with a <code class="literal">LIMIT</code> clause,
+ the planner makes an appropriate interpolation between the endpoint
+ costs to estimate which plan is really the cheapest.
+ </p><p>
+ The <code class="literal">ANALYZE</code> option causes the statement to be actually
+ executed, not only planned. Then actual run time statistics are added to
+ the display, including the total elapsed time expended within each plan
+ node (in milliseconds) and the total number of rows it actually returned.
+ This is useful for seeing whether the planner's estimates
+ are close to reality.
+ </p><div class="important"><h3 class="title">Important</h3><p>
+ Keep in mind that the statement is actually executed when
+ the <code class="literal">ANALYZE</code> option is used. Although
+ <code class="command">EXPLAIN</code> will discard any output that a
+ <code class="command">SELECT</code> would return, other side effects of the
+ statement will happen as usual. If you wish to use
+ <code class="command">EXPLAIN ANALYZE</code> on an
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">MERGE</code>,
+ <code class="command">CREATE TABLE AS</code>,
+ or <code class="command">EXECUTE</code> statement
+ without letting the command affect your data, use this approach:
+</p><pre class="programlisting">
+BEGIN;
+EXPLAIN ANALYZE ...;
+ROLLBACK;
+</pre><p>
+ </p></div><p>
+ Only the <code class="literal">ANALYZE</code> and <code class="literal">VERBOSE</code> options
+ can be specified, and only in that order, without surrounding the option
+ list in parentheses. Prior to <span class="productname">PostgreSQL</span> 9.0,
+ the unparenthesized syntax was the only one supported. It is expected that
+ all new options will be supported only in the parenthesized syntax.
+ </p></div><div class="refsect1" id="id-1.9.3.148.8"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ANALYZE</code></span></dt><dd><p>
+ Carry out the command and show actual run times and other statistics.
+ This parameter defaults to <code class="literal">FALSE</code>.
+ </p></dd><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
+ Display additional information regarding the plan. Specifically, include
+ the output column list for each node in the plan tree, schema-qualify
+ table and function names, always label variables in expressions with
+ their range table alias, and always print the name of each trigger for
+ which statistics are displayed. The query identifier will also be
+ displayed if one has been computed, see <a class="xref" href="runtime-config-statistics.html#GUC-COMPUTE-QUERY-ID">compute_query_id</a> for more details. This parameter
+ defaults to <code class="literal">FALSE</code>.
+ </p></dd><dt><span class="term"><code class="literal">COSTS</code></span></dt><dd><p>
+ Include information on the estimated startup and total cost of each
+ plan node, as well as the estimated number of rows and the estimated
+ width of each row.
+ This parameter defaults to <code class="literal">TRUE</code>.
+ </p></dd><dt><span class="term"><code class="literal">SETTINGS</code></span></dt><dd><p>
+ Include information on configuration parameters. Specifically, include
+ options affecting query planning with value different from the built-in
+ default value. This parameter defaults to <code class="literal">FALSE</code>.
+ </p></dd><dt><span class="term"><code class="literal">BUFFERS</code></span></dt><dd><p>
+ Include information on buffer usage. Specifically, include the number of
+ shared blocks hit, read, dirtied, and written, the number of local blocks
+ hit, read, dirtied, and written, the number of temp blocks read and
+ written, and the time spent reading and writing data file blocks and
+ temporary file blocks (in milliseconds) if
+ <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-IO-TIMING">track_io_timing</a> is enabled. A
+ <span class="emphasis"><em>hit</em></span> means that a read was avoided because the block
+ was found already in cache when needed.
+ Shared blocks contain data from regular tables and indexes;
+ local blocks contain data from temporary tables and indexes;
+ while temporary blocks contain short-term working data used in sorts,
+ hashes, Materialize plan nodes, and similar cases.
+ The number of blocks <span class="emphasis"><em>dirtied</em></span> indicates the number of
+ previously unmodified blocks that were changed by this query; while the
+ number of blocks <span class="emphasis"><em>written</em></span> indicates the number of
+ previously-dirtied blocks evicted from cache by this backend during
+ query processing.
+ The number of blocks shown for an
+ upper-level node includes those used by all its child nodes. In text
+ format, only non-zero values are printed. It defaults to
+ <code class="literal">FALSE</code>.
+ </p></dd><dt><span class="term"><code class="literal">WAL</code></span></dt><dd><p>
+ Include information on WAL record generation. Specifically, include the
+ number of records, number of full page images (fpi) and the amount of WAL
+ generated in bytes. In text format, only non-zero values are printed.
+ This parameter may only be used when <code class="literal">ANALYZE</code> is also
+ enabled. It defaults to <code class="literal">FALSE</code>.
+ </p></dd><dt><span class="term"><code class="literal">TIMING</code></span></dt><dd><p>
+ Include actual startup time and time spent in each node in the output.
+ The overhead of repeatedly reading the system clock can slow down the
+ query significantly on some systems, so it may be useful to set this
+ parameter to <code class="literal">FALSE</code> when only actual row counts, and
+ not exact times, are needed. Run time of the entire statement is
+ always measured, even when node-level timing is turned off with this
+ option.
+ This parameter may only be used when <code class="literal">ANALYZE</code> is also
+ enabled. It defaults to <code class="literal">TRUE</code>.
+ </p></dd><dt><span class="term"><code class="literal">SUMMARY</code></span></dt><dd><p>
+ Include summary information (e.g., totaled timing information) after the
+ query plan. Summary information is included by default when
+ <code class="literal">ANALYZE</code> is used but otherwise is not included by
+ default, but can be enabled using this option. Planning time in
+ <code class="command">EXPLAIN EXECUTE</code> includes the time required to fetch
+ the plan from the cache and the time required for re-planning, if
+ necessary.
+ </p></dd><dt><span class="term"><code class="literal">FORMAT</code></span></dt><dd><p>
+ Specify the output format, which can be TEXT, XML, JSON, or YAML.
+ Non-text output contains the same information as the text output
+ format, but is easier for programs to parse. This parameter defaults to
+ <code class="literal">TEXT</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>statement</code></em></span></dt><dd><p>
+ Any <code class="command">SELECT</code>, <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">MERGE</code>,
+ <code class="command">VALUES</code>, <code class="command">EXECUTE</code>,
+ <code class="command">DECLARE</code>, <code class="command">CREATE TABLE AS</code>, or
+ <code class="command">CREATE MATERIALIZED VIEW AS</code> statement, whose execution
+ plan you wish to see.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.148.9"><h2>Outputs</h2><p>
+ The command's result is a textual description of the plan selected
+ for the <em class="replaceable"><code>statement</code></em>,
+ optionally annotated with execution statistics.
+ <a class="xref" href="using-explain.html" title="14.1. Using EXPLAIN">Section 14.1</a> describes the information provided.
+ </p></div><div class="refsect1" id="id-1.9.3.148.10"><h2>Notes</h2><p>
+ In order to allow the <span class="productname">PostgreSQL</span> query
+ planner to make reasonably informed decisions when optimizing
+ queries, the <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>
+ data should be up-to-date for all tables used in the query. Normally
+ the <a class="link" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">autovacuum daemon</a> will take care
+ of that automatically. But if a table has recently had substantial
+ changes in its contents, you might need to do a manual
+ <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> rather than wait for autovacuum to catch up
+ with the changes.
+ </p><p>
+ In order to measure the run-time cost of each node in the execution
+ plan, the current implementation of <code class="command">EXPLAIN
+ ANALYZE</code> adds profiling overhead to query execution.
+ As a result, running <code class="command">EXPLAIN ANALYZE</code>
+ on a query can sometimes take significantly longer than executing
+ the query normally. The amount of overhead depends on the nature of
+ the query, as well as the platform being used. The worst case occurs
+ for plan nodes that in themselves require very little time per
+ execution, and on machines that have relatively slow operating
+ system calls for obtaining the time of day.
+ </p></div><div class="refsect1" id="id-1.9.3.148.11"><h2>Examples</h2><p>
+ To show the plan for a simple query on a table with a single
+ <code class="type">integer</code> column and 10000 rows:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM foo;
+
+ QUERY PLAN
+---------------------------------------------------------
+ Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4)
+(1 row)
+</pre><p>
+ </p><p>
+ Here is the same query, with JSON output formatting:
+</p><pre class="programlisting">
+EXPLAIN (FORMAT JSON) SELECT * FROM foo;
+ QUERY PLAN
+--------------------------------
+ [ +
+ { +
+ "Plan": { +
+ "Node Type": "Seq Scan",+
+ "Relation Name": "foo", +
+ "Alias": "foo", +
+ "Startup Cost": 0.00, +
+ "Total Cost": 155.00, +
+ "Plan Rows": 10000, +
+ "Plan Width": 4 +
+ } +
+ } +
+ ]
+(1 row)
+</pre><p>
+ </p><p>
+ If there is an index and we use a query with an indexable
+ <code class="literal">WHERE</code> condition, <code class="command">EXPLAIN</code>
+ might show a different plan:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT * FROM foo WHERE i = 4;
+
+ QUERY PLAN
+--------------------------------------------------------------
+ Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4)
+ Index Cond: (i = 4)
+(2 rows)
+</pre><p>
+ </p><p>
+ Here is the same query, but in YAML format:
+</p><pre class="programlisting">
+EXPLAIN (FORMAT YAML) SELECT * FROM foo WHERE i='4';
+ QUERY PLAN
+-------------------------------
+ - Plan: +
+ Node Type: "Index Scan" +
+ Scan Direction: "Forward"+
+ Index Name: "fi" +
+ Relation Name: "foo" +
+ Alias: "foo" +
+ Startup Cost: 0.00 +
+ Total Cost: 5.98 +
+ Plan Rows: 1 +
+ Plan Width: 4 +
+ Index Cond: "(i = 4)"
+(1 row)
+</pre><p>
+
+ XML format is left as an exercise for the reader.
+ </p><p>
+ Here is the same plan with cost estimates suppressed:
+
+</p><pre class="programlisting">
+EXPLAIN (COSTS FALSE) SELECT * FROM foo WHERE i = 4;
+
+ QUERY PLAN
+----------------------------
+ Index Scan using fi on foo
+ Index Cond: (i = 4)
+(2 rows)
+</pre><p>
+ </p><p>
+ Here is an example of a query plan for a query using an aggregate
+ function:
+
+</p><pre class="programlisting">
+EXPLAIN SELECT sum(i) FROM foo WHERE i &lt; 10;
+
+ QUERY PLAN
+-------------------------------------------------------------------​--
+ Aggregate (cost=23.93..23.93 rows=1 width=4)
+ -&gt; Index Scan using fi on foo (cost=0.00..23.92 rows=6 width=4)
+ Index Cond: (i &lt; 10)
+(3 rows)
+</pre><p>
+ </p><p>
+ Here is an example of using <code class="command">EXPLAIN EXECUTE</code> to
+ display the execution plan for a prepared query:
+
+</p><pre class="programlisting">
+PREPARE query(int, int) AS SELECT sum(bar) FROM test
+ WHERE id &gt; $1 AND id &lt; $2
+ GROUP BY foo;
+
+EXPLAIN ANALYZE EXECUTE query(100, 200);
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------------------------
+ HashAggregate (cost=9.54..9.54 rows=1 width=8) (actual time=0.156..0.161 rows=11 loops=1)
+ Group Key: foo
+ -&gt; Index Scan using test_pkey on test (cost=0.29..9.29 rows=50 width=8) (actual time=0.039..0.091 rows=99 loops=1)
+ Index Cond: ((id &gt; $1) AND (id &lt; $2))
+ Planning time: 0.197 ms
+ Execution time: 0.225 ms
+(6 rows)
+</pre><p>
+ </p><p>
+ Of course, the specific numbers shown here depend on the actual
+ contents of the tables involved. Also note that the numbers, and
+ even the selected query strategy, might vary between
+ <span class="productname">PostgreSQL</span> releases due to planner
+ improvements. In addition, the <code class="command">ANALYZE</code> command
+ uses random sampling to estimate data statistics; therefore, it is
+ possible for cost estimates to change after a fresh run of
+ <code class="command">ANALYZE</code>, even if the actual distribution of data
+ in the table has not changed.
+ </p></div><div class="refsect1" id="id-1.9.3.148.12"><h2>Compatibility</h2><p>
+ There is no <code class="command">EXPLAIN</code> statement defined in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.148.13"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-execute.html" title="EXECUTE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-fetch.html" title="FETCH">Next</a></td></tr><tr><td width="40%" align="left" valign="top">EXECUTE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> FETCH</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-expressions.html b/doc/src/sgml/html/sql-expressions.html
new file mode 100644
index 0000000..fc67755
--- /dev/null
+++ b/doc/src/sgml/html/sql-expressions.html
@@ -0,0 +1,995 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4.2. Value Expressions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-syntax-lexical.html" title="4.1. Lexical Structure" /><link rel="next" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">4.2. Value Expressions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-syntax-lexical.html" title="4.1. Lexical Structure">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><th width="60%" align="center">Chapter 4. SQL Syntax</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="SQL-EXPRESSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">4.2. Value Expressions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-COLUMN-REFS">4.2.1. Column References</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL">4.2.2. Positional Parameters</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-SUBSCRIPTS">4.2.3. Subscripts</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#FIELD-SELECTION">4.2.4. Field Selection</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-OPERATOR-CALLS">4.2.5. Operator Invocations</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-FUNCTION-CALLS">4.2.6. Function Calls</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-AGGREGATES">4.2.7. Aggregate Expressions</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS">4.2.8. Window Function Calls</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">4.2.9. Type Casts</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-COLLATE-EXPRS">4.2.10. Collation Expressions</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-SCALAR-SUBQUERIES">4.2.11. Scalar Subqueries</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS">4.2.12. Array Constructors</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS">4.2.13. Row Constructors</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-EXPRESS-EVAL">4.2.14. Expression Evaluation Rules</a></span></dt></dl></div><a id="id-1.5.3.6.2" class="indexterm"></a><a id="id-1.5.3.6.3" class="indexterm"></a><a id="id-1.5.3.6.4" class="indexterm"></a><p>
+ Value expressions are used in a variety of contexts, such
+ as in the target list of the <code class="command">SELECT</code> command, as
+ new column values in <code class="command">INSERT</code> or
+ <code class="command">UPDATE</code>, or in search conditions in a number of
+ commands. The result of a value expression is sometimes called a
+ <em class="firstterm">scalar</em>, to distinguish it from the result of
+ a table expression (which is a table). Value expressions are
+ therefore also called <em class="firstterm">scalar expressions</em> (or
+ even simply <em class="firstterm">expressions</em>). The expression
+ syntax allows the calculation of values from primitive parts using
+ arithmetic, logical, set, and other operations.
+ </p><p>
+ A value expression is one of the following:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A constant or literal value
+ </p></li><li class="listitem"><p>
+ A column reference
+ </p></li><li class="listitem"><p>
+ A positional parameter reference, in the body of a function definition
+ or prepared statement
+ </p></li><li class="listitem"><p>
+ A subscripted expression
+ </p></li><li class="listitem"><p>
+ A field selection expression
+ </p></li><li class="listitem"><p>
+ An operator invocation
+ </p></li><li class="listitem"><p>
+ A function call
+ </p></li><li class="listitem"><p>
+ An aggregate expression
+ </p></li><li class="listitem"><p>
+ A window function call
+ </p></li><li class="listitem"><p>
+ A type cast
+ </p></li><li class="listitem"><p>
+ A collation expression
+ </p></li><li class="listitem"><p>
+ A scalar subquery
+ </p></li><li class="listitem"><p>
+ An array constructor
+ </p></li><li class="listitem"><p>
+ A row constructor
+ </p></li><li class="listitem"><p>
+ Another value expression in parentheses (used to group
+ subexpressions and override
+ precedence<a id="id-1.5.3.6.6.1.15.1.1" class="indexterm"></a>)
+ </p></li></ul></div><p>
+ </p><p>
+ In addition to this list, there are a number of constructs that can
+ be classified as an expression but do not follow any general syntax
+ rules. These generally have the semantics of a function or
+ operator and are explained in the appropriate location in <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>. An example is the <code class="literal">IS NULL</code>
+ clause.
+ </p><p>
+ We have already discussed constants in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS" title="4.1.2. Constants">Section 4.1.2</a>. The following sections discuss
+ the remaining options.
+ </p><div class="sect2" id="SQL-EXPRESSIONS-COLUMN-REFS"><div class="titlepage"><div><div><h3 class="title">4.2.1. Column References</h3></div></div></div><a id="id-1.5.3.6.9.2" class="indexterm"></a><p>
+ A column can be referenced in the form:
+</p><pre class="synopsis">
+<em class="replaceable"><code>correlation</code></em>.<em class="replaceable"><code>columnname</code></em>
+</pre><p>
+ </p><p>
+ <em class="replaceable"><code>correlation</code></em> is the name of a
+ table (possibly qualified with a schema name), or an alias for a table
+ defined by means of a <code class="literal">FROM</code> clause.
+ The correlation name and separating dot can be omitted if the column name
+ is unique across all the tables being used in the current query. (See also <a class="xref" href="queries.html" title="Chapter 7. Queries">Chapter 7</a>.)
+ </p></div><div class="sect2" id="SQL-EXPRESSIONS-PARAMETERS-POSITIONAL"><div class="titlepage"><div><div><h3 class="title">4.2.2. Positional Parameters</h3></div></div></div><a id="id-1.5.3.6.10.2" class="indexterm"></a><a id="id-1.5.3.6.10.3" class="indexterm"></a><p>
+ A positional parameter reference is used to indicate a value
+ that is supplied externally to an SQL statement. Parameters are
+ used in SQL function definitions and in prepared queries. Some
+ client libraries also support specifying data values separately
+ from the SQL command string, in which case parameters are used to
+ refer to the out-of-line data values.
+ The form of a parameter reference is:
+</p><pre class="synopsis">
+$<em class="replaceable"><code>number</code></em>
+</pre><p>
+ </p><p>
+ For example, consider the definition of a function,
+ <code class="function">dept</code>, as:
+
+</p><pre class="programlisting">
+CREATE FUNCTION dept(text) RETURNS dept
+ AS $$ SELECT * FROM dept WHERE name = $1 $$
+ LANGUAGE SQL;
+</pre><p>
+
+ Here the <code class="literal">$1</code> references the value of the first
+ function argument whenever the function is invoked.
+ </p></div><div class="sect2" id="SQL-EXPRESSIONS-SUBSCRIPTS"><div class="titlepage"><div><div><h3 class="title">4.2.3. Subscripts</h3></div></div></div><a id="id-1.5.3.6.11.2" class="indexterm"></a><p>
+ If an expression yields a value of an array type, then a specific
+ element of the array value can be extracted by writing
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em>[<em class="replaceable"><code>subscript</code></em>]
+</pre><p>
+ or multiple adjacent elements (an <span class="quote">“<span class="quote">array slice</span>”</span>) can be extracted
+ by writing
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em>[<em class="replaceable"><code>lower_subscript</code></em>:<em class="replaceable"><code>upper_subscript</code></em>]
+</pre><p>
+ (Here, the brackets <code class="literal">[ ]</code> are meant to appear literally.)
+ Each <em class="replaceable"><code>subscript</code></em> is itself an expression,
+ which will be rounded to the nearest integer value.
+ </p><p>
+ In general the array <em class="replaceable"><code>expression</code></em> must be
+ parenthesized, but the parentheses can be omitted when the expression
+ to be subscripted is just a column reference or positional parameter.
+ Also, multiple subscripts can be concatenated when the original array
+ is multidimensional.
+ For example:
+
+</p><pre class="programlisting">
+mytable.arraycolumn[4]
+mytable.two_d_column[17][34]
+$1[10:42]
+(arrayfunction(a,b))[42]
+</pre><p>
+
+ The parentheses in the last example are required.
+ See <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a> for more about arrays.
+ </p></div><div class="sect2" id="FIELD-SELECTION"><div class="titlepage"><div><div><h3 class="title">4.2.4. Field Selection</h3></div></div></div><a id="id-1.5.3.6.12.2" class="indexterm"></a><p>
+ If an expression yields a value of a composite type (row type), then a
+ specific field of the row can be extracted by writing
+</p><pre class="synopsis">
+<em class="replaceable"><code>expression</code></em>.<em class="replaceable"><code>fieldname</code></em>
+</pre><p>
+ </p><p>
+ In general the row <em class="replaceable"><code>expression</code></em> must be
+ parenthesized, but the parentheses can be omitted when the expression
+ to be selected from is just a table reference or positional parameter.
+ For example:
+
+</p><pre class="programlisting">
+mytable.mycolumn
+$1.somecolumn
+(rowfunction(a,b)).col3
+</pre><p>
+
+ (Thus, a qualified column reference is actually just a special case
+ of the field selection syntax.) An important special case is
+ extracting a field from a table column that is of a composite type:
+
+</p><pre class="programlisting">
+(compositecol).somefield
+(mytable.compositecol).somefield
+</pre><p>
+
+ The parentheses are required here to show that
+ <code class="structfield">compositecol</code> is a column name not a table name,
+ or that <code class="structname">mytable</code> is a table name not a schema name
+ in the second case.
+ </p><p>
+ You can ask for all fields of a composite value by
+ writing <code class="literal">.*</code>:
+</p><pre class="programlisting">
+(compositecol).*
+</pre><p>
+ This notation behaves differently depending on context;
+ see <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a> for details.
+ </p></div><div class="sect2" id="SQL-EXPRESSIONS-OPERATOR-CALLS"><div class="titlepage"><div><div><h3 class="title">4.2.5. Operator Invocations</h3></div></div></div><a id="id-1.5.3.6.13.2" class="indexterm"></a><p>
+ There are two possible syntaxes for an operator invocation:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><em class="replaceable"><code>expression</code></em> <em class="replaceable"><code>operator</code></em> <em class="replaceable"><code>expression</code></em> (binary infix operator)</td></tr><tr><td><em class="replaceable"><code>operator</code></em> <em class="replaceable"><code>expression</code></em> (unary prefix operator)</td></tr></table><p>
+ where the <em class="replaceable"><code>operator</code></em> token follows the syntax
+ rules of <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-OPERATORS" title="4.1.3. Operators">Section 4.1.3</a>, or is one of the
+ key words <code class="token">AND</code>, <code class="token">OR</code>, and
+ <code class="token">NOT</code>, or is a qualified operator name in the form:
+</p><pre class="synopsis">
+<code class="literal">OPERATOR(</code><em class="replaceable"><code>schema</code></em><code class="literal">.</code><em class="replaceable"><code>operatorname</code></em><code class="literal">)</code>
+</pre><p>
+ Which particular operators exist and whether
+ they are unary or binary depends on what operators have been
+ defined by the system or the user. <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>
+ describes the built-in operators.
+ </p></div><div class="sect2" id="SQL-EXPRESSIONS-FUNCTION-CALLS"><div class="titlepage"><div><div><h3 class="title">4.2.6. Function Calls</h3></div></div></div><a id="id-1.5.3.6.14.2" class="indexterm"></a><p>
+ The syntax for a function call is the name of a function
+ (possibly qualified with a schema name), followed by its argument list
+ enclosed in parentheses:
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>function_name</code></em> ([<span class="optional"><em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> ... </span>]</span>] )
+</pre><p>
+ </p><p>
+ For example, the following computes the square root of 2:
+</p><pre class="programlisting">
+sqrt(2)
+</pre><p>
+ </p><p>
+ The list of built-in functions is in <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>.
+ Other functions can be added by the user.
+ </p><p>
+ When issuing queries in a database where some users mistrust other users,
+ observe security precautions from <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a> when
+ writing function calls.
+ </p><p>
+ The arguments can optionally have names attached.
+ See <a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a> for details.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ A function that takes a single argument of composite type can
+ optionally be called using field-selection syntax, and conversely
+ field selection can be written in functional style. That is, the
+ notations <code class="literal">col(table)</code> and <code class="literal">table.col</code> are
+ interchangeable. This behavior is not SQL-standard but is provided
+ in <span class="productname">PostgreSQL</span> because it allows use of functions to
+ emulate <span class="quote">“<span class="quote">computed fields</span>”</span>. For more information see
+ <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a>.
+ </p></div></div><div class="sect2" id="SYNTAX-AGGREGATES"><div class="titlepage"><div><div><h3 class="title">4.2.7. Aggregate Expressions</h3></div></div></div><a id="id-1.5.3.6.15.2" class="indexterm"></a><a id="id-1.5.3.6.15.3" class="indexterm"></a><a id="id-1.5.3.6.15.4" class="indexterm"></a><a id="id-1.5.3.6.15.5" class="indexterm"></a><p>
+ An <em class="firstterm">aggregate expression</em> represents the
+ application of an aggregate function across the rows selected by a
+ query. An aggregate function reduces multiple inputs to a single
+ output value, such as the sum or average of the inputs. The
+ syntax of an aggregate expression is one of the following:
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>aggregate_name</code></em> (<em class="replaceable"><code>expression</code></em> [ , ... ] [ <em class="replaceable"><code>order_by_clause</code></em> ] ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ]
+<em class="replaceable"><code>aggregate_name</code></em> (ALL <em class="replaceable"><code>expression</code></em> [ , ... ] [ <em class="replaceable"><code>order_by_clause</code></em> ] ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ]
+<em class="replaceable"><code>aggregate_name</code></em> (DISTINCT <em class="replaceable"><code>expression</code></em> [ , ... ] [ <em class="replaceable"><code>order_by_clause</code></em> ] ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ]
+<em class="replaceable"><code>aggregate_name</code></em> ( * ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ]
+<em class="replaceable"><code>aggregate_name</code></em> ( [ <em class="replaceable"><code>expression</code></em> [ , ... ] ] ) WITHIN GROUP ( <em class="replaceable"><code>order_by_clause</code></em> ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ]
+</pre><p>
+
+ where <em class="replaceable"><code>aggregate_name</code></em> is a previously
+ defined aggregate (possibly qualified with a schema name) and
+ <em class="replaceable"><code>expression</code></em> is
+ any value expression that does not itself contain an aggregate
+ expression or a window function call. The optional
+ <em class="replaceable"><code>order_by_clause</code></em> and
+ <em class="replaceable"><code>filter_clause</code></em> are described below.
+ </p><p>
+ The first form of aggregate expression invokes the aggregate
+ once for each input row.
+ The second form is the same as the first, since
+ <code class="literal">ALL</code> is the default.
+ The third form invokes the aggregate once for each distinct value
+ of the expression (or distinct set of values, for multiple expressions)
+ found in the input rows.
+ The fourth form invokes the aggregate once for each input row; since no
+ particular input value is specified, it is generally only useful
+ for the <code class="function">count(*)</code> aggregate function.
+ The last form is used with <em class="firstterm">ordered-set</em> aggregate
+ functions, which are described below.
+ </p><p>
+ Most aggregate functions ignore null inputs, so that rows in which
+ one or more of the expression(s) yield null are discarded. This
+ can be assumed to be true, unless otherwise specified, for all
+ built-in aggregates.
+ </p><p>
+ For example, <code class="literal">count(*)</code> yields the total number
+ of input rows; <code class="literal">count(f1)</code> yields the number of
+ input rows in which <code class="literal">f1</code> is non-null, since
+ <code class="function">count</code> ignores nulls; and
+ <code class="literal">count(distinct f1)</code> yields the number of
+ distinct non-null values of <code class="literal">f1</code>.
+ </p><p>
+ Ordinarily, the input rows are fed to the aggregate function in an
+ unspecified order. In many cases this does not matter; for example,
+ <code class="function">min</code> produces the same result no matter what order it
+ receives the inputs in. However, some aggregate functions
+ (such as <code class="function">array_agg</code> and <code class="function">string_agg</code>) produce
+ results that depend on the ordering of the input rows. When using
+ such an aggregate, the optional <em class="replaceable"><code>order_by_clause</code></em> can be
+ used to specify the desired ordering. The <em class="replaceable"><code>order_by_clause</code></em>
+ has the same syntax as for a query-level <code class="literal">ORDER BY</code> clause, as
+ described in <a class="xref" href="queries-order.html" title="7.5. Sorting Rows (ORDER BY)">Section 7.5</a>, except that its expressions
+ are always just expressions and cannot be output-column names or numbers.
+ For example:
+</p><pre class="programlisting">
+SELECT array_agg(a ORDER BY b DESC) FROM table;
+</pre><p>
+ </p><p>
+ When dealing with multiple-argument aggregate functions, note that the
+ <code class="literal">ORDER BY</code> clause goes after all the aggregate arguments.
+ For example, write this:
+</p><pre class="programlisting">
+SELECT string_agg(a, ',' ORDER BY a) FROM table;
+</pre><p>
+ not this:
+</p><pre class="programlisting">
+SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect
+</pre><p>
+ The latter is syntactically valid, but it represents a call of a
+ single-argument aggregate function with two <code class="literal">ORDER BY</code> keys
+ (the second one being rather useless since it's a constant).
+ </p><p>
+ If <code class="literal">DISTINCT</code> is specified in addition to an
+ <em class="replaceable"><code>order_by_clause</code></em>, then all the <code class="literal">ORDER BY</code>
+ expressions must match regular arguments of the aggregate; that is,
+ you cannot sort on an expression that is not included in the
+ <code class="literal">DISTINCT</code> list.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The ability to specify both <code class="literal">DISTINCT</code> and <code class="literal">ORDER BY</code>
+ in an aggregate function is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><p>
+ Placing <code class="literal">ORDER BY</code> within the aggregate's regular argument
+ list, as described so far, is used when ordering the input rows for
+ general-purpose and statistical aggregates, for which ordering is
+ optional. There is a
+ subclass of aggregate functions called <em class="firstterm">ordered-set
+ aggregates</em> for which an <em class="replaceable"><code>order_by_clause</code></em>
+ is <span class="emphasis"><em>required</em></span>, usually because the aggregate's computation is
+ only sensible in terms of a specific ordering of its input rows.
+ Typical examples of ordered-set aggregates include rank and percentile
+ calculations. For an ordered-set aggregate,
+ the <em class="replaceable"><code>order_by_clause</code></em> is written
+ inside <code class="literal">WITHIN GROUP (...)</code>, as shown in the final syntax
+ alternative above. The expressions in
+ the <em class="replaceable"><code>order_by_clause</code></em> are evaluated once per
+ input row just like regular aggregate arguments, sorted as per
+ the <em class="replaceable"><code>order_by_clause</code></em>'s requirements, and fed
+ to the aggregate function as input arguments. (This is unlike the case
+ for a non-<code class="literal">WITHIN GROUP</code> <em class="replaceable"><code>order_by_clause</code></em>,
+ which is not treated as argument(s) to the aggregate function.) The
+ argument expressions preceding <code class="literal">WITHIN GROUP</code>, if any, are
+ called <em class="firstterm">direct arguments</em> to distinguish them from
+ the <em class="firstterm">aggregated arguments</em> listed in
+ the <em class="replaceable"><code>order_by_clause</code></em>. Unlike regular aggregate
+ arguments, direct arguments are evaluated only once per aggregate call,
+ not once per input row. This means that they can contain variables only
+ if those variables are grouped by <code class="literal">GROUP BY</code>; this restriction
+ is the same as if the direct arguments were not inside an aggregate
+ expression at all. Direct arguments are typically used for things like
+ percentile fractions, which only make sense as a single value per
+ aggregation calculation. The direct argument list can be empty; in this
+ case, write just <code class="literal">()</code> not <code class="literal">(*)</code>.
+ (<span class="productname">PostgreSQL</span> will actually accept either spelling, but
+ only the first way conforms to the SQL standard.)
+ </p><p>
+ <a id="id-1.5.3.6.15.15.1" class="indexterm"></a>
+ An example of an ordered-set aggregate call is:
+
+</p><pre class="programlisting">
+SELECT percentile_cont(0.5) WITHIN GROUP (ORDER BY income) FROM households;
+ percentile_cont
+-----------------
+ 50489
+</pre><p>
+
+ which obtains the 50th percentile, or median, value of
+ the <code class="structfield">income</code> column from table <code class="structname">households</code>.
+ Here, <code class="literal">0.5</code> is a direct argument; it would make no sense
+ for the percentile fraction to be a value varying across rows.
+ </p><p>
+ If <code class="literal">FILTER</code> is specified, then only the input
+ rows for which the <em class="replaceable"><code>filter_clause</code></em>
+ evaluates to true are fed to the aggregate function; other rows
+ are discarded. For example:
+</p><pre class="programlisting">
+SELECT
+ count(*) AS unfiltered,
+ count(*) FILTER (WHERE i &lt; 5) AS filtered
+FROM generate_series(1,10) AS s(i);
+ unfiltered | filtered
+------------+----------
+ 10 | 4
+(1 row)
+</pre><p>
+ </p><p>
+ The predefined aggregate functions are described in <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a>. Other aggregate functions can be added
+ by the user.
+ </p><p>
+ An aggregate expression can only appear in the result list or
+ <code class="literal">HAVING</code> clause of a <code class="command">SELECT</code> command.
+ It is forbidden in other clauses, such as <code class="literal">WHERE</code>,
+ because those clauses are logically evaluated before the results
+ of aggregates are formed.
+ </p><p>
+ When an aggregate expression appears in a subquery (see
+ <a class="xref" href="sql-expressions.html#SQL-SYNTAX-SCALAR-SUBQUERIES" title="4.2.11. Scalar Subqueries">Section 4.2.11</a> and
+ <a class="xref" href="functions-subquery.html" title="9.23. Subquery Expressions">Section 9.23</a>), the aggregate is normally
+ evaluated over the rows of the subquery. But an exception occurs
+ if the aggregate's arguments (and <em class="replaceable"><code>filter_clause</code></em>
+ if any) contain only outer-level variables:
+ the aggregate then belongs to the nearest such outer level, and is
+ evaluated over the rows of that query. The aggregate expression
+ as a whole is then an outer reference for the subquery it appears in,
+ and acts as a constant over any one evaluation of that subquery.
+ The restriction about
+ appearing only in the result list or <code class="literal">HAVING</code> clause
+ applies with respect to the query level that the aggregate belongs to.
+ </p></div><div class="sect2" id="SYNTAX-WINDOW-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">4.2.8. Window Function Calls</h3></div></div></div><a id="id-1.5.3.6.16.2" class="indexterm"></a><a id="id-1.5.3.6.16.3" class="indexterm"></a><p>
+ A <em class="firstterm">window function call</em> represents the application
+ of an aggregate-like function over some portion of the rows selected
+ by a query. Unlike non-window aggregate calls, this is not tied
+ to grouping of the selected rows into a single output row — each
+ row remains separate in the query output. However the window function
+ has access to all the rows that would be part of the current row's
+ group according to the grouping specification (<code class="literal">PARTITION BY</code>
+ list) of the window function call.
+ The syntax of a window function call is one of the following:
+
+</p><pre class="synopsis">
+<em class="replaceable"><code>function_name</code></em> ([<span class="optional"><em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> ... </span>]</span>]) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ] OVER <em class="replaceable"><code>window_name</code></em>
+<em class="replaceable"><code>function_name</code></em> ([<span class="optional"><em class="replaceable"><code>expression</code></em> [<span class="optional">, <em class="replaceable"><code>expression</code></em> ... </span>]</span>]) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ] OVER ( <em class="replaceable"><code>window_definition</code></em> )
+<em class="replaceable"><code>function_name</code></em> ( * ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ] OVER <em class="replaceable"><code>window_name</code></em>
+<em class="replaceable"><code>function_name</code></em> ( * ) [ FILTER ( WHERE <em class="replaceable"><code>filter_clause</code></em> ) ] OVER ( <em class="replaceable"><code>window_definition</code></em> )
+</pre><p>
+ where <em class="replaceable"><code>window_definition</code></em>
+ has the syntax
+</p><pre class="synopsis">
+[ <em class="replaceable"><code>existing_window_name</code></em> ]
+[ PARTITION BY <em class="replaceable"><code>expression</code></em> [, ...] ]
+[ ORDER BY <em class="replaceable"><code>expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [ NULLS { FIRST | LAST } ] [, ...] ]
+[ <em class="replaceable"><code>frame_clause</code></em> ]
+</pre><p>
+ The optional <em class="replaceable"><code>frame_clause</code></em>
+ can be one of
+</p><pre class="synopsis">
+{ RANGE | ROWS | GROUPS } <em class="replaceable"><code>frame_start</code></em> [ <em class="replaceable"><code>frame_exclusion</code></em> ]
+{ RANGE | ROWS | GROUPS } BETWEEN <em class="replaceable"><code>frame_start</code></em> AND <em class="replaceable"><code>frame_end</code></em> [ <em class="replaceable"><code>frame_exclusion</code></em> ]
+</pre><p>
+ where <em class="replaceable"><code>frame_start</code></em>
+ and <em class="replaceable"><code>frame_end</code></em> can be one of
+</p><pre class="synopsis">
+UNBOUNDED PRECEDING
+<em class="replaceable"><code>offset</code></em> PRECEDING
+CURRENT ROW
+<em class="replaceable"><code>offset</code></em> FOLLOWING
+UNBOUNDED FOLLOWING
+</pre><p>
+ and <em class="replaceable"><code>frame_exclusion</code></em> can be one of
+</p><pre class="synopsis">
+EXCLUDE CURRENT ROW
+EXCLUDE GROUP
+EXCLUDE TIES
+EXCLUDE NO OTHERS
+</pre><p>
+ </p><p>
+ Here, <em class="replaceable"><code>expression</code></em> represents any value
+ expression that does not itself contain window function calls.
+ </p><p>
+ <em class="replaceable"><code>window_name</code></em> is a reference to a named window
+ specification defined in the query's <code class="literal">WINDOW</code> clause.
+ Alternatively, a full <em class="replaceable"><code>window_definition</code></em> can
+ be given within parentheses, using the same syntax as for defining a
+ named window in the <code class="literal">WINDOW</code> clause; see the
+ <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> reference page for details. It's worth
+ pointing out that <code class="literal">OVER wname</code> is not exactly equivalent to
+ <code class="literal">OVER (wname ...)</code>; the latter implies copying and modifying the
+ window definition, and will be rejected if the referenced window
+ specification includes a frame clause.
+ </p><p>
+ The <code class="literal">PARTITION BY</code> clause groups the rows of the query into
+ <em class="firstterm">partitions</em>, which are processed separately by the window
+ function. <code class="literal">PARTITION BY</code> works similarly to a query-level
+ <code class="literal">GROUP BY</code> clause, except that its expressions are always just
+ expressions and cannot be output-column names or numbers.
+ Without <code class="literal">PARTITION BY</code>, all rows produced by the query are
+ treated as a single partition.
+ The <code class="literal">ORDER BY</code> clause determines the order in which the rows
+ of a partition are processed by the window function. It works similarly
+ to a query-level <code class="literal">ORDER BY</code> clause, but likewise cannot use
+ output-column names or numbers. Without <code class="literal">ORDER BY</code>, rows are
+ processed in an unspecified order.
+ </p><p>
+ The <em class="replaceable"><code>frame_clause</code></em> specifies
+ the set of rows constituting the <em class="firstterm">window frame</em>, which is a
+ subset of the current partition, for those window functions that act on
+ the frame instead of the whole partition. The set of rows in the frame
+ can vary depending on which row is the current row. The frame can be
+ specified in <code class="literal">RANGE</code>, <code class="literal">ROWS</code>
+ or <code class="literal">GROUPS</code> mode; in each case, it runs from
+ the <em class="replaceable"><code>frame_start</code></em> to
+ the <em class="replaceable"><code>frame_end</code></em>.
+ If <em class="replaceable"><code>frame_end</code></em> is omitted, the end defaults
+ to <code class="literal">CURRENT ROW</code>.
+ </p><p>
+ A <em class="replaceable"><code>frame_start</code></em> of <code class="literal">UNBOUNDED PRECEDING</code> means
+ that the frame starts with the first row of the partition, and similarly
+ a <em class="replaceable"><code>frame_end</code></em> of <code class="literal">UNBOUNDED FOLLOWING</code> means
+ that the frame ends with the last row of the partition.
+ </p><p>
+ In <code class="literal">RANGE</code> or <code class="literal">GROUPS</code> mode,
+ a <em class="replaceable"><code>frame_start</code></em> of
+ <code class="literal">CURRENT ROW</code> means the frame starts with the current
+ row's first <em class="firstterm">peer</em> row (a row that the
+ window's <code class="literal">ORDER BY</code> clause sorts as equivalent to the
+ current row), while a <em class="replaceable"><code>frame_end</code></em> of
+ <code class="literal">CURRENT ROW</code> means the frame ends with the current
+ row's last peer row.
+ In <code class="literal">ROWS</code> mode, <code class="literal">CURRENT ROW</code> simply
+ means the current row.
+ </p><p>
+ In the <em class="replaceable"><code>offset</code></em> <code class="literal">PRECEDING</code>
+ and <em class="replaceable"><code>offset</code></em> <code class="literal">FOLLOWING</code> frame
+ options, the <em class="replaceable"><code>offset</code></em> must be an expression not
+ containing any variables, aggregate functions, or window functions.
+ The meaning of the <em class="replaceable"><code>offset</code></em> depends on the
+ frame mode:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ In <code class="literal">ROWS</code> mode,
+ the <em class="replaceable"><code>offset</code></em> must yield a non-null,
+ non-negative integer, and the option means that the frame starts or
+ ends the specified number of rows before or after the current row.
+ </p></li><li class="listitem"><p>
+ In <code class="literal">GROUPS</code> mode,
+ the <em class="replaceable"><code>offset</code></em> again must yield a non-null,
+ non-negative integer, and the option means that the frame starts or
+ ends the specified number of <em class="firstterm">peer groups</em>
+ before or after the current row's peer group, where a peer group is a
+ set of rows that are equivalent in the <code class="literal">ORDER BY</code>
+ ordering. (There must be an <code class="literal">ORDER BY</code> clause
+ in the window definition to use <code class="literal">GROUPS</code> mode.)
+ </p></li><li class="listitem"><p>
+ In <code class="literal">RANGE</code> mode, these options require that
+ the <code class="literal">ORDER BY</code> clause specify exactly one column.
+ The <em class="replaceable"><code>offset</code></em> specifies the maximum
+ difference between the value of that column in the current row and
+ its value in preceding or following rows of the frame. The data type
+ of the <em class="replaceable"><code>offset</code></em> expression varies depending
+ on the data type of the ordering column. For numeric ordering
+ columns it is typically of the same type as the ordering column,
+ but for datetime ordering columns it is an <code class="type">interval</code>.
+ For example, if the ordering column is of type <code class="type">date</code>
+ or <code class="type">timestamp</code>, one could write <code class="literal">RANGE BETWEEN
+ '1 day' PRECEDING AND '10 days' FOLLOWING</code>.
+ The <em class="replaceable"><code>offset</code></em> is still required to be
+ non-null and non-negative, though the meaning
+ of <span class="quote">“<span class="quote">non-negative</span>”</span> depends on its data type.
+ </p></li></ul></div><p>
+ In any case, the distance to the end of the frame is limited by the
+ distance to the end of the partition, so that for rows near the partition
+ ends the frame might contain fewer rows than elsewhere.
+ </p><p>
+ Notice that in both <code class="literal">ROWS</code> and <code class="literal">GROUPS</code>
+ mode, <code class="literal">0 PRECEDING</code> and <code class="literal">0 FOLLOWING</code>
+ are equivalent to <code class="literal">CURRENT ROW</code>. This normally holds
+ in <code class="literal">RANGE</code> mode as well, for an appropriate
+ data-type-specific meaning of <span class="quote">“<span class="quote">zero</span>”</span>.
+ </p><p>
+ The <em class="replaceable"><code>frame_exclusion</code></em> option allows rows around
+ the current row to be excluded from the frame, even if they would be
+ included according to the frame start and frame end options.
+ <code class="literal">EXCLUDE CURRENT ROW</code> excludes the current row from the
+ frame.
+ <code class="literal">EXCLUDE GROUP</code> excludes the current row and its
+ ordering peers from the frame.
+ <code class="literal">EXCLUDE TIES</code> excludes any peers of the current
+ row from the frame, but not the current row itself.
+ <code class="literal">EXCLUDE NO OTHERS</code> simply specifies explicitly the
+ default behavior of not excluding the current row or its peers.
+ </p><p>
+ The default framing option is <code class="literal">RANGE UNBOUNDED PRECEDING</code>,
+ which is the same as <code class="literal">RANGE BETWEEN UNBOUNDED PRECEDING AND
+ CURRENT ROW</code>. With <code class="literal">ORDER BY</code>, this sets the frame to be
+ all rows from the partition start up through the current row's last
+ <code class="literal">ORDER BY</code> peer. Without <code class="literal">ORDER BY</code>,
+ this means all rows of the partition are included in the window frame,
+ since all rows become peers of the current row.
+ </p><p>
+ Restrictions are that
+ <em class="replaceable"><code>frame_start</code></em> cannot be <code class="literal">UNBOUNDED FOLLOWING</code>,
+ <em class="replaceable"><code>frame_end</code></em> cannot be <code class="literal">UNBOUNDED PRECEDING</code>,
+ and the <em class="replaceable"><code>frame_end</code></em> choice cannot appear earlier in the
+ above list of <em class="replaceable"><code>frame_start</code></em>
+ and <em class="replaceable"><code>frame_end</code></em> options than
+ the <em class="replaceable"><code>frame_start</code></em> choice does — for example
+ <code class="literal">RANGE BETWEEN CURRENT ROW AND <em class="replaceable"><code>offset</code></em>
+ PRECEDING</code> is not allowed.
+ But, for example, <code class="literal">ROWS BETWEEN 7 PRECEDING AND 8
+ PRECEDING</code> is allowed, even though it would never select any
+ rows.
+ </p><p>
+ If <code class="literal">FILTER</code> is specified, then only the input
+ rows for which the <em class="replaceable"><code>filter_clause</code></em>
+ evaluates to true are fed to the window function; other rows
+ are discarded. Only window functions that are aggregates accept
+ a <code class="literal">FILTER</code> clause.
+ </p><p>
+ The built-in window functions are described in <a class="xref" href="functions-window.html#FUNCTIONS-WINDOW-TABLE" title="Table 9.63. General-Purpose Window Functions">Table 9.63</a>. Other window functions can be added by
+ the user. Also, any built-in or user-defined general-purpose or
+ statistical aggregate can be used as a window function. (Ordered-set
+ and hypothetical-set aggregates cannot presently be used as window functions.)
+ </p><p>
+ The syntaxes using <code class="literal">*</code> are used for calling parameter-less
+ aggregate functions as window functions, for example
+ <code class="literal">count(*) OVER (PARTITION BY x ORDER BY y)</code>.
+ The asterisk (<code class="literal">*</code>) is customarily not used for
+ window-specific functions. Window-specific functions do not
+ allow <code class="literal">DISTINCT</code> or <code class="literal">ORDER BY</code> to be used within the
+ function argument list.
+ </p><p>
+ Window function calls are permitted only in the <code class="literal">SELECT</code>
+ list and the <code class="literal">ORDER BY</code> clause of the query.
+ </p><p>
+ More information about window functions can be found in
+ <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a>,
+ <a class="xref" href="functions-window.html" title="9.22. Window Functions">Section 9.22</a>, and
+ <a class="xref" href="queries-table-expressions.html#QUERIES-WINDOW" title="7.2.5. Window Function Processing">Section 7.2.5</a>.
+ </p></div><div class="sect2" id="SQL-SYNTAX-TYPE-CASTS"><div class="titlepage"><div><div><h3 class="title">4.2.9. Type Casts</h3></div></div></div><a id="id-1.5.3.6.17.2" class="indexterm"></a><a id="id-1.5.3.6.17.3" class="indexterm"></a><a id="id-1.5.3.6.17.4" class="indexterm"></a><p>
+ A type cast specifies a conversion from one data type to another.
+ <span class="productname">PostgreSQL</span> accepts two equivalent syntaxes
+ for type casts:
+</p><pre class="synopsis">
+CAST ( <em class="replaceable"><code>expression</code></em> AS <em class="replaceable"><code>type</code></em> )
+<em class="replaceable"><code>expression</code></em>::<em class="replaceable"><code>type</code></em>
+</pre><p>
+ The <code class="literal">CAST</code> syntax conforms to SQL; the syntax with
+ <code class="literal">::</code> is historical <span class="productname">PostgreSQL</span>
+ usage.
+ </p><p>
+ When a cast is applied to a value expression of a known type, it
+ represents a run-time type conversion. The cast will succeed only
+ if a suitable type conversion operation has been defined. Notice that this
+ is subtly different from the use of casts with constants, as shown in
+ <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS-GENERIC" title="4.1.2.7. Constants of Other Types">Section 4.1.2.7</a>. A cast applied to an
+ unadorned string literal represents the initial assignment of a type
+ to a literal constant value, and so it will succeed for any type
+ (if the contents of the string literal are acceptable input syntax for the
+ data type).
+ </p><p>
+ An explicit type cast can usually be omitted if there is no ambiguity as
+ to the type that a value expression must produce (for example, when it is
+ assigned to a table column); the system will automatically apply a
+ type cast in such cases. However, automatic casting is only done for
+ casts that are marked <span class="quote">“<span class="quote">OK to apply implicitly</span>”</span>
+ in the system catalogs. Other casts must be invoked with
+ explicit casting syntax. This restriction is intended to prevent
+ surprising conversions from being applied silently.
+ </p><p>
+ It is also possible to specify a type cast using a function-like
+ syntax:
+</p><pre class="synopsis">
+<em class="replaceable"><code>typename</code></em> ( <em class="replaceable"><code>expression</code></em> )
+</pre><p>
+ However, this only works for types whose names are also valid as
+ function names. For example, <code class="literal">double precision</code>
+ cannot be used this way, but the equivalent <code class="literal">float8</code>
+ can. Also, the names <code class="literal">interval</code>, <code class="literal">time</code>, and
+ <code class="literal">timestamp</code> can only be used in this fashion if they are
+ double-quoted, because of syntactic conflicts. Therefore, the use of
+ the function-like cast syntax leads to inconsistencies and should
+ probably be avoided.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The function-like syntax is in fact just a function call. When
+ one of the two standard cast syntaxes is used to do a run-time
+ conversion, it will internally invoke a registered function to
+ perform the conversion. By convention, these conversion functions
+ have the same name as their output type, and thus the <span class="quote">“<span class="quote">function-like
+ syntax</span>”</span> is nothing more than a direct invocation of the underlying
+ conversion function. Obviously, this is not something that a portable
+ application should rely on. For further details see
+ <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>.
+ </p></div></div><div class="sect2" id="SQL-SYNTAX-COLLATE-EXPRS"><div class="titlepage"><div><div><h3 class="title">4.2.10. Collation Expressions</h3></div></div></div><a id="id-1.5.3.6.18.2" class="indexterm"></a><p>
+ The <code class="literal">COLLATE</code> clause overrides the collation of
+ an expression. It is appended to the expression it applies to:
+</p><pre class="synopsis">
+<em class="replaceable"><code>expr</code></em> COLLATE <em class="replaceable"><code>collation</code></em>
+</pre><p>
+ where <em class="replaceable"><code>collation</code></em> is a possibly
+ schema-qualified identifier. The <code class="literal">COLLATE</code>
+ clause binds tighter than operators; parentheses can be used when
+ necessary.
+ </p><p>
+ If no collation is explicitly specified, the database system
+ either derives a collation from the columns involved in the
+ expression, or it defaults to the default collation of the
+ database if no column is involved in the expression.
+ </p><p>
+ The two common uses of the <code class="literal">COLLATE</code> clause are
+ overriding the sort order in an <code class="literal">ORDER BY</code> clause, for
+ example:
+</p><pre class="programlisting">
+SELECT a, b, c FROM tbl WHERE ... ORDER BY a COLLATE "C";
+</pre><p>
+ and overriding the collation of a function or operator call that
+ has locale-sensitive results, for example:
+</p><pre class="programlisting">
+SELECT * FROM tbl WHERE a &gt; 'foo' COLLATE "C";
+</pre><p>
+ Note that in the latter case the <code class="literal">COLLATE</code> clause is
+ attached to an input argument of the operator we wish to affect.
+ It doesn't matter which argument of the operator or function call the
+ <code class="literal">COLLATE</code> clause is attached to, because the collation that is
+ applied by the operator or function is derived by considering all
+ arguments, and an explicit <code class="literal">COLLATE</code> clause will override the
+ collations of all other arguments. (Attaching non-matching
+ <code class="literal">COLLATE</code> clauses to more than one argument, however, is an
+ error. For more details see <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>.)
+ Thus, this gives the same result as the previous example:
+</p><pre class="programlisting">
+SELECT * FROM tbl WHERE a COLLATE "C" &gt; 'foo';
+</pre><p>
+ But this is an error:
+</p><pre class="programlisting">
+SELECT * FROM tbl WHERE (a &gt; 'foo') COLLATE "C";
+</pre><p>
+ because it attempts to apply a collation to the result of the
+ <code class="literal">&gt;</code> operator, which is of the non-collatable data type
+ <code class="type">boolean</code>.
+ </p></div><div class="sect2" id="SQL-SYNTAX-SCALAR-SUBQUERIES"><div class="titlepage"><div><div><h3 class="title">4.2.11. Scalar Subqueries</h3></div></div></div><a id="id-1.5.3.6.19.2" class="indexterm"></a><p>
+ A scalar subquery is an ordinary
+ <code class="command">SELECT</code> query in parentheses that returns exactly one
+ row with one column. (See <a class="xref" href="queries.html" title="Chapter 7. Queries">Chapter 7</a> for information about writing queries.)
+ The <code class="command">SELECT</code> query is executed
+ and the single returned value is used in the surrounding value expression.
+ It is an error to use a query that
+ returns more than one row or more than one column as a scalar subquery.
+ (But if, during a particular execution, the subquery returns no rows,
+ there is no error; the scalar result is taken to be null.)
+ The subquery can refer to variables from the surrounding query,
+ which will act as constants during any one evaluation of the subquery.
+ See also <a class="xref" href="functions-subquery.html" title="9.23. Subquery Expressions">Section 9.23</a> for other expressions involving subqueries.
+ </p><p>
+ For example, the following finds the largest city population in each
+ state:
+</p><pre class="programlisting">
+SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)
+ FROM states;
+</pre><p>
+ </p></div><div class="sect2" id="SQL-SYNTAX-ARRAY-CONSTRUCTORS"><div class="titlepage"><div><div><h3 class="title">4.2.12. Array Constructors</h3></div></div></div><a id="id-1.5.3.6.20.2" class="indexterm"></a><a id="id-1.5.3.6.20.3" class="indexterm"></a><p>
+ An array constructor is an expression that builds an
+ array value using values for its member elements. A simple array
+ constructor
+ consists of the key word <code class="literal">ARRAY</code>, a left square bracket
+ <code class="literal">[</code>, a list of expressions (separated by commas) for the
+ array element values, and finally a right square bracket <code class="literal">]</code>.
+ For example:
+</p><pre class="programlisting">
+SELECT ARRAY[1,2,3+4];
+ array
+---------
+ {1,2,7}
+(1 row)
+</pre><p>
+ By default,
+ the array element type is the common type of the member expressions,
+ determined using the same rules as for <code class="literal">UNION</code> or
+ <code class="literal">CASE</code> constructs (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
+ You can override this by explicitly casting the array constructor to the
+ desired type, for example:
+</p><pre class="programlisting">
+SELECT ARRAY[1,2,22.7]::integer[];
+ array
+----------
+ {1,2,23}
+(1 row)
+</pre><p>
+ This has the same effect as casting each expression to the array
+ element type individually.
+ For more on casting, see <a class="xref" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS" title="4.2.9. Type Casts">Section 4.2.9</a>.
+ </p><p>
+ Multidimensional array values can be built by nesting array
+ constructors.
+ In the inner constructors, the key word <code class="literal">ARRAY</code> can
+ be omitted. For example, these produce the same result:
+
+</p><pre class="programlisting">
+SELECT ARRAY[ARRAY[1,2], ARRAY[3,4]];
+ array
+---------------
+ {{1,2},{3,4}}
+(1 row)
+
+SELECT ARRAY[[1,2],[3,4]];
+ array
+---------------
+ {{1,2},{3,4}}
+(1 row)
+</pre><p>
+
+ Since multidimensional arrays must be rectangular, inner constructors
+ at the same level must produce sub-arrays of identical dimensions.
+ Any cast applied to the outer <code class="literal">ARRAY</code> constructor propagates
+ automatically to all the inner constructors.
+ </p><p>
+ Multidimensional array constructor elements can be anything yielding
+ an array of the proper kind, not only a sub-<code class="literal">ARRAY</code> construct.
+ For example:
+</p><pre class="programlisting">
+CREATE TABLE arr(f1 int[], f2 int[]);
+
+INSERT INTO arr VALUES (ARRAY[[1,2],[3,4]], ARRAY[[5,6],[7,8]]);
+
+SELECT ARRAY[f1, f2, '{{9,10},{11,12}}'::int[]] FROM arr;
+ array
+------------------------------------------------
+ {{{1,2},{3,4}},{{5,6},{7,8}},{{9,10},{11,12}}}
+(1 row)
+</pre><p>
+ </p><p>
+ You can construct an empty array, but since it's impossible to have an
+ array with no type, you must explicitly cast your empty array to the
+ desired type. For example:
+</p><pre class="programlisting">
+SELECT ARRAY[]::integer[];
+ array
+-------
+ {}
+(1 row)
+</pre><p>
+ </p><p>
+ It is also possible to construct an array from the results of a
+ subquery. In this form, the array constructor is written with the
+ key word <code class="literal">ARRAY</code> followed by a parenthesized (not
+ bracketed) subquery. For example:
+</p><pre class="programlisting">
+SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
+ array
+------------------------------------------------------------------
+ {2011,1954,1948,1952,1951,1244,1950,2005,1949,1953,2006,31,2412}
+(1 row)
+
+SELECT ARRAY(SELECT ARRAY[i, i*2] FROM generate_series(1,5) AS a(i));
+ array
+----------------------------------
+ {{1,2},{2,4},{3,6},{4,8},{5,10}}
+(1 row)
+</pre><p>
+ The subquery must return a single column.
+ If the subquery's output column is of a non-array type, the resulting
+ one-dimensional array will have an element for each row in the
+ subquery result, with an element type matching that of the
+ subquery's output column.
+ If the subquery's output column is of an array type, the result will be
+ an array of the same type but one higher dimension; in this case all
+ the subquery rows must yield arrays of identical dimensionality, else
+ the result would not be rectangular.
+ </p><p>
+ The subscripts of an array value built with <code class="literal">ARRAY</code>
+ always begin with one. For more information about arrays, see
+ <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a>.
+ </p></div><div class="sect2" id="SQL-SYNTAX-ROW-CONSTRUCTORS"><div class="titlepage"><div><div><h3 class="title">4.2.13. Row Constructors</h3></div></div></div><a id="id-1.5.3.6.21.2" class="indexterm"></a><a id="id-1.5.3.6.21.3" class="indexterm"></a><a id="id-1.5.3.6.21.4" class="indexterm"></a><p>
+ A row constructor is an expression that builds a row value (also
+ called a composite value) using values
+ for its member fields. A row constructor consists of the key word
+ <code class="literal">ROW</code>, a left parenthesis, zero or more
+ expressions (separated by commas) for the row field values, and finally
+ a right parenthesis. For example:
+</p><pre class="programlisting">
+SELECT ROW(1,2.5,'this is a test');
+</pre><p>
+ The key word <code class="literal">ROW</code> is optional when there is more than one
+ expression in the list.
+ </p><p>
+ A row constructor can include the syntax
+ <em class="replaceable"><code>rowvalue</code></em><code class="literal">.*</code>,
+ which will be expanded to a list of the elements of the row value,
+ just as occurs when the <code class="literal">.*</code> syntax is used at the top level
+ of a <code class="command">SELECT</code> list (see <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a>).
+ For example, if table <code class="literal">t</code> has
+ columns <code class="literal">f1</code> and <code class="literal">f2</code>, these are the same:
+</p><pre class="programlisting">
+SELECT ROW(t.*, 42) FROM t;
+SELECT ROW(t.f1, t.f2, 42) FROM t;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 8.2, the
+ <code class="literal">.*</code> syntax was not expanded in row constructors, so
+ that writing <code class="literal">ROW(t.*, 42)</code> created a two-field row whose first
+ field was another row value. The new behavior is usually more useful.
+ If you need the old behavior of nested row values, write the inner
+ row value without <code class="literal">.*</code>, for instance
+ <code class="literal">ROW(t, 42)</code>.
+ </p></div><p>
+ By default, the value created by a <code class="literal">ROW</code> expression is of
+ an anonymous record type. If necessary, it can be cast to a named
+ composite type — either the row type of a table, or a composite type
+ created with <code class="command">CREATE TYPE AS</code>. An explicit cast might be needed
+ to avoid ambiguity. For example:
+</p><pre class="programlisting">
+CREATE TABLE mytable(f1 int, f2 float, f3 text);
+
+CREATE FUNCTION getf1(mytable) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
+
+-- No cast needed since only one getf1() exists
+SELECT getf1(ROW(1,2.5,'this is a test'));
+ getf1
+-------
+ 1
+(1 row)
+
+CREATE TYPE myrowtype AS (f1 int, f2 text, f3 numeric);
+
+CREATE FUNCTION getf1(myrowtype) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
+
+-- Now we need a cast to indicate which function to call:
+SELECT getf1(ROW(1,2.5,'this is a test'));
+ERROR: function getf1(record) is not unique
+
+SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
+ getf1
+-------
+ 1
+(1 row)
+
+SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
+ getf1
+-------
+ 11
+(1 row)
+</pre><p>
+ </p><p>
+ Row constructors can be used to build composite values to be stored
+ in a composite-type table column, or to be passed to a function that
+ accepts a composite parameter. Also,
+ it is possible to compare two row values or test a row with
+ <code class="literal">IS NULL</code> or <code class="literal">IS NOT NULL</code>, for example:
+</p><pre class="programlisting">
+SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
+
+SELECT ROW(table.*) IS NULL FROM table; -- detect all-null rows
+</pre><p>
+ For more detail see <a class="xref" href="functions-comparisons.html" title="9.24. Row and Array Comparisons">Section 9.24</a>.
+ Row constructors can also be used in connection with subqueries,
+ as discussed in <a class="xref" href="functions-subquery.html" title="9.23. Subquery Expressions">Section 9.23</a>.
+ </p></div><div class="sect2" id="SYNTAX-EXPRESS-EVAL"><div class="titlepage"><div><div><h3 class="title">4.2.14. Expression Evaluation Rules</h3></div></div></div><a id="id-1.5.3.6.22.2" class="indexterm"></a><p>
+ The order of evaluation of subexpressions is not defined. In
+ particular, the inputs of an operator or function are not necessarily
+ evaluated left-to-right or in any other fixed order.
+ </p><p>
+ Furthermore, if the result of an expression can be determined by
+ evaluating only some parts of it, then other subexpressions
+ might not be evaluated at all. For instance, if one wrote:
+</p><pre class="programlisting">
+SELECT true OR somefunc();
+</pre><p>
+ then <code class="literal">somefunc()</code> would (probably) not be called
+ at all. The same would be the case if one wrote:
+</p><pre class="programlisting">
+SELECT somefunc() OR true;
+</pre><p>
+ Note that this is not the same as the left-to-right
+ <span class="quote">“<span class="quote">short-circuiting</span>”</span> of Boolean operators that is found
+ in some programming languages.
+ </p><p>
+ As a consequence, it is unwise to use functions with side effects
+ as part of complex expressions. It is particularly dangerous to
+ rely on side effects or evaluation order in <code class="literal">WHERE</code> and <code class="literal">HAVING</code> clauses,
+ since those clauses are extensively reprocessed as part of
+ developing an execution plan. Boolean
+ expressions (<code class="literal">AND</code>/<code class="literal">OR</code>/<code class="literal">NOT</code> combinations) in those clauses can be reorganized
+ in any manner allowed by the laws of Boolean algebra.
+ </p><p>
+ When it is essential to force evaluation order, a <code class="literal">CASE</code>
+ construct (see <a class="xref" href="functions-conditional.html" title="9.18. Conditional Expressions">Section 9.18</a>) can be
+ used. For example, this is an untrustworthy way of trying to
+ avoid division by zero in a <code class="literal">WHERE</code> clause:
+</p><pre class="programlisting">
+SELECT ... WHERE x &gt; 0 AND y/x &gt; 1.5;
+</pre><p>
+ But this is safe:
+</p><pre class="programlisting">
+SELECT ... WHERE CASE WHEN x &gt; 0 THEN y/x &gt; 1.5 ELSE false END;
+</pre><p>
+ A <code class="literal">CASE</code> construct used in this fashion will defeat optimization
+ attempts, so it should only be done when necessary. (In this particular
+ example, it would be better to sidestep the problem by writing
+ <code class="literal">y &gt; 1.5*x</code> instead.)
+ </p><p>
+ <code class="literal">CASE</code> is not a cure-all for such issues, however.
+ One limitation of the technique illustrated above is that it does not
+ prevent early evaluation of constant subexpressions.
+ As described in <a class="xref" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Section 38.7</a>, functions and
+ operators marked <code class="literal">IMMUTABLE</code> can be evaluated when
+ the query is planned rather than when it is executed. Thus for example
+</p><pre class="programlisting">
+SELECT CASE WHEN x &gt; 0 THEN x ELSE 1/0 END FROM tab;
+</pre><p>
+ is likely to result in a division-by-zero failure due to the planner
+ trying to simplify the constant subexpression,
+ even if every row in the table has <code class="literal">x &gt; 0</code> so that the
+ <code class="literal">ELSE</code> arm would never be entered at run time.
+ </p><p>
+ While that particular example might seem silly, related cases that don't
+ obviously involve constants can occur in queries executed within
+ functions, since the values of function arguments and local variables
+ can be inserted into queries as constants for planning purposes.
+ Within <span class="application">PL/pgSQL</span> functions, for example, using an
+ <code class="literal">IF</code>-<code class="literal">THEN</code>-<code class="literal">ELSE</code> statement to protect
+ a risky computation is much safer than just nesting it in a
+ <code class="literal">CASE</code> expression.
+ </p><p>
+ Another limitation of the same kind is that a <code class="literal">CASE</code> cannot
+ prevent evaluation of an aggregate expression contained within it,
+ because aggregate expressions are computed before other
+ expressions in a <code class="literal">SELECT</code> list or <code class="literal">HAVING</code> clause
+ are considered. For example, the following query can cause a
+ division-by-zero error despite seemingly having protected against it:
+</p><pre class="programlisting">
+SELECT CASE WHEN min(employees) &gt; 0
+ THEN avg(expenses / employees)
+ END
+ FROM departments;
+</pre><p>
+ The <code class="function">min()</code> and <code class="function">avg()</code> aggregates are computed
+ concurrently over all the input rows, so if any row
+ has <code class="structfield">employees</code> equal to zero, the division-by-zero error
+ will occur before there is any opportunity to test the result of
+ <code class="function">min()</code>. Instead, use a <code class="literal">WHERE</code>
+ or <code class="literal">FILTER</code> clause to prevent problematic input rows from
+ reaching an aggregate function in the first place.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-syntax-lexical.html" title="4.1. Lexical Structure">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.1. Lexical Structure </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 4.3. Calling Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-fetch.html b/doc/src/sgml/html/sql-fetch.html
new file mode 100644
index 0000000..0dd70b5
--- /dev/null
+++ b/doc/src/sgml/html/sql-fetch.html
@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>FETCH</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-explain.html" title="EXPLAIN" /><link rel="next" href="sql-grant.html" title="GRANT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">FETCH</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-explain.html" title="EXPLAIN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-grant.html" title="GRANT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-FETCH"><div class="titlepage"></div><a id="id-1.9.3.149.1" class="indexterm"></a><a id="id-1.9.3.149.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">FETCH</span></h2><p>FETCH — retrieve rows from a query using a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+FETCH [ <em class="replaceable"><code>direction</code></em> ] [ FROM | IN ] <em class="replaceable"><code>cursor_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>direction</code></em> can be one of:</span>
+
+ NEXT
+ PRIOR
+ FIRST
+ LAST
+ ABSOLUTE <em class="replaceable"><code>count</code></em>
+ RELATIVE <em class="replaceable"><code>count</code></em>
+ <em class="replaceable"><code>count</code></em>
+ ALL
+ FORWARD
+ FORWARD <em class="replaceable"><code>count</code></em>
+ FORWARD ALL
+ BACKWARD
+ BACKWARD <em class="replaceable"><code>count</code></em>
+ BACKWARD ALL
+</pre></div><div class="refsect1" id="id-1.9.3.149.6"><h2>Description</h2><p>
+ <code class="command">FETCH</code> retrieves rows using a previously-created cursor.
+ </p><p>
+ A cursor has an associated position, which is used by
+ <code class="command">FETCH</code>. The cursor position can be before the first row of the
+ query result, on any particular row of the result, or after the last row
+ of the result. When created, a cursor is positioned before the first row.
+ After fetching some rows, the cursor is positioned on the row most recently
+ retrieved. If <code class="command">FETCH</code> runs off the end of the available rows
+ then the cursor is left positioned after the last row, or before the first
+ row if fetching backward. <code class="command">FETCH ALL</code> or <code class="command">FETCH BACKWARD
+ ALL</code> will always leave the cursor positioned after the last row or before
+ the first row.
+ </p><p>
+ The forms <code class="literal">NEXT</code>, <code class="literal">PRIOR</code>, <code class="literal">FIRST</code>,
+ <code class="literal">LAST</code>, <code class="literal">ABSOLUTE</code>, <code class="literal">RELATIVE</code> fetch
+ a single row after moving the cursor appropriately. If there is no
+ such row, an empty result is returned, and the cursor is left
+ positioned before the first row or after the last row as
+ appropriate.
+ </p><p>
+ The forms using <code class="literal">FORWARD</code> and <code class="literal">BACKWARD</code>
+ retrieve the indicated number of rows moving in the forward or
+ backward direction, leaving the cursor positioned on the
+ last-returned row (or after/before all rows, if the <em class="replaceable"><code>count</code></em> exceeds the number of rows
+ available).
+ </p><p>
+ <code class="literal">RELATIVE 0</code>, <code class="literal">FORWARD 0</code>, and
+ <code class="literal">BACKWARD 0</code> all request fetching the current row without
+ moving the cursor, that is, re-fetching the most recently fetched
+ row. This will succeed unless the cursor is positioned before the
+ first row or after the last row; in which case, no row is returned.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ This page describes usage of cursors at the SQL command level.
+ If you are trying to use cursors inside a <span class="application">PL/pgSQL</span>
+ function, the rules are different —
+ see <a class="xref" href="plpgsql-cursors.html#PLPGSQL-CURSOR-USING" title="43.7.3. Using Cursors">Section 43.7.3</a>.
+ </p></div></div><div class="refsect1" id="id-1.9.3.149.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>direction</code></em></span></dt><dd><p><em class="replaceable"><code>direction</code></em> defines
+ the fetch direction and number of rows to fetch. It can be one
+ of the following:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">NEXT</code></span></dt><dd><p>
+ Fetch the next row. This is the default if <em class="replaceable"><code>direction</code></em> is omitted.
+ </p></dd><dt><span class="term"><code class="literal">PRIOR</code></span></dt><dd><p>
+ Fetch the prior row.
+ </p></dd><dt><span class="term"><code class="literal">FIRST</code></span></dt><dd><p>
+ Fetch the first row of the query (same as <code class="literal">ABSOLUTE 1</code>).
+ </p></dd><dt><span class="term"><code class="literal">LAST</code></span></dt><dd><p>
+ Fetch the last row of the query (same as <code class="literal">ABSOLUTE -1</code>).
+ </p></dd><dt><span class="term"><code class="literal">ABSOLUTE <em class="replaceable"><code>count</code></em></code></span></dt><dd><p>
+ Fetch the <em class="replaceable"><code>count</code></em>'th row of the query,
+ or the <code class="literal">abs(<em class="replaceable"><code>count</code></em>)</code>'th row from
+ the end if <em class="replaceable"><code>count</code></em> is negative. Position
+ before first row or after last row if <em class="replaceable"><code>count</code></em> is out of range; in
+ particular, <code class="literal">ABSOLUTE 0</code> positions before
+ the first row.
+ </p></dd><dt><span class="term"><code class="literal">RELATIVE <em class="replaceable"><code>count</code></em></code></span></dt><dd><p>
+ Fetch the <em class="replaceable"><code>count</code></em>'th succeeding row, or
+ the <code class="literal">abs(<em class="replaceable"><code>count</code></em>)</code>'th prior
+ row if <em class="replaceable"><code>count</code></em> is
+ negative. <code class="literal">RELATIVE 0</code> re-fetches the
+ current row, if any.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>count</code></em></span></dt><dd><p>
+ Fetch the next <em class="replaceable"><code>count</code></em> rows (same as
+ <code class="literal">FORWARD <em class="replaceable"><code>count</code></em></code>).
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Fetch all remaining rows (same as <code class="literal">FORWARD ALL</code>).
+ </p></dd><dt><span class="term"><code class="literal">FORWARD</code></span></dt><dd><p>
+ Fetch the next row (same as <code class="literal">NEXT</code>).
+ </p></dd><dt><span class="term"><code class="literal">FORWARD <em class="replaceable"><code>count</code></em></code></span></dt><dd><p>
+ Fetch the next <em class="replaceable"><code>count</code></em> rows.
+ <code class="literal">FORWARD 0</code> re-fetches the current row.
+ </p></dd><dt><span class="term"><code class="literal">FORWARD ALL</code></span></dt><dd><p>
+ Fetch all remaining rows.
+ </p></dd><dt><span class="term"><code class="literal">BACKWARD</code></span></dt><dd><p>
+ Fetch the prior row (same as <code class="literal">PRIOR</code>).
+ </p></dd><dt><span class="term"><code class="literal">BACKWARD <em class="replaceable"><code>count</code></em></code></span></dt><dd><p>
+ Fetch the prior <em class="replaceable"><code>count</code></em> rows (scanning
+ backwards). <code class="literal">BACKWARD 0</code> re-fetches the
+ current row.
+ </p></dd><dt><span class="term"><code class="literal">BACKWARD ALL</code></span></dt><dd><p>
+ Fetch all prior rows (scanning backwards).
+ </p></dd></dl></div></dd><dt><span class="term"><em class="replaceable"><code>count</code></em></span></dt><dd><p><em class="replaceable"><code>count</code></em> is a
+ possibly-signed integer constant, determining the location or
+ number of rows to fetch. For <code class="literal">FORWARD</code> and
+ <code class="literal">BACKWARD</code> cases, specifying a negative <em class="replaceable"><code>count</code></em> is equivalent to changing
+ the sense of <code class="literal">FORWARD</code> and <code class="literal">BACKWARD</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+ An open cursor's name.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.149.8"><h2>Outputs</h2><p>
+ On successful completion, a <code class="command">FETCH</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+FETCH <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number
+ of rows fetched (possibly zero). Note that in
+ <span class="application">psql</span>, the command tag will not actually be
+ displayed, since <span class="application">psql</span> displays the fetched
+ rows instead.
+ </p></div><div class="refsect1" id="id-1.9.3.149.9"><h2>Notes</h2><p>
+ The cursor should be declared with the <code class="literal">SCROLL</code>
+ option if one intends to use any variants of <code class="command">FETCH</code>
+ other than <code class="command">FETCH NEXT</code> or <code class="command">FETCH FORWARD</code> with
+ a positive count. For simple queries
+ <span class="productname">PostgreSQL</span> will allow backwards fetch
+ from cursors not declared with <code class="literal">SCROLL</code>, but this
+ behavior is best not relied on. If the cursor is declared with
+ <code class="literal">NO SCROLL</code>, no backward fetches are allowed.
+ </p><p>
+ <code class="literal">ABSOLUTE</code> fetches are not any faster than
+ navigating to the desired row with a relative move: the underlying
+ implementation must traverse all the intermediate rows anyway.
+ Negative absolute fetches are even worse: the query must be read to
+ the end to find the last row, and then traversed backward from
+ there. However, rewinding to the start of the query (as with
+ <code class="literal">FETCH ABSOLUTE 0</code>) is fast.
+ </p><p>
+ <a class="link" href="sql-declare.html" title="DECLARE"><code class="command">DECLARE</code></a>
+ is used to define a cursor. Use
+ <a class="link" href="sql-move.html" title="MOVE"><code class="command">MOVE</code></a>
+ to change cursor position without retrieving data.
+ </p></div><div class="refsect1" id="id-1.9.3.149.10"><h2>Examples</h2><p>
+ The following example traverses a table using a cursor:
+
+</p><pre class="programlisting">
+BEGIN WORK;
+
+-- Set up a cursor:
+DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;
+
+-- Fetch the first 5 rows in the cursor liahona:
+FETCH FORWARD 5 FROM liahona;
+
+ code | title | did | date_prod | kind | len
+-------+-------------------------+-----+------------+----------+-------
+ BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44
+ BL102 | The African Queen | 101 | 1951-08-11 | Romantic | 01:43
+ JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
+ P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
+ P_302 | Becket | 103 | 1964-02-03 | Drama | 02:28
+
+-- Fetch the previous row:
+FETCH PRIOR FROM liahona;
+
+ code | title | did | date_prod | kind | len
+-------+---------+-----+------------+--------+-------
+ P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
+
+-- Close the cursor and end the transaction:
+CLOSE liahona;
+COMMIT WORK;
+</pre></div><div class="refsect1" id="id-1.9.3.149.11"><h2>Compatibility</h2><p>
+ The SQL standard defines <code class="command">FETCH</code> for use in
+ embedded SQL only. The variant of <code class="command">FETCH</code>
+ described here returns the data as if it were a
+ <code class="command">SELECT</code> result rather than placing it in host
+ variables. Other than this point, <code class="command">FETCH</code> is
+ fully upward-compatible with the SQL standard.
+ </p><p>
+ The <code class="command">FETCH</code> forms involving
+ <code class="literal">FORWARD</code> and <code class="literal">BACKWARD</code>, as well
+ as the forms <code class="literal">FETCH <em class="replaceable"><code>count</code></em></code> and <code class="literal">FETCH
+ ALL</code>, in which <code class="literal">FORWARD</code> is implicit, are
+ <span class="productname">PostgreSQL</span> extensions.
+ </p><p>
+ The SQL standard allows only <code class="literal">FROM</code> preceding the cursor
+ name; the option to use <code class="literal">IN</code>, or to leave them out altogether, is
+ an extension.
+ </p></div><div class="refsect1" id="id-1.9.3.149.12"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-close.html" title="CLOSE"><span class="refentrytitle">CLOSE</span></a>, <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>, <a class="xref" href="sql-move.html" title="MOVE"><span class="refentrytitle">MOVE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-explain.html" title="EXPLAIN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-grant.html" title="GRANT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">EXPLAIN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> GRANT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-grant.html b/doc/src/sgml/html/sql-grant.html
new file mode 100644
index 0000000..9d4a136
--- /dev/null
+++ b/doc/src/sgml/html/sql-grant.html
@@ -0,0 +1,318 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>GRANT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-fetch.html" title="FETCH" /><link rel="next" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">GRANT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-fetch.html" title="FETCH">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-GRANT"><div class="titlepage"></div><a id="id-1.9.3.150.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">GRANT</span></h2><p>GRANT — define access privileges</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON { [ TABLE ] <em class="replaceable"><code>table_name</code></em> [, ...]
+ | ALL TABLES IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { SELECT | INSERT | UPDATE | REFERENCES } ( <em class="replaceable"><code>column_name</code></em> [, ...] )
+ [, ...] | ALL [ PRIVILEGES ] ( <em class="replaceable"><code>column_name</code></em> [, ...] ) }
+ ON [ TABLE ] <em class="replaceable"><code>table_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { USAGE | SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON { SEQUENCE <em class="replaceable"><code>sequence_name</code></em> [, ...]
+ | ALL SEQUENCES IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { CREATE | CONNECT | TEMPORARY | TEMP } [, ...] | ALL [ PRIVILEGES ] }
+ ON DATABASE <em class="replaceable"><code>database_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON DOMAIN <em class="replaceable"><code>domain_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON FOREIGN DATA WRAPPER <em class="replaceable"><code>fdw_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON FOREIGN SERVER <em class="replaceable"><code>server_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { EXECUTE | ALL [ PRIVILEGES ] }
+ ON { { FUNCTION | PROCEDURE | ROUTINE } <em class="replaceable"><code>routine_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>arg_name</code></em> ] <em class="replaceable"><code>arg_type</code></em> [, ...] ] ) ] [, ...]
+ | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON LANGUAGE <em class="replaceable"><code>lang_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { SELECT | UPDATE } [, ...] | ALL [ PRIVILEGES ] }
+ ON LARGE OBJECT <em class="replaceable"><code>loid</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { SET | ALTER SYSTEM } [, ... ] | ALL [ PRIVILEGES ] }
+ ON PARAMETER <em class="replaceable"><code>configuration_parameter</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
+ ON SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { CREATE | ALL [ PRIVILEGES ] }
+ ON TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+ ON TYPE <em class="replaceable"><code>type_name</code></em> [, ...]
+ TO <em class="replaceable"><code>role_specification</code></em> [, ...] [ WITH GRANT OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+GRANT <em class="replaceable"><code>role_name</code></em> [, ...] TO <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ WITH ADMIN OPTION ]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ [ GROUP ] <em class="replaceable"><code>role_name</code></em>
+ | PUBLIC
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+</pre></div><div class="refsect1" id="SQL-GRANT-DESCRIPTION"><h2>Description</h2><p>
+ The <code class="command">GRANT</code> command has two basic variants: one
+ that grants privileges on a database object (table, column, view,
+ foreign table, sequence, database, foreign-data wrapper, foreign server,
+ function, procedure, procedural language, large object, configuration
+ parameter, schema, tablespace, or type), and one that grants
+ membership in a role. These variants are similar in many ways, but
+ they are different enough to be described separately.
+ </p><div class="refsect2" id="SQL-GRANT-DESCRIPTION-OBJECTS"><h3>GRANT on Database Objects</h3><p>
+ This variant of the <code class="command">GRANT</code> command gives specific
+ privileges on a database object to
+ one or more roles. These privileges are added
+ to those already granted, if any.
+ </p><p>
+ The key word <code class="literal">PUBLIC</code> indicates that the
+ privileges are to be granted to all roles, including those that might
+ be created later. <code class="literal">PUBLIC</code> can be thought of as an
+ implicitly defined group that always includes all roles.
+ Any particular role will have the sum
+ of privileges granted directly to it, privileges granted to any role it
+ is presently a member of, and privileges granted to
+ <code class="literal">PUBLIC</code>.
+ </p><p>
+ If <code class="literal">WITH GRANT OPTION</code> is specified, the recipient
+ of the privilege can in turn grant it to others. Without a grant
+ option, the recipient cannot do that. Grant options cannot be granted
+ to <code class="literal">PUBLIC</code>.
+ </p><p>
+ If <code class="literal">GRANTED BY</code> is specified, the specified grantor must
+ be the current user. This clause is currently present in this form only
+ for SQL compatibility.
+ </p><p>
+ There is no need to grant privileges to the owner of an object
+ (usually the user that created it),
+ as the owner has all privileges by default. (The owner could,
+ however, choose to revoke some of their own privileges for safety.)
+ </p><p>
+ The right to drop an object, or to alter its definition in any way, is
+ not treated as a grantable privilege; it is inherent in the owner,
+ and cannot be granted or revoked. (However, a similar effect can be
+ obtained by granting or revoking membership in the role that owns
+ the object; see below.) The owner implicitly has all grant
+ options for the object, too.
+ </p><p>
+ The possible privileges are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SELECT</code><br /></span><span class="term"><code class="literal">INSERT</code><br /></span><span class="term"><code class="literal">UPDATE</code><br /></span><span class="term"><code class="literal">DELETE</code><br /></span><span class="term"><code class="literal">TRUNCATE</code><br /></span><span class="term"><code class="literal">REFERENCES</code><br /></span><span class="term"><code class="literal">TRIGGER</code><br /></span><span class="term"><code class="literal">CREATE</code><br /></span><span class="term"><code class="literal">CONNECT</code><br /></span><span class="term"><code class="literal">TEMPORARY</code><br /></span><span class="term"><code class="literal">EXECUTE</code><br /></span><span class="term"><code class="literal">USAGE</code><br /></span><span class="term"><code class="literal">SET</code><br /></span><span class="term"><code class="literal">ALTER SYSTEM</code></span></dt><dd><p>
+ Specific types of privileges, as defined in <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.
+ </p></dd><dt><span class="term"><code class="literal">TEMP</code></span></dt><dd><p>
+ Alternative spelling for <code class="literal">TEMPORARY</code>.
+ </p></dd><dt><span class="term"><code class="literal">ALL PRIVILEGES</code></span></dt><dd><p>
+ Grant all of the privileges available for the object's type.
+ The <code class="literal">PRIVILEGES</code> key word is optional in
+ <span class="productname">PostgreSQL</span>, though it is required by
+ strict SQL.
+ </p></dd></dl></div><p>
+ </p><p>
+ The <code class="literal">FUNCTION</code> syntax works for plain functions,
+ aggregate functions, and window functions, but not for procedures;
+ use <code class="literal">PROCEDURE</code> for those.
+ Alternatively, use <code class="literal">ROUTINE</code> to refer to a function,
+ aggregate function, window function, or procedure regardless of its
+ precise type.
+ </p><p>
+ There is also an option to grant privileges on all objects of the same
+ type within one or more schemas. This functionality is currently supported
+ only for tables, sequences, functions, and procedures. <code class="literal">ALL
+ TABLES</code> also affects views and foreign tables, just like the
+ specific-object <code class="command">GRANT</code> command. <code class="literal">ALL
+ FUNCTIONS</code> also affects aggregate and window functions, but not
+ procedures, again just like the specific-object <code class="command">GRANT</code>
+ command. Use <code class="literal">ALL ROUTINES</code> to include procedures.
+ </p></div><div class="refsect2" id="SQL-GRANT-DESCRIPTION-ROLES"><h3>GRANT on Roles</h3><p>
+ This variant of the <code class="command">GRANT</code> command grants membership
+ in a role to one or more other roles. Membership in a role is significant
+ because it conveys the privileges granted to a role to each of its
+ members.
+ </p><p>
+ If <code class="literal">WITH ADMIN OPTION</code> is specified, the member can
+ in turn grant membership in the role to others, and revoke membership
+ in the role as well. Without the admin option, ordinary users cannot
+ do that. A role is not considered to hold <code class="literal">WITH ADMIN
+ OPTION</code> on itself. Database superusers can grant or revoke
+ membership in any role to anyone. Roles having
+ <code class="literal">CREATEROLE</code> privilege can grant or revoke membership
+ in any role that is not a superuser.
+ </p><p>
+ If <code class="literal">GRANTED BY</code> is specified, the grant is recorded as
+ having been done by the specified role. Only database superusers may
+ use this option, except when it names the same role executing the command.
+ </p><p>
+ Unlike the case with privileges, membership in a role cannot be granted
+ to <code class="literal">PUBLIC</code>. Note also that this form of the command
+ does not allow the noise word <code class="literal">GROUP</code>
+ in <em class="replaceable"><code>role_specification</code></em>.
+ </p></div></div><div class="refsect1" id="SQL-GRANT-NOTES"><h2>Notes</h2><p>
+ The <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a> command is used
+ to revoke access privileges.
+ </p><p>
+ Since <span class="productname">PostgreSQL</span> 8.1, the concepts of users and
+ groups have been unified into a single kind of entity called a role.
+ It is therefore no longer necessary to use the keyword <code class="literal">GROUP</code>
+ to identify whether a grantee is a user or a group. <code class="literal">GROUP</code>
+ is still allowed in the command, but it is a noise word.
+ </p><p>
+ A user may perform <code class="command">SELECT</code>, <code class="command">INSERT</code>, etc. on a
+ column if they hold that privilege for either the specific column or
+ its whole table. Granting the privilege at the table level and then
+ revoking it for one column will not do what one might wish: the
+ table-level grant is unaffected by a column-level operation.
+ </p><p>
+ When a non-owner of an object attempts to <code class="command">GRANT</code> privileges
+ on the object, the command will fail outright if the user has no
+ privileges whatsoever on the object. As long as some privilege is
+ available, the command will proceed, but it will grant only those
+ privileges for which the user has grant options. The <code class="command">GRANT ALL
+ PRIVILEGES</code> forms will issue a warning message if no grant options are
+ held, while the other forms will issue a warning if grant options for
+ any of the privileges specifically named in the command are not held.
+ (In principle these statements apply to the object owner as well, but
+ since the owner is always treated as holding all grant options, the
+ cases can never occur.)
+ </p><p>
+ It should be noted that database superusers can access
+ all objects regardless of object privilege settings. This
+ is comparable to the rights of <code class="literal">root</code> in a Unix system.
+ As with <code class="literal">root</code>, it's unwise to operate as a superuser
+ except when absolutely necessary.
+ </p><p>
+ If a superuser chooses to issue a <code class="command">GRANT</code> or <code class="command">REVOKE</code>
+ command, the command is performed as though it were issued by the
+ owner of the affected object. In particular, privileges granted via
+ such a command will appear to have been granted by the object owner.
+ (For role membership, the membership appears to have been granted
+ by the containing role itself.)
+ </p><p>
+ <code class="command">GRANT</code> and <code class="command">REVOKE</code> can also be done by a role
+ that is not the owner of the affected object, but is a member of the role
+ that owns the object, or is a member of a role that holds privileges
+ <code class="literal">WITH GRANT OPTION</code> on the object. In this case the
+ privileges will be recorded as having been granted by the role that
+ actually owns the object or holds the privileges
+ <code class="literal">WITH GRANT OPTION</code>. For example, if table
+ <code class="literal">t1</code> is owned by role <code class="literal">g1</code>, of which role
+ <code class="literal">u1</code> is a member, then <code class="literal">u1</code> can grant privileges
+ on <code class="literal">t1</code> to <code class="literal">u2</code>, but those privileges will appear
+ to have been granted directly by <code class="literal">g1</code>. Any other member
+ of role <code class="literal">g1</code> could revoke them later.
+ </p><p>
+ If the role executing <code class="command">GRANT</code> holds the required privileges
+ indirectly via more than one role membership path, it is unspecified
+ which containing role will be recorded as having done the grant. In such
+ cases it is best practice to use <code class="command">SET ROLE</code> to become the
+ specific role you want to do the <code class="command">GRANT</code> as.
+ </p><p>
+ Granting permission on a table does not automatically extend
+ permissions to any sequences used by the table, including
+ sequences tied to <code class="type">SERIAL</code> columns. Permissions on
+ sequences must be set separately.
+ </p><p>
+ See <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for more information about specific
+ privilege types, as well as how to inspect objects' privileges.
+ </p></div><div class="refsect1" id="SQL-GRANT-EXAMPLES"><h2>Examples</h2><p>
+ Grant insert privilege to all users on table <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+GRANT INSERT ON films TO PUBLIC;
+</pre><p>
+ </p><p>
+ Grant all available privileges to user <code class="literal">manuel</code> on view
+ <code class="literal">kinds</code>:
+
+</p><pre class="programlisting">
+GRANT ALL PRIVILEGES ON kinds TO manuel;
+</pre><p>
+
+ Note that while the above will indeed grant all privileges if executed by a
+ superuser or the owner of <code class="literal">kinds</code>, when executed by someone
+ else it will only grant those permissions for which the someone else has
+ grant options.
+ </p><p>
+ Grant membership in role <code class="literal">admins</code> to user <code class="literal">joe</code>:
+
+</p><pre class="programlisting">
+GRANT admins TO joe;
+</pre></div><div class="refsect1" id="SQL-GRANT-COMPATIBILITY"><h2>Compatibility</h2><p>
+ According to the SQL standard, the <code class="literal">PRIVILEGES</code>
+ key word in <code class="literal">ALL PRIVILEGES</code> is required. The
+ SQL standard does not support setting the privileges on more than
+ one object per command.
+ </p><p>
+ <span class="productname">PostgreSQL</span> allows an object owner to revoke their
+ own ordinary privileges: for example, a table owner can make the table
+ read-only to themselves by revoking their own <code class="literal">INSERT</code>,
+ <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>, and <code class="literal">TRUNCATE</code>
+ privileges. This is not possible according to the SQL standard. The
+ reason is that <span class="productname">PostgreSQL</span> treats the owner's
+ privileges as having been granted by the owner to themselves; therefore they
+ can revoke them too. In the SQL standard, the owner's privileges are
+ granted by an assumed entity <span class="quote">“<span class="quote">_SYSTEM</span>”</span>. Not being
+ <span class="quote">“<span class="quote">_SYSTEM</span>”</span>, the owner cannot revoke these rights.
+ </p><p>
+ According to the SQL standard, grant options can be granted to
+ <code class="literal">PUBLIC</code>; PostgreSQL only supports granting grant options
+ to roles.
+ </p><p>
+ The SQL standard allows the <code class="literal">GRANTED BY</code> option to
+ specify only <code class="literal">CURRENT_USER</code> or
+ <code class="literal">CURRENT_ROLE</code>. The other variants are PostgreSQL
+ extensions.
+ </p><p>
+ The SQL standard provides for a <code class="literal">USAGE</code> privilege
+ on other kinds of objects: character sets, collations,
+ translations.
+ </p><p>
+ In the SQL standard, sequences only have a <code class="literal">USAGE</code>
+ privilege, which controls the use of the <code class="literal">NEXT VALUE FOR</code>
+ expression, which is equivalent to the
+ function <code class="function">nextval</code> in PostgreSQL. The sequence
+ privileges <code class="literal">SELECT</code> and <code class="literal">UPDATE</code> are
+ PostgreSQL extensions. The application of the
+ sequence <code class="literal">USAGE</code> privilege to
+ the <code class="literal">currval</code> function is also a PostgreSQL extension (as
+ is the function itself).
+ </p><p>
+ Privileges on databases, tablespaces, schemas, languages, and
+ configuration parameters are
+ <span class="productname">PostgreSQL</span> extensions.
+ </p></div><div class="refsect1" id="id-1.9.3.150.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a>, <a class="xref" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES"><span class="refentrytitle">ALTER DEFAULT PRIVILEGES</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-fetch.html" title="FETCH">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA">Next</a></td></tr><tr><td width="40%" align="left" valign="top">FETCH </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> IMPORT FOREIGN SCHEMA</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-importforeignschema.html b/doc/src/sgml/html/sql-importforeignschema.html
new file mode 100644
index 0000000..bea69bf
--- /dev/null
+++ b/doc/src/sgml/html/sql-importforeignschema.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>IMPORT FOREIGN SCHEMA</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-grant.html" title="GRANT" /><link rel="next" href="sql-insert.html" title="INSERT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">IMPORT FOREIGN SCHEMA</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-grant.html" title="GRANT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-insert.html" title="INSERT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-IMPORTFOREIGNSCHEMA"><div class="titlepage"></div><a id="id-1.9.3.151.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></h2><p>IMPORT FOREIGN SCHEMA — import table definitions from a foreign server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+IMPORT FOREIGN SCHEMA <em class="replaceable"><code>remote_schema</code></em>
+ [ { LIMIT TO | EXCEPT } ( <em class="replaceable"><code>table_name</code></em> [, ...] ) ]
+ FROM SERVER <em class="replaceable"><code>server_name</code></em>
+ INTO <em class="replaceable"><code>local_schema</code></em>
+ [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
+</pre></div><div class="refsect1" id="SQL-IMPORTFOREIGNSCHEMA-DESCRIPTION"><h2>Description</h2><p>
+ <code class="command">IMPORT FOREIGN SCHEMA</code> creates foreign tables that
+ represent tables existing on a foreign server. The new foreign tables
+ will be owned by the user issuing the command and are created with
+ the correct column definitions and options to match the remote tables.
+ </p><p>
+ By default, all tables and views existing in a particular schema on the
+ foreign server are imported. Optionally, the list of tables can be limited
+ to a specified subset, or specific tables can be excluded. The new foreign
+ tables are all created in the target schema, which must already exist.
+ </p><p>
+ To use <code class="command">IMPORT FOREIGN SCHEMA</code>, the user must have
+ <code class="literal">USAGE</code> privilege on the foreign server, as well as
+ <code class="literal">CREATE</code> privilege on the target schema.
+ </p></div><div class="refsect1" id="id-1.9.3.151.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>remote_schema</code></em></span></dt><dd><p>
+ The remote schema to import from. The specific meaning of a remote schema
+ depends on the foreign data wrapper in use.
+ </p></dd><dt><span class="term"><code class="literal">LIMIT TO ( <em class="replaceable"><code>table_name</code></em> [, ...] )</code></span></dt><dd><p>
+ Import only foreign tables matching one of the given table names.
+ Other tables existing in the foreign schema will be ignored.
+ </p></dd><dt><span class="term"><code class="literal">EXCEPT ( <em class="replaceable"><code>table_name</code></em> [, ...] )</code></span></dt><dd><p>
+ Exclude specified foreign tables from the import. All tables
+ existing in the foreign schema will be imported except the
+ ones listed here.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
+ The foreign server to import from.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>local_schema</code></em></span></dt><dd><p>
+ The schema in which the imported foreign tables will be created.
+ </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ...] )</code></span></dt><dd><p>
+ Options to be used during the import.
+ The allowed option names and values are specific to each foreign
+ data wrapper.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-IMPORTFOREIGNSCHEMA-EXAMPLES"><h2>Examples</h2><p>
+ Import table definitions from a remote schema <code class="structname">foreign_films</code>
+ on server <code class="structname">film_server</code>, creating the foreign tables in
+ local schema <code class="structname">films</code>:
+
+</p><pre class="programlisting">
+IMPORT FOREIGN SCHEMA foreign_films
+ FROM SERVER film_server INTO films;
+</pre><p>
+ </p><p>
+ As above, but import only the two tables <code class="structname">actors</code> and
+ <code class="literal">directors</code> (if they exist):
+
+</p><pre class="programlisting">
+IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors)
+ FROM SERVER film_server INTO films;
+</pre></div><div class="refsect1" id="SQL-IMPORTFOREIGNSCHEMA-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The <code class="command">IMPORT FOREIGN SCHEMA</code> command conforms to the
+ <acronym class="acronym">SQL</acronym> standard, except that the <code class="literal">OPTIONS</code>
+ clause is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.151.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>, <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-grant.html" title="GRANT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-insert.html" title="INSERT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">GRANT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> INSERT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-insert.html b/doc/src/sgml/html/sql-insert.html
new file mode 100644
index 0000000..e840ddc
--- /dev/null
+++ b/doc/src/sgml/html/sql-insert.html
@@ -0,0 +1,488 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>INSERT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA" /><link rel="next" href="sql-listen.html" title="LISTEN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">INSERT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-listen.html" title="LISTEN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-INSERT"><div class="titlepage"></div><a id="id-1.9.3.152.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">INSERT</span></h2><p>INSERT — create new rows in a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+INSERT INTO <em class="replaceable"><code>table_name</code></em> [ AS <em class="replaceable"><code>alias</code></em> ] [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+ [ OVERRIDING { SYSTEM | USER } VALUE ]
+ { DEFAULT VALUES | VALUES ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) [, ...] | <em class="replaceable"><code>query</code></em> }
+ [ ON CONFLICT [ <em class="replaceable"><code>conflict_target</code></em> ] <em class="replaceable"><code>conflict_action</code></em> ]
+ [ RETURNING * | <em class="replaceable"><code>output_expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]
+
+<span class="phrase">where <em class="replaceable"><code>conflict_target</code></em> can be one of:</span>
+
+ ( { <em class="replaceable"><code>index_column_name</code></em> | ( <em class="replaceable"><code>index_expression</code></em> ) } [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>opclass</code></em> ] [, ...] ) [ WHERE <em class="replaceable"><code>index_predicate</code></em> ]
+ ON CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>
+
+<span class="phrase">and <em class="replaceable"><code>conflict_action</code></em> is one of:</span>
+
+ DO NOTHING
+ DO UPDATE SET { <em class="replaceable"><code>column_name</code></em> = { <em class="replaceable"><code>expression</code></em> | DEFAULT } |
+ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = [ ROW ] ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) |
+ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = ( <em class="replaceable"><code>sub-SELECT</code></em> )
+ } [, ...]
+ [ WHERE <em class="replaceable"><code>condition</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.152.5"><h2>Description</h2><p>
+ <code class="command">INSERT</code> inserts new rows into a table.
+ One can insert one or more rows specified by value expressions,
+ or zero or more rows resulting from a query.
+ </p><p>
+ The target column names can be listed in any order. If no list of
+ column names is given at all, the default is all the columns of the
+ table in their declared order; or the first <em class="replaceable"><code>N</code></em> column
+ names, if there are only <em class="replaceable"><code>N</code></em> columns supplied by the
+ <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em>. The values
+ supplied by the <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em> are
+ associated with the explicit or implicit column list left-to-right.
+ </p><p>
+ Each column not present in the explicit or implicit column list will be
+ filled with a default value, either its declared default value
+ or null if there is none.
+ </p><p>
+ If the expression for any column is not of the correct data type,
+ automatic type conversion will be attempted.
+ </p><p>
+ <code class="command">INSERT</code> into tables that lack unique indexes will
+ not be blocked by concurrent activity. Tables with unique indexes
+ might block if concurrent sessions perform actions that lock or modify
+ rows matching the unique index values being inserted; the details
+ are covered in <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a>.
+ <code class="literal">ON CONFLICT</code> can be used to specify an alternative
+ action to raising a unique constraint or exclusion constraint
+ violation error. (See <a class="xref" href="sql-insert.html#SQL-ON-CONFLICT" title="ON CONFLICT Clause">ON CONFLICT Clause</a> below.)
+ </p><p>
+ The optional <code class="literal">RETURNING</code> clause causes <code class="command">INSERT</code>
+ to compute and return value(s) based on each row actually inserted
+ (or updated, if an <code class="literal">ON CONFLICT DO UPDATE</code> clause was
+ used). This is primarily useful for obtaining values that were
+ supplied by defaults, such as a serial sequence number. However,
+ any expression using the table's columns is allowed. The syntax of
+ the <code class="literal">RETURNING</code> list is identical to that of the output
+ list of <code class="command">SELECT</code>. Only rows that were successfully
+ inserted or updated will be returned. For example, if a row was
+ locked but not updated because an <code class="literal">ON CONFLICT DO UPDATE
+ ... WHERE</code> clause <em class="replaceable"><code>condition</code></em> was not satisfied, the
+ row will not be returned.
+ </p><p>
+ You must have <code class="literal">INSERT</code> privilege on a table in
+ order to insert into it. If <code class="literal">ON CONFLICT DO UPDATE</code> is
+ present, <code class="literal">UPDATE</code> privilege on the table is also
+ required.
+ </p><p>
+ If a column list is specified, you only need
+ <code class="literal">INSERT</code> privilege on the listed columns.
+ Similarly, when <code class="literal">ON CONFLICT DO UPDATE</code> is specified, you
+ only need <code class="literal">UPDATE</code> privilege on the column(s) that are
+ listed to be updated. However, <code class="literal">ON CONFLICT DO UPDATE</code>
+ also requires <code class="literal">SELECT</code> privilege on any column whose
+ values are read in the <code class="literal">ON CONFLICT DO UPDATE</code>
+ expressions or <em class="replaceable"><code>condition</code></em>.
+ </p><p>
+ Use of the <code class="literal">RETURNING</code> clause requires <code class="literal">SELECT</code>
+ privilege on all columns mentioned in <code class="literal">RETURNING</code>.
+ If you use the <em class="replaceable"><code>query</code></em> clause to insert rows from a
+ query, you of course need to have <code class="literal">SELECT</code> privilege on
+ any table or column used in the query.
+ </p></div><div class="refsect1" id="id-1.9.3.152.6"><h2>Parameters</h2><div class="refsect2" id="id-1.9.3.152.6.2"><h3>Inserting</h3><p>
+ This section covers parameters that may be used when only
+ inserting new rows. Parameters <span class="emphasis"><em>exclusively</em></span>
+ used with the <code class="literal">ON CONFLICT</code> clause are described
+ separately.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>
+ The <code class="literal">WITH</code> clause allows you to specify one or more
+ subqueries that can be referenced by name in the <code class="command">INSERT</code>
+ query. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> and <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ for details.
+ </p><p>
+ It is possible for the <em class="replaceable"><code>query</code></em>
+ (<code class="command">SELECT</code> statement)
+ to also contain a <code class="literal">WITH</code> clause. In such a case both
+ sets of <em class="replaceable"><code>with_query</code></em> can be referenced within
+ the <em class="replaceable"><code>query</code></em>, but the
+ second one takes precedence since it is more closely nested.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>
+ A substitute name for <em class="replaceable"><code>table_name</code></em>. When an alias is
+ provided, it completely hides the actual name of the table.
+ This is particularly useful when <code class="literal">ON CONFLICT DO UPDATE</code>
+ targets a table named <code class="varname">excluded</code>, since that will otherwise
+ be taken as the name of the special table representing the row proposed
+ for insertion.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column in the table named by <em class="replaceable"><code>table_name</code></em>. The column name
+ can be qualified with a subfield name or array subscript, if
+ needed. (Inserting into only some fields of a composite
+ column leaves the other fields null.) When referencing a
+ column with <code class="literal">ON CONFLICT DO UPDATE</code>, do not include
+ the table's name in the specification of a target column. For
+ example, <code class="literal">INSERT INTO table_name ... ON CONFLICT DO UPDATE
+ SET table_name.col = 1</code> is invalid (this follows the general
+ behavior for <code class="command">UPDATE</code>).
+ </p></dd><dt><span class="term"><code class="literal">OVERRIDING SYSTEM VALUE</code></span></dt><dd><p>
+ If this clause is specified, then any values supplied for identity
+ columns will override the default sequence-generated values.
+ </p><p>
+ For an identity column defined as <code class="literal">GENERATED ALWAYS</code>,
+ it is an error to insert an explicit value (other than
+ <code class="literal">DEFAULT</code>) without specifying either
+ <code class="literal">OVERRIDING SYSTEM VALUE</code> or <code class="literal">OVERRIDING USER
+ VALUE</code>. (For an identity column defined as
+ <code class="literal">GENERATED BY DEFAULT</code>, <code class="literal">OVERRIDING SYSTEM
+ VALUE</code> is the normal behavior and specifying it does nothing,
+ but <span class="productname">PostgreSQL</span> allows it as an extension.)
+ </p></dd><dt><span class="term"><code class="literal">OVERRIDING USER VALUE</code></span></dt><dd><p>
+ If this clause is specified, then any values supplied for identity
+ columns are ignored and the default sequence-generated values are
+ applied.
+ </p><p>
+ This clause is useful for example when copying values between tables.
+ Writing <code class="literal">INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM
+ tbl1</code> will copy from <code class="literal">tbl1</code> all columns that
+ are not identity columns in <code class="literal">tbl2</code> while values for
+ the identity columns in <code class="literal">tbl2</code> will be generated by
+ the sequences associated with <code class="literal">tbl2</code>.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT VALUES</code></span></dt><dd><p>
+ All columns will be filled with their default values, as if
+ <code class="literal">DEFAULT</code> were explicitly specified for each column.
+ (An <code class="literal">OVERRIDING</code> clause is not permitted in this
+ form.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ An expression or value to assign to the corresponding column.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ The corresponding column will be filled with its default value. An
+ identity column will be filled with a new value generated by the
+ associated sequence. For a generated column, specifying this is
+ permitted but merely specifies the normal behavior of computing the
+ column from its generation expression.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>
+ A query (<code class="command">SELECT</code> statement) that supplies the
+ rows to be inserted. Refer to the
+ <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ statement for a description of the syntax.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_expression</code></em></span></dt><dd><p>
+ An expression to be computed and returned by the
+ <code class="command">INSERT</code> command after each row is inserted or
+ updated. The expression can use any column names of the table
+ named by <em class="replaceable"><code>table_name</code></em>. Write
+ <code class="literal">*</code> to return all columns of the inserted or updated
+ row(s).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_name</code></em></span></dt><dd><p>
+ A name to use for a returned column.
+ </p></dd></dl></div></div><div class="refsect2" id="SQL-ON-CONFLICT"><h3><code class="literal">ON CONFLICT</code> Clause</h3><a id="id-1.9.3.152.6.3.2" class="indexterm"></a><a id="id-1.9.3.152.6.3.3" class="indexterm"></a><p>
+ The optional <code class="literal">ON CONFLICT</code> clause specifies an
+ alternative action to raising a unique violation or exclusion
+ constraint violation error. For each individual row proposed for
+ insertion, either the insertion proceeds, or, if an
+ <span class="emphasis"><em>arbiter</em></span> constraint or index specified by
+ <em class="parameter"><code>conflict_target</code></em> is violated, the
+ alternative <em class="parameter"><code>conflict_action</code></em> is taken.
+ <code class="literal">ON CONFLICT DO NOTHING</code> simply avoids inserting
+ a row as its alternative action. <code class="literal">ON CONFLICT DO
+ UPDATE</code> updates the existing row that conflicts with the
+ row proposed for insertion as its alternative action.
+ </p><p>
+ <em class="parameter"><code>conflict_target</code></em> can perform
+ <span class="emphasis"><em>unique index inference</em></span>. When performing
+ inference, it consists of one or more <em class="replaceable"><code>index_column_name</code></em> columns and/or
+ <em class="replaceable"><code>index_expression</code></em>
+ expressions, and an optional <em class="replaceable"><code>index_predicate</code></em>. All <em class="replaceable"><code>table_name</code></em> unique indexes that,
+ without regard to order, contain exactly the
+ <em class="parameter"><code>conflict_target</code></em>-specified
+ columns/expressions are inferred (chosen) as arbiter indexes. If
+ an <em class="replaceable"><code>index_predicate</code></em> is
+ specified, it must, as a further requirement for inference,
+ satisfy arbiter indexes. Note that this means a non-partial
+ unique index (a unique index without a predicate) will be inferred
+ (and thus used by <code class="literal">ON CONFLICT</code>) if such an index
+ satisfying every other criteria is available. If an attempt at
+ inference is unsuccessful, an error is raised.
+ </p><p>
+ <code class="literal">ON CONFLICT DO UPDATE</code> guarantees an atomic
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code> outcome;
+ provided there is no independent error, one of those two outcomes
+ is guaranteed, even under high concurrency. This is also known as
+ <em class="firstterm">UPSERT</em> — <span class="quote">“<span class="quote">UPDATE or
+ INSERT</span>”</span>.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>conflict_target</code></em></span></dt><dd><p>
+ Specifies which conflicts <code class="literal">ON CONFLICT</code> takes
+ the alternative action on by choosing <em class="firstterm">arbiter
+ indexes</em>. Either performs <span class="emphasis"><em>unique index
+ inference</em></span>, or names a constraint explicitly. For
+ <code class="literal">ON CONFLICT DO NOTHING</code>, it is optional to
+ specify a <em class="parameter"><code>conflict_target</code></em>; when
+ omitted, conflicts with all usable constraints (and unique
+ indexes) are handled. For <code class="literal">ON CONFLICT DO
+ UPDATE</code>, a <em class="parameter"><code>conflict_target</code></em>
+ <span class="emphasis"><em>must</em></span> be provided.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>conflict_action</code></em></span></dt><dd><p>
+ <em class="parameter"><code>conflict_action</code></em> specifies an
+ alternative <code class="literal">ON CONFLICT</code> action. It can be
+ either <code class="literal">DO NOTHING</code>, or a <code class="literal">DO
+ UPDATE</code> clause specifying the exact details of the
+ <code class="literal">UPDATE</code> action to be performed in case of a
+ conflict. The <code class="literal">SET</code> and
+ <code class="literal">WHERE</code> clauses in <code class="literal">ON CONFLICT DO
+ UPDATE</code> have access to the existing row using the
+ table's name (or an alias), and to the row proposed for insertion
+ using the special <code class="varname">excluded</code> table.
+ <code class="literal">SELECT</code> privilege is required on any column in the
+ target table where corresponding <code class="varname">excluded</code>
+ columns are read.
+ </p><p>
+ Note that the effects of all per-row <code class="literal">BEFORE
+ INSERT</code> triggers are reflected in
+ <code class="varname">excluded</code> values, since those effects may
+ have contributed to the row being excluded from insertion.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_column_name</code></em></span></dt><dd><p>
+ The name of a <em class="replaceable"><code>table_name</code></em> column. Used to
+ infer arbiter indexes. Follows <code class="command">CREATE
+ INDEX</code> format. <code class="literal">SELECT</code> privilege on
+ <em class="replaceable"><code>index_column_name</code></em>
+ is required.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_expression</code></em></span></dt><dd><p>
+ Similar to <em class="replaceable"><code>index_column_name</code></em>, but used to
+ infer expressions on <em class="replaceable"><code>table_name</code></em> columns appearing
+ within index definitions (not simple columns). Follows
+ <code class="command">CREATE INDEX</code> format. <code class="literal">SELECT</code>
+ privilege on any column appearing within <em class="replaceable"><code>index_expression</code></em> is required.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>collation</code></em></span></dt><dd><p>
+ When specified, mandates that corresponding <em class="replaceable"><code>index_column_name</code></em> or
+ <em class="replaceable"><code>index_expression</code></em>
+ use a particular collation in order to be matched during
+ inference. Typically this is omitted, as collations usually
+ do not affect whether or not a constraint violation occurs.
+ Follows <code class="command">CREATE INDEX</code> format.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>opclass</code></em></span></dt><dd><p>
+ When specified, mandates that corresponding <em class="replaceable"><code>index_column_name</code></em> or
+ <em class="replaceable"><code>index_expression</code></em>
+ use particular operator class in order to be matched during
+ inference. Typically this is omitted, as the
+ <span class="emphasis"><em>equality</em></span> semantics are often equivalent
+ across a type's operator classes anyway, or because it's
+ sufficient to trust that the defined unique indexes have the
+ pertinent definition of equality. Follows <code class="command">CREATE
+ INDEX</code> format.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>index_predicate</code></em></span></dt><dd><p>
+ Used to allow inference of partial unique indexes. Any
+ indexes that satisfy the predicate (which need not actually be
+ partial indexes) can be inferred. Follows <code class="command">CREATE
+ INDEX</code> format. <code class="literal">SELECT</code> privilege on any
+ column appearing within <em class="replaceable"><code>index_predicate</code></em> is required.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>
+ Explicitly specifies an arbiter
+ <span class="emphasis"><em>constraint</em></span> by name, rather than inferring
+ a constraint or index.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ An expression that returns a value of type
+ <code class="type">boolean</code>. Only rows for which this expression
+ returns <code class="literal">true</code> will be updated, although all
+ rows will be locked when the <code class="literal">ON CONFLICT DO UPDATE</code>
+ action is taken. Note that
+ <em class="replaceable"><code>condition</code></em> is evaluated last, after
+ a conflict has been identified as a candidate to update.
+ </p></dd></dl></div><p>
+ Note that exclusion constraints are not supported as arbiters with
+ <code class="literal">ON CONFLICT DO UPDATE</code>. In all cases, only
+ <code class="literal">NOT DEFERRABLE</code> constraints and unique indexes
+ are supported as arbiters.
+ </p><p>
+ <code class="command">INSERT</code> with an <code class="literal">ON CONFLICT DO UPDATE</code>
+ clause is a <span class="quote">“<span class="quote">deterministic</span>”</span> statement. This means
+ that the command will not be allowed to affect any single existing
+ row more than once; a cardinality violation error will be raised
+ when this situation arises. Rows proposed for insertion should
+ not duplicate each other in terms of attributes constrained by an
+ arbiter index or constraint.
+ </p><p>
+ Note that it is currently not supported for the
+ <code class="literal">ON CONFLICT DO UPDATE</code> clause of an
+ <code class="command">INSERT</code> applied to a partitioned table to update the
+ partition key of a conflicting row such that it requires the row be moved
+ to a new partition.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ It is often preferable to use unique index inference rather than
+ naming a constraint directly using <code class="literal">ON CONFLICT ON
+ CONSTRAINT</code> <em class="replaceable"><code>
+ constraint_name</code></em>. Inference will continue to work
+ correctly when the underlying index is replaced by another more
+ or less equivalent index in an overlapping way, for example when
+ using <code class="literal">CREATE UNIQUE INDEX ... CONCURRENTLY</code>
+ before dropping the index being replaced.
+ </p></div></div></div><div class="refsect1" id="id-1.9.3.152.7"><h2>Outputs</h2><p>
+ On successful completion, an <code class="command">INSERT</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+INSERT <em class="replaceable"><code>oid</code></em> <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number of
+ rows inserted or updated. <em class="replaceable"><code>oid</code></em> is always 0 (it
+ used to be the <acronym class="acronym">OID</acronym> assigned to the inserted row if
+ <em class="replaceable"><code>count</code></em> was exactly one and the target table was
+ declared <code class="literal">WITH OIDS</code> and 0 otherwise, but creating a table
+ <code class="literal">WITH OIDS</code> is not supported anymore).
+ </p><p>
+ If the <code class="command">INSERT</code> command contains a <code class="literal">RETURNING</code>
+ clause, the result will be similar to that of a <code class="command">SELECT</code>
+ statement containing the columns and values defined in the
+ <code class="literal">RETURNING</code> list, computed over the row(s) inserted or
+ updated by the command.
+ </p></div><div class="refsect1" id="id-1.9.3.152.8"><h2>Notes</h2><p>
+ If the specified table is a partitioned table, each row is routed to
+ the appropriate partition and inserted into it. If the specified table
+ is a partition, an error will occur if one of the input rows violates
+ the partition constraint.
+ </p><p>
+ You may also wish to consider using <code class="command">MERGE</code>, since that
+ allows mixing <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> within a single statement.
+ See <a class="xref" href="sql-merge.html" title="MERGE"><span class="refentrytitle">MERGE</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.152.9"><h2>Examples</h2><p>
+ Insert a single row into table <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+INSERT INTO films VALUES
+ ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
+</pre><p>
+ </p><p>
+ In this example, the <code class="literal">len</code> column is
+ omitted and therefore it will have the default value:
+
+</p><pre class="programlisting">
+INSERT INTO films (code, title, did, date_prod, kind)
+ VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
+</pre><p>
+ </p><p>
+ This example uses the <code class="literal">DEFAULT</code> clause for
+ the date columns rather than specifying a value:
+
+</p><pre class="programlisting">
+INSERT INTO films VALUES
+ ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
+INSERT INTO films (code, title, did, date_prod, kind)
+ VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');
+</pre><p>
+ </p><p>
+ To insert a row consisting entirely of default values:
+
+</p><pre class="programlisting">
+INSERT INTO films DEFAULT VALUES;
+</pre><p>
+ </p><p>
+ To insert multiple rows using the multirow <code class="command">VALUES</code> syntax:
+
+</p><pre class="programlisting">
+INSERT INTO films (code, title, did, date_prod, kind) VALUES
+ ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
+ ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');
+</pre><p>
+ </p><p>
+ This example inserts some rows into table
+ <code class="literal">films</code> from a table <code class="literal">tmp_films</code>
+ with the same column layout as <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+INSERT INTO films SELECT * FROM tmp_films WHERE date_prod &lt; '2004-05-07';
+</pre><p>
+ </p><p>
+ This example inserts into array columns:
+
+</p><pre class="programlisting">
+-- Create an empty 3x3 gameboard for noughts-and-crosses
+INSERT INTO tictactoe (game, board[1:3][1:3])
+ VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
+-- The subscripts in the above example aren't really needed
+INSERT INTO tictactoe (game, board)
+ VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');
+</pre><p>
+ </p><p>
+ Insert a single row into table <code class="literal">distributors</code>, returning
+ the sequence number generated by the <code class="literal">DEFAULT</code> clause:
+
+</p><pre class="programlisting">
+INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
+ RETURNING did;
+</pre><p>
+ </p><p>
+ Increment the sales count of the salesperson who manages the
+ account for Acme Corporation, and record the whole updated row
+ along with current time in a log table:
+</p><pre class="programlisting">
+WITH upd AS (
+ UPDATE employees SET sales_count = sales_count + 1 WHERE id =
+ (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
+ RETURNING *
+)
+INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
+</pre><p>
+ </p><p>
+ Insert or update new distributors as appropriate. Assumes a unique
+ index has been defined that constrains values appearing in the
+ <code class="literal">did</code> column. Note that the special
+ <code class="varname">excluded</code> table is used to reference values originally
+ proposed for insertion:
+</p><pre class="programlisting">
+INSERT INTO distributors (did, dname)
+ VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
+ ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;
+</pre><p>
+ </p><p>
+ Insert a distributor, or do nothing for rows proposed for insertion
+ when an existing, excluded row (a row with a matching constrained
+ column or columns after before row insert triggers fire) exists.
+ Example assumes a unique index has been defined that constrains
+ values appearing in the <code class="literal">did</code> column:
+</p><pre class="programlisting">
+INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH')
+ ON CONFLICT (did) DO NOTHING;
+</pre><p>
+ </p><p>
+ Insert or update new distributors as appropriate. Example assumes
+ a unique index has been defined that constrains values appearing in
+ the <code class="literal">did</code> column. <code class="literal">WHERE</code> clause is
+ used to limit the rows actually updated (any existing row not
+ updated will still be locked, though):
+</p><pre class="programlisting">
+-- Don't update existing distributors based in a certain ZIP code
+INSERT INTO distributors AS d (did, dname) VALUES (8, 'Anvil Distribution')
+ ON CONFLICT (did) DO UPDATE
+ SET dname = EXCLUDED.dname || ' (formerly ' || d.dname || ')'
+ WHERE d.zipcode &lt;&gt; '21201';
+
+-- Name a constraint directly in the statement (uses associated
+-- index to arbitrate taking the DO NOTHING action)
+INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
+ ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;
+</pre><p>
+ </p><p>
+ Insert new distributor if possible; otherwise
+ <code class="literal">DO NOTHING</code>. Example assumes a unique index has been
+ defined that constrains values appearing in the
+ <code class="literal">did</code> column on a subset of rows where the
+ <code class="literal">is_active</code> Boolean column evaluates to
+ <code class="literal">true</code>:
+</p><pre class="programlisting">
+-- This statement could infer a partial unique index on "did"
+-- with a predicate of "WHERE is_active", but it could also
+-- just use a regular unique constraint on "did"
+INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
+ ON CONFLICT (did) WHERE is_active DO NOTHING;
+</pre></div><div class="refsect1" id="id-1.9.3.152.10"><h2>Compatibility</h2><p>
+ <code class="command">INSERT</code> conforms to the SQL standard, except that
+ the <code class="literal">RETURNING</code> clause is a
+ <span class="productname">PostgreSQL</span> extension, as is the ability
+ to use <code class="literal">WITH</code> with <code class="command">INSERT</code>, and the ability to
+ specify an alternative action with <code class="literal">ON CONFLICT</code>.
+ Also, the case in
+ which a column name list is omitted, but not all the columns are
+ filled from the <code class="literal">VALUES</code> clause or <em class="replaceable"><code>query</code></em>,
+ is disallowed by the standard. If you prefer a more SQL standard
+ conforming statement than <code class="literal">ON CONFLICT</code>, see
+ <a class="xref" href="sql-merge.html" title="MERGE"><span class="refentrytitle">MERGE</span></a>.
+ </p><p>
+ The SQL standard specifies that <code class="literal">OVERRIDING SYSTEM VALUE</code>
+ can only be specified if an identity column that is generated always
+ exists. PostgreSQL allows the clause in any case and ignores it if it is
+ not applicable.
+ </p><p>
+ Possible limitations of the <em class="replaceable"><code>query</code></em> clause are documented under
+ <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-listen.html" title="LISTEN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">IMPORT FOREIGN SCHEMA </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> LISTEN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-keywords-appendix.html b/doc/src/sgml/html/sql-keywords-appendix.html
new file mode 100644
index 0000000..742b82c
--- /dev/null
+++ b/doc/src/sgml/html/sql-keywords-appendix.html
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix C. SQL Key Words</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-julian-dates.html" title="B.7. Julian Dates" /><link rel="next" href="features.html" title="Appendix D. SQL Conformance" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Appendix C. <acronym class="acronym">SQL</acronym> Key Words</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-julian-dates.html" title="B.7. Julian Dates">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><th width="60%" align="center">Part VIII. Appendixes</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="features.html" title="Appendix D. SQL Conformance">Next</a></td></tr></table><hr /></div><div class="appendix" id="SQL-KEYWORDS-APPENDIX"><div class="titlepage"><div><div><h2 class="title">Appendix C. <acronym class="acronym">SQL</acronym> Key Words</h2></div></div></div><a id="id-1.11.4.2" class="indexterm"></a><p>
+ <a class="xref" href="sql-keywords-appendix.html#KEYWORDS-TABLE" title="Table C.1. SQL Key Words">Table C.1</a> lists all tokens that are key words
+ in the SQL standard and in <span class="productname">PostgreSQL</span>
+ 15.5. Background information can be found in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS" title="4.1.1. Identifiers and Key Words">Section 4.1.1</a>.
+ (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.)
+ </p><p>
+ SQL distinguishes between <em class="firstterm">reserved</em> and
+ <em class="firstterm">non-reserved</em> key words. According to the standard,
+ reserved key words
+ are the only real key words; they are never allowed as identifiers.
+ Non-reserved key words only have a special meaning in particular
+ contexts and can be used as identifiers in other contexts. Most
+ non-reserved key words are actually the names of built-in tables
+ and functions specified by SQL. The concept of non-reserved key
+ words essentially only exists to declare that some predefined meaning
+ is attached to a word in some contexts.
+ </p><p>
+ In the <span class="productname">PostgreSQL</span> parser, life is a bit
+ more complicated. There are several different classes of tokens
+ ranging from those that can never be used as an identifier to those
+ that have absolutely no special status in the parser, but are considered
+ ordinary identifiers. (The latter is usually the case for
+ functions specified by SQL.) Even reserved key words are not
+ completely reserved in <span class="productname">PostgreSQL</span>, but
+ can be used as column labels (for example, <code class="literal">SELECT 55 AS
+ CHECK</code>, even though <code class="token">CHECK</code> is a reserved key
+ word).
+ </p><p>
+ In <a class="xref" href="sql-keywords-appendix.html#KEYWORDS-TABLE" title="Table C.1. SQL Key Words">Table C.1</a> in the column for
+ <span class="productname">PostgreSQL</span> we classify as
+ <span class="quote">“<span class="quote">non-reserved</span>”</span> those key words that are explicitly
+ known to the parser but are allowed as column or table names.
+ Some key words that are otherwise
+ non-reserved cannot be used as function or data type names and are
+ marked accordingly. (Most of these words represent built-in
+ functions or data types with special syntax. The function or type
+ is still available but it cannot be redefined by the user.) Labeled
+ <span class="quote">“<span class="quote">reserved</span>”</span> are those tokens that are not allowed as
+ column or table names. Some reserved key words are
+ allowable as names for functions or data types; this is also shown in the
+ table. If not so marked, a reserved key word is only allowed as a
+ column label.
+ A blank entry in this column means that the word is treated as an
+ ordinary identifier by <span class="productname">PostgreSQL</span>.
+ </p><p>
+ Furthermore, while most key words can be used as <span class="quote">“<span class="quote">bare</span>”</span>
+ column labels without writing <code class="literal">AS</code> before them (as
+ described in <a class="xref" href="queries-select-lists.html#QUERIES-COLUMN-LABELS" title="7.3.2. Column Labels">Section 7.3.2</a>), there are a few
+ that require a leading <code class="literal">AS</code> to avoid ambiguity. These
+ are marked in the table as <span class="quote">“<span class="quote">requires <code class="literal">AS</code></span>”</span>.
+ </p><p>
+ As a general rule, if you get spurious parser errors for commands
+ that use any of the listed key words as an identifier, you should
+ try quoting the identifier to see if the problem goes away.
+ </p><p>
+ It is important to understand before studying <a class="xref" href="sql-keywords-appendix.html#KEYWORDS-TABLE" title="Table C.1. SQL Key Words">Table C.1</a> that the fact that a key word is not
+ reserved in <span class="productname">PostgreSQL</span> 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.
+ </p><div class="table" id="KEYWORDS-TABLE"><p class="title"><strong>Table C.1. <acronym class="acronym">SQL</acronym> Key Words</strong></p><div class="table-contents"><table class="table" summary="SQL Key Words" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>Key Word</th><th><span class="productname">PostgreSQL</span></th><th>SQL:2016</th><th>SQL:2011</th><th>SQL-92</th></tr></thead><tbody><tr><td><code class="token">A</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ABORT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ABS</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ABSENT</code></td><td> </td><td>reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ABSOLUTE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">ACCESS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ACCORDING</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ACOS</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ACTION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">ADA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">ADD</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">ADMIN</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">AFTER</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">AGGREGATE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ALL</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ALLOCATE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ALSO</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ALTER</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ALWAYS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ANALYSE</code></td><td>reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ANALYZE</code></td><td>reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">AND</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ANY</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ARE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ARRAY</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ARRAY_AGG</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ARRAY_​MAX_​CARDINALITY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">AS</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ASC</code></td><td>reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">ASENSITIVE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ASIN</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ASSERTION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">ASSIGNMENT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ASYMMETRIC</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">AT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ATAN</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ATOMIC</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ATTACH</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ATTRIBUTE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ATTRIBUTES</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">AUTHORIZATION</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">AVG</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">BACKWARD</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">BASE64</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BEFORE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BEGIN</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">BEGIN_FRAME</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BEGIN_PARTITION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BERNOULLI</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BETWEEN</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">BIGINT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BINARY</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BIT</code></td><td>non-reserved (cannot be function or type)</td><td> </td><td> </td><td>reserved</td></tr><tr><td><code class="token">BIT_LENGTH</code></td><td> </td><td> </td><td> </td><td>reserved</td></tr><tr><td><code class="token">BLOB</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BLOCKED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BOM</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BOOLEAN</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">BOTH</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">BREADTH</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">BY</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">C</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CACHE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CALL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CALLED</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CARDINALITY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CASCADE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">CASCADED</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CASE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CAST</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CATALOG</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">CATALOG_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CEIL</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CEILING</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CHAIN</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CHAINING</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">CHAR</code></td><td>non-reserved (cannot be function or type), requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CHARACTER</code></td><td>non-reserved (cannot be function or type), requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CHARACTERISTICS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CHARACTERS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CHARACTER_LENGTH</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CHARACTER_​SET_​CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CHARACTER_SET_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CHARACTER_SET_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CHAR_LENGTH</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CHECK</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CHECKPOINT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CLASS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CLASSIFIER</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">CLASS_ORIGIN</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CLOB</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CLOSE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CLUSTER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">COALESCE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COBOL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COLLATE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COLLATION</code></td><td>reserved (can be function or type)</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">COLLATION_CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COLLATION_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COLLATION_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COLLECT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">COLUMN</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COLUMNS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">COLUMN_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COMMAND_FUNCTION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COMMAND_​FUNCTION_​CODE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">COMMENT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">COMMENTS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">COMMIT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COMMITTED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">COMPRESSION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CONCURRENTLY</code></td><td>reserved (can be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CONDITION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CONDITIONAL</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">CONDITION_NUMBER</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CONFIGURATION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CONFLICT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CONNECT</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CONNECTION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">CONNECTION_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CONSTRAINT</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CONSTRAINTS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">CONSTRAINT_CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CONSTRAINT_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CONSTRAINT_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CONSTRUCTOR</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CONTAINS</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CONTENT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CONTINUE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">CONTROL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">CONVERSION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CONVERT</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COPY</code></td><td>non-reserved</td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">CORR</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CORRESPONDING</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COS</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">COSH</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">COST</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">COUNT</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">COVAR_POP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">COVAR_SAMP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CREATE</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CROSS</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CSV</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">CUBE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CUME_DIST</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURRENT_CATALOG</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_DATE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURRENT_​DEFAULT_​TRANSFORM_​GROUP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_PATH</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_ROLE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_ROW</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_SCHEMA</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_TIME</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURRENT_TIMESTAMP</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURRENT_​TRANSFORM_​GROUP_​FOR_​TYPE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">CURRENT_USER</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURSOR</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">CURSOR_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">CYCLE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DATA</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">DATABASE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DATALINK</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DATE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DATETIME_​INTERVAL_​CODE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">DATETIME_​INTERVAL_​PRECISION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">DAY</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DB</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DEALLOCATE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DEC</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DECFLOAT</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">DECIMAL</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DECLARE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DEFAULT</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DEFAULTS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DEFERRABLE</code></td><td>reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DEFERRED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DEFINE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">DEFINED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DEFINER</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DEGREE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DELETE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DELIMITER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DELIMITERS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DENSE_RANK</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DEPENDS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DEPTH</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DEREF</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DERIVED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DESC</code></td><td>reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DESCRIBE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DESCRIPTOR</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DETACH</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DETERMINISTIC</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DIAGNOSTICS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DICTIONARY</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DISABLE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DISCARD</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DISCONNECT</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DISPATCH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DISTINCT</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DLNEWCOPY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLPREVIOUSCOPY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLCOMPLETE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLCOMPLETEONLY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLCOMPLETEWRITE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLPATH</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLPATHONLY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLPATHWRITE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLSCHEME</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLURLSERVER</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DLVALUE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DO</code></td><td>reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">DOCUMENT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">DOMAIN</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">DOUBLE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DROP</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">DYNAMIC</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">DYNAMIC_FUNCTION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">DYNAMIC_​FUNCTION_​CODE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">EACH</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ELEMENT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ELSE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EMPTY</code></td><td> </td><td>reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ENABLE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ENCODING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ENCRYPTED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">END</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">END-EXEC</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">END_FRAME</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">END_PARTITION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ENFORCED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ENUM</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">EQUALS</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ERROR</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ESCAPE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EVENT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">EVERY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">EXCEPT</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EXCEPTION</code></td><td> </td><td> </td><td> </td><td>reserved</td></tr><tr><td><code class="token">EXCLUDE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">EXCLUDING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">EXCLUSIVE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">EXEC</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EXECUTE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EXISTS</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EXP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">EXPLAIN</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">EXPRESSION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">EXTENSION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">EXTERNAL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">EXTRACT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FALSE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FAMILY</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FETCH</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FILE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">FILTER</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FINAL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">FINALIZE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FINISH</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">FIRST</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">FIRST_VALUE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FLAG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">FLOAT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FLOOR</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FOLLOWING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">FOR</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FORCE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FOREIGN</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FORMAT</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">FORTRAN</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">FORWARD</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FOUND</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">FRAME_ROW</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FREE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FREEZE</code></td><td>reserved (can be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FROM</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">FULFILL</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">FULL</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">FUNCTION</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">FUNCTIONS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">FUSION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">G</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">GENERAL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">GENERATED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">GET</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">GLOBAL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">GO</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">GOTO</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">GRANT</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">GRANTED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">GREATEST</code></td><td>non-reserved (cannot be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">GROUP</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">GROUPING</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">GROUPS</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">HANDLER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">HAVING</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">HEADER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">HEX</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">HIERARCHY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">HOLD</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">HOUR</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ID</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">IDENTITY</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">IF</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">IGNORE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ILIKE</code></td><td>reserved (can be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">IMMEDIATE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">IMMEDIATELY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">IMMUTABLE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">IMPLEMENTATION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">IMPLICIT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">IMPORT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">IN</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INCLUDE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INCLUDING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INCREMENT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INDENT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INDEX</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INDEXES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INDICATOR</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INHERIT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INHERITS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INITIAL</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">INITIALLY</code></td><td>reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">INLINE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">INNER</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INOUT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">INPUT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">INSENSITIVE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INSERT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INSTANCE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INSTANTIABLE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INSTEAD</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INTEGER</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INTEGRITY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">INTERSECT</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INTERSECTION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">INTERVAL</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INTO</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">INVOKER</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">IS</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ISNULL</code></td><td>reserved (can be function or type), requires <code class="literal">AS</code></td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ISOLATION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">JOIN</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">JSON_ARRAY</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_ARRAYAGG</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_EXISTS</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_OBJECT</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_OBJECTAGG</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_QUERY</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_TABLE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_TABLE_PRIMITIVE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">JSON_VALUE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">K</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">KEEP</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">KEY</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">KEYS</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">KEY_MEMBER</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">KEY_TYPE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LABEL</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LAG</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LANGUAGE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">LARGE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LAST</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">LAST_VALUE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LATERAL</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LEAD</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LEADING</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">LEAKPROOF</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LEAST</code></td><td>non-reserved (cannot be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LEFT</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">LENGTH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">LEVEL</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">LIBRARY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LIKE</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">LIKE_REGEX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LIMIT</code></td><td>reserved, requires <code class="literal">AS</code></td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LINK</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LISTAGG</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">LISTEN</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LN</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LOAD</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LOCAL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">LOCALTIME</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LOCALTIMESTAMP</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">LOCATION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LOCATOR</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">LOCK</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LOCKED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LOG</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">LOG10</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">LOGGED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">LOWER</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">M</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MAP</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MAPPING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MATCH</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MATCHED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MATCHES</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">MATCH_NUMBER</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">MATCH_RECOGNIZE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">MATERIALIZED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">MAX</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MAXVALUE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MEASURES</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">MEMBER</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MERGE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MESSAGE_LENGTH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">MESSAGE_OCTET_LENGTH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">MESSAGE_TEXT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">METHOD</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MIN</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MINUTE</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MINVALUE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">MOD</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MODE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">MODIFIES</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MODULE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MONTH</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">MORE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">MOVE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">MULTISET</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">MUMPS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">NAME</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">NAMES</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">NAMESPACE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NATIONAL</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NATURAL</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NCHAR</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NCLOB</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NESTED</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">NESTING</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NEW</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NEXT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">NFC</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NFD</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NFKC</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NFKD</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NIL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NO</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NONE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NORMALIZE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NORMALIZED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NOT</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NOTHING</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">NOTIFY</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">NOTNULL</code></td><td>reserved (can be function or type), requires <code class="literal">AS</code></td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">NOWAIT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">NTH_VALUE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NTILE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">NULL</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NULLABLE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">NULLIF</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">NULLS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">NULL_ORDERING</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">NUMBER</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">NUMERIC</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OBJECT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OCCURRENCE</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">OCCURRENCES_REGEX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OCTETS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OCTET_LENGTH</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OF</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OFF</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OFFSET</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OIDS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">OLD</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OMIT</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ON</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ONE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">ONLY</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OPEN</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OPERATOR</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">OPTION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">OPTIONS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OR</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ORDER</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ORDERING</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ORDINALITY</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OTHERS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OUT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OUTER</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OUTPUT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">OVER</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OVERFLOW</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">OVERLAPS</code></td><td>reserved (can be function or type), requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">OVERLAY</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">OVERRIDING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">OWNED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">OWNER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">P</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PAD</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PARALLEL</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PARAMETER</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_MODE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_​ORDINAL_​POSITION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_​SPECIFIC_​CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_​SPECIFIC_​NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARAMETER_​SPECIFIC_​SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PARSER</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PARTIAL</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PARTITION</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PASCAL</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">PASS</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PASSING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PASSTHROUGH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PASSWORD</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PAST</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PATH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PATTERN</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PER</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PERCENT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PERCENTILE_CONT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PERCENTILE_DISC</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PERCENT_RANK</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PERIOD</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PERMISSION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PERMUTE</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PIPE</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PLACING</code></td><td>reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PLAN</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PLANS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PLI</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">POLICY</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PORTION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">POSITION</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">POSITION_REGEX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">POWER</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PRECEDES</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">PRECEDING</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">PRECISION</code></td><td>non-reserved (cannot be function or type), requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">PREPARE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">PREPARED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PRESERVE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PREV</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PRIMARY</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">PRIOR</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PRIVATE</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PRIVILEGES</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PROCEDURAL</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PROCEDURE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">PROCEDURES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PROGRAM</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">PRUNE</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PTF</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">PUBLIC</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">PUBLICATION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">QUOTE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">QUOTES</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">RANGE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">RANK</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">READ</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">READS</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REAL</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">REASSIGN</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">RECHECK</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">RECOVERY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RECURSIVE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REF</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REFERENCES</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">REFERENCING</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REFRESH</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">REGR_AVGX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_AVGY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_COUNT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_INTERCEPT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_R2</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_SLOPE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_SXX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_SXY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REGR_SYY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REINDEX</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">RELATIVE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">RELEASE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">RENAME</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">REPEATABLE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">REPLACE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">REPLICA</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">REQUIRING</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RESET</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">RESPECT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RESTART</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RESTORE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RESTRICT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">RESULT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">RETURN</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">RETURNED_CARDINALITY</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RETURNED_LENGTH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">RETURNED_​OCTET_​LENGTH</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">RETURNED_SQLSTATE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">RETURNING</code></td><td>reserved, requires <code class="literal">AS</code></td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">RETURNS</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">REVOKE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">RIGHT</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ROLE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ROLLBACK</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ROLLUP</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ROUTINE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ROUTINES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">ROUTINE_CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ROUTINE_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ROUTINE_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ROW</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">ROWS</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">ROW_COUNT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">ROW_NUMBER</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">RULE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">RUNNING</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SAVEPOINT</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SCALAR</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SCALE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">SCHEMA</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">SCHEMAS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SCHEMA_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">SCOPE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SCOPE_CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SCOPE_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SCOPE_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SCROLL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SEARCH</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SECOND</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SECTION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">SECURITY</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SEEK</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SELECT</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SELECTIVE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SELF</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SEMANTICS</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SENSITIVE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SEQUENCE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SEQUENCES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SERIALIZABLE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">SERVER</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SERVER_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">SESSION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">SESSION_USER</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SET</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SETOF</code></td><td>non-reserved (cannot be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SETS</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SHARE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SHOW</code></td><td>non-reserved</td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SIMILAR</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SIMPLE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SIN</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SINH</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SIZE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">SKIP</code></td><td>non-reserved</td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SMALLINT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SNAPSHOT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SOME</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SORT_DIRECTION</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SOURCE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SPACE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">SPECIFIC</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SPECIFICTYPE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SPECIFIC_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SQL</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SQLCODE</code></td><td> </td><td> </td><td> </td><td>reserved</td></tr><tr><td><code class="token">SQLERROR</code></td><td> </td><td> </td><td> </td><td>reserved</td></tr><tr><td><code class="token">SQLEXCEPTION</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SQLSTATE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SQLWARNING</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SQRT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">STABLE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STANDALONE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">START</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">STATE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">STATEMENT</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">STATIC</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">STATISTICS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STDDEV_POP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">STDDEV_SAMP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">STDIN</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STDOUT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STORAGE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STORED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STRICT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">STRING</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">STRIP</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">STRUCTURE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">STYLE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">SUBCLASS_ORIGIN</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">SUBMULTISET</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SUBSCRIPTION</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SUBSET</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">SUBSTRING</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SUBSTRING_REGEX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SUCCEEDS</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SUM</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">SUPPORT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SYMMETRIC</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SYSID</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">SYSTEM</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SYSTEM_TIME</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">SYSTEM_USER</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">T</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TABLE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TABLES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">TABLESAMPLE</code></td><td>reserved (can be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TABLESPACE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">TABLE_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">TAN</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">TANH</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">TEMP</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">TEMPLATE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">TEMPORARY</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">TEXT</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">THEN</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">THROUGH</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">TIES</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TIME</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TIMESTAMP</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TIMEZONE_HOUR</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TIMEZONE_MINUTE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TO</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TOKEN</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TOP_LEVEL_COUNT</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRAILING</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TRANSACTION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">TRANSACTIONS_​COMMITTED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRANSACTIONS_​ROLLED_​BACK</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRANSACTION_ACTIVE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRANSFORM</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRANSFORMS</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRANSLATE</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TRANSLATE_REGEX</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TRANSLATION</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TREAT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TRIGGER</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TRIGGER_CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRIGGER_NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRIGGER_SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">TRIM</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TRIM_ARRAY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TRUE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">TRUNCATE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">TRUSTED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">TYPE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">TYPES</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">UESCAPE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">UNBOUNDED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">UNCOMMITTED</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">UNCONDITIONAL</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">UNDER</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">UNENCRYPTED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">UNION</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">UNIQUE</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">UNKNOWN</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">UNLINK</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">UNLISTEN</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">UNLOGGED</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">UNMATCHED</code></td><td> </td><td>reserved</td><td> </td><td> </td></tr><tr><td><code class="token">UNNAMED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td></tr><tr><td><code class="token">UNNEST</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">UNTIL</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">UNTYPED</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">UPDATE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">UPPER</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">URI</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">USAGE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">USER</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">USER_​DEFINED_​TYPE_​CATALOG</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">USER_​DEFINED_​TYPE_​CODE</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">USER_​DEFINED_​TYPE_​NAME</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">USER_​DEFINED_​TYPE_​SCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">USING</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">UTF16</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">UTF32</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">UTF8</code></td><td> </td><td>non-reserved</td><td> </td><td> </td></tr><tr><td><code class="token">VACUUM</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VALID</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">VALIDATE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VALIDATOR</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VALUE</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">VALUES</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">VALUE_OF</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">VARBINARY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">VARCHAR</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">VARIADIC</code></td><td>reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VARYING</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">VAR_POP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">VAR_SAMP</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">VERBOSE</code></td><td>reserved (can be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VERSION</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">VERSIONING</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">VIEW</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">VIEWS</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">VOLATILE</code></td><td>non-reserved</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">WHEN</code></td><td>reserved</td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">WHENEVER</code></td><td> </td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">WHERE</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">WHITESPACE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">WIDTH_BUCKET</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">WINDOW</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">WITH</code></td><td>reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">WITHIN</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">WITHOUT</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">WORK</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">WRAPPER</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">WRITE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr><tr><td><code class="token">XML</code></td><td>non-reserved</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLAGG</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLATTRIBUTES</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLBINARY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLCAST</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLCOMMENT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLCONCAT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLDECLARATION</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">XMLDOCUMENT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLELEMENT</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLEXISTS</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLFOREST</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLITERATE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLNAMESPACES</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLPARSE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLPI</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLQUERY</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLROOT</code></td><td>non-reserved (cannot be function or type)</td><td> </td><td> </td><td> </td></tr><tr><td><code class="token">XMLSCHEMA</code></td><td> </td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">XMLSERIALIZE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLTABLE</code></td><td>non-reserved (cannot be function or type)</td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLTEXT</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">XMLVALIDATE</code></td><td> </td><td>reserved</td><td>reserved</td><td> </td></tr><tr><td><code class="token">YEAR</code></td><td>non-reserved, requires <code class="literal">AS</code></td><td>reserved</td><td>reserved</td><td>reserved</td></tr><tr><td><code class="token">YES</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td> </td></tr><tr><td><code class="token">ZONE</code></td><td>non-reserved</td><td>non-reserved</td><td>non-reserved</td><td>reserved</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-julian-dates.html" title="B.7. Julian Dates">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendixes.html" title="Part VIII. Appendixes">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="features.html" title="Appendix D. SQL Conformance">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.7. Julian Dates </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix D. SQL Conformance</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-listen.html b/doc/src/sgml/html/sql-listen.html
new file mode 100644
index 0000000..9a61760
--- /dev/null
+++ b/doc/src/sgml/html/sql-listen.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>LISTEN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-insert.html" title="INSERT" /><link rel="next" href="sql-load.html" title="LOAD" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">LISTEN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-insert.html" title="INSERT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-load.html" title="LOAD">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-LISTEN"><div class="titlepage"></div><a id="id-1.9.3.153.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">LISTEN</span></h2><p>LISTEN — listen for a notification</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+LISTEN <em class="replaceable"><code>channel</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.153.5"><h2>Description</h2><p>
+ <code class="command">LISTEN</code> registers the current session as a
+ listener on the notification channel named <em class="replaceable"><code>channel</code></em>.
+ If the current session is already registered as a listener for
+ this notification channel, nothing is done.
+ </p><p>
+ Whenever the command <code class="command">NOTIFY <em class="replaceable"><code>channel</code></em></code> is invoked, either
+ by this session or another one connected to the same database, all
+ the sessions currently listening on that notification channel are
+ notified, and each will in turn notify its connected client
+ application.
+ </p><p>
+ A session can be unregistered for a given notification channel with the
+ <code class="command">UNLISTEN</code> command. A session's listen
+ registrations are automatically cleared when the session ends.
+ </p><p>
+ The method a client application must use to detect notification events depends on
+ which <span class="productname">PostgreSQL</span> application programming interface it
+ uses. With the <span class="application">libpq</span> library, the application issues
+ <code class="command">LISTEN</code> as an ordinary SQL command, and then must
+ periodically call the function <code class="function">PQnotifies</code> to find out
+ whether any notification events have been received. Other interfaces such as
+ <span class="application">libpgtcl</span> provide higher-level methods for handling notify events; indeed,
+ with <span class="application">libpgtcl</span> the application programmer should not even issue
+ <code class="command">LISTEN</code> or <code class="command">UNLISTEN</code> directly. See the
+ documentation for the interface you are using for more details.
+ </p></div><div class="refsect1" id="id-1.9.3.153.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>channel</code></em></span></dt><dd><p>
+ Name of a notification channel (any identifier).
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.153.7"><h2>Notes</h2><p>
+ <code class="command">LISTEN</code> takes effect at transaction commit.
+ If <code class="command">LISTEN</code> or <code class="command">UNLISTEN</code> is executed
+ within a transaction that later rolls back, the set of notification
+ channels being listened to is unchanged.
+ </p><p>
+ A transaction that has executed <code class="command">LISTEN</code> cannot be
+ prepared for two-phase commit.
+ </p><p>
+ There is a race condition when first setting up a listening session:
+ if concurrently-committing transactions are sending notify events,
+ exactly which of those will the newly listening session receive?
+ The answer is that the session will receive all events committed after
+ an instant during the transaction's commit step. But that is slightly
+ later than any database state that the transaction could have observed
+ in queries. This leads to the following rule for
+ using <code class="command">LISTEN</code>: first execute (and commit!) that
+ command, then in a new transaction inspect the database state as needed
+ by the application logic, then rely on notifications to find out about
+ subsequent changes to the database state. The first few received
+ notifications might refer to updates already observed in the initial
+ database inspection, but this is usually harmless.
+ </p><p>
+ <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>
+ contains a more extensive
+ discussion of the use of <code class="command">LISTEN</code> and
+ <code class="command">NOTIFY</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.153.8"><h2>Examples</h2><p>
+ Configure and execute a listen/notify sequence from
+ <span class="application">psql</span>:
+
+</p><pre class="programlisting">
+LISTEN virtual;
+NOTIFY virtual;
+Asynchronous notification "virtual" received from server process with PID 8448.
+</pre></div><div class="refsect1" id="id-1.9.3.153.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">LISTEN</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.153.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>, <a class="xref" href="sql-unlisten.html" title="UNLISTEN"><span class="refentrytitle">UNLISTEN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-insert.html" title="INSERT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-load.html" title="LOAD">Next</a></td></tr><tr><td width="40%" align="left" valign="top">INSERT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> LOAD</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-load.html b/doc/src/sgml/html/sql-load.html
new file mode 100644
index 0000000..2fa608a
--- /dev/null
+++ b/doc/src/sgml/html/sql-load.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>LOAD</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-listen.html" title="LISTEN" /><link rel="next" href="sql-lock.html" title="LOCK" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">LOAD</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-listen.html" title="LISTEN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-lock.html" title="LOCK">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-LOAD"><div class="titlepage"></div><a id="id-1.9.3.154.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">LOAD</span></h2><p>LOAD — load a shared library file</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+LOAD '<em class="replaceable"><code>filename</code></em>'
+</pre></div><div class="refsect1" id="SQL-LOAD-DESCRIPTION"><h2>Description</h2><p>
+ This command loads a shared library file into the <span class="productname">PostgreSQL</span>
+ server's address space. If the file has been loaded already,
+ the command does nothing. Shared library files that contain C functions
+ are automatically loaded whenever one of their functions is called.
+ Therefore, an explicit <code class="command">LOAD</code> is usually only needed to
+ load a library that modifies the server's behavior through <span class="quote">“<span class="quote">hooks</span>”</span>
+ rather than providing a set of functions.
+ </p><p>
+ The library file name is typically given as just a bare file name,
+ which is sought in the server's library search path (set
+ by <a class="xref" href="runtime-config-client.html#GUC-DYNAMIC-LIBRARY-PATH">dynamic_library_path</a>). Alternatively it can be
+ given as a full path name. In either case the platform's standard shared
+ library file name extension may be omitted.
+ See <a class="xref" href="xfunc-c.html#XFUNC-C-DYNLOAD" title="38.10.1. Dynamic Loading">Section 38.10.1</a> for more information on this topic.
+ </p><a id="id-1.9.3.154.5.4" class="indexterm"></a><p>
+ Non-superusers can only apply <code class="command">LOAD</code> to library files
+ located in <code class="filename">$libdir/plugins/</code> — the specified
+ <em class="replaceable"><code>filename</code></em> must begin
+ with exactly that string. (It is the database administrator's
+ responsibility to ensure that only <span class="quote">“<span class="quote">safe</span>”</span> libraries
+ are installed there.)
+ </p></div><div class="refsect1" id="SQL-LOAD-COMPAT"><h2>Compatibility</h2><p>
+ <code class="command">LOAD</code> is a <span class="productname">PostgreSQL</span>
+ extension.
+ </p></div><div class="refsect1" id="id-1.9.3.154.7"><h2>See Also</h2><p>
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-listen.html" title="LISTEN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-lock.html" title="LOCK">Next</a></td></tr><tr><td width="40%" align="left" valign="top">LISTEN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> LOCK</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-lock.html b/doc/src/sgml/html/sql-lock.html
new file mode 100644
index 0000000..b7e76ab
--- /dev/null
+++ b/doc/src/sgml/html/sql-lock.html
@@ -0,0 +1,167 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>LOCK</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-load.html" title="LOAD" /><link rel="next" href="sql-merge.html" title="MERGE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">LOCK</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-load.html" title="LOAD">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-merge.html" title="MERGE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-LOCK"><div class="titlepage"></div><a id="id-1.9.3.155.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">LOCK</span></h2><p>LOCK — lock a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+LOCK [ TABLE ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ] [, ...] [ IN <em class="replaceable"><code>lockmode</code></em> MODE ] [ NOWAIT ]
+
+<span class="phrase">where <em class="replaceable"><code>lockmode</code></em> is one of:</span>
+
+ ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE
+ | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE
+</pre></div><div class="refsect1" id="id-1.9.3.155.5"><h2>Description</h2><p>
+ <code class="command">LOCK TABLE</code> obtains a table-level lock, waiting
+ if necessary for any conflicting locks to be released. If
+ <code class="literal">NOWAIT</code> is specified, <code class="command">LOCK
+ TABLE</code> does not wait to acquire the desired lock: if it
+ cannot be acquired immediately, the command is aborted and an
+ error is emitted. Once obtained, the lock is held for the
+ remainder of the current transaction. (There is no <code class="command">UNLOCK
+ TABLE</code> command; locks are always released at transaction
+ end.)
+ </p><p>
+ When a view is locked, all relations appearing in the view definition
+ query are also locked recursively with the same lock mode.
+ </p><p>
+ When acquiring locks automatically for commands that reference
+ tables, <span class="productname">PostgreSQL</span> always uses the least
+ restrictive lock mode possible. <code class="command">LOCK TABLE</code>
+ provides for cases when you might need more restrictive locking.
+ For example, suppose an application runs a transaction at the
+ <code class="literal">READ COMMITTED</code> isolation level and needs to ensure that
+ data in a table remains stable for the duration of the transaction.
+ To achieve this you could obtain <code class="literal">SHARE</code> lock mode over the
+ table before querying. This will prevent concurrent data changes
+ and ensure subsequent reads of the table see a stable view of
+ committed data, because <code class="literal">SHARE</code> lock mode conflicts with
+ the <code class="literal">ROW EXCLUSIVE</code> lock acquired by writers, and your
+ <code class="command">LOCK TABLE <em class="replaceable"><code>name</code></em> IN SHARE MODE</code>
+ statement will wait until any concurrent holders of <code class="literal">ROW
+ EXCLUSIVE</code> mode locks commit or roll back. Thus, once you
+ obtain the lock, there are no uncommitted writes outstanding;
+ furthermore none can begin until you release the lock.
+ </p><p>
+ To achieve a similar effect when running a transaction at the
+ <code class="literal">REPEATABLE READ</code> or <code class="literal">SERIALIZABLE</code>
+ isolation level, you have to execute the <code class="command">LOCK TABLE</code> statement
+ before executing any <code class="command">SELECT</code> or data modification statement.
+ A <code class="literal">REPEATABLE READ</code> or <code class="literal">SERIALIZABLE</code> transaction's
+ view of data will be frozen when its first
+ <code class="command">SELECT</code> or data modification statement begins. A <code class="command">LOCK
+ TABLE</code> later in the transaction will still prevent concurrent writes
+ — but it won't ensure that what the transaction reads corresponds to
+ the latest committed values.
+ </p><p>
+ If a transaction of this sort is going to change the data in the
+ table, then it should use <code class="literal">SHARE ROW EXCLUSIVE</code> lock mode
+ instead of <code class="literal">SHARE</code> mode. This ensures that only one
+ transaction of this type runs at a time. Without this, a deadlock
+ is possible: two transactions might both acquire <code class="literal">SHARE</code>
+ mode, and then be unable to also acquire <code class="literal">ROW EXCLUSIVE</code>
+ mode to actually perform their updates. (Note that a transaction's
+ own locks never conflict, so a transaction can acquire <code class="literal">ROW
+ EXCLUSIVE</code> mode when it holds <code class="literal">SHARE</code> mode — but not
+ if anyone else holds <code class="literal">SHARE</code> mode.) To avoid deadlocks,
+ make sure all transactions acquire locks on the same objects in the
+ same order, and if multiple lock modes are involved for a single
+ object, then transactions should always acquire the most
+ restrictive mode first.
+ </p><p>
+ More information about the lock modes and locking strategies can be
+ found in <a class="xref" href="explicit-locking.html" title="13.3. Explicit Locking">Section 13.3</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.155.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing table to
+ lock. If <code class="literal">ONLY</code> is specified before the table name, only that
+ table is locked. If <code class="literal">ONLY</code> is not specified, the table and all
+ its descendant tables (if any) are locked. Optionally, <code class="literal">*</code>
+ can be specified after the table name to explicitly indicate that
+ descendant tables are included.
+ </p><p>
+ The command <code class="literal">LOCK TABLE a, b;</code> is equivalent to
+ <code class="literal">LOCK TABLE a; LOCK TABLE b;</code>. The tables are locked
+ one-by-one in the order specified in the <code class="command">LOCK
+ TABLE</code> command.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>lockmode</code></em></span></dt><dd><p>
+ The lock mode specifies which locks this lock conflicts with.
+ Lock modes are described in <a class="xref" href="explicit-locking.html" title="13.3. Explicit Locking">Section 13.3</a>.
+ </p><p>
+ If no lock mode is specified, then <code class="literal">ACCESS
+ EXCLUSIVE</code>, the most restrictive mode, is used.
+ </p></dd><dt><span class="term"><code class="literal">NOWAIT</code></span></dt><dd><p>
+ Specifies that <code class="command">LOCK TABLE</code> should not wait for
+ any conflicting locks to be released: if the specified lock(s)
+ cannot be acquired immediately without waiting, the transaction
+ is aborted.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.155.7"><h2>Notes</h2><p>
+ <code class="literal">LOCK TABLE ... IN ACCESS SHARE MODE</code> requires <code class="literal">SELECT</code>
+ privileges on the target table. <code class="literal">LOCK TABLE ... IN ROW EXCLUSIVE
+ MODE</code> requires <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>,
+ or <code class="literal">TRUNCATE</code> privileges on the target table. All other forms of
+ <code class="command">LOCK</code> require table-level <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>,
+ or <code class="literal">TRUNCATE</code> privileges.
+ </p><p>
+ The user performing the lock on the view must have the corresponding
+ privilege on the view. In addition, by default, the view's owner must
+ have the relevant privileges on the underlying base relations, whereas the
+ user performing the lock does not need any permissions on the underlying
+ base relations. However, if the view has
+ <code class="literal">security_invoker</code> set to <code class="literal">true</code>
+ (see <a class="link" href="sql-createview.html" title="CREATE VIEW"><code class="command">CREATE VIEW</code></a>),
+ the user performing the lock, rather than the view owner, must have the
+ relevant privileges on the underlying base relations.
+ </p><p>
+ <code class="command">LOCK TABLE</code> is useless outside a transaction block: the lock
+ would remain held only to the completion of the statement. Therefore
+ <span class="productname">PostgreSQL</span> reports an error if <code class="command">LOCK</code>
+ is used outside a transaction block.
+ Use
+ <a class="link" href="sql-begin.html" title="BEGIN"><code class="command">BEGIN</code></a> and
+ <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a>
+ (or <a class="link" href="sql-rollback.html" title="ROLLBACK"><code class="command">ROLLBACK</code></a>)
+ to define a transaction block.
+ </p><p>
+ <code class="command">LOCK TABLE</code> only deals with table-level locks, and so
+ the mode names involving <code class="literal">ROW</code> are all misnomers. These
+ mode names should generally be read as indicating the intention of
+ the user to acquire row-level locks within the locked table. Also,
+ <code class="literal">ROW EXCLUSIVE</code> mode is a shareable table lock. Keep in
+ mind that all the lock modes have identical semantics so far as
+ <code class="command">LOCK TABLE</code> is concerned, differing only in the rules
+ about which modes conflict with which. For information on how to
+ acquire an actual row-level lock, see <a class="xref" href="explicit-locking.html#LOCKING-ROWS" title="13.3.2. Row-Level Locks">Section 13.3.2</a>
+ and <a class="xref" href="sql-select.html#SQL-FOR-UPDATE-SHARE" title="The Locking Clause">The Locking Clause</a>
+ in the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> documentation.
+ </p></div><div class="refsect1" id="id-1.9.3.155.8"><h2>Examples</h2><p>
+ Obtain a <code class="literal">SHARE</code> lock on a primary key table when going to perform
+ inserts into a foreign key table:
+
+</p><pre class="programlisting">
+BEGIN WORK;
+LOCK TABLE films IN SHARE MODE;
+SELECT id FROM films
+ WHERE name = 'Star Wars: Episode I - The Phantom Menace';
+-- Do ROLLBACK if record was not returned
+INSERT INTO films_user_comments VALUES
+ (_id_, 'GREAT! I was waiting for it for so long!');
+COMMIT WORK;
+</pre><p>
+ </p><p>
+ Take a <code class="literal">SHARE ROW EXCLUSIVE</code> lock on a primary key table when going to perform
+ a delete operation:
+
+</p><pre class="programlisting">
+BEGIN WORK;
+LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
+DELETE FROM films_user_comments WHERE id IN
+ (SELECT id FROM films WHERE rating &lt; 5);
+DELETE FROM films WHERE rating &lt; 5;
+COMMIT WORK;
+</pre></div><div class="refsect1" id="id-1.9.3.155.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">LOCK TABLE</code> in the SQL standard,
+ which instead uses <code class="command">SET TRANSACTION</code> to specify
+ concurrency levels on transactions. <span class="productname">PostgreSQL</span> supports that too;
+ see <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for details.
+ </p><p>
+ Except for <code class="literal">ACCESS SHARE</code>, <code class="literal">ACCESS EXCLUSIVE</code>,
+ and <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock modes, the
+ <span class="productname">PostgreSQL</span> lock modes and the
+ <code class="command">LOCK TABLE</code> syntax are compatible with those
+ present in <span class="productname">Oracle</span>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-load.html" title="LOAD">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-merge.html" title="MERGE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">LOAD </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> MERGE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-merge.html b/doc/src/sgml/html/sql-merge.html
new file mode 100644
index 0000000..1aef4c7
--- /dev/null
+++ b/doc/src/sgml/html/sql-merge.html
@@ -0,0 +1,380 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>MERGE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-lock.html" title="LOCK" /><link rel="next" href="sql-move.html" title="MOVE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">MERGE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-lock.html" title="LOCK">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-move.html" title="MOVE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-MERGE"><div class="titlepage"></div><a id="id-1.9.3.156.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">MERGE</span></h2><p>MERGE — conditionally insert, update, or delete rows of a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH <em class="replaceable"><code>with_query</code></em> [, ...] ]
+MERGE INTO [ ONLY ] <em class="replaceable"><code>target_table_name</code></em> [ * ] [ [ AS ] <em class="replaceable"><code>target_alias</code></em> ]
+USING <em class="replaceable"><code>data_source</code></em> ON <em class="replaceable"><code>join_condition</code></em>
+<em class="replaceable"><code>when_clause</code></em> [...]
+
+<span class="phrase">where <em class="replaceable"><code>data_source</code></em> is:</span>
+
+{ [ ONLY ] <em class="replaceable"><code>source_table_name</code></em> [ * ] | ( <em class="replaceable"><code>source_query</code></em> ) } [ [ AS ] <em class="replaceable"><code>source_alias</code></em> ]
+
+<span class="phrase">and <em class="replaceable"><code>when_clause</code></em> is:</span>
+
+{ WHEN MATCHED [ AND <em class="replaceable"><code>condition</code></em> ] THEN { <em class="replaceable"><code>merge_update</code></em> | <em class="replaceable"><code>merge_delete</code></em> | DO NOTHING } |
+ WHEN NOT MATCHED [ AND <em class="replaceable"><code>condition</code></em> ] THEN { <em class="replaceable"><code>merge_insert</code></em> | DO NOTHING } }
+
+<span class="phrase">and <em class="replaceable"><code>merge_insert</code></em> is:</span>
+
+INSERT [( <em class="replaceable"><code>column_name</code></em> [, ...] )]
+[ OVERRIDING { SYSTEM | USER } VALUE ]
+{ VALUES ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) | DEFAULT VALUES }
+
+<span class="phrase">and <em class="replaceable"><code>merge_update</code></em> is:</span>
+
+UPDATE SET { <em class="replaceable"><code>column_name</code></em> = { <em class="replaceable"><code>expression</code></em> | DEFAULT } |
+ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) } [, ...]
+
+<span class="phrase">and <em class="replaceable"><code>merge_delete</code></em> is:</span>
+
+DELETE
+</pre></div><div class="refsect1" id="id-1.9.3.156.5"><h2>Description</h2><p>
+ <code class="command">MERGE</code> performs actions that modify rows in the
+ <em class="replaceable"><code>target_table_name</code></em>,
+ using the <em class="replaceable"><code>data_source</code></em>.
+ <code class="command">MERGE</code> provides a single <acronym class="acronym">SQL</acronym>
+ statement that can conditionally <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code> or <code class="command">DELETE</code> rows, a task
+ that would otherwise require multiple procedural language statements.
+ </p><p>
+ First, the <code class="command">MERGE</code> command performs a join
+ from <em class="replaceable"><code>data_source</code></em> to
+ <em class="replaceable"><code>target_table_name</code></em>
+ producing zero or more candidate change rows. For each candidate change
+ row, the status of <code class="literal">MATCHED</code> or <code class="literal">NOT MATCHED</code>
+ is set just once, after which <code class="literal">WHEN</code> clauses are evaluated
+ in the order specified. For each candidate change row, the first clause to
+ evaluate as true is executed. No more than one <code class="literal">WHEN</code>
+ clause is executed for any candidate change row.
+ </p><p>
+ <code class="command">MERGE</code> actions have the same effect as
+ regular <code class="command">UPDATE</code>, <code class="command">INSERT</code>, or
+ <code class="command">DELETE</code> commands of the same names. The syntax of
+ those commands is different, notably that there is no <code class="literal">WHERE</code>
+ clause and no table name is specified. All actions refer to the
+ <em class="replaceable"><code>target_table_name</code></em>,
+ though modifications to other tables may be made using triggers.
+ </p><p>
+ When <code class="literal">DO NOTHING</code> is specified, the source row is
+ skipped. Since actions are evaluated in their specified order, <code class="literal">DO
+ NOTHING</code> can be handy to skip non-interesting source rows before
+ more fine-grained handling.
+ </p><p>
+ There is no separate <code class="literal">MERGE</code> privilege.
+ If you specify an update action, you must have the
+ <code class="literal">UPDATE</code> privilege on the column(s)
+ of the <em class="replaceable"><code>target_table_name</code></em>
+ that are referred to in the <code class="literal">SET</code> clause.
+ If you specify an insert action, you must have the <code class="literal">INSERT</code>
+ privilege on the <em class="replaceable"><code>target_table_name</code></em>.
+ If you specify an delete action, you must have the <code class="literal">DELETE</code>
+ privilege on the <em class="replaceable"><code>target_table_name</code></em>.
+ Privileges are tested once at statement start and are checked
+ whether or not particular <code class="literal">WHEN</code> clauses are executed.
+ You will require the <code class="literal">SELECT</code> privilege on the
+ <em class="replaceable"><code>data_source</code></em> and any column(s)
+ of the <em class="replaceable"><code>target_table_name</code></em>
+ referred to in a <code class="literal">condition</code>.
+ </p><p>
+ <code class="command">MERGE</code> is not supported if the
+ <em class="replaceable"><code>target_table_name</code></em> is a
+ materialized view, foreign table, or if it has any
+ rules defined on it.
+ </p></div><div class="refsect1" id="id-1.9.3.156.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>target_table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the target table to merge into.
+ If <code class="literal">ONLY</code> is specified before the table name, matching
+ rows are updated or deleted in the named table only. If
+ <code class="literal">ONLY</code> is not specified, matching rows are also updated
+ or deleted in any tables inheriting from the named table. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included. The
+ <code class="literal">ONLY</code> keyword and <code class="literal">*</code> option do not
+ affect insert actions, which always insert into the named table only.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>target_alias</code></em></span></dt><dd><p>
+ A substitute name for the target table. When an alias is
+ provided, it completely hides the actual name of the table. For
+ example, given <code class="literal">MERGE INTO foo AS f</code>, the remainder of the
+ <code class="command">MERGE</code> statement must refer to this table as
+ <code class="literal">f</code> not <code class="literal">foo</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the source table, view, or
+ transition table. If <code class="literal">ONLY</code> is specified before the
+ table name, matching rows are included from the named table only. If
+ <code class="literal">ONLY</code> is not specified, matching rows are also included
+ from any tables inheriting from the named table. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_query</code></em></span></dt><dd><p>
+ A query (<code class="command">SELECT</code> statement or <code class="command">VALUES</code>
+ statement) that supplies the rows to be merged into the
+ <em class="replaceable"><code>target_table_name</code></em>.
+ Refer to the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ statement or <a class="xref" href="sql-values.html" title="VALUES"><span class="refentrytitle">VALUES</span></a>
+ statement for a description of the syntax.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>source_alias</code></em></span></dt><dd><p>
+ A substitute name for the data source. When an alias is
+ provided, it completely hides the actual name of the table or the fact
+ that a query was issued.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>join_condition</code></em></span></dt><dd><p>
+ <em class="replaceable"><code>join_condition</code></em> is
+ an expression resulting in a value of type
+ <code class="type">boolean</code> (similar to a <code class="literal">WHERE</code>
+ clause) that specifies which rows in the
+ <em class="replaceable"><code>data_source</code></em>
+ match rows in the
+ <em class="replaceable"><code>target_table_name</code></em>.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ Only columns from <em class="replaceable"><code>target_table_name</code></em>
+ that attempt to match <em class="replaceable"><code>data_source</code></em>
+ rows should appear in <em class="replaceable"><code>join_condition</code></em>.
+ <em class="replaceable"><code>join_condition</code></em> subexpressions that
+ only reference <em class="replaceable"><code>target_table_name</code></em>
+ columns can affect which action is taken, often in surprising ways.
+ </p></div></dd><dt><span class="term"><em class="replaceable"><code>when_clause</code></em></span></dt><dd><p>
+ At least one <code class="literal">WHEN</code> clause is required.
+ </p><p>
+ If the <code class="literal">WHEN</code> clause specifies <code class="literal">WHEN MATCHED</code>
+ and the candidate change row matches a row in the
+ <em class="replaceable"><code>target_table_name</code></em>,
+ the <code class="literal">WHEN</code> clause is executed if the
+ <em class="replaceable"><code>condition</code></em> is
+ absent or it evaluates to <code class="literal">true</code>.
+ </p><p>
+ Conversely, if the <code class="literal">WHEN</code> clause specifies
+ <code class="literal">WHEN NOT MATCHED</code>
+ and the candidate change row does not match a row in the
+ <em class="replaceable"><code>target_table_name</code></em>,
+ the <code class="literal">WHEN</code> clause is executed if the
+ <em class="replaceable"><code>condition</code></em> is
+ absent or it evaluates to <code class="literal">true</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ An expression that returns a value of type <code class="type">boolean</code>.
+ If this expression for a <code class="literal">WHEN</code> clause
+ returns <code class="literal">true</code>, then the action for that clause
+ is executed for that row.
+ </p><p>
+ A condition on a <code class="literal">WHEN MATCHED</code> clause can refer to columns
+ in both the source and the target relations. A condition on a
+ <code class="literal">WHEN NOT MATCHED</code> clause can only refer to columns from
+ the source relation, since by definition there is no matching target row.
+ Only the system attributes from the target table are accessible.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>merge_insert</code></em></span></dt><dd><p>
+ The specification of an <code class="literal">INSERT</code> action that inserts
+ one row into the target table.
+ The target column names can be listed in any order. If no list of
+ column names is given at all, the default is all the columns of the
+ table in their declared order.
+ </p><p>
+ Each column not present in the explicit or implicit column list will be
+ filled with a default value, either its declared default value
+ or null if there is none.
+ </p><p>
+ If <em class="replaceable"><code>target_table_name</code></em>
+ is a partitioned table, each row is routed to the appropriate partition
+ and inserted into it.
+ If <em class="replaceable"><code>target_table_name</code></em>
+ is a partition, an error will occur if any input row violates the
+ partition constraint.
+ </p><p>
+ Column names may not be specified more than once.
+ <code class="command">INSERT</code> actions cannot contain sub-selects.
+ </p><p>
+ Only one <code class="literal">VALUES</code> clause can be specified.
+ The <code class="literal">VALUES</code> clause can only refer to columns from
+ the source relation, since by definition there is no matching target row.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>merge_update</code></em></span></dt><dd><p>
+ The specification of an <code class="literal">UPDATE</code> action that updates
+ the current row of the <em class="replaceable"><code>target_table_name</code></em>.
+ Column names may not be specified more than once.
+ </p><p>
+ Neither a table name nor a <code class="literal">WHERE</code> clause are allowed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>merge_delete</code></em></span></dt><dd><p>
+ Specifies a <code class="literal">DELETE</code> action that deletes the current row
+ of the <em class="replaceable"><code>target_table_name</code></em>.
+ Do not include the table name or any other clauses, as you would normally
+ do with a <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a> command.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column in the <em class="replaceable"><code>target_table_name</code></em>. The column name
+ can be qualified with a subfield name or array subscript, if
+ needed. (Inserting into only some fields of a composite
+ column leaves the other fields null.)
+ Do not include the table's name in the specification
+ of a target column.
+ </p></dd><dt><span class="term"><code class="literal">OVERRIDING SYSTEM VALUE</code></span></dt><dd><p>
+ Without this clause, it is an error to specify an explicit value
+ (other than <code class="literal">DEFAULT</code>) for an identity column defined
+ as <code class="literal">GENERATED ALWAYS</code>. This clause overrides that
+ restriction.
+ </p></dd><dt><span class="term"><code class="literal">OVERRIDING USER VALUE</code></span></dt><dd><p>
+ If this clause is specified, then any values supplied for identity
+ columns defined as <code class="literal">GENERATED BY DEFAULT</code> are ignored
+ and the default sequence-generated values are applied.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT VALUES</code></span></dt><dd><p>
+ All columns will be filled with their default values.
+ (An <code class="literal">OVERRIDING</code> clause is not permitted in this
+ form.)
+ </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ An expression to assign to the column. If used in a
+ <code class="literal">WHEN MATCHED</code> clause, the expression can use values
+ from the original row in the target table, and values from the
+ <code class="literal">data_source</code> row.
+ If used in a <code class="literal">WHEN NOT MATCHED</code> clause, the
+ expression can use values from the <code class="literal">data_source</code>.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ Set the column to its default value (which will be <code class="literal">NULL</code>
+ if no specific default expression has been assigned to it).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>
+ The <code class="literal">WITH</code> clause allows you to specify one or more
+ subqueries that can be referenced by name in the <code class="command">MERGE</code>
+ query. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> and <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ for details.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.156.7"><h2>Outputs</h2><p>
+ On successful completion, a <code class="command">MERGE</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+MERGE <em class="replaceable"><code>total_count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>total_count</code></em> is the total
+ number of rows changed (whether inserted, updated, or deleted).
+ If <em class="replaceable"><code>total_count</code></em> is 0, no rows
+ were changed in any way.
+ </p></div><div class="refsect1" id="id-1.9.3.156.8"><h2>Notes</h2><p>
+ The following steps take place during the execution of
+ <code class="command">MERGE</code>.
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Perform any <code class="literal">BEFORE STATEMENT</code> triggers for all
+ actions specified, whether or not their <code class="literal">WHEN</code>
+ clauses match.
+ </p></li><li class="listitem"><p>
+ Perform a join from source to target table.
+ The resulting query will be optimized normally and will produce
+ a set of candidate change rows. For each candidate change row,
+ </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
+ Evaluate whether each row is <code class="literal">MATCHED</code> or
+ <code class="literal">NOT MATCHED</code>.
+ </p></li><li class="listitem"><p>
+ Test each <code class="literal">WHEN</code> condition in the order
+ specified until one returns true.
+ </p></li><li class="listitem"><p>
+ When a condition returns true, perform the following actions:
+ </p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p>
+ Perform any <code class="literal">BEFORE ROW</code> triggers that fire
+ for the action's event type.
+ </p></li><li class="listitem"><p>
+ Perform the specified action, invoking any check constraints on the
+ target table.
+ </p></li><li class="listitem"><p>
+ Perform any <code class="literal">AFTER ROW</code> triggers that fire for
+ the action's event type.
+ </p></li></ol></div></li></ol></div></li><li class="listitem"><p>
+ Perform any <code class="literal">AFTER STATEMENT</code> triggers for actions
+ specified, whether or not they actually occur. This is similar to the
+ behavior of an <code class="command">UPDATE</code> statement that modifies no rows.
+ </p></li></ol></div><p>
+ In summary, statement triggers for an event type (say,
+ <code class="command">INSERT</code>) will be fired whenever we
+ <span class="emphasis"><em>specify</em></span> an action of that kind.
+ In contrast, row-level triggers will fire only for the specific event type
+ being <span class="emphasis"><em>executed</em></span>.
+ So a <code class="command">MERGE</code> command might fire statement triggers for both
+ <code class="command">UPDATE</code> and <code class="command">INSERT</code>, even though only
+ <code class="command">UPDATE</code> row triggers were fired.
+ </p><p>
+ You should ensure that the join produces at most one candidate change row
+ for each target row. In other words, a target row shouldn't join to more
+ than one data source row. If it does, then only one of the candidate change
+ rows will be used to modify the target row; later attempts to modify the
+ row will cause an error.
+ This can also occur if row triggers make changes to the target table
+ and the rows so modified are then subsequently also modified by
+ <code class="command">MERGE</code>.
+ If the repeated action is an <code class="command">INSERT</code>, this will
+ cause a uniqueness violation, while a repeated <code class="command">UPDATE</code>
+ or <code class="command">DELETE</code> will cause a cardinality violation; the
+ latter behavior is required by the <acronym class="acronym">SQL</acronym> standard.
+ This differs from historical <span class="productname">PostgreSQL</span>
+ behavior of joins in <code class="command">UPDATE</code> and
+ <code class="command">DELETE</code> statements where second and subsequent
+ attempts to modify the same row are simply ignored.
+ </p><p>
+ If a <code class="literal">WHEN</code> clause omits an <code class="literal">AND</code>
+ sub-clause, it becomes the final reachable clause of that
+ kind (<code class="literal">MATCHED</code> or <code class="literal">NOT MATCHED</code>).
+ If a later <code class="literal">WHEN</code> clause of that kind
+ is specified it would be provably unreachable and an error is raised.
+ If no final reachable clause is specified of either kind, it is
+ possible that no action will be taken for a candidate change row.
+ </p><p>
+ The order in which rows are generated from the data source is
+ indeterminate by default.
+ A <em class="replaceable"><code>source_query</code></em> can be
+ used to specify a consistent ordering, if required, which might be
+ needed to avoid deadlocks between concurrent transactions.
+ </p><p>
+ There is no <code class="literal">RETURNING</code> clause with
+ <code class="command">MERGE</code>. Actions of <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code> and <code class="command">DELETE</code> cannot contain
+ <code class="literal">RETURNING</code> or <code class="literal">WITH</code> clauses.
+ </p><p>
+ When <code class="command">MERGE</code> is run concurrently with other commands
+ that modify the target table, the usual transaction isolation rules
+ apply; see <a class="xref" href="transaction-iso.html" title="13.2. Transaction Isolation">Section 13.2</a> for an explanation
+ on the behavior at each isolation level.
+ You may also wish to consider using <code class="command">INSERT ... ON CONFLICT</code>
+ as an alternative statement which offers the ability to run an
+ <code class="command">UPDATE</code> if a concurrent <code class="command">INSERT</code>
+ occurs. There are a variety of differences and restrictions between
+ the two statement types and they are not interchangeable.
+ </p></div><div class="refsect1" id="id-1.9.3.156.9"><h2>Examples</h2><p>
+ Perform maintenance on <code class="literal">customer_accounts</code> based
+ upon new <code class="literal">recent_transactions</code>.
+
+</p><pre class="programlisting">
+MERGE INTO customer_account ca
+USING recent_transactions t
+ON t.customer_id = ca.customer_id
+WHEN MATCHED THEN
+ UPDATE SET balance = balance + transaction_value
+WHEN NOT MATCHED THEN
+ INSERT (customer_id, balance)
+ VALUES (t.customer_id, t.transaction_value);
+</pre><p>
+ </p><p>
+ Notice that this would be exactly equivalent to the following
+ statement because the <code class="literal">MATCHED</code> result does not change
+ during execution.
+
+</p><pre class="programlisting">
+MERGE INTO customer_account ca
+USING (SELECT customer_id, transaction_value FROM recent_transactions) AS t
+ON t.customer_id = ca.customer_id
+WHEN MATCHED THEN
+ UPDATE SET balance = balance + transaction_value
+WHEN NOT MATCHED THEN
+ INSERT (customer_id, balance)
+ VALUES (t.customer_id, t.transaction_value);
+</pre><p>
+ </p><p>
+ Attempt to insert a new stock item along with the quantity of stock. If
+ the item already exists, instead update the stock count of the existing
+ item. Don't allow entries that have zero stock.
+</p><pre class="programlisting">
+MERGE INTO wines w
+USING wine_stock_changes s
+ON s.winename = w.winename
+WHEN NOT MATCHED AND s.stock_delta &gt; 0 THEN
+ INSERT VALUES(s.winename, s.stock_delta)
+WHEN MATCHED AND w.stock + s.stock_delta &gt; 0 THEN
+ UPDATE SET stock = w.stock + s.stock_delta
+WHEN MATCHED THEN
+ DELETE;
+</pre><p>
+
+ The <code class="literal">wine_stock_changes</code> table might be, for example, a
+ temporary table recently loaded into the database.
+ </p></div><div class="refsect1" id="id-1.9.3.156.10"><h2>Compatibility</h2><p>
+ This command conforms to the <acronym class="acronym">SQL</acronym> standard.
+ </p><p>
+ The WITH clause and <code class="literal">DO NOTHING</code> action are extensions to
+ the <acronym class="acronym">SQL</acronym> standard.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-lock.html" title="LOCK">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-move.html" title="MOVE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">LOCK </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> MOVE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-move.html b/doc/src/sgml/html/sql-move.html
new file mode 100644
index 0000000..09bb08b
--- /dev/null
+++ b/doc/src/sgml/html/sql-move.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>MOVE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-merge.html" title="MERGE" /><link rel="next" href="sql-notify.html" title="NOTIFY" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">MOVE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-merge.html" title="MERGE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-notify.html" title="NOTIFY">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-MOVE"><div class="titlepage"></div><a id="id-1.9.3.157.1" class="indexterm"></a><a id="id-1.9.3.157.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">MOVE</span></h2><p>MOVE — position a cursor</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+MOVE [ <em class="replaceable"><code>direction</code></em> ] [ FROM | IN ] <em class="replaceable"><code>cursor_name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>direction</code></em> can be one of:</span>
+
+ NEXT
+ PRIOR
+ FIRST
+ LAST
+ ABSOLUTE <em class="replaceable"><code>count</code></em>
+ RELATIVE <em class="replaceable"><code>count</code></em>
+ <em class="replaceable"><code>count</code></em>
+ ALL
+ FORWARD
+ FORWARD <em class="replaceable"><code>count</code></em>
+ FORWARD ALL
+ BACKWARD
+ BACKWARD <em class="replaceable"><code>count</code></em>
+ BACKWARD ALL
+</pre></div><div class="refsect1" id="id-1.9.3.157.6"><h2>Description</h2><p>
+ <code class="command">MOVE</code> repositions a cursor without retrieving any data.
+ <code class="command">MOVE</code> works exactly like the <code class="command">FETCH</code>
+ command, except it only positions the cursor and does not return rows.
+ </p><p>
+ The parameters for the <code class="command">MOVE</code> command are identical to
+ those of the <code class="command">FETCH</code> command; refer to
+ <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>
+ for details on syntax and usage.
+ </p></div><div class="refsect1" id="id-1.9.3.157.7"><h2>Outputs</h2><p>
+ On successful completion, a <code class="command">MOVE</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+MOVE <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number
+ of rows that a <code class="command">FETCH</code> command with the same parameters
+ would have returned (possibly zero).
+ </p></div><div class="refsect1" id="id-1.9.3.157.8"><h2>Examples</h2><pre class="programlisting">
+BEGIN WORK;
+DECLARE liahona CURSOR FOR SELECT * FROM films;
+
+-- Skip the first 5 rows:
+MOVE FORWARD 5 IN liahona;
+MOVE 5
+
+-- Fetch the 6th row from the cursor liahona:
+FETCH 1 FROM liahona;
+ code | title | did | date_prod | kind | len
+-------+--------+-----+------------+--------+-------
+ P_303 | 48 Hrs | 103 | 1982-10-22 | Action | 01:37
+(1 row)
+
+-- Close the cursor liahona and end the transaction:
+CLOSE liahona;
+COMMIT WORK;
+</pre></div><div class="refsect1" id="id-1.9.3.157.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">MOVE</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.157.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-close.html" title="CLOSE"><span class="refentrytitle">CLOSE</span></a>, <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>, <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-merge.html" title="MERGE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-notify.html" title="NOTIFY">Next</a></td></tr><tr><td width="40%" align="left" valign="top">MERGE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> NOTIFY</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-notify.html b/doc/src/sgml/html/sql-notify.html
new file mode 100644
index 0000000..0c03195
--- /dev/null
+++ b/doc/src/sgml/html/sql-notify.html
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>NOTIFY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-move.html" title="MOVE" /><link rel="next" href="sql-prepare.html" title="PREPARE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">NOTIFY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-move.html" title="MOVE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-prepare.html" title="PREPARE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-NOTIFY"><div class="titlepage"></div><a id="id-1.9.3.158.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">NOTIFY</span></h2><p>NOTIFY — generate a notification</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+NOTIFY <em class="replaceable"><code>channel</code></em> [ , <em class="replaceable"><code>payload</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.158.5"><h2>Description</h2><p>
+ The <code class="command">NOTIFY</code> command sends a notification event together
+ with an optional <span class="quote">“<span class="quote">payload</span>”</span> string to each client application that
+ has previously executed
+ <code class="command">LISTEN <em class="replaceable"><code>channel</code></em></code>
+ for the specified channel name in the current database.
+ Notifications are visible to all users.
+ </p><p>
+ <code class="command">NOTIFY</code> provides a simple
+ interprocess communication mechanism for a collection of processes
+ accessing the same <span class="productname">PostgreSQL</span> database.
+ A payload string can be sent along with the notification, and
+ higher-level mechanisms for passing structured data can be built by using
+ tables in the database to pass additional data from notifier to listener(s).
+ </p><p>
+ The information passed to the client for a notification event includes the
+ notification channel
+ name, the notifying session's server process <acronym class="acronym">PID</acronym>, and the
+ payload string, which is an empty string if it has not been specified.
+ </p><p>
+ It is up to the database designer to define the channel names that will
+ be used in a given database and what each one means.
+ Commonly, the channel name is the same as the name of some table in
+ the database, and the notify event essentially means, <span class="quote">“<span class="quote">I changed this table,
+ take a look at it to see what's new</span>”</span>. But no such association is enforced by
+ the <code class="command">NOTIFY</code> and <code class="command">LISTEN</code> commands. For
+ example, a database designer could use several different channel names
+ to signal different sorts of changes to a single table. Alternatively,
+ the payload string could be used to differentiate various cases.
+ </p><p>
+ When <code class="command">NOTIFY</code> is used to signal the occurrence of changes
+ to a particular table, a useful programming technique is to put the
+ <code class="command">NOTIFY</code> in a statement trigger that is triggered by table updates.
+ In this way, notification happens automatically when the table is changed,
+ and the application programmer cannot accidentally forget to do it.
+ </p><p>
+ <code class="command">NOTIFY</code> interacts with SQL transactions in some important
+ ways. Firstly, if a <code class="command">NOTIFY</code> is executed inside a
+ transaction, the notify events are not delivered until and unless the
+ transaction is committed. This is appropriate, since if the transaction
+ is aborted, all the commands within it have had no
+ effect, including <code class="command">NOTIFY</code>. But it can be disconcerting if one
+ is expecting the notification events to be delivered immediately. Secondly, if
+ a listening session receives a notification signal while it is within a transaction,
+ the notification event will not be delivered to its connected client until just
+ after the transaction is completed (either committed or aborted). Again, the
+ reasoning is that if a notification were delivered within a transaction that was
+ later aborted, one would want the notification to be undone somehow —
+ but
+ the server cannot <span class="quote">“<span class="quote">take back</span>”</span> a notification once it has sent it to the client.
+ So notification events are only delivered between transactions. The upshot of this
+ is that applications using <code class="command">NOTIFY</code> for real-time signaling
+ should try to keep their transactions short.
+ </p><p>
+ If the same channel name is signaled multiple times with identical
+ payload strings within the same transaction, only one instance of the
+ notification event is delivered to listeners.
+ On the other hand, notifications with distinct payload strings will
+ always be delivered as distinct notifications. Similarly, notifications from
+ different transactions will never get folded into one notification.
+ Except for dropping later instances of duplicate notifications,
+ <code class="command">NOTIFY</code> guarantees that notifications from the same
+ transaction get delivered in the order they were sent. It is also
+ guaranteed that messages from different transactions are delivered in
+ the order in which the transactions committed.
+ </p><p>
+ It is common for a client that executes <code class="command">NOTIFY</code>
+ to be listening on the same notification channel itself. In that case
+ it will get back a notification event, just like all the other
+ listening sessions. Depending on the application logic, this could
+ result in useless work, for example, reading a database table to
+ find the same updates that that session just wrote out. It is
+ possible to avoid such extra work by noticing whether the notifying
+ session's server process <acronym class="acronym">PID</acronym> (supplied in the
+ notification event message) is the same as one's own session's
+ <acronym class="acronym">PID</acronym> (available from <span class="application">libpq</span>). When they
+ are the same, the notification event is one's own work bouncing
+ back, and can be ignored.
+ </p></div><div class="refsect1" id="id-1.9.3.158.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>channel</code></em></span></dt><dd><p>
+ Name of the notification channel to be signaled (any identifier).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>payload</code></em></span></dt><dd><p>
+ The <span class="quote">“<span class="quote">payload</span>”</span> string to be communicated along with the
+ notification. This must be specified as a simple string literal.
+ In the default configuration it must be shorter than 8000 bytes.
+ (If binary data or large amounts of information need to be communicated,
+ it's best to put it in a database table and send the key of the record.)
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.158.7"><h2>Notes</h2><p>
+ There is a queue that holds notifications that have been sent but not
+ yet processed by all listening sessions. If this queue becomes full,
+ transactions calling <code class="command">NOTIFY</code> will fail at commit.
+ The queue is quite large (8GB in a standard installation) and should be
+ sufficiently sized for almost every use case. However, no cleanup can take
+ place if a session executes <code class="command">LISTEN</code> and then enters a
+ transaction for a very long time. Once the queue is half full you will see
+ warnings in the log file pointing you to the session that is preventing
+ cleanup. In this case you should make sure that this session ends its
+ current transaction so that cleanup can proceed.
+ </p><p>
+ The function <code class="function">pg_notification_queue_usage</code> returns the
+ fraction of the queue that is currently occupied by pending notifications.
+ See <a class="xref" href="functions-info.html" title="9.26. System Information Functions and Operators">Section 9.26</a> for more information.
+ </p><p>
+ A transaction that has executed <code class="command">NOTIFY</code> cannot be
+ prepared for two-phase commit.
+ </p><div class="refsect2" id="id-1.9.3.158.7.5"><h3>pg_notify</h3><a id="id-1.9.3.158.7.5.2" class="indexterm"></a><p>
+ To send a notification you can also use the function
+ <code class="literal"><code class="function">pg_notify</code>(<code class="type">text</code>,
+ <code class="type">text</code>)</code>. The function takes the channel name as the
+ first argument and the payload as the second. The function is much easier
+ to use than the <code class="command">NOTIFY</code> command if you need to work with
+ non-constant channel names and payloads.
+ </p></div></div><div class="refsect1" id="id-1.9.3.158.8"><h2>Examples</h2><p>
+ Configure and execute a listen/notify sequence from
+ <span class="application">psql</span>:
+
+</p><pre class="programlisting">
+LISTEN virtual;
+NOTIFY virtual;
+Asynchronous notification "virtual" received from server process with PID 8448.
+NOTIFY virtual, 'This is the payload';
+Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448.
+
+LISTEN foo;
+SELECT pg_notify('fo' || 'o', 'pay' || 'load');
+Asynchronous notification "foo" with payload "payload" received from server process with PID 14728.
+</pre></div><div class="refsect1" id="id-1.9.3.158.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">NOTIFY</code> statement in the SQL
+ standard.
+ </p></div><div class="refsect1" id="id-1.9.3.158.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-listen.html" title="LISTEN"><span class="refentrytitle">LISTEN</span></a>, <a class="xref" href="sql-unlisten.html" title="UNLISTEN"><span class="refentrytitle">UNLISTEN</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-move.html" title="MOVE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-prepare.html" title="PREPARE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">MOVE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> PREPARE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-prepare-transaction.html b/doc/src/sgml/html/sql-prepare-transaction.html
new file mode 100644
index 0000000..883395b
--- /dev/null
+++ b/doc/src/sgml/html/sql-prepare-transaction.html
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PREPARE TRANSACTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-prepare.html" title="PREPARE" /><link rel="next" href="sql-reassign-owned.html" title="REASSIGN OWNED" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PREPARE TRANSACTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-prepare.html" title="PREPARE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-reassign-owned.html" title="REASSIGN OWNED">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-PREPARE-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.160.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">PREPARE TRANSACTION</span></h2><p>PREPARE TRANSACTION — prepare the current transaction for two-phase commit</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+PREPARE TRANSACTION <em class="replaceable"><code>transaction_id</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.160.5"><h2>Description</h2><p>
+ <code class="command">PREPARE TRANSACTION</code> prepares the current transaction
+ for two-phase commit. After this command, the transaction is no longer
+ associated with the current session; instead, its state is fully stored on
+ disk, and there is a very high probability that it can be committed
+ successfully, even if a database crash occurs before the commit is
+ requested.
+ </p><p>
+ Once prepared, a transaction can later be committed or rolled back
+ with <a class="link" href="sql-commit-prepared.html" title="COMMIT PREPARED"><code class="command">COMMIT PREPARED</code></a>
+ or <a class="link" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED"><code class="command">ROLLBACK PREPARED</code></a>,
+ respectively. Those commands can be issued from any session, not
+ only the one that executed the original transaction.
+ </p><p>
+ From the point of view of the issuing session, <code class="command">PREPARE
+ TRANSACTION</code> is not unlike a <code class="command">ROLLBACK</code> command:
+ after executing it, there is no active current transaction, and the
+ effects of the prepared transaction are no longer visible. (The effects
+ will become visible again if the transaction is committed.)
+ </p><p>
+ If the <code class="command">PREPARE TRANSACTION</code> command fails for any
+ reason, it becomes a <code class="command">ROLLBACK</code>: the current transaction
+ is canceled.
+ </p></div><div class="refsect1" id="id-1.9.3.160.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ An arbitrary identifier that later identifies this transaction for
+ <code class="command">COMMIT PREPARED</code> or <code class="command">ROLLBACK PREPARED</code>.
+ The identifier must be written as a string literal, and must be
+ less than 200 bytes long. It must not be the same as the identifier
+ used for any currently prepared transaction.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.160.7"><h2>Notes</h2><p>
+ <code class="command">PREPARE TRANSACTION</code> is not intended for use in applications
+ or interactive sessions. Its purpose is to allow an external
+ transaction manager to perform atomic global transactions across multiple
+ databases or other transactional resources. Unless you're writing a
+ transaction manager, you probably shouldn't be using <code class="command">PREPARE
+ TRANSACTION</code>.
+ </p><p>
+ This command must be used inside a transaction block. Use <a class="link" href="sql-begin.html" title="BEGIN"><code class="command">BEGIN</code></a> to start one.
+ </p><p>
+ It is not currently allowed to <code class="command">PREPARE</code> a transaction that
+ has executed any operations involving temporary tables or the session's
+ temporary namespace, created any cursors <code class="literal">WITH HOLD</code>, or
+ executed <code class="command">LISTEN</code>, <code class="command">UNLISTEN</code>, or
+ <code class="command">NOTIFY</code>.
+ Those features are too tightly
+ tied to the current session to be useful in a transaction to be prepared.
+ </p><p>
+ If the transaction modified any run-time parameters with <code class="command">SET</code>
+ (without the <code class="literal">LOCAL</code> option),
+ those effects persist after <code class="command">PREPARE TRANSACTION</code>, and will not
+ be affected by any later <code class="command">COMMIT PREPARED</code> or
+ <code class="command">ROLLBACK PREPARED</code>. Thus, in this one respect
+ <code class="command">PREPARE TRANSACTION</code> acts more like <code class="command">COMMIT</code> than
+ <code class="command">ROLLBACK</code>.
+ </p><p>
+ All currently available prepared transactions are listed in the
+ <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a>
+ system view.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is unwise to leave transactions in the prepared state for a long time.
+ This will interfere with the ability of <code class="command">VACUUM</code> to reclaim
+ storage, and in extreme cases could cause the database to shut down
+ to prevent transaction ID wraparound (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>). Keep in mind also that the transaction
+ continues to hold whatever locks it held. The intended usage of the
+ feature is that a prepared transaction will normally be committed or
+ rolled back as soon as an external transaction manager has verified that
+ other databases are also prepared to commit.
+ </p><p>
+ If you have not set up an external transaction manager to track prepared
+ transactions and ensure they get closed out promptly, it is best to keep
+ the prepared-transaction feature disabled by setting
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a> to zero. This will
+ prevent accidental creation of prepared transactions that might then
+ be forgotten and eventually cause problems.
+ </p></div></div><div class="refsect1" id="SQL-PREPARE-TRANSACTION-EXAMPLES"><h2>Examples</h2><p>
+ Prepare the current transaction for two-phase commit, using
+ <code class="literal">foobar</code> as the transaction identifier:
+
+</p><pre class="programlisting">
+PREPARE TRANSACTION 'foobar';
+</pre></div><div class="refsect1" id="id-1.9.3.160.9"><h2>Compatibility</h2><p>
+ <code class="command">PREPARE TRANSACTION</code> is a
+ <span class="productname">PostgreSQL</span> extension. It is intended for use by
+ external transaction management systems, some of which are covered by
+ standards (such as X/Open XA), but the SQL side of those systems is not
+ standardized.
+ </p></div><div class="refsect1" id="id-1.9.3.160.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-commit-prepared.html" title="COMMIT PREPARED"><span class="refentrytitle">COMMIT PREPARED</span></a>, <a class="xref" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED"><span class="refentrytitle">ROLLBACK PREPARED</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-prepare.html" title="PREPARE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-reassign-owned.html" title="REASSIGN OWNED">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PREPARE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> REASSIGN OWNED</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-prepare.html b/doc/src/sgml/html/sql-prepare.html
new file mode 100644
index 0000000..dd6d3b1
--- /dev/null
+++ b/doc/src/sgml/html/sql-prepare.html
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PREPARE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-notify.html" title="NOTIFY" /><link rel="next" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PREPARE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-notify.html" title="NOTIFY">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-PREPARE"><div class="titlepage"></div><a id="id-1.9.3.159.1" class="indexterm"></a><a id="id-1.9.3.159.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">PREPARE</span></h2><p>PREPARE — prepare a statement for execution</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+PREPARE <em class="replaceable"><code>name</code></em> [ ( <em class="replaceable"><code>data_type</code></em> [, ...] ) ] AS <em class="replaceable"><code>statement</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.159.6"><h2>Description</h2><p>
+ <code class="command">PREPARE</code> creates a prepared statement. A prepared
+ statement is a server-side object that can be used to optimize
+ performance. When the <code class="command">PREPARE</code> statement is
+ executed, the specified statement is parsed, analyzed, and rewritten.
+ When an <code class="command">EXECUTE</code> command is subsequently
+ issued, the prepared statement is planned and executed. This division
+ of labor avoids repetitive parse analysis work, while allowing
+ the execution plan to depend on the specific parameter values supplied.
+ </p><p>
+ Prepared statements can take parameters: values that are
+ substituted into the statement when it is executed. When creating
+ the prepared statement, refer to parameters by position, using
+ <code class="literal">$1</code>, <code class="literal">$2</code>, etc. A corresponding list of
+ parameter data types can optionally be specified. When a
+ parameter's data type is not specified or is declared as
+ <code class="literal">unknown</code>, the type is inferred from the context
+ in which the parameter is first referenced (if possible). When executing the
+ statement, specify the actual values for these parameters in the
+ <code class="command">EXECUTE</code> statement. Refer to <a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a> for more
+ information about that.
+ </p><p>
+ Prepared statements only last for the duration of the current
+ database session. When the session ends, the prepared statement is
+ forgotten, so it must be recreated before being used again. This
+ also means that a single prepared statement cannot be used by
+ multiple simultaneous database clients; however, each client can create
+ their own prepared statement to use. Prepared statements can be
+ manually cleaned up using the <a class="link" href="sql-deallocate.html" title="DEALLOCATE"><code class="command">DEALLOCATE</code></a> command.
+ </p><p>
+ Prepared statements potentially have the largest performance advantage
+ when a single session is being used to execute a large number of similar
+ statements. The performance difference will be particularly
+ significant if the statements are complex to plan or rewrite, e.g.,
+ if the query involves a join of many tables or requires
+ the application of several rules. If the statement is relatively simple
+ to plan and rewrite but relatively expensive to execute, the
+ performance advantage of prepared statements will be less noticeable.
+ </p></div><div class="refsect1" id="id-1.9.3.159.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ An arbitrary name given to this particular prepared
+ statement. It must be unique within a single session and is
+ subsequently used to execute or deallocate a previously prepared
+ statement.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
+ The data type of a parameter to the prepared statement. If the
+ data type of a particular parameter is unspecified or is
+ specified as <code class="literal">unknown</code>, it will be inferred
+ from the context in which the parameter is first referenced. To refer to the
+ parameters in the prepared statement itself, use
+ <code class="literal">$1</code>, <code class="literal">$2</code>, etc.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>statement</code></em></span></dt><dd><p>
+ Any <code class="command">SELECT</code>, <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">MERGE</code>, or <code class="command">VALUES</code>
+ statement.
+ </p></dd></dl></div></div><div class="refsect1" id="SQL-PREPARE-NOTES"><h2>Notes</h2><p>
+ A prepared statement can be executed with either a <em class="firstterm">generic
+ plan</em> or a <em class="firstterm">custom plan</em>. A generic
+ plan is the same across all executions, while a custom plan is generated
+ for a specific execution using the parameter values given in that call.
+ Use of a generic plan avoids planning overhead, but in some situations
+ a custom plan will be much more efficient to execute because the planner
+ can make use of knowledge of the parameter values. (Of course, if the
+ prepared statement has no parameters, then this is moot and a generic
+ plan is always used.)
+ </p><p>
+ By default (that is, when <a class="xref" href="runtime-config-query.html#GUC-PLAN-CACHE_MODE">plan_cache_mode</a> is set
+ to <code class="literal">auto</code>), the server will automatically choose
+ whether to use a generic or custom plan for a prepared statement that
+ has parameters. The current rule for this is that the first five
+ executions are done with custom plans and the average estimated cost of
+ those plans is calculated. Then a generic plan is created and its
+ estimated cost is compared to the average custom-plan cost. Subsequent
+ executions use the generic plan if its cost is not so much higher than
+ the average custom-plan cost as to make repeated replanning seem
+ preferable.
+ </p><p>
+ This heuristic can be overridden, forcing the server to use either
+ generic or custom plans, by setting <code class="varname">plan_cache_mode</code>
+ to <code class="literal">force_generic_plan</code>
+ or <code class="literal">force_custom_plan</code> respectively.
+ This setting is primarily useful if the generic plan's cost estimate
+ is badly off for some reason, allowing it to be chosen even though
+ its actual cost is much more than that of a custom plan.
+ </p><p>
+ To examine the query plan <span class="productname">PostgreSQL</span> is using
+ for a prepared statement, use <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN</code></a>, for example
+</p><pre class="programlisting">
+EXPLAIN EXECUTE <em class="replaceable"><code>name</code></em>(<em class="replaceable"><code>parameter_values</code></em>);
+</pre><p>
+ If a generic plan is in use, it will contain parameter symbols
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code>, while a custom plan
+ will have the supplied parameter values substituted into it.
+ </p><p>
+ For more information on query planning and the statistics collected
+ by <span class="productname">PostgreSQL</span> for that purpose, see
+ the <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>
+ documentation.
+ </p><p>
+ Although the main point of a prepared statement is to avoid repeated parse
+ analysis and planning of the statement, <span class="productname">PostgreSQL</span> will
+ force re-analysis and re-planning of the statement before using it
+ whenever database objects used in the statement have undergone
+ definitional (DDL) changes or their planner statistics have
+ been updated since the previous use of the prepared
+ statement. Also, if the value of <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> changes
+ from one use to the next, the statement will be re-parsed using the new
+ <code class="varname">search_path</code>. (This latter behavior is new as of
+ <span class="productname">PostgreSQL</span> 9.3.) These rules make use of a
+ prepared statement semantically almost equivalent to re-submitting the
+ same query text over and over, but with a performance benefit if no object
+ definitions are changed, especially if the best plan remains the same
+ across uses. An example of a case where the semantic equivalence is not
+ perfect is that if the statement refers to a table by an unqualified name,
+ and then a new table of the same name is created in a schema appearing
+ earlier in the <code class="varname">search_path</code>, no automatic re-parse will occur
+ since no object used in the statement changed. However, if some other
+ change forces a re-parse, the new table will be referenced in subsequent
+ uses.
+ </p><p>
+ You can see all prepared statements available in the session by querying the
+ <a class="link" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements"><code class="structname">pg_prepared_statements</code></a>
+ system view.
+ </p></div><div class="refsect1" id="SQL-PREPARE-EXAMPLES"><h2>Examples</h2><p>
+ Create a prepared statement for an <code class="command">INSERT</code>
+ statement, and then execute it:
+</p><pre class="programlisting">
+PREPARE fooplan (int, text, bool, numeric) AS
+ INSERT INTO foo VALUES($1, $2, $3, $4);
+EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00);
+</pre><p>
+ </p><p>
+ Create a prepared statement for a <code class="command">SELECT</code>
+ statement, and then execute it:
+</p><pre class="programlisting">
+PREPARE usrrptplan (int) AS
+ SELECT * FROM users u, logs l WHERE u.usrid=$1 AND u.usrid=l.usrid
+ AND l.date = $2;
+EXECUTE usrrptplan(1, current_date);
+</pre><p>
+
+ In this example, the data type of the second parameter is not specified,
+ so it is inferred from the context in which <code class="literal">$2</code> is used.
+ </p></div><div class="refsect1" id="id-1.9.3.159.10"><h2>Compatibility</h2><p>
+ The SQL standard includes a <code class="command">PREPARE</code> statement,
+ but it is only for use in embedded SQL. This version of the
+ <code class="command">PREPARE</code> statement also uses a somewhat different
+ syntax.
+ </p></div><div class="refsect1" id="id-1.9.3.159.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-deallocate.html" title="DEALLOCATE"><span class="refentrytitle">DEALLOCATE</span></a>, <a class="xref" href="sql-execute.html" title="EXECUTE"><span class="refentrytitle">EXECUTE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-notify.html" title="NOTIFY">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">NOTIFY </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> PREPARE TRANSACTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-reassign-owned.html b/doc/src/sgml/html/sql-reassign-owned.html
new file mode 100644
index 0000000..763e3a8
--- /dev/null
+++ b/doc/src/sgml/html/sql-reassign-owned.html
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>REASSIGN OWNED</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION" /><link rel="next" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">REASSIGN OWNED</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-REASSIGN-OWNED"><div class="titlepage"></div><a id="id-1.9.3.161.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">REASSIGN OWNED</span></h2><p>REASSIGN OWNED — change the ownership of database objects owned by a database role</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+REASSIGN OWNED BY { <em class="replaceable"><code>old_role</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, ...]
+ TO { <em class="replaceable"><code>new_role</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+</pre></div><div class="refsect1" id="id-1.9.3.161.5"><h2>Description</h2><p>
+ <code class="command">REASSIGN OWNED</code> instructs the system to change
+ the ownership of database objects owned by any of the
+ <em class="replaceable"><code>old_roles</code></em> to
+ <em class="replaceable"><code>new_role</code></em>.
+ </p></div><div class="refsect1" id="id-1.9.3.161.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>old_role</code></em></span></dt><dd><p>
+ The name of a role. The ownership of all the objects within the
+ current database, and of all shared objects (databases, tablespaces),
+ owned by this role will be reassigned to
+ <em class="replaceable"><code>new_role</code></em>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_role</code></em></span></dt><dd><p>
+ The name of the role that will be made the new owner of the
+ affected objects.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.161.7"><h2>Notes</h2><p>
+ <code class="command">REASSIGN OWNED</code> is often used to prepare for the
+ removal of one or more roles. Because <code class="command">REASSIGN
+ OWNED</code> does not affect objects within other databases,
+ it is usually necessary to execute this command in each database
+ that contains objects owned by a role that is to be removed.
+ </p><p>
+ <code class="command">REASSIGN OWNED</code> requires membership on both the
+ source role(s) and the target role.
+ </p><p>
+ The <a class="link" href="sql-drop-owned.html" title="DROP OWNED"><code class="command">DROP OWNED</code></a> command is an alternative that
+ simply drops all the database objects owned by one or more roles.
+ </p><p>
+ The <code class="command">REASSIGN OWNED</code> command does not affect any
+ privileges granted to
+ the <em class="replaceable"><code>old_roles</code></em> on objects
+ that are not owned by them. Likewise, it does not affect default
+ privileges created with <code class="command">ALTER DEFAULT PRIVILEGES</code>.
+ Use <code class="command">DROP OWNED</code> to revoke such privileges.
+ </p><p>
+ See <a class="xref" href="role-removal.html" title="22.4. Dropping Roles">Section 22.4</a> for more discussion.
+ </p></div><div class="refsect1" id="id-1.9.3.161.8"><h2>Compatibility</h2><p>
+ The <code class="command">REASSIGN OWNED</code> command is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.161.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-drop-owned.html" title="DROP OWNED"><span class="refentrytitle">DROP OWNED</span></a>, <a class="xref" href="sql-droprole.html" title="DROP ROLE"><span class="refentrytitle">DROP ROLE</span></a>, <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PREPARE TRANSACTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> REFRESH MATERIALIZED VIEW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-refreshmaterializedview.html b/doc/src/sgml/html/sql-refreshmaterializedview.html
new file mode 100644
index 0000000..b33122b
--- /dev/null
+++ b/doc/src/sgml/html/sql-refreshmaterializedview.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>REFRESH MATERIALIZED VIEW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-reassign-owned.html" title="REASSIGN OWNED" /><link rel="next" href="sql-reindex.html" title="REINDEX" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">REFRESH MATERIALIZED VIEW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-reassign-owned.html" title="REASSIGN OWNED">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-reindex.html" title="REINDEX">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-REFRESHMATERIALIZEDVIEW"><div class="titlepage"></div><a id="id-1.9.3.162.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">REFRESH MATERIALIZED VIEW</span></h2><p>REFRESH MATERIALIZED VIEW — replace the contents of a materialized view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] <em class="replaceable"><code>name</code></em>
+ [ WITH [ NO ] DATA ]
+</pre></div><div class="refsect1" id="id-1.9.3.162.5"><h2>Description</h2><p>
+ <code class="command">REFRESH MATERIALIZED VIEW</code> completely replaces the
+ contents of a materialized view. To execute this command you must be the
+ owner of the materialized view. The old contents are discarded. If
+ <code class="literal">WITH DATA</code> is specified (or defaults) the backing query
+ is executed to provide the new data, and the materialized view is left in a
+ scannable state. If <code class="literal">WITH NO DATA</code> is specified no new
+ data is generated and the materialized view is left in an unscannable
+ state.
+ </p><p>
+ <code class="literal">CONCURRENTLY</code> and <code class="literal">WITH NO DATA</code> may not
+ be specified together.
+ </p></div><div class="refsect1" id="id-1.9.3.162.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">CONCURRENTLY</code></span></dt><dd><p>
+ Refresh the materialized view without locking out concurrent selects on
+ the materialized view. Without this option a refresh which affects a
+ lot of rows will tend to use fewer resources and complete more quickly,
+ but could block other connections which are trying to read from the
+ materialized view. This option may be faster in cases where a small
+ number of rows are affected.
+ </p><p>
+ This option is only allowed if there is at least one
+ <code class="literal">UNIQUE</code> index on the materialized view which uses only
+ column names and includes all rows; that is, it must not be an
+ expression index or include a <code class="literal">WHERE</code> clause.
+ </p><p>
+ This option may not be used when the materialized view is not already
+ populated.
+ </p><p>
+ Even with this option only one <code class="literal">REFRESH</code> at a time may
+ run against any one materialized view.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the materialized view to
+ refresh.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.162.7"><h2>Notes</h2><p>
+ If there is an <code class="literal">ORDER BY</code> clause in the materialized
+ view's defining query, the original contents of the materialized view
+ will be ordered that way; but <code class="command">REFRESH MATERIALIZED
+ VIEW</code> does not guarantee to preserve that ordering.
+ </p></div><div class="refsect1" id="id-1.9.3.162.8"><h2>Examples</h2><p>
+ This command will replace the contents of the materialized view called
+ <code class="literal">order_summary</code> using the query from the materialized
+ view's definition, and leave it in a scannable state:
+</p><pre class="programlisting">
+REFRESH MATERIALIZED VIEW order_summary;
+</pre><p>
+ </p><p>
+ This command will free storage associated with the materialized view
+ <code class="literal">annual_statistics_basis</code> and leave it in an unscannable
+ state:
+</p><pre class="programlisting">
+REFRESH MATERIALIZED VIEW annual_statistics_basis WITH NO DATA;
+</pre></div><div class="refsect1" id="id-1.9.3.162.9"><h2>Compatibility</h2><p>
+ <code class="command">REFRESH MATERIALIZED VIEW</code> is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.162.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW"><span class="refentrytitle">CREATE MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-altermaterializedview.html" title="ALTER MATERIALIZED VIEW"><span class="refentrytitle">ALTER MATERIALIZED VIEW</span></a>, <a class="xref" href="sql-dropmaterializedview.html" title="DROP MATERIALIZED VIEW"><span class="refentrytitle">DROP MATERIALIZED VIEW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-reassign-owned.html" title="REASSIGN OWNED">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-reindex.html" title="REINDEX">Next</a></td></tr><tr><td width="40%" align="left" valign="top">REASSIGN OWNED </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> REINDEX</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-reindex.html b/doc/src/sgml/html/sql-reindex.html
new file mode 100644
index 0000000..82a0ee2
--- /dev/null
+++ b/doc/src/sgml/html/sql-reindex.html
@@ -0,0 +1,327 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>REINDEX</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW" /><link rel="next" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">REINDEX</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-REINDEX"><div class="titlepage"></div><a id="id-1.9.3.163.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">REINDEX</span></h2><p>REINDEX — rebuild indexes</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+REINDEX [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURRENTLY ] <em class="replaceable"><code>name</code></em>
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ CONCURRENTLY [ <em class="replaceable"><code>boolean</code></em> ]
+ TABLESPACE <em class="replaceable"><code>new_tablespace</code></em>
+ VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
+</pre></div><div class="refsect1" id="id-1.9.3.163.5"><h2>Description</h2><p>
+ <code class="command">REINDEX</code> rebuilds an index using the data
+ stored in the index's table, replacing the old copy of the index. There are
+ several scenarios in which to use <code class="command">REINDEX</code>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ An index has become corrupted, and no longer contains valid
+ data. Although in theory this should never happen, in
+ practice indexes can become corrupted due to software bugs or
+ hardware failures. <code class="command">REINDEX</code> provides a
+ recovery method.
+ </p></li><li class="listitem"><p>
+ An index has become <span class="quote">“<span class="quote">bloated</span>”</span>, that is it contains many
+ empty or nearly-empty pages. This can occur with B-tree indexes in
+ <span class="productname">PostgreSQL</span> under certain uncommon access
+ patterns. <code class="command">REINDEX</code> provides a way to reduce
+ the space consumption of the index by writing a new version of
+ the index without the dead pages. See <a class="xref" href="routine-reindex.html" title="25.2. Routine Reindexing">Section 25.2</a> for more information.
+ </p></li><li class="listitem"><p>
+ You have altered a storage parameter (such as fillfactor)
+ for an index, and wish to ensure that the change has taken full effect.
+ </p></li><li class="listitem"><p>
+ If an index build fails with the <code class="literal">CONCURRENTLY</code> option,
+ this index is left as <span class="quote">“<span class="quote">invalid</span>”</span>. Such indexes are useless
+ but it can be convenient to use <code class="command">REINDEX</code> to rebuild
+ them. Note that only <code class="command">REINDEX INDEX</code> is able
+ to perform a concurrent build on an invalid index.
+ </p></li></ul></div></div><div class="refsect1" id="id-1.9.3.163.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">INDEX</code></span></dt><dd><p>
+ Recreate the specified index. This form of <code class="command">REINDEX</code>
+ cannot be executed inside a transaction block when used with a
+ partitioned index.
+ </p></dd><dt><span class="term"><code class="literal">TABLE</code></span></dt><dd><p>
+ Recreate all indexes of the specified table. If the table has a
+ secondary <span class="quote">“<span class="quote">TOAST</span>”</span> table, that is reindexed as well.
+ This form of <code class="command">REINDEX</code> cannot be executed inside a
+ transaction block when used with a partitioned table.
+ </p></dd><dt><span class="term"><code class="literal">SCHEMA</code></span></dt><dd><p>
+ Recreate all indexes of the specified schema. If a table of this
+ schema has a secondary <span class="quote">“<span class="quote">TOAST</span>”</span> table, that is reindexed as
+ well. Indexes on shared system catalogs are also processed.
+ This form of <code class="command">REINDEX</code> cannot be executed inside a
+ transaction block.
+ </p></dd><dt><span class="term"><code class="literal">DATABASE</code></span></dt><dd><p>
+ Recreate all indexes within the current database.
+ Indexes on shared system catalogs are also processed.
+ This form of <code class="command">REINDEX</code> cannot be executed inside a
+ transaction block.
+ </p></dd><dt><span class="term"><code class="literal">SYSTEM</code></span></dt><dd><p>
+ Recreate all indexes on system catalogs within the current database.
+ Indexes on shared system catalogs are included.
+ Indexes on user tables are not processed.
+ This form of <code class="command">REINDEX</code> cannot be executed inside a
+ transaction block.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of the specific index, table, or database to be
+ reindexed. Index and table names can be schema-qualified.
+ Presently, <code class="command">REINDEX DATABASE</code> and <code class="command">REINDEX SYSTEM</code>
+ can only reindex the current database, so their parameter must match
+ the current database's name.
+ </p></dd><dt><span class="term"><code class="literal">CONCURRENTLY</code></span></dt><dd><p>
+ When this option is used, <span class="productname">PostgreSQL</span> will rebuild the
+ index without taking any locks that prevent concurrent inserts,
+ updates, or deletes on the table; whereas a standard index rebuild
+ locks out writes (but not reads) on the table until it's done.
+ There are several caveats to be aware of when using this option
+ — see <a class="xref" href="sql-reindex.html#SQL-REINDEX-CONCURRENTLY" title="Rebuilding Indexes Concurrently">Rebuilding Indexes Concurrently</a> below.
+ </p><p>
+ For temporary tables, <code class="command">REINDEX</code> is always
+ non-concurrent, as no other session can access them, and
+ non-concurrent reindex is cheaper.
+ </p></dd><dt><span class="term"><code class="literal">TABLESPACE</code></span></dt><dd><p>
+ Specifies that indexes will be rebuilt on a new tablespace.
+ </p></dd><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
+ Prints a progress report as each index is reindexed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_tablespace</code></em></span></dt><dd><p>
+ The tablespace where indexes will be rebuilt.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.163.7"><h2>Notes</h2><p>
+ If you suspect corruption of an index on a user table, you can
+ simply rebuild that index, or all indexes on the table, using
+ <code class="command">REINDEX INDEX</code> or <code class="command">REINDEX TABLE</code>.
+ </p><p>
+ Things are more difficult if you need to recover from corruption of
+ an index on a system table. In this case it's important for the
+ system to not have used any of the suspect indexes itself.
+ (Indeed, in this sort of scenario you might find that server
+ processes are crashing immediately at start-up, due to reliance on
+ the corrupted indexes.) To recover safely, the server must be started
+ with the <code class="option">-P</code> option, which prevents it from using
+ indexes for system catalog lookups.
+ </p><p>
+ One way to do this is to shut down the server and start a single-user
+ <span class="productname">PostgreSQL</span> server
+ with the <code class="option">-P</code> option included on its command line.
+ Then, <code class="command">REINDEX DATABASE</code>, <code class="command">REINDEX SYSTEM</code>,
+ <code class="command">REINDEX TABLE</code>, or <code class="command">REINDEX INDEX</code> can be
+ issued, depending on how much you want to reconstruct. If in
+ doubt, use <code class="command">REINDEX SYSTEM</code> to select
+ reconstruction of all system indexes in the database. Then quit
+ the single-user server session and restart the regular server.
+ See the <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a> reference page for more
+ information about how to interact with the single-user server
+ interface.
+ </p><p>
+ Alternatively, a regular server session can be started with
+ <code class="option">-P</code> included in its command line options.
+ The method for doing this varies across clients, but in all
+ <span class="application">libpq</span>-based clients, it is possible to set
+ the <code class="envar">PGOPTIONS</code> environment variable to <code class="literal">-P</code>
+ before starting the client. Note that while this method does not
+ require locking out other clients, it might still be wise to prevent
+ other users from connecting to the damaged database until repairs
+ have been completed.
+ </p><p>
+ <code class="command">REINDEX</code> is similar to a drop and recreate of the index
+ in that the index contents are rebuilt from scratch. However, the locking
+ considerations are rather different. <code class="command">REINDEX</code> locks out writes
+ but not reads of the index's parent table. It also takes an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the specific index being processed,
+ which will block reads that attempt to use that index. In particular,
+ the query planner tries to take an <code class="literal">ACCESS SHARE</code>
+ lock on every index of the table, regardless of the query, and so
+ <code class="command">REINDEX</code> blocks virtually any queries except for some
+ prepared queries whose plan has been cached and which don't use this very
+ index. In contrast,
+ <code class="command">DROP INDEX</code> momentarily takes an
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the parent table, blocking both
+ writes and reads. The subsequent <code class="command">CREATE INDEX</code> locks out
+ writes but not reads; since the index is not there, no read will attempt to
+ use it, meaning that there will be no blocking but reads might be forced
+ into expensive sequential scans.
+ </p><p>
+ Reindexing a single index or table requires being the owner of that
+ index or table. Reindexing a schema or database requires being the
+ owner of that schema or database. Note specifically that it's thus
+ possible for non-superusers to rebuild indexes of tables owned by
+ other users. However, as a special exception, when
+ <code class="command">REINDEX DATABASE</code>, <code class="command">REINDEX SCHEMA</code>
+ or <code class="command">REINDEX SYSTEM</code> is issued by a non-superuser,
+ indexes on shared catalogs will be skipped unless the user owns the
+ catalog (which typically won't be the case). Of course, superusers
+ can always reindex anything.
+ </p><p>
+ Reindexing partitioned indexes or partitioned tables is supported
+ with <code class="command">REINDEX INDEX</code> or <code class="command">REINDEX TABLE</code>,
+ respectively. Each partition of the specified partitioned relation is
+ reindexed in a separate transaction. Those commands cannot be used inside
+ a transaction block when working on a partitioned table or index.
+ </p><p>
+ When using the <code class="literal">TABLESPACE</code> clause with
+ <code class="command">REINDEX</code> on a partitioned index or table, only the
+ tablespace references of the leaf partitions are updated. As partitioned
+ indexes are not updated, it is recommended to separately use
+ <code class="command">ALTER TABLE ONLY</code> on them so as any new partitions
+ attached inherit the new tablespace. On failure, it may not have moved
+ all the indexes to the new tablespace. Re-running the command will rebuild
+ all the leaf partitions and move previously-unprocessed indexes to the new
+ tablespace.
+ </p><p>
+ If <code class="literal">SCHEMA</code>, <code class="literal">DATABASE</code> or
+ <code class="literal">SYSTEM</code> is used with <code class="literal">TABLESPACE</code>,
+ system relations are skipped and a single <code class="literal">WARNING</code>
+ will be generated. Indexes on TOAST tables are rebuilt, but not moved
+ to the new tablespace.
+ </p><div class="refsect2" id="SQL-REINDEX-CONCURRENTLY"><h3>Rebuilding Indexes Concurrently</h3><a id="id-1.9.3.163.7.11.2" class="indexterm"></a><p>
+ Rebuilding an index can interfere with regular operation of a database.
+ Normally <span class="productname">PostgreSQL</span> locks the table whose index is rebuilt
+ against writes and performs the entire index build with a single scan of the
+ table. Other transactions can still read the table, but if they try to
+ insert, update, or delete rows in the table they will block until the
+ index rebuild is finished. This could have a severe effect if the system is
+ a live production database. Very large tables can take many hours to be
+ indexed, and even for smaller tables, an index rebuild can lock out writers
+ for periods that are unacceptably long for a production system.
+ </p><p>
+ <span class="productname">PostgreSQL</span> supports rebuilding indexes with minimum locking
+ of writes. This method is invoked by specifying the
+ <code class="literal">CONCURRENTLY</code> option of <code class="command">REINDEX</code>. When this option
+ is used, <span class="productname">PostgreSQL</span> must perform two scans of the table
+ for each index that needs to be rebuilt and wait for termination of
+ all existing transactions that could potentially use the index.
+ This method requires more total work than a standard index
+ rebuild and takes significantly longer to complete as it needs to wait
+ for unfinished transactions that might modify the index. However, since
+ it allows normal operations to continue while the index is being rebuilt, this
+ method is useful for rebuilding indexes in a production environment. Of
+ course, the extra CPU, memory and I/O load imposed by the index rebuild
+ may slow down other operations.
+ </p><p>
+ The following steps occur in a concurrent reindex. Each step is run in a
+ separate transaction. If there are multiple indexes to be rebuilt, then
+ each step loops through all the indexes before moving to the next step.
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ A new transient index definition is added to the catalog
+ <code class="literal">pg_index</code>. This definition will be used to replace
+ the old index. A <code class="literal">SHARE UPDATE EXCLUSIVE</code> lock at
+ session level is taken on the indexes being reindexed as well as their
+ associated tables to prevent any schema modification while processing.
+ </p></li><li class="listitem"><p>
+ A first pass to build the index is done for each new index. Once the
+ index is built, its flag <code class="literal">pg_index.indisready</code> is
+ switched to <span class="quote">“<span class="quote">true</span>”</span> to make it ready for inserts, making it
+ visible to other sessions once the transaction that performed the build
+ is finished. This step is done in a separate transaction for each
+ index.
+ </p></li><li class="listitem"><p>
+ Then a second pass is performed to add tuples that were added while the
+ first pass was running. This step is also done in a separate
+ transaction for each index.
+ </p></li><li class="listitem"><p>
+ All the constraints that refer to the index are changed to refer to the
+ new index definition, and the names of the indexes are changed. At
+ this point, <code class="literal">pg_index.indisvalid</code> is switched to
+ <span class="quote">“<span class="quote">true</span>”</span> for the new index and to <span class="quote">“<span class="quote">false</span>”</span> for
+ the old, and a cache invalidation is done causing all sessions that
+ referenced the old index to be invalidated.
+ </p></li><li class="listitem"><p>
+ The old indexes have <code class="literal">pg_index.indisready</code> switched to
+ <span class="quote">“<span class="quote">false</span>”</span> to prevent any new tuple insertions, after waiting
+ for running queries that might reference the old index to complete.
+ </p></li><li class="listitem"><p>
+ The old indexes are dropped. The <code class="literal">SHARE UPDATE
+ EXCLUSIVE</code> session locks for the indexes and the table are
+ released.
+ </p></li></ol></div><p>
+ </p><p>
+ If a problem arises while rebuilding the indexes, such as a
+ uniqueness violation in a unique index, the <code class="command">REINDEX</code>
+ command will fail but leave behind an <span class="quote">“<span class="quote">invalid</span>”</span> new index in addition to
+ the pre-existing one. This index will be ignored for querying purposes
+ because it might be incomplete; however it will still consume update
+ overhead. The <span class="application">psql</span> <code class="command">\d</code> command will report
+ such an index as <code class="literal">INVALID</code>:
+
+</p><pre class="programlisting">
+postgres=# \d tab
+ Table "public.tab"
+ Column | Type | Modifiers
+--------+---------+-----------
+ col | integer |
+Indexes:
+ "idx" btree (col)
+ "idx_ccnew" btree (col) INVALID
+</pre><p>
+
+ If the index marked <code class="literal">INVALID</code> is suffixed
+ <code class="literal">ccnew</code>, then it corresponds to the transient
+ index created during the concurrent operation, and the recommended
+ recovery method is to drop it using <code class="literal">DROP INDEX</code>,
+ then attempt <code class="command">REINDEX CONCURRENTLY</code> again.
+ If the invalid index is instead suffixed <code class="literal">ccold</code>,
+ it corresponds to the original index which could not be dropped;
+ the recommended recovery method is to just drop said index, since the
+ rebuild proper has been successful.
+ </p><p>
+ Regular index builds permit other regular index builds on the same table
+ to occur simultaneously, but only one concurrent index build can occur on a
+ table at a time. In both cases, no other types of schema modification on
+ the table are allowed meanwhile. Another difference is that a regular
+ <code class="command">REINDEX TABLE</code> or <code class="command">REINDEX INDEX</code>
+ command can be performed within a transaction block, but <code class="command">REINDEX
+ CONCURRENTLY</code> cannot.
+ </p><p>
+ Like any long-running transaction, <code class="command">REINDEX</code> on a table
+ can affect which tuples can be removed by concurrent
+ <code class="command">VACUUM</code> on any other table.
+ </p><p>
+ <code class="command">REINDEX SYSTEM</code> does not support
+ <code class="command">CONCURRENTLY</code> since system catalogs cannot be reindexed
+ concurrently.
+ </p><p>
+ Furthermore, indexes for exclusion constraints cannot be reindexed
+ concurrently. If such an index is named directly in this command, an
+ error is raised. If a table or database with exclusion constraint indexes
+ is reindexed concurrently, those indexes will be skipped. (It is possible
+ to reindex such indexes without the <code class="command">CONCURRENTLY</code> option.)
+ </p><p>
+ Each backend running <code class="command">REINDEX</code> will report its progress
+ in the <code class="structname">pg_stat_progress_create_index</code> view. See
+ <a class="xref" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING" title="28.4.2. CREATE INDEX Progress Reporting">Section 28.4.2</a> for details.
+ </p></div></div><div class="refsect1" id="id-1.9.3.163.8"><h2>Examples</h2><p>
+ Rebuild a single index:
+
+</p><pre class="programlisting">
+REINDEX INDEX my_index;
+</pre><p>
+ </p><p>
+ Rebuild all the indexes on the table <code class="literal">my_table</code>:
+
+</p><pre class="programlisting">
+REINDEX TABLE my_table;
+</pre><p>
+ </p><p>
+ Rebuild all indexes in a particular database, without trusting the
+ system indexes to be valid already:
+
+</p><pre class="programlisting">
+$ <strong class="userinput"><code>export PGOPTIONS="-P"</code></strong>
+$ <strong class="userinput"><code>psql broken_db</code></strong>
+...
+broken_db=&gt; REINDEX DATABASE broken_db;
+broken_db=&gt; \q
+</pre><p>
+ Rebuild indexes for a table, without blocking read and write operations
+ on involved relations while reindexing is in progress:
+
+</p><pre class="programlisting">
+REINDEX TABLE CONCURRENTLY my_broken_table;
+</pre></div><div class="refsect1" id="id-1.9.3.163.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">REINDEX</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.163.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>, <a class="xref" href="sql-dropindex.html" title="DROP INDEX"><span class="refentrytitle">DROP INDEX</span></a>, <a class="xref" href="app-reindexdb.html" title="reindexdb"><span class="refentrytitle"><span class="application">reindexdb</span></span></a>, <a class="xref" href="progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING" title="28.4.2. CREATE INDEX Progress Reporting">Section 28.4.2</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-refreshmaterializedview.html" title="REFRESH MATERIALIZED VIEW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">REFRESH MATERIALIZED VIEW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> RELEASE SAVEPOINT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-release-savepoint.html b/doc/src/sgml/html/sql-release-savepoint.html
new file mode 100644
index 0000000..312aca2
--- /dev/null
+++ b/doc/src/sgml/html/sql-release-savepoint.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>RELEASE SAVEPOINT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-reindex.html" title="REINDEX" /><link rel="next" href="sql-reset.html" title="RESET" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">RELEASE SAVEPOINT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-reindex.html" title="REINDEX">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-reset.html" title="RESET">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-RELEASE-SAVEPOINT"><div class="titlepage"></div><a id="id-1.9.3.164.1" class="indexterm"></a><a id="id-1.9.3.164.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">RELEASE SAVEPOINT</span></h2><p>RELEASE SAVEPOINT — destroy a previously defined savepoint</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+RELEASE [ SAVEPOINT ] <em class="replaceable"><code>savepoint_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.164.6"><h2>Description</h2><p>
+ <code class="command">RELEASE SAVEPOINT</code> destroys a savepoint previously defined
+ in the current transaction.
+ </p><p>
+ Destroying a savepoint makes it unavailable as a rollback point,
+ but it has no other user visible behavior. It does not undo the
+ effects of commands executed after the savepoint was established.
+ (To do that, see <a class="xref" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT"><span class="refentrytitle">ROLLBACK TO SAVEPOINT</span></a>.)
+ Destroying a savepoint when
+ it is no longer needed allows the system to reclaim some resources
+ earlier than transaction end.
+ </p><p>
+ <code class="command">RELEASE SAVEPOINT</code> also destroys all savepoints that were
+ established after the named savepoint was established.
+ </p></div><div class="refsect1" id="id-1.9.3.164.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>savepoint_name</code></em></span></dt><dd><p>
+ The name of the savepoint to destroy.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.164.8"><h2>Notes</h2><p>
+ Specifying a savepoint name that was not previously defined is an error.
+ </p><p>
+ It is not possible to release a savepoint when the transaction is in
+ an aborted state.
+ </p><p>
+ If multiple savepoints have the same name, only the most recently defined
+ unreleased one is released. Repeated commands will release progressively
+ older savepoints.
+ </p></div><div class="refsect1" id="id-1.9.3.164.9"><h2>Examples</h2><p>
+ To establish and later destroy a savepoint:
+</p><pre class="programlisting">
+BEGIN;
+ INSERT INTO table1 VALUES (3);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (4);
+ RELEASE SAVEPOINT my_savepoint;
+COMMIT;
+</pre><p>
+ The above transaction will insert both 3 and 4.
+ </p></div><div class="refsect1" id="id-1.9.3.164.10"><h2>Compatibility</h2><p>
+ This command conforms to the <acronym class="acronym">SQL</acronym> standard. The standard
+ specifies that the key word <code class="literal">SAVEPOINT</code> is
+ mandatory, but <span class="productname">PostgreSQL</span> allows it to
+ be omitted.
+ </p></div><div class="refsect1" id="id-1.9.3.164.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>, <a class="xref" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT"><span class="refentrytitle">ROLLBACK TO SAVEPOINT</span></a>, <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-reindex.html" title="REINDEX">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-reset.html" title="RESET">Next</a></td></tr><tr><td width="40%" align="left" valign="top">REINDEX </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> RESET</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-reset.html b/doc/src/sgml/html/sql-reset.html
new file mode 100644
index 0000000..649aa6b
--- /dev/null
+++ b/doc/src/sgml/html/sql-reset.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>RESET</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT" /><link rel="next" href="sql-revoke.html" title="REVOKE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">RESET</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-revoke.html" title="REVOKE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-RESET"><div class="titlepage"></div><a id="id-1.9.3.165.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">RESET</span></h2><p>RESET — restore the value of a run-time parameter to the default value</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+RESET <em class="replaceable"><code>configuration_parameter</code></em>
+RESET ALL
+</pre></div><div class="refsect1" id="id-1.9.3.165.5"><h2>Description</h2><p>
+ <code class="command">RESET</code> restores run-time parameters to their
+ default values. <code class="command">RESET</code> is an alternative
+ spelling for
+</p><pre class="synopsis">
+SET <em class="replaceable"><code>configuration_parameter</code></em> TO DEFAULT
+</pre><p>
+ Refer to <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> for
+ details.
+ </p><p>
+ The default value is defined as the value that the parameter would
+ have had, if no <code class="command">SET</code> had ever been issued for it in the
+ current session. The actual source of this value might be a
+ compiled-in default, the configuration file, command-line options,
+ or per-database or per-user default settings. This is subtly different
+ from defining it as <span class="quote">“<span class="quote">the value that the parameter had at session
+ start</span>”</span>, because if the value came from the configuration file, it
+ will be reset to whatever is specified by the configuration file now.
+ See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for details.
+ </p><p>
+ The transactional behavior of <code class="command">RESET</code> is the same as
+ <code class="command">SET</code>: its effects will be undone by transaction rollback.
+ </p></div><div class="refsect1" id="id-1.9.3.165.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em></span></dt><dd><p>
+ Name of a settable run-time parameter. Available parameters are
+ documented in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> and on the
+ <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> reference page.
+ </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Resets all settable run-time parameters to default values.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.165.7"><h2>Examples</h2><p>
+ Set the <code class="varname">timezone</code> configuration variable to its default value:
+</p><pre class="screen">
+RESET timezone;
+</pre></div><div class="refsect1" id="id-1.9.3.165.8"><h2>Compatibility</h2><p>
+ <code class="command">RESET</code> is a <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.165.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>, <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-revoke.html" title="REVOKE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">RELEASE SAVEPOINT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> REVOKE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-revoke.html b/doc/src/sgml/html/sql-revoke.html
new file mode 100644
index 0000000..085011c
--- /dev/null
+++ b/doc/src/sgml/html/sql-revoke.html
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>REVOKE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-reset.html" title="RESET" /><link rel="next" href="sql-rollback.html" title="ROLLBACK" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">REVOKE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-reset.html" title="RESET">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-rollback.html" title="ROLLBACK">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-REVOKE"><div class="titlepage"></div><a id="id-1.9.3.166.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">REVOKE</span></h2><p>REVOKE — remove access privileges</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+REVOKE [ GRANT OPTION FOR ]
+ { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON { [ TABLE ] <em class="replaceable"><code>table_name</code></em> [, ...]
+ | ALL TABLES IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { SELECT | INSERT | UPDATE | REFERENCES } ( <em class="replaceable"><code>column_name</code></em> [, ...] )
+ [, ...] | ALL [ PRIVILEGES ] ( <em class="replaceable"><code>column_name</code></em> [, ...] ) }
+ ON [ TABLE ] <em class="replaceable"><code>table_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { USAGE | SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON { SEQUENCE <em class="replaceable"><code>sequence_name</code></em> [, ...]
+ | ALL SEQUENCES IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { CREATE | CONNECT | TEMPORARY | TEMP } [, ...] | ALL [ PRIVILEGES ] }
+ ON DATABASE <em class="replaceable"><code>database_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON DOMAIN <em class="replaceable"><code>domain_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON FOREIGN DATA WRAPPER <em class="replaceable"><code>fdw_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON FOREIGN SERVER <em class="replaceable"><code>server_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { EXECUTE | ALL [ PRIVILEGES ] }
+ ON { { FUNCTION | PROCEDURE | ROUTINE } <em class="replaceable"><code>function_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>arg_name</code></em> ] <em class="replaceable"><code>arg_type</code></em> [, ...] ] ) ] [, ...]
+ | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...] }
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON LANGUAGE <em class="replaceable"><code>lang_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { SELECT | UPDATE } [, ...] | ALL [ PRIVILEGES ] }
+ ON LARGE OBJECT <em class="replaceable"><code>loid</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { SET | ALTER SYSTEM } [, ...] | ALL [ PRIVILEGES ] }
+ ON PARAMETER <em class="replaceable"><code>configuration_parameter</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] }
+ ON SCHEMA <em class="replaceable"><code>schema_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { CREATE | ALL [ PRIVILEGES ] }
+ ON TABLESPACE <em class="replaceable"><code>tablespace_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { USAGE | ALL [ PRIVILEGES ] }
+ ON TYPE <em class="replaceable"><code>type_name</code></em> [, ...]
+ FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+REVOKE [ ADMIN OPTION FOR ]
+ <em class="replaceable"><code>role_name</code></em> [, ...] FROM <em class="replaceable"><code>role_specification</code></em> [, ...]
+ [ GRANTED BY <em class="replaceable"><code>role_specification</code></em> ]
+ [ CASCADE | RESTRICT ]
+
+<span class="phrase">where <em class="replaceable"><code>role_specification</code></em> can be:</span>
+
+ [ GROUP ] <em class="replaceable"><code>role_name</code></em>
+ | PUBLIC
+ | CURRENT_ROLE
+ | CURRENT_USER
+ | SESSION_USER
+</pre></div><div class="refsect1" id="SQL-REVOKE-DESCRIPTION"><h2>Description</h2><p>
+ The <code class="command">REVOKE</code> command revokes previously granted
+ privileges from one or more roles. The key word
+ <code class="literal">PUBLIC</code> refers to the implicitly defined group of
+ all roles.
+ </p><p>
+ See the description of the <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> command for
+ the meaning of the privilege types.
+ </p><p>
+ Note that any particular role will have the sum
+ of privileges granted directly to it, privileges granted to any role it
+ is presently a member of, and privileges granted to
+ <code class="literal">PUBLIC</code>. Thus, for example, revoking <code class="literal">SELECT</code> privilege
+ from <code class="literal">PUBLIC</code> does not necessarily mean that all roles
+ have lost <code class="literal">SELECT</code> privilege on the object: those who have it granted
+ directly or via another role will still have it. Similarly, revoking
+ <code class="literal">SELECT</code> from a user might not prevent that user from using
+ <code class="literal">SELECT</code> if <code class="literal">PUBLIC</code> or another membership
+ role still has <code class="literal">SELECT</code> rights.
+ </p><p>
+ If <code class="literal">GRANT OPTION FOR</code> is specified, only the grant
+ option for the privilege is revoked, not the privilege itself.
+ Otherwise, both the privilege and the grant option are revoked.
+ </p><p>
+ If a user holds a privilege with grant option and has granted it to
+ other users then the privileges held by those other users are
+ called dependent privileges. If the privilege or the grant option
+ held by the first user is being revoked and dependent privileges
+ exist, those dependent privileges are also revoked if
+ <code class="literal">CASCADE</code> is specified; if it is not, the revoke action
+ will fail. This recursive revocation only affects privileges that
+ were granted through a chain of users that is traceable to the user
+ that is the subject of this <code class="literal">REVOKE</code> command.
+ Thus, the affected users might effectively keep the privilege if it
+ was also granted through other users.
+ </p><p>
+ When revoking privileges on a table, the corresponding column privileges
+ (if any) are automatically revoked on each column of the table, as well.
+ On the other hand, if a role has been granted privileges on a table, then
+ revoking the same privileges from individual columns will have no effect.
+ </p><p>
+ When revoking membership in a role, <code class="literal">GRANT OPTION</code> is instead
+ called <code class="literal">ADMIN OPTION</code>, but the behavior is similar.
+ This form of the command also allows a <code class="literal">GRANTED BY</code>
+ option, but that option is currently ignored (except for checking
+ the existence of the named role).
+ Note also that this form of the command does not
+ allow the noise word <code class="literal">GROUP</code>
+ in <em class="replaceable"><code>role_specification</code></em>.
+ </p></div><div class="refsect1" id="SQL-REVOKE-NOTES"><h2>Notes</h2><p>
+ A user can only revoke privileges that were granted directly by
+ that user. If, for example, user A has granted a privilege with
+ grant option to user B, and user B has in turn granted it to user
+ C, then user A cannot revoke the privilege directly from C.
+ Instead, user A could revoke the grant option from user B and use
+ the <code class="literal">CASCADE</code> option so that the privilege is
+ in turn revoked from user C. For another example, if both A and B
+ have granted the same privilege to C, A can revoke their own grant
+ but not B's grant, so C will still effectively have the privilege.
+ </p><p>
+ When a non-owner of an object attempts to <code class="command">REVOKE</code> privileges
+ on the object, the command will fail outright if the user has no
+ privileges whatsoever on the object. As long as some privilege is
+ available, the command will proceed, but it will revoke only those
+ privileges for which the user has grant options. The <code class="command">REVOKE ALL
+ PRIVILEGES</code> forms will issue a warning message if no grant options are
+ held, while the other forms will issue a warning if grant options for
+ any of the privileges specifically named in the command are not held.
+ (In principle these statements apply to the object owner as well, but
+ since the owner is always treated as holding all grant options, the
+ cases can never occur.)
+ </p><p>
+ If a superuser chooses to issue a <code class="command">GRANT</code> or <code class="command">REVOKE</code>
+ command, the command is performed as though it were issued by the
+ owner of the affected object. Since all privileges ultimately come
+ from the object owner (possibly indirectly via chains of grant options),
+ it is possible for a superuser to revoke all privileges, but this might
+ require use of <code class="literal">CASCADE</code> as stated above.
+ </p><p>
+ <code class="command">REVOKE</code> can also be done by a role
+ that is not the owner of the affected object, but is a member of the role
+ that owns the object, or is a member of a role that holds privileges
+ <code class="literal">WITH GRANT OPTION</code> on the object. In this case the
+ command is performed as though it were issued by the containing role that
+ actually owns the object or holds the privileges
+ <code class="literal">WITH GRANT OPTION</code>. For example, if table
+ <code class="literal">t1</code> is owned by role <code class="literal">g1</code>, of which role
+ <code class="literal">u1</code> is a member, then <code class="literal">u1</code> can revoke privileges
+ on <code class="literal">t1</code> that are recorded as being granted by <code class="literal">g1</code>.
+ This would include grants made by <code class="literal">u1</code> as well as by other
+ members of role <code class="literal">g1</code>.
+ </p><p>
+ If the role executing <code class="command">REVOKE</code> holds privileges
+ indirectly via more than one role membership path, it is unspecified
+ which containing role will be used to perform the command. In such cases
+ it is best practice to use <code class="command">SET ROLE</code> to become the specific
+ role you want to do the <code class="command">REVOKE</code> as. Failure to do so might
+ lead to revoking privileges other than the ones you intended, or not
+ revoking anything at all.
+ </p><p>
+ See <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a> for more information about specific
+ privilege types, as well as how to inspect objects' privileges.
+ </p></div><div class="refsect1" id="SQL-REVOKE-EXAMPLES"><h2>Examples</h2><p>
+ Revoke insert privilege for the public on table
+ <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+REVOKE INSERT ON films FROM PUBLIC;
+</pre><p>
+ </p><p>
+ Revoke all privileges from user <code class="literal">manuel</code> on view
+ <code class="literal">kinds</code>:
+
+</p><pre class="programlisting">
+REVOKE ALL PRIVILEGES ON kinds FROM manuel;
+</pre><p>
+
+ Note that this actually means <span class="quote">“<span class="quote">revoke all privileges that I
+ granted</span>”</span>.
+ </p><p>
+ Revoke membership in role <code class="literal">admins</code> from user <code class="literal">joe</code>:
+
+</p><pre class="programlisting">
+REVOKE admins FROM joe;
+</pre></div><div class="refsect1" id="SQL-REVOKE-COMPATIBILITY"><h2>Compatibility</h2><p>
+ The compatibility notes of the <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> command
+ apply analogously to <code class="command">REVOKE</code>.
+ The keyword <code class="literal">RESTRICT</code> or <code class="literal">CASCADE</code>
+ is required according to the standard, but <span class="productname">PostgreSQL</span>
+ assumes <code class="literal">RESTRICT</code> by default.
+ </p></div><div class="refsect1" id="id-1.9.3.166.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES"><span class="refentrytitle">ALTER DEFAULT PRIVILEGES</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-reset.html" title="RESET">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-rollback.html" title="ROLLBACK">Next</a></td></tr><tr><td width="40%" align="left" valign="top">RESET </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ROLLBACK</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-rollback-prepared.html b/doc/src/sgml/html/sql-rollback-prepared.html
new file mode 100644
index 0000000..36be571
--- /dev/null
+++ b/doc/src/sgml/html/sql-rollback-prepared.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ROLLBACK PREPARED</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-rollback.html" title="ROLLBACK" /><link rel="next" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ROLLBACK PREPARED</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-rollback.html" title="ROLLBACK">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ROLLBACK-PREPARED"><div class="titlepage"></div><a id="id-1.9.3.168.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ROLLBACK PREPARED</span></h2><p>ROLLBACK PREPARED — cancel a transaction that was earlier prepared for two-phase commit</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ROLLBACK PREPARED <em class="replaceable"><code>transaction_id</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.168.5"><h2>Description</h2><p>
+ <code class="command">ROLLBACK PREPARED</code> rolls back a transaction that is in
+ prepared state.
+ </p></div><div class="refsect1" id="id-1.9.3.168.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p>
+ The transaction identifier of the transaction that is to be
+ rolled back.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.168.7"><h2>Notes</h2><p>
+ To roll back a prepared transaction, you must be either the same user that
+ executed the transaction originally, or a superuser. But you do not
+ have to be in the same session that executed the transaction.
+ </p><p>
+ This command cannot be executed inside a transaction block. The prepared
+ transaction is rolled back immediately.
+ </p><p>
+ All currently available prepared transactions are listed in the
+ <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a>
+ system view.
+ </p></div><div class="refsect1" id="SQL-ROLLBACK-PREPARED-EXAMPLES"><h2>Examples</h2><p>
+ Roll back the transaction identified by the transaction
+ identifier <code class="literal">foobar</code>:
+
+</p><pre class="programlisting">
+ROLLBACK PREPARED 'foobar';
+</pre></div><div class="refsect1" id="id-1.9.3.168.9"><h2>Compatibility</h2><p>
+ <code class="command">ROLLBACK PREPARED</code> is a
+ <span class="productname">PostgreSQL</span> extension. It is intended for use by
+ external transaction management systems, some of which are covered by
+ standards (such as X/Open XA), but the SQL side of those systems is not
+ standardized.
+ </p></div><div class="refsect1" id="id-1.9.3.168.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>, <a class="xref" href="sql-commit-prepared.html" title="COMMIT PREPARED"><span class="refentrytitle">COMMIT PREPARED</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-rollback.html" title="ROLLBACK">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ROLLBACK </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ROLLBACK TO SAVEPOINT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-rollback-to.html b/doc/src/sgml/html/sql-rollback-to.html
new file mode 100644
index 0000000..37218b2
--- /dev/null
+++ b/doc/src/sgml/html/sql-rollback-to.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ROLLBACK TO SAVEPOINT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED" /><link rel="next" href="sql-savepoint.html" title="SAVEPOINT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ROLLBACK TO SAVEPOINT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-savepoint.html" title="SAVEPOINT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ROLLBACK-TO"><div class="titlepage"></div><a id="id-1.9.3.169.1" class="indexterm"></a><a id="id-1.9.3.169.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ROLLBACK TO SAVEPOINT</span></h2><p>ROLLBACK TO SAVEPOINT — roll back to a savepoint</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <em class="replaceable"><code>savepoint_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.169.6"><h2>Description</h2><p>
+ Roll back all commands that were executed after the savepoint was
+ established. The savepoint remains valid and can be rolled back to
+ again later, if needed.
+ </p><p>
+ <code class="command">ROLLBACK TO SAVEPOINT</code> implicitly destroys all savepoints that
+ were established after the named savepoint.
+ </p></div><div class="refsect1" id="id-1.9.3.169.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>savepoint_name</code></em></span></dt><dd><p>
+ The savepoint to roll back to.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.169.8"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT"><code class="command">RELEASE SAVEPOINT</code></a> to destroy a savepoint
+ without discarding the effects of commands executed after it was
+ established.
+ </p><p>
+ Specifying a savepoint name that has not been established is an error.
+ </p><p>
+ Cursors have somewhat non-transactional behavior with respect to
+ savepoints. Any cursor that is opened inside a savepoint will be closed
+ when the savepoint is rolled back. If a previously opened cursor is
+ affected by a <code class="command">FETCH</code> or <code class="command">MOVE</code> command inside a
+ savepoint that is later rolled back, the cursor remains at the
+ position that <code class="command">FETCH</code> left it pointing to (that is, the cursor
+ motion caused by <code class="command">FETCH</code> is not rolled back).
+ Closing a cursor is not undone by rolling back, either.
+ However, other side-effects caused by the cursor's query (such as
+ side-effects of volatile functions called by the query) <span class="emphasis"><em>are</em></span>
+ rolled back if they occur during a savepoint that is later rolled back.
+ A cursor whose execution causes a transaction to abort is put in a
+ cannot-execute state, so while the transaction can be restored using
+ <code class="command">ROLLBACK TO SAVEPOINT</code>, the cursor can no longer be used.
+ </p></div><div class="refsect1" id="id-1.9.3.169.9"><h2>Examples</h2><p>
+ To undo the effects of the commands executed after <code class="literal">my_savepoint</code>
+ was established:
+</p><pre class="programlisting">
+ROLLBACK TO SAVEPOINT my_savepoint;
+</pre><p>
+ </p><p>
+ Cursor positions are not affected by savepoint rollback:
+</p><pre class="programlisting">
+BEGIN;
+
+DECLARE foo CURSOR FOR SELECT 1 UNION SELECT 2;
+
+SAVEPOINT foo;
+
+FETCH 1 FROM foo;
+ ?column?
+----------
+ 1
+
+ROLLBACK TO SAVEPOINT foo;
+
+FETCH 1 FROM foo;
+ ?column?
+----------
+ 2
+
+COMMIT;
+</pre></div><div class="refsect1" id="id-1.9.3.169.10"><h2>Compatibility</h2><p>
+ The <acronym class="acronym">SQL</acronym> standard specifies that the key word
+ <code class="literal">SAVEPOINT</code> is mandatory, but <span class="productname">PostgreSQL</span>
+ and <span class="productname">Oracle</span> allow it to be omitted. SQL allows
+ only <code class="literal">WORK</code>, not <code class="literal">TRANSACTION</code>, as a noise word
+ after <code class="literal">ROLLBACK</code>. Also, SQL has an optional clause
+ <code class="literal">AND [ NO ] CHAIN</code> which is not currently supported by
+ <span class="productname">PostgreSQL</span>. Otherwise, this command conforms to
+ the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.169.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT"><span class="refentrytitle">RELEASE SAVEPOINT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>, <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-savepoint.html" title="SAVEPOINT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ROLLBACK PREPARED </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SAVEPOINT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-rollback.html b/doc/src/sgml/html/sql-rollback.html
new file mode 100644
index 0000000..af8f48e
--- /dev/null
+++ b/doc/src/sgml/html/sql-rollback.html
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ROLLBACK</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-revoke.html" title="REVOKE" /><link rel="next" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ROLLBACK</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-revoke.html" title="REVOKE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ROLLBACK"><div class="titlepage"></div><a id="id-1.9.3.167.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ROLLBACK</span></h2><p>ROLLBACK — abort the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
+</pre></div><div class="refsect1" id="id-1.9.3.167.5"><h2>Description</h2><p>
+ <code class="command">ROLLBACK</code> rolls back the current transaction and causes
+ all the updates made by the transaction to be discarded.
+ </p></div><div class="refsect1" id="id-1.9.3.167.6"><h2>Parameters</h2><a id="id-1.9.3.167.6.2" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">WORK</code><br /></span><span class="term"><code class="literal">TRANSACTION</code></span></dt><dd><p>
+ Optional key words. They have no effect.
+ </p></dd><dt id="SQL-ROLLBACK-CHAIN"><span class="term"><code class="literal">AND CHAIN</code></span></dt><dd><p>
+ If <code class="literal">AND CHAIN</code> is specified, a new transaction is
+ immediately started with the same transaction characteristics (see <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a>) as the just finished one. Otherwise,
+ no new transaction is started.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.167.7"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-commit.html" title="COMMIT"><code class="command">COMMIT</code></a> to
+ successfully terminate a transaction.
+ </p><p>
+ Issuing <code class="command">ROLLBACK</code> outside of a transaction
+ block emits a warning and otherwise has no effect. <code class="command">ROLLBACK AND
+ CHAIN</code> outside of a transaction block is an error.
+ </p></div><div class="refsect1" id="id-1.9.3.167.8"><h2>Examples</h2><p>
+ To abort all changes:
+</p><pre class="programlisting">
+ROLLBACK;
+</pre></div><div class="refsect1" id="id-1.9.3.167.9"><h2>Compatibility</h2><p>
+ The command <code class="command">ROLLBACK</code> conforms to the SQL standard. The
+ form <code class="literal">ROLLBACK TRANSACTION</code> is a PostgreSQL extension.
+ </p></div><div class="refsect1" id="id-1.9.3.167.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT"><span class="refentrytitle">ROLLBACK TO SAVEPOINT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-revoke.html" title="REVOKE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED">Next</a></td></tr><tr><td width="40%" align="left" valign="top">REVOKE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ROLLBACK PREPARED</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-savepoint.html b/doc/src/sgml/html/sql-savepoint.html
new file mode 100644
index 0000000..8c32dcd
--- /dev/null
+++ b/doc/src/sgml/html/sql-savepoint.html
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SAVEPOINT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT" /><link rel="next" href="sql-security-label.html" title="SECURITY LABEL" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SAVEPOINT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-security-label.html" title="SECURITY LABEL">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SAVEPOINT"><div class="titlepage"></div><a id="id-1.9.3.170.1" class="indexterm"></a><a id="id-1.9.3.170.2" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SAVEPOINT</span></h2><p>SAVEPOINT — define a new savepoint within the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SAVEPOINT <em class="replaceable"><code>savepoint_name</code></em>
+</pre></div><div class="refsect1" id="id-1.9.3.170.6"><h2>Description</h2><p>
+ <code class="command">SAVEPOINT</code> establishes a new savepoint within
+ the current transaction.
+ </p><p>
+ A savepoint is a special mark inside a transaction that allows all commands
+ that are executed after it was established to be rolled back, restoring
+ the transaction state to what it was at the time of the savepoint.
+ </p></div><div class="refsect1" id="id-1.9.3.170.7"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>savepoint_name</code></em></span></dt><dd><p>
+ The name to give to the new savepoint. If savepoints with the
+ same name already exist, they will be inaccessible until newer
+ identically-named savepoints are released.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.170.8"><h2>Notes</h2><p>
+ Use <a class="link" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT"><code class="command">ROLLBACK TO</code></a> to
+ rollback to a savepoint. Use <a class="link" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT"><code class="command">RELEASE SAVEPOINT</code></a>
+ to destroy a savepoint, keeping
+ the effects of commands executed after it was established.
+ </p><p>
+ Savepoints can only be established when inside a transaction block.
+ There can be multiple savepoints defined within a transaction.
+ </p></div><div class="refsect1" id="id-1.9.3.170.9"><h2>Examples</h2><p>
+ To establish a savepoint and later undo the effects of all commands executed
+ after it was established:
+</p><pre class="programlisting">
+BEGIN;
+ INSERT INTO table1 VALUES (1);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (2);
+ ROLLBACK TO SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (3);
+COMMIT;
+</pre><p>
+ The above transaction will insert the values 1 and 3, but not 2.
+ </p><p>
+ To establish and later destroy a savepoint:
+</p><pre class="programlisting">
+BEGIN;
+ INSERT INTO table1 VALUES (3);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (4);
+ RELEASE SAVEPOINT my_savepoint;
+COMMIT;
+</pre><p>
+ The above transaction will insert both 3 and 4.
+ </p><p>
+ To use a single savepoint name:
+</p><pre class="programlisting">
+BEGIN;
+ INSERT INTO table1 VALUES (1);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (2);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table1 VALUES (3);
+
+ -- rollback to the second savepoint
+ ROLLBACK TO SAVEPOINT my_savepoint;
+ SELECT * FROM table1; -- shows rows 1 and 2
+
+ -- release the second savepoint
+ RELEASE SAVEPOINT my_savepoint;
+
+ -- rollback to the first savepoint
+ ROLLBACK TO SAVEPOINT my_savepoint;
+ SELECT * FROM table1; -- shows only row 1
+COMMIT;
+</pre><p>
+ The above transaction shows row 3 being rolled back first, then row 2.
+ </p></div><div class="refsect1" id="id-1.9.3.170.10"><h2>Compatibility</h2><p>
+ SQL requires a savepoint to be destroyed automatically when another
+ savepoint with the same name is established. In
+ <span class="productname">PostgreSQL</span>, the old savepoint is kept, though only the more
+ recent one will be used when rolling back or releasing. (Releasing the
+ newer savepoint with <code class="command">RELEASE SAVEPOINT</code> will cause the older one
+ to again become accessible to <code class="command">ROLLBACK TO SAVEPOINT</code> and
+ <code class="command">RELEASE SAVEPOINT</code>.) Otherwise, <code class="command">SAVEPOINT</code> is
+ fully SQL conforming.
+ </p></div><div class="refsect1" id="id-1.9.3.170.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-release-savepoint.html" title="RELEASE SAVEPOINT"><span class="refentrytitle">RELEASE SAVEPOINT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>, <a class="xref" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT"><span class="refentrytitle">ROLLBACK TO SAVEPOINT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-rollback-to.html" title="ROLLBACK TO SAVEPOINT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-security-label.html" title="SECURITY LABEL">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ROLLBACK TO SAVEPOINT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SECURITY LABEL</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-security-label.html b/doc/src/sgml/html/sql-security-label.html
new file mode 100644
index 0000000..47d0796
--- /dev/null
+++ b/doc/src/sgml/html/sql-security-label.html
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SECURITY LABEL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-savepoint.html" title="SAVEPOINT" /><link rel="next" href="sql-select.html" title="SELECT" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SECURITY LABEL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-savepoint.html" title="SAVEPOINT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-select.html" title="SELECT">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SECURITY-LABEL"><div class="titlepage"></div><a id="id-1.9.3.171.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SECURITY LABEL</span></h2><p>SECURITY LABEL — define or change a security label applied to an object</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SECURITY LABEL [ FOR <em class="replaceable"><code>provider</code></em> ] ON
+{
+ TABLE <em class="replaceable"><code>object_name</code></em> |
+ COLUMN <em class="replaceable"><code>table_name</code></em>.<em class="replaceable"><code>column_name</code></em> |
+ AGGREGATE <em class="replaceable"><code>aggregate_name</code></em> ( <em class="replaceable"><code>aggregate_signature</code></em> ) |
+ DATABASE <em class="replaceable"><code>object_name</code></em> |
+ DOMAIN <em class="replaceable"><code>object_name</code></em> |
+ EVENT TRIGGER <em class="replaceable"><code>object_name</code></em> |
+ FOREIGN TABLE <em class="replaceable"><code>object_name</code></em>
+ FUNCTION <em class="replaceable"><code>function_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ LARGE OBJECT <em class="replaceable"><code>large_object_oid</code></em> |
+ MATERIALIZED VIEW <em class="replaceable"><code>object_name</code></em> |
+ [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>object_name</code></em> |
+ PROCEDURE <em class="replaceable"><code>procedure_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ PUBLICATION <em class="replaceable"><code>object_name</code></em> |
+ ROLE <em class="replaceable"><code>object_name</code></em> |
+ ROUTINE <em class="replaceable"><code>routine_name</code></em> [ ( [ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [, ...] ] ) ] |
+ SCHEMA <em class="replaceable"><code>object_name</code></em> |
+ SEQUENCE <em class="replaceable"><code>object_name</code></em> |
+ SUBSCRIPTION <em class="replaceable"><code>object_name</code></em> |
+ TABLESPACE <em class="replaceable"><code>object_name</code></em> |
+ TYPE <em class="replaceable"><code>object_name</code></em> |
+ VIEW <em class="replaceable"><code>object_name</code></em>
+} IS { <em class="replaceable"><code>string_literal</code></em> | NULL }
+
+<span class="phrase">where <em class="replaceable"><code>aggregate_signature</code></em> is:</span>
+
+* |
+[ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] |
+[ [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ] ] ORDER BY [ <em class="replaceable"><code>argmode</code></em> ] [ <em class="replaceable"><code>argname</code></em> ] <em class="replaceable"><code>argtype</code></em> [ , ... ]
+</pre></div><div class="refsect1" id="id-1.9.3.171.5"><h2>Description</h2><p>
+ <code class="command">SECURITY LABEL</code> applies a security label to a database
+ object. An arbitrary number of security labels, one per label provider, can
+ be associated with a given database object. Label providers are loadable
+ modules which register themselves by using the function
+ <code class="function">register_label_provider</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">register_label_provider</code> is not an SQL function; it can
+ only be called from C code loaded into the backend.
+ </p></div><p>
+ The label provider determines whether a given label is valid and whether
+ it is permissible to assign that label to a given object. The meaning of a
+ given label is likewise at the discretion of the label provider.
+ <span class="productname">PostgreSQL</span> places no restrictions on whether or how a
+ label provider must interpret security labels; it merely provides a
+ mechanism for storing them. In practice, this facility is intended to allow
+ integration with label-based mandatory access control (MAC) systems such as
+ <span class="productname">SELinux</span>. Such systems make all access control decisions
+ based on object labels, rather than traditional discretionary access control
+ (DAC) concepts such as users and groups.
+ </p></div><div class="refsect1" id="id-1.9.3.171.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>object_name</code></em><br /></span><span class="term"><em class="replaceable"><code>table_name.column_name</code></em><br /></span><span class="term"><em class="replaceable"><code>aggregate_name</code></em><br /></span><span class="term"><em class="replaceable"><code>function_name</code></em><br /></span><span class="term"><em class="replaceable"><code>procedure_name</code></em><br /></span><span class="term"><em class="replaceable"><code>routine_name</code></em></span></dt><dd><p>
+ The name of the object to be labeled. Names of objects that reside in
+ schemas (tables, functions, etc.) can be schema-qualified.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>provider</code></em></span></dt><dd><p>
+ The name of the provider with which this label is to be associated. The
+ named provider must be loaded and must consent to the proposed labeling
+ operation. If exactly one provider is loaded, the provider name may be
+ omitted for brevity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argmode</code></em></span></dt><dd><p>
+ The mode of a function, procedure, or aggregate
+ argument: <code class="literal">IN</code>, <code class="literal">OUT</code>,
+ <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ If omitted, the default is <code class="literal">IN</code>.
+ Note that <code class="command">SECURITY LABEL</code> does not actually
+ pay any attention to <code class="literal">OUT</code> arguments, since only the input
+ arguments are needed to determine the function's identity.
+ So it is sufficient to list the <code class="literal">IN</code>, <code class="literal">INOUT</code>,
+ and <code class="literal">VARIADIC</code> arguments.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argname</code></em></span></dt><dd><p>
+ The name of a function, procedure, or aggregate argument.
+ Note that <code class="command">SECURITY LABEL</code> does not actually
+ pay any attention to argument names, since only the argument data
+ types are needed to determine the function's identity.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>argtype</code></em></span></dt><dd><p>
+ The data type of a function, procedure, or aggregate argument.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>large_object_oid</code></em></span></dt><dd><p>
+ The OID of the large object.
+ </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p>
+ This is a noise word.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>string_literal</code></em></span></dt><dd><p>
+ The new setting of the security label, written as a string literal.
+ </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
+ Write <code class="literal">NULL</code> to drop the security label.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.171.7"><h2>Examples</h2><p>
+ The following example shows how the security label of a table could
+ be set or changed:
+
+</p><pre class="programlisting">
+SECURITY LABEL FOR selinux ON TABLE mytable IS 'system_u:object_r:sepgsql_table_t:s0';
+</pre><p>
+
+ To remove the label:
+
+</p><pre class="programlisting">
+SECURITY LABEL FOR selinux ON TABLE mytable IS NULL;
+</pre><p>
+ </p></div><div class="refsect1" id="id-1.9.3.171.8"><h2>Compatibility</h2><p>
+ There is no <code class="command">SECURITY LABEL</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.171.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sepgsql.html" title="F.40. sepgsql">sepgsql</a>, <code class="filename">src/test/modules/dummy_seclabel</code></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-savepoint.html" title="SAVEPOINT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-select.html" title="SELECT">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SAVEPOINT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SELECT</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-select.html b/doc/src/sgml/html/sql-select.html
new file mode 100644
index 0000000..2cb7d85
--- /dev/null
+++ b/doc/src/sgml/html/sql-select.html
@@ -0,0 +1,1606 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SELECT</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-security-label.html" title="SECURITY LABEL" /><link rel="next" href="sql-selectinto.html" title="SELECT INTO" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SELECT</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-security-label.html" title="SECURITY LABEL">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-selectinto.html" title="SELECT INTO">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SELECT"><div class="titlepage"></div><a id="id-1.9.3.172.1" class="indexterm"></a><a id="id-1.9.3.172.2" class="indexterm"></a><a id="id-1.9.3.172.3" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SELECT</span></h2><p>SELECT, TABLE, WITH — retrieve rows from a table or view</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+SELECT [ ALL | DISTINCT [ ON ( <em class="replaceable"><code>expression</code></em> [, ...] ) ] ]
+ [ * | <em class="replaceable"><code>expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]
+ [ FROM <em class="replaceable"><code>from_item</code></em> [, ...] ]
+ [ WHERE <em class="replaceable"><code>condition</code></em> ]
+ [ GROUP BY [ ALL | DISTINCT ] <em class="replaceable"><code>grouping_element</code></em> [, ...] ]
+ [ HAVING <em class="replaceable"><code>condition</code></em> ]
+ [ WINDOW <em class="replaceable"><code>window_name</code></em> AS ( <em class="replaceable"><code>window_definition</code></em> ) [, ...] ]
+ [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <em class="replaceable"><code>select</code></em> ]
+ [ ORDER BY <em class="replaceable"><code>expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [ NULLS { FIRST | LAST } ] [, ...] ]
+ [ LIMIT { <em class="replaceable"><code>count</code></em> | ALL } ]
+ [ OFFSET <em class="replaceable"><code>start</code></em> [ ROW | ROWS ] ]
+ [ FETCH { FIRST | NEXT } [ <em class="replaceable"><code>count</code></em> ] { ROW | ROWS } { ONLY | WITH TIES } ]
+ [ FOR { UPDATE | NO KEY UPDATE | SHARE | KEY SHARE } [ OF <em class="replaceable"><code>table_name</code></em> [, ...] ] [ NOWAIT | SKIP LOCKED ] [...] ]
+
+<span class="phrase">where <em class="replaceable"><code>from_item</code></em> can be one of:</span>
+
+ [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ [ AS ] <em class="replaceable"><code>alias</code></em> [ ( <em class="replaceable"><code>column_alias</code></em> [, ...] ) ] ]
+ [ TABLESAMPLE <em class="replaceable"><code>sampling_method</code></em> ( <em class="replaceable"><code>argument</code></em> [, ...] ) [ REPEATABLE ( <em class="replaceable"><code>seed</code></em> ) ] ]
+ [ LATERAL ] ( <em class="replaceable"><code>select</code></em> ) [ AS ] <em class="replaceable"><code>alias</code></em> [ ( <em class="replaceable"><code>column_alias</code></em> [, ...] ) ]
+ <em class="replaceable"><code>with_query_name</code></em> [ [ AS ] <em class="replaceable"><code>alias</code></em> [ ( <em class="replaceable"><code>column_alias</code></em> [, ...] ) ] ]
+ [ LATERAL ] <em class="replaceable"><code>function_name</code></em> ( [ <em class="replaceable"><code>argument</code></em> [, ...] ] )
+ [ WITH ORDINALITY ] [ [ AS ] <em class="replaceable"><code>alias</code></em> [ ( <em class="replaceable"><code>column_alias</code></em> [, ...] ) ] ]
+ [ LATERAL ] <em class="replaceable"><code>function_name</code></em> ( [ <em class="replaceable"><code>argument</code></em> [, ...] ] ) [ AS ] <em class="replaceable"><code>alias</code></em> ( <em class="replaceable"><code>column_definition</code></em> [, ...] )
+ [ LATERAL ] <em class="replaceable"><code>function_name</code></em> ( [ <em class="replaceable"><code>argument</code></em> [, ...] ] ) AS ( <em class="replaceable"><code>column_definition</code></em> [, ...] )
+ [ LATERAL ] ROWS FROM( <em class="replaceable"><code>function_name</code></em> ( [ <em class="replaceable"><code>argument</code></em> [, ...] ] ) [ AS ( <em class="replaceable"><code>column_definition</code></em> [, ...] ) ] [, ...] )
+ [ WITH ORDINALITY ] [ [ AS ] <em class="replaceable"><code>alias</code></em> [ ( <em class="replaceable"><code>column_alias</code></em> [, ...] ) ] ]
+ <em class="replaceable"><code>from_item</code></em> <em class="replaceable"><code>join_type</code></em> <em class="replaceable"><code>from_item</code></em> { ON <em class="replaceable"><code>join_condition</code></em> | USING ( <em class="replaceable"><code>join_column</code></em> [, ...] ) [ AS <em class="replaceable"><code>join_using_alias</code></em> ] }
+ <em class="replaceable"><code>from_item</code></em> NATURAL <em class="replaceable"><code>join_type</code></em> <em class="replaceable"><code>from_item</code></em>
+ <em class="replaceable"><code>from_item</code></em> CROSS JOIN <em class="replaceable"><code>from_item</code></em>
+
+<span class="phrase">and <em class="replaceable"><code>grouping_element</code></em> can be one of:</span>
+
+ ( )
+ <em class="replaceable"><code>expression</code></em>
+ ( <em class="replaceable"><code>expression</code></em> [, ...] )
+ ROLLUP ( { <em class="replaceable"><code>expression</code></em> | ( <em class="replaceable"><code>expression</code></em> [, ...] ) } [, ...] )
+ CUBE ( { <em class="replaceable"><code>expression</code></em> | ( <em class="replaceable"><code>expression</code></em> [, ...] ) } [, ...] )
+ GROUPING SETS ( <em class="replaceable"><code>grouping_element</code></em> [, ...] )
+
+<span class="phrase">and <em class="replaceable"><code>with_query</code></em> is:</span>
+
+ <em class="replaceable"><code>with_query_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ] AS [ [ NOT ] MATERIALIZED ] ( <em class="replaceable"><code>select</code></em> | <em class="replaceable"><code>values</code></em> | <em class="replaceable"><code>insert</code></em> | <em class="replaceable"><code>update</code></em> | <em class="replaceable"><code>delete</code></em> )
+ [ SEARCH { BREADTH | DEPTH } FIRST BY <em class="replaceable"><code>column_name</code></em> [, ...] SET <em class="replaceable"><code>search_seq_col_name</code></em> ]
+ [ CYCLE <em class="replaceable"><code>column_name</code></em> [, ...] SET <em class="replaceable"><code>cycle_mark_col_name</code></em> [ TO <em class="replaceable"><code>cycle_mark_value</code></em> DEFAULT <em class="replaceable"><code>cycle_mark_default</code></em> ] USING <em class="replaceable"><code>cycle_path_col_name</code></em> ]
+
+TABLE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ]
+</pre></div><div class="refsect1" id="id-1.9.3.172.7"><h2>Description</h2><p>
+ <code class="command">SELECT</code> retrieves rows from zero or more tables.
+ The general processing of <code class="command">SELECT</code> is as follows:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ All queries in the <code class="literal">WITH</code> list are computed.
+ These effectively serve as temporary tables that can be referenced
+ in the <code class="literal">FROM</code> list. A <code class="literal">WITH</code> query
+ that is referenced more than once in <code class="literal">FROM</code> is
+ computed only once,
+ unless specified otherwise with <code class="literal">NOT MATERIALIZED</code>.
+ (See <a class="xref" href="sql-select.html#SQL-WITH" title="WITH Clause">WITH Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ All elements in the <code class="literal">FROM</code> list are computed.
+ (Each element in the <code class="literal">FROM</code> list is a real or
+ virtual table.) If more than one element is specified in the
+ <code class="literal">FROM</code> list, they are cross-joined together.
+ (See <a class="xref" href="sql-select.html#SQL-FROM" title="FROM Clause">FROM Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ If the <code class="literal">WHERE</code> clause is specified, all rows
+ that do not satisfy the condition are eliminated from the
+ output. (See <a class="xref" href="sql-select.html#SQL-WHERE" title="WHERE Clause">WHERE Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ If the <code class="literal">GROUP BY</code> clause is specified,
+ or if there are aggregate function calls, the
+ output is combined into groups of rows that match on one or more
+ values, and the results of aggregate functions are computed.
+ If the <code class="literal">HAVING</code> clause is present, it
+ eliminates groups that do not satisfy the given condition. (See
+ <a class="xref" href="sql-select.html#SQL-GROUPBY" title="GROUP BY Clause">GROUP BY Clause</a> and
+ <a class="xref" href="sql-select.html#SQL-HAVING" title="HAVING Clause">HAVING Clause</a> below.)
+ Although query output columns are nominally computed in the next
+ step, they can also be referenced (by name or ordinal number)
+ in the <code class="literal">GROUP BY</code> clause.
+ </p></li><li class="listitem"><p>
+ The actual output rows are computed using the
+ <code class="command">SELECT</code> output expressions for each selected
+ row or row group. (See <a class="xref" href="sql-select.html#SQL-SELECT-LIST" title="SELECT List">SELECT List</a> below.)
+ </p></li><li class="listitem"><p><code class="literal">SELECT DISTINCT</code> eliminates duplicate rows from the
+ result. <code class="literal">SELECT DISTINCT ON</code> eliminates rows that
+ match on all the specified expressions. <code class="literal">SELECT ALL</code>
+ (the default) will return all candidate rows, including
+ duplicates. (See <a class="xref" href="sql-select.html#SQL-DISTINCT" title="DISTINCT Clause">DISTINCT Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ Using the operators <code class="literal">UNION</code>,
+ <code class="literal">INTERSECT</code>, and <code class="literal">EXCEPT</code>, the
+ output of more than one <code class="command">SELECT</code> statement can
+ be combined to form a single result set. The
+ <code class="literal">UNION</code> operator returns all rows that are in
+ one or both of the result sets. The
+ <code class="literal">INTERSECT</code> operator returns all rows that are
+ strictly in both result sets. The <code class="literal">EXCEPT</code>
+ operator returns the rows that are in the first result set but
+ not in the second. In all three cases, duplicate rows are
+ eliminated unless <code class="literal">ALL</code> is specified. The noise
+ word <code class="literal">DISTINCT</code> can be added to explicitly specify
+ eliminating duplicate rows. Notice that <code class="literal">DISTINCT</code> is
+ the default behavior here, even though <code class="literal">ALL</code> is
+ the default for <code class="command">SELECT</code> itself. (See
+ <a class="xref" href="sql-select.html#SQL-UNION" title="UNION Clause">UNION Clause</a>, <a class="xref" href="sql-select.html#SQL-INTERSECT" title="INTERSECT Clause">INTERSECT Clause</a>, and
+ <a class="xref" href="sql-select.html#SQL-EXCEPT" title="EXCEPT Clause">EXCEPT Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ If the <code class="literal">ORDER BY</code> clause is specified, the
+ returned rows are sorted in the specified order. If
+ <code class="literal">ORDER BY</code> is not given, the rows are returned
+ in whatever order the system finds fastest to produce. (See
+ <a class="xref" href="sql-select.html#SQL-ORDERBY" title="ORDER BY Clause">ORDER BY Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ If the <code class="literal">LIMIT</code> (or <code class="literal">FETCH FIRST</code>) or <code class="literal">OFFSET</code>
+ clause is specified, the <code class="command">SELECT</code> statement
+ only returns a subset of the result rows. (See <a class="xref" href="sql-select.html#SQL-LIMIT" title="LIMIT Clause">LIMIT Clause</a> below.)
+ </p></li><li class="listitem"><p>
+ If <code class="literal">FOR UPDATE</code>, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR SHARE</code>
+ or <code class="literal">FOR KEY SHARE</code>
+ is specified, the
+ <code class="command">SELECT</code> statement locks the selected rows
+ against concurrent updates. (See <a class="xref" href="sql-select.html#SQL-FOR-UPDATE-SHARE" title="The Locking Clause">The Locking Clause</a>
+ below.)
+ </p></li></ol></div><p>
+ </p><p>
+ You must have <code class="literal">SELECT</code> privilege on each column used
+ in a <code class="command">SELECT</code> command. The use of <code class="literal">FOR NO KEY UPDATE</code>,
+ <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code> or <code class="literal">FOR KEY SHARE</code> requires
+ <code class="literal">UPDATE</code> privilege as well (for at least one column
+ of each table so selected).
+ </p></div><div class="refsect1" id="id-1.9.3.172.8"><h2>Parameters</h2><div class="refsect2" id="SQL-WITH"><h3><code class="literal">WITH</code> Clause</h3><p>
+ The <code class="literal">WITH</code> clause allows you to specify one or more
+ subqueries that can be referenced by name in the primary query.
+ The subqueries effectively act as temporary tables or views
+ for the duration of the primary query.
+ Each subquery can be a <code class="command">SELECT</code>, <code class="command">TABLE</code>, <code class="command">VALUES</code>,
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> statement.
+ When writing a data-modifying statement (<code class="command">INSERT</code>,
+ <code class="command">UPDATE</code> or <code class="command">DELETE</code>) in
+ <code class="literal">WITH</code>, it is usual to include a <code class="literal">RETURNING</code> clause.
+ It is the output of <code class="literal">RETURNING</code>, <span class="emphasis"><em>not</em></span> the underlying
+ table that the statement modifies, that forms the temporary table that is
+ read by the primary query. If <code class="literal">RETURNING</code> is omitted, the
+ statement is still executed, but it produces no output so it cannot be
+ referenced as a table by the primary query.
+ </p><p>
+ A name (without schema qualification) must be specified for each
+ <code class="literal">WITH</code> query. Optionally, a list of column names
+ can be specified; if this is omitted,
+ the column names are inferred from the subquery.
+ </p><p>
+ If <code class="literal">RECURSIVE</code> is specified, it allows a
+ <code class="command">SELECT</code> subquery to reference itself by name. Such a
+ subquery must have the form
+</p><pre class="synopsis">
+<em class="replaceable"><code>non_recursive_term</code></em> UNION [ ALL | DISTINCT ] <em class="replaceable"><code>recursive_term</code></em>
+</pre><p>
+ where the recursive self-reference must appear on the right-hand
+ side of the <code class="literal">UNION</code>. Only one recursive self-reference
+ is permitted per query. Recursive data-modifying statements are not
+ supported, but you can use the results of a recursive
+ <code class="command">SELECT</code> query in
+ a data-modifying statement. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> for
+ an example.
+ </p><p>
+ Another effect of <code class="literal">RECURSIVE</code> is that
+ <code class="literal">WITH</code> queries need not be ordered: a query
+ can reference another one that is later in the list. (However,
+ circular references, or mutual recursion, are not implemented.)
+ Without <code class="literal">RECURSIVE</code>, <code class="literal">WITH</code> queries
+ can only reference sibling <code class="literal">WITH</code> queries
+ that are earlier in the <code class="literal">WITH</code> list.
+ </p><p>
+ When there are multiple queries in the <code class="literal">WITH</code>
+ clause, <code class="literal">RECURSIVE</code> should be written only once,
+ immediately after <code class="literal">WITH</code>. It applies to all queries
+ in the <code class="literal">WITH</code> clause, though it has no effect on
+ queries that do not use recursion or forward references.
+ </p><p>
+ The optional <code class="literal">SEARCH</code> clause computes a <em class="firstterm">search
+ sequence column</em> that can be used for ordering the results of a
+ recursive query in either breadth-first or depth-first order. The
+ supplied column name list specifies the row key that is to be used for
+ keeping track of visited rows. A column named
+ <em class="replaceable"><code>search_seq_col_name</code></em> will be added to the result
+ column list of the <code class="literal">WITH</code> query. This column can be
+ ordered by in the outer query to achieve the respective ordering. See
+ <a class="xref" href="queries-with.html#QUERIES-WITH-SEARCH" title="7.8.2.1. Search Order">Section 7.8.2.1</a> for examples.
+ </p><p>
+ The optional <code class="literal">CYCLE</code> clause is used to detect cycles in
+ recursive queries. The supplied column name list specifies the row key
+ that is to be used for keeping track of visited rows. A column named
+ <em class="replaceable"><code>cycle_mark_col_name</code></em> will be added to the result
+ column list of the <code class="literal">WITH</code> query. This column will be set
+ to <em class="replaceable"><code>cycle_mark_value</code></em> when a cycle has been
+ detected, else to <em class="replaceable"><code>cycle_mark_default</code></em>.
+ Furthermore, processing of the recursive union will stop when a cycle has
+ been detected. <em class="replaceable"><code>cycle_mark_value</code></em> and
+ <em class="replaceable"><code>cycle_mark_default</code></em> must be constants and they
+ must be coercible to a common data type, and the data type must have an
+ inequality operator. (The SQL standard requires that they be Boolean
+ constants or character strings, but PostgreSQL does not require that.) By
+ default, <code class="literal">TRUE</code> and <code class="literal">FALSE</code> (of type
+ <code class="type">boolean</code>) are used. Furthermore, a column
+ named <em class="replaceable"><code>cycle_path_col_name</code></em> will be added to the
+ result column list of the <code class="literal">WITH</code> query. This column is
+ used internally for tracking visited rows. See <a class="xref" href="queries-with.html#QUERIES-WITH-CYCLE" title="7.8.2.2. Cycle Detection">Section 7.8.2.2</a> for examples.
+ </p><p>
+ Both the <code class="literal">SEARCH</code> and the <code class="literal">CYCLE</code> clause
+ are only valid for recursive <code class="literal">WITH</code> queries. The
+ <em class="replaceable"><code>with_query</code></em> must be a <code class="literal">UNION</code>
+ (or <code class="literal">UNION ALL</code>) of two <code class="literal">SELECT</code> (or
+ equivalent) commands (no nested <code class="literal">UNION</code>s). If both
+ clauses are used, the column added by the <code class="literal">SEARCH</code> clause
+ appears before the columns added by the <code class="literal">CYCLE</code> clause.
+ </p><p>
+ The primary query and the <code class="literal">WITH</code> queries are all
+ (notionally) executed at the same time. This implies that the effects of
+ a data-modifying statement in <code class="literal">WITH</code> cannot be seen from
+ other parts of the query, other than by reading its <code class="literal">RETURNING</code>
+ output. If two such data-modifying statements attempt to modify the same
+ row, the results are unspecified.
+ </p><p>
+ A key property of <code class="literal">WITH</code> queries is that they
+ are normally evaluated only once per execution of the primary query,
+ even if the primary query refers to them more than once.
+ In particular, data-modifying statements are guaranteed to be
+ executed once and only once, regardless of whether the primary query
+ reads all or any of their output.
+ </p><p>
+ However, a <code class="literal">WITH</code> query can be marked
+ <code class="literal">NOT MATERIALIZED</code> to remove this guarantee. In that
+ case, the <code class="literal">WITH</code> query can be folded into the primary
+ query much as though it were a simple sub-<code class="literal">SELECT</code> in
+ the primary query's <code class="literal">FROM</code> clause. This results in
+ duplicate computations if the primary query refers to
+ that <code class="literal">WITH</code> query more than once; but if each such use
+ requires only a few rows of the <code class="literal">WITH</code> query's total
+ output, <code class="literal">NOT MATERIALIZED</code> can provide a net savings by
+ allowing the queries to be optimized jointly.
+ <code class="literal">NOT MATERIALIZED</code> is ignored if it is attached to
+ a <code class="literal">WITH</code> query that is recursive or is not
+ side-effect-free (i.e., is not a plain <code class="literal">SELECT</code>
+ containing no volatile functions).
+ </p><p>
+ By default, a side-effect-free <code class="literal">WITH</code> query is folded
+ into the primary query if it is used exactly once in the primary
+ query's <code class="literal">FROM</code> clause. This allows joint optimization
+ of the two query levels in situations where that should be semantically
+ invisible. However, such folding can be prevented by marking the
+ <code class="literal">WITH</code> query as <code class="literal">MATERIALIZED</code>.
+ That might be useful, for example, if the <code class="literal">WITH</code> query
+ is being used as an optimization fence to prevent the planner from
+ choosing a bad plan.
+ <span class="productname">PostgreSQL</span> versions before v12 never did
+ such folding, so queries written for older versions might rely on
+ <code class="literal">WITH</code> to act as an optimization fence.
+ </p><p>
+ See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> for additional information.
+ </p></div><div class="refsect2" id="SQL-FROM"><h3><code class="literal">FROM</code> Clause</h3><p>
+ The <code class="literal">FROM</code> clause specifies one or more source
+ tables for the <code class="command">SELECT</code>. If multiple sources are
+ specified, the result is the Cartesian product (cross join) of all
+ the sources. But usually qualification conditions are added (via
+ <code class="literal">WHERE</code>) to restrict the returned rows to a small subset of the
+ Cartesian product.
+ </p><p>
+ The <code class="literal">FROM</code> clause can contain the following
+ elements:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of an existing table or view.
+ If <code class="literal">ONLY</code> is specified before the table name, only that
+ table is scanned. If <code class="literal">ONLY</code> is not specified, the table
+ and all its descendant tables (if any) are scanned. Optionally,
+ <code class="literal">*</code> can be specified after the table name to explicitly
+ indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>
+ A substitute name for the <code class="literal">FROM</code> item containing the
+ alias. An alias is used for brevity or to eliminate ambiguity
+ for self-joins (where the same table is scanned multiple
+ times). When an alias is provided, it completely hides the
+ actual name of the table or function; for example given
+ <code class="literal">FROM foo AS f</code>, the remainder of the
+ <code class="command">SELECT</code> must refer to this <code class="literal">FROM</code>
+ item as <code class="literal">f</code> not <code class="literal">foo</code>. If an alias is
+ written, a column alias list can also be written to provide
+ substitute names for one or more columns of the table.
+ </p></dd><dt><span class="term"><code class="literal">TABLESAMPLE <em class="replaceable"><code>sampling_method</code></em> ( <em class="replaceable"><code>argument</code></em> [, ...] ) [ REPEATABLE ( <em class="replaceable"><code>seed</code></em> ) ]</code></span></dt><dd><p>
+ A <code class="literal">TABLESAMPLE</code> clause after
+ a <em class="replaceable"><code>table_name</code></em> indicates that the
+ specified <em class="replaceable"><code>sampling_method</code></em>
+ should be used to retrieve a subset of the rows in that table.
+ This sampling precedes the application of any other filters such
+ as <code class="literal">WHERE</code> clauses.
+ The standard <span class="productname">PostgreSQL</span> distribution
+ includes two sampling methods, <code class="literal">BERNOULLI</code>
+ and <code class="literal">SYSTEM</code>, and other sampling methods can be
+ installed in the database via extensions.
+ </p><p>
+ The <code class="literal">BERNOULLI</code> and <code class="literal">SYSTEM</code> sampling methods
+ each accept a single <em class="replaceable"><code>argument</code></em>
+ which is the fraction of the table to sample, expressed as a
+ percentage between 0 and 100. This argument can be
+ any <code class="type">real</code>-valued expression. (Other sampling methods might
+ accept more or different arguments.) These two methods each return
+ a randomly-chosen sample of the table that will contain
+ approximately the specified percentage of the table's rows.
+ The <code class="literal">BERNOULLI</code> method scans the whole table and
+ selects or ignores individual rows independently with the specified
+ probability.
+ The <code class="literal">SYSTEM</code> method does block-level sampling with
+ each block having the specified chance of being selected; all rows
+ in each selected block are returned.
+ The <code class="literal">SYSTEM</code> method is significantly faster than
+ the <code class="literal">BERNOULLI</code> method when small sampling
+ percentages are specified, but it may return a less-random sample of
+ the table as a result of clustering effects.
+ </p><p>
+ The optional <code class="literal">REPEATABLE</code> clause specifies
+ a <em class="replaceable"><code>seed</code></em> number or expression to use
+ for generating random numbers within the sampling method. The seed
+ value can be any non-null floating-point value. Two queries that
+ specify the same seed and <em class="replaceable"><code>argument</code></em>
+ values will select the same sample of the table, if the table has
+ not been changed meanwhile. But different seed values will usually
+ produce different samples.
+ If <code class="literal">REPEATABLE</code> is not given then a new random
+ sample is selected for each query, based upon a system-generated seed.
+ Note that some add-on sampling methods do not
+ accept <code class="literal">REPEATABLE</code>, and will always produce new
+ samples on each use.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>select</code></em></span></dt><dd><p>
+ A sub-<code class="command">SELECT</code> can appear in the
+ <code class="literal">FROM</code> clause. This acts as though its
+ output were created as a temporary table for the duration of
+ this single <code class="command">SELECT</code> command. Note that the
+ sub-<code class="command">SELECT</code> must be surrounded by
+ parentheses, and an alias <span class="emphasis"><em>must</em></span> be
+ provided for it. A
+ <a class="link" href="sql-values.html" title="VALUES"><code class="command">VALUES</code></a> command
+ can also be used here.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>with_query_name</code></em></span></dt><dd><p>
+ A <code class="literal">WITH</code> query is referenced by writing its name,
+ just as though the query's name were a table name. (In fact,
+ the <code class="literal">WITH</code> query hides any real table of the same name
+ for the purposes of the primary query. If necessary, you can
+ refer to a real table of the same name by schema-qualifying
+ the table's name.)
+ An alias can be provided in the same way as for a table.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>function_name</code></em></span></dt><dd><p>
+ Function calls can appear in the <code class="literal">FROM</code>
+ clause. (This is especially useful for functions that return
+ result sets, but any function can be used.) This acts as
+ though the function's output were created as a temporary table for the
+ duration of this single <code class="command">SELECT</code> command.
+ If the function's result type is composite (including the case of a
+ function with multiple <code class="literal">OUT</code> parameters), each
+ attribute becomes a separate column in the implicit table.
+ </p><p>
+ When the optional <code class="command">WITH ORDINALITY</code> clause is added
+ to the function call, an additional column of type <code class="type">bigint</code>
+ will be appended to the function's result column(s). This column
+ numbers the rows of the function's result set, starting from 1.
+ By default, this column is named <code class="literal">ordinality</code>.
+ </p><p>
+ An alias can be provided in the same way as for a table.
+ If an alias is written, a column
+ alias list can also be written to provide substitute names for
+ one or more attributes of the function's composite return
+ type, including the ordinality column if present.
+ </p><p>
+ Multiple function calls can be combined into a
+ single <code class="literal">FROM</code>-clause item by surrounding them
+ with <code class="literal">ROWS FROM( ... )</code>. The output of such an item is the
+ concatenation of the first row from each function, then the second
+ row from each function, etc. If some of the functions produce fewer
+ rows than others, null values are substituted for the missing data, so
+ that the total number of rows returned is always the same as for the
+ function that produced the most rows.
+ </p><p>
+ If the function has been defined as returning the
+ <code class="type">record</code> data type, then an alias or the key word
+ <code class="literal">AS</code> must be present, followed by a column
+ definition list in the form <code class="literal">( <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [<span class="optional">, ...
+ </span>])</code>. The column definition list must match the
+ actual number and types of columns returned by the function.
+ </p><p>
+ When using the <code class="literal">ROWS FROM( ... )</code> syntax, if one of the
+ functions requires a column definition list, it's preferred to put
+ the column definition list after the function call inside
+ <code class="literal">ROWS FROM( ... )</code>. A column definition list can be placed
+ after the <code class="literal">ROWS FROM( ... )</code> construct only if there's just
+ a single function and no <code class="literal">WITH ORDINALITY</code> clause.
+ </p><p>
+ To use <code class="literal">ORDINALITY</code> together with a column definition
+ list, you must use the <code class="literal">ROWS FROM( ... )</code> syntax and put the
+ column definition list inside <code class="literal">ROWS FROM( ... )</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>join_type</code></em></span></dt><dd><p>
+ One of
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">[ INNER ] JOIN</code></p></li><li class="listitem"><p><code class="literal">LEFT [ OUTER ] JOIN</code></p></li><li class="listitem"><p><code class="literal">RIGHT [ OUTER ] JOIN</code></p></li><li class="listitem"><p><code class="literal">FULL [ OUTER ] JOIN</code></p></li></ul></div><p>
+
+ For the <code class="literal">INNER</code> and <code class="literal">OUTER</code> join types, a
+ join condition must be specified, namely exactly one of
+ <code class="literal">ON <em class="replaceable"><code>join_condition</code></em></code>,
+ <code class="literal">USING (<em class="replaceable"><code>join_column</code></em> [, ...])</code>,
+ or <code class="literal">NATURAL</code>. See below for the meaning.
+ </p><p>
+ A <code class="literal">JOIN</code> clause combines two <code class="literal">FROM</code>
+ items, which for convenience we will refer to as <span class="quote">“<span class="quote">tables</span>”</span>,
+ though in reality they can be any type of <code class="literal">FROM</code> item.
+ Use parentheses if necessary to determine the order of nesting.
+ In the absence of parentheses, <code class="literal">JOIN</code>s nest
+ left-to-right. In any case <code class="literal">JOIN</code> binds more
+ tightly than the commas separating <code class="literal">FROM</code>-list items.
+ All the <code class="literal">JOIN</code> options are just a notational
+ convenience, since they do nothing you couldn't do with plain
+ <code class="literal">FROM</code> and <code class="literal">WHERE</code>.
+ </p><p><code class="literal">LEFT OUTER JOIN</code> returns all rows in the qualified
+ Cartesian product (i.e., all combined rows that pass its join
+ condition), plus one copy of each row in the left-hand table
+ for which there was no right-hand row that passed the join
+ condition. This left-hand row is extended to the full width
+ of the joined table by inserting null values for the
+ right-hand columns. Note that only the <code class="literal">JOIN</code>
+ clause's own condition is considered while deciding which rows
+ have matches. Outer conditions are applied afterwards.
+ </p><p>
+ Conversely, <code class="literal">RIGHT OUTER JOIN</code> returns all the
+ joined rows, plus one row for each unmatched right-hand row
+ (extended with nulls on the left). This is just a notational
+ convenience, since you could convert it to a <code class="literal">LEFT
+ OUTER JOIN</code> by switching the left and right tables.
+ </p><p><code class="literal">FULL OUTER JOIN</code> returns all the joined rows, plus
+ one row for each unmatched left-hand row (extended with nulls
+ on the right), plus one row for each unmatched right-hand row
+ (extended with nulls on the left).
+ </p></dd><dt><span class="term"><code class="literal">ON <em class="replaceable"><code>join_condition</code></em></code></span></dt><dd><p><em class="replaceable"><code>join_condition</code></em> is
+ an expression resulting in a value of type
+ <code class="type">boolean</code> (similar to a <code class="literal">WHERE</code>
+ clause) that specifies which rows in a join are considered to
+ match.
+ </p></dd><dt><span class="term"><code class="literal">USING ( <em class="replaceable"><code>join_column</code></em> [, ...] ) [ AS <em class="replaceable"><code>join_using_alias</code></em> ]</code></span></dt><dd><p>
+ A clause of the form <code class="literal">USING ( a, b, ... )</code> is
+ shorthand for <code class="literal">ON left_table.a = right_table.a AND
+ left_table.b = right_table.b ...</code>. Also,
+ <code class="literal">USING</code> implies that only one of each pair of
+ equivalent columns will be included in the join output, not
+ both.
+ </p><p>
+ If a <em class="replaceable"><code>join_using_alias</code></em>
+ name is specified, it provides a table alias for the join columns.
+ Only the join columns listed in the <code class="literal">USING</code> clause
+ are addressable by this name. Unlike a regular <em class="replaceable"><code>alias</code></em>, this does not hide the names of
+ the joined tables from the rest of the query. Also unlike a regular
+ <em class="replaceable"><code>alias</code></em>, you cannot write a
+ column alias list — the output names of the join columns are the
+ same as they appear in the <code class="literal">USING</code> list.
+ </p></dd><dt><span class="term"><code class="literal">NATURAL</code></span></dt><dd><p>
+ <code class="literal">NATURAL</code> is shorthand for a
+ <code class="literal">USING</code> list that mentions all columns in the two
+ tables that have matching names. If there are no common
+ column names, <code class="literal">NATURAL</code> is equivalent
+ to <code class="literal">ON TRUE</code>.
+ </p></dd><dt><span class="term"><code class="literal">CROSS JOIN</code></span></dt><dd><p>
+ <code class="literal">CROSS JOIN</code> is equivalent to <code class="literal">INNER JOIN ON
+ (TRUE)</code>, that is, no rows are removed by qualification.
+ They produce a simple Cartesian product, the same result as you get from
+ listing the two tables at the top level of <code class="literal">FROM</code>,
+ but restricted by the join condition (if any).
+ </p></dd><dt><span class="term"><code class="literal">LATERAL</code></span></dt><dd><p>
+ The <code class="literal">LATERAL</code> key word can precede a
+ sub-<code class="command">SELECT</code> <code class="literal">FROM</code> item. This allows the
+ sub-<code class="command">SELECT</code> to refer to columns of <code class="literal">FROM</code>
+ items that appear before it in the <code class="literal">FROM</code> list. (Without
+ <code class="literal">LATERAL</code>, each sub-<code class="command">SELECT</code> is
+ evaluated independently and so cannot cross-reference any other
+ <code class="literal">FROM</code> item.)
+ </p><p><code class="literal">LATERAL</code> can also precede a function-call
+ <code class="literal">FROM</code> item, but in this case it is a noise word, because
+ the function expression can refer to earlier <code class="literal">FROM</code> items
+ in any case.
+ </p><p>
+ A <code class="literal">LATERAL</code> item can appear at top level in the
+ <code class="literal">FROM</code> list, or within a <code class="literal">JOIN</code> tree. In the
+ latter case it can also refer to any items that are on the left-hand
+ side of a <code class="literal">JOIN</code> that it is on the right-hand side of.
+ </p><p>
+ When a <code class="literal">FROM</code> item contains <code class="literal">LATERAL</code>
+ cross-references, evaluation proceeds as follows: for each row of the
+ <code class="literal">FROM</code> item providing the cross-referenced column(s), or
+ set of rows of multiple <code class="literal">FROM</code> items providing the
+ columns, the <code class="literal">LATERAL</code> item is evaluated using that
+ row or row set's values of the columns. The resulting row(s) are
+ joined as usual with the rows they were computed from. This is
+ repeated for each row or set of rows from the column source table(s).
+ </p><p>
+ The column source table(s) must be <code class="literal">INNER</code> or
+ <code class="literal">LEFT</code> joined to the <code class="literal">LATERAL</code> item, else
+ there would not be a well-defined set of rows from which to compute
+ each set of rows for the <code class="literal">LATERAL</code> item. Thus,
+ although a construct such as <code class="literal"><em class="replaceable"><code>X</code></em> RIGHT JOIN
+ LATERAL <em class="replaceable"><code>Y</code></em></code> is syntactically valid, it is
+ not actually allowed for <em class="replaceable"><code>Y</code></em> to reference
+ <em class="replaceable"><code>X</code></em>.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect2" id="SQL-WHERE"><h3><code class="literal">WHERE</code> Clause</h3><p>
+ The optional <code class="literal">WHERE</code> clause has the general form
+</p><pre class="synopsis">
+WHERE <em class="replaceable"><code>condition</code></em>
+</pre><p>
+ where <em class="replaceable"><code>condition</code></em> is
+ any expression that evaluates to a result of type
+ <code class="type">boolean</code>. Any row that does not satisfy this
+ condition will be eliminated from the output. A row satisfies the
+ condition if it returns true when the actual row values are
+ substituted for any variable references.
+ </p></div><div class="refsect2" id="SQL-GROUPBY"><h3><code class="literal">GROUP BY</code> Clause</h3><p>
+ The optional <code class="literal">GROUP BY</code> clause has the general form
+</p><pre class="synopsis">
+GROUP BY [ ALL | DISTINCT ] <em class="replaceable"><code>grouping_element</code></em> [, ...]
+</pre><p>
+ </p><p>
+ <code class="literal">GROUP BY</code> will condense into a single row all
+ selected rows that share the same values for the grouped
+ expressions. An <em class="replaceable"><code>expression</code></em> used inside a
+ <em class="replaceable"><code>grouping_element</code></em>
+ can be an input column name, or the name or ordinal number of an
+ output column (<code class="command">SELECT</code> list item), or an arbitrary
+ expression formed from input-column values. In case of ambiguity,
+ a <code class="literal">GROUP BY</code> name will be interpreted as an
+ input-column name rather than an output column name.
+ </p><p>
+ If any of <code class="literal">GROUPING SETS</code>, <code class="literal">ROLLUP</code> or
+ <code class="literal">CUBE</code> are present as grouping elements, then the
+ <code class="literal">GROUP BY</code> clause as a whole defines some number of
+ independent <em class="replaceable"><code>grouping sets</code></em>. The effect of this is
+ equivalent to constructing a <code class="literal">UNION ALL</code> between
+ subqueries with the individual grouping sets as their
+ <code class="literal">GROUP BY</code> clauses. The optional <code class="literal">DISTINCT</code>
+ clause removes duplicate sets before processing; it does <span class="emphasis"><em>not</em></span>
+ transform the <code class="literal">UNION ALL</code> into a <code class="literal">UNION DISTINCT</code>.
+ For further details on the handling
+ of grouping sets see <a class="xref" href="queries-table-expressions.html#QUERIES-GROUPING-SETS" title="7.2.4. GROUPING SETS, CUBE, and ROLLUP">Section 7.2.4</a>.
+ </p><p>
+ Aggregate functions, if any are used, are computed across all rows
+ making up each group, producing a separate value for each group.
+ (If there are aggregate functions but no <code class="literal">GROUP BY</code>
+ clause, the query is treated as having a single group comprising all
+ the selected rows.)
+ The set of rows fed to each aggregate function can be further filtered by
+ attaching a <code class="literal">FILTER</code> clause to the aggregate function
+ call; see <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a> for more information. When
+ a <code class="literal">FILTER</code> clause is present, only those rows matching it
+ are included in the input to that aggregate function.
+ </p><p>
+ When <code class="literal">GROUP BY</code> is present,
+ or any aggregate functions are present, it is not valid for
+ the <code class="command">SELECT</code> list expressions to refer to
+ ungrouped columns except within aggregate functions or when the
+ ungrouped column is functionally dependent on the grouped columns,
+ since there would otherwise be more than one possible value to
+ return for an ungrouped column. A functional dependency exists if
+ the grouped columns (or a subset thereof) are the primary key of
+ the table containing the ungrouped column.
+ </p><p>
+ Keep in mind that all aggregate functions are evaluated before
+ evaluating any <span class="quote">“<span class="quote">scalar</span>”</span> expressions in the <code class="literal">HAVING</code>
+ clause or <code class="literal">SELECT</code> list. This means that, for example,
+ a <code class="literal">CASE</code> expression cannot be used to skip evaluation of
+ an aggregate function; see <a class="xref" href="sql-expressions.html#SYNTAX-EXPRESS-EVAL" title="4.2.14. Expression Evaluation Rules">Section 4.2.14</a>.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code> and <code class="literal">FOR KEY SHARE</code> cannot be
+ specified with <code class="literal">GROUP BY</code>.
+ </p></div><div class="refsect2" id="SQL-HAVING"><h3><code class="literal">HAVING</code> Clause</h3><p>
+ The optional <code class="literal">HAVING</code> clause has the general form
+</p><pre class="synopsis">
+HAVING <em class="replaceable"><code>condition</code></em>
+</pre><p>
+ where <em class="replaceable"><code>condition</code></em> is
+ the same as specified for the <code class="literal">WHERE</code> clause.
+ </p><p>
+ <code class="literal">HAVING</code> eliminates group rows that do not
+ satisfy the condition. <code class="literal">HAVING</code> is different
+ from <code class="literal">WHERE</code>: <code class="literal">WHERE</code> filters
+ individual rows before the application of <code class="literal">GROUP
+ BY</code>, while <code class="literal">HAVING</code> filters group rows
+ created by <code class="literal">GROUP BY</code>. Each column referenced in
+ <em class="replaceable"><code>condition</code></em> must
+ unambiguously reference a grouping column, unless the reference
+ appears within an aggregate function or the ungrouped column is
+ functionally dependent on the grouping columns.
+ </p><p>
+ The presence of <code class="literal">HAVING</code> turns a query into a grouped
+ query even if there is no <code class="literal">GROUP BY</code> clause. This is the
+ same as what happens when the query contains aggregate functions but
+ no <code class="literal">GROUP BY</code> clause. All the selected rows are considered to
+ form a single group, and the <code class="command">SELECT</code> list and
+ <code class="literal">HAVING</code> clause can only reference table columns from
+ within aggregate functions. Such a query will emit a single row if the
+ <code class="literal">HAVING</code> condition is true, zero rows if it is not true.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code> and <code class="literal">FOR KEY SHARE</code> cannot be
+ specified with <code class="literal">HAVING</code>.
+ </p></div><div class="refsect2" id="SQL-WINDOW"><h3><code class="literal">WINDOW</code> Clause</h3><p>
+ The optional <code class="literal">WINDOW</code> clause has the general form
+</p><pre class="synopsis">
+WINDOW <em class="replaceable"><code>window_name</code></em> AS ( <em class="replaceable"><code>window_definition</code></em> ) [, ...]
+</pre><p>
+ where <em class="replaceable"><code>window_name</code></em> is
+ a name that can be referenced from <code class="literal">OVER</code> clauses or
+ subsequent window definitions, and
+ <em class="replaceable"><code>window_definition</code></em> is
+</p><pre class="synopsis">
+[ <em class="replaceable"><code>existing_window_name</code></em> ]
+[ PARTITION BY <em class="replaceable"><code>expression</code></em> [, ...] ]
+[ ORDER BY <em class="replaceable"><code>expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [ NULLS { FIRST | LAST } ] [, ...] ]
+[ <em class="replaceable"><code>frame_clause</code></em> ]
+</pre><p>
+ </p><p>
+ If an <em class="replaceable"><code>existing_window_name</code></em>
+ is specified it must refer to an earlier entry in the <code class="literal">WINDOW</code>
+ list; the new window copies its partitioning clause from that entry,
+ as well as its ordering clause if any. In this case the new window cannot
+ specify its own <code class="literal">PARTITION BY</code> clause, and it can specify
+ <code class="literal">ORDER BY</code> only if the copied window does not have one.
+ The new window always uses its own frame clause; the copied window
+ must not specify a frame clause.
+ </p><p>
+ The elements of the <code class="literal">PARTITION BY</code> list are interpreted in
+ much the same fashion as elements of a <a class="link" href="sql-select.html#SQL-GROUPBY" title="GROUP BY Clause"><code class="literal">GROUP BY</code></a> clause, except that
+ they are always simple expressions and never the name or number of an
+ output column.
+ Another difference is that these expressions can contain aggregate
+ function calls, which are not allowed in a regular <code class="literal">GROUP BY</code>
+ clause. They are allowed here because windowing occurs after grouping
+ and aggregation.
+ </p><p>
+ Similarly, the elements of the <code class="literal">ORDER BY</code> list are interpreted
+ in much the same fashion as elements of a statement-level <a class="link" href="sql-select.html#SQL-ORDERBY" title="ORDER BY Clause"><code class="literal">ORDER BY</code></a> clause, except that
+ the expressions are always taken as simple expressions and never the name
+ or number of an output column.
+ </p><p>
+ The optional <em class="replaceable"><code>frame_clause</code></em> defines
+ the <em class="firstterm">window frame</em> for window functions that depend on the
+ frame (not all do). The window frame is a set of related rows for
+ each row of the query (called the <em class="firstterm">current row</em>).
+ The <em class="replaceable"><code>frame_clause</code></em> can be one of
+
+</p><pre class="synopsis">
+{ RANGE | ROWS | GROUPS } <em class="replaceable"><code>frame_start</code></em> [ <em class="replaceable"><code>frame_exclusion</code></em> ]
+{ RANGE | ROWS | GROUPS } BETWEEN <em class="replaceable"><code>frame_start</code></em> AND <em class="replaceable"><code>frame_end</code></em> [ <em class="replaceable"><code>frame_exclusion</code></em> ]
+</pre><p>
+
+ where <em class="replaceable"><code>frame_start</code></em>
+ and <em class="replaceable"><code>frame_end</code></em> can be one of
+
+</p><pre class="synopsis">
+UNBOUNDED PRECEDING
+<em class="replaceable"><code>offset</code></em> PRECEDING
+CURRENT ROW
+<em class="replaceable"><code>offset</code></em> FOLLOWING
+UNBOUNDED FOLLOWING
+</pre><p>
+
+ and <em class="replaceable"><code>frame_exclusion</code></em> can be one of
+
+</p><pre class="synopsis">
+EXCLUDE CURRENT ROW
+EXCLUDE GROUP
+EXCLUDE TIES
+EXCLUDE NO OTHERS
+</pre><p>
+
+ If <em class="replaceable"><code>frame_end</code></em> is omitted it defaults to <code class="literal">CURRENT
+ ROW</code>. Restrictions are that
+ <em class="replaceable"><code>frame_start</code></em> cannot be <code class="literal">UNBOUNDED FOLLOWING</code>,
+ <em class="replaceable"><code>frame_end</code></em> cannot be <code class="literal">UNBOUNDED PRECEDING</code>,
+ and the <em class="replaceable"><code>frame_end</code></em> choice cannot appear earlier in the
+ above list of <em class="replaceable"><code>frame_start</code></em>
+ and <em class="replaceable"><code>frame_end</code></em> options than
+ the <em class="replaceable"><code>frame_start</code></em> choice does — for example
+ <code class="literal">RANGE BETWEEN CURRENT ROW AND <em class="replaceable"><code>offset</code></em>
+ PRECEDING</code> is not allowed.
+ </p><p>
+ The default framing option is <code class="literal">RANGE UNBOUNDED PRECEDING</code>,
+ which is the same as <code class="literal">RANGE BETWEEN UNBOUNDED PRECEDING AND
+ CURRENT ROW</code>; it sets the frame to be all rows from the partition start
+ up through the current row's last <em class="firstterm">peer</em> (a row
+ that the window's <code class="literal">ORDER BY</code> clause considers
+ equivalent to the current row; all rows are peers if there
+ is no <code class="literal">ORDER BY</code>).
+ In general, <code class="literal">UNBOUNDED PRECEDING</code> means that the frame
+ starts with the first row of the partition, and similarly
+ <code class="literal">UNBOUNDED FOLLOWING</code> means that the frame ends with the last
+ row of the partition, regardless
+ of <code class="literal">RANGE</code>, <code class="literal">ROWS</code>
+ or <code class="literal">GROUPS</code> mode.
+ In <code class="literal">ROWS</code> mode, <code class="literal">CURRENT ROW</code> means
+ that the frame starts or ends with the current row; but
+ in <code class="literal">RANGE</code> or <code class="literal">GROUPS</code> mode it means
+ that the frame starts or ends with the current row's first or last peer
+ in the <code class="literal">ORDER BY</code> ordering.
+ The <em class="replaceable"><code>offset</code></em> <code class="literal">PRECEDING</code> and
+ <em class="replaceable"><code>offset</code></em> <code class="literal">FOLLOWING</code> options
+ vary in meaning depending on the frame mode.
+ In <code class="literal">ROWS</code> mode, the <em class="replaceable"><code>offset</code></em>
+ is an integer indicating that the frame starts or ends that many rows
+ before or after the current row.
+ In <code class="literal">GROUPS</code> mode, the <em class="replaceable"><code>offset</code></em>
+ is an integer indicating that the frame starts or ends that many peer
+ groups before or after the current row's peer group, where
+ a <em class="firstterm">peer group</em> is a group of rows that are
+ equivalent according to the window's <code class="literal">ORDER BY</code> clause.
+ In <code class="literal">RANGE</code> mode, use of
+ an <em class="replaceable"><code>offset</code></em> option requires that there be
+ exactly one <code class="literal">ORDER BY</code> column in the window definition.
+ Then the frame contains those rows whose ordering column value is no
+ more than <em class="replaceable"><code>offset</code></em> less than
+ (for <code class="literal">PRECEDING</code>) or more than
+ (for <code class="literal">FOLLOWING</code>) the current row's ordering column
+ value. In these cases the data type of
+ the <em class="replaceable"><code>offset</code></em> expression depends on the data
+ type of the ordering column. For numeric ordering columns it is
+ typically of the same type as the ordering column, but for datetime
+ ordering columns it is an <code class="type">interval</code>.
+ In all these cases, the value of the <em class="replaceable"><code>offset</code></em>
+ must be non-null and non-negative. Also, while
+ the <em class="replaceable"><code>offset</code></em> does not have to be a simple
+ constant, it cannot contain variables, aggregate functions, or window
+ functions.
+ </p><p>
+ The <em class="replaceable"><code>frame_exclusion</code></em> option allows rows around
+ the current row to be excluded from the frame, even if they would be
+ included according to the frame start and frame end options.
+ <code class="literal">EXCLUDE CURRENT ROW</code> excludes the current row from the
+ frame.
+ <code class="literal">EXCLUDE GROUP</code> excludes the current row and its
+ ordering peers from the frame.
+ <code class="literal">EXCLUDE TIES</code> excludes any peers of the current
+ row from the frame, but not the current row itself.
+ <code class="literal">EXCLUDE NO OTHERS</code> simply specifies explicitly the
+ default behavior of not excluding the current row or its peers.
+ </p><p>
+ Beware that the <code class="literal">ROWS</code> mode can produce unpredictable
+ results if the <code class="literal">ORDER BY</code> ordering does not order the rows
+ uniquely. The <code class="literal">RANGE</code> and <code class="literal">GROUPS</code>
+ modes are designed to ensure that rows that are peers in
+ the <code class="literal">ORDER BY</code> ordering are treated alike: all rows of
+ a given peer group will be in the frame or excluded from it.
+ </p><p>
+ The purpose of a <code class="literal">WINDOW</code> clause is to specify the
+ behavior of <em class="firstterm">window functions</em> appearing in the query's
+ <a class="link" href="sql-select.html#SQL-SELECT-LIST" title="SELECT List"><code class="command">SELECT</code> list</a> or
+ <a class="link" href="sql-select.html#SQL-ORDERBY" title="ORDER BY Clause"><code class="literal">ORDER BY</code></a> clause.
+ These functions
+ can reference the <code class="literal">WINDOW</code> clause entries by name
+ in their <code class="literal">OVER</code> clauses. A <code class="literal">WINDOW</code> clause
+ entry does not have to be referenced anywhere, however; if it is not
+ used in the query it is simply ignored. It is possible to use window
+ functions without any <code class="literal">WINDOW</code> clause at all, since
+ a window function call can specify its window definition directly in
+ its <code class="literal">OVER</code> clause. However, the <code class="literal">WINDOW</code>
+ clause saves typing when the same window definition is needed for more
+ than one window function.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code> and <code class="literal">FOR KEY SHARE</code> cannot be
+ specified with <code class="literal">WINDOW</code>.
+ </p><p>
+ Window functions are described in detail in
+ <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a>,
+ <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a>, and
+ <a class="xref" href="queries-table-expressions.html#QUERIES-WINDOW" title="7.2.5. Window Function Processing">Section 7.2.5</a>.
+ </p></div><div class="refsect2" id="SQL-SELECT-LIST"><h3><code class="command">SELECT</code> List</h3><p>
+ The <code class="command">SELECT</code> list (between the key words
+ <code class="literal">SELECT</code> and <code class="literal">FROM</code>) specifies expressions
+ that form the output rows of the <code class="command">SELECT</code>
+ statement. The expressions can (and usually do) refer to columns
+ computed in the <code class="literal">FROM</code> clause.
+ </p><p>
+ Just as in a table, every output column of a <code class="command">SELECT</code>
+ has a name. In a simple <code class="command">SELECT</code> this name is just
+ used to label the column for display, but when the <code class="command">SELECT</code>
+ is a sub-query of a larger query, the name is seen by the larger query
+ as the column name of the virtual table produced by the sub-query.
+ To specify the name to use for an output column, write
+ <code class="literal">AS</code> <em class="replaceable"><code>output_name</code></em>
+ after the column's expression. (You can omit <code class="literal">AS</code>,
+ but only if the desired output name does not match any
+ <span class="productname">PostgreSQL</span> keyword (see <a class="xref" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Appendix C</a>). For protection against possible
+ future keyword additions, it is recommended that you always either
+ write <code class="literal">AS</code> or double-quote the output name.)
+ If you do not specify a column name, a name is chosen automatically
+ by <span class="productname">PostgreSQL</span>. If the column's expression
+ is a simple column reference then the chosen name is the same as that
+ column's name. In more complex cases a function or type name may be
+ used, or the system may fall back on a generated name such as
+ <code class="literal">?column?</code>.
+ </p><p>
+ An output column's name can be used to refer to the column's value in
+ <code class="literal">ORDER BY</code> and <code class="literal">GROUP BY</code> clauses, but not in the
+ <code class="literal">WHERE</code> or <code class="literal">HAVING</code> clauses; there you must write
+ out the expression instead.
+ </p><p>
+ Instead of an expression, <code class="literal">*</code> can be written in
+ the output list as a shorthand for all the columns of the selected
+ rows. Also, you can write <code class="literal"><em class="replaceable"><code>table_name</code></em>.*</code> as a
+ shorthand for the columns coming from just that table. In these
+ cases it is not possible to specify new names with <code class="literal">AS</code>;
+ the output column names will be the same as the table columns' names.
+ </p><p>
+ According to the SQL standard, the expressions in the output list should
+ be computed before applying <code class="literal">DISTINCT</code>, <code class="literal">ORDER
+ BY</code>, or <code class="literal">LIMIT</code>. This is obviously necessary
+ when using <code class="literal">DISTINCT</code>, since otherwise it's not clear
+ what values are being made distinct. However, in many cases it is
+ convenient if output expressions are computed after <code class="literal">ORDER
+ BY</code> and <code class="literal">LIMIT</code>; particularly if the output list
+ contains any volatile or expensive functions. With that behavior, the
+ order of function evaluations is more intuitive and there will not be
+ evaluations corresponding to rows that never appear in the output.
+ <span class="productname">PostgreSQL</span> will effectively evaluate output expressions
+ after sorting and limiting, so long as those expressions are not
+ referenced in <code class="literal">DISTINCT</code>, <code class="literal">ORDER BY</code>
+ or <code class="literal">GROUP BY</code>. (As a counterexample, <code class="literal">SELECT
+ f(x) FROM tab ORDER BY 1</code> clearly must evaluate <code class="function">f(x)</code>
+ before sorting.) Output expressions that contain set-returning functions
+ are effectively evaluated after sorting and before limiting, so
+ that <code class="literal">LIMIT</code> will act to cut off the output from a
+ set-returning function.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> versions before 9.6 did not provide any
+ guarantees about the timing of evaluation of output expressions versus
+ sorting and limiting; it depended on the form of the chosen query plan.
+ </p></div></div><div class="refsect2" id="SQL-DISTINCT"><h3><code class="literal">DISTINCT</code> Clause</h3><p>
+ If <code class="literal">SELECT DISTINCT</code> is specified, all duplicate rows are
+ removed from the result set (one row is kept from each group of
+ duplicates). <code class="literal">SELECT ALL</code> specifies the opposite: all rows are
+ kept; that is the default.
+ </p><p>
+ <code class="literal">SELECT DISTINCT ON ( <em class="replaceable"><code>expression</code></em> [, ...] )</code>
+ keeps only the first row of each set of rows where the given
+ expressions evaluate to equal. The <code class="literal">DISTINCT ON</code>
+ expressions are interpreted using the same rules as for
+ <code class="literal">ORDER BY</code> (see above). Note that the <span class="quote">“<span class="quote">first
+ row</span>”</span> of each set is unpredictable unless <code class="literal">ORDER
+ BY</code> is used to ensure that the desired row appears first. For
+ example:
+</p><pre class="programlisting">
+SELECT DISTINCT ON (location) location, time, report
+ FROM weather_reports
+ ORDER BY location, time DESC;
+</pre><p>
+ retrieves the most recent weather report for each location. But
+ if we had not used <code class="literal">ORDER BY</code> to force descending order
+ of time values for each location, we'd have gotten a report from
+ an unpredictable time for each location.
+ </p><p>
+ The <code class="literal">DISTINCT ON</code> expression(s) must match the leftmost
+ <code class="literal">ORDER BY</code> expression(s). The <code class="literal">ORDER BY</code> clause
+ will normally contain additional expression(s) that determine the
+ desired precedence of rows within each <code class="literal">DISTINCT ON</code> group.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code> and <code class="literal">FOR KEY SHARE</code> cannot be
+ specified with <code class="literal">DISTINCT</code>.
+ </p></div><div class="refsect2" id="SQL-UNION"><h3><code class="literal">UNION</code> Clause</h3><p>
+ The <code class="literal">UNION</code> clause has this general form:
+</p><pre class="synopsis">
+<em class="replaceable"><code>select_statement</code></em> UNION [ ALL | DISTINCT ] <em class="replaceable"><code>select_statement</code></em>
+</pre><p><em class="replaceable"><code>select_statement</code></em> is
+ any <code class="command">SELECT</code> statement without an <code class="literal">ORDER
+ BY</code>, <code class="literal">LIMIT</code>, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code>, or <code class="literal">FOR KEY SHARE</code> clause.
+ (<code class="literal">ORDER BY</code> and <code class="literal">LIMIT</code> can be attached to a
+ subexpression if it is enclosed in parentheses. Without
+ parentheses, these clauses will be taken to apply to the result of
+ the <code class="literal">UNION</code>, not to its right-hand input
+ expression.)
+ </p><p>
+ The <code class="literal">UNION</code> operator computes the set union of
+ the rows returned by the involved <code class="command">SELECT</code>
+ statements. A row is in the set union of two result sets if it
+ appears in at least one of the result sets. The two
+ <code class="command">SELECT</code> statements that represent the direct
+ operands of the <code class="literal">UNION</code> must produce the same
+ number of columns, and corresponding columns must be of compatible
+ data types.
+ </p><p>
+ The result of <code class="literal">UNION</code> does not contain any duplicate
+ rows unless the <code class="literal">ALL</code> option is specified.
+ <code class="literal">ALL</code> prevents elimination of duplicates. (Therefore,
+ <code class="literal">UNION ALL</code> is usually significantly quicker than
+ <code class="literal">UNION</code>; use <code class="literal">ALL</code> when you can.)
+ <code class="literal">DISTINCT</code> can be written to explicitly specify the
+ default behavior of eliminating duplicate rows.
+ </p><p>
+ Multiple <code class="literal">UNION</code> operators in the same
+ <code class="command">SELECT</code> statement are evaluated left to right,
+ unless otherwise indicated by parentheses.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>, <code class="literal">FOR SHARE</code> and
+ <code class="literal">FOR KEY SHARE</code> cannot be
+ specified either for a <code class="literal">UNION</code> result or for any input of a
+ <code class="literal">UNION</code>.
+ </p></div><div class="refsect2" id="SQL-INTERSECT"><h3><code class="literal">INTERSECT</code> Clause</h3><p>
+ The <code class="literal">INTERSECT</code> clause has this general form:
+</p><pre class="synopsis">
+<em class="replaceable"><code>select_statement</code></em> INTERSECT [ ALL | DISTINCT ] <em class="replaceable"><code>select_statement</code></em>
+</pre><p><em class="replaceable"><code>select_statement</code></em> is
+ any <code class="command">SELECT</code> statement without an <code class="literal">ORDER
+ BY</code>, <code class="literal">LIMIT</code>, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code>, or <code class="literal">FOR KEY SHARE</code> clause.
+ </p><p>
+ The <code class="literal">INTERSECT</code> operator computes the set
+ intersection of the rows returned by the involved
+ <code class="command">SELECT</code> statements. A row is in the
+ intersection of two result sets if it appears in both result sets.
+ </p><p>
+ The result of <code class="literal">INTERSECT</code> does not contain any
+ duplicate rows unless the <code class="literal">ALL</code> option is specified.
+ With <code class="literal">ALL</code>, a row that has <em class="replaceable"><code>m</code></em> duplicates in the
+ left table and <em class="replaceable"><code>n</code></em> duplicates in the right table will appear
+ min(<em class="replaceable"><code>m</code></em>,<em class="replaceable"><code>n</code></em>) times in the result set.
+ <code class="literal">DISTINCT</code> can be written to explicitly specify the
+ default behavior of eliminating duplicate rows.
+ </p><p>
+ Multiple <code class="literal">INTERSECT</code> operators in the same
+ <code class="command">SELECT</code> statement are evaluated left to right,
+ unless parentheses dictate otherwise.
+ <code class="literal">INTERSECT</code> binds more tightly than
+ <code class="literal">UNION</code>. That is, <code class="literal">A UNION B INTERSECT
+ C</code> will be read as <code class="literal">A UNION (B INTERSECT
+ C)</code>.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>, <code class="literal">FOR SHARE</code> and
+ <code class="literal">FOR KEY SHARE</code> cannot be
+ specified either for an <code class="literal">INTERSECT</code> result or for any input of
+ an <code class="literal">INTERSECT</code>.
+ </p></div><div class="refsect2" id="SQL-EXCEPT"><h3><code class="literal">EXCEPT</code> Clause</h3><p>
+ The <code class="literal">EXCEPT</code> clause has this general form:
+</p><pre class="synopsis">
+<em class="replaceable"><code>select_statement</code></em> EXCEPT [ ALL | DISTINCT ] <em class="replaceable"><code>select_statement</code></em>
+</pre><p><em class="replaceable"><code>select_statement</code></em> is
+ any <code class="command">SELECT</code> statement without an <code class="literal">ORDER
+ BY</code>, <code class="literal">LIMIT</code>, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>,
+ <code class="literal">FOR SHARE</code>, or <code class="literal">FOR KEY SHARE</code> clause.
+ </p><p>
+ The <code class="literal">EXCEPT</code> operator computes the set of rows
+ that are in the result of the left <code class="command">SELECT</code>
+ statement but not in the result of the right one.
+ </p><p>
+ The result of <code class="literal">EXCEPT</code> does not contain any
+ duplicate rows unless the <code class="literal">ALL</code> option is specified.
+ With <code class="literal">ALL</code>, a row that has <em class="replaceable"><code>m</code></em> duplicates in the
+ left table and <em class="replaceable"><code>n</code></em> duplicates in the right table will appear
+ max(<em class="replaceable"><code>m</code></em>-<em class="replaceable"><code>n</code></em>,0) times in the result set.
+ <code class="literal">DISTINCT</code> can be written to explicitly specify the
+ default behavior of eliminating duplicate rows.
+ </p><p>
+ Multiple <code class="literal">EXCEPT</code> operators in the same
+ <code class="command">SELECT</code> statement are evaluated left to right,
+ unless parentheses dictate otherwise. <code class="literal">EXCEPT</code> binds at
+ the same level as <code class="literal">UNION</code>.
+ </p><p>
+ Currently, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>, <code class="literal">FOR SHARE</code> and
+ <code class="literal">FOR KEY SHARE</code> cannot be
+ specified either for an <code class="literal">EXCEPT</code> result or for any input of
+ an <code class="literal">EXCEPT</code>.
+ </p></div><div class="refsect2" id="SQL-ORDERBY"><h3><code class="literal">ORDER BY</code> Clause</h3><p>
+ The optional <code class="literal">ORDER BY</code> clause has this general form:
+</p><pre class="synopsis">
+ORDER BY <em class="replaceable"><code>expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [ NULLS { FIRST | LAST } ] [, ...]
+</pre><p>
+ The <code class="literal">ORDER BY</code> clause causes the result rows to
+ be sorted according to the specified expression(s). If two rows are
+ equal according to the leftmost expression, they are compared
+ according to the next expression and so on. If they are equal
+ according to all specified expressions, they are returned in
+ an implementation-dependent order.
+ </p><p>
+ Each <em class="replaceable"><code>expression</code></em> can be the
+ name or ordinal number of an output column
+ (<code class="command">SELECT</code> list item), or it can be an arbitrary
+ expression formed from input-column values.
+ </p><p>
+ The ordinal number refers to the ordinal (left-to-right) position
+ of the output column. This feature makes it possible to define an
+ ordering on the basis of a column that does not have a unique
+ name. This is never absolutely necessary because it is always
+ possible to assign a name to an output column using the
+ <code class="literal">AS</code> clause.
+ </p><p>
+ It is also possible to use arbitrary expressions in the
+ <code class="literal">ORDER BY</code> clause, including columns that do not
+ appear in the <code class="command">SELECT</code> output list. Thus the
+ following statement is valid:
+</p><pre class="programlisting">
+SELECT name FROM distributors ORDER BY code;
+</pre><p>
+ A limitation of this feature is that an <code class="literal">ORDER BY</code>
+ clause applying to the result of a <code class="literal">UNION</code>,
+ <code class="literal">INTERSECT</code>, or <code class="literal">EXCEPT</code> clause can only
+ specify an output column name or number, not an expression.
+ </p><p>
+ If an <code class="literal">ORDER BY</code> expression is a simple name that
+ matches both an output column name and an input column name,
+ <code class="literal">ORDER BY</code> will interpret it as the output column name.
+ This is the opposite of the choice that <code class="literal">GROUP BY</code> will
+ make in the same situation. This inconsistency is made to be
+ compatible with the SQL standard.
+ </p><p>
+ Optionally one can add the key word <code class="literal">ASC</code> (ascending) or
+ <code class="literal">DESC</code> (descending) after any expression in the
+ <code class="literal">ORDER BY</code> clause. If not specified, <code class="literal">ASC</code> is
+ assumed by default. Alternatively, a specific ordering operator
+ name can be specified in the <code class="literal">USING</code> clause.
+ An ordering operator must be a less-than or greater-than
+ member of some B-tree operator family.
+ <code class="literal">ASC</code> is usually equivalent to <code class="literal">USING &lt;</code> and
+ <code class="literal">DESC</code> is usually equivalent to <code class="literal">USING &gt;</code>.
+ (But the creator of a user-defined data type can define exactly what the
+ default sort ordering is, and it might correspond to operators with other
+ names.)
+ </p><p>
+ If <code class="literal">NULLS LAST</code> is specified, null values sort after all
+ non-null values; if <code class="literal">NULLS FIRST</code> is specified, null values
+ sort before all non-null values. If neither is specified, the default
+ behavior is <code class="literal">NULLS LAST</code> when <code class="literal">ASC</code> is specified
+ or implied, and <code class="literal">NULLS FIRST</code> when <code class="literal">DESC</code> is specified
+ (thus, the default is to act as though nulls are larger than non-nulls).
+ When <code class="literal">USING</code> is specified, the default nulls ordering depends
+ on whether the operator is a less-than or greater-than operator.
+ </p><p>
+ Note that ordering options apply only to the expression they follow;
+ for example <code class="literal">ORDER BY x, y DESC</code> does not mean
+ the same thing as <code class="literal">ORDER BY x DESC, y DESC</code>.
+ </p><p>
+ Character-string data is sorted according to the collation that applies
+ to the column being sorted. That can be overridden at need by including
+ a <code class="literal">COLLATE</code> clause in the
+ <em class="replaceable"><code>expression</code></em>, for example
+ <code class="literal">ORDER BY mycolumn COLLATE "en_US"</code>.
+ For more information see <a class="xref" href="sql-expressions.html#SQL-SYNTAX-COLLATE-EXPRS" title="4.2.10. Collation Expressions">Section 4.2.10</a> and
+ <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>.
+ </p></div><div class="refsect2" id="SQL-LIMIT"><h3><code class="literal">LIMIT</code> Clause</h3><p>
+ The <code class="literal">LIMIT</code> clause consists of two independent
+ sub-clauses:
+</p><pre class="synopsis">
+LIMIT { <em class="replaceable"><code>count</code></em> | ALL }
+OFFSET <em class="replaceable"><code>start</code></em>
+</pre><p>
+ The parameter <em class="replaceable"><code>count</code></em> specifies the
+ maximum number of rows to return, while <em class="replaceable"><code>start</code></em> specifies the number of rows
+ to skip before starting to return rows. When both are specified,
+ <em class="replaceable"><code>start</code></em> rows are skipped
+ before starting to count the <em class="replaceable"><code>count</code></em> rows to be returned.
+ </p><p>
+ If the <em class="replaceable"><code>count</code></em> expression
+ evaluates to NULL, it is treated as <code class="literal">LIMIT ALL</code>, i.e., no
+ limit. If <em class="replaceable"><code>start</code></em> evaluates
+ to NULL, it is treated the same as <code class="literal">OFFSET 0</code>.
+ </p><p>
+ SQL:2008 introduced a different syntax to achieve the same result,
+ which <span class="productname">PostgreSQL</span> also supports. It is:
+</p><pre class="synopsis">
+OFFSET <em class="replaceable"><code>start</code></em> { ROW | ROWS }
+FETCH { FIRST | NEXT } [ <em class="replaceable"><code>count</code></em> ] { ROW | ROWS } { ONLY | WITH TIES }
+</pre><p>
+ In this syntax, the <em class="replaceable"><code>start</code></em>
+ or <em class="replaceable"><code>count</code></em> value is required by
+ the standard to be a literal constant, a parameter, or a variable name;
+ as a <span class="productname">PostgreSQL</span> extension, other expressions
+ are allowed, but will generally need to be enclosed in parentheses to avoid
+ ambiguity.
+ If <em class="replaceable"><code>count</code></em> is
+ omitted in a <code class="literal">FETCH</code> clause, it defaults to 1.
+ The <code class="literal">WITH TIES</code> option is used to return any additional
+ rows that tie for the last place in the result set according to
+ the <code class="literal">ORDER BY</code> clause; <code class="literal">ORDER BY</code>
+ is mandatory in this case, and <code class="literal">SKIP LOCKED</code> is
+ not allowed.
+ <code class="literal">ROW</code> and <code class="literal">ROWS</code> as well as
+ <code class="literal">FIRST</code> and <code class="literal">NEXT</code> are noise
+ words that don't influence the effects of these clauses.
+ According to the standard, the <code class="literal">OFFSET</code> clause must come
+ before the <code class="literal">FETCH</code> clause if both are present; but
+ <span class="productname">PostgreSQL</span> is laxer and allows either order.
+ </p><p>
+ When using <code class="literal">LIMIT</code>, it is a good idea to use an
+ <code class="literal">ORDER BY</code> clause that constrains the result rows into a
+ unique order. Otherwise you will get an unpredictable subset of
+ the query's rows — you might be asking for the tenth through
+ twentieth rows, but tenth through twentieth in what ordering? You
+ don't know what ordering unless you specify <code class="literal">ORDER BY</code>.
+ </p><p>
+ The query planner takes <code class="literal">LIMIT</code> into account when
+ generating a query plan, so you are very likely to get different
+ plans (yielding different row orders) depending on what you use
+ for <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code>. Thus, using
+ different <code class="literal">LIMIT</code>/<code class="literal">OFFSET</code> values to select
+ different subsets of a query result <span class="emphasis"><em>will give
+ inconsistent results</em></span> unless you enforce a predictable
+ result ordering with <code class="literal">ORDER BY</code>. This is not a bug; it
+ is an inherent consequence of the fact that SQL does not promise
+ to deliver the results of a query in any particular order unless
+ <code class="literal">ORDER BY</code> is used to constrain the order.
+ </p><p>
+ It is even possible for repeated executions of the same <code class="literal">LIMIT</code>
+ query to return different subsets of the rows of a table, if there
+ is not an <code class="literal">ORDER BY</code> to enforce selection of a deterministic
+ subset. Again, this is not a bug; determinism of the results is
+ simply not guaranteed in such a case.
+ </p></div><div class="refsect2" id="SQL-FOR-UPDATE-SHARE"><h3>The Locking Clause</h3><p>
+ <code class="literal">FOR UPDATE</code>, <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR SHARE</code>
+ and <code class="literal">FOR KEY SHARE</code>
+ are <em class="firstterm">locking clauses</em>; they affect how <code class="literal">SELECT</code>
+ locks rows as they are obtained from the table.
+ </p><p>
+ The locking clause has the general form
+
+</p><pre class="synopsis">
+FOR <em class="replaceable"><code>lock_strength</code></em> [ OF <em class="replaceable"><code>table_name</code></em> [, ...] ] [ NOWAIT | SKIP LOCKED ]
+</pre><p>
+
+ where <em class="replaceable"><code>lock_strength</code></em> can be one of
+
+</p><pre class="synopsis">
+UPDATE
+NO KEY UPDATE
+SHARE
+KEY SHARE
+</pre><p>
+ </p><p>
+ For more information on each row-level lock mode, refer to
+ <a class="xref" href="explicit-locking.html#LOCKING-ROWS" title="13.3.2. Row-Level Locks">Section 13.3.2</a>.
+ </p><p>
+ To prevent the operation from waiting for other transactions to commit,
+ use either the <code class="literal">NOWAIT</code> or <code class="literal">SKIP LOCKED</code>
+ option. With <code class="literal">NOWAIT</code>, the statement reports an error, rather
+ than waiting, if a selected row cannot be locked immediately.
+ With <code class="literal">SKIP LOCKED</code>, any selected rows that cannot be
+ immediately locked are skipped. Skipping locked rows provides an
+ inconsistent view of the data, so this is not suitable for general purpose
+ work, but can be used to avoid lock contention with multiple consumers
+ accessing a queue-like table.
+ Note that <code class="literal">NOWAIT</code> and <code class="literal">SKIP LOCKED</code> apply only
+ to the row-level lock(s) — the required <code class="literal">ROW SHARE</code>
+ table-level lock is still taken in the ordinary way (see
+ <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>). You can use
+ <a class="link" href="sql-lock.html" title="LOCK"><code class="command">LOCK</code></a>
+ with the <code class="literal">NOWAIT</code> option first,
+ if you need to acquire the table-level lock without waiting.
+ </p><p>
+ If specific tables are named in a locking clause,
+ then only rows coming from those tables are locked; any other
+ tables used in the <code class="command">SELECT</code> are simply read as
+ usual. A locking
+ clause without a table list affects all tables used in the statement.
+ If a locking clause is
+ applied to a view or sub-query, it affects all tables used in
+ the view or sub-query.
+ However, these clauses
+ do not apply to <code class="literal">WITH</code> queries referenced by the primary query.
+ If you want row locking to occur within a <code class="literal">WITH</code> query, specify
+ a locking clause within the <code class="literal">WITH</code> query.
+ </p><p>
+ Multiple locking
+ clauses can be written if it is necessary to specify different locking
+ behavior for different tables. If the same table is mentioned (or
+ implicitly affected) by more than one locking clause,
+ then it is processed as if it was only specified by the strongest one.
+ Similarly, a table is processed
+ as <code class="literal">NOWAIT</code> if that is specified in any of the clauses
+ affecting it. Otherwise, it is processed
+ as <code class="literal">SKIP LOCKED</code> if that is specified in any of the
+ clauses affecting it.
+ </p><p>
+ The locking clauses cannot be
+ used in contexts where returned rows cannot be clearly identified with
+ individual table rows; for example they cannot be used with aggregation.
+ </p><p>
+ When a locking clause
+ appears at the top level of a <code class="command">SELECT</code> query, the rows that
+ are locked are exactly those that are returned by the query; in the
+ case of a join query, the rows locked are those that contribute to
+ returned join rows. In addition, rows that satisfied the query
+ conditions as of the query snapshot will be locked, although they
+ will not be returned if they were updated after the snapshot
+ and no longer satisfy the query conditions. If a
+ <code class="literal">LIMIT</code> is used, locking stops
+ once enough rows have been returned to satisfy the limit (but note that
+ rows skipped over by <code class="literal">OFFSET</code> will get locked). Similarly,
+ if a locking clause
+ is used in a cursor's query, only rows actually fetched or stepped past
+ by the cursor will be locked.
+ </p><p>
+ When a locking clause
+ appears in a sub-<code class="command">SELECT</code>, the rows locked are those
+ returned to the outer query by the sub-query. This might involve
+ fewer rows than inspection of the sub-query alone would suggest,
+ since conditions from the outer query might be used to optimize
+ execution of the sub-query. For example,
+</p><pre class="programlisting">
+SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss WHERE col1 = 5;
+</pre><p>
+ will lock only rows having <code class="literal">col1 = 5</code>, even though that
+ condition is not textually within the sub-query.
+ </p><p>
+ Previous releases failed to preserve a lock which is upgraded by a later
+ savepoint. For example, this code:
+</p><pre class="programlisting">
+BEGIN;
+SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
+SAVEPOINT s;
+UPDATE mytable SET ... WHERE key = 1;
+ROLLBACK TO s;
+</pre><p>
+ would fail to preserve the <code class="literal">FOR UPDATE</code> lock after the
+ <code class="command">ROLLBACK TO</code>. This has been fixed in release 9.3.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ It is possible for a <code class="command">SELECT</code> command running at the <code class="literal">READ
+ COMMITTED</code> transaction isolation level and using <code class="literal">ORDER
+ BY</code> and a locking clause to return rows out of
+ order. This is because <code class="literal">ORDER BY</code> is applied first.
+ The command sorts the result, but might then block trying to obtain a lock
+ on one or more of the rows. Once the <code class="literal">SELECT</code> unblocks, some
+ of the ordering column values might have been modified, leading to those
+ rows appearing to be out of order (though they are in order in terms
+ of the original column values). This can be worked around at need by
+ placing the <code class="literal">FOR UPDATE/SHARE</code> clause in a sub-query,
+ for example
+</p><pre class="programlisting">
+SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss ORDER BY column1;
+</pre><p>
+ Note that this will result in locking all rows of <code class="structname">mytable</code>,
+ whereas <code class="literal">FOR UPDATE</code> at the top level would lock only the
+ actually returned rows. This can make for a significant performance
+ difference, particularly if the <code class="literal">ORDER BY</code> is combined with
+ <code class="literal">LIMIT</code> or other restrictions. So this technique is recommended
+ only if concurrent updates of the ordering columns are expected and a
+ strictly sorted result is required.
+ </p><p>
+ At the <code class="literal">REPEATABLE READ</code> or <code class="literal">SERIALIZABLE</code>
+ transaction isolation level this would cause a serialization failure (with
+ an <code class="literal">SQLSTATE</code> of <code class="literal">'40001'</code>), so there is
+ no possibility of receiving rows out of order under these isolation levels.
+ </p></div></div><div class="refsect2" id="SQL-TABLE"><h3><code class="literal">TABLE</code> Command</h3><p>
+ The command
+</p><pre class="programlisting">
+TABLE <em class="replaceable"><code>name</code></em>
+</pre><p>
+ is equivalent to
+</p><pre class="programlisting">
+SELECT * FROM <em class="replaceable"><code>name</code></em>
+</pre><p>
+ It can be used as a top-level command or as a space-saving syntax
+ variant in parts of complex queries. Only the <code class="literal">WITH</code>,
+ <code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>,
+ <code class="literal">ORDER BY</code>, <code class="literal">LIMIT</code>, <code class="literal">OFFSET</code>,
+ <code class="literal">FETCH</code> and <code class="literal">FOR</code> locking clauses can be used
+ with <code class="command">TABLE</code>; the <code class="literal">WHERE</code> clause and any form of
+ aggregation cannot
+ be used.
+ </p></div></div><div class="refsect1" id="id-1.9.3.172.9"><h2>Examples</h2><p>
+ To join the table <code class="literal">films</code> with the table
+ <code class="literal">distributors</code>:
+
+</p><pre class="programlisting">
+SELECT f.title, f.did, d.name, f.date_prod, f.kind
+ FROM distributors d JOIN films f USING (did);
+
+ title | did | name | date_prod | kind
+-------------------+-----+--------------+------------+----------
+ The Third Man | 101 | British Lion | 1949-12-23 | Drama
+ The African Queen | 101 | British Lion | 1951-08-11 | Romantic
+ ...
+</pre><p>
+ </p><p>
+ To sum the column <code class="literal">len</code> of all films and group
+ the results by <code class="literal">kind</code>:
+
+</p><pre class="programlisting">
+SELECT kind, sum(len) AS total FROM films GROUP BY kind;
+
+ kind | total
+----------+-------
+ Action | 07:34
+ Comedy | 02:58
+ Drama | 14:28
+ Musical | 06:42
+ Romantic | 04:38
+</pre><p>
+ </p><p>
+ To sum the column <code class="literal">len</code> of all films, group
+ the results by <code class="literal">kind</code> and show those group totals
+ that are less than 5 hours:
+
+</p><pre class="programlisting">
+SELECT kind, sum(len) AS total
+ FROM films
+ GROUP BY kind
+ HAVING sum(len) &lt; interval '5 hours';
+
+ kind | total
+----------+-------
+ Comedy | 02:58
+ Romantic | 04:38
+</pre><p>
+ </p><p>
+ The following two examples are identical ways of sorting the individual
+ results according to the contents of the second column
+ (<code class="literal">name</code>):
+
+</p><pre class="programlisting">
+SELECT * FROM distributors ORDER BY name;
+SELECT * FROM distributors ORDER BY 2;
+
+ did | name
+-----+------------------
+ 109 | 20th Century Fox
+ 110 | Bavaria Atelier
+ 101 | British Lion
+ 107 | Columbia
+ 102 | Jean Luc Godard
+ 113 | Luso films
+ 104 | Mosfilm
+ 103 | Paramount
+ 106 | Toho
+ 105 | United Artists
+ 111 | Walt Disney
+ 112 | Warner Bros.
+ 108 | Westward
+</pre><p>
+ </p><p>
+ The next example shows how to obtain the union of the tables
+ <code class="literal">distributors</code> and
+ <code class="literal">actors</code>, restricting the results to those that begin
+ with the letter W in each table. Only distinct rows are wanted, so the
+ key word <code class="literal">ALL</code> is omitted.
+
+</p><pre class="programlisting">
+distributors: actors:
+ did | name id | name
+-----+-------------- ----+----------------
+ 108 | Westward 1 | Woody Allen
+ 111 | Walt Disney 2 | Warren Beatty
+ 112 | Warner Bros. 3 | Walter Matthau
+ ... ...
+
+SELECT distributors.name
+ FROM distributors
+ WHERE distributors.name LIKE 'W%'
+UNION
+SELECT actors.name
+ FROM actors
+ WHERE actors.name LIKE 'W%';
+
+ name
+----------------
+ Walt Disney
+ Walter Matthau
+ Warner Bros.
+ Warren Beatty
+ Westward
+ Woody Allen
+</pre><p>
+ </p><p>
+ This example shows how to use a function in the <code class="literal">FROM</code>
+ clause, both with and without a column definition list:
+
+</p><pre class="programlisting">
+CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS $$
+ SELECT * FROM distributors WHERE did = $1;
+$$ LANGUAGE SQL;
+
+SELECT * FROM distributors(111);
+ did | name
+-----+-------------
+ 111 | Walt Disney
+
+CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS $$
+ SELECT * FROM distributors WHERE did = $1;
+$$ LANGUAGE SQL;
+
+SELECT * FROM distributors_2(111) AS (f1 int, f2 text);
+ f1 | f2
+-----+-------------
+ 111 | Walt Disney
+</pre><p>
+ </p><p>
+ Here is an example of a function with an ordinality column added:
+
+</p><pre class="programlisting">
+SELECT * FROM unnest(ARRAY['a','b','c','d','e','f']) WITH ORDINALITY;
+ unnest | ordinality
+--------+----------
+ a | 1
+ b | 2
+ c | 3
+ d | 4
+ e | 5
+ f | 6
+(6 rows)
+</pre><p>
+ </p><p>
+ This example shows how to use a simple <code class="literal">WITH</code> clause:
+
+</p><pre class="programlisting">
+WITH t AS (
+ SELECT random() as x FROM generate_series(1, 3)
+ )
+SELECT * FROM t
+UNION ALL
+SELECT * FROM t
+
+ x
+--------------------
+ 0.534150459803641
+ 0.520092216785997
+ 0.0735620250925422
+ 0.534150459803641
+ 0.520092216785997
+ 0.0735620250925422
+</pre><p>
+
+ Notice that the <code class="literal">WITH</code> query was evaluated only once,
+ so that we got two sets of the same three random values.
+ </p><p>
+ This example uses <code class="literal">WITH RECURSIVE</code> to find all
+ subordinates (direct or indirect) of the employee Mary, and their
+ level of indirectness, from a table that shows only direct
+ subordinates:
+
+</p><pre class="programlisting">
+WITH RECURSIVE employee_recursive(distance, employee_name, manager_name) AS (
+ SELECT 1, employee_name, manager_name
+ FROM employee
+ WHERE manager_name = 'Mary'
+ UNION ALL
+ SELECT er.distance + 1, e.employee_name, e.manager_name
+ FROM employee_recursive er, employee e
+ WHERE er.employee_name = e.manager_name
+ )
+SELECT distance, employee_name FROM employee_recursive;
+</pre><p>
+
+ Notice the typical form of recursive queries:
+ an initial condition, followed by <code class="literal">UNION</code>,
+ followed by the recursive part of the query. Be sure that the
+ recursive part of the query will eventually return no tuples, or
+ else the query will loop indefinitely. (See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a>
+ for more examples.)
+ </p><p>
+ This example uses <code class="literal">LATERAL</code> to apply a set-returning function
+ <code class="function">get_product_names()</code> for each row of the
+ <code class="structname">manufacturers</code> table:
+
+</p><pre class="programlisting">
+SELECT m.name AS mname, pname
+FROM manufacturers m, LATERAL get_product_names(m.id) pname;
+</pre><p>
+
+ Manufacturers not currently having any products would not appear in the
+ result, since it is an inner join. If we wished to include the names of
+ such manufacturers in the result, we could do:
+
+</p><pre class="programlisting">
+SELECT m.name AS mname, pname
+FROM manufacturers m LEFT JOIN LATERAL get_product_names(m.id) pname ON true;
+</pre></div><div class="refsect1" id="id-1.9.3.172.10"><h2>Compatibility</h2><p>
+ Of course, the <code class="command">SELECT</code> statement is compatible
+ with the SQL standard. But there are some extensions and some
+ missing features.
+ </p><div class="refsect2" id="id-1.9.3.172.10.3"><h3>Omitted <code class="literal">FROM</code> Clauses</h3><p>
+ <span class="productname">PostgreSQL</span> allows one to omit the
+ <code class="literal">FROM</code> clause. It has a straightforward use to
+ compute the results of simple expressions:
+</p><pre class="programlisting">
+SELECT 2+2;
+
+ ?column?
+----------
+ 4
+</pre><p>
+ Some other <acronym class="acronym">SQL</acronym> databases cannot do this except
+ by introducing a dummy one-row table from which to do the
+ <code class="command">SELECT</code>.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.4"><h3>Empty <code class="literal">SELECT</code> Lists</h3><p>
+ The list of output expressions after <code class="literal">SELECT</code> can be
+ empty, producing a zero-column result table.
+ This is not valid syntax according to the SQL standard.
+ <span class="productname">PostgreSQL</span> allows it to be consistent with
+ allowing zero-column tables.
+ However, an empty list is not allowed when <code class="literal">DISTINCT</code> is used.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.5"><h3>Omitting the <code class="literal">AS</code> Key Word</h3><p>
+ In the SQL standard, the optional key word <code class="literal">AS</code> can be
+ omitted before an output column name whenever the new column name
+ is a valid column name (that is, not the same as any reserved
+ keyword). <span class="productname">PostgreSQL</span> is slightly more
+ restrictive: <code class="literal">AS</code> is required if the new column name
+ matches any keyword at all, reserved or not. Recommended practice is
+ to use <code class="literal">AS</code> or double-quote output column names, to prevent
+ any possible conflict against future keyword additions.
+ </p><p>
+ In <code class="literal">FROM</code> items, both the standard and
+ <span class="productname">PostgreSQL</span> allow <code class="literal">AS</code> to
+ be omitted before an alias that is an unreserved keyword. But
+ this is impractical for output column names, because of syntactic
+ ambiguities.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.6"><h3><code class="literal">ONLY</code> and Inheritance</h3><p>
+ The SQL standard requires parentheses around the table name when
+ writing <code class="literal">ONLY</code>, for example <code class="literal">SELECT * FROM ONLY
+ (tab1), ONLY (tab2) WHERE ...</code>. <span class="productname">PostgreSQL</span>
+ considers these parentheses to be optional.
+ </p><p>
+ <span class="productname">PostgreSQL</span> allows a trailing <code class="literal">*</code> to be written to
+ explicitly specify the non-<code class="literal">ONLY</code> behavior of including
+ child tables. The standard does not allow this.
+ </p><p>
+ (These points apply equally to all SQL commands supporting the
+ <code class="literal">ONLY</code> option.)
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.7"><h3><code class="literal">TABLESAMPLE</code> Clause Restrictions</h3><p>
+ The <code class="literal">TABLESAMPLE</code> clause is currently accepted only on
+ regular tables and materialized views. According to the SQL standard
+ it should be possible to apply it to any <code class="literal">FROM</code> item.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.8"><h3>Function Calls in <code class="literal">FROM</code></h3><p>
+ <span class="productname">PostgreSQL</span> allows a function call to be
+ written directly as a member of the <code class="literal">FROM</code> list. In the SQL
+ standard it would be necessary to wrap such a function call in a
+ sub-<code class="command">SELECT</code>; that is, the syntax
+ <code class="literal">FROM <em class="replaceable"><code>func</code></em>(...) <em class="replaceable"><code>alias</code></em></code>
+ is approximately equivalent to
+ <code class="literal">FROM LATERAL (SELECT <em class="replaceable"><code>func</code></em>(...)) <em class="replaceable"><code>alias</code></em></code>.
+ Note that <code class="literal">LATERAL</code> is considered to be implicit; this is
+ because the standard requires <code class="literal">LATERAL</code> semantics for an
+ <code class="literal">UNNEST()</code> item in <code class="literal">FROM</code>.
+ <span class="productname">PostgreSQL</span> treats <code class="literal">UNNEST()</code> the
+ same as other set-returning functions.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.9"><h3>Namespace Available to <code class="literal">GROUP BY</code> and <code class="literal">ORDER BY</code></h3><p>
+ In the SQL-92 standard, an <code class="literal">ORDER BY</code> clause can
+ only use output column names or numbers, while a <code class="literal">GROUP
+ BY</code> clause can only use expressions based on input column
+ names. <span class="productname">PostgreSQL</span> extends each of
+ these clauses to allow the other choice as well (but it uses the
+ standard's interpretation if there is ambiguity).
+ <span class="productname">PostgreSQL</span> also allows both clauses to
+ specify arbitrary expressions. Note that names appearing in an
+ expression will always be taken as input-column names, not as
+ output-column names.
+ </p><p>
+ SQL:1999 and later use a slightly different definition which is not
+ entirely upward compatible with SQL-92.
+ In most cases, however, <span class="productname">PostgreSQL</span>
+ will interpret an <code class="literal">ORDER BY</code> or <code class="literal">GROUP
+ BY</code> expression the same way SQL:1999 does.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.10"><h3>Functional Dependencies</h3><p>
+ <span class="productname">PostgreSQL</span> recognizes functional dependency
+ (allowing columns to be omitted from <code class="literal">GROUP BY</code>) only when
+ a table's primary key is included in the <code class="literal">GROUP BY</code> list.
+ The SQL standard specifies additional conditions that should be
+ recognized.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.11"><h3><code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></h3><p>
+ The clauses <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code>
+ are <span class="productname">PostgreSQL</span>-specific syntax, also
+ used by <span class="productname">MySQL</span>. The SQL:2008 standard
+ has introduced the clauses <code class="literal">OFFSET ... FETCH {FIRST|NEXT}
+ ...</code> for the same functionality, as shown above
+ in <a class="xref" href="sql-select.html#SQL-LIMIT" title="LIMIT Clause">LIMIT Clause</a>. This
+ syntax is also used by <span class="productname">IBM DB2</span>.
+ (Applications written for <span class="productname">Oracle</span>
+ frequently use a workaround involving the automatically
+ generated <code class="literal">rownum</code> column, which is not available in
+ PostgreSQL, to implement the effects of these clauses.)
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.12"><h3><code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR UPDATE</code>, <code class="literal">FOR SHARE</code>, <code class="literal">FOR KEY SHARE</code></h3><p>
+ Although <code class="literal">FOR UPDATE</code> appears in the SQL standard, the
+ standard allows it only as an option of <code class="command">DECLARE CURSOR</code>.
+ <span class="productname">PostgreSQL</span> allows it in any <code class="command">SELECT</code>
+ query as well as in sub-<code class="command">SELECT</code>s, but this is an extension.
+ The <code class="literal">FOR NO KEY UPDATE</code>, <code class="literal">FOR SHARE</code> and
+ <code class="literal">FOR KEY SHARE</code> variants, as well as the <code class="literal">NOWAIT</code>
+ and <code class="literal">SKIP LOCKED</code> options, do not appear in the
+ standard.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.13"><h3>Data-Modifying Statements in <code class="literal">WITH</code></h3><p>
+ <span class="productname">PostgreSQL</span> allows <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, and <code class="command">DELETE</code> to be used as <code class="literal">WITH</code>
+ queries. This is not found in the SQL standard.
+ </p></div><div class="refsect2" id="id-1.9.3.172.10.14"><h3>Nonstandard Clauses</h3><p>
+ <code class="literal">DISTINCT ON ( ... )</code> is an extension of the
+ SQL standard.
+ </p><p>
+ <code class="literal">ROWS FROM( ... )</code> is an extension of the SQL standard.
+ </p><p>
+ The <code class="literal">MATERIALIZED</code> and <code class="literal">NOT
+ MATERIALIZED</code> options of <code class="literal">WITH</code> are extensions
+ of the SQL standard.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-security-label.html" title="SECURITY LABEL">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-selectinto.html" title="SELECT INTO">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SECURITY LABEL </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SELECT INTO</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-selectinto.html b/doc/src/sgml/html/sql-selectinto.html
new file mode 100644
index 0000000..b926f2c
--- /dev/null
+++ b/doc/src/sgml/html/sql-selectinto.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SELECT INTO</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-select.html" title="SELECT" /><link rel="next" href="sql-set.html" title="SET" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SELECT INTO</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-select.html" title="SELECT">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set.html" title="SET">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SELECTINTO"><div class="titlepage"></div><a id="id-1.9.3.173.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SELECT INTO</span></h2><p>SELECT INTO — define a new table from the results of a query</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+SELECT [ ALL | DISTINCT [ ON ( <em class="replaceable"><code>expression</code></em> [, ...] ) ] ]
+ * | <em class="replaceable"><code>expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...]
+ INTO [ TEMPORARY | TEMP | UNLOGGED ] [ TABLE ] <em class="replaceable"><code>new_table</code></em>
+ [ FROM <em class="replaceable"><code>from_item</code></em> [, ...] ]
+ [ WHERE <em class="replaceable"><code>condition</code></em> ]
+ [ GROUP BY <em class="replaceable"><code>expression</code></em> [, ...] ]
+ [ HAVING <em class="replaceable"><code>condition</code></em> ]
+ [ WINDOW <em class="replaceable"><code>window_name</code></em> AS ( <em class="replaceable"><code>window_definition</code></em> ) [, ...] ]
+ [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <em class="replaceable"><code>select</code></em> ]
+ [ ORDER BY <em class="replaceable"><code>expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [ NULLS { FIRST | LAST } ] [, ...] ]
+ [ LIMIT { <em class="replaceable"><code>count</code></em> | ALL } ]
+ [ OFFSET <em class="replaceable"><code>start</code></em> [ ROW | ROWS ] ]
+ [ FETCH { FIRST | NEXT } [ <em class="replaceable"><code>count</code></em> ] { ROW | ROWS } ONLY ]
+ [ FOR { UPDATE | SHARE } [ OF <em class="replaceable"><code>table_name</code></em> [, ...] ] [ NOWAIT ] [...] ]
+</pre></div><div class="refsect1" id="id-1.9.3.173.5"><h2>Description</h2><p>
+ <code class="command">SELECT INTO</code> creates a new table and fills it
+ with data computed by a query. The data is not returned to the
+ client, as it is with a normal <code class="command">SELECT</code>. The new
+ table's columns have the names and data types associated with the
+ output columns of the <code class="command">SELECT</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.173.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></span></dt><dd><p>
+ If specified, the table is created as a temporary table. Refer
+ to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for details.
+ </p></dd><dt><span class="term"><code class="literal">UNLOGGED</code></span></dt><dd><p>
+ If specified, the table is created as an unlogged table. Refer
+ to <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a> for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>new_table</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to be created.
+ </p></dd></dl></div><p>
+ All other parameters are described in detail under <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.173.7"><h2>Notes</h2><p>
+ <a class="link" href="sql-createtableas.html" title="CREATE TABLE AS"><code class="command">CREATE TABLE AS</code></a> is functionally similar to
+ <code class="command">SELECT INTO</code>. <code class="command">CREATE TABLE AS</code>
+ is the recommended syntax, since this form of <code class="command">SELECT
+ INTO</code> is not available in <span class="application">ECPG</span>
+ or <span class="application">PL/pgSQL</span>, because they interpret the
+ <code class="literal">INTO</code> clause differently. Furthermore,
+ <code class="command">CREATE TABLE AS</code> offers a superset of the
+ functionality provided by <code class="command">SELECT INTO</code>.
+ </p><p>
+ In contrast to <code class="command">CREATE TABLE AS</code>, <code class="command">SELECT
+ INTO</code> does not allow specifying properties like a table's access
+ method with <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-METHOD"><code class="literal">USING <em class="replaceable"><code>method</code></em></code></a> or the table's
+ tablespace with <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-TABLESPACE"><code class="literal">TABLESPACE <em class="replaceable"><code>tablespace_name</code></em></code></a>. Use
+ <code class="command">CREATE TABLE AS</code> if necessary. Therefore, the default table
+ access method is chosen for the new table. See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TABLE-ACCESS-METHOD">default_table_access_method</a> for more information.
+ </p></div><div class="refsect1" id="id-1.9.3.173.8"><h2>Examples</h2><p>
+ Create a new table <code class="literal">films_recent</code> consisting of only
+ recent entries from the table <code class="literal">films</code>:
+
+</p><pre class="programlisting">
+SELECT * INTO films_recent FROM films WHERE date_prod &gt;= '2002-01-01';
+</pre></div><div class="refsect1" id="id-1.9.3.173.9"><h2>Compatibility</h2><p>
+ The SQL standard uses <code class="command">SELECT INTO</code> to
+ represent selecting values into scalar variables of a host program,
+ rather than creating a new table. This indeed is the usage found
+ in <span class="application">ECPG</span> (see <a class="xref" href="ecpg.html" title="Chapter 36. ECPG — Embedded SQL in C">Chapter 36</a>) and
+ <span class="application">PL/pgSQL</span> (see <a class="xref" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Chapter 43</a>).
+ The <span class="productname">PostgreSQL</span> usage of <code class="command">SELECT
+ INTO</code> to represent table creation is historical. Some other SQL
+ implementations also use <code class="command">SELECT INTO</code> in this way (but
+ most SQL implementations support <code class="command">CREATE TABLE AS</code>
+ instead). Apart from such compatibility considerations, it is best to use
+ <code class="command">CREATE TABLE AS</code> for this purpose in new code.
+ </p></div><div class="refsect1" id="id-1.9.3.173.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtableas.html" title="CREATE TABLE AS"><span class="refentrytitle">CREATE TABLE AS</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-select.html" title="SELECT">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set.html" title="SET">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SELECT </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-set-constraints.html b/doc/src/sgml/html/sql-set-constraints.html
new file mode 100644
index 0000000..726fc0a
--- /dev/null
+++ b/doc/src/sgml/html/sql-set-constraints.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET CONSTRAINTS</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set.html" title="SET" /><link rel="next" href="sql-set-role.html" title="SET ROLE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET CONSTRAINTS</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set.html" title="SET">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set-role.html" title="SET ROLE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET-CONSTRAINTS"><div class="titlepage"></div><a id="id-1.9.3.175.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET CONSTRAINTS</span></h2><p>SET CONSTRAINTS — set constraint check timing for the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET CONSTRAINTS { ALL | <em class="replaceable"><code>name</code></em> [, ...] } { DEFERRED | IMMEDIATE }
+</pre></div><div class="refsect1" id="id-1.9.3.175.5"><h2>Description</h2><p>
+ <code class="command">SET CONSTRAINTS</code> sets the behavior of constraint
+ checking within the current transaction. <code class="literal">IMMEDIATE</code>
+ constraints are checked at the end of each
+ statement. <code class="literal">DEFERRED</code> constraints are not checked until
+ transaction commit. Each constraint has its own
+ <code class="literal">IMMEDIATE</code> or <code class="literal">DEFERRED</code> mode.
+ </p><p>
+ Upon creation, a constraint is given one of three
+ characteristics: <code class="literal">DEFERRABLE INITIALLY DEFERRED</code>,
+ <code class="literal">DEFERRABLE INITIALLY IMMEDIATE</code>, or
+ <code class="literal">NOT DEFERRABLE</code>. The third
+ class is always <code class="literal">IMMEDIATE</code> and is not affected by the
+ <code class="command">SET CONSTRAINTS</code> command. The first two classes start
+ every transaction in the indicated mode, but their behavior can be changed
+ within a transaction by <code class="command">SET CONSTRAINTS</code>.
+ </p><p>
+ <code class="command">SET CONSTRAINTS</code> with a list of constraint names changes
+ the mode of just those constraints (which must all be deferrable). Each
+ constraint name can be schema-qualified. The
+ current schema search path is used to find the first matching name if
+ no schema name is specified. <code class="command">SET CONSTRAINTS ALL</code>
+ changes the mode of all deferrable constraints.
+ </p><p>
+ When <code class="command">SET CONSTRAINTS</code> changes the mode of a constraint
+ from <code class="literal">DEFERRED</code>
+ to <code class="literal">IMMEDIATE</code>, the new mode takes effect
+ retroactively: any outstanding data modifications that would have
+ been checked at the end of the transaction are instead checked during the
+ execution of the <code class="command">SET CONSTRAINTS</code> command.
+ If any such constraint is violated, the <code class="command">SET CONSTRAINTS</code>
+ fails (and does not change the constraint mode). Thus, <code class="command">SET
+ CONSTRAINTS</code> can be used to force checking of constraints to
+ occur at a specific point in a transaction.
+ </p><p>
+ Currently, only <code class="literal">UNIQUE</code>, <code class="literal">PRIMARY KEY</code>,
+ <code class="literal">REFERENCES</code> (foreign key), and <code class="literal">EXCLUDE</code>
+ constraints are affected by this setting.
+ <code class="literal">NOT NULL</code> and <code class="literal">CHECK</code> constraints are
+ always checked immediately when a row is inserted or modified
+ (<span class="emphasis"><em>not</em></span> at the end of the statement).
+ Uniqueness and exclusion constraints that have not been declared
+ <code class="literal">DEFERRABLE</code> are also checked immediately.
+ </p><p>
+ The firing of triggers that are declared as <span class="quote">“<span class="quote">constraint triggers</span>”</span>
+ is also controlled by this setting — they fire at the same time
+ that the associated constraint should be checked.
+ </p></div><div class="refsect1" id="id-1.9.3.175.6"><h2>Notes</h2><p>
+ Because <span class="productname">PostgreSQL</span> does not require constraint
+ names to be unique within a schema (but only per-table), it is possible
+ that there is more than one match for a specified constraint name.
+ In this case <code class="command">SET CONSTRAINTS</code> will act on all matches.
+ For a non-schema-qualified name, once a match or matches have been found in
+ some schema in the search path, schemas appearing later in the path are not
+ searched.
+ </p><p>
+ This command only alters the behavior of constraints within the
+ current transaction. Issuing this outside of a transaction block
+ emits a warning and otherwise has no effect.
+ </p></div><div class="refsect1" id="id-1.9.3.175.7"><h2>Compatibility</h2><p>
+ This command complies with the behavior defined in the SQL
+ standard, except for the limitation that, in
+ <span class="productname">PostgreSQL</span>, it does not apply to
+ <code class="literal">NOT NULL</code> and <code class="literal">CHECK</code> constraints.
+ Also, <span class="productname">PostgreSQL</span> checks non-deferrable
+ uniqueness constraints immediately, not at end of statement as the
+ standard would suggest.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set.html" title="SET">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set-role.html" title="SET ROLE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET ROLE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-set-role.html b/doc/src/sgml/html/sql-set-role.html
new file mode 100644
index 0000000..6bbfe78
--- /dev/null
+++ b/doc/src/sgml/html/sql-set-role.html
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET ROLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set-constraints.html" title="SET CONSTRAINTS" /><link rel="next" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET ROLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set-constraints.html" title="SET CONSTRAINTS">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET-ROLE"><div class="titlepage"></div><a id="id-1.9.3.176.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET ROLE</span></h2><p>SET ROLE — set the current user identifier of the current session</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET [ SESSION | LOCAL ] ROLE <em class="replaceable"><code>role_name</code></em>
+SET [ SESSION | LOCAL ] ROLE NONE
+RESET ROLE
+</pre></div><div class="refsect1" id="id-1.9.3.176.5"><h2>Description</h2><p>
+ This command sets the current user
+ identifier of the current SQL session to be <em class="replaceable"><code>role_name</code></em>. The role name can be
+ written as either an identifier or a string literal.
+ After <code class="command">SET ROLE</code>, permissions checking for SQL commands
+ is carried out as though the named role were the one that had logged
+ in originally.
+ </p><p>
+ The specified <em class="replaceable"><code>role_name</code></em>
+ must be a role that the current session user is a member of.
+ (If the session user is a superuser, any role can be selected.)
+ </p><p>
+ The <code class="literal">SESSION</code> and <code class="literal">LOCAL</code> modifiers act the same
+ as for the regular <a class="link" href="sql-set.html" title="SET"><code class="command">SET</code></a>
+ command.
+ </p><p>
+ <code class="literal">SET ROLE NONE</code> sets the current user identifier to the
+ current session user identifier, as returned by
+ <code class="function">session_user</code>. <code class="literal">RESET ROLE</code> sets the
+ current user identifier to the connection-time setting specified by the
+ <a class="link" href="libpq-connect.html#LIBPQ-CONNECT-OPTIONS">command-line options</a>,
+ <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a>, or
+ <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE</code></a>,
+ if any such settings exist. Otherwise, <code class="literal">RESET ROLE</code> sets
+ the current user identifier to the current session user identifier. These
+ forms can be executed by any user.
+ </p></div><div class="refsect1" id="id-1.9.3.176.6"><h2>Notes</h2><p>
+ Using this command, it is possible to either add privileges or restrict
+ one's privileges. If the session user role has the <code class="literal">INHERIT</code>
+ attribute, then it automatically has all the privileges of every role that
+ it could <code class="command">SET ROLE</code> to; in this case <code class="command">SET ROLE</code>
+ effectively drops all the privileges assigned directly to the session user
+ and to the other roles it is a member of, leaving only the privileges
+ available to the named role. On the other hand, if the session user role
+ has the <code class="literal">NOINHERIT</code> attribute, <code class="command">SET ROLE</code> drops the
+ privileges assigned directly to the session user and instead acquires the
+ privileges available to the named role.
+ </p><p>
+ In particular, when a superuser chooses to <code class="command">SET ROLE</code> to a
+ non-superuser role, they lose their superuser privileges.
+ </p><p>
+ <code class="command">SET ROLE</code> has effects comparable to
+ <a class="link" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION"><code class="command">SET SESSION AUTHORIZATION</code></a>, but the privilege
+ checks involved are quite different. Also,
+ <code class="command">SET SESSION AUTHORIZATION</code> determines which roles are
+ allowable for later <code class="command">SET ROLE</code> commands, whereas changing
+ roles with <code class="command">SET ROLE</code> does not change the set of roles
+ allowed to a later <code class="command">SET ROLE</code>.
+ </p><p>
+ <code class="command">SET ROLE</code> does not process session variables as specified by
+ the role's <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a> settings; this only happens during
+ login.
+ </p><p>
+ <code class="command">SET ROLE</code> cannot be used within a
+ <code class="literal">SECURITY DEFINER</code> function.
+ </p></div><div class="refsect1" id="id-1.9.3.176.7"><h2>Examples</h2><pre class="programlisting">
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ peter | peter
+
+SET ROLE 'paul';
+
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ peter | paul
+</pre></div><div class="refsect1" id="id-1.9.3.176.8"><h2>Compatibility</h2><p>
+ <span class="productname">PostgreSQL</span>
+ allows identifier syntax (<code class="literal">"<em class="replaceable"><code>rolename</code></em>"</code>), while
+ the SQL standard requires the role name to be written as a string
+ literal. SQL does not allow this command during a transaction;
+ <span class="productname">PostgreSQL</span> does not make this
+ restriction because there is no reason to.
+ The <code class="literal">SESSION</code> and <code class="literal">LOCAL</code> modifiers are a
+ <span class="productname">PostgreSQL</span> extension, as is the
+ <code class="literal">RESET</code> syntax.
+ </p></div><div class="refsect1" id="id-1.9.3.176.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION"><span class="refentrytitle">SET SESSION AUTHORIZATION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set-constraints.html" title="SET CONSTRAINTS">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET CONSTRAINTS </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET SESSION AUTHORIZATION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-set-session-authorization.html b/doc/src/sgml/html/sql-set-session-authorization.html
new file mode 100644
index 0000000..13a48c9
--- /dev/null
+++ b/doc/src/sgml/html/sql-set-session-authorization.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET SESSION AUTHORIZATION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set-role.html" title="SET ROLE" /><link rel="next" href="sql-set-transaction.html" title="SET TRANSACTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET SESSION AUTHORIZATION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set-role.html" title="SET ROLE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set-transaction.html" title="SET TRANSACTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET-SESSION-AUTHORIZATION"><div class="titlepage"></div><a id="id-1.9.3.177.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET SESSION AUTHORIZATION</span></h2><p>SET SESSION AUTHORIZATION — set the session user identifier and the current user identifier of the current session</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <em class="replaceable"><code>user_name</code></em>
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
+RESET SESSION AUTHORIZATION
+</pre></div><div class="refsect1" id="id-1.9.3.177.5"><h2>Description</h2><p>
+ This command sets the session user identifier and the current user
+ identifier of the current SQL session to be <em class="replaceable"><code>user_name</code></em>. The user name can be
+ written as either an identifier or a string literal. Using this
+ command, it is possible, for example, to temporarily become an
+ unprivileged user and later switch back to being a superuser.
+ </p><p>
+ The session user identifier is initially set to be the (possibly
+ authenticated) user name provided by the client. The current user
+ identifier is normally equal to the session user identifier, but
+ might change temporarily in the context of <code class="literal">SECURITY DEFINER</code>
+ functions and similar mechanisms; it can also be changed by
+ <a class="link" href="sql-set-role.html" title="SET ROLE"><code class="command">SET ROLE</code></a>.
+ The current user identifier is relevant for permission checking.
+ </p><p>
+ The session user identifier can be changed only if the initial session
+ user (the <em class="firstterm">authenticated user</em>) had the
+ superuser privilege. Otherwise, the command is accepted only if it
+ specifies the authenticated user name.
+ </p><p>
+ The <code class="literal">SESSION</code> and <code class="literal">LOCAL</code> modifiers act the same
+ as for the regular <a class="link" href="sql-set.html" title="SET"><code class="command">SET</code></a>
+ command.
+ </p><p>
+ The <code class="literal">DEFAULT</code> and <code class="literal">RESET</code> forms reset the session
+ and current user identifiers to be the originally authenticated user
+ name. These forms can be executed by any user.
+ </p></div><div class="refsect1" id="id-1.9.3.177.6"><h2>Notes</h2><p>
+ <code class="command">SET SESSION AUTHORIZATION</code> cannot be used within a
+ <code class="literal">SECURITY DEFINER</code> function.
+ </p></div><div class="refsect1" id="id-1.9.3.177.7"><h2>Examples</h2><pre class="programlisting">
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ peter | peter
+
+SET SESSION AUTHORIZATION 'paul';
+
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
+--------------+--------------
+ paul | paul
+</pre></div><div class="refsect1" id="id-1.9.3.177.8"><h2>Compatibility</h2><p>
+ The SQL standard allows some other expressions to appear in place
+ of the literal <em class="replaceable"><code>user_name</code></em>, but these options
+ are not important in practice. <span class="productname">PostgreSQL</span>
+ allows identifier syntax (<code class="literal">"<em class="replaceable"><code>username</code></em>"</code>), which SQL
+ does not. SQL does not allow this command during a transaction;
+ <span class="productname">PostgreSQL</span> does not make this
+ restriction because there is no reason to.
+ The <code class="literal">SESSION</code> and <code class="literal">LOCAL</code> modifiers are a
+ <span class="productname">PostgreSQL</span> extension, as is the
+ <code class="literal">RESET</code> syntax.
+ </p><p>
+ The privileges necessary to execute this command are left
+ implementation-defined by the standard.
+ </p></div><div class="refsect1" id="id-1.9.3.177.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set-role.html" title="SET ROLE"><span class="refentrytitle">SET ROLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set-role.html" title="SET ROLE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set-transaction.html" title="SET TRANSACTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET ROLE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET TRANSACTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-set-transaction.html b/doc/src/sgml/html/sql-set-transaction.html
new file mode 100644
index 0000000..41dac01
--- /dev/null
+++ b/doc/src/sgml/html/sql-set-transaction.html
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET TRANSACTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION" /><link rel="next" href="sql-show.html" title="SHOW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET TRANSACTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-show.html" title="SHOW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.178.1" class="indexterm"></a><a id="id-1.9.3.178.2" class="indexterm"></a><a id="id-1.9.3.178.3" class="indexterm"></a><a id="id-1.9.3.178.4" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET TRANSACTION</span></h2><p>SET TRANSACTION — set the characteristics of the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET TRANSACTION <em class="replaceable"><code>transaction_mode</code></em> [, ...]
+SET TRANSACTION SNAPSHOT <em class="replaceable"><code>snapshot_id</code></em>
+SET SESSION CHARACTERISTICS AS TRANSACTION <em class="replaceable"><code>transaction_mode</code></em> [, ...]
+
+<span class="phrase">where <em class="replaceable"><code>transaction_mode</code></em> is one of:</span>
+
+ ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
+ READ WRITE | READ ONLY
+ [ NOT ] DEFERRABLE
+</pre></div><div class="refsect1" id="id-1.9.3.178.8"><h2>Description</h2><p>
+ The <code class="command">SET TRANSACTION</code> command sets the
+ characteristics of the current transaction. It has no effect on any
+ subsequent transactions. <code class="command">SET SESSION
+ CHARACTERISTICS</code> sets the default transaction
+ characteristics for subsequent transactions of a session. These
+ defaults can be overridden by <code class="command">SET TRANSACTION</code>
+ for an individual transaction.
+ </p><p>
+ The available transaction characteristics are the transaction
+ isolation level, the transaction access mode (read/write or
+ read-only), and the deferrable mode.
+ In addition, a snapshot can be selected, though only for the current
+ transaction, not as a session default.
+ </p><p>
+ The isolation level of a transaction determines what data the
+ transaction can see when other transactions are running concurrently:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">READ COMMITTED</code></span></dt><dd><p>
+ A statement can only see rows committed before it began. This
+ is the default.
+ </p></dd><dt><span class="term"><code class="literal">REPEATABLE READ</code></span></dt><dd><p>
+ All statements of the current transaction can only see rows committed
+ before the first query or data-modification statement was executed in
+ this transaction.
+ </p></dd><dt><span class="term"><code class="literal">SERIALIZABLE</code></span></dt><dd><p>
+ All statements of the current transaction can only see rows committed
+ before the first query or data-modification statement was executed in
+ this transaction. If a pattern of reads and writes among concurrent
+ serializable transactions would create a situation which could not
+ have occurred for any serial (one-at-a-time) execution of those
+ transactions, one of them will be rolled back with a
+ <code class="literal">serialization_failure</code> error.
+ </p></dd></dl></div><p>
+
+ The SQL standard defines one additional level, <code class="literal">READ
+ UNCOMMITTED</code>.
+ In <span class="productname">PostgreSQL</span> <code class="literal">READ
+ UNCOMMITTED</code> is treated as <code class="literal">READ COMMITTED</code>.
+ </p><p>
+ The transaction isolation level cannot be changed after the first query or
+ data-modification statement (<code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">DELETE</code>,
+ <code class="command">UPDATE</code>, <code class="command">MERGE</code>,
+ <code class="command">FETCH</code>, or
+ <code class="command">COPY</code>) of a transaction has been executed. See
+ <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a> for more information about transaction
+ isolation and concurrency control.
+ </p><p>
+ The transaction access mode determines whether the transaction is
+ read/write or read-only. Read/write is the default. When a
+ transaction is read-only, the following SQL commands are
+ disallowed: <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, <code class="command">MERGE</code>, and
+ <code class="command">COPY FROM</code> if the
+ table they would write to is not a temporary table; all
+ <code class="literal">CREATE</code>, <code class="literal">ALTER</code>, and
+ <code class="literal">DROP</code> commands; <code class="literal">COMMENT</code>,
+ <code class="literal">GRANT</code>, <code class="literal">REVOKE</code>,
+ <code class="literal">TRUNCATE</code>; and <code class="literal">EXPLAIN ANALYZE</code>
+ and <code class="literal">EXECUTE</code> if the command they would execute is
+ among those listed. This is a high-level notion of read-only that
+ does not prevent all writes to disk.
+ </p><p>
+ The <code class="literal">DEFERRABLE</code> transaction property has no effect
+ unless the transaction is also <code class="literal">SERIALIZABLE</code> and
+ <code class="literal">READ ONLY</code>. When all three of these properties are
+ selected for a
+ transaction, the transaction may block when first acquiring its snapshot,
+ after which it is able to run without the normal overhead of a
+ <code class="literal">SERIALIZABLE</code> transaction and without any risk of
+ contributing to or being canceled by a serialization failure. This mode
+ is well suited for long-running reports or backups.
+ </p><p>
+ The <code class="literal">SET TRANSACTION SNAPSHOT</code> command allows a new
+ transaction to run with the same <em class="firstterm">snapshot</em> as an existing
+ transaction. The pre-existing transaction must have exported its snapshot
+ with the <code class="literal">pg_export_snapshot</code> function (see <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.27.5. Snapshot Synchronization Functions">Section 9.27.5</a>). That function returns a
+ snapshot identifier, which must be given to <code class="literal">SET TRANSACTION
+ SNAPSHOT</code> to specify which snapshot is to be imported. The
+ identifier must be written as a string literal in this command, for example
+ <code class="literal">'00000003-0000001B-1'</code>.
+ <code class="literal">SET TRANSACTION SNAPSHOT</code> can only be executed at the
+ start of a transaction, before the first query or
+ data-modification statement (<code class="command">SELECT</code>,
+ <code class="command">INSERT</code>, <code class="command">DELETE</code>,
+ <code class="command">UPDATE</code>, <code class="command">MERGE</code>,
+ <code class="command">FETCH</code>, or
+ <code class="command">COPY</code>) of the transaction. Furthermore, the transaction
+ must already be set to <code class="literal">SERIALIZABLE</code> or
+ <code class="literal">REPEATABLE READ</code> isolation level (otherwise, the snapshot
+ would be discarded immediately, since <code class="literal">READ COMMITTED</code> mode takes
+ a new snapshot for each command). If the importing transaction uses
+ <code class="literal">SERIALIZABLE</code> isolation level, then the transaction that
+ exported the snapshot must also use that isolation level. Also, a
+ non-read-only serializable transaction cannot import a snapshot from a
+ read-only transaction.
+ </p></div><div class="refsect1" id="id-1.9.3.178.9"><h2>Notes</h2><p>
+ If <code class="command">SET TRANSACTION</code> is executed without a prior
+ <code class="command">START TRANSACTION</code> or <code class="command">BEGIN</code>,
+ it emits a warning and otherwise has no effect.
+ </p><p>
+ It is possible to dispense with <code class="command">SET TRANSACTION</code>
+ by instead specifying the desired <em class="replaceable"><code>transaction_modes</code></em> in
+ <code class="command">BEGIN</code> or <code class="command">START TRANSACTION</code>.
+ But that option is not available for <code class="command">SET TRANSACTION
+ SNAPSHOT</code>.
+ </p><p>
+ The session default transaction modes can also be set or examined via the
+ configuration parameters <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION">default_transaction_isolation</a>,
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY">default_transaction_read_only</a>, and
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE">default_transaction_deferrable</a>.
+ (In fact <code class="command">SET SESSION CHARACTERISTICS</code> is just a
+ verbose equivalent for setting these variables with <code class="command">SET</code>.)
+ This means the defaults can be set in the configuration file, via
+ <code class="command">ALTER DATABASE</code>, etc. Consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>
+ for more information.
+ </p><p>
+ The current transaction's modes can similarly be set or examined via the
+ configuration parameters <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-ISOLATION">transaction_isolation</a>,
+ <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-READ-ONLY">transaction_read_only</a>, and
+ <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-DEFERRABLE">transaction_deferrable</a>. Setting one of these
+ parameters acts the same as the corresponding <code class="command">SET
+ TRANSACTION</code> option, with the same restrictions on when it can
+ be done. However, these parameters cannot be set in the configuration
+ file, or from any source other than live SQL.
+ </p></div><div class="refsect1" id="id-1.9.3.178.10"><h2>Examples</h2><p>
+ To begin a new transaction with the same snapshot as an already
+ existing transaction, first export the snapshot from the existing
+ transaction. That will return the snapshot identifier, for example:
+
+</p><pre class="programlisting">
+BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
+SELECT pg_export_snapshot();
+ pg_export_snapshot
+---------------------
+ 00000003-0000001B-1
+(1 row)
+</pre><p>
+
+ Then give the snapshot identifier in a <code class="command">SET TRANSACTION
+ SNAPSHOT</code> command at the beginning of the newly opened
+ transaction:
+
+</p><pre class="programlisting">
+BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
+SET TRANSACTION SNAPSHOT '00000003-0000001B-1';
+</pre></div><div class="refsect1" id="R1-SQL-SET-TRANSACTION-3"><h2>Compatibility</h2><p>
+ These commands are defined in the <acronym class="acronym">SQL</acronym> standard,
+ except for the <code class="literal">DEFERRABLE</code> transaction mode
+ and the <code class="command">SET TRANSACTION SNAPSHOT</code> form, which are
+ <span class="productname">PostgreSQL</span> extensions.
+ </p><p>
+ <code class="literal">SERIALIZABLE</code> is the default transaction
+ isolation level in the standard. In
+ <span class="productname">PostgreSQL</span> the default is ordinarily
+ <code class="literal">READ COMMITTED</code>, but you can change it as
+ mentioned above.
+ </p><p>
+ In the SQL standard, there is one other transaction characteristic
+ that can be set with these commands: the size of the diagnostics
+ area. This concept is specific to embedded SQL, and therefore is
+ not implemented in the <span class="productname">PostgreSQL</span> server.
+ </p><p>
+ The SQL standard requires commas between successive <em class="replaceable"><code>transaction_modes</code></em>, but for historical
+ reasons <span class="productname">PostgreSQL</span> allows the commas to be
+ omitted.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-show.html" title="SHOW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET SESSION AUTHORIZATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SHOW</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-set.html b/doc/src/sgml/html/sql-set.html
new file mode 100644
index 0000000..5850371
--- /dev/null
+++ b/doc/src/sgml/html/sql-set.html
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-selectinto.html" title="SELECT INTO" /><link rel="next" href="sql-set-constraints.html" title="SET CONSTRAINTS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-selectinto.html" title="SELECT INTO">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set-constraints.html" title="SET CONSTRAINTS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET"><div class="titlepage"></div><a id="id-1.9.3.174.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET</span></h2><p>SET — change a run-time parameter</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SET [ SESSION | LOCAL ] <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | '<em class="replaceable"><code>value</code></em>' | DEFAULT }
+SET [ SESSION | LOCAL ] TIME ZONE { <em class="replaceable"><code>value</code></em> | '<em class="replaceable"><code>value</code></em>' | LOCAL | DEFAULT }
+</pre></div><div class="refsect1" id="id-1.9.3.174.5"><h2>Description</h2><p>
+ The <code class="command">SET</code> command changes run-time configuration
+ parameters. Many of the run-time parameters listed in
+ <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> can be changed on-the-fly with
+ <code class="command">SET</code>.
+ (Some parameters can only be changed by superusers and users who
+ have been granted <code class="literal">SET</code> privilege on that parameter.
+ There are also parameters that cannot be changed after server or
+ session start.)
+ <code class="command">SET</code> only affects the value used by the current
+ session.
+ </p><p>
+ If <code class="command">SET</code> (or equivalently <code class="command">SET SESSION</code>)
+ is issued within a transaction that is later aborted, the effects of the
+ <code class="command">SET</code> command disappear when the transaction is rolled
+ back. Once the surrounding transaction is committed, the effects
+ will persist until the end of the session, unless overridden by another
+ <code class="command">SET</code>.
+ </p><p>
+ The effects of <code class="command">SET LOCAL</code> last only till the end of
+ the current transaction, whether committed or not. A special case is
+ <code class="command">SET</code> followed by <code class="command">SET LOCAL</code> within
+ a single transaction: the <code class="command">SET LOCAL</code> value will be
+ seen until the end of the transaction, but afterwards (if the transaction
+ is committed) the <code class="command">SET</code> value will take effect.
+ </p><p>
+ The effects of <code class="command">SET</code> or <code class="command">SET LOCAL</code> are
+ also canceled by rolling back to a savepoint that is earlier than the
+ command.
+ </p><p>
+ If <code class="command">SET LOCAL</code> is used within a function that has a
+ <code class="literal">SET</code> option for the same variable (see
+ <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>),
+ the effects of the <code class="command">SET LOCAL</code> command disappear at
+ function exit; that is, the value in effect when the function was called is
+ restored anyway. This allows <code class="command">SET LOCAL</code> to be used for
+ dynamic or repeated changes of a parameter within a function, while still
+ having the convenience of using the <code class="literal">SET</code> option to save and
+ restore the caller's value. However, a regular <code class="command">SET</code> command
+ overrides any surrounding function's <code class="literal">SET</code> option; its effects
+ will persist unless rolled back.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In <span class="productname">PostgreSQL</span> versions 8.0 through 8.2,
+ the effects of a <code class="command">SET LOCAL</code> would be canceled by
+ releasing an earlier savepoint, or by successful exit from a
+ <span class="application">PL/pgSQL</span> exception block. This behavior
+ has been changed because it was deemed unintuitive.
+ </p></div></div><div class="refsect1" id="id-1.9.3.174.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SESSION</code></span></dt><dd><p>
+ Specifies that the command takes effect for the current session.
+ (This is the default if neither <code class="literal">SESSION</code> nor
+ <code class="literal">LOCAL</code> appears.)
+ </p></dd><dt><span class="term"><code class="literal">LOCAL</code></span></dt><dd><p>
+ Specifies that the command takes effect for only the current
+ transaction. After <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code>,
+ the session-level setting takes effect again. Issuing this
+ outside of a transaction block emits a warning and otherwise has
+ no effect.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em></span></dt><dd><p>
+ Name of a settable run-time parameter. Available parameters are
+ documented in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> and below.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
+ New value of parameter. Values can be specified as string
+ constants, identifiers, numbers, or comma-separated lists of
+ these, as appropriate for the particular parameter.
+ <code class="literal">DEFAULT</code> can be written to specify
+ resetting the parameter to its default value (that is, whatever
+ value it would have had if no <code class="command">SET</code> had been executed
+ in the current session).
+ </p></dd></dl></div><p>
+ Besides the configuration parameters documented in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>, there are a few that can only be
+ adjusted using the <code class="command">SET</code> command or that have a
+ special syntax:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SCHEMA</code></span></dt><dd><p><code class="literal">SET SCHEMA '<em class="replaceable"><code>value</code></em>'</code> is an alias for
+ <code class="literal">SET search_path TO <em class="replaceable"><code>value</code></em></code>. Only one
+ schema can be specified using this syntax.
+ </p></dd><dt><span class="term"><code class="literal">NAMES</code></span></dt><dd><p><code class="literal">SET NAMES <em class="replaceable"><code>value</code></em></code> is an alias for
+ <code class="literal">SET client_encoding TO <em class="replaceable"><code>value</code></em></code>.
+ </p></dd><dt><span class="term"><code class="literal">SEED</code></span></dt><dd><p>
+ Sets the internal seed for the random number generator (the
+ function <code class="function">random</code>). Allowed values are
+ floating-point numbers between -1 and 1 inclusive.
+ </p><p>
+ The seed can also be set by invoking the function
+ <code class="function">setseed</code>:
+</p><pre class="programlisting">
+SELECT setseed(<em class="replaceable"><code>value</code></em>);
+</pre></dd><dt><span class="term"><code class="literal">TIME ZONE</code></span></dt><dd><p><code class="literal">SET TIME ZONE '<em class="replaceable"><code>value</code></em>'</code> is an alias
+ for <code class="literal">SET timezone TO '<em class="replaceable"><code>value</code></em>'</code>. The
+ syntax <code class="literal">SET TIME ZONE</code> allows special syntax
+ for the time zone specification. Here are examples of valid
+ values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">'PST8PDT'</code></span></dt><dd><p>
+ The time zone for Berkeley, California.
+ </p></dd><dt><span class="term"><code class="literal">'Europe/Rome'</code></span></dt><dd><p>
+ The time zone for Italy.
+ </p></dd><dt><span class="term"><code class="literal">-7</code></span></dt><dd><p>
+ The time zone 7 hours west from UTC (equivalent
+ to PDT). Positive values are east from UTC.
+ </p></dd><dt><span class="term"><code class="literal">INTERVAL '-08:00' HOUR TO MINUTE</code></span></dt><dd><p>
+ The time zone 8 hours west from UTC (equivalent
+ to PST).
+ </p></dd><dt><span class="term"><code class="literal">LOCAL</code><br /></span><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ Set the time zone to your local time zone (that is, the
+ server's default value of <code class="varname">timezone</code>).
+ </p></dd></dl></div><p>
+ </p><p>
+ Timezone settings given as numbers or intervals are internally
+ translated to POSIX timezone syntax. For example, after
+ <code class="literal">SET TIME ZONE -7</code>, <code class="command">SHOW TIME ZONE</code> would
+ report <code class="literal">&lt;-07&gt;+07</code>.
+ </p><p>
+ Time zone abbreviations are not supported by <code class="command">SET</code>;
+ see <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a> for more information
+ about time zones.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.3.174.7"><h2>Notes</h2><p>
+ The function <code class="function">set_config</code> provides equivalent
+ functionality; see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET" title="9.27.1. Configuration Settings Functions">Section 9.27.1</a>.
+ Also, it is possible to UPDATE the
+ <a class="link" href="view-pg-settings.html" title="54.24. pg_settings"><code class="structname">pg_settings</code></a>
+ system view to perform the equivalent of <code class="command">SET</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.174.8"><h2>Examples</h2><p>
+ Set the schema search path:
+</p><pre class="programlisting">
+SET search_path TO my_schema, public;
+</pre><p>
+ </p><p>
+ Set the style of date to traditional
+ <span class="productname">POSTGRES</span> with <span class="quote">“<span class="quote">day before month</span>”</span>
+ input convention:
+</p><pre class="screen">
+SET datestyle TO postgres, dmy;
+</pre><p>
+ </p><p>
+ Set the time zone for Berkeley, California:
+</p><pre class="screen">
+SET TIME ZONE 'PST8PDT';
+</pre><p>
+ </p><p>
+ Set the time zone for Italy:
+</p><pre class="screen">
+SET TIME ZONE 'Europe/Rome';
+</pre></div><div class="refsect1" id="id-1.9.3.174.9"><h2>Compatibility</h2><p>
+ <code class="literal">SET TIME ZONE</code> extends syntax defined in the SQL
+ standard. The standard allows only numeric time zone offsets while
+ <span class="productname">PostgreSQL</span> allows more flexible
+ time-zone specifications. All other <code class="literal">SET</code>
+ features are <span class="productname">PostgreSQL</span> extensions.
+ </p></div><div class="refsect1" id="id-1.9.3.174.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-reset.html" title="RESET"><span class="refentrytitle">RESET</span></a>, <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-selectinto.html" title="SELECT INTO">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set-constraints.html" title="SET CONSTRAINTS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SELECT INTO </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET CONSTRAINTS</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-show.html b/doc/src/sgml/html/sql-show.html
new file mode 100644
index 0000000..f792633
--- /dev/null
+++ b/doc/src/sgml/html/sql-show.html
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SHOW</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set-transaction.html" title="SET TRANSACTION" /><link rel="next" href="sql-start-transaction.html" title="START TRANSACTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SHOW</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set-transaction.html" title="SET TRANSACTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-start-transaction.html" title="START TRANSACTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SHOW"><div class="titlepage"></div><a id="id-1.9.3.179.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SHOW</span></h2><p>SHOW — show the value of a run-time parameter</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SHOW <em class="replaceable"><code>name</code></em>
+SHOW ALL
+</pre></div><div class="refsect1" id="id-1.9.3.179.5"><h2>Description</h2><p>
+ <code class="command">SHOW</code> will display the current setting of
+ run-time parameters. These variables can be set using the
+ <code class="command">SET</code> statement, by editing the
+ <code class="filename">postgresql.conf</code> configuration file, through
+ the <code class="envar">PGOPTIONS</code> environmental variable (when using
+ <span class="application">libpq</span> or a <span class="application">libpq</span>-based
+ application), or through command-line flags when starting the
+ <code class="command">postgres</code> server. See <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.179.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name of a run-time parameter. Available parameters are
+ documented in <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> and on the <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a> reference page. In
+ addition, there are a few parameters that can be shown but not
+ set:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SERVER_VERSION</code></span></dt><dd><p>
+ Shows the server's version number.
+ </p></dd><dt><span class="term"><code class="literal">SERVER_ENCODING</code></span></dt><dd><p>
+ Shows the server-side character set encoding. At present,
+ this parameter can be shown but not set, because the
+ encoding is determined at database creation time.
+ </p></dd><dt><span class="term"><code class="literal">LC_COLLATE</code></span></dt><dd><p>
+ Shows the database's locale setting for collation (text
+ ordering). At present, this parameter can be shown but not
+ set, because the setting is determined at database creation
+ time.
+ </p></dd><dt><span class="term"><code class="literal">LC_CTYPE</code></span></dt><dd><p>
+ Shows the database's locale setting for character
+ classification. At present, this parameter can be shown but
+ not set, because the setting is determined at database creation
+ time.
+ </p></dd><dt><span class="term"><code class="literal">IS_SUPERUSER</code></span></dt><dd><p>
+ True if the current role has superuser privileges.
+ </p></dd></dl></div></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
+ Show the values of all configuration parameters, with descriptions.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.179.7"><h2>Notes</h2><p>
+ The function <code class="function">current_setting</code> produces
+ equivalent output; see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET" title="9.27.1. Configuration Settings Functions">Section 9.27.1</a>.
+ Also, the
+ <a class="link" href="view-pg-settings.html" title="54.24. pg_settings"><code class="structname">pg_settings</code></a>
+ system view produces the same information.
+
+ </p></div><div class="refsect1" id="id-1.9.3.179.8"><h2>Examples</h2><p>
+ Show the current setting of the parameter <code class="varname">DateStyle</code>:
+
+</p><pre class="programlisting">
+SHOW DateStyle;
+ DateStyle
+-----------
+ ISO, MDY
+(1 row)
+</pre><p>
+ </p><p>
+ Show the current setting of the parameter <code class="varname">geqo</code>:
+</p><pre class="programlisting">
+SHOW geqo;
+ geqo
+------
+ on
+(1 row)
+</pre><p>
+ </p><p>
+ Show all settings:
+</p><pre class="programlisting">
+SHOW ALL;
+ name | setting | description
+-------------------------+---------+-------------------------------------------------
+ allow_system_table_mods | off | Allows modifications of the structure of ...
+ .
+ .
+ .
+ xmloption | content | Sets whether XML data in implicit parsing ...
+ zero_damaged_pages | off | Continues processing past damaged page headers.
+(196 rows)
+</pre></div><div class="refsect1" id="id-1.9.3.179.9"><h2>Compatibility</h2><p>
+ The <code class="command">SHOW</code> command is a
+ <span class="productname">PostgreSQL</span> extension.
+ </p></div><div class="refsect1" id="id-1.9.3.179.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>, <a class="xref" href="sql-reset.html" title="RESET"><span class="refentrytitle">RESET</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set-transaction.html" title="SET TRANSACTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-start-transaction.html" title="START TRANSACTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET TRANSACTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> START TRANSACTION</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-start-transaction.html b/doc/src/sgml/html/sql-start-transaction.html
new file mode 100644
index 0000000..955abfe
--- /dev/null
+++ b/doc/src/sgml/html/sql-start-transaction.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>START TRANSACTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-show.html" title="SHOW" /><link rel="next" href="sql-truncate.html" title="TRUNCATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">START TRANSACTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-show.html" title="SHOW">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-truncate.html" title="TRUNCATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-START-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.180.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">START TRANSACTION</span></h2><p>START TRANSACTION — start a transaction block</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+START TRANSACTION [ <em class="replaceable"><code>transaction_mode</code></em> [, ...] ]
+
+<span class="phrase">where <em class="replaceable"><code>transaction_mode</code></em> is one of:</span>
+
+ ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
+ READ WRITE | READ ONLY
+ [ NOT ] DEFERRABLE
+</pre></div><div class="refsect1" id="id-1.9.3.180.5"><h2>Description</h2><p>
+ This command begins a new transaction block. If the isolation level,
+ read/write mode, or deferrable mode is specified, the new transaction has those
+ characteristics, as if <a class="link" href="sql-set-transaction.html" title="SET TRANSACTION"><code class="command">SET TRANSACTION</code></a> was executed. This is the same
+ as the <a class="link" href="sql-begin.html" title="BEGIN"><code class="command">BEGIN</code></a> command.
+ </p></div><div class="refsect1" id="id-1.9.3.180.6"><h2>Parameters</h2><p>
+ Refer to <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> for information on the meaning
+ of the parameters to this statement.
+ </p></div><div class="refsect1" id="id-1.9.3.180.7"><h2>Compatibility</h2><p>
+ In the standard, it is not necessary to issue <code class="command">START TRANSACTION</code>
+ to start a transaction block: any SQL command implicitly begins a block.
+ <span class="productname">PostgreSQL</span>'s behavior can be seen as implicitly
+ issuing a <code class="command">COMMIT</code> after each command that does not
+ follow <code class="command">START TRANSACTION</code> (or <code class="command">BEGIN</code>),
+ and it is therefore often called <span class="quote">“<span class="quote">autocommit</span>”</span>.
+ Other relational database systems might offer an autocommit feature
+ as a convenience.
+ </p><p>
+ The <code class="literal">DEFERRABLE</code>
+ <em class="replaceable"><code>transaction_mode</code></em>
+ is a <span class="productname">PostgreSQL</span> language extension.
+ </p><p>
+ The SQL standard requires commas between successive <em class="replaceable"><code>transaction_modes</code></em>, but for historical
+ reasons <span class="productname">PostgreSQL</span> allows the commas to be
+ omitted.
+ </p><p>
+ See also the compatibility section of <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.180.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-begin.html" title="BEGIN"><span class="refentrytitle">BEGIN</span></a>, <a class="xref" href="sql-commit.html" title="COMMIT"><span class="refentrytitle">COMMIT</span></a>, <a class="xref" href="sql-rollback.html" title="ROLLBACK"><span class="refentrytitle">ROLLBACK</span></a>, <a class="xref" href="sql-savepoint.html" title="SAVEPOINT"><span class="refentrytitle">SAVEPOINT</span></a>, <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-show.html" title="SHOW">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-truncate.html" title="TRUNCATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SHOW </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> TRUNCATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-syntax-calling-funcs.html b/doc/src/sgml/html/sql-syntax-calling-funcs.html
new file mode 100644
index 0000000..0280dd2
--- /dev/null
+++ b/doc/src/sgml/html/sql-syntax-calling-funcs.html
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4.3. Calling Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-expressions.html" title="4.2. Value Expressions" /><link rel="next" href="ddl.html" title="Chapter 5. Data Definition" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">4.3. Calling Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-expressions.html" title="4.2. Value Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><th width="60%" align="center">Chapter 4. SQL Syntax</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl.html" title="Chapter 5. Data Definition">Next</a></td></tr></table><hr /></div><div class="sect1" id="SQL-SYNTAX-CALLING-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">4.3. Calling Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-POSITIONAL">4.3.1. Using Positional Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED">4.3.2. Using Named Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-MIXED">4.3.3. Using Mixed Notation</a></span></dt></dl></div><a id="id-1.5.3.7.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> allows functions that have named
+ parameters to be called using either <em class="firstterm">positional</em> or
+ <em class="firstterm">named</em> notation. Named notation is especially
+ useful for functions that have a large number of parameters, since it
+ makes the associations between parameters and actual arguments more
+ explicit and reliable.
+ In positional notation, a function call is written with
+ its argument values in the same order as they are defined in the function
+ declaration. In named notation, the arguments are matched to the
+ function parameters by name and can be written in any order.
+ For each notation, also consider the effect of function argument types,
+ documented in <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>.
+ </p><p>
+ In either notation, parameters that have default values given in the
+ function declaration need not be written in the call at all. But this
+ is particularly useful in named notation, since any combination of
+ parameters can be omitted; while in positional notation parameters can
+ only be omitted from right to left.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also supports
+ <em class="firstterm">mixed</em> notation, which combines positional and
+ named notation. In this case, positional parameters are written first
+ and named parameters appear after them.
+ </p><p>
+ The following examples will illustrate the usage of all three
+ notations, using the following function definition:
+</p><pre class="programlisting">
+CREATE FUNCTION concat_lower_or_upper(a text, b text, uppercase boolean DEFAULT false)
+RETURNS text
+AS
+$$
+ SELECT CASE
+ WHEN $3 THEN UPPER($1 || ' ' || $2)
+ ELSE LOWER($1 || ' ' || $2)
+ END;
+$$
+LANGUAGE SQL IMMUTABLE STRICT;
+</pre><p>
+ Function <code class="function">concat_lower_or_upper</code> has two mandatory
+ parameters, <code class="literal">a</code> and <code class="literal">b</code>. Additionally
+ there is one optional parameter <code class="literal">uppercase</code> which defaults
+ to <code class="literal">false</code>. The <code class="literal">a</code> and
+ <code class="literal">b</code> inputs will be concatenated, and forced to either
+ upper or lower case depending on the <code class="literal">uppercase</code>
+ parameter. The remaining details of this function
+ definition are not important here (see <a class="xref" href="extend.html" title="Chapter 38. Extending SQL">Chapter 38</a> for
+ more information).
+ </p><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-POSITIONAL"><div class="titlepage"><div><div><h3 class="title">4.3.1. Using Positional Notation</h3></div></div></div><a id="id-1.5.3.7.7.2" class="indexterm"></a><p>
+ Positional notation is the traditional mechanism for passing arguments
+ to functions in <span class="productname">PostgreSQL</span>. An example is:
+</p><pre class="screen">
+SELECT concat_lower_or_upper('Hello', 'World', true);
+ concat_lower_or_upper
+-----------------------
+ HELLO WORLD
+(1 row)
+</pre><p>
+ All arguments are specified in order. The result is upper case since
+ <code class="literal">uppercase</code> is specified as <code class="literal">true</code>.
+ Another example is:
+</p><pre class="screen">
+SELECT concat_lower_or_upper('Hello', 'World');
+ concat_lower_or_upper
+-----------------------
+ hello world
+(1 row)
+</pre><p>
+ Here, the <code class="literal">uppercase</code> parameter is omitted, so it
+ receives its default value of <code class="literal">false</code>, resulting in
+ lower case output. In positional notation, arguments can be omitted
+ from right to left so long as they have defaults.
+ </p></div><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-NAMED"><div class="titlepage"><div><div><h3 class="title">4.3.2. Using Named Notation</h3></div></div></div><a id="id-1.5.3.7.8.2" class="indexterm"></a><p>
+ In named notation, each argument's name is specified using
+ <code class="literal">=&gt;</code> to separate it from the argument expression.
+ For example:
+</p><pre class="screen">
+SELECT concat_lower_or_upper(a =&gt; 'Hello', b =&gt; 'World');
+ concat_lower_or_upper
+-----------------------
+ hello world
+(1 row)
+</pre><p>
+ Again, the argument <code class="literal">uppercase</code> was omitted
+ so it is set to <code class="literal">false</code> implicitly. One advantage of
+ using named notation is that the arguments may be specified in any
+ order, for example:
+</p><pre class="screen">
+SELECT concat_lower_or_upper(a =&gt; 'Hello', b =&gt; 'World', uppercase =&gt; true);
+ concat_lower_or_upper
+-----------------------
+ HELLO WORLD
+(1 row)
+
+SELECT concat_lower_or_upper(a =&gt; 'Hello', uppercase =&gt; true, b =&gt; 'World');
+ concat_lower_or_upper
+-----------------------
+ HELLO WORLD
+(1 row)
+</pre><p>
+ </p><p>
+ An older syntax based on ":=" is supported for backward compatibility:
+</p><pre class="screen">
+SELECT concat_lower_or_upper(a := 'Hello', uppercase := true, b := 'World');
+ concat_lower_or_upper
+-----------------------
+ HELLO WORLD
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-MIXED"><div class="titlepage"><div><div><h3 class="title">4.3.3. Using Mixed Notation</h3></div></div></div><a id="id-1.5.3.7.9.2" class="indexterm"></a><p>
+ The mixed notation combines positional and named notation. However, as
+ already mentioned, named arguments cannot precede positional arguments.
+ For example:
+</p><pre class="screen">
+SELECT concat_lower_or_upper('Hello', 'World', uppercase =&gt; true);
+ concat_lower_or_upper
+-----------------------
+ HELLO WORLD
+(1 row)
+</pre><p>
+ In the above query, the arguments <code class="literal">a</code> and
+ <code class="literal">b</code> are specified positionally, while
+ <code class="literal">uppercase</code> is specified by name. In this example,
+ that adds little except documentation. With a more complex function
+ having numerous parameters that have default values, named or mixed
+ notation can save a great deal of writing and reduce chances for error.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Named and mixed call notations currently cannot be used when calling an
+ aggregate function (but they do work when an aggregate function is used
+ as a window function).
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-expressions.html" title="4.2. Value Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl.html" title="Chapter 5. Data Definition">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. Value Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Data Definition</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-syntax-lexical.html b/doc/src/sgml/html/sql-syntax-lexical.html
new file mode 100644
index 0000000..18b47df
--- /dev/null
+++ b/doc/src/sgml/html/sql-syntax-lexical.html
@@ -0,0 +1,647 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4.1. Lexical Structure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-syntax.html" title="Chapter 4. SQL Syntax" /><link rel="next" href="sql-expressions.html" title="4.2. Value Expressions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">4.1. Lexical Structure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><th width="60%" align="center">Chapter 4. SQL Syntax</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-expressions.html" title="4.2. Value Expressions">Next</a></td></tr></table><hr /></div><div class="sect1" id="SQL-SYNTAX-LEXICAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">4.1. Lexical Structure</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">4.1.1. Identifiers and Key Words</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS">4.1.2. Constants</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-OPERATORS">4.1.3. Operators</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-SPECIAL-CHARS">4.1.4. Special Characters</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS">4.1.5. Comments</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-PRECEDENCE">4.1.6. Operator Precedence</a></span></dt></dl></div><a id="id-1.5.3.5.2" class="indexterm"></a><p>
+ SQL input consists of a sequence of
+ <em class="firstterm">commands</em>. A command is composed of a
+ sequence of <em class="firstterm">tokens</em>, terminated by a
+ semicolon (<span class="quote">“<span class="quote">;</span>”</span>). The end of the input stream also
+ terminates a command. Which tokens are valid depends on the syntax
+ of the particular command.
+ </p><p>
+ A token can be a <em class="firstterm">key word</em>, an
+ <em class="firstterm">identifier</em>, a <em class="firstterm">quoted
+ identifier</em>, a <em class="firstterm">literal</em> (or
+ constant), or a special character symbol. Tokens are normally
+ separated by whitespace (space, tab, newline), but need not be if
+ there is no ambiguity (which is generally only the case if a
+ special character is adjacent to some other token type).
+ </p><p>
+ For example, the following is (syntactically) valid SQL input:
+</p><pre class="programlisting">
+SELECT * FROM MY_TABLE;
+UPDATE MY_TABLE SET A = 5;
+INSERT INTO MY_TABLE VALUES (3, 'hi there');
+</pre><p>
+ This is a sequence of three commands, one per line (although this
+ is not required; more than one command can be on a line, and
+ commands can usefully be split across lines).
+ </p><p>
+ Additionally, <em class="firstterm">comments</em> can occur in SQL
+ input. They are not tokens, they are effectively equivalent to
+ whitespace.
+ </p><p>
+ The SQL syntax is not very consistent regarding what tokens
+ identify commands and which are operands or parameters. The first
+ few tokens are generally the command name, so in the above example
+ we would usually speak of a <span class="quote">“<span class="quote">SELECT</span>”</span>, an
+ <span class="quote">“<span class="quote">UPDATE</span>”</span>, and an <span class="quote">“<span class="quote">INSERT</span>”</span> command. But
+ for instance the <code class="command">UPDATE</code> command always requires
+ a <code class="token">SET</code> token to appear in a certain position, and
+ this particular variation of <code class="command">INSERT</code> also
+ requires a <code class="token">VALUES</code> in order to be complete. The
+ precise syntax rules for each command are described in <a class="xref" href="reference.html" title="Part VI. Reference">Part VI</a>.
+ </p><div class="sect2" id="SQL-SYNTAX-IDENTIFIERS"><div class="titlepage"><div><div><h3 class="title">4.1.1. Identifiers and Key Words</h3></div></div></div><a id="id-1.5.3.5.8.2" class="indexterm"></a><a id="id-1.5.3.5.8.3" class="indexterm"></a><a id="id-1.5.3.5.8.4" class="indexterm"></a><p>
+ Tokens such as <code class="token">SELECT</code>, <code class="token">UPDATE</code>, or
+ <code class="token">VALUES</code> in the example above are examples of
+ <em class="firstterm">key words</em>, that is, words that have a fixed
+ meaning in the SQL language. The tokens <code class="token">MY_TABLE</code>
+ and <code class="token">A</code> are examples of
+ <em class="firstterm">identifiers</em>. They identify names of
+ tables, columns, or other database objects, depending on the
+ command they are used in. Therefore they are sometimes simply
+ called <span class="quote">“<span class="quote">names</span>”</span>. Key words and identifiers have the
+ same lexical structure, meaning that one cannot know whether a
+ token is an identifier or a key word without knowing the language.
+ A complete list of key words can be found in <a class="xref" href="sql-keywords-appendix.html" title="Appendix C. SQL Key Words">Appendix C</a>.
+ </p><p>
+ SQL identifiers and key words must begin with a letter
+ (<code class="literal">a</code>-<code class="literal">z</code>, but also letters with
+ diacritical marks and non-Latin letters) or an underscore
+ (<code class="literal">_</code>). Subsequent characters in an identifier or
+ key word can be letters, underscores, digits
+ (<code class="literal">0</code>-<code class="literal">9</code>), or dollar signs
+ (<code class="literal">$</code>). Note that dollar signs are not allowed in identifiers
+ according to the letter of the SQL standard, so their use might render
+ applications less portable.
+ The SQL standard will not define a key word that contains
+ digits or starts or ends with an underscore, so identifiers of this
+ form are safe against possible conflict with future extensions of the
+ standard.
+ </p><p>
+ <a id="id-1.5.3.5.8.7.1" class="indexterm"></a>
+ The system uses no more than <code class="symbol">NAMEDATALEN</code>-1
+ bytes of an identifier; longer names can be written in
+ commands, but they will be truncated. By default,
+ <code class="symbol">NAMEDATALEN</code> is 64 so the maximum identifier
+ length is 63 bytes. If this limit is problematic, it can be raised by
+ changing the <code class="symbol">NAMEDATALEN</code> constant in
+ <code class="filename">src/include/pg_config_manual.h</code>.
+ </p><p>
+ <a id="id-1.5.3.5.8.8.1" class="indexterm"></a>
+ Key words and unquoted identifiers are case insensitive. Therefore:
+</p><pre class="programlisting">
+UPDATE MY_TABLE SET A = 5;
+</pre><p>
+ can equivalently be written as:
+</p><pre class="programlisting">
+uPDaTE my_TabLE SeT a = 5;
+</pre><p>
+ A convention often used is to write key words in upper
+ case and names in lower case, e.g.:
+</p><pre class="programlisting">
+UPDATE my_table SET a = 5;
+</pre><p>
+ </p><p>
+ <a id="id-1.5.3.5.8.9.1" class="indexterm"></a>
+ There is a second kind of identifier: the <em class="firstterm">delimited
+ identifier</em> or <em class="firstterm">quoted
+ identifier</em>. It is formed by enclosing an arbitrary
+ sequence of characters in double-quotes
+ (<code class="literal">"</code>). A delimited
+ identifier is always an identifier, never a key word. So
+ <code class="literal">"select"</code> could be used to refer to a column or
+ table named <span class="quote">“<span class="quote">select</span>”</span>, whereas an unquoted
+ <code class="literal">select</code> would be taken as a key word and
+ would therefore provoke a parse error when used where a table or
+ column name is expected. The example can be written with quoted
+ identifiers like this:
+</p><pre class="programlisting">
+UPDATE "my_table" SET "a" = 5;
+</pre><p>
+ </p><p>
+ Quoted identifiers can contain any character, except the character
+ with code zero. (To include a double quote, write two double quotes.)
+ This allows constructing table or column names that would
+ otherwise not be possible, such as ones containing spaces or
+ ampersands. The length limitation still applies.
+ </p><p>
+ Quoting an identifier also makes it case-sensitive, whereas
+ unquoted names are always folded to lower case. For example, the
+ identifiers <code class="literal">FOO</code>, <code class="literal">foo</code>, and
+ <code class="literal">"foo"</code> are considered the same by
+ <span class="productname">PostgreSQL</span>, but
+ <code class="literal">"Foo"</code> and <code class="literal">"FOO"</code> are
+ different from these three and each other. (The folding of
+ unquoted names to lower case in <span class="productname">PostgreSQL</span> is
+ incompatible with the SQL standard, which says that unquoted names
+ should be folded to upper case. Thus, <code class="literal">foo</code>
+ should be equivalent to <code class="literal">"FOO"</code> not
+ <code class="literal">"foo"</code> according to the standard. If you want
+ to write portable applications you are advised to always quote a
+ particular name or never quote it.)
+ </p><a id="id-1.5.3.5.8.12" class="indexterm"></a><p>
+ A variant of quoted
+ identifiers allows including escaped Unicode characters identified
+ by their code points. This variant starts
+ with <code class="literal">U&amp;</code> (upper or lower case U followed by
+ ampersand) immediately before the opening double quote, without
+ any spaces in between, for example <code class="literal">U&amp;"foo"</code>.
+ (Note that this creates an ambiguity with the
+ operator <code class="literal">&amp;</code>. Use spaces around the operator to
+ avoid this problem.) Inside the quotes, Unicode characters can be
+ specified in escaped form by writing a backslash followed by the
+ four-digit hexadecimal code point number or alternatively a
+ backslash followed by a plus sign followed by a six-digit
+ hexadecimal code point number. For example, the
+ identifier <code class="literal">"data"</code> could be written as
+</p><pre class="programlisting">
+U&amp;"d\0061t\+000061"
+</pre><p>
+ The following less trivial example writes the Russian
+ word <span class="quote">“<span class="quote">slon</span>”</span> (elephant) in Cyrillic letters:
+</p><pre class="programlisting">
+U&amp;"\0441\043B\043E\043D"
+</pre><p>
+ </p><p>
+ If a different escape character than backslash is desired, it can
+ be specified using
+ the <code class="literal">UESCAPE</code><a id="id-1.5.3.5.8.14.2" class="indexterm"></a>
+ clause after the string, for example:
+</p><pre class="programlisting">
+U&amp;"d!0061t!+000061" UESCAPE '!'
+</pre><p>
+ The escape character can be any single character other than a
+ hexadecimal digit, the plus sign, a single quote, a double quote,
+ or a whitespace character. Note that the escape character is
+ written in single quotes, not double quotes,
+ after <code class="literal">UESCAPE</code>.
+ </p><p>
+ To include the escape character in the identifier literally, write
+ it twice.
+ </p><p>
+ Either the 4-digit or the 6-digit escape form can be used to
+ specify UTF-16 surrogate pairs to compose characters with code
+ points larger than U+FFFF, although the availability of the
+ 6-digit form technically makes this unnecessary. (Surrogate
+ pairs are not stored directly, but are combined into a single
+ code point.)
+ </p><p>
+ If the server encoding is not UTF-8, the Unicode code point identified
+ by one of these escape sequences is converted to the actual server
+ encoding; an error is reported if that's not possible.
+ </p></div><div class="sect2" id="SQL-SYNTAX-CONSTANTS"><div class="titlepage"><div><div><h3 class="title">4.1.2. Constants</h3></div></div></div><a id="id-1.5.3.5.9.2" class="indexterm"></a><p>
+ There are three kinds of <em class="firstterm">implicitly-typed
+ constants</em> in <span class="productname">PostgreSQL</span>:
+ strings, bit strings, and numbers.
+ Constants can also be specified with explicit types, which can
+ enable more accurate representation and more efficient handling by
+ the system. These alternatives are discussed in the following
+ subsections.
+ </p><div class="sect3" id="SQL-SYNTAX-STRINGS"><div class="titlepage"><div><div><h4 class="title">4.1.2.1. String Constants</h4></div></div></div><a id="id-1.5.3.5.9.4.2" class="indexterm"></a><p>
+ <a id="id-1.5.3.5.9.4.3.1" class="indexterm"></a>
+ A string constant in SQL is an arbitrary sequence of characters
+ bounded by single quotes (<code class="literal">'</code>), for example
+ <code class="literal">'This is a string'</code>. To include
+ a single-quote character within a string constant,
+ write two adjacent single quotes, e.g.,
+ <code class="literal">'Dianne''s horse'</code>.
+ Note that this is <span class="emphasis"><em>not</em></span> the same as a double-quote
+ character (<code class="literal">"</code>).
+ </p><p>
+ Two string constants that are only separated by whitespace
+ <span class="emphasis"><em>with at least one newline</em></span> are concatenated
+ and effectively treated as if the string had been written as one
+ constant. For example:
+</p><pre class="programlisting">
+SELECT 'foo'
+'bar';
+</pre><p>
+ is equivalent to:
+</p><pre class="programlisting">
+SELECT 'foobar';
+</pre><p>
+ but:
+</p><pre class="programlisting">
+SELECT 'foo' 'bar';
+</pre><p>
+ is not valid syntax. (This slightly bizarre behavior is specified
+ by <acronym class="acronym">SQL</acronym>; <span class="productname">PostgreSQL</span> is
+ following the standard.)
+ </p></div><div class="sect3" id="SQL-SYNTAX-STRINGS-ESCAPE"><div class="titlepage"><div><div><h4 class="title">4.1.2.2. String Constants with C-Style Escapes</h4></div></div></div><a id="id-1.5.3.5.9.5.2" class="indexterm"></a><a id="id-1.5.3.5.9.5.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> also accepts <span class="quote">“<span class="quote">escape</span>”</span>
+ string constants, which are an extension to the SQL standard.
+ An escape string constant is specified by writing the letter
+ <code class="literal">E</code> (upper or lower case) just before the opening single
+ quote, e.g., <code class="literal">E'foo'</code>. (When continuing an escape string
+ constant across lines, write <code class="literal">E</code> only before the first opening
+ quote.)
+ Within an escape string, a backslash character (<code class="literal">\</code>) begins a
+ C-like <em class="firstterm">backslash escape</em> sequence, in which the combination
+ of backslash and following character(s) represent a special byte
+ value, as shown in <a class="xref" href="sql-syntax-lexical.html#SQL-BACKSLASH-TABLE" title="Table 4.1. Backslash Escape Sequences">Table 4.1</a>.
+ </p><div class="table" id="SQL-BACKSLASH-TABLE"><p class="title"><strong>Table 4.1. Backslash Escape Sequences</strong></p><div class="table-contents"><table class="table" summary="Backslash Escape Sequences" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Backslash Escape Sequence</th><th>Interpretation</th></tr></thead><tbody><tr><td><code class="literal">\b</code></td><td>backspace</td></tr><tr><td><code class="literal">\f</code></td><td>form feed</td></tr><tr><td><code class="literal">\n</code></td><td>newline</td></tr><tr><td><code class="literal">\r</code></td><td>carriage return</td></tr><tr><td><code class="literal">\t</code></td><td>tab</td></tr><tr><td>
+ <code class="literal">\<em class="replaceable"><code>o</code></em></code>,
+ <code class="literal">\<em class="replaceable"><code>oo</code></em></code>,
+ <code class="literal">\<em class="replaceable"><code>ooo</code></em></code>
+ (<em class="replaceable"><code>o</code></em> = 0–7)
+ </td><td>octal byte value</td></tr><tr><td>
+ <code class="literal">\x<em class="replaceable"><code>h</code></em></code>,
+ <code class="literal">\x<em class="replaceable"><code>hh</code></em></code>
+ (<em class="replaceable"><code>h</code></em> = 0–9, A–F)
+ </td><td>hexadecimal byte value</td></tr><tr><td>
+ <code class="literal">\u<em class="replaceable"><code>xxxx</code></em></code>,
+ <code class="literal">\U<em class="replaceable"><code>xxxxxxxx</code></em></code>
+ (<em class="replaceable"><code>x</code></em> = 0–9, A–F)
+ </td><td>16 or 32-bit hexadecimal Unicode character value</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Any other
+ character following a backslash is taken literally. Thus, to
+ include a backslash character, write two backslashes (<code class="literal">\\</code>).
+ Also, a single quote can be included in an escape string by writing
+ <code class="literal">\'</code>, in addition to the normal way of <code class="literal">''</code>.
+ </p><p>
+ It is your responsibility that the byte sequences you create,
+ especially when using the octal or hexadecimal escapes, compose
+ valid characters in the server character set encoding.
+ A useful alternative is to use Unicode escapes or the
+ alternative Unicode escape syntax, explained
+ in <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-UESCAPE" title="4.1.2.3. String Constants with Unicode Escapes">Section 4.1.2.3</a>; then the server
+ will check that the character conversion is possible.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ If the configuration parameter
+ <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> is <code class="literal">off</code>,
+ then <span class="productname">PostgreSQL</span> recognizes backslash escapes
+ in both regular and escape string constants. However, as of
+ <span class="productname">PostgreSQL</span> 9.1, the default is <code class="literal">on</code>, meaning
+ that backslash escapes are recognized only in escape string constants.
+ This behavior is more standards-compliant, but might break applications
+ which rely on the historical behavior, where backslash escapes
+ were always recognized. As a workaround, you can set this parameter
+ to <code class="literal">off</code>, but it is better to migrate away from using backslash
+ escapes. If you need to use a backslash escape to represent a special
+ character, write the string constant with an <code class="literal">E</code>.
+ </p><p>
+ In addition to <code class="varname">standard_conforming_strings</code>, the configuration
+ parameters <a class="xref" href="runtime-config-compatible.html#GUC-ESCAPE-STRING-WARNING">escape_string_warning</a> and
+ <a class="xref" href="runtime-config-compatible.html#GUC-BACKSLASH-QUOTE">backslash_quote</a> govern treatment of backslashes
+ in string constants.
+ </p></div><p>
+ The character with the code zero cannot be in a string constant.
+ </p></div><div class="sect3" id="SQL-SYNTAX-STRINGS-UESCAPE"><div class="titlepage"><div><div><h4 class="title">4.1.2.3. String Constants with Unicode Escapes</h4></div></div></div><a id="id-1.5.3.5.9.6.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> also supports another type
+ of escape syntax for strings that allows specifying arbitrary
+ Unicode characters by code point. A Unicode escape string
+ constant starts with <code class="literal">U&amp;</code> (upper or lower case
+ letter U followed by ampersand) immediately before the opening
+ quote, without any spaces in between, for
+ example <code class="literal">U&amp;'foo'</code>. (Note that this creates an
+ ambiguity with the operator <code class="literal">&amp;</code>. Use spaces
+ around the operator to avoid this problem.) Inside the quotes,
+ Unicode characters can be specified in escaped form by writing a
+ backslash followed by the four-digit hexadecimal code point
+ number or alternatively a backslash followed by a plus sign
+ followed by a six-digit hexadecimal code point number. For
+ example, the string <code class="literal">'data'</code> could be written as
+</p><pre class="programlisting">
+U&amp;'d\0061t\+000061'
+</pre><p>
+ The following less trivial example writes the Russian
+ word <span class="quote">“<span class="quote">slon</span>”</span> (elephant) in Cyrillic letters:
+</p><pre class="programlisting">
+U&amp;'\0441\043B\043E\043D'
+</pre><p>
+ </p><p>
+ If a different escape character than backslash is desired, it can
+ be specified using
+ the <code class="literal">UESCAPE</code><a id="id-1.5.3.5.9.6.4.2" class="indexterm"></a>
+ clause after the string, for example:
+</p><pre class="programlisting">
+U&amp;'d!0061t!+000061' UESCAPE '!'
+</pre><p>
+ The escape character can be any single character other than a
+ hexadecimal digit, the plus sign, a single quote, a double quote,
+ or a whitespace character.
+ </p><p>
+ To include the escape character in the string literally, write
+ it twice.
+ </p><p>
+ Either the 4-digit or the 6-digit escape form can be used to
+ specify UTF-16 surrogate pairs to compose characters with code
+ points larger than U+FFFF, although the availability of the
+ 6-digit form technically makes this unnecessary. (Surrogate
+ pairs are not stored directly, but are combined into a single
+ code point.)
+ </p><p>
+ If the server encoding is not UTF-8, the Unicode code point identified
+ by one of these escape sequences is converted to the actual server
+ encoding; an error is reported if that's not possible.
+ </p><p>
+ Also, the Unicode escape syntax for string constants only works
+ when the configuration
+ parameter <a class="xref" href="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS">standard_conforming_strings</a> is
+ turned on. This is because otherwise this syntax could confuse
+ clients that parse the SQL statements to the point that it could
+ lead to SQL injections and similar security issues. If the
+ parameter is set to off, this syntax will be rejected with an
+ error message.
+ </p></div><div class="sect3" id="SQL-SYNTAX-DOLLAR-QUOTING"><div class="titlepage"><div><div><h4 class="title">4.1.2.4. Dollar-Quoted String Constants</h4></div></div></div><a id="id-1.5.3.5.9.7.2" class="indexterm"></a><p>
+ While the standard syntax for specifying string constants is usually
+ convenient, it can be difficult to understand when the desired string
+ contains many single quotes, since each of those must
+ be doubled. To allow more readable queries in such situations,
+ <span class="productname">PostgreSQL</span> provides another way, called
+ <span class="quote">“<span class="quote">dollar quoting</span>”</span>, to write string constants.
+ A dollar-quoted string constant
+ consists of a dollar sign (<code class="literal">$</code>), an optional
+ <span class="quote">“<span class="quote">tag</span>”</span> of zero or more characters, another dollar
+ sign, an arbitrary sequence of characters that makes up the
+ string content, a dollar sign, the same tag that began this
+ dollar quote, and a dollar sign. For example, here are two
+ different ways to specify the string <span class="quote">“<span class="quote">Dianne's horse</span>”</span>
+ using dollar quoting:
+</p><pre class="programlisting">
+$$Dianne's horse$$
+$SomeTag$Dianne's horse$SomeTag$
+</pre><p>
+ Notice that inside the dollar-quoted string, single quotes can be
+ used without needing to be escaped. Indeed, no characters inside
+ a dollar-quoted string are ever escaped: the string content is always
+ written literally. Backslashes are not special, and neither are
+ dollar signs, unless they are part of a sequence matching the opening
+ tag.
+ </p><p>
+ It is possible to nest dollar-quoted string constants by choosing
+ different tags at each nesting level. This is most commonly used in
+ writing function definitions. For example:
+</p><pre class="programlisting">
+$function$
+BEGIN
+ RETURN ($1 ~ $q$[\t\r\n\v\\]$q$);
+END;
+$function$
+</pre><p>
+ Here, the sequence <code class="literal">$q$[\t\r\n\v\\]$q$</code> represents a
+ dollar-quoted literal string <code class="literal">[\t\r\n\v\\]</code>, which will
+ be recognized when the function body is executed by
+ <span class="productname">PostgreSQL</span>. But since the sequence does not match
+ the outer dollar quoting delimiter <code class="literal">$function$</code>, it is
+ just some more characters within the constant so far as the outer
+ string is concerned.
+ </p><p>
+ The tag, if any, of a dollar-quoted string follows the same rules
+ as an unquoted identifier, except that it cannot contain a dollar sign.
+ Tags are case sensitive, so <code class="literal">$tag$String content$tag$</code>
+ is correct, but <code class="literal">$TAG$String content$tag$</code> is not.
+ </p><p>
+ A dollar-quoted string that follows a keyword or identifier must
+ be separated from it by whitespace; otherwise the dollar quoting
+ delimiter would be taken as part of the preceding identifier.
+ </p><p>
+ Dollar quoting is not part of the SQL standard, but it is often a more
+ convenient way to write complicated string literals than the
+ standard-compliant single quote syntax. It is particularly useful when
+ representing string constants inside other constants, as is often needed
+ in procedural function definitions. With single-quote syntax, each
+ backslash in the above example would have to be written as four
+ backslashes, which would be reduced to two backslashes in parsing the
+ original string constant, and then to one when the inner string constant
+ is re-parsed during function execution.
+ </p></div><div class="sect3" id="SQL-SYNTAX-BIT-STRINGS"><div class="titlepage"><div><div><h4 class="title">4.1.2.5. Bit-String Constants</h4></div></div></div><a id="id-1.5.3.5.9.8.2" class="indexterm"></a><p>
+ Bit-string constants look like regular string constants with a
+ <code class="literal">B</code> (upper or lower case) immediately before the
+ opening quote (no intervening whitespace), e.g.,
+ <code class="literal">B'1001'</code>. The only characters allowed within
+ bit-string constants are <code class="literal">0</code> and
+ <code class="literal">1</code>.
+ </p><p>
+ Alternatively, bit-string constants can be specified in hexadecimal
+ notation, using a leading <code class="literal">X</code> (upper or lower case),
+ e.g., <code class="literal">X'1FF'</code>. This notation is equivalent to
+ a bit-string constant with four binary digits for each hexadecimal digit.
+ </p><p>
+ Both forms of bit-string constant can be continued
+ across lines in the same way as regular string constants.
+ Dollar quoting cannot be used in a bit-string constant.
+ </p></div><div class="sect3" id="SQL-SYNTAX-CONSTANTS-NUMERIC"><div class="titlepage"><div><div><h4 class="title">4.1.2.6. Numeric Constants</h4></div></div></div><a id="id-1.5.3.5.9.9.2" class="indexterm"></a><p>
+ Numeric constants are accepted in these general forms:
+</p><pre class="synopsis">
+<em class="replaceable"><code>digits</code></em>
+<em class="replaceable"><code>digits</code></em>.[<span class="optional"><em class="replaceable"><code>digits</code></em></span>][<span class="optional">e[<span class="optional">+-</span>]<em class="replaceable"><code>digits</code></em></span>]
+[<span class="optional"><em class="replaceable"><code>digits</code></em></span>].<em class="replaceable"><code>digits</code></em>[<span class="optional">e[<span class="optional">+-</span>]<em class="replaceable"><code>digits</code></em></span>]
+<em class="replaceable"><code>digits</code></em>e[<span class="optional">+-</span>]<em class="replaceable"><code>digits</code></em>
+</pre><p>
+ where <em class="replaceable"><code>digits</code></em> is one or more decimal
+ digits (0 through 9). At least one digit must be before or after the
+ decimal point, if one is used. At least one digit must follow the
+ exponent marker (<code class="literal">e</code>), if one is present.
+ There cannot be any spaces or other characters embedded in the
+ constant. Note that any leading plus or minus sign is not actually
+ considered part of the constant; it is an operator applied to the
+ constant.
+ </p><p>
+ These are some examples of valid numeric constants:
+</p><div class="literallayout"><p><br />
+42<br />
+3.5<br />
+4.<br />
+.001<br />
+5e2<br />
+1.925e-3<br />
+</p></div><p>
+ </p><p>
+ <a id="id-1.5.3.5.9.9.5.1" class="indexterm"></a>
+ <a id="id-1.5.3.5.9.9.5.2" class="indexterm"></a>
+ <a id="id-1.5.3.5.9.9.5.3" class="indexterm"></a>
+ A numeric constant that contains neither a decimal point nor an
+ exponent is initially presumed to be type <code class="type">integer</code> if its
+ value fits in type <code class="type">integer</code> (32 bits); otherwise it is
+ presumed to be type <code class="type">bigint</code> if its
+ value fits in type <code class="type">bigint</code> (64 bits); otherwise it is
+ taken to be type <code class="type">numeric</code>. Constants that contain decimal
+ points and/or exponents are always initially presumed to be type
+ <code class="type">numeric</code>.
+ </p><p>
+ The initially assigned data type of a numeric constant is just a
+ starting point for the type resolution algorithms. In most cases
+ the constant will be automatically coerced to the most
+ appropriate type depending on context. When necessary, you can
+ force a numeric value to be interpreted as a specific data type
+ by casting it.<a id="id-1.5.3.5.9.9.6.1" class="indexterm"></a>
+ For example, you can force a numeric value to be treated as type
+ <code class="type">real</code> (<code class="type">float4</code>) by writing:
+
+</p><pre class="programlisting">
+REAL '1.23' -- string style
+1.23::REAL -- PostgreSQL (historical) style
+</pre><p>
+
+ These are actually just special cases of the general casting
+ notations discussed next.
+ </p></div><div class="sect3" id="SQL-SYNTAX-CONSTANTS-GENERIC"><div class="titlepage"><div><div><h4 class="title">4.1.2.7. Constants of Other Types</h4></div></div></div><a id="id-1.5.3.5.9.10.2" class="indexterm"></a><p>
+ A constant of an <span class="emphasis"><em>arbitrary</em></span> type can be
+ entered using any one of the following notations:
+</p><pre class="synopsis">
+<em class="replaceable"><code>type</code></em> '<em class="replaceable"><code>string</code></em>'
+'<em class="replaceable"><code>string</code></em>'::<em class="replaceable"><code>type</code></em>
+CAST ( '<em class="replaceable"><code>string</code></em>' AS <em class="replaceable"><code>type</code></em> )
+</pre><p>
+ The string constant's text is passed to the input conversion
+ routine for the type called <em class="replaceable"><code>type</code></em>. The
+ result is a constant of the indicated type. The explicit type
+ cast can be omitted if there is no ambiguity as to the type the
+ constant must be (for example, when it is assigned directly to a
+ table column), in which case it is automatically coerced.
+ </p><p>
+ The string constant can be written using either regular SQL
+ notation or dollar-quoting.
+ </p><p>
+ It is also possible to specify a type coercion using a function-like
+ syntax:
+</p><pre class="synopsis">
+<em class="replaceable"><code>typename</code></em> ( '<em class="replaceable"><code>string</code></em>' )
+</pre><p>
+ but not all type names can be used in this way; see <a class="xref" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS" title="4.2.9. Type Casts">Section 4.2.9</a> for details.
+ </p><p>
+ The <code class="literal">::</code>, <code class="literal">CAST()</code>, and
+ function-call syntaxes can also be used to specify run-time type
+ conversions of arbitrary expressions, as discussed in <a class="xref" href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS" title="4.2.9. Type Casts">Section 4.2.9</a>. To avoid syntactic ambiguity, the
+ <code class="literal"><em class="replaceable"><code>type</code></em> '<em class="replaceable"><code>string</code></em>'</code>
+ syntax can only be used to specify the type of a simple literal constant.
+ Another restriction on the
+ <code class="literal"><em class="replaceable"><code>type</code></em> '<em class="replaceable"><code>string</code></em>'</code>
+ syntax is that it does not work for array types; use <code class="literal">::</code>
+ or <code class="literal">CAST()</code> to specify the type of an array constant.
+ </p><p>
+ The <code class="literal">CAST()</code> syntax conforms to SQL. The
+ <code class="literal"><em class="replaceable"><code>type</code></em> '<em class="replaceable"><code>string</code></em>'</code>
+ syntax is a generalization of the standard: SQL specifies this syntax only
+ for a few data types, but <span class="productname">PostgreSQL</span> allows it
+ for all types. The syntax with
+ <code class="literal">::</code> is historical <span class="productname">PostgreSQL</span>
+ usage, as is the function-call syntax.
+ </p></div></div><div class="sect2" id="SQL-SYNTAX-OPERATORS"><div class="titlepage"><div><div><h3 class="title">4.1.3. Operators</h3></div></div></div><a id="id-1.5.3.5.10.2" class="indexterm"></a><p>
+ An operator name is a sequence of up to <code class="symbol">NAMEDATALEN</code>-1
+ (63 by default) characters from the following list:
+</p><div class="literallayout"><p><br />
++ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?<br />
+</p></div><p>
+
+ There are a few restrictions on operator names, however:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">--</code> and <code class="literal">/*</code> cannot appear
+ anywhere in an operator name, since they will be taken as the
+ start of a comment.
+ </p></li><li class="listitem"><p>
+ A multiple-character operator name cannot end in <code class="literal">+</code> or <code class="literal">-</code>,
+ unless the name also contains at least one of these characters:
+</p><div class="literallayout"><p><br />
+~ ! @ # % ^ &amp; | ` ?<br />
+</p></div><p>
+ For example, <code class="literal">@-</code> is an allowed operator name,
+ but <code class="literal">*-</code> is not. This restriction allows
+ <span class="productname">PostgreSQL</span> to parse SQL-compliant
+ queries without requiring spaces between tokens.
+ </p></li></ul></div><p>
+ </p><p>
+ When working with non-SQL-standard operator names, you will usually
+ need to separate adjacent operators with spaces to avoid ambiguity.
+ For example, if you have defined a prefix operator named <code class="literal">@</code>,
+ you cannot write <code class="literal">X*@Y</code>; you must write
+ <code class="literal">X* @Y</code> to ensure that
+ <span class="productname">PostgreSQL</span> reads it as two operator names
+ not one.
+ </p></div><div class="sect2" id="SQL-SYNTAX-SPECIAL-CHARS"><div class="titlepage"><div><div><h3 class="title">4.1.4. Special Characters</h3></div></div></div><p>
+ Some characters that are not alphanumeric have a special meaning
+ that is different from being an operator. Details on the usage can
+ be found at the location where the respective syntax element is
+ described. This section only exists to advise the existence and
+ summarize the purposes of these characters.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A dollar sign (<code class="literal">$</code>) followed by digits is used
+ to represent a positional parameter in the body of a function
+ definition or a prepared statement. In other contexts the
+ dollar sign can be part of an identifier or a dollar-quoted string
+ constant.
+ </p></li><li class="listitem"><p>
+ Parentheses (<code class="literal">()</code>) have their usual meaning to
+ group expressions and enforce precedence. In some cases
+ parentheses are required as part of the fixed syntax of a
+ particular SQL command.
+ </p></li><li class="listitem"><p>
+ Brackets (<code class="literal">[]</code>) are used to select the elements
+ of an array. See <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a> for more information
+ on arrays.
+ </p></li><li class="listitem"><p>
+ Commas (<code class="literal">,</code>) are used in some syntactical
+ constructs to separate the elements of a list.
+ </p></li><li class="listitem"><p>
+ The semicolon (<code class="literal">;</code>) terminates an SQL command.
+ It cannot appear anywhere within a command, except within a
+ string constant or quoted identifier.
+ </p></li><li class="listitem"><p>
+ The colon (<code class="literal">:</code>) is used to select
+ <span class="quote">“<span class="quote">slices</span>”</span> from arrays. (See <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a>.) In certain SQL dialects (such as Embedded
+ SQL), the colon is used to prefix variable names.
+ </p></li><li class="listitem"><p>
+ The asterisk (<code class="literal">*</code>) is used in some contexts to denote
+ all the fields of a table row or composite value. It also
+ has a special meaning when used as the argument of an
+ aggregate function, namely that the aggregate does not require
+ any explicit parameter.
+ </p></li><li class="listitem"><p>
+ The period (<code class="literal">.</code>) is used in numeric
+ constants, and to separate schema, table, and column names.
+ </p></li></ul></div><p>
+
+ </p></div><div class="sect2" id="SQL-SYNTAX-COMMENTS"><div class="titlepage"><div><div><h3 class="title">4.1.5. Comments</h3></div></div></div><a id="id-1.5.3.5.12.2" class="indexterm"></a><p>
+ A comment is a sequence of characters beginning with
+ double dashes and extending to the end of the line, e.g.:
+</p><pre class="programlisting">
+-- This is a standard SQL comment
+</pre><p>
+ </p><p>
+ Alternatively, C-style block comments can be used:
+</p><pre class="programlisting">
+/* multiline comment
+ * with nesting: /* nested block comment */
+ */
+</pre><p>
+ where the comment begins with <code class="literal">/*</code> and extends to
+ the matching occurrence of <code class="literal">*/</code>. These block
+ comments nest, as specified in the SQL standard but unlike C, so that one can
+ comment out larger blocks of code that might contain existing block
+ comments.
+ </p><p>
+ A comment is removed from the input stream before further syntax
+ analysis and is effectively replaced by whitespace.
+ </p></div><div class="sect2" id="SQL-PRECEDENCE"><div class="titlepage"><div><div><h3 class="title">4.1.6. Operator Precedence</h3></div></div></div><a id="id-1.5.3.5.13.2" class="indexterm"></a><p>
+ <a class="xref" href="sql-syntax-lexical.html#SQL-PRECEDENCE-TABLE" title="Table 4.2. Operator Precedence (highest to lowest)">Table 4.2</a> shows the precedence and
+ associativity of the operators in <span class="productname">PostgreSQL</span>.
+ Most operators have the same precedence and are left-associative.
+ The precedence and associativity of the operators is hard-wired
+ into the parser.
+ Add parentheses if you want an expression with multiple operators
+ to be parsed in some other way than what the precedence rules imply.
+ </p><div class="table" id="SQL-PRECEDENCE-TABLE"><p class="title"><strong>Table 4.2. Operator Precedence (highest to lowest)</strong></p><div class="table-contents"><table class="table" summary="Operator Precedence (highest to lowest)" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Operator/Element</th><th>Associativity</th><th>Description</th></tr></thead><tbody><tr><td><code class="token">.</code></td><td>left</td><td>table/column name separator</td></tr><tr><td><code class="token">::</code></td><td>left</td><td><span class="productname">PostgreSQL</span>-style typecast</td></tr><tr><td><code class="token">[</code> <code class="token">]</code></td><td>left</td><td>array element selection</td></tr><tr><td><code class="token">+</code> <code class="token">-</code></td><td>right</td><td>unary plus, unary minus</td></tr><tr><td><code class="token">^</code></td><td>left</td><td>exponentiation</td></tr><tr><td><code class="token">*</code> <code class="token">/</code> <code class="token">%</code></td><td>left</td><td>multiplication, division, modulo</td></tr><tr><td><code class="token">+</code> <code class="token">-</code></td><td>left</td><td>addition, subtraction</td></tr><tr><td>(any other operator)</td><td>left</td><td>all other native and user-defined operators</td></tr><tr><td><code class="token">BETWEEN</code> <code class="token">IN</code> <code class="token">LIKE</code> <code class="token">ILIKE</code> <code class="token">SIMILAR</code></td><td> </td><td>range containment, set membership, string matching</td></tr><tr><td><code class="token">&lt;</code> <code class="token">&gt;</code> <code class="token">=</code> <code class="token">&lt;=</code> <code class="token">&gt;=</code> <code class="token">&lt;&gt;</code>
+</td><td> </td><td>comparison operators</td></tr><tr><td><code class="token">IS</code> <code class="token">ISNULL</code> <code class="token">NOTNULL</code></td><td> </td><td><code class="literal">IS TRUE</code>, <code class="literal">IS FALSE</code>, <code class="literal">IS
+ NULL</code>, <code class="literal">IS DISTINCT FROM</code>, etc.</td></tr><tr><td><code class="token">NOT</code></td><td>right</td><td>logical negation</td></tr><tr><td><code class="token">AND</code></td><td>left</td><td>logical conjunction</td></tr><tr><td><code class="token">OR</code></td><td>left</td><td>logical disjunction</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Note that the operator precedence rules also apply to user-defined
+ operators that have the same names as the built-in operators
+ mentioned above. For example, if you define a
+ <span class="quote">“<span class="quote">+</span>”</span> operator for some custom data type it will have
+ the same precedence as the built-in <span class="quote">“<span class="quote">+</span>”</span> operator, no
+ matter what yours does.
+ </p><p>
+ When a schema-qualified operator name is used in the
+ <code class="literal">OPERATOR</code> syntax, as for example in:
+</p><pre class="programlisting">
+SELECT 3 OPERATOR(pg_catalog.+) 4;
+</pre><p>
+ the <code class="literal">OPERATOR</code> construct is taken to have the default precedence
+ shown in <a class="xref" href="sql-syntax-lexical.html#SQL-PRECEDENCE-TABLE" title="Table 4.2. Operator Precedence (highest to lowest)">Table 4.2</a> for
+ <span class="quote">“<span class="quote">any other operator</span>”</span>. This is true no matter
+ which specific operator appears inside <code class="literal">OPERATOR()</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> versions before 9.5 used slightly different
+ operator precedence rules. In particular, <code class="token">&lt;=</code>
+ <code class="token">&gt;=</code> and <code class="token">&lt;&gt;</code> used to be treated as
+ generic operators; <code class="literal">IS</code> tests used to have higher priority;
+ and <code class="literal">NOT BETWEEN</code> and related constructs acted inconsistently,
+ being taken in some cases as having the precedence of <code class="literal">NOT</code>
+ rather than <code class="literal">BETWEEN</code>. These rules were changed for better
+ compliance with the SQL standard and to reduce confusion from
+ inconsistent treatment of logically equivalent constructs. In most
+ cases, these changes will result in no behavioral change, or perhaps
+ in <span class="quote">“<span class="quote">no such operator</span>”</span> failures which can be resolved by adding
+ parentheses. However there are corner cases in which a query might
+ change behavior without any parsing error being reported.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-expressions.html" title="4.2. Value Expressions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. SQL Syntax </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 4.2. Value Expressions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-syntax.html b/doc/src/sgml/html/sql-syntax.html
new file mode 100644
index 0000000..bbe1554
--- /dev/null
+++ b/doc/src/sgml/html/sql-syntax.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 4. SQL Syntax</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql.html" title="Part II. The SQL Language" /><link rel="next" href="sql-syntax-lexical.html" title="4.1. Lexical Structure" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 4. SQL Syntax</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql.html" title="Part II. The SQL Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-syntax-lexical.html" title="4.1. Lexical Structure">Next</a></td></tr></table><hr /></div><div class="chapter" id="SQL-SYNTAX"><div class="titlepage"><div><div><h2 class="title">Chapter 4. SQL Syntax</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="sql-syntax-lexical.html">4.1. Lexical Structure</a></span></dt><dd><dl><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS">4.1.1. Identifiers and Key Words</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS">4.1.2. Constants</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-OPERATORS">4.1.3. Operators</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-SPECIAL-CHARS">4.1.4. Special Characters</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS">4.1.5. Comments</a></span></dt><dt><span class="sect2"><a href="sql-syntax-lexical.html#SQL-PRECEDENCE">4.1.6. Operator Precedence</a></span></dt></dl></dd><dt><span class="sect1"><a href="sql-expressions.html">4.2. Value Expressions</a></span></dt><dd><dl><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-COLUMN-REFS">4.2.1. Column References</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-PARAMETERS-POSITIONAL">4.2.2. Positional Parameters</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-SUBSCRIPTS">4.2.3. Subscripts</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#FIELD-SELECTION">4.2.4. Field Selection</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-OPERATOR-CALLS">4.2.5. Operator Invocations</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-EXPRESSIONS-FUNCTION-CALLS">4.2.6. Function Calls</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-AGGREGATES">4.2.7. Aggregate Expressions</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS">4.2.8. Window Function Calls</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">4.2.9. Type Casts</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-COLLATE-EXPRS">4.2.10. Collation Expressions</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-SCALAR-SUBQUERIES">4.2.11. Scalar Subqueries</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-ARRAY-CONSTRUCTORS">4.2.12. Array Constructors</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS">4.2.13. Row Constructors</a></span></dt><dt><span class="sect2"><a href="sql-expressions.html#SYNTAX-EXPRESS-EVAL">4.2.14. Expression Evaluation Rules</a></span></dt></dl></dd><dt><span class="sect1"><a href="sql-syntax-calling-funcs.html">4.3. Calling Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-POSITIONAL">4.3.1. Using Positional Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED">4.3.2. Using Named Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-MIXED">4.3.3. Using Mixed Notation</a></span></dt></dl></dd></dl></div><a id="id-1.5.3.2" class="indexterm"></a><p>
+ This chapter describes the syntax of SQL. It forms the foundation
+ for understanding the following chapters which will go into detail
+ about how SQL commands are applied to define and modify data.
+ </p><p>
+ We also advise users who are already familiar with SQL to read this
+ chapter carefully because it contains several rules and concepts that
+ are implemented inconsistently among SQL databases or that are
+ specific to <span class="productname">PostgreSQL</span>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql.html" title="Part II. The SQL Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-syntax-lexical.html" title="4.1. Lexical Structure">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. The SQL Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 4.1. Lexical Structure</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-truncate.html b/doc/src/sgml/html/sql-truncate.html
new file mode 100644
index 0000000..9c2178c
--- /dev/null
+++ b/doc/src/sgml/html/sql-truncate.html
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>TRUNCATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-start-transaction.html" title="START TRANSACTION" /><link rel="next" href="sql-unlisten.html" title="UNLISTEN" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">TRUNCATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-start-transaction.html" title="START TRANSACTION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-unlisten.html" title="UNLISTEN">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-TRUNCATE"><div class="titlepage"></div><a id="id-1.9.3.181.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">TRUNCATE</span></h2><p>TRUNCATE — empty a table or set of tables</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+TRUNCATE [ TABLE ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ] [, ... ]
+ [ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ]
+</pre></div><div class="refsect1" id="id-1.9.3.181.5"><h2>Description</h2><p>
+ <code class="command">TRUNCATE</code> quickly removes all rows from a set of
+ tables. It has the same effect as an unqualified
+ <code class="command">DELETE</code> on each table, but since it does not actually
+ scan the tables it is faster. Furthermore, it reclaims disk space
+ immediately, rather than requiring a subsequent <code class="command">VACUUM</code>
+ operation. This is most useful on large tables.
+ </p></div><div class="refsect1" id="id-1.9.3.181.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a table to truncate.
+ If <code class="literal">ONLY</code> is specified before the table name, only that table
+ is truncated. If <code class="literal">ONLY</code> is not specified, the table and all
+ its descendant tables (if any) are truncated. Optionally, <code class="literal">*</code>
+ can be specified after the table name to explicitly indicate that
+ descendant tables are included.
+ </p></dd><dt><span class="term"><code class="literal">RESTART IDENTITY</code></span></dt><dd><p>
+ Automatically restart sequences owned by columns of
+ the truncated table(s).
+ </p></dd><dt><span class="term"><code class="literal">CONTINUE IDENTITY</code></span></dt><dd><p>
+ Do not change the values of sequences. This is the default.
+ </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
+ Automatically truncate all tables that have foreign-key references
+ to any of the named tables, or to any tables added to the group
+ due to <code class="literal">CASCADE</code>.
+ </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
+ Refuse to truncate if any of the tables have foreign-key references
+ from tables that are not listed in the command. This is the default.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.181.7"><h2>Notes</h2><p>
+ You must have the <code class="literal">TRUNCATE</code> privilege on a table
+ to truncate it.
+ </p><p>
+ <code class="command">TRUNCATE</code> acquires an <code class="literal">ACCESS EXCLUSIVE</code> lock on each
+ table it operates on, which blocks all other concurrent operations
+ on the table. When <code class="literal">RESTART IDENTITY</code> is specified, any
+ sequences that are to be restarted are likewise locked exclusively.
+ If concurrent access to a table is required, then
+ the <code class="command">DELETE</code> command should be used instead.
+ </p><p>
+ <code class="command">TRUNCATE</code> cannot be used on a table that has foreign-key
+ references from other tables, unless all such tables are also truncated
+ in the same command. Checking validity in such cases would require table
+ scans, and the whole point is not to do one. The <code class="literal">CASCADE</code>
+ option can be used to automatically include all dependent tables —
+ but be very careful when using this option, or else you might lose data you
+ did not intend to!
+ Note in particular that when the table to be truncated is a partition,
+ siblings partitions are left untouched, but cascading occurs to all
+ referencing tables and all their partitions with no distinction.
+ </p><p>
+ <code class="command">TRUNCATE</code> will not fire any <code class="literal">ON DELETE</code>
+ triggers that might exist for the tables. But it will fire
+ <code class="literal">ON TRUNCATE</code> triggers.
+ If <code class="literal">ON TRUNCATE</code> triggers are defined for any of
+ the tables, then all <code class="literal">BEFORE TRUNCATE</code> triggers are
+ fired before any truncation happens, and all <code class="literal">AFTER
+ TRUNCATE</code> triggers are fired after the last truncation is
+ performed and any sequences are reset.
+ The triggers will fire in the order that the tables are
+ to be processed (first those listed in the command, and then any
+ that were added due to cascading).
+ </p><p>
+ <code class="command">TRUNCATE</code> is not MVCC-safe. After truncation, the table will
+ appear empty to concurrent transactions, if they are using a snapshot
+ taken before the truncation occurred.
+ See <a class="xref" href="mvcc-caveats.html" title="13.6. Caveats">Section 13.6</a> for more details.
+ </p><p>
+ <code class="command">TRUNCATE</code> is transaction-safe with respect to the data
+ in the tables: the truncation will be safely rolled back if the surrounding
+ transaction does not commit.
+ </p><p>
+ When <code class="literal">RESTART IDENTITY</code> is specified, the implied
+ <code class="command">ALTER SEQUENCE RESTART</code> operations are also done
+ transactionally; that is, they will be rolled back if the surrounding
+ transaction does not commit. Be aware that if any additional
+ sequence operations are done on the restarted sequences before the
+ transaction rolls back, the effects of these operations on the sequences
+ will be rolled back, but not their effects on <code class="function">currval()</code>;
+ that is, after the transaction <code class="function">currval()</code> will continue to
+ reflect the last sequence value obtained inside the failed transaction,
+ even though the sequence itself may no longer be consistent with that.
+ This is similar to the usual behavior of <code class="function">currval()</code> after
+ a failed transaction.
+ </p><p>
+ <code class="command">TRUNCATE</code> can be used for foreign tables if
+ supported by the foreign data wrapper, for instance,
+ see <a class="xref" href="postgres-fdw.html" title="F.38. postgres_fdw">postgres_fdw</a>.
+ </p></div><div class="refsect1" id="id-1.9.3.181.8"><h2>Examples</h2><p>
+ Truncate the tables <code class="literal">bigtable</code> and
+ <code class="literal">fattable</code>:
+
+</p><pre class="programlisting">
+TRUNCATE bigtable, fattable;
+</pre><p>
+ </p><p>
+ The same, and also reset any associated sequence generators:
+
+</p><pre class="programlisting">
+TRUNCATE bigtable, fattable RESTART IDENTITY;
+</pre><p>
+ </p><p>
+ Truncate the table <code class="literal">othertable</code>, and cascade to any tables
+ that reference <code class="literal">othertable</code> via foreign-key
+ constraints:
+
+</p><pre class="programlisting">
+TRUNCATE othertable CASCADE;
+</pre></div><div class="refsect1" id="id-1.9.3.181.9"><h2>Compatibility</h2><p>
+ The SQL:2008 standard includes a <code class="command">TRUNCATE</code> command
+ with the syntax <code class="literal">TRUNCATE TABLE
+ <em class="replaceable"><code>tablename</code></em></code>. The clauses
+ <code class="literal">CONTINUE IDENTITY</code>/<code class="literal">RESTART IDENTITY</code>
+ also appear in that standard, but have slightly different though related
+ meanings. Some of the concurrency behavior of this command is left
+ implementation-defined by the standard, so the above notes should be
+ considered and compared with other implementations if necessary.
+ </p></div><div class="refsect1" id="id-1.9.3.181.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-start-transaction.html" title="START TRANSACTION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-unlisten.html" title="UNLISTEN">Next</a></td></tr><tr><td width="40%" align="left" valign="top">START TRANSACTION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> UNLISTEN</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-unlisten.html b/doc/src/sgml/html/sql-unlisten.html
new file mode 100644
index 0000000..ae1499d
--- /dev/null
+++ b/doc/src/sgml/html/sql-unlisten.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>UNLISTEN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-truncate.html" title="TRUNCATE" /><link rel="next" href="sql-update.html" title="UPDATE" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">UNLISTEN</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-truncate.html" title="TRUNCATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-update.html" title="UPDATE">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-UNLISTEN"><div class="titlepage"></div><a id="id-1.9.3.182.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">UNLISTEN</span></h2><p>UNLISTEN — stop listening for a notification</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+UNLISTEN { <em class="replaceable"><code>channel</code></em> | * }
+</pre></div><div class="refsect1" id="id-1.9.3.182.5"><h2>Description</h2><p>
+ <code class="command">UNLISTEN</code> is used to remove an existing
+ registration for <code class="command">NOTIFY</code> events.
+ <code class="command">UNLISTEN</code> cancels any existing registration of
+ the current <span class="productname">PostgreSQL</span> session as a
+ listener on the notification channel named <em class="replaceable"><code>channel</code></em>. The special wildcard
+ <code class="literal">*</code> cancels all listener registrations for the
+ current session.
+ </p><p>
+ <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a>
+ contains a more extensive
+ discussion of the use of <code class="command">LISTEN</code> and
+ <code class="command">NOTIFY</code>.
+ </p></div><div class="refsect1" id="id-1.9.3.182.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>channel</code></em></span></dt><dd><p>
+ Name of a notification channel (any identifier).
+ </p></dd><dt><span class="term"><code class="literal">*</code></span></dt><dd><p>
+ All current listen registrations for this session are cleared.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.182.7"><h2>Notes</h2><p>
+ You can unlisten something you were not listening for; no warning or error
+ will appear.
+ </p><p>
+ At the end of each session, <code class="command">UNLISTEN *</code> is
+ automatically executed.
+ </p><p>
+ A transaction that has executed <code class="command">UNLISTEN</code> cannot be
+ prepared for two-phase commit.
+ </p></div><div class="refsect1" id="id-1.9.3.182.8"><h2>Examples</h2><p>
+ To make a registration:
+
+</p><pre class="programlisting">
+LISTEN virtual;
+NOTIFY virtual;
+Asynchronous notification "virtual" received from server process with PID 8448.
+</pre><p>
+ </p><p>
+ Once <code class="command">UNLISTEN</code> has been executed, further <code class="command">NOTIFY</code>
+ messages will be ignored:
+
+</p><pre class="programlisting">
+UNLISTEN virtual;
+NOTIFY virtual;
+-- no NOTIFY event is received
+</pre></div><div class="refsect1" id="id-1.9.3.182.9"><h2>Compatibility</h2><p>
+ There is no <code class="command">UNLISTEN</code> command in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.182.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-listen.html" title="LISTEN"><span class="refentrytitle">LISTEN</span></a>, <a class="xref" href="sql-notify.html" title="NOTIFY"><span class="refentrytitle">NOTIFY</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-truncate.html" title="TRUNCATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-update.html" title="UPDATE">Next</a></td></tr><tr><td width="40%" align="left" valign="top">TRUNCATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> UPDATE</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-update.html b/doc/src/sgml/html/sql-update.html
new file mode 100644
index 0000000..8f54420
--- /dev/null
+++ b/doc/src/sgml/html/sql-update.html
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>UPDATE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-unlisten.html" title="UNLISTEN" /><link rel="next" href="sql-vacuum.html" title="VACUUM" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">UPDATE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-unlisten.html" title="UNLISTEN">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-vacuum.html" title="VACUUM">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-UPDATE"><div class="titlepage"></div><a id="id-1.9.3.183.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">UPDATE</span></h2><p>UPDATE — update rows of a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+[ WITH [ RECURSIVE ] <em class="replaceable"><code>with_query</code></em> [, ...] ]
+UPDATE [ ONLY ] <em class="replaceable"><code>table_name</code></em> [ * ] [ [ AS ] <em class="replaceable"><code>alias</code></em> ]
+ SET { <em class="replaceable"><code>column_name</code></em> = { <em class="replaceable"><code>expression</code></em> | DEFAULT } |
+ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = [ ROW ] ( { <em class="replaceable"><code>expression</code></em> | DEFAULT } [, ...] ) |
+ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) = ( <em class="replaceable"><code>sub-SELECT</code></em> )
+ } [, ...]
+ [ FROM <em class="replaceable"><code>from_item</code></em> [, ...] ]
+ [ WHERE <em class="replaceable"><code>condition</code></em> | WHERE CURRENT OF <em class="replaceable"><code>cursor_name</code></em> ]
+ [ RETURNING * | <em class="replaceable"><code>output_expression</code></em> [ [ AS ] <em class="replaceable"><code>output_name</code></em> ] [, ...] ]
+</pre></div><div class="refsect1" id="id-1.9.3.183.5"><h2>Description</h2><p>
+ <code class="command">UPDATE</code> changes the values of the specified
+ columns in all rows that satisfy the condition. Only the columns to
+ be modified need be mentioned in the <code class="literal">SET</code> clause;
+ columns not explicitly modified retain their previous values.
+ </p><p>
+ There are two ways to modify a table using information contained in
+ other tables in the database: using sub-selects, or specifying
+ additional tables in the <code class="literal">FROM</code> clause. Which
+ technique is more appropriate depends on the specific
+ circumstances.
+ </p><p>
+ The optional <code class="literal">RETURNING</code> clause causes <code class="command">UPDATE</code>
+ to compute and return value(s) based on each row actually updated.
+ Any expression using the table's columns, and/or columns of other
+ tables mentioned in <code class="literal">FROM</code>, can be computed.
+ The new (post-update) values of the table's columns are used.
+ The syntax of the <code class="literal">RETURNING</code> list is identical to that of the
+ output list of <code class="command">SELECT</code>.
+ </p><p>
+ You must have the <code class="literal">UPDATE</code> privilege on the table,
+ or at least on the column(s) that are listed to be updated.
+ You must also have the <code class="literal">SELECT</code>
+ privilege on any column whose values are read in the
+ <em class="replaceable"><code>expressions</code></em> or
+ <em class="replaceable"><code>condition</code></em>.
+ </p></div><div class="refsect1" id="id-1.9.3.183.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>with_query</code></em></span></dt><dd><p>
+ The <code class="literal">WITH</code> clause allows you to specify one or more
+ subqueries that can be referenced by name in the <code class="command">UPDATE</code>
+ query. See <a class="xref" href="queries-with.html" title="7.8. WITH Queries (Common Table Expressions)">Section 7.8</a> and <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>
+ for details.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of the table to update.
+ If <code class="literal">ONLY</code> is specified before the table name, matching rows
+ are updated in the named table only. If <code class="literal">ONLY</code> is not
+ specified, matching rows are also updated in any tables inheriting from
+ the named table. Optionally, <code class="literal">*</code> can be specified after the
+ table name to explicitly indicate that descendant tables are included.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>alias</code></em></span></dt><dd><p>
+ A substitute name for the target table. When an alias is
+ provided, it completely hides the actual name of the table. For
+ example, given <code class="literal">UPDATE foo AS f</code>, the remainder of the
+ <code class="command">UPDATE</code> statement must refer to this table as
+ <code class="literal">f</code> not <code class="literal">foo</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a column in the table named by <em class="replaceable"><code>table_name</code></em>.
+ The column name can be qualified with a subfield name or array
+ subscript, if needed. Do not include the table's name in the
+ specification of a target column — for example,
+ <code class="literal">UPDATE table_name SET table_name.col = 1</code> is invalid.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ An expression to assign to the column. The expression can use the
+ old values of this and other columns in the table.
+ </p></dd><dt><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
+ Set the column to its default value (which will be NULL if no specific
+ default expression has been assigned to it). An identity column will be
+ set to a new value generated by the associated sequence. For a
+ generated column, specifying this is permitted but merely specifies the
+ normal behavior of computing the column from its generation expression.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sub-SELECT</code></em></span></dt><dd><p>
+ A <code class="literal">SELECT</code> sub-query that produces as many output columns
+ as are listed in the parenthesized column list preceding it. The
+ sub-query must yield no more than one row when executed. If it
+ yields one row, its column values are assigned to the target columns;
+ if it yields no rows, NULL values are assigned to the target columns.
+ The sub-query can refer to old values of the current row of the table
+ being updated.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>from_item</code></em></span></dt><dd><p>
+ A table expression allowing columns from other tables to appear in
+ the <code class="literal">WHERE</code> condition and update expressions. This
+ uses the same syntax as the <a class="link" href="sql-select.html#SQL-FROM" title="FROM Clause"><code class="literal">FROM</code></a> clause of
+ a <code class="command">SELECT</code> statement;
+ for example, an alias for the table name can be specified. Do not
+ repeat the target table as a <em class="replaceable"><code>from_item</code></em>
+ unless you intend a self-join (in which case it must appear with
+ an alias in the <em class="replaceable"><code>from_item</code></em>).
+ </p></dd><dt><span class="term"><em class="replaceable"><code>condition</code></em></span></dt><dd><p>
+ An expression that returns a value of type <code class="type">boolean</code>.
+ Only rows for which this expression returns <code class="literal">true</code>
+ will be updated.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>cursor_name</code></em></span></dt><dd><p>
+ The name of the cursor to use in a <code class="literal">WHERE CURRENT OF</code>
+ condition. The row to be updated is the one most recently fetched
+ from this cursor. The cursor must be a non-grouping
+ query on the <code class="command">UPDATE</code>'s target table.
+ Note that <code class="literal">WHERE CURRENT OF</code> cannot be
+ specified together with a Boolean condition. See
+ <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>
+ for more information about using cursors with
+ <code class="literal">WHERE CURRENT OF</code>.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_expression</code></em></span></dt><dd><p>
+ An expression to be computed and returned by the <code class="command">UPDATE</code>
+ command after each row is updated. The expression can use any
+ column names of the table named by <em class="replaceable"><code>table_name</code></em>
+ or table(s) listed in <code class="literal">FROM</code>.
+ Write <code class="literal">*</code> to return all columns.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>output_name</code></em></span></dt><dd><p>
+ A name to use for a returned column.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.183.7"><h2>Outputs</h2><p>
+ On successful completion, an <code class="command">UPDATE</code> command returns a command
+ tag of the form
+</p><pre class="screen">
+UPDATE <em class="replaceable"><code>count</code></em>
+</pre><p>
+ The <em class="replaceable"><code>count</code></em> is the number
+ of rows updated, including matched rows whose values did not change.
+ Note that the number may be less than the number of rows that matched
+ the <em class="replaceable"><code>condition</code></em> when
+ updates were suppressed by a <code class="literal">BEFORE UPDATE</code> trigger. If
+ <em class="replaceable"><code>count</code></em> is 0, no rows were
+ updated by the query (this is not considered an error).
+ </p><p>
+ If the <code class="command">UPDATE</code> command contains a <code class="literal">RETURNING</code>
+ clause, the result will be similar to that of a <code class="command">SELECT</code>
+ statement containing the columns and values defined in the
+ <code class="literal">RETURNING</code> list, computed over the row(s) updated by the
+ command.
+ </p></div><div class="refsect1" id="id-1.9.3.183.8"><h2>Notes</h2><p>
+ When a <code class="literal">FROM</code> clause is present, what essentially happens
+ is that the target table is joined to the tables mentioned in the
+ <em class="replaceable"><code>from_item</code></em> list, and each output row of the join
+ represents an update operation for the target table. When using
+ <code class="literal">FROM</code> you should ensure that the join
+ produces at most one output row for each row to be modified. In
+ other words, a target row shouldn't join to more than one row from
+ the other table(s). If it does, then only one of the join rows
+ will be used to update the target row, but which one will be used
+ is not readily predictable.
+ </p><p>
+ Because of this indeterminacy, referencing other tables only within
+ sub-selects is safer, though often harder to read and slower than
+ using a join.
+ </p><p>
+ In the case of a partitioned table, updating a row might cause it to no
+ longer satisfy the partition constraint of the containing partition. In that
+ case, if there is some other partition in the partition tree for which this
+ row satisfies its partition constraint, then the row is moved to that
+ partition. If there is no such partition, an error will occur. Behind the
+ scenes, the row movement is actually a <code class="command">DELETE</code> and
+ <code class="command">INSERT</code> operation.
+ </p><p>
+ There is a possibility that a concurrent <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> on the row being moved will get a serialization
+ failure error. Suppose session 1 is performing an <code class="command">UPDATE</code>
+ on a partition key, and meanwhile a concurrent session 2 for which this
+ row is visible performs an <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> operation on this row. In such case,
+ session 2's <code class="command">UPDATE</code> or <code class="command">DELETE</code> will
+ detect the row movement and raise a serialization failure error (which
+ always returns with an SQLSTATE code '40001'). Applications may wish to
+ retry the transaction if this occurs. In the usual case where the table
+ is not partitioned, or where there is no row movement, session 2 would
+ have identified the newly updated row and carried out the
+ <code class="command">UPDATE</code>/<code class="command">DELETE</code> on this new row
+ version.
+ </p><p>
+ Note that while rows can be moved from local partitions to a foreign-table
+ partition (provided the foreign data wrapper supports tuple routing), they
+ cannot be moved from a foreign-table partition to another partition.
+ </p><p>
+ An attempt of moving a row from one partition to another will fail if a
+ foreign key is found to directly reference an ancestor of the source
+ partition that is not the same as the ancestor that's mentioned in the
+ <code class="command">UPDATE</code> query.
+ </p></div><div class="refsect1" id="id-1.9.3.183.9"><h2>Examples</h2><p>
+ Change the word <code class="literal">Drama</code> to <code class="literal">Dramatic</code> in the
+ column <code class="structfield">kind</code> of the table <code class="structname">films</code>:
+
+</p><pre class="programlisting">
+UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama';
+</pre><p>
+ </p><p>
+ Adjust temperature entries and reset precipitation to its default
+ value in one row of the table <code class="structname">weather</code>:
+
+</p><pre class="programlisting">
+UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
+ WHERE city = 'San Francisco' AND date = '2003-07-03';
+</pre><p>
+ </p><p>
+ Perform the same operation and return the updated entries:
+
+</p><pre class="programlisting">
+UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
+ WHERE city = 'San Francisco' AND date = '2003-07-03'
+ RETURNING temp_lo, temp_hi, prcp;
+</pre><p>
+ </p><p>
+ Use the alternative column-list syntax to do the same update:
+</p><pre class="programlisting">
+UPDATE weather SET (temp_lo, temp_hi, prcp) = (temp_lo+1, temp_lo+15, DEFAULT)
+ WHERE city = 'San Francisco' AND date = '2003-07-03';
+</pre><p>
+ </p><p>
+ Increment the sales count of the salesperson who manages the
+ account for Acme Corporation, using the <code class="literal">FROM</code>
+ clause syntax:
+</p><pre class="programlisting">
+UPDATE employees SET sales_count = sales_count + 1 FROM accounts
+ WHERE accounts.name = 'Acme Corporation'
+ AND employees.id = accounts.sales_person;
+</pre><p>
+ </p><p>
+ Perform the same operation, using a sub-select in the
+ <code class="literal">WHERE</code> clause:
+</p><pre class="programlisting">
+UPDATE employees SET sales_count = sales_count + 1 WHERE id =
+ (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation');
+</pre><p>
+ </p><p>
+ Update contact names in an accounts table to match the currently assigned
+ salespeople:
+</p><pre class="programlisting">
+UPDATE accounts SET (contact_first_name, contact_last_name) =
+ (SELECT first_name, last_name FROM employees
+ WHERE employees.id = accounts.sales_person);
+</pre><p>
+ A similar result could be accomplished with a join:
+</p><pre class="programlisting">
+UPDATE accounts SET contact_first_name = first_name,
+ contact_last_name = last_name
+ FROM employees WHERE employees.id = accounts.sales_person;
+</pre><p>
+ However, the second query may give unexpected results
+ if <code class="structname">employees</code>.<code class="structfield">id</code> is not a unique key, whereas
+ the first query is guaranteed to raise an error if there are multiple
+ <code class="structfield">id</code> matches. Also, if there is no match for a particular
+ <code class="structname">accounts</code>.<code class="structfield">sales_person</code> entry, the first query
+ will set the corresponding name fields to NULL, whereas the second query
+ will not update that row at all.
+ </p><p>
+ Update statistics in a summary table to match the current data:
+</p><pre class="programlisting">
+UPDATE summary s SET (sum_x, sum_y, avg_x, avg_y) =
+ (SELECT sum(x), sum(y), avg(x), avg(y) FROM data d
+ WHERE d.group_id = s.group_id);
+</pre><p>
+ </p><p>
+ Attempt to insert a new stock item along with the quantity of stock. If
+ the item already exists, instead update the stock count of the existing
+ item. To do this without failing the entire transaction, use savepoints:
+</p><pre class="programlisting">
+BEGIN;
+-- other operations
+SAVEPOINT sp1;
+INSERT INTO wines VALUES('Chateau Lafite 2003', '24');
+-- Assume the above fails because of a unique key violation,
+-- so now we issue these commands:
+ROLLBACK TO sp1;
+UPDATE wines SET stock = stock + 24 WHERE winename = 'Chateau Lafite 2003';
+-- continue with other operations, and eventually
+COMMIT;
+</pre><p>
+ </p><p>
+ Change the <code class="structfield">kind</code> column of the table
+ <code class="structname">films</code> in the row on which the cursor
+ <code class="literal">c_films</code> is currently positioned:
+</p><pre class="programlisting">
+UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films;
+</pre></div><div class="refsect1" id="id-1.9.3.183.10"><h2>Compatibility</h2><p>
+ This command conforms to the <acronym class="acronym">SQL</acronym> standard, except
+ that the <code class="literal">FROM</code> and <code class="literal">RETURNING</code> clauses
+ are <span class="productname">PostgreSQL</span> extensions, as is the ability
+ to use <code class="literal">WITH</code> with <code class="command">UPDATE</code>.
+ </p><p>
+ Some other database systems offer a <code class="literal">FROM</code> option in which
+ the target table is supposed to be listed again within <code class="literal">FROM</code>.
+ That is not how <span class="productname">PostgreSQL</span> interprets
+ <code class="literal">FROM</code>. Be careful when porting applications that use this
+ extension.
+ </p><p>
+ According to the standard, the source value for a parenthesized sub-list of
+ target column names can be any row-valued expression yielding the correct
+ number of columns. <span class="productname">PostgreSQL</span> only allows the
+ source value to be a <a class="link" href="sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS" title="4.2.13. Row Constructors">row
+ constructor</a> or a sub-<code class="literal">SELECT</code>. An individual column's
+ updated value can be specified as <code class="literal">DEFAULT</code> in the
+ row-constructor case, but not inside a sub-<code class="literal">SELECT</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-unlisten.html" title="UNLISTEN">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-vacuum.html" title="VACUUM">Next</a></td></tr><tr><td width="40%" align="left" valign="top">UNLISTEN </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> VACUUM</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-vacuum.html b/doc/src/sgml/html/sql-vacuum.html
new file mode 100644
index 0000000..789ff56
--- /dev/null
+++ b/doc/src/sgml/html/sql-vacuum.html
@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>VACUUM</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-update.html" title="UPDATE" /><link rel="next" href="sql-values.html" title="VALUES" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">VACUUM</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-update.html" title="UPDATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-values.html" title="VALUES">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-VACUUM"><div class="titlepage"></div><a id="id-1.9.3.184.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">VACUUM</span></h2><p>VACUUM — garbage-collect and optionally analyze a database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+VACUUM [ ( <em class="replaceable"><code>option</code></em> [, ...] ) ] [ <em class="replaceable"><code>table_and_columns</code></em> [, ...] ]
+VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <em class="replaceable"><code>table_and_columns</code></em> [, ...] ]
+
+<span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>
+
+ FULL [ <em class="replaceable"><code>boolean</code></em> ]
+ FREEZE [ <em class="replaceable"><code>boolean</code></em> ]
+ VERBOSE [ <em class="replaceable"><code>boolean</code></em> ]
+ ANALYZE [ <em class="replaceable"><code>boolean</code></em> ]
+ DISABLE_PAGE_SKIPPING [ <em class="replaceable"><code>boolean</code></em> ]
+ SKIP_LOCKED [ <em class="replaceable"><code>boolean</code></em> ]
+ INDEX_CLEANUP { AUTO | ON | OFF }
+ PROCESS_TOAST [ <em class="replaceable"><code>boolean</code></em> ]
+ TRUNCATE [ <em class="replaceable"><code>boolean</code></em> ]
+ PARALLEL <em class="replaceable"><code>integer</code></em>
+
+<span class="phrase">and <em class="replaceable"><code>table_and_columns</code></em> is:</span>
+
+ <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]
+</pre></div><div class="refsect1" id="id-1.9.3.184.5"><h2>Description</h2><p>
+ <code class="command">VACUUM</code> reclaims storage occupied by dead tuples.
+ In normal <span class="productname">PostgreSQL</span> operation, tuples that
+ are deleted or obsoleted by an update are not physically removed from
+ their table; they remain present until a <code class="command">VACUUM</code> is
+ done. Therefore it's necessary to do <code class="command">VACUUM</code>
+ periodically, especially on frequently-updated tables.
+ </p><p>
+ Without a <em class="replaceable"><code>table_and_columns</code></em>
+ list, <code class="command">VACUUM</code> processes every table and materialized view
+ in the current database that the current user has permission to vacuum.
+ With a list, <code class="command">VACUUM</code> processes only those table(s).
+ </p><p>
+ <code class="command">VACUUM ANALYZE</code> performs a <code class="command">VACUUM</code>
+ and then an <code class="command">ANALYZE</code> for each selected table. This
+ is a handy combination form for routine maintenance scripts. See
+ <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>
+ for more details about its processing.
+ </p><p>
+ Plain <code class="command">VACUUM</code> (without <code class="literal">FULL</code>) simply reclaims
+ space and makes it
+ available for re-use. This form of the command can operate in parallel
+ with normal reading and writing of the table, as an exclusive lock
+ is not obtained. However, extra space is not returned to the operating
+ system (in most cases); it's just kept available for re-use within the
+ same table. It also allows us to leverage multiple CPUs in order to process
+ indexes. This feature is known as <em class="firstterm">parallel vacuum</em>.
+ To disable this feature, one can use <code class="literal">PARALLEL</code> option and
+ specify parallel workers as zero. <code class="command">VACUUM FULL</code> rewrites
+ the entire contents of the table into a new disk file with no extra space,
+ allowing unused space to be returned to the operating system. This form is
+ much slower and requires an <code class="literal">ACCESS EXCLUSIVE</code> lock on
+ each table while it is being processed.
+ </p><p>
+ When the option list is surrounded by parentheses, the options can be
+ written in any order. Without parentheses, options must be specified
+ in exactly the order shown above.
+ The parenthesized syntax was added in
+ <span class="productname">PostgreSQL</span> 9.0; the unparenthesized
+ syntax is deprecated.
+ </p></div><div class="refsect1" id="id-1.9.3.184.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">FULL</code></span></dt><dd><p>
+ Selects <span class="quote">“<span class="quote">full</span>”</span> vacuum, which can reclaim more
+ space, but takes much longer and exclusively locks the table.
+ This method also requires extra disk space, since it writes a
+ new copy of the table and doesn't release the old copy until
+ the operation is complete. Usually this should only be used when a
+ significant amount of space needs to be reclaimed from within the table.
+ </p></dd><dt><span class="term"><code class="literal">FREEZE</code></span></dt><dd><p>
+ Selects aggressive <span class="quote">“<span class="quote">freezing</span>”</span> of tuples.
+ Specifying <code class="literal">FREEZE</code> is equivalent to performing
+ <code class="command">VACUUM</code> with the
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-MIN-AGE">vacuum_freeze_min_age</a> and
+ <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FREEZE-TABLE-AGE">vacuum_freeze_table_age</a> parameters
+ set to zero. Aggressive freezing is always performed when the
+ table is rewritten, so this option is redundant when <code class="literal">FULL</code>
+ is specified.
+ </p></dd><dt><span class="term"><code class="literal">VERBOSE</code></span></dt><dd><p>
+ Prints a detailed vacuum activity report for each table.
+ </p></dd><dt><span class="term"><code class="literal">ANALYZE</code></span></dt><dd><p>
+ Updates statistics used by the planner to determine the most
+ efficient way to execute a query.
+ </p></dd><dt><span class="term"><code class="literal">DISABLE_PAGE_SKIPPING</code></span></dt><dd><p>
+ Normally, <code class="command">VACUUM</code> will skip pages based on the <a class="link" href="routine-vacuuming.html#VACUUM-FOR-VISIBILITY-MAP" title="25.1.4. Updating the Visibility Map">visibility map</a>. Pages where
+ all tuples are known to be frozen can always be skipped, and those
+ where all tuples are known to be visible to all transactions may be
+ skipped except when performing an aggressive vacuum. Furthermore,
+ except when performing an aggressive vacuum, some pages may be skipped
+ in order to avoid waiting for other sessions to finish using them.
+ This option disables all page-skipping behavior, and is intended to
+ be used only when the contents of the visibility map are
+ suspect, which should happen only if there is a hardware or software
+ issue causing database corruption.
+ </p></dd><dt><span class="term"><code class="literal">SKIP_LOCKED</code></span></dt><dd><p>
+ Specifies that <code class="command">VACUUM</code> should not wait for any
+ conflicting locks to be released when beginning work on a relation:
+ if a relation cannot be locked immediately without waiting, the relation
+ is skipped. Note that even with this option,
+ <code class="command">VACUUM</code> may still block when opening the relation's
+ indexes. Additionally, <code class="command">VACUUM ANALYZE</code> may still
+ block when acquiring sample rows from partitions, table inheritance
+ children, and some types of foreign tables. Also, while
+ <code class="command">VACUUM</code> ordinarily processes all partitions of
+ specified partitioned tables, this option will cause
+ <code class="command">VACUUM</code> to skip all partitions if there is a
+ conflicting lock on the partitioned table.
+ </p></dd><dt><span class="term"><code class="literal">INDEX_CLEANUP</code></span></dt><dd><p>
+ Normally, <code class="command">VACUUM</code> will skip index vacuuming
+ when there are very few dead tuples in the table. The cost of
+ processing all of the table's indexes is expected to greatly
+ exceed the benefit of removing dead index tuples when this
+ happens. This option can be used to force
+ <code class="command">VACUUM</code> to process indexes when there are more
+ than zero dead tuples. The default is <code class="literal">AUTO</code>,
+ which allows <code class="command">VACUUM</code> to skip index vacuuming
+ when appropriate. If <code class="literal">INDEX_CLEANUP</code> is set to
+ <code class="literal">ON</code>, <code class="command">VACUUM</code> will
+ conservatively remove all dead tuples from indexes. This may be
+ useful for backwards compatibility with earlier releases of
+ <span class="productname">PostgreSQL</span> where this was the
+ standard behavior.
+ </p><p>
+ <code class="literal">INDEX_CLEANUP</code> can also be set to
+ <code class="literal">OFF</code> to force <code class="command">VACUUM</code> to
+ <span class="emphasis"><em>always</em></span> skip index vacuuming, even when
+ there are many dead tuples in the table. This may be useful
+ when it is necessary to make <code class="command">VACUUM</code> run as
+ quickly as possible to avoid imminent transaction ID wraparound
+ (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>). However, the
+ wraparound failsafe mechanism controlled by <a class="xref" href="runtime-config-client.html#GUC-VACUUM-FAILSAFE-AGE">vacuum_failsafe_age</a> will generally trigger
+ automatically to avoid transaction ID wraparound failure, and
+ should be preferred. If index cleanup is not performed
+ regularly, performance may suffer, because as the table is
+ modified indexes will accumulate dead tuples and the table
+ itself will accumulate dead line pointers that cannot be removed
+ until index cleanup is completed.
+ </p><p>
+ This option has no effect for tables that have no index and is
+ ignored if the <code class="literal">FULL</code> option is used. It also
+ has no effect on the transaction ID wraparound failsafe
+ mechanism. When triggered it will skip index vacuuming, even
+ when <code class="literal">INDEX_CLEANUP</code> is set to
+ <code class="literal">ON</code>.
+ </p></dd><dt><span class="term"><code class="literal">PROCESS_TOAST</code></span></dt><dd><p>
+ Specifies that <code class="command">VACUUM</code> should attempt to process the
+ corresponding <code class="literal">TOAST</code> table for each relation, if one
+ exists. This is usually the desired behavior and is the default.
+ Setting this option to false may be useful when it is only necessary to
+ vacuum the main relation. This option is required when the
+ <code class="literal">FULL</code> option is used.
+ </p></dd><dt><span class="term"><code class="literal">TRUNCATE</code></span></dt><dd><p>
+ Specifies that <code class="command">VACUUM</code> should attempt to
+ truncate off any empty pages at the end of the table and allow
+ the disk space for the truncated pages to be returned to
+ the operating system. This is normally the desired behavior
+ and is the default unless the <code class="literal">vacuum_truncate</code>
+ option has been set to false for the table to be vacuumed.
+ Setting this option to false may be useful to avoid
+ <code class="literal">ACCESS EXCLUSIVE</code> lock on the table that
+ the truncation requires. This option is ignored if the
+ <code class="literal">FULL</code> option is used.
+ </p></dd><dt><span class="term"><code class="literal">PARALLEL</code></span></dt><dd><p>
+ Perform index vacuum and index cleanup phases of <code class="command">VACUUM</code>
+ in parallel using <em class="replaceable"><code>integer</code></em>
+ background workers (for the details of each vacuum phase, please
+ refer to <a class="xref" href="progress-reporting.html#VACUUM-PHASES" title="Table 28.41. VACUUM Phases">Table 28.41</a>). The number of workers used
+ to perform the operation is equal to the number of indexes on the
+ relation that support parallel vacuum which is limited by the number of
+ workers specified with <code class="literal">PARALLEL</code> option if any which is
+ further limited by <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS">max_parallel_maintenance_workers</a>.
+ An index can participate in parallel vacuum if and only if the size of the
+ index is more than <a class="xref" href="runtime-config-query.html#GUC-MIN-PARALLEL-INDEX-SCAN-SIZE">min_parallel_index_scan_size</a>.
+ Please note that it is not guaranteed that the number of parallel workers
+ specified in <em class="replaceable"><code>integer</code></em> will be
+ used during execution. It is possible for a vacuum to run with fewer
+ workers than specified, or even with no workers at all. Only one worker
+ can be used per index. So parallel workers are launched only when there
+ are at least <code class="literal">2</code> indexes in the table. Workers for
+ vacuum are launched before the start of each phase and exit at the end of
+ the phase. These behaviors might change in a future release. This
+ option can't be used with the <code class="literal">FULL</code> option.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>
+ Specifies whether the selected option should be turned on or off.
+ You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or
+ <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,
+ <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it. The
+ <em class="replaceable"><code>boolean</code></em> value can also
+ be omitted, in which case <code class="literal">TRUE</code> is assumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>integer</code></em></span></dt><dd><p>
+ Specifies a non-negative integer value passed to the selected option.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
+ The name (optionally schema-qualified) of a specific table or
+ materialized view to vacuum. If the specified table is a partitioned
+ table, all of its leaf partitions are vacuumed.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
+ The name of a specific column to analyze. Defaults to all columns.
+ If a column list is specified, <code class="literal">ANALYZE</code> must also be
+ specified.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.184.7"><h2>Outputs</h2><p>
+ When <code class="literal">VERBOSE</code> is specified, <code class="command">VACUUM</code> emits
+ progress messages to indicate which table is currently being
+ processed. Various statistics about the tables are printed as well.
+ </p></div><div class="refsect1" id="id-1.9.3.184.8"><h2>Notes</h2><p>
+ To vacuum a table, one must ordinarily be the table's owner or a
+ superuser. However, database owners are allowed to
+ vacuum all tables in their databases, except shared catalogs.
+ (The restriction for shared catalogs means that a true database-wide
+ <code class="command">VACUUM</code> can only be performed by a superuser.)
+ <code class="command">VACUUM</code> will skip over any tables that the calling user
+ does not have permission to vacuum.
+ </p><p>
+ <code class="command">VACUUM</code> cannot be executed inside a transaction block.
+ </p><p>
+ For tables with <acronym class="acronym">GIN</acronym> indexes, <code class="command">VACUUM</code> (in
+ any form) also completes any pending index insertions, by moving pending
+ index entries to the appropriate places in the main <acronym class="acronym">GIN</acronym> index
+ structure. See <a class="xref" href="gin-implementation.html#GIN-FAST-UPDATE" title="70.4.1. GIN Fast Update Technique">Section 70.4.1</a> for details.
+ </p><p>
+ We recommend that all databases be vacuumed regularly in
+ order to remove dead rows. <span class="productname">PostgreSQL</span> includes
+ an <span class="quote">“<span class="quote">autovacuum</span>”</span> facility which can automate routine vacuum
+ maintenance. For more information about automatic and manual vacuuming,
+ see <a class="xref" href="routine-vacuuming.html" title="25.1. Routine Vacuuming">Section 25.1</a>.
+ </p><p>
+ The <code class="option">FULL</code> option is not recommended for routine use,
+ but might be useful in special cases. An example is when you have deleted
+ or updated most of the rows in a table and would like the table to
+ physically shrink to occupy less disk space and allow faster table
+ scans. <code class="command">VACUUM FULL</code> will usually shrink the table
+ more than a plain <code class="command">VACUUM</code> would.
+ </p><p>
+ The <code class="option">PARALLEL</code> option is used only for vacuum purposes.
+ If this option is specified with the <code class="option">ANALYZE</code> option,
+ it does not affect <code class="option">ANALYZE</code>.
+ </p><p>
+ <code class="command">VACUUM</code> causes a substantial increase in I/O traffic,
+ which might cause poor performance for other active sessions. Therefore,
+ it is sometimes advisable to use the cost-based vacuum delay feature. For
+ parallel vacuum, each worker sleeps in proportion to the work done by that
+ worker. See <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST" title="20.4.4. Cost-based Vacuum Delay">Section 20.4.4</a> for
+ details.
+ </p><p>
+ Each backend running <code class="command">VACUUM</code> without the
+ <code class="literal">FULL</code> option will report its progress in the
+ <code class="structname">pg_stat_progress_vacuum</code> view. Backends running
+ <code class="command">VACUUM FULL</code> will instead report their progress in the
+ <code class="structname">pg_stat_progress_cluster</code> view. See
+ <a class="xref" href="progress-reporting.html#VACUUM-PROGRESS-REPORTING" title="28.4.3. VACUUM Progress Reporting">Section 28.4.3</a> and
+ <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a> for details.
+ </p></div><div class="refsect1" id="id-1.9.3.184.9"><h2>Examples</h2><p>
+ To clean a single table <code class="literal">onek</code>, analyze it for
+ the optimizer and print a detailed vacuum activity report:
+
+</p><pre class="programlisting">
+VACUUM (VERBOSE, ANALYZE) onek;
+</pre></div><div class="refsect1" id="id-1.9.3.184.10"><h2>Compatibility</h2><p>
+ There is no <code class="command">VACUUM</code> statement in the SQL standard.
+ </p></div><div class="refsect1" id="id-1.9.3.184.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-vacuumdb.html" title="vacuumdb"><span class="refentrytitle"><span class="application">vacuumdb</span></span></a>, <a class="xref" href="runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST" title="20.4.4. Cost-based Vacuum Delay">Section 20.4.4</a>, <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="25.1.6. The Autovacuum Daemon">Section 25.1.6</a>, <a class="xref" href="progress-reporting.html#VACUUM-PROGRESS-REPORTING" title="28.4.3. VACUUM Progress Reporting">Section 28.4.3</a>, <a class="xref" href="progress-reporting.html#CLUSTER-PROGRESS-REPORTING" title="28.4.4. CLUSTER Progress Reporting">Section 28.4.4</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-update.html" title="UPDATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-values.html" title="VALUES">Next</a></td></tr><tr><td width="40%" align="left" valign="top">UPDATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> VALUES</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql-values.html b/doc/src/sgml/html/sql-values.html
new file mode 100644
index 0000000..ac0ad90
--- /dev/null
+++ b/doc/src/sgml/html/sql-values.html
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>VALUES</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-vacuum.html" title="VACUUM" /><link rel="next" href="reference-client.html" title="PostgreSQL Client Applications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">VALUES</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-vacuum.html" title="VACUUM">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="reference-client.html" title="PostgreSQL Client Applications">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-VALUES"><div class="titlepage"></div><a id="id-1.9.3.185.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">VALUES</span></h2><p>VALUES — compute a set of rows</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+VALUES ( <em class="replaceable"><code>expression</code></em> [, ...] ) [, ...]
+ [ ORDER BY <em class="replaceable"><code>sort_expression</code></em> [ ASC | DESC | USING <em class="replaceable"><code>operator</code></em> ] [, ...] ]
+ [ LIMIT { <em class="replaceable"><code>count</code></em> | ALL } ]
+ [ OFFSET <em class="replaceable"><code>start</code></em> [ ROW | ROWS ] ]
+ [ FETCH { FIRST | NEXT } [ <em class="replaceable"><code>count</code></em> ] { ROW | ROWS } ONLY ]
+</pre></div><div class="refsect1" id="id-1.9.3.185.5"><h2>Description</h2><p>
+ <code class="command">VALUES</code> computes a row value or set of row values
+ specified by value expressions. It is most commonly used to generate
+ a <span class="quote">“<span class="quote">constant table</span>”</span> within a larger command, but it can be
+ used on its own.
+ </p><p>
+ When more than one row is specified, all the rows must have the same
+ number of elements. The data types of the resulting table's columns are
+ determined by combining the explicit or inferred types of the expressions
+ appearing in that column, using the same rules as for <code class="literal">UNION</code>
+ (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
+ </p><p>
+ Within larger commands, <code class="command">VALUES</code> is syntactically allowed
+ anywhere that <code class="command">SELECT</code> is. Because it is treated like a
+ <code class="command">SELECT</code> by the grammar, it is possible to use
+ the <code class="literal">ORDER BY</code>, <code class="literal">LIMIT</code> (or
+ equivalently <code class="literal">FETCH FIRST</code>),
+ and <code class="literal">OFFSET</code> clauses with a
+ <code class="command">VALUES</code> command.
+ </p></div><div class="refsect1" id="id-1.9.3.185.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>expression</code></em></span></dt><dd><p>
+ A constant or expression to compute and insert at the indicated place
+ in the resulting table (set of rows). In a <code class="command">VALUES</code> list
+ appearing at the top level of an <code class="command">INSERT</code>, an
+ <em class="replaceable"><code>expression</code></em> can be replaced
+ by <code class="literal">DEFAULT</code> to indicate that the destination column's
+ default value should be inserted. <code class="literal">DEFAULT</code> cannot
+ be used when <code class="command">VALUES</code> appears in other contexts.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>sort_expression</code></em></span></dt><dd><p>
+ An expression or integer constant indicating how to sort the result
+ rows. This expression can refer to the columns of the
+ <code class="command">VALUES</code> result as <code class="literal">column1</code>, <code class="literal">column2</code>,
+ etc. For more details see
+ <a class="xref" href="sql-select.html#SQL-ORDERBY" title="ORDER BY Clause">ORDER BY Clause</a>
+ in the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> documentation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>operator</code></em></span></dt><dd><p>
+ A sorting operator. For details see
+ <a class="xref" href="sql-select.html#SQL-ORDERBY" title="ORDER BY Clause">ORDER BY Clause</a>
+ in the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> documentation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>count</code></em></span></dt><dd><p>
+ The maximum number of rows to return. For details see
+ <a class="xref" href="sql-select.html#SQL-LIMIT" title="LIMIT Clause">LIMIT Clause</a>
+ in the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> documentation.
+ </p></dd><dt><span class="term"><em class="replaceable"><code>start</code></em></span></dt><dd><p>
+ The number of rows to skip before starting to return rows.
+ For details see <a class="xref" href="sql-select.html#SQL-LIMIT" title="LIMIT Clause">LIMIT Clause</a>
+ in the <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> documentation.
+ </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.185.7"><h2>Notes</h2><p>
+ <code class="command">VALUES</code> lists with very large numbers of rows should be avoided,
+ as you might encounter out-of-memory failures or poor performance.
+ <code class="command">VALUES</code> appearing within <code class="command">INSERT</code> is a special case
+ (because the desired column types are known from the <code class="command">INSERT</code>'s
+ target table, and need not be inferred by scanning the <code class="command">VALUES</code>
+ list), so it can handle larger lists than are practical in other contexts.
+ </p></div><div class="refsect1" id="id-1.9.3.185.8"><h2>Examples</h2><p>
+ A bare <code class="command">VALUES</code> command:
+
+</p><pre class="programlisting">
+VALUES (1, 'one'), (2, 'two'), (3, 'three');
+</pre><p>
+
+ This will return a table of two columns and three rows. It's effectively
+ equivalent to:
+
+</p><pre class="programlisting">
+SELECT 1 AS column1, 'one' AS column2
+UNION ALL
+SELECT 2, 'two'
+UNION ALL
+SELECT 3, 'three';
+</pre><p>
+
+ </p><p>
+ More usually, <code class="command">VALUES</code> is used within a larger SQL command.
+ The most common use is in <code class="command">INSERT</code>:
+
+</p><pre class="programlisting">
+INSERT INTO films (code, title, did, date_prod, kind)
+ VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
+</pre><p>
+ </p><p>
+ In the context of <code class="command">INSERT</code>, entries of a <code class="command">VALUES</code> list
+ can be <code class="literal">DEFAULT</code> to indicate that the column default
+ should be used here instead of specifying a value:
+
+</p><pre class="programlisting">
+INSERT INTO films VALUES
+ ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes'),
+ ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama', DEFAULT);
+</pre><p>
+ </p><p>
+ <code class="command">VALUES</code> can also be used where a sub-<code class="command">SELECT</code> might
+ be written, for example in a <code class="literal">FROM</code> clause:
+
+</p><pre class="programlisting">
+SELECT f.*
+ FROM films f, (VALUES('MGM', 'Horror'), ('UA', 'Sci-Fi')) AS t (studio, kind)
+ WHERE f.studio = t.studio AND f.kind = t.kind;
+
+UPDATE employees SET salary = salary * v.increase
+ FROM (VALUES(1, 200000, 1.2), (2, 400000, 1.4)) AS v (depno, target, increase)
+ WHERE employees.depno = v.depno AND employees.sales &gt;= v.target;
+</pre><p>
+
+ Note that an <code class="literal">AS</code> clause is required when <code class="command">VALUES</code>
+ is used in a <code class="literal">FROM</code> clause, just as is true for
+ <code class="command">SELECT</code>. It is not required that the <code class="literal">AS</code> clause
+ specify names for all the columns, but it's good practice to do so.
+ (The default column names for <code class="command">VALUES</code> are <code class="literal">column1</code>,
+ <code class="literal">column2</code>, etc. in <span class="productname">PostgreSQL</span>, but
+ these names might be different in other database systems.)
+ </p><p>
+ When <code class="command">VALUES</code> is used in <code class="command">INSERT</code>, the values are all
+ automatically coerced to the data type of the corresponding destination
+ column. When it's used in other contexts, it might be necessary to specify
+ the correct data type. If the entries are all quoted literal constants,
+ coercing the first is sufficient to determine the assumed type for all:
+
+</p><pre class="programlisting">
+SELECT * FROM machines
+WHERE ip_address IN (VALUES('192.168.0.1'::inet), ('192.168.0.10'), ('192.168.1.43'));
+</pre><div class="tip"><h3 class="title">Tip</h3><p>
+ For simple <code class="literal">IN</code> tests, it's better to rely on the
+ <a class="link" href="functions-comparisons.html#FUNCTIONS-COMPARISONS-IN-SCALAR" title="9.24.1. IN">list-of-scalars</a>
+ form of <code class="literal">IN</code> than to write a <code class="command">VALUES</code>
+ query as shown above. The list of scalars method requires less writing
+ and is often more efficient.
+ </p></div></div><div class="refsect1" id="id-1.9.3.185.9"><h2>Compatibility</h2><p><code class="command">VALUES</code> conforms to the SQL standard.
+ <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code> are
+ <span class="productname">PostgreSQL</span> extensions; see also
+ under <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>.
+ </p></div><div class="refsect1" id="id-1.9.3.185.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>, <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-vacuum.html" title="VACUUM">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="reference-client.html" title="PostgreSQL Client Applications">Next</a></td></tr><tr><td width="40%" align="left" valign="top">VACUUM </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> PostgreSQL Client Applications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sql.html b/doc/src/sgml/html/sql.html
new file mode 100644
index 0000000..02521a2
--- /dev/null
+++ b/doc/src/sgml/html/sql.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part II. The SQL Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-conclusion.html" title="3.7. Conclusion" /><link rel="next" href="sql-syntax.html" title="Chapter 4. SQL Syntax" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part II. The SQL Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-conclusion.html" title="3.7. Conclusion">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Next</a></td></tr></table><hr /></div><div class="part" id="SQL"><div class="titlepage"><div><div><h1 class="title">Part II. The SQL Language</h1></div></div></div><div class="partintro" id="id-1.5.2"><div></div><p>
+ This part describes the use of the <acronym class="acronym">SQL</acronym> language
+ in <span class="productname">PostgreSQL</span>. We start with
+ describing the general syntax of <acronym class="acronym">SQL</acronym>, then
+ explain how to create the structures to hold data, how to populate
+ the database, and how to query it. The middle part lists the
+ available data types and functions for use in
+ <acronym class="acronym">SQL</acronym> commands. The rest treats several
+ aspects that are important for tuning a database for optimal
+ performance.
+ </p><p>
+ The information in this part is arranged so that a novice user can
+ follow it start to end to gain a full understanding of the topics
+ without having to refer forward too many times. The chapters are
+ intended to be self-contained, so that advanced users can read the
+ chapters individually as they choose. The information in this
+ part is presented in a narrative fashion in topical units.
+ Readers looking for a complete description of a particular command
+ should see <a class="xref" href="reference.html" title="Part VI. Reference">Part VI</a>.
+ </p><p>
+ Readers of this part should know how to connect to a
+ <span class="productname">PostgreSQL</span> database and issue
+ <acronym class="acronym">SQL</acronym> commands. Readers that are unfamiliar with
+ these issues are encouraged to read <a class="xref" href="tutorial.html" title="Part I. Tutorial">Part I</a>
+ first. <acronym class="acronym">SQL</acronym> commands are typically entered
+ using the <span class="productname">PostgreSQL</span> interactive terminal
+ <span class="application">psql</span>, but other programs that have
+ similar functionality can be used as well.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="sql-syntax.html">4. SQL Syntax</a></span></dt><dd><dl><dt><span class="sect1"><a href="sql-syntax-lexical.html">4.1. Lexical Structure</a></span></dt><dt><span class="sect1"><a href="sql-expressions.html">4.2. Value Expressions</a></span></dt><dt><span class="sect1"><a href="sql-syntax-calling-funcs.html">4.3. Calling Functions</a></span></dt></dl></dd><dt><span class="chapter"><a href="ddl.html">5. Data Definition</a></span></dt><dd><dl><dt><span class="sect1"><a href="ddl-basics.html">5.1. Table Basics</a></span></dt><dt><span class="sect1"><a href="ddl-default.html">5.2. Default Values</a></span></dt><dt><span class="sect1"><a href="ddl-generated-columns.html">5.3. Generated Columns</a></span></dt><dt><span class="sect1"><a href="ddl-constraints.html">5.4. Constraints</a></span></dt><dt><span class="sect1"><a href="ddl-system-columns.html">5.5. System Columns</a></span></dt><dt><span class="sect1"><a href="ddl-alter.html">5.6. Modifying Tables</a></span></dt><dt><span class="sect1"><a href="ddl-priv.html">5.7. Privileges</a></span></dt><dt><span class="sect1"><a href="ddl-rowsecurity.html">5.8. Row Security Policies</a></span></dt><dt><span class="sect1"><a href="ddl-schemas.html">5.9. Schemas</a></span></dt><dt><span class="sect1"><a href="ddl-inherit.html">5.10. Inheritance</a></span></dt><dt><span class="sect1"><a href="ddl-partitioning.html">5.11. Table Partitioning</a></span></dt><dt><span class="sect1"><a href="ddl-foreign-data.html">5.12. Foreign Data</a></span></dt><dt><span class="sect1"><a href="ddl-others.html">5.13. Other Database Objects</a></span></dt><dt><span class="sect1"><a href="ddl-depend.html">5.14. Dependency Tracking</a></span></dt></dl></dd><dt><span class="chapter"><a href="dml.html">6. Data Manipulation</a></span></dt><dd><dl><dt><span class="sect1"><a href="dml-insert.html">6.1. Inserting Data</a></span></dt><dt><span class="sect1"><a href="dml-update.html">6.2. Updating Data</a></span></dt><dt><span class="sect1"><a href="dml-delete.html">6.3. Deleting Data</a></span></dt><dt><span class="sect1"><a href="dml-returning.html">6.4. Returning Data from Modified Rows</a></span></dt></dl></dd><dt><span class="chapter"><a href="queries.html">7. Queries</a></span></dt><dd><dl><dt><span class="sect1"><a href="queries-overview.html">7.1. Overview</a></span></dt><dt><span class="sect1"><a href="queries-table-expressions.html">7.2. Table Expressions</a></span></dt><dt><span class="sect1"><a href="queries-select-lists.html">7.3. Select Lists</a></span></dt><dt><span class="sect1"><a href="queries-union.html">7.4. Combining Queries (<code class="literal">UNION</code>, <code class="literal">INTERSECT</code>, <code class="literal">EXCEPT</code>)</a></span></dt><dt><span class="sect1"><a href="queries-order.html">7.5. Sorting Rows (<code class="literal">ORDER BY</code>)</a></span></dt><dt><span class="sect1"><a href="queries-limit.html">7.6. <code class="literal">LIMIT</code> and <code class="literal">OFFSET</code></a></span></dt><dt><span class="sect1"><a href="queries-values.html">7.7. <code class="literal">VALUES</code> Lists</a></span></dt><dt><span class="sect1"><a href="queries-with.html">7.8. <code class="literal">WITH</code> Queries (Common Table Expressions)</a></span></dt></dl></dd><dt><span class="chapter"><a href="datatype.html">8. Data Types</a></span></dt><dd><dl><dt><span class="sect1"><a href="datatype-numeric.html">8.1. Numeric Types</a></span></dt><dt><span class="sect1"><a href="datatype-money.html">8.2. Monetary Types</a></span></dt><dt><span class="sect1"><a href="datatype-character.html">8.3. Character Types</a></span></dt><dt><span class="sect1"><a href="datatype-binary.html">8.4. Binary Data Types</a></span></dt><dt><span class="sect1"><a href="datatype-datetime.html">8.5. Date/Time Types</a></span></dt><dt><span class="sect1"><a href="datatype-boolean.html">8.6. Boolean Type</a></span></dt><dt><span class="sect1"><a href="datatype-enum.html">8.7. Enumerated Types</a></span></dt><dt><span class="sect1"><a href="datatype-geometric.html">8.8. Geometric Types</a></span></dt><dt><span class="sect1"><a href="datatype-net-types.html">8.9. Network Address Types</a></span></dt><dt><span class="sect1"><a href="datatype-bit.html">8.10. Bit String Types</a></span></dt><dt><span class="sect1"><a href="datatype-textsearch.html">8.11. Text Search Types</a></span></dt><dt><span class="sect1"><a href="datatype-uuid.html">8.12. <acronym class="acronym">UUID</acronym> Type</a></span></dt><dt><span class="sect1"><a href="datatype-xml.html">8.13. <acronym class="acronym">XML</acronym> Type</a></span></dt><dt><span class="sect1"><a href="datatype-json.html">8.14. <acronym class="acronym">JSON</acronym> Types</a></span></dt><dt><span class="sect1"><a href="arrays.html">8.15. Arrays</a></span></dt><dt><span class="sect1"><a href="rowtypes.html">8.16. Composite Types</a></span></dt><dt><span class="sect1"><a href="rangetypes.html">8.17. Range Types</a></span></dt><dt><span class="sect1"><a href="domains.html">8.18. Domain Types</a></span></dt><dt><span class="sect1"><a href="datatype-oid.html">8.19. Object Identifier Types</a></span></dt><dt><span class="sect1"><a href="datatype-pg-lsn.html">8.20. <code class="type">pg_lsn</code> Type</a></span></dt><dt><span class="sect1"><a href="datatype-pseudo.html">8.21. Pseudo-Types</a></span></dt></dl></dd><dt><span class="chapter"><a href="functions.html">9. Functions and Operators</a></span></dt><dd><dl><dt><span class="sect1"><a href="functions-logical.html">9.1. Logical Operators</a></span></dt><dt><span class="sect1"><a href="functions-comparison.html">9.2. Comparison Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-math.html">9.3. Mathematical Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-string.html">9.4. String Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-binarystring.html">9.5. Binary String Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-bitstring.html">9.6. Bit String Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-matching.html">9.7. Pattern Matching</a></span></dt><dt><span class="sect1"><a href="functions-formatting.html">9.8. Data Type Formatting Functions</a></span></dt><dt><span class="sect1"><a href="functions-datetime.html">9.9. Date/Time Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-enum.html">9.10. Enum Support Functions</a></span></dt><dt><span class="sect1"><a href="functions-geometry.html">9.11. Geometric Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-net.html">9.12. Network Address Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-textsearch.html">9.13. Text Search Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-uuid.html">9.14. UUID Functions</a></span></dt><dt><span class="sect1"><a href="functions-xml.html">9.15. XML Functions</a></span></dt><dt><span class="sect1"><a href="functions-json.html">9.16. JSON Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-sequence.html">9.17. Sequence Manipulation Functions</a></span></dt><dt><span class="sect1"><a href="functions-conditional.html">9.18. Conditional Expressions</a></span></dt><dt><span class="sect1"><a href="functions-array.html">9.19. Array Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-range.html">9.20. Range/Multirange Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-aggregate.html">9.21. Aggregate Functions</a></span></dt><dt><span class="sect1"><a href="functions-window.html">9.22. Window Functions</a></span></dt><dt><span class="sect1"><a href="functions-subquery.html">9.23. Subquery Expressions</a></span></dt><dt><span class="sect1"><a href="functions-comparisons.html">9.24. Row and Array Comparisons</a></span></dt><dt><span class="sect1"><a href="functions-srf.html">9.25. Set Returning Functions</a></span></dt><dt><span class="sect1"><a href="functions-info.html">9.26. System Information Functions and Operators</a></span></dt><dt><span class="sect1"><a href="functions-admin.html">9.27. System Administration Functions</a></span></dt><dt><span class="sect1"><a href="functions-trigger.html">9.28. Trigger Functions</a></span></dt><dt><span class="sect1"><a href="functions-event-triggers.html">9.29. Event Trigger Functions</a></span></dt><dt><span class="sect1"><a href="functions-statistics.html">9.30. Statistics Information Functions</a></span></dt></dl></dd><dt><span class="chapter"><a href="typeconv.html">10. Type Conversion</a></span></dt><dd><dl><dt><span class="sect1"><a href="typeconv-overview.html">10.1. Overview</a></span></dt><dt><span class="sect1"><a href="typeconv-oper.html">10.2. Operators</a></span></dt><dt><span class="sect1"><a href="typeconv-func.html">10.3. Functions</a></span></dt><dt><span class="sect1"><a href="typeconv-query.html">10.4. Value Storage</a></span></dt><dt><span class="sect1"><a href="typeconv-union-case.html">10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs</a></span></dt><dt><span class="sect1"><a href="typeconv-select.html">10.6. <code class="literal">SELECT</code> Output Columns</a></span></dt></dl></dd><dt><span class="chapter"><a href="indexes.html">11. Indexes</a></span></dt><dd><dl><dt><span class="sect1"><a href="indexes-intro.html">11.1. Introduction</a></span></dt><dt><span class="sect1"><a href="indexes-types.html">11.2. Index Types</a></span></dt><dt><span class="sect1"><a href="indexes-multicolumn.html">11.3. Multicolumn Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-ordering.html">11.4. Indexes and <code class="literal">ORDER BY</code></a></span></dt><dt><span class="sect1"><a href="indexes-bitmap-scans.html">11.5. Combining Multiple Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-unique.html">11.6. Unique Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-expressional.html">11.7. Indexes on Expressions</a></span></dt><dt><span class="sect1"><a href="indexes-partial.html">11.8. Partial Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-index-only-scans.html">11.9. Index-Only Scans and Covering Indexes</a></span></dt><dt><span class="sect1"><a href="indexes-opclass.html">11.10. Operator Classes and Operator Families</a></span></dt><dt><span class="sect1"><a href="indexes-collations.html">11.11. Indexes and Collations</a></span></dt><dt><span class="sect1"><a href="indexes-examine.html">11.12. Examining Index Usage</a></span></dt></dl></dd><dt><span class="chapter"><a href="textsearch.html">12. Full Text Search</a></span></dt><dd><dl><dt><span class="sect1"><a href="textsearch-intro.html">12.1. Introduction</a></span></dt><dt><span class="sect1"><a href="textsearch-tables.html">12.2. Tables and Indexes</a></span></dt><dt><span class="sect1"><a href="textsearch-controls.html">12.3. Controlling Text Search</a></span></dt><dt><span class="sect1"><a href="textsearch-features.html">12.4. Additional Features</a></span></dt><dt><span class="sect1"><a href="textsearch-parsers.html">12.5. Parsers</a></span></dt><dt><span class="sect1"><a href="textsearch-dictionaries.html">12.6. Dictionaries</a></span></dt><dt><span class="sect1"><a href="textsearch-configuration.html">12.7. Configuration Example</a></span></dt><dt><span class="sect1"><a href="textsearch-debugging.html">12.8. Testing and Debugging Text Search</a></span></dt><dt><span class="sect1"><a href="textsearch-indexes.html">12.9. Preferred Index Types for Text Search</a></span></dt><dt><span class="sect1"><a href="textsearch-psql.html">12.10. <span class="application">psql</span> Support</a></span></dt><dt><span class="sect1"><a href="textsearch-limitations.html">12.11. Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="mvcc.html">13. Concurrency Control</a></span></dt><dd><dl><dt><span class="sect1"><a href="mvcc-intro.html">13.1. Introduction</a></span></dt><dt><span class="sect1"><a href="transaction-iso.html">13.2. Transaction Isolation</a></span></dt><dt><span class="sect1"><a href="explicit-locking.html">13.3. Explicit Locking</a></span></dt><dt><span class="sect1"><a href="applevel-consistency.html">13.4. Data Consistency Checks at the Application Level</a></span></dt><dt><span class="sect1"><a href="mvcc-serialization-failure-handling.html">13.5. Serialization Failure Handling</a></span></dt><dt><span class="sect1"><a href="mvcc-caveats.html">13.6. Caveats</a></span></dt><dt><span class="sect1"><a href="locking-indexes.html">13.7. Locking and Indexes</a></span></dt></dl></dd><dt><span class="chapter"><a href="performance-tips.html">14. Performance Tips</a></span></dt><dd><dl><dt><span class="sect1"><a href="using-explain.html">14.1. Using <code class="command">EXPLAIN</code></a></span></dt><dt><span class="sect1"><a href="planner-stats.html">14.2. Statistics Used by the Planner</a></span></dt><dt><span class="sect1"><a href="explicit-joins.html">14.3. Controlling the Planner with Explicit <code class="literal">JOIN</code> Clauses</a></span></dt><dt><span class="sect1"><a href="populate.html">14.4. Populating a Database</a></span></dt><dt><span class="sect1"><a href="non-durability.html">14.5. Non-Durable Settings</a></span></dt></dl></dd><dt><span class="chapter"><a href="parallel-query.html">15. Parallel Query</a></span></dt><dd><dl><dt><span class="sect1"><a href="how-parallel-query-works.html">15.1. How Parallel Query Works</a></span></dt><dt><span class="sect1"><a href="when-can-parallel-query-be-used.html">15.2. When Can Parallel Query Be Used?</a></span></dt><dt><span class="sect1"><a href="parallel-plans.html">15.3. Parallel Plans</a></span></dt><dt><span class="sect1"><a href="parallel-safety.html">15.4. Parallel Safety</a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-conclusion.html" title="3.7. Conclusion">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.7. Conclusion </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. SQL Syntax</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ssh-tunnels.html b/doc/src/sgml/html/ssh-tunnels.html
new file mode 100644
index 0000000..4ca453c
--- /dev/null
+++ b/doc/src/sgml/html/ssh-tunnels.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.11. Secure TCP/IP Connections with SSH Tunnels</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption" /><link rel="next" href="event-log-registration.html" title="19.12. Registering Event Log on Windows" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-log-registration.html" title="19.12. Registering Event Log on Windows">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSH-TUNNELS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.11. Secure TCP/IP Connections with <span class="application">SSH</span> Tunnels</h2></div></div></div><a id="id-1.6.6.14.2" class="indexterm"></a><p>
+ It is possible to use <span class="application">SSH</span> to encrypt the network
+ connection between clients and a
+ <span class="productname">PostgreSQL</span> server. Done properly, this
+ provides an adequately secure network connection, even for non-SSL-capable
+ clients.
+ </p><p>
+ First make sure that an <span class="application">SSH</span> server is
+ running properly on the same machine as the
+ <span class="productname">PostgreSQL</span> server and that you can log in using
+ <code class="command">ssh</code> as some user; you then can establish a
+ secure tunnel to the remote server. A secure tunnel listens on a
+ local port and forwards all traffic to a port on the remote machine.
+ Traffic sent to the remote port can arrive on its
+ <code class="literal">localhost</code> address, or different bind
+ address if desired; it does not appear as coming from your
+ local machine. This command creates a secure tunnel from the client
+ machine to the remote machine <code class="literal">foo.com</code>:
+</p><pre class="programlisting">
+ssh -L 63333:localhost:5432 joe@foo.com
+</pre><p>
+ The first number in the <code class="option">-L</code> argument, 63333, is the
+ local port number of the tunnel; it can be any unused port. (IANA
+ reserves ports 49152 through 65535 for private use.) The name or IP
+ address after this is the remote bind address you are connecting to,
+ i.e., <code class="literal">localhost</code>, which is the default. The second
+ number, 5432, is the remote end of the tunnel, e.g., the port number
+ your database server is using. In order to connect to the database
+ server using this tunnel, you connect to port 63333 on the local
+ machine:
+</p><pre class="programlisting">
+psql -h localhost -p 63333 postgres
+</pre><p>
+ To the database server it will then look as though you are
+ user <code class="literal">joe</code> on host <code class="literal">foo.com</code>
+ connecting to the <code class="literal">localhost</code> bind address, and it
+ will use whatever authentication procedure was configured for
+ connections by that user to that bind address. Note that the server will not
+ think the connection is SSL-encrypted, since in fact it is not
+ encrypted between the
+ <span class="application">SSH</span> server and the
+ <span class="productname">PostgreSQL</span> server. This should not pose any
+ extra security risk because they are on the same machine.
+ </p><p>
+ In order for the
+ tunnel setup to succeed you must be allowed to connect via
+ <code class="command">ssh</code> as <code class="literal">joe@foo.com</code>, just
+ as if you had attempted to use <code class="command">ssh</code> to create a
+ terminal session.
+ </p><p>
+ You could also have set up port forwarding as
+</p><pre class="programlisting">
+ssh -L 63333:foo.com:5432 joe@foo.com
+</pre><p>
+ but then the database server will see the connection as coming in
+ on its <code class="literal">foo.com</code> bind address, which is not opened by
+ the default setting <code class="literal">listen_addresses =
+ 'localhost'</code>. This is usually not what you want.
+ </p><p>
+ If you have to <span class="quote">“<span class="quote">hop</span>”</span> to the database server via some
+ login host, one possible setup could look like this:
+</p><pre class="programlisting">
+ssh -L 63333:db.foo.com:5432 joe@shell.foo.com
+</pre><p>
+ Note that this way the connection
+ from <code class="literal">shell.foo.com</code>
+ to <code class="literal">db.foo.com</code> will not be encrypted by the SSH
+ tunnel.
+ SSH offers quite a few configuration possibilities when the network
+ is restricted in various ways. Please refer to the SSH
+ documentation for details.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Several other applications exist that can provide secure tunnels using
+ a procedure similar in concept to the one just described.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-log-registration.html" title="19.12. Registering Event Log on Windows">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.10. Secure TCP/IP Connections with GSSAPI Encryption </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.12. Registering <span class="application">Event Log</span> on <span class="systemitem">Windows</span></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/ssl-tcp.html b/doc/src/sgml/html/ssl-tcp.html
new file mode 100644
index 0000000..24aecfb
--- /dev/null
+++ b/doc/src/sgml/html/ssl-tcp.html
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.9. Secure TCP/IP Connections with SSL</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="encryption-options.html" title="19.8. Encryption Options" /><link rel="next" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.9. Secure TCP/IP Connections with SSL</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="encryption-options.html" title="19.8. Encryption Options">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSL-TCP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.9. Secure TCP/IP Connections with SSL</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SETUP">19.9.1. Basic Setup</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-OPENSSL-CONFIG">19.9.2. OpenSSL Configuration</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CLIENT-CERTIFICATES">19.9.3. Using Client Certificates</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-SERVER-FILES">19.9.4. SSL Server File Usage</a></span></dt><dt><span class="sect2"><a href="ssl-tcp.html#SSL-CERTIFICATE-CREATION">19.9.5. Creating Certificates</a></span></dt></dl></div><a id="id-1.6.6.12.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> has native support for using
+ <acronym class="acronym">SSL</acronym> connections to encrypt client/server communications
+ for increased security. This requires that
+ <span class="productname">OpenSSL</span> is installed on both client and
+ server systems and that support in <span class="productname">PostgreSQL</span> is
+ enabled at build time (see <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>).
+ </p><p>
+ The terms <acronym class="acronym">SSL</acronym> and <acronym class="acronym">TLS</acronym> are often used
+ interchangeably to mean a secure encrypted connection using a
+ <acronym class="acronym">TLS</acronym> protocol. <acronym class="acronym">SSL</acronym> protocols are the
+ precursors to <acronym class="acronym">TLS</acronym> protocols, and the term
+ <acronym class="acronym">SSL</acronym> is still used for encrypted connections even though
+ <acronym class="acronym">SSL</acronym> protocols are no longer supported.
+ <acronym class="acronym">SSL</acronym> is used interchangeably with <acronym class="acronym">TLS</acronym>
+ in <span class="productname">PostgreSQL</span>.
+
+ </p><div class="sect2" id="SSL-SETUP"><div class="titlepage"><div><div><h3 class="title">19.9.1. Basic Setup</h3></div></div></div><p>
+ With <acronym class="acronym">SSL</acronym> support compiled in, the
+ <span class="productname">PostgreSQL</span> server can be started with
+ support for encrypted connections using <acronym class="acronym">TLS</acronym> protocols
+ enabled by setting the parameter
+ <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> to <code class="literal">on</code> in
+ <code class="filename">postgresql.conf</code>. The server will listen for both normal
+ and <acronym class="acronym">SSL</acronym> connections on the same TCP port, and will negotiate
+ with any connecting client on whether to use <acronym class="acronym">SSL</acronym>. By
+ default, this is at the client's option; see <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a> about how to set up the server to require
+ use of <acronym class="acronym">SSL</acronym> for some or all connections.
+ </p><p>
+ To start in <acronym class="acronym">SSL</acronym> mode, files containing the server certificate
+ and private key must exist. By default, these files are expected to be
+ named <code class="filename">server.crt</code> and <code class="filename">server.key</code>, respectively, in
+ the server's data directory, but other names and locations can be specified
+ using the configuration parameters <a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a>
+ and <a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a>.
+ </p><p>
+ On Unix systems, the permissions on <code class="filename">server.key</code> must
+ disallow any access to world or group; achieve this by the command
+ <code class="command">chmod 0600 server.key</code>. Alternatively, the file can be
+ owned by root and have group read access (that is, <code class="literal">0640</code>
+ permissions). That setup is intended for installations where certificate
+ and key files are managed by the operating system. The user under which
+ the <span class="productname">PostgreSQL</span> server runs should then be made a
+ member of the group that has access to those certificate and key files.
+ </p><p>
+ If the data directory allows group read access then certificate files may
+ need to be located outside of the data directory in order to conform to the
+ security requirements outlined above. Generally, group access is enabled
+ to allow an unprivileged user to backup the database, and in that case the
+ backup software will not be able to read the certificate files and will
+ likely error.
+ </p><p>
+ If the private key is protected with a passphrase, the
+ server will prompt for the passphrase and will not start until it has
+ been entered.
+ Using a passphrase by default disables the ability to change the server's
+ SSL configuration without a server restart, but see <a class="xref" href="runtime-config-connection.html#GUC-SSL-PASSPHRASE-COMMAND-SUPPORTS-RELOAD">ssl_passphrase_command_supports_reload</a>.
+ Furthermore, passphrase-protected private keys cannot be used at all
+ on Windows.
+ </p><p>
+ The first certificate in <code class="filename">server.crt</code> must be the
+ server's certificate because it must match the server's private key.
+ The certificates of <span class="quote">“<span class="quote">intermediate</span>”</span> certificate authorities
+ can also be appended to the file. Doing this avoids the necessity of
+ storing intermediate certificates on clients, assuming the root and
+ intermediate certificates were created with <code class="literal">v3_ca</code>
+ extensions. (This sets the certificate's basic constraint of
+ <code class="literal">CA</code> to <code class="literal">true</code>.)
+ This allows easier expiration of intermediate certificates.
+ </p><p>
+ It is not necessary to add the root certificate to
+ <code class="filename">server.crt</code>. Instead, clients must have the root
+ certificate of the server's certificate chain.
+ </p></div><div class="sect2" id="SSL-OPENSSL-CONFIG"><div class="titlepage"><div><div><h3 class="title">19.9.2. OpenSSL Configuration</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> reads the system-wide
+ <span class="productname">OpenSSL</span> configuration file. By default, this
+ file is named <code class="filename">openssl.cnf</code> and is located in the
+ directory reported by <code class="literal">openssl version -d</code>.
+ This default can be overridden by setting environment variable
+ <code class="envar">OPENSSL_CONF</code> to the name of the desired configuration file.
+ </p><p>
+ <span class="productname">OpenSSL</span> supports a wide range of ciphers
+ and authentication algorithms, of varying strength. While a list of
+ ciphers can be specified in the <span class="productname">OpenSSL</span>
+ configuration file, you can specify ciphers specifically for use by
+ the database server by modifying <a class="xref" href="runtime-config-connection.html#GUC-SSL-CIPHERS">ssl_ciphers</a> in
+ <code class="filename">postgresql.conf</code>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ It is possible to have authentication without encryption overhead by
+ using <code class="literal">NULL-SHA</code> or <code class="literal">NULL-MD5</code> ciphers. However,
+ a man-in-the-middle could read and pass communications between client
+ and server. Also, encryption overhead is minimal compared to the
+ overhead of authentication. For these reasons NULL ciphers are not
+ recommended.
+ </p></div></div><div class="sect2" id="SSL-CLIENT-CERTIFICATES"><div class="titlepage"><div><div><h3 class="title">19.9.3. Using Client Certificates</h3></div></div></div><p>
+ To require the client to supply a trusted certificate,
+ place certificates of the root certificate authorities
+ (<acronym class="acronym">CA</acronym>s) you trust in a file in the data
+ directory, set the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> in
+ <code class="filename">postgresql.conf</code> to the new file name, and add the
+ authentication option <code class="literal">clientcert=verify-ca</code> or
+ <code class="literal">clientcert=verify-full</code> to the appropriate
+ <code class="literal">hostssl</code> line(s) in <code class="filename">pg_hba.conf</code>.
+ A certificate will then be requested from the client during SSL
+ connection startup. (See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a description
+ of how to set up certificates on the client.)
+ </p><p>
+ For a <code class="literal">hostssl</code> entry with
+ <code class="literal">clientcert=verify-ca</code>, the server will verify
+ that the client's certificate is signed by one of the trusted
+ certificate authorities. If <code class="literal">clientcert=verify-full</code>
+ is specified, the server will not only verify the certificate
+ chain, but it will also check whether the username or its mapping
+ matches the <code class="literal">cn</code> (Common Name) of the provided certificate.
+ Note that certificate chain validation is always ensured when the
+ <code class="literal">cert</code> authentication method is used
+ (see <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a>).
+ </p><p>
+ Intermediate certificates that chain up to existing root certificates
+ can also appear in the <a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a> file if
+ you wish to avoid storing them on clients (assuming the root and
+ intermediate certificates were created with <code class="literal">v3_ca</code>
+ extensions). Certificate Revocation List (CRL) entries are also
+ checked if the parameter <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> or
+ <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-DIR">ssl_crl_dir</a> is set.
+ </p><p>
+ The <code class="literal">clientcert</code> authentication option is available for
+ all authentication methods, but only in <code class="filename">pg_hba.conf</code> lines
+ specified as <code class="literal">hostssl</code>. When <code class="literal">clientcert</code> is
+ not specified, the server verifies the client certificate against its CA
+ file only if a client certificate is presented and the CA is configured.
+ </p><p>
+ There are two approaches to enforce that users provide a certificate during login.
+ </p><p>
+ The first approach makes use of the <code class="literal">cert</code> authentication
+ method for <code class="literal">hostssl</code> entries in <code class="filename">pg_hba.conf</code>,
+ such that the certificate itself is used for authentication while also
+ providing ssl connection security. See <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a> for details.
+ (It is not necessary to specify any <code class="literal">clientcert</code> options
+ explicitly when using the <code class="literal">cert</code> authentication method.)
+ In this case, the <code class="literal">cn</code> (Common Name) provided in
+ the certificate is checked against the user name or an applicable mapping.
+ </p><p>
+ The second approach combines any authentication method for <code class="literal">hostssl</code>
+ entries with the verification of client certificates by setting the
+ <code class="literal">clientcert</code> authentication option to <code class="literal">verify-ca</code>
+ or <code class="literal">verify-full</code>. The former option only enforces that
+ the certificate is valid, while the latter also ensures that the
+ <code class="literal">cn</code> (Common Name) in the certificate matches
+ the user name or an applicable mapping.
+ </p></div><div class="sect2" id="SSL-SERVER-FILES"><div class="titlepage"><div><div><h3 class="title">19.9.4. SSL Server File Usage</h3></div></div></div><p>
+ <a class="xref" href="ssl-tcp.html#SSL-FILE-USAGE" title="Table 19.2. SSL Server File Usage">Table 19.2</a> summarizes the files that are
+ relevant to the SSL setup on the server. (The shown file names are default
+ names. The locally configured names could be different.)
+ </p><div class="table" id="SSL-FILE-USAGE"><p class="title"><strong>Table 19.2. SSL Server File Usage</strong></p><div class="table-contents"><table class="table" summary="SSL Server File Usage" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>File</th><th>Contents</th><th>Effect</th></tr></thead><tbody><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CERT-FILE">ssl_cert_file</a> (<code class="filename">$PGDATA/server.crt</code>)</td><td>server certificate</td><td>sent to client to indicate server's identity</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-KEY-FILE">ssl_key_file</a> (<code class="filename">$PGDATA/server.key</code>)</td><td>server private key</td><td>proves server certificate was sent by the owner; does not indicate
+ certificate owner is trustworthy</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CA-FILE">ssl_ca_file</a></td><td>trusted certificate authorities</td><td>checks that client certificate is
+ signed by a trusted certificate authority</td></tr><tr><td><a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a></td><td>certificates revoked by certificate authorities</td><td>client certificate must not be on this list</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The server reads these files at server start and whenever the server
+ configuration is reloaded. On <span class="systemitem">Windows</span>
+ systems, they are also re-read whenever a new backend process is spawned
+ for a new client connection.
+ </p><p>
+ If an error in these files is detected at server start, the server will
+ refuse to start. But if an error is detected during a configuration
+ reload, the files are ignored and the old SSL configuration continues to
+ be used. On <span class="systemitem">Windows</span> systems, if an error in
+ these files is detected at backend start, that backend will be unable to
+ establish an SSL connection. In all these cases, the error condition is
+ reported in the server log.
+ </p></div><div class="sect2" id="SSL-CERTIFICATE-CREATION"><div class="titlepage"><div><div><h3 class="title">19.9.5. Creating Certificates</h3></div></div></div><p>
+ To create a simple self-signed certificate for the server, valid for 365
+ days, use the following <span class="productname">OpenSSL</span> command,
+ replacing <em class="replaceable"><code>dbhost.yourdomain.com</code></em> with the
+ server's host name:
+</p><pre class="programlisting">
+openssl req -new -x509 -days 365 -nodes -text -out server.crt \
+ -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+</pre><p>
+ Then do:
+</p><pre class="programlisting">
+chmod og-rwx server.key
+</pre><p>
+ because the server will reject the file if its permissions are more
+ liberal than this.
+ For more details on how to create your server private key and
+ certificate, refer to the <span class="productname">OpenSSL</span> documentation.
+ </p><p>
+ While a self-signed certificate can be used for testing, a certificate
+ signed by a certificate authority (<acronym class="acronym">CA</acronym>) (usually an
+ enterprise-wide root <acronym class="acronym">CA</acronym>) should be used in production.
+ </p><p>
+ To create a server certificate whose identity can be validated
+ by clients, first create a certificate signing request
+ (<acronym class="acronym">CSR</acronym>) and a public/private key file:
+</p><pre class="programlisting">
+openssl req -new -nodes -text -out root.csr \
+ -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
+chmod og-rwx root.key
+</pre><p>
+ Then, sign the request with the key to create a root certificate
+ authority (using the default <span class="productname">OpenSSL</span>
+ configuration file location on <span class="productname">Linux</span>):
+</p><pre class="programlisting">
+openssl x509 -req -in root.csr -text -days 3650 \
+ -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+ -signkey root.key -out root.crt
+</pre><p>
+ Finally, create a server certificate signed by the new root certificate
+ authority:
+</p><pre class="programlisting">
+openssl req -new -nodes -text -out server.csr \
+ -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+chmod og-rwx server.key
+
+openssl x509 -req -in server.csr -text -days 365 \
+ -CA root.crt -CAkey root.key -CAcreateserial \
+ -out server.crt
+</pre><p>
+ <code class="filename">server.crt</code> and <code class="filename">server.key</code>
+ should be stored on the server, and <code class="filename">root.crt</code> should
+ be stored on the client so the client can verify that the server's leaf
+ certificate was signed by its trusted root certificate.
+ <code class="filename">root.key</code> should be stored offline for use in
+ creating future certificates.
+ </p><p>
+ It is also possible to create a chain of trust that includes
+ intermediate certificates:
+</p><pre class="programlisting">
+# root
+openssl req -new -nodes -text -out root.csr \
+ -keyout root.key -subj "/CN=<em class="replaceable"><code>root.yourdomain.com</code></em>"
+chmod og-rwx root.key
+openssl x509 -req -in root.csr -text -days 3650 \
+ -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+ -signkey root.key -out root.crt
+
+# intermediate
+openssl req -new -nodes -text -out intermediate.csr \
+ -keyout intermediate.key -subj "/CN=<em class="replaceable"><code>intermediate.yourdomain.com</code></em>"
+chmod og-rwx intermediate.key
+openssl x509 -req -in intermediate.csr -text -days 1825 \
+ -extfile /etc/ssl/openssl.cnf -extensions v3_ca \
+ -CA root.crt -CAkey root.key -CAcreateserial \
+ -out intermediate.crt
+
+# leaf
+openssl req -new -nodes -text -out server.csr \
+ -keyout server.key -subj "/CN=<em class="replaceable"><code>dbhost.yourdomain.com</code></em>"
+chmod og-rwx server.key
+openssl x509 -req -in server.csr -text -days 365 \
+ -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
+ -out server.crt
+</pre><p>
+ <code class="filename">server.crt</code> and
+ <code class="filename">intermediate.crt</code> should be concatenated
+ into a certificate file bundle and stored on the server.
+ <code class="filename">server.key</code> should also be stored on the server.
+ <code class="filename">root.crt</code> should be stored on the client so
+ the client can verify that the server's leaf certificate was signed
+ by a chain of certificates linked to its trusted root certificate.
+ <code class="filename">root.key</code> and <code class="filename">intermediate.key</code>
+ should be stored offline for use in creating future certificates.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="encryption-options.html" title="19.8. Encryption Options">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="gssapi-enc.html" title="19.10. Secure TCP/IP Connections with GSSAPI Encryption">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.8. Encryption Options </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.10. Secure TCP/IP Connections with GSSAPI Encryption</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sslinfo.html b/doc/src/sgml/html/sslinfo.html
new file mode 100644
index 0000000..b4dea33
--- /dev/null
+++ b/doc/src/sgml/html/sslinfo.html
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.42. sslinfo</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-spi.html" title="F.41. spi" /><link rel="next" href="tablefunc.html" title="F.43. tablefunc" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.42. sslinfo</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-spi.html" title="F.41. spi">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tablefunc.html" title="F.43. tablefunc">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSLINFO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.42. sslinfo</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.6">F.42.1. Functions Provided</a></span></dt><dt><span class="sect2"><a href="sslinfo.html#id-1.11.7.51.7">F.42.2. Author</a></span></dt></dl></div><a id="id-1.11.7.51.2" class="indexterm"></a><p>
+ The <code class="filename">sslinfo</code> module provides information about the SSL
+ certificate that the current client provided when connecting to
+ <span class="productname">PostgreSQL</span>. The module is useless (most functions
+ will return NULL) if the current connection does not use SSL.
+ </p><p>
+ Some of the information available through this module can also be obtained
+ using the built-in system view <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-SSL-VIEW" title="28.2.10. pg_stat_ssl">
+ <code class="structname">pg_stat_ssl</code></a>.
+ </p><p>
+ This extension won't build at all unless the installation was
+ configured with <code class="literal">--with-ssl=openssl</code>.
+ </p><div class="sect2" id="id-1.11.7.51.6"><div class="titlepage"><div><div><h3 class="title">F.42.1. Functions Provided</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="function">ssl_is_used() returns boolean</code>
+ <a id="id-1.11.7.51.6.2.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns true if current connection to server uses SSL, and false
+ otherwise.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_version() returns text</code>
+ <a id="id-1.11.7.51.6.2.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the name of the protocol used for the SSL connection (e.g., TLSv1.0,
+ TLSv1.1, TLSv1.2 or TLSv1.3).
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_cipher() returns text</code>
+ <a id="id-1.11.7.51.6.2.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the name of the cipher used for the SSL connection
+ (e.g., DHE-RSA-AES256-SHA).
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_client_cert_present() returns boolean</code>
+ <a id="id-1.11.7.51.6.2.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns true if current client has presented a valid SSL client
+ certificate to the server, and false otherwise. (The server
+ might or might not be configured to require a client certificate.)
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_client_serial() returns numeric</code>
+ <a id="id-1.11.7.51.6.2.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns serial number of current client certificate. The combination of
+ certificate serial number and certificate issuer is guaranteed to
+ uniquely identify a certificate (but not its owner — the owner
+ ought to regularly change their keys, and get new certificates from the
+ issuer).
+ </p><p>
+ So, if you run your own CA and allow only certificates from this CA to
+ be accepted by the server, the serial number is the most reliable (albeit
+ not very mnemonic) means to identify a user.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_client_dn() returns text</code>
+ <a id="id-1.11.7.51.6.2.6.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the full subject of the current client certificate, converting
+ character data into the current database encoding. It is assumed that
+ if you use non-ASCII characters in the certificate names, your
+ database is able to represent these characters, too. If your database
+ uses the SQL_ASCII encoding, non-ASCII characters in the name will be
+ represented as UTF-8 sequences.
+ </p><p>
+ The result looks like <code class="literal">/CN=Somebody /C=Some country/O=Some organization</code>.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_issuer_dn() returns text</code>
+ <a id="id-1.11.7.51.6.2.7.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Returns the full issuer name of the current client certificate, converting
+ character data into the current database encoding. Encoding conversions
+ are handled the same as for <code class="function">ssl_client_dn</code>.
+ </p><p>
+ The combination of the return value of this function with the
+ certificate serial number uniquely identifies the certificate.
+ </p><p>
+ This function is really useful only if you have more than one trusted CA
+ certificate in your server's certificate authority file, or if this CA
+ has issued some intermediate certificate authority certificates.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_client_dn_field(fieldname text) returns text</code>
+ <a id="id-1.11.7.51.6.2.8.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ This function returns the value of the specified field in the
+ certificate subject, or NULL if the field is not present.
+ Field names are string constants that are converted into ASN1 object
+ identifiers using the <span class="productname">OpenSSL</span> object
+ database. The following values are acceptable:
+ </p><pre class="literallayout">
+commonName (alias CN)
+surname (alias SN)
+name
+givenName (alias GN)
+countryName (alias C)
+localityName (alias L)
+stateOrProvinceName (alias ST)
+organizationName (alias O)
+organizationalUnitName (alias OU)
+title
+description
+initials
+postalCode
+streetAddress
+generationQualifier
+description
+dnQualifier
+x500UniqueIdentifier
+pseudonym
+role
+emailAddress
+</pre><p>
+ All of these fields are optional, except <code class="structfield">commonName</code>.
+ It depends
+ entirely on your CA's policy which of them would be included and which
+ wouldn't. The meaning of these fields, however, is strictly defined by
+ the X.500 and X.509 standards, so you cannot just assign arbitrary
+ meaning to them.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_issuer_field(fieldname text) returns text</code>
+ <a id="id-1.11.7.51.6.2.9.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Same as <code class="function">ssl_client_dn_field</code>, but for the certificate issuer
+ rather than the certificate subject.
+ </p></dd><dt><span class="term">
+ <code class="function">ssl_extension_info() returns setof record</code>
+ <a id="id-1.11.7.51.6.2.10.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Provide information about extensions of client certificate: extension name,
+ extension value, and if it is a critical extension.
+ </p></dd></dl></div></div><div class="sect2" id="id-1.11.7.51.7"><div class="titlepage"><div><div><h3 class="title">F.42.2. Author</h3></div></div></div><p>
+ Victor Wagner <code class="email">&lt;<a class="email" href="mailto:vitus@cryptocom.ru">vitus@cryptocom.ru</a>&gt;</code>, Cryptocom LTD
+ </p><p>
+ Dmitry Voronin <code class="email">&lt;<a class="email" href="mailto:carriingfate92@yandex.ru">carriingfate92@yandex.ru</a>&gt;</code>
+ </p><p>
+ E-Mail of Cryptocom OpenSSL development group:
+ <code class="email">&lt;<a class="email" href="mailto:openssl@cryptocom.ru">openssl@cryptocom.ru</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-spi.html" title="F.41. spi">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tablefunc.html" title="F.43. tablefunc">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.41. spi </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.43. tablefunc</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/sspi-auth.html b/doc/src/sgml/html/sspi-auth.html
new file mode 100644
index 0000000..8c4bd60
--- /dev/null
+++ b/doc/src/sgml/html/sspi-auth.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.7. SSPI Authentication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="gssapi-auth.html" title="21.6. GSSAPI Authentication" /><link rel="next" href="auth-ident.html" title="21.8. Ident Authentication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.7. SSPI Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-ident.html" title="21.8. Ident Authentication">Next</a></td></tr></table><hr /></div><div class="sect1" id="SSPI-AUTH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.7. SSPI Authentication</h2></div></div></div><a id="id-1.6.8.14.2" class="indexterm"></a><p>
+ <span class="productname">SSPI</span> is a <span class="productname">Windows</span>
+ technology for secure authentication with single sign-on.
+ <span class="productname">PostgreSQL</span> will use SSPI in
+ <code class="literal">negotiate</code> mode, which will use
+ <span class="productname">Kerberos</span> when possible and automatically
+ fall back to <span class="productname">NTLM</span> in other cases.
+ <span class="productname">SSPI</span> and <span class="productname">GSSAPI</span>
+ interoperate as clients and servers, e.g., an
+ <span class="productname">SSPI</span> client can authenticate to an
+ <span class="productname">GSSAPI</span> server. It is recommended to use
+ <span class="productname">SSPI</span> on Windows clients and servers and
+ <span class="productname">GSSAPI</span> on non-Windows platforms.
+ </p><p>
+ When using <span class="productname">Kerberos</span> authentication,
+ <span class="productname">SSPI</span> works the same way
+ <span class="productname">GSSAPI</span> does; see <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>
+ for details.
+ </p><p>
+ The following configuration options are supported for <span class="productname">SSPI</span>:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">include_realm</code></span></dt><dd><p>
+ If set to 0, the realm name from the authenticated user principal is
+ stripped off before being passed through the user name mapping
+ (<a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a>). This is discouraged and is
+ primarily available for backwards compatibility, as it is not secure
+ in multi-realm environments unless <code class="literal">krb_realm</code> is
+ also used. It is recommended to
+ leave <code class="literal">include_realm</code> set to the default (1) and to
+ provide an explicit mapping in <code class="filename">pg_ident.conf</code> to convert
+ principal names to <span class="productname">PostgreSQL</span> user names.
+ </p></dd><dt><span class="term"><code class="literal">compat_realm</code></span></dt><dd><p>
+ If set to 1, the domain's SAM-compatible name (also known as the
+ NetBIOS name) is used for the <code class="literal">include_realm</code>
+ option. This is the default. If set to 0, the true realm name from
+ the Kerberos user principal name is used.
+ </p><p>
+ Do not disable this option unless your server runs under a domain
+ account (this includes virtual service accounts on a domain member
+ system) and all clients authenticating through SSPI are also using
+ domain accounts, or authentication will fail.
+ </p></dd><dt><span class="term"><code class="literal">upn_username</code></span></dt><dd><p>
+ If this option is enabled along with <code class="literal">compat_realm</code>,
+ the user name from the Kerberos UPN is used for authentication. If
+ it is disabled (the default), the SAM-compatible user name is used.
+ By default, these two names are identical for new user accounts.
+ </p><p>
+ Note that <span class="application">libpq</span> uses the SAM-compatible name if no
+ explicit user name is specified. If you use
+ <span class="application">libpq</span> or a driver based on it, you should
+ leave this option disabled or explicitly specify user name in the
+ connection string.
+ </p></dd><dt><span class="term"><code class="literal">map</code></span></dt><dd><p>
+ Allows for mapping between system and database user names. See
+ <a class="xref" href="auth-username-maps.html" title="21.2. User Name Maps">Section 21.2</a> for details. For an SSPI/Kerberos
+ principal, such as <code class="literal">username@EXAMPLE.COM</code> (or, less
+ commonly, <code class="literal">username/hostbased@EXAMPLE.COM</code>), the
+ user name used for mapping is
+ <code class="literal">username@EXAMPLE.COM</code> (or
+ <code class="literal">username/hostbased@EXAMPLE.COM</code>, respectively),
+ unless <code class="literal">include_realm</code> has been set to 0, in which case
+ <code class="literal">username</code> (or <code class="literal">username/hostbased</code>)
+ is what is seen as the system user name when mapping.
+ </p></dd><dt><span class="term"><code class="literal">krb_realm</code></span></dt><dd><p>
+ Sets the realm to match user principal names against. If this parameter
+ is set, only users of that realm will be accepted. If it is not set,
+ users of any realm can connect, subject to whatever user name mapping
+ is done.
+ </p></dd></dl></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-ident.html" title="21.8. Ident Authentication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.6. GSSAPI Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.8. Ident Authentication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-file-layout.html b/doc/src/sgml/html/storage-file-layout.html
new file mode 100644
index 0000000..9544f55
--- /dev/null
+++ b/doc/src/sgml/html/storage-file-layout.html
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.1. Database File Layout</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage.html" title="Chapter 73. Database Physical Storage" /><link rel="next" href="storage-toast.html" title="73.2. TOAST" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.1. Database File Layout</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage.html" title="Chapter 73. Database Physical Storage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-toast.html" title="73.2. TOAST">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-FILE-LAYOUT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.1. Database File Layout</h2></div></div></div><p>
+This section describes the storage format at the level of files and
+directories.
+</p><p>
+Traditionally, the configuration and data files used by a database
+cluster are stored together within the cluster's data
+directory, commonly referred to as <code class="varname">PGDATA</code> (after the name of the
+environment variable that can be used to define it). A common location for
+<code class="varname">PGDATA</code> is <code class="filename">/var/lib/pgsql/data</code>. Multiple clusters,
+managed by different server instances, can exist on the same machine.
+</p><p>
+The <code class="varname">PGDATA</code> directory contains several subdirectories and control
+files, as shown in <a class="xref" href="storage-file-layout.html#PGDATA-CONTENTS-TABLE" title="Table 73.1. Contents of PGDATA">Table 73.1</a>. In addition to
+these required items, the cluster configuration files
+<code class="filename">postgresql.conf</code>, <code class="filename">pg_hba.conf</code>, and
+<code class="filename">pg_ident.conf</code> are traditionally stored in
+<code class="varname">PGDATA</code>, although it is possible to place them elsewhere.
+</p><div class="table" id="PGDATA-CONTENTS-TABLE"><p class="title"><strong>Table 73.1. Contents of <code class="varname">PGDATA</code></strong></p><div class="table-contents"><table class="table" summary="Contents of PGDATA" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>
+Item
+</th><th>Description</th></tr></thead><tbody><tr><td><code class="filename">PG_VERSION</code></td><td>A file containing the major version number of <span class="productname">PostgreSQL</span></td></tr><tr><td><code class="filename">base</code></td><td>Subdirectory containing per-database subdirectories</td></tr><tr><td><code class="filename">current_logfiles</code></td><td>File recording the log file(s) currently written to by the logging
+ collector</td></tr><tr><td><code class="filename">global</code></td><td>Subdirectory containing cluster-wide tables, such as
+ <code class="structname">pg_database</code></td></tr><tr><td><code class="filename">pg_commit_ts</code></td><td>Subdirectory containing transaction commit timestamp data</td></tr><tr><td><code class="filename">pg_dynshmem</code></td><td>Subdirectory containing files used by the dynamic shared memory
+ subsystem</td></tr><tr><td><code class="filename">pg_logical</code></td><td>Subdirectory containing status data for logical decoding</td></tr><tr><td><code class="filename">pg_multixact</code></td><td>Subdirectory containing multitransaction status data
+ (used for shared row locks)</td></tr><tr><td><code class="filename">pg_notify</code></td><td>Subdirectory containing LISTEN/NOTIFY status data</td></tr><tr><td><code class="filename">pg_replslot</code></td><td>Subdirectory containing replication slot data</td></tr><tr><td><code class="filename">pg_serial</code></td><td>Subdirectory containing information about committed serializable transactions</td></tr><tr><td><code class="filename">pg_snapshots</code></td><td>Subdirectory containing exported snapshots</td></tr><tr><td><code class="filename">pg_stat</code></td><td>Subdirectory containing permanent files for the statistics
+ subsystem</td></tr><tr><td><code class="filename">pg_stat_tmp</code></td><td>Subdirectory containing temporary files for the statistics
+ subsystem</td></tr><tr><td><code class="filename">pg_subtrans</code></td><td>Subdirectory containing subtransaction status data</td></tr><tr><td><code class="filename">pg_tblspc</code></td><td>Subdirectory containing symbolic links to tablespaces</td></tr><tr><td><code class="filename">pg_twophase</code></td><td>Subdirectory containing state files for prepared transactions</td></tr><tr><td><code class="filename">pg_wal</code></td><td>Subdirectory containing WAL (Write Ahead Log) files</td></tr><tr><td><code class="filename">pg_xact</code></td><td>Subdirectory containing transaction commit status data</td></tr><tr><td><code class="filename">postgresql.auto.conf</code></td><td>A file used for storing configuration parameters that are set by
+<code class="command">ALTER SYSTEM</code></td></tr><tr><td><code class="filename">postmaster.opts</code></td><td>A file recording the command-line options the server was
+last started with</td></tr><tr><td><code class="filename">postmaster.pid</code></td><td>A lock file recording the current postmaster process ID (PID),
+ cluster data directory path,
+ postmaster start timestamp,
+ port number,
+ Unix-domain socket directory path (could be empty),
+ first valid listen_address (IP address or <code class="literal">*</code>, or empty if
+ not listening on TCP),
+ and shared memory segment ID
+ (this file is not present after server shutdown)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+For each database in the cluster there is a subdirectory within
+<code class="varname">PGDATA</code><code class="filename">/base</code>, named after the database's OID in
+<code class="structname">pg_database</code>. This subdirectory is the default location
+for the database's files; in particular, its system catalogs are stored
+there.
+</p><p>
+ Note that the following sections describe the behavior of the builtin
+ <code class="literal">heap</code> <a class="link" href="tableam.html" title="Chapter 63. Table Access Method Interface Definition">table access method</a>,
+ and the builtin <a class="link" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">index access methods</a>. Due
+ to the extensible nature of <span class="productname">PostgreSQL</span>, other
+ access methods might work differently.
+</p><p>
+Each table and index is stored in a separate file. For ordinary relations,
+these files are named after the table or index's <em class="firstterm">filenode</em> number,
+which can be found in <code class="structname">pg_class</code>.<code class="structfield">relfilenode</code>. But
+for temporary relations, the file name is of the form
+<code class="literal">t<em class="replaceable"><code>BBB</code></em>_<em class="replaceable"><code>FFF</code></em></code>, where <em class="replaceable"><code>BBB</code></em>
+is the backend ID of the backend which created the file, and <em class="replaceable"><code>FFF</code></em>
+is the filenode number. In either case, in addition to the main file (a/k/a
+main fork), each table and index has a <em class="firstterm">free space map</em> (see <a class="xref" href="storage-fsm.html" title="73.3. Free Space Map">Section 73.3</a>), which stores information about free space available in
+the relation. The free space map is stored in a file named with the filenode
+number plus the suffix <code class="literal">_fsm</code>. Tables also have a
+<em class="firstterm">visibility map</em>, stored in a fork with the suffix <code class="literal">_vm</code>,
+to track which pages are known to have no dead tuples. The visibility map is
+described further in <a class="xref" href="storage-vm.html" title="73.4. Visibility Map">Section 73.4</a>. Unlogged tables and indexes
+have a third fork, known as the initialization fork, which is stored in a fork
+with the suffix <code class="literal">_init</code> (see <a class="xref" href="storage-init.html" title="73.5. The Initialization Fork">Section 73.5</a>).
+</p><div class="caution"><h3 class="title">Caution</h3><p>
+Note that while a table's filenode often matches its OID, this is
+<span class="emphasis"><em>not</em></span> necessarily the case; some operations, like
+<code class="command">TRUNCATE</code>, <code class="command">REINDEX</code>, <code class="command">CLUSTER</code> and some forms
+of <code class="command">ALTER TABLE</code>, can change the filenode while preserving the OID.
+Avoid assuming that filenode and table OID are the same.
+Also, for certain system catalogs including <code class="structname">pg_class</code> itself,
+<code class="structname">pg_class</code>.<code class="structfield">relfilenode</code> contains zero. The
+actual filenode number of these catalogs is stored in a lower-level data
+structure, and can be obtained using the <code class="function">pg_relation_filenode()</code>
+function.
+</p></div><p>
+When a table or index exceeds 1 GB, it is divided into gigabyte-sized
+<em class="firstterm">segments</em>. The first segment's file name is the same as the
+filenode; subsequent segments are named filenode.1, filenode.2, etc.
+This arrangement avoids problems on platforms that have file size limitations.
+(Actually, 1 GB is just the default segment size. The segment size can be
+adjusted using the configuration option <code class="option">--with-segsize</code>
+when building <span class="productname">PostgreSQL</span>.)
+In principle, free space map and visibility map forks could require multiple
+segments as well, though this is unlikely to happen in practice.
+</p><p>
+A table that has columns with potentially large entries will have an
+associated <em class="firstterm">TOAST</em> table, which is used for out-of-line storage of
+field values that are too large to keep in the table rows proper.
+<code class="structname">pg_class</code>.<code class="structfield">reltoastrelid</code> links from a table to
+its <acronym class="acronym">TOAST</acronym> table, if any.
+See <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a> for more information.
+</p><p>
+The contents of tables and indexes are discussed further in
+<a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>.
+</p><p>
+Tablespaces make the scenario more complicated. Each user-defined tablespace
+has a symbolic link inside the <code class="varname">PGDATA</code><code class="filename">/pg_tblspc</code>
+directory, which points to the physical tablespace directory (i.e., the
+location specified in the tablespace's <code class="command">CREATE TABLESPACE</code> command).
+This symbolic link is named after
+the tablespace's OID. Inside the physical tablespace directory there is
+a subdirectory with a name that depends on the <span class="productname">PostgreSQL</span>
+server version, such as <code class="literal">PG_9.0_201008051</code>. (The reason for using
+this subdirectory is so that successive versions of the database can use
+the same <code class="command">CREATE TABLESPACE</code> location value without conflicts.)
+Within the version-specific subdirectory, there is
+a subdirectory for each database that has elements in the tablespace, named
+after the database's OID. Tables and indexes are stored within that
+directory, using the filenode naming scheme.
+The <code class="literal">pg_default</code> tablespace is not accessed through
+<code class="filename">pg_tblspc</code>, but corresponds to
+<code class="varname">PGDATA</code><code class="filename">/base</code>. Similarly, the <code class="literal">pg_global</code>
+tablespace is not accessed through <code class="filename">pg_tblspc</code>, but corresponds to
+<code class="varname">PGDATA</code><code class="filename">/global</code>.
+</p><p>
+The <code class="function">pg_relation_filepath()</code> function shows the entire path
+(relative to <code class="varname">PGDATA</code>) of any relation. It is often useful
+as a substitute for remembering many of the above rules. But keep in
+mind that this function just gives the name of the first segment of the
+main fork of the relation — you may need to append a segment number
+and/or <code class="literal">_fsm</code>, <code class="literal">_vm</code>, or <code class="literal">_init</code> to find all
+the files associated with the relation.
+</p><p>
+Temporary files (for operations such as sorting more data than can fit in
+memory) are created within <code class="varname">PGDATA</code><code class="filename">/base/pgsql_tmp</code>,
+or within a <code class="filename">pgsql_tmp</code> subdirectory of a tablespace directory
+if a tablespace other than <code class="literal">pg_default</code> is specified for them.
+The name of a temporary file has the form
+<code class="filename">pgsql_tmp<em class="replaceable"><code>PPP</code></em>.<em class="replaceable"><code>NNN</code></em></code>,
+where <em class="replaceable"><code>PPP</code></em> is the PID of the owning backend and
+<em class="replaceable"><code>NNN</code></em> distinguishes different temporary files of that backend.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage.html" title="Chapter 73. Database Physical Storage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-toast.html" title="73.2. TOAST">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 73. Database Physical Storage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.2. TOAST</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-fsm.html b/doc/src/sgml/html/storage-fsm.html
new file mode 100644
index 0000000..9b8bf9c
--- /dev/null
+++ b/doc/src/sgml/html/storage-fsm.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.3. Free Space Map</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-toast.html" title="73.2. TOAST" /><link rel="next" href="storage-vm.html" title="73.4. Visibility Map" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.3. Free Space Map</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-toast.html" title="73.2. TOAST">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-vm.html" title="73.4. Visibility Map">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-FSM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.3. Free Space Map</h2></div></div></div><a id="id-1.10.24.5.2" class="indexterm"></a><a id="id-1.10.24.5.3" class="indexterm"></a><p>
+Each heap and index relation, except for hash indexes, has a Free Space Map
+(<acronym class="acronym">FSM</acronym>) to keep track of available space in the relation.
+It's stored alongside the main relation data in a separate relation fork,
+named after the filenode number of the relation, plus a <code class="literal">_fsm</code>
+suffix. For example, if the filenode of a relation is 12345, the
+<acronym class="acronym">FSM</acronym> is stored in a file called
+<code class="filename">12345_fsm</code>, in the same directory as the main relation file.
+</p><p>
+The Free Space Map is organized as a tree of <acronym class="acronym">FSM</acronym> pages. The
+bottom level <acronym class="acronym">FSM</acronym> pages store the free space available on each
+heap (or index) page, using one byte to represent each such page. The upper
+levels aggregate information from the lower levels.
+</p><p>
+Within each <acronym class="acronym">FSM</acronym> page is a binary tree, stored in an array with
+one byte per node. Each leaf node represents a heap page, or a lower level
+<acronym class="acronym">FSM</acronym> page. In each non-leaf node, the higher of its children's
+values is stored. The maximum value in the leaf nodes is therefore stored
+at the root.
+</p><p>
+See <code class="filename">src/backend/storage/freespace/README</code> for more details on
+how the <acronym class="acronym">FSM</acronym> is structured, and how it's updated and searched.
+The <a class="xref" href="pgfreespacemap.html" title="F.29. pg_freespacemap">pg_freespacemap</a> module
+can be used to examine the information stored in free space maps.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-toast.html" title="73.2. TOAST">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-vm.html" title="73.4. Visibility Map">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.2. TOAST </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.4. Visibility Map</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-hot.html b/doc/src/sgml/html/storage-hot.html
new file mode 100644
index 0000000..412e97d
--- /dev/null
+++ b/doc/src/sgml/html/storage-hot.html
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.7. Heap-Only Tuples (HOT)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-page-layout.html" title="73.6. Database Page Layout" /><link rel="next" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-page-layout.html" title="73.6. Database Page Layout">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-HOT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>)</h2></div></div></div><p>
+ To allow for high concurrency, <span class="productname">PostgreSQL</span>
+ uses <a class="link" href="mvcc-intro.html" title="13.1. Introduction">multiversion concurrency
+ control</a> (<acronym class="acronym">MVCC</acronym>) to store rows. However,
+ <acronym class="acronym">MVCC</acronym> has some downsides for update queries.
+ Specifically, updates require new versions of rows to be added to
+ tables. This can also require new index entries for each updated row,
+ and removal of old versions of rows and their index entries can be
+ expensive.
+ </p><p>
+ To help reduce the overhead of updates,
+ <span class="productname">PostgreSQL</span> has an optimization called
+ heap-only tuples (<acronym class="acronym">HOT</acronym>). This optimization is
+ possible when:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The update does not modify any columns referenced by the table's
+ indexes, including expression and partial indexes.
+ </p></li><li class="listitem"><p>
+ There is sufficient free space on the page containing the old row
+ for the updated row.
+ </p></li></ul></div><p>
+
+ In such cases, heap-only tuples provide two optimizations:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ New index entries are not needed to represent updated rows.
+ </p></li><li class="listitem"><p>
+ Old versions of updated rows can be completely removed during normal
+ operation, including <code class="command">SELECT</code>s, instead of requiring
+ periodic vacuum operations. (This is possible because indexes
+ do not reference their <a class="link" href="storage-page-layout.html" title="73.6. Database Page Layout">page
+ item identifiers</a>.)
+ </p></li></ul></div><p>
+ </p><p>
+ In summary, heap-only tuple updates can only be created
+ if columns used by indexes are not updated. You can
+ increase the likelihood of sufficient page space for
+ <acronym class="acronym">HOT</acronym> updates by decreasing a table's <a class="link" href="sql-createtable.html#RELOPTION-FILLFACTOR"><code class="literal">fillfactor</code></a>.
+ If you don't, <acronym class="acronym">HOT</acronym> updates will still happen because
+ new rows will naturally migrate to new pages and existing pages with
+ sufficient free space for new row versions. The system view <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ALL-TABLES-VIEW" title="28.2.17. pg_stat_all_tables">pg_stat_all_tables</a>
+ allows monitoring of the occurrence of HOT and non-HOT updates.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-page-layout.html" title="73.6. Database Page Layout">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.6. Database Page Layout </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 74. System Catalog Declarations and Initial Contents</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-init.html b/doc/src/sgml/html/storage-init.html
new file mode 100644
index 0000000..ea7c633
--- /dev/null
+++ b/doc/src/sgml/html/storage-init.html
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.5. The Initialization Fork</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-vm.html" title="73.4. Visibility Map" /><link rel="next" href="storage-page-layout.html" title="73.6. Database Page Layout" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.5. The Initialization Fork</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-vm.html" title="73.4. Visibility Map">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-page-layout.html" title="73.6. Database Page Layout">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-INIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.5. The Initialization Fork</h2></div></div></div><a id="id-1.10.24.7.2" class="indexterm"></a><p>
+Each unlogged table, and each index on an unlogged table, has an initialization
+fork. The initialization fork is an empty table or index of the appropriate
+type. When an unlogged table must be reset to empty due to a crash, the
+initialization fork is copied over the main fork, and any other forks are
+erased (they will be recreated automatically as needed).
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-vm.html" title="73.4. Visibility Map">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-page-layout.html" title="73.6. Database Page Layout">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.4. Visibility Map </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.6. Database Page Layout</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-page-layout.html b/doc/src/sgml/html/storage-page-layout.html
new file mode 100644
index 0000000..e6fb04c
--- /dev/null
+++ b/doc/src/sgml/html/storage-page-layout.html
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.6. Database Page Layout</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-init.html" title="73.5. The Initialization Fork" /><link rel="next" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.6. Database Page Layout</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-init.html" title="73.5. The Initialization Fork">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-PAGE-LAYOUT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.6. Database Page Layout</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="storage-page-layout.html#STORAGE-TUPLE-LAYOUT">73.6.1. Table Row Layout</a></span></dt></dl></div><p>
+This section provides an overview of the page format used within
+<span class="productname">PostgreSQL</span> tables and indexes.<a href="#ftn.id-1.10.24.8.2.2" class="footnote"><sup class="footnote" id="id-1.10.24.8.2.2">[17]</sup></a>
+Sequences and <acronym class="acronym">TOAST</acronym> tables are formatted just like a regular table.
+</p><p>
+In the following explanation, a
+<em class="firstterm">byte</em>
+is assumed to contain 8 bits. In addition, the term
+<em class="firstterm">item</em>
+refers to an individual data value that is stored on a page. In a table,
+an item is a row; in an index, an item is an index entry.
+</p><p>
+Every table and index is stored as an array of <em class="firstterm">pages</em> of a
+fixed size (usually 8 kB, although a different page size can be selected
+when compiling the server). In a table, all the pages are logically
+equivalent, so a particular item (row) can be stored in any page. In
+indexes, the first page is generally reserved as a <em class="firstterm">metapage</em>
+holding control information, and there can be different types of pages
+within the index, depending on the index access method.
+</p><p>
+<a class="xref" href="storage-page-layout.html#PAGE-TABLE" title="Table 73.2. Overall Page Layout">Table 73.2</a> shows the overall layout of a page.
+There are five parts to each page.
+</p><div class="table" id="PAGE-TABLE"><p class="title"><strong>Table 73.2. Overall Page Layout</strong></p><div class="table-contents"><table class="table" summary="Overall Page Layout" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>
+Item
+</th><th>Description</th></tr></thead><tbody><tr><td>PageHeaderData</td><td>24 bytes long. Contains general information about the page, including
+free space pointers.</td></tr><tr><td>ItemIdData</td><td>Array of item identifiers pointing to the actual items. Each
+entry is an (offset,length) pair. 4 bytes per item.</td></tr><tr><td>Free space</td><td>The unallocated space. New item identifiers are allocated from
+the start of this area, new items from the end.</td></tr><tr><td>Items</td><td>The actual items themselves.</td></tr><tr><td>Special space</td><td>Index access method specific data. Different methods store different
+data. Empty in ordinary tables.</td></tr></tbody></table></div></div><br class="table-break" /><p>
+
+ The first 24 bytes of each page consists of a page header
+ (<code class="structname">PageHeaderData</code>). Its format is detailed in <a class="xref" href="storage-page-layout.html#PAGEHEADERDATA-TABLE" title="Table 73.3. PageHeaderData Layout">Table 73.3</a>. The first field tracks the most
+ recent WAL entry related to this page. The second field contains
+ the page checksum if <a class="xref" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS">data checksums</a> are
+ enabled. Next is a 2-byte field containing flag bits. This is followed
+ by three 2-byte integer fields (<code class="structfield">pd_lower</code>,
+ <code class="structfield">pd_upper</code>, and
+ <code class="structfield">pd_special</code>). These contain byte offsets
+ from the page start to the start of unallocated space, to the end of
+ unallocated space, and to the start of the special space. The next 2
+ bytes of the page header, <code class="structfield">pd_pagesize_version</code>,
+ store both the page size and a version indicator. Beginning with
+ <span class="productname">PostgreSQL</span> 8.3 the version number is 4;
+ <span class="productname">PostgreSQL</span> 8.1 and 8.2 used version number 3;
+ <span class="productname">PostgreSQL</span> 8.0 used version number 2;
+ <span class="productname">PostgreSQL</span> 7.3 and 7.4 used version number 1;
+ prior releases used version number 0.
+ (The basic page layout and header format has not changed in most of these
+ versions, but the layout of heap row headers has.) The page size
+ is basically only present as a cross-check; there is no support for having
+ more than one page size in an installation.
+ The last field is a hint that shows whether pruning the page is likely
+ to be profitable: it tracks the oldest un-pruned XMAX on the page.
+
+ </p><div class="table" id="PAGEHEADERDATA-TABLE"><p class="title"><strong>Table 73.3. PageHeaderData Layout</strong></p><div class="table-contents"><table class="table" summary="PageHeaderData Layout" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Field</th><th>Type</th><th>Length</th><th>Description</th></tr></thead><tbody><tr><td>pd_lsn</td><td>PageXLogRecPtr</td><td>8 bytes</td><td>LSN: next byte after last byte of WAL record for last change
+ to this page</td></tr><tr><td>pd_checksum</td><td>uint16</td><td>2 bytes</td><td>Page checksum</td></tr><tr><td>pd_flags</td><td>uint16</td><td>2 bytes</td><td>Flag bits</td></tr><tr><td>pd_lower</td><td>LocationIndex</td><td>2 bytes</td><td>Offset to start of free space</td></tr><tr><td>pd_upper</td><td>LocationIndex</td><td>2 bytes</td><td>Offset to end of free space</td></tr><tr><td>pd_special</td><td>LocationIndex</td><td>2 bytes</td><td>Offset to start of special space</td></tr><tr><td>pd_pagesize_version</td><td>uint16</td><td>2 bytes</td><td>Page size and layout version number information</td></tr><tr><td>pd_prune_xid</td><td>TransactionId</td><td>4 bytes</td><td>Oldest unpruned XMAX on page, or zero if none</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ All the details can be found in
+ <code class="filename">src/include/storage/bufpage.h</code>.
+ </p><p>
+ Following the page header are item identifiers
+ (<code class="type">ItemIdData</code>), each requiring four bytes.
+ An item identifier contains a byte-offset to
+ the start of an item, its length in bytes, and a few attribute bits
+ which affect its interpretation.
+ New item identifiers are allocated
+ as needed from the beginning of the unallocated space.
+ The number of item identifiers present can be determined by looking at
+ <code class="structfield">pd_lower</code>, which is increased to allocate a new identifier.
+ Because an item
+ identifier is never moved until it is freed, its index can be used on a
+ long-term basis to reference an item, even when the item itself is moved
+ around on the page to compact free space. In fact, every pointer to an
+ item (<code class="type">ItemPointer</code>, also known as
+ <code class="type">CTID</code>) created by
+ <span class="productname">PostgreSQL</span> consists of a page number and the
+ index of an item identifier.
+
+ </p><p>
+
+ The items themselves are stored in space allocated backwards from the end
+ of unallocated space. The exact structure varies depending on what the
+ table is to contain. Tables and sequences both use a structure named
+ <code class="type">HeapTupleHeaderData</code>, described below.
+
+ </p><p>
+
+ The final section is the <span class="quote">“<span class="quote">special section</span>”</span> which can
+ contain anything the access method wishes to store. For example,
+ b-tree indexes store links to the page's left and right siblings,
+ as well as some other data relevant to the index structure.
+ Ordinary tables do not use a special section at all (indicated by setting
+ <code class="structfield">pd_special</code> to equal the page size).
+
+ </p><p>
+ <a class="xref" href="storage-page-layout.html#STORAGE-PAGE-LAYOUT-FIGURE" title="Figure 73.1. Page Layout">Figure 73.1</a> illustrates how these parts are
+ laid out in a page.
+ </p><div class="figure" id="STORAGE-PAGE-LAYOUT-FIGURE"><p class="title"><strong>Figure 73.1. Page Layout</strong></p><div class="figure-contents"><div class="mediaobject"><object type="image/svg+xml" data="pagelayout.svg" width="100%"></object></div></div></div><br class="figure-break" /><div class="sect2" id="STORAGE-TUPLE-LAYOUT"><div class="titlepage"><div><div><h3 class="title">73.6.1. Table Row Layout</h3></div></div></div><p>
+
+ All table rows are structured in the same way. There is a fixed-size
+ header (occupying 23 bytes on most machines), followed by an optional null
+ bitmap, an optional object ID field, and the user data. The header is
+ detailed
+ in <a class="xref" href="storage-page-layout.html#HEAPTUPLEHEADERDATA-TABLE" title="Table 73.4. HeapTupleHeaderData Layout">Table 73.4</a>. The actual user data
+ (columns of the row) begins at the offset indicated by
+ <code class="structfield">t_hoff</code>, which must always be a multiple of the MAXALIGN
+ distance for the platform.
+ The null bitmap is
+ only present if the <em class="firstterm">HEAP_HASNULL</em> bit is set in
+ <code class="structfield">t_infomask</code>. If it is present it begins just after
+ the fixed header and occupies enough bytes to have one bit per data column
+ (that is, the number of bits that equals the attribute count in
+ <code class="structfield">t_infomask2</code>). In this list of bits, a
+ 1 bit indicates not-null, a 0 bit is a null. When the bitmap is not
+ present, all columns are assumed not-null.
+ The object ID is only present if the <em class="firstterm">HEAP_HASOID_OLD</em> bit
+ is set in <code class="structfield">t_infomask</code>. If present, it appears just
+ before the <code class="structfield">t_hoff</code> boundary. Any padding needed to make
+ <code class="structfield">t_hoff</code> a MAXALIGN multiple will appear between the null
+ bitmap and the object ID. (This in turn ensures that the object ID is
+ suitably aligned.)
+
+ </p><div class="table" id="HEAPTUPLEHEADERDATA-TABLE"><p class="title"><strong>Table 73.4. HeapTupleHeaderData Layout</strong></p><div class="table-contents"><table class="table" summary="HeapTupleHeaderData Layout" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th>Field</th><th>Type</th><th>Length</th><th>Description</th></tr></thead><tbody><tr><td>t_xmin</td><td>TransactionId</td><td>4 bytes</td><td>insert XID stamp</td></tr><tr><td>t_xmax</td><td>TransactionId</td><td>4 bytes</td><td>delete XID stamp</td></tr><tr><td>t_cid</td><td>CommandId</td><td>4 bytes</td><td>insert and/or delete CID stamp (overlays with t_xvac)</td></tr><tr><td>t_xvac</td><td>TransactionId</td><td>4 bytes</td><td>XID for VACUUM operation moving a row version</td></tr><tr><td>t_ctid</td><td>ItemPointerData</td><td>6 bytes</td><td>current TID of this or newer row version</td></tr><tr><td>t_infomask2</td><td>uint16</td><td>2 bytes</td><td>number of attributes, plus various flag bits</td></tr><tr><td>t_infomask</td><td>uint16</td><td>2 bytes</td><td>various flag bits</td></tr><tr><td>t_hoff</td><td>uint8</td><td>1 byte</td><td>offset to user data</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ All the details can be found in
+ <code class="filename">src/include/access/htup_details.h</code>.
+ </p><p>
+
+ Interpreting the actual data can only be done with information obtained
+ from other tables, mostly <code class="structname">pg_attribute</code>. The
+ key values needed to identify field locations are
+ <code class="structfield">attlen</code> and <code class="structfield">attalign</code>.
+ There is no way to directly get a
+ particular attribute, except when there are only fixed width fields and no
+ null values. All this trickery is wrapped up in the functions
+ <em class="firstterm">heap_getattr</em>, <em class="firstterm">fastgetattr</em>
+ and <em class="firstterm">heap_getsysattr</em>.
+
+ </p><p>
+
+ To read the data you need to examine each attribute in turn. First check
+ whether the field is NULL according to the null bitmap. If it is, go to
+ the next. Then make sure you have the right alignment. If the field is a
+ fixed width field, then all the bytes are simply placed. If it's a
+ variable length field (attlen = -1) then it's a bit more complicated.
+ All variable-length data types share the common header structure
+ <code class="type">struct varlena</code>, which includes the total length of the stored
+ value and some flag bits. Depending on the flags, the data can be either
+ inline or in a <acronym class="acronym">TOAST</acronym> table;
+ it might be compressed, too (see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>).
+
+ </p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.10.24.8.2.2" class="footnote"><p><a href="#id-1.10.24.8.2.2" class="para"><sup class="para">[17] </sup></a>
+ Actually, use of this page format is not required for either table or
+ index access methods. The <code class="literal">heap</code> table access method
+ always uses this format. All the existing index methods also use the
+ basic format, but the data kept on index metapages usually doesn't follow
+ the item layout rules.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-init.html" title="73.5. The Initialization Fork">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-hot.html" title="73.7. Heap-Only Tuples (HOT)">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.5. The Initialization Fork </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>)</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-toast.html b/doc/src/sgml/html/storage-toast.html
new file mode 100644
index 0000000..9ce0e1c
--- /dev/null
+++ b/doc/src/sgml/html/storage-toast.html
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.2. TOAST</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-file-layout.html" title="73.1. Database File Layout" /><link rel="next" href="storage-fsm.html" title="73.3. Free Space Map" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.2. TOAST</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-file-layout.html" title="73.1. Database File Layout">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-fsm.html" title="73.3. Free Space Map">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-TOAST"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.2. TOAST</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="storage-toast.html#STORAGE-TOAST-ONDISK">73.2.1. Out-of-Line, On-Disk TOAST Storage</a></span></dt><dt><span class="sect2"><a href="storage-toast.html#STORAGE-TOAST-INMEMORY">73.2.2. Out-of-Line, In-Memory TOAST Storage</a></span></dt></dl></div><a id="id-1.10.24.4.2" class="indexterm"></a><a id="id-1.10.24.4.3" class="indexterm"></a><p>
+This section provides an overview of <acronym class="acronym">TOAST</acronym> (The
+Oversized-Attribute Storage Technique).
+</p><p>
+<span class="productname">PostgreSQL</span> uses a fixed page size (commonly
+8 kB), and does not allow tuples to span multiple pages. Therefore, it is
+not possible to store very large field values directly. To overcome
+this limitation, large field values are compressed and/or broken up into
+multiple physical rows. This happens transparently to the user, with only
+small impact on most of the backend code. The technique is affectionately
+known as <acronym class="acronym">TOAST</acronym> (or <span class="quote">“<span class="quote">the best thing since sliced bread</span>”</span>).
+The <acronym class="acronym">TOAST</acronym> infrastructure is also used to improve handling of
+large data values in-memory.
+</p><p>
+Only certain data types support <acronym class="acronym">TOAST</acronym> — there is no need to
+impose the overhead on data types that cannot produce large field values.
+To support <acronym class="acronym">TOAST</acronym>, a data type must have a variable-length
+(<em class="firstterm">varlena</em>) representation, in which, ordinarily, the first
+four-byte word of any stored value contains the total length of the value in
+bytes (including itself). <acronym class="acronym">TOAST</acronym> does not constrain the rest
+of the data type's representation. The special representations collectively
+called <em class="firstterm"><acronym class="acronym">TOAST</acronym>ed values</em> work by modifying or
+reinterpreting this initial length word. Therefore, the C-level functions
+supporting a <acronym class="acronym">TOAST</acronym>-able data type must be careful about how they
+handle potentially <acronym class="acronym">TOAST</acronym>ed input values: an input might not
+actually consist of a four-byte length word and contents until after it's
+been <em class="firstterm">detoasted</em>. (This is normally done by invoking
+<code class="function">PG_DETOAST_DATUM</code> before doing anything with an input value,
+but in some cases more efficient approaches are possible.
+See <a class="xref" href="xtypes.html#XTYPES-TOAST" title="38.13.1. TOAST Considerations">Section 38.13.1</a> for more detail.)
+</p><p>
+<acronym class="acronym">TOAST</acronym> usurps two bits of the varlena length word (the high-order
+bits on big-endian machines, the low-order bits on little-endian machines),
+thereby limiting the logical size of any value of a <acronym class="acronym">TOAST</acronym>-able
+data type to 1 GB (2<sup>30</sup> - 1 bytes). When both bits are zero,
+the value is an ordinary un-<acronym class="acronym">TOAST</acronym>ed value of the data type, and
+the remaining bits of the length word give the total datum size (including
+length word) in bytes. When the highest-order or lowest-order bit is set,
+the value has only a single-byte header instead of the normal four-byte
+header, and the remaining bits of that byte give the total datum size
+(including length byte) in bytes. This alternative supports space-efficient
+storage of values shorter than 127 bytes, while still allowing the data type
+to grow to 1 GB at need. Values with single-byte headers aren't aligned on
+any particular boundary, whereas values with four-byte headers are aligned on
+at least a four-byte boundary; this omission of alignment padding provides
+additional space savings that is significant compared to short values.
+As a special case, if the remaining bits of a single-byte header are all
+zero (which would be impossible for a self-inclusive length), the value is
+a pointer to out-of-line data, with several possible alternatives as
+described below. The type and size of such a <em class="firstterm">TOAST pointer</em>
+are determined by a code stored in the second byte of the datum.
+Lastly, when the highest-order or lowest-order bit is clear but the adjacent
+bit is set, the content of the datum has been compressed and must be
+decompressed before use. In this case the remaining bits of the four-byte
+length word give the total size of the compressed datum, not the
+original data. Note that compression is also possible for out-of-line data
+but the varlena header does not tell whether it has occurred —
+the content of the <acronym class="acronym">TOAST</acronym> pointer tells that, instead.
+</p><p>
+The compression technique used for either in-line or out-of-line compressed
+data can be selected for each column by setting
+the <code class="literal">COMPRESSION</code> column option in <code class="command">CREATE
+TABLE</code> or <code class="command">ALTER TABLE</code>. The default for columns
+with no explicit setting is to consult the
+<a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TOAST-COMPRESSION">default_toast_compression</a> parameter at the time data is
+inserted.
+</p><p>
+As mentioned, there are multiple types of <acronym class="acronym">TOAST</acronym> pointer datums.
+The oldest and most common type is a pointer to out-of-line data stored in
+a <em class="firstterm"><acronym class="acronym">TOAST</acronym> table</em> that is separate from, but
+associated with, the table containing the <acronym class="acronym">TOAST</acronym> pointer datum
+itself. These <em class="firstterm">on-disk</em> pointer datums are created by the
+<acronym class="acronym">TOAST</acronym> management code (in <code class="filename">access/common/toast_internals.c</code>)
+when a tuple to be stored on disk is too large to be stored as-is.
+Further details appear in <a class="xref" href="storage-toast.html#STORAGE-TOAST-ONDISK" title="73.2.1. Out-of-Line, On-Disk TOAST Storage">Section 73.2.1</a>.
+Alternatively, a <acronym class="acronym">TOAST</acronym> pointer datum can contain a pointer to
+out-of-line data that appears elsewhere in memory. Such datums are
+necessarily short-lived, and will never appear on-disk, but they are very
+useful for avoiding copying and redundant processing of large data values.
+Further details appear in <a class="xref" href="storage-toast.html#STORAGE-TOAST-INMEMORY" title="73.2.2. Out-of-Line, In-Memory TOAST Storage">Section 73.2.2</a>.
+</p><div class="sect2" id="STORAGE-TOAST-ONDISK"><div class="titlepage"><div><div><h3 class="title">73.2.1. Out-of-Line, On-Disk TOAST Storage</h3></div></div></div><p>
+If any of the columns of a table are <acronym class="acronym">TOAST</acronym>-able, the table will
+have an associated <acronym class="acronym">TOAST</acronym> table, whose OID is stored in the table's
+<code class="structname">pg_class</code>.<code class="structfield">reltoastrelid</code> entry. On-disk
+<acronym class="acronym">TOAST</acronym>ed values are kept in the <acronym class="acronym">TOAST</acronym> table, as
+described in more detail below.
+</p><p>
+Out-of-line values are divided (after compression if used) into chunks of at
+most <code class="symbol">TOAST_MAX_CHUNK_SIZE</code> bytes (by default this value is chosen
+so that four chunk rows will fit on a page, making it about 2000 bytes).
+Each chunk is stored as a separate row in the <acronym class="acronym">TOAST</acronym> table
+belonging to the owning table. Every
+<acronym class="acronym">TOAST</acronym> table has the columns <code class="structfield">chunk_id</code> (an OID
+identifying the particular <acronym class="acronym">TOAST</acronym>ed value),
+<code class="structfield">chunk_seq</code> (a sequence number for the chunk within its value),
+and <code class="structfield">chunk_data</code> (the actual data of the chunk). A unique index
+on <code class="structfield">chunk_id</code> and <code class="structfield">chunk_seq</code> provides fast
+retrieval of the values. A pointer datum representing an out-of-line on-disk
+<acronym class="acronym">TOAST</acronym>ed value therefore needs to store the OID of the
+<acronym class="acronym">TOAST</acronym> table in which to look and the OID of the specific value
+(its <code class="structfield">chunk_id</code>). For convenience, pointer datums also store the
+logical datum size (original uncompressed data length), physical stored size
+(different if compression was applied), and the compression method used, if
+any. Allowing for the varlena header bytes,
+the total size of an on-disk <acronym class="acronym">TOAST</acronym> pointer datum is therefore 18
+bytes regardless of the actual size of the represented value.
+</p><p>
+The <acronym class="acronym">TOAST</acronym> management code is triggered only
+when a row value to be stored in a table is wider than
+<code class="symbol">TOAST_TUPLE_THRESHOLD</code> bytes (normally 2 kB).
+The <acronym class="acronym">TOAST</acronym> code will compress and/or move
+field values out-of-line until the row value is shorter than
+<code class="symbol">TOAST_TUPLE_TARGET</code> bytes (also normally 2 kB, adjustable)
+or no more gains can be had. During an UPDATE
+operation, values of unchanged fields are normally preserved as-is; so an
+UPDATE of a row with out-of-line values incurs no <acronym class="acronym">TOAST</acronym> costs if
+none of the out-of-line values change.
+</p><p>
+The <acronym class="acronym">TOAST</acronym> management code recognizes four different strategies
+for storing <acronym class="acronym">TOAST</acronym>-able columns on disk:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">PLAIN</code> prevents either compression or
+ out-of-line storage. This is the only possible strategy for
+ columns of non-<acronym class="acronym">TOAST</acronym>-able data types.
+ </p></li><li class="listitem"><p>
+ <code class="literal">EXTENDED</code> allows both compression and out-of-line
+ storage. This is the default for most <acronym class="acronym">TOAST</acronym>-able data types.
+ Compression will be attempted first, then out-of-line storage if
+ the row is still too big.
+ </p></li><li class="listitem"><p>
+ <code class="literal">EXTERNAL</code> allows out-of-line storage but not
+ compression. Use of <code class="literal">EXTERNAL</code> will
+ make substring operations on wide <code class="type">text</code> and
+ <code class="type">bytea</code> columns faster (at the penalty of increased storage
+ space) because these operations are optimized to fetch only the
+ required parts of the out-of-line value when it is not compressed.
+ </p></li><li class="listitem"><p>
+ <code class="literal">MAIN</code> allows compression but not out-of-line
+ storage. (Actually, out-of-line storage will still be performed
+ for such columns, but only as a last resort when there is no other
+ way to make the row small enough to fit on a page.)
+ </p></li></ul></div><p>
+
+Each <acronym class="acronym">TOAST</acronym>-able data type specifies a default strategy for columns
+of that data type, but the strategy for a given table column can be altered
+with <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ... SET STORAGE</code></a>.
+</p><p>
+<code class="symbol">TOAST_TUPLE_TARGET</code> can be adjusted for each table using
+<a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ... SET (toast_tuple_target = N)</code></a>
+</p><p>
+This scheme has a number of advantages compared to a more straightforward
+approach such as allowing row values to span pages. Assuming that queries are
+usually qualified by comparisons against relatively small key values, most of
+the work of the executor will be done using the main row entry. The big values
+of <acronym class="acronym">TOAST</acronym>ed attributes will only be pulled out (if selected at all)
+at the time the result set is sent to the client. Thus, the main table is much
+smaller and more of its rows fit in the shared buffer cache than would be the
+case without any out-of-line storage. Sort sets shrink also, and sorts will
+more often be done entirely in memory. A little test showed that a table
+containing typical HTML pages and their URLs was stored in about half of the
+raw data size including the <acronym class="acronym">TOAST</acronym> table, and that the main table
+contained only about 10% of the entire data (the URLs and some small HTML
+pages). There was no run time difference compared to an un-<acronym class="acronym">TOAST</acronym>ed
+comparison table, in which all the HTML pages were cut down to 7 kB to fit.
+</p></div><div class="sect2" id="STORAGE-TOAST-INMEMORY"><div class="titlepage"><div><div><h3 class="title">73.2.2. Out-of-Line, In-Memory TOAST Storage</h3></div></div></div><p>
+<acronym class="acronym">TOAST</acronym> pointers can point to data that is not on disk, but is
+elsewhere in the memory of the current server process. Such pointers
+obviously cannot be long-lived, but they are nonetheless useful. There
+are currently two sub-cases:
+pointers to <em class="firstterm">indirect</em> data and
+pointers to <em class="firstterm">expanded</em> data.
+</p><p>
+Indirect <acronym class="acronym">TOAST</acronym> pointers simply point at a non-indirect varlena
+value stored somewhere in memory. This case was originally created merely
+as a proof of concept, but it is currently used during logical decoding to
+avoid possibly having to create physical tuples exceeding 1 GB (as pulling
+all out-of-line field values into the tuple might do). The case is of
+limited use since the creator of the pointer datum is entirely responsible
+that the referenced data survives for as long as the pointer could exist,
+and there is no infrastructure to help with this.
+</p><p>
+Expanded <acronym class="acronym">TOAST</acronym> pointers are useful for complex data types
+whose on-disk representation is not especially suited for computational
+purposes. As an example, the standard varlena representation of a
+<span class="productname">PostgreSQL</span> array includes dimensionality information, a
+nulls bitmap if there are any null elements, then the values of all the
+elements in order. When the element type itself is variable-length, the
+only way to find the <em class="replaceable"><code>N</code></em>'th element is to scan through all the
+preceding elements. This representation is appropriate for on-disk storage
+because of its compactness, but for computations with the array it's much
+nicer to have an <span class="quote">“<span class="quote">expanded</span>”</span> or <span class="quote">“<span class="quote">deconstructed</span>”</span>
+representation in which all the element starting locations have been
+identified. The <acronym class="acronym">TOAST</acronym> pointer mechanism supports this need by
+allowing a pass-by-reference Datum to point to either a standard varlena
+value (the on-disk representation) or a <acronym class="acronym">TOAST</acronym> pointer that
+points to an expanded representation somewhere in memory. The details of
+this expanded representation are up to the data type, though it must have
+a standard header and meet the other API requirements given
+in <code class="filename">src/include/utils/expandeddatum.h</code>. C-level functions
+working with the data type can choose to handle either representation.
+Functions that do not know about the expanded representation, but simply
+apply <code class="function">PG_DETOAST_DATUM</code> to their inputs, will automatically
+receive the traditional varlena representation; so support for an expanded
+representation can be introduced incrementally, one function at a time.
+</p><p>
+<acronym class="acronym">TOAST</acronym> pointers to expanded values are further broken down
+into <em class="firstterm">read-write</em> and <em class="firstterm">read-only</em> pointers.
+The pointed-to representation is the same either way, but a function that
+receives a read-write pointer is allowed to modify the referenced value
+in-place, whereas one that receives a read-only pointer must not; it must
+first create a copy if it wants to make a modified version of the value.
+This distinction and some associated conventions make it possible to avoid
+unnecessary copying of expanded values during query execution.
+</p><p>
+For all types of in-memory <acronym class="acronym">TOAST</acronym> pointer, the <acronym class="acronym">TOAST</acronym>
+management code ensures that no such pointer datum can accidentally get
+stored on disk. In-memory <acronym class="acronym">TOAST</acronym> pointers are automatically
+expanded to normal in-line varlena values before storage — and then
+possibly converted to on-disk <acronym class="acronym">TOAST</acronym> pointers, if the containing
+tuple would otherwise be too big.
+</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-file-layout.html" title="73.1. Database File Layout">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-fsm.html" title="73.3. Free Space Map">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.1. Database File Layout </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.3. Free Space Map</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage-vm.html b/doc/src/sgml/html/storage-vm.html
new file mode 100644
index 0000000..706d2ac
--- /dev/null
+++ b/doc/src/sgml/html/storage-vm.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>73.4. Visibility Map</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="storage-fsm.html" title="73.3. Free Space Map" /><link rel="next" href="storage-init.html" title="73.5. The Initialization Fork" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">73.4. Visibility Map</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="storage-fsm.html" title="73.3. Free Space Map">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><th width="60%" align="center">Chapter 73. Database Physical Storage</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-init.html" title="73.5. The Initialization Fork">Next</a></td></tr></table><hr /></div><div class="sect1" id="STORAGE-VM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">73.4. Visibility Map</h2></div></div></div><a id="id-1.10.24.6.2" class="indexterm"></a><a id="id-1.10.24.6.3" class="indexterm"></a><p>
+Each heap relation has a Visibility Map
+(VM) to keep track of which pages contain only tuples that are known to be
+visible to all active transactions; it also keeps track of which pages contain
+only frozen tuples. It's stored
+alongside the main relation data in a separate relation fork, named after the
+filenode number of the relation, plus a <code class="literal">_vm</code> suffix. For example,
+if the filenode of a relation is 12345, the VM is stored in a file called
+<code class="filename">12345_vm</code>, in the same directory as the main relation file.
+Note that indexes do not have VMs.
+</p><p>
+The visibility map stores two bits per heap page. The first bit, if set,
+indicates that the page is all-visible, or in other words that the page does
+not contain any tuples that need to be vacuumed.
+This information can also be used
+by <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes"><em class="firstterm">index-only
+scans</em></a> to answer queries using only the index tuple.
+The second bit, if set, means that all tuples on the page have been frozen.
+That means that even an anti-wraparound vacuum need not revisit the page.
+</p><p>
+The map is conservative in the sense that we make sure that whenever a bit is
+set, we know the condition is true, but if a bit is not set, it might or
+might not be true. Visibility map bits are only set by vacuum, but are
+cleared by any data-modifying operations on a page.
+</p><p>
+The <a class="xref" href="pgvisibility.html" title="F.36. pg_visibility">pg_visibility</a> module can be used to examine the
+information stored in the visibility map.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="storage-fsm.html" title="73.3. Free Space Map">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="storage.html" title="Chapter 73. Database Physical Storage">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-init.html" title="73.5. The Initialization Fork">Next</a></td></tr><tr><td width="40%" align="left" valign="top">73.3. Free Space Map </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.5. The Initialization Fork</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/storage.html b/doc/src/sgml/html/storage.html
new file mode 100644
index 0000000..cb94e5d
--- /dev/null
+++ b/doc/src/sgml/html/storage.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 73. Database Physical Storage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="hash-implementation.html" title="72.2. Implementation" /><link rel="next" href="storage-file-layout.html" title="73.1. Database File Layout" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 73. Database Physical Storage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="hash-implementation.html" title="72.2. Implementation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="storage-file-layout.html" title="73.1. Database File Layout">Next</a></td></tr></table><hr /></div><div class="chapter" id="STORAGE"><div class="titlepage"><div><div><h2 class="title">Chapter 73. Database Physical Storage</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="storage-file-layout.html">73.1. Database File Layout</a></span></dt><dt><span class="sect1"><a href="storage-toast.html">73.2. TOAST</a></span></dt><dd><dl><dt><span class="sect2"><a href="storage-toast.html#STORAGE-TOAST-ONDISK">73.2.1. Out-of-Line, On-Disk TOAST Storage</a></span></dt><dt><span class="sect2"><a href="storage-toast.html#STORAGE-TOAST-INMEMORY">73.2.2. Out-of-Line, In-Memory TOAST Storage</a></span></dt></dl></dd><dt><span class="sect1"><a href="storage-fsm.html">73.3. Free Space Map</a></span></dt><dt><span class="sect1"><a href="storage-vm.html">73.4. Visibility Map</a></span></dt><dt><span class="sect1"><a href="storage-init.html">73.5. The Initialization Fork</a></span></dt><dt><span class="sect1"><a href="storage-page-layout.html">73.6. Database Page Layout</a></span></dt><dd><dl><dt><span class="sect2"><a href="storage-page-layout.html#STORAGE-TUPLE-LAYOUT">73.6.1. Table Row Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="storage-hot.html">73.7. Heap-Only Tuples (<acronym class="acronym">HOT</acronym>)</a></span></dt></dl></div><p>
+This chapter provides an overview of the physical storage format used by
+<span class="productname">PostgreSQL</span> databases.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="hash-implementation.html" title="72.2. Implementation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="storage-file-layout.html" title="73.1. Database File Layout">Next</a></td></tr><tr><td width="40%" align="left" valign="top">72.2. Implementation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 73.1. Database File Layout</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/stylesheet.css b/doc/src/sgml/html/stylesheet.css
new file mode 100644
index 0000000..6410a47
--- /dev/null
+++ b/doc/src/sgml/html/stylesheet.css
@@ -0,0 +1,165 @@
+/* doc/src/sgml/stylesheet.css */
+
+/* color scheme similar to www.postgresql.org */
+
+body {
+ color: #000000;
+ background: #FFFFFF;
+ font-family: verdana, sans-serif;
+}
+
+a:link { color:#0066A2; }
+a:visited { color:#004E66; }
+a:active { color:#0066A2; }
+a:hover { color:#000000; }
+
+h1 {
+ font-size: 1.4em;
+ font-weight: bold;
+ margin-top: 0em;
+ margin-bottom: 0em;
+ color: #EC5800;
+}
+
+h2 {
+ font-size: 1.2em;
+ margin: 1.2em 0em 1.2em 0em;
+ font-weight: bold;
+ color: #666;
+}
+
+.titlepage h2.title,
+.refnamediv h2 {
+ color: #EC5800;
+}
+
+h3 {
+ font-size: 1.1em;
+ margin: 1.2em 0em 1.2em 0em;
+ font-weight: bold;
+ color: #666;
+}
+
+h4 {
+ font-size: 0.95em;
+ margin: 1.2em 0em 1.2em 0em;
+ font-weight: normal;
+ color: #666;
+}
+
+h5 {
+ font-size: 0.9em;
+ margin: 1.2em 0em 1.2em 0em;
+ font-weight: normal;
+}
+
+h6 {
+ font-size: 0.85em;
+ margin: 1.2em 0em 1.2em 0em;
+ font-weight: normal;
+}
+
+/* center some titles */
+
+.book .title, .book .corpauthor, .book .copyright {
+ text-align: center;
+}
+
+/* decoration for formal examples */
+
+div.example {
+ padding-left: 15px;
+ border-style: solid;
+ border-width: 0px;
+ border-left-width: 2px;
+ border-color: black;
+ margin: 0.5ex;
+}
+
+/* formatting for entries in tables of functions: indent all but first line */
+
+th.func_table_entry p,
+td.func_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+ text-align: left;
+}
+
+p.func_signature {
+ text-indent: -3.5em;
+}
+
+td.func_table_entry pre.programlisting {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+}
+
+/* formatting for entries in tables of catalog/view columns */
+
+th.catalog_table_entry p,
+td.catalog_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+ text-align: left;
+}
+
+th.catalog_table_entry p.column_definition {
+ text-indent: -3.5em;
+ word-spacing: 0.25em;
+}
+
+td.catalog_table_entry p.column_definition {
+ text-indent: -3.5em;
+}
+
+p.column_definition code.type {
+ padding-left: 0.25em;
+ padding-right: 0.25em;
+}
+
+td.catalog_table_entry pre.programlisting {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+}
+
+/* Put these here instead of inside the HTML (see unsetting of
+ admon.style in XSL) so that the web site stylesheet can set its own
+ style. */
+
+.tip,
+.note,
+.important,
+.caution,
+.warning {
+ margin-left: 0.5in;
+ margin-right: 0.5in;
+}
+
+/* miscellaneous */
+
+pre.literallayout, .screen, .synopsis, .programlisting {
+ margin-left: 4ex;
+}
+
+ul.itemizedlist {
+ margin-left: 2.5rem;
+}
+
+.comment { color: red; }
+
+var { font-family: monospace; font-style: italic; }
+/* Konqueror's standard style for ACRONYM is italic. */
+acronym { font-style: inherit; }
+
+.option { white-space: nowrap; }
+
+/* make images not too wide on larger screens */
+@media (min-width: 800px) {
+ .mediaobject {
+ width: 75%;
+ }
+}
diff --git a/doc/src/sgml/html/supported-platforms.html b/doc/src/sgml/html/supported-platforms.html
new file mode 100644
index 0000000..e42c106
--- /dev/null
+++ b/doc/src/sgml/html/supported-platforms.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>17.6. Supported Platforms</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="install-post.html" title="17.5. Post-Installation Setup" /><link rel="next" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">17.6. Supported Platforms</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="install-post.html" title="17.5. Post-Installation Setup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><th width="60%" align="center">Chapter 17. Installation from Source Code</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes">Next</a></td></tr></table><hr /></div><div class="sect1" id="SUPPORTED-PLATFORMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">17.6. Supported Platforms</h2></div></div></div><p>
+ A platform (that is, a CPU architecture and operating system combination)
+ is considered supported by the <span class="productname">PostgreSQL</span> development
+ community if the code contains provisions to work on that platform and
+ it has recently been verified to build and pass its regression tests
+ on that platform. Currently, most testing of platform compatibility
+ is done automatically by test machines in the
+ <a class="ulink" href="https://buildfarm.postgresql.org/" target="_top">PostgreSQL Build Farm</a>.
+ If you are interested in using <span class="productname">PostgreSQL</span> on a platform
+ that is not represented in the build farm, but on which the code works
+ or can be made to work, you are strongly encouraged to set up a build
+ farm member machine so that continued compatibility can be assured.
+ </p><p>
+ In general, <span class="productname">PostgreSQL</span> can be expected to work on
+ these CPU architectures: x86, x86_64, IA64, PowerPC,
+ PowerPC 64, S/390, S/390x, Sparc, Sparc 64, ARM, MIPS, MIPSEL,
+ and PA-RISC. Code support exists for M68K, M32R, and VAX, but these
+ architectures are not known to have been tested recently. It is often
+ possible to build on an unsupported CPU type by configuring with
+ <code class="option">--disable-spinlocks</code>, but performance will be poor.
+ </p><p>
+ <span class="productname">PostgreSQL</span> can be expected to work on these operating
+ systems: Linux (all recent distributions), Windows (XP and later),
+ FreeBSD, OpenBSD, NetBSD, macOS, AIX, HP/UX, and Solaris.
+ 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
+ <a class="xref" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes">Section 17.7</a> below to see if
+ there is information
+ specific to your operating system, particularly if using an older system.
+ </p><p>
+ If you have installation problems on a platform that is known
+ to be supported according to recent build farm results, please report
+ it to <code class="email">&lt;<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>&gt;</code>. If you are interested
+ in porting <span class="productname">PostgreSQL</span> to a new platform,
+ <code class="email">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</code> is the appropriate place
+ to discuss that.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-post.html" title="17.5. Post-Installation Setup">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="installation.html" title="Chapter 17. Installation from Source Code">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="installation-platform-notes.html" title="17.7. Platform-Specific Notes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">17.5. Post-Installation Setup </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 17.7. Platform-Specific Notes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/system-catalog-declarations.html b/doc/src/sgml/html/system-catalog-declarations.html
new file mode 100644
index 0000000..bd8b6b4
--- /dev/null
+++ b/doc/src/sgml/html/system-catalog-declarations.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.1. System Catalog Declaration Rules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents" /><link rel="next" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.1. System Catalog Declaration Rules</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="SYSTEM-CATALOG-DECLARATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.1. System Catalog Declaration Rules</h2></div></div></div><p>
+ The key part of a catalog header file is a C structure definition
+ describing the layout of each row of the catalog. This begins with
+ a <code class="literal">CATALOG</code> macro, which so far as the C compiler is
+ concerned is just shorthand for <code class="literal">typedef struct
+ FormData_<em class="replaceable"><code>catalogname</code></em></code>.
+ Each field in the struct gives rise to a catalog column.
+ Fields can be annotated using the BKI property macros described
+ in <code class="filename">genbki.h</code>, for example to define a default value
+ for a field or mark it as nullable or not nullable.
+ The <code class="literal">CATALOG</code> line can also be annotated, with some
+ other BKI property macros described in <code class="filename">genbki.h</code>, to
+ define other properties of the catalog as a whole, such as whether
+ it is a shared relation.
+ </p><p>
+ The system catalog cache code (and most catalog-munging code in general)
+ assumes that the fixed-length portions of all system catalog tuples are
+ in fact present, because it maps this C struct declaration onto them.
+ Thus, all variable-length fields and nullable fields must be placed at
+ the end, and they cannot be accessed as struct fields.
+ For example, if you tried to
+ set <code class="structname">pg_type</code>.<code class="structfield">typrelid</code>
+ to be NULL, it would fail when some piece of code tried to reference
+ <code class="literal">typetup-&gt;typrelid</code> (or worse,
+ <code class="literal">typetup-&gt;typelem</code>, because that follows
+ <code class="structfield">typrelid</code>). This would result in
+ random errors or even segmentation violations.
+ </p><p>
+ As a partial guard against this type of error, variable-length or
+ nullable fields should not be made directly visible to the C compiler.
+ This is accomplished by wrapping them in <code class="literal">#ifdef
+ CATALOG_VARLEN</code> ... <code class="literal">#endif</code> (where
+ <code class="literal">CATALOG_VARLEN</code> is a symbol that is never defined).
+ This prevents C code from carelessly trying to access fields that might
+ not be there or might be at some other offset.
+ As an independent guard against creating incorrect rows, we
+ require all columns that should be non-nullable to be marked so
+ in <code class="structname">pg_attribute</code>. The bootstrap code will
+ automatically mark catalog columns as <code class="literal">NOT NULL</code>
+ if they are fixed-width and are not preceded by any nullable or
+ variable-width column.
+ Where this rule is inadequate, you can force correct marking by using
+ <code class="literal">BKI_FORCE_NOT_NULL</code>
+ and <code class="literal">BKI_FORCE_NULL</code> annotations as needed.
+ </p><p>
+ Frontend code should not include any <code class="filename">pg_xxx.h</code>
+ catalog header file, as these files may contain C code that won't compile
+ outside the backend. (Typically, that happens because these files also
+ contain declarations for functions
+ in <code class="filename">src/backend/catalog/</code> files.)
+ Instead, frontend code may include the corresponding
+ generated <code class="filename">pg_xxx_d.h</code> header, which will contain
+ OID <code class="literal">#define</code>s and any other data that might be of use
+ on the client side. If you want macros or other code in a catalog header
+ to be visible to frontend code, write <code class="literal">#ifdef
+ EXPOSE_TO_CLIENT_CODE</code> ... <code class="literal">#endif</code> around that
+ section to instruct <code class="filename">genbki.pl</code> to copy that section
+ to the <code class="filename">pg_xxx_d.h</code> header.
+ </p><p>
+ A few of the catalogs are so fundamental that they can't even be created
+ by the <acronym class="acronym">BKI</acronym> <code class="literal">create</code> command that's
+ used for most catalogs, because that command needs to write information
+ into these catalogs to describe the new catalog. These are
+ called <em class="firstterm">bootstrap</em> catalogs, and defining one takes
+ a lot of extra work: you have to manually prepare appropriate entries for
+ them in the pre-loaded contents of <code class="structname">pg_class</code>
+ and <code class="structname">pg_type</code>, and those entries will need to be
+ updated for subsequent changes to the catalog's structure.
+ (Bootstrap catalogs also need pre-loaded entries
+ in <code class="structname">pg_attribute</code>, but
+ fortunately <code class="filename">genbki.pl</code> handles that chore nowadays.)
+ Avoid making new catalogs be bootstrap catalogs if at all possible.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="system-catalog-initial-data.html" title="74.2. System Catalog Initial Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 74. System Catalog Declarations and Initial Contents </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.2. System Catalog Initial Data</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/system-catalog-initial-data.html b/doc/src/sgml/html/system-catalog-initial-data.html
new file mode 100644
index 0000000..4daa189
--- /dev/null
+++ b/doc/src/sgml/html/system-catalog-initial-data.html
@@ -0,0 +1,404 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>74.2. System Catalog Initial Data</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules" /><link rel="next" href="bki-format.html" title="74.3. BKI File Format" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">74.2. System Catalog Initial Data</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 74. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="bki-format.html" title="74.3. BKI File Format">Next</a></td></tr></table><hr /></div><div class="sect1" id="SYSTEM-CATALOG-INITIAL-DATA"><div class="titlepage"><div><div><h2 class="title" style="clear: both">74.2. System Catalog Initial Data</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-INITIAL-DATA-FORMAT">74.2.1. Data File Format</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-ASSIGNMENT">74.2.2. OID Assignment</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-REFERENCES">74.2.3. OID Reference Lookup</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-AUTO-ARRAY-TYPES">74.2.4. Automatic Creation of Array Types</a></span></dt><dt><span class="sect2"><a href="system-catalog-initial-data.html#SYSTEM-CATALOG-RECIPES">74.2.5. Recipes for Editing Data Files</a></span></dt></dl></div><p>
+ Each catalog that has any manually-created initial data (some do not)
+ has a corresponding <code class="literal">.dat</code> file that contains its
+ initial data in an editable format.
+ </p><div class="sect2" id="SYSTEM-CATALOG-INITIAL-DATA-FORMAT"><div class="titlepage"><div><div><h3 class="title">74.2.1. Data File Format</h3></div></div></div><p>
+ Each <code class="literal">.dat</code> file contains Perl data structure literals
+ that are simply eval'd to produce an in-memory data structure consisting
+ of an array of hash references, one per catalog row.
+ A slightly modified excerpt from <code class="filename">pg_database.dat</code>
+ will demonstrate the key features:
+ </p><pre class="programlisting">
+[
+
+# A comment could appear here.
+{ oid =&gt; '1', oid_symbol =&gt; 'Template1DbOid',
+ descr =&gt; 'database\'s default template',
+ datname =&gt; 'template1', encoding =&gt; 'ENCODING',
+ datlocprovider =&gt; 'LOCALE_PROVIDER', datistemplate =&gt; 't',
+ datallowconn =&gt; 't', datconnlimit =&gt; '-1', datfrozenxid =&gt; '0',
+ datminmxid =&gt; '1', dattablespace =&gt; 'pg_default', datcollate =&gt; 'LC_COLLATE',
+ datctype =&gt; 'LC_CTYPE', daticulocale =&gt; 'ICU_LOCALE', datacl =&gt; '_null_' },
+
+]
+</pre><p>
+ Points to note:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The overall file layout is: open square bracket, one or more sets of
+ curly braces each of which represents a catalog row, close square
+ bracket. Write a comma after each closing curly brace.
+ </p></li><li class="listitem"><p>
+ Within each catalog row, write comma-separated
+ <em class="replaceable"><code>key</code></em> <code class="literal">=&gt;</code>
+ <em class="replaceable"><code>value</code></em> pairs. The
+ allowed <em class="replaceable"><code>key</code></em>s are the names of the catalog's
+ columns, plus the metadata keys <code class="literal">oid</code>,
+ <code class="literal">oid_symbol</code>,
+ <code class="literal">array_type_oid</code>, and <code class="literal">descr</code>.
+ (The use of <code class="literal">oid</code> and <code class="literal">oid_symbol</code>
+ is described in <a class="xref" href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-ASSIGNMENT" title="74.2.2. OID Assignment">Section 74.2.2</a> below,
+ while <code class="literal">array_type_oid</code> is described in
+ <a class="xref" href="system-catalog-initial-data.html#SYSTEM-CATALOG-AUTO-ARRAY-TYPES" title="74.2.4. Automatic Creation of Array Types">Section 74.2.4</a>.
+ <code class="literal">descr</code> supplies a description string for the object,
+ which will be inserted into <code class="structname">pg_description</code>
+ or <code class="structname">pg_shdescription</code> as appropriate.)
+ While the metadata keys are optional, the catalog's defined columns
+ must all be provided, except when the catalog's <code class="literal">.h</code>
+ file specifies a default value for the column.
+ (In the example above, the <code class="structfield">datdba</code> field has
+ been omitted because <code class="filename">pg_database.h</code> supplies a
+ suitable default value for it.)
+ </p></li><li class="listitem"><p>
+ All values must be single-quoted. Escape single quotes used within a
+ value with a backslash. Backslashes meant as data can, but need not,
+ be doubled; this follows Perl's rules for simple quoted literals.
+ Note that backslashes appearing as data will be treated as escapes by
+ the bootstrap scanner, according to the same rules as for escape string
+ constants (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE" title="4.1.2.2. String Constants with C-Style Escapes">Section 4.1.2.2</a>); for
+ example <code class="literal">\t</code> converts to a tab character. If you
+ actually want a backslash in the final value, you will need to write
+ four of them: Perl strips two, leaving <code class="literal">\\</code> for the
+ bootstrap scanner to see.
+ </p></li><li class="listitem"><p>
+ Null values are represented by <code class="literal">_null_</code>.
+ (Note that there is no way to create a value that is just that
+ string.)
+ </p></li><li class="listitem"><p>
+ Comments are preceded by <code class="literal">#</code>, and must be on their
+ own lines.
+ </p></li><li class="listitem"><p>
+ Field values that are OIDs of other catalog entries should be
+ represented by symbolic names rather than actual numeric OIDs.
+ (In the example above, <code class="structfield">dattablespace</code>
+ contains such a reference.)
+ This is described in <a class="xref" href="system-catalog-initial-data.html#SYSTEM-CATALOG-OID-REFERENCES" title="74.2.3. OID Reference Lookup">Section 74.2.3</a>
+ below.
+ </p></li><li class="listitem"><p>
+ Since hashes are unordered data structures, field order and line
+ layout aren't semantically significant. However, to maintain a
+ consistent appearance, we set a few rules that are applied by the
+ formatting script <code class="filename">reformat_dat_file.pl</code>:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
+ Within each pair of curly braces, the metadata
+ fields <code class="literal">oid</code>, <code class="literal">oid_symbol</code>,
+ <code class="literal">array_type_oid</code>, and <code class="literal">descr</code>
+ (if present) come first, in that order, then the catalog's own
+ fields appear in their defined order.
+ </p></li><li class="listitem"><p>
+ Newlines are inserted between fields as needed to limit line length
+ to 80 characters, if possible. A newline is also inserted between
+ the metadata fields and the regular fields.
+ </p></li><li class="listitem"><p>
+ If the catalog's <code class="literal">.h</code> file specifies a default
+ value for a column, and a data entry has that same
+ value, <code class="filename">reformat_dat_file.pl</code> will omit it from
+ the data file. This keeps the data representation compact.
+ </p></li><li class="listitem"><p>
+ <code class="filename">reformat_dat_file.pl</code> preserves blank lines
+ and comment lines as-is.
+ </p></li></ul></div><p>
+
+ It's recommended to run <code class="filename">reformat_dat_file.pl</code>
+ before submitting catalog data patches. For convenience, you can
+ simply change to <code class="filename">src/include/catalog/</code> and
+ run <code class="literal">make reformat-dat-files</code>.
+ </p></li><li class="listitem"><p>
+ If you want to add a new method of making the data representation
+ smaller, you must implement it
+ in <code class="filename">reformat_dat_file.pl</code> and also
+ teach <code class="function">Catalog::ParseData()</code> how to expand the
+ data back into the full representation.
+ </p></li></ul></div></div><div class="sect2" id="SYSTEM-CATALOG-OID-ASSIGNMENT"><div class="titlepage"><div><div><h3 class="title">74.2.2. OID Assignment</h3></div></div></div><p>
+ A catalog row appearing in the initial data can be given a
+ manually-assigned OID by writing an <code class="literal">oid
+ =&gt; <em class="replaceable"><code>nnnn</code></em></code> metadata field.
+ Furthermore, if an OID is assigned, a C macro for that OID can be
+ created by writing an <code class="literal">oid_symbol
+ =&gt; <em class="replaceable"><code>name</code></em></code> metadata field.
+ </p><p>
+ Pre-loaded catalog rows must have preassigned OIDs if there are OID
+ references to them in other pre-loaded rows. A preassigned OID is
+ also needed if the row's OID must be referenced from C code.
+ If neither case applies, the <code class="literal">oid</code> metadata field can
+ be omitted, in which case the bootstrap code assigns an OID
+ automatically.
+ In practice we usually preassign OIDs for all or none of the pre-loaded
+ rows in a given catalog, even if only some of them are actually
+ cross-referenced.
+ </p><p>
+ Writing the actual numeric value of any OID in C code is considered
+ very bad form; always use a macro, instead. Direct references
+ to <code class="structname">pg_proc</code> OIDs are common enough that there's
+ a special mechanism to create the necessary macros automatically;
+ see <code class="filename">src/backend/utils/Gen_fmgrtab.pl</code>. Similarly
+ — but, for historical reasons, not done the same way —
+ there's an automatic method for creating macros
+ for <code class="structname">pg_type</code>
+ OIDs. <code class="literal">oid_symbol</code> entries are therefore not
+ necessary in those two catalogs. Likewise, macros for
+ the <code class="structname">pg_class</code> OIDs of system catalogs and
+ indexes are set up automatically. For all other system catalogs, you
+ have to manually specify any macros you need
+ via <code class="literal">oid_symbol</code> entries.
+ </p><p>
+ To find an available OID for a new pre-loaded row, run the
+ script <code class="filename">src/include/catalog/unused_oids</code>.
+ It prints inclusive ranges of unused OIDs (e.g., the output
+ line <code class="literal">45-900</code> means OIDs 45 through 900 have not been
+ allocated yet). Currently, OIDs 1–9999 are reserved for manual
+ assignment; the <code class="filename">unused_oids</code> script simply looks
+ through the catalog headers and <code class="filename">.dat</code> files
+ to see which ones do not appear. You can also use
+ the <code class="filename">duplicate_oids</code> script to check for mistakes.
+ (<code class="filename">genbki.pl</code> will assign OIDs for any rows that
+ didn't get one hand-assigned to them, and it will also detect duplicate
+ OIDs at compile time.)
+ </p><p>
+ When choosing OIDs for a patch that is not expected to be committed
+ immediately, best practice is to use a group of more-or-less
+ consecutive OIDs starting with some random choice in the range
+ 8000—9999. This minimizes the risk of OID collisions with other
+ patches being developed concurrently. To keep the 8000—9999
+ range free for development purposes, after a patch has been committed
+ to the master git repository its OIDs should be renumbered into
+ available space below that range. Typically, this will be done
+ near the end of each development cycle, moving all OIDs consumed by
+ patches committed in that cycle at the same time. The script
+ <code class="filename">renumber_oids.pl</code> can be used for this purpose.
+ If an uncommitted patch is found to have OID conflicts with some
+ recently-committed patch, <code class="filename">renumber_oids.pl</code> may
+ also be useful for recovering from that situation.
+ </p><p>
+ Because of this convention of possibly renumbering OIDs assigned by
+ patches, the OIDs assigned by a patch should not be considered stable
+ until the patch has been included in an official release. We do not
+ change manually-assigned object OIDs once released, however, as that
+ would create assorted compatibility problems.
+ </p><p>
+ If <code class="filename">genbki.pl</code> needs to assign an OID to a catalog
+ entry that does not have a manually-assigned OID, it will use a value in
+ the range 10000—11999. The server's OID counter is set to 10000
+ at the start of a bootstrap run, so that any objects created on-the-fly
+ during bootstrap processing also receive OIDs in this range. (The
+ usual OID assignment mechanism takes care of preventing any conflicts.)
+ </p><p>
+ Objects with OIDs below <code class="symbol">FirstUnpinnedObjectId</code> (12000)
+ are considered <span class="quote">“<span class="quote">pinned</span>”</span>, preventing them from being
+ deleted. (There are a small number of exceptions, which are
+ hard-wired into <code class="function">IsPinnedObject()</code>.)
+ <span class="application">initdb</span> forces the OID counter up
+ to <code class="symbol">FirstUnpinnedObjectId</code> as soon as it's ready to
+ create unpinned objects. Thus objects created during the later phases
+ of <span class="application">initdb</span>, such as objects created while
+ running the <code class="filename">information_schema.sql</code> script, will
+ not be pinned, while all objects known
+ to <code class="filename">genbki.pl</code> will be.
+ </p><p>
+ OIDs assigned during normal database operation are constrained to be
+ 16384 or higher. This ensures that the range 10000—16383 is free
+ for OIDs assigned automatically by <code class="filename">genbki.pl</code> or
+ during <span class="application">initdb</span>. These
+ automatically-assigned OIDs are not considered stable, and may change
+ from one installation to another.
+ </p></div><div class="sect2" id="SYSTEM-CATALOG-OID-REFERENCES"><div class="titlepage"><div><div><h3 class="title">74.2.3. OID Reference Lookup</h3></div></div></div><p>
+ In principle, cross-references from one initial catalog row to another
+ could be written just by writing the preassigned OID of the referenced
+ row in the referencing field. However, that is against project
+ policy, because it is error-prone, hard to read, and subject to
+ breakage if a newly-assigned OID is renumbered. Therefore
+ <code class="filename">genbki.pl</code> provides mechanisms to write
+ symbolic references instead.
+ The rules are as follows:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Use of symbolic references is enabled in a particular catalog column
+ by attaching <code class="literal">BKI_LOOKUP(<em class="replaceable"><code>lookuprule</code></em>)</code>
+ to the column's definition, where <em class="replaceable"><code>lookuprule</code></em>
+ is the name of the referenced catalog, e.g., <code class="literal">pg_proc</code>.
+ <code class="literal">BKI_LOOKUP</code> can be attached to columns of
+ type <code class="type">Oid</code>, <code class="type">regproc</code>, <code class="type">oidvector</code>,
+ or <code class="type">Oid[]</code>; in the latter two cases it implies performing a
+ lookup on each element of the array.
+ </p></li><li class="listitem"><p>
+ It's also permissible to attach <code class="literal">BKI_LOOKUP(encoding)</code>
+ to integer columns to reference character set encodings, which are
+ not currently represented as catalog OIDs, but have a set of values
+ known to <code class="filename">genbki.pl</code>.
+ </p></li><li class="listitem"><p>
+ In some catalog columns, it's allowed for entries to be zero instead
+ of a valid reference. If this is allowed, write
+ <code class="literal">BKI_LOOKUP_OPT</code> instead
+ of <code class="literal">BKI_LOOKUP</code>. Then you can
+ write <code class="literal">0</code> for an entry. (If the column is
+ declared <code class="type">regproc</code>, you can optionally
+ write <code class="literal">-</code> instead of <code class="literal">0</code>.)
+ Except for this special case, all entries in
+ a <code class="literal">BKI_LOOKUP</code> column must be symbolic references.
+ <code class="filename">genbki.pl</code> will warn about unrecognized names.
+ </p></li><li class="listitem"><p>
+ Most kinds of catalog objects are simply referenced by their names.
+ Note that type names must exactly match the
+ referenced <code class="structname">pg_type</code>
+ entry's <code class="structfield">typname</code>; you do not get to use
+ any aliases such as <code class="literal">integer</code>
+ for <code class="literal">int4</code>.
+ </p></li><li class="listitem"><p>
+ A function can be represented by
+ its <code class="structfield">proname</code>, if that is unique among
+ the <code class="filename">pg_proc.dat</code> entries (this works like regproc
+ input). Otherwise, write it
+ as <em class="replaceable"><code>proname(argtypename,argtypename,...)</code></em>,
+ like regprocedure. The argument type names must be spelled exactly as
+ they are in the <code class="filename">pg_proc.dat</code> entry's
+ <code class="structfield">proargtypes</code> field. Do not insert any
+ spaces.
+ </p></li><li class="listitem"><p>
+ Operators are represented
+ by <em class="replaceable"><code>oprname(lefttype,righttype)</code></em>,
+ writing the type names exactly as they appear in
+ the <code class="filename">pg_operator.dat</code>
+ entry's <code class="structfield">oprleft</code>
+ and <code class="structfield">oprright</code> fields.
+ (Write <code class="literal">0</code> for the omitted operand of a unary
+ operator.)
+ </p></li><li class="listitem"><p>
+ The names of opclasses and opfamilies are only unique within an
+ access method, so they are represented
+ by <em class="replaceable"><code>access_method_name</code></em><code class="literal">/</code><em class="replaceable"><code>object_name</code></em>.
+ </p></li><li class="listitem"><p>
+ In none of these cases is there any provision for
+ schema-qualification; all objects created during bootstrap are
+ expected to be in the <code class="literal">pg_catalog</code> schema.
+ </p></li></ul></div><p>
+ <code class="filename">genbki.pl</code> resolves all symbolic references while it
+ runs, and puts simple numeric OIDs into the emitted BKI file. There is
+ therefore no need for the bootstrap backend to deal with symbolic
+ references.
+ </p><p>
+ It's desirable to mark OID reference columns
+ with <code class="literal">BKI_LOOKUP</code> or <code class="literal">BKI_LOOKUP_OPT</code>
+ even if the catalog has no initial data that requires lookup. This
+ allows <code class="filename">genbki.pl</code> to record the foreign key
+ relationships that exist in the system catalogs. That information is
+ used in the regression tests to check for incorrect entries. See also
+ the macros <code class="literal">DECLARE_FOREIGN_KEY</code>,
+ <code class="literal">DECLARE_FOREIGN_KEY_OPT</code>,
+ <code class="literal">DECLARE_ARRAY_FOREIGN_KEY</code>,
+ and <code class="literal">DECLARE_ARRAY_FOREIGN_KEY_OPT</code>, which are
+ used to declare foreign key relationships that are too complex
+ for <code class="literal">BKI_LOOKUP</code> (typically, multi-column foreign
+ keys).
+ </p></div><div class="sect2" id="SYSTEM-CATALOG-AUTO-ARRAY-TYPES"><div class="titlepage"><div><div><h3 class="title">74.2.4. Automatic Creation of Array Types</h3></div></div></div><p>
+ Most scalar data types should have a corresponding array type (that is,
+ a standard varlena array type whose element type is the scalar type, and
+ which is referenced by the <code class="structfield">typarray</code> field of
+ the scalar type's <code class="structname">pg_type</code>
+ entry). <code class="filename">genbki.pl</code> is able to generate
+ the <code class="structname">pg_type</code> entry for the array type
+ automatically in most cases.
+ </p><p>
+ To use this facility, just write an <code class="literal">array_type_oid
+ =&gt; <em class="replaceable"><code>nnnn</code></em></code> metadata field in the
+ scalar type's <code class="structname">pg_type</code> entry, specifying the OID
+ to use for the array type. You may then omit
+ the <code class="structfield">typarray</code> field, since it will be filled
+ automatically with that OID.
+ </p><p>
+ The generated array type's name is the scalar type's name with an
+ underscore prepended. The array entry's other fields are filled from
+ <code class="literal">BKI_ARRAY_DEFAULT(<em class="replaceable"><code>value</code></em>)</code>
+ annotations in <code class="filename">pg_type.h</code>, or if there isn't one,
+ copied from the scalar type. (There's also a special case
+ for <code class="structfield">typalign</code>.) Then
+ the <code class="structfield">typelem</code>
+ and <code class="structfield">typarray</code> fields of the two entries are
+ set to cross-reference each other.
+ </p></div><div class="sect2" id="SYSTEM-CATALOG-RECIPES"><div class="titlepage"><div><div><h3 class="title">74.2.5. Recipes for Editing Data Files</h3></div></div></div><p>
+ Here are some suggestions about the easiest ways to perform common tasks
+ when updating catalog data files.
+ </p><p><strong>Add a new column with a default to a catalog: </strong>
+ Add the column to the header file with
+ a <code class="literal">BKI_DEFAULT(<em class="replaceable"><code>value</code></em>)</code>
+ annotation. The data file need only be adjusted by adding the field
+ in existing rows where a non-default value is needed.
+ </p><p><strong>Add a default value to an existing column that doesn't have
+ one: </strong>
+ Add a <code class="literal">BKI_DEFAULT</code> annotation to the header file,
+ then run <code class="literal">make reformat-dat-files</code> to remove
+ now-redundant field entries.
+ </p><p><strong>Remove a column, whether it has a default or not: </strong>
+ Remove the column from the header, then run <code class="literal">make
+ reformat-dat-files</code> to remove now-useless field entries.
+ </p><p><strong>Change or remove an existing default value: </strong>
+ You cannot simply change the header file, since that will cause the
+ current data to be interpreted incorrectly. First run <code class="literal">make
+ expand-dat-files</code> to rewrite the data files with all
+ default values inserted explicitly, then change or remove
+ the <code class="literal">BKI_DEFAULT</code> annotation, then run <code class="literal">make
+ reformat-dat-files</code> to remove superfluous fields again.
+ </p><p><strong>Ad-hoc bulk editing: </strong>
+ <code class="filename">reformat_dat_file.pl</code> can be adapted to perform
+ many kinds of bulk changes. Look for its block comments showing where
+ one-off code can be inserted. In the following example, we are going
+ to consolidate two Boolean fields in <code class="structname">pg_proc</code>
+ into a char field:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Add the new column, with a default,
+ to <code class="filename">pg_proc.h</code>:
+</p><pre class="programlisting">
++ /* see PROKIND_ categories below */
++ char prokind BKI_DEFAULT(f);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Create a new script based on <code class="filename">reformat_dat_file.pl</code>
+ to insert appropriate values on-the-fly:
+</p><pre class="programlisting">
+- # At this point we have the full row in memory as a hash
+- # and can do any operations we want. As written, it only
+- # removes default values, but this script can be adapted to
+- # do one-off bulk-editing.
++ # One-off change to migrate to prokind
++ # Default has already been filled in by now, so change to other
++ # values as appropriate
++ if ($values{proisagg} eq 't')
++ {
++ $values{prokind} = 'a';
++ }
++ elsif ($values{proiswindow} eq 't')
++ {
++ $values{prokind} = 'w';
++ }
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Run the new script:
+</p><pre class="programlisting">
+$ cd src/include/catalog
+$ perl rewrite_dat_with_prokind.pl pg_proc.dat
+</pre><p>
+ At this point <code class="filename">pg_proc.dat</code> has all three
+ columns, <code class="structfield">prokind</code>,
+ <code class="structfield">proisagg</code>,
+ and <code class="structfield">proiswindow</code>, though they will appear
+ only in rows where they have non-default values.
+ </p></li><li class="listitem"><p>
+ Remove the old columns from <code class="filename">pg_proc.h</code>:
+</p><pre class="programlisting">
+- /* is it an aggregate? */
+- bool proisagg BKI_DEFAULT(f);
+-
+- /* is it a window function? */
+- bool proiswindow BKI_DEFAULT(f);
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Finally, run <code class="literal">make reformat-dat-files</code> to remove
+ the useless old entries from <code class="filename">pg_proc.dat</code>.
+ </p></li></ol></div><p>
+
+ For further examples of scripts used for bulk editing, see
+ <code class="filename">convert_oid2name.pl</code>
+ and <code class="filename">remove_pg_type_oid_symbols.pl</code> attached to this
+ message:
+ <a class="ulink" href="https://www.postgresql.org/message-id/CAJVSVGVX8gXnPm+Xa=DxR7kFYprcQ1tNcCT5D0O3ShfnM6jehA@mail.gmail.com" target="_top">https://www.postgresql.org/message-id/CAJVSVGVX8gXnPm+Xa=DxR7kFYprcQ1tNcCT5D0O3ShfnM6jehA@mail.gmail.com</a>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="system-catalog-declarations.html" title="74.1. System Catalog Declaration Rules">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 74. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bki-format.html" title="74.3. BKI File Format">Next</a></td></tr><tr><td width="40%" align="left" valign="top">74.1. System Catalog Declaration Rules </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 74.3. <acronym class="acronym">BKI</acronym> File Format</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tableam.html b/doc/src/sgml/html/tableam.html
new file mode 100644
index 0000000..a7bf924
--- /dev/null
+++ b/doc/src/sgml/html/tableam.html
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 63. Table Access Method Interface Definition</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo-biblio.html" title="62.4. Further Reading" /><link rel="next" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 63. Table Access Method Interface Definition</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo-biblio.html" title="62.4. Further Reading">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Next</a></td></tr></table><hr /></div><div class="chapter" id="TABLEAM"><div class="titlepage"><div><div><h2 class="title">Chapter 63. Table Access Method Interface Definition</h2></div></div></div><a id="id-1.10.14.2" class="indexterm"></a><a id="id-1.10.14.3" class="indexterm"></a><p>
+ This chapter explains the interface between the core
+ <span class="productname">PostgreSQL</span> system and <em class="firstterm">table access
+ methods</em>, which manage the storage for tables. The core system
+ knows little about these access methods beyond what is specified here, so
+ it is possible to develop entirely new access method types by writing
+ add-on code.
+ </p><p>
+ Each table access method is described by a row in the <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a> system
+ catalog. The <code class="structname">pg_am</code> entry specifies a name and a
+ <em class="firstterm">handler function</em> for the table access method. These
+ entries can be created and deleted using the <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and <a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a> SQL commands.
+ </p><p>
+ A table access method handler function must be declared to accept a single
+ argument of type <code class="type">internal</code> and to return the pseudo-type
+ <code class="type">table_am_handler</code>. The argument is a dummy value that simply
+ serves to prevent handler functions from being called directly from SQL commands.
+
+ The result of the function must be a pointer to a struct of type
+ <code class="structname">TableAmRoutine</code>, which contains everything that the
+ core code needs to know to make use of the table access method. The return
+ value needs to be of server lifetime, which is typically achieved by
+ defining it as a <code class="literal">static const</code> variable in global
+ scope. The <code class="structname">TableAmRoutine</code> struct, also called the
+ access method's <em class="firstterm">API struct</em>, defines the behavior of
+ the access method using callbacks. These callbacks are pointers to plain C
+ functions and are not visible or callable at the SQL level. All the
+ callbacks and their behavior is defined in the
+ <code class="structname">TableAmRoutine</code> structure (with comments inside the
+ struct defining the requirements for callbacks). Most callbacks have
+ wrapper functions, which are documented from the point of view of a user
+ (rather than an implementor) of the table access method. For details,
+ please refer to the <a class="ulink" href="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=HEAD" target="_top">
+ <code class="filename">src/include/access/tableam.h</code></a> file.
+ </p><p>
+ To implement an access method, an implementor will typically need to
+ implement an AM-specific type of tuple table slot (see
+ <a class="ulink" href="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD" target="_top">
+ <code class="filename">src/include/executor/tuptable.h</code></a>), which allows
+ code outside the access method to hold references to tuples of the AM, and
+ to access the columns of the tuple.
+ </p><p>
+ Currently, the way an AM actually stores data is fairly unconstrained. For
+ example, it's possible, but not required, to use postgres' shared buffer
+ cache. In case it is used, it likely makes sense to use
+ <span class="productname">PostgreSQL</span>'s standard page layout as described in
+ <a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>.
+ </p><p>
+ One fairly large constraint of the table access method API is that,
+ currently, if the AM wants to support modifications and/or indexes, it is
+ necessary for each tuple to have a tuple identifier (<acronym class="acronym">TID</acronym>)
+ consisting of a block number and an item number (see also <a class="xref" href="storage-page-layout.html" title="73.6. Database Page Layout">Section 73.6</a>). It is not strictly necessary that the
+ sub-parts of <acronym class="acronym">TIDs</acronym> have the same meaning they e.g., have
+ for <code class="literal">heap</code>, but if bitmap scan support is desired (it is
+ optional), the block number needs to provide locality.
+ </p><p>
+ For crash safety, an AM can use postgres' <a class="link" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log"><acronym class="acronym">WAL</acronym></a>, or a custom implementation.
+ If <acronym class="acronym">WAL</acronym> is chosen, either <a class="link" href="generic-wal.html" title="Chapter 65. Generic WAL Records">Generic WAL Records</a> can be used,
+ or a <a class="link" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Custom WAL Resource Manager</a> can be
+ implemented.
+ </p><p>
+ To implement transactional support in a manner that allows different table
+ access methods be accessed within a single transaction, it likely is
+ necessary to closely integrate with the machinery in
+ <code class="filename">src/backend/access/transam/xlog.c</code>.
+ </p><p>
+ Any developer of a new <code class="literal">table access method</code> can refer to
+ the existing <code class="literal">heap</code> implementation present in
+ <code class="filename">src/backend/access/heap/heapam_handler.c</code> for details of
+ its implementation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo-biblio.html" title="62.4. Further Reading">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Next</a></td></tr><tr><td width="40%" align="left" valign="top">62.4. Further Reading </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 64. Index Access Method Interface Definition</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tablefunc.html b/doc/src/sgml/html/tablefunc.html
new file mode 100644
index 0000000..676f590
--- /dev/null
+++ b/doc/src/sgml/html/tablefunc.html
@@ -0,0 +1,613 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.43. tablefunc</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sslinfo.html" title="F.42. sslinfo" /><link rel="next" href="tcn.html" title="F.44. tcn" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.43. tablefunc</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sslinfo.html" title="F.42. sslinfo">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tcn.html" title="F.44. tcn">Next</a></td></tr></table><hr /></div><div class="sect1" id="TABLEFUNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.43. tablefunc</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="tablefunc.html#id-1.11.7.52.5">F.43.1. Functions Provided</a></span></dt><dt><span class="sect2"><a href="tablefunc.html#id-1.11.7.52.6">F.43.2. Author</a></span></dt></dl></div><a id="id-1.11.7.52.2" class="indexterm"></a><p>
+ The <code class="filename">tablefunc</code> module includes various functions that return
+ tables (that is, multiple rows). These functions are useful both in their
+ own right and as examples of how to write C functions that return
+ multiple rows.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.52.5"><div class="titlepage"><div><div><h3 class="title">F.43.1. Functions Provided</h3></div></div></div><p>
+ <a class="xref" href="tablefunc.html#TABLEFUNC-FUNCTIONS" title="Table F.30. tablefunc Functions">Table F.30</a> summarizes the functions provided
+ by the <code class="filename">tablefunc</code> module.
+ </p><div class="table" id="TABLEFUNC-FUNCTIONS"><p class="title"><strong>Table F.30. <code class="filename">tablefunc</code> Functions</strong></p><div class="table-contents"><table class="table" summary="tablefunc Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">normal_rand</code> ( <em class="parameter"><code>numvals</code></em> <code class="type">integer</code>, <em class="parameter"><code>mean</code></em> <code class="type">float8</code>, <em class="parameter"><code>stddev</code></em> <code class="type">float8</code> )
+ → <code class="returnvalue">setof float8</code>
+ </p>
+ <p>
+ Produces a set of normally distributed random values.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">crosstab</code> ( <em class="parameter"><code>sql</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Produces a <span class="quote">“<span class="quote">pivot table</span>”</span> containing
+ row names plus <em class="replaceable"><code>N</code></em> value columns, where
+ <em class="replaceable"><code>N</code></em> is determined by the row type specified
+ in the calling query.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">crosstab<em class="replaceable"><code>N</code></em></code> ( <em class="parameter"><code>sql</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof table_crosstab_<em class="replaceable"><code>N</code></em></code>
+ </p>
+ <p>
+ Produces a <span class="quote">“<span class="quote">pivot table</span>”</span> containing
+ row names plus <em class="replaceable"><code>N</code></em> value columns.
+ <code class="function">crosstab2</code>, <code class="function">crosstab3</code>, and
+ <code class="function">crosstab4</code> are predefined, but you can create additional
+ <code class="function">crosstab<em class="replaceable"><code>N</code></em></code> functions as described below.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">crosstab</code> ( <em class="parameter"><code>source_sql</code></em> <code class="type">text</code>, <em class="parameter"><code>category_sql</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Produces a <span class="quote">“<span class="quote">pivot table</span>”</span>
+ with the value columns specified by a second query.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">crosstab</code> ( <em class="parameter"><code>sql</code></em> <code class="type">text</code>, <em class="parameter"><code>N</code></em> <code class="type">integer</code> )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Obsolete version of <code class="function">crosstab(text)</code>.
+ The parameter <em class="parameter"><code>N</code></em> is now ignored, since the
+ number of value columns is always determined by the calling query.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.52.5.3.2.2.6.1.1.1" class="indexterm"></a>
+ <code class="function">connectby</code> ( <em class="parameter"><code>relname</code></em> <code class="type">text</code>, <em class="parameter"><code>keyid_fld</code></em> <code class="type">text</code>, <em class="parameter"><code>parent_keyid_fld</code></em> <code class="type">text</code>
+ [<span class="optional">, <em class="parameter"><code>orderby_fld</code></em> <code class="type">text</code> </span>], <em class="parameter"><code>start_with</code></em> <code class="type">text</code>, <em class="parameter"><code>max_depth</code></em> <code class="type">integer</code>
+ [<span class="optional">, <em class="parameter"><code>branch_delim</code></em> <code class="type">text</code> </span>] )
+ → <code class="returnvalue">setof record</code>
+ </p>
+ <p>
+ Produces a representation of a hierarchical tree structure.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="sect3" id="id-1.11.7.52.5.4"><div class="titlepage"><div><div><h4 class="title">F.43.1.1. <code class="function">normal_rand</code></h4></div></div></div><a id="id-1.11.7.52.5.4.2" class="indexterm"></a><pre class="synopsis">
+normal_rand(int numvals, float8 mean, float8 stddev) returns setof float8
+</pre><p>
+ <code class="function">normal_rand</code> produces a set of normally distributed random
+ values (Gaussian distribution).
+ </p><p>
+ <em class="parameter"><code>numvals</code></em> is the number of values to be returned
+ from the function. <em class="parameter"><code>mean</code></em> is the mean of the normal
+ distribution of values and <em class="parameter"><code>stddev</code></em> is the standard
+ deviation of the normal distribution of values.
+ </p><p>
+ For example, this call requests 1000 values with a mean of 5 and a
+ standard deviation of 3:
+ </p><pre class="screen">
+test=# SELECT * FROM normal_rand(1000, 5, 3);
+ normal_rand
+----------------------
+ 1.56556322244898
+ 9.10040991424657
+ 5.36957140345079
+ -0.369151492880995
+ 0.283600703686639
+ .
+ .
+ .
+ 4.82992125404908
+ 9.71308014517282
+ 2.49639286969028
+(1000 rows)
+</pre></div><div class="sect3" id="id-1.11.7.52.5.5"><div class="titlepage"><div><div><h4 class="title">F.43.1.2. <code class="function">crosstab(text)</code></h4></div></div></div><a id="id-1.11.7.52.5.5.2" class="indexterm"></a><pre class="synopsis">
+crosstab(text sql)
+crosstab(text sql, int N)
+</pre><p>
+ The <code class="function">crosstab</code> function is used to produce <span class="quote">“<span class="quote">pivot</span>”</span>
+ displays, wherein data is listed across the page rather than down.
+ For example, we might have data like
+</p><pre class="programlisting">
+row1 val11
+row1 val12
+row1 val13
+...
+row2 val21
+row2 val22
+row2 val23
+...
+</pre><p>
+ which we wish to display like
+</p><pre class="programlisting">
+row1 val11 val12 val13 ...
+row2 val21 val22 val23 ...
+...
+</pre><p>
+ The <code class="function">crosstab</code> function takes a text parameter that is an SQL
+ query producing raw data formatted in the first way, and produces a table
+ formatted in the second way.
+ </p><p>
+ The <em class="parameter"><code>sql</code></em> parameter is an SQL statement that produces
+ the source set of data. This statement must return one
+ <code class="structfield">row_name</code> column, one
+ <code class="structfield">category</code> column, and one
+ <code class="structfield">value</code> column. <em class="parameter"><code>N</code></em> is an
+ obsolete parameter, ignored if supplied (formerly this had to match the
+ number of output value columns, but now that is determined by the
+ calling query).
+ </p><p>
+ For example, the provided query might produce a set something like:
+</p><pre class="programlisting">
+ row_name cat value
+----------+-------+-------
+ row1 cat1 val1
+ row1 cat2 val2
+ row1 cat3 val3
+ row1 cat4 val4
+ row2 cat1 val5
+ row2 cat2 val6
+ row2 cat3 val7
+ row2 cat4 val8
+</pre><p>
+ </p><p>
+ The <code class="function">crosstab</code> function is declared to return <code class="type">setof
+ record</code>, so the actual names and types of the output columns must be
+ defined in the <code class="literal">FROM</code> clause of the calling <code class="command">SELECT</code>
+ statement, for example:
+</p><pre class="programlisting">
+SELECT * FROM crosstab('...') AS ct(row_name text, category_1 text, category_2 text);
+</pre><p>
+ This example produces a set something like:
+</p><pre class="programlisting">
+ &lt;== value columns ==&gt;
+ row_name category_1 category_2
+----------+------------+------------
+ row1 val1 val2
+ row2 val5 val6
+</pre><p>
+ </p><p>
+ The <code class="literal">FROM</code> clause must define the output as one
+ <code class="structfield">row_name</code> column (of the same data type as the first result
+ column of the SQL query) followed by N <code class="structfield">value</code> columns
+ (all of the same data type as the third result column of the SQL query).
+ You can set up as many output value columns as you wish. The names of the
+ output columns are up to you.
+ </p><p>
+ The <code class="function">crosstab</code> function produces one output row for each
+ consecutive group of input rows with the same
+ <code class="structfield">row_name</code> value. It fills the output
+ <code class="structfield">value</code> columns, left to right, with the
+ <code class="structfield">value</code> fields from these rows. If there
+ are fewer rows in a group than there are output <code class="structfield">value</code>
+ columns, the extra output columns are filled with nulls; if there are
+ more rows, the extra input rows are skipped.
+ </p><p>
+ In practice the SQL query should always specify <code class="literal">ORDER BY 1,2</code>
+ to ensure that the input rows are properly ordered, that is, values with
+ the same <code class="structfield">row_name</code> are brought together and
+ correctly ordered within the row. Notice that <code class="function">crosstab</code>
+ itself does not pay any attention to the second column of the query
+ result; it's just there to be ordered by, to control the order in which
+ the third-column values appear across the page.
+ </p><p>
+ Here is a complete example:
+</p><pre class="programlisting">
+CREATE TABLE ct(id SERIAL, rowid TEXT, attribute TEXT, value TEXT);
+INSERT INTO ct(rowid, attribute, value) VALUES('test1','att1','val1');
+INSERT INTO ct(rowid, attribute, value) VALUES('test1','att2','val2');
+INSERT INTO ct(rowid, attribute, value) VALUES('test1','att3','val3');
+INSERT INTO ct(rowid, attribute, value) VALUES('test1','att4','val4');
+INSERT INTO ct(rowid, attribute, value) VALUES('test2','att1','val5');
+INSERT INTO ct(rowid, attribute, value) VALUES('test2','att2','val6');
+INSERT INTO ct(rowid, attribute, value) VALUES('test2','att3','val7');
+INSERT INTO ct(rowid, attribute, value) VALUES('test2','att4','val8');
+
+SELECT *
+FROM crosstab(
+ 'select rowid, attribute, value
+ from ct
+ where attribute = ''att2'' or attribute = ''att3''
+ order by 1,2')
+AS ct(row_name text, category_1 text, category_2 text, category_3 text);
+
+ row_name | category_1 | category_2 | category_3
+----------+------------+------------+------------
+ test1 | val2 | val3 |
+ test2 | val6 | val7 |
+(2 rows)
+</pre><p>
+ </p><p>
+ You can avoid always having to write out a <code class="literal">FROM</code> clause to
+ define the output columns, by setting up a custom crosstab function that
+ has the desired output row type wired into its definition. This is
+ described in the next section. Another possibility is to embed the
+ required <code class="literal">FROM</code> clause in a view definition.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ See also the <code class="command"><a class="link" href="app-psql.html#APP-PSQL-META-COMMANDS-CROSSTABVIEW">\crosstabview</a></code>
+ command in <span class="application">psql</span>, which provides functionality similar
+ to <code class="function">crosstab()</code>.
+ </p></div></div><div class="sect3" id="id-1.11.7.52.5.6"><div class="titlepage"><div><div><h4 class="title">F.43.1.3. <code class="function">crosstab<em class="replaceable"><code>N</code></em>(text)</code></h4></div></div></div><a id="id-1.11.7.52.5.6.2" class="indexterm"></a><pre class="synopsis">
+crosstab<em class="replaceable"><code>N</code></em>(text sql)
+</pre><p>
+ The <code class="function">crosstab<em class="replaceable"><code>N</code></em></code> functions are examples of how
+ to set up custom wrappers for the general <code class="function">crosstab</code> function,
+ so that you need not write out column names and types in the calling
+ <code class="command">SELECT</code> query. The <code class="filename">tablefunc</code> module includes
+ <code class="function">crosstab2</code>, <code class="function">crosstab3</code>, and
+ <code class="function">crosstab4</code>, whose output row types are defined as
+ </p><pre class="programlisting">
+CREATE TYPE tablefunc_crosstab_N AS (
+ row_name TEXT,
+ category_1 TEXT,
+ category_2 TEXT,
+ .
+ .
+ .
+ category_N TEXT
+);
+</pre><p>
+ Thus, these functions can be used directly when the input query produces
+ <code class="structfield">row_name</code> and <code class="structfield">value</code> columns of type
+ <code class="type">text</code>, and you want 2, 3, or 4 output values columns.
+ In all other ways they behave exactly as described above for the
+ general <code class="function">crosstab</code> function.
+ </p><p>
+ For instance, the example given in the previous section would also
+ work as
+</p><pre class="programlisting">
+SELECT *
+FROM crosstab3(
+ 'select rowid, attribute, value
+ from ct
+ where attribute = ''att2'' or attribute = ''att3''
+ order by 1,2');
+</pre><p>
+ </p><p>
+ These functions are provided mostly for illustration purposes. You
+ can create your own return types and functions based on the
+ underlying <code class="function">crosstab()</code> function. There are two ways
+ to do it:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Create a composite type describing the desired output columns,
+ similar to the examples in
+ <code class="filename">contrib/tablefunc/tablefunc--1.0.sql</code>.
+ Then define a
+ unique function name accepting one <code class="type">text</code> parameter and returning
+ <code class="type">setof your_type_name</code>, but linking to the same underlying
+ <code class="function">crosstab</code> C function. For example, if your source data
+ produces row names that are <code class="type">text</code>, and values that are
+ <code class="type">float8</code>, and you want 5 value columns:
+</p><pre class="programlisting">
+CREATE TYPE my_crosstab_float8_5_cols AS (
+ my_row_name text,
+ my_category_1 float8,
+ my_category_2 float8,
+ my_category_3 float8,
+ my_category_4 float8,
+ my_category_5 float8
+);
+
+CREATE OR REPLACE FUNCTION crosstab_float8_5_cols(text)
+ RETURNS setof my_crosstab_float8_5_cols
+ AS '$libdir/tablefunc','crosstab' LANGUAGE C STABLE STRICT;
+</pre><p>
+ </p></li><li class="listitem"><p>
+ Use <code class="literal">OUT</code> parameters to define the return type implicitly.
+ The same example could also be done this way:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION crosstab_float8_5_cols(
+ IN text,
+ OUT my_row_name text,
+ OUT my_category_1 float8,
+ OUT my_category_2 float8,
+ OUT my_category_3 float8,
+ OUT my_category_4 float8,
+ OUT my_category_5 float8)
+ RETURNS setof record
+ AS '$libdir/tablefunc','crosstab' LANGUAGE C STABLE STRICT;
+</pre><p>
+ </p></li></ul></div><p>
+ </p></div><div class="sect3" id="id-1.11.7.52.5.7"><div class="titlepage"><div><div><h4 class="title">F.43.1.4. <code class="function">crosstab(text, text)</code></h4></div></div></div><a id="id-1.11.7.52.5.7.2" class="indexterm"></a><pre class="synopsis">
+crosstab(text source_sql, text category_sql)
+</pre><p>
+ The main limitation of the single-parameter form of <code class="function">crosstab</code>
+ is that it treats all values in a group alike, inserting each value into
+ the first available column. If you want the value
+ columns to correspond to specific categories of data, and some groups
+ might not have data for some of the categories, that doesn't work well.
+ The two-parameter form of <code class="function">crosstab</code> handles this case by
+ providing an explicit list of the categories corresponding to the
+ output columns.
+ </p><p>
+ <em class="parameter"><code>source_sql</code></em> is an SQL statement that produces the
+ source set of data. This statement must return one
+ <code class="structfield">row_name</code> column, one
+ <code class="structfield">category</code> column, and one
+ <code class="structfield">value</code> column. It may also have one or more
+ <span class="quote">“<span class="quote">extra</span>”</span> columns.
+ The <code class="structfield">row_name</code> column must be first. The
+ <code class="structfield">category</code> and <code class="structfield">value</code>
+ columns must be the last two columns, in that order. Any columns between
+ <code class="structfield">row_name</code> and
+ <code class="structfield">category</code> are treated as <span class="quote">“<span class="quote">extra</span>”</span>.
+ The <span class="quote">“<span class="quote">extra</span>”</span> columns are expected to be the same for all rows
+ with the same <code class="structfield">row_name</code> value.
+ </p><p>
+ For example, <em class="parameter"><code>source_sql</code></em> might produce a set
+ something like:
+</p><pre class="programlisting">
+SELECT row_name, extra_col, cat, value FROM foo ORDER BY 1;
+
+ row_name extra_col cat value
+----------+------------+-----+---------
+ row1 extra1 cat1 val1
+ row1 extra1 cat2 val2
+ row1 extra1 cat4 val4
+ row2 extra2 cat1 val5
+ row2 extra2 cat2 val6
+ row2 extra2 cat3 val7
+ row2 extra2 cat4 val8
+</pre><p>
+ </p><p>
+ <em class="parameter"><code>category_sql</code></em> is an SQL statement that produces
+ the set of categories. This statement must return only one column.
+ It must produce at least one row, or an error will be generated.
+ Also, it must not produce duplicate values, or an error will be
+ generated. <em class="parameter"><code>category_sql</code></em> might be something like:
+
+</p><pre class="programlisting">
+SELECT DISTINCT cat FROM foo ORDER BY 1;
+ cat
+ -------
+ cat1
+ cat2
+ cat3
+ cat4
+</pre><p>
+ </p><p>
+ The <code class="function">crosstab</code> function is declared to return <code class="type">setof
+ record</code>, so the actual names and types of the output columns must be
+ defined in the <code class="literal">FROM</code> clause of the calling <code class="command">SELECT</code>
+ statement, for example:
+
+</p><pre class="programlisting">
+SELECT * FROM crosstab('...', '...')
+ AS ct(row_name text, extra text, cat1 text, cat2 text, cat3 text, cat4 text);
+</pre><p>
+ </p><p>
+ This will produce a result something like:
+</p><pre class="programlisting">
+ &lt;== value columns ==&gt;
+row_name extra cat1 cat2 cat3 cat4
+---------+-------+------+------+------+------
+ row1 extra1 val1 val2 val4
+ row2 extra2 val5 val6 val7 val8
+</pre><p>
+ </p><p>
+ The <code class="literal">FROM</code> clause must define the proper number of output
+ columns of the proper data types. If there are <em class="replaceable"><code>N</code></em>
+ columns in the <em class="parameter"><code>source_sql</code></em> query's result, the first
+ <em class="replaceable"><code>N</code></em>-2 of them must match up with the first
+ <em class="replaceable"><code>N</code></em>-2 output columns. The remaining output columns
+ must have the type of the last column of the <em class="parameter"><code>source_sql</code></em>
+ query's result, and there must be exactly as many of them as there
+ are rows in the <em class="parameter"><code>category_sql</code></em> query's result.
+ </p><p>
+ The <code class="function">crosstab</code> function produces one output row for each
+ consecutive group of input rows with the same
+ <code class="structfield">row_name</code> value. The output
+ <code class="structfield">row_name</code> column, plus any <span class="quote">“<span class="quote">extra</span>”</span>
+ columns, are copied from the first row of the group. The output
+ <code class="structfield">value</code> columns are filled with the
+ <code class="structfield">value</code> fields from rows having matching
+ <code class="structfield">category</code> values. If a row's <code class="structfield">category</code>
+ does not match any output of the <em class="parameter"><code>category_sql</code></em>
+ query, its <code class="structfield">value</code> is ignored. Output
+ columns whose matching category is not present in any input row
+ of the group are filled with nulls.
+ </p><p>
+ In practice the <em class="parameter"><code>source_sql</code></em> query should always
+ specify <code class="literal">ORDER BY 1</code> to ensure that values with the same
+ <code class="structfield">row_name</code> are brought together. However,
+ ordering of the categories within a group is not important.
+ Also, it is essential to be sure that the order of the
+ <em class="parameter"><code>category_sql</code></em> query's output matches the specified
+ output column order.
+ </p><p>
+ Here are two complete examples:
+</p><pre class="programlisting">
+create table sales(year int, month int, qty int);
+insert into sales values(2007, 1, 1000);
+insert into sales values(2007, 2, 1500);
+insert into sales values(2007, 7, 500);
+insert into sales values(2007, 11, 1500);
+insert into sales values(2007, 12, 2000);
+insert into sales values(2008, 1, 1000);
+
+select * from crosstab(
+ 'select year, month, qty from sales order by 1',
+ 'select m from generate_series(1,12) m'
+) as (
+ year int,
+ "Jan" int,
+ "Feb" int,
+ "Mar" int,
+ "Apr" int,
+ "May" int,
+ "Jun" int,
+ "Jul" int,
+ "Aug" int,
+ "Sep" int,
+ "Oct" int,
+ "Nov" int,
+ "Dec" int
+);
+ year | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec
+------+------+------+-----+-----+-----+-----+-----+-----+-----+-----+------+------
+ 2007 | 1000 | 1500 | | | | | 500 | | | | 1500 | 2000
+ 2008 | 1000 | | | | | | | | | | |
+(2 rows)
+</pre><p>
+
+</p><pre class="programlisting">
+CREATE TABLE cth(rowid text, rowdt timestamp, attribute text, val text);
+INSERT INTO cth VALUES('test1','01 March 2003','temperature','42');
+INSERT INTO cth VALUES('test1','01 March 2003','test_result','PASS');
+INSERT INTO cth VALUES('test1','01 March 2003','volts','2.6987');
+INSERT INTO cth VALUES('test2','02 March 2003','temperature','53');
+INSERT INTO cth VALUES('test2','02 March 2003','test_result','FAIL');
+INSERT INTO cth VALUES('test2','02 March 2003','test_startdate','01 March 2003');
+INSERT INTO cth VALUES('test2','02 March 2003','volts','3.1234');
+
+SELECT * FROM crosstab
+(
+ 'SELECT rowid, rowdt, attribute, val FROM cth ORDER BY 1',
+ 'SELECT DISTINCT attribute FROM cth ORDER BY 1'
+)
+AS
+(
+ rowid text,
+ rowdt timestamp,
+ temperature int4,
+ test_result text,
+ test_startdate timestamp,
+ volts float8
+);
+ rowid | rowdt | temperature | test_result | test_startdate | volts
+-------+--------------------------+-------------+-------------+--------------------------+--------
+ test1 | Sat Mar 01 00:00:00 2003 | 42 | PASS | | 2.6987
+ test2 | Sun Mar 02 00:00:00 2003 | 53 | FAIL | Sat Mar 01 00:00:00 2003 | 3.1234
+(2 rows)
+</pre><p>
+ </p><p>
+ You can create predefined functions to avoid having to write out
+ the result column names and types in each query. See the examples
+ in the previous section. The underlying C function for this form
+ of <code class="function">crosstab</code> is named <code class="literal">crosstab_hash</code>.
+ </p></div><div class="sect3" id="id-1.11.7.52.5.8"><div class="titlepage"><div><div><h4 class="title">F.43.1.5. <code class="function">connectby</code></h4></div></div></div><a id="id-1.11.7.52.5.8.2" class="indexterm"></a><pre class="synopsis">
+connectby(text relname, text keyid_fld, text parent_keyid_fld
+ [, text orderby_fld ], text start_with, int max_depth
+ [, text branch_delim ])
+</pre><p>
+ The <code class="function">connectby</code> function produces a display of hierarchical
+ data that is stored in a table. The table must have a key field that
+ uniquely identifies rows, and a parent-key field that references the
+ parent (if any) of each row. <code class="function">connectby</code> can display the
+ sub-tree descending from any row.
+ </p><p>
+ <a class="xref" href="tablefunc.html#TABLEFUNC-CONNECTBY-PARAMETERS" title="Table F.31. connectby Parameters">Table F.31</a> explains the
+ parameters.
+ </p><div class="table" id="TABLEFUNC-CONNECTBY-PARAMETERS"><p class="title"><strong>Table F.31. <code class="function">connectby</code> Parameters</strong></p><div class="table-contents"><table class="table" summary="connectby Parameters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>relname</code></em></td><td>Name of the source relation</td></tr><tr><td><em class="parameter"><code>keyid_fld</code></em></td><td>Name of the key field</td></tr><tr><td><em class="parameter"><code>parent_keyid_fld</code></em></td><td>Name of the parent-key field</td></tr><tr><td><em class="parameter"><code>orderby_fld</code></em></td><td>Name of the field to order siblings by (optional)</td></tr><tr><td><em class="parameter"><code>start_with</code></em></td><td>Key value of the row to start at</td></tr><tr><td><em class="parameter"><code>max_depth</code></em></td><td>Maximum depth to descend to, or zero for unlimited depth</td></tr><tr><td><em class="parameter"><code>branch_delim</code></em></td><td>String to separate keys with in branch output (optional)</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The key and parent-key fields can be any data type, but they must be
+ the same type. Note that the <em class="parameter"><code>start_with</code></em> value must be
+ entered as a text string, regardless of the type of the key field.
+ </p><p>
+ The <code class="function">connectby</code> function is declared to return <code class="type">setof
+ record</code>, so the actual names and types of the output columns must be
+ defined in the <code class="literal">FROM</code> clause of the calling <code class="command">SELECT</code>
+ statement, for example:
+ </p><pre class="programlisting">
+SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'pos', 'row2', 0, '~')
+ AS t(keyid text, parent_keyid text, level int, branch text, pos int);
+</pre><p>
+ The first two output columns are used for the current row's key and
+ its parent row's key; they must match the type of the table's key field.
+ The third output column is the depth in the tree and must be of type
+ <code class="type">integer</code>. If a <em class="parameter"><code>branch_delim</code></em> parameter was
+ given, the next output column is the branch display and must be of type
+ <code class="type">text</code>. Finally, if an <em class="parameter"><code>orderby_fld</code></em>
+ parameter was given, the last output column is a serial number, and must
+ be of type <code class="type">integer</code>.
+ </p><p>
+ The <span class="quote">“<span class="quote">branch</span>”</span> output column shows the path of keys taken to
+ reach the current row. The keys are separated by the specified
+ <em class="parameter"><code>branch_delim</code></em> string. If no branch display is
+ wanted, omit both the <em class="parameter"><code>branch_delim</code></em> parameter
+ and the branch column in the output column list.
+ </p><p>
+ If the ordering of siblings of the same parent is important,
+ include the <em class="parameter"><code>orderby_fld</code></em> parameter to
+ specify which field to order siblings by. This field can be of any
+ sortable data type. The output column list must include a final
+ integer serial-number column, if and only if
+ <em class="parameter"><code>orderby_fld</code></em> is specified.
+ </p><p>
+ The parameters representing table and field names are copied as-is
+ into the SQL queries that <code class="function">connectby</code> generates internally.
+ Therefore, include double quotes if the names are mixed-case or contain
+ special characters. You may also need to schema-qualify the table name.
+ </p><p>
+ In large tables, performance will be poor unless there is an index on
+ the parent-key field.
+ </p><p>
+ It is important that the <em class="parameter"><code>branch_delim</code></em> string
+ not appear in any key values, else <code class="function">connectby</code> may incorrectly
+ report an infinite-recursion error. Note that if
+ <em class="parameter"><code>branch_delim</code></em> is not provided, a default value
+ of <code class="literal">~</code> is used for recursion detection purposes.
+
+ </p><p>
+ Here is an example:
+</p><pre class="programlisting">
+CREATE TABLE connectby_tree(keyid text, parent_keyid text, pos int);
+
+INSERT INTO connectby_tree VALUES('row1',NULL, 0);
+INSERT INTO connectby_tree VALUES('row2','row1', 0);
+INSERT INTO connectby_tree VALUES('row3','row1', 0);
+INSERT INTO connectby_tree VALUES('row4','row2', 1);
+INSERT INTO connectby_tree VALUES('row5','row2', 0);
+INSERT INTO connectby_tree VALUES('row6','row4', 0);
+INSERT INTO connectby_tree VALUES('row7','row3', 0);
+INSERT INTO connectby_tree VALUES('row8','row6', 0);
+INSERT INTO connectby_tree VALUES('row9','row5', 0);
+
+-- with branch, without orderby_fld (order of results is not guaranteed)
+SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'row2', 0, '~')
+ AS t(keyid text, parent_keyid text, level int, branch text);
+ keyid | parent_keyid | level | branch
+-------+--------------+-------+---------------------
+ row2 | | 0 | row2
+ row4 | row2 | 1 | row2~row4
+ row6 | row4 | 2 | row2~row4~row6
+ row8 | row6 | 3 | row2~row4~row6~row8
+ row5 | row2 | 1 | row2~row5
+ row9 | row5 | 2 | row2~row5~row9
+(6 rows)
+
+-- without branch, without orderby_fld (order of results is not guaranteed)
+SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'row2', 0)
+ AS t(keyid text, parent_keyid text, level int);
+ keyid | parent_keyid | level
+-------+--------------+-------
+ row2 | | 0
+ row4 | row2 | 1
+ row6 | row4 | 2
+ row8 | row6 | 3
+ row5 | row2 | 1
+ row9 | row5 | 2
+(6 rows)
+
+-- with branch, with orderby_fld (notice that row5 comes before row4)
+SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'pos', 'row2', 0, '~')
+ AS t(keyid text, parent_keyid text, level int, branch text, pos int);
+ keyid | parent_keyid | level | branch | pos
+-------+--------------+-------+---------------------+-----
+ row2 | | 0 | row2 | 1
+ row5 | row2 | 1 | row2~row5 | 2
+ row9 | row5 | 2 | row2~row5~row9 | 3
+ row4 | row2 | 1 | row2~row4 | 4
+ row6 | row4 | 2 | row2~row4~row6 | 5
+ row8 | row6 | 3 | row2~row4~row6~row8 | 6
+(6 rows)
+
+-- without branch, with orderby_fld (notice that row5 comes before row4)
+SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'pos', 'row2', 0)
+ AS t(keyid text, parent_keyid text, level int, pos int);
+ keyid | parent_keyid | level | pos
+-------+--------------+-------+-----
+ row2 | | 0 | 1
+ row5 | row2 | 1 | 2
+ row9 | row5 | 2 | 3
+ row4 | row2 | 1 | 4
+ row6 | row4 | 2 | 5
+ row8 | row6 | 3 | 6
+(6 rows)
+</pre><p>
+ </p></div></div><div class="sect2" id="id-1.11.7.52.6"><div class="titlepage"><div><div><h3 class="title">F.43.2. Author</h3></div></div></div><p>
+ Joe Conway
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sslinfo.html" title="F.42. sslinfo">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tcn.html" title="F.44. tcn">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.42. sslinfo </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.44. tcn</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tablesample-method.html b/doc/src/sgml/html/tablesample-method.html
new file mode 100644
index 0000000..7cb7736
--- /dev/null
+++ b/doc/src/sgml/html/tablesample-method.html
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 60. Writing a Table Sampling Method</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers" /><link rel="next" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 60. Writing a Table Sampling Method</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions">Next</a></td></tr></table><hr /></div><div class="chapter" id="TABLESAMPLE-METHOD"><div class="titlepage"><div><div><h2 class="title">Chapter 60. Writing a Table Sampling Method</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="tablesample-support-functions.html">60.1. Sampling Method Support Functions</a></span></dt></dl></div><a id="id-1.10.11.2" class="indexterm"></a><a id="id-1.10.11.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span>'s implementation of the <code class="literal">TABLESAMPLE</code>
+ clause supports custom table sampling methods, in addition to
+ the <code class="literal">BERNOULLI</code> and <code class="literal">SYSTEM</code> methods that are required
+ by the SQL standard. The sampling method determines which rows of the
+ table will be selected when the <code class="literal">TABLESAMPLE</code> clause is used.
+ </p><p>
+ At the SQL level, a table sampling method is represented by a single SQL
+ function, typically implemented in C, having the signature
+</p><pre class="programlisting">
+method_name(internal) RETURNS tsm_handler
+</pre><p>
+ The name of the function is the same method name appearing in the
+ <code class="literal">TABLESAMPLE</code> clause. The <code class="type">internal</code> argument is a dummy
+ (always having value zero) that simply serves to prevent this function from
+ being called directly from an SQL command.
+ The result of the function must be a palloc'd struct of
+ type <code class="type">TsmRoutine</code>, which contains pointers to support functions for
+ the sampling method. These support functions are plain C functions and
+ are not visible or callable at the SQL level. The support functions are
+ described in <a class="xref" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions">Section 60.1</a>.
+ </p><p>
+ In addition to function pointers, the <code class="type">TsmRoutine</code> struct must
+ provide these additional fields:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">List *parameterTypes</code></span></dt><dd><p>
+ This is an OID list containing the data type OIDs of the parameter(s)
+ that will be accepted by the <code class="literal">TABLESAMPLE</code> clause when this
+ sampling method is used. For example, for the built-in methods, this
+ list contains a single item with value <code class="literal">FLOAT4OID</code>, which
+ represents the sampling percentage. Custom sampling methods can have
+ more or different parameters.
+ </p></dd><dt><span class="term"><code class="literal">bool repeatable_across_queries</code></span></dt><dd><p>
+ If <code class="literal">true</code>, the sampling method can deliver identical samples
+ across successive queries, if the same parameters
+ and <code class="literal">REPEATABLE</code> seed value are supplied each time and the
+ table contents have not changed. When this is <code class="literal">false</code>,
+ the <code class="literal">REPEATABLE</code> clause is not accepted for use with the
+ sampling method.
+ </p></dd><dt><span class="term"><code class="literal">bool repeatable_across_scans</code></span></dt><dd><p>
+ If <code class="literal">true</code>, the sampling method can deliver identical samples
+ across successive scans in the same query (assuming unchanging
+ parameters, seed value, and snapshot).
+ When this is <code class="literal">false</code>, the planner will not select plans that
+ would require scanning the sampled table more than once, since that
+ might result in inconsistent query output.
+ </p></dd></dl></div><p>
+ The <code class="type">TsmRoutine</code> struct type is declared
+ in <code class="filename">src/include/access/tsmapi.h</code>, which see for additional
+ details.
+ </p><p>
+ The table sampling methods included in the standard distribution are good
+ references when trying to write your own. Look into
+ the <code class="filename">src/backend/access/tablesample</code> subdirectory of the source
+ tree for the built-in sampling methods, and into the <code class="filename">contrib</code>
+ subdirectory for add-on methods.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fdw-row-locking.html" title="59.5. Row Locking in Foreign Data Wrappers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tablesample-support-functions.html" title="60.1. Sampling Method Support Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">59.5. Row Locking in Foreign Data Wrappers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 60.1. Sampling Method Support Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tablesample-support-functions.html b/doc/src/sgml/html/tablesample-support-functions.html
new file mode 100644
index 0000000..efc28b2
--- /dev/null
+++ b/doc/src/sgml/html/tablesample-support-functions.html
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>60.1. Sampling Method Support Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method" /><link rel="next" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">60.1. Sampling Method Support Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Up</a></td><th width="60%" align="center">Chapter 60. Writing a Table Sampling Method</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Next</a></td></tr></table><hr /></div><div class="sect1" id="TABLESAMPLE-SUPPORT-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">60.1. Sampling Method Support Functions</h2></div></div></div><p>
+ The TSM handler function returns a palloc'd <code class="type">TsmRoutine</code> struct
+ containing pointers to the support functions described below. Most of
+ the functions are required, but some are optional, and those pointers can
+ be NULL.
+ </p><p>
+</p><pre class="programlisting">
+void
+SampleScanGetSampleSize (PlannerInfo *root,
+ RelOptInfo *baserel,
+ List *paramexprs,
+ BlockNumber *pages,
+ double *tuples);
+</pre><p>
+
+ This function is called during planning. It must estimate the number of
+ relation pages that will be read during a sample scan, and the number of
+ tuples that will be selected by the scan. (For example, these might be
+ determined by estimating the sampling fraction, and then multiplying
+ the <code class="literal">baserel-&gt;pages</code> and <code class="literal">baserel-&gt;tuples</code>
+ numbers by that, being sure to round the results to integral values.)
+ The <code class="literal">paramexprs</code> list holds the expression(s) that are
+ parameters to the <code class="literal">TABLESAMPLE</code> clause. It is recommended to
+ use <code class="function">estimate_expression_value()</code> to try to reduce these
+ expressions to constants, if their values are needed for estimation
+ purposes; but the function must provide size estimates even if they cannot
+ be reduced, and it should not fail even if the values appear invalid
+ (remember that they're only estimates of what the run-time values will be).
+ The <code class="literal">pages</code> and <code class="literal">tuples</code> parameters are outputs.
+ </p><p>
+</p><pre class="programlisting">
+void
+InitSampleScan (SampleScanState *node,
+ int eflags);
+</pre><p>
+
+ Initialize for execution of a SampleScan plan node.
+ This is called during executor startup.
+ It should perform any initialization needed before processing can start.
+ The <code class="structname">SampleScanState</code> node has already been created, but
+ its <code class="structfield">tsm_state</code> field is NULL.
+ The <code class="function">InitSampleScan</code> function can palloc whatever internal
+ state data is needed by the sampling method, and store a pointer to
+ it in <code class="literal">node-&gt;tsm_state</code>.
+ Information about the table to scan is accessible through other fields
+ of the <code class="structname">SampleScanState</code> node (but note that the
+ <code class="literal">node-&gt;ss.ss_currentScanDesc</code> scan descriptor is not set
+ up yet).
+ <code class="literal">eflags</code> contains flag bits describing the executor's
+ operating mode for this plan node.
+ </p><p>
+ When <code class="literal">(eflags &amp; EXEC_FLAG_EXPLAIN_ONLY)</code> is true,
+ the scan will not actually be performed, so this function should only do
+ the minimum required to make the node state valid for <code class="command">EXPLAIN</code>
+ and <code class="function">EndSampleScan</code>.
+ </p><p>
+ This function can be omitted (set the pointer to NULL), in which case
+ <code class="function">BeginSampleScan</code> must perform all initialization needed
+ by the sampling method.
+ </p><p>
+</p><pre class="programlisting">
+void
+BeginSampleScan (SampleScanState *node,
+ Datum *params,
+ int nparams,
+ uint32 seed);
+</pre><p>
+
+ Begin execution of a sampling scan.
+ This is called just before the first attempt to fetch a tuple, and
+ may be called again if the scan needs to be restarted.
+ Information about the table to scan is accessible through fields
+ of the <code class="structname">SampleScanState</code> node (but note that the
+ <code class="literal">node-&gt;ss.ss_currentScanDesc</code> scan descriptor is not set
+ up yet).
+ The <code class="literal">params</code> array, of length <code class="literal">nparams</code>, contains the
+ values of the parameters supplied in the <code class="literal">TABLESAMPLE</code> clause.
+ These will have the number and types specified in the sampling
+ method's <code class="literal">parameterTypes</code> list, and have been checked
+ to not be null.
+ <code class="literal">seed</code> contains a seed to use for any random numbers generated
+ within the sampling method; it is either a hash derived from the
+ <code class="literal">REPEATABLE</code> value if one was given, or the result
+ of <code class="literal">random()</code> if not.
+ </p><p>
+ This function may adjust the fields <code class="literal">node-&gt;use_bulkread</code>
+ and <code class="literal">node-&gt;use_pagemode</code>.
+ If <code class="literal">node-&gt;use_bulkread</code> is <code class="literal">true</code>, which it is by
+ default, the scan will use a buffer access strategy that encourages
+ recycling buffers after use. It might be reasonable to set this
+ to <code class="literal">false</code> if the scan will visit only a small fraction of the
+ table's pages.
+ If <code class="literal">node-&gt;use_pagemode</code> is <code class="literal">true</code>, which it is by
+ default, the scan will perform visibility checking in a single pass for
+ all tuples on each visited page. It might be reasonable to set this
+ to <code class="literal">false</code> if the scan will select only a small fraction of the
+ tuples on each visited page. That will result in fewer tuple visibility
+ checks being performed, though each one will be more expensive because it
+ will require more locking.
+ </p><p>
+ If the sampling method is
+ marked <code class="literal">repeatable_across_scans</code>, it must be able to
+ select the same set of tuples during a rescan as it did originally, that is
+ a fresh call of <code class="function">BeginSampleScan</code> must lead to selecting the
+ same tuples as before (if the <code class="literal">TABLESAMPLE</code> parameters
+ and seed don't change).
+ </p><p>
+</p><pre class="programlisting">
+BlockNumber
+NextSampleBlock (SampleScanState *node, BlockNumber nblocks);
+</pre><p>
+
+ Returns the block number of the next page to be scanned, or
+ <code class="literal">InvalidBlockNumber</code> if no pages remain to be scanned.
+ </p><p>
+ This function can be omitted (set the pointer to NULL), in which case
+ the core code will perform a sequential scan of the entire relation.
+ Such a scan can use synchronized scanning, so that the sampling method
+ cannot assume that the relation pages are visited in the same order on
+ each scan.
+ </p><p>
+</p><pre class="programlisting">
+OffsetNumber
+NextSampleTuple (SampleScanState *node,
+ BlockNumber blockno,
+ OffsetNumber maxoffset);
+</pre><p>
+
+ Returns the offset number of the next tuple to be sampled on the
+ specified page, or <code class="literal">InvalidOffsetNumber</code> if no tuples remain to
+ be sampled. <code class="literal">maxoffset</code> is the largest offset number in use
+ on the page.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">NextSampleTuple</code> is not explicitly told which of the offset
+ numbers in the range <code class="literal">1 .. maxoffset</code> actually contain valid
+ tuples. This is not normally a problem since the core code ignores
+ requests to sample missing or invisible tuples; that should not result in
+ any bias in the sample. However, if necessary, the function can use
+ <code class="literal">node-&gt;donetuples</code> to examine how many of the tuples
+ it returned were valid and visible.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">NextSampleTuple</code> must <span class="emphasis"><em>not</em></span> assume
+ that <code class="literal">blockno</code> is the same page number returned by the most
+ recent <code class="function">NextSampleBlock</code> call. It was returned by some
+ previous <code class="function">NextSampleBlock</code> call, but the core code is allowed
+ to call <code class="function">NextSampleBlock</code> in advance of actually scanning
+ pages, so as to support prefetching. It is OK to assume that once
+ sampling of a given page begins, successive <code class="function">NextSampleTuple</code>
+ calls all refer to the same page until <code class="literal">InvalidOffsetNumber</code> is
+ returned.
+ </p></div><p>
+</p><pre class="programlisting">
+void
+EndSampleScan (SampleScanState *node);
+</pre><p>
+
+ End the scan and release resources. It is normally not important
+ to release palloc'd memory, but any externally-visible resources
+ should be cleaned up.
+ This function can be omitted (set the pointer to NULL) in the common
+ case where no such resources exist.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tablesample-method.html" title="Chapter 60. Writing a Table Sampling Method">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-scan.html" title="Chapter 61. Writing a Custom Scan Provider">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 60. Writing a Table Sampling Method </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 61. Writing a Custom Scan Provider</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tcn.html b/doc/src/sgml/html/tcn.html
new file mode 100644
index 0000000..eda9f65
--- /dev/null
+++ b/doc/src/sgml/html/tcn.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.44. tcn</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tablefunc.html" title="F.43. tablefunc" /><link rel="next" href="test-decoding.html" title="F.45. test_decoding" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.44. tcn</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tablefunc.html" title="F.43. tablefunc">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="test-decoding.html" title="F.45. test_decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="TCN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.44. tcn</h2></div></div></div><a id="id-1.11.7.53.2" class="indexterm"></a><a id="id-1.11.7.53.3" class="indexterm"></a><p>
+ The <code class="filename">tcn</code> module provides a trigger function that notifies
+ listeners of changes to any table on which it is attached. It must be
+ used as an <code class="literal">AFTER</code> trigger <code class="literal">FOR EACH ROW</code>.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><p>
+ Only one parameter may be supplied to the function in a
+ <code class="literal">CREATE TRIGGER</code> statement, and that is optional. If supplied
+ it will be used for the channel name for the notifications. If omitted
+ <code class="literal">tcn</code> will be used for the channel name.
+ </p><p>
+ The payload of the notifications consists of the table name, a letter to
+ indicate which type of operation was performed, and column name/value pairs
+ for primary key columns. Each part is separated from the next by a comma.
+ For ease of parsing using regular expressions, table and column names are
+ always wrapped in double quotes, and data values are always wrapped in
+ single quotes. Embedded quotes are doubled.
+ </p><p>
+ A brief example of using the extension follows.
+
+</p><pre class="programlisting">
+test=# create table tcndata
+test-# (
+test(# a int not null,
+test(# b date not null,
+test(# c text,
+test(# primary key (a, b)
+test(# );
+CREATE TABLE
+test=# create trigger tcndata_tcn_trigger
+test-# after insert or update or delete on tcndata
+test-# for each row execute function triggered_change_notification();
+CREATE TRIGGER
+test=# listen tcn;
+LISTEN
+test=# insert into tcndata values (1, date '2012-12-22', 'one'),
+test-# (1, date '2012-12-23', 'another'),
+test-# (2, date '2012-12-23', 'two');
+INSERT 0 3
+Asynchronous notification "tcn" with payload ""tcndata",I,"a"='1',"b"='2012-12-22'" received from server process with PID 22770.
+Asynchronous notification "tcn" with payload ""tcndata",I,"a"='1',"b"='2012-12-23'" received from server process with PID 22770.
+Asynchronous notification "tcn" with payload ""tcndata",I,"a"='2',"b"='2012-12-23'" received from server process with PID 22770.
+test=# update tcndata set c = 'uno' where a = 1;
+UPDATE 2
+Asynchronous notification "tcn" with payload ""tcndata",U,"a"='1',"b"='2012-12-22'" received from server process with PID 22770.
+Asynchronous notification "tcn" with payload ""tcndata",U,"a"='1',"b"='2012-12-23'" received from server process with PID 22770.
+test=# delete from tcndata where a = 1 and b = date '2012-12-22';
+DELETE 1
+Asynchronous notification "tcn" with payload ""tcndata",D,"a"='1',"b"='2012-12-22'" received from server process with PID 22770.
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tablefunc.html" title="F.43. tablefunc">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="test-decoding.html" title="F.45. test_decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.43. tablefunc </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.45. test_decoding</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/test-decoding.html b/doc/src/sgml/html/test-decoding.html
new file mode 100644
index 0000000..6734bbb
--- /dev/null
+++ b/doc/src/sgml/html/test-decoding.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.45. test_decoding</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tcn.html" title="F.44. tcn" /><link rel="next" href="tsm-system-rows.html" title="F.46. tsm_system_rows" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.45. test_decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tcn.html" title="F.44. tcn">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tsm-system-rows.html" title="F.46. tsm_system_rows">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEST-DECODING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.45. test_decoding</h2></div></div></div><a id="id-1.11.7.54.2" class="indexterm"></a><p>
+ <code class="filename">test_decoding</code> is an example of a logical decoding
+ output plugin. It doesn't do anything especially useful, but can serve as
+ a starting point for developing your own output plugin.
+ </p><p>
+ <code class="filename">test_decoding</code> receives WAL through the logical decoding
+ mechanism and decodes it into text representations of the operations
+ performed.
+ </p><p>
+ Typical output from this plugin, used over the SQL logical decoding
+ interface, might be:
+
+</p><pre class="programlisting">
+postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'include-xids', '0');
+ lsn | xid | data
+-----------+-----+--------------------------------------------------
+ 0/16D30F8 | 691 | BEGIN
+ 0/16D32A0 | 691 | table public.data: INSERT: id[int4]:2 data[text]:'arg'
+ 0/16D32A0 | 691 | table public.data: INSERT: id[int4]:3 data[text]:'demo'
+ 0/16D32A0 | 691 | COMMIT
+ 0/16D32D8 | 692 | BEGIN
+ 0/16D3398 | 692 | table public.data: DELETE: id[int4]:2
+ 0/16D3398 | 692 | table public.data: DELETE: id[int4]:3
+ 0/16D3398 | 692 | COMMIT
+(8 rows)
+</pre><p>
+ </p><p>
+ We can also get the changes of the in-progress transaction, and the typical
+ output might be:
+
+</p><pre class="programlisting">
+postgres[33712]=#* SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'stream-changes', '1');
+ lsn | xid | data
+-----------+-----+--------------------------------------------------
+ 0/16B21F8 | 503 | opening a streamed block for transaction TXN 503
+ 0/16B21F8 | 503 | streaming change for TXN 503
+ 0/16B2300 | 503 | streaming change for TXN 503
+ 0/16B2408 | 503 | streaming change for TXN 503
+ 0/16BEBA0 | 503 | closing a streamed block for transaction TXN 503
+ 0/16B21F8 | 503 | opening a streamed block for transaction TXN 503
+ 0/16BECA8 | 503 | streaming change for TXN 503
+ 0/16BEDB0 | 503 | streaming change for TXN 503
+ 0/16BEEB8 | 503 | streaming change for TXN 503
+ 0/16BEBA0 | 503 | closing a streamed block for transaction TXN 503
+(10 rows)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tcn.html" title="F.44. tcn">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tsm-system-rows.html" title="F.46. tsm_system_rows">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.44. tcn </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.46. tsm_system_rows</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-configuration.html b/doc/src/sgml/html/textsearch-configuration.html
new file mode 100644
index 0000000..ab0b2e8
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-configuration.html
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.7. Configuration Example</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-dictionaries.html" title="12.6. Dictionaries" /><link rel="next" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.7. Configuration Example</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-dictionaries.html" title="12.6. Dictionaries">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-CONFIGURATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.7. Configuration Example</h2></div></div></div><p>
+ A text search configuration specifies all options necessary to transform a
+ document into a <code class="type">tsvector</code>: the parser to use to break text
+ into tokens, and the dictionaries to use to transform each token into a
+ lexeme. Every call of
+ <code class="function">to_tsvector</code> or <code class="function">to_tsquery</code>
+ needs a text search configuration to perform its processing.
+ The configuration parameter
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a>
+ specifies the name of the default configuration, which is the
+ one used by text search functions if an explicit configuration
+ parameter is omitted.
+ It can be set in <code class="filename">postgresql.conf</code>, or set for an
+ individual session using the <code class="command">SET</code> command.
+ </p><p>
+ Several predefined text search configurations are available, and
+ you can create custom configurations easily. To facilitate management
+ of text search objects, a set of <acronym class="acronym">SQL</acronym> commands
+ is available, and there are several <span class="application">psql</span> commands that display information
+ about text search objects (<a class="xref" href="textsearch-psql.html" title="12.10. psql Support">Section 12.10</a>).
+ </p><p>
+ As an example we will create a configuration
+ <code class="literal">pg</code>, starting by duplicating the built-in
+ <code class="literal">english</code> configuration:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH CONFIGURATION public.pg ( COPY = pg_catalog.english );
+</pre><p>
+ </p><p>
+ We will use a PostgreSQL-specific synonym list
+ and store it in <code class="filename">$SHAREDIR/tsearch_data/pg_dict.syn</code>.
+ The file contents look like:
+
+</p><pre class="programlisting">
+postgres pg
+pgsql pg
+postgresql pg
+</pre><p>
+
+ We define the synonym dictionary like this:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY pg_dict (
+ TEMPLATE = synonym,
+ SYNONYMS = pg_dict
+);
+</pre><p>
+
+ Next we register the <span class="productname">Ispell</span> dictionary
+ <code class="literal">english_ispell</code>, which has its own configuration files:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY english_ispell (
+ TEMPLATE = ispell,
+ DictFile = english,
+ AffFile = english,
+ StopWords = english
+);
+</pre><p>
+
+ Now we can set up the mappings for words in configuration
+ <code class="literal">pg</code>:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION pg
+ ALTER MAPPING FOR asciiword, asciihword, hword_asciipart,
+ word, hword, hword_part
+ WITH pg_dict, english_ispell, english_stem;
+</pre><p>
+
+ We choose not to index or search some token types that the built-in
+ configuration does handle:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION pg
+ DROP MAPPING FOR email, url, url_path, sfloat, float;
+</pre><p>
+ </p><p>
+ Now we can test our configuration:
+
+</p><pre class="programlisting">
+SELECT * FROM ts_debug('public.pg', '
+PostgreSQL, the highly scalable, SQL compliant, open source object-relational
+database management system, is now undergoing beta testing of the next
+version of our software.
+');
+</pre><p>
+ </p><p>
+ The next step is to set the session to use the new configuration, which was
+ created in the <code class="literal">public</code> schema:
+
+</p><pre class="screen">
+=&gt; \dF
+ List of text search configurations
+ Schema | Name | Description
+---------+------+-------------
+ public | pg |
+
+SET default_text_search_config = 'public.pg';
+SET
+
+SHOW default_text_search_config;
+ default_text_search_config
+----------------------------
+ public.pg
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-dictionaries.html" title="12.6. Dictionaries">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.6. Dictionaries </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.8. Testing and Debugging Text Search</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-controls.html b/doc/src/sgml/html/textsearch-controls.html
new file mode 100644
index 0000000..d6465b0
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-controls.html
@@ -0,0 +1,550 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.3. Controlling Text Search</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-tables.html" title="12.2. Tables and Indexes" /><link rel="next" href="textsearch-features.html" title="12.4. Additional Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.3. Controlling Text Search</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-tables.html" title="12.2. Tables and Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-features.html" title="12.4. Additional Features">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-CONTROLS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.3. Controlling Text Search</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-PARSING-DOCUMENTS">12.3.1. Parsing Documents</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES">12.3.2. Parsing Queries</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-RANKING">12.3.3. Ranking Search Results</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-HEADLINE">12.3.4. Highlighting Results</a></span></dt></dl></div><p>
+ To implement full text searching there must be a function to create a
+ <code class="type">tsvector</code> from a document and a <code class="type">tsquery</code> from a
+ user query. Also, we need to return results in a useful order, so we need
+ a function that compares documents with respect to their relevance to
+ the query. It's also important to be able to display the results nicely.
+ <span class="productname">PostgreSQL</span> provides support for all of these
+ functions.
+ </p><div class="sect2" id="TEXTSEARCH-PARSING-DOCUMENTS"><div class="titlepage"><div><div><h3 class="title">12.3.1. Parsing Documents</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides the
+ function <code class="function">to_tsvector</code> for converting a document to
+ the <code class="type">tsvector</code> data type.
+ </p><a id="id-1.5.11.6.3.3" class="indexterm"></a><pre class="synopsis">
+to_tsvector([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>document</code></em> <code class="type">text</code>) returns <code class="type">tsvector</code>
+</pre><p>
+ <code class="function">to_tsvector</code> parses a textual document into tokens,
+ reduces the tokens to lexemes, and returns a <code class="type">tsvector</code> which
+ lists the lexemes together with their positions in the document.
+ The document is processed according to the specified or default
+ text search configuration.
+ Here is a simple example:
+
+</p><pre class="screen">
+SELECT to_tsvector('english', 'a fat cat sat on a mat - it ate a fat rats');
+ to_tsvector
+-----------------------------------------------------
+ 'ate':9 'cat':3 'fat':2,11 'mat':7 'rat':12 'sat':4
+</pre><p>
+ </p><p>
+ In the example above we see that the resulting <code class="type">tsvector</code> does not
+ contain the words <code class="literal">a</code>, <code class="literal">on</code>, or
+ <code class="literal">it</code>, the word <code class="literal">rats</code> became
+ <code class="literal">rat</code>, and the punctuation sign <code class="literal">-</code> was
+ ignored.
+ </p><p>
+ The <code class="function">to_tsvector</code> function internally calls a parser
+ which breaks the document text into tokens and assigns a type to
+ each token. For each token, a list of
+ dictionaries (<a class="xref" href="textsearch-dictionaries.html" title="12.6. Dictionaries">Section 12.6</a>) is consulted,
+ where the list can vary depending on the token type. The first dictionary
+ that <em class="firstterm">recognizes</em> the token emits one or more normalized
+ <em class="firstterm">lexemes</em> to represent the token. For example,
+ <code class="literal">rats</code> became <code class="literal">rat</code> because one of the
+ dictionaries recognized that the word <code class="literal">rats</code> is a plural
+ form of <code class="literal">rat</code>. Some words are recognized as
+ <em class="firstterm">stop words</em> (<a class="xref" href="textsearch-dictionaries.html#TEXTSEARCH-STOPWORDS" title="12.6.1. Stop Words">Section 12.6.1</a>), which
+ causes them to be ignored since they occur too frequently to be useful in
+ searching. In our example these are
+ <code class="literal">a</code>, <code class="literal">on</code>, and <code class="literal">it</code>.
+ If no dictionary in the list recognizes the token then it is also ignored.
+ In this example that happened to the punctuation sign <code class="literal">-</code>
+ because there are in fact no dictionaries assigned for its token type
+ (<code class="literal">Space symbols</code>), meaning space tokens will never be
+ indexed. The choices of parser, dictionaries and which types of tokens to
+ index are determined by the selected text search configuration (<a class="xref" href="textsearch-configuration.html" title="12.7. Configuration Example">Section 12.7</a>). It is possible to have
+ many different configurations in the same database, and predefined
+ configurations are available for various languages. In our example
+ we used the default configuration <code class="literal">english</code> for the
+ English language.
+ </p><p>
+ The function <code class="function">setweight</code> can be used to label the
+ entries of a <code class="type">tsvector</code> with a given <em class="firstterm">weight</em>,
+ where a weight is one of the letters <code class="literal">A</code>, <code class="literal">B</code>,
+ <code class="literal">C</code>, or <code class="literal">D</code>.
+ This is typically used to mark entries coming from
+ different parts of a document, such as title versus body. Later, this
+ information can be used for ranking of search results.
+ </p><p>
+ Because <code class="function">to_tsvector</code>(<code class="literal">NULL</code>) will
+ return <code class="literal">NULL</code>, it is recommended to use
+ <code class="function">coalesce</code> whenever a field might be null.
+ Here is the recommended method for creating
+ a <code class="type">tsvector</code> from a structured document:
+
+</p><pre class="programlisting">
+UPDATE tt SET ti =
+ setweight(to_tsvector(coalesce(title,'')), 'A') ||
+ setweight(to_tsvector(coalesce(keyword,'')), 'B') ||
+ setweight(to_tsvector(coalesce(abstract,'')), 'C') ||
+ setweight(to_tsvector(coalesce(body,'')), 'D');
+</pre><p>
+
+ Here we have used <code class="function">setweight</code> to label the source
+ of each lexeme in the finished <code class="type">tsvector</code>, and then merged
+ the labeled <code class="type">tsvector</code> values using the <code class="type">tsvector</code>
+ concatenation operator <code class="literal">||</code>. (<a class="xref" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR" title="12.4.1. Manipulating Documents">Section 12.4.1</a> gives details about these
+ operations.)
+ </p></div><div class="sect2" id="TEXTSEARCH-PARSING-QUERIES"><div class="titlepage"><div><div><h3 class="title">12.3.2. Parsing Queries</h3></div></div></div><p>
+ <span class="productname">PostgreSQL</span> provides the
+ functions <code class="function">to_tsquery</code>,
+ <code class="function">plainto_tsquery</code>,
+ <code class="function">phraseto_tsquery</code> and
+ <code class="function">websearch_to_tsquery</code>
+ for converting a query to the <code class="type">tsquery</code> data type.
+ <code class="function">to_tsquery</code> offers access to more features
+ than either <code class="function">plainto_tsquery</code> or
+ <code class="function">phraseto_tsquery</code>, but it is less forgiving about its
+ input. <code class="function">websearch_to_tsquery</code> is a simplified version
+ of <code class="function">to_tsquery</code> with an alternative syntax, similar
+ to the one used by web search engines.
+ </p><a id="id-1.5.11.6.4.3" class="indexterm"></a><pre class="synopsis">
+to_tsquery([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>querytext</code></em> <code class="type">text</code>) returns <code class="type">tsquery</code>
+</pre><p>
+ <code class="function">to_tsquery</code> creates a <code class="type">tsquery</code> value from
+ <em class="replaceable"><code>querytext</code></em>, which must consist of single tokens
+ separated by the <code class="type">tsquery</code> operators <code class="literal">&amp;</code> (AND),
+ <code class="literal">|</code> (OR), <code class="literal">!</code> (NOT), and
+ <code class="literal">&lt;-&gt;</code> (FOLLOWED BY), possibly grouped
+ using parentheses. In other words, the input to
+ <code class="function">to_tsquery</code> must already follow the general rules for
+ <code class="type">tsquery</code> input, as described in <a class="xref" href="datatype-textsearch.html#DATATYPE-TSQUERY" title="8.11.2. tsquery">Section 8.11.2</a>. The difference is that while basic
+ <code class="type">tsquery</code> input takes the tokens at face value,
+ <code class="function">to_tsquery</code> normalizes each token into a lexeme using
+ the specified or default configuration, and discards any tokens that are
+ stop words according to the configuration. For example:
+
+</p><pre class="screen">
+SELECT to_tsquery('english', 'The &amp; Fat &amp; Rats');
+ to_tsquery
+---------------
+ 'fat' &amp; 'rat'
+</pre><p>
+
+ As in basic <code class="type">tsquery</code> input, weight(s) can be attached to each
+ lexeme to restrict it to match only <code class="type">tsvector</code> lexemes of those
+ weight(s). For example:
+
+</p><pre class="screen">
+SELECT to_tsquery('english', 'Fat | Rats:AB');
+ to_tsquery
+------------------
+ 'fat' | 'rat':AB
+</pre><p>
+
+ Also, <code class="literal">*</code> can be attached to a lexeme to specify prefix matching:
+
+</p><pre class="screen">
+SELECT to_tsquery('supern:*A &amp; star:A*B');
+ to_tsquery
+--------------------------
+ 'supern':*A &amp; 'star':*AB
+</pre><p>
+
+ Such a lexeme will match any word in a <code class="type">tsvector</code> that begins
+ with the given string.
+ </p><p>
+ <code class="function">to_tsquery</code> can also accept single-quoted
+ phrases. This is primarily useful when the configuration includes a
+ thesaurus dictionary that may trigger on such phrases.
+ In the example below, a thesaurus contains the rule <code class="literal">supernovae
+ stars : sn</code>:
+
+</p><pre class="screen">
+SELECT to_tsquery('''supernovae stars'' &amp; !crab');
+ to_tsquery
+---------------
+ 'sn' &amp; !'crab'
+</pre><p>
+
+ Without quotes, <code class="function">to_tsquery</code> will generate a syntax
+ error for tokens that are not separated by an AND, OR, or FOLLOWED BY
+ operator.
+ </p><a id="id-1.5.11.6.4.7" class="indexterm"></a><pre class="synopsis">
+plainto_tsquery([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>querytext</code></em> <code class="type">text</code>) returns <code class="type">tsquery</code>
+</pre><p>
+ <code class="function">plainto_tsquery</code> transforms the unformatted text
+ <em class="replaceable"><code>querytext</code></em> to a <code class="type">tsquery</code> value.
+ The text is parsed and normalized much as for <code class="function">to_tsvector</code>,
+ then the <code class="literal">&amp;</code> (AND) <code class="type">tsquery</code> operator is
+ inserted between surviving words.
+ </p><p>
+ Example:
+
+</p><pre class="screen">
+SELECT plainto_tsquery('english', 'The Fat Rats');
+ plainto_tsquery
+-----------------
+ 'fat' &amp; 'rat'
+</pre><p>
+
+ Note that <code class="function">plainto_tsquery</code> will not
+ recognize <code class="type">tsquery</code> operators, weight labels,
+ or prefix-match labels in its input:
+
+</p><pre class="screen">
+SELECT plainto_tsquery('english', 'The Fat &amp; Rats:C');
+ plainto_tsquery
+---------------------
+ 'fat' &amp; 'rat' &amp; 'c'
+</pre><p>
+
+ Here, all the input punctuation was discarded.
+ </p><a id="id-1.5.11.6.4.11" class="indexterm"></a><pre class="synopsis">
+phraseto_tsquery([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>querytext</code></em> <code class="type">text</code>) returns <code class="type">tsquery</code>
+</pre><p>
+ <code class="function">phraseto_tsquery</code> behaves much like
+ <code class="function">plainto_tsquery</code>, except that it inserts
+ the <code class="literal">&lt;-&gt;</code> (FOLLOWED BY) operator between
+ surviving words instead of the <code class="literal">&amp;</code> (AND) operator.
+ Also, stop words are not simply discarded, but are accounted for by
+ inserting <code class="literal">&lt;<em class="replaceable"><code>N</code></em>&gt;</code> operators rather
+ than <code class="literal">&lt;-&gt;</code> operators. This function is useful
+ when searching for exact lexeme sequences, since the FOLLOWED BY
+ operators check lexeme order not just the presence of all the lexemes.
+ </p><p>
+ Example:
+
+</p><pre class="screen">
+SELECT phraseto_tsquery('english', 'The Fat Rats');
+ phraseto_tsquery
+------------------
+ 'fat' &lt;-&gt; 'rat'
+</pre><p>
+
+ Like <code class="function">plainto_tsquery</code>, the
+ <code class="function">phraseto_tsquery</code> function will not
+ recognize <code class="type">tsquery</code> operators, weight labels,
+ or prefix-match labels in its input:
+
+</p><pre class="screen">
+SELECT phraseto_tsquery('english', 'The Fat &amp; Rats:C');
+ phraseto_tsquery
+-----------------------------
+ 'fat' &lt;-&gt; 'rat' &lt;-&gt; 'c'
+</pre><p>
+ </p><pre class="synopsis">
+websearch_to_tsquery([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>querytext</code></em> <code class="type">text</code>) returns <code class="type">tsquery</code>
+</pre><p>
+ <code class="function">websearch_to_tsquery</code> creates a <code class="type">tsquery</code>
+ value from <em class="replaceable"><code>querytext</code></em> using an alternative
+ syntax in which simple unformatted text is a valid query.
+ Unlike <code class="function">plainto_tsquery</code>
+ and <code class="function">phraseto_tsquery</code>, it also recognizes certain
+ operators. Moreover, this function will never raise syntax errors,
+ which makes it possible to use raw user-supplied input for search.
+ The following syntax is supported:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">unquoted text</code>: text not inside quote marks will be
+ converted to terms separated by <code class="literal">&amp;</code> operators, as
+ if processed by <code class="function">plainto_tsquery</code>.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">"quoted text"</code>: text inside quote marks will be
+ converted to terms separated by <code class="literal">&lt;-&gt;</code>
+ operators, as if processed by <code class="function">phraseto_tsquery</code>.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">OR</code>: the word <span class="quote">“<span class="quote">or</span>”</span> will be converted to
+ the <code class="literal">|</code> operator.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">-</code>: a dash will be converted to
+ the <code class="literal">!</code> operator.
+ </p></li></ul></div><p>
+
+ Other punctuation is ignored. So
+ like <code class="function">plainto_tsquery</code>
+ and <code class="function">phraseto_tsquery</code>,
+ the <code class="function">websearch_to_tsquery</code> function will not
+ recognize <code class="type">tsquery</code> operators, weight labels, or prefix-match
+ labels in its input.
+ </p><p>
+ Examples:
+</p><pre class="screen">
+SELECT websearch_to_tsquery('english', 'The fat rats');
+ websearch_to_tsquery
+----------------------
+ 'fat' &amp; 'rat'
+(1 row)
+
+SELECT websearch_to_tsquery('english', '"supernovae stars" -crab');
+ websearch_to_tsquery
+----------------------------------
+ 'supernova' &lt;-&gt; 'star' &amp; !'crab'
+(1 row)
+
+SELECT websearch_to_tsquery('english', '"sad cat" or "fat rat"');
+ websearch_to_tsquery
+-----------------------------------
+ 'sad' &lt;-&gt; 'cat' | 'fat' &lt;-&gt; 'rat'
+(1 row)
+
+SELECT websearch_to_tsquery('english', 'signal -"segmentation fault"');
+ websearch_to_tsquery
+---------------------------------------
+ 'signal' &amp; !( 'segment' &lt;-&gt; 'fault' )
+(1 row)
+
+SELECT websearch_to_tsquery('english', '""" )( dummy \\ query &lt;-&gt;');
+ websearch_to_tsquery
+----------------------
+ 'dummi' &amp; 'queri'
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="TEXTSEARCH-RANKING"><div class="titlepage"><div><div><h3 class="title">12.3.3. Ranking Search Results</h3></div></div></div><p>
+ Ranking attempts to measure how relevant documents are to a particular
+ query, so that when there are many matches the most relevant ones can be
+ shown first. <span class="productname">PostgreSQL</span> provides two
+ predefined ranking functions, which take into account lexical, proximity,
+ and structural information; that is, they consider how often the query
+ terms appear in the document, how close together the terms are in the
+ document, and how important is the part of the document where they occur.
+ However, the concept of relevancy is vague and very application-specific.
+ Different applications might require additional information for ranking,
+ e.g., document modification time. The built-in ranking functions are only
+ examples. You can write your own ranking functions and/or combine their
+ results with additional factors to fit your specific needs.
+ </p><p>
+ The two ranking functions currently available are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <a id="id-1.5.11.6.5.3.1.1.1.1" class="indexterm"></a>
+
+ <code class="literal">ts_rank([<span class="optional"> <em class="replaceable"><code>weights</code></em> <code class="type">float4[]</code>, </span>] <em class="replaceable"><code>vector</code></em> <code class="type">tsvector</code>, <em class="replaceable"><code>query</code></em> <code class="type">tsquery</code> [<span class="optional">, <em class="replaceable"><code>normalization</code></em> <code class="type">integer</code> </span>]) returns <code class="type">float4</code></code>
+ </span></dt><dd><p>
+ Ranks vectors based on the frequency of their matching lexemes.
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.6.5.3.1.2.1.1" class="indexterm"></a>
+
+ <code class="literal">ts_rank_cd([<span class="optional"> <em class="replaceable"><code>weights</code></em> <code class="type">float4[]</code>, </span>] <em class="replaceable"><code>vector</code></em> <code class="type">tsvector</code>, <em class="replaceable"><code>query</code></em> <code class="type">tsquery</code> [<span class="optional">, <em class="replaceable"><code>normalization</code></em> <code class="type">integer</code> </span>]) returns <code class="type">float4</code></code>
+ </span></dt><dd><p>
+ This function computes the <em class="firstterm">cover density</em>
+ ranking for the given document vector and query, as described in
+ Clarke, Cormack, and Tudhope's "Relevance Ranking for One to Three
+ Term Queries" in the journal "Information Processing and Management",
+ 1999. Cover density is similar to <code class="function">ts_rank</code> ranking
+ except that the proximity of matching lexemes to each other is
+ taken into consideration.
+ </p><p>
+ This function requires lexeme positional information to perform
+ its calculation. Therefore, it ignores any <span class="quote">“<span class="quote">stripped</span>”</span>
+ lexemes in the <code class="type">tsvector</code>. If there are no unstripped
+ lexemes in the input, the result will be zero. (See <a class="xref" href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR" title="12.4.1. Manipulating Documents">Section 12.4.1</a> for more information
+ about the <code class="function">strip</code> function and positional information
+ in <code class="type">tsvector</code>s.)
+ </p></dd></dl></div><p>
+
+ </p><p>
+ For both these functions,
+ the optional <em class="replaceable"><code>weights</code></em>
+ argument offers the ability to weigh word instances more or less
+ heavily depending on how they are labeled. The weight arrays specify
+ how heavily to weigh each category of word, in the order:
+
+</p><pre class="synopsis">
+{D-weight, C-weight, B-weight, A-weight}
+</pre><p>
+
+ If no <em class="replaceable"><code>weights</code></em> are provided,
+ then these defaults are used:
+
+</p><pre class="programlisting">
+{0.1, 0.2, 0.4, 1.0}
+</pre><p>
+
+ Typically weights are used to mark words from special areas of the
+ document, like the title or an initial abstract, so they can be
+ treated with more or less importance than words in the document body.
+ </p><p>
+ Since a longer document has a greater chance of containing a query term
+ it is reasonable to take into account document size, e.g., a hundred-word
+ document with five instances of a search word is probably more relevant
+ than a thousand-word document with five instances. Both ranking functions
+ take an integer <em class="replaceable"><code>normalization</code></em> option that
+ specifies whether and how a document's length should impact its rank.
+ The integer option controls several behaviors, so it is a bit mask:
+ you can specify one or more behaviors using
+ <code class="literal">|</code> (for example, <code class="literal">2|4</code>).
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ 0 (the default) ignores the document length
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 1 divides the rank by 1 + the logarithm of the document length
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 2 divides the rank by the document length
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 4 divides the rank by the mean harmonic distance between extents
+ (this is implemented only by <code class="function">ts_rank_cd</code>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 8 divides the rank by the number of unique words in document
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 16 divides the rank by 1 + the logarithm of the number
+ of unique words in document
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ 32 divides the rank by itself + 1
+ </p></li></ul></div><p>
+
+ If more than one flag bit is specified, the transformations are
+ applied in the order listed.
+ </p><p>
+ It is important to note that the ranking functions do not use any global
+ information, so it is impossible to produce a fair normalization to 1% or
+ 100% as sometimes desired. Normalization option 32
+ (<code class="literal">rank/(rank+1)</code>) can be applied to scale all ranks
+ into the range zero to one, but of course this is just a cosmetic change;
+ it will not affect the ordering of the search results.
+ </p><p>
+ Here is an example that selects only the ten highest-ranked matches:
+
+</p><pre class="screen">
+SELECT title, ts_rank_cd(textsearch, query) AS rank
+FROM apod, to_tsquery('neutrino|(dark &amp; matter)') query
+WHERE query @@ textsearch
+ORDER BY rank DESC
+LIMIT 10;
+ title | rank
+-----------------------------------------------+----------
+ Neutrinos in the Sun | 3.1
+ The Sudbury Neutrino Detector | 2.4
+ A MACHO View of Galactic Dark Matter | 2.01317
+ Hot Gas and Dark Matter | 1.91171
+ The Virgo Cluster: Hot Plasma and Dark Matter | 1.90953
+ Rafting for Solar Neutrinos | 1.9
+ NGC 4650A: Strange Galaxy and Dark Matter | 1.85774
+ Hot Gas and Dark Matter | 1.6123
+ Ice Fishing for Cosmic Neutrinos | 1.6
+ Weak Lensing Distorts the Universe | 0.818218
+</pre><p>
+
+ This is the same example using normalized ranking:
+
+</p><pre class="screen">
+SELECT title, ts_rank_cd(textsearch, query, 32 /* rank/(rank+1) */ ) AS rank
+FROM apod, to_tsquery('neutrino|(dark &amp; matter)') query
+WHERE query @@ textsearch
+ORDER BY rank DESC
+LIMIT 10;
+ title | rank
+-----------------------------------------------+-------------------
+ Neutrinos in the Sun | 0.756097569485493
+ The Sudbury Neutrino Detector | 0.705882361190954
+ A MACHO View of Galactic Dark Matter | 0.668123210574724
+ Hot Gas and Dark Matter | 0.65655958650282
+ The Virgo Cluster: Hot Plasma and Dark Matter | 0.656301290640973
+ Rafting for Solar Neutrinos | 0.655172410958162
+ NGC 4650A: Strange Galaxy and Dark Matter | 0.650072921219637
+ Hot Gas and Dark Matter | 0.617195790024749
+ Ice Fishing for Cosmic Neutrinos | 0.615384618911517
+ Weak Lensing Distorts the Universe | 0.450010798361481
+</pre><p>
+ </p><p>
+ Ranking can be expensive since it requires consulting the
+ <code class="type">tsvector</code> of each matching document, which can be I/O bound and
+ therefore slow. Unfortunately, it is almost impossible to avoid since
+ practical queries often result in large numbers of matches.
+ </p></div><div class="sect2" id="TEXTSEARCH-HEADLINE"><div class="titlepage"><div><div><h3 class="title">12.3.4. Highlighting Results</h3></div></div></div><p>
+ To present search results it is ideal to show a part of each document and
+ how it is related to the query. Usually, search engines show fragments of
+ the document with marked search terms. <span class="productname">PostgreSQL</span>
+ provides a function <code class="function">ts_headline</code> that
+ implements this functionality.
+ </p><a id="id-1.5.11.6.6.3" class="indexterm"></a><pre class="synopsis">
+ts_headline([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>document</code></em> <code class="type">text</code>, <em class="replaceable"><code>query</code></em> <code class="type">tsquery</code> [<span class="optional">, <em class="replaceable"><code>options</code></em> <code class="type">text</code> </span>]) returns <code class="type">text</code>
+</pre><p>
+ <code class="function">ts_headline</code> accepts a document along
+ with a query, and returns an excerpt from
+ the document in which terms from the query are highlighted. The
+ configuration to be used to parse the document can be specified by
+ <em class="replaceable"><code>config</code></em>; if <em class="replaceable"><code>config</code></em>
+ is omitted, the
+ <code class="varname">default_text_search_config</code> configuration is used.
+ </p><p>
+ If an <em class="replaceable"><code>options</code></em> string is specified it must
+ consist of a comma-separated list of one or more
+ <em class="replaceable"><code>option</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em> pairs.
+ The available options are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">MaxWords</code>, <code class="literal">MinWords</code> (integers):
+ these numbers determine the longest and shortest headlines to output.
+ The default values are 35 and 15.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">ShortWord</code> (integer): words of this length or less
+ will be dropped at the start and end of a headline, unless they are
+ query terms. The default value of three eliminates common English
+ articles.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">HighlightAll</code> (boolean): if
+ <code class="literal">true</code> the whole document will be used as the
+ headline, ignoring the preceding three parameters. The default
+ is <code class="literal">false</code>.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">MaxFragments</code> (integer): maximum number of text
+ fragments to display. The default value of zero selects a
+ non-fragment-based headline generation method. A value greater
+ than zero selects fragment-based headline generation (see below).
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">StartSel</code>, <code class="literal">StopSel</code> (strings):
+ the strings with which to delimit query words appearing in the
+ document, to distinguish them from other excerpted words. The
+ default values are <span class="quote">“<span class="quote"><code class="literal">&lt;b&gt;</code></span>”</span> and
+ <span class="quote">“<span class="quote"><code class="literal">&lt;/b&gt;</code></span>”</span>, which can be suitable
+ for HTML output.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">FragmentDelimiter</code> (string): When more than one
+ fragment is displayed, the fragments will be separated by this string.
+ The default is <span class="quote">“<span class="quote"><code class="literal"> ... </code></span>”</span>.
+ </p></li></ul></div><p>
+
+ These option names are recognized case-insensitively.
+ You must double-quote string values if they contain spaces or commas.
+ </p><p>
+ In non-fragment-based headline
+ generation, <code class="function">ts_headline</code> locates matches for the
+ given <em class="replaceable"><code>query</code></em> and chooses a
+ single one to display, preferring matches that have more query words
+ within the allowed headline length.
+ In fragment-based headline generation, <code class="function">ts_headline</code>
+ locates the query matches and splits each match
+ into <span class="quote">“<span class="quote">fragments</span>”</span> of no more than <code class="literal">MaxWords</code>
+ words each, preferring fragments with more query words, and when
+ possible <span class="quote">“<span class="quote">stretching</span>”</span> fragments to include surrounding
+ words. The fragment-based mode is thus more useful when the query
+ matches span large sections of the document, or when it's desirable to
+ display multiple matches.
+ In either mode, if no query matches can be identified, then a single
+ fragment of the first <code class="literal">MinWords</code> words in the document
+ will be displayed.
+ </p><p>
+ For example:
+
+</p><pre class="screen">
+SELECT ts_headline('english',
+ 'The most common type of search
+is to find all documents containing given query terms
+and return them in order of their similarity to the
+query.',
+ to_tsquery('english', 'query &amp; similarity'));
+ ts_headline
+------------------------------------------------------------
+ containing given &lt;b&gt;query&lt;/b&gt; terms +
+ and return them in order of their &lt;b&gt;similarity&lt;/b&gt; to the+
+ &lt;b&gt;query&lt;/b&gt;.
+
+SELECT ts_headline('english',
+ 'Search terms may occur
+many times in a document,
+requiring ranking of the search matches to decide which
+occurrences to display in the result.',
+ to_tsquery('english', 'search &amp; term'),
+ 'MaxFragments=10, MaxWords=7, MinWords=3, StartSel=&lt;&lt;, StopSel=&gt;&gt;');
+ ts_headline
+------------------------------------------------------------
+ &lt;&lt;Search&gt;&gt; &lt;&lt;terms&gt;&gt; may occur +
+ many times ... ranking of the &lt;&lt;search&gt;&gt; matches to decide
+</pre><p>
+ </p><p>
+ <code class="function">ts_headline</code> uses the original document, not a
+ <code class="type">tsvector</code> summary, so it can be slow and should be used with
+ care.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-tables.html" title="12.2. Tables and Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-features.html" title="12.4. Additional Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.2. Tables and Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.4. Additional Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-debugging.html b/doc/src/sgml/html/textsearch-debugging.html
new file mode 100644
index 0000000..6ee63fa
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-debugging.html
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.8. Testing and Debugging Text Search</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-configuration.html" title="12.7. Configuration Example" /><link rel="next" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.8. Testing and Debugging Text Search</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-configuration.html" title="12.7. Configuration Example">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-DEBUGGING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.8. Testing and Debugging Text Search</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-CONFIGURATION-TESTING">12.8.1. Configuration Testing</a></span></dt><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING">12.8.2. Parser Testing</a></span></dt><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-DICTIONARY-TESTING">12.8.3. Dictionary Testing</a></span></dt></dl></div><p>
+ The behavior of a custom text search configuration can easily become
+ confusing. The functions described
+ in this section are useful for testing text search objects. You can
+ test a complete configuration, or test parsers and dictionaries separately.
+ </p><div class="sect2" id="TEXTSEARCH-CONFIGURATION-TESTING"><div class="titlepage"><div><div><h3 class="title">12.8.1. Configuration Testing</h3></div></div></div><p>
+ The function <code class="function">ts_debug</code> allows easy testing of a
+ text search configuration.
+ </p><a id="id-1.5.11.11.3.3" class="indexterm"></a><pre class="synopsis">
+ts_debug([<span class="optional"> <em class="replaceable"><code>config</code></em> <code class="type">regconfig</code>, </span>] <em class="replaceable"><code>document</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>alias</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>description</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>token</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>dictionaries</code></em> <code class="type">regdictionary[]</code>,
+ OUT <em class="replaceable"><code>dictionary</code></em> <code class="type">regdictionary</code>,
+ OUT <em class="replaceable"><code>lexemes</code></em> <code class="type">text[]</code>)
+ returns setof record
+</pre><p>
+ <code class="function">ts_debug</code> displays information about every token of
+ <em class="replaceable"><code>document</code></em> as produced by the
+ parser and processed by the configured dictionaries. It uses the
+ configuration specified by <em class="replaceable"><code>config</code></em>,
+ or <code class="varname">default_text_search_config</code> if that argument is
+ omitted.
+ </p><p>
+ <code class="function">ts_debug</code> returns one row for each token identified in the text
+ by the parser. The columns returned are
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>alias</code></em> <code class="type">text</code> — short name of the token type
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>description</code></em> <code class="type">text</code> — description of the
+ token type
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>token</code></em> <code class="type">text</code> — text of the token
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>dictionaries</code></em> <code class="type">regdictionary[]</code> — the
+ dictionaries selected by the configuration for this token type
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>dictionary</code></em> <code class="type">regdictionary</code> — the dictionary
+ that recognized the token, or <code class="literal">NULL</code> if none did
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>lexemes</code></em> <code class="type">text[]</code> — the lexeme(s) produced
+ by the dictionary that recognized the token, or <code class="literal">NULL</code> if
+ none did; an empty array (<code class="literal">{}</code>) means it was recognized as a
+ stop word
+ </p></li></ul></div><p>
+ </p><p>
+ Here is a simple example:
+
+</p><pre class="screen">
+SELECT * FROM ts_debug('english', 'a fat cat sat on a mat - it ate a fat rats');
+ alias | description | token | dictionaries | dictionary | lexemes
+-----------+-----------------+-------+----------------+--------------+---------
+ asciiword | Word, all ASCII | a | {english_stem} | english_stem | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | fat | {english_stem} | english_stem | {fat}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | cat | {english_stem} | english_stem | {cat}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | sat | {english_stem} | english_stem | {sat}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | on | {english_stem} | english_stem | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | a | {english_stem} | english_stem | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | mat | {english_stem} | english_stem | {mat}
+ blank | Space symbols | | {} | |
+ blank | Space symbols | - | {} | |
+ asciiword | Word, all ASCII | it | {english_stem} | english_stem | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | ate | {english_stem} | english_stem | {ate}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | a | {english_stem} | english_stem | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | fat | {english_stem} | english_stem | {fat}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | rats | {english_stem} | english_stem | {rat}
+</pre><p>
+ </p><p>
+ For a more extensive demonstration, we
+ first create a <code class="literal">public.english</code> configuration and
+ Ispell dictionary for the English language:
+ </p><pre class="programlisting">
+CREATE TEXT SEARCH CONFIGURATION public.english ( COPY = pg_catalog.english );
+
+CREATE TEXT SEARCH DICTIONARY english_ispell (
+ TEMPLATE = ispell,
+ DictFile = english,
+ AffFile = english,
+ StopWords = english
+);
+
+ALTER TEXT SEARCH CONFIGURATION public.english
+ ALTER MAPPING FOR asciiword WITH english_ispell, english_stem;
+</pre><pre class="screen">
+SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes');
+ alias | description | token | dictionaries | dictionary | lexemes
+-----------+-----------------+-------------+-------------------------------+----------------+-------------
+ asciiword | Word, all ASCII | The | {english_ispell,english_stem} | english_ispell | {}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | Brightest | {english_ispell,english_stem} | english_ispell | {bright}
+ blank | Space symbols | | {} | |
+ asciiword | Word, all ASCII | supernovaes | {english_ispell,english_stem} | english_stem | {supernova}
+</pre><p>
+ In this example, the word <code class="literal">Brightest</code> was recognized by the
+ parser as an <code class="literal">ASCII word</code> (alias <code class="literal">asciiword</code>).
+ For this token type the dictionary list is
+ <code class="literal">english_ispell</code> and
+ <code class="literal">english_stem</code>. The word was recognized by
+ <code class="literal">english_ispell</code>, which reduced it to the noun
+ <code class="literal">bright</code>. The word <code class="literal">supernovaes</code> is
+ unknown to the <code class="literal">english_ispell</code> dictionary so it
+ was passed to the next dictionary, and, fortunately, was recognized (in
+ fact, <code class="literal">english_stem</code> is a Snowball dictionary which
+ recognizes everything; that is why it was placed at the end of the
+ dictionary list).
+ </p><p>
+ The word <code class="literal">The</code> was recognized by the
+ <code class="literal">english_ispell</code> dictionary as a stop word (<a class="xref" href="textsearch-dictionaries.html#TEXTSEARCH-STOPWORDS" title="12.6.1. Stop Words">Section 12.6.1</a>) and will not be indexed.
+ The spaces are discarded too, since the configuration provides no
+ dictionaries at all for them.
+ </p><p>
+ You can reduce the width of the output by explicitly specifying which columns
+ you want to see:
+
+</p><pre class="screen">
+SELECT alias, token, dictionary, lexemes
+FROM ts_debug('public.english', 'The Brightest supernovaes');
+ alias | token | dictionary | lexemes
+-----------+-------------+----------------+-------------
+ asciiword | The | english_ispell | {}
+ blank | | |
+ asciiword | Brightest | english_ispell | {bright}
+ blank | | |
+ asciiword | supernovaes | english_stem | {supernova}
+</pre><p>
+ </p></div><div class="sect2" id="TEXTSEARCH-PARSER-TESTING"><div class="titlepage"><div><div><h3 class="title">12.8.2. Parser Testing</h3></div></div></div><p>
+ The following functions allow direct testing of a text search parser.
+ </p><a id="id-1.5.11.11.4.3" class="indexterm"></a><pre class="synopsis">
+ts_parse(<em class="replaceable"><code>parser_name</code></em> <code class="type">text</code>, <em class="replaceable"><code>document</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>tokid</code></em> <code class="type">integer</code>, OUT <em class="replaceable"><code>token</code></em> <code class="type">text</code>) returns <code class="type">setof record</code>
+ts_parse(<em class="replaceable"><code>parser_oid</code></em> <code class="type">oid</code>, <em class="replaceable"><code>document</code></em> <code class="type">text</code>,
+ OUT <em class="replaceable"><code>tokid</code></em> <code class="type">integer</code>, OUT <em class="replaceable"><code>token</code></em> <code class="type">text</code>) returns <code class="type">setof record</code>
+</pre><p>
+ <code class="function">ts_parse</code> parses the given <em class="replaceable"><code>document</code></em>
+ and returns a series of records, one for each token produced by
+ parsing. Each record includes a <code class="varname">tokid</code> showing the
+ assigned token type and a <code class="varname">token</code> which is the text of the
+ token. For example:
+
+</p><pre class="screen">
+SELECT * FROM ts_parse('default', '123 - a number');
+ tokid | token
+-------+--------
+ 22 | 123
+ 12 |
+ 12 | -
+ 1 | a
+ 12 |
+ 1 | number
+</pre><p>
+ </p><a id="id-1.5.11.11.4.6" class="indexterm"></a><pre class="synopsis">
+ts_token_type(<em class="replaceable"><code>parser_name</code></em> <code class="type">text</code>, OUT <em class="replaceable"><code>tokid</code></em> <code class="type">integer</code>,
+ OUT <em class="replaceable"><code>alias</code></em> <code class="type">text</code>, OUT <em class="replaceable"><code>description</code></em> <code class="type">text</code>) returns <code class="type">setof record</code>
+ts_token_type(<em class="replaceable"><code>parser_oid</code></em> <code class="type">oid</code>, OUT <em class="replaceable"><code>tokid</code></em> <code class="type">integer</code>,
+ OUT <em class="replaceable"><code>alias</code></em> <code class="type">text</code>, OUT <em class="replaceable"><code>description</code></em> <code class="type">text</code>) returns <code class="type">setof record</code>
+</pre><p>
+ <code class="function">ts_token_type</code> returns a table which describes each type of
+ token the specified parser can recognize. For each token type, the table
+ gives the integer <code class="varname">tokid</code> that the parser uses to label a
+ token of that type, the <code class="varname">alias</code> that names the token type
+ in configuration commands, and a short <code class="varname">description</code>. For
+ example:
+
+</p><pre class="screen">
+SELECT * FROM ts_token_type('default');
+ tokid | alias | description
+-------+-----------------+------------------------------------------
+ 1 | asciiword | Word, all ASCII
+ 2 | word | Word, all letters
+ 3 | numword | Word, letters and digits
+ 4 | email | Email address
+ 5 | url | URL
+ 6 | host | Host
+ 7 | sfloat | Scientific notation
+ 8 | version | Version number
+ 9 | hword_numpart | Hyphenated word part, letters and digits
+ 10 | hword_part | Hyphenated word part, all letters
+ 11 | hword_asciipart | Hyphenated word part, all ASCII
+ 12 | blank | Space symbols
+ 13 | tag | XML tag
+ 14 | protocol | Protocol head
+ 15 | numhword | Hyphenated word, letters and digits
+ 16 | asciihword | Hyphenated word, all ASCII
+ 17 | hword | Hyphenated word, all letters
+ 18 | url_path | URL path
+ 19 | file | File or path name
+ 20 | float | Decimal notation
+ 21 | int | Signed integer
+ 22 | uint | Unsigned integer
+ 23 | entity | XML entity
+</pre><p>
+ </p></div><div class="sect2" id="TEXTSEARCH-DICTIONARY-TESTING"><div class="titlepage"><div><div><h3 class="title">12.8.3. Dictionary Testing</h3></div></div></div><p>
+ The <code class="function">ts_lexize</code> function facilitates dictionary testing.
+ </p><a id="id-1.5.11.11.5.3" class="indexterm"></a><pre class="synopsis">
+ts_lexize(<em class="replaceable"><code>dict</code></em> <code class="type">regdictionary</code>, <em class="replaceable"><code>token</code></em> <code class="type">text</code>) returns <code class="type">text[]</code>
+</pre><p>
+ <code class="function">ts_lexize</code> returns an array of lexemes if the input
+ <em class="replaceable"><code>token</code></em> is known to the dictionary,
+ or an empty array if the token
+ is known to the dictionary but it is a stop word, or
+ <code class="literal">NULL</code> if it is an unknown word.
+ </p><p>
+ Examples:
+
+</p><pre class="screen">
+SELECT ts_lexize('english_stem', 'stars');
+ ts_lexize
+-----------
+ {star}
+
+SELECT ts_lexize('english_stem', 'a');
+ ts_lexize
+-----------
+ {}
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <code class="function">ts_lexize</code> function expects a single
+ <span class="emphasis"><em>token</em></span>, not text. Here is a case
+ where this can be confusing:
+
+</p><pre class="screen">
+SELECT ts_lexize('thesaurus_astro', 'supernovae stars') is null;
+ ?column?
+----------
+ t
+</pre><p>
+
+ The thesaurus dictionary <code class="literal">thesaurus_astro</code> does know the
+ phrase <code class="literal">supernovae stars</code>, but <code class="function">ts_lexize</code>
+ fails since it does not parse the input text but treats it as a single
+ token. Use <code class="function">plainto_tsquery</code> or <code class="function">to_tsvector</code> to
+ test thesaurus dictionaries, for example:
+
+</p><pre class="screen">
+SELECT plainto_tsquery('supernovae stars');
+ plainto_tsquery
+-----------------
+ 'sn'
+</pre><p>
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-configuration.html" title="12.7. Configuration Example">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.7. Configuration Example </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.9. Preferred Index Types for Text Search</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-dictionaries.html b/doc/src/sgml/html/textsearch-dictionaries.html
new file mode 100644
index 0000000..be0b365
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-dictionaries.html
@@ -0,0 +1,661 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.6. Dictionaries</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-parsers.html" title="12.5. Parsers" /><link rel="next" href="textsearch-configuration.html" title="12.7. Configuration Example" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.6. Dictionaries</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-parsers.html" title="12.5. Parsers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-configuration.html" title="12.7. Configuration Example">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-DICTIONARIES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.6. Dictionaries</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-STOPWORDS">12.6.1. Stop Words</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SIMPLE-DICTIONARY">12.6.2. Simple Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SYNONYM-DICTIONARY">12.6.3. Synonym Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-THESAURUS">12.6.4. Thesaurus Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-ISPELL-DICTIONARY">12.6.5. <span class="application">Ispell</span> Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SNOWBALL-DICTIONARY">12.6.6. <span class="application">Snowball</span> Dictionary</a></span></dt></dl></div><p>
+ Dictionaries are used to eliminate words that should not be considered in a
+ search (<em class="firstterm">stop words</em>), and to <em class="firstterm">normalize</em> words so
+ that different derived forms of the same word will match. A successfully
+ normalized word is called a <em class="firstterm">lexeme</em>. Aside from
+ improving search quality, normalization and removal of stop words reduce the
+ size of the <code class="type">tsvector</code> representation of a document, thereby
+ improving performance. Normalization does not always have linguistic meaning
+ and usually depends on application semantics.
+ </p><p>
+ Some examples of normalization:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ Linguistic — Ispell dictionaries try to reduce input words to a
+ normalized form; stemmer dictionaries remove word endings
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <acronym class="acronym">URL</acronym> locations can be canonicalized to make
+ equivalent URLs match:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ http://www.pgsql.ru/db/mw/index.html
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ http://www.pgsql.ru/db/mw/
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ http://www.pgsql.ru/db/../db/mw/index.html
+ </p></li></ul></div><p>
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Color names can be replaced by their hexadecimal values, e.g.,
+ <code class="literal">red, green, blue, magenta -&gt; FF0000, 00FF00, 0000FF, FF00FF</code>
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ If indexing numbers, we can
+ remove some fractional digits to reduce the range of possible
+ numbers, so for example <span class="emphasis"><em>3.14</em></span>159265359,
+ <span class="emphasis"><em>3.14</em></span>15926, <span class="emphasis"><em>3.14</em></span> will be the same
+ after normalization if only two digits are kept after the decimal point.
+ </p></li></ul></div><p>
+
+ </p><p>
+ A dictionary is a program that accepts a token as
+ input and returns:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ an array of lexemes if the input token is known to the dictionary
+ (notice that one token can produce more than one lexeme)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ a single lexeme with the <code class="literal">TSL_FILTER</code> flag set, to replace
+ the original token with a new token to be passed to subsequent
+ dictionaries (a dictionary that does this is called a
+ <em class="firstterm">filtering dictionary</em>)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ an empty array if the dictionary knows the token, but it is a stop word
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">NULL</code> if the dictionary does not recognize the input token
+ </p></li></ul></div><p>
+ </p><p>
+ <span class="productname">PostgreSQL</span> provides predefined dictionaries for
+ many languages. There are also several predefined templates that can be
+ used to create new dictionaries with custom parameters. Each predefined
+ dictionary template is described below. If no existing
+ template is suitable, it is possible to create new ones; see the
+ <code class="filename">contrib/</code> area of the <span class="productname">PostgreSQL</span> distribution
+ for examples.
+ </p><p>
+ A text search configuration binds a parser together with a set of
+ dictionaries to process the parser's output tokens. For each token
+ type that the parser can return, a separate list of dictionaries is
+ specified by the configuration. When a token of that type is found
+ by the parser, each dictionary in the list is consulted in turn,
+ until some dictionary recognizes it as a known word. If it is identified
+ as a stop word, or if no dictionary recognizes the token, it will be
+ discarded and not indexed or searched for.
+ Normally, the first dictionary that returns a non-<code class="literal">NULL</code>
+ output determines the result, and any remaining dictionaries are not
+ consulted; but a filtering dictionary can replace the given word
+ with a modified word, which is then passed to subsequent dictionaries.
+ </p><p>
+ The general rule for configuring a list of dictionaries
+ is to place first the most narrow, most specific dictionary, then the more
+ general dictionaries, finishing with a very general dictionary, like
+ a <span class="application">Snowball</span> stemmer or <code class="literal">simple</code>, which
+ recognizes everything. For example, for an astronomy-specific search
+ (<code class="literal">astro_en</code> configuration) one could bind token type
+ <code class="type">asciiword</code> (ASCII word) to a synonym dictionary of astronomical
+ terms, a general English dictionary and a <span class="application">Snowball</span> English
+ stemmer:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION astro_en
+ ADD MAPPING FOR asciiword WITH astrosyn, english_ispell, english_stem;
+</pre><p>
+ </p><p>
+ A filtering dictionary can be placed anywhere in the list, except at the
+ end where it'd be useless. Filtering dictionaries are useful to partially
+ normalize words to simplify the task of later dictionaries. For example,
+ a filtering dictionary could be used to remove accents from accented
+ letters, as is done by the <a class="xref" href="unaccent.html" title="F.48. unaccent">unaccent</a> module.
+ </p><div class="sect2" id="TEXTSEARCH-STOPWORDS"><div class="titlepage"><div><div><h3 class="title">12.6.1. Stop Words</h3></div></div></div><p>
+ Stop words are words that are very common, appear in almost every
+ document, and have no discrimination value. Therefore, they can be ignored
+ in the context of full text searching. For example, every English text
+ contains words like <code class="literal">a</code> and <code class="literal">the</code>, so it is
+ useless to store them in an index. However, stop words do affect the
+ positions in <code class="type">tsvector</code>, which in turn affect ranking:
+
+</p><pre class="screen">
+SELECT to_tsvector('english', 'in the list of stop words');
+ to_tsvector
+----------------------------
+ 'list':3 'stop':5 'word':6
+</pre><p>
+
+ The missing positions 1,2,4 are because of stop words. Ranks
+ calculated for documents with and without stop words are quite different:
+
+</p><pre class="screen">
+SELECT ts_rank_cd (to_tsvector('english', 'in the list of stop words'), to_tsquery('list &amp; stop'));
+ ts_rank_cd
+------------
+ 0.05
+
+SELECT ts_rank_cd (to_tsvector('english', 'list stop words'), to_tsquery('list &amp; stop'));
+ ts_rank_cd
+------------
+ 0.1
+</pre><p>
+
+ </p><p>
+ It is up to the specific dictionary how it treats stop words. For example,
+ <code class="literal">ispell</code> dictionaries first normalize words and then
+ look at the list of stop words, while <code class="literal">Snowball</code> stemmers
+ first check the list of stop words. The reason for the different
+ behavior is an attempt to decrease noise.
+ </p></div><div class="sect2" id="TEXTSEARCH-SIMPLE-DICTIONARY"><div class="titlepage"><div><div><h3 class="title">12.6.2. Simple Dictionary</h3></div></div></div><p>
+ The <code class="literal">simple</code> dictionary template operates by converting the
+ input token to lower case and checking it against a file of stop words.
+ If it is found in the file then an empty array is returned, causing
+ the token to be discarded. If not, the lower-cased form of the word
+ is returned as the normalized lexeme. Alternatively, the dictionary
+ can be configured to report non-stop-words as unrecognized, allowing
+ them to be passed on to the next dictionary in the list.
+ </p><p>
+ Here is an example of a dictionary definition using the <code class="literal">simple</code>
+ template:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY public.simple_dict (
+ TEMPLATE = pg_catalog.simple,
+ STOPWORDS = english
+);
+</pre><p>
+
+ Here, <code class="literal">english</code> is the base name of a file of stop words.
+ The file's full name will be
+ <code class="filename">$SHAREDIR/tsearch_data/english.stop</code>,
+ where <code class="literal">$SHAREDIR</code> means the
+ <span class="productname">PostgreSQL</span> installation's shared-data directory,
+ often <code class="filename">/usr/local/share/postgresql</code> (use <code class="command">pg_config
+ --sharedir</code> to determine it if you're not sure).
+ The file format is simply a list
+ of words, one per line. Blank lines and trailing spaces are ignored,
+ and upper case is folded to lower case, but no other processing is done
+ on the file contents.
+ </p><p>
+ Now we can test our dictionary:
+
+</p><pre class="screen">
+SELECT ts_lexize('public.simple_dict', 'YeS');
+ ts_lexize
+-----------
+ {yes}
+
+SELECT ts_lexize('public.simple_dict', 'The');
+ ts_lexize
+-----------
+ {}
+</pre><p>
+ </p><p>
+ We can also choose to return <code class="literal">NULL</code>, instead of the lower-cased
+ word, if it is not found in the stop words file. This behavior is
+ selected by setting the dictionary's <code class="literal">Accept</code> parameter to
+ <code class="literal">false</code>. Continuing the example:
+
+</p><pre class="screen">
+ALTER TEXT SEARCH DICTIONARY public.simple_dict ( Accept = false );
+
+SELECT ts_lexize('public.simple_dict', 'YeS');
+ ts_lexize
+-----------
+
+
+SELECT ts_lexize('public.simple_dict', 'The');
+ ts_lexize
+-----------
+ {}
+</pre><p>
+ </p><p>
+ With the default setting of <code class="literal">Accept</code> = <code class="literal">true</code>,
+ it is only useful to place a <code class="literal">simple</code> dictionary at the end
+ of a list of dictionaries, since it will never pass on any token to
+ a following dictionary. Conversely, <code class="literal">Accept</code> = <code class="literal">false</code>
+ is only useful when there is at least one following dictionary.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Most types of dictionaries rely on configuration files, such as files of
+ stop words. These files <span class="emphasis"><em>must</em></span> be stored in UTF-8 encoding.
+ They will be translated to the actual database encoding, if that is
+ different, when they are read into the server.
+ </p></div><div class="caution"><h3 class="title">Caution</h3><p>
+ Normally, a database session will read a dictionary configuration file
+ only once, when it is first used within the session. If you modify a
+ configuration file and want to force existing sessions to pick up the
+ new contents, issue an <code class="command">ALTER TEXT SEARCH DICTIONARY</code> command
+ on the dictionary. This can be a <span class="quote">“<span class="quote">dummy</span>”</span> update that doesn't
+ actually change any parameter values.
+ </p></div></div><div class="sect2" id="TEXTSEARCH-SYNONYM-DICTIONARY"><div class="titlepage"><div><div><h3 class="title">12.6.3. Synonym Dictionary</h3></div></div></div><p>
+ This dictionary template is used to create dictionaries that replace a
+ word with a synonym. Phrases are not supported (use the thesaurus
+ template (<a class="xref" href="textsearch-dictionaries.html#TEXTSEARCH-THESAURUS" title="12.6.4. Thesaurus Dictionary">Section 12.6.4</a>) for that). A synonym
+ dictionary can be used to overcome linguistic problems, for example, to
+ prevent an English stemmer dictionary from reducing the word <span class="quote">“<span class="quote">Paris</span>”</span> to
+ <span class="quote">“<span class="quote">pari</span>”</span>. It is enough to have a <code class="literal">Paris paris</code> line in the
+ synonym dictionary and put it before the <code class="literal">english_stem</code>
+ dictionary. For example:
+
+</p><pre class="screen">
+SELECT * FROM ts_debug('english', 'Paris');
+ alias | description | token | dictionaries | dictionary | lexemes
+-----------+-----------------+-------+----------------+--------------+---------
+ asciiword | Word, all ASCII | Paris | {english_stem} | english_stem | {pari}
+
+CREATE TEXT SEARCH DICTIONARY my_synonym (
+ TEMPLATE = synonym,
+ SYNONYMS = my_synonyms
+);
+
+ALTER TEXT SEARCH CONFIGURATION english
+ ALTER MAPPING FOR asciiword
+ WITH my_synonym, english_stem;
+
+SELECT * FROM ts_debug('english', 'Paris');
+ alias | description | token | dictionaries | dictionary | lexemes
+-----------+-----------------+-------+---------------------------+------------+---------
+ asciiword | Word, all ASCII | Paris | {my_synonym,english_stem} | my_synonym | {paris}
+</pre><p>
+ </p><p>
+ The only parameter required by the <code class="literal">synonym</code> template is
+ <code class="literal">SYNONYMS</code>, which is the base name of its configuration file
+ — <code class="literal">my_synonyms</code> in the above example.
+ The file's full name will be
+ <code class="filename">$SHAREDIR/tsearch_data/my_synonyms.syn</code>
+ (where <code class="literal">$SHAREDIR</code> means the
+ <span class="productname">PostgreSQL</span> installation's shared-data directory).
+ The file format is just one line
+ per word to be substituted, with the word followed by its synonym,
+ separated by white space. Blank lines and trailing spaces are ignored.
+ </p><p>
+ The <code class="literal">synonym</code> template also has an optional parameter
+ <code class="literal">CaseSensitive</code>, which defaults to <code class="literal">false</code>. When
+ <code class="literal">CaseSensitive</code> is <code class="literal">false</code>, words in the synonym file
+ are folded to lower case, as are input tokens. When it is
+ <code class="literal">true</code>, words and tokens are not folded to lower case,
+ but are compared as-is.
+ </p><p>
+ An asterisk (<code class="literal">*</code>) can be placed at the end of a synonym
+ in the configuration file. This indicates that the synonym is a prefix.
+ The asterisk is ignored when the entry is used in
+ <code class="function">to_tsvector()</code>, but when it is used in
+ <code class="function">to_tsquery()</code>, the result will be a query item with
+ the prefix match marker (see
+ <a class="xref" href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES" title="12.3.2. Parsing Queries">Section 12.3.2</a>).
+ For example, suppose we have these entries in
+ <code class="filename">$SHAREDIR/tsearch_data/synonym_sample.syn</code>:
+</p><pre class="programlisting">
+postgres pgsql
+postgresql pgsql
+postgre pgsql
+gogle googl
+indices index*
+</pre><p>
+ Then we will get these results:
+</p><pre class="screen">
+mydb=# CREATE TEXT SEARCH DICTIONARY syn (template=synonym, synonyms='synonym_sample');
+mydb=# SELECT ts_lexize('syn', 'indices');
+ ts_lexize
+-----------
+ {index}
+(1 row)
+
+mydb=# CREATE TEXT SEARCH CONFIGURATION tst (copy=simple);
+mydb=# ALTER TEXT SEARCH CONFIGURATION tst ALTER MAPPING FOR asciiword WITH syn;
+mydb=# SELECT to_tsvector('tst', 'indices');
+ to_tsvector
+-------------
+ 'index':1
+(1 row)
+
+mydb=# SELECT to_tsquery('tst', 'indices');
+ to_tsquery
+------------
+ 'index':*
+(1 row)
+
+mydb=# SELECT 'indexes are very useful'::tsvector;
+ tsvector
+---------------------------------
+ 'are' 'indexes' 'useful' 'very'
+(1 row)
+
+mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices');
+ ?column?
+----------
+ t
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="TEXTSEARCH-THESAURUS"><div class="titlepage"><div><div><h3 class="title">12.6.4. Thesaurus Dictionary</h3></div></div></div><p>
+ A thesaurus dictionary (sometimes abbreviated as <acronym class="acronym">TZ</acronym>) is
+ a collection of words that includes information about the relationships
+ of words and phrases, i.e., broader terms (<acronym class="acronym">BT</acronym>), narrower
+ terms (<acronym class="acronym">NT</acronym>), preferred terms, non-preferred terms, related
+ terms, etc.
+ </p><p>
+ Basically a thesaurus dictionary replaces all non-preferred terms by one
+ preferred term and, optionally, preserves the original terms for indexing
+ as well. <span class="productname">PostgreSQL</span>'s current implementation of the
+ thesaurus dictionary is an extension of the synonym dictionary with added
+ <em class="firstterm">phrase</em> support. A thesaurus dictionary requires
+ a configuration file of the following format:
+
+</p><pre class="programlisting">
+# this is a comment
+sample word(s) : indexed word(s)
+more sample word(s) : more indexed word(s)
+...
+</pre><p>
+
+ where the colon (<code class="symbol">:</code>) symbol acts as a delimiter between a
+ phrase and its replacement.
+ </p><p>
+ A thesaurus dictionary uses a <em class="firstterm">subdictionary</em> (which
+ is specified in the dictionary's configuration) to normalize the input
+ text before checking for phrase matches. It is only possible to select one
+ subdictionary. An error is reported if the subdictionary fails to
+ recognize a word. In that case, you should remove the use of the word or
+ teach the subdictionary about it. You can place an asterisk
+ (<code class="symbol">*</code>) at the beginning of an indexed word to skip applying
+ the subdictionary to it, but all sample words <span class="emphasis"><em>must</em></span> be known
+ to the subdictionary.
+ </p><p>
+ The thesaurus dictionary chooses the longest match if there are multiple
+ phrases matching the input, and ties are broken by using the last
+ definition.
+ </p><p>
+ Specific stop words recognized by the subdictionary cannot be
+ specified; instead use <code class="literal">?</code> to mark the location where any
+ stop word can appear. For example, assuming that <code class="literal">a</code> and
+ <code class="literal">the</code> are stop words according to the subdictionary:
+
+</p><pre class="programlisting">
+? one ? two : swsw
+</pre><p>
+
+ matches <code class="literal">a one the two</code> and <code class="literal">the one a two</code>;
+ both would be replaced by <code class="literal">swsw</code>.
+ </p><p>
+ Since a thesaurus dictionary has the capability to recognize phrases it
+ must remember its state and interact with the parser. A thesaurus dictionary
+ uses these assignments to check if it should handle the next word or stop
+ accumulation. The thesaurus dictionary must be configured
+ carefully. For example, if the thesaurus dictionary is assigned to handle
+ only the <code class="literal">asciiword</code> token, then a thesaurus dictionary
+ definition like <code class="literal">one 7</code> will not work since token type
+ <code class="literal">uint</code> is not assigned to the thesaurus dictionary.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ Thesauruses are used during indexing so any change in the thesaurus
+ dictionary's parameters <span class="emphasis"><em>requires</em></span> reindexing.
+ For most other dictionary types, small changes such as adding or
+ removing stopwords does not force reindexing.
+ </p></div><div class="sect3" id="TEXTSEARCH-THESAURUS-CONFIG"><div class="titlepage"><div><div><h4 class="title">12.6.4.1. Thesaurus Configuration</h4></div></div></div><p>
+ To define a new thesaurus dictionary, use the <code class="literal">thesaurus</code>
+ template. For example:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY thesaurus_simple (
+ TEMPLATE = thesaurus,
+ DictFile = mythesaurus,
+ Dictionary = pg_catalog.english_stem
+);
+</pre><p>
+
+ Here:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">thesaurus_simple</code> is the new dictionary's name
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">mythesaurus</code> is the base name of the thesaurus
+ configuration file.
+ (Its full name will be <code class="filename">$SHAREDIR/tsearch_data/mythesaurus.ths</code>,
+ where <code class="literal">$SHAREDIR</code> means the installation shared-data
+ directory.)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <code class="literal">pg_catalog.english_stem</code> is the subdictionary (here,
+ a Snowball English stemmer) to use for thesaurus normalization.
+ Notice that the subdictionary will have its own
+ configuration (for example, stop words), which is not shown here.
+ </p></li></ul></div><p>
+
+ Now it is possible to bind the thesaurus dictionary <code class="literal">thesaurus_simple</code>
+ to the desired token types in a configuration, for example:
+
+</p><pre class="programlisting">
+ALTER TEXT SEARCH CONFIGURATION russian
+ ALTER MAPPING FOR asciiword, asciihword, hword_asciipart
+ WITH thesaurus_simple;
+</pre><p>
+ </p></div><div class="sect3" id="TEXTSEARCH-THESAURUS-EXAMPLES"><div class="titlepage"><div><div><h4 class="title">12.6.4.2. Thesaurus Example</h4></div></div></div><p>
+ Consider a simple astronomical thesaurus <code class="literal">thesaurus_astro</code>,
+ which contains some astronomical word combinations:
+
+</p><pre class="programlisting">
+supernovae stars : sn
+crab nebulae : crab
+</pre><p>
+
+ Below we create a dictionary and bind some token types to
+ an astronomical thesaurus and English stemmer:
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY thesaurus_astro (
+ TEMPLATE = thesaurus,
+ DictFile = thesaurus_astro,
+ Dictionary = english_stem
+);
+
+ALTER TEXT SEARCH CONFIGURATION russian
+ ALTER MAPPING FOR asciiword, asciihword, hword_asciipart
+ WITH thesaurus_astro, english_stem;
+</pre><p>
+
+ Now we can see how it works.
+ <code class="function">ts_lexize</code> is not very useful for testing a thesaurus,
+ because it treats its input as a single token. Instead we can use
+ <code class="function">plainto_tsquery</code> and <code class="function">to_tsvector</code>
+ which will break their input strings into multiple tokens:
+
+</p><pre class="screen">
+SELECT plainto_tsquery('supernova star');
+ plainto_tsquery
+-----------------
+ 'sn'
+
+SELECT to_tsvector('supernova star');
+ to_tsvector
+-------------
+ 'sn':1
+</pre><p>
+
+ In principle, one can use <code class="function">to_tsquery</code> if you quote
+ the argument:
+
+</p><pre class="screen">
+SELECT to_tsquery('''supernova star''');
+ to_tsquery
+------------
+ 'sn'
+</pre><p>
+
+ Notice that <code class="literal">supernova star</code> matches <code class="literal">supernovae
+ stars</code> in <code class="literal">thesaurus_astro</code> because we specified
+ the <code class="literal">english_stem</code> stemmer in the thesaurus definition.
+ The stemmer removed the <code class="literal">e</code> and <code class="literal">s</code>.
+ </p><p>
+ To index the original phrase as well as the substitute, just include it
+ in the right-hand part of the definition:
+
+</p><pre class="screen">
+supernovae stars : sn supernovae stars
+
+SELECT plainto_tsquery('supernova star');
+ plainto_tsquery
+-----------------------------
+ 'sn' &amp; 'supernova' &amp; 'star'
+</pre><p>
+ </p></div></div><div class="sect2" id="TEXTSEARCH-ISPELL-DICTIONARY"><div class="titlepage"><div><div><h3 class="title">12.6.5. <span class="application">Ispell</span> Dictionary</h3></div></div></div><p>
+ The <span class="application">Ispell</span> dictionary template supports
+ <em class="firstterm">morphological dictionaries</em>, which can normalize many
+ different linguistic forms of a word into the same lexeme. For example,
+ an English <span class="application">Ispell</span> dictionary can match all declensions and
+ conjugations of the search term <code class="literal">bank</code>, e.g.,
+ <code class="literal">banking</code>, <code class="literal">banked</code>, <code class="literal">banks</code>,
+ <code class="literal">banks'</code>, and <code class="literal">bank's</code>.
+ </p><p>
+ The standard <span class="productname">PostgreSQL</span> distribution does
+ not include any <span class="application">Ispell</span> configuration files.
+ Dictionaries for a large number of languages are available from <a class="ulink" href="https://www.cs.hmc.edu/~geoff/ispell.html" target="_top">Ispell</a>.
+ Also, some more modern dictionary file formats are supported — <a class="ulink" href="https://en.wikipedia.org/wiki/MySpell" target="_top">MySpell</a> (OO &lt; 2.0.1)
+ and <a class="ulink" href="https://hunspell.github.io/" target="_top">Hunspell</a>
+ (OO &gt;= 2.0.2). A large list of dictionaries is available on the <a class="ulink" href="https://wiki.openoffice.org/wiki/Dictionaries" target="_top">OpenOffice
+ Wiki</a>.
+ </p><p>
+ To create an <span class="application">Ispell</span> dictionary perform these steps:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ download dictionary configuration files. <span class="productname">OpenOffice</span>
+ extension files have the <code class="filename">.oxt</code> extension. It is necessary
+ to extract <code class="filename">.aff</code> and <code class="filename">.dic</code> files, change
+ extensions to <code class="filename">.affix</code> and <code class="filename">.dict</code>. For some
+ dictionary files it is also needed to convert characters to the UTF-8
+ encoding with commands (for example, for a Norwegian language dictionary):
+</p><pre class="programlisting">
+iconv -f ISO_8859-1 -t UTF-8 -o nn_no.affix nn_NO.aff
+iconv -f ISO_8859-1 -t UTF-8 -o nn_no.dict nn_NO.dic
+</pre><p>
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ copy files to the <code class="filename">$SHAREDIR/tsearch_data</code> directory
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ load files into PostgreSQL with the following command:
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY english_hunspell (
+ TEMPLATE = ispell,
+ DictFile = en_us,
+ AffFile = en_us,
+ Stopwords = english);
+</pre><p>
+ </p></li></ul></div><p>
+ Here, <code class="literal">DictFile</code>, <code class="literal">AffFile</code>, and <code class="literal">StopWords</code>
+ specify the base names of the dictionary, affixes, and stop-words files.
+ The stop-words file has the same format explained above for the
+ <code class="literal">simple</code> dictionary type. The format of the other files is
+ not specified here but is available from the above-mentioned web sites.
+ </p><p>
+ Ispell dictionaries usually recognize a limited set of words, so they
+ should be followed by another broader dictionary; for
+ example, a Snowball dictionary, which recognizes everything.
+ </p><p>
+ The <code class="filename">.affix</code> file of <span class="application">Ispell</span> has the following
+ structure:
+</p><pre class="programlisting">
+prefixes
+flag *A:
+ . &gt; RE # As in enter &gt; reenter
+suffixes
+flag T:
+ E &gt; ST # As in late &gt; latest
+ [^AEIOU]Y &gt; -Y,IEST # As in dirty &gt; dirtiest
+ [AEIOU]Y &gt; EST # As in gray &gt; grayest
+ [^EY] &gt; EST # As in small &gt; smallest
+</pre><p>
+ </p><p>
+ And the <code class="filename">.dict</code> file has the following structure:
+</p><pre class="programlisting">
+lapse/ADGRS
+lard/DGRS
+large/PRTY
+lark/MRS
+</pre><p>
+ </p><p>
+ Format of the <code class="filename">.dict</code> file is:
+</p><pre class="programlisting">
+basic_form/affix_class_name
+</pre><p>
+ </p><p>
+ In the <code class="filename">.affix</code> file every affix flag is described in the
+ following format:
+</p><pre class="programlisting">
+condition &gt; [-stripping_letters,] adding_affix
+</pre><p>
+ </p><p>
+ Here, condition has a format similar to the format of regular expressions.
+ It can use groupings <code class="literal">[...]</code> and <code class="literal">[^...]</code>.
+ For example, <code class="literal">[AEIOU]Y</code> means that the last letter of the word
+ is <code class="literal">"y"</code> and the penultimate letter is <code class="literal">"a"</code>,
+ <code class="literal">"e"</code>, <code class="literal">"i"</code>, <code class="literal">"o"</code> or <code class="literal">"u"</code>.
+ <code class="literal">[^EY]</code> means that the last letter is neither <code class="literal">"e"</code>
+ nor <code class="literal">"y"</code>.
+ </p><p>
+ Ispell dictionaries support splitting compound words;
+ a useful feature.
+ Notice that the affix file should specify a special flag using the
+ <code class="literal">compoundwords controlled</code> statement that marks dictionary
+ words that can participate in compound formation:
+
+</p><pre class="programlisting">
+compoundwords controlled z
+</pre><p>
+
+ Here are some examples for the Norwegian language:
+
+</p><pre class="programlisting">
+SELECT ts_lexize('norwegian_ispell', 'overbuljongterningpakkmesterassistent');
+ {over,buljong,terning,pakk,mester,assistent}
+SELECT ts_lexize('norwegian_ispell', 'sjokoladefabrikk');
+ {sjokoladefabrikk,sjokolade,fabrikk}
+</pre><p>
+ </p><p>
+ <span class="application">MySpell</span> format is a subset of <span class="application">Hunspell</span>.
+ The <code class="filename">.affix</code> file of <span class="application">Hunspell</span> has the following
+ structure:
+</p><pre class="programlisting">
+PFX A Y 1
+PFX A 0 re .
+SFX T N 4
+SFX T 0 st e
+SFX T y iest [^aeiou]y
+SFX T 0 est [aeiou]y
+SFX T 0 est [^ey]
+</pre><p>
+ </p><p>
+ The first line of an affix class is the header. Fields of an affix rules are
+ listed after the header:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ parameter name (PFX or SFX)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ flag (name of the affix class)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ stripping characters from beginning (at prefix) or end (at suffix) of the
+ word
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ adding affix
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ condition that has a format similar to the format of regular expressions.
+ </p></li></ul></div><p>
+ The <code class="filename">.dict</code> file looks like the <code class="filename">.dict</code> file of
+ <span class="application">Ispell</span>:
+</p><pre class="programlisting">
+larder/M
+lardy/RT
+large/RSPMYT
+largehearted
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="application">MySpell</span> does not support compound words.
+ <span class="application">Hunspell</span> has sophisticated support for compound words. At
+ present, <span class="productname">PostgreSQL</span> implements only the basic
+ compound word operations of Hunspell.
+ </p></div></div><div class="sect2" id="TEXTSEARCH-SNOWBALL-DICTIONARY"><div class="titlepage"><div><div><h3 class="title">12.6.6. <span class="application">Snowball</span> Dictionary</h3></div></div></div><p>
+ The <span class="application">Snowball</span> dictionary template is based on a project
+ by Martin Porter, inventor of the popular Porter's stemming algorithm
+ for the English language. Snowball now provides stemming algorithms for
+ many languages (see the <a class="ulink" href="https://snowballstem.org/" target="_top">Snowball
+ site</a> for more information). Each algorithm understands how to
+ reduce common variant forms of words to a base, or stem, spelling within
+ its language. A Snowball dictionary requires a <code class="literal">language</code>
+ parameter to identify which stemmer to use, and optionally can specify a
+ <code class="literal">stopword</code> file name that gives a list of words to eliminate.
+ (<span class="productname">PostgreSQL</span>'s standard stopword lists are also
+ provided by the Snowball project.)
+ For example, there is a built-in definition equivalent to
+
+</p><pre class="programlisting">
+CREATE TEXT SEARCH DICTIONARY english_stem (
+ TEMPLATE = snowball,
+ Language = english,
+ StopWords = english
+);
+</pre><p>
+
+ The stopword file format is the same as already explained.
+ </p><p>
+ A <span class="application">Snowball</span> dictionary recognizes everything, whether
+ or not it is able to simplify the word, so it should be placed
+ at the end of the dictionary list. It is useless to have it
+ before any other dictionary because a token will never pass through it to
+ the next dictionary.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-parsers.html" title="12.5. Parsers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-configuration.html" title="12.7. Configuration Example">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.5. Parsers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.7. Configuration Example</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-features.html b/doc/src/sgml/html/textsearch-features.html
new file mode 100644
index 0000000..9e5ae4f
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-features.html
@@ -0,0 +1,392 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.4. Additional Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-controls.html" title="12.3. Controlling Text Search" /><link rel="next" href="textsearch-parsers.html" title="12.5. Parsers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.4. Additional Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-controls.html" title="12.3. Controlling Text Search">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-parsers.html" title="12.5. Parsers">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-FEATURES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.4. Additional Features</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">12.4.1. Manipulating Documents</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSQUERY">12.4.2. Manipulating Queries</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS">12.4.3. Triggers for Automatic Updates</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-STATISTICS">12.4.4. Gathering Document Statistics</a></span></dt></dl></div><p>
+ This section describes additional functions and operators that are
+ useful in connection with text search.
+ </p><div class="sect2" id="TEXTSEARCH-MANIPULATE-TSVECTOR"><div class="titlepage"><div><div><h3 class="title">12.4.1. Manipulating Documents</h3></div></div></div><p>
+ <a class="xref" href="textsearch-controls.html#TEXTSEARCH-PARSING-DOCUMENTS" title="12.3.1. Parsing Documents">Section 12.3.1</a> showed how raw textual
+ documents can be converted into <code class="type">tsvector</code> values.
+ <span class="productname">PostgreSQL</span> also provides functions and
+ operators that can be used to manipulate documents that are already
+ in <code class="type">tsvector</code> form.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <a id="id-1.5.11.7.3.3.1.1.1" class="indexterm"></a>
+
+ <code class="literal"><code class="type">tsvector</code> || <code class="type">tsvector</code></code>
+ </span></dt><dd><p>
+ The <code class="type">tsvector</code> concatenation operator
+ returns a vector which combines the lexemes and positional information
+ of the two vectors given as arguments. Positions and weight labels
+ are retained during the concatenation.
+ Positions appearing in the right-hand vector are offset by the largest
+ position mentioned in the left-hand vector, so that the result is
+ nearly equivalent to the result of performing <code class="function">to_tsvector</code>
+ on the concatenation of the two original document strings. (The
+ equivalence is not exact, because any stop-words removed from the
+ end of the left-hand argument will not affect the result, whereas
+ they would have affected the positions of the lexemes in the
+ right-hand argument if textual concatenation were used.)
+ </p><p>
+ One advantage of using concatenation in the vector form, rather than
+ concatenating text before applying <code class="function">to_tsvector</code>, is that
+ you can use different configurations to parse different sections
+ of the document. Also, because the <code class="function">setweight</code> function
+ marks all lexemes of the given vector the same way, it is necessary
+ to parse the text and do <code class="function">setweight</code> before concatenating
+ if you want to label different parts of the document with different
+ weights.
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.3.3.2.1.1" class="indexterm"></a>
+
+ <code class="literal">setweight(<em class="replaceable"><code>vector</code></em> <code class="type">tsvector</code>, <em class="replaceable"><code>weight</code></em> <code class="type">"char"</code>) returns <code class="type">tsvector</code></code>
+ </span></dt><dd><p>
+ <code class="function">setweight</code> returns a copy of the input vector in which every
+ position has been labeled with the given <em class="replaceable"><code>weight</code></em>, either
+ <code class="literal">A</code>, <code class="literal">B</code>, <code class="literal">C</code>, or
+ <code class="literal">D</code>. (<code class="literal">D</code> is the default for new
+ vectors and as such is not displayed on output.) These labels are
+ retained when vectors are concatenated, allowing words from different
+ parts of a document to be weighted differently by ranking functions.
+ </p><p>
+ Note that weight labels apply to <span class="emphasis"><em>positions</em></span>, not
+ <span class="emphasis"><em>lexemes</em></span>. If the input vector has been stripped of
+ positions then <code class="function">setweight</code> does nothing.
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.3.3.3.1.1" class="indexterm"></a>
+
+ <code class="literal">length(<em class="replaceable"><code>vector</code></em> <code class="type">tsvector</code>) returns <code class="type">integer</code></code>
+ </span></dt><dd><p>
+ Returns the number of lexemes stored in the vector.
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.3.3.4.1.1" class="indexterm"></a>
+
+ <code class="literal">strip(<em class="replaceable"><code>vector</code></em> <code class="type">tsvector</code>) returns <code class="type">tsvector</code></code>
+ </span></dt><dd><p>
+ Returns a vector that lists the same lexemes as the given vector, but
+ lacks any position or weight information. The result is usually much
+ smaller than an unstripped vector, but it is also less useful.
+ Relevance ranking does not work as well on stripped vectors as
+ unstripped ones. Also,
+ the <code class="literal">&lt;-&gt;</code> (FOLLOWED BY) <code class="type">tsquery</code> operator
+ will never match stripped input, since it cannot determine the
+ distance between lexeme occurrences.
+ </p></dd></dl></div><p>
+ A full list of <code class="type">tsvector</code>-related functions is available
+ in <a class="xref" href="functions-textsearch.html#TEXTSEARCH-FUNCTIONS-TABLE" title="Table 9.43. Text Search Functions">Table 9.43</a>.
+ </p></div><div class="sect2" id="TEXTSEARCH-MANIPULATE-TSQUERY"><div class="titlepage"><div><div><h3 class="title">12.4.2. Manipulating Queries</h3></div></div></div><p>
+ <a class="xref" href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES" title="12.3.2. Parsing Queries">Section 12.3.2</a> showed how raw textual
+ queries can be converted into <code class="type">tsquery</code> values.
+ <span class="productname">PostgreSQL</span> also provides functions and
+ operators that can be used to manipulate queries that are already
+ in <code class="type">tsquery</code> form.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal"><code class="type">tsquery</code> &amp;&amp; <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ Returns the AND-combination of the two given queries.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="type">tsquery</code> || <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ Returns the OR-combination of the two given queries.
+ </p></dd><dt><span class="term">
+ <code class="literal">!! <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ Returns the negation (NOT) of the given query.
+ </p></dd><dt><span class="term">
+ <code class="literal"><code class="type">tsquery</code> &lt;-&gt; <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ Returns a query that searches for a match to the first given query
+ immediately followed by a match to the second given query, using
+ the <code class="literal">&lt;-&gt;</code> (FOLLOWED BY)
+ <code class="type">tsquery</code> operator. For example:
+
+</p><pre class="screen">
+SELECT to_tsquery('fat') &lt;-&gt; to_tsquery('cat | rat');
+ ?column?
+----------------------------
+ 'fat' &lt;-&gt; ( 'cat' | 'rat' )
+</pre><p>
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.4.3.5.1.1" class="indexterm"></a>
+
+ <code class="literal">tsquery_phrase(<em class="replaceable"><code>query1</code></em> <code class="type">tsquery</code>, <em class="replaceable"><code>query2</code></em> <code class="type">tsquery</code> [, <em class="replaceable"><code>distance</code></em> <code class="type">integer</code> ]) returns <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ Returns a query that searches for a match to the first given query
+ followed by a match to the second given query at a distance of exactly
+ <em class="replaceable"><code>distance</code></em> lexemes, using
+ the <code class="literal">&lt;<em class="replaceable"><code>N</code></em>&gt;</code>
+ <code class="type">tsquery</code> operator. For example:
+
+</p><pre class="screen">
+SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10);
+ tsquery_phrase
+------------------
+ 'fat' &lt;10&gt; 'cat'
+</pre><p>
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.4.3.6.1.1" class="indexterm"></a>
+
+ <code class="literal">numnode(<em class="replaceable"><code>query</code></em> <code class="type">tsquery</code>) returns <code class="type">integer</code></code>
+ </span></dt><dd><p>
+ Returns the number of nodes (lexemes plus operators) in a
+ <code class="type">tsquery</code>. This function is useful
+ to determine if the <em class="replaceable"><code>query</code></em> is meaningful
+ (returns &gt; 0), or contains only stop words (returns 0).
+ Examples:
+
+</p><pre class="screen">
+SELECT numnode(plainto_tsquery('the any'));
+NOTICE: query contains only stopword(s) or doesn't contain lexeme(s), ignored
+ numnode
+---------
+ 0
+
+SELECT numnode('foo &amp; bar'::tsquery);
+ numnode
+---------
+ 3
+</pre><p>
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.7.4.3.7.1.1" class="indexterm"></a>
+
+ <code class="literal">querytree(<em class="replaceable"><code>query</code></em> <code class="type">tsquery</code>) returns <code class="type">text</code></code>
+ </span></dt><dd><p>
+ Returns the portion of a <code class="type">tsquery</code> that can be used for
+ searching an index. This function is useful for detecting
+ unindexable queries, for example those containing only stop words
+ or only negated terms. For example:
+
+</p><pre class="screen">
+SELECT querytree(to_tsquery('defined'));
+ querytree
+-----------
+ 'defin'
+
+SELECT querytree(to_tsquery('!defined'));
+ querytree
+-----------
+ T
+</pre><p>
+ </p></dd></dl></div><div class="sect3" id="TEXTSEARCH-QUERY-REWRITING"><div class="titlepage"><div><div><h4 class="title">12.4.2.1. Query Rewriting</h4></div></div></div><a id="id-1.5.11.7.4.4.2" class="indexterm"></a><p>
+ The <code class="function">ts_rewrite</code> family of functions search a
+ given <code class="type">tsquery</code> for occurrences of a target
+ subquery, and replace each occurrence with a
+ substitute subquery. In essence this operation is a
+ <code class="type">tsquery</code>-specific version of substring replacement.
+ A target and substitute combination can be
+ thought of as a <em class="firstterm">query rewrite rule</em>. A collection
+ of such rewrite rules can be a powerful search aid.
+ For example, you can expand the search using synonyms
+ (e.g., <code class="literal">new york</code>, <code class="literal">big apple</code>, <code class="literal">nyc</code>,
+ <code class="literal">gotham</code>) or narrow the search to direct the user to some hot
+ topic. There is some overlap in functionality between this feature
+ and thesaurus dictionaries (<a class="xref" href="textsearch-dictionaries.html#TEXTSEARCH-THESAURUS" title="12.6.4. Thesaurus Dictionary">Section 12.6.4</a>).
+ However, you can modify a set of rewrite rules on-the-fly without
+ reindexing, whereas updating a thesaurus requires reindexing to be
+ effective.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <code class="literal">ts_rewrite (<em class="replaceable"><code>query</code></em> <code class="type">tsquery</code>, <em class="replaceable"><code>target</code></em> <code class="type">tsquery</code>, <em class="replaceable"><code>substitute</code></em> <code class="type">tsquery</code>) returns <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ This form of <code class="function">ts_rewrite</code> simply applies a single
+ rewrite rule: <em class="replaceable"><code>target</code></em>
+ is replaced by <em class="replaceable"><code>substitute</code></em>
+ wherever it appears in <em class="replaceable"><code>query</code></em>. For example:
+
+</p><pre class="screen">
+SELECT ts_rewrite('a &amp; b'::tsquery, 'a'::tsquery, 'c'::tsquery);
+ ts_rewrite
+------------
+ 'b' &amp; 'c'
+</pre><p>
+ </p></dd><dt><span class="term">
+ <code class="literal">ts_rewrite (<em class="replaceable"><code>query</code></em> <code class="type">tsquery</code>, <em class="replaceable"><code>select</code></em> <code class="type">text</code>) returns <code class="type">tsquery</code></code>
+ </span></dt><dd><p>
+ This form of <code class="function">ts_rewrite</code> accepts a starting
+ <em class="replaceable"><code>query</code></em> and an SQL <em class="replaceable"><code>select</code></em> command, which
+ is given as a text string. The <em class="replaceable"><code>select</code></em> must yield two
+ columns of <code class="type">tsquery</code> type. For each row of the
+ <em class="replaceable"><code>select</code></em> result, occurrences of the first column value
+ (the target) are replaced by the second column value (the substitute)
+ within the current <em class="replaceable"><code>query</code></em> value. For example:
+
+</p><pre class="screen">
+CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery);
+INSERT INTO aliases VALUES('a', 'c');
+
+SELECT ts_rewrite('a &amp; b'::tsquery, 'SELECT t,s FROM aliases');
+ ts_rewrite
+------------
+ 'b' &amp; 'c'
+</pre><p>
+ </p><p>
+ Note that when multiple rewrite rules are applied in this way,
+ the order of application can be important; so in practice you will
+ want the source query to <code class="literal">ORDER BY</code> some ordering key.
+ </p></dd></dl></div><p>
+ Let's consider a real-life astronomical example. We'll expand query
+ <code class="literal">supernovae</code> using table-driven rewriting rules:
+
+</p><pre class="screen">
+CREATE TABLE aliases (t tsquery primary key, s tsquery);
+INSERT INTO aliases VALUES(to_tsquery('supernovae'), to_tsquery('supernovae|sn'));
+
+SELECT ts_rewrite(to_tsquery('supernovae &amp; crab'), 'SELECT * FROM aliases');
+ ts_rewrite
+---------------------------------
+ 'crab' &amp; ( 'supernova' | 'sn' )
+</pre><p>
+
+ We can change the rewriting rules just by updating the table:
+
+</p><pre class="screen">
+UPDATE aliases
+SET s = to_tsquery('supernovae|sn &amp; !nebulae')
+WHERE t = to_tsquery('supernovae');
+
+SELECT ts_rewrite(to_tsquery('supernovae &amp; crab'), 'SELECT * FROM aliases');
+ ts_rewrite
+---------------------------------------------
+ 'crab' &amp; ( 'supernova' | 'sn' &amp; !'nebula' )
+</pre><p>
+ </p><p>
+ Rewriting can be slow when there are many rewriting rules, since it
+ checks every rule for a possible match. To filter out obvious non-candidate
+ rules we can use the containment operators for the <code class="type">tsquery</code>
+ type. In the example below, we select only those rules which might match
+ the original query:
+
+</p><pre class="screen">
+SELECT ts_rewrite('a &amp; b'::tsquery,
+ 'SELECT t,s FROM aliases WHERE ''a &amp; b''::tsquery @&gt; t');
+ ts_rewrite
+------------
+ 'b' &amp; 'c'
+</pre><p>
+ </p></div></div><div class="sect2" id="TEXTSEARCH-UPDATE-TRIGGERS"><div class="titlepage"><div><div><h3 class="title">12.4.3. Triggers for Automatic Updates</h3></div></div></div><a id="id-1.5.11.7.5.2" class="indexterm"></a><div class="note"><h3 class="title">Note</h3><p>
+ The method described in this section has been obsoleted by the use of
+ stored generated columns, as described in <a class="xref" href="textsearch-tables.html#TEXTSEARCH-TABLES-INDEX" title="12.2.2. Creating Indexes">Section 12.2.2</a>.
+ </p></div><p>
+ When using a separate column to store the <code class="type">tsvector</code> representation
+ of your documents, it is necessary to create a trigger to update the
+ <code class="type">tsvector</code> column when the document content columns change.
+ Two built-in trigger functions are available for this, or you can write
+ your own.
+ </p><pre class="synopsis">
+tsvector_update_trigger(<em class="replaceable"><code>tsvector_column_name</code></em>,​ <em class="replaceable"><code>config_name</code></em>, <em class="replaceable"><code>text_column_name</code></em> [<span class="optional">, ... </span>])
+tsvector_update_trigger_column(<em class="replaceable"><code>tsvector_column_name</code></em>,​ <em class="replaceable"><code>config_column_name</code></em>, <em class="replaceable"><code>text_column_name</code></em> [<span class="optional">, ... </span>])
+</pre><p>
+ These trigger functions automatically compute a <code class="type">tsvector</code>
+ column from one or more textual columns, under the control of
+ parameters specified in the <code class="command">CREATE TRIGGER</code> command.
+ An example of their use is:
+
+</p><pre class="screen">
+CREATE TABLE messages (
+ title text,
+ body text,
+ tsv tsvector
+);
+
+CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE
+ON messages FOR EACH ROW EXECUTE FUNCTION
+tsvector_update_trigger(tsv, 'pg_catalog.english', title, body);
+
+INSERT INTO messages VALUES('title here', 'the body text is here');
+
+SELECT * FROM messages;
+ title | body | tsv
+------------+-----------------------+----------------------------
+ title here | the body text is here | 'bodi':4 'text':5 'titl':1
+
+SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title &amp; body');
+ title | body
+------------+-----------------------
+ title here | the body text is here
+</pre><p>
+
+ Having created this trigger, any change in <code class="structfield">title</code> or
+ <code class="structfield">body</code> will automatically be reflected into
+ <code class="structfield">tsv</code>, without the application having to worry about it.
+ </p><p>
+ The first trigger argument must be the name of the <code class="type">tsvector</code>
+ column to be updated. The second argument specifies the text search
+ configuration to be used to perform the conversion. For
+ <code class="function">tsvector_update_trigger</code>, the configuration name is simply
+ given as the second trigger argument. It must be schema-qualified as
+ shown above, so that the trigger behavior will not change with changes
+ in <code class="varname">search_path</code>. For
+ <code class="function">tsvector_update_trigger_column</code>, the second trigger argument
+ is the name of another table column, which must be of type
+ <code class="type">regconfig</code>. This allows a per-row selection of configuration
+ to be made. The remaining argument(s) are the names of textual columns
+ (of type <code class="type">text</code>, <code class="type">varchar</code>, or <code class="type">char</code>). These
+ will be included in the document in the order given. NULL values will
+ be skipped (but the other columns will still be indexed).
+ </p><p>
+ A limitation of these built-in triggers is that they treat all the
+ input columns alike. To process columns differently — for
+ example, to weight title differently from body — it is necessary
+ to write a custom trigger. Here is an example using
+ <span class="application">PL/pgSQL</span> as the trigger language:
+
+</p><pre class="programlisting">
+CREATE FUNCTION messages_trigger() RETURNS trigger AS $$
+begin
+ new.tsv :=
+ setweight(to_tsvector('pg_catalog.english', coalesce(new.title,'')), 'A') ||
+ setweight(to_tsvector('pg_catalog.english', coalesce(new.body,'')), 'D');
+ return new;
+end
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE
+ ON messages FOR EACH ROW EXECUTE FUNCTION messages_trigger();
+</pre><p>
+ </p><p>
+ Keep in mind that it is important to specify the configuration name
+ explicitly when creating <code class="type">tsvector</code> values inside triggers,
+ so that the column's contents will not be affected by changes to
+ <code class="varname">default_text_search_config</code>. Failure to do this is likely to
+ lead to problems such as search results changing after a dump and restore.
+ </p></div><div class="sect2" id="TEXTSEARCH-STATISTICS"><div class="titlepage"><div><div><h3 class="title">12.4.4. Gathering Document Statistics</h3></div></div></div><a id="id-1.5.11.7.6.2" class="indexterm"></a><p>
+ The function <code class="function">ts_stat</code> is useful for checking your
+ configuration and for finding stop-word candidates.
+ </p><pre class="synopsis">
+ts_stat(<em class="replaceable"><code>sqlquery</code></em> <code class="type">text</code>, [<span class="optional"> <em class="replaceable"><code>weights</code></em> <code class="type">text</code>, </span>]
+ OUT <em class="replaceable"><code>word</code></em> <code class="type">text</code>, OUT <em class="replaceable"><code>ndoc</code></em> <code class="type">integer</code>,
+ OUT <em class="replaceable"><code>nentry</code></em> <code class="type">integer</code>) returns <code class="type">setof record</code>
+</pre><p>
+ <em class="replaceable"><code>sqlquery</code></em> is a text value containing an SQL
+ query which must return a single <code class="type">tsvector</code> column.
+ <code class="function">ts_stat</code> executes the query and returns statistics about
+ each distinct lexeme (word) contained in the <code class="type">tsvector</code>
+ data. The columns returned are
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>word</code></em> <code class="type">text</code> — the value of a lexeme
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>ndoc</code></em> <code class="type">integer</code> — number of documents
+ (<code class="type">tsvector</code>s) the word occurred in
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="replaceable"><code>nentry</code></em> <code class="type">integer</code> — total number of
+ occurrences of the word
+ </p></li></ul></div><p>
+
+ If <em class="replaceable"><code>weights</code></em> is supplied, only occurrences
+ having one of those weights are counted.
+ </p><p>
+ For example, to find the ten most frequent words in a document collection:
+
+</p><pre class="programlisting">
+SELECT * FROM ts_stat('SELECT vector FROM apod')
+ORDER BY nentry DESC, ndoc DESC, word
+LIMIT 10;
+</pre><p>
+
+ The same, but counting only word occurrences with weight <code class="literal">A</code>
+ or <code class="literal">B</code>:
+
+</p><pre class="programlisting">
+SELECT * FROM ts_stat('SELECT vector FROM apod', 'ab')
+ORDER BY nentry DESC, ndoc DESC, word
+LIMIT 10;
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-controls.html" title="12.3. Controlling Text Search">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-parsers.html" title="12.5. Parsers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.3. Controlling Text Search </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.5. Parsers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-indexes.html b/doc/src/sgml/html/textsearch-indexes.html
new file mode 100644
index 0000000..8182546
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-indexes.html
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.9. Preferred Index Types for Text Search</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search" /><link rel="next" href="textsearch-psql.html" title="12.10. psql Support" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.9. Preferred Index Types for Text Search</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-psql.html" title="12.10. psql Support">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-INDEXES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.9. Preferred Index Types for Text Search</h2></div></div></div><a id="id-1.5.11.12.2" class="indexterm"></a><p>
+ There are two kinds of indexes that can be used to speed up full text
+ searches:
+ <a class="link" href="gin.html" title="Chapter 70. GIN Indexes"><acronym class="acronym">GIN</acronym></a> and
+ <a class="link" href="gist.html" title="Chapter 68. GiST Indexes"><acronym class="acronym">GiST</acronym></a>.
+ Note that indexes are not mandatory for full text searching, but in
+ cases where a column is searched on a regular basis, an index is
+ usually desirable.
+ </p><p>
+ To create such an index, do one of:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <a id="id-1.5.11.12.4.1.1.1.1" class="indexterm"></a>
+
+ <code class="literal">CREATE INDEX <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table</code></em> USING GIN (<em class="replaceable"><code>column</code></em>);</code>
+ </span></dt><dd><p>
+ Creates a GIN (Generalized Inverted Index)-based index.
+ The <em class="replaceable"><code>column</code></em> must be of <code class="type">tsvector</code> type.
+ </p></dd><dt><span class="term">
+ <a id="id-1.5.11.12.4.1.2.1.1" class="indexterm"></a>
+
+ <code class="literal">CREATE INDEX <em class="replaceable"><code>name</code></em> ON <em class="replaceable"><code>table</code></em> USING GIST (<em class="replaceable"><code>column</code></em> [ { DEFAULT | tsvector_ops } (siglen = <em class="replaceable"><code>number</code></em>) ] );</code>
+ </span></dt><dd><p>
+ Creates a GiST (Generalized Search Tree)-based index.
+ The <em class="replaceable"><code>column</code></em> can be of <code class="type">tsvector</code> or
+ <code class="type">tsquery</code> type.
+ Optional integer parameter <code class="literal">siglen</code> determines
+ signature length in bytes (see below for details).
+ </p></dd></dl></div><p>
+ </p><p>
+ GIN indexes are the preferred text search index type. As inverted
+ indexes, they contain an index entry for each word (lexeme), with a
+ compressed list of matching locations. Multi-word searches can find
+ the first match, then use the index to remove rows that are lacking
+ additional words. GIN indexes store only the words (lexemes) of
+ <code class="type">tsvector</code> values, and not their weight labels. Thus a table
+ row recheck is needed when using a query that involves weights.
+ </p><p>
+ A GiST index is <em class="firstterm">lossy</em>, meaning that the index
+ might produce false matches, and it is necessary
+ to check the actual table row to eliminate such false matches.
+ (<span class="productname">PostgreSQL</span> does this automatically when needed.)
+ GiST indexes are lossy because each document is represented in the
+ index by a fixed-length signature. The signature length in bytes is determined
+ by the value of the optional integer parameter <code class="literal">siglen</code>.
+ The default signature length (when <code class="literal">siglen</code> is not specified) is
+ 124 bytes, the maximum signature length is 2024 bytes. The signature is generated by hashing
+ each word into a single bit in an n-bit string, with all these bits OR-ed
+ together to produce an n-bit document signature. When two words hash to
+ the same bit position there will be a false match. If all words in
+ the query have matches (real or false) then the table row must be
+ retrieved to see if the match is correct. Longer signatures lead to a more
+ precise search (scanning a smaller fraction of the index and fewer heap
+ pages), at the cost of a larger index.
+ </p><p>
+ A GiST index can be covering, i.e., use the <code class="literal">INCLUDE</code>
+ clause. Included columns can have data types without any GiST operator
+ class. Included attributes will be stored uncompressed.
+ </p><p>
+ Lossiness causes performance degradation due to unnecessary fetches of table
+ records that turn out to be false matches. Since random access to table
+ records is slow, this limits the usefulness of GiST indexes. The
+ likelihood of false matches depends on several factors, in particular the
+ number of unique words, so using dictionaries to reduce this number is
+ recommended.
+ </p><p>
+ Note that <acronym class="acronym">GIN</acronym> index build time can often be improved
+ by increasing <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</a>, while
+ <acronym class="acronym">GiST</acronym> index build time is not sensitive to that
+ parameter.
+ </p><p>
+ Partitioning of big collections and the proper use of GIN and GiST indexes
+ allows the implementation of very fast searches with online update.
+ Partitioning can be done at the database level using table inheritance,
+ or by distributing documents over
+ servers and collecting external search results, e.g., via <a class="link" href="ddl-foreign-data.html" title="5.12. Foreign Data">Foreign Data</a> access.
+ The latter is possible because ranking functions use
+ only local information.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-debugging.html" title="12.8. Testing and Debugging Text Search">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-psql.html" title="12.10. psql Support">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.8. Testing and Debugging Text Search </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.10. <span class="application">psql</span> Support</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-intro.html b/doc/src/sgml/html/textsearch-intro.html
new file mode 100644
index 0000000..01efe7b
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-intro.html
@@ -0,0 +1,339 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch.html" title="Chapter 12. Full Text Search" /><link rel="next" href="textsearch-tables.html" title="12.2. Tables and Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch.html" title="Chapter 12. Full Text Search">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-tables.html" title="12.2. Tables and Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.1. Introduction</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-DOCUMENT">12.1.1. What Is a Document?</a></span></dt><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-MATCHING">12.1.2. Basic Text Matching</a></span></dt><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-INTRO-CONFIGURATIONS">12.1.3. Configurations</a></span></dt></dl></div><p>
+ Full Text Searching (or just <em class="firstterm">text search</em>) provides
+ the capability to identify natural-language <em class="firstterm">documents</em> that
+ satisfy a <em class="firstterm">query</em>, and optionally to sort them by
+ relevance to the query. The most common type of search
+ is to find all documents containing given <em class="firstterm">query terms</em>
+ and return them in order of their <em class="firstterm">similarity</em> to the
+ query. Notions of <code class="varname">query</code> and
+ <code class="varname">similarity</code> are very flexible and depend on the specific
+ application. The simplest search considers <code class="varname">query</code> as a
+ set of words and <code class="varname">similarity</code> as the frequency of query
+ words in the document.
+ </p><p>
+ Textual search operators have existed in databases for years.
+ <span class="productname">PostgreSQL</span> has
+ <code class="literal">~</code>, <code class="literal">~*</code>, <code class="literal">LIKE</code>, and
+ <code class="literal">ILIKE</code> operators for textual data types, but they lack
+ many essential properties required by modern information systems:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ There is no linguistic support, even for English. Regular expressions
+ are not sufficient because they cannot easily handle derived words, e.g.,
+ <code class="literal">satisfies</code> and <code class="literal">satisfy</code>. You might
+ miss documents that contain <code class="literal">satisfies</code>, although you
+ probably would like to find them when searching for
+ <code class="literal">satisfy</code>. It is possible to use <code class="literal">OR</code>
+ to search for multiple derived forms, but this is tedious and error-prone
+ (some words can have several thousand derivatives).
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ They provide no ordering (ranking) of search results, which makes them
+ ineffective when thousands of matching documents are found.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ They tend to be slow because there is no index support, so they must
+ process all documents for every search.
+ </p></li></ul></div><p>
+ Full text indexing allows documents to be <span class="emphasis"><em>preprocessed</em></span>
+ and an index saved for later rapid searching. Preprocessing includes:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><p>
+ <span class="emphasis"><em>Parsing documents into <em class="firstterm">tokens</em></em></span>. It is
+ useful to identify various classes of tokens, e.g., numbers, words,
+ complex words, email addresses, so that they can be processed
+ differently. In principle token classes depend on the specific
+ application, but for most purposes it is adequate to use a predefined
+ set of classes.
+ <span class="productname">PostgreSQL</span> uses a <em class="firstterm">parser</em> to
+ perform this step. A standard parser is provided, and custom parsers
+ can be created for specific needs.
+ </p></li><li class="listitem" style="list-style-type: none"><p>
+ <span class="emphasis"><em>Converting tokens into <em class="firstterm">lexemes</em></em></span>.
+ A lexeme is a string, just like a token, but it has been
+ <em class="firstterm">normalized</em> so that different forms of the same word
+ are made alike. For example, normalization almost always includes
+ folding upper-case letters to lower-case, and often involves removal
+ of suffixes (such as <code class="literal">s</code> or <code class="literal">es</code> in English).
+ This allows searches to find variant forms of the
+ same word, without tediously entering all the possible variants.
+ Also, this step typically eliminates <em class="firstterm">stop words</em>, which
+ are words that are so common that they are useless for searching.
+ (In short, then, tokens are raw fragments of the document text, while
+ lexemes are words that are believed useful for indexing and searching.)
+ <span class="productname">PostgreSQL</span> uses <em class="firstterm">dictionaries</em> to
+ perform this step. Various standard dictionaries are provided, and
+ custom ones can be created for specific needs.
+ </p></li><li class="listitem" style="list-style-type: none"><p>
+ <span class="emphasis"><em>Storing preprocessed documents optimized for
+ searching</em></span>. For example, each document can be represented
+ as a sorted array of normalized lexemes. Along with the lexemes it is
+ often desirable to store positional information to use for
+ <em class="firstterm">proximity ranking</em>, so that a document that
+ contains a more <span class="quote">“<span class="quote">dense</span>”</span> region of query words is
+ assigned a higher rank than one with scattered query words.
+ </p></li></ul></div><p>
+ Dictionaries allow fine-grained control over how tokens are normalized.
+ With appropriate dictionaries, you can:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ Define stop words that should not be indexed.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Map synonyms to a single word using <span class="application">Ispell</span>.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Map phrases to a single word using a thesaurus.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Map different variations of a word to a canonical form using
+ an <span class="application">Ispell</span> dictionary.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Map different variations of a word to a canonical form using
+ <span class="application">Snowball</span> stemmer rules.
+ </p></li></ul></div><p>
+ A data type <code class="type">tsvector</code> is provided for storing preprocessed
+ documents, along with a type <code class="type">tsquery</code> for representing processed
+ queries (<a class="xref" href="datatype-textsearch.html" title="8.11. Text Search Types">Section 8.11</a>). There are many
+ functions and operators available for these data types
+ (<a class="xref" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Section 9.13</a>), the most important of which is
+ the match operator <code class="literal">@@</code>, which we introduce in
+ <a class="xref" href="textsearch-intro.html#TEXTSEARCH-MATCHING" title="12.1.2. Basic Text Matching">Section 12.1.2</a>. Full text searches can be accelerated
+ using indexes (<a class="xref" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Section 12.9</a>).
+ </p><div class="sect2" id="TEXTSEARCH-DOCUMENT"><div class="titlepage"><div><div><h3 class="title">12.1.1. What Is a Document?</h3></div></div></div><a id="id-1.5.11.4.10.2" class="indexterm"></a><p>
+ A <em class="firstterm">document</em> is the unit of searching in a full text search
+ system; for example, a magazine article or email message. The text search
+ engine must be able to parse documents and store associations of lexemes
+ (key words) with their parent document. Later, these associations are
+ used to search for documents that contain query words.
+ </p><p>
+ For searches within <span class="productname">PostgreSQL</span>,
+ a document is normally a textual field within a row of a database table,
+ or possibly a combination (concatenation) of such fields, perhaps stored
+ in several tables or obtained dynamically. In other words, a document can
+ be constructed from different parts for indexing and it might not be
+ stored anywhere as a whole. For example:
+
+</p><pre class="programlisting">
+SELECT title || ' ' || author || ' ' || abstract || ' ' || body AS document
+FROM messages
+WHERE mid = 12;
+
+SELECT m.title || ' ' || m.author || ' ' || m.abstract || ' ' || d.body AS document
+FROM messages m, docs d
+WHERE m.mid = d.did AND m.mid = 12;
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Actually, in these example queries, <code class="function">coalesce</code>
+ should be used to prevent a single <code class="literal">NULL</code> attribute from
+ causing a <code class="literal">NULL</code> result for the whole document.
+ </p></div><p>
+ Another possibility is to store the documents as simple text files in the
+ file system. In this case, the database can be used to store the full text
+ index and to execute searches, and some unique identifier can be used to
+ retrieve the document from the file system. However, retrieving files
+ from outside the database requires superuser permissions or special
+ function support, so this is usually less convenient than keeping all
+ the data inside <span class="productname">PostgreSQL</span>. Also, keeping
+ everything inside the database allows easy access
+ to document metadata to assist in indexing and display.
+ </p><p>
+ For text search purposes, each document must be reduced to the
+ preprocessed <code class="type">tsvector</code> format. Searching and ranking
+ are performed entirely on the <code class="type">tsvector</code> representation
+ of a document — the original text need only be retrieved
+ when the document has been selected for display to a user.
+ We therefore often speak of the <code class="type">tsvector</code> as being the
+ document, but of course it is only a compact representation of
+ the full document.
+ </p></div><div class="sect2" id="TEXTSEARCH-MATCHING"><div class="titlepage"><div><div><h3 class="title">12.1.2. Basic Text Matching</h3></div></div></div><p>
+ Full text searching in <span class="productname">PostgreSQL</span> is based on
+ the match operator <code class="literal">@@</code>, which returns
+ <code class="literal">true</code> if a <code class="type">tsvector</code>
+ (document) matches a <code class="type">tsquery</code> (query).
+ It doesn't matter which data type is written first:
+
+</p><pre class="programlisting">
+SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat &amp; rat'::tsquery;
+ ?column?
+----------
+ t
+
+SELECT 'fat &amp; cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::tsvector;
+ ?column?
+----------
+ f
+</pre><p>
+ </p><p>
+ As the above example suggests, a <code class="type">tsquery</code> is not just raw
+ text, any more than a <code class="type">tsvector</code> is. A <code class="type">tsquery</code>
+ contains search terms, which must be already-normalized lexemes, and
+ may combine multiple terms using AND, OR, NOT, and FOLLOWED BY operators.
+ (For syntax details see <a class="xref" href="datatype-textsearch.html#DATATYPE-TSQUERY" title="8.11.2. tsquery">Section 8.11.2</a>.) There are
+ functions <code class="function">to_tsquery</code>, <code class="function">plainto_tsquery</code>,
+ and <code class="function">phraseto_tsquery</code>
+ that are helpful in converting user-written text into a proper
+ <code class="type">tsquery</code>, primarily by normalizing words appearing in
+ the text. Similarly, <code class="function">to_tsvector</code> is used to parse and
+ normalize a document string. So in practice a text search match would
+ look more like this:
+
+</p><pre class="programlisting">
+SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat &amp; rat');
+ ?column?
+----------
+ t
+</pre><p>
+
+ Observe that this match would not succeed if written as
+
+</p><pre class="programlisting">
+SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat &amp; rat');
+ ?column?
+----------
+ f
+</pre><p>
+
+ since here no normalization of the word <code class="literal">rats</code> will occur.
+ The elements of a <code class="type">tsvector</code> are lexemes, which are assumed
+ already normalized, so <code class="literal">rats</code> does not match <code class="literal">rat</code>.
+ </p><p>
+ The <code class="literal">@@</code> operator also
+ supports <code class="type">text</code> input, allowing explicit conversion of a text
+ string to <code class="type">tsvector</code> or <code class="type">tsquery</code> to be skipped
+ in simple cases. The variants available are:
+
+</p><pre class="programlisting">
+tsvector @@ tsquery
+tsquery @@ tsvector
+text @@ tsquery
+text @@ text
+</pre><p>
+ </p><p>
+ The first two of these we saw already.
+ The form <code class="type">text</code> <code class="literal">@@</code> <code class="type">tsquery</code>
+ is equivalent to <code class="literal">to_tsvector(x) @@ y</code>.
+ The form <code class="type">text</code> <code class="literal">@@</code> <code class="type">text</code>
+ is equivalent to <code class="literal">to_tsvector(x) @@ plainto_tsquery(y)</code>.
+ </p><p>
+ Within a <code class="type">tsquery</code>, the <code class="literal">&amp;</code> (AND) operator
+ specifies that both its arguments must appear in the document to have a
+ match. Similarly, the <code class="literal">|</code> (OR) operator specifies that
+ at least one of its arguments must appear, while the <code class="literal">!</code> (NOT)
+ operator specifies that its argument must <span class="emphasis"><em>not</em></span> appear in
+ order to have a match.
+ For example, the query <code class="literal">fat &amp; ! rat</code> matches documents that
+ contain <code class="literal">fat</code> but not <code class="literal">rat</code>.
+ </p><p>
+ Searching for phrases is possible with the help of
+ the <code class="literal">&lt;-&gt;</code> (FOLLOWED BY) <code class="type">tsquery</code> operator, which
+ matches only if its arguments have matches that are adjacent and in the
+ given order. For example:
+
+</p><pre class="programlisting">
+SELECT to_tsvector('fatal error') @@ to_tsquery('fatal &lt;-&gt; error');
+ ?column?
+----------
+ t
+
+SELECT to_tsvector('error is not fatal') @@ to_tsquery('fatal &lt;-&gt; error');
+ ?column?
+----------
+ f
+</pre><p>
+
+ There is a more general version of the FOLLOWED BY operator having the
+ form <code class="literal">&lt;<em class="replaceable"><code>N</code></em>&gt;</code>,
+ where <em class="replaceable"><code>N</code></em> is an integer standing for the difference between
+ the positions of the matching lexemes. <code class="literal">&lt;1&gt;</code> is
+ the same as <code class="literal">&lt;-&gt;</code>, while <code class="literal">&lt;2&gt;</code>
+ allows exactly one other lexeme to appear between the matches, and so
+ on. The <code class="literal">phraseto_tsquery</code> function makes use of this
+ operator to construct a <code class="literal">tsquery</code> that can match a multi-word
+ phrase when some of the words are stop words. For example:
+
+</p><pre class="programlisting">
+SELECT phraseto_tsquery('cats ate rats');
+ phraseto_tsquery
+-------------------------------
+ 'cat' &lt;-&gt; 'ate' &lt;-&gt; 'rat'
+
+SELECT phraseto_tsquery('the cats ate the rats');
+ phraseto_tsquery
+-------------------------------
+ 'cat' &lt;-&gt; 'ate' &lt;2&gt; 'rat'
+</pre><p>
+ </p><p>
+ A special case that's sometimes useful is that <code class="literal">&lt;0&gt;</code>
+ can be used to require that two patterns match the same word.
+ </p><p>
+ Parentheses can be used to control nesting of the <code class="type">tsquery</code>
+ operators. Without parentheses, <code class="literal">|</code> binds least tightly,
+ then <code class="literal">&amp;</code>, then <code class="literal">&lt;-&gt;</code>,
+ and <code class="literal">!</code> most tightly.
+ </p><p>
+ It's worth noticing that the AND/OR/NOT operators mean something subtly
+ different when they are within the arguments of a FOLLOWED BY operator
+ than when they are not, because within FOLLOWED BY the exact position of
+ the match is significant. For example, normally <code class="literal">!x</code> matches
+ only documents that do not contain <code class="literal">x</code> anywhere.
+ But <code class="literal">!x &lt;-&gt; y</code> matches <code class="literal">y</code> if it is not
+ immediately after an <code class="literal">x</code>; an occurrence of <code class="literal">x</code>
+ elsewhere in the document does not prevent a match. Another example is
+ that <code class="literal">x &amp; y</code> normally only requires that <code class="literal">x</code>
+ and <code class="literal">y</code> both appear somewhere in the document, but
+ <code class="literal">(x &amp; y) &lt;-&gt; z</code> requires <code class="literal">x</code>
+ and <code class="literal">y</code> to match at the same place, immediately before
+ a <code class="literal">z</code>. Thus this query behaves differently from
+ <code class="literal">x &lt;-&gt; z &amp; y &lt;-&gt; z</code>, which will match a
+ document containing two separate sequences <code class="literal">x z</code> and
+ <code class="literal">y z</code>. (This specific query is useless as written,
+ since <code class="literal">x</code> and <code class="literal">y</code> could not match at the same place;
+ but with more complex situations such as prefix-match patterns, a query
+ of this form could be useful.)
+ </p></div><div class="sect2" id="TEXTSEARCH-INTRO-CONFIGURATIONS"><div class="titlepage"><div><div><h3 class="title">12.1.3. Configurations</h3></div></div></div><p>
+ The above are all simple text search examples. As mentioned before, full
+ text search functionality includes the ability to do many more things:
+ skip indexing certain words (stop words), process synonyms, and use
+ sophisticated parsing, e.g., parse based on more than just white space.
+ This functionality is controlled by <em class="firstterm">text search
+ configurations</em>. <span class="productname">PostgreSQL</span> comes with predefined
+ configurations for many languages, and you can easily create your own
+ configurations. (<span class="application">psql</span>'s <code class="command">\dF</code> command
+ shows all available configurations.)
+ </p><p>
+ During installation an appropriate configuration is selected and
+ <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a> is set accordingly
+ in <code class="filename">postgresql.conf</code>. If you are using the same text search
+ configuration for the entire cluster you can use the value in
+ <code class="filename">postgresql.conf</code>. To use different configurations
+ throughout the cluster but the same configuration within any one database,
+ use <code class="command">ALTER DATABASE ... SET</code>. Otherwise, you can set
+ <code class="varname">default_text_search_config</code> in each session.
+ </p><p>
+ Each text search function that depends on a configuration has an optional
+ <code class="type">regconfig</code> argument, so that the configuration to use can be
+ specified explicitly. <code class="varname">default_text_search_config</code>
+ is used only when this argument is omitted.
+ </p><p>
+ To make it easier to build custom text search configurations, a
+ configuration is built up from simpler database objects.
+ <span class="productname">PostgreSQL</span>'s text search facility provides
+ four types of configuration-related database objects:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ <em class="firstterm">Text search parsers</em> break documents into tokens
+ and classify each token (for example, as words or numbers).
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="firstterm">Text search dictionaries</em> convert tokens to normalized
+ form and reject stop words.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="firstterm">Text search templates</em> provide the functions underlying
+ dictionaries. (A dictionary simply specifies a template and a set
+ of parameters for the template.)
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ <em class="firstterm">Text search configurations</em> select a parser and a set
+ of dictionaries to use to normalize the tokens produced by the parser.
+ </p></li></ul></div><p>
+ Text search parsers and templates are built from low-level C functions;
+ therefore it requires C programming ability to develop new ones, and
+ superuser privileges to install one into a database. (There are examples
+ of add-on parsers and templates in the <code class="filename">contrib/</code> area of the
+ <span class="productname">PostgreSQL</span> distribution.) Since dictionaries and
+ configurations just parameterize and connect together some underlying
+ parsers and templates, no special privilege is needed to create a new
+ dictionary or configuration. Examples of creating custom dictionaries and
+ configurations appear later in this chapter.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch.html" title="Chapter 12. Full Text Search">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-tables.html" title="12.2. Tables and Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. Full Text Search </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.2. Tables and Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-limitations.html b/doc/src/sgml/html/textsearch-limitations.html
new file mode 100644
index 0000000..57bdd7e
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-limitations.html
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.11. Limitations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-psql.html" title="12.10. psql Support" /><link rel="next" href="mvcc.html" title="Chapter 13. Concurrency Control" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.11. Limitations</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-psql.html" title="12.10. psql Support">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="mvcc.html" title="Chapter 13. Concurrency Control">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-LIMITATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.11. Limitations</h2></div></div></div><p>
+ The current limitations of <span class="productname">PostgreSQL</span>'s
+ text search features are:
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>The length of each lexeme must be less than 2 kilobytes</p></li><li class="listitem" style="list-style-type: disc"><p>The length of a <code class="type">tsvector</code> (lexemes + positions) must be
+ less than 1 megabyte</p></li><li class="listitem" style="list-style-type: disc"><p>The number of lexemes must be less than
+ 2<sup>64</sup></p></li><li class="listitem" style="list-style-type: disc"><p>Position values in <code class="type">tsvector</code> must be greater than 0 and
+ no more than 16,383</p></li><li class="listitem" style="list-style-type: disc"><p>The match distance in a <code class="literal">&lt;<em class="replaceable"><code>N</code></em>&gt;</code>
+ (FOLLOWED BY) <code class="type">tsquery</code> operator cannot be more than
+ 16,384</p></li><li class="listitem" style="list-style-type: disc"><p>No more than 256 positions per lexeme</p></li><li class="listitem" style="list-style-type: disc"><p>The number of nodes (lexemes + operators) in a <code class="type">tsquery</code>
+ must be less than 32,768</p></li></ul></div><p>
+ </p><p>
+ For comparison, the <span class="productname">PostgreSQL</span> 8.1 documentation
+ contained 10,441 unique words, a total of 335,420 words, and the most
+ frequent word <span class="quote">“<span class="quote">postgresql</span>”</span> was mentioned 6,127 times in 655
+ documents.
+ </p><p>
+ Another example — the <span class="productname">PostgreSQL</span> mailing
+ list archives contained 910,989 unique words with 57,491,343 lexemes in
+ 461,020 messages.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-psql.html" title="12.10. psql Support">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mvcc.html" title="Chapter 13. Concurrency Control">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.10. <span class="application">psql</span> Support </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 13. Concurrency Control</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-parsers.html b/doc/src/sgml/html/textsearch-parsers.html
new file mode 100644
index 0000000..233e61b
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-parsers.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.5. Parsers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-features.html" title="12.4. Additional Features" /><link rel="next" href="textsearch-dictionaries.html" title="12.6. Dictionaries" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.5. Parsers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-features.html" title="12.4. Additional Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-dictionaries.html" title="12.6. Dictionaries">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-PARSERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.5. Parsers</h2></div></div></div><p>
+ Text search parsers are responsible for splitting raw document text
+ into <em class="firstterm">tokens</em> and identifying each token's type, where
+ the set of possible types is defined by the parser itself.
+ Note that a parser does not modify the text at all — it simply
+ identifies plausible word boundaries. Because of this limited scope,
+ there is less need for application-specific custom parsers than there is
+ for custom dictionaries. At present <span class="productname">PostgreSQL</span>
+ provides just one built-in parser, which has been found to be useful for a
+ wide range of applications.
+ </p><p>
+ The built-in parser is named <code class="literal">pg_catalog.default</code>.
+ It recognizes 23 token types, shown in <a class="xref" href="textsearch-parsers.html#TEXTSEARCH-DEFAULT-PARSER" title="Table 12.1. Default Parser's Token Types">Table 12.1</a>.
+ </p><div class="table" id="TEXTSEARCH-DEFAULT-PARSER"><p class="title"><strong>Table 12.1. Default Parser's Token Types</strong></p><div class="table-contents"><table class="table" summary="Default Parser's Token Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Alias</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code class="literal">asciiword</code></td><td>Word, all ASCII letters</td><td><code class="literal">elephant</code></td></tr><tr><td><code class="literal">word</code></td><td>Word, all letters</td><td><code class="literal">mañana</code></td></tr><tr><td><code class="literal">numword</code></td><td>Word, letters and digits</td><td><code class="literal">beta1</code></td></tr><tr><td><code class="literal">asciihword</code></td><td>Hyphenated word, all ASCII</td><td><code class="literal">up-to-date</code></td></tr><tr><td><code class="literal">hword</code></td><td>Hyphenated word, all letters</td><td><code class="literal">lógico-matemática</code></td></tr><tr><td><code class="literal">numhword</code></td><td>Hyphenated word, letters and digits</td><td><code class="literal">postgresql-beta1</code></td></tr><tr><td><code class="literal">hword_asciipart</code></td><td>Hyphenated word part, all ASCII</td><td><code class="literal">postgresql</code> in the context <code class="literal">postgresql-beta1</code></td></tr><tr><td><code class="literal">hword_part</code></td><td>Hyphenated word part, all letters</td><td><code class="literal">lógico</code> or <code class="literal">matemática</code>
+ in the context <code class="literal">lógico-matemática</code></td></tr><tr><td><code class="literal">hword_numpart</code></td><td>Hyphenated word part, letters and digits</td><td><code class="literal">beta1</code> in the context
+ <code class="literal">postgresql-beta1</code></td></tr><tr><td><code class="literal">email</code></td><td>Email address</td><td><code class="literal">foo@example.com</code></td></tr><tr><td><code class="literal">protocol</code></td><td>Protocol head</td><td><code class="literal">http://</code></td></tr><tr><td><code class="literal">url</code></td><td>URL</td><td><code class="literal">example.com/stuff/index.html</code></td></tr><tr><td><code class="literal">host</code></td><td>Host</td><td><code class="literal">example.com</code></td></tr><tr><td><code class="literal">url_path</code></td><td>URL path</td><td><code class="literal">/stuff/index.html</code>, in the context of a URL</td></tr><tr><td><code class="literal">file</code></td><td>File or path name</td><td><code class="literal">/usr/local/foo.txt</code>, if not within a URL</td></tr><tr><td><code class="literal">sfloat</code></td><td>Scientific notation</td><td><code class="literal">-1.234e56</code></td></tr><tr><td><code class="literal">float</code></td><td>Decimal notation</td><td><code class="literal">-1.234</code></td></tr><tr><td><code class="literal">int</code></td><td>Signed integer</td><td><code class="literal">-1234</code></td></tr><tr><td><code class="literal">uint</code></td><td>Unsigned integer</td><td><code class="literal">1234</code></td></tr><tr><td><code class="literal">version</code></td><td>Version number</td><td><code class="literal">8.3.0</code></td></tr><tr><td><code class="literal">tag</code></td><td>XML tag</td><td><code class="literal">&lt;a href="dictionaries.html"&gt;</code></td></tr><tr><td><code class="literal">entity</code></td><td>XML entity</td><td><code class="literal">&amp;amp;</code></td></tr><tr><td><code class="literal">blank</code></td><td>Space symbols</td><td>(any whitespace or punctuation not otherwise recognized)</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><h3 class="title">Note</h3><p>
+ The parser's notion of a <span class="quote">“<span class="quote">letter</span>”</span> is determined by the database's
+ locale setting, specifically <code class="varname">lc_ctype</code>. Words containing
+ only the basic ASCII letters are reported as a separate token type,
+ since it is sometimes useful to distinguish them. In most European
+ languages, token types <code class="literal">word</code> and <code class="literal">asciiword</code>
+ should be treated alike.
+ </p><p>
+ <code class="literal">email</code> does not support all valid email characters as
+ defined by <a class="ulink" href="https://tools.ietf.org/html/rfc5322" target="_top">RFC 5322</a>.
+ Specifically, the only non-alphanumeric characters supported for
+ email user names are period, dash, and underscore.
+ </p></div><p>
+ It is possible for the parser to produce overlapping tokens from the same
+ piece of text. As an example, a hyphenated word will be reported both
+ as the entire word and as each component:
+
+</p><pre class="screen">
+SELECT alias, description, token FROM ts_debug('foo-bar-beta1');
+ alias | description | token
+-----------------+------------------------------------------+---------------
+ numhword | Hyphenated word, letters and digits | foo-bar-beta1
+ hword_asciipart | Hyphenated word part, all ASCII | foo
+ blank | Space symbols | -
+ hword_asciipart | Hyphenated word part, all ASCII | bar
+ blank | Space symbols | -
+ hword_numpart | Hyphenated word part, letters and digits | beta1
+</pre><p>
+
+ This behavior is desirable since it allows searches to work for both
+ the whole compound word and for components. Here is another
+ instructive example:
+
+</p><pre class="screen">
+SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.html');
+ alias | description | token
+----------+---------------+------------------------------
+ protocol | Protocol head | http://
+ url | URL | example.com/stuff/index.html
+ host | Host | example.com
+ url_path | URL path | /stuff/index.html
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-features.html" title="12.4. Additional Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-dictionaries.html" title="12.6. Dictionaries">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.4. Additional Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.6. Dictionaries</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-psql.html b/doc/src/sgml/html/textsearch-psql.html
new file mode 100644
index 0000000..2c39344
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-psql.html
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.10. psql Support</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search" /><link rel="next" href="textsearch-limitations.html" title="12.11. Limitations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.10. <span class="application">psql</span> Support</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-limitations.html" title="12.11. Limitations">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-PSQL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.10. <span class="application">psql</span> Support</h2></div></div></div><p>
+ Information about text search configuration objects can be obtained
+ in <span class="application">psql</span> using a set of commands:
+</p><pre class="synopsis">
+\dF{d,p,t}[<span class="optional">+</span>] [<span class="optional">PATTERN</span>]
+</pre><p>
+ An optional <code class="literal">+</code> produces more details.
+ </p><p>
+ The optional parameter <em class="replaceable"><code>PATTERN</code></em> can be the name of
+ a text search object, optionally schema-qualified. If
+ <em class="replaceable"><code>PATTERN</code></em> is omitted then information about all
+ visible objects will be displayed. <em class="replaceable"><code>PATTERN</code></em> can be a
+ regular expression and can provide <span class="emphasis"><em>separate</em></span> patterns
+ for the schema and object names. The following examples illustrate this:
+
+</p><pre class="screen">
+=&gt; \dF *fulltext*
+ List of text search configurations
+ Schema | Name | Description
+--------+--------------+-------------
+ public | fulltext_cfg |
+</pre><p>
+
+</p><pre class="screen">
+=&gt; \dF *.fulltext*
+ List of text search configurations
+ Schema | Name | Description
+----------+----------------------------
+ fulltext | fulltext_cfg |
+ public | fulltext_cfg |
+</pre><p>
+
+ The available commands are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">\dF[<span class="optional">+</span>] [<span class="optional">PATTERN</span>]</code></span></dt><dd><p>
+ List text search configurations (add <code class="literal">+</code> for more detail).
+</p><pre class="screen">
+=&gt; \dF russian
+ List of text search configurations
+ Schema | Name | Description
+------------+---------+------------------------------------
+ pg_catalog | russian | configuration for russian language
+
+=&gt; \dF+ russian
+Text search configuration "pg_catalog.russian"
+Parser: "pg_catalog.default"
+ Token | Dictionaries
+-----------------+--------------
+ asciihword | english_stem
+ asciiword | english_stem
+ email | simple
+ file | simple
+ float | simple
+ host | simple
+ hword | russian_stem
+ hword_asciipart | english_stem
+ hword_numpart | simple
+ hword_part | russian_stem
+ int | simple
+ numhword | simple
+ numword | simple
+ sfloat | simple
+ uint | simple
+ url | simple
+ url_path | simple
+ version | simple
+ word | russian_stem
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">\dFd[<span class="optional">+</span>] [<span class="optional">PATTERN</span>]</code></span></dt><dd><p>
+ List text search dictionaries (add <code class="literal">+</code> for more detail).
+</p><pre class="screen">
+=&gt; \dFd
+ List of text search dictionaries
+ Schema | Name | Description
+------------+-----------------+-----------------------------------------------------------
+ pg_catalog | arabic_stem | snowball stemmer for arabic language
+ pg_catalog | armenian_stem | snowball stemmer for armenian language
+ pg_catalog | basque_stem | snowball stemmer for basque language
+ pg_catalog | catalan_stem | snowball stemmer for catalan language
+ pg_catalog | danish_stem | snowball stemmer for danish language
+ pg_catalog | dutch_stem | snowball stemmer for dutch language
+ pg_catalog | english_stem | snowball stemmer for english language
+ pg_catalog | finnish_stem | snowball stemmer for finnish language
+ pg_catalog | french_stem | snowball stemmer for french language
+ pg_catalog | german_stem | snowball stemmer for german language
+ pg_catalog | greek_stem | snowball stemmer for greek language
+ pg_catalog | hindi_stem | snowball stemmer for hindi language
+ pg_catalog | hungarian_stem | snowball stemmer for hungarian language
+ pg_catalog | indonesian_stem | snowball stemmer for indonesian language
+ pg_catalog | irish_stem | snowball stemmer for irish language
+ pg_catalog | italian_stem | snowball stemmer for italian language
+ pg_catalog | lithuanian_stem | snowball stemmer for lithuanian language
+ pg_catalog | nepali_stem | snowball stemmer for nepali language
+ pg_catalog | norwegian_stem | snowball stemmer for norwegian language
+ pg_catalog | portuguese_stem | snowball stemmer for portuguese language
+ pg_catalog | romanian_stem | snowball stemmer for romanian language
+ pg_catalog | russian_stem | snowball stemmer for russian language
+ pg_catalog | serbian_stem | snowball stemmer for serbian language
+ pg_catalog | simple | simple dictionary: just lower case and check for stopword
+ pg_catalog | spanish_stem | snowball stemmer for spanish language
+ pg_catalog | swedish_stem | snowball stemmer for swedish language
+ pg_catalog | tamil_stem | snowball stemmer for tamil language
+ pg_catalog | turkish_stem | snowball stemmer for turkish language
+ pg_catalog | yiddish_stem | snowball stemmer for yiddish language
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">\dFp[<span class="optional">+</span>] [<span class="optional">PATTERN</span>]</code></span></dt><dd><p>
+ List text search parsers (add <code class="literal">+</code> for more detail).
+</p><pre class="screen">
+=&gt; \dFp
+ List of text search parsers
+ Schema | Name | Description
+------------+---------+---------------------
+ pg_catalog | default | default word parser
+=&gt; \dFp+
+ Text search parser "pg_catalog.default"
+ Method | Function | Description
+-----------------+----------------+-------------
+ Start parse | prsd_start |
+ Get next token | prsd_nexttoken |
+ End parse | prsd_end |
+ Get headline | prsd_headline |
+ Get token types | prsd_lextype |
+
+ Token types for parser "pg_catalog.default"
+ Token name | Description
+-----------------+------------------------------------------
+ asciihword | Hyphenated word, all ASCII
+ asciiword | Word, all ASCII
+ blank | Space symbols
+ email | Email address
+ entity | XML entity
+ file | File or path name
+ float | Decimal notation
+ host | Host
+ hword | Hyphenated word, all letters
+ hword_asciipart | Hyphenated word part, all ASCII
+ hword_numpart | Hyphenated word part, letters and digits
+ hword_part | Hyphenated word part, all letters
+ int | Signed integer
+ numhword | Hyphenated word, letters and digits
+ numword | Word, letters and digits
+ protocol | Protocol head
+ sfloat | Scientific notation
+ tag | XML tag
+ uint | Unsigned integer
+ url | URL
+ url_path | URL path
+ version | Version number
+ word | Word, all letters
+(23 rows)
+</pre><p>
+ </p></dd><dt><span class="term"><code class="literal">\dFt[<span class="optional">+</span>] [<span class="optional">PATTERN</span>]</code></span></dt><dd><p>
+ List text search templates (add <code class="literal">+</code> for more detail).
+</p><pre class="screen">
+=&gt; \dFt
+ List of text search templates
+ Schema | Name | Description
+------------+-----------+-----------------------------------------------------------
+ pg_catalog | ispell | ispell dictionary
+ pg_catalog | simple | simple dictionary: just lower case and check for stopword
+ pg_catalog | snowball | snowball stemmer
+ pg_catalog | synonym | synonym dictionary: replace word by its synonym
+ pg_catalog | thesaurus | thesaurus dictionary: phrase by phrase substitution
+</pre><p>
+ </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-limitations.html" title="12.11. Limitations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.9. Preferred Index Types for Text Search </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.11. Limitations</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch-tables.html b/doc/src/sgml/html/textsearch-tables.html
new file mode 100644
index 0000000..3cde56a
--- /dev/null
+++ b/doc/src/sgml/html/textsearch-tables.html
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>12.2. Tables and Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="textsearch-intro.html" title="12.1. Introduction" /><link rel="next" href="textsearch-controls.html" title="12.3. Controlling Text Search" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">12.2. Tables and Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="textsearch-intro.html" title="12.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><th width="60%" align="center">Chapter 12. Full Text Search</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-controls.html" title="12.3. Controlling Text Search">Next</a></td></tr></table><hr /></div><div class="sect1" id="TEXTSEARCH-TABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">12.2. Tables and Indexes</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="textsearch-tables.html#TEXTSEARCH-TABLES-SEARCH">12.2.1. Searching a Table</a></span></dt><dt><span class="sect2"><a href="textsearch-tables.html#TEXTSEARCH-TABLES-INDEX">12.2.2. Creating Indexes</a></span></dt></dl></div><p>
+ The examples in the previous section illustrated full text matching using
+ simple constant strings. This section shows how to search table data,
+ optionally using indexes.
+ </p><div class="sect2" id="TEXTSEARCH-TABLES-SEARCH"><div class="titlepage"><div><div><h3 class="title">12.2.1. Searching a Table</h3></div></div></div><p>
+ It is possible to do a full text search without an index. A simple query
+ to print the <code class="structname">title</code> of each row that contains the word
+ <code class="literal">friend</code> in its <code class="structfield">body</code> field is:
+
+</p><pre class="programlisting">
+SELECT title
+FROM pgweb
+WHERE to_tsvector('english', body) @@ to_tsquery('english', 'friend');
+</pre><p>
+
+ This will also find related words such as <code class="literal">friends</code>
+ and <code class="literal">friendly</code>, since all these are reduced to the same
+ normalized lexeme.
+ </p><p>
+ The query above specifies that the <code class="literal">english</code> configuration
+ is to be used to parse and normalize the strings. Alternatively we
+ could omit the configuration parameters:
+
+</p><pre class="programlisting">
+SELECT title
+FROM pgweb
+WHERE to_tsvector(body) @@ to_tsquery('friend');
+</pre><p>
+
+ This query will use the configuration set by <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a>.
+ </p><p>
+ A more complex example is to
+ select the ten most recent documents that contain <code class="literal">create</code> and
+ <code class="literal">table</code> in the <code class="structname">title</code> or <code class="structname">body</code>:
+
+</p><pre class="programlisting">
+SELECT title
+FROM pgweb
+WHERE to_tsvector(title || ' ' || body) @@ to_tsquery('create &amp; table')
+ORDER BY last_mod_date DESC
+LIMIT 10;
+</pre><p>
+
+ For clarity we omitted the <code class="function">coalesce</code> function calls
+ which would be needed to find rows that contain <code class="literal">NULL</code>
+ in one of the two fields.
+ </p><p>
+ Although these queries will work without an index, most applications
+ will find this approach too slow, except perhaps for occasional ad-hoc
+ searches. Practical use of text searching usually requires creating
+ an index.
+ </p></div><div class="sect2" id="TEXTSEARCH-TABLES-INDEX"><div class="titlepage"><div><div><h3 class="title">12.2.2. Creating Indexes</h3></div></div></div><p>
+ We can create a <acronym class="acronym">GIN</acronym> index (<a class="xref" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Section 12.9</a>) to speed up text searches:
+
+</p><pre class="programlisting">
+CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', body));
+</pre><p>
+
+ Notice that the 2-argument version of <code class="function">to_tsvector</code> is
+ used. Only text search functions that specify a configuration name can
+ be used in expression indexes (<a class="xref" href="indexes-expressional.html" title="11.7. Indexes on Expressions">Section 11.7</a>).
+ This is because the index contents must be unaffected by <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a>. If they were affected, the
+ index contents might be inconsistent because different entries could
+ contain <code class="type">tsvector</code>s that were created with different text search
+ configurations, and there would be no way to guess which was which. It
+ would be impossible to dump and restore such an index correctly.
+ </p><p>
+ Because the two-argument version of <code class="function">to_tsvector</code> was
+ used in the index above, only a query reference that uses the 2-argument
+ version of <code class="function">to_tsvector</code> with the same configuration
+ name will use that index. That is, <code class="literal">WHERE
+ to_tsvector('english', body) @@ 'a &amp; b'</code> can use the index,
+ but <code class="literal">WHERE to_tsvector(body) @@ 'a &amp; b'</code> cannot.
+ This ensures that an index will be used only with the same configuration
+ used to create the index entries.
+ </p><p>
+ It is possible to set up more complex expression indexes wherein the
+ configuration name is specified by another column, e.g.:
+
+</p><pre class="programlisting">
+CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector(config_name, body));
+</pre><p>
+
+ where <code class="literal">config_name</code> is a column in the <code class="literal">pgweb</code>
+ table. This allows mixed configurations in the same index while
+ recording which configuration was used for each index entry. This
+ would be useful, for example, if the document collection contained
+ documents in different languages. Again,
+ queries that are meant to use the index must be phrased to match, e.g.,
+ <code class="literal">WHERE to_tsvector(config_name, body) @@ 'a &amp; b'</code>.
+ </p><p>
+ Indexes can even concatenate columns:
+
+</p><pre class="programlisting">
+CREATE INDEX pgweb_idx ON pgweb USING GIN (to_tsvector('english', title || ' ' || body));
+</pre><p>
+ </p><p>
+ Another approach is to create a separate <code class="type">tsvector</code> column
+ to hold the output of <code class="function">to_tsvector</code>. To keep this
+ column automatically up to date with its source data, use a stored
+ generated column. This example is a
+ concatenation of <code class="literal">title</code> and <code class="literal">body</code>,
+ using <code class="function">coalesce</code> to ensure that one field will still be
+ indexed when the other is <code class="literal">NULL</code>:
+
+</p><pre class="programlisting">
+ALTER TABLE pgweb
+ ADD COLUMN textsearchable_index_col tsvector
+ GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED;
+</pre><p>
+
+ Then we create a <acronym class="acronym">GIN</acronym> index to speed up the search:
+
+</p><pre class="programlisting">
+CREATE INDEX textsearch_idx ON pgweb USING GIN (textsearchable_index_col);
+</pre><p>
+
+ Now we are ready to perform a fast full text search:
+
+</p><pre class="programlisting">
+SELECT title
+FROM pgweb
+WHERE textsearchable_index_col @@ to_tsquery('create &amp; table')
+ORDER BY last_mod_date DESC
+LIMIT 10;
+</pre><p>
+ </p><p>
+ One advantage of the separate-column approach over an expression index
+ is that it is not necessary to explicitly specify the text search
+ configuration in queries in order to make use of the index. As shown
+ in the example above, the query can depend on
+ <code class="varname">default_text_search_config</code>. Another advantage is that
+ searches will be faster, since it will not be necessary to redo the
+ <code class="function">to_tsvector</code> calls to verify index matches. (This is more
+ important when using a GiST index than a GIN index; see <a class="xref" href="textsearch-indexes.html" title="12.9. Preferred Index Types for Text Search">Section 12.9</a>.) The expression-index approach is
+ simpler to set up, however, and it requires less disk space since the
+ <code class="type">tsvector</code> representation is not stored explicitly.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textsearch-intro.html" title="12.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="textsearch.html" title="Chapter 12. Full Text Search">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-controls.html" title="12.3. Controlling Text Search">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.3. Controlling Text Search</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/textsearch.html b/doc/src/sgml/html/textsearch.html
new file mode 100644
index 0000000..250fcc4
--- /dev/null
+++ b/doc/src/sgml/html/textsearch.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 12. Full Text Search</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexes-examine.html" title="11.12. Examining Index Usage" /><link rel="next" href="textsearch-intro.html" title="12.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 12. Full Text Search</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexes-examine.html" title="11.12. Examining Index Usage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="textsearch-intro.html" title="12.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="TEXTSEARCH"><div class="titlepage"><div><div><h2 class="title">Chapter 12. Full Text Search</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="textsearch-intro.html">12.1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-DOCUMENT">12.1.1. What Is a Document?</a></span></dt><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-MATCHING">12.1.2. Basic Text Matching</a></span></dt><dt><span class="sect2"><a href="textsearch-intro.html#TEXTSEARCH-INTRO-CONFIGURATIONS">12.1.3. Configurations</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-tables.html">12.2. Tables and Indexes</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-tables.html#TEXTSEARCH-TABLES-SEARCH">12.2.1. Searching a Table</a></span></dt><dt><span class="sect2"><a href="textsearch-tables.html#TEXTSEARCH-TABLES-INDEX">12.2.2. Creating Indexes</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-controls.html">12.3. Controlling Text Search</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-PARSING-DOCUMENTS">12.3.1. Parsing Documents</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES">12.3.2. Parsing Queries</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-RANKING">12.3.3. Ranking Search Results</a></span></dt><dt><span class="sect2"><a href="textsearch-controls.html#TEXTSEARCH-HEADLINE">12.3.4. Highlighting Results</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-features.html">12.4. Additional Features</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSVECTOR">12.4.1. Manipulating Documents</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-MANIPULATE-TSQUERY">12.4.2. Manipulating Queries</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS">12.4.3. Triggers for Automatic Updates</a></span></dt><dt><span class="sect2"><a href="textsearch-features.html#TEXTSEARCH-STATISTICS">12.4.4. Gathering Document Statistics</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-parsers.html">12.5. Parsers</a></span></dt><dt><span class="sect1"><a href="textsearch-dictionaries.html">12.6. Dictionaries</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-STOPWORDS">12.6.1. Stop Words</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SIMPLE-DICTIONARY">12.6.2. Simple Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SYNONYM-DICTIONARY">12.6.3. Synonym Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-THESAURUS">12.6.4. Thesaurus Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-ISPELL-DICTIONARY">12.6.5. <span class="application">Ispell</span> Dictionary</a></span></dt><dt><span class="sect2"><a href="textsearch-dictionaries.html#TEXTSEARCH-SNOWBALL-DICTIONARY">12.6.6. <span class="application">Snowball</span> Dictionary</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-configuration.html">12.7. Configuration Example</a></span></dt><dt><span class="sect1"><a href="textsearch-debugging.html">12.8. Testing and Debugging Text Search</a></span></dt><dd><dl><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-CONFIGURATION-TESTING">12.8.1. Configuration Testing</a></span></dt><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-PARSER-TESTING">12.8.2. Parser Testing</a></span></dt><dt><span class="sect2"><a href="textsearch-debugging.html#TEXTSEARCH-DICTIONARY-TESTING">12.8.3. Dictionary Testing</a></span></dt></dl></dd><dt><span class="sect1"><a href="textsearch-indexes.html">12.9. Preferred Index Types for Text Search</a></span></dt><dt><span class="sect1"><a href="textsearch-psql.html">12.10. <span class="application">psql</span> Support</a></span></dt><dt><span class="sect1"><a href="textsearch-limitations.html">12.11. Limitations</a></span></dt></dl></div><a id="id-1.5.11.2" class="indexterm"></a><a id="id-1.5.11.3" class="indexterm"></a></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexes-examine.html" title="11.12. Examining Index Usage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="textsearch-intro.html" title="12.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.12. Examining Index Usage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 12.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/transaction-iso.html b/doc/src/sgml/html/transaction-iso.html
new file mode 100644
index 0000000..bcc71ae
--- /dev/null
+++ b/doc/src/sgml/html/transaction-iso.html
@@ -0,0 +1,540 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>13.2. Transaction Isolation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="mvcc-intro.html" title="13.1. Introduction" /><link rel="next" href="explicit-locking.html" title="13.3. Explicit Locking" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">13.2. Transaction Isolation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="mvcc-intro.html" title="13.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><th width="60%" align="center">Chapter 13. Concurrency Control</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="explicit-locking.html" title="13.3. Explicit Locking">Next</a></td></tr></table><hr /></div><div class="sect1" id="TRANSACTION-ISO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">13.2. Transaction Isolation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="transaction-iso.html#XACT-READ-COMMITTED">13.2.1. Read Committed Isolation Level</a></span></dt><dt><span class="sect2"><a href="transaction-iso.html#XACT-REPEATABLE-READ">13.2.2. Repeatable Read Isolation Level</a></span></dt><dt><span class="sect2"><a href="transaction-iso.html#XACT-SERIALIZABLE">13.2.3. Serializable Isolation Level</a></span></dt></dl></div><a id="id-1.5.12.5.2" class="indexterm"></a><p>
+ The <acronym class="acronym">SQL</acronym> standard defines four levels of
+ transaction isolation. The most strict is Serializable,
+ which is defined by the standard in a paragraph which says that any
+ concurrent execution of a set of Serializable transactions is guaranteed
+ to produce the same effect as running them one at a time in some order.
+ The other three levels are defined in terms of phenomena, resulting from
+ interaction between concurrent transactions, which must not occur at
+ each level. The standard notes that due to the definition of
+ Serializable, none of these phenomena are possible at that level. (This
+ is hardly surprising -- if the effect of the transactions must be
+ consistent with having been run one at a time, how could you see any
+ phenomena caused by interactions?)
+ </p><p>
+ The phenomena which are prohibited at various levels are:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ dirty read
+ <a id="id-1.5.12.5.4.1.1.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ A transaction reads data written by a concurrent uncommitted transaction.
+ </p></dd><dt><span class="term">
+ nonrepeatable read
+ <a id="id-1.5.12.5.4.1.2.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ A transaction re-reads data it has previously read and finds that data
+ has been modified by another transaction (that committed since the
+ initial read).
+ </p></dd><dt><span class="term">
+ phantom read
+ <a id="id-1.5.12.5.4.1.3.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ A transaction re-executes a query returning a set of rows that satisfy a
+ search condition and finds that the set of rows satisfying the condition
+ has changed due to another recently-committed transaction.
+ </p></dd><dt><span class="term">
+ serialization anomaly
+ <a id="id-1.5.12.5.4.1.4.1.1" class="indexterm"></a>
+ </span></dt><dd><p>
+ The result of successfully committing a group of transactions
+ is inconsistent with all possible orderings of running those
+ transactions one at a time.
+ </p></dd></dl></div><p>
+ </p><p>
+ <a id="id-1.5.12.5.5.1" class="indexterm"></a>
+ The SQL standard and PostgreSQL-implemented transaction isolation levels
+ are described in <a class="xref" href="transaction-iso.html#MVCC-ISOLEVEL-TABLE" title="Table 13.1. Transaction Isolation Levels">Table 13.1</a>.
+ </p><div class="table" id="MVCC-ISOLEVEL-TABLE"><p class="title"><strong>Table 13.1. Transaction Isolation Levels</strong></p><div class="table-contents"><table class="table" summary="Transaction Isolation Levels" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th>
+ Isolation Level
+ </th><th>
+ Dirty Read
+ </th><th>
+ Nonrepeatable Read
+ </th><th>
+ Phantom Read
+ </th><th>
+ Serialization Anomaly
+ </th></tr></thead><tbody><tr><td>
+ Read uncommitted
+ </td><td>
+ Allowed, but not in PG
+ </td><td>
+ Possible
+ </td><td>
+ Possible
+ </td><td>
+ Possible
+ </td></tr><tr><td>
+ Read committed
+ </td><td>
+ Not possible
+ </td><td>
+ Possible
+ </td><td>
+ Possible
+ </td><td>
+ Possible
+ </td></tr><tr><td>
+ Repeatable read
+ </td><td>
+ Not possible
+ </td><td>
+ Not possible
+ </td><td>
+ Allowed, but not in PG
+ </td><td>
+ Possible
+ </td></tr><tr><td>
+ Serializable
+ </td><td>
+ Not possible
+ </td><td>
+ Not possible
+ </td><td>
+ Not possible
+ </td><td>
+ Not possible
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ In <span class="productname">PostgreSQL</span>, you can request any of
+ the four standard transaction isolation levels, but internally only
+ three distinct isolation levels are implemented, i.e., PostgreSQL's
+ Read Uncommitted mode behaves like Read Committed. This is because
+ it is the only sensible way to map the standard isolation levels to
+ PostgreSQL's multiversion concurrency control architecture.
+ </p><p>
+ The table also shows that PostgreSQL's Repeatable Read implementation
+ does not allow phantom reads. This is acceptable under the SQL
+ standard because the standard specifies which anomalies must
+ <span class="emphasis"><em>not</em></span> occur at certain isolation levels; higher
+ guarantees are acceptable.
+ The behavior of the available isolation levels is detailed in the
+ following subsections.
+ </p><p>
+ To set the transaction isolation level of a transaction, use the
+ command <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a>.
+ </p><div class="important"><h3 class="title">Important</h3><p>
+ Some <span class="productname">PostgreSQL</span> data types and functions have
+ special rules regarding transactional behavior. In particular, changes
+ made to a sequence (and therefore the counter of a
+ column declared using <code class="type">serial</code>) are immediately visible
+ to all other transactions and are not rolled back if the transaction
+ that made the changes aborts. See <a class="xref" href="functions-sequence.html" title="9.17. Sequence Manipulation Functions">Section 9.17</a>
+ and <a class="xref" href="datatype-numeric.html#DATATYPE-SERIAL" title="8.1.4. Serial Types">Section 8.1.4</a>.
+ </p></div><div class="sect2" id="XACT-READ-COMMITTED"><div class="titlepage"><div><div><h3 class="title">13.2.1. Read Committed Isolation Level</h3></div></div></div><a id="id-1.5.12.5.11.2" class="indexterm"></a><a id="id-1.5.12.5.11.3" class="indexterm"></a><p>
+ <em class="firstterm">Read Committed</em> is the default isolation
+ level in <span class="productname">PostgreSQL</span>. When a transaction
+ uses this isolation level, a <code class="command">SELECT</code> query
+ (without a <code class="literal">FOR UPDATE/SHARE</code> clause) sees only data
+ committed before the query began; it never sees either uncommitted
+ data or changes committed during query execution by concurrent
+ transactions. In effect, a <code class="command">SELECT</code> query sees
+ a snapshot of the database as of the instant the query begins to
+ run. However, <code class="command">SELECT</code> does see the effects
+ of previous updates executed within its own transaction, even
+ though they are not yet committed. Also note that two successive
+ <code class="command">SELECT</code> commands can see different data, even
+ though they are within a single transaction, if other transactions
+ commit changes after the first <code class="command">SELECT</code> starts and
+ before the second <code class="command">SELECT</code> starts.
+ </p><p>
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, <code class="command">SELECT
+ FOR UPDATE</code>, and <code class="command">SELECT FOR SHARE</code> commands
+ behave the same as <code class="command">SELECT</code>
+ in terms of searching for target rows: they will only find target rows
+ that were committed as of the command start time. However, such a target
+ row might have already been updated (or deleted or locked) by
+ another concurrent transaction by the time it is found. In this case, the
+ would-be updater will wait for the first updating transaction to commit or
+ roll back (if it is still in progress). If the first updater rolls back,
+ then its effects are negated and the second updater can proceed with
+ updating the originally found row. If the first updater commits, the
+ second updater will ignore the row if the first updater deleted it,
+ otherwise it will attempt to apply its operation to the updated version of
+ the row. The search condition of the command (the <code class="literal">WHERE</code> clause) is
+ re-evaluated to see if the updated version of the row still matches the
+ search condition. If so, the second updater proceeds with its operation
+ using the updated version of the row. In the case of
+ <code class="command">SELECT FOR UPDATE</code> and <code class="command">SELECT FOR
+ SHARE</code>, this means it is the updated version of the row that is
+ locked and returned to the client.
+ </p><p>
+ <code class="command">INSERT</code> with an <code class="literal">ON CONFLICT DO UPDATE</code> clause
+ behaves similarly. In Read Committed mode, each row proposed for insertion
+ will either insert or update. Unless there are unrelated errors, one of
+ those two outcomes is guaranteed. If a conflict originates in another
+ transaction whose effects are not yet visible to the <code class="command">INSERT</code>,
+ the <code class="command">UPDATE</code> clause will affect that row,
+ even though possibly <span class="emphasis"><em>no</em></span> version of that row is
+ conventionally visible to the command.
+ </p><p>
+ <code class="command">INSERT</code> with an <code class="literal">ON CONFLICT DO
+ NOTHING</code> clause may have insertion not proceed for a row due to
+ the outcome of another transaction whose effects are not visible
+ to the <code class="command">INSERT</code> snapshot. Again, this is only
+ the case in Read Committed mode.
+ </p><p>
+ <code class="command">MERGE</code> allows the user to specify various
+ combinations of <code class="command">INSERT</code>, <code class="command">UPDATE</code>
+ and <code class="command">DELETE</code> subcommands. A <code class="command">MERGE</code>
+ command with both <code class="command">INSERT</code> and <code class="command">UPDATE</code>
+ subcommands looks similar to <code class="command">INSERT</code> with an
+ <code class="literal">ON CONFLICT DO UPDATE</code> clause but does not
+ guarantee that either <code class="command">INSERT</code> or
+ <code class="command">UPDATE</code> will occur.
+ If <code class="command">MERGE</code> attempts an <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> and the row is concurrently updated but
+ the join condition still passes for the current target and the
+ current source tuple, then <code class="command">MERGE</code> will behave
+ the same as the <code class="command">UPDATE</code> or
+ <code class="command">DELETE</code> commands and perform its action on the
+ updated version of the row. However, because <code class="command">MERGE</code>
+ can specify several actions and they can be conditional, the
+ conditions for each action are re-evaluated on the updated version of
+ the row, starting from the first action, even if the action that had
+ originally matched appears later in the list of actions.
+ On the other hand, if the row is concurrently updated or deleted so
+ that the join condition fails, then <code class="command">MERGE</code> will
+ evaluate the condition's <code class="literal">NOT MATCHED</code> actions next,
+ and execute the first one that succeeds.
+ If <code class="command">MERGE</code> attempts an <code class="command">INSERT</code>
+ and a unique index is present and a duplicate row is concurrently
+ inserted, then a uniqueness violation error is raised;
+ <code class="command">MERGE</code> does not attempt to avoid such
+ errors by restarting evaluation of <code class="literal">MATCHED</code>
+ conditions.
+ </p><p>
+ Because of the above rules, it is possible for an updating command to see
+ an inconsistent snapshot: it can see the effects of concurrent updating
+ commands on the same rows it is trying to update, but it
+ does not see effects of those commands on other rows in the database.
+ This behavior makes Read Committed mode unsuitable for commands that
+ involve complex search conditions; however, it is just right for simpler
+ cases. For example, consider updating bank balances with transactions
+ like:
+
+</p><pre class="screen">
+BEGIN;
+UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 12345;
+UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 7534;
+COMMIT;
+</pre><p>
+
+ If two such transactions concurrently try to change the balance of account
+ 12345, we clearly want the second transaction to start with the updated
+ version of the account's row. Because each command is affecting only a
+ predetermined row, letting it see the updated version of the row does
+ not create any troublesome inconsistency.
+ </p><p>
+ More complex usage can produce undesirable results in Read Committed
+ mode. For example, consider a <code class="command">DELETE</code> command
+ operating on data that is being both added and removed from its
+ restriction criteria by another command, e.g., assume
+ <code class="literal">website</code> is a two-row table with
+ <code class="literal">website.hits</code> equaling <code class="literal">9</code> and
+ <code class="literal">10</code>:
+
+</p><pre class="screen">
+BEGIN;
+UPDATE website SET hits = hits + 1;
+-- run from another session: DELETE FROM website WHERE hits = 10;
+COMMIT;
+</pre><p>
+
+ The <code class="command">DELETE</code> will have no effect even though
+ there is a <code class="literal">website.hits = 10</code> row before and
+ after the <code class="command">UPDATE</code>. This occurs because the
+ pre-update row value <code class="literal">9</code> is skipped, and when the
+ <code class="command">UPDATE</code> completes and <code class="command">DELETE</code>
+ obtains a lock, the new row value is no longer <code class="literal">10</code> but
+ <code class="literal">11</code>, which no longer matches the criteria.
+ </p><p>
+ Because Read Committed mode starts each command with a new snapshot
+ that includes all transactions committed up to that instant,
+ subsequent commands in the same transaction will see the effects
+ of the committed concurrent transaction in any case. The point
+ at issue above is whether or not a <span class="emphasis"><em>single</em></span> command
+ sees an absolutely consistent view of the database.
+ </p><p>
+ The partial transaction isolation provided by Read Committed mode
+ is adequate for many applications, and this mode is fast and simple
+ to use; however, it is not sufficient for all cases. Applications
+ that do complex queries and updates might require a more rigorously
+ consistent view of the database than Read Committed mode provides.
+ </p></div><div class="sect2" id="XACT-REPEATABLE-READ"><div class="titlepage"><div><div><h3 class="title">13.2.2. Repeatable Read Isolation Level</h3></div></div></div><a id="id-1.5.12.5.12.2" class="indexterm"></a><a id="id-1.5.12.5.12.3" class="indexterm"></a><p>
+ The <em class="firstterm">Repeatable Read</em> isolation level only sees
+ data committed before the transaction began; it never sees either
+ uncommitted data or changes committed during transaction execution
+ by concurrent transactions. (However, the query does see the
+ effects of previous updates executed within its own transaction,
+ even though they are not yet committed.) This is a stronger
+ guarantee than is required by the <acronym class="acronym">SQL</acronym> standard
+ for this isolation level, and prevents all of the phenomena described
+ in <a class="xref" href="transaction-iso.html#MVCC-ISOLEVEL-TABLE" title="Table 13.1. Transaction Isolation Levels">Table 13.1</a> except for serialization
+ anomalies. As mentioned above, this is
+ specifically allowed by the standard, which only describes the
+ <span class="emphasis"><em>minimum</em></span> protections each isolation level must
+ provide.
+ </p><p>
+ This level is different from Read Committed in that a query in a
+ repeatable read transaction sees a snapshot as of the start of the
+ first non-transaction-control statement in the
+ <span class="emphasis"><em>transaction</em></span>, not as of the start
+ of the current statement within the transaction. Thus, successive
+ <code class="command">SELECT</code> commands within a <span class="emphasis"><em>single</em></span>
+ transaction see the same data, i.e., they do not see changes made by
+ other transactions that committed after their own transaction started.
+ </p><p>
+ Applications using this level must be prepared to retry transactions
+ due to serialization failures.
+ </p><p>
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>,
+ <code class="command">MERGE</code>, <code class="command">SELECT FOR UPDATE</code>,
+ and <code class="command">SELECT FOR SHARE</code> commands
+ behave the same as <code class="command">SELECT</code>
+ in terms of searching for target rows: they will only find target rows
+ that were committed as of the transaction start time. However, such a
+ target row might have already been updated (or deleted or locked) by
+ another concurrent transaction by the time it is found. In this case, the
+ repeatable read transaction will wait for the first updating transaction to commit or
+ roll back (if it is still in progress). If the first updater rolls back,
+ then its effects are negated and the repeatable read transaction can proceed
+ with updating the originally found row. But if the first updater commits
+ (and actually updated or deleted the row, not just locked it)
+ then the repeatable read transaction will be rolled back with the message
+
+</p><pre class="screen">
+ERROR: could not serialize access due to concurrent update
+</pre><p>
+
+ because a repeatable read transaction cannot modify or lock rows changed by
+ other transactions after the repeatable read transaction began.
+ </p><p>
+ When an application receives this error message, it should abort
+ the current transaction and retry the whole transaction from
+ the beginning. The second time through, the transaction will see the
+ previously-committed change as part of its initial view of the database,
+ so there is no logical conflict in using the new version of the row
+ as the starting point for the new transaction's update.
+ </p><p>
+ Note that only updating transactions might need to be retried; read-only
+ transactions will never have serialization conflicts.
+ </p><p>
+ The Repeatable Read mode provides a rigorous guarantee that each
+ transaction sees a completely stable view of the database. However,
+ this view will not necessarily always be consistent with some serial
+ (one at a time) execution of concurrent transactions of the same level.
+ For example, even a read-only transaction at this level may see a
+ control record updated to show that a batch has been completed but
+ <span class="emphasis"><em>not</em></span> see one of the detail records which is logically
+ part of the batch because it read an earlier revision of the control
+ record. Attempts to enforce business rules by transactions running at
+ this isolation level are not likely to work correctly without careful use
+ of explicit locks to block conflicting transactions.
+ </p><p>
+ The Repeatable Read isolation level is implemented using a technique
+ known in academic database literature and in some other database products
+ as <em class="firstterm">Snapshot Isolation</em>. Differences in behavior
+ and performance may be observed when compared with systems that use a
+ traditional locking technique that reduces concurrency. Some other
+ systems may even offer Repeatable Read and Snapshot Isolation as distinct
+ isolation levels with different behavior. The permitted phenomena that
+ distinguish the two techniques were not formalized by database researchers
+ until after the SQL standard was developed, and are outside the scope of
+ this manual. For a full treatment, please see
+ <a class="xref" href="biblio.html#BERENSON95">[berenson95]</a>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> version 9.1, a request
+ for the Serializable transaction isolation level provided exactly the
+ same behavior described here. To retain the legacy Serializable
+ behavior, Repeatable Read should now be requested.
+ </p></div></div><div class="sect2" id="XACT-SERIALIZABLE"><div class="titlepage"><div><div><h3 class="title">13.2.3. Serializable Isolation Level</h3></div></div></div><a id="id-1.5.12.5.13.2" class="indexterm"></a><a id="id-1.5.12.5.13.3" class="indexterm"></a><a id="id-1.5.12.5.13.4" class="indexterm"></a><a id="id-1.5.12.5.13.5" class="indexterm"></a><p>
+ The <em class="firstterm">Serializable</em> isolation level provides
+ the strictest transaction isolation. This level emulates serial
+ transaction execution for all committed transactions;
+ as if transactions had been executed one after another, serially,
+ rather than concurrently. However, like the Repeatable Read level,
+ applications using this level must
+ be prepared to retry transactions due to serialization failures.
+ In fact, this isolation level works exactly the same as Repeatable
+ Read except that it also monitors for conditions which could make
+ execution of a concurrent set of serializable transactions behave
+ in a manner inconsistent with all possible serial (one at a time)
+ executions of those transactions. This monitoring does not
+ introduce any blocking beyond that present in repeatable read, but
+ there is some overhead to the monitoring, and detection of the
+ conditions which could cause a
+ <em class="firstterm">serialization anomaly</em> will trigger a
+ <em class="firstterm">serialization failure</em>.
+ </p><p>
+ As an example,
+ consider a table <code class="structname">mytab</code>, initially containing:
+</p><pre class="screen">
+ class | value
+-------+-------
+ 1 | 10
+ 1 | 20
+ 2 | 100
+ 2 | 200
+</pre><p>
+ Suppose that serializable transaction A computes:
+</p><pre class="screen">
+SELECT SUM(value) FROM mytab WHERE class = 1;
+</pre><p>
+ and then inserts the result (30) as the <code class="structfield">value</code> in a
+ new row with <code class="structfield">class</code><code class="literal"> = 2</code>. Concurrently, serializable
+ transaction B computes:
+</p><pre class="screen">
+SELECT SUM(value) FROM mytab WHERE class = 2;
+</pre><p>
+ and obtains the result 300, which it inserts in a new row with
+ <code class="structfield">class</code><code class="literal"> = 1</code>. Then both transactions try to commit.
+ If either transaction were running at the Repeatable Read isolation level,
+ both would be allowed to commit; but since there is no serial order of execution
+ consistent with the result, using Serializable transactions will allow one
+ transaction to commit and will roll the other back with this message:
+
+</p><pre class="screen">
+ERROR: could not serialize access due to read/write dependencies among transactions
+</pre><p>
+
+ This is because if A had
+ executed before B, B would have computed the sum 330, not 300, and
+ similarly the other order would have resulted in a different sum
+ computed by A.
+ </p><p>
+ When relying on Serializable transactions to prevent anomalies, it is
+ important that any data read from a permanent user table not be
+ considered valid until the transaction which read it has successfully
+ committed. This is true even for read-only transactions, except that
+ data read within a <em class="firstterm">deferrable</em> read-only
+ transaction is known to be valid as soon as it is read, because such a
+ transaction waits until it can acquire a snapshot guaranteed to be free
+ from such problems before starting to read any data. In all other cases
+ applications must not depend on results read during a transaction that
+ later aborted; instead, they should retry the transaction until it
+ succeeds.
+ </p><p>
+ To guarantee true serializability <span class="productname">PostgreSQL</span>
+ uses <em class="firstterm">predicate locking</em>, which means that it keeps locks
+ which allow it to determine when a write would have had an impact on
+ the result of a previous read from a concurrent transaction, had it run
+ first. In <span class="productname">PostgreSQL</span> these locks do not
+ cause any blocking and therefore can <span class="emphasis"><em>not</em></span> play any part in
+ causing a deadlock. They are used to identify and flag dependencies
+ among concurrent Serializable transactions which in certain combinations
+ can lead to serialization anomalies. In contrast, a Read Committed or
+ Repeatable Read transaction which wants to ensure data consistency may
+ need to take out a lock on an entire table, which could block other
+ users attempting to use that table, or it may use <code class="literal">SELECT FOR
+ UPDATE</code> or <code class="literal">SELECT FOR SHARE</code> which not only
+ can block other transactions but cause disk access.
+ </p><p>
+ Predicate locks in <span class="productname">PostgreSQL</span>, like in most
+ other database systems, are based on data actually accessed by a
+ transaction. These will show up in the
+ <a class="link" href="view-pg-locks.html" title="54.12. pg_locks"><code class="structname">pg_locks</code></a>
+ system view with a <code class="literal">mode</code> of <code class="literal">SIReadLock</code>. The
+ particular locks
+ acquired during execution of a query will depend on the plan used by
+ the query, and multiple finer-grained locks (e.g., tuple locks) may be
+ combined into fewer coarser-grained locks (e.g., page locks) during the
+ course of the transaction to prevent exhaustion of the memory used to
+ track the locks. A <code class="literal">READ ONLY</code> transaction may be able to
+ release its SIRead locks before completion, if it detects that no
+ conflicts can still occur which could lead to a serialization anomaly.
+ In fact, <code class="literal">READ ONLY</code> transactions will often be able to
+ establish that fact at startup and avoid taking any predicate locks.
+ If you explicitly request a <code class="literal">SERIALIZABLE READ ONLY DEFERRABLE</code>
+ transaction, it will block until it can establish this fact. (This is
+ the <span class="emphasis"><em>only</em></span> case where Serializable transactions block but
+ Repeatable Read transactions don't.) On the other hand, SIRead locks
+ often need to be kept past transaction commit, until overlapping read
+ write transactions complete.
+ </p><p>
+ Consistent use of Serializable transactions can simplify development.
+ The guarantee that any set of successfully committed concurrent
+ Serializable transactions will have the same effect as if they were run
+ one at a time means that if you can demonstrate that a single transaction,
+ as written, will do the right thing when run by itself, you can have
+ confidence that it will do the right thing in any mix of Serializable
+ transactions, even without any information about what those other
+ transactions might do, or it will not successfully commit. It is
+ important that an environment which uses this technique have a
+ generalized way of handling serialization failures (which always return
+ with an SQLSTATE value of '40001'), because it will be very hard to
+ predict exactly which transactions might contribute to the read/write
+ dependencies and need to be rolled back to prevent serialization
+ anomalies. The monitoring of read/write dependencies has a cost, as does
+ the restart of transactions which are terminated with a serialization
+ failure, but balanced against the cost and blocking involved in use of
+ explicit locks and <code class="literal">SELECT FOR UPDATE</code> or <code class="literal">SELECT FOR
+ SHARE</code>, Serializable transactions are the best performance choice
+ for some environments.
+ </p><p>
+ While <span class="productname">PostgreSQL</span>'s Serializable transaction isolation
+ level only allows concurrent transactions to commit if it can prove there
+ is a serial order of execution that would produce the same effect, it
+ doesn't always prevent errors from being raised that would not occur in
+ true serial execution. In particular, it is possible to see unique
+ constraint violations caused by conflicts with overlapping Serializable
+ transactions even after explicitly checking that the key isn't present
+ before attempting to insert it. This can be avoided by making sure
+ that <span class="emphasis"><em>all</em></span> Serializable transactions that insert potentially
+ conflicting keys explicitly check if they can do so first. For example,
+ imagine an application that asks the user for a new key and then checks
+ that it doesn't exist already by trying to select it first, or generates
+ a new key by selecting the maximum existing key and adding one. If some
+ Serializable transactions insert new keys directly without following this
+ protocol, unique constraints violations might be reported even in cases
+ where they could not occur in a serial execution of the concurrent
+ transactions.
+ </p><p>
+ For optimal performance when relying on Serializable transactions for
+ concurrency control, these issues should be considered:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Declare transactions as <code class="literal">READ ONLY</code> when possible.
+ </p></li><li class="listitem"><p>
+ Control the number of active connections, using a connection pool if
+ needed. This is always an important performance consideration, but
+ it can be particularly important in a busy system using Serializable
+ transactions.
+ </p></li><li class="listitem"><p>
+ Don't put more into a single transaction than needed for integrity
+ purposes.
+ </p></li><li class="listitem"><p>
+ Don't leave connections dangling <span class="quote">“<span class="quote">idle in transaction</span>”</span>
+ longer than necessary. The configuration parameter
+ <a class="xref" href="runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT">idle_in_transaction_session_timeout</a> may be used to
+ automatically disconnect lingering sessions.
+ </p></li><li class="listitem"><p>
+ Eliminate explicit locks, <code class="literal">SELECT FOR UPDATE</code>, and
+ <code class="literal">SELECT FOR SHARE</code> where no longer needed due to the
+ protections automatically provided by Serializable transactions.
+ </p></li><li class="listitem"><p>
+ When the system is forced to combine multiple page-level predicate
+ locks into a single relation-level predicate lock because the predicate
+ lock table is short of memory, an increase in the rate of serialization
+ failures may occur. You can avoid this by increasing
+ <a class="xref" href="runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-TRANSACTION">max_pred_locks_per_transaction</a>,
+ <a class="xref" href="runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-RELATION">max_pred_locks_per_relation</a>, and/or
+ <a class="xref" href="runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-PAGE">max_pred_locks_per_page</a>.
+ </p></li><li class="listitem"><p>
+ A sequential scan will always necessitate a relation-level predicate
+ lock. This can result in an increased rate of serialization failures.
+ It may be helpful to encourage the use of index scans by reducing
+ <a class="xref" href="runtime-config-query.html#GUC-RANDOM-PAGE-COST">random_page_cost</a> and/or increasing
+ <a class="xref" href="runtime-config-query.html#GUC-CPU-TUPLE-COST">cpu_tuple_cost</a>. Be sure to weigh any decrease
+ in transaction rollbacks and restarts against any overall change in
+ query execution time.
+ </p></li></ul></div><p>
+ </p><p>
+ The Serializable isolation level is implemented using a technique known
+ in academic database literature as Serializable Snapshot Isolation, which
+ builds on Snapshot Isolation by adding checks for serialization anomalies.
+ Some differences in behavior and performance may be observed when compared
+ with other systems that use a traditional locking technique. Please see
+ <a class="xref" href="biblio.html#PORTS12">[ports12]</a> for detailed information.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mvcc-intro.html" title="13.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mvcc.html" title="Chapter 13. Concurrency Control">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="explicit-locking.html" title="13.3. Explicit Locking">Next</a></td></tr><tr><td width="40%" align="left" valign="top">13.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 13.3. Explicit Locking</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/trigger-datachanges.html b/doc/src/sgml/html/trigger-datachanges.html
new file mode 100644
index 0000000..68614aa
--- /dev/null
+++ b/doc/src/sgml/html/trigger-datachanges.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>39.2. Visibility of Data Changes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior" /><link rel="next" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">39.2. Visibility of Data Changes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><th width="60%" align="center">Chapter 39. Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C">Next</a></td></tr></table><hr /></div><div class="sect1" id="TRIGGER-DATACHANGES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">39.2. Visibility of Data Changes</h2></div></div></div><p>
+ If you execute SQL commands in your trigger function, and these
+ commands access the table that the trigger is for, then
+ you need to be aware of the data visibility rules, because they determine
+ whether these SQL commands will see the data change that the trigger
+ is fired for. Briefly:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Statement-level triggers follow simple visibility rules: none of
+ the changes made by a statement are visible to statement-level
+ <code class="literal">BEFORE</code> triggers, whereas all
+ modifications are visible to statement-level <code class="literal">AFTER</code>
+ triggers.
+ </p></li><li class="listitem"><p>
+ The data change (insertion, update, or deletion) causing the
+ trigger to fire is naturally <span class="emphasis"><em>not</em></span> visible
+ to SQL commands executed in a row-level <code class="literal">BEFORE</code> trigger,
+ because it hasn't happened yet.
+ </p></li><li class="listitem"><p>
+ However, SQL commands executed in a row-level <code class="literal">BEFORE</code>
+ trigger <span class="emphasis"><em>will</em></span> see the effects of data
+ changes for rows previously processed in the same outer
+ command. This requires caution, since the ordering of these
+ change events is not in general predictable; an SQL command that
+ affects multiple rows can visit the rows in any order.
+ </p></li><li class="listitem"><p>
+ Similarly, a row-level <code class="literal">INSTEAD OF</code> trigger will see the
+ effects of data changes made by previous firings of <code class="literal">INSTEAD
+ OF</code> triggers in the same outer command.
+ </p></li><li class="listitem"><p>
+ When a row-level <code class="literal">AFTER</code> trigger is fired, all data
+ changes made
+ by the outer command are already complete, and are visible to
+ the invoked trigger function.
+ </p></li></ul></div><p>
+ </p><p>
+ If your trigger function is written in any of the standard procedural
+ languages, then the above statements apply only if the function is
+ declared <code class="literal">VOLATILE</code>. Functions that are declared
+ <code class="literal">STABLE</code> or <code class="literal">IMMUTABLE</code> will not see changes made by
+ the calling command in any case.
+ </p><p>
+ Further information about data visibility rules can be found in
+ <a class="xref" href="spi-visibility.html" title="47.5. Visibility of Data Changes">Section 47.5</a>. The example in <a class="xref" href="trigger-example.html" title="39.4. A Complete Trigger Example">Section 39.4</a> contains a demonstration of these rules.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C">Next</a></td></tr><tr><td width="40%" align="left" valign="top">39.1. Overview of Trigger Behavior </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 39.3. Writing Trigger Functions in C</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/trigger-definition.html b/doc/src/sgml/html/trigger-definition.html
new file mode 100644
index 0000000..f791221
--- /dev/null
+++ b/doc/src/sgml/html/trigger-definition.html
@@ -0,0 +1,315 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>39.1. Overview of Trigger Behavior</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="triggers.html" title="Chapter 39. Triggers" /><link rel="next" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">39.1. Overview of Trigger Behavior</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="triggers.html" title="Chapter 39. Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><th width="60%" align="center">Chapter 39. Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes">Next</a></td></tr></table><hr /></div><div class="sect1" id="TRIGGER-DEFINITION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">39.1. Overview of Trigger Behavior</h2></div></div></div><p>
+ A trigger is a specification that the database should automatically
+ execute a particular function whenever a certain type of operation is
+ performed. Triggers can be attached to tables (partitioned or not),
+ views, and foreign tables.
+ </p><p>
+ On tables and foreign tables, triggers can be defined to execute either
+ before or after any <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ or <code class="command">DELETE</code> operation, either once per modified row,
+ or once per <acronym class="acronym">SQL</acronym> statement.
+ <code class="command">UPDATE</code> triggers can moreover be set to fire only if
+ certain columns are mentioned in the <code class="literal">SET</code> clause of
+ the <code class="command">UPDATE</code> statement. Triggers can also fire
+ for <code class="command">TRUNCATE</code> statements. If a trigger event occurs,
+ the trigger's function is called at the appropriate time to handle the
+ event.
+ </p><p>
+ On views, triggers can be defined to execute instead of
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> operations.
+ Such <code class="literal">INSTEAD OF</code> triggers
+ are fired once for each row that needs to be modified in the view.
+ It is the responsibility of the
+ trigger's function to perform the necessary modifications to the view's
+ underlying base table(s) and, where appropriate, return the modified
+ row as it will appear in the view. Triggers on views can also be defined
+ to execute once per <acronym class="acronym">SQL</acronym> statement, before or after
+ <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or
+ <code class="command">DELETE</code> operations.
+ However, such triggers are fired only if there is also
+ an <code class="literal">INSTEAD OF</code> trigger on the view. Otherwise,
+ any statement targeting the view must be rewritten into a statement
+ affecting its underlying base table(s), and then the triggers
+ that will be fired are the ones attached to the base table(s).
+ </p><p>
+ The trigger function must be defined before the trigger itself can be
+ created. The trigger function must be declared as a
+ function taking no arguments and returning type <code class="literal">trigger</code>.
+ (The trigger function receives its input through a specially-passed
+ <code class="structname">TriggerData</code> structure, not in the form of ordinary function
+ arguments.)
+ </p><p>
+ Once a suitable trigger function has been created, the trigger is
+ established with
+ <a class="xref" href="sql-createtrigger.html" title="CREATE TRIGGER"><span class="refentrytitle">CREATE TRIGGER</span></a>.
+ The same trigger function can be used for multiple triggers.
+ </p><p>
+ <span class="productname">PostgreSQL</span> offers both <em class="firstterm">per-row</em>
+ triggers and <em class="firstterm">per-statement</em> triggers. With a per-row
+ trigger, the trigger function
+ is invoked once for each row that is affected by the statement
+ that fired the trigger. In contrast, a per-statement trigger is
+ invoked only once when an appropriate statement is executed,
+ regardless of the number of rows affected by that statement. In
+ particular, a statement that affects zero rows will still result
+ in the execution of any applicable per-statement triggers. These
+ two types of triggers are sometimes called <em class="firstterm">row-level</em>
+ triggers and <em class="firstterm">statement-level</em> triggers,
+ respectively. Triggers on <code class="command">TRUNCATE</code> may only be
+ defined at statement level, not per-row.
+ </p><p>
+ Triggers are also classified according to whether they fire
+ <em class="firstterm">before</em>, <em class="firstterm">after</em>, or
+ <em class="firstterm">instead of</em> the operation. These are referred to
+ as <code class="literal">BEFORE</code> triggers, <code class="literal">AFTER</code> triggers, and
+ <code class="literal">INSTEAD OF</code> triggers respectively.
+ Statement-level <code class="literal">BEFORE</code> triggers naturally fire before the
+ statement starts to do anything, while statement-level <code class="literal">AFTER</code>
+ triggers fire at the very end of the statement. These types of
+ triggers may be defined on tables, views, or foreign tables. Row-level
+ <code class="literal">BEFORE</code> triggers fire immediately before a particular row is
+ operated on, while row-level <code class="literal">AFTER</code> triggers fire at the end of
+ the statement (but before any statement-level <code class="literal">AFTER</code> triggers).
+ These types of triggers may only be defined on tables and
+ foreign tables, not views.
+ <code class="literal">INSTEAD OF</code> triggers may only be
+ defined on views, and only at row level; they fire immediately as each
+ row in the view is identified as needing to be operated on.
+ </p><p>
+ The execution of an <code class="literal">AFTER</code> trigger can be deferred
+ to the end of the transaction, rather than the end of the statement,
+ if it was defined as a <em class="firstterm">constraint trigger</em>.
+ In all cases, a trigger is executed as part of the same transaction as
+ the statement that triggered it, so if either the statement or the
+ trigger causes an error, the effects of both will be rolled back.
+ </p><p>
+ A statement that targets a parent table in an inheritance or partitioning
+ hierarchy does not cause the statement-level triggers of affected child
+ tables to be fired; only the parent table's statement-level triggers are
+ fired. However, row-level triggers of any affected child tables will be
+ fired.
+ </p><p>
+ If an <code class="command">INSERT</code> contains an <code class="literal">ON CONFLICT
+ DO UPDATE</code> clause, it is possible that the effects of
+ row-level <code class="literal">BEFORE</code> <code class="command">INSERT</code> triggers and
+ row-level <code class="literal">BEFORE</code> <code class="command">UPDATE</code> triggers can
+ both be applied in a way that is apparent from the final state of
+ the updated row, if an <code class="varname">EXCLUDED</code> column is referenced.
+ There need not be an <code class="varname">EXCLUDED</code> column reference for
+ both sets of row-level <code class="literal">BEFORE</code> triggers to execute,
+ though. The
+ possibility of surprising outcomes should be considered when there
+ are both <code class="literal">BEFORE</code> <code class="command">INSERT</code> and
+ <code class="literal">BEFORE</code> <code class="command">UPDATE</code> row-level triggers
+ that change a row being inserted/updated (this can be
+ problematic even if the modifications are more or less equivalent, if
+ they're not also idempotent). Note that statement-level
+ <code class="command">UPDATE</code> triggers are executed when <code class="literal">ON
+ CONFLICT DO UPDATE</code> is specified, regardless of whether or not
+ any rows were affected by the <code class="command">UPDATE</code> (and
+ regardless of whether the alternative <code class="command">UPDATE</code>
+ path was ever taken). An <code class="command">INSERT</code> with an
+ <code class="literal">ON CONFLICT DO UPDATE</code> clause will execute
+ statement-level <code class="literal">BEFORE</code> <code class="command">INSERT</code>
+ triggers first, then statement-level <code class="literal">BEFORE</code>
+ <code class="command">UPDATE</code> triggers, followed by statement-level
+ <code class="literal">AFTER</code> <code class="command">UPDATE</code> triggers and finally
+ statement-level <code class="literal">AFTER</code> <code class="command">INSERT</code>
+ triggers.
+ </p><p>
+ If an <code class="command">UPDATE</code> on a partitioned table causes a row to move
+ to another partition, it will be performed as a <code class="command">DELETE</code>
+ from the original partition followed by an <code class="command">INSERT</code> into
+ the new partition. In this case, all row-level <code class="literal">BEFORE</code>
+ <code class="command">UPDATE</code> triggers and all row-level
+ <code class="literal">BEFORE</code> <code class="command">DELETE</code> triggers are fired on
+ the original partition. Then all row-level <code class="literal">BEFORE</code>
+ <code class="command">INSERT</code> triggers are fired on the destination partition.
+ The possibility of surprising outcomes should be considered when all these
+ triggers affect the row being moved. As far as <code class="literal">AFTER ROW</code>
+ triggers are concerned, <code class="literal">AFTER</code> <code class="command">DELETE</code>
+ and <code class="literal">AFTER</code> <code class="command">INSERT</code> triggers are
+ applied; but <code class="literal">AFTER</code> <code class="command">UPDATE</code> triggers
+ are not applied because the <code class="command">UPDATE</code> has been converted to
+ a <code class="command">DELETE</code> and an <code class="command">INSERT</code>. As far as
+ statement-level triggers are concerned, none of the
+ <code class="command">DELETE</code> or <code class="command">INSERT</code> triggers are fired,
+ even if row movement occurs; only the <code class="command">UPDATE</code> triggers
+ defined on the target table used in the <code class="command">UPDATE</code> statement
+ will be fired.
+ </p><p>
+ No separate triggers are defined for <code class="command">MERGE</code>. Instead,
+ statement-level or row-level <code class="command">UPDATE</code>,
+ <code class="command">DELETE</code>, and <code class="command">INSERT</code> triggers are fired
+ depending on (for statement-level triggers) what actions are specified in
+ the <code class="command">MERGE</code> query and (for row-level triggers) what
+ actions are performed.
+ </p><p>
+ While running a <code class="command">MERGE</code> command, statement-level
+ <code class="literal">BEFORE</code> and <code class="literal">AFTER</code> triggers are
+ fired for events specified in the actions of the <code class="command">MERGE</code>
+ command, irrespective of whether or not the action is ultimately performed.
+ This is the same as an <code class="command">UPDATE</code> statement that updates
+ no rows, yet statement-level triggers are fired.
+ The row-level triggers are fired only when a row is actually updated,
+ inserted or deleted. So it's perfectly legal that while statement-level
+ triggers are fired for certain types of action, no row-level triggers
+ are fired for the same kind of action.
+ </p><p>
+ Trigger functions invoked by per-statement triggers should always
+ return <code class="symbol">NULL</code>. Trigger functions invoked by per-row
+ triggers can return a table row (a value of
+ type <code class="structname">HeapTuple</code>) to the calling executor,
+ if they choose. A row-level trigger fired before an operation has
+ the following choices:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ It can return <code class="symbol">NULL</code> to skip the operation for the
+ current row. This instructs the executor to not perform the
+ row-level operation that invoked the trigger (the insertion,
+ modification, or deletion of a particular table row).
+ </p></li><li class="listitem"><p>
+ For row-level <code class="command">INSERT</code>
+ and <code class="command">UPDATE</code> triggers only, the returned row
+ becomes the row that will be inserted or will replace the row
+ being updated. This allows the trigger function to modify the
+ row being inserted or updated.
+ </p></li></ul></div><p>
+
+ A row-level <code class="literal">BEFORE</code> trigger that does not intend to cause
+ either of these behaviors must be careful to return as its result the same
+ row that was passed in (that is, the <code class="varname">NEW</code> row
+ for <code class="command">INSERT</code> and <code class="command">UPDATE</code>
+ triggers, the <code class="varname">OLD</code> row for
+ <code class="command">DELETE</code> triggers).
+ </p><p>
+ A row-level <code class="literal">INSTEAD OF</code> trigger should either return
+ <code class="symbol">NULL</code> to indicate that it did not modify any data from
+ the view's underlying base tables, or it should return the view
+ row that was passed in (the <code class="varname">NEW</code> row
+ for <code class="command">INSERT</code> and <code class="command">UPDATE</code>
+ operations, or the <code class="varname">OLD</code> row for
+ <code class="command">DELETE</code> operations). A nonnull return value is
+ used to signal that the trigger performed the necessary data
+ modifications in the view. This will cause the count of the number
+ of rows affected by the command to be incremented. For
+ <code class="command">INSERT</code> and <code class="command">UPDATE</code> operations only, the trigger
+ may modify the <code class="varname">NEW</code> row before returning it. This will
+ change the data returned by
+ <code class="command">INSERT RETURNING</code> or <code class="command">UPDATE RETURNING</code>,
+ and is useful when the view will not show exactly the same data
+ that was provided.
+ </p><p>
+ The return value is ignored for row-level triggers fired after an
+ operation, and so they can return <code class="symbol">NULL</code>.
+ </p><p>
+ Some considerations apply for generated
+ columns.<a id="id-1.8.4.5.18.1" class="indexterm"></a> Stored generated columns are computed after
+ <code class="literal">BEFORE</code> triggers and before <code class="literal">AFTER</code>
+ triggers. Therefore, the generated value can be inspected in
+ <code class="literal">AFTER</code> triggers. In <code class="literal">BEFORE</code> triggers,
+ the <code class="literal">OLD</code> row contains the old generated value, as one
+ would expect, but the <code class="literal">NEW</code> row does not yet contain the
+ new generated value and should not be accessed. In the C language
+ interface, the content of the column is undefined at this point; a
+ higher-level programming language should prevent access to a stored
+ generated column in the <code class="literal">NEW</code> row in a
+ <code class="literal">BEFORE</code> trigger. Changes to the value of a generated
+ column in a <code class="literal">BEFORE</code> trigger are ignored and will be
+ overwritten.
+ </p><p>
+ If more than one trigger is defined for the same event on the same
+ relation, the triggers will be fired in alphabetical order by
+ trigger name. In the case of <code class="literal">BEFORE</code> and
+ <code class="literal">INSTEAD OF</code> triggers, the possibly-modified row returned by
+ each trigger becomes the input to the next trigger. If any
+ <code class="literal">BEFORE</code> or <code class="literal">INSTEAD OF</code> trigger returns
+ <code class="symbol">NULL</code>, the operation is abandoned for that row and subsequent
+ triggers are not fired (for that row).
+ </p><p>
+ A trigger definition can also specify a Boolean <code class="literal">WHEN</code>
+ condition, which will be tested to see whether the trigger should
+ be fired. In row-level triggers the <code class="literal">WHEN</code> condition can
+ examine the old and/or new values of columns of the row. (Statement-level
+ triggers can also have <code class="literal">WHEN</code> conditions, although the feature
+ is not so useful for them.) In a <code class="literal">BEFORE</code> trigger, the
+ <code class="literal">WHEN</code>
+ condition is evaluated just before the function is or would be executed,
+ so using <code class="literal">WHEN</code> is not materially different from testing the
+ same condition at the beginning of the trigger function. However, in
+ an <code class="literal">AFTER</code> trigger, the <code class="literal">WHEN</code> condition is evaluated
+ just after the row update occurs, and it determines whether an event is
+ queued to fire the trigger at the end of statement. So when an
+ <code class="literal">AFTER</code> trigger's
+ <code class="literal">WHEN</code> condition does not return true, it is not necessary
+ to queue an event nor to re-fetch the row at end of statement. This
+ can result in significant speedups in statements that modify many
+ rows, if the trigger only needs to be fired for a few of the rows.
+ <code class="literal">INSTEAD OF</code> triggers do not support
+ <code class="literal">WHEN</code> conditions.
+ </p><p>
+ Typically, row-level <code class="literal">BEFORE</code> triggers are used for checking or
+ modifying the data that will be inserted or updated. For example,
+ a <code class="literal">BEFORE</code> trigger might be used to insert the current time into a
+ <code class="type">timestamp</code> column, or to check that two elements of the row are
+ consistent. Row-level <code class="literal">AFTER</code> triggers are most sensibly
+ used to propagate the updates to other tables, or make consistency
+ checks against other tables. The reason for this division of labor is
+ that an <code class="literal">AFTER</code> trigger can be certain it is seeing the final
+ value of the row, while a <code class="literal">BEFORE</code> trigger cannot; there might
+ be other <code class="literal">BEFORE</code> triggers firing after it. If you have no
+ specific reason to make a trigger <code class="literal">BEFORE</code> or
+ <code class="literal">AFTER</code>, the <code class="literal">BEFORE</code> case is more efficient, since
+ the information about
+ the operation doesn't have to be saved until end of statement.
+ </p><p>
+ If a trigger function executes SQL commands then these
+ commands might fire triggers again. This is known as cascading
+ triggers. There is no direct limitation on the number of cascade
+ levels. It is possible for cascades to cause a recursive invocation
+ of the same trigger; for example, an <code class="command">INSERT</code>
+ trigger might execute a command that inserts an additional row
+ into the same table, causing the <code class="command">INSERT</code> trigger
+ to be fired again. It is the trigger programmer's responsibility
+ to avoid infinite recursion in such scenarios.
+ </p><p>
+ <a id="id-1.8.4.5.23.1" class="indexterm"></a>
+ When a trigger is being defined, arguments can be specified for
+ it. The purpose of including arguments in the
+ trigger definition is to allow different triggers with similar
+ requirements to call the same function. As an example, there
+ could be a generalized trigger function that takes as its
+ arguments two column names and puts the current user in one and
+ the current time stamp in the other. Properly written, this
+ trigger function would be independent of the specific table it is
+ triggering on. So the same function could be used for
+ <code class="command">INSERT</code> events on any table with suitable
+ columns, to automatically track creation of records in a
+ transaction table for example. It could also be used to track
+ last-update events if defined as an <code class="command">UPDATE</code>
+ trigger.
+ </p><p>
+ Each programming language that supports triggers has its own method
+ for making the trigger input data available to the trigger function.
+ This input data includes the type of trigger event (e.g.,
+ <code class="command">INSERT</code> or <code class="command">UPDATE</code>) as well as any
+ arguments that were listed in <code class="command">CREATE TRIGGER</code>.
+ For a row-level trigger, the input data also includes the
+ <code class="varname">NEW</code> row for <code class="command">INSERT</code> and
+ <code class="command">UPDATE</code> triggers, and/or the <code class="varname">OLD</code> row
+ for <code class="command">UPDATE</code> and <code class="command">DELETE</code> triggers.
+ </p><p>
+ By default, statement-level triggers do not have any way to examine the
+ individual row(s) modified by the statement. But an <code class="literal">AFTER
+ STATEMENT</code> trigger can request that <em class="firstterm">transition tables</em>
+ be created to make the sets of affected rows available to the trigger.
+ <code class="literal">AFTER ROW</code> triggers can also request transition tables, so
+ that they can see the total changes in the table as well as the change in
+ the individual row they are currently being fired for. The method for
+ examining the transition tables again depends on the programming language
+ that is being used, but the typical approach is to make the transition
+ tables act like read-only temporary tables that can be accessed by SQL
+ commands issued within the trigger function.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="triggers.html" title="Chapter 39. Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 39. Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 39.2. Visibility of Data Changes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/trigger-example.html b/doc/src/sgml/html/trigger-example.html
new file mode 100644
index 0000000..187baef
--- /dev/null
+++ b/doc/src/sgml/html/trigger-example.html
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>39.4. A Complete Trigger Example</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C" /><link rel="next" href="event-triggers.html" title="Chapter 40. Event Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">39.4. A Complete Trigger Example</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><th width="60%" align="center">Chapter 39. Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="event-triggers.html" title="Chapter 40. Event Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="TRIGGER-EXAMPLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">39.4. A Complete Trigger Example</h2></div></div></div><p>
+ Here is a very simple example of a trigger function written in C.
+ (Examples of triggers written in procedural languages can be found
+ in the documentation of the procedural languages.)
+ </p><p>
+ The function <code class="function">trigf</code> reports the number of rows in the
+ table <code class="structname">ttest</code> and skips the actual operation if the
+ command attempts to insert a null value into the column
+ <code class="structfield">x</code>. (So the trigger acts as a not-null constraint but
+ doesn't abort the transaction.)
+ </p><p>
+ First, the table definition:
+</p><pre class="programlisting">
+CREATE TABLE ttest (
+ x integer
+);
+</pre><p>
+ </p><p>
+ This is the source code of the trigger function:
+</p><pre class="programlisting">
+#include "postgres.h"
+#include "fmgr.h"
+#include "executor/spi.h" /* this is what you need to work with SPI */
+#include "commands/trigger.h" /* ... triggers ... */
+#include "utils/rel.h" /* ... and relations */
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(trigf);
+
+Datum
+trigf(PG_FUNCTION_ARGS)
+{
+ TriggerData *trigdata = (TriggerData *) fcinfo-&gt;context;
+ TupleDesc tupdesc;
+ HeapTuple rettuple;
+ char *when;
+ bool checknull = false;
+ bool isnull;
+ int ret, i;
+
+ /* make sure it's called as a trigger at all */
+ if (!CALLED_AS_TRIGGER(fcinfo))
+ elog(ERROR, "trigf: not called by trigger manager");
+
+ /* tuple to return to executor */
+ if (TRIGGER_FIRED_BY_UPDATE(trigdata-&gt;tg_event))
+ rettuple = trigdata-&gt;tg_newtuple;
+ else
+ rettuple = trigdata-&gt;tg_trigtuple;
+
+ /* check for null values */
+ if (!TRIGGER_FIRED_BY_DELETE(trigdata-&gt;tg_event)
+ &amp;&amp; TRIGGER_FIRED_BEFORE(trigdata-&gt;tg_event))
+ checknull = true;
+
+ if (TRIGGER_FIRED_BEFORE(trigdata-&gt;tg_event))
+ when = "before";
+ else
+ when = "after ";
+
+ tupdesc = trigdata-&gt;tg_relation-&gt;rd_att;
+
+ /* connect to SPI manager */
+ if ((ret = SPI_connect()) &lt; 0)
+ elog(ERROR, "trigf (fired %s): SPI_connect returned %d", when, ret);
+
+ /* get number of rows in table */
+ ret = SPI_exec("SELECT count(*) FROM ttest", 0);
+
+ if (ret &lt; 0)
+ elog(ERROR, "trigf (fired %s): SPI_exec returned %d", when, ret);
+
+ /* count(*) returns int8, so be careful to convert */
+ i = DatumGetInt64(SPI_getbinval(SPI_tuptable-&gt;vals[0],
+ SPI_tuptable-&gt;tupdesc,
+ 1,
+ &amp;isnull));
+
+ elog (INFO, "trigf (fired %s): there are %d rows in ttest", when, i);
+
+ SPI_finish();
+
+ if (checknull)
+ {
+ SPI_getbinval(rettuple, tupdesc, 1, &amp;isnull);
+ if (isnull)
+ rettuple = NULL;
+ }
+
+ return PointerGetDatum(rettuple);
+}
+
+</pre><p>
+ </p><p>
+ After you have compiled the source code (see <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a>), declare the function and the triggers:
+</p><pre class="programlisting">
+CREATE FUNCTION trigf() RETURNS trigger
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C;
+
+CREATE TRIGGER tbefore BEFORE INSERT OR UPDATE OR DELETE ON ttest
+ FOR EACH ROW EXECUTE FUNCTION trigf();
+
+CREATE TRIGGER tafter AFTER INSERT OR UPDATE OR DELETE ON ttest
+ FOR EACH ROW EXECUTE FUNCTION trigf();
+</pre><p>
+ </p><p>
+ Now you can test the operation of the trigger:
+</p><pre class="screen">
+=&gt; INSERT INTO ttest VALUES (NULL);
+INFO: trigf (fired before): there are 0 rows in ttest
+INSERT 0 0
+
+-- Insertion skipped and AFTER trigger is not fired
+
+=&gt; SELECT * FROM ttest;
+ x
+---
+(0 rows)
+
+=&gt; INSERT INTO ttest VALUES (1);
+INFO: trigf (fired before): there are 0 rows in ttest
+INFO: trigf (fired after ): there are 1 rows in ttest
+ ^^^^^^^^
+ remember what we said about visibility.
+INSERT 167793 1
+vac=&gt; SELECT * FROM ttest;
+ x
+---
+ 1
+(1 row)
+
+=&gt; INSERT INTO ttest SELECT x * 2 FROM ttest;
+INFO: trigf (fired before): there are 1 rows in ttest
+INFO: trigf (fired after ): there are 2 rows in ttest
+ ^^^^^^
+ remember what we said about visibility.
+INSERT 167794 1
+=&gt; SELECT * FROM ttest;
+ x
+---
+ 1
+ 2
+(2 rows)
+
+=&gt; UPDATE ttest SET x = NULL WHERE x = 2;
+INFO: trigf (fired before): there are 2 rows in ttest
+UPDATE 0
+=&gt; UPDATE ttest SET x = 4 WHERE x = 2;
+INFO: trigf (fired before): there are 2 rows in ttest
+INFO: trigf (fired after ): there are 2 rows in ttest
+UPDATE 1
+vac=&gt; SELECT * FROM ttest;
+ x
+---
+ 1
+ 4
+(2 rows)
+
+=&gt; DELETE FROM ttest;
+INFO: trigf (fired before): there are 2 rows in ttest
+INFO: trigf (fired before): there are 1 rows in ttest
+INFO: trigf (fired after ): there are 0 rows in ttest
+INFO: trigf (fired after ): there are 0 rows in ttest
+ ^^^^^^
+ remember what we said about visibility.
+DELETE 2
+=&gt; SELECT * FROM ttest;
+ x
+---
+(0 rows)
+</pre><p>
+
+ </p><p>
+ There are more complex examples in
+ <code class="filename">src/test/regress/regress.c</code> and
+ in <a class="xref" href="contrib-spi.html" title="F.41. spi">spi</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="trigger-interface.html" title="39.3. Writing Trigger Functions in C">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="event-triggers.html" title="Chapter 40. Event Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">39.3. Writing Trigger Functions in C </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 40. Event Triggers</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/trigger-interface.html b/doc/src/sgml/html/trigger-interface.html
new file mode 100644
index 0000000..ed345ef
--- /dev/null
+++ b/doc/src/sgml/html/trigger-interface.html
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>39.3. Writing Trigger Functions in C</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes" /><link rel="next" href="trigger-example.html" title="39.4. A Complete Trigger Example" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">39.3. Writing Trigger Functions in C</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><th width="60%" align="center">Chapter 39. Triggers</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="trigger-example.html" title="39.4. A Complete Trigger Example">Next</a></td></tr></table><hr /></div><div class="sect1" id="TRIGGER-INTERFACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">39.3. Writing Trigger Functions in C</h2></div></div></div><a id="id-1.8.4.7.2" class="indexterm"></a><a id="id-1.8.4.7.3" class="indexterm"></a><p>
+ This section describes the low-level details of the interface to a
+ trigger function. This information is only needed when writing
+ trigger functions in C. If you are using a higher-level language then
+ these details are handled for you. In most cases you should consider
+ using a procedural language before writing your triggers in C. The
+ documentation of each procedural language explains how to write a
+ trigger in that language.
+ </p><p>
+ Trigger functions must use the <span class="quote">“<span class="quote">version 1</span>”</span> function manager
+ interface.
+ </p><p>
+ When a function is called by the trigger manager, it is not passed
+ any normal arguments, but it is passed a <span class="quote">“<span class="quote">context</span>”</span>
+ pointer pointing to a <code class="structname">TriggerData</code> structure. C
+ functions can check whether they were called from the trigger
+ manager or not by executing the macro:
+</p><pre class="programlisting">
+CALLED_AS_TRIGGER(fcinfo)
+</pre><p>
+ which expands to:
+</p><pre class="programlisting">
+((fcinfo)-&gt;context != NULL &amp;&amp; IsA((fcinfo)-&gt;context, TriggerData))
+</pre><p>
+ If this returns true, then it is safe to cast
+ <code class="literal">fcinfo-&gt;context</code> to type <code class="literal">TriggerData
+ *</code> and make use of the pointed-to
+ <code class="structname">TriggerData</code> structure. The function must
+ <span class="emphasis"><em>not</em></span> alter the <code class="structname">TriggerData</code>
+ structure or any of the data it points to.
+ </p><p>
+ <code class="structname">struct TriggerData</code> is defined in
+ <code class="filename">commands/trigger.h</code>:
+
+</p><pre class="programlisting">
+typedef struct TriggerData
+{
+ NodeTag type;
+ TriggerEvent tg_event;
+ Relation tg_relation;
+ HeapTuple tg_trigtuple;
+ HeapTuple tg_newtuple;
+ Trigger *tg_trigger;
+ TupleTableSlot *tg_trigslot;
+ TupleTableSlot *tg_newslot;
+ Tuplestorestate *tg_oldtable;
+ Tuplestorestate *tg_newtable;
+ const Bitmapset *tg_updatedcols;
+} TriggerData;
+</pre><p>
+
+ where the members are defined as follows:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="structfield">type</code></span></dt><dd><p>
+ Always <code class="literal">T_TriggerData</code>.
+ </p></dd><dt><span class="term"><code class="structfield">tg_event</code></span></dt><dd><p>
+ Describes the event for which the function is called. You can use the
+ following macros to examine <code class="literal">tg_event</code>:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TRIGGER_FIRED_BEFORE(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger fired before the operation.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_AFTER(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger fired after the operation.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_INSTEAD(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger fired instead of the operation.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_FOR_ROW(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger fired for a row-level event.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_FOR_STATEMENT(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger fired for a statement-level event.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_INSERT(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger was fired by an <code class="command">INSERT</code> command.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_UPDATE(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger was fired by an <code class="command">UPDATE</code> command.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_DELETE(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger was fired by a <code class="command">DELETE</code> command.
+ </p></dd><dt><span class="term"><code class="literal">TRIGGER_FIRED_BY_TRUNCATE(tg_event)</code></span></dt><dd><p>
+ Returns true if the trigger was fired by a <code class="command">TRUNCATE</code> command.
+ </p></dd></dl></div><p>
+ </p></dd><dt><span class="term"><code class="structfield">tg_relation</code></span></dt><dd><p>
+ A pointer to a structure describing the relation that the trigger fired for.
+ Look at <code class="filename">utils/rel.h</code> for details about
+ this structure. The most interesting things are
+ <code class="literal">tg_relation-&gt;rd_att</code> (descriptor of the relation
+ tuples) and <code class="literal">tg_relation-&gt;rd_rel-&gt;relname</code>
+ (relation name; the type is not <code class="type">char*</code> but
+ <code class="type">NameData</code>; use
+ <code class="literal">SPI_getrelname(tg_relation)</code> to get a <code class="type">char*</code> if you
+ need a copy of the name).
+ </p></dd><dt><span class="term"><code class="structfield">tg_trigtuple</code></span></dt><dd><p>
+ A pointer to the row for which the trigger was fired. This is
+ the row being inserted, updated, or deleted. If this trigger
+ was fired for an <code class="command">INSERT</code> or
+ <code class="command">DELETE</code> then this is what you should return
+ from the function if you don't want to replace the row with
+ a different one (in the case of <code class="command">INSERT</code>) or
+ skip the operation. For triggers on foreign tables, values of system
+ columns herein are unspecified.
+ </p></dd><dt><span class="term"><code class="structfield">tg_newtuple</code></span></dt><dd><p>
+ A pointer to the new version of the row, if the trigger was
+ fired for an <code class="command">UPDATE</code>, and <code class="symbol">NULL</code> if
+ it is for an <code class="command">INSERT</code> or a
+ <code class="command">DELETE</code>. This is what you have to return
+ from the function if the event is an <code class="command">UPDATE</code>
+ and you don't want to replace this row by a different one or
+ skip the operation. For triggers on foreign tables, values of system
+ columns herein are unspecified.
+ </p></dd><dt><span class="term"><code class="structfield">tg_trigger</code></span></dt><dd><p>
+ A pointer to a structure of type <code class="structname">Trigger</code>,
+ defined in <code class="filename">utils/reltrigger.h</code>:
+
+</p><pre class="programlisting">
+typedef struct Trigger
+{
+ Oid tgoid;
+ char *tgname;
+ Oid tgfoid;
+ int16 tgtype;
+ char tgenabled;
+ bool tgisinternal;
+ bool tgisclone;
+ Oid tgconstrrelid;
+ Oid tgconstrindid;
+ Oid tgconstraint;
+ bool tgdeferrable;
+ bool tginitdeferred;
+ int16 tgnargs;
+ int16 tgnattr;
+ int16 *tgattr;
+ char **tgargs;
+ char *tgqual;
+ char *tgoldtable;
+ char *tgnewtable;
+} Trigger;
+</pre><p>
+
+ where <code class="structfield">tgname</code> is the trigger's name,
+ <code class="structfield">tgnargs</code> is the number of arguments in
+ <code class="structfield">tgargs</code>, and <code class="structfield">tgargs</code> is an array of
+ pointers to the arguments specified in the <code class="command">CREATE
+ TRIGGER</code> statement. The other members are for internal use
+ only.
+ </p></dd><dt><span class="term"><code class="structfield">tg_trigslot</code></span></dt><dd><p>
+ The slot containing <code class="structfield">tg_trigtuple</code>,
+ or a <code class="symbol">NULL</code> pointer if there is no such tuple.
+ </p></dd><dt><span class="term"><code class="structfield">tg_newslot</code></span></dt><dd><p>
+ The slot containing <code class="structfield">tg_newtuple</code>,
+ or a <code class="symbol">NULL</code> pointer if there is no such tuple.
+ </p></dd><dt><span class="term"><code class="structfield">tg_oldtable</code></span></dt><dd><p>
+ A pointer to a structure of type <code class="structname">Tuplestorestate</code>
+ containing zero or more rows in the format specified by
+ <code class="structfield">tg_relation</code>, or a <code class="symbol">NULL</code> pointer
+ if there is no <code class="literal">OLD TABLE</code> transition relation.
+ </p></dd><dt><span class="term"><code class="structfield">tg_newtable</code></span></dt><dd><p>
+ A pointer to a structure of type <code class="structname">Tuplestorestate</code>
+ containing zero or more rows in the format specified by
+ <code class="structfield">tg_relation</code>, or a <code class="symbol">NULL</code> pointer
+ if there is no <code class="literal">NEW TABLE</code> transition relation.
+ </p></dd><dt><span class="term"><code class="structfield">tg_updatedcols</code></span></dt><dd><p>
+ For <code class="literal">UPDATE</code> triggers, a bitmap set indicating the
+ columns that were updated by the triggering command. Generic trigger
+ functions can use this to optimize actions by not having to deal with
+ columns that were not changed.
+ </p><p>
+ As an example, to determine whether a column with attribute number
+ <code class="varname">attnum</code> (1-based) is a member of this bitmap set,
+ call <code class="literal">bms_is_member(attnum -
+ FirstLowInvalidHeapAttributeNumber,
+ trigdata-&gt;tg_updatedcols))</code>.
+ </p><p>
+ For triggers other than <code class="literal">UPDATE</code> triggers, this will
+ be <code class="symbol">NULL</code>.
+ </p></dd></dl></div><p>
+ </p><p>
+ To allow queries issued through SPI to reference transition tables, see
+ <a class="xref" href="spi-spi-register-trigger-data.html" title="SPI_register_trigger_data"><span class="refentrytitle">SPI_register_trigger_data</span></a>.
+ </p><p>
+ A trigger function must return either a
+ <code class="structname">HeapTuple</code> pointer or a <code class="symbol">NULL</code> pointer
+ (<span class="emphasis"><em>not</em></span> an SQL null value, that is, do not set <em class="parameter"><code>isNull</code></em> true).
+ Be careful to return either
+ <code class="structfield">tg_trigtuple</code> or <code class="structfield">tg_newtuple</code>,
+ as appropriate, if you don't want to modify the row being operated on.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="trigger-datachanges.html" title="39.2. Visibility of Data Changes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="triggers.html" title="Chapter 39. Triggers">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="trigger-example.html" title="39.4. A Complete Trigger Example">Next</a></td></tr><tr><td width="40%" align="left" valign="top">39.2. Visibility of Data Changes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 39.4. A Complete Trigger Example</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/triggers.html b/doc/src/sgml/html/triggers.html
new file mode 100644
index 0000000..95aacdf
--- /dev/null
+++ b/doc/src/sgml/html/triggers.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 39. Triggers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure" /><link rel="next" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 39. Triggers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior">Next</a></td></tr></table><hr /></div><div class="chapter" id="TRIGGERS"><div class="titlepage"><div><div><h2 class="title">Chapter 39. Triggers</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="trigger-definition.html">39.1. Overview of Trigger Behavior</a></span></dt><dt><span class="sect1"><a href="trigger-datachanges.html">39.2. Visibility of Data Changes</a></span></dt><dt><span class="sect1"><a href="trigger-interface.html">39.3. Writing Trigger Functions in C</a></span></dt><dt><span class="sect1"><a href="trigger-example.html">39.4. A Complete Trigger Example</a></span></dt></dl></div><a id="id-1.8.4.2" class="indexterm"></a><p>
+ This chapter provides general information about writing trigger functions.
+ Trigger functions can be written in most of the available procedural
+ languages, including
+ <span class="application">PL/pgSQL</span> (<a class="xref" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Chapter 43</a>),
+ <span class="application">PL/Tcl</span> (<a class="xref" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Chapter 44</a>),
+ <span class="application">PL/Perl</span> (<a class="xref" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Chapter 45</a>), and
+ <span class="application">PL/Python</span> (<a class="xref" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Chapter 46</a>).
+ After reading this chapter, you should consult the chapter for
+ your favorite procedural language to find out the language-specific
+ details of writing a trigger in it.
+ </p><p>
+ It is also possible to write a trigger function in C, although
+ most people find it easier to use one of the procedural languages.
+ It is not currently possible to write a trigger function in the
+ plain SQL function language.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-pgxs.html" title="38.18. Extension Building Infrastructure">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="trigger-definition.html" title="39.1. Overview of Trigger Behavior">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.18. Extension Building Infrastructure </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 39.1. Overview of Trigger Behavior</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tsm-system-rows.html b/doc/src/sgml/html/tsm-system-rows.html
new file mode 100644
index 0000000..8231086
--- /dev/null
+++ b/doc/src/sgml/html/tsm-system-rows.html
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.46. tsm_system_rows</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="test-decoding.html" title="F.45. test_decoding" /><link rel="next" href="tsm-system-time.html" title="F.47. tsm_system_time" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.46. tsm_system_rows</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="test-decoding.html" title="F.45. test_decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tsm-system-time.html" title="F.47. tsm_system_time">Next</a></td></tr></table><hr /></div><div class="sect1" id="TSM-SYSTEM-ROWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.46. tsm_system_rows</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="tsm-system-rows.html#id-1.11.7.55.8">F.46.1. Examples</a></span></dt></dl></div><a id="id-1.11.7.55.2" class="indexterm"></a><p>
+ The <code class="filename">tsm_system_rows</code> module provides the table sampling method
+ <code class="literal">SYSTEM_ROWS</code>, which can be used in
+ the <code class="literal">TABLESAMPLE</code> clause of a <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a>
+ command.
+ </p><p>
+ This table sampling method accepts a single integer argument that is the
+ maximum number of rows to read. The resulting sample will always contain
+ exactly that many rows, unless the table does not contain enough rows, in
+ which case the whole table is selected.
+ </p><p>
+ Like the built-in <code class="literal">SYSTEM</code> sampling
+ method, <code class="literal">SYSTEM_ROWS</code> performs block-level sampling, so
+ that the sample is not completely random but may be subject to clustering
+ effects, especially if only a small number of rows are requested.
+ </p><p>
+ <code class="literal">SYSTEM_ROWS</code> does not support
+ the <code class="literal">REPEATABLE</code> clause.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.55.8"><div class="titlepage"><div><div><h3 class="title">F.46.1. Examples</h3></div></div></div><p>
+ Here is an example of selecting a sample of a table with
+ <code class="literal">SYSTEM_ROWS</code>. First install the extension:
+ </p><pre class="programlisting">
+CREATE EXTENSION tsm_system_rows;
+</pre><p>
+ Then you can use it in a <code class="command">SELECT</code> command, for instance:
+
+</p><pre class="programlisting">
+SELECT * FROM my_table TABLESAMPLE SYSTEM_ROWS(100);
+</pre><p>
+ </p><p>
+ This command will return a sample of 100 rows from the
+ table <code class="structname">my_table</code> (unless the table does not have 100
+ visible rows, in which case all its rows are returned).
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test-decoding.html" title="F.45. test_decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tsm-system-time.html" title="F.47. tsm_system_time">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.45. test_decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.47. tsm_system_time</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tsm-system-time.html b/doc/src/sgml/html/tsm-system-time.html
new file mode 100644
index 0000000..b3dadf7
--- /dev/null
+++ b/doc/src/sgml/html/tsm-system-time.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.47. tsm_system_time</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tsm-system-rows.html" title="F.46. tsm_system_rows" /><link rel="next" href="unaccent.html" title="F.48. unaccent" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.47. tsm_system_time</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tsm-system-rows.html" title="F.46. tsm_system_rows">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="unaccent.html" title="F.48. unaccent">Next</a></td></tr></table><hr /></div><div class="sect1" id="TSM-SYSTEM-TIME"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.47. tsm_system_time</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="tsm-system-time.html#id-1.11.7.56.8">F.47.1. Examples</a></span></dt></dl></div><a id="id-1.11.7.56.2" class="indexterm"></a><p>
+ The <code class="filename">tsm_system_time</code> module provides the table sampling method
+ <code class="literal">SYSTEM_TIME</code>, which can be used in
+ the <code class="literal">TABLESAMPLE</code> clause of a <a class="link" href="sql-select.html" title="SELECT"><code class="command">SELECT</code></a>
+ command.
+ </p><p>
+ This table sampling method accepts a single floating-point argument that
+ is the maximum number of milliseconds to spend reading the table. This
+ gives you direct control over how long the query takes, at the price that
+ the size of the sample becomes hard to predict. The resulting sample will
+ contain as many rows as could be read in the specified time, unless the
+ whole table has been read first.
+ </p><p>
+ Like the built-in <code class="literal">SYSTEM</code> sampling
+ method, <code class="literal">SYSTEM_TIME</code> performs block-level sampling, so
+ that the sample is not completely random but may be subject to clustering
+ effects, especially if only a small number of rows are selected.
+ </p><p>
+ <code class="literal">SYSTEM_TIME</code> does not support
+ the <code class="literal">REPEATABLE</code> clause.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.56.8"><div class="titlepage"><div><div><h3 class="title">F.47.1. Examples</h3></div></div></div><p>
+ Here is an example of selecting a sample of a table with
+ <code class="literal">SYSTEM_TIME</code>. First install the extension:
+ </p><pre class="programlisting">
+CREATE EXTENSION tsm_system_time;
+</pre><p>
+ Then you can use it in a <code class="command">SELECT</code> command, for instance:
+
+</p><pre class="programlisting">
+SELECT * FROM my_table TABLESAMPLE SYSTEM_TIME(1000);
+</pre><p>
+ </p><p>
+ This command will return as large a sample of <code class="structname">my_table</code> as
+ it can read in 1 second (1000 milliseconds). Of course, if the whole
+ table can be read in under 1 second, all its rows will be returned.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tsm-system-rows.html" title="F.46. tsm_system_rows">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="unaccent.html" title="F.48. unaccent">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.46. tsm_system_rows </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.48. unaccent</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-accessdb.html b/doc/src/sgml/html/tutorial-accessdb.html
new file mode 100644
index 0000000..1566068
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-accessdb.html
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>1.4. Accessing a Database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-createdb.html" title="1.3. Creating a Database" /><link rel="next" href="tutorial-sql.html" title="Chapter 2. The SQL Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">1.4. Accessing a Database</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-createdb.html" title="1.3. Creating a Database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><th width="60%" align="center">Chapter 1. Getting Started</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-ACCESSDB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.4. Accessing a Database</h2></div></div></div><a id="id-1.4.3.5.2" class="indexterm"></a><p>
+ Once you have created a database, you can access it by:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p>
+ Running the <span class="productname">PostgreSQL</span> interactive
+ terminal program, called <span class="application"><em class="firstterm">psql</em></span>, which allows you
+ to interactively enter, edit, and execute
+ <acronym class="acronym">SQL</acronym> commands.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Using an existing graphical frontend tool like
+ <span class="application">pgAdmin</span> or an office suite with
+ <acronym class="acronym">ODBC</acronym> or <acronym class="acronym">JDBC</acronym> support to create and manipulate a
+ database. These possibilities are not covered in this
+ tutorial.
+ </p></li><li class="listitem" style="list-style-type: disc"><p>
+ Writing a custom application, using one of the several
+ available language bindings. These possibilities are discussed
+ further in <a class="xref" href="client-interfaces.html" title="Part IV. Client Interfaces">Part IV</a>.
+ </p></li></ul></div><p>
+
+ You probably want to start up <code class="command">psql</code> to try
+ the examples in this tutorial. It can be activated for the
+ <code class="literal">mydb</code> database by typing the command:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>psql mydb</code></strong>
+</pre><p>
+ If you do not supply the database name then it will default to your
+ user account name. You already discovered this scheme in the
+ previous section using <code class="command">createdb</code>.
+ </p><p>
+ In <code class="command">psql</code>, you will be greeted with the following
+ message:
+</p><pre class="screen">
+psql (15.5)
+Type "help" for help.
+
+mydb=&gt;
+</pre><p>
+ <a id="id-1.4.3.5.4.3" class="indexterm"></a>
+ The last line could also be:
+</p><pre class="screen">
+mydb=#
+</pre><p>
+ That would mean you are a database superuser, which is most likely
+ the case if you installed the <span class="productname">PostgreSQL</span> instance
+ yourself. Being a superuser means that you are not subject to
+ access controls. For the purposes of this tutorial that is not
+ important.
+ </p><p>
+ If you encounter problems starting <code class="command">psql</code>
+ then go back to the previous section. The diagnostics of
+ <code class="command">createdb</code> and <code class="command">psql</code> are
+ similar, and if the former worked the latter should work as well.
+ </p><p>
+ The last line printed out by <code class="command">psql</code> is the
+ prompt, and it indicates that <code class="command">psql</code> is listening
+ to you and that you can type <acronym class="acronym">SQL</acronym> queries into a
+ work space maintained by <code class="command">psql</code>. Try out these
+ commands:
+ <a id="id-1.4.3.5.6.5" class="indexterm"></a>
+</p><pre class="screen">
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>SELECT version();</code></strong>
+ version
+-------------------------------------------------------------------​-----------------------
+ PostgreSQL 15.5 on x86_64-pc-linux-gnu, compiled by gcc (Debian 4.9.2-10) 4.9.2, 64-bit
+(1 row)
+
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>SELECT current_date;</code></strong>
+ date
+------------
+ 2016-01-07
+(1 row)
+
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>SELECT 2 + 2;</code></strong>
+ ?column?
+----------
+ 4
+(1 row)
+</pre><p>
+ </p><p>
+ The <code class="command">psql</code> program has a number of internal
+ commands that are not SQL commands. They begin with the backslash
+ character, <span class="quote">“<span class="quote"><code class="literal">\</code></span>”</span>.
+ For example,
+ you can get help on the syntax of various
+ <span class="productname">PostgreSQL</span> <acronym class="acronym">SQL</acronym>
+ commands by typing:
+</p><pre class="screen">
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>\h</code></strong>
+</pre><p>
+ </p><p>
+ To get out of <code class="command">psql</code>, type:
+</p><pre class="screen">
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>\q</code></strong>
+</pre><p>
+ and <code class="command">psql</code> will quit and return you to your
+ command shell. (For more internal commands, type
+ <code class="literal">\?</code> at the <code class="command">psql</code> prompt.) The
+ full capabilities of <code class="command">psql</code> are documented in
+ <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>. In this tutorial we will not use these
+ features explicitly, but you can use them yourself when it is helpful.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-createdb.html" title="1.3. Creating a Database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.3. Creating a Database </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. The <acronym class="acronym">SQL</acronym> Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-advanced-intro.html b/doc/src/sgml/html/tutorial-advanced-intro.html
new file mode 100644
index 0000000..2713a20
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-advanced-intro.html
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-advanced.html" title="Chapter 3. Advanced Features" /><link rel="next" href="tutorial-views.html" title="3.2. Views" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-views.html" title="3.2. Views">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-ADVANCED-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.1. Introduction</h2></div></div></div><p>
+ In the previous chapter we have covered the basics of using
+ <acronym class="acronym">SQL</acronym> to store and access your data in
+ <span class="productname">PostgreSQL</span>. We will now discuss some
+ more advanced features of <acronym class="acronym">SQL</acronym> that simplify
+ management and prevent loss or corruption of your data. Finally,
+ we will look at some <span class="productname">PostgreSQL</span>
+ extensions.
+ </p><p>
+ This chapter will on occasion refer to examples found in <a class="xref" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Chapter 2</a> 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
+ <code class="filename">advanced.sql</code> in the tutorial directory. This
+ file also contains some sample data to load, which is not
+ repeated here. (Refer to <a class="xref" href="tutorial-sql-intro.html" title="2.1. Introduction">Section 2.1</a> for
+ how to use the file.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-views.html" title="3.2. Views">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Advanced Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.2. Views</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-advanced.html b/doc/src/sgml/html/tutorial-advanced.html
new file mode 100644
index 0000000..3cc6e3b
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-advanced.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Advanced Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-delete.html" title="2.9. Deletions" /><link rel="next" href="tutorial-advanced-intro.html" title="3.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 3. Advanced Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-delete.html" title="2.9. Deletions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><th width="60%" align="center">Part I. Tutorial</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-advanced-intro.html" title="3.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="TUTORIAL-ADVANCED"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Advanced Features</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-advanced-intro.html">3.1. Introduction</a></span></dt><dt><span class="sect1"><a href="tutorial-views.html">3.2. Views</a></span></dt><dt><span class="sect1"><a href="tutorial-fk.html">3.3. Foreign Keys</a></span></dt><dt><span class="sect1"><a href="tutorial-transactions.html">3.4. Transactions</a></span></dt><dt><span class="sect1"><a href="tutorial-window.html">3.5. Window Functions</a></span></dt><dt><span class="sect1"><a href="tutorial-inheritance.html">3.6. Inheritance</a></span></dt><dt><span class="sect1"><a href="tutorial-conclusion.html">3.7. Conclusion</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-delete.html" title="2.9. Deletions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced-intro.html" title="3.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.9. Deletions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-agg.html b/doc/src/sgml/html/tutorial-agg.html
new file mode 100644
index 0000000..b89fd78
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-agg.html
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.7. Aggregate Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-join.html" title="2.6. Joins Between Tables" /><link rel="next" href="tutorial-update.html" title="2.8. Updates" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.7. Aggregate Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-join.html" title="2.6. Joins Between Tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-update.html" title="2.8. Updates">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-AGG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.7. Aggregate Functions</h2></div></div></div><a id="id-1.4.4.8.2" class="indexterm"></a><p>
+ Like most other relational database products,
+ <span class="productname">PostgreSQL</span> supports
+ <em class="firstterm">aggregate functions</em>.
+ An aggregate function computes a single result from multiple input rows.
+ For example, there are aggregates to compute the
+ <code class="function">count</code>, <code class="function">sum</code>,
+ <code class="function">avg</code> (average), <code class="function">max</code> (maximum) and
+ <code class="function">min</code> (minimum) over a set of rows.
+ </p><p>
+ As an example, we can find the highest low-temperature reading anywhere
+ with:
+
+</p><pre class="programlisting">
+SELECT max(temp_lo) FROM weather;
+</pre><p>
+
+</p><pre class="screen">
+ max
+-----
+ 46
+(1 row)
+</pre><p>
+ </p><p>
+ <a id="id-1.4.4.8.5.1" class="indexterm"></a>
+
+ If we wanted to know what city (or cities) that reading occurred in,
+ we might try:
+
+</p><pre class="programlisting">
+SELECT city FROM weather WHERE temp_lo = max(temp_lo); <em class="lineannotation"><span class="lineannotation">WRONG</span></em>
+</pre><p>
+
+ but this will not work since the aggregate
+ <code class="function">max</code> cannot be used in the
+ <code class="literal">WHERE</code> clause. (This restriction exists because
+ the <code class="literal">WHERE</code> clause determines which rows will be
+ included in the aggregate calculation; so obviously it has to be evaluated
+ before aggregate functions are computed.)
+ However, as is often the case
+ the query can be restated to accomplish the desired result, here
+ by using a <em class="firstterm">subquery</em>:
+
+</p><pre class="programlisting">
+SELECT city FROM weather
+ WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
+</pre><p>
+
+</p><pre class="screen">
+ city
+---------------
+ San Francisco
+(1 row)
+</pre><p>
+
+ This is OK because the subquery is an independent computation
+ that computes its own aggregate separately from what is happening
+ in the outer query.
+ </p><p>
+ <a id="id-1.4.4.8.6.1" class="indexterm"></a>
+ <a id="id-1.4.4.8.6.2" class="indexterm"></a>
+
+ Aggregates are also very useful in combination with <code class="literal">GROUP
+ BY</code> clauses. For example, we can get the number of readings
+ and the maximum low temperature observed in each city with:
+
+</p><pre class="programlisting">
+SELECT city, count(*), max(temp_lo)
+ FROM weather
+ GROUP BY city;
+</pre><p>
+
+</p><pre class="screen">
+ city | count | max
+---------------+-------+-----
+ Hayward | 1 | 37
+ San Francisco | 2 | 46
+(2 rows)
+</pre><p>
+
+ which gives us one output row per city. Each aggregate result is
+ computed over the table rows matching that city.
+ We can filter these grouped
+ rows using <code class="literal">HAVING</code>:
+
+</p><pre class="programlisting">
+SELECT city, count(*), max(temp_lo)
+ FROM weather
+ GROUP BY city
+ HAVING max(temp_lo) &lt; 40;
+</pre><p>
+
+</p><pre class="screen">
+ city | count | max
+---------+-------+-----
+ Hayward | 1 | 37
+(1 row)
+</pre><p>
+
+ which gives us the same results for only the cities that have all
+ <code class="structfield">temp_lo</code> values below 40. Finally, if we only care about
+ cities whose
+ names begin with <span class="quote">“<span class="quote"><code class="literal">S</code></span>”</span>, we might do:
+
+</p><pre class="programlisting">
+SELECT city, count(*), max(temp_lo)
+ FROM weather
+ WHERE city LIKE 'S%' -- <span id="co.tutorial-agg-like"></span>(1)
+ GROUP BY city;
+</pre><p>
+
+</p><pre class="screen">
+ city | count | max
+---------------+-------+-----
+ San Francisco | 2 | 46
+(1 row)
+</pre><p>
+ </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co.tutorial-agg-like">(1)</a> </p></td><td valign="top" align="left"><p>
+ The <code class="literal">LIKE</code> operator does pattern matching and
+ is explained in <a class="xref" href="functions-matching.html" title="9.7. Pattern Matching">Section 9.7</a>.
+ </p></td></tr></table></div><p>
+ </p><p>
+ It is important to understand the interaction between aggregates and
+ <acronym class="acronym">SQL</acronym>'s <code class="literal">WHERE</code> and <code class="literal">HAVING</code> clauses.
+ The fundamental difference between <code class="literal">WHERE</code> and
+ <code class="literal">HAVING</code> is this: <code class="literal">WHERE</code> selects
+ input rows before groups and aggregates are computed (thus, it controls
+ which rows go into the aggregate computation), whereas
+ <code class="literal">HAVING</code> selects group rows after groups and
+ aggregates are computed. Thus, the
+ <code class="literal">WHERE</code> clause must not contain aggregate functions;
+ it makes no sense to try to use an aggregate to determine which rows
+ will be inputs to the aggregates. On the other hand, the
+ <code class="literal">HAVING</code> clause always contains aggregate functions.
+ (Strictly speaking, you are allowed to write a <code class="literal">HAVING</code>
+ clause that doesn't use aggregates, but it's seldom useful. The same
+ condition could be used more efficiently at the <code class="literal">WHERE</code>
+ stage.)
+ </p><p>
+ In the previous example, we can apply the city name restriction in
+ <code class="literal">WHERE</code>, since it needs no aggregate. This is
+ more efficient than adding the restriction to <code class="literal">HAVING</code>,
+ because we avoid doing the grouping and aggregate calculations
+ for all rows that fail the <code class="literal">WHERE</code> check.
+ </p><p>
+ Another way to select the rows that go into an aggregate
+ computation is to use <code class="literal">FILTER</code>, which is a
+ per-aggregate option:
+
+</p><pre class="programlisting">
+SELECT city, count(*) FILTER (WHERE temp_lo &lt; 45), max(temp_lo)
+ FROM weather
+ GROUP BY city;
+</pre><p>
+
+</p><pre class="screen">
+ city | count | max
+---------------+-------+-----
+ Hayward | 1 | 37
+ San Francisco | 1 | 46
+(2 rows)
+</pre><p>
+
+ <code class="literal">FILTER</code> is much like <code class="literal">WHERE</code>,
+ except that it removes rows only from the input of the particular
+ aggregate function that it is attached to.
+ Here, the <code class="literal">count</code> aggregate counts only
+ rows with <code class="literal">temp_lo</code> below 45; but the
+ <code class="literal">max</code> aggregate is still applied to all rows,
+ so it still finds the reading of 46.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-join.html" title="2.6. Joins Between Tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-update.html" title="2.8. Updates">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.6. Joins Between Tables </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.8. Updates</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-arch.html b/doc/src/sgml/html/tutorial-arch.html
new file mode 100644
index 0000000..f123008
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-arch.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>1.2. Architectural Fundamentals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-install.html" title="1.1. Installation" /><link rel="next" href="tutorial-createdb.html" title="1.3. Creating a Database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">1.2. Architectural Fundamentals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-install.html" title="1.1. Installation">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><th width="60%" align="center">Chapter 1. Getting Started</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-createdb.html" title="1.3. Creating a Database">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-ARCH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.2. Architectural Fundamentals</h2></div></div></div><p>
+ Before we proceed, you should understand the basic
+ <span class="productname">PostgreSQL</span> system architecture.
+ Understanding how the parts of
+ <span class="productname">PostgreSQL</span> interact will make this
+ chapter somewhat clearer.
+ </p><p>
+ In database jargon, <span class="productname">PostgreSQL</span> uses a
+ client/server model. A <span class="productname">PostgreSQL</span>
+ session consists of the following cooperating processes
+ (programs):
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A server process, which manages the database files, accepts
+ connections to the database from client applications, and
+ performs database actions on behalf of the clients. The
+ database server program is called
+ <code class="filename">postgres</code>.
+ <a id="id-1.4.3.3.3.3.1.1.2" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ The user's client (frontend) application that wants to perform
+ database operations. Client applications can be very diverse
+ in nature: a client could be a text-oriented tool, a graphical
+ application, a web server that accesses the database to
+ display web pages, or a specialized database maintenance tool.
+ Some client applications are supplied with the
+ <span class="productname">PostgreSQL</span> distribution; most are
+ developed by users.
+ </p></li></ul></div><p>
+ </p><p>
+ As is typical of client/server applications, the client and the
+ server can be on different hosts. In that case they communicate
+ over a TCP/IP network connection. You should keep this in mind,
+ because the files that can be accessed on a client machine might
+ not be accessible (or might only be accessible using a different
+ file name) on the database server machine.
+ </p><p>
+ The <span class="productname">PostgreSQL</span> server can handle
+ multiple concurrent connections from clients. To achieve this it
+ starts (<span class="quote">“<span class="quote">forks</span>”</span>) a new process for each connection.
+ From that point on, the client and the new server process
+ communicate without intervention by the original
+ <code class="filename">postgres</code> process. Thus, the
+ supervisor server process is always running, waiting for
+ client connections, whereas client and associated server processes
+ come and go. (All of this is of course invisible to the user. We
+ only mention it here for completeness.)
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-install.html" title="1.1. Installation">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-createdb.html" title="1.3. Creating a Database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.1. Installation </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 1.3. Creating a Database</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-concepts.html b/doc/src/sgml/html/tutorial-concepts.html
new file mode 100644
index 0000000..02b8d65
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-concepts.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.2. Concepts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-sql-intro.html" title="2.1. Introduction" /><link rel="next" href="tutorial-table.html" title="2.3. Creating a New Table" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.2. Concepts</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-sql-intro.html" title="2.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-table.html" title="2.3. Creating a New Table">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-CONCEPTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.2. Concepts</h2></div></div></div><p>
+ <a id="id-1.4.4.3.2.1" class="indexterm"></a>
+ <a id="id-1.4.4.3.2.2" class="indexterm"></a>
+ <a id="id-1.4.4.3.2.3" class="indexterm"></a>
+ <a id="id-1.4.4.3.2.4" class="indexterm"></a>
+ <a id="id-1.4.4.3.2.5" class="indexterm"></a>
+
+ <span class="productname">PostgreSQL</span> is a <em class="firstterm">relational
+ database management system</em> (<acronym class="acronym">RDBMS</acronym>).
+ That means it is a system for managing data stored in
+ <em class="firstterm">relations</em>. Relation is essentially a
+ mathematical term for <em class="firstterm">table</em>. The notion of
+ storing data in tables is so commonplace today that it might
+ seem inherently obvious, but there are a number of other ways of
+ organizing databases. Files and directories on Unix-like
+ operating systems form an example of a hierarchical database. A
+ more modern development is the object-oriented database.
+ </p><p>
+ <a id="id-1.4.4.3.3.1" class="indexterm"></a>
+ <a id="id-1.4.4.3.3.2" class="indexterm"></a>
+
+ Each table is a named collection of <em class="firstterm">rows</em>.
+ Each row of a given table has the same set of named
+ <em class="firstterm">columns</em>,
+ and each column is of a specific data type. Whereas columns have
+ a fixed order in each row, it is important to remember that SQL
+ does not guarantee the order of the rows within the table in any
+ way (although they can be explicitly sorted for display).
+ </p><p>
+ <a id="id-1.4.4.3.4.1" class="indexterm"></a>
+ <a id="id-1.4.4.3.4.2" class="indexterm"></a>
+
+ Tables are grouped into databases, and a collection of databases
+ managed by a single <span class="productname">PostgreSQL</span> server
+ instance constitutes a database <em class="firstterm">cluster</em>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-sql-intro.html" title="2.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-table.html" title="2.3. Creating a New Table">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.3. Creating a New Table</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-conclusion.html b/doc/src/sgml/html/tutorial-conclusion.html
new file mode 100644
index 0000000..8a83182
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-conclusion.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.7. Conclusion</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-inheritance.html" title="3.6. Inheritance" /><link rel="next" href="sql.html" title="Part II. The SQL Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.7. Conclusion</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-inheritance.html" title="3.6. Inheritance">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql.html" title="Part II. The SQL Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-CONCLUSION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.7. Conclusion</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> has many features not
+ touched upon in this tutorial introduction, which has been
+ oriented toward newer users of <acronym class="acronym">SQL</acronym>. These
+ features are discussed in more detail in the remainder of this
+ book.
+ </p><p>
+ If you feel you need more introductory material, please visit the PostgreSQL
+ <a class="ulink" href="https://www.postgresql.org" target="_top">web site</a>
+ for links to more resources.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-inheritance.html" title="3.6. Inheritance">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql.html" title="Part II. The SQL Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.6. Inheritance </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part II. The SQL Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-createdb.html b/doc/src/sgml/html/tutorial-createdb.html
new file mode 100644
index 0000000..e785b4a
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-createdb.html
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>1.3. Creating a Database</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-arch.html" title="1.2. Architectural Fundamentals" /><link rel="next" href="tutorial-accessdb.html" title="1.4. Accessing a Database" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">1.3. Creating a Database</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-arch.html" title="1.2. Architectural Fundamentals">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><th width="60%" align="center">Chapter 1. Getting Started</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-accessdb.html" title="1.4. Accessing a Database">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-CREATEDB"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.3. Creating a Database</h2></div></div></div><a id="id-1.4.3.4.2" class="indexterm"></a><a id="id-1.4.3.4.3" class="indexterm"></a><p>
+ The first test to see whether you can access the database server
+ is to try to create a database. A running
+ <span class="productname">PostgreSQL</span> server can manage many
+ databases. Typically, a separate database is used for each
+ project or for each user.
+ </p><p>
+ Possibly, your site administrator has already created a database
+ for your use. In that case you can omit this step and skip ahead
+ to the next section.
+ </p><p>
+ To create a new database, in this example named
+ <code class="literal">mydb</code>, you use the following command:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>createdb mydb</code></strong>
+</pre><p>
+ If this produces no response then this step was successful and you can skip over the
+ remainder of this section.
+ </p><p>
+ If you see a message similar to:
+</p><pre class="screen">
+createdb: command not found
+</pre><p>
+ then <span class="productname">PostgreSQL</span> was not installed properly. Either it was not
+ installed at all or your shell's search path was not set to include it.
+ Try calling the command with an absolute path instead:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>/usr/local/pgsql/bin/createdb mydb</code></strong>
+</pre><p>
+ The path at your site might be different. Contact your site
+ administrator or check the installation instructions to
+ correct the situation.
+ </p><p>
+ Another response could be this:
+</p><pre class="screen">
+createdb: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
+ Is the server running locally and accepting connections on that socket?
+</pre><p>
+ This means that the server was not started, or it is not listening
+ where <code class="command">createdb</code> expects to contact it. Again, check the
+ installation instructions or consult the administrator.
+ </p><p>
+ Another response could be this:
+</p><pre class="screen">
+createdb: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL: role "joe" does not exist
+</pre><p>
+ where your own login name is mentioned. This will happen if the
+ administrator has not created a <span class="productname">PostgreSQL</span> user account
+ for you. (<span class="productname">PostgreSQL</span> user accounts are distinct from
+ operating system user accounts.) If you are the administrator, see
+ <a class="xref" href="user-manag.html" title="Chapter 22. Database Roles">Chapter 22</a> for help creating accounts. You will need to
+ become the operating system user under which <span class="productname">PostgreSQL</span>
+ was installed (usually <code class="literal">postgres</code>) to create the first user
+ account. It could also be that you were assigned a
+ <span class="productname">PostgreSQL</span> user name that is different from your
+ operating system user name; in that case you need to use the <code class="option">-U</code>
+ switch or set the <code class="envar">PGUSER</code> environment variable to specify your
+ <span class="productname">PostgreSQL</span> user name.
+ </p><p>
+ If you have a user account but it does not have the privileges required to
+ create a database, you will see the following:
+</p><pre class="screen">
+createdb: error: database creation failed: ERROR: permission denied to create database
+</pre><p>
+ Not every user has authorization to create new databases. If
+ <span class="productname">PostgreSQL</span> refuses to create databases
+ for you then the site administrator needs to grant you permission
+ to create databases. Consult your site administrator if this
+ occurs. If you installed <span class="productname">PostgreSQL</span>
+ yourself then you should log in for the purposes of this tutorial
+ under the user account that you started the server as.
+
+ <a href="#ftn.id-1.4.3.4.10.4" class="footnote"><sup class="footnote" id="id-1.4.3.4.10.4">[1]</sup></a>
+ </p><p>
+ You can also create databases with other names.
+ <span class="productname">PostgreSQL</span> allows you to create any
+ number of databases at a given site. Database names must have an
+ alphabetic first character and are limited to 63 bytes in
+ length. A convenient choice is to create a database with the same
+ name as your current user name. Many tools assume that database
+ name as the default, so it can save you some typing. To create
+ that database, simply type:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>createdb</code></strong>
+</pre><p>
+ </p><p>
+ If you do not want to use your database anymore you can remove it.
+ For example, if you are the owner (creator) of the database
+ <code class="literal">mydb</code>, you can destroy it using the following
+ command:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>dropdb mydb</code></strong>
+</pre><p>
+ (For this command, the database name does not default to the user
+ account name. You always need to specify it.) This action
+ physically removes all files associated with the database and
+ cannot be undone, so this should only be done with a great deal of
+ forethought.
+ </p><p>
+ More about <code class="command">createdb</code> and <code class="command">dropdb</code> can
+ be found in <a class="xref" href="app-createdb.html" title="createdb"><span class="refentrytitle"><span class="application">createdb</span></span></a> and <a class="xref" href="app-dropdb.html" title="dropdb"><span class="refentrytitle"><span class="application">dropdb</span></span></a>
+ respectively.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.4.3.4.10.4" class="footnote"><p><a href="#id-1.4.3.4.10.4" class="para"><sup class="para">[1] </sup></a>
+ As an explanation for why this works:
+ <span class="productname">PostgreSQL</span> user names are separate
+ from operating system user accounts. When you connect to a
+ database, you can choose what
+ <span class="productname">PostgreSQL</span> user name to connect as;
+ if you don't, it will default to the same name as your current
+ operating system account. As it happens, there will always be a
+ <span class="productname">PostgreSQL</span> user account that has the
+ same name as the operating system user that started the server,
+ and it also happens that that user always has permission to
+ create databases. Instead of logging in as that user you can
+ also specify the <code class="option">-U</code> option everywhere to select
+ a <span class="productname">PostgreSQL</span> user name to connect as.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-arch.html" title="1.2. Architectural Fundamentals">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-accessdb.html" title="1.4. Accessing a Database">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.2. Architectural Fundamentals </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 1.4. Accessing a Database</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-delete.html b/doc/src/sgml/html/tutorial-delete.html
new file mode 100644
index 0000000..5fab888
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-delete.html
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.9. Deletions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-update.html" title="2.8. Updates" /><link rel="next" href="tutorial-advanced.html" title="Chapter 3. Advanced Features" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.9. Deletions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-update.html" title="2.8. Updates">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-DELETE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.9. Deletions</h2></div></div></div><a id="id-1.4.4.10.2" class="indexterm"></a><p>
+ Rows can be removed from a table using the <code class="command">DELETE</code>
+ command.
+ Suppose you are no longer interested in the weather of Hayward.
+ Then you can do the following to delete those rows from the table:
+</p><pre class="programlisting">
+DELETE FROM weather WHERE city = 'Hayward';
+</pre><p>
+
+ All weather records belonging to Hayward are removed.
+
+</p><pre class="programlisting">
+SELECT * FROM weather;
+</pre><p>
+
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date
+---------------+---------+---------+------+------------
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27
+ San Francisco | 41 | 55 | 0 | 1994-11-29
+(2 rows)
+</pre><p>
+ </p><p>
+ One should be wary of statements of the form
+</p><pre class="synopsis">
+DELETE FROM <em class="replaceable"><code>tablename</code></em>;
+</pre><p>
+
+ Without a qualification, <code class="command">DELETE</code> will
+ remove <span class="emphasis"><em>all</em></span> rows from the given table, leaving it
+ empty. The system will not request confirmation before
+ doing this!
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-update.html" title="2.8. Updates">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.8. Updates </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Advanced Features</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-fk.html b/doc/src/sgml/html/tutorial-fk.html
new file mode 100644
index 0000000..2b52a23
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-fk.html
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.3. Foreign Keys</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-views.html" title="3.2. Views" /><link rel="next" href="tutorial-transactions.html" title="3.4. Transactions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.3. Foreign Keys</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-views.html" title="3.2. Views">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-transactions.html" title="3.4. Transactions">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-FK"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.3. Foreign Keys</h2></div></div></div><a id="id-1.4.5.4.2" class="indexterm"></a><a id="id-1.4.5.4.3" class="indexterm"></a><p>
+ Recall the <code class="classname">weather</code> and
+ <code class="classname">cities</code> tables from <a class="xref" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Chapter 2</a>. Consider the following problem: You
+ want to make sure that no one can insert rows in the
+ <code class="classname">weather</code> table that do not have a matching
+ entry in the <code class="classname">cities</code> table. This is called
+ maintaining the <em class="firstterm">referential integrity</em> of
+ your data. In simplistic database systems this would be
+ implemented (if at all) by first looking at the
+ <code class="classname">cities</code> table to check if a matching record
+ exists, and then inserting or rejecting the new
+ <code class="classname">weather</code> records. This approach has a
+ number of problems and is very inconvenient, so
+ <span class="productname">PostgreSQL</span> can do this for you.
+ </p><p>
+ The new declaration of the tables would look like this:
+
+</p><pre class="programlisting">
+CREATE TABLE cities (
+ name varchar(80) primary key,
+ location point
+);
+
+CREATE TABLE weather (
+ city varchar(80) references cities(name),
+ temp_lo int,
+ temp_hi int,
+ prcp real,
+ date date
+);
+</pre><p>
+
+ Now try inserting an invalid record:
+
+</p><pre class="programlisting">
+INSERT INTO weather VALUES ('Berkeley', 45, 53, 0.0, '1994-11-28');
+</pre><p>
+
+</p><pre class="screen">
+ERROR: insert or update on table "weather" violates foreign key constraint "weather_city_fkey"
+DETAIL: Key (city)=(Berkeley) is not present in table "cities".
+</pre><p>
+ </p><p>
+ 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 <a class="xref" href="ddl.html" title="Chapter 5. Data Definition">Chapter 5</a>
+ 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.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-views.html" title="3.2. Views">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-transactions.html" title="3.4. Transactions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.2. Views </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.4. Transactions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-inheritance.html b/doc/src/sgml/html/tutorial-inheritance.html
new file mode 100644
index 0000000..1481ae3
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-inheritance.html
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.6. Inheritance</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-window.html" title="3.5. Window Functions" /><link rel="next" href="tutorial-conclusion.html" title="3.7. Conclusion" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.6. Inheritance</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-window.html" title="3.5. Window Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-conclusion.html" title="3.7. Conclusion">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-INHERITANCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.6. Inheritance</h2></div></div></div><a id="id-1.4.5.7.2" class="indexterm"></a><p>
+ Inheritance is a concept from object-oriented databases. It opens
+ up interesting new possibilities of database design.
+ </p><p>
+ Let's create two tables: A table <code class="classname">cities</code>
+ and a table <code class="classname">capitals</code>. Naturally, capitals
+ are also cities, so you want some way to show the capitals
+ implicitly when you list all cities. If you're really clever you
+ might invent some scheme like this:
+
+</p><pre class="programlisting">
+CREATE TABLE capitals (
+ name text,
+ population real,
+ elevation int, -- (in ft)
+ state char(2)
+);
+
+CREATE TABLE non_capitals (
+ name text,
+ population real,
+ elevation int -- (in ft)
+);
+
+CREATE VIEW cities AS
+ SELECT name, population, elevation FROM capitals
+ UNION
+ SELECT name, population, elevation FROM non_capitals;
+</pre><p>
+
+ This works OK as far as querying goes, but it gets ugly when you
+ need to update several rows, for one thing.
+ </p><p>
+ A better solution is this:
+
+</p><pre class="programlisting">
+CREATE TABLE cities (
+ name text,
+ population real,
+ elevation int -- (in ft)
+);
+
+CREATE TABLE capitals (
+ state char(2) UNIQUE NOT NULL
+) INHERITS (cities);
+</pre><p>
+ </p><p>
+ In this case, a row of <code class="classname">capitals</code>
+ <em class="firstterm">inherits</em> all columns (<code class="structfield">name</code>,
+ <code class="structfield">population</code>, and <code class="structfield">elevation</code>) from its
+ <em class="firstterm">parent</em>, <code class="classname">cities</code>. The
+ type of the column <code class="structfield">name</code> is
+ <code class="type">text</code>, a native <span class="productname">PostgreSQL</span>
+ type for variable length character strings. The
+ <code class="classname">capitals</code> table has
+ an additional column, <code class="structfield">state</code>, which shows its
+ state abbreviation. In
+ <span class="productname">PostgreSQL</span>, a table can inherit from
+ zero or more other tables.
+ </p><p>
+ For example, the following query finds the names of all cities,
+ including state capitals, that are located at an elevation
+ over 500 feet:
+
+</p><pre class="programlisting">
+SELECT name, elevation
+ FROM cities
+ WHERE elevation &gt; 500;
+</pre><p>
+
+ which returns:
+
+</p><pre class="screen">
+ name | elevation
+-----------+-----------
+ Las Vegas | 2174
+ Mariposa | 1953
+ Madison | 845
+(3 rows)
+</pre><p>
+ </p><p>
+ On the other hand, the following query finds
+ all the cities that are not state capitals and
+ are situated at an elevation over 500 feet:
+
+</p><pre class="programlisting">
+SELECT name, elevation
+ FROM ONLY cities
+ WHERE elevation &gt; 500;
+</pre><p>
+
+</p><pre class="screen">
+ name | elevation
+-----------+-----------
+ Las Vegas | 2174
+ Mariposa | 1953
+(2 rows)
+</pre><p>
+ </p><p>
+ Here the <code class="literal">ONLY</code> before <code class="literal">cities</code>
+ indicates that the query should be run over only the
+ <code class="classname">cities</code> table, and not tables below
+ <code class="classname">cities</code> in the inheritance hierarchy. Many
+ of the commands that we have already discussed —
+ <code class="command">SELECT</code>, <code class="command">UPDATE</code>, and
+ <code class="command">DELETE</code> — support this <code class="literal">ONLY</code>
+ notation.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Although inheritance is frequently useful, it has not been integrated
+ with unique constraints or foreign keys, which limits its usefulness.
+ See <a class="xref" href="ddl-inherit.html" title="5.10. Inheritance">Section 5.10</a> for more detail.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-window.html" title="3.5. Window Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-conclusion.html" title="3.7. Conclusion">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.5. Window Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.7. Conclusion</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-install.html b/doc/src/sgml/html/tutorial-install.html
new file mode 100644
index 0000000..b37492b
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-install.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>1.1. Installation</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-start.html" title="Chapter 1. Getting Started" /><link rel="next" href="tutorial-arch.html" title="1.2. Architectural Fundamentals" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">1.1. Installation</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-start.html" title="Chapter 1. Getting Started">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><th width="60%" align="center">Chapter 1. Getting Started</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-arch.html" title="1.2. Architectural Fundamentals">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-INSTALL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.1. Installation</h2></div></div></div><p>
+ Before you can use <span class="productname">PostgreSQL</span> you need
+ to install it, of course. It is possible that
+ <span class="productname">PostgreSQL</span> is already installed at your
+ site, either because it was included in your operating system
+ distribution or because the system administrator already installed
+ it. If that is the case, you should obtain information from the
+ operating system documentation or your system administrator about
+ how to access <span class="productname">PostgreSQL</span>.
+ </p><p>
+ If you are not sure whether <span class="productname">PostgreSQL</span>
+ is already available or whether you can use it for your
+ experimentation then you can install it yourself. Doing so is not
+ hard and it can be a good exercise.
+ <span class="productname">PostgreSQL</span> can be installed by any
+ unprivileged user; no superuser (<span class="systemitem">root</span>)
+ access is required.
+ </p><p>
+ If you are installing <span class="productname">PostgreSQL</span>
+ yourself, then refer to <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>
+ for instructions on installation, and return to
+ this guide when the installation is complete. Be sure to follow
+ closely the section about setting up the appropriate environment
+ variables.
+ </p><p>
+ If your site administrator has not set things up in the default
+ way, you might have some more work to do. For example, if the
+ database server machine is a remote machine, you will need to set
+ the <code class="envar">PGHOST</code> environment variable to the name of the
+ database server machine. The environment variable
+ <code class="envar">PGPORT</code> might also have to be set. The bottom line is
+ this: if you try to start an application program and it complains
+ that it cannot connect to the database, you should consult your
+ site administrator or, if that is you, the documentation to make
+ sure that your environment is properly set up. If you did not
+ understand the preceding paragraph then read the next section.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-start.html" title="Chapter 1. Getting Started">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-start.html" title="Chapter 1. Getting Started">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-arch.html" title="1.2. Architectural Fundamentals">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Getting Started </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 1.2. Architectural Fundamentals</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-join.html b/doc/src/sgml/html/tutorial-join.html
new file mode 100644
index 0000000..60b04bf
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-join.html
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.6. Joins Between Tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-select.html" title="2.5. Querying a Table" /><link rel="next" href="tutorial-agg.html" title="2.7. Aggregate Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.6. Joins Between Tables</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-select.html" title="2.5. Querying a Table">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-agg.html" title="2.7. Aggregate Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-JOIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.6. Joins Between Tables</h2></div></div></div><a id="id-1.4.4.7.2" class="indexterm"></a><p>
+ Thus far, our queries have only accessed one table at a time.
+ Queries can access multiple tables at once, or access the same
+ table in such a way that multiple rows of the table are being
+ processed at the same time. Queries that access multiple tables
+ (or multiple instances of the same table) at one time are called
+ <em class="firstterm">join</em> queries. They combine rows from one table
+ with rows from a second table, with an expression specifying which rows
+ are to be paired. For example, to return all the weather records together
+ with the location of the associated city, the database needs to compare
+ the <code class="structfield">city</code>
+ column of each row of the <code class="structname">weather</code> table with the
+ <code class="structfield">name</code> column of all rows in the <code class="structname">cities</code>
+ table, and select the pairs of rows where these values match.<a href="#ftn.id-1.4.4.7.3.6" class="footnote"><sup class="footnote" id="id-1.4.4.7.3.6">[4]</sup></a>
+ This would be accomplished by the following query:
+
+</p><pre class="programlisting">
+SELECT * FROM weather JOIN cities ON city = name;
+</pre><p>
+
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date | name | location
+---------------+---------+---------+------+------------+---------------+-----------
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27 | San Francisco | (-194,53)
+ San Francisco | 43 | 57 | 0 | 1994-11-29 | San Francisco | (-194,53)
+(2 rows)
+</pre><p>
+
+ </p><p>
+ Observe two things about the result set:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ There is no result row for the city of Hayward. This is
+ because there is no matching entry in the
+ <code class="structname">cities</code> table for Hayward, so the join
+ ignores the unmatched rows in the <code class="structname">weather</code> table. We will see
+ shortly how this can be fixed.
+ </p></li><li class="listitem"><p>
+ There are two columns containing the city name. This is
+ correct because the lists of columns from the
+ <code class="structname">weather</code> and
+ <code class="structname">cities</code> tables are concatenated. In
+ practice this is undesirable, though, so you will probably want
+ to list the output columns explicitly rather than using
+ <code class="literal">*</code>:
+</p><pre class="programlisting">
+SELECT city, temp_lo, temp_hi, prcp, date, location
+ FROM weather JOIN cities ON city = name;
+</pre><p>
+ </p></li></ul></div><p>
+ </p><p>
+ Since the columns all had different names, the parser
+ automatically found which table they belong to. If there
+ were duplicate column names in the two tables you'd need to
+ <em class="firstterm">qualify</em> the column names to show which one you
+ meant, as in:
+
+</p><pre class="programlisting">
+SELECT weather.city, weather.temp_lo, weather.temp_hi,
+ weather.prcp, weather.date, cities.location
+ FROM weather JOIN cities ON weather.city = cities.name;
+</pre><p>
+
+ It is widely considered good style to qualify all column names
+ in a join query, so that the query won't fail if a duplicate
+ column name is later added to one of the tables.
+ </p><p>
+ Join queries of the kind seen thus far can also be written in this
+ form:
+
+</p><pre class="programlisting">
+SELECT *
+ FROM weather, cities
+ WHERE city = name;
+</pre><p>
+
+ This syntax pre-dates the <code class="literal">JOIN</code>/<code class="literal">ON</code>
+ syntax, which was introduced in SQL-92. The tables are simply listed in
+ the <code class="literal">FROM</code> clause, and the comparison expression is added
+ to the <code class="literal">WHERE</code> clause. The results from this older
+ implicit syntax and the newer explicit
+ <code class="literal">JOIN</code>/<code class="literal">ON</code> syntax are identical. But
+ for a reader of the query, the explicit syntax makes its meaning easier to
+ understand: The join condition is introduced by its own key word whereas
+ previously the condition was mixed into the <code class="literal">WHERE</code>
+ clause together with other conditions.
+ </p><a id="id-1.4.4.7.7" class="indexterm"></a><p>
+ Now we will figure out how we can get the Hayward records back in.
+ What we want the query to do is to scan the
+ <code class="structname">weather</code> table and for each row to find the
+ matching <code class="structname">cities</code> row(s). If no matching row is
+ found we want some <span class="quote">“<span class="quote">empty values</span>”</span> to be substituted
+ for the <code class="structname">cities</code> table's columns. This kind
+ of query is called an <em class="firstterm">outer join</em>. (The
+ joins we have seen so far are <em class="firstterm">inner joins</em>.)
+ The command looks like this:
+
+</p><pre class="programlisting">
+SELECT *
+ FROM weather LEFT OUTER JOIN cities ON weather.city = cities.name;
+</pre><p>
+
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date | name | location
+---------------+---------+---------+------+------------+---------------+-----------
+ Hayward | 37 | 54 | | 1994-11-29 | |
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27 | San Francisco | (-194,53)
+ San Francisco | 43 | 57 | 0 | 1994-11-29 | San Francisco | (-194,53)
+(3 rows)
+</pre><p>
+
+ This query is called a <em class="firstterm">left outer
+ join</em> because the table mentioned on the left of the
+ join operator will have each of its rows in the output at least
+ once, whereas the table on the right will only have those rows
+ output that match some row of the left table. When outputting a
+ left-table row for which there is no right-table match, empty (null)
+ values are substituted for the right-table columns.
+ </p><p><strong>Exercise: </strong>
+ There are also right outer joins and full outer joins. Try to
+ find out what those do.
+ </p><a id="id-1.4.4.7.10" class="indexterm"></a><a id="id-1.4.4.7.11" class="indexterm"></a><p>
+ We can also join a table against itself. This is called a
+ <em class="firstterm">self join</em>. As an example, suppose we wish
+ to find all the weather records that are in the temperature range
+ of other weather records. So we need to compare the
+ <code class="structfield">temp_lo</code> and <code class="structfield">temp_hi</code> columns of
+ each <code class="structname">weather</code> row to the
+ <code class="structfield">temp_lo</code> and
+ <code class="structfield">temp_hi</code> columns of all other
+ <code class="structname">weather</code> rows. We can do this with the
+ following query:
+
+</p><pre class="programlisting">
+SELECT w1.city, w1.temp_lo AS low, w1.temp_hi AS high,
+ w2.city, w2.temp_lo AS low, w2.temp_hi AS high
+ FROM weather w1 JOIN weather w2
+ ON w1.temp_lo &lt; w2.temp_lo AND w1.temp_hi &gt; w2.temp_hi;
+</pre><p>
+
+</p><pre class="screen">
+ city | low | high | city | low | high
+---------------+-----+------+---------------+-----+------
+ San Francisco | 43 | 57 | San Francisco | 46 | 50
+ Hayward | 37 | 54 | San Francisco | 46 | 50
+(2 rows)
+</pre><p>
+
+ Here we have relabeled the weather table as <code class="literal">w1</code> and
+ <code class="literal">w2</code> to be able to distinguish the left and right side
+ of the join. You can also use these kinds of aliases in other
+ queries to save some typing, e.g.:
+</p><pre class="programlisting">
+SELECT *
+ FROM weather w JOIN cities c ON w.city = c.name;
+</pre><p>
+ You will encounter this style of abbreviating quite frequently.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.4.4.7.3.6" class="footnote"><p><a href="#id-1.4.4.7.3.6" class="para"><sup class="para">[4] </sup></a>
+ This is only a conceptual model. The join is usually performed
+ in a more efficient manner than actually comparing each possible
+ pair of rows, but this is invisible to the user.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-select.html" title="2.5. Querying a Table">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-agg.html" title="2.7. Aggregate Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.5. Querying a Table </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.7. Aggregate Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-populate.html b/doc/src/sgml/html/tutorial-populate.html
new file mode 100644
index 0000000..53b0123
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-populate.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.4. Populating a Table With Rows</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-table.html" title="2.3. Creating a New Table" /><link rel="next" href="tutorial-select.html" title="2.5. Querying a Table" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.4. Populating a Table With Rows</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-table.html" title="2.3. Creating a New Table">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-select.html" title="2.5. Querying a Table">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-POPULATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.4. Populating a Table With Rows</h2></div></div></div><a id="id-1.4.4.5.2" class="indexterm"></a><p>
+ The <code class="command">INSERT</code> statement is used to populate a table with
+ rows:
+
+</p><pre class="programlisting">
+INSERT INTO weather VALUES ('San Francisco', 46, 50, 0.25, '1994-11-27');
+</pre><p>
+
+ Note that all data types use rather obvious input formats.
+ Constants that are not simple numeric values usually must be
+ surrounded by single quotes (<code class="literal">'</code>), as in the example.
+ The
+ <code class="type">date</code> type is actually quite flexible in what it
+ accepts, but for this tutorial we will stick to the unambiguous
+ format shown here.
+ </p><p>
+ The <code class="type">point</code> type requires a coordinate pair as input,
+ as shown here:
+</p><pre class="programlisting">
+INSERT INTO cities VALUES ('San Francisco', '(-194.0, 53.0)');
+</pre><p>
+ </p><p>
+ The syntax used so far requires you to remember the order of the
+ columns. An alternative syntax allows you to list the columns
+ explicitly:
+</p><pre class="programlisting">
+INSERT INTO weather (city, temp_lo, temp_hi, prcp, date)
+ VALUES ('San Francisco', 43, 57, 0.0, '1994-11-29');
+</pre><p>
+ You can list the columns in a different order if you wish or
+ even omit some columns, e.g., if the precipitation is unknown:
+</p><pre class="programlisting">
+INSERT INTO weather (date, city, temp_hi, temp_lo)
+ VALUES ('1994-11-29', 'Hayward', 54, 37);
+</pre><p>
+ Many developers consider explicitly listing the columns better
+ style than relying on the order implicitly.
+ </p><p>
+ Please enter all the commands shown above so you have some data to
+ work with in the following sections.
+ </p><p>
+ <a id="id-1.4.4.5.7.1" class="indexterm"></a>
+
+ You could also have used <code class="command">COPY</code> to load large
+ amounts of data from flat-text files. This is usually faster
+ because the <code class="command">COPY</code> command is optimized for this
+ application while allowing less flexibility than
+ <code class="command">INSERT</code>. An example would be:
+
+</p><pre class="programlisting">
+COPY weather FROM '/home/user/weather.txt';
+</pre><p>
+
+ where the file name for the source file must be available on the
+ machine running the backend process, not the client, since the backend process
+ reads the file directly. You can read more about the
+ <code class="command">COPY</code> command in <a class="xref" href="sql-copy.html" title="COPY"><span class="refentrytitle">COPY</span></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-table.html" title="2.3. Creating a New Table">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-select.html" title="2.5. Querying a Table">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.3. Creating a New Table </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.5. Querying a Table</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-select.html b/doc/src/sgml/html/tutorial-select.html
new file mode 100644
index 0000000..16b3397
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-select.html
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.5. Querying a Table</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-populate.html" title="2.4. Populating a Table With Rows" /><link rel="next" href="tutorial-join.html" title="2.6. Joins Between Tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.5. Querying a Table</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-populate.html" title="2.4. Populating a Table With Rows">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-join.html" title="2.6. Joins Between Tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-SELECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.5. Querying a Table</h2></div></div></div><p>
+ <a id="id-1.4.4.6.2.1" class="indexterm"></a>
+ <a id="id-1.4.4.6.2.2" class="indexterm"></a>
+
+ To retrieve data from a table, the table is
+ <em class="firstterm">queried</em>. An <acronym class="acronym">SQL</acronym>
+ <code class="command">SELECT</code> statement is used to do this. The
+ statement is divided into a select list (the part that lists the
+ columns to be returned), a table list (the part that lists the
+ tables from which to retrieve the data), and an optional
+ qualification (the part that specifies any restrictions). For
+ example, to retrieve all the rows of table
+ <code class="structname">weather</code>, type:
+</p><pre class="programlisting">
+SELECT * FROM weather;
+</pre><p>
+ Here <code class="literal">*</code> is a shorthand for <span class="quote">“<span class="quote">all columns</span>”</span>.
+ <a href="#ftn.id-1.4.4.6.2.10" class="footnote"><sup class="footnote" id="id-1.4.4.6.2.10">[2]</sup></a>
+ So the same result would be had with:
+</p><pre class="programlisting">
+SELECT city, temp_lo, temp_hi, prcp, date FROM weather;
+</pre><p>
+
+ The output should be:
+
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date
+---------------+---------+---------+------+------------
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27
+ San Francisco | 43 | 57 | 0 | 1994-11-29
+ Hayward | 37 | 54 | | 1994-11-29
+(3 rows)
+</pre><p>
+ </p><p>
+ You can write expressions, not just simple column references, in the
+ select list. For example, you can do:
+</p><pre class="programlisting">
+SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
+</pre><p>
+ This should give:
+</p><pre class="screen">
+ city | temp_avg | date
+---------------+----------+------------
+ San Francisco | 48 | 1994-11-27
+ San Francisco | 50 | 1994-11-29
+ Hayward | 45 | 1994-11-29
+(3 rows)
+</pre><p>
+ Notice how the <code class="literal">AS</code> clause is used to relabel the
+ output column. (The <code class="literal">AS</code> clause is optional.)
+ </p><p>
+ A query can be <span class="quote">“<span class="quote">qualified</span>”</span> by adding a <code class="literal">WHERE</code>
+ clause that specifies which rows are wanted. The <code class="literal">WHERE</code>
+ clause contains a Boolean (truth value) expression, and only rows for
+ which the Boolean expression is true are returned. The usual
+ Boolean operators (<code class="literal">AND</code>,
+ <code class="literal">OR</code>, and <code class="literal">NOT</code>) are allowed in
+ the qualification. For example, the following
+ retrieves the weather of San Francisco on rainy days:
+
+</p><pre class="programlisting">
+SELECT * FROM weather
+ WHERE city = 'San Francisco' AND prcp &gt; 0.0;
+</pre><p>
+ Result:
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date
+---------------+---------+---------+------+------------
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27
+(1 row)
+</pre><p>
+ </p><p>
+ <a id="id-1.4.4.6.5.1" class="indexterm"></a>
+
+ You can request that the results of a query
+ be returned in sorted order:
+
+</p><pre class="programlisting">
+SELECT * FROM weather
+ ORDER BY city;
+</pre><p>
+
+</p><pre class="screen">
+ city | temp_lo | temp_hi | prcp | date
+---------------+---------+---------+------+------------
+ Hayward | 37 | 54 | | 1994-11-29
+ San Francisco | 43 | 57 | 0 | 1994-11-29
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27
+</pre><p>
+
+ In this example, the sort order isn't fully specified, and so you
+ might get the San Francisco rows in either order. But you'd always
+ get the results shown above if you do:
+
+</p><pre class="programlisting">
+SELECT * FROM weather
+ ORDER BY city, temp_lo;
+</pre><p>
+ </p><p>
+ <a id="id-1.4.4.6.6.1" class="indexterm"></a>
+ <a id="id-1.4.4.6.6.2" class="indexterm"></a>
+
+ You can request that duplicate rows be removed from the result of
+ a query:
+
+</p><pre class="programlisting">
+SELECT DISTINCT city
+ FROM weather;
+</pre><p>
+
+</p><pre class="screen">
+ city
+---------------
+ Hayward
+ San Francisco
+(2 rows)
+</pre><p>
+
+ Here again, the result row ordering might vary.
+ You can ensure consistent results by using <code class="literal">DISTINCT</code> and
+ <code class="literal">ORDER BY</code> together:
+ <a href="#ftn.id-1.4.4.6.6.7" class="footnote"><sup class="footnote" id="id-1.4.4.6.6.7">[3]</sup></a>
+
+</p><pre class="programlisting">
+SELECT DISTINCT city
+ FROM weather
+ ORDER BY city;
+</pre><p>
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.4.4.6.2.10" class="footnote"><p><a href="#id-1.4.4.6.2.10" class="para"><sup class="para">[2] </sup></a>
+ While <code class="literal">SELECT *</code> is useful for off-the-cuff
+ queries, it is widely considered bad style in production code,
+ since adding a column to the table would change the results.
+ </p></div><div id="ftn.id-1.4.4.6.6.7" class="footnote"><p><a href="#id-1.4.4.6.6.7" class="para"><sup class="para">[3] </sup></a>
+ In some database systems, including older versions of
+ <span class="productname">PostgreSQL</span>, the implementation of
+ <code class="literal">DISTINCT</code> automatically orders the rows and
+ so <code class="literal">ORDER BY</code> is unnecessary. But this is not
+ required by the SQL standard, and current
+ <span class="productname">PostgreSQL</span> does not guarantee that
+ <code class="literal">DISTINCT</code> causes the rows to be ordered.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-populate.html" title="2.4. Populating a Table With Rows">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-join.html" title="2.6. Joins Between Tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.4. Populating a Table With Rows </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.6. Joins Between Tables</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-sql-intro.html b/doc/src/sgml/html/tutorial-sql-intro.html
new file mode 100644
index 0000000..bf49142
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-sql-intro.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.1. Introduction</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-sql.html" title="Chapter 2. The SQL Language" /><link rel="next" href="tutorial-concepts.html" title="2.2. Concepts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.1. Introduction</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-concepts.html" title="2.2. Concepts">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-SQL-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.1. Introduction</h2></div></div></div><p>
+ This chapter provides an overview of how to use
+ <acronym class="acronym">SQL</acronym> to perform simple operations. This
+ tutorial is only intended to give you an introduction and is in no
+ way a complete tutorial on <acronym class="acronym">SQL</acronym>. Numerous books
+ have been written on <acronym class="acronym">SQL</acronym>, including <a class="xref" href="biblio.html#MELT93" title="Understanding the New SQL">[melt93]</a> and <a class="xref" href="biblio.html#DATE97" title="A Guide to the SQL Standard">[date97]</a>.
+ You should be aware that some <span class="productname">PostgreSQL</span>
+ language features are extensions to the standard.
+ </p><p>
+ In the examples that follow, we assume that you have created a
+ database named <code class="literal">mydb</code>, as described in the previous
+ chapter, and have been able to start <span class="application">psql</span>.
+ </p><p>
+ Examples in this manual can also be found in the
+ <span class="productname">PostgreSQL</span> source distribution
+ in the directory <code class="filename">src/tutorial/</code>. (Binary
+ distributions of <span class="productname">PostgreSQL</span> might not
+ provide those files.) To use those
+ files, first change to that directory and run <span class="application">make</span>:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>cd <em class="replaceable"><code>...</code></em>/src/tutorial</code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code>make</code></strong>
+</pre><p>
+
+ This creates the scripts and compiles the C files containing user-defined
+ functions and types. Then, to start the tutorial, do the following:
+
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>psql -s mydb</code></strong>
+<code class="computeroutput">
+...
+</code>
+<code class="prompt">mydb=&gt;</code> <strong class="userinput"><code>\i basics.sql</code></strong>
+</pre><p>
+
+ The <code class="literal">\i</code> command reads in commands from the
+ specified file. <code class="command">psql</code>'s <code class="literal">-s</code> option puts you in
+ single step mode which pauses before sending each statement to the
+ server. The commands used in this section are in the file
+ <code class="filename">basics.sql</code>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-concepts.html" title="2.2. Concepts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. The <acronym class="acronym">SQL</acronym> Language </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.2. Concepts</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-sql.html b/doc/src/sgml/html/tutorial-sql.html
new file mode 100644
index 0000000..a232e0d
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-sql.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. The SQL Language</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-accessdb.html" title="1.4. Accessing a Database" /><link rel="next" href="tutorial-sql-intro.html" title="2.1. Introduction" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-accessdb.html" title="1.4. Accessing a Database">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><th width="60%" align="center">Part I. Tutorial</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-sql-intro.html" title="2.1. Introduction">Next</a></td></tr></table><hr /></div><div class="chapter" id="TUTORIAL-SQL"><div class="titlepage"><div><div><h2 class="title">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-sql-intro.html">2.1. Introduction</a></span></dt><dt><span class="sect1"><a href="tutorial-concepts.html">2.2. Concepts</a></span></dt><dt><span class="sect1"><a href="tutorial-table.html">2.3. Creating a New Table</a></span></dt><dt><span class="sect1"><a href="tutorial-populate.html">2.4. Populating a Table With Rows</a></span></dt><dt><span class="sect1"><a href="tutorial-select.html">2.5. Querying a Table</a></span></dt><dt><span class="sect1"><a href="tutorial-join.html">2.6. Joins Between Tables</a></span></dt><dt><span class="sect1"><a href="tutorial-agg.html">2.7. Aggregate Functions</a></span></dt><dt><span class="sect1"><a href="tutorial-update.html">2.8. Updates</a></span></dt><dt><span class="sect1"><a href="tutorial-delete.html">2.9. Deletions</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-accessdb.html" title="1.4. Accessing a Database">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-sql-intro.html" title="2.1. Introduction">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.4. Accessing a Database </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.1. Introduction</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-start.html b/doc/src/sgml/html/tutorial-start.html
new file mode 100644
index 0000000..33b1d4f
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-start.html
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 1. Getting Started</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial.html" title="Part I. Tutorial" /><link rel="next" href="tutorial-install.html" title="1.1. Installation" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 1. Getting Started</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial.html" title="Part I. Tutorial">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><th width="60%" align="center">Part I. Tutorial</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-install.html" title="1.1. Installation">Next</a></td></tr></table><hr /></div><div class="chapter" id="TUTORIAL-START"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Getting Started</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-install.html">1.1. Installation</a></span></dt><dt><span class="sect1"><a href="tutorial-arch.html">1.2. Architectural Fundamentals</a></span></dt><dt><span class="sect1"><a href="tutorial-createdb.html">1.3. Creating a Database</a></span></dt><dt><span class="sect1"><a href="tutorial-accessdb.html">1.4. Accessing a Database</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial.html" title="Part I. Tutorial">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html" title="Part I. Tutorial">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-install.html" title="1.1. Installation">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part I. Tutorial </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 1.1. Installation</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-table.html b/doc/src/sgml/html/tutorial-table.html
new file mode 100644
index 0000000..6c80b6f
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-table.html
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.3. Creating a New Table</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-concepts.html" title="2.2. Concepts" /><link rel="next" href="tutorial-populate.html" title="2.4. Populating a Table With Rows" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.3. Creating a New Table</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-concepts.html" title="2.2. Concepts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-populate.html" title="2.4. Populating a Table With Rows">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-TABLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.3. Creating a New Table</h2></div></div></div><a id="id-1.4.4.4.2" class="indexterm"></a><p>
+ You can create a new table by specifying the table
+ name, along with all column names and their types:
+
+</p><pre class="programlisting">
+CREATE TABLE weather (
+ city varchar(80),
+ temp_lo int, -- low temperature
+ temp_hi int, -- high temperature
+ prcp real, -- precipitation
+ date date
+);
+</pre><p>
+
+ You can enter this into <code class="command">psql</code> with the line
+ breaks. <code class="command">psql</code> will recognize that the command
+ is not terminated until the semicolon.
+ </p><p>
+ White space (i.e., spaces, tabs, and newlines) can be used freely
+ in SQL commands. That means you can type the command aligned
+ differently than above, or even all on one line. Two dashes
+ (<span class="quote">“<span class="quote"><code class="literal">--</code></span>”</span>) introduce comments.
+ Whatever follows them is ignored up to the end of the line. SQL
+ is case insensitive about key words and identifiers, except
+ when identifiers are double-quoted to preserve the case (not done
+ above).
+ </p><p>
+ <code class="type">varchar(80)</code> specifies a data type that can store
+ arbitrary character strings up to 80 characters in length.
+ <code class="type">int</code> is the normal integer type. <code class="type">real</code> is
+ a type for storing single precision floating-point numbers.
+ <code class="type">date</code> should be self-explanatory. (Yes, the column of
+ type <code class="type">date</code> is also named <code class="structfield">date</code>.
+ This might be convenient or confusing — you choose.)
+ </p><p>
+ <span class="productname">PostgreSQL</span> supports the standard
+ <acronym class="acronym">SQL</acronym> types <code class="type">int</code>,
+ <code class="type">smallint</code>, <code class="type">real</code>, <code class="type">double
+ precision</code>, <code class="type">char(<em class="replaceable"><code>N</code></em>)</code>,
+ <code class="type">varchar(<em class="replaceable"><code>N</code></em>)</code>, <code class="type">date</code>,
+ <code class="type">time</code>, <code class="type">timestamp</code>, and
+ <code class="type">interval</code>, as well as other types of general utility
+ and a rich set of geometric types.
+ <span class="productname">PostgreSQL</span> can be customized with an
+ arbitrary number of user-defined data types. Consequently, type
+ names are not key words in the syntax, except where required to
+ support special cases in the <acronym class="acronym">SQL</acronym> standard.
+ </p><p>
+ The second example will store cities and their associated
+ geographical location:
+</p><pre class="programlisting">
+CREATE TABLE cities (
+ name varchar(80),
+ location point
+);
+</pre><p>
+ The <code class="type">point</code> type is an example of a
+ <span class="productname">PostgreSQL</span>-specific data type.
+ </p><p>
+ <a id="id-1.4.4.4.8.1" class="indexterm"></a>
+
+ Finally, it should be mentioned that if you don't need a table any
+ longer or want to recreate it differently you can remove it using
+ the following command:
+</p><pre class="synopsis">
+DROP TABLE <em class="replaceable"><code>tablename</code></em>;
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-concepts.html" title="2.2. Concepts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-populate.html" title="2.4. Populating a Table With Rows">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.2. Concepts </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.4. Populating a Table With Rows</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-transactions.html b/doc/src/sgml/html/tutorial-transactions.html
new file mode 100644
index 0000000..bb7779b
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-transactions.html
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.4. Transactions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-fk.html" title="3.3. Foreign Keys" /><link rel="next" href="tutorial-window.html" title="3.5. Window Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.4. Transactions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-fk.html" title="3.3. Foreign Keys">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-window.html" title="3.5. Window Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-TRANSACTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.4. Transactions</h2></div></div></div><a id="id-1.4.5.5.2" class="indexterm"></a><p>
+ <em class="firstterm">Transactions</em> are a fundamental concept of all database
+ systems. The essential point of a transaction is that it bundles
+ multiple steps into a single, all-or-nothing operation. The intermediate
+ states between the steps are not visible to other concurrent transactions,
+ and if some failure occurs that prevents the transaction from completing,
+ then none of the steps affect the database at all.
+ </p><p>
+ For example, consider a bank database that contains balances for various
+ customer accounts, as well as total deposit balances for branches.
+ Suppose that we want to record a payment of $100.00 from Alice's account
+ to Bob's account. Simplifying outrageously, the SQL commands for this
+ might look like:
+
+</p><pre class="programlisting">
+UPDATE accounts SET balance = balance - 100.00
+ WHERE name = 'Alice';
+UPDATE branches SET balance = balance - 100.00
+ WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Alice');
+UPDATE accounts SET balance = balance + 100.00
+ WHERE name = 'Bob';
+UPDATE branches SET balance = balance + 100.00
+ WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Bob');
+</pre><p>
+ </p><p>
+ The details of these commands are not important here; the important
+ point is that there are several separate updates involved to accomplish
+ this rather simple operation. Our bank's officers will want to be
+ assured that either all these updates happen, or none of them happen.
+ It would certainly not do for a system failure to result in Bob
+ receiving $100.00 that was not debited from Alice. Nor would Alice long
+ remain a happy customer if she was debited without Bob being credited.
+ We need a guarantee that if something goes wrong partway through the
+ operation, none of the steps executed so far will take effect. Grouping
+ the updates into a <em class="firstterm">transaction</em> gives us this guarantee.
+ A transaction is said to be <em class="firstterm">atomic</em>: from the point of
+ view of other transactions, it either happens completely or not at all.
+ </p><p>
+ We also want a
+ guarantee that once a transaction is completed and acknowledged by
+ the database system, it has indeed been permanently recorded
+ and won't be lost even if a crash ensues shortly thereafter.
+ For example, if we are recording a cash withdrawal by Bob,
+ we do not want any chance that the debit to his account will
+ disappear in a crash just after he walks out the bank door.
+ A transactional database guarantees that all the updates made by
+ a transaction are logged in permanent storage (i.e., on disk) before
+ the transaction is reported complete.
+ </p><p>
+ Another important property of transactional databases is closely
+ related to the notion of atomic updates: when multiple transactions
+ are running concurrently, each one should not be able to see the
+ incomplete changes made by others. For example, if one transaction
+ is busy totalling all the branch balances, it would not do for it
+ to include the debit from Alice's branch but not the credit to
+ Bob's branch, nor vice versa. So transactions must be all-or-nothing
+ not only in terms of their permanent effect on the database, but
+ also in terms of their visibility as they happen. The updates made
+ so far by an open transaction are invisible to other transactions
+ until the transaction completes, whereupon all the updates become
+ visible simultaneously.
+ </p><p>
+ In <span class="productname">PostgreSQL</span>, a transaction is set up by surrounding
+ the SQL commands of the transaction with
+ <code class="command">BEGIN</code> and <code class="command">COMMIT</code> commands. So our banking
+ transaction would actually look like:
+
+</p><pre class="programlisting">
+BEGIN;
+UPDATE accounts SET balance = balance - 100.00
+ WHERE name = 'Alice';
+-- etc etc
+COMMIT;
+</pre><p>
+ </p><p>
+ If, partway through the transaction, we decide we do not want to
+ commit (perhaps we just noticed that Alice's balance went negative),
+ we can issue the command <code class="command">ROLLBACK</code> instead of
+ <code class="command">COMMIT</code>, and all our updates so far will be canceled.
+ </p><p>
+ <span class="productname">PostgreSQL</span> actually treats every SQL statement as being
+ executed within a transaction. If you do not issue a <code class="command">BEGIN</code>
+ command,
+ then each individual statement has an implicit <code class="command">BEGIN</code> and
+ (if successful) <code class="command">COMMIT</code> wrapped around it. A group of
+ statements surrounded by <code class="command">BEGIN</code> and <code class="command">COMMIT</code>
+ is sometimes called a <em class="firstterm">transaction block</em>.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Some client libraries issue <code class="command">BEGIN</code> and <code class="command">COMMIT</code>
+ commands automatically, so that you might get the effect of transaction
+ blocks without asking. Check the documentation for the interface
+ you are using.
+ </p></div><p>
+ It's possible to control the statements in a transaction in a more
+ granular fashion through the use of <em class="firstterm">savepoints</em>. Savepoints
+ allow you to selectively discard parts of the transaction, while
+ committing the rest. After defining a savepoint with
+ <code class="command">SAVEPOINT</code>, you can if needed roll back to the savepoint
+ with <code class="command">ROLLBACK TO</code>. All the transaction's database changes
+ between defining the savepoint and rolling back to it are discarded, but
+ changes earlier than the savepoint are kept.
+ </p><p>
+ After rolling back to a savepoint, it continues to be defined, so you can
+ roll back to it several times. Conversely, if you are sure you won't need
+ to roll back to a particular savepoint again, it can be released, so the
+ system can free some resources. Keep in mind that either releasing or
+ rolling back to a savepoint
+ will automatically release all savepoints that were defined after it.
+ </p><p>
+ All this is happening within the transaction block, so none of it
+ is visible to other database sessions. When and if you commit the
+ transaction block, the committed actions become visible as a unit
+ to other sessions, while the rolled-back actions never become visible
+ at all.
+ </p><p>
+ Remembering the bank database, suppose we debit $100.00 from Alice's
+ account, and credit Bob's account, only to find later that we should
+ have credited Wally's account. We could do it using savepoints like
+ this:
+
+</p><pre class="programlisting">
+BEGIN;
+UPDATE accounts SET balance = balance - 100.00
+ WHERE name = 'Alice';
+SAVEPOINT my_savepoint;
+UPDATE accounts SET balance = balance + 100.00
+ WHERE name = 'Bob';
+-- oops ... forget that and use Wally's account
+ROLLBACK TO my_savepoint;
+UPDATE accounts SET balance = balance + 100.00
+ WHERE name = 'Wally';
+COMMIT;
+</pre><p>
+ </p><p>
+ This example is, of course, oversimplified, but there's a lot of control
+ possible in a transaction block through the use of savepoints.
+ Moreover, <code class="command">ROLLBACK TO</code> is the only way to regain control of a
+ transaction block that was put in aborted state by the
+ system due to an error, short of rolling it back completely and starting
+ again.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-fk.html" title="3.3. Foreign Keys">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-window.html" title="3.5. Window Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.3. Foreign Keys </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.5. Window Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-update.html b/doc/src/sgml/html/tutorial-update.html
new file mode 100644
index 0000000..d5879a2
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-update.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>2.8. Updates</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-agg.html" title="2.7. Aggregate Functions" /><link rel="next" href="tutorial-delete.html" title="2.9. Deletions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">2.8. Updates</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-agg.html" title="2.7. Aggregate Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><th width="60%" align="center">Chapter 2. The <acronym class="acronym">SQL</acronym> Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-delete.html" title="2.9. Deletions">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-UPDATE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.8. Updates</h2></div></div></div><a id="id-1.4.4.9.2" class="indexterm"></a><p>
+ You can update existing rows using the
+ <code class="command">UPDATE</code> command.
+ Suppose you discover the temperature readings are
+ all off by 2 degrees after November 28. You can correct the
+ data as follows:
+
+</p><pre class="programlisting">
+UPDATE weather
+ SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2
+ WHERE date &gt; '1994-11-28';
+</pre><p>
+ </p><p>
+ Look at the new state of the data:
+</p><pre class="programlisting">
+SELECT * FROM weather;
+
+ city | temp_lo | temp_hi | prcp | date
+---------------+---------+---------+------+------------
+ San Francisco | 46 | 50 | 0.25 | 1994-11-27
+ San Francisco | 41 | 55 | 0 | 1994-11-29
+ Hayward | 35 | 52 | | 1994-11-29
+(3 rows)
+</pre><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-agg.html" title="2.7. Aggregate Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-sql.html" title="Chapter 2. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-delete.html" title="2.9. Deletions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.7. Aggregate Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 2.9. Deletions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-views.html b/doc/src/sgml/html/tutorial-views.html
new file mode 100644
index 0000000..b99e785
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-views.html
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.2. Views</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-advanced-intro.html" title="3.1. Introduction" /><link rel="next" href="tutorial-fk.html" title="3.3. Foreign Keys" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.2. Views</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-advanced-intro.html" title="3.1. Introduction">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-fk.html" title="3.3. Foreign Keys">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-VIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.2. Views</h2></div></div></div><a id="id-1.4.5.3.2" class="indexterm"></a><p>
+ Refer back to the queries in <a class="xref" href="tutorial-join.html" title="2.6. Joins Between Tables">Section 2.6</a>.
+ 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
+ <em class="firstterm">view</em> over the query, which gives a name to
+ the query that you can refer to like an ordinary table:
+
+</p><pre class="programlisting">
+CREATE VIEW myview AS
+ SELECT name, temp_lo, temp_hi, prcp, date, location
+ FROM weather, cities
+ WHERE city = name;
+
+SELECT * FROM myview;
+</pre><p>
+ </p><p>
+ Making liberal use of views is a key aspect of good SQL database
+ design. Views allow you to encapsulate the details of the
+ structure of your tables, which might change as your application
+ evolves, behind consistent interfaces.
+ </p><p>
+ Views can be used in almost any place a real table can be used.
+ Building views upon other views is not uncommon.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced-intro.html" title="3.1. Introduction">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-fk.html" title="3.3. Foreign Keys">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.3. Foreign Keys</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial-window.html b/doc/src/sgml/html/tutorial-window.html
new file mode 100644
index 0000000..1459518
--- /dev/null
+++ b/doc/src/sgml/html/tutorial-window.html
@@ -0,0 +1,202 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.5. Window Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tutorial-transactions.html" title="3.4. Transactions" /><link rel="next" href="tutorial-inheritance.html" title="3.6. Inheritance" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">3.5. Window Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tutorial-transactions.html" title="3.4. Transactions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><th width="60%" align="center">Chapter 3. Advanced Features</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-inheritance.html" title="3.6. Inheritance">Next</a></td></tr></table><hr /></div><div class="sect1" id="TUTORIAL-WINDOW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.5. Window Functions</h2></div></div></div><a id="id-1.4.5.6.2" class="indexterm"></a><p>
+ A <em class="firstterm">window function</em> performs a calculation across a set of
+ table rows that are somehow related to the current row. This is comparable
+ to the type of calculation that can be done with an aggregate function.
+ However, window functions do not cause rows to become grouped into a single
+ output row like non-window aggregate calls would. Instead, the
+ rows retain their separate identities. Behind the scenes, the window
+ function is able to access more than just the current row of the query
+ result.
+ </p><p>
+ Here is an example that shows how to compare each employee's salary
+ with the average salary in his or her department:
+
+</p><pre class="programlisting">
+SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM empsalary;
+</pre><p>
+
+</p><pre class="screen">
+ depname | empno | salary | avg
+-----------+-------+--------+-----------------------
+ develop | 11 | 5200 | 5020.0000000000000000
+ develop | 7 | 4200 | 5020.0000000000000000
+ develop | 9 | 4500 | 5020.0000000000000000
+ develop | 8 | 6000 | 5020.0000000000000000
+ develop | 10 | 5200 | 5020.0000000000000000
+ personnel | 5 | 3500 | 3700.0000000000000000
+ personnel | 2 | 3900 | 3700.0000000000000000
+ sales | 3 | 4800 | 4866.6666666666666667
+ sales | 1 | 5000 | 4866.6666666666666667
+ sales | 4 | 4800 | 4866.6666666666666667
+(10 rows)
+</pre><p>
+
+ The first three output columns come directly from the table
+ <code class="structname">empsalary</code>, and there is one output row for each row in the
+ table. The fourth column represents an average taken across all the table
+ rows that have the same <code class="structfield">depname</code> value as the current row.
+ (This actually is the same function as the non-window <code class="function">avg</code>
+ aggregate, but the <code class="literal">OVER</code> clause causes it to be
+ treated as a window function and computed across the window frame.)
+ </p><p>
+ A window function call always contains an <code class="literal">OVER</code> clause
+ directly following the window function's name and argument(s). This is what
+ syntactically distinguishes it from a normal function or non-window
+ aggregate. The <code class="literal">OVER</code> clause determines exactly how the
+ rows of the query are split up for processing by the window function.
+ The <code class="literal">PARTITION BY</code> clause within <code class="literal">OVER</code>
+ divides the rows into groups, or partitions, that share the same
+ values of the <code class="literal">PARTITION BY</code> expression(s). For each row,
+ the window function is computed across the rows that fall into the
+ same partition as the current row.
+ </p><p>
+ You can also control the order in which rows are processed by
+ window functions using <code class="literal">ORDER BY</code> within <code class="literal">OVER</code>.
+ (The window <code class="literal">ORDER BY</code> does not even have to match the
+ order in which the rows are output.) Here is an example:
+
+</p><pre class="programlisting">
+SELECT depname, empno, salary,
+ rank() OVER (PARTITION BY depname ORDER BY salary DESC)
+FROM empsalary;
+</pre><p>
+
+</p><pre class="screen">
+ depname | empno | salary | rank
+-----------+-------+--------+------
+ develop | 8 | 6000 | 1
+ develop | 10 | 5200 | 2
+ develop | 11 | 5200 | 2
+ develop | 9 | 4500 | 4
+ develop | 7 | 4200 | 5
+ personnel | 2 | 3900 | 1
+ personnel | 5 | 3500 | 2
+ sales | 1 | 5000 | 1
+ sales | 4 | 4800 | 2
+ sales | 3 | 4800 | 2
+(10 rows)
+</pre><p>
+
+ As shown here, the <code class="function">rank</code> function produces a numerical rank
+ for each distinct <code class="literal">ORDER BY</code> value in the current row's
+ partition, using the order defined by the <code class="literal">ORDER BY</code> clause.
+ <code class="function">rank</code> needs no explicit parameter, because its behavior
+ is entirely determined by the <code class="literal">OVER</code> clause.
+ </p><p>
+ The rows considered by a window function are those of the <span class="quote">“<span class="quote">virtual
+ table</span>”</span> produced by the query's <code class="literal">FROM</code> clause as filtered by its
+ <code class="literal">WHERE</code>, <code class="literal">GROUP BY</code>, and <code class="literal">HAVING</code> clauses
+ if any. For example, a row removed because it does not meet the
+ <code class="literal">WHERE</code> condition is not seen by any window function.
+ A query can contain multiple window functions that slice up the data
+ in different ways using different <code class="literal">OVER</code> clauses, but
+ they all act on the same collection of rows defined by this virtual table.
+ </p><p>
+ We already saw that <code class="literal">ORDER BY</code> can be omitted if the ordering
+ of rows is not important. It is also possible to omit <code class="literal">PARTITION
+ BY</code>, in which case there is a single partition containing all rows.
+ </p><p>
+ There is another important concept associated with window functions:
+ for each row, there is a set of rows within its partition called its
+ <em class="firstterm">window frame</em>. Some window functions act only
+ on the rows of the window frame, rather than of the whole partition.
+ By default, if <code class="literal">ORDER BY</code> is supplied then the frame consists of
+ all rows from the start of the partition up through the current row, plus
+ any following rows that are equal to the current row according to the
+ <code class="literal">ORDER BY</code> clause. When <code class="literal">ORDER BY</code> is omitted the
+ default frame consists of all rows in the partition.
+ <a href="#ftn.id-1.4.5.6.9.5" class="footnote"><sup class="footnote" id="id-1.4.5.6.9.5">[5]</sup></a>
+ Here is an example using <code class="function">sum</code>:
+ </p><pre class="programlisting">
+SELECT salary, sum(salary) OVER () FROM empsalary;
+</pre><pre class="screen">
+ salary | sum
+--------+-------
+ 5200 | 47100
+ 5000 | 47100
+ 3500 | 47100
+ 4800 | 47100
+ 3900 | 47100
+ 4200 | 47100
+ 4500 | 47100
+ 4800 | 47100
+ 6000 | 47100
+ 5200 | 47100
+(10 rows)
+</pre><p>
+ Above, since there is no <code class="literal">ORDER BY</code> in the <code class="literal">OVER</code>
+ clause, the window frame is the same as the partition, which for lack of
+ <code class="literal">PARTITION BY</code> is the whole table; in other words each sum is
+ taken over the whole table and so we get the same result for each output
+ row. But if we add an <code class="literal">ORDER BY</code> clause, we get very different
+ results:
+ </p><pre class="programlisting">
+SELECT salary, sum(salary) OVER (ORDER BY salary) FROM empsalary;
+</pre><pre class="screen">
+ salary | sum
+--------+-------
+ 3500 | 3500
+ 3900 | 7400
+ 4200 | 11600
+ 4500 | 16100
+ 4800 | 25700
+ 4800 | 25700
+ 5000 | 30700
+ 5200 | 41100
+ 5200 | 41100
+ 6000 | 47100
+(10 rows)
+</pre><p>
+ Here the sum is taken from the first (lowest) salary up through the
+ current one, including any duplicates of the current one (notice the
+ results for the duplicated salaries).
+ </p><p>
+ Window functions are permitted only in the <code class="literal">SELECT</code> list
+ and the <code class="literal">ORDER BY</code> clause of the query. They are forbidden
+ elsewhere, such as in <code class="literal">GROUP BY</code>, <code class="literal">HAVING</code>
+ and <code class="literal">WHERE</code> clauses. This is because they logically
+ execute after the processing of those clauses. Also, window functions
+ execute after non-window aggregate functions. This means it is valid to
+ include an aggregate function call in the arguments of a window function,
+ but not vice versa.
+ </p><p>
+ If there is a need to filter or group rows after the window calculations
+ are performed, you can use a sub-select. For example:
+
+</p><pre class="programlisting">
+SELECT depname, empno, salary, enroll_date
+FROM
+ (SELECT depname, empno, salary, enroll_date,
+ rank() OVER (PARTITION BY depname ORDER BY salary DESC, empno) AS pos
+ FROM empsalary
+ ) AS ss
+WHERE pos &lt; 3;
+</pre><p>
+
+ The above query only shows the rows from the inner query having
+ <code class="literal">rank</code> less than 3.
+ </p><p>
+ When a query involves multiple window functions, it is possible to write
+ out each one with a separate <code class="literal">OVER</code> clause, but this is
+ duplicative and error-prone if the same windowing behavior is wanted
+ for several functions. Instead, each windowing behavior can be named
+ in a <code class="literal">WINDOW</code> clause and then referenced in <code class="literal">OVER</code>.
+ For example:
+
+</p><pre class="programlisting">
+SELECT sum(salary) OVER w, avg(salary) OVER w
+ FROM empsalary
+ WINDOW w AS (PARTITION BY depname ORDER BY salary DESC);
+</pre><p>
+ </p><p>
+ More details about window functions can be found in
+ <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a>,
+ <a class="xref" href="functions-window.html" title="9.22. Window Functions">Section 9.22</a>,
+ <a class="xref" href="queries-table-expressions.html#QUERIES-WINDOW" title="7.2.5. Window Function Processing">Section 7.2.5</a>, and the
+ <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> reference page.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.4.5.6.9.5" class="footnote"><p><a href="#id-1.4.5.6.9.5" class="para"><sup class="para">[5] </sup></a>
+ There are options to define the window frame in other ways, but
+ this tutorial does not cover them. See
+ <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a> for details.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-transactions.html" title="3.4. Transactions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html" title="Chapter 3. Advanced Features">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-inheritance.html" title="3.6. Inheritance">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.4. Transactions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 3.6. Inheritance</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/tutorial.html b/doc/src/sgml/html/tutorial.html
new file mode 100644
index 0000000..988bd19
--- /dev/null
+++ b/doc/src/sgml/html/tutorial.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Part I. Tutorial</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bug-reporting.html" title="5. Bug Reporting Guidelines" /><link rel="next" href="tutorial-start.html" title="Chapter 1. Getting Started" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Part I. Tutorial</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bug-reporting.html" title="5. Bug Reporting Guidelines">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><th width="60%" align="center">PostgreSQL 15.5 Documentation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial-start.html" title="Chapter 1. Getting Started">Next</a></td></tr></table><hr /></div><div class="part" id="TUTORIAL"><div class="titlepage"><div><div><h1 class="title">Part I. Tutorial</h1></div></div></div><div class="partintro" id="id-1.4.2"><div></div><p>
+ Welcome to the <span class="productname">PostgreSQL</span> Tutorial. The
+ following few chapters are intended to give a simple introduction
+ to <span class="productname">PostgreSQL</span>, relational database
+ concepts, and the SQL language to those who are new to any one of
+ these aspects. We only assume some general knowledge about how to
+ use computers. No particular Unix or programming experience is
+ required. This part is mainly intended to give you some hands-on
+ experience with important aspects of the
+ <span class="productname">PostgreSQL</span> system. It makes no attempt
+ to be a complete or thorough treatment of the topics it covers.
+ </p><p>
+ After you have worked through this tutorial you might want to move
+ on to reading <a class="xref" href="sql.html" title="Part II. The SQL Language">Part II</a> to gain a more formal knowledge
+ of the SQL language, or <a class="xref" href="client-interfaces.html" title="Part IV. Client Interfaces">Part IV</a> for
+ information about developing applications for
+ <span class="productname">PostgreSQL</span>. Those who set up and
+ manage their own server should also read <a class="xref" href="admin.html" title="Part III. Server Administration">Part III</a>.
+ </p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="tutorial-start.html">1. Getting Started</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-install.html">1.1. Installation</a></span></dt><dt><span class="sect1"><a href="tutorial-arch.html">1.2. Architectural Fundamentals</a></span></dt><dt><span class="sect1"><a href="tutorial-createdb.html">1.3. Creating a Database</a></span></dt><dt><span class="sect1"><a href="tutorial-accessdb.html">1.4. Accessing a Database</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-sql.html">2. The <acronym class="acronym">SQL</acronym> Language</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-sql-intro.html">2.1. Introduction</a></span></dt><dt><span class="sect1"><a href="tutorial-concepts.html">2.2. Concepts</a></span></dt><dt><span class="sect1"><a href="tutorial-table.html">2.3. Creating a New Table</a></span></dt><dt><span class="sect1"><a href="tutorial-populate.html">2.4. Populating a Table With Rows</a></span></dt><dt><span class="sect1"><a href="tutorial-select.html">2.5. Querying a Table</a></span></dt><dt><span class="sect1"><a href="tutorial-join.html">2.6. Joins Between Tables</a></span></dt><dt><span class="sect1"><a href="tutorial-agg.html">2.7. Aggregate Functions</a></span></dt><dt><span class="sect1"><a href="tutorial-update.html">2.8. Updates</a></span></dt><dt><span class="sect1"><a href="tutorial-delete.html">2.9. Deletions</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-advanced.html">3. Advanced Features</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-advanced-intro.html">3.1. Introduction</a></span></dt><dt><span class="sect1"><a href="tutorial-views.html">3.2. Views</a></span></dt><dt><span class="sect1"><a href="tutorial-fk.html">3.3. Foreign Keys</a></span></dt><dt><span class="sect1"><a href="tutorial-transactions.html">3.4. Transactions</a></span></dt><dt><span class="sect1"><a href="tutorial-window.html">3.5. Window Functions</a></span></dt><dt><span class="sect1"><a href="tutorial-inheritance.html">3.6. Inheritance</a></span></dt><dt><span class="sect1"><a href="tutorial-conclusion.html">3.7. Conclusion</a></span></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bug-reporting.html" title="5. Bug Reporting Guidelines">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html" title="PostgreSQL 15.5 Documentation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-start.html" title="Chapter 1. Getting Started">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. Bug Reporting Guidelines </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 1. Getting Started</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-func.html b/doc/src/sgml/html/typeconv-func.html
new file mode 100644
index 0000000..63be92a
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-func.html
@@ -0,0 +1,268 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.3. Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-oper.html" title="10.2. Operators" /><link rel="next" href="typeconv-query.html" title="10.4. Value Storage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.3. Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-oper.html" title="10.2. Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-query.html" title="10.4. Value Storage">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-FUNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.3. Functions</h2></div></div></div><a id="id-1.5.9.8.2" class="indexterm"></a><p>
+ The specific function that is referenced by a function call
+ is determined using the following procedure.
+ </p><div class="procedure" id="id-1.5.9.8.4"><p class="title"><strong>Function Type Resolution</strong></p><ol class="procedure" type="1"><li class="step"><p>
+Select the functions to be considered from the
+<code class="classname">pg_proc</code> system catalog. If a non-schema-qualified
+function name was used, the functions
+considered are those with the matching name and argument count that are
+visible in the current search path (see <a class="xref" href="ddl-schemas.html#DDL-SCHEMAS-PATH" title="5.9.3. The Schema Search Path">Section 5.9.3</a>).
+If a qualified function name was given, only functions in the specified
+schema are considered.
+</p><ol type="a" class="substeps"><li class="step"><p>
+If the search path finds multiple functions of identical argument types,
+only the one appearing earliest in the path is considered. Functions of
+different argument types are considered on an equal footing regardless of
+search path position.
+</p></li><li class="step"><p>
+If a function is declared with a <code class="literal">VARIADIC</code> array parameter, and
+the call does not use the <code class="literal">VARIADIC</code> keyword, then the function
+is treated as if the array parameter were replaced by one or more occurrences
+of its element type, as needed to match the call. After such expansion the
+function might have effective argument types identical to some non-variadic
+function. In that case the function appearing earlier in the search path is
+used, or if the two functions are in the same schema, the non-variadic one is
+preferred.
+</p><p>
+This creates a security hazard when calling, via qualified name
+ <a href="#ftn.FUNC-QUALIFIED-SECURITY" class="footnote"><sup class="footnote" id="FUNC-QUALIFIED-SECURITY">[10]</sup></a>,
+a variadic function found in a schema that permits untrusted users to create
+objects. A malicious user can take control and execute arbitrary SQL
+functions as though you executed them. Substitute a call bearing
+the <code class="literal">VARIADIC</code> keyword, which bypasses this hazard. Calls
+populating <code class="literal">VARIADIC "any"</code> parameters often have no
+equivalent formulation containing the <code class="literal">VARIADIC</code> keyword. To
+issue those calls safely, the function's schema must permit only trusted users
+to create objects.
+</p></li><li class="step"><p>
+Functions that have default values for parameters are considered to match any
+call that omits zero or more of the defaultable parameter positions. If more
+than one such function matches a call, the one appearing earliest in the
+search path is used. If there are two or more such functions in the same
+schema with identical parameter types in the non-defaulted positions (which is
+possible if they have different sets of defaultable parameters), the system
+will not be able to determine which to prefer, and so an <span class="quote">“<span class="quote">ambiguous
+function call</span>”</span> error will result if no better match to the call can be
+found.
+</p><p>
+This creates an availability hazard when calling, via qualified
+name<a href="typeconv-func.html#ftn.FUNC-QUALIFIED-SECURITY" class="footnoteref"><sup class="footnoteref">[10]</sup></a>, any function found in a
+schema that permits untrusted users to create objects. A malicious user can
+create a function with the name of an existing function, replicating that
+function's parameters and appending novel parameters having default values.
+This precludes new calls to the original function. To forestall this hazard,
+place functions in schemas that permit only trusted users to create objects.
+</p></li></ol></li><li class="step"><p>
+Check for a function accepting exactly the input argument types.
+If one exists (there can be only one exact match in the set of
+functions considered), use it. Lack of an exact match creates a security
+hazard when calling, via qualified
+name<a href="typeconv-func.html#ftn.FUNC-QUALIFIED-SECURITY" class="footnoteref"><sup class="footnoteref">[10]</sup></a>, a function found in a
+schema that permits untrusted users to create objects. In such situations,
+cast arguments to force an exact match. (Cases involving <code class="type">unknown</code>
+will never find a match at this step.)
+</p></li><li class="step"><p>
+If no exact match is found, see if the function call appears
+to be a special type conversion request. This happens if the function call
+has just one argument and the function name is the same as the (internal)
+name of some data type. Furthermore, the function argument must be either
+an unknown-type literal, or a type that is binary-coercible to the named
+data type, or a type that could be converted to the named data type by
+applying that type's I/O functions (that is, the conversion is either to or
+from one of the standard string types). When these conditions are met,
+the function call is treated as a form of <code class="literal">CAST</code> specification.
+ <a href="#ftn.id-1.5.9.8.4.4.1.2" class="footnote"><sup class="footnote" id="id-1.5.9.8.4.4.1.2">[11]</sup></a>
+</p></li><li class="step"><p>
+Look for the best match.
+</p><ol type="a" class="substeps"><li class="step"><p>
+Discard candidate functions for which the input types do not match
+and cannot be converted (using an implicit conversion) to match.
+<code class="type">unknown</code> literals are
+assumed to be convertible to anything for this purpose. If only one
+candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+If any input argument is of a domain type, treat it as being of the
+domain's base type for all subsequent steps. This ensures that domains
+act like their base types for purposes of ambiguous-function resolution.
+</p></li><li class="step"><p>
+Run through all candidates and keep those with the most exact matches
+on input types. Keep all candidates if none have exact matches.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+Run through all candidates and keep those that accept preferred types (of the
+input data type's type category) at the most positions where type conversion
+will be required.
+Keep all candidates if none accept preferred types.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+If any input arguments are <code class="type">unknown</code>, check the type categories
+accepted
+at those argument positions by the remaining candidates. At each position,
+select the <code class="type">string</code> category if any candidate accepts that category.
+(This bias towards string
+is appropriate since an unknown-type literal looks like a string.)
+Otherwise, if all the remaining candidates accept the same type category,
+select that category; otherwise fail because
+the correct choice cannot be deduced without more clues.
+Now discard candidates that do not accept the selected type category.
+Furthermore, if any candidate accepts a preferred type in that category,
+discard candidates that accept non-preferred types for that argument.
+Keep all candidates if none survive these tests.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+If there are both <code class="type">unknown</code> and known-type arguments, and all
+the known-type arguments have the same type, assume that the
+<code class="type">unknown</code> arguments are also of that type, and check which
+candidates can accept that type at the <code class="type">unknown</code>-argument
+positions. If exactly one candidate passes this test, use it.
+Otherwise, fail.
+</p></li></ol></li></ol></div><p>
+Note that the <span class="quote">“<span class="quote">best match</span>”</span> rules are identical for operator and
+function type resolution.
+Some examples follow.
+</p><div class="example" id="id-1.5.9.8.6"><p class="title"><strong>Example 10.6. Rounding Function Argument Type Resolution</strong></p><div class="example-contents"><p>
+There is only one <code class="function">round</code> function that takes two
+arguments; it takes a first argument of type <code class="type">numeric</code> and
+a second argument of type <code class="type">integer</code>.
+So the following query automatically converts
+the first argument of type <code class="type">integer</code> to
+<code class="type">numeric</code>:
+
+</p><pre class="screen">
+SELECT round(4, 4);
+
+ round
+--------
+ 4.0000
+(1 row)
+</pre><p>
+
+That query is actually transformed by the parser to:
+</p><pre class="screen">
+SELECT round(CAST (4 AS numeric), 4);
+</pre><p>
+</p><p>
+Since numeric constants with decimal points are initially assigned the
+type <code class="type">numeric</code>, the following query will require no type
+conversion and therefore might be slightly more efficient:
+</p><pre class="screen">
+SELECT round(4.0, 4);
+</pre><p>
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.8.7"><p class="title"><strong>Example 10.7. Variadic Function Resolution</strong></p><div class="example-contents"><p>
+</p><pre class="screen">
+CREATE FUNCTION public.variadic_example(VARIADIC numeric[]) RETURNS int
+ LANGUAGE sql AS 'SELECT 1';
+CREATE FUNCTION
+</pre><p>
+
+This function accepts, but does not require, the VARIADIC keyword. It
+tolerates both integer and numeric arguments:
+
+</p><pre class="screen">
+SELECT public.variadic_example(0),
+ public.variadic_example(0.0),
+ public.variadic_example(VARIADIC array[0.0]);
+ variadic_example | variadic_example | variadic_example
+------------------+------------------+------------------
+ 1 | 1 | 1
+(1 row)
+</pre><p>
+
+However, the first and second calls will prefer more-specific functions, if
+available:
+
+</p><pre class="screen">
+CREATE FUNCTION public.variadic_example(numeric) RETURNS int
+ LANGUAGE sql AS 'SELECT 2';
+CREATE FUNCTION
+
+CREATE FUNCTION public.variadic_example(int) RETURNS int
+ LANGUAGE sql AS 'SELECT 3';
+CREATE FUNCTION
+
+SELECT public.variadic_example(0),
+ public.variadic_example(0.0),
+ public.variadic_example(VARIADIC array[0.0]);
+ variadic_example | variadic_example | variadic_example
+------------------+------------------+------------------
+ 3 | 2 | 1
+(1 row)
+</pre><p>
+
+Given the default configuration and only the first function existing, the
+first and second calls are insecure. Any user could intercept them by
+creating the second or third function. By matching the argument type exactly
+and using the <code class="literal">VARIADIC</code> keyword, the third call is secure.
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.8.8"><p class="title"><strong>Example 10.8. Substring Function Type Resolution</strong></p><div class="example-contents"><p>
+There are several <code class="function">substr</code> functions, one of which
+takes types <code class="type">text</code> and <code class="type">integer</code>. If called
+with a string constant of unspecified type, the system chooses the
+candidate function that accepts an argument of the preferred category
+<code class="literal">string</code> (namely of type <code class="type">text</code>).
+
+</p><pre class="screen">
+SELECT substr('1234', 3);
+
+ substr
+--------
+ 34
+(1 row)
+</pre><p>
+</p><p>
+If the string is declared to be of type <code class="type">varchar</code>, as might be the case
+if it comes from a table, then the parser will try to convert it to become <code class="type">text</code>:
+</p><pre class="screen">
+SELECT substr(varchar '1234', 3);
+
+ substr
+--------
+ 34
+(1 row)
+</pre><p>
+
+This is transformed by the parser to effectively become:
+</p><pre class="screen">
+SELECT substr(CAST (varchar '1234' AS text), 3);
+</pre><p>
+</p><p>
+</p><div class="note"><h3 class="title">Note</h3><p>
+The parser learns from the <code class="structname">pg_cast</code> catalog that
+<code class="type">text</code> and <code class="type">varchar</code>
+are binary-compatible, meaning that one can be passed to a function that
+accepts the other without doing any physical conversion. Therefore, no
+type conversion call is really inserted in this case.
+</p></div><p>
+</p><p>
+And, if the function is called with an argument of type <code class="type">integer</code>,
+the parser will try to convert that to <code class="type">text</code>:
+</p><pre class="screen">
+SELECT substr(1234, 3);
+ERROR: function substr(integer, integer) does not exist
+HINT: No function matches the given name and argument types. You might need
+to add explicit type casts.
+</pre><p>
+
+This does not work because <code class="type">integer</code> does not have an implicit cast
+to <code class="type">text</code>. An explicit cast will work, however:
+</p><pre class="screen">
+SELECT substr(CAST (1234 AS text), 3);
+
+ substr
+--------
+ 34
+(1 row)
+</pre><p>
+</p></div></div><br class="example-break" /><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.FUNC-QUALIFIED-SECURITY" class="footnote"><p><a href="#FUNC-QUALIFIED-SECURITY" class="para"><sup class="para">[10] </sup></a>
+ The hazard does not arise with a non-schema-qualified name, because a
+ search path containing schemas that permit untrusted users to create
+ objects is not a <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage
+ pattern</a>.
+ </p></div><div id="ftn.id-1.5.9.8.4.4.1.2" class="footnote"><p><a href="#id-1.5.9.8.4.4.1.2" class="para"><sup class="para">[11] </sup></a>
+ The reason for this step is to support function-style cast specifications
+ in cases where there is not an actual cast function. If there is a cast
+ function, it is conventionally named after its output type, and so there
+ is no need to have a special case. See
+ <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>
+ for additional commentary.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-oper.html" title="10.2. Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-query.html" title="10.4. Value Storage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.2. Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.4. Value Storage</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-oper.html b/doc/src/sgml/html/typeconv-oper.html
new file mode 100644
index 0000000..fbcb13c
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-oper.html
@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.2. Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-overview.html" title="10.1. Overview" /><link rel="next" href="typeconv-func.html" title="10.3. Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.2. Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-overview.html" title="10.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-func.html" title="10.3. Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-OPER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.2. Operators</h2></div></div></div><a id="id-1.5.9.7.2" class="indexterm"></a><p>
+ The specific operator that is referenced by an operator expression
+ is determined using the following procedure.
+ Note that this procedure is indirectly affected
+ by the precedence of the operators involved, since that will determine
+ which sub-expressions are taken to be the inputs of which operators.
+ See <a class="xref" href="sql-syntax-lexical.html#SQL-PRECEDENCE" title="4.1.6. Operator Precedence">Section 4.1.6</a> for more information.
+ </p><div class="procedure" id="id-1.5.9.7.4"><p class="title"><strong>Operator Type Resolution</strong></p><ol class="procedure" type="1"><li class="step" id="OP-RESOL-SELECT"><p>
+Select the operators to be considered from the
+<code class="classname">pg_operator</code> system catalog. If a non-schema-qualified
+operator name was used (the usual case), the operators
+considered are those with the matching name and argument count that are
+visible in the current search path (see <a class="xref" href="ddl-schemas.html#DDL-SCHEMAS-PATH" title="5.9.3. The Schema Search Path">Section 5.9.3</a>).
+If a qualified operator name was given, only operators in the specified
+schema are considered.
+</p><ol type="a" class="substeps"><li class="step"><p>
+If the search path finds multiple operators with identical argument types,
+only the one appearing earliest in the path is considered. Operators with
+different argument types are considered on an equal footing regardless of
+search path position.
+</p></li></ol></li><li class="step" id="OP-RESOL-EXACT-MATCH"><p>
+Check for an operator accepting exactly the input argument types.
+If one exists (there can be only one exact match in the set of
+operators considered), use it. Lack of an exact match creates a security
+hazard when calling, via qualified name
+ <a href="#ftn.OP-QUALIFIED-SECURITY" class="footnote"><sup class="footnote" id="OP-QUALIFIED-SECURITY">[9]</sup></a>
+(not typical), any operator found in a schema that permits untrusted users to
+create objects. In such situations, cast arguments to force an exact match.
+</p><ol type="a" class="substeps"><li class="step" id="OP-RESOL-EXACT-UNKNOWN"><p>
+If one argument of a binary operator invocation is of the <code class="type">unknown</code> type,
+then assume it is the same type as the other argument for this check.
+Invocations involving two <code class="type">unknown</code> inputs, or a prefix operator
+with an <code class="type">unknown</code> input, will never find a match at this step.
+</p></li><li class="step" id="OP-RESOL-EXACT-DOMAIN"><p>
+If one argument of a binary operator invocation is of the <code class="type">unknown</code>
+type and the other is of a domain type, next check to see if there is an
+operator accepting exactly the domain's base type on both sides; if so, use it.
+</p></li></ol></li><li class="step" id="OP-RESOL-BEST-MATCH"><p>
+Look for the best match.
+</p><ol type="a" class="substeps"><li class="step"><p>
+Discard candidate operators for which the input types do not match
+and cannot be converted (using an implicit conversion) to match.
+<code class="type">unknown</code> literals are
+assumed to be convertible to anything for this purpose. If only one
+candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+If any input argument is of a domain type, treat it as being of the
+domain's base type for all subsequent steps. This ensures that domains
+act like their base types for purposes of ambiguous-operator resolution.
+</p></li><li class="step"><p>
+Run through all candidates and keep those with the most exact matches
+on input types. Keep all candidates if none have exact matches.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+Run through all candidates and keep those that accept preferred types (of the
+input data type's type category) at the most positions where type conversion
+will be required.
+Keep all candidates if none accept preferred types.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step"><p>
+If any input arguments are <code class="type">unknown</code>, check the type
+categories accepted at those argument positions by the remaining
+candidates. At each position, select the <code class="type">string</code> category
+if any
+candidate accepts that category. (This bias towards string is appropriate
+since an unknown-type literal looks like a string.) Otherwise, if
+all the remaining candidates accept the same type category, select that
+category; otherwise fail because the correct choice cannot be deduced
+without more clues. Now discard
+candidates that do not accept the selected type category. Furthermore,
+if any candidate accepts a preferred type in that category,
+discard candidates that accept non-preferred types for that argument.
+Keep all candidates if none survive these tests.
+If only one candidate remains, use it; else continue to the next step.
+</p></li><li class="step" id="OP-RESOL-LAST-UNKNOWN"><p>
+If there are both <code class="type">unknown</code> and known-type arguments, and all
+the known-type arguments have the same type, assume that the
+<code class="type">unknown</code> arguments are also of that type, and check which
+candidates can accept that type at the <code class="type">unknown</code>-argument
+positions. If exactly one candidate passes this test, use it.
+Otherwise, fail.
+</p></li></ol></li></ol></div><p>
+Some examples follow.
+</p><div class="example" id="id-1.5.9.7.6"><p class="title"><strong>Example 10.1. Square Root Operator Type Resolution</strong></p><div class="example-contents"><p>
+There is only one square root operator (prefix <code class="literal">|/</code>)
+defined in the standard catalog, and it takes an argument of type
+<code class="type">double precision</code>.
+The scanner assigns an initial type of <code class="type">integer</code> to the argument
+in this query expression:
+</p><pre class="screen">
+SELECT |/ 40 AS "square root of 40";
+ square root of 40
+-------------------
+ 6.324555320336759
+(1 row)
+</pre><p>
+
+So the parser does a type conversion on the operand and the query
+is equivalent to:
+
+</p><pre class="screen">
+SELECT |/ CAST(40 AS double precision) AS "square root of 40";
+</pre><p>
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.7.7"><p class="title"><strong>Example 10.2. String Concatenation Operator Type Resolution</strong></p><div class="example-contents"><p>
+A string-like syntax is used for working with string types and for
+working with complex extension types.
+Strings with unspecified type are matched with likely operator candidates.
+</p><p>
+An example with one unspecified argument:
+</p><pre class="screen">
+SELECT text 'abc' || 'def' AS "text and unknown";
+
+ text and unknown
+------------------
+ abcdef
+(1 row)
+</pre><p>
+</p><p>
+In this case the parser looks to see if there is an operator taking <code class="type">text</code>
+for both arguments. Since there is, it assumes that the second argument should
+be interpreted as type <code class="type">text</code>.
+</p><p>
+Here is a concatenation of two values of unspecified types:
+</p><pre class="screen">
+SELECT 'abc' || 'def' AS "unspecified";
+
+ unspecified
+-------------
+ abcdef
+(1 row)
+</pre><p>
+</p><p>
+In this case there is no initial hint for which type to use, since no types
+are specified in the query. So, the parser looks for all candidate operators
+and finds that there are candidates accepting both string-category and
+bit-string-category inputs. Since string category is preferred when available,
+that category is selected, and then the
+preferred type for strings, <code class="type">text</code>, is used as the specific
+type to resolve the unknown-type literals as.
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.7.8"><p class="title"><strong>Example 10.3. Absolute-Value and Negation Operator Type Resolution</strong></p><div class="example-contents"><p>
+The <span class="productname">PostgreSQL</span> operator catalog has several
+entries for the prefix operator <code class="literal">@</code>, all of which implement
+absolute-value operations for various numeric data types. One of these
+entries is for type <code class="type">float8</code>, which is the preferred type in
+the numeric category. Therefore, <span class="productname">PostgreSQL</span>
+will use that entry when faced with an <code class="type">unknown</code> input:
+</p><pre class="screen">
+SELECT @ '-4.5' AS "abs";
+ abs
+-----
+ 4.5
+(1 row)
+</pre><p>
+Here the system has implicitly resolved the unknown-type literal as type
+<code class="type">float8</code> before applying the chosen operator. We can verify that
+<code class="type">float8</code> and not some other type was used:
+</p><pre class="screen">
+SELECT @ '-4.5e500' AS "abs";
+
+ERROR: "-4.5e500" is out of range for type double precision
+</pre><p>
+</p><p>
+On the other hand, the prefix operator <code class="literal">~</code> (bitwise negation)
+is defined only for integer data types, not for <code class="type">float8</code>. So, if we
+try a similar case with <code class="literal">~</code>, we get:
+</p><pre class="screen">
+SELECT ~ '20' AS "negation";
+
+ERROR: operator is not unique: ~ "unknown"
+HINT: Could not choose a best candidate operator. You might need to add
+explicit type casts.
+</pre><p>
+This happens because the system cannot decide which of the several
+possible <code class="literal">~</code> operators should be preferred. We can help
+it out with an explicit cast:
+</p><pre class="screen">
+SELECT ~ CAST('20' AS int8) AS "negation";
+
+ negation
+----------
+ -21
+(1 row)
+</pre><p>
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.7.9"><p class="title"><strong>Example 10.4. Array Inclusion Operator Type Resolution</strong></p><div class="example-contents"><p>
+Here is another example of resolving an operator with one known and one
+unknown input:
+</p><pre class="screen">
+SELECT array[1,2] &lt;@ '{1,2,3}' as "is subset";
+
+ is subset
+-----------
+ t
+(1 row)
+</pre><p>
+The <span class="productname">PostgreSQL</span> operator catalog has several
+entries for the infix operator <code class="literal">&lt;@</code>, but the only two that
+could possibly accept an integer array on the left-hand side are
+array inclusion (<code class="type">anyarray</code> <code class="literal">&lt;@</code> <code class="type">anyarray</code>)
+and range inclusion (<code class="type">anyelement</code> <code class="literal">&lt;@</code> <code class="type">anyrange</code>).
+Since none of these polymorphic pseudo-types (see <a class="xref" href="datatype-pseudo.html" title="8.21. Pseudo-Types">Section 8.21</a>) are considered preferred, the parser cannot
+resolve the ambiguity on that basis.
+However, <a class="xref" href="typeconv-oper.html#OP-RESOL-LAST-UNKNOWN" title="Step 3.f">Step 3.f</a> tells
+it to assume that the unknown-type literal is of the same type as the other
+input, that is, integer array. Now only one of the two operators can match,
+so array inclusion is selected. (Had range inclusion been selected, we would
+have gotten an error, because the string does not have the right format to be
+a range literal.)
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.7.10"><p class="title"><strong>Example 10.5. Custom Operator on a Domain Type</strong></p><div class="example-contents"><p>
+Users sometimes try to declare operators applying just to a domain type.
+This is possible but is not nearly as useful as it might seem, because the
+operator resolution rules are designed to select operators applying to the
+domain's base type. As an example consider
+</p><pre class="screen">
+CREATE DOMAIN mytext AS text CHECK(...);
+CREATE FUNCTION mytext_eq_text (mytext, text) RETURNS boolean AS ...;
+CREATE OPERATOR = (procedure=mytext_eq_text, leftarg=mytext, rightarg=text);
+CREATE TABLE mytable (val mytext);
+
+SELECT * FROM mytable WHERE val = 'foo';
+</pre><p>
+This query will not use the custom operator. The parser will first see if
+there is a <code class="type">mytext</code> <code class="literal">=</code> <code class="type">mytext</code> operator
+(<a class="xref" href="typeconv-oper.html#OP-RESOL-EXACT-UNKNOWN" title="Step 2.a">Step 2.a</a>), which there is not;
+then it will consider the domain's base type <code class="type">text</code>, and see if
+there is a <code class="type">text</code> <code class="literal">=</code> <code class="type">text</code> operator
+(<a class="xref" href="typeconv-oper.html#OP-RESOL-EXACT-DOMAIN" title="Step 2.b">Step 2.b</a>), which there is;
+so it resolves the <code class="type">unknown</code>-type literal as <code class="type">text</code> and
+uses the <code class="type">text</code> <code class="literal">=</code> <code class="type">text</code> operator.
+The only way to get the custom operator to be used is to explicitly cast
+the literal:
+</p><pre class="screen">
+SELECT * FROM mytable WHERE val = text 'foo';
+</pre><p>
+so that the <code class="type">mytext</code> <code class="literal">=</code> <code class="type">text</code> operator is found
+immediately according to the exact-match rule. If the best-match rules
+are reached, they actively discriminate against operators on domain types.
+If they did not, such an operator would create too many ambiguous-operator
+failures, because the casting rules always consider a domain as castable
+to or from its base type, and so the domain operator would be considered
+usable in all the same cases as a similarly-named operator on the base type.
+</p></div></div><br class="example-break" /><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.OP-QUALIFIED-SECURITY" class="footnote"><p><a href="#OP-QUALIFIED-SECURITY" class="para"><sup class="para">[9] </sup></a>
+ The hazard does not arise with a non-schema-qualified name, because a
+ search path containing schemas that permit untrusted users to create
+ objects is not a <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage
+ pattern</a>.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-overview.html" title="10.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-func.html" title="10.3. Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.3. Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-overview.html b/doc/src/sgml/html/typeconv-overview.html
new file mode 100644
index 0000000..3f29ed5
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-overview.html
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv.html" title="Chapter 10. Type Conversion" /><link rel="next" href="typeconv-oper.html" title="10.2. Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv.html" title="Chapter 10. Type Conversion">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-oper.html" title="10.2. Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.1. Overview</h2></div></div></div><p>
+<acronym class="acronym">SQL</acronym> is a strongly typed language. That is, every data item
+has an associated data type which determines its behavior and allowed usage.
+<span class="productname">PostgreSQL</span> has an extensible type system that is
+more general and flexible than other <acronym class="acronym">SQL</acronym> implementations.
+Hence, most type conversion behavior in <span class="productname">PostgreSQL</span>
+is governed by general rules rather than by ad hoc
+heuristics. This allows the use of mixed-type expressions even with
+user-defined types.
+</p><p>
+The <span class="productname">PostgreSQL</span> scanner/parser divides lexical
+elements into five fundamental categories: integers, non-integer numbers,
+strings, identifiers, and key words. Constants of most non-numeric types are
+first classified as strings. The <acronym class="acronym">SQL</acronym> language definition
+allows specifying type names with strings, and this mechanism can be used in
+<span class="productname">PostgreSQL</span> to start the parser down the correct
+path. For example, the query:
+
+</p><pre class="screen">
+SELECT text 'Origin' AS "label", point '(0,0)' AS "value";
+
+ label | value
+--------+-------
+ Origin | (0,0)
+(1 row)
+</pre><p>
+
+has two literal constants, of type <code class="type">text</code> and <code class="type">point</code>.
+If a type is not specified for a string literal, then the placeholder type
+<code class="type">unknown</code> is assigned initially, to be resolved in later
+stages as described below.
+</p><p>
+There are four fundamental <acronym class="acronym">SQL</acronym> constructs requiring
+distinct type conversion rules in the <span class="productname">PostgreSQL</span>
+parser:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+Function calls
+</span></dt><dd><p>
+Much of the <span class="productname">PostgreSQL</span> type system is built around a
+rich set of functions. Functions can have one or more arguments.
+Since <span class="productname">PostgreSQL</span> permits function
+overloading, the function name alone does not uniquely identify the function
+to be called; the parser must select the right function based on the data
+types of the supplied arguments.
+</p></dd><dt><span class="term">
+Operators
+</span></dt><dd><p>
+<span class="productname">PostgreSQL</span> allows expressions with
+prefix (one-argument) operators,
+as well as infix (two-argument) operators. Like functions, operators can
+be overloaded, so the same problem of selecting the right operator
+exists.
+</p></dd><dt><span class="term">
+Value Storage
+</span></dt><dd><p>
+<acronym class="acronym">SQL</acronym> <code class="command">INSERT</code> and <code class="command">UPDATE</code> statements place the results of
+expressions into a table. The expressions in the statement must be matched up
+with, and perhaps converted to, the types of the target columns.
+</p></dd><dt><span class="term">
+<code class="literal">UNION</code>, <code class="literal">CASE</code>, and related constructs
+</span></dt><dd><p>
+Since all query results from a unionized <code class="command">SELECT</code> statement
+must appear in a single set of columns, the types of the results of each
+<code class="command">SELECT</code> clause must be matched up and converted to a uniform set.
+Similarly, the result expressions of a <code class="literal">CASE</code> construct must be
+converted to a common type so that the <code class="literal">CASE</code> expression as a whole
+has a known output type. Some other constructs, such
+as <code class="literal">ARRAY[]</code> and the <code class="function">GREATEST</code>
+and <code class="function">LEAST</code> functions, likewise require determination of a
+common type for several subexpressions.
+</p></dd></dl></div><p>
+</p><p>
+The system catalogs store information about which conversions, or
+<em class="firstterm">casts</em>, exist between which data types, and how to
+perform those conversions. Additional casts can be added by the user
+with the <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>
+command. (This is usually
+done in conjunction with defining new data types. The set of casts
+between built-in types has been carefully crafted and is best not
+altered.)
+</p><a id="id-1.5.9.6.6" class="indexterm"></a><p>
+An additional heuristic provided by the parser allows improved determination
+of the proper casting behavior among groups of types that have implicit casts.
+Data types are divided into several basic <em class="firstterm">type
+categories</em>, including <code class="type">boolean</code>, <code class="type">numeric</code>,
+<code class="type">string</code>, <code class="type">bitstring</code>, <code class="type">datetime</code>,
+<code class="type">timespan</code>, <code class="type">geometric</code>, <code class="type">network</code>, and
+user-defined. (For a list see <a class="xref" href="catalog-pg-type.html#CATALOG-TYPCATEGORY-TABLE" title="Table 53.65. typcategory Codes">Table 53.65</a>;
+but note it is also possible to create custom type categories.) Within each
+category there can be one or more <em class="firstterm">preferred types</em>, which
+are preferred when there is a choice of possible types. With careful selection
+of preferred types and available implicit casts, it is possible to ensure that
+ambiguous expressions (those with multiple candidate parsing solutions) can be
+resolved in a useful way.
+</p><p>
+All type conversion rules are designed with several principles in mind:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+Implicit conversions should never have surprising or unpredictable outcomes.
+</p></li><li class="listitem"><p>
+There should be no extra overhead in the parser or executor
+if a query does not need implicit type conversion.
+That is, if a query is well-formed and the types already match, then the query should execute
+without spending extra time in the parser and without introducing unnecessary implicit conversion
+calls in the query.
+</p></li><li class="listitem"><p>
+Additionally, if a query usually requires an implicit conversion for a function, and
+if then the user defines a new function with the correct argument types, the parser
+should use this new function and no longer do implicit conversion to use the old function.
+</p></li></ul></div><p>
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv.html" title="Chapter 10. Type Conversion">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-oper.html" title="10.2. Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. Type Conversion </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.2. Operators</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-query.html b/doc/src/sgml/html/typeconv-query.html
new file mode 100644
index 0000000..e33a03c
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-query.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.4. Value Storage</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-func.html" title="10.3. Functions" /><link rel="next" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.4. Value Storage</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-func.html" title="10.3. Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-QUERY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.4. Value Storage</h2></div></div></div><p>
+ Values to be inserted into a table are converted to the destination
+ column's data type according to the
+ following steps.
+ </p><div class="procedure" id="id-1.5.9.9.3"><p class="title"><strong>Value Storage Type Conversion</strong></p><ol class="procedure" type="1"><li class="step"><p>
+Check for an exact match with the target.
+</p></li><li class="step"><p>
+Otherwise, try to convert the expression to the target type. This is possible
+if an <em class="firstterm">assignment cast</em> between the two types is registered in the
+<code class="structname">pg_cast</code> catalog (see <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>).
+Alternatively, if the expression is an unknown-type literal, the contents of
+the literal string will be fed to the input conversion routine for the target
+type.
+</p></li><li class="step"><p>
+Check to see if there is a sizing cast for the target type. A sizing
+cast is a cast from that type to itself. If one is found in the
+<code class="structname">pg_cast</code> catalog, apply it to the expression before storing
+into the destination column. The implementation function for such a cast
+always takes an extra parameter of type <code class="type">integer</code>, which receives
+the destination column's <code class="structfield">atttypmod</code> value (typically its
+declared length, although the interpretation of <code class="structfield">atttypmod</code>
+varies for different data types), and it may take a third <code class="type">boolean</code>
+parameter that says whether the cast is explicit or implicit. The cast
+function
+is responsible for applying any length-dependent semantics such as size
+checking or truncation.
+</p></li></ol></div><div class="example" id="id-1.5.9.9.4"><p class="title"><strong>Example 10.9. <code class="type">character</code> Storage Type Conversion</strong></p><div class="example-contents"><p>
+For a target column declared as <code class="type">character(20)</code> the following
+statement shows that the stored value is sized correctly:
+
+</p><pre class="screen">
+CREATE TABLE vv (v character(20));
+INSERT INTO vv SELECT 'abc' || 'def';
+SELECT v, octet_length(v) FROM vv;
+
+ v | octet_length
+----------------------+--------------
+ abcdef | 20
+(1 row)
+</pre><p>
+</p><p>
+What has really happened here is that the two unknown literals are resolved
+to <code class="type">text</code> by default, allowing the <code class="literal">||</code> operator
+to be resolved as <code class="type">text</code> concatenation. Then the <code class="type">text</code>
+result of the operator is converted to <code class="type">bpchar</code> (<span class="quote">“<span class="quote">blank-padded
+char</span>”</span>, the internal name of the <code class="type">character</code> data type) to match the target
+column type. (Since the conversion from <code class="type">text</code> to
+<code class="type">bpchar</code> is binary-coercible, this conversion does
+not insert any real function call.) Finally, the sizing function
+<code class="literal">bpchar(bpchar, integer, boolean)</code> is found in the system catalog
+and applied to the operator's result and the stored column length. This
+type-specific function performs the required length check and addition of
+padding spaces.
+</p></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-func.html" title="10.3. Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.3. Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-select.html b/doc/src/sgml/html/typeconv-select.html
new file mode 100644
index 0000000..bf4d5d8
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-select.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.6. SELECT Output Columns</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs" /><link rel="next" href="indexes.html" title="Chapter 11. Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.6. <code class="literal">SELECT</code> Output Columns</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexes.html" title="Chapter 11. Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-SELECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.6. <code class="literal">SELECT</code> Output Columns</h2></div></div></div><a id="id-1.5.9.11.2" class="indexterm"></a><p>
+The rules given in the preceding sections will result in assignment
+of non-<code class="type">unknown</code> data types to all expressions in an SQL query,
+except for unspecified-type literals that appear as simple output
+columns of a <code class="command">SELECT</code> command. For example, in
+
+</p><pre class="screen">
+SELECT 'Hello World';
+</pre><p>
+
+there is nothing to identify what type the string literal should be
+taken as. In this situation <span class="productname">PostgreSQL</span> will fall back
+to resolving the literal's type as <code class="type">text</code>.
+</p><p>
+When the <code class="command">SELECT</code> is one arm of a <code class="literal">UNION</code>
+(or <code class="literal">INTERSECT</code> or <code class="literal">EXCEPT</code>) construct, or when it
+appears within <code class="command">INSERT ... SELECT</code>, this rule is not applied
+since rules given in preceding sections take precedence. The type of an
+unspecified-type literal can be taken from the other <code class="literal">UNION</code> arm
+in the first case, or from the destination column in the second case.
+</p><p>
+<code class="literal">RETURNING</code> lists are treated the same as <code class="command">SELECT</code>
+output lists for this purpose.
+</p><div class="note"><h3 class="title">Note</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> 10, this rule did not exist, and
+ unspecified-type literals in a <code class="command">SELECT</code> output list were
+ left as type <code class="type">unknown</code>. That had assorted bad consequences,
+ so it's been changed.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexes.html" title="Chapter 11. Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv-union-case.html b/doc/src/sgml/html/typeconv-union-case.html
new file mode 100644
index 0000000..93c451e
--- /dev/null
+++ b/doc/src/sgml/html/typeconv-union-case.html
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>10.5. UNION, CASE, and Related Constructs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="typeconv-query.html" title="10.4. Value Storage" /><link rel="next" href="typeconv-select.html" title="10.6. SELECT Output Columns" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="typeconv-query.html" title="10.4. Value Storage">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><th width="60%" align="center">Chapter 10. Type Conversion</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-select.html" title="10.6. SELECT Output Columns">Next</a></td></tr></table><hr /></div><div class="sect1" id="TYPECONV-UNION-CASE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs</h2></div></div></div><a id="id-1.5.9.10.2" class="indexterm"></a><a id="id-1.5.9.10.3" class="indexterm"></a><a id="id-1.5.9.10.4" class="indexterm"></a><a id="id-1.5.9.10.5" class="indexterm"></a><a id="id-1.5.9.10.6" class="indexterm"></a><a id="id-1.5.9.10.7" class="indexterm"></a><p>
+SQL <code class="literal">UNION</code> constructs must match up possibly dissimilar
+types to become a single result set. The resolution algorithm is
+applied separately to each output column of a union query. The
+<code class="literal">INTERSECT</code> and <code class="literal">EXCEPT</code> constructs resolve
+dissimilar types in the same way as <code class="literal">UNION</code>.
+Some other constructs, including
+<code class="literal">CASE</code>, <code class="literal">ARRAY</code>, <code class="literal">VALUES</code>,
+and the <code class="function">GREATEST</code> and <code class="function">LEAST</code>
+functions, use the identical
+algorithm to match up their component expressions and select a result
+data type.
+</p><div class="procedure" id="id-1.5.9.10.9"><p class="title"><strong>Type Resolution for <code class="literal">UNION</code>, <code class="literal">CASE</code>,
+and Related Constructs</strong></p><ol class="procedure" type="1"><li class="step"><p>
+If all inputs are of the same type, and it is not <code class="type">unknown</code>,
+resolve as that type.
+</p></li><li class="step"><p>
+If any input is of a domain type, treat it as being of the
+domain's base type for all subsequent steps.
+ <a href="#ftn.id-1.5.9.10.9.3.1.1" class="footnote"><sup class="footnote" id="id-1.5.9.10.9.3.1.1">[12]</sup></a>
+</p></li><li class="step"><p>
+If all inputs are of type <code class="type">unknown</code>, resolve as type
+<code class="type">text</code> (the preferred type of the string category).
+Otherwise, <code class="type">unknown</code> inputs are ignored for the purposes
+of the remaining rules.
+</p></li><li class="step"><p>
+If the non-unknown inputs are not all of the same type category, fail.
+</p></li><li class="step"><p>
+Select the first non-unknown input type as the candidate type,
+then consider each other non-unknown input type, left to right.
+ <a href="#ftn.id-1.5.9.10.9.6.1.1" class="footnote"><sup class="footnote" id="id-1.5.9.10.9.6.1.1">[13]</sup></a>
+If the candidate type can be implicitly converted to the other type,
+but not vice-versa, select the other type as the new candidate type.
+Then continue considering the remaining inputs. If, at any stage of this
+process, a preferred type is selected, stop considering additional
+inputs.
+</p></li><li class="step"><p>
+Convert all inputs to the final candidate type. Fail if there is not an
+implicit conversion from a given input type to the candidate type.
+</p></li></ol></div><p>
+Some examples follow.
+</p><div class="example" id="id-1.5.9.10.11"><p class="title"><strong>Example 10.10. Type Resolution with Underspecified Types in a Union</strong></p><div class="example-contents"><p>
+</p><pre class="screen">
+SELECT text 'a' AS "text" UNION SELECT 'b';
+
+ text
+------
+ a
+ b
+(2 rows)
+</pre><p>
+Here, the unknown-type literal <code class="literal">'b'</code> will be resolved to type <code class="type">text</code>.
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.10.12"><p class="title"><strong>Example 10.11. Type Resolution in a Simple Union</strong></p><div class="example-contents"><p>
+</p><pre class="screen">
+SELECT 1.2 AS "numeric" UNION SELECT 1;
+
+ numeric
+---------
+ 1
+ 1.2
+(2 rows)
+</pre><p>
+The literal <code class="literal">1.2</code> is of type <code class="type">numeric</code>,
+and the <code class="type">integer</code> value <code class="literal">1</code> can be cast implicitly to
+<code class="type">numeric</code>, so that type is used.
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.10.13"><p class="title"><strong>Example 10.12. Type Resolution in a Transposed Union</strong></p><div class="example-contents"><p>
+</p><pre class="screen">
+SELECT 1 AS "real" UNION SELECT CAST('2.2' AS REAL);
+
+ real
+------
+ 1
+ 2.2
+(2 rows)
+</pre><p>
+Here, since type <code class="type">real</code> cannot be implicitly cast to <code class="type">integer</code>,
+but <code class="type">integer</code> can be implicitly cast to <code class="type">real</code>, the union
+result type is resolved as <code class="type">real</code>.
+</p></div></div><br class="example-break" /><div class="example" id="id-1.5.9.10.14"><p class="title"><strong>Example 10.13. Type Resolution in a Nested Union</strong></p><div class="example-contents"><p>
+</p><pre class="screen">
+SELECT NULL UNION SELECT NULL UNION SELECT 1;
+
+ERROR: UNION types text and integer cannot be matched
+</pre><p>
+This failure occurs because <span class="productname">PostgreSQL</span> treats
+multiple <code class="literal">UNION</code>s as a nest of pairwise operations;
+that is, this input is the same as
+</p><pre class="screen">
+(SELECT NULL UNION SELECT NULL) UNION SELECT 1;
+</pre><p>
+The inner <code class="literal">UNION</code> is resolved as emitting
+type <code class="type">text</code>, according to the rules given above. Then the
+outer <code class="literal">UNION</code> has inputs of types <code class="type">text</code>
+and <code class="type">integer</code>, leading to the observed error. The problem
+can be fixed by ensuring that the leftmost <code class="literal">UNION</code>
+has at least one input of the desired result type.
+</p><p>
+<code class="literal">INTERSECT</code> and <code class="literal">EXCEPT</code> operations are
+likewise resolved pairwise. However, the other constructs described in this
+section consider all of their inputs in one resolution step.
+</p></div></div><br class="example-break" /><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.9.10.9.3.1.1" class="footnote"><p><a href="#id-1.5.9.10.9.3.1.1" class="para"><sup class="para">[12] </sup></a>
+ Somewhat like the treatment of domain inputs for operators and
+ functions, this behavior allows a domain type to be preserved through
+ a <code class="literal">UNION</code> or similar construct, so long as the user is
+ careful to ensure that all inputs are implicitly or explicitly of that
+ exact type. Otherwise the domain's base type will be used.
+ </p></div><div id="ftn.id-1.5.9.10.9.6.1.1" class="footnote"><p><a href="#id-1.5.9.10.9.6.1.1" class="para"><sup class="para">[13] </sup></a>
+ For historical reasons, <code class="literal">CASE</code> treats
+ its <code class="literal">ELSE</code> clause (if any) as the <span class="quote">“<span class="quote">first</span>”</span>
+ input, with the <code class="literal">THEN</code> clauses(s) considered after
+ that. In all other cases, <span class="quote">“<span class="quote">left to right</span>”</span> means the order
+ in which the expressions appear in the query text.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="typeconv-query.html" title="10.4. Value Storage">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="typeconv.html" title="Chapter 10. Type Conversion">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-select.html" title="10.6. SELECT Output Columns">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.4. Value Storage </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.6. <code class="literal">SELECT</code> Output Columns</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/typeconv.html b/doc/src/sgml/html/typeconv.html
new file mode 100644
index 0000000..c38f58d
--- /dev/null
+++ b/doc/src/sgml/html/typeconv.html
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 10. Type Conversion</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-statistics.html" title="9.30. Statistics Information Functions" /><link rel="next" href="typeconv-overview.html" title="10.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 10. Type Conversion</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-statistics.html" title="9.30. Statistics Information Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><th width="60%" align="center">Part II. The SQL Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="typeconv-overview.html" title="10.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="TYPECONV"><div class="titlepage"><div><div><h2 class="title">Chapter 10. Type Conversion</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="typeconv-overview.html">10.1. Overview</a></span></dt><dt><span class="sect1"><a href="typeconv-oper.html">10.2. Operators</a></span></dt><dt><span class="sect1"><a href="typeconv-func.html">10.3. Functions</a></span></dt><dt><span class="sect1"><a href="typeconv-query.html">10.4. Value Storage</a></span></dt><dt><span class="sect1"><a href="typeconv-union-case.html">10.5. <code class="literal">UNION</code>, <code class="literal">CASE</code>, and Related Constructs</a></span></dt><dt><span class="sect1"><a href="typeconv-select.html">10.6. <code class="literal">SELECT</code> Output Columns</a></span></dt></dl></div><a id="id-1.5.9.2" class="indexterm"></a><p>
+<acronym class="acronym">SQL</acronym> statements can, intentionally or not, require
+the mixing of different data types in the same expression.
+<span class="productname">PostgreSQL</span> has extensive facilities for
+evaluating mixed-type expressions.
+</p><p>
+In many cases a user does not need
+to understand the details of the type conversion mechanism.
+However, implicit conversions done by <span class="productname">PostgreSQL</span>
+can affect the results of a query. When necessary, these results
+can be tailored by using <span class="emphasis"><em>explicit</em></span> type conversion.
+</p><p>
+This chapter introduces the <span class="productname">PostgreSQL</span>
+type conversion mechanisms and conventions.
+Refer to the relevant sections in <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a> and <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>
+for more information on specific data types and allowed functions and
+operators.
+</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-statistics.html" title="9.30. Statistics Information Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql.html" title="Part II. The SQL Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="typeconv-overview.html" title="10.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.30. Statistics Information Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 10.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/unaccent.html b/doc/src/sgml/html/unaccent.html
new file mode 100644
index 0000000..79979cb
--- /dev/null
+++ b/doc/src/sgml/html/unaccent.html
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.48. unaccent</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="tsm-system-time.html" title="F.47. tsm_system_time" /><link rel="next" href="uuid-ossp.html" title="F.49. uuid-ossp" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.48. unaccent</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="tsm-system-time.html" title="F.47. tsm_system_time">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="uuid-ossp.html" title="F.49. uuid-ossp">Next</a></td></tr></table><hr /></div><div class="sect1" id="UNACCENT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.48. unaccent</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.6">F.48.1. Configuration</a></span></dt><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.7">F.48.2. Usage</a></span></dt><dt><span class="sect2"><a href="unaccent.html#id-1.11.7.57.8">F.48.3. Functions</a></span></dt></dl></div><a id="id-1.11.7.57.2" class="indexterm"></a><p>
+ <code class="filename">unaccent</code> is a text search dictionary that removes accents
+ (diacritic signs) from lexemes.
+ It's a filtering dictionary, which means its output is
+ always passed to the next dictionary (if any), unlike the normal
+ behavior of dictionaries. This allows accent-insensitive processing
+ for full text search.
+ </p><p>
+ The current implementation of <code class="filename">unaccent</code> cannot be used as a
+ normalizing dictionary for the <code class="filename">thesaurus</code> dictionary.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.57.6"><div class="titlepage"><div><div><h3 class="title">F.48.1. Configuration</h3></div></div></div><p>
+ An <code class="literal">unaccent</code> dictionary accepts the following options:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="literal">RULES</code> is the base name of the file containing the list of
+ translation rules. This file must be stored in
+ <code class="filename">$SHAREDIR/tsearch_data/</code> (where <code class="literal">$SHAREDIR</code> means
+ the <span class="productname">PostgreSQL</span> installation's shared-data directory).
+ Its name must end in <code class="literal">.rules</code> (which is not to be included in
+ the <code class="literal">RULES</code> parameter).
+ </p></li></ul></div><p>
+ The rules file has the following format:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Each line represents one translation rule, consisting of a character with
+ accent followed by a character without accent. The first is translated
+ into the second. For example,
+</p><pre class="programlisting">
+À A
+Á A
+Â A
+Ã A
+Ä A
+Å A
+Æ AE
+</pre><p>
+ The two characters must be separated by whitespace, and any leading or
+ trailing whitespace on a line is ignored.
+ </p></li><li class="listitem"><p>
+ Alternatively, if only one character is given on a line, instances of
+ that character are deleted; this is useful in languages where accents
+ are represented by separate characters.
+ </p></li><li class="listitem"><p>
+ Actually, each <span class="quote">“<span class="quote">character</span>”</span> can be any string not containing
+ whitespace, so <code class="filename">unaccent</code> dictionaries could be used for
+ other sorts of substring substitutions besides diacritic removal.
+ </p></li><li class="listitem"><p>
+ As with other <span class="productname">PostgreSQL</span> text search configuration files,
+ the rules file must be stored in UTF-8 encoding. The data is
+ automatically translated into the current database's encoding when
+ loaded. Any lines containing untranslatable characters are silently
+ ignored, so that rules files can contain rules that are not applicable in
+ the current encoding.
+ </p></li></ul></div><p>
+ A more complete example, which is directly useful for most European
+ languages, can be found in <code class="filename">unaccent.rules</code>, which is installed
+ in <code class="filename">$SHAREDIR/tsearch_data/</code> when the <code class="filename">unaccent</code>
+ module is installed. This rules file translates characters with accents
+ to the same characters without accents, and it also expands ligatures
+ into the equivalent series of simple characters (for example, Æ to
+ AE).
+ </p></div><div class="sect2" id="id-1.11.7.57.7"><div class="titlepage"><div><div><h3 class="title">F.48.2. Usage</h3></div></div></div><p>
+ Installing the <code class="literal">unaccent</code> extension creates a text
+ search template <code class="literal">unaccent</code> and a dictionary <code class="literal">unaccent</code>
+ based on it. The <code class="literal">unaccent</code> dictionary has the default
+ parameter setting <code class="literal">RULES='unaccent'</code>, which makes it immediately
+ usable with the standard <code class="filename">unaccent.rules</code> file.
+ If you wish, you can alter the parameter, for example
+
+</p><pre class="programlisting">
+mydb=# ALTER TEXT SEARCH DICTIONARY unaccent (RULES='my_rules');
+</pre><p>
+
+ or create new dictionaries based on the template.
+ </p><p>
+ To test the dictionary, you can try:
+</p><pre class="programlisting">
+mydb=# select ts_lexize('unaccent','Hôtel');
+ ts_lexize
+-----------
+ {Hotel}
+(1 row)
+</pre><p>
+ </p><p>
+ Here is an example showing how to insert the
+ <code class="filename">unaccent</code> dictionary into a text search configuration:
+</p><pre class="programlisting">
+mydb=# CREATE TEXT SEARCH CONFIGURATION fr ( COPY = french );
+mydb=# ALTER TEXT SEARCH CONFIGURATION fr
+ ALTER MAPPING FOR hword, hword_part, word
+ WITH unaccent, french_stem;
+mydb=# select to_tsvector('fr','Hôtels de la Mer');
+ to_tsvector
+-------------------
+ 'hotel':1 'mer':4
+(1 row)
+
+mydb=# select to_tsvector('fr','Hôtel de la Mer') @@ to_tsquery('fr','Hotels');
+ ?column?
+----------
+ t
+(1 row)
+
+mydb=# select ts_headline('fr','Hôtel de la Mer',to_tsquery('fr','Hotels'));
+ ts_headline
+------------------------
+ &lt;b&gt;Hôtel&lt;/b&gt; de la Mer
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.11.7.57.8"><div class="titlepage"><div><div><h3 class="title">F.48.3. Functions</h3></div></div></div><p>
+ The <code class="function">unaccent()</code> function removes accents (diacritic signs) from
+ a given string. Basically, it's a wrapper around
+ <code class="filename">unaccent</code>-type dictionaries, but it can be used outside normal
+ text search contexts.
+ </p><a id="id-1.11.7.57.8.3" class="indexterm"></a><pre class="synopsis">
+unaccent([<span class="optional"><em class="replaceable"><code>dictionary</code></em> <code class="type">regdictionary</code>, </span>] <em class="replaceable"><code>string</code></em> <code class="type">text</code>) returns <code class="type">text</code>
+</pre><p>
+ If the <em class="replaceable"><code>dictionary</code></em> argument is
+ omitted, the text search dictionary named <code class="literal">unaccent</code> and
+ appearing in the same schema as the <code class="function">unaccent()</code>
+ function itself is used.
+ </p><p>
+ For example:
+</p><pre class="programlisting">
+SELECT unaccent('unaccent', 'Hôtel');
+SELECT unaccent('Hôtel');
+</pre><p>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tsm-system-time.html" title="F.47. tsm_system_time">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="uuid-ossp.html" title="F.49. uuid-ossp">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.47. tsm_system_time </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.49. uuid-ossp</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/unsupported-features-sql-standard.html b/doc/src/sgml/html/unsupported-features-sql-standard.html
new file mode 100644
index 0000000..8754274
--- /dev/null
+++ b/doc/src/sgml/html/unsupported-features-sql-standard.html
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>D.2. Unsupported Features</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="features-sql-standard.html" title="D.1. Supported Features" /><link rel="next" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">D.2. Unsupported Features</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="features-sql-standard.html" title="D.1. Supported Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><th width="60%" align="center">Appendix D. SQL Conformance</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Next</a></td></tr></table><hr /></div><div class="sect1" id="UNSUPPORTED-FEATURES-SQL-STANDARD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">D.2. Unsupported Features</h2></div></div></div><p>
+ The following features defined in <acronym class="acronym">SQL:2016</acronym> are not
+ implemented in this release of
+ <span class="productname">PostgreSQL</span>. In a few cases, equivalent
+ functionality is available.
+
+ </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /></colgroup><thead><tr><th>Identifier</th><th>Core?</th><th>Description</th><th>Comment</th></tr></thead><tbody><tr><td>B011</td><td> </td><td>Embedded Ada</td><td> </td></tr><tr><td>B013</td><td> </td><td>Embedded COBOL</td><td> </td></tr><tr><td>B014</td><td> </td><td>Embedded Fortran</td><td> </td></tr><tr><td>B015</td><td> </td><td>Embedded MUMPS</td><td> </td></tr><tr><td>B016</td><td> </td><td>Embedded Pascal</td><td> </td></tr><tr><td>B017</td><td> </td><td>Embedded PL/I</td><td> </td></tr><tr><td>B031</td><td> </td><td>Basic dynamic SQL</td><td> </td></tr><tr><td>B032</td><td> </td><td>Extended dynamic SQL</td><td> </td></tr><tr><td>B032-01</td><td> </td><td>&lt;describe input statement&gt;</td><td> </td></tr><tr><td>B033</td><td> </td><td>Untyped SQL-invoked function arguments</td><td> </td></tr><tr><td>B034</td><td> </td><td>Dynamic specification of cursor attributes</td><td> </td></tr><tr><td>B035</td><td> </td><td>Non-extended descriptor names</td><td> </td></tr><tr><td>B041</td><td> </td><td>Extensions to embedded SQL exception declarations</td><td> </td></tr><tr><td>B051</td><td> </td><td>Enhanced execution rights</td><td> </td></tr><tr><td>B111</td><td> </td><td>Module language Ada</td><td> </td></tr><tr><td>B112</td><td> </td><td>Module language C</td><td> </td></tr><tr><td>B113</td><td> </td><td>Module language COBOL</td><td> </td></tr><tr><td>B114</td><td> </td><td>Module language Fortran</td><td> </td></tr><tr><td>B115</td><td> </td><td>Module language MUMPS</td><td> </td></tr><tr><td>B116</td><td> </td><td>Module language Pascal</td><td> </td></tr><tr><td>B117</td><td> </td><td>Module language PL/I</td><td> </td></tr><tr><td>B121</td><td> </td><td>Routine language Ada</td><td> </td></tr><tr><td>B122</td><td> </td><td>Routine language C</td><td> </td></tr><tr><td>B123</td><td> </td><td>Routine language COBOL</td><td> </td></tr><tr><td>B124</td><td> </td><td>Routine language Fortran</td><td> </td></tr><tr><td>B125</td><td> </td><td>Routine language MUMPS</td><td> </td></tr><tr><td>B126</td><td> </td><td>Routine language Pascal</td><td> </td></tr><tr><td>B127</td><td> </td><td>Routine language PL/I</td><td> </td></tr><tr><td>B200</td><td> </td><td>Polymorphic table functions</td><td> </td></tr><tr><td>B201</td><td> </td><td>More than one PTF generic table parameter</td><td> </td></tr><tr><td>B202</td><td> </td><td>PTF Copartitioning</td><td> </td></tr><tr><td>B203</td><td> </td><td>More than one copartition specification</td><td> </td></tr><tr><td>B204</td><td> </td><td>PRUNE WHEN EMPTY</td><td> </td></tr><tr><td>B205</td><td> </td><td>Pass-through columns</td><td> </td></tr><tr><td>B206</td><td> </td><td>PTF descriptor parameters</td><td> </td></tr><tr><td>B207</td><td> </td><td>Cross products of partitionings</td><td> </td></tr><tr><td>B208</td><td> </td><td>PTF component procedure interface</td><td> </td></tr><tr><td>B209</td><td> </td><td>PTF extended names</td><td> </td></tr><tr><td>B211</td><td> </td><td>Module language Ada: VARCHAR and NUMERIC support</td><td> </td></tr><tr><td>B221</td><td> </td><td>Routine language Ada: VARCHAR and NUMERIC support</td><td> </td></tr><tr><td>F054</td><td> </td><td>TIMESTAMP in DATE type precedence list</td><td> </td></tr><tr><td>F121</td><td> </td><td>Basic diagnostics management</td><td> </td></tr><tr><td>F121-01</td><td> </td><td>GET DIAGNOSTICS statement</td><td> </td></tr><tr><td>F121-02</td><td> </td><td>SET TRANSACTION statement: DIAGNOSTICS SIZE clause</td><td> </td></tr><tr><td>F122</td><td> </td><td>Enhanced diagnostics management</td><td> </td></tr><tr><td>F123</td><td> </td><td>All diagnostics</td><td> </td></tr><tr><td>F263</td><td> </td><td>Comma-separated predicates in simple CASE expression</td><td> </td></tr><tr><td>F291</td><td> </td><td>UNIQUE predicate</td><td> </td></tr><tr><td>F301</td><td> </td><td>CORRESPONDING in query expressions</td><td> </td></tr><tr><td>F403</td><td> </td><td>Partitioned joined tables</td><td> </td></tr><tr><td>F451</td><td> </td><td>Character set definition</td><td> </td></tr><tr><td>F461</td><td> </td><td>Named character sets</td><td> </td></tr><tr><td>F492</td><td> </td><td>Optional table constraint enforcement</td><td> </td></tr><tr><td>F521</td><td> </td><td>Assertions</td><td> </td></tr><tr><td>F671</td><td> </td><td>Subqueries in CHECK</td><td>intentionally omitted</td></tr><tr><td>F673</td><td> </td><td>Reads SQL-data routine invocations in CHECK constraints</td><td> </td></tr><tr><td>F693</td><td> </td><td>SQL-session and client module collations</td><td> </td></tr><tr><td>F695</td><td> </td><td>Translation support</td><td> </td></tr><tr><td>F696</td><td> </td><td>Additional translation documentation</td><td> </td></tr><tr><td>F721</td><td> </td><td>Deferrable constraints</td><td>foreign and unique keys only</td></tr><tr><td>F741</td><td> </td><td>Referential MATCH types</td><td>no partial match yet</td></tr><tr><td>F812</td><td>Core</td><td>Basic flagging</td><td> </td></tr><tr><td>F813</td><td> </td><td>Extended flagging</td><td> </td></tr><tr><td>F821</td><td> </td><td>Local table references</td><td> </td></tr><tr><td>F831</td><td> </td><td>Full cursor update</td><td> </td></tr><tr><td>F831-01</td><td> </td><td>Updatable scrollable cursors</td><td> </td></tr><tr><td>F831-02</td><td> </td><td>Updatable ordered cursors</td><td> </td></tr><tr><td>F841</td><td> </td><td>LIKE_REGEX predicate</td><td>consider regexp_like()</td></tr><tr><td>F842</td><td> </td><td>OCCURRENCES_REGEX function</td><td>consider regexp_matches()</td></tr><tr><td>F843</td><td> </td><td>POSITION_REGEX function</td><td>consider regexp_instr()</td></tr><tr><td>F844</td><td> </td><td>SUBSTRING_REGEX function</td><td>consider regexp_substr()</td></tr><tr><td>F845</td><td> </td><td>TRANSLATE_REGEX function</td><td>consider regexp_replace()</td></tr><tr><td>F846</td><td> </td><td>Octet support in regular expression operators</td><td> </td></tr><tr><td>F847</td><td> </td><td>Nonconstant regular expressions</td><td> </td></tr><tr><td>F866</td><td> </td><td>FETCH FIRST clause: PERCENT option</td><td> </td></tr><tr><td>R010</td><td> </td><td>Row pattern recognition: FROM clause</td><td> </td></tr><tr><td>R020</td><td> </td><td>Row pattern recognition: WINDOW clause</td><td> </td></tr><tr><td>R030</td><td> </td><td>Row pattern recognition: full aggregate support</td><td> </td></tr><tr><td>S011</td><td>Core</td><td>Distinct data types</td><td> </td></tr><tr><td>S011-01</td><td>Core</td><td>USER_DEFINED_TYPES view</td><td> </td></tr><tr><td>S023</td><td> </td><td>Basic structured types</td><td> </td></tr><tr><td>S024</td><td> </td><td>Enhanced structured types</td><td> </td></tr><tr><td>S025</td><td> </td><td>Final structured types</td><td> </td></tr><tr><td>S026</td><td> </td><td>Self-referencing structured types</td><td> </td></tr><tr><td>S027</td><td> </td><td>Create method by specific method name</td><td> </td></tr><tr><td>S028</td><td> </td><td>Permutable UDT options list</td><td> </td></tr><tr><td>S041</td><td> </td><td>Basic reference types</td><td> </td></tr><tr><td>S043</td><td> </td><td>Enhanced reference types</td><td> </td></tr><tr><td>S051</td><td> </td><td>Create table of type</td><td>partially supported</td></tr><tr><td>S081</td><td> </td><td>Subtables</td><td> </td></tr><tr><td>S091</td><td> </td><td>Basic array support</td><td>partially supported</td></tr><tr><td>S091-02</td><td> </td><td>Arrays of distinct types</td><td> </td></tr><tr><td>S094</td><td> </td><td>Arrays of reference types</td><td> </td></tr><tr><td>S097</td><td> </td><td>Array element assignment</td><td> </td></tr><tr><td>S151</td><td> </td><td>Type predicate</td><td>see pg_typeof()</td></tr><tr><td>S161</td><td> </td><td>Subtype treatment</td><td> </td></tr><tr><td>S162</td><td> </td><td>Subtype treatment for references</td><td> </td></tr><tr><td>S202</td><td> </td><td>SQL-invoked routines on multisets</td><td> </td></tr><tr><td>S231</td><td> </td><td>Structured type locators</td><td> </td></tr><tr><td>S232</td><td> </td><td>Array locators</td><td> </td></tr><tr><td>S233</td><td> </td><td>Multiset locators</td><td> </td></tr><tr><td>S241</td><td> </td><td>Transform functions</td><td> </td></tr><tr><td>S242</td><td> </td><td>Alter transform statement</td><td> </td></tr><tr><td>S251</td><td> </td><td>User-defined orderings</td><td> </td></tr><tr><td>S261</td><td> </td><td>Specific type method</td><td> </td></tr><tr><td>S271</td><td> </td><td>Basic multiset support</td><td> </td></tr><tr><td>S272</td><td> </td><td>Multisets of user-defined types</td><td> </td></tr><tr><td>S274</td><td> </td><td>Multisets of reference types</td><td> </td></tr><tr><td>S275</td><td> </td><td>Advanced multiset support</td><td> </td></tr><tr><td>S281</td><td> </td><td>Nested collection types</td><td> </td></tr><tr><td>S291</td><td> </td><td>Unique constraint on entire row</td><td> </td></tr><tr><td>S401</td><td> </td><td>Distinct types based on array types</td><td> </td></tr><tr><td>S402</td><td> </td><td>Distinct types based on distinct types</td><td> </td></tr><tr><td>S403</td><td> </td><td>ARRAY_MAX_CARDINALITY</td><td> </td></tr><tr><td>T011</td><td> </td><td>Timestamp in Information Schema</td><td> </td></tr><tr><td>T021</td><td> </td><td>BINARY and VARBINARY data types</td><td> </td></tr><tr><td>T022</td><td> </td><td>Advanced support for BINARY and VARBINARY data types</td><td> </td></tr><tr><td>T023</td><td> </td><td>Compound binary literal</td><td> </td></tr><tr><td>T024</td><td> </td><td>Spaces in binary literals</td><td> </td></tr><tr><td>T041</td><td> </td><td>Basic LOB data type support</td><td> </td></tr><tr><td>T041-01</td><td> </td><td>BLOB data type</td><td> </td></tr><tr><td>T041-02</td><td> </td><td>CLOB data type</td><td> </td></tr><tr><td>T041-03</td><td> </td><td>POSITION, LENGTH, LOWER, TRIM, UPPER, and SUBSTRING functions for LOB data types</td><td> </td></tr><tr><td>T041-04</td><td> </td><td>Concatenation of LOB data types</td><td> </td></tr><tr><td>T041-05</td><td> </td><td>LOB locator: non-holdable</td><td> </td></tr><tr><td>T042</td><td> </td><td>Extended LOB data type support</td><td> </td></tr><tr><td>T043</td><td> </td><td>Multiplier T</td><td> </td></tr><tr><td>T044</td><td> </td><td>Multiplier P</td><td> </td></tr><tr><td>T051</td><td> </td><td>Row types</td><td> </td></tr><tr><td>T053</td><td> </td><td>Explicit aliases for all-fields reference</td><td> </td></tr><tr><td>T061</td><td> </td><td>UCS support</td><td> </td></tr><tr><td>T076</td><td> </td><td>DECFLOAT data type</td><td> </td></tr><tr><td>T101</td><td> </td><td>Enhanced nullability determination</td><td> </td></tr><tr><td>T111</td><td> </td><td>Updatable joins, unions, and columns</td><td> </td></tr><tr><td>T175</td><td> </td><td>Generated columns</td><td>mostly supported</td></tr><tr><td>T176</td><td> </td><td>Sequence generator support</td><td>supported except for NEXT VALUE FOR</td></tr><tr><td>T180</td><td> </td><td>System-versioned tables</td><td> </td></tr><tr><td>T181</td><td> </td><td>Application-time period tables</td><td> </td></tr><tr><td>T211</td><td> </td><td>Basic trigger capability</td><td> </td></tr><tr><td>T211-06</td><td> </td><td>Support for run-time rules for the interaction of triggers and constraints</td><td> </td></tr><tr><td>T211-08</td><td> </td><td>Multiple triggers for the same event are executed in the order in which they were created in the catalog</td><td>intentionally omitted</td></tr><tr><td>T231</td><td> </td><td>Sensitive cursors</td><td> </td></tr><tr><td>T251</td><td> </td><td>SET TRANSACTION statement: LOCAL option</td><td> </td></tr><tr><td>T272</td><td> </td><td>Enhanced savepoint management</td><td> </td></tr><tr><td>T301</td><td> </td><td>Functional dependencies</td><td>partially supported</td></tr><tr><td>T321</td><td>Core</td><td>Basic SQL-invoked routines</td><td>partially supported</td></tr><tr><td>T322</td><td> </td><td>Declared data type attributes</td><td> </td></tr><tr><td>T324</td><td> </td><td>Explicit security for SQL routines</td><td> </td></tr><tr><td>T326</td><td> </td><td>Table functions</td><td> </td></tr><tr><td>T471</td><td> </td><td>Result sets return value</td><td> </td></tr><tr><td>T472</td><td> </td><td>DESCRIBE CURSOR</td><td> </td></tr><tr><td>T495</td><td> </td><td>Combined data change and retrieval</td><td>different syntax</td></tr><tr><td>T502</td><td> </td><td>Period predicates</td><td> </td></tr><tr><td>T511</td><td> </td><td>Transaction counts</td><td> </td></tr><tr><td>T522</td><td> </td><td>Default values for IN parameters of SQL-invoked procedures</td><td>supported except DEFAULT key word in invocation</td></tr><tr><td>T561</td><td> </td><td>Holdable locators</td><td> </td></tr><tr><td>T571</td><td> </td><td>Array-returning external SQL-invoked functions</td><td> </td></tr><tr><td>T572</td><td> </td><td>Multiset-returning external SQL-invoked functions</td><td> </td></tr><tr><td>T601</td><td> </td><td>Local cursor references</td><td> </td></tr><tr><td>T616</td><td> </td><td>Null treatment option for LEAD and LAG functions</td><td> </td></tr><tr><td>T618</td><td> </td><td>NTH_VALUE function</td><td>function exists, but some options missing</td></tr><tr><td>T619</td><td> </td><td>Nested window functions</td><td> </td></tr><tr><td>T625</td><td> </td><td>LISTAGG</td><td> </td></tr><tr><td>T641</td><td> </td><td>Multiple column assignment</td><td>only some syntax variants supported</td></tr><tr><td>T652</td><td> </td><td>SQL-dynamic statements in SQL routines</td><td> </td></tr><tr><td>T654</td><td> </td><td>SQL-dynamic statements in external routines</td><td> </td></tr><tr><td>T811</td><td> </td><td>Basic SQL/JSON constructor functions</td><td> </td></tr><tr><td>T812</td><td> </td><td>SQL/JSON: JSON_OBJECTAGG</td><td> </td></tr><tr><td>T813</td><td> </td><td>SQL/JSON: JSON_ARRAYAGG with ORDER BY</td><td> </td></tr><tr><td>T814</td><td> </td><td>Colon in JSON_OBJECT or JSON_OBJECTAGG</td><td> </td></tr><tr><td>T821</td><td> </td><td>Basic SQL/JSON query operators</td><td> </td></tr><tr><td>T822</td><td> </td><td>SQL/JSON: IS JSON WITH UNIQUE KEYS predicate</td><td> </td></tr><tr><td>T823</td><td> </td><td>SQL/JSON: PASSING clause</td><td> </td></tr><tr><td>T824</td><td> </td><td>JSON_TABLE: specific PLAN clause</td><td> </td></tr><tr><td>T825</td><td> </td><td>SQL/JSON: ON EMPTY and ON ERROR clauses</td><td> </td></tr><tr><td>T826</td><td> </td><td>General value expression in ON ERROR or ON EMPTY clauses</td><td> </td></tr><tr><td>T827</td><td> </td><td>JSON_TABLE: sibling NESTED COLUMNS clauses</td><td> </td></tr><tr><td>T828</td><td> </td><td>JSON_QUERY</td><td> </td></tr><tr><td>T829</td><td> </td><td>JSON_QUERY: array wrapper options</td><td> </td></tr><tr><td>T830</td><td> </td><td>Enforcing unique keys in SQL/JSON constructor functions</td><td> </td></tr><tr><td>T838</td><td> </td><td>JSON_TABLE: PLAN DEFAULT clause</td><td> </td></tr><tr><td>T839</td><td> </td><td>Formatted cast of datetimes to/from character strings</td><td> </td></tr><tr><td>M001</td><td> </td><td>Datalinks</td><td> </td></tr><tr><td>M002</td><td> </td><td>Datalinks via SQL/CLI</td><td> </td></tr><tr><td>M003</td><td> </td><td>Datalinks via Embedded SQL</td><td> </td></tr><tr><td>M004</td><td> </td><td>Foreign data support</td><td>partially supported</td></tr><tr><td>M005</td><td> </td><td>Foreign schema support</td><td> </td></tr><tr><td>M006</td><td> </td><td>GetSQLString routine</td><td> </td></tr><tr><td>M007</td><td> </td><td>TransmitRequest</td><td> </td></tr><tr><td>M009</td><td> </td><td>GetOpts and GetStatistics routines</td><td> </td></tr><tr><td>M010</td><td> </td><td>Foreign data wrapper support</td><td>different API</td></tr><tr><td>M011</td><td> </td><td>Datalinks via Ada</td><td> </td></tr><tr><td>M012</td><td> </td><td>Datalinks via C</td><td> </td></tr><tr><td>M013</td><td> </td><td>Datalinks via COBOL</td><td> </td></tr><tr><td>M014</td><td> </td><td>Datalinks via Fortran</td><td> </td></tr><tr><td>M015</td><td> </td><td>Datalinks via M</td><td> </td></tr><tr><td>M016</td><td> </td><td>Datalinks via Pascal</td><td> </td></tr><tr><td>M017</td><td> </td><td>Datalinks via PL/I</td><td> </td></tr><tr><td>M018</td><td> </td><td>Foreign data wrapper interface routines in Ada</td><td> </td></tr><tr><td>M019</td><td> </td><td>Foreign data wrapper interface routines in C</td><td>different API</td></tr><tr><td>M020</td><td> </td><td>Foreign data wrapper interface routines in COBOL</td><td> </td></tr><tr><td>M021</td><td> </td><td>Foreign data wrapper interface routines in Fortran</td><td> </td></tr><tr><td>M022</td><td> </td><td>Foreign data wrapper interface routines in MUMPS</td><td> </td></tr><tr><td>M023</td><td> </td><td>Foreign data wrapper interface routines in Pascal</td><td> </td></tr><tr><td>M024</td><td> </td><td>Foreign data wrapper interface routines in PL/I</td><td> </td></tr><tr><td>M030</td><td> </td><td>SQL-server foreign data support</td><td> </td></tr><tr><td>M031</td><td> </td><td>Foreign data wrapper general routines</td><td> </td></tr><tr><td>X012</td><td> </td><td>Multisets of XML type</td><td> </td></tr><tr><td>X013</td><td> </td><td>Distinct types of XML type</td><td> </td></tr><tr><td>X015</td><td> </td><td>Fields of XML type</td><td> </td></tr><tr><td>X025</td><td> </td><td>XMLCast</td><td> </td></tr><tr><td>X030</td><td> </td><td>XMLDocument</td><td> </td></tr><tr><td>X038</td><td> </td><td>XMLText</td><td> </td></tr><tr><td>X065</td><td> </td><td>XMLParse: BLOB input and CONTENT option</td><td> </td></tr><tr><td>X066</td><td> </td><td>XMLParse: BLOB input and DOCUMENT option</td><td> </td></tr><tr><td>X068</td><td> </td><td>XMLSerialize: BOM</td><td> </td></tr><tr><td>X069</td><td> </td><td>XMLSerialize: INDENT</td><td> </td></tr><tr><td>X073</td><td> </td><td>XMLSerialize: BLOB serialization and CONTENT option</td><td> </td></tr><tr><td>X074</td><td> </td><td>XMLSerialize: BLOB serialization and DOCUMENT option</td><td> </td></tr><tr><td>X075</td><td> </td><td>XMLSerialize: BLOB serialization</td><td> </td></tr><tr><td>X076</td><td> </td><td>XMLSerialize: VERSION</td><td> </td></tr><tr><td>X077</td><td> </td><td>XMLSerialize: explicit ENCODING option</td><td> </td></tr><tr><td>X078</td><td> </td><td>XMLSerialize: explicit XML declaration</td><td> </td></tr><tr><td>X080</td><td> </td><td>Namespaces in XML publishing</td><td> </td></tr><tr><td>X081</td><td> </td><td>Query-level XML namespace declarations</td><td> </td></tr><tr><td>X082</td><td> </td><td>XML namespace declarations in DML</td><td> </td></tr><tr><td>X083</td><td> </td><td>XML namespace declarations in DDL</td><td> </td></tr><tr><td>X084</td><td> </td><td>XML namespace declarations in compound statements</td><td> </td></tr><tr><td>X085</td><td> </td><td>Predefined namespace prefixes</td><td> </td></tr><tr><td>X086</td><td> </td><td>XML namespace declarations in XMLTable</td><td> </td></tr><tr><td>X091</td><td> </td><td>XML content predicate</td><td> </td></tr><tr><td>X096</td><td> </td><td>XMLExists</td><td>XPath 1.0 only</td></tr><tr><td>X100</td><td> </td><td>Host language support for XML: CONTENT option</td><td> </td></tr><tr><td>X101</td><td> </td><td>Host language support for XML: DOCUMENT option</td><td> </td></tr><tr><td>X110</td><td> </td><td>Host language support for XML: VARCHAR mapping</td><td> </td></tr><tr><td>X111</td><td> </td><td>Host language support for XML: CLOB mapping</td><td> </td></tr><tr><td>X112</td><td> </td><td>Host language support for XML: BLOB mapping</td><td> </td></tr><tr><td>X113</td><td> </td><td>Host language support for XML: STRIP WHITESPACE option</td><td> </td></tr><tr><td>X114</td><td> </td><td>Host language support for XML: PRESERVE WHITESPACE option</td><td> </td></tr><tr><td>X131</td><td> </td><td>Query-level XMLBINARY clause</td><td> </td></tr><tr><td>X132</td><td> </td><td>XMLBINARY clause in DML</td><td> </td></tr><tr><td>X133</td><td> </td><td>XMLBINARY clause in DDL</td><td> </td></tr><tr><td>X134</td><td> </td><td>XMLBINARY clause in compound statements</td><td> </td></tr><tr><td>X135</td><td> </td><td>XMLBINARY clause in subqueries</td><td> </td></tr><tr><td>X141</td><td> </td><td>IS VALID predicate: data-driven case</td><td> </td></tr><tr><td>X142</td><td> </td><td>IS VALID predicate: ACCORDING TO clause</td><td> </td></tr><tr><td>X143</td><td> </td><td>IS VALID predicate: ELEMENT clause</td><td> </td></tr><tr><td>X144</td><td> </td><td>IS VALID predicate: schema location</td><td> </td></tr><tr><td>X145</td><td> </td><td>IS VALID predicate outside check constraints</td><td> </td></tr><tr><td>X151</td><td> </td><td>IS VALID predicate with DOCUMENT option</td><td> </td></tr><tr><td>X152</td><td> </td><td>IS VALID predicate with CONTENT option</td><td> </td></tr><tr><td>X153</td><td> </td><td>IS VALID predicate with SEQUENCE option</td><td> </td></tr><tr><td>X155</td><td> </td><td>IS VALID predicate: NAMESPACE without ELEMENT clause</td><td> </td></tr><tr><td>X157</td><td> </td><td>IS VALID predicate: NO NAMESPACE with ELEMENT clause</td><td> </td></tr><tr><td>X160</td><td> </td><td>Basic Information Schema for registered XML Schemas</td><td> </td></tr><tr><td>X161</td><td> </td><td>Advanced Information Schema for registered XML Schemas</td><td> </td></tr><tr><td>X170</td><td> </td><td>XML null handling options</td><td> </td></tr><tr><td>X171</td><td> </td><td>NIL ON NO CONTENT option</td><td> </td></tr><tr><td>X181</td><td> </td><td>XML(DOCUMENT(UNTYPED)) type</td><td> </td></tr><tr><td>X182</td><td> </td><td>XML(DOCUMENT(ANY)) type</td><td> </td></tr><tr><td>X190</td><td> </td><td>XML(SEQUENCE) type</td><td> </td></tr><tr><td>X191</td><td> </td><td>XML(DOCUMENT(XMLSCHEMA)) type</td><td> </td></tr><tr><td>X192</td><td> </td><td>XML(CONTENT(XMLSCHEMA)) type</td><td> </td></tr><tr><td>X200</td><td> </td><td>XMLQuery</td><td> </td></tr><tr><td>X201</td><td> </td><td>XMLQuery: RETURNING CONTENT</td><td> </td></tr><tr><td>X202</td><td> </td><td>XMLQuery: RETURNING SEQUENCE</td><td> </td></tr><tr><td>X203</td><td> </td><td>XMLQuery: passing a context item</td><td> </td></tr><tr><td>X204</td><td> </td><td>XMLQuery: initializing an XQuery variable</td><td> </td></tr><tr><td>X205</td><td> </td><td>XMLQuery: EMPTY ON EMPTY option</td><td> </td></tr><tr><td>X206</td><td> </td><td>XMLQuery: NULL ON EMPTY option</td><td> </td></tr><tr><td>X211</td><td> </td><td>XML 1.1 support</td><td> </td></tr><tr><td>X222</td><td> </td><td>XML passing mechanism BY REF</td><td>parser accepts BY REF but ignores it; passing is always BY VALUE</td></tr><tr><td>X231</td><td> </td><td>XML(CONTENT(UNTYPED)) type</td><td> </td></tr><tr><td>X232</td><td> </td><td>XML(CONTENT(ANY)) type</td><td> </td></tr><tr><td>X241</td><td> </td><td>RETURNING CONTENT in XML publishing</td><td> </td></tr><tr><td>X242</td><td> </td><td>RETURNING SEQUENCE in XML publishing</td><td> </td></tr><tr><td>X251</td><td> </td><td>Persistent XML values of XML(DOCUMENT(UNTYPED)) type</td><td> </td></tr><tr><td>X252</td><td> </td><td>Persistent XML values of XML(DOCUMENT(ANY)) type</td><td> </td></tr><tr><td>X253</td><td> </td><td>Persistent XML values of XML(CONTENT(UNTYPED)) type</td><td> </td></tr><tr><td>X254</td><td> </td><td>Persistent XML values of XML(CONTENT(ANY)) type</td><td> </td></tr><tr><td>X255</td><td> </td><td>Persistent XML values of XML(SEQUENCE) type</td><td> </td></tr><tr><td>X256</td><td> </td><td>Persistent XML values of XML(DOCUMENT(XMLSCHEMA)) type</td><td> </td></tr><tr><td>X257</td><td> </td><td>Persistent XML values of XML(CONTENT(XMLSCHEMA)) type</td><td> </td></tr><tr><td>X260</td><td> </td><td>XML type: ELEMENT clause</td><td> </td></tr><tr><td>X261</td><td> </td><td>XML type: NAMESPACE without ELEMENT clause</td><td> </td></tr><tr><td>X263</td><td> </td><td>XML type: NO NAMESPACE with ELEMENT clause</td><td> </td></tr><tr><td>X264</td><td> </td><td>XML type: schema location</td><td> </td></tr><tr><td>X271</td><td> </td><td>XMLValidate: data-driven case</td><td> </td></tr><tr><td>X272</td><td> </td><td>XMLValidate: ACCORDING TO clause</td><td> </td></tr><tr><td>X273</td><td> </td><td>XMLValidate: ELEMENT clause</td><td> </td></tr><tr><td>X274</td><td> </td><td>XMLValidate: schema location</td><td> </td></tr><tr><td>X281</td><td> </td><td>XMLValidate with DOCUMENT option</td><td> </td></tr><tr><td>X282</td><td> </td><td>XMLValidate with CONTENT option</td><td> </td></tr><tr><td>X283</td><td> </td><td>XMLValidate with SEQUENCE option</td><td> </td></tr><tr><td>X284</td><td> </td><td>XMLValidate: NAMESPACE without ELEMENT clause</td><td> </td></tr><tr><td>X286</td><td> </td><td>XMLValidate: NO NAMESPACE with ELEMENT clause</td><td> </td></tr><tr><td>X300</td><td> </td><td>XMLTable</td><td>XPath 1.0 only</td></tr><tr><td>X305</td><td> </td><td>XMLTable: initializing an XQuery variable</td><td> </td></tr></tbody></table></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="features-sql-standard.html" title="D.1. Supported Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Next</a></td></tr><tr><td width="40%" align="left" valign="top">D.1. Supported Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> D.3. XML Limits and Conformance to SQL/XML</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/upgrading.html b/doc/src/sgml/html/upgrading.html
new file mode 100644
index 0000000..7cb184b
--- /dev/null
+++ b/doc/src/sgml/html/upgrading.html
@@ -0,0 +1,195 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.6. Upgrading a PostgreSQL Cluster</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="server-shutdown.html" title="19.5. Shutting Down the Server" /><link rel="next" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="server-shutdown.html" title="19.5. Shutting Down the Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 19. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing">Next</a></td></tr></table><hr /></div><div class="sect1" id="UPGRADING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PGDUMPALL">19.6.1. Upgrading Data via <span class="application">pg_dumpall</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PG-UPGRADE">19.6.2. Upgrading Data via <span class="application">pg_upgrade</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-REPLICATION">19.6.3. Upgrading Data via Replication</a></span></dt></dl></div><a id="id-1.6.6.9.2" class="indexterm"></a><a id="id-1.6.6.9.3" class="indexterm"></a><p>
+ This section discusses how to upgrade your database data from one
+ <span class="productname">PostgreSQL</span> release to a newer one.
+ </p><p>
+ Current <span class="productname">PostgreSQL</span> version numbers consist of a
+ major and a minor version number. For example, in the version number 10.1,
+ the 10 is the major version number and the 1 is the minor version number,
+ meaning this would be the first minor release of the major release 10. For
+ releases before <span class="productname">PostgreSQL</span> version 10.0, version
+ numbers consist of three numbers, for example, 9.5.3. In those cases, the
+ major version consists of the first two digit groups of the version number,
+ e.g., 9.5, and the minor version is the third number, e.g., 3, meaning this
+ would be the third minor release of the major release 9.5.
+ </p><p>
+ Minor releases never change the internal storage format and are always
+ compatible with earlier and later minor releases of the same major version
+ number. For example, version 10.1 is compatible with version 10.0 and
+ version 10.6. Similarly, for example, 9.5.3 is compatible with 9.5.0,
+ 9.5.1, and 9.5.6. To update between compatible versions, you simply
+ replace the executables while the server is down and restart the server.
+ The data directory remains unchanged — minor upgrades are that
+ simple.
+ </p><p>
+ For <span class="emphasis"><em>major</em></span> releases of <span class="productname">PostgreSQL</span>, the
+ internal data storage format is subject to change, thus complicating
+ upgrades. The traditional method for moving data to a new major version
+ is to dump and restore the database, though this can be slow. A
+ faster method is <a class="xref" href="pgupgrade.html" title="pg_upgrade"><span class="refentrytitle"><span class="application">pg_upgrade</span></span></a>. Replication methods are
+ also available, as discussed below.
+ (If you are using a pre-packaged version
+ of <span class="productname">PostgreSQL</span>, it may provide scripts to
+ assist with major version upgrades. Consult the package-level
+ documentation for details.)
+ </p><p>
+ New major versions also typically introduce some user-visible
+ incompatibilities, so application programming changes might be required.
+ All user-visible changes are listed in the release notes (<a class="xref" href="release.html" title="Appendix E. Release Notes">Appendix E</a>); pay particular attention to the section
+ labeled "Migration". Though you can upgrade from one major version
+ to another without upgrading to intervening versions, you should read
+ the major release notes of all intervening versions.
+ </p><p>
+ Cautious users will want to test their client applications on the new
+ version before switching over fully; therefore, it's often a good idea to
+ set up concurrent installations of old and new versions. When
+ testing a <span class="productname">PostgreSQL</span> major upgrade, consider the
+ following categories of possible changes:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Administration</span></dt><dd><p>
+ The capabilities available for administrators to monitor and control
+ the server often change and improve in each major release.
+ </p></dd><dt><span class="term">SQL</span></dt><dd><p>
+ Typically this includes new SQL command capabilities and not changes
+ in behavior, unless specifically mentioned in the release notes.
+ </p></dd><dt><span class="term">Library API</span></dt><dd><p>
+ Typically libraries like <span class="application">libpq</span> only add new
+ functionality, again unless mentioned in the release notes.
+ </p></dd><dt><span class="term">System Catalogs</span></dt><dd><p>
+ System catalog changes usually only affect database management tools.
+ </p></dd><dt><span class="term">Server C-language API</span></dt><dd><p>
+ This involves changes in the backend function API, which is written
+ in the C programming language. Such changes affect code that
+ references backend functions deep inside the server.
+ </p></dd></dl></div><div class="sect2" id="UPGRADING-VIA-PGDUMPALL"><div class="titlepage"><div><div><h3 class="title">19.6.1. Upgrading Data via <span class="application">pg_dumpall</span></h3></div></div></div><p>
+ One upgrade method is to dump data from one major version of
+ <span class="productname">PostgreSQL</span> and restore it in another — to do
+ this, you must use a <span class="emphasis"><em>logical</em></span> backup tool like
+ <span class="application">pg_dumpall</span>; file system
+ level backup methods will not work. (There are checks in place that prevent
+ you from using a data directory with an incompatible version of
+ <span class="productname">PostgreSQL</span>, so no great harm can be done by
+ trying to start the wrong server version on a data directory.)
+ </p><p>
+ It is recommended that you use the <span class="application">pg_dump</span> and
+ <span class="application">pg_dumpall</span> programs from the <span class="emphasis"><em>newer</em></span>
+ version of
+ <span class="productname">PostgreSQL</span>, to take advantage of enhancements
+ that might have been made in these programs. Current releases of the
+ dump programs can read data from any server version back to 9.2.
+ </p><p>
+ These instructions assume that your existing installation is under the
+ <code class="filename">/usr/local/pgsql</code> directory, and that the data area is in
+ <code class="filename">/usr/local/pgsql/data</code>. Substitute your paths
+ appropriately.
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
+ If making a backup, make sure that your database is not being updated.
+ This does not affect the integrity of the backup, but the changed
+ data would of course not be included. If necessary, edit the
+ permissions in the file <code class="filename">/usr/local/pgsql/data/pg_hba.conf</code>
+ (or equivalent) to disallow access from everyone except you.
+ See <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> for additional information on
+ access control.
+ </p><p>
+ <a id="id-1.6.6.9.11.5.1.2.1" class="indexterm"></a>
+
+ To back up your database installation, type:
+</p><pre class="screen">
+<strong class="userinput"><code>pg_dumpall &gt; <em class="replaceable"><code>outputfile</code></em></code></strong>
+</pre><p>
+ </p><p>
+ To make the backup, you can use the <span class="application">pg_dumpall</span>
+ command from the version you are currently running; see <a class="xref" href="backup-dump.html#BACKUP-DUMP-ALL" title="26.1.2. Using pg_dumpall">Section 26.1.2</a> for more details. For best
+ results, however, try to use the <span class="application">pg_dumpall</span>
+ command from <span class="productname">PostgreSQL</span> 15.5,
+ since this version contains bug fixes and improvements over older
+ versions. While this advice might seem idiosyncratic since you
+ haven't installed the new version yet, it is advisable to follow
+ it if you plan to install the new version in parallel with the
+ old version. In that case you can complete the installation
+ normally and transfer the data later. This will also decrease
+ the downtime.
+ </p></li><li class="step"><p>
+ Shut down the old server:
+</p><pre class="screen">
+<strong class="userinput"><code>pg_ctl stop</code></strong>
+</pre><p>
+ On systems that have <span class="productname">PostgreSQL</span> started at boot time,
+ there is probably a start-up file that will accomplish the same thing. For
+ example, on a <span class="systemitem">Red Hat Linux</span> system one
+ might find that this works:
+</p><pre class="screen">
+<strong class="userinput"><code>/etc/rc.d/init.d/postgresql stop</code></strong>
+</pre><p>
+ See <a class="xref" href="runtime.html" title="Chapter 19. Server Setup and Operation">Chapter 19</a> for details about starting and
+ stopping the server.
+ </p></li><li class="step"><p>
+ If restoring from backup, rename or delete the old installation
+ directory if it is not version-specific. It is a good idea to
+ rename the directory, rather than
+ delete it, in case you have trouble and need to revert to it. Keep
+ in mind the directory might consume significant disk space. To rename
+ the directory, use a command like this:
+</p><pre class="screen">
+<strong class="userinput"><code>mv /usr/local/pgsql /usr/local/pgsql.old</code></strong>
+</pre><p>
+ (Be sure to move the directory as a single unit so relative paths
+ remain unchanged.)
+ </p></li><li class="step"><p>
+ Install the new version of <span class="productname">PostgreSQL</span> as
+ outlined in <a class="xref" href="install-procedure.html" title="17.4. Installation Procedure">Section 17.4</a>.
+ </p></li><li class="step"><p>
+ Create a new database cluster if needed. Remember that you must
+ execute these commands while logged in to the special database user
+ account (which you already have if you are upgrading).
+</p><pre class="programlisting">
+<strong class="userinput"><code>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ </p></li><li class="step"><p>
+ Restore your previous <code class="filename">pg_hba.conf</code> and any
+ <code class="filename">postgresql.conf</code> modifications.
+ </p></li><li class="step"><p>
+ Start the database server, again using the special database user
+ account:
+</p><pre class="programlisting">
+<strong class="userinput"><code>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</code></strong>
+</pre><p>
+ </p></li><li class="step"><p>
+ Finally, restore your data from backup with:
+</p><pre class="screen">
+<strong class="userinput"><code>/usr/local/pgsql/bin/psql -d postgres -f <em class="replaceable"><code>outputfile</code></em></code></strong>
+</pre><p>
+ using the <span class="emphasis"><em>new</em></span> <span class="application">psql</span>.
+ </p></li></ol></div><p>
+ The least downtime can be achieved by installing the new server in
+ a different directory and running both the old and the new servers
+ in parallel, on different ports. Then you can use something like:
+
+</p><pre class="programlisting">
+pg_dumpall -p 5432 | psql -d postgres -p 5433
+</pre><p>
+ to transfer your data.
+ </p></div><div class="sect2" id="UPGRADING-VIA-PG-UPGRADE"><div class="titlepage"><div><div><h3 class="title">19.6.2. Upgrading Data via <span class="application">pg_upgrade</span></h3></div></div></div><p>
+ The <a class="xref" href="pgupgrade.html" title="pg_upgrade"><span class="refentrytitle"><span class="application">pg_upgrade</span></span></a> module allows an installation to
+ be migrated in-place from one major <span class="productname">PostgreSQL</span>
+ version to another. Upgrades can be performed in minutes,
+ particularly with <code class="option">--link</code> mode. It requires steps similar to
+ <span class="application">pg_dumpall</span> above, e.g., starting/stopping the server,
+ running <span class="application">initdb</span>. The <span class="application">pg_upgrade</span> <a class="link" href="pgupgrade.html" title="pg_upgrade">documentation</a> outlines the necessary steps.
+ </p></div><div class="sect2" id="UPGRADING-VIA-REPLICATION"><div class="titlepage"><div><div><h3 class="title">19.6.3. Upgrading Data via Replication</h3></div></div></div><p>
+ It is also possible to use logical replication methods to create a standby
+ server with the updated version of <span class="productname">PostgreSQL</span>.
+ This is possible because logical replication supports
+ replication between different major versions of
+ <span class="productname">PostgreSQL</span>. The standby can be on the same computer or
+ a different computer. Once it has synced up with the primary server
+ (running the older version of <span class="productname">PostgreSQL</span>), you can
+ switch primaries and make the standby the primary and shut down the older
+ database instance. Such a switch-over results in only several seconds
+ of downtime for an upgrade.
+ </p><p>
+ This method of upgrading can be performed using the built-in logical
+ replication facilities as well as using external logical replication
+ systems such as <span class="productname">pglogical</span>,
+ <span class="productname">Slony</span>, <span class="productname">Londiste</span>, and
+ <span class="productname">Bucardo</span>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server-shutdown.html" title="19.5. Shutting Down the Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 19. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="preventing-server-spoofing.html" title="19.7. Preventing Server Spoofing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.5. Shutting Down the Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 19.7. Preventing Server Spoofing</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/user-manag.html b/doc/src/sgml/html/user-manag.html
new file mode 100644
index 0000000..b49ec9a
--- /dev/null
+++ b/doc/src/sgml/html/user-manag.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 22. Database Roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="client-authentication-problems.html" title="21.15. Authentication Problems" /><link rel="next" href="database-roles.html" title="22.1. Database Roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 22. Database Roles</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="client-authentication-problems.html" title="21.15. Authentication Problems">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="database-roles.html" title="22.1. Database Roles">Next</a></td></tr></table><hr /></div><div class="chapter" id="USER-MANAG"><div class="titlepage"><div><div><h2 class="title">Chapter 22. Database Roles</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="database-roles.html">22.1. Database Roles</a></span></dt><dt><span class="sect1"><a href="role-attributes.html">22.2. Role Attributes</a></span></dt><dt><span class="sect1"><a href="role-membership.html">22.3. Role Membership</a></span></dt><dt><span class="sect1"><a href="role-removal.html">22.4. Dropping Roles</a></span></dt><dt><span class="sect1"><a href="predefined-roles.html">22.5. Predefined Roles</a></span></dt><dt><span class="sect1"><a href="perm-functions.html">22.6. Function Security</a></span></dt></dl></div><p>
+ <span class="productname">PostgreSQL</span> manages database access permissions
+ using the concept of <em class="firstterm">roles</em>. A role can be thought of as
+ either a database user, or a group of database users, depending on how
+ the role is set up. Roles can own database objects (for example, tables
+ and functions) and can assign privileges on those objects to other roles to
+ control who has access to which objects. Furthermore, it is possible
+ to grant <em class="firstterm">membership</em> in a role to another role, thus
+ allowing the member role to use privileges assigned to another role.
+ </p><p>
+ The concept of roles subsumes the concepts of <span class="quote">“<span class="quote">users</span>”</span> and
+ <span class="quote">“<span class="quote">groups</span>”</span>. In <span class="productname">PostgreSQL</span> versions
+ before 8.1, users and groups were distinct kinds of entities, but now
+ there are only roles. Any role can act as a user, a group, or both.
+ </p><p>
+ This chapter describes how to create and manage roles.
+ More information about the effects of role privileges on various
+ database objects can be found in <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="client-authentication-problems.html" title="21.15. Authentication Problems">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="database-roles.html" title="22.1. Database Roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">21.15. Authentication Problems </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 22.1. Database Roles</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/using-explain.html b/doc/src/sgml/html/using-explain.html
new file mode 100644
index 0000000..66145e7
--- /dev/null
+++ b/doc/src/sgml/html/using-explain.html
@@ -0,0 +1,804 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>14.1. Using EXPLAIN</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="performance-tips.html" title="Chapter 14. Performance Tips" /><link rel="next" href="planner-stats.html" title="14.2. Statistics Used by the Planner" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">14.1. Using <code class="command">EXPLAIN</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="performance-tips.html" title="Chapter 14. Performance Tips">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><th width="60%" align="center">Chapter 14. Performance Tips</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Next</a></td></tr></table><hr /></div><div class="sect1" id="USING-EXPLAIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">14.1. Using <code class="command">EXPLAIN</code></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-BASICS">14.1.1. <code class="command">EXPLAIN</code> Basics</a></span></dt><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-ANALYZE">14.1.2. <code class="command">EXPLAIN ANALYZE</code></a></span></dt><dt><span class="sect2"><a href="using-explain.html#USING-EXPLAIN-CAVEATS">14.1.3. Caveats</a></span></dt></dl></div><a id="id-1.5.13.4.2" class="indexterm"></a><a id="id-1.5.13.4.3" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> devises a <em class="firstterm">query
+ plan</em> for each query it receives. Choosing the right
+ plan to match the query structure and the properties of the data
+ is absolutely critical for good performance, so the system includes
+ a complex <em class="firstterm">planner</em> that tries to choose good plans.
+ You can use the <a class="link" href="sql-explain.html" title="EXPLAIN"><code class="command">EXPLAIN</code></a> command
+ to see what query plan the planner creates for any query.
+ Plan-reading is an art that requires some experience to master,
+ but this section attempts to cover the basics.
+ </p><p>
+ Examples in this section are drawn from the regression test database
+ after doing a <code class="command">VACUUM ANALYZE</code>, using 9.3 development sources.
+ You should be able to get similar results if you try the examples
+ yourself, but your estimated costs and row counts might vary slightly
+ because <code class="command">ANALYZE</code>'s statistics are random samples rather
+ than exact, and because costs are inherently somewhat platform-dependent.
+ </p><p>
+ The examples use <code class="command">EXPLAIN</code>'s default <span class="quote">“<span class="quote">text</span>”</span> output
+ format, which is compact and convenient for humans to read.
+ If you want to feed <code class="command">EXPLAIN</code>'s output to a program for further
+ analysis, you should use one of its machine-readable output formats
+ (XML, JSON, or YAML) instead.
+ </p><div class="sect2" id="USING-EXPLAIN-BASICS"><div class="titlepage"><div><div><h3 class="title">14.1.1. <code class="command">EXPLAIN</code> Basics</h3></div></div></div><p>
+ The structure of a query plan is a tree of <em class="firstterm">plan nodes</em>.
+ Nodes at the bottom level of the tree are scan nodes: they return raw rows
+ from a table. There are different types of scan nodes for different
+ table access methods: sequential scans, index scans, and bitmap index
+ scans. There are also non-table row sources, such as <code class="literal">VALUES</code>
+ clauses and set-returning functions in <code class="literal">FROM</code>, which have their
+ own scan node types.
+ If the query requires joining, aggregation, sorting, or other
+ operations on the raw rows, then there will be additional nodes
+ above the scan nodes to perform these operations. Again,
+ there is usually more than one possible way to do these operations,
+ so different node types can appear here too. The output
+ of <code class="command">EXPLAIN</code> has one line for each node in the plan
+ tree, showing the basic node type plus the cost estimates that the planner
+ made for the execution of that plan node. Additional lines might appear,
+ indented from the node's summary line,
+ to show additional properties of the node.
+ The very first line (the summary line for the topmost
+ node) has the estimated total execution cost for the plan; it is this
+ number that the planner seeks to minimize.
+ </p><p>
+ Here is a trivial example, just to show what the output looks like:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1;
+
+ QUERY PLAN
+-------------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..458.00 rows=10000 width=244)
+</pre><p>
+ </p><p>
+ Since this query has no <code class="literal">WHERE</code> clause, it must scan all the
+ rows of the table, so the planner has chosen to use a simple sequential
+ scan plan. The numbers that are quoted in parentheses are (left
+ to right):
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Estimated start-up cost. This is the time expended before the output
+ phase can begin, e.g., time to do the sorting in a sort node.
+ </p></li><li class="listitem"><p>
+ Estimated total cost. This is stated on the assumption that the plan
+ node is run to completion, i.e., all available rows are retrieved.
+ In practice a node's parent node might stop short of reading all
+ available rows (see the <code class="literal">LIMIT</code> example below).
+ </p></li><li class="listitem"><p>
+ Estimated number of rows output by this plan node. Again, the node
+ is assumed to be run to completion.
+ </p></li><li class="listitem"><p>
+ Estimated average width of rows output by this plan node (in bytes).
+ </p></li></ul></div><p>
+ </p><p>
+ The costs are measured in arbitrary units determined by the planner's
+ cost parameters (see <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS" title="20.7.2. Planner Cost Constants">Section 20.7.2</a>).
+ Traditional practice is to measure the costs in units of disk page
+ fetches; that is, <a class="xref" href="runtime-config-query.html#GUC-SEQ-PAGE-COST">seq_page_cost</a> is conventionally
+ set to <code class="literal">1.0</code> and the other cost parameters are set relative
+ to that. The examples in this section are run with the default cost
+ parameters.
+ </p><p>
+ It's important to understand that the cost of an upper-level node includes
+ the cost of all its child nodes. It's also important to realize that
+ the cost only reflects things that the planner cares about.
+ In particular, the cost does not consider the time spent transmitting
+ result rows to the client, which could be an important
+ factor in the real elapsed time; but the planner ignores it because
+ it cannot change it by altering the plan. (Every correct plan will
+ output the same row set, we trust.)
+ </p><p>
+ The <code class="literal">rows</code> value is a little tricky because it is
+ not the number of rows processed or scanned by the
+ plan node, but rather the number emitted by the node. This is often
+ less than the number scanned, as a result of filtering by any
+ <code class="literal">WHERE</code>-clause conditions that are being applied at the node.
+ Ideally the top-level rows estimate will approximate the number of rows
+ actually returned, updated, or deleted by the query.
+ </p><p>
+ Returning to our example:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1;
+
+ QUERY PLAN
+-------------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..458.00 rows=10000 width=244)
+</pre><p>
+ </p><p>
+ These numbers are derived very straightforwardly. If you do:
+
+</p><pre class="programlisting">
+SELECT relpages, reltuples FROM pg_class WHERE relname = 'tenk1';
+</pre><p>
+
+ you will find that <code class="classname">tenk1</code> has 358 disk
+ pages and 10000 rows. The estimated cost is computed as (disk pages read *
+ <a class="xref" href="runtime-config-query.html#GUC-SEQ-PAGE-COST">seq_page_cost</a>) + (rows scanned *
+ <a class="xref" href="runtime-config-query.html#GUC-CPU-TUPLE-COST">cpu_tuple_cost</a>). By default,
+ <code class="varname">seq_page_cost</code> is 1.0 and <code class="varname">cpu_tuple_cost</code> is 0.01,
+ so the estimated cost is (358 * 1.0) + (10000 * 0.01) = 458.
+ </p><p>
+ Now let's modify the query to add a <code class="literal">WHERE</code> condition:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 7000;
+
+ QUERY PLAN
+------------------------------------------------------------
+ Seq Scan on tenk1 (cost=0.00..483.00 rows=7001 width=244)
+ Filter: (unique1 &lt; 7000)
+</pre><p>
+
+ Notice that the <code class="command">EXPLAIN</code> output shows the <code class="literal">WHERE</code>
+ clause being applied as a <span class="quote">“<span class="quote">filter</span>”</span> condition attached to the Seq
+ Scan plan node. This means that
+ the plan node checks the condition for each row it scans, and outputs
+ only the ones that pass the condition.
+ The estimate of output rows has been reduced because of the
+ <code class="literal">WHERE</code> clause.
+ However, the scan will still have to visit all 10000 rows, so the cost
+ hasn't decreased; in fact it has gone up a bit (by 10000 * <a class="xref" href="runtime-config-query.html#GUC-CPU-OPERATOR-COST">cpu_operator_cost</a>, to be exact) to reflect the extra CPU
+ time spent checking the <code class="literal">WHERE</code> condition.
+ </p><p>
+ The actual number of rows this query would select is 7000, but the <code class="literal">rows</code>
+ estimate is only approximate. If you try to duplicate this experiment,
+ you will probably get a slightly different estimate; moreover, it can
+ change after each <code class="command">ANALYZE</code> command, because the
+ statistics produced by <code class="command">ANALYZE</code> are taken from a
+ randomized sample of the table.
+ </p><p>
+ Now, let's make the condition more restrictive:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------
+ Bitmap Heap Scan on tenk1 (cost=5.07..229.20 rows=101 width=244)
+ Recheck Cond: (unique1 &lt; 100)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0)
+ Index Cond: (unique1 &lt; 100)
+</pre><p>
+
+ Here the planner has decided to use a two-step plan: the child plan
+ node visits an index to find the locations of rows matching the index
+ condition, and then the upper plan node actually fetches those rows
+ from the table itself. Fetching rows separately is much more
+ expensive than reading them sequentially, but because not all the pages
+ of the table have to be visited, this is still cheaper than a sequential
+ scan. (The reason for using two plan levels is that the upper plan
+ node sorts the row locations identified by the index into physical order
+ before reading them, to minimize the cost of separate fetches.
+ The <span class="quote">“<span class="quote">bitmap</span>”</span> mentioned in the node names is the mechanism that
+ does the sorting.)
+ </p><p>
+ Now let's add another condition to the <code class="literal">WHERE</code> clause:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND stringu1 = 'xxx';
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------
+ Bitmap Heap Scan on tenk1 (cost=5.04..229.43 rows=1 width=244)
+ Recheck Cond: (unique1 &lt; 100)
+ Filter: (stringu1 = 'xxx'::name)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0)
+ Index Cond: (unique1 &lt; 100)
+</pre><p>
+
+ The added condition <code class="literal">stringu1 = 'xxx'</code> reduces the
+ output row count estimate, but not the cost because we still have to visit
+ the same set of rows. Notice that the <code class="literal">stringu1</code> clause
+ cannot be applied as an index condition, since this index is only on
+ the <code class="literal">unique1</code> column. Instead it is applied as a filter on
+ the rows retrieved by the index. Thus the cost has actually gone up
+ slightly to reflect this extra checking.
+ </p><p>
+ In some cases the planner will prefer a <span class="quote">“<span class="quote">simple</span>”</span> index scan plan:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 = 42;
+
+ QUERY PLAN
+-------------------------------------------------------------------​----------
+ Index Scan using tenk1_unique1 on tenk1 (cost=0.29..8.30 rows=1 width=244)
+ Index Cond: (unique1 = 42)
+</pre><p>
+
+ In this type of plan the table rows are fetched in index order, which
+ makes them even more expensive to read, but there are so few that the
+ extra cost of sorting the row locations is not worth it. You'll most
+ often see this plan type for queries that fetch just a single row. It's
+ also often used for queries that have an <code class="literal">ORDER BY</code> condition
+ that matches the index order, because then no extra sorting step is needed
+ to satisfy the <code class="literal">ORDER BY</code>. In this example, adding
+ <code class="literal">ORDER BY unique1</code> would use the same plan because the
+ index already implicitly provides the requested ordering.
+ </p><p>
+ The planner may implement an <code class="literal">ORDER BY</code> clause in several
+ ways. The above example shows that such an ordering clause may be
+ implemented implicitly. The planner may also add an explicit
+ <code class="literal">sort</code> step:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 ORDER BY unique1;
+ QUERY PLAN
+-------------------------------------------------------------------
+ Sort (cost=1109.39..1134.39 rows=10000 width=244)
+ Sort Key: unique1
+ -&gt; Seq Scan on tenk1 (cost=0.00..445.00 rows=10000 width=244)
+</pre><p>
+
+ If a part of the plan guarantees an ordering on a prefix of the
+ required sort keys, then the planner may instead decide to use an
+ <code class="literal">incremental sort</code> step:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 ORDER BY four, ten LIMIT 100;
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------
+ Limit (cost=521.06..538.05 rows=100 width=244)
+ -&gt; Incremental Sort (cost=521.06..2220.95 rows=10000 width=244)
+ Sort Key: four, ten
+ Presorted Key: four
+ -&gt; Index Scan using index_tenk1_on_four on tenk1 (cost=0.29..1510.08 rows=10000 width=244)
+</pre><p>
+
+ Compared to regular sorts, sorting incrementally allows returning tuples
+ before the entire result set has been sorted, which particularly enables
+ optimizations with <code class="literal">LIMIT</code> queries. It may also reduce
+ memory usage and the likelihood of spilling sorts to disk, but it comes at
+ the cost of the increased overhead of splitting the result set into multiple
+ sorting batches.
+ </p><p>
+ If there are separate indexes on several of the columns referenced
+ in <code class="literal">WHERE</code>, the planner might choose to use an AND or OR
+ combination of the indexes:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000;
+
+ QUERY PLAN
+-------------------------------------------------------------------​------------------
+ Bitmap Heap Scan on tenk1 (cost=25.08..60.21 rows=10 width=244)
+ Recheck Cond: ((unique1 &lt; 100) AND (unique2 &gt; 9000))
+ -&gt; BitmapAnd (cost=25.08..25.08 rows=10 width=0)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0)
+ Index Cond: (unique1 &lt; 100)
+ -&gt; Bitmap Index Scan on tenk1_unique2 (cost=0.00..19.78 rows=999 width=0)
+ Index Cond: (unique2 &gt; 9000)
+</pre><p>
+
+ But this requires visiting both indexes, so it's not necessarily a win
+ compared to using just one index and treating the other condition as
+ a filter. If you vary the ranges involved you'll see the plan change
+ accordingly.
+ </p><p>
+ Here is an example showing the effects of <code class="literal">LIMIT</code>:
+
+</p><pre class="screen">
+EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000 LIMIT 2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​------------------
+ Limit (cost=0.29..14.48 rows=2 width=244)
+ -&gt; Index Scan using tenk1_unique2 on tenk1 (cost=0.29..71.27 rows=10 width=244)
+ Index Cond: (unique2 &gt; 9000)
+ Filter: (unique1 &lt; 100)
+</pre><p>
+ </p><p>
+ This is the same query as above, but we added a <code class="literal">LIMIT</code> so that
+ not all the rows need be retrieved, and the planner changed its mind about
+ what to do. Notice that the total cost and row count of the Index Scan
+ node are shown as if it were run to completion. However, the Limit node
+ is expected to stop after retrieving only a fifth of those rows, so its
+ total cost is only a fifth as much, and that's the actual estimated cost
+ of the query. This plan is preferred over adding a Limit node to the
+ previous plan because the Limit could not avoid paying the startup cost
+ of the bitmap scan, so the total cost would be something over 25 units
+ with that approach.
+ </p><p>
+ Let's try joining two tables, using the columns we have been discussing:
+
+</p><pre class="screen">
+EXPLAIN SELECT *
+FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 10 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------
+ Nested Loop (cost=4.65..118.62 rows=10 width=488)
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.47 rows=10 width=244)
+ Recheck Cond: (unique1 &lt; 10)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36 rows=10 width=0)
+ Index Cond: (unique1 &lt; 10)
+ -&gt; Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.29..7.91 rows=1 width=244)
+ Index Cond: (unique2 = t1.unique2)
+</pre><p>
+ </p><p>
+ In this plan, we have a nested-loop join node with two table scans as
+ inputs, or children. The indentation of the node summary lines reflects
+ the plan tree structure. The join's first, or <span class="quote">“<span class="quote">outer</span>”</span>, child
+ is a bitmap scan similar to those we saw before. Its cost and row count
+ are the same as we'd get from <code class="literal">SELECT ... WHERE unique1 &lt; 10</code>
+ because we are
+ applying the <code class="literal">WHERE</code> clause <code class="literal">unique1 &lt; 10</code>
+ at that node.
+ The <code class="literal">t1.unique2 = t2.unique2</code> clause is not relevant yet,
+ so it doesn't affect the row count of the outer scan. The nested-loop
+ join node will run its second,
+ or <span class="quote">“<span class="quote">inner</span>”</span> child once for each row obtained from the outer child.
+ Column values from the current outer row can be plugged into the inner
+ scan; here, the <code class="literal">t1.unique2</code> value from the outer row is available,
+ so we get a plan and costs similar to what we saw above for a simple
+ <code class="literal">SELECT ... WHERE t2.unique2 = <em class="replaceable"><code>constant</code></em></code> case.
+ (The estimated cost is actually a bit lower than what was seen above,
+ as a result of caching that's expected to occur during the repeated
+ index scans on <code class="literal">t2</code>.) The
+ costs of the loop node are then set on the basis of the cost of the outer
+ scan, plus one repetition of the inner scan for each outer row (10 * 7.91,
+ here), plus a little CPU time for join processing.
+ </p><p>
+ In this example the join's output row count is the same as the product
+ of the two scans' row counts, but that's not true in all cases because
+ there can be additional <code class="literal">WHERE</code> clauses that mention both tables
+ and so can only be applied at the join point, not to either input scan.
+ Here's an example:
+
+</p><pre class="screen">
+EXPLAIN SELECT *
+FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 10 AND t2.unique2 &lt; 10 AND t1.hundred &lt; t2.hundred;
+
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------
+ Nested Loop (cost=4.65..49.46 rows=33 width=488)
+ Join Filter: (t1.hundred &lt; t2.hundred)
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.47 rows=10 width=244)
+ Recheck Cond: (unique1 &lt; 10)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36 rows=10 width=0)
+ Index Cond: (unique1 &lt; 10)
+ -&gt; Materialize (cost=0.29..8.51 rows=10 width=244)
+ -&gt; Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.29..8.46 rows=10 width=244)
+ Index Cond: (unique2 &lt; 10)
+</pre><p>
+
+ The condition <code class="literal">t1.hundred &lt; t2.hundred</code> can't be
+ tested in the <code class="literal">tenk2_unique2</code> index, so it's applied at the
+ join node. This reduces the estimated output row count of the join node,
+ but does not change either input scan.
+ </p><p>
+ Notice that here the planner has chosen to <span class="quote">“<span class="quote">materialize</span>”</span> the inner
+ relation of the join, by putting a Materialize plan node atop it. This
+ means that the <code class="literal">t2</code> index scan will be done just once, even
+ though the nested-loop join node needs to read that data ten times, once
+ for each row from the outer relation. The Materialize node saves the data
+ in memory as it's read, and then returns the data from memory on each
+ subsequent pass.
+ </p><p>
+ When dealing with outer joins, you might see join plan nodes with both
+ <span class="quote">“<span class="quote">Join Filter</span>”</span> and plain <span class="quote">“<span class="quote">Filter</span>”</span> conditions attached.
+ Join Filter conditions come from the outer join's <code class="literal">ON</code> clause,
+ so a row that fails the Join Filter condition could still get emitted as
+ a null-extended row. But a plain Filter condition is applied after the
+ outer-join rules and so acts to remove rows unconditionally. In an inner
+ join there is no semantic difference between these types of filters.
+ </p><p>
+ If we change the query's selectivity a bit, we might get a very different
+ join plan:
+
+</p><pre class="screen">
+EXPLAIN SELECT *
+FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------
+ Hash Join (cost=230.47..713.98 rows=101 width=488)
+ Hash Cond: (t2.unique2 = t1.unique2)
+ -&gt; Seq Scan on tenk2 t2 (cost=0.00..445.00 rows=10000 width=244)
+ -&gt; Hash (cost=229.20..229.20 rows=101 width=244)
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=5.07..229.20 rows=101 width=244)
+ Recheck Cond: (unique1 &lt; 100)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0)
+ Index Cond: (unique1 &lt; 100)
+</pre><p>
+ </p><p>
+ Here, the planner has chosen to use a hash join, in which rows of one
+ table are entered into an in-memory hash table, after which the other
+ table is scanned and the hash table is probed for matches to each row.
+ Again note how the indentation reflects the plan structure: the bitmap
+ scan on <code class="literal">tenk1</code> is the input to the Hash node, which constructs
+ the hash table. That's then returned to the Hash Join node, which reads
+ rows from its outer child plan and searches the hash table for each one.
+ </p><p>
+ Another possible type of join is a merge join, illustrated here:
+
+</p><pre class="screen">
+EXPLAIN SELECT *
+FROM tenk1 t1, onek t2
+WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------
+ Merge Join (cost=198.11..268.19 rows=10 width=488)
+ Merge Cond: (t1.unique2 = t2.unique2)
+ -&gt; Index Scan using tenk1_unique2 on tenk1 t1 (cost=0.29..656.28 rows=101 width=244)
+ Filter: (unique1 &lt; 100)
+ -&gt; Sort (cost=197.83..200.33 rows=1000 width=244)
+ Sort Key: t2.unique2
+ -&gt; Seq Scan on onek t2 (cost=0.00..148.00 rows=1000 width=244)
+</pre><p>
+ </p><p>
+ Merge join requires its input data to be sorted on the join keys. In this
+ plan the <code class="literal">tenk1</code> data is sorted by using an index scan to visit
+ the rows in the correct order, but a sequential scan and sort is preferred
+ for <code class="literal">onek</code>, because there are many more rows to be visited in
+ that table.
+ (Sequential-scan-and-sort frequently beats an index scan for sorting many rows,
+ because of the nonsequential disk access required by the index scan.)
+ </p><p>
+ One way to look at variant plans is to force the planner to disregard
+ whatever strategy it thought was the cheapest, using the enable/disable
+ flags described in <a class="xref" href="runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE" title="20.7.1. Planner Method Configuration">Section 20.7.1</a>.
+ (This is a crude tool, but useful. See
+ also <a class="xref" href="explicit-joins.html" title="14.3. Controlling the Planner with Explicit JOIN Clauses">Section 14.3</a>.)
+ For example, if we're unconvinced that sequential-scan-and-sort is the best way to
+ deal with table <code class="literal">onek</code> in the previous example, we could try
+
+</p><pre class="screen">
+SET enable_sort = off;
+
+EXPLAIN SELECT *
+FROM tenk1 t1, onek t2
+WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------
+ Merge Join (cost=0.56..292.65 rows=10 width=488)
+ Merge Cond: (t1.unique2 = t2.unique2)
+ -&gt; Index Scan using tenk1_unique2 on tenk1 t1 (cost=0.29..656.28 rows=101 width=244)
+ Filter: (unique1 &lt; 100)
+ -&gt; Index Scan using onek_unique2 on onek t2 (cost=0.28..224.79 rows=1000 width=244)
+</pre><p>
+
+ which shows that the planner thinks that sorting <code class="literal">onek</code> by
+ index-scanning is about 12% more expensive than sequential-scan-and-sort.
+ Of course, the next question is whether it's right about that.
+ We can investigate that using <code class="command">EXPLAIN ANALYZE</code>, as discussed
+ below.
+ </p></div><div class="sect2" id="USING-EXPLAIN-ANALYZE"><div class="titlepage"><div><div><h3 class="title">14.1.2. <code class="command">EXPLAIN ANALYZE</code></h3></div></div></div><p>
+ It is possible to check the accuracy of the planner's estimates
+ by using <code class="command">EXPLAIN</code>'s <code class="literal">ANALYZE</code> option. With this
+ option, <code class="command">EXPLAIN</code> actually executes the query, and then displays
+ the true row counts and true run time accumulated within each plan node,
+ along with the same estimates that a plain <code class="command">EXPLAIN</code>
+ shows. For example, we might get a result like this:
+
+</p><pre class="screen">
+EXPLAIN ANALYZE SELECT *
+FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 10 AND t1.unique2 = t2.unique2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------------------------------------------
+ Nested Loop (cost=4.65..118.62 rows=10 width=488) (actual time=0.128..0.377 rows=10 loops=1)
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.47 rows=10 width=244) (actual time=0.057..0.121 rows=10 loops=1)
+ Recheck Cond: (unique1 &lt; 10)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36 rows=10 width=0) (actual time=0.024..0.024 rows=10 loops=1)
+ Index Cond: (unique1 &lt; 10)
+ -&gt; Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.29..7.91 rows=1 width=244) (actual time=0.021..0.022 rows=1 loops=10)
+ Index Cond: (unique2 = t1.unique2)
+ Planning time: 0.181 ms
+ Execution time: 0.501 ms
+</pre><p>
+
+ Note that the <span class="quote">“<span class="quote">actual time</span>”</span> values are in milliseconds of
+ real time, whereas the <code class="literal">cost</code> estimates are expressed in
+ arbitrary units; so they are unlikely to match up.
+ The thing that's usually most important to look for is whether the
+ estimated row counts are reasonably close to reality. In this example
+ the estimates were all dead-on, but that's quite unusual in practice.
+ </p><p>
+ In some query plans, it is possible for a subplan node to be executed more
+ than once. For example, the inner index scan will be executed once per
+ outer row in the above nested-loop plan. In such cases, the
+ <code class="literal">loops</code> value reports the
+ total number of executions of the node, and the actual time and rows
+ values shown are averages per-execution. This is done to make the numbers
+ comparable with the way that the cost estimates are shown. Multiply by
+ the <code class="literal">loops</code> value to get the total time actually spent in
+ the node. In the above example, we spent a total of 0.220 milliseconds
+ executing the index scans on <code class="literal">tenk2</code>.
+ </p><p>
+ In some cases <code class="command">EXPLAIN ANALYZE</code> shows additional execution
+ statistics beyond the plan node execution times and row counts.
+ For example, Sort and Hash nodes provide extra information:
+
+</p><pre class="screen">
+EXPLAIN ANALYZE SELECT *
+FROM tenk1 t1, tenk2 t2
+WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2 ORDER BY t1.fivethous;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------------------------------------------------------​------
+ Sort (cost=717.34..717.59 rows=101 width=488) (actual time=7.761..7.774 rows=100 loops=1)
+ Sort Key: t1.fivethous
+ Sort Method: quicksort Memory: 77kB
+ -&gt; Hash Join (cost=230.47..713.98 rows=101 width=488) (actual time=0.711..7.427 rows=100 loops=1)
+ Hash Cond: (t2.unique2 = t1.unique2)
+ -&gt; Seq Scan on tenk2 t2 (cost=0.00..445.00 rows=10000 width=244) (actual time=0.007..2.583 rows=10000 loops=1)
+ -&gt; Hash (cost=229.20..229.20 rows=101 width=244) (actual time=0.659..0.659 rows=100 loops=1)
+ Buckets: 1024 Batches: 1 Memory Usage: 28kB
+ -&gt; Bitmap Heap Scan on tenk1 t1 (cost=5.07..229.20 rows=101 width=244) (actual time=0.080..0.526 rows=100 loops=1)
+ Recheck Cond: (unique1 &lt; 100)
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0) (actual time=0.049..0.049 rows=100 loops=1)
+ Index Cond: (unique1 &lt; 100)
+ Planning time: 0.194 ms
+ Execution time: 8.008 ms
+</pre><p>
+
+ The Sort node shows the sort method used (in particular, whether the sort
+ was in-memory or on-disk) and the amount of memory or disk space needed.
+ The Hash node shows the number of hash buckets and batches as well as the
+ peak amount of memory used for the hash table. (If the number of batches
+ exceeds one, there will also be disk space usage involved, but that is not
+ shown.)
+ </p><p>
+ Another type of extra information is the number of rows removed by a
+ filter condition:
+
+</p><pre class="screen">
+EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE ten &lt; 7;
+
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------------------
+ Seq Scan on tenk1 (cost=0.00..483.00 rows=7000 width=244) (actual time=0.016..5.107 rows=7000 loops=1)
+ Filter: (ten &lt; 7)
+ Rows Removed by Filter: 3000
+ Planning time: 0.083 ms
+ Execution time: 5.905 ms
+</pre><p>
+
+ These counts can be particularly valuable for filter conditions applied at
+ join nodes. The <span class="quote">“<span class="quote">Rows Removed</span>”</span> line only appears when at least
+ one scanned row, or potential join pair in the case of a join node,
+ is rejected by the filter condition.
+ </p><p>
+ A case similar to filter conditions occurs with <span class="quote">“<span class="quote">lossy</span>”</span>
+ index scans. For example, consider this search for polygons containing a
+ specific point:
+
+</p><pre class="screen">
+EXPLAIN ANALYZE SELECT * FROM polygon_tbl WHERE f1 @&gt; polygon '(0.5,2.0)';
+
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------
+ Seq Scan on polygon_tbl (cost=0.00..1.05 rows=1 width=32) (actual time=0.044..0.044 rows=0 loops=1)
+ Filter: (f1 @&gt; '((0.5,2))'::polygon)
+ Rows Removed by Filter: 4
+ Planning time: 0.040 ms
+ Execution time: 0.083 ms
+</pre><p>
+
+ The planner thinks (quite correctly) that this sample table is too small
+ to bother with an index scan, so we have a plain sequential scan in which
+ all the rows got rejected by the filter condition. But if we force an
+ index scan to be used, we see:
+
+</p><pre class="screen">
+SET enable_seqscan TO off;
+
+EXPLAIN ANALYZE SELECT * FROM polygon_tbl WHERE f1 @&gt; polygon '(0.5,2.0)';
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------------------------------------------
+ Index Scan using gpolygonind on polygon_tbl (cost=0.13..8.15 rows=1 width=32) (actual time=0.062..0.062 rows=0 loops=1)
+ Index Cond: (f1 @&gt; '((0.5,2))'::polygon)
+ Rows Removed by Index Recheck: 1
+ Planning time: 0.034 ms
+ Execution time: 0.144 ms
+</pre><p>
+
+ Here we can see that the index returned one candidate row, which was
+ then rejected by a recheck of the index condition. This happens because a
+ GiST index is <span class="quote">“<span class="quote">lossy</span>”</span> for polygon containment tests: it actually
+ returns the rows with polygons that overlap the target, and then we have
+ to do the exact containment test on those rows.
+ </p><p>
+ <code class="command">EXPLAIN</code> has a <code class="literal">BUFFERS</code> option that can be used with
+ <code class="literal">ANALYZE</code> to get even more run time statistics:
+
+</p><pre class="screen">
+EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000;
+
+ QUERY PLAN
+-------------------------------------------------------------------​--------------------------------------------------------------
+ Bitmap Heap Scan on tenk1 (cost=25.08..60.21 rows=10 width=244) (actual time=0.323..0.342 rows=10 loops=1)
+ Recheck Cond: ((unique1 &lt; 100) AND (unique2 &gt; 9000))
+ Buffers: shared hit=15
+ -&gt; BitmapAnd (cost=25.08..25.08 rows=10 width=0) (actual time=0.309..0.309 rows=0 loops=1)
+ Buffers: shared hit=7
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=101 width=0) (actual time=0.043..0.043 rows=100 loops=1)
+ Index Cond: (unique1 &lt; 100)
+ Buffers: shared hit=2
+ -&gt; Bitmap Index Scan on tenk1_unique2 (cost=0.00..19.78 rows=999 width=0) (actual time=0.227..0.227 rows=999 loops=1)
+ Index Cond: (unique2 &gt; 9000)
+ Buffers: shared hit=5
+ Planning time: 0.088 ms
+ Execution time: 0.423 ms
+</pre><p>
+
+ The numbers provided by <code class="literal">BUFFERS</code> help to identify which parts
+ of the query are the most I/O-intensive.
+ </p><p>
+ Keep in mind that because <code class="command">EXPLAIN ANALYZE</code> actually
+ runs the query, any side-effects will happen as usual, even though
+ whatever results the query might output are discarded in favor of
+ printing the <code class="command">EXPLAIN</code> data. If you want to analyze a
+ data-modifying query without changing your tables, you can
+ roll the command back afterwards, for example:
+
+</p><pre class="screen">
+BEGIN;
+
+EXPLAIN ANALYZE UPDATE tenk1 SET hundred = hundred + 1 WHERE unique1 &lt; 100;
+
+ QUERY PLAN
+-------------------------------------------------------------------​-------------------------------------------------------------
+ Update on tenk1 (cost=5.08..230.08 rows=0 width=0) (actual time=3.791..3.792 rows=0 loops=1)
+ -&gt; Bitmap Heap Scan on tenk1 (cost=5.08..230.08 rows=102 width=10) (actual time=0.069..0.513 rows=100 loops=1)
+ Recheck Cond: (unique1 &lt; 100)
+ Heap Blocks: exact=90
+ -&gt; Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.05 rows=102 width=0) (actual time=0.036..0.037 rows=300 loops=1)
+ Index Cond: (unique1 &lt; 100)
+ Planning Time: 0.113 ms
+ Execution Time: 3.850 ms
+
+ROLLBACK;
+</pre><p>
+ </p><p>
+ As seen in this example, when the query is an <code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, or
+ <code class="command">MERGE</code> command, the actual work of
+ applying the table changes is done by a top-level Insert, Update,
+ Delete, or Merge plan node. The plan nodes underneath this node perform
+ the work of locating the old rows and/or computing the new data.
+ So above, we see the same sort of bitmap table scan we've seen already,
+ and its output is fed to an Update node that stores the updated rows.
+ It's worth noting that although the data-modifying node can take a
+ considerable amount of run time (here, it's consuming the lion's share
+ of the time), the planner does not currently add anything to the cost
+ estimates to account for that work. That's because the work to be done is
+ the same for every correct query plan, so it doesn't affect planning
+ decisions.
+ </p><p>
+ When an <code class="command">UPDATE</code>, <code class="command">DELETE</code>, or
+ <code class="command">MERGE</code> command affects an
+ inheritance hierarchy, the output might look like this:
+
+</p><pre class="screen">
+EXPLAIN UPDATE parent SET f2 = f2 + 1 WHERE f1 = 101;
+ QUERY PLAN
+-------------------------------------------------------------------​-----------------------------------
+ Update on parent (cost=0.00..24.59 rows=0 width=0)
+ Update on parent parent_1
+ Update on child1 parent_2
+ Update on child2 parent_3
+ Update on child3 parent_4
+ -&gt; Result (cost=0.00..24.59 rows=4 width=14)
+ -&gt; Append (cost=0.00..24.54 rows=4 width=14)
+ -&gt; Seq Scan on parent parent_1 (cost=0.00..0.00 rows=1 width=14)
+ Filter: (f1 = 101)
+ -&gt; Index Scan using child1_pkey on child1 parent_2 (cost=0.15..8.17 rows=1 width=14)
+ Index Cond: (f1 = 101)
+ -&gt; Index Scan using child2_pkey on child2 parent_3 (cost=0.15..8.17 rows=1 width=14)
+ Index Cond: (f1 = 101)
+ -&gt; Index Scan using child3_pkey on child3 parent_4 (cost=0.15..8.17 rows=1 width=14)
+ Index Cond: (f1 = 101)
+</pre><p>
+
+ In this example the Update node needs to consider three child tables as
+ well as the originally-mentioned parent table. So there are four input
+ scanning subplans, one per table. For clarity, the Update node is
+ annotated to show the specific target tables that will be updated, in the
+ same order as the corresponding subplans.
+ </p><p>
+ The <code class="literal">Planning time</code> shown by <code class="command">EXPLAIN
+ ANALYZE</code> is the time it took to generate the query plan from the
+ parsed query and optimize it. It does not include parsing or rewriting.
+ </p><p>
+ The <code class="literal">Execution time</code> shown by <code class="command">EXPLAIN
+ ANALYZE</code> includes executor start-up and shut-down time, as well
+ as the time to run any triggers that are fired, but it does not include
+ parsing, rewriting, or planning time.
+ Time spent executing <code class="literal">BEFORE</code> triggers, if any, is included in
+ the time for the related Insert, Update, or Delete node; but time
+ spent executing <code class="literal">AFTER</code> triggers is not counted there because
+ <code class="literal">AFTER</code> triggers are fired after completion of the whole plan.
+ The total time spent in each trigger
+ (either <code class="literal">BEFORE</code> or <code class="literal">AFTER</code>) is also shown separately.
+ Note that deferred constraint triggers will not be executed
+ until end of transaction and are thus not considered at all by
+ <code class="command">EXPLAIN ANALYZE</code>.
+ </p></div><div class="sect2" id="USING-EXPLAIN-CAVEATS"><div class="titlepage"><div><div><h3 class="title">14.1.3. Caveats</h3></div></div></div><p>
+ There are two significant ways in which run times measured by
+ <code class="command">EXPLAIN ANALYZE</code> can deviate from normal execution of
+ the same query. First, since no output rows are delivered to the client,
+ network transmission costs and I/O conversion costs are not included.
+ Second, the measurement overhead added by <code class="command">EXPLAIN
+ ANALYZE</code> can be significant, especially on machines with slow
+ <code class="function">gettimeofday()</code> operating-system calls. You can use the
+ <a class="xref" href="pgtesttiming.html" title="pg_test_timing"><span class="refentrytitle"><span class="application">pg_test_timing</span></span></a> tool to measure the overhead of timing
+ on your system.
+ </p><p>
+ <code class="command">EXPLAIN</code> results should not be extrapolated to situations
+ much different from the one you are actually testing; for example,
+ results on a toy-sized table cannot be assumed to apply to large tables.
+ The planner's cost estimates are not linear and so it might choose
+ a different plan for a larger or smaller table. An extreme example
+ is that on a table that only occupies one disk page, you'll nearly
+ always get a sequential scan plan whether indexes are available or not.
+ The planner realizes that it's going to take one disk page read to
+ process the table in any case, so there's no value in expending additional
+ page reads to look at an index. (We saw this happening in the
+ <code class="literal">polygon_tbl</code> example above.)
+ </p><p>
+ There are cases in which the actual and estimated values won't match up
+ well, but nothing is really wrong. One such case occurs when
+ plan node execution is stopped short by a <code class="literal">LIMIT</code> or similar
+ effect. For example, in the <code class="literal">LIMIT</code> query we used before,
+
+</p><pre class="screen">
+EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000 LIMIT 2;
+
+ QUERY PLAN
+-------------------------------------------------------------------​------------------------------------------------------------
+ Limit (cost=0.29..14.71 rows=2 width=244) (actual time=0.177..0.249 rows=2 loops=1)
+ -&gt; Index Scan using tenk1_unique2 on tenk1 (cost=0.29..72.42 rows=10 width=244) (actual time=0.174..0.244 rows=2 loops=1)
+ Index Cond: (unique2 &gt; 9000)
+ Filter: (unique1 &lt; 100)
+ Rows Removed by Filter: 287
+ Planning time: 0.096 ms
+ Execution time: 0.336 ms
+</pre><p>
+
+ the estimated cost and row count for the Index Scan node are shown as
+ though it were run to completion. But in reality the Limit node stopped
+ requesting rows after it got two, so the actual row count is only 2 and
+ the run time is less than the cost estimate would suggest. This is not
+ an estimation error, only a discrepancy in the way the estimates and true
+ values are displayed.
+ </p><p>
+ Merge joins also have measurement artifacts that can confuse the unwary.
+ A merge join will stop reading one input if it's exhausted the other input
+ and the next key value in the one input is greater than the last key value
+ of the other input; in such a case there can be no more matches and so no
+ need to scan the rest of the first input. This results in not reading all
+ of one child, with results like those mentioned for <code class="literal">LIMIT</code>.
+ Also, if the outer (first) child contains rows with duplicate key values,
+ the inner (second) child is backed up and rescanned for the portion of its
+ rows matching that key value. <code class="command">EXPLAIN ANALYZE</code> counts these
+ repeated emissions of the same inner rows as if they were real additional
+ rows. When there are many outer duplicates, the reported actual row count
+ for the inner child plan node can be significantly larger than the number
+ of rows that are actually in the inner relation.
+ </p><p>
+ BitmapAnd and BitmapOr nodes always report their actual row counts as zero,
+ due to implementation limitations.
+ </p><p>
+ Normally, <code class="command">EXPLAIN</code> will display every plan node
+ created by the planner. However, there are cases where the executor
+ can determine that certain nodes need not be executed because they
+ cannot produce any rows, based on parameter values that were not
+ available at planning time. (Currently this can only happen for child
+ nodes of an Append or MergeAppend node that is scanning a partitioned
+ table.) When this happens, those plan nodes are omitted from
+ the <code class="command">EXPLAIN</code> output and a <code class="literal">Subplans
+ Removed: <em class="replaceable"><code>N</code></em></code> annotation appears
+ instead.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="performance-tips.html" title="Chapter 14. Performance Tips">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="performance-tips.html" title="Chapter 14. Performance Tips">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="planner-stats.html" title="14.2. Statistics Used by the Planner">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. Performance Tips </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 14.2. Statistics Used by the Planner</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/uuid-ossp.html b/doc/src/sgml/html/uuid-ossp.html
new file mode 100644
index 0000000..cafa95a
--- /dev/null
+++ b/doc/src/sgml/html/uuid-ossp.html
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.49. uuid-ossp</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="unaccent.html" title="F.48. unaccent" /><link rel="next" href="xml2.html" title="F.50. xml2" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.49. uuid-ossp</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="unaccent.html" title="F.48. unaccent">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xml2.html" title="F.50. xml2">Next</a></td></tr></table><hr /></div><div class="sect1" id="UUID-OSSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.49. uuid-ossp</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.5">F.49.1. <code class="literal">uuid-ossp</code> Functions</a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.6">F.49.2. Building <code class="filename">uuid-ossp</code></a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#id-1.11.7.58.7">F.49.3. Author</a></span></dt></dl></div><a id="id-1.11.7.58.2" class="indexterm"></a><p>
+ The <code class="filename">uuid-ossp</code> module provides functions to generate universally
+ unique identifiers (UUIDs) using one of several standard algorithms. There
+ are also functions to produce certain special UUID constants.
+ This module is only necessary for special requirements beyond what is
+ available in core <span class="productname">PostgreSQL</span>. See <a class="xref" href="functions-uuid.html" title="9.14. UUID Functions">Section 9.14</a> for built-in ways to generate UUIDs.
+ </p><p>
+ This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
+ installed by non-superusers who have <code class="literal">CREATE</code> privilege
+ on the current database.
+ </p><div class="sect2" id="id-1.11.7.58.5"><div class="titlepage"><div><div><h3 class="title">F.49.1. <code class="literal">uuid-ossp</code> Functions</h3></div></div></div><p>
+ <a class="xref" href="uuid-ossp.html#UUID-OSSP-FUNCTIONS" title="Table F.32. Functions for UUID Generation">Table F.32</a> shows the functions available to
+ generate UUIDs.
+ The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and
+ <a class="ulink" href="https://tools.ietf.org/html/rfc4122" target="_top">RFC 4122</a>
+ specify four algorithms for generating UUIDs, identified by the
+ version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.)
+ Each of these algorithms could be suitable for a different set of
+ applications.
+ </p><div class="table" id="UUID-OSSP-FUNCTIONS"><p class="title"><strong>Table F.32. Functions for UUID Generation</strong></p><div class="table-contents"><table class="table" summary="Functions for UUID Generation" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.58.5.3.2.2.1.1.1.1" class="indexterm"></a>
+ <code class="function">uuid_generate_v1</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Generates a version 1 UUID. This involves the MAC
+ address of the computer and a time stamp. Note that UUIDs of this
+ kind reveal the identity of the computer that created the identifier
+ and the time at which it did so, which might make it unsuitable for
+ certain security-sensitive applications.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.58.5.3.2.2.2.1.1.1" class="indexterm"></a>
+ <code class="function">uuid_generate_v1mc</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Generates a version 1 UUID, but uses a random multicast
+ MAC address instead of the real MAC address of the computer.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <a id="id-1.11.7.58.5.3.2.2.3.1.1.1" class="indexterm"></a>
+ <code class="function">uuid_generate_v3</code> ( <em class="parameter"><code>namespace</code></em> <code class="type">uuid</code>, <em class="parameter"><code>name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Generates a version 3 UUID in the given namespace using
+ the specified input name. The namespace should be one of the special
+ constants produced by the <code class="function">uuid_ns_*()</code> functions
+ shown in <a class="xref" href="uuid-ossp.html#UUID-OSSP-CONSTANTS" title="Table F.33. Functions Returning UUID Constants">Table F.33</a>. (It could be any UUID
+ in theory.) The name is an identifier in the selected namespace.
+ </p>
+ <p>
+ For example:
+
+</p><pre class="programlisting">
+SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
+</pre><p>
+
+ The name parameter will be MD5-hashed, so the cleartext cannot be
+ derived from the generated UUID.
+ The generation of UUIDs by this method has no random or
+ environment-dependent element and is therefore reproducible.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_generate_v4</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Generates a version 4 UUID, which is derived entirely
+ from random numbers.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_generate_v5</code> ( <em class="parameter"><code>namespace</code></em> <code class="type">uuid</code>, <em class="parameter"><code>name</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Generates a version 5 UUID, which works like a version 3
+ UUID except that SHA-1 is used as a hashing method. Version 5 should
+ be preferred over version 3 because SHA-1 is thought to be more secure
+ than MD5.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="UUID-OSSP-CONSTANTS"><p class="title"><strong>Table F.33. Functions Returning UUID Constants</strong></p><div class="table-contents"><table class="table" summary="Functions Returning UUID Constants" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_nil</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Returns a <span class="quote">“<span class="quote">nil</span>”</span> UUID constant, which does not occur as a
+ real UUID.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_ns_dns</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Returns a constant designating the DNS namespace for UUIDs.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_ns_url</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Returns a constant designating the URL namespace for UUIDs.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_ns_oid</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Returns a constant designating the ISO object identifier (OID) namespace for
+ UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs
+ used in <span class="productname">PostgreSQL</span>.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">uuid_ns_x500</code> ()
+ → <code class="returnvalue">uuid</code>
+ </p>
+ <p>
+ Returns a constant designating the X.500 distinguished name (DN)
+ namespace for UUIDs.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.58.6"><div class="titlepage"><div><div><h3 class="title">F.49.2. Building <code class="filename">uuid-ossp</code></h3></div></div></div><p>
+ Historically this module depended on the OSSP UUID library, which accounts
+ for the module's name. While the OSSP UUID library can still be found
+ at <a class="ulink" href="http://www.ossp.org/pkg/lib/uuid/" target="_top">http://www.ossp.org/pkg/lib/uuid/</a>, it is not well
+ maintained, and is becoming increasingly difficult to port to newer
+ platforms. <code class="filename">uuid-ossp</code> can now be built without the OSSP
+ library on some platforms. On FreeBSD and some other BSD-derived
+ platforms, suitable UUID creation functions are included in the
+ core <code class="filename">libc</code> library. On Linux, macOS, and some other
+ platforms, suitable functions are provided in the <code class="filename">libuuid</code>
+ library, which originally came from the <code class="literal">e2fsprogs</code> project
+ (though on modern Linux it is considered part
+ of <code class="literal">util-linux-ng</code>). When invoking <code class="filename">configure</code>,
+ specify <code class="option">--with-uuid=bsd</code> to use the BSD functions,
+ or <code class="option">--with-uuid=e2fs</code> to
+ use <code class="literal">e2fsprogs</code>' <code class="filename">libuuid</code>, or
+ <code class="option">--with-uuid=ossp</code> to use the OSSP UUID library.
+ More than one of these libraries might be available on a particular
+ machine, so <code class="filename">configure</code> does not automatically choose one.
+ </p></div><div class="sect2" id="id-1.11.7.58.7"><div class="titlepage"><div><div><h3 class="title">F.49.3. Author</h3></div></div></div><p>
+ Peter Eisentraut <code class="email">&lt;<a class="email" href="mailto:peter_e@gmx.net">peter_e@gmx.net</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unaccent.html" title="F.48. unaccent">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xml2.html" title="F.50. xml2">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.48. unaccent </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.50. xml2</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/vacuumlo.html b/doc/src/sgml/html/vacuumlo.html
new file mode 100644
index 0000000..16e6b05
--- /dev/null
+++ b/doc/src/sgml/html/vacuumlo.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>vacuumlo</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="oid2name.html" title="oid2name" /><link rel="next" href="contrib-prog-server.html" title="G.2. Server Applications" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">vacuumlo</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="oid2name.html" title="oid2name">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib-prog-client.html" title="G.1. Client Applications">Up</a></td><th width="60%" align="center">G.1. Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-prog-server.html" title="G.2. Server Applications">Next</a></td></tr></table><hr /></div><div class="refentry" id="VACUUMLO"><div class="titlepage"></div><a id="id-1.11.8.4.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">vacuumlo</span></span></h2><p>vacuumlo — remove orphaned large objects from a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.11.8.4.4.4.1"><code class="command">vacuumlo</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>dbname</code></em>... </p></div></div><div class="refsect1" id="id-1.11.8.4.4.5"><h2>Description</h2><p>
+ <span class="application">vacuumlo</span> is a simple utility program that will remove any
+ <span class="quote">“<span class="quote">orphaned</span>”</span> large objects from a
+ <span class="productname">PostgreSQL</span> database. An orphaned large object (LO) is
+ considered to be any LO whose OID does not appear in any <code class="type">oid</code> or
+ <code class="type">lo</code> data column of the database.
+ </p><p>
+ If you use this, you may also be interested in the <code class="function">lo_manage</code>
+ trigger in the <a class="xref" href="lo.html" title="F.22. lo">lo</a> module.
+ <code class="function">lo_manage</code> is useful to try
+ to avoid creating orphaned LOs in the first place.
+ </p><p>
+ All databases named on the command line are processed.
+ </p></div><div class="refsect1" id="id-1.11.8.4.4.6"><h2>Options</h2><p>
+ <span class="application">vacuumlo</span> accepts the following command-line arguments:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-l <em class="replaceable"><code>limit</code></em></code><br /></span><span class="term"><code class="option">--limit=<em class="replaceable"><code>limit</code></em></code></span></dt><dd><p>
+ Remove no more than <em class="replaceable"><code>limit</code></em> large objects per
+ transaction (default 1000). Since the server acquires a lock per LO
+ removed, removing too many LOs in one transaction risks exceeding
+ <a class="xref" href="runtime-config-locks.html#GUC-MAX-LOCKS-PER-TRANSACTION">max_locks_per_transaction</a>. Set the limit to
+ zero if you want all removals done in a single transaction.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>Don't remove anything, just show what would be done.</p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>Write a lot of progress messages.</p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">vacuumlo</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">vacuumlo</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">vacuumlo</span> also accepts the following command-line
+ arguments for connection parameters:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>Database server's host.</p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>Database server's port.</p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>User name to connect as.</p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires password
+ authentication and a password is not available by other means
+ such as a <code class="filename">.pgpass</code> file, the connection
+ attempt will fail. This option can be useful in batch jobs and
+ scripts where no user is present to enter a password.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">vacuumlo</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">vacuumlo</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">vacuumlo</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.11.8.4.4.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
+ Default connection parameters.
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.11.8.4.4.8"><h2>Notes</h2><p>
+ <span class="application">vacuumlo</span> works by the following method:
+ First, <span class="application">vacuumlo</span> builds a temporary table which contains all
+ of the OIDs of the large objects in the selected database. It then scans
+ through all columns in the database that are of type
+ <code class="type">oid</code> or <code class="type">lo</code>, and removes matching entries from the temporary
+ table. (Note: Only types with these names are considered; in particular,
+ domains over them are not considered.) The remaining entries in the
+ temporary table identify orphaned LOs. These are removed.
+ </p></div><div class="refsect1" id="id-1.11.8.4.4.9"><h2>Author</h2><p>
+ Peter Mount <code class="email">&lt;<a class="email" href="mailto:peter@retep.org.uk">peter@retep.org.uk</a>&gt;</code>
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oid2name.html" title="oid2name">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib-prog-client.html" title="G.1. Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-prog-server.html" title="G.2. Server Applications">Next</a></td></tr><tr><td width="40%" align="left" valign="top">oid2name </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> G.2. Server Applications</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-available-extension-versions.html b/doc/src/sgml/html/view-pg-available-extension-versions.html
new file mode 100644
index 0000000..cf3406d
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-available-extension-versions.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.3. pg_available_extension_versions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions" /><link rel="next" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.3. <code class="structname">pg_available_extension_versions</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-AVAILABLE-EXTENSION-VERSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.3. <code class="structname">pg_available_extension_versions</code></h2></div></div></div><a id="id-1.10.5.7.2" class="indexterm"></a><p>
+ The <code class="structname">pg_available_extension_versions</code> view lists the
+ specific extension versions that are available for installation.
+ See also the <a class="link" href="catalog-pg-extension.html" title="53.22. pg_extension"><code class="structname">pg_extension</code></a>
+ catalog, which shows the extensions currently installed.
+ </p><div class="table" id="id-1.10.5.7.4"><p class="title"><strong>Table 54.3. <code class="structname">pg_available_extension_versions</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_available_extension_versions Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">name</code>
+ </p>
+ <p>
+ Extension name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">version</code> <code class="type">text</code>
+ </p>
+ <p>
+ Version name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">installed</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this version of this extension is currently
+ installed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">superuser</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if only superusers are allowed to install this extension
+ (but see <code class="structfield">trusted</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">trusted</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the extension can be installed by non-superusers
+ with appropriate privileges
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relocatable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if extension can be relocated to another schema
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schema</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the schema that the extension must be installed into,
+ or <code class="literal">NULL</code> if partially or fully relocatable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">requires</code> <code class="type">name[]</code>
+ </p>
+ <p>
+ Names of prerequisite extensions,
+ or <code class="literal">NULL</code> if none
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comment</code> <code class="type">text</code>
+ </p>
+ <p>
+ Comment string from the extension's control file
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_available_extension_versions</code> view is
+ read-only.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.2. <code class="structname">pg_available_extensions</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.4. <code class="structname">pg_backend_memory_contexts</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-available-extensions.html b/doc/src/sgml/html/view-pg-available-extensions.html
new file mode 100644
index 0000000..66414e4
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-available-extensions.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.2. pg_available_extensions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="views-overview.html" title="54.1. Overview" /><link rel="next" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.2. <code class="structname">pg_available_extensions</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="views-overview.html" title="54.1. Overview">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-AVAILABLE-EXTENSIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.2. <code class="structname">pg_available_extensions</code></h2></div></div></div><a id="id-1.10.5.6.2" class="indexterm"></a><p>
+ The <code class="structname">pg_available_extensions</code> view lists the
+ extensions that are available for installation.
+ See also the
+ <a class="link" href="catalog-pg-extension.html" title="53.22. pg_extension"><code class="structname">pg_extension</code></a>
+ catalog, which shows the extensions currently installed.
+ </p><div class="table" id="id-1.10.5.6.4"><p class="title"><strong>Table 54.2. <code class="structname">pg_available_extensions</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_available_extensions Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">name</code>
+ </p>
+ <p>
+ Extension name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">default_version</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of default version, or <code class="literal">NULL</code> if none is
+ specified
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">installed_version</code> <code class="type">text</code>
+ </p>
+ <p>
+ Currently installed version of the extension,
+ or <code class="literal">NULL</code> if not installed
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">comment</code> <code class="type">text</code>
+ </p>
+ <p>
+ Comment string from the extension's control file
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_available_extensions</code> view is read-only.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="views-overview.html" title="54.1. Overview">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.1. Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.3. <code class="structname">pg_available_extension_versions</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-backend-memory-contexts.html b/doc/src/sgml/html/view-pg-backend-memory-contexts.html
new file mode 100644
index 0000000..35d64a3
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-backend-memory-contexts.html
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.4. pg_backend_memory_contexts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions" /><link rel="next" href="view-pg-config.html" title="54.5. pg_config" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.4. <code class="structname">pg_backend_memory_contexts</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-config.html" title="54.5. pg_config">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-BACKEND-MEMORY-CONTEXTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.4. <code class="structname">pg_backend_memory_contexts</code></h2></div></div></div><a id="id-1.10.5.8.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_backend_memory_contexts</code> displays all
+ the memory contexts of the server process attached to the current session.
+ </p><p>
+ <code class="structname">pg_backend_memory_contexts</code> contains one row
+ for each memory context.
+ </p><div class="table" id="id-1.10.5.8.5"><p class="title"><strong>Table 54.4. <code class="structname">pg_backend_memory_contexts</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_backend_memory_contexts Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the memory context
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ident</code> <code class="type">text</code>
+ </p>
+ <p>
+ Identification information of the memory context. This field is truncated at 1024 bytes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parent</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the parent of this memory context
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">level</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Distance from TopMemoryContext in context tree
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_bytes</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Total bytes allocated for this memory context
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">total_nblocks</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Total number of blocks allocated for this memory context
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">free_bytes</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Free space in bytes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">free_chunks</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Total number of free chunks
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">used_bytes</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Used space in bytes
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ By default, the <code class="structname">pg_backend_memory_contexts</code> view can be
+ read only by superusers or roles with the privileges of the
+ <code class="literal">pg_read_all_stats</code> role.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-config.html" title="54.5. pg_config">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.3. <code class="structname">pg_available_extension_versions</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.5. <code class="structname">pg_config</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-config.html b/doc/src/sgml/html/view-pg-config.html
new file mode 100644
index 0000000..14e66e5
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-config.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.5. pg_config</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts" /><link rel="next" href="view-pg-cursors.html" title="54.6. pg_cursors" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.5. <code class="structname">pg_config</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-cursors.html" title="54.6. pg_cursors">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-CONFIG"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.5. <code class="structname">pg_config</code></h2></div></div></div><a id="id-1.10.5.9.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_config</code> describes the
+ compile-time configuration parameters of the currently installed
+ version of <span class="productname">PostgreSQL</span>. It is intended, for example, to
+ be used by software packages that want to interface to
+ <span class="productname">PostgreSQL</span> to facilitate finding the required header
+ files and libraries. It provides the same basic information as the
+ <a class="xref" href="app-pgconfig.html" title="pg_config"><span class="refentrytitle"><span class="application">pg_config</span></span></a> <span class="productname">PostgreSQL</span> client
+ application.
+ </p><p>
+ By default, the <code class="structname">pg_config</code> view can be read
+ only by superusers.
+ </p><div class="table" id="id-1.10.5.9.5"><p class="title"><strong>Table 54.5. <code class="structname">pg_config</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_config Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ The parameter name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setting</code> <code class="type">text</code>
+ </p>
+ <p>
+ The parameter value
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-cursors.html" title="54.6. pg_cursors">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.4. <code class="structname">pg_backend_memory_contexts</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.6. <code class="structname">pg_cursors</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-cursors.html b/doc/src/sgml/html/view-pg-cursors.html
new file mode 100644
index 0000000..ccda25f
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-cursors.html
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.6. pg_cursors</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-config.html" title="54.5. pg_config" /><link rel="next" href="view-pg-file-settings.html" title="54.7. pg_file_settings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.6. <code class="structname">pg_cursors</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-config.html" title="54.5. pg_config">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-file-settings.html" title="54.7. pg_file_settings">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-CURSORS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.6. <code class="structname">pg_cursors</code></h2></div></div></div><a id="id-1.10.5.10.2" class="indexterm"></a><p>
+ The <code class="structname">pg_cursors</code> view lists the cursors that
+ are currently available. Cursors can be defined in several ways:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ via the <a class="link" href="sql-declare.html" title="DECLARE"><code class="command">DECLARE</code></a>
+ statement in SQL
+ </p></li><li class="listitem"><p>
+ via the Bind message in the frontend/backend protocol, as
+ described in <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="55.2.3. Extended Query">Section 55.2.3</a>
+ </p></li><li class="listitem"><p>
+ via the Server Programming Interface (SPI), as described in
+ <a class="xref" href="spi-interface.html" title="47.1. Interface Functions">Section 47.1</a>
+ </p></li></ul></div><p>
+
+ The <code class="structname">pg_cursors</code> view displays cursors
+ created by any of these means. Cursors only exist for the duration
+ of the transaction that defines them, unless they have been
+ declared <code class="literal">WITH HOLD</code>. Therefore non-holdable
+ cursors are only present in the view until the end of their
+ creating transaction.
+
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Cursors are used internally to implement some of the components
+ of <span class="productname">PostgreSQL</span>, such as procedural languages.
+ Therefore, the <code class="structname">pg_cursors</code> view might include cursors
+ that have not been explicitly created by the user.
+ </p></div><p>
+ </p><div class="table" id="id-1.10.5.10.4"><p class="title"><strong>Table 54.6. <code class="structname">pg_cursors</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_cursors Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ The name of the cursor
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statement</code> <code class="type">text</code>
+ </p>
+ <p>
+ The verbatim query string submitted to declare this cursor
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_holdable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> if the cursor is holdable (that is, it
+ can be accessed after the transaction that declared the cursor
+ has committed); <code class="literal">false</code> otherwise
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_binary</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> if the cursor was declared
+ <code class="literal">BINARY</code>; <code class="literal">false</code>
+ otherwise
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_scrollable</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> if the cursor is scrollable (that is, it
+ allows rows to be retrieved in a nonsequential manner);
+ <code class="literal">false</code> otherwise
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">creation_time</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ The time at which the cursor was declared
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_cursors</code> view is read-only.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-config.html" title="54.5. pg_config">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-file-settings.html" title="54.7. pg_file_settings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.5. <code class="structname">pg_config</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.7. <code class="structname">pg_file_settings</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-file-settings.html b/doc/src/sgml/html/view-pg-file-settings.html
new file mode 100644
index 0000000..611f252
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-file-settings.html
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.7. pg_file_settings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-cursors.html" title="54.6. pg_cursors" /><link rel="next" href="view-pg-group.html" title="54.8. pg_group" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.7. <code class="structname">pg_file_settings</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-cursors.html" title="54.6. pg_cursors">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-group.html" title="54.8. pg_group">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-FILE-SETTINGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.7. <code class="structname">pg_file_settings</code></h2></div></div></div><a id="id-1.10.5.11.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_file_settings</code> provides a summary of
+ the contents of the server's configuration file(s). A row appears in
+ this view for each <span class="quote">“<span class="quote">name = value</span>”</span> entry appearing in the files,
+ with annotations indicating whether the value could be applied
+ successfully. Additional row(s) may appear for problems not linked to
+ a <span class="quote">“<span class="quote">name = value</span>”</span> entry, such as syntax errors in the files.
+ </p><p>
+ This view is helpful for checking whether planned changes in the
+ configuration files will work, or for diagnosing a previous failure.
+ Note that this view reports on the <span class="emphasis"><em>current</em></span> contents of the
+ files, not on what was last applied by the server. (The
+ <a class="link" href="view-pg-settings.html" title="54.24. pg_settings"><code class="structname">pg_settings</code></a>
+ view is usually sufficient to determine that.)
+ </p><p>
+ By default, the <code class="structname">pg_file_settings</code> view can be read
+ only by superusers.
+ </p><div class="table" id="id-1.10.5.11.6"><p class="title"><strong>Table 54.7. <code class="structname">pg_file_settings</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_file_settings Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sourcefile</code> <code class="type">text</code>
+ </p>
+ <p>
+ Full path name of the configuration file
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sourceline</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Line number within the configuration file where the entry appears
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">seqno</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Order in which the entries are processed (1..<em class="replaceable"><code>n</code></em>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Configuration parameter name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setting</code> <code class="type">text</code>
+ </p>
+ <p>
+ Value to be assigned to the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">applied</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the value can be applied successfully
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">error</code> <code class="type">text</code>
+ </p>
+ <p>
+ If not null, an error message indicating why this entry could
+ not be applied
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ If the configuration file contains syntax errors or invalid parameter
+ names, the server will not attempt to apply any settings from it, and
+ therefore all the <code class="structfield">applied</code> fields will read as false.
+ In such a case there will be one or more rows with
+ non-null <code class="structfield">error</code> fields indicating the
+ problem(s). Otherwise, individual settings will be applied if possible.
+ If an individual setting cannot be applied (e.g., invalid value, or the
+ setting cannot be changed after server start) it will have an appropriate
+ message in the <code class="structfield">error</code> field. Another way that
+ an entry might have <code class="structfield">applied</code> = false is that it is
+ overridden by a later entry for the same parameter name; this case is not
+ considered an error so nothing appears in
+ the <code class="structfield">error</code> field.
+ </p><p>
+ See <a class="xref" href="config-setting.html" title="20.1. Setting Parameters">Section 20.1</a> for more information about the various
+ ways to change run-time parameters.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-cursors.html" title="54.6. pg_cursors">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-group.html" title="54.8. pg_group">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.6. <code class="structname">pg_cursors</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.8. <code class="structname">pg_group</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-group.html b/doc/src/sgml/html/view-pg-group.html
new file mode 100644
index 0000000..a1b4259
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-group.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.8. pg_group</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-file-settings.html" title="54.7. pg_file_settings" /><link rel="next" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.8. <code class="structname">pg_group</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-file-settings.html" title="54.7. pg_file_settings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-GROUP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.8. <code class="structname">pg_group</code></h2></div></div></div><a id="id-1.10.5.12.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_group</code> exists for backwards
+ compatibility: it emulates a catalog that existed in
+ <span class="productname">PostgreSQL</span> before version 8.1.
+ It shows the names and members of all roles that are marked as not
+ <code class="structfield">rolcanlogin</code>, which is an approximation to the set
+ of roles that are being used as groups.
+ </p><div class="table" id="id-1.10.5.12.4"><p class="title"><strong>Table 54.8. <code class="structname">pg_group</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_group Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">groname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of the group
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grosysid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of this group
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">grolist</code> <code class="type">oid[]</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ An array containing the IDs of the roles in this group
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-file-settings.html" title="54.7. pg_file_settings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.7. <code class="structname">pg_file_settings</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.9. <code class="structname">pg_hba_file_rules</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-hba-file-rules.html b/doc/src/sgml/html/view-pg-hba-file-rules.html
new file mode 100644
index 0000000..3a1de1d
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-hba-file-rules.html
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.9. pg_hba_file_rules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-group.html" title="54.8. pg_group" /><link rel="next" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.9. <code class="structname">pg_hba_file_rules</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-group.html" title="54.8. pg_group">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-HBA-FILE-RULES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.9. <code class="structname">pg_hba_file_rules</code></h2></div></div></div><a id="id-1.10.5.13.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_hba_file_rules</code> provides a summary of
+ the contents of the client authentication configuration file,
+ <a class="link" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File"><code class="filename">pg_hba.conf</code></a>.
+ A row appears in this view for each
+ non-empty, non-comment line in the file, with annotations indicating
+ whether the rule could be applied successfully.
+ </p><p>
+ This view can be helpful for checking whether planned changes in the
+ authentication configuration file will work, or for diagnosing a previous
+ failure. Note that this view reports on the <span class="emphasis"><em>current</em></span> contents
+ of the file, not on what was last loaded by the server.
+ </p><p>
+ By default, the <code class="structname">pg_hba_file_rules</code> view can be read
+ only by superusers.
+ </p><div class="table" id="id-1.10.5.13.6"><p class="title"><strong>Table 54.9. <code class="structname">pg_hba_file_rules</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_hba_file_rules Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">line_number</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Line number of this rule in <code class="filename">pg_hba.conf</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">type</code> <code class="type">text</code>
+ </p>
+ <p>
+ Type of connection
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">database</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ List of database name(s) to which this rule applies
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">user_name</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ List of user and group name(s) to which this rule applies
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">address</code> <code class="type">text</code>
+ </p>
+ <p>
+ Host name or IP address, or one
+ of <code class="literal">all</code>, <code class="literal">samehost</code>,
+ or <code class="literal">samenet</code>, or null for local connections
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">netmask</code> <code class="type">text</code>
+ </p>
+ <p>
+ IP address mask, or null if not applicable
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">auth_method</code> <code class="type">text</code>
+ </p>
+ <p>
+ Authentication method
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">options</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Options specified for authentication method, if any
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">error</code> <code class="type">text</code>
+ </p>
+ <p>
+ If not null, an error message indicating why this
+ line could not be processed
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Usually, a row reflecting an incorrect entry will have values for only
+ the <code class="structfield">line_number</code> and <code class="structfield">error</code> fields.
+ </p><p>
+ See <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> for more information about
+ client authentication configuration.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-group.html" title="54.8. pg_group">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.8. <code class="structname">pg_group</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.10. <code class="structname">pg_ident_file_mappings</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-ident-file-mappings.html b/doc/src/sgml/html/view-pg-ident-file-mappings.html
new file mode 100644
index 0000000..be8d3be
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-ident-file-mappings.html
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.10. pg_ident_file_mappings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules" /><link rel="next" href="view-pg-indexes.html" title="54.11. pg_indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.10. <code class="structname">pg_ident_file_mappings</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-indexes.html" title="54.11. pg_indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-IDENT-FILE-MAPPINGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.10. <code class="structname">pg_ident_file_mappings</code></h2></div></div></div><a id="id-1.10.5.14.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_ident_file_mappings</code> provides a summary
+ of the contents of the client user name mapping configuration file,
+ <a class="link" href="auth-username-maps.html" title="21.2. User Name Maps"><code class="filename">pg_ident.conf</code></a>.
+ A row appears in this view for each non-empty, non-comment line in the file,
+ with annotations indicating whether the map could be applied successfully.
+ </p><p>
+ This view can be helpful for checking whether planned changes in the
+ authentication configuration file will work, or for diagnosing a previous
+ failure. Note that this view reports on the <span class="emphasis"><em>current</em></span>
+ contents of the file, not on what was last loaded by the server.
+ </p><p>
+ By default, the <code class="structname">pg_ident_file_mappings</code> view can be
+ read only by superusers.
+ </p><div class="table" id="id-1.10.5.14.6"><p class="title"><strong>Table 54.10. <code class="structname">pg_ident_file_mappings</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_ident_file_mappings Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">line_number</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Line number of this map in <code class="filename">pg_ident.conf</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">map_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the map
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sys_name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Detected user name of the client
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pg_username</code> <code class="type">text</code>
+ </p>
+ <p>
+ Requested PostgreSQL user name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">error</code> <code class="type">text</code>
+ </p>
+ <p>
+ If not <code class="literal">NULL</code>, an error message indicating why this
+ line could not be processed
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Usually, a row reflecting an incorrect entry will have values for only
+ the <code class="structfield">line_number</code> and <code class="structfield">error</code> fields.
+ </p><p>
+ See <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a> for more information about
+ client authentication configuration.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-indexes.html" title="54.11. pg_indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.9. <code class="structname">pg_hba_file_rules</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.11. <code class="structname">pg_indexes</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-indexes.html b/doc/src/sgml/html/view-pg-indexes.html
new file mode 100644
index 0000000..8f8cb53
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-indexes.html
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.11. pg_indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings" /><link rel="next" href="view-pg-locks.html" title="54.12. pg_locks" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.11. <code class="structname">pg_indexes</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-locks.html" title="54.12. pg_locks">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-INDEXES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.11. <code class="structname">pg_indexes</code></h2></div></div></div><a id="id-1.10.5.15.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_indexes</code> provides access to
+ useful information about each index in the database.
+ </p><div class="table" id="id-1.10.5.15.4"><p class="title"><strong>Table 54.11. <code class="structname">pg_indexes</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_indexes Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table and index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table the index is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of index
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablespace</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">spcname</code>)
+ </p>
+ <p>
+ Name of tablespace containing index (null if default for database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">indexdef</code> <code class="type">text</code>
+ </p>
+ <p>
+ Index definition (a reconstructed <a class="xref" href="sql-createindex.html" title="CREATE INDEX"><span class="refentrytitle">CREATE INDEX</span></a>
+ command)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-locks.html" title="54.12. pg_locks">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.10. <code class="structname">pg_ident_file_mappings</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.12. <code class="structname">pg_locks</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-locks.html b/doc/src/sgml/html/view-pg-locks.html
new file mode 100644
index 0000000..1dfd859
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-locks.html
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.12. pg_locks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-indexes.html" title="54.11. pg_indexes" /><link rel="next" href="view-pg-matviews.html" title="54.13. pg_matviews" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.12. <code class="structname">pg_locks</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-indexes.html" title="54.11. pg_indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-matviews.html" title="54.13. pg_matviews">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-LOCKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.12. <code class="structname">pg_locks</code></h2></div></div></div><a id="id-1.10.5.16.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_locks</code> provides access to
+ information about the locks held by active processes within the
+ database server. See <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a> for more discussion
+ of locking.
+ </p><p>
+ <code class="structname">pg_locks</code> contains one row per active lockable
+ object, requested lock mode, and relevant process. Thus, the same
+ lockable object might
+ appear many times, if multiple processes are holding or waiting
+ for locks on it. However, an object that currently has no locks on it
+ will not appear at all.
+ </p><p>
+ There are several distinct types of lockable objects:
+ whole relations (e.g., tables), individual pages of relations,
+ individual tuples of relations,
+ transaction IDs (both virtual and permanent IDs),
+ and general database objects (identified by class OID and object OID,
+ in the same way as in <a class="link" href="catalog-pg-description.html" title="53.19. pg_description"><code class="structname">pg_description</code></a> or
+ <a class="link" href="catalog-pg-depend.html" title="53.18. pg_depend"><code class="structname">pg_depend</code></a>). Also, the right to extend a
+ relation is represented as a separate lockable object, as is the right to
+ update <code class="structname">pg_database</code>.<code class="structfield">datfrozenxid</code>.
+ Also, <span class="quote">“<span class="quote">advisory</span>”</span> locks can be taken on numbers that have
+ user-defined meanings.
+ </p><div class="table" id="id-1.10.5.16.6"><p class="title"><strong>Table 54.12. <code class="structname">pg_locks</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_locks Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">locktype</code> <code class="type">text</code>
+ </p>
+ <p>
+ Type of the lockable object:
+ <code class="literal">relation</code>,
+ <code class="literal">extend</code>,
+ <code class="literal">frozenid</code>,
+ <code class="literal">page</code>,
+ <code class="literal">tuple</code>,
+ <code class="literal">transactionid</code>,
+ <code class="literal">virtualxid</code>,
+ <code class="literal">spectoken</code>,
+ <code class="literal">object</code>,
+ <code class="literal">userlock</code>, or
+ <code class="literal">advisory</code>.
+ (See also <a class="xref" href="monitoring-stats.html#WAIT-EVENT-LOCK-TABLE" title="Table 28.11. Wait Events of Type Lock">Table 28.11</a>.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">database</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the database in which the lock target exists, or
+ zero if the target is a shared object, or
+ null if the target is a transaction ID
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">relation</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the relation targeted by the lock, or null if the target is not
+ a relation or part of a relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">page</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Page number targeted by the lock within the relation,
+ or null if the target is not a relation page or tuple
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tuple</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Tuple number targeted by the lock within the page,
+ or null if the target is not a tuple
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">virtualxid</code> <code class="type">text</code>
+ </p>
+ <p>
+ Virtual ID of the transaction targeted by the lock,
+ or null if the target is not a virtual transaction ID
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">transactionid</code> <code class="type">xid</code>
+ </p>
+ <p>
+ ID of the transaction targeted by the lock,
+ or null if the target is not a transaction ID
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the system catalog containing the lock target, or null if the
+ target is not a general database object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ OID of the lock target within its system catalog, or null if the
+ target is not a general database object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int2</code>
+ </p>
+ <p>
+ Column number targeted by the lock (the
+ <code class="structfield">classid</code> and <code class="structfield">objid</code> refer to the
+ table itself),
+ or zero if the target is some other general database object,
+ or null if the target is not a general database object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">virtualtransaction</code> <code class="type">text</code>
+ </p>
+ <p>
+ Virtual ID of the transaction that is holding or awaiting this lock
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Process ID of the server process holding or awaiting this
+ lock, or null if the lock is held by a prepared transaction
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">mode</code> <code class="type">text</code>
+ </p>
+ <p>
+ Name of the lock mode held or desired by this process (see <a class="xref" href="explicit-locking.html#LOCKING-TABLES" title="13.3.1. Table-Level Locks">Section 13.3.1</a> and <a class="xref" href="transaction-iso.html#XACT-SERIALIZABLE" title="13.2.3. Serializable Isolation Level">Section 13.2.3</a>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">granted</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if lock is held, false if lock is awaited
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">fastpath</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if lock was taken via fast path, false if taken via main
+ lock table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">waitstart</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Time when the server process started waiting for this lock,
+ or null if the lock is held.
+ Note that this can be null for a very short period of time after
+ the wait started even though <code class="structfield">granted</code>
+ is <code class="literal">false</code>.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ <code class="structfield">granted</code> is true in a row representing a lock
+ held by the indicated process. False indicates that this process is
+ currently waiting to acquire this lock, which implies that at least one
+ other process is holding or waiting for a conflicting lock mode on the same
+ lockable object. The waiting process will sleep until the other lock is
+ released (or a deadlock situation is detected). A single process can be
+ waiting to acquire at most one lock at a time.
+ </p><p>
+ Throughout running a transaction, a server process holds an exclusive lock
+ on the transaction's virtual transaction ID. If a permanent ID is assigned
+ to the transaction (which normally happens only if the transaction changes
+ the state of the database), it also holds an exclusive lock on the
+ transaction's permanent transaction ID until it ends. When a process finds
+ it necessary to wait specifically for another transaction to end, it does
+ so by attempting to acquire share lock on the other transaction's ID
+ (either virtual or permanent ID depending on the situation). That will
+ succeed only when the other transaction terminates and releases its locks.
+ </p><p>
+ Although tuples are a lockable type of object,
+ information about row-level locks is stored on disk, not in memory,
+ and therefore row-level locks normally do not appear in this view.
+ If a process is waiting for a
+ row-level lock, it will usually appear in the view as waiting for the
+ permanent transaction ID of the current holder of that row lock.
+ </p><p>
+ Advisory locks can be acquired on keys consisting of either a single
+ <code class="type">bigint</code> value or two integer values.
+ A <code class="type">bigint</code> key is displayed with its
+ high-order half in the <code class="structfield">classid</code> column, its low-order half
+ in the <code class="structfield">objid</code> column, and <code class="structfield">objsubid</code> equal
+ to 1. The original <code class="type">bigint</code> value can be reassembled with the
+ expression <code class="literal">(classid::bigint &lt;&lt; 32) |
+ objid::bigint</code>. Integer keys are displayed with the
+ first key in the
+ <code class="structfield">classid</code> column, the second key in the <code class="structfield">objid</code>
+ column, and <code class="structfield">objsubid</code> equal to 2. The actual meaning of
+ the keys is up to the user. Advisory locks are local to each database,
+ so the <code class="structfield">database</code> column is meaningful for an advisory lock.
+ </p><p>
+ <code class="structname">pg_locks</code> provides a global view of all locks
+ in the database cluster, not only those relevant to the current database.
+ Although its <code class="structfield">relation</code> column can be joined
+ against <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code> to identify locked
+ relations, this will only work correctly for relations in the current
+ database (those for which the <code class="structfield">database</code> column
+ is either the current database's OID or zero).
+ </p><p>
+ The <code class="structfield">pid</code> column can be joined to the
+ <code class="structfield">pid</code> column of the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW" title="28.2.3. pg_stat_activity">
+ <code class="structname">pg_stat_activity</code></a>
+ view to get more
+ information on the session holding or awaiting each lock,
+ for example
+</p><pre class="programlisting">
+SELECT * FROM pg_locks pl LEFT JOIN pg_stat_activity psa
+ ON pl.pid = psa.pid;
+</pre><p>
+ Also, if you are using prepared transactions, the
+ <code class="structfield">virtualtransaction</code> column can be joined to the
+ <code class="structfield">transaction</code> column of the <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a>
+ view to get more information on prepared transactions that hold locks.
+ (A prepared transaction can never be waiting for a lock,
+ but it continues to hold the locks it acquired while running.)
+ For example:
+</p><pre class="programlisting">
+SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
+ ON pl.virtualtransaction = '-1/' || ppx.transaction;
+</pre><p>
+ </p><p>
+ While it is possible to obtain information about which processes block
+ which other processes by joining <code class="structname">pg_locks</code> against
+ itself, this is very difficult to get right in detail. Such a query would
+ have to encode knowledge about which lock modes conflict with which
+ others. Worse, the <code class="structname">pg_locks</code> view does not expose
+ information about which processes are ahead of which others in lock wait
+ queues, nor information about which processes are parallel workers running
+ on behalf of which other client sessions. It is better to use
+ the <code class="function">pg_blocking_pids()</code> function
+ (see <a class="xref" href="functions-info.html#FUNCTIONS-INFO-SESSION-TABLE" title="Table 9.66. Session Information Functions">Table 9.66</a>) to identify which
+ process(es) a waiting process is blocked behind.
+ </p><p>
+ The <code class="structname">pg_locks</code> view displays data from both the
+ regular lock manager and the predicate lock manager, which are
+ separate systems; in addition, the regular lock manager subdivides its
+ locks into regular and <em class="firstterm">fast-path</em> locks.
+ This data is not guaranteed to be entirely consistent.
+ When the view is queried,
+ data on fast-path locks (with <code class="structfield">fastpath</code> = <code class="literal">true</code>)
+ is gathered from each backend one at a time, without freezing the state of
+ the entire lock manager, so it is possible for locks to be taken or
+ released while information is gathered. Note, however, that these locks are
+ known not to conflict with any other lock currently in place. After
+ all backends have been queried for fast-path locks, the remainder of the
+ regular lock manager is locked as a unit, and a consistent snapshot of all
+ remaining locks is collected as an atomic action. After unlocking the
+ regular lock manager, the predicate lock manager is similarly locked and all
+ predicate locks are collected as an atomic action. Thus, with the exception
+ of fast-path locks, each lock manager will deliver a consistent set of
+ results, but as we do not lock both lock managers simultaneously, it is
+ possible for locks to be taken or released after we interrogate the regular
+ lock manager and before we interrogate the predicate lock manager.
+ </p><p>
+ Locking the regular and/or predicate lock manager could have some
+ impact on database performance if this view is very frequently accessed.
+ The locks are held only for the minimum amount of time necessary to
+ obtain data from the lock managers, but this does not completely eliminate
+ the possibility of a performance impact.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-indexes.html" title="54.11. pg_indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-matviews.html" title="54.13. pg_matviews">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.11. <code class="structname">pg_indexes</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.13. <code class="structname">pg_matviews</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-matviews.html b/doc/src/sgml/html/view-pg-matviews.html
new file mode 100644
index 0000000..a14ec1c
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-matviews.html
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.13. pg_matviews</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-locks.html" title="54.12. pg_locks" /><link rel="next" href="view-pg-policies.html" title="54.14. pg_policies" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.13. <code class="structname">pg_matviews</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-locks.html" title="54.12. pg_locks">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-policies.html" title="54.14. pg_policies">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-MATVIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.13. <code class="structname">pg_matviews</code></h2></div></div></div><a id="id-1.10.5.17.2" class="indexterm"></a><a id="id-1.10.5.17.3" class="indexterm"></a><p>
+ The view <code class="structname">pg_matviews</code> provides access to
+ useful information about each materialized view in the database.
+ </p><div class="table" id="id-1.10.5.17.5"><p class="title"><strong>Table 54.13. <code class="structname">pg_matviews</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_matviews Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing materialized view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">matviewname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of materialized view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">matviewowner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of materialized view's owner
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablespace</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">spcname</code>)
+ </p>
+ <p>
+ Name of tablespace containing materialized view (null if default for database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">hasindexes</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if materialized view has (or recently had) any indexes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">ispopulated</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if materialized view is currently populated
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">definition</code> <code class="type">text</code>
+ </p>
+ <p>
+ Materialized view definition (a reconstructed <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> query)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-locks.html" title="54.12. pg_locks">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-policies.html" title="54.14. pg_policies">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.12. <code class="structname">pg_locks</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.14. <code class="structname">pg_policies</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-policies.html b/doc/src/sgml/html/view-pg-policies.html
new file mode 100644
index 0000000..c123ca8
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-policies.html
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.14. pg_policies</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-matviews.html" title="54.13. pg_matviews" /><link rel="next" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.14. <code class="structname">pg_policies</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-matviews.html" title="54.13. pg_matviews">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-POLICIES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.14. <code class="structname">pg_policies</code></h2></div></div></div><a id="id-1.10.5.18.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_policies</code> provides access to
+ useful information about each row-level security policy in the database.
+ </p><div class="table" id="id-1.10.5.18.4"><p class="title"><strong>Table 54.14. <code class="structname">pg_policies</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_policies Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table policy is on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table policy is on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">policyname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-policy.html" title="53.38. pg_policy"><code class="structname">pg_policy</code></a>.<code class="structfield">polname</code>)
+ </p>
+ <p>
+ Name of policy
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">permissive</code> <code class="type">text</code>
+ </p>
+ <p>
+ Is the policy permissive or restrictive?
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">roles</code> <code class="type">name[]</code>
+ </p>
+ <p>
+ The roles to which this policy applies
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cmd</code> <code class="type">text</code>
+ </p>
+ <p>
+ The command type to which the policy is applied
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">qual</code> <code class="type">text</code>
+ </p>
+ <p>
+ The expression added to the security barrier qualifications for
+ queries that this policy applies to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">with_check</code> <code class="type">text</code>
+ </p>
+ <p>
+ The expression added to the WITH CHECK qualifications for
+ queries that attempt to add rows to this table
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-matviews.html" title="54.13. pg_matviews">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.13. <code class="structname">pg_matviews</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.15. <code class="structname">pg_prepared_statements</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-prepared-statements.html b/doc/src/sgml/html/view-pg-prepared-statements.html
new file mode 100644
index 0000000..c75aa8f
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-prepared-statements.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.15. pg_prepared_statements</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-policies.html" title="54.14. pg_policies" /><link rel="next" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.15. <code class="structname">pg_prepared_statements</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-policies.html" title="54.14. pg_policies">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-PREPARED-STATEMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.15. <code class="structname">pg_prepared_statements</code></h2></div></div></div><a id="id-1.10.5.19.2" class="indexterm"></a><p>
+ The <code class="structname">pg_prepared_statements</code> view displays
+ all the prepared statements that are available in the current
+ session. See <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for more information about prepared
+ statements.
+ </p><p>
+ <code class="structname">pg_prepared_statements</code> 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 <a class="link" href="sql-deallocate.html" title="DEALLOCATE"><code class="command">DEALLOCATE</code></a> command).
+ </p><div class="table" id="id-1.10.5.19.5"><p class="title"><strong>Table 54.15. <code class="structname">pg_prepared_statements</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_prepared_statements Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ The identifier of the prepared statement
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statement</code> <code class="type">text</code>
+ </p>
+ <p>
+ The query string submitted by the client to create this
+ prepared statement. For prepared statements created via SQL,
+ this is the <code class="command">PREPARE</code> statement submitted by
+ the client. For prepared statements created via the
+ frontend/backend protocol, this is the text of the prepared
+ statement itself.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prepare_time</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ The time at which the prepared statement was created
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">parameter_types</code> <code class="type">regtype[]</code>
+ </p>
+ <p>
+ The expected parameter types for the prepared statement in the
+ form of an array of <code class="type">regtype</code>. The OID corresponding
+ to an element of this array can be obtained by casting the
+ <code class="type">regtype</code> value to <code class="type">oid</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">from_sql</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> if the prepared statement was created
+ via the <code class="command">PREPARE</code> SQL command;
+ <code class="literal">false</code> if the statement was prepared via the
+ frontend/backend protocol
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">generic_plans</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Number of times generic plan was chosen
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">custom_plans</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Number of times custom plan was chosen
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_prepared_statements</code> view is read-only.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-policies.html" title="54.14. pg_policies">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.14. <code class="structname">pg_policies</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.16. <code class="structname">pg_prepared_xacts</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-prepared-xacts.html b/doc/src/sgml/html/view-pg-prepared-xacts.html
new file mode 100644
index 0000000..4d91b46
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-prepared-xacts.html
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.16. pg_prepared_xacts</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements" /><link rel="next" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.16. <code class="structname">pg_prepared_xacts</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-PREPARED-XACTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.16. <code class="structname">pg_prepared_xacts</code></h2></div></div></div><a id="id-1.10.5.20.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_prepared_xacts</code> displays
+ information about transactions that are currently prepared for two-phase
+ commit (see <a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a> for details).
+ </p><p>
+ <code class="structname">pg_prepared_xacts</code> contains one row per prepared
+ transaction. An entry is removed when the transaction is committed or
+ rolled back.
+ </p><div class="table" id="id-1.10.5.20.5"><p class="title"><strong>Table 54.16. <code class="structname">pg_prepared_xacts</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_prepared_xacts Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">transaction</code> <code class="type">xid</code>
+ </p>
+ <p>
+ Numeric transaction identifier of the prepared transaction
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">gid</code> <code class="type">text</code>
+ </p>
+ <p>
+ Global transaction identifier that was assigned to the transaction
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">prepared</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Time at which the transaction was prepared for commit
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">owner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of the user that executed the transaction
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">database</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">datname</code>)
+ </p>
+ <p>
+ Name of the database in which the transaction was executed
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ When the <code class="structname">pg_prepared_xacts</code> view is accessed, the
+ internal transaction manager data structures are momentarily locked, and
+ a copy is made for the view to display. This ensures that the
+ view produces a consistent set of results, while not blocking
+ normal operations longer than necessary. Nonetheless
+ there could be some impact on database performance if this view is
+ frequently accessed.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.15. <code class="structname">pg_prepared_statements</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.17. <code class="structname">pg_publication_tables</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-publication-tables.html b/doc/src/sgml/html/view-pg-publication-tables.html
new file mode 100644
index 0000000..6b9705a
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-publication-tables.html
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.17. pg_publication_tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts" /><link rel="next" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.17. <code class="structname">pg_publication_tables</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-PUBLICATION-TABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.17. <code class="structname">pg_publication_tables</code></h2></div></div></div><a id="id-1.10.5.21.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_publication_tables</code> provides
+ information about the mapping between publications and information of
+ tables they contain. Unlike the underlying catalog
+ <a class="link" href="catalog-pg-publication-rel.html" title="53.42. pg_publication_rel"><code class="structname">pg_publication_rel</code></a>,
+ this view expands publications defined as <code class="literal">FOR ALL TABLES</code>
+ and <code class="literal">FOR TABLES IN SCHEMA</code>, so for such publications
+ there will be a row for each eligible table.
+ </p><div class="table" id="id-1.10.5.21.4"><p class="title"><strong>Table 54.17. <code class="structname">pg_publication_tables</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_publication_tables Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pubname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-publication.html" title="53.40. pg_publication"><code class="structname">pg_publication</code></a>.<code class="structfield">pubname</code>)
+ </p>
+ <p>
+ Name of publication
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attnames</code> <code class="type">name[]</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attname</code>)
+ </p>
+ <p>
+ Names of table columns included in the publication. This contains all
+ the columns of the table when the user didn't specify the column list
+ for the table.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rowfilter</code> <code class="type">text</code>
+ </p>
+ <p>
+ Expression for the table's publication qualifying condition
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.16. <code class="structname">pg_prepared_xacts</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.18. <code class="structname">pg_replication_origin_status</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-replication-origin-status.html b/doc/src/sgml/html/view-pg-replication-origin-status.html
new file mode 100644
index 0000000..8787673
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-replication-origin-status.html
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.18. pg_replication_origin_status</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables" /><link rel="next" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.18. <code class="structname">pg_replication_origin_status</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-REPLICATION-ORIGIN-STATUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.18. <code class="structname">pg_replication_origin_status</code></h2></div></div></div><a id="id-1.10.5.22.2" class="indexterm"></a><p>
+ The <code class="structname">pg_replication_origin_status</code> view
+ contains information about how far replay for a certain origin has
+ progressed. For more on replication origins
+ see <a class="xref" href="replication-origins.html" title="Chapter 50. Replication Progress Tracking">Chapter 50</a>.
+ </p><div class="table" id="id-1.10.5.22.4"><p class="title"><strong>Table 54.18. <code class="structname">pg_replication_origin_status</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_replication_origin_status Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_id</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin"><code class="structname">pg_replication_origin</code></a>.<code class="structfield">roident</code>)
+ </p>
+ <p>
+ internal node identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">external_id</code> <code class="type">text</code>
+ (references <a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin"><code class="structname">pg_replication_origin</code></a>.<code class="structfield">roname</code>)
+ </p>
+ <p>
+ external node identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">remote_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ The origin node's LSN up to which data has been replicated.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">local_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ This node's LSN at which <code class="literal">remote_lsn</code> has
+ been replicated. Used to flush commit records before persisting
+ data to disk when using asynchronous commits.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.17. <code class="structname">pg_publication_tables</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.19. <code class="structname">pg_replication_slots</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-replication-slots.html b/doc/src/sgml/html/view-pg-replication-slots.html
new file mode 100644
index 0000000..bdb96f1
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-replication-slots.html
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.19. pg_replication_slots</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status" /><link rel="next" href="view-pg-roles.html" title="54.20. pg_roles" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.19. <code class="structname">pg_replication_slots</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-roles.html" title="54.20. pg_roles">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-REPLICATION-SLOTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.19. <code class="structname">pg_replication_slots</code></h2></div></div></div><a id="id-1.10.5.23.2" class="indexterm"></a><p>
+ The <code class="structname">pg_replication_slots</code> view provides a listing
+ of all replication slots that currently exist on the database cluster,
+ along with their current state.
+ </p><p>
+ For more on replication slots,
+ see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a> and <a class="xref" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Chapter 49</a>.
+ </p><div class="table" id="id-1.10.5.23.5"><p class="title"><strong>Table 54.19. <code class="structname">pg_replication_slots</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_replication_slots Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">slot_name</code> <code class="type">name</code>
+ </p>
+ <p>
+ A unique, cluster-wide identifier for the replication slot
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">plugin</code> <code class="type">name</code>
+ </p>
+ <p>
+ The base name of the shared object containing the output plugin this logical slot is using, or null for physical slots.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">slot_type</code> <code class="type">text</code>
+ </p>
+ <p>
+ The slot type: <code class="literal">physical</code> or <code class="literal">logical</code>
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">datoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the database this slot is associated with, or
+ null. Only logical slots have an associated database.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">database</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-database.html" title="53.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">datname</code>)
+ </p>
+ <p>
+ The name of the database this slot is associated with, or
+ null. Only logical slots have an associated database.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">temporary</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this is a temporary replication slot. Temporary slots are
+ not saved to disk and are automatically dropped on error or when
+ the session has finished.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">active</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this slot is currently actively being used
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">active_pid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ The process ID of the session using this slot if the slot
+ is currently actively being used. <code class="literal">NULL</code> if
+ inactive.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">xmin</code> <code class="type">xid</code>
+ </p>
+ <p>
+ The oldest transaction that this slot needs the database to
+ retain. <code class="literal">VACUUM</code> cannot remove tuples deleted
+ by any later transaction.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">catalog_xmin</code> <code class="type">xid</code>
+ </p>
+ <p>
+ The oldest transaction affecting the system catalogs that this
+ slot needs the database to retain. <code class="literal">VACUUM</code> cannot
+ remove catalog tuples deleted by any later transaction.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">restart_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ The address (<code class="literal">LSN</code>) of oldest WAL which still
+ might be required by the consumer of this slot and thus won't be
+ automatically removed during checkpoints unless this LSN
+ gets behind more than <a class="xref" href="runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE">max_slot_wal_keep_size</a>
+ from the current LSN. <code class="literal">NULL</code>
+ if the <code class="literal">LSN</code> of this slot has never been reserved.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">confirmed_flush_lsn</code> <code class="type">pg_lsn</code>
+ </p>
+ <p>
+ The address (<code class="literal">LSN</code>) up to which the logical
+ slot's consumer has confirmed receiving data. Data older than this is
+ not available anymore. <code class="literal">NULL</code> for physical slots.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">wal_status</code> <code class="type">text</code>
+ </p>
+ <p>
+ Availability of WAL files claimed by this slot.
+ Possible values are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">reserved</code> means that the claimed files
+ are within <code class="varname">max_wal_size</code>.</p></li><li class="listitem"><p><code class="literal">extended</code> means
+ that <code class="varname">max_wal_size</code> is exceeded but the files are
+ still retained, either by the replication slot or
+ by <code class="varname">wal_keep_size</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">unreserved</code> means that the slot no longer
+ retains the required WAL files and some of them are to be removed at
+ the next checkpoint. This state can return
+ to <code class="literal">reserved</code> or <code class="literal">extended</code>.
+ </p></li><li class="listitem"><p>
+ <code class="literal">lost</code> means that some required WAL files have
+ been removed and this slot is no longer usable.
+ </p></li></ul></div><p>
+ The last two states are seen only when
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE">max_slot_wal_keep_size</a> is
+ non-negative. If <code class="structfield">restart_lsn</code> is NULL, this
+ field is null.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">safe_wal_size</code> <code class="type">int8</code>
+ </p>
+ <p>
+ The number of bytes that can be written to WAL such that this slot
+ is not in danger of getting in state "lost". It is NULL for lost
+ slots, as well as if <code class="varname">max_slot_wal_keep_size</code>
+ is <code class="literal">-1</code>.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">two_phase</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if the slot is enabled for decoding prepared transactions. Always
+ false for physical slots.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-roles.html" title="54.20. pg_roles">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.18. <code class="structname">pg_replication_origin_status</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.20. <code class="structname">pg_roles</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-roles.html b/doc/src/sgml/html/view-pg-roles.html
new file mode 100644
index 0000000..4fede12
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-roles.html
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.20. pg_roles</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots" /><link rel="next" href="view-pg-rules.html" title="54.21. pg_rules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.20. <code class="structname">pg_roles</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-rules.html" title="54.21. pg_rules">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-ROLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.20. <code class="structname">pg_roles</code></h2></div></div></div><a id="id-1.10.5.24.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_roles</code> provides access to
+ information about database roles. This is simply a publicly
+ readable view of
+ <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>
+ that blanks out the password field.
+ </p><div class="table" id="id-1.10.5.24.4"><p class="title"><strong>Table 54.20. <code class="structname">pg_roles</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_roles Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolname</code> <code class="type">name</code>
+ </p>
+ <p>
+ Role name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolsuper</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role has superuser privileges
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolinherit</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role automatically inherits privileges of roles it is a
+ member of
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcreaterole</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can create more roles
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcreatedb</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can create databases
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolcanlogin</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role can log in. That is, this role can be given as the initial
+ session authorization identifier
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolreplication</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role is a replication role. A replication role can initiate replication
+ connections and create and drop replication slots.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolconnlimit</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For roles that can log in, this sets maximum number of concurrent
+ connections this role can make. -1 means no limit.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolpassword</code> <code class="type">text</code>
+ </p>
+ <p>
+ Not the password (always reads as <code class="literal">********</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolvaliduntil</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Password expiry time (only used for password authentication);
+ null if no expiration
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolbypassrls</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Role bypasses every row-level security policy, see
+ <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rolconfig</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Role-specific defaults for run-time configuration variables
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">oid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of role
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-rules.html" title="54.21. pg_rules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.19. <code class="structname">pg_replication_slots</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.21. <code class="structname">pg_rules</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-rules.html b/doc/src/sgml/html/view-pg-rules.html
new file mode 100644
index 0000000..8aed34b
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-rules.html
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.21. pg_rules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-roles.html" title="54.20. pg_roles" /><link rel="next" href="view-pg-seclabels.html" title="54.22. pg_seclabels" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.21. <code class="structname">pg_rules</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-roles.html" title="54.20. pg_roles">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-RULES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.21. <code class="structname">pg_rules</code></h2></div></div></div><a id="id-1.10.5.25.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_rules</code> provides access to
+ useful information about query rewrite rules.
+ </p><div class="table" id="id-1.10.5.25.4"><p class="title"><strong>Table 54.21. <code class="structname">pg_rules</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_rules Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table the rule is for
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rulename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-rewrite.html" title="53.45. pg_rewrite"><code class="structname">pg_rewrite</code></a>.<code class="structfield">rulename</code>)
+ </p>
+ <p>
+ Name of rule
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">definition</code> <code class="type">text</code>
+ </p>
+ <p>
+ Rule definition (a reconstructed creation command)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The <code class="structname">pg_rules</code> view excludes the <code class="literal">ON SELECT</code> rules
+ of views and materialized views; those can be seen in
+ <a class="link" href="view-pg-views.html" title="54.35. pg_views"><code class="structname">pg_views</code></a> and <a class="link" href="view-pg-matviews.html" title="54.13. pg_matviews"><code class="structname">pg_matviews</code></a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-roles.html" title="54.20. pg_roles">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.20. <code class="structname">pg_roles</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.22. <code class="structname">pg_seclabels</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-seclabels.html b/doc/src/sgml/html/view-pg-seclabels.html
new file mode 100644
index 0000000..e1e41ff
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-seclabels.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.22. pg_seclabels</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-rules.html" title="54.21. pg_rules" /><link rel="next" href="view-pg-sequences.html" title="54.23. pg_sequences" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.22. <code class="structname">pg_seclabels</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-rules.html" title="54.21. pg_rules">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-sequences.html" title="54.23. pg_sequences">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-SECLABELS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.22. <code class="structname">pg_seclabels</code></h2></div></div></div><a id="id-1.10.5.26.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_seclabels</code> provides information about
+ security labels. It as an easier-to-query version of the
+ <a class="link" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel"><code class="structname">pg_seclabel</code></a> catalog.
+ </p><div class="table" id="id-1.10.5.26.4"><p class="title"><strong>Table 54.22. <code class="structname">pg_seclabels</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_seclabels Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objoid</code> <code class="type">oid</code>
+ (references any OID column)
+ </p>
+ <p>
+ The OID of the object this security label pertains to
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">classoid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the system catalog this object appears in
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objsubid</code> <code class="type">int4</code>
+ </p>
+ <p>
+ For a security label on a table column, this is the column number (the
+ <code class="structfield">objoid</code> and <code class="structfield">classoid</code> refer to
+ the table itself). For all other object types, this column is
+ zero.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objtype</code> <code class="type">text</code>
+ </p>
+ <p>
+ The type of object to which this label applies, as text.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objnamespace</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the namespace for this object, if applicable;
+ otherwise NULL.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">objname</code> <code class="type">text</code>
+ </p>
+ <p>
+ The name of the object to which this label applies, as text.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">provider</code> <code class="type">text</code>
+ (references <a class="link" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel"><code class="structname">pg_seclabel</code></a>.<code class="structfield">provider</code>)
+ </p>
+ <p>
+ The label provider associated with this label.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">label</code> <code class="type">text</code>
+ (references <a class="link" href="catalog-pg-seclabel.html" title="53.46. pg_seclabel"><code class="structname">pg_seclabel</code></a>.<code class="structfield">label</code>)
+ </p>
+ <p>
+ The security label applied to this object.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-rules.html" title="54.21. pg_rules">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-sequences.html" title="54.23. pg_sequences">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.21. <code class="structname">pg_rules</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.23. <code class="structname">pg_sequences</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-sequences.html b/doc/src/sgml/html/view-pg-sequences.html
new file mode 100644
index 0000000..4e4a5e7
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-sequences.html
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.23. pg_sequences</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-seclabels.html" title="54.22. pg_seclabels" /><link rel="next" href="view-pg-settings.html" title="54.24. pg_settings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.23. <code class="structname">pg_sequences</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-settings.html" title="54.24. pg_settings">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-SEQUENCES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.23. <code class="structname">pg_sequences</code></h2></div></div></div><a id="id-1.10.5.27.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_sequences</code> provides access to
+ useful information about each sequence in the database.
+ </p><div class="table" id="id-1.10.5.27.4"><p class="title"><strong>Table 54.23. <code class="structname">pg_sequences</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_sequences Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequencename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sequenceowner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of sequence's owner
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">data_type</code> <code class="type">regtype</code>
+ (references <a class="link" href="catalog-pg-type.html" title="53.64. pg_type"><code class="structname">pg_type</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ Data type of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">start_value</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Start value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">min_value</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Minimum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_value</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Maximum value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">increment_by</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Increment value of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cycle</code> <code class="type">bool</code>
+ </p>
+ <p>
+ Whether the sequence cycles
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">cache_size</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Cache size of the sequence
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">last_value</code> <code class="type">int8</code>
+ </p>
+ <p>
+ The last sequence value written to disk. If caching is used,
+ this value can be greater than the last value handed out from the
+ sequence. Null if the sequence has not been read from yet. Also, if
+ the current user does not have <code class="literal">USAGE</code>
+ or <code class="literal">SELECT</code> privilege on the sequence, the value is
+ null.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-seclabels.html" title="54.22. pg_seclabels">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-settings.html" title="54.24. pg_settings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.22. <code class="structname">pg_seclabels</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.24. <code class="structname">pg_settings</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-settings.html b/doc/src/sgml/html/view-pg-settings.html
new file mode 100644
index 0000000..0d00543
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-settings.html
@@ -0,0 +1,201 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.24. pg_settings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-sequences.html" title="54.23. pg_sequences" /><link rel="next" href="view-pg-shadow.html" title="54.25. pg_shadow" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.24. <code class="structname">pg_settings</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-sequences.html" title="54.23. pg_sequences">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-shadow.html" title="54.25. pg_shadow">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-SETTINGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.24. <code class="structname">pg_settings</code></h2></div></div></div><a id="id-1.10.5.28.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_settings</code> provides access to
+ run-time parameters of the server. It is essentially an alternative
+ interface to the <a class="link" href="sql-show.html" title="SHOW"><code class="command">SHOW</code></a>
+ and <a class="link" href="sql-set.html" title="SET"><code class="command">SET</code></a> commands.
+ It also provides access to some facts about each parameter that are
+ not directly available from <a class="link" href="sql-show.html" title="SHOW"><code class="command">SHOW</code></a>, such as minimum and
+ maximum values.
+ </p><div class="table" id="id-1.10.5.28.4"><p class="title"><strong>Table 54.24. <code class="structname">pg_settings</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_settings Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Run-time configuration parameter name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">setting</code> <code class="type">text</code>
+ </p>
+ <p>
+ Current value of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">unit</code> <code class="type">text</code>
+ </p>
+ <p>
+ Implicit unit of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">category</code> <code class="type">text</code>
+ </p>
+ <p>
+ Logical group of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">short_desc</code> <code class="type">text</code>
+ </p>
+ <p>
+ A brief description of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">extra_desc</code> <code class="type">text</code>
+ </p>
+ <p>
+ Additional, more detailed, description of the parameter
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">context</code> <code class="type">text</code>
+ </p>
+ <p>
+ Context required to set the parameter's value (see below)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">vartype</code> <code class="type">text</code>
+ </p>
+ <p>
+ Parameter type (<code class="literal">bool</code>, <code class="literal">enum</code>,
+ <code class="literal">integer</code>, <code class="literal">real</code>, or <code class="literal">string</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">source</code> <code class="type">text</code>
+ </p>
+ <p>
+ Source of the current parameter value
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">min_val</code> <code class="type">text</code>
+ </p>
+ <p>
+ Minimum allowed value of the parameter (null for non-numeric
+ values)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">max_val</code> <code class="type">text</code>
+ </p>
+ <p>
+ Maximum allowed value of the parameter (null for non-numeric
+ values)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">enumvals</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Allowed values of an enum parameter (null for non-enum
+ values)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">boot_val</code> <code class="type">text</code>
+ </p>
+ <p>
+ Parameter value assumed at server startup if the parameter is
+ not otherwise set
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">reset_val</code> <code class="type">text</code>
+ </p>
+ <p>
+ Value that <a class="link" href="sql-reset.html" title="RESET"><code class="command">RESET</code></a> would reset the parameter to
+ in the current session
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sourcefile</code> <code class="type">text</code>
+ </p>
+ <p>
+ Configuration file the current value was set in (null for
+ values set from sources other than configuration files, or when
+ examined by a user who neither is a superuser nor has privileges of
+ <code class="literal">pg_read_all_settings</code>); helpful when using
+ <code class="literal">include</code> directives in configuration files
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">sourceline</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Line number within the configuration file the current value was
+ set at (null for values set from sources other than configuration files,
+ or when examined by a user who neither is a superuser nor has privileges of
+ <code class="literal">pg_read_all_settings</code>).
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">pending_restart</code> <code class="type">bool</code>
+ </p>
+ <p>
+ <code class="literal">true</code> if the value has been changed in the
+ configuration file but needs a restart; or <code class="literal">false</code>
+ otherwise.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ There are several possible values of <code class="structfield">context</code>.
+ In order of decreasing difficulty of changing the setting, they are:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">internal</code></span></dt><dd><p>
+ These settings cannot be changed directly; they reflect internally
+ determined values. Some of them may be adjustable by rebuilding the
+ server with different configuration options, or by changing options
+ supplied to <span class="application">initdb</span>.
+ </p></dd><dt><span class="term"><code class="literal">postmaster</code></span></dt><dd><p>
+ These settings can only be applied when the server starts, so any change
+ requires restarting the server. Values for these settings are typically
+ stored in the <code class="filename">postgresql.conf</code> file, or passed on
+ the command line when starting the server. Of course, settings with any
+ of the lower <code class="structfield">context</code> types can also be
+ set at server start time.
+ </p></dd><dt><span class="term"><code class="literal">sighup</code></span></dt><dd><p>
+ Changes to these settings can be made in
+ <code class="filename">postgresql.conf</code> without restarting the server.
+ Send a <span class="systemitem">SIGHUP</span> signal to the postmaster to
+ cause it to re-read <code class="filename">postgresql.conf</code> and apply
+ the changes. The postmaster will also forward the
+ <span class="systemitem">SIGHUP</span> signal to its child processes so that
+ they all pick up the new value.
+ </p></dd><dt><span class="term"><code class="literal">superuser-backend</code></span></dt><dd><p>
+ Changes to these settings can be made in
+ <code class="filename">postgresql.conf</code> without restarting the server.
+ They can also be set for a particular session in the connection request
+ packet (for example, via <span class="application">libpq</span>'s <code class="literal">PGOPTIONS</code>
+ environment variable), but only if the connecting user is a superuser
+ or has been granted the appropriate <code class="literal">SET</code> privilege.
+ However, these settings never change in a session after it is started.
+ If you change them in <code class="filename">postgresql.conf</code>, send a
+ <span class="systemitem">SIGHUP</span> signal to the postmaster to cause it to
+ re-read <code class="filename">postgresql.conf</code>. The new values will only
+ affect subsequently-launched sessions.
+ </p></dd><dt><span class="term"><code class="literal">backend</code></span></dt><dd><p>
+ Changes to these settings can be made in
+ <code class="filename">postgresql.conf</code> without restarting the server.
+ They can also be set for a particular session in the connection request
+ packet (for example, via <span class="application">libpq</span>'s <code class="literal">PGOPTIONS</code>
+ environment variable); any user can make such a change for their session.
+ However, these settings never change in a session after it is started.
+ If you change them in <code class="filename">postgresql.conf</code>, send a
+ <span class="systemitem">SIGHUP</span> signal to the postmaster to cause it to
+ re-read <code class="filename">postgresql.conf</code>. The new values will only
+ affect subsequently-launched sessions.
+ </p></dd><dt><span class="term"><code class="literal">superuser</code></span></dt><dd><p>
+ These settings can be set from <code class="filename">postgresql.conf</code>,
+ or within a session via the <code class="command">SET</code> command; but only superusers
+ and users with the appropriate <code class="literal">SET</code> privilege
+ can change them via <code class="command">SET</code>. Changes in
+ <code class="filename">postgresql.conf</code> will affect existing sessions
+ only if no session-local value has been established with <code class="command">SET</code>.
+ </p></dd><dt><span class="term"><code class="literal">user</code></span></dt><dd><p>
+ These settings can be set from <code class="filename">postgresql.conf</code>,
+ or within a session via the <code class="command">SET</code> command. Any user is
+ allowed to change their session-local value. Changes in
+ <code class="filename">postgresql.conf</code> will affect existing sessions
+ only if no session-local value has been established with <code class="command">SET</code>.
+ </p></dd></dl></div><p>
+ See <a class="xref" href="config-setting.html" title="20.1. Setting Parameters">Section 20.1</a> for more information about the various
+ ways to change these parameters.
+ </p><p>
+ This view cannot be inserted into or deleted from, but it can be updated. An
+ <code class="command">UPDATE</code> applied to a row of <code class="structname">pg_settings</code>
+ is equivalent to executing the <code class="command">SET</code> command on that named
+ parameter. The change only affects the value used by the current
+ session. If an <code class="command">UPDATE</code> is issued within a transaction
+ that is later aborted, the effects of the <code class="command">UPDATE</code> command
+ disappear when the transaction is rolled back. Once the surrounding
+ transaction is committed, the effects will persist until the end of the
+ session, unless overridden by another <code class="command">UPDATE</code> or
+ <code class="command">SET</code>.
+ </p><p>
+ This view does not
+ display <a class="link" href="runtime-config-custom.html" title="20.16. Customized Options">customized options</a>
+ unless the extension module that defines them has been loaded by the
+ backend process executing the query (e.g., via a mention in
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>,
+ a call to a C function in the extension, or the
+ <a class="link" href="sql-load.html" title="LOAD"><code class="command">LOAD</code></a> command).
+ For example, since <a class="link" href="archive-modules.html" title="Chapter 51. Archive Modules">archive modules</a>
+ are normally loaded only by the archiver process not regular sessions,
+ this view will not display any customized options defined by such modules
+ unless special action is taken to load them into the backend process
+ executing the query.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-sequences.html" title="54.23. pg_sequences">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-shadow.html" title="54.25. pg_shadow">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.23. <code class="structname">pg_sequences</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.25. <code class="structname">pg_shadow</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-shadow.html b/doc/src/sgml/html/view-pg-shadow.html
new file mode 100644
index 0000000..a3308f7
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-shadow.html
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.25. pg_shadow</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-settings.html" title="54.24. pg_settings" /><link rel="next" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.25. <code class="structname">pg_shadow</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-settings.html" title="54.24. pg_settings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-SHADOW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.25. <code class="structname">pg_shadow</code></h2></div></div></div><a id="id-1.10.5.29.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_shadow</code> exists for backwards
+ compatibility: it emulates a catalog that existed in
+ <span class="productname">PostgreSQL</span> before version 8.1.
+ It shows properties of all roles that are marked as
+ <code class="structfield">rolcanlogin</code> in
+ <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.
+ </p><p>
+ The name stems from the fact that this table
+ should not be readable by the public since it contains passwords.
+ <a class="link" href="view-pg-user.html" title="54.33. pg_user"><code class="structname">pg_user</code></a>
+ is a publicly readable view on
+ <code class="structname">pg_shadow</code> that blanks out the password field.
+ </p><div class="table" id="id-1.10.5.29.5"><p class="title"><strong>Table 54.25. <code class="structname">pg_shadow</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_shadow Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ User name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesysid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ ID of this user
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usecreatedb</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User can create databases
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesuper</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User is a superuser
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">userepl</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User can initiate streaming replication and put the system in and
+ out of backup mode.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usebypassrls</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User bypasses every row-level security policy, see
+ <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">passwd</code> <code class="type">text</code>
+ </p>
+ <p>
+ Password (possibly encrypted); null if none. See
+ <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>
+ for details of how encrypted passwords are stored.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">valuntil</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Password expiry time (only used for password authentication)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">useconfig</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Session defaults for run-time configuration variables
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-settings.html" title="54.24. pg_settings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.24. <code class="structname">pg_settings</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.26. <code class="structname">pg_shmem_allocations</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-shmem-allocations.html b/doc/src/sgml/html/view-pg-shmem-allocations.html
new file mode 100644
index 0000000..90d270c
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-shmem-allocations.html
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.26. pg_shmem_allocations</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-shadow.html" title="54.25. pg_shadow" /><link rel="next" href="view-pg-stats.html" title="54.27. pg_stats" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.26. <code class="structname">pg_shmem_allocations</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-shadow.html" title="54.25. pg_shadow">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-stats.html" title="54.27. pg_stats">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-SHMEM-ALLOCATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.26. <code class="structname">pg_shmem_allocations</code></h2></div></div></div><a id="id-1.10.5.30.2" class="indexterm"></a><p>
+ The <code class="structname">pg_shmem_allocations</code> view shows allocations
+ made from the server's main shared memory segment. This includes both
+ memory allocated by <span class="productname">PostgreSQL</span> itself and memory
+ allocated by extensions using the mechanisms detailed in
+ <a class="xref" href="xfunc-c.html#XFUNC-SHARED-ADDIN" title="38.10.10. Shared Memory and LWLocks">Section 38.10.10</a>.
+ </p><p>
+ Note that this view does not include memory allocated using the dynamic
+ shared memory infrastructure.
+ </p><div class="table" id="id-1.10.5.30.5"><p class="title"><strong>Table 54.26. <code class="structname">pg_shmem_allocations</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_shmem_allocations Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ The name of the shared memory allocation. NULL for unused memory
+ and <code class="literal">&lt;anonymous&gt;</code> for anonymous
+ allocations.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">off</code> <code class="type">int8</code>
+ </p>
+ <p>
+ The offset at which the allocation starts. NULL for anonymous
+ allocations, since details related to them are not known.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">size</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Size of the allocation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">allocated_size</code> <code class="type">int8</code>
+ </p>
+ <p>
+ Size of the allocation including padding. For anonymous
+ allocations, no information about padding is available, so the
+ <code class="literal">size</code> and <code class="literal">allocated_size</code> columns
+ will always be equal. Padding is not meaningful for free memory, so
+ the columns will be equal in that case also.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Anonymous allocations are allocations that have been made
+ with <code class="literal">ShmemAlloc()</code> directly, rather than via
+ <code class="literal">ShmemInitStruct()</code> or
+ <code class="literal">ShmemInitHash()</code>.
+ </p><p>
+ By default, the <code class="structname">pg_shmem_allocations</code> view can be
+ read only by superusers or roles with privileges of the
+ <code class="literal">pg_read_all_stats</code> role.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-shadow.html" title="54.25. pg_shadow">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-stats.html" title="54.27. pg_stats">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.25. <code class="structname">pg_shadow</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.27. <code class="structname">pg_stats</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-stats-ext-exprs.html b/doc/src/sgml/html/view-pg-stats-ext-exprs.html
new file mode 100644
index 0000000..9b281a7
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-stats-ext-exprs.html
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.29. pg_stats_ext_exprs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext" /><link rel="next" href="view-pg-tables.html" title="54.30. pg_tables" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.29. <code class="structname">pg_stats_ext_exprs</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-tables.html" title="54.30. pg_tables">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-STATS-EXT-EXPRS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.29. <code class="structname">pg_stats_ext_exprs</code></h2></div></div></div><a id="id-1.10.5.33.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_stats_ext_exprs</code> provides access to
+ information about all expressions included in extended statistics objects,
+ combining information stored in the <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>
+ and <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ catalogs. This view allows access only to rows of
+ <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a> and <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ that correspond to tables the user has permission to read, and therefore
+ it is safe to allow public read access to this view.
+ </p><p>
+ <code class="structname">pg_stats_ext_exprs</code> is also designed to present
+ the information in a more readable format than the underlying catalogs
+ — at the cost that its schema must be extended whenever the structure
+ of statistics in <code class="structname">pg_statistic_ext</code> changes.
+ </p><div class="table" id="id-1.10.5.33.5"><p class="title"><strong>Table 54.29. <code class="structname">pg_stats_ext_exprs</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stats_ext_exprs Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table the statistics object is defined on
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_name</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>.<code class="structfield">stxname</code>)
+ </p>
+ <p>
+ Name of extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_owner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Owner of the extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">expr</code> <code class="type">text</code>
+ </p>
+ <p>
+ Expression included in the extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inherited</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>.<code class="structfield">stxdinherit</code>)
+ </p>
+ <p>
+ If true, the stats include values from child tables, not just the
+ values in the specified relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">null_frac</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Fraction of expression entries that are null
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">avg_width</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Average width in bytes of expression's entries
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_distinct</code> <code class="type">float4</code>
+ </p>
+ <p>
+ If greater than zero, the estimated number of distinct values in the
+ expression. If less than zero, the negative of the number of distinct
+ values divided by the number of rows. (The negated form is used when
+ <code class="command">ANALYZE</code> believes that the number of distinct values is
+ likely to increase as the table grows; the positive form is used when
+ the expression seems to have a fixed number of possible values.) For
+ example, -1 indicates a unique expression in which the number of distinct
+ values is the same as the number of rows.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_vals</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of the most common values in the expression. (Null if
+ no values seem to be more common than any others.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_freqs</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A list of the frequencies of the most common values,
+ i.e., number of occurrences of each divided by total number of rows.
+ (Null when <code class="structfield">most_common_vals</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">histogram_bounds</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of values that divide the expression's values into groups of
+ approximately equal population. The values in
+ <code class="structfield">most_common_vals</code>, if present, are omitted from this
+ histogram calculation. (This expression is null if the expression data type
+ does not have a <code class="literal">&lt;</code> operator or if the
+ <code class="structfield">most_common_vals</code> list accounts for the entire
+ population.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">correlation</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Statistical correlation between physical row ordering and
+ logical ordering of the expression values. This ranges from -1 to +1.
+ When the value is near -1 or +1, an index scan on the expression will
+ be estimated to be cheaper than when it is near zero, due to reduction
+ of random access to the disk. (This expression is null if the expression's
+ data type does not have a <code class="literal">&lt;</code> operator.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_elems</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of non-null element values most often appearing within values of
+ the expression. (Null for scalar types.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_elem_freqs</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A list of the frequencies of the most common element values, i.e., the
+ fraction of rows containing at least one instance of the given value.
+ Two or three additional values follow the per-element frequencies;
+ these are the minimum and maximum of the preceding per-element
+ frequencies, and optionally the frequency of null elements.
+ (Null when <code class="structfield">most_common_elems</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">elem_count_histogram</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A histogram of the counts of distinct non-null element values within the
+ values of the expression, followed by the average number of distinct
+ non-null elements. (Null for scalar types.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The maximum number of entries in the array fields can be controlled on a
+ column-by-column basis using the <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER
+ TABLE SET STATISTICS</code></a> command, or globally by setting the
+ <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> run-time parameter.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-tables.html" title="54.30. pg_tables">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.28. <code class="structname">pg_stats_ext</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.30. <code class="structname">pg_tables</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-stats-ext.html b/doc/src/sgml/html/view-pg-stats-ext.html
new file mode 100644
index 0000000..da67620
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-stats-ext.html
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.28. pg_stats_ext</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-stats.html" title="54.27. pg_stats" /><link rel="next" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.28. <code class="structname">pg_stats_ext</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-stats.html" title="54.27. pg_stats">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-STATS-EXT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.28. <code class="structname">pg_stats_ext</code></h2></div></div></div><a id="id-1.10.5.32.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_stats_ext</code> provides access to
+ information about each extended statistics object in the database,
+ combining information stored in the <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>
+ and <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ catalogs. This view allows access only to rows of
+ <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a> and <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>
+ that correspond to tables the user has permission to read, and therefore
+ it is safe to allow public read access to this view.
+ </p><p>
+ <code class="structname">pg_stats_ext</code> is also designed to present the
+ information in a more readable format than the underlying catalogs
+ — at the cost that its schema must be extended whenever new types
+ of extended statistics are added to <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>.
+ </p><div class="table" id="id-1.10.5.32.5"><p class="title"><strong>Table 54.28. <code class="structname">pg_stats_ext</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stats_ext Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_name</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-statistic-ext.html" title="53.52. pg_statistic_ext"><code class="structname">pg_statistic_ext</code></a>.<code class="structfield">stxname</code>)
+ </p>
+ <p>
+ Name of extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">statistics_owner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Owner of the extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attnames</code> <code class="type">name[]</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attname</code>)
+ </p>
+ <p>
+ Names of the columns included in the extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">exprs</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Expressions included in the extended statistics object
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">kinds</code> <code class="type">char[]</code>
+ </p>
+ <p>
+ Types of extended statistics object enabled for this record
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inherited</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-statistic-ext-data.html" title="53.53. pg_statistic_ext_data"><code class="structname">pg_statistic_ext_data</code></a>.<code class="structfield">stxdinherit</code>)
+ </p>
+ <p>
+ If true, the stats include values from child tables, not just the
+ values in the specified relation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_distinct</code> <code class="type">pg_ndistinct</code>
+ </p>
+ <p>
+ N-distinct counts for combinations of column values. If greater
+ than zero, the estimated number of distinct values in the combination.
+ If less than zero, the negative of the number of distinct values divided
+ by the number of rows.
+ (The negated form is used when <code class="command">ANALYZE</code> believes that
+ the number of distinct values is likely to increase as the table grows;
+ the positive form is used when the column seems to have a fixed number
+ of possible values.) For example, -1 indicates a unique combination of
+ columns in which the number of distinct combinations is the same as the
+ number of rows.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">dependencies</code> <code class="type">pg_dependencies</code>
+ </p>
+ <p>
+ Functional dependency statistics
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_vals</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ A list of the most common combinations of values in the columns.
+ (Null if no combinations seem to be more common than any others.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_val_nulls</code> <code class="type">bool[]</code>
+ </p>
+ <p>
+ A list of NULL flags for the most common combinations of values.
+ (Null when <code class="structfield">most_common_vals</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_freqs</code> <code class="type">float8[]</code>
+ </p>
+ <p>
+ A list of the frequencies of the most common combinations,
+ i.e., number of occurrences of each divided by total number of rows.
+ (Null when <code class="structfield">most_common_vals</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_base_freqs</code> <code class="type">float8[]</code>
+ </p>
+ <p>
+ A list of the base frequencies of the most common combinations,
+ i.e., product of per-value frequencies.
+ (Null when <code class="structfield">most_common_vals</code> is.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The maximum number of entries in the array fields can be controlled on a
+ column-by-column basis using the <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER
+ TABLE SET STATISTICS</code></a> command, or globally by setting the
+ <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> run-time parameter.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-stats.html" title="54.27. pg_stats">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.27. <code class="structname">pg_stats</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.29. <code class="structname">pg_stats_ext_exprs</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-stats.html b/doc/src/sgml/html/view-pg-stats.html
new file mode 100644
index 0000000..1a9b34f
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-stats.html
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.27. pg_stats</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations" /><link rel="next" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.27. <code class="structname">pg_stats</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-STATS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.27. <code class="structname">pg_stats</code></h2></div></div></div><a id="id-1.10.5.31.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_stats</code> provides access to
+ the information stored in the <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>
+ catalog. This view allows access only to rows of
+ <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a> that correspond to tables the
+ user has permission to read, and therefore it is safe to allow public
+ read access to this view.
+ </p><p>
+ <code class="structname">pg_stats</code> is also designed to present the
+ information in a more readable format than the underlying catalog
+ — at the cost that its schema must be extended whenever new slot types
+ are defined for <a class="link" href="catalog-pg-statistic.html" title="53.51. pg_statistic"><code class="structname">pg_statistic</code></a>.
+ </p><div class="table" id="id-1.10.5.31.5"><p class="title"><strong>Table 54.27. <code class="structname">pg_stats</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_stats Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">attname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-attribute.html" title="53.7. pg_attribute"><code class="structname">pg_attribute</code></a>.<code class="structfield">attname</code>)
+ </p>
+ <p>
+ Name of column described by this row
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">inherited</code> <code class="type">bool</code>
+ </p>
+ <p>
+ If true, this row includes values from child tables, not just the
+ values in the specified table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">null_frac</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Fraction of column entries that are null
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">avg_width</code> <code class="type">int4</code>
+ </p>
+ <p>
+ Average width in bytes of column's entries
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">n_distinct</code> <code class="type">float4</code>
+ </p>
+ <p>
+ If greater than zero, the estimated number of distinct values in the
+ column. If less than zero, the negative of the number of distinct
+ values divided by the number of rows. (The negated form is used when
+ <code class="command">ANALYZE</code> believes that the number of distinct values is
+ likely to increase as the table grows; the positive form is used when
+ the column seems to have a fixed number of possible values.) For
+ example, -1 indicates a unique column in which the number of distinct
+ values is the same as the number of rows.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_vals</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of the most common values in the column. (Null if
+ no values seem to be more common than any others.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_freqs</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A list of the frequencies of the most common values,
+ i.e., number of occurrences of each divided by total number of rows.
+ (Null when <code class="structfield">most_common_vals</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">histogram_bounds</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of values that divide the column's values into groups of
+ approximately equal population. The values in
+ <code class="structfield">most_common_vals</code>, if present, are omitted from this
+ histogram calculation. (This column is null if the column data type
+ does not have a <code class="literal">&lt;</code> operator or if the
+ <code class="structfield">most_common_vals</code> list accounts for the entire
+ population.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">correlation</code> <code class="type">float4</code>
+ </p>
+ <p>
+ Statistical correlation between physical row ordering and
+ logical ordering of the column values. This ranges from -1 to +1.
+ When the value is near -1 or +1, an index scan on the column will
+ be estimated to be cheaper than when it is near zero, due to reduction
+ of random access to the disk. (This column is null if the column data
+ type does not have a <code class="literal">&lt;</code> operator.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_elems</code> <code class="type">anyarray</code>
+ </p>
+ <p>
+ A list of non-null element values most often appearing within values of
+ the column. (Null for scalar types.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">most_common_elem_freqs</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A list of the frequencies of the most common element values, i.e., the
+ fraction of rows containing at least one instance of the given value.
+ Two or three additional values follow the per-element frequencies;
+ these are the minimum and maximum of the preceding per-element
+ frequencies, and optionally the frequency of null elements.
+ (Null when <code class="structfield">most_common_elems</code> is.)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">elem_count_histogram</code> <code class="type">float4[]</code>
+ </p>
+ <p>
+ A histogram of the counts of distinct non-null element values within the
+ values of the column, followed by the average number of distinct
+ non-null elements. (Null for scalar types.)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ The maximum number of entries in the array fields can be controlled on a
+ column-by-column basis using the <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER
+ TABLE SET STATISTICS</code></a>
+ command, or globally by setting the
+ <a class="xref" href="runtime-config-query.html#GUC-DEFAULT-STATISTICS-TARGET">default_statistics_target</a> run-time parameter.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.26. <code class="structname">pg_shmem_allocations</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.28. <code class="structname">pg_stats_ext</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-tables.html b/doc/src/sgml/html/view-pg-tables.html
new file mode 100644
index 0000000..21f4d9f
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-tables.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.30. pg_tables</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs" /><link rel="next" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.30. <code class="structname">pg_tables</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-TABLES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.30. <code class="structname">pg_tables</code></h2></div></div></div><a id="id-1.10.5.34.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_tables</code> provides access to
+ useful information about each table in the database.
+ </p><div class="table" id="id-1.10.5.34.4"><p class="title"><strong>Table 54.30. <code class="structname">pg_tables</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_tables Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablename</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of table
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tableowner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of table's owner
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">tablespace</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-tablespace.html" title="53.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">spcname</code>)
+ </p>
+ <p>
+ Name of tablespace containing table (null if default for database)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">hasindexes</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relhasindex</code>)
+ </p>
+ <p>
+ True if table has (or recently had) any indexes
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">hasrules</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relhasrules</code>)
+ </p>
+ <p>
+ True if table has (or once had) rules
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">hastriggers</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relhastriggers</code>)
+ </p>
+ <p>
+ True if table has (or once had) triggers
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">rowsecurity</code> <code class="type">bool</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relrowsecurity</code>)
+ </p>
+ <p>
+ True if row security is enabled on the table
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.29. <code class="structname">pg_stats_ext_exprs</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.31. <code class="structname">pg_timezone_abbrevs</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-timezone-abbrevs.html b/doc/src/sgml/html/view-pg-timezone-abbrevs.html
new file mode 100644
index 0000000..b7ef98c
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-timezone-abbrevs.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.31. pg_timezone_abbrevs</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-tables.html" title="54.30. pg_tables" /><link rel="next" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.31. <code class="structname">pg_timezone_abbrevs</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-tables.html" title="54.30. pg_tables">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-TIMEZONE-ABBREVS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.31. <code class="structname">pg_timezone_abbrevs</code></h2></div></div></div><a id="id-1.10.5.35.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_timezone_abbrevs</code> provides a list
+ of time zone abbreviations that are currently recognized by the datetime
+ input routines. The contents of this view change when the
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE-ABBREVIATIONS">timezone_abbreviations</a> run-time parameter is modified.
+ </p><div class="table" id="id-1.10.5.35.4"><p class="title"><strong>Table 54.31. <code class="structname">pg_timezone_abbrevs</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_timezone_abbrevs Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">abbrev</code> <code class="type">text</code>
+ </p>
+ <p>
+ Time zone abbreviation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">utc_offset</code> <code class="type">interval</code>
+ </p>
+ <p>
+ Offset from UTC (positive means east of Greenwich)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_dst</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if this is a daylight-savings abbreviation
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ While most timezone abbreviations represent fixed offsets from UTC,
+ there are some that have historically varied in value
+ (see <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a> for more information).
+ In such cases this view presents their current meaning.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-tables.html" title="54.30. pg_tables">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.30. <code class="structname">pg_tables</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.32. <code class="structname">pg_timezone_names</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-timezone-names.html b/doc/src/sgml/html/view-pg-timezone-names.html
new file mode 100644
index 0000000..bbcb17c
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-timezone-names.html
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.32. pg_timezone_names</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs" /><link rel="next" href="view-pg-user.html" title="54.33. pg_user" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.32. <code class="structname">pg_timezone_names</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-user.html" title="54.33. pg_user">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-TIMEZONE-NAMES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.32. <code class="structname">pg_timezone_names</code></h2></div></div></div><a id="id-1.10.5.36.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_timezone_names</code> provides a list
+ of time zone names that are recognized by <code class="command">SET TIMEZONE</code>,
+ along with their associated abbreviations, UTC offsets,
+ and daylight-savings status. (Technically,
+ <span class="productname">PostgreSQL</span> does not use UTC because leap
+ seconds are not handled.)
+ Unlike the abbreviations shown in <a class="link" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs"><code class="structname">pg_timezone_abbrevs</code></a>, many of these names imply a set of daylight-savings transition
+ date rules. Therefore, the associated information changes across local DST
+ boundaries. The displayed information is computed based on the current
+ value of <code class="function">CURRENT_TIMESTAMP</code>.
+ </p><div class="table" id="id-1.10.5.36.4"><p class="title"><strong>Table 54.32. <code class="structname">pg_timezone_names</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_timezone_names Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">name</code> <code class="type">text</code>
+ </p>
+ <p>
+ Time zone name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">abbrev</code> <code class="type">text</code>
+ </p>
+ <p>
+ Time zone abbreviation
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">utc_offset</code> <code class="type">interval</code>
+ </p>
+ <p>
+ Offset from UTC (positive means east of Greenwich)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">is_dst</code> <code class="type">bool</code>
+ </p>
+ <p>
+ True if currently observing daylight savings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-user.html" title="54.33. pg_user">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.31. <code class="structname">pg_timezone_abbrevs</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.33. <code class="structname">pg_user</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-user-mappings.html b/doc/src/sgml/html/view-pg-user-mappings.html
new file mode 100644
index 0000000..e55c2c1
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-user-mappings.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.34. pg_user_mappings</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-user.html" title="54.33. pg_user" /><link rel="next" href="view-pg-views.html" title="54.35. pg_views" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.34. <code class="structname">pg_user_mappings</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-user.html" title="54.33. pg_user">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-views.html" title="54.35. pg_views">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-USER-MAPPINGS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.34. <code class="structname">pg_user_mappings</code></h2></div></div></div><a id="id-1.10.5.38.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_user_mappings</code> provides access
+ to information about user mappings. This is essentially a publicly
+ readable view of
+ <a class="link" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping"><code class="structname">pg_user_mapping</code></a>
+ that leaves out the options field if the user has no rights to use
+ it.
+ </p><div class="table" id="id-1.10.5.38.4"><p class="title"><strong>Table 54.34. <code class="structname">pg_user_mappings</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_user_mappings Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping"><code class="structname">pg_user_mapping</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the user mapping
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvid</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server"><code class="structname">pg_foreign_server</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ The OID of the foreign server that contains this mapping
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">srvname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-foreign-server.html" title="53.24. pg_foreign_server"><code class="structname">pg_foreign_server</code></a>.<code class="structfield">srvname</code>)
+ </p>
+ <p>
+ Name of the foreign server
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umuser</code> <code class="type">oid</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">oid</code>)
+ </p>
+ <p>
+ OID of the local role being mapped, or zero if the user mapping is public
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usename</code> <code class="type">name</code>
+ </p>
+ <p>
+ Name of the local user to be mapped
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">umoptions</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ User mapping specific options, as <span class="quote">“<span class="quote">keyword=value</span>”</span> strings
+ </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ To protect password information stored as a user mapping option,
+ the <code class="structfield">umoptions</code> column will read as null
+ unless one of the following applies:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ current user is the user being mapped, and owns the server or
+ holds <code class="literal">USAGE</code> privilege on it
+ </p></li><li class="listitem"><p>
+ current user is the server owner and mapping is for <code class="literal">PUBLIC</code>
+ </p></li><li class="listitem"><p>
+ current user is a superuser
+ </p></li></ul></div><p>
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-user.html" title="54.33. pg_user">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-views.html" title="54.35. pg_views">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.33. <code class="structname">pg_user</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.35. <code class="structname">pg_views</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-user.html b/doc/src/sgml/html/view-pg-user.html
new file mode 100644
index 0000000..b91720a
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-user.html
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.33. pg_user</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names" /><link rel="next" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.33. <code class="structname">pg_user</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-USER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.33. <code class="structname">pg_user</code></h2></div></div></div><a id="id-1.10.5.37.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_user</code> provides access to
+ information about database users. This is simply a publicly
+ readable view of
+ <a class="link" href="view-pg-shadow.html" title="54.25. pg_shadow"><code class="structname">pg_shadow</code></a>
+ that blanks out the password field.
+ </p><div class="table" id="id-1.10.5.37.4"><p class="title"><strong>Table 54.33. <code class="structname">pg_user</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_user Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usename</code> <code class="type">name</code>
+ </p>
+ <p>
+ User name
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesysid</code> <code class="type">oid</code>
+ </p>
+ <p>
+ ID of this user
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usecreatedb</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User can create databases
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usesuper</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User is a superuser
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">userepl</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User can initiate streaming replication and put the system in and
+ out of backup mode.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">usebypassrls</code> <code class="type">bool</code>
+ </p>
+ <p>
+ User bypasses every row-level security policy, see
+ <a class="xref" href="ddl-rowsecurity.html" title="5.8. Row Security Policies">Section 5.8</a> for more information.
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">passwd</code> <code class="type">text</code>
+ </p>
+ <p>
+ Not the password (always reads as <code class="literal">********</code>)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">valuntil</code> <code class="type">timestamptz</code>
+ </p>
+ <p>
+ Password expiry time (only used for password authentication)
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">useconfig</code> <code class="type">text[]</code>
+ </p>
+ <p>
+ Session defaults for run-time configuration variables
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.32. <code class="structname">pg_timezone_names</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.34. <code class="structname">pg_user_mappings</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/view-pg-views.html b/doc/src/sgml/html/view-pg-views.html
new file mode 100644
index 0000000..ce568db
--- /dev/null
+++ b/doc/src/sgml/html/view-pg-views.html
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.35. pg_views</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings" /><link rel="next" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.35. <code class="structname">pg_views</code></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEW-PG-VIEWS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.35. <code class="structname">pg_views</code></h2></div></div></div><a id="id-1.10.5.39.2" class="indexterm"></a><p>
+ The view <code class="structname">pg_views</code> provides access to
+ useful information about each view in the database.
+ </p><div class="table" id="id-1.10.5.39.4"><p class="title"><strong>Table 54.35. <code class="structname">pg_views</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_views Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
+ Column Type
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">schemaname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-namespace.html" title="53.32. pg_namespace"><code class="structname">pg_namespace</code></a>.<code class="structfield">nspname</code>)
+ </p>
+ <p>
+ Name of schema containing view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">viewname</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relname</code>)
+ </p>
+ <p>
+ Name of view
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">viewowner</code> <code class="type">name</code>
+ (references <a class="link" href="catalog-pg-authid.html" title="53.8. pg_authid"><code class="structname">pg_authid</code></a>.<code class="structfield">rolname</code>)
+ </p>
+ <p>
+ Name of view's owner
+ </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
+ <code class="structfield">definition</code> <code class="type">text</code>
+ </p>
+ <p>
+ View definition (a reconstructed <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a> query)
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Next</a></td></tr><tr><td width="40%" align="left" valign="top">54.34. <code class="structname">pg_user_mappings</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 55. Frontend/Backend Protocol</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/views-overview.html b/doc/src/sgml/html/views-overview.html
new file mode 100644
index 0000000..1133c80
--- /dev/null
+++ b/doc/src/sgml/html/views-overview.html
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>54.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="views.html" title="Chapter 54. System Views" /><link rel="next" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">54.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="views.html" title="Chapter 54. System Views">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><th width="60%" align="center">Chapter 54. System Views</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions">Next</a></td></tr></table><hr /></div><div class="sect1" id="VIEWS-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">54.1. Overview</h2></div></div></div><p>
+ <a class="xref" href="views-overview.html#VIEW-TABLE" title="Table 54.1. System Views">Table 54.1</a> lists the system views.
+ More detailed documentation of each catalog follows below.
+ Except where noted, all the views described here are read-only.
+ </p><div class="table" id="VIEW-TABLE"><p class="title"><strong>Table 54.1. System Views</strong></p><div class="table-contents"><table class="table" summary="System Views" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>View Name</th><th>Purpose</th></tr></thead><tbody><tr><td><a class="link" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions"><code class="structname">pg_available_extensions</code></a></td><td>available extensions</td></tr><tr><td><a class="link" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions"><code class="structname">pg_available_extension_versions</code></a></td><td>available versions of extensions</td></tr><tr><td><a class="link" href="view-pg-backend-memory-contexts.html" title="54.4. pg_backend_memory_contexts"><code class="structname">pg_backend_memory_contexts</code></a></td><td>backend memory contexts</td></tr><tr><td><a class="link" href="view-pg-config.html" title="54.5. pg_config"><code class="structname">pg_config</code></a></td><td>compile-time configuration parameters</td></tr><tr><td><a class="link" href="view-pg-cursors.html" title="54.6. pg_cursors"><code class="structname">pg_cursors</code></a></td><td>open cursors</td></tr><tr><td><a class="link" href="view-pg-file-settings.html" title="54.7. pg_file_settings"><code class="structname">pg_file_settings</code></a></td><td>summary of configuration file contents</td></tr><tr><td><a class="link" href="view-pg-group.html" title="54.8. pg_group"><code class="structname">pg_group</code></a></td><td>groups of database users</td></tr><tr><td><a class="link" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a></td><td>summary of client authentication configuration file contents</td></tr><tr><td><a class="link" href="view-pg-ident-file-mappings.html" title="54.10. pg_ident_file_mappings"><code class="structname">pg_ident_file_mappings</code></a></td><td>summary of client user name mapping configuration file contents</td></tr><tr><td><a class="link" href="view-pg-indexes.html" title="54.11. pg_indexes"><code class="structname">pg_indexes</code></a></td><td>indexes</td></tr><tr><td><a class="link" href="view-pg-locks.html" title="54.12. pg_locks"><code class="structname">pg_locks</code></a></td><td>locks currently held or awaited</td></tr><tr><td><a class="link" href="view-pg-matviews.html" title="54.13. pg_matviews"><code class="structname">pg_matviews</code></a></td><td>materialized views</td></tr><tr><td><a class="link" href="view-pg-policies.html" title="54.14. pg_policies"><code class="structname">pg_policies</code></a></td><td>policies</td></tr><tr><td><a class="link" href="view-pg-prepared-statements.html" title="54.15. pg_prepared_statements"><code class="structname">pg_prepared_statements</code></a></td><td>prepared statements</td></tr><tr><td><a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a></td><td>prepared transactions</td></tr><tr><td><a class="link" href="view-pg-publication-tables.html" title="54.17. pg_publication_tables"><code class="structname">pg_publication_tables</code></a></td><td>publications and information of their associated tables</td></tr><tr><td><a class="link" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status"><code class="structname">pg_replication_origin_status</code></a></td><td>information about replication origins, including replication progress</td></tr><tr><td><a class="link" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots"><code class="structname">pg_replication_slots</code></a></td><td>replication slot information</td></tr><tr><td><a class="link" href="view-pg-roles.html" title="54.20. pg_roles"><code class="structname">pg_roles</code></a></td><td>database roles</td></tr><tr><td><a class="link" href="view-pg-rules.html" title="54.21. pg_rules"><code class="structname">pg_rules</code></a></td><td>rules</td></tr><tr><td><a class="link" href="view-pg-seclabels.html" title="54.22. pg_seclabels"><code class="structname">pg_seclabels</code></a></td><td>security labels</td></tr><tr><td><a class="link" href="view-pg-sequences.html" title="54.23. pg_sequences"><code class="structname">pg_sequences</code></a></td><td>sequences</td></tr><tr><td><a class="link" href="view-pg-settings.html" title="54.24. pg_settings"><code class="structname">pg_settings</code></a></td><td>parameter settings</td></tr><tr><td><a class="link" href="view-pg-shadow.html" title="54.25. pg_shadow"><code class="structname">pg_shadow</code></a></td><td>database users</td></tr><tr><td><a class="link" href="view-pg-shmem-allocations.html" title="54.26. pg_shmem_allocations"><code class="structname">pg_shmem_allocations</code></a></td><td>shared memory allocations</td></tr><tr><td><a class="link" href="view-pg-stats.html" title="54.27. pg_stats"><code class="structname">pg_stats</code></a></td><td>planner statistics</td></tr><tr><td><a class="link" href="view-pg-stats-ext.html" title="54.28. pg_stats_ext"><code class="structname">pg_stats_ext</code></a></td><td>extended planner statistics</td></tr><tr><td><a class="link" href="view-pg-stats-ext-exprs.html" title="54.29. pg_stats_ext_exprs"><code class="structname">pg_stats_ext_exprs</code></a></td><td>extended planner statistics for expressions</td></tr><tr><td><a class="link" href="view-pg-tables.html" title="54.30. pg_tables"><code class="structname">pg_tables</code></a></td><td>tables</td></tr><tr><td><a class="link" href="view-pg-timezone-abbrevs.html" title="54.31. pg_timezone_abbrevs"><code class="structname">pg_timezone_abbrevs</code></a></td><td>time zone abbreviations</td></tr><tr><td><a class="link" href="view-pg-timezone-names.html" title="54.32. pg_timezone_names"><code class="structname">pg_timezone_names</code></a></td><td>time zone names</td></tr><tr><td><a class="link" href="view-pg-user.html" title="54.33. pg_user"><code class="structname">pg_user</code></a></td><td>database users</td></tr><tr><td><a class="link" href="view-pg-user-mappings.html" title="54.34. pg_user_mappings"><code class="structname">pg_user_mappings</code></a></td><td>user mappings</td></tr><tr><td><a class="link" href="view-pg-views.html" title="54.35. pg_views"><code class="structname">pg_views</code></a></td><td>views</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="views.html" title="Chapter 54. System Views">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="views.html" title="Chapter 54. System Views">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 54. System Views </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.2. <code class="structname">pg_available_extensions</code></td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/views.html b/doc/src/sgml/html/views.html
new file mode 100644
index 0000000..33a09c6
--- /dev/null
+++ b/doc/src/sgml/html/views.html
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 54. System Views</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping" /><link rel="next" href="views-overview.html" title="54.1. Overview" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 54. System Views</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="views-overview.html" title="54.1. Overview">Next</a></td></tr></table><hr /></div><div class="chapter" id="VIEWS"><div class="titlepage"><div><div><h2 class="title">Chapter 54. System Views</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="views-overview.html">54.1. Overview</a></span></dt><dt><span class="sect1"><a href="view-pg-available-extensions.html">54.2. <code class="structname">pg_available_extensions</code></a></span></dt><dt><span class="sect1"><a href="view-pg-available-extension-versions.html">54.3. <code class="structname">pg_available_extension_versions</code></a></span></dt><dt><span class="sect1"><a href="view-pg-backend-memory-contexts.html">54.4. <code class="structname">pg_backend_memory_contexts</code></a></span></dt><dt><span class="sect1"><a href="view-pg-config.html">54.5. <code class="structname">pg_config</code></a></span></dt><dt><span class="sect1"><a href="view-pg-cursors.html">54.6. <code class="structname">pg_cursors</code></a></span></dt><dt><span class="sect1"><a href="view-pg-file-settings.html">54.7. <code class="structname">pg_file_settings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-group.html">54.8. <code class="structname">pg_group</code></a></span></dt><dt><span class="sect1"><a href="view-pg-hba-file-rules.html">54.9. <code class="structname">pg_hba_file_rules</code></a></span></dt><dt><span class="sect1"><a href="view-pg-ident-file-mappings.html">54.10. <code class="structname">pg_ident_file_mappings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-indexes.html">54.11. <code class="structname">pg_indexes</code></a></span></dt><dt><span class="sect1"><a href="view-pg-locks.html">54.12. <code class="structname">pg_locks</code></a></span></dt><dt><span class="sect1"><a href="view-pg-matviews.html">54.13. <code class="structname">pg_matviews</code></a></span></dt><dt><span class="sect1"><a href="view-pg-policies.html">54.14. <code class="structname">pg_policies</code></a></span></dt><dt><span class="sect1"><a href="view-pg-prepared-statements.html">54.15. <code class="structname">pg_prepared_statements</code></a></span></dt><dt><span class="sect1"><a href="view-pg-prepared-xacts.html">54.16. <code class="structname">pg_prepared_xacts</code></a></span></dt><dt><span class="sect1"><a href="view-pg-publication-tables.html">54.17. <code class="structname">pg_publication_tables</code></a></span></dt><dt><span class="sect1"><a href="view-pg-replication-origin-status.html">54.18. <code class="structname">pg_replication_origin_status</code></a></span></dt><dt><span class="sect1"><a href="view-pg-replication-slots.html">54.19. <code class="structname">pg_replication_slots</code></a></span></dt><dt><span class="sect1"><a href="view-pg-roles.html">54.20. <code class="structname">pg_roles</code></a></span></dt><dt><span class="sect1"><a href="view-pg-rules.html">54.21. <code class="structname">pg_rules</code></a></span></dt><dt><span class="sect1"><a href="view-pg-seclabels.html">54.22. <code class="structname">pg_seclabels</code></a></span></dt><dt><span class="sect1"><a href="view-pg-sequences.html">54.23. <code class="structname">pg_sequences</code></a></span></dt><dt><span class="sect1"><a href="view-pg-settings.html">54.24. <code class="structname">pg_settings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-shadow.html">54.25. <code class="structname">pg_shadow</code></a></span></dt><dt><span class="sect1"><a href="view-pg-shmem-allocations.html">54.26. <code class="structname">pg_shmem_allocations</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats.html">54.27. <code class="structname">pg_stats</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats-ext.html">54.28. <code class="structname">pg_stats_ext</code></a></span></dt><dt><span class="sect1"><a href="view-pg-stats-ext-exprs.html">54.29. <code class="structname">pg_stats_ext_exprs</code></a></span></dt><dt><span class="sect1"><a href="view-pg-tables.html">54.30. <code class="structname">pg_tables</code></a></span></dt><dt><span class="sect1"><a href="view-pg-timezone-abbrevs.html">54.31. <code class="structname">pg_timezone_abbrevs</code></a></span></dt><dt><span class="sect1"><a href="view-pg-timezone-names.html">54.32. <code class="structname">pg_timezone_names</code></a></span></dt><dt><span class="sect1"><a href="view-pg-user.html">54.33. <code class="structname">pg_user</code></a></span></dt><dt><span class="sect1"><a href="view-pg-user-mappings.html">54.34. <code class="structname">pg_user_mappings</code></a></span></dt><dt><span class="sect1"><a href="view-pg-views.html">54.35. <code class="structname">pg_views</code></a></span></dt></dl></div><p>
+ In addition to the system catalogs, <span class="productname">PostgreSQL</span>
+ provides a number of built-in views. Some system views provide convenient
+ access to some commonly used queries on the system catalogs. Other views
+ provide access to internal server state.
+ </p><p>
+ The information schema (<a class="xref" href="information-schema.html" title="Chapter 37. The Information Schema">Chapter 37</a>) 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 <span class="productname">PostgreSQL</span>-specific,
+ it's usually better to use the information schema if it provides all
+ the information you need.
+ </p><p>
+ <a class="xref" href="views-overview.html#VIEW-TABLE" title="Table 54.1. System Views">Table 54.1</a> lists the system views described here.
+ More detailed documentation of each view follows below.
+ There are some additional views that provide access to accumulated
+ statistics; they are described in
+ <a class="xref" href="monitoring-stats.html#MONITORING-STATS-VIEWS-TABLE" title="Table 28.2. Collected Statistics Views">Table 28.2</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="catalog-pg-user-mapping.html" title="53.65. pg_user_mapping">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="views-overview.html" title="54.1. Overview">Next</a></td></tr><tr><td width="40%" align="left" valign="top">53.65. <code class="structname">pg_user_mapping</code> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 54.1. Overview</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal-async-commit.html b/doc/src/sgml/html/wal-async-commit.html
new file mode 100644
index 0000000..8b5c55f
--- /dev/null
+++ b/doc/src/sgml/html/wal-async-commit.html
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.4. Asynchronous Commit</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)" /><link rel="next" href="wal-configuration.html" title="30.5. WAL Configuration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.4. Asynchronous Commit</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal-configuration.html" title="30.5. WAL Configuration">Next</a></td></tr></table><hr /></div><div class="sect1" id="WAL-ASYNC-COMMIT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.4. Asynchronous Commit</h2></div></div></div><a id="id-1.6.17.6.2" class="indexterm"></a><a id="id-1.6.17.6.3" class="indexterm"></a><p>
+ <em class="firstterm">Asynchronous commit</em> is an option that allows transactions
+ to complete more quickly, at the cost that the most recent transactions may
+ be lost if the database should crash. In many applications this is an
+ acceptable trade-off.
+ </p><p>
+ As described in the previous section, transaction commit is normally
+ <em class="firstterm">synchronous</em>: the server waits for the transaction's
+ <acronym class="acronym">WAL</acronym> records to be flushed to permanent storage
+ before returning a success indication to the client. The client is
+ therefore guaranteed that a transaction reported to be committed will
+ be preserved, even in the event of a server crash immediately after.
+ However, for short transactions this delay is a major component of the
+ total transaction time. Selecting asynchronous commit mode means that
+ the server returns success as soon as the transaction is logically
+ completed, before the <acronym class="acronym">WAL</acronym> records it generated have
+ actually made their way to disk. This can provide a significant boost
+ in throughput for small transactions.
+ </p><p>
+ Asynchronous commit introduces the risk of data loss. There is a short
+ time window between the report of transaction completion to the client
+ and the time that the transaction is truly committed (that is, it is
+ guaranteed not to be lost if the server crashes). Thus asynchronous
+ commit should not be used if the client will take external actions
+ relying on the assumption that the transaction will be remembered.
+ As an example, a bank would certainly not use asynchronous commit for
+ a transaction recording an ATM's dispensing of cash. But in many
+ scenarios, such as event logging, there is no need for a strong
+ guarantee of this kind.
+ </p><p>
+ The risk that is taken by using asynchronous commit is of data loss,
+ not data corruption. If the database should crash, it will recover
+ by replaying <acronym class="acronym">WAL</acronym> up to the last record that was
+ flushed. The database will therefore be restored to a self-consistent
+ state, but any transactions that were not yet flushed to disk will
+ not be reflected in that state. The net effect is therefore loss of
+ the last few transactions. Because the transactions are replayed in
+ commit order, no inconsistency can be introduced — for example,
+ if transaction B made changes relying on the effects of a previous
+ transaction A, it is not possible for A's effects to be lost while B's
+ effects are preserved.
+ </p><p>
+ The user can select the commit mode of each transaction, so that
+ it is possible to have both synchronous and asynchronous commit
+ transactions running concurrently. This allows flexible trade-offs
+ between performance and certainty of transaction durability.
+ The commit mode is controlled by the user-settable parameter
+ <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a>, which can be changed in any of
+ the ways that a configuration parameter can be set. The mode used for
+ any one transaction depends on the value of
+ <code class="varname">synchronous_commit</code> when transaction commit begins.
+ </p><p>
+ Certain utility commands, for instance <code class="command">DROP TABLE</code>, are
+ forced to commit synchronously regardless of the setting of
+ <code class="varname">synchronous_commit</code>. This is to ensure consistency
+ between the server's file system and the logical state of the database.
+ The commands supporting two-phase commit, such as <code class="command">PREPARE
+ TRANSACTION</code>, are also always synchronous.
+ </p><p>
+ If the database crashes during the risk window between an
+ asynchronous commit and the writing of the transaction's
+ <acronym class="acronym">WAL</acronym> records,
+ then changes made during that transaction <span class="emphasis"><em>will</em></span> be lost.
+ The duration of the
+ risk window is limited because a background process (the <span class="quote">“<span class="quote">WAL
+ writer</span>”</span>) flushes unwritten <acronym class="acronym">WAL</acronym> records to disk
+ every <a class="xref" href="runtime-config-wal.html#GUC-WAL-WRITER-DELAY">wal_writer_delay</a> milliseconds.
+ The actual maximum duration of the risk window is three times
+ <code class="varname">wal_writer_delay</code> because the WAL writer is
+ designed to favor writing whole pages at a time during busy periods.
+ </p><div class="caution"><h3 class="title">Caution</h3><p>
+ An immediate-mode shutdown is equivalent to a server crash, and will
+ therefore cause loss of any unflushed asynchronous commits.
+ </p></div><p>
+ Asynchronous commit provides behavior different from setting
+ <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> = off.
+ <code class="varname">fsync</code> is a server-wide
+ setting that will alter the behavior of all transactions. It disables
+ all logic within <span class="productname">PostgreSQL</span> that attempts to synchronize
+ writes to different portions of the database, and therefore a system
+ crash (that is, a hardware or operating system crash, not a failure of
+ <span class="productname">PostgreSQL</span> itself) could result in arbitrarily bad
+ corruption of the database state. In many scenarios, asynchronous
+ commit provides most of the performance improvement that could be
+ obtained by turning off <code class="varname">fsync</code>, but without the risk
+ of data corruption.
+ </p><p>
+ <a class="xref" href="runtime-config-wal.html#GUC-COMMIT-DELAY">commit_delay</a> also sounds very similar to
+ asynchronous commit, but it is actually a synchronous commit method
+ (in fact, <code class="varname">commit_delay</code> is ignored during an
+ asynchronous commit). <code class="varname">commit_delay</code> causes a delay
+ just before a transaction flushes <acronym class="acronym">WAL</acronym> to disk, in
+ the hope that a single flush executed by one such transaction can also
+ serve other transactions committing at about the same time. The
+ setting can be thought of as a way of increasing the time window in
+ which transactions can join a group about to participate in a single
+ flush, to amortize the cost of the flush among multiple transactions.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-intro.html" title="30.3. Write-Ahead Logging (WAL)">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal-configuration.html" title="30.5. WAL Configuration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>) </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.5. <acronym class="acronym">WAL</acronym> Configuration</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal-configuration.html b/doc/src/sgml/html/wal-configuration.html
new file mode 100644
index 0000000..45d4f2f
--- /dev/null
+++ b/doc/src/sgml/html/wal-configuration.html
@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.5. WAL Configuration</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-async-commit.html" title="30.4. Asynchronous Commit" /><link rel="next" href="wal-internals.html" title="30.6. WAL Internals" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.5. <acronym class="acronym">WAL</acronym> Configuration</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal-internals.html" title="30.6. WAL Internals">Next</a></td></tr></table><hr /></div><div class="sect1" id="WAL-CONFIGURATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.5. <acronym class="acronym">WAL</acronym> Configuration</h2></div></div></div><p>
+ There are several <acronym class="acronym">WAL</acronym>-related configuration parameters that
+ affect database performance. This section explains their use.
+ Consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a> for general information about
+ setting server configuration parameters.
+ </p><p>
+ <em class="firstterm">Checkpoints</em><a id="id-1.6.17.7.3.2" class="indexterm"></a>
+ are points in the sequence of transactions at which it is guaranteed
+ that the heap and index data files have been updated with all
+ information written before that checkpoint. At checkpoint time, all
+ dirty data pages are flushed to disk and a special checkpoint record is
+ written to the log file. (The change records were previously flushed
+ to the <acronym class="acronym">WAL</acronym> files.)
+ In the event of a crash, the crash recovery procedure looks at the latest
+ checkpoint record to determine the point in the log (known as the redo
+ record) from which it should start the REDO operation. Any changes made to
+ data files before that point are guaranteed to be already on disk.
+ Hence, after a checkpoint, log segments preceding the one containing
+ the redo record are no longer needed and can be recycled or removed. (When
+ <acronym class="acronym">WAL</acronym> archiving is being done, the log segments must be
+ archived before being recycled or removed.)
+ </p><p>
+ The checkpoint requirement of flushing all dirty data pages to disk
+ can cause a significant I/O load. For this reason, checkpoint
+ activity is throttled so that I/O begins at checkpoint start and completes
+ before the next checkpoint is due to start; this minimizes performance
+ degradation during checkpoints.
+ </p><p>
+ The server's checkpointer process automatically performs
+ a checkpoint every so often. A checkpoint is begun every <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-TIMEOUT">checkpoint_timeout</a> seconds, or if
+ <a class="xref" href="runtime-config-wal.html#GUC-MAX-WAL-SIZE">max_wal_size</a> is about to be exceeded,
+ whichever comes first.
+ The default settings are 5 minutes and 1 GB, respectively.
+ If no WAL has been written since the previous checkpoint, new checkpoints
+ will be skipped even if <code class="varname">checkpoint_timeout</code> has passed.
+ (If WAL archiving is being used and you want to put a lower limit on how
+ often files are archived in order to bound potential data loss, you should
+ adjust the <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> parameter rather than the
+ checkpoint parameters.)
+ It is also possible to force a checkpoint by using the SQL
+ command <code class="command">CHECKPOINT</code>.
+ </p><p>
+ Reducing <code class="varname">checkpoint_timeout</code> and/or
+ <code class="varname">max_wal_size</code> causes checkpoints to occur
+ more often. This allows faster after-crash recovery, since less work
+ will need to be redone. However, one must balance this against the
+ increased cost of flushing dirty data pages more often. If
+ <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> is set (as is the default), there is
+ another factor to consider. To ensure data page consistency,
+ the first modification of a data page after each checkpoint results in
+ logging the entire page content. In that case,
+ a smaller checkpoint interval increases the volume of output to the WAL log,
+ partially negating the goal of using a smaller interval,
+ and in any case causing more disk I/O.
+ </p><p>
+ Checkpoints are fairly expensive, first because they require writing
+ out all currently dirty buffers, and second because they result in
+ extra subsequent WAL traffic as discussed above. It is therefore
+ wise to set the checkpointing parameters high enough so that checkpoints
+ don't happen too often. As a simple sanity check on your checkpointing
+ parameters, you can set the <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-WARNING">checkpoint_warning</a>
+ parameter. If checkpoints happen closer together than
+ <code class="varname">checkpoint_warning</code> seconds,
+ a message will be output to the server log recommending increasing
+ <code class="varname">max_wal_size</code>. Occasional appearance of such
+ a message is not cause for alarm, but if it appears often then the
+ checkpoint control parameters should be increased. Bulk operations such
+ as large <code class="command">COPY</code> transfers might cause a number of such warnings
+ to appear if you have not set <code class="varname">max_wal_size</code> high
+ enough.
+ </p><p>
+ To avoid flooding the I/O system with a burst of page writes,
+ writing dirty buffers during a checkpoint is spread over a period of time.
+ That period is controlled by
+ <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-COMPLETION-TARGET">checkpoint_completion_target</a>, which is
+ given as a fraction of the checkpoint interval (configured by using
+ <code class="varname">checkpoint_timeout</code>).
+ The I/O rate is adjusted so that the checkpoint finishes when the
+ given fraction of
+ <code class="varname">checkpoint_timeout</code> seconds have elapsed, or before
+ <code class="varname">max_wal_size</code> is exceeded, whichever is sooner.
+ With the default value of 0.9,
+ <span class="productname">PostgreSQL</span> can be expected to complete each checkpoint
+ a bit before the next scheduled checkpoint (at around 90% of the last checkpoint's
+ duration). This spreads out the I/O as much as possible so that the checkpoint
+ I/O load is consistent throughout the checkpoint interval. The disadvantage of
+ this is that prolonging checkpoints affects recovery time, because more WAL
+ segments will need to be kept around for possible use in recovery. A user
+ concerned about the amount of time required to recover might wish to reduce
+ <code class="varname">checkpoint_timeout</code> so that checkpoints occur more frequently
+ but still spread the I/O across the checkpoint interval. Alternatively,
+ <code class="varname">checkpoint_completion_target</code> could be reduced, but this would
+ result in times of more intense I/O (during the checkpoint) and times of less I/O
+ (after the checkpoint completed but before the next scheduled checkpoint) and
+ therefore is not recommended.
+ Although <code class="varname">checkpoint_completion_target</code> could be set as high as
+ 1.0, it is typically recommended to set it to no higher than 0.9 (the default)
+ since checkpoints include some other activities besides writing dirty buffers.
+ A setting of 1.0 is quite likely to result in checkpoints not being
+ completed on time, which would result in performance loss due to
+ unexpected variation in the number of WAL segments needed.
+ </p><p>
+ On Linux and POSIX platforms <a class="xref" href="runtime-config-wal.html#GUC-CHECKPOINT-FLUSH-AFTER">checkpoint_flush_after</a>
+ allows to force the OS that pages written by the checkpoint should be
+ flushed to disk after a configurable number of bytes. Otherwise, these
+ pages may be kept in the OS's page cache, inducing a stall when
+ <code class="literal">fsync</code> is issued at the end of a checkpoint. This setting will
+ often help to reduce transaction latency, but it also can have an adverse
+ effect on performance; particularly for workloads that are bigger than
+ <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but smaller than the OS's page cache.
+ </p><p>
+ The number of WAL segment files in <code class="filename">pg_wal</code> directory depends on
+ <code class="varname">min_wal_size</code>, <code class="varname">max_wal_size</code> and
+ the amount of WAL generated in previous checkpoint cycles. When old log
+ segment files are no longer needed, they are removed or recycled (that is,
+ renamed to become future segments in the numbered sequence). If, due to a
+ short-term peak of log output rate, <code class="varname">max_wal_size</code> is
+ exceeded, the unneeded segment files will be removed until the system
+ gets back under this limit. Below that limit, the system recycles enough
+ WAL files to cover the estimated need until the next checkpoint, and
+ removes the rest. The estimate is based on a moving average of the number
+ of WAL files used in previous checkpoint cycles. The moving average
+ is increased immediately if the actual usage exceeds the estimate, so it
+ accommodates peak usage rather than average usage to some extent.
+ <code class="varname">min_wal_size</code> puts a minimum on the amount of WAL files
+ recycled for future usage; that much WAL is always recycled for future use,
+ even if the system is idle and the WAL usage estimate suggests that little
+ WAL is needed.
+ </p><p>
+ Independently of <code class="varname">max_wal_size</code>,
+ the most recent <a class="xref" href="runtime-config-replication.html#GUC-WAL-KEEP-SIZE">wal_keep_size</a> megabytes of
+ WAL files plus one additional WAL file are
+ kept at all times. Also, if WAL archiving is used, old segments cannot be
+ removed or recycled until they are archived. If WAL archiving cannot keep up
+ with the pace that WAL is generated, or if <code class="varname">archive_command</code>
+ or <code class="varname">archive_library</code>
+ fails repeatedly, old WAL files will accumulate in <code class="filename">pg_wal</code>
+ until the situation is resolved. A slow or failed standby server that
+ uses a replication slot will have the same effect (see
+ <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>).
+ </p><p>
+ In archive recovery or standby mode, the server periodically performs
+ <em class="firstterm">restartpoints</em>,<a id="id-1.6.17.7.12.2" class="indexterm"></a>
+ which are similar to checkpoints in normal operation: the server forces
+ all its state to disk, updates the <code class="filename">pg_control</code> file to
+ indicate that the already-processed WAL data need not be scanned again,
+ and then recycles any old log segment files in the <code class="filename">pg_wal</code>
+ directory.
+ Restartpoints can't be performed more frequently than checkpoints on the
+ primary because restartpoints can only be performed at checkpoint records.
+ A restartpoint is triggered when a checkpoint record is reached if at
+ least <code class="varname">checkpoint_timeout</code> seconds have passed since the last
+ restartpoint, or if WAL size is about to exceed
+ <code class="varname">max_wal_size</code>. However, because of limitations on when a
+ restartpoint can be performed, <code class="varname">max_wal_size</code> is often exceeded
+ during recovery, by up to one checkpoint cycle's worth of WAL.
+ (<code class="varname">max_wal_size</code> is never a hard limit anyway, so you should
+ always leave plenty of headroom to avoid running out of disk space.)
+ </p><p>
+ There are two commonly used internal <acronym class="acronym">WAL</acronym> functions:
+ <code class="function">XLogInsertRecord</code> and <code class="function">XLogFlush</code>.
+ <code class="function">XLogInsertRecord</code> is used to place a new record into
+ the <acronym class="acronym">WAL</acronym> buffers in shared memory. If there is no
+ space for the new record, <code class="function">XLogInsertRecord</code> will have
+ to write (move to kernel cache) a few filled <acronym class="acronym">WAL</acronym>
+ buffers. This is undesirable because <code class="function">XLogInsertRecord</code>
+ is used on every database low level modification (for example, row
+ insertion) at a time when an exclusive lock is held on affected
+ data pages, so the operation needs to be as fast as possible. What
+ is worse, writing <acronym class="acronym">WAL</acronym> buffers might also force the
+ creation of a new log segment, which takes even more
+ time. Normally, <acronym class="acronym">WAL</acronym> buffers should be written
+ and flushed by an <code class="function">XLogFlush</code> request, which is
+ made, for the most part, at transaction commit time to ensure that
+ transaction records are flushed to permanent storage. On systems
+ with high log output, <code class="function">XLogFlush</code> requests might
+ not occur often enough to prevent <code class="function">XLogInsertRecord</code>
+ from having to do writes. On such systems
+ one should increase the number of <acronym class="acronym">WAL</acronym> buffers by
+ modifying the <a class="xref" href="runtime-config-wal.html#GUC-WAL-BUFFERS">wal_buffers</a> parameter. When
+ <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> is set and the system is very busy,
+ setting <code class="varname">wal_buffers</code> higher will help smooth response times
+ during the period immediately following each checkpoint.
+ </p><p>
+ The <a class="xref" href="runtime-config-wal.html#GUC-COMMIT-DELAY">commit_delay</a> parameter defines for how many
+ microseconds a group commit leader process will sleep after acquiring a
+ lock within <code class="function">XLogFlush</code>, while group commit
+ followers queue up behind the leader. This delay allows other server
+ processes to add their commit records to the WAL buffers so that all of
+ them will be flushed by the leader's eventual sync operation. No sleep
+ will occur if <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> is not enabled, or if fewer
+ than <a class="xref" href="runtime-config-wal.html#GUC-COMMIT-SIBLINGS">commit_siblings</a> other sessions are currently
+ in active transactions; this avoids sleeping when it's unlikely that
+ any other session will commit soon. Note that on some platforms, the
+ resolution of a sleep request is ten milliseconds, so that any nonzero
+ <code class="varname">commit_delay</code> setting between 1 and 10000
+ microseconds would have the same effect. Note also that on some
+ platforms, sleep operations may take slightly longer than requested by
+ the parameter.
+ </p><p>
+ Since the purpose of <code class="varname">commit_delay</code> is to allow the
+ cost of each flush operation to be amortized across concurrently
+ committing transactions (potentially at the expense of transaction
+ latency), it is necessary to quantify that cost before the setting can
+ be chosen intelligently. The higher that cost is, the more effective
+ <code class="varname">commit_delay</code> is expected to be in increasing
+ transaction throughput, up to a point. The <a class="xref" href="pgtestfsync.html" title="pg_test_fsync"><span class="refentrytitle"><span class="application">pg_test_fsync</span></span></a> program can be used to measure the average time
+ in microseconds that a single WAL flush operation takes. A value of
+ half of the average time the program reports it takes to flush after a
+ single 8kB write operation is often the most effective setting for
+ <code class="varname">commit_delay</code>, so this value is recommended as the
+ starting point to use when optimizing for a particular workload. While
+ tuning <code class="varname">commit_delay</code> is particularly useful when the
+ WAL log is stored on high-latency rotating disks, benefits can be
+ significant even on storage media with very fast sync times, such as
+ solid-state drives or RAID arrays with a battery-backed write cache;
+ but this should definitely be tested against a representative workload.
+ Higher values of <code class="varname">commit_siblings</code> should be used in
+ such cases, whereas smaller <code class="varname">commit_siblings</code> values
+ are often helpful on higher latency media. Note that it is quite
+ possible that a setting of <code class="varname">commit_delay</code> that is too
+ high can increase transaction latency by so much that total transaction
+ throughput suffers.
+ </p><p>
+ When <code class="varname">commit_delay</code> is set to zero (the default), it
+ is still possible for a form of group commit to occur, but each group
+ will consist only of sessions that reach the point where they need to
+ flush their commit records during the window in which the previous
+ flush operation (if any) is occurring. At higher client counts a
+ <span class="quote">“<span class="quote">gangway effect</span>”</span> tends to occur, so that the effects of group
+ commit become significant even when <code class="varname">commit_delay</code> is
+ zero, and thus explicitly setting <code class="varname">commit_delay</code> tends
+ to help less. Setting <code class="varname">commit_delay</code> can only help
+ when (1) there are some concurrently committing transactions, and (2)
+ throughput is limited to some degree by commit rate; but with high
+ rotational latency this setting can be effective in increasing
+ transaction throughput with as few as two clients (that is, a single
+ committing client with one sibling transaction).
+ </p><p>
+ The <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a> parameter determines how
+ <span class="productname">PostgreSQL</span> will ask the kernel to force
+ <acronym class="acronym">WAL</acronym> updates out to disk.
+ All the options should be the same in terms of reliability, with
+ the exception of <code class="literal">fsync_writethrough</code>, which can sometimes
+ force a flush of the disk cache even when other options do not do so.
+ However, it's quite platform-specific which one will be the fastest.
+ You can test the speeds of different options using the <a class="xref" href="pgtestfsync.html" title="pg_test_fsync"><span class="refentrytitle"><span class="application">pg_test_fsync</span></span></a> program.
+ Note that this parameter is irrelevant if <code class="varname">fsync</code>
+ has been turned off.
+ </p><p>
+ Enabling the <a class="xref" href="runtime-config-developer.html#GUC-WAL-DEBUG">wal_debug</a> configuration parameter
+ (provided that <span class="productname">PostgreSQL</span> has been
+ compiled with support for it) will result in each
+ <code class="function">XLogInsertRecord</code> and <code class="function">XLogFlush</code>
+ <acronym class="acronym">WAL</acronym> call being logged to the server log. This
+ option might be replaced by a more general mechanism in the future.
+ </p><p>
+ There are two internal functions to write WAL data to disk:
+ <code class="function">XLogWrite</code> and <code class="function">issue_xlog_fsync</code>.
+ When <a class="xref" href="runtime-config-statistics.html#GUC-TRACK-WAL-IO-TIMING">track_wal_io_timing</a> is enabled, the total
+ amounts of time <code class="function">XLogWrite</code> writes and
+ <code class="function">issue_xlog_fsync</code> syncs WAL data to disk are counted as
+ <code class="literal">wal_write_time</code> and <code class="literal">wal_sync_time</code> in
+ <a class="xref" href="monitoring-stats.html#PG-STAT-WAL-VIEW" title="Table 28.24. pg_stat_wal View">pg_stat_wal</a>, respectively.
+ <code class="function">XLogWrite</code> is normally called by
+ <code class="function">XLogInsertRecord</code> (when there is no space for the new
+ record in WAL buffers), <code class="function">XLogFlush</code> and the WAL writer,
+ to write WAL buffers to disk and call <code class="function">issue_xlog_fsync</code>.
+ <code class="function">issue_xlog_fsync</code> is normally called by
+ <code class="function">XLogWrite</code> to sync WAL files to disk.
+ If <code class="varname">wal_sync_method</code> is either
+ <code class="literal">open_datasync</code> or <code class="literal">open_sync</code>,
+ a write operation in <code class="function">XLogWrite</code> guarantees to sync written
+ WAL data to disk and <code class="function">issue_xlog_fsync</code> does nothing.
+ If <code class="varname">wal_sync_method</code> is either <code class="literal">fdatasync</code>,
+ <code class="literal">fsync</code>, or <code class="literal">fsync_writethrough</code>,
+ the write operation moves WAL buffers to kernel cache and
+ <code class="function">issue_xlog_fsync</code> syncs them to disk. Regardless
+ of the setting of <code class="varname">track_wal_io_timing</code>, the number
+ of times <code class="function">XLogWrite</code> writes and
+ <code class="function">issue_xlog_fsync</code> syncs WAL data to disk are also
+ counted as <code class="literal">wal_write</code> and <code class="literal">wal_sync</code>
+ in <code class="structname">pg_stat_wal</code>, respectively.
+ </p><p>
+ The <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-PREFETCH">recovery_prefetch</a> parameter can be used to reduce
+ I/O wait times during recovery by instructing the kernel to initiate reads
+ of disk blocks that will soon be needed but are not currently in
+ <span class="productname">PostgreSQL</span>'s buffer pool.
+ The <a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY">maintenance_io_concurrency</a> and
+ <a class="xref" href="runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE">wal_decode_buffer_size</a> settings limit prefetching
+ concurrency and distance, respectively. By default, it is set to
+ <code class="literal">try</code>, which enables the feature on systems where
+ <code class="function">posix_fadvise</code> is available.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal-internals.html" title="30.6. WAL Internals">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.4. Asynchronous Commit </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.6. WAL Internals</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal-internals.html b/doc/src/sgml/html/wal-internals.html
new file mode 100644
index 0000000..e692147
--- /dev/null
+++ b/doc/src/sgml/html/wal-internals.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.6. WAL Internals</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-configuration.html" title="30.5. WAL Configuration" /><link rel="next" href="logical-replication.html" title="Chapter 31. Logical Replication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.6. WAL Internals</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-configuration.html" title="30.5. WAL Configuration">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication.html" title="Chapter 31. Logical Replication">Next</a></td></tr></table><hr /></div><div class="sect1" id="WAL-INTERNALS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.6. WAL Internals</h2></div></div></div><a id="id-1.6.17.8.2" class="indexterm"></a><p>
+ <acronym class="acronym">WAL</acronym> is automatically enabled; no action is
+ required from the administrator except ensuring that the
+ disk-space requirements for the <acronym class="acronym">WAL</acronym> logs are met,
+ and that any necessary tuning is done (see <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a>).
+ </p><p>
+ <acronym class="acronym">WAL</acronym> records are appended to the <acronym class="acronym">WAL</acronym>
+ logs as each new record is written. The insert position is described by
+ a Log Sequence Number (<acronym class="acronym">LSN</acronym>) that is a byte offset into
+ the logs, increasing monotonically with each new record.
+ <acronym class="acronym">LSN</acronym> values are returned as the datatype
+ <a class="link" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type"><code class="type">pg_lsn</code></a>. Values can be
+ compared to calculate the volume of <acronym class="acronym">WAL</acronym> data that
+ separates them, so they are used to measure the progress of replication
+ and recovery.
+ </p><p>
+ <acronym class="acronym">WAL</acronym> logs are stored in the directory
+ <code class="filename">pg_wal</code> under the data directory, as a set of
+ segment files, normally each 16 MB in size (but the size can be changed
+ by altering the <code class="option">--wal-segsize</code> <span class="application">initdb</span> option). Each segment is
+ divided into pages, normally 8 kB each (this size can be changed via the
+ <code class="option">--with-wal-blocksize</code> configure option). The log record headers
+ are described in <code class="filename">access/xlogrecord.h</code>; the record
+ content is dependent on the type of event that is being logged. Segment
+ files are given ever-increasing numbers as names, starting at
+ <code class="filename">000000010000000000000001</code>. The numbers do not wrap,
+ but it will take a very, very long time to exhaust the
+ available stock of numbers.
+ </p><p>
+ It is advantageous if the log is located on a different disk from the
+ main database files. This can be achieved by moving the
+ <code class="filename">pg_wal</code> directory to another location (while the server
+ is shut down, of course) and creating a symbolic link from the
+ original location in the main data directory to the new location.
+ </p><p>
+ The aim of <acronym class="acronym">WAL</acronym> is to ensure that the log is
+ written before database records are altered, but this can be subverted by
+ disk drives<a id="id-1.6.17.8.7.2" class="indexterm"></a> that falsely report a
+ successful write to the kernel,
+ when in fact they have only cached the data and not yet stored it
+ on the disk. A power failure in such a situation might lead to
+ irrecoverable data corruption. Administrators should try to ensure
+ that disks holding <span class="productname">PostgreSQL</span>'s
+ <acronym class="acronym">WAL</acronym> log files do not make such false reports.
+ (See <a class="xref" href="wal-reliability.html" title="30.1. Reliability">Section 30.1</a>.)
+ </p><p>
+ After a checkpoint has been made and the log flushed, the
+ checkpoint's position is saved in the file
+ <code class="filename">pg_control</code>. Therefore, at the start of recovery,
+ the server first reads <code class="filename">pg_control</code> and
+ then the checkpoint record; then it performs the REDO operation by
+ scanning forward from the log location indicated in the checkpoint
+ record. Because the entire content of data pages is saved in the
+ log on the first page modification after a checkpoint (assuming
+ <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> is not disabled), all pages
+ changed since the checkpoint will be restored to a consistent
+ state.
+ </p><p>
+ To deal with the case where <code class="filename">pg_control</code> is
+ corrupt, we should support the possibility of scanning existing log
+ segments in reverse order — newest to oldest — in order to find the
+ latest checkpoint. This has not been implemented yet.
+ <code class="filename">pg_control</code> is small enough (less than one disk page)
+ that it is not subject to partial-write problems, and as of this writing
+ there have been no reports of database failures due solely to the inability
+ to read <code class="filename">pg_control</code> itself. So while it is
+ theoretically a weak spot, <code class="filename">pg_control</code> does not
+ seem to be a problem in practice.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-configuration.html" title="30.5. WAL Configuration">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication.html" title="Chapter 31. Logical Replication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.5. <acronym class="acronym">WAL</acronym> Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 31. Logical Replication</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal-intro.html b/doc/src/sgml/html/wal-intro.html
new file mode 100644
index 0000000..fd36028
--- /dev/null
+++ b/doc/src/sgml/html/wal-intro.html
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.3. Write-Ahead Logging (WAL)</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="checksums.html" title="30.2. Data Checksums" /><link rel="next" href="wal-async-commit.html" title="30.4. Asynchronous Commit" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>)</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="checksums.html" title="30.2. Data Checksums">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Next</a></td></tr></table><hr /></div><div class="sect1" id="WAL-INTRO"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>)</h2></div></div></div><a id="id-1.6.17.5.2" class="indexterm"></a><a id="id-1.6.17.5.3" class="indexterm"></a><p>
+ <em class="firstterm">Write-Ahead Logging</em> (<acronym class="acronym">WAL</acronym>)
+ is a standard method for ensuring data integrity. A detailed
+ description can be found in most (if not all) books about
+ transaction processing. Briefly, <acronym class="acronym">WAL</acronym>'s central
+ concept is that changes to data files (where tables and indexes
+ reside) must be written only after those changes have been logged,
+ that is, after log records describing the changes have been flushed
+ to permanent storage. If we follow this procedure, we do not need
+ to flush data pages to disk on every transaction commit, because we
+ know that in the event of a crash we will be able to recover the
+ database using the log: any changes that have not been applied to
+ the data pages can be redone from the log records. (This is
+ roll-forward recovery, also known as REDO.)
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ Because <acronym class="acronym">WAL</acronym> restores database file
+ contents after a crash, journaled file systems are not necessary for
+ reliable storage of the data files or WAL files. In fact, journaling
+ overhead can reduce performance, especially if journaling
+ causes file system <span class="emphasis"><em>data</em></span> to be flushed
+ to disk. Fortunately, data flushing during journaling can
+ often be disabled with a file system mount option, e.g.,
+ <code class="literal">data=writeback</code> on a Linux ext3 file system.
+ Journaled file systems do improve boot speed after a crash.
+ </p></div><p>
+ Using <acronym class="acronym">WAL</acronym> results in a
+ significantly reduced number of disk writes, because only the log
+ file needs to be flushed to disk to guarantee that a transaction is
+ committed, rather than every data file changed by the transaction.
+ The log file is written sequentially,
+ and so the cost of syncing the log is much less than the cost of
+ flushing the data pages. This is especially true for servers
+ handling many small transactions touching different parts of the data
+ store. Furthermore, when the server is processing many small concurrent
+ transactions, one <code class="function">fsync</code> of the log file may
+ suffice to commit many transactions.
+ </p><p>
+ <acronym class="acronym">WAL</acronym> also makes it possible to support on-line
+ backup and point-in-time recovery, as described in <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>. By archiving the WAL data we can support
+ reverting to any time instant covered by the available WAL data:
+ we simply install a prior physical backup of the database, and
+ replay the WAL log just as far as the desired time. What's more,
+ the physical backup doesn't have to be an instantaneous snapshot
+ of the database state — if it is made over some period of time,
+ then replaying the WAL log for that period will fix any internal
+ inconsistencies.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="checksums.html" title="30.2. Data Checksums">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Next</a></td></tr><tr><td width="40%" align="left" valign="top">30.2. Data Checksums </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.4. Asynchronous Commit</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal-reliability.html b/doc/src/sgml/html/wal-reliability.html
new file mode 100644
index 0000000..84505e3
--- /dev/null
+++ b/doc/src/sgml/html/wal-reliability.html
@@ -0,0 +1,161 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>30.1. Reliability</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log" /><link rel="next" href="checksums.html" title="30.2. Data Checksums" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">30.1. Reliability</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><th width="60%" align="center">Chapter 30. Reliability and the Write-Ahead Log</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="checksums.html" title="30.2. Data Checksums">Next</a></td></tr></table><hr /></div><div class="sect1" id="WAL-RELIABILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">30.1. Reliability</h2></div></div></div><p>
+ Reliability is an important property of any serious database
+ system, and <span class="productname">PostgreSQL</span> does everything possible to
+ guarantee reliable operation. One aspect of reliable operation is
+ that all data recorded by a committed transaction should be stored
+ in a nonvolatile area that is safe from power loss, operating
+ system failure, and hardware failure (except failure of the
+ nonvolatile area itself, of course). Successfully writing the data
+ to the computer's permanent storage (disk drive or equivalent)
+ ordinarily meets this requirement. In fact, even if a computer is
+ fatally damaged, if the disk drives survive they can be moved to
+ another computer with similar hardware and all committed
+ transactions will remain intact.
+ </p><p>
+ While forcing data to the disk platters periodically might seem like
+ a simple operation, it is not. Because disk drives are dramatically
+ slower than main memory and CPUs, several layers of caching exist
+ between the computer's main memory and the disk platters.
+ First, there is the operating system's buffer cache, which caches
+ frequently requested disk blocks and combines disk writes. Fortunately,
+ all operating systems give applications a way to force writes from
+ the buffer cache to disk, and <span class="productname">PostgreSQL</span> uses those
+ features. (See the <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a> parameter
+ to adjust how this is done.)
+ </p><p>
+ Next, there might be a cache in the disk drive controller; this is
+ particularly common on <acronym class="acronym">RAID</acronym> controller cards. Some of
+ these caches are <em class="firstterm">write-through</em>, meaning writes are sent
+ to the drive as soon as they arrive. Others are
+ <em class="firstterm">write-back</em>, meaning data is sent to the drive at
+ some later time. Such caches can be a reliability hazard because the
+ memory in the disk controller cache is volatile, and will lose its
+ contents in a power failure. Better controller cards have
+ <em class="firstterm">battery-backup units</em> (<acronym class="acronym">BBU</acronym>s), meaning
+ the card has a battery that
+ maintains power to the cache in case of system power loss. After power
+ is restored the data will be written to the disk drives.
+ </p><p>
+ And finally, most disk drives have caches. Some are write-through
+ while some are write-back, and the same concerns about data loss
+ exist for write-back drive caches as for disk controller
+ caches. Consumer-grade IDE and SATA drives are particularly likely
+ to have write-back caches that will not survive a power failure. Many
+ solid-state drives (SSD) also have volatile write-back caches.
+ </p><p>
+ These caches can typically be disabled; however, the method for doing
+ this varies by operating system and drive type:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ On <span class="productname">Linux</span>, IDE and SATA drives can be queried using
+ <code class="command">hdparm -I</code>; write caching is enabled if there is
+ a <code class="literal">*</code> next to <code class="literal">Write cache</code>. <code class="command">hdparm -W 0</code>
+ can be used to turn off write caching. SCSI drives can be queried
+ using <a class="ulink" href="http://sg.danny.cz/sg/sdparm.html" target="_top"><span class="application">sdparm</span></a>.
+ Use <code class="command">sdparm --get=WCE</code> to check
+ whether the write cache is enabled and <code class="command">sdparm --clear=WCE</code>
+ to disable it.
+ </p></li><li class="listitem"><p>
+ On <span class="productname">FreeBSD</span>, IDE drives can be queried using
+ <code class="command">atacontrol</code> and write caching turned off using
+ <code class="literal">hw.ata.wc=0</code> in <code class="filename">/boot/loader.conf</code>;
+ SCSI drives can be queried using <code class="command">camcontrol identify</code>,
+ and the write cache both queried and changed using
+ <code class="command">sdparm</code> when available.
+ </p></li><li class="listitem"><p>
+ On <span class="productname">Solaris</span>, the disk write cache is controlled by
+ <code class="command">format -e</code>.
+ (The Solaris <acronym class="acronym">ZFS</acronym> file system is safe with disk write-cache
+ enabled because it issues its own disk cache flush commands.)
+ </p></li><li class="listitem"><p>
+ On <span class="productname">Windows</span>, if <code class="varname">wal_sync_method</code> is
+ <code class="literal">open_datasync</code> (the default), write caching can be disabled
+ by unchecking <code class="literal">My Computer\Open\<em class="replaceable"><code>disk drive</code></em>\Properties\Hardware\Properties\Policies\Enable write caching on the disk</code>.
+ Alternatively, set <code class="varname">wal_sync_method</code> to
+ <code class="literal">fsync</code> or <code class="literal">fsync_writethrough</code>, which prevent
+ write caching.
+ </p></li><li class="listitem"><p>
+ On <span class="productname">macOS</span>, write caching can be prevented by
+ setting <code class="varname">wal_sync_method</code> to <code class="literal">fsync_writethrough</code>.
+ </p></li></ul></div><p>
+ Recent SATA drives (those following <acronym class="acronym">ATAPI-6</acronym> or later)
+ offer a drive cache flush command (<code class="command">FLUSH CACHE EXT</code>),
+ while SCSI drives have long supported a similar command
+ <code class="command">SYNCHRONIZE CACHE</code>. These commands are not directly
+ accessible to <span class="productname">PostgreSQL</span>, but some file systems
+ (e.g., <acronym class="acronym">ZFS</acronym>, <acronym class="acronym">ext4</acronym>) can use them to flush
+ data to the platters on write-back-enabled drives. Unfortunately, such
+ file systems behave suboptimally when combined with battery-backup unit
+ (<acronym class="acronym">BBU</acronym>) disk controllers. In such setups, the synchronize
+ command forces all data from the controller cache to the disks,
+ eliminating much of the benefit of the BBU. You can run the
+ <a class="xref" href="pgtestfsync.html" title="pg_test_fsync"><span class="refentrytitle"><span class="application">pg_test_fsync</span></span></a> program to see
+ if you are affected. If you are affected, the performance benefits
+ of the BBU can be regained by turning off write barriers in
+ the file system or reconfiguring the disk controller, if that is
+ an option. If write barriers are turned off, make sure the battery
+ remains functional; a faulty battery can potentially lead to data loss.
+ Hopefully file system and disk controller designers will eventually
+ address this suboptimal behavior.
+ </p><p>
+ When the operating system sends a write request to the storage hardware,
+ there is little it can do to make sure the data has arrived at a truly
+ non-volatile storage area. Rather, it is the
+ administrator's responsibility to make certain that all storage components
+ ensure integrity for both data and file-system metadata.
+ Avoid disk controllers that have non-battery-backed write caches.
+ At the drive level, disable write-back caching if the
+ drive cannot guarantee the data will be written before shutdown.
+ If you use SSDs, be aware that many of these do not honor cache flush
+ commands by default.
+ You can test for reliable I/O subsystem behavior using <a class="ulink" href="https://brad.livejournal.com/2116715.html" target="_top"><code class="filename">diskchecker.pl</code></a>.
+ </p><p>
+ Another risk of data loss is posed by the disk platter write
+ operations themselves. Disk platters are divided into sectors,
+ commonly 512 bytes each. Every physical read or write operation
+ processes a whole sector.
+ When a write request arrives at the drive, it might be for some multiple
+ of 512 bytes (<span class="productname">PostgreSQL</span> typically writes 8192 bytes, or
+ 16 sectors, at a time), and the process of writing could fail due
+ to power loss at any time, meaning some of the 512-byte sectors were
+ written while others were not. To guard against such failures,
+ <span class="productname">PostgreSQL</span> periodically writes full page images to
+ permanent WAL storage <span class="emphasis"><em>before</em></span> modifying the actual page on
+ disk. By doing this, during crash recovery <span class="productname">PostgreSQL</span> can
+ restore partially-written pages from WAL. If you have file-system software
+ that prevents partial page writes (e.g., ZFS), you can turn off
+ this page imaging by turning off the <a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> parameter. Battery-Backed Unit
+ (BBU) disk controllers do not prevent partial page writes unless
+ they guarantee that data is written to the BBU as full (8kB) pages.
+ </p><p>
+ <span class="productname">PostgreSQL</span> also protects against some kinds of data corruption
+ on storage devices that may occur because of hardware errors or media failure over time,
+ such as reading/writing garbage data.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Each individual record in a WAL file is protected by a CRC-32 (32-bit) check
+ that allows us to tell if record contents are correct. The CRC value
+ is set when we write each WAL record and checked during crash recovery,
+ archive recovery and replication.
+ </p></li><li class="listitem"><p>
+ Data pages are not currently checksummed by default, though full page images
+ recorded in WAL records will be protected; see <a class="link" href="app-initdb.html#APP-INITDB-DATA-CHECKSUMS"><span class="application">initdb</span></a>
+ for details about enabling data checksums.
+ </p></li><li class="listitem"><p>
+ Internal data structures such as <code class="filename">pg_xact</code>, <code class="filename">pg_subtrans</code>, <code class="filename">pg_multixact</code>,
+ <code class="filename">pg_serial</code>, <code class="filename">pg_notify</code>, <code class="filename">pg_stat</code>, <code class="filename">pg_snapshots</code> are not directly
+ checksummed, nor are pages protected by full page writes. However, where
+ such data structures are persistent, WAL records are written that allow
+ recent changes to be accurately rebuilt at crash recovery and those
+ WAL records are protected as discussed above.
+ </p></li><li class="listitem"><p>
+ Individual state files in <code class="filename">pg_twophase</code> are protected by CRC-32.
+ </p></li><li class="listitem"><p>
+ Temporary data files used in larger SQL queries for sorts,
+ materializations and intermediate results are not currently checksummed,
+ nor will WAL records be written for changes to those files.
+ </p></li></ul></div><p>
+ </p><p>
+ <span class="productname">PostgreSQL</span> does not protect against correctable memory errors
+ and it is assumed you will operate using RAM that uses industry standard
+ Error Correcting Codes (ECC) or better protection.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal.html" title="Chapter 30. Reliability and the Write-Ahead Log">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="checksums.html" title="30.2. Data Checksums">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 30. Reliability and the Write-Ahead Log </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.2. Data Checksums</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/wal.html b/doc/src/sgml/html/wal.html
new file mode 100644
index 0000000..db27ef2
--- /dev/null
+++ b/doc/src/sgml/html/wal.html
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 30. Reliability and the Write-Ahead Log</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="disk-full.html" title="29.2. Disk Full Failure" /><link rel="next" href="wal-reliability.html" title="30.1. Reliability" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 30. Reliability and the Write-Ahead Log</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="disk-full.html" title="29.2. Disk Full Failure">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><th width="60%" align="center">Part III. Server Administration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="wal-reliability.html" title="30.1. Reliability">Next</a></td></tr></table><hr /></div><div class="chapter" id="WAL"><div class="titlepage"><div><div><h2 class="title">Chapter 30. Reliability and the Write-Ahead Log</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="wal-reliability.html">30.1. Reliability</a></span></dt><dt><span class="sect1"><a href="checksums.html">30.2. Data Checksums</a></span></dt><dd><dl><dt><span class="sect2"><a href="checksums.html#CHECKSUMS-OFFLINE-ENABLE-DISABLE">30.2.1. Off-line Enabling of Checksums</a></span></dt></dl></dd><dt><span class="sect1"><a href="wal-intro.html">30.3. Write-Ahead Logging (<acronym class="acronym">WAL</acronym>)</a></span></dt><dt><span class="sect1"><a href="wal-async-commit.html">30.4. Asynchronous Commit</a></span></dt><dt><span class="sect1"><a href="wal-configuration.html">30.5. <acronym class="acronym">WAL</acronym> Configuration</a></span></dt><dt><span class="sect1"><a href="wal-internals.html">30.6. WAL Internals</a></span></dt></dl></div><p>
+ This chapter explains how the Write-Ahead Log is used to obtain
+ efficient, reliable operation.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="disk-full.html" title="29.2. Disk Full Failure">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="admin.html" title="Part III. Server Administration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wal-reliability.html" title="30.1. Reliability">Next</a></td></tr><tr><td width="40%" align="left" valign="top">29.2. Disk Full Failure </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 30.1. Reliability</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/warm-standby-failover.html b/doc/src/sgml/html/warm-standby-failover.html
new file mode 100644
index 0000000..f3c1002
--- /dev/null
+++ b/doc/src/sgml/html/warm-standby-failover.html
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>27.3. Failover</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers" /><link rel="next" href="hot-standby.html" title="27.4. Hot Standby" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">27.3. Failover</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><th width="60%" align="center">Chapter 27. High Availability, Load Balancing, and Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="hot-standby.html" title="27.4. Hot Standby">Next</a></td></tr></table><hr /></div><div class="sect1" id="WARM-STANDBY-FAILOVER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">27.3. Failover</h2></div></div></div><p>
+ If the primary server fails then the standby server should begin
+ failover procedures.
+ </p><p>
+ If the standby server fails then no failover need take place. If the
+ standby server can be restarted, even some time later, then the recovery
+ process can also be restarted immediately, taking advantage of
+ restartable recovery. If the standby server cannot be restarted, then a
+ full new standby server instance should be created.
+ </p><p>
+ If the primary server fails and the standby server becomes the
+ new primary, and then the old primary restarts, you must have
+ a mechanism for informing the old primary that it is no longer the primary. This is
+ sometimes known as <acronym class="acronym">STONITH</acronym> (Shoot The Other Node In The Head), which is
+ necessary to avoid situations where both systems think they are the
+ primary, which will lead to confusion and ultimately data loss.
+ </p><p>
+ Many failover systems use just two systems, the primary and the standby,
+ connected by some kind of heartbeat mechanism to continually verify the
+ connectivity between the two and the viability of the primary. It is
+ also possible to use a third system (called a witness server) to prevent
+ some cases of inappropriate failover, but the additional complexity
+ might not be worthwhile unless it is set up with sufficient care and
+ rigorous testing.
+ </p><p>
+ <span class="productname">PostgreSQL</span> does not provide the system
+ software required to identify a failure on the primary and notify
+ the standby database server. Many such tools exist and are well
+ integrated with the operating system facilities required for
+ successful failover, such as IP address migration.
+ </p><p>
+ Once failover to the standby occurs, there is only a
+ single server in operation. This is known as a degenerate state.
+ The former standby is now the primary, but the former primary is down
+ 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 <a class="xref" href="app-pgrewind.html" title="pg_rewind"><span class="refentrytitle"><span class="application">pg_rewind</span></span></a> 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
+ server to provide backup for the new primary until the new standby
+ server is recreated,
+ though clearly this complicates the system configuration and
+ operational processes.
+ </p><p>
+ So, switching from primary to standby server can be fast but requires
+ some time to re-prepare the failover cluster. Regular switching from
+ primary to standby is useful, since it allows regular downtime on
+ each system for maintenance. This also serves as a test of the
+ failover mechanism to ensure that it will really work when you need it.
+ Written administration procedures are advised.
+ </p><p>
+ To trigger failover of a log-shipping standby server, run
+ <code class="command">pg_ctl promote</code>, call <code class="function">pg_promote()</code>,
+ or create a trigger file with the file name and path specified by the
+ <code class="varname">promote_trigger_file</code>. If you're planning to use
+ <code class="command">pg_ctl promote</code> or to call
+ <code class="function">pg_promote()</code> to fail over,
+ <code class="varname">promote_trigger_file</code> is not required. If you're
+ setting up the reporting servers that are only used to offload read-only
+ queries from the primary, not for high availability purposes, you don't
+ need to promote it.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hot-standby.html" title="27.4. Hot Standby">Next</a></td></tr><tr><td width="40%" align="left" valign="top">27.2. Log-Shipping Standby Servers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 27.4. Hot Standby</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/warm-standby.html b/doc/src/sgml/html/warm-standby.html
new file mode 100644
index 0000000..88a2d47
--- /dev/null
+++ b/doc/src/sgml/html/warm-standby.html
@@ -0,0 +1,657 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>27.2. Log-Shipping Standby Servers</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions" /><link rel="next" href="warm-standby-failover.html" title="27.3. Failover" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">27.2. Log-Shipping Standby Servers</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><th width="60%" align="center">Chapter 27. High Availability, Load Balancing, and Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="warm-standby-failover.html" title="27.3. Failover">Next</a></td></tr></table><hr /></div><div class="sect1" id="WARM-STANDBY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">27.2. Log-Shipping Standby Servers</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="warm-standby.html#STANDBY-PLANNING">27.2.1. Planning</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STANDBY-SERVER-OPERATION">27.2.2. Standby Server Operation</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#PREPARING-PRIMARY-FOR-STANDBY">27.2.3. Preparing the Primary for Standby Servers</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STANDBY-SERVER-SETUP">27.2.4. Setting Up a Standby Server</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STREAMING-REPLICATION">27.2.5. Streaming Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#STREAMING-REPLICATION-SLOTS">27.2.6. Replication Slots</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#CASCADING-REPLICATION">27.2.7. Cascading Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#SYNCHRONOUS-REPLICATION">27.2.8. Synchronous Replication</a></span></dt><dt><span class="sect2"><a href="warm-standby.html#CONTINUOUS-ARCHIVING-IN-STANDBY">27.2.9. Continuous Archiving in Standby</a></span></dt></dl></div><p>
+ Continuous archiving can be used to create a <em class="firstterm">high
+ availability</em> (HA) cluster configuration with one or more
+ <em class="firstterm">standby servers</em> ready to take over operations if the
+ primary server fails. This capability is widely referred to as
+ <em class="firstterm">warm standby</em> or <em class="firstterm">log shipping</em>.
+ </p><p>
+ The primary and standby server work together to provide this capability,
+ though the servers are only loosely coupled. The primary server operates
+ in continuous archiving mode, while each standby server operates in
+ continuous recovery mode, reading the WAL files from the primary. No
+ changes to the database tables are required to enable this capability,
+ so it offers low administration overhead compared to some other
+ replication solutions. This configuration also has relatively low
+ performance impact on the primary server.
+ </p><p>
+ Directly moving WAL records from one database server to another
+ is typically described as log shipping. <span class="productname">PostgreSQL</span>
+ implements file-based log shipping by transferring WAL records
+ one file (WAL segment) at a time. WAL files (16MB) can be
+ shipped easily and cheaply over any distance, whether it be to an
+ adjacent system, another system at the same site, or another system on
+ the far side of the globe. The bandwidth required for this technique
+ 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 <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>).
+ </p><p>
+ It should be noted that log shipping is asynchronous, i.e., the WAL
+ records are shipped after transaction commit. As a result, there is a
+ window for data loss should the primary server suffer a catastrophic
+ failure; transactions not yet shipped will be lost. The size of the
+ data loss window in file-based log shipping can be limited by use of the
+ <code class="varname">archive_timeout</code> 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 <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="27.2.5. Streaming Replication">Section 27.2.5</a>)
+ allows a much smaller window of data loss.
+ </p><p>
+ Recovery performance is sufficiently good that the standby will
+ typically be only moments away from full
+ availability once it has been activated. As a result, this is called
+ a warm standby configuration which offers high
+ availability. Restoring a server from an archived base backup and
+ 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 <em class="firstterm">hot standby</em> server. See
+ <a class="xref" href="hot-standby.html" title="27.4. Hot Standby">Section 27.4</a> for more information.
+ </p><a id="id-1.6.14.16.7" class="indexterm"></a><a id="id-1.6.14.16.8" class="indexterm"></a><a id="id-1.6.14.16.9" class="indexterm"></a><a id="id-1.6.14.16.10" class="indexterm"></a><a id="id-1.6.14.16.11" class="indexterm"></a><a id="id-1.6.14.16.12" class="indexterm"></a><div class="sect2" id="STANDBY-PLANNING"><div class="titlepage"><div><div><h3 class="title">27.2.1. Planning</h3></div></div></div><p>
+ It is usually wise to create the primary and standby servers
+ so that they are as similar as possible, at least from the
+ perspective of the database server. In particular, the path names
+ 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
+ <a class="xref" href="sql-createtablespace.html" title="CREATE TABLESPACE"><span class="refentrytitle">CREATE TABLESPACE</span></a>
+ 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
+ that maintaining two identical systems is easier than maintaining two
+ dissimilar ones over the lifetime of the application and system.
+ In any case the hardware architecture must be the same — shipping
+ from, say, a 32-bit to a 64-bit system will not work.
+ </p><p>
+ In general, log shipping between servers running different major
+ <span class="productname">PostgreSQL</span> release
+ levels is not possible. It is the policy of the PostgreSQL Global
+ Development Group not to make changes to disk formats during minor release
+ upgrades, so it is likely that running different minor release levels
+ on primary and standby servers will work successfully. However, no
+ formal support for that is offered and you are advised to keep primary
+ and standby servers at the same release level as much as possible.
+ When updating to a new minor release, the safest policy is to update
+ the standby servers first — a new minor release is more likely
+ to be able to read WAL files from a previous minor release than vice
+ versa.
+ </p></div><div class="sect2" id="STANDBY-SERVER-OPERATION"><div class="titlepage"><div><div><h3 class="title">27.2.2. Standby Server Operation</h3></div></div></div><p>
+ A server enters standby mode if a
+ <span id="FILE-STANDBY-SIGNAL"></span>
+ <code class="filename">standby.signal</code>
+ <a id="id-1.6.14.16.14.2.3" class="indexterm"></a>
+ file exists in the data directory when the server is started.
+ </p><p>
+ In standby mode, the server continuously applies WAL received from the
+ primary server. The standby server can read WAL from a WAL archive
+ (see <a class="xref" href="runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a>) or directly from the primary
+ over a TCP connection (streaming replication). The standby server will
+ also attempt to restore any WAL found in the standby cluster's
+ <code class="filename">pg_wal</code> directory. That typically happens after a server
+ restart, when the standby replays again WAL that was streamed from the
+ primary before the restart, but you can also manually copy files to
+ <code class="filename">pg_wal</code> at any time to have them replayed.
+ </p><p>
+ At startup, the standby begins by restoring all WAL available in the
+ archive location, calling <code class="varname">restore_command</code>. Once it
+ reaches the end of WAL available there and <code class="varname">restore_command</code>
+ fails, it tries to restore any WAL available in the <code class="filename">pg_wal</code> directory.
+ If that fails, and streaming replication has been configured, the
+ standby tries to connect to the primary server and start streaming WAL
+ from the last valid record found in archive or <code class="filename">pg_wal</code>. If that fails
+ or streaming replication is not configured, or if the connection is
+ later disconnected, the standby goes back to step 1 and tries to
+ restore the file from the archive again. This loop of retries from the
+ archive, <code class="filename">pg_wal</code>, and via streaming replication goes on until the server
+ is stopped or failover is triggered by a trigger file.
+ </p><p>
+ Standby mode is exited and the server switches to normal operation
+ when <code class="command">pg_ctl promote</code> is run,
+ <code class="function">pg_promote()</code> is called, or a trigger file is found
+ (<code class="varname">promote_trigger_file</code>). Before failover,
+ any WAL immediately available in the archive or in <code class="filename">pg_wal</code> will be
+ restored, but no attempt is made to connect to the primary.
+ </p></div><div class="sect2" id="PREPARING-PRIMARY-FOR-STANDBY"><div class="titlepage"><div><div><h3 class="title">27.2.3. Preparing the Primary for Standby Servers</h3></div></div></div><p>
+ Set up continuous archiving on the primary to an archive directory
+ accessible from the standby, as described
+ in <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>. The archive location should be
+ accessible from the standby even when the primary is down, i.e., it should
+ reside on the standby server itself or another trusted server, not on
+ the primary server.
+ </p><p>
+ If you want to use streaming replication, set up authentication on the
+ primary server to allow replication connections from the standby
+ server(s); that is, create a role and provide a suitable entry or
+ entries in <code class="filename">pg_hba.conf</code> with the database field set to
+ <code class="literal">replication</code>. Also ensure <code class="varname">max_wal_senders</code> is set
+ to a sufficiently large value in the configuration file of the primary
+ server. If replication slots will be used,
+ ensure that <code class="varname">max_replication_slots</code> is set sufficiently
+ high as well.
+ </p><p>
+ Take a base backup as described in <a class="xref" href="continuous-archiving.html#BACKUP-BASE-BACKUP" title="26.3.2. Making a Base Backup">Section 26.3.2</a>
+ to bootstrap the standby server.
+ </p></div><div class="sect2" id="STANDBY-SERVER-SETUP"><div class="titlepage"><div><div><h3 class="title">27.2.4. Setting Up a Standby Server</h3></div></div></div><p>
+ To set up the standby server, restore the base backup taken from primary
+ server (see <a class="xref" href="continuous-archiving.html#BACKUP-PITR-RECOVERY" title="26.3.4. Recovering Using a Continuous Archive Backup">Section 26.3.4</a>). Create a file
+ <a class="link" href="warm-standby.html#FILE-STANDBY-SIGNAL"><code class="filename">standby.signal</code></a><a id="id-1.6.14.16.16.2.3" class="indexterm"></a>
+ in the standby's cluster data
+ directory. Set <a class="xref" href="runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a> to a simple command to copy files from
+ the WAL archive. If you plan to have multiple standby servers for high
+ availability purposes, make sure that <code class="varname">recovery_target_timeline</code> is set to
+ <code class="literal">latest</code> (the default), to make the standby server follow the timeline change
+ that occurs at failover to another standby.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <a class="xref" href="runtime-config-wal.html#GUC-RESTORE-COMMAND">restore_command</a> should return immediately
+ if the file does not exist; the server will retry the command again if
+ necessary.
+ </p></div><p>
+ If you want to use streaming replication, fill in
+ <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</a> with a libpq connection string, including
+ the host name (or IP address) and any additional details needed to
+ connect to the primary server. If the primary needs a password for
+ authentication, the password needs to be specified in
+ <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</a> as well.
+ </p><p>
+ If you're setting up the standby server for high availability purposes,
+ set up WAL archiving, connections and authentication like the primary
+ server, because the standby server will work as a primary server after
+ failover.
+ </p><p>
+ If you're using a WAL archive, its size can be minimized using the <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-COMMAND">archive_cleanup_command</a> parameter to remove files that are no
+ longer required by the standby server.
+ The <span class="application">pg_archivecleanup</span> utility is designed specifically to
+ be used with <code class="varname">archive_cleanup_command</code> in typical single-standby
+ configurations, see <a class="xref" href="pgarchivecleanup.html" title="pg_archivecleanup"><span class="refentrytitle"><span class="application">pg_archivecleanup</span></span></a>.
+ 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.
+ </p><p>
+ A simple example of configuration is:
+</p><pre class="programlisting">
+primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass options=''-c wal_sender_timeout=5000'''
+restore_command = 'cp /path/to/archive/%f %p'
+archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
+</pre><p>
+ </p><p>
+ You can have any number of standby servers, but if you use streaming
+ replication, make sure you set <code class="varname">max_wal_senders</code> high enough in
+ the primary to allow them to be connected simultaneously.
+ </p></div><div class="sect2" id="STREAMING-REPLICATION"><div class="titlepage"><div><div><h3 class="title">27.2.5. Streaming Replication</h3></div></div></div><a id="id-1.6.14.16.17.2" class="indexterm"></a><p>
+ Streaming replication allows a standby server to stay more up-to-date
+ than is possible with file-based log shipping. The standby connects
+ to the primary, which streams WAL records to the standby as they're
+ generated, without waiting for the WAL file to be filled.
+ </p><p>
+ Streaming replication is asynchronous by default
+ (see <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">Section 27.2.8</a>), 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
+ assuming the standby is powerful enough to keep up with the load. With
+ streaming replication, <code class="varname">archive_timeout</code> is not required to
+ reduce the data loss window.
+ </p><p>
+ If you use streaming replication without file-based continuous
+ archiving, the server might recycle old WAL segments before the standby
+ has received them. If this occurs, the standby will need to be
+ reinitialized from a new base backup. You can avoid this by setting
+ <code class="varname">wal_keep_size</code> to a value large enough to ensure that
+ WAL segments are not recycled too early, or by configuring a replication
+ slot for the standby. If you set up a WAL archive that's accessible from
+ the standby, these solutions are not required, since the standby can
+ always use the archive to catch up provided it retains enough segments.
+ </p><p>
+ To use streaming replication, set up a file-based log-shipping standby
+ server as described in <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>. The step that
+ turns a file-based log-shipping standby into streaming replication
+ standby is setting the <code class="varname">primary_conninfo</code> setting
+ to point to the primary server. Set
+ <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> and authentication options
+ (see <code class="filename">pg_hba.conf</code>) on the primary so that the standby server
+ can connect to the <code class="literal">replication</code> pseudo-database on the primary
+ server (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-AUTHENTICATION" title="27.2.5.1. Authentication">Section 27.2.5.1</a>).
+ </p><p>
+ On systems that support the keepalive socket option, setting
+ <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-IDLE">tcp_keepalives_idle</a>,
+ <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-INTERVAL">tcp_keepalives_interval</a> and
+ <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-COUNT">tcp_keepalives_count</a> helps the primary promptly
+ notice a broken connection.
+ </p><p>
+ Set the maximum number of concurrent connections from the standby servers
+ (see <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> for details).
+ </p><p>
+ When the standby is started and <code class="varname">primary_conninfo</code> is set
+ correctly, the standby will connect to the primary after replaying all
+ WAL files available in the archive. If the connection is established
+ successfully, you will see a <code class="literal">walreceiver</code> in the standby, and
+ a corresponding <code class="literal">walsender</code> process in the primary.
+ </p><div class="sect3" id="STREAMING-REPLICATION-AUTHENTICATION"><div class="titlepage"><div><div><h4 class="title">27.2.5.1. Authentication</h4></div></div></div><p>
+ It is very important that the access privileges for replication be set up
+ so that only trusted users can read the WAL stream, because it is
+ easy to extract privileged information from it. Standby servers must
+ authenticate to the primary as an account that has the
+ <code class="literal">REPLICATION</code> privilege or a superuser. It is
+ recommended to create a dedicated user account with
+ <code class="literal">REPLICATION</code> and <code class="literal">LOGIN</code>
+ privileges for replication. While <code class="literal">REPLICATION</code>
+ privilege gives very high permissions, it does not allow the user to
+ modify any data on the primary system, which the
+ <code class="literal">SUPERUSER</code> privilege does.
+ </p><p>
+ Client authentication for replication is controlled by a
+ <code class="filename">pg_hba.conf</code> record specifying <code class="literal">replication</code> in the
+ <em class="replaceable"><code>database</code></em> field. For example, if the standby is running on
+ host IP <code class="literal">192.168.1.100</code> and the account name for replication
+ is <code class="literal">foo</code>, the administrator can add the following line to the
+ <code class="filename">pg_hba.conf</code> file on the primary:
+
+</p><pre class="programlisting">
+# Allow the user "foo" from host 192.168.1.100 to connect to the primary
+# as a replication standby if the user's password is correctly supplied.
+#
+# TYPE DATABASE USER ADDRESS METHOD
+host replication foo 192.168.1.100/32 md5
+</pre><p>
+ </p><p>
+ The host name and port number of the primary, connection user name,
+ and password are specified in the <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-CONNINFO">primary_conninfo</a>.
+ The password can also be set in the <code class="filename">~/.pgpass</code> file on the
+ standby (specify <code class="literal">replication</code> in the <em class="replaceable"><code>database</code></em>
+ field).
+ For example, if the primary is running on host IP <code class="literal">192.168.1.50</code>,
+ port <code class="literal">5432</code>, the account name for replication is
+ <code class="literal">foo</code>, and the password is <code class="literal">foopass</code>, the administrator
+ can add the following line to the <code class="filename">postgresql.conf</code> file on the
+ standby:
+
+</p><pre class="programlisting">
+# The standby connects to the primary that is running on host 192.168.1.50
+# and port 5432 as the user "foo" whose password is "foopass".
+primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
+</pre><p>
+ </p></div><div class="sect3" id="STREAMING-REPLICATION-MONITORING"><div class="titlepage"><div><div><h4 class="title">27.2.5.2. Monitoring</h4></div></div></div><p>
+ An important health indicator of streaming replication is the amount
+ of WAL records generated in the primary, but not yet applied in the
+ standby. You can calculate this lag by comparing the current WAL write
+ location on the primary with the last WAL location received by the
+ standby. These locations can be retrieved using
+ <code class="function">pg_current_wal_lsn</code> on the primary and
+ <code class="function">pg_last_wal_receive_lsn</code> on the standby,
+ respectively (see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.89. Backup Control Functions">Table 9.89</a> and
+ <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-INFO-TABLE" title="Table 9.90. Recovery Information Functions">Table 9.90</a> 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
+ <code class="command">ps</code> command (see <a class="xref" href="monitoring-ps.html" title="28.1. Standard Unix Tools">Section 28.1</a> for details).
+ </p><p>
+ You can retrieve a list of WAL sender processes via the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW" title="28.2.4. pg_stat_replication"><code class="structname">
+ pg_stat_replication</code></a> view. Large differences between
+ <code class="function">pg_current_wal_lsn</code> and the view's <code class="literal">sent_lsn</code> field
+ might indicate that the primary server is under heavy load, while
+ differences between <code class="literal">sent_lsn</code> and
+ <code class="function">pg_last_wal_receive_lsn</code> on the standby might indicate
+ network delay, or that the standby is under heavy load.
+ </p><p>
+ On a hot standby, the status of the WAL receiver process can be retrieved
+ via the <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-WAL-RECEIVER-VIEW" title="28.2.6. pg_stat_wal_receiver">
+ <code class="structname">pg_stat_wal_receiver</code></a> view. A large
+ difference between <code class="function">pg_last_wal_replay_lsn</code> and the
+ view's <code class="literal">flushed_lsn</code> indicates that WAL is being
+ received faster than it can be replayed.
+ </p></div></div><div class="sect2" id="STREAMING-REPLICATION-SLOTS"><div class="titlepage"><div><div><h3 class="title">27.2.6. Replication Slots</h3></div></div></div><a id="id-1.6.14.16.18.2" class="indexterm"></a><p>
+ Replication slots provide an automated way to ensure that the primary does
+ not remove WAL segments until they have been received by all standbys,
+ and that the primary does not remove rows which could cause a
+ <a class="link" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="27.4.2. Handling Query Conflicts">recovery conflict</a> even when the
+ standby is disconnected.
+ </p><p>
+ In lieu of using replication slots, it is possible to prevent the removal
+ of old WAL segments using <a class="xref" href="runtime-config-replication.html#GUC-WAL-KEEP-SIZE">wal_keep_size</a>, or by
+ storing the segments in an archive using
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a>.
+ 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. On the other hand, replication slots can retain so
+ many WAL segments that they fill up the space allocated
+ for <code class="literal">pg_wal</code>;
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE">max_slot_wal_keep_size</a> limits the size of WAL files
+ retained by replication slots.
+ </p><p>
+ Similarly, <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY-FEEDBACK">hot_standby_feedback</a>
+ and <a class="xref" href="runtime-config-replication.html#GUC-VACUUM-DEFER-CLEANUP-AGE">vacuum_defer_cleanup_age</a> 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
+ protection. Replication slots overcome these disadvantages.
+ </p><div class="sect3" id="STREAMING-REPLICATION-SLOTS-MANIPULATION"><div class="titlepage"><div><div><h4 class="title">27.2.6.1. Querying and Manipulating Replication Slots</h4></div></div></div><p>
+ Each replication slot has a name, which can contain lower-case letters,
+ numbers, and the underscore character.
+ </p><p>
+ Existing replication slots and their state can be seen in the
+ <a class="link" href="view-pg-replication-slots.html" title="54.19. pg_replication_slots"><code class="structname">pg_replication_slots</code></a>
+ view.
+ </p><p>
+ Slots can be created and dropped either via the streaming replication
+ protocol (see <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>) or via SQL
+ functions (see <a class="xref" href="functions-admin.html#FUNCTIONS-REPLICATION" title="9.27.6. Replication Management Functions">Section 9.27.6</a>).
+ </p></div><div class="sect3" id="STREAMING-REPLICATION-SLOTS-CONFIG"><div class="titlepage"><div><div><h4 class="title">27.2.6.2. Configuration Example</h4></div></div></div><p>
+ You can create a replication slot like this:
+</p><pre class="programlisting">
+postgres=# SELECT * FROM pg_create_physical_replication_slot('node_a_slot');
+ slot_name | lsn
+-------------+-----
+ node_a_slot |
+
+postgres=# SELECT slot_name, slot_type, active FROM pg_replication_slots;
+ slot_name | slot_type | active
+-------------+-----------+--------
+ node_a_slot | physical | f
+(1 row)
+</pre><p>
+ To configure the standby to use this slot, <code class="varname">primary_slot_name</code>
+ should be configured on the standby. Here is a simple example:
+</p><pre class="programlisting">
+primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
+primary_slot_name = 'node_a_slot'
+</pre><p>
+ </p></div></div><div class="sect2" id="CASCADING-REPLICATION"><div class="titlepage"><div><div><h3 class="title">27.2.7. Cascading Replication</h3></div></div></div><a id="id-1.6.14.16.19.2" class="indexterm"></a><p>
+ The cascading replication feature allows a standby server to accept replication
+ connections and stream WAL records to other standbys, acting as a relay.
+ This can be used to reduce the number of direct connections to the primary
+ and also to minimize inter-site bandwidth overheads.
+ </p><p>
+ A standby acting as both a receiver and a sender is known as a cascading
+ standby. Standbys that are more directly connected to the primary are known
+ as upstream servers, while those standby servers further away are downstream
+ servers. Cascading replication does not place limits on the number or
+ arrangement of downstream servers, though each standby connects to only
+ one upstream server which eventually links to a single primary server.
+ </p><p>
+ A cascading standby sends not only WAL records received from the
+ primary but also those restored from the archive. So even if the replication
+ connection in some upstream connection is terminated, streaming replication
+ continues downstream for as long as new WAL records are available.
+ </p><p>
+ Cascading replication is currently asynchronous. Synchronous replication
+ (see <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="27.2.8. Synchronous Replication">Section 27.2.8</a>) settings have no effect on
+ cascading replication at present.
+ </p><p>
+ Hot standby feedback propagates upstream, whatever the cascaded arrangement.
+ </p><p>
+ If an upstream standby server is promoted to become the new primary, downstream
+ servers will continue to stream from the new primary if
+ <code class="varname">recovery_target_timeline</code> is set to <code class="literal">'latest'</code> (the default).
+ </p><p>
+ To use cascading replication, set up the cascading standby so that it can
+ accept replication connections (that is, set
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> and <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a>,
+ and configure
+ <a class="link" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">host-based authentication</a>).
+ You will also need to set <code class="varname">primary_conninfo</code> in the downstream
+ standby to point to the cascading standby.
+ </p></div><div class="sect2" id="SYNCHRONOUS-REPLICATION"><div class="titlepage"><div><div><h3 class="title">27.2.8. Synchronous Replication</h3></div></div></div><a id="id-1.6.14.16.20.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> streaming replication is asynchronous by
+ default. If the primary server
+ crashes then some transactions that were committed may not have been
+ replicated to the standby server, causing data loss. The amount
+ of data loss is proportional to the replication delay at the time of
+ failover.
+ </p><p>
+ Synchronous replication offers the ability to confirm that all changes
+ made by a transaction have been transferred to one or more synchronous
+ standby servers. This extends that standard level of durability
+ offered by a transaction commit. This level of protection is referred
+ to as 2-safe replication in computer science theory, and group-1-safe
+ (group-safe and 1-safe) when <code class="varname">synchronous_commit</code> is set to
+ <code class="literal">remote_write</code>.
+ </p><p>
+ When requesting synchronous replication, each commit of a
+ write transaction will wait until confirmation is
+ received that the commit has been written to the write-ahead log on disk
+ of both the primary and standby server. The only possibility that data
+ can be lost is if both the primary and the standby suffer crashes at the
+ same time. This can provide a much higher level of durability, though only
+ if the sysadmin is cautious about the placement and management of the two
+ servers. Waiting for confirmation increases the user's confidence that the
+ changes will not be lost in the event of server crashes but it also
+ necessarily increases the response time for the requesting transaction.
+ The minimum wait time is the round-trip time between primary and standby.
+ </p><p>
+ Read-only transactions and transaction rollbacks need not wait for
+ replies from standby servers. Subtransaction commits do not wait for
+ responses from standby servers, only top-level commits. Long
+ running actions such as data loading or index building do not wait
+ until the very final commit message. All two-phase commit actions
+ require commit waits, including both prepare and commit.
+ </p><p>
+ A synchronous standby can be a physical replication standby or a logical
+ replication subscriber. It can also be any other physical or logical WAL
+ replication stream consumer that knows how to send the appropriate
+ feedback messages. Besides the built-in physical and logical replication
+ systems, this includes special programs such
+ as <code class="command">pg_receivewal</code> and <code class="command">pg_recvlogical</code>
+ as well as some third-party replication systems and custom programs.
+ Check the respective documentation for details on synchronous replication
+ support.
+ </p><div class="sect3" id="SYNCHRONOUS-REPLICATION-CONFIG"><div class="titlepage"><div><div><h4 class="title">27.2.8.1. Basic Configuration</h4></div></div></div><p>
+ Once streaming replication has been configured, configuring synchronous
+ replication requires only one additional configuration step:
+ <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a> must be set to
+ a non-empty value. <code class="varname">synchronous_commit</code> must also be set to
+ <code class="literal">on</code>, but since this is the default value, typically no change is
+ required. (See <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS" title="20.5.1. Settings">Section 20.5.1</a> and
+ <a class="xref" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY" title="20.6.2. Primary Server">Section 20.6.2</a>.)
+ This configuration will cause each commit to wait for
+ confirmation that the standby has written the commit record to durable
+ storage.
+ <code class="varname">synchronous_commit</code> can be set by individual
+ users, so it can be configured in the configuration file, for particular
+ users or databases, or dynamically by applications, in order to control
+ the durability guarantee on a per-transaction basis.
+ </p><p>
+ After a commit record has been written to disk on the primary, the
+ WAL record is then sent to the standby. The standby sends reply
+ messages each time a new batch of WAL data is written to disk, unless
+ <code class="varname">wal_receiver_status_interval</code> is set to zero on the standby.
+ In the case that <code class="varname">synchronous_commit</code> is set to
+ <code class="literal">remote_apply</code>, the standby sends reply messages when the commit
+ record is replayed, making the transaction visible.
+ If the standby is chosen as a synchronous standby, according to the setting
+ of <code class="varname">synchronous_standby_names</code> on the primary, the reply
+ messages from that standby will be considered along with those from other
+ synchronous standbys to decide when to release transactions waiting for
+ confirmation that the commit record has been received. These parameters
+ allow the administrator to specify which standby servers should be
+ synchronous standbys. Note that the configuration of synchronous
+ replication is mainly on the primary. Named standbys must be directly
+ connected to the primary; the primary knows nothing about downstream
+ standby servers using cascaded replication.
+ </p><p>
+ Setting <code class="varname">synchronous_commit</code> to <code class="literal">remote_write</code> will
+ cause each commit to wait for confirmation that the standby has received
+ the commit record and written it out to its own operating system, but not
+ for the data to be flushed to disk on the standby. This
+ setting provides a weaker guarantee of durability than <code class="literal">on</code>
+ does: the standby could lose the data in the event of an operating system
+ crash, though not a <span class="productname">PostgreSQL</span> crash.
+ However, it's a useful setting in practice
+ because it can decrease the response time for the transaction.
+ Data loss could only occur if both the primary and the standby crash and
+ the database of the primary gets corrupted at the same time.
+ </p><p>
+ Setting <code class="varname">synchronous_commit</code> to <code class="literal">remote_apply</code> will
+ cause each commit to wait until the current synchronous standbys report
+ that they have replayed the transaction, making it visible to user
+ queries. In simple cases, this allows for load balancing with causal
+ consistency.
+ </p><p>
+ Users will stop waiting if a fast shutdown is requested. However, as
+ when using asynchronous replication, the server will not fully
+ shutdown until all outstanding WAL records are transferred to the currently
+ connected standby servers.
+ </p></div><div class="sect3" id="SYNCHRONOUS-REPLICATION-MULTIPLE-STANDBYS"><div class="titlepage"><div><div><h4 class="title">27.2.8.2. Multiple Synchronous Standbys</h4></div></div></div><p>
+ Synchronous replication supports one or more synchronous standby servers;
+ transactions will wait until all the standby servers which are considered
+ as synchronous confirm receipt of their data. The number of synchronous
+ standbys that transactions must wait for replies from is specified in
+ <code class="varname">synchronous_standby_names</code>. This parameter also specifies
+ a list of standby names and the method (<code class="literal">FIRST</code> and
+ <code class="literal">ANY</code>) to choose synchronous standbys from the listed ones.
+ </p><p>
+ The method <code class="literal">FIRST</code> specifies a priority-based synchronous
+ replication and makes transaction commits wait until their WAL records are
+ replicated to the requested number of synchronous standbys chosen based on
+ their priorities. The standbys whose names appear earlier in the list are
+ given higher priority and will be considered as synchronous. Other standby
+ servers appearing later in this list represent potential synchronous
+ standbys. If any of the current synchronous standbys disconnects for
+ whatever reason, it will be replaced immediately with the
+ next-highest-priority standby.
+ </p><p>
+ An example of <code class="varname">synchronous_standby_names</code> for
+ a priority-based multiple synchronous standbys is:
+</p><pre class="programlisting">
+synchronous_standby_names = 'FIRST 2 (s1, s2, s3)'
+</pre><p>
+ In this example, if four standby servers <code class="literal">s1</code>, <code class="literal">s2</code>,
+ <code class="literal">s3</code> and <code class="literal">s4</code> are running, the two standbys
+ <code class="literal">s1</code> and <code class="literal">s2</code> will be chosen as synchronous standbys
+ because their names appear early in the list of standby names.
+ <code class="literal">s3</code> is a potential synchronous standby and will take over
+ the role of synchronous standby when either of <code class="literal">s1</code> or
+ <code class="literal">s2</code> fails. <code class="literal">s4</code> is an asynchronous standby since
+ its name is not in the list.
+ </p><p>
+ The method <code class="literal">ANY</code> specifies a quorum-based synchronous
+ replication and makes transaction commits wait until their WAL records
+ are replicated to <span class="emphasis"><em>at least</em></span> the requested number of
+ synchronous standbys in the list.
+ </p><p>
+ An example of <code class="varname">synchronous_standby_names</code> for
+ a quorum-based multiple synchronous standbys is:
+</p><pre class="programlisting">
+synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
+</pre><p>
+ In this example, if four standby servers <code class="literal">s1</code>, <code class="literal">s2</code>,
+ <code class="literal">s3</code> and <code class="literal">s4</code> are running, transaction commits will
+ wait for replies from at least any two standbys of <code class="literal">s1</code>,
+ <code class="literal">s2</code> and <code class="literal">s3</code>. <code class="literal">s4</code> is an asynchronous
+ standby since its name is not in the list.
+ </p><p>
+ The synchronous states of standby servers can be viewed using
+ the <code class="structname">pg_stat_replication</code> view.
+ </p></div><div class="sect3" id="SYNCHRONOUS-REPLICATION-PERFORMANCE"><div class="titlepage"><div><div><h4 class="title">27.2.8.3. Planning for Performance</h4></div></div></div><p>
+ Synchronous replication usually requires carefully planned and placed
+ standby servers to ensure applications perform acceptably. Waiting
+ doesn't utilize system resources, but transaction locks continue to be
+ held until the transfer is confirmed. As a result, incautious use of
+ synchronous replication will reduce performance for database
+ applications because of increased response times and higher contention.
+ </p><p>
+ <span class="productname">PostgreSQL</span> allows the application developer
+ to specify the durability level required via replication. This can be
+ specified for the system overall, though it can also be specified for
+ specific users or connections, or even individual transactions.
+ </p><p>
+ For example, an application workload might consist of:
+ 10% of changes are important customer details, while
+ 90% of changes are less important data that the business can more
+ easily survive if it is lost, such as chat messages between users.
+ </p><p>
+ With synchronous replication options specified at the application level
+ (on the primary) we can offer synchronous replication for the most
+ important changes, without slowing down the bulk of the total workload.
+ Application level options are an important and practical tool for allowing
+ the benefits of synchronous replication for high performance applications.
+ </p><p>
+ You should consider that the network bandwidth must be higher than
+ the rate of generation of WAL data.
+ </p></div><div class="sect3" id="SYNCHRONOUS-REPLICATION-HA"><div class="titlepage"><div><div><h4 class="title">27.2.8.4. Planning for High Availability</h4></div></div></div><p>
+ <code class="varname">synchronous_standby_names</code> specifies the number and
+ names of synchronous standbys that transaction commits made when
+ <code class="varname">synchronous_commit</code> is set to <code class="literal">on</code>,
+ <code class="literal">remote_apply</code> or <code class="literal">remote_write</code> will wait for
+ responses from. Such transaction commits may never be completed
+ if any one of synchronous standbys should crash.
+ </p><p>
+ The best solution for high availability is to ensure you keep as many
+ synchronous standbys as requested. This can be achieved by naming multiple
+ potential synchronous standbys using <code class="varname">synchronous_standby_names</code>.
+ </p><p>
+ In a priority-based synchronous replication, the standbys whose names
+ appear earlier in the list will be used as synchronous standbys.
+ Standbys listed after these will take over the role of synchronous standby
+ if one of current ones should fail.
+ </p><p>
+ In a quorum-based synchronous replication, all the standbys appearing
+ in the list will be used as candidates for synchronous standbys.
+ Even if one of them should fail, the other standbys will keep performing
+ the role of candidates of synchronous standby.
+ </p><p>
+ When a standby first attaches to the primary, it will not yet be properly
+ synchronized. This is described as <code class="literal">catchup</code> mode. Once
+ the lag between standby and primary reaches zero for the first time
+ we move to real-time <code class="literal">streaming</code> state.
+ The catch-up duration may be long immediately after the standby has
+ been created. If the standby is shut down, then the catch-up period
+ will increase according to the length of time the standby has been down.
+ The standby is only able to become a synchronous standby
+ once it has reached <code class="literal">streaming</code> state.
+ This state can be viewed using
+ the <code class="structname">pg_stat_replication</code> view.
+ </p><p>
+ If primary restarts while commits are waiting for acknowledgment, those
+ waiting transactions will be marked fully committed once the primary
+ database recovers.
+ There is no way to be certain that all standbys have received all
+ outstanding WAL data at time of the crash of the primary. Some
+ transactions may not show as committed on the standby, even though
+ they show as committed on the primary. The guarantee we offer is that
+ the application will not receive explicit acknowledgment of the
+ successful commit of a transaction until the WAL data is known to be
+ safely received by all the synchronous standbys.
+ </p><p>
+ If you really cannot keep as many synchronous standbys as requested
+ then you should decrease the number of synchronous standbys that
+ transaction commits must wait for responses from
+ in <code class="varname">synchronous_standby_names</code> (or disable it) and
+ reload the configuration file on the primary server.
+ </p><p>
+ If the primary is isolated from remaining standby servers you should
+ fail over to the best candidate of those other remaining standby servers.
+ </p><p>
+ If you need to re-create a standby server while transactions are
+ waiting, make sure that the commands pg_backup_start() and
+ pg_backup_stop() are run in a session with
+ <code class="varname">synchronous_commit</code> = <code class="literal">off</code>, otherwise those
+ requests will wait forever for the standby to appear.
+ </p></div></div><div class="sect2" id="CONTINUOUS-ARCHIVING-IN-STANDBY"><div class="titlepage"><div><div><h3 class="title">27.2.9. Continuous Archiving in Standby</h3></div></div></div><a id="id-1.6.14.16.21.2" class="indexterm"></a><p>
+ When continuous WAL archiving is used in a standby, there are two
+ different scenarios: the WAL archive can be shared between the primary
+ and the standby, or the standby can have its own WAL archive. When
+ the standby has its own WAL archive, set <code class="varname">archive_mode</code>
+ to <code class="literal">always</code>, and the standby will call the archive
+ command for every WAL segment it receives, whether it's by restoring
+ from the archive or by streaming replication. The shared archive can
+ be handled similarly, but the <code class="varname">archive_command</code> or <code class="varname">archive_library</code> must
+ test if the file being archived exists already, and if the existing file
+ has identical contents. This requires more care in the
+ <code class="varname">archive_command</code> or <code class="varname">archive_library</code>, as it must
+ be careful to not overwrite an existing file with different contents,
+ but return success if the exactly same file is archived twice. And
+ all that must be done free of race conditions, if two servers attempt
+ to archive the same file at the same time.
+ </p><p>
+ If <code class="varname">archive_mode</code> is set to <code class="literal">on</code>, the
+ archiver is not enabled during recovery or standby mode. If the standby
+ server is promoted, it will start archiving after the promotion, but
+ will not archive any WAL or timeline history files that
+ it did not generate itself. To get a complete
+ series of WAL files in the archive, you must ensure that all WAL is
+ archived, before it reaches the standby. This is inherently true with
+ file-based log shipping, as the standby can only restore files that
+ are found in the archive, but not if streaming replication is enabled.
+ When a server is not in recovery mode, there is no difference between
+ <code class="literal">on</code> and <code class="literal">always</code> modes.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="different-replication-solutions.html" title="27.1. Comparison of Different Solutions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="high-availability.html" title="Chapter 27. High Availability, Load Balancing, and Replication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="warm-standby-failover.html" title="27.3. Failover">Next</a></td></tr><tr><td width="40%" align="left" valign="top">27.1. Comparison of Different Solutions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 27.3. Failover</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/when-can-parallel-query-be-used.html b/doc/src/sgml/html/when-can-parallel-query-be-used.html
new file mode 100644
index 0000000..89e20b2
--- /dev/null
+++ b/doc/src/sgml/html/when-can-parallel-query-be-used.html
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.2. When Can Parallel Query Be Used?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works" /><link rel="next" href="parallel-plans.html" title="15.3. Parallel Plans" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.2. When Can Parallel Query Be Used?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parallel-plans.html" title="15.3. Parallel Plans">Next</a></td></tr></table><hr /></div><div class="sect1" id="WHEN-CAN-PARALLEL-QUERY-BE-USED"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.2. When Can Parallel Query Be Used?</h2></div></div></div><p>
+ There are several settings that can cause the query planner not to
+ generate a parallel query plan under any circumstances. In order for
+ any parallel query plans whatsoever to be generated, the following
+ settings must be configured as indicated.
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> must be set to a
+ value that is greater than zero. This is a special case of the more
+ general principle that no more workers should be used than the number
+ configured via <code class="varname">max_parallel_workers_per_gather</code>.
+ </p></li></ul></div><p>
+ In addition, the system must not be running in single-user mode. Since
+ the entire database system is running as a single process in this situation,
+ no background workers will be available.
+ </p><p>
+ Even when it is in general possible for parallel query plans to be
+ generated, the planner will not generate them for a given query
+ if any of the following are true:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The query writes any data or locks any database rows. If a query
+ contains a data-modifying operation either at the top level or within
+ a CTE, no parallel plans for that query will be generated. As an
+ exception, the following commands, which create a new table and populate
+ it, can use a parallel plan for the underlying <code class="literal">SELECT</code>
+ part of the query:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="command">CREATE TABLE ... AS</code></p></li><li class="listitem"><p><code class="command">SELECT INTO</code></p></li><li class="listitem"><p><code class="command">CREATE MATERIALIZED VIEW</code></p></li><li class="listitem"><p><code class="command">REFRESH MATERIALIZED VIEW</code></p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ The query might be suspended during execution. In any situation in
+ which the system thinks that partial or incremental execution might
+ occur, no parallel plan is generated. For example, a cursor created
+ using <a class="link" href="sql-declare.html" title="DECLARE">DECLARE CURSOR</a> will never use
+ a parallel plan. Similarly, a PL/pgSQL loop of the form
+ <code class="literal">FOR x IN query LOOP .. END LOOP</code> will never use a
+ parallel plan, because the parallel query system is unable to verify
+ that the code in the loop is safe to execute while parallel query is
+ active.
+ </p></li><li class="listitem"><p>
+ The query uses any function marked <code class="literal">PARALLEL UNSAFE</code>.
+ Most system-defined functions are <code class="literal">PARALLEL SAFE</code>,
+ but user-defined functions are marked <code class="literal">PARALLEL
+ UNSAFE</code> by default. See the discussion of
+ <a class="xref" href="parallel-safety.html" title="15.4. Parallel Safety">Section 15.4</a>.
+ </p></li><li class="listitem"><p>
+ The query is running inside of another query that is already parallel.
+ For example, if a function called by a parallel query issues an SQL
+ query itself, that query will never use a parallel plan. This is a
+ limitation of the current implementation, but it may not be desirable
+ to remove this limitation, since it could result in a single query
+ using a very large number of processes.
+ </p></li></ul></div><p>
+ Even when parallel query plan is generated for a particular query, there
+ are several circumstances under which it will be impossible to execute
+ that plan in parallel at execution time. If this occurs, the leader
+ will execute the portion of the plan below the <code class="literal">Gather</code>
+ node entirely by itself, almost as if the <code class="literal">Gather</code> node were
+ not present. This will happen if any of the following conditions are met:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ No background workers can be obtained because of the limitation that
+ the total number of background workers cannot exceed
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>.
+ </p></li><li class="listitem"><p>
+ No background workers can be obtained because of the limitation that
+ the total number of background workers launched for purposes of
+ parallel query cannot exceed <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>.
+ </p></li><li class="listitem"><p>
+ The client sends an Execute message with a non-zero fetch count.
+ See the discussion of the
+ <a class="link" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="55.2.3. Extended Query">extended query protocol</a>.
+ Since <a class="link" href="libpq.html" title="Chapter 34. libpq — C Library">libpq</a> currently provides no way to
+ send such a message, this can only occur when using a client that
+ does not rely on libpq. If this is a frequent
+ occurrence, it may be a good idea to set
+ <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> to zero in
+ sessions where it is likely, so as to avoid generating query plans
+ that may be suboptimal when run serially.
+ </p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel-plans.html" title="15.3. Parallel Plans">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.1. How Parallel Query Works </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 15.3. Parallel Plans</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xaggr.html b/doc/src/sgml/html/xaggr.html
new file mode 100644
index 0000000..a1d582e
--- /dev/null
+++ b/doc/src/sgml/html/xaggr.html
@@ -0,0 +1,528 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.12. User-Defined Aggregates</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-optimization.html" title="38.11. Function Optimization Information" /><link rel="next" href="xtypes.html" title="38.13. User-Defined Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.12. User-Defined Aggregates</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xtypes.html" title="38.13. User-Defined Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="XAGGR"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.12. User-Defined Aggregates</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xaggr.html#XAGGR-MOVING-AGGREGATES">38.12.1. Moving-Aggregate Mode</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-POLYMORPHIC-AGGREGATES">38.12.2. Polymorphic and Variadic Aggregates</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-ORDERED-SET-AGGREGATES">38.12.3. Ordered-Set Aggregates</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-PARTIAL-AGGREGATES">38.12.4. Partial Aggregation</a></span></dt><dt><span class="sect2"><a href="xaggr.html#XAGGR-SUPPORT-FUNCTIONS">38.12.5. Support Functions for Aggregates</a></span></dt></dl></div><a id="id-1.8.3.15.2" class="indexterm"></a><p>
+ Aggregate functions in <span class="productname">PostgreSQL</span>
+ are defined in terms of <em class="firstterm">state values</em>
+ and <em class="firstterm">state transition functions</em>.
+ That is, an aggregate operates using a state value that is updated
+ as each successive input row is processed.
+ To define a new aggregate
+ function, one selects a data type for the state value,
+ an initial value for the state, and a state transition
+ function. The state transition function takes the previous state
+ value and the aggregate's input value(s) for the current row, and
+ returns a new state value.
+ A <em class="firstterm">final function</em>
+ can also be specified, in case the desired result of the aggregate
+ is different from the data that needs to be kept in the running
+ state value. The final function takes the ending state value
+ and returns whatever is wanted as the aggregate result.
+ In principle, the transition and final functions are just ordinary
+ functions that could also be used outside the context of the
+ aggregate. (In practice, it's often helpful for performance reasons
+ to create specialized transition functions that can only work when
+ called as part of an aggregate.)
+ </p><p>
+ Thus, in addition to the argument and result data types seen by a user
+ of the aggregate, there is an internal state-value data type that
+ might be different from both the argument and result types.
+ </p><p>
+ If we define an aggregate that does not use a final function,
+ we have an aggregate that computes a running function of
+ the column values from each row. <code class="function">sum</code> is an
+ example of this kind of aggregate. <code class="function">sum</code> starts at
+ zero and always adds the current row's value to
+ its running total. For example, if we want to make a <code class="function">sum</code>
+ aggregate to work on a data type for complex numbers,
+ we only need the addition function for that data type.
+ The aggregate definition would be:
+
+</p><pre class="programlisting">
+CREATE AGGREGATE sum (complex)
+(
+ sfunc = complex_add,
+ stype = complex,
+ initcond = '(0,0)'
+);
+</pre><p>
+
+ which we might use like this:
+
+</p><pre class="programlisting">
+SELECT sum(a) FROM test_complex;
+
+ sum
+-----------
+ (34,53.9)
+</pre><p>
+
+ (Notice that we are relying on function overloading: there is more than
+ one aggregate named <code class="function">sum</code>, but
+ <span class="productname">PostgreSQL</span> can figure out which kind
+ of sum applies to a column of type <code class="type">complex</code>.)
+ </p><p>
+ The above definition of <code class="function">sum</code> will return zero
+ (the initial state value) if there are no nonnull input values.
+ Perhaps we want to return null in that case instead — the SQL standard
+ expects <code class="function">sum</code> to behave that way. We can do this simply by
+ omitting the <code class="literal">initcond</code> phrase, so that the initial state
+ value is null. Ordinarily this would mean that the <code class="literal">sfunc</code>
+ would need to check for a null state-value input. But for
+ <code class="function">sum</code> and some other simple aggregates like
+ <code class="function">max</code> and <code class="function">min</code>,
+ it is sufficient to insert the first nonnull input value into
+ the state variable and then start applying the transition function
+ at the second nonnull input value. <span class="productname">PostgreSQL</span>
+ will do that automatically if the initial state value is null and
+ the transition function is marked <span class="quote">“<span class="quote">strict</span>”</span> (i.e., not to be called
+ for null inputs).
+ </p><p>
+ Another bit of default behavior for a <span class="quote">“<span class="quote">strict</span>”</span> transition function
+ is that the previous state value is retained unchanged whenever a
+ null input value is encountered. Thus, null values are ignored. If you
+ need some other behavior for null inputs, do not declare your
+ transition function as strict; instead code it to test for null inputs and
+ do whatever is needed.
+ </p><p>
+ <code class="function">avg</code> (average) is a more complex example of an aggregate.
+ It requires
+ two pieces of running state: the sum of the inputs and the count
+ of the number of inputs. The final result is obtained by dividing
+ these quantities. Average is typically implemented by using an
+ array as the state value. For example,
+ the built-in implementation of <code class="function">avg(float8)</code>
+ looks like:
+
+</p><pre class="programlisting">
+CREATE AGGREGATE avg (float8)
+(
+ sfunc = float8_accum,
+ stype = float8[],
+ finalfunc = float8_avg,
+ initcond = '{0,0,0}'
+);
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">float8_accum</code> requires a three-element array, not just
+ two elements, because it accumulates the sum of squares as well as
+ the sum and count of the inputs. This is so that it can be used for
+ some other aggregates as well as <code class="function">avg</code>.
+ </p></div><p>
+ Aggregate function calls in SQL allow <code class="literal">DISTINCT</code>
+ and <code class="literal">ORDER BY</code> options that control which rows are fed
+ to the aggregate's transition function and in what order. These
+ options are implemented behind the scenes and are not the concern
+ of the aggregate's support functions.
+ </p><p>
+ For further details see the
+ <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a>
+ command.
+ </p><div class="sect2" id="XAGGR-MOVING-AGGREGATES"><div class="titlepage"><div><div><h3 class="title">38.12.1. Moving-Aggregate Mode</h3></div></div></div><a id="id-1.8.3.15.12.2" class="indexterm"></a><a id="id-1.8.3.15.12.3" class="indexterm"></a><p>
+ Aggregate functions can optionally support <em class="firstterm">moving-aggregate
+ mode</em>, which allows substantially faster execution of aggregate
+ functions within windows with moving frame starting points.
+ (See <a class="xref" href="tutorial-window.html" title="3.5. Window Functions">Section 3.5</a>
+ and <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a> for information about use of
+ aggregate functions as window functions.)
+ The basic idea is that in addition to a normal <span class="quote">“<span class="quote">forward</span>”</span>
+ transition function, the aggregate provides an <em class="firstterm">inverse
+ transition function</em>, which allows rows to be removed from the
+ aggregate's running state value when they exit the window frame.
+ For example a <code class="function">sum</code> aggregate, which uses addition as the
+ forward transition function, would use subtraction as the inverse
+ transition function. Without an inverse transition function, the window
+ function mechanism must recalculate the aggregate from scratch each time
+ the frame starting point moves, resulting in run time proportional to the
+ number of input rows times the average frame length. With an inverse
+ transition function, the run time is only proportional to the number of
+ input rows.
+ </p><p>
+ The inverse transition function is passed the current state value and the
+ aggregate input value(s) for the earliest row included in the current
+ state. It must reconstruct what the state value would have been if the
+ given input row had never been aggregated, but only the rows following
+ it. This sometimes requires that the forward transition function keep
+ more state than is needed for plain aggregation mode. Therefore, the
+ moving-aggregate mode uses a completely separate implementation from the
+ plain mode: it has its own state data type, its own forward transition
+ function, and its own final function if needed. These can be the same as
+ the plain mode's data type and functions, if there is no need for extra
+ state.
+ </p><p>
+ As an example, we could extend the <code class="function">sum</code> aggregate given above
+ to support moving-aggregate mode like this:
+
+</p><pre class="programlisting">
+CREATE AGGREGATE sum (complex)
+(
+ sfunc = complex_add,
+ stype = complex,
+ initcond = '(0,0)',
+ msfunc = complex_add,
+ minvfunc = complex_sub,
+ mstype = complex,
+ minitcond = '(0,0)'
+);
+</pre><p>
+
+ The parameters whose names begin with <code class="literal">m</code> define the
+ moving-aggregate implementation. Except for the inverse transition
+ function <code class="literal">minvfunc</code>, they correspond to the plain-aggregate
+ parameters without <code class="literal">m</code>.
+ </p><p>
+ The forward transition function for moving-aggregate mode is not allowed
+ to return null as the new state value. If the inverse transition
+ function returns null, this is taken as an indication that the inverse
+ function cannot reverse the state calculation for this particular input,
+ and so the aggregate calculation will be redone from scratch for the
+ current frame starting position. This convention allows moving-aggregate
+ mode to be used in situations where there are some infrequent cases that
+ are impractical to reverse out of the running state value. The inverse
+ transition function can <span class="quote">“<span class="quote">punt</span>”</span> on these cases, and yet still come
+ out ahead so long as it can work for most cases. As an example, an
+ aggregate working with floating-point numbers might choose to punt when
+ a <code class="literal">NaN</code> (not a number) input has to be removed from the running
+ state value.
+ </p><p>
+ When writing moving-aggregate support functions, it is important to be
+ sure that the inverse transition function can reconstruct the correct
+ state value exactly. Otherwise there might be user-visible differences
+ in results depending on whether the moving-aggregate mode is used.
+ An example of an aggregate for which adding an inverse transition
+ function seems easy at first, yet where this requirement cannot be met
+ is <code class="function">sum</code> over <code class="type">float4</code> or <code class="type">float8</code> inputs. A
+ naive declaration of <code class="function">sum(<code class="type">float8</code>)</code> could be
+
+</p><pre class="programlisting">
+CREATE AGGREGATE unsafe_sum (float8)
+(
+ stype = float8,
+ sfunc = float8pl,
+ mstype = float8,
+ msfunc = float8pl,
+ minvfunc = float8mi
+);
+</pre><p>
+
+ This aggregate, however, can give wildly different results than it would
+ have without the inverse transition function. For example, consider
+
+</p><pre class="programlisting">
+SELECT
+ unsafe_sum(x) OVER (ORDER BY n ROWS BETWEEN CURRENT ROW AND 1 FOLLOWING)
+FROM (VALUES (1, 1.0e20::float8),
+ (2, 1.0::float8)) AS v (n,x);
+</pre><p>
+
+ This query returns <code class="literal">0</code> as its second result, rather than the
+ expected answer of <code class="literal">1</code>. The cause is the limited precision of
+ floating-point values: adding <code class="literal">1</code> to <code class="literal">1e20</code> results
+ in <code class="literal">1e20</code> again, and so subtracting <code class="literal">1e20</code> from that
+ yields <code class="literal">0</code>, not <code class="literal">1</code>. Note that this is a limitation
+ of floating-point arithmetic in general, not a limitation
+ of <span class="productname">PostgreSQL</span>.
+ </p></div><div class="sect2" id="XAGGR-POLYMORPHIC-AGGREGATES"><div class="titlepage"><div><div><h3 class="title">38.12.2. Polymorphic and Variadic Aggregates</h3></div></div></div><a id="id-1.8.3.15.13.2" class="indexterm"></a><a id="id-1.8.3.15.13.3" class="indexterm"></a><p>
+ Aggregate functions can use polymorphic
+ state transition functions or final functions, so that the same functions
+ can be used to implement multiple aggregates.
+ See <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>
+ for an explanation of polymorphic functions.
+ Going a step further, the aggregate function itself can be specified
+ with polymorphic input type(s) and state type, allowing a single
+ aggregate definition to serve for multiple input data types.
+ Here is an example of a polymorphic aggregate:
+
+</p><pre class="programlisting">
+CREATE AGGREGATE array_accum (anycompatible)
+(
+ sfunc = array_append,
+ stype = anycompatiblearray,
+ initcond = '{}'
+);
+</pre><p>
+
+ Here, the actual state type for any given aggregate call is the array type
+ having the actual input type as elements. The behavior of the aggregate
+ is to concatenate all the inputs into an array of that type.
+ (Note: the built-in aggregate <code class="function">array_agg</code> provides similar
+ functionality, with better performance than this definition would have.)
+ </p><p>
+ Here's the output using two different actual data types as arguments:
+
+</p><pre class="programlisting">
+SELECT attrelid::regclass, array_accum(attname)
+ FROM pg_attribute
+ WHERE attnum &gt; 0 AND attrelid = 'pg_tablespace'::regclass
+ GROUP BY attrelid;
+
+ attrelid | array_accum
+---------------+---------------------------------------
+ pg_tablespace | {spcname,spcowner,spcacl,spcoptions}
+(1 row)
+
+SELECT attrelid::regclass, array_accum(atttypid::regtype)
+ FROM pg_attribute
+ WHERE attnum &gt; 0 AND attrelid = 'pg_tablespace'::regclass
+ GROUP BY attrelid;
+
+ attrelid | array_accum
+---------------+---------------------------
+ pg_tablespace | {name,oid,aclitem[],text[]}
+(1 row)
+</pre><p>
+ </p><p>
+ Ordinarily, an aggregate function with a polymorphic result type has a
+ polymorphic state type, as in the above example. This is necessary
+ because otherwise the final function cannot be declared sensibly: it
+ would need to have a polymorphic result type but no polymorphic argument
+ type, which <code class="command">CREATE FUNCTION</code> will reject on the grounds that
+ the result type cannot be deduced from a call. But sometimes it is
+ inconvenient to use a polymorphic state type. The most common case is
+ where the aggregate support functions are to be written in C and the
+ state type should be declared as <code class="type">internal</code> because there is
+ no SQL-level equivalent for it. To address this case, it is possible to
+ declare the final function as taking extra <span class="quote">“<span class="quote">dummy</span>”</span> arguments
+ that match the input arguments of the aggregate. Such dummy arguments
+ are always passed as null values since no specific value is available when the
+ final function is called. Their only use is to allow a polymorphic
+ final function's result type to be connected to the aggregate's input
+ type(s). For example, the definition of the built-in
+ aggregate <code class="function">array_agg</code> is equivalent to
+
+</p><pre class="programlisting">
+CREATE FUNCTION array_agg_transfn(internal, anynonarray)
+ RETURNS internal ...;
+CREATE FUNCTION array_agg_finalfn(internal, anynonarray)
+ RETURNS anyarray ...;
+
+CREATE AGGREGATE array_agg (anynonarray)
+(
+ sfunc = array_agg_transfn,
+ stype = internal,
+ finalfunc = array_agg_finalfn,
+ finalfunc_extra
+);
+</pre><p>
+
+ Here, the <code class="literal">finalfunc_extra</code> option specifies that the final
+ function receives, in addition to the state value, extra dummy
+ argument(s) corresponding to the aggregate's input argument(s).
+ The extra <code class="type">anynonarray</code> argument allows the declaration
+ of <code class="function">array_agg_finalfn</code> to be valid.
+ </p><p>
+ An aggregate function can be made to accept a varying number of arguments
+ by declaring its last argument as a <code class="literal">VARIADIC</code> array, in much
+ the same fashion as for regular functions; see
+ <a class="xref" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS" title="38.5.6. SQL Functions with Variable Numbers of Arguments">Section 38.5.6</a>. The aggregate's transition
+ function(s) must have the same array type as their last argument. The
+ transition function(s) typically would also be marked <code class="literal">VARIADIC</code>,
+ but this is not strictly required.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Variadic aggregates are easily misused in connection with
+ the <code class="literal">ORDER BY</code> option (see <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a>),
+ since the parser cannot tell whether the wrong number of actual arguments
+ have been given in such a combination. Keep in mind that everything to
+ the right of <code class="literal">ORDER BY</code> is a sort key, not an argument to the
+ aggregate. For example, in
+</p><pre class="programlisting">
+SELECT myaggregate(a ORDER BY a, b, c) FROM ...
+</pre><p>
+ the parser will see this as a single aggregate function argument and
+ three sort keys. However, the user might have intended
+</p><pre class="programlisting">
+SELECT myaggregate(a, b, c ORDER BY a) FROM ...
+</pre><p>
+ If <code class="literal">myaggregate</code> is variadic, both these calls could be
+ perfectly valid.
+ </p><p>
+ For the same reason, it's wise to think twice before creating aggregate
+ functions with the same names and different numbers of regular arguments.
+ </p></div></div><div class="sect2" id="XAGGR-ORDERED-SET-AGGREGATES"><div class="titlepage"><div><div><h3 class="title">38.12.3. Ordered-Set Aggregates</h3></div></div></div><a id="id-1.8.3.15.14.2" class="indexterm"></a><p>
+ The aggregates we have been describing so far are <span class="quote">“<span class="quote">normal</span>”</span>
+ aggregates. <span class="productname">PostgreSQL</span> also
+ supports <em class="firstterm">ordered-set aggregates</em>, which differ from
+ normal aggregates in two key ways. First, in addition to ordinary
+ aggregated arguments that are evaluated once per input row, an
+ ordered-set aggregate can have <span class="quote">“<span class="quote">direct</span>”</span> arguments that are
+ evaluated only once per aggregation operation. Second, the syntax
+ for the ordinary aggregated arguments specifies a sort ordering
+ for them explicitly. An ordered-set aggregate is usually
+ used to implement a computation that depends on a specific row
+ ordering, for instance rank or percentile, so that the sort ordering
+ is a required aspect of any call. For example, the built-in
+ definition of <code class="function">percentile_disc</code> is equivalent to:
+
+</p><pre class="programlisting">
+CREATE FUNCTION ordered_set_transition(internal, anyelement)
+ RETURNS internal ...;
+CREATE FUNCTION percentile_disc_final(internal, float8, anyelement)
+ RETURNS anyelement ...;
+
+CREATE AGGREGATE percentile_disc (float8 ORDER BY anyelement)
+(
+ sfunc = ordered_set_transition,
+ stype = internal,
+ finalfunc = percentile_disc_final,
+ finalfunc_extra
+);
+</pre><p>
+
+ This aggregate takes a <code class="type">float8</code> direct argument (the percentile
+ fraction) and an aggregated input that can be of any sortable data type.
+ It could be used to obtain a median household income like this:
+
+</p><pre class="programlisting">
+SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY income) FROM households;
+ percentile_disc
+-----------------
+ 50489
+</pre><p>
+
+ Here, <code class="literal">0.5</code> is a direct argument; it would make no sense
+ for the percentile fraction to be a value varying across rows.
+ </p><p>
+ Unlike the case for normal aggregates, the sorting of input rows for
+ an ordered-set aggregate is <span class="emphasis"><em>not</em></span> done behind the scenes,
+ but is the responsibility of the aggregate's support functions.
+ The typical implementation approach is to keep a reference to
+ a <span class="quote">“<span class="quote">tuplesort</span>”</span> object in the aggregate's state value, feed the
+ incoming rows into that object, and then complete the sorting and
+ read out the data in the final function. This design allows the
+ final function to perform special operations such as injecting
+ additional <span class="quote">“<span class="quote">hypothetical</span>”</span> rows into the data to be sorted.
+ While normal aggregates can often be implemented with support
+ functions written in <span class="application">PL/pgSQL</span> or another
+ PL language, ordered-set aggregates generally have to be written in
+ C, since their state values aren't definable as any SQL data type.
+ (In the above example, notice that the state value is declared as
+ type <code class="type">internal</code> — this is typical.)
+ Also, because the final function performs the sort, it is not possible
+ to continue adding input rows by executing the transition function again
+ later. This means the final function is not <code class="literal">READ_ONLY</code>;
+ it must be declared in <a class="link" href="sql-createaggregate.html" title="CREATE AGGREGATE"><code class="command">CREATE AGGREGATE</code></a>
+ as <code class="literal">READ_WRITE</code>, or as <code class="literal">SHAREABLE</code> if
+ it's possible for additional final-function calls to make use of the
+ already-sorted state.
+ </p><p>
+ The state transition function for an ordered-set aggregate receives
+ the current state value plus the aggregated input values for
+ each row, and returns the updated state value. This is the
+ same definition as for normal aggregates, but note that the direct
+ arguments (if any) are not provided. The final function receives
+ the last state value, the values of the direct arguments if any,
+ and (if <code class="literal">finalfunc_extra</code> is specified) null values
+ corresponding to the aggregated input(s). As with normal
+ aggregates, <code class="literal">finalfunc_extra</code> is only really useful if the
+ aggregate is polymorphic; then the extra dummy argument(s) are needed
+ to connect the final function's result type to the aggregate's input
+ type(s).
+ </p><p>
+ Currently, ordered-set aggregates cannot be used as window functions,
+ and therefore there is no need for them to support moving-aggregate mode.
+ </p></div><div class="sect2" id="XAGGR-PARTIAL-AGGREGATES"><div class="titlepage"><div><div><h3 class="title">38.12.4. Partial Aggregation</h3></div></div></div><a id="id-1.8.3.15.15.2" class="indexterm"></a><p>
+ Optionally, an aggregate function can support <em class="firstterm">partial
+ aggregation</em>. The idea of partial aggregation is to run the aggregate's
+ state transition function over different subsets of the input data
+ independently, and then to combine the state values resulting from those
+ subsets to produce the same state value that would have resulted from
+ scanning all the input in a single operation. This mode can be used for
+ parallel aggregation by having different worker processes scan different
+ portions of a table. Each worker produces a partial state value, and at
+ the end those state values are combined to produce a final state value.
+ (In the future this mode might also be used for purposes such as combining
+ aggregations over local and remote tables; but that is not implemented
+ yet.)
+ </p><p>
+ To support partial aggregation, the aggregate definition must provide
+ a <em class="firstterm">combine function</em>, which takes two values of the
+ aggregate's state type (representing the results of aggregating over two
+ subsets of the input rows) and produces a new value of the state type,
+ representing what the state would have been after aggregating over the
+ combination of those sets of rows. It is unspecified what the relative
+ order of the input rows from the two sets would have been. This means
+ that it's usually impossible to define a useful combine function for
+ aggregates that are sensitive to input row order.
+ </p><p>
+ As simple examples, <code class="literal">MAX</code> and <code class="literal">MIN</code> aggregates can be
+ made to support partial aggregation by specifying the combine function as
+ the same greater-of-two or lesser-of-two comparison function that is used
+ as their transition function. <code class="literal">SUM</code> aggregates just need an
+ addition function as combine function. (Again, this is the same as their
+ transition function, unless the state value is wider than the input data
+ type.)
+ </p><p>
+ The combine function is treated much like a transition function that
+ happens to take a value of the state type, not of the underlying input
+ type, as its second argument. In particular, the rules for dealing
+ with null values and strict functions are similar. Also, if the aggregate
+ definition specifies a non-null <code class="literal">initcond</code>, keep in mind that
+ that will be used not only as the initial state for each partial
+ aggregation run, but also as the initial state for the combine function,
+ which will be called to combine each partial result into that state.
+ </p><p>
+ If the aggregate's state type is declared as <code class="type">internal</code>, it is
+ the combine function's responsibility that its result is allocated in
+ the correct memory context for aggregate state values. This means in
+ particular that when the first input is <code class="literal">NULL</code> it's invalid
+ to simply return the second input, as that value will be in the wrong
+ context and will not have sufficient lifespan.
+ </p><p>
+ When the aggregate's state type is declared as <code class="type">internal</code>, it is
+ usually also appropriate for the aggregate definition to provide a
+ <em class="firstterm">serialization function</em> and a <em class="firstterm">deserialization
+ function</em>, which allow such a state value to be copied from one process
+ to another. Without these functions, parallel aggregation cannot be
+ performed, and future applications such as local/remote aggregation will
+ probably not work either.
+ </p><p>
+ A serialization function must take a single argument of
+ type <code class="type">internal</code> and return a result of type <code class="type">bytea</code>, which
+ represents the state value packaged up into a flat blob of bytes.
+ Conversely, a deserialization function reverses that conversion. It must
+ take two arguments of types <code class="type">bytea</code> and <code class="type">internal</code>, and
+ return a result of type <code class="type">internal</code>. (The second argument is unused
+ and is always zero, but it is required for type-safety reasons.) The
+ result of the deserialization function should simply be allocated in the
+ current memory context, as unlike the combine function's result, it is not
+ long-lived.
+ </p><p>
+ Worth noting also is that for an aggregate to be executed in parallel,
+ the aggregate itself must be marked <code class="literal">PARALLEL SAFE</code>. The
+ parallel-safety markings on its support functions are not consulted.
+ </p></div><div class="sect2" id="XAGGR-SUPPORT-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.12.5. Support Functions for Aggregates</h3></div></div></div><a id="id-1.8.3.15.16.2" class="indexterm"></a><p>
+ A function written in C can detect that it is being called as an
+ aggregate support function by calling
+ <code class="function">AggCheckCallContext</code>, for example:
+</p><pre class="programlisting">
+if (AggCheckCallContext(fcinfo, NULL))
+</pre><p>
+ One reason for checking this is that when it is true, the first input
+ must be a temporary state value and can therefore safely be modified
+ in-place rather than allocating a new copy.
+ See <code class="function">int8inc()</code> for an example.
+ (While aggregate transition functions are always allowed to modify
+ the transition value in-place, aggregate final functions are generally
+ discouraged from doing so; if they do so, the behavior must be declared
+ when creating the aggregate. See <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a>
+ for more detail.)
+ </p><p>
+ The second argument of <code class="function">AggCheckCallContext</code> can be used to
+ retrieve the memory context in which aggregate state values are being kept.
+ This is useful for transition functions that wish to use <span class="quote">“<span class="quote">expanded</span>”</span>
+ objects (see <a class="xref" href="xtypes.html#XTYPES-TOAST" title="38.13.1. TOAST Considerations">Section 38.13.1</a>) as their state values.
+ On first call, the transition function should return an expanded object
+ whose memory context is a child of the aggregate state context, and then
+ keep returning the same expanded object on subsequent calls. See
+ <code class="function">array_append()</code> for an example. (<code class="function">array_append()</code>
+ is not the transition function of any built-in aggregate, but it is written
+ to behave efficiently when used as transition function of a custom
+ aggregate.)
+ </p><p>
+ Another support routine available to aggregate functions written in C
+ is <code class="function">AggGetAggref</code>, which returns the <code class="literal">Aggref</code>
+ parse node that defines the aggregate call. This is mainly useful
+ for ordered-set aggregates, which can inspect the substructure of
+ the <code class="literal">Aggref</code> node to find out what sort ordering they are
+ supposed to implement. Examples can be found
+ in <code class="filename">orderedsetaggs.c</code> in the <span class="productname">PostgreSQL</span>
+ source code.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xtypes.html" title="38.13. User-Defined Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.11. Function Optimization Information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.13. User-Defined Types</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-c.html b/doc/src/sgml/html/xfunc-c.html
new file mode 100644
index 0000000..061c566
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-c.html
@@ -0,0 +1,1387 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.10. C-Language Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-internal.html" title="38.9. Internal Functions" /><link rel="next" href="xfunc-optimization.html" title="38.11. Function Optimization Information" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.10. C-Language Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-internal.html" title="38.9. Internal Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-C"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.10. C-Language Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-DYNLOAD">38.10.1. Dynamic Loading</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-BASETYPE">38.10.2. Base Types in C-Language Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.7">38.10.3. Version 1 Calling Conventions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.8">38.10.4. Writing Code</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#DFUNC">38.10.5. Compiling and Linking Dynamically-Loaded Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.10">38.10.6. Composite-Type Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.11">38.10.7. Returning Rows (Composite Types)</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-C-RETURN-SET">38.10.8. Returning Sets</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#id-1.8.3.13.13">38.10.9. Polymorphic Arguments and Return Types</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#XFUNC-SHARED-ADDIN">38.10.10. Shared Memory and LWLocks</a></span></dt><dt><span class="sect2"><a href="xfunc-c.html#EXTEND-CPP">38.10.11. Using C++ for Extensibility</a></span></dt></dl></div><a id="id-1.8.3.13.2" class="indexterm"></a><p>
+ User-defined functions can be written in C (or a language that can
+ be made compatible with C, such as C++). Such functions are
+ compiled into dynamically loadable objects (also called shared
+ libraries) and are loaded by the server on demand. The dynamic
+ loading feature is what distinguishes <span class="quote">“<span class="quote">C language</span>”</span> functions
+ from <span class="quote">“<span class="quote">internal</span>”</span> functions — the actual coding conventions
+ are essentially the same for both. (Hence, the standard internal
+ function library is a rich source of coding examples for user-defined
+ C functions.)
+ </p><p>
+ Currently only one calling convention is used for C functions
+ (<span class="quote">“<span class="quote">version 1</span>”</span>). Support for that calling convention is
+ indicated by writing a <code class="literal">PG_FUNCTION_INFO_V1()</code> macro
+ call for the function, as illustrated below.
+ </p><div class="sect2" id="XFUNC-C-DYNLOAD"><div class="titlepage"><div><div><h3 class="title">38.10.1. Dynamic Loading</h3></div></div></div><a id="id-1.8.3.13.5.2" class="indexterm"></a><p>
+ The first time a user-defined function in a particular
+ loadable object file is called in a session,
+ the dynamic loader loads that object file into memory so that the
+ function can be called. The <code class="command">CREATE FUNCTION</code>
+ for a user-defined C function must therefore specify two pieces of
+ information for the function: the name of the loadable
+ object file, and the C name (link symbol) of the specific function to call
+ within that object file. If the C name is not explicitly specified then
+ it is assumed to be the same as the SQL function name.
+ </p><p>
+ The following algorithm is used to locate the shared object file
+ based on the name given in the <code class="command">CREATE FUNCTION</code>
+ command:
+
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ If the name is an absolute path, the given file is loaded.
+ </p></li><li class="listitem"><p>
+ If the name starts with the string <code class="literal">$libdir</code>,
+ that part is replaced by the <span class="productname">PostgreSQL</span> package
+ library directory
+ name, which is determined at build time.<a id="id-1.8.3.13.5.4.2.2.1.3" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ If the name does not contain a directory part, the file is
+ searched for in the path specified by the configuration variable
+ <a class="xref" href="runtime-config-client.html#GUC-DYNAMIC-LIBRARY-PATH">dynamic_library_path</a>.<a id="id-1.8.3.13.5.4.2.3.1.2" class="indexterm"></a>
+ </p></li><li class="listitem"><p>
+ Otherwise (the file was not found in the path, or it contains a
+ non-absolute directory part), the dynamic loader will try to
+ take the name as given, which will most likely fail. (It is
+ unreliable to depend on the current working directory.)
+ </p></li></ol></div><p>
+
+ If this sequence does not work, the platform-specific shared
+ library file name extension (often <code class="filename">.so</code>) is
+ appended to the given name and this sequence is tried again. If
+ that fails as well, the load will fail.
+ </p><p>
+ It is recommended to locate shared libraries either relative to
+ <code class="literal">$libdir</code> or through the dynamic library path.
+ This simplifies version upgrades if the new installation is at a
+ different location. The actual directory that
+ <code class="literal">$libdir</code> stands for can be found out with the
+ command <code class="literal">pg_config --pkglibdir</code>.
+ </p><p>
+ The user ID the <span class="productname">PostgreSQL</span> server runs
+ as must be able to traverse the path to the file you intend to
+ load. Making the file or a higher-level directory not readable
+ and/or not executable by the <span class="systemitem">postgres</span>
+ user is a common mistake.
+ </p><p>
+ In any case, the file name that is given in the
+ <code class="command">CREATE FUNCTION</code> command is recorded literally
+ in the system catalogs, so if the file needs to be loaded again
+ the same procedure is applied.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> will not compile a C function
+ automatically. The object file must be compiled before it is referenced
+ in a <code class="command">CREATE
+ FUNCTION</code> command. See <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a> for additional
+ information.
+ </p></div><a id="id-1.8.3.13.5.9" class="indexterm"></a><p>
+ To ensure that a dynamically loaded object file is not loaded into an
+ incompatible server, <span class="productname">PostgreSQL</span> checks that the
+ file contains a <span class="quote">“<span class="quote">magic block</span>”</span> with the appropriate contents.
+ This allows the server to detect obvious incompatibilities, such as code
+ compiled for a different major version of
+ <span class="productname">PostgreSQL</span>. To include a magic block,
+ write this in one (and only one) of the module source files, after having
+ included the header <code class="filename">fmgr.h</code>:
+
+</p><pre class="programlisting">
+PG_MODULE_MAGIC;
+</pre><p>
+ </p><p>
+ After it is used for the first time, a dynamically loaded object
+ file is retained in memory. Future calls in the same session to
+ the function(s) in that file will only incur the small overhead of
+ a symbol table lookup. If you need to force a reload of an object
+ file, for example after recompiling it, begin a fresh session.
+ </p><a id="id-1.8.3.13.5.12" class="indexterm"></a><a id="id-1.8.3.13.5.13" class="indexterm"></a><p>
+ Optionally, a dynamically loaded file can contain an initialization
+ function. If the file includes a function named
+ <code class="function">_PG_init</code>, that function will be called immediately after
+ loading the file. The function receives no parameters and should
+ return void. There is presently no way to unload a dynamically loaded file.
+ </p></div><div class="sect2" id="XFUNC-C-BASETYPE"><div class="titlepage"><div><div><h3 class="title">38.10.2. Base Types in C-Language Functions</h3></div></div></div><a id="id-1.8.3.13.6.2" class="indexterm"></a><p>
+ To know how to write C-language functions, you need to know how
+ <span class="productname">PostgreSQL</span> internally represents base
+ data types and how they can be passed to and from functions.
+ Internally, <span class="productname">PostgreSQL</span> regards a base
+ type as a <span class="quote">“<span class="quote">blob of memory</span>”</span>. The user-defined
+ functions that you define over a type in turn define the way that
+ <span class="productname">PostgreSQL</span> can operate on it. That
+ is, <span class="productname">PostgreSQL</span> will only store and
+ retrieve the data from disk and use your user-defined functions
+ to input, process, and output the data.
+ </p><p>
+ Base types can have one of three internal formats:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ pass by value, fixed-length
+ </p></li><li class="listitem"><p>
+ pass by reference, fixed-length
+ </p></li><li class="listitem"><p>
+ pass by reference, variable-length
+ </p></li></ul></div><p>
+ </p><p>
+ By-value types can only be 1, 2, or 4 bytes in length
+ (also 8 bytes, if <code class="literal">sizeof(Datum)</code> is 8 on your machine).
+ You should be careful to define your types such that they will be the
+ same size (in bytes) on all architectures. For example, the
+ <code class="literal">long</code> type is dangerous because it is 4 bytes on some
+ machines and 8 bytes on others, whereas <code class="type">int</code> type is 4 bytes
+ on most Unix machines. A reasonable implementation of the
+ <code class="type">int4</code> type on Unix machines might be:
+
+</p><pre class="programlisting">
+/* 4-byte integer, passed by value */
+typedef int int4;
+</pre><p>
+
+ (The actual PostgreSQL C code calls this type <code class="type">int32</code>, because
+ it is a convention in C that <code class="type">int<em class="replaceable"><code>XX</code></em></code>
+ means <em class="replaceable"><code>XX</code></em> <span class="emphasis"><em>bits</em></span>. Note
+ therefore also that the C type <code class="type">int8</code> is 1 byte in size. The
+ SQL type <code class="type">int8</code> is called <code class="type">int64</code> in C. See also
+ <a class="xref" href="xfunc-c.html#XFUNC-C-TYPE-TABLE" title="Table 38.2. Equivalent C Types for Built-in SQL Types">Table 38.2</a>.)
+ </p><p>
+ On the other hand, fixed-length types of any size can
+ be passed by-reference. For example, here is a sample
+ implementation of a <span class="productname">PostgreSQL</span> type:
+
+</p><pre class="programlisting">
+/* 16-byte structure, passed by reference */
+typedef struct
+{
+ double x, y;
+} Point;
+</pre><p>
+
+ Only pointers to such types can be used when passing
+ them in and out of <span class="productname">PostgreSQL</span> functions.
+ To return a value of such a type, allocate the right amount of
+ memory with <code class="literal">palloc</code>, fill in the allocated memory,
+ and return a pointer to it. (Also, if you just want to return the
+ same value as one of your input arguments that's of the same data type,
+ you can skip the extra <code class="literal">palloc</code> and just return the
+ pointer to the input value.)
+ </p><p>
+ Finally, all variable-length types must also be passed
+ by reference. All variable-length types must begin
+ with an opaque length field of exactly 4 bytes, which will be set
+ by <code class="symbol">SET_VARSIZE</code>; never set this field directly! All data to
+ be stored within that type must be located in the memory
+ immediately following that length field. The
+ length field contains the total length of the structure,
+ that is, it includes the size of the length field
+ itself.
+ </p><p>
+ Another important point is to avoid leaving any uninitialized bits
+ within data type values; for example, take care to zero out any
+ alignment padding bytes that might be present in structs. Without
+ this, logically-equivalent constants of your data type might be
+ seen as unequal by the planner, leading to inefficient (though not
+ incorrect) plans.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ <span class="emphasis"><em>Never</em></span> modify the contents of a pass-by-reference input
+ value. If you do so you are likely to corrupt on-disk data, since
+ the pointer you are given might point directly into a disk buffer.
+ The sole exception to this rule is explained in
+ <a class="xref" href="xaggr.html" title="38.12. User-Defined Aggregates">Section 38.12</a>.
+ </p></div><p>
+ As an example, we can define the type <code class="type">text</code> as
+ follows:
+
+</p><pre class="programlisting">
+typedef struct {
+ int32 length;
+ char data[FLEXIBLE_ARRAY_MEMBER];
+} text;
+</pre><p>
+
+ The <code class="literal">[FLEXIBLE_ARRAY_MEMBER]</code> notation means that the actual
+ length of the data part is not specified by this declaration.
+ </p><p>
+ When manipulating
+ variable-length types, we must be careful to allocate
+ the correct amount of memory and set the length field correctly.
+ For example, if we wanted to store 40 bytes in a <code class="structname">text</code>
+ structure, we might use a code fragment like this:
+
+</p><pre class="programlisting">
+#include "postgres.h"
+...
+char buffer[40]; /* our source data */
+...
+text *destination = (text *) palloc(VARHDRSZ + 40);
+SET_VARSIZE(destination, VARHDRSZ + 40);
+memcpy(destination-&gt;data, buffer, 40);
+...
+
+</pre><p>
+
+ <code class="literal">VARHDRSZ</code> is the same as <code class="literal">sizeof(int32)</code>, but
+ it's considered good style to use the macro <code class="literal">VARHDRSZ</code>
+ to refer to the size of the overhead for a variable-length type.
+ Also, the length field <span class="emphasis"><em>must</em></span> be set using the
+ <code class="literal">SET_VARSIZE</code> macro, not by simple assignment.
+ </p><p>
+ <a class="xref" href="xfunc-c.html#XFUNC-C-TYPE-TABLE" title="Table 38.2. Equivalent C Types for Built-in SQL Types">Table 38.2</a> shows the C types
+ corresponding to many of the built-in SQL data types
+ of <span class="productname">PostgreSQL</span>.
+ The <span class="quote">“<span class="quote">Defined In</span>”</span> column gives the header file that
+ needs to be included to get the type definition. (The actual
+ definition might be in a different file that is included by the
+ listed file. It is recommended that users stick to the defined
+ interface.) Note that you should always include
+ <code class="filename">postgres.h</code> first in any source file of server
+ code, because it declares a number of things that you will need
+ anyway, and because including other headers first can cause
+ portability issues.
+ </p><div class="table" id="XFUNC-C-TYPE-TABLE"><p class="title"><strong>Table 38.2. Equivalent C Types for Built-in SQL Types</strong></p><div class="table-contents"><table class="table" summary="Equivalent C Types for Built-in SQL Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>
+ SQL Type
+ </th><th>
+ C Type
+ </th><th>
+ Defined In
+ </th></tr></thead><tbody><tr><td><code class="type">boolean</code></td><td><code class="type">bool</code></td><td><code class="filename">postgres.h</code> (maybe compiler built-in)</td></tr><tr><td><code class="type">box</code></td><td><code class="type">BOX*</code></td><td><code class="filename">utils/geo_decls.h</code></td></tr><tr><td><code class="type">bytea</code></td><td><code class="type">bytea*</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">"char"</code></td><td><code class="type">char</code></td><td>(compiler built-in)</td></tr><tr><td><code class="type">character</code></td><td><code class="type">BpChar*</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">cid</code></td><td><code class="type">CommandId</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">date</code></td><td><code class="type">DateADT</code></td><td><code class="filename">utils/date.h</code></td></tr><tr><td><code class="type">float4</code> (<code class="type">real</code>)</td><td><code class="type">float4</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">float8</code> (<code class="type">double precision</code>)</td><td><code class="type">float8</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">int2</code> (<code class="type">smallint</code>)</td><td><code class="type">int16</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">int4</code> (<code class="type">integer</code>)</td><td><code class="type">int32</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">int8</code> (<code class="type">bigint</code>)</td><td><code class="type">int64</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">interval</code></td><td><code class="type">Interval*</code></td><td><code class="filename">datatype/timestamp.h</code></td></tr><tr><td><code class="type">lseg</code></td><td><code class="type">LSEG*</code></td><td><code class="filename">utils/geo_decls.h</code></td></tr><tr><td><code class="type">name</code></td><td><code class="type">Name</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">numeric</code></td><td><code class="type">Numeric</code></td><td><code class="filename">utils/numeric.h</code></td></tr><tr><td><code class="type">oid</code></td><td><code class="type">Oid</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">oidvector</code></td><td><code class="type">oidvector*</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">path</code></td><td><code class="type">PATH*</code></td><td><code class="filename">utils/geo_decls.h</code></td></tr><tr><td><code class="type">point</code></td><td><code class="type">POINT*</code></td><td><code class="filename">utils/geo_decls.h</code></td></tr><tr><td><code class="type">regproc</code></td><td><code class="type">RegProcedure</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">text</code></td><td><code class="type">text*</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">tid</code></td><td><code class="type">ItemPointer</code></td><td><code class="filename">storage/itemptr.h</code></td></tr><tr><td><code class="type">time</code></td><td><code class="type">TimeADT</code></td><td><code class="filename">utils/date.h</code></td></tr><tr><td><code class="type">time with time zone</code></td><td><code class="type">TimeTzADT</code></td><td><code class="filename">utils/date.h</code></td></tr><tr><td><code class="type">timestamp</code></td><td><code class="type">Timestamp</code></td><td><code class="filename">datatype/timestamp.h</code></td></tr><tr><td><code class="type">timestamp with time zone</code></td><td><code class="type">TimestampTz</code></td><td><code class="filename">datatype/timestamp.h</code></td></tr><tr><td><code class="type">varchar</code></td><td><code class="type">VarChar*</code></td><td><code class="filename">postgres.h</code></td></tr><tr><td><code class="type">xid</code></td><td><code class="type">TransactionId</code></td><td><code class="filename">postgres.h</code></td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Now that we've gone over all of the possible structures
+ for base types, we can show some examples of real functions.
+ </p></div><div class="sect2" id="id-1.8.3.13.7"><div class="titlepage"><div><div><h3 class="title">38.10.3. Version 1 Calling Conventions</h3></div></div></div><p>
+ The version-1 calling convention relies on macros to suppress most
+ of the complexity of passing arguments and results. The C declaration
+ of a version-1 function is always:
+</p><pre class="programlisting">
+Datum funcname(PG_FUNCTION_ARGS)
+</pre><p>
+ In addition, the macro call:
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(funcname);
+</pre><p>
+ must appear in the same source file. (Conventionally, it's
+ written just before the function itself.) This macro call is not
+ needed for <code class="literal">internal</code>-language functions, since
+ <span class="productname">PostgreSQL</span> assumes that all internal functions
+ use the version-1 convention. It is, however, required for
+ dynamically-loaded functions.
+ </p><p>
+ In a version-1 function, each actual argument is fetched using a
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>()</code>
+ macro that corresponds to the argument's data type. (In non-strict
+ functions there needs to be a previous check about argument null-ness
+ using <code class="function">PG_ARGISNULL()</code>; see below.)
+ The result is returned using a
+ <code class="function">PG_RETURN_<em class="replaceable"><code>xxx</code></em>()</code>
+ macro for the return type.
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>()</code>
+ takes as its argument the number of the function argument to
+ fetch, where the count starts at 0.
+ <code class="function">PG_RETURN_<em class="replaceable"><code>xxx</code></em>()</code>
+ takes as its argument the actual value to return.
+ </p><p>
+ Here are some examples using the version-1 calling convention:
+ </p><pre class="programlisting">
+#include "postgres.h"
+#include &lt;string.h&gt;
+#include "fmgr.h"
+#include "utils/geo_decls.h"
+
+PG_MODULE_MAGIC;
+
+/* by value */
+
+PG_FUNCTION_INFO_V1(add_one);
+
+Datum
+add_one(PG_FUNCTION_ARGS)
+{
+ int32 arg = PG_GETARG_INT32(0);
+
+ PG_RETURN_INT32(arg + 1);
+}
+
+/* by reference, fixed length */
+
+PG_FUNCTION_INFO_V1(add_one_float8);
+
+Datum
+add_one_float8(PG_FUNCTION_ARGS)
+{
+ /* The macros for FLOAT8 hide its pass-by-reference nature. */
+ float8 arg = PG_GETARG_FLOAT8(0);
+
+ PG_RETURN_FLOAT8(arg + 1.0);
+}
+
+PG_FUNCTION_INFO_V1(makepoint);
+
+Datum
+makepoint(PG_FUNCTION_ARGS)
+{
+ /* Here, the pass-by-reference nature of Point is not hidden. */
+ Point *pointx = PG_GETARG_POINT_P(0);
+ Point *pointy = PG_GETARG_POINT_P(1);
+ Point *new_point = (Point *) palloc(sizeof(Point));
+
+ new_point-&gt;x = pointx-&gt;x;
+ new_point-&gt;y = pointy-&gt;y;
+
+ PG_RETURN_POINT_P(new_point);
+}
+
+/* by reference, variable length */
+
+PG_FUNCTION_INFO_V1(copytext);
+
+Datum
+copytext(PG_FUNCTION_ARGS)
+{
+ text *t = PG_GETARG_TEXT_PP(0);
+
+ /*
+ * VARSIZE_ANY_EXHDR is the size of the struct in bytes, minus the
+ * VARHDRSZ or VARHDRSZ_SHORT of its header. Construct the copy with a
+ * full-length header.
+ */
+ text *new_t = (text *) palloc(VARSIZE_ANY_EXHDR(t) + VARHDRSZ);
+ SET_VARSIZE(new_t, VARSIZE_ANY_EXHDR(t) + VARHDRSZ);
+
+ /*
+ * VARDATA is a pointer to the data region of the new struct. The source
+ * could be a short datum, so retrieve its data through VARDATA_ANY.
+ */
+ memcpy((void *) VARDATA(new_t), /* destination */
+ (void *) VARDATA_ANY(t), /* source */
+ VARSIZE_ANY_EXHDR(t)); /* how many bytes */
+ PG_RETURN_TEXT_P(new_t);
+}
+
+PG_FUNCTION_INFO_V1(concat_text);
+
+Datum
+concat_text(PG_FUNCTION_ARGS)
+{
+ text *arg1 = PG_GETARG_TEXT_PP(0);
+ text *arg2 = PG_GETARG_TEXT_PP(1);
+ int32 arg1_size = VARSIZE_ANY_EXHDR(arg1);
+ int32 arg2_size = VARSIZE_ANY_EXHDR(arg2);
+ int32 new_text_size = arg1_size + arg2_size + VARHDRSZ;
+ text *new_text = (text *) palloc(new_text_size);
+
+ SET_VARSIZE(new_text, new_text_size);
+ memcpy(VARDATA(new_text), VARDATA_ANY(arg1), arg1_size);
+ memcpy(VARDATA(new_text) + arg1_size, VARDATA_ANY(arg2), arg2_size);
+ PG_RETURN_TEXT_P(new_text);
+}
+
+</pre><p>
+ Supposing that the above code has been prepared in file
+ <code class="filename">funcs.c</code> and compiled into a shared object,
+ we could define the functions to <span class="productname">PostgreSQL</span>
+ with commands like this:
+ </p><pre class="programlisting">
+CREATE FUNCTION add_one(integer) RETURNS integer
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'add_one'
+ LANGUAGE C STRICT;
+
+-- note overloading of SQL function name "add_one"
+CREATE FUNCTION add_one(double precision) RETURNS double precision
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'add_one_float8'
+ LANGUAGE C STRICT;
+
+CREATE FUNCTION makepoint(point, point) RETURNS point
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'makepoint'
+ LANGUAGE C STRICT;
+
+CREATE FUNCTION copytext(text) RETURNS text
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'copytext'
+ LANGUAGE C STRICT;
+
+CREATE FUNCTION concat_text(text, text) RETURNS text
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'concat_text'
+ LANGUAGE C STRICT;
+</pre><p>
+ Here, <em class="replaceable"><code>DIRECTORY</code></em> stands for the
+ directory of the shared library file (for instance the
+ <span class="productname">PostgreSQL</span> tutorial directory, which
+ contains the code for the examples used in this section).
+ (Better style would be to use just <code class="literal">'funcs'</code> in the
+ <code class="literal">AS</code> clause, after having added
+ <em class="replaceable"><code>DIRECTORY</code></em> to the search path. In any
+ case, we can omit the system-specific extension for a shared
+ library, commonly <code class="literal">.so</code>.)
+ </p><p>
+ Notice that we have specified the functions as <span class="quote">“<span class="quote">strict</span>”</span>,
+ meaning that
+ the system should automatically assume a null result if any input
+ value is null. By doing this, we avoid having to check for null inputs
+ in the function code. Without this, we'd have to check for null values
+ explicitly, using <code class="function">PG_ARGISNULL()</code>.
+ </p><p>
+ The macro <code class="function">PG_ARGISNULL(<em class="replaceable"><code>n</code></em>)</code>
+ allows a function to test whether each input is null. (Of course, doing
+ this is only necessary in functions not declared <span class="quote">“<span class="quote">strict</span>”</span>.)
+ As with the
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>()</code> macros,
+ the input arguments are counted beginning at zero. Note that one
+ should refrain from executing
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>()</code> until
+ one has verified that the argument isn't null.
+ To return a null result, execute <code class="function">PG_RETURN_NULL()</code>;
+ this works in both strict and nonstrict functions.
+ </p><p>
+ At first glance, the version-1 coding conventions might appear
+ to be just pointless obscurantism, compared to using
+ plain <code class="literal">C</code> calling conventions. They do however allow
+ us to deal with <code class="literal">NULL</code>able arguments/return values,
+ and <span class="quote">“<span class="quote">toasted</span>”</span> (compressed or out-of-line) values.
+ </p><p>
+ Other options provided by the version-1 interface are two
+ variants of the
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>()</code>
+ macros. The first of these,
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>_COPY()</code>,
+ guarantees to return a copy of the specified argument that is
+ safe for writing into. (The normal macros will sometimes return a
+ pointer to a value that is physically stored in a table, which
+ must not be written to. Using the
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>_COPY()</code>
+ macros guarantees a writable result.)
+ The second variant consists of the
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em>_SLICE()</code>
+ macros which take three arguments. The first is the number of the
+ function argument (as above). The second and third are the offset and
+ length of the segment to be returned. Offsets are counted from
+ zero, and a negative length requests that the remainder of the
+ value be returned. These macros provide more efficient access to
+ parts of large values in the case where they have storage type
+ <span class="quote">“<span class="quote">external</span>”</span>. (The storage type of a column can be specified using
+ <code class="literal">ALTER TABLE <em class="replaceable"><code>tablename</code></em> ALTER
+ COLUMN <em class="replaceable"><code>colname</code></em> SET STORAGE
+ <em class="replaceable"><code>storagetype</code></em></code>. <em class="replaceable"><code>storagetype</code></em> is one of
+ <code class="literal">plain</code>, <code class="literal">external</code>, <code class="literal">extended</code>,
+ or <code class="literal">main</code>.)
+ </p><p>
+ Finally, the version-1 function call conventions make it possible
+ to return set results (<a class="xref" href="xfunc-c.html#XFUNC-C-RETURN-SET" title="38.10.8. Returning Sets">Section 38.10.8</a>) and
+ implement trigger functions (<a class="xref" href="triggers.html" title="Chapter 39. Triggers">Chapter 39</a>) and
+ procedural-language call handlers (<a class="xref" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Chapter 58</a>). For more details
+ see <code class="filename">src/backend/utils/fmgr/README</code> in the
+ source distribution.
+ </p></div><div class="sect2" id="id-1.8.3.13.8"><div class="titlepage"><div><div><h3 class="title">38.10.4. Writing Code</h3></div></div></div><p>
+ Before we turn to the more advanced topics, we should discuss
+ some coding rules for <span class="productname">PostgreSQL</span>
+ C-language functions. While it might be possible to load functions
+ written in languages other than C into
+ <span class="productname">PostgreSQL</span>, this is usually difficult
+ (when it is possible at all) because other languages, such as
+ C++, FORTRAN, or Pascal often do not follow the same calling
+ convention as C. That is, other languages do not pass argument
+ and return values between functions in the same way. For this
+ reason, we will assume that your C-language functions are
+ actually written in C.
+ </p><p>
+ The basic rules for writing and building C functions are as follows:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Use <code class="literal">pg_config
+ --includedir-server</code><a id="id-1.8.3.13.8.3.1.1.1.2" class="indexterm"></a>
+ to find out where the <span class="productname">PostgreSQL</span> server header
+ files are installed on your system (or the system that your
+ users will be running on).
+ </p></li><li class="listitem"><p>
+ Compiling and linking your code so that it can be dynamically
+ loaded into <span class="productname">PostgreSQL</span> always
+ requires special flags. See <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a> for a
+ detailed explanation of how to do it for your particular
+ operating system.
+ </p></li><li class="listitem"><p>
+ Remember to define a <span class="quote">“<span class="quote">magic block</span>”</span> for your shared library,
+ as described in <a class="xref" href="xfunc-c.html#XFUNC-C-DYNLOAD" title="38.10.1. Dynamic Loading">Section 38.10.1</a>.
+ </p></li><li class="listitem"><p>
+ When allocating memory, use the
+ <span class="productname">PostgreSQL</span> functions
+ <code class="function">palloc</code><a id="id-1.8.3.13.8.3.1.4.1.3" class="indexterm"></a> and <code class="function">pfree</code><a id="id-1.8.3.13.8.3.1.4.1.5" class="indexterm"></a>
+ instead of the corresponding C library functions
+ <code class="function">malloc</code> and <code class="function">free</code>.
+ The memory allocated by <code class="function">palloc</code> will be
+ freed automatically at the end of each transaction, preventing
+ memory leaks.
+ </p></li><li class="listitem"><p>
+ Always zero the bytes of your structures using <code class="function">memset</code>
+ (or allocate them with <code class="function">palloc0</code> in the first place).
+ Even if you assign to each field of your structure, there might be
+ alignment padding (holes in the structure) that contain
+ garbage values. Without this, it's difficult to
+ support hash indexes or hash joins, as you must pick out only
+ the significant bits of your data structure to compute a hash.
+ The planner also sometimes relies on comparing constants via
+ bitwise equality, so you can get undesirable planning results if
+ logically-equivalent values aren't bitwise equal.
+ </p></li><li class="listitem"><p>
+ Most of the internal <span class="productname">PostgreSQL</span>
+ types are declared in <code class="filename">postgres.h</code>, while
+ the function manager interfaces
+ (<code class="symbol">PG_FUNCTION_ARGS</code>, etc.) are in
+ <code class="filename">fmgr.h</code>, so you will need to include at
+ least these two files. For portability reasons it's best to
+ include <code class="filename">postgres.h</code> <span class="emphasis"><em>first</em></span>,
+ before any other system or user header files. Including
+ <code class="filename">postgres.h</code> will also include
+ <code class="filename">elog.h</code> and <code class="filename">palloc.h</code>
+ for you.
+ </p></li><li class="listitem"><p>
+ Symbol names defined within object files must not conflict
+ with each other or with symbols defined in the
+ <span class="productname">PostgreSQL</span> server executable. You
+ will have to rename your functions or variables if you get
+ error messages to this effect.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="DFUNC"><div class="titlepage"><div><div><h3 class="title">38.10.5. Compiling and Linking Dynamically-Loaded Functions</h3></div></div></div><p>
+ Before you are able to use your
+ <span class="productname">PostgreSQL</span> extension functions written in
+ C, they must be compiled and linked in a special way to produce a
+ file that can be dynamically loaded by the server. To be precise, a
+ <em class="firstterm">shared library</em> needs to be
+ created.<a id="id-1.8.3.13.9.2.3" class="indexterm"></a>
+
+ </p><p>
+ For information beyond what is contained in this section
+ you should read the documentation of your
+ operating system, in particular the manual pages for the C compiler,
+ <code class="command">cc</code>, and the link editor, <code class="command">ld</code>.
+ In addition, the <span class="productname">PostgreSQL</span> source code
+ contains several working examples in the
+ <code class="filename">contrib</code> directory. If you rely on these
+ examples you will make your modules dependent on the availability
+ of the <span class="productname">PostgreSQL</span> source code, however.
+ </p><p>
+ Creating shared libraries is generally analogous to linking
+ executables: first the source files are compiled into object files,
+ then the object files are linked together. The object files need to
+ be created as <em class="firstterm">position-independent code</em>
+ (<acronym class="acronym">PIC</acronym>),<a id="id-1.8.3.13.9.4.3" class="indexterm"></a> which
+ conceptually means that they can be placed at an arbitrary location
+ in memory when they are loaded by the executable. (Object files
+ intended for executables are usually not compiled that way.) The
+ command to link a shared library contains special flags to
+ distinguish it from linking an executable (at least in theory
+ — on some systems the practice is much uglier).
+ </p><p>
+ In the following examples we assume that your source code is in a
+ file <code class="filename">foo.c</code> and we will create a shared library
+ <code class="filename">foo.so</code>. The intermediate object file will be
+ called <code class="filename">foo.o</code> unless otherwise noted. A shared
+ library can contain more than one object file, but we only use one
+ here.
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
+ <span class="systemitem">FreeBSD</span>
+ <a id="id-1.8.3.13.9.6.1.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag to create <acronym class="acronym">PIC</acronym> is
+ <code class="option">-fPIC</code>. To create shared libraries the compiler
+ flag is <code class="option">-shared</code>.
+</p><pre class="programlisting">
+gcc -fPIC -c foo.c
+gcc -shared -o foo.so foo.o
+</pre><p>
+ This is applicable as of version 3.0 of
+ <span class="systemitem">FreeBSD</span>.
+ </p></dd><dt><span class="term">
+ <span class="systemitem">HP-UX</span>
+ <a id="id-1.8.3.13.9.6.2.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag of the system compiler to create
+ <acronym class="acronym">PIC</acronym> is <code class="option">+z</code>. When using
+ <span class="application">GCC</span> it's <code class="option">-fPIC</code>. The
+ linker flag for shared libraries is <code class="option">-b</code>. So:
+</p><pre class="programlisting">
+cc +z -c foo.c
+</pre><p>
+ or:
+</p><pre class="programlisting">
+gcc -fPIC -c foo.c
+</pre><p>
+ and then:
+</p><pre class="programlisting">
+ld -b -o foo.sl foo.o
+</pre><p>
+ <span class="systemitem">HP-UX</span> uses the extension
+ <code class="filename">.sl</code> for shared libraries, unlike most other
+ systems.
+ </p></dd><dt><span class="term">
+ <span class="systemitem">Linux</span>
+ <a id="id-1.8.3.13.9.6.3.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag to create <acronym class="acronym">PIC</acronym> is
+ <code class="option">-fPIC</code>.
+ The compiler flag to create a shared library is
+ <code class="option">-shared</code>. A complete example looks like this:
+</p><pre class="programlisting">
+cc -fPIC -c foo.c
+cc -shared -o foo.so foo.o
+</pre><p>
+ </p></dd><dt><span class="term">
+ <span class="systemitem">macOS</span>
+ <a id="id-1.8.3.13.9.6.4.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ Here is an example. It assumes the developer tools are installed.
+</p><pre class="programlisting">
+cc -c foo.c
+cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
+</pre><p>
+ </p></dd><dt><span class="term">
+ <span class="systemitem">NetBSD</span>
+ <a id="id-1.8.3.13.9.6.5.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag to create <acronym class="acronym">PIC</acronym> is
+ <code class="option">-fPIC</code>. For <acronym class="acronym">ELF</acronym> systems, the
+ compiler with the flag <code class="option">-shared</code> is used to link
+ shared libraries. On the older non-ELF systems, <code class="literal">ld
+ -Bshareable</code> is used.
+</p><pre class="programlisting">
+gcc -fPIC -c foo.c
+gcc -shared -o foo.so foo.o
+</pre><p>
+ </p></dd><dt><span class="term">
+ <span class="systemitem">OpenBSD</span>
+ <a id="id-1.8.3.13.9.6.6.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag to create <acronym class="acronym">PIC</acronym> is
+ <code class="option">-fPIC</code>. <code class="literal">ld -Bshareable</code> is
+ used to link shared libraries.
+</p><pre class="programlisting">
+gcc -fPIC -c foo.c
+ld -Bshareable -o foo.so foo.o
+</pre><p>
+ </p></dd><dt><span class="term">
+ <span class="systemitem">Solaris</span>
+ <a id="id-1.8.3.13.9.6.7.1.2" class="indexterm"></a>
+ </span></dt><dd><p>
+ The compiler flag to create <acronym class="acronym">PIC</acronym> is
+ <code class="option">-KPIC</code> with the Sun compiler and
+ <code class="option">-fPIC</code> with <span class="application">GCC</span>. To
+ link shared libraries, the compiler option is
+ <code class="option">-G</code> with either compiler or alternatively
+ <code class="option">-shared</code> with <span class="application">GCC</span>.
+</p><pre class="programlisting">
+cc -KPIC -c foo.c
+cc -G -o foo.so foo.o
+</pre><p>
+ or
+</p><pre class="programlisting">
+gcc -fPIC -c foo.c
+gcc -G -o foo.so foo.o
+</pre><p>
+ </p></dd></dl></div><div class="tip"><h3 class="title">Tip</h3><p>
+ If this is too complicated for you, you should consider using
+ <a class="ulink" href="https://www.gnu.org/software/libtool/" target="_top">
+ <span class="productname">GNU Libtool</span></a>,
+ which hides the platform differences behind a uniform interface.
+ </p></div><p>
+ The resulting shared library file can then be loaded into
+ <span class="productname">PostgreSQL</span>. When specifying the file name
+ to the <code class="command">CREATE FUNCTION</code> command, one must give it
+ the name of the shared library file, not the intermediate object file.
+ Note that the system's standard shared-library extension (usually
+ <code class="literal">.so</code> or <code class="literal">.sl</code>) can be omitted from
+ the <code class="command">CREATE FUNCTION</code> command, and normally should
+ be omitted for best portability.
+ </p><p>
+ Refer back to <a class="xref" href="xfunc-c.html#XFUNC-C-DYNLOAD" title="38.10.1. Dynamic Loading">Section 38.10.1</a> about where the
+ server expects to find the shared library files.
+ </p></div><div class="sect2" id="id-1.8.3.13.10"><div class="titlepage"><div><div><h3 class="title">38.10.6. Composite-Type Arguments</h3></div></div></div><p>
+ Composite types do not have a fixed layout like C structures.
+ Instances of a composite type can contain null fields. In
+ addition, composite types that are part of an inheritance
+ hierarchy can have different fields than other members of the
+ same inheritance hierarchy. Therefore,
+ <span class="productname">PostgreSQL</span> provides a function
+ interface for accessing fields of composite types from C.
+ </p><p>
+ Suppose we want to write a function to answer the query:
+
+</p><pre class="programlisting">
+SELECT name, c_overpaid(emp, 1500) AS overpaid
+ FROM emp
+ WHERE name = 'Bill' OR name = 'Sam';
+</pre><p>
+
+ Using the version-1 calling conventions, we can define
+ <code class="function">c_overpaid</code> as:
+
+</p><pre class="programlisting">
+#include "postgres.h"
+#include "executor/executor.h" /* for GetAttributeByName() */
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(c_overpaid);
+
+Datum
+c_overpaid(PG_FUNCTION_ARGS)
+{
+ HeapTupleHeader t = PG_GETARG_HEAPTUPLEHEADER(0);
+ int32 limit = PG_GETARG_INT32(1);
+ bool isnull;
+ Datum salary;
+
+ salary = GetAttributeByName(t, "salary", &amp;isnull);
+ if (isnull)
+ PG_RETURN_BOOL(false);
+ /* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */
+
+ PG_RETURN_BOOL(DatumGetInt32(salary) &gt; limit);
+}
+
+</pre><p>
+ </p><p>
+ <code class="function">GetAttributeByName</code> is the
+ <span class="productname">PostgreSQL</span> system function that
+ returns attributes out of the specified row. It has
+ three arguments: the argument of type <code class="type">HeapTupleHeader</code> passed
+ into
+ the function, the name of the desired attribute, and a
+ return parameter that tells whether the attribute
+ is null. <code class="function">GetAttributeByName</code> returns a <code class="type">Datum</code>
+ value that you can convert to the proper data type by using the
+ appropriate <code class="function">DatumGet<em class="replaceable"><code>XXX</code></em>()</code>
+ macro. Note that the return value is meaningless if the null flag is
+ set; always check the null flag before trying to do anything with the
+ result.
+ </p><p>
+ There is also <code class="function">GetAttributeByNum</code>, which selects
+ the target attribute by column number instead of name.
+ </p><p>
+ The following command declares the function
+ <code class="function">c_overpaid</code> in SQL:
+
+</p><pre class="programlisting">
+CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'c_overpaid'
+ LANGUAGE C STRICT;
+</pre><p>
+
+ Notice we have used <code class="literal">STRICT</code> so that we did not have to
+ check whether the input arguments were NULL.
+ </p></div><div class="sect2" id="id-1.8.3.13.11"><div class="titlepage"><div><div><h3 class="title">38.10.7. Returning Rows (Composite Types)</h3></div></div></div><p>
+ To return a row or composite-type value from a C-language
+ function, you can use a special API that provides macros and
+ functions to hide most of the complexity of building composite
+ data types. To use this API, the source file must include:
+</p><pre class="programlisting">
+#include "funcapi.h"
+</pre><p>
+ </p><p>
+ There are two ways you can build a composite data value (henceforth
+ a <span class="quote">“<span class="quote">tuple</span>”</span>): you can build it from an array of Datum values,
+ or from an array of C strings that can be passed to the input
+ conversion functions of the tuple's column data types. In either
+ case, you first need to obtain or construct a <code class="structname">TupleDesc</code>
+ descriptor for the tuple structure. When working with Datums, you
+ pass the <code class="structname">TupleDesc</code> to <code class="function">BlessTupleDesc</code>,
+ and then call <code class="function">heap_form_tuple</code> for each row. When working
+ with C strings, you pass the <code class="structname">TupleDesc</code> to
+ <code class="function">TupleDescGetAttInMetadata</code>, and then call
+ <code class="function">BuildTupleFromCStrings</code> for each row. In the case of a
+ function returning a set of tuples, the setup steps can all be done
+ once during the first call of the function.
+ </p><p>
+ Several helper functions are available for setting up the needed
+ <code class="structname">TupleDesc</code>. The recommended way to do this in most
+ functions returning composite values is to call:
+</p><pre class="programlisting">
+TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
+ Oid *resultTypeId,
+ TupleDesc *resultTupleDesc)
+</pre><p>
+ passing the same <code class="literal">fcinfo</code> struct passed to the calling function
+ itself. (This of course requires that you use the version-1
+ calling conventions.) <code class="varname">resultTypeId</code> can be specified
+ as <code class="literal">NULL</code> or as the address of a local variable to receive the
+ function's result type OID. <code class="varname">resultTupleDesc</code> should be the
+ address of a local <code class="structname">TupleDesc</code> variable. Check that the
+ result is <code class="literal">TYPEFUNC_COMPOSITE</code>; if so,
+ <code class="varname">resultTupleDesc</code> has been filled with the needed
+ <code class="structname">TupleDesc</code>. (If it is not, you can report an error along
+ the lines of <span class="quote">“<span class="quote">function returning record called in context that
+ cannot accept type record</span>”</span>.)
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <code class="function">get_call_result_type</code> can resolve the actual type of a
+ polymorphic function result; so it is useful in functions that return
+ scalar polymorphic results, not only functions that return composites.
+ The <code class="varname">resultTypeId</code> output is primarily useful for functions
+ returning polymorphic scalars.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ <code class="function">get_call_result_type</code> has a sibling
+ <code class="function">get_expr_result_type</code>, which can be used to resolve the
+ expected output type for a function call represented by an expression
+ tree. This can be used when trying to determine the result type from
+ outside the function itself. There is also
+ <code class="function">get_func_result_type</code>, which can be used when only the
+ function's OID is available. However these functions are not able
+ to deal with functions declared to return <code class="structname">record</code>, and
+ <code class="function">get_func_result_type</code> cannot resolve polymorphic types,
+ so you should preferentially use <code class="function">get_call_result_type</code>.
+ </p></div><p>
+ Older, now-deprecated functions for obtaining
+ <code class="structname">TupleDesc</code>s are:
+</p><pre class="programlisting">
+TupleDesc RelationNameGetTupleDesc(const char *relname)
+</pre><p>
+ to get a <code class="structname">TupleDesc</code> for the row type of a named relation,
+ and:
+</p><pre class="programlisting">
+TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)
+</pre><p>
+ to get a <code class="structname">TupleDesc</code> based on a type OID. This can
+ be used to get a <code class="structname">TupleDesc</code> for a base or
+ composite type. It will not work for a function that returns
+ <code class="structname">record</code>, however, and it cannot resolve polymorphic
+ types.
+ </p><p>
+ Once you have a <code class="structname">TupleDesc</code>, call:
+</p><pre class="programlisting">
+TupleDesc BlessTupleDesc(TupleDesc tupdesc)
+</pre><p>
+ if you plan to work with Datums, or:
+</p><pre class="programlisting">
+AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)
+</pre><p>
+ if you plan to work with C strings. If you are writing a function
+ returning set, you can save the results of these functions in the
+ <code class="structname">FuncCallContext</code> structure — use the
+ <code class="structfield">tuple_desc</code> or <code class="structfield">attinmeta</code> field
+ respectively.
+ </p><p>
+ When working with Datums, use:
+</p><pre class="programlisting">
+HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull)
+</pre><p>
+ to build a <code class="structname">HeapTuple</code> given user data in Datum form.
+ </p><p>
+ When working with C strings, use:
+</p><pre class="programlisting">
+HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
+</pre><p>
+ to build a <code class="structname">HeapTuple</code> given user data
+ in C string form. <em class="parameter"><code>values</code></em> is an array of C strings,
+ one for each attribute of the return row. Each C string should be in
+ the form expected by the input function of the attribute data
+ type. In order to return a null value for one of the attributes,
+ the corresponding pointer in the <em class="parameter"><code>values</code></em> array
+ should be set to <code class="symbol">NULL</code>. This function will need to
+ be called again for each row you return.
+ </p><p>
+ Once you have built a tuple to return from your function, it
+ must be converted into a <code class="type">Datum</code>. Use:
+</p><pre class="programlisting">
+HeapTupleGetDatum(HeapTuple tuple)
+</pre><p>
+ to convert a <code class="structname">HeapTuple</code> into a valid Datum. This
+ <code class="type">Datum</code> can be returned directly if you intend to return
+ just a single row, or it can be used as the current return value
+ in a set-returning function.
+ </p><p>
+ An example appears in the next section.
+ </p></div><div class="sect2" id="XFUNC-C-RETURN-SET"><div class="titlepage"><div><div><h3 class="title">38.10.8. Returning Sets</h3></div></div></div><p>
+ C-language functions have two options for returning sets (multiple
+ rows). In one method, called <em class="firstterm">ValuePerCall</em>
+ mode, a set-returning function is called repeatedly (passing the same
+ arguments each time) and it returns one new row on each call, until
+ it has no more rows to return and signals that by returning NULL.
+ The set-returning function (<acronym class="acronym">SRF</acronym>) must therefore
+ save enough state across calls to remember what it was doing and
+ return the correct next item on each call.
+ In the other method, called <em class="firstterm">Materialize</em> mode,
+ an SRF fills and returns a tuplestore object containing its
+ entire result; then only one call occurs for the whole result, and
+ no inter-call state is needed.
+ </p><p>
+ When using ValuePerCall mode, it is important to remember that the
+ query is not guaranteed to be run to completion; that is, due to
+ options such as <code class="literal">LIMIT</code>, the executor might stop
+ making calls to the set-returning function before all rows have been
+ fetched. This means it is not safe to perform cleanup activities in
+ the last call, because that might not ever happen. It's recommended
+ to use Materialize mode for functions that need access to external
+ resources, such as file descriptors.
+ </p><p>
+ The remainder of this section documents a set of helper macros that
+ are commonly used (though not required to be used) for SRFs using
+ ValuePerCall mode. Additional details about Materialize mode can be
+ found in <code class="filename">src/backend/utils/fmgr/README</code>. Also,
+ the <code class="filename">contrib</code> modules in
+ the <span class="productname">PostgreSQL</span> source distribution contain
+ many examples of SRFs using both ValuePerCall and Materialize mode.
+ </p><p>
+ To use the ValuePerCall support macros described here,
+ include <code class="filename">funcapi.h</code>. These macros work with a
+ structure <code class="structname">FuncCallContext</code> that contains the
+ state that needs to be saved across calls. Within the calling
+ SRF, <code class="literal">fcinfo-&gt;flinfo-&gt;fn_extra</code> is used to
+ hold a pointer to <code class="structname">FuncCallContext</code> across
+ calls. The macros automatically fill that field on first use,
+ and expect to find the same pointer there on subsequent uses.
+</p><pre class="programlisting">
+typedef struct FuncCallContext
+{
+ /*
+ * Number of times we've been called before
+ *
+ * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
+ * incremented for you every time SRF_RETURN_NEXT() is called.
+ */
+ uint64 call_cntr;
+
+ /*
+ * OPTIONAL maximum number of calls
+ *
+ * max_calls is here for convenience only and setting it is optional.
+ * If not set, you must provide alternative means to know when the
+ * function is done.
+ */
+ uint64 max_calls;
+
+ /*
+ * OPTIONAL pointer to miscellaneous user-provided context information
+ *
+ * user_fctx is for use as a pointer to your own data to retain
+ * arbitrary context information between calls of your function.
+ */
+ void *user_fctx;
+
+ /*
+ * OPTIONAL pointer to struct containing attribute type input metadata
+ *
+ * attinmeta is for use when returning tuples (i.e., composite data types)
+ * and is not used when returning base data types. It is only needed
+ * if you intend to use BuildTupleFromCStrings() to create the return
+ * tuple.
+ */
+ AttInMetadata *attinmeta;
+
+ /*
+ * memory context used for structures that must live for multiple calls
+ *
+ * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
+ * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
+ * context for any memory that is to be reused across multiple calls
+ * of the SRF.
+ */
+ MemoryContext multi_call_memory_ctx;
+
+ /*
+ * OPTIONAL pointer to struct containing tuple description
+ *
+ * tuple_desc is for use when returning tuples (i.e., composite data types)
+ * and is only needed if you are going to build the tuples with
+ * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
+ * the TupleDesc pointer stored here should usually have been run through
+ * BlessTupleDesc() first.
+ */
+ TupleDesc tuple_desc;
+
+} FuncCallContext;
+</pre><p>
+ </p><p>
+ The macros to be used by an <acronym class="acronym">SRF</acronym> using this
+ infrastructure are:
+</p><pre class="programlisting">
+SRF_IS_FIRSTCALL()
+</pre><p>
+ Use this to determine if your function is being called for the first or a
+ subsequent time. On the first call (only), call:
+</p><pre class="programlisting">
+SRF_FIRSTCALL_INIT()
+</pre><p>
+ to initialize the <code class="structname">FuncCallContext</code>. On every function call,
+ including the first, call:
+</p><pre class="programlisting">
+SRF_PERCALL_SETUP()
+</pre><p>
+ to set up for using the <code class="structname">FuncCallContext</code>.
+ </p><p>
+ If your function has data to return in the current call, use:
+</p><pre class="programlisting">
+SRF_RETURN_NEXT(funcctx, result)
+</pre><p>
+ to return it to the caller. (<code class="literal">result</code> must be of type
+ <code class="type">Datum</code>, either a single value or a tuple prepared as
+ described above.) Finally, when your function is finished
+ returning data, use:
+</p><pre class="programlisting">
+SRF_RETURN_DONE(funcctx)
+</pre><p>
+ to clean up and end the <acronym class="acronym">SRF</acronym>.
+ </p><p>
+ The memory context that is current when the <acronym class="acronym">SRF</acronym> is called is
+ a transient context that will be cleared between calls. This means
+ that you do not need to call <code class="function">pfree</code> on everything
+ you allocated using <code class="function">palloc</code>; it will go away anyway. However, if you want to allocate
+ any data structures to live across calls, you need to put them somewhere
+ else. The memory context referenced by
+ <code class="structfield">multi_call_memory_ctx</code> is a suitable location for any
+ data that needs to survive until the <acronym class="acronym">SRF</acronym> is finished running. In most
+ cases, this means that you should switch into
+ <code class="structfield">multi_call_memory_ctx</code> while doing the
+ first-call setup.
+ Use <code class="literal">funcctx-&gt;user_fctx</code> to hold a pointer to
+ any such cross-call data structures.
+ (Data you allocate
+ in <code class="structfield">multi_call_memory_ctx</code> will go away
+ automatically when the query ends, so it is not necessary to free
+ that data manually, either.)
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ While the actual arguments to the function remain unchanged between
+ calls, if you detoast the argument values (which is normally done
+ transparently by the
+ <code class="function">PG_GETARG_<em class="replaceable"><code>xxx</code></em></code> macro)
+ in the transient context then the detoasted copies will be freed on
+ each cycle. Accordingly, if you keep references to such values in
+ your <code class="structfield">user_fctx</code>, you must either copy them into the
+ <code class="structfield">multi_call_memory_ctx</code> after detoasting, or ensure
+ that you detoast the values only in that context.
+ </p></div><p>
+ A complete pseudo-code example looks like the following:
+</p><pre class="programlisting">
+Datum
+my_set_returning_function(PG_FUNCTION_ARGS)
+{
+ FuncCallContext *funcctx;
+ Datum result;
+ <em class="replaceable"><code>further declarations as needed</code></em>
+
+ if (SRF_IS_FIRSTCALL())
+ {
+ MemoryContext oldcontext;
+
+ funcctx = SRF_FIRSTCALL_INIT();
+ oldcontext = MemoryContextSwitchTo(funcctx-&gt;multi_call_memory_ctx);
+ /* One-time setup code appears here: */
+ <em class="replaceable"><code>user code</code></em>
+ <em class="replaceable"><code>if returning composite</code></em>
+ <em class="replaceable"><code>build TupleDesc, and perhaps AttInMetadata</code></em>
+ <em class="replaceable"><code>endif returning composite</code></em>
+ <em class="replaceable"><code>user code</code></em>
+ MemoryContextSwitchTo(oldcontext);
+ }
+
+ /* Each-time setup code appears here: */
+ <em class="replaceable"><code>user code</code></em>
+ funcctx = SRF_PERCALL_SETUP();
+ <em class="replaceable"><code>user code</code></em>
+
+ /* this is just one way we might test whether we are done: */
+ if (funcctx-&gt;call_cntr &lt; funcctx-&gt;max_calls)
+ {
+ /* Here we want to return another item: */
+ <em class="replaceable"><code>user code</code></em>
+ <em class="replaceable"><code>obtain result Datum</code></em>
+ SRF_RETURN_NEXT(funcctx, result);
+ }
+ else
+ {
+ /* Here we are done returning items, so just report that fact. */
+ /* (Resist the temptation to put cleanup code here.) */
+ SRF_RETURN_DONE(funcctx);
+ }
+}
+</pre><p>
+ </p><p>
+ A complete example of a simple <acronym class="acronym">SRF</acronym> returning a composite type
+ looks like:
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(retcomposite);
+
+Datum
+retcomposite(PG_FUNCTION_ARGS)
+{
+ FuncCallContext *funcctx;
+ int call_cntr;
+ int max_calls;
+ TupleDesc tupdesc;
+ AttInMetadata *attinmeta;
+
+ /* stuff done only on the first call of the function */
+ if (SRF_IS_FIRSTCALL())
+ {
+ MemoryContext oldcontext;
+
+ /* create a function context for cross-call persistence */
+ funcctx = SRF_FIRSTCALL_INIT();
+
+ /* switch to memory context appropriate for multiple function calls */
+ oldcontext = MemoryContextSwitchTo(funcctx-&gt;multi_call_memory_ctx);
+
+ /* total number of tuples to be returned */
+ funcctx-&gt;max_calls = PG_GETARG_INT32(0);
+
+ /* Build a tuple descriptor for our result type */
+ if (get_call_result_type(fcinfo, NULL, &amp;tupdesc) != TYPEFUNC_COMPOSITE)
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("function returning record called in context "
+ "that cannot accept type record")));
+
+ /*
+ * generate attribute metadata needed later to produce tuples from raw
+ * C strings
+ */
+ attinmeta = TupleDescGetAttInMetadata(tupdesc);
+ funcctx-&gt;attinmeta = attinmeta;
+
+ MemoryContextSwitchTo(oldcontext);
+ }
+
+ /* stuff done on every call of the function */
+ funcctx = SRF_PERCALL_SETUP();
+
+ call_cntr = funcctx-&gt;call_cntr;
+ max_calls = funcctx-&gt;max_calls;
+ attinmeta = funcctx-&gt;attinmeta;
+
+ if (call_cntr &lt; max_calls) /* do when there is more left to send */
+ {
+ char **values;
+ HeapTuple tuple;
+ Datum result;
+
+ /*
+ * Prepare a values array for building the returned tuple.
+ * This should be an array of C strings which will
+ * be processed later by the type input functions.
+ */
+ values = (char **) palloc(3 * sizeof(char *));
+ values[0] = (char *) palloc(16 * sizeof(char));
+ values[1] = (char *) palloc(16 * sizeof(char));
+ values[2] = (char *) palloc(16 * sizeof(char));
+
+ snprintf(values[0], 16, "%d", 1 * PG_GETARG_INT32(1));
+ snprintf(values[1], 16, "%d", 2 * PG_GETARG_INT32(1));
+ snprintf(values[2], 16, "%d", 3 * PG_GETARG_INT32(1));
+
+ /* build a tuple */
+ tuple = BuildTupleFromCStrings(attinmeta, values);
+
+ /* make the tuple into a datum */
+ result = HeapTupleGetDatum(tuple);
+
+ /* clean up (this is not really necessary) */
+ pfree(values[0]);
+ pfree(values[1]);
+ pfree(values[2]);
+ pfree(values);
+
+ SRF_RETURN_NEXT(funcctx, result);
+ }
+ else /* do when there is no more left */
+ {
+ SRF_RETURN_DONE(funcctx);
+ }
+}
+
+</pre><p>
+
+ One way to declare this function in SQL is:
+</p><pre class="programlisting">
+CREATE TYPE __retcomposite AS (f1 integer, f2 integer, f3 integer);
+
+CREATE OR REPLACE FUNCTION retcomposite(integer, integer)
+ RETURNS SETOF __retcomposite
+ AS '<em class="replaceable"><code>filename</code></em>', 'retcomposite'
+ LANGUAGE C IMMUTABLE STRICT;
+</pre><p>
+ A different way is to use OUT parameters:
+</p><pre class="programlisting">
+CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer,
+ OUT f1 integer, OUT f2 integer, OUT f3 integer)
+ RETURNS SETOF record
+ AS '<em class="replaceable"><code>filename</code></em>', 'retcomposite'
+ LANGUAGE C IMMUTABLE STRICT;
+</pre><p>
+ Notice that in this method the output type of the function is formally
+ an anonymous <code class="structname">record</code> type.
+ </p></div><div class="sect2" id="id-1.8.3.13.13"><div class="titlepage"><div><div><h3 class="title">38.10.9. Polymorphic Arguments and Return Types</h3></div></div></div><p>
+ C-language functions can be declared to accept and
+ return the polymorphic types described in <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>.
+ When a function's arguments or return types
+ are defined as polymorphic types, the function author cannot know
+ in advance what data type it will be called with, or
+ need to return. There are two routines provided in <code class="filename">fmgr.h</code>
+ to allow a version-1 C function to discover the actual data types
+ of its arguments and the type it is expected to return. The routines are
+ called <code class="literal">get_fn_expr_rettype(FmgrInfo *flinfo)</code> and
+ <code class="literal">get_fn_expr_argtype(FmgrInfo *flinfo, int argnum)</code>.
+ They return the result or argument type OID, or <code class="symbol">InvalidOid</code> if the
+ information is not available.
+ The structure <code class="literal">flinfo</code> is normally accessed as
+ <code class="literal">fcinfo-&gt;flinfo</code>. The parameter <code class="literal">argnum</code>
+ is zero based. <code class="function">get_call_result_type</code> can also be used
+ as an alternative to <code class="function">get_fn_expr_rettype</code>.
+ There is also <code class="function">get_fn_expr_variadic</code>, which can be used to
+ find out whether variadic arguments have been merged into an array.
+ This is primarily useful for <code class="literal">VARIADIC "any"</code> functions,
+ since such merging will always have occurred for variadic functions
+ taking ordinary array types.
+ </p><p>
+ For example, suppose we want to write a function to accept a single
+ element of any type, and return a one-dimensional array of that type:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(make_array);
+Datum
+make_array(PG_FUNCTION_ARGS)
+{
+ ArrayType *result;
+ Oid element_type = get_fn_expr_argtype(fcinfo-&gt;flinfo, 0);
+ Datum element;
+ bool isnull;
+ int16 typlen;
+ bool typbyval;
+ char typalign;
+ int ndims;
+ int dims[MAXDIM];
+ int lbs[MAXDIM];
+
+ if (!OidIsValid(element_type))
+ elog(ERROR, "could not determine data type of input");
+
+ /* get the provided element, being careful in case it's NULL */
+ isnull = PG_ARGISNULL(0);
+ if (isnull)
+ element = (Datum) 0;
+ else
+ element = PG_GETARG_DATUM(0);
+
+ /* we have one dimension */
+ ndims = 1;
+ /* and one element */
+ dims[0] = 1;
+ /* and lower bound is 1 */
+ lbs[0] = 1;
+
+ /* get required info about the element type */
+ get_typlenbyvalalign(element_type, &amp;typlen, &amp;typbyval, &amp;typalign);
+
+ /* now build the array */
+ result = construct_md_array(&amp;element, &amp;isnull, ndims, dims, lbs,
+ element_type, typlen, typbyval, typalign);
+
+ PG_RETURN_ARRAYTYPE_P(result);
+}
+</pre><p>
+ </p><p>
+ The following command declares the function
+ <code class="function">make_array</code> in SQL:
+
+</p><pre class="programlisting">
+CREATE FUNCTION make_array(anyelement) RETURNS anyarray
+ AS '<em class="replaceable"><code>DIRECTORY</code></em>/funcs', 'make_array'
+ LANGUAGE C IMMUTABLE;
+</pre><p>
+ </p><p>
+ There is a variant of polymorphism that is only available to C-language
+ functions: they can be declared to take parameters of type
+ <code class="literal">"any"</code>. (Note that this type name must be double-quoted,
+ since it's also an SQL reserved word.) This works like
+ <code class="type">anyelement</code> except that it does not constrain different
+ <code class="literal">"any"</code> arguments to be the same type, nor do they help
+ determine the function's result type. A C-language function can also
+ declare its final parameter to be <code class="literal">VARIADIC "any"</code>. This will
+ match one or more actual arguments of any type (not necessarily the same
+ type). These arguments will <span class="emphasis"><em>not</em></span> be gathered into an array
+ as happens with normal variadic functions; they will just be passed to
+ the function separately. The <code class="function">PG_NARGS()</code> macro and the
+ methods described above must be used to determine the number of actual
+ arguments and their types when using this feature. Also, users of such
+ a function might wish to use the <code class="literal">VARIADIC</code> keyword in their
+ function call, with the expectation that the function would treat the
+ array elements as separate arguments. The function itself must implement
+ that behavior if wanted, after using <code class="function">get_fn_expr_variadic</code> to
+ detect that the actual argument was marked with <code class="literal">VARIADIC</code>.
+ </p></div><div class="sect2" id="XFUNC-SHARED-ADDIN"><div class="titlepage"><div><div><h3 class="title">38.10.10. Shared Memory and LWLocks</h3></div></div></div><p>
+ Add-ins can reserve LWLocks and an allocation of shared memory on server
+ startup. The add-in's shared library must be preloaded by specifying
+ it in
+ <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a><a id="id-1.8.3.13.14.2.2" class="indexterm"></a>.
+ The shared library should register a <code class="literal">shmem_request_hook</code>
+ in its <code class="function">_PG_init</code> function. This
+ <code class="literal">shmem_request_hook</code> can reserve LWLocks or shared memory.
+ Shared memory is reserved by calling:
+</p><pre class="programlisting">
+void RequestAddinShmemSpace(int size)
+</pre><p>
+ from your <code class="literal">shmem_request_hook</code>.
+ </p><p>
+ LWLocks are reserved by calling:
+</p><pre class="programlisting">
+void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
+</pre><p>
+ from your <code class="literal">shmem_request_hook</code>. This will ensure that an array of
+ <code class="literal">num_lwlocks</code> LWLocks is available under the name
+ <code class="literal">tranche_name</code>. Use <code class="function">GetNamedLWLockTranche</code>
+ to get a pointer to this array.
+ </p><p>
+ An example of a <code class="literal">shmem_request_hook</code> can be found in
+ <code class="filename">contrib/pg_stat_statements/pg_stat_statements.c</code> in the
+ <span class="productname">PostgreSQL</span> source tree.
+ </p><p>
+ To avoid possible race-conditions, each backend should use the LWLock
+ <code class="function">AddinShmemInitLock</code> when connecting to and initializing
+ its allocation of shared memory, as shown here:
+</p><pre class="programlisting">
+static mystruct *ptr = NULL;
+
+if (!ptr)
+{
+ bool found;
+
+ LWLockAcquire(AddinShmemInitLock, LW_EXCLUSIVE);
+ ptr = ShmemInitStruct("my struct name", size, &amp;found);
+ if (!found)
+ {
+ initialize contents of shmem area;
+ acquire any requested LWLocks using:
+ ptr-&gt;locks = GetNamedLWLockTranche("my tranche name");
+ }
+ LWLockRelease(AddinShmemInitLock);
+}
+</pre><p>
+ </p></div><div class="sect2" id="EXTEND-CPP"><div class="titlepage"><div><div><h3 class="title">38.10.11. Using C++ for Extensibility</h3></div></div></div><a id="id-1.8.3.13.15.2" class="indexterm"></a><p>
+ Although the <span class="productname">PostgreSQL</span> backend is written in
+ C, it is possible to write extensions in C++ if these guidelines are
+ followed:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ All functions accessed by the backend must present a C interface
+ to the backend; these C functions can then call C++ functions.
+ For example, <code class="literal">extern C</code> linkage is required for
+ backend-accessed functions. This is also necessary for any
+ functions that are passed as pointers between the backend and
+ C++ code.
+ </p></li><li class="listitem"><p>
+ Free memory using the appropriate deallocation method. For example,
+ most backend memory is allocated using <code class="function">palloc()</code>, so use
+ <code class="function">pfree()</code> to free it. Using C++
+ <code class="function">delete</code> in such cases will fail.
+ </p></li><li class="listitem"><p>
+ Prevent exceptions from propagating into the C code (use a catch-all
+ block at the top level of all <code class="literal">extern C</code> functions). This
+ is necessary even if the C++ code does not explicitly throw any
+ exceptions, because events like out-of-memory can still throw
+ exceptions. Any exceptions must be caught and appropriate errors
+ passed back to the C interface. If possible, compile C++ with
+ <code class="option">-fno-exceptions</code> to eliminate exceptions entirely; in such
+ cases, you must check for failures in your C++ code, e.g., check for
+ NULL returned by <code class="function">new()</code>.
+ </p></li><li class="listitem"><p>
+ If calling backend functions from C++ code, be sure that the
+ C++ call stack contains only plain old data structures
+ (<acronym class="acronym">POD</acronym>). This is necessary because backend errors
+ generate a distant <code class="function">longjmp()</code> that does not properly
+ unroll a C++ call stack with non-POD objects.
+ </p></li></ul></div><p>
+ </p><p>
+ In summary, it is best to place C++ code behind a wall of
+ <code class="literal">extern C</code> functions that interface to the backend,
+ and avoid exception, memory, and call stack leakage.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-internal.html" title="38.9. Internal Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.9. Internal Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.11. Function Optimization Information</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-internal.html b/doc/src/sgml/html/xfunc-internal.html
new file mode 100644
index 0000000..033ece2
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-internal.html
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.9. Internal Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-pl.html" title="38.8. Procedural Language Functions" /><link rel="next" href="xfunc-c.html" title="38.10. C-Language Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.9. Internal Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-pl.html" title="38.8. Procedural Language Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-c.html" title="38.10. C-Language Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-INTERNAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.9. Internal Functions</h2></div></div></div><a id="id-1.8.3.12.2" class="indexterm"></a><p>
+ Internal functions are functions written in C that have been statically
+ linked into the <span class="productname">PostgreSQL</span> server.
+ The <span class="quote">“<span class="quote">body</span>”</span> of the function definition
+ specifies the C-language name of the function, which need not be the
+ same as the name being declared for SQL use.
+ (For reasons of backward compatibility, an empty body
+ is accepted as meaning that the C-language function name is the
+ same as the SQL name.)
+ </p><p>
+ Normally, all internal functions present in the
+ server are declared during the initialization of the database cluster
+ (see <a class="xref" href="creating-cluster.html" title="19.2. Creating a Database Cluster">Section 19.2</a>),
+ but a user could use <code class="command">CREATE FUNCTION</code>
+ to create additional alias names for an internal function.
+ Internal functions are declared in <code class="command">CREATE FUNCTION</code>
+ with language name <code class="literal">internal</code>. For instance, to
+ create an alias for the <code class="function">sqrt</code> function:
+</p><pre class="programlisting">
+CREATE FUNCTION square_root(double precision) RETURNS double precision
+ AS 'dsqrt'
+ LANGUAGE internal
+ STRICT;
+</pre><p>
+ (Most internal functions expect to be declared <span class="quote">“<span class="quote">strict</span>”</span>.)
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Not all <span class="quote">“<span class="quote">predefined</span>”</span> functions are
+ <span class="quote">“<span class="quote">internal</span>”</span> in the above sense. Some predefined
+ functions are written in SQL.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-pl.html" title="38.8. Procedural Language Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-c.html" title="38.10. C-Language Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.8. Procedural Language Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.10. C-Language Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-optimization.html b/doc/src/sgml/html/xfunc-optimization.html
new file mode 100644
index 0000000..d468dee
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-optimization.html
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.11. Function Optimization Information</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-c.html" title="38.10. C-Language Functions" /><link rel="next" href="xaggr.html" title="38.12. User-Defined Aggregates" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.11. Function Optimization Information</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-c.html" title="38.10. C-Language Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xaggr.html" title="38.12. User-Defined Aggregates">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-OPTIMIZATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.11. Function Optimization Information</h2></div></div></div><a id="id-1.8.3.14.2" class="indexterm"></a><p>
+ By default, a function is just a <span class="quote">“<span class="quote">black box</span>”</span> that the
+ database system knows very little about the behavior of. However,
+ that means that queries using the function may be executed much less
+ efficiently than they could be. It is possible to supply additional
+ knowledge that helps the planner optimize function calls.
+ </p><p>
+ Some basic facts can be supplied by declarative annotations provided in
+ the <a class="link" href="sql-createfunction.html" title="CREATE FUNCTION"><code class="command">CREATE FUNCTION</code></a> command. Most important of
+ these is the function's <a class="link" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">volatility
+ category</a> (<code class="literal">IMMUTABLE</code>, <code class="literal">STABLE</code>,
+ or <code class="literal">VOLATILE</code>); one should always be careful to
+ specify this correctly when defining a function.
+ The parallel safety property (<code class="literal">PARALLEL
+ UNSAFE</code>, <code class="literal">PARALLEL RESTRICTED</code>, or
+ <code class="literal">PARALLEL SAFE</code>) must also be specified if you hope
+ to use the function in parallelized queries.
+ It can also be useful to specify the function's estimated execution
+ cost, and/or the number of rows a set-returning function is estimated
+ to return. However, the declarative way of specifying those two
+ facts only allows specifying a constant value, which is often
+ inadequate.
+ </p><p>
+ It is also possible to attach a <em class="firstterm">planner support
+ function</em> to an SQL-callable function (called
+ its <em class="firstterm">target function</em>), and thereby provide
+ knowledge about the target function that is too complex to be
+ represented declaratively. Planner support functions have to be
+ written in C (although their target functions might not be), so this is
+ an advanced feature that relatively few people will use.
+ </p><p>
+ A planner support function must have the SQL signature
+</p><pre class="programlisting">
+supportfn(internal) returns internal
+</pre><p>
+ It is attached to its target function by specifying
+ the <code class="literal">SUPPORT</code> clause when creating the target function.
+ </p><p>
+ The details of the API for planner support functions can be found in
+ file <code class="filename">src/include/nodes/supportnodes.h</code> in the
+ <span class="productname">PostgreSQL</span> source code. Here we provide
+ just an overview of what planner support functions can do.
+ The set of possible requests to a support function is extensible,
+ so more things might be possible in future versions.
+ </p><p>
+ Some function calls can be simplified during planning based on
+ properties specific to the function. For example,
+ <code class="literal">int4mul(n, 1)</code> could be simplified to
+ just <code class="literal">n</code>. This type of transformation can be
+ performed by a planner support function, by having it implement
+ the <code class="literal">SupportRequestSimplify</code> request type.
+ The support function will be called for each instance of its target
+ function found in a query parse tree. If it finds that the particular
+ call can be simplified into some other form, it can build and return a
+ parse tree representing that expression. This will automatically work
+ for operators based on the function, too — in the example just
+ given, <code class="literal">n * 1</code> would also be simplified to
+ <code class="literal">n</code>.
+ (But note that this is just an example; this particular
+ optimization is not actually performed by
+ standard <span class="productname">PostgreSQL</span>.)
+ We make no guarantee that <span class="productname">PostgreSQL</span> will
+ never call the target function in cases that the support function could
+ simplify. Ensure rigorous equivalence between the simplified
+ expression and an actual execution of the target function.
+ </p><p>
+ For target functions that return <code class="type">boolean</code>, it is often useful to estimate
+ the fraction of rows that will be selected by a <code class="literal">WHERE</code> clause using that
+ function. This can be done by a support function that implements
+ the <code class="literal">SupportRequestSelectivity</code> request type.
+ </p><p>
+ If the target function's run time is highly dependent on its inputs,
+ it may be useful to provide a non-constant cost estimate for it.
+ This can be done by a support function that implements
+ the <code class="literal">SupportRequestCost</code> request type.
+ </p><p>
+ For target functions that return sets, it is often useful to provide
+ a non-constant estimate for the number of rows that will be returned.
+ This can be done by a support function that implements
+ the <code class="literal">SupportRequestRows</code> request type.
+ </p><p>
+ For target functions that return <code class="type">boolean</code>, it may be possible to
+ convert a function call appearing in <code class="literal">WHERE</code> into an indexable operator
+ clause or clauses. The converted clauses might be exactly equivalent
+ to the function's condition, or they could be somewhat weaker (that is,
+ they might accept some values that the function condition does not).
+ In the latter case the index condition is said to
+ be <em class="firstterm">lossy</em>; it can still be used to scan an index,
+ but the function call will have to be executed for each row returned by
+ the index to see if it really passes the <code class="literal">WHERE</code> condition or not.
+ To create such conditions, the support function must implement
+ the <code class="literal">SupportRequestIndexCondition</code> request type.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-c.html" title="38.10. C-Language Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xaggr.html" title="38.12. User-Defined Aggregates">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.10. C-Language Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.12. User-Defined Aggregates</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-overload.html b/doc/src/sgml/html/xfunc-overload.html
new file mode 100644
index 0000000..0556ad0
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-overload.html
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.6. Function Overloading</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions" /><link rel="next" href="xfunc-volatility.html" title="38.7. Function Volatility Categories" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.6. Function Overloading</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-OVERLOAD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.6. Function Overloading</h2></div></div></div><a id="id-1.8.3.9.2" class="indexterm"></a><p>
+ More than one function can be defined with the same SQL name, so long
+ as the arguments they take are different. In other words,
+ function names can be <em class="firstterm">overloaded</em>. Whether or not
+ you use it, this capability entails security precautions when calling
+ functions in databases where some users mistrust other users; see
+ <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>. When a query is executed, the server
+ will determine which function to call from the data types and the number
+ of the provided arguments. Overloading can also be used to simulate
+ functions with a variable number of arguments, up to a finite maximum
+ number.
+ </p><p>
+ When creating a family of overloaded functions, one should be
+ careful not to create ambiguities. For instance, given the
+ functions:
+</p><pre class="programlisting">
+CREATE FUNCTION test(int, real) RETURNS ...
+CREATE FUNCTION test(smallint, double precision) RETURNS ...
+</pre><p>
+ it is not immediately clear which function would be called with
+ some trivial input like <code class="literal">test(1, 1.5)</code>. The
+ currently implemented resolution rules are described in
+ <a class="xref" href="typeconv.html" title="Chapter 10. Type Conversion">Chapter 10</a>, but it is unwise to design a system that subtly
+ relies on this behavior.
+ </p><p>
+ A function that takes a single argument of a composite type should
+ generally not have the same name as any attribute (field) of that type.
+ Recall that <code class="literal"><em class="replaceable"><code>attribute</code></em>(<em class="replaceable"><code>table</code></em>)</code>
+ is considered equivalent
+ to <code class="literal"><em class="replaceable"><code>table</code></em>.<em class="replaceable"><code>attribute</code></em></code>.
+ In the case that there is an
+ ambiguity between a function on a composite type and an attribute of
+ the composite type, the attribute will always be used. It is possible
+ to override that choice by schema-qualifying the function name
+ (that is, <code class="literal"><em class="replaceable"><code>schema</code></em>.<em class="replaceable"><code>func</code></em>(<em class="replaceable"><code>table</code></em>)
+ </code>) but it's better to
+ avoid the problem by not choosing conflicting names.
+ </p><p>
+ Another possible conflict is between variadic and non-variadic functions.
+ For instance, it is possible to create both <code class="literal">foo(numeric)</code> and
+ <code class="literal">foo(VARIADIC numeric[])</code>. In this case it is unclear which one
+ should be matched to a call providing a single numeric argument, such as
+ <code class="literal">foo(10.1)</code>. The rule is that the function appearing
+ earlier in the search path is used, or if the two functions are in the
+ same schema, the non-variadic one is preferred.
+ </p><p>
+ When overloading C-language functions, there is an additional
+ constraint: The C name of each function in the family of
+ overloaded functions must be different from the C names of all
+ other functions, either internal or dynamically loaded. If this
+ rule is violated, the behavior is not portable. You might get a
+ run-time linker error, or one of the functions will get called
+ (usually the internal one). The alternative form of the
+ <code class="literal">AS</code> clause for the SQL <code class="command">CREATE
+ FUNCTION</code> command decouples the SQL function name from
+ the function name in the C source code. For instance:
+</p><pre class="programlisting">
+CREATE FUNCTION test(int) RETURNS int
+ AS '<em class="replaceable"><code>filename</code></em>', 'test_1arg'
+ LANGUAGE C;
+CREATE FUNCTION test(int, int) RETURNS int
+ AS '<em class="replaceable"><code>filename</code></em>', 'test_2arg'
+ LANGUAGE C;
+</pre><p>
+ The names of the C functions here reflect one of many possible conventions.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.7. Function Volatility Categories</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-pl.html b/doc/src/sgml/html/xfunc-pl.html
new file mode 100644
index 0000000..06656fe
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-pl.html
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.8. Procedural Language Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-volatility.html" title="38.7. Function Volatility Categories" /><link rel="next" href="xfunc-internal.html" title="38.9. Internal Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.8. Procedural Language Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-internal.html" title="38.9. Internal Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-PL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.8. Procedural Language Functions</h2></div></div></div><p>
+ <span class="productname">PostgreSQL</span> allows user-defined functions
+ to be written in other languages besides SQL and C. These other
+ languages are generically called <em class="firstterm">procedural
+ languages</em> (<acronym class="acronym">PL</acronym>s).
+ Procedural languages aren't built into the
+ <span class="productname">PostgreSQL</span> server; they are offered
+ by loadable modules.
+ See <a class="xref" href="xplang.html" title="Chapter 42. Procedural Languages">Chapter 42</a> and following chapters for more
+ information.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-internal.html" title="38.9. Internal Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.7. Function Volatility Categories </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.9. Internal Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-sql.html b/doc/src/sgml/html/xfunc-sql.html
new file mode 100644
index 0000000..d63b57b
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-sql.html
@@ -0,0 +1,1123 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.5. Query Language (SQL) Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xproc.html" title="38.4. User-Defined Procedures" /><link rel="next" href="xfunc-overload.html" title="38.6. Function Overloading" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xproc.html" title="38.4. User-Defined Procedures">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-overload.html" title="38.6. Function Overloading">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-SQL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS">38.5.1. Arguments for <acronym class="acronym">SQL</acronym> Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-BASE-FUNCTIONS">38.5.2. <acronym class="acronym">SQL</acronym> Functions on Base Types</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-COMPOSITE-FUNCTIONS">38.5.3. <acronym class="acronym">SQL</acronym> Functions on Composite Types</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS">38.5.4. <acronym class="acronym">SQL</acronym> Functions with Output Parameters</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-OUTPUT-PARAMETERS-PROC">38.5.5. <acronym class="acronym">SQL</acronym> Procedures with Output Parameters</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS">38.5.6. <acronym class="acronym">SQL</acronym> Functions with Variable Numbers of Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-PARAMETER-DEFAULTS">38.5.7. <acronym class="acronym">SQL</acronym> Functions with Default Values for Arguments</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-TABLE-FUNCTIONS">38.5.8. <acronym class="acronym">SQL</acronym> Functions as Table Sources</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-SET">38.5.9. <acronym class="acronym">SQL</acronym> Functions Returning Sets</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-FUNCTIONS-RETURNING-TABLE">38.5.10. <acronym class="acronym">SQL</acronym> Functions Returning <code class="literal">TABLE</code></a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#XFUNC-SQL-POLYMORPHIC-FUNCTIONS">38.5.11. Polymorphic <acronym class="acronym">SQL</acronym> Functions</a></span></dt><dt><span class="sect2"><a href="xfunc-sql.html#id-1.8.3.8.21">38.5.12. <acronym class="acronym">SQL</acronym> Functions with Collations</a></span></dt></dl></div><a id="id-1.8.3.8.2" class="indexterm"></a><p>
+ SQL functions execute an arbitrary list of SQL statements, returning
+ the result of the last query in the list.
+ In the simple (non-set)
+ case, the first row of the last query's result will be returned.
+ (Bear in mind that <span class="quote">“<span class="quote">the first row</span>”</span> of a multirow
+ result is not well-defined unless you use <code class="literal">ORDER BY</code>.)
+ If the last query happens
+ to return no rows at all, the null value will be returned.
+ </p><p>
+ Alternatively, an SQL function can be declared to return a set (that is,
+ multiple rows) by specifying the function's return type as <code class="literal">SETOF
+ <em class="replaceable"><code>sometype</code></em></code>, or equivalently by declaring it as
+ <code class="literal">RETURNS TABLE(<em class="replaceable"><code>columns</code></em>)</code>. In this case
+ all rows of the last query's result are returned. Further details appear
+ below.
+ </p><p>
+ The body of an SQL function must be a list of SQL
+ statements separated by semicolons. A semicolon after the last
+ statement is optional. Unless the function is declared to return
+ <code class="type">void</code>, the last statement must be a <code class="command">SELECT</code>,
+ or an <code class="command">INSERT</code>, <code class="command">UPDATE</code>, or <code class="command">DELETE</code>
+ that has a <code class="literal">RETURNING</code> clause.
+ </p><p>
+ Any collection of commands in the <acronym class="acronym">SQL</acronym>
+ language can be packaged together and defined as a function.
+ Besides <code class="command">SELECT</code> queries, the commands can include data
+ modification queries (<code class="command">INSERT</code>,
+ <code class="command">UPDATE</code>, <code class="command">DELETE</code>, and
+ <code class="command">MERGE</code>), as well as
+ other SQL commands. (You cannot use transaction control commands, e.g.,
+ <code class="command">COMMIT</code>, <code class="command">SAVEPOINT</code>, and some utility
+ commands, e.g., <code class="literal">VACUUM</code>, in <acronym class="acronym">SQL</acronym> functions.)
+ However, the final command
+ must be a <code class="command">SELECT</code> or have a <code class="literal">RETURNING</code>
+ clause that returns whatever is
+ specified as the function's return type. Alternatively, if you
+ want to define an SQL function that performs actions but has no
+ useful value to return, you can define it as returning <code class="type">void</code>.
+ For example, this function removes rows with negative salaries from
+ the <code class="literal">emp</code> table:
+
+</p><pre class="screen">
+CREATE FUNCTION clean_emp() RETURNS void AS '
+ DELETE FROM emp
+ WHERE salary &lt; 0;
+' LANGUAGE SQL;
+
+SELECT clean_emp();
+
+ clean_emp
+-----------
+
+(1 row)
+</pre><p>
+ </p><p>
+ You can also write this as a procedure, thus avoiding the issue of the
+ return type. For example:
+</p><pre class="screen">
+CREATE PROCEDURE clean_emp() AS '
+ DELETE FROM emp
+ WHERE salary &lt; 0;
+' LANGUAGE SQL;
+
+CALL clean_emp();
+</pre><p>
+ In simple cases like this, the difference between a function returning
+ <code class="type">void</code> and a procedure is mostly stylistic. However,
+ procedures offer additional functionality such as transaction control
+ that is not available in functions. Also, procedures are SQL standard
+ whereas returning <code class="type">void</code> is a PostgreSQL extension.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The entire body of an SQL function is parsed before any of it is
+ executed. While an SQL function can contain commands that alter
+ the system catalogs (e.g., <code class="command">CREATE TABLE</code>), the effects
+ of such commands will not be visible during parse analysis of
+ later commands in the function. Thus, for example,
+ <code class="literal">CREATE TABLE foo (...); INSERT INTO foo VALUES(...);</code>
+ will not work as desired if packaged up into a single SQL function,
+ since <code class="structname">foo</code> won't exist yet when the <code class="command">INSERT</code>
+ command is parsed. It's recommended to use <span class="application">PL/pgSQL</span>
+ instead of an SQL function in this type of situation.
+ </p></div><p>
+ The syntax of the <code class="command">CREATE FUNCTION</code> command requires
+ the function body to be written as a string constant. It is usually
+ most convenient to use dollar quoting (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING" title="4.1.2.4. Dollar-Quoted String Constants">Section 4.1.2.4</a>) for the string constant.
+ If you choose to use regular single-quoted string constant syntax,
+ you must double single quote marks (<code class="literal">'</code>) and backslashes
+ (<code class="literal">\</code>) (assuming escape string syntax) in the body of
+ the function (see <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a>).
+ </p><div class="sect2" id="XFUNC-SQL-FUNCTION-ARGUMENTS"><div class="titlepage"><div><div><h3 class="title">38.5.1. Arguments for <acronym class="acronym">SQL</acronym> Functions</h3></div></div></div><a id="id-1.8.3.8.10.2" class="indexterm"></a><p>
+ Arguments of an SQL function can be referenced in the function
+ body using either names or numbers. Examples of both methods appear
+ below.
+ </p><p>
+ To use a name, declare the function argument as having a name, and
+ then just write that name in the function body. If the argument name
+ is the same as any column name in the current SQL command within the
+ function, the column name will take precedence. To override this,
+ qualify the argument name with the name of the function itself, that is
+ <code class="literal"><em class="replaceable"><code>function_name</code></em>.<em class="replaceable"><code>argument_name</code></em></code>.
+ (If this would conflict with a qualified column name, again the column
+ name wins. You can avoid the ambiguity by choosing a different alias for
+ the table within the SQL command.)
+ </p><p>
+ In the older numeric approach, arguments are referenced using the syntax
+ <code class="literal">$<em class="replaceable"><code>n</code></em></code>: <code class="literal">$1</code> refers to the first input
+ argument, <code class="literal">$2</code> to the second, and so on. This will work
+ whether or not the particular argument was declared with a name.
+ </p><p>
+ If an argument is of a composite type, then the dot notation,
+ e.g., <code class="literal"><em class="replaceable"><code>argname</code></em>.<em class="replaceable"><code>fieldname</code></em></code> or
+ <code class="literal">$1.<em class="replaceable"><code>fieldname</code></em></code>, can be used to access attributes of the
+ argument. Again, you might need to qualify the argument's name with the
+ function name to make the form with an argument name unambiguous.
+ </p><p>
+ SQL function arguments can only be used as data values,
+ not as identifiers. Thus for example this is reasonable:
+</p><pre class="programlisting">
+INSERT INTO mytable VALUES ($1);
+</pre><p>
+but this will not work:
+</p><pre class="programlisting">
+INSERT INTO $1 VALUES (42);
+</pre><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The ability to use names to reference SQL function arguments was added
+ in <span class="productname">PostgreSQL</span> 9.2. Functions to be used in
+ older servers must use the <code class="literal">$<em class="replaceable"><code>n</code></em></code> notation.
+ </p></div></div><div class="sect2" id="XFUNC-SQL-BASE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.5.2. <acronym class="acronym">SQL</acronym> Functions on Base Types</h3></div></div></div><p>
+ The simplest possible <acronym class="acronym">SQL</acronym> function has no arguments and
+ simply returns a base type, such as <code class="type">integer</code>:
+
+</p><pre class="screen">
+CREATE FUNCTION one() RETURNS integer AS $$
+ SELECT 1 AS result;
+$$ LANGUAGE SQL;
+
+-- Alternative syntax for string literal:
+CREATE FUNCTION one() RETURNS integer AS '
+ SELECT 1 AS result;
+' LANGUAGE SQL;
+
+SELECT one();
+
+ one
+-----
+ 1
+</pre><p>
+ </p><p>
+ Notice that we defined a column alias within the function body for the result of the function
+ (with the name <code class="literal">result</code>), but this column alias is not visible
+ outside the function. Hence, the result is labeled <code class="literal">one</code>
+ instead of <code class="literal">result</code>.
+ </p><p>
+ It is almost as easy to define <acronym class="acronym">SQL</acronym> functions
+ that take base types as arguments:
+
+</p><pre class="screen">
+CREATE FUNCTION add_em(x integer, y integer) RETURNS integer AS $$
+ SELECT x + y;
+$$ LANGUAGE SQL;
+
+SELECT add_em(1, 2) AS answer;
+
+ answer
+--------
+ 3
+</pre><p>
+ </p><p>
+ Alternatively, we could dispense with names for the arguments and
+ use numbers:
+
+</p><pre class="screen">
+CREATE FUNCTION add_em(integer, integer) RETURNS integer AS $$
+ SELECT $1 + $2;
+$$ LANGUAGE SQL;
+
+SELECT add_em(1, 2) AS answer;
+
+ answer
+--------
+ 3
+</pre><p>
+ </p><p>
+ Here is a more useful function, which might be used to debit a
+ bank account:
+
+</p><pre class="programlisting">
+CREATE FUNCTION tf1 (accountno integer, debit numeric) RETURNS numeric AS $$
+ UPDATE bank
+ SET balance = balance - debit
+ WHERE accountno = tf1.accountno;
+ SELECT 1;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ A user could execute this function to debit account 17 by $100.00 as
+ follows:
+
+</p><pre class="programlisting">
+SELECT tf1(17, 100.0);
+</pre><p>
+ </p><p>
+ In this example, we chose the name <code class="literal">accountno</code> for the first
+ argument, but this is the same as the name of a column in the
+ <code class="literal">bank</code> table. Within the <code class="command">UPDATE</code> command,
+ <code class="literal">accountno</code> refers to the column <code class="literal">bank.accountno</code>,
+ so <code class="literal">tf1.accountno</code> must be used to refer to the argument.
+ We could of course avoid this by using a different name for the argument.
+ </p><p>
+ In practice one would probably like a more useful result from the
+ function than a constant 1, so a more likely definition
+ is:
+
+</p><pre class="programlisting">
+CREATE FUNCTION tf1 (accountno integer, debit numeric) RETURNS numeric AS $$
+ UPDATE bank
+ SET balance = balance - debit
+ WHERE accountno = tf1.accountno;
+ SELECT balance FROM bank WHERE accountno = tf1.accountno;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ which adjusts the balance and returns the new balance.
+ The same thing could be done in one command using <code class="literal">RETURNING</code>:
+
+</p><pre class="programlisting">
+CREATE FUNCTION tf1 (accountno integer, debit numeric) RETURNS numeric AS $$
+ UPDATE bank
+ SET balance = balance - debit
+ WHERE accountno = tf1.accountno
+ RETURNING balance;
+$$ LANGUAGE SQL;
+</pre><p>
+ </p><p>
+ If the final <code class="literal">SELECT</code> or <code class="literal">RETURNING</code>
+ clause in an <acronym class="acronym">SQL</acronym> function does not return exactly
+ the function's declared result
+ type, <span class="productname">PostgreSQL</span> will automatically cast
+ the value to the required type, if that is possible with an implicit
+ or assignment cast. Otherwise, you must write an explicit cast.
+ For example, suppose we wanted the
+ previous <code class="function">add_em</code> function to return
+ type <code class="type">float8</code> instead. It's sufficient to write
+
+</p><pre class="programlisting">
+CREATE FUNCTION add_em(integer, integer) RETURNS float8 AS $$
+ SELECT $1 + $2;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ since the <code class="type">integer</code> sum can be implicitly cast
+ to <code class="type">float8</code>.
+ (See <a class="xref" href="typeconv.html" title="Chapter 10. Type Conversion">Chapter 10</a> or <a class="xref" href="sql-createcast.html" title="CREATE CAST"><span class="refentrytitle">CREATE CAST</span></a>
+ for more about casts.)
+ </p></div><div class="sect2" id="XFUNC-SQL-COMPOSITE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.5.3. <acronym class="acronym">SQL</acronym> Functions on Composite Types</h3></div></div></div><p>
+ When writing functions with arguments of composite types, we must not
+ only specify which argument we want but also the desired attribute
+ (field) of that argument. For example, suppose that
+ <code class="type">emp</code> is a table containing employee data, and therefore
+ also the name of the composite type of each row of the table. Here
+ is a function <code class="function">double_salary</code> that computes what someone's
+ salary would be if it were doubled:
+
+</p><pre class="screen">
+CREATE TABLE emp (
+ name text,
+ salary numeric,
+ age integer,
+ cubicle point
+);
+
+INSERT INTO emp VALUES ('Bill', 4200, 45, '(2,1)');
+
+CREATE FUNCTION double_salary(emp) RETURNS numeric AS $$
+ SELECT $1.salary * 2 AS salary;
+$$ LANGUAGE SQL;
+
+SELECT name, double_salary(emp.*) AS dream
+ FROM emp
+ WHERE emp.cubicle ~= point '(2,1)';
+
+ name | dream
+------+-------
+ Bill | 8400
+</pre><p>
+ </p><p>
+ Notice the use of the syntax <code class="literal">$1.salary</code>
+ to select one field of the argument row value. Also notice
+ how the calling <code class="command">SELECT</code> command
+ uses <em class="replaceable"><code>table_name</code></em><code class="literal">.*</code> to select
+ the entire current row of a table as a composite value. The table
+ row can alternatively be referenced using just the table name,
+ like this:
+</p><pre class="screen">
+SELECT name, double_salary(emp) AS dream
+ FROM emp
+ WHERE emp.cubicle ~= point '(2,1)';
+</pre><p>
+ but this usage is deprecated since it's easy to get confused.
+ (See <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a> for details about these
+ two notations for the composite value of a table row.)
+ </p><p>
+ Sometimes it is handy to construct a composite argument value
+ on-the-fly. This can be done with the <code class="literal">ROW</code> construct.
+ For example, we could adjust the data being passed to the function:
+</p><pre class="screen">
+SELECT name, double_salary(ROW(name, salary*1.1, age, cubicle)) AS dream
+ FROM emp;
+</pre><p>
+ </p><p>
+ It is also possible to build a function that returns a composite type.
+ This is an example of a function
+ that returns a single <code class="type">emp</code> row:
+
+</p><pre class="programlisting">
+CREATE FUNCTION new_emp() RETURNS emp AS $$
+ SELECT text 'None' AS name,
+ 1000.0 AS salary,
+ 25 AS age,
+ point '(2,2)' AS cubicle;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ In this example we have specified each of the attributes
+ with a constant value, but any computation
+ could have been substituted for these constants.
+ </p><p>
+ Note two important things about defining the function:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The select list order in the query must be exactly the same as
+ that in which the columns appear in the composite type.
+ (Naming the columns, as we did above,
+ is irrelevant to the system.)
+ </p></li><li class="listitem"><p>
+ We must ensure each expression's type can be cast to that of
+ the corresponding column of the composite type.
+ Otherwise we'll get errors like this:
+</p><pre class="screen">
+<code class="computeroutput">
+ERROR: return type mismatch in function declared to return emp
+DETAIL: Final statement returns text instead of point at column 4.
+</code>
+</pre><p>
+ As with the base-type case, the system will not insert explicit
+ casts automatically, only implicit or assignment casts.
+ </p></li></ul></div><p>
+ </p><p>
+ A different way to define the same function is:
+
+</p><pre class="programlisting">
+CREATE FUNCTION new_emp() RETURNS emp AS $$
+ SELECT ROW('None', 1000.0, 25, '(2,2)')::emp;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ Here we wrote a <code class="command">SELECT</code> that returns just a single
+ column of the correct composite type. This isn't really better
+ in this situation, but it is a handy alternative in some cases
+ — for example, if we need to compute the result by calling
+ another function that returns the desired composite value.
+ Another example is that if we are trying to write a function that
+ returns a domain over composite, rather than a plain composite type,
+ it is always necessary to write it as returning a single column,
+ since there is no way to cause a coercion of the whole row result.
+ </p><p>
+ We could call this function directly either by using it in
+ a value expression:
+
+</p><pre class="screen">
+SELECT new_emp();
+
+ new_emp
+--------------------------
+ (None,1000.0,25,"(2,2)")
+</pre><p>
+
+ or by calling it as a table function:
+
+</p><pre class="screen">
+SELECT * FROM new_emp();
+
+ name | salary | age | cubicle
+------+--------+-----+---------
+ None | 1000.0 | 25 | (2,2)
+</pre><p>
+
+ The second way is described more fully in <a class="xref" href="xfunc-sql.html#XFUNC-SQL-TABLE-FUNCTIONS" title="38.5.8. SQL Functions as Table Sources">Section 38.5.8</a>.
+ </p><p>
+ When you use a function that returns a composite type,
+ you might want only one field (attribute) from its result.
+ You can do that with syntax like this:
+
+</p><pre class="screen">
+SELECT (new_emp()).name;
+
+ name
+------
+ None
+</pre><p>
+
+ The extra parentheses are needed to keep the parser from getting
+ confused. If you try to do it without them, you get something like this:
+
+</p><pre class="screen">
+SELECT new_emp().name;
+ERROR: syntax error at or near "."
+LINE 1: SELECT new_emp().name;
+ ^
+</pre><p>
+ </p><p>
+ Another option is to use functional notation for extracting an attribute:
+
+</p><pre class="screen">
+SELECT name(new_emp());
+
+ name
+------
+ None
+</pre><p>
+
+ As explained in <a class="xref" href="rowtypes.html#ROWTYPES-USAGE" title="8.16.5. Using Composite Types in Queries">Section 8.16.5</a>, the field notation and
+ functional notation are equivalent.
+ </p><p>
+ Another way to use a function returning a composite type is to pass the
+ result to another function that accepts the correct row type as input:
+
+</p><pre class="screen">
+CREATE FUNCTION getname(emp) RETURNS text AS $$
+ SELECT $1.name;
+$$ LANGUAGE SQL;
+
+SELECT getname(new_emp());
+ getname
+---------
+ None
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="XFUNC-OUTPUT-PARAMETERS"><div class="titlepage"><div><div><h3 class="title">38.5.4. <acronym class="acronym">SQL</acronym> Functions with Output Parameters</h3></div></div></div><a id="id-1.8.3.8.13.2" class="indexterm"></a><p>
+ An alternative way of describing a function's results is to define it
+ with <em class="firstterm">output parameters</em>, as in this example:
+
+</p><pre class="screen">
+CREATE FUNCTION add_em (IN x int, IN y int, OUT sum int)
+AS 'SELECT x + y'
+LANGUAGE SQL;
+
+SELECT add_em(3,7);
+ add_em
+--------
+ 10
+(1 row)
+</pre><p>
+
+ This is not essentially different from the version of <code class="literal">add_em</code>
+ shown in <a class="xref" href="xfunc-sql.html#XFUNC-SQL-BASE-FUNCTIONS" title="38.5.2. SQL Functions on Base Types">Section 38.5.2</a>. The real value of
+ output parameters is that they provide a convenient way of defining
+ functions that return several columns. For example,
+
+</p><pre class="screen">
+CREATE FUNCTION sum_n_product (x int, y int, OUT sum int, OUT product int)
+AS 'SELECT x + y, x * y'
+LANGUAGE SQL;
+
+ SELECT * FROM sum_n_product(11,42);
+ sum | product
+-----+---------
+ 53 | 462
+(1 row)
+</pre><p>
+
+ What has essentially happened here is that we have created an anonymous
+ composite type for the result of the function. The above example has
+ the same end result as
+
+</p><pre class="screen">
+CREATE TYPE sum_prod AS (sum int, product int);
+
+CREATE FUNCTION sum_n_product (int, int) RETURNS sum_prod
+AS 'SELECT $1 + $2, $1 * $2'
+LANGUAGE SQL;
+</pre><p>
+
+ but not having to bother with the separate composite type definition
+ is often handy. Notice that the names attached to the output parameters
+ are not just decoration, but determine the column names of the anonymous
+ composite type. (If you omit a name for an output parameter, the
+ system will choose a name on its own.)
+ </p><p>
+ Notice that output parameters are not included in the calling argument
+ list when invoking such a function from SQL. This is because
+ <span class="productname">PostgreSQL</span> considers only the input
+ parameters to define the function's calling signature. That means
+ also that only the input parameters matter when referencing the function
+ for purposes such as dropping it. We could drop the above function
+ with either of
+
+</p><pre class="screen">
+DROP FUNCTION sum_n_product (x int, y int, OUT sum int, OUT product int);
+DROP FUNCTION sum_n_product (int, int);
+</pre><p>
+ </p><p>
+ Parameters can be marked as <code class="literal">IN</code> (the default),
+ <code class="literal">OUT</code>, <code class="literal">INOUT</code>, or <code class="literal">VARIADIC</code>.
+ An <code class="literal">INOUT</code>
+ parameter serves as both an input parameter (part of the calling
+ argument list) and an output parameter (part of the result record type).
+ <code class="literal">VARIADIC</code> parameters are input parameters, but are treated
+ specially as described below.
+ </p></div><div class="sect2" id="XFUNC-OUTPUT-PARAMETERS-PROC"><div class="titlepage"><div><div><h3 class="title">38.5.5. <acronym class="acronym">SQL</acronym> Procedures with Output Parameters</h3></div></div></div><a id="id-1.8.3.8.14.2" class="indexterm"></a><p>
+ Output parameters are also supported in procedures, but they work a bit
+ differently from functions. In <code class="command">CALL</code> commands,
+ output parameters must be included in the argument list.
+ For example, the bank account debiting routine from earlier could be
+ written like this:
+</p><pre class="programlisting">
+CREATE PROCEDURE tp1 (accountno integer, debit numeric, OUT new_balance numeric) AS $$
+ UPDATE bank
+ SET balance = balance - debit
+ WHERE accountno = tp1.accountno
+ RETURNING balance;
+$$ LANGUAGE SQL;
+</pre><p>
+ To call this procedure, an argument matching the <code class="literal">OUT</code>
+ parameter must be included. It's customary to write
+ <code class="literal">NULL</code>:
+</p><pre class="programlisting">
+CALL tp1(17, 100.0, NULL);
+</pre><p>
+ If you write something else, it must be an expression that is implicitly
+ coercible to the declared type of the parameter, just as for input
+ parameters. Note however that such an expression will not be evaluated.
+ </p><p>
+ When calling a procedure from <span class="application">PL/pgSQL</span>,
+ instead of writing <code class="literal">NULL</code> you must write a variable
+ that will receive the procedure's output. See <a class="xref" href="plpgsql-control-structures.html#PLPGSQL-STATEMENTS-CALLING-PROCEDURE" title="43.6.3. Calling a Procedure">Section 43.6.3</a> for details.
+ </p></div><div class="sect2" id="XFUNC-SQL-VARIADIC-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.5.6. <acronym class="acronym">SQL</acronym> Functions with Variable Numbers of Arguments</h3></div></div></div><a id="id-1.8.3.8.15.2" class="indexterm"></a><a id="id-1.8.3.8.15.3" class="indexterm"></a><p>
+ <acronym class="acronym">SQL</acronym> functions can be declared to accept
+ variable numbers of arguments, so long as all the <span class="quote">“<span class="quote">optional</span>”</span>
+ arguments are of the same data type. The optional arguments will be
+ passed to the function as an array. The function is declared by
+ marking the last parameter as <code class="literal">VARIADIC</code>; this parameter
+ must be declared as being of an array type. For example:
+
+</p><pre class="screen">
+CREATE FUNCTION mleast(VARIADIC arr numeric[]) RETURNS numeric AS $$
+ SELECT min($1[i]) FROM generate_subscripts($1, 1) g(i);
+$$ LANGUAGE SQL;
+
+SELECT mleast(10, -1, 5, 4.4);
+ mleast
+--------
+ -1
+(1 row)
+</pre><p>
+
+ Effectively, all the actual arguments at or beyond the
+ <code class="literal">VARIADIC</code> position are gathered up into a one-dimensional
+ array, as if you had written
+
+</p><pre class="screen">
+SELECT mleast(ARRAY[10, -1, 5, 4.4]); -- doesn't work
+</pre><p>
+
+ You can't actually write that, though — or at least, it will
+ not match this function definition. A parameter marked
+ <code class="literal">VARIADIC</code> matches one or more occurrences of its element
+ type, not of its own type.
+ </p><p>
+ Sometimes it is useful to be able to pass an already-constructed array
+ to a variadic function; this is particularly handy when one variadic
+ function wants to pass on its array parameter to another one. Also,
+ this is the only secure way to call a variadic function found in a schema
+ that permits untrusted users to create objects; see
+ <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>. You can do this by
+ specifying <code class="literal">VARIADIC</code> in the call:
+
+</p><pre class="screen">
+SELECT mleast(VARIADIC ARRAY[10, -1, 5, 4.4]);
+</pre><p>
+
+ This prevents expansion of the function's variadic parameter into its
+ element type, thereby allowing the array argument value to match
+ normally. <code class="literal">VARIADIC</code> can only be attached to the last
+ actual argument of a function call.
+ </p><p>
+ Specifying <code class="literal">VARIADIC</code> in the call is also the only way to
+ pass an empty array to a variadic function, for example:
+
+</p><pre class="screen">
+SELECT mleast(VARIADIC ARRAY[]::numeric[]);
+</pre><p>
+
+ Simply writing <code class="literal">SELECT mleast()</code> does not work because a
+ variadic parameter must match at least one actual argument.
+ (You could define a second function also named <code class="literal">mleast</code>,
+ with no parameters, if you wanted to allow such calls.)
+ </p><p>
+ The array element parameters generated from a variadic parameter are
+ treated as not having any names of their own. This means it is not
+ possible to call a variadic function using named arguments (<a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a>), except when you specify
+ <code class="literal">VARIADIC</code>. For example, this will work:
+
+</p><pre class="screen">
+SELECT mleast(VARIADIC arr =&gt; ARRAY[10, -1, 5, 4.4]);
+</pre><p>
+
+ but not these:
+
+</p><pre class="screen">
+SELECT mleast(arr =&gt; 10);
+SELECT mleast(arr =&gt; ARRAY[10, -1, 5, 4.4]);
+</pre><p>
+ </p></div><div class="sect2" id="XFUNC-SQL-PARAMETER-DEFAULTS"><div class="titlepage"><div><div><h3 class="title">38.5.7. <acronym class="acronym">SQL</acronym> Functions with Default Values for Arguments</h3></div></div></div><a id="id-1.8.3.8.16.2" class="indexterm"></a><p>
+ Functions can be declared with default values for some or all input
+ arguments. The default values are inserted whenever the function is
+ called with insufficiently many actual arguments. Since arguments
+ can only be omitted from the end of the actual argument list, all
+ parameters after a parameter with a default value have to have
+ default values as well. (Although the use of named argument notation
+ could allow this restriction to be relaxed, it's still enforced so that
+ positional argument notation works sensibly.) Whether or not you use it,
+ this capability creates a need for precautions when calling functions in
+ databases where some users mistrust other users; see
+ <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>.
+ </p><p>
+ For example:
+</p><pre class="screen">
+CREATE FUNCTION foo(a int, b int DEFAULT 2, c int DEFAULT 3)
+RETURNS int
+LANGUAGE SQL
+AS $$
+ SELECT $1 + $2 + $3;
+$$;
+
+SELECT foo(10, 20, 30);
+ foo
+-----
+ 60
+(1 row)
+
+SELECT foo(10, 20);
+ foo
+-----
+ 33
+(1 row)
+
+SELECT foo(10);
+ foo
+-----
+ 15
+(1 row)
+
+SELECT foo(); -- fails since there is no default for the first argument
+ERROR: function foo() does not exist
+</pre><p>
+ The <code class="literal">=</code> sign can also be used in place of the
+ key word <code class="literal">DEFAULT</code>.
+ </p></div><div class="sect2" id="XFUNC-SQL-TABLE-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.5.8. <acronym class="acronym">SQL</acronym> Functions as Table Sources</h3></div></div></div><p>
+ All SQL functions can be used in the <code class="literal">FROM</code> clause of a query,
+ but it is particularly useful for functions returning composite types.
+ If the function is defined to return a base type, the table function
+ produces a one-column table. If the function is defined to return
+ a composite type, the table function produces a column for each attribute
+ of the composite type.
+ </p><p>
+ Here is an example:
+
+</p><pre class="screen">
+CREATE TABLE foo (fooid int, foosubid int, fooname text);
+INSERT INTO foo VALUES (1, 1, 'Joe');
+INSERT INTO foo VALUES (1, 2, 'Ed');
+INSERT INTO foo VALUES (2, 1, 'Mary');
+
+CREATE FUNCTION getfoo(int) RETURNS foo AS $$
+ SELECT * FROM foo WHERE fooid = $1;
+$$ LANGUAGE SQL;
+
+SELECT *, upper(fooname) FROM getfoo(1) AS t1;
+
+ fooid | foosubid | fooname | upper
+-------+----------+---------+-------
+ 1 | 1 | Joe | JOE
+(1 row)
+</pre><p>
+
+ As the example shows, we can work with the columns of the function's
+ result just the same as if they were columns of a regular table.
+ </p><p>
+ Note that we only got one row out of the function. This is because
+ we did not use <code class="literal">SETOF</code>. That is described in the next section.
+ </p></div><div class="sect2" id="XFUNC-SQL-FUNCTIONS-RETURNING-SET"><div class="titlepage"><div><div><h3 class="title">38.5.9. <acronym class="acronym">SQL</acronym> Functions Returning Sets</h3></div></div></div><a id="id-1.8.3.8.18.2" class="indexterm"></a><p>
+ When an SQL function is declared as returning <code class="literal">SETOF
+ <em class="replaceable"><code>sometype</code></em></code>, the function's final
+ query is executed to completion, and each row it
+ outputs is returned as an element of the result set.
+ </p><p>
+ This feature is normally used when calling the function in the <code class="literal">FROM</code>
+ clause. In this case each row returned by the function becomes
+ a row of the table seen by the query. For example, assume that
+ table <code class="literal">foo</code> has the same contents as above, and we say:
+
+</p><pre class="programlisting">
+CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS $$
+ SELECT * FROM foo WHERE fooid = $1;
+$$ LANGUAGE SQL;
+
+SELECT * FROM getfoo(1) AS t1;
+</pre><p>
+
+ Then we would get:
+</p><pre class="screen">
+ fooid | foosubid | fooname
+-------+----------+---------
+ 1 | 1 | Joe
+ 1 | 2 | Ed
+(2 rows)
+</pre><p>
+ </p><p>
+ It is also possible to return multiple rows with the columns defined by
+ output parameters, like this:
+
+</p><pre class="programlisting">
+CREATE TABLE tab (y int, z int);
+INSERT INTO tab VALUES (1, 2), (3, 4), (5, 6), (7, 8);
+
+CREATE FUNCTION sum_n_product_with_tab (x int, OUT sum int, OUT product int)
+RETURNS SETOF record
+AS $$
+ SELECT $1 + tab.y, $1 * tab.y FROM tab;
+$$ LANGUAGE SQL;
+
+SELECT * FROM sum_n_product_with_tab(10);
+ sum | product
+-----+---------
+ 11 | 10
+ 13 | 30
+ 15 | 50
+ 17 | 70
+(4 rows)
+</pre><p>
+
+ The key point here is that you must write <code class="literal">RETURNS SETOF record</code>
+ to indicate that the function returns multiple rows instead of just one.
+ If there is only one output parameter, write that parameter's type
+ instead of <code class="type">record</code>.
+ </p><p>
+ It is frequently useful to construct a query's result by invoking a
+ set-returning function multiple times, with the parameters for each
+ invocation coming from successive rows of a table or subquery. The
+ preferred way to do this is to use the <code class="literal">LATERAL</code> key word,
+ which is described in <a class="xref" href="queries-table-expressions.html#QUERIES-LATERAL" title="7.2.1.5. LATERAL Subqueries">Section 7.2.1.5</a>.
+ Here is an example using a set-returning function to enumerate
+ elements of a tree structure:
+
+</p><pre class="screen">
+SELECT * FROM nodes;
+ name | parent
+-----------+--------
+ Top |
+ Child1 | Top
+ Child2 | Top
+ Child3 | Top
+ SubChild1 | Child1
+ SubChild2 | Child1
+(6 rows)
+
+CREATE FUNCTION listchildren(text) RETURNS SETOF text AS $$
+ SELECT name FROM nodes WHERE parent = $1
+$$ LANGUAGE SQL STABLE;
+
+SELECT * FROM listchildren('Top');
+ listchildren
+--------------
+ Child1
+ Child2
+ Child3
+(3 rows)
+
+SELECT name, child FROM nodes, LATERAL listchildren(name) AS child;
+ name | child
+--------+-----------
+ Top | Child1
+ Top | Child2
+ Top | Child3
+ Child1 | SubChild1
+ Child1 | SubChild2
+(5 rows)
+</pre><p>
+
+ This example does not do anything that we couldn't have done with a
+ simple join, but in more complex calculations the option to put
+ some of the work into a function can be quite convenient.
+ </p><p>
+ Functions returning sets can also be called in the select list
+ of a query. For each row that the query
+ generates by itself, the set-returning function is invoked, and an output
+ row is generated for each element of the function's result set.
+ The previous example could also be done with queries like
+ these:
+
+</p><pre class="screen">
+SELECT listchildren('Top');
+ listchildren
+--------------
+ Child1
+ Child2
+ Child3
+(3 rows)
+
+SELECT name, listchildren(name) FROM nodes;
+ name | listchildren
+--------+--------------
+ Top | Child1
+ Top | Child2
+ Top | Child3
+ Child1 | SubChild1
+ Child1 | SubChild2
+(5 rows)
+</pre><p>
+
+ In the last <code class="command">SELECT</code>,
+ notice that no output row appears for <code class="literal">Child2</code>, <code class="literal">Child3</code>, etc.
+ This happens because <code class="function">listchildren</code> returns an empty set
+ for those arguments, so no result rows are generated. This is the same
+ behavior as we got from an inner join to the function result when using
+ the <code class="literal">LATERAL</code> syntax.
+ </p><p>
+ <span class="productname">PostgreSQL</span>'s behavior for a set-returning function in a
+ query's select list is almost exactly the same as if the set-returning
+ function had been written in a <code class="literal">LATERAL FROM</code>-clause item
+ instead. For example,
+</p><pre class="programlisting">
+SELECT x, generate_series(1,5) AS g FROM tab;
+</pre><p>
+ is almost equivalent to
+</p><pre class="programlisting">
+SELECT x, g FROM tab, LATERAL generate_series(1,5) AS g;
+</pre><p>
+ It would be exactly the same, except that in this specific example,
+ the planner could choose to put <code class="structname">g</code> on the outside of the
+ nested-loop join, since <code class="structname">g</code> has no actual lateral dependency
+ on <code class="structname">tab</code>. That would result in a different output row
+ order. Set-returning functions in the select list are always evaluated
+ as though they are on the inside of a nested-loop join with the rest of
+ the <code class="literal">FROM</code> clause, so that the function(s) are run to
+ completion before the next row from the <code class="literal">FROM</code> clause is
+ considered.
+ </p><p>
+ If there is more than one set-returning function in the query's select
+ list, the behavior is similar to what you get from putting the functions
+ into a single <code class="literal">LATERAL ROWS FROM( ... )</code> <code class="literal">FROM</code>-clause
+ item. For each row from the underlying query, there is an output row
+ using the first result from each function, then an output row using the
+ second result, and so on. If some of the set-returning functions
+ produce fewer outputs than others, null values are substituted for the
+ missing data, so that the total number of rows emitted for one
+ underlying row is the same as for the set-returning function that
+ produced the most outputs. Thus the set-returning functions
+ run <span class="quote">“<span class="quote">in lockstep</span>”</span> until they are all exhausted, and then
+ execution continues with the next underlying row.
+ </p><p>
+ Set-returning functions can be nested in a select list, although that is
+ not allowed in <code class="literal">FROM</code>-clause items. In such cases, each level
+ of nesting is treated separately, as though it were
+ a separate <code class="literal">LATERAL ROWS FROM( ... )</code> item. For example, in
+</p><pre class="programlisting">
+SELECT srf1(srf2(x), srf3(y)), srf4(srf5(z)) FROM tab;
+</pre><p>
+ the set-returning functions <code class="function">srf2</code>, <code class="function">srf3</code>,
+ and <code class="function">srf5</code> would be run in lockstep for each row
+ of <code class="structname">tab</code>, and then <code class="function">srf1</code> and <code class="function">srf4</code>
+ would be applied in lockstep to each row produced by the lower
+ functions.
+ </p><p>
+ Set-returning functions cannot be used within conditional-evaluation
+ constructs, such as <code class="literal">CASE</code> or <code class="literal">COALESCE</code>. For
+ example, consider
+</p><pre class="programlisting">
+SELECT x, CASE WHEN x &gt; 0 THEN generate_series(1, 5) ELSE 0 END FROM tab;
+</pre><p>
+ It might seem that this should produce five repetitions of input rows
+ that have <code class="literal">x &gt; 0</code>, and a single repetition of those that do
+ not; but actually, because <code class="function">generate_series(1, 5)</code> would be
+ run in an implicit <code class="literal">LATERAL FROM</code> item before
+ the <code class="literal">CASE</code> expression is ever evaluated, it would produce five
+ repetitions of every input row. To reduce confusion, such cases produce
+ a parse-time error instead.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If a function's last command is <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
+ or <code class="command">DELETE</code> with <code class="literal">RETURNING</code>, that command will
+ always be executed to completion, even if the function is not declared
+ with <code class="literal">SETOF</code> or the calling query does not fetch all the
+ result rows. Any extra rows produced by the <code class="literal">RETURNING</code>
+ clause are silently dropped, but the commanded table modifications
+ still happen (and are all completed before returning from the function).
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ Before <span class="productname">PostgreSQL</span> 10, putting more than one
+ set-returning function in the same select list did not behave very
+ sensibly unless they always produced equal numbers of rows. Otherwise,
+ what you got was a number of output rows equal to the least common
+ multiple of the numbers of rows produced by the set-returning
+ functions. Also, nested set-returning functions did not work as
+ described above; instead, a set-returning function could have at most
+ one set-returning argument, and each nest of set-returning functions
+ was run independently. Also, conditional execution (set-returning
+ functions inside <code class="literal">CASE</code> etc.) was previously allowed,
+ complicating things even more.
+ Use of the <code class="literal">LATERAL</code> syntax is recommended when writing
+ queries that need to work in older <span class="productname">PostgreSQL</span> versions,
+ because that will give consistent results across different versions.
+ If you have a query that is relying on conditional execution of a
+ set-returning function, you may be able to fix it by moving the
+ conditional test into a custom set-returning function. For example,
+</p><pre class="programlisting">
+SELECT x, CASE WHEN y &gt; 0 THEN generate_series(1, z) ELSE 5 END FROM tab;
+</pre><p>
+ could become
+</p><pre class="programlisting">
+CREATE FUNCTION case_generate_series(cond bool, start int, fin int, els int)
+ RETURNS SETOF int AS $$
+BEGIN
+ IF cond THEN
+ RETURN QUERY SELECT generate_series(start, fin);
+ ELSE
+ RETURN QUERY SELECT els;
+ END IF;
+END$$ LANGUAGE plpgsql;
+
+SELECT x, case_generate_series(y &gt; 0, 1, z, 5) FROM tab;
+</pre><p>
+ This formulation will work the same in all versions
+ of <span class="productname">PostgreSQL</span>.
+ </p></div></div><div class="sect2" id="XFUNC-SQL-FUNCTIONS-RETURNING-TABLE"><div class="titlepage"><div><div><h3 class="title">38.5.10. <acronym class="acronym">SQL</acronym> Functions Returning <code class="literal">TABLE</code></h3></div></div></div><a id="id-1.8.3.8.19.2" class="indexterm"></a><p>
+ There is another way to declare a function as returning a set,
+ which is to use the syntax
+ <code class="literal">RETURNS TABLE(<em class="replaceable"><code>columns</code></em>)</code>.
+ This is equivalent to using one or more <code class="literal">OUT</code> parameters plus
+ marking the function as returning <code class="literal">SETOF record</code> (or
+ <code class="literal">SETOF</code> a single output parameter's type, as appropriate).
+ This notation is specified in recent versions of the SQL standard, and
+ thus may be more portable than using <code class="literal">SETOF</code>.
+ </p><p>
+ For example, the preceding sum-and-product example could also be
+ done this way:
+
+</p><pre class="programlisting">
+CREATE FUNCTION sum_n_product_with_tab (x int)
+RETURNS TABLE(sum int, product int) AS $$
+ SELECT $1 + tab.y, $1 * tab.y FROM tab;
+$$ LANGUAGE SQL;
+</pre><p>
+
+ It is not allowed to use explicit <code class="literal">OUT</code> or <code class="literal">INOUT</code>
+ parameters with the <code class="literal">RETURNS TABLE</code> notation — you must
+ put all the output columns in the <code class="literal">TABLE</code> list.
+ </p></div><div class="sect2" id="XFUNC-SQL-POLYMORPHIC-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">38.5.11. Polymorphic <acronym class="acronym">SQL</acronym> Functions</h3></div></div></div><p>
+ <acronym class="acronym">SQL</acronym> functions can be declared to accept and
+ return the polymorphic types described in <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC" title="38.2.5. Polymorphic Types">Section 38.2.5</a>. Here is a polymorphic
+ function <code class="function">make_array</code> that builds up an array
+ from two arbitrary data type elements:
+</p><pre class="screen">
+CREATE FUNCTION make_array(anyelement, anyelement) RETURNS anyarray AS $$
+ SELECT ARRAY[$1, $2];
+$$ LANGUAGE SQL;
+
+SELECT make_array(1, 2) AS intarray, make_array('a'::text, 'b') AS textarray;
+ intarray | textarray
+----------+-----------
+ {1,2} | {a,b}
+(1 row)
+</pre><p>
+ </p><p>
+ Notice the use of the typecast <code class="literal">'a'::text</code>
+ to specify that the argument is of type <code class="type">text</code>. This is
+ required if the argument is just a string literal, since otherwise
+ it would be treated as type
+ <code class="type">unknown</code>, and array of <code class="type">unknown</code> is not a valid
+ type.
+ Without the typecast, you will get errors like this:
+</p><pre class="screen">
+ERROR: could not determine polymorphic type because input has type unknown
+</pre><p>
+ </p><p>
+ With <code class="function">make_array</code> declared as above, you must
+ provide two arguments that are of exactly the same data type; the
+ system will not attempt to resolve any type differences. Thus for
+ example this does not work:
+</p><pre class="screen">
+SELECT make_array(1, 2.5) AS numericarray;
+ERROR: function make_array(integer, numeric) does not exist
+</pre><p>
+ An alternative approach is to use the <span class="quote">“<span class="quote">common</span>”</span> family of
+ polymorphic types, which allows the system to try to identify a
+ suitable common type:
+</p><pre class="screen">
+CREATE FUNCTION make_array2(anycompatible, anycompatible)
+RETURNS anycompatiblearray AS $$
+ SELECT ARRAY[$1, $2];
+$$ LANGUAGE SQL;
+
+SELECT make_array2(1, 2.5) AS numericarray;
+ numericarray
+--------------
+ {1,2.5}
+(1 row)
+</pre><p>
+ Because the rules for common type resolution default to choosing
+ type <code class="type">text</code> when all inputs are of unknown types, this
+ also works:
+</p><pre class="screen">
+SELECT make_array2('a', 'b') AS textarray;
+ textarray
+-----------
+ {a,b}
+(1 row)
+</pre><p>
+ </p><p>
+ It is permitted to have polymorphic arguments with a fixed
+ return type, but the converse is not. For example:
+</p><pre class="screen">
+CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS boolean AS $$
+ SELECT $1 &gt; $2;
+$$ LANGUAGE SQL;
+
+SELECT is_greater(1, 2);
+ is_greater
+------------
+ f
+(1 row)
+
+CREATE FUNCTION invalid_func() RETURNS anyelement AS $$
+ SELECT 1;
+$$ LANGUAGE SQL;
+ERROR: cannot determine result data type
+DETAIL: A result of type anyelement requires at least one input of type anyelement, anyarray, anynonarray, anyenum, or anyrange.
+</pre><p>
+ </p><p>
+ Polymorphism can be used with functions that have output arguments.
+ For example:
+</p><pre class="screen">
+CREATE FUNCTION dup (f1 anyelement, OUT f2 anyelement, OUT f3 anyarray)
+AS 'select $1, array[$1,$1]' LANGUAGE SQL;
+
+SELECT * FROM dup(22);
+ f2 | f3
+----+---------
+ 22 | {22,22}
+(1 row)
+</pre><p>
+ </p><p>
+ Polymorphism can also be used with variadic functions.
+ For example:
+</p><pre class="screen">
+CREATE FUNCTION anyleast (VARIADIC anyarray) RETURNS anyelement AS $$
+ SELECT min($1[i]) FROM generate_subscripts($1, 1) g(i);
+$$ LANGUAGE SQL;
+
+SELECT anyleast(10, -1, 5, 4);
+ anyleast
+----------
+ -1
+(1 row)
+
+SELECT anyleast('abc'::text, 'def');
+ anyleast
+----------
+ abc
+(1 row)
+
+CREATE FUNCTION concat_values(text, VARIADIC anyarray) RETURNS text AS $$
+ SELECT array_to_string($2, $1);
+$$ LANGUAGE SQL;
+
+SELECT concat_values('|', 1, 4, 2);
+ concat_values
+---------------
+ 1|4|2
+(1 row)
+</pre><p>
+ </p></div><div class="sect2" id="id-1.8.3.8.21"><div class="titlepage"><div><div><h3 class="title">38.5.12. <acronym class="acronym">SQL</acronym> Functions with Collations</h3></div></div></div><a id="id-1.8.3.8.21.2" class="indexterm"></a><p>
+ When an SQL function has one or more parameters of collatable data types,
+ a collation is identified for each function call depending on the
+ collations assigned to the actual arguments, as described in <a class="xref" href="collation.html" title="24.2. Collation Support">Section 24.2</a>. If a collation is successfully identified
+ (i.e., there are no conflicts of implicit collations among the arguments)
+ then all the collatable parameters are treated as having that collation
+ implicitly. This will affect the behavior of collation-sensitive
+ operations within the function. For example, using the
+ <code class="function">anyleast</code> function described above, the result of
+</p><pre class="programlisting">
+SELECT anyleast('abc'::text, 'ABC');
+</pre><p>
+ will depend on the database's default collation. In <code class="literal">C</code> locale
+ the result will be <code class="literal">ABC</code>, but in many other locales it will
+ be <code class="literal">abc</code>. The collation to use can be forced by adding
+ a <code class="literal">COLLATE</code> clause to any of the arguments, for example
+</p><pre class="programlisting">
+SELECT anyleast('abc'::text, 'ABC' COLLATE "C");
+</pre><p>
+ Alternatively, if you wish a function to operate with a particular
+ collation regardless of what it is called with, insert
+ <code class="literal">COLLATE</code> clauses as needed in the function definition.
+ This version of <code class="function">anyleast</code> would always use <code class="literal">en_US</code>
+ locale to compare strings:
+</p><pre class="programlisting">
+CREATE FUNCTION anyleast (VARIADIC anyarray) RETURNS anyelement AS $$
+ SELECT min($1[i] COLLATE "en_US") FROM generate_subscripts($1, 1) g(i);
+$$ LANGUAGE SQL;
+</pre><p>
+ But note that this will throw an error if applied to a non-collatable
+ data type.
+ </p><p>
+ If no common collation can be identified among the actual arguments,
+ then an SQL function treats its parameters as having their data types'
+ default collation (which is usually the database's default collation,
+ but could be different for parameters of domain types).
+ </p><p>
+ The behavior of collatable parameters can be thought of as a limited
+ form of polymorphism, applicable only to textual data types.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xproc.html" title="38.4. User-Defined Procedures">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-overload.html" title="38.6. Function Overloading">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.4. User-Defined Procedures </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.6. Function Overloading</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc-volatility.html b/doc/src/sgml/html/xfunc-volatility.html
new file mode 100644
index 0000000..db8ed70
--- /dev/null
+++ b/doc/src/sgml/html/xfunc-volatility.html
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.7. Function Volatility Categories</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-overload.html" title="38.6. Function Overloading" /><link rel="next" href="xfunc-pl.html" title="38.8. Procedural Language Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.7. Function Volatility Categories</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-overload.html" title="38.6. Function Overloading">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-pl.html" title="38.8. Procedural Language Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC-VOLATILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.7. Function Volatility Categories</h2></div></div></div><a id="id-1.8.3.10.2" class="indexterm"></a><a id="id-1.8.3.10.3" class="indexterm"></a><a id="id-1.8.3.10.4" class="indexterm"></a><a id="id-1.8.3.10.5" class="indexterm"></a><p>
+ Every function has a <em class="firstterm">volatility</em> classification, with
+ the possibilities being <code class="literal">VOLATILE</code>, <code class="literal">STABLE</code>, or
+ <code class="literal">IMMUTABLE</code>. <code class="literal">VOLATILE</code> is the default if the
+ <a class="link" href="sql-createfunction.html" title="CREATE FUNCTION"><code class="command">CREATE FUNCTION</code></a>
+ command does not specify a category. The volatility category is a
+ promise to the optimizer about the behavior of the function:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ A <code class="literal">VOLATILE</code> function can do anything, including modifying
+ the database. It can return different results on successive calls with
+ the same arguments. The optimizer makes no assumptions about the
+ behavior of such functions. A query using a volatile function will
+ re-evaluate the function at every row where its value is needed.
+ </p></li><li class="listitem"><p>
+ A <code class="literal">STABLE</code> function cannot modify the database and is
+ guaranteed to return the same results given the same arguments
+ for all rows within a single statement. This category allows the
+ optimizer to optimize multiple calls of the function to a single
+ call. In particular, it is safe to use an expression containing
+ such a function in an index scan condition. (Since an index scan
+ will evaluate the comparison value only once, not once at each
+ row, it is not valid to use a <code class="literal">VOLATILE</code> function in an
+ index scan condition.)
+ </p></li><li class="listitem"><p>
+ An <code class="literal">IMMUTABLE</code> function cannot modify the database and is
+ guaranteed to return the same results given the same arguments forever.
+ This category allows the optimizer to pre-evaluate the function when
+ a query calls it with constant arguments. For example, a query like
+ <code class="literal">SELECT ... WHERE x = 2 + 2</code> can be simplified on sight to
+ <code class="literal">SELECT ... WHERE x = 4</code>, because the function underlying
+ the integer addition operator is marked <code class="literal">IMMUTABLE</code>.
+ </p></li></ul></div><p>
+ </p><p>
+ For best optimization results, you should label your functions with the
+ strictest volatility category that is valid for them.
+ </p><p>
+ Any function with side-effects <span class="emphasis"><em>must</em></span> be labeled
+ <code class="literal">VOLATILE</code>, so that calls to it cannot be optimized away.
+ Even a function with no side-effects needs to be labeled
+ <code class="literal">VOLATILE</code> if its value can change within a single query;
+ some examples are <code class="literal">random()</code>, <code class="literal">currval()</code>,
+ <code class="literal">timeofday()</code>.
+ </p><p>
+ Another important example is that the <code class="function">current_timestamp</code>
+ family of functions qualify as <code class="literal">STABLE</code>, since their values do
+ not change within a transaction.
+ </p><p>
+ There is relatively little difference between <code class="literal">STABLE</code> and
+ <code class="literal">IMMUTABLE</code> categories when considering simple interactive
+ queries that are planned and immediately executed: it doesn't matter
+ a lot whether a function is executed once during planning or once during
+ query execution startup. But there is a big difference if the plan is
+ saved and reused later. Labeling a function <code class="literal">IMMUTABLE</code> when
+ it really isn't might allow it to be prematurely folded to a constant during
+ planning, resulting in a stale value being re-used during subsequent uses
+ of the plan. This is a hazard when using prepared statements or when
+ using function languages that cache plans (such as
+ <span class="application">PL/pgSQL</span>).
+ </p><p>
+ For functions written in SQL or in any of the standard procedural
+ languages, there is a second important property determined by the
+ volatility category, namely the visibility of any data changes that have
+ been made by the SQL command that is calling the function. A
+ <code class="literal">VOLATILE</code> function will see such changes, a <code class="literal">STABLE</code>
+ or <code class="literal">IMMUTABLE</code> function will not. This behavior is implemented
+ using the snapshotting behavior of MVCC (see <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>):
+ <code class="literal">STABLE</code> and <code class="literal">IMMUTABLE</code> functions use a snapshot
+ established as of the start of the calling query, whereas
+ <code class="literal">VOLATILE</code> functions obtain a fresh snapshot at the start of
+ each query they execute.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Functions written in C can manage snapshots however they want, but it's
+ usually a good idea to make C functions work this way too.
+ </p></div><p>
+ Because of this snapshotting behavior,
+ a function containing only <code class="command">SELECT</code> commands can safely be
+ marked <code class="literal">STABLE</code>, even if it selects from tables that might be
+ undergoing modifications by concurrent queries.
+ <span class="productname">PostgreSQL</span> will execute all commands of a
+ <code class="literal">STABLE</code> function using the snapshot established for the
+ calling query, and so it will see a fixed view of the database throughout
+ that query.
+ </p><p>
+ The same snapshotting behavior is used for <code class="command">SELECT</code> commands
+ within <code class="literal">IMMUTABLE</code> functions. It is generally unwise to select
+ from database tables within an <code class="literal">IMMUTABLE</code> function at all,
+ since the immutability will be broken if the table contents ever change.
+ However, <span class="productname">PostgreSQL</span> does not enforce that you
+ do not do that.
+ </p><p>
+ A common error is to label a function <code class="literal">IMMUTABLE</code> when its
+ results depend on a configuration parameter. For example, a function
+ that manipulates timestamps might well have results that depend on the
+ <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting. For safety, such functions should
+ be labeled <code class="literal">STABLE</code> instead.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ <span class="productname">PostgreSQL</span> requires that <code class="literal">STABLE</code>
+ and <code class="literal">IMMUTABLE</code> functions contain no SQL commands other
+ than <code class="command">SELECT</code> to prevent data modification.
+ (This is not a completely bulletproof test, since such functions could
+ still call <code class="literal">VOLATILE</code> functions that modify the database.
+ If you do that, you will find that the <code class="literal">STABLE</code> or
+ <code class="literal">IMMUTABLE</code> function does not notice the database changes
+ applied by the called function, since they are hidden from its snapshot.)
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-overload.html" title="38.6. Function Overloading">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-pl.html" title="38.8. Procedural Language Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.6. Function Overloading </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.8. Procedural Language Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xfunc.html b/doc/src/sgml/html/xfunc.html
new file mode 100644
index 0000000..2017086
--- /dev/null
+++ b/doc/src/sgml/html/xfunc.html
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.3. User-Defined Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-type-system.html" title="38.2. The PostgreSQL Type System" /><link rel="next" href="xproc.html" title="38.4. User-Defined Procedures" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.3. User-Defined Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-type-system.html" title="38.2. The PostgreSQL Type System">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xproc.html" title="38.4. User-Defined Procedures">Next</a></td></tr></table><hr /></div><div class="sect1" id="XFUNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.3. User-Defined Functions</h2></div></div></div><a id="id-1.8.3.6.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> provides four kinds of
+ functions:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ query language functions (functions written in
+ <acronym class="acronym">SQL</acronym>) (<a class="xref" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Section 38.5</a>)
+ </p></li><li class="listitem"><p>
+ procedural language functions (functions written in, for
+ example, <span class="application">PL/pgSQL</span> or <span class="application">PL/Tcl</span>)
+ (<a class="xref" href="xfunc-pl.html" title="38.8. Procedural Language Functions">Section 38.8</a>)
+ </p></li><li class="listitem"><p>
+ internal functions (<a class="xref" href="xfunc-internal.html" title="38.9. Internal Functions">Section 38.9</a>)
+ </p></li><li class="listitem"><p>
+ C-language functions (<a class="xref" href="xfunc-c.html" title="38.10. C-Language Functions">Section 38.10</a>)
+ </p></li></ul></div><p>
+ </p><p>
+ Every kind
+ of function can take base types, composite types, or
+ combinations of these as arguments (parameters). In addition,
+ every kind of function can return a base type or
+ a composite type. Functions can also be defined to return
+ sets of base or composite values.
+ </p><p>
+ Many kinds of functions can take or return certain pseudo-types
+ (such as polymorphic types), but the available facilities vary.
+ Consult the description of each kind of function for more details.
+ </p><p>
+ It's easiest to define <acronym class="acronym">SQL</acronym>
+ functions, so we'll start by discussing those.
+ Most of the concepts presented for <acronym class="acronym">SQL</acronym> functions
+ will carry over to the other types of functions.
+ </p><p>
+ Throughout this chapter, it can be useful to look at the reference
+ page of the <a class="link" href="sql-createfunction.html" title="CREATE FUNCTION"><code class="command">CREATE
+ FUNCTION</code></a> command to
+ understand the examples better. Some examples from this chapter
+ can be found in <code class="filename">funcs.sql</code> and
+ <code class="filename">funcs.c</code> in the <code class="filename">src/tutorial</code>
+ directory in the <span class="productname">PostgreSQL</span> source
+ distribution.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-type-system.html" title="38.2. The PostgreSQL Type System">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xproc.html" title="38.4. User-Defined Procedures">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.2. The <span class="productname">PostgreSQL</span> Type System </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.4. User-Defined Procedures</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xindex.html b/doc/src/sgml/html/xindex.html
new file mode 100644
index 0000000..2082c5c
--- /dev/null
+++ b/doc/src/sgml/html/xindex.html
@@ -0,0 +1,772 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.16. Interfacing Extensions to Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xoper-optimization.html" title="38.15. Operator Optimization Information" /><link rel="next" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.16. Interfacing Extensions to Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xoper-optimization.html" title="38.15. Operator Optimization Information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Next</a></td></tr></table><hr /></div><div class="sect1" id="XINDEX"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.16. Interfacing Extensions to Indexes</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS">38.16.1. Index Methods and Operator Classes</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-STRATEGIES">38.16.2. Index Method Strategies</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-SUPPORT">38.16.3. Index Method Support Routines</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-EXAMPLE">38.16.4. An Example</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPFAMILY">38.16.5. Operator Classes and Operator Families</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS-DEPENDENCIES">38.16.6. System Dependencies on Operator Classes</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-ORDERING-OPS">38.16.7. Ordering Operators</a></span></dt><dt><span class="sect2"><a href="xindex.html#XINDEX-OPCLASS-FEATURES">38.16.8. Special Features of Operator Classes</a></span></dt></dl></div><a id="id-1.8.3.19.2" class="indexterm"></a><p>
+ The procedures described thus far let you define new types, new
+ functions, and new operators. However, we cannot yet define an
+ index on a column of a new data type. To do this, we must define an
+ <em class="firstterm">operator class</em> for the new data type. Later in this
+ section, we will illustrate this concept in an example: a new
+ operator class for the B-tree index method that stores and sorts
+ complex numbers in ascending absolute value order.
+ </p><p>
+ Operator classes can be grouped into <em class="firstterm">operator families</em>
+ to show the relationships between semantically compatible classes.
+ When only a single data type is involved, an operator class is sufficient,
+ so we'll focus on that case first and then return to operator families.
+ </p><div class="sect2" id="XINDEX-OPCLASS"><div class="titlepage"><div><div><h3 class="title">38.16.1. Index Methods and Operator Classes</h3></div></div></div><p>
+ The <code class="classname">pg_am</code> table contains one row for every
+ index method (internally known as access method). Support for
+ regular access to tables is built into
+ <span class="productname">PostgreSQL</span>, but all index methods are
+ described in <code class="classname">pg_am</code>. It is possible to add a
+ new index access method by writing the necessary code and
+ then creating an entry in <code class="classname">pg_am</code> — but that is
+ beyond the scope of this chapter (see <a class="xref" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Chapter 64</a>).
+ </p><p>
+ The routines for an index method do not directly know anything
+ about the data types that the index method will operate on.
+ Instead, an <em class="firstterm">operator
+ class</em><a id="id-1.8.3.19.5.3.2" class="indexterm"></a>
+ identifies the set of operations that the index method needs to use
+ to work with a particular data type. Operator classes are so
+ called because one thing they specify is the set of
+ <code class="literal">WHERE</code>-clause operators that can be used with an index
+ (i.e., can be converted into an index-scan qualification). An
+ operator class can also specify some <em class="firstterm">support
+ function</em> that are needed by the internal operations of the
+ index method, but do not directly correspond to any
+ <code class="literal">WHERE</code>-clause operator that can be used with the index.
+ </p><p>
+ It is possible to define multiple operator classes for the same
+ data type and index method. By doing this, multiple
+ sets of indexing semantics can be defined for a single data type.
+ For example, a B-tree index requires a sort ordering to be defined
+ for each data type it works on.
+ It might be useful for a complex-number data type
+ to have one B-tree operator class that sorts the data by complex
+ absolute value, another that sorts by real part, and so on.
+ Typically, one of the operator classes will be deemed most commonly
+ useful and will be marked as the default operator class for that
+ data type and index method.
+ </p><p>
+ The same operator class name
+ can be used for several different index methods (for example, both B-tree
+ and hash index methods have operator classes named
+ <code class="literal">int4_ops</code>), but each such class is an independent
+ entity and must be defined separately.
+ </p></div><div class="sect2" id="XINDEX-STRATEGIES"><div class="titlepage"><div><div><h3 class="title">38.16.2. Index Method Strategies</h3></div></div></div><p>
+ The operators associated with an operator class are identified by
+ <span class="quote">“<span class="quote">strategy numbers</span>”</span>, which serve to identify the semantics of
+ each operator within the context of its operator class.
+ For example, B-trees impose a strict ordering on keys, lesser to greater,
+ and so operators like <span class="quote">“<span class="quote">less than</span>”</span> and <span class="quote">“<span class="quote">greater than or equal
+ to</span>”</span> are interesting with respect to a B-tree.
+ Because
+ <span class="productname">PostgreSQL</span> allows the user to define operators,
+ <span class="productname">PostgreSQL</span> cannot look at the name of an operator
+ (e.g., <code class="literal">&lt;</code> or <code class="literal">&gt;=</code>) and tell what kind of
+ comparison it is. Instead, the index method defines a set of
+ <span class="quote">“<span class="quote">strategies</span>”</span>, which can be thought of as generalized operators.
+ Each operator class specifies which actual operator corresponds to each
+ strategy for a particular data type and interpretation of the index
+ semantics.
+ </p><p>
+ The B-tree index method defines five strategies, shown in <a class="xref" href="xindex.html#XINDEX-BTREE-STRAT-TABLE" title="Table 38.3. B-Tree Strategies">Table 38.3</a>.
+ </p><div class="table" id="XINDEX-BTREE-STRAT-TABLE"><p class="title"><strong>Table 38.3. B-Tree Strategies</strong></p><div class="table-contents"><table class="table" summary="B-Tree Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>less than</td><td>1</td></tr><tr><td>less than or equal</td><td>2</td></tr><tr><td>equal</td><td>3</td></tr><tr><td>greater than or equal</td><td>4</td></tr><tr><td>greater than</td><td>5</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Hash indexes support only equality comparisons, and so they use only one
+ strategy, shown in <a class="xref" href="xindex.html#XINDEX-HASH-STRAT-TABLE" title="Table 38.4. Hash Strategies">Table 38.4</a>.
+ </p><div class="table" id="XINDEX-HASH-STRAT-TABLE"><p class="title"><strong>Table 38.4. Hash Strategies</strong></p><div class="table-contents"><table class="table" summary="Hash Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>equal</td><td>1</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ GiST indexes are more flexible: they do not have a fixed set of
+ strategies at all. Instead, the <span class="quote">“<span class="quote">consistency</span>”</span> support routine
+ of each particular GiST operator class interprets the strategy numbers
+ however it likes. As an example, several of the built-in GiST index
+ operator classes index two-dimensional geometric objects, providing
+ the <span class="quote">“<span class="quote">R-tree</span>”</span> strategies shown in
+ <a class="xref" href="xindex.html#XINDEX-RTREE-STRAT-TABLE" title="Table 38.5. GiST Two-Dimensional “R-tree” Strategies">Table 38.5</a>. Four of these are true
+ two-dimensional tests (overlaps, same, contains, contained by);
+ four of them consider only the X direction; and the other four
+ provide the same tests in the Y direction.
+ </p><div class="table" id="XINDEX-RTREE-STRAT-TABLE"><p class="title"><strong>Table 38.5. GiST Two-Dimensional <span class="quote">“<span class="quote">R-tree</span>”</span> Strategies</strong></p><div class="table-contents"><table class="table" summary="GiST Two-Dimensional R-tree Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>strictly left of</td><td>1</td></tr><tr><td>does not extend to right of</td><td>2</td></tr><tr><td>overlaps</td><td>3</td></tr><tr><td>does not extend to left of</td><td>4</td></tr><tr><td>strictly right of</td><td>5</td></tr><tr><td>same</td><td>6</td></tr><tr><td>contains</td><td>7</td></tr><tr><td>contained by</td><td>8</td></tr><tr><td>does not extend above</td><td>9</td></tr><tr><td>strictly below</td><td>10</td></tr><tr><td>strictly above</td><td>11</td></tr><tr><td>does not extend below</td><td>12</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ SP-GiST indexes are similar to GiST indexes in flexibility: they don't have
+ a fixed set of strategies. Instead the support routines of each operator
+ class interpret the strategy numbers according to the operator class's
+ definition. As an example, the strategy numbers used by the built-in
+ operator classes for points are shown in <a class="xref" href="xindex.html#XINDEX-SPGIST-POINT-STRAT-TABLE" title="Table 38.6. SP-GiST Point Strategies">Table 38.6</a>.
+ </p><div class="table" id="XINDEX-SPGIST-POINT-STRAT-TABLE"><p class="title"><strong>Table 38.6. SP-GiST Point Strategies</strong></p><div class="table-contents"><table class="table" summary="SP-GiST Point Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>strictly left of</td><td>1</td></tr><tr><td>strictly right of</td><td>5</td></tr><tr><td>same</td><td>6</td></tr><tr><td>contained by</td><td>8</td></tr><tr><td>strictly below</td><td>10</td></tr><tr><td>strictly above</td><td>11</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ GIN indexes are similar to GiST and SP-GiST indexes, in that they don't
+ have a fixed set of strategies either. Instead the support routines of
+ each operator class interpret the strategy numbers according to the
+ operator class's definition. As an example, the strategy numbers used by
+ the built-in operator class for arrays are shown in
+ <a class="xref" href="xindex.html#XINDEX-GIN-ARRAY-STRAT-TABLE" title="Table 38.7. GIN Array Strategies">Table 38.7</a>.
+ </p><div class="table" id="XINDEX-GIN-ARRAY-STRAT-TABLE"><p class="title"><strong>Table 38.7. GIN Array Strategies</strong></p><div class="table-contents"><table class="table" summary="GIN Array Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>overlap</td><td>1</td></tr><tr><td>contains</td><td>2</td></tr><tr><td>is contained by</td><td>3</td></tr><tr><td>equal</td><td>4</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ BRIN indexes are similar to GiST, SP-GiST and GIN indexes in that they
+ don't have a fixed set of strategies either. Instead the support routines
+ of each operator class interpret the strategy numbers according to the
+ operator class's definition. As an example, the strategy numbers used by
+ the built-in <code class="literal">Minmax</code> operator classes are shown in
+ <a class="xref" href="xindex.html#XINDEX-BRIN-MINMAX-STRAT-TABLE" title="Table 38.8. BRIN Minmax Strategies">Table 38.8</a>.
+ </p><div class="table" id="XINDEX-BRIN-MINMAX-STRAT-TABLE"><p class="title"><strong>Table 38.8. BRIN Minmax Strategies</strong></p><div class="table-contents"><table class="table" summary="BRIN Minmax Strategies" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operation</th><th>Strategy Number</th></tr></thead><tbody><tr><td>less than</td><td>1</td></tr><tr><td>less than or equal</td><td>2</td></tr><tr><td>equal</td><td>3</td></tr><tr><td>greater than or equal</td><td>4</td></tr><tr><td>greater than</td><td>5</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Notice that all the operators listed above return Boolean values. In
+ practice, all operators defined as index method search operators must
+ return type <code class="type">boolean</code>, since they must appear at the top
+ level of a <code class="literal">WHERE</code> clause to be used with an index.
+ (Some index access methods also support <em class="firstterm">ordering operators</em>,
+ which typically don't return Boolean values; that feature is discussed
+ in <a class="xref" href="xindex.html#XINDEX-ORDERING-OPS" title="38.16.7. Ordering Operators">Section 38.16.7</a>.)
+ </p></div><div class="sect2" id="XINDEX-SUPPORT"><div class="titlepage"><div><div><h3 class="title">38.16.3. Index Method Support Routines</h3></div></div></div><p>
+ Strategies aren't usually enough information for the system to figure
+ out how to use an index. In practice, the index methods require
+ additional support routines in order to work. For example, the B-tree
+ index method must be able to compare two keys and determine whether one
+ is greater than, equal to, or less than the other. Similarly, the
+ hash index method must be able to compute hash codes for key values.
+ These operations do not correspond to operators used in qualifications in
+ SQL commands; they are administrative routines used by
+ the index methods, internally.
+ </p><p>
+ Just as with strategies, the operator class identifies which specific
+ functions should play each of these roles for a given data type and
+ semantic interpretation. The index method defines the set
+ of functions it needs, and the operator class identifies the correct
+ functions to use by assigning them to the <span class="quote">“<span class="quote">support function numbers</span>”</span>
+ specified by the index method.
+ </p><p>
+ Additionally, some opclasses allow users to specify parameters which
+ control their behavior. Each builtin index access method has an optional
+ <code class="function">options</code> support function, which defines a set of
+ opclass-specific parameters.
+ </p><p>
+ B-trees require a comparison support function,
+ and allow four additional support functions to be
+ supplied at the operator class author's option, as shown in <a class="xref" href="xindex.html#XINDEX-BTREE-SUPPORT-TABLE" title="Table 38.9. B-Tree Support Functions">Table 38.9</a>.
+ The requirements for these support functions are explained further in
+ <a class="xref" href="btree-support-funcs.html" title="67.3. B-Tree Support Functions">Section 67.3</a>.
+ </p><div class="table" id="XINDEX-BTREE-SUPPORT-TABLE"><p class="title"><strong>Table 38.9. B-Tree Support Functions</strong></p><div class="table-contents"><table class="table" summary="B-Tree Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Function</th><th>Support Number</th></tr></thead><tbody><tr><td>
+ Compare two keys and return an integer less than zero, zero, or
+ greater than zero, indicating whether the first key is less than,
+ equal to, or greater than the second
+ </td><td>1</td></tr><tr><td>
+ Return the addresses of C-callable sort support function(s)
+ (optional)
+ </td><td>2</td></tr><tr><td>
+ Compare a test value to a base value plus/minus an offset, and return
+ true or false according to the comparison result (optional)
+ </td><td>3</td></tr><tr><td>
+ Determine if it is safe for indexes that use the operator
+ class to apply the btree deduplication optimization (optional)
+ </td><td>4</td></tr><tr><td>
+ Define options that are specific to this operator class
+ (optional)
+ </td><td>5</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Hash indexes require one support function, and allow two additional ones to
+ be supplied at the operator class author's option, as shown in <a class="xref" href="xindex.html#XINDEX-HASH-SUPPORT-TABLE" title="Table 38.10. Hash Support Functions">Table 38.10</a>.
+ </p><div class="table" id="XINDEX-HASH-SUPPORT-TABLE"><p class="title"><strong>Table 38.10. Hash Support Functions</strong></p><div class="table-contents"><table class="table" summary="Hash Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Function</th><th>Support Number</th></tr></thead><tbody><tr><td>Compute the 32-bit hash value for a key</td><td>1</td></tr><tr><td>
+ Compute the 64-bit hash value for a key given a 64-bit salt; if
+ the salt is 0, the low 32 bits of the result must match the value
+ that would have been computed by function 1
+ (optional)
+ </td><td>2</td></tr><tr><td>
+ Define options that are specific to this operator class
+ (optional)
+ </td><td>3</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ GiST indexes have eleven support functions, six of which are optional,
+ as shown in <a class="xref" href="xindex.html#XINDEX-GIST-SUPPORT-TABLE" title="Table 38.11. GiST Support Functions">Table 38.11</a>.
+ (For more information see <a class="xref" href="gist.html" title="Chapter 68. GiST Indexes">Chapter 68</a>.)
+ </p><div class="table" id="XINDEX-GIST-SUPPORT-TABLE"><p class="title"><strong>Table 38.11. GiST Support Functions</strong></p><div class="table-contents"><table class="table" summary="GiST Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Function</th><th>Description</th><th>Support Number</th></tr></thead><tbody><tr><td><code class="function">consistent</code></td><td>determine whether key satisfies the
+ query qualifier</td><td>1</td></tr><tr><td><code class="function">union</code></td><td>compute union of a set of keys</td><td>2</td></tr><tr><td><code class="function">compress</code></td><td>compute a compressed representation of a key or value
+ to be indexed (optional)</td><td>3</td></tr><tr><td><code class="function">decompress</code></td><td>compute a decompressed representation of a
+ compressed key (optional)</td><td>4</td></tr><tr><td><code class="function">penalty</code></td><td>compute penalty for inserting new key into subtree
+ with given subtree's key</td><td>5</td></tr><tr><td><code class="function">picksplit</code></td><td>determine which entries of a page are to be moved
+ to the new page and compute the union keys for resulting pages</td><td>6</td></tr><tr><td><code class="function">same</code></td><td>compare two keys and return true if they are equal</td><td>7</td></tr><tr><td><code class="function">distance</code></td><td>determine distance from key to query value (optional)</td><td>8</td></tr><tr><td><code class="function">fetch</code></td><td>compute original representation of a compressed key for
+ index-only scans (optional)</td><td>9</td></tr><tr><td><code class="function">options</code></td><td>define options that are specific to this operator class
+ (optional)</td><td>10</td></tr><tr><td><code class="function">sortsupport</code></td><td>provide a sort comparator to be used in fast index builds
+ (optional)</td><td>11</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ SP-GiST indexes have six support functions, one of which is optional, as
+ shown in <a class="xref" href="xindex.html#XINDEX-SPGIST-SUPPORT-TABLE" title="Table 38.12. SP-GiST Support Functions">Table 38.12</a>.
+ (For more information see <a class="xref" href="spgist.html" title="Chapter 69. SP-GiST Indexes">Chapter 69</a>.)
+ </p><div class="table" id="XINDEX-SPGIST-SUPPORT-TABLE"><p class="title"><strong>Table 38.12. SP-GiST Support Functions</strong></p><div class="table-contents"><table class="table" summary="SP-GiST Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Function</th><th>Description</th><th>Support Number</th></tr></thead><tbody><tr><td><code class="function">config</code></td><td>provide basic information about the operator class</td><td>1</td></tr><tr><td><code class="function">choose</code></td><td>determine how to insert a new value into an inner tuple</td><td>2</td></tr><tr><td><code class="function">picksplit</code></td><td>determine how to partition a set of values</td><td>3</td></tr><tr><td><code class="function">inner_consistent</code></td><td>determine which sub-partitions need to be searched for a
+ query</td><td>4</td></tr><tr><td><code class="function">leaf_consistent</code></td><td>determine whether key satisfies the
+ query qualifier</td><td>5</td></tr><tr><td><code class="function">options</code></td><td>define options that are specific to this operator class
+ (optional)</td><td>6</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ GIN indexes have seven support functions, four of which are optional,
+ as shown in <a class="xref" href="xindex.html#XINDEX-GIN-SUPPORT-TABLE" title="Table 38.13. GIN Support Functions">Table 38.13</a>.
+ (For more information see <a class="xref" href="gin.html" title="Chapter 70. GIN Indexes">Chapter 70</a>.)
+ </p><div class="table" id="XINDEX-GIN-SUPPORT-TABLE"><p class="title"><strong>Table 38.13. GIN Support Functions</strong></p><div class="table-contents"><table class="table" summary="GIN Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Function</th><th>Description</th><th>Support Number</th></tr></thead><tbody><tr><td><code class="function">compare</code></td><td>
+ compare two keys and return an integer less than zero, zero,
+ or greater than zero, indicating whether the first key is less than,
+ equal to, or greater than the second
+ </td><td>1</td></tr><tr><td><code class="function">extractValue</code></td><td>extract keys from a value to be indexed</td><td>2</td></tr><tr><td><code class="function">extractQuery</code></td><td>extract keys from a query condition</td><td>3</td></tr><tr><td><code class="function">consistent</code></td><td>
+ determine whether value matches query condition (Boolean variant)
+ (optional if support function 6 is present)
+ </td><td>4</td></tr><tr><td><code class="function">comparePartial</code></td><td>
+ compare partial key from
+ query and key from index, and return an integer less than zero, zero,
+ or greater than zero, indicating whether GIN should ignore this index
+ entry, treat the entry as a match, or stop the index scan (optional)
+ </td><td>5</td></tr><tr><td><code class="function">triConsistent</code></td><td>
+ determine whether value matches query condition (ternary variant)
+ (optional if support function 4 is present)
+ </td><td>6</td></tr><tr><td><code class="function">options</code></td><td>
+ define options that are specific to this operator class
+ (optional)
+ </td><td>7</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ BRIN indexes have five basic support functions, one of which is optional,
+ as shown in <a class="xref" href="xindex.html#XINDEX-BRIN-SUPPORT-TABLE" title="Table 38.14. BRIN Support Functions">Table 38.14</a>. Some versions of
+ the basic functions require additional support functions to be provided.
+ (For more information see <a class="xref" href="brin-extensibility.html" title="71.3. Extensibility">Section 71.3</a>.)
+ </p><div class="table" id="XINDEX-BRIN-SUPPORT-TABLE"><p class="title"><strong>Table 38.14. BRIN Support Functions</strong></p><div class="table-contents"><table class="table" summary="BRIN Support Functions" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Function</th><th>Description</th><th>Support Number</th></tr></thead><tbody><tr><td><code class="function">opcInfo</code></td><td>
+ return internal information describing the indexed columns'
+ summary data
+ </td><td>1</td></tr><tr><td><code class="function">add_value</code></td><td>add a new value to an existing summary index tuple</td><td>2</td></tr><tr><td><code class="function">consistent</code></td><td>determine whether value matches query condition</td><td>3</td></tr><tr><td><code class="function">union</code></td><td>
+ compute union of two summary tuples
+ </td><td>4</td></tr><tr><td><code class="function">options</code></td><td>
+ define options that are specific to this operator class
+ (optional)
+ </td><td>5</td></tr></tbody></table></div></div><br class="table-break" /><p>
+ Unlike search operators, support functions return whichever data
+ type the particular index method expects; for example in the case
+ of the comparison function for B-trees, a signed integer. The number
+ and types of the arguments to each support function are likewise
+ dependent on the index method. For B-tree and hash the comparison and
+ hashing support functions take the same input data types as do the
+ operators included in the operator class, but this is not the case for
+ most GiST, SP-GiST, GIN, and BRIN support functions.
+ </p></div><div class="sect2" id="XINDEX-EXAMPLE"><div class="titlepage"><div><div><h3 class="title">38.16.4. An Example</h3></div></div></div><p>
+ Now that we have seen the ideas, here is the promised example of
+ creating a new operator class.
+ (You can find a working copy of this example in
+ <code class="filename">src/tutorial/complex.c</code> and
+ <code class="filename">src/tutorial/complex.sql</code> in the source
+ distribution.)
+ The operator class encapsulates
+ operators that sort complex numbers in absolute value order, so we
+ choose the name <code class="literal">complex_abs_ops</code>. First, we need
+ a set of operators. The procedure for defining operators was
+ discussed in <a class="xref" href="xoper.html" title="38.14. User-Defined Operators">Section 38.14</a>. For an operator class on
+ B-trees, the operators we require are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">absolute-value less-than (strategy 1)</li><li class="listitem">absolute-value less-than-or-equal (strategy 2)</li><li class="listitem">absolute-value equal (strategy 3)</li><li class="listitem">absolute-value greater-than-or-equal (strategy 4)</li><li class="listitem">absolute-value greater-than (strategy 5)</li></ul></div><p>
+ </p><p>
+ The least error-prone way to define a related set of comparison operators
+ is to write the B-tree comparison support function first, and then write the
+ other functions as one-line wrappers around the support function. This
+ reduces the odds of getting inconsistent results for corner cases.
+ Following this approach, we first write:
+
+</p><pre class="programlisting">
+#define Mag(c) ((c)-&gt;x*(c)-&gt;x + (c)-&gt;y*(c)-&gt;y)
+
+static int
+complex_abs_cmp_internal(Complex *a, Complex *b)
+{
+ double amag = Mag(a),
+ bmag = Mag(b);
+
+ if (amag &lt; bmag)
+ return -1;
+ if (amag &gt; bmag)
+ return 1;
+ return 0;
+}
+
+</pre><p>
+
+ Now the less-than function looks like:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(complex_abs_lt);
+
+Datum
+complex_abs_lt(PG_FUNCTION_ARGS)
+{
+ Complex *a = (Complex *) PG_GETARG_POINTER(0);
+ Complex *b = (Complex *) PG_GETARG_POINTER(1);
+
+ PG_RETURN_BOOL(complex_abs_cmp_internal(a, b) &lt; 0);
+}
+
+</pre><p>
+
+ The other four functions differ only in how they compare the internal
+ function's result to zero.
+ </p><p>
+ Next we declare the functions and the operators based on the functions
+ to SQL:
+
+</p><pre class="programlisting">
+CREATE FUNCTION complex_abs_lt(complex, complex) RETURNS bool
+ AS '<em class="replaceable"><code>filename</code></em>', 'complex_abs_lt'
+ LANGUAGE C IMMUTABLE STRICT;
+
+CREATE OPERATOR &lt; (
+ leftarg = complex, rightarg = complex, procedure = complex_abs_lt,
+ commutator = &gt; , negator = &gt;= ,
+ restrict = scalarltsel, join = scalarltjoinsel
+);
+</pre><p>
+ It is important to specify the correct commutator and negator operators,
+ as well as suitable restriction and join selectivity
+ functions, otherwise the optimizer will be unable to make effective
+ use of the index.
+ </p><p>
+ Other things worth noting are happening here:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ There can only be one operator named, say, <code class="literal">=</code>
+ and taking type <code class="type">complex</code> for both operands. In this
+ case we don't have any other operator <code class="literal">=</code> for
+ <code class="type">complex</code>, but if we were building a practical data
+ type we'd probably want <code class="literal">=</code> to be the ordinary
+ equality operation for complex numbers (and not the equality of
+ the absolute values). In that case, we'd need to use some other
+ operator name for <code class="function">complex_abs_eq</code>.
+ </p></li><li class="listitem"><p>
+ Although <span class="productname">PostgreSQL</span> can cope with
+ functions having the same SQL name as long as they have different
+ argument data types, C can only cope with one global function
+ having a given name. So we shouldn't name the C function
+ something simple like <code class="filename">abs_eq</code>. Usually it's
+ a good practice to include the data type name in the C function
+ name, so as not to conflict with functions for other data types.
+ </p></li><li class="listitem"><p>
+ We could have made the SQL name
+ of the function <code class="filename">abs_eq</code>, relying on
+ <span class="productname">PostgreSQL</span> to distinguish it by
+ argument data types from any other SQL function of the same name.
+ To keep the example simple, we make the function have the same
+ names at the C level and SQL level.
+ </p></li></ul></div><p>
+ </p><p>
+ The next step is the registration of the support routine required
+ by B-trees. The example C code that implements this is in the same
+ file that contains the operator functions. This is how we declare
+ the function:
+
+</p><pre class="programlisting">
+CREATE FUNCTION complex_abs_cmp(complex, complex)
+ RETURNS integer
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C IMMUTABLE STRICT;
+</pre><p>
+ </p><p>
+ Now that we have the required operators and support routine,
+ we can finally create the operator class:
+
+</p><pre class="programlisting">
+CREATE OPERATOR CLASS complex_abs_ops
+ DEFAULT FOR TYPE complex USING btree AS
+ OPERATOR 1 &lt; ,
+ OPERATOR 2 &lt;= ,
+ OPERATOR 3 = ,
+ OPERATOR 4 &gt;= ,
+ OPERATOR 5 &gt; ,
+ FUNCTION 1 complex_abs_cmp(complex, complex);
+
+</pre><p>
+ </p><p>
+ And we're done! It should now be possible to create
+ and use B-tree indexes on <code class="type">complex</code> columns.
+ </p><p>
+ We could have written the operator entries more verbosely, as in:
+</p><pre class="programlisting">
+ OPERATOR 1 &lt; (complex, complex) ,
+</pre><p>
+ but there is no need to do so when the operators take the same data type
+ we are defining the operator class for.
+ </p><p>
+ The above example assumes that you want to make this new operator class the
+ default B-tree operator class for the <code class="type">complex</code> data type.
+ If you don't, just leave out the word <code class="literal">DEFAULT</code>.
+ </p></div><div class="sect2" id="XINDEX-OPFAMILY"><div class="titlepage"><div><div><h3 class="title">38.16.5. Operator Classes and Operator Families</h3></div></div></div><p>
+ So far we have implicitly assumed that an operator class deals with
+ only one data type. While there certainly can be only one data type in
+ a particular index column, it is often useful to index operations that
+ compare an indexed column to a value of a different data type. Also,
+ if there is use for a cross-data-type operator in connection with an
+ operator class, it is often the case that the other data type has a
+ related operator class of its own. It is helpful to make the connections
+ between related classes explicit, because this can aid the planner in
+ optimizing SQL queries (particularly for B-tree operator classes, since
+ the planner contains a great deal of knowledge about how to work with them).
+ </p><p>
+ To handle these needs, <span class="productname">PostgreSQL</span>
+ uses the concept of an <em class="firstterm">operator
+ family</em><a id="id-1.8.3.19.9.3.3" class="indexterm"></a>.
+ An operator family contains one or more operator classes, and can also
+ contain indexable operators and corresponding support functions that
+ belong to the family as a whole but not to any single class within the
+ family. We say that such operators and functions are <span class="quote">“<span class="quote">loose</span>”</span>
+ within the family, as opposed to being bound into a specific class.
+ Typically each operator class contains single-data-type operators
+ while cross-data-type operators are loose in the family.
+ </p><p>
+ All the operators and functions in an operator family must have compatible
+ semantics, where the compatibility requirements are set by the index
+ method. You might therefore wonder why bother to single out particular
+ subsets of the family as operator classes; and indeed for many purposes
+ the class divisions are irrelevant and the family is the only interesting
+ grouping. The reason for defining operator classes is that they specify
+ how much of the family is needed to support any particular index.
+ If there is an index using an operator class, then that operator class
+ cannot be dropped without dropping the index — but other parts of
+ the operator family, namely other operator classes and loose operators,
+ could be dropped. Thus, an operator class should be specified to contain
+ the minimum set of operators and functions that are reasonably needed
+ to work with an index on a specific data type, and then related but
+ non-essential operators can be added as loose members of the operator
+ family.
+ </p><p>
+ As an example, <span class="productname">PostgreSQL</span> has a built-in
+ B-tree operator family <code class="literal">integer_ops</code>, which includes operator
+ classes <code class="literal">int8_ops</code>, <code class="literal">int4_ops</code>, and
+ <code class="literal">int2_ops</code> for indexes on <code class="type">bigint</code> (<code class="type">int8</code>),
+ <code class="type">integer</code> (<code class="type">int4</code>), and <code class="type">smallint</code> (<code class="type">int2</code>)
+ columns respectively. The family also contains cross-data-type comparison
+ operators allowing any two of these types to be compared, so that an index
+ on one of these types can be searched using a comparison value of another
+ type. The family could be duplicated by these definitions:
+
+</p><pre class="programlisting">
+CREATE OPERATOR FAMILY integer_ops USING btree;
+
+CREATE OPERATOR CLASS int8_ops
+DEFAULT FOR TYPE int8 USING btree FAMILY integer_ops AS
+ -- standard int8 comparisons
+ OPERATOR 1 &lt; ,
+ OPERATOR 2 &lt;= ,
+ OPERATOR 3 = ,
+ OPERATOR 4 &gt;= ,
+ OPERATOR 5 &gt; ,
+ FUNCTION 1 btint8cmp(int8, int8) ,
+ FUNCTION 2 btint8sortsupport(internal) ,
+ FUNCTION 3 in_range(int8, int8, int8, boolean, boolean) ,
+ FUNCTION 4 btequalimage(oid) ;
+
+CREATE OPERATOR CLASS int4_ops
+DEFAULT FOR TYPE int4 USING btree FAMILY integer_ops AS
+ -- standard int4 comparisons
+ OPERATOR 1 &lt; ,
+ OPERATOR 2 &lt;= ,
+ OPERATOR 3 = ,
+ OPERATOR 4 &gt;= ,
+ OPERATOR 5 &gt; ,
+ FUNCTION 1 btint4cmp(int4, int4) ,
+ FUNCTION 2 btint4sortsupport(internal) ,
+ FUNCTION 3 in_range(int4, int4, int4, boolean, boolean) ,
+ FUNCTION 4 btequalimage(oid) ;
+
+CREATE OPERATOR CLASS int2_ops
+DEFAULT FOR TYPE int2 USING btree FAMILY integer_ops AS
+ -- standard int2 comparisons
+ OPERATOR 1 &lt; ,
+ OPERATOR 2 &lt;= ,
+ OPERATOR 3 = ,
+ OPERATOR 4 &gt;= ,
+ OPERATOR 5 &gt; ,
+ FUNCTION 1 btint2cmp(int2, int2) ,
+ FUNCTION 2 btint2sortsupport(internal) ,
+ FUNCTION 3 in_range(int2, int2, int2, boolean, boolean) ,
+ FUNCTION 4 btequalimage(oid) ;
+
+ALTER OPERATOR FAMILY integer_ops USING btree ADD
+ -- cross-type comparisons int8 vs int2
+ OPERATOR 1 &lt; (int8, int2) ,
+ OPERATOR 2 &lt;= (int8, int2) ,
+ OPERATOR 3 = (int8, int2) ,
+ OPERATOR 4 &gt;= (int8, int2) ,
+ OPERATOR 5 &gt; (int8, int2) ,
+ FUNCTION 1 btint82cmp(int8, int2) ,
+
+ -- cross-type comparisons int8 vs int4
+ OPERATOR 1 &lt; (int8, int4) ,
+ OPERATOR 2 &lt;= (int8, int4) ,
+ OPERATOR 3 = (int8, int4) ,
+ OPERATOR 4 &gt;= (int8, int4) ,
+ OPERATOR 5 &gt; (int8, int4) ,
+ FUNCTION 1 btint84cmp(int8, int4) ,
+
+ -- cross-type comparisons int4 vs int2
+ OPERATOR 1 &lt; (int4, int2) ,
+ OPERATOR 2 &lt;= (int4, int2) ,
+ OPERATOR 3 = (int4, int2) ,
+ OPERATOR 4 &gt;= (int4, int2) ,
+ OPERATOR 5 &gt; (int4, int2) ,
+ FUNCTION 1 btint42cmp(int4, int2) ,
+
+ -- cross-type comparisons int4 vs int8
+ OPERATOR 1 &lt; (int4, int8) ,
+ OPERATOR 2 &lt;= (int4, int8) ,
+ OPERATOR 3 = (int4, int8) ,
+ OPERATOR 4 &gt;= (int4, int8) ,
+ OPERATOR 5 &gt; (int4, int8) ,
+ FUNCTION 1 btint48cmp(int4, int8) ,
+
+ -- cross-type comparisons int2 vs int8
+ OPERATOR 1 &lt; (int2, int8) ,
+ OPERATOR 2 &lt;= (int2, int8) ,
+ OPERATOR 3 = (int2, int8) ,
+ OPERATOR 4 &gt;= (int2, int8) ,
+ OPERATOR 5 &gt; (int2, int8) ,
+ FUNCTION 1 btint28cmp(int2, int8) ,
+
+ -- cross-type comparisons int2 vs int4
+ OPERATOR 1 &lt; (int2, int4) ,
+ OPERATOR 2 &lt;= (int2, int4) ,
+ OPERATOR 3 = (int2, int4) ,
+ OPERATOR 4 &gt;= (int2, int4) ,
+ OPERATOR 5 &gt; (int2, int4) ,
+ FUNCTION 1 btint24cmp(int2, int4) ,
+
+ -- cross-type in_range functions
+ FUNCTION 3 in_range(int4, int4, int8, boolean, boolean) ,
+ FUNCTION 3 in_range(int4, int4, int2, boolean, boolean) ,
+ FUNCTION 3 in_range(int2, int2, int8, boolean, boolean) ,
+ FUNCTION 3 in_range(int2, int2, int4, boolean, boolean) ;
+
+</pre><p>
+
+ Notice that this definition <span class="quote">“<span class="quote">overloads</span>”</span> the operator strategy and
+ support function numbers: each number occurs multiple times within the
+ family. This is allowed so long as each instance of a
+ particular number has distinct input data types. The instances that have
+ both input types equal to an operator class's input type are the
+ primary operators and support functions for that operator class,
+ and in most cases should be declared as part of the operator class rather
+ than as loose members of the family.
+ </p><p>
+ In a B-tree operator family, all the operators in the family must sort
+ compatibly, as is specified in detail in <a class="xref" href="btree-behavior.html" title="67.2. Behavior of B-Tree Operator Classes">Section 67.2</a>.
+ For each
+ operator in the family there must be a support function having the same
+ two input data types as the operator. It is recommended that a family be
+ complete, i.e., for each combination of data types, all operators are
+ included. Each operator class should include just the non-cross-type
+ operators and support function for its data type.
+ </p><p>
+ To build a multiple-data-type hash operator family, compatible hash
+ support functions must be created for each data type supported by the
+ family. Here compatibility means that the functions are guaranteed to
+ return the same hash code for any two values that are considered equal
+ by the family's equality operators, even when the values are of different
+ types. This is usually difficult to accomplish when the types have
+ different physical representations, but it can be done in some cases.
+ Furthermore, casting a value from one data type represented in the operator
+ family to another data type also represented in the operator family via
+ an implicit or binary coercion cast must not change the computed hash value.
+ Notice that there is only one support function per data type, not one
+ per equality operator. It is recommended that a family be complete, i.e.,
+ provide an equality operator for each combination of data types.
+ Each operator class should include just the non-cross-type equality
+ operator and the support function for its data type.
+ </p><p>
+ GiST, SP-GiST, and GIN indexes do not have any explicit notion of
+ cross-data-type operations. The set of operators supported is just
+ whatever the primary support functions for a given operator class can
+ handle.
+ </p><p>
+ In BRIN, the requirements depends on the framework that provides the
+ operator classes. For operator classes based on <code class="literal">minmax</code>,
+ the behavior required is the same as for B-tree operator families:
+ all the operators in the family must sort compatibly, and casts must
+ not change the associated sort ordering.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Prior to <span class="productname">PostgreSQL</span> 8.3, there was no concept
+ of operator families, and so any cross-data-type operators intended to be
+ used with an index had to be bound directly into the index's operator
+ class. While this approach still works, it is deprecated because it
+ makes an index's dependencies too broad, and because the planner can
+ handle cross-data-type comparisons more effectively when both data types
+ have operators in the same operator family.
+ </p></div></div><div class="sect2" id="XINDEX-OPCLASS-DEPENDENCIES"><div class="titlepage"><div><div><h3 class="title">38.16.6. System Dependencies on Operator Classes</h3></div></div></div><a id="id-1.8.3.19.10.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> uses operator classes to infer the
+ properties of operators in more ways than just whether they can be used
+ with indexes. Therefore, you might want to create operator classes
+ even if you have no intention of indexing any columns of your data type.
+ </p><p>
+ In particular, there are SQL features such as <code class="literal">ORDER BY</code> and
+ <code class="literal">DISTINCT</code> that require comparison and sorting of values.
+ To implement these features on a user-defined data type,
+ <span class="productname">PostgreSQL</span> looks for the default B-tree operator
+ class for the data type. The <span class="quote">“<span class="quote">equals</span>”</span> member of this operator
+ class defines the system's notion of equality of values for
+ <code class="literal">GROUP BY</code> and <code class="literal">DISTINCT</code>, and the sort ordering
+ imposed by the operator class defines the default <code class="literal">ORDER BY</code>
+ ordering.
+ </p><p>
+ If there is no default B-tree operator class for a data type, the system
+ will look for a default hash operator class. But since that kind of
+ operator class only provides equality, it is only able to support grouping
+ not sorting.
+ </p><p>
+ When there is no default operator class for a data type, you will get
+ errors like <span class="quote">“<span class="quote">could not identify an ordering operator</span>”</span> if you
+ try to use these SQL features with the data type.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ In <span class="productname">PostgreSQL</span> versions before 7.4,
+ sorting and grouping operations would implicitly use operators named
+ <code class="literal">=</code>, <code class="literal">&lt;</code>, and <code class="literal">&gt;</code>. The new
+ behavior of relying on default operator classes avoids having to make
+ any assumption about the behavior of operators with particular names.
+ </p></div><p>
+ Sorting by a non-default B-tree operator class is possible by specifying
+ the class's less-than operator in a <code class="literal">USING</code> option,
+ for example
+</p><pre class="programlisting">
+SELECT * FROM mytable ORDER BY somecol USING ~&lt;~;
+</pre><p>
+ Alternatively, specifying the class's greater-than operator
+ in <code class="literal">USING</code> selects a descending-order sort.
+ </p><p>
+ Comparison of arrays of a user-defined type also relies on the semantics
+ defined by the type's default B-tree operator class. If there is no
+ default B-tree operator class, but there is a default hash operator class,
+ then array equality is supported, but not ordering comparisons.
+ </p><p>
+ Another SQL feature that requires even more data-type-specific knowledge
+ is the <code class="literal">RANGE</code> <em class="replaceable"><code>offset</code></em>
+ <code class="literal">PRECEDING</code>/<code class="literal">FOLLOWING</code> framing option
+ for window functions (see <a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. Window Function Calls">Section 4.2.8</a>).
+ For a query such as
+</p><pre class="programlisting">
+SELECT sum(x) OVER (ORDER BY x RANGE BETWEEN 5 PRECEDING AND 10 FOLLOWING)
+ FROM mytable;
+</pre><p>
+ it is not sufficient to know how to order by <code class="literal">x</code>;
+ the database must also understand how to <span class="quote">“<span class="quote">subtract 5</span>”</span> or
+ <span class="quote">“<span class="quote">add 10</span>”</span> to the current row's value of <code class="literal">x</code>
+ to identify the bounds of the current window frame. Comparing the
+ resulting bounds to other rows' values of <code class="literal">x</code> is
+ possible using the comparison operators provided by the B-tree operator
+ class that defines the <code class="literal">ORDER BY</code> ordering — but
+ addition and subtraction operators are not part of the operator class, so
+ which ones should be used? Hard-wiring that choice would be undesirable,
+ because different sort orders (different B-tree operator classes) might
+ need different behavior. Therefore, a B-tree operator class can specify
+ an <em class="firstterm">in_range</em> support function that encapsulates the
+ addition and subtraction behaviors that make sense for its sort order.
+ It can even provide more than one in_range support function, in case
+ there is more than one data type that makes sense to use as the offset
+ in <code class="literal">RANGE</code> clauses.
+ If the B-tree operator class associated with the window's <code class="literal">ORDER
+ BY</code> clause does not have a matching in_range support function,
+ the <code class="literal">RANGE</code> <em class="replaceable"><code>offset</code></em>
+ <code class="literal">PRECEDING</code>/<code class="literal">FOLLOWING</code>
+ option is not supported.
+ </p><p>
+ Another important point is that an equality operator that
+ appears in a hash operator family is a candidate for hash joins,
+ hash aggregation, and related optimizations. The hash operator family
+ is essential here since it identifies the hash function(s) to use.
+ </p></div><div class="sect2" id="XINDEX-ORDERING-OPS"><div class="titlepage"><div><div><h3 class="title">38.16.7. Ordering Operators</h3></div></div></div><p>
+ Some index access methods (currently, only GiST and SP-GiST) support the concept of
+ <em class="firstterm">ordering operators</em>. What we have been discussing so far
+ are <em class="firstterm">search operators</em>. A search operator is one for which
+ the index can be searched to find all rows satisfying
+ <code class="literal">WHERE</code>
+ <em class="replaceable"><code>indexed_column</code></em>
+ <em class="replaceable"><code>operator</code></em>
+ <em class="replaceable"><code>constant</code></em>.
+ Note that nothing is promised about the order in which the matching rows
+ will be returned. In contrast, an ordering operator does not restrict the
+ set of rows that can be returned, but instead determines their order.
+ An ordering operator is one for which the index can be scanned to return
+ rows in the order represented by
+ <code class="literal">ORDER BY</code>
+ <em class="replaceable"><code>indexed_column</code></em>
+ <em class="replaceable"><code>operator</code></em>
+ <em class="replaceable"><code>constant</code></em>.
+ The reason for defining ordering operators that way is that it supports
+ nearest-neighbor searches, if the operator is one that measures distance.
+ For example, a query like
+</p><pre class="programlisting">
+SELECT * FROM places ORDER BY location &lt;-&gt; point '(101,456)' LIMIT 10;
+
+</pre><p>
+ finds the ten places closest to a given target point. A GiST index
+ on the location column can do this efficiently because
+ <code class="literal">&lt;-&gt;</code> is an ordering operator.
+ </p><p>
+ While search operators have to return Boolean results, ordering operators
+ usually return some other type, such as float or numeric for distances.
+ This type is normally not the same as the data type being indexed.
+ To avoid hard-wiring assumptions about the behavior of different data
+ types, the definition of an ordering operator is required to name
+ a B-tree operator family that specifies the sort ordering of the result
+ data type. As was stated in the previous section, B-tree operator families
+ define <span class="productname">PostgreSQL</span>'s notion of ordering, so
+ this is a natural representation. Since the point <code class="literal">&lt;-&gt;</code>
+ operator returns <code class="type">float8</code>, it could be specified in an operator
+ class creation command like this:
+</p><pre class="programlisting">
+OPERATOR 15 &lt;-&gt; (point, point) FOR ORDER BY float_ops
+
+</pre><p>
+ where <code class="literal">float_ops</code> is the built-in operator family that includes
+ operations on <code class="type">float8</code>. This declaration states that the index
+ is able to return rows in order of increasing values of the
+ <code class="literal">&lt;-&gt;</code> operator.
+ </p></div><div class="sect2" id="XINDEX-OPCLASS-FEATURES"><div class="titlepage"><div><div><h3 class="title">38.16.8. Special Features of Operator Classes</h3></div></div></div><p>
+ There are two special features of operator classes that we have
+ not discussed yet, mainly because they are not useful
+ with the most commonly used index methods.
+ </p><p>
+ Normally, declaring an operator as a member of an operator class
+ (or family) means that the index method can retrieve exactly the set of rows
+ that satisfy a <code class="literal">WHERE</code> condition using the operator. For example:
+</p><pre class="programlisting">
+SELECT * FROM table WHERE integer_column &lt; 4;
+</pre><p>
+ can be satisfied exactly by a B-tree index on the integer column.
+ But there are cases where an index is useful as an inexact guide to
+ the matching rows. For example, if a GiST index stores only bounding boxes
+ for geometric objects, then it cannot exactly satisfy a <code class="literal">WHERE</code>
+ condition that tests overlap between nonrectangular objects such as
+ polygons. Yet we could use the index to find objects whose bounding
+ box overlaps the bounding box of the target object, and then do the
+ exact overlap test only on the objects found by the index. If this
+ scenario applies, the index is said to be <span class="quote">“<span class="quote">lossy</span>”</span> for the
+ operator. Lossy index searches are implemented by having the index
+ method return a <em class="firstterm">recheck</em> flag when a row might or might
+ not really satisfy the query condition. The core system will then
+ test the original query condition on the retrieved row to see whether
+ it should be returned as a valid match. This approach works if
+ the index is guaranteed to return all the required rows, plus perhaps
+ some additional rows, which can be eliminated by performing the original
+ operator invocation. The index methods that support lossy searches
+ (currently, GiST, SP-GiST and GIN) allow the support functions of individual
+ operator classes to set the recheck flag, and so this is essentially an
+ operator-class feature.
+ </p><p>
+ Consider again the situation where we are storing in the index only
+ the bounding box of a complex object such as a polygon. In this
+ case there's not much value in storing the whole polygon in the index
+ entry — we might as well store just a simpler object of type
+ <code class="type">box</code>. This situation is expressed by the <code class="literal">STORAGE</code>
+ option in <code class="command">CREATE OPERATOR CLASS</code>: we'd write something like:
+
+</p><pre class="programlisting">
+CREATE OPERATOR CLASS polygon_ops
+ DEFAULT FOR TYPE polygon USING gist AS
+ ...
+ STORAGE box;
+</pre><p>
+
+ At present, only the GiST, SP-GiST, GIN and BRIN index methods support a
+ <code class="literal">STORAGE</code> type that's different from the column data type.
+ The GiST <code class="function">compress</code> and <code class="function">decompress</code> support
+ routines must deal with data-type conversion when <code class="literal">STORAGE</code>
+ is used. SP-GiST likewise requires a <code class="function">compress</code>
+ support function to convert to the storage type, when that is different;
+ if an SP-GiST opclass also supports retrieving data, the reverse
+ conversion must be handled by the <code class="function">consistent</code> function.
+ In GIN, the <code class="literal">STORAGE</code> type identifies the type of
+ the <span class="quote">“<span class="quote">key</span>”</span> values, which normally is different from the type
+ of the indexed column — for example, an operator class for
+ integer-array columns might have keys that are just integers. The
+ GIN <code class="function">extractValue</code> and <code class="function">extractQuery</code> support
+ routines are responsible for extracting keys from indexed values.
+ BRIN is similar to GIN: the <code class="literal">STORAGE</code> type identifies the
+ type of the stored summary values, and operator classes' support
+ procedures are responsible for interpreting the summary values
+ correctly.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xoper-optimization.html" title="38.15. Operator Optimization Information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.15. Operator Optimization Information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.17. Packaging Related Objects into an Extension</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xml-limits-conformance.html b/doc/src/sgml/html/xml-limits-conformance.html
new file mode 100644
index 0000000..010d67d
--- /dev/null
+++ b/doc/src/sgml/html/xml-limits-conformance.html
@@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>D.3. XML Limits and Conformance to SQL/XML</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features" /><link rel="next" href="release.html" title="Appendix E. Release Notes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">D.3. XML Limits and Conformance to SQL/XML</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><th width="60%" align="center">Appendix D. SQL Conformance</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="release.html" title="Appendix E. Release Notes">Next</a></td></tr></table><hr /></div><div class="sect1" id="XML-LIMITS-CONFORMANCE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">D.3. XML Limits and Conformance to SQL/XML</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1">D.3.1. Queries Are Restricted to XPath 1.0</a></span></dt><dt><span class="sect2"><a href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL">D.3.2. Incidental Limits of the Implementation</a></span></dt></dl></div><a id="id-1.11.5.13.2" class="indexterm"></a><p>
+ Significant revisions to the XML-related specifications in ISO/IEC 9075-14
+ (SQL/XML) were introduced with SQL:2006.
+ <span class="productname">PostgreSQL</span>'s implementation of the XML data
+ type and related functions largely follows the earlier 2003 edition,
+ with some borrowing from later editions. In particular:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Where the current standard provides a family of XML data types
+ to hold <span class="quote">“<span class="quote">document</span>”</span> or <span class="quote">“<span class="quote">content</span>”</span> in
+ untyped or XML Schema-typed variants, and a type
+ <code class="type">XML(SEQUENCE)</code> to hold arbitrary pieces of XML content,
+ <span class="productname">PostgreSQL</span> provides the single
+ <code class="type">xml</code> type, which can hold <span class="quote">“<span class="quote">document</span>”</span> or
+ <span class="quote">“<span class="quote">content</span>”</span>. There is no equivalent of the
+ standard's <span class="quote">“<span class="quote">sequence</span>”</span> type.
+ </p></li><li class="listitem"><p>
+ <span class="productname">PostgreSQL</span> provides two functions
+ introduced in SQL:2006, but in variants that use the XPath 1.0
+ language, rather than XML Query as specified for them in the
+ standard.
+ </p></li></ul></div><p>
+ </p><p>
+ This section presents some of the resulting differences you may encounter.
+ </p><div class="sect2" id="FUNCTIONS-XML-LIMITS-XPATH1"><div class="titlepage"><div><div><h3 class="title">D.3.1. Queries Are Restricted to XPath 1.0</h3></div></div></div><p>
+ The <span class="productname">PostgreSQL</span>-specific functions
+ <code class="function">xpath()</code> and <code class="function">xpath_exists()</code>
+ query XML documents using the XPath language.
+ <span class="productname">PostgreSQL</span> also provides XPath-only variants
+ of the standard functions <code class="function">XMLEXISTS</code> and
+ <code class="function">XMLTABLE</code>, which officially use
+ the XQuery language. For all of these functions,
+ <span class="productname">PostgreSQL</span> relies on the
+ <span class="application">libxml2</span> library, which provides only XPath 1.0.
+ </p><p>
+ There is a strong connection between the XQuery language and XPath
+ versions 2.0 and later: any expression that is syntactically valid and
+ executes successfully in both produces the same result (with a minor
+ exception for expressions containing numeric character references or
+ predefined entity references, which XQuery replaces with the
+ corresponding character while XPath leaves them alone). But there is
+ no such connection between these languages and XPath 1.0; it was an
+ earlier language and differs in many respects.
+ </p><p>
+ There are two categories of limitation to keep in mind: the restriction
+ from XQuery to XPath for the functions specified in the SQL standard, and
+ the restriction of XPath to version 1.0 for both the standard and the
+ <span class="productname">PostgreSQL</span>-specific functions.
+ </p><div class="sect3" id="id-1.11.5.13.5.5"><div class="titlepage"><div><div><h4 class="title">D.3.1.1. Restriction of XQuery to XPath</h4></div></div></div><p>
+ Features of XQuery beyond those of XPath include:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ XQuery expressions can construct and return new XML nodes, in
+ addition to all possible XPath values. XPath can create and return
+ values of the atomic types (numbers, strings, and so on) but can
+ only return XML nodes that were already present in documents
+ supplied as input to the expression.
+ </p></li><li class="listitem"><p>
+ XQuery has control constructs for iteration, sorting, and grouping.
+ </p></li><li class="listitem"><p>
+ XQuery allows declaration and use of local functions.
+ </p></li></ul></div><p>
+ </p><p>
+ Recent XPath versions begin to offer capabilities overlapping with
+ these (such as functional-style <code class="function">for-each</code> and
+ <code class="function">sort</code>, anonymous functions, and
+ <code class="function">parse-xml</code> to create a node from a string),
+ but such features were not available before XPath 3.0.
+ </p></div><div class="sect3" id="XML-XPATH-1-SPECIFICS"><div class="titlepage"><div><div><h4 class="title">D.3.1.2. Restriction of XPath to 1.0</h4></div></div></div><p>
+ For developers familiar with XQuery and XPath 2.0 or later, XPath 1.0
+ presents a number of differences to contend with:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ The fundamental type of an XQuery/XPath expression, the
+ <code class="type">sequence</code>, which can contain XML nodes, atomic values,
+ or both, does not exist in XPath 1.0. A 1.0 expression can only
+ produce a node-set (containing zero or more XML nodes), or a single
+ atomic value.
+ </p></li><li class="listitem"><p>
+ Unlike an XQuery/XPath sequence, which can contain any desired
+ items in any desired order, an XPath 1.0 node-set has no
+ guaranteed order and, like any set, does not allow multiple
+ appearances of the same item.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The <span class="application">libxml2</span> library does seem to
+ always return node-sets to <span class="productname">PostgreSQL</span>
+ with their members in the same relative order they had in the
+ input document. Its documentation does not commit to this
+ behavior, and an XPath 1.0 expression cannot control it.
+ </p></div><p>
+ </p></li><li class="listitem"><p>
+ While XQuery/XPath provides all of the types defined in XML Schema
+ and many operators and functions over those types, XPath 1.0 has only
+ node-sets and the three atomic types <code class="type">boolean</code>,
+ <code class="type">double</code>, and <code class="type">string</code>.
+ </p></li><li class="listitem"><p>
+ XPath 1.0 has no conditional operator. An XQuery/XPath expression
+ such as <code class="literal">if ( hat ) then hat/@size else "no hat"</code>
+ has no XPath 1.0 equivalent.
+ </p></li><li class="listitem"><p>
+ XPath 1.0 has no ordering comparison operator for strings. Both
+ <code class="literal">"cat" &lt; "dog"</code> and
+ <code class="literal">"cat" &gt; "dog"</code> are false, because each is a
+ numeric comparison of two <code class="literal">NaN</code>s. In contrast,
+ <code class="literal">=</code> and <code class="literal">!=</code> do compare the strings
+ as strings.
+ </p></li><li class="listitem"><p>
+ XPath 1.0 blurs the distinction between
+ <em class="firstterm">value comparisons</em> and
+ <em class="firstterm">general comparisons</em> as XQuery/XPath define
+ them. Both <code class="literal">sale/@hatsize = 7</code> and
+ <code class="literal">sale/@customer = "alice"</code> are existentially
+ quantified comparisons, true if there is
+ any <code class="literal">sale</code> with the given value for the
+ attribute, but <code class="literal">sale/@taxable = false()</code> is a
+ value comparison to the
+ <em class="firstterm">effective boolean value</em> of a whole node-set.
+ It is true only if no <code class="literal">sale</code> has
+ a <code class="literal">taxable</code> attribute at all.
+ </p></li><li class="listitem"><p>
+ In the XQuery/XPath data model, a <em class="firstterm">document
+ node</em> can have either document form (i.e., exactly one
+ top-level element, with only comments and processing instructions
+ outside of it) or content form (with those constraints
+ relaxed). Its equivalent in XPath 1.0, the
+ <em class="firstterm">root node</em>, can only be in document form.
+ This is part of the reason an <code class="type">xml</code> value passed as the
+ context item to any <span class="productname">PostgreSQL</span>
+ XPath-based function must be in document form.
+ </p></li></ul></div><p>
+ </p><p>
+ The differences highlighted here are not all of them. In XQuery and
+ the 2.0 and later versions of XPath, there is an XPath 1.0 compatibility
+ mode, and the W3C lists of
+ <a class="ulink" href="https://www.w3.org/TR/2010/REC-xpath-functions-20101214/#xpath1-compatibility" target="_top">function library changes</a>
+ and
+ <a class="ulink" href="https://www.w3.org/TR/xpath20/#id-backwards-compatibility" target="_top">language changes</a>
+ applied in that mode offer a more complete (but still not exhaustive)
+ account of the differences. The compatibility mode cannot make the
+ later languages exactly equivalent to XPath 1.0.
+ </p></div><div class="sect3" id="FUNCTIONS-XML-LIMITS-CASTS"><div class="titlepage"><div><div><h4 class="title">D.3.1.3. Mappings between SQL and XML Data Types and Values</h4></div></div></div><p>
+ In SQL:2006 and later, both directions of conversion between standard SQL
+ data types and the XML Schema types are specified precisely. However, the
+ rules are expressed using the types and semantics of XQuery/XPath, and
+ have no direct application to the different data model of XPath 1.0.
+ </p><p>
+ When <span class="productname">PostgreSQL</span> maps SQL data values to XML
+ (as in <code class="function">xmlelement</code>), or XML to SQL (as in the output
+ columns of <code class="function">xmltable</code>), except for a few cases
+ treated specially, <span class="productname">PostgreSQL</span> simply assumes
+ that the XML data type's XPath 1.0 string form will be valid as the
+ text-input form of the SQL datatype, and conversely. This rule has the
+ virtue of simplicity while producing, for many data types, results similar
+ to the mappings specified in the standard.
+ </p><p>
+ Where interoperability with other systems is a concern, for some data
+ types, it may be necessary to use data type formatting functions (such
+ as those in <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>) explicitly to
+ produce the standard mappings.
+ </p></div></div><div class="sect2" id="FUNCTIONS-XML-LIMITS-POSTGRESQL"><div class="titlepage"><div><div><h3 class="title">D.3.2. Incidental Limits of the Implementation</h3></div></div></div><p>
+ This section concerns limits that are not inherent in the
+ <span class="application">libxml2</span> library, but apply to the current
+ implementation in <span class="productname">PostgreSQL</span>.
+ </p><div class="sect3" id="id-1.11.5.13.6.3"><div class="titlepage"><div><div><h4 class="title">D.3.2.1. Only <code class="literal">BY VALUE</code> Passing Mechanism Is Supported</h4></div></div></div><p>
+ The SQL standard defines two <em class="firstterm">passing mechanisms</em>
+ that apply when passing an XML argument from SQL to an XML function or
+ receiving a result: <code class="literal">BY REF</code>, in which a particular XML
+ value retains its node identity, and <code class="literal">BY VALUE</code>, in which
+ the content of the XML is passed but node identity is not preserved. A
+ mechanism can be specified before a list of parameters, as the default
+ mechanism for all of them, or after any parameter, to override the
+ default.
+ </p><p>
+ To illustrate the difference, if
+ <em class="replaceable"><code>x</code></em> is an XML value, these two queries in
+ an SQL:2006 environment would produce true and false, respectively:
+
+</p><pre class="programlisting">
+SELECT XMLQUERY('$a is $b' PASSING BY REF <em class="replaceable"><code>x</code></em> AS a, <em class="replaceable"><code>x</code></em> AS b NULL ON EMPTY);
+SELECT XMLQUERY('$a is $b' PASSING BY VALUE <em class="replaceable"><code>x</code></em> AS a, <em class="replaceable"><code>x</code></em> AS b NULL ON EMPTY);
+</pre><p>
+ </p><p>
+ <span class="productname">PostgreSQL</span> will accept
+ <code class="literal">BY VALUE</code> or <code class="literal">BY REF</code> in an
+ <code class="function">XMLEXISTS</code> or <code class="function">XMLTABLE</code>
+ construct, but it ignores them. The <code class="type">xml</code> data type holds
+ a character-string serialized representation, so there is no node
+ identity to preserve, and passing is always effectively <code class="literal">BY
+ VALUE</code>.
+ </p></div><div class="sect3" id="id-1.11.5.13.6.4"><div class="titlepage"><div><div><h4 class="title">D.3.2.2. Cannot Pass Named Parameters to Queries</h4></div></div></div><p>
+ The XPath-based functions support passing one parameter to serve as the
+ XPath expression's context item, but do not support passing additional
+ values to be available to the expression as named parameters.
+ </p></div><div class="sect3" id="id-1.11.5.13.6.5"><div class="titlepage"><div><div><h4 class="title">D.3.2.3. No <code class="type">XML(SEQUENCE)</code> Type</h4></div></div></div><p>
+ The <span class="productname">PostgreSQL</span> <code class="type">xml</code> data type
+ can only hold a value in <code class="literal">DOCUMENT</code>
+ or <code class="literal">CONTENT</code> form. An XQuery/XPath expression
+ context item must be a single XML node or atomic value, but XPath 1.0
+ further restricts it to be only an XML node, and has no node type
+ allowing <code class="literal">CONTENT</code>. The upshot is that a
+ well-formed <code class="literal">DOCUMENT</code> is the only form of XML value
+ that <span class="productname">PostgreSQL</span> can supply as an XPath
+ context item.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unsupported-features-sql-standard.html" title="D.2. Unsupported Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="features.html" title="Appendix D. SQL Conformance">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="release.html" title="Appendix E. Release Notes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">D.2. Unsupported Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix E. Release Notes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xml2.html b/doc/src/sgml/html/xml2.html
new file mode 100644
index 0000000..dc2b870
--- /dev/null
+++ b/doc/src/sgml/html/xml2.html
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.50. xml2</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="uuid-ossp.html" title="F.49. uuid-ossp" /><link rel="next" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.50. xml2</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="uuid-ossp.html" title="F.49. uuid-ossp">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="XML2"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.50. xml2</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.4">F.50.1. Deprecation Notice</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.5">F.50.2. Description of Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.6">F.50.3. <code class="literal">xpath_table</code></a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.7">F.50.4. XSLT Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#id-1.11.7.59.8">F.50.5. Author</a></span></dt></dl></div><a id="id-1.11.7.59.2" class="indexterm"></a><p>
+ The <code class="filename">xml2</code> module provides XPath querying and
+ XSLT functionality.
+ </p><div class="sect2" id="id-1.11.7.59.4"><div class="titlepage"><div><div><h3 class="title">F.50.1. Deprecation Notice</h3></div></div></div><p>
+ From <span class="productname">PostgreSQL</span> 8.3 on, there is XML-related
+ functionality based on the SQL/XML standard in the core server.
+ That functionality covers XML syntax checking and XPath queries,
+ which is what this module does, and more, but the API is
+ not at all compatible. It is planned that this module will be
+ removed in a future version of PostgreSQL in favor of the newer standard API, so
+ you are encouraged to try converting your applications. If you
+ find that some of the functionality of this module is not
+ available in an adequate form with the newer API, please explain
+ your issue to <code class="email">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</code> so that the deficiency
+ can be addressed.
+ </p></div><div class="sect2" id="id-1.11.7.59.5"><div class="titlepage"><div><div><h3 class="title">F.50.2. Description of Functions</h3></div></div></div><p>
+ <a class="xref" href="xml2.html#XML2-FUNCTIONS-TABLE" title="Table F.34. xml2 Functions">Table F.34</a> shows the functions provided by this module.
+ These functions provide straightforward XML parsing and XPath queries.
+ </p><div class="table" id="XML2-FUNCTIONS-TABLE"><p class="title"><strong>Table F.34. <code class="filename">xml2</code> Functions</strong></p><div class="table-contents"><table class="table" summary="xml2 Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+ Function
+ </p>
+ <p>
+ Description
+ </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xml_valid</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Parses the given document and returns true if the
+ document is well-formed XML. (Note: this is an alias for the standard
+ PostgreSQL function <code class="function">xml_is_well_formed()</code>. The
+ name <code class="function">xml_valid()</code> is technically incorrect since validity
+ and well-formedness have different meanings in XML.)
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_string</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <code class="type">text</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_number</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">real</code>
+ </p>
+ <p>
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <code class="type">real</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_bool</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">boolean</code>
+ </p>
+ <p>
+ Evaluates the XPath query on the supplied document, and
+ casts the result to <code class="type">boolean</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>toptag</code></em> <code class="type">text</code>, <em class="parameter"><code>itemtag</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Evaluates the query on the document and wraps the result in XML
+ tags. If the result is multivalued, the output will look like:
+</p><pre class="synopsis">
+&lt;toptag&gt;
+&lt;itemtag&gt;Value 1 which could be an XML fragment&lt;/itemtag&gt;
+&lt;itemtag&gt;Value 2....&lt;/itemtag&gt;
+&lt;/toptag&gt;
+</pre><p>
+ If either <em class="parameter"><code>toptag</code></em>
+ or <em class="parameter"><code>itemtag</code></em> is an empty string, the relevant tag
+ is omitted.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>itemtag</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Like <code class="function">xpath_nodeset(document, query, toptag, itemtag)</code> but result omits <em class="parameter"><code>toptag</code></em>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Like <code class="function">xpath_nodeset(document, query, toptag, itemtag)</code> but result omits both tags.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_list</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>separator</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ Evaluates the query on the document and returns multiple values
+ separated by the specified separator, for example <code class="literal">Value
+ 1,Value 2,Value 3</code> if <em class="parameter"><code>separator</code></em>
+ is <code class="literal">,</code>.
+ </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+ <code class="function">xpath_list</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
+ → <code class="returnvalue">text</code>
+ </p>
+ <p>
+ This is a wrapper for the above function that uses <code class="literal">,</code>
+ as the separator.
+ </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="id-1.11.7.59.6"><div class="titlepage"><div><div><h3 class="title">F.50.3. <code class="literal">xpath_table</code></h3></div></div></div><a id="id-1.11.7.59.6.2" class="indexterm"></a><pre class="synopsis">
+xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record
+</pre><p>
+ <code class="function">xpath_table</code> is a table function that evaluates a set of XPath
+ queries on each of a set of documents and returns the results as a
+ table. The primary key field from the original document table is returned
+ as the first column of the result so that the result set
+ can readily be used in joins. The parameters are described in
+ <a class="xref" href="xml2.html#XML2-XPATH-TABLE-PARAMETERS" title="Table F.35. xpath_table Parameters">Table F.35</a>.
+ </p><div class="table" id="XML2-XPATH-TABLE-PARAMETERS"><p class="title"><strong>Table F.35. <code class="function">xpath_table</code> Parameters</strong></p><div class="table-contents"><table class="table" summary="xpath_table Parameters" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>key</code></em></td><td>
+ <p>
+ the name of the <span class="quote">“<span class="quote">key</span>”</span> field — this is just a field to be used as
+ the first column of the output table, i.e., it identifies the record from
+ which each output row came (see note below about multiple values)
+ </p>
+ </td></tr><tr><td><em class="parameter"><code>document</code></em></td><td>
+ <p>
+ the name of the field containing the XML document
+ </p>
+ </td></tr><tr><td><em class="parameter"><code>relation</code></em></td><td>
+ <p>
+ the name of the table or view containing the documents
+ </p>
+ </td></tr><tr><td><em class="parameter"><code>xpaths</code></em></td><td>
+ <p>
+ one or more XPath expressions, separated by <code class="literal">|</code>
+ </p>
+ </td></tr><tr><td><em class="parameter"><code>criteria</code></em></td><td>
+ <p>
+ the contents of the WHERE clause. This cannot be omitted, so use
+ <code class="literal">true</code> or <code class="literal">1=1</code> if you want to
+ process all the rows in the relation
+ </p>
+ </td></tr></tbody></table></div></div><br class="table-break" /><p>
+ These parameters (except the XPath strings) are just substituted
+ into a plain SQL SELECT statement, so you have some flexibility — the
+ statement is
+ </p><p>
+ <code class="literal">
+ SELECT &lt;key&gt;, &lt;document&gt; FROM &lt;relation&gt; WHERE &lt;criteria&gt;
+ </code>
+ </p><p>
+ so those parameters can be <span class="emphasis"><em>anything</em></span> valid in those particular
+ locations. The result from this SELECT needs to return exactly two
+ columns (which it will unless you try to list multiple fields for key
+ or document). Beware that this simplistic approach requires that you
+ validate any user-supplied values to avoid SQL injection attacks.
+ </p><p>
+ The function has to be used in a <code class="literal">FROM</code> expression, with an
+ <code class="literal">AS</code> clause to specify the output columns; for example
+</p><pre class="programlisting">
+SELECT * FROM
+xpath_table('article_id',
+ 'article_xml',
+ 'articles',
+ '/article/author|/article/pages|/article/title',
+ 'date_entered &gt; ''2003-01-01'' ')
+AS t(article_id integer, author text, page_count integer, title text);
+</pre><p>
+ The <code class="literal">AS</code> clause defines the names and types of the columns in the
+ output table. The first is the <span class="quote">“<span class="quote">key</span>”</span> field and the rest correspond
+ to the XPath queries.
+ If there are more XPath queries than result columns,
+ the extra queries will be ignored. If there are more result columns
+ than XPath queries, the extra columns will be NULL.
+ </p><p>
+ Notice that this example defines the <code class="structname">page_count</code> result
+ column as an integer. The function deals internally with string
+ representations, so when you say you want an integer in the output, it will
+ take the string representation of the XPath result and use PostgreSQL input
+ functions to transform it into an integer (or whatever type the <code class="type">AS</code>
+ clause requests). An error will result if it can't do this — for
+ example if the result is empty — so you may wish to just stick to
+ <code class="type">text</code> as the column type if you think your data has any problems.
+ </p><p>
+ The calling <code class="command">SELECT</code> statement doesn't necessarily have to be
+ just <code class="literal">SELECT *</code> — it can reference the output
+ columns by name or join them to other tables. The function produces a
+ virtual table with which you can perform any operation you wish (e.g.,
+ aggregation, joining, sorting etc.). So we could also have:
+</p><pre class="programlisting">
+SELECT t.title, p.fullname, p.email
+FROM xpath_table('article_id', 'article_xml', 'articles',
+ '/article/title|/article/author/@id',
+ 'xpath_string(article_xml,''/article/@date'') &gt; ''2003-03-20'' ')
+ AS t(article_id integer, title text, author_id integer),
+ tblPeopleInfo AS p
+WHERE t.author_id = p.person_id;
+</pre><p>
+ as a more complicated example. Of course, you could wrap all
+ of this in a view for convenience.
+ </p><div class="sect3" id="id-1.11.7.59.6.12"><div class="titlepage"><div><div><h4 class="title">F.50.3.1. Multivalued Results</h4></div></div></div><p>
+ The <code class="function">xpath_table</code> function assumes that the results of each XPath query
+ might be multivalued, so the number of rows returned by the function
+ may not be the same as the number of input documents. The first row
+ returned contains the first result from each query, the second row the
+ second result from each query. If one of the queries has fewer values
+ than the others, null values will be returned instead.
+ </p><p>
+ In some cases, a user will know that a given XPath query will return
+ only a single result (perhaps a unique document identifier) — if used
+ alongside an XPath query returning multiple results, the single-valued
+ result will appear only on the first row of the result. The solution
+ to this is to use the key field as part of a join against a simpler
+ XPath query. As an example:
+
+</p><pre class="programlisting">
+CREATE TABLE test (
+ id int PRIMARY KEY,
+ xml text
+);
+
+INSERT INTO test VALUES (1, '&lt;doc num="C1"&gt;
+&lt;line num="L1"&gt;&lt;a&gt;1&lt;/a&gt;&lt;b&gt;2&lt;/b&gt;&lt;c&gt;3&lt;/c&gt;&lt;/line&gt;
+&lt;line num="L2"&gt;&lt;a&gt;11&lt;/a&gt;&lt;b&gt;22&lt;/b&gt;&lt;c&gt;33&lt;/c&gt;&lt;/line&gt;
+&lt;/doc&gt;');
+
+INSERT INTO test VALUES (2, '&lt;doc num="C2"&gt;
+&lt;line num="L1"&gt;&lt;a&gt;111&lt;/a&gt;&lt;b&gt;222&lt;/b&gt;&lt;c&gt;333&lt;/c&gt;&lt;/line&gt;
+&lt;line num="L2"&gt;&lt;a&gt;111&lt;/a&gt;&lt;b&gt;222&lt;/b&gt;&lt;c&gt;333&lt;/c&gt;&lt;/line&gt;
+&lt;/doc&gt;');
+
+SELECT * FROM
+ xpath_table('id','xml','test',
+ '/doc/@num|/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
+ 'true')
+ AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int)
+WHERE id = 1 ORDER BY doc_num, line_num
+
+ id | doc_num | line_num | val1 | val2 | val3
+----+---------+----------+------+------+------
+ 1 | C1 | L1 | 1 | 2 | 3
+ 1 | | L2 | 11 | 22 | 33
+</pre><p>
+ </p><p>
+ To get <code class="literal">doc_num</code> on every line, the solution is to use two invocations
+ of <code class="function">xpath_table</code> and join the results:
+
+</p><pre class="programlisting">
+SELECT t.*,i.doc_num FROM
+ xpath_table('id', 'xml', 'test',
+ '/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
+ 'true')
+ AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int),
+ xpath_table('id', 'xml', 'test', '/doc/@num', 'true')
+ AS i(id int, doc_num varchar(10))
+WHERE i.id=t.id AND i.id=1
+ORDER BY doc_num, line_num;
+
+ id | line_num | val1 | val2 | val3 | doc_num
+----+----------+------+------+------+---------
+ 1 | L1 | 1 | 2 | 3 | C1
+ 1 | L2 | 11 | 22 | 33 | C1
+(2 rows)
+</pre><p>
+ </p></div></div><div class="sect2" id="id-1.11.7.59.7"><div class="titlepage"><div><div><h3 class="title">F.50.4. XSLT Functions</h3></div></div></div><p>
+ The following functions are available if libxslt is installed:
+ </p><div class="sect3" id="id-1.11.7.59.7.3"><div class="titlepage"><div><div><h4 class="title">F.50.4.1. <code class="literal">xslt_process</code></h4></div></div></div><a id="id-1.11.7.59.7.3.2" class="indexterm"></a><pre class="synopsis">
+xslt_process(text document, text stylesheet, text paramlist) returns text
+</pre><p>
+ This function applies the XSL stylesheet to the document and returns
+ the transformed result. The <code class="literal">paramlist</code> is a list of parameter
+ assignments to be used in the transformation, specified in the form
+ <code class="literal">a=1,b=2</code>. Note that the
+ parameter parsing is very simple-minded: parameter values cannot
+ contain commas!
+ </p><p>
+ There is also a two-parameter version of <code class="function">xslt_process</code> which
+ does not pass any parameters to the transformation.
+ </p></div></div><div class="sect2" id="id-1.11.7.59.8"><div class="titlepage"><div><div><h3 class="title">F.50.5. Author</h3></div></div></div><p>
+ John Gray <code class="email">&lt;<a class="email" href="mailto:jgray@azuli.co.uk">jgray@azuli.co.uk</a>&gt;</code>
+ </p><p>
+ Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com).
+ It has the same BSD license as PostgreSQL.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="uuid-ossp.html" title="F.49. uuid-ossp">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.49. uuid-ossp </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Appendix G. Additional Supplied Programs</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xoper-optimization.html b/doc/src/sgml/html/xoper-optimization.html
new file mode 100644
index 0000000..5d13846
--- /dev/null
+++ b/doc/src/sgml/html/xoper-optimization.html
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.15. Operator Optimization Information</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xoper.html" title="38.14. User-Defined Operators" /><link rel="next" href="xindex.html" title="38.16. Interfacing Extensions to Indexes" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.15. Operator Optimization Information</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xoper.html" title="38.14. User-Defined Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Next</a></td></tr></table><hr /></div><div class="sect1" id="XOPER-OPTIMIZATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.15. Operator Optimization Information</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.6">38.15.1. <code class="literal">COMMUTATOR</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.7">38.15.2. <code class="literal">NEGATOR</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.8">38.15.3. <code class="literal">RESTRICT</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.9">38.15.4. <code class="literal">JOIN</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.10">38.15.5. <code class="literal">HASHES</code></a></span></dt><dt><span class="sect2"><a href="xoper-optimization.html#id-1.8.3.18.11">38.15.6. <code class="literal">MERGES</code></a></span></dt></dl></div><a id="id-1.8.3.18.2" class="indexterm"></a><p>
+ A <span class="productname">PostgreSQL</span> operator definition can include
+ several optional clauses that tell the system useful things about how
+ the operator behaves. These clauses should be provided whenever
+ appropriate, because they can make for considerable speedups in execution
+ of queries that use the operator. But if you provide them, you must be
+ sure that they are right! Incorrect use of an optimization clause can
+ result in slow queries, subtly wrong output, or other Bad Things.
+ You can always leave out an optimization clause if you are not sure
+ about it; the only consequence is that queries might run slower than
+ they need to.
+ </p><p>
+ Additional optimization clauses might be added in future versions of
+ <span class="productname">PostgreSQL</span>. The ones described here are all
+ the ones that release 15.5 understands.
+ </p><p>
+ It is also possible to attach a planner support function to the function
+ that underlies an operator, providing another way of telling the system
+ about the behavior of the operator.
+ See <a class="xref" href="xfunc-optimization.html" title="38.11. Function Optimization Information">Section 38.11</a> for more information.
+ </p><div class="sect2" id="id-1.8.3.18.6"><div class="titlepage"><div><div><h3 class="title">38.15.1. <code class="literal">COMMUTATOR</code></h3></div></div></div><p>
+ The <code class="literal">COMMUTATOR</code> clause, if provided, names an operator that is the
+ commutator of the operator being defined. We say that operator A is the
+ commutator of operator B if (x A y) equals (y B x) for all possible input
+ values x, y. Notice that B is also the commutator of A. For example,
+ operators <code class="literal">&lt;</code> and <code class="literal">&gt;</code> for a particular data type are usually each others'
+ commutators, and operator <code class="literal">+</code> is usually commutative with itself.
+ But operator <code class="literal">-</code> is usually not commutative with anything.
+ </p><p>
+ The left operand type of a commutable operator is the same as the
+ right operand type of its commutator, and vice versa. So the name of
+ the commutator operator is all that <span class="productname">PostgreSQL</span>
+ needs to be given to look up the commutator, and that's all that needs to
+ be provided in the <code class="literal">COMMUTATOR</code> clause.
+ </p><p>
+ It's critical to provide commutator information for operators that
+ will be used in indexes and join clauses, because this allows the
+ query optimizer to <span class="quote">“<span class="quote">flip around</span>”</span> such a clause to the forms
+ needed for different plan types. For example, consider a query with
+ a WHERE clause like <code class="literal">tab1.x = tab2.y</code>, where <code class="literal">tab1.x</code>
+ and <code class="literal">tab2.y</code> are of a user-defined type, and suppose that
+ <code class="literal">tab2.y</code> is indexed. The optimizer cannot generate an
+ index scan unless it can determine how to flip the clause around to
+ <code class="literal">tab2.y = tab1.x</code>, because the index-scan machinery expects
+ to see the indexed column on the left of the operator it is given.
+ <span class="productname">PostgreSQL</span> will <span class="emphasis"><em>not</em></span> simply
+ assume that this is a valid transformation — the creator of the
+ <code class="literal">=</code> operator must specify that it is valid, by marking the
+ operator with commutator information.
+ </p><p>
+ When you are defining a self-commutative operator, you just do it.
+ When you are defining a pair of commutative operators, things are
+ a little trickier: how can the first one to be defined refer to the
+ other one, which you haven't defined yet? There are two solutions
+ to this problem:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ One way is to omit the <code class="literal">COMMUTATOR</code> clause in the first operator that
+ you define, and then provide one in the second operator's definition.
+ Since <span class="productname">PostgreSQL</span> knows that commutative
+ operators come in pairs, when it sees the second definition it will
+ automatically go back and fill in the missing <code class="literal">COMMUTATOR</code> clause in
+ the first definition.
+ </p></li><li class="listitem"><p>
+ The other, more straightforward way is just to include <code class="literal">COMMUTATOR</code> clauses
+ in both definitions. When <span class="productname">PostgreSQL</span> processes
+ the first definition and realizes that <code class="literal">COMMUTATOR</code> refers to a nonexistent
+ operator, the system will make a dummy entry for that operator in the
+ system catalog. This dummy entry will have valid data only
+ for the operator name, left and right operand types, and result type,
+ since that's all that <span class="productname">PostgreSQL</span> can deduce
+ at this point. The first operator's catalog entry will link to this
+ dummy entry. Later, when you define the second operator, the system
+ updates the dummy entry with the additional information from the second
+ definition. If you try to use the dummy operator before it's been filled
+ in, you'll just get an error message.
+ </p></li></ul></div><p>
+ </p></div><div class="sect2" id="id-1.8.3.18.7"><div class="titlepage"><div><div><h3 class="title">38.15.2. <code class="literal">NEGATOR</code></h3></div></div></div><p>
+ The <code class="literal">NEGATOR</code> clause, if provided, names an operator that is the
+ negator of the operator being defined. We say that operator A
+ is the negator of operator B if both return Boolean results and
+ (x A y) equals NOT (x B y) for all possible inputs x, y.
+ Notice that B is also the negator of A.
+ For example, <code class="literal">&lt;</code> and <code class="literal">&gt;=</code> are a negator pair for most data types.
+ An operator can never validly be its own negator.
+ </p><p>
+ Unlike commutators, a pair of unary operators could validly be marked
+ as each other's negators; that would mean (A x) equals NOT (B x)
+ for all x.
+ </p><p>
+ An operator's negator must have the same left and/or right operand types
+ as the operator to be defined, so just as with <code class="literal">COMMUTATOR</code>, only the operator
+ name need be given in the <code class="literal">NEGATOR</code> clause.
+ </p><p>
+ Providing a negator is very helpful to the query optimizer since
+ it allows expressions like <code class="literal">NOT (x = y)</code> to be simplified into
+ <code class="literal">x &lt;&gt; y</code>. This comes up more often than you might think, because
+ <code class="literal">NOT</code> operations can be inserted as a consequence of other rearrangements.
+ </p><p>
+ Pairs of negator operators can be defined using the same methods
+ explained above for commutator pairs.
+ </p></div><div class="sect2" id="id-1.8.3.18.8"><div class="titlepage"><div><div><h3 class="title">38.15.3. <code class="literal">RESTRICT</code></h3></div></div></div><p>
+ The <code class="literal">RESTRICT</code> clause, if provided, names a restriction selectivity
+ estimation function for the operator. (Note that this is a function
+ name, not an operator name.) <code class="literal">RESTRICT</code> clauses only make sense for
+ binary operators that return <code class="type">boolean</code>. The idea behind a restriction
+ selectivity estimator is to guess what fraction of the rows in a
+ table will satisfy a <code class="literal">WHERE</code>-clause condition of the form:
+</p><pre class="programlisting">
+column OP constant
+</pre><p>
+ for the current operator and a particular constant value.
+ This assists the optimizer by
+ giving it some idea of how many rows will be eliminated by <code class="literal">WHERE</code>
+ clauses that have this form. (What happens if the constant is on
+ the left, you might be wondering? Well, that's one of the things that
+ <code class="literal">COMMUTATOR</code> is for...)
+ </p><p>
+ Writing new restriction selectivity estimation functions is far beyond
+ the scope of this chapter, but fortunately you can usually just use
+ one of the system's standard estimators for many of your own operators.
+ These are the standard restriction estimators:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="function">eqsel</code> for <code class="literal">=</code></td></tr><tr><td><code class="function">neqsel</code> for <code class="literal">&lt;&gt;</code></td></tr><tr><td><code class="function">scalarltsel</code> for <code class="literal">&lt;</code></td></tr><tr><td><code class="function">scalarlesel</code> for <code class="literal">&lt;=</code></td></tr><tr><td><code class="function">scalargtsel</code> for <code class="literal">&gt;</code></td></tr><tr><td><code class="function">scalargesel</code> for <code class="literal">&gt;=</code></td></tr></table><p>
+ </p><p>
+ You can frequently get away with using either <code class="function">eqsel</code> or <code class="function">neqsel</code> for
+ operators that have very high or very low selectivity, even if they
+ aren't really equality or inequality. For example, the
+ approximate-equality geometric operators use <code class="function">eqsel</code> on the assumption that
+ they'll usually only match a small fraction of the entries in a table.
+ </p><p>
+ You can use <code class="function">scalarltsel</code>, <code class="function">scalarlesel</code>,
+ <code class="function">scalargtsel</code> and <code class="function">scalargesel</code> for comparisons on
+ data types that have some sensible means of being converted into numeric
+ scalars for range comparisons. If possible, add the data type to those
+ understood by the function <code class="function">convert_to_scalar()</code> in
+ <code class="filename">src/backend/utils/adt/selfuncs.c</code>.
+ (Eventually, this function should be replaced by per-data-type functions
+ identified through a column of the <code class="classname">pg_type</code> system catalog; but that hasn't happened
+ yet.) If you do not do this, things will still work, but the optimizer's
+ estimates won't be as good as they could be.
+ </p><p>
+ Another useful built-in selectivity estimation function
+ is <code class="function">matchingsel</code>, which will work for almost any
+ binary operator, if standard MCV and/or histogram statistics are
+ collected for the input data type(s). Its default estimate is set to
+ twice the default estimate used in <code class="function">eqsel</code>, making
+ it most suitable for comparison operators that are somewhat less
+ strict than equality. (Or you could call the
+ underlying <code class="function">generic_restriction_selectivity</code>
+ function, providing a different default estimate.)
+ </p><p>
+ There are additional selectivity estimation functions designed for geometric
+ operators in <code class="filename">src/backend/utils/adt/geo_selfuncs.c</code>: <code class="function">areasel</code>, <code class="function">positionsel</code>,
+ and <code class="function">contsel</code>. At this writing these are just stubs, but you might want
+ to use them (or even better, improve them) anyway.
+ </p></div><div class="sect2" id="id-1.8.3.18.9"><div class="titlepage"><div><div><h3 class="title">38.15.4. <code class="literal">JOIN</code></h3></div></div></div><p>
+ The <code class="literal">JOIN</code> clause, if provided, names a join selectivity
+ estimation function for the operator. (Note that this is a function
+ name, not an operator name.) <code class="literal">JOIN</code> clauses only make sense for
+ binary operators that return <code class="type">boolean</code>. The idea behind a join
+ selectivity estimator is to guess what fraction of the rows in a
+ pair of tables will satisfy a <code class="literal">WHERE</code>-clause condition of the form:
+</p><pre class="programlisting">
+table1.column1 OP table2.column2
+</pre><p>
+ for the current operator. As with the <code class="literal">RESTRICT</code> clause, this helps
+ the optimizer very substantially by letting it figure out which
+ of several possible join sequences is likely to take the least work.
+ </p><p>
+ As before, this chapter will make no attempt to explain how to write
+ a join selectivity estimator function, but will just suggest that
+ you use one of the standard estimators if one is applicable:
+ </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="function">eqjoinsel</code> for <code class="literal">=</code></td></tr><tr><td><code class="function">neqjoinsel</code> for <code class="literal">&lt;&gt;</code></td></tr><tr><td><code class="function">scalarltjoinsel</code> for <code class="literal">&lt;</code></td></tr><tr><td><code class="function">scalarlejoinsel</code> for <code class="literal">&lt;=</code></td></tr><tr><td><code class="function">scalargtjoinsel</code> for <code class="literal">&gt;</code></td></tr><tr><td><code class="function">scalargejoinsel</code> for <code class="literal">&gt;=</code></td></tr><tr><td><code class="function">matchingjoinsel</code> for generic matching operators</td></tr><tr><td><code class="function">areajoinsel</code> for 2D area-based comparisons</td></tr><tr><td><code class="function">positionjoinsel</code> for 2D position-based comparisons</td></tr><tr><td><code class="function">contjoinsel</code> for 2D containment-based comparisons</td></tr></table><p>
+ </p></div><div class="sect2" id="id-1.8.3.18.10"><div class="titlepage"><div><div><h3 class="title">38.15.5. <code class="literal">HASHES</code></h3></div></div></div><p>
+ The <code class="literal">HASHES</code> clause, if present, tells the system that
+ it is permissible to use the hash join method for a join based on this
+ operator. <code class="literal">HASHES</code> only makes sense for a binary operator that
+ returns <code class="literal">boolean</code>, and in practice the operator must represent
+ equality for some data type or pair of data types.
+ </p><p>
+ The assumption underlying hash join is that the join operator can
+ only return true for pairs of left and right values that hash to the
+ same hash code. If two values get put in different hash buckets, the
+ join will never compare them at all, implicitly assuming that the
+ result of the join operator must be false. So it never makes sense
+ to specify <code class="literal">HASHES</code> for operators that do not represent
+ some form of equality. In most cases it is only practical to support
+ hashing for operators that take the same data type on both sides.
+ However, sometimes it is possible to design compatible hash functions
+ for two or more data types; that is, functions that will generate the
+ same hash codes for <span class="quote">“<span class="quote">equal</span>”</span> values, even though the values
+ have different representations. For example, it's fairly simple
+ to arrange this property when hashing integers of different widths.
+ </p><p>
+ To be marked <code class="literal">HASHES</code>, the join operator must appear
+ in a hash index operator family. This is not enforced when you create
+ the operator, since of course the referencing operator family couldn't
+ exist yet. But attempts to use the operator in hash joins will fail
+ at run time if no such operator family exists. The system needs the
+ operator family to find the data-type-specific hash function(s) for the
+ operator's input data type(s). Of course, you must also create suitable
+ hash functions before you can create the operator family.
+ </p><p>
+ Care should be exercised when preparing a hash function, because there
+ are machine-dependent ways in which it might fail to do the right thing.
+ For example, if your data type is a structure in which there might be
+ uninteresting pad bits, you cannot simply pass the whole structure to
+ <code class="function">hash_any</code>. (Unless you write your other operators and
+ functions to ensure that the unused bits are always zero, which is the
+ recommended strategy.)
+ Another example is that on machines that meet the <acronym class="acronym">IEEE</acronym>
+ floating-point standard, negative zero and positive zero are different
+ values (different bit patterns) but they are defined to compare equal.
+ If a float value might contain negative zero then extra steps are needed
+ to ensure it generates the same hash value as positive zero.
+ </p><p>
+ A hash-joinable operator must have a commutator (itself if the two
+ operand data types are the same, or a related equality operator
+ if they are different) that appears in the same operator family.
+ If this is not the case, planner errors might occur when the operator
+ is used. Also, it is a good idea (but not strictly required) for
+ a hash operator family that supports multiple data types to provide
+ equality operators for every combination of the data types; this
+ allows better optimization.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The function underlying a hash-joinable operator must be marked
+ immutable or stable. If it is volatile, the system will never
+ attempt to use the operator for a hash join.
+ </p></div><div class="note"><h3 class="title">Note</h3><p>
+ If a hash-joinable operator has an underlying function that is marked
+ strict, the
+ function must also be complete: that is, it should return true or
+ false, never null, for any two nonnull inputs. If this rule is
+ not followed, hash-optimization of <code class="literal">IN</code> operations might
+ generate wrong results. (Specifically, <code class="literal">IN</code> might return
+ false where the correct answer according to the standard would be null;
+ or it might yield an error complaining that it wasn't prepared for a
+ null result.)
+ </p></div></div><div class="sect2" id="id-1.8.3.18.11"><div class="titlepage"><div><div><h3 class="title">38.15.6. <code class="literal">MERGES</code></h3></div></div></div><p>
+ The <code class="literal">MERGES</code> clause, if present, tells the system that
+ it is permissible to use the merge-join method for a join based on this
+ operator. <code class="literal">MERGES</code> only makes sense for a binary operator that
+ returns <code class="literal">boolean</code>, and in practice the operator must represent
+ equality for some data type or pair of data types.
+ </p><p>
+ Merge join is based on the idea of sorting the left- and right-hand tables
+ into order and then scanning them in parallel. So, both data types must
+ be capable of being fully ordered, and the join operator must be one
+ that can only succeed for pairs of values that fall at the
+ <span class="quote">“<span class="quote">same place</span>”</span>
+ in the sort order. In practice this means that the join operator must
+ behave like equality. But it is possible to merge-join two
+ distinct data types so long as they are logically compatible. For
+ example, the <code class="type">smallint</code>-versus-<code class="type">integer</code>
+ equality operator is merge-joinable.
+ We only need sorting operators that will bring both data types into a
+ logically compatible sequence.
+ </p><p>
+ To be marked <code class="literal">MERGES</code>, the join operator must appear
+ as an equality member of a <code class="literal">btree</code> index operator family.
+ This is not enforced when you create
+ the operator, since of course the referencing operator family couldn't
+ exist yet. But the operator will not actually be used for merge joins
+ unless a matching operator family can be found. The
+ <code class="literal">MERGES</code> flag thus acts as a hint to the planner that
+ it's worth looking for a matching operator family.
+ </p><p>
+ A merge-joinable operator must have a commutator (itself if the two
+ operand data types are the same, or a related equality operator
+ if they are different) that appears in the same operator family.
+ If this is not the case, planner errors might occur when the operator
+ is used. Also, it is a good idea (but not strictly required) for
+ a <code class="literal">btree</code> operator family that supports multiple data types to provide
+ equality operators for every combination of the data types; this
+ allows better optimization.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ The function underlying a merge-joinable operator must be marked
+ immutable or stable. If it is volatile, the system will never
+ attempt to use the operator for a merge join.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xoper.html" title="38.14. User-Defined Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.14. User-Defined Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.16. Interfacing Extensions to Indexes</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xoper.html b/doc/src/sgml/html/xoper.html
new file mode 100644
index 0000000..ebd0f83
--- /dev/null
+++ b/doc/src/sgml/html/xoper.html
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.14. User-Defined Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xtypes.html" title="38.13. User-Defined Types" /><link rel="next" href="xoper-optimization.html" title="38.15. Operator Optimization Information" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.14. User-Defined Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xtypes.html" title="38.13. User-Defined Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xoper-optimization.html" title="38.15. Operator Optimization Information">Next</a></td></tr></table><hr /></div><div class="sect1" id="XOPER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.14. User-Defined Operators</h2></div></div></div><a id="id-1.8.3.17.2" class="indexterm"></a><p>
+ Every operator is <span class="quote">“<span class="quote">syntactic sugar</span>”</span> for a call to an
+ underlying function that does the real work; so you must
+ first create the underlying function before you can create
+ the operator. However, an operator is <span class="emphasis"><em>not merely</em></span>
+ syntactic sugar, because it carries additional information
+ that helps the query planner optimize queries that use the
+ operator. The next section will be devoted to explaining
+ that additional information.
+ </p><p>
+ <span class="productname">PostgreSQL</span> supports prefix
+ and infix operators. Operators can be
+ overloaded;<a id="id-1.8.3.17.4.2" class="indexterm"></a>
+ that is, the same operator name can be used for different operators
+ that have different numbers and types of operands. When a query is
+ executed, the system determines the operator to call from the
+ number and types of the provided operands.
+ </p><p>
+ Here is an example of creating an operator for adding two complex
+ numbers. We assume we've already created the definition of type
+ <code class="type">complex</code> (see <a class="xref" href="xtypes.html" title="38.13. User-Defined Types">Section 38.13</a>). First we need a
+ function that does the work, then we can define the operator:
+
+</p><pre class="programlisting">
+CREATE FUNCTION complex_add(complex, complex)
+ RETURNS complex
+ AS '<em class="replaceable"><code>filename</code></em>', 'complex_add'
+ LANGUAGE C IMMUTABLE STRICT;
+
+CREATE OPERATOR + (
+ leftarg = complex,
+ rightarg = complex,
+ function = complex_add,
+ commutator = +
+);
+</pre><p>
+ </p><p>
+ Now we could execute a query like this:
+
+</p><pre class="screen">
+SELECT (a + b) AS c FROM test_complex;
+
+ c
+-----------------
+ (5.2,6.05)
+ (133.42,144.95)
+</pre><p>
+ </p><p>
+ We've shown how to create a binary operator here. To create a prefix
+ operator, just omit the <code class="literal">leftarg</code>.
+ The <code class="literal">function</code>
+ clause and the argument clauses are the only required items in
+ <code class="command">CREATE OPERATOR</code>. The <code class="literal">commutator</code>
+ clause shown in the example is an optional hint to the query
+ optimizer. Further details about <code class="literal">commutator</code> and other
+ optimizer hints appear in the next section.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xtypes.html" title="38.13. User-Defined Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xoper-optimization.html" title="38.15. Operator Optimization Information">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.13. User-Defined Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.15. Operator Optimization Information</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xplang-install.html b/doc/src/sgml/html/xplang-install.html
new file mode 100644
index 0000000..b1ec495
--- /dev/null
+++ b/doc/src/sgml/html/xplang-install.html
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>42.1. Installing Procedural Languages</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xplang.html" title="Chapter 42. Procedural Languages" /><link rel="next" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">42.1. Installing Procedural Languages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xplang.html" title="Chapter 42. Procedural Languages">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="xplang.html" title="Chapter 42. Procedural Languages">Up</a></td><th width="60%" align="center">Chapter 42. Procedural Languages</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="XPLANG-INSTALL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">42.1. Installing Procedural Languages</h2></div></div></div><p>
+ A procedural language must be <span class="quote">“<span class="quote">installed</span>”</span> into each
+ database where it is to be used. But procedural languages installed in
+ the database <code class="literal">template1</code> are automatically available in all
+ subsequently created databases, since their entries in
+ <code class="literal">template1</code> will be copied by <code class="command">CREATE DATABASE</code>.
+ So the database administrator can
+ decide which languages are available in which databases and can make
+ some languages available by default if desired.
+ </p><p>
+ For the languages supplied with the standard distribution, it is
+ only necessary to execute <code class="command">CREATE EXTENSION</code>
+ <em class="replaceable"><code>language_name</code></em> to install the language into the
+ current database.
+ The manual procedure described below is only recommended for
+ installing languages that have not been packaged as extensions.
+ </p><div class="procedure" id="id-1.8.7.5.4"><p class="title"><strong>Manual Procedural Language Installation</strong></p><p>
+ A procedural language is installed in a database in five steps,
+ which must be carried out by a database superuser. In most cases
+ the required SQL commands should be packaged as the installation script
+ of an <span class="quote">“<span class="quote">extension</span>”</span>, so that <code class="command">CREATE EXTENSION</code> can be
+ used to execute them.
+ </p><ol class="procedure" type="1"><li class="step" id="XPLANG-INSTALL-CR1"><p>
+ The shared object for the language handler must be compiled and
+ installed into an appropriate library directory. This works in the same
+ way as building and installing modules with regular user-defined C
+ functions does; see <a class="xref" href="xfunc-c.html#DFUNC" title="38.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 38.10.5</a>. Often, the language
+ handler will depend on an external library that provides the actual
+ programming language engine; if so, that must be installed as well.
+ </p></li><li class="step" id="XPLANG-INSTALL-CR2"><p>
+ The handler must be declared with the command
+</p><pre class="synopsis">
+CREATE FUNCTION <em class="replaceable"><code>handler_function_name</code></em>()
+ RETURNS language_handler
+ AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
+ LANGUAGE C;
+</pre><p>
+ The special return type of <code class="type">language_handler</code> tells
+ the database system that this function does not return one of
+ the defined <acronym class="acronym">SQL</acronym> data types and is not directly usable
+ in <acronym class="acronym">SQL</acronym> statements.
+ </p></li><li class="step" id="XPLANG-INSTALL-CR3"><p>
+ Optionally, the language handler can provide an <span class="quote">“<span class="quote">inline</span>”</span>
+ handler function that executes anonymous code blocks
+ (<a class="link" href="sql-do.html" title="DO"><code class="command">DO</code></a> commands)
+ written in this language. If an inline handler function
+ is provided by the language, declare it with a command like
+</p><pre class="synopsis">
+CREATE FUNCTION <em class="replaceable"><code>inline_function_name</code></em>(internal)
+ RETURNS void
+ AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
+ LANGUAGE C;
+</pre><p>
+ </p></li><li class="step" id="XPLANG-INSTALL-CR4"><p>
+ Optionally, the language handler can provide a <span class="quote">“<span class="quote">validator</span>”</span>
+ function that checks a function definition for correctness without
+ actually executing it. The validator function is called by
+ <code class="command">CREATE FUNCTION</code> if it exists. If a validator function
+ is provided by the language, declare it with a command like
+</p><pre class="synopsis">
+CREATE FUNCTION <em class="replaceable"><code>validator_function_name</code></em>(oid)
+ RETURNS void
+ AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
+ LANGUAGE C STRICT;
+</pre><p>
+ </p></li><li class="step" id="XPLANG-INSTALL-CR5"><p>
+ Finally, the PL must be declared with the command
+</p><pre class="synopsis">
+CREATE [<span class="optional">TRUSTED</span>] LANGUAGE <em class="replaceable"><code>language_name</code></em>
+ HANDLER <em class="replaceable"><code>handler_function_name</code></em>
+ [<span class="optional">INLINE <em class="replaceable"><code>inline_function_name</code></em></span>]
+ [<span class="optional">VALIDATOR <em class="replaceable"><code>validator_function_name</code></em></span>] ;
+</pre><p>
+ The optional key word <code class="literal">TRUSTED</code> specifies that
+ the language does not grant access to data that the user would
+ not otherwise have. Trusted languages are designed for ordinary
+ database users (those without superuser privilege) and allows them
+ to safely create functions and
+ procedures. Since PL functions are executed inside the database
+ server, the <code class="literal">TRUSTED</code> flag should only be given
+ for languages that do not allow access to database server
+ internals or the file system. The languages
+ <span class="application">PL/pgSQL</span>,
+ <span class="application">PL/Tcl</span>, and
+ <span class="application">PL/Perl</span>
+ are considered trusted; the languages
+ <span class="application">PL/TclU</span>,
+ <span class="application">PL/PerlU</span>, and
+ <span class="application">PL/PythonU</span>
+ are designed to provide unlimited functionality and should
+ <span class="emphasis"><em>not</em></span> be marked trusted.
+ </p></li></ol></div><p>
+ <a class="xref" href="xplang-install.html#XPLANG-INSTALL-EXAMPLE" title="Example 42.1. Manual Installation of PL/Perl">Example 42.1</a> shows how the manual
+ installation procedure would work with the language
+ <span class="application">PL/Perl</span>.
+ </p><div class="example" id="XPLANG-INSTALL-EXAMPLE"><p class="title"><strong>Example 42.1. Manual Installation of <span class="application">PL/Perl</span></strong></p><div class="example-contents"><p>
+ The following command tells the database server where to find the
+ shared object for the <span class="application">PL/Perl</span> language's call
+ handler function:
+
+</p><pre class="programlisting">
+CREATE FUNCTION plperl_call_handler() RETURNS language_handler AS
+ '$libdir/plperl' LANGUAGE C;
+</pre><p>
+ </p><p>
+ <span class="application">PL/Perl</span> has an inline handler function
+ and a validator function, so we declare those too:
+
+</p><pre class="programlisting">
+CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
+ '$libdir/plperl' LANGUAGE C STRICT;
+
+CREATE FUNCTION plperl_validator(oid) RETURNS void AS
+ '$libdir/plperl' LANGUAGE C STRICT;
+</pre><p>
+ </p><p>
+ The command:
+</p><pre class="programlisting">
+CREATE TRUSTED LANGUAGE plperl
+ HANDLER plperl_call_handler
+ INLINE plperl_inline_handler
+ VALIDATOR plperl_validator;
+</pre><p>
+ then defines that the previously declared functions
+ should be invoked for functions and procedures where the
+ language attribute is <code class="literal">plperl</code>.
+ </p></div></div><br class="example-break" /><p>
+ In a default <span class="productname">PostgreSQL</span> installation,
+ the handler for the <span class="application">PL/pgSQL</span> language
+ is built and installed into the <span class="quote">“<span class="quote">library</span>”</span>
+ directory; furthermore, the <span class="application">PL/pgSQL</span> language
+ itself is installed in all databases.
+ If <span class="application">Tcl</span> support is configured in, the handlers for
+ <span class="application">PL/Tcl</span> and <span class="application">PL/TclU</span> are built and installed
+ in the library directory, but the language itself is not installed in any
+ database by default.
+ Likewise, the <span class="application">PL/Perl</span> and <span class="application">PL/PerlU</span>
+ handlers are built and installed if Perl support is configured, and the
+ <span class="application">PL/PythonU</span> handler is installed if Python support is
+ configured, but these languages are not installed by default.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xplang.html" title="Chapter 42. Procedural Languages">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="xplang.html" title="Chapter 42. Procedural Languages">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 42. Procedural Languages </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 43. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xplang.html b/doc/src/sgml/html/xplang.html
new file mode 100644
index 0000000..0a90173
--- /dev/null
+++ b/doc/src/sgml/html/xplang.html
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 42. Procedural Languages</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="rules-triggers.html" title="41.7. Rules Versus Triggers" /><link rel="next" href="xplang-install.html" title="42.1. Installing Procedural Languages" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 42. Procedural Languages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="rules-triggers.html" title="41.7. Rules Versus Triggers">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xplang-install.html" title="42.1. Installing Procedural Languages">Next</a></td></tr></table><hr /></div><div class="chapter" id="XPLANG"><div class="titlepage"><div><div><h2 class="title">Chapter 42. Procedural Languages</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="xplang-install.html">42.1. Installing Procedural Languages</a></span></dt></dl></div><a id="id-1.8.7.2" class="indexterm"></a><p>
+ <span class="productname">PostgreSQL</span> allows user-defined functions
+ to be written in other languages besides SQL and C. These other
+ languages are generically called <em class="firstterm">procedural
+ languages</em> (<acronym class="acronym">PL</acronym>s). For a function
+ written in a procedural language, the database server has
+ no built-in knowledge about how to interpret the function's source
+ text. Instead, the task is passed to a special handler that knows
+ the details of the language. The handler could either do all the
+ work of parsing, syntax analysis, execution, etc. itself, or it
+ could serve as <span class="quote">“<span class="quote">glue</span>”</span> between
+ <span class="productname">PostgreSQL</span> and an existing implementation
+ of a programming language. The handler itself is a
+ C language function compiled into a shared object and
+ loaded on demand, just like any other C function.
+ </p><p>
+ There are currently four procedural languages available in the
+ standard <span class="productname">PostgreSQL</span> distribution:
+ <span class="application">PL/pgSQL</span> (<a class="xref" href="plpgsql.html" title="Chapter 43. PL/pgSQL — SQL Procedural Language">Chapter 43</a>),
+ <span class="application">PL/Tcl</span> (<a class="xref" href="pltcl.html" title="Chapter 44. PL/Tcl — Tcl Procedural Language">Chapter 44</a>),
+ <span class="application">PL/Perl</span> (<a class="xref" href="plperl.html" title="Chapter 45. PL/Perl — Perl Procedural Language">Chapter 45</a>), and
+ <span class="application">PL/Python</span> (<a class="xref" href="plpython.html" title="Chapter 46. PL/Python — Python Procedural Language">Chapter 46</a>).
+ There are additional procedural languages available that are not
+ included in the core distribution. <a class="xref" href="external-projects.html" title="Appendix H. External Projects">Appendix H</a>
+ has information about finding them. In addition other languages can
+ be defined by users; the basics of developing a new procedural
+ language are covered in <a class="xref" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Chapter 58</a>.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rules-triggers.html" title="41.7. Rules Versus Triggers">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xplang-install.html" title="42.1. Installing Procedural Languages">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.7. Rules Versus Triggers </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 42.1. Installing Procedural Languages</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xproc.html b/doc/src/sgml/html/xproc.html
new file mode 100644
index 0000000..1ec83a5
--- /dev/null
+++ b/doc/src/sgml/html/xproc.html
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.4. User-Defined Procedures</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc.html" title="38.3. User-Defined Functions" /><link rel="next" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.4. User-Defined Procedures</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc.html" title="38.3. User-Defined Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="XPROC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.4. User-Defined Procedures</h2></div></div></div><a id="id-1.8.3.7.2" class="indexterm"></a><p>
+ A procedure is a database object similar to a function.
+ The key differences are:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ Procedures are defined with
+ the <a class="link" href="sql-createprocedure.html" title="CREATE PROCEDURE"><code class="command">CREATE
+ PROCEDURE</code></a> command, not <code class="command">CREATE
+ FUNCTION</code>.
+ </p></li><li class="listitem"><p>
+ Procedures do not return a function value; hence <code class="command">CREATE
+ PROCEDURE</code> lacks a <code class="literal">RETURNS</code> clause.
+ However, procedures can instead return data to their callers via
+ output parameters.
+ </p></li><li class="listitem"><p>
+ While a function is called as part of a query or DML command, a
+ procedure is called in isolation using
+ the <a class="link" href="sql-call.html" title="CALL"><code class="command">CALL</code></a> command.
+ </p></li><li class="listitem"><p>
+ A procedure can commit or roll back transactions during its
+ execution (then automatically beginning a new transaction), so long
+ as the invoking <code class="command">CALL</code> command is not part of an
+ explicit transaction block. A function cannot do that.
+ </p></li><li class="listitem"><p>
+ Certain function attributes, such as strictness, don't apply to
+ procedures. Those attributes control how the function is
+ used in a query, which isn't relevant to procedures.
+ </p></li></ul></div><p>
+ </p><p>
+ The explanations in the following sections about how to define
+ user-defined functions apply to procedures as well, except for the
+ points made above.
+ </p><p>
+ Collectively, functions and procedures are also known
+ as <em class="firstterm">routines</em><a id="id-1.8.3.7.5.2" class="indexterm"></a>.
+ There are commands such as <a class="link" href="sql-alterroutine.html" title="ALTER ROUTINE"><code class="command">ALTER ROUTINE</code></a>
+ and <a class="link" href="sql-droproutine.html" title="DROP ROUTINE"><code class="command">DROP ROUTINE</code></a> that can operate on functions and
+ procedures without having to know which kind it is. Note, however, that
+ there is no <code class="literal">CREATE ROUTINE</code> command.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc.html" title="38.3. User-Defined Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.3. User-Defined Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.5. Query Language (<acronym class="acronym">SQL</acronym>) Functions</td></tr></table></div></body></html> \ No newline at end of file
diff --git a/doc/src/sgml/html/xtypes.html b/doc/src/sgml/html/xtypes.html
new file mode 100644
index 0000000..c370c6f
--- /dev/null
+++ b/doc/src/sgml/html/xtypes.html
@@ -0,0 +1,302 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.13. User-Defined Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xaggr.html" title="38.12. User-Defined Aggregates" /><link rel="next" href="xoper.html" title="38.14. User-Defined Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.13. User-Defined Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xaggr.html" title="38.12. User-Defined Aggregates">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xoper.html" title="38.14. User-Defined Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="XTYPES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.13. User-Defined Types</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xtypes.html#XTYPES-TOAST">38.13.1. TOAST Considerations</a></span></dt></dl></div><a id="id-1.8.3.16.2" class="indexterm"></a><p>
+ As described in <a class="xref" href="extend-type-system.html" title="38.2. The PostgreSQL Type System">Section 38.2</a>,
+ <span class="productname">PostgreSQL</span> can be extended to support new
+ data types. This section describes how to define new base types,
+ which are data types defined below the level of the <acronym class="acronym">SQL</acronym>
+ language. Creating a new base type requires implementing functions
+ to operate on the type in a low-level language, usually C.
+ </p><p>
+ The examples in this section can be found in
+ <code class="filename">complex.sql</code> and <code class="filename">complex.c</code>
+ in the <code class="filename">src/tutorial</code> directory of the source distribution.
+ See the <code class="filename">README</code> file in that directory for instructions
+ about running the examples.
+ </p><p>
+ <a id="id-1.8.3.16.5.1" class="indexterm"></a>
+ <a id="id-1.8.3.16.5.2" class="indexterm"></a>
+ A user-defined type must always have input and output functions.
+ These functions determine how the type appears in strings (for input
+ by the user and output to the user) and how the type is organized in
+ memory. The input function takes a null-terminated character string
+ as its argument and returns the internal (in memory) representation
+ of the type. The output function takes the internal representation
+ of the type as argument and returns a null-terminated character
+ string. If we want to do anything more with the type than merely
+ store it, we must provide additional functions to implement whatever
+ operations we'd like to have for the type.
+ </p><p>
+ Suppose we want to define a type <code class="type">complex</code> that represents
+ complex numbers. A natural way to represent a complex number in
+ memory would be the following C structure:
+
+</p><pre class="programlisting">
+typedef struct Complex {
+ double x;
+ double y;
+} Complex;
+</pre><p>
+
+ We will need to make this a pass-by-reference type, since it's too
+ large to fit into a single <code class="type">Datum</code> value.
+ </p><p>
+ As the external string representation of the type, we choose a
+ string of the form <code class="literal">(x,y)</code>.
+ </p><p>
+ The input and output functions are usually not hard to write,
+ especially the output function. But when defining the external
+ string representation of the type, remember that you must eventually
+ write a complete and robust parser for that representation as your
+ input function. For instance:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(complex_in);
+
+Datum
+complex_in(PG_FUNCTION_ARGS)
+{
+ char *str = PG_GETARG_CSTRING(0);
+ double x,
+ y;
+ Complex *result;
+
+ if (sscanf(str, " ( %lf , %lf )", &amp;x, &amp;y) != 2)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
+ errmsg("invalid input syntax for type %s: \"%s\"",
+ "complex", str)));
+
+ result = (Complex *) palloc(sizeof(Complex));
+ result-&gt;x = x;
+ result-&gt;y = y;
+ PG_RETURN_POINTER(result);
+}
+
+</pre><p>
+
+ The output function can simply be:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(complex_out);
+
+Datum
+complex_out(PG_FUNCTION_ARGS)
+{
+ Complex *complex = (Complex *) PG_GETARG_POINTER(0);
+ char *result;
+
+ result = psprintf("(%g,%g)", complex-&gt;x, complex-&gt;y);
+ PG_RETURN_CSTRING(result);
+}
+
+</pre><p>
+ </p><p>
+ You should be careful to make the input and output functions inverses of
+ each other. If you do not, you will have severe problems when you
+ need to dump your data into a file and then read it back in. This
+ is a particularly common problem when floating-point numbers are
+ involved.
+ </p><p>
+ Optionally, a user-defined type can provide binary input and output
+ routines. Binary I/O is normally faster but less portable than textual
+ I/O. As with textual I/O, it is up to you to define exactly what the
+ external binary representation is. Most of the built-in data types
+ try to provide a machine-independent binary representation. For
+ <code class="type">complex</code>, we will piggy-back on the binary I/O converters
+ for type <code class="type">float8</code>:
+
+</p><pre class="programlisting">
+PG_FUNCTION_INFO_V1(complex_recv);
+
+Datum
+complex_recv(PG_FUNCTION_ARGS)
+{
+ StringInfo buf = (StringInfo) PG_GETARG_POINTER(0);
+ Complex *result;
+
+ result = (Complex *) palloc(sizeof(Complex));
+ result-&gt;x = pq_getmsgfloat8(buf);
+ result-&gt;y = pq_getmsgfloat8(buf);
+ PG_RETURN_POINTER(result);
+}
+
+PG_FUNCTION_INFO_V1(complex_send);
+
+Datum
+complex_send(PG_FUNCTION_ARGS)
+{
+ Complex *complex = (Complex *) PG_GETARG_POINTER(0);
+ StringInfoData buf;
+
+ pq_begintypsend(&amp;buf);
+ pq_sendfloat8(&amp;buf, complex-&gt;x);
+ pq_sendfloat8(&amp;buf, complex-&gt;y);
+ PG_RETURN_BYTEA_P(pq_endtypsend(&amp;buf));
+}
+
+</pre><p>
+ </p><p>
+ Once we have written the I/O functions and compiled them into a shared
+ library, we can define the <code class="type">complex</code> type in SQL.
+ First we declare it as a shell type:
+
+</p><pre class="programlisting">
+CREATE TYPE complex;
+</pre><p>
+
+ This serves as a placeholder that allows us to reference the type while
+ defining its I/O functions. Now we can define the I/O functions:
+
+</p><pre class="programlisting">
+CREATE FUNCTION complex_in(cstring)
+ RETURNS complex
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C IMMUTABLE STRICT;
+
+CREATE FUNCTION complex_out(complex)
+ RETURNS cstring
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C IMMUTABLE STRICT;
+
+CREATE FUNCTION complex_recv(internal)
+ RETURNS complex
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C IMMUTABLE STRICT;
+
+CREATE FUNCTION complex_send(complex)
+ RETURNS bytea
+ AS '<em class="replaceable"><code>filename</code></em>'
+ LANGUAGE C IMMUTABLE STRICT;
+</pre><p>
+ </p><p>
+ Finally, we can provide the full definition of the data type:
+</p><pre class="programlisting">
+CREATE TYPE complex (
+ internallength = 16,
+ input = complex_in,
+ output = complex_out,
+ receive = complex_recv,
+ send = complex_send,
+ alignment = double
+);
+</pre><p>
+ </p><p>
+ <a id="id-1.8.3.16.13.1" class="indexterm"></a>
+ When you define a new base type,
+ <span class="productname">PostgreSQL</span> automatically provides support
+ for arrays of that type. The array type typically
+ has the same name as the base type with the underscore character
+ (<code class="literal">_</code>) prepended.
+ </p><p>
+ Once the data type exists, we can declare additional functions to
+ provide useful operations on the data type. Operators can then be
+ defined atop the functions, and if needed, operator classes can be
+ created to support indexing of the data type. These additional
+ layers are discussed in following sections.
+ </p><p>
+ If the internal representation of the data type is variable-length, the
+ internal representation must follow the standard layout for variable-length
+ data: the first four bytes must be a <code class="type">char[4]</code> field which is
+ never accessed directly (customarily named <code class="structfield">vl_len_</code>). You
+ must use the <code class="function">SET_VARSIZE()</code> macro to store the total
+ size of the datum (including the length field itself) in this field
+ and <code class="function">VARSIZE()</code> to retrieve it. (These macros exist
+ because the length field may be encoded depending on platform.)
+ </p><p>
+ For further details see the description of the
+ <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> command.
+ </p><div class="sect2" id="XTYPES-TOAST"><div class="titlepage"><div><div><h3 class="title">38.13.1. TOAST Considerations</h3></div></div></div><a id="id-1.8.3.16.17.2" class="indexterm"></a><p>
+ If the values of your data type vary in size (in internal form), it's
+ usually desirable to make the data type <acronym class="acronym">TOAST</acronym>-able (see <a class="xref" href="storage-toast.html" title="73.2. TOAST">Section 73.2</a>). You should do this even if the values are always
+ too small to be compressed or stored externally, because
+ <acronym class="acronym">TOAST</acronym> can save space on small data too, by reducing header
+ overhead.
+ </p><p>
+ To support <acronym class="acronym">TOAST</acronym> storage, the C functions operating on the data
+ type must always be careful to unpack any toasted values they are handed
+ by using <code class="function">PG_DETOAST_DATUM</code>. (This detail is customarily hidden
+ by defining type-specific <code class="function">GETARG_DATATYPE_P</code> macros.)
+ Then, when running the <code class="command">CREATE TYPE</code> command, specify the
+ internal length as <code class="literal">variable</code> and select some appropriate storage
+ option other than <code class="literal">plain</code>.
+ </p><p>
+ If data alignment is unimportant (either just for a specific function or
+ because the data type specifies byte alignment anyway) then it's possible
+ to avoid some of the overhead of <code class="function">PG_DETOAST_DATUM</code>. You can use
+ <code class="function">PG_DETOAST_DATUM_PACKED</code> instead (customarily hidden by
+ defining a <code class="function">GETARG_DATATYPE_PP</code> macro) and using the macros
+ <code class="function">VARSIZE_ANY_EXHDR</code> and <code class="function">VARDATA_ANY</code> to access
+ a potentially-packed datum.
+ Again, the data returned by these macros is not aligned even if the data
+ type definition specifies an alignment. If the alignment is important you
+ must go through the regular <code class="function">PG_DETOAST_DATUM</code> interface.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ Older code frequently declares <code class="structfield">vl_len_</code> as an
+ <code class="type">int32</code> field instead of <code class="type">char[4]</code>. This is OK as long as
+ the struct definition has other fields that have at least <code class="type">int32</code>
+ alignment. But it is dangerous to use such a struct definition when
+ working with a potentially unaligned datum; the compiler may take it as
+ license to assume the datum actually is aligned, leading to core dumps on
+ architectures that are strict about alignment.
+ </p></div><p>
+ Another feature that's enabled by <acronym class="acronym">TOAST</acronym> support is the
+ possibility of having an <em class="firstterm">expanded</em> in-memory data
+ representation that is more convenient to work with than the format that
+ is stored on disk. The regular or <span class="quote">“<span class="quote">flat</span>”</span> varlena storage format
+ is ultimately just a blob of bytes; it cannot for example contain
+ pointers, since it may get copied to other locations in memory.
+ For complex data types, the flat format may be quite expensive to work
+ with, so <span class="productname">PostgreSQL</span> provides a way to <span class="quote">“<span class="quote">expand</span>”</span>
+ the flat format into a representation that is more suited to computation,
+ and then pass that format in-memory between functions of the data type.
+ </p><p>
+ To use expanded storage, a data type must define an expanded format that
+ follows the rules given in <code class="filename">src/include/utils/expandeddatum.h</code>,
+ and provide functions to <span class="quote">“<span class="quote">expand</span>”</span> a flat varlena value into
+ expanded format and <span class="quote">“<span class="quote">flatten</span>”</span> the expanded format back to the
+ regular varlena representation. Then ensure that all C functions for
+ the data type can accept either representation, possibly by converting
+ one into the other immediately upon receipt. This does not require fixing
+ all existing functions for the data type at once, because the standard
+ <code class="function">PG_DETOAST_DATUM</code> macro is defined to convert expanded inputs
+ into regular flat format. Therefore, existing functions that work with
+ the flat varlena format will continue to work, though slightly
+ inefficiently, with expanded inputs; they need not be converted until and
+ unless better performance is important.
+ </p><p>
+ C functions that know how to work with an expanded representation
+ typically fall into two categories: those that can only handle expanded
+ format, and those that can handle either expanded or flat varlena inputs.
+ The former are easier to write but may be less efficient overall, because
+ converting a flat input to expanded form for use by a single function may
+ cost more than is saved by operating on the expanded format.
+ When only expanded format need be handled, conversion of flat inputs to
+ expanded form can be hidden inside an argument-fetching macro, so that
+ the function appears no more complex than one working with traditional
+ varlena input.
+ To handle both types of input, write an argument-fetching function that
+ will detoast external, short-header, and compressed varlena inputs, but
+ not expanded inputs. Such a function can be defined as returning a
+ pointer to a union of the flat varlena format and the expanded format.
+ Callers can use the <code class="function">VARATT_IS_EXPANDED_HEADER()</code> macro to
+ determine which format they received.
+ </p><p>
+ The <acronym class="acronym">TOAST</acronym> infrastructure not only allows regular varlena
+ values to be distinguished from expanded values, but also
+ distinguishes <span class="quote">“<span class="quote">read-write</span>”</span> and <span class="quote">“<span class="quote">read-only</span>”</span> pointers to
+ expanded values. C functions that only need to examine an expanded
+ value, or will only change it in safe and non-semantically-visible ways,
+ need not care which type of pointer they receive. C functions that
+ produce a modified version of an input value are allowed to modify an
+ expanded input value in-place if they receive a read-write pointer, but
+ must not modify the input if they receive a read-only pointer; in that
+ case they have to copy the value first, producing a new value to modify.
+ A C function that has constructed a new expanded value should always
+ return a read-write pointer to it. Also, a C function that is modifying
+ a read-write expanded value in-place should take care to leave the value
+ in a sane state if it fails partway through.
+ </p><p>
+ For examples of working with expanded values, see the standard array
+ infrastructure, particularly
+ <code class="filename">src/backend/utils/adt/array_expanded.c</code>.
+ </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xaggr.html" title="38.12. User-Defined Aggregates">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xoper.html" title="38.14. User-Defined Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.12. User-Defined Aggregates </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.14. User-Defined Operators</td></tr></table></div></body></html> \ No newline at end of file
generated by cgit v1.2.3 (git 2.39.1) at 2024-08-06 17:47:04 +0000